@descryy/core 0.1.0

package/dist/query/unresolved.d.ts

@@ -0,0 +1,195 @@
+/**
+ * The refusal ledger is three populations, and reporting it as one produced a
+ * wrong number that a lane then reasoned from.
+ *
+ * ## The conflation
+ *
+ * `UnresolvedRef` records what an adapter saw and could not resolve, and
+ * everything filed there reads as a **gap**. Two unrelated things are filed:
+ *
+ * - An outbound call to a third party, **read perfectly**. There is no endpoint
+ *   in this workspace for it and there never will be. That is §20.2's *not
+ *   applicable* — a fact, not a gap.
+ * - A call against this workspace's own surface whose target is not statically
+ *   determinable. That is the gap, and it is *not analysable*.
+ *
+ * A read-rate census across nine repositories reported **90 edges read against
+ * 773 recognised-and-refused, a 10% read rate**, and concluded that `USES_API`
+ * resolution was the system's largest deficit. On one repository **115 of 163
+ * ledger rows are calls to Microsoft, Zoom, Hitpay and Zoho** — correctly
+ * refused, counted as deficit. The deficit there is real and it is 47%, not 20%.
+ *
+ * ## What running it on real code established, and it is not what was expected
+ *
+ * **`rawTarget` does not carry the target.** On the reference repository every
+ * one of the 64 `USES_API` refusals carries the *callee* — `"fetch"`,
+ * `"api.get"`, `"api.post"` — because the URL was an expression the adapter
+ * could not evaluate, and the expression text is not what gets filed. So the
+ * ledger **cannot** be split from stored data by any engine-side rule, and this
+ * module reports all 64 as `undetermined`, which is the correct answer and a
+ * useless one.
+ *
+ * The distinction nevertheless **already exists** — in `reason`, as prose. Two
+ * sentence forms account for all 64, and they split it exactly as a hand count
+ * of the source did:
+ *
+ * | `reason` says | count | what it means |
+ * | --- | --- | --- |
+ * | *"the path is not repository-relative"* | **39** | outbound. A fact |
+ * | *"the request path is not a literal or template"* | **25** | the gap |
+ *
+ * 39 + 25 = 64, and the independent hand count of that repository was 39 outbound
+ * and 25 genuinely unread. **The adapter knows which population a refusal is in
+ * and says so in a sentence.** Parsing that sentence is not an option: it is
+ * free text, it is written per producer, and a consumer that greps it breaks
+ * silently the first time one is reworded — the CRLF-stripper failure exactly.
+ *
+ * So the conclusion is the opposite of this module's premise: **the
+ * discriminator has to be a field**, and this module is the evidence for that
+ * rather than a substitute for it. It classifies what the text can carry, and
+ * discloses everything it cannot, which is what makes the gap measurable.
+ *
+ * ## Why the field is still not added here
+ *
+ * The `category` discriminator is the right end state and is deliberately **not**
+ * added here, for two reasons that are the same reason:
+ *
+ * 1. **No adapter would set it today.** Shipping a consumer that reads a carrier
+ *    no producer emits is exactly the defect DEC-112 names, and it has already
+ *    cost this project three checks that were dead on every real repository. A
+ *    field added ahead of its producer is a dead carrier however obviously
+ *    correct it looks — so the field lands with an adapter emitting it, not
+ *    before.
+ * 2. **The storage column needs the migration policy** that is still open
+ *    (architecture §32). An engine-side classifier needs neither, works on graphs
+ *    already written, and turns the IR change into a request backed by measured
+ *    populations rather than a speculative one.
+ *
+ * ## DEC-242 landed, and this module now defers to it where it can
+ *
+ * The heuristic above is what this module reasoned its way to before a
+ * discriminator field existed. It now does: `attrs.refusalClass` (DEC-242),
+ * producer-declared and persisted (the store gained a real `attrs` column
+ * for it — DEC-224). `classifyRefusal` checks `refusalClass === "out-of-scope"`
+ * first and trusts it outright, ahead of the text heuristic below — a
+ * producer that resolved the target and declared it out of scope did real
+ * analysis, which is better evidence than this module re-deriving the same
+ * fact from `rawTarget` text. DEC-242's other three classes
+ * (`value-unknown`, `capability-gap`, `varies-per-call`) answer a different
+ * question — whether a human sentence could close the row — and say nothing
+ * about scope, so they and an unset field both fall through to the
+ * unchanged heuristic rather than being read as "not out-of-scope." Every
+ * row written before DEC-242 shipped is graded exactly as it always was.
+ *
+ * The practical consequence, per DEC-242's own note: any future recall
+ * figure computed over `unresolved.length` must exclude `refusalClass ===
+ * "out-of-scope"` rows from its deficit denominator, the same way
+ * `readRate` below already excludes this module's own `outOfScope`
+ * verdict — measured at 3 of ~215 rows on the corpora checked so far
+ * (DEC-260), small today and not distorting any published number, but
+ * expressible now in a way it was not before the field existed.
+ *
+ * ## The third population is the point
+ *
+ * A ledger row whose target is a runtime value cannot be classified either way:
+ * `fetch(url)` may be outbound or internal and the text does not say. Several
+ * such rows on the census repository turned out to be outbound, discovered by
+ * hand. **So this returns three counts and refuses to return one rate.** Folding
+ * `undetermined` into either side is the same error one level down — the whole
+ * defect was a denominator that quietly absorbed a population it should have
+ * disclosed.
+ */
+import type { UnresolvedRef } from "@descryy/ir";
+/**
+ * `outOfScope` — read correctly, targets something this workspace does not
+ * serve. `unreadable` — recognised, target not determinable. `undetermined` —
+ * the evidence does not say, and pretending otherwise is what produced the
+ * wrong number in the first place.
+ */
+export type RefusalClass = "outOfScope" | "unreadable" | "undetermined";
+export interface RefusalScope {
+    /**
+     * Hosts this workspace serves. An absolute target on one of these is
+     * *internal* and therefore a genuine gap, not an outbound call.
+     *
+     * Empty means "no host is known to be ours", which is honest rather than
+     * convenient: with no known host every absolute target classifies as
+     * `outOfScope`, so a caller that has hosts and does not pass them will
+     * understate its own deficit. `classifyRefusals` reports `scopeKnown` so that
+     * cannot happen silently.
+     */
+    readonly internalHosts?: readonly string[];
+}
+/**
+ * Classify one refusal.
+ *
+ * **A producer's own `attrs.refusalClass: "out-of-scope"` (DEC-242) is
+ * trusted directly, ahead of everything below.** DEC-242 landed after this
+ * module's own heuristic did, and it is strictly better evidence for the same
+ * question: a producer that read the call, resolved the target, and declared
+ * it out of scope did real analysis (Lane F's DEC-260 origin check, for one),
+ * where this module's `hostOf`/`isOpaque` pair is inference from `rawTarget`
+ * text alone. Rule 3's "declared beats re-derived" reordering, not a new rule.
+ *
+ * **A row with no `refusalClass`, or one of DEC-242's other three values
+ * (`value-unknown`, `capability-gap`, `varies-per-call`), falls through to
+ * the text heuristic unchanged — a deliberate choice, not an oversight.**
+ * Those three classes answer "is a human sentence enough to close this row,"
+ * a different question from "is this target inside or outside the
+ * workspace," and none of them says a row is or is not out of scope; reading
+ * absence as "therefore not out-of-scope" would be exactly the silent
+ * behaviour change this module's own module-header history warns against.
+ * Every row written before DEC-242 shipped, and every row a producer has not
+ * classified yet, is graded identically to how it always was.
+ *
+ * **Below that: absolute target on a host that is not ours → `outOfScope`.**
+ * The only positive classification made here from text alone, so it is as
+ * reliable as the text. Everything else is `unreadable` when it looks like a
+ * path this workspace could serve, and `undetermined` when the target says
+ * nothing about where the call goes.
+ */
+export declare function classifyRefusal(ref: UnresolvedRef, scope?: RefusalScope): RefusalClass;
+export interface RefusalCensus {
+    readonly total: number;
+    readonly outOfScope: number;
+    readonly unreadable: number;
+    readonly undetermined: number;
+    /**
+     * False when the caller supplied no internal hosts. Every absolute target is
+     * then `outOfScope`, which **understates the deficit**, and a report that does
+     * not say so is making a claim it cannot support.
+     */
+    readonly scopeKnown: boolean;
+    /** Hosts seen on absolute targets, most frequent first — the evidence for `internalHosts`. */
+    readonly hosts: readonly {
+        readonly host: string;
+        readonly count: number;
+    }[];
+}
+export declare function classifyRefusals(refs: readonly UnresolvedRef[], scope?: RefusalScope): RefusalCensus;
+/**
+ * Two rates and a disclosure, never one number.
+ *
+ * `overRecognised` is the census's original figure and it is kept because
+ * deleting a published number is worse than captioning it. `overInternal` is
+ * the one that describes the analyser's actual deficit. **Both are `null` when
+ * their denominator is zero** — `decisions()`'s rule, one level out: a rate over
+ * nothing is not 0% and not 100%, it is undefined, and returning a number there
+ * is how a dead component scores well.
+ */
+export interface ReadRate {
+    readonly read: number;
+    readonly census: RefusalCensus;
+    /** read / (read + every refusal). Understates the analyser by counting facts as gaps. */
+    readonly overRecognised: number | null;
+    /** read / (read + refusals that could plausibly be ours). The deficit that is actually ours. */
+    readonly overInternal: number | null;
+    /**
+     * Why the two differ, and what neither of them settles. Always non-empty when
+     * the numbers differ, because the gap between them is exactly the thing a
+     * single figure hid.
+     */
+    readonly disclosure: readonly string[];
+}
+export declare function readRate(read: number, refs: readonly UnresolvedRef[], scope?: RefusalScope): ReadRate;
+//# sourceMappingURL=unresolved.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"unresolved.d.ts","sourceRoot":"","sources":["../../src/query/unresolved.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoGG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG,YAAY,GAAG,YAAY,GAAG,cAAc,CAAC;AAExE,MAAM,WAAW,YAAY;IAC3B;;;;;;;;;OASG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC5C;AAiCD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,aAAa,EAAE,KAAK,GAAE,YAAiB,GAAG,YAAY,CAQ1F;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,8FAA8F;IAC9F,QAAQ,CAAC,KAAK,EAAE,SAAS;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CAC9E;AAED,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,SAAS,aAAa,EAAE,EAC9B,KAAK,GAAE,YAAiB,GACvB,aAAa,CAgBf;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,yFAAyF;IACzF,QAAQ,CAAC,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IACvC,gGAAgG;IAChG,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC;;;;OAIG;IACH,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;CACxC;AAED,wBAAgB,QAAQ,CACtB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,SAAS,aAAa,EAAE,EAC9B,KAAK,GAAE,YAAiB,GACvB,QAAQ,CAwCV"}

package/dist/query/unresolved.js

@@ -0,0 +1,225 @@
+/**
+ * The refusal ledger is three populations, and reporting it as one produced a
+ * wrong number that a lane then reasoned from.
+ *
+ * ## The conflation
+ *
+ * `UnresolvedRef` records what an adapter saw and could not resolve, and
+ * everything filed there reads as a **gap**. Two unrelated things are filed:
+ *
+ * - An outbound call to a third party, **read perfectly**. There is no endpoint
+ *   in this workspace for it and there never will be. That is §20.2's *not
+ *   applicable* — a fact, not a gap.
+ * - A call against this workspace's own surface whose target is not statically
+ *   determinable. That is the gap, and it is *not analysable*.
+ *
+ * A read-rate census across nine repositories reported **90 edges read against
+ * 773 recognised-and-refused, a 10% read rate**, and concluded that `USES_API`
+ * resolution was the system's largest deficit. On one repository **115 of 163
+ * ledger rows are calls to Microsoft, Zoom, Hitpay and Zoho** — correctly
+ * refused, counted as deficit. The deficit there is real and it is 47%, not 20%.
+ *
+ * ## What running it on real code established, and it is not what was expected
+ *
+ * **`rawTarget` does not carry the target.** On the reference repository every
+ * one of the 64 `USES_API` refusals carries the *callee* — `"fetch"`,
+ * `"api.get"`, `"api.post"` — because the URL was an expression the adapter
+ * could not evaluate, and the expression text is not what gets filed. So the
+ * ledger **cannot** be split from stored data by any engine-side rule, and this
+ * module reports all 64 as `undetermined`, which is the correct answer and a
+ * useless one.
+ *
+ * The distinction nevertheless **already exists** — in `reason`, as prose. Two
+ * sentence forms account for all 64, and they split it exactly as a hand count
+ * of the source did:
+ *
+ * | `reason` says | count | what it means |
+ * | --- | --- | --- |
+ * | *"the path is not repository-relative"* | **39** | outbound. A fact |
+ * | *"the request path is not a literal or template"* | **25** | the gap |
+ *
+ * 39 + 25 = 64, and the independent hand count of that repository was 39 outbound
+ * and 25 genuinely unread. **The adapter knows which population a refusal is in
+ * and says so in a sentence.** Parsing that sentence is not an option: it is
+ * free text, it is written per producer, and a consumer that greps it breaks
+ * silently the first time one is reworded — the CRLF-stripper failure exactly.
+ *
+ * So the conclusion is the opposite of this module's premise: **the
+ * discriminator has to be a field**, and this module is the evidence for that
+ * rather than a substitute for it. It classifies what the text can carry, and
+ * discloses everything it cannot, which is what makes the gap measurable.
+ *
+ * ## Why the field is still not added here
+ *
+ * The `category` discriminator is the right end state and is deliberately **not**
+ * added here, for two reasons that are the same reason:
+ *
+ * 1. **No adapter would set it today.** Shipping a consumer that reads a carrier
+ *    no producer emits is exactly the defect DEC-112 names, and it has already
+ *    cost this project three checks that were dead on every real repository. A
+ *    field added ahead of its producer is a dead carrier however obviously
+ *    correct it looks — so the field lands with an adapter emitting it, not
+ *    before.
+ * 2. **The storage column needs the migration policy** that is still open
+ *    (architecture §32). An engine-side classifier needs neither, works on graphs
+ *    already written, and turns the IR change into a request backed by measured
+ *    populations rather than a speculative one.
+ *
+ * ## DEC-242 landed, and this module now defers to it where it can
+ *
+ * The heuristic above is what this module reasoned its way to before a
+ * discriminator field existed. It now does: `attrs.refusalClass` (DEC-242),
+ * producer-declared and persisted (the store gained a real `attrs` column
+ * for it — DEC-224). `classifyRefusal` checks `refusalClass === "out-of-scope"`
+ * first and trusts it outright, ahead of the text heuristic below — a
+ * producer that resolved the target and declared it out of scope did real
+ * analysis, which is better evidence than this module re-deriving the same
+ * fact from `rawTarget` text. DEC-242's other three classes
+ * (`value-unknown`, `capability-gap`, `varies-per-call`) answer a different
+ * question — whether a human sentence could close the row — and say nothing
+ * about scope, so they and an unset field both fall through to the
+ * unchanged heuristic rather than being read as "not out-of-scope." Every
+ * row written before DEC-242 shipped is graded exactly as it always was.
+ *
+ * The practical consequence, per DEC-242's own note: any future recall
+ * figure computed over `unresolved.length` must exclude `refusalClass ===
+ * "out-of-scope"` rows from its deficit denominator, the same way
+ * `readRate` below already excludes this module's own `outOfScope`
+ * verdict — measured at 3 of ~215 rows on the corpora checked so far
+ * (DEC-260), small today and not distorting any published number, but
+ * expressible now in a way it was not before the field existed.
+ *
+ * ## The third population is the point
+ *
+ * A ledger row whose target is a runtime value cannot be classified either way:
+ * `fetch(url)` may be outbound or internal and the text does not say. Several
+ * such rows on the census repository turned out to be outbound, discovered by
+ * hand. **So this returns three counts and refuses to return one rate.** Folding
+ * `undetermined` into either side is the same error one level down — the whole
+ * defect was a denominator that quietly absorbed a population it should have
+ * disclosed.
+ */
+const ABSOLUTE = /^[a-zA-Z][a-zA-Z0-9+.-]*:\/\//;
+/** The host of an absolute target, lowercased and without a port; `null` if the target is not absolute. */
+function hostOf(rawTarget) {
+    if (!ABSOLUTE.test(rawTarget))
+        return null;
+    try {
+        return new URL(rawTarget).hostname.toLowerCase();
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * A target is **not** a literal path or URL if it carries no path-like evidence
+ * at all — a bare identifier, a call expression, a template with nothing fixed.
+ * These are the rows that cannot be classified, and they must stay visible.
+ */
+function isOpaque(rawTarget) {
+    const t = rawTarget.trim();
+    if (t === "")
+        return true;
+    // Looked absolute and had no parseable host — `https://` and friends. It says
+    // nothing about where the call goes, so it is opaque rather than internal.
+    // Reached only when `hostOf` has already returned null for it.
+    if (ABSOLUTE.test(t))
+        return true;
+    if (t.startsWith("/"))
+        return false;
+    // A bare `{param}` or `${...}` with no fixed segment says nothing about where
+    // the call goes. Anything containing a `/` outside a placeholder does.
+    const withoutPlaceholders = t.replace(/\$?\{[^}]*\}/g, "");
+    return !withoutPlaceholders.includes("/");
+}
+/**
+ * Classify one refusal.
+ *
+ * **A producer's own `attrs.refusalClass: "out-of-scope"` (DEC-242) is
+ * trusted directly, ahead of everything below.** DEC-242 landed after this
+ * module's own heuristic did, and it is strictly better evidence for the same
+ * question: a producer that read the call, resolved the target, and declared
+ * it out of scope did real analysis (Lane F's DEC-260 origin check, for one),
+ * where this module's `hostOf`/`isOpaque` pair is inference from `rawTarget`
+ * text alone. Rule 3's "declared beats re-derived" reordering, not a new rule.
+ *
+ * **A row with no `refusalClass`, or one of DEC-242's other three values
+ * (`value-unknown`, `capability-gap`, `varies-per-call`), falls through to
+ * the text heuristic unchanged — a deliberate choice, not an oversight.**
+ * Those three classes answer "is a human sentence enough to close this row,"
+ * a different question from "is this target inside or outside the
+ * workspace," and none of them says a row is or is not out of scope; reading
+ * absence as "therefore not out-of-scope" would be exactly the silent
+ * behaviour change this module's own module-header history warns against.
+ * Every row written before DEC-242 shipped, and every row a producer has not
+ * classified yet, is graded identically to how it always was.
+ *
+ * **Below that: absolute target on a host that is not ours → `outOfScope`.**
+ * The only positive classification made here from text alone, so it is as
+ * reliable as the text. Everything else is `unreadable` when it looks like a
+ * path this workspace could serve, and `undetermined` when the target says
+ * nothing about where the call goes.
+ */
+export function classifyRefusal(ref, scope = {}) {
+    if (ref.attrs?.["refusalClass"] === "out-of-scope")
+        return "outOfScope";
+    const internal = new Set((scope.internalHosts ?? []).map((h) => h.toLowerCase()));
+    const host = hostOf(ref.rawTarget);
+    if (host !== null)
+        return internal.has(host) ? "unreadable" : "outOfScope";
+    if (isOpaque(ref.rawTarget))
+        return "undetermined";
+    return "unreadable";
+}
+export function classifyRefusals(refs, scope = {}) {
+    const counts = { outOfScope: 0, unreadable: 0, undetermined: 0 };
+    const hosts = new Map();
+    for (const ref of refs) {
+        counts[classifyRefusal(ref, scope)] += 1;
+        const host = hostOf(ref.rawTarget);
+        if (host !== null)
+            hosts.set(host, (hosts.get(host) ?? 0) + 1);
+    }
+    return {
+        total: refs.length,
+        ...counts,
+        scopeKnown: (scope.internalHosts ?? []).length > 0,
+        hosts: [...hosts]
+            .map(([host, count]) => ({ host, count }))
+            .sort((a, b) => b.count - a.count || a.host.localeCompare(b.host)),
+    };
+}
+export function readRate(read, refs, scope = {}) {
+    const census = classifyRefusals(refs, scope);
+    const recognisedDenominator = read + census.total;
+    const internalDenominator = read + census.unreadable + census.undetermined;
+    const disclosure = [];
+    if (census.outOfScope > 0) {
+        disclosure.push(`${census.outOfScope} of ${census.total} refusals target a host this workspace does not serve. ` +
+            `They were read correctly and there is nothing here to resolve them to — "not applicable", not "not analysable". ` +
+            `Counting them as deficit is what made the published rate wrong.`);
+    }
+    if (census.undetermined > 0) {
+        disclosure.push(`${census.undetermined} refusals carry a target the text does not locate — a runtime value. ` +
+            `Some are outbound and some are ours, and this cannot tell which, so they are counted against the internal rate. ` +
+            `The internal deficit is therefore an upper bound, not a measurement.`);
+    }
+    if (!census.scopeKnown && census.hosts.length > 0) {
+        disclosure.push(`No internal hosts were supplied, so every absolute target counted as outbound. ` +
+            `If any of these are ours the internal rate is optimistic: ${census.hosts
+                .slice(0, 5)
+                .map((h) => `${h.host} (${h.count})`)
+                .join(", ")}.`);
+    }
+    if (recognisedDenominator === 0) {
+        disclosure.push("Nothing was recognised on this repository, so neither rate is defined.");
+    }
+    return {
+        read,
+        census,
+        overRecognised: recognisedDenominator === 0 ? null : read / recognisedDenominator,
+        overInternal: internalDenominator === 0 ? null : read / internalDenominator,
+        disclosure,
+    };
+}
+//# sourceMappingURL=unresolved.js.map

package/dist/query/unresolved.js.map

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

package/dist/query/verification-status.d.ts

@@ -0,0 +1,134 @@
+/**
+ * The static half of `verification_status` — `ai-tool-contract.md` §5.6, §8
+ * endpoint 13; AI layer §19/§20 (`Verification status` moved off the
+ * confidence axis); `ai-layer-plan.md` §2 (the trigger → stage mask), §4
+ * technique 6 (a dedicated tool, not appended to every response).
+ *
+ * ## Scope boundary — read this before assuming more than this module builds
+ *
+ * A complete `Verification status` also depends on **which pipeline stages
+ * ran under which trigger mask** (`ai-layer-plan.md` §2: the fast path skips
+ * stages 8-13 entirely) — that is runtime information about one specific
+ * run, and it does not exist in `descry-core`. This repo is the static
+ * knowledge plane; there is no live run here to ask "did stage 9 actually
+ * execute against this file." **This module builds the static half only:**
+ * what a static reading of the graph and a language's declared capabilities
+ * can determine about analysability and resolution. Combining that with the
+ * runtime half — which stages actually ran — is `descry-runtime`/the
+ * pipeline's job, not this one's.
+ *
+ * ## Output shape: `@descryy/ir`'s `VerificationStatus`, not a parallel one
+ *
+ * `packages/ir/src/finding.ts` already defines the shared shape two
+ * repositories (the pipeline and the desktop golden-report test) assert
+ * against — `{ exercised: string[], notExercised: UntestedScope[] }`. This
+ * module produces exactly that, deliberately, rather than a second
+ * "coverage" record: two structures answering the same question would be
+ * exactly the kind of divergence `finding.ts`'s own module doc warns about
+ * for `Finding` itself, one level down.
+ *
+ * An `exercised` entry is `"<ref> (R<resolution>)"` — the scope item's
+ * identifier plus the real resolution level the graph actually holds for it,
+ * because a present node's resolution is a fact worth keeping even though
+ * `VerificationStatus.exercised` is typed as bare strings; see
+ * {@link formatExercised} for the exact grammar and
+ * {@link resolutionOfExercised} for the matching parser. A present item's
+ * resolution is reported as-is and is **never filtered against the
+ * requested check's `minResolution`** — whether R1 is "enough" for a given
+ * claim is a judgement for something above this layer (rule 3's cap, or G4),
+ * not a fact this function may assert.
+ *
+ * ## Hard constraint: no report category, ever
+ *
+ * §19's five report categories (`confirmed` / `strongly supported` /
+ * `unconfirmed` / `not analysable` / `unsupported`) are assigned at G4,
+ * above this surface (`ai-tool-contract.md` §1.2 draws the same line for
+ * result states). This module returns only the raw coverage facts —
+ * reachable-or-not, resolution, a named reason — and never the literal
+ * category vocabulary; a test asserts none of the five strings ever appear
+ * in the output.
+ *
+ * ## Reuses `tiers/certify.ts`'s capability comparison, not a second one
+ *
+ * "Does this language's declared `CapabilityMatrix` cover what a check
+ * needs" is the same question `certify.ts`'s `checkCapability` already
+ * answers for a whole adapter's tier. {@link capabilityGaps} restates that
+ * comparison — declared node/edge types, declared `maxResolution` — at
+ * per-scope-item granularity rather than adapter-wide, so the two never
+ * quietly disagree about what "this language's capabilities satisfy this
+ * requirement" means. It is a restatement rather than an import because
+ * `certify.ts`'s function also folds in precision-draw attestation and
+ * corpus conformance, both properties of a *published tier*, not of one live
+ * scope item — pulling those in here would answer a different question than
+ * the one being asked.
+ *
+ * ## Why this never looks up capabilities by language itself
+ *
+ * `ScopeItem.capabilities` is supplied by the caller, already resolved, per
+ * item — never looked up here from a `language` string. A `Map.get(item.
+ * language)` shape inside `packages/core/src/query/` would be exactly the
+ * IR-boundary leak `descry-boundary/no-language-branch` exists to catch
+ * (architecture principle 7 / `CLAUDE.md` rule 1): deciding behaviour from
+ * *which* language a node came from, not merely from whether one is known.
+ * `certify.ts` holds the same discipline one layer up — it takes one
+ * `GateEvidence` per call and never builds a language-keyed registry inside
+ * `packages/core` either. Resolving "which capabilities apply to this
+ * item's language" is the caller's job, done above this boundary; `language`
+ * is read here only for disclosure (naming it in a reason string), never for
+ * a branch, comparison or lookup.
+ */
+import type { CapabilityMatrix, EdgeType, IRNode, NodeType, ResolutionLevel, VerificationStatus } from "@descryy/ir";
+/**
+ * What a caller wants to know is answerable, for the whole scope in one
+ * call. Mirrors the three targeting fields `tiers/ladder.ts`'s `Requirement`
+ * uses (`nodeTypes`/`edgeTypes`/`minResolution`), restated rather than
+ * imported: a live per-scope-item check is not a tier-ladder promotion row
+ * and carries none of `Requirement`'s `id`/`kind`/`statement`. Every field
+ * omitted asks only "was this item reached at all".
+ */
+export interface CoverageCheck {
+    readonly nodeTypes?: readonly NodeType[];
+    readonly edgeTypes?: readonly EdgeType[];
+    readonly minResolution?: ResolutionLevel;
+}
+/**
+ * One item of the scope being asked about — a file or a node.
+ *
+ * `node` is the strongest fact available: when the graph holds real,
+ * analysed content for this item, its own `resolution` is reported as-is,
+ * never re-derived. `capabilities` is consulted only when `node` is `null`,
+ * to explain *why* nothing is there — `undefined` means no adapter is
+ * registered for whatever this item is at all.
+ */
+export interface ScopeItem {
+    /** The identifier this item is reported under — a node id or a file path. Opaque to this module. */
+    readonly ref: string;
+    /** Read only for disclosure text, never for a lookup or branch — see the module header. `null` means genuinely unknown. */
+    readonly language: string | null;
+    /** The graph's own node for this item, when one exists. `null` means this item is not in the graph. */
+    readonly node: IRNode | null;
+    /** The declared capabilities of whatever would produce this item, when the caller can supply them. `undefined` means no adapter is registered. */
+    readonly capabilities: CapabilityMatrix | undefined;
+}
+/** Parses an `exercised` entry back into its ref and resolution. `null` if `entry` was not produced by {@link formatExercised}. */
+export declare function resolutionOfExercised(entry: string): {
+    readonly ref: string;
+    readonly resolution: ResolutionLevel;
+} | null;
+/**
+ * Compute the static half of `VerificationStatus` for a scope.
+ *
+ * Per item, one of three outcomes — see the module header for the full
+ * reasoning:
+ *
+ * 1. **Present in the graph** → `exercised`, carrying its real resolution.
+ * 2. **Absent, no capabilities supplied** → `notExercised`, naming the
+ *    language (or that none could be determined).
+ * 3. **Absent, capabilities supplied** → `notExercised`, naming the specific
+ *    declared gap against `check` when there is one, or — the honest edge
+ *    case — that a registered adapter declares everything asked for and a
+ *    static capability comparison alone cannot say why the item is still
+ *    absent.
+ */
+export declare function computeVerificationStatus(scope: readonly ScopeItem[], check?: CoverageCheck): VerificationStatus;
+//# sourceMappingURL=verification-status.d.ts.map

package/dist/query/verification-status.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verification-status.d.ts","sourceRoot":"","sources":["../../src/query/verification-status.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8EG;AAEH,OAAO,KAAK,EACV,gBAAgB,EAChB,QAAQ,EACR,MAAM,EACN,QAAQ,EACR,eAAe,EAEf,kBAAkB,EACnB,MAAM,aAAa,CAAC;AAErB;;;;;;;GAOG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,QAAQ,EAAE,CAAC;IACzC,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,QAAQ,EAAE,CAAC;IACzC,QAAQ,CAAC,aAAa,CAAC,EAAE,eAAe,CAAC;CAC1C;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,SAAS;IACxB,oGAAoG;IACpG,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,2HAA2H;IAC3H,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,uGAAuG;IACvG,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,kJAAkJ;IAClJ,QAAQ,CAAC,YAAY,EAAE,gBAAgB,GAAG,SAAS,CAAC;CACrD;AAuCD,mIAAmI;AACnI,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG;IAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,UAAU,EAAE,eAAe,CAAA;CAAE,GAAG,IAAI,CAI1H;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,SAAS,SAAS,EAAE,EAC3B,KAAK,GAAE,aAAkB,GACxB,kBAAkB,CAkCpB"}