@descryy/ir 0.1.0

package/dist/finding.js

@@ -0,0 +1,491 @@
+/**
+ * The shared finding record, and G3/G4 — the gates that decide what may be
+ * called what.
+ *
+ * `documents/architecture/descry-ai-layer.md` §20 is canonical for the type:
+ * **fourteen fields, no more and no fewer.** §42 carries a fifteenth,
+ * `Hypotheses considered`, which belongs to the output a developer reads and
+ * not to the stored record; it is deliberately absent here. DEC-276's own prose
+ * says *"eleven fields are extended to thirteen"* — eleven plus three is
+ * fourteen, and §20 corrects the arithmetic while keeping the field list the
+ * decision actually produced.
+ *
+ * It lives in `@descryy/ir` because two repositories construct and assert
+ * against it — the pipeline that produces findings and the golden-report test
+ * that checks all fourteen render — and both plans put it here specifically so
+ * that a divergence is a compile error rather than a field quietly missing from
+ * a page.
+ *
+ * ## Five axes, and they are not interchangeable
+ *
+ * A finding says five separate things, and collapsing any pair of them loses a
+ * distinction the product exists to make:
+ *
+ * - **Confidence** — how sure we are (§19's five categories).
+ * - **Fault layer** — whose problem it is (DEC-273). A finding can be
+ *   `confirmed` and `environment` at once: fully proven, and not the
+ *   application's fault.
+ * - **Reliability class** — how certain the *category* of claim is (§15.2).
+ * - **Resolution level** — how well the *code was understood* (§11A.6).
+ * - **Environment level** — how faithful the environment that produced it was
+ *   (architecture §16.3).
+ *
+ * **Coverage is a sixth thing and not a confidence value.** §19's adopted note
+ * moved untested scope out of the category list and into `Verification status`
+ * deliberately: *"we found nothing"* and *"we did not look"* are different
+ * statements, and the precision-over-recall rule is only defensible while the
+ * second one has an honest home.
+ */
+import { reliabilityCap } from "./reliability.js";
+import { RESOLUTION_LEVELS } from "./ir.js";
+/**
+ * The one cast in this module, kept in one place so the brand has exactly one
+ * runtime origin. Not exported — {@link rederive} is the whole legitimate
+ * surface for producing one on the read side of a storage boundary; every
+ * other producer is one of the derivations below, computed fresh.
+ */
+function derive(value) {
+    return value;
+}
+/**
+ * §19's five, adopted as superseding the architecture's previous four.
+ *
+ * `not analysable` and `unsupported` are refusals rather than readings of
+ * evidence — *"we cannot establish this here"* and *"we do not do this at
+ * all"* — and G4 below does not produce them; they are inherited from the
+ * static case unchanged.
+ */
+export const REPORT_CATEGORIES = [
+    "confirmed",
+    "strongly supported",
+    "unconfirmed",
+    "not analysable",
+    "unsupported",
+];
+/**
+ * The three of the five that G4's step 2 can return, ordered strongest first.
+ *
+ * A narrower return type than {@link ReportCategory} on purpose: the gate reads
+ * evidence, and no amount of evidence turns into *"we cannot analyse this"*.
+ */
+export const EVIDENCE_CATEGORIES = ["confirmed", "strongly supported", "unconfirmed"];
+/**
+ * DEC-273 — a second axis beside confidence, never a sixth category.
+ *
+ * Confidence asks *how sure are we*; fault layer asks *whose problem is this*.
+ * They are independent, and a finding is not more or less true for being an
+ * environment fault — it is attributable to a different owner.
+ *
+ * **Classification heuristics remain deliberately unspecified for `product`,
+ * and for the no-comparison-available fallback on `environment`/`dependency`.**
+ * DEC-273 rests on three real classifications, and three is not enough to
+ * generalize a pattern-match rule from — `descry-ai-layer.md` §20's own
+ * caution, unchanged by the ruling below. **`automation`, `dependency` and
+ * `environment` are the three exceptions** — see {@link classifyFaultLayer}.
+ * None of the three is a heuristic in the sense being deferred: each is a
+ * structural comparison a tool either reports or does not (a harness
+ * self-failure flag, a declared-vs-resolved dependency version, a
+ * declared-vs-observed runner version), not a pattern inferred from few
+ * examples. `automation` was unblocked 2026-08-24 by `descry-runtime`'s
+ * RT-219 self-observability channel; `dependency`/`environment`'s structural
+ * comparison is ruled in
+ * `DEC-NEXT-fault-layer-empirical-confirmation.md`, which also requires every
+ * classification to carry its own confidence marker — see
+ * {@link faultLayerConfidence}.
+ */
+export const FAULT_LAYERS = [
+    /** The application's own code. */
+    "product",
+    /** Descry's own test or harness logic. See {@link classifyFaultLayer}. */
+    "automation",
+    /** Runner, interpreter version, CI configuration — a mismatch, not a bug. */
+    "environment",
+    /** A pinned or transitive dependency. */
+    "dependency",
+    /** Not yet classified. An honest value, not a placeholder for a missing one. */
+    "unknown",
+];
+/**
+ * `DEC-NEXT-fault-layer-empirical-confirmation.md` — whether a fault-layer
+ * value rests on a structural comparison/rerun or a pattern-match with no
+ * comparison available. See {@link faultLayerConfidence}.
+ */
+export const FAULT_LAYER_CONFIDENCES = ["structural", "heuristic"];
+/**
+ * Architecture §16.3's fidelity levels — how real the environment that produced
+ * the finding was. Emitted on every finding as `Validated Against: Level N`.
+ *
+ * 1 stub · 2 real code + disposable seeded database (the preferred default) ·
+ * 3 real code + redacted production-shaped recordings · 4 real staging.
+ * Selection prefers the highest available, 4 → 1.
+ */
+export const ENVIRONMENT_LEVELS = [1, 2, 3, 4];
+/**
+ * The six independent observation channels, closed list —
+ * `ai-governance-spec.md` §5.2, ruled 2026-08-24 in
+ * `DEC-NEXT-independent-signal-type-inventory.md`, superseding DEC-276's
+ * original four.
+ *
+ * *"Two log lines are one signal type."* `E` counts **channels**, not
+ * observations, which is why {@link independentSignalTypes} derives it rather
+ * than trusting a caller's count.
+ *
+ * **Not a raw count over `descry-runtime`'s twenty-two runtime event types.**
+ * Each channel folds in the event types that belong to it (the full mapping
+ * is the spec's own table). `TEST_FAILED` — one of the four previously-open
+ * types — is deliberately **not** a seventh channel: its evidentiary weight
+ * belongs to `M` alone (see {@link directMechanismEvidence}), and counting it
+ * as one more corroborating channel would route a reproduced failure through
+ * the strictly weaker `E >= 1` path when it already qualifies for `M`'s
+ * direct path. `COLLECTOR_ERROR` and every harness-action type
+ * (`PROCESS_STARTED`, `NAVIGATION`, `CLICK`, ...) are excluded by name — they
+ * record that the observer failed, or what Descry did, never what the system
+ * under test did.
+ *
+ * **This list is deliberately narrow, and widening it must stay a compile
+ * error.** A new collector arriving quietly and re-tuning every confidence
+ * boundary with nothing failing is the exact defect the result-state enum next
+ * door exists to prevent, one level up. Typing `E` as a bare `number` would
+ * "fix" the friction by removing the alarm. An unrecognised event type must
+ * fail closed — {@link RuntimeEvidence.signal} of `null` — until this table is
+ * extended by the same process that built it.
+ */
+export const RUNTIME_SIGNAL_TYPES = [
+    "browser-visual",
+    "browser-console",
+    "network",
+    "backend-log",
+    "database",
+    "external-service",
+];
+/**
+ * Legal values of `E`. Bounded by the six channels above, hence 0–6.
+ */
+export const SIGNAL_TYPE_COUNTS = [0, 1, 2, 3, 4, 5, 6];
+/**
+ * §20's fourteen fields, in §20's order.
+ *
+ * Exported so the golden-report test can iterate the canonical list rather than
+ * restate it — the desktop plan's test previously asserted eleven fields and
+ * would have passed green while two axes vanished from the product. A list
+ * asserted against `Object.keys` of a real finding is what makes that a
+ * failure instead of a silence.
+ */
+export const FINDING_FIELDS = [
+    "finding",
+    "scope",
+    "affectedComponents",
+    "evidence",
+    "graphPath",
+    "runtimeEvidence",
+    "relevantChange",
+    "confidence",
+    "faultLayer",
+    "reliabilityClass",
+    "resolutionLevel",
+    "environmentLevel",
+    "recommendedAction",
+    "verificationStatus",
+];
+/**
+ * `E` — how many of the six channels named this finding, counting
+ * **channels** rather than observations, and ignoring any record whose
+ * `signal` is `null` (excluded by design — see {@link RuntimeEvidence}).
+ */
+export function independentSignalTypes(evidence) {
+    const distinct = new Set(evidence.map((item) => item.signal).filter((signal) => signal !== null));
+    // Indexed rather than cast: the set cannot exceed the declared channels, and
+    // the clamp keeps that provable to the compiler instead of asserted. The
+    // bound is read off the array so widening the vocabulary does not need this
+    // line changed too.
+    return SIGNAL_TYPE_COUNTS[Math.min(distinct.size, SIGNAL_TYPE_COUNTS.length - 1)] ?? 0;
+}
+/**
+ * `M` — direct mechanism evidence, `ai-governance-spec.md` §5.3. `true` when
+ * at least one runtime evidence record's resolved graph node id equals
+ * `failurePoint` — the hypothesis's named failure site — and that record is
+ * itself marked {@link RuntimeEvidence.directMechanism}, not merely
+ * co-occurring with the failure in time.
+ *
+ * A plain node-id match, the same identity mechanism §10 already requires for
+ * graph/runtime contradiction detection — deterministic, never a model
+ * judgement, which is what makes it a gate input rather than a slot output.
+ */
+export function directMechanismEvidence(evidence, failurePoint) {
+    return evidence.some((item) => item.directMechanism === true && item.nodeId === failurePoint);
+}
+/**
+ * `G3` — the evidence precondition, `ai-governance-spec.md` §4. `true` iff at
+ * least one runtime evidence record exists at all for this hypothesis,
+ * however it classifies under `E`/`M`. Restated from `root-cause-score.ts`'s
+ * own module doc: `RuntimeEvidence > 0` is a precondition on promotion above
+ * `unconfirmed`, never an addend folded into {@link reportCategory}'s step 2
+ * arithmetic.
+ */
+export function evidencePrecondition(evidence) {
+    return evidence.length > 0;
+}
+/**
+ * P11 — `ai-layer-plan.md` §11, `ai-governance-spec.md` §7. DEC-273's fault
+ * layer, computed rather than authored, for the one value that is currently
+ * groundable: {@link RuntimeEvidence.harnessFailure} is a structural fact
+ * (`descry-runtime` RT-219's self-observability channel either reported the
+ * harness dying or it did not) rather than a pattern inferred from a small
+ * number of examples, so classifying `"automation"` from it is not the kind
+ * of heuristic {@link FAULT_LAYERS}'s doc defers.
+ *
+ * **`product` / `environment` / `dependency` are deliberately not
+ * classified here.** No mechanism this codebase has built yet can positively
+ * distinguish them from evidence alone, and DEC-273's own three real
+ * classifications are explicitly too few to generalize a rule from. Every
+ * finding that is not an `automation` case is `"unknown"` — the honest
+ * default, not a placeholder for a missing case.
+ *
+ * A harness failure classifies `"automation"` even when domain evidence is
+ * also present: a collector that died mid-run can leave partial application
+ * evidence behind, and that evidence does not make the underlying failure
+ * any less Descry's own.
+ */
+export function classifyFaultLayer(evidence) {
+    // Priority order is not specified by the ruling for the three structural
+    // checks; automation goes first because a harness self-failure explains why
+    // nothing else on the run can be trusted, and dependency before environment
+    // because a pinned-dependency mismatch is the narrower, more specific fact
+    // of the two.
+    if (evidence.some((item) => item.harnessFailure === true))
+        return "automation";
+    if (evidence.some((item) => item.dependencyVersionMismatch === true))
+        return "dependency";
+    if (evidence.some((item) => item.environmentVersionMismatch === true))
+        return "environment";
+    return "unknown";
+}
+/**
+ * DEC-NEXT-fault-layer-empirical-confirmation.md — every fault-layer value
+ * carries its own confidence marker, independent of the finding's
+ * `Confidence`: `structural` (a comparison or rerun confirmed it) vs.
+ * `heuristic` (pattern-matched, no comparison run). *"A bare `environment` or
+ * `dependency` label must never be presented at the same visual weight as a
+ * `confirmed` finding unless it earned `structural`."*
+ *
+ * **Every path {@link classifyFaultLayer} can produce today is `structural`.**
+ * `product`'s heuristic and the no-comparison-available fallback for
+ * `dependency`/`environment` are the ones the ruling explicitly defers
+ * (`descry-ai-layer.md` §20's caution against generalizing from three
+ * classifications) and are not built — `heuristic` is reserved for whichever
+ * future function writes that fallback, not returned by anything here.
+ */
+export function faultLayerConfidence(_layer) {
+    return "structural";
+}
+/**
+ * `R` — the **minimum** resolution across the path.
+ *
+ * Minimum rather than average, first or last, and that single choice is what
+ * makes NOTE-4's control #6 (*a five-hop path inherits its worst hop's cap*)
+ * true by construction rather than by a second rule that could disagree.
+ *
+ * **An empty path derives R0**, the conservative floor: no hop resolved
+ * anything, so nothing above R0 has been established, and rule 2 says omit
+ * rather than overstate. Whether a purely runtime-observed finding should
+ * instead carry a synthetic R4 hop — so that a symptom confirmed on two
+ * channels is not capped to `unconfirmed` for having no traced cause — is a
+ * real question and is **not** decided here; filed as
+ * `documents/decisions-inbox/DEC-NEXT-empty-graph-path-resolution-floor.md`.
+ */
+export function minimumResolution(path) {
+    let lowest = 0;
+    let seen = false;
+    for (const hop of path) {
+        if (!seen || hop.resolution < lowest)
+            lowest = hop.resolution;
+        seen = true;
+    }
+    return derive(lowest);
+}
+/**
+ * `H` — testimony anywhere under the finding.
+ *
+ * Any load-bearing hop is enough: DEC-223's cap is not diluted by the number of
+ * honest hops beside it, because one unaudited assertion is one unaudited
+ * assertion however much resolved structure surrounds it.
+ */
+export function humanAssertedOnPath(path) {
+    return path.some((hop) => hop.humanAsserted === true);
+}
+/** Strongest first, so a cap is a `Math.min` over the rank. */
+const CATEGORY_RANK = {
+    confirmed: 2,
+    "strongly supported": 1,
+    unconfirmed: 0,
+};
+const BY_RANK = ["unconfirmed", "strongly supported", "confirmed"];
+/** Step 3's table — the highest category each class permits. */
+const CLASS_CEILING = {
+    A: "confirmed",
+    B: "strongly supported",
+    C: "unconfirmed",
+};
+/**
+ * **G3 + G4 — the evidence precondition and the category gate.**
+ * `ai-governance-spec.md` §4–§5, stage 14 of the V1 loop. G3 fires first; G4
+ * is three steps.
+ *
+ * ```
+ * G3      no runtime evidence at all -> unconfirmed, steps 1-3 below never run
+ * step 1  class = reliabilityCap(R, N, H)                        -> "A" | "B" | "C"
+ * step 2  M -> confirmed | !M && E >= 1 -> strongly supported | E == 0 -> unconfirmed
+ * step 3  A -> stands | B -> at most strongly supported | C -> at most unconfirmed
+ * ```
+ *
+ * **Resolution is an input to step 1 and appears nowhere in step 2.** An
+ * earlier form of this gate granted `confirmed` on *"the structural path
+ * resolves R2+ throughout"*, which reads resolution directly as a category
+ * threshold — re-implementing rule 3 in a second place, at a different
+ * threshold, with nothing tying the two together. `reliabilityCap()` is the one
+ * function that turns a resolution into a class, so step 1 calls it and never
+ * restates its table.
+ *
+ * The step 3 mapping is corroborated rather than invented: DEC-223 reached the
+ * class-B row independently, in its own words — *"a finding resting on
+ * testimony is at most strongly supported, never confirmed."*
+ *
+ * **`M` dominates step 2, not channel count** — `ai-governance-spec.md` §5.1.
+ * One piece of direct mechanism evidence — a reproduced test failure, an
+ * exception whose stack frame resolves to the hypothesis's node, a network
+ * response matching the predicted defect on the exact route — reaches
+ * `confirmed` regardless of how many channels agree. Two channels that merely
+ * co-occur without naming the node (§5.3's own example: a console error and a
+ * failed network call, neither correlated to the hypothesis) are `E = 2,
+ * M = false`: `strongly supported`, never `confirmed`. This is what the
+ * earlier `E >= 2 -> confirmed` form left open — §41 rule 12 (correlation must
+ * not become causation) re-entering through the gate built to enforce it.
+ *
+ * Two consequences worth stating because they are the point: `confirmed` at
+ * class B is unreachable, so the two labels can never disagree about one
+ * finding; and G3's precondition survives even inside step 2 alone, because
+ * zero runtime evidence forces both `M = false` and `E = 0` by construction
+ * (both are computed from the same evidence array) — the explicit
+ * short-circuit below is a second, independent enforcement of that same
+ * invariant, not a case step 2 would otherwise get wrong.
+ *
+ * **Ruled 2026-08-24 — `ai-governance-spec.md` §5, closing
+ * `documents/decisions-inbox/DEC-NEXT-hypothesis-states-vs-g4.md` and
+ * `documents/decisions-inbox/DEC-NEXT-independent-signal-type-inventory.md`.**
+ * `documents/architecture/descry-ai-layer.md` §12's hypothesis-state
+ * thresholds and this gate now agree on identical evidence — there is only
+ * one function; §12's states are machine states, never a label directly
+ * (`ai-layer-plan.md` §6 rule 2).
+ *
+ * Takes an object rather than positionals because several of the fields are
+ * adjacent booleans, and a swapped pair is a silent wrong answer rather than a
+ * compile error.
+ */
+export function reportCategory(inputs) {
+    // Step 1 — the structural ceiling. Computed unconditionally: it is a pure
+    // function of the graph path alone (R, N, H), so it stays well-defined —
+    // and useful, e.g. for display — even when G3 below short-circuits the
+    // category.
+    const reliability = reliabilityCap(inputs.resolution, inputs.nameLevel, inputs.humanAsserted);
+    // G3 — the evidence precondition, evaluated before step 2's arithmetic ever
+    // runs. Zero runtime evidence records at all means steps 2/3 are not
+    // consulted: a purely static finding cannot buy its way to `confirmed` by
+    // scoring well on the structural terms alone.
+    if (!inputs.hasRuntimeEvidence) {
+        return { category: "unconfirmed", reliabilityClass: derive(reliability) };
+    }
+    // Step 2 — evidence category. Resolution plays no part here. `M` dominates:
+    // one piece of direct mechanism evidence reaches `confirmed` regardless of
+    // channel count; channel count only decides among the cases `M` does not
+    // settle.
+    const observed = inputs.directMechanismEvidence
+        ? "confirmed"
+        : inputs.independentSignalTypes >= 1
+            ? "strongly supported"
+            : "unconfirmed";
+    // Step 3 — rule 3 applied one layer up. A cap, so it can only ever lower.
+    const ceiling = CLASS_CEILING[reliability];
+    const rank = Math.min(CATEGORY_RANK[observed], CATEGORY_RANK[ceiling]);
+    return {
+        category: BY_RANK[rank] ?? "unconfirmed",
+        reliabilityClass: derive(reliability),
+    };
+}
+/**
+ * Thrown by {@link rederive} when a record cannot be trusted to re-derive
+ * from — a missing, mistyped or out-of-range G4 input, or a finding whose
+ * `confidence` was never G4-gated in the first place.
+ *
+ * A thrown error rather than a best-effort fallback, because the alternative
+ * is a *silently* wrong reliability class — the one field the whole cap in
+ * rule 3 rests on — which is worse than none at all.
+ */
+export class RederivationError extends Error {
+    name = "RederivationError";
+}
+function fail(detail) {
+    throw new RederivationError(detail);
+}
+/**
+ * Runtime-validate one G4 input, regardless of what its static type claims.
+ *
+ * `record.inputs` is typed `G4Inputs` on {@link FindingRecord}, which is true
+ * for a caller holding a value this module produced — but the entire reason
+ * this validation exists is the storage boundary in between: a `JSON.parse`
+ * result is `any`, and nothing stops a writer from dropping a field, and
+ * nothing about TypeScript's guarantee survives that round trip. This is the
+ * one place that gap is closed.
+ */
+function checked(value, field, isValid) {
+    if (!isValid(value))
+        fail(`"${field}" is missing or invalid — got ${JSON.stringify(value)}`);
+    return value;
+}
+const isSignalTypeCount = (v) => typeof v === "number" && SIGNAL_TYPE_COUNTS.includes(v);
+const isResolutionLevel = (v) => typeof v === "number" && RESOLUTION_LEVELS.includes(v);
+const isBoolean = (v) => typeof v === "boolean";
+function validatedG4Inputs(inputs) {
+    return {
+        hasRuntimeEvidence: checked(inputs.hasRuntimeEvidence, "hasRuntimeEvidence", isBoolean),
+        independentSignalTypes: checked(inputs.independentSignalTypes, "independentSignalTypes", isSignalTypeCount),
+        directMechanismEvidence: checked(inputs.directMechanismEvidence, "directMechanismEvidence", isBoolean),
+        resolution: checked(inputs.resolution, "resolution", isResolutionLevel),
+        nameLevel: checked(inputs.nameLevel, "nameLevel", isBoolean),
+        humanAsserted: checked(inputs.humanAsserted, "humanAsserted", isBoolean),
+    };
+}
+/**
+ * Read a {@link FindingRecord} back as a `Finding` — the legitimate producer
+ * of `Derived<T>` on the read side of a storage boundary. The provisional
+ * escape hatch this module used to carry for the same purpose is gone; this
+ * is what made it deletable rather than permanent.
+ *
+ * Recomputes `reliabilityClass`, `resolutionLevel` and `confidence` from
+ * `record.inputs` by calling {@link reportCategory} — the one function that
+ * turns `E`/`R`/`N`/`H` into a class, never restated here. The recomputed
+ * values are authoritative; `record.finding`'s own copies of these three
+ * fields are not read at all, only overwritten, because the entire point is
+ * that this is a *re-derivation*, not a restoration of whatever the record
+ * happened to say.
+ *
+ * Throws {@link RederivationError} — rather than returning a plausible but
+ * wrong value — when `record.inputs` cannot be trusted (a missing, mistyped
+ * or out-of-range field) or when `record.finding.confidence` is not one of
+ * {@link EVIDENCE_CATEGORIES} (the finding was never G4-gated, so it has no
+ * G4 inputs to rederive from regardless of what `record.inputs` claims).
+ */
+export function rederive(record) {
+    if (!EVIDENCE_CATEGORIES.includes(record.finding.confidence)) {
+        fail(`cannot rederive confidence "${record.finding.confidence}": only the three G4-gated ` +
+            `categories (${EVIDENCE_CATEGORIES.join(", ")}) have recorded G4 inputs to rederive from.`);
+    }
+    const inputs = validatedG4Inputs(record.inputs);
+    const { category, reliabilityClass } = reportCategory(inputs);
+    return {
+        ...record.finding,
+        confidence: category,
+        reliabilityClass,
+        resolutionLevel: derive(inputs.resolution),
+    };
+}
+//# sourceMappingURL=finding.js.map

package/dist/finding.js.map

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

package/dist/hypothesis.d.ts

@@ -0,0 +1,130 @@
+/**
+ * The hypothesis state machine — `descry-ai-layer.md` §12, P19 of
+ * `ai-layer-plan.md` §11 (Phase 4).
+ *
+ * Six states, four transitions, all evaluated outside the model: *"Every
+ * transition is a deterministic rule evaluated outside the model. The model
+ * proposes; a rule disposes."* (`ai-layer-plan.md` §6). Same posture as
+ * G1–G4 (`../governance/*.ts`, `./finding.ts`) — a pure function over
+ * caller-supplied facts, never a prompt instruction.
+ *
+ * ## This is not a report category
+ *
+ * §12's own ruling, 2026-08-24 (Option B, `ai-governance-spec.md` §9): these
+ * six are *machine states*. `supported`/`confirmed` are not §19's
+ * `strongly supported`/`confirmed` report categories — only G4
+ * ({@link "./finding.ts".reportCategory}) assigns those, and it reads
+ * different inputs (resolution, name-level-ness, humanAsserted) that this
+ * module does not see at all. Do not compare a `HypothesisState` against a
+ * `ReportCategory` anywhere upstream of G4.
+ *
+ * ## What this module does not compute
+ *
+ * Three of the five inputs below are facts only the caller (the investigation
+ * loop, stage 12, P20) can supply, and are deliberately *not* derived here:
+ *
+ * - **`contradicted`** — whether evidence directly contradicts the
+ *   hypothesis. Detecting a contradiction is §10's own machinery (graph vs.
+ *   runtime disagreement, P21) — a larger, separate mechanism this module
+ *   does not reimplement.
+ * - **`roundLimitReached`** — whether this hypothesis has exhausted its
+ *   per-hypothesis tool-call budget. That accounting is `../governance/budget.ts`
+ *   (P18)'s job; this module only reacts to the boolean it produces.
+ * - **`toolCallsIssued`** — the raw count of tool calls issued so far.
+ *   `candidate → investigating` fires the instant the first call is issued,
+ *   before any result — even an empty or refused one — comes back, so this
+ *   cannot be derived from the evidence array's shape.
+ */
+import type { RuntimeEvidence } from "./finding.ts";
+/** §12's six states, in the order the architecture lists them. */
+export declare const HYPOTHESIS_STATES: readonly ["candidate", "investigating", "supported", "confirmed", "rejected", "unconfirmed"];
+export type HypothesisState = (typeof HYPOTHESIS_STATES)[number];
+/** States §12 marks terminal outright — the loop stops touching this hypothesis. */
+export declare const TERMINAL_HYPOTHESIS_STATES: readonly ["confirmed", "rejected", "unconfirmed"];
+export declare function isTerminalHypothesisState(state: HypothesisState): boolean;
+/**
+ * Why an `unconfirmed` result was reached. `ai-layer-plan.md` §6 point 4 names
+ * three: `round-limit` is the one transition §12 actually defines
+ * (`any state → unconfirmed`, the round limit reached before `confirmed` or
+ * `rejected`); `superseded` and `unreachable` are named by the plan as
+ * additional reasons but have no defined trigger here — **disclosed, not
+ * modeled**, same as every other gap this project leaves rather than guesses
+ * a rule for.
+ */
+export declare const UNCONFIRMED_REASONS: readonly ["round-limit"];
+export type UnconfirmedReason = (typeof UNCONFIRMED_REASONS)[number];
+/**
+ * Everything {@link deriveHypothesisState} reads. Computed fresh each round
+ * from the hypothesis's accumulated evidence — this is a derivation, not an
+ * incremental transition-application function, matching G3/G4's own shape
+ * (`../governance/*.ts` calls this the same way `reportCategory` is called:
+ * full inputs in, one output out, every time).
+ */
+export interface HypothesisStateInput {
+    /** How many tool calls have been issued investigating this hypothesis. `0` means still `candidate`. */
+    readonly toolCallsIssued: number;
+    /**
+     * The failure-site node id this hypothesis names — what
+     * {@link directMechanismEvidence} matches evidence against. `hash(repo,
+     * kind, qualified symbol path)`, never a file path.
+     */
+    readonly failurePoint: string;
+    /** Every runtime evidence record gathered for this hypothesis so far. */
+    readonly runtimeEvidence: readonly RuntimeEvidence[];
+    /**
+     * Whether a graph-structural fact — independent of any runtime
+     * observation — supports this hypothesis. One of §12's two named
+     * `supported` sources (*"a graph fact plus a runtime observation"*); the
+     * other is two distinct runtime channels, already counted via
+     * `runtimeEvidence`.
+     */
+    readonly hasGraphFact: boolean;
+    /**
+     * Caller-supplied: at least one gathered evidence record directly
+     * contradicts the hypothesis. Not computed here — see the module doc.
+     */
+    readonly contradicted: boolean;
+    /**
+     * Caller-supplied: this hypothesis has reached its round limit (§41 rule
+     * 17) without reaching `confirmed` or `rejected`. Not computed here — see
+     * the module doc.
+     */
+    readonly roundLimitReached: boolean;
+}
+export interface HypothesisStateResult {
+    readonly state: HypothesisState;
+    /** Present only when `state === "unconfirmed"`. */
+    readonly unconfirmedReason?: UnconfirmedReason;
+}
+/**
+ * How many independent evidence sources name this hypothesis — a graph fact
+ * counts as one, and each of the six {@link RuntimeSignalType} channels
+ * counts once however many records carry it (the same dedup-by-channel
+ * discipline `independentSignalTypes` uses for G4's `E`, applied to a wider
+ * source set).
+ *
+ * **Not `E`.** G4's `E` is a closed count over exactly the six runtime
+ * channels (`ai-governance-spec.md` §5.2) and a graph fact is not one of
+ * them by design — conflating the two is exactly the "machine state leaking
+ * into report vocabulary" failure §12's own ruling exists to prevent. This
+ * function answers a different question — *how many independent sources
+ * back this hypothesis, for the state machine's own `supported` transition*
+ * — and must never be passed anywhere G4 reads.
+ */
+export declare function independentEvidenceSources(runtimeEvidence: readonly RuntimeEvidence[], hasGraphFact: boolean): number;
+/**
+ * Derive this hypothesis's current state from its accumulated evidence.
+ * Never throws — this is a check, not an execution of the thing it is
+ * checking.
+ *
+ * Precedence, most decisive first: a caller-flagged contradiction always
+ * rejects, ahead of mechanism evidence — a sane caller never sets both, but
+ * rejection winning is the conservative reading. Direct mechanism evidence
+ * confirms next, regardless of round limit — §12's `confirmed` transition
+ * names no round bound. Only after both are checked does the round limit
+ * force `unconfirmed`. Below that, two or more independent sources reach
+ * `supported`; otherwise the hypothesis is still `investigating` once at
+ * least one call has been issued, or `candidate` before the first.
+ */
+export declare function deriveHypothesisState(input: HypothesisStateInput): HypothesisStateResult;
+//# sourceMappingURL=hypothesis.d.ts.map

package/dist/hypothesis.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hypothesis.d.ts","sourceRoot":"","sources":["../src/hypothesis.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAqB,MAAM,cAAc,CAAC;AAGvE,kEAAkE;AAClE,eAAO,MAAM,iBAAiB,8FAOpB,CAAC;AAEX,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,iBAAiB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEjE,oFAAoF;AACpF,eAAO,MAAM,0BAA0B,mDAAoD,CAAC;AAE5F,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAEzE;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,mBAAmB,0BAA2B,CAAC;AAC5D,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,mBAAmB,CAAC,CAAC,MAAM,CAAC,CAAC;AAErE;;;;;;GAMG;AACH,MAAM,WAAW,oBAAoB;IACnC,uGAAuG;IACvG,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC;;;;OAIG;IACH,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,yEAAyE;IACzE,QAAQ,CAAC,eAAe,EAAE,SAAS,eAAe,EAAE,CAAC;IACrD;;;;;;OAMG;IACH,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAC/B;;;OAGG;IACH,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAC/B;;;;OAIG;IACH,QAAQ,CAAC,iBAAiB,EAAE,OAAO,CAAC;CACrC;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,KAAK,EAAE,eAAe,CAAC;IAChC,mDAAmD;IACnD,QAAQ,CAAC,iBAAiB,CAAC,EAAE,iBAAiB,CAAC;CAChD;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,0BAA0B,CACxC,eAAe,EAAE,SAAS,eAAe,EAAE,EAC3C,YAAY,EAAE,OAAO,GACpB,MAAM,CAOR;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,oBAAoB,GAAG,qBAAqB,CAsBxF"}