amalgm 0.1.245 → 0.1.246

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

@@ -0,0 +1,387 @@
+'use strict';
+
+/**
+ * The truth half of detection: walk a root, then compare what disk says
+ * against what the store remembers. `diffRootState` is the one compare
+ * function — doorbells and rescans both end here.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const { lookFailed } = require('../adapters/truth');
+
+/**
+ * Does a .git hold this ground? Three answers, like every look — and
+ * only present or absent may conclude: territory is never born,
+ * buried, or converted on a look that failed.
+ */
+function gitDirTruth(absDir) {
+  try {
+    fs.lstatSync(path.join(absDir, '.git'));
+    return 'present';
+  } catch (error) {
+    return lookFailed(error).truth;
+  }
+}
+
+/**
+ * Every enrollable entity under rootPath, as
+ * { files: [{ relPath, device, inode, size, mtimeMs }],
+ *   dirs: [{ relPath, device, inode }],
+ *   links: [{ relPath, device, inode, target }], repoDirs: [relDir],
+ *   unsettled: [relPath] }.
+ * `unsettled` lists ground the walk could not read: an unlistable
+ * directory (its whole subtree is unknown, not empty) or an entry whose
+ * own read failed. Ground that vanished mid-walk is genuinely absent
+ * and is simply not listed; only a failed LOOK is unsettled — the walk
+ * reports it so the consumer concludes nothing there (only present or
+ * absent may conclude) and reads again.
+ * Directories are channels too — physical identity, no content of their
+ * own — listed at walk time so folder detection sees them exactly like
+ * files ('' is the root, never listed; a territory's dir belongs to
+ * repoDirs, never dirs). Symlinks are channels whose whole payload is the
+ * target string exactly as disk holds it (a symlink stores a written
+ * address, not the target's inode) — read here, NEVER followed: the real
+ * target is watched at its real enrolled location, and traversing the
+ * pointer would walk the same ground twice. `repoDirs` lists every
+ * subtree a .git claims ('' when the root itself does): repo territory,
+ * reported instead of walked.
+ */
+function walkRoot(rootPath, shouldEnroll, { allowRootRepository = false } = {}) {
+  const files = [];
+  const dirs = [];
+  const links = [];
+  const repoDirs = [];
+  const unsettled = [];
+  // A failed look concludes nothing: vanished mid-walk is honest absence
+  // (simply not listed), an unreadable look marks the ground unsettled.
+  const vanished = (error, relPath) => {
+    if (lookFailed(error).truth === 'absent') return true;
+    unsettled.push(relPath);
+    return false;
+  };
+  const pending = [''];
+  while (pending.length > 0) {
+    const relDir = pending.pop();
+    const absDir = relDir ? path.join(rootPath, relDir) : rootPath;
+    let entries;
+    try {
+      entries = fs.readdirSync(absDir, { withFileTypes: true });
+    } catch (error) {
+      vanished(error, relDir);
+      continue;
+    }
+    // A .git claims its subtree: an embedded repository is repo territory,
+    // never files territory. Its changes travel as one card, not as files.
+    if (entries.some((entry) => entry.name === '.git') && !(allowRootRepository && relDir === '')) {
+      repoDirs.push(relDir);
+      if (!relDir) return { files: [], dirs: [], links: [], repoDirs, unsettled }; // the whole root is repo territory
+      continue;
+    }
+    if (relDir) {
+      try {
+        const stat = fs.lstatSync(absDir);
+        dirs.push({ relPath: relDir, device: stat.dev, inode: stat.ino });
+      } catch (error) {
+        vanished(error, relDir);
+        continue;
+      }
+    }
+    for (const entry of entries) {
+      const relPath = relDir ? `${relDir}/${entry.name}` : entry.name;
+      if (!shouldEnroll(relPath)) continue;
+      if (entry.isDirectory()) {
+        pending.push(relPath);
+        continue;
+      }
+      if (entry.isSymbolicLink()) {
+        try {
+          const stat = fs.lstatSync(path.join(rootPath, relPath));
+          const target = fs.readlinkSync(path.join(rootPath, relPath));
+          links.push({ relPath, device: stat.dev, inode: stat.ino, target });
+        } catch (error) {
+          vanished(error, relPath);
+        }
+        continue;
+      }
+      if (!entry.isFile()) continue;
+      let stat;
+      try {
+        stat = fs.lstatSync(path.join(rootPath, relPath));
+      } catch (error) {
+        vanished(error, relPath);
+        continue;
+      }
+      if (!stat.isFile()) continue;
+      files.push({
+        relPath,
+        device: stat.dev,
+        inode: stat.ino,
+        size: stat.size,
+        mtimeMs: Math.floor(stat.mtimeMs),
+      });
+    }
+  }
+  return { files, dirs, links, repoDirs, unsettled };
+}
+
+function defaultShouldEnroll(relPath) {
+  return require('../workspace/tree/inclusion').shouldEnroll(relPath);
+}
+
+/**
+ * Every nested repository boundary under a repo root: directories beneath
+ * rootPath holding their own `.git` (directory or file — linked worktrees
+ * and initialized submodules count). Descent follows amalgm's OWN
+ * enrollment policy (`shouldEnroll`) — the exact rule walkRoot applies to
+ * files territory. Git's ignore rules never decide enrollment (entity
+ * axiom 2: external conventions may inform the manual policy, never decide
+ * it implicitly) — so a gitignored worktree is a territory and a repo in
+ * amalgm-excluded ground is not. The walk stops at each boundary — a
+ * child's children belong to the child's own census. Symlinks are never
+ * followed, matching walkRoot. The census speaks three states like every
+ * walk: `unsettled` names ground it could not list — an unreadable
+ * directory may hide a boundary, so its silence concludes nothing.
+ */
+function censusBoundaries(rootPath, shouldEnroll = defaultShouldEnroll) {
+  const boundaries = [];
+  const unsettled = [];
+  const pending = [''];
+  while (pending.length > 0) {
+    const relDir = pending.pop();
+    const absDir = relDir ? path.join(rootPath, relDir) : rootPath;
+    let entries;
+    try {
+      entries = fs.readdirSync(absDir, { withFileTypes: true });
+    } catch (error) {
+      // Vanished mid-walk is a settled fact; a failed LOOK is not.
+      if (lookFailed(error).truth === 'unsettled') unsettled.push(relDir);
+      continue;
+    }
+    if (relDir && entries.some((entry) => entry.name === '.git')) {
+      boundaries.push(relDir);
+      continue;
+    }
+    for (const entry of entries) {
+      if (!entry.isDirectory() || entry.name === '.git') continue;
+      const rel = relDir ? `${relDir}/${entry.name}` : entry.name;
+      if (!shouldEnroll(rel)) continue;
+      pending.push(rel);
+    }
+  }
+  return { boundaries: boundaries.sort(), unsettled: unsettled.sort() };
+}
+
+/**
+ * Every symlink edge in a repo root's worktree: { relPath, target }. A
+ * repo's CHANGES travel as one Card + Checkpoint state — raw doorbells
+ * never publish child changes — but its registered child channels are
+ * refreshed after that state settles. This census remains an
+ * enrollment-policy input like any other root's, so it reads fresh on
+ * demand. Same walk law as censusBoundaries: descent follows
+ * amalgm's enrollment policy, stops at nested `.git` boundaries (a
+ * child's edges belong to the child's own census), never follows a
+ * pointer, and speaks three states — `unsettled` names ground it could
+ * not read, because an unlisted directory may hide an edge.
+ */
+function censusLinks(rootPath, shouldEnroll = defaultShouldEnroll) {
+  const links = [];
+  const unsettled = [];
+  const pending = [''];
+  while (pending.length > 0) {
+    const relDir = pending.pop();
+    const absDir = relDir ? path.join(rootPath, relDir) : rootPath;
+    let entries;
+    try {
+      entries = fs.readdirSync(absDir, { withFileTypes: true });
+    } catch (error) {
+      // Vanished mid-walk is a settled fact; a failed LOOK is not.
+      if (lookFailed(error).truth === 'unsettled') unsettled.push(relDir);
+      continue;
+    }
+    if (relDir && entries.some((entry) => entry.name === '.git')) continue;
+    for (const entry of entries) {
+      if (entry.name === '.git') continue;
+      const rel = relDir ? `${relDir}/${entry.name}` : entry.name;
+      if (!shouldEnroll(rel)) continue;
+      if (entry.isDirectory()) {
+        pending.push(rel);
+        continue;
+      }
+      if (!entry.isSymbolicLink()) continue;
+      try {
+        links.push({ relPath: rel, target: fs.readlinkSync(path.join(rootPath, rel)) });
+      } catch (error) {
+        if (lookFailed(error).truth === 'unsettled') unsettled.push(rel);
+      }
+    }
+  }
+  return {
+    links: links.sort((a, b) => (a.relPath < b.relPath ? -1 : 1)),
+    unsettled: unsettled.sort(),
+  };
+}
+
+/**
+ * Physical continuity, shared by both compare functions: a row and an entry
+ * sharing one device:inode, exactly one match on both sides → the same
+ * physical thing. Anything else is never guessed. For files this rescues
+ * path-orphans (rule 2); for directories it IS rule 1.
+ */
+function matchByInode(rows, entries) {
+  const one = (map, key, value) => map.set(key, map.has(key) ? 'many' : value);
+  const rowsByInode = new Map();
+  for (const row of rows) one(rowsByInode, `${row.device}:${row.inode}`, row);
+  const entriesByInode = new Map();
+  for (const entry of entries) one(entriesByInode, `${entry.device}:${entry.inode}`, entry);
+  const matched = [];
+  for (const [key, entry] of entriesByInode) {
+    const row = rowsByInode.get(key);
+    if (entry === 'many' || !row || row === 'many') continue;
+    matched.push({ row, entry });
+  }
+  return matched;
+}
+
+/**
+ * The compare function for directory channels — the file identity rules in
+ * the OPPOSITE order, for the mirror reason. A file's inode is replaced in
+ * place on every atomic save, so for files the path must absorb that churn
+ * (path claims first). Nothing replaces a directory's inode in place: a
+ * known inode at a new address IS the directory, moved — even when its old
+ * address was reoccupied in the same interval (two directories exchanging
+ * names cross by inode, exactly like the files inside them). So:
+ *  1. Physical continuity claims the channel: unique device:inode, whole
+ *     sets, same path = continued, new path = rename.
+ *  2. The address claims what no inode claims — recreation under an old
+ *     name is the same channel wearing a never-seen inode (`retags`,
+ *     silent).
+ *  3. Leftover entries are creates; leftover rows are deletes.
+ * No content: a directory's membership is derived state upstream, so there
+ * is nothing to hash or check.
+ */
+function diffDirState(rows, entries) {
+  const matched = matchByInode(rows, entries);
+  const matchedRowIds = new Set(matched.map((pair) => pair.row.dirId));
+  const matchedEntries = new Set(matched.map((pair) => pair.entry));
+  const rowsByPath = new Map(rows.filter((row) => !matchedRowIds.has(row.dirId))
+    .map((row) => [row.relPath, row]));
+  const retags = [];
+  const creates = [];
+  for (const entry of entries) {
+    if (matchedEntries.has(entry)) continue;
+    const row = rowsByPath.get(entry.relPath);
+    if (row) {
+      rowsByPath.delete(entry.relPath);
+      retags.push({ row, entry });
+    } else {
+      creates.push(entry);
+    }
+  }
+  return {
+    renames: matched.filter((pair) => pair.row.relPath !== pair.entry.relPath),
+    retags,
+    creates,
+    deletes: [...rowsByPath.values()],
+  };
+}
+
+/**
+ * The compare function for link channels — the FILE identity rules, for the
+ * file reason: a symlink cannot be retargeted in place (retarget is unlink +
+ * recreate, so the inode churns exactly like an atomic save), so the path
+ * absorbs that churn and claims first; the inode rescues path-orphans (`mv`
+ * preserves a symlink's inode). The payload is the target string, already
+ * read at walk time — as cheap as the lstat beside it, so there is no
+ * stat-excuse machinery and nothing deferred. A consequence worth naming:
+ * two links exchanging names read as two retargets (path-first), because a
+ * link's meaning IS its written address.
+ *  1. Path claims the channel: same target = continued (a new inode under
+ *     an old name with an old target is silent recreation), different
+ *     target = changed.
+ *  2. Inode rescues path-orphans: renames.
+ *  3. Leftover entries are creates; leftover rows are deletes.
+ */
+function diffLinkState(rows, entries) {
+  const changes = [];
+  const retags = [];
+  const rowsByPath = new Map(rows.map((row) => [row.relPath, row]));
+  const claimedRowIds = new Set();
+  const orphanEntries = [];
+  for (const entry of entries) {
+    const row = rowsByPath.get(entry.relPath);
+    if (!row) {
+      orphanEntries.push(entry);
+      continue;
+    }
+    claimedRowIds.add(row.linkId);
+    if (row.target !== entry.target) changes.push({ row, entry });
+    else if (row.device !== entry.device || row.inode !== entry.inode) retags.push({ row, entry });
+  }
+  const orphanRows = rows.filter((row) => !claimedRowIds.has(row.linkId));
+  const renames = matchByInode(orphanRows, orphanEntries);
+  const renamedRowIds = new Set(renames.map((pair) => pair.row.linkId));
+  const renamedEntries = new Set(renames.map((pair) => pair.entry));
+  return {
+    changes,
+    retags,
+    renames,
+    creates: orphanEntries.filter((entry) => !renamedEntries.has(entry)),
+    deletes: orphanRows.filter((row) => !renamedRowIds.has(row.linkId)),
+  };
+}
+
+/**
+ * The compare function. Pure: rows (store memory) + entries (disk truth) in,
+ * actions out. Hashing is deferred — `checks` name the files whose content
+ * must be read before an event may be claimed.
+ *
+ * Identity rules, in order:
+ *  1. Path claims the channel. Same rel_path = same file_id, even when the
+ *     inode changed (atomic saves replace the inode on every write).
+ *  2. Inode rescues path-orphans (matchByInode above).
+ *  3. Leftover entries are creates; leftover rows are deletes.
+ *
+ * The single stat-shortcut this layer allows itself: a (size, mtime, inode)
+ * triple identical to the stored one is skipped as unchanged — but only when
+ * the mtime is strictly older than the moment we last read the bytes
+ * (git's "racily clean" rule), and only when nothing pointed at the file.
+ * A path named in `mustCheck` (the doorbell said so) is always hashed:
+ * timestamps can lie, a delivered watcher event cannot be un-delivered.
+ */
+function diffRootState(rows, entries, mustCheck = null) {
+  const actions = { checks: [], renames: [], creates: [], deletes: [], unchanged: 0 };
+  const rowsByPath = new Map(rows.map((row) => [row.relPath, row]));
+  const claimedRowIds = new Set();
+  const orphanEntries = [];
+
+  for (const entry of entries) {
+    const row = rowsByPath.get(entry.relPath);
+    if (!row) {
+      orphanEntries.push(entry);
+      continue;
+    }
+    claimedRowIds.add(row.fileId);
+    const statsMatch = row.size === entry.size && row.mtimeMs === entry.mtimeMs && row.inode === entry.inode;
+    const provablyBeforeLastRead = typeof row.hashedAtMs === 'number' && entry.mtimeMs < row.hashedAtMs;
+    const named = mustCheck !== null && mustCheck.has(entry.relPath);
+    if (statsMatch && provablyBeforeLastRead && !named) {
+      actions.unchanged += 1;
+    } else {
+      actions.checks.push({ row, entry });
+    }
+  }
+
+  const orphanRows = rows.filter((row) => !claimedRowIds.has(row.fileId));
+  actions.renames = matchByInode(orphanRows, orphanEntries);
+  const renamedRowIds = new Set(actions.renames.map((pair) => pair.row.fileId));
+  const renamedEntries = new Set(actions.renames.map((pair) => pair.entry));
+
+  actions.creates = orphanEntries.filter((entry) => !renamedEntries.has(entry));
+  actions.deletes = orphanRows.filter((row) => !renamedRowIds.has(row.fileId));
+
+  return actions;
+}
+
+module.exports = { censusBoundaries, censusLinks, diffDirState, diffLinkState, diffRootState, gitDirTruth, walkRoot };

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

@@ -0,0 +1,262 @@
+'use strict';
+
+/**
+ * The observer's whole memory: enrolled roots and the last-known disk state
+ * per channel — files with their content, directories with identity alone
+ * (a directory has no bytes of its own), links with the written address
+ * that IS their content. The database handle is injected — this module
+ * owns only its four tables and never opens a connection itself.
+ *
+ * This store IS the identity evidence: channels live and die with it.
+ * Losing it re-detects bytes harmlessly (equal hashes are silence), but it
+ * ends every channel — a fresh store is a new witness, wearing a new root
+ * id — and the evidence layer above pins the witness and convicts an
+ * unknown one loudly rather than let replacements mint. Identity evidence
+ * is durable, or its loss is explicit.
+ */
+
+const SCHEMA = `
+CREATE TABLE IF NOT EXISTS observer_roots (
+  root_id TEXT PRIMARY KEY,
+  path TEXT NOT NULL UNIQUE,
+  kind TEXT NOT NULL CHECK (kind IN ('files', 'repo', 'file')),
+  device INTEGER,
+  inode INTEGER,
+  present INTEGER NOT NULL DEFAULT 1
+);
+CREATE TABLE IF NOT EXISTS observer_files (
+  file_id TEXT PRIMARY KEY,
+  root_id TEXT NOT NULL REFERENCES observer_roots(root_id) ON DELETE CASCADE,
+  rel_path TEXT NOT NULL,
+  device INTEGER,
+  inode INTEGER,
+  size INTEGER,
+  mtime_ms INTEGER,
+  content_hash TEXT,
+  is_binary INTEGER,
+  hashed_at_ms INTEGER,
+  UNIQUE (root_id, rel_path)
+);
+CREATE INDEX IF NOT EXISTS observer_files_inode
+  ON observer_files (root_id, device, inode);
+CREATE TABLE IF NOT EXISTS observer_dirs (
+  dir_id TEXT PRIMARY KEY,
+  root_id TEXT NOT NULL REFERENCES observer_roots(root_id) ON DELETE CASCADE,
+  rel_path TEXT NOT NULL,
+  device INTEGER,
+  inode INTEGER,
+  UNIQUE (root_id, rel_path)
+);
+CREATE INDEX IF NOT EXISTS observer_dirs_inode
+  ON observer_dirs (root_id, device, inode);
+CREATE TABLE IF NOT EXISTS observer_links (
+  link_id TEXT PRIMARY KEY,
+  root_id TEXT NOT NULL REFERENCES observer_roots(root_id) ON DELETE CASCADE,
+  rel_path TEXT NOT NULL,
+  device INTEGER,
+  inode INTEGER,
+  target TEXT NOT NULL,
+  UNIQUE (root_id, rel_path)
+);
+CREATE INDEX IF NOT EXISTS observer_links_inode
+  ON observer_links (root_id, device, inode);
+`;
+
+function rowToFile(row) {
+  if (!row) return null;
+  return {
+    fileId: row.file_id,
+    rootId: row.root_id,
+    relPath: row.rel_path,
+    device: row.device,
+    inode: row.inode,
+    size: row.size,
+    mtimeMs: row.mtime_ms,
+    contentHash: row.content_hash,
+    binary: Boolean(row.is_binary),
+    hashedAtMs: row.hashed_at_ms,
+  };
+}
+
+const TABLES = ['observer_roots', 'observer_files', 'observer_dirs', 'observer_links'];
+
+function rowToRoot(row) {
+  return {
+    rootId: row.root_id, path: row.path, kind: row.kind,
+    device: row.device, inode: row.inode, present: Boolean(row.present),
+  };
+}
+
+// The schema generation this code speaks, stamped as PRAGMA user_version at
+// creation so completeness is judged against a declared shape, never
+// guessed. Generation 2 added observer_links; generation 3 added the
+// 'file' root kind (a single registered file is a root of one channel);
+// generation 4 added the root's own physical identity (device, inode) —
+// a root has a permanent identity and a mutable local address, so a
+// moved root is rescued by continuity exactly like the directories
+// inside it; generation 5 added `present` — identity persists while
+// local presence is separate evidence, so a root whose address is
+// undecided reports unavailable instead of falling silent; generation 6
+// added `is_binary` beside `content_hash` — a file's type is a claim
+// about the bytes its hash fingerprints, so the two are produced by ONE
+// read and stored together, never re-derived later from a second look.
+// The pre-links three-table store never stamped a version and reads 0 —
+// an older generation, refused distinctly from loss until an explicit
+// migration exists.
+const GENERATION = 6;
+
+function createStore(db) {
+  // An established store either has its complete schema or it is loss:
+  // a missing table would be silently recreated empty, ending every
+  // channel it held while the surviving tables vouch for the store — so
+  // an older generation or some-but-not-all tables convicts before
+  // anything is created. Zero tables is a genuinely fresh store.
+  const present = db.prepare(
+    `SELECT name FROM sqlite_master WHERE type = 'table' AND name IN (${TABLES.map(() => '?').join(', ')})`,
+  ).all(...TABLES).map((row) => row.name);
+  if (present.length > 0) {
+    const generation = db.pragma('user_version', { simple: true });
+    if (generation !== GENERATION) {
+      throw new Error(`observer store is schema generation ${generation}, this code speaks ${GENERATION} — migration is an explicit act, never a silent table creation`);
+    }
+    if (present.length < TABLES.length) {
+      const missing = TABLES.filter((name) => !present.includes(name));
+      throw new Error(`identity evidence lost: ${missing.join(', ')} missing from an established observer store — a partial store is loss, never a fresh start`);
+    }
+  }
+  db.exec(SCHEMA);
+  db.pragma(`user_version = ${GENERATION}`);
+
+  return {
+    addRoot({ rootId, path, kind, device = null, inode = null }) {
+      db.prepare('INSERT INTO observer_roots (root_id, path, kind, device, inode) VALUES (?, ?, ?, ?, ?)')
+        .run(rootId, path, kind, device, inode);
+    },
+    rootByPath(path) {
+      const row = db.prepare('SELECT * FROM observer_roots WHERE path = ?').get(path);
+      return row ? rowToRoot(row) : null;
+    },
+    listRoots() {
+      return db.prepare('SELECT * FROM observer_roots ORDER BY path').all().map(rowToRoot);
+    },
+    setRootKind(rootId, kind) {
+      db.prepare('UPDATE observer_roots SET kind = ? WHERE root_id = ?').run(kind, rootId);
+    },
+    /** Identity persists; local presence is separate evidence. */
+    setRootPresent(rootId, present) {
+      db.prepare('UPDATE observer_roots SET present = ? WHERE root_id = ?').run(present ? 1 : 0, rootId);
+    },
+    /**
+     * A root's identity is permanent; its address is not — and a family
+     * of roots (a tree with the nested territories inside it) changes
+     * address as ONE durable transition: every move lands or none does,
+     * so a failure mid-move can never tear a parent from its children.
+     * Device and inode are continuity itself and never churn on a rename.
+     */
+    moveRoots(moves) {
+      const move = db.prepare('UPDATE observer_roots SET path = ? WHERE root_id = ?');
+      db.transaction(() => {
+        for (const { rootId, path } of moves) move.run(path, rootId);
+      })();
+    },
+    /** Adoption: an enrollment moment deliberately named ground wearing a
+     * new identity at a known address (see enrollRoot) — the one write
+     * where a root's own device:inode may change. */
+    setRootIdentity(rootId, device, inode) {
+      db.prepare('UPDATE observer_roots SET device = ?, inode = ? WHERE root_id = ?')
+        .run(device, inode, rootId);
+    },
+    removeRoot(rootId) {
+      db.prepare('DELETE FROM observer_files WHERE root_id = ?').run(rootId);
+      db.prepare('DELETE FROM observer_dirs WHERE root_id = ?').run(rootId);
+      db.prepare('DELETE FROM observer_links WHERE root_id = ?').run(rootId);
+      db.prepare('DELETE FROM observer_roots WHERE root_id = ?').run(rootId);
+    },
+
+    filesForRoot(rootId) {
+      return db.prepare('SELECT * FROM observer_files WHERE root_id = ? ORDER BY rel_path').all(rootId)
+        .map(rowToFile);
+    },
+    fileByPath(rootId, relPath) {
+      return rowToFile(
+        db.prepare('SELECT * FROM observer_files WHERE root_id = ? AND rel_path = ?').get(rootId, relPath),
+      );
+    },
+    insertFile(file) {
+      db.prepare(`
+        INSERT INTO observer_files (file_id, root_id, rel_path, device, inode, size, mtime_ms, content_hash, is_binary, hashed_at_ms)
+        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      `).run(
+        file.fileId, file.rootId, file.relPath,
+        file.device, file.inode, file.size, file.mtimeMs, file.contentHash, file.binary ? 1 : 0, file.hashedAtMs,
+      );
+    },
+    updateFile(fileId, { relPath, device, inode, size, mtimeMs, contentHash, binary, hashedAtMs }) {
+      db.prepare(`
+        UPDATE observer_files
+        SET rel_path = ?, device = ?, inode = ?, size = ?, mtime_ms = ?, content_hash = ?, is_binary = ?, hashed_at_ms = ?
+        WHERE file_id = ?
+      `).run(relPath, device, inode, size, mtimeMs, contentHash, binary ? 1 : 0, hashedAtMs, fileId);
+    },
+    removeFile(fileId) {
+      db.prepare('DELETE FROM observer_files WHERE file_id = ?').run(fileId);
+    },
+
+    dirsForRoot(rootId) {
+      return db.prepare('SELECT * FROM observer_dirs WHERE root_id = ? ORDER BY rel_path').all(rootId)
+        .map((row) => ({
+          dirId: row.dir_id, rootId: row.root_id, relPath: row.rel_path,
+          device: row.device, inode: row.inode,
+        }));
+    },
+    /**
+     * One compare result is ONE truth transition. Movers may exchange
+     * addresses and land on freshly-deleted ones (directories cross by
+     * inode), so uniqueness holds only at the batch boundary: deletes free
+     * their slots and every mover vacates before any lands — all inside a
+     * single transaction. Committed state is always some truth disk
+     * actually had; a crash mid-batch leaves the previous truth whole, and
+     * the next scan re-detects the same batch.
+     */
+    applyDirDiff({ deletes, moves, retags, creates }) {
+      const remove = db.prepare('DELETE FROM observer_dirs WHERE dir_id = ?');
+      const insert = db.prepare('INSERT INTO observer_dirs (dir_id, root_id, rel_path, device, inode) VALUES (?, ?, ?, ?, ?)');
+      const retag = db.prepare('UPDATE observer_dirs SET rel_path = ?, device = ?, inode = ? WHERE dir_id = ?');
+      db.transaction(() => {
+        for (const dirId of deletes) remove.run(dirId);
+        for (const dir of moves) remove.run(dir.dirId);
+        for (const dir of moves) insert.run(dir.dirId, dir.rootId, dir.relPath, dir.device, dir.inode);
+        for (const dir of retags) retag.run(dir.relPath, dir.device, dir.inode, dir.dirId);
+        for (const dir of creates) insert.run(dir.dirId, dir.rootId, dir.relPath, dir.device, dir.inode);
+      })();
+    },
+    removeDir(dirId) {
+      db.prepare('DELETE FROM observer_dirs WHERE dir_id = ?').run(dirId);
+    },
+
+    // Link channels: a pointer's whole payload is its target string, read
+    // fresh every scan. Renames never cross (the address claims first, so
+    // a rename only ever targets a row-free slot), so link rows commit
+    // per-row like files — every commit is a valid last-known truth.
+    linksForRoot(rootId) {
+      return db.prepare('SELECT * FROM observer_links WHERE root_id = ? ORDER BY rel_path').all(rootId)
+        .map((row) => ({
+          linkId: row.link_id, rootId: row.root_id, relPath: row.rel_path,
+          device: row.device, inode: row.inode, target: row.target,
+        }));
+    },
+    insertLink({ linkId, rootId, relPath, device, inode, target }) {
+      db.prepare('INSERT INTO observer_links (link_id, root_id, rel_path, device, inode, target) VALUES (?, ?, ?, ?, ?, ?)')
+        .run(linkId, rootId, relPath, device, inode, target);
+    },
+    updateLink(linkId, { relPath, device, inode, target }) {
+      db.prepare('UPDATE observer_links SET rel_path = ?, device = ?, inode = ?, target = ? WHERE link_id = ?')
+        .run(relPath, device, inode, target, linkId);
+    },
+    removeLink(linkId) {
+      db.prepare('DELETE FROM observer_links WHERE link_id = ?').run(linkId);
+    },
+  };
+}
+
+module.exports = { createStore };