amalgm 0.1.257 → 0.1.258

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

@@ -11,12 +11,13 @@
 
 const crypto = require('crypto');
 
-// `@1` was an unreleased bootstrap experiment which could project arbitrary
-// pre-cloud local registrations into the first private head. A resource
-// contract names immutable authority semantics, so it is quarantined rather
-// than interpreted or overwritten. `@2` begins with only the verified user
-// home; later user ground enters exclusively through `amalgm register`.
-const ENTITY_CLOUD_CONTRACT = 'amalgm-entity-registry@2';
+// `@1` could project arbitrary pre-cloud registrations. `@2` omitted the
+// declared built-in tool entities, so its toolbox root could not prove the
+// snapshot membership it named. A resource contract names immutable authority
+// semantics: both remain quarantined rather than reinterpreted or overwritten.
+// `@3` begins with the complete verified user home; later user ground enters
+// exclusively through `amalgm register`.
+const ENTITY_CLOUD_CONTRACT = 'amalgm-entity-registry@3';
 const ENTITY_CLOUD_SCHEMA_VERSION = 1;
 const BOOTSTRAP_RECONCILIATION_STATE = 'reconciling-bootstrap';
 const SNAPSHOT_REPLACE_OPERATION = 'entity.snapshot.replace';
@@ -191,6 +192,56 @@ function createEntityCloud({ db, userId, deviceId, content = null, repoStates =
     };
   }
 
+  // The catalog mirrors the compacted cloud head as long as every head
+  // advance since the last installed snapshot was applied to it in order:
+  // journal() upserts this device's own records, ingest() upserts remote
+  // ones, and the gateway's fold regenerates only derived container
+  // versions, which every catalog consumer already tolerates. A version
+  // gap, a remote snapshot replacement, or a restart drops this back to
+  // whatever the durable pin proves, and the next snapshot download
+  // re-establishes it.
+  let catalogLive = null;
+  // Mutation rows whose content-upload cursors already exist on disk.
+  const contentQueuedSequences = new Set();
+
+  function catalogPinnedAtHead(current) {
+    if (!current) return false;
+    const pin = db.prepare(`
+      SELECT resource_id, authority_epoch, snapshot_version
+      FROM entity_cloud_catalog_state WHERE singleton = 1
+    `).get();
+    return Boolean(pin && pin.resource_id === current.resourceId
+      && Number(pin.authority_epoch) === current.authorityEpoch
+      && Number(pin.snapshot_version) === current.headVersion);
+  }
+
+  function unsettledMutationCount(resourceId) {
+    return Number(db.prepare(`
+      SELECT COUNT(*) AS count FROM entity_cloud_mutations
+      WHERE resource_id = ? AND mutation_state <> 'synced'
+    `).get(resourceId).count);
+  }
+
+  function catalogIsLive(current) {
+    if (catalogLive === null) {
+      catalogLive = catalogPinnedAtHead(current) && unsettledMutationCount(current.resourceId) === 0;
+    }
+    return catalogLive;
+  }
+
+  function pinCatalogState({ resourceId, authorityEpoch, headVersion }) {
+    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());
+  }
+
   function saveReplica(value) {
     db.prepare(`
       INSERT INTO entity_cloud_replica (
@@ -236,16 +287,7 @@ function createEntityCloud({ db, userId, deviceId, content = null, repoStates =
       // 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());
+      pinCatalogState({ resourceId, authorityEpoch, headVersion });
     })();
     return normalized;
   }
@@ -523,6 +565,7 @@ function createEntityCloud({ db, userId, deviceId, content = null, repoStates =
         });
         enqueueBootstrapReconciliation(trustedBootstrap, next);
       })();
+      catalogLive = false;
       return {
         resourceId,
         records: snapshot.records.length,
@@ -557,6 +600,7 @@ function createEntityCloud({ db, userId, deviceId, content = null, repoStates =
         state: complete ? 'active' : BOOTSTRAP_RECONCILIATION_STATE,
         snapshotCutoff: null,
       });
+      catalogLive = complete;
       return {
         resourceId,
         records: snapshot.records.length,
@@ -604,6 +648,10 @@ function createEntityCloud({ db, userId, deviceId, content = null, repoStates =
       state: 'active',
       snapshotCutoff: null,
     });
+    // A snapshot installed over unsettled local mutations replaced their
+    // catalog upserts; liveness returns with the install that finds an
+    // empty outbox.
+    catalogLive = unsettledMutationCount(resourceId) === 0;
     return {
       resourceId,
       records: snapshot.records.length,
@@ -710,6 +758,58 @@ function createEntityCloud({ db, userId, deviceId, content = null, repoStates =
     return materialization(db.prepare('SELECT * FROM entity_materializations WHERE job_id = ?').get(jobId));
   }
 
+  /** Read-only cloud-replica truth for `amalgm status`.  This deliberately
+   * reports a stale catalog as stale instead of presenting its records as a
+   * head that is safe to materialize.  Status is an observer of authority,
+   * never a repair or a hidden snapshot handshake. */
+  function status() {
+    const current = replica();
+    const resourceId = current?.resourceId || null;
+    const mutationCounts = new Map();
+    if (resourceId) {
+      for (const row of db.prepare(`
+        SELECT mutation_state, COUNT(*) AS count
+        FROM entity_cloud_mutations
+        WHERE resource_id = ?
+        GROUP BY mutation_state
+      `).all(resourceId)) {
+        mutationCounts.set(row.mutation_state, Number(row.count));
+      }
+    }
+    const materializationCounts = new Map();
+    if (resourceId) {
+      for (const row of db.prepare(`
+        SELECT state, COUNT(*) AS count
+        FROM entity_materializations
+        WHERE resource_id = ?
+        GROUP BY state
+      `).all(resourceId)) {
+        materializationCounts.set(row.state, Number(row.count));
+      }
+    }
+    const pending = (mutationCounts.get('pending') || 0) + (mutationCounts.get('syncing') || 0);
+    const pinned = current ? catalogPinnedAtHead(current) : false;
+    return {
+      identity: identity(),
+      replica: current,
+      catalog: {
+        pinned,
+        current: Boolean(current?.state === 'active' && pinned && pending === 0),
+        records: resourceId ? catalogRecords(resourceId) : [],
+      },
+      outbox: {
+        pending: mutationCounts.get('pending') || 0,
+        syncing: mutationCounts.get('syncing') || 0,
+        rejected: mutationCounts.get('rejected') || 0,
+      },
+      materializations: {
+        waitingForContent: materializationCounts.get('waiting_for_content') || 0,
+        materializing: materializationCounts.get('materializing') || 0,
+        failed: materializationCounts.get('failed') || 0,
+      },
+    };
+  }
+
   /** A completed add is a live binding, not a one-time download.  A remote
    * record beneath that binding moves the durable job back to its content
    * gate.  The service owns the later filesystem application; this module
@@ -810,17 +910,21 @@ function createEntityCloud({ db, userId, deviceId, content = null, repoStates =
     // Later registrations journal their record transactionally in SQLite.
     // Derive its content-upload cursor only after that commit exists, so a
     // failed transaction cannot publish a private object no entity names.
+    // Each mutation's operation is immutable, so it is scanned once per
+    // process; a restart simply rescans the still-unsettled rows.
     const rows = db.prepare(`
-      SELECT operation_json FROM entity_cloud_mutations
+      SELECT sequence, operation_json FROM entity_cloud_mutations
       WHERE resource_id = ? AND mutation_state IN ('pending', 'syncing')
       ORDER BY sequence ASC
     `).all(current.resourceId);
     for (const row of rows) {
+      if (contentQueuedSequences.has(row.sequence)) continue;
       const operation = JSON.parse(row.operation_json);
       const records = operation?.kind === SNAPSHOT_REPLACE_OPERATION
         ? operation?.snapshot?.records
         : [operation?.record];
       for (const record of records || []) queueContent(record, current.resourceId, { queue: true });
+      contentQueuedSequences.add(row.sequence);
     }
     return content.claim({ resourceId: current.resourceId, leaseMs });
   }
@@ -850,31 +954,59 @@ function createEntityCloud({ db, userId, deviceId, content = null, repoStates =
         .get(resourceId, mutationId);
       if (!row) throw new Error(`unknown entity cloud mutation ${mutationId}`);
       if (row.mutation_state === 'synced') {
-        const unsettled = db.prepare('SELECT COUNT(*) AS count FROM entity_cloud_mutations WHERE resource_id = ? AND mutation_state <> \'synced\'')
-          .get(resourceId);
         return {
           duplicate: true,
           version: Number(row.official_version),
-          requiresSnapshot: current.state !== BOOTSTRAP_RECONCILIATION_STATE || Number(unsettled.count) === 0,
+          requiresSnapshot: current.state === BOOTSTRAP_RECONCILIATION_STATE
+            ? unsettledMutationCount(resourceId) === 0
+            : !catalogIsLive(current),
         };
       }
       if (!['pending', 'syncing'].includes(row.mutation_state)) throw new Error(`entity cloud mutation ${mutationId} cannot sync from ${row.mutation_state}`);
+      const live = current.state === BOOTSTRAP_RECONCILIATION_STATE ? false : catalogIsLive(current);
       db.prepare(`
         UPDATE entity_cloud_mutations
         SET mutation_state = 'synced', official_version = ?, cloud_committed_at = ?,
             next_attempt_at = NULL, last_error = NULL, updated_at = ?
         WHERE sequence = ?
       `).run(Number(version), String(committedAt || now()), now(), row.sequence);
-      if (Number(version) > current.headVersion) {
+      const previousHead = current.headVersion;
+      if (Number(version) > previousHead) {
         saveReplica({ ...current, headVersion: Number(version) });
       }
-      const unsettled = db.prepare('SELECT COUNT(*) AS count FROM entity_cloud_mutations WHERE resource_id = ? AND mutation_state <> \'synced\'')
-        .get(resourceId);
-      return {
-        duplicate: false,
-        version: Number(version),
-        requiresSnapshot: current.state !== BOOTSTRAP_RECONCILIATION_STATE || Number(unsettled.count) === 0,
-      };
+      const unsettled = unsettledMutationCount(resourceId);
+      if (current.state === BOOTSTRAP_RECONCILIATION_STATE) {
+        return { duplicate: false, version: Number(version), requiresSnapshot: unsettled === 0 };
+      }
+      // Local convergence instead of a snapshot re-download per ack. This
+      // device journaled these exact records into the catalog when the
+      // mutation was created, so an in-order acknowledgement leaves the
+      // catalog equal to the compacted head by construction. Anything out
+      // of order gives liveness up until the next installed snapshot.
+      let operation = null;
+      try { operation = JSON.parse(row.operation_json); } catch {}
+      if (operation?.kind === SNAPSHOT_REPLACE_OPERATION) {
+        if (unsettled === 0 && Array.isArray(operation?.snapshot?.records)) {
+          // The replacement operation IS the complete graph at this version.
+          replaceCatalog({
+            resourceId,
+            authorityEpoch: current.authorityEpoch,
+            headVersion: Number(version),
+            records: operation.snapshot.records,
+          });
+          catalogLive = true;
+        } else {
+          catalogLive = false;
+        }
+      } else if (!operation || Number(version) !== previousHead + 1) {
+        catalogLive = false;
+      } else {
+        catalogLive = live;
+        if (catalogLive && unsettled === 0) {
+          pinCatalogState({ resourceId, authorityEpoch: current.authorityEpoch, headVersion: Number(version) });
+        }
+      }
+      return { duplicate: false, version: Number(version), requiresSnapshot: !catalogLive };
     })();
   }
 
@@ -912,10 +1044,17 @@ function createEntityCloud({ db, userId, deviceId, content = null, repoStates =
     if (envelope?.operationKind === SNAPSHOT_REPLACE_OPERATION
       && envelope?.operation?.kind === SNAPSHOT_REPLACE_OPERATION) {
       // The complete replacement is imported only from the active snapshot
-      // the gateway makes before acknowledgement. Consuming its tail would
-      // reintroduce the very partial-graph state this operation prevents.
+      // the gateway compacts at lookup. Consuming its tail would reintroduce
+      // the very partial-graph state this operation prevents.
       if (Number(version) > current.headVersion) saveReplica({ ...current, headVersion: Number(version) });
-      return { duplicate: true, version: Number(version), snapshotRequired: true, materializations: [] };
+      catalogLive = false;
+      return {
+        duplicate: true,
+        version: Number(version),
+        snapshotRequired: true,
+        requiresSnapshot: true,
+        materializations: [],
+      };
     }
     if (envelope?.operationKind !== 'entity.upsert' || envelope?.operation?.kind !== 'entity.upsert') {
       throw new Error('cloud entity mutation does not belong to this registry');
@@ -951,10 +1090,24 @@ function createEntityCloud({ db, userId, deviceId, content = null, repoStates =
       headVersion: Number(version),
       record,
     });
-    if (Number(version) > current.headVersion) saveReplica({ ...current, headVersion: Number(version) });
+    // A remote record applied in official order keeps the catalog at the
+    // compacted head, so no snapshot re-download is needed for it either.
+    const live = catalogIsLive(current);
+    const previousHead = current.headVersion;
+    if (Number(version) > previousHead) saveReplica({ ...current, headVersion: Number(version) });
+    if (Number(version) !== previousHead + 1) {
+      catalogLive = false;
+    } else if (live && unsettledMutationCount(current.resourceId) === 0) {
+      pinCatalogState({
+        resourceId: current.resourceId,
+        authorityEpoch: current.authorityEpoch,
+        headVersion: Number(version),
+      });
+    }
     return {
       duplicate: true,
       version: Number(version),
+      requiresSnapshot: !catalogLive,
       materializations: refreshMaterializations({ resourceId: current.resourceId, record, version }),
     };
   }
@@ -980,6 +1133,7 @@ function createEntityCloud({ db, userId, deviceId, content = null, repoStates =
     completeMaterialization,
     failMaterialization,
     materializationStatus,
+    status,
     hasUnsettledLocalMutation,
     catalogTree,
     replica,

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

@@ -15,7 +15,10 @@ const fs = require('fs');
 const path = require('path');
 
 const CONTENT_CONTRACT = 'amalgm-entity-content@1';
-const CHUNK_BYTES = 256 * 1024;
+// One chunk is one WAN round trip. The gateway accepts parts up to this same
+// bound (ENTITY_CONTENT_PART_BYTES); older 256KB chunks remain valid because
+// the manifest rule is `bytes <= CHUNK_BYTES`, never an exact size.
+const CHUNK_BYTES = 4 * 1024 * 1024;
 const HASH = /^[0-9a-f]{64}$/;
 
 function digest(bytes) {
@@ -41,6 +44,10 @@ function createEntityContent({ dir }) {
   const chunksDir = path.join(root, 'chunks');
   const manifestsDir = path.join(root, 'manifests');
   const uploadsDir = path.join(root, 'uploads');
+  // Unfinished uploads per resource, so claim() does not re-read the whole
+  // ledger directory for every part it sends. The on-disk ledger stays the
+  // durable truth; this set is rebuilt from it once per process.
+  const pendingUploads = new Map();
 
   function ensureDirs() {
     for (const target of [chunksDir, manifestsDir, uploadsDir]) {
@@ -236,14 +243,27 @@ function createEntityContent({ dir }) {
     }
   }
 
+  function pendingSet(resourceId) {
+    let pending = pendingUploads.get(resourceId);
+    if (!pending) {
+      pending = new Set(uploadEntries(resourceId));
+      pendingUploads.set(resourceId, pending);
+    }
+    return pending;
+  }
+
   function ensureUpload({ resourceId, contentHash }) {
     if (typeof resourceId !== 'string' || !resourceId) throw new Error('entity content upload requires a resource id');
     const content = manifest(contentHash);
     if (!content) throw new Error(`content ${contentHash} was not captured before its entity record committed`);
     const current = readUpload(resourceId, contentHash, content);
-    if (current) return current;
+    if (current) {
+      if (!current.manifestUploaded) pendingSet(resourceId).add(contentHash);
+      return current;
+    }
     const created = initialUpload(resourceId, contentHash);
     saveUpload(created);
+    pendingSet(resourceId).add(contentHash);
     return created;
   }
 
@@ -269,11 +289,15 @@ function createEntityContent({ dir }) {
   function claim({ resourceId, leaseMs = 30_000 }) {
     ensureDirs();
     const at = Date.now();
-    for (const contentHash of uploadEntries(resourceId)) {
+    const pending = pendingSet(resourceId);
+    for (const contentHash of pending) {
       const content = manifest(contentHash);
       if (!content) throw new Error(`entity content ${contentHash} disappeared from the local cache`);
       const upload = readUpload(resourceId, contentHash, content);
-      if (!upload || upload.manifestUploaded) continue;
+      if (!upload || upload.manifestUploaded) {
+        pending.delete(contentHash);
+        continue;
+      }
       if (upload.leaseUntil && Date.parse(upload.leaseUntil) > at) continue;
       const next = { ...upload, leaseUntil: new Date(at + Math.max(1_000, Number(leaseMs) || 30_000)).toISOString(), updatedAt: now() };
       if (next.nextPart < content.chunks.length) {
@@ -333,6 +357,7 @@ function createEntityContent({ dir }) {
     current.leaseUntil = null;
     current.updatedAt = now();
     saveUpload(current);
+    if (current.manifestUploaded) pendingUploads.get(resourceId)?.delete(contentHash);
     return { duplicate: false, uploaded: current.manifestUploaded };
   }
 
@@ -412,9 +437,11 @@ function createEntityContent({ dir }) {
     if (!current) return { kind: 'manifest', partIndex: 0, sha256: null };
     for (let partIndex = 0; partIndex < current.chunks.length; partIndex += 1) {
       const chunk = current.chunks[partIndex];
+      // Presence + size only: every chunk file was hash-verified before it
+      // was written (capture or receive), writes are write-once, and final
+      // assembly (`bytes`) re-verifies the whole content head.
       try {
-        const bytes = fs.readFileSync(chunkFile(chunk.sha256));
-        if (bytes.length === chunk.bytes && digest(bytes) === chunk.sha256) continue;
+        if (fs.statSync(chunkFile(chunk.sha256)).size === chunk.bytes) continue;
       } catch (error) {
         if (error.code !== 'ENOENT') throw error;
       }

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

@@ -596,6 +596,26 @@ function createRegistration(options) {
     return normalized.map(({ targetPath, identityAt }) => add(targetPath, { identityAt }));
   }
 
+  /** Reconcile one already-watched tree after the platform has materialized
+   * a newly declared exact default inside it. This is deliberately not part
+   * of ordinary re-registration: the caller must have already named the
+   * exact platform node it needs, and the normal Detect → Record path still
+   * decides the resulting record. */
+  function reconcileDeclared(targetPath) {
+    let ground;
+    try {
+      ground = fs.lstatSync(targetPath).isSymbolicLink() ? path.resolve(targetPath) : fs.realpathSync(targetPath);
+    } catch {
+      throw new Error(`declared user-home root is unavailable: ${targetPath}`);
+    }
+    const covering = treeRootCovering(ground);
+    if (!covering) throw new Error(`declared user-home root was not registered: ${targetPath}`);
+    observer.scanNow(covering.rootId);
+    flushIfDirty();
+    requireLiveWatchers(covering.path);
+    return { rootPath: covering.path, record: rootRecordOf(covering.rootId) };
+  }
+
   /** The boundary's whole convergence pass, one act: loss convicted
    * first (loudly — a conviction is never a retry), edges followed,
    * lenses reconciled, renderings projected. Startup, the explicit
@@ -626,6 +646,7 @@ function createRegistration(options) {
     registry,
     add,
     addMany,
+    reconcileDeclared,
 
     /**
      * `amalgm register <existing-path> --as <address>` — the managed

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

@@ -47,6 +47,10 @@ const Database = require('better-sqlite3');
 const { STORAGE_DIR } = require('../config');
 const { ensureDir } = require('../lib/storage');
 const { ensureUserHome } = require('../lib/layout');
+const {
+  materializeSystemToolArtifacts,
+  migrateLegacyToolboxCatalog,
+} = require('../toolbox/artifacts');
 const { createObserver } = require('../observer');
 const { shouldEnroll } = require('../workspace/tree/inclusion');
 const { classifyFile } = require('./classify');
@@ -58,8 +62,8 @@ 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 USER_HOME_CLOUD_CONTRACT = 'amalgm-user-home@2';
+const USER_HOME_CLOUD_SCHEMA_VERSION = 2;
 const ATOMIC_REGISTRATION_THRESHOLD = 500;
 
 let live = null;
@@ -260,6 +264,19 @@ function createRegistrationService({
    */
   async function bootstrapUserHome({ identitySnapshot = null } = {}) {
     const declaration = ensureUserHome(homeDir);
+    // Materialize every built-in tool before the shared registration boundary
+    // first sees `toolbox/`. Each file is an exact managed child; user tools
+    // remain ordinary sibling files. A legacy aggregate is moved outside the
+    // watched tree only after per-tool replacements exist.
+    const toolbox = declaration.roots.find((entry) => entry.key === 'toolbox');
+    if (!toolbox) throw new Error('declared user-home is missing its toolbox root');
+    const migrated = migrateLegacyToolboxCatalog({ toolboxDir: toolbox.path });
+    const systemTools = materializeSystemToolArtifacts({ toolboxDir: toolbox.path });
+    declaration.materializedExactPaths = [
+      ...(declaration.materializedExactPaths || []),
+      ...(migrated.artifactPaths || []).map((target) => path.relative(homeDir, target).split(path.sep).join('/')),
+      ...(systemTools.changedRelativePaths || []),
+    ];
     const seeds = identitySeeds(identitySnapshot, declaration);
     const addedRoots = boundary.current.addMany(declaration.roots.map((entry) => ({
       targetPath: entry.path,
@@ -274,25 +291,50 @@ function createRegistrationService({
       };
     });
 
-    const system = roots.find((entry) => entry.key === 'system');
-    if (!system) throw new Error('declared user home has no system root');
-    const tree = boundary.current.tree(system.path);
-    if (!tree?.root()) throw new Error(`declared system root was not registered: ${system.path}`);
-
-    const recordAt = (relativePath) => {
+    const recordAt = (rootKey, relativePath, { required = true } = {}) => {
+      const root = roots.find((entry) => entry.key === rootKey);
+      if (!root) throw new Error(`declared user-home root was not registered: ${rootKey}`);
+      const tree = boundary.current.tree(root.path);
+      if (!tree?.root()) throw new Error(`declared user-home root was not registered: ${root.path}`);
       let record = tree.root();
       for (const name of relativePath.split('/')) {
         record = tree.registry.activeAt(record.uuid, name);
-        if (!record) throw new Error(`declared user-home target was not registered: ${relativePath}`);
+        if (!record) {
+          if (!required) return null;
+          throw new Error(`declared user-home target was not registered: ${rootKey}/${relativePath}`);
+        }
       }
       return record;
     };
 
+    // An upgraded installation can already watch an older declared root.
+    // Re-registering that root must remain only an availability check, so the
+    // narrow exception is a root holding an exact node that the layout just
+    // materialized or that the registry proves missing. Detect and Record
+    // still create/update its identity through the shared boundary.
+    const rootsToReconcile = new Set((declaration.materializedExactPaths || [])
+      .map((relativePath) => relativePath.split('/')[0]));
+    for (const entry of declaration.exactManaged) {
+      if (entry.relativePath === entry.rootKey) continue;
+      const relativePath = entry.relativePath.slice(entry.rootKey.length + 1);
+      if (!recordAt(entry.rootKey, relativePath, { required: false })) {
+        rootsToReconcile.add(entry.rootKey);
+      }
+    }
+    for (const rootKey of rootsToReconcile) {
+      const root = roots.find((candidate) => candidate.key === rootKey);
+      if (!root) throw new Error(`declared user-home root was not registered: ${rootKey}`);
+      boundary.current.reconcileDeclared(root.path);
+      roots = roots.map((candidate) => candidate.key === rootKey
+        ? { ...candidate, record: boundary.current.tree(candidate.path).root() }
+        : candidate);
+    }
+
     let exactManaged = declaration.exactManaged.map((entry) => {
       const root = roots.find((candidate) => candidate.key === entry.rootKey);
       const isRoot = entry.relativePath === entry.rootKey;
       const relativePath = isRoot ? '' : entry.relativePath.slice(entry.rootKey.length + 1);
-      const record = isRoot ? root?.record : recordAt(relativePath);
+      const record = isRoot ? root?.record : recordAt(entry.rootKey, relativePath);
       if (!record) throw new Error(`declared user-home managed target was not registered: ${entry.relativePath}`);
       return {
         key: entry.key,
@@ -767,6 +809,51 @@ function createRegistrationService({
     }
   }
 
+  /** The status surface composes each layer's own facts without creating a
+   * second registry or treating local paths as cloud metadata.  A cloud-only
+   * catalog record is intentionally visible with `localPath: null`; only
+   * `amalgm add` creates a watcher binding for it. */
+  function status() {
+    const cloud = entityCloud.status();
+    const localRecords = boundary.current.registry.syncRecords();
+    const localByUuid = new Map(localRecords.map((record) => [record.uuid, record]));
+    const cloudByUuid = new Map(cloud.catalog.records.map((record) => [record.uuid, record]));
+    const roots = observer.status().map((root) => {
+      const tree = boundary.current.tree(root.path);
+      const record = tree ? tree.root() : null;
+      return {
+        uuid: record?.uuid || null,
+        path: root.path,
+        kind: root.kind,
+        watching: root.watching,
+        degraded: root.degraded,
+        addressWatching: root.addressWatching,
+        addressDegraded: root.addressDegraded,
+      };
+    });
+    const rootByUuid = new Map(roots.filter((root) => root.uuid !== null).map((root) => [root.uuid, root]));
+    const uuids = new Set([...localByUuid.keys(), ...cloudByUuid.keys()]);
+    const entities = [...uuids].sort().map((uuid) => {
+      const local = localByUuid.get(uuid) || null;
+      const record = cloudByUuid.get(uuid) || local;
+      let localPath = null;
+      if (local) {
+        try { localPath = boundary.current.addressOf(uuid); } catch {}
+      }
+      return {
+        ...record,
+        // A local journal projects its intent into the catalog before the
+        // gateway acknowledges it.  Call that fact `catalogued`, not
+        // `cloudBacked`: the enclosing cloud summary says whether the
+        // catalog is actually pinned to an authoritative current head.
+        catalogued: cloudByUuid.has(uuid),
+        localPath,
+        root: rootByUuid.get(uuid) || null,
+      };
+    });
+    return { cloud, roots, entities };
+  }
+
   return {
     dir,
     homeDir,
@@ -820,9 +907,13 @@ function createRegistrationService({
       const received = entityCloud.receiveDownload({
         resourceId, contentHash, kind, partIndex, sha256, dataBase64,
       });
-      advanceMaterializations();
+      // A mid-file part cannot complete any waiting tree; only a finished
+      // content head can. Advancing on every part re-walks every waiting
+      // job once per part, which is quadratic over a large download.
+      if (received?.complete) advanceMaterializations();
       return received;
     },
+    status,
     advanceMaterializations,
     bootstrapUserHome,
     exactUserHomeCloudRecords,

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

@@ -686,7 +686,7 @@ function createRegistry(options) {
 
     /**
      * First cloud bootstrap may meet a pre-cloud local safe home. Its six
-     * roots and three exact managed nodes are platform truth, so they may
+     * roots and ten exact managed nodes are platform truth, so they may
      * adopt the authenticated cloud UUIDs without changing any user-owned
      * descendant identity. This is one atomic graph rekey, never a delete or
      * local-wins merge, and callers must prove that no ordinary entity-cloud

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

@@ -316,6 +316,12 @@ async function handleEntityRoutes(ctx) {
     return true;
   }
 
+  if (ctx.pathname === '/entities/status' && ctx.method === 'GET') {
+    ctx.res.setHeader('Cache-Control', 'no-store');
+    ctx.sendJson(200, registrationService().status());
+    return true;
+  }
+
   const materializationMatch = /^\/entities\/add\/(mat_[A-Za-z0-9_-]+)$/.exec(ctx.pathname);
   if (materializationMatch && ctx.method === 'GET') {
     const service = registrationService();