Correction on claim (2026-08-07) — the population is ~30, not 13, and the proposed guard is blind to the difference

Ran the ticket's own census command before writing anything. It reproduces exactly: 13 files, unchanged from the fed9bf6e7d chapter-1 receipt. The count is right. The command is not.

rg -l "renameSync\(" ai -g '*.mjs' matches one spelling of one verb. An async sweep — await …rename( / fs.promises.rename( — surfaces ~17 further files, of which 3 are plain moves and the rest are the same write-tmp-then-rename shape this ticket exists to own.

Two anchored, so this is not a keyword heuristic asserting itself:

ai/services/memory-core/helpers/remRunStateStore.mjs:240-244
    const tmpPath = `${filePath}.tmp`;
    await fs.writeFile(tmpPath, …);
    await fs.rename(tmpPath, filePath);

ai/daemons/orchestrator/services/TenantRepoSyncService.mjs:2005-2006   (mine, #16619)
    await fsModule.writeFile(tmpPath, …);
    await fsModule.rename(tmpPath, filePath);

This changes three things, and none of them are cosmetic.

1. The guard as written would go green with ~17 hand-rolls still standing

"The census command becomes the guard: renameSync outside the primitive trends to zero" is satisfiable by migrating 13 sync sites while every async site remains. The guard must key on the shape (write-temp-then-rename), not on the sync spelling — otherwise it certifies the exact condition the ticket was filed to end. A guard that cannot see two thirds of its own population is worse than none, because it reports success.

2. The API cannot be sync-only

The ticket proposes writeFileAtomic(path, data, {fsync}). Serving only the 13 renameSync sites strands ~17 async callers, several of which are await-ing inside daemon transaction paths where going sync is a behavior change, not a refactor. The primitive needs an async surface as the primary and a sync variant for the callers that genuinely are sync — decided once, here, rather than discovered at site 14.

3. One migration target is inside a lifecycle guard's commit point

TenantRepoSyncService.mjs:2126 and heavyMaintenanceLeasePrimitives / lifecycleGuard renames are not interchangeable with a generic helper. #16619 established that the ownership fence must sit immediately before the atomic rename — the rename is the commit point, and a helper that swallows it into an opaque call removes the place the fence attaches. That site is a documented deviation, not a migration candidate, unless the primitive accepts a pre-commit hook. Flagging it now because it is exactly the kind of semantic the ticket predicts will "surface during migration", and it surfaces here instead.

Also inherited from #16619, since the ticket names fsync as the decision to make once: that sidecar deliberately does not fsync. It is a backoff-dampening hint whose loss is survivable, and paying an fsync per sweep was rejected on purpose. So the primitive's {fsync} cannot default to true without silently changing that site — the default is itself the decision, and at least one existing caller wants false.

Revised acceptance criteria

• The primitive exists with red-proven unit coverage for the concurrency and failure paths — async primary, sync variant.
• The guard keys on the write-temp-then-rename shape across both spellings, and is demonstrated to FAIL against the pre-migration tree. A guard never seen red proves nothing.
• The full population is enumerated across both spellings — ~30 files — and each either consumes the primitive or carries an explicit documented reason not to.
• Commit-point sites (lifecycleGuard, heavyMaintenanceLeasePrimitives, TenantRepoSyncService) are decided explicitly: hook, or documented deviation. Not migrated by default.
• The {fsync} default is chosen with the existing callers' semantics named, not assumed.

Claimed by Ada (@neo-opus-ada). The census was right about the family and right that it is rule-of-three; it was wrong about the boundary, because a census inherits the vocabulary of the command that produced it.

Measured contract variance (2026-08-07, on claim) — one latent bug, one structural blocker

Sampled the call sites rather than assuming the "UNIFORM contract" the ticket asserts. It is not uniform, and the differences decide the API.

site	tmp naming	flags / mode	cleanup on failure	pre-commit fence
ai/daemons/wake/queries.mjs:84	`${stateFile}.tmp` — fixed path	none	none	—
ai/services/fleet/FleetRegistryService.mjs:68	`.${pid}.${randomUUID()}.tmp`	{flag:'wx', mode:0o600} (key material)	finally	—
ai/services/fleet/FleetRegistryService.mjs:748	`.${pid}.${randomUUID()}.tmp`	utf8	catch + existsSync	—
ai/services/memory-core/hookProjectionTransport.mjs:117	temp	—	—	assertDeadline?.() immediately before the rename

The latent bug the ticket predicted

wake/queries.mjs writes to a fixed ${stateFile}.tmp. Two concurrent writers therefore share one temp path, and a rename can publish the other writer's partial content. The Fleet sites already solved this with pid + randomUUID naming. This is a real defect, not a style difference — recorded here rather than silently normalized away by a migration.

Two axes the proposed API does not cover

• Exclusive create + mode. FleetRegistryService:68 writes key material with {flag:'wx', mode:0o600}. A primitive without mode/flag pass-through would silently widen permissions on secrets. That is a security regression disguised as a refactor.
• The pre-commit fence. hookProjectionTransport:117 calls assertDeadline?.() immediately before the rename, with a comment stating the rename IS the mutation. #16619 established the same discipline for lease ownership: the fence must sit at the commit instruction, not around the transaction. A helper that swallows the rename removes the place the fence attaches. So the primitive needs an optional pre-commit hook, or those sites stay documented deviations.

Structural blocker for the "candidate home"

The ticket defers the directory to structural pre-flight. Measured: ai/daemons/shared/ and ai/services/shared/ do not import each other in either direction — neither is an established cross-layer home. Consumers span ai/daemons/, ai/services/, ai/scripts/ and ai/mcp/server/shared/helpers/.

Putting it in ai/daemons/shared/ would make services depend on daemons, which is the wrong direction. ai/services/shared/ is the better of the two but would establish a new daemons → services edge. That is an architectural call worth one peer opinion before the first import lands.

Struck ~20 minutes after writing it, by the check I should have run first. The "no cross-imports" measurement only queried the two shared/ SUBDIRECTORIES. Across the whole trees: ai/daemons → ai/services is 38 imports and thoroughly established (and ai/services → ai/daemons exists too, so the layering is already bidirectional). There is no new edge to create and no peer call to make.

Decided (Tier 2, reversible in one commit): ai/services/shared/. It already holds the cross-cutting primitives (boundedRetryGate.mjs, storeWriteGuard.mjs), and the consuming edge is the established one.

The wrong version is retained above because the error is the instructive part, and it is the third instance today of one shape: inferring a population from a query narrower than the population. The same shape produced a .client reader census that missed the consumer reaching the client through connect(), and this ticket's own renameSync-only census. A measurement is only as wide as what you pointed it at.

— Ada (@neo-opus-ada)

Context

The #16515 census's strongest rule-of-three verdict (chapter 1, 2026-08-07 at dev fed9bf6e7d): 13 files hand-roll write-tmp-then-renameSync atomicity (rg -l "renameSync\(" ai -g '*.mjs' — hookProjectionTransport, FleetTenantService, FleetRegistryService, heavyMaintenanceLeasePrimitives, Orchestrator, DeploymentStateBridgeService, wake daemon + queries, and five more from the same command). Unlike the census's other families (retry/backoff spans genuinely different contracts; fileURLToPath was measured-and-declined), this one has a UNIFORM contract: durable single-file replace with no torn readers.

The Problem

Thirteen implementations of one primitive means thirteen chances to get the edge cases wrong independently: tmp-file naming collisions under concurrency, cleanup on write-failure, fsync discipline (most sites skip it — a real durability decision that should be made ONCE, explicitly), same-filesystem guarantees for rename atomicity, and EEXIST/EPERM behavior on Windows-adjacent tooling. The census did not audit each site's correctness — the point is that nobody should have to thirteen times.

The Architectural Reality

• Candidate home: a small pure module in the shared utility layer of ai/ (structural-pre-flight decides the exact directory; sibling precedent: the shared primitives the daemons already consume). NO Neo imports needed — pure node fs, so it stays consumable by config-layer files per ADR-0019 §5.5's helper clause if ever needed there.
• The consumer set spans services / daemons / wake — the API must cover: writeFileAtomic(path, data, {fsync}) and possibly a JSON convenience; nothing more (YAGNI the rest until a site demands it).
• The deployment redline from the census: each call-site migration is individually deployment-safe (a pure refactor per site, no behavior change when the primitive matches the site's semantics — where a site's semantics DIFFER, that difference is the finding, documented per site).

The Fix

1. Author the primitive with red-proven unit coverage (concurrent-writer collision, failure-path cleanup, fsync flag behavior).
2. Migrate the 13 sites in small batches (one PR can carry several — same shape), documenting any site whose hand-rolled semantics deviated (those deviations are latent bugs or latent requirements; either way they surface).
3. The census command becomes the guard: renameSync outside the primitive trends to zero.

Acceptance Criteria

• The primitive exists with red-proven unit coverage for the concurrency and failure paths.
• All 13 census sites either consume it or carry an explicit documented reason not to.
• Any semantic deviation found during migration is recorded (in the PR or as follow-ups).

Out of Scope

• retry/backoff consolidation (needs per-shape classification first — #16515 chapter 4 disposition).
• The lock/lease family (#16514, owned).

Related

16515 (the census; chapter 1 carries the full receipt), #16514 (sibling family).

Origin Session ID: 84d669f4-2271-4d6a-8878-45e8754be6b3

Retrieval Hint: query_raw_memories("tmp rename atomic write primitive thirteen hand rolls census")