sweet-search 2.5.2 → 2.5.4

package/core/incremental-indexing/infrastructure/path-filter.mjs

@@ -0,0 +1,190 @@
+/**
+ * Path filter (`.sweet-search-ignore` + repo-size cap).
+ *
+ * Plan § 11 ("Default deny-list (independent of `.gitignore`) catches"),
+ * § 22.9 ("Many tiny files / Cursor's 400 k freeze") and § 14.2.7
+ * ("resolved-exclude fingerprint"). Three concerns combined:
+ *
+ *   1. **Default deny-list** for paths that should never reach the
+ *      reconcile dirty set, independent of project `.gitignore`. This
+ *      catches `node_modules`, build dirs, common artifact extensions,
+ *      etc.
+ *   2. **`.sweet-search-ignore`** — a project-level ignore file with
+ *      gitignore-compatible patterns. Allows users to opt out of paths
+ *      that `.gitignore` doesn't already cover.
+ *   3. **Repo-size cap** — Cursor froze at ~400 k indexed files; we cap
+ *      at 200 k by default with a warning at 50 % of cap.
+ *
+ * Pattern matching is intentionally simple — substring + extension +
+ * directory checks. Full gitignore semantics live in
+ * `core/infrastructure/config/search.js::loadProjectConfig` which the
+ * reconcile path consults for the authoritative exclude list.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { loadProjectConfig } from '../../infrastructure/config/search.js';
+
+const DEFAULT_DENY_DIRS = Object.freeze([
+  'node_modules',
+  '.git',
+  '.sweet-search',
+  'dist',
+  'build',
+  '.next',
+  '.nuxt',
+  'target',
+  'vendor',
+  '__pycache__',
+  '.venv',
+  'venv',
+  '.cache',
+  '.turbo',
+  'coverage',
+  '.parcel-cache',
+  '.svelte-kit',
+  '.vercel',
+]);
+
+const DEFAULT_DENY_EXTS = Object.freeze([
+  '.lock',
+  '.lockb',
+  '.min.js',
+  '.min.css',
+  '.map',
+  '.bundle.js',
+  '.pyc',
+  '.so',
+  '.dylib',
+  '.dll',
+  '.exe',
+  '.bin',
+  '.wasm',
+]);
+
+export const DEFAULT_REPO_SIZE_CAP = 200_000;
+export const DEFAULT_REPO_SIZE_WARN_FRAC = 0.5;
+
+/**
+ * Parse a `.sweet-search-ignore` file. Format: gitignore-like, but we
+ * only support `glob`, `dir/`, `**`, `*`, and `#` comments. Returns
+ * the array of normalised pattern strings.
+ *
+ * @param {string} filePath
+ * @returns {string[]}
+ */
+export function loadIgnoreFile(filePath) {
+  if (!fs.existsSync(filePath)) return [];
+  const raw = fs.readFileSync(filePath, 'utf-8');
+  const out = [];
+  for (const rawLine of raw.split('\n')) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith('#')) continue;
+    out.push(line);
+  }
+  return out;
+}
+
+function patternToRegex(pattern) {
+  // Convert the subset of gitignore-style globbing used by the shared
+  // sweet-search config. In particular, leading `**/` must match root-level
+  // files too (`**/package-lock.json` matches `package-lock.json`).
+  let p = String(pattern || '').replace(/\\/g, '/');
+  let dirOnly = false;
+  if (p.startsWith('/')) p = p.slice(1);
+  if (p.endsWith('/')) { p = p.slice(0, -1); dirOnly = true; }
+  const hasSlash = p.includes('/');
+
+  let body = '';
+  for (let i = 0; i < p.length; i++) {
+    if (p.startsWith('**/', i)) {
+      body += '(?:.*/)?';
+      i += 2;
+      continue;
+    }
+    if (p.startsWith('/**', i) && i + 3 === p.length) {
+      body += '(?:/.*)?';
+      i += 2;
+      continue;
+    }
+    if (p.startsWith('**', i)) {
+      body += '.*';
+      i += 1;
+      continue;
+    }
+    const ch = p[i];
+    if (ch === '*') body += '[^/]*';
+    else if (ch === '?') body += '[^/]';
+    else body += ch.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+  }
+
+  const prefix = hasSlash ? '^' : '(?:^|.*/)';
+  const suffix = dirOnly ? '(?:/.*)?$' : '$';
+  return new RegExp(prefix + body + suffix);
+}
+
+/**
+ * Build a path-filter function from default deny-list + ignore file.
+ *
+ * The filter is true for paths that should be **excluded**.
+ *
+ * @param {{projectRoot?:string, ignoreFile?:string, extraPatterns?:string[], allowSweetSearchDir?:boolean}} [opts]
+ * @returns {(relativePath:string)=>boolean}
+ */
+export function buildPathFilter(opts = {}) {
+  const patterns = [];
+  if (opts.projectRoot) {
+    for (const p of loadProjectConfig(opts.projectRoot).exclude || []) {
+      if (opts.allowSweetSearchDir && String(p).includes('.sweet-search')) continue;
+      patterns.push(p);
+    }
+  }
+  for (const p of (opts.extraPatterns || [])) patterns.push(p);
+  const ignoreFile = opts.ignoreFile
+    || (opts.projectRoot ? path.join(opts.projectRoot, '.sweet-search-ignore') : null);
+  if (ignoreFile) {
+    for (const p of loadIgnoreFile(ignoreFile)) patterns.push(p);
+  }
+  const regexes = patterns.map(patternToRegex);
+  const denyDirs = new Set(DEFAULT_DENY_DIRS);
+  if (opts.allowSweetSearchDir) denyDirs.delete('.sweet-search');
+  const denyExts = new Set(DEFAULT_DENY_EXTS);
+
+  return function isExcluded(relativePath) {
+    if (typeof relativePath !== 'string') return true;
+    const norm = relativePath.replace(/\\/g, '/');
+    const parts = norm.split('/');
+    for (const part of parts) {
+      if (denyDirs.has(part)) return true;
+    }
+    const base = parts[parts.length - 1] || '';
+    const ext = path.extname(base).toLowerCase();
+    if (denyExts.has(ext)) return true;
+    // Multi-suffix matches like `.min.js` — denyExts already has them.
+    for (const compound of ['.min.js', '.min.css', '.bundle.js']) {
+      if (base.endsWith(compound)) return true;
+    }
+    for (const re of regexes) {
+      if (re.test(norm)) return true;
+    }
+    return false;
+  };
+}
+
+/**
+ * Apply the repo-size cap policy. Plan § 22.9.
+ *
+ * @param {number} fileCount
+ * @param {{cap?:number, warnFrac?:number}} [opts]
+ * @returns {{ok:boolean, warn:boolean, cap:number, fileCount:number}}
+ */
+export function evaluateRepoSizeCap(fileCount, opts = {}) {
+  const cap = opts.cap ?? DEFAULT_REPO_SIZE_CAP;
+  const warnFrac = opts.warnFrac ?? DEFAULT_REPO_SIZE_WARN_FRAC;
+  return {
+    ok: fileCount <= cap,
+    warn: fileCount >= cap * warnFrac,
+    cap,
+    fileCount,
+  };
+}

package/core/incremental-indexing/infrastructure/reader-heartbeat.mjs

@@ -0,0 +1,201 @@
+/**
+ * Reader heartbeat / grace policy.
+ *
+ * Plan § 8.1.1. Strict row visibility requires bounded history retention:
+ * retired rows cannot be physically pruned until every live reader has
+ * advanced past their epoch. We track each reader's pinned epoch via a
+ * small JSON file under `.sweet-search/readers/<pid>-<boot>-<read>.json`
+ * so the maintenance scheduler can compute `min_live_epoch` across
+ * non-stale heartbeats. The per-read token is load-bearing: a long-lived
+ * MCP/server process can run concurrent queries pinned to different
+ * manifest epochs, and those pins must not overwrite each other.
+ *
+ * Lifecycle:
+ *   - Each reader process (sweet-search CLI, MCP server, etc.) calls
+ *     `beginRead(stateDir, epoch)` before a query and `endRead` when it
+ *     finishes. The heartbeat file holds `{ epoch, pid, bootId, readId, startedAt }`.
+ *   - The reconcile maintenance worker enumerates the heartbeats and:
+ *     - drops files whose process no longer exists,
+ *     - returns `min({live readers}.epoch)` as the prune frontier.
+ *   - Heartbeats older than READER_GRACE_MS without a live pid are
+ *     ignored.
+ *
+ * This file is pure I/O. The reconciler / maintenance worker uses it to
+ * compute `min_live_epoch` but does not block on it (heartbeats are
+ * advisory; correctness is preserved by tombstone-then-prune).
+ */
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+export const READER_GRACE_MS = 60 * 60 * 1000; // 1h default
+const HEARTBEAT_DIR = 'readers';
+let heartbeatSeq = 0;
+
+function heartbeatDir(stateDir) {
+  return path.join(stateDir, HEARTBEAT_DIR);
+}
+
+function heartbeatPath(stateDir, pid, bootId, readId = null) {
+  const suffix = readId ? `-${readId}` : '';
+  return path.join(heartbeatDir(stateDir), `${pid}-${bootId}${suffix}.json`);
+}
+
+function nextReadId() {
+  heartbeatSeq = (heartbeatSeq + 1) >>> 0;
+  const time = Date.now().toString(36);
+  const seq = heartbeatSeq.toString(36);
+  const rand = Math.random().toString(36).slice(2, 8);
+  return `${time}-${seq}-${rand}`;
+}
+
+/**
+ * Returns a coarse boot-id stand-in. Plan § 8.6 mentions
+ * `/proc/sys/kernel/random/boot_id` on Linux and `kern.boottime` on macOS;
+ * we keep a cross-platform fallback based on `os.uptime()` rounded to the
+ * minute boundary, which is stable across the lifetime of a process and
+ * changes whenever the machine reboots.
+ *
+ * @returns {string}
+ */
+export function bootIdStub() {
+  try {
+    const procBoot = '/proc/sys/kernel/random/boot_id';
+    if (fs.existsSync(procBoot)) {
+      const raw = fs.readFileSync(procBoot, 'utf-8').trim();
+      return raw.replace(/[^a-zA-Z0-9-]/g, '');
+    }
+  } catch {
+    // fall through
+  }
+  // Stable enough for the heartbeat: the same process never gets a different
+  // value, and a reboot always changes it.
+  const epochSeconds = Math.floor(Date.now() / 1000 - os.uptime());
+  return `boot-${epochSeconds}`;
+}
+
+/**
+ * Record a reader heartbeat. Idempotent; safe to call before every query.
+ *
+ * @param {string} stateDir
+ * @param {number} epoch
+ * @param {object} [meta]   Optional caller-supplied metadata (mcp-session-id,
+ *                           query, etc.) — stored verbatim for diagnostics.
+ * @returns {{pid:number, bootId:string, readId:string, path:string}}
+ */
+export function beginRead(stateDir, epoch, meta = {}) {
+  const dir = heartbeatDir(stateDir);
+  fs.mkdirSync(dir, { recursive: true });
+  const pid = process.pid;
+  const bootId = bootIdStub();
+  const readId = nextReadId();
+  const p = heartbeatPath(stateDir, pid, bootId, readId);
+  const payload = {
+    epoch,
+    pid,
+    bootId,
+    readId,
+    startedAt: new Date().toISOString(),
+    meta,
+  };
+  fs.writeFileSync(p, JSON.stringify(payload));
+  return { pid, bootId, readId, path: p };
+}
+
+/**
+ * Drop the heartbeat. Plan § 8.1.1 step 2 requires every reader process
+ * to delete its file when the query completes.
+ *
+ * @param {string} stateDir
+ * @param {{pid:number, bootId:string, readId?:string, path?:string}|undefined} record
+ *        Return value of beginRead.
+ */
+export function endRead(stateDir, record) {
+  const pid = record?.pid ?? process.pid;
+  const bootId = record?.bootId ?? bootIdStub();
+  const p = typeof record?.path === 'string'
+    ? record.path
+    : heartbeatPath(stateDir, pid, bootId, record?.readId ?? null);
+  try {
+    fs.unlinkSync(p);
+  } catch {
+    // Ignore — the heartbeat may have been swept by the maintenance scheduler.
+  }
+}
+
+/**
+ * Best-effort liveness check. Returns true when the process is still
+ * running and matches the recorded boot id.
+ *
+ * @param {number} pid
+ * @param {string} bootId
+ */
+export function isReaderAlive(pid, bootId) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  if (bootId !== bootIdStub()) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return err.code === 'EPERM';
+  }
+}
+
+/**
+ * Sweep stale heartbeats. Returns the surviving records sorted by
+ * pinned epoch.
+ *
+ * @param {string} stateDir
+ * @returns {Array<{epoch:number, pid:number, bootId:string, readId?:string, startedAt:string, meta:object}>}
+ */
+export function liveReaders(stateDir) {
+  const dir = heartbeatDir(stateDir);
+  if (!fs.existsSync(dir)) return [];
+  const out = [];
+  for (const name of fs.readdirSync(dir)) {
+    const p = path.join(dir, name);
+    let payload;
+    try {
+      payload = JSON.parse(fs.readFileSync(p, 'utf-8'));
+    } catch {
+      // Malformed — drop after grace.
+      tryUnlinkAfterGrace(p);
+      continue;
+    }
+    if (!Number.isInteger(payload.epoch) || !Number.isInteger(payload.pid) || typeof payload.bootId !== 'string') {
+      tryUnlinkAfterGrace(p);
+      continue;
+    }
+    if (!isReaderAlive(payload.pid, payload.bootId)) {
+      tryUnlinkAfterGrace(p);
+      continue;
+    }
+    out.push(payload);
+  }
+  return out.sort((a, b) => a.epoch - b.epoch);
+}
+
+function tryUnlinkAfterGrace(p) {
+  try {
+    const stat = fs.statSync(p);
+    const ageMs = Date.now() - stat.mtimeMs;
+    if (ageMs > READER_GRACE_MS) fs.unlinkSync(p);
+  } catch {
+    // ignore
+  }
+}
+
+/**
+ * Compute the prune frontier — the minimum epoch any live reader pins.
+ * Returns `null` when no live readers exist, meaning all retired rows
+ * older than the current epoch are eligible for prune.
+ *
+ * @param {string} stateDir
+ * @returns {number|null}
+ */
+export function minLiveEpoch(stateDir) {
+  const live = liveReaders(stateDir);
+  if (live.length === 0) return null;
+  return live[0].epoch;
+}

package/core/incremental-indexing/infrastructure/schema-migrations.mjs

@@ -0,0 +1,257 @@
+/**
+ * Schema migrations for the incremental-indexing bounded context.
+ *
+ * Plan § 7.1.6, § 7.2, § 13 Phase 1, § 33 Phase 1 Pre-Merge Checklist.
+ *
+ * Adds the strict-row-visibility and exact-encoder-input columns required by
+ * the reconcile path. All columns carry `DEFAULT` clauses so an older daemon
+ * running the original INSERT path (e.g. after a git rollback) does NOT crash
+ * with `SQLITE_CONSTRAINT_NOTNULL`. This is load-bearing: without the
+ * defaults a rollback would put the daemon into a permanent crash-loop.
+ *
+ * The migrations are idempotent: `ALTER TABLE ... ADD COLUMN` is skipped when
+ * the column already exists, mirroring the pattern in
+ * `core/graph/graph-extractor.js`.
+ *
+ * Index choice: the epoch visibility index is a full B-tree on
+ * `epoch_written` rather than a partial recent-window index. Plan § 0 / § 36.5
+ * requires Phase 0 benchmarking before committing to the partial form;
+ * SQLite's single-writer monotonic-integer append is already a fast path, so
+ * we default to the full B-tree and revisit only if Phase 0 measurement shows
+ * insertion latency creep.
+ */
+
+/**
+ * Add a column only if it is missing, in a transaction-safe way.
+ * Helper kept private to this module.
+ *
+ * @param {import('better-sqlite3').Database} db
+ * @param {string} table
+ * @param {string} column
+ * @param {string} definition  e.g. `"TEXT NOT NULL DEFAULT ''"`.
+ * @returns {boolean} true if the column was added; false if it already existed.
+ */
+function addColumnIfMissing(db, table, column, definition) {
+  const cols = db.prepare(`PRAGMA table_info(${table})`).all();
+  if (cols.some((c) => c.name === column)) return false;
+  db.exec(`ALTER TABLE ${table} ADD COLUMN ${column} ${definition}`);
+  return true;
+}
+
+function createIndexIfMissing(db, indexName, sql) {
+  db.exec(sql);
+  // SQLite's CREATE INDEX IF NOT EXISTS already covers idempotence; this
+  // helper exists for symmetry with addColumnIfMissing in case we ever need
+  // to wrap with logging.
+  void indexName;
+}
+
+/**
+ * Apply the reconcile-v2 vectors-table migration.
+ *
+ * Adds (plan § 7.2):
+ *   - `chunk_struct_id        TEXT NOT NULL DEFAULT ''`
+ *   - `chunk_text_hash        TEXT NOT NULL DEFAULT ''`
+ *   - `embedding_input_hash   TEXT NOT NULL DEFAULT ''`
+ *   - `li_input_hash          TEXT NOT NULL DEFAULT ''`
+ *   - `metadata_fingerprint   TEXT NOT NULL DEFAULT ''`
+ *   - `logical_chunk_id       TEXT NOT NULL DEFAULT ''`
+ *   - `epoch_written          INTEGER NOT NULL DEFAULT 0`
+ *   - `epoch_retired          INTEGER`
+ *
+ * Plus the epoch visibility index.
+ *
+ * Idempotent. Safe to call on every daemon start.
+ *
+ * @param {import('better-sqlite3').Database} db
+ * @returns {{added: string[]}}
+ */
+export function migrateVectorsSchema(db) {
+  const added = [];
+  const columns = [
+    ['chunk_struct_id', "TEXT NOT NULL DEFAULT ''"],
+    ['chunk_text_hash', "TEXT NOT NULL DEFAULT ''"],
+    ['embedding_input_hash', "TEXT NOT NULL DEFAULT ''"],
+    ['li_input_hash', "TEXT NOT NULL DEFAULT ''"],
+    ['metadata_fingerprint', "TEXT NOT NULL DEFAULT ''"],
+    ['logical_chunk_id', "TEXT NOT NULL DEFAULT ''"],
+    ['epoch_written', 'INTEGER NOT NULL DEFAULT 0'],
+    ['epoch_retired', 'INTEGER'],
+  ];
+  // The `vectors` table is created lazily by `createVectorSchema` in
+  // `core/indexing/indexer-build.js`. We assume the caller has invoked that
+  // already; otherwise the PRAGMA call returns empty and addColumnIfMissing
+  // would throw on the ALTER. The reconciler always seeds the schema first.
+  const hasTable = db.prepare(
+    "SELECT 1 FROM sqlite_master WHERE type='table' AND name='vectors'",
+  ).get();
+  if (!hasTable) return { added };
+
+  for (const [col, defn] of columns) {
+    if (addColumnIfMissing(db, 'vectors', col, defn)) added.push(col);
+  }
+
+  createIndexIfMissing(
+    db,
+    'idx_vectors_struct',
+    'CREATE INDEX IF NOT EXISTS idx_vectors_struct ON vectors(chunk_struct_id) WHERE chunk_struct_id != \'\'',
+  );
+  createIndexIfMissing(
+    db,
+    'idx_vectors_epoch_written',
+    'CREATE INDEX IF NOT EXISTS idx_vectors_epoch_written ON vectors(epoch_written)',
+  );
+  createIndexIfMissing(
+    db,
+    'idx_vectors_epoch_retired',
+    'CREATE INDEX IF NOT EXISTS idx_vectors_epoch_retired ON vectors(epoch_retired) WHERE epoch_retired IS NOT NULL',
+  );
+  createIndexIfMissing(
+    db,
+    'idx_vectors_logical',
+    'CREATE INDEX IF NOT EXISTS idx_vectors_logical ON vectors(logical_chunk_id) WHERE logical_chunk_id != \'\'',
+  );
+  return { added };
+}
+
+/**
+ * Apply the reconcile-v2 entities-table migration.
+ *
+ * Adds (plan § 7.1.6):
+ *   - `logical_entity_id  TEXT NOT NULL DEFAULT ''`
+ *   - `epoch_written      INTEGER NOT NULL DEFAULT 0`
+ *   - `epoch_retired      INTEGER`
+ *
+ * The `stale_since` column is already present; we keep it for compatibility
+ * with existing soft-delete behaviour in `core/graph/graph-extractor.js`.
+ *
+ * @param {import('better-sqlite3').Database} db
+ * @returns {{added: string[]}}
+ */
+export function migrateEntitiesSchema(db) {
+  const added = [];
+  const hasTable = db.prepare(
+    "SELECT 1 FROM sqlite_master WHERE type='table' AND name='entities'",
+  ).get();
+  if (!hasTable) return { added };
+
+  if (addColumnIfMissing(db, 'entities', 'logical_entity_id', "TEXT NOT NULL DEFAULT ''")) {
+    added.push('logical_entity_id');
+  }
+  if (addColumnIfMissing(db, 'entities', 'epoch_written', 'INTEGER NOT NULL DEFAULT 0')) {
+    added.push('epoch_written');
+  }
+  if (addColumnIfMissing(db, 'entities', 'epoch_retired', 'INTEGER')) {
+    added.push('epoch_retired');
+  }
+  createIndexIfMissing(
+    db,
+    'idx_entities_logical',
+    'CREATE INDEX IF NOT EXISTS idx_entities_logical ON entities(logical_entity_id) WHERE logical_entity_id != \'\'',
+  );
+  createIndexIfMissing(
+    db,
+    'idx_entities_epoch_written',
+    'CREATE INDEX IF NOT EXISTS idx_entities_epoch_written ON entities(epoch_written)',
+  );
+  createIndexIfMissing(
+    db,
+    'idx_entities_epoch_retired',
+    'CREATE INDEX IF NOT EXISTS idx_entities_epoch_retired ON entities(epoch_retired) WHERE epoch_retired IS NOT NULL',
+  );
+  return { added };
+}
+
+/**
+ * Apply the reconcile-v2 relationships-table migration.
+ *
+ * Adds (plan § 7.1.6 / § 33):
+ *   - `logical_relationship_id  TEXT NOT NULL DEFAULT ''`
+ *   - `epoch_written            INTEGER NOT NULL DEFAULT 0`
+ *   - `epoch_retired            INTEGER`
+ *
+ * @param {import('better-sqlite3').Database} db
+ * @returns {{added: string[]}}
+ */
+export function migrateRelationshipsSchema(db) {
+  const added = [];
+  const hasTable = db.prepare(
+    "SELECT 1 FROM sqlite_master WHERE type='table' AND name='relationships'",
+  ).get();
+  if (!hasTable) return { added };
+
+  if (addColumnIfMissing(db, 'relationships', 'logical_relationship_id', "TEXT NOT NULL DEFAULT ''")) {
+    added.push('logical_relationship_id');
+  }
+  if (addColumnIfMissing(db, 'relationships', 'epoch_written', 'INTEGER NOT NULL DEFAULT 0')) {
+    added.push('epoch_written');
+  }
+  if (addColumnIfMissing(db, 'relationships', 'epoch_retired', 'INTEGER')) {
+    added.push('epoch_retired');
+  }
+  createIndexIfMissing(
+    db,
+    'idx_rel_logical',
+    'CREATE INDEX IF NOT EXISTS idx_rel_logical ON relationships(logical_relationship_id) WHERE logical_relationship_id != \'\'',
+  );
+  createIndexIfMissing(
+    db,
+    'idx_rel_epoch_written',
+    'CREATE INDEX IF NOT EXISTS idx_rel_epoch_written ON relationships(epoch_written)',
+  );
+  createIndexIfMissing(
+    db,
+    'idx_rel_epoch_retired',
+    'CREATE INDEX IF NOT EXISTS idx_rel_epoch_retired ON relationships(epoch_retired) WHERE epoch_retired IS NOT NULL',
+  );
+  return { added };
+}
+
+/**
+ * Apply the encoder-input dependency sidecar (plan § 7.2.1 / § 13 Phase 1).
+ *
+ * Stores reverse dependencies from external facts to dependent chunks:
+ *   `(dependency_key, file_path, chunk_struct_id, consumer)`
+ *
+ * `consumer` is one of `dense | li | dedup` so the reconciler can mark a
+ * chunk metadata-dirty for the specific consumer whose input changed.
+ * Future cross-file metadata rules register dependency keys whose changes
+ * expand the dirty set; the table also holds the dense / LI / dedup
+ * dependencies for same-file metadata edits.
+ *
+ * @param {import('better-sqlite3').Database} db
+ */
+export function ensureEncoderDepsSchema(db) {
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS encoder_input_dependencies (
+      dependency_key TEXT NOT NULL,
+      file_path TEXT NOT NULL,
+      chunk_struct_id TEXT NOT NULL,
+      consumer TEXT NOT NULL CHECK (consumer IN ('dense', 'li', 'dedup')),
+      PRIMARY KEY (dependency_key, file_path, chunk_struct_id, consumer)
+    ) WITHOUT ROWID;
+  `);
+  db.exec(`
+    CREATE INDEX IF NOT EXISTS idx_encoder_deps_by_chunk
+      ON encoder_input_dependencies (file_path, chunk_struct_id);
+  `);
+}
+
+/**
+ * Run every reconcile-v2 schema migration against the given database.
+ *
+ * The migrations are split by destination table so callers that only need
+ * one can call the focused helper, but the umbrella is the common path for
+ * the reconcile bootstrap.
+ *
+ * @param {{ codeGraph: import('better-sqlite3').Database, vectors: import('better-sqlite3').Database }} dbs
+ * @returns {{vectors:{added:string[]}, entities:{added:string[]}, relationships:{added:string[]}}}
+ */
+export function applyReconcileSchemaMigrations(dbs) {
+  const { codeGraph, vectors } = dbs;
+  const vRes = migrateVectorsSchema(vectors);
+  const eRes = migrateEntitiesSchema(codeGraph);
+  const rRes = migrateRelationshipsSchema(codeGraph);
+  ensureEncoderDepsSchema(codeGraph);
+  return { vectors: vRes, entities: eRes, relationships: rRes };
+}