amalgm 0.1.238 → 0.1.240

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

@@ -16,6 +16,8 @@ const { cachedStatement, openLocalDb } = require('./db');
 const { insertStateEvent, publishStateEvent } = require('./events');
 const {
   diagnosticOperation,
+  mutationNeedsOfficialMaterialization,
+  mutationNeedsOrderedEcho,
   protectOperation,
   revealOperation,
 } = require('./mutation-contracts');
@@ -174,10 +176,12 @@ function normalizeJournalRow(row, options = {}) {
     state: row.mutation_state,
     localRevision: row.local_revision == null ? null : Number(row.local_revision),
     materializedAt: row.materialized_at || null,
+    officialProjectedAt: row.official_projected_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,
+    failureCode: row.failure_code || null,
     cloudCommittedAt: row.cloud_committed_at || null,
     createdAt: row.created_at,
     updatedAt: row.updated_at,
@@ -224,66 +228,67 @@ function sameCloudEnvelope(existing, mutation) {
     && JSON.stringify(existingOperation) === 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 };
+function journalNormalizedMutation(database, mutation, persist = null) {
+  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);
+  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,
+    JSON.stringify(protectOperation(mutation.contract, mutation.operation)),
+    mutation.localRevision,
+  );
 
-    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,
-      JSON.stringify(protectOperation(mutation.contract, mutation.operation)),
-      mutation.localRevision,
-    );
+  const row = cachedStatement(database, 'SELECT * FROM mutation_journal WHERE journal_id = ?')
+    .get(Number(info.lastInsertRowid));
+  trace('journal', {
+    mutationId: mutation.mutationId,
+    channel: mutation.channelId,
+    shared: mutation.sharedResourceId,
+  });
+  return { mutation: normalizeJournalRow(row), duplicate: false };
+}
 
-    const row = cachedStatement(database, 'SELECT * FROM mutation_journal WHERE journal_id = ?')
-      .get(Number(info.lastInsertRowid));
-    trace('journal', {
-      mutationId: mutation.mutationId,
-      channel: mutation.channelId,
-      shared: mutation.sharedResourceId,
-    });
-    return { mutation: normalizeJournalRow(row), duplicate: false };
-  })();
+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(() => journalNormalizedMutation(database, mutation, persist))();
 }
 
 function recordMaterializationError(database, channelId, mutationId, error) {
@@ -307,7 +312,7 @@ function advanceReplicaCursor(database, sharedResourceId) {
     WHERE shared_resource_id = ?
       AND official_cloud_version = ?
       AND mutation_state = 'synced'
-      AND materialized_at IS NOT NULL
+      AND official_projected_at IS NOT NULL
     LIMIT 1
   `);
   const update = cachedStatement(database, `
@@ -332,61 +337,168 @@ function advanceReplicaCursor(database, sharedResourceId) {
   return replica ? Number(replica.applied_version) : null;
 }
 
+function completeMaterializedInTransaction(database, channelId, mutationId, eventInput) {
+  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, event: null };
+  }
+  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');
+  }
+
+  const 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';
+  const officialProjectedAt = row.mutation_origin === 'cloud' ? now : null;
+  cachedStatement(database, `
+    UPDATE mutation_journal
+    SET mutation_state = ?,
+        materialized_at = ?,
+        official_projected_at = ?,
+        event_seq = ?,
+        last_error = NULL,
+        failure_code = NULL,
+        updated_at = ?
+    WHERE journal_id = ?
+  `).run(nextState, now, officialProjectedAt, event.seq, now, row.journal_id);
+
+  if (row.mutation_origin === 'cloud') {
+    advanceReplicaCursor(database, row.shared_resource_id);
+  }
+
+  trace('materialized', {
+    mutationId: row.mutation_id,
+    origin: row.mutation_origin,
+    state: nextState,
+    eventSeq: event.seq,
+  });
+  return {
+    mutation: normalizeJournalRow(
+      cachedStatement(database, 'SELECT * FROM mutation_journal WHERE journal_id = ?')
+        .get(row.journal_id),
+    ),
+    duplicate: false,
+    event,
+  };
+}
+
 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 completed = completeMaterializedInTransaction(
+      database,
+      channelId,
+      mutationId,
+      eventInput,
+    );
+    if (typeof options.finalize === 'function') {
+      options.finalize(database, completed);
+    }
+    return completed;
+  })();
+  if (result.event) publishStateEvent(result.event);
+  return result;
+}
 
+/**
+ * A code-project outbox event is not the official materialization. When that
+ * same mutation returns in the numbered cloud tail, project it once more,
+ * then move the replica cursor. Repeating this after a crash is safe because
+ * the contract materializer folds by official snapshot version.
+ */
+function completeOfficialMaterialization(
+  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 finalize = (completed) => {
+      if (typeof options.finalize === 'function') {
+        options.finalize(database, completed);
+      }
+      return completed;
+    };
     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_origin !== 'local'
+      || row.mutation_state !== 'synced'
+      || row.official_cloud_version == null
+    ) throw invalid(`mutation ${mutationId} has no official projection`, 409);
+    const replica = cachedStatement(
+      database,
+      'SELECT applied_version FROM shared_resource_replicas WHERE resource_id = ?',
+    ).get(row.shared_resource_id);
+    const appliedVersion = Number(replica?.applied_version);
+    const officialVersion = Number(row.official_cloud_version);
+    if (row.official_projected_at != null || appliedVersion >= officialVersion) {
+      if (row.official_projected_at == null) {
+        const now = new Date().toISOString();
+        cachedStatement(database, `
+          UPDATE mutation_journal
+          SET official_projected_at = ?,
+              updated_at = ?
+          WHERE journal_id = ?
+        `).run(now, now, row.journal_id);
+      }
+      advanceReplicaCursor(database, row.shared_resource_id);
+      return finalize({
+        mutation: normalizeJournalRow(
+          cachedStatement(database, 'SELECT * FROM mutation_journal WHERE journal_id = ?')
+            .get(row.journal_id),
+        ),
+        duplicate: true,
+      });
     }
-    if (row.mutation_state !== 'saving-local') {
-      throw invalid(`mutation ${mutationId} cannot materialize from ${row.mutation_state}`, 409);
+    if (officialVersion !== appliedVersion + 1) {
+      const error = invalid(
+        `shared mutation gap for ${row.shared_resource_id}: expected ${appliedVersion + 1}, received ${officialVersion}`,
+        409,
+      );
+      error.code = 'shared_mutation_gap';
+      error.expectedVersion = appliedVersion + 1;
+      error.receivedVersion = officialVersion;
+      throw error;
     }
     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,
+      SET official_projected_at = ?,
           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);
-    }
-
-    trace('materialized', {
-      mutationId: row.mutation_id,
-      origin: row.mutation_origin,
-      state: nextState,
-      eventSeq: event.seq,
-    });
-    return {
+    `).run(now, now, row.journal_id);
+    advanceReplicaCursor(database, row.shared_resource_id);
+    return finalize({
       mutation: normalizeJournalRow(
         cachedStatement(database, 'SELECT * FROM mutation_journal WHERE journal_id = ?')
           .get(row.journal_id),
       ),
       duplicate: false,
-    };
+    });
   })();
-
   if (event) publishStateEvent(event);
   return { ...result, event };
 }
@@ -411,6 +523,7 @@ function journalCloudMutation(input, options = {}) {
   const version = positiveInteger(input?.version, 'version');
   const committedAt = cleanText(input?.committedAt, 'committedAt', 64);
   const database = options.database || openLocalDb();
+  const persist = typeof options.persist === 'function' ? options.persist : null;
 
   return database.transaction(() => {
     const replica = cachedStatement(
@@ -440,22 +553,60 @@ function journalCloudMutation(input, options = {}) {
         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);
+      if (existing.mutation_origin === 'local') {
+        const appliedVersion = Number(replica.applied_version);
+        if (version > appliedVersion && 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;
+        }
+        if (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,
+                failure_code = NULL,
+                updated_at = ?
+            WHERE journal_id = ?
+          `).run(version, committedAt, now, existing.journal_id);
+        }
+        if (!mutationNeedsOrderedEcho(existing.contract)) {
+          const now = new Date().toISOString();
+          cachedStatement(database, `
+            UPDATE mutation_journal
+            SET official_projected_at = COALESCE(official_projected_at, ?),
+                updated_at = ?
+            WHERE journal_id = ?
+          `).run(now, 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: true,
+          };
+        }
+        if (appliedVersion >= version && existing.official_projected_at == null) {
+          const now = new Date().toISOString();
+          cachedStatement(database, `
+            UPDATE mutation_journal
+            SET official_projected_at = ?,
+                updated_at = ?
+            WHERE journal_id = ?
+          `).run(now, now, existing.journal_id);
+        }
         const reconciled = cachedStatement(
           database,
           'SELECT * FROM mutation_journal WHERE journal_id = ?',
@@ -463,14 +614,15 @@ function journalCloudMutation(input, options = {}) {
         return {
           mutation: normalizeJournalRow(reconciled),
           duplicate: true,
-          alreadyApplied: reconciled.event_seq != null,
+          alreadyApplied: appliedVersion >= version,
+          officialMaterialization: appliedVersion < version,
         };
       }
 
       return {
         mutation: normalizeJournalRow(existing),
         duplicate: true,
-        alreadyApplied: existing.event_seq != null,
+        alreadyApplied: existing.official_projected_at != null,
       };
     }
 
@@ -490,6 +642,7 @@ function journalCloudMutation(input, options = {}) {
     }
 
     const now = new Date().toISOString();
+    if (persist) persist(database, mutation);
     const info = cachedStatement(database, `
       INSERT INTO mutation_journal (
         channel_id,
@@ -541,7 +694,10 @@ function journalCloudMutation(input, options = {}) {
 
 function ingestCloudMutation(input, options = {}) {
   const database = options.database || openLocalDb();
-  const started = journalCloudMutation(input, { database });
+  const started = journalCloudMutation(input, {
+    database,
+    persist: options.persist,
+  });
   if (started.alreadyApplied) return { ...started, event: null };
 
   try {
@@ -558,17 +714,56 @@ function ingestCloudMutation(input, options = {}) {
   const eventInput = typeof options.event === 'function'
     ? options.event(started.mutation)
     : options.event;
-  const completed = completeMaterializedMutation(
-    started.mutation.channelId,
-    started.mutation.mutationId,
-    eventInput,
-    { database },
-  );
+  const completed = started.officialMaterialization
+    ? completeOfficialMaterialization(
+      started.mutation.channelId,
+      started.mutation.mutationId,
+      eventInput,
+      { database, finalize: options.finalize },
+    )
+    : completeMaterializedMutation(
+      started.mutation.channelId,
+      started.mutation.mutationId,
+      eventInput,
+      { database, finalize: options.finalize },
+    );
   return { ...completed, duplicate: started.duplicate || completed.duplicate };
 }
 
 function commitLocalMutation(input, options = {}) {
   const database = options.database || openLocalDb();
+  if (mutationNeedsOfficialMaterialization(input?.contract)) {
+    if (typeof options.materialize === 'function') {
+      throw invalid('code publication cannot materialize official state before cloud order', 409);
+    }
+    const mutation = normalizeMutationInput(input);
+    const persist = typeof options.persist === 'function' ? options.persist : null;
+    const result = database.transaction(() => {
+      const started = journalNormalizedMutation(database, mutation, persist);
+      if (started.duplicate && started.mutation.state !== 'saving-local') {
+        return { ...started, event: null };
+      }
+      const eventInput = typeof options.event === 'function'
+        ? options.event(started.mutation)
+        : options.event;
+      const completed = completeMaterializedInTransaction(
+        database,
+        started.mutation.channelId,
+        started.mutation.mutationId,
+        eventInput,
+      );
+      if (typeof options.finalize === 'function') {
+        options.finalize(database, completed);
+      }
+      return {
+        ...completed,
+        duplicate: started.duplicate || completed.duplicate,
+      };
+    })();
+    if (result.event) publishStateEvent(result.event);
+    return result;
+  }
+
   const started = journalMutation(input, { database, persist: options.persist });
   if (started.duplicate && started.mutation.state !== 'saving-local') {
     return { ...started, event: null };
@@ -595,7 +790,7 @@ function commitLocalMutation(input, options = {}) {
     started.mutation.channelId,
     started.mutation.mutationId,
     eventInput,
-    { database },
+    { database, finalize: options.finalize },
   );
   return {
     ...completed,
@@ -723,10 +918,10 @@ function acknowledgeCloudMutation(sharedResourceIdInput, mutationIdInput, acknow
           cloud_committed_at = ?,
           next_attempt_at = NULL,
           last_error = NULL,
+          failure_code = NULL,
           updated_at = ?
       WHERE journal_id = ?
     `).run(version, committedAt, now, row.journal_id);
-    advanceReplicaCursor(database, sharedResourceId);
     event = insertStateEvent(database, {
       resource: 'shared-mutations',
       op: 'ack',
@@ -746,6 +941,17 @@ function acknowledgeCloudMutation(sharedResourceIdInput, mutationIdInput, acknow
     };
   })();
   if (event) publishStateEvent(event);
+  if (result.mutation?.contract === require('./mutation-contracts').CODE_PROJECT_CONTRACT) {
+    const project = require('../workspace/wall').projectForResource(sharedResourceId);
+    if (project) {
+      require('../workspace/intent').markPublicationNumbered(
+        project,
+        mutationId,
+        version,
+        committedAt,
+      );
+    }
+  }
   return { ...result, event };
 }
 
@@ -754,6 +960,10 @@ function failCloudMutation(sharedResourceIdInput, mutationIdInput, failure, opti
   const mutationId = cleanText(mutationIdInput, 'mutationId', 160);
   const message = cleanText(failure?.message || failure || 'cloud mutation failed', 'message', 4000);
   const retryable = failure?.retryable !== false;
+  const failureCode = typeof failure?.code === 'string'
+    && /^[a-z][a-z0-9_:-]{0,127}$/.test(failure.code)
+    ? failure.code
+    : null;
   const retryAt = retryable
     ? (failure?.retryAt || new Date(Date.now() + 1000).toISOString())
     : null;
@@ -768,9 +978,17 @@ function failCloudMutation(sharedResourceIdInput, mutationIdInput, failure, opti
     SET mutation_state = ?,
         next_attempt_at = ?,
         last_error = ?,
+        failure_code = ?,
         updated_at = ?
     WHERE journal_id = ?
-  `).run(retryable ? 'syncing' : 'rejected', retryAt, message, now, row.journal_id);
+  `).run(
+    retryable ? 'syncing' : 'rejected',
+    retryAt,
+    message,
+    failureCode,
+    now,
+    row.journal_id,
+  );
   trace('cloud-fail', { mutationId, shared: sharedResourceId, retryable, message });
   return normalizeJournalRow(
     cachedStatement(database, 'SELECT * FROM mutation_journal WHERE journal_id = ?')
@@ -799,18 +1017,38 @@ function markMutationConflicted(sharedResourceIdInput, mutationIdInput, messageI
 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, `
+  const localResource = options.localResource == null
+    ? null
+    : cleanText(options.localResource, 'localResource', 8192);
+  let rows;
+  if (options.state && localResource) {
+    rows = cachedStatement(database, `
+        SELECT * FROM mutation_journal
+        WHERE mutation_state = ? AND local_resource = ?
+        ORDER BY journal_id ASC
+        LIMIT ?
+      `).all(options.state, localResource, limit);
+  } else if (options.state) {
+    rows = cachedStatement(database, `
         SELECT * FROM mutation_journal
         WHERE mutation_state = ?
         ORDER BY journal_id ASC
         LIMIT ?
-      `).all(options.state, limit)
-    : cachedStatement(database, `
+      `).all(options.state, limit);
+  } else if (localResource) {
+    rows = cachedStatement(database, `
+        SELECT * FROM mutation_journal
+        WHERE local_resource = ?
+        ORDER BY journal_id ASC
+        LIMIT ?
+      `).all(localResource, limit);
+  } else {
+    rows = cachedStatement(database, `
         SELECT * FROM mutation_journal
         ORDER BY journal_id ASC
         LIMIT ?
       `).all(limit);
+  }
   return rows.map((row) => normalizeJournalRow(row, { diagnostic: true }));
 }
 
@@ -834,6 +1072,120 @@ function listPendingCloudMutations(resourceIdInput, options = {}) {
   `).all(resourceId).map((row) => normalizeJournalRow(row));
 }
 
+/**
+ * Local overlay rows are every unnumbered mutation plus numbered local work
+ * whose official event has not yet folded into the materialized resource.
+ * Snapshot projection must retain the complete set, so this view is
+ * deliberately unpaged.
+ */
+function listLocalOverlayMutations(resourceIdInput, options = {}) {
+  const resourceId = cleanText(resourceIdInput, 'resourceId', 132);
+  if (!isCloudResourceId(resourceId)) {
+    throw invalid('resourceId must be an opaque cloud resource id');
+  }
+  const database = options.database || openLocalDb();
+  const throughVersion = options.throughVersion == null
+    ? null
+    : nonNegativeInteger(options.throughVersion, 'throughVersion');
+  if (throughVersion !== null) {
+    return cachedStatement(database, `
+      SELECT * FROM mutation_journal
+      WHERE shared_resource_id = ?
+        AND mutation_origin = 'local'
+        AND (
+          mutation_state != 'synced'
+          OR official_cloud_version IS NULL
+          OR official_cloud_version > ?
+        )
+      ORDER BY journal_id ASC
+    `).all(resourceId, throughVersion).map((row) => normalizeJournalRow(row));
+  }
+  return cachedStatement(database, `
+    SELECT * FROM mutation_journal
+    WHERE shared_resource_id = ?
+      AND mutation_origin = 'local'
+      AND (mutation_state != 'synced' OR official_projected_at IS NULL)
+    ORDER BY journal_id ASC
+  `).all(resourceId).map((row) => normalizeJournalRow(row));
+}
+
+function listUnappliedOfficialMutations(resourceIdInput, options = {}) {
+  const resourceId = cleanText(resourceIdInput, 'resourceId', 132);
+  if (!isCloudResourceId(resourceId)) {
+    throw invalid('resourceId must be an opaque cloud resource id');
+  }
+  const database = options.database || openLocalDb();
+  const replica = cachedStatement(
+    database,
+    'SELECT applied_version FROM shared_resource_replicas WHERE resource_id = ?',
+  ).get(resourceId);
+  const appliedVersion = Number(replica?.applied_version ?? -1);
+  return cachedStatement(database, `
+    SELECT *
+    FROM mutation_journal
+    WHERE shared_resource_id = ?
+      AND mutation_origin = 'local'
+      AND mutation_state = 'synced'
+      AND official_cloud_version > ?
+    ORDER BY official_cloud_version ASC
+  `).all(resourceId, appliedVersion)
+    .filter((row) => mutationNeedsOfficialMaterialization(row.contract))
+    .map((row) => normalizeJournalRow(row));
+}
+
+/**
+ * A verified code snapshot through N is the ordinary ordered fold for every
+ * already-numbered local publication at or before N. This repairs the same
+ * durable fact on an equal snapshot retry after a crash.
+ */
+function completeOfficialSnapshotFold(resourceIdInput, throughInput, options = {}) {
+  const resourceId = cleanText(resourceIdInput, 'resourceId', 132);
+  const through = nonNegativeInteger(throughInput, 'through');
+  const database = options.database || openLocalDb();
+  const contract = cleanText(
+    options.contract || require('./mutation-contracts').CODE_PROJECT_CONTRACT,
+    'contract',
+    128,
+  );
+  const now = new Date().toISOString();
+  return cachedStatement(database, `
+    UPDATE mutation_journal
+    SET official_projected_at = COALESCE(official_projected_at, ?),
+        updated_at = ?
+    WHERE shared_resource_id = ?
+      AND contract = ?
+      AND mutation_origin = 'local'
+      AND mutation_state = 'synced'
+      AND official_cloud_version <= ?
+  `).run(
+    now,
+    now,
+    resourceId,
+    contract,
+    through,
+  ).changes;
+}
+
+/**
+ * A stale proposal was never an official event. Keep it as a publication
+ * barrier until this replica has actually advanced past the base it used,
+ * then retire it so the unchanged local intent can be proposed anew.
+ */
+function retireStaleCodeMutations(resourceIdInput, appliedVersionInput, options = {}) {
+  const resourceId = cleanText(resourceIdInput, 'resourceId', 132);
+  const appliedVersion = nonNegativeInteger(appliedVersionInput, 'appliedVersion');
+  const database = options.database || openLocalDb();
+  return cachedStatement(database, `
+    DELETE FROM mutation_journal
+    WHERE shared_resource_id = ?
+      AND mutation_origin = 'local'
+      AND contract = ?
+      AND mutation_state = 'rejected'
+      AND failure_code = 'code_project_stale_base'
+      AND base_cloud_version < ?
+  `).run(resourceId, require('./mutation-contracts').CODE_PROJECT_CONTRACT, appliedVersion).changes;
+}
+
 function pruneMutationJournal(options = {}) {
   const database = options.database || openLocalDb();
   const hours = Number(options.retentionHours ?? process.env.AMALGM_EVENT_LOG_RETENTION_HOURS ?? 0.25);
@@ -843,23 +1195,44 @@ function pruneMutationJournal(options = {}) {
   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'
+  const readPage = cachedStatement(database, `
+    SELECT *
+    FROM mutation_journal
+    WHERE journal_id > ?
+      AND updated_at < ?
+      AND event_seq IS NOT NULL
+      AND (
+        (shared_resource_id IS NULL AND mutation_state = 'saved-local')
+        OR (
+          shared_resource_id IS NOT NULL
+          AND mutation_state = 'synced'
+          AND official_projected_at IS NOT NULL
         )
-      ORDER BY journal_id ASC
-      LIMIT ?
-    )
-  `).run(cutoffIso, batchSize);
+      )
+    ORDER BY journal_id ASC
+    LIMIT ?
+  `);
+  const { mutationMayPrune } = require('./mutation-contracts');
+  const snapshotCache = new Map();
+  const deletable = [];
+  let afterJournalId = 0;
+  while (deletable.length < batchSize) {
+    const page = readPage.all(afterJournalId, cutoffIso, batchSize);
+    if (page.length === 0) break;
+    for (const row of page) {
+      afterJournalId = Number(row.journal_id);
+      if (mutationMayPrune(row, { database, snapshotCache })) {
+        deletable.push(row.journal_id);
+        if (deletable.length === batchSize) break;
+      }
+    }
+  }
+  const remove = cachedStatement(database, 'DELETE FROM mutation_journal WHERE journal_id = ?');
+  const deleted = database.transaction((journalIds) => (
+    journalIds.reduce((count, journalId) => count + remove.run(journalId).changes, 0)
+  ))(deletable);
   return {
-    deleted: result.changes || 0,
+    deleted,
     cutoffIso,
     retentionHours: hours,
     batchSize,
@@ -872,13 +1245,17 @@ module.exports = {
   claimCloudMutations,
   commitLocalMutation,
   completeMaterializedMutation,
+  completeOfficialSnapshotFold,
   failCloudMutation,
   getMutation,
   ingestCloudMutation,
   journalCloudMutation,
   journalMutation,
+  listLocalOverlayMutations,
+  listUnappliedOfficialMutations,
   listPendingCloudMutations,
   listMutations,
   markMutationConflicted,
   pruneMutationJournal,
+  retireStaleCodeMutations,
 };