Clean Close
In this section
A brain that closes cleanly leaves a store the next process can attach to. A brain that does not — a kill, a crash, a power cut — leaves a store the next process must verify before it attaches. Both are supported states. This page says exactly what each guarantees, what each costs, and why the cost has the shape it has.
What a clean close guarantees
Three things, and only three:
Flushed | Every mutation this process acknowledged is on disk. Nothing acknowledged is in a buffer only. |
Attested | The projection artifacts carry a close-time attestation, so the next open is a manifest load and an attach rather than a proof. |
Unlocked | The writer lock is released, so the next process is not made to decide whether a lock file describes a live writer or a dead one. |
Everything else a close could do, it deliberately does not.
What a close deliberately does NOT do
It does not finish background work. Background jobs are aborted at their next checkpoint and settled with a bound (10 s). Every one of them carries a durable progress marker, so a job cut short is a job the next open resumes — never a job whose work is lost.
It does not wait for an online rebuild. A rebuild in flight is stood down, not awaited. Its progress marker is written at every checkpoint rather than at the end, which is precisely what makes waiting unnecessary: the next open resumes the walk from where the marker says it reached.
It does not pay compaction debt. Deferred compaction — the id mapper's, the verb stores' — is tracked by counters that survive the close, and the next open's background maintenance pass folds it behind the doors. Paying it at close was measured as the single largest close cost, and every second of it was a service that had already stopped serving standing in front of one that had not started.
The result is a close that costs O(dirty), not O(store) and not O(artifacts).
What it costs
Closing
Settle background jobs | ≤ 10 s, bounded; a job that will not settle is named and abandoned to its marker |
Flush | O(dirty) — proportional to what this process changed, not to what the store holds |
Attest | milliseconds |
MEASURED, and the reason this page exists. On a production restart, close cost 230 s on two stores and 31 s on five before the shape above was enforced. The cost was not the flush: it was an awaited rebuild unwind and up to 60 s per leg of compaction paid at close. Both are now deferred to where they belong, and neither loses work.
Booting
After a clean close | Manifest load + attach. No proof, no walk. |
After an unclean stop | Attach verification, then any strand heal, behind the doors — reads are served throughout |
The load-bearing word in the unclean row is behind the doors. An unclean boot does not become a foreground rebuild: the store serves from what it has while the verification and any heal proceed as background work with their own progress markers. A boot that had to rebuild before answering would make an unclean stop a second outage, which is exactly the failure this design refuses.
MEASURED, on the personal brain (15,941 rows) at 11.0.2: a boot whose metadata generation had to be rebuilt took 521 s, of which 351 s was the verb walk — and that 351 s was durability the build did not need, two msyncs per shard per row on a build artifact nobody replays. With the shadow build's logs in bulk-load mode and one batch per page, a build pays barriers per SHARD rather than per row. The barrier count is narrated on every shadow build, so the claim is a number in the log rather than an assertion on this page.
What is not measured here yet
The close and boot cost shape is stated above from a production restart and from the personal brain. The rehearsal fixtures' own numbers — Wicks & Whiskers and the platform copy — are owed and not yet taken, so they are not quoted. When the rehearsal lane records them, they belong in this table rather than in a thread.
Operating notes
A close that narrates deferred compaction debt is working correctly. The line names what was deferred and to where; the next open's background pass pays it.
A close that names a background job as unsettled is also working correctly — that job's marker stands, and the next open resumes it.
If a boot is slow, read the shadow build's narration: it carries rows done out of rows total, the rate, the projected remaining wall, and the barrier count. A build reporting barriers in the tens of thousands has lost bulk-load mode, and that is a defect worth filing with those numbers.