amalgm 0.1.260 → 0.1.262

package/lib/cli.js

@@ -1215,10 +1215,16 @@ function selectEntity(status, selector) {
   const uuid = selector && /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(selector)
     ? selector.toLowerCase()
     : null;
+  // A UUID is an entity's globally unique address. Do not let rows without
+  // an optional display path turn that exact address into a fuzzy selector.
+  if (uuid) {
+    const match = entities.find((entity) => entity.uuid === uuid);
+    if (!match) throw new Error(`No cloud-backed entity matches ${selector}.`);
+    return match;
+  }
   const localPath = selector && !uuid ? path.resolve(selector) : null;
-  const cloudPath = uuid ? null : String(selector).replace(/^\/+|\/+$/g, '');
-  const matches = entities.filter((entity) => entity.uuid === uuid
-    || entity.localPath === localPath
+  const cloudPath = String(selector).replace(/^\/+|\/+$/g, '');
+  const matches = entities.filter((entity) => entity.localPath === localPath
     || entity.cloudPath === cloudPath
     || entity.name === selector);
   if (matches.length === 0) throw new Error(`No cloud-backed entity matches ${selector}.`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "amalgm",
-  "version": "0.1.260",
+  "version": "0.1.262",
   "description": "Amalgm local computer runtime: login, MCP, chat, events, previews, and tunnels.",
   "license": "UNLICENSED",
   "private": false,

package/runtime/scripts/amalgm-mcp/lib/prepared.js

@@ -0,0 +1,27 @@
+'use strict';
+
+/**
+ * Memoized statement preparation for one database handle.
+ *
+ * better-sqlite3 compiles the SQL text on EVERY `db.prepare()` call — it
+ * keeps no statement cache of its own. The stores' row-level verbs run
+ * thousands of times per scan (a first census inserts one row per file),
+ * so recompiling identical SQL each call was a measured double-digit
+ * share of a large registration. Each store builds one preparer over its
+ * injected handle and asks it instead; the SQL string is the whole key,
+ * so a handful of table-templated queries memoize to a handful of
+ * statements, never an unbounded set.
+ */
+function preparer(db) {
+  const statements = new Map();
+  return (sql) => {
+    let statement = statements.get(sql);
+    if (!statement) {
+      statement = db.prepare(sql);
+      statements.set(sql, statement);
+    }
+    return statement;
+  };
+}
+
+module.exports = { preparer };

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

@@ -407,8 +407,10 @@ function createObserver(options) {
       || linkDiff.renames.length || linkDiff.creates.length || linkDiff.deletes.length
       || fileDiff.renames.length || fileDiff.creates.length || fileDiff.deletes.length;
     if (structural) return false;
-    applyLinkDiff(root, linkDiff); // changes and retags: payload-local facts
-    applyDiff(root, fileDiff); // checks only: content truth on existing channels
+    store.transaction(() => {
+      applyLinkDiff(root, linkDiff); // changes and retags: payload-local facts
+      applyDiff(root, fileDiff); // checks only: content truth on existing channels
+    });
     return true;
   }
 
@@ -448,11 +450,17 @@ function createObserver(options) {
       : { ...diff, deletes: diff.deletes.filter((row) => !underUnsettled(row.relPath)) });
     if (unsettled.length > 0 && state) armRetry(root, state);
 
-    applyDirDiff(root, concluded(diffDirState(store.dirsForRoot(root.rootId), dirs)));
-    applyLinkDiff(root, concluded(diffLinkState(store.linksForRoot(root.rootId), links)));
-    const rows = store.filesForRoot(root.rootId);
-    const mustCheck = checkAll ? new Set(entries.map((entry) => entry.relPath)) : rung;
-    applyDiff(root, concluded(diffRootState(rows, entries, mustCheck)));
+    // One walk's conclusions are one durable transition: a census over
+    // thousands of channels commits once, not once per row. Events stay
+    // hints — a consumer told early about a rolled-back row re-reads
+    // store truth and finds the old state, which concludes nothing.
+    store.transaction(() => {
+      applyDirDiff(root, concluded(diffDirState(store.dirsForRoot(root.rootId), dirs)));
+      applyLinkDiff(root, concluded(diffLinkState(store.linksForRoot(root.rootId), links)));
+      const rows = store.filesForRoot(root.rootId);
+      const mustCheck = checkAll ? new Set(entries.map((entry) => entry.relPath)) : rung;
+      applyDiff(root, concluded(diffRootState(rows, entries, mustCheck)));
+    });
   }
 
   /**

package/runtime/scripts/amalgm-mcp/observer/store.js

@@ -15,6 +15,8 @@
  * is durable, or its loss is explicit.
  */
 
+const { preparer } = require('../lib/prepared');
+
 const SCHEMA = `
 CREATE TABLE IF NOT EXISTS observer_roots (
   root_id TEXT PRIMARY KEY,
@@ -141,6 +143,8 @@ function createStore(db) {
   db.exec(SCHEMA);
   db.pragma(`user_version = ${GENERATION}`);
 
+  const prepared = preparer(db);
+
   /**
    * One directory's immediate child rows — the scoped scan's slice of
    * memory, served by the (root_id, rel_path) unique index. '0' is the
@@ -150,33 +154,43 @@ function createStore(db) {
    */
   function immediateRows(table, rootId, relDir) {
     if (relDir === '') {
-      return db.prepare(`SELECT * FROM ${table} WHERE root_id = ? AND instr(rel_path, '/') = 0 ORDER BY rel_path`)
+      return prepared(`SELECT * FROM ${table} WHERE root_id = ? AND instr(rel_path, '/') = 0 ORDER BY rel_path`)
         .all(rootId);
     }
     const prefix = `${relDir}/`;
-    return db.prepare(`SELECT * FROM ${table} WHERE root_id = ? AND rel_path >= ? AND rel_path < ? ORDER BY rel_path`)
+    return prepared(`SELECT * FROM ${table} WHERE root_id = ? AND rel_path >= ? AND rel_path < ? ORDER BY rel_path`)
       .all(rootId, prefix, `${relDir}0`)
       .filter((row) => !row.rel_path.slice(prefix.length).includes('/'));
   }
 
   return {
+    /**
+     * One scan's whole apply phase commits as one durable transition.
+     * Row-level verbs each pay a full journal cycle when run bare, so a
+     * census over thousands of channels was thousands of commits; batched,
+     * it is one. Nesting is safe — SQLite savepoints — and a crash
+     * mid-batch leaves the previous truth whole, exactly like applyDirDiff.
+     */
+    transaction(fn) {
+      return db.transaction(fn)();
+    },
     addRoot({ rootId, path, kind, device = null, inode = null }) {
-      db.prepare('INSERT INTO observer_roots (root_id, path, kind, device, inode) VALUES (?, ?, ?, ?, ?)')
+      prepared('INSERT INTO observer_roots (root_id, path, kind, device, inode) VALUES (?, ?, ?, ?, ?)')
         .run(rootId, path, kind, device, inode);
     },
     rootByPath(path) {
-      const row = db.prepare('SELECT * FROM observer_roots WHERE path = ?').get(path);
+      const row = prepared('SELECT * FROM observer_roots WHERE path = ?').get(path);
       return row ? rowToRoot(row) : null;
     },
     listRoots() {
-      return db.prepare('SELECT * FROM observer_roots ORDER BY path').all().map(rowToRoot);
+      return prepared('SELECT * FROM observer_roots ORDER BY path').all().map(rowToRoot);
     },
     setRootKind(rootId, kind) {
-      db.prepare('UPDATE observer_roots SET kind = ? WHERE root_id = ?').run(kind, rootId);
+      prepared('UPDATE observer_roots SET kind = ? WHERE root_id = ?').run(kind, rootId);
     },
     /** Identity persists; local presence is separate evidence. */
     setRootPresent(rootId, present) {
-      db.prepare('UPDATE observer_roots SET present = ? WHERE root_id = ?').run(present ? 1 : 0, rootId);
+      prepared('UPDATE observer_roots SET present = ? WHERE root_id = ?').run(present ? 1 : 0, rootId);
     },
     /**
      * A root's identity is permanent; its address is not — and a family
@@ -186,7 +200,7 @@ function createStore(db) {
      * Device and inode are continuity itself and never churn on a rename.
      */
     moveRoots(moves) {
-      const move = db.prepare('UPDATE observer_roots SET path = ? WHERE root_id = ?');
+      const move = prepared('UPDATE observer_roots SET path = ? WHERE root_id = ?');
       db.transaction(() => {
         for (const { rootId, path } of moves) move.run(path, rootId);
       })();
@@ -195,18 +209,18 @@ function createStore(db) {
      * new identity at a known address (see enrollRoot) — the one write
      * where a root's own device:inode may change. */
     setRootIdentity(rootId, device, inode) {
-      db.prepare('UPDATE observer_roots SET device = ?, inode = ? WHERE root_id = ?')
+      prepared('UPDATE observer_roots SET device = ?, inode = ? WHERE root_id = ?')
         .run(device, inode, rootId);
     },
     removeRoot(rootId) {
-      db.prepare('DELETE FROM observer_files WHERE root_id = ?').run(rootId);
-      db.prepare('DELETE FROM observer_dirs WHERE root_id = ?').run(rootId);
-      db.prepare('DELETE FROM observer_links WHERE root_id = ?').run(rootId);
-      db.prepare('DELETE FROM observer_roots WHERE root_id = ?').run(rootId);
+      prepared('DELETE FROM observer_files WHERE root_id = ?').run(rootId);
+      prepared('DELETE FROM observer_dirs WHERE root_id = ?').run(rootId);
+      prepared('DELETE FROM observer_links WHERE root_id = ?').run(rootId);
+      prepared('DELETE FROM observer_roots WHERE root_id = ?').run(rootId);
     },
 
     filesForRoot(rootId) {
-      return db.prepare('SELECT * FROM observer_files WHERE root_id = ? ORDER BY rel_path').all(rootId)
+      return prepared('SELECT * FROM observer_files WHERE root_id = ? ORDER BY rel_path').all(rootId)
         .map(rowToFile);
     },
     filesInDir(rootId, relDir) {
@@ -220,11 +234,11 @@ function createStore(db) {
     },
     fileByPath(rootId, relPath) {
       return rowToFile(
-        db.prepare('SELECT * FROM observer_files WHERE root_id = ? AND rel_path = ?').get(rootId, relPath),
+        prepared('SELECT * FROM observer_files WHERE root_id = ? AND rel_path = ?').get(rootId, relPath),
       );
     },
     insertFile(file) {
-      db.prepare(`
+      prepared(`
         INSERT INTO observer_files (file_id, root_id, rel_path, device, inode, size, mtime_ms, content_hash, is_binary, hashed_at_ms)
         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
       `).run(
@@ -233,18 +247,18 @@ function createStore(db) {
       );
     },
     updateFile(fileId, { relPath, device, inode, size, mtimeMs, contentHash, binary, hashedAtMs }) {
-      db.prepare(`
+      prepared(`
         UPDATE observer_files
         SET rel_path = ?, device = ?, inode = ?, size = ?, mtime_ms = ?, content_hash = ?, is_binary = ?, hashed_at_ms = ?
         WHERE file_id = ?
       `).run(relPath, device, inode, size, mtimeMs, contentHash, binary ? 1 : 0, hashedAtMs, fileId);
     },
     removeFile(fileId) {
-      db.prepare('DELETE FROM observer_files WHERE file_id = ?').run(fileId);
+      prepared('DELETE FROM observer_files WHERE file_id = ?').run(fileId);
     },
 
     dirsForRoot(rootId) {
-      return db.prepare('SELECT * FROM observer_dirs WHERE root_id = ? ORDER BY rel_path').all(rootId)
+      return prepared('SELECT * FROM observer_dirs WHERE root_id = ? ORDER BY rel_path').all(rootId)
         .map(rowToDir);
     },
     /**
@@ -257,9 +271,9 @@ function createStore(db) {
      * the next scan re-detects the same batch.
      */
     applyDirDiff({ deletes, moves, retags, creates }) {
-      const remove = db.prepare('DELETE FROM observer_dirs WHERE dir_id = ?');
-      const insert = db.prepare('INSERT INTO observer_dirs (dir_id, root_id, rel_path, device, inode) VALUES (?, ?, ?, ?, ?)');
-      const retag = db.prepare('UPDATE observer_dirs SET rel_path = ?, device = ?, inode = ? WHERE dir_id = ?');
+      const remove = prepared('DELETE FROM observer_dirs WHERE dir_id = ?');
+      const insert = prepared('INSERT INTO observer_dirs (dir_id, root_id, rel_path, device, inode) VALUES (?, ?, ?, ?, ?)');
+      const retag = prepared('UPDATE observer_dirs SET rel_path = ?, device = ?, inode = ? WHERE dir_id = ?');
       db.transaction(() => {
         for (const dirId of deletes) remove.run(dirId);
         for (const dir of moves) remove.run(dir.dirId);
@@ -269,7 +283,7 @@ function createStore(db) {
       })();
     },
     removeDir(dirId) {
-      db.prepare('DELETE FROM observer_dirs WHERE dir_id = ?').run(dirId);
+      prepared('DELETE FROM observer_dirs WHERE dir_id = ?').run(dirId);
     },
 
     // Link channels: a pointer's whole payload is its target string, read
@@ -277,19 +291,19 @@ function createStore(db) {
     // a rename only ever targets a row-free slot), so link rows commit
     // per-row like files — every commit is a valid last-known truth.
     linksForRoot(rootId) {
-      return db.prepare('SELECT * FROM observer_links WHERE root_id = ? ORDER BY rel_path').all(rootId)
+      return prepared('SELECT * FROM observer_links WHERE root_id = ? ORDER BY rel_path').all(rootId)
         .map(rowToLink);
     },
     insertLink({ linkId, rootId, relPath, device, inode, target }) {
-      db.prepare('INSERT INTO observer_links (link_id, root_id, rel_path, device, inode, target) VALUES (?, ?, ?, ?, ?, ?)')
+      prepared('INSERT INTO observer_links (link_id, root_id, rel_path, device, inode, target) VALUES (?, ?, ?, ?, ?, ?)')
         .run(linkId, rootId, relPath, device, inode, target);
     },
     updateLink(linkId, { relPath, device, inode, target }) {
-      db.prepare('UPDATE observer_links SET rel_path = ?, device = ?, inode = ?, target = ? WHERE link_id = ?')
+      prepared('UPDATE observer_links SET rel_path = ?, device = ?, inode = ?, target = ? WHERE link_id = ?')
         .run(relPath, device, inode, target, linkId);
     },
     removeLink(linkId) {
-      db.prepare('DELETE FROM observer_links WHERE link_id = ?').run(linkId);
+      prepared('DELETE FROM observer_links WHERE link_id = ?').run(linkId);
     },
   };
 }

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

@@ -124,7 +124,15 @@ function parseSnapshot(bytes) {
  * no watcher imports: a cloud record may be known on this machine long before
  * `amalgm add <uuid>` chooses and validates local ground for it.
  */
-function createEntityCloud({ db, userId, deviceId, content = null, repoStates = null, repoTransportFor = null }) {
+function createEntityCloud({
+  db,
+  userId,
+  deviceId,
+  content = null,
+  repoStates = null,
+  repoTransportFor = null,
+  recordAt = null,
+}) {
   if (!db) throw new Error('createEntityCloud requires an identity database');
   const ownerUserId = typeof userId === 'string' && userId ? userId : null;
   const localDeviceId = typeof deviceId === 'string' && deviceId ? deviceId : null;
@@ -155,17 +163,62 @@ function createEntityCloud({ db, userId, deviceId, content = null, repoStates =
     return snapshotFromRecords(records.map(cloudRecord));
   }
 
-  function queueContent(input, resourceId, { queue = false } = {}) {
-    const record = cloudRecord(input);
-    const head = contentHead(record);
-    if (!head) return;
-    if (!content || typeof content.has !== 'function') {
-      throw new Error('file entity content is unavailable: registration must capture bytes before it records their cloud head');
+  /**
+   * Select bytes by the root representation that reconstructs them. A
+   * repository's Repocard transport contains its worktree, so child file rows
+   * retain their UUID/version facts but never create duplicate cloud cargo.
+   * Ordinary workspace files still carry their own content, and a nested
+   * repository carries its own transport.
+   */
+  function contentHeads(records, { fallbackRecordAt = recordAt } = {}) {
+    const normalized = (records || []).map(cloudRecord);
+    const supplied = new Map(normalized.map((record) => [record.uuid, record]));
+    const lookup = (uuid) => {
+      const known = supplied.get(uuid);
+      if (known) return known;
+      const fallback = typeof fallbackRecordAt === 'function' ? fallbackRecordAt(uuid) : null;
+      return fallback ? cloudRecord(fallback) : null;
+    };
+
+    function enclosedByRepository(record) {
+      const seen = new Set([record.uuid]);
+      let parentUUID = record.parentUUID;
+      while (parentUUID !== null) {
+        if (seen.has(parentUUID)) throw new Error(`cloud entity ${record.uuid} has a cyclic parent chain`);
+        seen.add(parentUUID);
+        const parent = lookup(parentUUID);
+        // Missing ancestry retains content rather than risking an ordinary
+        // file whose only bytes were silently skipped.
+        if (!parent) return false;
+        if (parent.type === 'repo.git') return true;
+        parentUUID = parent.parentUUID;
+      }
+      return false;
+    }
+
+    const heads = [];
+    const seen = new Set();
+    for (const record of normalized) {
+      const contentHash = contentHead(record);
+      if (!contentHash) continue;
+      if (['file.text', 'file.binary'].includes(record.type) && enclosedByRepository(record)) continue;
+      if (seen.has(contentHash)) continue;
+      seen.add(contentHash);
+      heads.push({ record, contentHash });
     }
-    if (!content.has({ contentHash: head })) {
-      throw new Error('file entity bytes were not captured before its cloud head committed');
+    return heads;
+  }
+
+  function queueContentHeads(records, resourceId, { queue = false, fallbackRecordAt = recordAt } = {}) {
+    for (const { contentHash } of contentHeads(records, { fallbackRecordAt })) {
+      if (!content || typeof content.has !== 'function') {
+        throw new Error('file entity content is unavailable: registration must capture bytes before it records their cloud head');
+      }
+      if (!content.has({ contentHash })) {
+        throw new Error('file entity bytes were not captured before its cloud head committed');
+      }
+      if (queue) content.ensureUpload({ resourceId, contentHash });
     }
-    if (queue) content.ensureUpload({ resourceId, contentHash: head });
   }
 
   function replica() {
@@ -383,7 +436,7 @@ function createEntityCloud({ db, userId, deviceId, content = null, repoStates =
     // content drain creates the filesystem upload cursor; doing that here
     // would let a rolled-back identity write upload unreachable bytes.
     const cloud = cloudRecord(record);
-    queueContent(cloud, current.resourceId);
+    queueContentHeads([cloud], current.resourceId);
     upsertCatalogRecord({
       resourceId: current.resourceId,
       authorityEpoch: current.authorityEpoch,
@@ -423,7 +476,7 @@ function createEntityCloud({ db, userId, deviceId, content = null, repoStates =
     if (bytes > SNAPSHOT_REPLACE_MAX_BYTES) {
       throw new Error(`registered entity graph is ${bytes} bytes; the atomic cloud registration limit is ${SNAPSHOT_REPLACE_MAX_BYTES} bytes`);
     }
-    for (const record of snapshot.records) queueContent(record, current.resourceId, { queue: true });
+    queueContentHeads(snapshot.records, current.resourceId, { queue: true });
     const createdAt = now();
     db.prepare(`
       INSERT INTO entity_cloud_mutations (
@@ -448,8 +501,9 @@ function createEntityCloud({ db, userId, deviceId, content = null, repoStates =
     }
     const insert = db.prepare('INSERT INTO entity_cloud_mutations (resource_id, mutation_id, operation_json, mutation_state, created_at, updated_at) VALUES (?, ?, ?, \'pending\', ?, ?)');
     const createdAt = now();
-    for (const record of cloudSnapshot(records).records) {
-      queueContent(record, current.resourceId, { queue: true });
+    const snapshot = cloudSnapshot(records);
+    queueContentHeads(snapshot.records, current.resourceId, { queue: true });
+    for (const record of snapshot.records) {
       insert.run(
         current.resourceId,
         'ent_' + crypto.randomBytes(18).toString('base64url'),
@@ -632,7 +686,7 @@ function createEntityCloud({ db, userId, deviceId, content = null, repoStates =
     // 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 });
+      queueContentHeads(snapshot.records, resourceId, { queue: true });
     }
     replaceCatalog({
       resourceId,
@@ -706,15 +760,13 @@ function createEntityCloud({ db, userId, deviceId, content = null, repoStates =
     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 (record.status !== 'active') continue;
-        const head = contentHead(record);
-        if (!head) continue;
-        const part = content.missingPart({ contentHash: head });
+      const active = tree.filter((record) => record.status === 'active');
+      for (const { contentHash } of contentHeads(active)) {
+        const part = content.missingPart({ contentHash });
         if (!part) continue;
         return {
           resourceId: job.resourceId,
-          contentHash: head,
+          contentHash,
           kind: part.kind,
           partIndex: part.partIndex,
           sha256: part.sha256,
@@ -882,10 +934,9 @@ function createEntityCloud({ db, userId, deviceId, content = null, repoStates =
         const records = operation?.kind === SNAPSHOT_REPLACE_OPERATION
           ? operation?.snapshot?.records
           : [operation?.record];
-        if ((records || []).some((record) => {
-          const head = contentHead(record);
-          return head && (!content || !content.uploaded({ resourceId: current.resourceId, contentHash: head }));
-        })) {
+        if (contentHeads(records).some(({ contentHash }) => (
+          !content || !content.uploaded({ resourceId: current.resourceId, contentHash })
+        ))) {
           return [];
         }
         claimRow.run(current.headVersion, leaseUntil, started, row.sequence);
@@ -923,7 +974,7 @@ function createEntityCloud({ db, userId, deviceId, content = null, repoStates =
       const records = operation?.kind === SNAPSHOT_REPLACE_OPERATION
         ? operation?.snapshot?.records
         : [operation?.record];
-      for (const record of records || []) queueContent(record, current.resourceId, { queue: true });
+      queueContentHeads(records || [], current.resourceId, { queue: true });
       contentQueuedSequences.add(row.sequence);
     }
     return content.claim({ resourceId: current.resourceId, leaseMs });
@@ -1136,6 +1187,7 @@ function createEntityCloud({ db, userId, deviceId, content = null, repoStates =
     status,
     hasUnsettledLocalMutation,
     catalogTree,
+    contentHeads,
     replica,
   };
 }

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

@@ -86,6 +86,17 @@ function createRegistrationService({
 
   const evidenceDb = new Database(path.join(dir, 'observer.db'));
   const identityDb = new Database(path.join(dir, 'identity.db'));
+  // WAL, decided here because this root OWNS the handles: SQLite's default
+  // journal mode pays a create-fsync-delete journal cycle on every commit,
+  // which made a large registration ~65% commit ceremony. WAL appends to
+  // one log instead, and synchronous=NORMAL keeps every commit durable
+  // against process crash (an OS crash can lose the tail, never corrupt —
+  // detection re-derives evidence, and identity commits are re-walked by
+  // the registration that was still running).
+  for (const handle of [evidenceDb, identityDb]) {
+    handle.pragma('journal_mode = WAL');
+    handle.pragma('synchronous = NORMAL');
+  }
   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
@@ -106,6 +117,10 @@ function createRegistrationService({
     return localState(captured, artifact.contentHash);
   }
 
+  // Entity-cloud needs only logical ancestry to choose a content plan. It
+  // never owns a watcher or address; this facade is available after the
+  // registration boundary is constructed below.
+  const boundary = { current: null };
   const entityCloud = createEntityCloud({
     db: identityDb,
     userId: cloudUserId,
@@ -113,11 +128,13 @@ function createRegistrationService({
     content: entityContent,
     repoStates: repoStateLookup,
     repoTransportFor: (record) => repoTransportHeads.get(record.payloadVersion) || null,
+    recordAt: (uuid) => {
+      try { return boundary.current?.registry.syncRecord(uuid) || null; } catch { return null; }
+    },
   });
 
   // The observer emits before the boundary exists (its constructor
   // scans), so the wire reads through a box that the boundary fills.
-  const boundary = { current: null };
   const observer = createObserver({
     db: evidenceDb,
     emit: (event) => boundary.current?.onEvent(event),
@@ -474,15 +491,8 @@ function createRegistrationService({
       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;
-      }
+    for (const { contentHash } of entityCloud.contentHeads(active)) {
+      if (!entityContent.complete({ contentHash })) return false;
     }
     if (!['workspace', 'repo.git', 'file.text', 'file.binary', 'link'].includes(root.type)) {
       throw new Error(`cloud root ${root.uuid} is ${root.type}; this materializer supports workspace, repository, file, and link trees only`);
@@ -579,11 +589,8 @@ function createRegistrationService({
     if (!['workspace', 'repo.git', 'file.text', 'file.binary', 'link'].includes(root.type)) {
       throw new Error(`cloud root ${root.uuid} is ${root.type}; this live materializer supports workspace, repository, file, and link 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;
+    for (const { contentHash } of entityCloud.contentHeads(active)) {
+      if (!entityContent.complete({ contentHash })) return false;
     }
 
     const parent = fs.realpathSync(job.targetPath);
@@ -877,7 +884,13 @@ function createRegistrationService({
     /** `amalgm register <path>` — register, then begin Watch + Detect. */
     register: async (targetPath) => {
       entityCloud.assertRegistrationReady();
-      if (estimatedRegistrationRecords(targetPath) < ATOMIC_REGISTRATION_THRESHOLD) {
+      // No active cloud replica means no cloud is listening — the journal
+      // itself already no-ops there, so a large tree takes the same plain
+      // local registration a small one does instead of demanding an atomic
+      // replacement that has nowhere to land. Size never changes whether a
+      // signed-out registration is allowed.
+      const cloudActive = entityCloud.replica()?.state === 'active';
+      if (!cloudActive || estimatedRegistrationRecords(targetPath) < ATOMIC_REGISTRATION_THRESHOLD) {
         return boundary.current.add(targetPath);
       }
       const result = boundary.current.registry.withoutJournal(() => boundary.current.add(targetPath));
@@ -890,9 +903,10 @@ function createRegistrationService({
      * materialize. Small selections retain their ordinary per-entity intent. */
     registerMany: async (targetPaths) => {
       entityCloud.assertRegistrationReady();
-      const needsAtomicReplacement = targetPaths.some((targetPath) => (
-        estimatedRegistrationRecords(targetPath) >= ATOMIC_REGISTRATION_THRESHOLD
-      ));
+      const needsAtomicReplacement = entityCloud.replica()?.state === 'active'
+        && 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());

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

@@ -103,6 +103,8 @@
 const fs = require('fs');
 const path = require('path');
 
+const { preparer } = require('../lib/prepared');
+
 const FILE_TYPES = new Set(['file.text', 'file.binary']);
 const LEAF_TYPES = new Set(['file.text', 'file.binary', 'link']);
 // Adoption candidates by ground shape: a dir channel can be an arrived
@@ -132,6 +134,7 @@ const MEMORY_TABLES = ['registry_meta', 'channel_bindings', 'contested_ground'];
  * Retiring a tree drops its whole scope — bindings and markers together.
  */
 function createEvidenceMemory(db) {
+  const prepared = preparer(db);
   const present = db.prepare(
     `SELECT name FROM sqlite_master WHERE type = 'table' AND name IN (${MEMORY_TABLES.map(() => '?').join(', ')})`,
   ).all(...MEMORY_TABLES).map((row) => row.name);
@@ -145,30 +148,30 @@ function createEvidenceMemory(db) {
   }
   return {
     epoch: () => meta.epoch_uuid,
-    bindings: (scopeId) => db.prepare('SELECT channel_id, entity_uuid FROM channel_bindings WHERE scope_id = ?')
+    bindings: (scopeId) => prepared('SELECT channel_id, entity_uuid FROM channel_bindings WHERE scope_id = ?')
       .all(scopeId).map((row) => ({ channelId: row.channel_id, uuid: row.entity_uuid })),
-    bind: (scopeId, channelId, uuid) => db.prepare(
+    bind: (scopeId, channelId, uuid) => prepared(
       'INSERT INTO channel_bindings (channel_id, scope_id, entity_uuid) VALUES (?, ?, ?)'
       + ' ON CONFLICT(channel_id) DO UPDATE SET scope_id = excluded.scope_id, entity_uuid = excluded.entity_uuid',
     ).run(channelId, scopeId, uuid),
-    unbind: (channelId) => db.prepare('DELETE FROM channel_bindings WHERE channel_id = ?').run(channelId),
+    unbind: (channelId) => prepared('DELETE FROM channel_bindings WHERE channel_id = ?').run(channelId),
     /** Across scopes — channel ids are globally unique. */
-    boundTo: (channelId) => db.prepare('SELECT entity_uuid FROM channel_bindings WHERE channel_id = ?')
+    boundTo: (channelId) => prepared('SELECT entity_uuid FROM channel_bindings WHERE channel_id = ?')
       .get(channelId)?.entity_uuid,
-    allBindings: () => db.prepare('SELECT channel_id, scope_id, entity_uuid FROM channel_bindings').all()
+    allBindings: () => prepared('SELECT channel_id, scope_id, entity_uuid FROM channel_bindings').all()
       .map((row) => ({ channelId: row.channel_id, scopeId: row.scope_id, uuid: row.entity_uuid })),
     /** A retired tree's whole evidence namespace, gone as one act. */
     dropScope: (scopeId) => {
-      db.prepare('DELETE FROM channel_bindings WHERE scope_id = ?').run(scopeId);
-      db.prepare('DELETE FROM contested_ground WHERE scope_id = ?').run(scopeId);
+      prepared('DELETE FROM channel_bindings WHERE scope_id = ?').run(scopeId);
+      prepared('DELETE FROM contested_ground WHERE scope_id = ?').run(scopeId);
     },
-    contests: (scopeId) => db.prepare('SELECT rel_path, claimant_uuid, kind FROM contested_ground WHERE scope_id = ?')
+    contests: (scopeId) => prepared('SELECT rel_path, claimant_uuid, kind FROM contested_ground WHERE scope_id = ?')
       .all(scopeId).map((row) => ({ relPath: row.rel_path, uuid: row.claimant_uuid, kind: row.kind })),
-    contest: (scopeId, relPath, uuid, kind) => db.prepare(
+    contest: (scopeId, relPath, uuid, kind) => prepared(
       'INSERT INTO contested_ground (scope_id, rel_path, claimant_uuid, kind) VALUES (?, ?, ?, ?)'
       + ' ON CONFLICT(scope_id, rel_path) DO UPDATE SET claimant_uuid = excluded.claimant_uuid, kind = excluded.kind',
     ).run(scopeId, relPath, uuid, kind),
-    clearContest: (scopeId, relPath) => db.prepare('DELETE FROM contested_ground WHERE scope_id = ? AND rel_path = ?')
+    clearContest: (scopeId, relPath) => prepared('DELETE FROM contested_ground WHERE scope_id = ? AND rel_path = ?')
       .run(scopeId, relPath),
   };
 }
@@ -359,6 +362,27 @@ function createEvidence(options) {
   function reconcile() {
     dirty = false; // an event landing mid-reconcile re-dirties honestly
     try {
+      // One reconciliation is ONE durable truth transition: a first census
+      // over thousands of channels lands as one commit, not one per record.
+      // The registry's own transaction defers every bell to the commit and
+      // discards them all on rollback, so a failed pass publishes nothing.
+      registry.transaction(pass);
+    } catch (error) {
+      // The transaction rolled every durable write back; the in-memory
+      // caches may still hold entries from the rolled-back half. Durable
+      // truth first, cache second — so the caches reload from the tables
+      // before the retry, never believing a write that no longer exists.
+      channelToUuid.clear();
+      for (const row of memory.bindings(rootId)) channelToUuid.set(row.channelId, row.uuid);
+      contested.clear();
+      for (const row of memory.contests(rootId)) contested.set(row.relPath, { uuid: row.uuid, kind: row.kind });
+      dirty = true;
+      throw error;
+    }
+  }
+
+  function pass() {
+    {
       const rootRow = observer.listRoots().find((row) => row.rootId === rootId);
       if (!rootRow) return; // not enrolled yet — nothing is claimed
       groundPath = rootRow.path; // the address is derived, never the lens's identity
@@ -771,9 +795,6 @@ function createEvidence(options) {
             : null);
       }
       for (const [relPath, hash] of nowDivergent) divergent.set(relPath, hash);
-    } catch (error) {
-      dirty = true;
-      throw error;
     }
   }
 

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

@@ -26,6 +26,8 @@
  * (address), never by name, so two trees may share a basename.
  */
 
+const { preparer } = require('../lib/prepared');
+
 const SCHEMA = `
 CREATE TABLE IF NOT EXISTS registry_meta (
   singleton INTEGER PRIMARY KEY CHECK (singleton = 1),
@@ -246,56 +248,58 @@ function createStore(db) {
   db.exec(SCHEMA);
   db.pragma(`user_version = ${GENERATION}`);
 
+  const prepared = preparer(db);
+
   return {
     meta() {
-      const row = db.prepare('SELECT * FROM registry_meta WHERE singleton = 1').get();
+      const row = prepared('SELECT * FROM registry_meta WHERE singleton = 1').get();
       return row ? { epochUuid: row.epoch_uuid, createdAtMs: row.created_at_ms } : null;
     },
     initMeta({ epochUuid, createdAtMs }) {
-      db.prepare('INSERT INTO registry_meta (singleton, epoch_uuid, created_at_ms) VALUES (1, ?, ?)')
+      prepared('INSERT INTO registry_meta (singleton, epoch_uuid, created_at_ms) VALUES (1, ?, ?)')
         .run(epochUuid, createdAtMs);
     },
 
     byUuid(uuid) {
-      return rowToEntity(db.prepare('SELECT * FROM entities WHERE uuid = ?').get(uuid));
+      return rowToEntity(prepared('SELECT * FROM entities WHERE uuid = ?').get(uuid));
     },
     /** Every registered tree's top record: the active parentless rows. */
     activeRoots() {
-      return db.prepare("SELECT * FROM entities WHERE parent_uuid IS NULL AND status = 'active' ORDER BY uuid")
+      return prepared("SELECT * FROM entities WHERE parent_uuid IS NULL AND status = 'active' ORDER BY uuid")
         .all().map(rowToEntity);
     },
     activeAtSlot(parentUuid, name) {
       return rowToEntity(
-        db.prepare("SELECT * FROM entities WHERE parent_uuid IS ? AND name = ? AND status = 'active'")
+        prepared("SELECT * FROM entities WHERE parent_uuid IS ? AND name = ? AND status = 'active'")
           .get(parentUuid, name),
       );
     },
     childrenOf(parentUuid) {
-      return db.prepare('SELECT * FROM entities WHERE parent_uuid = ? ORDER BY uuid').all(parentUuid)
+      return prepared('SELECT * FROM entities WHERE parent_uuid = ? ORDER BY uuid').all(parentUuid)
         .map(rowToEntity);
     },
     activeChildrenOf(parentUuid) {
-      return db.prepare("SELECT * FROM entities WHERE parent_uuid = ? AND status = 'active' ORDER BY uuid")
+      return prepared("SELECT * FROM entities WHERE parent_uuid = ? AND status = 'active' ORDER BY uuid")
         .all(parentUuid).map(rowToEntity);
     },
     activeByType(type) {
-      return db.prepare("SELECT * FROM entities WHERE type = ? AND status = 'active' ORDER BY uuid")
+      return prepared("SELECT * FROM entities WHERE type = ? AND status = 'active' ORDER BY uuid")
         .all(type).map(rowToEntity);
     },
     /** Logical graph rows for the cloud registry. This deliberately excludes
      * observer bindings and every machine-local table. */
     allEntities() {
-      return db.prepare('SELECT * FROM entities ORDER BY uuid').all().map(rowToEntity);
+      return prepared('SELECT * FROM entities ORDER BY uuid').all().map(rowToEntity);
     },
 
     insert(entity) {
-      db.prepare(`
+      prepared(`
         INSERT INTO entities (uuid, type, parent_uuid, name, status, payload_version)
         VALUES (?, ?, ?, ?, ?, ?)
       `).run(entity.uuid, entity.type, entity.parentUuid, entity.name, entity.status, entity.payloadVersion);
     },
     update(uuid, { type, parentUuid, name, status, payloadVersion }) {
-      db.prepare(`
+      prepared(`
         UPDATE entities SET type = ?, parent_uuid = ?, name = ?, status = ?, payload_version = ?
         WHERE uuid = ?
       `).run(type, parentUuid, name, status, payloadVersion, uuid);
@@ -313,17 +317,17 @@ function createStore(db) {
      */
     rebindIdentities(mappings) {
       const retired = mappings.filter((mapping) => mapping.oldUuid !== mapping.newUuid);
-      const retire = db.prepare("UPDATE entities SET status = 'trashed' WHERE uuid = ?");
-      const insert = db.prepare(`
+      const retire = prepared("UPDATE entities SET status = 'trashed' WHERE uuid = ?");
+      const insert = prepared(`
         INSERT INTO entities (uuid, type, parent_uuid, name, status, payload_version)
         VALUES (?, ?, ?, ?, ?, ?)
       `);
-      const reparent = db.prepare('UPDATE entities SET parent_uuid = ? WHERE parent_uuid = ?');
-      const rebindChannels = db.prepare('UPDATE channel_bindings SET entity_uuid = ? WHERE entity_uuid = ?');
-      const rebindClaims = db.prepare('UPDATE contested_ground SET claimant_uuid = ? WHERE claimant_uuid = ?');
-      const rebindRepoState = db.prepare('UPDATE repo_states SET entity_uuid = ? WHERE entity_uuid = ?');
-      const rebindReference = db.prepare("UPDATE entities SET payload_version = ? WHERE type = 'reference' AND payload_version = ?");
-      const remove = db.prepare('DELETE FROM entities WHERE uuid = ?');
+      const reparent = prepared('UPDATE entities SET parent_uuid = ? WHERE parent_uuid = ?');
+      const rebindChannels = prepared('UPDATE channel_bindings SET entity_uuid = ? WHERE entity_uuid = ?');
+      const rebindClaims = prepared('UPDATE contested_ground SET claimant_uuid = ? WHERE claimant_uuid = ?');
+      const rebindRepoState = prepared('UPDATE repo_states SET entity_uuid = ? WHERE entity_uuid = ?');
+      const rebindReference = prepared("UPDATE entities SET payload_version = ? WHERE type = 'reference' AND payload_version = ?");
+      const remove = prepared('DELETE FROM entities WHERE uuid = ?');
 
       db.transaction(() => {
         for (const mapping of retired) retire.run(mapping.oldUuid);
@@ -365,10 +369,10 @@ function createStore(db) {
      * for an exchange. One transaction: the in-between never exists.
      */
     applyMoves(moves) {
-      const toTemp = db.prepare('UPDATE entities SET name = ? WHERE uuid = ?');
+      const toTemp = prepared('UPDATE entities SET name = ? WHERE uuid = ?');
       // An optional type rides the same transition (adoption lands a
       // workspace as a folder) — a separate write could tear.
-      const toFinal = db.prepare('UPDATE entities SET parent_uuid = ?, name = ?, type = COALESCE(?, type) WHERE uuid = ?');
+      const toFinal = prepared('UPDATE entities SET parent_uuid = ?, name = ?, type = COALESCE(?, type) WHERE uuid = ?');
       db.transaction(() => {
         for (const move of moves) toTemp.run(`\0${move.uuid}`, move.uuid);
         for (const move of moves) toFinal.run(move.parentUuid, move.name, move.type ?? null, move.uuid);
@@ -376,7 +380,7 @@ function createStore(db) {
     },
 
     cloudReplica() {
-      const row = db.prepare('SELECT * FROM entity_cloud_replica WHERE singleton = 1').get();
+      const row = prepared('SELECT * FROM entity_cloud_replica WHERE singleton = 1').get();
       if (!row) return null;
       return {
         resourceId: row.resource_id,
@@ -389,7 +393,7 @@ function createStore(db) {
       };
     },
     saveCloudReplica(replica) {
-      db.prepare(`
+      prepared(`
         INSERT INTO entity_cloud_replica (
           singleton, resource_id, device_id, authority_epoch, head_version,
           state, snapshot_cutoff, updated_at
@@ -413,11 +417,11 @@ function createStore(db) {
       );
     },
     cloudMutationCutoff() {
-      const row = db.prepare('SELECT COALESCE(MAX(sequence), 0) AS sequence FROM entity_cloud_mutations').get();
+      const row = prepared('SELECT COALESCE(MAX(sequence), 0) AS sequence FROM entity_cloud_mutations').get();
       return Number(row.sequence);
     },
     enqueueCloudMutation(mutation) {
-      db.prepare(`
+      prepared(`
         INSERT INTO entity_cloud_mutations (
           resource_id, mutation_id, operation_json, mutation_state,
           created_at, updated_at
@@ -431,7 +435,7 @@ function createStore(db) {
       );
     },
     listCloudMutations() {
-      return db.prepare('SELECT * FROM entity_cloud_mutations ORDER BY sequence').all();
+      return prepared('SELECT * FROM entity_cloud_mutations ORDER BY sequence').all();
     },
   };
 }

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

@@ -369,20 +369,35 @@ test('add recreates an actual Git repository from verified Repocard cargo, then
       snapshotChecksum: sha256(snapshotBytes),
     });
 
-    const heads = new Set(records.flatMap((record) => {
-      if (['file.text', 'file.binary'].includes(record.type) && record.payloadVersion) return [record.payloadVersion];
-      if (record.type === 'repo.git' && record.transportVersion) return [record.transportVersion];
-      return [];
-    }));
-    for (const head of heads) {
-      const parts = uploadedParts(source.entityContent, bootstrap.resourceId, head);
-      for (const part of [...parts.filter((entry) => entry.kind === 'manifest'), ...parts.filter((entry) => entry.kind === 'chunk')]) {
-        target.receiveCloudContent({
-          resourceId: bootstrap.resourceId, contentHash: head, kind: part.kind,
-          partIndex: part.kind === 'manifest' ? 0 : part.partIndex,
-          sha256: part.sha256, dataBase64: part.dataBase64,
-        });
-      }
+    const planned = source.entityCloud.contentHeads(records);
+    assert.deepEqual(
+      planned.map(({ contentHash }) => contentHash),
+      [repoCloudRecord.transportVersion],
+      'a repository register uploads its one Repocard transport, never duplicate child file bytes',
+    );
+    const uploaded = [];
+    while (true) {
+      const part = source.entityCloud.claimContent();
+      if (!part) break;
+      uploaded.push(part);
+      source.entityCloud.acknowledgeContent({
+        resourceId: bootstrap.resourceId,
+        contentHash: part.contentHash,
+        kind: part.kind,
+        partIndex: part.partIndex,
+      });
+    }
+    assert.deepEqual(
+      [...new Set(uploaded.map((part) => part.contentHash))],
+      [repoCloudRecord.transportVersion],
+      'the source content pump sends only the repository transport',
+    );
+    for (const part of [...uploaded.filter((entry) => entry.kind === 'manifest'), ...uploaded.filter((entry) => entry.kind === 'chunk')]) {
+      target.receiveCloudContent({
+        resourceId: bootstrap.resourceId, contentHash: part.contentHash, kind: part.kind,
+        partIndex: part.kind === 'manifest' ? 0 : part.partIndex,
+        sha256: part.sha256, dataBase64: part.dataBase64,
+      });
     }
 
     const job = await target.add({ uuid: registered.record.uuid, targetPath: targetParent });

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

@@ -544,6 +544,27 @@ test('register registers the named ground and every file beneath it', async () =
   assert.equal(nested[0].type, 'file.binary', 'and it distinguishes bytes from text');
 });
 
+test('a signed-out installation registers a large tree the same way it registers a small one', async () => {
+  // Size routes a SIGNED-IN registration to the atomic cloud replacement;
+  // it must never decide whether a signed-out one is allowed at all. The
+  // journal already no-ops without an active replica, so a large tree takes
+  // the same plain local registration a small tree does.
+  const service = makeService('add-large-signed-out');
+  const ground = makeGround('add-large-signed-out');
+  for (let dir = 0; dir < 30; dir++) {
+    const nested = path.join(ground, `dir${dir}`);
+    fs.mkdirSync(nested);
+    for (let file = 0; file < 20; file++) {
+      fs.writeFileSync(path.join(nested, `f${file}.md`), `${dir}/${file}`);
+    }
+  }
+
+  const { record } = await service.register(ground);
+  assert.ok(record.uuid, 'the large tree registered without demanding a cloud handshake');
+  const registry = service.registration.tree(ground).registry;
+  assert.equal(registry.children(record.uuid).length, 30, 'every directory is registered');
+});
+
 test('registerMany registers every selected file or folder through the one registration boundary', async () => {
   const service = makeService('add-many');
   const folder = makeGround('add-many-folder');