amalgm 0.1.245 → 0.1.246

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, so everything that reads the file — agents, exports,
- * git — keeps working unchanged.
+ * remains the artifact (debounced write-back), so everything that reads the
+ * file — agents, exports, git — keeps working unchanged.
  *
  * Wire contract:
  *   POST /state/docs/open    {path}                → {resource, path, state, seq}
@@ -30,28 +30,22 @@
  * (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 arrived since
- * the filesystem writer's apparent base), 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 inside the
+ * write-back debounce window), 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 journal-owned native file transaction then puts the merged text
- * on disk only if that exact observed predecessor is still there.
+ * event. The next write-back then puts the merged text on disk — the
+ * incoming version it replaces lives on in the sidecar.
  */
 
 const crypto = require('crypto');
 const fs = require('fs');
 const path = require('path');
 const { cachedStatement, ensureDocStatesSchema, openLocalDb } = require('./db');
-const docDisk = require('./doc-disk');
-const {
-  appendStateEvent,
-  currentSeq,
-  insertStateEvent,
-  publishStateEvent,
-} = require('./events');
+const { appendStateEvent, currentSeq } = require('./events');
 const { merge3 } = require('./merge3');
 const { trace } = require('./trace');
 
@@ -59,8 +53,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
@@ -84,8 +78,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, lastAccess,
-//                    lastDiskText, lastDiskHash, pathAliases }
+// resolved path -> { doc, resource, reconcileTimer, diskWriteTimer,
+//                    lastAccess, lastDiskText, lastDiskHash, pathAliases }
 const openDocs = new Map();
 
 // pathInput (as the client sent it) -> resolved path, held only while the doc
@@ -98,9 +92,6 @@ 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;
@@ -122,10 +113,6 @@ 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');
 }
@@ -146,16 +133,15 @@ function newMutationId() {
 }
 
 // The only way lastDiskText is ever assigned: the hash is what persistence
-// writes, and hashing at assignment (rare: open, reconcile, materialize) keeps the
+// writes, and hashing at assignment (rare: open, reconcile, flush) 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 native materialization), 'open' (seed of an unchanged file) — and is what the
+// doc's own write-back), '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, observation = null) {
+function setLastDiskText(entry, text, origin) {
   entry.lastDiskText = text;
   entry.lastDiskHash = text == null ? null : hashText(text);
-  entry.lastDiskObservation = observation;
   if (text != null) pushDiskHistory(entry, text, entry.lastDiskHash, origin || 'disk');
 }
 
@@ -168,6 +154,7 @@ 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;
   }
@@ -299,48 +286,21 @@ 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 },
-  );
-}
-
 /**
- * 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.
+ * 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.
  */
-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);
+function spliceDocText(Y, entry, nextText, source, mutationId = newMutationId()) {
   const origin = { amalgmMutation: true, source, patch: 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,
-  };
+  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 };
 }
 
 function canCurrentUserEditDoc(entry) {
@@ -353,123 +313,23 @@ 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. 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.
+ * 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.
  */
-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));
+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);
   const replica = require('./replicas').getReplicaByLocalResource(entry.resource);
   trace('doc-commit', {
     mutationId,
@@ -478,53 +338,39 @@ function commitDocMutation(
     shared: replica?.resourceId,
   });
   const origin = { amalgmMutation: true, source, patch: null };
-  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;
-  }
+  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 };
+    },
+  });
 }
 
 // A merge where every incoming hunk conflicted leaves the doc text unchanged:
@@ -561,6 +407,58 @@ 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);
 }
@@ -602,59 +500,31 @@ function writeConflictSidecar(entry, theirsText, hunkCount) {
   );
 }
 
-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 {
+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) {
         const sidecarPath = writeConflictSidecar(entry, onDisk, merged.conflicts.length);
         entry.pendingConflict = {
           reason: 'overlapping-hunks',
@@ -663,181 +533,52 @@ function diskEditForObservation(Y, entry, observation) {
           at: new Date().toISOString(),
         };
       }
-    }
-  } 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 (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(),
       };
-    } else if (observation.text === entry.doc.getText(TEXT_KEY).toString()) {
-      setLastDiskText(entry, observation.text, 'disk', observation);
+    }
+    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 {
       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) {
-    if (strict) throw error;
+    // File deleted or unreadable — the doc simply stops following the disk.
     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 (an interrupted journal-owned file
- *    transaction), finish that durable mutation instead of splicing stale disk text
+ *    if the persisted doc is ahead (edits inside the unflushed debounce
+ *    window), write the doc back out 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.
@@ -847,11 +588,10 @@ function seedFromDisk(Y, entry, persisted) {
   if (!knownHash) {
     if (!canCurrentUserEditDoc(entry)) {
       try {
-        const observation = docDisk.observe(entry.path);
-        const onDisk = observation.text;
+        const onDisk = fs.readFileSync(entry.path, 'utf8');
         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', observation);
+        setLastDiskText(entry, onDisk, 'open');
         persistDocState(Y, entry);
       } catch {
         // Unreadable/deleted: same posture as reconcile — stop following disk.
@@ -862,10 +602,8 @@ function seedFromDisk(Y, entry, persisted) {
     return;
   }
   let onDisk = null;
-  let observation = null;
   try {
-    observation = docDisk.observe(entry.path);
-    onDisk = observation.text;
+    onDisk = fs.readFileSync(entry.path, 'utf8');
   } catch {
     // Unreadable/deleted: same posture as reconcile — stop following disk.
     return;
@@ -874,15 +612,9 @@ function seedFromDisk(Y, entry, persisted) {
     reconcileFromDisk(Y, entry);
     return;
   }
-  setLastDiskText(entry, onDisk, 'open', observation);
+  setLastDiskText(entry, onDisk, 'open');
   if (entry.doc.getText(TEXT_KEY).toString() !== onDisk) {
-    const bytes = Buffer.from(Y.encodeStateAsUpdate(entry.doc));
-    commitDocMutation(Y, entry, {
-      mutationId: newMutationId(),
-      update: bytes.toString('base64'),
-      bytes,
-      diskObservation: observation,
-    }, 'doc:recovery');
+    scheduleDiskWrite(Y, entry);
   }
 }
 
@@ -895,35 +627,6 @@ 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);
@@ -971,36 +674,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;
   }
-  // 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);
+  // 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);
+  }
   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 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;
+  const pending = require('./mutations').listMutations({ state: 'saving-local', limit: 1000 })
+    .filter((mutation) => mutation.localResource === entry.resource);
+  for (const mutation of pending) {
     if (
       mutation.operationKind !== 'yjs.update'
       || typeof mutation.operation?.update !== 'string'
     ) {
-      throw new Error(`document mutation ${mutation.mutationId} has an unsupported operation`);
+      continue;
     }
     const bytes = Buffer.from(mutation.operation.update, 'base64');
     try {
@@ -1009,52 +712,11 @@ 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);
-    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(
+    if (mutation.sharedResourceId) flushDocToDisk(Y, entry);
+    else scheduleDiskWrite(Y, entry);
+    require('./mutations').completeMaterializedMutation(
       mutation.channelId,
       mutation.mutationId,
       {
@@ -1062,37 +724,10 @@ function recoverPendingDocMutations(Y, entry) {
         op: 'update',
         id: entry.path,
         patch: origin.patch || { yjs: mutation.operation.update },
-        source: mutation.origin === 'cloud'
-          ? 'doc:cloud-recovery'
-          : plan.mutationSource === 'doc:disk'
-            ? 'doc:disk'
-            : 'doc:recovery',
+        source: mutation.origin === 'cloud' ? 'doc:cloud-recovery' : '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);
-    }
   }
 }
 
@@ -1148,13 +783,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.
@@ -1163,26 +798,19 @@ 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]),
   };
 
-  const readPersisted = () => (
-    nodeId
-      ? cachedStatement(database, `
+  let persisted = 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
-  );
-  let persisted = readPersisted();
+    : cachedStatement(database, 'SELECT state, last_disk_hash FROM doc_states WHERE path = ?').get(resolved) || null;
   if (persisted?.state) {
     try {
       Y.applyUpdate(doc, new Uint8Array(persisted.state), 'persisted');
@@ -1205,52 +833,33 @@ function loadDocEntry(pathInput) {
     origin.patch = { yjs: Buffer.from(update).toString('base64') };
   });
 
-  // 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);
+  // 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);
+  }
 
   // A process can die after the durable journal insert but before Y.Doc/file
   // materialization or event projection. Replay those exact operation IDs
-  // 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.
+  // before this open is acknowledged, so a restart cannot bury an edit.
   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 native materialization as if it were an external user edit creates a second
+  // own atomic flush 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;
 }
@@ -1341,10 +950,12 @@ function writeDocText(pathInput, textInput, options = {}) {
   const entry = loadDocEntry(pathInput);
   entry.lastAccess = Date.now();
   requireCurrentUserDocEdit(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);
+  // 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);
   const ytext = entry.doc.getText(TEXT_KEY);
   const ours = ytext.toString();
 
@@ -1410,29 +1021,9 @@ function writeDocText(pathInput, textInput, options = {}) {
 
   entry.pendingConflict = conflict;
   const edit = spliceDocText(Y, entry, nextText, 'doc:write', mutationId);
-  if (edit) {
-    if (diskTransactionTestHooks.pauseAfterEditBeforeJournal > 0) {
-      Atomics.wait(
-        new Int32Array(new SharedArrayBuffer(4)),
-        0,
-        0,
-        diskTransactionTestHooks.pauseAfterEditBeforeJournal,
-      );
-    }
-    commitDocMutation(
-      Y,
-      entry,
-      { ...edit, materializationBase },
-      'doc:write',
-    );
-  }
+  if (edit) commitDocMutation(Y, entry, edit, 'doc:write');
   else publishConflictOnly(entry, 'doc:write');
-  return respond(
-    merge,
-    entry.doc.getText(TEXT_KEY).toString(),
-    conflict,
-    edit?.mutationId || null,
-  );
+  return respond(merge, nextText, conflict, edit?.mutationId || null);
 }
 
 function normalizeDocMutations(Y, mutationsInput) {
@@ -1468,7 +1059,6 @@ 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 {
@@ -1503,30 +1093,18 @@ 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 };
-  let diskOutcome = null;
-  const result = require('./mutations').ingestCloudMutation({
+  return require('./mutations').ingestCloudMutation({
     envelope,
     version: input?.version,
     committedAt: input?.committedAt,
     localResource: entry.resource,
   }, {
-    persist(database, journaled) {
-      docDisk.insertBase(database, journaled, base, 'doc:cloud');
-    },
-    materialize(journaled) {
+    materialize() {
       Y.applyUpdate(entry.doc, new Uint8Array(mutation.bytes), origin);
       persistDocState(Y, entry);
-      diskOutcome = materializeDocDiskMutation(
-        Y,
-        entry,
-        journaled,
-        diskTransactionTestHooks,
-      );
+      // Recipient file first; the projected event that wakes its UI follows.
+      flushDocToDisk(Y, entry);
     },
     event: () => ({
       resource: entry.resource,
@@ -1537,233 +1115,10 @@ 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');
@@ -1776,9 +1131,8 @@ function installCloudDocSnapshot(pathInput, input) {
   } catch (error) {
     throw invalid(`invalid Yjs snapshot: ${error?.message || error}`);
   }
-  const entry = loadDocEntry(pathInput);
-  recoverPendingDocSnapshots(Y, entry);
   const replicas = require('./replicas');
+  const entry = loadDocEntry(pathInput);
   const existingReplica = replicas.getReplicaByResourceId(input?.resourceId);
   if (existingReplica) {
     // Rehydration: this replica fell behind the pruned official tail, so the
@@ -1788,36 +1142,46 @@ function installCloudDocSnapshot(pathInput, input) {
     if (existingReplica.localResource !== entry.resource) {
       throw invalid(`shared resource ${input?.resourceId} is bound to a different local file`, 409);
     }
-    const incomingVersion = envelope.snapshotVersion;
-    if (incomingVersion <= existingReplica.appliedVersion) {
-      const checked = replicas.advanceReplicaSnapshot({
-        resourceId: envelope.resourceId,
-        snapshotVersion: incomingVersion,
-        snapshotChecksum: checksum,
-        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 };
-    }
-  } else if (
-    entry.doc.getText(TEXT_KEY).toString().length > 0
-    && !isJournalCursor(input?.attachmentJournalCursor)
-  ) {
+  } else if (entry.doc.getText(TEXT_KEY).toString().length > 0) {
     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);
+  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,
+        snapshotChecksum: checksum,
+        authorityEpoch: input?.authorityEpoch,
+      }),
+    }
+    : 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 };
 }
 
 /**
@@ -1852,165 +1216,36 @@ 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, options = {}) {
-  const database = options.database || openLocalDb();
+function rebindNodePaths(changes) {
+  const database = openLocalDb();
   ensureDocStatesSchema(database);
-  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) => (
+  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) => (
       candidate.nodeId === change.nodeId || candidate.path === change.oldPath
-    )) || 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}`);
-    }
+    ));
+    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);
   }
-
-  // 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) {
@@ -2031,28 +1266,7 @@ function closeDocsByNodeIds(nodeIds) {
   return closed;
 }
 
-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. */
+/** Test/shutdown helper: flush and close every open document. */
 function closeAllDocs() {
   let Y;
   try {
@@ -2068,7 +1282,6 @@ module.exports = {
   applyCloudDocMutation,
   applyDocMutations,
   applyDocUpdates,
-  captureDocsByNodeIds,
   closeDocByNode,
   closeDocsByNodeIds,
   closeAllDocs,
@@ -2081,18 +1294,5 @@ module.exports = {
   rebindNodePaths,
   writeDocText,
   // Test hooks only — not part of the module contract.
-  _private: {
-    isInternalStateDoc,
-    openDocs,
-    setDiskTransactionTestHooks(hooks = {}) {
-      diskTransactionTestHooks = { ...hooks };
-    },
-    verifyOpenDocs,
-    watchVerificationStats() {
-      return {
-        active: watchVerificationTimer !== null,
-        passes: watchVerificationPasses,
-      };
-    },
-  },
+  _private: { isInternalStateDoc, openDocs },
 };