Decisions · ADR-001

Append-only decision ledger

Status
Accepted
Date
Updated
Surfaces on

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_at field, 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)