Tracking S4a: guarded write CAS core with per-path FIFO chain #1399

Tracking issue for the S4a PR (branch feat/guarded-write-s4a; PR to be opened after review).

Part of the file-write safety series — plan: easonLiangWorldedtech/Zoo-Code#33, epic: #1375. Item: S4a — Guarded write CAS core. Stacks on #1383 (S1 version tokens), #1394 (S2 observation registry), and #1395 (S3 atomic publish) — the branch is built on all three; S4b wires it into the save paths.

Scope

• New src/core/tools/guardedWrite.ts: a compare-and-swap layer over the S1/S2/S3 primitives. Decision table per absolute path:
  • unobserved + absent → createIfAbsent
  • unobserved + present → fail (file not read yet — read the file, then retry), forcing the model to re-read
  • observed + absent → createIfAbsent
  • observed + present → replaceIfVersion (version mismatch → stale fail: stale version — re-read the file, then retry)
• Typed error classes carrying the exact remediation texts; per-absolute-path tail-promise FIFO chain (in-process, no lockfile) so concurrent writes to the same path serialize and different paths stay parallel.
• Pure core module: no tool wiring, no DiffViewProvider changes (that is S4b).

Acceptance

• Every decision-table row has a deterministic unit test, including both exact remediation strings
• Same-path writes serialize (FIFO); cross-path writes run in parallel
• Uses only the existing S1 (versionToken), S2 (ObservationRegistry), S3 (safeWriteText) APIs — no new deps, no lockfiles
• CI green (ubuntu unit-test gate), 100% codecov patch coverage

Status

• PR: to be opened (after S1+S2+S3 merge)