"""The one place audit rows are written (AUD-01, AUD-47). Call it inside the same database transaction as the change it records (ADR-53), so a change and its trace commit or roll back together. """ from typing import Any from .models import AuditEntry def record( action: str, *, actor=None, actor_label: str | None = None, reason: str = "", outcome: str = AuditEntry.Outcome.OK, subject_type: str = "", subject_id: object = "", payload: dict[str, Any] | None = None, ) -> AuditEntry: """Append one audit row. `actor` is the user who acted, or None for the system/worker.""" if actor_label is None: actor_label = actor.get_username() if actor is not None else "system" return AuditEntry.objects.create( actor=actor, actor_label=actor_label, action=action, reason=reason, outcome=outcome, subject_type=subject_type, subject_id=str(subject_id), payload=payload or {}, )