amalgm 0.1.156 → 0.1.157

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "amalgm",
-  "version": "0.1.156",
+  "version": "0.1.157",
   "description": "Amalgm local computer runtime: login, MCP, chat, events, previews, and tunnels.",
   "license": "UNLICENSED",
   "private": false,

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

@@ -186,6 +186,11 @@ function migrate(database = openLocalDb()) {
       next_attempt_at TEXT,
       last_error TEXT,
       snapshot_key TEXT,
+      -- Promotion fence: MAX(journal_id) when the snapshot was captured.
+      -- Local mutations journaled past this cursor are not in the snapshot;
+      -- acknowledgePromotion re-homes them onto the shared channel so edits
+      -- made while sharing was in flight reach the cloud outbox.
+      journal_cursor INTEGER NOT NULL DEFAULT 0,
       created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
       updated_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now'))
     );
@@ -604,6 +609,9 @@ function migrate(database = openLocalDb()) {
   // untouched while new SDK mutations carry their stable identity.
   ensureColumn(database, 'event_log', 'mutation_id', 'TEXT');
   ensureColumn(database, 'event_log', 'shared_resource_id', 'TEXT');
+  // Wave-3 canaries created shared_resource_promotions before the fence
+  // cursor existed.
+  ensureColumn(database, 'shared_resource_promotions', 'journal_cursor', 'INTEGER NOT NULL DEFAULT 0');
   require('./migrations').runLegacyMigrations(database);
 }
 

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

@@ -47,6 +47,7 @@ const path = require('path');
 const { cachedStatement, ensureDocStatesSchema, openLocalDb } = require('./db');
 const { appendStateEvent, currentSeq } = require('./events');
 const { merge3 } = require('./merge3');
+const { trace } = require('./trace');
 
 const DOC_RESOURCE_PREFIX = 'doc:';
 const TEXT_KEY = 'content';
@@ -208,13 +209,12 @@ function resolveDocPath(pathInput) {
 }
 
 /**
- * Splice `nextText` into ytext as a minimal edit (common prefix/suffix kept),
- * backing off surrogate-pair boundaries so we never split a character.
+ * The minimal edit turning `current` into `nextText`: common prefix and
+ * suffix kept, backed off surrogate-pair boundaries so a character is never
+ * split. `[start, endCurrent)` is the replaced region of `current`;
+ * `[start, endNext)` is its replacement in `nextText`.
  */
-function spliceTextInto(Y, doc, ytext, nextText, origin) {
-  const current = ytext.toString();
-  if (current === nextText) return false;
-
+function spliceBounds(current, nextText) {
   let start = 0;
   const maxStart = Math.min(current.length, nextText.length);
   while (start < maxStart && current[start] === nextText[start]) start += 1;
@@ -230,6 +230,29 @@ function spliceTextInto(Y, doc, ytext, nextText, origin) {
     endCurrent += 1;
     endNext += 1;
   }
+  return { start, endCurrent, endNext };
+}
+
+// Whether replacing `current` with `nextText` deletes any text. This is the
+// exact question the overwrite guards care about: an insertion-only change
+// (append, new paragraph, edits at several points) destroys nothing, so
+// there is nothing to preserve and no reason to surface it. "Deletes
+// nothing" means every character of `current` survives, in order, in
+// `nextText` — a subsequence scan, so multi-point insertions count as
+// preserving, not just a single splice.
+function overwriteDeletesText(current, nextText) {
+  let kept = 0;
+  for (let j = 0; kept < current.length && j < nextText.length; j += 1) {
+    if (current[kept] === nextText[j]) kept += 1;
+  }
+  return kept < current.length;
+}
+
+// Splice `nextText` into ytext as the minimal edit from spliceBounds.
+function spliceTextInto(Y, doc, ytext, nextText, origin) {
+  const current = ytext.toString();
+  if (current === nextText) return false;
+  const { start, endCurrent, endNext } = spliceBounds(current, nextText);
 
   doc.transact(() => {
     if (endCurrent > start) ytext.delete(start, endCurrent - start);
@@ -242,6 +265,98 @@ function isLowSurrogate(code) {
   return code >= 0xdc00 && code <= 0xdfff;
 }
 
+/**
+ * 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) {
+  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: newMutationId(), update: origin.patch.yjs, bytes: null };
+}
+
+/**
+ * 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.
+ */
+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,
+    source,
+    path: entry.path,
+    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 ? process.env.AMALGM_DEVICE_ID : 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:
+// there is no edit to journal, but the conflict (and its sidecar) must still
+// reach subscribed surfaces.
+function publishConflictOnly(entry, source) {
+  if (!entry.pendingConflict) return;
+  appendStateEvent({
+    resource: entry.resource,
+    op: 'update',
+    id: entry.path,
+    patch: { conflict: entry.pendingConflict },
+    source,
+  });
+  entry.pendingConflict = null;
+}
+
 // Schema is ensured once at loadDocEntry; every entry that reaches here came
 // through it.
 function persistDocState(Y, entry) {
@@ -263,21 +378,52 @@ function scheduleDiskWrite(Y, entry) {
   if (entry.diskWriteTimer) return;
   entry.diskWriteTimer = setTimeout(() => {
     entry.diskWriteTimer = null;
-    flushDocToDisk(Y, entry);
+    // 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 {
-    const text = entry.doc.getText(TEXT_KEY).toString();
-    const onDisk = fs.readFileSync(entry.path, 'utf8');
-    if (onDisk !== text) fs.writeFileSync(entry.path, text, 'utf8');
-    setLastDiskText(entry, text, 'flush');
-    persistDocState(Y, entry);
+    onDisk = fs.readFileSync(entry.path, 'utf8');
   } catch (error) {
-    console.warn(`[LiveDoc] Failed to flush "${entry.path}" to disk:`, error?.message || 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) {
@@ -349,13 +495,15 @@ function reconcileFromDisk(Y, entry) {
           at: new Date().toISOString(),
         };
       }
-    } else if (ours !== onDisk && liveEditsSinceLastDiskState(entry)) {
-      // Wholesale accept, but the text it replaces was produced through the
-      // live channel and 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.
+    } 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,
@@ -369,27 +517,18 @@ function reconcileFromDisk(Y, entry) {
       };
     }
     setLastDiskText(entry, onDisk, 'disk');
-    // origin 'disk' keeps the update handler from writing the same bytes back.
-    const spliced = spliceTextInto(Y, entry.doc, ytext, nextText, 'disk');
-    if (!spliced && entry.pendingConflict) {
-      // Every external hunk conflicted, so the doc text is unchanged and no
-      // update event fired — publish the conflict on its own.
-      appendStateEvent({
-        resource: entry.resource,
-        op: 'update',
-        id: entry.path,
-        patch: { conflict: entry.pendingConflict },
-        source: 'doc:disk',
-      });
-      entry.pendingConflict = null;
+    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);
     }
-    // A merge that diverged from what's on disk must write back: disk still
-    // holds THEIRS (preserved in the sidecar when it conflicted); the file
-    // artifact follows the doc.
-    if (nextText !== onDisk) scheduleDiskWrite(Y, entry);
-    // Persist even for a no-op splice: the refreshed lastDiskText hash still
-    // needs recording.
-    persistDocState(Y, entry);
   } catch (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);
@@ -493,7 +632,13 @@ function closeDocEntry(Y, entry) {
     clearTimeout(entry.reconcileTimer);
     entry.reconcileTimer = null;
   }
-  flushDocToDisk(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.doc.destroy();
@@ -612,38 +757,15 @@ function loadDocEntry(pathInput) {
     }
   }
 
-  // Every applied change — client update, disk reconcile, or seed — flows
-  // through this one pipeline: event out, then (except disk-origin) disk out.
-  // State persistence is NOT per update: the durability contract only needs
-  // the state durable before the caller acknowledges, so each mutation entry
-  // point (applyDocUpdates, reconcileFromDisk, flushDocToDisk) persists once
-  // when it is done. A kill — even SIGKILL — still never loses an
-  // acknowledged edit; at worst the disk artifact lags by the debounce window
-  // until the doc is next opened.
+  // One door: every change to this doc is applied by a journal-owned commit
+  // (client mutation, whole-text write, disk reconcile, cloud ingest,
+  // snapshot install, recovery), and that commit materializes state and
+  // projects the event itself. The observer's only job is handing the exact
+  // emitted update bytes back to the commit that applied it. Assigning to a
+  // non-object origin throws in strict mode — any future path that mutates
+  // the doc outside the door fails loudly instead of losing its event.
   doc.on('update', (update, origin) => {
-    const patch = { yjs: Buffer.from(update).toString('base64') };
-    // Disk reconciles and versioned writes both splice synchronously right
-    // after setting pendingConflict, so the conflict rides this event.
-    if ((origin === 'disk' || origin === 'write') && entry.pendingConflict) {
-      patch.conflict = entry.pendingConflict;
-      entry.pendingConflict = null;
-    }
-    // SDK mutations own their journal row and event projection explicitly:
-    // durable journal first, then Y.Doc + file materialization, then event.
-    // The observer still captures the exact emitted update, but must not
-    // append an early event or schedule the shared file write after ack.
-    if (origin && typeof origin === 'object' && origin.amalgmMutation === true) {
-      origin.patch = patch;
-      return;
-    }
-    appendStateEvent({
-      resource: entry.resource,
-      op: 'update',
-      id: entry.path,
-      patch,
-      source: origin === 'disk' ? 'doc:disk' : origin === 'write' ? 'doc:write' : 'doc:update',
-    });
-    if (origin !== 'disk') scheduleDiskWrite(Y, entry);
+    origin.patch = { yjs: Buffer.from(update).toString('base64') };
   });
 
   // Disk at open: an externally changed file folds in as an edit, but a file
@@ -743,6 +865,12 @@ function writeDocText(pathInput, textInput, options = {}) {
 
   const entry = loadDocEntry(pathInput);
   entry.lastAccess = Date.now();
+  // 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();
 
@@ -788,10 +916,14 @@ function writeDocText(pathInput, textInput, options = {}) {
     }
   } else {
     // No base declared: same conservative posture as a raw disk write —
-    // silent when the replaced text is just the last disk state, preserved
-    // and surfaced when live-channel edits would be destroyed.
+    // silent when nothing is destroyed or the replaced text is just the last
+    // disk state, preserved and surfaced when live-channel edits would be
+    // deleted.
     merge = 'overwrite';
-    if (ours !== entry.lastDiskText || liveEditsSinceLastDiskState(entry)) {
+    if (
+      overwriteDeletesText(ours, textInput)
+      && (ours !== entry.lastDiskText || liveEditsSinceLastDiskState(entry))
+    ) {
       const sidecarPath = writePreservationSidecar(
         entry,
         ours,
@@ -802,22 +934,9 @@ function writeDocText(pathInput, textInput, options = {}) {
   }
 
   entry.pendingConflict = conflict;
-  // origin 'write' rides the conflict on the emitted doc event and schedules
-  // the disk write-back (unlike 'disk', which must not echo to disk).
-  const spliced = spliceTextInto(Y, entry.doc, ytext, nextText, 'write');
-  if (!spliced && entry.pendingConflict) {
-    // Every incoming hunk conflicted: the doc text is unchanged, no update
-    // event fired — publish the conflict on its own (mirrors reconcile).
-    appendStateEvent({
-      resource: entry.resource,
-      op: 'update',
-      id: entry.path,
-      patch: { conflict: entry.pendingConflict },
-      source: 'doc:write',
-    });
-    entry.pendingConflict = null;
-  }
-  persistDocState(Y, entry);
+  const edit = spliceDocText(Y, entry, nextText, 'doc:write');
+  if (edit) commitDocMutation(Y, entry, edit, 'doc:write');
+  else publishConflictOnly(entry, 'doc:write');
   return respond(merge, nextText, conflict);
 }
 
@@ -853,47 +972,7 @@ function applyDocMutations(pathInput, mutationsInput) {
   if (mutations.length === 0) return { applied: 0, seq: currentSeq(), mutationIds: [] };
   const entry = loadDocEntry(pathInput);
   entry.lastAccess = Date.now();
-  const results = [];
-
-  for (const mutation of mutations) {
-    const replica = require('./replicas').getReplicaByLocalResource(entry.resource);
-    const operation = { kind: 'yjs.update', update: mutation.update };
-    const origin = { amalgmMutation: true, source: 'local', patch: null };
-    const result = require('./mutations').commitLocalMutation({
-      channelId: replica ? `resource:${replica.resourceId}` : entry.resource,
-      localResource: entry.resource,
-      sharedResourceId: replica?.resourceId,
-      mutationId: mutation.mutationId,
-      deviceId: replica ? process.env.AMALGM_DEVICE_ID : null,
-      authorityEpoch: replica?.authorityEpoch || 0,
-      baseCloudVersion: replica?.appliedVersion || 0,
-      contract: replica?.contract || 'text-yjs@1',
-      schemaVersion: replica?.schemaVersion || 1,
-      operationKind: 'yjs.update',
-      operation,
-    }, {
-      materialize() {
-        Y.applyUpdate(entry.doc, new Uint8Array(mutation.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 {
-          // Preserve the existing local-only write-back behavior.
-          scheduleDiskWrite(Y, entry);
-        }
-      },
-      event: () => ({
-        resource: entry.resource,
-        op: 'update',
-        id: entry.path,
-        patch: origin.patch || { yjs: mutation.update },
-        source: 'doc:update',
-      }),
-    });
-    results.push(result);
-  }
+  const results = mutations.map((mutation) => commitDocMutation(Y, entry, mutation, 'doc:update'));
 
   return {
     applied: mutations.length,

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

@@ -14,6 +14,7 @@
 
 const { cachedStatement, openLocalDb } = require('./db');
 const { insertStateEvent, publishStateEvent } = require('./events');
+const { trace } = require('./trace');
 
 const MAX_MUTATION_BYTES = 4 * 1024 * 1024;
 const DEFAULT_CLAIM_LIMIT = 100;
@@ -253,6 +254,11 @@ function journalMutation(input, options = {}) {
 
     const row = cachedStatement(database, 'SELECT * FROM mutation_journal WHERE journal_id = ?')
       .get(Number(info.lastInsertRowid));
+    trace('journal', {
+      mutationId: mutation.mutationId,
+      channel: mutation.channelId,
+      shared: mutation.sharedResourceId,
+    });
     return { mutation: normalizeJournalRow(row), duplicate: false };
   })();
 }
@@ -343,6 +349,12 @@ function completeMaterializedMutation(channelIdInput, mutationIdInput, eventInpu
       advanceReplicaCursor(database, row.shared_resource_id);
     }
 
+    trace('materialized', {
+      mutationId: row.mutation_id,
+      origin: row.mutation_origin,
+      state: nextState,
+      eventSeq: event.seq,
+    });
     return {
       mutation: normalizeJournalRow(
         cachedStatement(database, 'SELECT * FROM mutation_journal WHERE journal_id = ?')
@@ -492,6 +504,7 @@ function journalCloudMutation(input, options = {}) {
       now,
       now,
     );
+    trace('cloud-ingest', { mutationId: mutation.mutationId, shared: sharedResourceId, version });
     return {
       mutation: normalizeJournalRow(
         cachedStatement(database, 'SELECT * FROM mutation_journal WHERE journal_id = ?')
@@ -629,6 +642,11 @@ function claimCloudMutations(options = {}) {
     return rows.map((row) => {
       claim.run(leaseUntil, now, row.journal_id);
       const mutation = normalizeJournalRow(read.get(row.journal_id));
+      trace('claim', {
+        mutationId: mutation.mutationId,
+        shared: mutation.sharedResourceId,
+        attempt: mutation.attemptCount,
+      });
       return { mutation, envelope: cloudEnvelope(mutation) };
     });
   })();
@@ -677,6 +695,7 @@ function acknowledgeCloudMutation(sharedResourceIdInput, mutationIdInput, acknow
       WHERE journal_id = ?
     `).run(version, committedAt, now, row.journal_id);
     advanceReplicaCursor(database, sharedResourceId);
+    trace('cloud-ack', { mutationId, shared: sharedResourceId, version });
     return {
       mutation: normalizeJournalRow(
         cachedStatement(database, 'SELECT * FROM mutation_journal WHERE journal_id = ?')
@@ -709,6 +728,7 @@ function failCloudMutation(sharedResourceIdInput, mutationIdInput, failure, opti
         updated_at = ?
     WHERE journal_id = ?
   `).run(retryable ? 'syncing' : 'rejected', retryAt, message, now, row.journal_id);
+  trace('cloud-fail', { mutationId, shared: sharedResourceId, retryable, message });
   return normalizeJournalRow(
     cachedStatement(database, 'SELECT * FROM mutation_journal WHERE journal_id = ?')
       .get(row.journal_id),

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

@@ -5,6 +5,7 @@ const path = require('path');
 const { cachedStatement, openLocalDb } = require('./db');
 const { appendStateEvent } = require('./events');
 const { registerReplica } = require('./replicas');
+const { trace } = require('./trace');
 
 const SHARED_RESOURCE_ID = /^shr_[A-Za-z0-9_-]{16,128}$/;
 const PROMOTION_ID = /^[A-Za-z0-9_-]{16,160}$/;
@@ -41,6 +42,7 @@ function normalizeRow(row) {
     nextAttemptAt: row.next_attempt_at || null,
     lastError: row.last_error || null,
     snapshotKey: row.snapshot_key || null,
+    journalCursor: Number(row.journal_cursor || 0),
     createdAt: row.created_at,
     updatedAt: row.updated_at,
   };
@@ -82,6 +84,14 @@ function enqueuePromotion(input, options = {}) {
     return { promotion: row, duplicate: true };
   }
 
+  // The fence: every local mutation already journaled is contained in the
+  // snapshot captured above; anything journaled past this cursor happened
+  // while the promotion was in flight and is re-homed at acknowledgement.
+  const journalCursor = Number(
+    cachedStatement(database, 'SELECT COALESCE(MAX(journal_id), 0) AS cursor FROM mutation_journal')
+      .get().cursor,
+  );
+
   const now = new Date().toISOString();
   cachedStatement(database, `
     INSERT INTO shared_resource_promotions (
@@ -97,9 +107,10 @@ function enqueuePromotion(input, options = {}) {
       content_bytes,
       name,
       media_type,
+      journal_cursor,
       created_at,
       updated_at
-    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
   `).run(
     promotionId,
     resourceId,
@@ -113,6 +124,7 @@ function enqueuePromotion(input, options = {}) {
     contentBytes,
     input?.name || path.basename(localPath),
     input?.mediaType || 'application/vnd.amalgm.text-yjs-snapshot',
+    journalCursor,
     now,
     now,
   );
@@ -121,6 +133,12 @@ function enqueuePromotion(input, options = {}) {
       .get(promotionId),
   );
 
+  trace('promotion-enqueue', {
+    promotionId,
+    resourceId,
+    path: localPath,
+    cursor: journalCursor,
+  });
   // Wake the already-open internal Local Live stream used by the tunnel
   // process. This is a control event, not a cloud mutation/version.
   appendStateEvent({
@@ -196,7 +214,7 @@ function acknowledgePromotion(promotionIdInput, acknowledgement, options = {}) {
     }
     if (promotion.state === 'promoted') return { promotion, duplicate: true };
 
-    registerReplica({
+    const { replica } = registerReplica({
       resourceId: promotion.resourceId,
       localResource: promotion.localResource,
       localPath: promotion.localPath,
@@ -209,6 +227,40 @@ function acknowledgePromotion(promotionIdInput, acknowledgement, options = {}) {
     }, { database });
 
     const now = new Date().toISOString();
+
+    // Close the promotion fence: edits journaled while the promotion was in
+    // flight are local-only rows past the enqueue cursor. Re-home them onto
+    // the shared channel — their base is the promoted snapshot — so the
+    // normal outbox claim delivers them. Their journal identity, order, and
+    // already-projected local events are untouched.
+    const rehomed = 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,
+      process.env.AMALGM_DEVICE_ID || null,
+      replica.authorityEpoch,
+      replica.snapshotVersion,
+      now,
+      promotion.localResource,
+      promotion.journalCursor,
+    );
+    trace('promotion-ack', {
+      promotionId,
+      resourceId: replica.resourceId,
+      epoch: replica.authorityEpoch,
+      rehomed: rehomed.changes,
+    });
     cachedStatement(database, `
       UPDATE shared_resource_promotions
       SET promotion_state = 'promoted',

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

@@ -9,6 +9,7 @@
  */
 
 const { cachedStatement, openLocalDb } = require('./db');
+const { trace } = require('./trace');
 
 const SHARED_RESOURCE_ID = /^shr_[A-Za-z0-9_-]{16,128}$/;
 const CONTRACT = /^[A-Za-z0-9][A-Za-z0-9._:@/-]{0,127}$/;
@@ -126,6 +127,7 @@ function registerReplica(input, options = {}) {
     }
     throw error;
   }
+  trace('replica-bind', { resourceId, path: localPath, epoch: authorityEpoch });
   return {
     replica: normalizeReplica(
       cachedStatement(database, 'SELECT * FROM shared_resource_replicas WHERE resource_id = ?')

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

@@ -0,0 +1,26 @@
+'use strict';
+
+/**
+ * Shared-realtime lifecycle tracing. Off unless AMALGM_SHARED_TRACE=1 — the
+ * guard is one boolean, so instrumented paths cost nothing in normal
+ * operation, and the instrumentation ships in production for live debugging
+ * instead of being stripped before release.
+ *
+ * Every line is `[SharedTrace] <step> key=value …` with stable identifiers
+ * (mutationId, resourceId, promotionId), so grepping one id reconstructs the
+ * full journey of one edit: doc-commit → journal → materialized → claim →
+ * cloud-ack (or cloud-ingest → materialized on the recipient).
+ */
+
+const enabled = process.env.AMALGM_SHARED_TRACE === '1';
+
+function trace(step, fields = {}) {
+  if (!enabled) return;
+  let line = `[SharedTrace] ${step}`;
+  for (const [key, value] of Object.entries(fields)) {
+    if (value !== undefined && value !== null) line += ` ${key}=${value}`;
+  }
+  console.log(line);
+}
+
+module.exports = { trace };

package/runtime/scripts/amalgm-mcp/tests/state-docs-versioning.test.js

@@ -176,6 +176,67 @@ test('agent rewrites with no live edits since last sync stay silent: no sidecar,
   assert.equal(conflictEventsFor(opened.resource, before).length, 0, 'no conflict events either');
 });
 
+test('a raw append after flushed live edits applies silently: nothing destroyed, no sidecar', async () => {
+  const target = writeDoc('vim-append.md', 'v1\n');
+  const opened = docs.openDoc(target);
+  const client = clientFromState(opened.state);
+
+  docs.applyDocUpdates(target, [
+    encodeLocalEdit(client, (ytext) => ytext.insert('v1'.length, ' human')),
+  ]);
+  await sleep(500);
+  assert.equal(fs.readFileSync(target, 'utf8'), 'v1 human\n', 'precondition: live edit flushed');
+
+  // A vim user reads the CURRENT file and appends: every existing character
+  // survives, so there is nothing to preserve and nothing to surface.
+  const before = currentSeq();
+  fs.writeFileSync(target, 'v1 human\nFrom vim\n', 'utf8');
+  await sleep(700);
+
+  assert.equal(docs.getDocText(target), 'v1 human\nFrom vim\n');
+  assert.equal(sidecarsFor(target).length, 0, 'an insertion-only write is not a conflict');
+  assert.equal(conflictEventsFor(opened.resource, before).length, 0);
+});
+
+test('insertions at several points still delete nothing: silent, no sidecar', async () => {
+  const target = writeDoc('multi-insert.md', 'm1\nm2\nm3\n');
+  const opened = docs.openDoc(target);
+  const client = clientFromState(opened.state);
+
+  docs.applyDocUpdates(target, [
+    encodeLocalEdit(client, (ytext) => ytext.insert('m1\nm2'.length, ' human')),
+  ]);
+  await sleep(500);
+  assert.equal(fs.readFileSync(target, 'utf8'), 'm1\nm2 human\nm3\n');
+
+  // Not a single splice: new text lands both between m1/m2 and after m3.
+  // Every original character survives in order — nothing was destroyed.
+  const before = currentSeq();
+  fs.writeFileSync(target, 'm1\ninserted\nm2 human\nm3\nappended\n', 'utf8');
+  await sleep(700);
+
+  assert.equal(docs.getDocText(target), 'm1\ninserted\nm2 human\nm3\nappended\n');
+  assert.equal(sidecarsFor(target).length, 0, 'multi-point insertion is not a conflict');
+  assert.equal(conflictEventsFor(opened.resource, before).length, 0);
+});
+
+test('an unversioned API append that preserves all live text applies silently', async () => {
+  const target = writeDoc('api-append.md', 'p1\n');
+  const opened = docs.openDoc(target);
+  const client = clientFromState(opened.state);
+
+  // Live edit still inside the debounce window — the strictest case.
+  docs.applyDocUpdates(target, [
+    encodeLocalEdit(client, (ytext) => ytext.insert('p1'.length, ' human')),
+  ]);
+  const result = docs.writeDocText(target, 'p1 human\nappended\n');
+  assert.equal(result.merge, 'overwrite');
+  assert.equal(result.conflict, null, 'nothing was deleted, so nothing to surface');
+  assert.equal(docs.getDocText(target), 'p1 human\nappended\n');
+  assert.equal(sidecarsFor(target).length, 0);
+  await sleep(500);
+});
+
 test('unflushed live edits still merge exactly as before (step-5 regression guard)', async () => {
   const base = 'k1\nk2\nk3\nk4\nk5\n';
   const target = writeDoc('unflushed-window.md', base);

package/runtime/scripts/amalgm-mcp/tests/state-shared-replica.test.js

@@ -20,6 +20,7 @@ const {
   claimCloudMutations,
   getMutation,
   journalMutation,
+  listMutations,
 } = require('../state/mutations');
 const {
   acknowledgePromotion,
@@ -239,6 +240,13 @@ test('reopen recovers a journaled shared edit that died before materialization',
     listEventsAfter(0).filter((event) => event.mutationId === mutationId).length,
     1,
   );
+
+  // Drain the outbox so later tests observe only their own deliveries.
+  const [claim] = claimCloudMutations().filter((item) => item.envelope.mutationId === mutationId);
+  acknowledgeCloudMutation(resourceId, claim.envelope.mutationId, {
+    version: 4,
+    committedAt: '2026-07-14T20:00:04.000Z',
+  });
 });
 
 test('authorized snapshot attachment creates the recipient file before its UI event', () => {
@@ -281,3 +289,177 @@ test('authorized snapshot attachment creates the recipient file before its UI ev
     resourceId: recipientResourceId,
   }).duplicate, true);
 });
+
+function sleep(ms) {
+  return new Promise((resolve) => { setTimeout(resolve, ms); });
+}
+
+function sha256(text) {
+  return require('crypto').createHash('sha256').update(text, 'utf8').digest('hex');
+}
+
+// One door: an agent writing the shared file directly (no doc API at all)
+// must produce a cloud-deliverable mutation, not just a local event.
+test('an external disk write on a shared doc enters the cloud outbox', async () => {
+  docs.openDoc(target);
+  const beforeText = fs.readFileSync(target, 'utf8');
+  fs.writeFileSync(target, `${beforeText}From vim\n`, 'utf8');
+  await sleep(700);
+
+  assert.equal(docs.getDocText(target), `${beforeText}From vim\n`);
+  const claims = claimCloudMutations().filter((claim) => claim.envelope.resourceId === resourceId);
+  assert.equal(claims.length, 1, 'the raw disk write must be claimable for cloud delivery');
+  assert.equal(claims[0].envelope.operationKind, 'yjs.update');
+  const event = listEventsAfter(0).find((e) => e.mutationId === claims[0].envelope.mutationId);
+  assert.equal(event.source, 'doc:disk');
+  acknowledgeCloudMutation(resourceId, claims[0].envelope.mutationId, {
+    version: getReplicaByResourceId(resourceId).appliedVersion + 1,
+    committedAt: '2026-07-15T20:00:00.000Z',
+  });
+});
+
+// One door: the whole-text write API (agents/tools) on a shared doc.
+test('a versioned whole-text write on a shared doc enters the cloud outbox', () => {
+  const ours = docs.getDocText(target);
+  const written = docs.writeDocText(target, `${ours}From the write API\n`, { baseHash: sha256(ours) });
+  assert.equal(written.merge, 'clean');
+
+  const claims = claimCloudMutations().filter((claim) => claim.envelope.resourceId === resourceId);
+  assert.equal(claims.length, 1, 'the API write must be claimable for cloud delivery');
+  const event = listEventsAfter(0).find((e) => e.mutationId === claims[0].envelope.mutationId);
+  assert.equal(event.source, 'doc:write');
+  acknowledgeCloudMutation(resourceId, claims[0].envelope.mutationId, {
+    version: getReplicaByResourceId(resourceId).appliedVersion + 1,
+    committedAt: '2026-07-15T20:00:01.000Z',
+  });
+});
+
+// Promotion fence: edits made while sharing is being set up may not strand.
+test('edits journaled during the promotion window are re-homed into the outbox', () => {
+  const fenceResourceId = 'shr_fencefencefence1';
+  const fencePath = path.join(docDir, 'fence.md');
+  fs.writeFileSync(fencePath, 'fence base\n', 'utf8');
+  const opened = docs.openDoc(fencePath);
+
+  enqueuePromotion({
+    promotionId: 'prm_fencefencefence1',
+    resourceId: fenceResourceId,
+    localResource: opened.resource,
+    localPath: opened.path,
+    contract: 'text-yjs@1',
+    schemaVersion: 1,
+    snapshotBase64: opened.state,
+    contentBytes: fs.statSync(fencePath).size,
+  });
+
+  // The user keeps typing while the promotion is in flight: no replica yet,
+  // so this journals as a local-only mutation.
+  const client = clientFromState(opened.state);
+  const update = captureEdit(client, (text) => text.insert(text.length, 'typed during promotion\n'));
+  docs.applyDocMutations(fencePath, [{ mutationId: 'mut_during_promotion1', update }]);
+  assert.equal(getMutation(opened.resource, 'mut_during_promotion1').sharedResourceId, null);
+
+  const [claimed] = claimPromotions();
+  acknowledgePromotion('prm_fencefencefence1', {
+    resourceId: fenceResourceId,
+    authorityEpoch: 1,
+    headVersion: 0,
+    snapshotVersion: 0,
+    snapshotKey: `shared/${fenceResourceId}/snapshots/v0/${claimed.frame.snapshotChecksum}.bin`,
+    snapshotChecksum: claimed.frame.snapshotChecksum,
+  });
+
+  const rehomed = getMutation(`resource:${fenceResourceId}`, 'mut_during_promotion1');
+  assert.equal(rehomed.sharedResourceId, fenceResourceId);
+  assert.equal(rehomed.authorityEpoch, 1);
+  assert.equal(rehomed.baseCloudVersion, 0);
+  assert.equal(rehomed.deviceId, process.env.AMALGM_DEVICE_ID);
+  const claims = claimCloudMutations().filter((claim) => claim.envelope.resourceId === fenceResourceId);
+  assert.deepEqual(claims.map((claim) => claim.envelope.mutationId), ['mut_during_promotion1']);
+});
+
+// Truthful saves: a failed file write must fail the edit — no journal
+// completion, no event, no acknowledgement — and recover once disk works.
+test('a failed shared-file write reports failure and recovers on reopen', async () => {
+  const beforeEvents = listEventsAfter(0).length;
+  const client = clientFromState(docs.openDoc(target).state);
+  const update = captureEdit(client, (text) => text.insert(text.length, 'Unwritable\n'));
+
+  fs.chmodSync(docDir, 0o555);
+  try {
+    assert.throws(
+      () => docs.applyDocMutations(target, [{ mutationId: 'mut_unwritable_00001', update }]),
+      /EACCES|EPERM/,
+    );
+  } finally {
+    fs.chmodSync(docDir, 0o755);
+  }
+  assert.equal(listEventsAfter(0).length, beforeEvents, 'a failed save must not project an event');
+  const stalled = getMutation(`resource:${resourceId}`, 'mut_unwritable_00001');
+  assert.equal(stalled.state, 'saving-local');
+  assert.match(stalled.lastError, /EACCES|EPERM/);
+
+  docs.closeAllDocs();
+  docs.openDoc(target);
+  assert.equal(getMutation(`resource:${resourceId}`, 'mut_unwritable_00001').state, 'saved-local');
+  assert.match(fs.readFileSync(target, 'utf8'), /Unwritable\n$/);
+
+  // Drain the outbox so later tests observe only their own deliveries.
+  claimCloudMutations();
+  acknowledgeCloudMutation(resourceId, 'mut_unwritable_00001', {
+    version: getReplicaByResourceId(resourceId).appliedVersion + 1,
+    committedAt: '2026-07-15T20:00:01.500Z',
+  });
+});
+
+// Truthful saves, the retry-while-open half: after a failed flush the desired
+// text already lives in memory, so a naive retry looks like a noop. The retry
+// must instead settle the ORIGINAL mutation — file current, journal row
+// completed, exactly one event, exactly one cloud delivery — before answering.
+test('retrying a failed whole-text write settles the original mutation: disk, journal, event, outbox agree', () => {
+  const ours = docs.getDocText(target);
+  const nextText = `${ours}Retry survives\n`;
+  const baseHash = sha256(ours);
+  const beforeDisk = fs.readFileSync(target, 'utf8');
+
+  fs.chmodSync(docDir, 0o555);
+  try {
+    assert.throws(() => docs.writeDocText(target, nextText, { baseHash }), /EACCES|EPERM/);
+  } finally {
+    fs.chmodSync(docDir, 0o755);
+  }
+  assert.equal(fs.readFileSync(target, 'utf8'), beforeDisk, 'failed save leaves the file untouched');
+  const [stuck] = listMutations({ state: 'saving-local' });
+  assert.ok(stuck, 'the failed write is journaled, not lost');
+
+  const retried = docs.writeDocText(target, nextText, { baseHash });
+  assert.equal(retried.sha256, sha256(nextText));
+  assert.equal(fs.readFileSync(target, 'utf8'), nextText, 'retry really saved the file');
+  assert.equal(getMutation(stuck.channelId, stuck.mutationId).state, 'saved-local');
+  assert.equal(
+    listEventsAfter(0).filter((event) => event.mutationId === stuck.mutationId).length,
+    1,
+    'exactly one projected event for the settled mutation',
+  );
+  const claims = claimCloudMutations().filter((claim) => claim.envelope.resourceId === resourceId);
+  assert.deepEqual(claims.map((claim) => claim.envelope.mutationId), [stuck.mutationId]);
+  acknowledgeCloudMutation(resourceId, stuck.mutationId, {
+    version: getReplicaByResourceId(resourceId).appliedVersion + 1,
+    committedAt: '2026-07-15T20:00:02.000Z',
+  });
+});
+
+// A live edit must not strip the file's permission bits: replace-by-rename
+// carries the original mode onto the replacement inode.
+test('an executable file stays executable through a live write', () => {
+  fs.chmodSync(target, 0o755);
+  const ours = docs.getDocText(target);
+  docs.writeDocText(target, `${ours}chmod check\n`, { baseHash: sha256(ours) });
+  assert.equal(fs.statSync(target).mode & 0o777, 0o755);
+
+  const claims = claimCloudMutations().filter((claim) => claim.envelope.resourceId === resourceId);
+  acknowledgeCloudMutation(resourceId, claims[0].envelope.mutationId, {
+    version: getReplicaByResourceId(resourceId).appliedVersion + 1,
+    committedAt: '2026-07-15T20:00:03.000Z',
+  });
+});