@descryy/core 0.1.0

package/dist/store/index.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The store: open a graph, write batches into it, read rows back out.
+ */
+import type { OpenOptions, SqlDriver } from "./driver/driver.ts";
+export interface OpenStoreOptions extends OpenOptions {
+    /** Swap the backend. The reason the driver interface exists (DEC-018). */
+    readonly driver?: SqlDriver;
+}
+export interface Store {
+    readonly driver: SqlDriver;
+    /** True when this call created the schema, rather than opening an existing graph. */
+    readonly created: boolean;
+    close(): void;
+}
+/**
+ * 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.
+ */
+export declare function openStore(path: string, options?: OpenStoreOptions): Store;
+export { DriverError } from "./driver/driver.ts";
+export type { DriverVersion, OpenOptions, RunResult, SqlDriver, SqlParam, SqlStatement, } from "./driver/driver.ts";
+export { NodeSqliteDriver } from "./driver/node-sqlite.ts";
+export { migrate, verifyReadOnly, dropDerived, rebuildStaleGraph, SchemaVersionError } from "./migrate.ts";
+export { DERIVED_TABLES, DERIVED_DROP_ORDER, EARNED_TABLES, IR_SCHEMA_VERSION, NODE_ID_SCHEME, SCHEMA_SQL, } from "./schema.ts";
+export type { DerivedTable, EarnedTable } from "./schema.ts";
+export { writeBatch, invalidateAdapter, runIdFor, putFileHash, getFileHash } from "./writer.ts";
+export type { WriteResult, WriteOptions } from "./writer.ts";
+export { getNode, findNodes, nodesOfType, nodesInFiles, outgoing, incoming, counts, contentHash } from "./reader.ts";
+export type { StoreCounts } from "./reader.ts";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/store/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAGjE,MAAM,WAAW,gBAAiB,SAAQ,WAAW;IACnD,0EAA0E;IAC1E,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,CAAC;CAC7B;AAED,MAAM,WAAW,KAAK;IACpB,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC;IAC3B,qFAAqF;IACrF,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,KAAK,IAAI,IAAI,CAAC;CACf;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,GAAE,gBAAqB,GAAG,KAAK,CAyB7E;AAED,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,YAAY,EACV,aAAa,EACb,WAAW,EACX,SAAS,EACT,SAAS,EACT,QAAQ,EACR,YAAY,GACb,MAAM,oBAAoB,CAAC;AAC5B,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;AACrB,YAAY,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE7D,OAAO,EAAE,UAAU,EAAE,iBAAiB,EAAE,QAAQ,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAChG,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE7D,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,YAAY,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AACrH,YAAY,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC"}

package/dist/store/index.js

@@ -0,0 +1,46 @@
+/**
+ * The store: open a graph, write batches into it, read rows back out.
+ */
+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.
+ */
+export function openStore(path, options = {}) {
+    const driver = options.driver ?? new NodeSqliteDriver();
+    const openOptions = {
+        ...(options.wal === undefined ? {} : { wal: options.wal }),
+        ...(options.readOnly === undefined ? {} : { readOnly: options.readOnly }),
+    };
+    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.
+        if (options.readOnly === true) {
+            verifyReadOnly(driver);
+            return { driver, created: false, close: () => driver.close() };
+        }
+        const { created } = migrate(driver);
+        return {
+            driver,
+            created,
+            close: () => driver.close(),
+        };
+    }
+    catch (error) {
+        driver.close();
+        throw error;
+    }
+}
+export { DriverError } from "./driver/driver.js";
+export { NodeSqliteDriver } from "./driver/node-sqlite.js";
+export { migrate, verifyReadOnly, dropDerived, rebuildStaleGraph, SchemaVersionError } from "./migrate.js";
+export { DERIVED_TABLES, DERIVED_DROP_ORDER, EARNED_TABLES, IR_SCHEMA_VERSION, NODE_ID_SCHEME, SCHEMA_SQL, } from "./schema.js";
+export { writeBatch, invalidateAdapter, runIdFor, putFileHash, getFileHash } from "./writer.js";
+export { getNode, findNodes, nodesOfType, nodesInFiles, outgoing, incoming, counts, contentHash } from "./reader.js";
+//# sourceMappingURL=index.js.map

package/dist/store/index.js.map

@@ -0,0 +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"}

package/dist/store/migrate.d.ts

@@ -0,0 +1,68 @@
+/**
+ * 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.
+ */
+import { type SqlDriver } from "./driver/driver.ts";
+export declare class SchemaVersionError extends Error {
+    readonly name = "SchemaVersionError";
+    readonly found: number;
+    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.
+ */
+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".
+ */
+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.
+ */
+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.
+ */
+export declare function rebuildStaleGraph(driver: SqlDriver): {
+    readonly rebuilt: boolean;
+};
+//# sourceMappingURL=migrate.d.ts.map

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

@@ -0,0 +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"}

package/dist/store/migrate.js

@@ -0,0 +1,140 @@
+/**
+ * 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.
+ */
+import { DriverError } from "./driver/driver.js";
+import { DERIVED_DROP_ORDER, IR_SCHEMA_VERSION, NODE_ID_SCHEME, SCHEMA_SQL } from "./schema.js";
+export class SchemaVersionError extends Error {
+    name = "SchemaVersionError";
+    found;
+    expected;
+    constructor(found, expected) {
+        super(`stored graph was written under IR schema version ${found}, this build expects ${expected}. ` +
+            `The graph is derived data (DEC-017): drop the derived tables and rebuild — call "analyze" ` +
+            `to do this; it detects exactly this condition and repairs it before reading anything else. ` +
+            `Earned data — R4 observations, edge corrections, incident links — survives.`);
+        this.found = found;
+        this.expected = expected;
+    }
+}
+function readMeta(driver, key) {
+    const row = driver.prepare("SELECT key, value FROM graph_meta WHERE key = ?").get(key);
+    return row?.value;
+}
+function writeMeta(driver, key, value) {
+    driver
+        .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.
+ */
+export function migrate(driver) {
+    return driver.transaction(() => {
+        driver.exec(SCHEMA_SQL);
+        const storedVersion = readMeta(driver, "ir_schema_version");
+        if (storedVersion === undefined) {
+            writeMeta(driver, "ir_schema_version", String(IR_SCHEMA_VERSION));
+            writeMeta(driver, "node_id_scheme", NODE_ID_SCHEME);
+            return { created: true };
+        }
+        const found = Number(storedVersion);
+        if (!Number.isInteger(found)) {
+            throw new DriverError(`graph_meta.ir_schema_version is not an integer: ${storedVersion}`);
+        }
+        if (found !== IR_SCHEMA_VERSION)
+            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).
+            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".
+ */
+export function verifyReadOnly(driver) {
+    const exists = driver
+        .prepare("SELECT COUNT(*) AS n FROM sqlite_master WHERE type = 'table' AND name = 'graph_meta'")
+        .get();
+    if ((exists?.n ?? 0) === 0) {
+        throw new DriverError("no graph at this path — build one before opening it read-only");
+    }
+    const found = Number(readMeta(driver, "ir_schema_version"));
+    if (!Number.isInteger(found)) {
+        throw new DriverError("graph_meta.ir_schema_version is missing or not an integer");
+    }
+    if (found !== IR_SCHEMA_VERSION)
+        throw new SchemaVersionError(found, IR_SCHEMA_VERSION);
+    const scheme = readMeta(driver, "node_id_scheme");
+    if (scheme !== NODE_ID_SCHEME) {
+        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.
+ */
+export function dropDerived(driver) {
+    driver.transaction(() => {
+        for (const table of DERIVED_DROP_ORDER) {
+            driver.exec(`DROP TABLE IF EXISTS ${table}`);
+        }
+        driver.exec(SCHEMA_SQL);
+        writeMeta(driver, "ir_schema_version", String(IR_SCHEMA_VERSION));
+        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.
+ */
+export function rebuildStaleGraph(driver) {
+    driver.exec(SCHEMA_SQL);
+    const storedVersion = readMeta(driver, "ir_schema_version");
+    if (storedVersion === undefined)
+        return { rebuilt: false };
+    const found = Number(storedVersion);
+    if (!Number.isInteger(found) || found === IR_SCHEMA_VERSION)
+        return { rebuilt: false };
+    dropDerived(driver);
+    return { rebuilt: true };
+}
+//# sourceMappingURL=migrate.js.map

package/dist/store/migrate.js.map

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

package/dist/store/reader.d.ts

@@ -0,0 +1,127 @@
+/**
+ * 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.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+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.
+ */
+export declare function outgoing(driver: SqlDriver, id: string, options?: {
+    types?: readonly EdgeType[];
+    limit?: number;
+}): IREdge[];
+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.
+ */
+export declare function unresolvedRefs(driver: SqlDriver, options?: {
+    readonly classified?: boolean;
+    readonly limit?: number;
+}): {
+    readonly refs: UnresolvedRef[];
+    readonly truncated: boolean;
+};
+export interface StoreCounts {
+    readonly nodes: number;
+    readonly edges: number;
+    readonly unresolvedRefs: number;
+    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.
+ */
+export declare function contentHash(driver: SqlDriver): string;
+//# sourceMappingURL=reader.d.ts.map

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

@@ -0,0 +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"}