@descryy/core 0.1.0

package/dist/query/provider.js

@@ -0,0 +1,54 @@
+/**
+ * `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.
+ */
+/** The cap `nodesOfType` applies when a caller names none. */
+export const DEFAULT_NODE_SET_LIMIT = 5_000;
+/**
+ * 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 function rankEdges(edges) {
+    return [...edges].sort((a, b) => {
+        if (a.resolution !== b.resolution)
+            return b.resolution - a.resolution;
+        if (a.confidence !== b.confidence)
+            return b.confidence - a.confidence;
+        return `${a.from}${a.to}${a.type}`.localeCompare(`${b.from}${b.to}${b.type}`);
+    });
+}
+/** Apply type filter, confidence floor, ranking and limit. Shared by both providers. */
+export function applyAdjacencyOptions(edges, options = {}) {
+    const types = options.types;
+    let filtered = types === undefined || types.length === 0
+        ? [...edges]
+        : edges.filter((e) => types.includes(e.type));
+    if (options.minConfidence !== undefined) {
+        const floor = options.minConfidence;
+        filtered = filtered.filter((e) => e.confidence >= floor);
+    }
+    const ranked = rankEdges(filtered);
+    return options.limit === undefined ? ranked : ranked.slice(0, Math.max(0, options.limit));
+}
+//# sourceMappingURL=provider.js.map

package/dist/query/provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.js","sourceRoot":"","sources":["../../src/query/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAkGH,8DAA8D;AAC9D,MAAM,CAAC,MAAM,sBAAsB,GAAG,KAAK,CAAC;AAE5C;;;;;;;GAOG;AACH,MAAM,UAAU,SAAS,CAAC,KAAwB;IAChD,OAAO,CAAC,GAAG,KAAK,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;QAC9B,IAAI,CAAC,CAAC,UAAU,KAAK,CAAC,CAAC,UAAU;YAAE,OAAO,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,UAAU,CAAC;QACtE,IAAI,CAAC,CAAC,UAAU,KAAK,CAAC,CAAC,UAAU;YAAE,OAAO,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,UAAU,CAAC;QACtE,OAAO,GAAG,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;IAChF,CAAC,CAAC,CAAC;AACL,CAAC;AAED,wFAAwF;AACxF,MAAM,UAAU,qBAAqB,CACnC,KAAwB,EACxB,UAA4B,EAAE;IAE9B,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC;IAC5B,IAAI,QAAQ,GACV,KAAK,KAAK,SAAS,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QACvC,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC;QACZ,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;IAClD,IAAI,OAAO,CAAC,aAAa,KAAK,SAAS,EAAE,CAAC;QACxC,MAAM,KAAK,GAAG,OAAO,CAAC,aAAa,CAAC;QACpC,QAAQ,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,IAAI,KAAK,CAAC,CAAC;IAC3D,CAAC;IACD,MAAM,MAAM,GAAG,SAAS,CAAC,QAAQ,CAAC,CAAC;IACnC,OAAO,OAAO,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC;AAC5F,CAAC"}

package/dist/query/queries.d.ts

@@ -0,0 +1,119 @@
+/**
+ * The six query types of architecture §11.9, plus one added since: §18's
+ * `get_git_history`/`get_git_diff` named a real gap — `CHANGES_WITH` edges
+ * existed in the graph, produced by `analyze`'s git source, with no query
+ * reading them per node. `changesWith` (below) is that query. It is scoped to
+ * the stored co-change graph, never a live `git log`/`git diff` call — a new
+ * query over an existing edge type, not a new capability.
+ *
+ * Every one returns a `QueryResult`, so no caller can take the answer without
+ * the disclosure attached to it. That is the point of the envelope: §27.3's
+ * staleness rule and principle 3's resolution cap are not reporting concerns
+ * bolted on later, they are properties of the answer itself.
+ *
+ * One of the seven is **deliberately incomplete in this build** and says so —
+ * see `rootCauseSearch`. Reporting a partial answer as a whole one is the
+ * exact failure the honest-degradation rule exists to prevent.
+ */
+import type { EdgeType, IRNode } from "@descryy/ir";
+import type { AdjacencyProvider, QueryResult } from "./provider.ts";
+import { type TraversalOptions } from "./traverse.ts";
+export interface ImpactOptions extends TraversalOptions {
+    /** Score decay per hop. Step 12 replaces this with §12.4's real weights. */
+    readonly weightFor?: (edge: {
+        confidence: number;
+        type: EdgeType;
+    }) => number;
+    readonly minScore?: number;
+}
+export declare function impactOf(provider: AdjacencyProvider, seeds: readonly string[], options?: ImpactOptions): QueryResult<{
+    node: IRNode;
+    depth: number;
+    score: number;
+}[]>;
+export interface RootCauseMatch {
+    readonly incident: IRNode;
+    readonly via: EdgeType;
+}
+/**
+ * Incidents correlated with a node, by graph edges only.
+ *
+ * **Incomplete by design in this build, and the caller is told so.** §11.9's
+ * root-cause query is "incident **plus embedding match**", and this build has no
+ * vector store — `embeddings` is a pointer table, since §8.2 keeps vectors in
+ * pgvector or a local extension and a column of serialised floats with no index
+ * is a scan rather than a search.
+ *
+ * So this answers the structural half and discloses the other. Returning it
+ * silently as "root cause search" would report "we found no similar incident"
+ * when the truth is "we did not look the way we said we would" — §20.2 keeps
+ * those in different categories for a reason.
+ */
+export declare function rootCauseSearch(provider: AdjacencyProvider, nodeId: string): QueryResult<RootCauseMatch[]>;
+export declare function testsCovering(provider: AdjacencyProvider, nodeId: string, options?: {
+    maxDepth?: number;
+    budget?: number;
+}): QueryResult<IRNode[]>;
+/**
+ * The four edge types that carry data rather than control.
+ *
+ * Exported because a caller that discloses *what it walked* must name the same
+ * list this walk uses. A second copy in the MCP tool would drift, and the note
+ * would then describe a walk that did not run — the report-the-run rule applied
+ * to a constant instead of to a header.
+ */
+export declare const DATA_FLOW_EDGE_TYPES: readonly ["PROPAGATES_TO", "READS", "WRITES", "RETURNS"];
+export declare function dataFlowFrom(provider: AdjacencyProvider, nodeId: string, options?: TraversalOptions): QueryResult<{
+    node: IRNode;
+    depth: number;
+    score: number;
+}[]>;
+export declare function traceApi(provider: AdjacencyProvider, fromNodeId: string, toNodeId: string, options?: TraversalOptions): QueryResult<{
+    path: IRNode[];
+    hops: number;
+}>;
+export interface ChangeRisk {
+    readonly affected: {
+        node: IRNode;
+        depth: number;
+        score: number;
+    }[];
+    readonly tests: IRNode[];
+    readonly untested: IRNode[];
+}
+/**
+ * The scoped subgraph, ranked, intersected with `TESTS` edges.
+ *
+ * The ranking weights are Step 12's; this composes the primitives so that step
+ * supplies a weight function rather than a second traversal.
+ */
+export declare function changeRisk(provider: AdjacencyProvider, changed: readonly string[], options?: ImpactOptions): QueryResult<ChangeRisk>;
+export interface CoChange {
+    readonly node: IRNode;
+    /** Commits touching both files together, within the git source's own read window. */
+    readonly support: number;
+    /** `support` divided by the more-frequently-changed file's own total — DEC-036/§11.7. */
+    readonly confidence: number;
+}
+/**
+ * `CHANGES_WITH` edges touching one `FILE` node, in either direction.
+ *
+ * `CHANGES_WITH` is symmetric but stored once, `from` the lexicographically
+ * smaller path (DEC-036) — reading only `provider.outgoing` would silently
+ * miss every pair where this file sorts second. Both `outgoing` and
+ * `incoming` are read here so the caller never has to know which side of the
+ * pair this file landed on; `traverse.ts`'s `neighbours()` does the identical
+ * thing for `direction: "both"`, but a one-hop, unscored list is what this
+ * question actually asks — walking it through `bfs` would return `Reached`
+ * entries with no `support`/`confidence` to report, since those live in
+ * `attrs`, not in the traversal primitives' own `Reached` shape.
+ *
+ * Answers only what the stored graph holds: co-change is windowed by however
+ * far back the git source read (`GitSourceOptions`, not this function's
+ * concern), and a pair below `minSupport`/`minConfidence` at ingest time
+ * never became an edge at all — silence here does not mean the files never
+ * changed together, only that they did not clear the threshold recorded when
+ * the graph was built.
+ */
+export declare function changesWith(provider: AdjacencyProvider, nodeId: string): QueryResult<CoChange[]>;
+//# sourceMappingURL=queries.d.ts.map

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

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

package/dist/query/queries.js

@@ -0,0 +1,267 @@
+/**
+ * The six query types of architecture §11.9, plus one added since: §18's
+ * `get_git_history`/`get_git_diff` named a real gap — `CHANGES_WITH` edges
+ * existed in the graph, produced by `analyze`'s git source, with no query
+ * reading them per node. `changesWith` (below) is that query. It is scoped to
+ * the stored co-change graph, never a live `git log`/`git diff` call — a new
+ * query over an existing edge type, not a new capability.
+ *
+ * Every one returns a `QueryResult`, so no caller can take the answer without
+ * the disclosure attached to it. That is the point of the envelope: §27.3's
+ * staleness rule and principle 3's resolution cap are not reporting concerns
+ * bolted on later, they are properties of the answer itself.
+ *
+ * One of the seven is **deliberately incomplete in this build** and says so —
+ * see `rootCauseSearch`. Reporting a partial answer as a whole one is the
+ * exact failure the honest-degradation rule exists to prevent.
+ */
+import { bfs, findPath, weightedBfs } from "./traverse.js";
+function stampFor(provider, resolutionFloor) {
+    return { ...provider.baseStamp(), resolutionFloor };
+}
+function result(provider, data, resolutionFloor, truncated, notes) {
+    if (truncated) {
+        notes.push("The node budget was reached, so this answer is partial. Nodes beyond the budget " +
+            "were not examined and are not reported as clean.");
+    }
+    return { data, stamp: stampFor(provider, resolutionFloor), truncated, notes };
+}
+/** Resolves reached ids to nodes, dropping any the provider no longer has. */
+function hydrate(provider, reached) {
+    const out = [];
+    for (const entry of reached) {
+        const node = provider.node(entry.id);
+        if (node !== undefined)
+            out.push({ node, depth: entry.depth, score: entry.score });
+    }
+    return out;
+}
+export function impactOf(provider, seeds, options = {}) {
+    const outcome = weightedBfs(provider, seeds, {
+        direction: "in",
+        ...options,
+        ...(options.weightFor === undefined ? {} : { weightFor: options.weightFor }),
+    });
+    // Direction is `in` by default and that is not a typo: "what breaks if this
+    // changes" walks from the changed node to its *callers*, not its callees. A
+    // function's dependencies are unaffected by it changing; its dependents are
+    // the blast radius.
+    const notes = [];
+    if (outcome.resolutionFloor <= 1) {
+        notes.push(`This blast radius rests on edges resolved no better than R${outcome.resolutionFloor}. ` +
+            "Cross-file calls are not reliably resolved at that level, so the radius is a " +
+            "lower bound rather than a complete answer.");
+    }
+    return result(provider, hydrate(provider, outcome.reached), outcome.resolutionFloor, outcome.truncated, notes);
+}
+/**
+ * Incidents correlated with a node, by graph edges only.
+ *
+ * **Incomplete by design in this build, and the caller is told so.** §11.9's
+ * root-cause query is "incident **plus embedding match**", and this build has no
+ * vector store — `embeddings` is a pointer table, since §8.2 keeps vectors in
+ * pgvector or a local extension and a column of serialised floats with no index
+ * is a scan rather than a search.
+ *
+ * So this answers the structural half and discloses the other. Returning it
+ * silently as "root cause search" would report "we found no similar incident"
+ * when the truth is "we did not look the way we said we would" — §20.2 keeps
+ * those in different categories for a reason.
+ */
+export function rootCauseSearch(provider, nodeId) {
+    const types = ["INCIDENT_CORRELATED", "FIXED_BY"];
+    const matches = [];
+    let floor = 4;
+    for (const edge of [...provider.incoming(nodeId, { types }), ...provider.outgoing(nodeId, { types })]) {
+        const otherId = edge.from === nodeId ? edge.to : edge.from;
+        const node = provider.node(otherId);
+        if (node === undefined)
+            continue;
+        if (node.type !== "INCIDENT" && node.type !== "FIX_PATTERN")
+            continue;
+        if (edge.resolution < floor)
+            floor = edge.resolution;
+        matches.push({ incident: node, via: edge.type });
+    }
+    return result(provider, matches, floor, false, [
+        "Structural incident links only. Embedding similarity was not run — this build has no " +
+            "vector store (§8.2), so a similar past incident with no graph edge to this node will " +
+            "not appear here. Absence is not evidence.",
+    ]);
+}
+// ---------------------------------------------------------------------------
+// 3. Test discovery — "what tests cover this?"
+// ---------------------------------------------------------------------------
+export function testsCovering(provider, nodeId, options = {}) {
+    // `TESTS` edges inward, transitively: a test covering a handler also covers
+    // what the handler calls, and stopping at depth 1 would report a changed
+    // helper as untested when a test does exercise it.
+    const outcome = bfs(provider, [nodeId], {
+        direction: "in",
+        types: ["TESTS", "CALLS"],
+        maxDepth: options.maxDepth ?? 3,
+        ...(options.budget === undefined ? {} : { budget: options.budget }),
+    });
+    const tests = hydrate(provider, outcome.reached)
+        .map((r) => r.node)
+        .filter((n) => n.type === "TEST_CASE");
+    const notes = [];
+    if (outcome.resolutionFloor <= 1) {
+        notes.push(`Test discovery rests on R${outcome.resolutionFloor} edges. At that level cross-file calls ` +
+            "are unresolved, so tests reaching this node indirectly may be missing from this list.");
+    }
+    if (tests.length === 0) {
+        notes.push("No covering test was found. That is not the same as this code being untested — it may " +
+            "be exercised by a test the adapter could not link.");
+    }
+    return result(provider, tests, outcome.resolutionFloor, outcome.truncated, notes);
+}
+// ---------------------------------------------------------------------------
+// 4. Data flow — "where does this field end up?"
+// ---------------------------------------------------------------------------
+/**
+ * The four edge types that carry data rather than control.
+ *
+ * Exported because a caller that discloses *what it walked* must name the same
+ * list this walk uses. A second copy in the MCP tool would drift, and the note
+ * would then describe a walk that did not run — the report-the-run rule applied
+ * to a constant instead of to a header.
+ */
+export const DATA_FLOW_EDGE_TYPES = ["PROPAGATES_TO", "READS", "WRITES", "RETURNS"];
+export function dataFlowFrom(provider, nodeId, options = {}) {
+    const outcome = bfs(provider, [nodeId], {
+        direction: "out",
+        types: [...DATA_FLOW_EDGE_TYPES],
+        ...options,
+    });
+    const notes = [];
+    if (outcome.resolutionFloor < 3) {
+        // §11A.6: data propagation compares *shapes*, not names, and shapes are an
+        // R3 capability. Below it the chain is path-level at best.
+        notes.push(`Field-level propagation requires R3; the edges here reach only R${outcome.resolutionFloor}. ` +
+            "This is a path-level answer — where data can flow, not which field arrives where.");
+    }
+    return result(provider, hydrate(provider, outcome.reached), outcome.resolutionFloor, outcome.truncated, notes);
+}
+// ---------------------------------------------------------------------------
+// 5. API tracing — "how does this work end to end?"
+// ---------------------------------------------------------------------------
+export function traceApi(provider, fromNodeId, toNodeId, options = {}) {
+    const edges = findPath(provider, fromNodeId, toNodeId, { direction: "both", ...options });
+    const ids = edges.length === 0 ? [] : [fromNodeId];
+    for (const e of edges) {
+        // Each hop may be traversed in either direction, so the far end is
+        // whichever of the two is not wherever the walk actually is right now —
+        // tracked from `ids` itself, not re-derived from the previous edge's own
+        // `.to`, which is only correct when every hop happens to go forward.
+        // `direction: "both"` exists precisely so a hop can go either way (e.g.
+        // an incoming SERVES_API followed by an outgoing CALLS), and the old
+        // `edges[i - 1]!.to` comparison silently re-picked the node just left
+        // whenever the previous hop was traversed backward, duplicating it in
+        // the path instead of advancing.
+        const current = ids[ids.length - 1];
+        ids.push(e.from === current ? e.to : e.from);
+    }
+    const path = [];
+    for (const id of ids) {
+        const node = provider.node(id);
+        if (node !== undefined)
+            path.push(node);
+    }
+    let floor = 4;
+    for (const edge of edges)
+        if (edge.resolution < floor)
+            floor = edge.resolution;
+    const notes = edges.length === 0
+        ? ["No path found. The two nodes may be genuinely unconnected, or connected only by " +
+                "edges this resolution level cannot resolve."]
+        : [];
+    return result(provider, { path, hops: edges.length }, floor, false, notes);
+}
+/**
+ * The scoped subgraph, ranked, intersected with `TESTS` edges.
+ *
+ * The ranking weights are Step 12's; this composes the primitives so that step
+ * supplies a weight function rather than a second traversal.
+ */
+export function changeRisk(provider, changed, options = {}) {
+    const impact = impactOf(provider, changed, options);
+    const tests = new Map();
+    const untested = [];
+    for (const entry of impact.data) {
+        if (entry.node.type === "TEST_CASE")
+            continue;
+        const covering = provider.incoming(entry.node.id, { types: ["TESTS"] });
+        if (covering.length === 0) {
+            untested.push(entry.node);
+            continue;
+        }
+        for (const edge of covering) {
+            const test = provider.node(edge.from);
+            if (test !== undefined)
+                tests.set(test.id, test);
+        }
+    }
+    const notes = [...impact.notes];
+    if (untested.length > 0) {
+        // §20.2's "not tested" category, populated rather than implied. This list is
+        // the honest half of the answer — the part a passing test run cannot cover.
+        notes.push(`${untested.length} affected node(s) have no covering test in the graph and cannot be ` +
+            "verified by re-running the suite.");
+    }
+    return {
+        data: { affected: impact.data, tests: [...tests.values()], untested },
+        stamp: impact.stamp,
+        truncated: impact.truncated,
+        notes,
+    };
+}
+/**
+ * `CHANGES_WITH` edges touching one `FILE` node, in either direction.
+ *
+ * `CHANGES_WITH` is symmetric but stored once, `from` the lexicographically
+ * smaller path (DEC-036) — reading only `provider.outgoing` would silently
+ * miss every pair where this file sorts second. Both `outgoing` and
+ * `incoming` are read here so the caller never has to know which side of the
+ * pair this file landed on; `traverse.ts`'s `neighbours()` does the identical
+ * thing for `direction: "both"`, but a one-hop, unscored list is what this
+ * question actually asks — walking it through `bfs` would return `Reached`
+ * entries with no `support`/`confidence` to report, since those live in
+ * `attrs`, not in the traversal primitives' own `Reached` shape.
+ *
+ * Answers only what the stored graph holds: co-change is windowed by however
+ * far back the git source read (`GitSourceOptions`, not this function's
+ * concern), and a pair below `minSupport`/`minConfidence` at ingest time
+ * never became an edge at all — silence here does not mean the files never
+ * changed together, only that they did not clear the threshold recorded when
+ * the graph was built.
+ */
+export function changesWith(provider, nodeId) {
+    const edges = [
+        ...provider.outgoing(nodeId, { types: ["CHANGES_WITH"] }),
+        ...provider.incoming(nodeId, { types: ["CHANGES_WITH"] }),
+    ];
+    const byOther = new Map();
+    let floor = 4;
+    for (const edge of edges) {
+        const otherId = edge.from === nodeId ? edge.to : edge.from;
+        if (otherId === nodeId)
+            continue; // Self-pairs cannot occur (source dedupes per commit), guarded anyway.
+        const node = provider.node(otherId);
+        if (node === undefined)
+            continue;
+        if (edge.resolution < floor)
+            floor = edge.resolution;
+        const support = typeof edge.attrs?.["support"] === "number" ? edge.attrs["support"] : 0;
+        byOther.set(otherId, { node, support, confidence: edge.confidence });
+    }
+    const data = [...byOther.values()].sort((a, b) => b.support - a.support || a.node.id.localeCompare(b.node.id));
+    const notes = [];
+    if (data.length === 0) {
+        notes.push("No CHANGES_WITH edge touches this node. That may mean the file has no co-change history " +
+            "above the recorded support/confidence thresholds, or that git history was skipped when " +
+            "the graph was built — this query cannot tell the two apart from the graph alone.");
+    }
+    return result(provider, data, edges.length === 0 ? 0 : floor, false, notes);
+}
+//# sourceMappingURL=queries.js.map

package/dist/query/queries.js.map

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

package/dist/query/refusal-fetch.d.ts

@@ -0,0 +1,114 @@
+/**
+ * The backing for `refusal_fetch` — `ai-tool-contract.md` §5.4, §8 endpoint 14.
+ *
+ * ## The premise this corrects
+ *
+ * `ai-layer-plan.md` §3 originally claimed this tool was cheap because
+ * "`askableHandle` exists in core and nothing serves it." Checked against
+ * `refusal-questions.ts` rather than taken on the plan's word, both halves
+ * were false: `askableHandle` is the *askable predicate* — `blockedBy` only
+ * for `refusalClass === "value-unknown"`, `null` for `capability-gap` /
+ * `out-of-scope` / `varies-per-call` / unset — and it is already served, by
+ * `packages/mcp/src/tools/questions.ts` via `groupRefusalsIntoQuestions`.
+ * The contract's own §5.4 records the correction; this module is the new
+ * work it points at.
+ *
+ * ## Why `groupRefusalsIntoQuestions` cannot be reused here
+ *
+ * That grouper drops every row that is not `value-unknown` **by design** —
+ * correct for its own purpose (a question queue only wants rows a human
+ * sentence can close), wrong for this one. A `refusal_fetch` that silently
+ * returned only the askable subset would be the empty-denominator defect
+ * (`ai-tool-contract.md` §1's "count over something that was not there,
+ * presented as a count of zero") wearing technique 4's clothes — the same
+ * defect class this project has already hit three times elsewhere
+ * (shopizer's 0-of-370 route count, airbyte's "not on disk", koa's silent
+ * `routers.size === 0`). This module therefore counts and pages **every**
+ * `UnresolvedRef`, of every `refusalClass` and unset alike.
+ *
+ * ## Call-site trap, named so it is not rediscovered the expensive way
+ *
+ * `store/reader.ts#unresolvedRefs` defaults `classified: true`, which
+ * restricts to `attrs IS NOT NULL` — exactly the rows a producer has
+ * classified at all. A caller that wires this module up to that reader
+ * without passing `{ classified: false }` will silently exclude every
+ * *unclassified* row from `count`, reproducing the same defect this module
+ * exists to prevent, one call site later. `summariseRefusals`/
+ * `fetchRefusalPage` cannot detect that mistake — they only know the
+ * population they were handed — so the honesty of `count` here is only as
+ * good as the completeness of what a caller passes in.
+ *
+ * ## The handle
+ *
+ * Stateless and self-describing (a base64url-encoded cursor plus a content
+ * fingerprint of the population it was issued against), not a session-cache
+ * lookup — so redemption is correct across process restarts and does not
+ * need this module to keep anything in memory between calls. An MCP surface
+ * that wants a prettier, shorter token (the contract's own illustrative
+ * `ref_9f2c1a`) is free to wrap this in a session cache; that is a
+ * presentation choice for P27, not a correctness requirement for this
+ * module.
+ *
+ * `UnresolvedRef` carries no stable id once it has crossed the store
+ * boundary (`store/reader.ts#toUnresolvedRef` does not carry the row's
+ * content-hash `id` column into the IR shape), so this module derives its
+ * own deterministic ordering key from the fields the type does carry. That
+ * key is what makes "same handle + same underlying population → same page
+ * ordering every time" true regardless of what order the caller's array
+ * happens to be in — a concatenation from several producers, or a
+ * differently-ordered SQL read, must not change which row lands on which
+ * page.
+ *
+ * Redeeming a handle that cannot be decoded, or whose population fingerprint
+ * no longer matches what is being read, is `refused` with a named reason —
+ * never a page that happens to be empty, and never a page silently drawn
+ * from the wrong cursor position. That is the rule the whole contract rests
+ * on (§1: `refused` is a fact about Descry, never a guess dressed as one),
+ * and this endpoint is the easiest place in the system to violate it
+ * silently.
+ */
+import type { ResultState, UnresolvedRef } from "@descryy/ir";
+/** `refusals` in the envelope (`ai-tool-contract.md` §5.4): `{ count, exemplar, handle }`. */
+export interface RefusalSummary {
+    /** The honest denominator — every row in the population handed in, computed before any page cap. */
+    readonly count: number;
+    /** One row's `reason`, passed through unmodified — never re-worded, templated or truncated (contract §4). `null` only when `count === 0`. */
+    readonly exemplar: string | null;
+    /** Opaque; redeem with {@link fetchRefusalPage}. `null` only when `count === 0` — there is nothing to page through. */
+    readonly handle: string | null;
+}
+/**
+ * Summarise a population of refusal rows into the one-line shape the
+ * envelope carries. `refs` must already be the complete population the
+ * caller intends to disclose — see the module header's call-site trap for
+ * the classic way to under-supply it.
+ */
+export declare function summariseRefusals(refs: readonly UnresolvedRef[], pageSize?: number): RefusalSummary;
+export interface RefusalPageOk {
+    readonly state: Extract<ResultState, "ok">;
+    readonly items: readonly UnresolvedRef[];
+    /** The honest total, restated on every page — the truncation rule pointed the other way (contract §5.5). */
+    readonly total: number;
+    /** Redeem for the next page. `null` on the last page. */
+    readonly nextHandle: string | null;
+}
+export interface RefusalPageRefused {
+    readonly state: Extract<ResultState, "refused">;
+    /** Named and specific — never a generic "invalid handle" with nothing to act on. */
+    readonly reason: string;
+}
+export type RefusalPage = RefusalPageOk | RefusalPageRefused;
+/**
+ * Redeem a handle against the current population. `refs` need not be
+ * pre-sorted or supplied in the same order as the call that minted the
+ * handle — ordering is re-derived deterministically every time.
+ *
+ * Three distinct ways to be `refused`, each named: the handle cannot be
+ * decoded at all; the population's content fingerprint no longer matches
+ * (the graph moved since the handle was issued); or the cursor position the
+ * handle names does not exist in the current population (only reachable via
+ * a handle not issued by this module's own chain, since a well-formed
+ * `nextHandle` is never offered past the end).
+ */
+export declare function fetchRefusalPage(refs: readonly UnresolvedRef[], handle: string): RefusalPage;
+//# sourceMappingURL=refusal-fetch.d.ts.map

package/dist/query/refusal-fetch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"refusal-fetch.d.ts","sourceRoot":"","sources":["../../src/query/refusal-fetch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoEG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AA8E9D,8FAA8F;AAC9F,MAAM,WAAW,cAAc;IAC7B,oGAAoG;IACpG,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,6IAA6I;IAC7I,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,uHAAuH;IACvH,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,SAAS,aAAa,EAAE,EAC9B,QAAQ,GAAE,MAA0B,GACnC,cAAc,CAgBhB;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC,WAAW,EAAE,IAAI,CAAC,CAAC;IAC3C,QAAQ,CAAC,KAAK,EAAE,SAAS,aAAa,EAAE,CAAC;IACzC,4GAA4G;IAC5G,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,yDAAyD;IACzD,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CACpC;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC,WAAW,EAAE,SAAS,CAAC,CAAC;IAChD,oFAAoF;IACpF,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,MAAM,WAAW,GAAG,aAAa,GAAG,kBAAkB,CAAC;AAE7D;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,SAAS,aAAa,EAAE,EAAE,MAAM,EAAE,MAAM,GAAG,WAAW,CAoC5F"}