amalgm 0.1.155 → 0.1.156

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

@@ -0,0 +1,271 @@
+'use strict';
+
+const crypto = require('crypto');
+const path = require('path');
+const { cachedStatement, openLocalDb } = require('./db');
+const { appendStateEvent } = require('./events');
+const { registerReplica } = require('./replicas');
+
+const SHARED_RESOURCE_ID = /^shr_[A-Za-z0-9_-]{16,128}$/;
+const PROMOTION_ID = /^[A-Za-z0-9_-]{16,160}$/;
+
+function invalid(message, statusCode = 400) {
+  return Object.assign(new Error(message), { statusCode });
+}
+
+function requiredText(value, name, max = 1024) {
+  const text = typeof value === 'string' ? value.trim() : '';
+  if (!text || text.length > max || /[\u0000-\u001f\u007f]/.test(text)) {
+    throw invalid(`${name} must be a non-empty string of at most ${max} characters`);
+  }
+  return text;
+}
+
+function normalizeRow(row) {
+  if (!row) return null;
+  return {
+    promotionId: row.promotion_id,
+    resourceId: row.resource_id,
+    localResource: row.local_resource,
+    localPath: row.local_path,
+    contract: row.contract,
+    schemaVersion: Number(row.schema_version),
+    snapshotBase64: row.snapshot_b64,
+    snapshotChecksum: row.snapshot_checksum,
+    snapshotBytes: Number(row.snapshot_bytes),
+    contentBytes: row.content_bytes == null ? null : Number(row.content_bytes),
+    name: row.name || null,
+    mediaType: row.media_type || null,
+    state: row.promotion_state,
+    attemptCount: Number(row.attempt_count),
+    nextAttemptAt: row.next_attempt_at || null,
+    lastError: row.last_error || null,
+    snapshotKey: row.snapshot_key || null,
+    createdAt: row.created_at,
+    updatedAt: row.updated_at,
+  };
+}
+
+function enqueuePromotion(input, options = {}) {
+  const promotionId = requiredText(input?.promotionId, 'promotionId', 160);
+  const resourceId = requiredText(input?.resourceId, 'resourceId', 132);
+  if (!PROMOTION_ID.test(promotionId)) throw invalid('promotionId has an invalid format');
+  if (!SHARED_RESOURCE_ID.test(resourceId)) throw invalid('resourceId has an invalid format');
+  const localResource = requiredText(input?.localResource, 'localResource');
+  const localPath = requiredText(input?.localPath, 'localPath', 4096);
+  const contract = requiredText(input?.contract || 'text-yjs@1', 'contract', 128);
+  const schemaVersion = Number(input?.schemaVersion || 1);
+  if (!Number.isSafeInteger(schemaVersion) || schemaVersion < 1) {
+    throw invalid('schemaVersion must be a positive integer');
+  }
+  const snapshotBase64 = requiredText(input?.snapshotBase64, 'snapshotBase64', 8 * 1024 * 1024);
+  const snapshot = Buffer.from(snapshotBase64, 'base64');
+  const snapshotChecksum = crypto.createHash('sha256').update(snapshot).digest('hex');
+  const contentBytes = input?.contentBytes == null ? null : Number(input.contentBytes);
+  if (contentBytes != null && (!Number.isSafeInteger(contentBytes) || contentBytes < 0)) {
+    throw invalid('contentBytes must be a non-negative integer');
+  }
+  const database = options.database || openLocalDb();
+  const existing = cachedStatement(
+    database,
+    'SELECT * FROM shared_resource_promotions WHERE promotion_id = ?',
+  ).get(promotionId);
+  if (existing) {
+    const row = normalizeRow(existing);
+    if (
+      row.resourceId !== resourceId
+      || row.localResource !== localResource
+      || row.snapshotChecksum !== snapshotChecksum
+    ) {
+      throw invalid(`promotionId ${promotionId} was reused with different content`, 409);
+    }
+    return { promotion: row, duplicate: true };
+  }
+
+  const now = new Date().toISOString();
+  cachedStatement(database, `
+    INSERT INTO shared_resource_promotions (
+      promotion_id,
+      resource_id,
+      local_resource,
+      local_path,
+      contract,
+      schema_version,
+      snapshot_b64,
+      snapshot_checksum,
+      snapshot_bytes,
+      content_bytes,
+      name,
+      media_type,
+      created_at,
+      updated_at
+    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `).run(
+    promotionId,
+    resourceId,
+    localResource,
+    localPath,
+    contract,
+    schemaVersion,
+    snapshotBase64,
+    snapshotChecksum,
+    snapshot.length,
+    contentBytes,
+    input?.name || path.basename(localPath),
+    input?.mediaType || 'application/vnd.amalgm.text-yjs-snapshot',
+    now,
+    now,
+  );
+  const promotion = normalizeRow(
+    cachedStatement(database, 'SELECT * FROM shared_resource_promotions WHERE promotion_id = ?')
+      .get(promotionId),
+  );
+
+  // Wake the already-open internal Local Live stream used by the tunnel
+  // process. This is a control event, not a cloud mutation/version.
+  appendStateEvent({
+    resource: 'shared:promotions',
+    op: 'update',
+    id: promotionId,
+    sharedResourceId: resourceId,
+    value: { state: 'pending' },
+    source: 'shared:promotion',
+  });
+  return { promotion, duplicate: false };
+}
+
+function claimPromotions(options = {}) {
+  const database = options.database || openLocalDb();
+  const limit = Math.max(1, Math.min(Number(options.limit) || 4, 20));
+  const leaseMs = Math.max(1000, Number(options.leaseMs) || 30_000);
+  const now = new Date().toISOString();
+  const leaseUntil = new Date(Date.now() + leaseMs).toISOString();
+  return database.transaction(() => {
+    const rows = cachedStatement(database, `
+      SELECT * FROM shared_resource_promotions
+      WHERE promotion_state = 'pending'
+         OR (promotion_state = 'syncing' AND (next_attempt_at IS NULL OR next_attempt_at <= ?))
+      ORDER BY created_at ASC
+      LIMIT ?
+    `).all(now, limit);
+    const update = cachedStatement(database, `
+      UPDATE shared_resource_promotions
+      SET promotion_state = 'syncing',
+          attempt_count = attempt_count + 1,
+          next_attempt_at = ?,
+          updated_at = ?
+      WHERE promotion_id = ?
+    `);
+    return rows.map((row) => {
+      update.run(leaseUntil, now, row.promotion_id);
+      const promotion = normalizeRow(
+        cachedStatement(database, 'SELECT * FROM shared_resource_promotions WHERE promotion_id = ?')
+          .get(row.promotion_id),
+      );
+      return {
+        promotion,
+        frame: {
+          promotionId: promotion.promotionId,
+          resourceId: promotion.resourceId,
+          contract: promotion.contract,
+          schemaVersion: promotion.schemaVersion,
+          snapshotBase64: promotion.snapshotBase64,
+          snapshotChecksum: promotion.snapshotChecksum,
+          snapshotBytes: promotion.snapshotBytes,
+          contentBytes: promotion.contentBytes,
+          name: promotion.name,
+          mediaType: promotion.mediaType,
+        },
+      };
+    });
+  })();
+}
+
+function acknowledgePromotion(promotionIdInput, acknowledgement, options = {}) {
+  const promotionId = requiredText(promotionIdInput, 'promotionId', 160);
+  const database = options.database || openLocalDb();
+  return database.transaction(() => {
+    const row = cachedStatement(
+      database,
+      'SELECT * FROM shared_resource_promotions WHERE promotion_id = ?',
+    ).get(promotionId);
+    if (!row) throw invalid(`unknown promotion ${promotionId}`, 404);
+    const promotion = normalizeRow(row);
+    if (acknowledgement?.resourceId !== promotion.resourceId) {
+      throw invalid('promotion acknowledgement resource mismatch', 409);
+    }
+    if (promotion.state === 'promoted') return { promotion, duplicate: true };
+
+    registerReplica({
+      resourceId: promotion.resourceId,
+      localResource: promotion.localResource,
+      localPath: promotion.localPath,
+      contract: promotion.contract,
+      schemaVersion: promotion.schemaVersion,
+      authorityEpoch: acknowledgement?.authorityEpoch,
+      appliedVersion: acknowledgement?.headVersion ?? 0,
+      snapshotVersion: acknowledgement?.snapshotVersion ?? 0,
+      snapshotChecksum: acknowledgement?.snapshotChecksum,
+    }, { database });
+
+    const now = new Date().toISOString();
+    cachedStatement(database, `
+      UPDATE shared_resource_promotions
+      SET promotion_state = 'promoted',
+          next_attempt_at = NULL,
+          last_error = NULL,
+          snapshot_key = ?,
+          updated_at = ?
+      WHERE promotion_id = ?
+    `).run(acknowledgement?.snapshotKey || null, now, promotionId);
+    return {
+      promotion: normalizeRow(
+        cachedStatement(database, 'SELECT * FROM shared_resource_promotions WHERE promotion_id = ?')
+          .get(promotionId),
+      ),
+      duplicate: false,
+    };
+  })();
+}
+
+function failPromotion(promotionIdInput, failure, options = {}) {
+  const promotionId = requiredText(promotionIdInput, 'promotionId', 160);
+  const database = options.database || openLocalDb();
+  const retryable = failure?.retryable !== false;
+  const now = new Date().toISOString();
+  const result = cachedStatement(database, `
+    UPDATE shared_resource_promotions
+    SET promotion_state = ?,
+        next_attempt_at = ?,
+        last_error = ?,
+        updated_at = ?
+    WHERE promotion_id = ? AND promotion_state != 'promoted'
+  `).run(
+    retryable ? 'syncing' : 'rejected',
+    retryable ? new Date(Date.now() + 1000).toISOString() : null,
+    String(failure?.message || 'promotion failed').slice(0, 4000),
+    now,
+    promotionId,
+  );
+  if (!result.changes) throw invalid(`unknown or completed promotion ${promotionId}`, 404);
+  return normalizeRow(
+    cachedStatement(database, 'SELECT * FROM shared_resource_promotions WHERE promotion_id = ?')
+      .get(promotionId),
+  );
+}
+
+function getPromotion(promotionId, options = {}) {
+  const database = options.database || openLocalDb();
+  return normalizeRow(
+    cachedStatement(database, 'SELECT * FROM shared_resource_promotions WHERE promotion_id = ?')
+      .get(promotionId),
+  );
+}
+
+module.exports = {
+  acknowledgePromotion,
+  claimPromotions,
+  enqueuePromotion,
+  failPromotion,
+  getPromotion,
+};

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

@@ -0,0 +1,200 @@
+'use strict';
+
+/**
+ * Local bindings for cloud-authoritative resources.
+ *
+ * The binding is the answer to "is this edit cloud-backed?". That decision
+ * is owned by the runtime and persisted in SQLite; it is never trusted from
+ * a browser mutation payload.
+ */
+
+const { cachedStatement, openLocalDb } = require('./db');
+
+const SHARED_RESOURCE_ID = /^shr_[A-Za-z0-9_-]{16,128}$/;
+const CONTRACT = /^[A-Za-z0-9][A-Za-z0-9._:@/-]{0,127}$/;
+
+function invalid(message, statusCode = 400) {
+  return Object.assign(new Error(message), { statusCode });
+}
+
+function requiredText(value, name, max = 1024) {
+  const text = typeof value === 'string' ? value.trim() : '';
+  if (!text || text.length > max || /[\u0000-\u001f\u007f]/.test(text)) {
+    throw invalid(`${name} must be a non-empty string of at most ${max} characters`);
+  }
+  return text;
+}
+
+function integer(value, name, minimum) {
+  const number = Number(value);
+  if (!Number.isSafeInteger(number) || number < minimum) {
+    throw invalid(`${name} must be an integer >= ${minimum}`);
+  }
+  return number;
+}
+
+function normalizeReplica(row) {
+  if (!row) return null;
+  return {
+    resourceId: row.resource_id,
+    localResource: row.local_resource,
+    localPath: row.local_path,
+    contract: row.contract,
+    schemaVersion: Number(row.schema_version),
+    authorityEpoch: Number(row.authority_epoch),
+    appliedVersion: Number(row.applied_version),
+    snapshotVersion: Number(row.snapshot_version),
+    snapshotChecksum: row.snapshot_checksum || null,
+    syncStatus: row.sync_status,
+    lastError: row.last_error || null,
+    createdAt: row.created_at,
+    updatedAt: row.updated_at,
+  };
+}
+
+function registerReplica(input, options = {}) {
+  const resourceId = requiredText(input?.resourceId, 'resourceId', 132);
+  if (!SHARED_RESOURCE_ID.test(resourceId)) {
+    throw invalid('resourceId must be an opaque id beginning with shr_');
+  }
+  const localResource = requiredText(input?.localResource, 'localResource');
+  const localPath = requiredText(input?.localPath, 'localPath', 4096);
+  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 appliedVersion = integer(input?.appliedVersion ?? 0, 'appliedVersion', 0);
+  const snapshotVersion = integer(input?.snapshotVersion ?? appliedVersion, 'snapshotVersion', 0);
+  if (snapshotVersion > appliedVersion) throw invalid('snapshotVersion cannot exceed appliedVersion');
+  const snapshotChecksum = input?.snapshotChecksum == null
+    ? null
+    : requiredText(input.snapshotChecksum, 'snapshotChecksum', 64);
+  if (snapshotChecksum && !/^[0-9a-f]{64}$/.test(snapshotChecksum)) {
+    throw invalid('snapshotChecksum must be lowercase sha256 hex');
+  }
+  const database = options.database || openLocalDb();
+  const existing = cachedStatement(
+    database,
+    'SELECT * FROM shared_resource_replicas WHERE resource_id = ?',
+  ).get(resourceId);
+  if (existing) {
+    const normalized = normalizeReplica(existing);
+    if (
+      normalized.localResource !== localResource
+      || normalized.localPath !== localPath
+      || normalized.contract !== contract
+      || normalized.schemaVersion !== schemaVersion
+    ) {
+      throw invalid(`shared resource ${resourceId} is already bound differently`, 409);
+    }
+    return { replica: normalized, duplicate: true };
+  }
+
+  const now = new Date().toISOString();
+  try {
+    cachedStatement(database, `
+      INSERT INTO shared_resource_replicas (
+        resource_id,
+        local_resource,
+        local_path,
+        contract,
+        schema_version,
+        authority_epoch,
+        applied_version,
+        snapshot_version,
+        snapshot_checksum,
+        sync_status,
+        created_at,
+        updated_at
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, 'synced', ?, ?)
+    `).run(
+      resourceId,
+      localResource,
+      localPath,
+      contract,
+      schemaVersion,
+      authorityEpoch,
+      appliedVersion,
+      snapshotVersion,
+      snapshotChecksum,
+      now,
+      now,
+    );
+  } catch (error) {
+    if (String(error?.code || '').includes('CONSTRAINT')) {
+      throw invalid('that local file is already bound to another shared resource', 409);
+    }
+    throw error;
+  }
+  return {
+    replica: normalizeReplica(
+      cachedStatement(database, 'SELECT * FROM shared_resource_replicas WHERE resource_id = ?')
+        .get(resourceId),
+    ),
+    duplicate: false,
+  };
+}
+
+function getReplicaByResourceId(resourceId, options = {}) {
+  const database = options.database || openLocalDb();
+  return normalizeReplica(
+    cachedStatement(database, 'SELECT * FROM shared_resource_replicas WHERE resource_id = ?')
+      .get(resourceId),
+  );
+}
+
+function getReplicaByLocalResource(localResource, options = {}) {
+  const database = options.database || openLocalDb();
+  return normalizeReplica(
+    cachedStatement(database, 'SELECT * FROM shared_resource_replicas WHERE local_resource = ?')
+      .get(localResource),
+  );
+}
+
+function listReplicas(options = {}) {
+  const database = options.database || openLocalDb();
+  return cachedStatement(database, 'SELECT * FROM shared_resource_replicas ORDER BY created_at ASC')
+    .all()
+    .map(normalizeReplica);
+}
+
+function refreshReplicaAuthority(input, options = {}) {
+  const resourceId = requiredText(input?.resourceId, 'resourceId', 132);
+  const authorityEpoch = integer(input?.authorityEpoch, 'authorityEpoch', 1);
+  const headVersion = integer(input?.headVersion, 'headVersion', 0);
+  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);
+  if (
+    (input?.contract && input.contract !== row.contract)
+    || (input?.schemaVersion && Number(input.schemaVersion) !== Number(row.schema_version))
+  ) {
+    throw invalid(`shared resource ${resourceId} contract changed`, 409);
+  }
+  if (authorityEpoch < Number(row.authority_epoch)) {
+    return normalizeReplica(row);
+  }
+  cachedStatement(database, `
+    UPDATE shared_resource_replicas
+    SET authority_epoch = ?,
+        sync_status = CASE WHEN applied_version < ? THEN 'syncing' ELSE sync_status END,
+        last_error = CASE
+          WHEN applied_version < ? THEN 'official tail recovery required'
+          ELSE last_error
+        END,
+        updated_at = ?
+    WHERE resource_id = ?
+  `).run(authorityEpoch, headVersion, headVersion, new Date().toISOString(), resourceId);
+  return getReplicaByResourceId(resourceId, { database });
+}
+
+module.exports = {
+  getReplicaByLocalResource,
+  getReplicaByResourceId,
+  listReplicas,
+  refreshReplicaAuthority,
+  registerReplica,
+};

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

@@ -98,6 +98,10 @@ async function handleDocOpen(body, sendJson) {
 
 async function handleDocUpdate(body, sendJson) {
   try {
+    if (Array.isArray(body?.mutations)) {
+      sendJson(200, require('./docs').applyDocMutations(body?.path, body.mutations));
+      return;
+    }
     const updates = body?.updates ?? body?.update;
     if (updates == null) {
       sendJson(400, { error: 'body requires "updates" (array of base64 Yjs updates) or "update"' });