Decisions · ADR-001
Append-only decision ledger
Compliance determinations are written as new rows; never updated in place. Storage-layer integrity, enforced by row-level triggers, not by policy.
Context
Compliance determinations are evidentiary records. They get challenged at fair hearings, in court, and in administrative review years after they were originally made. A mutable record is a record that can be tampered with, by accident or by intent, and the audit trail loses its evidentiary value the moment that mutability is detectable. State Medicaid agencies relying on this platform need records that still show what happened when they are reviewed years later.
Decision
Audit and ledger records are written as new rows and are not updated in place; a correction is a new entry. The mechanism is a row-level database trigger that raises an exception on any UPDATE or DELETE attempt against the ledger tables. There is no application-level honor code; the database refuses the operation even if a hypothetical privileged client tried. Soft-delete semantics (status fields, deleted_at timestamps) are used where a “remove” operation is conceptually needed, but the underlying row stays.
Consequences
The history is still there for review years later because integrity is enforced at the storage layer, not the policy layer. Storage cost grows monotonically over time; the platform plans for this in retention and archive policy. Operations that conceptually “delete” something become append-with-status-change, which requires query patterns to filter on status. The discipline is enforced uniformly across every service that touches a ledger table.
Alternatives considered
- Soft-delete with
deleted_atfield, no triggers. Rejected: rows remain technically mutable; tampering is not detected at the storage layer. Audit posture under hostile-discovery scrutiny is weaker. - Audit-log triggered on UPDATE/DELETE rather than refusal. Rejected: still allows the original row to change; the audit log records that a change happened but the original value is gone. Doesn’t preserve evidentiary integrity.
References
- standardACID (Atomicity, Consistency, Isolation, Durability) isolation guarantees
- standardAppend-only ledger pattern (canonical in financial systems and event-sourcing architectures)