amalgm 0.1.246 → 0.1.247

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

@@ -167,6 +167,121 @@ function createEntityCloud({ db, userId, deviceId, content = null }) {
     );
   }
 
+  /** The catalog is the cloud graph imported at one verified snapshot head.
+   * It deliberately lives outside `entities`: a catalog record has no local
+   * address, evidence, or watcher claim until `amalgm add` binds it. */
+  function replaceCatalog({ resourceId, authorityEpoch, headVersion, records }) {
+    const normalized = snapshotFromRecords(records).records;
+    db.transaction(() => {
+      db.prepare('DELETE FROM entity_cloud_catalog WHERE resource_id = ?').run(resourceId);
+      const insert = db.prepare(`
+        INSERT INTO entity_cloud_catalog (
+          resource_id, entity_uuid, record_json, snapshot_epoch,
+          snapshot_version, updated_at
+        ) VALUES (?, ?, ?, ?, ?, ?)
+      `);
+      for (const record of normalized) {
+        insert.run(resourceId, record.uuid, stableJson(record), authorityEpoch, headVersion, now());
+      }
+      // This marker is intentionally separate from the rows it describes.
+      // A later mutation may update an individual catalog row so live state
+      // can be inspected, but that must never make the whole catalog look
+      // like a newly compacted snapshot that is safe to materialize.
+      db.prepare(`
+        INSERT INTO entity_cloud_catalog_state (
+          singleton, resource_id, authority_epoch, snapshot_version, updated_at
+        ) VALUES (1, ?, ?, ?, ?)
+        ON CONFLICT(singleton) DO UPDATE SET
+          resource_id = excluded.resource_id,
+          authority_epoch = excluded.authority_epoch,
+          snapshot_version = excluded.snapshot_version,
+          updated_at = excluded.updated_at
+      `).run(resourceId, authorityEpoch, headVersion, now());
+    })();
+    return normalized;
+  }
+
+  function catalogRecords(resourceId) {
+    return db.prepare(`
+      SELECT record_json FROM entity_cloud_catalog
+      WHERE resource_id = ?
+      ORDER BY entity_uuid
+    `).all(resourceId).map((row) => assertRecord(JSON.parse(row.record_json)));
+  }
+
+  function upsertCatalogRecord({ resourceId, authorityEpoch, headVersion, record }) {
+    const normalized = assertRecord(record);
+    db.prepare(`
+      INSERT INTO entity_cloud_catalog (
+        resource_id, entity_uuid, record_json, snapshot_epoch,
+        snapshot_version, updated_at
+      ) VALUES (?, ?, ?, ?, ?, ?)
+      ON CONFLICT(resource_id, entity_uuid) DO UPDATE SET
+        record_json = excluded.record_json,
+        snapshot_epoch = excluded.snapshot_epoch,
+        snapshot_version = excluded.snapshot_version,
+        updated_at = excluded.updated_at
+    `).run(resourceId, normalized.uuid, stableJson(normalized), authorityEpoch, headVersion, now());
+    return normalized;
+  }
+
+  function catalogTree({ resourceId, uuid }) {
+    const records = catalogRecords(resourceId);
+    const byUuid = new Map(records.map((record) => [record.uuid, record]));
+    const root = byUuid.get(String(uuid || '').toLowerCase());
+    if (!root) throw new Error(`cloud entity ${uuid} is not available on this machine`);
+    if (root.parentUUID !== null) {
+      throw new Error('amalgm add currently materializes a cloud tree root; select the parentless workspace, repository, file, or link UUID');
+    }
+    const children = new Map();
+    for (const record of records) {
+      if (record.parentUUID === null) continue;
+      const group = children.get(record.parentUUID) || [];
+      group.push(record);
+      children.set(record.parentUUID, group);
+    }
+    const tree = [];
+    const visit = (record) => {
+      tree.push(record);
+      for (const child of (children.get(record.uuid) || []).sort((left, right) => left.name.localeCompare(right.name))) {
+        visit(child);
+      }
+    };
+    visit(root);
+    return tree;
+  }
+
+  function currentCatalog() {
+    const current = replica();
+    if (!current || current.state !== 'active') {
+      throw new Error('entity cloud registry is not ready yet; wait for the signed-in runtime to finish its cloud handshake');
+    }
+    const snapshot = db.prepare(`
+      SELECT resource_id, authority_epoch, snapshot_version
+      FROM entity_cloud_catalog_state WHERE singleton = 1
+    `).get();
+    if (!snapshot || snapshot.resource_id !== current.resourceId
+      || Number(snapshot.authority_epoch) !== current.authorityEpoch
+      || Number(snapshot.snapshot_version) !== current.headVersion) {
+      throw new Error('entity cloud catalog is not pinned to the active cloud head yet; retry after the next snapshot handshake');
+    }
+    return current;
+  }
+
+  function materialization(row) {
+    if (!row) return null;
+    return {
+      jobId: row.job_id,
+      resourceId: row.resource_id,
+      entityUuid: row.entity_uuid,
+      targetPath: row.target_path,
+      authorityEpoch: Number(row.authority_epoch),
+      headVersion: Number(row.head_version),
+      state: row.state,
+      error: row.error,
+    };
+  }
+
   /** Invoked by registry/index.js INSIDE its identity transaction. */
   function journal({ record }) {
     const current = replica();
@@ -177,6 +292,12 @@ function createEntityCloud({ db, userId, deviceId, content = null }) {
     // content drain creates the filesystem upload cursor; doing that here
     // would let a rolled-back identity write upload unreachable bytes.
     queueContent(record, current.resourceId);
+    upsertCatalogRecord({
+      resourceId: current.resourceId,
+      authorityEpoch: current.authorityEpoch,
+      headVersion: current.headVersion,
+      record,
+    });
     const mutationId = `ent_${crypto.randomBytes(18).toString('base64url')}`;
     const operation = { kind: 'entity.upsert', record: assertRecord(record) };
     const createdAt = now();
@@ -239,20 +360,30 @@ function createEntityCloud({ db, userId, deviceId, content = null }) {
     if (bootstrapping && !sameRecord(local, snapshot)) {
       throw new Error('first cloud entity snapshot does not match the locally bootstrapped identity graph');
     }
-    if (!bootstrapping && !sameRecord(local, snapshot)) {
-      // Import is intentionally delayed until the materializer can bind every
-      // extra root deliberately. Failing loudly is safer than silently
-      // treating a remote entity as watched local ground.
-      throw new Error('cloud entity graph differs from this local registry; materialization import is not enabled for this runtime yet');
+    if (!bootstrapping) {
+      const cloudByUuid = new Map(snapshot.records.map((record) => [record.uuid, record]));
+      for (const record of local.records) {
+        if (!sameRecord(record, cloudByUuid.get(record.uuid))) {
+          throw new Error('cloud entity graph conflicts with locally bound ground; resolve the local mutation before importing a new cloud head');
+        }
+      }
     }
     if (!Number.isInteger(Number(authorityEpoch)) || Number(authorityEpoch) < 1
       || !Number.isInteger(Number(headVersion)) || Number(headVersion) < 0) {
       throw new Error('cloud entity registry authority is invalid');
     }
-    // Initial snapshot records have no tail mutation to trigger a content
-    // upload. Queue every actual file head before calling this replica
-    // active; from that moment its graph may be advertised to the cloud.
-    for (const record of snapshot.records) queueContent(record, resourceId, { queue: true });
+    // A creator's first snapshot has no tail mutation to trigger content
+    // upload. A joining device must NOT queue remote bytes as uploads; it
+    // downloads them later through a materialization job instead.
+    if (bootstrapping) {
+      for (const record of snapshot.records) queueContent(record, resourceId, { queue: true });
+    }
+    replaceCatalog({
+      resourceId,
+      authorityEpoch: Number(authorityEpoch),
+      headVersion: Number(headVersion),
+      records: snapshot.records,
+    });
     saveReplica({
       resourceId,
       deviceId: currentIdentity.deviceId,
@@ -261,7 +392,109 @@ function createEntityCloud({ db, userId, deviceId, content = null }) {
       state: 'active',
       snapshotCutoff: null,
     });
-    return { resourceId, records: snapshot.records.length, headVersion: Number(headVersion) };
+    return {
+      resourceId,
+      records: snapshot.records.length,
+      headVersion: Number(headVersion),
+      snapshotVersion: Number(headVersion),
+    };
+  }
+
+  /**
+   * Start an `amalgm add` job from exactly one compacted cloud snapshot. The
+   * job deliberately contains no mutation cursor: historical mutations were
+   * folded into that snapshot by the authority before this point.
+   */
+  function startMaterialization({ uuid, targetPath }) {
+    const current = currentCatalog();
+    if (typeof targetPath !== 'string' || !targetPath) throw new Error('materialization requires a destination path');
+    const tree = catalogTree({ resourceId: current.resourceId, uuid });
+    if (tree[0].status !== 'active') throw new Error(`cloud entity ${uuid} is not active`);
+    const unsupported = tree.find((record) => ['repo.git', 'link', 'reference'].includes(record.type));
+    if (unsupported) {
+      throw new Error(`cloud entity ${unsupported.uuid} is ${unsupported.type}; this first materializer supports ordinary workspace and file trees only`);
+    }
+    const prior = db.prepare(`
+      SELECT * FROM entity_materializations
+      WHERE resource_id = ? AND entity_uuid = ? AND target_path = ?
+        AND state IN ('waiting_for_content', 'materializing', 'complete')
+      ORDER BY created_at DESC LIMIT 1
+    `).get(current.resourceId, tree[0].uuid, targetPath);
+    if (prior) return materialization(prior);
+    const jobId = `mat_${crypto.randomBytes(18).toString('base64url')}`;
+    const createdAt = now();
+    db.prepare(`
+      INSERT INTO entity_materializations (
+        job_id, resource_id, entity_uuid, target_path, authority_epoch,
+        head_version, state, created_at, updated_at
+      ) VALUES (?, ?, ?, ?, ?, ?, 'waiting_for_content', ?, ?)
+    `).run(jobId, current.resourceId, tree[0].uuid, targetPath, current.authorityEpoch, current.headVersion, createdAt, createdAt);
+    return materialization(db.prepare('SELECT * FROM entity_materializations WHERE job_id = ?').get(jobId));
+  }
+
+  function pendingMaterializations() {
+    return db.prepare(`
+      SELECT * FROM entity_materializations
+      WHERE state IN ('waiting_for_content', 'materializing')
+      ORDER BY created_at ASC
+    `).all().map(materialization);
+  }
+
+  function claimDownload() {
+    const current = replica();
+    if (!current || !content) return null;
+    for (const job of pendingMaterializations().filter((entry) => entry.state === 'waiting_for_content')) {
+      if (job.resourceId !== current.resourceId) continue;
+      const tree = catalogTree({ resourceId: job.resourceId, uuid: job.entityUuid });
+      for (const record of tree) {
+        if (!['file.text', 'file.binary'].includes(record.type) || record.status !== 'active') continue;
+        if (!contentHead(record)) throw new Error(`cloud file ${record.uuid} has no immutable content head`);
+        const part = content.missingPart({ contentHash: record.payloadVersion });
+        if (!part) continue;
+        return {
+          resourceId: job.resourceId,
+          contentHash: record.payloadVersion,
+          kind: part.kind,
+          partIndex: part.partIndex,
+          sha256: part.sha256,
+        };
+      }
+    }
+    return null;
+  }
+
+  function receiveDownload({ resourceId, contentHash, kind, partIndex, sha256, dataBase64 }) {
+    const current = replica();
+    if (!current || current.resourceId !== resourceId || !content) {
+      throw new Error(`unknown entity content resource ${resourceId}`);
+    }
+    return content.receive({ contentHash, kind, partIndex, sha256, dataBase64 });
+  }
+
+  function completeMaterialization({ jobId }) {
+    const row = db.prepare('SELECT * FROM entity_materializations WHERE job_id = ?').get(jobId);
+    if (!row) throw new Error(`unknown entity materialization ${jobId}`);
+    db.prepare(`
+      UPDATE entity_materializations
+      SET state = 'complete', error = NULL, updated_at = ?
+      WHERE job_id = ?
+    `).run(now(), jobId);
+    return materialization(db.prepare('SELECT * FROM entity_materializations WHERE job_id = ?').get(jobId));
+  }
+
+  function failMaterialization({ jobId, message }) {
+    const row = db.prepare('SELECT * FROM entity_materializations WHERE job_id = ?').get(jobId);
+    if (!row) throw new Error(`unknown entity materialization ${jobId}`);
+    db.prepare(`
+      UPDATE entity_materializations
+      SET state = 'failed', error = ?, updated_at = ?
+      WHERE job_id = ?
+    `).run(String(message || 'cloud materialization failed').slice(0, 4000), now(), jobId);
+    return materialization(db.prepare('SELECT * FROM entity_materializations WHERE job_id = ?').get(jobId));
+  }
+
+  function materializationStatus(jobId) {
+    return materialization(db.prepare('SELECT * FROM entity_materializations WHERE job_id = ?').get(jobId));
   }
 
   function claim({ limit = 16, leaseMs = 30_000 } = {}) {
@@ -411,20 +644,19 @@ function createEntityCloud({ db, userId, deviceId, content = null }) {
         committedAt,
       });
     }
-    // The snapshot install is the first place an unbound remote root may
-    // enter this machine. Until `add` has the materializer/catalog rail,
-    // accepting a later unknown root here would violate the registry's
-    // watched-root loss law. A duplicate record is safe and advances the
-    // local cloud cursor; a distinct record is deliberately surfaced.
+    // Remote mutations update the cloud-only catalog. They never create a
+    // local watcher; `amalgm add` alone turns catalog identity into ground.
     let local;
-    try {
-      local = registry.syncRecord(record.uuid);
-    } catch {
-      throw new Error('remote entity mutation needs cloud-to-local materialization before this device can apply it');
-    }
-    if (!sameRecord(local, record)) {
-      throw new Error('remote entity mutation conflicts with this device; materialize or reconcile the cloud entity first');
+    try { local = registry.syncRecord(record.uuid); } catch { local = null; }
+    if (local && !sameRecord(local, record)) {
+      throw new Error('remote entity mutation conflicts with this device; refresh the compacted cloud head before applying it locally');
     }
+    upsertCatalogRecord({
+      resourceId: current.resourceId,
+      authorityEpoch: current.authorityEpoch,
+      headVersion: Number(version),
+      record,
+    });
     if (Number(version) > current.headVersion) saveReplica({ ...current, headVersion: Number(version) });
     return { duplicate: true, version: Number(version) };
   }
@@ -442,6 +674,14 @@ function createEntityCloud({ db, userId, deviceId, content = null }) {
     claimContent,
     acknowledgeContent,
     failContent,
+    startMaterialization,
+    pendingMaterializations,
+    claimDownload,
+    receiveDownload,
+    completeMaterialization,
+    failMaterialization,
+    materializationStatus,
+    catalogTree,
     replica,
   };
 }

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

@@ -330,6 +330,88 @@ function createEntityContent({ dir }) {
     return manifest(contentHash) !== null;
   }
 
+  /**
+   * A received cloud part is admitted by the same immutable manifest/chunk
+   * rules as a locally captured part. A manifest arrives first; it names the
+   * exact chunk checksums the later requests are allowed to write.
+   */
+  function receive({ contentHash, kind, partIndex, sha256, dataBase64 }) {
+    assertHash(contentHash);
+    assertHash(sha256, 'part checksum');
+    if (!['manifest', 'chunk'].includes(kind) || !Number.isSafeInteger(partIndex) || partIndex < 0) {
+      throw new Error('remote entity content part is invalid');
+    }
+    const bytes = Buffer.from(String(dataBase64 || ''), 'base64');
+    if (digest(bytes) !== sha256) throw new Error('remote entity content checksum mismatch');
+    ensureDirs();
+    if (kind === 'manifest') {
+      if (partIndex !== 0) throw new Error('remote entity content manifest has an invalid part index');
+      let remote;
+      try {
+        remote = JSON.parse(bytes.toString('utf8'));
+      } catch {
+        throw new Error('remote entity content manifest is not JSON');
+      }
+      const value = validateManifest(remote, contentHash);
+      const current = manifest(contentHash);
+      if (current && stableManifest(current) !== stableManifest(value)) {
+        throw new Error(`local entity content manifest ${contentHash} conflicts with cloud`);
+      }
+      if (!current) writeJson(manifestFile(contentHash), value);
+      return { kind, contentHash, complete: complete({ contentHash }) };
+    }
+    const current = manifest(contentHash);
+    if (!current) throw new Error(`remote entity content chunk ${contentHash} arrived before its manifest`);
+    const expected = current.chunks[partIndex];
+    if (!expected || expected.sha256 !== sha256 || expected.bytes !== bytes.length) {
+      throw new Error(`remote entity content chunk ${contentHash}/${partIndex} does not match its manifest`);
+    }
+    writeChunk(sha256, bytes);
+    return { kind, contentHash, complete: complete({ contentHash }) };
+  }
+
+  function stableManifest(value) {
+    return JSON.stringify({
+      contract: value.contract,
+      contentHash: value.contentHash,
+      bytes: value.bytes,
+      chunks: value.chunks,
+    });
+  }
+
+  function missingPart({ contentHash }) {
+    const current = manifest(contentHash);
+    if (!current) return { kind: 'manifest', partIndex: 0, sha256: null };
+    for (let partIndex = 0; partIndex < current.chunks.length; partIndex += 1) {
+      const chunk = current.chunks[partIndex];
+      try {
+        const bytes = fs.readFileSync(chunkFile(chunk.sha256));
+        if (bytes.length === chunk.bytes && digest(bytes) === chunk.sha256) continue;
+      } catch (error) {
+        if (error.code !== 'ENOENT') throw error;
+      }
+      return { kind: 'chunk', partIndex, sha256: chunk.sha256 };
+    }
+    return null;
+  }
+
+  function complete({ contentHash }) {
+    return missingPart({ contentHash }) === null;
+  }
+
+  function bytes({ contentHash }) {
+    const current = manifest(contentHash);
+    if (!current || !complete({ contentHash })) {
+      throw new Error(`entity content ${contentHash} is not complete locally`);
+    }
+    const parts = current.chunks.map((chunk) => fs.readFileSync(chunkFile(chunk.sha256)));
+    const full = Buffer.concat(parts, current.bytes);
+    if (full.length !== current.bytes || digest(full) !== contentHash) {
+      throw new Error(`entity content ${contentHash} does not match its declared head`);
+    }
+    return full;
+  }
+
   return {
     captureFile,
     ensureUpload,
@@ -339,6 +421,10 @@ function createEntityContent({ dir }) {
     fail,
     uploaded,
     has,
+    receive,
+    missingPart,
+    complete,
+    bytes,
   };
 }
 

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

@@ -478,6 +478,7 @@ function createRegistration(options) {
    */
   function add(targetPath, options = {}) {
     const identityAt = options.identityAt ?? null;
+    const suppressJournal = options.suppressJournal === true;
     if (identityAt !== null && typeof identityAt !== 'function') {
       throw new Error('add identityAt must be a function when supplied');
     }
@@ -514,7 +515,7 @@ function createRegistration(options) {
     const root = observer.enrollRoot(ground, { scan: false, watch: false });
     try {
       assertWitnessed({ observer, registry, memory });
-      registerTree({
+      const register = () => registerTree({
         root,
         registry,
         memory,
@@ -523,6 +524,8 @@ function createRegistration(options) {
         repoStates,
         identityAt,
       });
+      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

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

@@ -38,6 +38,8 @@
  * every declared safe root (docs/user-cloud-bootstrap.md).
  */
 
+const crypto = require('crypto');
+const fs = require('fs');
 const path = require('path');
 
 const Database = require('better-sqlite3');
@@ -257,6 +259,99 @@ function createRegistrationService({
     };
   }
 
+  /** Materialize one already-pinned cloud tree into a fresh destination, then
+   * bind its cloud UUID graph to Watch. The destination is never merged with
+   * user ground: bytes are assembled in a sibling staging path and renamed
+   * only after every immutable head verifies locally. */
+  function materializeCloudTree(job) {
+    const tree = entityCloud.catalogTree({ resourceId: job.resourceId, uuid: job.entityUuid });
+    const root = tree[0];
+    const active = tree.filter((record) => record.status === 'active');
+    const records = new Map(active.map((record) => [record.uuid, record]));
+    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 record of active) {
+      if (['file.text', 'file.binary'].includes(record.type)
+        && !entityContent.complete({ contentHash: record.payloadVersion })) {
+        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`);
+    }
+
+    const parent = fs.realpathSync(job.targetPath);
+    const parentStat = fs.statSync(parent);
+    if (!parentStat.isDirectory()) throw new Error(`add destination is not a directory: ${parent}`);
+    const destination = path.join(parent, root.name);
+    if (fs.existsSync(destination)) throw new Error(`refusing to add ${root.name}: destination already exists at ${destination}`);
+    const staging = path.join(parent, `.${root.name}.amalgm-materializing-${crypto.randomBytes(10).toString('hex')}`);
+    let promoted = false;
+
+    function write(record, target) {
+      if (record.type === 'workspace' || record.type === 'folder') {
+        fs.mkdirSync(target, { mode: 0o700 });
+        for (const child of (children.get(record.uuid) || []).sort((left, right) => left.name.localeCompare(right.name))) {
+          write(child, path.join(target, child.name));
+        }
+        return;
+      }
+      if (record.type === 'file.text' || record.type === 'file.binary') {
+        fs.writeFileSync(target, entityContent.bytes({ contentHash: record.payloadVersion }), { mode: 0o600, flag: 'wx' });
+        return;
+      }
+      throw new Error(`cloud entity ${record.uuid} is ${record.type}; this materializer cannot write it yet`);
+    }
+
+    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;
+      }
+      return records.get(cursor.uuid) || null;
+    }
+
+    try {
+      write(root, staging);
+      fs.renameSync(staging, destination);
+      promoted = true;
+      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}`);
+      }
+      return { ...bound, destination };
+    } catch (error) {
+      // The staging and, if binding failed, destination contain only bytes
+      // produced from the verified immutable snapshot in this invocation.
+      // They never existed before this command, so removing them cannot erase
+      // user ground or hide a merge.
+      try {
+        if (fs.existsSync(staging)) fs.rmSync(staging, { recursive: true, force: true });
+        if (promoted && fs.existsSync(destination)) fs.rmSync(destination, { recursive: true, force: true });
+      } catch {}
+      throw error;
+    }
+  }
+
+  function advanceMaterializations() {
+    for (const job of entityCloud.pendingMaterializations()) {
+      if (job.state !== 'waiting_for_content') continue;
+      try {
+        const result = materializeCloudTree(job);
+        if (result) entityCloud.completeMaterialization({ jobId: job.jobId });
+      } catch (error) {
+        entityCloud.failMaterialization({ jobId: job.jobId, message: error.message });
+      }
+    }
+  }
+
   return {
     dir,
     homeDir,
@@ -272,6 +367,13 @@ function createRegistrationService({
       entityCloud.assertRegistrationReady();
       return boundary.current.addMany(targetPaths);
     },
+    /** `amalgm add <cloud-root-uuid> [parent-directory]` — cloud to local. */
+    add: async ({ uuid, targetPath }) => {
+      const job = entityCloud.startMaterialization({ uuid, targetPath });
+      advanceMaterializations();
+      return entityCloud.materializationStatus(job.jobId);
+    },
+    advanceMaterializations,
     bootstrapUserHome,
     entityCloud,
     entityContent,

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

@@ -67,7 +67,7 @@ function registerTree({ root, registry, memory, shouldEnroll, captureRepo, repoS
 
   function seeded(relativePath, { type, parentUUID, name, root: isRoot }) {
     const identity = identityAt?.(relativePath) || null;
-    if (!identity) return { type, uuid: undefined };
+    if (!identity) return { type, uuid: undefined, payloadVersion: undefined };
     if (identity.name !== name || identity.parentUUID !== parentUUID || identity.status !== 'active') {
       throw new Error(`cloud identity at ${relativePath || '.'} does not match the local declared tree`);
     }
@@ -82,7 +82,15 @@ function registerTree({ root, registry, memory, shouldEnroll, captureRepo, repoS
     if (isRoot && !['workspace', 'repo.git', 'file.text', 'file.binary', 'link'].includes(identity.type)) {
       throw new Error(`cloud identity at ${relativePath || '.'} is not a valid tree root`);
     }
-    return { type: identity.type, uuid: identity.uuid };
+    return {
+      type: identity.type,
+      uuid: identity.uuid,
+      // Structural registration normally leaves leaf payloads for Detect.
+      // A cloud materializer has already verified immutable bytes before it
+      // binds this tree, so retaining that head prevents an import from
+      // inventing a temporary local mutation.
+      payloadVersion: identity.payloadVersion,
+    };
   }
 
   return registry.transaction(() => {
@@ -93,7 +101,7 @@ function registerTree({ root, registry, memory, shouldEnroll, captureRepo, repoS
     const record = registry.enrollRoot({
       type: rootIdentity.type,
       name: path.basename(root.path),
-      payloadVersion: initialState?.stateId ?? null,
+      payloadVersion: initialState?.stateId ?? rootIdentity.payloadVersion ?? null,
       uuid: rootIdentity.uuid,
     });
     memory.bind(root.rootId, root.rootId, record.uuid);
@@ -157,7 +165,7 @@ function registerDirectory(dirPath, parentUUID, {
         type: identity.type,
         parentUUID,
         name: entry.name,
-        payloadVersion: state?.stateId ?? null,
+        payloadVersion: state?.stateId ?? identity.payloadVersion ?? null,
         uuid: identity.uuid,
       });
       if (state) repoStates.put(record.uuid, state);
@@ -170,7 +178,13 @@ function registerDirectory(dirPath, parentUUID, {
       const identity = seeded(entryRelativePath, {
         type: 'file.text', parentUUID, name: entry.name, root: false,
       });
-      registry.create({ type: identity.type, parentUUID, name: entry.name, uuid: identity.uuid });
+      registry.create({
+        type: identity.type,
+        parentUUID,
+        name: entry.name,
+        payloadVersion: identity.payloadVersion ?? null,
+        uuid: identity.uuid,
+      });
     }
   }
 }

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

@@ -182,6 +182,7 @@ function createRegistry(options) {
   // attachment must always compare, pending bell or not.
   let bellPending = false;
   const deferred = []; // bells born inside an open transaction: they ring at commit, or a rollback silences them
+  let journalSuppression = 0;
 
   function ring(event) {
     try {
@@ -311,7 +312,9 @@ function createRegistry(options) {
     // before notification. A failed journal write rolls the entity mutation
     // back; a later process can never observe local truth without its cloud
     // delivery intent.
-    if (journal) journal({ record: syncRecord(next), previous: previous ? syncRecord(previous) : null });
+    if (journal && journalSuppression === 0) {
+      journal({ record: syncRecord(next), previous: previous ? syncRecord(previous) : null });
+    }
   }
 
   function normalizeCloudRecord(value) {
@@ -475,6 +478,18 @@ function createRegistry(options) {
      */
     transaction,
 
+    /** Bind already-authoritative cloud identity to materialized local ground
+     * without turning that import into a new outbound mutation tail. */
+    withoutJournal(fn) {
+      if (typeof fn !== 'function') throw new Error('withoutJournal requires a function');
+      journalSuppression += 1;
+      try {
+        return fn();
+      } finally {
+        journalSuppression -= 1;
+      }
+    },
+
     /** Always requests comparison — it never trusts the in-memory flag,
      * because a restart loses that memory. Returns whether the bell rang. */
     flush() {