@descryy/core 0.3.0 → 0.5.0

package/dist/store/index.js

@@ -3,13 +3,8 @@
  */
 import { NodeSqliteDriver } from "./driver/node-sqlite.js";
 import { migrate, verifyReadOnly } from "./migrate.js";
-/**
- * Open (or create) a graph at `path`, or `":memory:"` for a throwaway one.
- *
- * Migration runs on open, so there is no window in which a caller holds a handle
- * to a store whose version has not been checked — DEC-017's "refuse to read"
- * has to happen before the first read, not on the first query.
- */
+/** Opens (or creates) a graph at `path`, or ":memory:" for a throwaway one. Migration runs on
+ *  open — DEC-017's "refuse to read" happens before the first read, never on the first query. */
 export function openStore(path, options = {}) {
     const driver = options.driver ?? new NodeSqliteDriver();
     const openOptions = {
@@ -18,9 +13,8 @@ export function openStore(path, options = {}) {
     };
     driver.open(path, openOptions);
     try {
-        // A read-only handle cannot run migrate — even CREATE TABLE IF NOT EXISTS
-        // needs write permission — so it verifies instead. Same DEC-017 rule, reads
-        // only. This is the path the traversal worker takes.
+        // A read-only handle can't run migrate (even CREATE TABLE IF NOT EXISTS needs write) — it
+        // verifies instead, same DEC-017 rule, reads only. This is the traversal worker's path.
         if (options.readOnly === true) {
             verifyReadOnly(driver);
             return { driver, created: false, close: () => driver.close() };

package/dist/store/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/store/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAE3D,OAAO,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAcvD;;;;;;GAMG;AACH,MAAM,UAAU,SAAS,CAAC,IAAY,EAAE,UAA4B,EAAE;IACpE,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,IAAI,gBAAgB,EAAE,CAAC;IACxD,MAAM,WAAW,GAAgB;QAC/B,GAAG,CAAC,OAAO,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,CAAC;QAC1D,GAAG,CAAC,OAAO,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,EAAE,CAAC;KAC1E,CAAC;IACF,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC;IAC/B,IAAI,CAAC;QACH,0EAA0E;QAC1E,4EAA4E;QAC5E,qDAAqD;QACrD,IAAI,OAAO,CAAC,QAAQ,KAAK,IAAI,EAAE,CAAC;YAC9B,cAAc,CAAC,MAAM,CAAC,CAAC;YACvB,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,KAAK,EAAE,EAAE,CAAC;QACjE,CAAC;QACD,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;QACpC,OAAO;YACL,MAAM;YACN,OAAO;YACP,KAAK,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,KAAK,EAAE;SAC5B,CAAC;IACJ,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,CAAC,KAAK,EAAE,CAAC;QACf,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC;AAED,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AASjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAE3D,OAAO,EAAE,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAC3G,OAAO,EACL,cAAc,EACd,kBAAkB,EAClB,aAAa,EACb,iBAAiB,EACjB,cAAc,EACd,UAAU,GACX,MAAM,aAAa,CAAC;AAGrB,OAAO,EAAE,UAAU,EAAE,iBAAiB,EAAE,QAAQ,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAGhG,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,YAAY,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/store/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAE3D,OAAO,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAcvD;iGACiG;AACjG,MAAM,UAAU,SAAS,CAAC,IAAY,EAAE,UAA4B,EAAE;IACpE,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,IAAI,gBAAgB,EAAE,CAAC;IACxD,MAAM,WAAW,GAAgB;QAC/B,GAAG,CAAC,OAAO,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,CAAC;QAC1D,GAAG,CAAC,OAAO,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,EAAE,CAAC;KAC1E,CAAC;IACF,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC;IAC/B,IAAI,CAAC;QACH,0FAA0F;QAC1F,wFAAwF;QACxF,IAAI,OAAO,CAAC,QAAQ,KAAK,IAAI,EAAE,CAAC;YAC9B,cAAc,CAAC,MAAM,CAAC,CAAC;YACvB,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,KAAK,EAAE,EAAE,CAAC;QACjE,CAAC;QACD,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;QACpC,OAAO;YACL,MAAM;YACN,OAAO;YACP,KAAK,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,KAAK,EAAE;SAC5B,CAAC;IACJ,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,CAAC,KAAK,EAAE,CAAC;QACf,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC;AAED,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AASjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAE3D,OAAO,EAAE,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAC3G,OAAO,EACL,cAAc,EACd,kBAAkB,EAClB,aAAa,EACb,iBAAiB,EACjB,cAAc,EACd,UAAU,GACX,MAAM,aAAa,CAAC;AAGrB,OAAO,EAAE,UAAU,EAAE,iBAAiB,EAAE,QAAQ,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAGhG,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,YAAY,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC"}

package/dist/store/migrate.d.ts

@@ -1,11 +1,6 @@
 /**
- * Schema creation and IR-version enforcement — DEC-017.
- *
- * The rule this file implements: **on IR-version mismatch, refuse to read.**
- * Not "migrate what we can", not "read it and hope". A graph written under a
- * different IR carries node ids from a different identity scheme, and reading it
- * would silently mix two incompatible id spaces — the failure would surface much
- * later as missing edges, with nothing to trace it back to.
+ * Schema creation and IR-version enforcement (DEC-017): on version mismatch, refuse to read — never migrate or read-and-hope. A different IR version means a different
+ * node-id scheme; reading it would silently mix incompatible id spaces, surfacing later as missing edges with nothing to trace back to.
  */
 import { type SqlDriver } from "./driver/driver.ts";
 export declare class SchemaVersionError extends Error {
@@ -14,54 +9,23 @@ export declare class SchemaVersionError extends Error {
     readonly expected: number;
     constructor(found: number, expected: number);
 }
-/**
- * Create the schema if absent, then verify the store is one this build can read.
- *
- * Returns whether the store was newly created, which the caller needs in order
- * to distinguish "empty because it is new" from "empty because a rebuild is
- * pending" — two states that look identical from a row count.
- */
+/** Creates the schema if absent, then verifies the store is readable. `created`
+ *  lets a caller distinguish "empty because new" from "empty, rebuild pending". */
 export declare function migrate(driver: SqlDriver): {
     created: boolean;
 };
-/**
- * Verify a graph without writing to it.
- *
- * The traversal worker opens its own read-only handle (handles are not
- * transferable between threads), and `migrate` cannot run there — even
- * `CREATE TABLE IF NOT EXISTS` needs write permission, so the ordinary path
- * would fail on a perfectly healthy graph. This performs the same DEC-017 check
- * with reads only.
- *
- * Deliberately refuses an empty database rather than creating one: a read-only
- * consumer that silently accepts "no schema" would report an empty answer for a
- * graph that was never built, which is the difference between "nothing matched"
- * and "nothing was analysed".
- */
+/** Verifies a graph without writing to it — `migrate` needs write permission
+ *  (handles aren't transferable to the traversal worker's thread), so this does
+ *  the same DEC-017 check read-only, and refuses an empty database rather than
+ *  creating one ("nothing matched" vs "nothing was analysed"). */
 export declare function verifyReadOnly(driver: SqlDriver): void;
-/**
- * Drop and recreate every derived table, leaving earned data untouched.
- *
- * This is the whole operational content of DEC-017. It is also what makes the
- * decision falsifiable: a test asserts the earned rows are still there
- * afterwards, so the partition cannot quietly stop being real.
- */
+/** Drops and recreates every derived table, leaving earned data untouched — the
+ *  whole operational content of DEC-017; a test asserts earned rows survive. */
 export declare function dropDerived(driver: SqlDriver): void;
-/**
- * MK-4 — the repair `SchemaVersionError`'s own message now names: a caller
- * that is *about to rebuild the graph anyway* (`analyze`, and only `analyze`
- * — every other tool stays a reader and keeps refusing per DEC-017) can call
- * this first instead of hitting the refusal and stopping.
- *
- * Deliberately a separate entry point from `migrate()`, not a flag on it:
- * `migrate()`'s whole contract is "refuse to read a version this build does
- * not expect," and folding a silent repair into the same function would make
- * every caller's version check optionally not a check. This one opens its own
- * short-lived handle, repairs if (and only if) the stored version is a real
- * mismatch — never on a brand-new graph, where `migrate()`'s own create path
- * already does the right thing — and closes again, so the caller always goes
- * on to open its own handle through the normal, checked path.
- */
+/** MK-4: the repair `SchemaVersionError` names. Only `analyze` (about to rebuild
+ *  anyway) calls this instead of hitting the refusal; every other tool keeps
+ *  refusing per DEC-017. Separate from `migrate()` so its version check stays
+ *  a real check, not an optional one; repairs only on a genuine mismatch. */
 export declare function rebuildStaleGraph(driver: SqlDriver): {
     readonly rebuilt: boolean;
 };

package/dist/store/migrate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"migrate.d.ts","sourceRoot":"","sources":["../../src/store/migrate.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAe,KAAK,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAGjE,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,SAAkB,IAAI,wBAAwB;IAC9C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;gBAEd,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM;CAU5C;AAkBD;;;;;;GAMG;AACH,wBAAgB,OAAO,CAAC,MAAM,EAAE,SAAS,GAAG;IAAE,OAAO,EAAE,OAAO,CAAA;CAAE,CA4B/D;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAsBtD;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CASnD;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,SAAS,GAAG;IAAE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAQlF"}
+{"version":3,"file":"migrate.d.ts","sourceRoot":"","sources":["../../src/store/migrate.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAe,KAAK,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAGjE,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,SAAkB,IAAI,wBAAwB;IAC9C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;gBAEd,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM;CAU5C;AAkBD;mFACmF;AACnF,wBAAgB,OAAO,CAAC,MAAM,EAAE,SAAS,GAAG;IAAE,OAAO,EAAE,OAAO,CAAA;CAAE,CA2B/D;AAED;;;kEAGkE;AAClE,wBAAgB,cAAc,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CAsBtD;AAED;gFACgF;AAChF,wBAAgB,WAAW,CAAC,MAAM,EAAE,SAAS,GAAG,IAAI,CASnD;AAED;;;6EAG6E;AAC7E,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,SAAS,GAAG;IAAE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAQlF"}

package/dist/store/migrate.js

@@ -1,11 +1,6 @@
 /**
- * Schema creation and IR-version enforcement — DEC-017.
- *
- * The rule this file implements: **on IR-version mismatch, refuse to read.**
- * Not "migrate what we can", not "read it and hope". A graph written under a
- * different IR carries node ids from a different identity scheme, and reading it
- * would silently mix two incompatible id spaces — the failure would surface much
- * later as missing edges, with nothing to trace it back to.
+ * Schema creation and IR-version enforcement (DEC-017): on version mismatch, refuse to read — never migrate or read-and-hope. A different IR version means a different
+ * node-id scheme; reading it would silently mix incompatible id spaces, surfacing later as missing edges with nothing to trace back to.
  */
 import { DriverError } from "./driver/driver.js";
 import { DERIVED_DROP_ORDER, IR_SCHEMA_VERSION, NODE_ID_SCHEME, SCHEMA_SQL } from "./schema.js";
@@ -31,13 +26,8 @@ function writeMeta(driver, key, value) {
         .prepare("INSERT INTO graph_meta (key, value) VALUES (?, ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value")
         .run(key, value);
 }
-/**
- * Create the schema if absent, then verify the store is one this build can read.
- *
- * Returns whether the store was newly created, which the caller needs in order
- * to distinguish "empty because it is new" from "empty because a rebuild is
- * pending" — two states that look identical from a row count.
- */
+/** Creates the schema if absent, then verifies the store is readable. `created`
+ *  lets a caller distinguish "empty because new" from "empty, rebuild pending". */
 export function migrate(driver) {
     return driver.transaction(() => {
         driver.exec(SCHEMA_SQL);
@@ -55,27 +45,16 @@ export function migrate(driver) {
             throw new SchemaVersionError(found, IR_SCHEMA_VERSION);
         const scheme = readMeta(driver, "node_id_scheme");
         if (scheme !== NODE_ID_SCHEME) {
-            // The `n1:` tag exists for exactly this check — three bytes per id buying
-            // a recognisable mismatch instead of a silent one (DEC-011).
+            // `n1:` tag exists for exactly this check — a recognisable mismatch, not a silent one (DEC-011).
             throw new DriverError(`stored graph uses node id scheme ${String(scheme)}, this build writes ${NODE_ID_SCHEME}`);
         }
         return { created: false };
     });
 }
-/**
- * Verify a graph without writing to it.
- *
- * The traversal worker opens its own read-only handle (handles are not
- * transferable between threads), and `migrate` cannot run there — even
- * `CREATE TABLE IF NOT EXISTS` needs write permission, so the ordinary path
- * would fail on a perfectly healthy graph. This performs the same DEC-017 check
- * with reads only.
- *
- * Deliberately refuses an empty database rather than creating one: a read-only
- * consumer that silently accepts "no schema" would report an empty answer for a
- * graph that was never built, which is the difference between "nothing matched"
- * and "nothing was analysed".
- */
+/** Verifies a graph without writing to it — `migrate` needs write permission
+ *  (handles aren't transferable to the traversal worker's thread), so this does
+ *  the same DEC-017 check read-only, and refuses an empty database rather than
+ *  creating one ("nothing matched" vs "nothing was analysed"). */
 export function verifyReadOnly(driver) {
     const exists = driver
         .prepare("SELECT COUNT(*) AS n FROM sqlite_master WHERE type = 'table' AND name = 'graph_meta'")
@@ -94,13 +73,8 @@ export function verifyReadOnly(driver) {
         throw new DriverError(`stored graph uses node id scheme ${String(scheme)}, this build writes ${NODE_ID_SCHEME}`);
     }
 }
-/**
- * Drop and recreate every derived table, leaving earned data untouched.
- *
- * This is the whole operational content of DEC-017. It is also what makes the
- * decision falsifiable: a test asserts the earned rows are still there
- * afterwards, so the partition cannot quietly stop being real.
- */
+/** Drops and recreates every derived table, leaving earned data untouched — the
+ *  whole operational content of DEC-017; a test asserts earned rows survive. */
 export function dropDerived(driver) {
     driver.transaction(() => {
         for (const table of DERIVED_DROP_ORDER) {
@@ -111,21 +85,10 @@ export function dropDerived(driver) {
         writeMeta(driver, "node_id_scheme", NODE_ID_SCHEME);
     });
 }
-/**
- * MK-4 — the repair `SchemaVersionError`'s own message now names: a caller
- * that is *about to rebuild the graph anyway* (`analyze`, and only `analyze`
- * — every other tool stays a reader and keeps refusing per DEC-017) can call
- * this first instead of hitting the refusal and stopping.
- *
- * Deliberately a separate entry point from `migrate()`, not a flag on it:
- * `migrate()`'s whole contract is "refuse to read a version this build does
- * not expect," and folding a silent repair into the same function would make
- * every caller's version check optionally not a check. This one opens its own
- * short-lived handle, repairs if (and only if) the stored version is a real
- * mismatch — never on a brand-new graph, where `migrate()`'s own create path
- * already does the right thing — and closes again, so the caller always goes
- * on to open its own handle through the normal, checked path.
- */
+/** MK-4: the repair `SchemaVersionError` names. Only `analyze` (about to rebuild
+ *  anyway) calls this instead of hitting the refusal; every other tool keeps
+ *  refusing per DEC-017. Separate from `migrate()` so its version check stays
+ *  a real check, not an optional one; repairs only on a genuine mismatch. */
 export function rebuildStaleGraph(driver) {
     driver.exec(SCHEMA_SQL);
     const storedVersion = readMeta(driver, "ir_schema_version");

package/dist/store/migrate.js.map

@@ -1 +1 @@
-{"version":3,"file":"migrate.js","sourceRoot":"","sources":["../../src/store/migrate.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"migrate.js","sourceRoot":"","sources":["../../src/store/migrate.ts"],"names":[],"mappings":"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"}

package/dist/store/reader.d.ts

@@ -1,82 +1,35 @@
 /**
- * Reads over the stored graph.
- *
- * Deliberately thin. This is not the query layer (plan Step 9) — it is the row
- * access the query layer will be written against, and nothing here knows about
- * scoring, budgets or traversal. Keeping the split means the query layer can be
- * tested against an in-memory adjacency provider with no database at all, which
- * is what stops 95% of the engine's tests needing SQLite and a worker.
- *
- * No row from `driver/` reaches a caller unconverted: SQLite has no booleans, no
- * null-vs-undefined distinction and no nested values, so every read here maps
- * columns back into IR shapes rather than handing out raw rows.
+ * Reads over the stored graph. Deliberately thin — not the query layer (Step 9), just the row access it's written against; the split lets the query layer test against an in-memory provider, no database, no SQLite in 95% of tests.
+ * No row from driver/ reaches a caller unconverted: SQLite has no booleans, no null-vs-undefined, no nested values.
  */
 import { type EdgeType, type IREdge, type IRNode, type NodeType, type UnresolvedRef } from "@descryy/ir";
 import type { SqlDriver } from "./driver/driver.ts";
 export declare function getNode(driver: SqlDriver, id: string): IRNode | undefined;
-/**
- * Every node declared in any of `paths` — the diff-to-seeds step.
- *
- * A diff names files; scoping seeds on nodes. Nothing bridged the two until now,
- * because every measurement so far started from node ids it had just built.
- *
- * **Which files miss is as important as which nodes hit.** A path present in the
- * diff and absent from the graph is not an empty result — it is a file the
- * analysis never read, and reporting its blast radius as "nothing affected"
- * would put an unanalysed file in §20.2's *confirmed clean* category when it
- * belongs in *not analysable*. So the misses come back alongside the hits and
- * the caller cannot take one without the other.
- *
- * Paths are matched exactly. They are repo-relative by the Normaliser's rule, so
- * a caller passing absolute paths gets zero hits and is told so by `missing`
- * rather than by silence.
- */
+/** Every node declared in any of `paths` — the diff-to-seeds step. Misses
+ *  matter as much as hits: an absent path is an unanalysed file (§20.2), not
+ *  an empty result, so both return together. Paths matched exactly (repo-relative); absolute paths get zero hits via `missing`. */
 export declare function nodesInFiles(driver: SqlDriver, paths: readonly string[]): {
     readonly nodes: IRNode[];
     readonly missing: string[];
 };
-/**
- * Every node of one type, capped, with one row of headroom.
- *
- * `limit + 1` is fetched so the caller can tell "exactly the limit" from "the
- * limit and more" without a second `COUNT(*)`. A set-property question answered
- * over a silently truncated set is a fact computed from a sample, so the
- * distinction has to be available.
- */
+/** Every node of one type, capped, with one row of headroom. `limit + 1` is
+ *  fetched so the caller can tell "exactly the limit" from "more", without a
+ *  second COUNT(*) — a truncated set answering a set-property question needs that distinction available. */
 export declare function nodesOfType(driver: SqlDriver, type: NodeType, limit: number): {
     readonly nodes: IRNode[];
     readonly truncated: boolean;
 };
-/**
- * Nodes matching a name and/or a file — the "I know what it's called" lookup.
- *
- * Deliberately returns **every** match rather than a best one. Two functions in
- * a repository can legitimately share a name, and picking one by a heuristic —
- * shortest path, most edges, first row — is how a caller ends up reasoning
- * confidently about the wrong symbol. Ambiguity is the caller's to report, so
- * the reader hands it over intact.
- *
- * `repo` narrows to nodes minted by a run recorded against that repository —
- * a subquery against `adapter_runs`, since `nodes` itself carries no `repo`
- * column (only `run_id`). Added for `descry-runtime`'s graph correlator: a
- * multi-repo session (frontend + backend merged into one store, per DEC-228)
- * makes a same-named symbol in the wrong repository a real candidate for a
- * bare `findNodes({ name })` call, and nothing before this filtered it out.
- * Omitted, this behaves exactly as before — existing callers are unaffected.
- */
+/** Nodes matching a name and/or file — the "I know what it's called" lookup.
+ *  Returns every match, never a best one: picking one by heuristic is how a
+ *  caller reasons confidently about the wrong symbol. `repo` narrows via an adapter_runs subquery (nodes carries no repo column) — added for descry-runtime's multi-repo correlator (DEC-228); omitted, behaves exactly as before. */
 export declare function findNodes(driver: SqlDriver, criteria: {
     readonly name?: string;
     readonly file?: string;
     readonly repo?: string;
     readonly limit?: number;
 }): IRNode[];
-/**
- * Edges leaving a node, optionally filtered by type and capped.
- *
- * The cap is not optional politeness. The prior-art graphs on this machine have
- * a max in-degree of 1,036 (`append`) — materialising every neighbour of a hub
- * node during a traversal is how a 200-node budget turns into a 10,000-row read.
- */
+/** Edges leaving a node, filtered by type and capped. Not optional politeness:
+ *  a real graph's max in-degree of 1,036 turns a 200-node budget into a 10,000-row read without it. */
 export declare function outgoing(driver: SqlDriver, id: string, options?: {
     types?: readonly EdgeType[];
     limit?: number;
@@ -85,18 +38,9 @@ export declare function incoming(driver: SqlDriver, id: string, options?: {
     types?: readonly EdgeType[];
     limit?: number;
 }): IREdge[];
-/**
- * Refusal-ledger rows, for the question-grouping layer (DEC-243) to consume.
- *
- * `classified` (default `true`) restricts to `attrs IS NOT NULL` — rows with
- * no `attrs` at all can never become a question (DEC-242: an unset
- * `refusalClass` is never askable) and are always the majority of this table
- * early in a producer's rollout — sherpa-frontend alone carries ~13,000. That
- * filter is a real optimisation, not an approximation: it changes which rows
- * are *materialised*, never which rows the grouper would have turned into a
- * question. The unclassified count for disclosure is `counts(driver)
- * .unresolvedRefs` minus this function's own row count, not recomputed here.
- */
+/** Refusal-ledger rows for the question-grouping layer (DEC-243). `classified`
+ *  (default true) restricts to `attrs IS NOT NULL` — rows with none can never
+ *  become a question (DEC-242) and dominate early rollout (~13,000 on sherpa-frontend). A real optimisation, not an approximation: it never drops a groupable row. */
 export declare function unresolvedRefs(driver: SqlDriver, options?: {
     readonly classified?: boolean;
     readonly limit?: number;
@@ -111,17 +55,8 @@ export interface StoreCounts {
     readonly runs: number;
 }
 export declare function counts(driver: SqlDriver): StoreCounts;
-/**
- * A hash of the store's logical content, independent of insertion order.
- *
- * This is the instrument for the determinism proof: ingesting the same batches
- * in a permuted order must produce the same hash. Without it, "the graph does
- * not depend on adapter ordering" is an assertion nobody can check, and by the
- * time a real ordering dependency shows up it presents as an unreproducible
- * difference in impact scores.
- *
- * `written_at` is excluded — a wall-clock stamp is not logical content, and
- * including it would make the proof untestable rather than making it stronger.
- */
+/** Hash of the store's logical content, independent of insertion order — the
+ *  determinism proof's instrument (permuted-order ingestion must hash the
+ *  same). `written_at` is excluded: a wall-clock stamp isn't logical content. */
 export declare function contentHash(driver: SqlDriver): string;
 //# sourceMappingURL=reader.d.ts.map

package/dist/store/reader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"reader.d.ts","sourceRoot":"","sources":["../../src/store/reader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,EAIL,KAAK,QAAQ,EACb,KAAK,MAAM,EACX,KAAK,MAAM,EACX,KAAK,QAAQ,EAEb,KAAK,aAAa,EACnB,MAAM,aAAa,CAAC;AAErB,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAuGpD,wBAAgB,OAAO,CAAC,MAAM,EAAE,SAAS,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAGzE;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,SAAS,EACjB,KAAK,EAAE,SAAS,MAAM,EAAE,GACvB;IAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,CAAA;CAAE,CA4B1D;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CACzB,MAAM,EAAE,SAAS,EACjB,IAAI,EAAE,QAAQ,EACd,KAAK,EAAE,MAAM,GACZ;IAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,CAAC;IAAC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAA;CAAE,CAU3D;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,SAAS,CACvB,MAAM,EAAE,SAAS,EACjB,QAAQ,EAAE;IACR,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB,GACA,MAAM,EAAE,CAyBV;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,CACtB,MAAM,EAAE,SAAS,EACjB,EAAE,EAAE,MAAM,EACV,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,SAAS,QAAQ,EAAE,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,GAC5D,MAAM,EAAE,CAEV;AAED,wBAAgB,QAAQ,CACtB,MAAM,EAAE,SAAS,EACjB,EAAE,EAAE,MAAM,EACV,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,SAAS,QAAQ,EAAE,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,GAC5D,MAAM,EAAE,CAEV;AA2BD;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,SAAS,EACjB,OAAO,GAAE;IAAE,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,GACvE;IAAE,QAAQ,CAAC,IAAI,EAAE,aAAa,EAAE,CAAC;IAAC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAA;CAAE,CAYjE;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,wBAAgB,MAAM,CAAC,MAAM,EAAE,SAAS,GAAG,WAAW,CASrD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,SAAS,GAAG,MAAM,CAqBrD"}
+{"version":3,"file":"reader.d.ts","sourceRoot":"","sources":["../../src/store/reader.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAIL,KAAK,QAAQ,EACb,KAAK,MAAM,EACX,KAAK,MAAM,EACX,KAAK,QAAQ,EAEb,KAAK,aAAa,EACnB,MAAM,aAAa,CAAC;AAErB,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAuGpD,wBAAgB,OAAO,CAAC,MAAM,EAAE,SAAS,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAGzE;AAED;;mIAEmI;AACnI,wBAAgB,YAAY,CAC1B,MAAM,EAAE,SAAS,EACjB,KAAK,EAAE,SAAS,MAAM,EAAE,GACvB;IAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,CAAA;CAAE,CA2B1D;AAED;;4GAE4G;AAC5G,wBAAgB,WAAW,CACzB,MAAM,EAAE,SAAS,EACjB,IAAI,EAAE,QAAQ,EACd,KAAK,EAAE,MAAM,GACZ;IAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,CAAC;IAAC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAA;CAAE,CAU3D;AAED;;sOAEsO;AACtO,wBAAgB,SAAS,CACvB,MAAM,EAAE,SAAS,EACjB,QAAQ,EAAE;IACR,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB,GACA,MAAM,EAAE,CAyBV;AAED;uGACuG;AACvG,wBAAgB,QAAQ,CACtB,MAAM,EAAE,SAAS,EACjB,EAAE,EAAE,MAAM,EACV,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,SAAS,QAAQ,EAAE,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,GAC5D,MAAM,EAAE,CAEV;AAED,wBAAgB,QAAQ,CACtB,MAAM,EAAE,SAAS,EACjB,EAAE,EAAE,MAAM,EACV,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,SAAS,QAAQ,EAAE,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,GAC5D,MAAM,EAAE,CAEV;AA0BD;;sKAEsK;AACtK,wBAAgB,cAAc,CAC5B,MAAM,EAAE,SAAS,EACjB,OAAO,GAAE;IAAE,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,GACvE;IAAE,QAAQ,CAAC,IAAI,EAAE,aAAa,EAAE,CAAC;IAAC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAA;CAAE,CAYjE;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,wBAAgB,MAAM,CAAC,MAAM,EAAE,SAAS,GAAG,WAAW,CASrD;AAED;;iFAEiF;AACjF,wBAAgB,WAAW,CAAC,MAAM,EAAE,SAAS,GAAG,MAAM,CAqBrD"}

package/dist/store/reader.js

@@ -1,15 +1,6 @@
 /**
- * Reads over the stored graph.
- *
- * Deliberately thin. This is not the query layer (plan Step 9) — it is the row
- * access the query layer will be written against, and nothing here knows about
- * scoring, budgets or traversal. Keeping the split means the query layer can be
- * tested against an in-memory adjacency provider with no database at all, which
- * is what stops 95% of the engine's tests needing SQLite and a worker.
- *
- * No row from `driver/` reaches a caller unconverted: SQLite has no booleans, no
- * null-vs-undefined distinction and no nested values, so every read here maps
- * columns back into IR shapes rather than handing out raw rows.
+ * Reads over the stored graph. Deliberately thin — not the query layer (Step 9), just the row access it's written against; the split lets the query layer test against an in-memory provider, no database, no SQLite in 95% of tests.
+ * No row from driver/ reaches a caller unconverted: SQLite has no booleans, no null-vs-undefined, no nested values.
  */
 import { createHash } from "node:crypto";
 import { canonicalJson, isEdgeType, isNodeType, } from "@descryy/ir";
@@ -19,8 +10,8 @@ const EDGE_COLUMNS = "id, source, target, type, resolution, confidence, produced
 const UNRESOLVED_REF_COLUMNS = "from_node_id, edge_type, raw_target, file_path, line, produced_by, reason, attrs";
 function toNode(row) {
     if (!isNodeType(row.type)) {
-        // Only reachable if something wrote around the Normaliser, which is exactly
-        // the case worth failing loudly on rather than coercing.
+        // Only reachable if something wrote around the Normaliser — worth
+        // failing loudly on rather than coercing.
         throw new Error(`stored node ${row.id} has an unknown type: ${row.type}`);
     }
     const type = row.type;
@@ -74,32 +65,17 @@ export function getNode(driver, id) {
     const row = driver.prepare(`SELECT ${NODE_COLUMNS} FROM nodes WHERE id = ?`).get(id);
     return row === undefined ? undefined : toNode(row);
 }
-/**
- * Every node declared in any of `paths` — the diff-to-seeds step.
- *
- * A diff names files; scoping seeds on nodes. Nothing bridged the two until now,
- * because every measurement so far started from node ids it had just built.
- *
- * **Which files miss is as important as which nodes hit.** A path present in the
- * diff and absent from the graph is not an empty result — it is a file the
- * analysis never read, and reporting its blast radius as "nothing affected"
- * would put an unanalysed file in §20.2's *confirmed clean* category when it
- * belongs in *not analysable*. So the misses come back alongside the hits and
- * the caller cannot take one without the other.
- *
- * Paths are matched exactly. They are repo-relative by the Normaliser's rule, so
- * a caller passing absolute paths gets zero hits and is told so by `missing`
- * rather than by silence.
- */
+/** Every node declared in any of `paths` — the diff-to-seeds step. Misses
+ *  matter as much as hits: an absent path is an unanalysed file (§20.2), not
+ *  an empty result, so both return together. Paths matched exactly (repo-relative); absolute paths get zero hits via `missing`. */
 export function nodesInFiles(driver, paths) {
     const wanted = [...new Set(paths)].sort();
     if (wanted.length === 0)
         return { nodes: [], missing: [] };
     const nodes = [];
     const seen = new Set();
-    // Chunked because SQLite's default parameter ceiling is 999 and a large PR
-    // legitimately exceeds it. Splitting here rather than asking the caller to
-    // keeps the limit where it belongs — a property of the driver, not of a diff.
+    // Chunked: SQLite's default parameter ceiling is 999, and a large PR
+    // legitimately exceeds it. Kept a driver property, not a caller's concern.
     const CHUNK = 500;
     for (let i = 0; i < wanted.length; i += CHUNK) {
         const chunk = wanted.slice(i, i + CHUNK);
@@ -117,14 +93,9 @@ export function nodesInFiles(driver, paths) {
     const hit = new Set(nodes.map((n) => n.file).filter((f) => f !== null));
     return { nodes, missing: wanted.filter((p) => !hit.has(p)) };
 }
-/**
- * Every node of one type, capped, with one row of headroom.
- *
- * `limit + 1` is fetched so the caller can tell "exactly the limit" from "the
- * limit and more" without a second `COUNT(*)`. A set-property question answered
- * over a silently truncated set is a fact computed from a sample, so the
- * distinction has to be available.
- */
+/** Every node of one type, capped, with one row of headroom. `limit + 1` is
+ *  fetched so the caller can tell "exactly the limit" from "more", without a
+ *  second COUNT(*) — a truncated set answering a set-property question needs that distinction available. */
 export function nodesOfType(driver, type, limit) {
     const rows = driver
         .prepare(`SELECT ${NODE_COLUMNS} FROM nodes WHERE type = ? ORDER BY id ASC LIMIT ${Math.max(1, Math.floor(limit)) + 1}`)
@@ -132,23 +103,9 @@ export function nodesOfType(driver, type, limit) {
     const truncated = rows.length > limit;
     return { nodes: rows.slice(0, limit).map(toNode), truncated };
 }
-/**
- * Nodes matching a name and/or a file — the "I know what it's called" lookup.
- *
- * Deliberately returns **every** match rather than a best one. Two functions in
- * a repository can legitimately share a name, and picking one by a heuristic —
- * shortest path, most edges, first row — is how a caller ends up reasoning
- * confidently about the wrong symbol. Ambiguity is the caller's to report, so
- * the reader hands it over intact.
- *
- * `repo` narrows to nodes minted by a run recorded against that repository —
- * a subquery against `adapter_runs`, since `nodes` itself carries no `repo`
- * column (only `run_id`). Added for `descry-runtime`'s graph correlator: a
- * multi-repo session (frontend + backend merged into one store, per DEC-228)
- * makes a same-named symbol in the wrong repository a real candidate for a
- * bare `findNodes({ name })` call, and nothing before this filtered it out.
- * Omitted, this behaves exactly as before — existing callers are unaffected.
- */
+/** Nodes matching a name and/or file — the "I know what it's called" lookup.
+ *  Returns every match, never a best one: picking one by heuristic is how a
+ *  caller reasons confidently about the wrong symbol. `repo` narrows via an adapter_runs subquery (nodes carries no repo column) — added for descry-runtime's multi-repo correlator (DEC-228); omitted, behaves exactly as before. */
 export function findNodes(driver, criteria) {
     const clauses = [];
     const params = [];
@@ -173,13 +130,8 @@ export function findNodes(driver, criteria) {
         .all(...params)
         .map(toNode);
 }
-/**
- * Edges leaving a node, optionally filtered by type and capped.
- *
- * The cap is not optional politeness. The prior-art graphs on this machine have
- * a max in-degree of 1,036 (`append`) — materialising every neighbour of a hub
- * node during a traversal is how a 200-node budget turns into a 10,000-row read.
- */
+/** Edges leaving a node, filtered by type and capped. Not optional politeness:
+ *  a real graph's max in-degree of 1,036 turns a 200-node budget into a 10,000-row read without it. */
 export function outgoing(driver, id, options = {}) {
     return adjacency(driver, "source", id, options);
 }
@@ -191,9 +143,8 @@ function adjacency(driver, column, id, options) {
     const typeFilter = types === undefined || types.length === 0
         ? ""
         : ` AND type IN (${types.map(() => "?").join(", ")})`;
-    // Ranked before truncation, so a cap keeps the most trustworthy neighbours
-    // rather than whichever rows the index happened to reach first. `id` breaks
-    // ties so the result is stable across runs.
+    // Ranked before truncation, so a cap keeps the most trustworthy neighbours,
+    // not whichever rows the index reached first. `id` breaks ties for stability.
     const sql = `SELECT ${EDGE_COLUMNS} FROM edges WHERE ${column} = ?${typeFilter}` +
         ` ORDER BY resolution DESC, confidence DESC, id ASC` +
         (options.limit === undefined ? "" : ` LIMIT ${Math.max(0, Math.floor(options.limit))}`);
@@ -202,18 +153,9 @@ function adjacency(driver, column, id, options) {
         .all(id, ...(types ?? []))
         .map(toEdge);
 }
-/**
- * Refusal-ledger rows, for the question-grouping layer (DEC-243) to consume.
- *
- * `classified` (default `true`) restricts to `attrs IS NOT NULL` — rows with
- * no `attrs` at all can never become a question (DEC-242: an unset
- * `refusalClass` is never askable) and are always the majority of this table
- * early in a producer's rollout — sherpa-frontend alone carries ~13,000. That
- * filter is a real optimisation, not an approximation: it changes which rows
- * are *materialised*, never which rows the grouper would have turned into a
- * question. The unclassified count for disclosure is `counts(driver)
- * .unresolvedRefs` minus this function's own row count, not recomputed here.
- */
+/** Refusal-ledger rows for the question-grouping layer (DEC-243). `classified`
+ *  (default true) restricts to `attrs IS NOT NULL` — rows with none can never
+ *  become a question (DEC-242) and dominate early rollout (~13,000 on sherpa-frontend). A real optimisation, not an approximation: it never drops a groupable row. */
 export function unresolvedRefs(driver, options = {}) {
     const classified = options.classified ?? true;
     const where = classified ? "WHERE attrs IS NOT NULL" : "";
@@ -234,18 +176,9 @@ export function counts(driver) {
         runs: one("SELECT COUNT(*) AS n FROM adapter_runs"),
     };
 }
-/**
- * A hash of the store's logical content, independent of insertion order.
- *
- * This is the instrument for the determinism proof: ingesting the same batches
- * in a permuted order must produce the same hash. Without it, "the graph does
- * not depend on adapter ordering" is an assertion nobody can check, and by the
- * time a real ordering dependency shows up it presents as an unreproducible
- * difference in impact scores.
- *
- * `written_at` is excluded — a wall-clock stamp is not logical content, and
- * including it would make the proof untestable rather than making it stronger.
- */
+/** Hash of the store's logical content, independent of insertion order — the
+ *  determinism proof's instrument (permuted-order ingestion must hash the
+ *  same). `written_at` is excluded: a wall-clock stamp isn't logical content. */
 export function contentHash(driver) {
     const digest = createHash("sha256");
     for (const table of [...DERIVED_TABLES, ...EARNED_TABLES].sort()) {