sweet-search 2.5.2 → 2.5.4

package/core/incremental-indexing/infrastructure/lockfile.mjs

@@ -0,0 +1,119 @@
+/**
+ * Single-writer lockfile with stale-owner recovery.
+ *
+ * Plan § 8.5 + § 8.6. The reconcile daemon, full reindex command, and
+ * maintenance worker all coordinate through `.sweet-search/
+ * index-maintainer.lock`. Each holder writes `{ pid, bootId, acquiredAt }`
+ * into the file; acquirers check whether the owner is still alive and
+ * release stale locks automatically.
+ *
+ * Stale-recovery rules (plan § 8.6 + § 11):
+ *   - If `bootId` differs from current → stale; clear.
+ *   - If `bootId` matches but `kill -0 pid` returns ESRCH → stale; clear.
+ *   - If alive → fail-fast with conflicting pid.
+ *
+ * Plan § 8.6 "Crash-leak recovery": when a stale lock is cleared, the
+ * caller enqueues an immediate Float HNSW background replacement with
+ * `reason = "crash_recovery"` so the duplicate-append window from an
+ * interrupted tick self-heals within minutes.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { bootIdStub } from './reader-heartbeat.mjs';
+
+export const LOCK_FILENAME = 'index-maintainer.lock';
+
+class LockHeldError extends Error {
+  constructor(owner) {
+    super(`index-maintainer.lock held by pid ${owner.pid} (bootId=${owner.bootId})`);
+    this.name = 'LockHeldError';
+    this.owner = owner;
+  }
+}
+
+function lockPath(stateDir) {
+  return path.join(stateDir, LOCK_FILENAME);
+}
+
+function readLock(stateDir) {
+  const p = lockPath(stateDir);
+  if (!fs.existsSync(p)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(p, 'utf-8'));
+  } catch {
+    return { corrupted: true };
+  }
+}
+
+function processAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return err.code === 'EPERM';
+  }
+}
+
+/**
+ * Try to acquire the lockfile. Returns a token the caller passes to
+ * `release()` when done. Throws `LockHeldError` when a live holder
+ * has it.
+ *
+ * @param {string} stateDir
+ * @returns {{pid:number, bootId:string, acquiredAt:string, staleCleared:boolean}}
+ */
+export function acquireLock(stateDir) {
+  fs.mkdirSync(stateDir, { recursive: true });
+  const existing = readLock(stateDir);
+  let staleCleared = false;
+  if (existing && !existing.corrupted) {
+    const currentBoot = bootIdStub();
+    if (existing.bootId !== currentBoot) {
+      // Different boot → owner can't possibly be alive.
+      try { fs.unlinkSync(lockPath(stateDir)); } catch {}
+      staleCleared = true;
+    } else if (!processAlive(existing.pid)) {
+      try { fs.unlinkSync(lockPath(stateDir)); } catch {}
+      staleCleared = true;
+    } else {
+      throw new LockHeldError(existing);
+    }
+  } else if (existing && existing.corrupted) {
+    try { fs.unlinkSync(lockPath(stateDir)); } catch {}
+    staleCleared = true;
+  }
+  const token = {
+    pid: process.pid,
+    bootId: bootIdStub(),
+    acquiredAt: new Date().toISOString(),
+    staleCleared,
+  };
+  // O_EXCL semantics via wx flag.
+  const fd = fs.openSync(lockPath(stateDir), 'wx');
+  try {
+    fs.writeSync(fd, JSON.stringify(token));
+    fs.fsyncSync(fd);
+  } finally {
+    fs.closeSync(fd);
+  }
+  return token;
+}
+
+/**
+ * Release the lock. Idempotent; missing files are not an error.
+ *
+ * @param {string} stateDir
+ * @param {{pid:number, bootId:string}} token
+ */
+export function releaseLock(stateDir, token) {
+  const existing = readLock(stateDir);
+  if (!existing || existing.corrupted) return;
+  if (existing.pid !== token.pid || existing.bootId !== token.bootId) {
+    // Someone else has taken the lock; don't unlink theirs.
+    return;
+  }
+  try { fs.unlinkSync(lockPath(stateDir)); } catch {}
+}
+
+export { LockHeldError };

package/core/incremental-indexing/infrastructure/maintenance-state-reader.mjs

@@ -0,0 +1,283 @@
+/**
+ * Maintenance-state readers.
+ *
+ * The reconciler invokes `readMaintenanceState()` at the end of each tick;
+ * `domain/watermark-scheduler.mjs::evaluateWatermarks` consumes the output
+ * and emits jobs when a tier crosses its threshold. Prior to this module,
+ * the production adapter reported only FTS5 and sparse-gram counters, so
+ * Float HNSW, Binary HNSW, and LI maintenance jobs never fired (see
+ * `eval/results/incremental-soak/REPORT.md` § 6.2 Finding 1).
+ *
+ * Each reader is intentionally cheap (small JSON + small bitmap reads) and
+ * degrades safely to a zero-metric object when an artifact is missing,
+ * legacy, or unreadable. Readers MUST NOT throw — the maintenance loop
+ * tolerates partial state, not exceptions.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import Database from 'better-sqlite3';
+
+import { loadBitmap, popcount, tombstoneFraction } from './tombstone-bitmap.mjs';
+import { deltaSizeStats } from './sparse-gram-delta.mjs';
+import { evaluateSegmentRatios, LI_SEGMENT_SIZE } from './li-segment-state.mjs';
+import { fts5SegmentCount } from './sqlite-fts5.mjs';
+
+function readJson(filePath) {
+  try { return JSON.parse(fs.readFileSync(filePath, 'utf-8')); } catch { return null; }
+}
+
+/**
+ * FTS5: max segment count across the two graph FTS tables. Returns 0 when
+ * the graph DB is absent or the tables are unmigrated.
+ */
+export function readFts5State(stateDir) {
+  const graph = path.join(stateDir, 'code-graph.db');
+  if (!fs.existsSync(graph)) return { segmentCount: 0 };
+  const db = new Database(graph, { readonly: true });
+  try {
+    const segmentCount = Math.max(
+      fts5SegmentCount(db, 'entities_fts'),
+      fts5SegmentCount(db, 'entities_trigram'),
+    );
+    return { segmentCount };
+  } catch {
+    return { segmentCount: 0 };
+  } finally {
+    db.close();
+  }
+}
+
+/**
+ * Sparse-gram delta artifacts: relative size + segment count for the
+ * compaction watermark.
+ */
+export function readSparseGramState(stateDir) {
+  try {
+    const stats = deltaSizeStats(path.join(stateDir, 'codebase-sparse-grams.idx'));
+    return { deltaSizeRatio: stats.ratio, deltaSegmentCount: stats.deltaSegments };
+  } catch {
+    return { deltaSizeRatio: 0, deltaSegmentCount: 0 };
+  }
+}
+
+/**
+ * Float HNSW: meta.json carries `idMap` (live ids — pruned on `remove()`)
+ * and the stale bitmap at `.idx.stale.bin` mirrors the soft-delete state.
+ *
+ *   tombstoneFraction = popcount(bitmap) / (popcount + liveTotal)
+ *
+ * `liveCandidateShortfall` stays undefined here — that signal must come
+ * from a query-path counter (plan § 7.3), not from offline state.
+ */
+export function readFloatHnswState(stateDir) {
+  const empty = { tombstoneFraction: 0, deleteCycles: 0 };
+  const metaPath = path.join(stateDir, 'codebase-hnsw.meta.json');
+  if (!fs.existsSync(metaPath)) return empty;
+  const meta = readJson(metaPath);
+  if (!meta) return empty;
+  const idMap = Array.isArray(meta.idMap) ? meta.idMap : [];
+  const liveTotal = idMap.length;
+  let bitmap = null;
+  try { bitmap = loadBitmap(path.join(stateDir, 'codebase-hnsw.idx.stale.bin')); } catch { bitmap = null; }
+  const fraction = bitmap ? tombstoneFraction(bitmap, liveTotal) : 0;
+  return { tombstoneFraction: fraction, deleteCycles: 0 };
+}
+
+/**
+ * Binary HNSW: meta.json's `vectorCount` is the row count in `vectors.json`
+ * (never pruned — see `binary-hnsw-index.js::save`). The bitmap at
+ * `.idx.stale.bin` flags retired rows; deadDocRatio = popcount / total.
+ */
+export function readBinaryHnswState(stateDir) {
+  const empty = { deadDocRatio: 0 };
+  const metaPath = path.join(stateDir, 'codebase-binary-hnsw.meta.json');
+  if (!fs.existsSync(metaPath)) return empty;
+  const meta = readJson(metaPath);
+  if (!meta) return empty;
+  const total = Number(meta.vectorCount) || 0;
+  if (total <= 0) return empty;
+  let bitmap = null;
+  try { bitmap = loadBitmap(path.join(stateDir, 'codebase-binary-hnsw.idx.stale.bin')); } catch { bitmap = null; }
+  const markedDead = bitmap ? popcount(bitmap) : 0;
+  // True dead count is divergence from codebase.db (the liveness authority):
+  // binary rows that are no longer live there, whether or not their stale bit
+  // was ever set. This catches a retire that never reached the binary tier so
+  // binaryHnswHandler (codebase.db-sourced) is scheduled to reclaim it. Falls
+  // back to the stale-bitmap popcount when codebase.db is unavailable.
+  let divergentDead = 0;
+  const dbPath = path.join(stateDir, 'codebase.db');
+  if (fs.existsSync(dbPath)) {
+    const db = new Database(dbPath, { readonly: true });
+    try {
+      const cols = db.prepare('PRAGMA table_info(vectors)').all().map((c) => c.name);
+      if (cols.includes('epoch_retired')) {
+        const live = db.prepare('SELECT COUNT(*) AS n FROM vectors WHERE epoch_retired IS NULL').get().n || 0;
+        divergentDead = Math.max(0, total - live);
+      }
+    } catch { divergentDead = 0; } finally { db.close(); }
+  }
+  const dead = Math.max(markedDead, divergentDead);
+  // Rows retired in codebase.db whose binary stale bit was never set. This is
+  // the precise signature of a retire that failed to reach the binary tier;
+  // surfacing it lets the scheduler reclaim promptly instead of waiting for the
+  // dead-doc ratio to cross its threshold from unrelated churn.
+  const unexplainedDead = Math.max(0, divergentDead - markedDead);
+  return { deadDocRatio: dead / total, unexplainedDead };
+}
+
+/**
+ * LI segments: walks `codebase-late-interaction.db.segments/manifest.json`
+ * and asks `li-segment-state.evaluateSegmentRatios` for the stale ratio
+ * per segment. Legacy unsegmented indices (or missing manifest) return [].
+ */
+export function readLiSegmentsState(stateDir) {
+  const stubPath = path.join(stateDir, 'codebase-late-interaction.db');
+  if (!fs.existsSync(stubPath)) return [];
+  const stub = readJson(stubPath);
+  if (!stub || stub.format !== 'segmented' || !stub.segmentDir) return [];
+  const segmentDir = path.resolve(stateDir, stub.segmentDir);
+  const manifestPath = path.join(segmentDir, 'manifest.json');
+  if (!fs.existsSync(manifestPath)) return [];
+  const manifest = readJson(manifestPath);
+  if (!manifest || !Array.isArray(manifest.segments)) return [];
+  const docCounts = new Map();
+  for (const seg of manifest.segments) {
+    if (!seg || typeof seg.path !== 'string' || !Number.isFinite(seg.count)) continue;
+    docCounts.set(path.join(segmentDir, seg.path), seg.count);
+  }
+  if (docCounts.size === 0) return [];
+  try {
+    return evaluateSegmentRatios(segmentDir, docCounts);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * LI segment-count stats for the batch-merge watermark. `smallSegmentCount`
+ * is the number of sealed segments below the SSLX capacity — the ones that
+ * accumulate ~1/tick and that the merge collapses. Legacy / missing indices
+ * return zeros.
+ */
+export function readLiSegmentStats(stateDir) {
+  const empty = { segmentCount: 0, smallSegmentCount: 0, pendingDeleteFiles: 0 };
+  const stubPath = path.join(stateDir, 'codebase-late-interaction.db');
+  if (!fs.existsSync(stubPath)) return empty;
+  const stub = readJson(stubPath);
+  if (!stub || stub.format !== 'segmented' || !stub.segmentDir) return empty;
+  const segmentDir = path.resolve(stateDir, stub.segmentDir);
+  const manifestPath = path.join(segmentDir, 'manifest.json');
+  if (!fs.existsSync(manifestPath)) return empty;
+  const manifest = readJson(manifestPath);
+  if (!manifest || !Array.isArray(manifest.segments)) return empty;
+  let small = 0;
+  for (const seg of manifest.segments) {
+    if (Number.isFinite(seg?.count) && seg.count < LI_SEGMENT_SIZE) small += 1;
+  }
+  // Quarantined (deferred-delete) segment files awaiting a grace-gated sweep.
+  // Surfaced so the watermark can re-trigger the merge handler to drain them
+  // even when no segment-count merge is otherwise due.
+  let pendingDeleteFiles = 0;
+  const pendingPath = path.join(segmentDir, 'pending-delete.jsonl');
+  try {
+    for (const line of fs.readFileSync(pendingPath, 'utf-8').split('\n')) {
+      const trimmed = line.trim();
+      if (!trimmed) continue;
+      try {
+        const entry = JSON.parse(trimmed);
+        if (entry && Array.isArray(entry.paths)) pendingDeleteFiles += entry.paths.length;
+      } catch { /* skip torn line */ }
+    }
+  } catch { /* no pending-delete journal */ }
+  return { segmentCount: manifest.segments.length, smallSegmentCount: small, pendingDeleteFiles };
+}
+
+/**
+ * Retired-vector counts in `codebase.db` for the physical-GC watermark.
+ * `retiredCount` = rows with a non-null `epoch_retired`; `retiredRatio` =
+ * retired / total. Returns zeros when the DB / table / column is absent.
+ */
+export function readVectorGcState(stateDir) {
+  const empty = { retiredCount: 0, retiredRatio: 0, totalCount: 0 };
+  const dbPath = path.join(stateDir, 'codebase.db');
+  if (!fs.existsSync(dbPath)) return empty;
+  const db = new Database(dbPath, { readonly: true });
+  try {
+    const cols = db.prepare('PRAGMA table_info(vectors)').all().map((c) => c.name);
+    if (!cols.includes('epoch_retired')) return empty;
+    const total = db.prepare('SELECT COUNT(*) AS n FROM vectors').get().n || 0;
+    const retired = db.prepare('SELECT COUNT(*) AS n FROM vectors WHERE epoch_retired IS NOT NULL').get().n || 0;
+    return { retiredCount: retired, retiredRatio: total > 0 ? retired / total : 0, totalCount: total };
+  } catch {
+    return empty;
+  } finally {
+    db.close();
+  }
+}
+
+/**
+ * Retired-row counts in `code-graph.db` for the graph physical-GC watermark.
+ * `retiredEntities` / `retiredRelationships` = rows with a non-null
+ * `epoch_retired`; `retiredEntityRatio` = retiredEntities / totalEntities.
+ * `retiredRows` is the combined entity+relationship tombstone count used by
+ * the count watermark. Returns zeros when the DB / tables / column are absent.
+ */
+export function readGraphGcState(stateDir) {
+  const empty = {
+    retiredEntities: 0, retiredRelationships: 0, retiredSummaries: 0,
+    retiredRows: 0, totalEntities: 0, retiredEntityRatio: 0,
+  };
+  const dbPath = path.join(stateDir, 'code-graph.db');
+  if (!fs.existsSync(dbPath)) return empty;
+  const db = new Database(dbPath, { readonly: true });
+  try {
+    const tableHas = (table, column) => {
+      try { return db.prepare(`PRAGMA table_info(${table})`).all().some((c) => c.name === column); }
+      catch { return false; }
+    };
+    let retiredEntities = 0;
+    let totalEntities = 0;
+    if (tableHas('entities', 'epoch_retired')) {
+      totalEntities = db.prepare('SELECT COUNT(*) AS n FROM entities').get().n || 0;
+      retiredEntities = db.prepare('SELECT COUNT(*) AS n FROM entities WHERE epoch_retired IS NOT NULL').get().n || 0;
+    }
+    let retiredRelationships = 0;
+    if (tableHas('relationships', 'epoch_retired')) {
+      retiredRelationships = db.prepare('SELECT COUNT(*) AS n FROM relationships WHERE epoch_retired IS NOT NULL').get().n || 0;
+    }
+    let retiredSummaries = 0;
+    if (tableHas('hcgs_summary_metadata', 'epoch_retired')) {
+      retiredSummaries = db.prepare('SELECT COUNT(*) AS n FROM hcgs_summary_metadata WHERE epoch_retired IS NOT NULL').get().n || 0;
+    }
+    return {
+      retiredEntities,
+      retiredRelationships,
+      retiredSummaries,
+      retiredRows: retiredEntities + retiredRelationships,
+      totalEntities,
+      retiredEntityRatio: totalEntities > 0 ? retiredEntities / totalEntities : 0,
+    };
+  } catch {
+    return empty;
+  } finally {
+    db.close();
+  }
+}
+
+/**
+ * One-shot bundle for the reconciler adapter. Returns the full shape
+ * `evaluateWatermarks` expects: `fts5 / sparseGram / floatHnsw /
+ * binaryHnsw / liSegments / liSegmentStats / vectors / graph`.
+ */
+export function readMaintenanceState(stateDir) {
+  return {
+    fts5: readFts5State(stateDir),
+    sparseGram: readSparseGramState(stateDir),
+    floatHnsw: readFloatHnswState(stateDir),
+    binaryHnsw: readBinaryHnswState(stateDir),
+    liSegments: readLiSegmentsState(stateDir),
+    liSegmentStats: readLiSegmentStats(stateDir),
+    vectors: readVectorGcState(stateDir),
+    graph: readGraphGcState(stateDir),
+  };
+}

package/core/incremental-indexing/infrastructure/manifest.mjs

@@ -0,0 +1,194 @@
+/**
+ * Reconcile manifest reader / writer.
+ *
+ * Plan § 8.1. The manifest is the single source of truth for "which tier
+ * artifacts and sidecars belong to which reconcile epoch". Readers pin
+ * one manifest at query start and use only the paths it names for the
+ * full query duration; the reconciler stages all per-tier writes under
+ * `<artifact>.next` (or per-tier append paths) and publishes a new
+ * manifest atomically via `fsync + rename`.
+ *
+ * Manifest shape (plan § 8.1):
+ *
+ *   {
+ *     "epoch": 12847,
+ *     "publishedAt": "2026-05-15T23:00:00.000Z",
+ *     "codeGraph":      { "path": "code-graph.db", "epoch": 12847 },
+ *     "vectors":        { "path": "codebase.db", "epoch": 12847 },
+ *     "hnsw":           { "path": "codebase-hnsw.idx",
+ *                          "stale": "codebase-hnsw.idx.stale.bin",
+ *                          "epoch": 12847 },
+ *     "binaryHnsw":     { "path": "codebase-binary-hnsw.idx", "epoch": 12847 },
+ *     "lateInteraction":{ "manifest": "codebase-late-interaction.db.segments/manifest.json",
+ *                          "epoch": 12847 },
+ *     "sparseGram":     { "base": "codebase-sparse-grams.idx",
+ *                          "deltas": ["codebase-sparse-grams.idx.deltas/12847-0.ssgrmdelta"],
+ *                          "weightsId": "common-code-bigram-v1",
+ *                          "epoch": 12847 }
+ *   }
+ *
+ * The manifest is written to `.sweet-search/reconcile-manifest.json` with
+ * a `*.tmp` staging file + fsync + rename + parent-dir fsync. Readers MUST
+ * load the manifest fresh per query (cheap — single JSON read of a small
+ * file); the reconciler is the only writer.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const MANIFEST_FILENAME = 'reconcile-manifest.json';
+export const DEFAULT_SPARSE_GRAM_WEIGHTS_ID = 'common-code-bigram-v1';
+
+function manifestPath(stateDir) {
+  return path.join(stateDir, MANIFEST_FILENAME);
+}
+
+function tempManifestPath(stateDir) {
+  return path.join(stateDir, MANIFEST_FILENAME + '.tmp');
+}
+
+/**
+ * Build a zero-state manifest for a brand-new index. Plan § 25.2:
+ * the manifest is created at first reconcile tick alongside the
+ * STATE_VERSION bump.
+ *
+ * @param {object} paths   per-tier filename map relative to stateDir
+ * @returns {object}
+ */
+export function zeroManifest(paths) {
+  return {
+    epoch: 0,
+    publishedAt: new Date().toISOString(),
+    codeGraph: { path: paths.codeGraph || 'code-graph.db', epoch: 0 },
+    vectors: { path: paths.vectors || 'codebase.db', epoch: 0 },
+    hnsw: {
+      path: paths.hnsw || 'codebase-hnsw.idx',
+      stale: paths.hnswStale || 'codebase-hnsw.idx.stale.bin',
+      epoch: 0,
+    },
+    binaryHnsw: {
+      path: paths.binaryHnsw || 'codebase-binary-hnsw.idx',
+      epoch: 0,
+    },
+    lateInteraction: {
+      manifest: paths.liManifest || 'codebase-late-interaction.db.segments/manifest.json',
+      epoch: 0,
+    },
+    sparseGram: {
+      base: paths.sparseBase || 'codebase-sparse-grams.idx',
+      deltas: paths.sparseDeltas || [],
+      weightsId: paths.weightsId || DEFAULT_SPARSE_GRAM_WEIGHTS_ID,
+      epoch: 0,
+    },
+  };
+}
+
+/**
+ * Read the current manifest. Returns `null` when none has been written
+ * yet — callers fall back to the legacy "open whatever file exists"
+ * behaviour until the reconciler runs at least once.
+ *
+ * @param {string} stateDir
+ * @returns {object|null}
+ */
+export function readManifest(stateDir) {
+  const p = manifestPath(stateDir);
+  if (!fs.existsSync(p)) return null;
+  try {
+    const raw = fs.readFileSync(p, 'utf-8');
+    return JSON.parse(raw);
+  } catch (err) {
+    // A corrupted manifest is recoverable: the next reconcile tick
+    // rebuilds it from the per-tier artifacts on disk. We return null so
+    // callers can fall back to the legacy paths until then.
+    return null;
+  }
+}
+
+/**
+ * Atomic write of a new manifest. Plan § 8.1 step 4 requires:
+ *
+ *   1. write `*.tmp`
+ *   2. fsync the temp file
+ *   3. atomically rename to the live name
+ *   4. fsync the parent directory so the rename survives a power loss
+ *
+ * @param {string} stateDir
+ * @param {object} manifest
+ */
+export function writeManifest(stateDir, manifest) {
+  fs.mkdirSync(stateDir, { recursive: true });
+  const tmp = tempManifestPath(stateDir);
+  const live = manifestPath(stateDir);
+  const data = JSON.stringify(manifest, null, 2);
+
+  const fd = fs.openSync(tmp, 'w');
+  try {
+    fs.writeSync(fd, data);
+    fs.fsyncSync(fd);
+  } finally {
+    fs.closeSync(fd);
+  }
+  fs.renameSync(tmp, live);
+  // Best-effort dir fsync. Some filesystems (e.g. tmpfs in containers)
+  // throw EINVAL on directory fsync; that is harmless because no power
+  // loss can affect them.
+  try {
+    const dirFd = fs.openSync(stateDir, 'r');
+    try { fs.fsyncSync(dirFd); } finally { fs.closeSync(dirFd); }
+  } catch {
+    // ignore
+  }
+}
+
+/**
+ * Build the next-epoch manifest from a previous manifest plus a list of
+ * per-tier overrides. The reconciler calls this once per tick after the
+ * per-tier writes finish staging.
+ *
+ * @param {object} prev    Previous manifest (use `zeroManifest` on first tick).
+ * @param {{epoch:number, tiers:object}} delta
+ * @returns {object}
+ */
+export function buildNextManifest(prev, delta) {
+  if (!Number.isInteger(delta.epoch)) {
+    throw new Error('buildNextManifest: delta.epoch must be an integer');
+  }
+  const out = {
+    ...prev,
+    epoch: delta.epoch,
+    publishedAt: new Date().toISOString(),
+  };
+  const tiers = delta.tiers || {};
+  for (const key of ['codeGraph', 'vectors', 'hnsw', 'binaryHnsw', 'lateInteraction', 'sparseGram']) {
+    if (!tiers[key]) {
+      // Carry forward the previous tier descriptor with the new epoch.
+      out[key] = { ...(prev[key] || {}), epoch: delta.epoch };
+      continue;
+    }
+    out[key] = { ...prev[key], ...tiers[key], epoch: delta.epoch };
+  }
+  return out;
+}
+
+/**
+ * SQL predicate fragment that filters rows visible at a given manifest
+ * epoch. Plan § 8.1.1 / § 7.2:
+ *
+ *   epoch_written <= :manifestEpoch
+ *     AND (epoch_retired IS NULL OR epoch_retired > :manifestEpoch)
+ *
+ * Returned with named-parameter placeholders so callers can bind the
+ * value once and reuse the prepared statement across queries.
+ *
+ * @param {string} [alias]   Optional table alias (e.g. `'v.'` or `'e.'`).
+ * @returns {string}
+ */
+export function epochVisibilityPredicate(alias = '') {
+  const normalizedAlias = alias.endsWith('.') ? alias.slice(0, -1) : alias;
+  const a = normalizedAlias.length > 0 ? `${normalizedAlias}.` : '';
+  return (
+    `${a}epoch_written <= :manifestEpoch ` +
+    `AND (${a}epoch_retired IS NULL OR ${a}epoch_retired > :manifestEpoch)`
+  );
+}