Story Index: audit-log (AUDIT) — V0 envelope¶
Module: audit-log Total stories: 6 (V0 scope: v0.0.0 → v0.1.0) Decomposed from: docs/architecture/audit-log-arch.md §11 Vertical Slice Decomposition (status: awaiting founder approval — see note) PRD reference: docs/prd/audit-log-prd.md (V1 PRD with V0 envelope block) + docs/prd/prd-v0.md §4 Design reference: N/A — AUDIT has no UI in V0/V1 (PRD §C.5) Date: 28/05/2026
Approval note: the architecture still reads "Awaiting founder approval (workflow stage 4)". These stories were decomposed at the founder's explicit
/decomposerequest; treat them as draft until the architecture approval marker is set.Naming: the architecture's first slice is
AUDIT-S0; it is filed here asAUDIT-000for zero-padded sequencing. Other modules (e.g. OP-000) reference it as "AUDIT-S0". The architecture'sAUDIT-001slice is split intoAUDIT-001a/b/c(the split candidate offered in arch §11) to keep each story within the 2–4 acceptance-criteria limit; cross-module references to "AUDIT-001" map to all three.
Sub-version flagging (per story)¶
| Story | Sub-version | Title |
|---|---|---|
| AUDIT-000 | v0.0.0 | Dev environment + test infrastructure |
| AUDIT-001a | v0.0.0 | Audit schema, Postgres roles, schema-migration self-event |
| AUDIT-001b | v0.0.0 | Outbox consumer, AuditEventBuilder, catalog enum, producer stubs |
| AUDIT-001c | v0.0.0 | PiiHasher + per-tenant salt provisioning |
| AUDIT-002 | v0.0.1 | Real audit emission on payment + notification hot paths |
| AUDIT-003 | v0.1.0 | Compliance-report stub (degraded CSV export) + ingest metrics |
Dependency Graph¶
TENANT-S0 ─┐
▼
AUDIT-000 (v0.0.0)
│
▼
AUDIT-001a (v0.0.0) ◄── TENANT-001 (FKs), needs AUTH-001 role wiring
│
┌─────┴─────┐
▼ ▼
AUDIT-001b AUDIT-001c (v0.0.0, concurrent — different files)
(outbox/ (PiiHasher/
builder) salt)
│ │
└─────┬─────┘
▼
AUDIT-002 (v0.0.1) ◄── PAY-001, NOTIF-002 (real emission lives there)
│
▼
AUDIT-003 (v0.1.0)
Story List¶
| # | Story ID | Title | Side | Depends On | Complexity | Status |
|---|---|---|---|---|---|---|
| 1 | AUDIT-000 | Dev env + test infrastructure | [BACKEND] | TENANT-S0 | M | Draft |
| 2 | AUDIT-001a | Schema + Postgres roles + schema-migration self-event | [BACKEND] | AUDIT-000, TENANT-001 | M | Draft |
| 3 | AUDIT-001b | Outbox consumer + builder + catalog + stubs | [BACKEND] | AUDIT-001a, TENANT-001, AUTH-001 | L | Draft |
| 4 | AUDIT-001c | PiiHasher + per-tenant salt | [BACKEND] | AUDIT-001a, AUDIT-001b, TENANT-001 | M | Draft |
| 5 | AUDIT-002 | Real emission on PAY + NOTIF | [BACKEND] | AUDIT-001b/c, PAY-001, NOTIF-002 | S | Draft |
| 6 | AUDIT-003 | Compliance-report stub + ingest metrics | [BACKEND]+[ADMIN] | AUDIT-002 | M | Draft |
Concurrency Tiers¶
| Tier | Stories | Can Start After |
|---|---|---|
| 0 | AUDIT-000 | TENANT-S0 |
| 1 | AUDIT-001a | AUDIT-000 |
| 2 | AUDIT-001b, AUDIT-001c (parallel) | AUDIT-001a |
| 3 | AUDIT-002 | AUDIT-001b + AUDIT-001c + PAY-001 + NOTIF-002 |
| 4 | AUDIT-003 | AUDIT-002 |
PRD Acceptance Criteria Coverage (V0 scope)¶
Only the ACs whose behaviour is delivered within the V0 envelope (v0.0.0–v0.1.0) are assigned here. ACs requiring the V1 query/by-case/full-export/active-alerting surfaces are explicitly deferred.
| PRD User Story | AC | Assigned To |
|---|---|---|
| AUDIT-US-01 | AC-01.1 | AUDIT-001b ✅ |
| AUDIT-US-01 | AC-01.2 | AUDIT-001b ✅ |
| AUDIT-US-01 | AC-01.3 | AUDIT-001b ✅ |
| AUDIT-US-01 | AC-01.4 | AUDIT-003 ✅ |
| AUDIT-US-02 | AC-02.1–02.4 | Deferred → V1 (AUDIT-004) |
| AUDIT-US-03 | AC-03.1–03.4 | Deferred → V1 (AUDIT-005) |
| AUDIT-US-04 | AC-04.3 | AUDIT-003 ✅ (degraded) |
| AUDIT-US-04 | AC-04.4 | AUDIT-003 ✅ (degraded budget) |
| AUDIT-US-04 | AC-04.5 | AUDIT-003 ✅ |
| AUDIT-US-04 | AC-04.1, AC-04.2 | Deferred → V1 (AUDIT-006: JSONL+manifest+SHA-256) |
| AUDIT-US-05 | AC-05.1 | AUDIT-001a ✅ |
| AUDIT-US-05 | AC-05.3 | AUDIT-001a ✅ (process) |
| AUDIT-US-05 | AC-05.4 | Documented in AUDIT-001a + AUDIT-003 (honest scope) ✅ |
| AUDIT-US-05 | AC-05.2 | Deferred → V1 (AUDIT-007: reader role) |
| AUDIT-US-06 | AC-06.1 | AUDIT-001c ✅ (+ verified on hot path in AUDIT-002) |
| AUDIT-US-06 | AC-06.2 | AUDIT-001c ✅ |
| AUDIT-US-06 | AC-06.5 | AUDIT-001c ✅ |
| AUDIT-US-06 | AC-06.3, AC-06.4 | Producer-side conventions (noted in AUDIT-001c / AUDIT-002) ✅ |
| AUDIT-US-07 | AC-07.1, AC-07.4 | AUDIT-001a ✅ (structural: no DELETE grant, no purge tool) |
| AUDIT-US-07 | AC-07.2, AC-07.3 | TENANT-owned (settings floor / soft-delete); AUDIT survives — noted in AUDIT-001a |
| AUDIT-US-08 | AC-08.2 | AUDIT-003 ✅ |
| AUDIT-US-08 | AC-08.3 | AUDIT-001a ✅ |
| AUDIT-US-08 | AC-08.1 | Deferred → V1 (AUDIT-004: query self-event + dedup) |
| AUDIT-US-09 | AC-09.3 | AUDIT-003 ✅ (AUDIT_RECONCILED + metrics) |
| AUDIT-US-09 | AC-09.1, AC-09.2 | Deferred → V1 (AUDIT-009: active alerting + Grafana) |
| V0 TOTAL | 18 ACs in V0 scope | 18 assigned ✅ (US-02, US-03, full export, active alerting, reader role deferred to V1 per arch §11) |
Implementation Order¶
- AUDIT-000 — dev env + Testcontainers + MinIO bucket + Postgres roles bootstrap; blocks everything.
- AUDIT-001a — schema frozen day one + append-only roles +
AUDIT_SCHEMA_MIGRATEDcallback; backbone for all writes/reads. - AUDIT-001b — outbox consumer + builder + catalog enum + producer stubs; delivers the zero-loss write contract (AUDIT-US-01).
- AUDIT-001c — PiiHasher + per-tenant salt; can run in parallel with 001b (different files).
- AUDIT-002 — turn on real emission for PAY + NOTIF and verify mandatory fields + phone hashing end-to-end.
- AUDIT-003 — degraded CSV export + reconciliation self-event + ingest metrics (closes the V0 envelope at v0.1.0).
Deferred to V1 (tracked, not decomposed here)¶
| Slice | Story | Tag |
|---|---|---|
| AUDIT-004 | Filtered query API (US-02) + AUDIT_QUERY_EXECUTED dedup (FR-09) |
[V1] |
| AUDIT-005 | By-case lookup (US-03) + correlation expansion | [V1] |
| AUDIT-006 | Full JSONL + manifest + SHA-256 export (US-04) | [V1] |
| AUDIT-007 | papillon_audit_reader role + query pool uses it |
[V1] |
| AUDIT-008 | Defensive PII scan at the AUDIT INSERT boundary (FR-03 §2) | [V1] |
| AUDIT-009 | Active ingest-degradation alerting + Grafana rules (US-09) | [V1] |
V2: tenant-side viewer, cryptographic tamper-evidence, BYO-DB audit residency, salt rotation, cryptographic erasure, automatic 10-year purge (PRD §A.5).