@descryy/ir 0.1.0

package/dist/reliability.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Architecture principle 3, as a function.
+ *
+ * *A finding's reliability class is capped by the resolution level of the edges
+ * it rests on.* §11A.5 states the rule as a table and calls it "the single most
+ * consequential addition in v2.1"; until now nothing in the codebase evaluated
+ * it. The query layer computes a `resolutionFloor` for every answer and every
+ * consumer was free to ignore it, which is precisely the shape of a rule that
+ * holds in the document and not in the product.
+ *
+ * It lives in `@descryy/ir` rather than in the query layer because it is a
+ * property of the resolution scale itself. The MCP server is the first consumer;
+ * governance and the report layer are the next two, and all three must agree.
+ *
+ * ## The R2 row is not a typo
+ *
+ * §11A.5 gives R2 two answers: **B** in general, **A** for name-level facts only
+ * — a missing environment variable, a migration head, a route path that does not
+ * exist. The distinction is real. At R2 an LSP has resolved *which symbol a name
+ * refers to*, so a claim about the name is as good as it will get; a claim about
+ * the *shape* behind the name is not, because no type checker ran. Collapsing
+ * the row to "B" would silently downgrade the env-var check, which is the
+ * cheapest Class A check in the system (§1.10) and works at R0 in any language.
+ *
+ * So the caller states which kind of claim it is making. There is no default:
+ * `nameLevel` is a required argument, because a caller that has not thought
+ * about which kind of fact it is asserting is exactly the caller that would take
+ * the wrong one.
+ *
+ * ## `humanAsserted` — a second, independent cap, never a promotion
+ *
+ * DEC-223's answer half: an edge minted because a person confirmed a value
+ * for a refusal-ledger row (§3's `ConfirmedFact`) rests on exactly one
+ * unaudited assertion, corroborated by nothing. It is not R0-R4 at all —
+ * testimony is a different kind of evidence than "how much static or runtime
+ * tooling ran" — so it cannot be slotted into the resolution ladder honestly.
+ * Left unguarded, a `nameLevel: true` claim at R2 or better would reach class
+ * A the same way a genuinely independent name-level fact does, and a single
+ * person's typed string would silently defeat the one rule principle 3 exists
+ * to enforce.
+ *
+ * So `humanAsserted` is a **second, independent ceiling**, applied after the
+ * resolution/name-level table above, never a replacement for it and never a
+ * promotion: a structural C stays C (there is nothing to cap down from), a
+ * structural B stays B, and only a structural A is pulled down to B. Default
+ * `false` so every existing caller is unaffected.
+ */
+import type { ResolutionLevel } from "./ir.ts";
+/**
+ * §15.2's classes.
+ *
+ * `A` provable · `B` reportable with explicit confidence labelling ·
+ * `C` behavioural prediction, which principle 4 forbids reporting as fact
+ * until a runtime run confirms it.
+ */
+export type ReliabilityClass = "A" | "B" | "C";
+export declare const RELIABILITY_CLASSES: readonly ["A", "B", "C"];
+/**
+ * What a claim resting on evidence at `resolution` may be classified as, at best.
+ *
+ * @param nameLevel `true` when the claim is about a *name* — a symbol that does
+ * or does not exist, a path, an identifier. `false` when it is about a *shape*:
+ * a field's type, a payload's structure, a signature. Only the name-level case
+ * can reach `A` at R2, and only shape-level claims are what R3 buys.
+ * @param humanAsserted `true` when the edge exists because a person confirmed a
+ * value for a refusal-ledger row (DEC-223), rather than because static or
+ * runtime analysis resolved it. Pulls a structural `A` down to `B`; never
+ * raises `B` or `C`, and never appears as a fourth resolution level — see the
+ * module doc. Defaults `false` so every pre-existing caller is unaffected.
+ */
+export declare function reliabilityCap(resolution: ResolutionLevel, nameLevel: boolean, humanAsserted?: boolean): ReliabilityClass;
+/**
+ * The sentence a report puts next to a capped finding.
+ *
+ * Returned rather than logged, and returned even for `A`, so that a caller
+ * cannot produce an unlabelled finding by taking the class and discarding the
+ * disclosure. Rule 7 — honest degradation — is a property of what reaches the
+ * user, not of what the engine computed.
+ *
+ * @param emptyPath `true` when `resolution` is `0` because
+ * {@link minimumResolution} was given an empty graph path — no hop existed to
+ * take a minimum over — rather than because a hop actually resolved to R0.
+ * Both cap at class C (DEC-NEXT-empty-graph-path-resolution-floor.md kept
+ * the stored value unchanged); this flag only changes which sentence explains
+ * the cap, so a genuinely untraced path is not described as a poorly
+ * resolved one. Defaults `false` so every pre-existing caller is unaffected.
+ */
+export declare function reliabilityNote(resolution: ResolutionLevel, nameLevel: boolean, humanAsserted?: boolean, emptyPath?: boolean): string;
+//# sourceMappingURL=reliability.d.ts.map

package/dist/reliability.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reliability.d.ts","sourceRoot":"","sources":["../src/reliability.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAI/C;;;;;;GAMG;AACH,MAAM,MAAM,gBAAgB,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC;AAE/C,eAAO,MAAM,mBAAmB,0BAA2B,CAAC;AAE5D;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAC5B,UAAU,EAAE,eAAe,EAC3B,SAAS,EAAE,OAAO,EAClB,aAAa,UAAQ,GACpB,gBAAgB,CAsBlB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,eAAe,CAC7B,UAAU,EAAE,eAAe,EAC3B,SAAS,EAAE,OAAO,EAClB,aAAa,UAAQ,EACrB,SAAS,UAAQ,GAChB,MAAM,CAwFR"}

package/dist/reliability.js

@@ -0,0 +1,181 @@
+/**
+ * Architecture principle 3, as a function.
+ *
+ * *A finding's reliability class is capped by the resolution level of the edges
+ * it rests on.* §11A.5 states the rule as a table and calls it "the single most
+ * consequential addition in v2.1"; until now nothing in the codebase evaluated
+ * it. The query layer computes a `resolutionFloor` for every answer and every
+ * consumer was free to ignore it, which is precisely the shape of a rule that
+ * holds in the document and not in the product.
+ *
+ * It lives in `@descryy/ir` rather than in the query layer because it is a
+ * property of the resolution scale itself. The MCP server is the first consumer;
+ * governance and the report layer are the next two, and all three must agree.
+ *
+ * ## The R2 row is not a typo
+ *
+ * §11A.5 gives R2 two answers: **B** in general, **A** for name-level facts only
+ * — a missing environment variable, a migration head, a route path that does not
+ * exist. The distinction is real. At R2 an LSP has resolved *which symbol a name
+ * refers to*, so a claim about the name is as good as it will get; a claim about
+ * the *shape* behind the name is not, because no type checker ran. Collapsing
+ * the row to "B" would silently downgrade the env-var check, which is the
+ * cheapest Class A check in the system (§1.10) and works at R0 in any language.
+ *
+ * So the caller states which kind of claim it is making. There is no default:
+ * `nameLevel` is a required argument, because a caller that has not thought
+ * about which kind of fact it is asserting is exactly the caller that would take
+ * the wrong one.
+ *
+ * ## `humanAsserted` — a second, independent cap, never a promotion
+ *
+ * DEC-223's answer half: an edge minted because a person confirmed a value
+ * for a refusal-ledger row (§3's `ConfirmedFact`) rests on exactly one
+ * unaudited assertion, corroborated by nothing. It is not R0-R4 at all —
+ * testimony is a different kind of evidence than "how much static or runtime
+ * tooling ran" — so it cannot be slotted into the resolution ladder honestly.
+ * Left unguarded, a `nameLevel: true` claim at R2 or better would reach class
+ * A the same way a genuinely independent name-level fact does, and a single
+ * person's typed string would silently defeat the one rule principle 3 exists
+ * to enforce.
+ *
+ * So `humanAsserted` is a **second, independent ceiling**, applied after the
+ * resolution/name-level table above, never a replacement for it and never a
+ * promotion: a structural C stays C (there is nothing to cap down from), a
+ * structural B stays B, and only a structural A is pulled down to B. Default
+ * `false` so every existing caller is unaffected.
+ */
+const RELIABILITY_ORDER = { A: 2, B: 1, C: 0 };
+export const RELIABILITY_CLASSES = ["A", "B", "C"];
+/**
+ * What a claim resting on evidence at `resolution` may be classified as, at best.
+ *
+ * @param nameLevel `true` when the claim is about a *name* — a symbol that does
+ * or does not exist, a path, an identifier. `false` when it is about a *shape*:
+ * a field's type, a payload's structure, a signature. Only the name-level case
+ * can reach `A` at R2, and only shape-level claims are what R3 buys.
+ * @param humanAsserted `true` when the edge exists because a person confirmed a
+ * value for a refusal-ledger row (DEC-223), rather than because static or
+ * runtime analysis resolved it. Pulls a structural `A` down to `B`; never
+ * raises `B` or `C`, and never appears as a fourth resolution level — see the
+ * module doc. Defaults `false` so every pre-existing caller is unaffected.
+ */
+export function reliabilityCap(resolution, nameLevel, humanAsserted = false) {
+    const structural = (() => {
+        switch (resolution) {
+            case 0:
+                return "C";
+            case 1:
+                return "B";
+            case 2:
+                return nameLevel ? "A" : "B";
+            default:
+                // R3 (type checker) and R4 (witnessed at runtime). R4 is unconditional —
+                // the edge was observed rather than inferred, so there is no kind of claim
+                // it fails to support.
+                return "A";
+        }
+    })();
+    if (!humanAsserted)
+        return structural;
+    // A cap, never a promotion: only pulls A down to B. C is already below B, so
+    // a human declaration cannot make an R0-grounded claim look stronger than it
+    // is — it can only ever cost reliability, never buy it.
+    return RELIABILITY_ORDER[structural] > RELIABILITY_ORDER.B ? "B" : structural;
+}
+/**
+ * The sentence a report puts next to a capped finding.
+ *
+ * Returned rather than logged, and returned even for `A`, so that a caller
+ * cannot produce an unlabelled finding by taking the class and discarding the
+ * disclosure. Rule 7 — honest degradation — is a property of what reaches the
+ * user, not of what the engine computed.
+ *
+ * @param emptyPath `true` when `resolution` is `0` because
+ * {@link minimumResolution} was given an empty graph path — no hop existed to
+ * take a minimum over — rather than because a hop actually resolved to R0.
+ * Both cap at class C (DEC-NEXT-empty-graph-path-resolution-floor.md kept
+ * the stored value unchanged); this flag only changes which sentence explains
+ * the cap, so a genuinely untraced path is not described as a poorly
+ * resolved one. Defaults `false` so every pre-existing caller is unaffected.
+ */
+export function reliabilityNote(resolution, nameLevel, humanAsserted = false, emptyPath = false) {
+    const cap = reliabilityCap(resolution, nameLevel, humanAsserted);
+    const structuralCap = reliabilityCap(resolution, nameLevel);
+    const basis = `The weakest evidence under this answer is R${resolution}`;
+    if (humanAsserted && RELIABILITY_ORDER[structuralCap] > RELIABILITY_ORDER.B) {
+        // The one case rule 7 exists for here: the structural evidence alone would
+        // have permitted A, and a person's declaration is the only reason it does
+        // not. Naming that plainly rather than folding it into the generic B
+        // sentence below, which would read as an ordinary resolution shortfall.
+        return (`${basis}, which on its own would permit reliability class A. This edge exists because a ` +
+            "person confirmed a value for a refusal-ledger row, not because analysis resolved it — one " +
+            "unaudited assertion, corroborated by nothing — so it is capped at class B regardless.");
+    }
+    switch (cap) {
+        case "C":
+            // DEC-NEXT-empty-graph-path-resolution-floor.md's ruling: a zero-hop
+            // graph path derives R0 by the same construction as a genuinely
+            // R0-resolved hop, and both cap at class C — but they are not the same
+            // claim, and describing an untraced path with the "syntax only, nothing
+            // resolved" wording below would suggest a bad trace where none was
+            // attempted at all. This branch is checked first, ahead of the
+            // name-level/shape-level split, because what's missing here is
+            // attribution, not a name-vs-shape distinction — the sentence is the
+            // same regardless of `nameLevel`. The strength of the underlying
+            // observation (if any) belongs in Runtime evidence, not here: rule 3's
+            // cap does not move, only the sentence explaining it stays honest about
+            // why (rule 7).
+            if (emptyPath) {
+                return (`${basis} — no graph path was traced at all, which caps this at reliability class C. ` +
+                    "This is a different fact from a path that was traced and resolved poorly: nothing here " +
+                    "suggests a weak trace, only that no causal path from evidence to code was ever asserted. " +
+                    "Any runtime corroboration for the underlying observation is reported separately, under " +
+                    "Runtime evidence, and does not raise this cap. Principle 4 forbids reporting this as a " +
+                    "fact about the running system until a runtime run confirms it.");
+            }
+            // Described by what R0 *is* — syntax with nothing resolved — rather than
+            // by the parser that produces it. The boundary lint refuses the toolchain
+            // name here and is right to: this string reaches a user, and a user with a
+            // repository in a language whose R0 comes from somewhere else would be
+            // told something false about their own run.
+            //
+            // **The two R0 claims are not the same claim, and one sentence for both
+            // overstated one of them.** A name-level fact at R0 — *this file names
+            // this environment variable* — was read where it is written. What R0
+            // fails to establish is what the name refers to and whether the code runs
+            // at all. Calling that "a behavioural prediction" describes neither
+            // failure, and to a reader it suggests the finding was inferred rather
+            // than read, which is worse than saying nothing. A shape-level claim at
+            // R0 genuinely is a prediction: nothing resolved the type under it.
+            //
+            // The class is C either way. Principle 3's cap is not what changes here
+            // — only the sentence that explains it, and a disclosure that misstates
+            // its own basis is rule 7 failing in the one place rule 7 acts.
+            return nameLevel
+                ? `${basis} (syntax only, with no references resolved), which caps this at reliability ` +
+                    "class C. The name was read where it is written; what has not been established is what " +
+                    "it refers to, or whether this code runs at all. Principle 4 forbids reporting it as a " +
+                    "fact about the running system until a runtime run confirms it."
+                : `${basis} (syntax only, with no references resolved), which caps this at reliability ` +
+                    "class C: a behavioural prediction, not an established fact — no type checker resolved " +
+                    "the shapes it rests on. Principle 4 forbids reporting it as one until a runtime run " +
+                    "confirms it.";
+        case "B":
+            return (`${basis}, which caps this at reliability class B: reportable, but with its confidence ` +
+                "stated. " +
+                (resolution === 2
+                    ? "R2 resolves which symbol a name refers to but runs no type checker, so a claim " +
+                        "about the shape behind the name is not provable at this level."
+                    : "Cross-file resolution at this level is name-matched rather than resolved."));
+        default:
+            return (`${basis}, which permits reliability class A` +
+                (resolution === 2
+                    ? " for this claim, because it is a name-level fact — R2 resolved the symbol the name " +
+                        "refers to. A shape-level claim on the same evidence would be capped at B."
+                    : resolution === 4
+                        ? ": the evidence was witnessed at runtime rather than inferred."
+                        : ": a type checker resolved the shapes this rests on."));
+    }
+}
+//# sourceMappingURL=reliability.js.map

package/dist/reliability.js.map

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

package/dist/tool-surface.d.ts

@@ -0,0 +1,131 @@
+/**
+ * The two enumerations the AI layer's tool surface is built on, and nothing
+ * else.
+ *
+ * Neither is implemented here. `ResultState` is P2's work and `ToolClass` is
+ * P1's; what belongs at the IR boundary is the *vocabulary*, because three
+ * consumers — the MCP tool definitions, the pipeline that reads their results,
+ * and the desktop surface that renders them — must agree on it exactly. Three
+ * nearly-identical local copies of a five-member union is how two of them come
+ * to disagree about one member, which is the failure this file exists to make
+ * impossible rather than unlikely.
+ *
+ * Both follow `RELIABILITY_CLASSES`' shape: an `as const` array plus a derived
+ * union, never a TS enum — enums are not erasable syntax and Node's type
+ * stripping cannot run them (tsconfig `erasableSyntaxOnly` enforces this).
+ */
+/**
+ * `documents/architecture/ai-tool-contract.md` §1 — the five result states, and
+ * `documents/plans/ai-layer-plan.md` §3's contract rule 1 beneath it.
+ *
+ * | State | The tool… | `data` | What the caller may read from it |
+ * | --- | --- | --- | --- |
+ * | `ok` | looked and found something | populated | a fact about the code |
+ * | `empty` | looked, completely, and there was nothing | empty collection | **a fact about the code** — the absence is real |
+ * | `refused` | could not look, and knows why | `null` | **a fact about Descry**, never about the code |
+ * | `failed` | tried, and something broke | `null` or partial | a fault; not a statement about the code either way |
+ * | `timed_out` | ran out of its declared budget | partial, marked so | a partial answer; absence within it means nothing |
+ *
+ * The rule is measured rather than derived — **this project has hit the same
+ * defect at three separate layers**, each time because one shape stood for two
+ * facts:
+ *
+ * - a scan reporting 0 framework route annotations in a repository that had
+ *   370, because a relative path did not resolve;
+ * - a repository reported as *"not on disk"* when it was in the other
+ *   reference root all along;
+ * - a route extractor returning silently on an empty collection, with no
+ *   refusal row, so *"none are registered"* and *"registration has not run"*
+ *   arrived identically.
+ *
+ * A tool that answers `[]` for both *"nothing matched"* and *"I could not
+ * look"* teaches a model a false fact **it has no way to detect** — it cannot
+ * tell an empty answer from an absent one, so it reasons from the empty
+ * denominator as though it were a measurement. Rule 3 of §3 is the other half:
+ * a refusal carries its named reason verbatim, because `refused` alone is a
+ * state and not an explanation.
+ *
+ * ## `refused` is not `not analysable` — §1.2
+ *
+ * They are different axes on different objects. The five here describe **one
+ * tool call's outcome**; §19's five report categories — one of which is spelled
+ * `not analysable` — describe **a finding's confidence**. A `refused` result is
+ * one *input* a governance gate may use when it later assigns the `not
+ * analysable` category to a finding, but a tool assigns no category and no tool
+ * result carries one.
+ *
+ * So the two unions deliberately share no member name, and there is a test
+ * asserting it. The near-collision is exactly the conflation this project
+ * caught at three layers and would otherwise reintroduce at a fourth; a
+ * `not_analysable` spelled into this list is how one becomes assignable where
+ * the other belongs.
+ *
+ * ## `empty` is not permission to stop disclosing — §1.3
+ *
+ * `empty` is a claim that an absence is **real**, and an absence is only as
+ * real as the reach of the thing that looked. A tool answering `empty` still
+ * states what it searched, so a caller can tell *"there are no callers"* from
+ * *"there are no callers among the things this producer emits."*
+ *
+ * ## A zero population is `refused`, never `empty` — §1.3a
+ *
+ * **The test is §1's own table, and it is about the denominator, not the
+ * result.** `empty` says the tool looked completely and there was nothing to
+ * find — a fact about the code. `refused` says it could not look — a fact about
+ * Descry. So the question a producer must answer before choosing between them
+ * is *whose* absence this is:
+ *
+ * | | State |
+ * | --- | --- |
+ * | The population exists; nothing in it matched this query | `empty` |
+ * | The population is itself **zero** | **`refused`** |
+ *
+ * A count over an empty population is not a finding of zero — it is the
+ * absence of a measurement. **This project has now paid for that confusion at
+ * four layers**, the fourth being incident search, where the first revision of
+ * §1.3 used this very endpoint as its worked example of an honest `empty`: with
+ * no `INCIDENT` nodes in the graph, answering `empty` says *"this code has no
+ * similar incidents"* when the true statement is *"Descry cannot see most
+ * incidents in any codebase"* — only a revert mints one, and fix-forward, the
+ * commoner pattern by far, mints nothing. The empty-denominator defect, inside
+ * the endpoint written to demonstrate the rule against it.
+ *
+ * The disclosure obligation rides on **both** states, not only on `empty`.
+ *
+ * `timed_out` is spelled with an underscore, deliberately and once: it crosses
+ * a wire protocol as a literal, so the spelling is contract rather than style.
+ */
+export declare const RESULT_STATES: readonly ["ok", "empty", "refused", "failed", "timed_out"];
+export type ResultState = (typeof RESULT_STATES)[number];
+export declare function isResultState(value: string): value is ResultState;
+/**
+ * DEC-278 — the three-way split that replaced §3's rule 4 (*"read tools are
+ * pure and retryable; action tools are neither"*).
+ *
+ * | Class | Handshake |
+ * | --- | --- |
+ * | `read` | No. Pure, retryable. |
+ * | `stateful-read` | No. Mutates Descry's own derived state only; idempotent in effect. |
+ * | `action` | **Yes** — the two-call confirmation-token handshake. |
+ *
+ * **The line is not "does it write bytes."** It is *"can its effect change a
+ * later finding without the developer having said so."* Re-deriving a graph
+ * from code already on disk, or recording where that code is, cannot introduce
+ * a claim the repository does not already contain — both write, and neither
+ * can move a finding. Recording a person's confirmed value for a
+ * refusal-ledger row can: it becomes a graph input, it feeds `humanAsserted`,
+ * and DEC-223 caps it at reliability class B precisely because it rests on one
+ * unaudited assertion. Only that third kind takes the handshake.
+ *
+ * Gating all three was considered and rejected as consistent-but-unusable: a
+ * client that must confirm before it may build a graph cannot answer the first
+ * question asked of it.
+ *
+ * `stateful-read` needs its own contract test wherever these are enforced —
+ * pure-retryable assertions do not apply to it and action-gate assertions must
+ * not.
+ */
+export declare const TOOL_CLASSES: readonly ["read", "stateful-read", "action"];
+export type ToolClass = (typeof TOOL_CLASSES)[number];
+export declare function isToolClass(value: string): value is ToolClass;
+//# sourceMappingURL=tool-surface.d.ts.map

package/dist/tool-surface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-surface.d.ts","sourceRoot":"","sources":["../src/tool-surface.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgFG;AACH,eAAO,MAAM,aAAa,4DAA6D,CAAC;AAExF,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,CAAC,CAAC;AAEzD,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,WAAW,CAEjE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,eAAO,MAAM,YAAY,8CAA+C,CAAC;AAEzE,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,CAAC,CAAC;AAEtD,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,SAAS,CAE7D"}

package/dist/tool-surface.js

@@ -0,0 +1,133 @@
+/**
+ * The two enumerations the AI layer's tool surface is built on, and nothing
+ * else.
+ *
+ * Neither is implemented here. `ResultState` is P2's work and `ToolClass` is
+ * P1's; what belongs at the IR boundary is the *vocabulary*, because three
+ * consumers — the MCP tool definitions, the pipeline that reads their results,
+ * and the desktop surface that renders them — must agree on it exactly. Three
+ * nearly-identical local copies of a five-member union is how two of them come
+ * to disagree about one member, which is the failure this file exists to make
+ * impossible rather than unlikely.
+ *
+ * Both follow `RELIABILITY_CLASSES`' shape: an `as const` array plus a derived
+ * union, never a TS enum — enums are not erasable syntax and Node's type
+ * stripping cannot run them (tsconfig `erasableSyntaxOnly` enforces this).
+ */
+/**
+ * `documents/architecture/ai-tool-contract.md` §1 — the five result states, and
+ * `documents/plans/ai-layer-plan.md` §3's contract rule 1 beneath it.
+ *
+ * | State | The tool… | `data` | What the caller may read from it |
+ * | --- | --- | --- | --- |
+ * | `ok` | looked and found something | populated | a fact about the code |
+ * | `empty` | looked, completely, and there was nothing | empty collection | **a fact about the code** — the absence is real |
+ * | `refused` | could not look, and knows why | `null` | **a fact about Descry**, never about the code |
+ * | `failed` | tried, and something broke | `null` or partial | a fault; not a statement about the code either way |
+ * | `timed_out` | ran out of its declared budget | partial, marked so | a partial answer; absence within it means nothing |
+ *
+ * The rule is measured rather than derived — **this project has hit the same
+ * defect at three separate layers**, each time because one shape stood for two
+ * facts:
+ *
+ * - a scan reporting 0 framework route annotations in a repository that had
+ *   370, because a relative path did not resolve;
+ * - a repository reported as *"not on disk"* when it was in the other
+ *   reference root all along;
+ * - a route extractor returning silently on an empty collection, with no
+ *   refusal row, so *"none are registered"* and *"registration has not run"*
+ *   arrived identically.
+ *
+ * A tool that answers `[]` for both *"nothing matched"* and *"I could not
+ * look"* teaches a model a false fact **it has no way to detect** — it cannot
+ * tell an empty answer from an absent one, so it reasons from the empty
+ * denominator as though it were a measurement. Rule 3 of §3 is the other half:
+ * a refusal carries its named reason verbatim, because `refused` alone is a
+ * state and not an explanation.
+ *
+ * ## `refused` is not `not analysable` — §1.2
+ *
+ * They are different axes on different objects. The five here describe **one
+ * tool call's outcome**; §19's five report categories — one of which is spelled
+ * `not analysable` — describe **a finding's confidence**. A `refused` result is
+ * one *input* a governance gate may use when it later assigns the `not
+ * analysable` category to a finding, but a tool assigns no category and no tool
+ * result carries one.
+ *
+ * So the two unions deliberately share no member name, and there is a test
+ * asserting it. The near-collision is exactly the conflation this project
+ * caught at three layers and would otherwise reintroduce at a fourth; a
+ * `not_analysable` spelled into this list is how one becomes assignable where
+ * the other belongs.
+ *
+ * ## `empty` is not permission to stop disclosing — §1.3
+ *
+ * `empty` is a claim that an absence is **real**, and an absence is only as
+ * real as the reach of the thing that looked. A tool answering `empty` still
+ * states what it searched, so a caller can tell *"there are no callers"* from
+ * *"there are no callers among the things this producer emits."*
+ *
+ * ## A zero population is `refused`, never `empty` — §1.3a
+ *
+ * **The test is §1's own table, and it is about the denominator, not the
+ * result.** `empty` says the tool looked completely and there was nothing to
+ * find — a fact about the code. `refused` says it could not look — a fact about
+ * Descry. So the question a producer must answer before choosing between them
+ * is *whose* absence this is:
+ *
+ * | | State |
+ * | --- | --- |
+ * | The population exists; nothing in it matched this query | `empty` |
+ * | The population is itself **zero** | **`refused`** |
+ *
+ * A count over an empty population is not a finding of zero — it is the
+ * absence of a measurement. **This project has now paid for that confusion at
+ * four layers**, the fourth being incident search, where the first revision of
+ * §1.3 used this very endpoint as its worked example of an honest `empty`: with
+ * no `INCIDENT` nodes in the graph, answering `empty` says *"this code has no
+ * similar incidents"* when the true statement is *"Descry cannot see most
+ * incidents in any codebase"* — only a revert mints one, and fix-forward, the
+ * commoner pattern by far, mints nothing. The empty-denominator defect, inside
+ * the endpoint written to demonstrate the rule against it.
+ *
+ * The disclosure obligation rides on **both** states, not only on `empty`.
+ *
+ * `timed_out` is spelled with an underscore, deliberately and once: it crosses
+ * a wire protocol as a literal, so the spelling is contract rather than style.
+ */
+export const RESULT_STATES = ["ok", "empty", "refused", "failed", "timed_out"];
+export function isResultState(value) {
+    return RESULT_STATES.includes(value);
+}
+/**
+ * DEC-278 — the three-way split that replaced §3's rule 4 (*"read tools are
+ * pure and retryable; action tools are neither"*).
+ *
+ * | Class | Handshake |
+ * | --- | --- |
+ * | `read` | No. Pure, retryable. |
+ * | `stateful-read` | No. Mutates Descry's own derived state only; idempotent in effect. |
+ * | `action` | **Yes** — the two-call confirmation-token handshake. |
+ *
+ * **The line is not "does it write bytes."** It is *"can its effect change a
+ * later finding without the developer having said so."* Re-deriving a graph
+ * from code already on disk, or recording where that code is, cannot introduce
+ * a claim the repository does not already contain — both write, and neither
+ * can move a finding. Recording a person's confirmed value for a
+ * refusal-ledger row can: it becomes a graph input, it feeds `humanAsserted`,
+ * and DEC-223 caps it at reliability class B precisely because it rests on one
+ * unaudited assertion. Only that third kind takes the handshake.
+ *
+ * Gating all three was considered and rejected as consistent-but-unusable: a
+ * client that must confirm before it may build a graph cannot answer the first
+ * question asked of it.
+ *
+ * `stateful-read` needs its own contract test wherever these are enforced —
+ * pure-retryable assertions do not apply to it and action-gate assertions must
+ * not.
+ */
+export const TOOL_CLASSES = ["read", "stateful-read", "action"];
+export function isToolClass(value) {
+    return TOOL_CLASSES.includes(value);
+}
+//# sourceMappingURL=tool-surface.js.map

package/dist/tool-surface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-surface.js","sourceRoot":"","sources":["../src/tool-surface.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgFG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,IAAI,EAAE,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,WAAW,CAAU,CAAC;AAIxF,MAAM,UAAU,aAAa,CAAC,KAAa;IACzC,OAAQ,aAAmC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AAC9D,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,MAAM,EAAE,eAAe,EAAE,QAAQ,CAAU,CAAC;AAIzE,MAAM,UAAU,WAAW,CAAC,KAAa;IACvC,OAAQ,YAAkC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AAC7D,CAAC"}

package/dist/vocabulary.d.ts

@@ -0,0 +1,73 @@
+/**
+ * The canonical graph vocabulary: 15 node types, 15 edge types.
+ *
+ * FROZEN. See DEC-003. Adding a type multiplies traversal, ranking, storage and
+ * governance work — new capabilities are new *queries* over these edges, not new
+ * types. Extending either list requires a decision entry in DECISIONS.md, and the
+ * arity tests in test/vocabulary.test.ts will fail until the counts there are
+ * deliberately updated, which makes the change visible in review.
+ *
+ * Declared as `as const` arrays with derived unions rather than TS enums:
+ * enums are not erasable syntax and Node's type stripping cannot run them
+ * (tsconfig `erasableSyntaxOnly` enforces this).
+ */
+export declare const NODE_TYPES: readonly ["FILE", "FUNCTION", "CLASS", "MODULE", "API_ENDPOINT", "API_ROUTE", "DATABASE_TABLE", "DATABASE_COLUMN", "MODEL", "DTO", "COMPONENT", "PAGE", "TEST_CASE", "INCIDENT", "FIX_PATTERN"];
+export declare const EDGE_TYPES: readonly ["CALLS", "IMPORTS", "READS", "WRITES", "RETURNS", "IMPLEMENTS", "INHERITS", "USES_API", "SERVES_API", "USES_TYPE", "PROPAGATES_TO", "TESTS", "FIXED_BY", "CHANGES_WITH", "INCIDENT_CORRELATED"];
+export type NodeType = (typeof NODE_TYPES)[number];
+export type EdgeType = (typeof EDGE_TYPES)[number];
+export declare function isNodeType(value: string): value is NodeType;
+export declare function isEdgeType(value: string): value is EdgeType;
+/**
+ * Node types that have no source file and no line range.
+ *
+ * `API_ENDPOINT` is the cross-language join node — it is written by two adapters
+ * that never share a line of code, so it belongs to neither file. `INCIDENT` and
+ * `FIX_PATTERN` come from git history rather than from source.
+ *
+ * See DEC-014: architecture §11A.4 typed `file` and `range` as required, which
+ * made the join node unrepresentable.
+ */
+export declare const FILELESS_NODE_TYPES: readonly ["API_ENDPOINT", "INCIDENT", "FIX_PATTERN"];
+export declare function isFilelessNodeType(type: NodeType): boolean;
+/**
+ * Node types that are a **declared type** — something a reference can name and a
+ * value can be an instance of.
+ *
+ * `MODEL` and `DTO` are not alternatives to `CLASS`; they are a `CLASS` that a
+ * framework extractor found extra evidence about. An ORM model is still a type:
+ * it is still imported, still named in annotations, still inherited from, still
+ * returned. The extra evidence is a persistence mapping or a transport boundary,
+ * and it changes what the node *means*, not what it *is*.
+ *
+ * This predicate exists because every adapter writes `type === "CLASS"` to ask
+ * "is this a type?", and there were twenty-one such sites across two adapters
+ * before the first framework extractor landed. Promoting one class to `MODEL`
+ * silently withdrew its `USES_TYPE`, `INHERITS` and `RETURNS` edges at every one
+ * of them — a recall collapse with no error, no rejection and no ledger row,
+ * which is the failure mode rule 7 exists to forbid.
+ *
+ * It is a query over the frozen vocabulary, not an extension of it. See DEC-093.
+ */
+export declare const TYPE_LIKE_NODE_TYPES: readonly ["CLASS", "MODEL", "DTO"];
+export declare function isTypeLikeNodeType(type: NodeType): boolean;
+/**
+ * Node types that are a **callable declaration** — something a call site can
+ * reach and a call graph can traverse.
+ *
+ * The same relationship `TYPE_LIKE_NODE_TYPES` describes, one row down. A React
+ * component is a function that a framework calls; `<OrderPage />` is a call in
+ * every sense a call graph cares about, which is the argument this codebase
+ * already made when it decided `post = (…) => …` is a method. `PAGE` is a
+ * component with a route attached and is callable for the same reason.
+ *
+ * `TEST_CASE` is deliberately absent. It is callable, but every site that
+ * distinguishes it does so because a call *inside* a test is coverage rather
+ * than a call-graph edge — folding it in here would erase that distinction at
+ * exactly the sites that exist to make it.
+ *
+ * See DEC-093, and the note there about what promotion costs when a kind check
+ * is written as an equality.
+ */
+export declare const CALLABLE_NODE_TYPES: readonly ["FUNCTION", "COMPONENT", "PAGE"];
+export declare function isCallableNodeType(type: NodeType): boolean;
+//# sourceMappingURL=vocabulary.d.ts.map

package/dist/vocabulary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vocabulary.d.ts","sourceRoot":"","sources":["../src/vocabulary.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,eAAO,MAAM,UAAU,iMAgBb,CAAC;AAEX,eAAO,MAAM,UAAU,2MA4Cb,CAAC;AAEX,MAAM,MAAM,QAAQ,GAAG,CAAC,OAAO,UAAU,CAAC,CAAC,MAAM,CAAC,CAAC;AACnD,MAAM,MAAM,QAAQ,GAAG,CAAC,OAAO,UAAU,CAAC,CAAC,MAAM,CAAC,CAAC;AAKnD,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,QAAQ,CAE3D;AAED,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,QAAQ,CAE3D;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,mBAAmB,sDAIQ,CAAC;AAIzC,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAE1D;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,oBAAoB,oCAAmE,CAAC;AAIrG,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAE1D;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,mBAAmB,4CAA2E,CAAC;AAI5G,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAE1D"}