ADR-106: Audit Entity IDs for Config Levels

Status: Accepted Date: 2026-01-19 Issue: #130

Context

The audit logging system requires an entity_id for all audit events. This works naturally for entity-level operations where the entity_id is the actual entity being modified.

However, system-level and resource-level config changes (introduced in #130) have no natural entity. System config applies globally, and resource config applies to a resource name rather than a specific entity.

Additionally, operators need to query audit trails for config changes separately from entity changes. Mixing config audits with entity audits under arbitrary entity IDs would make compliance queries difficult.

Decision

Use special prefixes for config-level audit entity IDs: - System config: $SYSTEM - Resource config: $RESOURCE:{resource_name} (e.g., $RESOURCE:gpt-4)

The $ prefix is chosen because it cannot appear in valid entity IDs (which must start with alphanumeric characters per validation rules).

Consequences

Positive: - Clear distinction between entity and config audit events - Operators can query all system config changes via entity_id=$SYSTEM - Resource config audits are grouped by resource name - No collision risk with real entity IDs

Negative: - Introduces a reserved character convention that must be documented - Audit queries for "all changes" must now include both entity and $-prefixed patterns

Alternatives Considered

Use literal strings without prefix (e.g., "SYSTEM")

Rejected: Could collide with actual entity IDs if a user creates an entity named "SYSTEM".

Skip audit logging for config changes

Rejected: Config changes are security-sensitive operations that require audit trails for compliance.