amalgm 0.1.262 → 0.1.264

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

@@ -15,8 +15,10 @@
  * (its own future head and rail), never an identity boundary. Every
  * top-level enrolled ground — a workspace, a repository, a single file,
  * or an explicitly added link — is such a tree, with one evidence LENS
- * over its observer root (nested repo territories live INSIDE their
- * tree as repo.git records; they are never trees of their own). A
+ * over its observer root. A Git territory noticed inside another watched
+ * tree is observer-only until an explicit registration admits it; that
+ * selected repo is then a tree of its own even if the outer watcher covers
+ * its local address. A
  * TREE'S IDENTITY IS ITS UUID, PERMANENT; its root path is only the
  * current local address — lenses are keyed by the observer's rootId
  * (the witness), the observer rescues moved ground by physical
@@ -66,6 +68,7 @@ const { refusal } = require('./refusal');
 const { createRepoFollowers } = require('./repo-followers');
 const { createRepoStates } = require('./repo-states');
 const { registerTree } = require('./tree');
+const { gitDirTruth } = require('../observer/scan');
 
 // Events that can change what the recorded edges reach: a new or
 // retargeted pointer, repo ground moving under its card (a worktree
@@ -112,12 +115,27 @@ function createRegistration(options) {
     onSettled: reconcileSettledRepo,
   });
 
-  /** Tree roots are the non-enclosed observer roots: a nested repo
-   * territory belongs to the tree that encloses it. */
+  /**
+   * A semantic tree is defined by its parentless identity record, never by
+   * directory containment.  `amalgm add` may materialize a cloud repo inside
+   * the local `workspaces/` directory, and `amalgm register` may select a
+   * repo already sitting there: both remain their own cloud root.  The outer
+   * workspace watcher supplies coverage, but it does not own the repo's
+   * Card + Checkpoint or identity tree.
+   *
+   * An unbound observer root is a tree candidate only when no other observer
+   * root physically encloses it.  That preserves the admission rule for a
+   * newly discovered nested repo: Watch can notice it, but only explicit
+   * registration can give it a cloud identity and state.
+   */
   function treeRoots() {
     const roots = observer.listRoots();
-    return roots.filter((root) => !roots.some((other) =>
-      other.rootId !== root.rootId && root.path.startsWith(`${other.path}/`)));
+    return roots.filter((root) => {
+      const record = rootRecordOf(root.rootId);
+      if (record) return record.parentUUID === null;
+      return !roots.some((other) => other.rootId !== root.rootId
+        && root.path.startsWith(`${other.path}/`));
+    });
   }
 
   function treeRootCovering(absPath) {
@@ -359,6 +377,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)
@@ -376,6 +431,75 @@ function createRegistration(options) {
     }
   }
 
+  /**
+   * A repository selected inside already-watched ground is still a new
+   * registered TREE, not a child record of the outer workspace.  The outer
+   * watcher already knows its territory (or this enrollment establishes that
+   * same territory), so the only missing fact is the repo's atomic
+   * Card+Checkpoint-backed identity birth.
+   */
+  function registerRepositoryInsideCoveredGround(ground, { identityAt = null, suppressJournal = false } = {}) {
+    let root = observer.listRoots().find((candidate) => candidate.path === ground) || null;
+    if (!root) root = observer.enrollRoot(ground, { scan: false, watch: false });
+    if (root.kind !== 'repo') {
+      throw new Error(`expected Git repository ground at ${ground}, found ${root.kind}`);
+    }
+
+    const bound = memory.boundTo(root.rootId);
+    if (bound !== undefined) {
+      const record = registry.record(bound);
+      if (record?.type !== 'repo.git') {
+        throw new Error(`repository watcher ${ground} is bound to non-repository entity ${bound}`);
+      }
+      if (record.parentUUID !== null) {
+        // This is the explicit nested-boundary case created as part of an
+        // already-registered enclosing repo.  It already has a complete
+        // Card+Checkpoint state and cannot be duplicated at one address.
+        requireLiveWatchers(ground);
+        return { rootPath: ground, record };
+      }
+      requireLiveWatchers(ground);
+      return { rootPath: ground, record };
+    }
+
+    try {
+      requireWatchBirth(root);
+      assertWitnessed({ observer, registry, memory });
+      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) {
+      // A root that existed only because the outer watcher discovered its
+      // territory must remain coverage after a refused explicit admission;
+      // do not remove it (the parent still owns the OS watcher).  A root this
+      // call itself enrolled has no durable identity and can safely retire.
+      throw error;
+    }
+
+    const startWatch = () => {
+      observer.start(root.rootId);
+      ensureTrees();
+      reconcileInitialRepoWorktrees(root.path);
+      flushIfDirty();
+      requireLiveWatchers(root.path);
+    };
+    if (suppressJournal) registry.withoutJournal(startWatch);
+    else startWatch();
+    return { rootPath: root.path, record: rootRecordOf(root.rootId) };
+  }
+
   /** Real ground -> the UUID of the entity that owns it, across trees. */
   function resolveGround(real) {
     const home = treeRootCovering(real);
@@ -505,6 +629,23 @@ function createRegistration(options) {
     }
     const covering = treeRootCovering(ground);
     if (covering) {
+      // A repository has a different state adapter from the workspace that
+      // happens to contain its local address.  Its observer territory may
+      // already exist, but it is not registered until this explicit command
+      // creates the parentless repo tree with its initial Card + Checkpoint.
+      // The same branch is used by cloud `add`: materialized repos commonly
+      // land under the default `workspaces/` directory while retaining their
+      // cloud root UUID and parentless graph position.
+      const isRepository = fs.lstatSync(ground).isDirectory() && gitDirTruth(ground) === 'present';
+      if (isRepository) {
+        const exact = observer.listRoots().find((root) => root.path === ground);
+        const known = exact && memory.boundTo(exact.rootId) !== undefined
+          ? registry.record(memory.boundTo(exact.rootId))
+          : null;
+        if (!known || known.type !== 'repo.git' || known.parentUUID === null) {
+          return registerRepositoryInsideCoveredGround(ground, { identityAt, suppressJournal });
+        }
+      }
       // This address is already registered ground. Its prior Register →
       // Watch transition remains the proof of its identity; repeating a
       // harmless "ensure the safe home exists" request must not rescan every
@@ -525,24 +666,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 },
   };
 }

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

@@ -52,6 +52,7 @@ const {
   migrateLegacyToolboxCatalog,
 } = require('../toolbox/artifacts');
 const { createObserver } = require('../observer');
+const { gitDirTruth } = require('../observer/scan');
 const { shouldEnroll } = require('../workspace/tree/inclusion');
 const { classifyFile } = require('./classify');
 const { createEntityCloud } = require('./entity-cloud');
@@ -106,13 +107,37 @@ function createRegistrationService({
   const repoTransportHeads = new Map(); // semantic stateId -> immutable content hash
   const importedRepoStates = new Map(); // cloud UUID -> verified bundle-free state
 
+  /** The identity map a settled repo state travels with: every enrolled
+   * record beneath the repo boundary (stopping at nested repo boundaries,
+   * which pack their own maps). Repo children never journal their own
+   * cloud mutations, so this map — inside the one transport parcel — is
+   * the only way their permanent UUIDs reach another machine. */
+  function worktreeIdentity(repoUuid) {
+    const registry = boundary.current?.registry;
+    if (!registry) return null;
+    const entries = [];
+    const visit = (parentUuid, base) => {
+      for (const child of registry.children(parentUuid)) {
+        if (child.status !== 'active') continue;
+        const childPath = base ? `${base}/${child.name}` : child.name;
+        entries.push({ path: childPath, uuid: child.uuid, type: child.type });
+        if (child.type === 'folder') visit(child.uuid, childPath);
+      }
+    };
+    visit(repoUuid, '');
+    return entries;
+  }
+
   /** Git transport is immutable content, not identity-database cargo.  The
    * semantic repo stateId remains the entity head; this prepares the exact
    * Card + Checkpoint + bundle payload and leaves only its content hash in
-   * SQLite so a large clone cannot bloat the device registry. */
-  function prepareRepo(captured) {
+   * SQLite so a large clone cannot bloat the device registry. Registration
+   * supplies the freshly assigned identity entries; a settled follower
+   * names its repo UUID instead and the map is read from the registry. */
+  function prepareRepo(captured, { identity = null, entityUuid = null } = {}) {
     if (captured?.busy) return captured;
-    const artifact = entityContent.captureBytes({ bytes: transportBytes(captured) });
+    const transportIdentity = identity ?? (entityUuid ? worktreeIdentity(entityUuid) : null);
+    const artifact = entityContent.captureBytes({ bytes: transportBytes(captured, transportIdentity) });
     repoTransportHeads.set(captured.stateId, artifact.contentHash);
     return localState(captured, artifact.contentHash);
   }
@@ -148,7 +173,7 @@ function createRegistrationService({
       db: identityDb,
       sentinelPath: path.join(dir, 'identity.epoch'),
       journal: entityCloud.journal,
-      captureRepo: (repoPath) => prepareRepo(capture(repoPath, { withBundle: true })),
+      captureRepo: (repoPath, options) => prepareRepo(capture(repoPath, { withBundle: true }), options),
       prepareRepo,
       repoStateAt: (uuid) => importedRepoStates.get(uuid) || null,
     }),
@@ -158,10 +183,12 @@ function createRegistrationService({
 
   let closed = false;
 
-  /** Count only the same eligible shape that registration will see.  This is
+  /** Count only the records that will actually TRAVEL to the cloud.  This is
    * not a second registration walker: it is a bounded routing decision that
    * lets a large tree use one atomic cloud graph replacement instead of
-   * thousands of individually compacted mutations. */
+   * thousands of individually compacted mutations. A repository counts as
+   * ONE — its children ride the transport parcel, never the cloud graph —
+   * so registering even a 40,000-file repo is a single ordinary mutation. */
   function estimatedRegistrationRecords(targetPath, limit = ATOMIC_REGISTRATION_THRESHOLD) {
     let total = 0;
     const visit = (candidate) => {
@@ -170,6 +197,7 @@ function createRegistrationService({
       let stat;
       try { stat = fs.lstatSync(candidate); } catch { return; }
       if (!stat.isDirectory() || stat.isSymbolicLink()) return;
+      if (gitDirTruth(candidate) === 'present') return;
       let entries;
       try { entries = fs.readdirSync(candidate, { withFileTypes: true }); } catch { return; }
       for (const entry of entries) {
@@ -482,15 +510,50 @@ function createRegistrationService({
       group.push(record);
       children.set(record.parentUUID, group);
     }
+    // Unpacking a transport decodes the whole bundle from base64; one unpack
+    // per repository, not one per caller.
+    const repoStatesByUuid = new Map();
     function repoState(record) {
+      const cached = repoStatesByUuid.get(record.uuid);
+      if (cached) return cached;
       if (!record.transportVersion) throw new Error(`cloud repository ${record.uuid} has no Repocard transport head`);
       const state = unpack(entityContent.bytes({ contentHash: record.transportVersion }));
       if (state.stateId !== record.payloadVersion) {
         throw new Error(`cloud repository ${record.uuid} transport does not name its declared state`);
       }
+      repoStatesByUuid.set(record.uuid, state);
       return state;
     }
 
+    /** The identity a repo's transport carries for one worktree address:
+     * the same permanent UUID the registering machine minted, synthesized
+     * into the record shape the structural walk verifies. Records under a
+     * repository no longer live in the cloud catalog — the map inside the
+     * one state parcel is their identity carrier. */
+    function repoChildIdentity(repoRecord, repoRelativePath) {
+      const state = repoState(repoRecord);
+      if (!Array.isArray(state.identity)) return null;
+      const byPath = state.identityByPath
+        || (state.identityByPath = new Map(state.identity.map((entry) => [entry.path, entry])));
+      const entry = byPath.get(repoRelativePath);
+      if (!entry) return null;
+      // A nested repository does not travel (the repo travel law), so the
+      // transport cannot promise this ground materializes as a repo here.
+      // The receiving walk decides what the ground actually is and mints
+      // fresh local identity for it.
+      if (entry.type === 'repo.git') return null;
+      const slash = repoRelativePath.lastIndexOf('/');
+      const parentEntry = slash === -1 ? null : byPath.get(repoRelativePath.slice(0, slash));
+      return {
+        uuid: entry.uuid,
+        type: entry.type,
+        parentUUID: parentEntry ? parentEntry.uuid : repoRecord.uuid,
+        name: repoRelativePath.slice(slash + 1),
+        status: 'active',
+        payloadVersion: null,
+      };
+    }
+
     for (const { contentHash } of entityCloud.contentHeads(active)) {
       if (!entityContent.complete({ contentHash })) return false;
     }
@@ -535,9 +598,21 @@ function createRegistrationService({
     function identityAt(relativePath) {
       if (!relativePath) return root;
       let cursor = root;
-      for (const name of relativePath.split('/')) {
-        cursor = (children.get(cursor.uuid) || []).find((record) => record.name === name) || null;
-        if (!cursor) return null;
+      const parts = relativePath.split('/');
+      for (let index = 0; index < parts.length; index += 1) {
+        const next = (children.get(cursor.uuid) || []).find((record) => record.name === parts[index]) || null;
+        if (next) {
+          cursor = next;
+          continue;
+        }
+        // Inside a repository boundary the catalog goes quiet: the rest of
+        // the address is answered by that repo's transport identity map.
+        // (A snapshot from before the repo travel law still carries child
+        // records; those keep answering above, exactly as they used to.)
+        if (cursor.type === 'repo.git') {
+          return repoChildIdentity(records.get(cursor.uuid) || cursor, parts.slice(index).join('/'));
+        }
+        return null;
       }
       return records.get(cursor.uuid) || null;
     }
@@ -621,12 +696,18 @@ function createRegistrationService({
       return crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex');
     }
 
+    // One unpack per repository: the live projection consults the same
+    // state for its drift check, its registry preload, and its apply.
+    const repoStatesByUuid = new Map();
     function repoState(record) {
+      const cached = repoStatesByUuid.get(record.uuid);
+      if (cached) return cached;
       if (!record.transportVersion) throw new Error(`cloud repository ${record.uuid} has no Repocard transport head`);
       const state = unpack(entityContent.bytes({ contentHash: record.transportVersion }));
       if (state.stateId !== record.payloadVersion) {
         throw new Error(`cloud repository ${record.uuid} transport does not name its declared state`);
       }
+      repoStatesByUuid.set(record.uuid, state);
       return state;
     }
 
@@ -908,9 +989,15 @@ function createRegistrationService({
           estimatedRegistrationRecords(targetPath) >= ATOMIC_REGISTRATION_THRESHOLD
         ));
       if (!needsAtomicReplacement) return boundary.current.addMany(targetPaths);
-      const results = boundary.current.registry.withoutJournal(() => boundary.current.addMany(targetPaths));
-      entityCloud.replaceSnapshot(boundary.current.registry.syncRecords());
-      return results;
+      // The snapshot must describe whatever actually committed, even when a
+      // later path refuses (each path is durable alone): without journal
+      // rows, a committed-but-unsnapshotted registration would be local
+      // truth with zero cloud delivery intent — a ghost nothing repairs.
+      try {
+        return boundary.current.registry.withoutJournal(() => boundary.current.addMany(targetPaths));
+      } finally {
+        entityCloud.replaceSnapshot(boundary.current.registry.syncRecords());
+      }
     },
     /** `amalgm add <cloud-root-uuid> [parent-directory]` — cloud to local. */
     add: async ({ uuid, targetPath }) => {