The audit trail: one row for every change an operator (or code) makes to the node's configuration or operational state, written with the change.

What is recorded

A row says who (actor, remote_ip, request_id, from Ankusa.Audit.Context), what (action, tenant, resource, detail), and what it did to the subject: before_hash and after_hash, an HMAC-SHA256 of the subject before and after, revision (the subject's own change counter, where it has one) and result. A row never holds a secret or a spec: a hash is keyed with a random per-store key (m:audit_key), so it shows that a source's secret changed without giving anyone with audit:read a way to test a guess against it, and detail carries only what the caller puts there (counts, filters, a rate).

A request that changes nothing (a validation error, a missing subject) writes no row; one that is refused by the store writes none either.

Order and durability

Rows live in the store's audit column family under <<?a, seq::64, at::64>>. This process hands out seq and commits the batch, so key order is commit order whatever the wall clock does, and a reader that remembers the last seq it saw (SEC-2.b's lifecycle outbox) can never miss a row that lands later with a smaller key.

There are two ways in:

• commit/4 is for a change that lives in this node's Ankusa.Store (API-managed sources, rate-limit overrides, quarantine, replay jobs): the change's own ops and the audit row go in one sync: true batch. Either both survive a kill -9 or neither does.

• begin/3 + finish/3 (or record/4) is for a change that lives somewhere else (route definitions, whose store is pluggable: ETS, or Redis shared by a fleet; the Redis source store). That is a dual write, and there is no transaction across the two. The row is written first, as a pending row (<<?p, seq::64>>, synced) that says what is about to happen; the change is applied; finish/3 then moves it into the trail with the outcome, in one batch. A crash in between leaves the pending row, and the next boot (or the caller dying, while this node runs) settles it as result: "interrupted": the change may or may not have been applied; after_hash is the hash of what was about to be written. For a source or route, Ankusa.Lifecycle.reconcile/2 does better than that: it reads the subject's present state and compares its hash to the row's after_hash (the change was applied: "ok") and before_hash (it was not: "failed"); a state that is neither (someone else changed it meanwhile) stays "interrupted" and is flagged for a state-refresh event. A boot has to wait for the subject's store to load, so such rows are settled by a tick (every second, for a minute, then as "interrupted"). The trail never loses a change that was applied; it can show one that was not only as "interrupted".

A change whose audit row cannot be written is not made: the caller gets {:error, :store_unavailable}.

The lifecycle outbox

When lifecycle events are on (Ankusa.Lifecycle), the row of a source or route change that took effect is flagged publish: true, and the redacted entity its event carries is written beside it at <<?o, seq::64>> in the same batch. The entity is not in the row: a row never holds a spec, and even redacted an entity is one. Ankusa.Lifecycle.Publisher reads the flagged rows in seq order with page/3 and keeps its place in m:lifecycle_cursor.

Restores and event identity

A store that came back from a backup (Ankusa.Store leaves m:incarnation_pending) re-issues the seq numbers of every change the lost one made after the backup, and some of those were already published. So the first thing this process does on such a boot is open a new incarnation: one history entry {from seq, fresh id} in m:incarnation, written with an instance.restore row (event io.ankusa.instance.restored, carrying the incarnation and the restored seq) in one synced batch, before any change is taken. incarnation/2 tells Ankusa.Lifecycle which id a row's event id is keyed with: rows of the restored trail keep the ids they were published under, every row from the new incarnation on gets a different one.

Retention

audit.retention_days (default 365). An hourly sweep deletes rows (and the lifecycle entities beside them) older than that, oldest first, in bounded batches, and emits [:ankusa, :audit, :pruned]. While lifecycle.sinks is set it never deletes a row at or above m:lifecycle_cursor, however old: a lifecycle sink that is down longer than the retention keeps the events it has not seen. The expired rows it holds back are emitted as blocked_by_cursor on [:ankusa, :audit, :retention] after every sweep. Every committed row emits [:ankusa, :audit].

Ceilings

The trail is bounded in audit.max_rows and audit.max_bytes, from counters kept in every batch (m:audit_usage; recounted at boot when it does not match the trail). Before a change is accepted the trail is pruned to them, oldest first and never past m:lifecycle_cursor; a trail that is still over a ceiling, or a lifecycle outbox holding audit.outbox_max_backlog or more events no sink has confirmed (m:audit_seq minus the cursor), refuses the new change with {:error, :audit_backlog} (503 audit_backlog, Retry-After: 60 on the admin APIs). An unpublished row is never dropped to make room, and a change already begun is always recorded. A change the node makes itself (Context.system/0) is not refused.