amalgm 0.1.245 → 0.1.246

package/runtime/scripts/amalgm-mcp/registration/entity-cloud.js

@@ -0,0 +1,456 @@
+'use strict';
+
+/**
+ * The entity-cloud boundary's local half.
+ *
+ * This module deliberately stores only logical graph facts in the cloud
+ * snapshot/outbox. The observer owns paths, inodes, watcher state, and
+ * evidence; identity owns UUID graph facts and the one durable delivery
+ * intent that accompanies each local graph mutation.
+ */
+
+const crypto = require('crypto');
+
+const ENTITY_CLOUD_CONTRACT = 'amalgm-entity-registry@1';
+const ENTITY_CLOUD_SCHEMA_VERSION = 1;
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+const TYPES = new Set([
+  'workspace', 'folder', 'repo.git', 'file.text', 'file.binary', 'link', 'reference',
+]);
+const ROOT_TYPES = new Set(['workspace', 'repo.git', 'file.text', 'file.binary', 'link']);
+const CONTENT_HEAD = /^[0-9a-f]{64}$/;
+
+function privateEntityResourceId(userId) {
+  return `pvr_${crypto
+    .createHash('sha256')
+    .update(`private-user:${userId}:${ENTITY_CLOUD_CONTRACT}`)
+    .digest('base64url')
+    .slice(0, 32)}`;
+}
+
+function now() {
+  return new Date().toISOString();
+}
+
+function stableJson(value) {
+  return JSON.stringify(value);
+}
+
+function sameRecord(left, right) {
+  return stableJson(left) === stableJson(right);
+}
+
+function assertRecord(value) {
+  if (!value || typeof value !== 'object' || typeof value.uuid !== 'string' || !UUID.test(value.uuid)
+    || typeof value.type !== 'string' || !TYPES.has(value.type)
+    || (value.parentUUID !== null && (typeof value.parentUUID !== 'string' || !UUID.test(value.parentUUID)))
+    || typeof value.name !== 'string' || !value.name || value.name.includes('/') || value.name.includes('\0')
+    || !['active', 'trashed', 'deleted'].includes(value.status)
+    || typeof value.version !== 'string' || !/^[0-9a-f]{64}$/.test(value.version)
+    || (value.payloadVersion !== null && typeof value.payloadVersion !== 'string')) {
+    throw new Error('cloud entity snapshot has an invalid record');
+  }
+  if (value.parentUUID === null && !ROOT_TYPES.has(value.type)) {
+    throw new Error(`cloud entity ${value.uuid} is not a valid tree root`);
+  }
+  return {
+    uuid: value.uuid.toLowerCase(),
+    type: value.type,
+    parentUUID: value.parentUUID === null ? null : value.parentUUID.toLowerCase(),
+    name: value.name,
+    status: value.status,
+    version: value.version,
+    payloadVersion: value.payloadVersion,
+  };
+}
+
+function snapshotFromRecords(records) {
+  const normalized = records.map(assertRecord).sort((left, right) => left.uuid.localeCompare(right.uuid));
+  if (new Set(normalized.map((record) => record.uuid)).size !== normalized.length) {
+    throw new Error('cloud entity snapshot has duplicate UUIDs');
+  }
+  return {
+    schemaVersion: ENTITY_CLOUD_SCHEMA_VERSION,
+    kind: 'amalgm-entity-registry',
+    records: normalized,
+  };
+}
+
+function parseSnapshot(bytes) {
+  let snapshot;
+  try {
+    snapshot = JSON.parse(bytes.toString('utf8'));
+  } catch {
+    throw new Error('cloud entity snapshot is not JSON');
+  }
+  if (snapshot?.schemaVersion !== ENTITY_CLOUD_SCHEMA_VERSION
+    || snapshot?.kind !== 'amalgm-entity-registry'
+    || !Array.isArray(snapshot.records)) {
+    throw new Error('cloud entity snapshot has an unsupported shape');
+  }
+  return snapshotFromRecords(snapshot.records);
+}
+
+/**
+ * A service-local adapter over the identity database. It intentionally has
+ * no watcher imports: a cloud record may be known on this machine long before
+ * `amalgm add <uuid>` chooses and validates local ground for it.
+ */
+function createEntityCloud({ db, userId, deviceId, content = null }) {
+  if (!db) throw new Error('createEntityCloud requires an identity database');
+  const ownerUserId = typeof userId === 'string' && userId ? userId : null;
+  const localDeviceId = typeof deviceId === 'string' && deviceId ? deviceId : null;
+
+  function contentHead(record) {
+    return ['file.text', 'file.binary'].includes(record?.type)
+      && typeof record?.payloadVersion === 'string'
+      && CONTENT_HEAD.test(record.payloadVersion);
+  }
+
+  function queueContent(record, resourceId, { queue = false } = {}) {
+    if (!contentHead(record)) return;
+    if (!content || typeof content.has !== 'function') {
+      throw new Error('file entity content is unavailable: registration must capture bytes before it records their cloud head');
+    }
+    if (!content.has({ contentHash: record.payloadVersion })) {
+      throw new Error('file entity bytes were not captured before its cloud head committed');
+    }
+    if (queue) content.ensureUpload({ resourceId, contentHash: record.payloadVersion });
+  }
+
+  function replica() {
+    const row = db.prepare('SELECT * FROM entity_cloud_replica WHERE singleton = 1').get();
+    if (!row) return null;
+    return {
+      resourceId: row.resource_id,
+      deviceId: row.device_id,
+      authorityEpoch: Number(row.authority_epoch),
+      headVersion: Number(row.head_version),
+      state: row.state,
+      snapshotCutoff: row.snapshot_cutoff == null ? null : Number(row.snapshot_cutoff),
+    };
+  }
+
+  function identity() {
+    if (!ownerUserId || !localDeviceId) return { enabled: false, reason: 'runtime is not enrolled to a user' };
+    return {
+      enabled: true,
+      resourceId: privateEntityResourceId(ownerUserId),
+      contract: ENTITY_CLOUD_CONTRACT,
+      schemaVersion: ENTITY_CLOUD_SCHEMA_VERSION,
+      deviceId: localDeviceId,
+    };
+  }
+
+  function saveReplica(value) {
+    db.prepare(`
+      INSERT INTO entity_cloud_replica (
+        singleton, resource_id, device_id, authority_epoch, head_version,
+        state, snapshot_cutoff, updated_at
+      ) VALUES (1, ?, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT(singleton) DO UPDATE SET
+        resource_id = excluded.resource_id,
+        device_id = excluded.device_id,
+        authority_epoch = excluded.authority_epoch,
+        head_version = excluded.head_version,
+        state = excluded.state,
+        snapshot_cutoff = excluded.snapshot_cutoff,
+        updated_at = excluded.updated_at
+    `).run(
+      value.resourceId,
+      value.deviceId,
+      value.authorityEpoch,
+      value.headVersion,
+      value.state,
+      value.snapshotCutoff ?? null,
+      now(),
+    );
+  }
+
+  /** Invoked by registry/index.js INSIDE its identity transaction. */
+  function journal({ record }) {
+    const current = replica();
+    // Bootstrap roots are included in the first immutable snapshot. No
+    // unscoped row is written before the cloud replica exists.
+    if (!current || current.state !== 'active') return;
+    // The SQLite mutation is the durable delivery intent. Its post-commit
+    // content drain creates the filesystem upload cursor; doing that here
+    // would let a rolled-back identity write upload unreachable bytes.
+    queueContent(record, current.resourceId);
+    const mutationId = `ent_${crypto.randomBytes(18).toString('base64url')}`;
+    const operation = { kind: 'entity.upsert', record: assertRecord(record) };
+    const createdAt = now();
+    db.prepare(`
+      INSERT INTO entity_cloud_mutations (
+        resource_id, mutation_id, operation_json, mutation_state,
+        created_at, updated_at
+      ) VALUES (?, ?, ?, 'pending', ?, ?)
+    `).run(current.resourceId, mutationId, stableJson(operation), createdAt, createdAt);
+  }
+
+  function assertRegistrationReady() {
+    if (!ownerUserId) return;
+    const current = replica();
+    if (!current || current.state !== 'active') {
+      const error = new Error('entity cloud registry is not ready yet; wait for the signed-in runtime to finish its first cloud handshake');
+      error.code = 'entity_cloud_not_ready';
+      error.statusCode = 409;
+      throw error;
+    }
+  }
+
+  function bootstrap(registry) {
+    const currentIdentity = identity();
+    if (!currentIdentity.enabled) return currentIdentity;
+    const existing = replica();
+    if (existing?.state === 'active') {
+      throw new Error('entity cloud registry already exists locally; cloud lookup must not create it again');
+    }
+    const snapshot = snapshotFromRecords(registry.syncRecords());
+    const cutoff = db.prepare('SELECT COALESCE(MAX(sequence), 0) AS sequence FROM entity_cloud_mutations').get().sequence;
+    saveReplica({
+      resourceId: currentIdentity.resourceId,
+      deviceId: currentIdentity.deviceId,
+      authorityEpoch: 1,
+      headVersion: 0,
+      state: 'bootstrapping',
+      snapshotCutoff: Number(cutoff),
+    });
+    const bytes = Buffer.from(stableJson(snapshot), 'utf8');
+    return {
+      ...currentIdentity,
+      snapshotBase64: bytes.toString('base64'),
+      snapshotBytes: bytes.length,
+      snapshotChecksum: crypto.createHash('sha256').update(bytes).digest('hex'),
+    };
+  }
+
+  function install({ registry, resourceId, authorityEpoch, headVersion, snapshotBase64, snapshotChecksum }) {
+    const currentIdentity = identity();
+    if (!currentIdentity.enabled || resourceId !== currentIdentity.resourceId) {
+      throw new Error('cloud entity registry identity does not belong to this runtime user');
+    }
+    const bytes = Buffer.from(String(snapshotBase64 || ''), 'base64');
+    const checksum = crypto.createHash('sha256').update(bytes).digest('hex');
+    if (checksum !== snapshotChecksum) throw new Error('cloud entity snapshot checksum mismatch');
+    const snapshot = parseSnapshot(bytes);
+    const local = snapshotFromRecords(registry.syncRecords());
+    const bootstrapping = replica()?.state === 'bootstrapping';
+    if (bootstrapping && !sameRecord(local, snapshot)) {
+      throw new Error('first cloud entity snapshot does not match the locally bootstrapped identity graph');
+    }
+    if (!bootstrapping && !sameRecord(local, snapshot)) {
+      // Import is intentionally delayed until the materializer can bind every
+      // extra root deliberately. Failing loudly is safer than silently
+      // treating a remote entity as watched local ground.
+      throw new Error('cloud entity graph differs from this local registry; materialization import is not enabled for this runtime yet');
+    }
+    if (!Number.isInteger(Number(authorityEpoch)) || Number(authorityEpoch) < 1
+      || !Number.isInteger(Number(headVersion)) || Number(headVersion) < 0) {
+      throw new Error('cloud entity registry authority is invalid');
+    }
+    // Initial snapshot records have no tail mutation to trigger a content
+    // upload. Queue every actual file head before calling this replica
+    // active; from that moment its graph may be advertised to the cloud.
+    for (const record of snapshot.records) queueContent(record, resourceId, { queue: true });
+    saveReplica({
+      resourceId,
+      deviceId: currentIdentity.deviceId,
+      authorityEpoch: Number(authorityEpoch),
+      headVersion: Number(headVersion),
+      state: 'active',
+      snapshotCutoff: null,
+    });
+    return { resourceId, records: snapshot.records.length, headVersion: Number(headVersion) };
+  }
+
+  function claim({ limit = 16, leaseMs = 30_000 } = {}) {
+    const current = replica();
+    if (!current || current.state !== 'active') return [];
+    const boundedLimit = Math.max(1, Math.min(Number(limit) || 16, 100));
+    const leaseUntil = new Date(Date.now() + Math.max(1_000, Number(leaseMs) || 30_000)).toISOString();
+    const started = now();
+    return db.transaction(() => {
+      // One mutation per resource at a time keeps each baseVersion equal to
+      // the official head advanced by the previous acknowledgement.
+      const rows = db.prepare(`
+        SELECT * FROM entity_cloud_mutations
+        WHERE resource_id = ?
+          AND (mutation_state = 'pending'
+            OR (mutation_state = 'syncing' AND (next_attempt_at IS NULL OR next_attempt_at <= ?)))
+        ORDER BY sequence ASC
+        LIMIT 1
+      `).all(current.resourceId, started).slice(0, boundedLimit);
+      const claimRow = db.prepare(`
+        UPDATE entity_cloud_mutations
+        SET mutation_state = 'syncing', base_version = ?, attempt_count = attempt_count + 1,
+            next_attempt_at = ?, updated_at = ?
+        WHERE sequence = ?
+      `);
+      return rows.flatMap((row) => {
+        const operation = JSON.parse(row.operation_json);
+        // The logical mutation is intentionally held behind the immutable
+        // content manifest. A cloud graph never advances to a file head
+        // whose bytes have not reached private R2 storage.
+        if (contentHead(operation?.record)
+          && (!content || !content.uploaded({ resourceId: current.resourceId, contentHash: operation.record.payloadVersion }))) {
+          return [];
+        }
+        claimRow.run(current.headVersion, leaseUntil, started, row.sequence);
+        return [{
+          resourceId: current.resourceId,
+          mutationId: row.mutation_id,
+          deviceId: current.deviceId,
+          authorityEpoch: current.authorityEpoch,
+          baseVersion: current.headVersion,
+          contract: ENTITY_CLOUD_CONTRACT,
+          schemaVersion: ENTITY_CLOUD_SCHEMA_VERSION,
+          operationKind: 'entity.upsert',
+          operation,
+        }];
+      });
+    })();
+  }
+
+  function claimContent({ leaseMs = 30_000 } = {}) {
+    const current = replica();
+    if (!current || current.state !== 'active' || !content) return null;
+    // Later registrations journal their record transactionally in SQLite.
+    // Derive its content-upload cursor only after that commit exists, so a
+    // failed transaction cannot publish a private object no entity names.
+    const rows = db.prepare(`
+      SELECT operation_json FROM entity_cloud_mutations
+      WHERE resource_id = ? AND mutation_state IN ('pending', 'syncing')
+      ORDER BY sequence ASC
+    `).all(current.resourceId);
+    for (const row of rows) {
+      const record = JSON.parse(row.operation_json)?.record;
+      queueContent(record, current.resourceId, { queue: true });
+    }
+    return content.claim({ resourceId: current.resourceId, leaseMs });
+  }
+
+  function acknowledgeContent({ resourceId, contentHash, kind, partIndex }) {
+    const current = replica();
+    if (!current || current.resourceId !== resourceId || !content) {
+      throw new Error(`unknown entity content resource ${resourceId}`);
+    }
+    return content.acknowledge({ resourceId, contentHash, kind, partIndex });
+  }
+
+  function failContent({ resourceId, contentHash, message }) {
+    const current = replica();
+    if (!current || current.resourceId !== resourceId || !content) {
+      throw new Error(`unknown entity content resource ${resourceId}`);
+    }
+    return content.fail({ resourceId, contentHash, message });
+  }
+
+  function acknowledge({ resourceId, mutationId, version, committedAt }) {
+    const current = replica();
+    if (!current || current.resourceId !== resourceId) throw new Error(`unknown entity cloud resource ${resourceId}`);
+    if (!Number.isInteger(Number(version)) || Number(version) < 1) throw new Error('entity cloud acknowledgement version is invalid');
+    return db.transaction(() => {
+      const row = db.prepare('SELECT * FROM entity_cloud_mutations WHERE resource_id = ? AND mutation_id = ?')
+        .get(resourceId, mutationId);
+      if (!row) throw new Error(`unknown entity cloud mutation ${mutationId}`);
+      if (row.mutation_state === 'synced') return { duplicate: true, version: Number(row.official_version) };
+      if (!['pending', 'syncing'].includes(row.mutation_state)) throw new Error(`entity cloud mutation ${mutationId} cannot sync from ${row.mutation_state}`);
+      db.prepare(`
+        UPDATE entity_cloud_mutations
+        SET mutation_state = 'synced', official_version = ?, cloud_committed_at = ?,
+            next_attempt_at = NULL, last_error = NULL, updated_at = ?
+        WHERE sequence = ?
+      `).run(Number(version), String(committedAt || now()), now(), row.sequence);
+      if (Number(version) > current.headVersion) {
+        saveReplica({ ...current, headVersion: Number(version) });
+      }
+      return { duplicate: false, version: Number(version) };
+    })();
+  }
+
+  function fail({ resourceId, mutationId, message, retryable = true }) {
+    const current = replica();
+    if (!current || current.resourceId !== resourceId) throw new Error(`unknown entity cloud resource ${resourceId}`);
+    const row = db.prepare('SELECT sequence, mutation_state FROM entity_cloud_mutations WHERE resource_id = ? AND mutation_id = ?')
+      .get(resourceId, mutationId);
+    if (!row) throw new Error(`unknown entity cloud mutation ${mutationId}`);
+    if (row.mutation_state === 'synced') return { duplicate: true };
+    db.prepare(`
+      UPDATE entity_cloud_mutations
+      SET mutation_state = ?, next_attempt_at = ?, last_error = ?, updated_at = ?
+      WHERE sequence = ?
+    `).run(
+      retryable ? 'syncing' : 'rejected',
+      retryable ? new Date(Date.now() + 1_000).toISOString() : null,
+      String(message || 'entity cloud mutation failed').slice(0, 4000),
+      now(),
+      row.sequence,
+    );
+    return { duplicate: false };
+  }
+
+  function ingest({ registry, envelope, version, committedAt }) {
+    const current = replica();
+    if (!current || current.state !== 'active') throw new Error('entity cloud registry is not active');
+    if (envelope?.resourceId !== current.resourceId
+      || envelope?.contract !== ENTITY_CLOUD_CONTRACT
+      || Number(envelope?.schemaVersion) !== ENTITY_CLOUD_SCHEMA_VERSION
+      || envelope?.operationKind !== 'entity.upsert'
+      || envelope?.operation?.kind !== 'entity.upsert') {
+      throw new Error('cloud entity mutation does not belong to this registry');
+    }
+    const record = assertRecord(envelope.operation.record);
+    const localMutation = db.prepare('SELECT mutation_state FROM entity_cloud_mutations WHERE resource_id = ? AND mutation_id = ?')
+      .get(current.resourceId, envelope.mutationId);
+    if (localMutation) {
+      return acknowledge({
+        resourceId: current.resourceId,
+        mutationId: envelope.mutationId,
+        version,
+        committedAt,
+      });
+    }
+    // The snapshot install is the first place an unbound remote root may
+    // enter this machine. Until `add` has the materializer/catalog rail,
+    // accepting a later unknown root here would violate the registry's
+    // watched-root loss law. A duplicate record is safe and advances the
+    // local cloud cursor; a distinct record is deliberately surfaced.
+    let local;
+    try {
+      local = registry.syncRecord(record.uuid);
+    } catch {
+      throw new Error('remote entity mutation needs cloud-to-local materialization before this device can apply it');
+    }
+    if (!sameRecord(local, record)) {
+      throw new Error('remote entity mutation conflicts with this device; materialize or reconcile the cloud entity first');
+    }
+    if (Number(version) > current.headVersion) saveReplica({ ...current, headVersion: Number(version) });
+    return { duplicate: true, version: Number(version) };
+  }
+
+  return {
+    identity,
+    journal,
+    assertRegistrationReady,
+    bootstrap,
+    install,
+    claim,
+    acknowledge,
+    fail,
+    ingest,
+    claimContent,
+    acknowledgeContent,
+    failContent,
+    replica,
+  };
+}
+
+module.exports = {
+  ENTITY_CLOUD_CONTRACT,
+  ENTITY_CLOUD_SCHEMA_VERSION,
+  createEntityCloud,
+  parseSnapshot,
+  privateEntityResourceId,
+  snapshotFromRecords,
+};