@davesheffer/hunch 1.31.0 → 1.32.0

package/dist/core/pipeline.d.ts

@@ -0,0 +1,289 @@
+export type Firmness = "off" | "advisory" | "firm" | "strict";
+export declare const EXECUTION_OBLIGATION_CATEGORIES: readonly ["evidence", "behavior", "types", "serialization", "compatibility", "other"];
+export type ExecutionObligationCategory = (typeof EXECUTION_OBLIGATION_CATEGORIES)[number];
+export type ExecutionObligationPhase = "before-edit" | "session" | "after-edit";
+export type ExecutionObligationOrigin = "memory" | "episode" | "manual";
+export declare const CONTRACT_AXES: readonly ["runtime", "static", "serialization", "compatibility"];
+export type ContractAxis = (typeof CONTRACT_AXES)[number];
+export interface ExecutionExpectation {
+    /** Whether the tool call itself must succeed or fail. */
+    success: boolean;
+    /** Case-insensitive output markers that must all be present/absent. */
+    output_includes?: string[];
+    output_excludes?: string[];
+}
+export interface ExecutableProbe {
+    id: string;
+    origin: ExecutionObligationOrigin;
+    category: ExecutionObligationCategory;
+    claim: string;
+    falsifier: string;
+    /** Exact bounded command shown to the agent; Hunch never executes it itself. */
+    command: string;
+    /** Optional orchestrator materialization; never written or executed by hooks. */
+    artifact?: {
+        path: string;
+        content: string;
+    };
+    /** OR-of-AND tokens used to recognize the observed command safely. */
+    command_alternatives: string[][];
+    expected_before: ExecutionExpectation;
+    expected_after: ExecutionExpectation;
+}
+export interface ContractAxisAudit {
+    /** Axes promised by the supplied after-edit proof plan. */
+    required: ContractAxis[];
+    /** Axes already exercised by the executable contrast. */
+    covered: ContractAxis[];
+    /** Required axes not closed by the contrast itself. */
+    missing: ContractAxis[];
+}
+export interface ContractAxisProbeClosure extends ContractAxisAudit {
+    /** Independently red→green probes selected for uncovered axes. */
+    probes: ExecutableProbe[];
+}
+export interface ContractAxisDisclosure {
+    category: ExecutionObligationCategory;
+    claim: string;
+    falsifier: string;
+}
+export interface ContractAxisRiskHint {
+    probe_id: string;
+    category: ExecutionObligationCategory;
+    owner: string;
+}
+export interface ContractAxisOwnerSource {
+    path: string;
+    content: string;
+}
+export interface ContractAxisOwnerInference {
+    hint: ContractAxisRiskHint;
+    level: "symbol" | "file";
+    anchor: string;
+    score: number;
+    runner_up_score: number | null;
+}
+export interface ContractAxisOwnerRanking {
+    probe_id: string;
+    category: ExecutionObligationCategory;
+    candidates: Array<{
+        owner: string;
+        anchor: string;
+        score: number;
+    }>;
+}
+export interface ImplementationOwnerRanking {
+    candidates: Array<{
+        owner: string;
+        score: number;
+        lexical_score: number;
+        symbol_disclosed: boolean;
+        path_disclosed: boolean;
+    }>;
+}
+export interface ImplementationOwnerInference {
+    owner: string;
+    score: number;
+    runner_up_score: number | null;
+    symbol_disclosed: boolean;
+    path_disclosed: boolean;
+}
+export interface AdaptiveContractAxisProbeClosure extends ContractAxisProbeClosure {
+    /** One staged probe: main contrast first, uncovered consumers only once main is green. */
+    probe: ExecutableProbe | null;
+    /** Design-time consumer contracts, deliberately excluding executable commands. */
+    disclosures: ContractAxisDisclosure[];
+}
+export interface ExecutionProbeBinding {
+    id: string;
+    stage: "baseline" | "validation";
+    claim: string;
+    falsifier: string;
+    command: string;
+}
+/** A bounded, observable proof obligation. `command_alternatives` is OR-of-AND:
+ * one alternative selects a check when every token occurs in its command. The
+ * separate `expected` predicate decides whether the observed result proves it.
+ * Tokens are data, never executable regexes. */
+export interface ExecutionObligation {
+    id: string;
+    origin: ExecutionObligationOrigin;
+    category: ExecutionObligationCategory;
+    phase: ExecutionObligationPhase;
+    description: string;
+    command_alternatives: string[][];
+    expected: ExecutionExpectation;
+    /** Present when this obligation was compiled from one red→green probe. */
+    probe?: ExecutionProbeBinding;
+}
+export interface ExecutionAttempt {
+    command: string;
+    outcome: "success" | "failure" | "unknown";
+    expectation_met: boolean;
+    missing_output?: string[];
+    forbidden_output?: string[];
+}
+export interface TrackedExecutionObligation extends ExecutionObligation {
+    status: "pending" | "satisfied";
+    satisfied_by?: string;
+    satisfied_at_edit?: number;
+    last_attempt?: ExecutionAttempt;
+}
+export interface PipelineState {
+    turn: number;
+    soulInjected: boolean;
+    /** Stop blocks issued THIS turn (reset on every user prompt). */
+    blocks: number;
+    /** Pre-edit evidence denials THIS turn; bounded separately from Stop. */
+    probeBlocks: number;
+    /** Domains activated by edited paths, e.g. { backend: true }. */
+    domains: Record<string, boolean>;
+    editedFiles: string[];
+    /** True until a product edit happens, then true only after a verify command. */
+    verifyAfterEdit: boolean;
+    /** Monotonic product-edit generation; after-edit proofs bind to this value. */
+    editGeneration: number;
+    /** Specific proofs supplied by memory, an episode, or an orchestrator. */
+    obligations: TrackedExecutionObligation[];
+    /** Relevant PostToolUse activity observed while a proof plan is armed. */
+    proofActivity: number;
+    /** Activity index and count for bounded mid-flight reminders. */
+    proofReminderActivity: number;
+    proofReminders: number;
+}
+export declare const emptyState: () => PipelineState;
+/** Validate untrusted MCP/env episode data. Invalid entries are ignored so the
+ * hook's fail-open safety posture remains intact. */
+export declare function normalizeExecutionObligations(value: unknown): ExecutionObligation[];
+/** Validate untrusted probe specs. Probes are declarative data; only the agent
+ * sees the bounded command, and ordinary tool hooks observe its result. */
+export declare function normalizeExecutableProbes(value: unknown): ExecutableProbe[];
+/** Infer which contract consumers an immutable executable contrast actually
+ * exercises. This is deliberately conservative: static coverage requires both
+ * type-shaped source and a typechecking command, while compatibility requires
+ * at least one key=value control that stays identical across red and green. */
+export declare function discoverExecutableProbeContractAxes(value: unknown): ContractAxis[];
+/** Compare a contrast with its broader proof plan. This audit is diagnostic:
+ * category-labelled regression tests are not proof that an axis is closed. */
+export declare function auditExecutableProbeContractAxes(probeValue: unknown, obligationValue: unknown): ContractAxisAudit;
+/** Promote only independently falsifiable red→green probes for uncovered axes.
+ * A passing neighboring test is intentionally ineligible: the V experiment
+ * showed that it can resolve every receipt while leaving the claimed static
+ * contract wrong. */
+export declare function compileContractAxisProbeClosure(contrastValue: unknown, obligationValue: unknown, candidateValue: unknown): ContractAxisProbeClosure;
+/** Collapse a qualified axis closure into one staged red→green probe. The main
+ * contrast runs first on both passes. While it is red, consumer probes are
+ * skipped; once it turns green, only then are the independently qualified
+ * static/serialization/compatibility commands executed. This keeps the biting
+ * closure of W without forcing every baseline into the agent's pre-edit loop. */
+export declare function compileAdaptiveContractAxisProbeClosure(contrastValue: unknown, obligationValue: unknown, candidateValue: unknown): AdaptiveContractAxisProbeClosure;
+/** Compile one author-ranked consumer risk into a bounded design hint. The
+ * selected probe must already belong to the independently qualified closure.
+ * Commands, claims, and falsifiers are deliberately excluded: this hint names
+ * where to leave design room without turning the deferred consumer into work. */
+export declare function compileContractAxisRiskHint(closure: ContractAxisProbeClosure, value: unknown): ContractAxisRiskHint | null;
+/** Infer one bounded risk owner using only qualified probes and pre-edit source
+ * text supplied by the caller. Compatibility is ranked ahead of static and
+ * serialization because it most often crosses a public-surface owner. Within
+ * the chosen probe, public identifiers nominate existing declarations; an
+ * explicit package surface in the probe breaks ties without reading future
+ * changes. */
+export declare function rankContractAxisRiskOwners(closure: ContractAxisProbeClosure, sourceValue: unknown): ContractAxisOwnerRanking | null;
+export declare function inferContractAxisRiskHint(closure: ContractAxisProbeClosure, sourceValue: unknown): ContractAxisOwnerInference | null;
+/** Rank likely implementation declarations from issue/reproduction prose. This
+ * is deliberately separate from contract-axis owner inference: a public API
+ * can own a deferred consumer contract while an internal declaration owns the
+ * smallest patch. The ranker is deterministic BM25 over bounded pre-edit
+ * declaration text, with literal path/symbol disclosure recorded separately. */
+export declare function rankIssueImplementationOwners(issueValue: unknown, sourceValue: unknown, candidateLimit?: number): ImplementationOwnerRanking | null;
+/** Conservative delivery gate for implementation-owner retrieval. Thresholds
+ * are intentionally exposed in the result and require an absolute score plus
+ * a stable lead; benchmark policy may impose stricter external promotion. */
+export declare function inferIssueImplementationOwner(issueValue: unknown, sourceValue: unknown): ImplementationOwnerInference | null;
+/** Compile one probe into two independently observed receipts. The baseline is
+ * eligible only before a product edit; validation is eligible only afterwards. */
+export declare function compileExecutableProbes(value: unknown): ExecutionObligation[];
+/** Add/refresh controller obligations. Replacing an origin lets a newer
+ * hunch_context task discard stale memory obligations without disturbing a
+ * benchmark episode or a manually supplied plan. */
+export declare function armExecutionObligations(state: PipelineState, input: unknown, options?: {
+    replaceOrigin?: ExecutionObligationOrigin;
+}): PipelineState;
+export declare function pendingExecutionObligations(state: PipelineState): TrackedExecutionObligation[];
+export interface BeforeEditProbeVerdict {
+    block: boolean;
+    state: PipelineState;
+    reason?: string;
+}
+/** Before-edit evidence is useful only before implementation. At firm/strict,
+ * deny at most two product edits per prompt until all such receipts exist;
+ * then fail open so a broken probe or discriminator cannot deadlock the agent. */
+export declare function beforeEditProbeVerdict(state: PipelineState): BeforeEditProbeVerdict;
+export declare function executionObligationBrief(state: PipelineState): string;
+/** Harness/orchestrator injection. Malformed input returns no obligations. */
+export declare function environmentExecutionObligations(value?: string | undefined): ExecutionObligation[];
+/** Harness/orchestrator probe injection. Malformed input returns no probes. */
+export declare function environmentExecutableProbes(value?: string | undefined): ExecutableProbe[];
+/** What counts as verification, per domain. Paths activate a domain; verify
+ *  patterns are matched against Bash/PowerShell commands run AFTER an edit. */
+export interface DomainProfile {
+    paths: RegExp;
+    verify: RegExp;
+}
+export declare const DEFAULT_PROFILES: Record<string, DomainProfile>;
+/** Product code = behavior that ships. Docs, hunch's own graph, and .claude
+ *  config are not gated — editing THIS machinery must never trip it. */
+export declare function isProductPath(p: string): boolean;
+export declare function classifyDomains(path: string, profiles?: Record<string, DomainProfile>): string[];
+/** New user prompt: fresh block budget. */
+export declare function onPrompt(state: PipelineState): PipelineState;
+/** Edit/Write/MultiEdit landed on `path`. */
+export declare function onEdit(state: PipelineState, path: string, profiles?: Record<string, DomainProfile>): PipelineState;
+/** A shell command ran. After an edit, it counts as verification when it is
+ *  verify-shaped for an active domain, a generic runner (`node --test`,
+ *  `node -e` assertions), or names an edited file — a bespoke check on the
+ *  thing you changed is verification, and uncredited real checks are how a
+ *  gate gets disabled out of annoyance (first live false-negative: an HTML
+ *  structure assertion via `node -e` was blocked on 2026-07-08). */
+export declare function onCommand(state: PipelineState, command: string, outcome?: {
+    status: "success" | "failure" | "unknown";
+    output: string;
+}, profiles?: Record<string, DomainProfile>): PipelineState;
+/** A verification-class skill ran (/verify, /code-review) — counts as coverage. */
+export declare function onSkill(state: PipelineState, skill: string): PipelineState;
+export type ProofActivity = {
+    kind: "edit";
+} | {
+    kind: "command";
+    command: string;
+} | {
+    kind: "skill";
+};
+export interface ProofCheckpoint {
+    state: PipelineState;
+    reminder?: string;
+    reason?: "evidence-handoff" | "first-edit" | "proof-invalidated" | "falsifier-pivot" | "attempt-mismatch" | "cadence";
+}
+/** Schedule bounded proof reminders while work is still happening. Stop is too
+ * late for clients that terminate at a hard turn budget, so the controller also
+ * injects checkpoints at the evidence→implementation handoff, after the first
+ * product edit, invalidated proof receipts, mismatched proof attempts, and a
+ * small activity cadence. */
+export declare function proofCheckpoint(before: PipelineState, after: PipelineState, activity: ProofActivity): ProofCheckpoint;
+export declare const PIPELINE_LOOP: string;
+export declare const UNVERIFIED_NAG = "Hunch pipeline: earlier product edits are still UNVERIFIED \u2014 run the relevant test/build/typecheck before claiming anything about them.";
+export declare function unverifiedNag(state: PipelineState): string;
+/** Stop-gate verdict. Blocks only at firm/strict, only with unverified product
+ *  edits, and at most twice per turn. */
+export declare function stopVerdict(state: PipelineState, firmness: Firmness): {
+    block: false;
+} | {
+    block: true;
+    reason: string;
+    state: PipelineState;
+};
+export declare function pipelineEnabled(): boolean;
+/** Load session state; on ANY problem return a fresh state (never throw). */
+export declare function loadPipelineState(sessionId: string): PipelineState;
+/** Persist session state (best effort — scratch data, single writer). */
+export declare function savePipelineState(sessionId: string, state: PipelineState): void;

package/dist/core/premises.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Premise decay — the doc≠graph / code≠graph family gains a third spoke:
+ * WORLD≠graph. A decision's staleness signal today is code drift; but decisions
+ * also die when the REASON under them stops being true while the code and docs
+ * stay perfectly in sync ("we had no gateway auth", "no ops team yet"). This
+ * module evaluates the checkable premises a decision records and turns dead
+ * ones into inline escalations.
+ *
+ * Hard rules (red-teamed by design):
+ *   - A dead premise NEVER changes authority. Gates keep gating until a human
+ *     re-attests, supersedes, or retires — a self-relaxing gate is a gate the
+ *     actor it guards against can disarm by changing the world.
+ *   - Cannot-evaluate is NEVER "holds" (the fail-open lesson, dec-recorded in
+ *     v1.10.2): an unevaluable check fails and surfaces, so a typo'd premise
+ *     reaches a human instead of silently vouching.
+ *   - Recorded reasons only: the system cannot notice the premise nobody wrote
+ *     down, so callers must present premises as "conditioned on [these]",
+ *     never "verified valid".
+ *
+ * Pure: the clock and the existence probe are injected, so the CLI, drift, and
+ * the MCP surfaces share one semantics and tests need no filesystem.
+ */
+import type { Decision } from "./types.js";
+import type { Escalation } from "./escalations.js";
+export interface PremiseEnv {
+    /** ISO instant "now" (injected — never read the clock here). */
+    now: string;
+    /** Repo-relative existence probe. */
+    exists(relPath: string): boolean;
+}
+export interface PremiseVerdict {
+    claim: string;
+    holds: boolean;
+    reason: string;
+}
+/** Evaluate every recorded premise of one decision. Empty when none recorded. */
+export declare function evaluatePremises(d: Decision, env: PremiseEnv): PremiseVerdict[];
+/** One inline escalation per LIVE decision with ≥1 dead premise — the question
+ *  a human must answer, framed with its resolution verbs. Rejected alternatives
+ *  are MENTIONED (count only), never re-litigated into agent context: reopening
+ *  a settled rejection is a human call, and consistency alone is a valid reason
+ *  to keep a decision whose original premise died. */
+export declare function premiseEscalations(decisions: readonly Decision[], env: PremiseEnv): Escalation[];

package/dist/core/provenance.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Provenance and credential-free text — a LEAF module (zod only) so that record
+ * schemas registered in the store can import it without pulling in types.ts,
+ * which itself imports the store's kind registry. types.ts re-exports everything
+ * here, so existing imports keep working unchanged.
+ */
+import { z } from "zod";
+/** Where a fact came from and how much to trust it. Confidence tiers (DESIGN §4):
+ *  inferred < extracted < llm_draft < llm_draft+human_confirmed/derived. */
+export declare const ProvenanceSchema: z.ZodObject<{
+    source: z.ZodString;
+    confidence: z.ZodNumber;
+    evidence: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    last_verified: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type Provenance = z.infer<typeof ProvenanceSchema>;
+export declare const SENSITIVE_METADATA_KEY: RegExp;
+/** Reject credential material while allowing ordinary architecture prose such as
+ * "authentication service" or "secrets are managed externally". */
+export declare function isCredentialFreeText(value: string): boolean;
+export declare function isCredentialFreeValue(value: string): boolean;

package/dist/core/publication.d.ts

@@ -0,0 +1,54 @@
+/** Publication safety — what a record would EXPOSE if it lands in the committed store.
+ *
+ *  Context (2026-08-09, 2026-08-11): a capture defaults to the PUBLIC store, and for a
+ *  default `hunch init` user `.hunch/*.json` is git-tracked, so an unflagged
+ *  `hunch_record_*` publishes on the next push. Two leaks reached the public tree that
+ *  way. Nothing inspected what the records SAID.
+ *
+ *  Two tiers, deliberately unequal:
+ *
+ *  - STRUCTURAL hits (machine paths, overlay paths, secret material) are
+ *    domain-independent — a Windows home directory is a leak in any repository, in any
+ *    industry. These are safe to enforce in a package other people install.
+ *  - VOCABULARY hits are corpus-tuned and ship EMPTY. A term list built from one
+ *    project's strategy prose fires on another project's ordinary engineering writing
+ *    ("revenue" is a domain noun in a billing system). A repo opts in through
+ *    `.hunch/publication.json`; the package never presumes.
+ *
+ *  Nothing here throws or blocks. `con_03a0b94b2e` holds the lifecycle hook to
+ *  fail-open, and a privacy heuristic is a smoke detector, not a proof — it earns a
+ *  visible line, not a veto. */
+export type SensitivityKind = "machine-path" | "private-overlay-path" | "secret-material" | "market-vocabulary";
+export interface SensitivityHit {
+    kind: SensitivityKind;
+    /** Which field carried it — "$" for a whole-record structural match. */
+    field: string;
+    /** Short, quotable proof. Truncated: a hit is a pointer, not a payload. */
+    excerpt: string;
+}
+export declare function isStructural(hit: SensitivityHit): boolean;
+export interface ScanOptions {
+    /** Opt-in, repo-local vocabulary. Empty means vocabulary scanning is off. */
+    vocabulary?: readonly RegExp[];
+}
+/** Read a repo's opt-in term list, merged from two layers:
+ *      .hunch/publication.json        committed, shareable patterns
+ *      .hunch/publication.local.json  gitignored, per-machine patterns
+ *
+ *  The local layer exists because the list itself can be sensitive. A rule that
+ *  catches a competitor teardown has to NAME competitors, and committing that
+ *  publishes a watchlist — the exact class of content the scanner is meant to keep
+ *  out of a public repo. Patterns that would embarrass you if read belong in the
+ *  local layer; generic ones can ship.
+ *
+ *  Absent file, malformed JSON, or an invalid pattern all degrade to "no vocabulary".
+ *  A privacy heuristic that crashes a capture is worse than one that stays quiet, and
+ *  the structural tier — the part that works for everyone — never depends on this. */
+export declare function loadVocabulary(hunchDir: string): RegExp[];
+/** Pure. No IO, no throw. Returns every sensitivity signal in one record. */
+export declare function scanRecord(record: unknown, opts?: ScanOptions): SensitivityHit[];
+/** One line naming what was matched and the exact remedy. The predecessor of this
+ *  message was a generic "for sensitive content use private:true" nudge, which was
+ *  present and ignored during both leaks — a warning that does not quote the offending
+ *  text reads as boilerplate. */
+export declare function publicationWarning(hits: readonly SensitivityHit[]): string;

package/dist/core/refrepair.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Deterministic repair for a decision's file references.
+ *
+ * A path may appear both in `related_files` (the scope used by the guards) and in
+ * provenance evidence (the audit trail). Updating only one leaves misleading
+ * memory behind, so this small helper always changes both together and only on an
+ * exact match — never a risky substring rewrite.
+ */
+import type { Decision } from "./types.js";
+export interface DecisionReferenceRepair {
+    decision: Decision;
+    relatedFiles: number;
+    evidence: number;
+}
+export declare function replaceExact(values: string[], from: string, to: string): {
+    values: string[];
+    changed: number;
+};
+/**
+ * Return a corrected copy of a decision, or `null` when the source reference is
+ * not present. The decision's semantic content and verification timestamp are
+ * intentionally preserved: this repairs a locator, it does not re-approve intent.
+ */
+export declare function repairDecisionReference(decision: Decision, from: string, to: string): DecisionReferenceRepair | null;

package/dist/core/refrepair.js

@@ -1,4 +1,4 @@
-function replaceExact(values, from, to) {
+export function replaceExact(values, from, to) {
     let changed = 0;
     const replaced = values.map((value) => {
         if (value !== from)

package/dist/core/relativeImports.d.ts

@@ -0,0 +1,11 @@
+/** Candidate source files for one static relative JS/TS import, in the same
+ * deterministic precedence order used by the indexer. Bare packages, URLs,
+ * absolute paths, and import-map aliases are deliberately unsupported. */
+export declare function relativeImportCandidates(fromFile: string, specifier: string): string[];
+/** Resolve against an exact file set. The first candidate preserves existing
+ * indexer compatibility; callers that need ambiguity metadata can inspect the
+ * returned matches instead of guessing a different target. */
+export declare function resolveRelativeImport(fromFile: string, specifier: string, availableFiles: Iterable<string>): {
+    path: string | null;
+    matches: string[];
+};

package/dist/core/repair.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Self-repair (Phase 5 slice 1): heal memory bindings after a rename/move, with
+ * ZERO guessing. Git's own rename detection (`commitChanges`, -M) is the only
+ * source of old→new pairs, and only EXACT path matches are rewritten — a glob, a
+ * prefix, or anything ambiguous is left alone. Deleted paths stay the drift
+ * detector's job (dead refs); this module never touches them.
+ *
+ * Per §59.5: safe repairs auto-apply in the background and land as a revertable
+ * `repair` move on the memory timeline; anything this planner cannot prove safe
+ * simply isn't in the plan. Pure — no store, no git, no IO — so it is fully
+ * unit-testable; the sync path and `hunch repair` share it.
+ */
+import type { Decision, Constraint } from "./types.js";
+export interface RenamePair {
+    before: string;
+    after: string;
+}
+export interface BindingRewrite {
+    kind: "decisions" | "constraints";
+    id: string;
+    /** which binding field was healed (for the receipt / commit message). */
+    field: "related_files" | "tripwire.scope" | "scope";
+    from: string;
+    to: string;
+}
+export interface RepairPlan {
+    rewrites: BindingRewrite[];
+    /** record ids touched, deduped — the mutation surface. */
+    records: string[];
+}
+/** Extract the rename pairs from a commit's change records (already 1:1 by git -M). */
+export declare function renamesOf(changes: ReadonlyArray<{
+    status: string;
+    before: string | null;
+    after: string | null;
+}>): RenamePair[];
+/** Plan every safe rewrite. Only exact matches against a git-confirmed rename move;
+ *  live records only (a superseded/retired record's history stays as written). */
+export declare function planRepair(renames: readonly RenamePair[], decisions: readonly Decision[], constraints: readonly Constraint[]): RepairPlan;
+/** Apply a plan's rewrites to one decision (pure — returns the healed copy, or the
+ *  original reference when nothing in the plan touches it). */
+export declare function repairDecision(d: Decision, plan: RepairPlan): Decision;
+/** Apply a plan's rewrites to one constraint (pure). */
+export declare function repairConstraint(c: Constraint, plan: RepairPlan): Constraint;

package/dist/core/repairqueue.d.ts

@@ -0,0 +1,40 @@
+import { type CommitRewrite, type DroppedRewrite } from "./commitrepair.js";
+/** Tolerant read: a missing or corrupt queue file is treated as empty — this
+ *  is local scratch state, never a source of truth worth failing loudly over. */
+export declare function readPendingRepairs(root: string): CommitRewrite[];
+export declare function writePendingRepairs(root: string, rewrites: readonly CommitRewrite[]): void;
+/** Tolerant read, same discipline as readPendingRepairs. */
+export declare function readDroppedRepairs(root: string): DroppedRewrite[];
+export declare function writeDroppedRepairs(root: string, dropped: readonly DroppedRewrite[]): void;
+/** The queue as every READ-ONLY consumer should see it: raw entries minus
+ *  anything a human already rejected via `--drop`, regardless of how a
+ *  tombstoned entry ended up back in the raw queue file (e.g. the post-merge
+ *  hook's backgrounded detection racing a `--drop`). A read-time filter, not
+ *  a mutation — the raw queue file is untouched.
+ *
+ *  `repair-provenance`'s own action is the one exception: it needs the RAW
+ *  read (via readPendingRepairs) because it diffs raw-vs-swept to report what
+ *  it cleaned up, and it persists the sweep back to disk. Every other
+ *  reader — `hunch escalations`, SessionStart orientation, the `hunch_now`
+ *  and `hunch_escalations` MCP tools — must call this instead, or a
+ *  tombstoned entry that hasn't yet been swept by a `repair-provenance` run
+ *  re-surfaces as if the human never answered it. */
+export declare function readActivePendingRepairs(root: string): CommitRewrite[];
+/** The `queued` entries whose proposed `to` doesn't resolve to a real commit
+ *  in this repository — the same withheldForUnresolvableTo gate
+ *  `repair-provenance --apply` itself runs before writing, surfaced here so
+ *  a READ-ONLY consumer (hunch escalations, hunch_now/hunch_escalations,
+ *  SessionStart orientation) can tell a permanently-stuck entry apart from
+ *  one `--apply` can still resolve, instead of advertising a
+ *  `--apply --only <id>` that's guaranteed to no-op forever. `null` from
+ *  commitsExist (the check itself failed to run) is treated as fail-open —
+ *  same discipline as the apply path — so nothing is misreported as
+ *  withheld just because the check couldn't run.
+ *
+ *  Returns the OBJECTS, not their ids, and every caller must pass the exact
+ *  same `queued` array into both this function and whatever it hands the
+ *  result to (commitRepairEscalations) — an id-keyed set would collapse a
+ *  corrupted queue's two same-id entries (one resolvable, one not) into one
+ *  unit, exactly the identity confusion withheldForUnresolvableTo's own
+ *  docstring warns about. */
+export declare function withheldRewrites(root: string, queued: readonly CommitRewrite[]): Set<CommitRewrite>;