amalgm 0.1.238 → 0.1.240

package/runtime/scripts/amalgm-mcp/state/docs.js

@@ -6,8 +6,8 @@
  * A document is a text file (markdown, code — anything in the fs layer's
  * text-extension set) whose contents are held in a Y.Doc while open. Edits
  * travel as Yjs updates in the event log's `patch` slot; the file on disk
- * remains the artifact (debounced write-back), so everything that reads the
- * file — agents, exports, git — keeps working unchanged.
+ * remains the artifact, so everything that reads the file — agents, exports,
+ * git — keeps working unchanged.
  *
  * Wire contract:
  *   POST /state/docs/open    {path}                → {resource, path, state, seq}
@@ -30,22 +30,28 @@
  * (entry.lastDiskText) — our own write-backs and stale watcher events can
  * never splice, so they can never re-emit.
  *
- * When the doc has ALSO diverged from lastDiskText (live edits inside the
- * write-back debounce window), splicing disk text wholesale would delete
- * those edits. Instead the disk change three-way merges against
+ * When the doc has ALSO diverged from lastDiskText (live edits arrived since
+ * the filesystem writer's apparent base), splicing disk text wholesale would
+ * delete those edits. Instead the disk change three-way merges against
  * lastDiskText as the base (see ./merge3): non-overlapping hunks from both
  * sides land automatically; overlapping hunks keep the live doc's text, and
  * the full incoming disk text is preserved in a `<name>.conflicted-<stamp>`
  * sidecar next to the file, with a `conflict` field on the emitted doc
- * event. The next write-back then puts the merged text on disk — the
- * incoming version it replaces lives on in the sidecar.
+ * event. The journal-owned native file transaction then puts the merged text
+ * on disk only if that exact observed predecessor is still there.
  */
 
 const crypto = require('crypto');
 const fs = require('fs');
 const path = require('path');
 const { cachedStatement, ensureDocStatesSchema, openLocalDb } = require('./db');
-const { appendStateEvent, currentSeq } = require('./events');
+const docDisk = require('./doc-disk');
+const {
+  appendStateEvent,
+  currentSeq,
+  insertStateEvent,
+  publishStateEvent,
+} = require('./events');
 const { merge3 } = require('./merge3');
 const { trace } = require('./trace');
 
@@ -53,8 +59,8 @@ const DOC_RESOURCE_PREFIX = 'doc:';
 const TEXT_KEY = 'content';
 const MAX_DOC_BYTES = Number.parseInt(process.env.AMALGM_DOC_MAX_BYTES || '', 10) || 2 * 1024 * 1024;
 const MAX_OPEN_DOCS = 64;
-const DISK_WRITE_DEBOUNCE_MS = 300;
 const WATCH_RECONCILE_DEBOUNCE_MS = 200;
+const WATCH_VERIFY_MS = 5_000;
 const MAX_UPDATES_PER_CALL = 200;
 
 // Bounds on the per-doc disk-sync history ring (see pushDiskHistory): a small
@@ -78,8 +84,8 @@ const WRITE_EXAMPLE = '{"path": "notes.md", "text": "full new file contents", '
 // doc or feed the reconcile loop.
 const SIDECAR_NAME_RE = /\.conflicted-\d{8}-\d{6}(?:-\d+)?(?:\.[^./\\]*)?$/;
 
-// resolved path -> { doc, resource, reconcileTimer, diskWriteTimer,
-//                    lastAccess, lastDiskText, lastDiskHash, pathAliases }
+// resolved path -> { doc, resource, reconcileTimer, lastAccess,
+//                    lastDiskText, lastDiskHash, pathAliases }
 const openDocs = new Map();
 
 // pathInput (as the client sent it) -> resolved path, held only while the doc
@@ -92,6 +98,9 @@ const resolvedPathCache = new Map();
 // per directory instead of one per doc: N docs in a folder cost one fd, and
 // the watcher dies when its last doc closes (docs.size is the refcount).
 const dirWatchers = new Map();
+let watchVerificationTimer = null;
+let watchVerificationPasses = 0;
+let diskTransactionTestHooks = {};
 
 function fsPrivate() {
   return require('../fs/rest')._private;
@@ -113,6 +122,10 @@ function invalid(message, statusCode = 400) {
   return Object.assign(new Error(message), { statusCode });
 }
 
+function isJournalCursor(value) {
+  return Number.isSafeInteger(value) && value >= 0;
+}
+
 function hashText(text) {
   return crypto.createHash('sha256').update(text, 'utf8').digest('hex');
 }
@@ -133,15 +146,16 @@ function newMutationId() {
 }
 
 // The only way lastDiskText is ever assigned: the hash is what persistence
-// writes, and hashing at assignment (rare: open, reconcile, flush) keeps the
+// writes, and hashing at assignment (rare: open, reconcile, materialize) keeps the
 // full-text SHA-256 off the per-batch persist path. `origin` says how the
 // text got onto disk — 'disk' (external write folded in), 'flush' (the live
-// doc's own write-back), 'open' (seed of an unchanged file) — and is what the
+// doc's own native materialization), 'open' (seed of an unchanged file) — and is what the
 // overwrite guard reads: a 'flush' head means the last disk state was
 // produced through the live channel.
-function setLastDiskText(entry, text, origin) {
+function setLastDiskText(entry, text, origin, observation = null) {
   entry.lastDiskText = text;
   entry.lastDiskHash = text == null ? null : hashText(text);
+  entry.lastDiskObservation = observation;
   if (text != null) pushDiskHistory(entry, text, entry.lastDiskHash, origin || 'disk');
 }
 
@@ -154,7 +168,6 @@ function pushDiskHistory(entry, text, sha256, origin) {
   const history = entry.diskHistory;
   const head = history[history.length - 1];
   if (head && head.sha256 === sha256) {
-    head.seq = currentSeq();
     head.at = Date.now();
     return;
   }
@@ -286,21 +299,48 @@ function isLowSurrogate(code) {
   return code >= 0xdc00 && code <= 0xdfff;
 }
 
+function resetMutationAuthor(Y, entry) {
+  entry.mutationAuthor?.destroy();
+  entry.mutationAuthor = new Y.Doc();
+  Y.applyUpdate(
+    entry.mutationAuthor,
+    Y.encodeStateAsUpdate(entry.doc),
+    { amalgmMutation: true, source: 'doc:author-reset', patch: null },
+  );
+}
+
 /**
- * Splice `nextText` into the live doc and hand back the exact update it
- * produced, ready for commitDocMutation. The live doc's own clientID keeps
- * the Yjs state vector at one entry per open session — a fresh doc per splice
- * would grow it forever. The in-memory apply preceding the journal insert is
- * safe: nothing persists before materialization, so a death in the gap leaves
- * disk ahead of the persisted state and reopen simply re-reconciles (a write
- * API caller got no acknowledgement and retries). Returns null when the text
- * is already current.
+ * Produce the exact update for a whole-text change without touching the live
+ * document. One stable author is mirrored from the live document before each
+ * splice, so its Yjs client clock stays bounded. commitDocMutation is the only
+ * place that applies the bytes, after the durable mutation row exists.
  */
-function spliceDocText(Y, entry, nextText, source, mutationId = newMutationId()) {
+function spliceDocText(
+  Y,
+  entry,
+  nextText,
+  source,
+  mutationId = newMutationId(),
+  diskObservation = null,
+) {
+  if (!entry.mutationAuthor) resetMutationAuthor(Y, entry);
+  Y.applyUpdate(
+    entry.mutationAuthor,
+    Y.encodeStateAsUpdate(entry.doc),
+    { amalgmMutation: true, source: 'doc:author-mirror', patch: null },
+  );
+  const ytext = entry.mutationAuthor.getText(TEXT_KEY);
+  if (ytext.toString() === nextText) return null;
+  const before = Y.encodeStateVector(entry.mutationAuthor);
   const origin = { amalgmMutation: true, source, patch: null };
-  const changed = spliceTextInto(Y, entry.doc, entry.doc.getText(TEXT_KEY), nextText, origin);
-  if (!changed) return null;
-  return { mutationId, update: origin.patch.yjs, bytes: null };
+  spliceTextInto(Y, entry.mutationAuthor, ytext, nextText, origin);
+  const bytes = Buffer.from(Y.encodeStateAsUpdate(entry.mutationAuthor, before));
+  return {
+    mutationId,
+    update: bytes.toString('base64'),
+    bytes,
+    diskObservation,
+  };
 }
 
 function canCurrentUserEditDoc(entry) {
@@ -313,23 +353,123 @@ function requireCurrentUserDocEdit(entry) {
   if (!canCurrentUserEditDoc(entry)) throw invalid('document edit is forbidden', 403);
 }
 
+function localMutationInput(entry, replica, edit) {
+  return {
+    channelId: replica ? `resource:${replica.resourceId}` : entry.resource,
+    localResource: entry.resource,
+    sharedResourceId: replica?.resourceId,
+    mutationId: edit.mutationId,
+    deviceId: replica ? require('../workspace/identity').machineId() : null,
+    authorityEpoch: replica?.authorityEpoch || 0,
+    baseCloudVersion: replica?.appliedVersion || 0,
+    contract: replica?.contract || 'text-yjs@1',
+    schemaVersion: replica?.schemaVersion || 1,
+    operationKind: 'yjs.update',
+    operation: { kind: 'yjs.update', update: edit.update },
+  };
+}
+
+function materializeDocDiskMutation(
+  Y,
+  entry,
+  mutation,
+  testHooks = {},
+) {
+  const targetText = entry.doc.getText(TEXT_KEY).toString();
+  let plan = docDisk.prepare(mutation.channelId, mutation.mutationId, targetText);
+  for (let attempt = 0; attempt < 8; attempt += 1) {
+    const result = docDisk.cross(plan, openLocalDb(), testHooks);
+    trace('doc-disk-cross', {
+      mutationId: mutation.mutationId,
+      attempt,
+      status: result.status,
+      reason: result.reason,
+      target: hashText(targetText),
+    });
+    if (result.status === 'applied') {
+      const installed = docDisk.observe(entry.path);
+      if (installed.text !== targetText) {
+        // The receipt proves this mutation crossed. A different current file
+        // is therefore causally later local reality, including the narrow
+        // helper-return/process-crash window. Journal it as the successor
+        // before allowing the older mutation to complete.
+        const successor = stageDiskObservation(Y, entry, installed, {
+          predecessorChannelId: mutation.channelId,
+          predecessorMutationId: mutation.mutationId,
+          predecessorCrossed: true,
+        });
+        setLastDiskText(entry, installed.text, 'disk', installed);
+        persistDocState(Y, entry);
+        return {
+          crossed: true,
+          superseded: false,
+          successor,
+        };
+      }
+      setLastDiskText(
+        entry,
+        installed.text,
+        plan.mutationSource === 'doc:disk' ? 'disk' : 'flush',
+        installed,
+      );
+      persistDocState(Y, entry);
+      return { crossed: true, superseded: false };
+    }
+    if (result.status === 'pending') {
+      plan = docDisk.get(mutation.channelId, mutation.mutationId);
+      if (attempt < 7) continue;
+      throw new Error(
+        `document disk writer is still active: ${entry.path}: ${result.reason || 'pending'}`,
+      );
+    }
+    if (result.status !== 'changed') {
+      throw new Error(`unexpected document disk transaction state: ${result.status}`);
+    }
+    const newer = docDisk.observe(entry.path);
+    if (newer.text === targetText) {
+      plan = docDisk.rebaseExpected(mutation.channelId, mutation.mutationId, newer);
+      continue;
+    }
+    const successor = stageDiskObservation(Y, entry, newer, {
+      predecessorChannelId: mutation.channelId,
+      predecessorMutationId: mutation.mutationId,
+    });
+    if (!successor) {
+      plan = docDisk.rebaseExpected(mutation.channelId, mutation.mutationId, newer);
+      continue;
+    }
+    return { crossed: false, superseded: true, successor };
+  }
+  throw new Error(`document disk kept changing during materialization: ${entry.path}`);
+}
+
 /**
  * The one door. Every locally produced document edit — a client Yjs update,
  * a whole-text API write, a disk reconcile — becomes exactly one journal
  * mutation: durable row, then materialization, then the projected event;
- * shared docs land in the cloud outbox by the same row. `bytes` is null when
- * the update came from spliceDocText — the live doc already holds it and
- * materialization only persists; client updates arrive as bytes and are
- * applied here. `entry.pendingConflict` (set by the merge that produced this
- * edit) rides the projected event and is consumed here.
+ * shared docs land in the cloud outbox by the same row. Updates arrive as
+ * bytes and are applied here only after that row exists. `entry.pendingConflict`
+ * (set by the merge that produced this edit) rides the projected event and
+ * is consumed here.
  */
-function commitDocMutation(Y, entry, { mutationId, update, bytes }, source) {
-  // Finish before starting: a journal row whose materialization failed (a
-  // full disk, a permission flip) is completed here — original mutation id,
-  // event, cloud-outbox eligibility — before any new edit is journaled. This
-  // is what keeps journal order and the cloud stream gap-free; if the disk is
-  // still broken, the new edit fails too instead of shipping past a hole.
-  recoverPendingDocMutations(Y, entry);
+function commitDocMutation(
+  Y,
+  entry,
+  {
+    mutationId,
+    update,
+    bytes,
+    diskObservation = null,
+    materializationBase = null,
+  },
+  source,
+) {
+  // A local file save is full local reality before the API or cloud edit that
+  // races it. Capture it durably first. The disk-origin path already carries
+  // that exact observation and must not recurse through capture.
+  const capturedBase = diskObservation
+    || materializationBase
+    || (source === 'doc:disk' ? null : captureDiskBeforeMutation(Y, entry));
   const replica = require('./replicas').getReplicaByLocalResource(entry.resource);
   trace('doc-commit', {
     mutationId,
@@ -338,39 +478,53 @@ function commitDocMutation(Y, entry, { mutationId, update, bytes }, source) {
     shared: replica?.resourceId,
   });
   const origin = { amalgmMutation: true, source, patch: null };
-  return require('./mutations').commitLocalMutation({
-    channelId: replica ? `resource:${replica.resourceId}` : entry.resource,
-    localResource: entry.resource,
-    sharedResourceId: replica?.resourceId,
-    mutationId,
-    deviceId: replica ? require('../workspace/identity').machineId() : null,
-    authorityEpoch: replica?.authorityEpoch || 0,
-    baseCloudVersion: replica?.appliedVersion || 0,
-    contract: replica?.contract || 'text-yjs@1',
-    schemaVersion: replica?.schemaVersion || 1,
-    operationKind: 'yjs.update',
-    operation: { kind: 'yjs.update', update },
-  }, {
-    materialize() {
-      if (bytes) Y.applyUpdate(entry.doc, new Uint8Array(bytes), origin);
-      persistDocState(Y, entry);
-      if (replica) {
-        // Shared files have a strict saved-local boundary: the user-visible
-        // file is current before the event/HTTP acknowledgement.
-        flushDocToDisk(Y, entry);
-      } else {
-        scheduleDiskWrite(Y, entry);
-      }
-    },
-    event: () => {
-      const patch = origin.patch || { yjs: update };
-      if (entry.pendingConflict) {
-        patch.conflict = entry.pendingConflict;
-        entry.pendingConflict = null;
-      }
-      return { resource: entry.resource, op: 'update', id: entry.path, patch, source };
-    },
-  });
+  const edit = { mutationId, update, bytes, diskObservation };
+  const input = localMutationInput(entry, replica, edit);
+  const base = capturedBase || docDisk.observe(entry.path);
+  let diskOutcome = null;
+  try {
+    const committed = require('./mutations').commitLocalMutation(input, {
+      persist(database, mutation) {
+        docDisk.insertBase(
+          database,
+          mutation,
+          base,
+          source,
+        );
+      },
+      materialize(mutation) {
+        if (bytes) Y.applyUpdate(entry.doc, new Uint8Array(bytes), origin);
+        persistDocState(Y, entry);
+        diskOutcome = materializeDocDiskMutation(
+          Y,
+          entry,
+          mutation,
+          diskTransactionTestHooks,
+        );
+      },
+      event: () => {
+        const patch = origin.patch || { yjs: update };
+        if (entry.pendingConflict) {
+          patch.conflict = entry.pendingConflict;
+          entry.pendingConflict = null;
+        }
+        return { resource: entry.resource, op: 'update', id: entry.path, patch, source };
+      },
+    });
+    docDisk.finish(input.channelId, input.mutationId);
+    if (diskOutcome?.superseded || diskOutcome?.successor) {
+      recoverPendingDocMutations(Y, entry);
+    }
+    return committed;
+  } catch (error) {
+    // The journal row, when one exists, owns recovery. If no row exists, the
+    // unchanged live document (or disk observation) is the retry source. In
+    // either case an author that ran ahead must not make a retry look like a
+    // no-op.
+    entry.pendingConflict = null;
+    resetMutationAuthor(Y, entry);
+    throw error;
+  }
 }
 
 // A merge where every incoming hunk conflicted leaves the doc text unchanged:
@@ -407,58 +561,6 @@ function persistDocState(Y, entry) {
   );
 }
 
-function scheduleDiskWrite(Y, entry) {
-  if (entry.diskWriteTimer) return;
-  entry.diskWriteTimer = setTimeout(() => {
-    entry.diskWriteTimer = null;
-    // The debounced write-back has no caller to answer to. A failure here
-    // loses nothing durable — the acknowledged state lives in SQLite — so it
-    // is logged and the next flush (edit, close, reopen) retries.
-    try {
-      flushDocToDisk(Y, entry);
-    } catch (error) {
-      console.warn(`[LiveDoc] Debounced write-back failed for "${entry.path}":`, error?.message || error);
-    }
-  }, DISK_WRITE_DEBOUNCE_MS);
-  if (typeof entry.diskWriteTimer.unref === 'function') entry.diskWriteTimer.unref();
-}
-
-// Replace-by-rename so the file is always either the old text or the new
-// text, never a torn partial write. The rename replaces the inode, so the
-// original's permission bits must be carried over explicitly — chmod, not an
-// open-mode, because open(2) modes are masked by the umask. An executable
-// script stays executable through a live edit.
-function writeFileAtomic(filePath, text) {
-  const tmpPath = path.join(path.dirname(filePath), `.${path.basename(filePath)}.amalgm-write`);
-  let mode = null;
-  try {
-    mode = fs.statSync(filePath).mode;
-  } catch (error) {
-    if (error.code !== 'ENOENT') throw error;
-  }
-  fs.writeFileSync(tmpPath, text, 'utf8');
-  if (mode != null) fs.chmodSync(tmpPath, mode);
-  fs.renameSync(tmpPath, filePath);
-}
-
-// Throws on failure: "saved locally" must mean the file is really current.
-// Callers that acknowledge an edit (mutation materialization) propagate the
-// failure so the journal row is never completed and no event is projected;
-// only fire-and-forget callers (debounce timer, close) may catch and log.
-function flushDocToDisk(Y, entry) {
-  const text = entry.doc.getText(TEXT_KEY).toString();
-  let onDisk = null;
-  try {
-    onDisk = fs.readFileSync(entry.path, 'utf8');
-  } catch (error) {
-    // A deleted file is not a failed save — the write below recreates it.
-    if (error.code !== 'ENOENT') throw error;
-  }
-  if (onDisk !== text) writeFileAtomic(entry.path, text);
-  setLastDiskText(entry, text, 'flush');
-  persistDocState(Y, entry);
-}
-
 function isConflictSidecar(name) {
   return SIDECAR_NAME_RE.test(name);
 }
@@ -500,31 +602,59 @@ function writeConflictSidecar(entry, theirsText, hunkCount) {
   );
 }
 
-function reconcileFromDisk(Y, entry) {
-  try {
-    const onDisk = fs.readFileSync(entry.path, 'utf8');
-    // Only fold in disk content that actually CHANGED since we last read or
-    // wrote it. Without this, a watcher event firing while the doc is ahead
-    // of disk (write-back still debounced) would "reconcile" the stale disk
-    // text back over live edits. (This is also the THEIRS === BASE no-op.)
-    if (onDisk === entry.lastDiskText) return;
-    if (!canCurrentUserEditDoc(entry)) {
-      entry.heldDiskChange = { reason: 'forbidden', at: new Date().toISOString() };
-      return;
-    }
-    entry.heldDiskChange = null;
-    const ytext = entry.doc.getText(TEXT_KEY);
-    const ours = ytext.toString();
-    const base = entry.lastDiskText;
-    let nextText = onDisk;
-    // OURS === BASE (no live divergence) or no base at all (first seed):
-    // disk text applies wholesale, exactly as before. Otherwise both sides
-    // moved since the last sync — three-way merge against BASE so a writer
-    // that read the file before our live edits cannot delete them.
-    if (base != null && ours !== base && ours !== onDisk) {
-      const merged = merge3(base, ours, onDisk);
-      nextText = merged.text;
-      if (merged.conflicts.length > 0) {
+function diskEditForObservation(Y, entry, observation) {
+  const onDisk = observation.text;
+  if (onDisk === null) return null;
+  if (
+    onDisk === entry.lastDiskText
+    && (
+      !entry.lastDiskObservation
+      || docDisk.sameObservation(observation, entry.lastDiskObservation)
+    )
+  ) return null;
+  const ytext = entry.doc.getText(TEXT_KEY);
+  const ours = ytext.toString();
+  // Synchronous materialization means the newest history value may be a
+  // local Yjs edit that a filesystem writer never read. When that writer
+  // replaces the file from the immediately preceding disk version, merge
+  // against that predecessor just as the former debounce window did.
+  const history = entry.diskHistory;
+  const prior = history.length > 1 ? history[history.length - 2] : null;
+  const base = liveEditsSinceLastDiskState(entry) && prior
+    ? prior.text
+    : entry.lastDiskText;
+  let nextText = onDisk;
+  if (
+    base != null
+    && ours !== base
+    && ours !== onDisk
+    && overwriteDeletesText(ours, onDisk)
+  ) {
+    const merged = merge3(base, ours, onDisk);
+    nextText = merged.text;
+    if (merged.conflicts.length > 0) {
+      const conflictedOursBytes = merged.conflicts.reduce(
+        (total, conflict) => total + Buffer.byteLength(conflict.ours, 'utf8'),
+        0,
+      );
+      const oursBytes = Math.max(1, Buffer.byteLength(ours, 'utf8'));
+      if (conflictedOursBytes / oursBytes >= 0.8) {
+        // A raw filesystem writer is allowed to replace the whole file. Keep
+        // its rewrite in the main artifact while preserving the displaced
+        // live value and surfacing the loss boundary.
+        nextText = onDisk;
+        const sidecarPath = writePreservationSidecar(
+          entry,
+          ours,
+          'unversioned disk write replaced flushed live edits; '
+          + 'replaced text preserved in the sidecar',
+        );
+        entry.pendingConflict = {
+          reason: 'unversioned-overwrite',
+          sidecarPath,
+          at: new Date().toISOString(),
+        };
+      } else {
         const sidecarPath = writeConflictSidecar(entry, onDisk, merged.conflicts.length);
         entry.pendingConflict = {
           reason: 'overlapping-hunks',
@@ -533,52 +663,181 @@ function reconcileFromDisk(Y, entry) {
           at: new Date().toISOString(),
         };
       }
-    } else if (liveEditsSinceLastDiskState(entry) && overwriteDeletesText(ours, onDisk)) {
-      // Wholesale accept, but the incoming write DELETES text that arrived
-      // through the live channel and was already flushed (ours ===
-      // lastDiskText, so the merge gate above sees no divergence — this was
-      // the silent-loss window). A raw fs write carries no base, so lineage
-      // is genuinely ambiguous: the writer keeps the freedom to rewrite the
-      // file, but the replaced live text is preserved first and the
-      // overwrite is surfaced, never silent. An insertion-only write (a vim
-      // append, a new paragraph) destroys nothing and applies silently.
-      const sidecarPath = writePreservationSidecar(
-        entry,
-        ours,
-        'unversioned disk write replaced flushed live edits; '
-        + 'replaced text preserved in the sidecar',
-      );
-      entry.pendingConflict = {
-        reason: 'unversioned-overwrite',
-        sidecarPath,
-        at: new Date().toISOString(),
-      };
     }
-    setLastDiskText(entry, onDisk, 'disk');
-    const edit = spliceDocText(Y, entry, nextText, 'doc:disk');
-    if (edit) {
-      // The external edit walks through the same door as a client mutation:
-      // journal row, materialization (which writes any merged text back — the
-      // file artifact follows the doc), event, and the cloud outbox when the
-      // doc is shared.
-      commitDocMutation(Y, entry, edit, 'doc:disk');
-    } else {
+  } else if (liveEditsSinceLastDiskState(entry) && overwriteDeletesText(ours, onDisk)) {
+    const sidecarPath = writePreservationSidecar(
+      entry,
+      ours,
+      'unversioned disk write replaced flushed live edits; '
+      + 'replaced text preserved in the sidecar',
+    );
+    entry.pendingConflict = {
+      reason: 'unversioned-overwrite',
+      sidecarPath,
+      at: new Date().toISOString(),
+    };
+  }
+  return spliceDocText(
+    Y,
+    entry,
+    nextText,
+    'doc:disk',
+    newMutationId(),
+    observation,
+  );
+}
+
+function isKnownDiskObservation(entry, observation) {
+  return Boolean(
+    observation.text !== null
+    && observation.text === entry.lastDiskText
+    && (
+      !entry.lastDiskObservation
+      || docDisk.sameObservation(observation, entry.lastDiskObservation)
+    )
+  );
+}
+
+function holdDiskObservation(entry, observation, reason) {
+  entry.heldDiskChange = {
+    reason,
+    identity: observation.identity,
+    at: new Date().toISOString(),
+  };
+  throw invalid(`document disk change is held: ${reason}`, 409);
+}
+
+function stageDiskObservation(Y, entry, observation, options = {}) {
+  if (isKnownDiskObservation(entry, observation)) {
+    entry.heldDiskChange = null;
+    return null;
+  }
+  if (observation.text === null) {
+    return holdDiskObservation(entry, observation, 'missing');
+  }
+  if (!canCurrentUserEditDoc(entry)) {
+    return holdDiskObservation(entry, observation, 'forbidden');
+  }
+  entry.heldDiskChange = null;
+  let edit = diskEditForObservation(Y, entry, observation);
+  if (!edit) {
+    if (entry.pendingConflict) {
+      const bytes = Buffer.from(Y.encodeStateAsUpdate(entry.doc));
+      edit = {
+        mutationId: newMutationId(),
+        update: bytes.toString('base64'),
+        bytes,
+        diskObservation: observation,
+      };
+    } else if (observation.text === entry.doc.getText(TEXT_KEY).toString()) {
+      setLastDiskText(entry, observation.text, 'disk', observation);
       publishConflictOnly(entry, 'doc:disk');
-      // Even a no-op still refreshed lastDiskText; record its hash.
       persistDocState(Y, entry);
+    } else {
+      return null;
+    }
+    if (!edit) return null;
+  }
+  const replica = require('./replicas').getReplicaByLocalResource(entry.resource);
+  const input = localMutationInput(entry, replica, edit);
+  const persist = (database, mutation) => {
+    docDisk.insertBase(database, mutation, observation, 'doc:disk');
+    if (options.predecessorChannelId && options.predecessorMutationId) {
+      if (options.predecessorCrossed) {
+        docDisk.linkCrossedSuccessor(
+          database,
+          options.predecessorChannelId,
+          options.predecessorMutationId,
+          mutation.channelId,
+          mutation.mutationId,
+        );
+      } else {
+        docDisk.markSuperseded(
+          database,
+          options.predecessorChannelId,
+          options.predecessorMutationId,
+          mutation.channelId,
+          mutation.mutationId,
+        );
+      }
     }
+  };
+  if (!options.predecessorChannelId && !options.predecessorMutationId) {
+    return {
+      edit,
+      input,
+      committed: commitDocMutation(Y, entry, edit, 'doc:disk'),
+    };
+  }
+  const started = require('./mutations').journalMutation(input, {
+    persist(database, mutation) {
+      persist(database, mutation);
+    },
+  });
+  return { edit, input, mutation: started.mutation };
+}
+
+function captureDiskBeforeMutation(Y, entry) {
+  // A snapshot helper can die after installing official bytes but before the
+  // in-memory document and cursor commit. Recover that physical receipt first;
+  // otherwise a cached entry can mistake those official bytes for a new local
+  // save and publish an echo before the snapshot is replayed.
+  recoverPendingDocSnapshots(Y, entry);
+  recoverPendingDocMutations(Y, entry);
+  for (let attempt = 0; attempt < 8; attempt += 1) {
+    const observation = docDisk.observe(entry.path);
+    const staged = stageDiskObservation(Y, entry, observation);
+    if (!staged) {
+      // Return the exact observation whose provenance was just proved. A
+      // later reread could contain an unjournaled save and must never become
+      // overwrite permission for the caller's native CAS.
+      return observation;
+    }
+    recoverPendingDocMutations(Y, entry);
+  }
+  throw new Error(`document disk kept changing during capture: ${entry.path}`);
+}
+
+function reconcileFromDisk(Y, entry, strict = false) {
+  try {
+    captureDiskBeforeMutation(Y, entry);
   } catch (error) {
-    // File deleted or unreadable — the doc simply stops following the disk.
+    if (strict) throw error;
     console.warn(`[LiveDoc] Reconcile from disk failed for "${entry.path}":`, error?.message || error);
   }
 }
 
+function restoreDurableDiskBase(entry, persisted) {
+  const plan = docDisk.firstBase(entry.resource);
+  if (plan?.baseText !== null && plan?.baseText !== undefined) {
+    // Every destructive writer seals its exact semantic predecessor beside
+    // the physical CAS. That text remains the merge base even when a crash
+    // happens after the desired Y.Doc state was persisted but before the
+    // file crossed.
+    setLastDiskText(entry, plan.baseText, 'open');
+    return true;
+  }
+
+  const knownHash = persisted?.last_disk_hash;
+  if (!knownHash) return false;
+  const persistedText = entry.doc.getText(TEXT_KEY).toString();
+  if (hashText(persistedText) !== knownHash) return false;
+
+  // The persisted Y.Doc and last-disk hash together prove the semantic base
+  // that was on disk before the process stopped. The file may have changed
+  // since then, so this is merge provenance—not permission to replace its
+  // current inode. Physical permission still comes only from the durable
+  // plan's expected identity and the native CAS.
+  setLastDiskText(entry, persistedText, 'open');
+  return true;
+}
+
 /**
  * First look at the disk after (re)opening a doc. Three cases:
  *  - no persisted history → the disk seeds the doc (first ever open);
  *  - disk matches the hash we recorded before dying → disk is unchanged;
- *    if the persisted doc is ahead (edits inside the unflushed debounce
- *    window), write the doc back out instead of splicing stale disk text
+ *    if the persisted doc is ahead (an interrupted journal-owned file
+ *    transaction), finish that durable mutation instead of splicing stale disk text
  *    over those edits;
  *  - disk differs from the recorded hash → a genuine external edit while we
  *    were closed; fold it in like any other disk change.
@@ -588,10 +847,11 @@ function seedFromDisk(Y, entry, persisted) {
   if (!knownHash) {
     if (!canCurrentUserEditDoc(entry)) {
       try {
-        const onDisk = fs.readFileSync(entry.path, 'utf8');
+        const observation = docDisk.observe(entry.path);
+        const onDisk = observation.text;
         const origin = { amalgmMutation: true, source: 'doc:read-only-seed', patch: null };
         spliceTextInto(Y, entry.doc, entry.doc.getText(TEXT_KEY), onDisk, origin);
-        setLastDiskText(entry, onDisk, 'open');
+        setLastDiskText(entry, onDisk, 'open', observation);
         persistDocState(Y, entry);
       } catch {
         // Unreadable/deleted: same posture as reconcile — stop following disk.
@@ -602,8 +862,10 @@ function seedFromDisk(Y, entry, persisted) {
     return;
   }
   let onDisk = null;
+  let observation = null;
   try {
-    onDisk = fs.readFileSync(entry.path, 'utf8');
+    observation = docDisk.observe(entry.path);
+    onDisk = observation.text;
   } catch {
     // Unreadable/deleted: same posture as reconcile — stop following disk.
     return;
@@ -612,9 +874,15 @@ function seedFromDisk(Y, entry, persisted) {
     reconcileFromDisk(Y, entry);
     return;
   }
-  setLastDiskText(entry, onDisk, 'open');
+  setLastDiskText(entry, onDisk, 'open', observation);
   if (entry.doc.getText(TEXT_KEY).toString() !== onDisk) {
-    scheduleDiskWrite(Y, entry);
+    const bytes = Buffer.from(Y.encodeStateAsUpdate(entry.doc));
+    commitDocMutation(Y, entry, {
+      mutationId: newMutationId(),
+      update: bytes.toString('base64'),
+      bytes,
+      diskObservation: observation,
+    }, 'doc:recovery');
   }
 }
 
@@ -627,6 +895,35 @@ function scheduleReconcile(Y, entry) {
   if (typeof entry.reconcileTimer.unref === 'function') entry.reconcileTimer.unref();
 }
 
+/**
+ * Filesystem notifications make ordinary edits fast, but they are not
+ * durable evidence. This bounded pass makes every open document converge
+ * even when the operating system coalesces or drops a notification.
+ */
+function verifyOpenDocs() {
+  watchVerificationPasses += 1;
+  const Y = loadYjs();
+  for (const entry of openDocs.values()) {
+    if (isInternalStateDoc(entry.path)) continue;
+    reconcileFromDisk(Y, entry);
+    if (!dirWatchers.has(path.dirname(entry.path))) watchDocFile(Y, entry);
+  }
+}
+
+function ensureWatchVerification() {
+  if (watchVerificationTimer || openDocs.size === 0) return;
+  watchVerificationTimer = setInterval(verifyOpenDocs, WATCH_VERIFY_MS);
+  if (typeof watchVerificationTimer.unref === 'function') {
+    watchVerificationTimer.unref();
+  }
+}
+
+function stopWatchVerificationIfIdle() {
+  if (openDocs.size > 0 || !watchVerificationTimer) return;
+  clearInterval(watchVerificationTimer);
+  watchVerificationTimer = null;
+}
+
 function watchDocFile(Y, entry) {
   const dir = path.dirname(entry.path);
   let shared = dirWatchers.get(dir);
@@ -674,36 +971,36 @@ function unwatchDocFile(entry) {
 }
 
 function closeDocEntry(Y, entry) {
-  if (entry.diskWriteTimer) {
-    clearTimeout(entry.diskWriteTimer);
-    entry.diskWriteTimer = null;
-  }
   if (entry.reconcileTimer) {
     clearTimeout(entry.reconcileTimer);
     entry.reconcileTimer = null;
   }
-  // Close must complete even when the disk is unwritable: every acknowledged
-  // edit is already durable in SQLite, and reopen flushes the file current.
-  try {
-    flushDocToDisk(Y, entry);
-  } catch (error) {
-    console.warn(`[LiveDoc] Close flush failed for "${entry.path}":`, error?.message || error);
-  }
+  // Capture a last-moment external save before closing. If journaling fails,
+  // leave that disk value untouched; reopen sees it as unknown input and
+  // retries. Close is still allowed to release memory.
+  if (!isInternalStateDoc(entry.path)) reconcileFromDisk(Y, entry);
   unwatchDocFile(entry);
   for (const alias of entry.pathAliases) resolvedPathCache.delete(alias);
+  entry.mutationAuthor?.destroy();
   entry.doc.destroy();
   openDocs.delete(entry.path);
+  stopWatchVerificationIfIdle();
 }
 
 function recoverPendingDocMutations(Y, entry) {
-  const pending = require('./mutations').listMutations({ state: 'saving-local', limit: 1000 })
-    .filter((mutation) => mutation.localResource === entry.resource);
-  for (const mutation of pending) {
+  const mutations = require('./mutations');
+  for (let pass = 0; pass < 1000; pass += 1) {
+    const [mutation] = mutations.listMutations({
+      state: 'saving-local',
+      localResource: entry.resource,
+      limit: 1,
+    });
+    if (!mutation) return;
     if (
       mutation.operationKind !== 'yjs.update'
       || typeof mutation.operation?.update !== 'string'
     ) {
-      continue;
+      throw new Error(`document mutation ${mutation.mutationId} has an unsupported operation`);
     }
     const bytes = Buffer.from(mutation.operation.update, 'base64');
     try {
@@ -712,11 +1009,52 @@ function recoverPendingDocMutations(Y, entry) {
       throw invalid(`cannot recover mutation ${mutation.mutationId}: ${error?.message || error}`, 500);
     }
     const origin = { amalgmMutation: true, source: 'recovery', patch: null };
+    const beforeMutationText = entry.doc.getText(TEXT_KEY).toString();
     Y.applyUpdate(entry.doc, new Uint8Array(bytes), origin);
     persistDocState(Y, entry);
-    if (mutation.sharedResourceId) flushDocToDisk(Y, entry);
-    else scheduleDiskWrite(Y, entry);
-    require('./mutations').completeMaterializedMutation(
+    let plan = docDisk.get(mutation.channelId, mutation.mutationId);
+    if (!plan) {
+      // Legacy saving-local rows predate physical plans. The current file may
+      // be a newer save, so make it the old plan's base and immediately ask
+      // the ordinary disk detector whether it is a successor. Only an
+      // unchanged predecessor may then be replaced.
+      const base = docDisk.observe(entry.path);
+      if (entry.lastDiskText === null) {
+        setLastDiskText(entry, beforeMutationText, 'open');
+      }
+      docDisk.insertBase(openLocalDb(), mutation, base, 'doc:recovery');
+      stageDiskObservation(Y, entry, base, {
+        predecessorChannelId: mutation.channelId,
+        predecessorMutationId: mutation.mutationId,
+      });
+      plan = docDisk.get(mutation.channelId, mutation.mutationId);
+    }
+    const ownsSuccessor = (
+      plan.successorChannelId !== null
+      && plan.successorMutationId !== null
+    );
+    if (plan.state === 'superseded' || (plan.state === 'crossed' && ownsSuccessor)) {
+      const successor = mutations.getMutation(
+        plan.successorChannelId,
+        plan.successorMutationId,
+        { revealOperation: true },
+      );
+      if (!successor) {
+        throw new Error(`document mutation ${mutation.mutationId} lost its disk successor`);
+      }
+      // A crossed predecessor with a linked successor has already proved both
+      // sides of the handoff. Re-running its physical materializer would
+      // observe the successor as a new edit and assign the same save a second
+      // birth certificate.
+    } else {
+      materializeDocDiskMutation(
+        Y,
+        entry,
+        mutation,
+        diskTransactionTestHooks,
+      );
+    }
+    mutations.completeMaterializedMutation(
       mutation.channelId,
       mutation.mutationId,
       {
@@ -724,10 +1062,37 @@ function recoverPendingDocMutations(Y, entry) {
         op: 'update',
         id: entry.path,
         patch: origin.patch || { yjs: mutation.operation.update },
-        source: mutation.origin === 'cloud' ? 'doc:cloud-recovery' : 'doc:recovery',
+        source: mutation.origin === 'cloud'
+          ? 'doc:cloud-recovery'
+          : plan.mutationSource === 'doc:disk'
+            ? 'doc:disk'
+            : 'doc:recovery',
         resourceVersion: mutation.officialCloudVersion,
       },
     );
+    docDisk.finish(mutation.channelId, mutation.mutationId);
+  }
+  throw new Error(`document mutation recovery exceeded its finite bound: ${entry.path}`);
+}
+
+function releaseCompletedDocPlans(entry) {
+  const mutations = require('./mutations');
+  for (const plan of docDisk.listMutations(entry.resource)) {
+    const mutation = mutations.getMutation(
+      plan.channelId,
+      plan.mutationId,
+      { revealOperation: true },
+    );
+    if (!mutation) {
+      // Retention may prune a completed mutation after its event is durable
+      // but before a crash-left receipt is released. The plan itself proves
+      // whether it crossed; finish still rejects an incomplete orphan.
+      docDisk.finish(plan.channelId, plan.mutationId);
+      continue;
+    }
+    if (mutation.state !== 'saving-local') {
+      docDisk.finish(plan.channelId, plan.mutationId);
+    }
   }
 }
 
@@ -783,13 +1148,13 @@ function loadDocEntry(pathInput) {
     nodeId,
     doc,
     reconcileTimer: null,
-    diskWriteTimer: null,
     lastAccess: Date.now(),
     // The disk text as of our last read/write; reconcile skips anything that
     // hasn't changed past it (see reconcileFromDisk). Assigned only through
     // setLastDiskText so the hash that persistence writes stays in step.
     lastDiskText: null,
     lastDiskHash: null,
+    lastDiskObservation: null,
     // Bounded ring of recent disk-sync states {text, sha256, seq, at, origin}
     // (see pushDiskHistory): the base-resolution window for versioned writes
     // and the live-edit detector for unversioned overwrites. Newest last.
@@ -798,19 +1163,26 @@ function loadDocEntry(pathInput) {
     // consumed by the very next disk-origin update event (the merge splice is
     // synchronous) so the conflict rides the doc's own event patch.
     pendingConflict: null,
+    // Whole-text changes are generated by one stable Yjs writer but do not
+    // touch the live doc until their mutation row exists.
+    mutationAuthor: null,
     // Every pathInput form seen for this doc, so close can clear its
     // resolvedPathCache entries.
     pathAliases: new Set([pathInput]),
   };
 
-  let persisted = nodeId
-    ? cachedStatement(database, `
+  const readPersisted = () => (
+    nodeId
+      ? cachedStatement(database, `
       SELECT state, last_disk_hash FROM doc_states
       WHERE node_id = ? OR path = ?
       ORDER BY CASE WHEN node_id = ? THEN 0 ELSE 1 END
       LIMIT 1
     `).get(nodeId, resolved, nodeId) || null
-    : cachedStatement(database, 'SELECT state, last_disk_hash FROM doc_states WHERE path = ?').get(resolved) || null;
+      : cachedStatement(database, 'SELECT state, last_disk_hash FROM doc_states WHERE path = ?')
+        .get(resolved) || null
+  );
+  let persisted = readPersisted();
   if (persisted?.state) {
     try {
       Y.applyUpdate(doc, new Uint8Array(persisted.state), 'persisted');
@@ -833,33 +1205,52 @@ function loadDocEntry(pathInput) {
     origin.patch = { yjs: Buffer.from(update).toString('base64') };
   });
 
-  // Disk at open: an externally changed file folds in as an edit, but a file
-  // that merely lags our persisted state (the process died inside the disk
-  // write debounce) gets the doc written back out — never spliced over it.
-  seedFromDisk(Y, entry, persisted);
-  if (nodeId) {
-    cachedStatement(database, 'UPDATE doc_states SET node_id = ?, path = ? WHERE node_id = ? OR path = ?')
-      .run(nodeId, resolved, nodeId, resolved);
-  }
+  // Journal completion and native-receipt release are separately durable.
+  // A crash between them leaves a harmless receipt, which is released here
+  // before any new plan can accumulate beside it.
+  releaseCompletedDocPlans(entry);
+
+  // Restore the last proven semantic disk base before any durable recovery.
+  // A pending official row and a disjoint save made while this process was
+  // down must both derive from the exact text sealed in its physical plan;
+  // the persisted hash is only the legacy fallback.
+  restoreDurableDiskBase(entry, persisted);
+
+  // A crash may leave an official snapshot physically crossed but not yet
+  // registered. Finish that recorded plan before ordinary disk seeding can
+  // misclassify its bytes as a new local edit.
+  recoverPendingDocSnapshots(Y, entry);
 
   // A process can die after the durable journal insert but before Y.Doc/file
   // materialization or event projection. Replay those exact operation IDs
-  // before this open is acknowledged, so a restart cannot bury an edit.
+  // before ordinary disk seeding. Otherwise a successor already owned by a
+  // pending row can look like a fresh save and receive a second mutation ID.
   try {
     recoverPendingDocMutations(Y, entry);
   } catch (error) {
-    if (entry.diskWriteTimer) clearTimeout(entry.diskWriteTimer);
     if (entry.reconcileTimer) clearTimeout(entry.reconcileTimer);
     doc.destroy();
     throw error;
   }
 
+  // Disk at open: an externally changed file folds in as an edit, but a file
+  // that merely lags our persisted state is recovered from the journal first.
+  // Re-read the hash because recovery above may have advanced both the live
+  // document and its exact physical provenance.
+  persisted = readPersisted();
+  seedFromDisk(Y, entry, persisted);
+  if (nodeId) {
+    cachedStatement(database, 'UPDATE doc_states SET node_id = ?, path = ? WHERE node_id = ? OR path = ?')
+      .run(nodeId, resolved, nodeId, resolved);
+  }
+
   evictIfNeeded(Y);
   openDocs.set(resolved, entry);
   // Protocol documents are written only through this module. Watching their
-  // own atomic flush as if it were an external user edit creates a second
+  // own native materialization as if it were an external user edit creates a second
   // concurrent mutation of the same value.
   if (!isInternalStateDoc(resolved)) watchDocFile(Y, entry);
+  ensureWatchVerification();
   resolvedPathCache.set(pathInput, resolved);
   return entry;
 }
@@ -950,12 +1341,10 @@ function writeDocText(pathInput, textInput, options = {}) {
   const entry = loadDocEntry(pathInput);
   entry.lastAccess = Date.now();
   requireCurrentUserDocEdit(entry);
-  // Every respond() below acknowledges saved state, so it must stand on a
-  // settled journal — most pointedly the noop return: a retry of a write
-  // whose disk flush failed finds the text already in memory, and without
-  // this the original mutation would stay stuck while the caller is told all
-  // is well. (Edits that DO reach commitDocMutation settle there.)
-  recoverPendingDocMutations(Y, entry);
+  // A dropped watcher cannot make a direct disk save disappear under this
+  // API write. Capture and materialize every unexplained byte first, then
+  // derive the merge from the resulting live state.
+  const materializationBase = captureDiskBeforeMutation(Y, entry);
   const ytext = entry.doc.getText(TEXT_KEY);
   const ours = ytext.toString();
 
@@ -1021,9 +1410,29 @@ function writeDocText(pathInput, textInput, options = {}) {
 
   entry.pendingConflict = conflict;
   const edit = spliceDocText(Y, entry, nextText, 'doc:write', mutationId);
-  if (edit) commitDocMutation(Y, entry, edit, 'doc:write');
+  if (edit) {
+    if (diskTransactionTestHooks.pauseAfterEditBeforeJournal > 0) {
+      Atomics.wait(
+        new Int32Array(new SharedArrayBuffer(4)),
+        0,
+        0,
+        diskTransactionTestHooks.pauseAfterEditBeforeJournal,
+      );
+    }
+    commitDocMutation(
+      Y,
+      entry,
+      { ...edit, materializationBase },
+      'doc:write',
+    );
+  }
   else publishConflictOnly(entry, 'doc:write');
-  return respond(merge, nextText, conflict, edit?.mutationId || null);
+  return respond(
+    merge,
+    entry.doc.getText(TEXT_KEY).toString(),
+    conflict,
+    edit?.mutationId || null,
+  );
 }
 
 function normalizeDocMutations(Y, mutationsInput) {
@@ -1059,6 +1468,7 @@ function applyDocMutations(pathInput, mutationsInput) {
   const entry = loadDocEntry(pathInput);
   entry.lastAccess = Date.now();
   requireCurrentUserDocEdit(entry);
+  captureDiskBeforeMutation(Y, entry);
   const results = mutations.map((mutation) => commitDocMutation(Y, entry, mutation, 'doc:update'));
 
   return {
@@ -1093,18 +1503,30 @@ function applyCloudDocMutation(input) {
   if (entry.resource !== replica.localResource) {
     throw invalid(`shared resource ${envelope.resourceId} local binding changed`, 409);
   }
+  // A save whose watcher was delayed is causally before the incoming cloud
+  // event and must acquire durable local provenance before cloud ingest can
+  // advance the official cursor.
+  const base = captureDiskBeforeMutation(Y, entry);
   const origin = { amalgmMutation: true, source: 'cloud', patch: null };
-  return require('./mutations').ingestCloudMutation({
+  let diskOutcome = null;
+  const result = require('./mutations').ingestCloudMutation({
     envelope,
     version: input?.version,
     committedAt: input?.committedAt,
     localResource: entry.resource,
   }, {
-    materialize() {
+    persist(database, journaled) {
+      docDisk.insertBase(database, journaled, base, 'doc:cloud');
+    },
+    materialize(journaled) {
       Y.applyUpdate(entry.doc, new Uint8Array(mutation.bytes), origin);
       persistDocState(Y, entry);
-      // Recipient file first; the projected event that wakes its UI follows.
-      flushDocToDisk(Y, entry);
+      diskOutcome = materializeDocDiskMutation(
+        Y,
+        entry,
+        journaled,
+        diskTransactionTestHooks,
+      );
     },
     event: () => ({
       resource: entry.resource,
@@ -1115,10 +1537,233 @@ function applyCloudDocMutation(input) {
       resourceVersion: Number(input.version),
     }),
   });
+  docDisk.finish(`resource:${envelope.resourceId}`, envelope.mutationId);
+  if (diskOutcome?.superseded || diskOutcome?.successor) {
+    recoverPendingDocMutations(Y, entry);
+  }
+  require('../workspace/tree-cloud').reconcileContentOverlay(envelope.resourceId);
+  return result;
+}
+
+function normalizedSnapshotPayload(entry, input, snapshotBase64, checksum) {
+  const envelope = require('./replicas').validateSnapshotEnvelope(input, {
+    contract: 'text-yjs@1',
+    schemaVersion: 1,
+  });
+  return {
+    resourceId: envelope.resourceId,
+    localResource: entry.resource,
+    localPath: entry.path,
+    snapshotBase64,
+    snapshotChecksum: checksum,
+    snapshotVersion: envelope.snapshotVersion,
+    headVersion: envelope.headVersion,
+    authorityEpoch: envelope.authorityEpoch,
+    schemaVersion: envelope.schemaVersion,
+    contract: envelope.contract,
+    journalCursor: isJournalCursor(input?.attachmentJournalCursor)
+      ? input.attachmentJournalCursor
+      : isJournalCursor(input?.journalCursor)
+        ? input.journalCursor
+        : Number(
+          cachedStatement(
+            openLocalDb(),
+            'SELECT COALESCE(MAX(journal_id), 0) AS cursor FROM mutation_journal',
+          ).get().cursor,
+        ),
+  };
+}
+
+function snapshotTargetText(Y, entry, snapshotBase64) {
+  const candidate = new Y.Doc();
+  try {
+    Y.applyUpdate(
+      candidate,
+      Y.encodeStateAsUpdate(entry.doc),
+      { amalgmMutation: true, source: 'snapshot-candidate-base', patch: null },
+    );
+    Y.applyUpdate(
+      candidate,
+      new Uint8Array(Buffer.from(snapshotBase64, 'base64')),
+      { amalgmMutation: true, source: 'snapshot-candidate-official', patch: null },
+    );
+    return candidate.getText(TEXT_KEY).toString();
+  } finally {
+    candidate.destroy();
+  }
+}
+
+function commitSnapshotCursor(Y, entry, plan) {
+  const payload = plan.snapshotPayload;
+  const replicas = require('./replicas');
+  const database = openLocalDb();
+  let event = null;
+  let replica = null;
+  database.transaction(() => {
+    const held = docDisk.get(plan.channelId, plan.mutationId, database);
+    if (!held || held.state !== 'crossed') {
+      throw new Error(`snapshot ${payload.resourceId}@${payload.snapshotVersion} did not cross`);
+    }
+    const existing = replicas.getReplicaByResourceId(payload.resourceId, { database });
+    if (existing && existing.localResource !== entry.resource) {
+      throw invalid(`shared resource ${payload.resourceId} is bound to a different local file`, 409);
+    }
+    if (existing) {
+      replica = replicas.advanceReplicaSnapshot({
+        resourceId: payload.resourceId,
+        snapshotVersion: payload.snapshotVersion,
+        snapshotChecksum: payload.snapshotChecksum,
+        authorityEpoch: payload.authorityEpoch,
+      }, { database });
+    } else {
+      replica = replicas.registerReplica({
+        resourceId: payload.resourceId,
+        localResource: entry.resource,
+        localPath: entry.path,
+        contract: payload.contract,
+        schemaVersion: payload.schemaVersion,
+        authorityEpoch: payload.authorityEpoch,
+        appliedVersion: payload.snapshotVersion,
+        snapshotVersion: payload.snapshotVersion,
+        snapshotChecksum: payload.snapshotChecksum,
+      }, { database }).replica;
+    }
+    // Close the attachment fence. Local edits born after the snapshot plan
+    // began were not in the official snapshot; re-home them onto the newly
+    // installed cloud channel without changing their mutation IDs or local
+    // event order.
+    cachedStatement(database, `
+      UPDATE mutation_journal
+      SET channel_id = ?,
+          shared_resource_id = ?,
+          device_id = COALESCE(device_id, ?),
+          authority_epoch = ?,
+          base_cloud_version = ?,
+          updated_at = ?
+      WHERE local_resource = ?
+        AND shared_resource_id IS NULL
+        AND mutation_origin = 'local'
+        AND journal_id > ?
+    `).run(
+      `resource:${replica.resourceId}`,
+      replica.resourceId,
+      require('../workspace/identity').machineId(),
+      replica.authorityEpoch,
+      replica.snapshotVersion,
+      new Date().toISOString(),
+      entry.resource,
+      payload.journalCursor,
+    );
+    if (held.snapshotEventSeq === null) {
+      event = insertStateEvent(database, {
+        resource: entry.resource,
+        op: 'update',
+        id: entry.path,
+        patch: { yjs: payload.snapshotBase64 },
+        mutationId: plan.mutationId,
+        sharedResourceId: payload.resourceId,
+        source: 'doc:cloud-snapshot',
+        resourceVersion: payload.snapshotVersion,
+      });
+      docDisk.markSnapshotCommitted(
+        plan.channelId,
+        plan.mutationId,
+        event.seq,
+        database,
+      );
+    }
+  })();
+  if (event) publishStateEvent(event);
+  return { replica, event };
+}
+
+function materializeCloudDocSnapshot(Y, entry, initialPlan) {
+  let plan = initialPlan;
+  const payload = plan.snapshotPayload;
+
+  for (let attempt = 0; attempt < 8; attempt += 1) {
+    const targetText = plan.targetContent
+      ? plan.targetContent.toString('utf8')
+      : snapshotTargetText(Y, entry, payload.snapshotBase64);
+    if (!plan.target) {
+      plan = docDisk.prepare(plan.channelId, plan.mutationId, targetText);
+    } else if (plan.targetContent.toString('utf8') !== targetText) {
+      throw new Error(`snapshot ${payload.resourceId}@${payload.snapshotVersion} changed its target`);
+    }
+    const result = docDisk.cross(plan, openLocalDb(), diskTransactionTestHooks);
+    if (result.status === 'pending') {
+      plan = docDisk.get(plan.channelId, plan.mutationId);
+      if (attempt < 7) continue;
+      throw new Error(
+        `snapshot disk writer is still active: ${entry.path}: ${result.reason || 'pending'}`,
+      );
+    }
+    if (result.status === 'changed') {
+      const newer = docDisk.observe(entry.path);
+      if (newer.text === targetText) {
+        plan = docDisk.rebaseExpected(plan.channelId, plan.mutationId, newer);
+        continue;
+      }
+      // No byte was replaced. Retire this physical attempt, capture the newer
+      // save through the ordinary mutation journal, then derive a new target
+      // for the same official snapshot over that overlay.
+      docDisk.cancel(plan.channelId, plan.mutationId);
+      if (attempt === 7) break;
+      plan = planCloudDocSnapshot(Y, entry, payload);
+      continue;
+    }
+    if (result.status !== 'applied') {
+      throw new Error(`unexpected snapshot disk transaction state: ${result.status}`);
+    }
+
+    const origin = { amalgmMutation: true, source: 'cloud-snapshot', patch: null };
+    Y.applyUpdate(
+      entry.doc,
+      new Uint8Array(Buffer.from(payload.snapshotBase64, 'base64')),
+      origin,
+    );
+    // The native receipt proves targetText was installed at the crossing.
+    // A later external save is causally after the snapshot and is captured by
+    // the immediately following reconcile or the restart seed.
+    setLastDiskText(entry, targetText, 'flush');
+    persistDocState(Y, entry);
+    const committed = commitSnapshotCursor(Y, entry, plan);
+    docDisk.finish(plan.channelId, plan.mutationId);
+    reconcileFromDisk(Y, entry, true);
+    require('../workspace/tree-cloud').reconcileContentOverlay(payload.resourceId);
+    return committed;
+  }
+  throw new Error(`document disk kept changing during snapshot install: ${entry.path}`);
+}
+
+function recoverPendingDocSnapshots(Y, entry) {
+  for (let pass = 0; pass < 100; pass += 1) {
+    const plan = docDisk.listSnapshots(entry.resource)[0];
+    if (!plan) return;
+    materializeCloudDocSnapshot(Y, entry, plan);
+  }
+  throw new Error(`snapshot recovery exceeded its finite bound: ${entry.path}`);
+}
+
+function planCloudDocSnapshot(Y, entry, payload) {
+  const base = captureDiskBeforeMutation(Y, entry);
+  if (diskTransactionTestHooks.pauseAfterSnapshotCapture > 0) {
+    Atomics.wait(
+      new Int32Array(new SharedArrayBuffer(4)),
+      0,
+      0,
+      diskTransactionTestHooks.pauseAfterSnapshotCapture,
+    );
+  }
+  return docDisk.insertSnapshotBase(openLocalDb(), payload, base);
 }
 
 function installCloudDocSnapshot(pathInput, input) {
   const Y = loadYjs();
+  const envelope = require('./replicas').validateSnapshotEnvelope(input, {
+    contract: 'text-yjs@1',
+    schemaVersion: 1,
+  });
   const snapshotBase64 = input?.snapshotBase64;
   if (typeof snapshotBase64 !== 'string' || !snapshotBase64) {
     throw invalid('snapshotBase64 is required');
@@ -1131,8 +1776,9 @@ function installCloudDocSnapshot(pathInput, input) {
   } catch (error) {
     throw invalid(`invalid Yjs snapshot: ${error?.message || error}`);
   }
-  const replicas = require('./replicas');
   const entry = loadDocEntry(pathInput);
+  recoverPendingDocSnapshots(Y, entry);
+  const replicas = require('./replicas');
   const existingReplica = replicas.getReplicaByResourceId(input?.resourceId);
   if (existingReplica) {
     // Rehydration: this replica fell behind the pruned official tail, so the
@@ -1142,46 +1788,36 @@ function installCloudDocSnapshot(pathInput, input) {
     if (existingReplica.localResource !== entry.resource) {
       throw invalid(`shared resource ${input?.resourceId} is bound to a different local file`, 409);
     }
-  } else if (entry.doc.getText(TEXT_KEY).toString().length > 0) {
-    throw invalid('cloud snapshot attachment requires an empty local text file', 409);
-  }
-  const origin = { amalgmMutation: true, source: 'cloud-snapshot', patch: null };
-  Y.applyUpdate(entry.doc, new Uint8Array(bytes), origin);
-  persistDocState(Y, entry);
-  flushDocToDisk(Y, entry);
-  const registered = existingReplica
-    ? {
-      replica: replicas.advanceReplicaSnapshot({
-        resourceId: input?.resourceId,
-        snapshotVersion: input?.snapshotVersion,
+    const incomingVersion = envelope.snapshotVersion;
+    if (incomingVersion <= existingReplica.appliedVersion) {
+      const checked = replicas.advanceReplicaSnapshot({
+        resourceId: envelope.resourceId,
+        snapshotVersion: incomingVersion,
         snapshotChecksum: checksum,
-        authorityEpoch: input?.authorityEpoch,
-      }),
+        authorityEpoch: envelope.authorityEpoch,
+      });
+      if (
+        incomingVersion === existingReplica.snapshotVersion
+        && existingReplica.snapshotChecksum === checksum
+      ) {
+        return { replica: checked, event: null, duplicate: true };
+      }
+      return { replica: checked, event: null, duplicate: true, stale: true };
     }
-    : replicas.registerReplica({
-      resourceId: input?.resourceId,
-      localResource: entry.resource,
-      localPath: entry.path,
-      contract: input?.contract,
-      schemaVersion: input?.schemaVersion,
-      authorityEpoch: input?.authorityEpoch,
-      appliedVersion: input?.snapshotVersion,
-      snapshotVersion: input?.snapshotVersion,
-      snapshotChecksum: checksum,
-    });
-  // File and SQLite binding are current before a mounted UI can observe the
-  // snapshot. Applying this full Yjs state is idempotent for an already-open
-  // recipient surface.
-  const event = appendStateEvent({
-    resource: entry.resource,
-    op: 'update',
-    id: entry.path,
-    patch: origin.patch || { yjs: snapshotBase64 },
-    sharedResourceId: input.resourceId,
-    source: 'doc:cloud-snapshot',
-    resourceVersion: Number(input.snapshotVersion),
-  });
-  return { replica: registered.replica, event };
+  } else if (
+    entry.doc.getText(TEXT_KEY).toString().length > 0
+    && !isJournalCursor(input?.attachmentJournalCursor)
+  ) {
+    throw invalid('cloud snapshot attachment requires an empty local text file', 409);
+  }
+  const payload = normalizedSnapshotPayload(entry, {
+    ...input,
+    ...envelope,
+    contract: input?.contract ?? existingReplica?.contract,
+    schemaVersion: input?.schemaVersion ?? existingReplica?.schemaVersion,
+  }, snapshotBase64, checksum);
+  const plan = planCloudDocSnapshot(Y, entry, payload);
+  return materializeCloudDocSnapshot(Y, entry, plan);
 }
 
 /**
@@ -1216,36 +1852,165 @@ function getDocText(pathInput) {
  * Repoint persisted and open document materializations after tree identity
  * moved. The resource remains doc:<node UUID>; only the local path changes.
  */
-function rebindNodePaths(changes) {
-  const database = openLocalDb();
+function rebindNodePaths(changes, options = {}) {
+  const database = options.database || openLocalDb();
   ensureDocStatesSchema(database);
-  for (const change of changes || []) {
-    if (!change?.nodeId || !change?.newPath || change.oldPath === change.newPath) continue;
-    database.transaction(() => {
-      database.prepare('UPDATE doc_states SET path = ? WHERE node_id = ? OR path = ?')
-        .run(change.newPath, change.nodeId, change.oldPath);
-      database.prepare('UPDATE shared_resource_replicas SET local_path = ?, updated_at = ? WHERE local_resource = ? OR local_path = ?')
-        .run(change.newPath, new Date().toISOString(), `${DOC_RESOURCE_PREFIX}${change.nodeId}`, change.oldPath);
-      database.prepare('UPDATE shared_resource_promotions SET local_path = ?, updated_at = ? WHERE local_resource = ? OR local_path = ?')
-        .run(change.newPath, new Date().toISOString(), `${DOC_RESOURCE_PREFIX}${change.nodeId}`, change.oldPath);
-      database.prepare('UPDATE shared_resource_attachments SET local_path = ?, updated_at = ? WHERE local_path = ?')
-        .run(change.newPath, new Date().toISOString(), change.oldPath);
-    })();
-
-    const entry = Array.from(openDocs.values()).find((candidate) => (
+  const token = crypto.randomBytes(16).toString('hex');
+  const nodeIds = new Set();
+  const newPaths = new Set();
+  const normalized = [];
+  for (const [index, value] of Array.from(changes || []).entries()) {
+    if (!value?.nodeId || !value?.newPath) continue;
+    const oldPath = path.resolve(value.oldPath);
+    const newPath = path.resolve(value.newPath);
+    if (oldPath === newPath) continue;
+    if (nodeIds.has(value.nodeId) || newPaths.has(newPath)) {
+      throw new Error('document path rebind is not one-to-one');
+    }
+    nodeIds.add(value.nodeId);
+    newPaths.add(newPath);
+    normalized.push({
+      nodeId: value.nodeId,
+      oldPath,
+      newPath,
+      newResource: `${DOC_RESOURCE_PREFIX}${value.nodeId}`,
+      oldLocalResource: `${DOC_RESOURCE_PREFIX}${
+        fsPrivate().base64UrlEncode(oldPath)
+      }`,
+      temporaryPath: path.join(
+        path.dirname(oldPath),
+        `.amalgm-rebind-${token}-${index}`,
+      ),
+    });
+  }
+  if (normalized.length === 0) return options.deferOpenDocs === true ? () => {} : undefined;
+
+  const currentEntries = Array.from(new Set(openDocs.values()));
+  const assignments = normalized.map((change) => ({
+    change,
+    entry: currentEntries.find((candidate) => (
       candidate.nodeId === change.nodeId || candidate.path === change.oldPath
-    ));
-    if (!entry) continue;
-    unwatchDocFile(entry);
-    openDocs.delete(entry.path);
-    entry.path = change.newPath;
-    entry.nodeId = change.nodeId;
-    entry.resource = `${DOC_RESOURCE_PREFIX}${change.nodeId}`;
-    entry.pathAliases.add(change.newPath);
-    resolvedPathCache.set(change.newPath, change.newPath);
-    openDocs.set(change.newPath, entry);
-    if (!isInternalStateDoc(change.newPath)) watchDocFile(loadYjs(), entry);
+    )) || null,
+  })).filter((assignment) => assignment.entry);
+  const affectedEntries = new Set(assignments.map((assignment) => assignment.entry));
+  for (const { change } of assignments) {
+    const occupant = currentEntries.find((entry) => entry.path === change.newPath);
+    if (occupant && !affectedEntries.has(occupant)) {
+      throw new Error(`document path rebind destination is already open: ${change.newPath}`);
+    }
   }
+
+  // Every path-bearing table moves through a private temporary namespace
+  // before any final path is installed. Swaps and longer cycles are therefore
+  // one set-wise transition instead of a sequence that can collide with
+  // UNIQUE(local_path) or doc_states' path primary key.
+  database.transaction(() => {
+    const now = new Date().toISOString();
+    for (const change of normalized) {
+      database.prepare('UPDATE doc_states SET path = ? WHERE node_id = ? OR path = ?')
+        .run(change.temporaryPath, change.nodeId, change.oldPath);
+      database.prepare(`
+        UPDATE shared_resource_replicas
+        SET local_resource = ?, local_path = ?, updated_at = ?
+        WHERE resource_id = ? OR local_resource = ? OR local_resource = ? OR local_path = ?
+      `).run(
+        change.newResource,
+        change.temporaryPath,
+        now,
+        change.nodeId,
+        change.oldLocalResource,
+        change.newResource,
+        change.oldPath,
+      );
+      database.prepare(`
+        UPDATE shared_resource_promotions
+        SET local_resource = ?, local_path = ?, updated_at = ?
+        WHERE resource_id = ? OR local_resource = ? OR local_resource = ? OR local_path = ?
+      `).run(
+        change.newResource,
+        change.temporaryPath,
+        now,
+        change.nodeId,
+        change.oldLocalResource,
+        change.newResource,
+        change.oldPath,
+      );
+      database.prepare(`
+        UPDATE shared_resource_attachments
+        SET local_path = ?, updated_at = ?
+        WHERE resource_id = ? OR local_path = ?
+      `).run(change.temporaryPath, now, change.nodeId, change.oldPath);
+    }
+    for (const change of normalized) {
+      database.prepare('UPDATE doc_states SET path = ? WHERE node_id = ? OR path = ?')
+        .run(change.newPath, change.nodeId, change.temporaryPath);
+      database.prepare(`
+        UPDATE mutation_journal
+        SET local_resource = ?, updated_at = ?
+        WHERE local_resource = ? OR local_resource = ?
+      `).run(
+        change.newResource,
+        now,
+        change.oldLocalResource,
+        change.newResource,
+      );
+      docDisk.rebindLocalResource(database, {
+        oldLocalResource: change.oldLocalResource,
+        newLocalResource: change.newResource,
+        newPath: change.newPath,
+      });
+      database.prepare(`
+        UPDATE shared_resource_replicas
+        SET local_resource = ?, local_path = ?, updated_at = ?
+        WHERE resource_id = ? OR local_resource = ? OR local_path = ?
+      `).run(
+        change.newResource,
+        change.newPath,
+        now,
+        change.nodeId,
+        change.newResource,
+        change.temporaryPath,
+      );
+      database.prepare(`
+        UPDATE shared_resource_promotions
+        SET local_resource = ?, local_path = ?, updated_at = ?
+        WHERE resource_id = ? OR local_resource = ? OR local_path = ?
+      `).run(
+        change.newResource,
+        change.newPath,
+        now,
+        change.nodeId,
+        change.newResource,
+        change.temporaryPath,
+      );
+      database.prepare(`
+        UPDATE shared_resource_attachments
+        SET local_path = ?, updated_at = ?
+        WHERE resource_id = ? OR local_path = ?
+      `).run(change.newPath, now, change.nodeId, change.temporaryPath);
+    }
+  })();
+
+  const finishOpenDocs = () => {
+    for (const entry of affectedEntries) unwatchDocFile(entry);
+    for (const [key, entry] of Array.from(openDocs.entries())) {
+      if (affectedEntries.has(entry)) openDocs.delete(key);
+    }
+    for (const { change, entry } of assignments) {
+      entry.path = change.newPath;
+      entry.nodeId = change.nodeId;
+      entry.resource = change.newResource;
+      entry.pathAliases.add(change.newPath);
+      resolvedPathCache.set(change.newPath, change.newPath);
+      openDocs.set(change.newPath, entry);
+    }
+    for (const entry of affectedEntries) {
+      if (!isInternalStateDoc(entry.path)) watchDocFile(loadYjs(), entry);
+    }
+  };
+  if (options.deferOpenDocs === true) return finishOpenDocs;
+  finishOpenDocs();
+  return undefined;
 }
 
 function closeDocByNode(nodeId) {
@@ -1266,7 +2031,28 @@ function closeDocsByNodeIds(nodeIds) {
   return closed;
 }
 
-/** Test/shutdown helper: flush and close every open document. */
+function captureDocsByNodeIds(nodeIds, options = {}) {
+  const ids = Array.from(nodeIds instanceof Set ? nodeIds : new Set(nodeIds || []));
+  if (!ids.length) return 0;
+  const database = options.database || openLocalDb();
+  const placeholders = ids.map(() => '?').join(',');
+  const replicas = database.prepare(`
+    SELECT resource_id, local_path
+    FROM shared_resource_replicas
+    WHERE resource_id IN (${placeholders})
+      AND contract = 'text-yjs@1'
+      AND access_status = 'active'
+  `).all(...ids);
+  if (!replicas.length) return 0;
+  const Y = loadYjs();
+  for (const replica of replicas) {
+    const entry = loadDocEntry(replica.local_path);
+    captureDiskBeforeMutation(Y, entry);
+  }
+  return replicas.length;
+}
+
+/** Test/shutdown helper: capture final disk observations and close every open document. */
 function closeAllDocs() {
   let Y;
   try {
@@ -1282,6 +2068,7 @@ module.exports = {
   applyCloudDocMutation,
   applyDocMutations,
   applyDocUpdates,
+  captureDocsByNodeIds,
   closeDocByNode,
   closeDocsByNodeIds,
   closeAllDocs,
@@ -1294,5 +2081,18 @@ module.exports = {
   rebindNodePaths,
   writeDocText,
   // Test hooks only — not part of the module contract.
-  _private: { isInternalStateDoc, openDocs },
+  _private: {
+    isInternalStateDoc,
+    openDocs,
+    setDiskTransactionTestHooks(hooks = {}) {
+      diskTransactionTestHooks = { ...hooks };
+    },
+    verifyOpenDocs,
+    watchVerificationStats() {
+      return {
+        active: watchVerificationTimer !== null,
+        passes: watchVerificationPasses,
+      };
+    },
+  },
 };