amalgm 0.1.155 → 0.1.156

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

@@ -0,0 +1,800 @@
+'use strict';
+
+/**
+ * Durable mutation journal for @amalgm/live.
+ *
+ * Every durable SDK edit has exactly one row here, whether its channel is
+ * local-only or cloud-authoritative. The cloud outbox is a query over shared
+ * rows whose lifecycle still needs delivery; it is not a second table.
+ *
+ * event_log stays the published Local Live delivery cursor. A journal row is
+ * projected into event_log only after the file/local store is materialized,
+ * so current snapshot/replay/stream ordering never observes an unsaved edit.
+ */
+
+const { cachedStatement, openLocalDb } = require('./db');
+const { insertStateEvent, publishStateEvent } = require('./events');
+
+const MAX_MUTATION_BYTES = 4 * 1024 * 1024;
+const DEFAULT_CLAIM_LIMIT = 100;
+const DEFAULT_CLAIM_LEASE_MS = 30_000;
+const SHARED_RESOURCE_ID = /^shr_[A-Za-z0-9_-]{16,128}$/;
+const MUTATION_ID = /^[A-Za-z0-9_-]{16,160}$/;
+const OPERATION_KIND = /^[a-z][a-z0-9._:-]{0,63}$/;
+const CONTRACT = /^[A-Za-z0-9][A-Za-z0-9._:@/-]{0,127}$/;
+
+function invalid(message, statusCode = 400) {
+  const error = new Error(message);
+  error.statusCode = statusCode;
+  return error;
+}
+
+function cleanText(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 nonNegativeInteger(value, name, fallback = 0) {
+  const candidate = value === undefined || value === null ? fallback : Number(value);
+  if (!Number.isInteger(candidate) || candidate < 0) {
+    throw invalid(`${name} must be a non-negative integer`);
+  }
+  return candidate;
+}
+
+function positiveInteger(value, name) {
+  const candidate = Number(value);
+  if (!Number.isInteger(candidate) || candidate <= 0) {
+    throw invalid(`${name} must be a positive integer`);
+  }
+  return candidate;
+}
+
+function safeJsonParse(value) {
+  try {
+    return JSON.parse(value);
+  } catch {
+    return null;
+  }
+}
+
+function normalizeMutationInput(input) {
+  if (!input || typeof input !== 'object') throw invalid('mutation input is required');
+
+  const channelId = cleanText(input.channelId, 'channelId');
+  const localResource = cleanText(input.localResource, 'localResource');
+  const mutationId = cleanText(input.mutationId, 'mutationId', 160);
+  if (!MUTATION_ID.test(mutationId)) {
+    throw invalid('mutationId must be a stable opaque id using letters, numbers, _ or -');
+  }
+
+  const contract = cleanText(input.contract, 'contract', 128);
+  if (!CONTRACT.test(contract)) throw invalid('contract has an invalid format');
+  const schemaVersion = positiveInteger(input.schemaVersion, 'schemaVersion');
+
+  const operation = input.operation;
+  if (operation === undefined) throw invalid('operation is required');
+  const operationKind = cleanText(
+    input.operationKind ?? (operation && typeof operation === 'object' ? operation.kind : ''),
+    'operationKind',
+    64,
+  );
+  if (!OPERATION_KIND.test(operationKind)) throw invalid('operationKind has an invalid format');
+
+  let operationJson;
+  try {
+    operationJson = JSON.stringify(operation);
+  } catch {
+    throw invalid('operation must be JSON-serializable');
+  }
+  if (operationJson === undefined) throw invalid('operation must be JSON-serializable');
+  if (Buffer.byteLength(operationJson, 'utf8') > MAX_MUTATION_BYTES) {
+    throw invalid(`operation exceeds the ${MAX_MUTATION_BYTES}-byte durable mutation limit`, 413);
+  }
+
+  const sharedResourceId = input.sharedResourceId == null
+    ? null
+    : cleanText(input.sharedResourceId, 'sharedResourceId', 132);
+  if (sharedResourceId && !SHARED_RESOURCE_ID.test(sharedResourceId)) {
+    throw invalid('sharedResourceId must be an opaque id beginning with shr_');
+  }
+  if (sharedResourceId && channelId !== `resource:${sharedResourceId}`) {
+    throw invalid('a shared mutation channelId must be resource:<sharedResourceId>');
+  }
+
+  const authorityEpoch = nonNegativeInteger(input.authorityEpoch, 'authorityEpoch');
+  const baseCloudVersion = nonNegativeInteger(input.baseCloudVersion, 'baseCloudVersion');
+  const deviceId = input.deviceId == null ? null : cleanText(input.deviceId, 'deviceId', 256);
+  if (sharedResourceId && authorityEpoch < 1) {
+    throw invalid('shared mutations require authorityEpoch >= 1');
+  }
+  if (sharedResourceId && !deviceId) {
+    throw invalid('shared mutations require deviceId');
+  }
+
+  const localRevision = input.localRevision == null
+    ? null
+    : nonNegativeInteger(input.localRevision, 'localRevision');
+
+  return {
+    channelId,
+    localResource,
+    sharedResourceId,
+    mutationId,
+    deviceId,
+    authorityEpoch,
+    baseCloudVersion,
+    contract,
+    schemaVersion,
+    operationKind,
+    operationJson,
+    operation,
+    localRevision,
+  };
+}
+
+function normalizeJournalRow(row) {
+  if (!row) return null;
+  return {
+    journalId: Number(row.journal_id),
+    channelId: row.channel_id,
+    localResource: row.local_resource,
+    sharedResourceId: row.shared_resource_id || null,
+    mutationId: row.mutation_id,
+    deviceId: row.device_id || null,
+    authorityEpoch: Number(row.authority_epoch || 0),
+    baseCloudVersion: Number(row.base_cloud_version || 0),
+    officialCloudVersion: row.official_cloud_version == null
+      ? null
+      : Number(row.official_cloud_version),
+    contract: row.contract,
+    schemaVersion: Number(row.schema_version),
+    operationKind: row.operation_kind,
+    operation: safeJsonParse(row.operation_json),
+    origin: row.mutation_origin,
+    state: row.mutation_state,
+    localRevision: row.local_revision == null ? null : Number(row.local_revision),
+    materializedAt: row.materialized_at || null,
+    eventSeq: row.event_seq == null ? null : Number(row.event_seq),
+    attemptCount: Number(row.attempt_count || 0),
+    nextAttemptAt: row.next_attempt_at || null,
+    lastError: row.last_error || null,
+    cloudCommittedAt: row.cloud_committed_at || null,
+    createdAt: row.created_at,
+    updatedAt: row.updated_at,
+  };
+}
+
+function getMutationRow(database, channelId, mutationId) {
+  return cachedStatement(
+    database,
+    'SELECT * FROM mutation_journal WHERE channel_id = ? AND mutation_id = ?',
+  ).get(channelId, mutationId) || null;
+}
+
+function sameMutation(existing, mutation) {
+  return existing.local_resource === mutation.localResource
+    && (existing.shared_resource_id || null) === mutation.sharedResourceId
+    && (existing.device_id || null) === mutation.deviceId
+    && Number(existing.authority_epoch || 0) === mutation.authorityEpoch
+    && Number(existing.base_cloud_version || 0) === mutation.baseCloudVersion
+    && existing.contract === mutation.contract
+    && Number(existing.schema_version) === mutation.schemaVersion
+    && existing.operation_kind === mutation.operationKind
+    && existing.operation_json === mutation.operationJson
+    && (existing.local_revision == null ? null : Number(existing.local_revision)) === mutation.localRevision;
+}
+
+function sameCloudEnvelope(existing, mutation) {
+  return existing.local_resource === mutation.localResource
+    && (existing.shared_resource_id || null) === mutation.sharedResourceId
+    && (existing.device_id || null) === mutation.deviceId
+    && Number(existing.authority_epoch || 0) === mutation.authorityEpoch
+    && Number(existing.base_cloud_version || 0) === mutation.baseCloudVersion
+    && existing.contract === mutation.contract
+    && Number(existing.schema_version) === mutation.schemaVersion
+    && existing.operation_kind === mutation.operationKind
+    && existing.operation_json === mutation.operationJson;
+}
+
+function journalMutation(input, options = {}) {
+  const mutation = normalizeMutationInput(input);
+  const database = options.database || openLocalDb();
+  const persist = typeof options.persist === 'function' ? options.persist : null;
+
+  return database.transaction(() => {
+    const existing = getMutationRow(database, mutation.channelId, mutation.mutationId);
+    if (existing) {
+      if (!sameMutation(existing, mutation)) {
+        throw invalid(
+          `mutationId ${mutation.mutationId} was reused with different content`,
+          409,
+        );
+      }
+      return { mutation: normalizeJournalRow(existing), duplicate: true };
+    }
+
+    if (persist) persist(database, mutation);
+
+    const info = cachedStatement(database, `
+      INSERT INTO mutation_journal (
+        channel_id,
+        local_resource,
+        shared_resource_id,
+        mutation_id,
+        device_id,
+        authority_epoch,
+        base_cloud_version,
+        contract,
+        schema_version,
+        operation_kind,
+        operation_json,
+        mutation_origin,
+        mutation_state,
+        local_revision
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'local', 'saving-local', ?)
+    `).run(
+      mutation.channelId,
+      mutation.localResource,
+      mutation.sharedResourceId,
+      mutation.mutationId,
+      mutation.deviceId,
+      mutation.authorityEpoch,
+      mutation.baseCloudVersion,
+      mutation.contract,
+      mutation.schemaVersion,
+      mutation.operationKind,
+      mutation.operationJson,
+      mutation.localRevision,
+    );
+
+    const row = cachedStatement(database, 'SELECT * FROM mutation_journal WHERE journal_id = ?')
+      .get(Number(info.lastInsertRowid));
+    return { mutation: normalizeJournalRow(row), duplicate: false };
+  })();
+}
+
+function recordMaterializationError(database, channelId, mutationId, error) {
+  const message = error instanceof Error ? error.message : String(error);
+  cachedStatement(database, `
+    UPDATE mutation_journal
+    SET last_error = ?, updated_at = strftime('%Y-%m-%dT%H:%M:%fZ', 'now')
+    WHERE channel_id = ? AND mutation_id = ? AND mutation_state = 'saving-local'
+  `).run(message.slice(0, 4000), channelId, mutationId);
+}
+
+function advanceReplicaCursor(database, sharedResourceId) {
+  if (!sharedResourceId) return null;
+  const readReplica = cachedStatement(
+    database,
+    'SELECT * FROM shared_resource_replicas WHERE resource_id = ?',
+  );
+  const readNext = cachedStatement(database, `
+    SELECT official_cloud_version
+    FROM mutation_journal
+    WHERE shared_resource_id = ?
+      AND official_cloud_version = ?
+      AND mutation_state = 'synced'
+      AND materialized_at IS NOT NULL
+    LIMIT 1
+  `);
+  const update = cachedStatement(database, `
+    UPDATE shared_resource_replicas
+    SET applied_version = ?,
+        sync_status = 'synced',
+        last_error = NULL,
+        updated_at = ?
+    WHERE resource_id = ? AND applied_version = ?
+  `);
+
+  let replica = readReplica.get(sharedResourceId);
+  if (!replica) return null;
+  let appliedVersion = Number(replica.applied_version);
+  while (readNext.get(sharedResourceId, appliedVersion + 1)) {
+    const next = appliedVersion + 1;
+    const result = update.run(next, new Date().toISOString(), sharedResourceId, appliedVersion);
+    if (!result.changes) break;
+    appliedVersion = next;
+  }
+  replica = readReplica.get(sharedResourceId);
+  return replica ? Number(replica.applied_version) : null;
+}
+
+function completeMaterializedMutation(channelIdInput, mutationIdInput, eventInput, options = {}) {
+  const channelId = cleanText(channelIdInput, 'channelId');
+  const mutationId = cleanText(mutationIdInput, 'mutationId', 160);
+  const database = options.database || openLocalDb();
+  let event = null;
+
+  const result = database.transaction(() => {
+    const row = getMutationRow(database, channelId, mutationId);
+    if (!row) throw invalid(`unknown mutation ${mutationId}`, 404);
+    if (row.event_seq != null) {
+      return { mutation: normalizeJournalRow(row), duplicate: true };
+    }
+    if (row.mutation_state !== 'saving-local') {
+      throw invalid(`mutation ${mutationId} cannot materialize from ${row.mutation_state}`, 409);
+    }
+    if (!eventInput || eventInput.resource !== row.local_resource) {
+      throw invalid('materialized event resource must match the journal localResource');
+    }
+
+    event = insertStateEvent(database, {
+      ...eventInput,
+      mutationId: row.mutation_id,
+      sharedResourceId: row.shared_resource_id,
+    });
+    const now = new Date().toISOString();
+    const nextState = row.mutation_origin === 'cloud' ? 'synced' : 'saved-local';
+    cachedStatement(database, `
+      UPDATE mutation_journal
+      SET mutation_state = ?,
+          materialized_at = ?,
+          event_seq = ?,
+          last_error = NULL,
+          updated_at = ?
+      WHERE journal_id = ?
+    `).run(nextState, now, event.seq, now, row.journal_id);
+
+    if (row.mutation_origin === 'cloud') {
+      advanceReplicaCursor(database, row.shared_resource_id);
+    }
+
+    return {
+      mutation: normalizeJournalRow(
+        cachedStatement(database, 'SELECT * FROM mutation_journal WHERE journal_id = ?')
+          .get(row.journal_id),
+      ),
+      duplicate: false,
+    };
+  })();
+
+  if (event) publishStateEvent(event);
+  return { ...result, event };
+}
+
+function journalCloudMutation(input, options = {}) {
+  const envelope = input?.envelope || {};
+  const sharedResourceId = cleanText(envelope.resourceId, 'resourceId', 132);
+  const localResource = cleanText(input?.localResource, 'localResource');
+  const mutation = normalizeMutationInput({
+    channelId: `resource:${sharedResourceId}`,
+    localResource,
+    sharedResourceId,
+    mutationId: envelope.mutationId,
+    deviceId: envelope.deviceId,
+    authorityEpoch: envelope.authorityEpoch,
+    baseCloudVersion: envelope.baseVersion,
+    contract: envelope.contract,
+    schemaVersion: envelope.schemaVersion,
+    operationKind: envelope.operationKind,
+    operation: envelope.operation,
+  });
+  const version = positiveInteger(input?.version, 'version');
+  const committedAt = cleanText(input?.committedAt, 'committedAt', 64);
+  const database = options.database || openLocalDb();
+
+  return database.transaction(() => {
+    const replica = cachedStatement(
+      database,
+      'SELECT * FROM shared_resource_replicas WHERE resource_id = ?',
+    ).get(sharedResourceId);
+    if (!replica) throw invalid(`shared resource ${sharedResourceId} has no local replica`, 404);
+    // authority_epoch fences new writes. An already-official tail may contain
+    // older epochs and still must replay; only its contract/schema must match
+    // the local surface adapter.
+    if (
+      replica.contract !== mutation.contract
+      || Number(replica.schema_version) !== mutation.schemaVersion
+    ) {
+      throw invalid(`shared resource ${sharedResourceId} contract changed`, 409);
+    }
+
+    const existing = findSharedMutationRow(database, sharedResourceId, mutation.mutationId);
+    if (existing) {
+      if (!sameCloudEnvelope(existing, mutation)) {
+        throw invalid(`mutationId ${mutation.mutationId} was reused with different content`, 409);
+      }
+      if (
+        existing.official_cloud_version != null
+        && Number(existing.official_cloud_version) !== version
+      ) {
+        throw invalid(`mutationId ${mutation.mutationId} was reused with different content`, 409);
+      }
+
+      // The cloud tail is also the lost-ack recovery path for this runtime's
+      // own optimistic mutation. Reconcile the official version onto the
+      // existing row; never create or materialize a second local edit.
+      if (existing.mutation_origin === 'local' && existing.official_cloud_version == null) {
+        const now = new Date().toISOString();
+        cachedStatement(database, `
+          UPDATE mutation_journal
+          SET mutation_state = 'synced',
+              official_cloud_version = ?,
+              cloud_committed_at = ?,
+              next_attempt_at = NULL,
+              last_error = NULL,
+              updated_at = ?
+          WHERE journal_id = ?
+        `).run(version, committedAt, now, existing.journal_id);
+        advanceReplicaCursor(database, sharedResourceId);
+        const reconciled = cachedStatement(
+          database,
+          'SELECT * FROM mutation_journal WHERE journal_id = ?',
+        ).get(existing.journal_id);
+        return {
+          mutation: normalizeJournalRow(reconciled),
+          duplicate: true,
+          alreadyApplied: reconciled.event_seq != null,
+        };
+      }
+
+      return {
+        mutation: normalizeJournalRow(existing),
+        duplicate: true,
+        alreadyApplied: existing.event_seq != null,
+      };
+    }
+
+    const appliedVersion = Number(replica.applied_version);
+    if (version <= appliedVersion) {
+      return { mutation: null, duplicate: true, alreadyApplied: true };
+    }
+    if (version !== appliedVersion + 1) {
+      const error = invalid(
+        `shared mutation gap for ${sharedResourceId}: expected ${appliedVersion + 1}, received ${version}`,
+        409,
+      );
+      error.code = 'shared_mutation_gap';
+      error.expectedVersion = appliedVersion + 1;
+      error.receivedVersion = version;
+      throw error;
+    }
+
+    const now = new Date().toISOString();
+    const info = cachedStatement(database, `
+      INSERT INTO mutation_journal (
+        channel_id,
+        local_resource,
+        shared_resource_id,
+        mutation_id,
+        device_id,
+        authority_epoch,
+        base_cloud_version,
+        official_cloud_version,
+        contract,
+        schema_version,
+        operation_kind,
+        operation_json,
+        mutation_origin,
+        mutation_state,
+        cloud_committed_at,
+        created_at,
+        updated_at
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'cloud', 'saving-local', ?, ?, ?)
+    `).run(
+      mutation.channelId,
+      mutation.localResource,
+      mutation.sharedResourceId,
+      mutation.mutationId,
+      mutation.deviceId,
+      mutation.authorityEpoch,
+      mutation.baseCloudVersion,
+      version,
+      mutation.contract,
+      mutation.schemaVersion,
+      mutation.operationKind,
+      mutation.operationJson,
+      committedAt,
+      now,
+      now,
+    );
+    return {
+      mutation: normalizeJournalRow(
+        cachedStatement(database, 'SELECT * FROM mutation_journal WHERE journal_id = ?')
+          .get(Number(info.lastInsertRowid)),
+      ),
+      duplicate: false,
+      alreadyApplied: false,
+    };
+  })();
+}
+
+function ingestCloudMutation(input, options = {}) {
+  const database = options.database || openLocalDb();
+  const started = journalCloudMutation(input, { database });
+  if (started.alreadyApplied) return { ...started, event: null };
+
+  try {
+    if (typeof options.materialize === 'function') options.materialize(started.mutation);
+  } catch (error) {
+    recordMaterializationError(
+      database,
+      started.mutation.channelId,
+      started.mutation.mutationId,
+      error,
+    );
+    throw error;
+  }
+  const eventInput = typeof options.event === 'function'
+    ? options.event(started.mutation)
+    : options.event;
+  const completed = completeMaterializedMutation(
+    started.mutation.channelId,
+    started.mutation.mutationId,
+    eventInput,
+    { database },
+  );
+  return { ...completed, duplicate: started.duplicate || completed.duplicate };
+}
+
+function commitLocalMutation(input, options = {}) {
+  const database = options.database || openLocalDb();
+  const started = journalMutation(input, { database, persist: options.persist });
+  if (started.duplicate && started.mutation.state !== 'saving-local') {
+    return { ...started, event: null };
+  }
+
+  try {
+    if (typeof options.materialize === 'function') {
+      options.materialize(started.mutation);
+    }
+  } catch (error) {
+    recordMaterializationError(
+      database,
+      started.mutation.channelId,
+      started.mutation.mutationId,
+      error,
+    );
+    throw error;
+  }
+
+  const eventInput = typeof options.event === 'function'
+    ? options.event(started.mutation)
+    : options.event;
+  const completed = completeMaterializedMutation(
+    started.mutation.channelId,
+    started.mutation.mutationId,
+    eventInput,
+    { database },
+  );
+  return {
+    ...completed,
+    duplicate: started.duplicate || completed.duplicate,
+  };
+}
+
+function getMutation(channelId, mutationId, options = {}) {
+  const database = options.database || openLocalDb();
+  return normalizeJournalRow(getMutationRow(database, channelId, mutationId));
+}
+
+function cloudEnvelope(mutation) {
+  if (!mutation.sharedResourceId || !mutation.deviceId) {
+    throw invalid(`mutation ${mutation.mutationId} is not cloud-deliverable`, 409);
+  }
+  return {
+    resourceId: mutation.sharedResourceId,
+    authorityEpoch: mutation.authorityEpoch,
+    mutationId: mutation.mutationId,
+    deviceId: mutation.deviceId,
+    baseVersion: mutation.baseCloudVersion,
+    contract: mutation.contract,
+    schemaVersion: mutation.schemaVersion,
+    operationKind: mutation.operationKind,
+    operation: mutation.operation,
+  };
+}
+
+function claimCloudMutations(options = {}) {
+  const database = options.database || openLocalDb();
+  const limit = Math.max(1, Math.min(Number(options.limit) || DEFAULT_CLAIM_LIMIT, 500));
+  const leaseMs = Math.max(1000, Number(options.leaseMs) || DEFAULT_CLAIM_LEASE_MS);
+  const now = typeof options.now === 'string' ? options.now : new Date().toISOString();
+  const leaseUntil = typeof options.leaseUntil === 'string'
+    ? options.leaseUntil
+    : new Date(new Date(now).getTime() + leaseMs).toISOString();
+
+  return database.transaction(() => {
+    const rows = cachedStatement(database, `
+      SELECT *
+      FROM mutation_journal
+      WHERE shared_resource_id IS NOT NULL
+        AND mutation_origin = 'local'
+        AND materialized_at IS NOT NULL
+        AND (
+          mutation_state = 'saved-local'
+          OR (
+            mutation_state = 'syncing'
+            AND (next_attempt_at IS NULL OR next_attempt_at <= ?)
+          )
+        )
+      ORDER BY journal_id ASC
+      LIMIT ?
+    `).all(now, limit);
+
+    const claim = cachedStatement(database, `
+      UPDATE mutation_journal
+      SET mutation_state = 'syncing',
+          attempt_count = attempt_count + 1,
+          next_attempt_at = ?,
+          updated_at = ?
+      WHERE journal_id = ?
+    `);
+    const read = cachedStatement(database, 'SELECT * FROM mutation_journal WHERE journal_id = ?');
+
+    return rows.map((row) => {
+      claim.run(leaseUntil, now, row.journal_id);
+      const mutation = normalizeJournalRow(read.get(row.journal_id));
+      return { mutation, envelope: cloudEnvelope(mutation) };
+    });
+  })();
+}
+
+function findSharedMutationRow(database, sharedResourceId, mutationId) {
+  return cachedStatement(database, `
+    SELECT * FROM mutation_journal
+    WHERE shared_resource_id = ? AND mutation_id = ?
+  `).get(sharedResourceId, mutationId) || null;
+}
+
+function acknowledgeCloudMutation(sharedResourceIdInput, mutationIdInput, acknowledgement, options = {}) {
+  const sharedResourceId = cleanText(sharedResourceIdInput, 'sharedResourceId', 132);
+  const mutationId = cleanText(mutationIdInput, 'mutationId', 160);
+  const version = positiveInteger(acknowledgement?.version, 'version');
+  const committedAt = cleanText(
+    acknowledgement?.committedAt || new Date().toISOString(),
+    'committedAt',
+    64,
+  );
+  const database = options.database || openLocalDb();
+
+  return database.transaction(() => {
+    const row = findSharedMutationRow(database, sharedResourceId, mutationId);
+    if (!row) throw invalid(`unknown shared mutation ${mutationId}`, 404);
+    if (row.mutation_state === 'synced') {
+      if (Number(row.official_cloud_version) !== version) {
+        throw invalid(`mutation ${mutationId} was acknowledged with a different version`, 409);
+      }
+      return { mutation: normalizeJournalRow(row), duplicate: true };
+    }
+    if (!['saved-local', 'syncing'].includes(row.mutation_state)) {
+      throw invalid(`mutation ${mutationId} cannot sync from ${row.mutation_state}`, 409);
+    }
+
+    const now = new Date().toISOString();
+    cachedStatement(database, `
+      UPDATE mutation_journal
+      SET mutation_state = 'synced',
+          official_cloud_version = ?,
+          cloud_committed_at = ?,
+          next_attempt_at = NULL,
+          last_error = NULL,
+          updated_at = ?
+      WHERE journal_id = ?
+    `).run(version, committedAt, now, row.journal_id);
+    advanceReplicaCursor(database, sharedResourceId);
+    return {
+      mutation: normalizeJournalRow(
+        cachedStatement(database, 'SELECT * FROM mutation_journal WHERE journal_id = ?')
+          .get(row.journal_id),
+      ),
+      duplicate: false,
+    };
+  })();
+}
+
+function failCloudMutation(sharedResourceIdInput, mutationIdInput, failure, options = {}) {
+  const sharedResourceId = cleanText(sharedResourceIdInput, 'sharedResourceId', 132);
+  const mutationId = cleanText(mutationIdInput, 'mutationId', 160);
+  const message = cleanText(failure?.message || failure || 'cloud mutation failed', 'message', 4000);
+  const retryable = failure?.retryable !== false;
+  const retryAt = retryable
+    ? (failure?.retryAt || new Date(Date.now() + 1000).toISOString())
+    : null;
+  const database = options.database || openLocalDb();
+  const row = findSharedMutationRow(database, sharedResourceId, mutationId);
+  if (!row) throw invalid(`unknown shared mutation ${mutationId}`, 404);
+  if (row.mutation_state === 'synced') return normalizeJournalRow(row);
+
+  const now = new Date().toISOString();
+  cachedStatement(database, `
+    UPDATE mutation_journal
+    SET mutation_state = ?,
+        next_attempt_at = ?,
+        last_error = ?,
+        updated_at = ?
+    WHERE journal_id = ?
+  `).run(retryable ? 'syncing' : 'rejected', retryAt, message, now, row.journal_id);
+  return normalizeJournalRow(
+    cachedStatement(database, 'SELECT * FROM mutation_journal WHERE journal_id = ?')
+      .get(row.journal_id),
+  );
+}
+
+function markMutationConflicted(sharedResourceIdInput, mutationIdInput, messageInput, options = {}) {
+  const sharedResourceId = cleanText(sharedResourceIdInput, 'sharedResourceId', 132);
+  const mutationId = cleanText(mutationIdInput, 'mutationId', 160);
+  const message = cleanText(messageInput || 'mutation requires conflict resolution', 'message', 4000);
+  const database = options.database || openLocalDb();
+  const now = new Date().toISOString();
+  const result = cachedStatement(database, `
+    UPDATE mutation_journal
+    SET mutation_state = 'conflicted',
+        next_attempt_at = NULL,
+        last_error = ?,
+        updated_at = ?
+    WHERE shared_resource_id = ? AND mutation_id = ? AND mutation_state != 'synced'
+  `).run(message, now, sharedResourceId, mutationId);
+  if (!result.changes) throw invalid(`unknown or synced shared mutation ${mutationId}`, 404);
+  return normalizeJournalRow(findSharedMutationRow(database, sharedResourceId, mutationId));
+}
+
+function listMutations(options = {}) {
+  const database = options.database || openLocalDb();
+  const limit = Math.max(1, Math.min(Number(options.limit) || 100, 1000));
+  const rows = options.state
+    ? cachedStatement(database, `
+        SELECT * FROM mutation_journal
+        WHERE mutation_state = ?
+        ORDER BY journal_id ASC
+        LIMIT ?
+      `).all(options.state, limit)
+    : cachedStatement(database, `
+        SELECT * FROM mutation_journal
+        ORDER BY journal_id ASC
+        LIMIT ?
+      `).all(limit);
+  return rows.map(normalizeJournalRow);
+}
+
+function pruneMutationJournal(options = {}) {
+  const database = options.database || openLocalDb();
+  const hours = Number(options.retentionHours ?? process.env.AMALGM_EVENT_LOG_RETENTION_HOURS ?? 0.25);
+  if (!Number.isFinite(hours) || hours <= 0) {
+    return { deleted: 0, skipped: true, reason: 'disabled' };
+  }
+  const cutoffIso = options.cutoffIso
+    || new Date(Date.now() - hours * 60 * 60 * 1000).toISOString();
+  const batchSize = Math.max(1, Math.floor(Number(options.batchSize) || 1000));
+  const result = cachedStatement(database, `
+    DELETE FROM mutation_journal
+    WHERE journal_id IN (
+      SELECT journal_id
+      FROM mutation_journal
+      WHERE updated_at < ?
+        AND event_seq IS NOT NULL
+        AND (
+          (shared_resource_id IS NULL AND mutation_state = 'saved-local')
+          OR mutation_state = 'synced'
+        )
+      ORDER BY journal_id ASC
+      LIMIT ?
+    )
+  `).run(cutoffIso, batchSize);
+  return {
+    deleted: result.changes || 0,
+    cutoffIso,
+    retentionHours: hours,
+    batchSize,
+  };
+}
+
+module.exports = {
+  MAX_MUTATION_BYTES,
+  acknowledgeCloudMutation,
+  claimCloudMutations,
+  commitLocalMutation,
+  completeMaterializedMutation,
+  failCloudMutation,
+  getMutation,
+  ingestCloudMutation,
+  journalCloudMutation,
+  journalMutation,
+  listMutations,
+  markMutationConflicted,
+  pruneMutationJournal,
+};