amalgm 0.1.245 → 0.1.246

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

@@ -0,0 +1,931 @@
+'use strict';
+
+/**
+ * The shared registration boundary (`amalgm add`) proving the composed
+ * story the audits demanded: every enrolled root exposes symlink edges
+ * regardless of its mutation adapter; watched ground is ALWAYS
+ * registered ground (a followed target gets a tree, a root record, a
+ * witness); a tree's identity is its permanent UUID and its path only
+ * the current address (moved ground is rescued, never re-minted); a
+ * link's derived resolution is the OS's own answer — realpath, chains
+ * and all — landing on the OWNING entity across every tree; exactly the
+ * named target enrolls (never an enclosing boundary the user did not
+ * name); and amalgm's enrollment policy gates every route, edges and
+ * explicit adds alike.
+ */
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const { execFileSync } = require('child_process');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const Database = require('better-sqlite3');
+const { createObserver } = require('../observer');
+const { createRegistration } = require('../registration');
+const { createEvidenceMemory } = require('../registry/evidence');
+const { shouldEnroll: defaultPolicy } = require('../workspace/tree/inclusion');
+const { installFakeWatch } = require('./fake-watch');
+
+const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'amalgm-registration-'));
+
+test.after(() => {
+  fs.rmSync(tempRoot, { recursive: true, force: true });
+});
+
+function makeDir(name) {
+  const dir = fs.mkdtempSync(path.join(tempRoot, `${name}-`));
+  return fs.realpathSync(dir);
+}
+
+function gitInit(dir) {
+  execFileSync('git', ['init', '-q'], { cwd: dir });
+}
+
+/**
+ * One observer + one registration over the ONE in-memory identity
+ * database, events captured and routed. `restart()` builds a fresh
+ * boundary over the same observer and the same database — the
+ * re-attachment path.
+ */
+function makeRig(options = {}) {
+  const events = [];
+  const ref = { current: null };
+  const observer = createObserver({
+    db: new Database(':memory:'),
+    emit: (event) => {
+      events.push(event);
+      ref.current?.onEvent(event);
+    },
+    shouldEnroll: options.shouldEnroll ?? (() => true),
+  });
+  // ONE identity database holds every tree; witness bindings key each
+  // tree by its permanent rootId, so a restart finds a moved tree by
+  // identity, never its address.
+  const identityDb = new Database(':memory:');
+  const boot = () => createRegistration({
+    observer, openIdentity: () => ({ db: identityDb, ephemeral: true }),
+    classify: () => 'file.text',
+    emit: (event) => events.push(event),
+  });
+  ref.current = boot();
+  return {
+    observer,
+    events,
+    identityDb,
+    get registration() { return ref.current; },
+    /** The crash window: events fire into a dead boundary. */
+    detach: () => { ref.current = null; },
+    restart: () => {
+      ref.current = boot();
+      return ref.current;
+    },
+  };
+}
+
+const committedSince = (events, from) => events.slice(from)
+  .filter((event) => event.type === 'entity.committed');
+
+// --- the link record, proven against the composed system ------------------
+
+test('a link record: the payload is the pointer as written; what it reaches is derived, and its death is honest', () => {
+  const rig = makeRig();
+  const dir = makeDir('link-rec');
+  fs.mkdirSync(path.join(dir, 'v2'));
+  fs.writeFileSync(path.join(dir, 'v2', 'app.js'), 'app');
+  fs.symlinkSync('v2', path.join(dir, 'current'));
+
+  const { rootPath, record: root } = rig.registration.add(dir);
+  assert.equal(rootPath, dir);
+  const tree = rig.registration.tree(dir);
+  const rootId = rig.observer.listRoots().find((row) => row.path === dir).rootId;
+  const link = tree.registry.activeAt(root.uuid, 'current');
+  const folderUuid = tree.registry.activeAt(root.uuid, 'v2').uuid;
+  assert.equal(link.type, 'link');
+  assert.equal(rig.registration.linkTargets().get(link.uuid), folderUuid,
+    'derived: the written address currently reaches the real folder\'s record');
+
+  // The target folder moves; the pointer text did not. The OS calls the
+  // link broken — the record stays silent (its payload is the text), only
+  // the derived resolution dies, and amalgm never repairs the pointer by
+  // remembering what it used to reach.
+  fs.renameSync(path.join(dir, 'v2'), path.join(dir, 'v3'));
+  rig.observer.scanNow(rootId);
+  rig.registration.flushIfDirty();
+  assert.equal(tree.registry.activeAt(root.uuid, 'v3').uuid, folderUuid, 'the folder moved as itself');
+  assert.equal(tree.registry.activeAt(root.uuid, 'current').version, link.version,
+    'the pointer text did not change, so the link record is silent');
+  assert.equal(rig.registration.linkTargets().get(link.uuid), null,
+    'the derived resolution died honestly: amalgm remembers the text, not the target');
+
+  // A retarget IS the link's own change: the version moves with the text.
+  fs.unlinkSync(path.join(dir, 'current'));
+  fs.symlinkSync('v3', path.join(dir, 'current'));
+  rig.observer.scanNow(rootId);
+  rig.registration.flushIfDirty();
+  const retargeted = tree.registry.activeAt(root.uuid, 'current');
+  assert.equal(retargeted.uuid, link.uuid, 'same entity');
+  assert.notEqual(retargeted.version, link.version, 'a new written address is a new version');
+  assert.equal(rig.registration.linkTargets().get(link.uuid), folderUuid,
+    'and the derived resolution lives again');
+
+  // A boundary restart re-attaches every tree; unchanged truth is silence.
+  const before = rig.events.length;
+  const reopened = rig.restart();
+  assert.deepEqual(committedSince(rig.events, before), [],
+    'startup over unchanged truth is silence — link bindings included');
+  assert.equal(reopened.tree(dir).registry.activeAt(root.uuid, 'current').uuid, link.uuid);
+});
+
+// --- the four permanent composition exams ---------------------------------
+
+test('a Git-contained link enrolls AND registers its external target', () => {
+  const rig = makeRig();
+  const outside = makeDir('git-edge-target');
+  fs.writeFileSync(path.join(outside, 'shared.md'), 'shared');
+  const repo = makeDir('git-edge');
+  gitInit(repo);
+  fs.symlinkSync(outside, path.join(repo, 'shared'));
+
+  const { record } = rig.registration.add(repo);
+  assert.equal(record.type, 'repo.git', 'the repo is one entity: its tree is the card\'s record');
+
+  const targetTree = rig.registration.tree(outside);
+  assert.ok(targetTree, 'the edge inside repo territory registered its target — a tree, not just a watcher');
+  const targetRoot = targetTree.root();
+  assert.equal(targetRoot.type, 'workspace');
+  assert.ok(targetTree.registry.activeAt(targetRoot.uuid, 'shared.md'),
+    'the target\'s ground has records down to its files');
+});
+
+test('watched means registered: a followed target gets a tree, a witness, and resolution reaches its UUID', () => {
+  const rig = makeRig();
+  const outside = makeDir('reg-target');
+  fs.writeFileSync(path.join(outside, 'lib.js'), 'x');
+  const ws = makeDir('reg-ws');
+  fs.symlinkSync(outside, path.join(ws, 'dep'));
+
+  const { record: wsRoot } = rig.registration.add(ws);
+  const wsTree = rig.registration.tree(ws);
+  const link = wsTree.registry.activeAt(wsRoot.uuid, 'dep');
+  const targetTree = rig.registration.tree(outside);
+  assert.ok(targetTree, 'following an edge registers the target, never merely watches it');
+  assert.equal(rig.registration.linkTargets().get(link.uuid), targetTree.root().uuid,
+    'the pointer resolves across trees to the target\'s own root UUID');
+});
+
+test('an external file target registers as a single-file tree, attested under the file laws', () => {
+  const rig = makeRig();
+  const holder = makeDir('solo-holder');
+  const filePath = path.join(holder, 'notes.md');
+  fs.writeFileSync(filePath, 'v1');
+  const ws = makeDir('solo-ws');
+  fs.symlinkSync(filePath, path.join(ws, 'notes'));
+
+  const { record: wsRoot } = rig.registration.add(ws);
+  const fileTree = rig.registration.tree(filePath);
+  assert.ok(fileTree, 'a file names itself: its tree is a tree of one');
+  const fileRoot = fileTree.root();
+  assert.equal(fileRoot.type, 'file.text');
+  assert.equal(fileRoot.name, 'notes.md');
+  const link = rig.registration.tree(ws).registry.activeAt(wsRoot.uuid, 'notes');
+  assert.equal(rig.registration.linkTargets().get(link.uuid), fileRoot.uuid,
+    'resolution reaches the file entity itself');
+  assert.ok(!rig.observer.listRoots().some((root) => root.path === holder),
+    'the parent was never enrolled: siblings the edge never named stay unshared');
+
+  // Content moves; the root record attests it like any file.
+  fs.writeFileSync(filePath, 'v2 — longer now');
+  const fileRootId = rig.observer.listRoots().find((row) => row.path === filePath).rootId;
+  rig.observer.scanNow(fileRootId);
+  rig.registration.flushIfDirty();
+  assert.notEqual(fileTree.root().version, fileRoot.version,
+    'the single-file tree\'s version moved with its bytes');
+});
+
+test('a retarget automatically enrolls and registers the new ground; the old tree stays', () => {
+  const rig = makeRig();
+  const first = makeDir('auto-old');
+  const second = makeDir('auto-new');
+  fs.writeFileSync(path.join(second, 'fresh.md'), 'f');
+  const ws = makeDir('auto-ws');
+  fs.symlinkSync(first, path.join(ws, 'ptr'));
+
+  const { record: wsRoot } = rig.registration.add(ws);
+  assert.ok(rig.registration.tree(first), 'the first target registered at add time');
+
+  fs.unlinkSync(path.join(ws, 'ptr'));
+  fs.symlinkSync(second, path.join(ws, 'ptr'));
+  const wsRootId = rig.observer.listRoots().find((row) => row.path === ws).rootId;
+  rig.observer.scanNow(wsRootId); // link.changed marks the edges dirty through onEvent
+  rig.registration.flushIfDirty();
+
+  const secondTree = rig.registration.tree(second);
+  assert.ok(secondTree, 'the retarget registered the new ground without anyone asking');
+  const link = rig.registration.tree(ws).registry.activeAt(wsRoot.uuid, 'ptr');
+  assert.equal(rig.registration.linkTargets().get(link.uuid), secondTree.root().uuid);
+  assert.ok(rig.registration.tree(first),
+    'the old tree stays — removing coverage is an explicit act, never a side effect');
+});
+
+// --- resolution is the OS's answer ----------------------------------------
+
+test('chains resolve like the OS resolves: to the final real ground, in-tree and across trees', () => {
+  const rig = makeRig();
+  const dir = makeDir('chain');
+  fs.writeFileSync(path.join(dir, 'real.md'), 'r');
+  fs.symlinkSync('real.md', path.join(dir, 'hop'));
+  fs.symlinkSync('hop', path.join(dir, 'chain'));
+
+  const jumpHolder = makeDir('chain-mid');
+  const far = makeDir('chain-far');
+  fs.symlinkSync(far, path.join(jumpHolder, 'jump'));
+  fs.symlinkSync(path.join(jumpHolder, 'jump'), path.join(dir, 'out'));
+
+  const { record: root } = rig.registration.add(dir);
+  const tree = rig.registration.tree(dir);
+  const targets = rig.registration.linkTargets();
+  const fileUuid = tree.registry.activeAt(root.uuid, 'real.md').uuid;
+  assert.equal(targets.get(tree.registry.activeAt(root.uuid, 'chain').uuid), fileUuid,
+    'chain → hop → real.md lands on the file, exactly where the OS lands');
+  assert.equal(targets.get(tree.registry.activeAt(root.uuid, 'hop').uuid), fileUuid);
+  assert.equal(targets.get(tree.registry.activeAt(root.uuid, 'out').uuid),
+    rig.registration.tree(far).root().uuid,
+    'a cross-tree chain registers and resolves the FINAL ground');
+  assert.ok(!rig.registration.tree(jumpHolder),
+    'intermediate ground was traversed, never registered: no edge named it as an endpoint');
+});
+
+test('repo-contained targets resolve to the owning entity: the card\'s record answers for its insides', () => {
+  const rig = makeRig();
+  const repo = makeDir('territory');
+  gitInit(repo);
+  fs.mkdirSync(path.join(repo, 'docs'));
+  fs.writeFileSync(path.join(repo, 'docs', 'a.md'), 'a');
+  const { record: repoRoot } = rig.registration.add(repo);
+  const ws = makeDir('territory-ws');
+  fs.symlinkSync(path.join(repo, 'docs'), path.join(ws, 'docs'));
+
+  const { record: wsRoot } = rig.registration.add(ws);
+  assert.equal(repoRoot.type, 'repo.git');
+  const link = rig.registration.tree(ws).registry.activeAt(wsRoot.uuid, 'docs');
+  assert.equal(rig.registration.linkTargets().get(link.uuid), repoRoot.uuid,
+    'the repo is the owning sync entity, so its UUID answers for every address inside it — never a null that pretends no owner exists');
+
+  // A nested territory answers the same way: the repo.git record on the
+  // way down the tree owns everything beneath it.
+  const rig2 = makeRig();
+  const ws2 = makeDir('territory-outer');
+  const nested = path.join(ws2, 'vendor');
+  fs.mkdirSync(path.join(nested, 'lib'), { recursive: true });
+  gitInit(nested);
+  fs.writeFileSync(path.join(nested, 'lib', 'x.js'), 'x');
+  const other = makeDir('territory-other');
+  fs.symlinkSync(path.join(nested, 'lib'), path.join(other, 'lib'));
+
+  const { record: outerRoot } = rig2.registration.add(ws2);
+  const { record: otherRoot } = rig2.registration.add(other);
+  const nestedRecord = rig2.registration.tree(ws2).registry.activeAt(outerRoot.uuid, 'vendor');
+  assert.equal(nestedRecord.type, 'repo.git');
+  const link2 = rig2.registration.tree(other).registry.activeAt(otherRoot.uuid, 'lib');
+  assert.equal(rig2.registration.linkTargets().get(link2.uuid), nestedRecord.uuid,
+    'a nested boundary\'s record owns its subtree');
+});
+
+// --- the four permanent exams of the second audit --------------------------
+
+test('a moved target keeps its permanent UUID: identity survives the address', () => {
+  const rig = makeRig();
+  const holder = makeDir('moved-holder');
+  const A = path.join(holder, 'A');
+  fs.mkdirSync(A);
+  fs.writeFileSync(path.join(A, 'doc.md'), 'doc');
+  const ws = makeDir('moved-ws');
+  fs.symlinkSync(A, path.join(ws, 'ptr'));
+
+  rig.registration.add(ws);
+  const uuid = rig.registration.tree(A).root().uuid;
+  const docUuid = rig.registration.tree(A).registry.activeAt(uuid, 'doc.md').uuid;
+  const treeCount = rig.registration.trees().size;
+
+  const B = path.join(holder, 'B');
+  fs.renameSync(A, B);
+  fs.unlinkSync(path.join(ws, 'ptr'));
+  fs.symlinkSync(B, path.join(ws, 'ptr'));
+  const wsRootId = rig.observer.listRoots().find((row) => row.path === ws).rootId;
+  const before = rig.events.length;
+  rig.observer.scanNow(wsRootId);
+  rig.registration.flushIfDirty();
+  rig.registration.flushIfDirty(); // the rescue lands mid-follow; the second flush proves clean
+
+  const treeB = rig.registration.tree(B);
+  assert.ok(treeB, 'the tree lives at its new address');
+  assert.equal(treeB.root().uuid, uuid,
+    'the UUID is the identity; the path was only the current local address');
+  assert.equal(treeB.registry.activeAt(uuid, 'doc.md').uuid, docUuid, 'records inside survived untouched');
+  assert.equal(rig.registration.tree(A), null, 'no ghost tree stayed behind at the old address');
+  assert.equal(rig.registration.trees().size, treeCount, 'a move minted nothing');
+  assert.deepEqual(
+    committedSince(rig.events, before).filter((event) => [uuid, docUuid].includes(event.record?.uuid)),
+    [], 'not one record in the moved tree was rewritten');
+  const wsTree = rig.registration.tree(ws);
+  const link = wsTree.registry.activeAt(wsTree.root().uuid, 'ptr');
+  assert.equal(rig.registration.linkTargets().get(link.uuid), uuid,
+    'the retargeted pointer reaches the SAME entity it always did');
+
+  // The tree is fully alive at its new address: fresh ground reconciles.
+  fs.writeFileSync(path.join(B, 'later.md'), 'later');
+  rig.observer.scanNow(rig.observer.listRoots().find((row) => row.path === B).rootId);
+  rig.registration.flushIfDirty();
+  assert.ok(treeB.registry.activeAt(uuid, 'later.md'),
+    'evidence follows the address: detection after the move lands on the same tree');
+});
+
+test('a restarted boundary finds a moved tree by its permanent identity, never its address', () => {
+  const rig = makeRig();
+  const holder = makeDir('restart-holder');
+  const A = path.join(holder, 'A');
+  fs.mkdirSync(A);
+  fs.writeFileSync(path.join(A, 'doc.md'), 'doc');
+  const ws = makeDir('restart-ws');
+  fs.symlinkSync(A, path.join(ws, 'ptr'));
+
+  rig.registration.add(ws);
+  const uuid = rig.registration.tree(A).root().uuid;
+
+  const B = path.join(holder, 'B');
+  fs.renameSync(A, B);
+  fs.unlinkSync(path.join(ws, 'ptr'));
+  fs.symlinkSync(B, path.join(ws, 'ptr'));
+  rig.observer.scanNow(rig.observer.listRoots().find((row) => row.path === ws).rootId);
+  rig.registration.flushIfDirty();
+  rig.registration.flushIfDirty(); // the rescue lands mid-follow; the second flush proves clean
+  assert.equal(rig.registration.tree(B).root().uuid, uuid, 'the live rescue held');
+
+  // The restart is the exam: durable storage opens by rootId, so the
+  // reopened boundary finds the SAME tree at the new address — a
+  // path-keyed policy would mint a fresh identity here.
+  const before = rig.events.length;
+  const reopened = rig.restart();
+  assert.equal(reopened.tree(B).root().uuid, uuid,
+    'identity survived the restart: storage is keyed by the permanent rootId, never the address');
+  assert.deepEqual(committedSince(rig.events, before), [],
+    'reopening a moved tree over unchanged truth is silence');
+});
+
+test('the policy judges the complete path: a benign name inside excluded ground is refused on every route', () => {
+  const rig = makeRig({ shouldEnroll: defaultPolicy });
+  const home = makeDir('sshhome');
+  fs.mkdirSync(path.join(home, '.ssh'));
+  const sshConfig = path.join(home, '.ssh', 'config');
+  fs.writeFileSync(sshConfig, 'Host *');
+  const ws = makeDir('sshws');
+  fs.writeFileSync(path.join(ws, 'app.md'), 'app');
+  fs.symlinkSync(sshConfig, path.join(ws, 'sshcfg'));
+
+  rig.registration.add(ws);
+  assert.ok(!rig.observer.listRoots().some((root) => root.path === sshConfig),
+    '"config" is a benign name, but .ssh on its path excludes it — never watched');
+  assert.equal(rig.registration.tree(sshConfig), null, 'and never registered');
+  assert.deepEqual(rig.registration.reported().map((entry) => [entry.path, entry.via]),
+    [[sshConfig, 'sshcfg']], 'the refusal is visible, never a silent basename bypass');
+  assert.match(rig.registration.reported()[0].reason, /enrollment policy/);
+
+  assert.throws(() => rig.registration.add(sshConfig), /enrollment policy excludes/,
+    'the explicit route judges the same complete path');
+});
+
+test('an enrollment failure is never silence: the boundary stays dirty and the retry completes', () => {
+  const rig = makeRig();
+  const target = makeDir('loud-target');
+  fs.writeFileSync(path.join(target, 'lib.js'), 'x');
+  const ws = makeDir('loud-ws');
+  rig.registration.add(ws);
+
+  // One injected identity failure — a database error, not a vanished
+  // target. Swallowing it as disappearance would let the boundary call
+  // itself clean while the target silently stays unregistered.
+  const original = rig.observer.enrollRoot;
+  let failures = 1;
+  rig.observer.enrollRoot = (...args) => {
+    if (failures-- > 0) throw new Error('injected: identity store failure');
+    return original.apply(rig.observer, args);
+  };
+
+  fs.symlinkSync(target, path.join(ws, 'dep'));
+  rig.observer.scanNow(rig.observer.listRoots().find((row) => row.path === ws).rootId);
+  assert.equal(rig.registration.flushIfDirty(), false,
+    'the failure propagated: the boundary stays dirty instead of reporting clean');
+  assert.equal(rig.registration.tree(target), null, 'nothing pretended to register');
+
+  assert.equal(rig.registration.flushIfDirty(), true, 'the retry runs the same pass and lands');
+  assert.ok(rig.registration.tree(target), 'the target is registered once the failure clears');
+});
+
+test('adding a symlink directly registers both the link and its target', () => {
+  const rig = makeRig();
+  const target = makeDir('alias-target');
+  fs.writeFileSync(path.join(target, 'x.md'), 'x');
+  const holder = makeDir('alias-holder');
+  const alias = path.join(holder, 'alias');
+  fs.symlinkSync(target, alias);
+
+  const { rootPath, record } = rig.registration.add(alias);
+  assert.equal(rootPath, alias, 'the address the user named is the ground that registers');
+  assert.equal(record.type, 'link', 'the pointer is an entity of its own — a tree of one');
+  assert.equal(record.name, 'alias');
+
+  const targetTree = rig.registration.tree(target);
+  assert.ok(targetTree, 'and its target followed as an edge, registered too');
+  assert.equal(rig.registration.linkTargets().get(record.uuid), targetTree.root().uuid,
+    'two entities, connected: link UUID → target UUID');
+  assert.ok(!rig.observer.listRoots().some((root) => root.path === holder),
+    'the holder was never enrolled: the alias names itself, not its parent');
+
+  // A retarget is the link entity's own change, and the resolution follows.
+  const second = makeDir('alias-second');
+  fs.unlinkSync(alias);
+  fs.symlinkSync(second, alias);
+  const aliasRootId = rig.observer.listRoots().find((row) => row.path === alias).rootId;
+  rig.observer.scanNow(aliasRootId);
+  rig.registration.flushIfDirty();
+  const after = rig.registration.tree(alias).root();
+  assert.equal(after.uuid, record.uuid, 'same entity');
+  assert.notEqual(after.version, record.version, 'a new written address is a new version');
+  assert.equal(rig.registration.linkTargets().get(record.uuid),
+    rig.registration.tree(second).root().uuid);
+});
+
+test('excluded targets are never auto-enrolled, and an explicit add refuses: one policy on every route', () => {
+  const rig = makeRig({ shouldEnroll: defaultPolicy });
+  const holder = makeDir('secret-holder');
+  const envPath = path.join(holder, '.env');
+  fs.writeFileSync(envPath, 'SECRET=1');
+  const ws = makeDir('secret-ws');
+  fs.writeFileSync(path.join(ws, 'app.md'), 'app');
+  fs.symlinkSync(envPath, path.join(ws, 'config'));
+
+  const { record: wsRoot } = rig.registration.add(ws);
+  const link = rig.registration.tree(ws).registry.activeAt(wsRoot.uuid, 'config');
+  assert.ok(link, 'the link record itself is workspace truth and stays');
+  assert.ok(!rig.observer.listRoots().some((root) => root.path === envPath),
+    'the secret was never watched');
+  assert.equal(rig.registration.tree(envPath), null, 'and never registered');
+  assert.deepEqual(rig.registration.reported().map((entry) => [entry.path, entry.via]),
+    [[envPath, 'config']], 'the refusal is visible on the boundary, never silent');
+  assert.match(rig.registration.reported()[0].reason, /enrollment policy/);
+  assert.equal(rig.registration.linkTargets().get(link.uuid), null,
+    'resolution is honestly null: no entity owns excluded ground');
+
+  assert.throws(() => rig.registration.add(envPath), /enrollment policy excludes/,
+    'the explicit route asks the same policy — the deliberate override is future work, never a default');
+});
+
+// --- adoption: a tree boundary is not identity ------------------------------
+
+test('a registered tree moving inside another registered tree is ADOPTED: same UUID, new parent, descendants silent', () => {
+  const rig = makeRig();
+  const ws = makeDir('adopt-ws');
+  const outside = makeDir('adopt-target');
+  fs.writeFileSync(path.join(outside, 'doc.md'), 'doc');
+  fs.symlinkSync(outside, path.join(ws, 'ptr'));
+
+  rig.registration.add(ws);
+  const treeUuid = rig.registration.tree(outside).root().uuid;
+  const docUuid = rig.registration.tree(outside).registry.activeAt(treeUuid, 'doc.md').uuid;
+
+  // The reproduced cross-tree move: the separately registered target
+  // relocates INSIDE the workspace, and the link follows it there.
+  const newHome = path.join(ws, 'target');
+  fs.renameSync(outside, newHome);
+  fs.unlinkSync(path.join(ws, 'ptr'));
+  fs.symlinkSync(newHome, path.join(ws, 'ptr'));
+  const before = rig.events.length;
+  rig.observer.scanNow();
+  rig.registration.flushIfDirty();
+  rig.registration.flushIfDirty(); // the second pass retires the orphan's observer family
+
+  const wsTree = rig.registration.tree(ws);
+  const inside = wsTree.registry.activeAt(wsTree.root().uuid, 'target');
+  assert.equal(inside.uuid, treeUuid,
+    'a tree boundary is not identity: the UUID rode the move into the new tree');
+  assert.equal(inside.type, 'folder',
+    'and the root shape shed in the same transition — workspace is the root type only');
+  assert.equal(wsTree.registry.activeAt(treeUuid, 'doc.md').uuid, docUuid,
+    'every descendant rode along: the arrival law reconnected its channel to the same record');
+  assert.equal(committedSince(rig.events, before)
+    .filter((event) => event.record?.uuid === docUuid).length, 0,
+    'descendants moved without one record rewritten');
+  assert.equal(rig.registration.tree(outside), null, 'no stranded ghost tree at the old address');
+  assert.ok(!rig.observer.listRoots().some((root) => root.path === outside),
+    'the orphan\'s observer family retired: the ground is covered by its new tree');
+  const link = wsTree.registry.activeAt(wsTree.root().uuid, 'ptr');
+  assert.equal(rig.registration.linkTargets().get(link.uuid), treeUuid,
+    'the retargeted pointer reaches the SAME entity it always did — inside its new tree');
+
+  // And the adoption is durable: a restarted boundary sees the same graph.
+  const mark = rig.events.length;
+  const reopened = rig.restart();
+  assert.deepEqual(committedSince(rig.events, mark), [], 'restart over the adopted graph is silence');
+  assert.equal(reopened.tree(ws).registry.activeAt(reopened.tree(ws).root().uuid, 'target').uuid, treeUuid);
+});
+
+test('a registered repository moving inside a registered workspace adopts as territory: same UUID, repo.git child', () => {
+  const rig = makeRig();
+  const repo = makeDir('adopt-repo');
+  gitInit(repo);
+  fs.writeFileSync(path.join(repo, 'lib.js'), 'x');
+  const { record: repoRecord } = rig.registration.add(repo);
+  const ws = makeDir('adopt-repo-ws');
+  rig.registration.add(ws);
+
+  fs.renameSync(repo, path.join(ws, 'vendor'));
+  rig.observer.scanNow();
+  rig.registration.flushIfDirty();
+  rig.registration.flushIfDirty();
+
+  const wsTree = rig.registration.tree(ws);
+  const vendor = wsTree.registry.activeAt(wsTree.root().uuid, 'vendor');
+  assert.equal(vendor.uuid, repoRecord.uuid,
+    'the repo tree adopted as territory of its new tree — never a fresh territory record');
+  assert.equal(vendor.type, 'repo.git');
+  assert.equal(rig.registration.tree(repo), null, 'no stranded tree at the old address');
+  assert.ok(!rig.observer.listRoots().some((root) => root.path === repo),
+    'the orphan repo root retired; the enclosed territory root carries the watching');
+});
+
+test('a retirement torn at any point never resurrects a duplicate: restart completes it', () => {
+  const rig = makeRig();
+  const ws = makeDir('tear-ws');
+  fs.writeFileSync(path.join(ws, 'w.md'), 'w');
+  const outside = makeDir('tear-target');
+  fs.writeFileSync(path.join(outside, 'doc.md'), 'doc');
+  const wsUuid = rig.registration.add(ws).record.uuid;
+  const tgtUuid = rig.registration.add(outside).record.uuid;
+  const orphanRootId = rig.observer.listRoots().find((root) => root.path === outside).rootId;
+  rig.registration.flushIfDirty();
+
+  fs.renameSync(outside, path.join(ws, 'target'));
+  rig.observer.scanNow();
+  rig.registration.flushIfDirty(); // the adoption commits
+
+  // TEAR ONE — the worst one: the process dies before a single observer
+  // row is removed, leaving a living orphan family. Retirement is
+  // evidence-first, identity-last, so the family's witness binding still
+  // stands and still proves the adoption. (The reverse order once
+  // resurrected a duplicate here: an unbound living root looks like
+  // fresh ground, and fresh ground mints.)
+  const realRemove = rig.observer.removeRoot;
+  rig.observer.removeRoot = () => { throw new Error('injected: process died mid-retirement'); };
+  try { rig.registration.flushIfDirty(); } catch { /* the crash */ }
+  rig.observer.removeRoot = realRemove;
+
+  const mark = rig.events.length;
+  const reborn = rig.restart();
+  assert.deepEqual([...reborn.trees().values()].map((tree) => tree.root().uuid), [wsUuid],
+    'one tree after the restart: nothing minted over the orphan');
+  assert.equal(reborn.tree(ws).registry.activeAt(wsUuid, 'target').uuid, tgtUuid,
+    'the adopted UUID is intact');
+  assert.ok(!rig.observer.listRoots().some((root) => root.path === outside),
+    'the restart completed the torn retirement');
+  assert.deepEqual(committedSince(rig.events, mark), [], 'and completing it committed nothing');
+
+  // TEAR TWO — rows removed, scope never dropped. That exact state is
+  // constructed here; the residue sweep collects it at the next pass,
+  // because a scope whose witness root no longer lives is a finished
+  // retirement's leftovers (the loss law has already vouched for every
+  // living tree before the sweep runs).
+  const second = makeDir('tear-second');
+  fs.writeFileSync(path.join(second, 's.md'), 's');
+  const secondUuid = reborn.add(second).record.uuid;
+  const secondRootId = rig.observer.listRoots().find((root) => root.path === second).rootId;
+  reborn.flushIfDirty();
+  fs.renameSync(second, path.join(ws, 'second'));
+  rig.observer.scanNow();
+  reborn.flushIfDirty(); // adoption
+  rig.observer.removeRoot(secondRootId); // the crash left exactly this: rows gone, scope standing
+  reborn.flushIfDirty();
+  const memory = createEvidenceMemory(rig.identityDb);
+  assert.equal(memory.allBindings().filter((row) => row.scopeId === secondRootId).length, 0,
+    'the sweep dropped the dead scope: no residue');
+  assert.equal(memory.allBindings().filter((row) => row.scopeId === orphanRootId).length, 0,
+    'tear one\'s scope is gone too');
+  assert.equal(reborn.tree(ws).registry.activeAt(wsUuid, 'second').uuid, secondUuid,
+    'the second adoption held through its tear as well');
+});
+
+test('a REAL restart: file-backed databases, closed and reopened, prove durable identity end to end', () => {
+  const stateDir = makeDir('durable-state');
+  const observerDbPath = path.join(stateDir, 'observer.db');
+  const identityDbPath = path.join(stateDir, 'identity.db');
+  const sentinelPath = path.join(stateDir, 'identity.epoch');
+  const events = [];
+
+  // A boot is the real thing: fresh connections over the durable files.
+  const boot = () => {
+    const observerDb = new Database(observerDbPath);
+    const identityDb = new Database(identityDbPath);
+    const ref = { current: null };
+    const observer = createObserver({
+      db: observerDb,
+      emit: (event) => { events.push(event); ref.current?.onEvent(event); },
+    });
+    ref.current = createRegistration({
+      observer, openIdentity: () => ({ db: identityDb, sentinelPath }),
+      classify: () => 'file.text',
+      emit: (event) => events.push(event),
+    });
+    return {
+      observer,
+      registration: ref.current,
+      close: () => { observer.stop(); observerDb.close(); identityDb.close(); },
+    };
+  };
+
+  // Session one: register a workspace whose link reaches an external
+  // tree, move that tree (rescued live), and lose a second tree's ground
+  // (honest absence). Then CLOSE EVERYTHING — no shared handles survive.
+  const one = boot();
+  const ws = makeDir('durable-ws');
+  const holder = makeDir('durable-holder');
+  const A = path.join(holder, 'A');
+  fs.mkdirSync(A);
+  fs.writeFileSync(path.join(A, 'doc.md'), 'doc');
+  fs.symlinkSync(A, path.join(ws, 'ptr'));
+  const gone = makeDir('durable-gone');
+  fs.writeFileSync(path.join(gone, 'x.md'), 'x');
+
+  one.registration.add(ws);
+  one.registration.add(gone);
+  const movedUuid = one.registration.tree(A).root().uuid;
+  const goneUuid = one.registration.tree(gone).root().uuid;
+
+  const B = path.join(holder, 'B');
+  fs.renameSync(A, B);
+  fs.unlinkSync(path.join(ws, 'ptr'));
+  fs.symlinkSync(B, path.join(ws, 'ptr'));
+  fs.rmSync(gone, { recursive: true, force: true });
+  one.observer.scanNow();
+  one.registration.flushIfDirty();
+  one.registration.flushIfDirty();
+  assert.equal(one.registration.tree(B).root().uuid, movedUuid, 'the live rescue held');
+  one.close();
+
+  // Session two: a true process-restart shape. Identity, presence, and
+  // bindings must all come back from the files alone — and unchanged
+  // truth must reconcile in silence.
+  const mark = events.length;
+  const two = boot();
+  assert.equal(two.registration.tree(B).root().uuid, movedUuid,
+    'the moved tree came back by identity from durable storage — same UUID, new address');
+  assert.equal(two.registration.tree(gone).root().uuid, goneUuid,
+    'the absent tree\'s identity survived the restart too');
+  const goneRow = two.observer.listRoots().find((row) => row.path === gone);
+  assert.equal(goneRow.present, false,
+    'presence is durable evidence: the restart still knows this ground is unavailable');
+  assert.ok(two.observer.verify(goneRow.rootId).length > 0, 'and the referee still convicts it');
+  assert.deepEqual(events.slice(mark).filter((event) => event.type === 'entity.committed'), [],
+    'reopening over unchanged truth is silence — no record minted, moved, or rewritten');
+  two.close();
+});
+
+test('the loss law convicts at the boundary: a fresh observer store over surviving trees mints nothing', () => {
+  const identityDb = new Database(':memory:');
+  const observer = createObserver({ db: new Database(':memory:'), emit: () => {} });
+  const registration = createRegistration({
+    observer, openIdentity: () => ({ db: identityDb, ephemeral: true }),
+    classify: () => 'file.text', emit: () => {},
+  });
+  const ws = makeDir('loss-ws');
+  fs.writeFileSync(path.join(ws, 'a.md'), 'a');
+  const external = makeDir('loss-external');
+  fs.writeFileSync(path.join(external, 'lib.md'), 'lib');
+  fs.symlinkSync(external, path.join(ws, 'ptr'));
+  registration.add(ws);
+
+  // The observer store is LOST; the surviving identity database still
+  // holds the tree. A fresh boundary must convict loudly at startup —
+  // BEFORE it acts at all: no lens mints a replacement over the
+  // surviving records, and no edge is followed onto new ground. A
+  // convicted boundary never expands coverage.
+  const observer2 = createObserver({ db: new Database(':memory:'), emit: () => {} });
+  observer2.enrollRoot(ws);
+  assert.throws(() => createRegistration({
+    observer: observer2, openIdentity: () => ({ db: identityDb, ephemeral: true }),
+    classify: () => 'file.text', emit: () => {},
+  }), /identity evidence lost/, 'a lost store is never a fresh start');
+  assert.equal(observer2.listRoots().some((root) => root.path === external), false,
+    'conviction came before action: the edge was never followed onto new ground');
+});
+
+// --- the managed reference: the OTHER link kind -----------------------------
+
+test('a managed reference targets a UUID, not a path: the rendering follows the target through absence and reattachment', () => {
+  const rig = makeRig();
+  const home = makeDir('ref-home'); // the Amalgm folder: ordinary registered ground
+  rig.registration.add(home);
+  const holder = makeDir('ref-holder');
+  const project = path.join(holder, 'project');
+  fs.mkdirSync(project);
+  fs.writeFileSync(path.join(project, 'main.js'), 'x');
+
+  const { record: ref, targetUUID } = rig.registration.addReference(project, path.join(home, 'project'));
+  assert.equal(ref.type, 'reference');
+  assert.equal(targetUUID, rig.registration.tree(project).root().uuid,
+    'the payload is the target entity\'s identity, never a path');
+  assert.equal(fs.readlinkSync(path.join(home, 'project')), project,
+    'locally the reference renders as an ordinary symlink to the target\'s current address');
+  rig.registration.flushIfDirty();
+  assert.equal(rig.registration.linkTargets().get(ref.uuid), targetUUID,
+    'the rendering resolves to the target: reference UUID → target UUID');
+
+  // The target moves while nothing observes it: honest absence first,
+  // then the reattachment moment rescues it — and the derived rendering
+  // follows. Neither UUID ever changes; the reference record never moves.
+  const moved = path.join(holder, 'project-v2');
+  fs.renameSync(project, moved);
+  rig.observer.scanNow();
+  rig.observer.enrollRoot(moved); // the reattachment names the new address
+  rig.registration.flushIfDirty();
+  assert.equal(fs.readlinkSync(path.join(home, 'project')), moved,
+    'the rendering follows the target: rewritten by the boundary, repaired after absence');
+  assert.equal(rig.registration.tree(moved).root().uuid, targetUUID, 'same target entity');
+  const after = rig.registration.tree(home).registry.record(ref.uuid);
+  assert.equal(after.version, ref.version,
+    'a rendering rewrite is derived state: the reference record itself never changed');
+  rig.registration.flushIfDirty();
+  assert.equal(rig.registration.linkTargets().get(ref.uuid), targetUUID,
+    'resolution lives again at the new address');
+});
+
+test('a reference is canonical truth with an idempotent projection: it self-heals, retries converge, real ground is never overwritten', async () => {
+  const rig = makeRig();
+  const home = makeDir('heal-home');
+  fs.writeFileSync(path.join(home, 'keep.md'), 'k');
+  rig.registration.add(home);
+  const homeRootId = rig.observer.listRoots().find((root) => root.path === home).rootId;
+  const notes = path.join(makeDir('heal-holder'), 'notes.md');
+  fs.writeFileSync(notes, 'n');
+  const at = path.join(home, 'notes');
+
+  // The rendering fails AFTER the record commits. The record is
+  // canonical truth; the deliberate act is idempotent, so repeating it
+  // converges the projection instead of refusing its own slot.
+  const realSymlink = fs.symlinkSync;
+  fs.symlinkSync = () => { throw new Error('injected: symlink failed after the record committed'); };
+  assert.throws(() => rig.registration.addReference(notes, at), /injected/);
+  fs.symlinkSync = realSymlink;
+  const { record: ref, targetUUID } = rig.registration.addReference(notes, at);
+  assert.equal(fs.readlinkSync(at), notes, 'the repeated act converged the missing projection');
+  assert.equal(rig.registration.tree(home).registry.references().length, 1, 'one record, not two');
+
+  // A vanished rendering is recreated by the ordinary flush: missing
+  // projections are exactly what the projector recreates — which is also
+  // why a rewrite may be remove-then-render and still never tear.
+  fs.unlinkSync(at);
+  rig.observer.scanNow(homeRootId);
+  rig.registration.flushIfDirty();
+  assert.equal(fs.readlinkSync(at), notes, 'a missing projection is recreated');
+
+  // ... and by the EVENT-scheduled pass: maintenance is automatic after
+  // events, never only on an explicit ask.
+  fs.unlinkSync(at);
+  rig.observer.scanNow(homeRootId); // the deletion fact schedules the full flush
+  await new Promise((resolve) => setImmediate(() => setImmediate(resolve)));
+  assert.equal(fs.readlinkSync(at), notes, 'the scheduled flush projected it back');
+
+  // Real ground occupying the slot is DIVERGENCE, never overwritten —
+  // and the ground leaving the address resolves it, like any contest.
+  fs.unlinkSync(at);
+  fs.writeFileSync(at, 'user data');
+  rig.observer.scanNow(homeRootId);
+  rig.registration.flushIfDirty();
+  assert.equal(fs.readFileSync(at, 'utf8'), 'user data', 'the projector never overwrites real ground');
+  assert.ok(rig.registration.tree(home).evidence.divergence().has('notes'),
+    'the lens reports the occupied rendering slot');
+  fs.unlinkSync(at);
+  rig.observer.scanNow(homeRootId);
+  rig.registration.flushIfDirty();
+  assert.equal(fs.readlinkSync(at), notes, 'the projection returns when the ground leaves');
+  rig.registration.flushIfDirty(); // the recreated rendering's channel binds on the next pass
+  assert.equal(rig.registration.tree(home).registry.record(ref.uuid).version, ref.version,
+    'through every repair the reference record never changed');
+  assert.equal(rig.registration.linkTargets().get(ref.uuid), targetUUID);
+});
+
+test('startup is the same convergence pass: a rendering no event can ever heal is recreated at attachment', () => {
+  const rig = makeRig();
+  const home = makeDir('startup-home');
+  rig.registration.add(home);
+  const target = path.join(makeDir('startup-holder'), 'notes.md');
+  fs.writeFileSync(target, 'n');
+  const rendered = path.join(home, 'notes');
+  const { record: ref, targetUUID } = rig.registration.addReference(target, rendered);
+  assert.equal(fs.readlinkSync(rendered), target);
+
+  // The worst shape: the deletion is DETECTED — the event fires into a
+  // dead boundary (the crash window) — so the store already holds this
+  // truth. The catch-up scan after restart finds equal truth: silence.
+  // No event will ever fire for it again; only startup itself can heal.
+  const homeRootId = rig.observer.listRoots().find((root) => root.path === home).rootId;
+  rig.detach();
+  fs.unlinkSync(rendered);
+  rig.observer.scanNow(homeRootId);
+  assert.equal(fs.existsSync(rendered), false, 'nothing attached, nothing healed');
+
+  rig.restart();
+  assert.equal(fs.readlinkSync(rendered), target,
+    'attachment recreated the rendering — no event, no explicit flush, the startup pass itself');
+  rig.observer.scanNow(homeRootId); // the catch-up over healed truth stays silent
+  rig.registration.flushIfDirty(); // the recreated rendering's channel binds on the next pass
+  assert.equal(fs.readlinkSync(rendered), target);
+  assert.equal(rig.registration.tree(home).registry.record(ref.uuid).version, ref.version,
+    'healing is projection, never mutation: the reference record is untouched');
+  assert.equal(rig.registration.linkTargets().get(ref.uuid), targetUUID);
+});
+
+test('a managed reference follows its single-file target renamed in place: the rendering re-aims live', async () => {
+  // The user-level promise, end to end through the doorbell: the parent
+  // hears the rename (lawful worst case — only the new name arrives),
+  // the file root's channel inode claims the new address, root.moved
+  // schedules the full flush, and the projection follows. No
+  // unavailable moment, no explicit act.
+  const { deliver, restore } = installFakeWatch();
+  try {
+    const rig = makeRig();
+    const home = makeDir('aim-home');
+    rig.registration.add(home);
+    const holder = makeDir('aim-holder');
+    const A = path.join(holder, 'A.md');
+    fs.writeFileSync(A, 'alpha');
+    const rendered = path.join(home, 'note');
+    rig.registration.addReference(A, rendered);
+    assert.equal(fs.readlinkSync(rendered), A);
+    rig.observer.start();
+    try {
+      const B = path.join(holder, 'B.md');
+      fs.renameSync(A, B);
+      deliver(holder, 'B.md');
+      await new Promise((resolve) => setImmediate(() => setImmediate(resolve)));
+      assert.equal(fs.readlinkSync(rendered), B, 'the rendering follows the renamed file');
+      assert.equal(rig.events.some((event) => event.type === 'root.unavailable'), false,
+        'continuity never broke: the follow is live, not an absence-then-repair');
+    } finally {
+      rig.observer.stop();
+    }
+  } finally {
+    restore();
+  }
+});
+
+// --- the add surface -------------------------------------------------------
+
+test('add is one operation: a bare file registers, covered ground returns its tree, a swallow refuses', () => {
+  const rig = makeRig();
+  const holder = makeDir('add-holder');
+  const ws = path.join(holder, 'ws');
+  fs.mkdirSync(ws);
+  fs.writeFileSync(path.join(ws, 'a.md'), 'a');
+  const filePath = path.join(makeDir('add-file'), 'todo.md');
+  fs.writeFileSync(filePath, 't');
+
+  const solo = rig.registration.add(filePath);
+  assert.equal(solo.record.type, 'file.text', '`amalgm add <file>` is the same primitive: a tree of one');
+
+  const added = rig.registration.add(ws);
+  const again = rig.registration.add(path.join(ws, 'a.md'));
+  assert.equal(again.rootPath, ws, 'ground already inside a registered tree returns that tree');
+  assert.equal(again.record.uuid, added.record.uuid);
+
+  assert.throws(() => rig.registration.add(holder), /one owner per path/,
+    'ground that would swallow a registered root refuses loudly');
+});
+
+test('the would-swallow edge refusal is visible on the boundary, never silent', () => {
+  const rig = makeRig();
+  const holder = makeDir('report-holder');
+  const ws = path.join(holder, 'ws');
+  fs.mkdirSync(ws);
+  fs.symlinkSync(holder, path.join(ws, 'up'));
+
+  rig.registration.add(ws);
+  assert.deepEqual(rig.registration.reported().map((entry) => [entry.path, entry.via]),
+    [[holder, 'up']], 'the refused edge is reported with the pointer that raised it');
+});
+
+test('an inconclusive edge follow keeps the boundary dirty until the ground settles', () => {
+  const rig = makeRig();
+  const dir = makeDir('sealed-follow');
+  gitInit(dir);
+  fs.mkdirSync(path.join(dir, 'sealed'));
+  fs.chmodSync(path.join(dir, 'sealed'), 0o000);
+  try {
+    rig.registration.add(dir);
+    assert.equal(rig.registration.flushIfDirty(), false,
+      'unreadable ground may hide an edge — the follow concludes no completeness');
+  } finally {
+    fs.chmodSync(path.join(dir, 'sealed'), 0o755);
+  }
+  assert.equal(rig.registration.flushIfDirty(), true, 'the settled ground converges clean');
+});