ENGINEERING CASE STUDY
Receipt continuity under partial writes, concurrency and corruption.
Blackbox receipt persistence is designed to preserve truthful chain state when writes are interrupted, multiple writers contend for the next chain position, or malformed data appears at the storage boundary — and to surface a boundary rather than manufacture a clean-looking one.
Engineering problem
An append-only evidence ledger has one job that matters above all others: never present a value as valid history unless it truly is. That job is hardest exactly when the environment misbehaves — a process is killed mid-write, two writers reach for the same next position at once, or a malformed row appears at the storage boundary. The failure that destroys an evidence store is not a crash; it is a crash whose damage gets silently normalized into apparently valid history on the next read.
The three failure modes it must survive
First, the partial write: a receipt that was being appended when the process died, leaving a torn tail at the end of the log. Second, concurrency: two appenders allocating the same chain-head position, which would fork or duplicate the chain. Third, corruption: a complete-looking row whose contents are malformed, which must not be quietly truncated away as if it never existed. Each mode has a distinct correct response, and the store is designed to the mode, not to a general hope that writes succeed.
Implementation
The current V2 receipt store serializes append so that writers do not race, and allocates the chain head under a lock so the next position is assigned exactly once. It uses durable flush behavior so an acknowledged append has actually reached storage, not just a buffer. On open it detects a torn tail — an incomplete trailing write — and repairs it before the next append rather than reading past it. And it refuses to silently mix legacy and V2 rows, because quietly interleaving two formats is itself a way to launder an inconsistent state into one that looks continuous.
Why silent normalization is the specific enemy
A naive store that truncates anything it cannot parse, or that reads past a torn tail, produces a log that always looks clean — and is therefore untrustworthy, because its cleanliness is manufactured. The design choice here is the opposite: a torn tail is repaired to the last known-good boundary, and a complete malformed row is refused rather than truncated, so the store would rather surface a boundary than hide one. Fail-closed on ambiguity is the only posture under which the chain means what it claims.
Negative controls
The current tests exercise the failure modes directly, not just the happy path: torn-tail repair before the next append; refusal to truncate a complete malformed row; the explicit requirement that legacy logs be migrated rather than silently accepted; and concurrent-append serialization under contention. These are negative controls in the proper sense — they assert what the store refuses to do, which is where an evidence system earns or loses trust.
Boundary
These controls establish the tested behavior of the receipt storage layer. They do not by themselves establish customer deployment, durability guarantees specific to a given filesystem or hardware, certification, or enterprise custody readiness — each of those is a separately evidenced state. The honest claim is precise: this is what the storage layer does under crash, contention and corruption in test, and nothing broader is implied.