amalgm 0.1.245 → 0.1.246

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

@@ -0,0 +1,1365 @@
+'use strict';
+
+/**
+ * The ENTITY oracle — files, folders, links, and repositories — proving
+ * itself against the current detector: the judge's expected state is the
+ * six-field universal entity record (docs/entity-model.md), and EVERY
+ * field of every record is judged
+ * at every quiet point: addresses re-derive through the parent chain,
+ * lifecycle is EXPLICIT registry law that detection never writes (a
+ * disappearance closes the channel and moves no record), git is a lens
+ * (type transition on one uuid — including the enrolled root — with
+ * entities persisting beneath it and exactly one adapter owning detection
+ * at a time), and both halves of the ratified version formula recompute
+ * from records + payload evidence alone. The boundary adapter
+ * (entity-oracle/adapter.js) compares the slice today's detector claims;
+ * when the registry lands, the adapter widens what the detector is held to.
+ *
+ * Before folder, link, or registry code exists, the judge must be shown
+ * able to catch bugs: these tests drive the real observer through the
+ * filesystem operation grammar and demand that four independent witnesses
+ * (operation model, disk referee, detector slice, event ledger) agree at
+ * every proven quiet point — then deliberately feed the judge lies and
+ * demand a conviction. A judge that can be fooled here would silently bless
+ * everything built after it.
+ *
+ * Two categories, named for what they prove:
+ *   - catch-up tests drive detection with explicit scans and judge
+ *     convergence;
+ *   - the event-only test rings doorbells through production wiring after
+ *     start() and never invokes a manual scan — the referee stays
+ *     read-only while judging.
+ */
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('fs');
+const path = require('path');
+
+const { sha256 } = require('./entity-oracle/graph');
+const {
+  cleanup, converged, defaultPolicy, fakeWatchKit, fileIdAt, linkIdAt,
+  makeKit, sleep,
+} = require('./entity.rig');
+
+test.after(cleanup);
+
+// --- the grammar, with the whole oracle agreeing at every quiet point -----
+
+test('enrollment is the birth of channels, and all four witnesses agree', () => {
+  const kit = makeKit('birth');
+  kit.write('a.md', 'alpha v1');
+  kit.write('sub/nested/b.txt', 'aaaa');
+  kit.write('sub/c.md', 'gamma');
+  kit.write('bin/data.bin', Buffer.from([0x00, 0xff, 0x00, 0x7f, 0x80, 0x00]));
+
+  kit.enroll();
+  kit.point();
+
+  assert.equal(kit.events.filter((e) => e.type === 'file.created').length, 4);
+});
+
+test('the filesystem grammar converges: edit, same-size, touch, replace, rename, move, swap, duplicate, delete, recreate', () => {
+  const kit = makeKit('grammar');
+  kit.write('a.md', 'alpha v1');
+  kit.write('sub/nested/b.txt', 'aaaa');
+  kit.write('sub/c.md', 'gamma');
+  kit.enroll();
+  kit.point();
+  const originalA = fileIdAt(kit, 'a.md');
+
+  // Content edit.
+  kit.write('a.md', 'alpha v2 with more bytes');
+  kit.point();
+
+  // Same-size edit (stats lie about content).
+  kit.write('sub/nested/b.txt', 'bbbb');
+  kit.point();
+
+  // A touch with identical bytes is silence.
+  kit.touchSame('a.md');
+  const before = kit.events.length;
+  kit.point();
+  assert.equal(kit.events.slice(before).filter((e) => e.type.startsWith('file.')).length, 0,
+    'identical bytes must be silence');
+
+  // Atomic replacement: new physical file, same address, same identity.
+  kit.replace('a.md', 'alpha v3 atomically');
+  kit.point();
+  assert.equal(fileIdAt(kit, 'a.md'), originalA, 'atomic replacement must not re-mint the channel');
+
+  // Rename into a new folder: exactly one folder-blind rename event today.
+  const preRename = kit.events.length;
+  kit.mv('a.md', 'docs/a2.md');
+  kit.point();
+  const renames = kit.events.slice(preRename).filter((e) => e.type === 'file.renamed');
+  assert.equal(renames.length, 1);
+  assert.equal(fileIdAt(kit, 'docs/a2.md'), originalA, 'the move must preserve identity');
+
+  // Ancestor move: every descendant is rescued, no identity re-minted.
+  const nestedB = fileIdAt(kit, 'sub/nested/b.txt');
+  const subC = fileIdAt(kit, 'sub/c.md');
+  kit.mvDir('sub', 'moved-sub');
+  kit.point();
+  assert.equal(fileIdAt(kit, 'moved-sub/nested/b.txt'), nestedB);
+  assert.equal(fileIdAt(kit, 'moved-sub/c.md'), subC);
+
+  // Path swap: neither path is orphaned, so the address claims the channel
+  // and the swap is two content changes — identity is never guessed.
+  const preSwap = kit.events.length;
+  kit.mv('moved-sub/c.md', 'swap-tmp');
+  kit.mv('docs/a2.md', 'moved-sub/c.md');
+  kit.mv('swap-tmp', 'docs/a2.md');
+  kit.point();
+  const swapEvents = kit.events.slice(preSwap);
+  assert.equal(swapEvents.filter((e) => e.type === 'file.changed').length, 2);
+  assert.equal(swapEvents.filter((e) => e.type === 'file.renamed').length, 0);
+
+  // Duplicate identical content: two channels, one hash — identity is
+  // never derived from bytes.
+  kit.copy('docs/a2.md', 'docs/dupe.md', 'gamma');
+  kit.point();
+  assert.notEqual(fileIdAt(kit, 'docs/dupe.md'), fileIdAt(kit, 'docs/a2.md'));
+
+  // A settled disappearance closes the channel; the returning ground
+  // reconnects to the same ENTITY (the slot's active owner) while the
+  // channel itself is re-minted evidence.
+  const doomed = fileIdAt(kit, 'docs/dupe.md');
+  kit.rm('docs/dupe.md');
+  kit.point();
+  kit.write('docs/dupe.md', 'reborn, reconnected');
+  kit.point();
+  assert.notEqual(fileIdAt(kit, 'docs/dupe.md'), doomed,
+    'the re-minted channel is fresh evidence — the entity underneath reconnects');
+
+  // Delete + recreate BETWEEN quiet points: the address never observably
+  // died, so the channel survives (path claims the channel).
+  const survivor = fileIdAt(kit, 'docs/dupe.md');
+  kit.rm('docs/dupe.md');
+  kit.write('docs/dupe.md', 'same interval, same channel');
+  kit.point();
+  assert.equal(fileIdAt(kit, 'docs/dupe.md'), survivor);
+});
+
+test('the universal record: every envelope field moves the version, the uuid never moves', () => {
+  const kit = makeKit('record');
+  kit.write('nest/doc.txt', 'v1 text');
+  kit.write('den/keep.txt', 'keeper');
+  kit.enroll();
+  let snap = kit.point();
+
+  const recordOf = (s, id) => s.records.find((r) => r.uuid === id);
+  const uuid = snap.files.get('nest/doc.txt').uuid;
+  const born = recordOf(snap, uuid);
+  assert.equal(born.type, 'file.text');
+  assert.equal(born.status, 'active');
+  assert.equal(snap.payloads.get(uuid), sha256('v1 text'));
+  assert.deepEqual(Object.keys(born).sort(),
+    ['name', 'parentUUID', 'status', 'type', 'uuid', 'version'],
+    'the universal record is EXACTLY six fields — payloads are evidence, not record');
+  const nestUuid = born.parentUUID;
+
+  // name: a rename in place moves the version; payload and parent do not.
+  kit.mv('nest/doc.txt', 'nest/memo.txt');
+  snap = kit.point();
+  const renamed = recordOf(snap, uuid);
+  assert.equal(renamed.name, 'memo.txt');
+  assert.equal(renamed.parentUUID, nestUuid);
+  assert.equal(snap.payloads.get(uuid), sha256('v1 text'));
+  assert.notEqual(renamed.version, born.version, 'name is in the envelope');
+
+  // parentUUID: a move across folders moves the version again.
+  kit.mv('nest/memo.txt', 'den/memo.txt');
+  snap = kit.point();
+  const moved = recordOf(snap, uuid);
+  assert.notEqual(moved.parentUUID, nestUuid);
+  assert.equal(moved.name, 'memo.txt');
+  assert.notEqual(moved.version, renamed.version, 'parentUUID is in the envelope');
+
+  // type: the injected classification policy flips its answer — a type
+  // transition on the SAME uuid (Axiom 1: type change preserves identity).
+  kit.write('den/memo.txt', Buffer.from([0x74, 0x00, 0x78]));
+  snap = kit.point();
+  const flipped = recordOf(snap, uuid);
+  assert.equal(flipped.type, 'file.binary');
+  assert.equal(flipped.uuid, uuid);
+  assert.notEqual(flipped.version, moved.version, 'type is in the envelope');
+
+  // payload: a content edit moves the version through the evidence alone.
+  const payloadBefore = snap.payloads.get(uuid);
+  kit.write('den/memo.txt', Buffer.from([0x74, 0x00, 0x79]));
+  snap = kit.point();
+  const edited = recordOf(snap, uuid);
+  assert.equal(edited.type, 'file.binary');
+  assert.notEqual(snap.payloads.get(uuid), payloadBefore);
+  assert.notEqual(edited.version, flipped.version, 'payload is in the envelope');
+});
+
+test('disappearance is evidence, not lifecycle: no record moves, and the slot\'s owner reconnects on return', () => {
+  const kit = makeKit('vanish');
+  kit.write('den/doomed.txt', 'mortal');
+  kit.write('den/keep.txt', 'keeper');
+  kit.enroll();
+  let snap = kit.point();
+  const uuid = snap.files.get('den/doomed.txt').uuid;
+  const channel = fileIdAt(kit, 'den/doomed.txt');
+  const freeze = (s) => new Map(s.records.map((r) => [r.uuid, JSON.stringify(r)]));
+  const movedSince = (before, s) => s.records
+    .filter((r) => before.get(r.uuid) !== JSON.stringify(r))
+    .map((r) => r.uuid);
+
+  // rm: the watcher reports absence and the channel closes — but lifecycle
+  // moves only by explicit registry action, so NOT ONE record moves. (The
+  // registry keeps the entity active and restores local from canonical;
+  // trash and delete are its explicit, owner-gated acts.)
+  let before = freeze(snap);
+  kit.rm('den/doomed.txt');
+  snap = kit.point();
+  assert.deepEqual(movedSince(before, snap), [],
+    'detection never writes lifecycle — a disappearance moves no record');
+  assert.equal(snap.records.find((r) => r.uuid === uuid).status, 'active');
+  assert.ok(!snap.files.has('den/doomed.txt'), 'the exposed slice reflects ground');
+  assert.ok(kit.events.some((e) => e.type === 'file.deleted' && e.fileId === channel),
+    'absence IS reported — as channel evidence, never as a lifecycle claim');
+
+  // Reappearance at the slot: the SAME entity — an active entity owns its
+  // (parent, name) slot even while absent, so the returning ground
+  // reconnects and the new bytes are its edit. Exactly one record moves
+  // (the entity's own version); the channel is fresh evidence.
+  before = freeze(snap);
+  kit.write('den/doomed.txt', 'reborn');
+  snap = kit.point();
+  assert.equal(snap.files.get('den/doomed.txt').uuid, uuid,
+    'reappearing ground reconnects to the active owner of the slot — never a second entity');
+  assert.deepEqual(movedSince(before, snap), [uuid],
+    'a reconnect with new bytes moves exactly one record: the entity\'s own version');
+  assert.equal(snap.payloads.get(uuid), sha256('reborn'));
+  assert.notEqual(fileIdAt(kit, 'den/doomed.txt'), channel,
+    'the channel is re-minted evidence; the entity underneath is the same');
+
+  // A whole subtree vanishing is still nothing: an external rm -rf, a
+  // disconnected drive, a permission failure — none may move a record.
+  before = freeze(snap);
+  kit.rmDir('den');
+  snap = kit.point();
+  assert.deepEqual(movedSince(before, snap), [],
+    'a vanished subtree moves no record — lifecycle is explicit only');
+
+  // And the subtree returning with the same bytes reconnects folder and
+  // file alike: a full round trip through absence in which NOTHING in the
+  // canonical graph ever moved — because nothing ever happened to it.
+  kit.write('den/doomed.txt', 'reborn');
+  snap = kit.point();
+  assert.equal(snap.files.get('den/doomed.txt').uuid, uuid);
+  assert.deepEqual(movedSince(before, snap), [],
+    'a round trip through absence with identical bytes moves nothing at all');
+});
+
+test('contested ground is divergence: two identity claims on one address move neither record', () => {
+  const kit = makeKit('contested');
+  kit.write('a.txt', 'alpha');
+  kit.write('b.txt', 'beta');
+  kit.enroll();
+  let snap = kit.point();
+  const uuidA = snap.files.get('a.txt').uuid;
+  const uuidB = snap.files.get('b.txt').uuid;
+  const channelA = fileIdAt(kit, 'a.txt');
+  const freeze = (s) => new Map(s.records.map((r) => [r.uuid, JSON.stringify(r)]));
+  const movedSince = (before, s) => s.records
+    .filter((r) => before.get(r.uuid) !== JSON.stringify(r))
+    .map((r) => r.uuid);
+
+  // b.txt departs; its active entity keeps the slot.
+  kit.rm('b.txt');
+  snap = kit.point();
+  const before = freeze(snap);
+  const regBefore = kit.regEvents.length;
+
+  // The physical a.txt lands on b.txt's slot. The channel honestly
+  // continues (one rename) AND an active entity owns the address: two
+  // established identity claims, one address — Amalgm picks no winner.
+  // Neither record moves, nothing is written, and the ground is reported
+  // as divergence pending resolution.
+  kit.mv('a.txt', 'b.txt');
+  snap = kit.point();
+  assert.deepEqual(movedSince(before, snap), [], 'a contest moves NEITHER record');
+  assert.ok(!snap.files.has('b.txt'), 'contested ground is claimed by no entity');
+  assert.equal(snap.divergent.get('b.txt'), sha256('alpha'),
+    'the contest itself is reported evidence, never hidden');
+  assert.equal(fileIdAt(kit, 'b.txt'), channelA,
+    'the observer honestly reports the continued channel — identity is never the channel\'s call');
+  assert.equal(kit.regEvents.length, regBefore, 'a contest commits nothing to the registry');
+
+  // The contest survives quiet points: nothing happened, nothing resolves.
+  snap = kit.point();
+  assert.equal(snap.divergent.get('b.txt'), sha256('alpha'));
+
+  // An atomic replace at the contested address is an ordinary edit OF THE
+  // CONTESTED GROUND: address continuity carries the contest, and the new
+  // bytes are never the claimant's payload nor the owner's.
+  kit.replace('b.txt', 'alpha v2');
+  snap = kit.point();
+  assert.deepEqual(movedSince(before, snap), [], 'an edit on contested ground moves no record');
+  assert.equal(snap.divergent.get('b.txt'), sha256('alpha v2'));
+  assert.equal(kit.regEvents.length, regBefore);
+
+  // Ground returning at the claimant's old address resolves NOTHING: the
+  // new file could be a copy — presence proves nothing about identity.
+  // The claimant reconnects at home on a fresh channel; the contest stands.
+  kit.write('a.txt', 'returned');
+  snap = kit.point();
+  assert.equal(snap.files.get('a.txt').uuid, uuidA,
+    'the claimant still owns its own slot and reconnects on return');
+  assert.notEqual(fileIdAt(kit, 'a.txt'), channelA);
+  assert.equal(snap.divergent.get('b.txt'), sha256('alpha v2'),
+    'reappearance is not resolution — the contest survives it');
+  assert.equal(snap.payloads.get(uuidB), sha256('beta'),
+    'the slot\'s owner never absorbed the contested bytes');
+
+  // The contest ends ONLY when the conflicting ground actually leaves.
+  kit.rm('b.txt');
+  snap = kit.point();
+  assert.equal(snap.divergent.size, 0, 'the ground left; the contest is over');
+
+  // And the slot's owner reconnects on genuinely fresh ground, as always.
+  kit.write('b.txt', 'beta again');
+  snap = kit.point();
+  assert.equal(snap.files.get('b.txt').uuid, uuidB);
+  assert.equal(snap.payloads.get(uuidB), sha256('beta again'));
+});
+
+test('a contest ends when its ground leaves: the open channel resumes ordinary continuity', () => {
+  const kit = makeKit('contest-moves');
+  kit.write('a.txt', 'alpha');
+  kit.write('b.txt', 'beta');
+  kit.enroll();
+  let snap = kit.point();
+  const uuidA = snap.files.get('a.txt').uuid;
+  const uuidB = snap.files.get('b.txt').uuid;
+  const channelA = fileIdAt(kit, 'a.txt');
+  kit.rm('b.txt');
+  kit.point();
+  kit.mv('a.txt', 'b.txt');
+  snap = kit.point();
+  assert.equal(snap.divergent.get('b.txt'), sha256('alpha'));
+
+  // The contested ground moves on to UNOWNED ground: the contest dissolves
+  // — its ground left the owned address — and the still-open channel's
+  // continuity simply resumes. One entity finally moves, and no contested
+  // question was ever answered by guessing.
+  kit.mv('b.txt', 'c.txt');
+  snap = kit.point();
+  assert.equal(snap.divergent.size, 0);
+  assert.equal(snap.files.get('c.txt').uuid, uuidA, 'continuity resumes on unowned ground');
+  assert.equal(fileIdAt(kit, 'c.txt'), channelA, 'the same channel carried it the whole way');
+  assert.equal(snap.records.find((r) => r.uuid === uuidB).name, 'b.txt',
+    'the slot\'s owner is untouched throughout');
+});
+
+test('a re-grounded claimant\'s surplus channel stays divergence wherever its ground goes', () => {
+  const kit = makeKit('contest-surplus');
+  kit.write('a.txt', 'alpha');
+  kit.write('b.txt', 'beta');
+  kit.enroll();
+  let snap = kit.point();
+  const uuidA = snap.files.get('a.txt').uuid;
+  const uuidB = snap.files.get('b.txt').uuid;
+  kit.rm('b.txt');
+  kit.point();
+  kit.mv('a.txt', 'b.txt');
+  kit.point();
+  kit.write('a.txt', 'returned');
+  snap = kit.point();
+  assert.equal(snap.divergent.get('b.txt'), sha256('alpha'));
+
+  // The claimant already holds canonical ground at home, so when the
+  // contested ground moves — even onto an UNOWNED address — its channel is
+  // surplus evidence: only one channel may stand as canonical ground, so
+  // the ground stays divergence, following the physical file.
+  kit.mv('b.txt', 'c.txt');
+  snap = kit.point();
+  assert.ok(!snap.divergent.has('b.txt'), 'the owned address is contested no longer');
+  assert.equal(snap.divergent.get('c.txt'), sha256('alpha'),
+    'the surplus channel\'s ground is divergence wherever it sits');
+  assert.ok(!snap.files.has('c.txt'), 'no entity claims it');
+  assert.equal(snap.files.get('a.txt').uuid, uuidA, 'the claimant keeps its canonical ground');
+  assert.equal(snap.records.find((r) => r.uuid === uuidB).name, 'b.txt',
+    'the old slot owner is untouched');
+
+  // The surplus ground leaving closes its channel and ends the divergence;
+  // genuinely fresh ground at that address is then an ordinary birth.
+  kit.rm('c.txt');
+  snap = kit.point();
+  assert.equal(snap.divergent.size, 0);
+  kit.write('c.txt', 'fresh');
+  snap = kit.point();
+  const bornUuid = snap.files.get('c.txt').uuid;
+  assert.ok(bornUuid !== uuidA && bornUuid !== uuidB,
+    'unmarked, unowned ground births a new entity — divergence never resolves by default');
+});
+
+test('an active entity owns its slot across kinds: valid type transitions ride one uuid', () => {
+  const kit = makeKit('slot-kind');
+  kit.write('shed/tool.txt', 'tool bytes');
+  kit.write('keep.md', 'bystander');
+  kit.enroll();
+  let snap = kit.point();
+  const toolUuid = snap.files.get('shed/tool.txt').uuid;
+  const wsBefore = JSON.stringify(snap.records.find((r) => r.parentUUID === null));
+
+  // The FILE departs; its active record keeps the (shed, "tool.txt") slot.
+  // FOLDER ground lands on it: ownership is identity, not kind, so this is
+  // the same entity changing type (Axiom 1) — never a second claimant. A
+  // file → folder transition is ALWAYS valid: a file never holds children.
+  kit.rm('shed/tool.txt');
+  kit.point();
+  kit.mkdir('shed/tool.txt');
+  snap = kit.point();
+  const asFolder = snap.records.find((r) => r.uuid === toolUuid);
+  assert.equal(asFolder.type, 'folder',
+    'the slot owner reconnects across kinds — folder ground, same entity');
+  assert.equal(asFolder.status, 'active');
+
+  // And back — inside ONE interval this time. The folder is EMPTY (it
+  // never held an active child), so folder → file is a valid transition
+  // too: same uuid, file again, between two quiet points.
+  kit.rmDir('shed/tool.txt');
+  kit.write('shed/tool.txt', 'a file again');
+  snap = kit.point();
+  assert.equal(snap.files.get('shed/tool.txt').uuid, toolUuid,
+    'empty folder → file inside one interval still reconnects to the slot\'s owner');
+  assert.equal(snap.records.find((r) => r.uuid === toolUuid).type, 'file.text');
+  assert.equal(snap.payloads.get(toolUuid), sha256('a file again'));
+
+  // The workspace never noticed: the same uuids held the same slots
+  // through the whole journey, so the root record is byte-for-byte still.
+  assert.equal(JSON.stringify(snap.records.find((r) => r.parentUUID === null)), wsBefore,
+    'type transitions on a slot move nothing above it');
+});
+
+test('only containers hold active children: an occupied folder swapped for a file is divergence, not a transition', () => {
+  const kit = makeKit('container');
+  kit.write('den/cub.txt', 'cub');
+  kit.enroll();
+  let snap = kit.point();
+  const cubUuid = snap.files.get('den/cub.txt').uuid;
+  const denUuid = snap.records.find((r) => r.uuid === cubUuid).parentUUID;
+  const freeze = (s) => new Map(s.records.map((r) => [r.uuid, JSON.stringify(r)]));
+  const movedSince = (before, s) => s.records
+    .filter((r) => before.get(r.uuid) !== JSON.stringify(r))
+    .map((r) => r.uuid);
+  const before = freeze(snap);
+
+  // The folder AND its child are swapped for a file at the folder's slot.
+  // Accepting that flip would canonicalize the subtree destruction that
+  // explicit-only lifecycle refuses to infer — so NOT ONE record moves.
+  // The file is honest, entity-less divergence: its channel and events are
+  // real, no entity claims it, resolution is explicit (amalgm resets local
+  // from canonical, or the owner moves/trashes the children first).
+  kit.rmDir('den');
+  kit.write('den', 'impostor');
+  snap = kit.point();
+  assert.deepEqual(movedSince(before, snap), [],
+    'an invalid type transition moves nothing — the canonical graph refuses the swap');
+  assert.equal(snap.records.find((r) => r.uuid === denUuid).type, 'folder');
+  assert.equal(snap.records.find((r) => r.uuid === cubUuid).status, 'active');
+  assert.ok(!snap.files.has('den'), 'divergent ground is claimed by no entity');
+  assert.equal(snap.divergent.get('den'), sha256('impostor'),
+    'the divergence itself is reported evidence, never hidden');
+  assert.ok(kit.events.some((e) => e.type === 'file.created' && e.path === 'den'),
+    'detection reports what happened — the refusal is canonical, not observational');
+
+  // Divergence resolves when ground reverts: the impostor goes, the folder
+  // and child return with the same bytes — and across the ENTIRE ordeal
+  // not one record ever moved.
+  kit.rm('den');
+  kit.write('den/cub.txt', 'cub');
+  snap = kit.point();
+  assert.deepEqual(movedSince(before, snap), [],
+    'a refused swap plus a full local restore is zero canonical history');
+  assert.equal(snap.files.get('den/cub.txt').uuid, cubUuid);
+  assert.equal(snap.divergent.size, 0);
+});
+
+test('an ancestor rename touches its own record only — descendants stay silent', () => {
+  const kit = makeKit('silent');
+  kit.write('den/cub.txt', 'cub');
+  kit.write('den/deep/pup.txt', 'pup');
+  kit.enroll();
+  let snap = kit.point();
+  const cubUuid = snap.files.get('den/cub.txt').uuid;
+  const denUuid = snap.records.find((r) => r.uuid === cubUuid).parentUUID;
+  const denBefore = snap.records.find((r) => r.uuid === denUuid);
+  const denPayloadBefore = snap.payloads.get(denUuid);
+  const wsUuid = snap.records.find((r) => r.type === 'workspace').uuid;
+  const wsPayloadBefore = snap.payloads.get(wsUuid);
+  const cubBefore = snap.records.find((r) => r.uuid === cubUuid);
+  const deepBefore = snap.records.find((r) => r.type === 'folder' && r.name === 'deep');
+  const pupBefore = snap.records.find((r) => r.name === 'pup.txt');
+
+  kit.mvDir('den', 'lair');
+  snap = kit.point();
+  const lair = snap.records.find((r) => r.uuid === denUuid);
+  assert.equal(lair.name, 'lair');
+  assert.equal(snap.payloads.get(denUuid), denPayloadBefore,
+    'membership is (childUUID, name) pairs — unchanged by the parent\'s own rename');
+  assert.notEqual(lair.version, denBefore.version);
+  // The workspace membership DOES move: its pair (denUuid, name) changed.
+  assert.notEqual(snap.payloads.get(wsUuid), wsPayloadBefore);
+  // Every descendant record is byte-for-byte untouched.
+  assert.deepEqual(snap.records.find((r) => r.uuid === cubUuid), cubBefore,
+    'descendant records must not move when an ancestor renames');
+  assert.deepEqual(snap.records.find((r) => r.uuid === deepBefore.uuid), deepBefore);
+  assert.deepEqual(snap.records.find((r) => r.uuid === pupBefore.uuid), pupBefore);
+});
+
+// --- folder detection: directories are channels, folders are entities -----
+
+test('a folder is an entity: an empty directory is born, dies as evidence only, and reconnects on one uuid', () => {
+  const kit = makeKit('hollow');
+  kit.mkdir('hollow');
+  kit.enroll();
+  kit.point();
+  const rootUuid = kit.registry.roots()[0].uuid;
+  const hollow = kit.registry.activeAt(rootUuid, 'hollow');
+  assert.equal(hollow.type, 'folder', 'an empty directory is a folder entity the moment disk holds it');
+
+  // Disappearance is evidence: the channel closes, the record stays active.
+  kit.rmDir('hollow');
+  kit.point();
+  assert.equal(kit.registry.activeAt(rootUuid, 'hollow').uuid, hollow.uuid,
+    'the record keeps its slot while locally absent — lifecycle is explicit, never inferred');
+
+  kit.mkdir('hollow');
+  kit.point();
+  assert.equal(kit.registry.activeAt(rootUuid, 'hollow').uuid, hollow.uuid,
+    'reappearing dir ground reconnects to the absent owner — one entity, one uuid');
+  assert.equal(kit.events.filter((e) => e.type === 'dir.created').length, 2);
+  assert.equal(kit.events.filter((e) => e.type === 'dir.deleted').length, 1);
+});
+
+test('a folder rename is one recorded fact: same uuid, one commit, descendants silent in the registry too', () => {
+  const kit = makeKit('one-commit');
+  kit.write('docs/note.md', 'note');
+  kit.write('docs/deep/plan.md', 'plan');
+  kit.enroll();
+  kit.point();
+  const rootUuid = kit.registry.roots()[0].uuid;
+  const docs = kit.registry.activeAt(rootUuid, 'docs');
+  const deep = kit.registry.activeAt(docs.uuid, 'deep');
+  const note = kit.registry.activeAt(docs.uuid, 'note.md');
+
+  const mark = kit.regEvents.length;
+  kit.mvDir('docs', 'papers');
+  kit.point();
+  const committed = kit.regEvents.slice(mark).filter((event) => event.type === 'entity.committed');
+  assert.equal(committed.length, 1, 'a folder move is recorded once, on the folder\'s own record');
+  assert.equal(committed[0].record.uuid, docs.uuid);
+  const papers = kit.registry.activeAt(rootUuid, 'papers');
+  assert.equal(papers.uuid, docs.uuid, 'the directory channel carried the folder\'s identity by inode');
+  assert.equal(kit.registry.activeAt(papers.uuid, 'note.md').uuid, note.uuid);
+  assert.equal(kit.registry.activeAt(papers.uuid, 'deep').uuid, deep.uuid);
+});
+
+test('two directories exchange names: identity crosses by inode, exactly like the files inside them', () => {
+  const kit = makeKit('dir-swap');
+  kit.write('alpha/a.txt', 'in-alpha');
+  kit.write('beta/b.txt', 'in-beta');
+  kit.enroll();
+  kit.point();
+  const rootUuid = kit.registry.roots()[0].uuid;
+  const alpha = kit.registry.activeAt(rootUuid, 'alpha');
+  const beta = kit.registry.activeAt(rootUuid, 'beta');
+  const fileA = kit.registry.activeAt(alpha.uuid, 'a.txt');
+
+  // The swap crosses between two scans; detection sees only the endpoints.
+  const mark = kit.regEvents.length;
+  kit.mvDir('alpha', 'limbo');
+  kit.mvDir('beta', 'alpha');
+  kit.mvDir('limbo', 'beta');
+  const snap = kit.point();
+  assert.equal(snap.divergent.size, 0, 'an exchange is continuity, never contest');
+  assert.equal(kit.registry.activeAt(rootUuid, 'beta').uuid, alpha.uuid,
+    'the directory once named alpha is the entity now named beta');
+  assert.equal(kit.registry.activeAt(rootUuid, 'alpha').uuid, beta.uuid,
+    'the directory once named beta is the entity now named alpha');
+  assert.equal(kit.registry.activeAt(alpha.uuid, 'a.txt').uuid, fileA.uuid,
+    'the file rode its physical parent across the exchange');
+  const committed = kit.regEvents.slice(mark).filter((event) => event.type === 'entity.committed');
+  assert.equal(committed.length, 2, 'an exchange is two recorded facts — one per folder, descendants silent');
+});
+
+test('a directory replacing a vanished one is a contest, never an inheritance', () => {
+  const kit = makeKit('dir-replace');
+  kit.mkdir('a');
+  kit.mkdir('b');
+  kit.enroll();
+  kit.point();
+  const rootUuid = kit.registry.roots()[0].uuid;
+  const dirA = kit.registry.activeAt(rootUuid, 'a');
+  const dirB = kit.registry.activeAt(rootUuid, 'b');
+
+  // One interval: b's ground vanishes AND a moves onto its name. The owner
+  // parks in the very settle the mover arrives — still a parked ACTIVE
+  // owner, still two identity claims on one address.
+  kit.rmDir('b');
+  kit.mvDir('a', 'b');
+  let snap = kit.point();
+  assert.deepEqual([...snap.divergent], [['b', null]],
+    'the moved directory is divergence on the vanished owner\'s slot');
+  assert.equal(kit.registry.activeAt(rootUuid, 'a').uuid, dirA.uuid, 'the mover\'s record did not move');
+  assert.equal(kit.registry.activeAt(rootUuid, 'b').uuid, dirB.uuid, 'the vanished owner keeps its slot');
+
+  kit.mvDir('b', 'c'); // the ground leaves the contested address: resolution
+  snap = kit.point();
+  assert.equal(snap.divergent.size, 0, 'the contest ended when its ground left');
+  assert.equal(kit.registry.activeAt(rootUuid, 'c').uuid, dirA.uuid,
+    'the mover\'s never-closed channel resumed ordinary continuity');
+  assert.equal(kit.registry.activeAt(rootUuid, 'b').uuid, dirB.uuid,
+    'the owner still owns its slot, parked and untouched');
+});
+
+test('folder ↔ repo.git rides one uuid: the dir channel yields to territory and returns', () => {
+  const kit = makeKit('lens-uuid');
+  kit.write('pkg/lib.md', 'lib');
+  kit.enroll();
+  kit.point();
+  const rootUuid = kit.registry.roots()[0].uuid;
+  const pkg = kit.registry.activeAt(rootUuid, 'pkg');
+  assert.equal(pkg.type, 'folder');
+
+  kit.gitInit('pkg');
+  kit.point();
+  const asRepo = kit.registry.activeAt(rootUuid, 'pkg');
+  assert.equal(asRepo.uuid, pkg.uuid, 'the boundary is a type transition, never a new entity');
+  assert.equal(asRepo.type, 'repo.git');
+  assert.equal(kit.observer.dirsForRoot(kit.rootId).length, 0,
+    'territory ground carries no dir channel — one adapter owns detection at a time');
+
+  kit.gitRemove('pkg');
+  kit.point();
+  const back = kit.registry.activeAt(rootUuid, 'pkg');
+  assert.equal(back.uuid, pkg.uuid, 'lifting the lens returns the folder on the same uuid');
+  assert.equal(back.type, 'folder');
+});
+
+test('contested folder ground: a moved directory onto a parked owner\'s slot is divergence, subtree included', () => {
+  const kit = makeKit('dir-contest');
+  kit.mkdir('a');
+  kit.write('b/f.txt', 'bravo');
+  kit.enroll();
+  kit.point();
+  const rootUuid = kit.registry.roots()[0].uuid;
+  const ownerA = kit.registry.activeAt(rootUuid, 'a');
+  const claimB = kit.registry.activeAt(rootUuid, 'b');
+  const fileF = kit.registry.activeAt(claimB.uuid, 'f.txt');
+
+  kit.rmDir('a'); // the owner's ground leaves; its record parks, active
+  kit.point();
+
+  kit.mvDir('b', 'a'); // dir continuity arrives on the parked owner's slot
+  let snap = kit.point();
+  assert.deepEqual([...snap.divergent].sort(), [['a', null], ['a/f.txt', sha256('bravo')]],
+    'the contest covers the moved subtree: dir ground with null bytes, file ground with its own');
+  assert.equal(kit.registry.activeAt(rootUuid, 'a').uuid, ownerA.uuid, 'the owner\'s record did not move');
+  assert.equal(kit.registry.activeAt(rootUuid, 'b').uuid, claimB.uuid, 'the claimant\'s record did not move');
+  assert.equal(kit.registry.activeAt(claimB.uuid, 'f.txt').uuid, fileF.uuid, 'the subtree\'s records did not move');
+
+  kit.mvDir('a', 'c'); // the ground leaves the contested address: resolution
+  snap = kit.point();
+  assert.equal(snap.divergent.size, 0, 'the contest ended when its ground left');
+  assert.equal(kit.registry.activeAt(rootUuid, 'c').uuid, claimB.uuid,
+    'the claimant\'s never-closed channel resumed ordinary continuity');
+  assert.equal(kit.registry.activeAt(claimB.uuid, 'f.txt').uuid, fileF.uuid);
+  assert.equal(kit.registry.activeAt(rootUuid, 'a').uuid, ownerA.uuid,
+    'the owner still owns its slot, parked and untouched');
+});
+
+test('a contest is kind-strict: file ground swapped for a directory has left, and the owner reconnects across kinds', () => {
+  const kit = makeKit('kind-swap');
+  kit.write('a.txt', 'alpha');
+  kit.write('b.txt', 'beta');
+  kit.enroll();
+  kit.point();
+  const rootUuid = kit.registry.roots()[0].uuid;
+  const ownerB = kit.registry.activeAt(rootUuid, 'b.txt');
+
+  kit.rm('b.txt');
+  kit.point();
+  kit.mv('a.txt', 'b.txt'); // the claimant's channel lands on the owner's slot
+  let snap = kit.point();
+  assert.equal(snap.divergent.get('b.txt'), sha256('alpha'));
+
+  // In one interval the contested FILE leaves and a DIRECTORY lands on the
+  // same address. A contest carries by address continuity within its kind:
+  // ground of the mark's kind is gone, so the contest is over — and the
+  // arriving dir ground reconnects to the slot's owner across kinds,
+  // because ownership is identity, not kind.
+  kit.rm('b.txt');
+  kit.mkdir('b.txt');
+  snap = kit.point();
+  assert.equal(snap.divergent.size, 0, 'a file mark does not carry on dir ground');
+  const back = kit.registry.activeAt(rootUuid, 'b.txt');
+  assert.equal(back.uuid, ownerB.uuid, 'the owner returned as a folder on its own uuid');
+  assert.equal(back.type, 'folder');
+});
+
+test('event-only: a folder rename through doorbells alone — identity preserved with no manual scan', async () => {
+  const bells = fakeWatchKit();
+  const kit = makeKit('dir-doorbell', { watch: bells.watch, settleMs: 1 });
+  kit.write('den/cub.md', 'cub');
+  kit.mkdir('den/empty');
+  kit.enroll();
+  kit.point();
+  kit.observer.start();
+  try {
+    const rootUuid = kit.registry.roots()[0].uuid;
+    const den = kit.registry.activeAt(rootUuid, 'den');
+    const empty = kit.registry.activeAt(den.uuid, 'empty');
+
+    kit.mvDir('den', 'burrow');
+    await converged(kit, () => bells.ring(kit.dir, 'den'));
+    kit.point({ scan: false });
+    assert.equal(kit.registry.activeAt(rootUuid, 'burrow').uuid, den.uuid,
+      'the doorbell-driven scan carried the folder identity by inode');
+    assert.equal(kit.registry.activeAt(den.uuid, 'empty').uuid, empty.uuid,
+      'the empty child folder rode its parent\'s move without its own record moving');
+  } finally {
+    kit.observer.stop();
+  }
+});
+
+// --- link detection: a pointer is leaf ground; its payload is its written address ---
+
+test('link grammar converges: birth, retarget, rename, silent recreation, name exchange, death and reconnection', () => {
+  const kit = makeKit('links');
+  kit.write('real.md', 'real bytes');
+  kit.symlink('ln.md', 'real.md');
+  kit.symlink('ghost.md', 'nowhere/said-so'); // dangling is honest ground
+  kit.enroll();
+  let snap = kit.point();
+  const uuid = snap.links.get('ln.md').uuid;
+  assert.equal(snap.payloads.get(uuid), 'real.md', 'the payload is the pointer exactly as written');
+
+  // Retarget IS unlink + recreate under a standing address — the address
+  // absorbs the churn; channel and entity both continue.
+  const channel = linkIdAt(kit, 'ln.md');
+  kit.retarget('ln.md', 'ghost.md');
+  snap = kit.point();
+  assert.equal(snap.links.get('ln.md').uuid, uuid);
+  assert.equal(linkIdAt(kit, 'ln.md'), channel, 'retarget continues the channel: the address claims first');
+  assert.equal(snap.payloads.get(uuid), 'ghost.md');
+
+  // Rename: mv preserves a symlink's inode; exactly-one continuity rescues.
+  kit.mvLink('ln.md', 'renamed.md');
+  snap = kit.point();
+  assert.equal(snap.links.get('renamed.md').uuid, uuid);
+  assert.equal(linkIdAt(kit, 'renamed.md'), channel);
+
+  // Silent recreation: a new inode under an old name with an old target.
+  const quiet = kit.events.length;
+  kit.retarget('renamed.md', 'ghost.md');
+  snap = kit.point();
+  assert.equal(kit.events.slice(quiet).filter((e) => e.type.startsWith('link.')).length, 0,
+    'an equal pointer is silence');
+  assert.equal(snap.links.get('renamed.md').uuid, uuid);
+
+  // Two links exchanging names read as two retargets: a link's meaning IS
+  // its written address, so the path claims first and nobody crosses.
+  const ghostUuid = snap.links.get('ghost.md').uuid;
+  const preSwap = kit.events.length;
+  kit.mvLink('renamed.md', 'swap-tmp');
+  kit.mvLink('ghost.md', 'renamed.md');
+  kit.mvLink('swap-tmp', 'ghost.md');
+  snap = kit.point();
+  const swapSpeech = kit.events.slice(preSwap).filter((e) => e.type.startsWith('link.'));
+  assert.deepEqual(swapSpeech.map((e) => e.type).sort(), ['link.changed', 'link.changed']);
+  assert.equal(snap.links.get('renamed.md').uuid, uuid, 'each address kept its entity');
+  assert.equal(snap.links.get('ghost.md').uuid, ghostUuid);
+  assert.equal(snap.payloads.get(uuid), 'nowhere/said-so');
+  assert.equal(snap.payloads.get(ghostUuid), 'ghost.md');
+
+  // A settled disappearance closes the channel; the record moves not one
+  // field, and returning pointer ground reconnects to the slot's owner.
+  kit.rmLink('ghost.md');
+  snap = kit.point();
+  assert.equal(snap.records.find((r) => r.uuid === ghostUuid).status, 'active');
+  assert.ok(!snap.links.has('ghost.md'));
+  kit.symlink('ghost.md', 'reborn-target');
+  snap = kit.point();
+  assert.equal(snap.links.get('ghost.md').uuid, ghostUuid,
+    'reappearing pointer ground reconnects to the active owner of the slot');
+  assert.equal(snap.payloads.get(ghostUuid), 'reborn-target');
+});
+
+test('a slot crosses kinds on one uuid: file → link → file is a type transition, never a second entity', () => {
+  const kit = makeKit('link-kinds');
+  kit.write('spot.md', 'file bytes');
+  kit.write('keep.md', 'bystander');
+  kit.enroll();
+  let snap = kit.point();
+  const uuid = snap.files.get('spot.md').uuid;
+
+  // The file leaves and a pointer lands on its slot inside one interval:
+  // ownership is identity, not kind.
+  kit.rm('spot.md');
+  kit.symlink('spot.md', 'keep.md');
+  snap = kit.point();
+  assert.equal(snap.links.get('spot.md').uuid, uuid, 'the slot owner returns as link ground on its own uuid');
+  assert.equal(snap.records.find((r) => r.uuid === uuid).type, 'link');
+  assert.equal(snap.payloads.get(uuid), 'keep.md');
+
+  // And back — across a settle this time.
+  kit.rmLink('spot.md');
+  kit.point();
+  kit.write('spot.md', 'a file again');
+  snap = kit.point();
+  assert.equal(snap.files.get('spot.md').uuid, uuid);
+  assert.equal(snap.records.find((r) => r.uuid === uuid).type, 'file.text');
+});
+
+test('links ride the git lens: covered ground closes the channel, the entity persists, the lift re-exposes it', () => {
+  const kit = makeKit('link-lens');
+  kit.write('pkg/lib.md', 'lib');
+  kit.symlink('pkg/ptr.md', 'lib.md');
+  kit.enroll();
+  let snap = kit.point();
+  const uuid = snap.links.get('pkg/ptr.md').uuid;
+  const channel = linkIdAt(kit, 'pkg/ptr.md');
+
+  kit.gitInit('pkg');
+  snap = kit.point();
+  assert.ok(!snap.links.has('pkg/ptr.md'), 'covered ground leaves the exposed slice');
+  assert.equal(snap.records.find((r) => r.uuid === uuid).status, 'active',
+    'the entity under the lens keeps existing');
+  assert.ok(kit.events.some((e) => e.type === 'link.deleted' && e.linkId === channel),
+    'the channel closes when the repo adapter takes ownership');
+
+  kit.gitRemove('pkg');
+  snap = kit.point();
+  assert.equal(snap.links.get('pkg/ptr.md').uuid, uuid, 'the lens lifts: same entity, fresh channel');
+  assert.notEqual(linkIdAt(kit, 'pkg/ptr.md'), channel);
+});
+
+test('the injected path-dependent policy decides enrollment — not names, not conventions', () => {
+  // Deliberately path-dependent: `pkg/private` is excluded ground while
+  // `other/private` enrolls. A name-based policy would treat them alike.
+  const policy = (rel) => defaultPolicy(rel) && rel !== 'pkg/private' && !rel.startsWith('pkg/private/');
+  const kit = makeKit('policy', { policy });
+  kit.write('keep.md', 'kept');
+  kit.write('pkg/private/hidden.md', 'never an entity');
+  kit.write('other/private/seen.md', 'an entity');
+  kit.enroll();
+  kit.point();
+
+  const paths = kit.observer.filesForRoot(kit.rootId).map((r) => r.relPath).sort();
+  assert.deepEqual(paths, ['keep.md', 'other/private/seen.md']);
+
+  // Live ops on excluded ground stay invisible; enrolled ground converges.
+  kit.write('pkg/private/more.md', 'still not an entity');
+  kit.write('keep.md', 'kept v2');
+  kit.point();
+});
+
+test('git is a lens: the folder transitions in place, entities persist beneath it, channels are re-minted evidence', () => {
+  const kit = makeKit('territory');
+  kit.write('top.md', 'top');
+  kit.write('lib/tool.md', 'tool v1');
+  kit.enroll();
+  let snap = kit.point();
+  const closedId = fileIdAt(kit, 'lib/tool.md');
+  const toolUuid = snap.files.get('lib/tool.md').uuid;
+  const libUuid = snap.records.find((r) => r.uuid === toolUuid).parentUUID;
+  assert.equal(snap.records.find((r) => r.uuid === libUuid).type, 'folder');
+
+  // A .git appears: the SAME folder entity becomes the repo (a type flip on
+  // one uuid), the file entities beneath it keep existing — only their
+  // detector channels close — and the census sees exactly one boundary.
+  kit.gitInit('lib');
+  snap = kit.point();
+  assert.ok(kit.events.some((e) => e.type === 'repo.discovered' && e.path === kit.abs('lib')));
+  assert.ok(kit.events.some((e) => e.type === 'file.deleted' && e.fileId === closedId));
+  const libAsRepo = snap.records.find((r) => r.uuid === libUuid);
+  assert.equal(libAsRepo.type, 'repo.git', 'the folder becomes the repo — same entity, new type');
+  assert.equal(libAsRepo.status, 'active');
+  assert.equal(snap.records.find((r) => r.uuid === toolUuid).status, 'active',
+    'entities under the lens keep existing');
+  assert.ok(!snap.files.has('lib/tool.md'), 'covered ground leaves the exposed slice');
+
+  // Writes inside the lens are the follower's business, never file events —
+  // and covered ground is UNWITNESSED by leaf detection: no leaf entity is
+  // born under the lens (the repo adapter owns that ground's meaning).
+  const preInner = kit.events.length;
+  kit.write('lib/inner.md', 'born under the lens');
+  snap = kit.point();
+  assert.equal(kit.events.slice(preInner).filter((e) => e.type.startsWith('file.')).length, 0,
+    'repo territory must never leak file events');
+  assert.ok(!snap.records.some((r) => r.name === 'inner.md'),
+    'ground first written under the lens is nobody until it surfaces');
+
+  // The .git vanishes: the lens lifts and the SAME entities are exposed
+  // again — the slot law reconnects each parked owner — while the detector
+  // re-mints its channels, and ground first written under the lens
+  // surfaces as a NEW entity at the lift.
+  kit.gitRemove('lib');
+  snap = kit.point();
+  assert.ok(kit.events.some((e) => e.type === 'repo.removed' && e.path === kit.abs('lib')));
+  assert.equal(snap.records.find((r) => r.uuid === libUuid).type, 'folder',
+    'the lens lifts: same entity, folder again');
+  assert.equal(snap.files.get('lib/tool.md').uuid, toolUuid,
+    'the file entity survived the whole journey under the lens');
+  assert.ok(snap.files.get('lib/inner.md'),
+    'ground born under the lens surfaces as an entity when the lens lifts');
+  assert.notEqual(fileIdAt(kit, 'lib/tool.md'), closedId,
+    'the reclaimed CHANNEL is fresh — evidence is re-minted even though the entity persisted');
+});
+
+test('a git repository is a git repository — including at the enrolled root: same uuid under and after the lens', () => {
+  const kit = makeKit('root-lens');
+  kit.write('a.md', 'alpha');
+  kit.write('sub/b.md', 'beta');
+  kit.enroll();
+  let snap = kit.point();
+  const rootRecord = snap.records.find((r) => r.parentUUID === null);
+  assert.equal(rootRecord.type, 'workspace');
+  const aUuid = snap.files.get('a.md').uuid;
+  const bUuid = snap.files.get('sub/b.md').uuid;
+  const aChannel = fileIdAt(kit, 'a.md');
+
+  // A .git lands at the enrolled root: the SAME root record becomes the
+  // repo — no separate workspace-versus-repository problem — and exactly
+  // one adapter owns detection: the repo owns everything, so the exposed
+  // file slice is empty while every entity beneath persists.
+  kit.gitInit('');
+  snap = kit.point();
+  assert.equal(snap.records.find((r) => r.uuid === rootRecord.uuid).type, 'repo.git',
+    'the root transitions in place on its own uuid');
+  assert.equal(snap.files.size, 0, 'under a root lens the repo adapter owns everything');
+  assert.ok(kit.events.some((e) => e.type === 'repo.discovered' && e.path === kit.dir));
+  assert.ok(kit.events.some((e) => e.type === 'file.deleted' && e.fileId === aChannel),
+    'file channels close when the repo adapter takes ownership');
+  assert.equal(snap.records.find((r) => r.uuid === aUuid).status, 'active');
+  assert.equal(snap.records.find((r) => r.uuid === bUuid).status, 'active');
+
+  // The .git goes: the same root uuid is the workspace again, file
+  // detection returns, and the same entities are exposed on fresh channels.
+  kit.gitRemove('');
+  snap = kit.point();
+  assert.equal(snap.records.find((r) => r.uuid === rootRecord.uuid).type, 'workspace',
+    'the lens lifts: same root entity, workspace again');
+  assert.equal(snap.files.get('a.md').uuid, aUuid);
+  assert.equal(snap.files.get('sub/b.md').uuid, bUuid);
+  assert.notEqual(fileIdAt(kit, 'a.md'), aChannel,
+    'channels are re-minted evidence; identity never moves');
+});
+
+test('a doorbell-named, backdated, same-size edit is caught — timestamps can lie, doorbells cannot', async () => {
+  const bells = fakeWatchKit();
+  const kit = makeKit('backdate', { watch: bells.watch, settleMs: 1 });
+  kit.write('f.md', 'aaaa');
+  // Pin the mtime to a SECOND-ALIGNED past instant: whole seconds survive
+  // the utimes float conversion exactly, so the forged restore below is
+  // deterministic (a millisecond value can shift by 1ms in the round-trip).
+  const pinned = new Date(Math.floor(Date.now() / 1000) * 1000 - 10_000);
+  fs.utimesSync(kit.abs('f.md'), pinned, pinned);
+  kit.enroll();
+  kit.point();
+  kit.observer.start();
+  try {
+    const row = kit.observer.filesForRoot(kit.rootId)[0];
+    assert.equal(row.mtimeMs, pinned.getTime(),
+      'a second-aligned pin must survive the stat round-trip exactly');
+
+    // Same size, same inode, mtime restored to the pinned value: to stats,
+    // nothing happened.
+    fs.writeFileSync(kit.abs('f.md'), 'bbbb');
+    kit.model.write('f.md', 'bbbb');
+    fs.utimesSync(kit.abs('f.md'), pinned, pinned);
+    assert.equal(Math.floor(fs.statSync(kit.abs('f.md')).mtimeMs), row.mtimeMs,
+      'the disguise must be exact for this test to prove anything');
+
+    // The honest boundary: without a doorbell, stats hide this edit.
+    const blind = kit.events.length;
+    kit.observer.scanNow(kit.rootId);
+    assert.equal(kit.events.length, blind, 'a perfect stat disguise defeats an unnamed scan');
+
+    // A delivered doorbell names the file; named files are always hashed.
+    await converged(kit, () => bells.ring(kit.dir, 'f.md'));
+    assert.ok(kit.events.slice(blind).some(
+      (e) => e.type === 'file.changed' && e.hash === sha256('bbbb')),
+    'the named doorbell must overrule the stat disguise');
+
+    kit.point();
+  } finally {
+    kit.observer.stop();
+  }
+});
+
+test('event-only: doorbells alone converge the detector — no manual scan after start()', async () => {
+  const bells = fakeWatchKit();
+  const kit = makeKit('event-only', { watch: bells.watch, settleMs: 1 });
+  kit.write('seed.md', 'seed');
+  kit.enroll();
+  kit.point(); // the catch-up era ends here
+  kit.observer.start();
+  try {
+    // From now on: rings through production wiring only, never a manual
+    // scan. The verdict runs in { scan: false } mode — the referee stays
+    // read-only, so a detector that needed help would be convicted stale.
+    const ring = (...names) => converged(kit, () => {
+      for (const name of names) bells.ring(kit.dir, name);
+    });
+
+    kit.write('live.md', 'v1');
+    await ring('live.md');
+    kit.point({ scan: false });
+
+    kit.write('live.md', 'v2 with more bytes');
+    await ring('live.md');
+    kit.point({ scan: false });
+
+    const liveId = fileIdAt(kit, 'live.md');
+    kit.mv('live.md', 'docs/live.md');
+    await ring('live.md', 'docs', 'docs/live.md');
+    kit.point({ scan: false });
+    assert.equal(fileIdAt(kit, 'docs/live.md'), liveId,
+      'an event-driven move must preserve identity');
+
+    kit.replace('docs/live.md', 'v3 atomically');
+    await ring('docs/live.md');
+    kit.point({ scan: false });
+
+    kit.rm('seed.md');
+    await ring('seed.md');
+    kit.point({ scan: false });
+
+    // A settled event-only detector says nothing more.
+    const settled = kit.events.length;
+    await sleep(100);
+    assert.equal(kit.events.length, settled,
+      'no timer, no scan, no doorbell — silence must hold');
+  } finally {
+    kit.observer.stop();
+  }
+});
+
+// --- the judge must convict when fed lies ---------------------------------
+
+test('the judge convicts a stale detector', () => {
+  const kit = makeKit('convict-stale');
+  kit.write('f.md', 'v1');
+  kit.enroll();
+  kit.point();
+
+  // Disk moves, detection is never given a chance: the referee must object.
+  fs.writeFileSync(kit.abs('f.md'), 'v2');
+  kit.model.write('f.md', 'v2');
+  assert.throws(() => kit.point({ scan: false }), /stale/);
+});
+
+test('the judge convicts a ghost believer', () => {
+  const kit = makeKit('convict-ghost');
+  kit.write('f.md', 'v1');
+  kit.enroll();
+  kit.point();
+
+  fs.rmSync(kit.abs('f.md'));
+  kit.model.remove('f.md');
+  assert.throws(() => kit.point({ scan: false }), /ghost/);
+});
+
+test('the judge convicts a stale link detector', () => {
+  const kit = makeKit('convict-stale-link');
+  kit.symlink('ln.md', 'v1-target');
+  kit.enroll();
+  kit.point();
+
+  // The pointer moves, detection is never given a chance.
+  fs.rmSync(kit.abs('ln.md'));
+  fs.symlinkSync('v2-target', kit.abs('ln.md'));
+  kit.model.writeLink('ln.md', 'v2-target');
+  assert.throws(() => kit.point({ scan: false }), /stale at link/);
+});
+
+test('a link channel may not claim a target never written', () => {
+  const kit = makeKit('convict-link-truth');
+  kit.symlink('ln.md', 'true-target');
+  kit.write('base.md', 'bytes');
+  kit.enroll();
+  kit.point();
+
+  // A forged round trip: the chain holds and the store still matches, so
+  // only per-entity emitted-truth can convict it.
+  const channel = linkIdAt(kit, 'ln.md');
+  kit.events.push(
+    {
+      type: 'link.changed', rootId: kit.rootId, linkId: channel, path: 'ln.md',
+      target: 'forged', previousTarget: 'true-target',
+    },
+    {
+      type: 'link.changed', rootId: kit.rootId, linkId: channel, path: 'ln.md',
+      target: 'true-target', previousTarget: 'forged',
+    },
+  );
+  assert.throws(() => kit.point(), /never written for that entity/);
+});
+
+test('the judge convicts its own drifting model — the two truths cross-check', () => {
+  const kit = makeKit('convict-model');
+  kit.write('f.md', 'v1');
+  kit.enroll();
+  kit.point();
+
+  // A file appears that the operation model never recorded: the referee
+  // must refuse to bless the run even though the detector saw it fine.
+  fs.writeFileSync(kit.abs('unrecorded.md'), 'the model never heard of me');
+  assert.throws(() => kit.point(), /model missing/);
+});
+
+test('the judge convicts a version claimed for the wrong channel', () => {
+  const kit = makeKit('convict-channel');
+  kit.write('a.md', 'alpha');
+  kit.write('b.md', 'beta');
+  kit.enroll();
+  kit.point();
+
+  // Forge a round trip: B claims hash(alpha) — true for A, never for B —
+  // then claims its real hash back. The ledger chain holds and the store
+  // still matches, so ONLY per-entity truth can convict this.
+  const bId = fileIdAt(kit, 'b.md');
+  kit.events.push(
+    {
+      type: 'file.changed', rootId: kit.rootId, fileId: bId, path: 'b.md',
+      hash: sha256('alpha'), previousHash: sha256('beta'),
+    },
+    {
+      type: 'file.changed', rootId: kit.rootId, fileId: bId, path: 'b.md',
+      hash: sha256('beta'), previousHash: sha256('alpha'),
+    },
+  );
+  assert.throws(() => kit.point(), /never true for that entity/);
+});
+
+test('a short-lived channel may not lie either: transients are judged at their address', async () => {
+  const bells = fakeWatchKit();
+  const kit = makeKit('convict-transient', { watch: bells.watch, settleMs: 1 });
+  kit.write('long.md', 'longlived');
+  kit.enroll();
+  kit.point();
+  kit.observer.start();
+  try {
+    const ring = (name) => converged(kit, () => bells.ring(kit.dir, name));
+
+    // Control: a channel born and dead inside one interval, telling the
+    // truth, passes — its address vouches for every version it claimed.
+    kit.write('honest.md', 'true words');
+    await ring('honest.md');
+    kit.rm('honest.md');
+    await ring('honest.md');
+    kit.point({ scan: false });
+
+    // A transient claiming a hash that was never true AT ITS ADDRESS —
+    // only ever true for the long-lived neighbor — must be convicted, even
+    // though it never settles and so never binds to an entity.
+    kit.write('flash.md', 'flash truth');
+    await ring('flash.md');
+    const flashId = fileIdAt(kit, 'flash.md');
+    kit.events.push(
+      {
+        type: 'file.changed', rootId: kit.rootId, fileId: flashId, path: 'flash.md',
+        hash: sha256('longlived'), previousHash: sha256('flash truth'),
+      },
+      {
+        type: 'file.changed', rootId: kit.rootId, fileId: flashId, path: 'flash.md',
+        hash: sha256('flash truth'), previousHash: sha256('longlived'),
+      },
+    );
+    kit.rm('flash.md');
+    await ring('flash.md');
+    assert.throws(() => kit.point({ scan: false }), /never true at that address/);
+  } finally {
+    kit.observer.stop();
+  }
+});
+
+test('address history is no alibi for a bound channel: only its contested ground answers there', async () => {
+  const bells = fakeWatchKit();
+  const kit = makeKit('convict-waypoint', { watch: bells.watch, settleMs: 1 });
+  kit.write('a.md', 'alpha');
+  kit.enroll();
+  kit.point();
+  kit.observer.start();
+  try {
+    const ring = (...names) => converged(kit, () => {
+      for (const name of names) bells.ring(kit.dir, name);
+    });
+
+    // Foreign bytes genuinely occupy way.md this interval: a transient
+    // tenant arrives and leaves without ever settling into an entity.
+    kit.write('way.md', 'foreign tenure');
+    await ring('way.md');
+    kit.rm('way.md');
+    await ring('way.md');
+
+    // The entity's channel then passes THROUGH way.md on its way to z.md —
+    // an honest multi-hop move. While parked there, a forged round trip
+    // claims it cycled through the dead tenant's bytes: true AT the
+    // address this interval, never true for THIS entity. The ledger chain
+    // holds and the store ends up matching, and the address is not
+    // contested ground — so an address escape for bound channels would
+    // swallow the lie whole. Only per-entity truth convicts it.
+    const aId = fileIdAt(kit, 'a.md');
+    kit.mv('a.md', 'way.md');
+    await ring('a.md', 'way.md');
+    kit.events.push(
+      {
+        type: 'file.changed', rootId: kit.rootId, fileId: aId, path: 'way.md',
+        hash: sha256('foreign tenure'), previousHash: sha256('alpha'),
+      },
+      {
+        type: 'file.changed', rootId: kit.rootId, fileId: aId, path: 'way.md',
+        hash: sha256('alpha'), previousHash: sha256('foreign tenure'),
+      },
+    );
+    kit.mv('way.md', 'z.md');
+    await ring('way.md', 'z.md');
+    assert.throws(() => kit.point({ scan: false }), /never true for that entity/);
+  } finally {
+    kit.observer.stop();
+  }
+});
+
+test('an honest edit on contested ground answers with the boundary it fired under, even after the ground moves', async () => {
+  const bells = fakeWatchKit();
+  const kit = makeKit('contest-boundary', { watch: bells.watch, settleMs: 1 });
+  kit.write('a.txt', 'alpha');
+  kit.write('b.txt', 'beta');
+  kit.enroll();
+  kit.point();
+  kit.observer.start();
+  try {
+    const ring = (...names) => converged(kit, () => {
+      for (const name of names) bells.ring(kit.dir, name);
+    });
+
+    // The surplus arc, event-driven: the owner parks, the claimant's
+    // ground lands on its slot, and fresh ground re-grounds the claimant
+    // at home — its contested channel is now surplus evidence.
+    kit.rm('b.txt');
+    await ring('b.txt');
+    kit.point({ scan: false });
+    kit.mv('a.txt', 'b.txt');
+    await ring('a.txt', 'b.txt');
+    kit.point({ scan: false });
+    kit.write('a.txt', 'returned');
+    await ring('a.txt');
+    let snap = kit.point({ scan: false });
+    assert.equal(snap.divergent.get('b.txt'), sha256('alpha'));
+
+    // ONE interval: an honest edit at contested b.txt, then the ground
+    // moves on to c.txt. At the settle the contest sits at c.txt — but the
+    // change event fired at b.txt, under the OPENING boundary's contest. A
+    // judge reading only the closing snapshot would falsely convict the
+    // honest event it just watched happen.
+    kit.write('b.txt', 'alpha, edited while contested');
+    await ring('b.txt');
+    kit.mv('b.txt', 'c.txt');
+    await ring('b.txt', 'c.txt');
+    snap = kit.point({ scan: false });
+    assert.equal(snap.divergent.get('c.txt'), sha256('alpha, edited while contested'),
+      'the surplus contest followed the edited ground');
+    assert.ok(!snap.files.has('c.txt'), 'no entity claims it');
+  } finally {
+    kit.observer.stop();
+  }
+});
+
+test('the judge convicts tampered event streams', () => {
+  const { createLedger: freshLedger } = require('./entity-oracle/ledger');
+
+  // A fresh identity must be fresh — even after its owner died.
+  let ledger = freshLedger();
+  ledger.ingest([
+    { type: 'file.created', rootId: 'r', fileId: 'F1', path: 'a.md', hash: 'h1' },
+    { type: 'file.deleted', rootId: 'r', fileId: 'F1', path: 'a.md' },
+  ]);
+  assert.throws(() => ledger.ingest([
+    { type: 'file.created', rootId: 'r', fileId: 'F1', path: 'b.md', hash: 'h2' },
+  ]), /used before/);
+
+  // The hash chain must hold.
+  ledger = freshLedger();
+  ledger.ingest([{ type: 'file.created', rootId: 'r', fileId: 'F1', path: 'a.md', hash: 'h1' }]);
+  assert.throws(() => ledger.ingest([
+    { type: 'file.changed', rootId: 'r', fileId: 'F1', path: 'a.md', hash: 'h3', previousHash: 'h2' },
+  ]), /chain/);
+
+  // Equal versions are silence.
+  ledger = freshLedger();
+  ledger.ingest([{ type: 'file.created', rootId: 'r', fileId: 'F1', path: 'a.md', hash: 'h1' }]);
+  assert.throws(() => ledger.ingest([
+    { type: 'file.changed', rootId: 'r', fileId: 'F1', path: 'a.md', hash: 'h1', previousHash: 'h1' },
+  ]), /silence/);
+
+  // A rename must start where the channel lives.
+  ledger = freshLedger();
+  ledger.ingest([{ type: 'file.created', rootId: 'r', fileId: 'F1', path: 'a.md', hash: 'h1' }]);
+  assert.throws(() => ledger.ingest([
+    { type: 'file.renamed', rootId: 'r', fileId: 'F1', from: 'elsewhere.md', to: 'b.md' },
+  ]), /rename from/);
+
+  // Nothing speaks after deletion.
+  ledger = freshLedger();
+  ledger.ingest([
+    { type: 'file.created', rootId: 'r', fileId: 'F1', path: 'a.md', hash: 'h1' },
+    { type: 'file.deleted', rootId: 'r', fileId: 'F1', path: 'a.md' },
+  ]);
+  assert.throws(() => ledger.ingest([
+    { type: 'file.changed', rootId: 'r', fileId: 'F1', path: 'a.md', hash: 'h2', previousHash: 'h1' },
+  ]), /after deletion/);
+
+  // Territories: discovered twice without a removal is a duplicate claim.
+  ledger = freshLedger();
+  ledger.ingest([{ type: 'repo.discovered', rootId: 'r2', path: '/tmp/x' }]);
+  assert.throws(() => ledger.ingest([
+    { type: 'repo.discovered', rootId: 'r3', path: '/tmp/x' },
+  ]), /twice/);
+
+  // Link channels obey the same stream law, with the target chain.
+  ledger = freshLedger();
+  ledger.ingest([{ type: 'link.created', rootId: 'r', linkId: 'L1', path: 'a', target: 't1' }]);
+  assert.throws(() => ledger.ingest([
+    { type: 'link.changed', rootId: 'r', linkId: 'L1', path: 'a', target: 't3', previousTarget: 't2' },
+  ]), /target chain/);
+
+  ledger = freshLedger();
+  ledger.ingest([{ type: 'link.created', rootId: 'r', linkId: 'L1', path: 'a', target: 't1' }]);
+  assert.throws(() => ledger.ingest([
+    { type: 'link.changed', rootId: 'r', linkId: 'L1', path: 'a', target: 't1', previousTarget: 't1' },
+  ]), /silence/);
+
+  ledger = freshLedger();
+  ledger.ingest([
+    { type: 'link.created', rootId: 'r', linkId: 'L1', path: 'a', target: 't1' },
+    { type: 'link.deleted', rootId: 'r', linkId: 'L1', path: 'a' },
+  ]);
+  assert.throws(() => ledger.ingest([
+    { type: 'link.created', rootId: 'r', linkId: 'L1', path: 'b', target: 't2' },
+  ]), /used before/);
+});
+
+// --- independence: the detector and its judge may not share a bug ---------
+
+test('the oracle imports nothing from the detector', () => {
+  const oracleDir = path.join(__dirname, 'entity-oracle');
+  const allowed = /^(node:)?(assert|crypto|fs|path)(\/.*)?$|^\.\/(?!\.)[\w-]+$/;
+  for (const name of fs.readdirSync(oracleDir).filter((f) => f.endsWith('.js'))) {
+    const source = fs.readFileSync(path.join(oracleDir, name), 'utf8');
+    for (const [, , spec] of source.matchAll(/require\((['"])([^'"]+)\1\)/g)) {
+      assert.match(spec, allowed,
+        `${name} requires "${spec}" — the oracle may only use node built-ins and its own modules`);
+      assert.doesNotMatch(spec, /observer|repocard|workspace|scan|store|follow/,
+        `${name} requires "${spec}" — the judge must not share the detector's code`);
+    }
+  }
+});