amalgm 0.1.155 → 0.1.156

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

@@ -0,0 +1,267 @@
+'use strict';
+
+/**
+ * Runtime-internal HTTP boundary for cloud-shared resources.
+ *
+ * Domain rules stay in mutations/replicas/promotions/attachments/docs. This
+ * file only translates the authenticated local state routes into those APIs.
+ */
+
+const crypto = require('crypto');
+const fs = require('fs');
+
+function sendHandlerError(error, sendJson) {
+  const statusCode = Number(error?.statusCode) || 500;
+  sendJson(statusCode, { error: error?.message || 'internal error' });
+}
+
+function parsePositiveInt(value, fallback) {
+  const parsed = Number(value);
+  return Number.isInteger(parsed) && parsed >= 0 ? parsed : fallback;
+}
+
+async function handleReplicaRegister(body, sendJson) {
+  try {
+    const opened = require('./docs').openDoc(body?.path);
+    sendJson(200, require('./replicas').registerReplica({
+      resourceId: body?.resourceId,
+      localResource: opened.resource,
+      localPath: opened.path,
+      contract: body?.contract,
+      schemaVersion: body?.schemaVersion,
+      authorityEpoch: body?.authorityEpoch,
+      appliedVersion: body?.appliedVersion,
+      snapshotVersion: body?.snapshotVersion,
+      snapshotChecksum: body?.snapshotChecksum,
+    }));
+  } catch (error) {
+    sendHandlerError(error, sendJson);
+  }
+}
+
+async function handleReplicaList(sendJson) {
+  try {
+    sendJson(200, { replicas: require('./replicas').listReplicas() });
+  } catch (error) {
+    sendHandlerError(error, sendJson);
+  }
+}
+
+async function handleReplicaAuthority(body, sendJson) {
+  try {
+    sendJson(200, require('./replicas').refreshReplicaAuthority({
+      resourceId: body?.resourceId,
+      authorityEpoch: body?.authorityEpoch,
+      headVersion: body?.headVersion,
+      contract: body?.contract,
+      schemaVersion: body?.schemaVersion,
+    }));
+  } catch (error) {
+    sendHandlerError(error, sendJson);
+  }
+}
+
+async function handlePromotionStart(body, sendJson) {
+  try {
+    const opened = require('./docs').openDoc(body?.path);
+    const result = require('./promotions').enqueuePromotion({
+      promotionId: body?.promotionId || `prm_${crypto.randomBytes(16).toString('base64url')}`,
+      resourceId: body?.resourceId || `shr_${crypto.randomBytes(18).toString('base64url')}`,
+      localResource: opened.resource,
+      localPath: opened.path,
+      contract: body?.contract || 'text-yjs@1',
+      schemaVersion: body?.schemaVersion || 1,
+      snapshotBase64: opened.state,
+      contentBytes: fs.statSync(opened.path).size,
+      name: body?.name,
+      mediaType: body?.mediaType || 'application/vnd.amalgm.text-yjs-snapshot',
+    });
+    sendJson(result.duplicate ? 200 : 202, result);
+  } catch (error) {
+    sendHandlerError(error, sendJson);
+  }
+}
+
+async function handlePromotionGet(promotionId, sendJson) {
+  try {
+    const promotion = require('./promotions').getPromotion(promotionId);
+    if (!promotion) {
+      sendJson(404, { error: `unknown promotion ${promotionId}` });
+      return;
+    }
+    sendJson(200, { promotion });
+  } catch (error) {
+    sendHandlerError(error, sendJson);
+  }
+}
+
+async function handlePromotionClaim(body, sendJson) {
+  try {
+    sendJson(200, { promotions: require('./promotions').claimPromotions({
+      limit: parsePositiveInt(body?.limit, 4),
+      leaseMs: parsePositiveInt(body?.leaseMs, 30_000),
+    }) });
+  } catch (error) {
+    sendHandlerError(error, sendJson);
+  }
+}
+
+async function handlePromotionAck(body, sendJson) {
+  try {
+    sendJson(200, require('./promotions').acknowledgePromotion(body?.promotionId, {
+      resourceId: body?.resourceId,
+      authorityEpoch: body?.authorityEpoch,
+      headVersion: body?.headVersion,
+      snapshotVersion: body?.snapshotVersion,
+      snapshotKey: body?.snapshotKey,
+      snapshotChecksum: body?.snapshotChecksum,
+    }));
+  } catch (error) {
+    sendHandlerError(error, sendJson);
+  }
+}
+
+async function handlePromotionFail(body, sendJson) {
+  try {
+    sendJson(200, require('./promotions').failPromotion(body?.promotionId, {
+      message: body?.message,
+      retryable: body?.retryable,
+    }));
+  } catch (error) {
+    sendHandlerError(error, sendJson);
+  }
+}
+
+async function handleAttachmentStart(body, sendJson) {
+  try {
+    const opened = require('./docs').openDoc(body?.path);
+    if (require('./docs').getDocText(opened.path).length > 0) {
+      sendJson(409, { error: 'cloud attachment requires an empty local text file' });
+      return;
+    }
+    const result = require('./attachments').enqueueAttachment({
+      attachmentId: body?.attachmentId || `att_${crypto.randomBytes(16).toString('base64url')}`,
+      resourceId: body?.resourceId,
+      localPath: opened.path,
+    });
+    sendJson(result.duplicate ? 200 : 202, result);
+  } catch (error) {
+    sendHandlerError(error, sendJson);
+  }
+}
+
+async function handleAttachmentGet(attachmentId, sendJson) {
+  try {
+    const attachment = require('./attachments').getAttachment(attachmentId);
+    if (!attachment) {
+      sendJson(404, { error: `unknown attachment ${attachmentId}` });
+      return;
+    }
+    sendJson(200, { attachment });
+  } catch (error) {
+    sendHandlerError(error, sendJson);
+  }
+}
+
+async function handleAttachmentClaim(body, sendJson) {
+  try {
+    sendJson(200, { attachments: require('./attachments').claimAttachments({
+      limit: parsePositiveInt(body?.limit, 4),
+      leaseMs: parsePositiveInt(body?.leaseMs, 30_000),
+    }) });
+  } catch (error) {
+    sendHandlerError(error, sendJson);
+  }
+}
+
+async function handleAttachmentAck(body, sendJson) {
+  try {
+    sendJson(200, require('./attachments').acknowledgeAttachment(body?.attachmentId, {
+      resourceId: body?.resourceId,
+      authorityEpoch: body?.authorityEpoch,
+      headVersion: body?.headVersion,
+      snapshotVersion: body?.snapshotVersion,
+      snapshotChecksum: body?.snapshotChecksum,
+      snapshotBase64: body?.snapshotBase64,
+      contract: body?.contract,
+      schemaVersion: body?.schemaVersion,
+    }));
+  } catch (error) {
+    sendHandlerError(error, sendJson);
+  }
+}
+
+async function handleAttachmentFail(body, sendJson) {
+  try {
+    sendJson(200, require('./attachments').failAttachment(body?.attachmentId, {
+      message: body?.message,
+      retryable: body?.retryable,
+    }));
+  } catch (error) {
+    sendHandlerError(error, sendJson);
+  }
+}
+
+async function handleMutationClaim(body, sendJson) {
+  try {
+    const mutations = require('./mutations').claimCloudMutations({
+      limit: parsePositiveInt(body?.limit, 100),
+      leaseMs: parsePositiveInt(body?.leaseMs, 30_000),
+    });
+    sendJson(200, { mutations });
+  } catch (error) {
+    sendHandlerError(error, sendJson);
+  }
+}
+
+async function handleMutationAck(body, sendJson) {
+  try {
+    sendJson(200, require('./mutations').acknowledgeCloudMutation(
+      body?.resourceId,
+      body?.mutationId,
+      { version: body?.version, committedAt: body?.committedAt },
+    ));
+  } catch (error) {
+    sendHandlerError(error, sendJson);
+  }
+}
+
+async function handleMutationFail(body, sendJson) {
+  try {
+    sendJson(200, require('./mutations').failCloudMutation(
+      body?.resourceId,
+      body?.mutationId,
+      { message: body?.message, retryable: body?.retryable, retryAt: body?.retryAt },
+    ));
+  } catch (error) {
+    sendHandlerError(error, sendJson);
+  }
+}
+
+async function handleMutationIngest(body, sendJson) {
+  try {
+    sendJson(200, require('./docs').applyCloudDocMutation(body));
+  } catch (error) {
+    sendHandlerError(error, sendJson);
+  }
+}
+
+module.exports = {
+  handleAttachmentAck,
+  handleAttachmentClaim,
+  handleAttachmentFail,
+  handleAttachmentGet,
+  handleAttachmentStart,
+  handleMutationAck,
+  handleMutationClaim,
+  handleMutationFail,
+  handleMutationIngest,
+  handlePromotionAck,
+  handlePromotionClaim,
+  handlePromotionFail,
+  handlePromotionGet,
+  handlePromotionStart,
+  handleReplicaAuthority,
+  handleReplicaList,
+  handleReplicaRegister,
+};

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

@@ -0,0 +1,337 @@
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'amalgm-state-mutations-test-'));
+process.env.AMALGM_DIR = path.join(tempRoot, '.amalgm');
+process.env.AMALGM_EVENT_LOG_PRUNE_INTERVAL_MS = '0';
+
+const { closeLocalDb, openLocalDb } = require('../state/db');
+const {
+  appendStateEvent,
+  listEventsAfter,
+  subscribeStateEvents,
+} = require('../state/events');
+const {
+  acknowledgeCloudMutation,
+  claimCloudMutations,
+  commitLocalMutation,
+  completeMaterializedMutation,
+  failCloudMutation,
+  getMutation,
+  journalCloudMutation,
+  listMutations,
+  pruneMutationJournal,
+} = require('../state/mutations');
+const { getReplicaByResourceId, registerReplica } = require('../state/replicas');
+
+const localInput = {
+  channelId: 'doc:local-journal-test',
+  localResource: 'doc:local-journal-test',
+  mutationId: 'mut_local_00000001',
+  contract: 'text-yjs@1',
+  schemaVersion: 1,
+  operationKind: 'delta',
+  operation: { kind: 'delta', yjs: 'AQID' },
+  localRevision: 1,
+};
+
+const sharedResourceId = 'shr_abcdefghijklmnop';
+const sharedInput = {
+  channelId: `resource:${sharedResourceId}`,
+  localResource: 'doc:shared-journal-test',
+  sharedResourceId,
+  mutationId: 'mut_shared_0000001',
+  deviceId: 'device-test-1',
+  authorityEpoch: 1,
+  baseCloudVersion: 0,
+  contract: 'text-yjs@1',
+  schemaVersion: 1,
+  operationKind: 'delta',
+  operation: { kind: 'delta', yjs: 'BAUG' },
+  localRevision: 1,
+};
+
+function eventFor(input) {
+  return {
+    resource: input.localResource,
+    op: 'update',
+    id: `/tmp/${input.mutationId}.md`,
+    patch: { yjs: input.operation.yjs },
+    source: 'test:mutation',
+  };
+}
+
+test.after(() => {
+  closeLocalDb();
+  fs.rmSync(tempRoot, { recursive: true, force: true });
+});
+
+test('legacy Local Live events keep their exact optional-field shape', () => {
+  const event = appendStateEvent({
+    resource: 'apps',
+    op: 'replace',
+    value: [{ id: 'legacy' }],
+    source: 'test',
+  });
+  assert.deepEqual(Object.keys(event), ['seq', 'ts', 'resource', 'op', 'source', 'value']);
+  assert.equal(event.mutationId, undefined);
+  assert.equal(event.sharedResourceId, undefined);
+});
+
+test('one local mutation is persisted, materialized, then projected once', () => {
+  const db = openLocalDb();
+  const target = path.join(tempRoot, 'local.md');
+  const observed = [];
+  const unsubscribe = subscribeStateEvents((event) => {
+    if (event.mutationId === localInput.mutationId) {
+      assert.equal(fs.readFileSync(target, 'utf8'), 'local bytes\n');
+      observed.push(event);
+    }
+  });
+
+  const result = commitLocalMutation(localInput, {
+    database: db,
+    persist(database) {
+      database.exec('CREATE TABLE IF NOT EXISTS mutation_test_state (id TEXT PRIMARY KEY, value TEXT NOT NULL)');
+      database.prepare('INSERT INTO mutation_test_state (id, value) VALUES (?, ?)').run('local', 'persisted');
+    },
+    materialize() {
+      fs.writeFileSync(target, 'local bytes\n', 'utf8');
+    },
+    event: eventFor(localInput),
+  });
+  unsubscribe();
+
+  assert.equal(result.duplicate, false);
+  assert.equal(result.mutation.state, 'saved-local');
+  assert.ok(result.mutation.materializedAt);
+  assert.equal(result.mutation.eventSeq, result.event.seq);
+  assert.equal(observed.length, 1);
+  assert.equal(db.prepare('SELECT value FROM mutation_test_state WHERE id = ?').get('local').value, 'persisted');
+
+  const replayed = listEventsAfter(result.event.seq - 1).filter(
+    (event) => event.mutationId === localInput.mutationId,
+  );
+  assert.equal(replayed.length, 1);
+  assert.equal(replayed[0].sharedResourceId, undefined);
+  assert.equal(claimCloudMutations({ database: db }).length, 0, 'local-only rows never enter cloud delivery');
+});
+
+test('a lost local acknowledgement reuses the journal row and event', () => {
+  const db = openLocalDb();
+  let materializeCalls = 0;
+  const result = commitLocalMutation(localInput, {
+    database: db,
+    materialize() {
+      materializeCalls += 1;
+    },
+    event: eventFor(localInput),
+  });
+
+  assert.equal(result.duplicate, true);
+  assert.equal(materializeCalls, 0);
+  assert.equal(
+    listMutations({ database: db }).filter((mutation) => mutation.mutationId === localInput.mutationId).length,
+    1,
+  );
+  assert.equal(
+    listEventsAfter(0).filter((event) => event.mutationId === localInput.mutationId).length,
+    1,
+  );
+});
+
+test('materialization failure stays durable but invisible until recovery completes', () => {
+  const db = openLocalDb();
+  const input = {
+    ...localInput,
+    channelId: 'doc:materialization-failure',
+    localResource: 'doc:materialization-failure',
+    mutationId: 'mut_local_00000002',
+  };
+  const before = listEventsAfter(0).length;
+
+  assert.throws(() => commitLocalMutation(input, {
+    database: db,
+    materialize() {
+      throw new Error('disk unavailable');
+    },
+    event: eventFor(input),
+  }), /disk unavailable/);
+
+  const pending = getMutation(input.channelId, input.mutationId, { database: db });
+  assert.equal(pending.state, 'saving-local');
+  assert.equal(pending.eventSeq, null);
+  assert.equal(pending.lastError, 'disk unavailable');
+  assert.equal(listEventsAfter(0).length, before, 'unsaved mutation never enters the delivery cursor');
+
+  const target = path.join(tempRoot, 'recovered.md');
+  fs.writeFileSync(target, 'recovered bytes\n', 'utf8');
+  const recovered = completeMaterializedMutation(
+    input.channelId,
+    input.mutationId,
+    eventFor(input),
+    { database: db },
+  );
+  assert.equal(recovered.mutation.state, 'saved-local');
+  assert.equal(recovered.mutation.lastError, null);
+  assert.equal(
+    listEventsAfter(0).filter((event) => event.mutationId === input.mutationId).length,
+    1,
+  );
+});
+
+test('shared rows alone form the leased cloud outbox and acknowledgements deduplicate', () => {
+  const db = openLocalDb();
+  const result = commitLocalMutation(sharedInput, {
+    database: db,
+    materialize() {},
+    event: eventFor(sharedInput),
+  });
+  assert.equal(result.mutation.state, 'saved-local');
+  assert.equal(result.event.sharedResourceId, sharedResourceId);
+
+  const claimed = claimCloudMutations({
+    database: db,
+    now: '2026-07-14T18:00:00.000Z',
+    leaseUntil: '2026-07-14T18:00:30.000Z',
+  });
+  assert.equal(claimed.length, 1);
+  assert.deepEqual(claimed[0].envelope, {
+    resourceId: sharedResourceId,
+    authorityEpoch: 1,
+    mutationId: sharedInput.mutationId,
+    deviceId: 'device-test-1',
+    baseVersion: 0,
+    contract: 'text-yjs@1',
+    schemaVersion: 1,
+    operationKind: 'delta',
+    operation: sharedInput.operation,
+  });
+  assert.equal(claimed[0].mutation.state, 'syncing');
+  assert.equal(claimed[0].mutation.attemptCount, 1);
+
+  assert.equal(claimCloudMutations({
+    database: db,
+    now: '2026-07-14T18:00:15.000Z',
+  }).length, 0, 'an active lease prevents a duplicate concurrent delivery');
+
+  const retrying = failCloudMutation(
+    sharedResourceId,
+    sharedInput.mutationId,
+    { message: 'temporary network error', retryable: true, retryAt: '2026-07-14T18:00:16.000Z' },
+    { database: db },
+  );
+  assert.equal(retrying.state, 'syncing');
+  assert.equal(claimCloudMutations({
+    database: db,
+    now: '2026-07-14T18:00:17.000Z',
+  }).length, 1);
+
+  const acknowledged = acknowledgeCloudMutation(
+    sharedResourceId,
+    sharedInput.mutationId,
+    { version: 1, committedAt: '2026-07-14T18:00:18.000Z' },
+    { database: db },
+  );
+  assert.equal(acknowledged.mutation.state, 'synced');
+  assert.equal(acknowledged.mutation.officialCloudVersion, 1);
+
+  const duplicate = acknowledgeCloudMutation(
+    sharedResourceId,
+    sharedInput.mutationId,
+    { version: 1, committedAt: '2026-07-14T18:00:18.000Z' },
+    { database: db },
+  );
+  assert.equal(duplicate.duplicate, true);
+  assert.equal(claimCloudMutations({ database: db }).length, 0);
+});
+
+test('the official tail reconciles a locally materialized mutation after its ack was lost', () => {
+  const db = openLocalDb();
+  const resourceId = 'shr_tailackabcdefghijkl';
+  const input = {
+    ...sharedInput,
+    channelId: `resource:${resourceId}`,
+    sharedResourceId: resourceId,
+    localResource: 'doc:shared-tail-ack-test',
+    mutationId: 'mut_shared_tailack_01',
+    operation: { kind: 'delta', yjs: 'DQ4P' },
+  };
+  registerReplica({
+    resourceId,
+    localResource: input.localResource,
+    localPath: path.join(tempRoot, 'tail-ack.md'),
+    contract: input.contract,
+    schemaVersion: input.schemaVersion,
+    authorityEpoch: input.authorityEpoch,
+    appliedVersion: 0,
+    snapshotVersion: 0,
+  }, { database: db });
+  commitLocalMutation(input, { database: db, materialize() {}, event: eventFor(input) });
+
+  const recovered = journalCloudMutation({
+    localResource: input.localResource,
+    version: 1,
+    committedAt: '2026-07-14T18:00:18.000Z',
+    envelope: {
+      resourceId,
+      authorityEpoch: input.authorityEpoch,
+      mutationId: input.mutationId,
+      deviceId: input.deviceId,
+      baseVersion: input.baseCloudVersion,
+      contract: input.contract,
+      schemaVersion: input.schemaVersion,
+      operationKind: input.operationKind,
+      operation: input.operation,
+    },
+  }, { database: db });
+
+  assert.equal(recovered.duplicate, true);
+  assert.equal(recovered.alreadyApplied, true);
+  assert.equal(recovered.mutation.state, 'synced');
+  assert.equal(recovered.mutation.officialCloudVersion, 1);
+  assert.equal(getReplicaByResourceId(resourceId, { database: db }).appliedVersion, 1);
+  assert.equal(
+    listEventsAfter(0).filter((event) => event.mutationId === input.mutationId).length,
+    1,
+    'tail recovery never projects a second local event',
+  );
+});
+
+test('retention deletes only completed rows and preserves unresolved cloud work', () => {
+  const db = openLocalDb();
+  const pendingInput = {
+    ...sharedInput,
+    mutationId: 'mut_shared_0000002',
+    operation: { kind: 'delta', yjs: 'BwgJ' },
+  };
+  const rejectedInput = {
+    ...sharedInput,
+    mutationId: 'mut_shared_0000003',
+    operation: { kind: 'delta', yjs: 'CgsM' },
+  };
+  commitLocalMutation(pendingInput, { database: db, materialize() {}, event: eventFor(pendingInput) });
+  commitLocalMutation(rejectedInput, { database: db, materialize() {}, event: eventFor(rejectedInput) });
+  failCloudMutation(
+    sharedResourceId,
+    rejectedInput.mutationId,
+    { message: 'viewer cannot write', retryable: false },
+    { database: db },
+  );
+
+  db.prepare("UPDATE mutation_journal SET updated_at = '2026-07-13T00:00:00.000Z'").run();
+  const pruned = pruneMutationJournal({
+    database: db,
+    cutoffIso: '2026-07-14T00:00:00.000Z',
+    batchSize: 100,
+  });
+
+  assert.ok(pruned.deleted >= 2, 'completed local and synced rows age out');
+  assert.equal(getMutation(pendingInput.channelId, pendingInput.mutationId, { database: db }).state, 'saved-local');
+  assert.equal(getMutation(rejectedInput.channelId, rejectedInput.mutationId, { database: db }).state, 'rejected');
+});