feat(file-safety): atomic text publish primitive (S3 v2-1, epic #1375)

[easonLiangWorldedtech]

Summary

First unit of the v2 split of the file-write-safety stack (epic Zoo-Code-Org#1375, A4). Recreates the reviewed content of upstream PR Zoo-Code-Org#1395 (S3: atomic text publish) on current main as a standalone unit, replacing the stacked PR chain that will be closed as superseded.

• Epic: [EPIC] File Write Safety Prevent Concurrent Write Races Data Corruption Zoo-Code-Org/Zoo-Code#1375
• Tracking issue: [ENHANCEMENT] File-write safety series (upstream epic #1375): version-guarded atomic writes + per-step visibility/rollback — PR series plan #33 (v2 ledger)

Changes

• src/services/file-safety/safeWriteText.ts (new, 304 lines): atomic text publish primitive
  • resolvePublishTarget: realpath resolution for the target; ENOENT falls back to the given path, any other error propagates
  • safeWriteText(filePath, content, options):
    • ensures the parent directory exists
    • writes the content to a staging temp file (short-write loop) preserving the existing target's mode (0o644 for a new file), fsyncs the file, then commits atomically via rename — no torn writes on crash
    • win32: best-effort DACL save before the commit rename and DACL restore onto the parent directory after it (falls back to a plain rename when the save fails; the dump file is always cleaned up)
    • backup: true: renames the previous target to a backup before the commit and deletes it on success; on commit failure the backup is renamed back (rollback) and the temp file is discarded
    • tempPath: caller-supplied pre-written temp file (used by safeWriteJson in a later unit); the staging dir is not created and the temp file is not unlinked (caller's concern)
    • platform / execFileRunner: test seams for the win32 DACL path
• src/services/file-safety/__tests__/safeWriteText.spec.ts (new, 672 lines): 31 unit tests — happy path/cleanup, fsync ordering, symlink resolution, backup/rollback semantics (ENOENT swallowing, error propagation), win32 DACL handling (save/restore args, fallback on failure, dump cleanup, default-platform path), pre-written tempPath behaviour (fchmod to target mode, 0o444 open ordering, no POSIX directory fsync), and durability regressions (short writes, POSIX directory fsync, realpath/access error propagation)

Tests

• Targeted vitest (src/ workspace): 31/31 passed
• eslint --prune-suppressions --max-warnings=0 on both files: clean, suppression counts unchanged
• pnpm check-types: passed (11/11 tasks)
• Stryker mutation-diff gate (scripts/stryker-diff.mjs ci, changed lines only): 115 mutants — 109 killed + 6 timeouts; 0 surviving, 0 NoCoverage
• Line budget: 976 insertions / 0 deletions standalone against origin/main (measured via git merge-tree --write-tree); within the 1000 hard cap. A single self-contained new module plus its spec — splitting further would fragment the primitive from its tests.

Provenance

• Source: upstream PR feat(file-safety): atomic text publish primitive + safeWriteJson refactor (A4, #1375) Zoo-Code-Org/Zoo-Code#1395 (S3 of the original [EPIC] File Write Safety Prevent Concurrent Write Races Data Corruption Zoo-Code-Org/Zoo-Code#1375 stacked chain), tip 7fd49bcea, S3 head a37dd24f1. Functionally identical, with the following documented micro-refactors made to satisfy the 100% mutation gate:
  • Buffer.from(content) — the explicit "utf8" encoding literal was an equivalent mutant (default encoding is utf8)
  • simplified code extraction in the ENOENT checks to typeof x === "object" && x !== null — property access on a non-null object returns undefined when absent, so dropping the "code" in x half is behaviour-identical while removing an equivalent-mutant site
  • const opts: SafeWriteTextOptions = options ?? {} instead of repeated options?. lookups
  • dropped the redundant platform === "win32" && guard in the post-commit DACL restore (daclDumpPath is non-null only on the win32 save path)
• Base: rebased onto origin/main 0dbd5846f (v3.82.0)
• Follow-up units of the same stack: v2-2 (safeWriteJson rewrite), then A4a guardedWrite (v2-5) + ReadFileTool integration (v2-6) once v2-1/v2-2 and open PRs feat(file-safety): file version token for the guarded-write path (A1, #1375) Zoo-Code-Org/Zoo-Code#1383/feat(task): per-task file observation registry (A2, #1375) Zoo-Code-Org/Zoo-Code#1394 land

[github-actions]

Review status

Thanks for contributing. This comment tracks the review sequence and the next action.

Current step: Required CI passed. Waiting for automated review of the latest commit.

If automated review does not start, a maintainer must restart it.

Review-state labels are managed by this workflow; do not edit them manually.