amalgm 0.1.238 → 0.1.240

package/runtime/scripts/amalgm-mcp/workspace/wall.js

@@ -1,13 +1,11 @@
 'use strict';
 
 /**
- * One ordered card+checkpoint stream per code project.
+ * Local adapter between a checkout and its one canonical project stream.
  *
- * A project is the authorization pool for one repository. Same-user
- * machines derive the same resource from (owner, repo identity). A
- * collaborator binds that repo identity to the owner's resource after the
- * owner grants membership. Every authorized machine is then an ordinary
- * writer in the same stream.
+ * repoKey is only a local lookup alias. resourceId is the sole cloud key.
+ * The cloud stores exactly one card and one checkpoint; this file derives
+ * one card.set or checkpoint.set proposal from the current checkout.
  */
 
 const crypto = require('crypto');
@@ -15,21 +13,20 @@ const fs = require('fs');
 const path = require('path');
 const { AMALGM_DIR } = require('../config');
 const { subscribeStateEvents } = require('../state/events');
+const durable = require('./durable');
 const { machineId, userId } = require('./identity');
 const { listRepoCards } = require('./cards');
 const {
   CHECKPOINT_CONTRACT,
-  checkpointValue,
   checkpointValueReady,
   readCheckpoint,
   repoKeyOfCard,
-  sameTransition,
   stampCheckpointMutation,
 } = require('./checkpoint');
 const projectStream = require('./project-stream');
 
 const { WALL_CONTRACT } = projectStream;
-const PROJECT_DIR = path.join(AMALGM_DIR, 'state', 'code-projects');
+const PROJECT_DIR = path.join(AMALGM_DIR, 'state', 'code-projects-v2');
 const REGISTRY_FILE = path.join(PROJECT_DIR, 'projects.json');
 const PUBLISH_QUIET_MS = 25;
 const ENSURE_STEP_TIMEOUT_MS = 20_000;
@@ -57,16 +54,7 @@ function readRegistry() {
 }
 
 function writeRegistry(registry) {
-  fs.mkdirSync(PROJECT_DIR, { recursive: true });
-  fs.writeFileSync(REGISTRY_FILE, `${JSON.stringify(registry, null, 2)}\n`);
-}
-
-function projectResourceId(repoKey, ownerUserId = userId()) {
-  if (!repoKey || !ownerUserId) return null;
-  const digest = crypto.createHash('sha256')
-    .update(`amalgm-code-project@2|${ownerUserId}|${repoKey}`)
-    .digest('base64url');
-  return `shr_cp1${digest.slice(0, 40)}`;
+  durable.writeJson(REGISTRY_FILE, registry, { pretty: true });
 }
 
 function projectFile(resourceId) {
@@ -74,66 +62,105 @@ function projectFile(resourceId) {
   return path.join(PROJECT_DIR, `${digest}.json`);
 }
 
+function canonicalPath(localPath) {
+  const resolved = path.resolve(localPath);
+  const tail = [];
+  let existing = resolved;
+  while (!fs.existsSync(existing)) {
+    const parent = path.dirname(existing);
+    if (parent === existing) return resolved;
+    tail.unshift(path.basename(existing));
+    existing = parent;
+  }
+  return path.join(fs.realpathSync.native(existing), ...tail);
+}
+
+function projectRecord(bound) {
+  if (!bound?.resourceId) return null;
+  return {
+    repoKey: `code-folder:${bound.resourceId}`,
+    resourceId: bound.resourceId,
+    ownerUserId: bound.ownerUserId || null,
+    path: bound?.path || null,
+    file: projectFile(bound.resourceId),
+  };
+}
+
+function projects() {
+  return Object.values(readRegistry()).map(projectRecord).filter(Boolean);
+}
+
+function projectForPath(localPath) {
+  if (!localPath) return null;
+  const resolved = canonicalPath(localPath);
+  return projects().find((project) => (
+    project.path && canonicalPath(project.path) === resolved
+  )) || null;
+}
+
 function projectForRepo(repoKey) {
   if (!repoKey) return null;
-  const bound = readRegistry()[repoKey];
-  const ownerUserId = bound?.ownerUserId || userId();
-  const resourceId = bound?.resourceId || projectResourceId(repoKey, ownerUserId);
-  return resourceId ? {
-    repoKey,
-    resourceId,
-    ownerUserId,
-    path: bound?.path || null,
-    file: projectFile(resourceId),
-  } : null;
+  const direct = projects().find((project) => project.repoKey === repoKey);
+  if (direct) return direct;
+  const card = listRepoCards().find((candidate) => repoKeyOfCard(candidate) === repoKey);
+  return projectForPath(card?.path);
 }
 
-function bindProject(repoKey, resourceId, ownerUserId = null, localPath = null) {
-  if (!repoKey || typeof repoKey !== 'string') throw new Error('repoKey is required');
-  if (!/^shr_[A-Za-z0-9_-]{16,128}$/.test(String(resourceId || ''))) {
-    throw new Error('resourceId must be an opaque shared resource id');
+function projectForResource(resourceId) {
+  return projects().find((project) => project.resourceId === resourceId) || null;
+}
+
+function bindProject(resourceId, ownerUserId = null, localPath = null) {
+  const identity = require('./tree/identity');
+  if (!identity.isUuid(String(resourceId || ''))) {
+    throw new Error('resourceId must be the code-folder UUID');
+  }
+  if (!identity.isUuid(String(ownerUserId || ''))) {
+    throw new Error('ownerUserId must be a user UUID');
   }
-  if (localPath !== null && (typeof localPath !== 'string' || !path.isAbsolute(localPath))) {
+  if (typeof localPath !== 'string' || !path.isAbsolute(localPath)) {
     throw new Error('path must be an absolute folder path');
   }
   const registry = readRegistry();
-  const previous = registry[repoKey];
-  registry[repoKey] = {
-    resourceId,
-    ownerUserId: ownerUserId || null,
-    path: localPath || previous?.path || null,
+  const key = resourceId.toLowerCase();
+  const owner = ownerUserId.toLowerCase();
+  const boundPath = canonicalPath(localPath);
+  const existing = registry[key];
+  if (existing) {
+    if (
+      existing.resourceId === key
+      && existing.ownerUserId === owner
+      && canonicalPath(existing.path) === boundPath
+    ) return projectRecord(existing);
+    throw new Error('that code-folder UUID is already bound differently');
+  }
+  const pathOwner = Object.values(registry).find((bound) => (
+    bound?.path && canonicalPath(bound.path) === boundPath
+  ));
+  if (pathOwner) throw new Error('that folder path is already bound to another code-folder UUID');
+  registry[key] = {
+    resourceId: key,
+    ownerUserId: owner,
+    path: boundPath,
     joinedAt: new Date().toISOString(),
   };
   writeRegistry(registry);
-  if (localPath) {
-    require('./store').upsertWorkspace({
-      path: localPath,
-      name: path.basename(localPath),
-      source: 'computer',
-      managed: false,
-    }, { source: 'workspace:code-project-bind' });
-  }
+  require('./store').upsertWorkspace({
+    path: boundPath,
+    name: path.basename(boundPath),
+    source: 'computer',
+    managed: false,
+  }, { source: 'workspace:code-project-bind' });
+  const project = projectRecord(registry[key]);
   if (service.started) {
-    ensureProjectBound(projectForRepo(repoKey))
+    ensureProjectBound(project)
       .then(() => {
         schedulePublish();
         return require('./reducer').reduceNow();
       })
       .catch(() => {});
   }
-  return projectForRepo(repoKey);
-}
-
-function projects() {
-  const byRepo = new Map();
-  for (const card of listRepoCards()) {
-    const repoKey = repoKeyOfCard(card);
-    if (repoKey && !byRepo.has(repoKey)) byRepo.set(repoKey, projectForRepo(repoKey));
-  }
-  for (const repoKey of Object.keys(readRegistry())) {
-    if (!byRepo.has(repoKey)) byRepo.set(repoKey, projectForRepo(repoKey));
-  }
-  return [...byRepo.values()].filter(Boolean);
+  return project;
 }
 
 function wallReplica(project) {
@@ -141,61 +168,111 @@ function wallReplica(project) {
   return replica?.contract === projectStream.STREAM_CONTRACT ? replica : null;
 }
 
+function outboundState(rows) {
+  const terminal = rows.find((row) => row.state === 'rejected' || row.state === 'conflicted');
+  return {
+    pending: rows.length,
+    terminalError: terminal
+      ? terminal.lastError || `code publication ${terminal.mutationId} was ${terminal.state}`
+      : null,
+  };
+}
+
 function publicationStatus(repoKey, reduced = undefined) {
   const project = projectForRepo(repoKey);
   const replica = project ? wallReplica(project) : null;
   const receivedThrough = replica?.appliedVersion ?? null;
+  if (project && Number.isInteger(receivedThrough)) {
+    require('../state/mutations').retireStaleCodeMutations(
+      project.resourceId,
+      receivedThrough,
+    );
+  }
   const baseline = reduced === undefined
     ? require('./reducer').readRepoState(repoKey, project?.resourceId)
     : reduced;
   const appliedThrough = Number.isInteger(baseline?.appliedThrough)
     ? baseline.appliedThrough
     : receivedThrough === 0 && !baseline ? 0 : null;
-  const pending = project
-    ? require('../state/mutations').listPendingCloudMutations(project.resourceId).length
-    : 0;
+  const mutations = require('../state/mutations');
+  const pendingRows = project
+    ? mutations.listPendingCloudMutations(project.resourceId)
+    : [];
+  const officialRows = project
+    ? mutations.listUnappliedOfficialMutations(project.resourceId)
+    : [];
+  const outgoing = outboundState(pendingRows);
   return {
     receivedThrough,
     appliedThrough,
-    pending,
+    ...outgoing,
+    awaitingOfficial: officialRows.length,
     current: receivedThrough !== null
       && appliedThrough === receivedThrough
-      && pending === 0,
+      && outgoing.pending === 0
+      && officialRows.length === 0,
   };
 }
 
-function sealCardVersions(project, card, record = null) {
-  const versionFor = (mutationId) => (
-    mutationId === record?.mutationId && validVersion(record?.version)
-      ? record.version
-      : officialVersion(project.resourceId, mutationId)
+function localRepo(card, repoKey) {
+  return card?.repo || (
+    repoKey.startsWith('root:')
+      ? { remote: null, rootCommit: repoKey.slice(5) }
+      : { remote: repoKey, rootCommit: null }
   );
-  return {
-    ...card,
-    positionVersion: validVersion(card.positionVersion)
-      ? card.positionVersion
-      : versionFor(card.positionMutationId),
-    branches: (card.branches || []).map((ref) => ({
-      ...ref,
-      version: validVersion(ref.version)
-        ? ref.version
-        : versionFor(ref.mutationId),
-    })),
-    checkpoints: (card.checkpoints || []).map((checkpoint) => ({
-      ...checkpoint,
-      version: validVersion(checkpoint.version)
-        ? checkpoint.version
-        : versionFor(checkpoint.mutationId),
-    })),
-  };
 }
 
+/**
+ * The reducer still consumes its local card-shaped projection. This adapter
+ * is not shared state: it injects the local repo alias and derives one exact
+ * clean→current checkpoint transition from the canonical two values.
+ */
 function readProjectWall(project) {
-  return projectStream.records(project).map((entry) => ({
-    ...entry,
+  const snapshot = projectStream.readSnapshot(project.file, project.resourceId);
+  if (!snapshot.card || !snapshot.checkpoint) return [];
+  const card = snapshot.card;
+  const checkpoint = snapshot.checkpoint;
+  return [{
+    wall: WALL_CONTRACT,
+    project: project.resourceId,
     resourceId: project.resourceId,
-    cards: entry.cards.map((card) => sealCardVersions(project, card, entry)),
-  }));
+    machine: card.machine,
+    mutationId: card.mutationId,
+    version: snapshot.version,
+    cards: [{
+      card: projectStream.CARD_CONTRACT,
+      machine: card.machine,
+      replica: `official:${project.resourceId}`,
+      repo: localRepo(null, project.repoKey),
+      kind: 'primary',
+      health: 'healthy',
+      head: card.head,
+      objects: card.objects,
+      positionMachine: card.machine,
+      positionMutationId: card.mutationId,
+      positionVersion: card.version,
+      branches: card.branches.map((branch) => ({
+        ...branch,
+        machine: card.machine,
+        mutationId: card.mutationId,
+        version: card.version,
+      })),
+      checkpoints: [{
+        checkpoint: CHECKPOINT_CONTRACT,
+        machine: checkpoint.machine,
+        baseOid: checkpoint.baseOid,
+        branch: checkpoint.branch,
+        from: {
+          revision: null,
+          indexDiff: '',
+          worktreeDiff: '',
+        },
+        to: checkpoint.value,
+        mutationId: checkpoint.mutationId,
+        version: checkpoint.version,
+      }],
+    }],
+  }];
 }
 
 function readWall(repoKey = null) {
@@ -203,356 +280,120 @@ function readWall(repoKey = null) {
   return selected.flatMap((project) => readProjectWall(project));
 }
 
-function publishedCardFor(card) {
-  const repoKey = repoKeyOfCard(card);
-  if (!repoKey) return null;
-  const own = readWall(repoKey).find((entry) => entry.machine === machineId());
-  const published = own?.cards?.find((candidate) => candidate.replica === card.replica);
-  if (
-    !published
-    || !Number.isInteger(published.positionVersion)
-    || published.positionVersion < 1
-    || published.head?.branch !== card.head?.branch
-    || published.head?.oid !== card.head?.oid
-    || Boolean(published.head?.detached) !== Boolean(card.head?.detached)
-  ) return null;
-  return published;
-}
-
 function samePosition(left, right) {
   return left?.head?.branch === right?.head?.branch
     && left?.head?.oid === right?.head?.oid
     && Boolean(left?.head?.detached) === Boolean(right?.head?.detached);
 }
 
-function oidMap(refs) {
-  return new Map((refs || []).map((ref) => [ref.name, ref.oid ?? null]));
-}
-
-/**
- * Publishing is a transition from the last shared state this checkout
- * materialized. A local value equal to either that baseline or the current
- * rail is not new work. Anything else is a local contribution.
- */
-function hasLocalContribution(card, plan, baseline, checkpoint = null, previousCard = null) {
-  if (!plan?.card) return true;
-  const onRail = samePosition(card, plan.card);
-  const atBaseline = baseline
-    && card.head?.branch === baseline.branch
-    && card.head?.oid === baseline.baseOid
-    && !baseline.pendingCard;
-  const alreadyPublished = validVersion(previousCard?.positionVersion)
-    && samePosition(card, previousCard);
-  const reversesPublishedSharedPosition = previousCard
-    && validVersion(previousCard.positionVersion)
-    && samePosition(previousCard, plan.card)
-    && !alreadyPublished;
-  if ((!onRail && !atBaseline && !alreadyPublished) || reversesPublishedSharedPosition) return true;
-
-  const currentRefs = oidMap(card.refs);
-  const railRefs = oidMap(plan.branches);
-  const baselineRefs = oidMap(baseline?.branches);
-  const previousRefs = new Map(
-    (previousCard?.branches || previousCard?.refs || []).map((ref) => [ref.name, ref]),
-  );
-  for (const name of new Set([
-    ...currentRefs.keys(),
-    ...baselineRefs.keys(),
-    ...previousRefs.keys(),
-  ])) {
-    const current = currentRefs.get(name) ?? null;
-    const shared = railRefs.get(name) ?? null;
-    const previous = baselineRefs.get(name) ?? null;
-    const publishedRef = previousRefs.get(name);
-    const published = publishedRef?.oid ?? null;
-    const matchesBaseline = baselineRefs.has(name) && current === previous;
-    const matchesPublished = validVersion(publishedRef?.version) && current === published;
-    const reversesPublishedSharedValue = validVersion(publishedRef?.version)
-      && published === shared
-      && current !== published;
-    if (
-      current !== shared
-      && ((!matchesBaseline && !matchesPublished) || reversesPublishedSharedValue)
-    ) return true;
-  }
-
-  if (
-    onRail
-    && checkpoint
-    && checkpoint.baseOid === card.head?.oid
-    && checkpoint.branch === card.head?.branch
-  ) {
-    const latest = [...(plan.transitions || [])]
-      .reverse()
-      .find((entry) => entry.machine === checkpoint.machine);
-    if (!sameTransition(latest, checkpoint)) return true;
-  }
-  return false;
+function branchIdentity(refs) {
+  return JSON.stringify((refs || [])
+    .map((ref) => ({ name: ref.name, oid: ref.oid }))
+    .sort((left, right) => left.name.localeCompare(right.name)));
 }
 
-function hasPendingContributionObjects(card, plan) {
-  if (!plan?.card || !samePosition(card, plan.card)) {
-    return card.objects?.kind === 'pending';
-  }
-  const shared = new Map((plan.branches || []).map((ref) => [ref.name, ref]));
-  return (card.refs || []).some((ref) => {
-    const accepted = shared.get(ref.name);
-    const alreadyAvailable = accepted
-      && validVersion(accepted.version)
-      && (accepted.oid ?? null) === (ref.oid ?? null);
-    return !alreadyAvailable && ref.objects?.kind === 'pending';
-  });
+function sameCardState(localCard, officialCard) {
+  return samePosition(localCard, officialCard)
+    && branchIdentity(localCard?.refs || localCard?.branches)
+      === branchIdentity(officialCard?.refs || officialCard?.branches);
 }
 
-function checkpointBaseFor(card, baseline, project, shared = null) {
-  if (
-    !baseline
-    || baseline.baseOid !== card.head?.oid
-    || baseline.branch !== card.head?.branch
-    || !Number.isInteger(baseline.appliedThrough)
-    || baseline.appliedThrough < 0
-  ) return null;
-  const value = checkpointValue(
-    machineId(),
-    project.repoKey,
-    card.head.oid,
-    baseline.indexDiff || '',
-    baseline.worktreeDiff || '',
-  );
-  if (!checkpointValueReady(value)) return null;
-  const reusableThrough = shared
-    && shared.baseOid === card.head.oid
-    && shared.branch === card.head.branch
-    && shared.value?.revision === value.revision
-    && Number.isInteger(shared.through)
-    && shared.through >= 0;
-  return {
-    checkpoint: CHECKPOINT_CONTRACT,
-    baseOid: card.head.oid,
-    branch: card.head.branch,
-    through: reusableThrough ? shared.through : baseline.appliedThrough,
-    value,
-  };
+function publishedCardFor(card) {
+  const project = projectForPath(card?.path);
+  if (!project) return null;
+  const projected = readProjectWall(project)[0]?.cards?.[0] || null;
+  return projected && sameCardState(card, projected) ? projected : null;
 }
 
-function validVersion(value) {
-  return Number.isInteger(value) && value > 0;
+function isCommittedCard(card) {
+  return typeof card?.head?.oid === 'string'
+    && /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/.test(card.head.oid);
 }
 
-function knownMutation(resourceId, mutationId) {
-  if (!mutationId) return false;
-  return Boolean(require('../state/mutations').getMutation(`resource:${resourceId}`, mutationId));
+function cardPayloadsReady(card) {
+  if (card.head?.oid && card.objects?.kind !== 'bundle') return false;
+  return (card.refs || card.branches || []).every((ref) => (
+    !ref.oid || ref.objects?.kind === 'bundle'
+  ));
 }
 
-function officialVersion(resourceId, mutationId) {
-  if (!mutationId) return null;
-  const mutation = require('../state/mutations').getMutation(`resource:${resourceId}`, mutationId);
-  return Number.isInteger(mutation?.officialCloudVersion) ? mutation.officialCloudVersion : null;
+function hasPendingContributionObjects(card) {
+  return !cardPayloadsReady(card);
 }
 
-function durableMutationVersion(project, mutationId) {
-  if (!project || !mutationId) return null;
-  for (const record of projectStream.records(project)) {
-    if (record.mutationId === mutationId && validVersion(record.version)) return record.version;
-    for (const card of record.cards) {
-      if (card.positionMutationId === mutationId) {
-        return validVersion(card.positionVersion) ? card.positionVersion : null;
-      }
-      const nested = [
-        ...(card.branches || []),
-        ...(card.checkpoints || []),
-      ].find((entry) => entry.mutationId === mutationId);
-      if (nested) return validVersion(nested.version) ? nested.version : null;
-    }
-  }
-  return null;
-}
-
-function mutationVersion(resourceId, mutationId, repoKey = null) {
-  if (!resourceId) return null;
-  return officialVersion(resourceId, mutationId)
-    || durableMutationVersion(repoKey ? projectForRepo(repoKey) : null, mutationId);
-}
-
-function sealedVersion(resourceId, mutationId, ...versions) {
-  return versions.find(validVersion)
-    || officialVersion(resourceId, mutationId)
-    || null;
-}
-
-function stampBranches(
-  refs,
-  previousBranches,
-  sharedBranches,
-  baselineBranches,
-  mutationId,
-  resourceId,
-) {
-  const current = new Map((refs || []).map((ref) => [ref.name, ref]));
-  const previous = new Map((previousBranches || []).map((ref) => [ref.name, ref]));
-  const shared = new Map((sharedBranches || []).map((ref) => [ref.name, ref]));
-  const baseline = new Map((baselineBranches || []).map((ref) => [ref.name, ref]));
-  const names = [...new Set([...current.keys(), ...previous.keys()])].sort();
-  return names.map((name) => {
-    const observed = current.get(name);
-    const before = previous.get(name);
-    const onRail = shared.get(name);
-    const materialized = baseline.get(name);
-    const oid = observed?.oid ?? null;
-    const unchanged = before && (before.oid ?? null) === oid;
-    const previousReusable = unchanged
-      && before.mutationId
-      && (validVersion(before.version) || knownMutation(resourceId, before.mutationId));
-    const railReusable = onRail
-      && (onRail.oid ?? null) === oid
-      && onRail.mutationId
-      && validVersion(onRail.version);
-    const baselineReusable = materialized
-      && (materialized.oid ?? null) === oid
-      && materialized.mutationId
-      && validVersion(materialized.version);
-    const mutation = previousReusable
-      ? before.mutationId
-      : railReusable
-        ? onRail.mutationId
-        : baselineReusable ? materialized.mutationId : mutationId;
-    return {
-      name,
-      oid,
-      ...(observed?.objects ? { objects: observed.objects } : {}),
-      mutationId: mutation,
-      version: sealedVersion(
-        resourceId,
-        mutation,
-        mutation === before?.mutationId ? before.version : null,
-        mutation === onRail?.mutationId ? onRail.version : null,
-        mutation === materialized?.mutationId ? materialized.version : null,
-      ),
-    };
-  });
+function checkpointForCard(card, repoKey) {
+  const checkpoint = readCheckpoint(machineId(), repoKey);
+  if (
+    checkpoint
+    && checkpoint.checkpoint === CHECKPOINT_CONTRACT
+    && checkpoint.baseOid === card.head?.oid
+    && checkpoint.branch === card.head?.branch
+    && checkpointValueReady(checkpoint.to)
+  ) return checkpoint;
+  const dirty = card.dirty || {};
+  const clean = ['staged', 'unstaged', 'untracked', 'conflicted', 'submodulesChanged']
+    .every((key) => Number(dirty[key] || 0) === 0);
+  return clean ? {
+    checkpoint: CHECKPOINT_CONTRACT,
+    baseOid: card.head.oid,
+    branch: card.head.branch,
+    from: { revision: null, indexDiff: '', worktreeDiff: '' },
+    to: { revision: null, indexDiff: '', worktreeDiff: '' },
+  } : null;
 }
 
-function sharedCard(card) {
+function cardSet(card, checkpoint) {
   return {
-    card: card.card,
-    machine: card.machine,
-    replica: card.replica,
-    repo: card.repo,
-    objects: card.objects,
-    kind: card.kind,
+    kind: 'card.set',
+    card: projectStream.CARD_CONTRACT,
     head: {
-      branch: card.head?.branch ?? null,
-      oid: card.head?.oid ?? null,
-      detached: Boolean(card.head?.detached),
+      branch: card.head.branch ?? null,
+      oid: card.head.oid,
+      detached: Boolean(card.head.detached),
+    },
+    objects: card.objects,
+    branches: (card.refs || card.branches || []).map((ref) => ({
+      name: ref.name,
+      oid: ref.oid,
+      objects: ref.objects,
+    })),
+    checkpoint: {
+      checkpoint: CHECKPOINT_CONTRACT,
+      baseOid: card.head.oid,
+      branch: card.head.branch ?? null,
+      value: checkpoint.to,
     },
-    health: card.health,
   };
 }
 
-function isCommittedCard(card) {
-  return typeof card?.head?.oid === 'string' && /^[0-9a-f]{40,64}$/.test(card.head.oid);
-}
-
-function stampCards(cards, previousCards, sharedPlan, baseline, mutationId, project) {
-  const previousByReplica = new Map(
-    (previousCards || []).filter((card) => card?.replica).map((card) => [card.replica, card]),
-  );
-  return cards.map((card) => {
-    const previous = previousByReplica.get(card.replica);
-    const reusablePosition = samePosition(previous, card)
-      && previous?.positionMutationId
-      && (
-        validVersion(previous.positionVersion)
-        || knownMutation(project.resourceId, previous.positionMutationId)
-      );
-    const reusableRailPosition = samePosition(sharedPlan?.card, card)
-      && sharedPlan.card.positionMutationId
-      && validVersion(sharedPlan.card.positionVersion);
-    const reusableBaselinePosition = baseline
-      && card.head?.branch === baseline.branch
-      && card.head?.oid === baseline.baseOid
-      && baseline.cardMutationId
-      && validVersion(baseline.cardVersion);
-    const positionMutationId = reusablePosition
-      ? previous.positionMutationId
-      : reusableRailPosition
-        ? sharedPlan.card.positionMutationId
-        : reusableBaselinePosition ? baseline.cardMutationId : mutationId;
-    const positionVersion = sealedVersion(
-      project.resourceId,
-      positionMutationId,
-      positionMutationId === previous?.positionMutationId ? previous.positionVersion : null,
-      positionMutationId === sharedPlan?.card?.positionMutationId
-        ? sharedPlan.card.positionVersion
-        : null,
-      positionMutationId === baseline?.cardMutationId ? baseline.cardVersion : null,
-    );
-    const checkpoint = readCheckpoint(machineId(), project.repoKey);
-    const currentCheckpoint = checkpoint
-      && checkpoint.baseOid === card.head?.oid
-      && checkpoint.branch === card.head?.branch
-      ? checkpoint
-      : null;
-    const checkpointBase = checkpointBaseFor(
-      card,
-      baseline,
-      project,
-      sharedPlan?.card?.checkpointBase,
-    );
-    const sameBase = previous?.head?.oid === card.head?.oid
-      && previous?.head?.branch === card.head?.branch;
-    const history = sameBase && Array.isArray(previous?.checkpoints)
-      ? previous.checkpoints.map((entry) => ({
-        ...entry,
-        version: sealedVersion(
-          project.resourceId,
-          entry.mutationId,
-          entry.version,
-        ),
-      })).filter((entry) => (
-        validVersion(entry.version)
-        && (!checkpointBase || entry.version > checkpointBase.through)
-      ))
-      : [];
-    const last = history.at(-1);
-    const checkpoints = currentCheckpoint
-      ? (sameTransition(last, currentCheckpoint)
-        ? history
-        : [...history, { ...currentCheckpoint, mutationId }])
-      : history;
-    return {
-      ...sharedCard(card),
-      positionMutationId,
-      positionVersion,
-      branches: stampBranches(
-        card.refs,
-        previous?.branches,
-        sharedPlan?.branches,
-        baseline?.branches,
-        mutationId,
-        project.resourceId,
-      ),
-      ...(checkpointBase ? { checkpointBase } : {}),
-      ...(checkpoints.length ? { checkpoints } : {}),
-    };
-  });
-}
-
-function cardsUseMutation(cards, mutationId) {
-  return cards.some((card) => (
-    card.positionMutationId === mutationId
-    || (card.branches || []).some((ref) => ref.mutationId === mutationId)
-    || (card.checkpoints || []).some((checkpoint) => checkpoint.mutationId === mutationId)
-  ));
+function checkpointSet(card, checkpoint, officialCheckpoint) {
+  return {
+    kind: 'checkpoint.set',
+    checkpoint: CHECKPOINT_CONTRACT,
+    baseOid: card.head.oid,
+    branch: card.head.branch ?? null,
+    from: officialCheckpoint.value,
+    to: checkpoint.to,
+  };
 }
 
-function samePublishedRecord(left, right) {
-  if (!left || !right) return false;
-  const stripTransport = ({ publishedAt, mutationId, version, ...record }) => record;
-  return JSON.stringify(stripTransport(left)) === JSON.stringify(stripTransport(right));
+function hasLocalContribution(card, plan) {
+  return !plan?.card || !sameCardState(card, plan.card);
 }
 
 function publishProject(project, rawCards) {
+  const intents = require('./intent');
+  const intent = intents.readOwnedIntent(project);
+  if (intent?.terminal) {
+    service.counters.publishSkips += 1;
+    return {
+      published: false,
+      reason: 'local-intent-rejected',
+      terminalError: intent.terminal.message,
+      terminalCode: intent.terminal.code,
+      repoKey: project.repoKey,
+    };
+  }
   const replica = wallReplica(project);
   if (!replica) {
     service.counters.publishSkips += 1;
@@ -562,75 +403,73 @@ function publishProject(project, rawCards) {
     service.counters.publishSkips += 1;
     return { published: false, reason: 'repo-materializing', repoKey: project.repoKey };
   }
-  const previousEntry = projectStream.records(project)
-    .find((entry) => entry.machine === machineId()) || null;
-
-  const reducer = require('./reducer');
-  const sharedPlan = reducer.reduceWall(readProjectWall(project)).get(project.repoKey);
-  const baseline = reducer.readRepoState(project.repoKey, project.resourceId);
-  const previousCards = (previousEntry?.cards || [])
-    .map((card) => sealCardVersions(project, card, previousEntry));
-  const previousReplicas = new Set(previousCards.map((card) => card.replica));
-  const currentReplicas = new Set(rawCards.map((card) => card.replica));
-  const removed = [...previousReplicas].some((replica) => !currentReplicas.has(replica));
-  const contributes = rawCards.some((card) => {
-    const checkpoint = readCheckpoint(machineId(), project.repoKey);
-    const previousCard = previousCards.find((entry) => entry.replica === card.replica);
-    return hasLocalContribution(card, sharedPlan, baseline, checkpoint, previousCard);
-  });
-  if (contributes && rawCards.some((card) => hasPendingContributionObjects(card, sharedPlan))) {
+  const status = publicationStatus(project.repoKey);
+  if (!status.current) {
     service.counters.publishSkips += 1;
-    return { published: false, reason: 'objects-preparing', repoKey: project.repoKey };
+    return {
+      published: false,
+      reason: status.terminalError ? 'publication-rejected' : 'project-not-current',
+      mayMaterialize: true,
+      repoKey: project.repoKey,
+      ...status,
+    };
   }
-  if (!removed && !contributes) {
+  if (!intent) {
     service.counters.publishSkips += 1;
-    return { published: false, reason: 'shared-state-covered', repoKey: project.repoKey };
+    return {
+      published: false,
+      reason: 'shared-state-covered',
+      mayMaterialize: true,
+      repoKey: project.repoKey,
+    };
   }
-  const mutationId = `mut_project_${crypto.randomBytes(16).toString('base64url')}`;
-  const cards = stampCards(
-    rawCards,
-    previousCards,
-    sharedPlan,
-    baseline,
-    mutationId,
-    project,
-  );
-  const mine = {
-    wall: WALL_CONTRACT,
-    project: project.repoKey,
-    machine: machineId(),
-    mutationId,
-    publishedAt: new Date().toISOString(),
-    cards,
-  };
-  if (samePublishedRecord(previousEntry, mine)) {
+  if (intent.base.through !== status.appliedThrough) {
     service.counters.publishSkips += 1;
-    return { published: false, reason: 'unchanged', repoKey: project.repoKey };
+    return {
+      published: false,
+      reason: 'local-intent-refreshing',
+      mayMaterialize: true,
+      repoKey: project.repoKey,
+    };
   }
-  if (!cardsUseMutation(cards, mutationId)) {
-    service.counters.publishSkips += 1;
-    return { published: false, reason: 'no-content-change', repoKey: project.repoKey };
+  const card = intent.local.card;
+  const checkpoint = {
+    checkpoint: CHECKPOINT_CONTRACT,
+    baseOid: intent.local.checkpoint.baseOid,
+    branch: intent.local.checkpoint.branch,
+    from: null,
+    to: intent.local.checkpoint.value,
+  };
+  const snapshot = projectStream.readSnapshot(project.file, project.resourceId);
+  let delta = null;
+  if (!snapshot.card || !sameCardState(card, snapshot.card)) {
+    if (!cardPayloadsReady(card)) {
+      service.counters.publishSkips += 1;
+      return { published: false, reason: 'objects-preparing', repoKey: project.repoKey };
+    }
+    delta = cardSet(card, checkpoint);
+  } else if (checkpoint.to.revision !== snapshot.checkpoint?.value?.revision) {
+    delta = checkpointSet(card, checkpoint, snapshot.checkpoint);
   }
-  const status = publicationStatus(project.repoKey, baseline);
-  if (!status.current) {
+  if (!delta) {
+    delta = checkpointSet(card, checkpoint, snapshot.checkpoint);
+  }
+  const reserved = intents.reservePublication(project, intent);
+  if (!reserved?.publication?.mutationId) {
     service.counters.publishSkips += 1;
     return {
       published: false,
-      reason: 'project-not-current',
+      reason: 'local-intent-refreshing',
+      mayMaterialize: true,
       repoKey: project.repoKey,
-      ...status,
     };
   }
-
-  for (const card of cards) {
-    const checkpoint = (card.checkpoints || []).find((entry) => (
-      entry.machine === machineId() && entry.mutationId === mutationId
-    ));
-    if (checkpoint) {
-      stampCheckpointMutation(machineId(), project.repoKey, checkpoint, mutationId);
-    }
-  }
-  const result = projectStream.publish(project, mine);
+  const result = projectStream.publish(
+    project,
+    delta,
+    reserved.publication.mutationId,
+  );
+  stampCheckpointMutation(machineId(), project.repoKey, checkpoint, result.mutation.mutationId);
   service.counters.publishes += 1;
   service.lastPublishedAt = new Date().toISOString();
   return {
@@ -638,26 +477,36 @@ function publishProject(project, rawCards) {
     repoKey: project.repoKey,
     resourceId: project.resourceId,
     mutationId: result.mutation.mutationId,
-    cards: cards.length,
+    delta: delta.kind,
   };
 }
 
 function publishSelected(selected, allCards, publisher = publishProject) {
   return selected.map((project) => {
     try {
-      return publisher(
-        project,
-        allCards.filter((card) => (
-          repoKeyOfCard(card) === project.repoKey
-          && isCommittedCard(card)
-        )),
-      );
+      const cards = allCards.filter((card) => (
+        projectForPath(card.path)?.resourceId === project.resourceId
+        && isCommittedCard(card)
+        && card.kind === 'primary'
+        && card.health === 'healthy'
+        && card.operation === 'none'
+      ));
+      if (cards.length === 0) {
+        service.counters.publishSkips += 1;
+        return {
+          published: false,
+          reason: 'local-checkout-unavailable',
+          repoKey: project.repoKey,
+        };
+      }
+      return publisher(project, cards);
     } catch (error) {
       service.counters.publishFailures += 1;
       console.warn(`[CodeProject] ${project.repoKey} publish failed:`, error.message);
       return {
         published: false,
         reason: 'publish-failed',
+        terminalError: error.message,
         repoKey: project.repoKey,
         error: error.message,
       };
@@ -705,9 +554,11 @@ async function ensureProject(project) {
   const attachments = require('../state/attachments');
   const promotions = require('../state/promotions');
   fs.mkdirSync(path.dirname(project.file), { recursive: true });
-  if (!fs.existsSync(project.file)) fs.writeFileSync(project.file, '');
+  if (!fs.existsSync(project.file)) {
+    projectStream.writeSnapshot(project.file, projectStream.emptySnapshot(project.resourceId));
+  }
 
-  let request = attachments.getAttachmentByResource(project.resourceId);
+  const request = attachments.getAttachmentByResource(project.resourceId);
   if (!request) {
     await callLocal(shared.handleAttachmentStart, {
       resourceId: project.resourceId,
@@ -715,21 +566,26 @@ async function ensureProject(project) {
       contract: projectStream.STREAM_CONTRACT,
     });
   } else if (request.state === 'rejected') {
+    let promotion = promotions.getPromotionByResource(project.resourceId);
     if (
       ATTACH_REJECTED.test(request.lastError || '')
-      && project.resourceId === projectResourceId(project.repoKey, userId())
-      && !promotions.getPromotionByResource(project.resourceId)
+      && project.ownerUserId === userId()
+      && !promotion
     ) {
       await callLocal(shared.handlePromotionStart, {
         resourceId: project.resourceId,
         path: project.file,
-        project: project.repoKey,
         contract: projectStream.STREAM_CONTRACT,
-        schemaVersion: 1,
+        schemaVersion: 2,
       });
-      await waitForSettled(project, () => promotions.getPromotionByResource(project.resourceId));
+      promotion = await waitForSettled(
+        project,
+        () => promotions.getPromotionByResource(project.resourceId),
+      );
+    }
+    if (!wallReplica(project) && promotion?.state === 'promoted') {
+      attachments.retryAttachment(project.resourceId);
     }
-    if (!wallReplica(project)) attachments.retryAttachment(project.resourceId);
   }
   await waitForSettled(project, () => attachments.getAttachmentByResource(project.resourceId));
   if (wallReplica(project)) schedulePublish();
@@ -770,17 +626,12 @@ function startWallService() {
   if (service.started) return;
   service.started = true;
   service.unsubscribe = subscribeStateEvents((event) => {
-    const acknowledgedProject = event.resource === 'shared-mutations'
-      ? projects().find((project) => project.resourceId === event.sharedResourceId)
-      : null;
-    if (acknowledgedProject) {
-      projectStream.seal(acknowledgedProject, event.mutationId || event.id, event.resourceVersion);
-    }
     if (
       event.resource === 'repo-cards'
       || event.resource === 'repo-checkpoints'
       || event.resource === 'repo-objects'
-      || acknowledgedProject
+      || event.resource === 'shared-mutations'
+      || String(event.resource || '').startsWith(projectStream.LOCAL_RESOURCE_PREFIX)
     ) {
       ensureProjects().catch(() => {});
       schedulePublish();
@@ -809,6 +660,7 @@ function stopWallService() {
 function wallStats() {
   const rows = projects().map((project) => {
     const replica = wallReplica(project);
+    const snapshot = projectStream.readSnapshot(project.file, project.resourceId);
     return {
       repoKey: project.repoKey,
       resourceId: project.resourceId,
@@ -822,7 +674,7 @@ function wallStats() {
         lastError: replica.lastError,
         updatedAt: replica.updatedAt,
       },
-      machines: readProjectWall(project).length,
+      version: snapshot.version,
     };
   });
   return {
@@ -838,24 +690,27 @@ function wallStats() {
 
 module.exports = {
   _test: {
-    cardsUseMutation,
+    cardPayloadsReady,
+    checkpointForCard,
     hasPendingContributionObjects,
+    ensureProject,
+    outboundState,
+    publishProject,
     publishSelected,
-    samePublishedRecord,
+    sameCardState,
   },
   WALL_CONTRACT,
   bindProject,
   hasLocalContribution,
   isCommittedCard,
-  mutationVersion,
   projectFile,
+  projectForPath,
   projectForRepo,
-  projectResourceId,
+  projectForResource,
   publicationStatus,
   publishedCardFor,
   publishWall,
   readWall,
-  stampCards,
   startWallService,
   stopWallService,
   wallStats,