amalgm 0.1.249 → 0.1.251

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

@@ -53,11 +53,14 @@ const { classifyFile } = require('./classify');
 const { createEntityCloud } = require('./entity-cloud');
 const { createEntityContent } = require('./entity-content');
 const { createRegistration } = require('./index');
+const { capture, apply: applyRepo } = require('../repocard');
+const { transportBytes, localState, unpack } = require('./repo-states');
 const { machineId, userId } = require('../workspace/identity');
 
 const ENTITIES_DIR = path.join(STORAGE_DIR, 'entities');
 const USER_HOME_CLOUD_CONTRACT = 'amalgm-user-home@1';
 const USER_HOME_CLOUD_SCHEMA_VERSION = 1;
+const ATOMIC_REGISTRATION_THRESHOLD = 500;
 
 let live = null;
 
@@ -80,11 +83,32 @@ function createRegistrationService({
   const evidenceDb = new Database(path.join(dir, 'observer.db'));
   const identityDb = new Database(path.join(dir, 'identity.db'));
   const entityContent = createEntityContent({ dir });
+  // createRegistration owns the schema migration. Give entity-cloud a stable
+  // lookup facade now, then connect it to that one migrated state store once
+  // the boundary exists; never open a second registry just to read Git state.
+  let repoStates = null;
+  const repoStateLookup = { get: (uuid) => repoStates?.get(uuid) || null };
+  const repoTransportHeads = new Map(); // semantic stateId -> immutable content hash
+  const importedRepoStates = new Map(); // cloud UUID -> verified bundle-free state
+
+  /** 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) {
+    if (captured?.busy) return captured;
+    const artifact = entityContent.captureBytes({ bytes: transportBytes(captured) });
+    repoTransportHeads.set(captured.stateId, artifact.contentHash);
+    return localState(captured, artifact.contentHash);
+  }
+
   const entityCloud = createEntityCloud({
     db: identityDb,
     userId: cloudUserId,
     deviceId: cloudDeviceId,
     content: entityContent,
+    repoStates: repoStateLookup,
+    repoTransportFor: (record) => repoTransportHeads.get(record.payloadVersion) || null,
   });
 
   // The observer emits before the boundary exists (its constructor
@@ -103,12 +127,41 @@ function createRegistrationService({
       db: identityDb,
       sentinelPath: path.join(dir, 'identity.epoch'),
       journal: entityCloud.journal,
+      captureRepo: (repoPath) => prepareRepo(capture(repoPath, { withBundle: true })),
+      prepareRepo,
+      repoStateAt: (uuid) => importedRepoStates.get(uuid) || null,
     }),
     classify: classifyFile,
   });
+  repoStates = boundary.current.repoStates;
 
   let closed = false;
 
+  /** Count only the same eligible shape that registration will see.  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. */
+  function estimatedRegistrationRecords(targetPath, limit = ATOMIC_REGISTRATION_THRESHOLD) {
+    let total = 0;
+    const visit = (candidate) => {
+      total += 1;
+      if (total >= limit) return;
+      let stat;
+      try { stat = fs.lstatSync(candidate); } catch { return; }
+      if (!stat.isDirectory() || stat.isSymbolicLink()) return;
+      let entries;
+      try { entries = fs.readdirSync(candidate, { withFileTypes: true }); } catch { return; }
+      for (const entry of entries) {
+        if (total >= limit) return;
+        const child = path.join(candidate, entry.name);
+        if (!shouldEnroll(child)) continue;
+        visit(child);
+      }
+    };
+    visit(targetPath);
+    return total;
+  }
+
   const publicRecord = (record) => ({
     uuid: record.uuid,
     type: record.type,
@@ -304,14 +357,27 @@ function createRegistrationService({
       group.push(record);
       children.set(record.parentUUID, group);
     }
+    function repoState(record) {
+      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`);
+      }
+      return state;
+    }
+
     for (const record of active) {
       if (['file.text', 'file.binary'].includes(record.type)
         && !entityContent.complete({ contentHash: record.payloadVersion })) {
         return false;
       }
+      if (record.type === 'repo.git'
+        && (!record.transportVersion || !entityContent.complete({ contentHash: record.transportVersion }))) {
+        return false;
+      }
     }
-    if (!['workspace', 'file.text', 'file.binary'].includes(root.type)) {
-      throw new Error(`cloud root ${root.uuid} is ${root.type}; this materializer supports workspace and file trees only`);
+    if (!['workspace', 'repo.git', 'file.text', 'file.binary'].includes(root.type)) {
+      throw new Error(`cloud root ${root.uuid} is ${root.type}; this materializer supports workspace, repository, and file trees only`);
     }
 
     const parent = fs.realpathSync(job.targetPath);
@@ -330,6 +396,10 @@ function createRegistrationService({
         }
         return;
       }
+      if (record.type === 'repo.git') {
+        applyRepo(target, repoState(record));
+        return;
+      }
       if (record.type === 'file.text' || record.type === 'file.binary') {
         fs.writeFileSync(target, entityContent.bytes({ contentHash: record.payloadVersion }), { mode: 0o600, flag: 'wx' });
         return;
@@ -351,6 +421,14 @@ function createRegistrationService({
       write(root, staging);
       fs.renameSync(staging, destination);
       promoted = true;
+      // Bind imported repo UUIDs to the verified state before registration's
+      // structural walk. The walk then reuses these facts instead of making
+      // a second bundle while it arms the local Git follower.
+      for (const record of active.filter((candidate) => candidate.type === 'repo.git')) {
+        const state = repoState(record);
+        importedRepoStates.set(record.uuid, localState(state, record.transportVersion));
+        repoTransportHeads.set(state.stateId, record.transportVersion);
+      }
       const bound = boundary.current.add(destination, { identityAt, suppressJournal: true });
       if (bound.record.uuid !== root.uuid) {
         throw new Error(`materialized cloud root ${root.uuid} bound to unexpected local UUID ${bound.record.uuid}`);
@@ -369,11 +447,197 @@ function createRegistrationService({
     }
   }
 
+  /** The local replica of `amalgm add` is Amalgm-managed ground.  This is
+   * deliberately not a two-way directory merger: if local bytes have drifted
+   * from the last authoritative record, the import stops rather than choosing
+   * a winner behind the user's back.  Otherwise a remote cloud head is
+   * projected into the existing binding, with journal suppression so the
+   * receiver never echoes its own download back to cloud. */
+  function applyLiveCloudTree(job) {
+    const tree = entityCloud.catalogTree({ resourceId: job.resourceId, uuid: job.entityUuid });
+    const root = tree[0];
+    const active = tree.filter((record) => record.status === 'active');
+    const unsupported = tree.find((record) => ['link', 'reference'].includes(record.type));
+    if (unsupported) {
+      throw new Error(`live cloud add for ${unsupported.type} is not available yet; the binding was left unchanged`);
+    }
+    if (!['workspace', 'repo.git', 'file.text', 'file.binary'].includes(root.type)) {
+      throw new Error(`cloud root ${root.uuid} is ${root.type}; this live materializer supports workspace, repository, and file trees only`);
+    }
+    for (const record of active) {
+      if (['file.text', 'file.binary'].includes(record.type)
+        && !entityContent.complete({ contentHash: record.payloadVersion })) return false;
+      if (record.type === 'repo.git'
+        && (!record.transportVersion || !entityContent.complete({ contentHash: record.transportVersion }))) return false;
+    }
+
+    const parent = fs.realpathSync(job.targetPath);
+    const destination = path.join(parent, root.name);
+    const boundRoot = boundary.current.tree(destination)?.root();
+    if (!boundRoot || boundRoot.uuid !== root.uuid) {
+      throw new Error(`cloud binding ${root.uuid} no longer owns ${destination}; refusing to overwrite local ground`);
+    }
+
+    const children = new Map();
+    for (const record of active) {
+      if (record.parentUUID === null) continue;
+      const group = children.get(record.parentUUID) || [];
+      group.push(record);
+      children.set(record.parentUUID, group);
+    }
+    for (const group of children.values()) group.sort((left, right) => left.name.localeCompare(right.name));
+
+    function localRecord(uuid) {
+      try { return boundary.current.registry.syncRecord(uuid); } catch { return null; }
+    }
+
+    function addressOf(uuid) {
+      try { return boundary.current.addressOf(uuid); } catch { return null; }
+    }
+
+    function fileHash(file) {
+      return crypto.createHash('sha256').update(fs.readFileSync(file)).digest('hex');
+    }
+
+    function repoState(record) {
+      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`);
+      }
+      return state;
+    }
+
+    // Before changing logical identity, prove that every local byte we could
+    // overwrite is still the byte named by the old authoritative record.
+    // An unsent local edit or an out-of-band edit is a conflict, never an
+    // implicit cloud-wins overwrite.
+    for (const record of tree) {
+      const current = localRecord(record.uuid);
+      if (!current || current.version === record.version) continue;
+      if (entityCloud.hasUnsettledLocalMutation(record.uuid)) {
+        throw new Error(`local change for ${record.uuid} is still waiting for cloud; refusing to overwrite it`);
+      }
+      if (current.type === 'repo.git') {
+        const currentPath = addressOf(record.uuid);
+        const observed = currentPath && fs.existsSync(currentPath)
+          ? capture(currentPath, { withBundle: false })
+          : null;
+        if (!observed || observed.busy || observed.stateId !== current.payloadVersion) {
+          throw new Error(`local repository ${currentPath || record.uuid} changed outside Amalgm; refusing to overwrite it`);
+        }
+        continue;
+      }
+      if (!['file.text', 'file.binary'].includes(current.type)) continue;
+      const currentPath = addressOf(record.uuid);
+      if (!currentPath || !fs.existsSync(currentPath)) {
+        throw new Error(`local file for ${record.uuid} is missing; refusing to overwrite an unverified binding`);
+      }
+      if (fileHash(currentPath) !== current.payloadVersion) {
+        throw new Error(`local file ${currentPath} changed outside Amalgm; refusing to overwrite it`);
+      }
+    }
+
+    function applyKnownRecords() {
+      // Catalog container versions are deliberately regenerated by the
+      // authority after child mutations.  Applying an unchanged container
+      // before its later child would therefore compare an old derived version.
+      // Only import records whose stored logical fields actually changed; the
+      // local registry derives the same container version after the child lands.
+      const depth = new Map([[root.uuid, 0]]);
+      for (const record of tree) {
+        if (record.parentUUID !== null) depth.set(record.uuid, (depth.get(record.parentUUID) || 0) + 1);
+      }
+      for (const record of [...tree].sort((left, right) => (depth.get(left.uuid) || 0) - (depth.get(right.uuid) || 0))) {
+        const current = localRecord(record.uuid);
+        if (current && current.type === record.type && current.parentUUID === record.parentUUID
+          && current.name === record.name && current.status === record.status
+          && current.payloadVersion === record.payloadVersion) continue;
+        boundary.current.registry.applyCloudRecord(record);
+      }
+    }
+
+    function atomicWrite(file, bytes) {
+      const temporary = path.join(path.dirname(file), `.${path.basename(file)}.amalgm-live-${crypto.randomBytes(10).toString('hex')}`);
+      try {
+        fs.writeFileSync(temporary, bytes, { mode: 0o600, flag: 'wx' });
+        fs.renameSync(temporary, file);
+      } finally {
+        fs.rmSync(temporary, { force: true });
+      }
+    }
+
+    function removeInactiveChild(parentRecord, name, target) {
+      const known = boundary.current.registry.children(parentRecord.uuid)
+        .find((candidate) => candidate.name === name);
+      if (!known || known.status === 'active') {
+        throw new Error(`local item ${target} is not owned by this cloud binding; refusing to remove it`);
+      }
+      if (['file.text', 'file.binary'].includes(known.type) && fs.existsSync(target)) {
+        const previous = localRecord(known.uuid);
+        if (previous?.payloadVersion && fileHash(target) !== previous.payloadVersion) {
+          throw new Error(`local file ${target} changed outside Amalgm; refusing to remove it`);
+        }
+      }
+      fs.rmSync(target, { recursive: true, force: true });
+    }
+
+    function project(record, target) {
+      if (record.type === 'workspace' || record.type === 'folder') {
+        if (fs.existsSync(target)) {
+          if (!fs.statSync(target).isDirectory()) {
+            throw new Error(`cloud container ${record.uuid} conflicts with local non-directory ${target}`);
+          }
+        } else {
+          fs.mkdirSync(target, { mode: 0o700 });
+        }
+        const wanted = new Set((children.get(record.uuid) || []).map((child) => child.name));
+        for (const child of children.get(record.uuid) || []) project(child, path.join(target, child.name));
+        for (const entry of fs.readdirSync(target)) {
+          if (!wanted.has(entry)) removeInactiveChild(record, entry, path.join(target, entry));
+        }
+        return;
+      }
+      if (record.type === 'repo.git') {
+        applyRepo(target, repoState(record));
+        return;
+      }
+      if (!['file.text', 'file.binary'].includes(record.type)) {
+        throw new Error(`cloud entity ${record.uuid} is ${record.type}; this live materializer cannot write it`);
+      }
+      if (fs.existsSync(target) && fs.statSync(target).isDirectory()) {
+        throw new Error(`cloud file ${record.uuid} conflicts with local directory ${target}`);
+      }
+      const bytes = entityContent.bytes({ contentHash: record.payloadVersion });
+      if (fs.existsSync(target) && Buffer.compare(fs.readFileSync(target), bytes) === 0) return;
+      atomicWrite(target, bytes);
+    }
+
+    boundary.current.registry.withoutJournal(() => {
+      for (const record of active.filter((candidate) => candidate.type === 'repo.git')) {
+        const state = repoState(record);
+        repoStates.put(record.uuid, localState(state, record.transportVersion));
+        repoTransportHeads.set(state.stateId, record.transportVersion);
+      }
+      applyKnownRecords();
+      project(root, destination);
+      const observerRoot = observer.listRoots().find((entry) => entry.path === destination);
+      if (!observerRoot) throw new Error(`cloud binding ${root.uuid} has no local watcher root at ${destination}`);
+      observer.scanNow(observerRoot.rootId);
+      boundary.current.flushIfDirty();
+    });
+    return { destination, root };
+  }
+
   function advanceMaterializations() {
     for (const job of entityCloud.pendingMaterializations()) {
       if (job.state !== 'waiting_for_content') continue;
       try {
-        const result = materializeCloudTree(job);
+        const root = entityCloud.catalogTree({ resourceId: job.resourceId, uuid: job.entityUuid })[0];
+        const destination = path.join(fs.realpathSync(job.targetPath), root.name);
+        const result = boundary.current.tree(destination)?.root()?.uuid === root.uuid
+          ? applyLiveCloudTree(job)
+          : materializeCloudTree(job);
         if (result) entityCloud.completeMaterialization({ jobId: job.jobId });
       } catch (error) {
         entityCloud.failMaterialization({ jobId: job.jobId, message: error.message });
@@ -389,12 +653,26 @@ function createRegistrationService({
     /** `amalgm register <path>` — register, then begin Watch + Detect. */
     register: async (targetPath) => {
       entityCloud.assertRegistrationReady();
-      return boundary.current.add(targetPath);
+      if (estimatedRegistrationRecords(targetPath) < ATOMIC_REGISTRATION_THRESHOLD) {
+        return boundary.current.add(targetPath);
+      }
+      const result = boundary.current.registry.withoutJournal(() => boundary.current.add(targetPath));
+      entityCloud.replaceSnapshot(boundary.current.registry.syncRecords());
+      return result;
     },
-    /** `amalgm register <path>...` — the same primitive for each selected root. */
+    /** `amalgm register <path>...` — the same primitive for each selected root.
+     * A large tree has one atomic cloud replacement record: partial graph
+     * acknowledgements would make an R2 active head that no receiver may
+     * materialize. Small selections retain their ordinary per-entity intent. */
     registerMany: async (targetPaths) => {
       entityCloud.assertRegistrationReady();
-      return boundary.current.addMany(targetPaths);
+      const needsAtomicReplacement = targetPaths.some((targetPath) => (
+        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;
     },
     /** `amalgm add <cloud-root-uuid> [parent-directory]` — cloud to local. */
     add: async ({ uuid, targetPath }) => {
@@ -402,6 +680,27 @@ function createRegistrationService({
       advanceMaterializations();
       return entityCloud.materializationStatus(job.jobId);
     },
+    /** The inbound realtime rail is part of the add binding.  Routes call
+     * these composition methods so receiving an authoritative record or one
+     * of its immutable content parts immediately advances the local replica;
+     * users never run a separate sync command. */
+    ingestCloudMutation: ({ envelope, version, committedAt }) => {
+      const ingested = entityCloud.ingest({
+        registry: boundary.current.registry,
+        envelope,
+        version,
+        committedAt,
+      });
+      advanceMaterializations();
+      return ingested;
+    },
+    receiveCloudContent: ({ resourceId, contentHash, kind, partIndex, sha256, dataBase64 }) => {
+      const received = entityCloud.receiveDownload({
+        resourceId, contentHash, kind, partIndex, sha256, dataBase64,
+      });
+      advanceMaterializations();
+      return received;
+    },
     advanceMaterializations,
     bootstrapUserHome,
     exactUserHomeCloudRecords,

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

@@ -28,6 +28,7 @@
 
 const fs = require('fs');
 const path = require('path');
+const crypto = require('crypto');
 
 function rootType(rootPath, kind) {
   if (kind === 'repo') return 'repo.git';
@@ -55,7 +56,7 @@ function isRepository(dirPath) {
  * directory ground. The caller supplies a root that is already known to the
  * observer but is not yet watched or scanned.
  */
-function registerTree({ root, registry, memory, shouldEnroll, captureRepo, repoStates, identityAt = null }) {
+function registerTree({ root, registry, memory, shouldEnroll, captureRepo, repoStates, identityAt = null, repoStateAt = null }) {
   if (!root || !registry || !memory || typeof shouldEnroll !== 'function'
     || typeof captureRepo !== 'function' || !repoStates) {
     throw new Error('registerTree requires { root, registry, memory, shouldEnroll, captureRepo, repoStates }');
@@ -93,23 +94,42 @@ 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) {
+    if (identity.uuid) {
+      const imported = repoStateAt?.(identity.uuid);
+      if (imported?.stateId === identity.payloadVersion) return imported;
+      const saved = repoStates.get(identity.uuid);
+      if (saved?.stateId === identity.payloadVersion) return saved;
+    }
+    return captureInitialRepo(repoPath, captureRepo);
+  }
+
   return registry.transaction(() => {
-    const initialState = root.kind === 'repo' ? captureInitialRepo(root.path, captureRepo) : null;
     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;
+    // 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 record = registry.enrollRoot({
       type: rootIdentity.type,
       name: path.basename(root.path),
       payloadVersion: initialState?.stateId ?? rootIdentity.payloadVersion ?? null,
-      uuid: rootIdentity.uuid,
+      uuid: rootUuid,
     });
     memory.bind(root.rootId, root.rootId, record.uuid);
     if (initialState) repoStates.put(record.uuid, initialState);
 
     if (root.kind === 'files' || root.kind === 'repo') {
       registerDirectory(root.path, record.uuid, {
-        registry, shouldEnroll, captureRepo, repoStates, identityAt, seeded, relativePath: '',
+        registry, shouldEnroll, captureRepo, repoStates, identityAt, repoStateAt, repoStateFor, seeded, relativePath: '',
       });
     }
     return record;
@@ -128,7 +148,7 @@ function captureInitialRepo(repoPath, captureRepo) {
 }
 
 function registerDirectory(dirPath, parentUUID, {
-  registry, shouldEnroll, captureRepo, repoStates, identityAt, seeded, relativePath,
+  registry, shouldEnroll, captureRepo, repoStates, identityAt, repoStateAt, repoStateFor, seeded, relativePath,
 }) {
   let entries;
   try {
@@ -157,20 +177,21 @@ function registerDirectory(dirPath, parentUUID, {
     }
     if (stat.isDirectory()) {
       const type = isRepository(entryPath) ? 'repo.git' : 'folder';
-      const state = type === 'repo.git' ? captureInitialRepo(entryPath, captureRepo) : null;
       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 record = registry.create({
         type: identity.type,
         parentUUID,
         name: entry.name,
         payloadVersion: state?.stateId ?? identity.payloadVersion ?? null,
-        uuid: identity.uuid,
+        uuid,
       });
       if (state) repoStates.put(record.uuid, state);
       registerDirectory(entryPath, record.uuid, {
-        registry, shouldEnroll, captureRepo, repoStates, identityAt, seeded, relativePath: entryRelativePath,
+        registry, shouldEnroll, captureRepo, repoStates, identityAt, repoStateAt, repoStateFor, seeded, relativePath: entryRelativePath,
       });
       continue;
     }

package/runtime/scripts/amalgm-mcp/server/routes/entities.js

@@ -240,7 +240,7 @@ async function handleEntityRoutes(ctx) {
     const body = await ctx.readJsonBody();
     const service = registrationService();
     try {
-      const received = service.entityCloud.receiveDownload({
+      const received = service.receiveCloudContent({
         resourceId: body?.resourceId,
         contentHash: body?.contentHash,
         kind: body?.kind,
@@ -248,7 +248,6 @@ async function handleEntityRoutes(ctx) {
         sha256: body?.sha256,
         dataBase64: body?.dataBase64,
       });
-      service.advanceMaterializations();
       ctx.sendJson(200, { ...received });
     } catch (error) {
       ctx.sendJson(400, { error: error.message });
@@ -290,12 +289,12 @@ async function handleEntityRoutes(ctx) {
     const body = await ctx.readJsonBody();
     const service = registrationService();
     try {
-      ctx.sendJson(200, service.entityCloud.ingest({
-        registry: service.registration.registry,
+      const ingested = service.ingestCloudMutation({
         envelope: body?.envelope,
         version: body?.version,
         committedAt: body?.committedAt,
-      }));
+      });
+      ctx.sendJson(200, ingested);
     } catch (error) {
       ctx.sendJson(409, { error: error.message });
     }

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

@@ -76,6 +76,56 @@ test('a signed-in registration is refused until the cloud entity resource is act
   assert.doesNotThrow(() => cloud.assertRegistrationReady());
 });
 
+test('a large registration replaces the complete graph in one cloud operation and a recipient waits for its compacted snapshot', () => {
+  const db = new Database(':memory:');
+  const cloud = createEntityCloud({ db, userId: 'user-1', deviceId: 'device-1' });
+  const registry = createRegistry({ db, ephemeral: true, emit: () => {}, journal: cloud.journal });
+  const root = registry.enrollRoot({ type: 'workspace', name: 'large-ground' });
+  const bootstrap = cloud.bootstrap(registry);
+  cloud.install({
+    registry,
+    resourceId: bootstrap.resourceId,
+    authorityEpoch: 1,
+    headVersion: 0,
+    snapshotBase64: bootstrap.snapshotBase64,
+    snapshotChecksum: bootstrap.snapshotChecksum,
+  });
+  registry.withoutJournal(() => {
+    for (let index = 0; index < 600; index += 1) {
+      registry.create({ type: 'folder', parentUUID: root.uuid, name: `folder-${index}` });
+    }
+  });
+  const replacement = cloud.replaceSnapshot(registry.syncRecords());
+  assert.equal(replacement.records, 601);
+  assert.equal(db.prepare('SELECT COUNT(*) AS count FROM entity_cloud_mutations').get().count, 1);
+  const claim = cloud.claim();
+  assert.equal(claim.length, 1);
+  assert.equal(claim[0].operationKind, 'entity.snapshot.replace');
+  assert.equal(claim[0].operation.snapshot.records.length, 601);
+
+  const recipientDb = new Database(':memory:');
+  const recipient = createEntityCloud({ db: recipientDb, userId: 'user-1', deviceId: 'device-2' });
+  const recipientRegistry = createRegistry({ db: recipientDb, ephemeral: true, emit: () => {}, journal: recipient.journal });
+  recipient.install({
+    registry: recipientRegistry,
+    resourceId: bootstrap.resourceId,
+    authorityEpoch: 1,
+    headVersion: 0,
+    snapshotBase64: bootstrap.snapshotBase64,
+    snapshotChecksum: bootstrap.snapshotChecksum,
+  });
+  const inbound = recipient.ingest({
+    registry: recipientRegistry,
+    envelope: { ...claim[0], operationKind: 'entity.snapshot.replace' },
+    version: 1,
+    committedAt: '2026-08-05T00:00:00.000Z',
+  });
+  assert.equal(inbound.snapshotRequired, true);
+  assert.equal(recipient.replica().headVersion, 1);
+  assert.deepEqual(recipientRegistry.syncRecords(), [], 'the replacement tail never becomes partially bound local identity');
+  recipientDb.close();
+});
+
 test('only an exact verified bootstrap graph can repair a legacy empty entity resource', () => {
   const db = new Database(':memory:');
   const cloud = createEntityCloud({ db, userId: 'user-1', deviceId: 'device-1' });