@davesheffer/hunch 1.31.1 → 1.32.0

package/dist/core/commitrepair.js

@@ -0,0 +1,238 @@
+/**
+ * Deterministic repair for a decision's commit provenance after a squash-merge.
+ *
+ * A squash-merge produces one new commit whose parent is the pre-merge target
+ * tip — the original per-commit SHAs it squashed are never ancestors of it.
+ * This module matches an orphaned decision to the ONE newly-merged commit
+ * whose changed files are a superset of the decision's related_files. Zero or
+ * multiple qualifying candidates means "don't guess" — same discipline as
+ * repair.ts's rename-repair.
+ */
+import { createHash } from "node:crypto";
+import { replaceExact } from "./refrepair.js";
+/** Bind review to the ordered queue and which targets are currently resolvable.
+ * Queue order matters: duplicate decision ids use first-match selection. */
+export function commitRepairReviewHash(queued, withheld = new Set()) {
+    const snapshot = queued.map((r) => ({ id: r.id, from: r.from, to: r.to, withheld: withheld.has(r) }));
+    return `sha256:${createHash("sha256").update(JSON.stringify(snapshot)).digest("hex")}`;
+}
+/** A scope entry is exact (usable as a match key) only when it contains no glob syntax. */
+function isExactPath(entry) {
+    return !!entry && !/[*?[\]{}]/.test(entry);
+}
+/** Live decisions whose cited commit still exists here but is no longer an
+ *  ancestor of the current tip. Only "orphaned" qualifies: a commit that
+ *  doesn't resolve at all ("unresolvable") is out of repair scope, and a git
+ *  failure ("unknown") must never be mistaken for repair-eligible. */
+export function orphanedCommitDecisions(decisions, status) {
+    return decisions.filter((d) => {
+        if (d.status === "superseded" || d.status === "rejected")
+            return false;
+        if (!d.commit)
+            return false;
+        return status(d.commit) === "orphaned";
+    });
+}
+/** Match each orphaned decision to exactly one candidate whose changed files are
+ *  a superset of the decision's related_files (non-empty, no globs). */
+export function planCommitRepair(orphaned, candidates) {
+    const rewrites = [];
+    for (const d of orphaned) {
+        const files = (d.related_files ?? []).filter(isExactPath);
+        if (!files.length)
+            continue;
+        const matches = candidates.filter((c) => files.every((f) => c.files.includes(f)));
+        if (matches.length !== 1)
+            continue; // zero or ambiguous: never guess
+        rewrites.push({ id: d.id, from: d.commit, to: matches[0].sha });
+    }
+    return { rewrites, records: [...new Set(rewrites.map((r) => r.id))] };
+}
+/** Whether a queued rewrite is still worth ASKING about: the decision it
+ *  names still exists, still cites the commit the entry expects to replace (a
+ *  decision that already moved on would make repairDecisionCommit's own
+ *  stale-plan bail refuse it), and hasn't since been superseded/rejected —
+ *  same exclusion as orphanedCommitDecisions, since repairing dead history's
+ *  provenance isn't worth asking about. Backs the read-only escalation
+ *  surface only (commitRepairEscalations) — absence-means-not-askable is
+ *  safe there because it self-heals the moment visibility returns.
+ *  repair-provenance itself does NOT use this: it reads the full store and
+ *  may legitimately list (dry-run) or leave queued (apply) an entry this
+ *  predicate would call not-live, so the escalation surface and the CLI can
+ *  disagree about the same entry — see deadRewrites and resolvedRewriteIds
+ *  for the CLI's own, looser-on-purpose reasoning. */
+export function liveRewrites(queued, decisions) {
+    const byId = new Map(decisions.map((d) => [d.id, d]));
+    return queued.filter((r) => {
+        const d = byId.get(r.id);
+        return !!d && d.commit === r.from && d.status !== "superseded" && d.status !== "rejected";
+    });
+}
+/** Entries a decision has demonstrably outgrown: the decision IS present in
+ *  `decisions`, and it either moved on from `from` or has since been
+ *  superseded/rejected. An id this list can't see is deliberately NOT
+ *  included — absence is a property of the READER (a branch checkout that
+ *  predates the decision, an unmounted private overlay), not proof the match
+ *  is stale. This predicate backs a DESTRUCTIVE prune (repair-provenance
+ *  deletes what it returns from the queue file); repairqueue.ts's own
+ *  docstring is why that matters — the queue is the one durable record of a
+ *  match once ORIG_HEAD moves on and the matched-away commit can be gc'd, so
+ *  deleting an entry on a merely-absent id would destroy it unrecoverably.
+ *  Contrast liveRewrites, whose absence-means-not-askable rule is safe on
+ *  the read-only escalation surface, which self-heals once visibility
+ *  returns.
+ *
+ *  Caveat: "demonstrably" is only as strong as this run's view of
+ *  `decisions`, which comes from the same git-tracked, branch-dependent
+ *  files that motivate treating ABSENCE as inconclusive. A decision whose
+ *  `commit`/`status` genuinely differ between branches (e.g. a repair
+ *  already applied and committed on one branch, checked out here from a
+ *  branch that predates it) could still read as "moved on" when it hasn't,
+ *  from this branch's perspective. Far narrower than the absence case this
+ *  function exists to fix, and not addressed here. */
+export function deadRewrites(queued, decisions) {
+    const byId = new Map(decisions.map((d) => [d.id, d]));
+    return queued.filter((r) => {
+        const d = byId.get(r.id);
+        return !!d && (d.commit !== r.from || d.status === "superseded" || d.status === "rejected");
+    });
+}
+/** Among `toApply` (the queued/matched candidates this run is about to act
+ *  on), the ids repair-provenance may treat as RESOLVED once it's done: the
+ *  decision is present in `decisions` this run, whether or not
+ *  repairDecisionCommit actually changed it (a present decision that already
+ *  moved on is "resolved" too — repairDecisionCommit's own bail refused it,
+ *  and there is nothing more this run can do about it). An id whose decision
+ *  is NOT present is never resolved — same reasoning as deadRewrites:
+ *  absence is the reader's transient view, not proof the match is settled,
+ *  so it must stay queued for a run where the decision is visible again. */
+export function resolvedRewriteIds(toApply, decisions) {
+    const seen = new Set(decisions.map((d) => d.id));
+    return new Set(toApply.filter((r) => seen.has(r.id)).map((r) => r.id));
+}
+/** Remove any match whose exact {id, from, to} triple was already tombstoned
+ *  by an earlier `--drop` — otherwise a later merge that re-derives the
+ *  identical candidate would re-queue exactly what the human rejected. A
+ *  match sharing {id, from} but proposing a different `to` is unaffected: it
+ *  is a different proposal, not the rejected one.
+ *
+ *  Preserves object identity for every surviving entry (a plain filter, never
+ *  a clone or a rebuild) — repair-provenance's own action relies on this to
+ *  diff its swept-vs-active queue by reference (`queue.filter(r =>
+ *  !active.includes(r))`) rather than re-spelling the {id, from, to} key a
+ *  third time. Do not change this to normalize or reconstruct entries
+ *  without updating that call site too. */
+export function withoutDropped(rewrites, dropped) {
+    if (!dropped.length)
+        return [...rewrites];
+    const tombstoned = new Set(dropped.map((t) => `${t.id}\0${t.from}\0${t.to}`));
+    return rewrites.filter((r) => !tombstoned.has(`${r.id}\0${r.from}\0${r.to}`));
+}
+/** Append newly-dropped {id, from, to} triples to the tombstone list,
+ *  deduped — same append-only, dedupe-by-key shape as mergeRewrites. */
+export function addDropped(newly, existing) {
+    const seen = new Set(existing.map((t) => `${t.id}\0${t.from}\0${t.to}`));
+    const additions = newly.filter((t) => !seen.has(`${t.id}\0${t.from}\0${t.to}`));
+    return [...existing, ...additions];
+}
+/** Combine a freshly-computed plan's rewrites with anything already queued
+ *  (src/core/repairqueue.ts) from an earlier detection. A fresh match —
+ *  computed just now, against the current range — overrides a queued one for
+ *  the same decision; queued entries no longer reachable are simply not
+ *  repeated by the fresh scan.
+ *
+ *  Overrides by object identity, targeting exactly the one queued entry
+ *  firstFor (id) would pick — the same first-match rule --drop applies, and
+ *  the same identity-not-id targeting the dead-entry prune applies (#53; the
+ *  prune itself removes every provably-dead entry, not just a first match).
+ *  A corrupted queue file, a hand edit, or a bug upstream could otherwise
+ *  carry a SECOND entry sharing that id; overriding by id alone would
+ *  silently destroy that still-queued sibling too, with no tombstone and no
+ *  way to recover it, even though it was never the entry that would have
+ *  been applied. Any such sibling is left queued and untouched.
+ *
+ *  How a survivor resolves: the dead-entry prune (deadRewrites), once
+ *  --apply has moved the decision past the sibling's `from`; or a --drop
+ *  whose tombstone matches the sibling's exact {id, from, to} — the same
+ *  --drop that dropped the fresh entry, when the sibling happens to share
+ *  its triple (the drop's own re-sweep, withoutDropped, catches it too), a
+ *  second explicit --drop otherwise. NOT a later fresh detection: by this
+ *  same first-match rule it always overrides the fresh entry sitting ahead
+ *  of it, never the sibling. */
+export function mergeRewrites(fresh, queued) {
+    const overridden = new Set();
+    for (const r of fresh) {
+        const first = firstFor(queued, r.id);
+        if (first)
+            overridden.add(first);
+    }
+    return [...fresh, ...queued.filter((r) => !overridden.has(r))];
+}
+/** Partition the entries --apply is about to act on by whether their proposed
+ *  `to` commit actually exists in this repository. `existing` is
+ *  `commitsExist`'s result over every `to` in `toApply`: `null` means the
+ *  check itself failed to run (not a git repo, git missing, timeout) and is
+ *  treated as fail-open, same discipline as drift.ts's own use of
+ *  commitsExist — nothing is withheld just because the check couldn't run.
+ *
+ *  A corrupted queue file, a hand-edited entry, or a bug upstream could
+ *  otherwise get a `to` that never resolves to a real commit written
+ *  straight into a decision's `commit` field and provenance evidence, then
+ *  auto-committed into shared team memory. `withheld` entries must stay
+ *  queued (never deleted, never passed to repairDecisionCommit) — the queue
+ *  file is the one durable record of the match, same reasoning as
+ *  deadRewrites/resolvedRewriteIds.
+ *
+ *  Both returned arrays preserve object identity (never clones or rebuilds
+ *  an entry) — the CLI's queue sweep and its "still queued" reporting both
+ *  key a `Set` off the exact objects in `withheld`, by reference, precisely
+ *  because a corrupted queue file can carry two entries sharing an id (one
+ *  resolvable, one not): an id alone can't tell them apart. Do not change
+ *  this to normalize or reconstruct entries without updating those call
+ *  sites too — same caveat withoutDropped's own docstring carries. */
+export function withheldForUnresolvableTo(toApply, existing) {
+    if (existing === null)
+        return { applicable: [...toApply], withheld: [] };
+    const applicable = [];
+    const withheld = [];
+    for (const r of toApply)
+        (existing.has(r.to) ? applicable : withheld).push(r);
+    return { applicable, withheld };
+}
+/** The one rule for which entry wins when more than one shares a decision id
+ *  (a corrupted queue file, a hand edit, or a bug upstream): first match, by
+ *  construction. Every caller goes through here so no two can independently
+ *  drift on which entry "won" — this file's own duplicate-id queue handling
+ *  has drifted between call sites three times already (see withoutDropped's,
+ *  withheldForUnresolvableTo's, and mergeRewrites' own docstrings). */
+export function firstFor(entries, id) {
+    return entries.find((r) => r.id === id);
+}
+/** pickRewrite is firstFor scoped to a plan's own rewrites (planCommitRepair
+ *  itself never produces same-id duplicates, but a plan carrying them isn't
+ *  ruled out here — see firstFor). repairDecisionCommit uses this to decide
+ *  what to WRITE; a caller that needs to know which entry WOULD be picked
+ *  without writing anything (the CLI's --apply summary and queue sweep)
+ *  calls this same function, so the two can never independently drift on
+ *  which entry "won". */
+export function pickRewrite(plan, id) {
+    return firstFor(plan.rewrites, id);
+}
+/** Pure: rewrite `commit` for one decision, and its matching `commit:<sha>`
+ *  evidence entry too if one is present (replaceExact is a no-op when the
+ *  evidence array never cited the old sha) — or return the same reference
+ *  when the plan doesn't touch it. If the record moved on since the plan was
+ *  built (its commit no longer equals the plan's `from`), bail entirely
+ *  rather than applying a now-stale match. */
+export function repairDecisionCommit(d, plan) {
+    const mine = pickRewrite(plan, d.id);
+    if (!mine || d.commit !== mine.from)
+        return d;
+    const evidence = replaceExact(d.provenance.evidence, `commit:${mine.from}`, `commit:${mine.to}`);
+    return {
+        ...d,
+        commit: mine.to,
+        provenance: { ...d.provenance, evidence: evidence.values },
+    };
+}
+//# sourceMappingURL=commitrepair.js.map

package/dist/core/compare.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Multi-candidate verdict (roadmap addendum, "evaluate 5 solutions"). Given several
+ * candidate refs (branches/commits — e.g. N agent-generated solutions to one task),
+ * replay each one's diff against the graph via the SAME deterministic merge-verdict
+ * (buildCheckReport + verdict) and RANK them: the candidate that fits the architecture
+ * best is the one that trips the fewest in-force invariants, reverses no decisions, and
+ * adds the least sprawl. No model in the ranking — it's set-intersection over the graph.
+ */
+import type { HunchStore } from "../store/hunchStore.js";
+export interface CandidateResult {
+    ref: string;
+    verdict: "block" | "warn" | "pass";
+    blocking: number;
+    direct: number;
+    near: number;
+    vetoes: number;
+    redundant: number;
+    files: number;
+    error?: string;
+}
+export declare function compareCandidates(store: HunchStore, root: string, base: string, candidates: string[]): CandidateResult[];

package/dist/core/config.d.ts

@@ -0,0 +1,20 @@
+import type { HunchPaths } from "./paths.js";
+/** How firmly the agent lifecycle hook (`hunch hook`) enforces Hunch on edits:
+ *   off      — emit nothing (hook is a no-op).
+ *   advisory — inject the relevant Hunch slice (decisions/constraints/bugs) as
+ *              context before the edit. The default: always informs, never blocks.
+ *   firm     — advisory + explicitly flag invariants in the edited file's scope.
+ *   strict   — firm + DENY an edit that hits a BLOCKING invariant (direct or via
+ *              blast radius), feeding the invariant back as the refusal reason. */
+export type Firmness = "off" | "advisory" | "firm" | "strict";
+export declare const FIRMNESS_LEVELS: readonly Firmness[];
+export declare const DEFAULT_FIRMNESS: Firmness;
+export interface HunchConfig {
+    firmness: Firmness;
+}
+export declare function isFirmness(v: unknown): v is Firmness;
+/** Read `.hunch/config.json`. A missing/unparseable file, or an unknown firmness
+ *  value, falls back to defaults — the hook must NEVER crash an edit over config. */
+export declare function readConfig(paths: HunchPaths): HunchConfig;
+/** Write `.hunch/config.json`, merging `patch` over the current on-disk config. */
+export declare function writeConfig(paths: HunchPaths, patch: Partial<HunchConfig>): HunchConfig;

package/dist/core/conformance.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Intent-conformance (the inversion). Today's guards ask "did this diff touch a guarded
+ * file?". This asks the deeper question: "does the code, right now, still SATISFY the
+ * intent a decision recorded?" — by compiling that intent into a DETERMINISTIC check over
+ * the symbol/dependency graph Hunch already builds. "pay must verify the session" becomes
+ * `pay` reaches `verifySession`; if the code drifts so it no longer does, the intent is
+ * violated even though no diff is in scope. No model — pure graph reachability.
+ *
+ * Note: reachability is over the unified dependency graph (call / import / depends-on /
+ * contains edges), so `calls` and `imports` both mean "must reach"; edge-type precision is
+ * a later refinement. The point this proves: code can be checked AGAINST intent.
+ */
+import type { HunchStore } from "../store/hunchStore.js";
+import type { Edge, Symbol as HunchSymbol } from "./types.js";
+export interface ConformanceResult {
+    decision: string;
+    title: string;
+    assert: string;
+    subject: string;
+    object?: string;
+    satisfied: boolean;
+    detail: string;
+}
+export type ConformanceGraph = {
+    symbols: HunchSymbol[];
+    edges: Edge[];
+};
+/** Check every in-force decision's conformance predicates against the CURRENT graph.
+ *  `.satisfied === false` means the code drifted from the recorded intent. Deterministic.
+ *  `publicOnly` selects every input at the JSON read boundary so a private decision,
+ *  symbol, or edge can never influence (or be rendered into) a public CI receipt. */
+export declare function checkConformance(store: HunchStore, opts?: {
+    publicOnly?: boolean;
+    graph?: ConformanceGraph;
+}): ConformanceResult[];

package/dist/core/constraintmatch.d.ts

@@ -0,0 +1,54 @@
+/** Precise, AST-grounded matching for a constraint's content — the primitive behind
+ *  "this change actually BREAKS the rule" (dec_… content-matched constraints).
+ *
+ *  A constraint can forbid, in precision order:
+ *   - deps:     an external import (matched against the PARSED import set, so a comment
+ *               or a string literal that merely names the module can't trip it; a
+ *               submodule import like "lodash/groupBy" is caught by "lodash").
+ *   - symbols:  an identifier added in scoped code (whole-word, comments stripped).
+ *   - patterns: a line regex (lint-grade last resort; comments stripped, strings kept).
+ *
+ *  Deciding a violation by CONTENT is verifiable per commit, so a content-matched
+ *  invariant is immune to file-change "staleness" and keeps its teeth across the file's
+ *  whole life. The same matcher backs the Veto Guard's tripwires (one matcher, audited
+ *  once) — see HunchStore.matchTripwire. */
+export interface Forbids {
+    deps: string[];
+    symbols: string[];
+    patterns: string[];
+}
+export interface ForbidMatch {
+    tier: "dep" | "symbol" | "pattern";
+    evidence: string[];
+}
+/** Walk the precision-first ladder against an analyzed diff/edit: dep (parsed import,
+ *  exact or submodule) > symbol (whole-word identifier in scoped code) > pattern (scoped
+ *  regex). Returns the highest-precision match, or null. */
+export declare function matchForbids(f: Forbids, addedDeps: Set<string>, scopedAdded: string[]): ForbidMatch | null;
+/** A constraint's effective forbids: its structured `forbids` plus a legacy `--match`
+ *  regex folded into the pattern tier (back-compat with v0.35). null when it has none. */
+export declare function effectiveForbids(c: {
+    forbids?: Forbids | null;
+    match?: string | null;
+}): Forbids | null;
+/** The external import module names on a set of raw lines (for the edit-time hook,
+ *  which sees proposed lines, not a parsed diff). Relative imports are ignored. */
+export declare function importedDeps(lines: string[]): Set<string>;
+/** Best-effort: derive a forbidden DEP from a natural-language rule like "never import
+ *  lodash" / "don't use the axios package" — so the seamless capture path (a human
+ *  correction → enforced constraint) mints a PRECISE matcher, not a scope-only rule that
+ *  goes stale. Conservative: only fires on an explicit import/require verb + a
+ *  module-shaped token; returns null otherwise (caller falls back to scope-only). */
+export declare function deriveForbids(rule: string, knownDeps?: readonly string[]): Forbids | null;
+/** The enforceable CODE of an added line: a comment carries no invariant, so the lint-grade
+ *  symbol/pattern tiers must not fire on it (a `// we avoid lodash` note is not a violation).
+ *  Strips a line comment, an inline block comment, and a comment-only / JSDoc line — but NOT
+ *  string literals, since an import specifier (`from "lodash"`) is itself a string.
+ *  Single-pass and line-local, so a multi-line block-comment BODY line (no marker) is NOT
+ *  stripped: that residual false-positive is why the DEP tier — gated on the PARSED import
+ *  set, immune to any comment — is the precise path for "never import X". */
+export declare function matchableCode(line: string): string;
+/** Legacy: compile a constraint's `--match` regex defensively (bad regex → inert). */
+export declare function constraintMatcher(pattern?: string | null): RegExp | null;
+/** True iff any added line's CODE trips a single regex (the v0.35 textual path). */
+export declare function contentViolates(re: RegExp | null, addedLines: string[]): boolean;

package/dist/core/correction.d.ts

@@ -0,0 +1,42 @@
+import type { Constraint } from "./types.js";
+export declare function looksLikeCorrection(prompt: string | undefined | null): boolean;
+/** One-line nudge appended to the UserPromptSubmit hook context when a prompt
+ *  reads like a correction — surfaces the write tool so the rule gets ENFORCED,
+ *  not merely remembered. Client-agnostic (no Claude-only wording). */
+export declare const CORRECTION_NUDGE: string;
+export interface CorrectionInput {
+    /** The invariant in the human's words, e.g. "never call the pay-per-token API here". */
+    rule: string;
+    /** A file the correction was about — scopes the constraint to it (conservative default). */
+    scope_hint_file?: string;
+    severity?: "advisory" | "warning" | "blocking";
+    /** True only when the rule is genuinely repo-wide; required to scope to "**". */
+    applies_to_all?: boolean;
+    type?: "security" | "performance" | "correctness" | "architecture" | "compliance";
+    rationale?: string;
+    /** id of the decision this correction derives from, if any. */
+    source_decision?: string;
+    /** The repo's real dependency names (package.json). When given, a dep matcher is
+     *  auto-derived ONLY for a dep that actually exists — so a non-dependency phrasing
+     *  never silently mints a never-firing rule. */
+    knownDeps?: string[];
+    /** Repo root, used to relativize an ABSOLUTE `scope_hint_file`. Agents naturally
+     *  produce absolute paths (edit-tool payloads and MCP roots are absolute), but every
+     *  consumer matches repo-relative paths — so without this an absolute hint mints a
+     *  scope that can never match. */
+    root?: string;
+    /** True when a capture token was CONSUMED for this write — proof a grilling interview
+     *  preceded it. Determines the TIER, never whether the write lands: an un-vouched
+     *  correction still records immediately and still surfaces at edit time and in CI.
+     *  Only the authority to DENY waits for a countersign. */
+    vouched?: boolean;
+}
+/**
+ * Build the Constraint a correction mints. Pure (caller passes `now`), so the
+ * scope/severity policy is testable in isolation. Key safety rule (research
+ * risk #2 — the scope footgun): a repo-wide ("**") constraint may only be
+ * BLOCKING when the caller explicitly set applies_to_all; otherwise a single
+ * mis-scoped correction would deny every edit under strict firmness, so we
+ * down-rank it to a warning.
+ */
+export declare function buildCorrectionConstraint(input: CorrectionInput, now: string): Constraint;

package/dist/core/correctionStage.d.ts

@@ -0,0 +1,224 @@
+import { type ContractAxisOwnerSource } from "./pipeline.js";
+import { type VerifiedEvidenceMap } from "./evidenceMap.js";
+import { type FileFirstDeclarationDiagnostic, type ProgressiveDeclarationPlan } from "./declarationClusters.js";
+/** The contract-owning layer suggested by issue/reproduction prose. */
+export type CorrectionStage = "schema-emission" | "schema-ingestion" | "presentation" | "constraint-definition" | "runtime-policy";
+export interface CorrectionStageCandidate {
+    owner: string;
+    stage: CorrectionStage;
+    lexical_score: number;
+    symbol_overlap: number;
+    runtime_declaration: boolean;
+    type_scaffolding: boolean;
+    default_locale: boolean;
+}
+export interface AdaptiveCorrectionStageCandidate {
+    owner: string;
+    stage: CorrectionStage;
+    score: number;
+    lexical_score: number;
+    path_overlap: number;
+    symbol_overlap: number;
+    component_support: number;
+    runtime_declaration: boolean;
+    invoked_entrance: boolean;
+    generic_entrance: boolean;
+    type_scaffolding: boolean;
+}
+export interface EvidenceGuidedCorrectionStageCandidate extends AdaptiveCorrectionStageCandidate {
+    baseline_rank: number;
+    optimized_rank: number;
+    evidence: {
+        behavior_sensitive_owner: boolean;
+        behavior_sensitive_file: boolean;
+        target_only_execution: boolean;
+        shared_execution: boolean;
+        strong_differential_file: boolean;
+    };
+}
+export declare const EVIDENCE_GUIDED_SHORTLIST_RULE: "guarded-evidence-bridge-v3";
+export interface CorrectionStageOptimizationReceipt {
+    version: 3;
+    receipt_id: string;
+    rule: typeof EVIDENCE_GUIDED_SHORTLIST_RULE;
+    applied: boolean;
+    reason: "evidence-reordered" | "already-ranked" | "claim-mismatch" | "probe-unverified" | "transfer-rejected-read-only" | "no-actionable-evidence" | "no-sensitive-declaration-resolved";
+    evidence_level: VerifiedEvidenceMap["level"];
+    probe_authenticated: boolean;
+    claim_bound: boolean;
+    requested_limit: number;
+    evidence_slots: number;
+    evidence_strategy: "behavior-sensitive" | "direct-high-contrast-execution" | "guarded-execution-file-peer" | null;
+    selected_execution_ratio: number | null;
+    selected_static_rank: number | null;
+    baseline_candidates: string[];
+    optimized_candidates: string[];
+    promoted_candidates: string[];
+    displaced_candidates: string[];
+    behavior_sensitive_files: string[];
+    strong_differential_files: string[];
+    exact_owner_enabled: false;
+}
+export interface CorrectionStageDiagnostic {
+    stage: CorrectionStage;
+    likely_file: string | null;
+    candidates: Array<CorrectionStageCandidate | AdaptiveCorrectionStageCandidate | EvidenceGuidedCorrectionStageCandidate>;
+    file_first_declaration_clusters: FileFirstDeclarationDiagnostic;
+    progressive_inspection: ProgressiveDeclarationPlan;
+    exact_owner_enabled: false;
+    optimization: CorrectionStageOptimizationReceipt | null;
+    calibration: {
+        holdout_tasks: 11;
+        likely_file_hits: 9;
+        top_five_hits: 8;
+    };
+    cross_repository_transfer: {
+        repositories: readonly ["jquense/yup", "sinclairzx81/typebox"];
+        holdout_tasks: 16;
+        likely_file_hits: 0;
+        top_five_hits: 0;
+        decision: "rejected";
+    };
+    adaptive_transfer: {
+        repositories: readonly ["arktypeio/arktype", "typestack/class-validator"];
+        scorable_tasks: 11;
+        likely_file_hits: 8;
+        top_five_hits: 9;
+        exact_symbol_hits: 7;
+        decision: "promoted-diagnostic";
+    };
+    adaptive_replication: {
+        repositories: readonly ["trpc/trpc", "elysiajs/elysia"];
+        scorable_tasks: 11;
+        likely_file_hits: 4;
+        top_five_hits: 5;
+        exact_symbol_hits: 4;
+        decision: "failed-replication";
+    };
+    optimization_policy: typeof CORRECTION_OPTIMIZATION_POLICY;
+}
+export declare const CORRECTION_STAGE_CANDIDATE_LIMIT = 5;
+export declare const EVIDENCE_GUIDED_SLOT_LIMIT = 3;
+export declare const EVIDENCE_GUIDED_BASELINE_FLOOR = 2;
+export declare const EXECUTION_GUIDED_SLOT_LIMIT = 1;
+export declare const EXECUTION_GUIDED_BASELINE_FLOOR = 4;
+export declare const EXECUTION_DIRECT_RATIO_MIN = 4;
+export declare const EXECUTION_DIRECT_STATIC_RANK_MAX = 20;
+export declare const EXECUTION_FILE_RATIO_MIN = 2;
+export declare const EXECUTION_FILE_STATIC_RANK_MAX = 10;
+export declare const CORRECTION_STAGE_CALIBRATION: {
+    readonly holdout_tasks: 11;
+    readonly likely_file_hits: 9;
+    readonly top_five_hits: 8;
+};
+export declare const CORRECTION_STAGE_TRANSFER: {
+    readonly repositories: readonly ["jquense/yup", "sinclairzx81/typebox"];
+    readonly holdout_tasks: 16;
+    readonly likely_file_hits: 0;
+    readonly top_five_hits: 0;
+    readonly decision: "rejected";
+};
+export declare const ADAPTIVE_CORRECTION_STAGE_TRANSFER: {
+    readonly repositories: readonly ["arktypeio/arktype", "typestack/class-validator"];
+    readonly scorable_tasks: 11;
+    readonly likely_file_hits: 8;
+    readonly top_five_hits: 9;
+    readonly exact_symbol_hits: 7;
+    readonly decision: "promoted-diagnostic";
+};
+export declare const ADAPTIVE_CORRECTION_STAGE_REPLICATION: {
+    readonly repositories: readonly ["trpc/trpc", "elysiajs/elysia"];
+    readonly scorable_tasks: 11;
+    readonly likely_file_hits: 4;
+    readonly top_five_hits: 5;
+    readonly exact_symbol_hits: 4;
+    readonly decision: "failed-replication";
+};
+export declare const CORRECTION_OPTIMIZATION_POLICY: {
+    readonly active: readonly [{
+        readonly mechanism: "repository-adaptive-ranking";
+        readonly verdict: "promote-adaptive-diagnostic";
+    }, {
+        readonly mechanism: "flat-file-anchored-semantic-clusters";
+        readonly verdict: "promote-flat-file-anchored-clusters-v3";
+    }];
+    readonly advisory_only: readonly [{
+        readonly mechanism: "static-stage-shortlist";
+        readonly verdict: "retain-diagnostic-stage-shortlist";
+    }, {
+        readonly mechanism: "progressive-inspection-budget";
+        readonly verdict: "retain-efficiency-advisory-v4";
+    }];
+    readonly disabled: readonly [{
+        readonly mechanism: "fixed-repository-stage-router";
+        readonly verdict: "reject-cross-repository-transfer";
+    }, {
+        readonly mechanism: "score-gap-confidence";
+        readonly verdict: "reject-shortlist-evidence";
+    }, {
+        readonly mechanism: "cross-view-confidence";
+        readonly verdict: "reject-cross-view-evidence";
+    }, {
+        readonly mechanism: "causal-slot-owner";
+        readonly verdict: "reject-causal-slot";
+    }, {
+        readonly mechanism: "causal-intervention-owner";
+        readonly verdict: "reject-causal-intervention-owner";
+    }, {
+        readonly mechanism: "evidence-guided-reordering";
+        readonly verdict: "reject-guarded-evidence-bridge-v3";
+    }, {
+        readonly mechanism: "product-source-filter";
+        readonly verdict: "reject-development-v5-one-loss";
+    }, {
+        readonly mechanism: "one-hop-relationship-expansion";
+        readonly verdict: "reject-development-v5-no-lift";
+    }, {
+        readonly mechanism: "same-file-frontier-replacement";
+        readonly verdict: "reject-development-v5-three-losses";
+    }, {
+        readonly mechanism: "additive-same-file-frontier";
+        readonly verdict: "reject-additive-frontier-v5-no-fresh-rescue";
+    }];
+    readonly exact_owner_policy: "disabled";
+    readonly per_case_confidence: "disabled";
+};
+/** Classify the layer that owns the broken contract, not the public API through
+ * which the symptom happened to surface. This is deterministic and read-only. */
+export declare function inferIssueCorrectionStage(issueValue: unknown): CorrectionStage;
+/** Repository paths that commonly implement each correction stage. Exported so
+ * safe source collection can prioritize the relevant layer in very large repos. */
+export declare function correctionStagePathPattern(stage: CorrectionStage, issueValue: unknown): RegExp;
+/** Return a stage-constrained declaration ranking. Public APIs invoked by the
+ * reproduction are treated as symptom entrances and excluded whenever deeper
+ * candidates exist in the selected stage. */
+export declare function rankIssueCorrectionStageCandidates(issueValue: unknown, sources: ContractAxisOwnerSource[]): CorrectionStageCandidate[];
+/** Reserve a bounded portion of a shortlist for declarations proven to affect
+ * the same authenticated behavior. File peers are included because the held
+ * intervention experiments localized files more reliably than exact owners. */
+export declare function reserveEvidenceGuidedOwners(baselineOwnersValue: string[], rankedOwnersValue: string[], evidenceMap: VerifiedEvidenceMap, requestedLimit?: number): string[];
+export interface GuardedExecutionBridgeSelection {
+    owner: string;
+    path: string;
+    strategy: "direct-high-contrast-execution" | "guarded-execution-file-peer";
+    execution_ratio: number;
+    static_rank: number;
+}
+/** Combine execution contrast with static plausibility. Files already covered
+ * by the baseline are ignored, generic instrumentation files are excluded,
+ * and only the final shortlist slot is eligible. Runtime evidence proposes a
+ * bounded hypothesis; it never becomes an exact-owner claim. */
+export declare function selectGuardedExecutionBridge(baselineOwnersValue: string[], rankedOwnersValue: string[], evidenceMap: VerifiedEvidenceMap, requestedLimit?: number): GuardedExecutionBridgeSelection | null;
+export declare function reserveExecutionGuidedFileOwner(baselineOwnersValue: string[], rankedOwnersValue: string[], evidenceMap: VerifiedEvidenceMap, requestedLimit?: number): string[];
+/** Repository-adaptive replacement for fixed Zod path routing. It discovers
+ * issue vocabulary in this repository's own paths and symbols, adds local
+ * component consensus, and removes an invoked facade only when a deeper
+ * repository-native candidate is available. */
+export declare function rankIssueAdaptiveCorrectionCandidates(issueValue: unknown, sources: ContractAxisOwnerSource[]): AdaptiveCorrectionStageCandidate[];
+export declare function optimizeIssueCorrectionCandidates(issueValue: unknown, sources: ContractAxisOwnerSource[], evidenceValue: unknown, requestedLimit?: number): {
+    candidates: EvidenceGuidedCorrectionStageCandidate[];
+    receipt: CorrectionStageOptimizationReceipt;
+    evidence_map: VerifiedEvidenceMap;
+};
+export declare function diagnoseIssueCorrectionStage(issueValue: unknown, sources: ContractAxisOwnerSource[], requestedLimit?: number, evidenceValue?: unknown): CorrectionStageDiagnostic;
+export declare function formatCorrectionStageDiagnostic(diagnostic: CorrectionStageDiagnostic): string;