amalgm 0.1.261 → 0.1.263

package/runtime/scripts/amalgm-mcp/observer/store.js

@@ -15,6 +15,8 @@
  * is durable, or its loss is explicit.
  */
 
+const { preparer } = require('../lib/prepared');
+
 const SCHEMA = `
 CREATE TABLE IF NOT EXISTS observer_roots (
   root_id TEXT PRIMARY KEY,
@@ -141,6 +143,8 @@ function createStore(db) {
   db.exec(SCHEMA);
   db.pragma(`user_version = ${GENERATION}`);
 
+  const prepared = preparer(db);
+
   /**
    * One directory's immediate child rows — the scoped scan's slice of
    * memory, served by the (root_id, rel_path) unique index. '0' is the
@@ -150,33 +154,43 @@ function createStore(db) {
    */
   function immediateRows(table, rootId, relDir) {
     if (relDir === '') {
-      return db.prepare(`SELECT * FROM ${table} WHERE root_id = ? AND instr(rel_path, '/') = 0 ORDER BY rel_path`)
+      return prepared(`SELECT * FROM ${table} WHERE root_id = ? AND instr(rel_path, '/') = 0 ORDER BY rel_path`)
         .all(rootId);
     }
     const prefix = `${relDir}/`;
-    return db.prepare(`SELECT * FROM ${table} WHERE root_id = ? AND rel_path >= ? AND rel_path < ? ORDER BY rel_path`)
+    return prepared(`SELECT * FROM ${table} WHERE root_id = ? AND rel_path >= ? AND rel_path < ? ORDER BY rel_path`)
       .all(rootId, prefix, `${relDir}0`)
       .filter((row) => !row.rel_path.slice(prefix.length).includes('/'));
   }
 
   return {
+    /**
+     * One scan's whole apply phase commits as one durable transition.
+     * Row-level verbs each pay a full journal cycle when run bare, so a
+     * census over thousands of channels was thousands of commits; batched,
+     * it is one. Nesting is safe — SQLite savepoints — and a crash
+     * mid-batch leaves the previous truth whole, exactly like applyDirDiff.
+     */
+    transaction(fn) {
+      return db.transaction(fn)();
+    },
     addRoot({ rootId, path, kind, device = null, inode = null }) {
-      db.prepare('INSERT INTO observer_roots (root_id, path, kind, device, inode) VALUES (?, ?, ?, ?, ?)')
+      prepared('INSERT INTO observer_roots (root_id, path, kind, device, inode) VALUES (?, ?, ?, ?, ?)')
         .run(rootId, path, kind, device, inode);
     },
     rootByPath(path) {
-      const row = db.prepare('SELECT * FROM observer_roots WHERE path = ?').get(path);
+      const row = prepared('SELECT * FROM observer_roots WHERE path = ?').get(path);
       return row ? rowToRoot(row) : null;
     },
     listRoots() {
-      return db.prepare('SELECT * FROM observer_roots ORDER BY path').all().map(rowToRoot);
+      return prepared('SELECT * FROM observer_roots ORDER BY path').all().map(rowToRoot);
     },
     setRootKind(rootId, kind) {
-      db.prepare('UPDATE observer_roots SET kind = ? WHERE root_id = ?').run(kind, rootId);
+      prepared('UPDATE observer_roots SET kind = ? WHERE root_id = ?').run(kind, rootId);
     },
     /** Identity persists; local presence is separate evidence. */
     setRootPresent(rootId, present) {
-      db.prepare('UPDATE observer_roots SET present = ? WHERE root_id = ?').run(present ? 1 : 0, rootId);
+      prepared('UPDATE observer_roots SET present = ? WHERE root_id = ?').run(present ? 1 : 0, rootId);
     },
     /**
      * A root's identity is permanent; its address is not — and a family
@@ -186,7 +200,7 @@ function createStore(db) {
      * Device and inode are continuity itself and never churn on a rename.
      */
     moveRoots(moves) {
-      const move = db.prepare('UPDATE observer_roots SET path = ? WHERE root_id = ?');
+      const move = prepared('UPDATE observer_roots SET path = ? WHERE root_id = ?');
       db.transaction(() => {
         for (const { rootId, path } of moves) move.run(path, rootId);
       })();
@@ -195,18 +209,18 @@ function createStore(db) {
      * new identity at a known address (see enrollRoot) — the one write
      * where a root's own device:inode may change. */
     setRootIdentity(rootId, device, inode) {
-      db.prepare('UPDATE observer_roots SET device = ?, inode = ? WHERE root_id = ?')
+      prepared('UPDATE observer_roots SET device = ?, inode = ? WHERE root_id = ?')
         .run(device, inode, rootId);
     },
     removeRoot(rootId) {
-      db.prepare('DELETE FROM observer_files WHERE root_id = ?').run(rootId);
-      db.prepare('DELETE FROM observer_dirs WHERE root_id = ?').run(rootId);
-      db.prepare('DELETE FROM observer_links WHERE root_id = ?').run(rootId);
-      db.prepare('DELETE FROM observer_roots WHERE root_id = ?').run(rootId);
+      prepared('DELETE FROM observer_files WHERE root_id = ?').run(rootId);
+      prepared('DELETE FROM observer_dirs WHERE root_id = ?').run(rootId);
+      prepared('DELETE FROM observer_links WHERE root_id = ?').run(rootId);
+      prepared('DELETE FROM observer_roots WHERE root_id = ?').run(rootId);
     },
 
     filesForRoot(rootId) {
-      return db.prepare('SELECT * FROM observer_files WHERE root_id = ? ORDER BY rel_path').all(rootId)
+      return prepared('SELECT * FROM observer_files WHERE root_id = ? ORDER BY rel_path').all(rootId)
         .map(rowToFile);
     },
     filesInDir(rootId, relDir) {
@@ -220,11 +234,11 @@ function createStore(db) {
     },
     fileByPath(rootId, relPath) {
       return rowToFile(
-        db.prepare('SELECT * FROM observer_files WHERE root_id = ? AND rel_path = ?').get(rootId, relPath),
+        prepared('SELECT * FROM observer_files WHERE root_id = ? AND rel_path = ?').get(rootId, relPath),
       );
     },
     insertFile(file) {
-      db.prepare(`
+      prepared(`
         INSERT INTO observer_files (file_id, root_id, rel_path, device, inode, size, mtime_ms, content_hash, is_binary, hashed_at_ms)
         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
       `).run(
@@ -233,18 +247,18 @@ function createStore(db) {
       );
     },
     updateFile(fileId, { relPath, device, inode, size, mtimeMs, contentHash, binary, hashedAtMs }) {
-      db.prepare(`
+      prepared(`
         UPDATE observer_files
         SET rel_path = ?, device = ?, inode = ?, size = ?, mtime_ms = ?, content_hash = ?, is_binary = ?, hashed_at_ms = ?
         WHERE file_id = ?
       `).run(relPath, device, inode, size, mtimeMs, contentHash, binary ? 1 : 0, hashedAtMs, fileId);
     },
     removeFile(fileId) {
-      db.prepare('DELETE FROM observer_files WHERE file_id = ?').run(fileId);
+      prepared('DELETE FROM observer_files WHERE file_id = ?').run(fileId);
     },
 
     dirsForRoot(rootId) {
-      return db.prepare('SELECT * FROM observer_dirs WHERE root_id = ? ORDER BY rel_path').all(rootId)
+      return prepared('SELECT * FROM observer_dirs WHERE root_id = ? ORDER BY rel_path').all(rootId)
         .map(rowToDir);
     },
     /**
@@ -257,9 +271,9 @@ function createStore(db) {
      * the next scan re-detects the same batch.
      */
     applyDirDiff({ deletes, moves, retags, creates }) {
-      const remove = db.prepare('DELETE FROM observer_dirs WHERE dir_id = ?');
-      const insert = db.prepare('INSERT INTO observer_dirs (dir_id, root_id, rel_path, device, inode) VALUES (?, ?, ?, ?, ?)');
-      const retag = db.prepare('UPDATE observer_dirs SET rel_path = ?, device = ?, inode = ? WHERE dir_id = ?');
+      const remove = prepared('DELETE FROM observer_dirs WHERE dir_id = ?');
+      const insert = prepared('INSERT INTO observer_dirs (dir_id, root_id, rel_path, device, inode) VALUES (?, ?, ?, ?, ?)');
+      const retag = prepared('UPDATE observer_dirs SET rel_path = ?, device = ?, inode = ? WHERE dir_id = ?');
       db.transaction(() => {
         for (const dirId of deletes) remove.run(dirId);
         for (const dir of moves) remove.run(dir.dirId);
@@ -269,7 +283,7 @@ function createStore(db) {
       })();
     },
     removeDir(dirId) {
-      db.prepare('DELETE FROM observer_dirs WHERE dir_id = ?').run(dirId);
+      prepared('DELETE FROM observer_dirs WHERE dir_id = ?').run(dirId);
     },
 
     // Link channels: a pointer's whole payload is its target string, read
@@ -277,19 +291,19 @@ function createStore(db) {
     // a rename only ever targets a row-free slot), so link rows commit
     // per-row like files — every commit is a valid last-known truth.
     linksForRoot(rootId) {
-      return db.prepare('SELECT * FROM observer_links WHERE root_id = ? ORDER BY rel_path').all(rootId)
+      return prepared('SELECT * FROM observer_links WHERE root_id = ? ORDER BY rel_path').all(rootId)
         .map(rowToLink);
     },
     insertLink({ linkId, rootId, relPath, device, inode, target }) {
-      db.prepare('INSERT INTO observer_links (link_id, root_id, rel_path, device, inode, target) VALUES (?, ?, ?, ?, ?, ?)')
+      prepared('INSERT INTO observer_links (link_id, root_id, rel_path, device, inode, target) VALUES (?, ?, ?, ?, ?, ?)')
         .run(linkId, rootId, relPath, device, inode, target);
     },
     updateLink(linkId, { relPath, device, inode, target }) {
-      db.prepare('UPDATE observer_links SET rel_path = ?, device = ?, inode = ?, target = ? WHERE link_id = ?')
+      prepared('UPDATE observer_links SET rel_path = ?, device = ?, inode = ?, target = ? WHERE link_id = ?')
         .run(relPath, device, inode, target, linkId);
     },
     removeLink(linkId) {
-      db.prepare('DELETE FROM observer_links WHERE link_id = ?').run(linkId);
+      prepared('DELETE FROM observer_links WHERE link_id = ?').run(linkId);
     },
   };
 }

package/runtime/scripts/amalgm-mcp/observer/watch.js

@@ -23,13 +23,17 @@ function install(dirPath, recursive, onDirty, onDead) {
     watcher = fs.watch(dirPath, { recursive, persistent: false }, (_event, filename) => {
       onDirty(filename ? String(filename).split('\\').join('/') : null);
     });
-  } catch {
+  } catch (error) {
     handle.degraded = true;
+    // WHY the birth failed travels with the handle: ENOSPC (the kernel's
+    // file-watch budget) earns the caller an actionable message, not a shrug.
+    handle.reason = error?.code || 'unknown';
     return handle;
   }
-  watcher.on('error', () => {
+  watcher.on('error', (error) => {
     if (handle.degraded) return; // dead is dead: one death, one report
     handle.degraded = true;
+    handle.reason = error?.code || 'unknown';
     try { watcher.close(); } catch { /* already dead */ }
     if (onDead) onDead();
   });

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

@@ -92,6 +92,31 @@ function assertRecord(value) {
   };
 }
 
+/**
+ * The repo travel law: a record with a `repo.git` PROPER ancestor never
+ * travels to the cloud on its own. The repository is the sync boundary —
+ * its one Card + Checkpoint state carries the worktree's bytes AND its
+ * children's permanent UUIDs (the transport identity map), so a register
+ * or a rebase is one parcel, never one postcard per file. A nested
+ * repository inside another repo's worktree is enclosed too: it becomes
+ * cloud-visible only when registered explicitly as its own tree.
+ * Missing ancestry keeps the record traveling rather than risking a
+ * silently unsynced entity.
+ */
+function enclosedByRepositoryAncestor(record, lookup) {
+  const seen = new Set([record.uuid]);
+  let parentUUID = record.parentUUID;
+  while (parentUUID !== null && parentUUID !== undefined) {
+    if (seen.has(parentUUID)) throw new Error(`cloud entity ${record.uuid} has a cyclic parent chain`);
+    seen.add(parentUUID);
+    const parent = lookup(parentUUID);
+    if (!parent) return false;
+    if (parent.type === 'repo.git') return true;
+    parentUUID = parent.parentUUID;
+  }
+  return false;
+}
+
 function snapshotFromRecords(records) {
   const normalized = records.map(assertRecord).sort((left, right) => left.uuid.localeCompare(right.uuid));
   if (new Set(normalized.map((record) => record.uuid)).size !== normalized.length) {
@@ -180,28 +205,14 @@ function createEntityCloud({
       return fallback ? cloudRecord(fallback) : null;
     };
 
-    function enclosedByRepository(record) {
-      const seen = new Set([record.uuid]);
-      let parentUUID = record.parentUUID;
-      while (parentUUID !== null) {
-        if (seen.has(parentUUID)) throw new Error(`cloud entity ${record.uuid} has a cyclic parent chain`);
-        seen.add(parentUUID);
-        const parent = lookup(parentUUID);
-        // Missing ancestry retains content rather than risking an ordinary
-        // file whose only bytes were silently skipped.
-        if (!parent) return false;
-        if (parent.type === 'repo.git') return true;
-        parentUUID = parent.parentUUID;
-      }
-      return false;
-    }
-
     const heads = [];
     const seen = new Set();
     for (const record of normalized) {
       const contentHash = contentHead(record);
       if (!contentHash) continue;
-      if (['file.text', 'file.binary'].includes(record.type) && enclosedByRepository(record)) continue;
+      // Missing ancestry retains content rather than risking an ordinary
+      // file whose only bytes were silently skipped.
+      if (['file.text', 'file.binary'].includes(record.type) && enclosedByRepositoryAncestor(record, lookup)) continue;
       if (seen.has(contentHash)) continue;
       seen.add(contentHash);
       heads.push({ record, contentHash });
@@ -432,6 +443,14 @@ function createEntityCloud({
     // Bootstrap roots are included in the first immutable snapshot. No
     // unscoped row is written before the cloud replica exists.
     if (!current || current.state !== 'active') return;
+    // The repo travel law: a record enclosed by a repository never mails
+    // its own postcard. The repo's one settled state is the parcel — the
+    // transport carries the worktree's bytes and its children's UUIDs, so
+    // a 14k-file repo register (or a 300-file rebase) is ONE mutation on
+    // the repo entity, never thousands of child mutations.
+    if (enclosedByRepositoryAncestor(record, (uuid) => (typeof recordAt === 'function' ? recordAt(uuid) : null))) {
+      return;
+    }
     // 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.
@@ -470,7 +489,15 @@ function createEntityCloud({
     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);
+    // The repo travel law applies to the atomic graph too: repo children
+    // stay out of the snapshot, so a workspace of large repositories
+    // publishes a graph proportional to its traveling records — the
+    // repos' bytes and child identity ride each repo's transport.
+    const byUuid = new Map(records.map((candidate) => [candidate.uuid, candidate]));
+    const traveling = records.filter((candidate) => (
+      !enclosedByRepositoryAncestor(candidate, (uuid) => byUuid.get(uuid) || null)
+    ));
+    const snapshot = cloudSnapshot(traveling);
     const operation = { kind: SNAPSHOT_REPLACE_OPERATION, snapshot };
     const bytes = Buffer.byteLength(stableJson(operation), 'utf8');
     if (bytes > SNAPSHOT_REPLACE_MAX_BYTES) {
@@ -671,7 +698,14 @@ function createEntityCloud({
     }
     if (!bootstrapping) {
       const cloudByUuid = new Map(snapshot.records.map((record) => [record.uuid, record]));
-      for (const local of registry.syncRecords()) {
+      const locals = registry.syncRecords();
+      const localByUuid = new Map(locals.map((record) => [record.uuid, record]));
+      for (const local of locals) {
+        // Repo-enclosed local records evolve locally (Detect corrects
+        // their types and payloads) without journaling; a snapshot from
+        // before the repo travel law may still carry their stale rows.
+        // They are not cloud truth, so they cannot veto an install.
+        if (enclosedByRepositoryAncestor(local, (uuid) => localByUuid.get(uuid) || null)) continue;
         const remote = cloudByUuid.get(local.uuid);
         if (remote && !sameRecord(cloudRecord(local), remote)) {
           throw new Error('cloud entity graph conflicts with locally bound ground; resolve the local mutation before importing a new cloud head');
@@ -1196,6 +1230,7 @@ module.exports = {
   ENTITY_CLOUD_CONTRACT,
   ENTITY_CLOUD_SCHEMA_VERSION,
   createEntityCloud,
+  enclosedByRepositoryAncestor,
   parseSnapshot,
   privateEntityResourceId,
   snapshotFromRecords,

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

@@ -359,6 +359,43 @@ function createRegistration(options) {
    * genuinely live. A filesystem watcher that could not open is not a
    * warning; it means the requested Register → Watch operation is incomplete
    * and the caller must hear that. */
+  /**
+   * Watcher FIRST: prove the doorbell can be born before any identity
+   * commits. The birth is held (observer.watchNow) — the watcher exists
+   * and is judged, but concludes nothing until start() releases it. One
+   * retry absorbs a transient failure; a genuine refusal names its reason,
+   * because ENOSPC is a kernel watch budget the caller can actually fix.
+   */
+  function requireWatchBirth(root) {
+    const unhealthy = (row) => !row.watching || row.degraded
+      || (row.addressRequired && (!row.addressWatching || row.addressDegraded));
+    let health = observer.watchNow(root.rootId);
+    if (unhealthy(health)) health = observer.watchNow(root.rootId);
+    if (!unhealthy(health)) return;
+    const reason = health.degradedReason ? ` (${health.degradedReason})` : '';
+    const remedy = health.degradedReason === 'ENOSPC'
+      ? ' — the OS file-watch budget is exhausted; raise fs.inotify.max_user_watches or unregister unused ground, then retry'
+      : '';
+    throw refusal(`refusing to register ${root.path}: its watcher could not be born${reason}${remedy}; nothing was registered`);
+  }
+
+  /**
+   * The commit's last word, spoken INSIDE the identity transaction: the
+   * watchers proven before the walk are still live as the rows land. A
+   * watcher that died mid-walk rolls the whole registration — records and
+   * cloud journal together — back to nothing. This is an environment
+   * fault, never the caller's path.
+   */
+  function assertWatchedThroughCommit(rootPath) {
+    const dead = observer.status().filter((row) => (row.path === rootPath
+      || row.path.startsWith(`${rootPath}/`))
+      && (!row.watching || row.degraded));
+    if (dead.length > 0) {
+      throw new Error(`watcher(s) died during registration of ${rootPath}: `
+        + `${dead.map((row) => row.path).join(', ')} — the registration was rolled back`);
+    }
+  }
+
   function requireLiveWatchers(rootPath) {
     const belongs = (root) => root.path === rootPath || root.path.startsWith(`${rootPath}/`);
     let unavailable = observer.status().filter((root) => belongs(root)
@@ -525,24 +562,33 @@ function createRegistration(options) {
     }
     const root = observer.enrollRoot(ground, { scan: false, watch: false });
     try {
+      // WATCHER FIRST. Registration is synchronous, never optimistic: the
+      // doorbell is born and proven (held — concluding nothing) before one
+      // identity row exists, and the commit's own last word re-checks it.
+      // A record and its cloud journal land together inside registerTree's
+      // transaction, so the outcome is registered-and-watched, or nothing.
+      requireWatchBirth(root);
       assertWitnessed({ observer, registry, memory });
-      const register = () => registerTree({
-        root,
-        registry,
-        memory,
-        shouldEnroll: observer.shouldEnroll,
-        captureRepo,
-        repoStates,
-        repoStateAt,
-        identityAt,
+      const register = () => registry.transaction(() => {
+        registerTree({
+          root,
+          registry,
+          memory,
+          shouldEnroll: observer.shouldEnroll,
+          captureRepo,
+          repoStates,
+          repoStateAt,
+          identityAt,
+        });
+        assertWatchedThroughCommit(root.path);
       });
       if (suppressJournal) registry.withoutJournal(register);
       else register();
     } catch (error) {
       // The observer root is only an address until structural registration
-      // commits. Do not leave an unregistered address behind after a refused
-      // or failed walk; a committed tree, by contrast, is durable truth and
-      // is never rolled back by a later Watch/Detect fault.
+      // commits — and its held watchers are only handles. A refused or
+      // failed walk leaves NOTHING behind: removeRoot closes the doorbells
+      // and the transaction above rolled every row and journal entry back.
       observer.removeRoot(root.rootId);
       throw error;
     }

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

@@ -35,6 +35,24 @@ function createRepoFollowers({ observer, registry, repoStates, recordForRoot, on
   const followers = new Map(); // observer rootId -> { path, uuid, follower }
   let stopped = false;
 
+  /**
+   * A scoped capture reuses an unsuspected untracked entry WITHOUT its
+   * bytes. The persisted state must stay whole — transport cargo packs
+   * untracked content straight from it — so the bytes are carried forward
+   * from the previous settled state: a memory copy, never a disk read.
+   * The transient `reused` flag never persists.
+   */
+  function hydrateReusedUntracked(next, previous) {
+    const entries = next?.checkpoint?.untracked;
+    if (!entries?.some((file) => file.reused)) return;
+    const prior = new Map((previous?.checkpoint?.untracked ?? []).map((file) => [file.path, file]));
+    next.checkpoint.untracked = entries.map((file) => {
+      if (!file.reused) return file;
+      const { reused, ...kept } = file;
+      return { ...kept, content: prior.get(file.path)?.content ?? null };
+    });
+  }
+
   function close(rootId) {
     const entry = followers.get(rootId);
     if (!entry) return;
@@ -74,14 +92,32 @@ function createRepoFollowers({ observer, registry, repoStates, recordForRoot, on
         // 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;
+        // The repo UUID rides along so the transport packs the current
+        // worktree identity map from the registry.
+        captureFn: async (repoPath, { suspects } = {}) => {
+          const withBundle = typeof prepareRepo === 'function';
+          // The warm checkpoint: the last settled state's untracked entries
+          // ((path, mode, sha256) — content is never persisted) let a scoped
+          // capture reuse every unsuspected file without opening it. Cloud
+          // cargo captures (withBundle) need content and read everything;
+          // capture() enforces that side of the contract itself.
+          const previous = withBundle ? null : repoStates.get(record.uuid);
+          const captured = await worker.capture(repoPath, {
+            withBundle,
+            suspects,
+            previousUntracked: previous?.checkpoint?.untracked?.map(
+              ({ path: rel, mode, sha256 }) => ({ path: rel, mode, sha256 }),
+            ) ?? null,
+          });
+          return withBundle && !captured?.busy
+            ? prepareRepo(captured, { entityUuid: record.uuid })
+            : captured;
         },
         emit: (next) => {
           // ONE settled Card + Checkpoint state is ONE registry transition on
           // the repo entity. Raw filesystem events never write Git state.
           const previous = repoStates.get(record.uuid);
+          hydrateReusedUntracked(next, previous);
           registry.transaction(() => {
             repoStates.put(record.uuid, next);
             registry.attest(record.uuid, { type: 'repo.git', payloadVersion: next.stateId });
@@ -115,7 +151,10 @@ function createRepoFollowers({ observer, registry, repoStates, recordForRoot, on
       sync();
       return;
     }
-    if (event.type === 'repo.changed') followers.get(event.rootId)?.follower.ring();
+    // The ding's hint (the named path, rebased to the repo's ground, or
+    // null for "anywhere") rides into the follower's scope: it is what
+    // lets the next capture patch one file instead of re-reading the world.
+    if (event.type === 'repo.changed') followers.get(event.rootId)?.follower.ring(event.hint ?? null);
   }
 
   function stop() {

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

@@ -28,13 +28,18 @@ function decodeBytes(encoded) {
 /** 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 } = {}) {
+ * the bundle bytes; SQLite retains only the content head that names them.
+ * The identity map is transport cargo too: it names the repo's enrolled
+ * worktree entities so a receiving machine binds the SAME child UUIDs
+ * instead of minting competitors — derived from the registry whenever a
+ * transport is packed, never persisted beside the local state. */
+function pack(state, { includeBundle = true, transportVersion = state.transportVersion ?? null, identity = null } = {}) {
   return JSON.stringify({
     stateId: state.stateId,
     cardId: state.cardId,
     checkpointId: state.checkpointId,
     transportVersion,
+    ...(identity ? { identity } : {}),
     card: {
       ...state.card,
       bundle: includeBundle && state.card.bundle ? {
@@ -59,6 +64,7 @@ function unpack(text) {
   return {
     ...state,
     transportVersion: typeof state.transportVersion === 'string' ? state.transportVersion : null,
+    identity: Array.isArray(state.identity) ? state.identity : null,
     card: {
       ...state.card,
       bundle: state.card.bundle && {
@@ -81,15 +87,19 @@ 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');
+ * vary without changing repository identity. `identity` is the enrolled
+ * worktree's path → { uuid, type } entries: repo children never travel as
+ * individual cloud records, so their permanent UUIDs ride here — inside
+ * the one state parcel — and `amalgm add` binds them from this map. */
+function transportBytes(state, identity = null) {
+  return Buffer.from(pack(state, { includeBundle: true, transportVersion: null, identity }), 'utf8');
 }
 
 function localState(state, transportVersion) {
   return {
     ...state,
     transportVersion,
+    identity: null,
     card: { ...state.card, bundle: null },
   };
 }