@remnic/coding-graph 9.3.759

package/dist/chunk-ZVCMIM4T.js

@@ -0,0 +1,216 @@
+// src/row-types.ts
+function isSqliteRow(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function expectRow(value, columns) {
+  if (!isSqliteRow(value)) return void 0;
+  for (const col of columns) {
+    if (!(col in value)) return void 0;
+  }
+  return value;
+}
+function expectRows(value, columns) {
+  if (!Array.isArray(value)) return [];
+  const out = [];
+  for (const row of value) {
+    const narrowed = expectRow(row, columns);
+    if (narrowed) out.push(narrowed);
+  }
+  return out;
+}
+
+// src/graph-schema.ts
+var CODING_GRAPH_SCHEMA_VERSION = 1;
+function ftsRowidForNodeId(nodeId) {
+  return BigInt(`0x${nodeId.slice(0, 16)}`) & BigInt("0x7fffffffffffffff");
+}
+var EDGE_PROVENANCE_VALUES = [
+  "heuristic",
+  "lsp",
+  "trace",
+  "semantic"
+];
+function isEdgeProvenance(value) {
+  return typeof value === "string" && EDGE_PROVENANCE_VALUES.includes(value);
+}
+function applyCodingGraphSchema(db) {
+  const versionRow = expectRow(
+    db.prepare(
+      "SELECT name FROM sqlite_master WHERE type='table' AND name='meta'"
+    ).get(),
+    ["name"]
+  );
+  if (!versionRow) {
+    createTables(db);
+    writeSchemaVersion(db, CODING_GRAPH_SCHEMA_VERSION);
+    return;
+  }
+  const meta = expectRow(
+    db.prepare("SELECT value FROM meta WHERE key = 'schema_version'").get(),
+    ["value"]
+  );
+  const currentVersion = meta ? parseInt(meta.value, 10) : 0;
+  if (currentVersion > CODING_GRAPH_SCHEMA_VERSION) {
+    return;
+  }
+  createTables(db);
+  writeSchemaVersion(db, CODING_GRAPH_SCHEMA_VERSION);
+}
+function createTables(db) {
+  const provenanceList = EDGE_PROVENANCE_VALUES.map((v) => `'${v}'`).join(", ");
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS meta (
+      key   TEXT PRIMARY KEY,
+      value TEXT NOT NULL
+    );
+
+    CREATE TABLE IF NOT EXISTS files (
+      id           INTEGER PRIMARY KEY AUTOINCREMENT,
+      path         TEXT NOT NULL UNIQUE,
+      lang         TEXT NOT NULL,
+      content_hash TEXT NOT NULL
+    );
+    CREATE INDEX IF NOT EXISTS idx_files_path ON files(path);
+
+    CREATE TABLE IF NOT EXISTS nodes (
+      id             TEXT PRIMARY KEY,
+      label          TEXT NOT NULL,
+      name           TEXT NOT NULL,
+      qualified_name TEXT NOT NULL,
+      file_id        INTEGER NOT NULL REFERENCES files(id) ON DELETE CASCADE,
+      span_start     INTEGER NOT NULL,
+      span_end       INTEGER NOT NULL,
+      lang           TEXT NOT NULL
+    );
+    CREATE INDEX IF NOT EXISTS idx_nodes_file ON nodes(file_id);
+    CREATE INDEX IF NOT EXISTS idx_nodes_qname ON nodes(qualified_name);
+    CREATE INDEX IF NOT EXISTS idx_nodes_label ON nodes(label);
+
+    CREATE TABLE IF NOT EXISTS edges (
+      src        TEXT NOT NULL REFERENCES nodes(id) ON DELETE CASCADE,
+      dst        TEXT NOT NULL REFERENCES nodes(id) ON DELETE CASCADE,
+      type       TEXT NOT NULL,
+      confidence REAL NOT NULL CHECK (confidence >= 0.0 AND confidence <= 1.0),
+      provenance TEXT NOT NULL CHECK (provenance IN (${provenanceList})),
+      UNIQUE (src, dst, type)
+    );
+    -- Destination-leading index. The UNIQUE(src,dst,type) key is
+    -- src-leading, so pruneFileNodes()'s 'WHERE dst IN (...)' count and
+    -- the ON DELETE CASCADE that follows a node delete (SQLite must
+    -- locate child edges by 'dst') would otherwise scan the whole edges
+    -- table. A dst-leading index turns ordinary symbol deletion into an
+    -- index lookup instead of a full scan
+    -- (chatgpt-codex-connector P2: 'Add an index for edge destination
+    -- lookups').
+    CREATE INDEX IF NOT EXISTS idx_edges_dst ON edges(dst);
+  `);
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS node_attributes (
+      node_id           TEXT PRIMARY KEY REFERENCES nodes(id) ON DELETE CASCADE,
+      is_exported       INTEGER NOT NULL CHECK (is_exported IN (0, 1)),
+      is_route_handler  INTEGER NOT NULL CHECK (is_route_handler IN (0, 1))
+    );
+    CREATE INDEX IF NOT EXISTS idx_node_attributes_exported
+      ON node_attributes(is_exported) WHERE is_exported = 1;
+    CREATE INDEX IF NOT EXISTS idx_node_attributes_route
+      ON node_attributes(is_route_handler) WHERE is_route_handler = 1;
+  `);
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS co_changes (
+      file_a     TEXT NOT NULL,
+      file_b     TEXT NOT NULL,
+      support    INTEGER NOT NULL CHECK (support >= 0),
+      confidence REAL NOT NULL CHECK (confidence >= 0.0 AND confidence <= 1.0),
+      UNIQUE (file_a, file_b)
+    );
+    CREATE INDEX IF NOT EXISTS idx_co_changes_a ON co_changes(file_a);
+    CREATE INDEX IF NOT EXISTS idx_co_changes_b ON co_changes(file_b);
+  `);
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS symbol_vectors (
+      node_id      TEXT NOT NULL REFERENCES nodes(id) ON DELETE CASCADE,
+      model_id     TEXT NOT NULL,
+      content_hash TEXT NOT NULL,
+      dims         INTEGER NOT NULL CHECK (dims > 0),
+      vector       BLOB NOT NULL,
+      PRIMARY KEY (node_id, model_id)
+    );
+    CREATE INDEX IF NOT EXISTS idx_symbol_vectors_model
+      ON symbol_vectors(model_id);
+  `);
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS fts_index (
+      fts_rowid INTEGER PRIMARY KEY,
+      node_id   TEXT NOT NULL UNIQUE
+    );
+    CREATE INDEX IF NOT EXISTS idx_fts_index_node ON fts_index(node_id);
+  `);
+  const ftsCreateSql = expectRow(
+    db.prepare(
+      "SELECT sql FROM sqlite_master WHERE type='table' AND name='nodes_fts'"
+    ).get(),
+    ["sql"]
+  );
+  const needsFtsRecreate = !ftsCreateSql || !ftsCreateSql.sql.includes("contentless_delete=1");
+  if (needsFtsRecreate) {
+    db.exec("DROP TABLE IF EXISTS nodes_fts;");
+    db.exec(`
+      CREATE VIRTUAL TABLE nodes_fts USING fts5(
+        name,
+        qualified_name,
+        id UNINDEXED,
+        content='',
+        contentless_delete=1,
+        tokenize='unicode61 remove_diacritics 2'
+      );
+    `);
+    const survivingNodes = expectRows(
+      db.prepare("SELECT id, name, qualified_name FROM nodes").all(),
+      ["id", "name", "qualified_name"]
+    );
+    if (survivingNodes.length > 0) {
+      const insertFts = db.prepare(
+        "INSERT INTO nodes_fts (rowid, name, qualified_name) VALUES (?, ?, ?)"
+      );
+      const upsertFtsIndex = db.prepare(
+        "INSERT OR REPLACE INTO fts_index (fts_rowid, node_id) VALUES (?, ?)"
+      );
+      for (const n of survivingNodes) {
+        const rowid = ftsRowidForNodeId(n.id);
+        insertFts.run(rowid, n.name, n.qualified_name);
+        upsertFtsIndex.run(rowid, n.id);
+      }
+    }
+  }
+}
+function writeSchemaVersion(db, version) {
+  db.prepare(
+    "INSERT OR REPLACE INTO meta (key, value) VALUES ('schema_version', ?)"
+  ).run(String(version));
+}
+function readSchemaVersion(db) {
+  const metaTable = expectRow(
+    db.prepare(
+      "SELECT name FROM sqlite_master WHERE type='table' AND name='meta'"
+    ).get(),
+    ["name"]
+  );
+  if (!metaTable) return 0;
+  const meta = expectRow(
+    db.prepare("SELECT value FROM meta WHERE key = 'schema_version'").get(),
+    ["value"]
+  );
+  return meta ? parseInt(meta.value, 10) : 0;
+}
+
+export {
+  expectRow,
+  expectRows,
+  CODING_GRAPH_SCHEMA_VERSION,
+  ftsRowidForNodeId,
+  EDGE_PROVENANCE_VALUES,
+  isEdgeProvenance,
+  applyCodingGraphSchema,
+  readSchemaVersion
+};
+//# sourceMappingURL=chunk-ZVCMIM4T.js.map

package/dist/chunk-ZVCMIM4T.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/row-types.ts","../src/graph-schema.ts"],"sourcesContent":["/**\n * Typed-row helpers for better-sqlite3 — narrow the library's `unknown`\n * return values with a runtime shape check before reading properties.\n *\n * better-sqlite3 returns `unknown` for `.get()` and `unknown[]` for\n * `.all()`. The codebase has historically relied on inline `as` casts;\n * this module provides a typed wrapper that validates the SHAPE at runtime\n * so a bad query (column renames, dropped columns) fails loudly instead\n * of silently reading `undefined`.\n */\n\nexport type SqliteRow = Record<string, unknown>;\n\nexport function isSqliteRow(value: unknown): value is SqliteRow {\n  return typeof value === \"object\" && value !== null && !Array.isArray(value);\n}\n\n/**\n * Narrow a `.get()` result. Returns `undefined` when the row is missing\n * OR when the expected columns are absent. Callers can then assert the\n * expected shape (the columns are guaranteed to exist after this check).\n */\nexport function expectRow<T extends SqliteRow>(\n  value: unknown,\n  columns: readonly (keyof T)[],\n): T | undefined {\n  if (!isSqliteRow(value)) return undefined;\n  for (const col of columns) {\n    if (!(col in value)) return undefined;\n  }\n  return value as T;\n}\n\nexport function expectRows<T extends SqliteRow>(\n  value: unknown,\n  columns: readonly (keyof T)[],\n): T[] {\n  if (!Array.isArray(value)) return [];\n  const out: T[] = [];\n  for (const row of value) {\n    const narrowed = expectRow<T>(row, columns);\n    if (narrowed) out.push(narrowed);\n  }\n  return out;\n}\n","/**\n * Coding-graph SQLite schema — versioned meta + tables + FTS5 virtual table.\n *\n * Issue #1552 PR1 (Track B, Phase 1). The schema + write pipeline only;\n * traversal, search, dead-code and the openCypher subset land in PR2/PR3.\n *\n * PR2 additive table (`node_attributes`): tracks per-node exclusion flags\n * consumed by `deadCode()` — `is_exported`, `is_route_handler`. Added in\n * PR2 (issue #1552 step 5) as a SEPARATE table rather than ALTER TABLE on\n * `nodes`, so existing v1 databases gain the table via the same\n * `CREATE TABLE IF NOT EXISTS` pass without a schema-version bump or a\n * migration (rule 23 — additive, characterized before moving).\n *\n * Design anchors:\n *   - `packages/remnic-core/src/lcm/schema.ts` (versioning + pragmas) —\n *     copied VERBATIM for the WAL / busy_timeout / synchronous pragmas and\n *     the meta-table version row. Do not invent a new pattern (rule 23/38).\n *   - `packages/remnic-core/src/runtime/better-sqlite.ts` (`openBetterSqlite3`)\n *     — the shared opener; native-binding lifecycle is paid for once there.\n *   - issue://1552 \"Design\" — node ids hash sorted key material; file\n *     contents are NEVER stored (only spans + content hashes); FTS5 covers\n *     node names; provenance CHECK enforces the four-value enum.\n *\n * Schema versioning:\n *   The schema_version row lives in `meta` (a generic key/value table, not\n *   lcm_meta — independent store, separate version namespace). Fresh DB →\n *   schema_version=1. Upgrade stub: meta v0 → v1 (rule 23, characterize\n *   before moving).\n *\n * Dangling-edge policy (PR1 decision):\n *   When `upsertFileBatch` deletes a file's prior nodes + edges, cross-file\n *   edges whose `dst` was a node owned by the deleted file become dangling.\n *   We DROP them. They are counted in `UpsertResult.droppedDanglingEdges`\n *   so callers can surface the loss. Keeping them with a `dst_unresolved`\n *   marker would leak orphans and bias `traverse()` results — drop is the\n *   conservative choice for a write pipeline whose caller knows the\n *   canonical file set on each batch (rule 11, 40).\n */\nimport type { BetterSqlite3Database } from \"@remnic/core/runtime/better-sqlite\";\n\nimport { expectRow, expectRows } from \"./row-types.js\";\n\nexport const CODING_GRAPH_SCHEMA_VERSION = 1;\n\n/**\n * FTS5 rowid derived from a deterministic node id. FTS5 rowids are\n * signed 64-bit integers; we slice the leading 16 hex chars (= 64 bits)\n * of the sha256 id and mask to the int64 positive range so SQLite\n * accepts it. The full 64-bit space is large enough that collisions\n * across distinct node ids are negligible. Contentless FTS5\n * (`content=''`) does NOT store UNINDEXED column values, so the only\n * reliable key into the virtual table is the rowid.\n *\n * Lives in graph-schema (not graph-store) so the schema migration path\n * can rebuild FTS rows from existing `nodes` without importing the\n * store module (which would create a circular dependency — graph-store\n * imports graph-schema).\n */\nexport function ftsRowidForNodeId(nodeId: string): bigint {\n  return BigInt(`0x${nodeId.slice(0, 16)}`) & BigInt(\"0x7fffffffffffffff\");\n}\n\n/**\n * Provenance enum for edges — mirrors #1552's `heuristic|lsp|trace|semantic`\n * whitelist. The CHECK constraint rejects writes outside this set so a\n * buggy resolver can't sneak in unknown values (rule 23).\n */\nexport const EDGE_PROVENANCE_VALUES = [\n  \"heuristic\",\n  \"lsp\",\n  \"trace\",\n  \"semantic\",\n] as const;\n\nexport type EdgeProvenance = (typeof EDGE_PROVENANCE_VALUES)[number];\n\nexport function isEdgeProvenance(value: unknown): value is EdgeProvenance {\n  return (\n    typeof value === \"string\" &&\n    (EDGE_PROVENANCE_VALUES as readonly string[]).includes(value)\n  );\n}\n\n/**\n * Apply (or upgrade) the coding-graph schema on an already-open SQLite\n * handle. Public so test seams and migration tools can bootstrap an\n * in-memory database without going through {@link openCodingGraphDatabase}.\n *\n * Mirrors `applyLcmSchema` in `packages/remnic-core/src/lcm/schema.ts` —\n * distinct function, same shape, separate version namespace.\n */\nexport function applyCodingGraphSchema(db: BetterSqlite3Database): void {\n  const versionRow = expectRow<{ name: string }>(\n    db\n      .prepare(\n        \"SELECT name FROM sqlite_master WHERE type='table' AND name='meta'\",\n      )\n      .get(),\n    [\"name\"],\n  );\n\n  if (!versionRow) {\n    // Fresh DB — create every table and stamp the current version.\n    createTables(db);\n    writeSchemaVersion(db, CODING_GRAPH_SCHEMA_VERSION);\n    return;\n  }\n\n  const meta = expectRow<{ value: string }>(\n    db\n      .prepare(\"SELECT value FROM meta WHERE key = 'schema_version'\")\n      .get(),\n    [\"value\"],\n  );\n  const currentVersion = meta ? parseInt(meta.value, 10) : 0;\n\n  // Only run createTables when the on-disk version is at or below this\n  // code's version. For an AT-OR-BELOW DB (fresh-ish v0/v1) the pass is\n  // additive: every core statement is CREATE TABLE IF NOT EXISTS, so the\n  // PR2 `node_attributes` table appears on existing v1 databases without\n  // a version bump (chatgpt-codex-connector P1: 'Create node_attributes\n  // for existing v1 stores'), and a v0 DB is upgraded.\n  //\n  // A NEWER DB (currentVersion > CODING_GRAPH_SCHEMA_VERSION — older\n  // code opening a future-version DB after a downgrade, or a parallel\n  // install) must be left UNTOUCHED: createTables is NOT purely\n  // additive because its FTS migration drops + recreates `nodes_fts`\n  // when the stored CREATE SQL lacks `contentless_delete=1`. Running\n  // that against a future schema that legitimately changed or removed\n  // that table would mutate the newer schema while preserving its\n  // version marker — silent corruption. Skip createTables AND the\n  // version write for newer DBs (chatgpt-codex-connector P2: 'Skip\n  // destructive DDL for future schema versions').\n  if (currentVersion > CODING_GRAPH_SCHEMA_VERSION) {\n    return;\n  }\n  createTables(db);\n  writeSchemaVersion(db, CODING_GRAPH_SCHEMA_VERSION);\n}\n\nfunction createTables(db: BetterSqlite3Database): void {\n  // Provenance whitelist must match EDGE_PROVENANCE_VALUES. SQLite CHECK\n  // constraints are re-checked against every INSERT/UPDATE; bypassing this\n  // gate would require raw exec, which we never do (rule 51).\n  const provenanceList = EDGE_PROVENANCE_VALUES.map((v) => `'${v}'`).join(\", \");\n\n  db.exec(`\n    CREATE TABLE IF NOT EXISTS meta (\n      key   TEXT PRIMARY KEY,\n      value TEXT NOT NULL\n    );\n\n    CREATE TABLE IF NOT EXISTS files (\n      id           INTEGER PRIMARY KEY AUTOINCREMENT,\n      path         TEXT NOT NULL UNIQUE,\n      lang         TEXT NOT NULL,\n      content_hash TEXT NOT NULL\n    );\n    CREATE INDEX IF NOT EXISTS idx_files_path ON files(path);\n\n    CREATE TABLE IF NOT EXISTS nodes (\n      id             TEXT PRIMARY KEY,\n      label          TEXT NOT NULL,\n      name           TEXT NOT NULL,\n      qualified_name TEXT NOT NULL,\n      file_id        INTEGER NOT NULL REFERENCES files(id) ON DELETE CASCADE,\n      span_start     INTEGER NOT NULL,\n      span_end       INTEGER NOT NULL,\n      lang           TEXT NOT NULL\n    );\n    CREATE INDEX IF NOT EXISTS idx_nodes_file ON nodes(file_id);\n    CREATE INDEX IF NOT EXISTS idx_nodes_qname ON nodes(qualified_name);\n    CREATE INDEX IF NOT EXISTS idx_nodes_label ON nodes(label);\n\n    CREATE TABLE IF NOT EXISTS edges (\n      src        TEXT NOT NULL REFERENCES nodes(id) ON DELETE CASCADE,\n      dst        TEXT NOT NULL REFERENCES nodes(id) ON DELETE CASCADE,\n      type       TEXT NOT NULL,\n      confidence REAL NOT NULL CHECK (confidence >= 0.0 AND confidence <= 1.0),\n      provenance TEXT NOT NULL CHECK (provenance IN (${provenanceList})),\n      UNIQUE (src, dst, type)\n    );\n    -- Destination-leading index. The UNIQUE(src,dst,type) key is\n    -- src-leading, so pruneFileNodes()'s 'WHERE dst IN (...)' count and\n    -- the ON DELETE CASCADE that follows a node delete (SQLite must\n    -- locate child edges by 'dst') would otherwise scan the whole edges\n    -- table. A dst-leading index turns ordinary symbol deletion into an\n    -- index lookup instead of a full scan\n    -- (chatgpt-codex-connector P2: 'Add an index for edge destination\n    -- lookups').\n    CREATE INDEX IF NOT EXISTS idx_edges_dst ON edges(dst);\n  `);\n  // PR2 (issue #1552 step 5): per-node exclusion flags consumed by\n  // `GraphStore.deadCode()`. Kept in a SEPARATE table rather than an\n  // ALTER TABLE on `nodes` so existing v1 databases gain the table via\n  // the same `CREATE TABLE IF NOT EXISTS` pass without a schema-version\n  // bump or a data migration (rule 23 — additive, characterized before\n  // moving). ON DELETE CASCADE on `nodes(id)` keeps the table in lockstep\n  // with node lifetimes; the foreign_keys=ON pragma set in\n  // `GraphStore.open()` enforces it.\n  //\n  // `is_exported`: 1 when the symbol's `name` matches an entry in the\n  //   FileIR's `exports` list (matched per-file at write time). The\n  //   dead-code query treats exported symbols as not-dead even with\n  //   zero inbound CALLS/USES_TYPE edges — they form the package's\n  //   public surface and may be called by external consumers the graph\n  //   cannot see.\n  // `is_route_handler`: 1 when the symbol's `qualified_name` matches a\n  //   route's `handlerQualifiedName` in the FileIR's `routes` list.\n  //   Route handlers are reachable from HTTP requests regardless of\n  //   whether any other node CALLS them inside the indexed codebase.\n  //\n  // Both columns are NOT NULL with CHECK IN (0,1): a missing row means\n  // \"neither flag set\" (the LEFT JOIN in deadCode() COALESCEs to 0).\n  db.exec(`\n    CREATE TABLE IF NOT EXISTS node_attributes (\n      node_id           TEXT PRIMARY KEY REFERENCES nodes(id) ON DELETE CASCADE,\n      is_exported       INTEGER NOT NULL CHECK (is_exported IN (0, 1)),\n      is_route_handler  INTEGER NOT NULL CHECK (is_route_handler IN (0, 1))\n    );\n    CREATE INDEX IF NOT EXISTS idx_node_attributes_exported\n      ON node_attributes(is_exported) WHERE is_exported = 1;\n    CREATE INDEX IF NOT EXISTS idx_node_attributes_route\n      ON node_attributes(is_route_handler) WHERE is_route_handler = 1;\n  `);\n  // PR3 (issue #1553): co-change edges — file-level relationships mined\n  // from git history. Stored separately from the symbol-level `edges`\n  // table because co-change is a file-to-file concern, not symbol-to-\n  // symbol. Additive to v1 (CREATE TABLE IF NOT EXISTS — same pattern\n  // as `node_attributes` in PR2, rule 23).\n  //\n  // UNIQUE(file_a, file_b) ensures idempotent upserts; the mining\n  // pipeline clears + repopulates each run so stale edges from history\n  // changes are pruned automatically.\n  db.exec(`\n    CREATE TABLE IF NOT EXISTS co_changes (\n      file_a     TEXT NOT NULL,\n      file_b     TEXT NOT NULL,\n      support    INTEGER NOT NULL CHECK (support >= 0),\n      confidence REAL NOT NULL CHECK (confidence >= 0.0 AND confidence <= 1.0),\n      UNIQUE (file_a, file_b)\n    );\n    CREATE INDEX IF NOT EXISTS idx_co_changes_a ON co_changes(file_a);\n    CREATE INDEX IF NOT EXISTS idx_co_changes_b ON co_changes(file_b);\n  `);\n  // Semantic layer (issue #1556): symbol embedding vectors. Additive to v1\n  // (CREATE TABLE IF NOT EXISTS — same rule-23 pattern as node_attributes).\n  // One row per (node_id, model_id): a node re-embedded under a different\n  // provider/model gets a distinct row so a provider swap does not\n  // overwrite the prior vectors (the cache invalidation test covers this).\n  // content_hash is the canonical-text hash (rule 37) — a re-index compares\n  // it to decide whether to re-embed. CASCADE on nodes(id) keeps the table\n  // in lockstep with node lifetimes (foreign_keys=ON is set in GraphStore.open).\n  db.exec(`\n    CREATE TABLE IF NOT EXISTS symbol_vectors (\n      node_id      TEXT NOT NULL REFERENCES nodes(id) ON DELETE CASCADE,\n      model_id     TEXT NOT NULL,\n      content_hash TEXT NOT NULL,\n      dims         INTEGER NOT NULL CHECK (dims > 0),\n      vector       BLOB NOT NULL,\n      PRIMARY KEY (node_id, model_id)\n    );\n    CREATE INDEX IF NOT EXISTS idx_symbol_vectors_model\n      ON symbol_vectors(model_id);\n  `);\n  // repopulate both tables in lockstep without ordering concerns.\n  db.exec(`\n    CREATE TABLE IF NOT EXISTS fts_index (\n      fts_rowid INTEGER PRIMARY KEY,\n      node_id   TEXT NOT NULL UNIQUE\n    );\n    CREATE INDEX IF NOT EXISTS idx_fts_index_node ON fts_index(node_id);\n  `);\n  // FTS5 virtual table over node names + qualified_names for PR2's\n  // name search. Contentless-delete mode (`content=''` plus\n  // `contentless_delete=1`, SQLite 3.43+) lets us run standard\n  // `DELETE` and `INSERT OR REPLACE` statements against the virtual\n  // table — the write pipeline's only requirement. The `id UNINDEXED`\n  // column mirrors the deterministic node id for human-readable\n  // inspection; the write pipeline's actual key is the rowid derived\n  // from the node-id hash (see `ftsRowidForNodeId` below).\n  //\n  // Migration: databases created before the contentless-FTS5 fix have\n  // an OLD `nodes_fts` table whose CREATE SQL used `content=nodes`\n  // (external-content) and lacks `contentless_delete=1`. The write\n  // pipeline's `DELETE FROM nodes_fts WHERE rowid = ?` fails on such\n  // a table while the source `nodes` row still exists, throwing and\n  // aborting the whole batch (kilo WARNING: 'Contentless FTS5 assumes\n  // fresh schema — old databases are not migrated'). We detect this\n  // by inspecting sqlite_master for the `contentless_delete=1` token;\n  // if absent, we DROP + RECREATE the virtual table and rebuild its\n  // rows from the surviving `nodes` table so the index is immediately\n  // usable after migration (rule 23: characterize before moving).\n  const ftsCreateSql = expectRow<{ sql: string }>(\n    db\n      .prepare(\n        \"SELECT sql FROM sqlite_master WHERE type='table' AND name='nodes_fts'\",\n      )\n      .get(),\n    [\"sql\"],\n  );\n  const needsFtsRecreate =\n    !ftsCreateSql || !ftsCreateSql.sql.includes(\"contentless_delete=1\");\n  if (needsFtsRecreate) {\n    db.exec(\"DROP TABLE IF EXISTS nodes_fts;\");\n    db.exec(`\n      CREATE VIRTUAL TABLE nodes_fts USING fts5(\n        name,\n        qualified_name,\n        id UNINDEXED,\n        content='',\n        contentless_delete=1,\n        tokenize='unicode61 remove_diacritics 2'\n      );\n    `);\n    // Rebuild FTS + fts_index from surviving nodes so both are populated\n    // after migration. Fresh databases have zero rows so this is a no-op.\n    const survivingNodes = expectRows<{\n      id: string;\n      name: string;\n      qualified_name: string;\n    }>(\n      db.prepare(\"SELECT id, name, qualified_name FROM nodes\").all(),\n      [\"id\", \"name\", \"qualified_name\"],\n    );\n    if (survivingNodes.length > 0) {\n      const insertFts = db.prepare(\n        \"INSERT INTO nodes_fts (rowid, name, qualified_name) VALUES (?, ?, ?)\",\n      );\n      const upsertFtsIndex = db.prepare(\n        \"INSERT OR REPLACE INTO fts_index (fts_rowid, node_id) VALUES (?, ?)\",\n      );\n      for (const n of survivingNodes) {\n        const rowid = ftsRowidForNodeId(n.id);\n        insertFts.run(rowid, n.name, n.qualified_name);\n        upsertFtsIndex.run(rowid, n.id);\n      }\n    }\n  }\n  // NOTE: the schema_version marker is written by the caller\n  // (applyCodingGraphSchema / writeSchemaVersion), NOT here. createTables\n  // only owns additive DDL; the version-write concern (never downgrade a\n  // newer DB) lives at the apply layer where currentVersion is known.\n}\n\n/**\n * Stamp the schema_version meta row. INSERT OR REPLACE so the upgrade\n * path can rewrite the row in place (rule 23 — one canonical form).\n * Callers MUST gate this on `currentVersion <= CODING_GRAPH_SCHEMA_VERSION`\n * to avoid downgrading a newer DB.\n */\nfunction writeSchemaVersion(\n  db: BetterSqlite3Database,\n  version: number,\n): void {\n  db.prepare(\n    \"INSERT OR REPLACE INTO meta (key, value) VALUES ('schema_version', ?)\",\n  ).run(String(version));\n}\n\n/**\n * Read the schema_version row. Returns 0 when the table is missing or the\n * row has not been written yet — used by the upgrade stub test.\n *\n * Mirrors the LCM helper's tolerance: a missing `meta` table is not an\n * error condition here, it just means the schema has never been applied.\n */\nexport function readSchemaVersion(db: BetterSqlite3Database): number {\n  const metaTable = expectRow<{ name: string }>(\n    db\n      .prepare(\n        \"SELECT name FROM sqlite_master WHERE type='table' AND name='meta'\",\n      )\n      .get(),\n    [\"name\"],\n  );\n  if (!metaTable) return 0;\n  const meta = expectRow<{ value: string }>(\n    db.prepare(\"SELECT value FROM meta WHERE key = 'schema_version'\").get(),\n    [\"value\"],\n  );\n  return meta ? parseInt(meta.value, 10) : 0;\n}\n"],"mappings":"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","names":[]}

package/dist/cypher/query-parser.d.ts

@@ -0,0 +1,253 @@
+import { GraphStore } from '../graph-store.js';
+import '../graph-schema.js';
+import '@remnic/core/runtime/better-sqlite';
+import '@remnic/core/coding/coding-graph-types';
+
+/**
+ * openCypher read subset — hand-written recursive-descent parser + executor.
+ *
+ * Issue #1552 PR3. This module is the thin, deletable Cypher layer over the
+ * structured store API (`searchGraph` / `traverse`). It compiles a strict
+ * read-only subset of openCypher to those primitives — there is NO SQL
+ * string assembly from user input anywhere; the structured API already
+ * parameterizes every bind (rule 51).
+ *
+ * ## Supported grammar (strict subset)
+ *
+ * ```
+ * query        := MATCH pattern [WHERE where_clause] RETURN return_list [LIMIT int]
+ * pattern      := node_pattern (rel_pattern node_pattern)*
+ * node_pattern := '(' [var] [':' label] ['{' prop_map '}'] ')'
+ * prop_map     := key ':' literal (',' key ':' literal)*
+ * rel_pattern  := ('<-'? '--' bracket '--' '->'?)
+ *                | ('<-'  bracket '--')          // incoming:  <-[...]-   (also <-[...]--)
+ *                | ('--'  bracket '->')          // outgoing:  -[...]->  (also --[...]->)
+ *                | ('<-'? '--' bracket '--' '->'?)   // canonical form
+ * bracket      := '[' [':' type ('|' ':' type)*] ['*' range] ']'
+ * range        := int ('..' int)? | '..' int
+ * where_clause := comparison ((AND | OR) comparison)*
+ * comparison   := var '.' key op literal
+ * op           := '=' | '<>' | '!=' | '>' | '<' | '>=' | '<='
+ * return_list  := return_item (',' return_item)*
+ * return_item  := var | var '.' key
+ * literal      := string | number | 'true' | 'false' | 'null'
+ * ```
+ *
+ * Direction (resolved from the dashes/arrows around the bracket):
+ *   - `-[...]->`  → outgoing (follow src→dst edges)
+ *   - `<-[...]-`  → incoming (follow dst→src edges)
+ *   - `-[...]-`   → both
+ *
+ * Variable-length hops:
+ *   - `-[:CALLS*1..3]->` → between 1 and 3 CALLS hops (inclusive)
+ *   - `-[:CALLS*2]->`    → exactly 2 hops
+ *   - `-[:CALLS..3]->`   → 1..3 hops (default min = 1)
+ *   - `-[:CALLS*]->`     → REJECTED (unbounded — see rejection table)
+ *
+ * ## Compile target
+ *
+ * Single-node patterns compile to `searchGraph({ label })`. Fixed-length
+ * relationship patterns compile to `traverse({ start, direction, edgeTypes,
+ * maxDepth })`, filtering the returned hits to the relationship's depth
+ * range. VARIABLE-length patterns (`*M..N` / `*N`) compile to the path-
+ * enumerating primitive `traversePaths` (issue #1650) so an exact `*N`
+ * honors concrete length-N paths; endpoints are filtered by PATH LENGTH
+ * and deduped by node id. Property filters in node patterns
+ * (`{name: "foo"}`) and WHERE conditions are applied in JS as post-filters
+ * on the bound nodes.
+ *
+ * Variable-length patterns enumerate concrete relationship-simple paths via
+ * `traversePaths` (issue #1650). Each path is cycle-safe under RELATIONSHIP
+ * UNIQUENESS (a single path never reuses an edge), capped at `maxHops` and a
+ * total-path cap. `*M..N` returns a node when a path of length in `[M, N]`
+ * reaches it; exact `*N` (N > 1) thus includes a node reachable at BOTH a
+ * shorter and a length-N path (the length-N path qualifies). The result is
+ * deduped by node id, so `*1..N` ("reachable within N hops") is unchanged
+ * from the prior BFS behavior — only exact `*N` (N > 1) gains paths the
+ * shortest-depth BFS dropped. If enumeration hits the store's maxPaths cap,
+ * the success result carries `truncated: true` so callers can detect a
+ * partial endpoint set instead of silently dropping reachable nodes.
+ *
+ * ## Read-only by construction
+ *
+ * The parser only recognizes the tokens `MATCH`, `WHERE`, `RETURN`,
+ * `LIMIT`, `AND`, `OR`, `true`, `false`, `null`. Every write/mutation
+ * clause token (`CREATE`, `MERGE`, `SET`, `DELETE`, `DETACH`, `REMOVE`,
+ * `DROP`, `CALL`, `YIELD`, `UNION`, `WITH`, `ORDER`, `BY`, `SKIP`,
+ * `OPTIONAL`, `EXPLAIN`, `PROFILE`, `USE`, `FOREACH`, `LOAD`,
+ * `CONSTRAINT`, `INDEX`) is rejected with a clear error naming the
+ * supported grammar (rule 51). The module has no code path that writes
+ * to the store.
+ *
+ * ## Rejection table (each has a dedicated test)
+ *
+ *   - `CREATE (n:Function)`            → unsupported clause (read-only)
+ *   - `MATCH (n) DELETE n`             → unsupported clause
+ *   - `MATCH (n) SET n.x = 1`          → unsupported clause
+ *   - `MATCH (a)-[:CALLS*]->(b) ...`   → unbounded `*` (must specify range)
+ *   - `MATCH (a:NotALabel) ...`        → unknown label (lists valid options)
+ *   - `MATCH (a) RETURN *`             → `RETURN *` not in subset
+ *   - `MATCH (a)-[:CALLS]->(b) RETURN a, c`  → unbound variable `c`
+ *   - `MATCH (a:Function {name: 123}) ...`   → wrong-type literal matches
+ *                                              nothing (standard Cypher;
+ *                                              NOT a parse error — a numeric
+ *                                              `name` never equals a string)
+ *   - `MATCH (a:Function WHERE ...`     → missing `)` / missing RETURN
+ *   - `MATCH (a:Function)` (no RETURN)  → missing RETURN
+ *
+ * ## Scale caveat
+ *
+ * The subset is aimed at interactive exploration over indexed graphs. The
+ * start-node resolution uses `searchGraph` (capped at 1000 rows by the
+ * store); the inline `name`/`filePath` property filter and a supported
+ * single-conjunction first-variable WHERE equality term are pushed down
+ * to the index BEFORE the cap, so an exact-name lookup is found even when
+ * the matching node sorts after the cap on a large graph. Values
+ * containing LIKE metacharacters (`%`/`_`) and multi-group (OR) WHERE
+ * clauses are NOT pushed down — they fall back to the capped scan, so on
+ * graphs with more than 1000 nodes of the starting label such queries can
+ * still false-negative; use the inline literal form for guaranteed
+ * Relationship expansion uses `traverse` (fixed hops) or `traversePaths`
+ * (variable length, issue #1650); both are cycle-safe and depth/length
+ * capped. See the compile-target note for the path-length semantics of
+ * variable-length `*N`.
+ */
+
+/**
+ * PascalCase Cypher label → the lowercase value stored in `nodes.label`.
+ * Labels whose DB form is not produced by ingest still map to a sensible
+ * storage key so the query is structurally valid (returns empty).
+ */
+declare const CYPHER_LABEL_TO_DB_LABEL: Record<string, string>;
+/** Sorted list of accepted Cypher labels — used in rejection messages. */
+declare const VALID_CYPHER_LABELS: readonly string[];
+/**
+ * A value projected by RETURN. Strings, numbers, booleans, or null. Whole
+ * nodes are returned as {@link CypherNodeValue} so callers can read every
+ * field without re-querying.
+ */
+type CypherScalar = string | number | boolean | null;
+/** A whole-node value (RETURN `var` with no property). */
+interface CypherNodeValue {
+    nodeId: string;
+    qualifiedName: string;
+    name: string;
+    label: string;
+    filePath: string;
+}
+type CypherValue = CypherScalar | CypherNodeValue;
+/** One result row — a map from RETURN-item column name to its value. */
+type CypherRow = Record<string, CypherValue>;
+/** Failure codes. Distinct from the store codes — Cypher has its own. */
+type CypherFailureCode = "parse_error" | "unsupported_clause" | "unknown_label" | "unbound_variable" | "invalid_query" | "store_closed" | "db_locked" | "db_corrupt" | "db_error";
+interface CypherFailure {
+    ok: false;
+    code: CypherFailureCode;
+    /** Human-readable explanation including the supported grammar hint. */
+    message: string;
+    /**
+     * Present only for `unknown_label`: the accepted label list, so callers
+     * can render a completion menu without re-deriving it.
+     */
+    validLabels?: readonly string[];
+}
+interface CypherSuccess {
+    ok: true;
+    /** Column names in RETURN order; each row has these keys. */
+    columns: string[];
+    rows: CypherRow[];
+    /**
+     * Present and `true` ONLY when a variable-length expansion hit the
+     * `traversePaths` maxPaths cap — the rows are a PARTIAL endpoint set and
+     * some reachable nodes may be omitted. Callers that must know the result
+     * is complete should treat `truncated: true` as unreliable. Absent means
+     * the enumeration completed (issue #1650).
+     */
+    truncated?: boolean;
+}
+type CypherResult = CypherSuccess | CypherFailure;
+interface NodePattern {
+    /** Variable name; undefined for an anonymous node `( )`. */
+    varName?: string;
+    /** PascalCase label as written (`Function`, `Class`, ...). */
+    label?: string;
+    /** Inline property filters from `{key: value, ...}`. */
+    properties: Array<{
+        key: string;
+        value: CypherScalar;
+    }>;
+}
+type RelDirection = "outgoing" | "incoming" | "both";
+interface RelPattern {
+    direction: RelDirection;
+    /** Edge types; empty means "any type". */
+    types: string[];
+    /** Inclusive minimum hop count (default 1). */
+    minHops: number;
+    /** Inclusive maximum hop count. Equal to minHops when `*N` form used. */
+    maxHops: number;
+    /** True when a `*` range was parsed (variable-length). Drives the path-enumerating compile target (issue #1650). */
+    isVarLength: boolean;
+}
+interface Comparison {
+    varName: string;
+    key: string;
+    op: "=" | "<>" | "!=" | ">" | "<" | ">=" | "<=";
+    value: CypherScalar;
+}
+type WhereTerm = Comparison;
+interface WhereClause {
+    /** Flat OR-of-AND-of-terms. We support AND+OR; no precedence gymnastics. */
+    orGroups: WhereTerm[][];
+}
+type ReturnItem = {
+    kind: "var";
+    varName: string;
+} | {
+    kind: "prop";
+    varName: string;
+    key: string;
+};
+interface MatchClause {
+    nodes: NodePattern[];
+    rels: RelPattern[];
+}
+interface CypherAst {
+    match: MatchClause;
+    where?: WhereClause;
+    return: ReturnItem[];
+    limit?: number;
+}
+declare class CypherParseError extends Error {
+    readonly code: CypherFailureCode;
+    readonly pos: number;
+    readonly validLabels?: readonly string[];
+    constructor(pos: number, message: string, code?: CypherFailureCode, validLabels?: readonly string[]);
+}
+type CypherParseResult = {
+    ok: true;
+    ast: CypherAst;
+} | CypherFailure;
+/**
+ * Parse a Cypher query string into an AST without executing it. Use this
+ * to validate query shape (e.g. at a tool boundary) before opening a
+ * store. The AST is an opaque internal type; callers should treat it as
+ * a handle to pass to {@link executeAst}.
+ */
+declare function parseCypher(query: string): CypherParseResult;
+/**
+ * Execute a parsed AST against a store. Exposed so callers that already
+ * hold an AST (e.g. a cached plan) can skip re-parsing.
+ */
+declare function executeAst(store: GraphStore, ast: CypherAst): CypherResult;
+/**
+ * Parse and execute a Cypher query against a store. Convenience wrapper
+ * around {@link parseCypher} + {@link executeAst}.
+ *
+ * @example
+ *   const r = executeCypher(store, 'MATCH (f:Function {name: "foo"})-[:CALLS*1..2]->(g) WHERE g.label = "function" RETURN f.name, g.qualifiedName LIMIT 5');
+ *   if (r.ok) for (const row of r.rows) console.log(row);
+ */
+declare function executeCypher(store: GraphStore, query: string): CypherResult;
+
+export { CYPHER_LABEL_TO_DB_LABEL, type CypherAst, type CypherFailure, type CypherFailureCode, type CypherNodeValue, CypherParseError, type CypherParseResult, type CypherResult, type CypherRow, type CypherScalar, type CypherSuccess, type CypherValue, VALID_CYPHER_LABELS, executeAst, executeCypher, parseCypher };

package/dist/cypher/query-parser.js

@@ -0,0 +1,17 @@
+import {
+  CYPHER_LABEL_TO_DB_LABEL,
+  VALID_CYPHER_LABELS,
+  executeAst,
+  executeCypher,
+  parseCypher
+} from "../chunk-5I2DBHOQ.js";
+import "../chunk-CPYJACC5.js";
+import "../chunk-ZVCMIM4T.js";
+export {
+  CYPHER_LABEL_TO_DB_LABEL,
+  VALID_CYPHER_LABELS,
+  executeAst,
+  executeCypher,
+  parseCypher
+};
+//# sourceMappingURL=query-parser.js.map

package/dist/cypher/query-parser.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/graph-schema.d.ts

@@ -0,0 +1,84 @@
+import { BetterSqlite3Database } from '@remnic/core/runtime/better-sqlite';
+
+/**
+ * Coding-graph SQLite schema — versioned meta + tables + FTS5 virtual table.
+ *
+ * Issue #1552 PR1 (Track B, Phase 1). The schema + write pipeline only;
+ * traversal, search, dead-code and the openCypher subset land in PR2/PR3.
+ *
+ * PR2 additive table (`node_attributes`): tracks per-node exclusion flags
+ * consumed by `deadCode()` — `is_exported`, `is_route_handler`. Added in
+ * PR2 (issue #1552 step 5) as a SEPARATE table rather than ALTER TABLE on
+ * `nodes`, so existing v1 databases gain the table via the same
+ * `CREATE TABLE IF NOT EXISTS` pass without a schema-version bump or a
+ * migration (rule 23 — additive, characterized before moving).
+ *
+ * Design anchors:
+ *   - `packages/remnic-core/src/lcm/schema.ts` (versioning + pragmas) —
+ *     copied VERBATIM for the WAL / busy_timeout / synchronous pragmas and
+ *     the meta-table version row. Do not invent a new pattern (rule 23/38).
+ *   - `packages/remnic-core/src/runtime/better-sqlite.ts` (`openBetterSqlite3`)
+ *     — the shared opener; native-binding lifecycle is paid for once there.
+ *   - issue://1552 "Design" — node ids hash sorted key material; file
+ *     contents are NEVER stored (only spans + content hashes); FTS5 covers
+ *     node names; provenance CHECK enforces the four-value enum.
+ *
+ * Schema versioning:
+ *   The schema_version row lives in `meta` (a generic key/value table, not
+ *   lcm_meta — independent store, separate version namespace). Fresh DB →
+ *   schema_version=1. Upgrade stub: meta v0 → v1 (rule 23, characterize
+ *   before moving).
+ *
+ * Dangling-edge policy (PR1 decision):
+ *   When `upsertFileBatch` deletes a file's prior nodes + edges, cross-file
+ *   edges whose `dst` was a node owned by the deleted file become dangling.
+ *   We DROP them. They are counted in `UpsertResult.droppedDanglingEdges`
+ *   so callers can surface the loss. Keeping them with a `dst_unresolved`
+ *   marker would leak orphans and bias `traverse()` results — drop is the
+ *   conservative choice for a write pipeline whose caller knows the
+ *   canonical file set on each batch (rule 11, 40).
+ */
+
+declare const CODING_GRAPH_SCHEMA_VERSION = 1;
+/**
+ * FTS5 rowid derived from a deterministic node id. FTS5 rowids are
+ * signed 64-bit integers; we slice the leading 16 hex chars (= 64 bits)
+ * of the sha256 id and mask to the int64 positive range so SQLite
+ * accepts it. The full 64-bit space is large enough that collisions
+ * across distinct node ids are negligible. Contentless FTS5
+ * (`content=''`) does NOT store UNINDEXED column values, so the only
+ * reliable key into the virtual table is the rowid.
+ *
+ * Lives in graph-schema (not graph-store) so the schema migration path
+ * can rebuild FTS rows from existing `nodes` without importing the
+ * store module (which would create a circular dependency — graph-store
+ * imports graph-schema).
+ */
+declare function ftsRowidForNodeId(nodeId: string): bigint;
+/**
+ * Provenance enum for edges — mirrors #1552's `heuristic|lsp|trace|semantic`
+ * whitelist. The CHECK constraint rejects writes outside this set so a
+ * buggy resolver can't sneak in unknown values (rule 23).
+ */
+declare const EDGE_PROVENANCE_VALUES: readonly ["heuristic", "lsp", "trace", "semantic"];
+type EdgeProvenance = (typeof EDGE_PROVENANCE_VALUES)[number];
+declare function isEdgeProvenance(value: unknown): value is EdgeProvenance;
+/**
+ * Apply (or upgrade) the coding-graph schema on an already-open SQLite
+ * handle. Public so test seams and migration tools can bootstrap an
+ * in-memory database without going through {@link openCodingGraphDatabase}.
+ *
+ * Mirrors `applyLcmSchema` in `packages/remnic-core/src/lcm/schema.ts` —
+ * distinct function, same shape, separate version namespace.
+ */
+declare function applyCodingGraphSchema(db: BetterSqlite3Database): void;
+/**
+ * Read the schema_version row. Returns 0 when the table is missing or the
+ * row has not been written yet — used by the upgrade stub test.
+ *
+ * Mirrors the LCM helper's tolerance: a missing `meta` table is not an
+ * error condition here, it just means the schema has never been applied.
+ */
+declare function readSchemaVersion(db: BetterSqlite3Database): number;
+
+export { CODING_GRAPH_SCHEMA_VERSION, EDGE_PROVENANCE_VALUES, type EdgeProvenance, applyCodingGraphSchema, ftsRowidForNodeId, isEdgeProvenance, readSchemaVersion };

package/dist/graph-schema.js

@@ -0,0 +1,17 @@
+import {
+  CODING_GRAPH_SCHEMA_VERSION,
+  EDGE_PROVENANCE_VALUES,
+  applyCodingGraphSchema,
+  ftsRowidForNodeId,
+  isEdgeProvenance,
+  readSchemaVersion
+} from "./chunk-ZVCMIM4T.js";
+export {
+  CODING_GRAPH_SCHEMA_VERSION,
+  EDGE_PROVENANCE_VALUES,
+  applyCodingGraphSchema,
+  ftsRowidForNodeId,
+  isEdgeProvenance,
+  readSchemaVersion
+};
+//# sourceMappingURL=graph-schema.js.map

package/dist/graph-schema.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}