amalgm 0.1.239 → 0.1.241

package/runtime/scripts/amalgm-mcp/workspace/project-stream.js

@@ -1,84 +1,528 @@
 'use strict';
 
+/**
+ * The one authoritative stream for a code project.
+ *
+ * Clients publish deltas. Only an officially numbered cloud mutation changes
+ * this snapshot. A local outbox row is intent, never authority.
+ */
+
 const crypto = require('crypto');
 const fs = require('fs');
 const { appendStateEvent } = require('../state/events');
 const { openLocalDb } = require('../state/db');
+const durable = require('./durable');
 
-const STREAM_CONTRACT = 'code-project-stream@1';
-const WALL_CONTRACT = 'code-project@6';
+const STREAM_CONTRACT = 'code-project-stream@2';
+const WALL_CONTRACT = 'code-project@7';
+const CARD_CONTRACT = 'repo-card@3';
+const CHECKPOINT_CONTRACT = 'repo-checkpoint@11';
+const BUNDLE_CONTRACT = 'git-bundle-chunks@2';
+const PAYLOAD_CONTRACT = 'opaque-chunks@2';
 const LOCAL_RESOURCE_PREFIX = 'code-project:';
+const SHA = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/;
+const SHA256 = /^[0-9a-f]{64}$/;
+const MUTATION_ID = /^[A-Za-z0-9_-]{16,160}$/;
+const MAX_CHUNKS = 4096;
+const MAX_CHUNK_BYTES = 512 * 1024;
+const MAX_BRANCHES = 4096;
 
-function invalid(message, statusCode = 400) {
-  return Object.assign(new Error(message), { statusCode });
+function invalid(message, statusCode = 400, code = null) {
+  const error = Object.assign(new Error(message), { statusCode });
+  if (code) error.code = code;
+  return error;
 }
 
-function emptySnapshot(project) {
-  return { schemaVersion: 1, project, version: 0, records: [] };
+function exactObject(input, keys, label) {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) {
+    throw invalid(`${label} is invalid`, 409);
+  }
+  const actual = Object.keys(input).sort();
+  const expected = [...keys].sort();
+  if (
+    actual.length !== expected.length
+    || actual.some((key, index) => key !== expected[index])
+  ) throw invalid(`${label} has unexpected fields`, 409);
+  return input;
 }
 
-function localResource(resourceId) {
-  return `${LOCAL_RESOURCE_PREFIX}${resourceId}`;
+function nonEmptyString(value, label) {
+  if (typeof value !== 'string' || !value) throw invalid(`${label} is invalid`, 409);
+  return value;
 }
 
-function normalizeRecord(input, project, official = false) {
+function branchName(value) {
+  const components = typeof value === 'string' ? value.split('/') : [];
   if (
-    !input
-    || input.wall !== WALL_CONTRACT
-    || input.project !== project
-    || typeof input.machine !== 'string'
-    || !input.machine
-    || typeof input.mutationId !== 'string'
-    || !input.mutationId
-    || typeof input.publishedAt !== 'string'
-    || !Number.isFinite(Date.parse(input.publishedAt))
-    || !Array.isArray(input.cards)
-  ) throw invalid('code project record is invalid', 409);
-  const version = Number(input.version);
-  if (official && (!Number.isSafeInteger(version) || version < 1)) {
-    throw invalid('code project record has no official version', 409);
+    typeof value !== 'string'
+    || value.length < 1
+    || value.length > 1024
+    || value === '@'
+    || value === 'HEAD'
+    || value.startsWith('-')
+    || value.endsWith('.')
+    || value.includes('..')
+    || value.includes('@{')
+    || value.includes('[')
+    || /[\u0000-\u0020\u007f~^:?*\\]/.test(value)
+    || components.some((component) => (
+      !component
+      || component.startsWith('.')
+      || component.endsWith('.lock')
+    ))
+  ) throw invalid('branch name is invalid', 409);
+  return value;
+}
+
+function mutationId(value, label) {
+  if (!MUTATION_ID.test(String(value || ''))) throw invalid(`${label} is invalid`, 409);
+  return value;
+}
+
+function normalizeChunks(input, resourceId, kind, contract) {
+  exactObject(
+    input,
+    ['kind', 'contract', 'resourceId', 'checksum', 'bytes', 'chunks'],
+    `${kind} locator`,
+  );
+  if (
+    input.kind !== kind
+    || input.contract !== contract
+    || input.resourceId !== resourceId
+    || !SHA256.test(String(input.checksum || ''))
+    || !Number.isSafeInteger(input.bytes)
+    || input.bytes < 1
+    || !Array.isArray(input.chunks)
+    || input.chunks.length < 1
+    || input.chunks.length > MAX_CHUNKS
+  ) throw invalid(`${kind} locator is invalid`, 409);
+  const chunks = input.chunks.map((chunk) => {
+    exactObject(chunk, ['sha256', 'bytes'], `${kind} chunk`);
+    if (
+      !SHA256.test(String(chunk.sha256 || ''))
+      || !Number.isSafeInteger(chunk.bytes)
+      || chunk.bytes < 1
+      || chunk.bytes > MAX_CHUNK_BYTES
+    ) throw invalid(`${kind} chunk is invalid`, 409);
+    return { sha256: chunk.sha256, bytes: chunk.bytes };
+  });
+  if (chunks.reduce((sum, chunk) => sum + chunk.bytes, 0) !== input.bytes) {
+    throw invalid(`${kind} locator byte count is invalid`, 409);
   }
+  const checksum = crypto.createHash('sha256').update(Buffer.from(JSON.stringify(chunks))).digest('hex');
+  if (checksum !== input.checksum) throw invalid(`${kind} locator checksum is invalid`, 409);
   return {
-    ...input,
-    ...(Number.isSafeInteger(version) && version > 0 ? { version } : {}),
+    kind,
+    contract,
+    resourceId,
+    checksum: input.checksum,
+    bytes: input.bytes,
+    chunks,
+  };
+}
+
+function normalizeBundle(input, resourceId, oid) {
+  exactObject(
+    input,
+    ['kind', 'contract', 'resourceId', 'oid', 'ref', 'checksum', 'bytes', 'chunks'],
+    'bundle locator',
+  );
+  if (
+    input.kind !== 'bundle'
+    || input.contract !== BUNDLE_CONTRACT
+    || input.resourceId !== resourceId
+    || input.oid !== oid
+    || input.ref !== `refs/amalgm/exports/${oid}`
+  ) throw invalid('bundle locator is invalid', 409);
+  const common = normalizeChunks(
+    {
+      kind: 'bundle',
+      contract: BUNDLE_CONTRACT,
+      resourceId: input.resourceId,
+      checksum: input.checksum,
+      bytes: input.bytes,
+      chunks: input.chunks,
+    },
+    resourceId,
+    'bundle',
+    BUNDLE_CONTRACT,
+  );
+  return { ...common, oid, ref: input.ref };
+}
+
+function normalizePayload(input, resourceId) {
+  return normalizeChunks(input, resourceId, 'chunks', PAYLOAD_CONTRACT);
+}
+
+function normalizeCheckpointValue(input, resourceId, baseOid = null) {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) {
+    throw invalid('checkpoint value is invalid', 409);
+  }
+  const revision = input.revision;
+  if (!(revision === null || SHA256.test(String(revision || '')))) {
+    throw invalid('checkpoint revision is invalid', 409);
+  }
+  if (Object.hasOwn(input, 'sections')) {
+    exactObject(input, ['revision', 'sections'], 'checkpoint value');
+    exactObject(input.sections, ['index', 'worktree'], 'checkpoint sections');
+    const normalizeLayer = (layer) => {
+      if (!Array.isArray(input.sections[layer])) {
+        throw invalid('checkpoint sections are invalid', 409);
+      }
+      return input.sections[layer].map((section) => {
+        if (Object.hasOwn(section || {}, 'text')) {
+          exactObject(section, ['text'], 'checkpoint section');
+          if (typeof section.text !== 'string' || section.text.length === 0) {
+            throw invalid('checkpoint section is invalid', 409);
+          }
+          return { text: section.text };
+        }
+        exactObject(section, ['payload'], 'checkpoint section');
+        return { payload: normalizePayload(section.payload, resourceId) };
+      });
+    };
+    const normalized = {
+      revision,
+      sections: {
+        index: normalizeLayer('index'),
+        worktree: normalizeLayer('worktree'),
+      },
+    };
+    if (require('./checkpoint').revisionOfValue(baseOid, normalized) !== revision) {
+      throw invalid('checkpoint revision is invalid', 409);
+    }
+    return normalized;
+  }
+  exactObject(input, ['revision', 'indexDiff', 'worktreeDiff'], 'checkpoint value');
+  if (typeof input.indexDiff !== 'string' || typeof input.worktreeDiff !== 'string') {
+    throw invalid('checkpoint value is invalid', 409);
+  }
+  if (
+    baseOid
+    && require('./checkpoint').revisionOfValue(baseOid, input) !== revision
+  ) throw invalid('checkpoint revision is invalid', 409);
+  return {
+    revision,
+    indexDiff: input.indexDiff,
+    worktreeDiff: input.worktreeDiff,
+  };
+}
+
+function normalizeHead(input) {
+  exactObject(input, ['branch', 'oid', 'detached'], 'card head');
+  if (
+    !(input.branch === null || branchName(input.branch))
+    || !SHA.test(String(input.oid || ''))
+    || typeof input.detached !== 'boolean'
+    || (input.detached && input.branch !== null)
+    || (!input.detached && !input.branch)
+  ) throw invalid('card head is invalid', 409);
+  return { branch: input.branch, oid: input.oid, detached: input.detached };
+}
+
+function normalizeBranch(input, resourceId) {
+  exactObject(input, ['name', 'oid', 'objects'], 'card branch');
+  const name = branchName(input.name);
+  if (!SHA.test(String(input.oid || ''))) throw invalid('branch oid is invalid', 409);
+  return {
+    name,
+    oid: input.oid,
+    objects: normalizeBundle(input.objects, resourceId, input.oid),
+  };
+}
+
+function normalizeCheckpoint(input, resourceId, expectedHead = null) {
+  exactObject(input, ['checkpoint', 'baseOid', 'branch', 'value'], 'card checkpoint');
+  if (
+    input.checkpoint !== CHECKPOINT_CONTRACT
+    || !SHA.test(String(input.baseOid || ''))
+    || !(input.branch === null || branchName(input.branch))
+    || (expectedHead && (
+      input.baseOid !== expectedHead.oid
+      || input.branch !== expectedHead.branch
+    ))
+  ) throw invalid('card checkpoint is invalid', 409);
+  return {
+    checkpoint: CHECKPOINT_CONTRACT,
+    baseOid: input.baseOid,
+    branch: input.branch,
+    value: normalizeCheckpointValue(input.value, resourceId, input.baseOid),
+  };
+}
+
+function normalizeCardSet(input, resourceId) {
+  exactObject(input, ['kind', 'card', 'head', 'objects', 'branches', 'checkpoint'], 'card.set');
+  if (input.kind !== 'card.set' || input.card !== CARD_CONTRACT) {
+    throw invalid('card.set is invalid', 409);
+  }
+  const head = normalizeHead(input.head);
+  const branches = Array.isArray(input.branches)
+    ? input.branches.map((branch) => normalizeBranch(branch, resourceId))
+    : null;
+  if (!branches) throw invalid('card branches are invalid', 409);
+  if (branches.length > MAX_BRANCHES) throw invalid('card has too many branches', 409);
+  const names = new Set();
+  for (const branch of branches) {
+    if (names.has(branch.name)) throw invalid('card repeats a branch', 409);
+    names.add(branch.name);
+  }
+  if (!head.detached && !branches.some((branch) => (
+    branch.name === head.branch && branch.oid === head.oid
+  ))) throw invalid('card branch map does not contain HEAD', 409);
+  return {
+    kind: 'card.set',
+    card: CARD_CONTRACT,
+    head,
+    objects: normalizeBundle(input.objects, resourceId, head.oid),
+    branches: branches.sort((left, right) => left.name.localeCompare(right.name)),
+    checkpoint: normalizeCheckpoint(input.checkpoint, resourceId, head),
+  };
+}
+
+function normalizeCheckpointSet(input, resourceId) {
+  exactObject(
+    input,
+    ['kind', 'checkpoint', 'baseOid', 'branch', 'from', 'to'],
+    'checkpoint.set',
+  );
+  if (
+    input.kind !== 'checkpoint.set'
+    || input.checkpoint !== CHECKPOINT_CONTRACT
+    || !SHA.test(String(input.baseOid || ''))
+    || !(input.branch === null || branchName(input.branch))
+  ) throw invalid('checkpoint.set is invalid', 409);
+  return {
+    kind: 'checkpoint.set',
+    checkpoint: CHECKPOINT_CONTRACT,
+    baseOid: input.baseOid,
+    branch: input.branch,
+    from: normalizeCheckpointValue(input.from, resourceId, input.baseOid),
+    to: normalizeCheckpointValue(input.to, resourceId, input.baseOid),
+  };
+}
+
+function normalizeDelta(input, resourceId) {
+  let normalized;
+  if (input?.kind === 'card.set') normalized = normalizeCardSet(input, resourceId);
+  else if (input?.kind === 'checkpoint.set') normalized = normalizeCheckpointSet(input, resourceId);
+  else throw invalid('code project delta is invalid', 409);
+  const chunks = new Map();
+  const visit = (value) => {
+    if (!value || typeof value !== 'object') return;
+    if (Array.isArray(value)) {
+      value.forEach(visit);
+      return;
+    }
+    if (Array.isArray(value.chunks)) {
+      value.chunks.forEach((chunk) => {
+        const previous = chunks.get(chunk.sha256);
+        if (previous !== undefined && previous !== chunk.bytes) {
+          throw invalid('one code chunk claims two sizes', 409);
+        }
+        chunks.set(chunk.sha256, chunk.bytes);
+      });
+    }
+    Object.values(value).forEach(visit);
+  };
+  visit(normalized);
+  if (chunks.size > MAX_CHUNKS) throw invalid('code publication has too many chunks', 409);
+  return normalized;
+}
+
+function normalizeOperation(input, resourceId) {
+  exactObject(input, ['kind', 'project', 'delta'], 'code.publish operation');
+  if (input.kind !== 'code.publish' || input.project !== resourceId) {
+    throw invalid('code.publish operation is invalid', 409);
+  }
+  return {
+    kind: 'code.publish',
+    project: resourceId,
+    delta: normalizeDelta(input.delta, resourceId),
+  };
+}
+
+function stampCard(delta, stamp) {
+  return {
+    card: CARD_CONTRACT,
+    head: delta.head,
+    objects: delta.objects,
+    branches: delta.branches,
+    ...stamp,
+  };
+}
+
+function stampCheckpoint(checkpoint, stamp) {
+  return { ...checkpoint, ...stamp };
+}
+
+function sameValue(left, right) {
+  return JSON.stringify(left) === JSON.stringify(right);
+}
+
+function fold(snapshotInput, operationInput, stampInput) {
+  const snapshot = normalizeSnapshot(snapshotInput, operationInput?.project, true);
+  const operation = normalizeOperation(operationInput, snapshot.project);
+  const version = Number(stampInput?.version);
+  const machine = nonEmptyString(stampInput?.machine, 'mutation machine');
+  const officialMutationId = mutationId(stampInput?.mutationId, 'mutation id');
+  if (!Number.isSafeInteger(version) || version < 1) {
+    throw invalid('mutation version is invalid', 409);
+  }
+  // Snapshot writes precede cursor writes. Replaying after a crash is silent.
+  if (snapshot.version >= version) return snapshot;
+  if (version !== snapshot.version + 1) {
+    throw invalid(
+      `code project gap: expected ${snapshot.version + 1}, received ${version}`,
+      409,
+      'shared_mutation_gap',
+    );
+  }
+  const stamp = { machine, mutationId: officialMutationId, version };
+  if (operation.delta.kind === 'card.set') {
+    return {
+      schemaVersion: 2,
+      project: snapshot.project,
+      version,
+      card: stampCard(operation.delta, stamp),
+      checkpoint: stampCheckpoint(operation.delta.checkpoint, stamp),
+    };
+  }
+  const delta = operation.delta;
+  if (
+    !snapshot.card
+    || snapshot.card.head.oid !== delta.baseOid
+    || snapshot.card.head.branch !== delta.branch
+    || !snapshot.checkpoint
+    || snapshot.checkpoint.baseOid !== delta.baseOid
+    || snapshot.checkpoint.branch !== delta.branch
+    || !sameValue(snapshot.checkpoint.value, delta.from)
+  ) throw invalid('code_project_stale_base', 409, 'code_project_stale_base');
+  return {
+    ...snapshot,
+    version,
+    checkpoint: stampCheckpoint({
+      checkpoint: CHECKPOINT_CONTRACT,
+      baseOid: delta.baseOid,
+      branch: delta.branch,
+      value: delta.to,
+    }, stamp),
+  };
+}
+
+function emptySnapshot(resourceId) {
+  return {
+    schemaVersion: 2,
+    project: resourceId,
+    version: 0,
+    card: null,
+    checkpoint: null,
+  };
+}
+
+function normalizeStampedCard(input, resourceId, snapshotVersion) {
+  exactObject(
+    input,
+    ['card', 'head', 'objects', 'branches', 'machine', 'mutationId', 'version'],
+    'official card',
+  );
+  const version = Number(input.version);
+  if (
+    input.card !== CARD_CONTRACT
+    || !Number.isSafeInteger(version)
+    || version < 1
+    || version > snapshotVersion
+  ) throw invalid('official card stamp is invalid', 409);
+  const delta = normalizeCardSet({
+    kind: 'card.set',
+    card: input.card,
+    head: input.head,
+    objects: input.objects,
+    branches: input.branches,
+    checkpoint: {
+      checkpoint: CHECKPOINT_CONTRACT,
+      baseOid: input.head.oid,
+      branch: input.head.branch,
+      value: { revision: null, indexDiff: '', worktreeDiff: '' },
+    },
+  }, resourceId);
+  return {
+    card: CARD_CONTRACT,
+    head: delta.head,
+    objects: delta.objects,
+    branches: delta.branches,
+    machine: nonEmptyString(input.machine, 'official card machine'),
+    mutationId: mutationId(input.mutationId, 'official card mutation'),
+    version,
+  };
+}
+
+function normalizeStampedCheckpoint(input, resourceId, snapshotVersion) {
+  exactObject(
+    input,
+    ['checkpoint', 'baseOid', 'branch', 'value', 'machine', 'mutationId', 'version'],
+    'official checkpoint',
+  );
+  const version = Number(input.version);
+  if (
+    !Number.isSafeInteger(version)
+    || version < 1
+    || version > snapshotVersion
+  ) throw invalid('official checkpoint stamp is invalid', 409);
+  return {
+    ...normalizeCheckpoint({
+      checkpoint: input.checkpoint,
+      baseOid: input.baseOid,
+      branch: input.branch,
+      value: input.value,
+    }, resourceId),
+    machine: nonEmptyString(input.machine, 'official checkpoint machine'),
+    mutationId: mutationId(input.mutationId, 'official checkpoint mutation'),
+    version,
   };
 }
 
-function normalizeSnapshot(input, project = null, official = false) {
+function normalizeSnapshot(input, resourceId = null, official = false) {
+  exactObject(input, ['schemaVersion', 'project', 'version', 'card', 'checkpoint'], 'code project snapshot');
   if (
-    !input
-    || input.schemaVersion !== 1
+    input.schemaVersion !== 2
     || typeof input.project !== 'string'
     || !input.project
+    || !require('./tree/identity').isUuid(input.project)
+    || (resourceId && input.project !== resourceId)
     || !Number.isSafeInteger(Number(input.version))
     || Number(input.version) < 0
-    || !Array.isArray(input.records)
-    || (project && input.project !== project)
   ) throw invalid('code project snapshot is invalid', 409);
-  const machines = new Set();
-  const records = input.records.map((record) => {
-    const normalized = normalizeRecord(record, input.project, official);
-    if (official && normalized.version > Number(input.version)) {
-      throw invalid('code project record is newer than its snapshot', 409);
-    }
-    if (machines.has(normalized.machine)) {
-      throw invalid('code project snapshot repeats a machine', 409);
+  const version = Number(input.version);
+  if (version === 0) {
+    if (input.card !== null || input.checkpoint !== null) {
+      throw invalid('empty code project snapshot is invalid', 409);
     }
-    machines.add(normalized.machine);
-    return normalized;
-  });
+    return emptySnapshot(input.project);
+  }
+  if (!official || !input.card || !input.checkpoint) {
+    throw invalid('official code project snapshot is incomplete', 409);
+  }
+  const card = normalizeStampedCard(input.card, input.project, version);
+  const checkpoint = normalizeStampedCheckpoint(input.checkpoint, input.project, version);
+  if (
+    checkpoint.version !== version
+    || card.version > checkpoint.version
+    || checkpoint.baseOid !== card.head.oid
+    || checkpoint.branch !== card.head.branch
+  ) throw invalid('official checkpoint does not match the card', 409);
   return {
-    schemaVersion: 1,
+    schemaVersion: 2,
     project: input.project,
-    version: Number(input.version),
-    records,
+    version,
+    card,
+    checkpoint,
   };
 }
 
-function readSnapshot(file, project) {
-  if (!fs.existsSync(file) || fs.statSync(file).size === 0) return emptySnapshot(project);
+function readSnapshot(file, resourceId) {
+  if (!fs.existsSync(file) || fs.statSync(file).size === 0) return emptySnapshot(resourceId);
   try {
-    return normalizeSnapshot(JSON.parse(fs.readFileSync(file, 'utf8')), project);
+    return normalizeSnapshot(JSON.parse(fs.readFileSync(file, 'utf8')), resourceId, true);
   } catch (error) {
     if (error?.statusCode) throw error;
     throw invalid('code project snapshot is not JSON', 409);
@@ -86,114 +530,47 @@ function readSnapshot(file, project) {
 }
 
 function writeSnapshot(file, snapshot) {
-  fs.mkdirSync(require('path').dirname(file), { recursive: true });
-  fs.writeFileSync(file, `${JSON.stringify(snapshot)}\n`);
-}
-
-function applyRecord(snapshot, record, version = null) {
-  const next = normalizeRecord(
-    version ? { ...record, version } : record,
-    snapshot.project,
-    false,
-  );
-  const records = new Map(snapshot.records.map((entry) => [entry.machine, entry]));
-  records.set(next.machine, next);
-  return {
-    ...snapshot,
-    version: Number.isSafeInteger(version)
-      ? Math.max(snapshot.version, version)
-      : snapshot.version,
-    records: [...records.values()].sort((left, right) => (
-      left.machine.localeCompare(right.machine)
-    )),
-  };
-}
-
-function records(project) {
-  const snapshot = readSnapshot(project.file, project.repoKey);
-  let changed = false;
-  const sealed = snapshot.records.map((record) => {
-    if (record.version) return record;
-    const mutation = require('../state/mutations').getMutation(
-      `resource:${project.resourceId}`,
-      record.mutationId,
-    );
-    const version = mutation?.officialCloudVersion;
-    if (!Number.isSafeInteger(version) || version < 1) return record;
-    changed = true;
-    return { ...record, version };
-  });
-  if (changed) writeSnapshot(project.file, {
-    ...snapshot,
-    version: Math.max(snapshot.version, ...sealed.map((record) => record.version || 0)),
-    records: sealed,
-  });
-  return sealed;
+  durable.writeJson(file, normalizeSnapshot(snapshot, snapshot.project, true));
 }
 
-function publish(project, record) {
+function publish(project, deltaInput, mutationIdInput) {
   const replica = require('../state/replicas').getReplicaByResourceId(project.resourceId);
   if (!replica || replica.contract !== STREAM_CONTRACT) {
     throw invalid('code project stream is not attached', 409);
   }
+  const operation = normalizeOperation({
+    kind: 'code.publish',
+    project: project.resourceId,
+    delta: deltaInput,
+  }, project.resourceId);
+  const publicationMutationId = mutationId(mutationIdInput, 'publication mutation');
   return require('../state/mutations').commitLocalMutation({
     channelId: `resource:${project.resourceId}`,
-    localResource: localResource(project.resourceId),
+    localResource: `${LOCAL_RESOURCE_PREFIX}${project.resourceId}`,
     sharedResourceId: project.resourceId,
-    mutationId: record.mutationId,
+    mutationId: publicationMutationId,
     deviceId: require('./identity').machineId(),
     authorityEpoch: replica.authorityEpoch,
     baseCloudVersion: replica.appliedVersion,
     contract: STREAM_CONTRACT,
-    schemaVersion: 1,
+    schemaVersion: 2,
     operationKind: 'code.publish',
-    operation: { kind: 'code.publish', record },
+    operation,
   }, {
-    materialize() {
-      writeSnapshot(
-        project.file,
-        applyRecord(readSnapshot(project.file, project.repoKey), record),
-      );
-    },
+    // Outbound intent deliberately does not mutate the official snapshot.
     event: {
-      resource: localResource(project.resourceId),
+      resource: `${LOCAL_RESOURCE_PREFIX}${project.resourceId}`,
       op: 'update',
       id: project.file,
       sharedResourceId: project.resourceId,
-      value: record,
-      source: 'code-project:local',
+      value: operation.delta,
+      source: 'code-project:outbox',
     },
   });
 }
 
-function seal(project, mutationId, version) {
-  if (!Number.isSafeInteger(Number(version)) || Number(version) < 1) return false;
-  const snapshot = readSnapshot(project.file, project.repoKey);
-  let changed = false;
-  const records = snapshot.records.map((record) => {
-    if (record.mutationId !== mutationId || record.version === Number(version)) return record;
-    changed = true;
-    return { ...record, version: Number(version) };
-  });
-  if (!changed) return false;
-  writeSnapshot(project.file, {
-    ...snapshot,
-    version: Math.max(snapshot.version, Number(version)),
-    records,
-  });
-  appendStateEvent({
-    resource: localResource(project.resourceId),
-    op: 'update',
-    id: project.file,
-    sharedResourceId: project.resourceId,
-    resourceVersion: Number(version),
-    source: 'code-project:ack',
-  });
-  return true;
-}
-
 function decodeSnapshot(input) {
-  if (input?.contract !== STREAM_CONTRACT || Number(input?.schemaVersion) !== 1) {
+  if (input?.contract !== STREAM_CONTRACT || Number(input?.schemaVersion) !== 2) {
     throw invalid('unsupported code project stream', 409);
   }
   const bytes = Buffer.from(String(input.snapshotBase64 || ''), 'base64');
@@ -207,72 +584,122 @@ function decodeSnapshot(input) {
   } catch {
     throw invalid('code project snapshot must be JSON', 409);
   }
-  const snapshot = normalizeSnapshot(parsed, null, true);
+  const snapshot = normalizeSnapshot(parsed, input.resourceId, true);
   if (snapshot.version !== Number(input.snapshotVersion)) {
     throw invalid('code project snapshot version mismatch', 409);
   }
-  return { bytes, snapshot };
+  return { snapshot };
 }
 
 function installSnapshot(file, input, options = {}) {
   const database = options.database || openLocalDb();
-  const { snapshot } = decodeSnapshot(input);
   const replicas = require('../state/replicas');
+  const envelope = replicas.validateSnapshotEnvelope(input, {
+    contract: STREAM_CONTRACT,
+    schemaVersion: 2,
+  });
+  const { snapshot } = decodeSnapshot(input);
   const existing = replicas.getReplicaByResourceId(input.resourceId, { database });
   if (existing && existing.localPath !== file) {
     throw invalid('code project stream is bound to another local file', 409);
   }
-  let installed = snapshot;
-  if (existing) {
-    for (const mutation of require('../state/mutations').listPendingCloudMutations(
-      input.resourceId,
-      { database },
-    )) {
-      if (mutation.contract !== STREAM_CONTRACT || mutation.operationKind !== 'code.publish') continue;
-      installed = applyRecord(installed, mutation.operation?.record);
+  const current = fs.existsSync(file)
+    ? readSnapshot(file, input.resourceId)
+    : emptySnapshot(input.resourceId);
+  if (snapshot.version < current.version) {
+    const checked = existing
+      ? replicas.advanceReplicaSnapshot({
+        resourceId: envelope.resourceId,
+        snapshotVersion: envelope.snapshotVersion,
+        snapshotChecksum: input.snapshotChecksum,
+        authorityEpoch: envelope.authorityEpoch,
+      }, { database })
+      : existing;
+    return { replica: checked, duplicate: true, ignored: true };
+  }
+  if (snapshot.version === current.version) {
+    if (JSON.stringify(snapshot) !== JSON.stringify(current)) {
+      throw invalid(
+        'equal code project snapshot versions contain different state',
+        409,
+        'code_project_snapshot_mismatch',
+      );
+    }
+    if (existing) {
+      const replica = replicas.advanceReplicaSnapshot({
+        resourceId: input.resourceId,
+        snapshotVersion: envelope.snapshotVersion,
+        snapshotChecksum: input.snapshotChecksum,
+        authorityEpoch: envelope.authorityEpoch,
+      }, { database });
+      completeInstalledSnapshot(input.resourceId, snapshot.version, database);
+      return { replica, duplicate: true };
     }
   }
-  writeSnapshot(file, installed);
+  writeSnapshot(file, snapshot);
   const registered = existing
     ? {
       replica: replicas.advanceReplicaSnapshot({
         resourceId: input.resourceId,
-        snapshotVersion: input.snapshotVersion,
+        snapshotVersion: envelope.snapshotVersion,
         snapshotChecksum: input.snapshotChecksum,
-        authorityEpoch: input.authorityEpoch,
+        authorityEpoch: envelope.authorityEpoch,
       }, { database }),
     }
     : replicas.registerReplica({
       resourceId: input.resourceId,
-      localResource: localResource(input.resourceId),
+      localResource: `${LOCAL_RESOURCE_PREFIX}${input.resourceId}`,
       localPath: file,
       contract: STREAM_CONTRACT,
-      schemaVersion: 1,
-      authorityEpoch: input.authorityEpoch,
-      appliedVersion: input.snapshotVersion,
-      snapshotVersion: input.snapshotVersion,
+      schemaVersion: 2,
+      authorityEpoch: envelope.authorityEpoch,
+      appliedVersion: envelope.snapshotVersion,
+      snapshotVersion: envelope.snapshotVersion,
       snapshotChecksum: input.snapshotChecksum,
     }, { database });
+  completeInstalledSnapshot(input.resourceId, snapshot.version, database);
   appendStateEvent({
-    resource: localResource(input.resourceId),
+    resource: `${LOCAL_RESOURCE_PREFIX}${input.resourceId}`,
     op: 'update',
     id: file,
     sharedResourceId: input.resourceId,
-    resourceVersion: Number(input.snapshotVersion),
+    resourceVersion: envelope.snapshotVersion,
     source: 'code-project:snapshot',
   });
   return registered;
 }
 
+function completeInstalledSnapshot(resourceId, through, database) {
+  require('../state/mutations').completeOfficialSnapshotFold(
+    resourceId,
+    through,
+    { database },
+  );
+  const project = require('./wall').projectForResource(resourceId);
+  if (!project) return;
+  const intents = require('./intent');
+  const held = intents.readIntent(project);
+  const acknowledgement = held
+    ? intents.officialAcknowledgement(project, held)
+    : null;
+  if (acknowledgement && acknowledgement.version <= through) {
+    intents.markPublicationFolded(
+      project,
+      acknowledgement.mutationId,
+      acknowledgement.version,
+      held.publication.numberedAt,
+    );
+  }
+}
+
 function applyCloudMutation(input, options = {}) {
   const envelope = input?.envelope || {};
-  const record = envelope.operation?.record;
   if (
     envelope.contract !== STREAM_CONTRACT
+    || Number(envelope.schemaVersion) !== 2
     || envelope.operationKind !== 'code.publish'
-    || envelope.operation?.kind !== 'code.publish'
-    || record?.mutationId !== envelope.mutationId
   ) throw invalid('invalid code project cloud mutation', 409);
+  const operation = normalizeOperation(envelope.operation, envelope.resourceId);
   const database = options.database || openLocalDb();
   const replica = require('../state/replicas').getReplicaByResourceId(
     envelope.resourceId,
@@ -283,41 +710,62 @@ function applyCloudMutation(input, options = {}) {
   }
   return require('../state/mutations').ingestCloudMutation({
     ...input,
-    localResource: localResource(envelope.resourceId),
+    localResource: `${LOCAL_RESOURCE_PREFIX}${envelope.resourceId}`,
   }, {
     database,
+    requireOfficialMaterialization: true,
     materialize() {
-      writeSnapshot(
-        replica.localPath,
-        applyRecord(
-          readSnapshot(replica.localPath, record.project),
-          record,
-          Number(input.version),
-        ),
+      const next = fold(
+        readSnapshot(replica.localPath, envelope.resourceId),
+        operation,
+        {
+          machine: envelope.deviceId,
+          mutationId: envelope.mutationId,
+          version: Number(input.version),
+        },
       );
+      writeSnapshot(replica.localPath, next);
+      const project = require('./wall').projectForResource(envelope.resourceId);
+      if (project) {
+        require('./intent').markPublicationFolded(
+          project,
+          envelope.mutationId,
+          Number(input.version),
+          input.committedAt,
+        );
+      }
     },
     event: {
-      resource: localResource(envelope.resourceId),
+      resource: `${LOCAL_RESOURCE_PREFIX}${envelope.resourceId}`,
       op: 'update',
       id: replica.localPath,
       sharedResourceId: envelope.resourceId,
       resourceVersion: Number(input.version),
-      value: record,
+      value: operation.delta,
       source: 'code-project:cloud',
     },
   });
 }
 
 module.exports = {
+  BUNDLE_CONTRACT,
+  CARD_CONTRACT,
+  CHECKPOINT_CONTRACT,
   LOCAL_RESOURCE_PREFIX,
+  PAYLOAD_CONTRACT,
   STREAM_CONTRACT,
   WALL_CONTRACT,
-  _test: { applyRecord, emptySnapshot, normalizeSnapshot },
+  _test: {
+    emptySnapshot,
+    fold,
+    normalizeDelta,
+    normalizeOperation,
+    normalizeSnapshot,
+  },
   applyCloudMutation,
+  emptySnapshot,
   installSnapshot,
   publish,
   readSnapshot,
-  records,
-  seal,
   writeSnapshot,
 };