GT-603: the audit ledger can finally say whether a human or an agent did it

[beyondnetPeru]

Closes GT-603 (P0). All four acceptance criteria met, each watched red before green.

Why this one was urgent in a way no other row is

audit_entries is append-only by database trigger. Every row written before the discriminator exists is permanently unattributable — this is the one item on the board that expires instead of accruing cost. The product's differentiating claim (human-versus-agent attribution) was false in code that was already 90% written: AgentExecutionService and AgentTurnAuditor existed, were tested, and appeared in zero DI registrations and zero endpoints.

The append-only trigger, probed rather than assumed

Before writing the migration, the trigger was tested against a real PostgreSQL. It forbids UPDATE, DELETE, TRUNCATE — not INSERT, and not DDL. In one transaction: ADD COLUMN actor_type varchar(32) NOT NULL DEFAULT 'unknown' succeeds (PG≥11 fast default, no rewrite, no DML trigger), while UPDATE … SET actor_type='human' is rejected:

ERROR: audit_entries es append-only (DP-5): UPDATE no esta permitido sobre el registro de auditoria

So back-filling is not merely undesirable — it is impossible. Confirmed independently by the integrating session on the live database.

Chosen shape: the DEFAULT exists only for the ADD COLUMN statement and is dropped immediately after, plus a COMMENT ON COLUMN recording the semantics. Old rows read unknown — "not declared, and untypeable" — and any new INSERT omitting the discriminator fails with 23502. AuditActorType.Writable excludes unknown and AuditEntry.Create rejects it, so no application path can produce it; Rehydrate exists so old rows stay readable. The three append-only triggers are untouched, and a live test asserts all three survive the migration.

Verified on the live DB by the integrating session: actor_type is varchar(32) NOT NULL with no default, and the rows read agent 4 · human 6 · unknown 1.

Evidence per criterion

1. Port + auditor registered, AssistantEndpoints goes through them. RED: ...to have an item matching (d.ServiceType == IAgentExecutionPort), and Expected asientos not to be empty. GREEN: 20/20 on those classes (re-run independently), full solution 1034 passed / 0 failed plus 14/14 architecture tests. The endpoint response body is unchanged, asserted by a test.
2. Schema. RED against real Postgres: 42703: column "actor_type" does not exist. GREEN after 20260731021901_AddAuditActorAttribution, generated by dotnet ef with the snapshot untouched by hand.
3. Robot end to end. RED produced by restoring the pre-change AssistantEndpoints.cs and restarting the server: ✗ the agent turn is in the trail — the agent path wrote nothing, actorType=undefined, FAIL audit-trail (19 ok, 6 failed). GREEN: PASS audit-trail (25 ok, 0 failed), with actorType=agent, agentId, sessionId, scope, and the prompt itself is not stored.
4. Migration lands before any production write — nothing is deployed, and the migration ships in the same commit as the code that writes the column.

A latent bug fixed on the way

AgentTurnAuditor called AddAsync with no SaveEntitiesAsync. "Audit before executing, abort if the audit write fails" was a claim about an in-memory change nobody committed. It now commits, and converts write failures into a Result instead of an exception. Relatedly, a turn with no agent identity is now rejected before anything is written: on an append-only ledger a mis-attributed row is permanent, so not writing beats writing wrong.

AuditEntry.Create now takes attribution as a required parameter, so all 8 write sites had to declare their type; the AOP sink translates the envelope's existing SubjectType rather than inventing one.

ADR: warranted, not written

A T-NNN should cover the closed set of actor types, the decision that pre-migration rows stay unknown forever, and the ratification that agent turns share audit_entries rather than a separate AgentActionLog — that last one currently lives only in code comments from EAG-16.

Deliberately left out

• reference/specs/design/tracker-postgresql-data-design.md §12.1 describes audit_entries in a schema and with columns that never matched the implementation — pre-existing drift, untouched.
• model_id is config-driven rather than harvested from the runtime response, because the row is written before execution.
• Gateway failures now surface as a uniform 502 instead of mirroring upstream; scope/audit failures map to 400/403/503.
• Two pre-existing failures appear only under EVOLITH_CORE_LIVE=1; they need a running Evolith Core and are unrelated.

🤖 Generated with Claude Code