@descryy/core 0.1.0

package/dist/query/refusal-fetch.js

@@ -0,0 +1,200 @@
+/**
+ * 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 { createHash } from "node:crypto";
+const DEFAULT_PAGE_SIZE = 50;
+const HANDLE_VERSION = 1;
+const HANDLE_PREFIX = "ref_";
+function isHandlePayload(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const v = value;
+    return (typeof v["v"] === "number" &&
+        typeof v["offset"] === "number" &&
+        typeof v["pageSize"] === "number" &&
+        typeof v["populationHash"] === "string");
+}
+/**
+ * A deterministic ordering key for one refusal row, built from every field
+ * `UnresolvedRef` carries except `attrs` — the same fields the store's own
+ * `unresolved_refs.id` content hash is built from (`schema.ts`'s own
+ * comment: classification is not part of what makes two refusals the same
+ * refusal). Restated here rather than imported, because the store's `id`
+ * never crosses into the `UnresolvedRef` shape this module receives.
+ */
+function sortKey(ref) {
+    return [
+        ref.fromNodeId,
+        ref.edgeType,
+        ref.rawTarget,
+        ref.file ?? "",
+        ref.line === null ? "" : String(ref.line),
+        ref.producedBy,
+        ref.reason,
+    ].join("|");
+}
+function orderedBy(refs) {
+    return [...refs].sort((a, b) => {
+        const ka = sortKey(a);
+        const kb = sortKey(b);
+        return ka < kb ? -1 : ka > kb ? 1 : 0;
+    });
+}
+/** A content fingerprint of the whole ordered population — the identity check that turns a
+ *  graph change between "summarise" and "fetch" into an honest `refused` rather than a wrong page. */
+function populationHash(ordered) {
+    const h = createHash("sha256");
+    for (const ref of ordered) {
+        h.update(sortKey(ref));
+        h.update("|");
+    }
+    return h.digest("hex");
+}
+function encodeHandle(payload) {
+    return HANDLE_PREFIX + Buffer.from(JSON.stringify(payload), "utf8").toString("base64url");
+}
+function decodeHandle(handle) {
+    if (!handle.startsWith(HANDLE_PREFIX))
+        return null;
+    try {
+        const json = Buffer.from(handle.slice(HANDLE_PREFIX.length), "base64url").toString("utf8");
+        const parsed = JSON.parse(json);
+        return isHandlePayload(parsed) ? parsed : null;
+    }
+    catch {
+        return 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 function summariseRefusals(refs, pageSize = DEFAULT_PAGE_SIZE) {
+    if (refs.length === 0) {
+        return { count: 0, exemplar: null, handle: null };
+    }
+    const ordered = orderedBy(refs);
+    const hash = populationHash(ordered);
+    return {
+        count: refs.length,
+        exemplar: ordered[0].reason,
+        handle: encodeHandle({
+            v: HANDLE_VERSION,
+            offset: 0,
+            pageSize: Math.max(1, Math.floor(pageSize)),
+            populationHash: hash,
+        }),
+    };
+}
+/**
+ * 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 function fetchRefusalPage(refs, handle) {
+    const payload = decodeHandle(handle);
+    if (payload === null) {
+        return {
+            state: "refused",
+            reason: `refusal_fetch handle "${handle}" cannot be decoded — it was not issued by summariseRefusals/fetchRefusalPage, or it is corrupted`,
+        };
+    }
+    const ordered = orderedBy(refs);
+    const hash = populationHash(ordered);
+    if (hash !== payload.populationHash) {
+        return {
+            state: "refused",
+            reason: "the refusal ledger has changed since this handle was issued (rows added, removed or reclassified) — " +
+                "re-fetch from a fresh summary rather than trusting this page",
+        };
+    }
+    if (payload.offset < 0 || payload.offset >= ordered.length) {
+        return {
+            state: "refused",
+            reason: `this handle's cursor position (${payload.offset}) does not exist in a ledger of ${ordered.length} row(s)`,
+        };
+    }
+    const pageSize = Math.max(1, Math.floor(payload.pageSize));
+    const items = ordered.slice(payload.offset, payload.offset + pageSize);
+    const nextOffset = payload.offset + items.length;
+    const nextHandle = nextOffset < ordered.length
+        ? encodeHandle({ v: HANDLE_VERSION, offset: nextOffset, pageSize, populationHash: hash })
+        : null;
+    return { state: "ok", items, total: ordered.length, nextHandle };
+}
+//# sourceMappingURL=refusal-fetch.js.map

package/dist/query/refusal-fetch.js.map

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

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

@@ -0,0 +1,123 @@
+/**
+ * The grouper — turns classified refusal rows into questions a person can
+ * actually answer.
+ *
+ * DEC-242 gave `UnresolvedRef` a machine-readable handle (`attrs.blockedBy`)
+ * and a producer-declared answerability class (`attrs.refusalClass`). Neither
+ * one is a question by itself: a ledger of 136 rows is still 136 rows until
+ * something collapses the ones that share a cause into one thing to ask.
+ * That collapse is all this module does.
+ *
+ * ## The filter is the whole point
+ *
+ * Only `"value-unknown"` rows become questions. `"capability-gap"`,
+ * `"out-of-scope"`, `"varies-per-call"` and **unset** never do — DEC-242's own
+ * measurement is why: 92 of 95 real C#/Java refusal rows are
+ * `"capability-gap"`, and asking a human to resolve one of those, or a
+ * `"varies-per-call"` row (*"what is `url`?"*), is a category error, not an
+ * unanswered question. Unset is the sharpest trap: it looks identical to
+ * `"value-unknown"` in shape (a row, a `rawTarget`, a `reason`) and is
+ * silently the majority case until every producer sets the field. Defaulting
+ * it to askable is exactly how an unaudited row reaches a user.
+ *
+ * ## Grouping key is `(repo, blockedBy)`, and this file only ever sees one repo
+ *
+ * `env.BACKEND_API_BASE_URL` in `sherpa-cf-worker` and the byte-identical
+ * string in a different repository are different facts about different
+ * runtimes — DEC-223 §3 already committed to exact-match scoped to one repo,
+ * and measured the failure mode directly (both repos use the same env var
+ * name for different backends). `groupRefusalsIntoQuestions` takes one repo's
+ * rows and returns that repo's questions; it has no way to merge across
+ * repos because it never sees more than one. `groupRefusalsAcrossRepos` is the
+ * only entry point that touches more than one repo's rows, and it keeps them
+ * in separate groups by construction — see its own doc for what that means in
+ * practice, and the test that proves it.
+ *
+ * ## What this does not do
+ *
+ * It does not run config resolution. DEC-242's ordering constraint —
+ * `refusalClass` is assigned only after a producer checks `.env` files,
+ * deploy config and the like — is the producer's job, upstream of this
+ * module entirely. A `"value-unknown"` row reaching here is trusted at face
+ * value; second-guessing it here would duplicate work a producer already did
+ * or silently paper over one that skipped it, and neither is this module's
+ * business to detect.
+ *
+ * It does not store, dedupe against a previously-answered `ConfirmedFact`
+ * (DEC-223 §3), or decide where a question surfaces. It is the piece in
+ * between: rows in, questions out, with everything dropped along the way
+ * counted rather than discarded.
+ */
+import type { UnresolvedRef } from "@descryy/ir";
+/** One call site behind a question — enough for a reader to go look, not just a count. */
+export interface RefusalSite {
+    readonly fromNodeId: string;
+    readonly file: string | null;
+    readonly line: number | null;
+    /** The callee text, unchanged from the row — `fetch`, `api.get`. */
+    readonly rawTarget: string;
+}
+/** One question: "what does `blockedBy` evaluate to, in `repo`?" (DEC-223 §2), plus its evidence. */
+export interface RefusalQuestion {
+    readonly repo: string;
+    readonly blockedBy: string;
+    readonly sites: readonly RefusalSite[];
+}
+/**
+ * What every accepted row not made into a question was instead, one bucket
+ * per cause. Never a single "dropped" count — `dropped["unset"]` and
+ * `dropped["capability-gap"]` are different facts with different remedies,
+ * and collapsing them would recreate the conflation DEC-223's own
+ * `query/unresolved.ts` header already measured once.
+ *
+ * `"value-unknown-no-handle"` is its own bucket rather than folded into
+ * `"value-unknown"`: a row can legally declare itself askable while naming no
+ * expression to ask about (`attrs.blockedBy` absent or `null`, DEC-242) — a
+ * producer contradiction, not the same thing as a row this module correctly
+ * turned into a question, and not the same thing as a row a producer
+ * correctly marked unanswerable either.
+ */
+export interface RefusalDropCounts {
+    readonly [refusalClass: string]: number;
+}
+export interface GroupingResult {
+    readonly repo: string;
+    readonly totalRows: number;
+    readonly questions: readonly RefusalQuestion[];
+    readonly dropped: RefusalDropCounts;
+}
+/**
+ * The askable predicate, exported so a second consumer (DEC-244's
+ * `applyDeclaredValues`) does not re-derive it a third time — `unresolved.ts`
+ * and this file already had one independent copy each before DEC-244, and a
+ * third divergent copy is exactly the drift DEC-098's own guard-omission
+ * incident (§3.1) named. Returns the row's `blockedBy` when, and only when,
+ * this row is `"value-unknown"` with a non-empty handle to ask about — `null`
+ * for every other case, unset included.
+ */
+export declare function askableHandle(ref: UnresolvedRef): string | null;
+/**
+ * Group one repository's refusal rows into questions.
+ *
+ * The reconciliation this makes checkable: every row in `refs` is accounted
+ * for in exactly one place — a site under some question's `sites`, or a count
+ * under `dropped` — so `totalRows === sum(dropped) + sum(questions[].sites.length)`
+ * always. The DEC-241-shaped law, one level down again.
+ */
+export declare function groupRefusalsIntoQuestions(repo: string, refs: readonly UnresolvedRef[]): GroupingResult;
+/**
+ * Group several repositories' rows without ever merging across them.
+ *
+ * This exists because the risk this module guards against is a *caller's*
+ * mistake, not this file's: nothing stops a consumer from concatenating two
+ * repos' `unresolved` arrays before calling `groupRefusalsIntoQuestions` once,
+ * and a byte-identical `blockedBy` string would then merge two unrelated
+ * facts into one question (DEC-223 §3's measured failure). This function is
+ * the version of the API where that mistake cannot be made — one
+ * `GroupingResult` per repo, always, however many repos come in.
+ */
+export declare function groupRefusalsAcrossRepos(inputs: readonly {
+    readonly repo: string;
+    readonly refs: readonly UnresolvedRef[];
+}[]): readonly GroupingResult[];
+//# sourceMappingURL=refusal-questions.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"refusal-questions.d.ts","sourceRoot":"","sources":["../../src/query/refusal-questions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD,0FAA0F;AAC1F,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,oEAAoE;IACpE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,qGAAqG;AACrG,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,SAAS,WAAW,EAAE,CAAC;CACxC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAAC;CACzC;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,SAAS,eAAe,EAAE,CAAC;IAC/C,QAAQ,CAAC,OAAO,EAAE,iBAAiB,CAAC;CACrC;AAYD;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,aAAa,GAAG,MAAM,GAAG,IAAI,CAE/D;AAED;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CACxC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,SAAS,aAAa,EAAE,GAC7B,cAAc,CA6BhB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,SAAS;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,SAAS,aAAa,EAAE,CAAA;CAAE,EAAE,GACpF,SAAS,cAAc,EAAE,CAE3B"}

package/dist/query/refusal-questions.js

@@ -0,0 +1,122 @@
+/**
+ * The grouper — turns classified refusal rows into questions a person can
+ * actually answer.
+ *
+ * DEC-242 gave `UnresolvedRef` a machine-readable handle (`attrs.blockedBy`)
+ * and a producer-declared answerability class (`attrs.refusalClass`). Neither
+ * one is a question by itself: a ledger of 136 rows is still 136 rows until
+ * something collapses the ones that share a cause into one thing to ask.
+ * That collapse is all this module does.
+ *
+ * ## The filter is the whole point
+ *
+ * Only `"value-unknown"` rows become questions. `"capability-gap"`,
+ * `"out-of-scope"`, `"varies-per-call"` and **unset** never do — DEC-242's own
+ * measurement is why: 92 of 95 real C#/Java refusal rows are
+ * `"capability-gap"`, and asking a human to resolve one of those, or a
+ * `"varies-per-call"` row (*"what is `url`?"*), is a category error, not an
+ * unanswered question. Unset is the sharpest trap: it looks identical to
+ * `"value-unknown"` in shape (a row, a `rawTarget`, a `reason`) and is
+ * silently the majority case until every producer sets the field. Defaulting
+ * it to askable is exactly how an unaudited row reaches a user.
+ *
+ * ## Grouping key is `(repo, blockedBy)`, and this file only ever sees one repo
+ *
+ * `env.BACKEND_API_BASE_URL` in `sherpa-cf-worker` and the byte-identical
+ * string in a different repository are different facts about different
+ * runtimes — DEC-223 §3 already committed to exact-match scoped to one repo,
+ * and measured the failure mode directly (both repos use the same env var
+ * name for different backends). `groupRefusalsIntoQuestions` takes one repo's
+ * rows and returns that repo's questions; it has no way to merge across
+ * repos because it never sees more than one. `groupRefusalsAcrossRepos` is the
+ * only entry point that touches more than one repo's rows, and it keeps them
+ * in separate groups by construction — see its own doc for what that means in
+ * practice, and the test that proves it.
+ *
+ * ## What this does not do
+ *
+ * It does not run config resolution. DEC-242's ordering constraint —
+ * `refusalClass` is assigned only after a producer checks `.env` files,
+ * deploy config and the like — is the producer's job, upstream of this
+ * module entirely. A `"value-unknown"` row reaching here is trusted at face
+ * value; second-guessing it here would duplicate work a producer already did
+ * or silently paper over one that skipped it, and neither is this module's
+ * business to detect.
+ *
+ * It does not store, dedupe against a previously-answered `ConfirmedFact`
+ * (DEC-223 §3), or decide where a question surfaces. It is the piece in
+ * between: rows in, questions out, with everything dropped along the way
+ * counted rather than discarded.
+ */
+function classOf(ref) {
+    const cls = ref.attrs?.["refusalClass"];
+    return typeof cls === "string" ? cls : "unset";
+}
+function handleOf(ref) {
+    const blockedBy = ref.attrs?.["blockedBy"];
+    return typeof blockedBy === "string" && blockedBy !== "" ? blockedBy : null;
+}
+/**
+ * The askable predicate, exported so a second consumer (DEC-244's
+ * `applyDeclaredValues`) does not re-derive it a third time — `unresolved.ts`
+ * and this file already had one independent copy each before DEC-244, and a
+ * third divergent copy is exactly the drift DEC-098's own guard-omission
+ * incident (§3.1) named. Returns the row's `blockedBy` when, and only when,
+ * this row is `"value-unknown"` with a non-empty handle to ask about — `null`
+ * for every other case, unset included.
+ */
+export function askableHandle(ref) {
+    return classOf(ref) === "value-unknown" ? handleOf(ref) : null;
+}
+/**
+ * Group one repository's refusal rows into questions.
+ *
+ * The reconciliation this makes checkable: every row in `refs` is accounted
+ * for in exactly one place — a site under some question's `sites`, or a count
+ * under `dropped` — so `totalRows === sum(dropped) + sum(questions[].sites.length)`
+ * always. The DEC-241-shaped law, one level down again.
+ */
+export function groupRefusalsIntoQuestions(repo, refs) {
+    const groups = new Map();
+    const dropped = {};
+    const drop = (bucket) => {
+        dropped[bucket] = (dropped[bucket] ?? 0) + 1;
+    };
+    for (const ref of refs) {
+        const cls = classOf(ref);
+        if (cls !== "value-unknown") {
+            drop(cls);
+            continue;
+        }
+        const handle = askableHandle(ref);
+        if (handle === null) {
+            drop("value-unknown-no-handle");
+            continue;
+        }
+        const site = { fromNodeId: ref.fromNodeId, file: ref.file, line: ref.line, rawTarget: ref.rawTarget };
+        const existing = groups.get(handle);
+        if (existing === undefined)
+            groups.set(handle, [site]);
+        else
+            existing.push(site);
+    }
+    const questions = [...groups.entries()]
+        .map(([blockedBy, sites]) => ({ repo, blockedBy, sites: [...sites] }))
+        .sort((a, b) => b.sites.length - a.sites.length || a.blockedBy.localeCompare(b.blockedBy));
+    return { repo, totalRows: refs.length, questions, dropped };
+}
+/**
+ * Group several repositories' rows without ever merging across them.
+ *
+ * This exists because the risk this module guards against is a *caller's*
+ * mistake, not this file's: nothing stops a consumer from concatenating two
+ * repos' `unresolved` arrays before calling `groupRefusalsIntoQuestions` once,
+ * and a byte-identical `blockedBy` string would then merge two unrelated
+ * facts into one question (DEC-223 §3's measured failure). This function is
+ * the version of the API where that mistake cannot be made — one
+ * `GroupingResult` per repo, always, however many repos come in.
+ */
+export function groupRefusalsAcrossRepos(inputs) {
+    return inputs.map(({ repo, refs }) => groupRefusalsIntoQuestions(repo, refs));
+}
+//# sourceMappingURL=refusal-questions.js.map

package/dist/query/refusal-questions.js.map

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