Entity: auditLog

Description: An immutable, append-only record of a change to EM3's data. One row is written each time a tracked entity is created, updated, or deleted (or a domain-specific event occurs).

Entity Type: database table

Naming note: the real table is audit_log (columns entity_type, tenant_id, …) — plain, unquoted, singular snake_case, the same convention every em3 table follows. The Attribute Name column above documents the domain/camelCase form (entityType, tenantId, …); that duality is the project-wide documentation convention, not something specific to this entity — see the overlay's naming-convention entry. (An earlier draft of this page modeled the table as a quoted-camelCase exception; that plan was not carried into the migration.)

Data Attributes Table

Attribute Name	Description	Data Type	Default Value	Required (= Nullable)	Unique	Format	Validations	Index	Example
id	Primary key.	UUID	-	Yes	Yes	-	Generated as UUID v7 at the application layer — never a DB default, never auto-increment.	Primary Key	550e8400-e29b-41d4-a716-446655440001
tenantId	Tenant that owns this entry. RLS predicate; set by the storage layer from request context.	UUID	-	Yes	No	-	-	-	550e8400-e29b-41d4-a716-446655440002
entityType	Type of the entity that changed — the name of the row, derived from the data model. Never a screen, feature, or navigation label.	string	-	Yes	No	-	Must match an entityType present in the Entity catalog. No foreign key: entries outlive deleted records, and a new entity type needs no change to this schema.	name: idx_auditLog_tenantId_entityType, type: btree	building
entityId	ID of the entity that changed.	UUID	-	Yes	No	-	No foreign key — the referenced record may since have been deleted.	name: idx_auditLog_tenantId_entityId, type: btree	550e8400-e29b-41d4-a716-446655440003
subjectEntityType	Type of the record these entries are filed about, when that differs from entityType — e.g. a membership row filed against the group but about the member. Also set by a type declared to name itself as its own subject, so its full history is one indexed read. null where the entry declares no subject at all.	string	-	No	No	-	Must match an entityType present in the Entity catalog when populated. No foreign key, same as entityType.	name: idx_auditLog_tenantId_subjectEntityType_subjectEntityId, type: btree (partial: WHERE subjectEntityType IS NOT NULL)	person
subjectEntityId	ID of the subject record. Requires subjectEntityType to be set; null together with it.	UUID	-	No	No	-	Requires subjectEntityType. No foreign key — the referenced record may since have been deleted.	(composite with subjectEntityType above)	550e8400-e29b-41d4-a716-446655440099
event	What happened to the entity.	string	-	Yes	No	enum — see Enum - AuditLogEvent	Must be a value in the AuditLogEvent vocabulary.	-	updated
logMetadata	Structured description of the change.	JSONB	-	No	No	See JSON-DAT: auditLog.logMetadata	Never contains secrets, credentials, or raw unencrypted personal data. null if there is no context beyond the event itself.	-	see JSON-DAT
actionId	Identifier tying together every entry written under one decision (one HTTP request, one job). Derived from the backend's existing requestId infrastructure (X-Request-Id header).	UUID	-	No	No	-	Null only for entries recorded outside request context (e.g. a job with no inbound request).	name: idx_auditLog_tenantId_actionId, type: btree (partial: WHERE actionId IS NOT NULL)	550e8400-e29b-41d4-a716-446655440004
createdAt	When the audited change happened (UTC).	timestamp with time zone	-	Yes	No	ISO 8601 UTC	Immutable after write.	name: idx_auditLog_tenantId_createdAt, type: btree — primary index; supports the investigation surface's newest-first read.	2026-09-11T14:00:00Z
updatedAt	Always equal to createdAt — the row is never modified after insert.	timestamp with time zone	-	Yes	No	ISO 8601 UTC	Must equal createdAt.	-	2026-09-11T14:00:00Z
deletedAt	Soft-delete marker; this row is never soft-deleted.	timestamp with time zone	-	No	No	ISO 8601 UTC	Always null; no current code path sets it.	-	null
createdBy	Who or what made the audited change.	string	-	Yes	No	type:actor	user:<uuid> for a human actor, system:<name> for a machine actor. Never null — machine writes use a dedicated system actor id.	name: idx_auditLog_tenantId_createdBy, type: btree	user:2cd4482b-5391-46b2-b491-69a1ee949fa6
updatedBy	Always equal to createdBy — the row is never modified after insert.	string	-	Yes	No	type:actor	Must equal createdBy.	-	user:2cd4482b-5391-46b2-b491-69a1ee949fa6

Audited fields

N/A — the audit log has no trail of its own.

Not applicable — entityName resolution describes how other entities are named when referenced from an audit_log row; the row itself has no entityType of its own to resolve.