fix(close): a read-only brain writes nothing under _system/

`readonly-close-no-marker` closed the clean-shutdown-marker half of this law and
named the rest as a known residual. This is that residual, closed.

MEASURED on the base: a read-only open → read → close rewrote FOUR files —
`_system/__metadata_field_registry__.json.gz`, `type-statistics.json.gz`,
`subtype-statistics.json.gz` and `verb-subtype-statistics.json.gz`. An IDLE
reader that only opened and closed rewrote all four as well.

The cause was not the closes the marker fix guarded. It was Phase 1 of
closeDurableSteps, where every component flush ran unconditionally. A flush is a
write by definition: MetadataIndexManager#flush() saves the field registry "even
with no dirty fields" (its own comment), and the storage adapter's count flush
re-stamps the three statistics files. A session that committed nothing re-stamped
all four. Phase 2's closes were ungated too — the graph index's close drains both
LSM MemTables to SSTables and stamps its watermark, and the optional
vector/metadata `close` hooks (unimplemented in the reference engine, filled in
by a native provider) persist buffered state.

Every one of those calls now carries the same `!isReadOnly` guard the generation
store already had.

A reader still RELEASES what it holds, so Phase 2 is a branch rather than a skip:
GraphAdjacencyIndex gains `stopBackgroundFlush()`, the non-writing half of its
close, which clears the auto-flush interval that would otherwise outlive the
session. `close()` now calls it too, so there is one place that owns the timer.

Why this matters beyond tidiness: `_system/` is where a store keeps its evidence
about itself — what the writer committed, what the projections have seen. A
reader that rewrites any of it vouches for a state it only observed, and on
shared or snapshot storage it mutates bytes another process owns.

The pin hashes every file under `_system/` (and, in one case, the whole store)
across a reader's open → read → close, names the four paths that used to move so
a regression says which subsystem did it, and asserts the asymmetry holds in the
other direction — a WRITER's close still persists.
This commit is contained in:
David Snelling 2026-09-02 13:48:25 -07:00
parent 0d5ab6077d
commit f27a777615
4 changed files with 322 additions and 16 deletions

View file

@ -149,12 +149,12 @@ describe('a read-only brain writes no clean-shutdown evidence', () => {
brain = null
// The FILE SET under `_system/` is unchanged — a reader creates and
// removes nothing. (Other files under `_system/` — e.g. the metadata
// field registry, which stamps its own `lastUpdated` on every persist —
// are a pre-existing, separate concern outside this fix's scope: this
// pin is specifically about the generation store's clean-shutdown
// evidence, not about every subsystem's close() being a true no-op for
// a reader.)
// removes nothing. This pin is specifically about the generation store's
// clean-shutdown evidence. The wider law — that a reader leaves EVERY
// file under `_system/` byte-identical, which this fix left open as a
// known residual (the metadata field registry and the three statistics
// files were still re-stamped by a reader's close) — is closed and pinned
// in `readonly-close-writes-nothing.test.ts`.
const after = snapshotDir(systemDir())
expect([...after.keys()].sort()).toEqual([...before.keys()].sort())