Consolidate atomic JSON persistence primitives

[lastobelus]

Outcome

Consolidate Markover atomic JSON file replacement behind one well-tested internal primitive while preserving each store's supported scheduling, ownership, recovery, and shutdown behavior.

Problem

Markover implements the same store-level same-directory temporary write and atomic rename independently in:

• src/review-store.ts;
• src/workspace-store.ts;
• src/settings-store.ts; and
• src/service-endpoint.ts.

The implementations differ in exclusive temporary creation, byte flushing, file mode, explicit chmod, cleanup, and retry behavior. Keeping these copies increases the chance that a durability or privacy fix reaches only some stores.

The earlier enrichment target is stale: #156 removed the unused private-enrichment runtime and preserved any sidecar bytes without a replacement store. PR #161 also removed unsupported cross-process settings locking and live watching while preserving the in-process queue and atomic replacement.

Acceptance criteria

• Define one internal atomic JSON replacement primitive with same-directory temporary files, exclusive wx creation, complete-byte flush before rename, user-only file mode where supported, explicit non-Windows permission enforcement where needed, atomic rename, and temporary-file cleanup.
• Migrate review, workspace, settings, and service-endpoint writers whose file-replacement requirements match.
• Keep store-specific scheduling outside the primitive: review serialization, workspace latest-snapshot and shutdown behavior, the settings in-process writer queue, and service-endpoint ownership remain independently testable. Preserve Simplify settings writer topology #161's supported settings topology; do not reintroduce cross-process settings locking or live settings-file watching.
• Preserve existing JSON formatting, paths, error behavior, schemas, and public contracts unless a separately justified correction is recorded.
• Add direct primitive coverage plus store-specific regression coverage for successful replacement, failure before rename, cleanup, concurrency/ordering, and restart or shutdown behavior where applicable.
• Gate POSIX permission assertions on platforms that expose POSIX mode semantics.
• Run the complete local CI suite and verify that no portable review, private workspace, settings, or service-endpoint behavior changes unintentionally.
• Deliver as a child of PR Add private remote attachment retrieval #191, address automated review, then retarget the green pull request to main after PR Add private remote attachment retrieval #191 merges.

Scope boundaries

• Internal durability and refactoring only; no user-facing feature or settings change and no UI QA.
• No persistence schema migration, compatibility reader, or data rewrite.
• Do not replace higher-level queues, locks, mutation gates, recovery policy, or lifecycle ownership with a generic abstraction.
• Startup diagnostics, instance descriptors, remote creation journals, create-only credentials, and directory publication have separate lifecycle or ownership contracts and are outside this named store slice.

Relationships

• Remove unused private-enrichment runtime #156 removed the unused private-enrichment runtime, so this issue has no enrichment writer to migrate.
• Investigate supported settings writer topology #159 established the supported settings writer topology; PR Simplify settings writer topology #161 removed the unsupported cross-process settings lock and live watcher.
• Run initially as a child of PR Add private remote attachment retrieval #191 / Let remote agents use canonical Markover #187, then retarget to main after PR Add private remote attachment retrieval #191 merges.
• Coordinate with Guarantee bounded-loss autosave durability across crashes and restarts #39 for crash/restart durability boundaries.
• Track in Technical Debt / Refactoring.

[lastobelus]

Settings topology evidence from #159

#159's latest-main investigation found one supported SettingsStore writer per state root. Electron's singleton lock excludes a second app owner in that root; development and smoke roots are isolated; the CLI is read-only; and the documented manual autosaveMaximumDelayMs edit requires Markover to be quit and restarted.

That evidence makes #144's current requirement to preserve settings cross-process locking a stale premise. #159 recommends retaining normalization, the in-process queue, atomic replacement, and malformed-file recovery while treating the symlink/PID lock and live filesystem subscription as removal candidates. No implementation or #144 scope edit was made; resolve this premise before #144 changes SettingsStore.

Evidence: #159 (comment)

[lastobelus]

Work intent

phase: review
summary: "PR #201 delivers the reconciled four-store atomic JSON replacement refactor as a ready child of PR #191; rebased onto the current parent head and babysit is active"
touch-points:
  - "src/atomic-json.ts and test/atomic-json.test.ts"
  - "src/review-store.ts and portable review persistence regressions"
  - "src/workspace-store.ts and latest-snapshot/flush regressions"
  - "src/settings-store.ts and in-process queue/restart regressions"
  - "src/service-endpoint.ts and private endpoint/credential regressions"
done-when:
  - "one primitive exclusively creates a same-directory private temporary file, flushes complete JSON bytes, enforces POSIX mode where supported, atomically renames, and cleans temporary files"
  - "review, workspace, settings, and service-endpoint writers use it without moving their scheduling, ownership, recovery, or shutdown behavior"
  - "JSON formatting, paths, schemas, and public contracts remain unchanged"
  - "focused regression tests and GitHub CI pass without UI QA"
  - "PR #201 targets PR #191, completes automated review and CI, then targets main after PR #191 merges"
excludes:
  - "private-enrichment persistence removed by #156, including migration, replacement storage, or sidecar consumption"
  - "cross-process settings locking, live settings-file watching, or any reversal of PR #161"
  - "startup diagnostics, instance descriptors, remote creation journals, create-only credentials, and directory publication"
  - "schema migration, compatibility readers, data rewrites, generic queues/locks, or UI behavior and UI QA"
blocked-by:
  - "PR #191 must merge before PR #201 is retargeted to main"
may-block: []
branch: "t3code/refactor-issue-144"
base-branch: "t3code/issue-187-slice-d (PR #191)"
base-head: "3783351e77f0a83818d617eb78a5e4260021cfda"
pull-request: 201
head: "b30bd26"
validation:
  - "lint, typecheck, build, and 83 focused tests pass after rebasing onto the current parent head"
  - "full local suite passes 861/862; unrelated load-sensitive decision-gardener timeout lower-bound assertion fails only in the concurrent suite and passes alone on Node 24"