amalgm 0.1.245 → 0.1.246

package/runtime/scripts/amalgm-mcp/adapters/contract.js

@@ -0,0 +1,197 @@
+'use strict';
+
+/**
+ * The adapter contract: what it means to serve an entity type.
+ *
+ * An adapter is how a KIND of entity rides the seven realtime rails —
+ * watch, detect, record, send, receive, apply, verify
+ * (docs/realtime-rails.md §2). The entity's `type` selects its adapter;
+ * the rails themselves never change shape per type.
+ *
+ * Axioms:
+ *
+ *  1. ONE ADAPTER PER TYPE, EVERY TYPE ASSIGNED. The alphabet belongs
+ *     to the registry (`ENTITY_TYPES`); the adapter map covers it
+ *     exactly — no type unassigned, no type claimed twice. Adapters
+ *     read the alphabet, never restate it, so the map cannot drift
+ *     from the registry that enforces it. Assigned is not yet
+ *     operational: operational is earned rail by rail, and absence is
+ *     honest.
+ *
+ *  2. ADAPTERS OWN BEHAVIOR; THE REGISTRY OWNS IDENTITY. An adapter
+ *     decides how truth is read and applied — never which UUID it
+ *     belongs to. A lawful type transition that crosses adapters
+ *     (folder becoming repo.git) is a handoff on the same UUID, never
+ *     a rebirth; and the kinds that transition into one another on a
+ *     single piece of ground (file ↔ link) live inside ONE adapter,
+ *     so their transitions never even change hands.
+ *
+ *  3. ONE SOCKET PER RAIL. A rail's callable surfaces — their names
+ *     and their shapes — are ratified HERE, once, for every adapter
+ *     (`SOCKETS`). A generic caller performs the same conceptual
+ *     operation through the same call on every type; it never branches
+ *     on an adapter-specific function name. An adapter binds a rail's
+ *     whole socket or binds the rail not at all; a rail whose socket
+ *     is not yet ratified cannot be bound by anyone. The sockets are
+ *     derived from the real consumer — the registration boundary and
+ *     its evidence lenses — never invented ahead of one, and never for
+ *     symmetry (axiom 7 decides which rails earn one at all).
+ *
+ *  4. A TRUTH READ NEVER LIES. Every assigned type names its source of
+ *     truth in one sentence, and reading it produces exactly one of
+ *     three honest answers: PRESENT (the complete truth behind a
+ *     version — equal versions mean equal truth, and equal truth is
+ *     silence), ABSENT (the ground genuinely is not there — a fact,
+ *     not an error), or UNSETTLED (changing or unreadable right now;
+ *     read again). Partial truth is never passed off as complete, and
+ *     nothing is silently omitted — a read is complete or it is
+ *     unsettled.
+ *
+ *  5. RAILS ARE HONEST. A rail an adapter binds is built and proven;
+ *     an unbound rail is absent — never stubbed, never defaulted, so
+ *     nothing downstream can mistake a placeholder for a capability.
+ *
+ *  6. THE CONTRACT IS FROZEN GROUND. A descriptor is immutable from
+ *     the moment it loads; behavior changes by shipping a new adapter,
+ *     never by mutating a live one.
+ *
+ *  7. THE BASE ORCHESTRATES; THE ADAPTER SUPPLIES TYPE BEHAVIOR. The
+ *     universal machinery owns orchestration and identity: what is
+ *     enrolled, when work happens, retries, routing, and which UUID
+ *     owns the result. An adapter supplies only the type-specific
+ *     behavior a real rail requires. A rail therefore earns a socket
+ *     only when a real consumer proves that behavior differs by type —
+ *     never for symmetry. Behavior that survives an adapter handoff
+ *     unchanged was never that adapter's behavior.
+ */
+
+const RAILS = Object.freeze([
+  'watch', 'detect', 'record', 'send', 'receive', 'apply', 'verify',
+]);
+
+/**
+ * The ratified sockets — for each rail that has one, the exact surfaces
+ * every binding adapter implements. Same names, same shapes, every
+ * type. ONE socket is ratified today, derived from what production
+ * detection actually asks of a type (the observer's content decision,
+ * the registration boundary's lenses): read the current truth and
+ * compare — equal truth is silence.
+ *
+ *   detect.truth(path) →
+ *     { truth: 'present', version, state }   the complete current
+ *       truth, fingerprinted — equal versions mean equal truth
+ *     { truth: 'absent' }                    the ground genuinely is
+ *       not there — a fact, not an error
+ *     { truth: 'unsettled', reason }         changing or unreadable
+ *       right now; read again — never a partial answer
+ *
+ * No other rail has a socket, and WATCH AND RECORD EARN NONE AT THIS
+ * BAR — adjudicated 2026-08-03 under axiom 7, on the filesystem
+ * alphabet we actually serve. The observer's doorbell is chosen by
+ * physical shape (one piece of ground watches its parent; a tree
+ * watches itself): identical for a folder and a repo, which are
+ * different adapters; different inside one adapter's own types; and
+ * untouched when a live root crosses `files` ↔ `repo` on the same
+ * UUID. It survives the adapter handoff, so it was never adapter
+ * behavior. Record is the registry's by axiom 2 — identity,
+ * hierarchy, versions, lifecycle. A type whose truth is NOT filesystem
+ * ground — an API, a database — would be new evidence, and axiom 7
+ * decides it then, on that consumer, exactly as it decided this one.
+ *
+ * Apply and verify remain what they are today: proven MODULE surfaces
+ * (repocard's materialize-and-prove and re-read-and-compare), joining
+ * the contract only when a real multi-type consumer — the
+ * Send/Receive rails — exists to derive their socket from, by the same
+ * law that made detect's. Send is where the next socket is expected,
+ * because there the cargo itself differs by type: bytes, membership,
+ * written target, repository state. A socket is ratified from a real
+ * consumer or it is not ratified at all.
+ */
+const SOCKETS = Object.freeze({
+  detect: Object.freeze(['truth']),
+});
+
+/**
+ * Convict a malformed adapter descriptor loudly; return it unchanged
+ * when lawful. The shape is deliberately tiny:
+ *
+ *   name   — the adapter's one name
+ *   types  — { entityType: 'one-sentence source of truth', ... }
+ *   rails  — { railName: { socket surfaces, complete }, ... } — only
+ *            rails whose ratified socket the adapter fully implements
+ */
+function assertAdapter(adapter) {
+  const where = adapter && adapter.name ? `adapter ${JSON.stringify(adapter.name)}` : 'adapter';
+  if (!adapter || typeof adapter !== 'object' || !Object.isFrozen(adapter)) {
+    throw new Error(`${where}: a descriptor is a frozen object`);
+  }
+  if (typeof adapter.name !== 'string' || adapter.name.length === 0) {
+    throw new Error('adapter: name is a non-empty string');
+  }
+  const { types, rails } = adapter;
+  if (!types || typeof types !== 'object' || !Object.isFrozen(types) || Object.keys(types).length === 0) {
+    throw new Error(`${where}: types is a frozen, non-empty map of entity type → declared truth`);
+  }
+  for (const [type, truth] of Object.entries(types)) {
+    if (typeof truth !== 'string' || truth.length === 0) {
+      throw new Error(`${where}: type ${JSON.stringify(type)} must declare its source of truth in one sentence`);
+    }
+  }
+  if (!rails || typeof rails !== 'object' || !Object.isFrozen(rails)) {
+    throw new Error(`${where}: rails is a frozen map (empty is honest; a stub is not)`);
+  }
+  for (const [rail, surfaces] of Object.entries(rails)) {
+    if (!RAILS.includes(rail)) {
+      throw new Error(`${where}: ${JSON.stringify(rail)} is not a rail — the rails are ${RAILS.join(', ')}`);
+    }
+    const socket = SOCKETS[rail];
+    if (!socket) {
+      throw new Error(`${where}: rail ${rail} has no ratified socket yet — a socket is ratified in the contract before anyone binds it`);
+    }
+    if (!surfaces || typeof surfaces !== 'object' || !Object.isFrozen(surfaces)) {
+      throw new Error(`${where}: rail ${rail} must bind a frozen map of its socket's surfaces`);
+    }
+    const bound = Object.keys(surfaces).sort();
+    if (bound.join(',') !== [...socket].sort().join(',')) {
+      throw new Error(`${where}: rail ${rail} binds [${bound.join(', ')}] but its socket is [${socket.join(', ')}] — an adapter implements a rail's whole socket or binds the rail not at all`);
+    }
+    for (const [surface, fn] of Object.entries(surfaces)) {
+      if (typeof fn !== 'function') {
+        throw new Error(`${where}: ${rail}.${surface} must be a function — an unbuilt surface is left absent, never stubbed`);
+      }
+    }
+  }
+  return adapter;
+}
+
+/**
+ * Build the one type → adapter map, convicting every violation of
+ * axiom 1: an adapter claiming a type outside the alphabet, two
+ * adapters claiming one type, or an alphabet type left unassigned.
+ * Pure — callers own where the alphabet and adapters come from.
+ */
+function buildTypeMap(adapters, alphabet) {
+  const known = new Set(alphabet);
+  const byType = new Map();
+  for (const adapter of adapters) {
+    assertAdapter(adapter);
+    for (const type of Object.keys(adapter.types)) {
+      if (!known.has(type)) {
+        throw new Error(`adapter ${adapter.name} claims ${JSON.stringify(type)}, which is not in the registry's alphabet`);
+      }
+      const holder = byType.get(type);
+      if (holder) {
+        throw new Error(`entity type ${JSON.stringify(type)} is claimed by both ${holder.name} and ${adapter.name} — one adapter per type`);
+      }
+      byType.set(type, adapter);
+    }
+  }
+  for (const type of known) {
+    if (!byType.has(type)) {
+      throw new Error(`entity type ${JSON.stringify(type)} has no adapter — every type is assigned`);
+    }
+  }
+  return byType;
+}
+
+module.exports = { RAILS, SOCKETS, assertAdapter, buildTypeMap };

package/runtime/scripts/amalgm-mcp/adapters/filesystem.js

@@ -0,0 +1,135 @@
+'use strict';
+
+/**
+ * The filesystem adapter: every kind whose truth IS ordinary filesystem
+ * ground — folders, files, symlinks — served by ONE adapter on purpose.
+ * These kinds transition into one another on the same UUID (a file
+ * becomes a link on the same slot, text becomes binary, a workspace
+ * sheds to folder on adoption), and one adapter means those transitions
+ * never cross a behavioral boundary where identity could be fumbled.
+ *
+ * Constructs — agents, apps, automations, tools, skills — are NOT
+ * types here or anywhere: physically they are folders and files with a
+ * known structure, served by this adapter like any other ground, and
+ * their construct meaning is layered above the physical type. If one
+ * ever truly travels or applies differently, promoting it is a
+ * deliberate future ratification — never a default.
+ *
+ * One rail bound: detect, through the ratified socket, and production
+ * consumes it — the observer's content reads (observer/index.js
+ * scanContent and safeContent) speak through this exact function. The
+ * content primitive lives HERE: one detector, owned by the adapter, and
+ * the dependency points one way — the observer reads truth through the
+ * socket, never the other way around. Watch and record stay
+ * orchestrated in the observer until their sockets are ratified from
+ * that seam; apply and verify for filesystem ground ride the cloud
+ * rails. All honestly absent.
+ */
+
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+
+const { lookFailed } = require('./truth');
+
+/**
+ * A file's bytes, read ONCE, answering both questions they support:
+ * their sha256 and whether any of them is a NUL. A hash and a type that
+ * came from different reads can disagree — the file may change between
+ * them — and a type is a claim ABOUT the bytes behind the hash, so the
+ * two are one answer or they are not honest. Streaming, so large files
+ * never load whole into memory; the NUL is looked for chunk by chunk.
+ */
+function readFile(absPath) {
+  const hash = crypto.createHash('sha256');
+  let binary = false;
+  const fd = fs.openSync(absPath, 'r');
+  try {
+    const buffer = Buffer.allocUnsafe(1 << 20);
+    let read;
+    while ((read = fs.readSync(fd, buffer, 0, buffer.length)) > 0) {
+      const chunk = buffer.subarray(0, read);
+      hash.update(chunk);
+      if (!binary && chunk.includes(0)) binary = true;
+    }
+  } finally {
+    fs.closeSync(fd);
+  }
+  return { sha256: hash.digest('hex'), binary };
+}
+
+const present = (parts, state) => ({
+  truth: 'present',
+  version: crypto.createHash('sha256').update(JSON.stringify(parts)).digest('hex'),
+  state,
+});
+
+const KIND = (stat) => (stat.isSymbolicLink() ? 'link' : stat.isDirectory() ? 'dir' : 'file');
+
+/**
+ * The detect socket: the ground's whole current truth, by its physical
+ * kind — the caller never says which kind it expects, disk decides
+ * (exactly how a file becomes a link on the same slot without anyone
+ * branching).
+ *
+ *   link   → its written target text, exactly as disk holds it
+ *   dir    → its direct membership: sorted names with their kinds
+ *            (folder truth is membership; content belongs to members)
+ *   file   → its bytes, as a streaming sha256, plus whether any of
+ *            those same bytes is a NUL — one read, so the fingerprint
+ *            and the text/bytes claim can never describe different ground
+ *
+ * Three honest answers, never a fourth: ground that is not there is
+ * ABSENT — a fact, not an error — and ground that moved between looks
+ * or refuses to be read completely is UNSETTLED: the whole read
+ * succeeds or the whole read says "read again"; a member is never
+ * silently dropped from a membership that claims to be complete.
+ *
+ * Physical truth only: enrollment policy — what deserves to be shared —
+ * is the caller's injected question, asked before this one.
+ */
+function truth(absPath) {
+  let stat;
+  try {
+    stat = fs.lstatSync(absPath);
+  } catch (error) {
+    return lookFailed(error);
+  }
+  const kind = KIND(stat);
+  try {
+    if (kind === 'link') {
+      const target = fs.readlinkSync(absPath);
+      return present(['link', target], { kind, target });
+    }
+    if (kind === 'dir') {
+      const members = fs.readdirSync(absPath).sort().map((name) => ({
+        name, kind: KIND(fs.lstatSync(path.join(absPath, name))),
+      }));
+      return present(['dir', members], { kind, members });
+    }
+    // `binary` rides the state but NOT the version: it is derived from
+    // the very bytes the sha256 fingerprints, so it can never vary
+    // while the hash holds. Adding it would fingerprint the same fact twice.
+    const { sha256, binary } = readFile(absPath);
+    return present(['file', sha256], { kind, sha256, binary });
+  } catch (error) {
+    // The ground changed between looks: a complete read was impossible.
+    return { truth: 'unsettled', reason: error.code ?? 'changed-mid-read' };
+  }
+}
+
+module.exports = Object.freeze({
+  name: 'filesystem',
+
+  types: Object.freeze({
+    workspace: 'its active direct membership — folder truth; the collaboration boundary it marks is authority meaning, layered above detection',
+    folder: 'its active direct membership',
+    'file.text': 'its bytes',
+    'file.binary': 'its bytes',
+    link: 'its written target text — the literal address, never what it resolves to',
+  }),
+
+  rails: Object.freeze({
+    detect: Object.freeze({ truth }),
+  }),
+});

package/runtime/scripts/amalgm-mcp/adapters/git.js

@@ -0,0 +1,84 @@
+'use strict';
+
+/**
+ * The Git adapter: a repository is ONE entity — its committed state
+ * (the card) plus its working checkpoint — never thousands of unrelated
+ * files. One logical operation (a checkout, a rebase) is one change on
+ * one UUID, not meaningless bulk churn.
+ *
+ * One rail bound: detect, through the ratified socket. Truth
+ * translates repocard's proven capture into the three-state answer:
+ * ground with no repository on it is ABSENT (a vanished .git is how a
+ * repository leaves an address — the territory law), a repo caught
+ * mid-operation is UNSETTLED (capture's busy markers — MERGE_HEAD, an
+ * active rebase — mean the truth is changing under the read), and a
+ * present truth's version is the stateId: one fingerprint over cardId
+ * and checkpointId. Detection's truth is deliberately bundle-free:
+ * comparing is constant work and packing is neither cheap nor
+ * deterministic, so the TRANSPORTED head — card with its bundle of
+ * objects — is the Send rail's packaging act, not detect's.
+ *
+ * Repocard's apply and verify remain proven MODULE surfaces
+ * (materialize-and-prove, re-read-and-compare); they join the contract
+ * when a real multi-type Apply consumer — the Send/Receive rails —
+ * exists to derive their socket from. Watching a repo (the follower,
+ * the capture worker) stays orchestrated by the observer until the
+ * watch socket is ratified from that seam.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const { capture } = require('../repocard');
+const { lookFailed } = require('./truth');
+
+/** The detect socket over capture: same call, same shape as every type. */
+function truth(repoPath) {
+  try {
+    fs.lstatSync(repoPath);
+  } catch (error) {
+    return lookFailed(error);
+  }
+  // No .git (directory or worktree file) means no repository holds this
+  // ground: the REPOSITORY is absent, whatever else stands at the path.
+  // The look is error-preserving: a .git that cannot be inspected still
+  // exists — that read is unsettled, never absence.
+  try {
+    fs.lstatSync(path.join(repoPath, '.git'));
+  } catch (error) {
+    return lookFailed(error);
+  }
+  let captured;
+  try {
+    captured = capture(repoPath, { withBundle: false });
+  } catch (error) {
+    // A git subprocess that failed is a repository that could not be
+    // inspected — unsettled, never a fourth answer. Only failures git
+    // itself reported are classified; a programming error propagates.
+    if (!error.gitFailed) throw error;
+    return { truth: 'unsettled', reason: error.gitFailed };
+  }
+  if (captured.busy) return { truth: 'unsettled', reason: captured.busy };
+  return {
+    truth: 'present',
+    version: captured.stateId,
+    state: {
+      card: captured.card,
+      checkpoint: captured.checkpoint,
+      cardId: captured.cardId,
+      checkpointId: captured.checkpointId,
+    },
+  };
+}
+
+module.exports = Object.freeze({
+  name: 'git',
+
+  types: Object.freeze({
+    'repo.git': 'its card — the committed state — plus its working checkpoint',
+  }),
+
+  rails: Object.freeze({
+    detect: Object.freeze({ truth }),
+  }),
+});

package/runtime/scripts/amalgm-mcp/adapters/index.js

@@ -0,0 +1,43 @@
+'use strict';
+
+/**
+ * The adapter layer's one door. Three adapters cover the registry's
+ * whole physical alphabet:
+ *
+ *   filesystem — workspace, folder, file.text, file.binary, link:
+ *                ordinary filesystem ground, one adapter so same-ground
+ *                type transitions never change hands (constructs —
+ *                agents, automations, and kin — are this ground too,
+ *                their meaning layered above the physical type)
+ *   git        — repo.git: card + checkpoint as one entity
+ *   reference  — reference: a UUID-targeting managed link (assigned,
+ *                not yet operational)
+ *
+ * The map is built against the registry's published alphabet at load —
+ * an unassigned type, a double claim, or a type the registry doesn't
+ * know refuses to load at all, so a drifted map cannot exist at
+ * runtime. A generic caller selects with `adapterFor(type)` and speaks
+ * only the ratified sockets — the same calls for every type, never an
+ * adapter-specific name. Every surface — SDK, CLI, MCP, REST — reaches
+ * type behavior through this door; none re-implements it.
+ */
+
+const { ENTITY_TYPES } = require('../registry');
+const { RAILS, SOCKETS, assertAdapter, buildTypeMap } = require('./contract');
+const filesystem = require('./filesystem');
+const git = require('./git');
+const reference = require('./reference');
+
+const ADAPTERS = Object.freeze([filesystem, git, reference]);
+const byType = buildTypeMap(ADAPTERS, ENTITY_TYPES);
+
+/** The one selection: entity type → its adapter. Unknown types convict. */
+function adapterFor(type) {
+  const adapter = byType.get(type);
+  if (!adapter) {
+    throw new Error(`no adapter serves entity type ${JSON.stringify(type)} — the alphabet is ${ENTITY_TYPES.join(', ')}`);
+  }
+  return adapter;
+}
+
+module.exports = { ADAPTERS, RAILS, SOCKETS, adapterFor, assertAdapter, buildTypeMap };

package/runtime/scripts/amalgm-mcp/adapters/reference.js

@@ -0,0 +1,31 @@
+'use strict';
+
+/**
+ * The managed-reference adapter: Amalgm's OWN link kind, never conflated
+ * with a filesystem symlink. Its payload is the target entity's UUID —
+ * identity, not an address — and its local rendering as an ordinary
+ * symlink is DERIVED state: canonical-truth-projected on every boundary
+ * pass, missing renderings recreated, drifted ones rewritten, real
+ * ground on the slot never overwritten, dangling honestly while the
+ * target is unavailable.
+ *
+ * ASSIGNED, NOT YET OPERATIONAL — and that absence is the honest
+ * truth: no rail is bound because the projection lives inside the
+ * registration boundary today (registration/index.js maintains
+ * renderings as part of every pass), proven by the wall but not yet
+ * standing as socket surfaces. A reference's truth is registry
+ * identity, not disk — its detect socket is ratified from that seam
+ * when the boundary's projection is extracted, never invented ahead
+ * of it. Send-side resolution of the target UUID on other machines
+ * rides the cloud rails.
+ */
+
+module.exports = Object.freeze({
+  name: 'reference',
+
+  types: Object.freeze({
+    reference: "its target entity's UUID — identity, not an address; the rendered symlink is derived state",
+  }),
+
+  rails: Object.freeze({}),
+});

package/runtime/scripts/amalgm-mcp/adapters/truth.js

@@ -0,0 +1,19 @@
+'use strict';
+
+/**
+ * The three-state vocabulary's one shared judgment: what a FAILED look
+ * at ground means. ENOENT and ENOTDIR are the filesystem itself saying
+ * "not there" — honest ABSENCE, a fact. Every other failure means the
+ * LOOK failed, not the ground — UNSETTLED: no conclusion, read again.
+ *
+ * Every truth reader classifies through this one function so no reader
+ * can invent its own idea of absence: mistaking "could not look" for
+ * "not there" is the exact lie the axiom forbids. Only present or
+ * absent may produce a conclusion.
+ */
+const lookFailed = (error) =>
+  error.code === 'ENOENT' || error.code === 'ENOTDIR'
+    ? { truth: 'absent' }
+    : { truth: 'unsettled', reason: error.code };
+
+module.exports = { lookFailed };

package/runtime/scripts/amalgm-mcp/browser/cookie-jar.js

@@ -599,26 +599,18 @@ function getCookieCloudBootstrap(options = {}) {
 
 function installCookieCloudBootstrap(input = {}, options = {}) {
   const database = options.database || require('../state/db').openLocalDb();
-  const replicas = require('../state/replicas');
-  const envelope = replicas.validateSnapshotEnvelope(input, {
-    contract: COOKIE_CLOUD_CONTRACT,
-    schemaVersion: COOKIE_JAR_SCHEMA_VERSION,
-  });
-  const expectedResourceId = privateCookieResourceId(
-    require('../workspace/identity').userId(),
-  );
-  if (!expectedResourceId || envelope.resourceId !== expectedResourceId) {
+  const replica = cookieCloudReplica({ database });
+  if (!replica || input.resourceId !== replica.resourceId) {
     throw new Error('Private cookie resource does not belong to this runtime user');
   }
+  if (input.contract !== COOKIE_CLOUD_CONTRACT || Number(input.schemaVersion) !== COOKIE_JAR_SCHEMA_VERSION) {
+    throw new Error('Private cookie resource contract changed');
+  }
   const bytes = Buffer.from(String(input.snapshotBase64 || ''), 'base64');
   const checksum = crypto.createHash('sha256').update(bytes).digest('hex');
   if (checksum !== input.snapshotChecksum) throw new Error('Private cookie snapshot checksum mismatch');
   const local = loadInternalCookieJar();
   const remote = normalizeCloudSnapshot(JSON.parse(bytes.toString('utf8')));
-  if (remote.version !== envelope.snapshotVersion) {
-    throw new Error('Private cookie snapshot version mismatch');
-  }
-  const replica = cookieCloudReplica({ database });
   const pending = require('../state/mutations').listPendingCloudMutations(replica.resourceId, { database });
   const pendingKeys = new Set(pending.map((mutation) => mutation.operation?.key).filter(Boolean));
   // A base snapshot behind the official head is not the current cloud jar.
@@ -626,62 +618,28 @@ function installCookieCloudBootstrap(input = {}, options = {}) {
   // as pre-cloud work and create an echo loop on every reconnect. The gateway
   // normally compacts private resources to head before bootstrap; this guard
   // makes the runtime fail closed if an older gateway sends a stale base.
-  const snapshotIsCurrent = envelope.snapshotVersion === envelope.headVersion;
+  const snapshotIsCurrent = Number(input.snapshotVersion) >= Number(input.headVersion);
   const bootstrapOperations = snapshotIsCurrent
     ? localBootstrapOperations(local, remote, pendingKeys)
     : [];
 
-  if (!snapshotIsCurrent) {
-    // A stale prefix is useful only as an identity check for a prefix this
-    // machine has already applied. Advancing to a newer stale prefix without
-    // installing its bytes would make the cursor lie; installing it would
-    // overwrite local legacy state before a head snapshot can classify it.
-    const currentReplica = replicas.refreshReplicaAuthority({
-      resourceId: replica.resourceId,
-      authorityEpoch: envelope.authorityEpoch,
-      headVersion: envelope.headVersion,
-      contract: COOKIE_CLOUD_CONTRACT,
-      schemaVersion: COOKIE_JAR_SCHEMA_VERSION,
-    }, { database });
-    return {
-      replica: currentReplica,
-      jar: readCookieJar(),
-      bootstrappedMutations: 0,
-      bootstrapDeferred: true,
-    };
-  }
-
-  // Legacy local values become durable mutations before the official
-  // snapshot can replace the physical jar. If the process dies after the
-  // replacement, restart can replay these rows; in-memory bootstrapOperations
-  // are never the only copy of user state.
-  let currentReplica = replica;
-  for (const operation of bootstrapOperations) {
-    commitCookieOperation(operation, currentReplica, { database });
-    currentReplica = cookieCloudReplica({ database });
-  }
-  const durablePending = require('../state/mutations')
-    .listPendingCloudMutations(replica.resourceId, { database });
-
   persistCloudSnapshot({
     schemaVersion: COOKIE_JAR_SCHEMA_VERSION,
     version: remote.version,
     records: [...remote.records.values()],
     tombstones: [...remote.tombstones.values()],
   });
-  if (options.testHooks?.crashAfterSnapshotPersist === true) {
-    throw new Error('simulated cookie bootstrap crash after snapshot persist');
-  }
-  replicas.advanceReplicaSnapshot({
-      resourceId: replica.resourceId,
-      snapshotVersion: envelope.snapshotVersion,
-      snapshotChecksum: checksum,
-      authorityEpoch: envelope.authorityEpoch,
+  const { advanceReplicaSnapshot, refreshReplicaAuthority } = require('../state/replicas');
+  advanceReplicaSnapshot({
+    resourceId: replica.resourceId,
+    snapshotVersion: Number(input.snapshotVersion) || 0,
+    snapshotChecksum: checksum,
+    authorityEpoch: Number(input.authorityEpoch) || 1,
   }, { database });
-  replicas.refreshReplicaAuthority({
+  refreshReplicaAuthority({
     resourceId: replica.resourceId,
-    authorityEpoch: envelope.authorityEpoch,
-    headVersion: envelope.headVersion,
+    authorityEpoch: Number(input.authorityEpoch) || 1,
+    headVersion: Number(input.headVersion) || 0,
     contract: COOKIE_CLOUD_CONTRACT,
     schemaVersion: COOKIE_JAR_SCHEMA_VERSION,
   }, { database });
@@ -689,18 +647,12 @@ function installCookieCloudBootstrap(input = {}, options = {}) {
   // Snapshot installation never discards local work. Already-journaled edits
   // replay from their durable rows; pre-cloud legacy entries become ordinary
   // new mutations through the same commit path.
-  for (const mutation of durablePending) {
-    materializeCookieOperation(mutation.operation);
-    if (mutation.state === 'saving-local' && mutation.materializedAt === null) {
-      require('../state/mutations').completeMaterializedMutation(
-        mutation.channelId,
-        mutation.mutationId,
-        cookieEvent(mutation.operation, mutation.mutationId),
-        { database },
-      );
-    }
+  for (const mutation of pending) materializeCookieOperation(mutation.operation);
+  let currentReplica = cookieCloudReplica({ database });
+  for (const operation of bootstrapOperations) {
+    commitCookieOperation(operation, currentReplica, { database });
+    currentReplica = cookieCloudReplica({ database });
   }
-  currentReplica = cookieCloudReplica({ database });
   return {
     replica: currentReplica,
     jar: readCookieJar(),

package/runtime/scripts/amalgm-mcp/index.js

@@ -127,6 +127,10 @@ async function boot() {
   ensureAppsDirs();
   startProjectContextService();
 
+  // The authenticated tunnel coordinates user-home bootstrap after it asks
+  // the gateway whether this user already has a cloud UUID graph. Runtime
+  // startup must not mint a competing graph before that answer arrives.
+
   require('./state/ports').startPortsBridge();
   require('./workspace/cards').startRepoCardService();
   require('./workspace/tree-store').startTreeEnrollmentService();