@descryy/core 0.1.0

package/dist/query/confirmed-facts.js

@@ -0,0 +1,64 @@
+/**
+ * DEC-223's answer half, matching side: which refusal-ledger rows does a
+ * confirmed fact actually answer?
+ *
+ * Deliberately does **not** mint a graph edge. Turning an answered row into a
+ * real `USES_API`/etc. edge needs a target to join against — an endpoint, a
+ * route — which this function has no way to resolve and which DEC-223 §6
+ * named as future work, not this row. What this function owns is narrower
+ * and load-bearing on its own: **which rows are answered, by what value, and
+ * that the match never crosses a repo or accessor boundary it should not.**
+ * A caller minting an edge from `answered` is the one obligated to pass
+ * `reliabilityCap`'s `humanAsserted: true` — this function does not compute a
+ * reliability class itself, because it has no resolution level to reason
+ * from (`UnresolvedRef` carries none — refusals are not edges and were never
+ * scored). Inventing one here would be exactly the overclaim principle 2
+ * exists to prevent.
+ */
+/**
+ * Match ledger rows against confirmed facts, scoped to one repository.
+ *
+ * Three things keep a row out of `answered`, all deliberate:
+ *
+ * 1. **No `attrs.refusalClass === "value-unknown"`.** Everything else —
+ *    unclassified, `capability-gap`, `out-of-scope`, `varies-per-call` — is
+ *    not askable at all (DEC-242), so no fact could ever answer it; matching
+ *    on `blockedBy` alone without this check would let a stored fact silently
+ *    resolve a `varies-per-call` row that structurally has no single answer.
+ * 2. **No `attrs.blockedBy`, or it is not a string.** Nothing to key against.
+ * 3. **No fact in `facts` shares this repo's exact `(repo, blockedBy)` pair.**
+ *    `facts` entries for a different `repo` are never consulted, even when the
+ *    blockedBy text is identical — rule 3's "never an inference about a
+ *    second case," enforced structurally rather than left to caller discipline.
+ */
+export function applyConfirmedFacts(refs, facts, repo) {
+    const byBlockedBy = new Map();
+    for (const fact of facts) {
+        if (fact.repo !== repo)
+            continue;
+        const existing = byBlockedBy.get(fact.blockedBy);
+        if (existing === undefined)
+            byBlockedBy.set(fact.blockedBy, [fact]);
+        else
+            existing.push(fact);
+    }
+    const answered = [];
+    const stillOpen = [];
+    for (const ref of refs) {
+        const refusalClass = ref.attrs?.["refusalClass"];
+        const blockedBy = ref.attrs?.["blockedBy"];
+        if (refusalClass !== "value-unknown" || typeof blockedBy !== "string" || blockedBy === "") {
+            stillOpen.push(ref);
+            continue;
+        }
+        const matched = byBlockedBy.get(blockedBy);
+        if (matched === undefined) {
+            stillOpen.push(ref);
+        }
+        else {
+            answered.push({ ref, facts: matched });
+        }
+    }
+    return { answered, stillOpen };
+}
+//# sourceMappingURL=confirmed-facts.js.map

package/dist/query/confirmed-facts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"confirmed-facts.js","sourceRoot":"","sources":["../../src/query/confirmed-facts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AA0BH;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,mBAAmB,CACjC,IAA8B,EAC9B,KAA+B,EAC/B,IAAY;IAEZ,MAAM,WAAW,GAAG,IAAI,GAAG,EAA2B,CAAC;IACvD,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,IAAI,CAAC,IAAI,KAAK,IAAI;YAAE,SAAS;QACjC,MAAM,QAAQ,GAAG,WAAW,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QACjD,IAAI,QAAQ,KAAK,SAAS;YAAE,WAAW,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC;;YAC/D,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC3B,CAAC;IAED,MAAM,QAAQ,GAAyB,EAAE,CAAC;IAC1C,MAAM,SAAS,GAAoB,EAAE,CAAC;IAEtC,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,MAAM,YAAY,GAAG,GAAG,CAAC,KAAK,EAAE,CAAC,cAAc,CAAC,CAAC;QACjD,MAAM,SAAS,GAAG,GAAG,CAAC,KAAK,EAAE,CAAC,WAAW,CAAC,CAAC;QAC3C,IAAI,YAAY,KAAK,eAAe,IAAI,OAAO,SAAS,KAAK,QAAQ,IAAI,SAAS,KAAK,EAAE,EAAE,CAAC;YAC1F,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YACpB,SAAS;QACX,CAAC;QACD,MAAM,OAAO,GAAG,WAAW,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QAC3C,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;YAC1B,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACtB,CAAC;aAAM,CAAC;YACN,QAAQ,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC,CAAC;QACzC,CAAC;IACH,CAAC;IAED,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,CAAC;AACjC,CAAC"}

package/dist/query/declared-value-closure.d.ts

@@ -0,0 +1,126 @@
+/**
+ * DEC-244's Row 2: wiring `resolveAgainstDeclared`'s output to actually close
+ * a ledger row.
+ *
+ * The grouper (DEC-243) turns rows into questions. `resolveAgainstDeclared`
+ * (`../ledger/resolve.ts`) turns a question into a per-environment answer
+ * from what the repository's own `.env*` files already state. Until this
+ * file, nothing joined the two — DEC-244's own measurement is 0 of 122 rows
+ * closed, not because either half is broken, but because neither called the
+ * other.
+ *
+ * ## What "closing" a row means here, and does not mean
+ *
+ * This produces a **classification**, never a graph edge — the same
+ * discipline `confirmed-facts.ts`'s header states for its own output and for
+ * the identical reason: minting `USES_API`/etc. needs a target to join
+ * against (an endpoint, a route) that this module has no way to resolve, and
+ * DEC-223 §6 already named that as separate, unbuilt work. A caller minting
+ * an edge from `closed`/`partiallyClosed` is the one obligated to attach the
+ * reliability this module already computed (`DECLARED_VALUE_RELIABILITY`,
+ * class A — see DEC-244 Row 1) rather than inventing its own.
+ *
+ * ## Why this is not a `ConfirmedFact`, and does not reuse its shape
+ *
+ * `ConfirmedFact` (DEC-223 §3) is testimony: one person's typed string,
+ * corroborated by nothing, capped at reliability class B by construction
+ * (`humanAsserted: true`). A value read from a repository's own `.env` file
+ * is the opposite kind of evidence — nobody asserted it, anyone can re-read
+ * the same file and get the same answer, and DEC-244 Row 1 rules it reaches
+ * class A on exactly the precedent `validation/env.ts` already established
+ * for `.env` reads generally (a direct, uninferred read of a declarative
+ * document, the same class of evidence that lets `adapter-openapi`/
+ * `adapter-sql` reach R3 with no language adapter at all). Constructing a
+ * `ConfirmedFact` here — with a synthetic `confirmedBy: "config:..."` and
+ * `humanAsserted` forced `false` at the call site — would make the *type*
+ * claim testimony while the *call site* claims otherwise, a distinction that
+ * survives exactly as long as every future caller remembers to look past the
+ * type to the call site. `DeclaredValueClosure` is the type-level guarantee
+ * instead: nothing shaped this way can ever be mistaken for testimony,
+ * because nothing about it says `confirmedBy`.
+ *
+ * ## The hard part: partial closure has to stay visibly partial
+ *
+ * `resolveAgainstDeclared`'s own `knownEnvironments` is deliberately narrow —
+ * it is *only* what this repository's `.env*` **filenames** assert exist,
+ * never invented. That narrowness is correct for `resolve.ts` (DEC-223's own
+ * "never guessed, always refused" rule) and creates a real trap one layer up:
+ * a repository can resolve **every environment its filenames mention** and
+ * still have a production deployment this reader has no way to see, because
+ * production's value never lived in a checked-in `.env*` file at all.
+ *
+ * Measured, not hypothetical: `sherpa-frontend` has exactly
+ * `.env.development` and `.env.development.local`, nothing named
+ * `production` anywhere in its `.env*` surface — `VITE_BACKEND_API_URL`
+ * resolves fully for `"development"` (`knownEnvironments.length === 1`), and
+ * a consumer that read that as "closed" would silently bind a `localhost`
+ * dev value to every production call site in the ledger. **That is the exact
+ * silent-failure shape this product exists to catch, reproduced inside the
+ * product**, which is why `MIN_KNOWN_ENVIRONMENTS_FOR_CLOSED` exists: a
+ * repository's own naming convention has to demonstrate it actually
+ * distinguishes more than one environment before this module will call
+ * anything fully closed. Below that bar, a fully-resolved result is reported
+ * as `"partially-closed"` — under-claiming is the safe direction (rule 2 —
+ * when in doubt, omit), and `resolution.knownEnvironments` stays attached to
+ * every closure record so a reader can see exactly what evidence there was.
+ *
+ * `sherpa-cf-worker` is the other real shape: it has **no** `.env*` files at
+ * all (its runtime config lives in `wrangler.toml`, `[vars]`/`[env.*.vars]`,
+ * a format `resolve.ts` deliberately does not read —
+ * `REQUEST-D-wrangler-vars-format.md`, not built). Every one of its rows
+ * therefore has `knownEnvironments.length === 0` and lands in `stillOpen`,
+ * which is correct and current, not a defect this module can fix.
+ */
+import type { UnresolvedRef } from "@descryy/ir";
+import { reliabilityCap } from "@descryy/ir";
+import type { DeclaredEnvValue, LedgerAccessorResolution } from "../ledger/resolve.ts";
+export type ClosureState = "closed" | "partially-closed";
+/** One row, closed or partially closed against this repository's own declared config values. */
+export interface DeclaredValueClosure {
+    readonly ref: UnresolvedRef;
+    readonly blockedBy: string;
+    readonly resolution: LedgerAccessorResolution;
+    readonly state: ClosureState;
+    /**
+     * Always `"A"` today — see the module header and DEC-244 Row 1.
+     * Carried per-closure rather than computed again by every caller, so a
+     * caller cannot accidentally pass `humanAsserted: true` and mislabel a
+     * direct read as testimony.
+     */
+    readonly reliability: ReturnType<typeof reliabilityCap>;
+}
+export interface DeclaredValueApplication {
+    readonly closed: readonly DeclaredValueClosure[];
+    readonly partiallyClosed: readonly DeclaredValueClosure[];
+    /**
+     * Everything else: not askable at all (wrong class, unset, no handle —
+     * `askableHandle` returned `null`), an unparseable `blockedBy`, zero
+     * `.env*` evidence for this repository, or a recognised name this
+     * repository's `.env*` files never set in any environment.
+     */
+    readonly stillOpen: readonly UnresolvedRef[];
+}
+/**
+ * A resolved value is a claim about *content* (what string a variable holds),
+ * not mere *existence* — `nameLevel: false`. At R3 this does not change the
+ * outcome (`reliabilityCap`'s R3/R4 branch returns `"A"` regardless of
+ * `nameLevel`), but a future caller reusing this constant at a lower
+ * resolution should not inherit a `nameLevel` value chosen for the wrong
+ * reason, so it is stated correctly here rather than left as an accident of
+ * R3 not needing it.
+ */
+export declare const DECLARED_VALUE_RELIABILITY: import("@descryy/ir").ReliabilityClass;
+/**
+ * Apply one repository's declared `.env*` values against its refusal ledger.
+ *
+ * The reconciliation this makes checkable, same law as the grouper and the
+ * Normaliser one level down each: every row in `refs` lands in exactly one
+ * of `closed`, `partiallyClosed` or `stillOpen` —
+ * `refs.length === closed.length + partiallyClosed.length + stillOpen.length`,
+ * always. `resolveAgainstDeclared` is called at most once per distinct
+ * `blockedBy` (cached), not once per row, matching `resolve.ts`'s own stated
+ * performance contract — "read once per repository ... runs many times
+ * against the result rather than rescanning per ledger row."
+ */
+export declare function applyDeclaredValues(refs: readonly UnresolvedRef[], declared: readonly DeclaredEnvValue[]): DeclaredValueApplication;
+//# sourceMappingURL=declared-value-closure.d.ts.map

package/dist/query/declared-value-closure.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"declared-value-closure.d.ts","sourceRoot":"","sources":["../../src/query/declared-value-closure.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwEG;AAEH,OAAO,KAAK,EAAmB,aAAa,EAAE,MAAM,aAAa,CAAC;AAClE,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAI7C,OAAO,KAAK,EAAE,gBAAgB,EAAE,wBAAwB,EAAE,MAAM,sBAAsB,CAAC;AAEvF,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,kBAAkB,CAAC;AAEzD,gGAAgG;AAChG,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,GAAG,EAAE,aAAa,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,wBAAwB,CAAC;IAC9C,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;IAC7B;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,EAAE,UAAU,CAAC,OAAO,cAAc,CAAC,CAAC;CACzD;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,MAAM,EAAE,SAAS,oBAAoB,EAAE,CAAC;IACjD,QAAQ,CAAC,eAAe,EAAE,SAAS,oBAAoB,EAAE,CAAC;IAC1D;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,EAAE,SAAS,aAAa,EAAE,CAAC;CAC9C;AAKD;;;;;;;;GAQG;AACH,eAAO,MAAM,0BAA0B,wCAA0D,CAAC;AAsBlG;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,SAAS,aAAa,EAAE,EAC9B,QAAQ,EAAE,SAAS,gBAAgB,EAAE,GACpC,wBAAwB,CAoC1B"}

package/dist/query/declared-value-closure.js

@@ -0,0 +1,156 @@
+/**
+ * DEC-244's Row 2: wiring `resolveAgainstDeclared`'s output to actually close
+ * a ledger row.
+ *
+ * The grouper (DEC-243) turns rows into questions. `resolveAgainstDeclared`
+ * (`../ledger/resolve.ts`) turns a question into a per-environment answer
+ * from what the repository's own `.env*` files already state. Until this
+ * file, nothing joined the two — DEC-244's own measurement is 0 of 122 rows
+ * closed, not because either half is broken, but because neither called the
+ * other.
+ *
+ * ## What "closing" a row means here, and does not mean
+ *
+ * This produces a **classification**, never a graph edge — the same
+ * discipline `confirmed-facts.ts`'s header states for its own output and for
+ * the identical reason: minting `USES_API`/etc. needs a target to join
+ * against (an endpoint, a route) that this module has no way to resolve, and
+ * DEC-223 §6 already named that as separate, unbuilt work. A caller minting
+ * an edge from `closed`/`partiallyClosed` is the one obligated to attach the
+ * reliability this module already computed (`DECLARED_VALUE_RELIABILITY`,
+ * class A — see DEC-244 Row 1) rather than inventing its own.
+ *
+ * ## Why this is not a `ConfirmedFact`, and does not reuse its shape
+ *
+ * `ConfirmedFact` (DEC-223 §3) is testimony: one person's typed string,
+ * corroborated by nothing, capped at reliability class B by construction
+ * (`humanAsserted: true`). A value read from a repository's own `.env` file
+ * is the opposite kind of evidence — nobody asserted it, anyone can re-read
+ * the same file and get the same answer, and DEC-244 Row 1 rules it reaches
+ * class A on exactly the precedent `validation/env.ts` already established
+ * for `.env` reads generally (a direct, uninferred read of a declarative
+ * document, the same class of evidence that lets `adapter-openapi`/
+ * `adapter-sql` reach R3 with no language adapter at all). Constructing a
+ * `ConfirmedFact` here — with a synthetic `confirmedBy: "config:..."` and
+ * `humanAsserted` forced `false` at the call site — would make the *type*
+ * claim testimony while the *call site* claims otherwise, a distinction that
+ * survives exactly as long as every future caller remembers to look past the
+ * type to the call site. `DeclaredValueClosure` is the type-level guarantee
+ * instead: nothing shaped this way can ever be mistaken for testimony,
+ * because nothing about it says `confirmedBy`.
+ *
+ * ## The hard part: partial closure has to stay visibly partial
+ *
+ * `resolveAgainstDeclared`'s own `knownEnvironments` is deliberately narrow —
+ * it is *only* what this repository's `.env*` **filenames** assert exist,
+ * never invented. That narrowness is correct for `resolve.ts` (DEC-223's own
+ * "never guessed, always refused" rule) and creates a real trap one layer up:
+ * a repository can resolve **every environment its filenames mention** and
+ * still have a production deployment this reader has no way to see, because
+ * production's value never lived in a checked-in `.env*` file at all.
+ *
+ * Measured, not hypothetical: `sherpa-frontend` has exactly
+ * `.env.development` and `.env.development.local`, nothing named
+ * `production` anywhere in its `.env*` surface — `VITE_BACKEND_API_URL`
+ * resolves fully for `"development"` (`knownEnvironments.length === 1`), and
+ * a consumer that read that as "closed" would silently bind a `localhost`
+ * dev value to every production call site in the ledger. **That is the exact
+ * silent-failure shape this product exists to catch, reproduced inside the
+ * product**, which is why `MIN_KNOWN_ENVIRONMENTS_FOR_CLOSED` exists: a
+ * repository's own naming convention has to demonstrate it actually
+ * distinguishes more than one environment before this module will call
+ * anything fully closed. Below that bar, a fully-resolved result is reported
+ * as `"partially-closed"` — under-claiming is the safe direction (rule 2 —
+ * when in doubt, omit), and `resolution.knownEnvironments` stays attached to
+ * every closure record so a reader can see exactly what evidence there was.
+ *
+ * `sherpa-cf-worker` is the other real shape: it has **no** `.env*` files at
+ * all (its runtime config lives in `wrangler.toml`, `[vars]`/`[env.*.vars]`,
+ * a format `resolve.ts` deliberately does not read —
+ * `REQUEST-D-wrangler-vars-format.md`, not built). Every one of its rows
+ * therefore has `knownEnvironments.length === 0` and lands in `stillOpen`,
+ * which is correct and current, not a defect this module can fix.
+ */
+import { reliabilityCap } from "@descryy/ir";
+import { askableHandle } from "./refusal-questions.js";
+import { resolveAgainstDeclared } from "../ledger/resolve.js";
+/** Direct reads of `.env*` need no resolution — same precedent `validation/env.ts` already uses (DEC-244 Row 1). */
+const DECLARED_VALUE_RESOLUTION = 3;
+/**
+ * A resolved value is a claim about *content* (what string a variable holds),
+ * not mere *existence* — `nameLevel: false`. At R3 this does not change the
+ * outcome (`reliabilityCap`'s R3/R4 branch returns `"A"` regardless of
+ * `nameLevel`), but a future caller reusing this constant at a lower
+ * resolution should not inherit a `nameLevel` value chosen for the wrong
+ * reason, so it is stated correctly here rather than left as an accident of
+ * R3 not needing it.
+ */
+export const DECLARED_VALUE_RELIABILITY = reliabilityCap(DECLARED_VALUE_RESOLUTION, false, false);
+/**
+ * A repository's own `.env*` naming has to name at least this many distinct
+ * environments before a fully-resolved result is trusted as `"closed"`
+ * rather than `"partially-closed"` — see the module header's `sherpa-frontend`
+ * case. Not tuned; picked as the smallest number that is structurally
+ * meaningful (one named environment proves nothing about whether a second,
+ * unnamed one exists; two or more is the repository's own convention
+ * demonstrating it actually distinguishes environments).
+ */
+const MIN_KNOWN_ENVIRONMENTS_FOR_CLOSED = 2;
+function classify(resolution) {
+    if (resolution.resolution === null)
+        return "open"; // blockedBy shape not recognised
+    if (resolution.knownEnvironments.length === 0)
+        return "open"; // no .env* evidence at all
+    if (resolution.resolved.length === 0)
+        return "open"; // known environments, resolved in none of them
+    if (resolution.unresolvedEnvironments.length > 0)
+        return "partially-closed"; // some known environments unresolved
+    if (resolution.knownEnvironments.length < MIN_KNOWN_ENVIRONMENTS_FOR_CLOSED)
+        return "partially-closed"; // thin evidence
+    return "closed";
+}
+/**
+ * Apply one repository's declared `.env*` values against its refusal ledger.
+ *
+ * The reconciliation this makes checkable, same law as the grouper and the
+ * Normaliser one level down each: every row in `refs` lands in exactly one
+ * of `closed`, `partiallyClosed` or `stillOpen` —
+ * `refs.length === closed.length + partiallyClosed.length + stillOpen.length`,
+ * always. `resolveAgainstDeclared` is called at most once per distinct
+ * `blockedBy` (cached), not once per row, matching `resolve.ts`'s own stated
+ * performance contract — "read once per repository ... runs many times
+ * against the result rather than rescanning per ledger row."
+ */
+export function applyDeclaredValues(refs, declared) {
+    const cache = new Map();
+    const closed = [];
+    const partiallyClosed = [];
+    const stillOpen = [];
+    for (const ref of refs) {
+        const blockedBy = askableHandle(ref);
+        if (blockedBy === null) {
+            stillOpen.push(ref);
+            continue;
+        }
+        let resolution = cache.get(blockedBy);
+        if (resolution === undefined) {
+            resolution = resolveAgainstDeclared(blockedBy, declared);
+            cache.set(blockedBy, resolution);
+        }
+        const state = classify(resolution);
+        if (state === "open") {
+            stillOpen.push(ref);
+            continue;
+        }
+        const closure = {
+            ref,
+            blockedBy,
+            resolution,
+            state,
+            reliability: DECLARED_VALUE_RELIABILITY,
+        };
+        (state === "closed" ? closed : partiallyClosed).push(closure);
+    }
+    return { closed, partiallyClosed, stillOpen };
+}
+//# sourceMappingURL=declared-value-closure.js.map

package/dist/query/declared-value-closure.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"declared-value-closure.js","sourceRoot":"","sources":["../../src/query/declared-value-closure.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwEG;AAGH,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAE7C,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AACvD,OAAO,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAgC9D,oHAAoH;AACpH,MAAM,yBAAyB,GAAoB,CAAC,CAAC;AAErD;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,cAAc,CAAC,yBAAyB,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC;AAElG;;;;;;;;GAQG;AACH,MAAM,iCAAiC,GAAG,CAAC,CAAC;AAE5C,SAAS,QAAQ,CAAC,UAAoC;IACpD,IAAI,UAAU,CAAC,UAAU,KAAK,IAAI;QAAE,OAAO,MAAM,CAAC,CAAC,iCAAiC;IACpF,IAAI,UAAU,CAAC,iBAAiB,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,MAAM,CAAC,CAAC,2BAA2B;IACzF,IAAI,UAAU,CAAC,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,MAAM,CAAC,CAAC,+CAA+C;IACpG,IAAI,UAAU,CAAC,sBAAsB,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,kBAAkB,CAAC,CAAC,qCAAqC;IAClH,IAAI,UAAU,CAAC,iBAAiB,CAAC,MAAM,GAAG,iCAAiC;QAAE,OAAO,kBAAkB,CAAC,CAAC,gBAAgB;IACxH,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,mBAAmB,CACjC,IAA8B,EAC9B,QAAqC;IAErC,MAAM,KAAK,GAAG,IAAI,GAAG,EAAoC,CAAC;IAC1D,MAAM,MAAM,GAA2B,EAAE,CAAC;IAC1C,MAAM,eAAe,GAA2B,EAAE,CAAC;IACnD,MAAM,SAAS,GAAoB,EAAE,CAAC;IAEtC,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,MAAM,SAAS,GAAG,aAAa,CAAC,GAAG,CAAC,CAAC;QACrC,IAAI,SAAS,KAAK,IAAI,EAAE,CAAC;YACvB,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YACpB,SAAS;QACX,CAAC;QAED,IAAI,UAAU,GAAG,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;QACtC,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;YAC7B,UAAU,GAAG,sBAAsB,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;YACzD,KAAK,CAAC,GAAG,CAAC,SAAS,EAAE,UAAU,CAAC,CAAC;QACnC,CAAC;QAED,MAAM,KAAK,GAAG,QAAQ,CAAC,UAAU,CAAC,CAAC;QACnC,IAAI,KAAK,KAAK,MAAM,EAAE,CAAC;YACrB,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YACpB,SAAS;QACX,CAAC;QAED,MAAM,OAAO,GAAyB;YACpC,GAAG;YACH,SAAS;YACT,UAAU;YACV,KAAK;YACL,WAAW,EAAE,0BAA0B;SACxC,CAAC;QACF,CAAC,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAChE,CAAC;IAED,OAAO,EAAE,MAAM,EAAE,eAAe,EAAE,SAAS,EAAE,CAAC;AAChD,CAAC"}

package/dist/query/index.d.ts

@@ -0,0 +1,28 @@
+export { rankEdges, applyAdjacencyOptions } from "./provider.ts";
+export type { AdjacencyProvider, AdjacencyOptions, GraphStamp, QueryResult, } from "./provider.ts";
+export { createMemoryProvider } from "./memory.ts";
+export type { MemoryGraph } from "./memory.ts";
+export { createStoreProvider, commitSpread } from "./sqlite.ts";
+export { bfs, weightedBfs, findPath, API_JOIN_EDGE_TYPES } from "./traverse.ts";
+export type { Direction, Reached, TraversalOptions, TraversalOutcome, WeightedOptions } from "./traverse.ts";
+export { impactOf, rootCauseSearch, testsCovering, dataFlowFrom, DATA_FLOW_EDGE_TYPES, traceApi, changeRisk, changesWith, } from "./queries.ts";
+export type { ImpactOptions, RootCauseMatch, ChangeRisk, CoChange } from "./queries.ts";
+export { similarIncidents, tokenSetSimilarity, fileOverlapSimilarity } from "./similar-incidents.ts";
+export type { SimilarFailureQuery, SimilarIncidentMatch, SimilarIncidentOptions, SimilarIncidentSignal, SimilarIncidentSignalKind, } from "./similar-incidents.ts";
+export { classifyRefusal, classifyRefusals, readRate } from "./unresolved.ts";
+export type { RefusalClass, RefusalScope, RefusalCensus, ReadRate } from "./unresolved.ts";
+export { applyConfirmedFacts } from "./confirmed-facts.ts";
+export type { ConfirmedFactApplication, ConfirmedFactMatch } from "./confirmed-facts.ts";
+export { groupRefusalsIntoQuestions, groupRefusalsAcrossRepos, askableHandle } from "./refusal-questions.ts";
+export type { RefusalSite, RefusalQuestion, RefusalDropCounts, GroupingResult, } from "./refusal-questions.ts";
+export { summariseRefusals, fetchRefusalPage } from "./refusal-fetch.ts";
+export type { RefusalSummary, RefusalPage, RefusalPageOk, RefusalPageRefused } from "./refusal-fetch.ts";
+export { computeVerificationStatus, resolutionOfExercised } from "./verification-status.ts";
+export type { CoverageCheck, ScopeItem } from "./verification-status.ts";
+export { applyDeclaredValues, DECLARED_VALUE_RELIABILITY } from "./declared-value-closure.ts";
+export type { ClosureState, DeclaredValueClosure, DeclaredValueApplication, } from "./declared-value-closure.ts";
+export { describeRowClosures } from "./row-closure-picture.ts";
+export type { EnvironmentValue, AssertedValue, RowClosurePicture, RowClosureApplication, } from "./row-closure-picture.ts";
+export { rankRootCause, DEFAULT_ROOT_CAUSE_WEIGHTS, ROOT_CAUSE_TRACE_EDGE_TYPES, INCIDENT_SATURATION } from "./root-cause-score.ts";
+export type { RootCauseWeights, RootCauseOptions, RankedRootCauseCandidate, RootCauseRanking, ChangeCouplingEvidence, } from "./root-cause-score.ts";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/query/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AACjE,YAAY,EACV,iBAAiB,EACjB,gBAAgB,EAChB,UAAU,EACV,WAAW,GACZ,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AACnD,YAAY,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/C,OAAO,EAAE,mBAAmB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhE,OAAO,EAAE,GAAG,EAAE,WAAW,EAAE,QAAQ,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAChF,YAAY,EAAE,SAAS,EAAE,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAE7G,OAAO,EACL,QAAQ,EACR,eAAe,EACf,aAAa,EACb,YAAY,EACZ,oBAAoB,EACpB,QAAQ,EACR,UAAU,EACV,WAAW,GACZ,MAAM,cAAc,CAAC;AACtB,YAAY,EAAE,aAAa,EAAE,cAAc,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAExF,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AACrG,YAAY,EACV,mBAAmB,EACnB,oBAAoB,EACpB,sBAAsB,EACtB,qBAAqB,EACrB,yBAAyB,GAC1B,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAC9E,YAAY,EAAE,YAAY,EAAE,YAAY,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAE3F,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAC3D,YAAY,EAAE,wBAAwB,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAEzF,OAAO,EAAE,0BAA0B,EAAE,wBAAwB,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAC7G,YAAY,EACV,WAAW,EACX,eAAe,EACf,iBAAiB,EACjB,cAAc,GACf,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACzE,YAAY,EAAE,cAAc,EAAE,WAAW,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAEzG,OAAO,EAAE,yBAAyB,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AAC5F,YAAY,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAEzE,OAAO,EAAE,mBAAmB,EAAE,0BAA0B,EAAE,MAAM,6BAA6B,CAAC;AAC9F,YAAY,EACV,YAAY,EACZ,oBAAoB,EACpB,wBAAwB,GACzB,MAAM,6BAA6B,CAAC;AAErC,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAC/D,YAAY,EACV,gBAAgB,EAChB,aAAa,EACb,iBAAiB,EACjB,qBAAqB,GACtB,MAAM,0BAA0B,CAAC;AAElC,OAAO,EAAE,aAAa,EAAE,0BAA0B,EAAE,2BAA2B,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AACpI,YAAY,EACV,gBAAgB,EAChB,gBAAgB,EAChB,wBAAwB,EACxB,gBAAgB,EAChB,sBAAsB,GACvB,MAAM,uBAAuB,CAAC"}

package/dist/query/index.js

@@ -0,0 +1,15 @@
+export { rankEdges, applyAdjacencyOptions } from "./provider.js";
+export { createMemoryProvider } from "./memory.js";
+export { createStoreProvider, commitSpread } from "./sqlite.js";
+export { bfs, weightedBfs, findPath, API_JOIN_EDGE_TYPES } from "./traverse.js";
+export { impactOf, rootCauseSearch, testsCovering, dataFlowFrom, DATA_FLOW_EDGE_TYPES, traceApi, changeRisk, changesWith, } from "./queries.js";
+export { similarIncidents, tokenSetSimilarity, fileOverlapSimilarity } from "./similar-incidents.js";
+export { classifyRefusal, classifyRefusals, readRate } from "./unresolved.js";
+export { applyConfirmedFacts } from "./confirmed-facts.js";
+export { groupRefusalsIntoQuestions, groupRefusalsAcrossRepos, askableHandle } from "./refusal-questions.js";
+export { summariseRefusals, fetchRefusalPage } from "./refusal-fetch.js";
+export { computeVerificationStatus, resolutionOfExercised } from "./verification-status.js";
+export { applyDeclaredValues, DECLARED_VALUE_RELIABILITY } from "./declared-value-closure.js";
+export { describeRowClosures } from "./row-closure-picture.js";
+export { rankRootCause, DEFAULT_ROOT_CAUSE_WEIGHTS, ROOT_CAUSE_TRACE_EDGE_TYPES, INCIDENT_SATURATION } from "./root-cause-score.js";
+//# sourceMappingURL=index.js.map

package/dist/query/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/query/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AAQjE,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAGnD,OAAO,EAAE,mBAAmB,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhE,OAAO,EAAE,GAAG,EAAE,WAAW,EAAE,QAAQ,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAGhF,OAAO,EACL,QAAQ,EACR,eAAe,EACf,aAAa,EACb,YAAY,EACZ,oBAAoB,EACpB,QAAQ,EACR,UAAU,EACV,WAAW,GACZ,MAAM,cAAc,CAAC;AAGtB,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AASrG,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAG9E,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAG3D,OAAO,EAAE,0BAA0B,EAAE,wBAAwB,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAQ7G,OAAO,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAGzE,OAAO,EAAE,yBAAyB,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AAG5F,OAAO,EAAE,mBAAmB,EAAE,0BAA0B,EAAE,MAAM,6BAA6B,CAAC;AAO9F,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAQ/D,OAAO,EAAE,aAAa,EAAE,0BAA0B,EAAE,2BAA2B,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/query/memory.d.ts

@@ -0,0 +1,20 @@
+/**
+ * An in-memory `AdjacencyProvider`.
+ *
+ * The reason the interface exists. Building one of these from a `BuildResult` is
+ * four lines and needs no file, no schema, no writer and no worker — so the
+ * traversal and query tests below it exercise the same code paths production
+ * uses, without any of the setup that would otherwise make them slow enough to
+ * skip.
+ */
+import type { IREdge, IRNode, UnresolvedRef } from "@descryy/ir";
+import { type AdjacencyProvider } from "./provider.ts";
+export interface MemoryGraph {
+    readonly nodes: readonly IRNode[];
+    readonly edges: readonly IREdge[];
+    readonly unresolved?: readonly UnresolvedRef[];
+    readonly commitSha?: string | null;
+    readonly graphBuiltAt?: number | null;
+}
+export declare function createMemoryProvider(graph: MemoryGraph): AdjacencyProvider;
+//# sourceMappingURL=memory.d.ts.map

package/dist/query/memory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../../src/query/memory.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,EAAY,aAAa,EAAE,MAAM,aAAa,CAAC;AAE3E,OAAO,EAIL,KAAK,iBAAiB,EAEvB,MAAM,eAAe,CAAC;AAGvB,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,aAAa,EAAE,CAAC;IAC/C,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACvC;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,WAAW,GAAG,iBAAiB,CA8C1E"}

package/dist/query/memory.js

@@ -0,0 +1,55 @@
+/**
+ * An in-memory `AdjacencyProvider`.
+ *
+ * The reason the interface exists. Building one of these from a `BuildResult` is
+ * four lines and needs no file, no schema, no writer and no worker — so the
+ * traversal and query tests below it exercise the same code paths production
+ * uses, without any of the setup that would otherwise make them slow enough to
+ * skip.
+ */
+import { applyAdjacencyOptions, DEFAULT_NODE_SET_LIMIT, } from "./provider.js";
+import { IR_SCHEMA_VERSION } from "../store/schema.js";
+export function createMemoryProvider(graph) {
+    const nodes = new Map(graph.nodes.map((n) => [n.id, n]));
+    const out = new Map();
+    const inc = new Map();
+    for (const edge of graph.edges) {
+        (out.get(edge.from) ?? out.set(edge.from, []).get(edge.from)).push(edge);
+        (inc.get(edge.to) ?? inc.set(edge.to, []).get(edge.to)).push(edge);
+    }
+    const stamp = {
+        commitSha: graph.commitSha ?? null,
+        graphBuiltAt: graph.graphBuiltAt ?? null,
+        irSchemaVersion: IR_SCHEMA_VERSION,
+    };
+    // Indexed once rather than filtered per call: the contract engine asks for
+    // three types in a row, and a linear scan each time turns an O(n) report into
+    // an O(3n) one for no reason.
+    const byType = new Map();
+    for (const node of graph.nodes) {
+        let bucket = byType.get(node.type);
+        if (bucket === undefined)
+            byType.set(node.type, (bucket = []));
+        bucket.push(node);
+    }
+    for (const bucket of byType.values())
+        bucket.sort((a, b) => a.id.localeCompare(b.id));
+    return {
+        node: (id) => nodes.get(id),
+        outgoing: (id, options) => applyAdjacencyOptions(out.get(id) ?? [], options),
+        incoming: (id, options) => applyAdjacencyOptions(inc.get(id) ?? [], options),
+        nodesOfType: (type, limit = DEFAULT_NODE_SET_LIMIT) => {
+            const all = byType.get(type) ?? [];
+            return { nodes: all.slice(0, limit), truncated: all.length > limit };
+        },
+        unresolvedRefs: (options) => {
+            const classified = options?.classified ?? true;
+            const all = (graph.unresolved ?? []).filter((r) => !classified || r.attrs !== undefined);
+            const limit = options?.limit;
+            const truncated = limit !== undefined && all.length > limit;
+            return { refs: truncated ? all.slice(0, limit) : all, truncated };
+        },
+        baseStamp: () => stamp,
+    };
+}
+//# sourceMappingURL=memory.js.map

package/dist/query/memory.js.map

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

package/dist/query/provider.d.ts

@@ -0,0 +1,127 @@
+/**
+ * `AdjacencyProvider` — the interface every traversal is written against.
+ *
+ * Not an abstraction for its own sake. Two consequences follow from it and both
+ * are structural:
+ *
+ * 1. **Most of the engine's tests need no database.** A traversal written
+ *    against SQLite is a traversal that can only be tested with a file, a
+ *    schema, a writer and eventually a worker thread. Written against this, the
+ *    same code runs over an in-memory graph built in four lines.
+ *
+ * 2. **Traversal stays identical across backends.** §11.8 chose application-code
+ *    traversal over recursive CTEs precisely so that decay scoring, budgets and
+ *    per-edge weights work the same on SQLite and Postgres. That only holds if
+ *    the traversal never sees which one it is talking to.
+ *
+ * `incoming()` takes a limit and a ranking rather than returning everything.
+ * That is not politeness: the prior-art graphs measured for this build have a
+ * max in-degree of **1,036** (`append`), and materialising every neighbour of a
+ * hub turns a 200-node budget into a 10,000-row read.
+ */
+import type { EdgeType, IREdge, IRNode, NodeType, ResolutionLevel, UnresolvedRef } from "@descryy/ir";
+export interface AdjacencyOptions {
+    readonly types?: readonly EdgeType[];
+    /**
+     * Cap on returned edges, applied *after* ranking by resolution then confidence.
+     * A cap without a ranking keeps whichever rows the index reached first, which
+     * is both arbitrary and unstable between runs.
+     */
+    readonly limit?: number;
+    /** Drop edges below this confidence before ranking. */
+    readonly minConfidence?: number;
+}
+/**
+ * What every query response carries — §27.3's staleness rule.
+ *
+ * Threaded through from the start on purpose. Retrofitting a stamp through six
+ * return shapes later is the kind of change that gets deferred once and then
+ * never made, and a query layer that cannot say *how old and how well resolved*
+ * its answer is cannot support the honesty rules that the product is.
+ */
+export interface GraphStamp {
+    /** The commit the graph was built from. Null on an empty graph. */
+    readonly commitSha: string | null;
+    /** Epoch ms of the most recent write. Null on an empty graph. */
+    readonly graphBuiltAt: number | null;
+    readonly irSchemaVersion: number;
+    /**
+     * The lowest resolution anything in *this answer* rests on.
+     *
+     * Per architecture principle 3 the reliability class of a finding is capped by
+     * the resolution of the edges beneath it, so this is the cap, computed per
+     * result rather than declared globally. A result touching one R0 edge is an R0
+     * result no matter how well resolved the rest of it is.
+     */
+    readonly resolutionFloor: ResolutionLevel;
+}
+/** Everything a query returns, so no caller can accidentally drop the disclosure. */
+export interface QueryResult<T> {
+    readonly data: T;
+    readonly stamp: GraphStamp;
+    /** True when a budget or limit stopped the answer short of complete. */
+    readonly truncated: boolean;
+    /**
+     * Things the caller must be told, in plain words — §20.2's "not tested" and
+     * "not analysable" categories start here. Never empty for a degraded answer.
+     */
+    readonly notes: readonly string[];
+}
+/** What `nodesOfType` returned, and whether that was all of them. */
+export interface NodeSet {
+    readonly nodes: readonly IRNode[];
+    /** True when the limit stopped the answer short. Never silently discarded. */
+    readonly truncated: boolean;
+}
+/** What `unresolvedRefs` returned, and whether that was all of them. */
+export interface UnresolvedRefSet {
+    readonly refs: readonly UnresolvedRef[];
+    readonly truncated: boolean;
+}
+export interface AdjacencyProvider {
+    node(id: string): IRNode | undefined;
+    outgoing(id: string, options?: AdjacencyOptions): readonly IREdge[];
+    incoming(id: string, options?: AdjacencyOptions): readonly IREdge[];
+    /**
+     * Every node of one type, capped.
+     *
+     * The one query that is not adjacency, and it is here because a whole class of
+     * question cannot start from a seed. *"Which endpoints does the frontend call
+     * that no route serves?"* has no node to begin at — the answer is a property
+     * of the **set**, and the contract engine, the static-validation checks and
+     * the capability-tier generator all need it.
+     *
+     * Capped, and the cap is reported rather than applied quietly. `API_ENDPOINT`
+     * runs to the hundreds and is safe to enumerate; `FUNCTION` on a large
+     * monorepo runs to tens of thousands, and a caller that asked for all of them
+     * and silently received the first thousand would compute a set property over a
+     * sample and report it as a fact.
+     */
+    nodesOfType(type: NodeType, limit?: number): NodeSet;
+    /**
+     * Refusal-ledger rows — DEC-243's question grouper reads these. `classified`
+     * (default `true`) restricts to rows carrying `attrs` at all, which is every
+     * row that could ever become a question; see `store/reader.ts#unresolvedRefs`
+     * for why that is a real filter and not an approximation.
+     */
+    unresolvedRefs(options?: {
+        readonly classified?: boolean;
+        readonly limit?: number;
+    }): UnresolvedRefSet;
+    /** Graph-level provenance. The per-result `resolutionFloor` is computed by the query. */
+    baseStamp(): Omit<GraphStamp, "resolutionFloor">;
+}
+/** The cap `nodesOfType` applies when a caller names none. */
+export declare const DEFAULT_NODE_SET_LIMIT = 5000;
+/**
+ * Rank edges the way every caller wants them: best evidence first, stably.
+ *
+ * Resolution outranks confidence because they are not the same axis — a
+ * type-checked edge at 0.8 is a better fact than a name-matched one at 0.95, and
+ * §11A.5 exists because v2.0 could not tell those apart. `from`/`to`/`type`
+ * break the final tie so the order is identical between runs.
+ */
+export declare function rankEdges(edges: readonly IREdge[]): IREdge[];
+/** Apply type filter, confidence floor, ranking and limit. Shared by both providers. */
+export declare function applyAdjacencyOptions(edges: readonly IREdge[], options?: AdjacencyOptions): IREdge[];
+//# sourceMappingURL=provider.d.ts.map

package/dist/query/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../../src/query/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEtG,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,QAAQ,EAAE,CAAC;IACrC;;;;OAIG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,uDAAuD;IACvD,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,UAAU;IACzB,mEAAmE;IACnE,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,iEAAiE;IACjE,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC;;;;;;;OAOG;IACH,QAAQ,CAAC,eAAe,EAAE,eAAe,CAAC;CAC3C;AAED,qFAAqF;AACrF,MAAM,WAAW,WAAW,CAAC,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;IACjB,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAC3B,wEAAwE;IACxE,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;CACnC;AAED,qEAAqE;AACrE,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,8EAA8E;IAC9E,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC7B;AAED,wEAAwE;AACxE,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,SAAS,aAAa,EAAE,CAAC;IACxC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC7B;AAED,MAAM,WAAW,iBAAiB;IAChC,IAAI,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IACrC,QAAQ,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,SAAS,MAAM,EAAE,CAAC;IACpE,QAAQ,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,SAAS,MAAM,EAAE,CAAC;IACpE;;;;;;;;;;;;;;OAcG;IACH,WAAW,CAAC,IAAI,EAAE,QAAQ,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IACrD;;;;;OAKG;IACH,cAAc,CAAC,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC;QAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,gBAAgB,CAAC;IACvG,yFAAyF;IACzF,SAAS,IAAI,IAAI,CAAC,UAAU,EAAE,iBAAiB,CAAC,CAAC;CAClD;AAED,8DAA8D;AAC9D,eAAO,MAAM,sBAAsB,OAAQ,CAAC;AAE5C;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,CAM5D;AAED,wFAAwF;AACxF,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,OAAO,GAAE,gBAAqB,GAC7B,MAAM,EAAE,CAYV"}