amalgm 0.1.238 → 0.1.240

package/runtime/scripts/amalgm-mcp/tests/code-project-stream.test.js

@@ -24,9 +24,14 @@ fs.writeFileSync(
 const { closeLocalDb } = require('../state/db');
 const attachments = require('../state/attachments');
 const promotions = require('../state/promotions');
+const replicas = require('../state/replicas');
+const mutations = require('../state/mutations');
 const shared = require('../state/shared-rest');
 const projectStream = require('../workspace/project-stream');
 
+const PROJECT = '018f0000-0000-7000-8000-00000000c0de';
+const HEAD = '1'.repeat(40);
+
 test.after(() => {
   closeLocalDb();
   fs.rmSync(tempRoot, { recursive: true, force: true });
@@ -41,17 +46,62 @@ function call(handler, body) {
   });
 }
 
-function record(project, machine, mutationId, marker) {
+function clone(value) {
+  return JSON.parse(JSON.stringify(value));
+}
+
+function chunks(byte = 'a', bytes = 1) {
+  const list = [{ sha256: byte.repeat(64), bytes }];
   return {
-    wall: projectStream.WALL_CONTRACT,
-    project,
-    machine,
-    mutationId,
-    publishedAt: '2026-07-26T12:00:00.000Z',
-    cards: [{ marker }],
+    checksum: crypto.createHash('sha256').update(Buffer.from(JSON.stringify(list))).digest('hex'),
+    bytes,
+    chunks: list,
+  };
+}
+
+function bundle(oid = HEAD, byte = 'a') {
+  return {
+    kind: 'bundle',
+    contract: projectStream.BUNDLE_CONTRACT,
+    resourceId: PROJECT,
+    oid,
+    ref: `refs/amalgm/exports/${oid}`,
+    ...chunks(byte),
+  };
+}
+
+function cleanValue() {
+  return { revision: null, indexDiff: '', worktreeDiff: '' };
+}
+
+function cardSet() {
+  return {
+    kind: 'card.set',
+    card: projectStream.CARD_CONTRACT,
+    head: { branch: 'main', oid: HEAD, detached: false },
+    objects: bundle(),
+    branches: [{ name: 'main', oid: HEAD, objects: bundle() }],
+    checkpoint: {
+      checkpoint: projectStream.CHECKPOINT_CONTRACT,
+      baseOid: HEAD,
+      branch: 'main',
+      value: cleanValue(),
+    },
   };
 }
 
+function operation(delta) {
+  return { kind: 'code.publish', project: PROJECT, delta };
+}
+
+function official(snapshot, delta, version, machine, mutationId) {
+  return projectStream._test.fold(
+    snapshot,
+    operation(delta),
+    { version, machine, mutationId },
+  );
+}
+
 function encodedSnapshot(snapshot) {
   const bytes = Buffer.from(`${JSON.stringify(snapshot)}\n`, 'utf8');
   return {
@@ -60,23 +110,227 @@ function encodedSnapshot(snapshot) {
   };
 }
 
-test('a code project promotes as a compact snapshot, not as a text document', async () => {
-  const project = 'root:promotion';
-  const resourceId = 'shr_code_project_promotion_0001';
+test('the shared gateway/runtime fixture folds byte-for-byte to one canonical snapshot', () => {
+  const fixture = require('./fixtures/code-project-stream-v2.json');
+  const folded = fixture.mutations.reduce((snapshot, mutation) => (
+    projectStream._test.fold(
+      snapshot,
+      mutation.operation,
+      {
+        version: mutation.version,
+        machine: mutation.device_id,
+        mutationId: mutation.mutation_id,
+      },
+    )
+  ), fixture.initialSnapshot);
+  assert.deepEqual(folded, fixture.expectedSnapshot);
+});
+
+test('state-neutral events retain the independently born mutation identity', () => {
+  const first = official(
+    projectStream.emptySnapshot(PROJECT),
+    cardSet(),
+    1,
+    'machine-a',
+    'mut_real_change_0001',
+  );
+  const repeatedCard = official(
+    first,
+    cardSet(),
+    2,
+    'machine-b',
+    'mut_independent_card_0002',
+  );
+  assert.equal(repeatedCard.version, 2);
+  assert.equal(repeatedCard.card.mutationId, 'mut_independent_card_0002');
+  const repeatedCheckpoint = official(repeatedCard, {
+      kind: 'checkpoint.set',
+      checkpoint: projectStream.CHECKPOINT_CONTRACT,
+      baseOid: HEAD,
+      branch: 'main',
+      from: cleanValue(),
+      to: cleanValue(),
+    }, 3, 'machine-c', 'mut_independent_checkpoint_0003');
+  assert.equal(repeatedCheckpoint.version, 3);
+  assert.equal(
+    repeatedCheckpoint.checkpoint.mutationId,
+    'mut_independent_checkpoint_0003',
+  );
+});
+
+test('checkpoint publication is exact-from compare-and-set', () => {
+  const first = official(
+    projectStream.emptySnapshot(PROJECT),
+    cardSet(),
+    1,
+    'machine-a',
+    'mut_cas_card_0001',
+  );
+  const staleDiff = 'diff --git a/stale.js b/stale.js\n';
+  const stale = {
+    revision: require('../workspace/checkpoint').revisionOf(HEAD, '', staleDiff),
+    indexDiff: '',
+    worktreeDiff: staleDiff,
+  };
+  assert.throws(
+    () => official(first, {
+      kind: 'checkpoint.set',
+      checkpoint: projectStream.CHECKPOINT_CONTRACT,
+      baseOid: HEAD,
+      branch: 'main',
+      from: stale,
+      to: cleanValue(),
+    }, 2, 'machine-b', 'mut_stale_checkpoint_0002'),
+    (error) => error.code === 'code_project_stale_base',
+  );
+});
+
+test('all branch fields use one exact Git branch grammar', () => {
+  for (const name of ['HEAD', '@', '-bad', 'bad..ref', 'bad//ref', '.hidden/ref', 'bad.lock']) {
+    for (const mutate of [
+      (delta) => { delta.head.branch = name; },
+      (delta) => { delta.branches[0].name = name; },
+      (delta) => { delta.checkpoint.branch = name; },
+    ]) {
+      const delta = clone(cardSet());
+      mutate(delta);
+      assert.throws(
+        () => projectStream._test.normalizeDelta(delta, PROJECT),
+        /branch/,
+        name,
+      );
+    }
+  }
+});
+
+test('checkpoint sections prove their content revision', () => {
+  const inline = {
+    revision: 'f'.repeat(64),
+    sections: {
+      index: [],
+      worktree: [{ text: 'diff --git a/app.js b/app.js\n' }],
+    },
+  };
+  assert.throws(
+    () => projectStream._test.normalizeDelta({
+      kind: 'checkpoint.set',
+      checkpoint: projectStream.CHECKPOINT_CONTRACT,
+      baseOid: HEAD,
+      branch: 'main',
+      from: cleanValue(),
+      to: inline,
+    }, PROJECT),
+    /revision/,
+  );
+
+  const payload = {
+    kind: 'chunks',
+    contract: projectStream.PAYLOAD_CONTRACT,
+    resourceId: PROJECT,
+    ...chunks('c'),
+  };
+  assert.throws(
+    () => projectStream._test.normalizeDelta({
+      kind: 'checkpoint.set',
+      checkpoint: projectStream.CHECKPOINT_CONTRACT,
+      baseOid: HEAD,
+      branch: 'main',
+      from: cleanValue(),
+      to: {
+        revision: null,
+        sections: {
+          index: [],
+          worktree: [{ payload }],
+        },
+      },
+    }, PROJECT),
+    /revision/,
+  );
+});
+
+test('inline and external sections have one Merkle revision', () => {
+  const text = 'diff --git a/app.js b/app.js\n';
+  const { describeBytes, manifestChecksum } = require('../workspace/content');
+  const sectionChunks = describeBytes(Buffer.from(text, 'utf8'));
+  const revision = require('../workspace/checkpoint').revisionOfValue(HEAD, {
+    sections: {
+      index: [],
+      worktree: [{ text }],
+    },
+  });
+  const inline = {
+    revision,
+    sections: {
+      index: [],
+      worktree: [{ text }],
+    },
+  };
+  const external = {
+    revision,
+    sections: {
+      index: [],
+      worktree: [{
+        payload: {
+          kind: 'chunks',
+          contract: projectStream.PAYLOAD_CONTRACT,
+          resourceId: PROJECT,
+          checksum: manifestChecksum(sectionChunks),
+          bytes: Buffer.byteLength(text),
+          chunks: sectionChunks,
+        },
+      }],
+    },
+  };
+  for (const to of [inline, external]) {
+    assert.doesNotThrow(() => projectStream._test.normalizeDelta({
+      kind: 'checkpoint.set',
+      checkpoint: projectStream.CHECKPOINT_CONTRACT,
+      baseOid: HEAD,
+      branch: 'main',
+      from: cleanValue(),
+      to,
+    }, PROJECT));
+  }
+});
+
+test('one content-addressed chunk cannot claim two sizes', () => {
+  const delta = cardSet();
+  delta.branches[0].objects = {
+    ...delta.branches[0].objects,
+    ...chunks('a', 2),
+  };
+  assert.throws(
+    () => projectStream._test.normalizeDelta(delta, PROJECT),
+    /two sizes/,
+  );
+});
+
+test('official mutation ids use the one transport grammar', () => {
+  assert.throws(
+    () => official(
+      projectStream.emptySnapshot(PROJECT),
+      cardSet(),
+      1,
+      'machine-a',
+      'short',
+    ),
+    /mutation id/,
+  );
+});
+
+test('a code project promotes as a compact v2 snapshot', async () => {
+  const resourceId = '018f0000-0000-7000-8000-000000000001';
   const file = path.join(tempRoot, 'promotion.json');
-  projectStream.writeSnapshot(file, projectStream._test.emptySnapshot(project));
+  projectStream.writeSnapshot(file, projectStream.emptySnapshot(resourceId));
 
   const started = await call(shared.handlePromotionStart, {
     resourceId,
     path: file,
-    project,
     contract: projectStream.STREAM_CONTRACT,
   });
   assert.equal(started.status, 202);
-  assert.equal(started.payload.promotion.contract, projectStream.STREAM_CONTRACT);
-  assert.equal(started.payload.promotion.localResource, `${projectStream.LOCAL_RESOURCE_PREFIX}${resourceId}`);
-
   const promotion = promotions.getPromotion(started.payload.promotion.promotionId);
+  assert.equal(promotion.schemaVersion, 2);
   promotions.acknowledgePromotion(promotion.promotionId, {
     resourceId,
     authorityEpoch: 1,
@@ -85,96 +339,61 @@ test('a code project promotes as a compact snapshot, not as a text document', as
     snapshotChecksum: promotion.snapshotChecksum,
     snapshotKey: 'shared/code-project/promotion.bin',
   });
-  const replica = require('../state/replicas').getReplicaByResourceId(resourceId);
-  assert.equal(replica.contract, projectStream.STREAM_CONTRACT);
-  assert.equal(replica.localPath, file);
+  assert.equal(replicas.getReplicaByResourceId(resourceId).contract, projectStream.STREAM_CONTRACT);
 });
 
-test('empty attachment hydrates through N, then applies only event N+1', async () => {
-  const project = 'root:hydrate';
-  const resourceId = 'shr_code_project_attachment_0001';
-  const file = path.join(tempRoot, 'attachment.json');
-  const started = await call(shared.handleAttachmentStart, {
+test('local outbox and ack are silent until the official tail folds', async () => {
+  const resourceId = '018f0000-0000-7000-8000-000000000002';
+  const file = path.join(tempRoot, 'official-tail.json');
+  const empty = projectStream.emptySnapshot(resourceId);
+  const encoded = encodedSnapshot(empty);
+  const attachment = attachments.enqueueAttachment({
+    attachmentId: 'att_code_project_official_tail_01',
     resourceId,
-    path: file,
+    localPath: file,
     contract: projectStream.STREAM_CONTRACT,
   });
-  assert.equal(started.status, 202);
-
-  const mutationA = 'mut_code_project_snapshot_a';
-  const snapshot = {
-    schemaVersion: 1,
-    project,
-    version: 2,
-    records: [{ ...record(project, 'machine-a', mutationA, 'snapshot'), version: 2 }],
-  };
-  const encoded = encodedSnapshot(snapshot);
-  await call(shared.handleAttachmentAck, {
-    attachmentId: started.payload.attachment.attachmentId,
+  attachments.acknowledgeAttachment(attachment.attachment.attachmentId, {
     resourceId,
     authorityEpoch: 1,
-    headVersion: 2,
-    snapshotVersion: 2,
+    headVersion: 0,
+    snapshotVersion: 0,
     contract: projectStream.STREAM_CONTRACT,
-    schemaVersion: 1,
+    schemaVersion: 2,
     ...encoded,
   });
 
-  assert.equal(attachments.getAttachmentByResource(resourceId).state, 'attached');
-  assert.deepEqual(projectStream.readSnapshot(file, project), snapshot);
-
-  const mutationB = 'mut_code_project_cloud_b';
-  await call(shared.handleMutationIngest, {
-    version: 3,
-    committedAt: '2026-07-26T12:00:03.000Z',
-    envelope: {
-      resourceId,
-      authorityEpoch: 1,
-      mutationId: mutationB,
-      deviceId: 'machine-b',
-      baseVersion: 2,
-      contract: projectStream.STREAM_CONTRACT,
-      schemaVersion: 1,
-      operationKind: 'code.publish',
-      operation: {
-        kind: 'code.publish',
-        record: record(project, 'machine-b', mutationB, 'event-3'),
-      },
-    },
-  });
-  assert.deepEqual(
-    projectStream.readSnapshot(file, project).records.map((entry) => [
-      entry.machine,
-      entry.version,
-      entry.cards[0].marker,
-    ]),
-    [
-      ['machine-a', 2, 'snapshot'],
-      ['machine-b', 3, 'event-3'],
-    ],
+  const project = { resourceId, file };
+  const delta = {
+    ...cardSet(),
+    objects: { ...cardSet().objects, resourceId },
+    branches: cardSet().branches.map((branch) => ({
+      ...branch,
+      objects: { ...branch.objects, resourceId },
+    })),
+  };
+  const published = projectStream.publish(
+    project,
+    delta,
+    'mut_code_official_tail_01',
   );
+  assert.equal(projectStream.readSnapshot(file, resourceId).version, 0);
+  const claimed = mutations.claimCloudMutations().find((entry) => (
+    entry.mutation.mutationId === published.mutation.mutationId
+  ));
+  mutations.acknowledgeCloudMutation(resourceId, published.mutation.mutationId, {
+    version: 1,
+    committedAt: '2026-07-26T12:00:00.000Z',
+  });
+  assert.equal(replicas.getReplicaByResourceId(resourceId).appliedVersion, 0);
+  assert.equal(projectStream.readSnapshot(file, resourceId).version, 0);
 
-  const beforeGap = fs.readFileSync(file, 'utf8');
-  await assert.rejects(
-    call(shared.handleMutationIngest, {
-      version: 5,
-      committedAt: '2026-07-26T12:00:05.000Z',
-      envelope: {
-        resourceId,
-        authorityEpoch: 1,
-        mutationId: 'mut_code_project_gap_005',
-        deviceId: 'machine-c',
-        baseVersion: 4,
-        contract: projectStream.STREAM_CONTRACT,
-        schemaVersion: 1,
-        operationKind: 'code.publish',
-        operation: {
-          kind: 'code.publish',
-          record: record(project, 'machine-c', 'mut_code_project_gap_005', 'gap'),
-        },
-      },
-    }),
-    /expected 4, received 5/,
-  );
-  assert.equal(fs.readFileSync(file, 'utf8'), beforeGap);
+  projectStream.applyCloudMutation({
+    version: 1,
+    committedAt: '2026-07-26T12:00:00.000Z',
+    envelope: claimed.envelope,
+  });
+  assert.equal(replicas.getReplicaByResourceId(resourceId).appliedVersion, 1);
+  assert.equal(projectStream.readSnapshot(file, resourceId).version, 1);
+  assert.equal(mutations.listUnappliedOfficialMutations(resourceId).length, 0);
 });

package/runtime/scripts/amalgm-mcp/tests/fixtures/code-project-stream-v2.json

@@ -0,0 +1 @@
+{"initialSnapshot":{"schemaVersion":2,"project":"018f0000-0000-7000-8000-00000000c0de","version":0,"card":null,"checkpoint":null},"mutations":[{"resource_id":"018f0000-0000-7000-8000-00000000c0de","version":1,"authority_epoch":1,"mutation_id":"mut_fixture_card_0001","actor_user_id":"11111111-1111-4111-8111-111111111111","device_id":"machine-a","base_version":0,"contract":"code-project-stream@2","schema_version":2,"operation_kind":"code.publish","operation":{"kind":"code.publish","project":"018f0000-0000-7000-8000-00000000c0de","delta":{"kind":"card.set","card":"repo-card@3","head":{"branch":"main","oid":"1111111111111111111111111111111111111111","detached":false},"objects":{"kind":"bundle","contract":"git-bundle-chunks@2","resourceId":"018f0000-0000-7000-8000-00000000c0de","oid":"1111111111111111111111111111111111111111","ref":"refs/amalgm/exports/1111111111111111111111111111111111111111","checksum":"c73bdbb6f6997aa08dfa250e66c49dd02aaa826c293bc9221f4b80614b9640ba","bytes":1,"chunks":[{"sha256":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","bytes":1}]},"branches":[{"name":"dev","oid":"2222222222222222222222222222222222222222","objects":{"kind":"bundle","contract":"git-bundle-chunks@2","resourceId":"018f0000-0000-7000-8000-00000000c0de","oid":"2222222222222222222222222222222222222222","ref":"refs/amalgm/exports/2222222222222222222222222222222222222222","checksum":"7bee928eebf88ea25f8c85aad26c2120325d4cee5ed3fbdd2ed7e92b9df46d98","bytes":2,"chunks":[{"sha256":"bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb","bytes":2}]}},{"name":"main","oid":"1111111111111111111111111111111111111111","objects":{"kind":"bundle","contract":"git-bundle-chunks@2","resourceId":"018f0000-0000-7000-8000-00000000c0de","oid":"1111111111111111111111111111111111111111","ref":"refs/amalgm/exports/1111111111111111111111111111111111111111","checksum":"c73bdbb6f6997aa08dfa250e66c49dd02aaa826c293bc9221f4b80614b9640ba","bytes":1,"chunks":[{"sha256":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","bytes":1}]}}],"checkpoint":{"checkpoint":"repo-checkpoint@11","baseOid":"1111111111111111111111111111111111111111","branch":"main","value":{"revision":null,"indexDiff":"","worktreeDiff":""}}}},"committed_at":"2026-07-26T12:00:00.000Z"},{"resource_id":"018f0000-0000-7000-8000-00000000c0de","version":2,"authority_epoch":1,"mutation_id":"mut_fixture_checkpoint_0002","actor_user_id":"22222222-2222-4222-8222-222222222222","device_id":"machine-b","base_version":1,"contract":"code-project-stream@2","schema_version":2,"operation_kind":"code.publish","operation":{"kind":"code.publish","project":"018f0000-0000-7000-8000-00000000c0de","delta":{"kind":"checkpoint.set","checkpoint":"repo-checkpoint@11","baseOid":"1111111111111111111111111111111111111111","branch":"main","from":{"revision":null,"indexDiff":"","worktreeDiff":""},"to":{"revision":"643c62c9879267f7312002ffeb672cce37f9bd1436306430deac344dfa2944e9","indexDiff":"","worktreeDiff":"diff --git a/app.js b/app.js\n"}}},"committed_at":"2026-07-26T12:00:01.000Z"}],"expectedSnapshot":{"schemaVersion":2,"project":"018f0000-0000-7000-8000-00000000c0de","version":2,"card":{"card":"repo-card@3","head":{"branch":"main","oid":"1111111111111111111111111111111111111111","detached":false},"objects":{"kind":"bundle","contract":"git-bundle-chunks@2","resourceId":"018f0000-0000-7000-8000-00000000c0de","oid":"1111111111111111111111111111111111111111","ref":"refs/amalgm/exports/1111111111111111111111111111111111111111","checksum":"c73bdbb6f6997aa08dfa250e66c49dd02aaa826c293bc9221f4b80614b9640ba","bytes":1,"chunks":[{"sha256":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","bytes":1}]},"branches":[{"name":"dev","oid":"2222222222222222222222222222222222222222","objects":{"kind":"bundle","contract":"git-bundle-chunks@2","resourceId":"018f0000-0000-7000-8000-00000000c0de","oid":"2222222222222222222222222222222222222222","ref":"refs/amalgm/exports/2222222222222222222222222222222222222222","checksum":"7bee928eebf88ea25f8c85aad26c2120325d4cee5ed3fbdd2ed7e92b9df46d98","bytes":2,"chunks":[{"sha256":"bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb","bytes":2}]}},{"name":"main","oid":"1111111111111111111111111111111111111111","objects":{"kind":"bundle","contract":"git-bundle-chunks@2","resourceId":"018f0000-0000-7000-8000-00000000c0de","oid":"1111111111111111111111111111111111111111","ref":"refs/amalgm/exports/1111111111111111111111111111111111111111","checksum":"c73bdbb6f6997aa08dfa250e66c49dd02aaa826c293bc9221f4b80614b9640ba","bytes":1,"chunks":[{"sha256":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","bytes":1}]}}],"machine":"machine-a","mutationId":"mut_fixture_card_0001","version":1},"checkpoint":{"checkpoint":"repo-checkpoint@11","baseOid":"1111111111111111111111111111111111111111","branch":"main","value":{"revision":"643c62c9879267f7312002ffeb672cce37f9bd1436306430deac344dfa2944e9","indexDiff":"","worktreeDiff":"diff --git a/app.js b/app.js\n"},"machine":"machine-b","mutationId":"mut_fixture_checkpoint_0002","version":2}}}

package/runtime/scripts/amalgm-mcp/tests/project-context.test.js

@@ -394,27 +394,42 @@ test('workspace removal drops the project_context row', () => {
   assert.equal(store.getProjectContext(workspace.path, { reconcile: false }), null);
 });
 
-test('watcher reconciles direct disk edits', async () => {
+test('the bounded watcher schedule reconciles a dropped notification and retries the watcher', async () => {
   const { projectPath, workspace } = makeProject('watch');
-  store.ensureProjectContext(workspace);
-  const before = store.getProjectContext(projectPath, { reconcile: false }).contextRevision;
+  const originalWatch = fs.watch;
+  let watchAttempts = 0;
+  fs.watch = (...args) => {
+    watchAttempts += 1;
+    if (watchAttempts === 1) {
+      const error = new Error('simulated dropped watcher');
+      error.code = 'EMFILE';
+      throw error;
+    }
+    return originalWatch.apply(fs, args);
+  };
 
-  fs.writeFileSync(
-    path.join(projectPath, '.amalgm/context/project-state.md'),
-    '# Project State\n\nWatched edit.\n',
-  );
+  try {
+    store.ensureProjectContext(workspace);
+    const before = store.getProjectContext(projectPath, { reconcile: false }).contextRevision;
 
-  // fs.watch + 200ms debounce; poll the row instead of guessing exact timing.
-  const deadline = Date.now() + 3000;
-  let row = null;
-  while (Date.now() < deadline) {
-    row = store.getProjectContext(projectPath, { reconcile: false });
-    if (row && row.contextRevision !== before) break;
-    await new Promise((resolve) => setTimeout(resolve, 100));
+    fs.writeFileSync(
+      path.join(projectPath, '.amalgm/context/project-state.md'),
+      '# Project State\n\nWatched edit.\n',
+    );
+
+    const deadline = Date.now() + 7_000;
+    let row = store.getProjectContext(projectPath, { reconcile: false });
+    while (row?.contextRevision === before && Date.now() < deadline) {
+      await new Promise((resolve) => setTimeout(resolve, 50));
+      row = store.getProjectContext(projectPath, { reconcile: false });
+    }
+    assert.ok(row, 'row exists');
+    assert.notEqual(row.contextRevision, before, 'scheduled verification updated the row');
+    assert.ok(row.prompt.projectState.includes('Watched edit.'));
+    assert.ok(watchAttempts >= 2, 'the scheduled pass retried the failed watcher');
+  } finally {
+    fs.watch = originalWatch;
   }
-  assert.ok(row, 'row exists');
-  assert.notEqual(row.contextRevision, before, 'watcher updated the row');
-  assert.ok(row.prompt.projectState.includes('Watched edit.'));
 });
 
 // ---------------------------------------------------------------------------

package/runtime/scripts/amalgm-mcp/tests/shared-tunnel-rehydration.test.js

@@ -213,3 +213,87 @@ test('a pruned-tail join answer triggers rehydration through the local state ser
     server.close();
   }
 });
+
+test('an authorized attachment with a local materialization failure stays retryable', async () => {
+  const calls = [];
+  let attachmentClaimed = false;
+  const server = http.createServer((req, res) => {
+    let body = '';
+    req.on('data', (chunk) => { body += chunk; });
+    req.on('end', () => {
+      const parsed = body ? JSON.parse(body) : null;
+      calls.push({ path: req.url, body: parsed });
+      res.setHeader('content-type', 'application/json');
+      if (req.url === '/state/shared/replicas') {
+        res.end('{"replicas":[]}');
+        return;
+      }
+      if (req.url.startsWith('/state/stream')) {
+        res.writeHead(200, { 'content-type': 'text/event-stream' });
+        res.write('\n');
+        return;
+      }
+      if (req.url === '/state/shared/attachments/claim') {
+        const attachments = attachmentClaimed
+          ? []
+          : [{
+            attachmentId: 'att_local_materialize_retry_01',
+            resourceId: 'shr_localretrytest01',
+          }];
+        attachmentClaimed = true;
+        res.end(JSON.stringify({ attachments }));
+        return;
+      }
+      if (req.url === '/state/shared/attachments/ack') {
+        res.statusCode = 409;
+        res.end('{"error":"local disk changed during snapshot install"}');
+        return;
+      }
+      res.end('{"mutations":[],"promotions":[],"attachments":[]}');
+    });
+  });
+  await new Promise((resolve) => { server.listen(0, '127.0.0.1', resolve); });
+  const sent = [];
+  const tunnel = createSharedRealtimeTunnel({
+    send: (frame) => { sent.push(frame); return true; },
+    sendLarge: (frame) => { sent.push(frame); return true; },
+    localPort: () => server.address().port,
+    localHeaders: (headers) => ({ ...headers }),
+    warn: () => {},
+  });
+  try {
+    tunnel.enable(['shared.mutation.v1']);
+    await until(
+      () => sent.some((frame) => frame.type === 'shared.resource.attach'),
+      'the attachment request',
+    );
+    const request = sent.find((frame) => frame.type === 'shared.resource.attach');
+    tunnel.handleFrame({
+      type: 'shared.resource.attached',
+      request_id: request.request_id,
+      resource_id: request.resource_id,
+      authority_epoch: 1,
+      head_version: 0,
+      snapshot_version: 0,
+      snapshot_checksum: 'a'.repeat(64),
+      snapshot_b64: 'AA==',
+      contract: 'text-yjs@1',
+      schema_version: 1,
+    });
+    await until(
+      () => calls.some((call) => call.path === '/state/shared/attachments/fail'),
+      'the retryable local attachment failure',
+    );
+    assert.deepEqual(
+      calls.find((call) => call.path === '/state/shared/attachments/fail').body,
+      {
+        attachmentId: 'att_local_materialize_retry_01',
+        message: 'local disk changed during snapshot install',
+        retryable: true,
+      },
+    );
+  } finally {
+    tunnel.stop();
+    server.close();
+  }
+});