amalgm 0.1.265 → 0.1.266

package/package.json

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

package/runtime/scripts/amalgm-mcp/observer/README.md

@@ -94,7 +94,10 @@ never merges, never decides truth — it emits facts for the layers above.
    (catch-up for the window we were dead), watcher death (rebuild the
    doorbell, reconcile the gap once), and whenever a consumer asks — a sync
    session opening, a document opening, an app regaining focus are events
-   too, and they belong to the layer above.
+   too, and they belong to the layer above. A freshly registered repo is the
+   one adapter-defined birth exception: its Card + Checkpoint is already the
+   complete first observation, so it arms Watch without scanning every child
+   again. Restart still performs the ordinary conservative catch-up scan.
 4. **Echo suppression is content, not bookkeeping.** A writer records its own
    write (`noteWrite`); a scan that finds the recorded hash finds nothing.
 5. **Identity has two axes, never mixed — and KIND decides which axis

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

@@ -1229,6 +1229,22 @@ function createObserver(options) {
       }
       scanFilesRoot(root, { allowRootRepository: true });
     },
+    /**
+     * Structural registration already knows its nested Git boundaries from
+     * the same state parcel that names them.  Refresh only that in-memory
+     * forwarding map after it installs those observer roots; this is not a
+     * filesystem census and it neither reads nor records worktree files.
+     */
+    refreshRepoTerritories(rootId) {
+      const root = store.listRoots().find((row) => row.rootId === rootId);
+      if (!root || root.kind !== 'repo') {
+        throw new Error(`refreshRepoTerritories requires a live repo root: ${rootId}`);
+      }
+      const state = live.get(root.rootId);
+      if (!state) return;
+      state.territories = new Set(childRepoRoots(root)
+        .map((child) => child.path.slice(root.path.length + 1)));
+    },
     scanNow,
 
     // The referee (verify.js): re-hash every enrolled byte, report every
@@ -1313,7 +1329,7 @@ function createObserver(options) {
       return statusOf(root);
     },
 
-    start(rootId = null) {
+    start(rootId = null, { census = true } = {}) {
       const firstStart = !started;
       if (firstStart) started = true;
       if (!firstStart && rootId === null) return;
@@ -1328,10 +1344,19 @@ function createObserver(options) {
         const state = attach(root, { watch: true });
         state.held = false;
       }
-      try {
-        for (const root of roots) scanNow(root.rootId);
-      } catch (error) {
-        console.warn('[Observer] initial scan failed:', error?.message || error);
+      // A normal root needs its first observed census before its structural
+      // registration can become evidence. A freshly registered Git root is
+      // different: its already-committed Card + Checkpoint is that complete
+      // initial observation. Re-walking its worktree here would duplicate
+      // the adapter's state (and can block the runtime for a large repo).
+      // `census: false` is therefore only the repo adapter's birth path;
+      // later recoveries and runtime start retain the conservative census.
+      if (census) {
+        try {
+          for (const root of roots) scanNow(root.rootId);
+        } catch (error) {
+          console.warn('[Observer] initial scan failed:', error?.message || error);
+        }
       }
     },
 

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

@@ -172,13 +172,14 @@ function createRegistration(options) {
     for (const { scopeId } of memory.allBindings()) {
       if (!liveIds.has(scopeId)) memory.dropScope(scopeId);
     }
-    for (const [rootId] of [...lenses]) {
-      const row = observer.listRoots().find((member) => member.rootId === rootId);
-      if (!row) {
-        lenses.delete(rootId);
-        continue;
-      }
-      const record = rootRecordOf(rootId);
+    // Retirement is decided from durable witness bindings, not from the
+    // in-memory lens map. A fresh runtime has no lenses yet, but it may have
+    // restarted halfway through retiring an adopted tree; letting that old
+    // observer root survive would make its next start look like a second
+    // tree. The binding is the evidence that survives the crash, so it is
+    // the only honest starting point.
+    for (const row of observer.listRoots()) {
+      const record = rootRecordOf(row.rootId);
       const nestedRepoScope = row.kind === 'repo' && record?.type === 'repo.git'
         && observer.listRoots().some((other) => other.rootId !== row.rootId
           && row.path.startsWith(`${other.path}/`));
@@ -190,15 +191,18 @@ function createRegistration(options) {
         // sweep above collects. The reverse order once minted a duplicate
         // tree: an unbound living root looks like fresh ground.
         const family = observer.listRoots()
-          .filter((member) => member.rootId === rootId || member.path.startsWith(`${row.path}/`));
+          .filter((member) => member.rootId === row.rootId || member.path.startsWith(`${row.path}/`));
         for (const member of family) {
-          if (member.rootId !== rootId) observer.removeRoot(member.rootId);
+          if (member.rootId !== row.rootId) observer.removeRoot(member.rootId);
         }
-        observer.removeRoot(rootId);
-        memory.dropScope(rootId);
-        lenses.delete(rootId);
+        observer.removeRoot(row.rootId);
+        memory.dropScope(row.rootId);
+        lenses.delete(row.rootId);
       }
     }
+    for (const [rootId] of [...lenses]) {
+      if (!observer.listRoots().some((row) => row.rootId === rootId)) lenses.delete(rootId);
+    }
     for (const root of treeRoots()) {
       if (lenses.has(root.rootId)) continue;
       const lens = createEvidence({ observer, registry, memory, rootId: root.rootId, classify });
@@ -508,18 +512,67 @@ function createRegistration(options) {
       throw error;
     }
 
-    const startWatch = () => {
-      observer.start(root.rootId);
-      ensureTrees();
-      reconcileInitialRepoWorktrees(root.path);
-      flushIfDirty();
-      requireLiveWatchers(root.path);
-    };
+    const startWatch = () => startRepositoryFromBaseline(root);
     if (suppressJournal) registry.withoutJournal(startWatch);
     else startWatch();
     return { rootPath: root.path, record: rootRecordOf(root.rootId) };
   }
 
+  /**
+   * A repo's initial Card + Checkpoint is not preliminary data awaiting a
+   * generic filesystem census: it *is* the first complete state. Start its
+   * follower while the watcher is held, then release the watcher without
+   * scanning every worktree child a second time. The next raw ding reaches
+   * the follower and exactly one settled state authorizes the ordinary child
+   * reconciliation. This keeps Register synchronous without duplicating
+   * either its cargo capture or its initial Detect pass.
+   */
+  function startRepositoryFromBaseline(root) {
+    // Structural registration already knows every nested repo boundary from
+    // the same assignment that packed its state. Install those territories
+    // directly from that identity graph; discovering them again by walking
+    // files would reintroduce the duplicate initial census this adapter
+    // exists to avoid.
+    const territories = [];
+    for (const record of registry.activeByType('repo.git')) {
+      const repoPath = addressOf(record.uuid);
+      if (repoPath === null || (repoPath !== root.path && !repoPath.startsWith(`${root.path}/`))) continue;
+      let territory = observer.listRoots().find((candidate) => candidate.path === repoPath) ?? null;
+      if (!territory) territory = observer.enrollRoot(repoPath, { scan: false, watch: false });
+      if (territory.kind !== 'repo') {
+        throw new Error(`registered repository ${repoPath} is no longer Git ground before Watch began`);
+      }
+      memory.bind(territory.rootId, territory.rootId, record.uuid);
+      if (!lenses.has(territory.rootId)) {
+        // A repo baseline is already authoritative state. The lens exists so
+        // callers can address the tree, but does not reconcile absent
+        // observer child rows as if that state had never been captured.
+        lenses.set(territory.rootId, createEvidence({
+          observer, registry, memory, rootId: territory.rootId, classify,
+        }));
+      }
+      territories.push(territory);
+    }
+    territories.sort((left, right) => left.path.length - right.path.length);
+    // The outer raw watcher must forward a nested repo's first later ding
+    // to that nested follower. Its territory set is normally filled by a
+    // census; structural registration already supplied the same boundaries,
+    // so refresh the forwarding map without performing that census.
+    for (const territory of territories) observer.refreshRepoTerritories(territory.rootId);
+    repoFollowers.sync({ startOnBirth: false });
+    for (const territory of territories) observer.start(territory.rootId, { census: false });
+    requireLiveWatchers(root.path);
+
+    // Edge discovery is a distinct registration promise. It only reads link
+    // surfaces (repo roots answer that with a link census), never converts
+    // the just-packed worktree into generic per-file evidence. The newly
+    // reached roots then receive their usual identity/lens setup.
+    edgesDirty = true;
+    tryFollow();
+    ensureTrees();
+    repoFollowers.sync({ startOnBirth: false });
+  }
+
   /**
    * Plan all repository cargo under one selected root before its identity
    * transaction begins.  This work can be slow (a Card contains a Git bundle
@@ -876,6 +929,7 @@ function createRegistration(options) {
     // mutation. Keep the whole first Watch/Detect transition inside the
     // existing journal boundary used for the seeded structural bind.
     const startWatch = () => {
+      if (root.kind === 'repo') return startRepositoryFromBaseline(root);
       observer.start(root.rootId);
       ensureTrees();
       reconcileInitialRepoWorktrees(root.path);

package/runtime/scripts/amalgm-mcp/registration/repo-followers.js

@@ -76,7 +76,16 @@ function createRepoFollowers({
    * move, be adopted, or cease being a repository; in every case the old
    * follower is closed before a replacement can speak.
    */
-  function sync() {
+  /**
+   * A freshly registered repo already has a Card + Checkpoint baseline and
+   * its watcher is still held.  Its follower must exist before that hold is
+   * released, but it must not immediately spend a second pair of full Git
+   * captures just to rediscover the state it was born with.  Any ding heard
+   * during the release rings this follower normally.  A cold runtime restart
+   * keeps the default (`startOnBirth: true`) and independently proves the
+   * persisted baseline against disk.
+   */
+  function sync({ startOnBirth = true } = {}) {
     if (stopped) return;
     const roots = observer.listRoots().filter((root) => root.kind === 'repo');
     const live = new Set(roots.map((root) => root.rootId));
@@ -143,9 +152,10 @@ function createRepoFollowers({
         },
       });
       followers.set(root.rootId, { path: root.path, uuid: record.uuid, follower });
-      // Birth captures the initial Card + Checkpoint. The follower owns its
-      // retry policy; registration must not invent an alternate Git scanner.
-      void follower.start();
+      // A restart catches up from disk; a fresh Register has already
+      // captured its exact baseline and will receive held doorbells when
+      // Watch releases, so it does not duplicate the expensive birth pair.
+      if (startOnBirth) void follower.start();
     }
   }
 

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

@@ -23,7 +23,10 @@
  * although they have identical behavior today. A structural walk therefore
  * uses file.text as the content-free ordinary-file placeholder. The first
  * Detect pass immediately attests the actual bytes and corrects that
- * representation through the normal one-observation transition.
+ * representation through the first later settled repo reconciliation. The
+ * initial Card + Checkpoint is authoritative content state; repeating a
+ * generic per-file scan merely to refine this local physical label would
+ * duplicate that state and can freeze large registration.
  */
 
 const fs = require('fs');

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

@@ -622,7 +622,20 @@ function createEvidence(options) {
         const parentUuid = ensureDir(path.dirname(territory) === '.' ? '' : path.dirname(territory), root);
         const name = path.basename(territory);
         const at = registry.activeAt(parentUuid, name);
-        if (at?.type !== 'repo.git') continue;
+        if (at?.type === 'repo.git') continue;
+        const territoryRoot = observer.listRoots()
+          .find((row) => row.kind === 'repo' && row.path === path.join(groundPath, territory));
+        const arrivedRecord = arrivedTree(territoryRoot?.device, territoryRoot?.inode, REPO_TREE);
+        if (!arrivedRecord) continue;
+        // A Git territory is the repo-shaped form of the same adoption law
+        // directories use above. Its initial Card + Checkpoint already
+        // travels with the existing repo UUID, so the new observer root must
+        // adopt that identity — never mint or ignore a half-repository.
+        if (at) {
+          nowDivergent.set(territory, null); // two identity claims: decide neither
+          continue;
+        }
+        registry.move(arrivedRecord.uuid, { parentUUID: parentUuid, name });
       }
       // A lifted lens is the reverse transition on the same record.
       for (const { record, rel } of walkActive(root.uuid, '', [])) {

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

@@ -750,6 +750,13 @@ function createRegistry(options) {
     /** Full logical graph for cloud snapshots. Machine bindings and evidence
      * are intentionally absent. */
     syncRecords: () => store.allEntities().map(syncRecord),
+    /** Active records of one physical type. This is a query primitive for
+     * type adapters; it does not expose storage writes or weaken the single
+     * registry boundary. */
+    activeByType: (type) => {
+      if (!TYPES.has(type)) throw new Error(`unknown entity type ${JSON.stringify(type)}`);
+      return store.activeByType(type).map(record);
+    },
     /** Every registered tree's top record. */
     roots: () => store.activeRoots().map(record),
     /** Every active managed reference with the identity it targets. The

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

@@ -608,13 +608,17 @@ test('adding a repository registers its allowed tree and saves its initial Repoc
   assert.ok(initialState?.stateId, 'registration saved the initial Card + Checkpoint');
   assert.ok(initialState.checkpoint.untracked.some((file) => file.path === 'readme.md'),
     'the persisted baseline contains the actual working checkpoint, not only its hash');
+  const observerRoot = service.observer.listRoots().find((root) => root.path === repo);
+  assert.deepEqual(service.observer.filesForRoot(observerRoot.rootId), [],
+    'repo birth does not perform a second per-file census after its Card + Checkpoint is saved');
   assert.equal(tree.root().version, registered.version,
     'add returned only after the repo entity pointed at its saved baseline');
   const readme = tree.registry.activeAt(registered.uuid, 'readme.md');
   const src = tree.registry.activeAt(registered.uuid, 'src');
   assert.equal(readme.type, 'file.text');
   assert.equal(src.type, 'folder');
-  assert.equal(tree.registry.activeAt(src.uuid, 'blob.bin').type, 'file.binary');
+  assert.equal(tree.registry.activeAt(src.uuid, 'blob.bin').type, 'file.text',
+    'repo birth records structural leaf shape; the Card + Checkpoint owns its actual bytes without a second read');
   assert.equal(tree.registry.activeAt(registered.uuid, 'node_modules'), null,
     'the same enrollment policy excludes dependency trees inside repos');
   const initial = tree.root();