amalgm 0.1.245 → 0.1.246

package/runtime/scripts/amalgm-mcp/observer/index.js

@@ -0,0 +1,1146 @@
+'use strict';
+
+/**
+ * The observer: the single place where a local change is born.
+ *
+ * Wiring only — watch.js rings, scan.js compares, store.js remembers, and
+ * this file turns compare results into events. A doorbell never emits
+ * anything itself; it only makes the next scan happen sooner (axiom 3).
+ *
+ * Territory: a .git claims its subtree. Files territory gets channels and
+ * hashes — directories included: a directory is a channel with physical
+ * identity and no content of its own, so folder renames survive by inode
+ * exactly like file renames, and empty folders exist the moment disk holds
+ * them. Repo territory gets a raw, instant doorbell (`repo.changed`) — the
+ * observer never editorializes repo events, because quieting and identity
+ * belong to the follower (repocard/follow.js), and a delayed doorbell would
+ * blind its torn-read guard. Territory is decided by disk, not by callers:
+ * a .git appearing anywhere converts the ground under it, and its
+ * disappearance converts it back.
+ *
+ * Nested repositories are territories too: a repo inside a repo is simply
+ * another repo. A census at lifecycle moments (enrollment, conversion,
+ * catch-up scans) plus doorbells live make each nested boundary its own
+ * root with its own watcher; the parent stays silent for a child's ground.
+ * A doorbell's filename never proves anything — it only says where to
+ * look, and disk decides what it means (a repo moved in whole rings only
+ * the directory that landed, never a path spelling ".git").
+ *
+ * Enrollment is amalgm's OWN policy (`shouldEnroll`), applied uniformly to
+ * files territory and repo boundaries alike. Git's ignore rules never
+ * decide it (entity axiom 2, docs/entity-model.md): a gitignored worktree
+ * or nested repo in enrolled ground is a territory; a repo inside
+ * amalgm-excluded ground (node_modules, caches) is not.
+ */
+
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+
+const { createApply } = require('./apply');
+const { createContinuity } = require('./continuity');
+const { createStore } = require('./store');
+const { censusBoundaries, censusLinks, diffDirState, diffLinkState, diffRootState, gitDirTruth, walkRoot } = require('./scan');
+const { createVerify } = require('./verify');
+const { watchDir, watchRecursive } = require('./watch');
+const { adapterFor } = require('../adapters');
+const { lookFailed } = require('../adapters/truth');
+
+// The production stitch (ratified 2026-08-02): the observer's content
+// decision reads file truth through the adapter socket — the same
+// three-state answer every surface speaks. Both file kinds declare the
+// same truth (bytes), so either selects the one filesystem adapter;
+// the text/binary split is classification policy downstream.
+const fileTruth = adapterFor('file.binary').rails.detect.truth;
+
+const DEFAULT_SETTLE_MS = 200;
+// Surviving suspicion backs off exponentially from settleMs to here:
+// permanently unsettled ground costs a heartbeat, never a hot loop.
+const RETRY_CAP_MS = 60_000;
+
+function defaultShouldEnroll(relPath) {
+  return require('../workspace/tree/inclusion').shouldEnroll(relPath);
+}
+
+function createObserver(options) {
+  const {
+    db,
+    emit,
+    shouldEnroll = defaultShouldEnroll,
+    settleMs = DEFAULT_SETTLE_MS,
+    // The entity-content cache is injected by the registration composition
+    // root. Detection still owns the observed hash; this hook only retains
+    // the exact bytes behind that hash for the later cloud rail.
+    captureContent = null,
+    // The doorbell implementation. Injectable so tests can ring through the
+    // production wiring what fs.watch rarely delivers (a null filename).
+    watch = watchRecursive,
+  } = options;
+  if (!db) throw new Error('createObserver requires { db }');
+  if (typeof emit !== 'function') throw new Error('createObserver requires { emit }');
+
+  const store = createStore(db);
+  // rootId -> { kind, watcher, settleTimer, dirtyPaths, checkAll, territories }
+  const live = new Map();
+  let started = false;
+
+  function publish(event) {
+    try {
+      emit(event);
+    } catch (error) {
+      console.warn('[Observer] emit failed:', error?.message || error);
+    }
+  }
+
+  /** A file's settled bytes right now, through the adapter socket —
+   * their fingerprint AND their kind, from the one read that produced
+   * both — or null when its truth is absent, unsettled, or no longer a
+   * file's. For the writer's own record (noteWrite), settled-or-null
+   * is the whole question; the SCAN's content read is scanContent
+   * below, where unsettled suspicion survives, and the referee
+   * (verify) reads the three states directly. */
+  function safeContent(absPath) {
+    const read = fileTruth(absPath);
+    if (read.truth !== 'present' || read.state.kind !== 'file') return null;
+    try {
+      captureContent?.({ filePath: absPath, contentHash: read.state.sha256 });
+    } catch {
+      return null;
+    }
+    return { contentHash: read.state.sha256, binary: read.state.binary };
+  }
+
+  /** One pending look per root, earliest due wins: a doorbell asks at
+   * settleMs and a surviving suspicion asks at its backed-off delay —
+   * a shorter ask replaces a longer wait (new evidence resets a
+   * backoff), while a pending sooner look absorbs later asks (rings
+   * inside the settle window still batch into one scan). */
+  function armSettle(root, state, delay = settleMs) {
+    const due = Date.now() + delay;
+    if (state.settleTimer) {
+      if (due >= state.settleDue) return;
+      clearTimeout(state.settleTimer);
+    }
+    state.settleDue = due;
+    state.settleTimer = setTimeout(() => {
+      state.settleTimer = null;
+      try {
+        scanNow(root.rootId);
+      } catch (error) {
+        console.warn(`[Observer] scan failed for "${root.path}":`, error?.message || error);
+      }
+    }, delay);
+    state.settleTimer.unref?.();
+  }
+
+  /** The one scheduling rule for suspicion that survives a scan:
+   * retries coalesce on the root's single pending look and back off
+   * exponentially toward RETRY_CAP_MS. Any new doorbell evidence
+   * resets the delay — ring() asks at settleMs, which replaces a
+   * longer wait in armSettle. */
+  function armRetry(root, state) {
+    if (state.settleTimer) return; // coalesce: one escalation per armed look
+    const delay = state.retryMs;
+    state.retryMs = Math.min(RETRY_CAP_MS, state.retryMs * 2);
+    armSettle(root, state, delay);
+  }
+
+  /** The scan's content read, all three truths honored: settled bytes
+   * for a present file; null when the ground is absent or no longer a
+   * file's — the walk's next look decides; and on UNSETTLED the
+   * suspicion SURVIVES: the path returns to the dirty set and the
+   * retry re-arms, so the read that reaches present or absent is
+   * scheduled by the observer itself — an unsettled read means "read
+   * again", and detection is who reads again. One transiently
+   * unreadable moment can never swallow a change. */
+  function scanContent(root, relPath) {
+    const read = fileTruth(path.join(root.path, relPath));
+    if (read.truth === 'unsettled') {
+      const state = live.get(root.rootId);
+      if (state) {
+        state.dirtyPaths.add(relPath);
+        armRetry(root, state);
+      }
+      return null;
+    }
+    if (read.truth !== 'present' || read.state.kind !== 'file') return null;
+    try {
+      captureContent?.({ filePath: path.join(root.path, relPath), contentHash: read.state.sha256 });
+    } catch {
+      // A file that changed between the observer's hash and the immutable
+      // capture is not a stable cloud head yet. Preserve suspicion and read
+      // again; recording the hash without its bytes would create a dangling
+      // cloud entity head.
+      const state = live.get(root.rootId);
+      if (state) {
+        state.dirtyPaths.add(relPath);
+        armRetry(root, state);
+      }
+      return null;
+    }
+    return { contentHash: read.state.sha256, binary: read.state.binary };
+  }
+
+  /** Symlinks are never followed, matching the walks. */
+  function isDirectory(absPath) {
+    try {
+      return fs.lstatSync(absPath).isDirectory();
+    } catch {
+      return false;
+    }
+  }
+
+  // Compare results become truth in apply.js — events + store rows,
+  // deterministic order, per channel kind. The content read is injected:
+  // scanContent keeps unsettled suspicion on the root's retry, above.
+  const { applyDiff, applyDirDiff, applyLinkDiff } = createApply({ store, publish, scanContent });
+
+  function childRepoRoots(filesRoot) {
+    return store.listRoots().filter(
+      (root) => root.kind === 'repo' && root.path.startsWith(`${filesRoot.path}/`),
+    );
+  }
+
+  /**
+   * Make the enrolled repo roots match the territories the walk reported:
+   * a new .git births a repo root, a vanished one dies. The files walk
+   * already skipped the claimed subtrees, so channels and territories can
+   * never overlap.
+   */
+  function reconcileTerritories(root, state, repoDirs) {
+    const claimed = new Set(repoDirs);
+    for (const relDir of repoDirs) {
+      const childPath = path.join(root.path, relDir);
+      if (store.rootByPath(childPath)) continue;
+      birthRepo(childPath);
+    }
+    for (const child of childRepoRoots(root)) {
+      const relDir = child.path.slice(root.path.length + 1);
+      if (claimed.has(relDir)) continue;
+      const territory = gitDirTruth(child.path);
+      if (territory !== 'absent') {
+        claimed.add(relDir); // deeper than the walk descends, or unreadable — only absence buries
+        if (territory === 'unsettled' && state) armRetry(root, state); // and unsettled stays pending
+        continue;
+      }
+      detach(child.rootId);
+      store.removeRoot(child.rootId);
+      publish({ type: 'repo.removed', rootId: child.rootId, path: child.path });
+    }
+    if (state) state.territories = claimed;
+  }
+
+  /**
+   * Birth a repo territory: enroll, watch, announce, census its own children.
+   *
+   * TEMPORARY IDENTITY CONTRACT: minting a fresh rootId here (and deleting
+   * it in removeRepoChild) is internal behavior, not the model. Under the
+   * entity axioms (docs/entity-model.md) a nested folder ↔ repo change is a
+   * TYPE TRANSITION on one permanent UUID; that lands with folder entities.
+   * Standalone roots already behave correctly (becomeRepo/becomeFiles keep
+   * their rootId) — do not build on the nested births' identity churn.
+   */
+  function birthRepo(childPath) {
+    let stat = null;
+    try {
+      stat = fs.lstatSync(childPath);
+    } catch {
+      stat = null; // vanished mid-birth; identity arrives with the next census
+    }
+    const child = {
+      rootId: crypto.randomUUID(), path: childPath, kind: 'repo',
+      device: stat?.dev ?? null, inode: stat?.ino ?? null,
+    };
+    store.addRoot(child);
+    attach(child);
+    publish({ type: 'repo.discovered', rootId: child.rootId, path: child.path });
+    censusRepoRoot(child);
+    return child;
+  }
+
+  function removeRepoChild(child) {
+    detach(child.rootId);
+    store.removeRoot(child.rootId);
+    publish({ type: 'repo.removed', rootId: child.rootId, path: child.path });
+  }
+
+  /**
+   * Nested repositories are territories too — a repo inside a repo is just
+   * another repo. Census the ground for `.git` boundaries, birth the
+   * missing, bury the dead. Runs at lifecycle moments (enrollment,
+   * conversion, catch-up scans), never on a timer; between moments the
+   * `.git` doorbells in ring() carry the news live.
+   */
+  function censusRepoRoot(root) {
+    const state = live.get(root.rootId);
+    const { boundaries, unsettled } = censusBoundaries(root.path, shouldEnroll);
+    const claimed = new Set(boundaries);
+    for (const relDir of boundaries) {
+      const childPath = path.join(root.path, relDir);
+      if (!store.rootByPath(childPath)) birthRepo(childPath);
+    }
+    for (const child of store.listRoots()) {
+      if (child.kind !== 'repo' || child.rootId === root.rootId) continue;
+      if (!child.path.startsWith(`${root.path}/`)) continue;
+      const relDir = child.path.slice(root.path.length + 1);
+      if (claimed.has(relDir)) continue;
+      if ([...claimed].some((owned) => relDir.startsWith(`${owned}/`))) continue; // a child's child
+      const territory = gitDirTruth(child.path);
+      if (territory !== 'absent') {
+        claimed.add(relDir); // existence wins — and only absence buries
+        if (territory === 'unsettled' && state) armRetry(root, state);
+        continue;
+      }
+      removeRepoChild(child);
+    }
+    // Unlisted ground may hide a boundary the census could not see:
+    // suspicion stays pending until the whole ground can be read.
+    if (unsettled.length > 0 && state) armRetry(root, state);
+    if (state) state.territories = claimed;
+  }
+
+  /** The root itself grew a .git: every channel closes, one repo is born. */
+  function becomeRepo(root, state) {
+    const rows = store.filesForRoot(root.rootId)
+      .sort((a, b) => (a.relPath < b.relPath ? -1 : 1));
+    for (const row of rows) {
+      store.removeFile(row.fileId);
+      publish({ type: 'file.deleted', rootId: root.rootId, fileId: row.fileId, path: row.relPath });
+    }
+    for (const row of store.linksForRoot(root.rootId)) {
+      store.removeLink(row.linkId);
+      publish({ type: 'link.deleted', rootId: root.rootId, linkId: row.linkId, path: row.relPath });
+    }
+    for (const row of store.dirsForRoot(root.rootId)) {
+      store.removeDir(row.dirId);
+      publish({ type: 'dir.deleted', rootId: root.rootId, dirId: row.dirId, path: row.relPath });
+    }
+    store.setRootKind(root.rootId, 'repo');
+    if (state) {
+      state.kind = 'repo';
+      state.dirtyPaths.clear();
+      state.checkAll = false;
+      state.territories = new Set();
+    }
+    publish({ type: 'repo.discovered', rootId: root.rootId, path: root.path });
+    censusRepoRoot(root);
+  }
+
+  /** A repo root's .git is gone: the ground reverts to whoever encloses it. */
+  function becomeFiles(root, state) {
+    publish({ type: 'repo.removed', rootId: root.rootId, path: root.path });
+    const parent = store.listRoots()
+      .filter((other) => other.rootId !== root.rootId && root.path.startsWith(`${other.path}/`))
+      .sort((a, b) => b.path.length - a.path.length)[0]; // nearest encloser decides
+    if (parent && parent.kind === 'repo') {
+      // Born inside repo territory, returned to it: the ground is the
+      // parent's worktree again, and its next capture is the reclaim.
+      detach(root.rootId);
+      store.removeRoot(root.rootId);
+      live.get(parent.rootId)?.territories.delete(root.path.slice(parent.path.length + 1));
+      publish({ type: 'repo.changed', rootId: parent.rootId, areas: ['worktree'] });
+      return;
+    }
+    if (parent) {
+      // Born from a files root, returned to it: the parent's next scan
+      // reclaims the files as creates.
+      detach(root.rootId);
+      store.removeRoot(root.rootId);
+      live.get(parent.rootId)?.territories.delete(root.path.slice(parent.path.length + 1));
+      scanFilesRoot(parent);
+      return;
+    }
+    store.setRootKind(root.rootId, 'files');
+    if (state) state.kind = 'files';
+    scanFilesRoot({ ...root, kind: 'files' });
+  }
+
+  function scanFilesRoot(root, { allowRootRepository = false } = {}) {
+    // Drain the doorbell's named hints first: anything that rings during the
+    // walk below belongs to the next scan, not this one.
+    const state = live.get(root.rootId);
+    const checkAll = Boolean(state?.checkAll);
+    const rung = state ? new Set(state.dirtyPaths) : new Set();
+    if (state) {
+      state.dirtyPaths.clear();
+      state.checkAll = false;
+    }
+
+    const { files: entries, dirs, links, repoDirs, unsettled } = walkRoot(
+      root.path,
+      shouldEnroll,
+      { allowRootRepository },
+    );
+    if (repoDirs.includes('')) {
+      becomeRepo(root, state);
+      return;
+    }
+    reconcileTerritories(root, state, repoDirs);
+
+    // Only present or absent may conclude: ground the walk could not
+    // read keeps every belief beneath it — a delete is a conclusion,
+    // and none may be drawn there — while the suspicion stays pending
+    // on the root's backed-off retry.
+    const underUnsettled = (relPath) =>
+      unsettled.some((dir) => dir === '' || relPath === dir || relPath.startsWith(`${dir}/`));
+    const concluded = (diff) => (unsettled.length === 0 ? diff
+      : { ...diff, deletes: diff.deletes.filter((row) => !underUnsettled(row.relPath)) });
+    if (unsettled.length > 0 && state) armRetry(root, state);
+
+    applyDirDiff(root, concluded(diffDirState(store.dirsForRoot(root.rootId), dirs)));
+    applyLinkDiff(root, concluded(diffLinkState(store.linksForRoot(root.rootId), links)));
+    const rows = store.filesForRoot(root.rootId);
+    const mustCheck = checkAll ? new Set(entries.map((entry) => entry.relPath)) : rung;
+    applyDiff(root, concluded(diffRootState(rows, entries, mustCheck)));
+  }
+
+  /**
+   * A single-ground root: one channel, the same laws, the smallest ground
+   * there is. The root's path IS the ground, its relPath is '' — and disk
+   * decides the channel's kind each scan: a regular file feeds the file
+   * compare (path claims the channel, so an atomic save's inode churn is
+   * absorbed; the racily-clean stat excuse and the doorbell-named-must-hash
+   * rule apply verbatim), a symlink feeds the link compare (the written
+   * target is the whole payload, read fresh, never followed — an
+   * explicitly added pointer is a root of the pointer kind). Ground that
+   * is neither never reaches this scan: the root's own address is the
+   * evidence horizon's edge, so its absence is undecidable and freezes
+   * upstream (addressUndecided) rather than closing the channel.
+   */
+  function scanFileRoot(root) {
+    const state = live.get(root.rootId);
+    const checkAll = Boolean(state?.checkAll);
+    const rung = state ? new Set(state.dirtyPaths) : new Set();
+    if (state) {
+      state.dirtyPaths.clear();
+      state.checkAll = false;
+    }
+    let stat = null;
+    try {
+      stat = fs.lstatSync(root.path);
+    } catch {
+      stat = null;
+    }
+    const entries = stat && stat.isFile()
+      ? [{ relPath: '', device: stat.dev, inode: stat.ino, size: stat.size, mtimeMs: Math.floor(stat.mtimeMs) }]
+      : [];
+    let linkEntries = [];
+    if (stat && stat.isSymbolicLink()) {
+      try {
+        linkEntries = [{ relPath: '', device: stat.dev, inode: stat.ino, target: fs.readlinkSync(root.path) }];
+      } catch (error) {
+        // Vanished mid-read is honest absence (the empty compare below
+        // concludes it); a failed look concludes nothing — the one
+        // channel keeps its belief and the retry reads again.
+        if (lookFailed(error).truth === 'unsettled') {
+          if (state) armRetry(root, state);
+          return;
+        }
+        linkEntries = [];
+      }
+    }
+    applyLinkDiff(root, diffLinkState(store.linksForRoot(root.rootId), linkEntries));
+    const mustCheck = checkAll ? new Set(entries.map((entry) => entry.relPath)) : rung;
+    applyDiff(root, diffRootState(store.filesForRoot(root.rootId), entries, mustCheck));
+  }
+
+  // Continuity questions and the presence bit live in continuity.js;
+  // the ACTIONS a verdict triggers (rebindRoot, decideUndecidedAddress)
+  // stay here, because they re-aim watchers and scans.
+  const {
+    addressUndecided, findMovedRoot, markAbsent, markPresent, rootIdentity,
+  } = createContinuity({ store, publish });
+
+  /**
+   * The rescue: same ground, new address. The root — and every enrolled
+   * territory inside it, whose store rows record absolute paths — moves
+   * as an ADDRESS ONLY: rootId, channels, and bindings all survive, and
+   * the follow-up scan proves silence when the ground truly just moved.
+   */
+  function rebindRoot(root, newPath) {
+    const oldPath = root.path;
+    const family = store.listRoots()
+      .filter((row) => row.rootId === root.rootId || row.path.startsWith(`${oldPath}/`));
+    // Truth first, as one transition — the whole family lands or none of
+    // it does, so a failure mid-move tears nothing. Doorbells re-aim only
+    // after truth has landed, exactly like the directory batches inside.
+    store.moveRoots(family.map((member) => ({
+      rootId: member.rootId,
+      path: member.rootId === root.rootId ? newPath : newPath + member.path.slice(oldPath.length),
+    })));
+    for (const member of family) {
+      detach(member.rootId);
+      attach(store.listRoots().find((row) => row.rootId === member.rootId));
+    }
+    publish({ type: 'root.moved', rootId: root.rootId, from: oldPath, to: newPath });
+    try {
+      scanNow(root.rootId);
+    } catch (error) {
+      console.warn(`[Observer] post-rebind scan failed for "${newPath}":`, error?.message || error);
+    }
+    return store.listRoots().find((row) => row.rootId === root.rootId);
+  }
+
+  function scanNow(rootId) {
+    const roots = rootId
+      ? store.listRoots().filter((root) => root.rootId === rootId)
+      : store.listRoots();
+    for (const stale of roots) {
+      // A scan earlier in this loop may have converted or removed a later
+      // root (territory handoff); the store row is the fresh truth.
+      const root = store.rootByPath(stale.path);
+      if (!root) continue;
+      if (addressUndecided(root)) {
+        // The same decision the address doorbell makes — whichever
+        // entrance finds the undecided address first, the verdict is
+        // identical, so a settle scan winning the race against a slow
+        // parent delivery follows instead of flapping presence.
+        decideUndecidedAddress(root);
+        continue;
+      }
+      markPresent(root);
+      if (root.kind === 'file') {
+        scanFileRoot(root);
+      } else if (root.kind === 'files') {
+        scanFilesRoot(root);
+      } else {
+        const territory = gitDirTruth(root.path);
+        if (territory === 'absent') {
+          becomeFiles(root, live.get(root.rootId));
+        } else if (territory === 'unsettled') {
+          // A failed look concludes nothing: the territory stands, the
+          // suspicion stays pending, and the settled look will bring
+          // the catch-up doorbell.
+          const state = live.get(root.rootId);
+          if (state) armRetry(root, state);
+        } else {
+          // Territory changes while nobody watched left no doorbell
+          // either: the catch-up census is their event.
+          censusRepoRoot(root);
+          // Catch-up semantics: the observer cannot know what happened to a
+          // repo while nobody watched; the follower's ids turn "maybe" into
+          // silence, so an unconditional doorbell is the honest answer.
+          publish({ type: 'repo.changed', rootId: root.rootId, areas: ['git', 'worktree'] });
+        }
+      }
+      // A scan that leaves no look pending resets the backoff: the
+      // next unsettled episode starts fresh from the settle delay.
+      const after = live.get(root.rootId);
+      if (after && !after.settleTimer) after.retryMs = settleMs;
+    }
+  }
+
+  function coveringTerritory(state, relPath) {
+    for (const territory of state.territories) {
+      if (relPath === territory || relPath.startsWith(`${territory}/`)) return territory;
+    }
+    return null;
+  }
+
+  function underTerritory(state, relPath) {
+    return coveringTerritory(state, relPath) !== null;
+  }
+
+  function ring(root, relPath) {
+    const state = live.get(root.rootId);
+    if (!state) return;
+    state.retryMs = settleMs; // new evidence resets a backoff
+
+    if (state.kind === 'file') {
+      // The parent-directory doorbell already filtered to this file (or
+      // to nothing named, which could be anything): the one channel is
+      // suspect either way, and a named event always hashes.
+      state.dirtyPaths.add('');
+      armSettle(root, state);
+      return;
+    }
+
+    if (state.kind === 'repo') {
+      const gitArea = relPath === null || relPath === '.git' || relPath.startsWith('.git/');
+      if (gitArea) {
+        const territory = gitDirTruth(root.path);
+        if (territory === 'absent') {
+          becomeFiles(root, state);
+          return;
+        }
+        if (territory === 'unsettled') {
+          // A failed look concludes nothing: no conversion, no doorbell
+          // forwarded on unknown ground — the retry looks again, and the
+          // settled look brings the catch-up doorbell.
+          armRetry(root, state);
+          return;
+        }
+      }
+      // The filename only says where to look; disk decides what it means.
+      // Four tiers, cheapest first; every check is a single shot on this
+      // event, never a poll. (Files roots need none of this: their scans
+      // re-walk the ground, and reconcileTerritories is their reconcile.)
+      if (relPath === null) {
+        // No name at all: the only honest reading is a full reconcile.
+        censusRepoRoot(root);
+      } else {
+        const territory = coveringTerritory(state, relPath);
+        if (territory !== null) {
+          // A live child territory's ground answers to its own root: its
+          // watcher rings it, its follower captures it. A dead boundary is
+          // territory news that never spells ".git" (a move-out rings only
+          // the directory that left): bury the child, the ground is the
+          // parent's worktree again, and the forward below is the reclaim.
+          const childPath = path.join(root.path, territory);
+          const childTruth = gitDirTruth(childPath);
+          if (childTruth !== 'absent') {
+            // Only absence buries — and an unsettled look keeps the news
+            // pending: the retry looks again, no second doorbell needed.
+            if (childTruth === 'unsettled') armRetry(root, state);
+            return;
+          }
+          const known = store.rootByPath(childPath);
+          if (known && known.kind === 'repo') removeRepoChild(known);
+          state.territories.delete(territory);
+        } else {
+          // Territories BELOW the named path: a move-out may name only an
+          // ancestor folder of a boundary (`mv vendor` away when the
+          // territory is vendor/lib). Existence is checked for every
+          // territory the named path contains.
+          for (const below of [...state.territories]) {
+            if (!below.startsWith(`${relPath}/`)) continue;
+            const belowPath = path.join(root.path, below);
+            const belowTruth = gitDirTruth(belowPath);
+            if (belowTruth !== 'absent') {
+              if (belowTruth === 'unsettled') armRetry(root, state); // only absence buries; unsettled stays pending
+              continue;
+            }
+            const known = store.rootByPath(belowPath);
+            if (known && known.kind === 'repo') removeRepoChild(known);
+            state.territories.delete(below);
+          }
+          // Unclaimed ground: any directory on the doorbell's path could be
+          // a boundary that never spelled ".git" (a move-in rings only the
+          // directory that landed; git init rings ".git/HEAD" under it).
+          // Walk the named path's prefixes. The nearest boundary claims;
+          // deeper ground is the child's own census's business.
+          const segments = relPath.split('/');
+          const gitIdx = segments.indexOf('.git');
+          const prefixEnd = gitIdx >= 0 ? gitIdx : segments.length;
+          let claimed = false;
+          let pruned = false;
+          for (let i = 1; i <= prefixEnd; i++) {
+            const rel = segments.slice(0, i).join('/');
+            // The policy prunes at the directory, exactly like the walks:
+            // excluded ground excludes everything under it, so the boundary
+            // may not be asked about point-wise.
+            if (!shouldEnroll(rel)) {
+              pruned = true;
+              break;
+            }
+            const childPath = path.join(root.path, rel);
+            const prefixTruth = gitDirTruth(childPath);
+            if (prefixTruth !== 'present') {
+              if (prefixTruth === 'unsettled') armRetry(root, state); // only presence births; unsettled stays pending
+              continue;
+            }
+            const known = store.rootByPath(childPath);
+            if (known) {
+              if (known.kind === 'repo') state.territories.add(rel); // heal a raced set
+            } else {
+              birthRepo(childPath);
+              state.territories.add(rel);
+            }
+            claimed = true;
+            break;
+          }
+          // A boundary may also sit DEEPER than the doorbell names (`mv
+          // pkg/` in when the repo lives at pkg/lib): when the named path
+          // is itself a plain directory on unclaimed, enrollable ground,
+          // walk it once for boundaries. The walk's paths are relative to
+          // the named directory, but the policy's contract is root-relative
+          // — re-prefix before asking, or a policy pruning `pkg/private`
+          // would not prune it here.
+          // (When gitIdx is -1 the loop's last prefix IS relPath, so an
+          // unpruned exit already vetted the named path itself.)
+          if (!claimed && !pruned && gitIdx === -1 && isDirectory(path.join(root.path, relPath))) {
+            const scopedEnroll = (rel) => shouldEnroll(`${relPath}/${rel}`);
+            const walked = censusBoundaries(path.join(root.path, relPath), scopedEnroll);
+            for (const sub of walked.boundaries) {
+              const rel = `${relPath}/${sub}`;
+              const childPath = path.join(root.path, rel);
+              if (!store.rootByPath(childPath)) {
+                birthRepo(childPath);
+                state.territories.add(rel);
+              }
+            }
+            // Unlisted ground may hide a boundary: suspicion stays pending.
+            if (walked.unsettled.length > 0) armRetry(root, state);
+          }
+        }
+      }
+      // Forwarded raw and instantly: quieting is the follower's job, and a
+      // delayed doorbell would blind its torn-read guard.
+      const areas = relPath === null
+        ? ['git', 'worktree']
+        : relPath === '.git' || relPath.startsWith('.git/') ? ['git'] : ['worktree'];
+      publish({ type: 'repo.changed', rootId: root.rootId, areas });
+      return;
+    }
+
+    // A child repo's own doorbell covers its territory — while the boundary
+    // is alive on disk. A dead one is territory news: fall through and let
+    // the scan's reconcile bury it and reclaim the ground.
+    const filesTerritory = relPath === null ? null : coveringTerritory(state, relPath);
+    if (filesTerritory !== null) {
+      const territoryTruth = gitDirTruth(path.join(root.path, filesTerritory));
+      if (territoryTruth === 'unsettled') {
+        armRetry(root, state); // no conclusion from a failed look — the retry decides
+        return;
+      }
+      if (territoryTruth === 'present') return;
+    }
+    // Enrollment policy applies to doorbells too — except .git itself: it is
+    // never enrollable, but its appearance is territory news and must scan.
+    const territoryNews = filesTerritory !== null
+      || (relPath !== null && relPath.split('/').includes('.git'));
+    if (relPath !== null && !territoryNews && !shouldEnroll(relPath)) return;
+    if (relPath === null) {
+      state.checkAll = true; // No filename given: every file is suspect.
+    } else if (!territoryNews) {
+      // A delivered event names its file; that file will be hashed no matter
+      // what its stats claim (timestamps can be backdated, doorbells can't).
+      state.dirtyPaths.add(relPath);
+    }
+    armSettle(root, state);
+  }
+
+  function openWatcher(root) {
+    // A single-file root's doorbell lives on its parent directory: a
+    // watcher on the file itself would follow the inode and go deaf on
+    // the first atomic save. The doorbell hears EVERYTHING in the parent
+    // — a rename may lawfully deliver only the NEW name — so events
+    // naming this file (or nothing, which could be anything) ring the
+    // content scan, and any foreign name is possible address news,
+    // answered by the cheap address check. Directory roots get the
+    // injected recursive doorbell.
+    if (root.kind === 'file') {
+      const name = path.basename(root.path);
+      return watchDir(path.dirname(root.path), (rung) => {
+        if (rung === null || rung === name) {
+          ring(root, rung);
+          return;
+        }
+        try {
+          checkAddress(root.rootId);
+        } catch (error) {
+          console.warn(`[Observer] address check failed for "${root.path}":`, error?.message || error);
+        }
+      }, () => reviveWatcher(root));
+    }
+    return watch(
+      root.path,
+      (relPath) => ring(root, relPath),
+      () => reviveWatcher(root),
+    );
+  }
+
+  /** A root enclosed by watched ground has its address observed already. */
+  function enclosed(root) {
+    return store.listRoots().some((other) =>
+      other.rootId !== root.rootId && root.path.startsWith(`${other.path}/`));
+  }
+
+  /**
+   * The parent observes address changes; the entity observes content
+   * changes. A top-level directory root's own recursive watcher can
+   * never see its address change, so a non-recursive doorbell on the
+   * parent directory — the same `watchDir` single-file roots ride —
+   * rings `checkAddress` on EVERY event there: a rename may deliver
+   * only the new name, so no name filter is lawful, and the cheap
+   * address check is what decides (an intact, present address returns
+   * in one lstat). A root inside another watched tree needs none: its
+   * encloser's walk is its address evidence (that arrival is adoption,
+   * one level up). Single-file roots' main doorbell IS a parent
+   * watcher, so their address news rings through openWatcher.
+   */
+  function openAddressWatcher(root) {
+    return watchDir(path.dirname(root.path), () => {
+      try {
+        checkAddress(root.rootId);
+      } catch (error) {
+        console.warn(`[Observer] address check failed for "${root.path}":`, error?.message || error);
+      }
+    }, () => reviveAddressWatcher(root));
+  }
+
+  function reviveAddressWatcher(root) {
+    const state = live.get(root.rootId);
+    if (!state || !started) return;
+    state.addressWatcher = openAddressWatcher(root);
+    try {
+      checkAddress(root.rootId);
+    } catch (error) {
+      console.warn(`[Observer] post-revive address check failed for "${root.path}":`, error?.message || error);
+    }
+  }
+
+  /**
+   * The address doorbell rang: decide what the root's address now means.
+   * Intact ground settles through the ordinary scan (which also flips
+   * presence back if the ground returned). Undecided ground goes to the
+   * one shared decision below — the same one every scan entrance makes.
+   */
+  function checkAddress(rootId) {
+    const root = store.listRoots().find((row) => row.rootId === rootId);
+    if (!root) return;
+    if (!addressUndecided(root)) {
+      // Intact address: content news is the root's own watcher's job —
+      // the parent doorbell also rings when the root's direct children
+      // change its entry, and scanning on that would double every scan.
+      // Only frozen ground RETURNING earns a reconcile here.
+      if (!root.present) scanNow(root.rootId);
+      return;
+    }
+    decideUndecidedAddress(root);
+  }
+
+  /**
+   * THE one decision for an undecided address, at EVERY entrance — the
+   * address doorbell, the settle scan racing a slow parent delivery,
+   * the catch-up scan at start. Two independent doorbells can learn of
+   * one rename in either order; the verdict may not depend on which
+   * arrived first, so both funnel here. Undecided ground of EVERY kind
+   * gets one directed look at the parent — a same-parent rename is the
+   * common move, and the root's kind-appropriate WITNESSED identity (a
+   * dir root its own inode; a single ground its channel row's, as of
+   * the last completed scan) claims the new name under the usual
+   * rules: exactly one candidate of the root's own shape. The path
+   * still claims first — ground is only ever undecided when nothing of
+   * the root's shape holds the address — and ambiguity (two entries
+   * wearing one inode: a hardlink beside a rename) refuses to guess.
+   * So does missing evidence: an atomic save renamed away inside its
+   * own settle window left ground no scan ever witnessed, and the
+   * follow rides witnessed continuity, never clairvoyance. Anything
+   * else is honest absence: `root.unavailable`, identity frozen, never
+   * a conclusion. Returns the root's fresh row after a follow, or null
+   * when the ground is absent.
+   */
+  function decideUndecidedAddress(root) {
+    const identity = rootIdentity(root);
+    if (identity) {
+      const wantDir = root.kind !== 'file';
+      const parent = path.dirname(root.path);
+      let entries = [];
+      try {
+        entries = fs.readdirSync(parent);
+      } catch {
+        entries = []; // the parent itself is gone: absence below
+      }
+      const found = [];
+      for (const name of entries) {
+        try {
+          const stat = fs.lstatSync(path.join(parent, name));
+          if (stat.isDirectory() === wantDir && stat.dev === identity.device && stat.ino === identity.inode) {
+            found.push(path.join(parent, name));
+          }
+        } catch { /* raced away mid-look; absence decides below */ }
+      }
+      if (found.length === 1) return rebindRoot(root, found[0]);
+    }
+    markAbsent(root);
+    return null;
+  }
+
+  /**
+   * Watcher death is an event: install a fresh doorbell, then reconcile the
+   * gap once. A replacement that cannot even be born stays degraded (visible
+   * in status()) until the next lifecycle moment retries — no timers.
+   */
+  function reviveWatcher(root) {
+    const state = live.get(root.rootId);
+    if (!state || !started) return;
+    state.watcher = openWatcher(root);
+    try {
+      scanNow(root.rootId);
+    } catch (error) {
+      console.warn(`[Observer] post-revive scan failed for "${root.path}":`, error?.message || error);
+    }
+  }
+
+  function startWatching(root, state) {
+    if (!state.watcher || state.watcher.degraded) {
+      state.watcher?.close();
+      state.watcher = openWatcher(root);
+    }
+    if ((!state.addressWatcher || state.addressWatcher.degraded)
+      && root.kind !== 'file' && !enclosed(root)) {
+      state.addressWatcher?.close();
+      state.addressWatcher = openAddressWatcher(root);
+    }
+  }
+
+  function attach(root, { watch = true } = {}) {
+    const existing = live.get(root.rootId);
+    if (existing) {
+      if (started && watch) startWatching(root, existing);
+      return existing;
+    }
+    const state = {
+      kind: root.kind,
+      watcher: null,
+      addressWatcher: null,
+      settleTimer: null,
+      settleDue: 0,
+      retryMs: settleMs,
+      dirtyPaths: new Set(),
+      checkAll: false,
+      territories: new Set(),
+    };
+    for (const child of childRepoRoots(root)) {
+      state.territories.add(child.path.slice(root.path.length + 1));
+    }
+    live.set(root.rootId, state);
+    if (started && watch) startWatching(root, state);
+    return state;
+  }
+
+  function detach(rootId) {
+    const state = live.get(rootId);
+    if (!state) return;
+    state.watcher?.close();
+    state.addressWatcher?.close();
+    if (state.settleTimer) clearTimeout(state.settleTimer);
+    live.delete(rootId);
+  }
+
+  return {
+    /**
+     * Enrollment names ground by ADDRESS: the parent chain is resolved so
+     * the address is canonical, but the last segment is inspected, never
+     * traversed — a symlink enrolled explicitly enrolls AS the pointer,
+     * the smallest root of the pointer kind (only real ground ever
+     * arrives here through edge-following, which resolves first).
+     * Identity is permanent and the address is not: ground that moved out
+     * from under a known root is rescued by physical continuity — the
+     * root keeps its rootId, every channel inside keeps its identity, and
+     * `root.moved` carries the news.
+     */
+    enrollRoot(rootPath, { kind, scan = true, watch = true } = {}) {
+      const parent = fs.realpathSync(path.dirname(rootPath));
+      const address = path.join(parent, path.basename(rootPath));
+      let stat = fs.lstatSync(address);
+      const resolved = stat.isSymbolicLink() ? address : fs.realpathSync(address);
+      if (!stat.isSymbolicLink() && resolved !== address) stat = fs.lstatSync(resolved);
+      const existing = store.rootByPath(resolved);
+      if (existing) {
+        // A known address wearing a different directory identity is a
+        // frozen reoccupation (see addressUndecided) — and THIS is the
+        // moment that resolves it: presence proved nothing, but naming
+        // the address is a deliberate act, so the root adopts the ground
+        // and a full scan turns the frozen beliefs into honest evidence.
+        // (Single-ground roots need no adoption — their address lawfully
+        // churns identity and the file laws absorb it at the next scan.)
+        if (existing.kind !== 'file' && stat.isDirectory() && existing.device != null
+          && (stat.dev !== existing.device || stat.ino !== existing.inode)) {
+          store.setRootIdentity(existing.rootId, stat.dev, stat.ino);
+          attach(existing, { watch });
+          if (scan) scanNow(existing.rootId);
+          return store.rootByPath(resolved);
+        }
+        attach(existing, { watch });
+        return existing;
+      }
+      const moved = findMovedRoot(stat);
+      if (moved) return rebindRoot(moved, resolved);
+      // Territory is decided by disk: a directory with a .git is a repo,
+      // a plain directory is files ground, and a file or pointer is the
+      // smallest root there is — one channel. Disk must actually answer:
+      // a kind is a durable conclusion, so unsettled ground refuses
+      // loudly instead of guessing — the caller's dirty/retry rule owns
+      // the next attempt, and no wrongly typed root is ever minted.
+      const territory = (kind || !stat.isDirectory()) ? null : gitDirTruth(resolved);
+      if (territory === 'unsettled') {
+        throw new Error(`cannot enroll ${resolved}: the ground could not be read, so its kind is unsettled — enroll again when a look settles`);
+      }
+      const resolvedKind = kind
+        ?? (!stat.isDirectory() ? 'file' : territory === 'present' ? 'repo' : 'files');
+      const root = {
+        rootId: crypto.randomUUID(), path: resolved, kind: resolvedKind,
+        device: stat.dev, inode: stat.ino,
+      };
+      store.addRoot(root);
+      attach(root, { watch });
+      if (!scan) return root;
+      if (resolvedKind === 'repo') {
+        publish({ type: 'repo.discovered', rootId: root.rootId, path: root.path });
+        censusRepoRoot(root); // enrollment is also the birth of child territories
+      } else if (resolvedKind === 'file') {
+        scanFileRoot(root); // Enrollment is the birth of the one channel.
+      } else {
+        scanFilesRoot(root); // Enrollment is the birth of channels.
+      }
+      return root;
+    },
+
+    removeRoot(rootId) {
+      detach(rootId);
+      store.removeRoot(rootId);
+    },
+
+    listRoots: () => store.listRoots(),
+    filesForRoot: (rootId) => store.filesForRoot(rootId),
+    dirsForRoot: (rootId) => store.dirsForRoot(rootId),
+    linksForRoot: (rootId) => store.linksForRoot(rootId),
+
+    /**
+     * Every enrolled root exposes its symlink edges, whatever its kind —
+     * the enrollment-policy surface (edges.js) reads THIS, never the
+     * tables directly. Files ground answers from detected truth (its
+     * links are channels — a single-ground root holding a pointer
+     * included: its one edge is the pointer itself); repo ground answers
+     * from a fresh worktree census. Its changes travel as one Card +
+     * Checkpoint state; stored child rows are refreshed only after that
+     * state settles, never by this raw edge query. The answer is
+     * three-state: `unsettled` names ground the census could not read —
+     * an edge may hide there, so the surface never claims completeness
+     * it did not earn.
+     */
+    linkEdges(rootId) {
+      const root = store.listRoots().find((row) => row.rootId === rootId);
+      if (!root) return { edges: [], unsettled: [] };
+      if (root.kind === 'repo') {
+        const { links, unsettled } = censusLinks(root.path, shouldEnroll);
+        return { edges: links, unsettled };
+      }
+      return {
+        edges: store.linksForRoot(rootId).map(({ relPath, target }) => ({ relPath, target })),
+        unsettled: [],
+      };
+    },
+
+    /**
+     * The one enrollment policy, exposed so EVERY route that expands
+     * coverage — walks, censuses, edge-following, the registration
+     * boundary's explicit add — asks the same rule, about the COMPLETE
+     * candidate path: the policy excludes by path segment (.ssh,
+     * node_modules, ...), so a benign final name inside excluded ground
+     * is still excluded. Walks ask with tree-relative paths, external
+     * candidates with their whole address. No route may enroll ground
+     * the policy excludes; an explicit override is a future deliberate
+     * operation, never a default.
+     */
+    shouldEnroll: (candidatePath) => shouldEnroll(candidatePath),
+    /**
+     * Reconcile registered Git worktree children after Repocard has settled
+     * a new Card + Checkpoint. This is deliberately NOT called by raw
+     * filesystem doorbells: Git state is the filter that authorizes this
+     * ordinary structural comparison. The root .git is skipped while nested
+     * repositories remain their own territories.
+     */
+    reconcileRepoWorktree(rootId) {
+      const root = store.listRoots().find((row) => row.rootId === rootId);
+      if (!root || root.kind !== 'repo') {
+        throw new Error(`reconcileRepoWorktree requires a live repo root: ${rootId}`);
+      }
+      scanFilesRoot(root, { allowRootRepository: true });
+    },
+    scanNow,
+
+    // The referee (verify.js): re-hash every enrolled byte, report every
+    // divergence — read-only, and deliberately none of the machinery above.
+    verify: createVerify({ store, shouldEnroll }),
+
+    /**
+     * A writer that changed disk itself records the result here so the next
+     * scan finds silence instead of manufacturing a change (axiom 4).
+     */
+    noteWrite(absPath) {
+      const resolved = fs.realpathSync(absPath);
+      for (const root of store.listRoots()) {
+        if (root.kind === 'file' && resolved === root.path) {
+          let stat;
+          try {
+            stat = fs.lstatSync(resolved);
+          } catch {
+            return;
+          }
+          const hashedAtMs = Date.now(); // stamped BEFORE reading, like every hash here
+          const content = safeContent(resolved);
+          if (content === null) return;
+          const fields = {
+            relPath: '', device: stat.dev, inode: stat.ino, size: stat.size,
+            mtimeMs: Math.floor(stat.mtimeMs), ...content, hashedAtMs,
+          };
+          const row = store.fileByPath(root.rootId, '');
+          if (row) store.updateFile(row.fileId, fields);
+          else store.insertFile({ fileId: crypto.randomUUID(), rootId: root.rootId, ...fields });
+          return;
+        }
+        if (root.kind !== 'files') continue;
+        const rel = path.relative(root.path, resolved);
+        if (rel === '' || rel.startsWith('..') || path.isAbsolute(rel)) continue;
+        const relPath = rel.split(path.sep).join('/');
+        const state = live.get(root.rootId);
+        if (state && underTerritory(state, relPath)) return; // repo territory: not a channel
+        let stat;
+        try {
+          stat = fs.lstatSync(resolved);
+        } catch {
+          return;
+        }
+        const hashedAtMs = Date.now();
+        const content = safeContent(resolved);
+        if (content === null) return;
+        const fields = {
+          relPath,
+          device: stat.dev,
+          inode: stat.ino,
+          size: stat.size,
+          mtimeMs: Math.floor(stat.mtimeMs),
+          ...content,
+          hashedAtMs,
+        };
+        const row = store.fileByPath(root.rootId, relPath);
+        if (row) store.updateFile(row.fileId, fields);
+        else store.insertFile({ fileId: crypto.randomUUID(), rootId: root.rootId, ...fields });
+        return;
+      }
+    },
+
+    start(rootId = null) {
+      const firstStart = !started;
+      if (firstStart) started = true;
+      if (!firstStart && rootId === null) return;
+      const roots = rootId === null
+        ? store.listRoots()
+        : store.listRoots().filter((root) => root.rootId === rootId);
+      // Watch begins after registration. The initial scan makes the fresh
+      // structural tree concrete; changes during registration are outside
+      // this operation's contract and are not reconstructed here.
+      for (const root of roots) attach(root, { watch: true });
+      try {
+        for (const root of roots) scanNow(root.rootId);
+      } catch (error) {
+        console.warn('[Observer] initial scan failed:', error?.message || error);
+      }
+    },
+
+    stop() {
+      started = false;
+      for (const rootId of [...live.keys()]) detach(rootId);
+    },
+
+    status() {
+      return store.listRoots().map((root) => {
+        const state = live.get(root.rootId);
+        return {
+          ...root,
+          watching: Boolean(state?.watcher) && !state.watcher.degraded,
+          degraded: Boolean(state?.watcher?.degraded),
+          addressRequired: root.kind !== 'file' && !enclosed(root),
+          addressWatching: Boolean(state?.addressWatcher) && !state.addressWatcher.degraded,
+          addressDegraded: Boolean(state?.addressWatcher?.degraded),
+          files: root.kind === 'repo' ? null : store.filesForRoot(root.rootId).length,
+        };
+      });
+    },
+  };
+}
+
+module.exports = { createObserver };