@descryy/ir 0.1.0

package/dist/finding.d.ts

@@ -0,0 +1,567 @@
+/**
+ * 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 type { ReliabilityClass } from "./reliability.ts";
+import type { ResolutionLevel } from "./ir.ts";
+import type { EdgeType } from "./vocabulary.ts";
+/**
+ * A value that may only be produced by the function that derives it.
+ *
+ * §20 says `Reliability class` and `Resolution level` are *"derived, never
+ * authored"*, and a doc comment saying so is not a mechanism. The brand makes
+ * the sentence hold in the type system: a bare `"A"` is not assignable to
+ * `Derived<ReliabilityClass>`, so the only way to fill either field is to call
+ * the function that computes it.
+ *
+ * A brand rather than an opaque class because these values still have to
+ * compare, switch and serialize as the plain `"A"` / `4` they are. Nothing at
+ * runtime carries the property — it exists only to make the assignment fail.
+ */
+export interface DerivationBrand {
+    /**
+     * Never present at runtime, and typed `never` so it cannot be satisfied by
+     * writing it out. The only routes to a branded value are the derivations
+     * below and {@link rederive}, the read-path re-derivation from a stored
+     * {@link FindingRecord}.
+     */
+    readonly derivedNotAuthored: never;
+}
+export type Derived<T> = T & DerivationBrand;
+/**
+ * §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 declare const REPORT_CATEGORIES: readonly ["confirmed", "strongly supported", "unconfirmed", "not analysable", "unsupported"];
+export type ReportCategory = (typeof REPORT_CATEGORIES)[number];
+/**
+ * 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 declare const EVIDENCE_CATEGORIES: readonly ["confirmed", "strongly supported", "unconfirmed"];
+export type EvidenceCategory = (typeof EVIDENCE_CATEGORIES)[number];
+/**
+ * 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 declare const FAULT_LAYERS: readonly ["product", "automation", "environment", "dependency", "unknown"];
+export type FaultLayer = (typeof FAULT_LAYERS)[number];
+/**
+ * `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 declare const FAULT_LAYER_CONFIDENCES: readonly ["structural", "heuristic"];
+export type FaultLayerConfidence = (typeof FAULT_LAYER_CONFIDENCES)[number];
+/**
+ * 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 declare const ENVIRONMENT_LEVELS: readonly [1, 2, 3, 4];
+export type EnvironmentLevel = (typeof ENVIRONMENT_LEVELS)[number];
+/**
+ * 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 declare const RUNTIME_SIGNAL_TYPES: readonly ["browser-visual", "browser-console", "network", "backend-log", "database", "external-service"];
+export type RuntimeSignalType = (typeof RUNTIME_SIGNAL_TYPES)[number];
+/**
+ * Legal values of `E`. Bounded by the six channels above, hence 0–6.
+ */
+export declare const SIGNAL_TYPE_COUNTS: readonly [0, 1, 2, 3, 4, 5, 6];
+export type SignalTypeCount = (typeof SIGNAL_TYPE_COUNTS)[number];
+/**
+ * One runtime observation.
+ *
+ * `signal` names which of the six {@link RUNTIME_SIGNAL_TYPES} channels this
+ * belongs to, or `null` when the record is excluded from `E` by design — a
+ * reproduced test failure (whose evidentiary weight is
+ * {@link directMechanismEvidence}'s alone, never double-counted as a channel
+ * too), a collector error, a harness action, or any type this table has not
+ * ruled on yet. `nodeId`/`directMechanism` are what
+ * {@link directMechanismEvidence} reads to compute `M` — both optional and
+ * absent by default, so a record making no mechanism claim says nothing
+ * rather than false.
+ */
+export interface RuntimeEvidence {
+    readonly signal: RuntimeSignalType | null;
+    /** What was observed, in the collector's own words. Never summarised here. */
+    readonly detail: string;
+    /**
+     * The graph node id this observation resolves to, if any — `hash(repo,
+     * kind, qualified symbol path)`, never a file path, so the match survives a
+     * rename the way a path comparison would not.
+     */
+    readonly nodeId?: string | null;
+    /**
+     * `true` when this record's own event type directly enacts the claimed
+     * failure mode at `nodeId` — not merely co-occurs with it in time.
+     * `ai-governance-spec.md` §5.3's three cases: a reproduced test failure
+     * whose assertion/stack frame resolves there, an exception or backend-log
+     * line whose stack frame resolves there, or a network response matching the
+     * predicted defect on the exact route the hypothesis names.
+     */
+    readonly directMechanism?: boolean;
+    /**
+     * `true` when this record is Descry's own harness observing itself fail —
+     * `descry-runtime` RT-219's `source: "harness"` channel — rather than an
+     * observation of the application under test. Independent of `signal`,
+     * which stays `null` here for the same reason it is `null` for
+     * `COLLECTOR_ERROR`/harness-action records: this is not one of the six
+     * domain channels and must not inflate `E`. Feeds {@link classifyFaultLayer}
+     * alone. Optional and absent by default, so an ordinary domain record says
+     * nothing.
+     */
+    readonly harnessFailure?: boolean;
+    /**
+     * `true` when this record is a structural comparison finding the lockfile's
+     * declared dependency version does not match the version actually resolved
+     * at runtime — `DEC-NEXT-fault-layer-empirical-confirmation.md`'s
+     * `dependency` mechanism. Same shape as `harnessFailure`: independent of
+     * `signal` (stays `null` here, not one of the six domain channels), never
+     * inflates `E`, feeds {@link classifyFaultLayer} alone. Optional and absent
+     * by default.
+     */
+    readonly dependencyVersionMismatch?: boolean;
+    /**
+     * `true` when this record is a structural comparison finding the declared
+     * (CI-configured) runner version does not match the version observed at
+     * execution — the same ruling's `environment` mechanism. Same shape and
+     * exclusions as `dependencyVersionMismatch`.
+     */
+    readonly environmentVersionMismatch?: boolean;
+}
+/**
+ * One hop of the structural path a finding rests on.
+ *
+ * Carries its own `resolution` because rule 3's cap is a property of the
+ * *weakest* hop, and a path that reports only an aggregate cannot be audited
+ * for which hop cost it the class.
+ */
+export interface GraphPathHop {
+    /** Source node ID — `hash(repo, kind, qualified symbol path)`, never a path. */
+    readonly from: string;
+    /** Target node ID. */
+    readonly to: string;
+    readonly edgeType: EdgeType;
+    /** How well this one hop was resolved, R0–R4. */
+    readonly resolution: ResolutionLevel;
+    /**
+     * DEC-223 — this edge exists because a person confirmed a value for a
+     * refusal-ledger row, not because analysis resolved it. Optional and
+     * defaulting to absent, so an ordinary structural hop says nothing.
+     */
+    readonly humanAsserted?: boolean;
+}
+/** One thing in scope that was not exercised, and why. */
+export interface UntestedScope {
+    readonly scope: string;
+    /**
+     * Named and verbatim. An untested item with no reason is the silence this
+     * whole field exists to prevent — rule 7 at the level of a single record.
+     */
+    readonly reason: string;
+}
+/**
+ * Coverage — a different axis from confidence, and the carrier of the
+ * untested-scope disclosure since §19's five categories dropped *not tested*.
+ *
+ * The documents name this field and describe what it must report — *what was in
+ * scope, what was actually exercised, and what was not, with a reason for each
+ * gap* — without enumerating a set of status values. Modelled as that
+ * structure rather than as an invented three-word vocabulary, because a label
+ * like *"partially verified"* answers none of the three questions.
+ */
+export interface VerificationStatus {
+    /**
+     * What this finding's claim was actually exercised against. An empty list is
+     * a legal, meaningful answer — *nothing was exercised* — and is not the same
+     * as an unknown one.
+     */
+    readonly exercised: readonly string[];
+    /** Every part of the scope that was not exercised, each with its reason. */
+    readonly notExercised: readonly UntestedScope[];
+}
+/**
+ * §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 declare const FINDING_FIELDS: readonly ["finding", "scope", "affectedComponents", "evidence", "graphPath", "runtimeEvidence", "relevantChange", "confidence", "faultLayer", "reliabilityClass", "resolutionLevel", "environmentLevel", "recommendedAction", "verificationStatus"];
+export type FindingField = (typeof FINDING_FIELDS)[number];
+/** §20's finding record. Fourteen fields; see the module doc for why not fifteen. */
+export interface Finding {
+    /** The claim itself, one statement. */
+    readonly finding: string;
+    /** What was being checked when this surfaced. */
+    readonly scope: string;
+    /**
+     * Node IDs, not display names — identity is `hash(repo, kind, qualified
+     * symbol path)` and survives renames, which a display name does not. The
+     * renderer resolves them for presentation.
+     */
+    readonly affectedComponents: readonly string[];
+    /** The enumerated grounds for the claim, static and observed alike. */
+    readonly evidence: readonly string[];
+    /** The structural path, hop by hop. Feeds {@link minimumResolution}. */
+    readonly graphPath: readonly GraphPathHop[];
+    /**
+     * Observations from the six channels, plus any direct-mechanism-only
+     * records (e.g. a reproduced test failure). Feeds
+     * {@link independentSignalTypes} and {@link directMechanismEvidence}.
+     */
+    readonly runtimeEvidence: readonly RuntimeEvidence[];
+    /**
+     * The change implicated, if one is. `null` means *no change is implicated*,
+     * which is a finding about existing code — not *"we did not check"*, which
+     * belongs in {@link VerificationStatus}.
+     */
+    readonly relevantChange: string | null;
+    /** §19's category, computed at G4 and capped by `reliabilityClass`. */
+    readonly confidence: ReportCategory;
+    /** DEC-273's axis. Independent of `confidence`. */
+    readonly faultLayer: FaultLayer;
+    /** Derived — {@link reportCategory}, which calls `reliabilityCap()`. */
+    readonly reliabilityClass: Derived<ReliabilityClass>;
+    /** Derived — {@link minimumResolution} over `graphPath`. */
+    readonly resolutionLevel: Derived<ResolutionLevel>;
+    /** Architecture §16.3. Authored: it is a fact about the run, not the claim. */
+    readonly environmentLevel: EnvironmentLevel;
+    readonly recommendedAction: string;
+    /** Coverage. A separate axis; see {@link VerificationStatus}. */
+    readonly verificationStatus: 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 declare function independentSignalTypes(evidence: readonly RuntimeEvidence[]): SignalTypeCount;
+/**
+ * `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 declare function directMechanismEvidence(evidence: readonly RuntimeEvidence[], failurePoint: string): boolean;
+/**
+ * `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 declare function evidencePrecondition(evidence: readonly RuntimeEvidence[]): boolean;
+/**
+ * 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 declare function classifyFaultLayer(evidence: readonly RuntimeEvidence[]): FaultLayer;
+/**
+ * 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 declare function faultLayerConfidence(_layer: FaultLayer): FaultLayerConfidence;
+/**
+ * `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 declare function minimumResolution(path: readonly GraphPathHop[]): Derived<ResolutionLevel>;
+/**
+ * `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 declare function humanAssertedOnPath(path: readonly GraphPathHop[]): boolean;
+/**
+ * G3's precondition plus G4's four inputs — and, wrapped in
+ * {@link FindingRecord}, the derivation record a finding is stored with.
+ *
+ * Recording these beside the finding is what `documents/plans/ai-layer-plan.md`
+ * §12's *"replay must reproduce the finding exactly"* requires, and it is also
+ * what lets a stored finding's derived axes be re-derived through
+ * {@link rederive} rather than restored by cast.
+ */
+export interface G4Inputs {
+    /**
+     * G3 — {@link evidencePrecondition} over the runtime evidence. `false`
+     * means step 2/3 below never run and the category is `unconfirmed`
+     * unconditionally, regardless of what `independentSignalTypes` or
+     * `directMechanismEvidence` claim.
+     */
+    readonly hasRuntimeEvidence: boolean;
+    /** `E` — {@link independentSignalTypes} over the runtime evidence, 0–6. */
+    readonly independentSignalTypes: SignalTypeCount;
+    /** `M` — {@link directMechanismEvidence} over the runtime evidence. */
+    readonly directMechanismEvidence: boolean;
+    /** `R` — {@link minimumResolution} over the graph path. */
+    readonly resolution: ResolutionLevel;
+    /** `N` — the claim is about a name, not a shape. See `reliabilityCap`. */
+    readonly nameLevel: boolean;
+    /** `H` — {@link humanAssertedOnPath} over the graph path. */
+    readonly humanAsserted: boolean;
+}
+/** G4's answer: both coupled values, from one call. */
+export interface G4Result {
+    /** The category the finding may be reported as, after the cap. */
+    readonly category: EvidenceCategory;
+    /**
+     * The class that capped it. Returned rather than left to the caller to
+     * recompute — the defect DEC-276 named in the previous G4 was rule 3 living
+     * in two places with nothing tying them together, and two call sites is two
+     * places.
+     */
+    readonly reliabilityClass: Derived<ReliabilityClass>;
+}
+/**
+ * **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 declare function reportCategory(inputs: G4Inputs): G4Result;
+/**
+ * A G4-gated finding as it is stored: the `Finding` plus the inputs that
+ * produced its derived axes.
+ *
+ * **Scoped to the findings §19's evidence categories actually govern.** The
+ * other two categories — `not analysable`, `unsupported` — are refusals
+ * inherited from the static case (see {@link EVIDENCE_CATEGORIES}'s doc) and
+ * were never subject to `E`/`R`/`N`/`H` at all, so they have no G4 inputs to
+ * record. Storing those is a different, currently unbuilt, concern — see
+ * `documents/architecture/descry-ai-layer.md` §20.3's static-pipeline gate.
+ *
+ * **A wrapper, not an extension: `Finding` stays exactly §20's fourteen
+ * fields.** This is what gets stored; {@link rederive} is what a reader gets
+ * back. Storage itself is P2/P24 — `descry-desktop/packages/session` per
+ * DEC-265 — and is not built here. This package builds the shape and the
+ * re-derivation function; whoever writes the store consumes them.
+ */
+export interface FindingRecord {
+    readonly finding: Finding;
+    readonly inputs: G4Inputs;
+}
+/**
+ * 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 declare class RederivationError extends Error {
+    readonly name = "RederivationError";
+}
+/**
+ * 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 declare function rederive(record: FindingRecord): Finding;
+//# sourceMappingURL=finding.d.ts.map

package/dist/finding.d.ts.map

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