amalgm 0.1.239 → 0.1.241

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

@@ -5,6 +5,7 @@ const assert = require('node:assert/strict');
 const fs = require('fs');
 const os = require('os');
 const path = require('path');
+const { spawn } = require('node:child_process');
 
 const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'amalgm-shared-replica-test-'));
 process.env.AMALGM_DIR = path.join(tempRoot, '.amalgm');
@@ -13,13 +14,14 @@ process.env.AMALGM_DEVICE_ID = 'device-shared-replica-test';
 process.env.AMALGM_EVENT_LOG_PRUNE_INTERVAL_MS = '0';
 
 const Y = require('yjs');
-const { closeLocalDb } = require('../state/db');
+const { closeLocalDb, openLocalDb } = require('../state/db');
 const docs = require('../state/docs');
 const { listEventsAfter, subscribeStateEvents } = require('../state/events');
 const {
   acknowledgeCloudMutation,
   claimCloudMutations,
   getMutation,
+  journalCloudMutation,
   journalMutation,
   listMutations,
 } = require('../state/mutations');
@@ -61,6 +63,27 @@ function captureEdit(doc, mutate) {
   return Buffer.from(captured).toString('base64');
 }
 
+function acknowledgeAndApplyClaim(claim, version, committedAt) {
+  acknowledgeCloudMutation(claim.envelope.resourceId, claim.envelope.mutationId, {
+    version,
+    committedAt,
+  });
+  return docs.applyCloudDocMutation({
+    envelope: claim.envelope,
+    version,
+    committedAt,
+  });
+}
+
+function writeFromAnotherProcessAfter(file, text, delayMs) {
+  return spawn(process.execPath, [
+    '-e',
+    'const fs=require("fs");'
+      + `setTimeout(()=>fs.writeFileSync(${JSON.stringify(file)},`
+      + `${JSON.stringify(text)},"utf8"),${delayMs});`,
+  ], { stdio: 'ignore' });
+}
+
 test.after(() => {
   docs.closeAllDocs();
   closeLocalDb();
@@ -151,10 +174,25 @@ test('batched surface edits retain separate IDs/versions and recipient file prec
     version: 1,
     committedAt: '2026-07-14T20:00:00.000Z',
   });
+  assert.equal(
+    getReplicaByResourceId(resourceId).appliedVersion,
+    0,
+    'an acknowledgement records order; the official inbox advances it',
+  );
+  docs.applyCloudDocMutation({
+    envelope: claims[0].envelope,
+    version: 1,
+    committedAt: '2026-07-14T20:00:00.000Z',
+  });
   acknowledgeCloudMutation(resourceId, 'mut_shared_batch_002', {
     version: 2,
     committedAt: '2026-07-14T20:00:01.000Z',
   });
+  docs.applyCloudDocMutation({
+    envelope: claims[1].envelope,
+    version: 2,
+    committedAt: '2026-07-14T20:00:01.000Z',
+  });
   assert.equal(getReplicaByResourceId(resourceId).appliedVersion, 2);
 
   const remoteUpdate = captureEdit(client, (text) => text.insert(text.length, 'Remote\n'));
@@ -253,10 +291,153 @@ test('reopen recovers a journaled shared edit that died before materialization',
 
   // 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',
+  acknowledgeAndApplyClaim(claim, 4, '2026-07-14T20:00:04.000Z');
+});
+
+test('restart merges a downtime disk edit over the last proven base before official recovery', () => {
+  const restartResourceId = 'shr_restartbasefold1';
+  const restartPath = path.join(docDir, 'restart-base-fold.md');
+  fs.writeFileSync(restartPath, '', 'utf8');
+  const cloud = new Y.Doc();
+  cloud.getText('content').insert(0, 'left\nright\n');
+  const snapshot = Buffer.from(Y.encodeStateAsUpdate(cloud));
+  const checksum = require('crypto').createHash('sha256').update(snapshot).digest('hex');
+  docs.installCloudDocSnapshot(restartPath, {
+    resourceId: restartResourceId,
+    authorityEpoch: 1,
+    headVersion: 0,
+    snapshotVersion: 0,
+    snapshotChecksum: checksum,
+    snapshotBase64: snapshot.toString('base64'),
+    contract: 'text-yjs@1',
+    schemaVersion: 1,
   });
+  const opened = docs.openDoc(restartPath);
+  const remote = clientFromState(opened.state);
+  const remoteUpdate = captureEdit(remote, (text) => {
+    text.insert('left\nright'.length, ' cloud');
+  });
+  docs.closeAllDocs();
+
+  const base = require('../state/doc-disk').observe(restartPath);
+  journalCloudMutation({
+    envelope: {
+      resourceId: restartResourceId,
+      authorityEpoch: 1,
+      mutationId: 'mut_restart_base_cloud_001',
+      deviceId: 'device-remote-restart-base',
+      baseVersion: 0,
+      contract: 'text-yjs@1',
+      schemaVersion: 1,
+      operationKind: 'yjs.update',
+      operation: { kind: 'yjs.update', update: remoteUpdate },
+    },
+    version: 1,
+    committedAt: '2026-07-28T10:30:00.000Z',
+    localResource: opened.resource,
+  }, {
+    persist(database, mutation) {
+      require('../state/doc-disk').insertBase(database, mutation, base, 'doc:cloud');
+    },
+  });
+
+  // Model the later crash window too: the desired official Y.Doc target was
+  // persisted, but its native file transaction never crossed. The persisted
+  // hash still names the old disk base, so recovery needs the exact base text
+  // sealed in the physical plan rather than trying to recover it from the
+  // newer Y.Doc state.
+  const persistedTarget = clientFromState(opened.state);
+  Y.applyUpdate(persistedTarget, new Uint8Array(Buffer.from(remoteUpdate, 'base64')));
+  openLocalDb().prepare('UPDATE doc_states SET state = ? WHERE path = ?').run(
+    Buffer.from(Y.encodeStateAsUpdate(persistedTarget)),
+    restartPath,
+  );
+
+  // This save is born while the process is down and changes only the other
+  // line. Recovery must merge both deltas over the persisted physical base.
+  fs.writeFileSync(restartPath, 'left local\nright\n', 'utf8');
+  const recovered = docs.openDoc(restartPath);
+  const finalText = fs.readFileSync(restartPath, 'utf8');
+  assert.equal(finalText, 'left local\nright cloud\n');
+  assert.equal(clientFromState(recovered.state).getText('content').toString(), finalText);
+  assert.equal(getReplicaByResourceId(restartResourceId).appliedVersion, 1);
+
+  const rows = listMutations({ localResource: opened.resource });
+  const cloudRow = rows.find(
+    (mutation) => mutation.mutationId === 'mut_restart_base_cloud_001',
+  );
+  assert.equal(cloudRow.state, 'synced');
+  const localRows = rows.filter((mutation) => (
+    mutation.origin === 'local'
+    && mutation.mutationId !== 'mut_restart_base_cloud_001'
+  ));
+  assert.equal(localRows.length, 1, 'one downtime disk save receives one local mutation ID');
+  assert.ok(
+    claimCloudMutations().some((claim) => (
+      claim.envelope.resourceId === restartResourceId
+      && claim.envelope.mutationId === localRows[0].mutationId
+    )),
+    'the merged downtime save remains in the outbox',
+  );
+});
+
+test('a held viewer disk save blocks official materialization instead of becoming permission', () => {
+  const heldResourceId = 'shr_viewerheldsave01';
+  const heldPath = path.join(docDir, 'viewer-held-save.md');
+  fs.writeFileSync(heldPath, '', 'utf8');
+  const cloud = new Y.Doc();
+  cloud.getText('content').insert(0, 'official base\n');
+  const snapshot = Buffer.from(Y.encodeStateAsUpdate(cloud));
+  const checksum = require('crypto').createHash('sha256').update(snapshot).digest('hex');
+  docs.installCloudDocSnapshot(heldPath, {
+    resourceId: heldResourceId,
+    authorityEpoch: 1,
+    headVersion: 0,
+    snapshotVersion: 0,
+    snapshotChecksum: checksum,
+    snapshotBase64: snapshot.toString('base64'),
+    contract: 'text-yjs@1',
+    schemaVersion: 1,
+  });
+  const opened = docs.openDoc(heldPath);
+  const remote = clientFromState(opened.state);
+  const remoteUpdate = captureEdit(remote, (text) => text.insert(text.length, 'cloud edit\n'));
+  const entry = docs._private.openDocs.get(opened.path);
+  const accessStore = require('../workspace/access-store');
+  const originalCurrentUserRole = accessStore.currentUserRole;
+  entry.nodeId = '33333333-3333-4333-8333-333333333333';
+  accessStore.currentUserRole = () => 'viewer';
+  fs.writeFileSync(heldPath, 'LOCAL SAVE\n', 'utf8');
+
+  try {
+    assert.throws(() => docs.applyCloudDocMutation({
+      envelope: {
+        resourceId: heldResourceId,
+        authorityEpoch: 1,
+        mutationId: 'mut_cloud_blocked_by_viewer_save',
+        deviceId: 'device-remote-viewer-held',
+        baseVersion: 0,
+        contract: 'text-yjs@1',
+        schemaVersion: 1,
+        operationKind: 'yjs.update',
+        operation: { kind: 'yjs.update', update: remoteUpdate },
+      },
+      version: 1,
+      committedAt: '2026-07-28T11:00:00.000Z',
+    }), /disk change is held: forbidden/);
+    assert.equal(fs.readFileSync(heldPath, 'utf8'), 'LOCAL SAVE\n');
+    assert.equal(getReplicaByResourceId(heldResourceId).appliedVersion, 0);
+    assert.equal(
+      getMutation(`resource:${heldResourceId}`, 'mut_cloud_blocked_by_viewer_save'),
+      null,
+      'the official cursor row is not journaled before held local bytes are resolved',
+    );
+  } finally {
+    accessStore.currentUserRole = originalCurrentUserRole;
+    entry.nodeId = null;
+    fs.writeFileSync(heldPath, 'official base\n', 'utf8');
+    docs._private.verifyOpenDocs();
+  }
 });
 
 test('authorized snapshot attachment creates the recipient file before its UI event', () => {
@@ -310,11 +491,11 @@ function sha256(text) {
 
 // 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 () => {
+test('bounded verification puts a dropped external disk write in the cloud outbox', () => {
   docs.openDoc(target);
   const beforeText = fs.readFileSync(target, 'utf8');
   fs.writeFileSync(target, `${beforeText}From vim\n`, 'utf8');
-  await sleep(700);
+  docs._private.verifyOpenDocs();
 
   assert.equal(docs.getDocText(target), `${beforeText}From vim\n`);
   const claims = claimCloudMutations().filter((claim) => claim.envelope.resourceId === resourceId);
@@ -322,10 +503,11 @@ test('an external disk write on a shared doc enters the cloud outbox', async ()
   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',
-  });
+  acknowledgeAndApplyClaim(
+    claims[0],
+    getReplicaByResourceId(resourceId).appliedVersion + 1,
+    '2026-07-15T20:00:00.000Z',
+  );
 });
 
 // One door: the whole-text write API (agents/tools) on a shared doc.
@@ -338,10 +520,11 @@ test('a versioned whole-text write on a shared doc enters the cloud outbox', ()
   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',
-  });
+  acknowledgeAndApplyClaim(
+    claims[0],
+    getReplicaByResourceId(resourceId).appliedVersion + 1,
+    '2026-07-15T20:00:01.000Z',
+  );
 });
 
 // Promotion fence: edits made while sharing is being set up may not strand.
@@ -388,6 +571,165 @@ test('edits journaled during the promotion window are re-homed into the outbox',
   assert.deepEqual(claims.map((claim) => claim.envelope.mutationId), ['mut_during_promotion1']);
 });
 
+test('promotion rehomes a saving mutation and its physical plan as one identity', () => {
+  const planResourceId = 'shr_planrehomecrash1';
+  const planPath = path.join(docDir, 'promotion-plan-rehome.md');
+  fs.writeFileSync(planPath, 'promotion base\n', 'utf8');
+  const opened = docs.openDoc(planPath);
+  const queued = enqueuePromotion({
+    promotionId: 'prm_plan_rehome_crash_01',
+    resourceId: planResourceId,
+    localResource: opened.resource,
+    localPath: opened.path,
+    contract: 'text-yjs@1',
+    schemaVersion: 1,
+    snapshotBase64: opened.state,
+    contentBytes: fs.statSync(planPath).size,
+  }).promotion;
+  const client = clientFromState(opened.state);
+  const update = captureEdit(client, (text) => text.insert(text.length, 'survives crash\n'));
+  const mutationId = 'mut_promotion_plan_rehome_01';
+  docs._private.setDiskTransactionTestHooks({ crashAfterInstall: true });
+  try {
+    assert.throws(
+      () => docs.applyDocMutations(planPath, [{ mutationId, update }]),
+      /native file transaction failed/,
+    );
+  } finally {
+    docs._private.setDiskTransactionTestHooks();
+  }
+  const docDisk = require('../state/doc-disk');
+  assert.ok(docDisk.get(opened.resource, mutationId));
+
+  acknowledgePromotion(queued.promotionId, {
+    resourceId: planResourceId,
+    authorityEpoch: 1,
+    headVersion: 0,
+    snapshotVersion: 0,
+    snapshotChecksum: queued.snapshotChecksum,
+    snapshotKey: `shared/${planResourceId}/snapshot.bin`,
+  });
+  const sharedChannel = `resource:${planResourceId}`;
+  assert.equal(docDisk.get(opened.resource, mutationId), null);
+  assert.ok(docDisk.get(sharedChannel, mutationId), 'the same physical plan follows the journal row');
+  assert.equal(getMutation(sharedChannel, mutationId).state, 'saving-local');
+
+  assert.doesNotThrow(() => docs.closeAllDocs());
+  const reopened = docs.openDoc(planPath);
+  assert.match(clientFromState(reopened.state).getText('content').toString(), /survives crash\n/);
+  assert.match(fs.readFileSync(planPath, 'utf8'), /survives crash\n/);
+  assert.equal(getMutation(sharedChannel, mutationId).state, 'saved-local');
+});
+
+test('an edit during first attachment stays overlay and joins after the snapshot', () => {
+  const attachedResourceId = 'shr_attachfenceedit1';
+  const attachedPath = path.join(docDir, 'attachment-fence-edit.md');
+  fs.writeFileSync(attachedPath, '', 'utf8');
+  const queued = enqueueAttachment({
+    attachmentId: 'att_first_attachment_fence_01',
+    resourceId: attachedResourceId,
+    localPath: attachedPath,
+  }).attachment;
+  const local = docs.writeDocText(attachedPath, 'local during request\n', {
+    baseHash: sha256(''),
+  });
+  const cloud = new Y.Doc();
+  cloud.getText('content').insert(0, 'official snapshot\n');
+  const snapshot = Buffer.from(Y.encodeStateAsUpdate(cloud));
+  const checksum = require('crypto').createHash('sha256').update(snapshot).digest('hex');
+
+  acknowledgeAttachment(queued.attachmentId, {
+    resourceId: attachedResourceId,
+    authorityEpoch: 1,
+    headVersion: 0,
+    snapshotVersion: 0,
+    snapshotChecksum: checksum,
+    snapshotBase64: snapshot.toString('base64'),
+    contract: 'text-yjs@1',
+    schemaVersion: 1,
+  });
+  const finalText = fs.readFileSync(attachedPath, 'utf8');
+  assert.match(finalText, /official snapshot\n/);
+  assert.match(finalText, /local during request\n/);
+  const rehomed = getMutation(`resource:${attachedResourceId}`, local.mutationId);
+  assert.ok(rehomed);
+  assert.equal(rehomed.sharedResourceId, attachedResourceId);
+  const claim = claimCloudMutations().find(
+    (item) => item.envelope.mutationId === local.mutationId,
+  );
+  assert.ok(claim, 'post-request local work joins the new cloud outbox');
+  acknowledgeAndApplyClaim(claim, 1, '2026-07-28T11:10:00.000Z');
+});
+
+test('a legacy nullable attachment fence migrates to durable zero', () => {
+  const Database = require('better-sqlite3');
+  const legacy = new Database(':memory:');
+  try {
+    legacy.exec(`
+      CREATE TABLE shared_resource_attachments (
+        attachment_id TEXT PRIMARY KEY,
+        resource_id TEXT NOT NULL UNIQUE,
+        local_path TEXT NOT NULL UNIQUE,
+        attachment_state TEXT NOT NULL DEFAULT 'pending',
+        attempt_count INTEGER NOT NULL DEFAULT 0,
+        next_attempt_at TEXT,
+        last_error TEXT,
+        journal_cursor INTEGER,
+        created_at TEXT NOT NULL,
+        updated_at TEXT NOT NULL
+      );
+      INSERT INTO shared_resource_attachments (
+        attachment_id,
+        resource_id,
+        local_path,
+        journal_cursor,
+        created_at,
+        updated_at
+      ) VALUES (
+        'att_legacy_nullable_fence_01',
+        'shr_legacyfence0001',
+        '/tmp/legacy-fence.md',
+        NULL,
+        '2026-07-28T00:00:00.000Z',
+        '2026-07-28T00:00:00.000Z'
+      );
+    `);
+    require('../state/db')._private.migrate(legacy);
+
+    const cursor = legacy.prepare(
+      'PRAGMA table_info(shared_resource_attachments)',
+    ).all().find((column) => column.name === 'journal_cursor');
+    assert.equal(cursor.notnull, 1);
+    assert.equal(String(cursor.dflt_value), '0');
+    assert.equal(
+      legacy.prepare(`
+        SELECT journal_cursor AS cursor
+        FROM shared_resource_attachments
+        WHERE attachment_id = 'att_legacy_nullable_fence_01'
+      `).get().cursor,
+      0,
+    );
+    assert.throws(() => legacy.prepare(`
+      INSERT INTO shared_resource_attachments (
+        attachment_id,
+        resource_id,
+        local_path,
+        journal_cursor,
+        created_at,
+        updated_at
+      ) VALUES (?, ?, ?, NULL, ?, ?)
+    `).run(
+      'att_legacy_null_rejected_01',
+      'shr_legacynull00001',
+      '/tmp/legacy-null-rejected.md',
+      '2026-07-28T00:00:00.000Z',
+      '2026-07-28T00:00:00.000Z',
+    ), /NOT NULL/);
+  } finally {
+    legacy.close();
+  }
+});
+
 // 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 () => {
@@ -399,7 +741,7 @@ test('a failed shared-file write reports failure and recovers on reopen', async
   try {
     assert.throws(
       () => docs.applyDocMutations(target, [{ mutationId: 'mut_unwritable_00001', update }]),
-      /EACCES|EPERM/,
+      /EACCES|EPERM|permission denied/,
     );
   } finally {
     fs.chmodSync(docDir, 0o755);
@@ -407,7 +749,7 @@ test('a failed shared-file write reports failure and recovers on reopen', async
   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/);
+  assert.match(stalled.lastError, /EACCES|EPERM|permission denied/);
 
   docs.closeAllDocs();
   docs.openDoc(target);
@@ -415,11 +757,14 @@ test('a failed shared-file write reports failure and recovers on reopen', async
   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',
-  });
+  const [claim] = claimCloudMutations().filter(
+    (item) => item.envelope.mutationId === 'mut_unwritable_00001',
+  );
+  acknowledgeAndApplyClaim(
+    claim,
+    getReplicaByResourceId(resourceId).appliedVersion + 1,
+    '2026-07-15T20:00:01.500Z',
+  );
 });
 
 // Truthful saves, the retry-while-open half: after a failed flush the desired
@@ -434,7 +779,10 @@ test('retrying a failed whole-text write settles the original mutation: disk, jo
 
   fs.chmodSync(docDir, 0o555);
   try {
-    assert.throws(() => docs.writeDocText(target, nextText, { baseHash }), /EACCES|EPERM/);
+    assert.throws(
+      () => docs.writeDocText(target, nextText, { baseHash }),
+      /EACCES|EPERM|permission denied/,
+    );
   } finally {
     fs.chmodSync(docDir, 0o755);
   }
@@ -453,10 +801,11 @@ test('retrying a failed whole-text write settles the original mutation: disk, jo
   );
   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',
-  });
+  acknowledgeAndApplyClaim(
+    claims[0],
+    getReplicaByResourceId(resourceId).appliedVersion + 1,
+    '2026-07-15T20:00:02.000Z',
+  );
 });
 
 // A live edit must not strip the file's permission bits: replace-by-rename
@@ -468,10 +817,11 @@ test('an executable file stays executable through a live write', () => {
   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',
-  });
+  acknowledgeAndApplyClaim(
+    claims[0],
+    getReplicaByResourceId(resourceId).appliedVersion + 1,
+    '2026-07-15T20:00:03.000Z',
+  );
 });
 
 // Compaction on the authority prunes official rows the moment a verified
@@ -530,6 +880,71 @@ test('a pruned-tail replica rehydrates: snapshot merge keeps unsynced local edit
   assert.notEqual(pending.state, 'synced');
 });
 
+test('equal snapshot version with different bytes fails before state or cursor movement', () => {
+  const equalResourceId = 'shr_equalsnapshot001';
+  const equalPath = path.join(docDir, 'equal-snapshot.md');
+  fs.writeFileSync(equalPath, '', 'utf8');
+  const first = new Y.Doc();
+  first.getText('content').insert(0, 'state A\n');
+  const firstBytes = Buffer.from(Y.encodeStateAsUpdate(first));
+  const firstChecksum = require('crypto').createHash('sha256').update(firstBytes).digest('hex');
+  docs.installCloudDocSnapshot(equalPath, {
+    resourceId: equalResourceId,
+    authorityEpoch: 1,
+    headVersion: 1,
+    snapshotVersion: 1,
+    snapshotChecksum: firstChecksum,
+    snapshotBase64: firstBytes.toString('base64'),
+    contract: 'text-yjs@1',
+    schemaVersion: 1,
+  });
+  const beforeEvents = listEventsAfter(0).length;
+  const second = new Y.Doc();
+  second.getText('content').insert(0, 'state B\n');
+  const secondBytes = Buffer.from(Y.encodeStateAsUpdate(second));
+  const secondChecksum = require('crypto').createHash('sha256').update(secondBytes).digest('hex');
+
+  assert.throws(() => docs.installCloudDocSnapshot(equalPath, {
+    resourceId: equalResourceId,
+    authorityEpoch: 1,
+    headVersion: 1,
+    snapshotVersion: 1,
+    snapshotChecksum: secondChecksum,
+    snapshotBase64: secondBytes.toString('base64'),
+    contract: 'text-yjs@1',
+    schemaVersion: 1,
+  }), /unequal state at version 1/);
+  assert.equal(fs.readFileSync(equalPath, 'utf8'), 'state A\n');
+  assert.equal(getReplicaByResourceId(equalResourceId).snapshotChecksum, firstChecksum);
+  assert.equal(listEventsAfter(0).length, beforeEvents);
+
+  openLocalDb().prepare(`
+    UPDATE shared_resource_replicas SET applied_version = 3 WHERE resource_id = ?
+  `).run(equalResourceId);
+  assert.throws(() => docs.installCloudDocSnapshot(equalPath, {
+    resourceId: equalResourceId,
+    authorityEpoch: 1,
+    headVersion: 3,
+    snapshotVersion: 1,
+    snapshotChecksum: secondChecksum,
+    snapshotBase64: secondBytes.toString('base64'),
+    contract: 'text-yjs@1',
+    schemaVersion: 1,
+  }), /unequal state at version 1/);
+  assert.throws(() => docs.installCloudDocSnapshot(equalPath, {
+    resourceId: equalResourceId,
+    authorityEpoch: 1,
+    headVersion: 3,
+    snapshotVersion: 4,
+    snapshotChecksum: secondChecksum,
+    snapshotBase64: secondBytes.toString('base64'),
+    contract: 'text-yjs@1',
+    schemaVersion: 1,
+  }), /cannot exceed headVersion/);
+  assert.equal(fs.readFileSync(equalPath, 'utf8'), 'state A\n');
+  assert.equal(getReplicaByResourceId(equalResourceId).appliedVersion, 3);
+});
+
 test('a promotion-born replica (which never attached) gets an attachment row for rehydration', () => {
   const { requestRehydration } = require('../state/attachments');
   const requested = requestRehydration({ resourceId });
@@ -572,3 +987,316 @@ test('revoked authority pauses the outbox and a successful rejoin resumes it', (
     'the same durable edit resumes after authority is restored',
   );
 });
+
+test('cloud apply first captures an unsent disk save and sends no machine-local metadata', () => {
+  const opened = docs.openDoc(target);
+  const beforeText = fs.readFileSync(target, 'utf8');
+  const priorEvents = listEventsAfter(0);
+  const beforeSeq = priorEvents.length ? priorEvents[priorEvents.length - 1].seq : 0;
+  fs.writeFileSync(target, `disk-before-cloud\n${beforeText}`, 'utf8');
+
+  const mutations = require('../state/mutations');
+  const originalCommit = mutations.commitLocalMutation;
+  mutations.commitLocalMutation = () => {
+    throw new Error('simulated local journal outage');
+  };
+  try {
+    docs._private.verifyOpenDocs();
+  } finally {
+    mutations.commitLocalMutation = originalCommit;
+  }
+  assert.equal(docs.getDocText(target), beforeText);
+
+  const remote = clientFromState(opened.state);
+  const update = captureEdit(remote, (text) => text.insert(text.length, 'cloud-after-disk\n'));
+  const beforeVersion = getReplicaByResourceId(resourceId).appliedVersion;
+  docs.applyCloudDocMutation({
+    envelope: {
+      resourceId,
+      authorityEpoch: getReplicaByResourceId(resourceId).authorityEpoch,
+      mutationId: 'mut_cloud_after_disk_1',
+      deviceId: 'device-remote-disk-capture',
+      baseVersion: beforeVersion,
+      contract: 'text-yjs@1',
+      schemaVersion: 1,
+      operationKind: 'yjs.update',
+      operation: { kind: 'yjs.update', update },
+    },
+    version: beforeVersion + 1,
+    committedAt: '2026-07-28T08:00:00.000Z',
+  });
+
+  const finalText = fs.readFileSync(target, 'utf8');
+  assert.match(finalText, /^disk-before-cloud\n/);
+  assert.match(finalText, /cloud-after-disk\n/);
+  assert.equal(getReplicaByResourceId(resourceId).appliedVersion, beforeVersion + 1);
+  const diskEvent = listEventsAfter(beforeSeq).find((event) => (
+    event.resource === opened.resource && event.source === 'doc:disk'
+  ));
+  assert.ok(diskEvent, 'the disk save received its own durable mutation identity');
+  const diskClaim = claimCloudMutations().find(
+    (claim) => claim.envelope.mutationId === diskEvent.mutationId,
+  );
+  assert.ok(diskClaim, 'the formerly unsent disk save is now in the shared outbox');
+  assert.deepEqual(Object.keys(diskClaim.envelope.operation).sort(), ['kind', 'update']);
+});
+
+test('cloud materialization CAS keeps a disk save that lands at the install boundary', () => {
+  const opened = docs.openDoc(target);
+  const beforeText = fs.readFileSync(target, 'utf8');
+  const remote = clientFromState(opened.state);
+  const update = captureEdit(remote, (text) => text.insert(text.length, 'cloud-cas\n'));
+  const beforeVersion = getReplicaByResourceId(resourceId).appliedVersion;
+  const child = writeFromAnotherProcessAfter(target, `disk-cas\n${beforeText}`, 75);
+  docs._private.setDiskTransactionTestHooks({ pauseBeforeInstall: 350 });
+  try {
+    docs.applyCloudDocMutation({
+      envelope: {
+        resourceId,
+        authorityEpoch: getReplicaByResourceId(resourceId).authorityEpoch,
+        mutationId: 'mut_cloud_cas_race_1',
+        deviceId: 'device-remote-cas',
+        baseVersion: beforeVersion,
+        contract: 'text-yjs@1',
+        schemaVersion: 1,
+        operationKind: 'yjs.update',
+        operation: { kind: 'yjs.update', update },
+      },
+      version: beforeVersion + 1,
+      committedAt: '2026-07-28T08:00:01.000Z',
+    });
+  } finally {
+    docs._private.setDiskTransactionTestHooks();
+  }
+  child.unref();
+  const finalText = fs.readFileSync(target, 'utf8');
+  assert.match(finalText, /^disk-cas\n/);
+  assert.match(finalText, /cloud-cas\n/);
+  assert.equal(getReplicaByResourceId(resourceId).appliedVersion, beforeVersion + 1);
+});
+
+test('snapshot CAS preserves and re-homes a local save racing first attachment', () => {
+  const recipientResourceId = 'shr_ponmlkjihgfedcba';
+  const recipientPath = path.join(docDir, 'snapshot-cas-recipient.md');
+  fs.writeFileSync(recipientPath, '', 'utf8');
+  const cloud = new Y.Doc();
+  cloud.getText('content').insert(0, 'official snapshot\n');
+  const snapshot = Buffer.from(Y.encodeStateAsUpdate(cloud));
+  const checksum = require('crypto').createHash('sha256').update(snapshot).digest('hex');
+  const child = writeFromAnotherProcessAfter(recipientPath, 'local during snapshot\n', 75);
+
+  docs._private.setDiskTransactionTestHooks({ pauseBeforeInstall: 350 });
+  try {
+    docs.installCloudDocSnapshot(recipientPath, {
+      resourceId: recipientResourceId,
+      authorityEpoch: 1,
+      headVersion: 8,
+      snapshotVersion: 8,
+      snapshotChecksum: checksum,
+      snapshotBase64: snapshot.toString('base64'),
+      contract: 'text-yjs@1',
+      schemaVersion: 1,
+    });
+  } finally {
+    docs._private.setDiskTransactionTestHooks();
+  }
+  child.unref();
+  const finalText = fs.readFileSync(recipientPath, 'utf8');
+  assert.match(finalText, /official snapshot\n/);
+  assert.match(finalText, /local during snapshot\n/);
+  assert.equal(getReplicaByResourceId(recipientResourceId).appliedVersion, 8);
+  assert.ok(
+    claimCloudMutations().some((claim) => (
+      claim.envelope.resourceId === recipientResourceId
+      && claim.envelope.operationKind === 'yjs.update'
+    )),
+    'the local save born during attachment is re-homed into the new outbox',
+  );
+});
+
+test('snapshot plan pins the captured file instead of adopting a later save', () => {
+  const recipientResourceId = 'shr_captureplanrace1';
+  const recipientPath = path.join(docDir, 'snapshot-capture-plan-recipient.md');
+  fs.writeFileSync(recipientPath, '', 'utf8');
+  const cloud = new Y.Doc();
+  cloud.getText('content').insert(0, 'official snapshot\n');
+  const snapshot = Buffer.from(Y.encodeStateAsUpdate(cloud));
+  const checksum = require('crypto').createHash('sha256').update(snapshot).digest('hex');
+  const child = writeFromAnotherProcessAfter(
+    recipientPath,
+    'local after snapshot capture\n',
+    75,
+  );
+
+  docs._private.setDiskTransactionTestHooks({ pauseAfterSnapshotCapture: 350 });
+  try {
+    docs.installCloudDocSnapshot(recipientPath, {
+      resourceId: recipientResourceId,
+      authorityEpoch: 1,
+      headVersion: 9,
+      snapshotVersion: 9,
+      snapshotChecksum: checksum,
+      snapshotBase64: snapshot.toString('base64'),
+      contract: 'text-yjs@1',
+      schemaVersion: 1,
+    });
+  } finally {
+    docs._private.setDiskTransactionTestHooks();
+  }
+  child.unref();
+
+  const finalText = fs.readFileSync(recipientPath, 'utf8');
+  assert.match(finalText, /official snapshot\n/);
+  assert.match(finalText, /local after snapshot capture\n/);
+  assert.equal(getReplicaByResourceId(recipientResourceId).appliedVersion, 9);
+  assert.ok(
+    claimCloudMutations().some((claim) => (
+      claim.envelope.resourceId === recipientResourceId
+      && claim.envelope.operationKind === 'yjs.update'
+    )),
+    'the save after capture keeps one durable local mutation identity',
+  );
+});
+
+test('snapshot replacement retries share one finite budget', () => {
+  const boundedResourceId = 'shr_snapshotbounded1';
+  const boundedPath = path.join(docDir, 'snapshot-bounded.md');
+  fs.writeFileSync(boundedPath, '', 'utf8');
+  const cloud = new Y.Doc();
+  cloud.getText('content').insert(0, 'never installs\n');
+  const snapshot = Buffer.from(Y.encodeStateAsUpdate(cloud));
+  const checksum = require('crypto').createHash('sha256').update(snapshot).digest('hex');
+  const docDisk = require('../state/doc-disk');
+  const originalCross = docDisk.cross;
+  let attempts = 0;
+  docDisk.cross = () => {
+    attempts += 1;
+    return { status: 'changed', reason: 'simulated continuous replacer' };
+  };
+  try {
+    assert.throws(() => docs.installCloudDocSnapshot(boundedPath, {
+      resourceId: boundedResourceId,
+      authorityEpoch: 1,
+      headVersion: 1,
+      snapshotVersion: 1,
+      snapshotChecksum: checksum,
+      snapshotBase64: snapshot.toString('base64'),
+      contract: 'text-yjs@1',
+      schemaVersion: 1,
+    }), /kept changing during snapshot install/);
+  } finally {
+    docDisk.cross = originalCross;
+  }
+  assert.equal(attempts, 8);
+  assert.equal(docDisk.listSnapshots(docs.docResourceName(boundedPath)).length, 0);
+  assert.equal(fs.readFileSync(boundedPath, 'utf8'), '');
+});
+
+test('snapshot install recovers exactly once after the native helper dies post-install', () => {
+  const recipientResourceId = 'shr_crashrecoverabcd';
+  const recipientPath = path.join(docDir, 'snapshot-crash-recipient.md');
+  fs.writeFileSync(recipientPath, '', 'utf8');
+  const cloud = new Y.Doc();
+  cloud.getText('content').insert(0, 'snapshot survives helper crash\n');
+  const snapshot = Buffer.from(Y.encodeStateAsUpdate(cloud));
+  const checksum = require('crypto').createHash('sha256').update(snapshot).digest('hex');
+  const input = {
+    resourceId: recipientResourceId,
+    authorityEpoch: 1,
+    headVersion: 3,
+    snapshotVersion: 3,
+    snapshotChecksum: checksum,
+    snapshotBase64: snapshot.toString('base64'),
+    contract: 'text-yjs@1',
+    schemaVersion: 1,
+  };
+
+  docs._private.setDiskTransactionTestHooks({ crashAfterInstall: true });
+  try {
+    assert.throws(
+      () => docs.installCloudDocSnapshot(recipientPath, input),
+      /native file transaction failed/,
+    );
+  } finally {
+    docs._private.setDiskTransactionTestHooks();
+  }
+  assert.equal(fs.readFileSync(recipientPath, 'utf8'), 'snapshot survives helper crash\n');
+  assert.equal(getReplicaByResourceId(recipientResourceId), null);
+
+  const snapshotText = fs.readFileSync(recipientPath, 'utf8');
+  docs.writeDocText(
+    recipientPath,
+    `${snapshotText}local write after helper crash\n`,
+    {
+      baseHash: require('crypto').createHash('sha256').update(snapshotText).digest('hex'),
+      mutationId: 'mut_snapshot_crash_local_01',
+    },
+  );
+  const retried = docs.installCloudDocSnapshot(recipientPath, input);
+  assert.equal(retried.duplicate, true);
+  assert.equal(getReplicaByResourceId(recipientResourceId).appliedVersion, 3);
+  assert.equal(
+    fs.readFileSync(recipientPath, 'utf8'),
+    'snapshot survives helper crash\nlocal write after helper crash\n',
+  );
+  assert.equal(
+    getMutation(`resource:${recipientResourceId}`, 'mut_snapshot_crash_local_01')?.mutationId,
+    'mut_snapshot_crash_local_01',
+  );
+  assert.equal(
+    listEventsAfter(0).filter((event) => (
+      event.sharedResourceId === recipientResourceId
+      && event.source === 'doc:cloud-snapshot'
+    )).length,
+    1,
+  );
+});
+
+test('rebasing a physical predecessor also rebases its durable semantic base', () => {
+  const docDisk = require('../state/doc-disk');
+  const file = path.join(docDir, 'rebase-semantic-base.md');
+  fs.writeFileSync(file, 'A\n', 'utf8');
+  const mutation = {
+    channelId: 'doc:rebase-semantic-base',
+    mutationId: 'mut_rebase_semantic_01',
+    localResource: 'doc:rebase-semantic-base',
+  };
+  docDisk.insertBase(openLocalDb(), mutation, docDisk.observe(file), 'doc:write');
+  docDisk.prepare(mutation.channelId, mutation.mutationId, 'B\n');
+  fs.writeFileSync(file, 'B\n', 'utf8');
+  const rebased = docDisk.rebaseExpected(
+    mutation.channelId,
+    mutation.mutationId,
+    docDisk.observe(file),
+  );
+  assert.equal(rebased.baseText, 'B\n');
+  docDisk.cancel(mutation.channelId, mutation.mutationId);
+});
+
+test('legacy restart recovery keeps a newer disk successor over an older saving row', () => {
+  const restartPath = path.join(docDir, 'restart-successor.md');
+  fs.writeFileSync(restartPath, 'base\n', 'utf8');
+  const opened = docs.openDoc(restartPath);
+  const client = clientFromState(opened.state);
+  const update = captureEdit(client, (text) => text.insert(text.length, 'older journal\n'));
+  docs.closeAllDocs();
+
+  journalMutation({
+    channelId: opened.resource,
+    localResource: opened.resource,
+    mutationId: 'mut_restart_successor_1',
+    authorityEpoch: 0,
+    baseCloudVersion: 0,
+    contract: 'text-yjs@1',
+    schemaVersion: 1,
+    operationKind: 'yjs.update',
+    operation: { kind: 'yjs.update', update },
+  });
+  fs.writeFileSync(restartPath, 'newer disk\nbase\n', 'utf8');
+
+  docs.openDoc(restartPath);
+  const recovered = fs.readFileSync(restartPath, 'utf8');
+  assert.match(recovered, /^newer disk\n/);
+  assert.match(recovered, /older journal\n/);
+  assert.equal(getMutation(opened.resource, 'mut_restart_successor_1').state, 'saved-local');
+});