amalgm 0.1.261 → 0.1.263

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/repocard/capture.js

@@ -62,13 +62,50 @@ function remoteList(repoPath) {
   }).sort((a, b) => (a.name < b.name ? -1 : 1));
 }
 
-function untrackedFiles(repoPath) {
+/** Is `rel` named by the suspect list — itself, or under a named directory? */
+function makeSuspectTest(suspects) {
+  const named = new Set(suspects);
+  return (rel) => {
+    if (named.has(rel)) return true;
+    let prefix = rel;
+    for (;;) {
+      const cut = prefix.lastIndexOf('/');
+      if (cut < 0) return false;
+      prefix = prefix.slice(0, cut);
+      if (named.has(prefix)) return true;
+    }
+  };
+}
+
+/**
+ * The warm half of the checkpoint. Git keeps the Card's ledger itself and
+ * its index makes the tracked diffs cheap — the one cost with no cache was
+ * untracked files, re-read in full on every capture. With `suspects` (the
+ * doorbell's named paths since the last settled state) and the previous
+ * state's untracked entries, an unsuspected file's (mode, sha256) is
+ * REUSED without opening it: silence from the doorbell is the proof the
+ * written answer is still true. Everything else stays a fresh read — a
+ * suspect, a new path, or any capture without both inputs (suspects null
+ * means "everything is suspect": first capture, flush, catch-up, a command
+ * ending). Reused entries carry `content: null`; ids derive from
+ * (path, mode, sha256) alone, so a scoped capture's ids are byte-identical
+ * to a from-scratch one over the same ground.
+ */
+function untrackedFiles(repoPath, { suspects = null, previousUntracked = null } = {}) {
+  const reusable = suspects !== null && previousUntracked
+    ? new Map(previousUntracked.map((file) => [file.path, file]))
+    : null;
+  const suspect = reusable ? makeSuspectTest(suspects) : null;
   const out = runGit(repoPath, ['ls-files', '--others', '--exclude-standard', '-z']).toString('utf8');
   return out.split('\0').filter(Boolean).sort().flatMap((rel) => {
     // A trailing slash is git marking a repo boundary it will not enter — a
     // nested repository or linked worktree. That is its own territory with
     // its own card; the parent's checkpoint must not contain it.
     if (rel.endsWith('/')) return [];
+    if (reusable && !suspect(rel)) {
+      const prev = reusable.get(rel);
+      if (prev) return [{ path: rel, mode: prev.mode, content: null, sha256: prev.sha256, reused: true }];
+    }
     const abs = path.join(repoPath, rel);
     try {
       const stat = fs.lstatSync(abs);
@@ -123,9 +160,14 @@ function deriveCheckpointId(checkpoint) {
   }));
 }
 
-function capture(repoPath, { withBundle = true } = {}) {
+function capture(repoPath, { withBundle = true, suspects = null, previousUntracked = null } = {}) {
   const busy = busyReason(repoPath);
   if (busy) return { busy };
+  // Untracked reuse is bundle-free (local) captures only: cloud cargo
+  // (prepareRepo) consumes untracked CONTENT, and a reused entry carries
+  // none. Teaching the cargo path to dedupe by sha256 is the named next
+  // step; until then a withBundle capture always reads every byte.
+  const scoped = withBundle ? {} : { suspects, previousUntracked };
 
   const branch = tryGitText(repoPath, ['symbolic-ref', '-q', '--short', 'HEAD']); // null = detached
   const commit = tryGitText(repoPath, ['rev-parse', '-q', '--verify', 'HEAD']);   // null = unborn
@@ -146,7 +188,7 @@ function capture(repoPath, { withBundle = true } = {}) {
     // raw non-UTF-8 bytes, and a string conversion would corrupt it silently.
     stagedPatch: runGit(repoPath, ['diff', '--cached', '--binary', '--full-index', commit ? 'HEAD' : EMPTY_TREE]),
     unstagedPatch: runGit(repoPath, ['diff', '--binary', '--full-index']),
-    untracked: untrackedFiles(repoPath),
+    untracked: untrackedFiles(repoPath, scoped),
   };
 
   const cardId = deriveCardId(card);

package/runtime/scripts/amalgm-mcp/repocard/follow.js

@@ -95,12 +95,24 @@ function createFollower(options) {
     last = null,    // resume seed: { cardId, checkpointId }
     // May return a promise (e.g. a capture worker): the follower awaits it,
     // and any doorbell that lands mid-pair re-arms a retry (`pendingWake`).
-    captureFn = (repo) => capture(repo, { withBundle: false }),
+    // Called with { suspects }: the worktree paths rung since the last
+    // settled state, or null when everything is suspect.
+    captureFn = (repo, { suspects } = {}) => capture(repo, { withBundle: false, suspects }),
   } = options;
   if (!repoPath) throw new Error('createFollower requires { repoPath }');
   if (typeof emit !== 'function') throw new Error('createFollower requires { emit }');
 
   let known = last ? { cardId: last.cardId, checkpointId: last.checkpointId } : null;
+  // The warm-checkpoint scope: which worktree paths the doorbell has named
+  // since the last settled state. Each entry remembers the GENERATION of
+  // the ring that named it, so a path rung again mid-pair keeps its
+  // suspicion when the pair's success consumes the older hints. A nameless
+  // ring — or any entrance that may follow missed doorbells (birth, flush,
+  // a command ending) — makes EVERYTHING suspect until a pair settles.
+  const SCOPE_CAP = 512;
+  const scope = new Map(); // repo-relative path -> generation
+  let scopeGen = 0;
+  let scopeAllGen = 0; // >0: everything is suspect (set at birth, flush, command end, nameless ring)
   let owned = 0; // depth of amalgm-owned commands in flight
   let blocked = null; // lock name while the last capture attempt met a held lock
   let blockedPath = null;
@@ -210,12 +222,15 @@ function createFollower(options) {
 
     // The torn-read guard: two consecutive reads must agree before a state
     // may travel — a repo mid-mutation cannot produce the same ids twice.
+    // Both halves of the pair read the SAME scope: the paths rung so far.
+    const genNow = scopeGen;
+    const suspects = scopeAllGen > 0 ? null : [...scope.keys()];
     let first;
     let second;
     try {
-      first = await captureFn(repoPath);
+      first = await captureFn(repoPath, { suspects });
       if (closed || owned > 0) return; // the pair is stale before it finished
-      second = first && !first.busy ? await captureFn(repoPath) : null;
+      second = first && !first.busy ? await captureFn(repoPath, { suspects }) : null;
     } catch (error) {
       if (closed) return;
       // A read tripping over a mid-flight writer (a file vanishing between
@@ -234,11 +249,34 @@ function createFollower(options) {
       retry(settleMs);
       return;
     }
-    if (!speak(second)) retry(capMs); // consumer failure: patient, loud, never lost
+    if (!speak(second)) {
+      retry(capMs); // consumer failure: patient, loud, never lost
+      return;
+    }
+    // The settled pair proved the ground the scope described: hints from
+    // BEFORE the pair began are consumed; anything rung mid-pair keeps its
+    // newer generation and stays suspect for the pendingWake retry.
+    if (scopeAllGen > 0 && scopeAllGen <= genNow) scopeAllGen = 0;
+    for (const [rel, gen] of scope) {
+      if (gen <= genNow) scope.delete(rel);
+    }
   }
 
-  function ring() {
+  function ring(hint) {
     if (closed || owned > 0) return; // the command's end is the boundary
+    // Accumulate the warm-checkpoint scope. A .git-area hint never touches
+    // untracked ground, so it schedules a capture without widening the
+    // scope; a nameless hint (or an overflowing scope) suspects everything.
+    scopeGen += 1;
+    if (hint === null || hint === undefined) {
+      scopeAllGen = scopeGen;
+    } else if (hint !== '.git' && !hint.startsWith('.git/')) {
+      scope.set(hint, scopeGen);
+      if (scope.size > SCOPE_CAP) {
+        scope.clear();
+        scopeAllGen = scopeGen;
+      }
+    }
     if (settleTimer) clearTimeout(settleTimer);
     settleTimer = setTimeout(() => {
       settleTimer = null;
@@ -262,7 +300,13 @@ function createFollower(options) {
 
   function endCommand() {
     owned = Math.max(0, owned - 1);
-    if (owned === 0 && !closed) fire();
+    // Rings were suppressed while the command ran: its writes are nobody's
+    // hints, so the capture at the boundary suspects everything.
+    if (owned === 0 && !closed) {
+      scopeGen += 1;
+      scopeAllGen = scopeGen;
+      fire();
+    }
   }
 
   /** Run an amalgm-owned command: no captures while it runs, one at its end. */
@@ -284,10 +328,21 @@ function createFollower(options) {
 
   return {
     ring,
-    /** Birth: capture once, immediately. With a seeded `last`, an unchanged repo is silence. */
-    start: () => fire(),
-    /** Consumer-requested capture — the "scanNow" of this layer. */
-    flush: () => fire(),
+    /** Birth: capture once, immediately, suspecting everything — rings
+     * before birth were nobody's. With a seeded `last`, an unchanged
+     * repo is silence. */
+    start: () => {
+      scopeGen += 1;
+      scopeAllGen = scopeGen;
+      return fire();
+    },
+    /** Consumer-requested capture — the "scanNow" of this layer. Its whole
+     * purpose is catching a LOST doorbell, so it never trusts the scope. */
+    flush: () => {
+      scopeGen += 1;
+      scopeAllGen = scopeGen;
+      return fire();
+    },
     beginCommand,
     endCommand,
     command,

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

@@ -371,3 +371,93 @@ test('add follows in-order mirrored mutations and refuses after a version gap un
     fs.rmSync(targetDir, { recursive: true, force: true });
   }
 });
+
+// --- the repo travel law -----------------------------------------------------
+
+function activeCloud({ content = { has: () => true, ensureUpload: () => {} }, repoTransportFor = null } = {}) {
+  const db = new Database(':memory:');
+  let registry = null;
+  const cloud = createEntityCloud({
+    db,
+    userId: 'user-1',
+    deviceId: 'device-1',
+    content,
+    repoTransportFor,
+    recordAt: (uuid) => {
+      try { return registry.syncRecord(uuid); } catch { return null; }
+    },
+  });
+  registry = createRegistry({ db, ephemeral: true, emit: () => {}, journal: cloud.journal });
+  const root = registry.enrollRoot({ type: 'workspace', name: 'ground' });
+  const bootstrap = cloud.bootstrap(registry.syncRecords());
+  cloud.install({
+    registry,
+    resourceId: bootstrap.resourceId,
+    authorityEpoch: 1,
+    headVersion: 0,
+    snapshotBase64: bootstrap.snapshotBase64,
+    snapshotChecksum: bootstrap.snapshotChecksum,
+  });
+  return { db, cloud, registry, root, resourceId: bootstrap.resourceId };
+}
+
+test('a record enclosed by a repository never journals its own cloud mutation — the repo state parcel is the carrier', () => {
+  const transportHead = 'a'.repeat(64);
+  const { db, registry, root, resourceId } = activeCloud({
+    repoTransportFor: () => transportHead,
+  });
+
+  const repo = registry.create({ type: 'repo.git', parentUUID: root.uuid, name: 'engine', payloadVersion: 'state-1' });
+  assert.equal(db.prepare('SELECT COUNT(*) AS count FROM entity_cloud_mutations').get().count, 1,
+    'the repository record itself travels');
+
+  const folder = registry.create({ type: 'folder', parentUUID: repo.uuid, name: 'src' });
+  registry.create({ type: 'file.text', parentUUID: folder.uuid, name: 'index.js', payloadVersion: 'b'.repeat(64) });
+  registry.create({ type: 'link', parentUUID: repo.uuid, name: 'current', payloadVersion: 'src' });
+  assert.equal(db.prepare('SELECT COUNT(*) AS count FROM entity_cloud_mutations').get().count, 1,
+    'worktree children mail no postcards: a register or a rebase is one parcel on the repo entity');
+
+  const catalog = db.prepare('SELECT entity_uuid FROM entity_cloud_catalog WHERE resource_id = ? ORDER BY entity_uuid').all(resourceId)
+    .map((row) => row.entity_uuid).sort();
+  assert.deepEqual(catalog, [root.uuid, repo.uuid].sort(),
+    'the cloud catalog holds the traveling graph only — no rows for repo-enclosed children');
+
+  // A later Detect correction on the child (type/payload) stays local too.
+  const inner = registry.activeAt(folder.uuid, 'index.js');
+  registry.attest(inner.uuid, { type: 'file.binary', payloadVersion: 'c'.repeat(64) });
+  assert.equal(db.prepare('SELECT COUNT(*) AS count FROM entity_cloud_mutations').get().count, 1,
+    'the census drip is dead: child corrections never reach the outbox');
+});
+
+test('an atomic snapshot replacement excludes repo-enclosed records and never demands their bytes', () => {
+  const transportHead = 'd'.repeat(64);
+  const childHead = 'e'.repeat(64);
+  const { db, cloud, registry, root, resourceId } = activeCloud({
+    repoTransportFor: () => transportHead,
+    content: {
+      ensureUpload: () => {},
+      has: ({ contentHash }) => {
+        assert.notEqual(contentHash, childHead, 'an enclosed child head must never be demanded as separate cloud cargo');
+        return true;
+      },
+    },
+  });
+
+  registry.withoutJournal(() => {
+    const repo = registry.create({ type: 'repo.git', parentUUID: root.uuid, name: 'engine', payloadVersion: 'state-1' });
+    registry.create({ type: 'file.text', parentUUID: repo.uuid, name: 'inner.md', payloadVersion: childHead });
+    registry.create({ type: 'file.text', parentUUID: root.uuid, name: 'loose.md', payloadVersion: 'f'.repeat(64) });
+  });
+
+  cloud.replaceSnapshot(registry.syncRecords());
+  const operation = JSON.parse(db.prepare(`
+    SELECT operation_json FROM entity_cloud_mutations
+    WHERE resource_id = ? ORDER BY sequence DESC LIMIT 1
+  `).get(resourceId).operation_json);
+  assert.equal(operation.kind, 'entity.snapshot.replace');
+  const types = operation.snapshot.records.map((record) => record.type).sort();
+  assert.deepEqual(types, ['file.text', 'repo.git', 'workspace'],
+    'the atomic graph carries the workspace, the loose file, and ONE record per repository');
+  assert.ok(!operation.snapshot.records.some((record) => record.name === 'inner.md'),
+    'repo children stay out of the published graph');
+});