amalgm 0.1.245 → 0.1.246

package/runtime/scripts/amalgm-mcp/tests/observer.territory.test.js

@@ -0,0 +1,845 @@
+'use strict';
+
+/**
+ * TERRITORY exams: a .git claims its subtree — conversion in both
+ * directions, nested repositories born and buried by doorbell or
+ * census, policy (never gitignore) deciding what enrolls — and the law
+ * that governs ground no look could read: only present or absent may
+ * conclude, so an unsettled read is retried, never forgotten.
+ */
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const { execFileSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+const { followEdges } = require('../observer/edges');
+const {
+  cleanup, eventsOf, fakeWatchKit, makeDir, makeObserver, nudgeUntil, realGit, realRepo,
+} = require('./observer.rig');
+
+test.after(cleanup);
+
+test('a .git claims its subtree: embedded repos are never files territory', () => {
+  const dir = makeDir('territory');
+  fs.writeFileSync(path.join(dir, 'keep.md'), 'mine');
+  fs.mkdirSync(path.join(dir, 'app'));
+  fs.writeFileSync(path.join(dir, 'app', 'index.md'), 'also mine');
+  fs.mkdirSync(path.join(dir, 'vendor', '.git'), { recursive: true });
+  fs.writeFileSync(path.join(dir, 'vendor', 'readme.md'), 'repo territory');
+
+  const { observer, events } = makeObserver();
+  observer.enrollRoot(dir);
+  assert.deepEqual(
+    eventsOf(events, 'file.created').map((event) => event.path).sort(),
+    ['app/index.md', 'keep.md'],
+  );
+  // The embedded repo became its own repo root, not files channels.
+  const discovered = eventsOf(events, 'repo.discovered');
+  assert.equal(discovered.length, 1);
+  assert.equal(discovered[0].path, path.join(dir, 'vendor'));
+  assert.ok(observer.listRoots().some(
+    (root) => root.kind === 'repo' && root.path === path.join(dir, 'vendor'),
+  ));
+  events.length = 0;
+
+  // Churn inside the embedded repo never becomes file events — only the
+  // vendor repo root's own doorbell speaks for it.
+  fs.writeFileSync(path.join(dir, 'vendor', 'readme.md'), 'checkout churn');
+  fs.writeFileSync(path.join(dir, 'vendor', 'new.md'), 'more churn');
+  observer.scanNow();
+  assert.equal(events.filter((event) => event.type.startsWith('file.')).length, 0);
+  events.length = 0;
+
+  // A .git appearing later transfers the territory: channels close, a repo is born.
+  fs.mkdirSync(path.join(dir, 'app', '.git'));
+  observer.scanNow();
+  const fileEvents = events.filter((event) => event.type.startsWith('file.'));
+  assert.deepEqual(fileEvents.map((event) => event.type), ['file.deleted']);
+  assert.equal(fileEvents[0].path, 'app/index.md');
+  assert.ok(eventsOf(events, 'repo.discovered').some(
+    (event) => event.path === path.join(dir, 'app'),
+  ));
+});
+
+test('a .git vanishing returns its territory to files: channels are reborn', () => {
+  const dir = makeDir('territory-back');
+  fs.mkdirSync(path.join(dir, 'vendor', '.git'), { recursive: true });
+  fs.writeFileSync(path.join(dir, 'vendor', 'readme.md'), 'was repo territory');
+
+  const { observer, events } = makeObserver();
+  observer.enrollRoot(dir);
+  assert.equal(eventsOf(events, 'repo.discovered').length, 1);
+  events.length = 0;
+
+  fs.rmSync(path.join(dir, 'vendor', '.git'), { recursive: true });
+  observer.scanNow();
+
+  assert.equal(eventsOf(events, 'repo.removed').length, 1);
+  assert.deepEqual(
+    eventsOf(events, 'file.created').map((event) => event.path),
+    ['vendor/readme.md'],
+  );
+  assert.ok(observer.listRoots().every((root) => root.kind === 'files'));
+});
+
+test('territory is decided by disk: enrolling a git repo auto-detects repo kind', () => {
+  const dir = makeDir('auto-repo');
+  fs.mkdirSync(path.join(dir, '.git'));
+  fs.writeFileSync(path.join(dir, 'main.ts'), 'v1');
+
+  const { observer, events } = makeObserver();
+  const root = observer.enrollRoot(dir);
+
+  assert.equal(root.kind, 'repo');
+  assert.equal(eventsOf(events, 'file.created').length, 0);
+  assert.deepEqual(eventsOf(events, 'repo.discovered').map((event) => event.path), [dir]);
+});
+
+test('a workspace root growing a .git converts in place: channels close, one repo is born', () => {
+  const dir = makeDir('root-convert');
+  fs.writeFileSync(path.join(dir, 'a.md'), 'a');
+  fs.writeFileSync(path.join(dir, 'b.md'), 'b');
+
+  const { observer, events } = makeObserver();
+  const root = observer.enrollRoot(dir);
+  assert.equal(eventsOf(events, 'file.created').length, 2);
+  events.length = 0;
+
+  fs.mkdirSync(path.join(dir, '.git'));
+  observer.scanNow();
+  assert.deepEqual(
+    eventsOf(events, 'file.deleted').map((event) => event.path).sort(),
+    ['a.md', 'b.md'],
+  );
+  assert.deepEqual(eventsOf(events, 'repo.discovered').map((event) => event.path), [dir]);
+  assert.equal(observer.listRoots()[0].kind, 'repo');
+  events.length = 0;
+
+  // And back: the .git vanishing rebirths the channels on the same root.
+  fs.rmSync(path.join(dir, '.git'), { recursive: true });
+  observer.scanNow();
+  assert.equal(eventsOf(events, 'repo.removed').length, 1);
+  assert.deepEqual(
+    eventsOf(events, 'file.created').map((event) => event.path).sort(),
+    ['a.md', 'b.md'],
+  );
+  assert.equal(observer.listRoots()[0].kind, 'files');
+  assert.equal(observer.listRoots()[0].rootId, root.rootId);
+});
+
+// --- unsettled convergence: an unsettled read is never forgotten -------------
+
+test('an unsettled read keeps the entity dirty: one doorbell, the change is still detected', async () => {
+  const dir = makeDir('unsettled-converge');
+  const beacon = path.join(dir, 'beacon.md');
+  const guarded = path.join(dir, 'guarded.md');
+  fs.writeFileSync(beacon, 'beacon-v1');
+  fs.writeFileSync(guarded, 'guarded-v1');
+  const kit = fakeWatchKit();
+  const { observer, events } = makeObserver({ settleMs: 25, watch: kit.watch });
+  const root = observer.enrollRoot(dir);
+  observer.start();
+  events.length = 0;
+  try {
+    // Both files change; the guarded one is unreadable when the scan
+    // looks — the deterministic stand-in for any transiently unsettled
+    // read — and each doorbell rings exactly ONCE.
+    fs.writeFileSync(beacon, 'beacon-v2');
+    fs.writeFileSync(guarded, 'guarded-v2');
+    fs.chmodSync(guarded, 0o000);
+    kit.ring(dir, 'beacon.md');
+    kit.ring(dir, 'guarded.md');
+
+    // The beacon's event proves the rung scan COMPLETED while the
+    // guarded ground was unreadable: its read was unsettled, no verdict.
+    assert.ok(await nudgeUntil(() => {}, () => eventsOf(events, 'file.changed')
+      .some((event) => event.path === 'beacon.md')), 'the rung scan never ran');
+    assert.equal(eventsOf(events, 'file.changed').filter((event) => event.path === 'guarded.md').length, 0,
+      'unsettled is not a conclusion');
+
+    // From here NO doorbell ever rings again. Truth settles; only a read
+    // the observer scheduled for itself can reach it — an unsettled read
+    // means "read again", and detection is who reads again.
+    fs.chmodSync(guarded, 0o644);
+    assert.ok(await nudgeUntil(() => {}, () => eventsOf(events, 'file.changed')
+      .some((event) => event.path === 'guarded.md')),
+      'the unsettled read was forgotten: the change was never detected');
+    assert.deepEqual(observer.verify(root.rootId), [], 'beliefs converged to disk');
+  } finally {
+    observer.stop();
+  }
+});
+
+// --- only present or absent may conclude -------------------------------------
+// Unsettled preserves existing belief, remains pending, and makes
+// verification inconclusive. Each exam below is a ratified reproduction
+// of a production lie (audit 10): territory demolished, verification
+// declaring unreadable ground clean or ghost, living files "deleted".
+
+test('an uninspectable repository never loses its territory', () => {
+  const dir = realRepo('sealed-territory');
+  const { observer, events } = makeObserver();
+  const root = observer.enrollRoot(dir);
+  events.length = 0;
+  fs.chmodSync(dir, 0o000);
+  try {
+    observer.scanNow(root.rootId);
+    assert.deepEqual(eventsOf(events, 'repo.removed'), [], 'a failed look demolished territory');
+    assert.equal(observer.listRoots()[0].kind, 'repo', 'the root stayed a repository');
+  } finally {
+    fs.chmodSync(dir, 0o755);
+  }
+  observer.scanNow(root.rootId);
+  assert.equal(observer.listRoots()[0].kind, 'repo');
+  assert.ok(eventsOf(events, 'repo.changed').length >= 1,
+    'the settled look brings the catch-up doorbell');
+  observer.stop();
+});
+
+test('verification is inconclusive on unreadable ground — never clean', () => {
+  const dir = makeDir('verify-unsettled');
+  const file = path.join(dir, 'single.txt');
+  fs.writeFileSync(file, 'v1');
+  const { observer } = makeObserver();
+  const root = observer.enrollRoot(file);
+  fs.writeFileSync(file, 'v2-diverged');
+  fs.chmodSync(file, 0o000);
+  try {
+    const report = observer.verify(root.rootId);
+    assert.equal(report.length, 1);
+    assert.match(report[0].problem, /^unsettled:/, 'unreadable ground is inconclusive, not clean');
+  } finally {
+    fs.chmodSync(file, 0o644);
+  }
+  assert.deepEqual(observer.verify(root.rootId).map((m) => m.problem.split(':')[0]), ['stale'],
+    'the settled look reports the real divergence');
+  observer.stop();
+});
+
+test('the referee never mistakes unreadable for ghost: one unsettled entry, no false alarm', () => {
+  const dir = makeDir('verify-sealed-member');
+  fs.writeFileSync(path.join(dir, 'open.txt'), 'fine');
+  fs.writeFileSync(path.join(dir, 'sealed.txt'), 'kept');
+  const { observer } = makeObserver();
+  const root = observer.enrollRoot(dir);
+  fs.chmodSync(path.join(dir, 'sealed.txt'), 0o000);
+  try {
+    const report = observer.verify(root.rootId);
+    assert.deepEqual(report.map((m) => [m.path, m.problem.split(':')[0]]),
+      [['sealed.txt', 'unsettled']],
+      'unchanged-but-unreadable is inconclusive — never ghost, never clean');
+  } finally {
+    fs.chmodSync(path.join(dir, 'sealed.txt'), 0o644);
+  }
+  assert.deepEqual(observer.verify(root.rootId), [], 'settled again: clean');
+  observer.stop();
+});
+
+test('an unlistable directory concludes nothing: no deletes beneath it, beliefs converge', () => {
+  const dir = makeDir('sealed-subtree');
+  fs.mkdirSync(path.join(dir, 'sub'));
+  fs.writeFileSync(path.join(dir, 'sub', 'inner.txt'), 'alive');
+  const { observer, events } = makeObserver();
+  const root = observer.enrollRoot(dir);
+  events.length = 0;
+  fs.chmodSync(path.join(dir, 'sub'), 0o000);
+  try {
+    observer.scanNow(root.rootId);
+    assert.deepEqual(events, [], 'a failed look produced conclusions');
+  } finally {
+    fs.chmodSync(path.join(dir, 'sub'), 0o755);
+  }
+  observer.scanNow(root.rootId);
+  assert.deepEqual(events, [], 'nothing actually changed: settling is silence');
+  assert.deepEqual(observer.verify(root.rootId), []);
+  observer.stop();
+});
+
+test('unsettled retries coalesce and back off; new doorbell evidence resets the delay', async () => {
+  const dir = makeDir('backoff');
+  const file = path.join(dir, 'slow.txt');
+  fs.writeFileSync(file, 'v1');
+  let probes = 0;
+  const kit = fakeWatchKit();
+  const { observer, events } = makeObserver({
+    settleMs: 100,
+    watch: kit.watch,
+    shouldEnroll: () => { probes++; return true; },
+  });
+  observer.enrollRoot(dir);
+  observer.start();
+  events.length = 0;
+  try {
+    fs.writeFileSync(file, 'v2-changed');
+    fs.chmodSync(file, 0o000);
+    const mark = probes;
+    kit.ring(dir, 'slow.txt');
+    // The walk asks the policy once per entry, so probes count the
+    // scans. Backed off, the first four looks land near 100, 200, 400,
+    // and 800ms; a hot loop would have run ~15 by then.
+    assert.ok(await nudgeUntil(() => {}, () => probes >= mark + 4, 5_000), 'retries stopped');
+    assert.ok(probes - mark <= 6, `retries did not back off: ${probes - mark} scans`);
+    // A long backed-off wait is now pending. New evidence must replace
+    // it: the change lands on the settle delay, not the backoff's.
+    fs.chmodSync(file, 0o644);
+    const rangAt = Date.now();
+    kit.ring(dir, 'slow.txt');
+    assert.ok(await nudgeUntil(() => {}, () => eventsOf(events, 'file.changed').length === 1, 5_000),
+      'the settled change was never detected');
+    assert.ok(Date.now() - rangAt < 500, 'new evidence did not reset the backoff');
+  } finally {
+    fs.chmodSync(file, 0o644);
+    observer.stop();
+  }
+});
+
+test('enrollment refuses to guess an unreadable kind', () => {
+  const dir = realRepo('sealed-enroll');
+  const { observer } = makeObserver();
+  fs.chmodSync(dir, 0o000);
+  try {
+    assert.throws(() => observer.enrollRoot(dir), /unsettled/,
+      'an unreadable kind must refuse loudly, never guess');
+    assert.deepEqual(observer.listRoots(), [], 'no wrongly typed root was minted');
+  } finally {
+    fs.chmodSync(dir, 0o755);
+  }
+  assert.equal(observer.enrollRoot(dir).kind, 'repo',
+    'the settled look enrolls the truth');
+  observer.stop();
+});
+
+test('a repository hidden behind unreadable ground is inconclusive — and the retry finds it when the ground settles', async () => {
+  const dir = realRepo('hidden-census');
+  const { observer, events } = makeObserver({ settleMs: 25 });
+  const root = observer.enrollRoot(dir);
+  const hidden = path.join(dir, 'hidden');
+  fs.mkdirSync(path.join(hidden, 'inner'), { recursive: true });
+  execFileSync('git', ['init', '-q'], { cwd: path.join(hidden, 'inner') });
+  fs.chmodSync(hidden, 0o000);
+  events.length = 0;
+  try {
+    observer.scanNow(root.rootId); // the census meets the unreadable ground
+    assert.deepEqual(eventsOf(events, 'repo.discovered'), [], 'a failed look concluded a discovery');
+    assert.deepEqual(observer.verify(root.rootId).map((m) => [m.path, m.problem.split(':')[0]]),
+      [['hidden', 'unsettled']],
+      'unlistable ground may hide a boundary — inconclusive, never clean');
+  } finally {
+    fs.chmodSync(hidden, 0o755);
+  }
+  // No further doorbell, no further scanNow: the census's own armed
+  // retry discovers the hidden repository once the ground settles.
+  assert.ok(await nudgeUntil(() => {}, () => eventsOf(events, 'repo.discovered').length === 1, 5_000),
+    'the unsettled census was forgotten: the hidden repository was never discovered');
+  assert.deepEqual(observer.verify(root.rootId), [], 'settled and complete');
+  observer.stop();
+});
+
+test('a doorbell about unsettled territory is never forgotten', async () => {
+  const dir = realRepo('kept-doorbell');
+  const child = path.join(dir, 'vendor');
+  fs.mkdirSync(child);
+  execFileSync('git', ['init', '-q'], { cwd: child });
+  const kit = fakeWatchKit();
+  const { observer, events } = makeObserver({ settleMs: 25, watch: kit.watch });
+  observer.enrollRoot(dir);
+  observer.start();
+  events.length = 0;
+  // The boundary dies while its ground cannot be inspected:
+  fs.rmSync(path.join(child, '.git'), { recursive: true, force: true });
+  fs.chmodSync(child, 0o000);
+  try {
+    kit.ring(dir, 'vendor/readme.md');
+    assert.deepEqual(eventsOf(events, 'repo.removed'), [], 'a failed look buried territory');
+  } finally {
+    fs.chmodSync(child, 0o755);
+  }
+  // Readability returns with NO second doorbell: only the armed
+  // backed-off retry can bury the dead boundary now.
+  assert.ok(await nudgeUntil(() => {}, () => eventsOf(events, 'repo.removed').length === 1, 5_000),
+    'the doorbell died with the failed look: the dead boundary was never buried');
+  observer.stop();
+});
+
+test('the edge surface is three-state: readable edges enroll, unreadable ground keeps the follow unsettled', () => {
+  const outside = makeDir('sealed-edge-target');
+  fs.writeFileSync(path.join(outside, 'shared.md'), 'shared');
+  const dir = realRepo('sealed-edges');
+  fs.symlinkSync(outside, path.join(dir, 'shared'));
+  fs.mkdirSync(path.join(dir, 'sealed'));
+  fs.chmodSync(path.join(dir, 'sealed'), 0o000);
+  const { observer } = makeObserver();
+  const root = observer.enrollRoot(dir);
+  try {
+    const surface = observer.linkEdges(root.rootId);
+    assert.deepEqual(surface.edges, [{ relPath: 'shared', target: outside }]);
+    assert.deepEqual(surface.unsettled, ['sealed'], 'unlisted ground may hide an edge');
+    const pass = followEdges(observer);
+    assert.deepEqual(pass.enrolled, [outside], 'what WAS readable still enrolls');
+    assert.equal(pass.settled, false, 'the pass claims no completeness it did not earn');
+  } finally {
+    fs.chmodSync(path.join(dir, 'sealed'), 0o755);
+  }
+  const settled = followEdges(observer);
+  assert.equal(settled.settled, true);
+  assert.deepEqual(settled.enrolled, [], 'idempotent once the ground settles');
+  observer.stop();
+});
+
+test('census at enrollment: nested repos and their children become territories', () => {
+  const dir = realRepo('census');
+  fs.writeFileSync(path.join(dir, 'a.md'), 'root\n');
+  const child = path.join(dir, 'vendor', 'lib');
+  fs.mkdirSync(child, { recursive: true });
+  realGit(child, 'init', '--quiet');
+  const grandchild = path.join(child, 'deeper');
+  fs.mkdirSync(grandchild);
+  realGit(grandchild, 'init', '--quiet');
+
+  const { observer, events } = makeObserver();
+  observer.enrollRoot(dir);
+
+  const discovered = eventsOf(events, 'repo.discovered').map((event) => event.path).sort();
+  assert.deepEqual(discovered, [dir, child, grandchild].sort(),
+    'the census must recurse: a child repo runs its own census');
+  assert.equal(observer.listRoots().length, 3);
+  assert.ok(observer.listRoots().every((root) => root.kind === 'repo'));
+  assert.equal(observer.verify().length, 0, 'the referee must agree the census is complete');
+});
+
+test('enrollment is amalgm policy, not gitignore: ignored ground enrolls, excluded ground does not', () => {
+  // Entity axiom 2: git's ignore rules never decide entity existence.
+  const dir = realRepo('census-policy');
+  fs.writeFileSync(path.join(dir, '.gitignore'), 'vendor/\n');
+  const ignored = path.join(dir, 'vendor', 'lib');
+  fs.mkdirSync(ignored, { recursive: true });
+  realGit(ignored, 'init', '--quiet');
+  const excluded = path.join(dir, 'node_modules', 'dep');
+  fs.mkdirSync(excluded, { recursive: true });
+  realGit(excluded, 'init', '--quiet');
+
+  const { observer, events } = makeObserver();
+  observer.enrollRoot(dir);
+
+  const discovered = eventsOf(events, 'repo.discovered').map((event) => event.path);
+  assert.ok(discovered.includes(ignored), 'gitignore never decides: an ignored repo in enrolled ground is an entity');
+  assert.equal(discovered.includes(excluded), false, 'amalgm-excluded ground enrolls nothing');
+  assert.equal(observer.verify().length, 0, 'the referee applies the same policy');
+});
+
+test('a repo born inside a tracked directory is discovered live by its .git doorbell', async () => {
+  // The case git itself cannot report: ls-files shows ordinary tracked
+  // files, no gitlink, no trailing-slash boundary. Only the walk and the
+  // doorbell see it.
+  const dir = realRepo('census-tracked');
+  fs.mkdirSync(path.join(dir, 'app'));
+  fs.writeFileSync(path.join(dir, 'app', 'index.md'), 'tracked\n');
+  realGit(dir, 'add', '-A');
+  realGit(dir, 'commit', '--quiet', '-m', 'first');
+
+  const { observer, events } = makeObserver();
+  observer.enrollRoot(dir);
+  observer.start();
+  try {
+    const appPath = path.join(dir, 'app');
+    const born = await nudgeUntil(
+      () => { try { realGit(appPath, 'init', '--quiet'); } catch {} },
+      () => eventsOf(events, 'repo.discovered').some((event) => event.path === appPath),
+    );
+    assert.ok(born, 'the .git doorbell must birth the child territory');
+    assert.equal(observer.listRoots().find((root) => root.path === appPath)?.kind, 'repo');
+  } finally {
+    observer.stop();
+  }
+});
+
+test('a linked worktree inside the checkout is its own territory', () => {
+  const dir = realRepo('census-worktree');
+  fs.writeFileSync(path.join(dir, 'a.md'), 'v1\n');
+  realGit(dir, 'add', '-A');
+  realGit(dir, 'commit', '--quiet', '-m', 'first');
+  realGit(dir, 'worktree', 'add', '--quiet', path.join(dir, 'trees', 'wt1'), '-b', 'side');
+
+  const { observer, events } = makeObserver();
+  observer.enrollRoot(dir);
+
+  const wtPath = path.join(dir, 'trees', 'wt1');
+  assert.ok(eventsOf(events, 'repo.discovered').some((event) => event.path === wtPath),
+    'a .git FILE is a boundary too');
+});
+
+test('submodules: initialized is a territory, uninitialized is nothing to follow', () => {
+  const inner = realRepo('census-sub-src');
+  fs.writeFileSync(path.join(inner, 'lib.md'), 'inner\n');
+  realGit(inner, 'add', '-A');
+  realGit(inner, 'commit', '--quiet', '-m', 'inner');
+
+  const outer = realRepo('census-sub-outer');
+  fs.writeFileSync(path.join(outer, 'a.md'), 'outer\n');
+  realGit(outer, 'add', '-A');
+  realGit(outer, 'commit', '--quiet', '-m', 'outer');
+  realGit(outer, '-c', 'protocol.file.allow=always', 'submodule', '--quiet', 'add', inner, 'sub');
+  realGit(outer, 'commit', '--quiet', '-m', 'add submodule');
+
+  {
+    const { observer, events } = makeObserver();
+    observer.enrollRoot(outer);
+    assert.ok(eventsOf(events, 'repo.discovered').some((event) => event.path === path.join(outer, 'sub')),
+      'an initialized submodule has a .git and is a territory');
+  }
+
+  const cloneDir = makeDir('census-sub-clone');
+  realGit(path.dirname(cloneDir), 'clone', '--quiet', outer, cloneDir);
+  {
+    const { observer, events } = makeObserver();
+    observer.enrollRoot(cloneDir);
+    assert.deepEqual(eventsOf(events, 'repo.discovered').map((event) => event.path), [cloneDir],
+      'an uninitialized submodule has no .git on disk — nothing to follow until init, which is a doorbell');
+    assert.equal(observer.verify().length, 0);
+  }
+});
+
+test('a nested repo death buries the child — by doorbell or the next catch-up', async () => {
+  const dir = realRepo('census-death');
+  const child = path.join(dir, 'sub');
+  fs.mkdirSync(child);
+  realGit(child, 'init', '--quiet');
+  fs.writeFileSync(path.join(child, 'inner.md'), 'child ground\n');
+
+  const { observer, events } = makeObserver();
+  const parentRoot = observer.enrollRoot(dir);
+  assert.ok(observer.listRoots().some((root) => root.path === child), 'enrollment census must claim the child');
+
+  observer.start();
+  try {
+    const buried = await nudgeUntil(
+      () => {
+        fs.rmSync(path.join(child, '.git'), { recursive: true, force: true });
+        observer.scanNow(); // the consumer moment: a lost deletion doorbell is delayed, not lost
+      },
+      () => eventsOf(events, 'repo.removed').some((event) => event.path === child),
+    );
+    assert.ok(buried, 'the child must be buried');
+    assert.equal(observer.listRoots().some((root) => root.path === child), false);
+    assert.ok(
+      eventsOf(events, 'repo.changed').some((event) => event.rootId === parentRoot.rootId),
+      'the ground must return to the parent: its capture is the reclaim',
+    );
+    assert.equal(observer.verify().length, 0);
+  } finally {
+    observer.stop();
+  }
+});
+
+test('the referee reports unclaimed territory: a .git the observer never registered', () => {
+  const dir = makeDir('unclaimed');
+  fs.writeFileSync(path.join(dir, 'a.md'), 'a');
+
+  const { observer } = makeObserver();
+  const root = observer.enrollRoot(dir);
+
+  // Appears behind the observer's back — no doorbell, no scan.
+  fs.mkdirSync(path.join(dir, 'hidden', '.git'), { recursive: true });
+
+  const problems = observer.verify(root.rootId);
+  assert.equal(problems.length, 1);
+  assert.match(problems[0].problem, /unclaimed territory/);
+  assert.equal(problems[0].path, 'hidden');
+
+  // The next scan claims it; the referee falls silent.
+  observer.scanNow();
+  assert.deepEqual(observer.verify(root.rootId), []);
+});
+
+test('the referee names a ghost territory: a registered repo whose .git left disk', () => {
+  const dir = realRepo('ghost');
+  const child = path.join(dir, 'sub');
+  fs.mkdirSync(child);
+  realGit(child, 'init', '--quiet');
+
+  const { observer } = makeObserver();
+  observer.enrollRoot(dir);
+  assert.ok(observer.listRoots().some((root) => root.path === child));
+
+  // Vanishes behind the observer's back — no doorbell, no scan.
+  fs.rmSync(path.join(child, '.git'), { recursive: true, force: true });
+
+  const problems = observer.verify();
+  assert.equal(problems.length, 1, 'the referee must prove equality in BOTH directions');
+  assert.match(problems[0].problem, /ghost territory/);
+
+  // The next catch-up buries it; the referee falls silent.
+  observer.scanNow();
+  assert.deepEqual(observer.verify(), []);
+});
+
+test('a repository moved in whole is discovered: the doorbell names a directory, disk decides', async () => {
+  // A mv delivers ONE event, for the directory that landed — no path ever
+  // spells ".git". The prefix walk must find the boundary anyway.
+  const staged = realRepo('mv-in-staged');
+  fs.writeFileSync(path.join(staged, 'inner.md'), 'inner\n');
+  realGit(staged, 'add', '-A');
+  realGit(staged, 'commit', '--quiet', '-m', 'inner');
+
+  const dir = realRepo('mv-in-parent');
+  fs.writeFileSync(path.join(dir, 'a.md'), 'root\n');
+
+  const { observer, events } = makeObserver();
+  observer.enrollRoot(dir);
+  observer.start();
+  try {
+    const landed = path.join(dir, 'vendor-lib');
+    const born = await nudgeUntil(
+      () => {
+        if (!fs.existsSync(landed)) {
+          try { fs.renameSync(staged, landed); } catch { /* raced; retry */ }
+        } else {
+          fs.writeFileSync(path.join(landed, 'probe.md'), 'probe\n');
+        }
+      },
+      () => eventsOf(events, 'repo.discovered').some((event) => event.path === landed),
+    );
+    assert.ok(born, 'a moved-in repository must be born by the doorbell it does ring');
+    assert.equal(observer.listRoots().find((root) => root.path === landed)?.kind, 'repo');
+    assert.equal(observer.verify().length, 0);
+  } finally {
+    observer.stop();
+  }
+});
+
+test('a repository moved out whole is buried: the doorbell names its ground, disk decides', async () => {
+  const dir = realRepo('mv-out-parent');
+  fs.writeFileSync(path.join(dir, 'a.md'), 'root\n');
+  const child = path.join(dir, 'sub');
+  fs.mkdirSync(child);
+  realGit(child, 'init', '--quiet');
+  fs.writeFileSync(path.join(child, 'inner.md'), 'inner\n');
+  const grave = path.join(makeDir('mv-out-grave'), 'sub');
+
+  const { observer, events } = makeObserver();
+  const parentRoot = observer.enrollRoot(dir);
+  assert.ok(observer.listRoots().some((root) => root.path === child));
+  observer.start();
+  try {
+    const buried = await nudgeUntil(
+      () => {
+        if (fs.existsSync(child)) {
+          try { fs.renameSync(child, grave); } catch { /* raced; retry */ }
+        } else {
+          // Ring the dead territory's ground: existence is the question,
+          // and no consumer moment (scanNow) is allowed to answer it here.
+          try { fs.mkdirSync(child); fs.rmdirSync(child); } catch { /* raced; retry */ }
+        }
+      },
+      () => eventsOf(events, 'repo.removed').some((event) => event.path === child),
+    );
+    assert.ok(buried, 'a moved-out repository must be buried by the doorbell it does ring');
+    assert.equal(observer.listRoots().some((root) => root.path === child), false);
+    assert.ok(
+      eventsOf(events, 'repo.changed').some((event) => event.rootId === parentRoot.rootId),
+      'the ground must return to the parent',
+    );
+    assert.equal(observer.verify().length, 0);
+  } finally {
+    observer.stop();
+  }
+});
+
+test('moving out a folder that contains a territory buries it: the doorbell names only the ancestor', async () => {
+  const dir = realRepo('mv-out-ancestor');
+  fs.writeFileSync(path.join(dir, 'a.md'), 'root\n');
+  const folder = path.join(dir, 'vendor');
+  const child = path.join(folder, 'lib');
+  fs.mkdirSync(child, { recursive: true });
+  realGit(child, 'init', '--quiet');
+  const grave = path.join(makeDir('mv-out-ancestor-grave'), 'vendor');
+
+  const { observer, events } = makeObserver();
+  observer.enrollRoot(dir);
+  assert.ok(observer.listRoots().some((root) => root.path === child));
+  observer.start();
+  try {
+    const buried = await nudgeUntil(
+      () => {
+        if (fs.existsSync(folder)) {
+          try { fs.renameSync(folder, grave); } catch { /* raced; retry */ }
+        } else {
+          // Ring the ancestor path itself; no consumer moment allowed here.
+          try { fs.mkdirSync(folder); fs.rmdirSync(folder); } catch { /* raced; retry */ }
+        }
+      },
+      () => eventsOf(events, 'repo.removed').some((event) => event.path === child),
+    );
+    assert.ok(buried, 'a territory below the named path must have its existence checked');
+    assert.equal(observer.listRoots().some((root) => root.path === child), false);
+    assert.equal(observer.verify().length, 0);
+  } finally {
+    observer.stop();
+  }
+});
+
+test('a repository moved in deeper than the doorbell names is discovered: scoped walk under the named folder', async () => {
+  const staged = makeDir('mv-deep-staged');
+  const stagedPkg = path.join(staged, 'pkg');
+  const stagedLib = path.join(stagedPkg, 'lib');
+  fs.mkdirSync(stagedLib, { recursive: true });
+  realGit(stagedLib, 'init', '--quiet');
+  fs.writeFileSync(path.join(stagedLib, 'inner.md'), 'inner\n');
+
+  const dir = realRepo('mv-deep-parent');
+  fs.writeFileSync(path.join(dir, 'a.md'), 'root\n');
+
+  const { observer, events } = makeObserver();
+  observer.enrollRoot(dir);
+  observer.start();
+  try {
+    const landedPkg = path.join(dir, 'pkg');
+    const landedLib = path.join(landedPkg, 'lib');
+    const born = await nudgeUntil(
+      () => {
+        if (!fs.existsSync(landedPkg)) {
+          try { fs.renameSync(stagedPkg, landedPkg); } catch { /* raced; retry */ }
+        } else {
+          // Re-ring the named folder itself (a touch, idempotent).
+          try { fs.utimesSync(landedPkg, new Date(), new Date()); } catch { /* raced; retry */ }
+        }
+      },
+      () => eventsOf(events, 'repo.discovered').some((event) => event.path === landedLib),
+    );
+    assert.ok(born, 'the scoped walk under the named directory must find the deeper boundary');
+    assert.equal(observer.listRoots().find((root) => root.path === landedLib)?.kind, 'repo');
+    assert.equal(observer.verify().length, 0);
+  } finally {
+    observer.stop();
+  }
+});
+
+test('doorbell births obey prune-at-the-directory policy: excluded ground never enrolls live', () => {
+  // Reviewer-caught (scoped walk) plus found-in-fix (prefix walk): both
+  // live tiers used to ask the policy point-wise. A manual policy pruning
+  // `pkg/private` was invisible — the scoped walk asked with paths relative
+  // to the named directory, the prefix walk asked only about the boundary
+  // itself — and existence-wins means a wrong birth is never buried.
+  const dir = realRepo('policy-doorbell');
+  fs.writeFileSync(path.join(dir, 'a.md'), 'root\n');
+
+  const defaultPolicy = require('../workspace/tree/inclusion').shouldEnroll;
+  const kit = fakeWatchKit();
+  const { observer, events } = makeObserver({
+    watch: kit.watch,
+    shouldEnroll: (rel) => defaultPolicy(rel) && rel !== 'pkg/private',
+  });
+  observer.enrollRoot(dir);
+  observer.start();
+  try {
+    // Ground appears while only the fake doorbell listens: one repo on
+    // enrollable ground, one under the pruned directory.
+    const lib = path.join(dir, 'pkg', 'lib');
+    const priv = path.join(dir, 'pkg', 'private', 'repo');
+    fs.mkdirSync(lib, { recursive: true });
+    realGit(lib, 'init', '--quiet');
+    fs.mkdirSync(priv, { recursive: true });
+    realGit(priv, 'init', '--quiet');
+
+    const discovered = () => eventsOf(events, 'repo.discovered').map((event) => event.path);
+
+    // The mv-in doorbell names only the directory that landed.
+    kit.ring(dir, 'pkg');
+    assert.ok(discovered().includes(lib), 'enrollable ground is discovered by the scoped walk');
+    assert.equal(discovered().includes(priv), false,
+      'a policy pruning pkg/private prunes the scoped walk too');
+
+    // A deep doorbell into pruned ground names a file inside the boundary.
+    kit.ring(dir, 'pkg/private/repo/inner.md');
+    assert.equal(discovered().includes(priv), false,
+      'the prefix walk prunes at the excluded directory, never point-wise at the boundary');
+    assert.equal(observer.verify().length, 0, 'the referee applies the same policy');
+  } finally {
+    observer.stop();
+  }
+});
+
+test('a null doorbell reconciles the whole root: one ring births the new boundary and buries the dead', () => {
+  // fs.watch may deliver a null filename; the only honest reading is a full
+  // reconcile. Proven through the production wiring via the injectable
+  // doorbell: a birth AND a burial from one null ring.
+  const dir = realRepo('null-doorbell');
+  fs.writeFileSync(path.join(dir, 'a.md'), 'root\n');
+  const dying = path.join(dir, 'vendor', 'lib');
+  fs.mkdirSync(dying, { recursive: true });
+  realGit(dying, 'init', '--quiet');
+
+  const kit = fakeWatchKit();
+  const { observer, events } = makeObserver({ watch: kit.watch });
+  observer.enrollRoot(dir);
+  observer.start();
+  try {
+    assert.ok(eventsOf(events, 'repo.discovered').some((event) => event.path === dying),
+      'the enrollment census claims the nested boundary');
+
+    // Offline changes: only the fake doorbell listens, so nothing rings.
+    fs.rmSync(path.join(dying, '.git'), { recursive: true, force: true });
+    const born = path.join(dir, 'pkg', 'tool');
+    fs.mkdirSync(born, { recursive: true });
+    realGit(born, 'init', '--quiet');
+
+    kit.ring(dir, null);
+
+    assert.ok(eventsOf(events, 'repo.removed').some((event) => event.path === dying),
+      'one null ring buries the dead boundary');
+    assert.ok(eventsOf(events, 'repo.discovered').some((event) => event.path === born),
+      'one null ring births the new boundary');
+    assert.deepEqual(eventsOf(events, 'repo.changed').at(-1)?.areas, ['git', 'worktree'],
+      'the raw forward still happens, classified as everything');
+    assert.equal(observer.verify().length, 0);
+  } finally {
+    observer.stop();
+  }
+});
+
+test('a gitignored linked worktree is still territory: policy, not gitignore, decides', () => {
+  const dir = realRepo('wt-ignored');
+  fs.writeFileSync(path.join(dir, '.gitignore'), 'trees/\n');
+  fs.writeFileSync(path.join(dir, 'a.md'), 'v1\n');
+  realGit(dir, 'add', '-A');
+  realGit(dir, 'commit', '--quiet', '-m', 'first');
+  realGit(dir, 'worktree', 'add', '--quiet', path.join(dir, 'trees', 'wt1'), '-b', 'side');
+
+  const { observer, events } = makeObserver();
+  observer.enrollRoot(dir);
+
+  assert.ok(eventsOf(events, 'repo.discovered').some((event) => event.path === path.join(dir, 'trees', 'wt1')),
+    'an ignored worktree in enrolled ground is a territory');
+  assert.equal(observer.verify().length, 0);
+});
+
+test('a gitignored worktree added live is born by its own doorbell', async () => {
+  const dir = realRepo('wt-live');
+  fs.writeFileSync(path.join(dir, '.gitignore'), 'trees/\n');
+  fs.writeFileSync(path.join(dir, 'a.md'), 'v1\n');
+  realGit(dir, 'add', '-A');
+  realGit(dir, 'commit', '--quiet', '-m', 'first');
+
+  const { observer, events } = makeObserver();
+  observer.enrollRoot(dir);
+  observer.start();
+  try {
+    const wt = path.join(dir, 'trees', 'wt2');
+    const born = await nudgeUntil(
+      () => {
+        if (!fs.existsSync(wt)) {
+          try { realGit(dir, 'worktree', 'add', '--quiet', wt, '-b', 'side2'); } catch { /* raced; retry */ }
+        } else {
+          fs.writeFileSync(path.join(wt, 'probe.md'), 'probe\n');
+        }
+      },
+      () => eventsOf(events, 'repo.discovered').some((event) => event.path === wt),
+    );
+    assert.ok(born, 'the enrollment policy, not gitignore, decides a live birth');
+    assert.equal(observer.verify().length, 0);
+  } finally {
+    observer.stop();
+  }
+});