amalgm 0.1.245 → 0.1.246

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

@@ -0,0 +1,505 @@
+'use strict';
+
+/**
+ * ROOT exams: identity is permanent and the address is not. Ground that
+ * moves is rescued by witnessed continuity (the root keeps its id and
+ * every channel), a departure is honest absence, ambiguity refuses to
+ * guess, and the smallest ground of all — a single-file root — carries
+ * the same laws over one channel.
+ */
+
+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 Database = require('better-sqlite3');
+const { installFakeWatch } = require('./fake-watch');
+const {
+  cleanup, eventsOf, makeDir, makeObserver, nudgeUntil,
+} = require('./observer.rig');
+
+test.after(cleanup);
+
+test('a root is rescued by continuity: moved ground keeps its rootId and every channel', () => {
+  const holder = makeDir('move-holder');
+  const A = path.join(holder, 'A');
+  fs.mkdirSync(path.join(A, 'sub'), { recursive: true });
+  fs.writeFileSync(path.join(A, 'doc.md'), 'doc');
+  fs.writeFileSync(path.join(A, 'sub', 'deep.md'), 'deep');
+
+  const { observer, events } = makeObserver();
+  const root = observer.enrollRoot(A);
+  const fileIds = observer.filesForRoot(root.rootId).map((row) => row.fileId).sort();
+
+  fs.renameSync(A, path.join(holder, 'B'));
+
+  // A same-parent rename discovered by a SCAN — no doorbell delivered
+  // anything. The undecided address gets the one shared decision (the
+  // same directed look the address doorbell makes), so the scan itself
+  // follows: one move, zero unavailable moments, every channel intact.
+  // Two independent doorbells can learn of one rename in either order;
+  // this is the order where the scan wins, and the verdict is the same.
+  const interim = events.length;
+  observer.scanNow();
+  assert.deepEqual(eventsOf(events.slice(interim), 'root.moved').map((event) => [event.from, event.to]),
+    [[A, path.join(holder, 'B')]], 'the scan followed the same-parent rename by witnessed continuity');
+  assert.deepEqual(eventsOf(events.slice(interim), 'root.unavailable'), [],
+    'a followed move is never an availability transition — whichever entrance decides it');
+  assert.deepEqual(observer.filesForRoot(root.rootId).map((row) => row.fileId).sort(), fileIds,
+    'every channel rode the follow');
+
+  // The move the directed look cannot claim: the ground departs beyond
+  // the parent. The look is same-parent by design, so the address is
+  // undecidable and a scan CONCLUDES NOTHING about identity. Beliefs
+  // freeze (a conclusion of "deleted" would end the very channels the
+  // rescue preserves), the referee convicts the divergence, and the
+  // next enrollment moment naming the new address is what rescues.
+  const elsewhere = makeDir('move-elsewhere');
+  const C = path.join(elsewhere, 'C');
+  fs.renameSync(path.join(holder, 'B'), C);
+  const frozen = events.length;
+  observer.scanNow();
+  assert.deepEqual(events.slice(frozen).map((event) => event.type), ['root.unavailable'],
+    'a scan over the departed address concludes NOTHING about identity — its one honest fact is presence');
+  observer.scanNow();
+  assert.equal(events.length, frozen + 1, 'presence is a transition, never a repeat');
+  assert.deepEqual(observer.filesForRoot(root.rootId).map((row) => row.fileId).sort(), fileIds,
+    'every channel is intact through the frozen interim');
+  assert.ok(observer.verify(root.rootId).length > 0,
+    'the referee convicts the divergence honestly while the address is undecided');
+
+  const before = events.length;
+  const rescued = observer.enrollRoot(C);
+  assert.equal(rescued.rootId, root.rootId, 'same ground, same root — the address is not the identity');
+  assert.equal(rescued.path, C);
+  assert.deepEqual(eventsOf(events.slice(before), 'root.moved').map((event) => [event.from, event.to]),
+    [[path.join(holder, 'B'), C]], 'the move is one event');
+  assert.deepEqual(eventsOf(events.slice(before), 'root.available').map((event) => event.path),
+    [C], 'presence restored symmetrically: available announces the return, at the new address');
+  assert.deepEqual(observer.filesForRoot(root.rootId).map((row) => row.fileId).sort(), fileIds,
+    'every channel survived: a move is an address change, never death and rebirth');
+  assert.deepEqual(events.slice(before).filter((event) => event.type.startsWith('file.')), [],
+    'and the follow-up scan proves silence');
+  assert.equal(observer.listRoots().length, 1, 'no ghost stayed behind at the old address');
+
+  // The old address reoccupied by a stranger: continuity already claimed
+  // the moved ground, and the lookalike is its own new ground.
+  fs.mkdirSync(A);
+  const stranger = observer.enrollRoot(A);
+  assert.notEqual(stranger.rootId, root.rootId, 'presence at an old address proves nothing about identity');
+});
+
+test('startup is an entrance too: a same-parent rename made while nothing ran is followed by the catch-up scan', () => {
+  // The rename happens while the observer is stopped — no doorbell will
+  // ever announce it. Start's catch-up scan finds the undecided address
+  // and makes the same decision every entrance makes: witnessed
+  // continuity claims the new name, one move, zero unavailable moments.
+  // (Beyond the parent the catch-up scan still freezes — proven above —
+  // so reattachment remains the deciding act for real departures.)
+  const holder = makeDir('offline-rename');
+  const A = path.join(holder, 'A');
+  fs.mkdirSync(A);
+  fs.writeFileSync(path.join(A, 'doc.md'), 'doc');
+  const F = path.join(holder, 'F.md');
+  fs.writeFileSync(F, 'f');
+
+  const { observer, events } = makeObserver();
+  const dirRoot = observer.enrollRoot(A);
+  const fileRoot = observer.enrollRoot(F);
+  observer.start();
+  observer.stop();
+
+  fs.renameSync(A, path.join(holder, 'B'));
+  fs.renameSync(F, path.join(holder, 'G.md'));
+
+  const mark = events.length;
+  observer.start();
+  try {
+    assert.deepEqual(eventsOf(events.slice(mark), 'root.moved').map((event) => [event.rootId, event.to]).sort(),
+      [[dirRoot.rootId, path.join(holder, 'B')], [fileRoot.rootId, path.join(holder, 'G.md')]].sort(),
+      'the catch-up scan followed both kinds by their witnessed identity');
+    assert.deepEqual(eventsOf(events.slice(mark), 'root.unavailable'), [],
+      'no unavailable moment: continuity never broke, it was merely unobserved');
+    const rows = observer.listRoots();
+    assert.equal(rows.find((row) => row.rootId === dirRoot.rootId).path, path.join(holder, 'B'));
+    assert.equal(rows.find((row) => row.rootId === fileRoot.rootId).path, path.join(holder, 'G.md'));
+  } finally {
+    observer.stop();
+  }
+});
+
+test('the parent observes address changes: a live rename is followed, a departure is honest absence', async () => {
+  const holder = makeDir('addr-live');
+  const A = path.join(holder, 'A');
+  fs.mkdirSync(A);
+  fs.writeFileSync(path.join(A, 'doc.md'), 'doc');
+
+  const { observer, events } = makeObserver({ settleMs: 40 });
+  const root = observer.enrollRoot(A);
+  observer.start();
+  try {
+    // Prime: fs.watch streams start asynchronously, so prove the
+    // doorbells are live before staging address changes — a rename fired
+    // into a not-yet-live stream would measure the exam's own race, not
+    // the law.
+    const primed = await nudgeUntil(
+      () => fs.writeFileSync(path.join(A, 'prime.md'), `p${Math.random()}`),
+      () => events.some((event) => event.type === 'file.created' && event.path === 'prime.md'),
+    );
+    assert.ok(primed, 'the doorbells are live');
+    const fileIds = observer.filesForRoot(root.rootId).map((row) => row.fileId).sort();
+
+    // The common move: the user renames the folder in place. The parent
+    // doorbell rings, the root's own inode identifies it under the usual
+    // claim rules, and the rescue follows — the entity observes content,
+    // the parent observes the address, and no unavailable moment ever
+    // happened because continuity never broke.
+    const B = path.join(holder, 'B');
+    let renamed = false;
+    const followed = await nudgeUntil(
+      () => { if (!renamed) { fs.renameSync(A, B); renamed = true; } },
+      () => eventsOf(events, 'root.moved').length > 0,
+    );
+    assert.ok(followed, 'the parent doorbell heard the rename and continuity followed it');
+    assert.deepEqual(eventsOf(events, 'root.moved').map((event) => [event.rootId, event.to]),
+      [[root.rootId, B]]);
+    assert.deepEqual(eventsOf(events, 'root.unavailable'), [],
+      'a followed move is never an availability transition');
+    assert.deepEqual(observer.filesForRoot(root.rootId).map((row) => row.fileId).sort(), fileIds,
+      'every channel rode the follow');
+
+    // The move the parent cannot follow: the ground leaves for another
+    // parent entirely. Presence reports honestly; identity stays frozen
+    // for the enrollment moment that eventually names the new address.
+    // The re-nudge is a consumer ask (scanNow) — doorbells are lossy BY
+    // CONTRACT, and the rescue re-arms its watchers asynchronously, so
+    // the absence FACT is what this proves, never stream promptness.
+    const elsewhere = makeDir('addr-elsewhere');
+    let departed = false;
+    const absent = await nudgeUntil(
+      () => {
+        if (!departed) {
+          fs.renameSync(B, path.join(elsewhere, 'C'));
+          departed = true;
+        } else {
+          observer.scanNow(root.rootId);
+        }
+      },
+      () => eventsOf(events, 'root.unavailable').length > 0,
+    );
+    assert.ok(absent, 'departure to unwatched ground is honest absence, never silence');
+    const row = observer.listRoots().find((member) => member.rootId === root.rootId);
+    assert.equal(row.present, false, 'presence is separate evidence');
+    assert.deepEqual(observer.filesForRoot(root.rootId).map((member) => member.fileId).sort(), fileIds,
+      'identity persists through absence: not one channel closed');
+  } finally {
+    observer.stop();
+  }
+});
+
+test('the parent doorbell hears every delivery: a rename naming only the NEW name still rings the address check', () => {
+  // A rename of A to B may lawfully deliver ONE event naming only "B".
+  // A doorbell that filtered for "A" decided the answer before looking
+  // and discarded the only live signal address watching has. This exam
+  // injects exactly that delivery, deterministically, through a fake
+  // fs.watch — the live exam above cannot pin which names the OS sends.
+  const { deliver, restore } = installFakeWatch();
+  try {
+    const holder = makeDir('newname');
+    const A = path.join(holder, 'A');
+    fs.mkdirSync(A);
+    fs.writeFileSync(path.join(A, 'doc.md'), 'doc');
+    const F = path.join(holder, 'F.md');
+    fs.writeFileSync(F, 'f');
+    const { observer, events } = makeObserver();
+    const dirRoot = observer.enrollRoot(A);
+    const fileRoot = observer.enrollRoot(F);
+    observer.start();
+    try {
+      // The directory root: renamed in place, delivered as the new name
+      // only. The address check identifies it by inode and follows —
+      // live, with no unavailable moment.
+      fs.renameSync(A, path.join(holder, 'B'));
+      deliver(holder, 'B');
+      assert.deepEqual(eventsOf(events, 'root.moved').map((event) => [event.rootId, event.to]),
+        [[dirRoot.rootId, path.join(holder, 'B')]],
+        'the new-name delivery was heard and continuity followed it');
+      assert.deepEqual(eventsOf(events, 'root.unavailable'), []);
+
+      // The single-file root: same delivery shape, same law. Its channel
+      // row's WITNESSED inode claims the new name under the exactly-one
+      // rule, so the rename is followed live too. The atomic save first:
+      // the root row's enrollment-time inode is now stale, so only the
+      // channel row's identity can make the claim.
+      fs.writeFileSync(path.join(holder, '.F.tmp'), 'f2');
+      fs.renameSync(path.join(holder, '.F.tmp'), F);
+      // THE WITNESS: the scan that makes the channel row current. The
+      // follow below rides exactly this evidence — the unwitnessed-burst
+      // exam proves that without it, the same rename is honest absence.
+      observer.scanNow(fileRoot.rootId);
+      fs.renameSync(F, path.join(holder, 'G.md'));
+      deliver(holder, 'G.md');
+      assert.deepEqual(eventsOf(events, 'root.moved').map((event) => [event.rootId, event.to]),
+        [[dirRoot.rootId, path.join(holder, 'B')], [fileRoot.rootId, path.join(holder, 'G.md')]],
+        'the file root followed its rename by its channel inode');
+      assert.deepEqual(eventsOf(events, 'root.unavailable'), [],
+        'no unavailable moment for either kind: continuity never broke');
+      const followed = observer.listRoots().find((row) => row.rootId === fileRoot.rootId);
+      assert.equal(followed.path, path.join(holder, 'G.md'), 'the address is the new name');
+    } finally {
+      observer.stop();
+    }
+  } finally {
+    restore();
+  }
+});
+
+test('the file follow refuses to guess: ambiguity and departures beyond the parent are honest absence', () => {
+  // The exactly-one rule is the whole safety of the file follow. A
+  // hardlink beside a rename puts TWO entries on one inode — guessing
+  // between them could bind the root to the wrong name — and a move to
+  // another directory leaves no candidate at all. Both refuse; absence
+  // is honest, and the explicit reattachment that names the new address
+  // is the act that decides.
+  const { deliver, restore } = installFakeWatch();
+  try {
+    const holder = makeDir('refuse');
+    const elsewhere = makeDir('refuse-elsewhere');
+    const F = path.join(holder, 'F.md');
+    fs.writeFileSync(F, 'f');
+    fs.linkSync(F, path.join(holder, 'H.md')); // a hardlink: same inode, second entry
+    const { observer, events } = makeObserver();
+    const fileRoot = observer.enrollRoot(F);
+    observer.start();
+    try {
+      // Two candidates wear the root's inode after the rename: refused.
+      fs.renameSync(F, path.join(holder, 'G.md'));
+      deliver(holder, 'G.md');
+      assert.deepEqual(eventsOf(events, 'root.moved'), [], 'ambiguity never rebinds');
+      assert.deepEqual(eventsOf(events, 'root.unavailable').map((event) => event.rootId),
+        [fileRoot.rootId], 'two entries on one inode is a refusal to guess, live');
+
+      // Explicit reattachment names the address; the same identity wakes.
+      const rescued = observer.enrollRoot(path.join(holder, 'G.md'));
+      assert.equal(rescued.rootId, fileRoot.rootId, 'the same identity, reattached');
+      assert.deepEqual(eventsOf(events, 'root.available').map((event) => event.rootId),
+        [fileRoot.rootId], 'presence is symmetric: the return is announced too');
+
+      // A departure beyond the parent leaves no candidate: the directed
+      // look is same-parent by design, so this is honest absence. (The
+      // reattachment above lawfully emitted its own root.moved — the
+      // mark scopes these assertions to the departure alone.)
+      const mark = events.length;
+      fs.unlinkSync(path.join(holder, 'H.md'));
+      fs.renameSync(path.join(holder, 'G.md'), path.join(elsewhere, 'G.md'));
+      deliver(holder, 'unrelated.txt'); // a foreign name rings the address check directly
+      assert.deepEqual(eventsOf(events.slice(mark), 'root.moved'), [], 'no candidate, no rebind');
+      assert.deepEqual(eventsOf(events.slice(mark), 'root.unavailable').map((event) => event.rootId),
+        [fileRoot.rootId], 'a cross-parent move stays honest absence');
+    } finally {
+      observer.stop();
+    }
+  } finally {
+    restore();
+  }
+});
+
+test('the follow rides witnessed continuity: an unwitnessed atomic-save burst is honest absence, and a re-add is a new identity', () => {
+  // Continuity is EVIDENCE, never clairvoyance. An atomic save mints a
+  // new inode at the address; until a scan WITNESSES it, the channel row
+  // still holds the old one. Rename the file away inside that settle
+  // window and the ground at the new name wears an inode nothing ever
+  // observed — and its bytes changed in the same burst, so no witness of
+  // any kind ties it to the channel. The law refuses to guess: honest
+  // absence, live. And the explicit re-add that names the new address
+  // enrolls a NEW identity — matching names never prove identity, and
+  // with no witnessed binding there is honestly nothing to rescue. The
+  // witnessed exam above is the follow promise's true extent.
+  const { deliver, restore } = installFakeWatch();
+  try {
+    const holder = makeDir('unwitnessed');
+    const F = path.join(holder, 'F.md');
+    fs.writeFileSync(F, 'v1');
+    // The settle window, held open: the scheduled witness never runs
+    // inside this exam — deterministically, not by racing a timer.
+    const { observer, events } = makeObserver({ settleMs: 60_000 });
+    const fileRoot = observer.enrollRoot(F);
+    observer.start();
+    try {
+      fs.writeFileSync(path.join(holder, '.F.tmp'), 'v2');
+      fs.renameSync(path.join(holder, '.F.tmp'), F); // the unwitnessed save: new inode, new bytes
+      deliver(holder, 'F.md'); // schedules the witness — held open above
+      fs.renameSync(F, path.join(holder, 'G.md'));
+      deliver(holder, 'G.md');
+      assert.deepEqual(eventsOf(events, 'root.moved'), [], 'no witnessed evidence, no follow');
+      assert.deepEqual(eventsOf(events, 'root.unavailable').map((event) => event.rootId),
+        [fileRoot.rootId], 'the unwitnessed burst is honest absence, live');
+      const row = observer.listRoots().find((member) => member.rootId === fileRoot.rootId);
+      assert.equal(row.path, F, 'identity frozen at its recorded address');
+      const readded = observer.enrollRoot(path.join(holder, 'G.md'));
+      assert.notEqual(readded.rootId, fileRoot.rootId,
+        'nothing witnessed ties the new ground to the old channel: the re-add is honestly a new identity');
+    } finally {
+      observer.stop();
+    }
+  } finally {
+    restore();
+  }
+});
+
+test('a family moves as one durable transition: a failure mid-move tears nothing', () => {
+  // Inject a failure into the second root-path write. Without one
+  // transaction over the whole family this tears the store — the parent
+  // at the new address, a nested territory left behind at the old.
+  const db = new Database(':memory:');
+  const realPrepare = db.prepare.bind(db);
+  let failAfter = Infinity;
+  db.prepare = (sql) => {
+    const stmt = realPrepare(sql);
+    if (!/UPDATE observer_roots SET path/.test(sql)) return stmt;
+    const realRun = stmt.run.bind(stmt);
+    stmt.run = (...args) => {
+      if (--failAfter < 0) throw new Error('injected: failure mid-move');
+      return realRun(...args);
+    };
+    return stmt;
+  };
+
+  const holder = makeDir('torn-holder');
+  const A = path.join(holder, 'A');
+  fs.mkdirSync(path.join(A, 'vendor'), { recursive: true });
+  execFileSync('git', ['init', '-q'], { cwd: path.join(A, 'vendor') });
+  const { observer } = makeObserver({ db });
+  const root = observer.enrollRoot(A);
+  const oldPaths = observer.listRoots().map((row) => row.path).sort();
+  assert.equal(oldPaths.length, 2, 'the family: the root and its nested territory');
+
+  const B = path.join(holder, 'B');
+  fs.renameSync(A, B);
+  failAfter = 1; // the first write lands, the second throws
+  assert.throws(() => observer.enrollRoot(B), /injected/);
+  assert.deepEqual(observer.listRoots().map((row) => row.path).sort(), oldPaths,
+    'nothing tore: the whole family still holds the previous truth');
+
+  failAfter = Infinity;
+  const rescued = observer.enrollRoot(B);
+  assert.equal(rescued.rootId, root.rootId, 'the retry is the same rescue, whole');
+  assert.ok(observer.listRoots().every((row) => row.path === B || row.path.startsWith(`${B}/`)),
+    'and the whole family lives at the new address');
+});
+
+test('a reoccupied address concludes nothing until named: scans freeze, the referee convicts, re-adding adopts', () => {
+  const holder = makeDir('reoccupy-holder');
+  const A = path.join(holder, 'A');
+  fs.mkdirSync(A);
+  fs.writeFileSync(path.join(A, 'old.md'), 'old');
+
+  const { observer, events } = makeObserver();
+  const root = observer.enrollRoot(A);
+  const fileIds = observer.filesForRoot(root.rootId).map((row) => row.fileId);
+
+  // The ground is destroyed and different ground reoccupies the address.
+  // Presence proves nothing about identity: the scan cannot tell a
+  // reoccupation from a move-away-plus-lookalike, so it concludes
+  // nothing and the referee carries the conviction.
+  fs.rmSync(A, { recursive: true });
+  fs.mkdirSync(A);
+  fs.writeFileSync(path.join(A, 'new.md'), 'new');
+  const interim = events.length;
+  observer.scanNow();
+  assert.deepEqual(events.slice(interim).map((event) => event.type), ['root.unavailable'],
+    'frozen: no identity conclusions at an undecided address — one presence fact, nothing more');
+  assert.deepEqual(observer.filesForRoot(root.rootId).map((row) => row.fileId), fileIds,
+    'the recorded channels stay — deletion is never inferred at the horizon\'s edge');
+  assert.ok(observer.verify(root.rootId).length > 0, 'the referee convicts the divergence');
+
+  // Naming the address again is the deliberate act that resolves it:
+  // the root adopts the ground it was told is its own, and a full scan
+  // turns the frozen beliefs into honest evidence.
+  const adopted = observer.enrollRoot(A);
+  assert.equal(adopted.rootId, root.rootId, 'adoption keeps the root: identity is the enrollment, not the inode');
+  assert.deepEqual(observer.filesForRoot(root.rootId).map((row) => row.relPath), ['new.md'],
+    'and the adopting scan reconciles the new ground honestly');
+  assert.deepEqual(observer.verify(root.rootId), [], 'settled truth');
+});
+
+// --- single-file roots: the smallest ground -------------------------------
+
+test('a single file is the smallest root: one channel, the file laws, path-first identity', () => {
+  const dir = makeDir('solo');
+  const filePath = path.join(dir, 'notes.md');
+  fs.writeFileSync(filePath, 'v1');
+
+  const { observer, events } = makeObserver();
+  const root = observer.enrollRoot(filePath);
+  assert.equal(root.kind, 'file');
+  assert.deepEqual(eventsOf(events, 'file.created').map((event) => [event.path, event.rootId]),
+    [['', root.rootId]], 'enrollment births the one channel; its address is the root itself');
+  const fileId = eventsOf(events, 'file.created')[0].fileId;
+
+  fs.writeFileSync(filePath, 'v2');
+  observer.scanNow(root.rootId);
+  assert.equal(eventsOf(events, 'file.changed').length, 1, 'a content change is one event');
+
+  // An atomic save: a fresh inode renamed over the path. Path-first
+  // identity absorbs the churn — same channel, one change event.
+  fs.writeFileSync(path.join(dir, '.notes.tmp'), 'v3');
+  fs.renameSync(path.join(dir, '.notes.tmp'), filePath);
+  observer.scanNow(root.rootId);
+  const changes = eventsOf(events, 'file.changed');
+  assert.equal(changes.length, 2);
+  assert.ok(changes.every((event) => event.fileId === fileId), 'the channel survived the inode churn');
+  assert.deepEqual(observer.verify(root.rootId), [], 'the referee agrees with the observer');
+
+  fs.writeFileSync(filePath, 'v4-behind-its-back');
+  assert.deepEqual(observer.verify(root.rootId).map((m) => m.problem),
+    ['stale: disk moved, the observer did not notice'],
+    'the referee re-hashes the one path with none of the observer\'s machinery');
+  observer.scanNow(root.rootId);
+
+  // Absence at the root's OWN address is the horizon's edge: moved away
+  // and deleted look identical from here, so the scan concludes nothing —
+  // the channel freezes, the referee convicts, and only an enrollment
+  // moment or explicit removal decides.
+  fs.rmSync(filePath);
+  observer.scanNow(root.rootId);
+  assert.deepEqual(eventsOf(events, 'file.deleted'), [],
+    'absent root ground closes nothing: deletion is never inferred at the horizon\'s edge');
+  assert.deepEqual(eventsOf(events, 'root.unavailable').map((event) => event.rootId), [root.rootId],
+    'identity persists; local presence is separate evidence — absence is one honest fact');
+  assert.deepEqual(observer.verify(root.rootId).map((m) => m.problem),
+    ['ghost: the observer believes in a file disk no longer has'],
+    'the referee convicts the divergence instead');
+
+  // Recreation under the same address is the same channel: the file laws
+  // absorb the churn, and continuity never broke.
+  fs.writeFileSync(filePath, 'v5-recreated');
+  observer.scanNow(root.rootId);
+  const last = eventsOf(events, 'file.changed').at(-1);
+  assert.equal(last.fileId, fileId, 'the channel outlived the gap: path-first identity claims the recreation');
+  assert.deepEqual(eventsOf(events, 'root.available').map((event) => event.rootId), [root.rootId],
+    'presence is symmetric: the return is announced, never inferred from unrelated events');
+  assert.deepEqual(observer.verify(root.rootId), [], 'and the referee sees settled truth');
+});
+
+test('the parent-directory doorbell hears a single-file root live', async () => {
+  const dir = makeDir('solo-live');
+  const filePath = path.join(dir, 'watched.md');
+  fs.writeFileSync(filePath, 'first');
+
+  const { observer, events } = makeObserver({ settleMs: 40 });
+  const root = observer.enrollRoot(filePath);
+  observer.start();
+  try {
+    const heard = await nudgeUntil(
+      () => fs.writeFileSync(filePath, 'second'),
+      () => eventsOf(events, 'file.changed').length > 0,
+    );
+    assert.ok(heard, 'a write reached the observer through the parent-directory doorbell');
+    assert.equal(eventsOf(events, 'file.changed')[0].rootId, root.rootId);
+  } finally {
+    observer.stop();
+  }
+});