amalgm 0.1.238 → 0.1.240

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

@@ -233,6 +233,26 @@ function acknowledgePromotion(promotionIdInput, acknowledgement, options = {}) {
     // 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 pendingRehomes = cachedStatement(database, `
+      SELECT channel_id, mutation_id
+      FROM mutation_journal
+      WHERE local_resource = ?
+        AND shared_resource_id IS NULL
+        AND mutation_origin = 'local'
+        AND journal_id > ?
+      ORDER BY journal_id ASC
+    `).all(promotion.localResource, promotion.journalCursor);
+    const sharedChannelId = `resource:${replica.resourceId}`;
+    for (const mutation of pendingRehomes) {
+      // The permanent mutation ID joins semantic and physical durability.
+      // Rekey both halves in this transaction; otherwise restart can see the
+      // shared journal row and strand its still-local native file receipt.
+      require('./doc-disk').rehomeMutation(database, {
+        mutationId: mutation.mutation_id,
+        oldChannelId: mutation.channel_id,
+        newChannelId: sharedChannelId,
+      });
+    }
     const rehomed = cachedStatement(database, `
       UPDATE mutation_journal
       SET channel_id = ?,
@@ -246,7 +266,7 @@ function acknowledgePromotion(promotionIdInput, acknowledgement, options = {}) {
         AND mutation_origin = 'local'
         AND journal_id > ?
     `).run(
-      `resource:${replica.resourceId}`,
+      sharedChannelId,
       replica.resourceId,
       require('../workspace/identity').machineId(),
       replica.authorityEpoch,

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

@@ -35,6 +35,41 @@ function integer(value, name, minimum) {
   return number;
 }
 
+/**
+ * A snapshot is an official prefix, never an independently numbered value.
+ * Validate the complete authority envelope before any caller touches disk,
+ * memory, or SQLite so every snapshot contract shares one ordering boundary.
+ */
+function validateSnapshotEnvelope(input, expected = {}) {
+  const resourceId = requiredText(input?.resourceId, 'resourceId', 132);
+  if (!isCloudResourceId(resourceId)) {
+    throw invalid('resourceId must be a node UUID or legacy cloud id');
+  }
+  const contract = requiredText(input?.contract, 'contract', 128);
+  if (!CONTRACT.test(contract)) throw invalid('contract has an invalid format');
+  const schemaVersion = integer(input?.schemaVersion, 'schemaVersion', 1);
+  const authorityEpoch = integer(input?.authorityEpoch, 'authorityEpoch', 1);
+  const snapshotVersion = integer(input?.snapshotVersion, 'snapshotVersion', 0);
+  const headVersion = integer(input?.headVersion, 'headVersion', 0);
+  if (expected.contract && contract !== expected.contract) {
+    throw invalid(`snapshot contract must be ${expected.contract}`, 409);
+  }
+  if (expected.schemaVersion && schemaVersion !== expected.schemaVersion) {
+    throw invalid(`snapshot schemaVersion must be ${expected.schemaVersion}`, 409);
+  }
+  if (snapshotVersion > headVersion) {
+    throw invalid('snapshotVersion cannot exceed headVersion', 409);
+  }
+  return {
+    resourceId,
+    contract,
+    schemaVersion,
+    authorityEpoch,
+    snapshotVersion,
+    headVersion,
+  };
+}
+
 function normalizeReplica(row) {
   if (!row) return null;
   return {
@@ -219,11 +254,17 @@ function markReplicaRevoked(input, options = {}) {
 }
 
 /**
- * A freshly attached official snapshot subsumes every version at or before
- * it, so the replica's cursors jump forward to the snapshot — never backward:
- * a replica that already applied past the snapshot keeps its position.
+ * Decide what an already-bound replica may do with a snapshot before the
+ * caller touches its materialization.
+ *
+ * Rail version and authority epoch are independent coordinates. Most
+ * contracts have one canonical value at a rail version, while an
+ * authority-projected contract (the workspace tree) may legitimately have
+ * different visible bytes at the same rail version after an access change.
+ * Older authority is never allowed to install, even when it carries a larger
+ * rail number.
  */
-function advanceReplicaSnapshot(input, options = {}) {
+function inspectReplicaSnapshot(input, options = {}) {
   const resourceId = requiredText(input?.resourceId, 'resourceId', 132);
   const snapshotVersion = integer(input?.snapshotVersion, 'snapshotVersion', 0);
   const snapshotChecksum = requiredText(input?.snapshotChecksum, 'snapshotChecksum', 64);
@@ -232,23 +273,101 @@ function advanceReplicaSnapshot(input, options = {}) {
   }
   const authorityEpoch = integer(input?.authorityEpoch, 'authorityEpoch', 1);
   const database = options.database || openLocalDb();
-  const row = cachedStatement(
-    database,
-    'SELECT * FROM shared_resource_replicas WHERE resource_id = ?',
-  ).get(resourceId);
-  if (!row) throw invalid(`unknown shared replica ${resourceId}`, 404);
+  const current = getReplicaByResourceId(resourceId, { database });
+  if (!current) throw invalid(`unknown shared replica ${resourceId}`, 404);
+  const projectedAuthorityEpoch = options.projectedAuthorityEpoch == null
+    ? current.authorityEpoch
+    : integer(options.projectedAuthorityEpoch, 'projectedAuthorityEpoch', 1);
+  if (
+    authorityEpoch < current.authorityEpoch
+    || authorityEpoch < projectedAuthorityEpoch
+  ) {
+    throw invalid(
+      `shared resource ${resourceId} snapshot has stale authority epoch ${authorityEpoch}`,
+      409,
+    );
+  }
+  // `authorityEpoch` on the replica is the newest authority advertised by
+  // the tunnel. `projectedAuthorityEpoch` is the authority whose bytes and
+  // permissions are physically installed. A reconnect may advance the first
+  // coordinate before the same-version projection arrives, so projection
+  // eligibility must compare with the second.
+  const authorityChanged = authorityEpoch > projectedAuthorityEpoch;
+  const authorityProjection = options.allowAuthorityProjection === true && authorityChanged;
+  if (
+    current.snapshotVersion === snapshotVersion
+    && current.snapshotChecksum !== null
+    && current.snapshotChecksum !== snapshotChecksum
+    && !authorityProjection
+  ) {
+    throw invalid(
+      `shared resource ${resourceId} has unequal state at version ${snapshotVersion}`,
+      409,
+    );
+  }
+  if (snapshotVersion < current.appliedVersion) {
+    return { action: 'stale', authorityChanged, replica: current };
+  }
+  if (authorityProjection) {
+    return { action: 'install', authorityChanged, replica: current };
+  }
+  if (snapshotVersion === current.appliedVersion) {
+    if (
+      current.snapshotVersion === snapshotVersion
+      && current.snapshotChecksum === null
+    ) {
+      return { action: 'metadata', authorityChanged, replica: current };
+    }
+    if (
+      current.snapshotVersion === snapshotVersion
+      && current.snapshotChecksum === snapshotChecksum
+    ) {
+      return { action: authorityChanged ? 'metadata' : 'duplicate', authorityChanged, replica: current };
+    }
+    if (current.snapshotVersion < snapshotVersion) {
+      return { action: 'metadata', authorityChanged, replica: current };
+    }
+    throw invalid(
+      `shared resource ${resourceId} has unequal state at version ${snapshotVersion}`,
+      409,
+    );
+  }
+  return { action: 'install', authorityChanged, replica: current };
+}
+
+/**
+ * A freshly attached official snapshot subsumes every version at or before
+ * it, so the replica's cursors jump forward to the snapshot — never backward:
+ * a replica that already applied past the snapshot keeps its position.
+ */
+function advanceReplicaSnapshot(input, options = {}) {
+  const database = options.database || openLocalDb();
+  const disposition = inspectReplicaSnapshot(input, options);
+  const {
+    resourceId,
+    snapshotVersion,
+    snapshotChecksum,
+    authorityEpoch,
+  } = {
+    resourceId: disposition.replica.resourceId,
+    snapshotVersion: integer(input?.snapshotVersion, 'snapshotVersion', 0),
+    snapshotChecksum: requiredText(input?.snapshotChecksum, 'snapshotChecksum', 64),
+    authorityEpoch: integer(input?.authorityEpoch, 'authorityEpoch', 1),
+  };
+  if (disposition.action === 'stale' || disposition.action === 'duplicate') {
+    return disposition.replica;
+  }
   cachedStatement(database, `
     UPDATE shared_resource_replicas
-    SET applied_version = MAX(applied_version, ?),
-        snapshot_version = MAX(snapshot_version, ?),
-        snapshot_checksum = CASE WHEN snapshot_version <= ? THEN ? ELSE snapshot_checksum END,
+    SET applied_version = ?,
+        snapshot_version = ?,
+        snapshot_checksum = ?,
         authority_epoch = MAX(authority_epoch, ?),
         sync_status = 'synced',
         last_error = NULL,
         updated_at = ?
     WHERE resource_id = ?
   `).run(
-    snapshotVersion,
     snapshotVersion,
     snapshotVersion,
     snapshotChecksum,
@@ -268,4 +387,6 @@ module.exports = {
   markReplicaRevoked,
   refreshReplicaAuthority,
   registerReplica,
+  inspectReplicaSnapshot,
+  validateSnapshotEnvelope,
 };

package/runtime/scripts/amalgm-mcp/state/shared-rest.js

@@ -118,7 +118,7 @@ async function handleWorkspaceContentDiscover(body, sendJson) {
 
 async function handlePromotionStart(body, sendJson) {
   try {
-    const codeProject = body?.contract === 'code-project-stream@1';
+    const codeProject = body?.contract === 'code-project-stream@2';
     const requestedResourceId = typeof body?.resourceId === 'string' && body.resourceId.trim()
       ? body.resourceId.trim()
       : null;
@@ -130,7 +130,7 @@ async function handlePromotionStart(body, sendJson) {
       }
       const projectStream = require('../workspace/project-stream');
       const localPath = require('path').resolve(body?.path || '');
-      const snapshot = projectStream.readSnapshot(localPath, body?.project);
+      const snapshot = projectStream.readSnapshot(localPath, requestedResourceId);
       const bytes = Buffer.from(`${JSON.stringify(snapshot)}\n`, 'utf8');
       const result = require('./promotions').enqueuePromotion({
         promotionId: body?.promotionId || `prm_${crypto.randomBytes(16).toString('base64url')}`,
@@ -138,7 +138,7 @@ async function handlePromotionStart(body, sendJson) {
         localResource: `${projectStream.LOCAL_RESOURCE_PREFIX}${requestedResourceId}`,
         localPath,
         contract: projectStream.STREAM_CONTRACT,
-        schemaVersion: 1,
+        schemaVersion: 2,
         snapshotBase64: bytes.toString('base64'),
         contentBytes: bytes.length,
         name: body?.name,
@@ -240,7 +240,7 @@ async function handlePromotionFail(body, sendJson) {
 async function handleAttachmentStart(body, sendJson) {
   try {
     const tree = body?.contract === 'workspace-tree@1';
-    const codeProject = body?.contract === 'code-project-stream@1';
+    const codeProject = body?.contract === 'code-project-stream@2';
     const localPath = tree || codeProject
       ? require('path').resolve(body?.path || '')
       : require('./docs').openDoc(body?.path).path;
@@ -251,8 +251,9 @@ async function handleAttachmentStart(body, sendJson) {
         return;
       }
     } else if (codeProject) {
-      const contents = fs.existsSync(localPath) ? fs.readFileSync(localPath, 'utf8').trim() : '';
-      if (contents) {
+      const stream = require('../workspace/project-stream');
+      const snapshot = stream.readSnapshot(localPath, body?.resourceId);
+      if (snapshot.version !== 0 || snapshot.card !== null || snapshot.checkpoint !== null) {
         sendJson(409, { error: 'code project attachment requires an empty local projection' });
         return;
       }
@@ -352,7 +353,12 @@ async function handleMutationFail(body, sendJson) {
     sendJson(200, require('./mutations').failCloudMutation(
       body?.resourceId,
       body?.mutationId,
-      { message: body?.message, retryable: body?.retryable, retryAt: body?.retryAt },
+      {
+        code: body?.code,
+        message: body?.message,
+        retryable: body?.retryable,
+        retryAt: body?.retryAt,
+      },
     ));
   } catch (error) {
     sendHandlerError(error, sendJson);
@@ -366,7 +372,7 @@ async function handleMutationIngest(body, sendJson) {
       ? require('../browser/cookie-jar').applyCloudCookieMutation(body)
       : contract === 'workspace-tree@1'
         ? require('../workspace/tree-store').applyCloudTreeMutation(body)
-        : contract === 'code-project-stream@1'
+        : contract === 'code-project-stream@2'
           ? require('../workspace/project-stream').applyCloudMutation(body)
           : require('./docs').applyCloudDocMutation(body);
     sendJson(200, result);

package/runtime/scripts/amalgm-mcp/tests/browser-cookie-cloud.test.js

@@ -23,6 +23,7 @@ const {
   claimCloudMutations,
   getMutation,
 } = require('../state/mutations');
+const { getReplicaByResourceId } = require('../state/replicas');
 const {
   COOKIE_CLOUD_CONTRACT,
   applyCloudCookieMutation,
@@ -89,6 +90,21 @@ test('official cookie mutations materialize in order and deletions stay tombston
     version: 1,
     committedAt: '2026-07-20T20:00:00.000Z',
   }, { database: db });
+  assert.equal(
+    getReplicaByResourceId(localClaim.envelope.resourceId, { database: db }).appliedVersion,
+    0,
+    'the acknowledgement records the number but does not apply it',
+  );
+  applyCloudCookieMutation({
+    version: 1,
+    committedAt: '2026-07-20T20:00:00.000Z',
+    envelope: localClaim.envelope,
+  }, { database: db });
+  assert.equal(
+    getReplicaByResourceId(localClaim.envelope.resourceId, { database: db }).appliedVersion,
+    1,
+    'the writer advances only when its committed event passes through the ordered inbox',
+  );
 
   const remoteCookie = cookie('remote', 'remote-secret');
   const key = require('../browser/cookie-jar').cookieKey(remoteCookie);
@@ -178,4 +194,181 @@ test('a stale cloud base never re-emits local cookies as bootstrap mutations', (
   assert.equal(result.bootstrapDeferred, true);
   assert.equal(result.bootstrappedMutations, 0);
   assert.equal(db.prepare('SELECT COUNT(*) AS count FROM mutation_journal').get().count, 0);
+  assert.equal(
+    readCookieJar().cookies.some((item) => item.name === 'already-synced'),
+    true,
+    'a stale prefix cannot roll the physical jar backward',
+  );
+});
+
+test('a private snapshot ahead of cloud head is rejected before changing the jar', () => {
+  const before = JSON.stringify(readCookieJar());
+  const resourceId = privateCookieResourceId(userId);
+  const bytes = Buffer.from(JSON.stringify({
+    schemaVersion: 1,
+    version: 8,
+    updatedAt: '2026-07-20T19:00:00.000Z',
+    records: [],
+    tombstones: [],
+  }), 'utf8');
+  assert.throws(() => installCookieCloudBootstrap({
+    resourceId,
+    authorityEpoch: 1,
+    headVersion: 7,
+    snapshotVersion: 8,
+    snapshotChecksum: require('crypto').createHash('sha256').update(bytes).digest('hex'),
+    snapshotBase64: bytes.toString('base64'),
+    contract: COOKIE_CLOUD_CONTRACT,
+    schemaVersion: 1,
+  }), /cannot exceed headVersion/);
+  assert.equal(JSON.stringify(readCookieJar()), before);
+});
+
+test('a stale cookie prefix ahead of the local cursor cannot claim application', () => {
+  mergeCookieJar({ sourceId: 'machine-a', upserts: [cookie('local-only', 'keep-me')] });
+  const db = openLocalDb();
+  db.prepare('DELETE FROM mutation_journal').run();
+  const resourceId = privateCookieResourceId(userId);
+  const before = JSON.stringify(readCookieJar());
+  const bytes = Buffer.from(JSON.stringify({
+    schemaVersion: 1,
+    version: 3,
+    updatedAt: '2026-07-20T19:00:00.000Z',
+    records: [],
+    tombstones: [],
+  }), 'utf8');
+
+  const result = installCookieCloudBootstrap({
+    resourceId,
+    authorityEpoch: 1,
+    headVersion: 7,
+    snapshotVersion: 3,
+    snapshotChecksum: require('crypto').createHash('sha256').update(bytes).digest('hex'),
+    snapshotBase64: bytes.toString('base64'),
+    contract: COOKIE_CLOUD_CONTRACT,
+    schemaVersion: 1,
+  }, { database: db });
+
+  assert.equal(result.bootstrapDeferred, true);
+  assert.equal(result.replica.appliedVersion, 0);
+  assert.equal(JSON.stringify(readCookieJar()), before);
+});
+
+test('cookie bootstrap journals legacy local state before replacing the physical jar', () => {
+  mergeCookieJar({
+    sourceId: 'legacy-browser',
+    upserts: [cookie('legacy-session', 'must-survive')],
+  });
+  const db = openLocalDb();
+  db.prepare('DELETE FROM mutation_journal').run();
+  const resourceId = privateCookieResourceId(userId);
+  const bytes = Buffer.from(JSON.stringify({
+    schemaVersion: 1,
+    version: 0,
+    updatedAt: '2026-07-20T19:00:00.000Z',
+    records: [],
+    tombstones: [],
+  }), 'utf8');
+  const input = {
+    resourceId,
+    authorityEpoch: 1,
+    headVersion: 0,
+    snapshotVersion: 0,
+    snapshotChecksum: require('crypto').createHash('sha256').update(bytes).digest('hex'),
+    snapshotBase64: bytes.toString('base64'),
+    contract: COOKIE_CLOUD_CONTRACT,
+    schemaVersion: 1,
+  };
+
+  assert.throws(
+    () => installCookieCloudBootstrap(input, {
+      database: db,
+      testHooks: { crashAfterSnapshotPersist: true },
+    }),
+    /simulated cookie bootstrap crash/,
+  );
+  assert.equal(
+    db.prepare(`
+      SELECT COUNT(*) AS count FROM mutation_journal
+      WHERE shared_resource_id = ? AND mutation_origin = 'local'
+    `).get(resourceId).count,
+    1,
+    'the local cookie is durable before the jar is replaced',
+  );
+
+  installCookieCloudBootstrap(input, { database: db });
+  assert.equal(
+    readCookieJar().cookies.some((item) => (
+      item.name === 'legacy-session' && item.value === 'must-survive'
+    )),
+    true,
+  );
+  assert.equal(
+    db.prepare(`
+      SELECT COUNT(*) AS count FROM mutation_journal
+      WHERE shared_resource_id = ? AND mutation_origin = 'local'
+    `).get(resourceId).count,
+    1,
+    'restart does not mint a second birth certificate',
+  );
+});
+
+test('cookie bootstrap completes a crash-left saving-local birth instead of replaying forever', () => {
+  mergeCookieJar({
+    sourceId: 'crashing-browser',
+    upserts: [cookie('crash-left', 'must-recover')],
+  });
+  const db = openLocalDb();
+  const row = db.prepare(`
+    SELECT * FROM mutation_journal
+    WHERE operation_kind = 'cookie.upsert'
+    ORDER BY journal_id DESC
+    LIMIT 1
+  `).get();
+  db.prepare(`
+    UPDATE mutation_journal
+    SET mutation_state = 'saving-local',
+        materialized_at = NULL,
+        event_seq = NULL
+    WHERE journal_id = ?
+  `).run(row.journal_id);
+  db.prepare('DELETE FROM event_log').run();
+
+  const bytes = Buffer.from(JSON.stringify({
+    schemaVersion: 1,
+    version: 0,
+    updatedAt: '2026-07-20T19:00:00.000Z',
+    records: [],
+    tombstones: [],
+  }), 'utf8');
+  installCookieCloudBootstrap({
+    resourceId: row.shared_resource_id,
+    authorityEpoch: 1,
+    headVersion: 0,
+    snapshotVersion: 0,
+    snapshotChecksum: require('crypto').createHash('sha256').update(bytes).digest('hex'),
+    snapshotBase64: bytes.toString('base64'),
+    contract: COOKIE_CLOUD_CONTRACT,
+    schemaVersion: 1,
+  }, { database: db });
+
+  const repaired = db.prepare(`
+    SELECT mutation_state, materialized_at, event_seq
+    FROM mutation_journal
+    WHERE journal_id = ?
+  `).get(row.journal_id);
+  assert.equal(repaired.mutation_state, 'saved-local');
+  assert.ok(repaired.materialized_at);
+  assert.ok(repaired.event_seq);
+  assert.equal(
+    readCookieJar().cookies.some((item) => (
+      item.name === 'crash-left' && item.value === 'must-recover'
+    )),
+    true,
+  );
+  assert.equal(
+    db.prepare('SELECT COUNT(*) AS count FROM mutation_journal').get().count,
+    1,
+    'recovery completes the original birth instead of minting another',
+  );
 });