amalgm 0.1.262 → 0.1.264

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

@@ -44,6 +44,57 @@ function isRepository(dirPath) {
   return gitDirTruth(dirPath) === 'present';
 }
 
+/**
+ * Assign every enrolled worktree entity its permanent UUID BEFORE the
+ * repo's transport is packed, so the transport's identity map and the
+ * records this walk then creates name the exact same UUIDs. Repo children
+ * never travel as individual cloud records (the repo travel law); this
+ * map, riding inside the one state parcel, is how a receiving machine
+ * binds the same child identities instead of minting competitors.
+ *
+ * The walk mirrors registerDirectory's classification exactly — same
+ * readdir order, same enrollment gate, same lstat shape — and stops at a
+ * nested repository boundary: that repo's own capture owns its own map.
+ */
+function collectWorktreeIdentity(repoPath, { shouldEnroll, identityFor }) {
+  const assignment = new Map(); // repo-relative path -> { uuid, type }
+  const walk = (dirPath, relativePath) => {
+    let entries;
+    try {
+      entries = fs.readdirSync(dirPath, { withFileTypes: true })
+        .sort((a, b) => a.name.localeCompare(b.name));
+    } catch (error) {
+      if (error.code === 'EACCES' || error.code === 'EPERM') return;
+      throw error;
+    }
+    for (const entry of entries) {
+      const entryPath = path.join(dirPath, entry.name);
+      const entryRelativePath = relativePath ? `${relativePath}/${entry.name}` : entry.name;
+      if (!shouldEnroll(entryPath)) continue;
+      let stat;
+      try {
+        stat = fs.lstatSync(entryPath);
+      } catch {
+        continue; // raced away between readdir and look; the create-walk decides
+      }
+      let type;
+      if (stat.isSymbolicLink()) type = 'link';
+      else if (stat.isDirectory()) type = isRepository(entryPath) ? 'repo.git' : 'folder';
+      else if (stat.isFile()) type = 'file.text';
+      else continue;
+      const uuid = identityFor?.(entryRelativePath) || crypto.randomUUID();
+      assignment.set(entryRelativePath, { uuid, type });
+      if (type === 'folder') walk(entryPath, entryRelativePath);
+    }
+  };
+  walk(repoPath, '');
+  return assignment;
+}
+
+function transportIdentity(assignment) {
+  return [...assignment].map(([entryPath, { uuid, type }]) => ({ path: entryPath, uuid, type }));
+}
+
 /**
  * Create the root record, its witness, and every entity below ordinary
  * directory ground. The caller supplies a root that is already known to the
@@ -90,47 +141,58 @@ function registerTree({ root, registry, memory, shouldEnroll, captureRepo, repoS
   /** An imported repository already has a verified Repocard artifact in the
    * local state table before it is bound to Watch. Reuse that exact state;
    * recapturing would waste a second Git bundle and could race the import.
-   * Ordinary local registration has no seeded UUID and captures fresh truth. */
-  function repoStateFor(identity, repoPath) {
+   * Ordinary local registration has no seeded UUID and captures fresh truth:
+   * the worktree's UUIDs are assigned FIRST so the packed transport's
+   * identity map and the created child records agree exactly. */
+  function repoStateFor(identity, repoPath, relativePath) {
     if (identity.uuid) {
       const imported = repoStateAt?.(identity.uuid);
-      if (imported?.stateId === identity.payloadVersion) return imported;
+      if (imported?.stateId === identity.payloadVersion) return { state: imported, assignment: null };
       const saved = repoStates.get(identity.uuid);
-      if (saved?.stateId === identity.payloadVersion) return saved;
+      if (saved?.stateId === identity.payloadVersion) return { state: saved, assignment: null };
     }
-    return captureInitialRepo(repoPath, captureRepo);
+    const assignment = collectWorktreeIdentity(repoPath, {
+      shouldEnroll,
+      identityFor: (repoRelativePath) => identityAt?.(
+        relativePath ? `${relativePath}/${repoRelativePath}` : repoRelativePath,
+      )?.uuid || null,
+    });
+    return {
+      state: captureInitialRepo(repoPath, captureRepo, transportIdentity(assignment)),
+      assignment,
+    };
   }
 
   return registry.transaction(() => {
     const rootIdentity = seeded('', {
       type: rootType(root.path, root.kind), parentUUID: null, name: path.basename(root.path), root: true,
     });
-    const initialState = root.kind === 'repo' ? repoStateFor(rootIdentity, root.path) : null;
+    const initial = root.kind === 'repo' ? repoStateFor(rootIdentity, root.path, '') : null;
     // A repo's immutable transport head is already held by the injected
     // cloud-cargo lookup before its entity journal runs. Allocate the UUID,
     // create the FK parent, then persist its bundle-free state in this same
     // transaction. A rollback removes both durable facts together.
-    const rootUuid = rootIdentity.uuid || (initialState ? crypto.randomUUID() : undefined);
+    const rootUuid = rootIdentity.uuid || (initial ? crypto.randomUUID() : undefined);
     const record = registry.enrollRoot({
       type: rootIdentity.type,
       name: path.basename(root.path),
-      payloadVersion: initialState?.stateId ?? rootIdentity.payloadVersion ?? null,
+      payloadVersion: initial?.state.stateId ?? rootIdentity.payloadVersion ?? null,
       uuid: rootUuid,
     });
     memory.bind(root.rootId, root.rootId, record.uuid);
-    if (initialState) repoStates.put(record.uuid, initialState);
+    if (initial) repoStates.put(record.uuid, initial.state);
 
     if (root.kind === 'files' || root.kind === 'repo') {
       registerDirectory(root.path, record.uuid, {
         registry, shouldEnroll, captureRepo, repoStates, identityAt, repoStateAt, repoStateFor, seeded, relativePath: '',
-      });
+      }, initial?.assignment ? { base: '', byPath: initial.assignment } : null);
     }
     return record;
   });
 }
 
-function captureInitialRepo(repoPath, captureRepo) {
-  const state = captureRepo(repoPath);
+function captureInitialRepo(repoPath, captureRepo, identityEntries = null) {
+  const state = captureRepo(repoPath, { identity: identityEntries });
   if (state?.busy) {
     throw new Error(`cannot register ${repoPath}: Git is unsettled (${state.busy})`);
   }
@@ -142,7 +204,7 @@ function captureInitialRepo(repoPath, captureRepo) {
 
 function registerDirectory(dirPath, parentUUID, {
   registry, shouldEnroll, captureRepo, repoStates, identityAt, repoStateAt, repoStateFor, seeded, relativePath,
-}) {
+}, assigned = null) {
   let entries;
   try {
     entries = fs.readdirSync(dirPath, { withFileTypes: true })
@@ -155,6 +217,20 @@ function registerDirectory(dirPath, parentUUID, {
     throw error;
   }
 
+  // The UUID a pre-capture assignment reserved for this exact ground. The
+  // transport's identity map was packed from these, so the created record
+  // must wear the same UUID — unless the ground changed shape between the
+  // assignment walk and this one, in which case the walk's truth wins and
+  // the map entry is honestly stale.
+  const assignedFor = (entryRelativePath, type) => {
+    if (!assigned) return undefined;
+    const repoRelativePath = assigned.base
+      ? entryRelativePath.slice(assigned.base.length + 1)
+      : entryRelativePath;
+    const seat = assigned.byPath.get(repoRelativePath);
+    return seat && seat.type === type ? seat.uuid : undefined;
+  };
+
   for (const entry of entries) {
     const entryPath = path.join(dirPath, entry.name);
     const entryRelativePath = relativePath ? `${relativePath}/${entry.name}` : entry.name;
@@ -173,7 +249,7 @@ function registerDirectory(dirPath, parentUUID, {
         // Preserve it through the structural bind; normal local registration
         // still leaves this null until Watch observes the filesystem.
         payloadVersion: identity.payloadVersion ?? null,
-        uuid: identity.uuid,
+        uuid: identity.uuid ?? assignedFor(entryRelativePath, 'link'),
       });
       continue;
     }
@@ -182,19 +258,27 @@ function registerDirectory(dirPath, parentUUID, {
       const identity = seeded(entryRelativePath, {
         type, parentUUID, name: entry.name, root: false,
       });
-      const state = type === 'repo.git' ? repoStateFor(identity, entryPath) : null;
-      const uuid = identity.uuid || (state ? crypto.randomUUID() : undefined);
+      const initial = type === 'repo.git' ? repoStateFor(identity, entryPath, entryRelativePath) : null;
+      const uuid = identity.uuid
+        ?? assignedFor(entryRelativePath, type)
+        ?? (initial ? crypto.randomUUID() : undefined);
       const record = registry.create({
         type: identity.type,
         parentUUID,
         name: entry.name,
-        payloadVersion: state?.stateId ?? identity.payloadVersion ?? null,
+        payloadVersion: initial?.state.stateId ?? identity.payloadVersion ?? null,
         uuid,
       });
-      if (state) repoStates.put(record.uuid, state);
+      if (initial) repoStates.put(record.uuid, initial.state);
+      // A repository starts its own assignment scope: its transport's map
+      // covers exactly its worktree, so its children draw from it — never
+      // from an enclosing repo's map.
+      const childAssigned = type === 'repo.git'
+        ? (initial?.assignment ? { base: entryRelativePath, byPath: initial.assignment } : null)
+        : assigned;
       registerDirectory(entryPath, record.uuid, {
         registry, shouldEnroll, captureRepo, repoStates, identityAt, repoStateAt, repoStateFor, seeded, relativePath: entryRelativePath,
-      });
+      }, childAssigned);
       continue;
     }
     if (stat.isFile()) {
@@ -206,7 +290,7 @@ function registerDirectory(dirPath, parentUUID, {
         parentUUID,
         name: entry.name,
         payloadVersion: identity.payloadVersion ?? null,
-        uuid: identity.uuid,
+        uuid: identity.uuid ?? assignedFor(entryRelativePath, 'file.text'),
       });
     }
   }

package/runtime/scripts/amalgm-mcp/registry/evidence.js

@@ -80,7 +80,8 @@
  *     the folder record and every descendant's derived address follows,
  *     which is why folders reconcile before files, parents before
  *     children;
- *   - repo territories as repo.git type transitions on the slot's record;
+ *   - repo territories as observer truth, with an explicitly registered
+ *     repository boundary supplying the corresponding repo.git record;
  *   - ADOPTION, the channel law completing across trees: unclaimed
  *     ground wearing the physical identity of an orphaned top-level tree
  *     is that tree's arrival — one lawful parent update on its
@@ -604,23 +605,24 @@ function createEvidence(options) {
       };
       settleClaims(claimsOf(desiredDirs, 'dir'), 'dir');
 
-      // Territories after folder continuity, before file ground: a
-      // boundary is a repo.git type transition on the slot's record, and
-      // the slot must already be where its folder channel says it is.
+      // Territories after folder continuity, before file ground.  A Git
+      // boundary is NOT ordinary filesystem evidence: every repo.git record
+      // needs a Card + Checkpoint state and immutable transport before it can
+      // travel.  This generic lens has neither, so it may only recognize a
+      // boundary that the registration adapter already made whole.  An
+      // unregistered repository remains a local observer territory until
+      // `amalgm register <repo>` admits it through that adapter.
+      //
+      // This is deliberately not a convenience gate.  Letting this layer
+      // mint or promote repo.git would create an identity record whose cloud
+      // head names no state — the exact invalid half-repository the cloud
+      // contract rejects.  Folders and files are evidence-shaped; Git is a
+      // type-specific state carrier.
       for (const territory of [...territories].sort()) {
         const parentUuid = ensureDir(path.dirname(territory) === '.' ? '' : path.dirname(territory), root);
         const name = path.basename(territory);
         const at = registry.activeAt(parentUuid, name);
-        if (!at) {
-          // Adoption before birth here too: a registered top-level repo
-          // TREE that moved in arrives as its own record, never a fresh
-          // territory record. The enclosed observer root's identity is
-          // the evidence — the same physical dir the orphaned tree owns.
-          const enclosed = observer.listRoots().find((row) => row.path === path.join(groundPath, territory));
-          const arrivedRecord = enclosed ? arrivedTree(enclosed.device, enclosed.inode, REPO_TREE) : null;
-          if (arrivedRecord) registry.move(arrivedRecord.uuid, { parentUUID: parentUuid, name });
-          else registry.create({ type: 'repo.git', parentUUID: parentUuid, name });
-        } else if (at.type !== 'repo.git') registry.changeType(at.uuid, 'repo.git');
+        if (at?.type !== 'repo.git') continue;
       }
       // A lifted lens is the reverse transition on the same record.
       for (const { record, rel } of walkActive(root.uuid, '', [])) {

package/runtime/scripts/amalgm-mcp/repocard/capture.js

@@ -62,13 +62,50 @@ function remoteList(repoPath) {
   }).sort((a, b) => (a.name < b.name ? -1 : 1));
 }
 
-function untrackedFiles(repoPath) {
+/** Is `rel` named by the suspect list — itself, or under a named directory? */
+function makeSuspectTest(suspects) {
+  const named = new Set(suspects);
+  return (rel) => {
+    if (named.has(rel)) return true;
+    let prefix = rel;
+    for (;;) {
+      const cut = prefix.lastIndexOf('/');
+      if (cut < 0) return false;
+      prefix = prefix.slice(0, cut);
+      if (named.has(prefix)) return true;
+    }
+  };
+}
+
+/**
+ * The warm half of the checkpoint. Git keeps the Card's ledger itself and
+ * its index makes the tracked diffs cheap — the one cost with no cache was
+ * untracked files, re-read in full on every capture. With `suspects` (the
+ * doorbell's named paths since the last settled state) and the previous
+ * state's untracked entries, an unsuspected file's (mode, sha256) is
+ * REUSED without opening it: silence from the doorbell is the proof the
+ * written answer is still true. Everything else stays a fresh read — a
+ * suspect, a new path, or any capture without both inputs (suspects null
+ * means "everything is suspect": first capture, flush, catch-up, a command
+ * ending). Reused entries carry `content: null`; ids derive from
+ * (path, mode, sha256) alone, so a scoped capture's ids are byte-identical
+ * to a from-scratch one over the same ground.
+ */
+function untrackedFiles(repoPath, { suspects = null, previousUntracked = null } = {}) {
+  const reusable = suspects !== null && previousUntracked
+    ? new Map(previousUntracked.map((file) => [file.path, file]))
+    : null;
+  const suspect = reusable ? makeSuspectTest(suspects) : null;
   const out = runGit(repoPath, ['ls-files', '--others', '--exclude-standard', '-z']).toString('utf8');
   return out.split('\0').filter(Boolean).sort().flatMap((rel) => {
     // A trailing slash is git marking a repo boundary it will not enter — a
     // nested repository or linked worktree. That is its own territory with
     // its own card; the parent's checkpoint must not contain it.
     if (rel.endsWith('/')) return [];
+    if (reusable && !suspect(rel)) {
+      const prev = reusable.get(rel);
+      if (prev) return [{ path: rel, mode: prev.mode, content: null, sha256: prev.sha256, reused: true }];
+    }
     const abs = path.join(repoPath, rel);
     try {
       const stat = fs.lstatSync(abs);
@@ -123,9 +160,14 @@ function deriveCheckpointId(checkpoint) {
   }));
 }
 
-function capture(repoPath, { withBundle = true } = {}) {
+function capture(repoPath, { withBundle = true, suspects = null, previousUntracked = null } = {}) {
   const busy = busyReason(repoPath);
   if (busy) return { busy };
+  // Untracked reuse is bundle-free (local) captures only: cloud cargo
+  // (prepareRepo) consumes untracked CONTENT, and a reused entry carries
+  // none. Teaching the cargo path to dedupe by sha256 is the named next
+  // step; until then a withBundle capture always reads every byte.
+  const scoped = withBundle ? {} : { suspects, previousUntracked };
 
   const branch = tryGitText(repoPath, ['symbolic-ref', '-q', '--short', 'HEAD']); // null = detached
   const commit = tryGitText(repoPath, ['rev-parse', '-q', '--verify', 'HEAD']);   // null = unborn
@@ -146,7 +188,7 @@ function capture(repoPath, { withBundle = true } = {}) {
     // raw non-UTF-8 bytes, and a string conversion would corrupt it silently.
     stagedPatch: runGit(repoPath, ['diff', '--cached', '--binary', '--full-index', commit ? 'HEAD' : EMPTY_TREE]),
     unstagedPatch: runGit(repoPath, ['diff', '--binary', '--full-index']),
-    untracked: untrackedFiles(repoPath),
+    untracked: untrackedFiles(repoPath, scoped),
   };
 
   const cardId = deriveCardId(card);

package/runtime/scripts/amalgm-mcp/repocard/follow.js

@@ -95,12 +95,24 @@ function createFollower(options) {
     last = null,    // resume seed: { cardId, checkpointId }
     // May return a promise (e.g. a capture worker): the follower awaits it,
     // and any doorbell that lands mid-pair re-arms a retry (`pendingWake`).
-    captureFn = (repo) => capture(repo, { withBundle: false }),
+    // Called with { suspects }: the worktree paths rung since the last
+    // settled state, or null when everything is suspect.
+    captureFn = (repo, { suspects } = {}) => capture(repo, { withBundle: false, suspects }),
   } = options;
   if (!repoPath) throw new Error('createFollower requires { repoPath }');
   if (typeof emit !== 'function') throw new Error('createFollower requires { emit }');
 
   let known = last ? { cardId: last.cardId, checkpointId: last.checkpointId } : null;
+  // The warm-checkpoint scope: which worktree paths the doorbell has named
+  // since the last settled state. Each entry remembers the GENERATION of
+  // the ring that named it, so a path rung again mid-pair keeps its
+  // suspicion when the pair's success consumes the older hints. A nameless
+  // ring — or any entrance that may follow missed doorbells (birth, flush,
+  // a command ending) — makes EVERYTHING suspect until a pair settles.
+  const SCOPE_CAP = 512;
+  const scope = new Map(); // repo-relative path -> generation
+  let scopeGen = 0;
+  let scopeAllGen = 0; // >0: everything is suspect (set at birth, flush, command end, nameless ring)
   let owned = 0; // depth of amalgm-owned commands in flight
   let blocked = null; // lock name while the last capture attempt met a held lock
   let blockedPath = null;
@@ -210,12 +222,15 @@ function createFollower(options) {
 
     // The torn-read guard: two consecutive reads must agree before a state
     // may travel — a repo mid-mutation cannot produce the same ids twice.
+    // Both halves of the pair read the SAME scope: the paths rung so far.
+    const genNow = scopeGen;
+    const suspects = scopeAllGen > 0 ? null : [...scope.keys()];
     let first;
     let second;
     try {
-      first = await captureFn(repoPath);
+      first = await captureFn(repoPath, { suspects });
       if (closed || owned > 0) return; // the pair is stale before it finished
-      second = first && !first.busy ? await captureFn(repoPath) : null;
+      second = first && !first.busy ? await captureFn(repoPath, { suspects }) : null;
     } catch (error) {
       if (closed) return;
       // A read tripping over a mid-flight writer (a file vanishing between
@@ -234,11 +249,34 @@ function createFollower(options) {
       retry(settleMs);
       return;
     }
-    if (!speak(second)) retry(capMs); // consumer failure: patient, loud, never lost
+    if (!speak(second)) {
+      retry(capMs); // consumer failure: patient, loud, never lost
+      return;
+    }
+    // The settled pair proved the ground the scope described: hints from
+    // BEFORE the pair began are consumed; anything rung mid-pair keeps its
+    // newer generation and stays suspect for the pendingWake retry.
+    if (scopeAllGen > 0 && scopeAllGen <= genNow) scopeAllGen = 0;
+    for (const [rel, gen] of scope) {
+      if (gen <= genNow) scope.delete(rel);
+    }
   }
 
-  function ring() {
+  function ring(hint) {
     if (closed || owned > 0) return; // the command's end is the boundary
+    // Accumulate the warm-checkpoint scope. A .git-area hint never touches
+    // untracked ground, so it schedules a capture without widening the
+    // scope; a nameless hint (or an overflowing scope) suspects everything.
+    scopeGen += 1;
+    if (hint === null || hint === undefined) {
+      scopeAllGen = scopeGen;
+    } else if (hint !== '.git' && !hint.startsWith('.git/')) {
+      scope.set(hint, scopeGen);
+      if (scope.size > SCOPE_CAP) {
+        scope.clear();
+        scopeAllGen = scopeGen;
+      }
+    }
     if (settleTimer) clearTimeout(settleTimer);
     settleTimer = setTimeout(() => {
       settleTimer = null;
@@ -262,7 +300,13 @@ function createFollower(options) {
 
   function endCommand() {
     owned = Math.max(0, owned - 1);
-    if (owned === 0 && !closed) fire();
+    // Rings were suppressed while the command ran: its writes are nobody's
+    // hints, so the capture at the boundary suspects everything.
+    if (owned === 0 && !closed) {
+      scopeGen += 1;
+      scopeAllGen = scopeGen;
+      fire();
+    }
   }
 
   /** Run an amalgm-owned command: no captures while it runs, one at its end. */
@@ -284,10 +328,21 @@ function createFollower(options) {
 
   return {
     ring,
-    /** Birth: capture once, immediately. With a seeded `last`, an unchanged repo is silence. */
-    start: () => fire(),
-    /** Consumer-requested capture — the "scanNow" of this layer. */
-    flush: () => fire(),
+    /** Birth: capture once, immediately, suspecting everything — rings
+     * before birth were nobody's. With a seeded `last`, an unchanged
+     * repo is silence. */
+    start: () => {
+      scopeGen += 1;
+      scopeAllGen = scopeGen;
+      return fire();
+    },
+    /** Consumer-requested capture — the "scanNow" of this layer. Its whole
+     * purpose is catching a LOST doorbell, so it never trusts the scope. */
+    flush: () => {
+      scopeGen += 1;
+      scopeAllGen = scopeGen;
+      return fire();
+    },
     beginCommand,
     endCommand,
     command,

package/runtime/scripts/amalgm-mcp/tests/entity-cloud.test.js

@@ -371,3 +371,93 @@ test('add follows in-order mirrored mutations and refuses after a version gap un
     fs.rmSync(targetDir, { recursive: true, force: true });
   }
 });
+
+// --- the repo travel law -----------------------------------------------------
+
+function activeCloud({ content = { has: () => true, ensureUpload: () => {} }, repoTransportFor = null } = {}) {
+  const db = new Database(':memory:');
+  let registry = null;
+  const cloud = createEntityCloud({
+    db,
+    userId: 'user-1',
+    deviceId: 'device-1',
+    content,
+    repoTransportFor,
+    recordAt: (uuid) => {
+      try { return registry.syncRecord(uuid); } catch { return null; }
+    },
+  });
+  registry = createRegistry({ db, ephemeral: true, emit: () => {}, journal: cloud.journal });
+  const root = registry.enrollRoot({ type: 'workspace', name: 'ground' });
+  const bootstrap = cloud.bootstrap(registry.syncRecords());
+  cloud.install({
+    registry,
+    resourceId: bootstrap.resourceId,
+    authorityEpoch: 1,
+    headVersion: 0,
+    snapshotBase64: bootstrap.snapshotBase64,
+    snapshotChecksum: bootstrap.snapshotChecksum,
+  });
+  return { db, cloud, registry, root, resourceId: bootstrap.resourceId };
+}
+
+test('a record enclosed by a repository never journals its own cloud mutation — the repo state parcel is the carrier', () => {
+  const transportHead = 'a'.repeat(64);
+  const { db, registry, root, resourceId } = activeCloud({
+    repoTransportFor: () => transportHead,
+  });
+
+  const repo = registry.create({ type: 'repo.git', parentUUID: root.uuid, name: 'engine', payloadVersion: 'state-1' });
+  assert.equal(db.prepare('SELECT COUNT(*) AS count FROM entity_cloud_mutations').get().count, 1,
+    'the repository record itself travels');
+
+  const folder = registry.create({ type: 'folder', parentUUID: repo.uuid, name: 'src' });
+  registry.create({ type: 'file.text', parentUUID: folder.uuid, name: 'index.js', payloadVersion: 'b'.repeat(64) });
+  registry.create({ type: 'link', parentUUID: repo.uuid, name: 'current', payloadVersion: 'src' });
+  assert.equal(db.prepare('SELECT COUNT(*) AS count FROM entity_cloud_mutations').get().count, 1,
+    'worktree children mail no postcards: a register or a rebase is one parcel on the repo entity');
+
+  const catalog = db.prepare('SELECT entity_uuid FROM entity_cloud_catalog WHERE resource_id = ? ORDER BY entity_uuid').all(resourceId)
+    .map((row) => row.entity_uuid).sort();
+  assert.deepEqual(catalog, [root.uuid, repo.uuid].sort(),
+    'the cloud catalog holds the traveling graph only — no rows for repo-enclosed children');
+
+  // A later Detect correction on the child (type/payload) stays local too.
+  const inner = registry.activeAt(folder.uuid, 'index.js');
+  registry.attest(inner.uuid, { type: 'file.binary', payloadVersion: 'c'.repeat(64) });
+  assert.equal(db.prepare('SELECT COUNT(*) AS count FROM entity_cloud_mutations').get().count, 1,
+    'the census drip is dead: child corrections never reach the outbox');
+});
+
+test('an atomic snapshot replacement excludes repo-enclosed records and never demands their bytes', () => {
+  const transportHead = 'd'.repeat(64);
+  const childHead = 'e'.repeat(64);
+  const { db, cloud, registry, root, resourceId } = activeCloud({
+    repoTransportFor: () => transportHead,
+    content: {
+      ensureUpload: () => {},
+      has: ({ contentHash }) => {
+        assert.notEqual(contentHash, childHead, 'an enclosed child head must never be demanded as separate cloud cargo');
+        return true;
+      },
+    },
+  });
+
+  registry.withoutJournal(() => {
+    const repo = registry.create({ type: 'repo.git', parentUUID: root.uuid, name: 'engine', payloadVersion: 'state-1' });
+    registry.create({ type: 'file.text', parentUUID: repo.uuid, name: 'inner.md', payloadVersion: childHead });
+    registry.create({ type: 'file.text', parentUUID: root.uuid, name: 'loose.md', payloadVersion: 'f'.repeat(64) });
+  });
+
+  cloud.replaceSnapshot(registry.syncRecords());
+  const operation = JSON.parse(db.prepare(`
+    SELECT operation_json FROM entity_cloud_mutations
+    WHERE resource_id = ? ORDER BY sequence DESC LIMIT 1
+  `).get(resourceId).operation_json);
+  assert.equal(operation.kind, 'entity.snapshot.replace');
+  const types = operation.snapshot.records.map((record) => record.type).sort();
+  assert.deepEqual(types, ['file.text', 'repo.git', 'workspace'],
+    'the atomic graph carries the workspace, the loose file, and ONE record per repository');
+  assert.ok(!operation.snapshot.records.some((record) => record.name === 'inner.md'),
+    'repo children stay out of the published graph');
+});