amalgm 0.1.245 → 0.1.246

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

@@ -0,0 +1,657 @@
+'use strict';
+
+/**
+ * The observer's CORE exams: enrollment births channels, and the compare
+ * function decides what a change is — content (an edit is one event
+ * carrying both hashes), identity (a rename keeps the channel, a path
+ * claims over an inode), echo suppression, doorbell routing, and
+ * recovery from a dead watcher. The other seams have their own suites:
+ * links, roots, territory — all over the shared rig.
+ */
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const { EventEmitter } = require('events');
+const fs = require('fs');
+const path = require('path');
+
+const Database = require('better-sqlite3');
+const { createObserver } = require('../observer');
+const { diffRootState } = require('../observer/scan');
+const {
+  cleanup, eventsOf, makeDir, makeObserver, nudgeUntil,
+} = require('./observer.rig');
+
+test.after(cleanup);
+
+// --- enrollment -----------------------------------------------------------
+
+test('enrollment births one channel per enrollable file, with content hashes', () => {
+  const dir = makeDir('enroll');
+  fs.writeFileSync(path.join(dir, 'notes.md'), 'hello');
+  fs.mkdirSync(path.join(dir, 'sub'));
+  fs.writeFileSync(path.join(dir, 'sub', 'plan.md'), 'world');
+
+  const { observer, events } = makeObserver();
+  const root = observer.enrollRoot(dir);
+
+  const created = eventsOf(events, 'file.created');
+  assert.deepEqual(created.map((event) => event.path).sort(), ['notes.md', 'sub/plan.md']);
+  assert.ok(created.every((event) => /^[0-9a-f]{64}$/.test(event.hash)));
+  assert.ok(created.every((event) => event.rootId === root.rootId));
+  assert.deepEqual(eventsOf(events, 'dir.created').map((event) => event.path), ['sub'],
+    'a directory is a channel too: enrollment births it beside the files');
+  assert.equal(events.length, 3);
+});
+
+test('two directories exchange names between scans: both channels follow their inodes', () => {
+  const dir = makeDir('dir-swap');
+  fs.mkdirSync(path.join(dir, 'north'));
+  fs.mkdirSync(path.join(dir, 'south'));
+  const { observer, events } = makeObserver();
+  const root = observer.enrollRoot(dir);
+  const before = new Map(observer.dirsForRoot(root.rootId).map((row) => [row.relPath, row.dirId]));
+
+  // The swap crosses between two scans; the walk sees only the endpoints.
+  fs.renameSync(path.join(dir, 'north'), path.join(dir, 'limbo'));
+  fs.renameSync(path.join(dir, 'south'), path.join(dir, 'north'));
+  fs.renameSync(path.join(dir, 'limbo'), path.join(dir, 'south'));
+  const mark = events.length;
+  observer.scanNow(root.rootId);
+
+  const renamed = eventsOf(events.slice(mark), 'dir.renamed');
+  assert.deepEqual(renamed.map((event) => [event.from, event.to, event.dirId]).sort(),
+    [['north', 'south', before.get('north')], ['south', 'north', before.get('south')]].sort(),
+    'physical continuity claims first: a known inode at a new address IS the move');
+  assert.equal(events.length - mark, renamed.length, 'nothing else spoke');
+  assert.deepEqual(observer.verify(root.rootId), []);
+
+  // The other rule is untouched: a never-seen inode at a known address is
+  // recreation — the same channel wearing a new inode, silently.
+  fs.rmSync(path.join(dir, 'north'), { recursive: true });
+  fs.mkdirSync(path.join(dir, 'north'));
+  const quiet = events.length;
+  observer.scanNow(root.rootId);
+  assert.equal(events.length, quiet, 'recreation under an old name is silence');
+  assert.equal(observer.dirsForRoot(root.rootId).find((row) => row.relPath === 'north').dirId,
+    before.get('south'), 'the recreated directory wears the same channel');
+});
+
+test('a torn dir batch changes nothing: the swap lands as one transaction or not at all', () => {
+  const dir = makeDir('dir-swap-torn');
+  fs.mkdirSync(path.join(dir, 'north'));
+  fs.mkdirSync(path.join(dir, 'south'));
+  const db = new Database(':memory:');
+  const { observer, events } = makeObserver({ db });
+  const root = observer.enrollRoot(dir);
+  const before = new Map(observer.dirsForRoot(root.rootId).map((row) => [row.relPath, row.dirId]));
+
+  fs.renameSync(path.join(dir, 'north'), path.join(dir, 'limbo'));
+  fs.renameSync(path.join(dir, 'south'), path.join(dir, 'north'));
+  fs.renameSync(path.join(dir, 'limbo'), path.join(dir, 'south'));
+
+  // The crash strikes after the first mover has landed, injected through
+  // the database's own law so the rollback is proven where it must hold.
+  db.exec(`CREATE TRIGGER torn BEFORE INSERT ON observer_dirs
+    WHEN NEW.rel_path = 'south' BEGIN SELECT RAISE(ABORT, 'injected mid-batch failure'); END`);
+  const mark = events.length;
+  assert.throws(() => observer.scanNow(root.rootId), /injected mid-batch failure/);
+  assert.equal(events.length, mark, 'no doorbell rang for truth that never landed');
+  assert.deepEqual(
+    new Map(observer.dirsForRoot(root.rootId).map((row) => [row.relPath, row.dirId])), before,
+    'a torn batch changes nothing: the previous truth is whole');
+
+  // The retry is an ordinary scan: the same batch, both original channels.
+  db.exec('DROP TRIGGER torn');
+  observer.scanNow(root.rootId);
+  const renamed = eventsOf(events.slice(mark), 'dir.renamed');
+  assert.deepEqual(renamed.map((event) => [event.from, event.to, event.dirId]).sort(),
+    [['north', 'south', before.get('north')], ['south', 'north', before.get('south')]].sort(),
+    'identity survives the crash: the retry crosses with the original channels');
+  assert.deepEqual(observer.verify(root.rootId), []);
+});
+
+test('an observer store with some of its tables is loss, never a fresh start', () => {
+  const dir = makeDir('partial-store');
+  fs.mkdirSync(path.join(dir, 'alpha'));
+  fs.writeFileSync(path.join(dir, 'alpha', 'note.txt'), 'hello');
+  const db = new Database(':memory:');
+  const { observer } = makeObserver({ db });
+  observer.enrollRoot(dir);
+
+  // A complete schema reopens freely: the same database carries a second
+  // observer (a restart) without ceremony.
+  assert.doesNotThrow(() => createObserver({ db, emit: () => {} }),
+    'an established store with its whole schema is an ordinary reopen');
+
+  // One table gone while the others survive: CREATE IF NOT EXISTS would
+  // silently regrow it empty — every channel it held ended behind a root
+  // id that still checks out as the witness. The store convicts at open
+  // instead: an established store either has its complete schema or it
+  // is loss.
+  db.exec('DROP TABLE observer_dirs');
+  assert.throws(() => createObserver({ db, emit: () => {} }), /identity evidence lost/,
+    'a partial store is loss, never a fresh start');
+});
+
+test('an unstamped pre-links store is an older schema generation, refused distinctly from loss', () => {
+  const db = new Database(':memory:');
+  db.exec(`CREATE TABLE observer_roots (root_id TEXT PRIMARY KEY, path TEXT NOT NULL UNIQUE, kind TEXT NOT NULL);
+    CREATE TABLE observer_files (file_id TEXT PRIMARY KEY);
+    CREATE TABLE observer_dirs (dir_id TEXT PRIMARY KEY);`);
+  assert.throws(() => createObserver({ db, emit: () => {} }), /schema generation 0/,
+    'a legitimate older schema is never confused with partial loss — migration is an explicit act');
+});
+
+test('enrollment skips excluded directories and secret files', () => {
+  const dir = makeDir('exclude');
+  fs.writeFileSync(path.join(dir, 'keep.md'), 'keep');
+  fs.writeFileSync(path.join(dir, '.env'), 'SECRET=1');
+  fs.writeFileSync(path.join(dir, 'id_rsa'), 'private');
+  fs.mkdirSync(path.join(dir, 'node_modules'));
+  fs.writeFileSync(path.join(dir, 'node_modules', 'dep.js'), 'x');
+
+  const { observer, events } = makeObserver();
+  observer.enrollRoot(dir);
+
+  assert.deepEqual(eventsOf(events, 'file.created').map((event) => event.path), ['keep.md']);
+});
+
+test('re-enrolling the same root (any spelling) is idempotent', () => {
+  const dir = makeDir('idempotent');
+  fs.writeFileSync(path.join(dir, 'a.md'), 'a');
+
+  const { observer, events } = makeObserver();
+  const first = observer.enrollRoot(dir);
+  const second = observer.enrollRoot(`${dir}${path.sep}`);
+  assert.equal(first.rootId, second.rootId);
+  assert.equal(eventsOf(events, 'file.created').length, 1);
+});
+
+// --- the compare function: content ----------------------------------------
+
+test('an external edit is exactly one file.changed carrying old and new hash', () => {
+  const dir = makeDir('edit');
+  const file = path.join(dir, 'notes.md');
+  fs.writeFileSync(file, 'v1');
+
+  const { observer, events } = makeObserver();
+  observer.enrollRoot(dir);
+  const born = eventsOf(events, 'file.created')[0];
+  events.length = 0;
+
+  fs.writeFileSync(file, 'v2 with more bytes');
+  observer.scanNow();
+
+  assert.equal(events.length, 1);
+  const [changed] = events;
+  assert.equal(changed.type, 'file.changed');
+  assert.equal(changed.fileId, born.fileId);
+  assert.equal(changed.previousHash, born.hash);
+  assert.notEqual(changed.hash, born.hash);
+});
+
+test('a burst of writes between scans collapses to one event with final content', () => {
+  const dir = makeDir('burst');
+  const file = path.join(dir, 'notes.md');
+  fs.writeFileSync(file, 'v1');
+
+  const { observer, events } = makeObserver();
+  observer.enrollRoot(dir);
+  events.length = 0;
+
+  fs.writeFileSync(file, 'v2');
+  fs.writeFileSync(file, 'v3');
+  fs.writeFileSync(file, 'v4-final');
+  observer.scanNow();
+
+  assert.equal(eventsOf(events, 'file.changed').length, 1);
+});
+
+test('a touch that rewrites identical bytes is silence', () => {
+  const dir = makeDir('touch');
+  const file = path.join(dir, 'notes.md');
+  fs.writeFileSync(file, 'same');
+
+  const { observer, events } = makeObserver();
+  observer.enrollRoot(dir);
+  events.length = 0;
+
+  const future = new Date(Date.now() + 5_000);
+  fs.utimesSync(file, future, future); // mtime moves, bytes do not
+  observer.scanNow();
+  assert.equal(events.length, 0);
+
+  observer.scanNow(); // and the stat advance persisted: still silence
+  assert.equal(events.length, 0);
+});
+
+test('an atomic save (write temp, rename over) keeps the channel id', () => {
+  const dir = makeDir('atomic');
+  const file = path.join(dir, 'notes.md');
+  fs.writeFileSync(file, 'v1');
+
+  const { observer, events } = makeObserver();
+  observer.enrollRoot(dir);
+  const born = eventsOf(events, 'file.created')[0];
+  events.length = 0;
+
+  // New inode lands at the same path — editors do this on every save.
+  const temp = path.join(dir, 'notes.md.tmp-manual');
+  fs.writeFileSync(temp, 'v2');
+  fs.renameSync(temp, file);
+  observer.scanNow();
+
+  const changed = eventsOf(events, 'file.changed');
+  assert.equal(changed.length, 1);
+  assert.equal(changed[0].fileId, born.fileId);
+  assert.equal(eventsOf(events, 'file.created').length, 0);
+  assert.equal(eventsOf(events, 'file.deleted').length, 0);
+});
+
+// --- the compare function: identity ----------------------------------------
+
+test('a rename keeps the channel id: one file.renamed, no delete, no create', () => {
+  const dir = makeDir('rename');
+  fs.writeFileSync(path.join(dir, 'old.md'), 'content');
+
+  const { observer, events } = makeObserver();
+  observer.enrollRoot(dir);
+  const born = eventsOf(events, 'file.created')[0];
+  events.length = 0;
+
+  fs.renameSync(path.join(dir, 'old.md'), path.join(dir, 'new.md'));
+  observer.scanNow();
+
+  assert.deepEqual(events.map((event) => event.type), ['file.renamed']);
+  assert.equal(events[0].fileId, born.fileId);
+  assert.equal(events[0].from, 'old.md');
+  assert.equal(events[0].to, 'new.md');
+});
+
+test('a move across directories with a simultaneous edit is rename + changed on one channel', () => {
+  const dir = makeDir('move-edit');
+  fs.mkdirSync(path.join(dir, 'a'));
+  fs.mkdirSync(path.join(dir, 'b'));
+  fs.writeFileSync(path.join(dir, 'a', 'doc.md'), 'v1');
+
+  const { observer, events } = makeObserver();
+  observer.enrollRoot(dir);
+  const born = eventsOf(events, 'file.created')[0];
+  events.length = 0;
+
+  fs.renameSync(path.join(dir, 'a', 'doc.md'), path.join(dir, 'b', 'doc.md'));
+  fs.appendFileSync(path.join(dir, 'b', 'doc.md'), ' plus v2');
+  observer.scanNow();
+
+  assert.deepEqual(events.map((event) => event.type), ['file.renamed', 'file.changed']);
+  assert.ok(events.every((event) => event.fileId === born.fileId));
+});
+
+test('deletion removes the channel: one file.deleted', () => {
+  const dir = makeDir('delete');
+  fs.writeFileSync(path.join(dir, 'gone.md'), 'bye');
+
+  const { observer, events } = makeObserver();
+  observer.enrollRoot(dir);
+  const born = eventsOf(events, 'file.created')[0];
+  events.length = 0;
+
+  fs.rmSync(path.join(dir, 'gone.md'));
+  observer.scanNow();
+
+  assert.deepEqual(events.map((event) => event.type), ['file.deleted']);
+  assert.equal(events[0].fileId, born.fileId);
+});
+
+test('path claims the channel over inode: swap-in at an old path is a change, not a rename', () => {
+  const dir = makeDir('path-wins');
+  fs.writeFileSync(path.join(dir, 'a.md'), 'original a');
+
+  const { observer, events } = makeObserver();
+  observer.enrollRoot(dir);
+  const born = eventsOf(events, 'file.created')[0];
+  events.length = 0;
+
+  // a.md renamed away AND an unrelated file lands at a.md in the same window.
+  fs.renameSync(path.join(dir, 'a.md'), path.join(dir, 'archived.md'));
+  fs.writeFileSync(path.join(dir, 'a.md'), 'brand new occupant');
+  observer.scanNow();
+
+  // The path a.md is still occupied, so it keeps its channel (rule 1); the
+  // inode rescue never runs because the row was never orphaned. archived.md
+  // is a new channel. Deterministic, and no bytes are ever lost.
+  const renames = eventsOf(events, 'file.renamed');
+  assert.equal(renames.length, 0);
+  const changed = eventsOf(events, 'file.changed');
+  assert.equal(changed.length, 1);
+  assert.equal(changed[0].fileId, born.fileId);
+  assert.equal(changed[0].path, 'a.md');
+  const created = eventsOf(events, 'file.created');
+  assert.equal(created.length, 1);
+  assert.equal(created[0].path, 'archived.md');
+});
+
+test('diffRootState never guesses on ambiguous inode matches', () => {
+  const row = (fileId, relPath, inode) => ({
+    fileId, relPath, device: 1, inode, size: 1, mtimeMs: 1, contentHash: 'h',
+  });
+  const entry = (relPath, inode) => ({ relPath, device: 1, inode, size: 2, mtimeMs: 2 });
+
+  // Two orphan rows share an inode; one orphan entry matches it: no rescue.
+  const ambiguous = diffRootState(
+    [row('f1', 'a.md', 7), row('f2', 'b.md', 7)],
+    [entry('c.md', 7)],
+  );
+  assert.equal(ambiguous.renames.length, 0);
+  assert.equal(ambiguous.creates.length, 1);
+  assert.equal(ambiguous.deletes.length, 2);
+
+  // Exactly one on each side: rescued.
+  const clean = diffRootState([row('f1', 'a.md', 7)], [entry('c.md', 7)]);
+  assert.equal(clean.renames.length, 1);
+  assert.equal(clean.creates.length, 0);
+  assert.equal(clean.deletes.length, 0);
+});
+
+test('stats alone never prove unchanged: a same-tick write is always re-checked', () => {
+  // The racy case: the file's mtime equals the instant we last read its
+  // bytes, so a same-size write may hide behind identical stats. The stat
+  // shortcut must refuse; only mtime strictly before the read is proof.
+  const row = {
+    fileId: 'f', relPath: 'a.md', device: 1, inode: 5,
+    size: 2, mtimeMs: 1000, contentHash: 'h', hashedAtMs: 1000,
+  };
+  const entry = { relPath: 'a.md', device: 1, inode: 5, size: 2, mtimeMs: 1000 };
+
+  const racy = diffRootState([row], [entry]);
+  assert.equal(racy.checks.length, 1);
+  assert.equal(racy.unchanged, 0);
+
+  const proven = diffRootState([{ ...row, hashedAtMs: 1001 }], [entry]);
+  assert.equal(proven.checks.length, 0);
+  assert.equal(proven.unchanged, 1);
+
+  // A row with no recorded read instant can prove nothing.
+  const unknown = diffRootState([{ ...row, hashedAtMs: null }], [entry]);
+  assert.equal(unknown.checks.length, 1);
+});
+
+test('a doorbell-named path overrules the stat shortcut', () => {
+  const row = {
+    fileId: 'f', relPath: 'a.md', device: 1, inode: 5,
+    size: 4, mtimeMs: 1000, contentHash: 'h', hashedAtMs: 2000,
+  };
+  const entry = { relPath: 'a.md', device: 1, inode: 5, size: 4, mtimeMs: 1000 };
+
+  // Quiet scan: stats identical, mtime provably before our read — skipped.
+  assert.equal(diffRootState([row], [entry]).unchanged, 1);
+
+  // The watcher named this exact path: hashed, no matter what stats claim.
+  const hinted = diffRootState([row], [entry], new Set(['a.md']));
+  assert.equal(hinted.checks.length, 1);
+  assert.equal(hinted.unchanged, 0);
+});
+
+test('rapid same-size writes between scans are never missed', () => {
+  const dir = makeDir('racy-e2e');
+  const file = path.join(dir, 'notes.md');
+  fs.writeFileSync(file, 'v0');
+
+  const { observer, events } = makeObserver();
+  observer.enrollRoot(dir);
+  events.length = 0;
+
+  // Same byte count every write, scans issued as fast as possible — the
+  // window where stats cannot distinguish writes. Every version must land.
+  for (let i = 1; i <= 20; i += 1) {
+    fs.writeFileSync(file, `v${String(i).padStart(2, '0')}`);
+    observer.scanNow();
+    const changed = eventsOf(events, 'file.changed');
+    assert.equal(changed.length, i, `write ${i} was missed by detection`);
+  }
+});
+
+// --- echo suppression -------------------------------------------------------
+
+test('noteWrite makes our own write invisible to the next scan', () => {
+  const dir = makeDir('echo');
+  const file = path.join(dir, 'notes.md');
+  fs.writeFileSync(file, 'v1');
+
+  const { observer, events } = makeObserver();
+  observer.enrollRoot(dir);
+  events.length = 0;
+
+  fs.writeFileSync(file, 'v2 written by the runtime itself');
+  observer.noteWrite(file);
+  observer.scanNow();
+
+  assert.equal(events.length, 0);
+});
+
+test('noteWrite on a brand-new file registers the channel without an event', () => {
+  const dir = makeDir('echo-create');
+  const { observer, events } = makeObserver();
+  observer.enrollRoot(dir);
+  events.length = 0;
+
+  const file = path.join(dir, 'made-by-us.md');
+  fs.writeFileSync(file, 'runtime artifact');
+  observer.noteWrite(file);
+  observer.scanNow();
+
+  assert.equal(events.length, 0);
+  const [root] = observer.listRoots();
+  assert.equal(observer.filesForRoot(root.rootId).length, 1);
+});
+
+// --- doorbells --------------------------------------------------------------
+
+test('the doorbell detects an external edit without scanNow being called', async () => {
+  const dir = makeDir('doorbell');
+  const file = path.join(dir, 'notes.md');
+  fs.writeFileSync(file, 'v1');
+
+  const { observer, events } = makeObserver({ settleMs: 50 });
+  observer.enrollRoot(dir);
+  observer.start();
+  events.length = 0;
+
+  await nudgeUntil(
+    () => fs.writeFileSync(file, 'v2 from outside'),
+    () => eventsOf(events, 'file.changed').length > 0,
+  );
+  observer.stop();
+
+  assert.equal(eventsOf(events, 'file.changed').length, 1);
+});
+
+test('a same-size edit with a backdated mtime is still detected via the doorbell', async () => {
+  const dir = makeDir('backdate');
+  const file = path.join(dir, 'notes.md');
+  fs.writeFileSync(file, 'aaaa');
+
+  const { observer, events } = makeObserver({ settleMs: 50 });
+  observer.enrollRoot(dir);
+  observer.start();
+  events.length = 0;
+
+  // Same size, same inode, and the mtime set BACK to its old value: every
+  // stat looks untouched, so only the watcher's word says anything happened.
+  const before = fs.statSync(file);
+  await nudgeUntil(
+    () => {
+      fs.writeFileSync(file, 'bbbb');
+      fs.utimesSync(file, before.atime, before.mtime);
+    },
+    () => eventsOf(events, 'file.changed').length > 0,
+  );
+  observer.stop();
+
+  assert.equal(eventsOf(events, 'file.changed').length, 1);
+});
+
+test('a repo root forwards raw doorbells instantly with classified areas', async () => {
+  const dir = makeDir('repo');
+  fs.mkdirSync(path.join(dir, '.git'));
+  fs.writeFileSync(path.join(dir, '.git', 'HEAD'), 'ref: refs/heads/main');
+  fs.writeFileSync(path.join(dir, 'main.ts'), 'v1');
+
+  const { observer, events } = makeObserver({ settleMs: 50 });
+  observer.enrollRoot(dir, { kind: 'repo' });
+  observer.start();
+  // Birth is one discovery; start()'s catch-up rings the repo unconditionally
+  // (the observer cannot know what happened while nobody watched — the
+  // follower's ids turn "maybe" into silence).
+  assert.equal(eventsOf(events, 'repo.discovered').length, 1);
+  assert.equal(eventsOf(events, 'repo.changed').length, 1);
+  events.length = 0;
+
+  await nudgeUntil(
+    () => {
+      fs.writeFileSync(path.join(dir, 'main.ts'), 'v2');
+      fs.writeFileSync(path.join(dir, '.git', 'HEAD'), 'ref: refs/heads/other');
+    },
+    () => new Set(eventsOf(events, 'repo.changed').flatMap((event) => event.areas)).size === 2,
+  );
+  observer.stop();
+
+  const areas = new Set(eventsOf(events, 'repo.changed').flatMap((event) => event.areas));
+  assert.deepEqual([...areas].sort(), ['git', 'worktree']);
+  assert.equal(events.filter((event) => event.type.startsWith('file.')).length, 0);
+});
+
+test('a repo born inside a live workspace is detected and claims its ground', async () => {
+  const dir = makeDir('live-birth');
+  fs.writeFileSync(path.join(dir, 'notes.md'), 'files territory');
+
+  const { observer, events } = makeObserver({ settleMs: 25 });
+  observer.enrollRoot(dir);
+  observer.start();
+  events.length = 0;
+
+  // The audited blind spot: a repo appears inside a watched workspace.
+  fs.mkdirSync(path.join(dir, 'proj'));
+  fs.writeFileSync(path.join(dir, 'proj', 'app.ts'), 'code');
+  fs.mkdirSync(path.join(dir, 'proj', '.git'));
+  await nudgeUntil(
+    () => fs.writeFileSync(path.join(dir, 'proj', '.git', 'HEAD'), 'ref: refs/heads/main'),
+    () => eventsOf(events, 'repo.discovered').length > 0,
+  );
+  const discovered = eventsOf(events, 'repo.discovered');
+  assert.equal(discovered.length, 1, 'the new repo was never discovered');
+  assert.equal(discovered[0].path, path.join(dir, 'proj'));
+  events.length = 0;
+
+  // Churn inside the new territory rings the repo doorbell, never files.
+  await nudgeUntil(
+    () => fs.writeFileSync(path.join(dir, 'proj', 'app.ts'), 'checkout churn'),
+    () => eventsOf(events, 'repo.changed').length > 0,
+  );
+  observer.stop();
+
+  assert.ok(eventsOf(events, 'repo.changed').length >= 1);
+  assert.ok(eventsOf(events, 'repo.changed').every((event) => event.rootId === discovered[0].rootId));
+  assert.equal(events.filter((event) => event.type.startsWith('file.')).length, 0);
+});
+
+// --- recovery ---------------------------------------------------------------
+
+test('a dead watcher degrades honestly and the rescan still finds the change', () => {
+  const dir = makeDir('degraded');
+  fs.writeFileSync(path.join(dir, 'notes.md'), 'v1');
+
+  const { observer, events } = makeObserver();
+  observer.enrollRoot(dir);
+  observer.start();
+  events.length = 0;
+
+  // Simulate total watcher loss: stop() closes watchers; an explicit scan
+  // (any consumer-driven event) still finds the truth.
+  observer.stop();
+  fs.writeFileSync(path.join(dir, 'notes.md'), 'v2 missed by any doorbell');
+  observer.scanNow();
+
+  assert.equal(eventsOf(events, 'file.changed').length, 1);
+});
+
+test('a fresh observer over the same store resumes channels instead of re-birthing them', () => {
+  const dir = makeDir('resume');
+  fs.writeFileSync(path.join(dir, 'notes.md'), 'v1');
+
+  const db = new Database(':memory:');
+  const firstEvents = [];
+  const first = createObserver({ db, emit: (event) => firstEvents.push(event) });
+  first.enrollRoot(dir);
+  const born = firstEvents.find((event) => event.type === 'file.created');
+
+  // New process, same db: the edit made "while we were dead" is one change
+  // on the same channel — not a delete + create, not a re-birth.
+  fs.writeFileSync(path.join(dir, 'notes.md'), 'v2 while offline');
+  const secondEvents = [];
+  const second = createObserver({ db, emit: (event) => secondEvents.push(event) });
+  second.enrollRoot(dir);
+  second.scanNow();
+
+  assert.deepEqual(secondEvents.map((event) => event.type), ['file.changed']);
+  assert.equal(secondEvents[0].fileId, born.fileId);
+});
+
+test('start() is the catch-up event: offline edits surface without any explicit scan', () => {
+  const dir = makeDir('catch-up');
+  const file = path.join(dir, 'notes.md');
+  fs.writeFileSync(file, 'v1');
+
+  const db = new Database(':memory:');
+  const firstEvents = [];
+  const first = createObserver({ db, emit: (event) => firstEvents.push(event) });
+  first.enrollRoot(dir);
+  const born = firstEvents.find((event) => event.type === 'file.created');
+
+  fs.writeFileSync(file, 'v2 while nobody was running');
+  const events = [];
+  const second = createObserver({ db, emit: (event) => events.push(event) });
+  second.start(); // no scanNow call: starting IS the event
+  second.stop();
+
+  assert.deepEqual(events.map((event) => event.type), ['file.changed']);
+  assert.equal(events[0].fileId, born.fileId);
+});
+
+test('watcher death rebuilds the doorbell and reconciles the gap once', () => {
+  const realWatch = fs.watch;
+  const fakes = [];
+  fs.watch = () => {
+    const fake = new EventEmitter();
+    fake.close = () => {};
+    fakes.push(fake);
+    return fake;
+  };
+  try {
+    const dir = makeDir('revive');
+    const file = path.join(dir, 'notes.md');
+    fs.writeFileSync(file, 'v1');
+
+    const { observer, events } = makeObserver();
+    observer.enrollRoot(dir);
+    observer.start();
+    assert.equal(fakes.length, 2, 'two doorbells per top-level root: content (recursive) and address (parent)');
+    events.length = 0;
+
+    // The change lands while the doorbell is broken. The death itself is
+    // the event: rebuild, then one reconciling scan finds the change.
+    fs.writeFileSync(file, 'v2 during the dead window');
+    fakes[0].emit('error', new Error('watcher lost'));
+
+    assert.deepEqual(events.map((event) => event.type), ['file.changed']);
+    assert.equal(fakes.length, 3); // a fresh content doorbell was installed
+    assert.equal(observer.status()[0].watching, true);
+
+    fakes[0].emit('error', new Error('echo of the same death'));
+    assert.equal(fakes.length, 3); // dead is dead: no rebuild storm
+    observer.stop();
+  } finally {
+    fs.watch = realWatch;
+  }
+});