@remnic/coding-graph 9.3.759

package/dist/chunk-CPYJACC5.js

@@ -0,0 +1,1838 @@
+import {
+  applyCodingGraphSchema,
+  expectRow,
+  expectRows,
+  ftsRowidForNodeId,
+  isEdgeProvenance,
+  readSchemaVersion
+} from "./chunk-ZVCMIM4T.js";
+
+// src/graph-store.ts
+import { createHash } from "crypto";
+import { mkdir, readFile } from "fs/promises";
+import path from "path";
+import {
+  openBetterSqlite3
+} from "@remnic/core/runtime/better-sqlite";
+var DEFAULT_TRAVERSE_PATHS_MAX = 1e4;
+var MAX_TRAVERSE_PATHS_HOPS = 1e3;
+var DEAD_CODE_EXCLUSION = {
+  /**
+   * Edge types that — when pointing INTO a node — count as "this node
+   * is used". Mirrors the issue's `CALLS/USAGE` wording plus the four
+   * call-flavored edge types in the wider coding-graph vocabulary.
+   */
+  INBOUND_USAGE_EDGE_TYPES: [
+    "CALLS",
+    "USES_TYPE",
+    "ASYNC_CALLS",
+    "HTTP_CALLS",
+    "DATA_FLOWS"
+  ],
+  /**
+   * File-path regexes identifying test files. Matched against
+   * `files.path` (repo-relative, forward slashes).
+   */
+  TEST_PATH_PATTERNS: [
+    /\.test\.[cm]?[tj]sx?$/,
+    /\.spec\.[cm]?[tj]sx?$/,
+    /(^|\/)__tests__\//,
+    /(^|\/)__mocks__\//,
+    /(^|\/)tests?\//,
+    /(^|\/)test\//
+  ],
+  /**
+   * File-path regexes identifying entry points (reachable from
+   * outside the indexed code). Matched against `files.path`. Kept
+   * deliberately narrow — `server.ts` / `app.ts` are intentionally
+   * NOT treated as entry points because they are common module
+   * names that may also contain dead helpers. The conservative
+   * direction is to report a symbol as dead rather than hide it.
+   */
+  ENTRY_POINT_PATH_PATTERNS: [
+    /(^|\/)index\.[cm]?[tj]sx?$/,
+    /(^|\/)main\.[cm]?[tj]sx?$/,
+    /(^|\/)cli\.[cm]?[tj]sx?$/,
+    /(^|\/)bin\//,
+    /(^|\/)src\/bin\//
+  ],
+  /**
+   * Columns on `node_attributes` whose value being `1` excludes the
+   * node. Names mirror the schema so a future column add is a one-line
+   * constant extension + a query clause (no scattered edits).
+   */
+  EXCLUDED_ATTRIBUTE_FLAGS: ["is_exported", "is_route_handler"]
+};
+function isExcludedByPath(filePath) {
+  for (const re of DEAD_CODE_EXCLUSION.TEST_PATH_PATTERNS) {
+    if (re.test(filePath)) return true;
+  }
+  for (const re of DEAD_CODE_EXCLUSION.ENTRY_POINT_PATH_PATTERNS) {
+    if (re.test(filePath)) return true;
+  }
+  return false;
+}
+var SQLITE_VARIABLE_LIMIT = 32766;
+var WriteQueue = class {
+  tail = Promise.resolve();
+  schedule(run) {
+    const next = this.tail.then(run, run);
+    this.tail = next.catch(() => void 0);
+    return next;
+  }
+  /** Test seam: wait until the queue has drained. */
+  async drain() {
+    await this.tail;
+  }
+};
+var GraphStore = class _GraphStore {
+  db;
+  queue = new WriteQueue();
+  repoRoot;
+  closed = false;
+  closing = false;
+  /**
+   * True once close() has begun (closing) or completed (closed). Public so
+   * callers that hold a GraphStore reference can return the documented
+   * 'store_closed' degradation code instead of treating a closed store as
+   * an empty graph (cursor Bugbot: 'Closed store reports success'). The
+   * read primitives already short-circuit on this internally; this getter
+   * lets the semantic entry points do the same BEFORE calling a read that
+   * would return [].
+   */
+  get isClosed() {
+    return this.closed || this.closing;
+  }
+  // Shared drain-and-close promise so a second close() called while the
+  // first is still draining awaits the same completion instead of
+  // resolving early (chatgpt-codex-connector P2: 'Wait for an
+  // in-progress close').
+  closePromise;
+  constructor(db, repoRoot) {
+    this.db = db;
+    this.repoRoot = repoRoot;
+  }
+  /**
+   * Open a store at the given dbPath. Creates parent directories and
+   * applies the schema (idempotent — also handles upgrade). The dbPath
+   * does no namespace resolution.
+   */
+  static async open(options) {
+    const { dbPath, repoRoot } = options;
+    if (!path.isAbsolute(dbPath)) {
+      throw new Error(
+        `graph-store: dbPath must be absolute; received ${JSON.stringify(dbPath)}`
+      );
+    }
+    if (repoRoot !== void 0 && !path.isAbsolute(repoRoot)) {
+      throw new Error(
+        `graph-store: repoRoot must be absolute when provided; received ${JSON.stringify(repoRoot)}`
+      );
+    }
+    await mkdir(path.dirname(dbPath), { recursive: true });
+    const db = openBetterSqlite3(dbPath);
+    db.pragma("journal_mode = WAL");
+    db.pragma("busy_timeout = 5000");
+    db.pragma("synchronous = NORMAL");
+    db.pragma("foreign_keys = ON");
+    applyCodingGraphSchema(db);
+    return new _GraphStore(db, repoRoot);
+  }
+  /**
+   * The current schema_version row. Test seam — never expires, never
+   * cached so migrations land without a restart.
+   */
+  schemaVersion() {
+    return readSchemaVersion(this.db);
+  }
+  /**
+   * Ingest a batch of IR files atomically. One transaction wraps every
+   * file's delete + insert; if any file throws, the whole batch rolls
+   * back (rule 34 — never partial-write a coding graph).
+   *
+   * Re-ingesting the same IR is a no-op once the rows are written
+   * (idempotency — node ids are deterministic so the second pass collides
+   * on PRIMARY KEY).
+   *
+   * Two-pass ordering: pass 1 upserts every file's nodes (so FTS stays
+   * in sync and cross-file edge targets exist by the time pass 2 runs),
+   * pass 2 resolves edges against the full batch's node map and deletes
+   * prior edges owned by these files so changed confidence/provenance
+   * values overwrite (chatgpt-codex-connector P1 + cursor medium + PR1
+   * design anchor in graph-schema).
+   *
+   * Tagging:
+   *   - `{ok:true, results}` — every file's counts.
+   *   - `{ok:false, code:"db_locked"}` — busy_timeout elapsed; caller may
+   *     retry. NOT a thrown error so the agent can degrade gracefully.
+   *   - `{ok:false, code:"db_corrupt"}` — SQLite reported
+   *     `database disk image is malformed`; the caller must surface and
+   *     stop trusting this DB.
+   */
+  async upsertFileBatch(files, deletePaths = []) {
+    if (this.closed || this.closing) {
+      return {
+        ok: false,
+        code: "store_closed"
+      };
+    }
+    return this.queue.schedule(() => this.runUpsert(files, deletePaths));
+  }
+  /**
+   * Upsert standalone edges whose endpoints are resolved from the FULL
+   * database (not just a per-file batch). Used by the codegraph
+   * ingest_traces surface (issue #1554) to persist runtime HTTP_CALLS
+   * observations as edges with `provenance: "trace"` — upgrading
+   * confidence on existing edges and inserting new ones.
+   *
+   * Endpoint resolution: when an edge carries `srcNodeId` / `dstNodeId`
+   * (issue #1677 — the SIMILAR_TO pipeline populates them from
+   * content-derived node ids), the endpoint is resolved by `nodes.id`
+   * (unique primary key), so an edge between two symbols that share a
+   * qualified name across files is persisted rather than dropped as
+   * ambiguous. Edges WITHOUT node ids fall back to qualified_name
+   * resolution via the global `resolveNodeId` (unambiguous single-match
+   * policy). Edges whose endpoints do not resolve (missing node id row OR
+   * an ambiguous/dangling qualified name) are skipped (and counted in
+   * `skipped`) rather than attached to the wrong node — the dangling-edge
+   * policy from `upsertFileBatch` applies.
+   *
+   * Serialized on the store's write queue like `upsertFileBatch` so a
+   * concurrent file-batch upsert and a trace upsert cannot interleave
+   * (rule 40).
+   */
+  async upsertEdges(edges) {
+    if (this.closed || this.closing) {
+      return { ok: false, code: "store_closed" };
+    }
+    return this.queue.schedule(() => this.runUpsertEdges(edges));
+  }
+  /** Wait for pending writes to drain — test seam. */
+  async drain() {
+    await this.queue.drain();
+  }
+  // ──────────────────────────────────────────────────────────────────────
+  // PR3 (issue #1553): meta-table + file-management methods for the
+  // incremental reindex pipeline.
+  // ──────────────────────────────────────────────────────────────────────
+  /**
+   * Read a value from the `meta` table. Returns `null` when the key is
+   * absent. Synchronous (like the other read primitives) so the reindex
+   * planner can read `last_indexed_head` without an await.
+   */
+  readMeta(key) {
+    if (this.closed) return { ok: false, code: "store_closed" };
+    try {
+      const row = expectRow(
+        this.db.prepare("SELECT value FROM meta WHERE key = ?").get(key),
+        ["value"]
+      );
+      return { ok: true, value: row ? row.value : null };
+    } catch (error) {
+      logWriteFailure(error);
+      return classifyReadError(error);
+    }
+  }
+  /**
+   * Write a key/value pair to the `meta` table. Synchronous — runs in its
+   * own implicit transaction. The reindex executor calls this AFTER
+   * `upsertFileBatch` resolves (rule 25: head/state updates only after
+   * the data transaction commits). A crash between the two leaves the old
+   * head, and the next run re-ingests idempotently (deterministic node ids).
+   */
+  writeMeta(key, value) {
+    if (this.closed) return;
+    this.db.prepare("INSERT OR REPLACE INTO meta (key, value) VALUES (?, ?)").run(key, value);
+  }
+  /**
+   * Read every file row's path → content_hash. Used by hash_scan mode
+   * to detect content drift without a reachable base commit (issue #1553).
+   */
+  readFileHashes() {
+    if (this.closed) return { ok: false, code: "store_closed" };
+    try {
+      const rows = expectRows(
+        this.db.prepare("SELECT path, content_hash FROM files").all(),
+        ["path", "content_hash"]
+      );
+      const out = /* @__PURE__ */ new Map();
+      for (const r of rows) out.set(r.path, r.content_hash);
+      return { ok: true, hashes: out };
+    } catch (error) {
+      logWriteFailure(error);
+      return classifyReadError(error);
+    }
+  }
+  /**
+   * Drop file rows by path, cascading to their nodes + edges +
+   * node_attributes (the schema's `ON DELETE CASCADE` from `files(id)`
+   * handles the cascade — `foreign_keys = ON` is set in `open()`).
+   * Used by the reindex executor to prune deleted files.
+   *
+   * Paths are chunked under the SQLite variable limit (rule 23 pattern).
+   */
+  async dropFiles(paths) {
+    if (this.closed || this.closing || paths.length === 0) return;
+    await this.queue.schedule(async () => {
+      this.runChunkedDelete(
+        "DELETE FROM files WHERE path IN (%PH%)",
+        paths
+      );
+    });
+  }
+  /**
+   * Chunk a parameterized DELETE-with-IN-list under SQLite's variable
+   * bind limit. Mirrors the chunking pattern used by `runChunkedUpdate`
+   * and the stale-edge deletes.
+   */
+  runChunkedDelete(sqlTemplate, params) {
+    if (params.length === 0) return;
+    for (let i = 0; i < params.length; i += SQLITE_VARIABLE_LIMIT) {
+      const chunk = params.slice(i, i + SQLITE_VARIABLE_LIMIT);
+      const placeholders = chunk.map(() => "?").join(", ");
+      this.db.prepare(sqlTemplate.replace("%PH%", placeholders)).run(...chunk);
+    }
+  }
+  /**
+   * PR3 (issue #1553): upsert co-change edges into the `co_changes`
+   * table. Clears existing edges then inserts the new set in one
+   * transaction (idempotent — re-running on unchanged history produces
+   * the same table). Serialized through the write queue.
+   */
+  /**
+   * PR3 (issue #1553): upsert co-change edges into the `co_changes`
+   * table. Clears existing edges then inserts the new set in one
+   * transaction (idempotent — re-running on unchanged history produces
+   * the same table). Serialized through the write queue.
+   *
+   * Returns `{ ok: false, code: "store_closed" }` when the store is
+   * closed/closing so the caller does NOT believe mining succeeded
+   * while nothing was persisted (cursor Bugbot: 'Co-change store
+   * reports false success').
+   */
+  async upsertCoChanges(edges) {
+    if (this.closed || this.closing) {
+      return { ok: false, code: "store_closed" };
+    }
+    try {
+      await this.queue.schedule(async () => {
+        const tx = this.db.transaction(() => {
+          this.db.exec("DELETE FROM co_changes");
+          const insert = this.db.prepare(
+            `INSERT INTO co_changes (file_a, file_b, support, confidence)
+               VALUES (?, ?, ?, ?)
+             ON CONFLICT(file_a, file_b) DO UPDATE SET
+               support = excluded.support,
+               confidence = excluded.confidence`
+          );
+          for (const e of edges) {
+            insert.run(e.fileA, e.fileB, e.support, e.confidence);
+          }
+        });
+        tx();
+      });
+      return { ok: true };
+    } catch (error) {
+      logWriteFailure(error);
+      return { ok: false, code: "db_error" };
+    }
+  }
+  /**
+   * PR3 (issue #1553): read co-change edges for a file. Returns edges
+   * where the file is either `file_a` or `file_b`. Synchronous read.
+   */
+  readCoChanges(filePath) {
+    if (this.closed) return { ok: false, code: "store_closed" };
+    try {
+      const rows = expectRows(
+        this.db.prepare(
+          `SELECT file_a, file_b, support, confidence
+               FROM co_changes
+              WHERE file_a = ? OR file_b = ?
+              ORDER BY confidence DESC, file_a ASC, file_b ASC`
+        ).all(filePath, filePath),
+        ["file_a", "file_b", "support", "confidence"]
+      );
+      return {
+        ok: true,
+        edges: rows.map((r) => ({
+          fileA: r.file_a,
+          fileB: r.file_b,
+          support: r.support,
+          confidence: r.confidence
+        }))
+      };
+    } catch (error) {
+      logWriteFailure(error);
+      return classifyReadError(error);
+    }
+  }
+  /**
+   * Close the SQLite handle after draining the write queue. A batch
+   * that has already been scheduled on the queue would otherwise run
+   * against a closed DB and surface as `db_corrupt` — the caller
+   * would stop trusting the store for unrelated reasons. Drain first,
+   * then close (cursor Bugbot #09be5784).
+   */
+  async close() {
+    if (this.closed) return;
+    if (this.closing) return this.closePromise;
+    this.closing = true;
+    this.closePromise = this.finishClose();
+    return this.closePromise;
+  }
+  /** Drain queued writes then close the SQLite handle exactly once. */
+  async finishClose() {
+    await this.queue.drain();
+    this.closed = true;
+    this.db.close();
+  }
+  // ────────────── private ──────────────
+  async runUpsert(files, deletePaths = []) {
+    const seenPaths = /* @__PURE__ */ new Set();
+    for (const ir of files) {
+      assertCanonicalFilePath(ir.path);
+      if (seenPaths.has(ir.path)) {
+        throw new Error(
+          `graph-store: duplicate path '${ir.path}' in batch \u2014 each FileIR must have a unique path`
+        );
+      }
+      seenPaths.add(ir.path);
+      const symbolsField = ir.symbols;
+      if (!Array.isArray(symbolsField)) {
+        throw new Error(
+          `graph-store: file '${ir.path}' symbols must be an array (FileIR contract requires it); received ${symbolsField === null ? "null" : typeof symbolsField} \u2014 refusing to ingest to avoid wiping existing nodes`
+        );
+      }
+      for (const sym of symbolsField) {
+        assertValidSymbolSpan(sym, ir.path);
+      }
+      if (ir.exports != null) {
+        if (!Array.isArray(ir.exports)) {
+          throw new Error(
+            `graph-store: file '${ir.path}' exports must be an array when present; received ${ir.exports === null ? "null" : typeof ir.exports} \u2014 refusing to ingest to avoid wiping existing flags`
+          );
+        }
+        for (const ex of ir.exports) {
+          if (!ex || typeof ex.name !== "string" || ex.name.length === 0) {
+            throw new Error(
+              `graph-store: file '${ir.path}' has a malformed export entry \u2014 expected { name: string (non-empty) }; refusing to ingest to avoid wiping existing flags`
+            );
+          }
+        }
+      }
+      if (ir.routes != null) {
+        if (!Array.isArray(ir.routes)) {
+          throw new Error(
+            `graph-store: file '${ir.path}' routes must be an array when present; received ${ir.routes === null ? "null" : typeof ir.routes} \u2014 refusing to ingest to avoid wiping existing flags`
+          );
+        }
+        for (const r of ir.routes) {
+          if (!r || typeof r.handlerQualifiedName !== "string" || r.handlerQualifiedName.length === 0) {
+            throw new Error(
+              `graph-store: file '${ir.path}' has a malformed route entry \u2014 expected { handlerQualifiedName: string (non-empty) }; refusing to ingest to avoid wiping existing flags`
+            );
+          }
+        }
+      }
+    }
+    try {
+      const results = [];
+      const tx = this.db.transaction((irs) => {
+        if (deletePaths.length > 0) {
+          for (let i = 0; i < deletePaths.length; i += SQLITE_VARIABLE_LIMIT) {
+            const chunk = deletePaths.slice(i, i + SQLITE_VARIABLE_LIMIT);
+            const placeholders = chunk.map(() => "?").join(", ");
+            this.db.prepare("DELETE FROM files WHERE path IN (%PH%)".replace("%PH%", placeholders)).run(...chunk);
+          }
+        }
+        const pending = [];
+        for (const ir of irs) {
+          const { result, prunedNodeIds } = this.upsertFileNodes(ir);
+          pending.push({ result, prunedNodeIds });
+          results.push(result);
+        }
+        const batchPrunedIds = [];
+        for (const { prunedNodeIds } of pending) {
+          for (const id of prunedNodeIds) batchPrunedIds.push(id);
+        }
+        for (const { result, prunedNodeIds } of pending) {
+          this.pruneFileNodes(result, prunedNodeIds, batchPrunedIds);
+        }
+        for (let i = 0; i < irs.length; i += 1) {
+          const ir = irs[i];
+          const result = results[i];
+          this.upsertFileEdges(ir, result);
+        }
+        for (let i = 0; i < irs.length; i += 1) {
+          const ir = irs[i];
+          const result = results[i];
+          this.upsertFileAttributes(ir, result);
+        }
+      });
+      tx(files);
+      return { ok: true, results };
+    } catch (error) {
+      logWriteFailure(error);
+      return classifyError(error);
+    }
+  }
+  /**
+   * Standalone-edge upsert body (runs under the write queue). Resolves
+   * both endpoints from the full DB via the unambiguous single-match
+   * `resolveNodeId` fallback, then upserts each edge with the same
+   * ON CONFLICT(src,dst,type) policy as the file-batch path. Edges whose
+   * src or dst do not resolve to exactly one node are skipped (counted
+   * in `skipped`) per the dangling-edge policy.
+   */
+  async runUpsertEdges(edges) {
+    const emptyBatch = /* @__PURE__ */ new Map();
+    const insertEdge = this.db.prepare(
+      `INSERT INTO edges (src, dst, type, confidence, provenance)
+         VALUES (?, ?, ?, ?, ?)
+         ON CONFLICT(src, dst, type) DO UPDATE SET
+           confidence = excluded.confidence,
+           provenance = excluded.provenance`
+    );
+    const nodeById = this.db.prepare(
+      "SELECT qualified_name FROM nodes WHERE id = ? LIMIT 1"
+    );
+    try {
+      let persisted = 0;
+      let skipped = 0;
+      this.db.transaction(() => {
+        for (const edge of edges) {
+          if (!isEdgeProvenance(edge.provenance)) {
+            throw new Error(
+              `graph-store: edge has invalid provenance ${JSON.stringify(edge.provenance)}`
+            );
+          }
+          if (!Number.isFinite(edge.confidence) || edge.confidence < 0 || edge.confidence > 1) {
+            throw new Error(
+              `graph-store: edge confidence ${edge.confidence} is out of range [0, 1] for edge ${edge.srcQualifiedName} \u2192 ${edge.dstQualifiedName}`
+            );
+          }
+          const srcId = edge.srcNodeId ? resolveByNodeId(nodeById, edge.srcNodeId, edge.srcQualifiedName) : resolveNodeId(edge.srcQualifiedName, emptyBatch, this.db);
+          const dstId = edge.dstNodeId ? resolveByNodeId(nodeById, edge.dstNodeId, edge.dstQualifiedName) : resolveNodeId(edge.dstQualifiedName, emptyBatch, this.db);
+          if (!srcId || !dstId) {
+            skipped += 1;
+            continue;
+          }
+          const r = insertEdge.run(srcId, dstId, edge.type, edge.confidence, edge.provenance);
+          persisted += r.changes;
+        }
+      })();
+      return { ok: true, persisted, skipped };
+    } catch (error) {
+      logWriteFailure(error);
+      return classifyError(error);
+    }
+  }
+  /**
+   * Pass 1a: upsert the file row and every symbol node, refreshing the
+   * contentless `nodes_fts` index in lockstep, and compute the set of
+   * stale node ids this file wants to prune (deterministic id, NOT
+   * qualified_name, so a kind change gets a new id and the OLD row is
+   * deleted). The prune itself — and the dangling-edge count that
+   * gates it — is deferred to {@link pruneFileNodes} so the whole batch
+   * shares one batch-wide view of what is being pruned before any
+   * cascade runs.
+   */
+  upsertFileNodes(ir) {
+    const upsertFile = this.db.prepare(
+      `INSERT INTO files (path, lang, content_hash)
+         VALUES (?, ?, ?)
+       ON CONFLICT(path) DO UPDATE SET
+         lang = excluded.lang,
+         content_hash = excluded.content_hash
+       RETURNING id`
+    );
+    const fileRow = expectRow(
+      upsertFile.get(ir.path, ir.language, ir.contentHash),
+      ["id"]
+    );
+    if (!fileRow) {
+      throw new Error(
+        `graph-store: INSERT INTO files RETURNING id returned no row for path=${ir.path}`
+      );
+    }
+    const fileId = fileRow.id;
+    const seenNodeIds = /* @__PURE__ */ new Set();
+    const symbolByNodeId = /* @__PURE__ */ new Map();
+    for (const sym of ir.symbols) {
+      const id = nodeIdFor({
+        qualifiedName: sym.qualifiedName,
+        filePath: ir.path,
+        label: sym.kind
+      });
+      seenNodeIds.add(id);
+      symbolByNodeId.set(id, sym);
+    }
+    const existingNodes = expectRows(
+      this.db.prepare(
+        `SELECT id, label, name, qualified_name, file_id,
+                  span_start, span_end, lang
+             FROM nodes WHERE file_id = ?`
+      ).all(fileId),
+      ["id", "label", "name", "qualified_name", "file_id", "span_start", "span_end", "lang"]
+    );
+    const existingById = new Map(existingNodes.map((n) => [n.id, n]));
+    const insertNode = this.db.prepare(
+      `INSERT INTO nodes (
+          id, label, name, qualified_name,
+          file_id, span_start, span_end, lang
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+        ON CONFLICT(id) DO UPDATE SET
+          label = excluded.label,
+          name = excluded.name,
+          qualified_name = excluded.qualified_name,
+          file_id = excluded.file_id,
+          span_start = excluded.span_start,
+          span_end = excluded.span_end,
+          lang = excluded.lang`
+    );
+    const insertFts = this.db.prepare(
+      `INSERT INTO nodes_fts (rowid, name, qualified_name) VALUES (?, ?, ?)`
+    );
+    const deleteFtsByRowid = this.db.prepare(
+      `DELETE FROM nodes_fts WHERE rowid = ?`
+    );
+    const upsertFtsIndex = this.db.prepare(
+      `INSERT INTO fts_index (fts_rowid, node_id) VALUES (?, ?)
+         ON CONFLICT(node_id) DO UPDATE SET
+           fts_rowid = excluded.fts_rowid`
+    );
+    const deleteFtsIndexByRowid = this.db.prepare(
+      `DELETE FROM fts_index WHERE fts_rowid = ?`
+    );
+    let nodeCount = 0;
+    for (const [id, sym] of symbolByNodeId) {
+      const prior = existingById.get(id);
+      if (prior && prior.label === sym.kind && prior.name === sym.name && prior.qualified_name === sym.qualifiedName && prior.span_start === sym.span.startByte && prior.span_end === sym.span.endByte && prior.lang === ir.language) {
+        continue;
+      }
+      const ftsRowid = ftsRowidForNodeId(id);
+      deleteFtsByRowid.run(ftsRowid);
+      deleteFtsIndexByRowid.run(ftsRowid);
+      insertNode.run(
+        id,
+        sym.kind,
+        sym.name,
+        sym.qualifiedName,
+        fileId,
+        sym.span.startByte,
+        sym.span.endByte,
+        ir.language
+      );
+      insertFts.run(ftsRowid, sym.name, sym.qualifiedName);
+      upsertFtsIndex.run(ftsRowid, id);
+      nodeCount += 1;
+    }
+    const prunedNodeIds = existingNodes.map((n) => n.id).filter((id) => !seenNodeIds.has(id));
+    return {
+      result: {
+        path: ir.path,
+        fileId,
+        nodeCount,
+        edgeCount: 0,
+        droppedDanglingEdges: 0
+      },
+      prunedNodeIds
+    };
+  }
+  /**
+   * Pass 1b: count the dangling edges this file's prune will drop and
+   * perform the cascade delete + FTS cleanup. A dangling edge is one
+   * whose dst is pruned by THIS file but whose src survives — and
+   * "survives" is judged against the BATCH-WIDE pruned set, so an edge
+   * whose both ends are pruned (possibly in different files) is
+   * cascade-deleted and never reported as dangling. This makes the
+   * reported loss independent of the order files are visited in
+   * (chatgpt-codex-connector P2: 'Count dangling edges against the
+   * whole batch').
+   */
+  pruneFileNodes(result, prunedNodeIds, batchPrunedIds) {
+    if (prunedNodeIds.length === 0) {
+      result.droppedDanglingEdges = 0;
+      return;
+    }
+    this.db.exec(
+      "CREATE TEMP TABLE IF NOT EXISTS _pruned_ids (id TEXT NOT NULL PRIMARY KEY)"
+    );
+    this.db.exec(
+      "CREATE TEMP TABLE IF NOT EXISTS _batch_pruned_ids (id TEXT NOT NULL PRIMARY KEY)"
+    );
+    const clearPruned = this.db.prepare("DELETE FROM _pruned_ids");
+    const clearBatch = this.db.prepare("DELETE FROM _batch_pruned_ids");
+    const insertPruned = this.db.prepare(
+      "INSERT OR IGNORE INTO _pruned_ids (id) VALUES (?)"
+    );
+    const insertBatch = this.db.prepare(
+      "INSERT OR IGNORE INTO _batch_pruned_ids (id) VALUES (?)"
+    );
+    clearPruned.run();
+    clearBatch.run();
+    const fillTemp = this.db.transaction(
+      (rows) => {
+        for (const { table, ids } of rows) {
+          const stmt = table === "_pruned_ids" ? insertPruned : insertBatch;
+          for (const id of ids) stmt.run(id);
+        }
+      }
+    );
+    fillTemp([
+      { table: "_pruned_ids", ids: prunedNodeIds },
+      { table: "_batch_pruned_ids", ids: batchPrunedIds }
+    ]);
+    const dangling = expectRow(
+      this.db.prepare(
+        `SELECT COUNT(*) AS c FROM edges
+             WHERE dst IN (SELECT id FROM _pruned_ids)
+               AND src NOT IN (SELECT id FROM _batch_pruned_ids)`
+      ).get(),
+      ["c"]
+    );
+    result.droppedDanglingEdges = dangling?.c ?? 0;
+    this.db.exec("DELETE FROM nodes WHERE id IN (SELECT id FROM _pruned_ids)");
+    clearPruned.run();
+    clearBatch.run();
+    const SQLITE_VAR_LIMIT = 32766;
+    const ftsRowids = prunedNodeIds.map(ftsRowidForNodeId);
+    for (let i = 0; i < ftsRowids.length; i += SQLITE_VAR_LIMIT) {
+      const chunk = ftsRowids.slice(i, i + SQLITE_VAR_LIMIT);
+      const ph = chunk.map(() => "?").join(", ");
+      this.db.prepare(`DELETE FROM nodes_fts WHERE rowid IN (${ph})`).run(...chunk);
+      this.db.prepare(`DELETE FROM fts_index WHERE fts_rowid IN (${ph})`).run(...chunk);
+    }
+  }
+  /**
+   * Pass 2: re-insert edges for one file. Runs AFTER every file's
+   * nodes are in place (the full batch is committed to nodes) so
+   * cross-file edges resolve regardless of input order. Stale edges
+   * for nodes owned by this file are deleted first so a changed
+   * `confidence` or `provenance` actually overwrites the prior row
+   * (chatgpt-codex-connector P1: ON CONFLICT DO NOTHING silently
+   * kept stale edges across re-ingests).
+   */
+  upsertFileEdges(ir, result) {
+    if (ir.edges == null) {
+      return;
+    }
+    const qualifiedNameToId = /* @__PURE__ */ new Map();
+    const ownSymbols = expectRows(
+      this.db.prepare("SELECT id, qualified_name FROM nodes WHERE file_id = ?").all(result.fileId),
+      ["id", "qualified_name"]
+    );
+    const qnameCounts = /* @__PURE__ */ new Map();
+    for (const row of ownSymbols) {
+      qnameCounts.set(row.qualified_name, (qnameCounts.get(row.qualified_name) ?? 0) + 1);
+    }
+    for (const row of ownSymbols) {
+      if ((qnameCounts.get(row.qualified_name) ?? 0) === 1) {
+        qualifiedNameToId.set(row.qualified_name, row.id);
+      }
+    }
+    const assertedKeys = /* @__PURE__ */ new Set();
+    const seenKeys = [];
+    const keyToEdge = /* @__PURE__ */ new Map();
+    for (const edge of ir.edges ?? []) {
+      if (!isEdgeProvenance(edge.provenance)) {
+        throw new Error(
+          `graph-store: edge has invalid provenance ${JSON.stringify(edge.provenance)}`
+        );
+      }
+      if (!Number.isFinite(edge.confidence) || edge.confidence < 0 || edge.confidence > 1) {
+        throw new Error(
+          `graph-store: edge confidence ${edge.confidence} is out of range [0, 1] for edge ${edge.srcQualifiedName} \u2192 ${edge.dstQualifiedName}`
+        );
+      }
+      const srcId = qualifiedNameToId.get(edge.srcQualifiedName);
+      if (!srcId) continue;
+      const dstId = resolveNodeId(
+        edge.dstQualifiedName,
+        qualifiedNameToId,
+        this.db
+      );
+      if (!dstId) continue;
+      const key = `${srcId}\0${dstId}\0${edge.type}`;
+      assertedKeys.add(key);
+      seenKeys.push(key);
+      if (!keyToEdge.has(key)) {
+        keyToEdge.set(key, edge);
+      }
+    }
+    const priorEdges = expectRows(
+      this.db.prepare(
+        "SELECT src, dst, type, confidence, provenance FROM edges WHERE src IN (SELECT id FROM nodes WHERE file_id = ?)"
+      ).all(result.fileId),
+      ["src", "dst", "type", "confidence", "provenance"]
+    );
+    const priorByKey = /* @__PURE__ */ new Map();
+    const staleSrcDstTypes = [];
+    for (const p of priorEdges) {
+      const key = `${p.src}\0${p.dst}\0${p.type}`;
+      priorByKey.set(key, { confidence: p.confidence, provenance: p.provenance });
+      if (!assertedKeys.has(key)) {
+        staleSrcDstTypes.push({ src: p.src, dst: p.dst, type: p.type });
+      }
+    }
+    const SQLITE_VARIABLE_LIMIT2 = 32766;
+    const PARAMS_PER_TUPLE = 3;
+    const MAX_TUPLES_PER_CHUNK = Math.floor(SQLITE_VARIABLE_LIMIT2 / PARAMS_PER_TUPLE);
+    for (let i = 0; i < staleSrcDstTypes.length; i += MAX_TUPLES_PER_CHUNK) {
+      const chunk = staleSrcDstTypes.slice(i, i + MAX_TUPLES_PER_CHUNK);
+      const placeholders = chunk.map(() => "(?, ?, ?)").join(", ");
+      this.db.prepare(`DELETE FROM edges WHERE (src, dst, type) IN (${placeholders})`).run(...chunk.flatMap((e) => [e.src, e.dst, e.type]));
+    }
+    const insertEdge = this.db.prepare(
+      `INSERT INTO edges (src, dst, type, confidence, provenance)
+         VALUES (?, ?, ?, ?, ?)
+         ON CONFLICT(src, dst, type) DO UPDATE SET
+           confidence = excluded.confidence,
+           provenance = excluded.provenance`
+    );
+    let edgeCount = 0;
+    const processedKeys = /* @__PURE__ */ new Set();
+    for (const key of seenKeys) {
+      if (processedKeys.has(key)) continue;
+      processedKeys.add(key);
+      const edge = keyToEdge.get(key);
+      if (!edge) continue;
+      const parts = key.split("\0");
+      const srcId = parts[0];
+      const dstId = parts[1];
+      const prior = priorByKey.get(key);
+      if (prior && prior.confidence === edge.confidence && prior.provenance === edge.provenance) {
+        continue;
+      }
+      const r = insertEdge.run(srcId, dstId, edge.type, edge.confidence, edge.provenance);
+      edgeCount += r.changes;
+    }
+    result.edgeCount = edgeCount;
+  }
+  /**
+   * Pass 3 (PR2): upsert `node_attributes` rows for this file's
+   * surviving nodes, derived from the IR's optional `exports` and
+   * `routes` arrays. Per-field preservation semantics (mirrors the
+   * edges pass, generalized to two independent flags):
+   *   - `exports == null` (omitted) → preserve existing `is_exported`
+   *     flags untouched (PR1-era IR has no exports field). The
+   *     `is_route_handler` flag is rebuilt independently from
+   *     `routes` — the two columns do NOT interact.
+   *   - `exports === []` (explicit empty) → wipe the file's
+   *     `is_exported` flags (the caller is asserting "this file
+   *     exports nothing").
+   *   - same rule for `routes` / `is_route_handler`.
+   *
+   * A symbol is `is_exported=1` when its `name` matches an entry in
+   * `ir.exports` (multiple symbols with the same name in one file all
+   * get the flag — the dead-code query treats this conservatively,
+   * never silently picking one). A symbol is `is_route_handler=1`
+   * when its `qualifiedName` equals a route's `handlerQualifiedName`.
+   *
+   * Implementation: per-flag UPDATE, not a delete-then-insert (the
+   * original PR2 implementation wiped both flags whenever either field
+   * was present, so a re-ingest with only `exports` silently dropped
+   * `is_route_handler` — cursor Bugbot + chatgpt-codex-connector P2).
+   * The two flags live in the same row keyed by node_id; INSERT OR
+   * IGNORE ensures a row exists, then UPDATE-per-flag changes only
+   * the column the IR is asserting.
+   */
+  upsertFileAttributes(ir, result) {
+    if (ir.exports == null && ir.routes == null) {
+      return;
+    }
+    const ownNodes = expectRows(
+      this.db.prepare("SELECT id, name, qualified_name FROM nodes WHERE file_id = ?").all(result.fileId),
+      ["id", "name", "qualified_name"]
+    );
+    const ownNodeIds = ownNodes.map((n) => n.id);
+    if (ownNodeIds.length === 0) {
+      return;
+    }
+    const ensureRow = this.db.prepare(
+      `INSERT OR IGNORE INTO node_attributes (node_id, is_exported, is_route_handler)
+         VALUES (?, 0, 0)`
+    );
+    for (const id of ownNodeIds) ensureRow.run(id);
+    if (ir.exports != null) {
+      const exportNames = /* @__PURE__ */ new Set();
+      for (const ex of ir.exports) {
+        if (ex && typeof ex.name === "string" && ex.name.length > 0) {
+          exportNames.add(ex.name);
+        }
+      }
+      const newExportedIds = /* @__PURE__ */ new Set();
+      for (const n of ownNodes) {
+        if (exportNames.has(n.name)) newExportedIds.add(n.id);
+      }
+      this.runChunkedUpdate(
+        `UPDATE node_attributes SET is_exported = 0 WHERE node_id IN (%PH%)`,
+        ownNodeIds
+      );
+      const setExported = this.db.prepare(
+        `UPDATE node_attributes SET is_exported = 1 WHERE node_id = ?`
+      );
+      for (const id of newExportedIds) setExported.run(id);
+    }
+    if (ir.routes != null) {
+      const handlerQNames = /* @__PURE__ */ new Set();
+      for (const r of ir.routes) {
+        if (r && typeof r.handlerQualifiedName === "string" && r.handlerQualifiedName.length > 0) {
+          handlerQNames.add(r.handlerQualifiedName);
+        }
+      }
+      const newRouteIds = /* @__PURE__ */ new Set();
+      for (const n of ownNodes) {
+        if (handlerQNames.has(n.qualified_name)) newRouteIds.add(n.id);
+      }
+      this.runChunkedUpdate(
+        `UPDATE node_attributes SET is_route_handler = 0 WHERE node_id IN (%PH%)`,
+        ownNodeIds
+      );
+      const setRoute = this.db.prepare(
+        `UPDATE node_attributes SET is_route_handler = 1 WHERE node_id = ?`
+      );
+      for (const id of newRouteIds) setRoute.run(id);
+    }
+  }
+  /**
+   * Chunk a parameterized UPDATE-with-IN-list under SQLite's variable
+   * bind limit. The SQL template uses `%PH%` as a placeholder for the
+   * `?,?,…` list. Mirrors the chunking pattern PR1 uses for deletes.
+   */
+  runChunkedUpdate(sqlTemplate, params) {
+    if (params.length === 0) return;
+    for (let i = 0; i < params.length; i += SQLITE_VARIABLE_LIMIT) {
+      const chunk = params.slice(i, i + SQLITE_VARIABLE_LIMIT);
+      const placeholders = chunk.map(() => "?").join(", ");
+      this.db.prepare(sqlTemplate.replace("%PH%", placeholders)).run(...chunk);
+    }
+  }
+  // ──────────────────────────────────────────────────────────────────────
+  // PR2 read primitives (issue #1552 steps 4–5).
+  // ──────────────────────────────────────────────────────────────────────
+  /**
+   * Iterative frontier BFS over the edges table. Cycle-safe via a JS
+   * visited set keyed by node id; depth-capped by {@link TraverseQuery.maxDepth}
+   * (half-open — depth==maxDepth is INCLUDED, maxDepth+1 is NOT — rule 35).
+   * The start node is always included at depth 0 when it exists.
+   *
+   * Reads the edges table via a single prepared statement per
+   * direction; the frontier expands level-by-level so memory is
+   * bounded by the visited set's size, not the recursion depth.
+   */
+  traverse(query) {
+    if (this.closed) return { ok: false, code: "store_closed" };
+    if (query == null || typeof query !== "object") {
+      return { ok: false, code: "invalid_query" };
+    }
+    if (typeof query.maxDepth !== "number" || !Number.isInteger(query.maxDepth) || query.maxDepth < 0) {
+      return {
+        ok: false,
+        code: "invalid_query"
+      };
+    }
+    const direction = query.direction === void 0 ? "outgoing" : query.direction;
+    if (direction !== "outgoing" && direction !== "incoming" && direction !== "both") {
+      return { ok: false, code: "invalid_query" };
+    }
+    if (query.edgeTypes !== void 0 && (!Array.isArray(query.edgeTypes) || !query.edgeTypes.every((e) => typeof e === "string"))) {
+      return { ok: false, code: "invalid_query" };
+    }
+    if (typeof query.start !== "string" || query.start.length === 0) {
+      return { ok: false, code: "invalid_query" };
+    }
+    try {
+      let startId;
+      const isNodeId = /^[0-9a-f]{64}$/.test(query.start);
+      const rows = expectRows(
+        this.db.prepare(
+          isNodeId ? "SELECT id FROM nodes WHERE id = ?" : "SELECT id FROM nodes WHERE qualified_name = ?"
+        ).all(query.start),
+        ["id"]
+      );
+      if (rows.length === 0) {
+        return { ok: false, code: "unknown_start" };
+      }
+      if (rows.length > 1) {
+        return { ok: false, code: "ambiguous_start" };
+      }
+      startId = rows[0].id;
+      const edgeTypes = query.edgeTypes ?? [];
+      const typeClause = edgeTypes.length > 0 ? `AND type IN (${edgeTypes.map(() => "?").join(", ")})` : "";
+      const outgoingStmt = this.db.prepare(
+        `SELECT dst AS neighbor, src AS via_id FROM edges WHERE src = ? ${typeClause}`
+      );
+      const incomingStmt = this.db.prepare(
+        `SELECT src AS neighbor, dst AS via_id FROM edges WHERE dst = ? ${typeClause}`
+      );
+      const visited = /* @__PURE__ */ new Set([startId]);
+      const hits = [];
+      const startRow = expectRow(
+        this.db.prepare(
+          "SELECT n.id, n.qualified_name, n.name, n.label, f.path AS file_path FROM nodes n JOIN files f ON n.file_id = f.id WHERE n.id = ?"
+        ).get(startId),
+        ["id", "qualified_name", "name", "label", "file_path"]
+      );
+      if (!startRow) {
+        return { ok: false, code: "unknown_start" };
+      }
+      hits.push({
+        nodeId: startRow.id,
+        qualifiedName: startRow.qualified_name,
+        name: startRow.name,
+        label: startRow.label,
+        filePath: startRow.file_path,
+        depth: 0
+      });
+      if (query.maxDepth === 0) {
+        return { ok: true, hits };
+      }
+      let frontier = [startId];
+      for (let depth = 1; depth <= query.maxDepth; depth += 1) {
+        const nextFrontier = [];
+        for (const nodeId of frontier) {
+          const params = [nodeId, ...edgeTypes];
+          const outRows = direction === "outgoing" || direction === "both" ? expectRows(
+            outgoingStmt.all(...params),
+            ["neighbor"]
+          ) : [];
+          const inRows = direction === "incoming" || direction === "both" ? expectRows(
+            incomingStmt.all(...params),
+            ["neighbor"]
+          ) : [];
+          for (const r of [...outRows, ...inRows]) {
+            const neighbor = r.neighbor;
+            if (visited.has(neighbor)) continue;
+            visited.add(neighbor);
+            nextFrontier.push(neighbor);
+            const hitRow = expectRow(
+              this.db.prepare(
+                "SELECT n.id, n.qualified_name, n.name, n.label, f.path AS file_path FROM nodes n JOIN files f ON n.file_id = f.id WHERE n.id = ?"
+              ).get(neighbor),
+              ["id", "qualified_name", "name", "label", "file_path"]
+            );
+            if (hitRow) {
+              hits.push({
+                nodeId: hitRow.id,
+                qualifiedName: hitRow.qualified_name,
+                name: hitRow.name,
+                label: hitRow.label,
+                filePath: hitRow.file_path,
+                depth
+              });
+            }
+          }
+        }
+        if (nextFrontier.length === 0) break;
+        frontier = nextFrontier;
+      }
+      return { ok: true, hits };
+    } catch (error) {
+      logWriteFailure(error);
+      return classifyReadError(error);
+    }
+  }
+  /**
+   * Path-enumerating traversal (issue #1650). Unlike {@link traverse}'s BFS —
+   * which visits each node ONCE at its shortest-path depth and so cannot honor
+   * an exact `*N` (N > 1) hop count for nodes reachable at both a shorter and a
+   * length-N path — this primitive enumerates concrete relationship-simple
+   * paths from the start, yielding one hit per distinct (path, endpoint) pair
+   * up to {@link TraversePathsQuery.maxHops}.
+   *
+   * Cycle safety uses RELATIONSHIP UNIQUENESS (the real Cypher rule): a single
+   * path never traverses the same edge twice, keyed by the edge's canonical
+   * `(src, dst, type)` identity. A node MAY recur in a path via distinct edges
+   * (e.g. A->B->A over two different edges) — that is correct Cypher behavior.
+   * The {@link TraversePathsQuery.maxHops} cap bounds each path's length;
+   * {@link TraversePathsQuery.maxPaths} bounds the total enumerated count so a
+   * dense subgraph cannot blow enumeration up exponentially without notice
+   * (when hit, enumeration stops and the result carries `truncated: true`).
+   *
+   * Every yielded path has length >= 1 (at least one edge). A length-0 "path"
+   * (the trivial start->start) is NOT enumerated; callers that need the start
+   * node for a `*0..N` bound add it themselves.
+   */
+  traversePaths(query) {
+    if (this.closed) return { ok: false, code: "store_closed" };
+    if (query == null || typeof query !== "object") {
+      return { ok: false, code: "invalid_query" };
+    }
+    if (typeof query.maxHops !== "number" || !Number.isInteger(query.maxHops) || query.maxHops < 0) {
+      return { ok: false, code: "invalid_query" };
+    }
+    if (query.maxHops > MAX_TRAVERSE_PATHS_HOPS) {
+      return { ok: false, code: "invalid_query" };
+    }
+    const direction = query.direction === void 0 ? "outgoing" : query.direction;
+    if (direction !== "outgoing" && direction !== "incoming" && direction !== "both") {
+      return { ok: false, code: "invalid_query" };
+    }
+    if (query.edgeTypes !== void 0 && (!Array.isArray(query.edgeTypes) || !query.edgeTypes.every((e) => typeof e === "string"))) {
+      return { ok: false, code: "invalid_query" };
+    }
+    if (typeof query.start !== "string" || query.start.length === 0) {
+      return { ok: false, code: "invalid_query" };
+    }
+    const minHops = query.minHops === void 0 ? 1 : query.minHops;
+    if (typeof minHops !== "number" || !Number.isInteger(minHops) || minHops < 1) {
+      return { ok: false, code: "invalid_query" };
+    }
+    let maxPaths;
+    if (query.maxPaths === void 0) {
+      maxPaths = DEFAULT_TRAVERSE_PATHS_MAX;
+    } else if (typeof query.maxPaths !== "number" || !Number.isInteger(query.maxPaths) || query.maxPaths < 0) {
+      return { ok: false, code: "invalid_query" };
+    } else {
+      maxPaths = query.maxPaths;
+    }
+    try {
+      const isNodeId = /^[0-9a-f]{64}$/.test(query.start);
+      const rows = expectRows(
+        this.db.prepare(
+          isNodeId ? "SELECT id FROM nodes WHERE id = ?" : "SELECT id FROM nodes WHERE qualified_name = ?"
+        ).all(query.start),
+        ["id"]
+      );
+      if (rows.length === 0) return { ok: false, code: "unknown_start" };
+      if (rows.length > 1) return { ok: false, code: "ambiguous_start" };
+      const startId = rows[0].id;
+      if (query.maxHops === 0) {
+        return { ok: true, hits: [], truncated: false };
+      }
+      const edgeTypes = query.edgeTypes ?? [];
+      const typeClause = edgeTypes.length > 0 ? `AND type IN (${edgeTypes.map(() => "?").join(", ")})` : "";
+      const outgoingStmt = this.db.prepare(
+        `SELECT dst AS neighbor, src, dst, type FROM edges WHERE src = ? ${typeClause}`
+      );
+      const incomingStmt = this.db.prepare(
+        `SELECT src AS neighbor, src, dst, type FROM edges WHERE dst = ? ${typeClause}`
+      );
+      const nodeStmt = this.db.prepare(
+        "SELECT n.id, n.qualified_name, n.name, n.label, f.path AS file_path FROM nodes n JOIN files f ON n.file_id = f.id WHERE n.id = ?"
+      );
+      const nodeCache = /* @__PURE__ */ new Map();
+      const getNode = (id) => {
+        const cached = nodeCache.get(id);
+        if (cached) return cached;
+        const row = expectRow(nodeStmt.get(id), [
+          "id",
+          "qualified_name",
+          "name",
+          "label",
+          "file_path"
+        ]);
+        if (row) nodeCache.set(id, row);
+        return row;
+      };
+      const neighborsOf = (id) => {
+        const params = [id, ...edgeTypes];
+        const out = direction === "outgoing" || direction === "both" ? expectRows(outgoingStmt.all(...params), [
+          "neighbor",
+          "src",
+          "dst",
+          "type"
+        ]) : [];
+        const inn = direction === "incoming" || direction === "both" ? expectRows(incomingStmt.all(...params), [
+          "neighbor",
+          "src",
+          "dst",
+          "type"
+        ]) : [];
+        const seenEdge = /* @__PURE__ */ new Set();
+        const deduped = [];
+        for (const e of [...out, ...inn]) {
+          const k = e.src + "\0" + e.dst + "\0" + e.type;
+          if (seenEdge.has(k)) continue;
+          seenEdge.add(k);
+          deduped.push(e);
+        }
+        return deduped;
+      };
+      const hits = [];
+      let truncated = false;
+      const usedEdges = /* @__PURE__ */ new Set();
+      const pathNodes = [startId];
+      const pathEdgeTypes = [];
+      const pathEndpoints = [];
+      const dfs = (currentId, length) => {
+        if (truncated) return;
+        if (length >= query.maxHops) return;
+        for (const e of neighborsOf(currentId)) {
+          if (truncated) return;
+          const key = `${e.src}\0${e.dst}\0${e.type}`;
+          if (usedEdges.has(key)) continue;
+          usedEdges.add(key);
+          pathNodes.push(e.neighbor);
+          pathEdgeTypes.push(e.type);
+          pathEndpoints.push({ src: e.src, dst: e.dst });
+          const newLength = length + 1;
+          if (newLength >= minHops) {
+            if (hits.length >= maxPaths) {
+              truncated = true;
+            } else {
+              const info = getNode(e.neighbor);
+              if (info) {
+                hits.push({
+                  nodeId: info.id,
+                  qualifiedName: info.qualified_name,
+                  name: info.name,
+                  label: info.label,
+                  filePath: info.file_path,
+                  length: newLength,
+                  nodeIds: pathNodes.slice(),
+                  edgeTypes: pathEdgeTypes.slice(),
+                  edgeEndpoints: pathEndpoints.slice()
+                });
+              }
+            }
+          }
+          if (!truncated) dfs(e.neighbor, newLength);
+          pathEndpoints.pop();
+          pathEdgeTypes.pop();
+          pathNodes.pop();
+          usedEdges.delete(key);
+        }
+      };
+      dfs(startId, 0);
+      return { ok: true, hits, truncated };
+    } catch (error) {
+      logWriteFailure(error);
+      return classifyReadError(error);
+    }
+  }
+  /**
+   * Structured node search. All filters are AND-combined; patterns use
+   * SQLite LIKE (case-insensitive via COLLATE NOCASE). Patterns and
+   * limits are parameter-bound, never string-interpolated, so user
+   * input cannot inject SQL.
+   */
+  searchGraph(query) {
+    if (this.closed) return { ok: false, code: "store_closed" };
+    if (query == null || typeof query !== "object") {
+      return { ok: false, code: "invalid_query" };
+    }
+    if (query.degreeMin !== void 0 && (typeof query.degreeMin !== "number" || !Number.isInteger(query.degreeMin) || query.degreeMin < 0) || query.degreeMax !== void 0 && (typeof query.degreeMax !== "number" || !Number.isInteger(query.degreeMax) || query.degreeMax < 0)) {
+      return { ok: false, code: "invalid_query" };
+    }
+    if (query.degreeMin !== void 0 && query.degreeMax !== void 0 && query.degreeMin > query.degreeMax) {
+      return { ok: false, code: "invalid_query" };
+    }
+    const rawLimit = query.limit ?? 100;
+    if (typeof rawLimit !== "number" || !Number.isInteger(rawLimit) || rawLimit < 0) {
+      return { ok: false, code: "invalid_query" };
+    }
+    const MAX_SEARCH_LIMIT = 1e3;
+    const limit = Math.min(rawLimit, MAX_SEARCH_LIMIT);
+    if (query.label !== void 0 && typeof query.label !== "string" || query.namePattern !== void 0 && typeof query.namePattern !== "string" || query.filePattern !== void 0 && typeof query.filePattern !== "string") {
+      return { ok: false, code: "invalid_query" };
+    }
+    try {
+      const params = [];
+      const where = [];
+      if (query.label !== void 0 && query.label.length > 0) {
+        where.push("n.label = ?");
+        params.push(query.label);
+      }
+      if (query.namePattern !== void 0 && query.namePattern.length > 0) {
+        where.push("n.name LIKE ? COLLATE NOCASE");
+        params.push(query.namePattern);
+      }
+      if (query.filePattern !== void 0 && query.filePattern.length > 0) {
+        where.push("f.path LIKE ? COLLATE NOCASE");
+        params.push(query.filePattern);
+      }
+      if (query.degreeMin !== void 0) {
+        where.push(
+          "(SELECT COUNT(*) FROM edges e WHERE e.src = n.id OR e.dst = n.id) >= ?"
+        );
+        params.push(query.degreeMin);
+      }
+      if (query.degreeMax !== void 0) {
+        where.push(
+          "(SELECT COUNT(*) FROM edges e WHERE e.src = n.id OR e.dst = n.id) <= ?"
+        );
+        params.push(query.degreeMax);
+      }
+      params.push(limit);
+      const sql = `SELECT n.id AS node_id, n.qualified_name, n.name, n.label,
+                        f.path AS file_path,
+                        (SELECT COUNT(*) FROM edges e WHERE e.src = n.id OR e.dst = n.id) AS degree
+                   FROM nodes n
+                   JOIN files f ON n.file_id = f.id
+                  ${where.length > 0 ? "WHERE " + where.join(" AND ") : ""}
+                  ORDER BY degree DESC, n.qualified_name ASC
+                  LIMIT ?`;
+      const rows = expectRows(this.db.prepare(sql).all(...params), [
+        "node_id",
+        "qualified_name",
+        "name",
+        "label",
+        "file_path",
+        "degree"
+      ]);
+      const hits = rows.map((r) => ({
+        nodeId: r.node_id,
+        qualifiedName: r.qualified_name,
+        name: r.name,
+        label: r.label,
+        filePath: r.file_path,
+        degree: r.degree
+      }));
+      return { ok: true, hits };
+    } catch (error) {
+      logWriteFailure(error);
+      return classifyReadError(error);
+    }
+  }
+  /**
+   * Aggregate counts over the whole graph. Single round-trip: one
+   * scalar per metric, two GROUP BY queries for the by-label /
+   * by-type histograms.
+   */
+  schemaStats() {
+    if (this.closed) return { ok: false, code: "store_closed" };
+    try {
+      const fileCount = expectRow(
+        this.db.prepare("SELECT COUNT(*) AS c FROM files").get(),
+        ["c"]
+      );
+      const nodeCount = expectRow(
+        this.db.prepare("SELECT COUNT(*) AS c FROM nodes").get(),
+        ["c"]
+      );
+      const edgeCount = expectRow(
+        this.db.prepare("SELECT COUNT(*) AS c FROM edges").get(),
+        ["c"]
+      );
+      const labelRows = expectRows(
+        this.db.prepare(
+          "SELECT label, COUNT(*) AS c FROM nodes GROUP BY label ORDER BY label"
+        ).all(),
+        ["label", "c"]
+      );
+      const typeRows = expectRows(
+        this.db.prepare(
+          "SELECT type, COUNT(*) AS c FROM edges GROUP BY type ORDER BY type"
+        ).all(),
+        ["type", "c"]
+      );
+      const nodesByLabel = {};
+      for (const r of labelRows) nodesByLabel[r.label] = r.c;
+      const edgesByType = {};
+      for (const r of typeRows) edgesByType[r.type] = r.c;
+      return {
+        ok: true,
+        stats: {
+          files: fileCount?.c ?? 0,
+          nodes: nodeCount?.c ?? 0,
+          edges: edgeCount?.c ?? 0,
+          nodesByLabel,
+          edgesByType
+        }
+      };
+    } catch (error) {
+      logWriteFailure(error);
+      const failure = classifyReadError(error);
+      return failure;
+    }
+  }
+  /**
+   * Dead-code candidates: nodes with zero inbound
+   * {@link DEAD_CODE_EXCLUSION.INBOUND_USAGE_EDGE_TYPES} edges, excluding
+   * nodes whose `node_attributes` row marks them exported / route-handler
+   * AND nodes whose file path matches the test / entry-point patterns
+   * in {@link DEAD_CODE_EXCLUSION}.
+   *
+   * The exclusion criteria live in the named constant — not in
+   * ad-hoc WHERE clauses (rule 53 analog). The stored flags come from
+   * the write pipeline's `upsertFileAttributes` pass, which the IR's
+   * `exports` and `routes` arrays feed.
+   */
+  deadCode() {
+    if (this.closed) return { ok: false, code: "store_closed" };
+    try {
+      const usageTypes = DEAD_CODE_EXCLUSION.INBOUND_USAGE_EDGE_TYPES;
+      const typePlaceholders = usageTypes.map(() => "?").join(", ");
+      const sql = `SELECT n.id AS node_id, n.qualified_name, n.name, n.label,
+                          f.path AS file_path
+                     FROM nodes n
+                     JOIN files f ON n.file_id = f.id
+                     LEFT JOIN node_attributes a ON a.node_id = n.id
+                    WHERE NOT EXISTS (
+                       SELECT 1 FROM edges e
+                        WHERE e.dst = n.id
+                          AND e.src <> n.id
+                          AND e.type IN (${typePlaceholders})
+                     )
+                      AND COALESCE(a.is_exported, 0) = 0
+                      AND COALESCE(a.is_route_handler, 0) = 0
+                    ORDER BY n.qualified_name ASC`;
+      const rows = expectRows(this.db.prepare(sql).all(...usageTypes), [
+        "node_id",
+        "qualified_name",
+        "name",
+        "label",
+        "file_path"
+      ]);
+      const hits = [];
+      for (const r of rows) {
+        if (isExcludedByPath(r.file_path)) continue;
+        hits.push({
+          nodeId: r.node_id,
+          qualifiedName: r.qualified_name,
+          name: r.name,
+          label: r.label,
+          filePath: r.file_path
+        });
+      }
+      return { ok: true, hits };
+    } catch (error) {
+      logWriteFailure(error);
+      const failure = classifyReadError(error);
+      return failure;
+    }
+  }
+  /**
+   * Read a symbol's source span from disk. The store NEVER persists
+   * file contents (privacy + DB size — issue #1552 design); this
+   * method resolves `files.path` against {@link GraphStoreOptions.repoRoot}
+   * and slices the half-open `[startByte, endByte)` span from the
+   * on-disk bytes.
+   */
+  async snippetFor(query) {
+    if (this.closed) return { ok: false, code: "store_closed" };
+    if (query == null || typeof query !== "object") {
+      return { ok: false, code: "invalid_query" };
+    }
+    const hasNodeId = typeof query.nodeId === "string" && query.nodeId.length > 0;
+    if (!hasNodeId && (typeof query.qualifiedName !== "string" || query.qualifiedName.length === 0)) {
+      return { ok: false, code: "invalid_query" };
+    }
+    if (query.contextLines !== void 0 && (typeof query.contextLines !== "number" || !Number.isInteger(query.contextLines) || query.contextLines < 0)) {
+      return { ok: false, code: "invalid_query" };
+    }
+    const root = typeof query.repoRoot === "string" && query.repoRoot.length > 0 ? query.repoRoot : this.repoRoot;
+    if (root === void 0) {
+      return { ok: false, code: "repo_root_unset" };
+    }
+    let rows;
+    try {
+      rows = expectRows(
+        this.db.prepare(
+          `SELECT n.id, n.qualified_name, n.span_start, n.span_end, n.lang,
+                    f.path AS file_path
+               FROM nodes n JOIN files f ON n.file_id = f.id
+              WHERE ${hasNodeId ? "n.id = ?" : "n.qualified_name = ?"}`
+        ).all(hasNodeId ? query.nodeId : query.qualifiedName),
+        ["id", "qualified_name", "file_path", "span_start", "span_end", "lang"]
+      );
+    } catch (error) {
+      logWriteFailure(error);
+      return classifyReadError(error);
+    }
+    if (rows.length === 0) return { ok: false, code: "not_found" };
+    if (rows.length > 1) return { ok: false, code: "ambiguous_name" };
+    const node = rows[0];
+    const absolutePath = path.resolve(root, node.file_path);
+    let bytes;
+    try {
+      bytes = await readFile(absolutePath);
+    } catch (error) {
+      logWriteFailure(error);
+      return { ok: false, code: "read_failed" };
+    }
+    const start = Math.max(0, node.span_start);
+    const end = Math.min(bytes.length, node.span_end);
+    if (start > end) {
+      return {
+        ok: true,
+        qualifiedName: node.qualified_name,
+        filePath: node.file_path,
+        absolutePath,
+        startByte: node.span_start,
+        endByte: node.span_end,
+        text: "",
+        lang: node.lang
+      };
+    }
+    let text = bytes.subarray(start, end).toString("utf8");
+    const ctx = query.contextLines ?? 0;
+    if (ctx > 0) {
+      const MAX_CTX = 200;
+      const contextLines = Math.min(Math.max(0, Math.floor(ctx)), MAX_CTX);
+      if (contextLines > 0) {
+        let lineStart = start;
+        while (lineStart > 0 && bytes[lineStart - 1] !== 10) {
+          lineStart -= 1;
+        }
+        for (let i = 0; i < contextLines && lineStart > 0; i += 1) {
+          lineStart -= 1;
+          while (lineStart > 0 && bytes[lineStart - 1] !== 10) {
+            lineStart -= 1;
+          }
+        }
+        let lineEnd = end;
+        while (lineEnd < bytes.length && bytes[lineEnd] !== 10) {
+          lineEnd += 1;
+        }
+        if (lineEnd < bytes.length && bytes[lineEnd] === 10) {
+          lineEnd += 1;
+        }
+        for (let i = 0; i < contextLines && lineEnd < bytes.length; i += 1) {
+          while (lineEnd < bytes.length && bytes[lineEnd] !== 10) {
+            lineEnd += 1;
+          }
+          if (lineEnd < bytes.length && bytes[lineEnd] === 10) {
+            lineEnd += 1;
+          }
+        }
+        text = bytes.subarray(lineStart, lineEnd).toString("utf8");
+      }
+    }
+    return {
+      ok: true,
+      qualifiedName: node.qualified_name,
+      filePath: node.file_path,
+      absolutePath,
+      startByte: node.span_start,
+      endByte: node.span_end,
+      text,
+      lang: node.lang
+    };
+  }
+  // ──────────────────────────────────────────────────────────────────────
+  // Semantic layer (issue #1556): symbol_vectors table read/write.
+  // The db is private; these methods are the ONLY surface the semantic
+  // indexer/query path uses. Vectors are float32 BLOBs; content_hash is
+  // the canonical-text hash (rule 37 — the cache invalidation key).
+  // ──────────────────────────────────────────────────────────────────────
+  /**
+   * Upsert one symbol vector. Idempotent on (node_id, model_id). The
+   * caller (the semantic indexer) has ALREADY decided to re-embed (the
+   * content_hash differs from the cached row); this method just persists.
+   */
+  async writeSymbolVector(input) {
+    if (this.closed || this.closing) return false;
+    const buf = Buffer.from(input.vector.buffer, input.vector.byteOffset, input.vector.byteLength);
+    await this.queue.schedule(async () => {
+      this.db.prepare(
+        `INSERT INTO symbol_vectors (node_id, model_id, content_hash, dims, vector)
+             VALUES (?, ?, ?, ?, ?)
+           ON CONFLICT(node_id, model_id) DO UPDATE SET
+             content_hash = excluded.content_hash,
+             dims = excluded.dims,
+             vector = excluded.vector`
+      ).run(input.nodeId, input.modelId, input.contentHash, input.dims, buf);
+    });
+    return true;
+  }
+  /**
+   * Read one vector row by (node_id, model_id). Returns null when absent.
+   * Used by the indexer's cache-check path (skip re-embed when content_hash
+   * matches) and by the cache-hit test.
+   */
+  readSymbolVector(nodeId, modelId) {
+    if (this.closed) return null;
+    const row = expectRow(
+      this.db.prepare(
+        `SELECT content_hash, dims, vector FROM symbol_vectors
+            WHERE node_id = ? AND model_id = ?`
+      ).get(nodeId, modelId),
+      ["content_hash", "dims", "vector"]
+    );
+    if (!row) return null;
+    return {
+      contentHash: row.content_hash,
+      dims: row.dims,
+      vector: new Float32Array(row.vector.buffer, row.vector.byteOffset, row.vector.byteLength / 4)
+    };
+  }
+  /**
+   * Read every vector row for a given model. Used by brute-force cosine
+   * retrieval (SIMILAR_TO confirmation + semantic_query). Returns node
+   * metadata alongside the vector so callers can hydrate hits without a
+   * second round-trip.
+   */
+  readAllSymbolVectors(modelId) {
+    if (this.closed) return [];
+    const rows = expectRows(
+      this.db.prepare(
+        `SELECT sv.node_id, sv.dims, sv.vector, sv.content_hash,
+                  n.qualified_name, n.label, f.path AS file_path
+             FROM symbol_vectors sv
+             JOIN nodes n ON sv.node_id = n.id
+             JOIN files f ON n.file_id = f.id
+            WHERE sv.model_id = ?`
+      ).all(modelId),
+      ["node_id", "qualified_name", "label", "file_path", "dims", "vector", "content_hash"]
+    );
+    return rows.map((r) => ({
+      nodeId: r.node_id,
+      qualifiedName: r.qualified_name,
+      filePath: r.file_path,
+      kind: r.label,
+      dims: r.dims,
+      contentHash: r.content_hash,
+      vector: new Float32Array(r.vector.buffer, r.vector.byteOffset, r.vector.byteLength / 4)
+    }));
+  }
+  /**
+   * Delete vector rows for a set of node ids (all models). Used by the
+   * cache-invalidation path when a symbol's canonical text changed AND
+   * it could not be re-embedded (provider gone) — the stale vector must
+   * not survive to pollute cosine retrieval. Cascades via the schema's
+   * ON DELETE CASCADE on nodes(id) when a node is pruned, so this method
+   * is only for the targeted-invalidation path.
+   */
+  async deleteSymbolVectors(nodeIds) {
+    if (this.closed || this.closing || nodeIds.length === 0) return;
+    await this.queue.schedule(async () => {
+      this.runChunkedDelete(
+        "DELETE FROM symbol_vectors WHERE node_id IN (%PH%)",
+        nodeIds
+      );
+    });
+  }
+  /**
+   * Remove every SIMILAR_TO edge written by the semantic similarity
+   * pipeline (type 'SIMILAR_TO', provenance 'semantic'). The pipeline
+   * recomputes the FULL near-clone edge set on each run, so callers MUST
+   * clear the prior set before upserting the new one — otherwise an edge
+   * between two symbols that stopped being similar survives indefinitely
+   * and graph traversal keeps reporting a stale clone relationship
+   * (chatgpt-codex-connector P2: 'Replace old SIMILAR_TO edges on
+   * recompute'). Scoped to provenance 'semantic' so non-semantic edges
+   * are untouched. Serialized via the write queue so it cannot interleave
+   * a concurrent file-batch edge upsert.
+   */
+  async clearSemanticSimilarToEdges() {
+    if (this.closed || this.closing) return;
+    await this.queue.schedule(async () => {
+      this.db.prepare("DELETE FROM edges WHERE type = ? AND provenance = ?").run("SIMILAR_TO", "semantic");
+    });
+  }
+  /**
+   * Read every node with its file path + span, for the semantic indexer.
+   * The indexer reads source text from disk (via repoRoot) and builds
+   * canonical text per node. Returns kind + qualified_name + span so the
+   * indexer can reconstruct the SymbolIR-equivalent without a second
+   * join. Ordered by qualified_name for deterministic processing order.
+   */
+  readNodesForSemantic() {
+    if (this.closed) return [];
+    const rows = expectRows(
+      this.db.prepare(
+        `SELECT n.id, n.qualified_name, n.label, n.span_start, n.span_end, n.lang,
+                  f.path AS file_path
+             FROM nodes n JOIN files f ON n.file_id = f.id
+            ORDER BY n.qualified_name ASC`
+      ).all(),
+      ["id", "qualified_name", "label", "file_path", "span_start", "span_end", "lang"]
+    );
+    return rows.map((r) => ({
+      nodeId: r.id,
+      qualifiedName: r.qualified_name,
+      kind: r.label,
+      filePath: r.file_path,
+      startByte: r.span_start,
+      endByte: r.span_end,
+      lang: r.lang
+    }));
+  }
+  /**
+   * Read the callers and callees of a node by qualified name, for
+   * semantic_query hydration (the issue: hydrate each hit with graph
+   * context — defining file, direct callers/callees).
+   */
+  readNeighbors(qualifiedName) {
+    if (this.closed) return { callers: [], callees: [] };
+    const nodeRow = expectRow(
+      this.db.prepare("SELECT id FROM nodes WHERE qualified_name = ?").get(qualifiedName),
+      ["id"]
+    );
+    if (!nodeRow) return { callers: [], callees: [] };
+    const id = nodeRow.id;
+    const callerRows = expectRows(
+      this.db.prepare(
+        `SELECT n.qualified_name FROM edges e
+             JOIN nodes n ON e.src = n.id
+            WHERE e.dst = ? AND e.type = 'CALLS'`
+      ).all(id),
+      ["qualified_name"]
+    );
+    const calleeRows = expectRows(
+      this.db.prepare(
+        `SELECT n.qualified_name FROM edges e
+             JOIN nodes n ON e.dst = n.id
+            WHERE e.src = ? AND e.type = 'CALLS'`
+      ).all(id),
+      ["qualified_name"]
+    );
+    return {
+      callers: callerRows.map((r) => r.qualified_name),
+      callees: calleeRows.map((r) => r.qualified_name)
+    };
+  }
+  /**
+   * Read callers/callees by node id directly (avoids the qualified-name
+   * ambiguity when duplicate names exist across files). Used by
+   * semantic_query hydration (chatgpt-codex-connector: 'Use the hit node
+   * id when hydrating neighbors').
+   */
+  readNeighborsByNodeId(nodeId) {
+    if (this.closed) return { callers: [], callees: [] };
+    const callerRows = expectRows(
+      this.db.prepare(
+        `SELECT n.qualified_name FROM edges e
+             JOIN nodes n ON e.src = n.id
+            WHERE e.dst = ? AND e.type = 'CALLS'`
+      ).all(nodeId),
+      ["qualified_name"]
+    );
+    const calleeRows = expectRows(
+      this.db.prepare(
+        `SELECT n.qualified_name FROM edges e
+             JOIN nodes n ON e.dst = n.id
+            WHERE e.src = ? AND e.type = 'CALLS'`
+      ).all(nodeId),
+      ["qualified_name"]
+    );
+    return {
+      callers: callerRows.map((r) => r.qualified_name),
+      callees: calleeRows.map((r) => r.qualified_name)
+    };
+  }
+};
+function nodeIdFor(input) {
+  const fields = [
+    ["qualifiedName", input.qualifiedName],
+    ["filePath", input.filePath],
+    ["label", input.label]
+  ].map(([k, v]) => [k, String(v)]).sort(([a], [b]) => a.localeCompare(b));
+  const hash = createHash("sha256");
+  for (const [k, v] of fields) {
+    hash.update(`${k.length}:${k}:`);
+    hash.update(`${v.length}:${v}:`);
+  }
+  return hash.digest("hex");
+}
+function resolveNodeId(qualifiedName, inBatch, db) {
+  const local = inBatch.get(qualifiedName);
+  if (local) return local;
+  const rows = expectRows(
+    db.prepare(
+      "SELECT id, file_id FROM nodes WHERE qualified_name = ? ORDER BY file_id, id"
+    ).all(qualifiedName),
+    ["id", "file_id"]
+  );
+  if (rows.length === 0) return void 0;
+  if (rows.length > 1) {
+    return void 0;
+  }
+  return rows[0]?.id;
+}
+function resolveByNodeId(stmt, nodeId, qualifiedName) {
+  const row = expectRow(stmt.get(nodeId), ["qualified_name"]);
+  if (!row) return void 0;
+  if (row.qualified_name !== qualifiedName) return void 0;
+  return nodeId;
+}
+function classifyError(error) {
+  const code = hasErrorCode(error) ? error.code : "";
+  if (code === "SQLITE_BUSY" || code === "SQLITE_LOCKED") {
+    return { ok: false, code: "db_locked" };
+  }
+  const msg = error instanceof Error ? error.message : String(error ?? "");
+  if (code === "SQLITE_CORRUPT" || code === "SQLITE_NOTADB" || msg.includes("database disk image is malformed")) {
+    return { ok: false, code: "db_corrupt" };
+  }
+  throw error instanceof Error ? error : new Error(String(error ?? ""));
+}
+function classifyReadError(error) {
+  try {
+    return classifyError(error);
+  } catch {
+    return { ok: false, code: "db_error" };
+  }
+}
+function hasErrorCode(value) {
+  if (typeof value !== "object" || value === null) return false;
+  if (!("code" in value)) return false;
+  const codeValue = value["code"];
+  return typeof codeValue === "string";
+}
+function logWriteFailure(error) {
+  console.error(
+    "[coding-graph] write failure:",
+    error instanceof Error ? error.message : String(error ?? "")
+  );
+}
+function assertCanonicalFilePath(filePath) {
+  if (typeof filePath !== "string" || filePath.length === 0) {
+    throw new Error(
+      `graph-store: file path must be a non-empty string; received ${filePath === null ? "null" : typeof filePath}`
+    );
+  }
+  if (filePath.includes("\\")) {
+    throw new Error(
+      `graph-store: file path '${filePath}' must use forward slashes (backslash rejected \u2014 FileIR contract requires repo-relative POSIX paths)`
+    );
+  }
+  if (filePath.startsWith("/") || /^[A-Za-z]:[\\/]/.test(filePath)) {
+    throw new Error(
+      `graph-store: file path '${filePath}' must be repo-relative (absolute path rejected \u2014 FileIR contract requires repo-relative forward-slash paths)`
+    );
+  }
+  if (filePath.split("/").some((segment) => segment === "." || segment === "..")) {
+    throw new Error(
+      `graph-store: file path '${filePath}' must be canonical (no '.' or '..' segments \u2014 FileIR contract requires repo-relative forward-slash paths)`
+    );
+  }
+}
+function assertValidSymbolSpan(sym, filePath) {
+  if (typeof sym !== "object" || sym === null) {
+    throw new Error(
+      `graph-store: file '${filePath}' has a non-object symbol; received ${sym === null ? "null" : typeof sym}`
+    );
+  }
+  if (!("span" in sym)) {
+    throw new Error(
+      `graph-store: file '${filePath}' has a symbol with no span (FileIR contract requires startByte/endByte)`
+    );
+  }
+  const span = sym.span;
+  if (typeof span !== "object" || span === null || !("startByte" in span) || !("endByte" in span)) {
+    throw new Error(
+      `graph-store: file '${filePath}' has a symbol with a malformed span \u2014 expected { startByte, endByte }; received ${JSON.stringify(span)}`
+    );
+  }
+  const startByte = span.startByte;
+  const endByte = span.endByte;
+  if (typeof startByte !== "number" || typeof endByte !== "number" || !Number.isInteger(startByte) || !Number.isInteger(endByte)) {
+    throw new Error(
+      `graph-store: file '${filePath}' has a symbol with a non-integer span [${JSON.stringify(startByte)}, ${JSON.stringify(endByte)}) \u2014 startByte and endByte must be finite integers`
+    );
+  }
+  if (startByte < 0 || endByte < 0) {
+    throw new Error(
+      `graph-store: file '${filePath}' has a symbol with a negative span [${startByte}, ${endByte}) \u2014 byte offsets must be non-negative`
+    );
+  }
+  if (startByte > endByte) {
+    throw new Error(
+      `graph-store: file '${filePath}' has a symbol with startByte > endByte [${startByte}, ${endByte}) \u2014 half-open spans require startByte <= endByte`
+    );
+  }
+}
+
+export {
+  DEFAULT_TRAVERSE_PATHS_MAX,
+  MAX_TRAVERSE_PATHS_HOPS,
+  DEAD_CODE_EXCLUSION,
+  GraphStore,
+  nodeIdFor
+};
+//# sourceMappingURL=chunk-CPYJACC5.js.map