amalgm 0.1.263 → 0.1.264

package/package.json

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

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

@@ -15,8 +15,10 @@
  * (its own future head and rail), never an identity boundary. Every
  * top-level enrolled ground — a workspace, a repository, a single file,
  * or an explicitly added link — is such a tree, with one evidence LENS
- * over its observer root (nested repo territories live INSIDE their
- * tree as repo.git records; they are never trees of their own). A
+ * over its observer root. A Git territory noticed inside another watched
+ * tree is observer-only until an explicit registration admits it; that
+ * selected repo is then a tree of its own even if the outer watcher covers
+ * its local address. A
  * TREE'S IDENTITY IS ITS UUID, PERMANENT; its root path is only the
  * current local address — lenses are keyed by the observer's rootId
  * (the witness), the observer rescues moved ground by physical
@@ -66,6 +68,7 @@ const { refusal } = require('./refusal');
 const { createRepoFollowers } = require('./repo-followers');
 const { createRepoStates } = require('./repo-states');
 const { registerTree } = require('./tree');
+const { gitDirTruth } = require('../observer/scan');
 
 // Events that can change what the recorded edges reach: a new or
 // retargeted pointer, repo ground moving under its card (a worktree
@@ -112,12 +115,27 @@ function createRegistration(options) {
     onSettled: reconcileSettledRepo,
   });
 
-  /** Tree roots are the non-enclosed observer roots: a nested repo
-   * territory belongs to the tree that encloses it. */
+  /**
+   * A semantic tree is defined by its parentless identity record, never by
+   * directory containment.  `amalgm add` may materialize a cloud repo inside
+   * the local `workspaces/` directory, and `amalgm register` may select a
+   * repo already sitting there: both remain their own cloud root.  The outer
+   * workspace watcher supplies coverage, but it does not own the repo's
+   * Card + Checkpoint or identity tree.
+   *
+   * An unbound observer root is a tree candidate only when no other observer
+   * root physically encloses it.  That preserves the admission rule for a
+   * newly discovered nested repo: Watch can notice it, but only explicit
+   * registration can give it a cloud identity and state.
+   */
   function treeRoots() {
     const roots = observer.listRoots();
-    return roots.filter((root) => !roots.some((other) =>
-      other.rootId !== root.rootId && root.path.startsWith(`${other.path}/`)));
+    return roots.filter((root) => {
+      const record = rootRecordOf(root.rootId);
+      if (record) return record.parentUUID === null;
+      return !roots.some((other) => other.rootId !== root.rootId
+        && root.path.startsWith(`${other.path}/`));
+    });
   }
 
   function treeRootCovering(absPath) {
@@ -413,6 +431,75 @@ function createRegistration(options) {
     }
   }
 
+  /**
+   * A repository selected inside already-watched ground is still a new
+   * registered TREE, not a child record of the outer workspace.  The outer
+   * watcher already knows its territory (or this enrollment establishes that
+   * same territory), so the only missing fact is the repo's atomic
+   * Card+Checkpoint-backed identity birth.
+   */
+  function registerRepositoryInsideCoveredGround(ground, { identityAt = null, suppressJournal = false } = {}) {
+    let root = observer.listRoots().find((candidate) => candidate.path === ground) || null;
+    if (!root) root = observer.enrollRoot(ground, { scan: false, watch: false });
+    if (root.kind !== 'repo') {
+      throw new Error(`expected Git repository ground at ${ground}, found ${root.kind}`);
+    }
+
+    const bound = memory.boundTo(root.rootId);
+    if (bound !== undefined) {
+      const record = registry.record(bound);
+      if (record?.type !== 'repo.git') {
+        throw new Error(`repository watcher ${ground} is bound to non-repository entity ${bound}`);
+      }
+      if (record.parentUUID !== null) {
+        // This is the explicit nested-boundary case created as part of an
+        // already-registered enclosing repo.  It already has a complete
+        // Card+Checkpoint state and cannot be duplicated at one address.
+        requireLiveWatchers(ground);
+        return { rootPath: ground, record };
+      }
+      requireLiveWatchers(ground);
+      return { rootPath: ground, record };
+    }
+
+    try {
+      requireWatchBirth(root);
+      assertWitnessed({ observer, registry, memory });
+      const register = () => registry.transaction(() => {
+        registerTree({
+          root,
+          registry,
+          memory,
+          shouldEnroll: observer.shouldEnroll,
+          captureRepo,
+          repoStates,
+          repoStateAt,
+          identityAt,
+        });
+        assertWatchedThroughCommit(root.path);
+      });
+      if (suppressJournal) registry.withoutJournal(register);
+      else register();
+    } catch (error) {
+      // A root that existed only because the outer watcher discovered its
+      // territory must remain coverage after a refused explicit admission;
+      // do not remove it (the parent still owns the OS watcher).  A root this
+      // call itself enrolled has no durable identity and can safely retire.
+      throw error;
+    }
+
+    const startWatch = () => {
+      observer.start(root.rootId);
+      ensureTrees();
+      reconcileInitialRepoWorktrees(root.path);
+      flushIfDirty();
+      requireLiveWatchers(root.path);
+    };
+    if (suppressJournal) registry.withoutJournal(startWatch);
+    else startWatch();
+    return { rootPath: root.path, record: rootRecordOf(root.rootId) };
+  }
+
   /** Real ground -> the UUID of the entity that owns it, across trees. */
   function resolveGround(real) {
     const home = treeRootCovering(real);
@@ -542,6 +629,23 @@ function createRegistration(options) {
     }
     const covering = treeRootCovering(ground);
     if (covering) {
+      // A repository has a different state adapter from the workspace that
+      // happens to contain its local address.  Its observer territory may
+      // already exist, but it is not registered until this explicit command
+      // creates the parentless repo tree with its initial Card + Checkpoint.
+      // The same branch is used by cloud `add`: materialized repos commonly
+      // land under the default `workspaces/` directory while retaining their
+      // cloud root UUID and parentless graph position.
+      const isRepository = fs.lstatSync(ground).isDirectory() && gitDirTruth(ground) === 'present';
+      if (isRepository) {
+        const exact = observer.listRoots().find((root) => root.path === ground);
+        const known = exact && memory.boundTo(exact.rootId) !== undefined
+          ? registry.record(memory.boundTo(exact.rootId))
+          : null;
+        if (!known || known.type !== 'repo.git' || known.parentUUID === null) {
+          return registerRepositoryInsideCoveredGround(ground, { identityAt, suppressJournal });
+        }
+      }
       // This address is already registered ground. Its prior Register →
       // Watch transition remains the proof of its identity; repeating a
       // harmless "ensure the safe home exists" request must not rescan every

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

@@ -80,7 +80,8 @@
  *     the folder record and every descendant's derived address follows,
  *     which is why folders reconcile before files, parents before
  *     children;
- *   - repo territories as repo.git type transitions on the slot's record;
+ *   - repo territories as observer truth, with an explicitly registered
+ *     repository boundary supplying the corresponding repo.git record;
  *   - ADOPTION, the channel law completing across trees: unclaimed
  *     ground wearing the physical identity of an orphaned top-level tree
  *     is that tree's arrival — one lawful parent update on its
@@ -604,23 +605,24 @@ function createEvidence(options) {
       };
       settleClaims(claimsOf(desiredDirs, 'dir'), 'dir');
 
-      // Territories after folder continuity, before file ground: a
-      // boundary is a repo.git type transition on the slot's record, and
-      // the slot must already be where its folder channel says it is.
+      // Territories after folder continuity, before file ground.  A Git
+      // boundary is NOT ordinary filesystem evidence: every repo.git record
+      // needs a Card + Checkpoint state and immutable transport before it can
+      // travel.  This generic lens has neither, so it may only recognize a
+      // boundary that the registration adapter already made whole.  An
+      // unregistered repository remains a local observer territory until
+      // `amalgm register <repo>` admits it through that adapter.
+      //
+      // This is deliberately not a convenience gate.  Letting this layer
+      // mint or promote repo.git would create an identity record whose cloud
+      // head names no state — the exact invalid half-repository the cloud
+      // contract rejects.  Folders and files are evidence-shaped; Git is a
+      // type-specific state carrier.
       for (const territory of [...territories].sort()) {
         const parentUuid = ensureDir(path.dirname(territory) === '.' ? '' : path.dirname(territory), root);
         const name = path.basename(territory);
         const at = registry.activeAt(parentUuid, name);
-        if (!at) {
-          // Adoption before birth here too: a registered top-level repo
-          // TREE that moved in arrives as its own record, never a fresh
-          // territory record. The enclosed observer root's identity is
-          // the evidence — the same physical dir the orphaned tree owns.
-          const enclosed = observer.listRoots().find((row) => row.path === path.join(groundPath, territory));
-          const arrivedRecord = enclosed ? arrivedTree(enclosed.device, enclosed.inode, REPO_TREE) : null;
-          if (arrivedRecord) registry.move(arrivedRecord.uuid, { parentUUID: parentUuid, name });
-          else registry.create({ type: 'repo.git', parentUUID: parentUuid, name });
-        } else if (at.type !== 'repo.git') registry.changeType(at.uuid, 'repo.git');
+        if (at?.type !== 'repo.git') continue;
       }
       // A lifted lens is the reverse transition on the same record.
       for (const { record, rel } of walkActive(root.uuid, '', [])) {

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

@@ -369,6 +369,11 @@ test('add recreates an actual Git repository from verified Repocard cargo, then
       snapshotChecksum: sha256(snapshotBytes),
     });
 
+    // This is the real user destination: a repo lands below an already-live
+    // local workspaces-like container.  Physical containment supplies watcher
+    // coverage only; the cloud repo must retain its parentless root identity.
+    target.registration.add(targetParent, { suppressJournal: true });
+
     const planned = source.entityCloud.contentHeads(records);
     assert.deepEqual(
       planned.map(({ contentHash }) => contentHash),
@@ -406,6 +411,8 @@ test('add recreates an actual Git repository from verified Repocard cargo, then
     const expected = source.registration.repoState(registered.record.uuid);
     assert.equal(verify(destination, expected).ok, true, 'the downloaded Git state reproduces its Card + Checkpoint IDs');
     assert.equal(target.registration.registry.syncRecord(registered.record.uuid).uuid, registered.record.uuid);
+    assert.equal(target.registration.registry.syncRecord(registered.record.uuid).parentUUID, null,
+      'a repo materialized beneath an existing local workspace keeps its cloud root position');
     assert.equal(target.observer.status().find((entry) => entry.path === fs.realpathSync(destination))?.watching, true,
       'the same successful add starts the destination repository watcher');
 

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

@@ -724,6 +724,45 @@ test('a nested repository has its own baseline and watcher, while its tree remai
   assert.equal(tree.registry.activeAt(src.uuid, 'live.js').type, 'file.text');
 });
 
+test('a repo discovered inside watched workspace ground stays unregistered until explicit register gives it one complete repo root', async () => {
+  const service = makeService('workspace-repo-admission');
+  const workspace = makeGround('workspace-repo-admission');
+  const { record: workspaceRecord } = await service.register(workspace);
+  const repo = path.join(workspace, 't3code');
+  fs.mkdirSync(repo);
+  execFileSync('git', ['init', '-q'], { cwd: repo });
+  fs.writeFileSync(path.join(repo, 'readme.md'), '# T3\n');
+
+  // This is the production ordering that convicted the live Fly run: the
+  // outer workspace watcher discovers a newly cloned repository first.
+  const workspaceRoot = service.observer.listRoots().find((root) => root.path === workspace);
+  service.observer.scanNow(workspaceRoot.rootId);
+  await new Promise((resolve) => setImmediate(resolve));
+  service.registration.flushIfDirty();
+
+  const territory = service.observer.listRoots().find((root) => root.path === repo);
+  assert.equal(territory?.kind, 'repo', 'Watch knows the local Git territory');
+  assert.notEqual(
+    service.registration.tree(workspace).registry.activeAt(workspaceRecord.uuid, 't3code')?.type,
+    'repo.git',
+    'generic filesystem evidence never mints a half-repository with no Card + Checkpoint',
+  );
+
+  const { record } = await service.register(repo);
+  assert.equal(record.type, 'repo.git');
+  assert.equal(record.parentUUID, null,
+    'selected repo is its own cloud tree even though its local address is inside workspaces');
+  assert.equal(service.registration.tree(repo).root().uuid, record.uuid,
+    'the nested observer root now witnesses that selected tree');
+  assert.ok(service.registration.repoState(record.uuid)?.stateId,
+    'its identity and initial Card + Checkpoint were committed together');
+  assert.equal(
+    service.observer.status().some((row) => row.path === repo && row.watching && !row.degraded),
+    true,
+    'the selected repo is live after the atomic registration',
+  );
+});
+
 test('a reopened repo watcher resumes from the saved Card + Checkpoint baseline', async () => {
   const service = makeService('repo-reopen');
   const repo = makeGround('repo-reopen');