amalgm 0.1.249 → 0.1.251

package/lib/cli.js

@@ -1456,6 +1456,8 @@ async function register(positionals) {
   const targets = (positionals.length > 0 ? positionals : [process.cwd()])
     .map((target) => path.resolve(target));
 
+  console.log(`Registering ${targets.length === 1 ? targets[0] : `${targets.length} locations`}…`);
+
   // A resolved port is not a running runtime — the manifest supplies a
   // default whether or not anything listens — so both "no port for this
   // scope" and "nothing answered" mean the same thing to the user.
@@ -1487,6 +1489,8 @@ async function register(positionals) {
     const target = targets[index];
     console.log(`Registered ${rootPath}`);
     console.log(`  ${record.type}  ${record.uuid}`);
+    console.log('  Watching: on');
+    console.log('  Cloud: queued');
     if (rootPath !== target) console.log(`  (${target} is already covered by this tree)`);
   }
 }
@@ -1504,6 +1508,7 @@ async function add(positionals) {
     throw new Error('amalgm add requires a cloud entity UUID');
   }
   const targetPath = path.resolve(positionals[1] || process.cwd());
+  console.log(`Adding ${uuid} to ${targetPath}…`);
   const port = servicePorts().find(([name]) => name === 'amalgm-mcp')?.[1];
   let answer = null;
   if (port) {
@@ -1539,6 +1544,9 @@ async function add(positionals) {
     return;
   }
   let job = answer.payload;
+  if (job?.state === 'waiting_for_content' || job?.state === 'materializing') {
+    console.log('  Downloading cloud content…');
+  }
   const deadline = Date.now() + 120_000;
   while (job?.state === 'waiting_for_content' || job?.state === 'materializing') {
     if (Date.now() > deadline) {
@@ -1555,6 +1563,8 @@ async function add(positionals) {
     return;
   }
   console.log(`Added ${job.entityUuid} to ${job.targetPath}`);
+  console.log('  Watching: on');
+  console.log('  Cloud: live');
 }
 
 /** POST JSON to a local runtime service, carrying the runtime token. */

package/lib/runtime-identity.js

@@ -50,7 +50,10 @@ function runtimeBranchForLabel(label, env = process.env) {
 }
 
 function npmTagForRuntimeLabel(label) {
-  return label === 'preview' ? 'canary' : 'latest';
+  // Releases are promoted deliberately to `main`; `latest` is retained as
+  // the public compatibility channel and may therefore lag the runtime we
+  // boot. A main installation must update from the channel it actually runs.
+  return label === 'preview' ? 'canary' : 'main';
 }
 
 function sanitizeScopeSegment(value, fallback = 'local') {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "amalgm",
-  "version": "0.1.249",
+  "version": "0.1.251",
   "description": "Amalgm local computer runtime: login, MCP, chat, events, previews, and tunnels.",
   "license": "UNLICENSED",
   "private": false,

package/runtime/scripts/amalgm-mcp/registration/entity-cloud.js

@@ -14,6 +14,8 @@ const crypto = require('crypto');
 const ENTITY_CLOUD_CONTRACT = 'amalgm-entity-registry@1';
 const ENTITY_CLOUD_SCHEMA_VERSION = 1;
 const BOOTSTRAP_RECONCILIATION_STATE = 'reconciling-bootstrap';
+const SNAPSHOT_REPLACE_OPERATION = 'entity.snapshot.replace';
+const SNAPSHOT_REPLACE_MAX_BYTES = 8 * 1024 * 1024;
 const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
 const TYPES = new Set([
   'workspace', 'folder', 'repo.git', 'file.text', 'file.binary', 'link', 'reference',
@@ -57,12 +59,21 @@ function assertRecord(value) {
     || typeof value.name !== 'string' || !value.name || value.name.includes('/') || value.name.includes('\0')
     || !['active', 'trashed', 'deleted'].includes(value.status)
     || typeof value.version !== 'string' || !/^[0-9a-f]{64}$/.test(value.version)
-    || (value.payloadVersion !== null && typeof value.payloadVersion !== 'string')) {
+    || (value.payloadVersion !== null && typeof value.payloadVersion !== 'string')
+    || (value.transportVersion !== undefined && value.transportVersion !== null
+      && (typeof value.transportVersion !== 'string' || !CONTENT_HEAD.test(value.transportVersion)))) {
     throw new Error('cloud entity snapshot has an invalid record');
   }
   if (value.parentUUID === null && !ROOT_TYPES.has(value.type)) {
     throw new Error(`cloud entity ${value.uuid} is not a valid tree root`);
   }
+  const transportVersion = value.transportVersion ?? null;
+  if (value.type === 'repo.git' && transportVersion !== null && !CONTENT_HEAD.test(transportVersion)) {
+    throw new Error('cloud repository transport head is invalid');
+  }
+  if (value.type !== 'repo.git' && transportVersion !== null) {
+    throw new Error('only repository entities may declare a transport head');
+  }
   return {
     uuid: value.uuid.toLowerCase(),
     type: value.type,
@@ -71,6 +82,7 @@ function assertRecord(value) {
     status: value.status,
     version: value.version,
     payloadVersion: value.payloadVersion,
+    transportVersion,
   };
 }
 
@@ -106,26 +118,48 @@ function parseSnapshot(bytes) {
  * no watcher imports: a cloud record may be known on this machine long before
  * `amalgm add <uuid>` chooses and validates local ground for it.
  */
-function createEntityCloud({ db, userId, deviceId, content = null }) {
+function createEntityCloud({ db, userId, deviceId, content = null, repoStates = null, repoTransportFor = null }) {
   if (!db) throw new Error('createEntityCloud requires an identity database');
   const ownerUserId = typeof userId === 'string' && userId ? userId : null;
   const localDeviceId = typeof deviceId === 'string' && deviceId ? deviceId : null;
 
+  function cloudRecord(record) {
+    const normalized = assertRecord(record);
+    if (normalized.type !== 'repo.git' || normalized.transportVersion !== null) return normalized;
+    const supplied = repoTransportFor?.(normalized) || null;
+    const state = repoStates?.get(normalized.uuid);
+    const transportVersion = supplied || state?.transportVersion || null;
+    if ((state && state.stateId !== normalized.payloadVersion) || !CONTENT_HEAD.test(String(transportVersion || ''))) {
+      throw new Error(`repository ${normalized.uuid} has no immutable Repocard transport for state ${normalized.payloadVersion || 'none'}`);
+    }
+    return { ...normalized, transportVersion };
+  }
+
   function contentHead(record) {
-    return ['file.text', 'file.binary'].includes(record?.type)
-      && typeof record?.payloadVersion === 'string'
-      && CONTENT_HEAD.test(record.payloadVersion);
+    if (['file.text', 'file.binary'].includes(record?.type)
+      && typeof record?.payloadVersion === 'string' && CONTENT_HEAD.test(record.payloadVersion)) {
+      return record.payloadVersion;
+    }
+    if (record?.type === 'repo.git' && typeof record?.transportVersion === 'string'
+      && CONTENT_HEAD.test(record.transportVersion)) return record.transportVersion;
+    return null;
+  }
+
+  function cloudSnapshot(records) {
+    return snapshotFromRecords(records.map(cloudRecord));
   }
 
-  function queueContent(record, resourceId, { queue = false } = {}) {
-    if (!contentHead(record)) return;
+  function queueContent(input, resourceId, { queue = false } = {}) {
+    const record = cloudRecord(input);
+    const head = contentHead(record);
+    if (!head) return;
     if (!content || typeof content.has !== 'function') {
       throw new Error('file entity content is unavailable: registration must capture bytes before it records their cloud head');
     }
-    if (!content.has({ contentHash: record.payloadVersion })) {
+    if (!content.has({ contentHash: head })) {
       throw new Error('file entity bytes were not captured before its cloud head committed');
     }
-    if (queue) content.ensureUpload({ resourceId, contentHash: record.payloadVersion });
+    if (queue) content.ensureUpload({ resourceId, contentHash: head });
   }
 
   function replica() {
@@ -301,15 +335,16 @@ function createEntityCloud({ db, userId, deviceId, content = null }) {
     // The SQLite mutation is the durable delivery intent. Its post-commit
     // content drain creates the filesystem upload cursor; doing that here
     // would let a rolled-back identity write upload unreachable bytes.
-    queueContent(record, current.resourceId);
+    const cloud = cloudRecord(record);
+    queueContent(cloud, current.resourceId);
     upsertCatalogRecord({
       resourceId: current.resourceId,
       authorityEpoch: current.authorityEpoch,
       headVersion: current.headVersion,
-      record,
+      record: cloud,
     });
     const mutationId = `ent_${crypto.randomBytes(18).toString('base64url')}`;
-    const operation = { kind: 'entity.upsert', record: assertRecord(record) };
+    const operation = { kind: 'entity.upsert', record: cloud };
     const createdAt = now();
     db.prepare(`
       INSERT INTO entity_cloud_mutations (
@@ -319,6 +354,45 @@ function createEntityCloud({ db, userId, deviceId, content = null }) {
     `).run(current.resourceId, mutationId, stableJson(operation), createdAt, createdAt);
   }
 
+  /** Publish one complete logical graph as one atomic cloud operation.  A
+   * large registration must never expose a half-created parent/child graph
+   * between individual acknowledgements. Ordinary watcher edits remain
+   * single-record operations. */
+  function replaceSnapshot(records) {
+    const current = replica();
+    if (!current || current.state !== 'active') {
+      throw new Error('entity cloud registry is not ready yet; wait for the signed-in runtime to finish its first cloud handshake');
+    }
+    const unsettled = db.prepare(`
+      SELECT COUNT(*) AS count FROM entity_cloud_mutations
+      WHERE resource_id = ? AND mutation_state <> 'synced'
+    `).get(current.resourceId);
+    if (Number(unsettled.count) !== 0) {
+      throw new Error('entity cloud registration is already uploading another change; wait for it before registering this large tree');
+    }
+    const snapshot = cloudSnapshot(records);
+    const operation = { kind: SNAPSHOT_REPLACE_OPERATION, snapshot };
+    const bytes = Buffer.byteLength(stableJson(operation), 'utf8');
+    if (bytes > SNAPSHOT_REPLACE_MAX_BYTES) {
+      throw new Error(`registered entity graph is ${bytes} bytes; the atomic cloud registration limit is ${SNAPSHOT_REPLACE_MAX_BYTES} bytes`);
+    }
+    for (const record of snapshot.records) queueContent(record, current.resourceId, { queue: true });
+    const createdAt = now();
+    db.prepare(`
+      INSERT INTO entity_cloud_mutations (
+        resource_id, mutation_id, operation_json, mutation_state,
+        created_at, updated_at
+      ) VALUES (?, ?, ?, 'pending', ?, ?)
+    `).run(
+      current.resourceId,
+      `ent_${crypto.randomBytes(18).toString('base64url')}`,
+      stableJson(operation),
+      createdAt,
+      createdAt,
+    );
+    return { records: snapshot.records.length, bytes };
+  }
+
   function enqueueBootstrapReconciliation(records, current) {
     const pending = db.prepare('SELECT COUNT(*) AS count FROM entity_cloud_mutations WHERE resource_id = ? AND mutation_state <> \'synced\'')
       .get(current.resourceId);
@@ -327,7 +401,7 @@ function createEntityCloud({ db, userId, deviceId, content = null }) {
     }
     const insert = db.prepare('INSERT INTO entity_cloud_mutations (resource_id, mutation_id, operation_json, mutation_state, created_at, updated_at) VALUES (?, ?, ?, \'pending\', ?, ?)');
     const createdAt = now();
-    for (const record of snapshotFromRecords(records).records) {
+    for (const record of cloudSnapshot(records).records) {
       queueContent(record, current.resourceId, { queue: true });
       insert.run(
         current.resourceId,
@@ -357,7 +431,7 @@ function createEntityCloud({ db, userId, deviceId, content = null }) {
     if (existing?.state === 'active') {
       throw new Error('entity cloud registry already exists locally; cloud lookup must not create it again');
     }
-    const snapshot = snapshotFromRecords(registry.syncRecords());
+    const snapshot = cloudSnapshot(registry.syncRecords());
     const cutoff = db.prepare('SELECT COALESCE(MAX(sequence), 0) AS sequence FROM entity_cloud_mutations').get().sequence;
     saveReplica({
       resourceId: currentIdentity.resourceId,
@@ -397,7 +471,7 @@ function createEntityCloud({ db, userId, deviceId, content = null }) {
       || !Number.isInteger(Number(headVersion)) || Number(headVersion) < 0) {
       throw new Error('entity cloud registry authority is invalid');
     }
-    const local = snapshotFromRecords(registry.syncRecords());
+    const local = cloudSnapshot(registry.syncRecords());
     const current = replica();
     const bootstrapping = current?.state === 'bootstrapping';
     const reconciling = current?.state === BOOTSTRAP_RECONCILIATION_STATE;
@@ -526,7 +600,7 @@ function createEntityCloud({ db, userId, deviceId, content = null }) {
     if (typeof targetPath !== 'string' || !targetPath) throw new Error('materialization requires a destination path');
     const tree = catalogTree({ resourceId: current.resourceId, uuid });
     if (tree[0].status !== 'active') throw new Error(`cloud entity ${uuid} is not active`);
-    const unsupported = tree.find((record) => ['repo.git', 'link', 'reference'].includes(record.type));
+    const unsupported = tree.find((record) => ['link', 'reference'].includes(record.type));
     if (unsupported) {
       throw new Error(`cloud entity ${unsupported.uuid} is ${unsupported.type}; this first materializer supports ordinary workspace and file trees only`);
     }
@@ -563,13 +637,14 @@ function createEntityCloud({ db, userId, deviceId, content = null }) {
       if (job.resourceId !== current.resourceId) continue;
       const tree = catalogTree({ resourceId: job.resourceId, uuid: job.entityUuid });
       for (const record of tree) {
-        if (!['file.text', 'file.binary'].includes(record.type) || record.status !== 'active') continue;
-        if (!contentHead(record)) throw new Error(`cloud file ${record.uuid} has no immutable content head`);
-        const part = content.missingPart({ contentHash: record.payloadVersion });
+        if (record.status !== 'active') continue;
+        const head = contentHead(record);
+        if (!head) continue;
+        const part = content.missingPart({ contentHash: head });
         if (!part) continue;
         return {
           resourceId: job.resourceId,
-          contentHash: record.payloadVersion,
+          contentHash: head,
           kind: part.kind,
           partIndex: part.partIndex,
           sha256: part.sha256,
@@ -613,6 +688,47 @@ function createEntityCloud({ db, userId, deviceId, content = null }) {
     return materialization(db.prepare('SELECT * FROM entity_materializations WHERE job_id = ?').get(jobId));
   }
 
+  /** A completed add is a live binding, not a one-time download.  A remote
+   * record beneath that binding moves the durable job back to its content
+   * gate.  The service owns the later filesystem application; this module
+   * owns only the durable intent to do it. */
+  function refreshMaterializations({ resourceId, record, version }) {
+    const refreshed = [];
+    for (const job of db.prepare(`
+      SELECT * FROM entity_materializations
+      WHERE resource_id = ? AND state = 'complete'
+      ORDER BY created_at ASC
+    `).all(resourceId)) {
+      const tree = catalogTree({ resourceId, uuid: job.entity_uuid });
+      if (!tree.some((candidate) => candidate.uuid === record.uuid)) continue;
+      db.prepare(`
+        UPDATE entity_materializations
+        SET head_version = ?, state = 'waiting_for_content', error = NULL, updated_at = ?
+        WHERE job_id = ?
+      `).run(Number(version), now(), job.job_id);
+      refreshed.push(job.job_id);
+    }
+    return refreshed;
+  }
+
+  function hasUnsettledLocalMutation(uuid) {
+    const rows = db.prepare(`
+      SELECT operation_json FROM entity_cloud_mutations
+      WHERE resource_id = ? AND mutation_state <> 'synced'
+      ORDER BY sequence ASC
+    `).all(replica()?.resourceId || '');
+    return rows.some((row) => {
+      try {
+        const operation = JSON.parse(row.operation_json);
+        return operation?.record?.uuid === uuid
+          || operation?.snapshot?.records?.some((record) => record?.uuid === uuid) === true;
+      } catch {
+        // A corrupt local outbox must never authorize an overwrite.
+        return true;
+      }
+    });
+  }
+
   function claim({ limit = 16, leaseMs = 30_000 } = {}) {
     const current = replica();
     if (!current || !['active', BOOTSTRAP_RECONCILIATION_STATE].includes(current.state)) return [];
@@ -641,8 +757,13 @@ function createEntityCloud({ db, userId, deviceId, content = null }) {
         // The logical mutation is intentionally held behind the immutable
         // content manifest. A cloud graph never advances to a file head
         // whose bytes have not reached private R2 storage.
-        if (contentHead(operation?.record)
-          && (!content || !content.uploaded({ resourceId: current.resourceId, contentHash: operation.record.payloadVersion }))) {
+        const records = operation?.kind === SNAPSHOT_REPLACE_OPERATION
+          ? operation?.snapshot?.records
+          : [operation?.record];
+        if ((records || []).some((record) => {
+          const head = contentHead(record);
+          return head && (!content || !content.uploaded({ resourceId: current.resourceId, contentHash: head }));
+        })) {
           return [];
         }
         claimRow.run(current.headVersion, leaseUntil, started, row.sequence);
@@ -654,7 +775,7 @@ function createEntityCloud({ db, userId, deviceId, content = null }) {
           baseVersion: current.headVersion,
           contract: ENTITY_CLOUD_CONTRACT,
           schemaVersion: ENTITY_CLOUD_SCHEMA_VERSION,
-          operationKind: 'entity.upsert',
+          operationKind: operation.kind,
           operation,
         }];
       });
@@ -673,8 +794,11 @@ function createEntityCloud({ db, userId, deviceId, content = null }) {
       ORDER BY sequence ASC
     `).all(current.resourceId);
     for (const row of rows) {
-      const record = JSON.parse(row.operation_json)?.record;
-      queueContent(record, current.resourceId, { queue: true });
+      const operation = JSON.parse(row.operation_json);
+      const records = operation?.kind === SNAPSHOT_REPLACE_OPERATION
+        ? operation?.snapshot?.records
+        : [operation?.record];
+      for (const record of records || []) queueContent(record, current.resourceId, { queue: true });
     }
     return content.claim({ resourceId: current.resourceId, leaseMs });
   }
@@ -760,9 +884,18 @@ function createEntityCloud({ db, userId, deviceId, content = null }) {
     }
     if (envelope?.resourceId !== current.resourceId
       || envelope?.contract !== ENTITY_CLOUD_CONTRACT
-      || Number(envelope?.schemaVersion) !== ENTITY_CLOUD_SCHEMA_VERSION
-      || envelope?.operationKind !== 'entity.upsert'
-      || envelope?.operation?.kind !== 'entity.upsert') {
+      || Number(envelope?.schemaVersion) !== ENTITY_CLOUD_SCHEMA_VERSION) {
+      throw new Error('cloud entity mutation does not belong to this registry');
+    }
+    if (envelope?.operationKind === SNAPSHOT_REPLACE_OPERATION
+      && envelope?.operation?.kind === SNAPSHOT_REPLACE_OPERATION) {
+      // The complete replacement is imported only from the active snapshot
+      // the gateway makes before acknowledgement. Consuming its tail would
+      // reintroduce the very partial-graph state this operation prevents.
+      if (Number(version) > current.headVersion) saveReplica({ ...current, headVersion: Number(version) });
+      return { duplicate: true, version: Number(version), snapshotRequired: true, materializations: [] };
+    }
+    if (envelope?.operationKind !== 'entity.upsert' || envelope?.operation?.kind !== 'entity.upsert') {
       throw new Error('cloud entity mutation does not belong to this registry');
     }
     const record = assertRecord(envelope.operation.record);
@@ -781,9 +914,13 @@ function createEntityCloud({ db, userId, deviceId, content = null }) {
     }
     // Remote mutations update the cloud-only catalog. They never create a
     // local watcher; `amalgm add` alone turns catalog identity into ground.
+    // A pre-existing local record is normally a conflict, except for a
+    // completed add binding with no unsent local edit. That binding will
+    // apply the authoritative cloud record through its own watcher-safe
+    // materializer below; it must not be stranded at its first snapshot.
     let local;
     try { local = registry.syncRecord(record.uuid); } catch { local = null; }
-    if (local && !sameRecord(local, record)) {
+    if (local && !sameRecord(local, record) && hasUnsettledLocalMutation(record.uuid)) {
       throw new Error('remote entity mutation conflicts with this device; refresh the compacted cloud head before applying it locally');
     }
     upsertCatalogRecord({
@@ -793,12 +930,17 @@ function createEntityCloud({ db, userId, deviceId, content = null }) {
       record,
     });
     if (Number(version) > current.headVersion) saveReplica({ ...current, headVersion: Number(version) });
-    return { duplicate: true, version: Number(version) };
+    return {
+      duplicate: true,
+      version: Number(version),
+      materializations: refreshMaterializations({ resourceId: current.resourceId, record, version }),
+    };
   }
 
   return {
     identity,
     journal,
+    replaceSnapshot,
     assertRegistrationReady,
     bootstrap,
     install,
@@ -816,6 +958,7 @@ function createEntityCloud({ db, userId, deviceId, content = null }) {
     completeMaterialization,
     failMaterialization,
     materializationStatus,
+    hasUnsettledLocalMutation,
     catalogTree,
     replica,
   };

package/runtime/scripts/amalgm-mcp/registration/entity-content.js

@@ -168,6 +168,34 @@ function createEntityContent({ dir }) {
     return installed;
   }
 
+  /** Capture immutable bytes that do not originate as a standalone file.
+   * Repocard transport is the first caller: its Git bundle plus checkpoint
+   * are one verified payload, while identity.db stores only the resulting
+   * content head.  The supplied bytes must already equal that head; this is
+   * the same content-addressed rule as captureFile, not a second storage
+   * format. */
+  function captureBytes({ bytes, contentHash = null }) {
+    const fullBytes = Buffer.from(bytes || []);
+    const head = contentHash || digest(fullBytes);
+    assertHash(head);
+    if (digest(fullBytes) !== head) throw new Error('entity content bytes do not match their declared head');
+    ensureDirs();
+    const existing = manifest(head);
+    if (existing) return existing;
+    const chunks = [];
+    for (let offset = 0; offset < fullBytes.length; offset += CHUNK_BYTES) {
+      const part = fullBytes.subarray(offset, Math.min(offset + CHUNK_BYTES, fullBytes.length));
+      const checksum = digest(part);
+      writeChunk(checksum, part);
+      chunks.push({ sha256: checksum, bytes: part.length });
+    }
+    const captured = { contract: CONTENT_CONTRACT, contentHash: head, bytes: fullBytes.length, chunks };
+    writeJson(manifestFile(head), captured);
+    const installed = manifest(head);
+    if (!installed) throw new Error('captured entity content bytes did not persist');
+    return installed;
+  }
+
   function initialUpload(resourceId, contentHash) {
     return {
       contract: CONTENT_CONTRACT,
@@ -414,6 +442,7 @@ function createEntityContent({ dir }) {
 
   return {
     captureFile,
+    captureBytes,
     ensureUpload,
     queueRecords,
     claim,

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

@@ -84,6 +84,11 @@ function createRegistration(options) {
   }
 
   const opened = openIdentity();
+  const captureRepo = opened.captureRepo || ((repoPath) => capture(repoPath, { withBundle: false }));
+  const repoStateAt = opened.repoStateAt ?? null;
+  if (repoStateAt !== null && typeof repoStateAt !== 'function') {
+    throw new Error('openIdentity.repoStateAt must be a function when supplied');
+  }
   const registry = createRegistry({
     db: opened.db,
     sentinelPath: opened.sentinelPath,
@@ -92,7 +97,7 @@ function createRegistration(options) {
     journal: opened.journal ?? null,
   });
   const memory = createEvidenceMemory(opened.db);
-  const repoStates = createRepoStates(opened.db);
+  const repoStates = opened.repoStates || createRepoStates(opened.db);
   const lenses = new Map(); // rootId (permanent witness) -> evidence lens
   let reported = []; // the latest edge pass's refusals
   let edgesDirty = false;
@@ -102,6 +107,7 @@ function createRegistration(options) {
     observer,
     registry,
     repoStates,
+    prepareRepo: opened.prepareRepo ?? null,
     recordForRoot: repoRecordForRoot,
     onSettled: reconcileSettledRepo,
   });
@@ -237,8 +243,9 @@ function createRegistration(options) {
           registry,
           memory,
           shouldEnroll: observer.shouldEnroll,
-          captureRepo: (repoPath) => capture(repoPath, { withBundle: false }),
+          captureRepo,
           repoStates,
+          repoStateAt,
         });
       } catch (error) {
         // An observer root is only coverage until its one structural
@@ -520,8 +527,9 @@ function createRegistration(options) {
         registry,
         memory,
         shouldEnroll: observer.shouldEnroll,
-        captureRepo: (repoPath) => capture(repoPath, { withBundle: false }),
+        captureRepo,
         repoStates,
+        repoStateAt,
         identityAt,
       });
       if (suppressJournal) registry.withoutJournal(register);
@@ -744,6 +752,11 @@ function createRegistration(options) {
 
     /** The latest edge pass's refusals — visible, never silent. */
     reported: () => [...reported],
+    addressOf,
+    // Composition owns the one database handle; exposing this narrow state
+    // store lets the cloud adapter name verified repository cargo without
+    // opening a competing registry over the same SQLite file.
+    repoStates,
     repoState: (uuid) => repoStates.get(uuid),
     tree: treeAt,
     trees: () => new Map(treeRoots()

package/runtime/scripts/amalgm-mcp/registration/repo-followers.js

@@ -25,7 +25,7 @@
 
 const { createFollower, createCaptureWorker } = require('../repocard');
 
-function createRepoFollowers({ observer, registry, repoStates, recordForRoot, onSettled }) {
+function createRepoFollowers({ observer, registry, repoStates, recordForRoot, onSettled, prepareRepo = null }) {
   if (!observer || !registry || !repoStates || typeof recordForRoot !== 'function'
     || typeof onSettled !== 'function') {
     throw new Error('createRepoFollowers requires { observer, registry, repoStates, recordForRoot, onSettled }');
@@ -71,7 +71,13 @@ function createRepoFollowers({ observer, registry, repoStates, recordForRoot, on
       const follower = createFollower({
         repoPath: root.path,
         last: baseline && { cardId: baseline.cardId, checkpointId: baseline.checkpointId },
-        captureFn: (repoPath) => worker.capture(repoPath, { withBundle: false }),
+        // The service can turn a full capture into immutable cloud cargo
+        // before the one stateId attestation commits. Local-only callers
+        // retain the lightweight bundle-free capture used historically.
+        captureFn: async (repoPath) => {
+          const captured = await worker.capture(repoPath, { withBundle: typeof prepareRepo === 'function' });
+          return typeof prepareRepo === 'function' && !captured?.busy ? prepareRepo(captured) : captured;
+        },
         emit: (next) => {
           // ONE settled Card + Checkpoint state is ONE registry transition on
           // the repo entity. Raw filesystem events never write Git state.

package/runtime/scripts/amalgm-mcp/registration/repo-states.js

@@ -25,17 +25,22 @@ function decodeBytes(encoded) {
   return Buffer.from(encoded || '', 'base64');
 }
 
-function pack(state) {
+/** The durable local state deliberately omits a Git bundle.  Bundles are
+ * transport cargo: keeping them in identity.db would turn a small registry
+ * into a second, unbounded object store.  The immutable content store owns
+ * the bundle bytes; SQLite retains only the content head that names them. */
+function pack(state, { includeBundle = true, transportVersion = state.transportVersion ?? null } = {}) {
   return JSON.stringify({
     stateId: state.stateId,
     cardId: state.cardId,
     checkpointId: state.checkpointId,
+    transportVersion,
     card: {
       ...state.card,
-      bundle: state.card.bundle && {
+      bundle: includeBundle && state.card.bundle ? {
         ...state.card.bundle,
         bytes: encodeBytes(state.card.bundle.bytes),
-      },
+      } : null,
     },
     checkpoint: {
       ...state.checkpoint,
@@ -53,6 +58,7 @@ function unpack(text) {
   const state = JSON.parse(text);
   return {
     ...state,
+    transportVersion: typeof state.transportVersion === 'string' ? state.transportVersion : null,
     card: {
       ...state.card,
       bundle: state.card.bundle && {
@@ -72,6 +78,22 @@ function unpack(text) {
   };
 }
 
+/** A Repocard transport document contains its bundle and checkpoint bytes,
+ * but never names itself: its SHA-256 is the immutable cloud content head.
+ * The semantic `stateId` remains on the repo entity, so bundle packing can
+ * vary without changing repository identity. */
+function transportBytes(state) {
+  return Buffer.from(pack(state, { includeBundle: true, transportVersion: null }), 'utf8');
+}
+
+function localState(state, transportVersion) {
+  return {
+    ...state,
+    transportVersion,
+    card: { ...state.card, bundle: null },
+  };
+}
+
 function createRepoStates(db) {
   if (!db) throw new Error('createRepoStates requires the identity database');
   const read = db.prepare('SELECT state_json FROM repo_states WHERE entity_uuid = ?');
@@ -106,4 +128,4 @@ function createRepoStates(db) {
   };
 }
 
-module.exports = { createRepoStates };
+module.exports = { createRepoStates, transportBytes, localState, unpack };