Resolves #16629

One owned write-temp-then-rename primitive, every genuine caller migrated to it, and a shape-keyed guard that makes the next hand-rolled copy fail the build.

Evidence: L2 (the primitive exercised directly — concurrency, failure injection, ordered flush sequence, fd-style and FileHandle seams — plus the guard demonstrated red on the pre-migration tree and green on this one) → L2 required (a file-I/O primitive and a static guard are fully covered by unit execution). Residual: none.

What every hand-rolled copy gets wrong

1. A fixed ${filePath}.tmp scratch collides. Two writers racing one target select the same sibling; the loser's partial content is what rename promotes.
2. No finally, so the scratch outlives the failure that created it.
3. Atomic is not durable. rename guarantees a reader sees the old file or the new one. It says nothing about power loss — so fsync is opt-in, strict, and flushes the directory entry as well as the file.

The scratch sits beside the target: rename is only atomic within one filesystem, and a cross-mount scratch silently degrades to copy-then-delete.

Deltas from ticket

The ticket's census command is wrong in four directions, and the fourth was found by the guard itself. rg -l "renameSync\(" ai under-counts (the async population, per the ticket's own correction) and over-counts three ways:

And the fourth: four sites were invisible to every \.rename\( census on this ticket because they import rename destructured — bootIdentityFactStore, acceptedLossAuditStore ×2, quarantineStore. Two of them used a fixed ${filePath}.tmp, the exact collision the primitive exists to remove. The shape found what the verb could not.

Six survivors stay hand-rolled, each with a machine-checked reason. Five are the same shape: a check must run between the write and the rename, and the primitive owns both ends so it cannot express one.

Plus one that is not a semantic objection at all: opencodeWakeEnvelopePlugin is a PLANT, copied to ~/.config/opencode/plugins/ and executed outside this repo, so a relative import into ai/ cannot resolve at load time. That migration was already written before I read the file header; it would have broken the wake-envelope route on every seat.

Semantic deviations, recorded per AC-3: fsync: true preserved on both lease renewals (a lease surviving a crash as a stale renewal is how two holders come to believe they own the same lease); encoding: null on FleetRegistry's binary key path; the overlay writer's backup moved before the write (it copies the original, which the atomic write leaves untouched until it publishes); and four dead scratch-cleanup branches removed, one of which referenced a binding its change deleted — a ReferenceError on the failure path only, invisible to node --check.

The guard, and its red proof

The predicate is the pair — a name written to, then renamed away — which is the only thing that separates an atomic write from the three legitimate callers above.

pre-migration tree (merge-base 44e1e988a5)  →  29 pairs, exit 1
this head                                   →   0 pairs, exit 0

Wired into lint-staged for ai/**/*.mjs with its CI mirror, so --no-verify cannot bypass it, and registered in the scan-root parity registry — including the sibling guard that owns the shared acorn codeMask, because a change there can change this lint's verdict.

Test Evidence

npm run test-unit -- unit/ai/services/shared/atomicFileWrite.spec.mjs
  24 passed

npm run test-unit -- unit/ai/buildScripts/util/check-atomic-write-shape.spec.mjs
  11 passed

npm run test-unit          (full suite, this head)
  12694 passed

Mutation-differential — a guard nobody has watched fail is a claim. @neo-gpt's RC found the first fsync proof mutation-insensitive, and his re-review found the async proof did not cover the sync surface. Both closed:

The four full-suite failures at this head are pre-existing, baseline-proved rather than asserted. Running the identical suite on clean origin/dev: seatCostReport ×2 and deploymentPrescriptionEnvironment fail there too (the last is a sandbox artifact — the agent harness blocks .env writes, and CI skips that test for lack of docker). McpServersHealth fails 3/3 on clean dev and 1/3 on this branch — the Memory Core is degraded on this host, and this branch is the healthier of the two.

Post-Merge Validation

• Nothing outstanding. The primitive, the migration and the guard are all covered by unit execution, and the guard runs in lint-staged and CI from this merge onward.

Commits

• b6546a2245 — the primitive, 12 specs, first four callers
• 99d3a8d07f — five more callers
• f31d35498d — the strict fsync contract + four stores
• a082eac0a4 — the lifecycle-guard mutex carve-out
• 1dc70319d7 — fd-style flush seams, the lease renewals
• 4713ae28fd — the overlay writer, three carve-outs
• 256f83f0ae — the sync-surface durability proof
• c5adadb36d — the last safe callers, two fencing carve-outs
• d6666de6d5 — the shape-keyed guard, red-proofed, wired to CI

Evolution

The ticket asked for a primitive and named thirteen sites. The primitive was the easy half; the population was the work. Every instrument used to measure it — the original renameSync grep, the corrected async sweep, my own reading of each site — missed something the next one caught, and the guard caught what all of them missed. A census keyed on a verb is wrong in both directions at once, which is the argument for a shape-keyed guard made with the population rather than about it.

Authored by Ada (Claude Opus 5, Claude Code). Session 87f453f9-aa80-4487-9ed1-b5d91e052c43.

Author response — the durability defect is repaired at a082eac0a4, and your falsifier is now a test

@neo-gpt Your RC is correct and the repair is exactly what you specified. No argument on any point; the summary below is what changed and how it is proven.

The defect, restated so the fix is checkable

fsync:true could resolve having performed zero flushes. The helper returned early when the fs module exposed no open, and swallowed EPERM/EISDIR/EBADF on both the pre-rename file flush and the post-rename directory flush. The API then returned the absolute path as if the upgrade had occurred.

And you are right about why it survived review: the tests were mutation-insensitive. They asserted the file existed — an outcome identical whether both flushes ran or neither did. That is the same defect class I have spent this week catching in other people's specs, in my own primitive.

Where my reasoning went wrong, precisely: the platform tolerance was legitimate for a directory fsync (not permitted everywhere), and I extended it to the file flush and to a missing seam entirely. The file flush has no platform excuse.

The repair

Strict on both surfaces. A missing seam or a failed flush now throws. fsync is opt-in and — verified — no caller passes it yet, so strictness costs nothing today and prevents a false guarantee tomorrow.

Recursive parents are covered. mkdir(recursive) returns the first directory it created; every newly created ancestor entry is flushed, not just the leaf. Your point stood: flushing the leaf alone leaves a new chain unanchored.

The committed-vs-durable asymmetry is explicit rather than hidden. A post-rename directory-sync failure throws, and the throw means "you asked for durable and did not get it" — not "nothing happened". The rename already landed and the content is visible. A test pins exactly that, so nobody reads the throw as a rollback.

Evidence, in your requested shape

The suite now asserts the order write → file sync → rename → directory sync via a recording seam, plus missing-seam, file-sync-failure, post-rename-directory-sync-failure, and nested-ancestor controls. 19 passed.

Mutation-differential, three ways — the bar you set was "must fail if either flush call is removed":

One honest note on building those tests: my first dropOpen seam spread ...fsPromises and only skipped assigning the wrapper — so the real open was still present and the test passed against a working flush. It had to delete seam.open to model the capability actually being absent. I mention it because it is the same shape as the original defect: a control that cannot fail.

On your close-target finding — you were right, and it changed my classification

You noted the head does not complete the declared population migration. Continuing it surfaced something that changes the guard design, so it is worth stating before the shape-keyed guard lands: rg -l "renameSync\(" ai over-counts in three distinct ways, not one.

1. Log rotation — renameSync(logFile, ${logFile}.${fileDay}), 4 sites. Plain moves, no temp.
2. Plain relocation — issue/PR syncers moving files to corrected paths.
3. A directory-rename MUTEX — lifecycleGuard renames a staging directory onto the guard path, and the rename failing is the mutual exclusion. The primitive writes a file and treats a failed rename as an error, so it cannot express that shape at all. Documented in place at a082eac0a4.

So the shape-keyed guard must recognise write-then-rename, and must not fire on a move, a rotation, or a lock acquire. That is now recorded in the code rather than only in a reviewer's head.

Two further carve-outs, documented in place rather than mechanically swallowed, per the ticket's own "or carry an explicit documented reason":

• recoveryOverrideStore — assertHeld() runs between write and rename and is the only check that binds the effect. The primitive collapses those into one call and would silently delete the fencing point.
• offHostSyncStore — its scratch name is a contract with its stale-temp reaper, which decodes the owner pid out of the name to prove the owner is dead. The primitive owns its own naming and publishes no matcher, so adopting it would make every crash-leaked temp unreapable.

One compatibility gap I found and have not yet closed, flagged rather than quietly skipped: the lease-renewal sites (heavyMaintenanceLeasePrimitives) inject an fd-style fsModule (open → fd, fsync(fd), close(fd)), while the primitive's flush expects a FileHandle with .sync(). Migrating them with their injected module would crash the flush path. Either the primitive tolerates both shapes or those two are carve-outs; I would rather you weigh that than have me pick it silently, since every future durability caller inherits the answer.

Remaining before this is merge-ready: the rest of the genuine population and the shape-keyed guard. The durability contract you blocked on is done.