M1-sync-contract

[pt-act]

Proposal

Summary

Make the filesystem sync conflict contract a first-class, discoverable guarantee, and add
one observability signal for the case where reconciliation silently discards local data.

Background and motivation

docs/02_sync_protocol.md describes bidirectional sync as DO-authoritative
last-writer-wins, and the "Conflict semantics" section notes that when an upstream entry
of a different node type lands where the receiver has a subtree, the receiver removes the
local node tree and applies the upstream entry — "local-only children under the
conflicting path are discarded without separate tombstones."

The sync engine has grown a lot of machinery around that core in recent weeks — deferred
command synchronization, path-aware push cursors, node_modules inclusion, ignore lists,
reconnect fencing keyed by runtime identity. All of it increases the number of paths an
upstream apply can take, while the discard behavior at the heart of reconciliation is
unchanged and still completely silent: removeInodeTreeAtPath in
packages/dofs/src/sync/apply.ts removes the local subtree with no tombstones and no
signal, so the one real data-loss path in the system is invisible to callers and operators.

Two gaps for consumers:

• The last-writer-wins contract and the absence of any guarantee for concurrent
  same-path writes on both sides are stated only inside the design doc, not on the
  public fs/Workspace surface — easy to miss when building on the API.
• The type-mismatch subtree discard is silent: nothing marks that local data was
  dropped, so a container command that clobbered local-only files is indistinguishable,
  after the fact, from a run where nothing was lost.

Who is affected: anyone building on @cloudflare/computer who writes to the workspace
from both the DO and a running command/container.

Goals

• Promote the LWW contract + "no concurrent same-path guarantee" caveat into a normative,
  clearly-titled block inside "Conflict semantics", cross-referenced from
  packages/computer/README.md (which currently describes the two stores syncing across
  the capnweb WebSocket without linking the conflict contract).
• Emit a structured observability signal when the type-mismatch discard path executes —
  e.g. a stable, greppable log line carrying path, fromType, toType, and the
  discarded-child count. Log-only; no behavior change.
• Add a regression test pinning both convergence and the signal, so docs and code cannot
  drift.
• Explicitly out of scope: any change to the wire protocol, cursor model, or conflict
  resolution/merge. (If safe concurrent same-path writes are ever wanted, that's a
  separate feature proposal.)

Example

Upstream pushes a file at /w/a where the receiver has a directory /w/a/ containing a
local-only /w/a/b.txt. After apply, /w/a is a file and /w/a/b.txt is gone. Today
that happens with no signal anywhere; the proposal is to emit one discard event and to
document the behavior on the public surface.

---

We have a working implementation of the signal plus its regression tests
(packages/dofs/src/sync/apply.ts / apply.test.ts) that applies cleanly on current
main. Per the contribution policy we have not opened a PR — happy to if the maintainers
would like one.