acdl/core/audit_ledger_design.md

ACDL Tiered Audit Ledger Design (REQ-20)

Status: design authored in Phase 07 (milestone v1.1); the spike (Phases 08-10) implements the v1.0 hash chain + DynamoDB outbox write (D-041); the v1.2 build-out implements S3 Object Lock + JWS + async worker + DLQ + daily checkpoints.

The audit stream is the platform's tamper-evident record of every delivery action. The vision's "Audit truth lives outside the repository" bet [1] and "Not a mutable audit log" anti-goal [1] are the binding constraints. Version-control history does not satisfy regulatory evidence; the ledger is the source of truth.

Three tiers

• Cold tier (source of truth): S3 with Object Lock in compliance mode, 7-year retention (ARCHITECTURE.md §9). No one — including root — can delete or overwrite until retention expires. The regulatory record.
• Hot tier (query index): the acdl-evidence audit repo (unchanged from the v1.0 demo). Not part of the chain; a queryable mirror the evidence UI (evidence-ui/index.html) reads. Lightweight attestation linkage lives in the repo; the regulatory event body lives in S3.
• Outbox (write path): DynamoDB, RPO = 0 (synchronous write before contract submission ack). Single-region in v1 (us-east-1).

Spike scope (D-041) — what Phases 08-10 implement

• DynamoDB outbox: table acdl-outbox, PAY_PER_REQUEST (D-044), PK contractId, SK eventType#eventTs, TTL expire_at = now + 365d (1-year storage per ARCHITECTURE.md §8).
• prev_event_hash chain: SHA-256 over canonical JSON (json.dumps(event, sort_keys=True, separators=(",", ":"))), lifted from the v1.0 demo's evidence_writer.py. Auto-genesis: first event has prev_hash="GENESIS".
• Synchronous write via boto3 put_item (strong-consistent by default). No separate async worker / DLQ in the spike (RTO = workflow re-run).
• Mirror to acdl-evidence: unchanged from v1.0 — the finalize step commits audit.json to the evidence repo (the hot tier).
• Spike evidence event shape: {seq, ts, stage, event, prev_hash, hash, contractId, environment, stack, score, band}.

v1.2 build-out — what Phase 07 designs but the spike defers

• S3 Object Lock: bucket acdl-evidence-lock-<account-id>, Object Lock enabled at creation, compliance mode, 7-yr retention (RetainUntilDate = now + 7y). The outbox→S3 path is an async worker that reads from the outbox and writes to Object Lock.
• JWS detached signature (RFC 7515): the event payload is canonical-JSON-serialized, SHA-256 hashed, signed with a private key; the signature is stored detached alongside the payload. Signing key = platform-level KMS key (not per-contract — a per-contract key would explode the key-management surface), rotated quarterly. The jws field is added to the event shape in v1.2.
• Async worker + DLQ: a Lambda (or a Gitea Actions scheduled workflow) reads the outbox, writes to S3 Object Lock, signs with KMS. DLQ = an SQS dead-letter queue for failed writes. RTO = DLQ replay.
• Daily checkpoints (§9): a daily job reads the last event hash and writes a "checkpoint" event to the ledger (+ optionally to a public notarization service). The spike runs in minutes, not days — no checkpoint in spike.

JWS vs chain — orthogonality note

The prev_event_hash chain gives ordering/tamper-evidence within the log (a deleted event breaks the chain visibly); JWS gives authenticity per event (a forged event is detectable without re-reading the whole chain). The chain is spike-scope; JWS is v1.2. Together they cover both integrity properties the vision's "Not a mutable audit log" anti-goal requires.

Outbox item shape (full, spike + v1.2)

• PK contractId (UUID).
• SK eventType#eventTs (e.g. POLICY_CHECKED#2026-07-21T12:00:00Z).
• payload (the event body — hash-chained in spike, JWS-signed in v1.2).
• prev_event_hash (chain link; GENESIS for the first event).
• hash (this event's SHA-256 over canonical JSON).
• approver_qa (Gitea username of the QA approver; empty in dev-only spike; populated on qa-promotion — D-042).
• approver_prod (SRE username; empty in spike).
• environment, stack, score, band.
• expire_at (TTL = now + 365d).
• v1.2 only: jws (detached signature), checkpoint_ref.

RPO / RTO table

Phase	RPO	RTO
Spike (D-041)	0 (sync outbox write)	workflow re-run
v1.2	0 (sync outbox)	async worker DLQ replay

Decision trail

• D-041 — spike scope = hash chain + outbox write; Object Lock + JWS
  • worker + DLQ are v1.2.
• D-044 — outbox mode PAY_PER_REQUEST; PK/SK; TTL expire_at = now + 365d; no separate async worker in spike.
• D-042 — approver identities (approver_qa, approver_prod) live in the outbox; the separation-of-duties check (platform/separation_of_duties.py) reads approver_qa and compares to the prod-dispatch gitea.actor.