@davesheffer/hunch 1.31.0 → 1.32.0

package/dist/constitution/staticGraphBaseline.d.ts

@@ -0,0 +1,13 @@
+/** Canonical committed identity for the deterministic static graph.
+ *
+ * Public Hunch pumping creates clone-local commits containing `.hunch/` JSON and
+ * sometimes refreshed grounding docs. Those commits do not change anything the
+ * indexer parses, so binding a shared static receipt to their local SHA makes the
+ * same graph produce different artifact ids in otherwise identical clones. Walk
+ * first-parent until the newest indexed-code or checkout-attribute change instead.
+ * Attributes are a boundary because proof replay validates them before materializing
+ * exact source bytes. A merge is always a boundary: its resolution can change the
+ * effective tree even when a simple diff listing is incomplete. Reverts touch code
+ * and therefore remain distinct. */
+export declare function canonicalStaticGraphBaseline(root: string, ref?: string): string;
+export declare function isAncestorOrSame(root: string, ancestor: string, descendant: string): boolean;

package/dist/constitution/structural.d.ts

@@ -0,0 +1,64 @@
+import type { Decision } from "../core/types.js";
+import type { HunchStore } from "../store/hunchStore.js";
+import { type BootstrapOptions, type BootstrapReport } from "./bootstrap.js";
+import type { PolicyRepository } from "./repository.js";
+import { type PolicyAssertion, type PolicySpec, type StructuralDelta } from "./schema.js";
+export interface StructuralCandidate {
+    id: string;
+    assertion: PolicyAssertion;
+    scope: PolicySpec["scope"];
+    basis: "added-call" | "removed-call" | "added-symbol" | "removed-import" | "added-relative-import" | "removed-relative-import";
+    reason: string;
+}
+export interface StructuralInspection {
+    decision: string;
+    commit: string;
+    kind: "revert" | "bug_fix" | "decision";
+    delta: StructuralDelta;
+    candidates: StructuralCandidate[];
+    unsupported: string[];
+    private: boolean;
+}
+interface Enumerated {
+    candidates: StructuralCandidate[];
+    unsupported: string[];
+}
+export interface ExternalImportBoundaryCandidate {
+    id: string;
+    assertion: PolicyAssertion;
+    scope: PolicySpec["scope"];
+    basis: "correction-forbidden-import";
+    reason: string;
+}
+export type ExternalImportBoundaryInspection = {
+    candidate: ExternalImportBoundaryCandidate;
+    reason: null;
+} | {
+    candidate: null;
+    reason: string;
+    code: "unsupported_dependency" | "unsupported_file" | "missing_anchor" | "baseline_violated";
+};
+/** Bind one exact file/package boundary to the existing static import graph.
+ * The file-level fact is anchored to the first stable symbol because the
+ * indexer attaches every external import in a file to every symbol in it. */
+export declare function inspectExternalImportBoundary(store: HunchStore, file: string, specifier: string, opts?: {
+    publicOnly?: boolean;
+}): ExternalImportBoundaryInspection;
+export declare function structuralKey(policy: Pick<PolicySpec, "assertion" | "scope" | "data_class">): string;
+export declare function directConflict(candidate: PolicySpec, incumbent: PolicySpec): boolean;
+/** Enumerate every supported assertion that the current graph can bind exactly.
+ * Ambiguous or missing bindings are reported; they are never guessed through. */
+export declare function enumerateStructuralCandidates(store: HunchStore, delta: StructuralDelta, opts?: {
+    publicOnly?: boolean;
+    judgment?: Decision;
+    retiredDependenciesOnly?: boolean;
+}): Enumerated;
+export declare function inspectStructuralDecision(store: HunchStore, root: string, decisionId: string, opts?: {
+    publicOnly?: boolean;
+    privateOnly?: boolean;
+}): StructuralInspection;
+/** Phase-2B opt-in bootstrap: only human-confirmed fix/revert or explicit
+ * dependency-retirement decisions, exact
+ * first-parent deltas, and exactly one bindable candidate may compile. */
+export declare function bootstrapStructuralPolicies(store: HunchStore, root: string, repository: PolicyRepository, opts?: BootstrapOptions): BootstrapReport;
+export {};

package/dist/core/agenthook.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Provider hook dialects → Hunch's one internal event shape.
+ *
+ * Hook payloads are an integration boundary: every provider is free to rename
+ * fields or tools. Keep that variability here so the policy engine receives
+ * the same small, fail-open shape regardless of the assistant that emitted it.
+ */
+export declare const HOOK_PROVIDERS: readonly ["claude", "vscode", "windsurf", "antigravity", "cursor"];
+export type HookProvider = (typeof HOOK_PROVIDERS)[number];
+export type HunchHookEvent = "PreToolUse" | "PostToolUse" | "PostToolUseFailure" | "UserPromptSubmit" | "SessionStart" | "SubagentStart" | "PreCompact" | "Stop";
+export interface HunchToolInput {
+    file_path?: string;
+    new_string?: string;
+    content?: string;
+    edits?: Array<{
+        new_string?: string;
+    }>;
+    command?: string;
+    skill?: string;
+}
+/** A provider-neutral observation of the tool result. Output is ephemeral: the
+ * pipeline compares it with bounded expectations but never persists it. */
+export interface HunchToolOutcome {
+    status: "success" | "failure" | "unknown";
+    output: string;
+}
+export interface HunchHookInput {
+    hook_event_name: HunchHookEvent;
+    session_id?: string;
+    /** Native Claude correlation; never synthesize these from prompt text/time. */
+    prompt_id?: string;
+    cwd?: string;
+    agent_id?: string;
+    tool_name?: string;
+    tool_input?: HunchToolInput;
+    tool_outcome?: HunchToolOutcome;
+    prompt?: string;
+    /** SessionStart origin ("startup" | "resume" | "clear" | "compact") — compaction
+     * summarizes away injected grounding, so "compact" resets injection dedup. */
+    source?: string;
+    /** SubagentStart: the delegated agent's type (e.g. "Explore", "Plan"). */
+    agent_type?: string;
+}
+/** Parse a provider name supplied by a hook config. Unknown values intentionally
+ * return null so a bad config cannot make an edit fail. */
+export declare function hookProvider(value: unknown): HookProvider | null;
+/** Normalize a hook stdin payload. Unknown/malformed events return null and the
+ * CLI exits successfully without output — the Never Block on Hook Failure rule. */
+export declare function normalizeHookEvent(raw: unknown, provider: HookProvider): HunchHookInput | null;
+/** Provider-aware hook output. Context output is intentionally omitted for
+ * Windsurf because its documented hook protocol has no agent-context channel;
+ * its always-on project rule + MCP server remain the grounding delivery path. */
+export declare function contextHookOutput(provider: HookProvider, event: HunchHookEvent, text: string): object | null;
+/** Strict-deny response in each native dialect. Windsurf uses documented exit
+ * code 2; the caller writes this error to stderr and preserves exit success for
+ * every accidental/malformed invocation. */
+export declare function denyHookOutput(provider: HookProvider, reason: string): {
+    output: object | null;
+    exitCode?: number;
+    stderr?: string;
+};
+/** Stop-gate output in each native dialect. */
+export declare function stopHookOutput(provider: HookProvider, reason: string): object;

package/dist/core/agenthook.js

@@ -194,6 +194,7 @@ export function normalizeHookEvent(raw, provider) {
     return {
         hook_event_name: event,
         session_id: stringAt(input, "session_id", "sessionId", "conversation_id", "conversationId"),
+        ...(provider === "claude" ? Object.fromEntries(["prompt_id", "cwd", "agent_id"].filter(key => input[key] !== undefined).map(key => [key, typeof input[key] === "string" ? input[key] : ""])) : {}),
         tool_name: hunchToolName(stringAt(input, "tool_name", "toolName"), toolInput ?? {}),
         tool_input: toolInput,
         ...(toolOutcome ? { tool_outcome: toolOutcome } : {}),

package/dist/core/automaticReviewMemory.d.ts

@@ -0,0 +1,60 @@
+import type { Constraint } from "./types.js";
+export interface AutomaticReviewEntry {
+    candidate_id: string;
+    evidence_hash: string;
+    file: string;
+    status: "ready" | "saved" | "skipped" | "review" | "deferred";
+    reason: string;
+    code_hash?: string;
+    rule_id?: string;
+    cached?: boolean;
+    retryable?: boolean;
+}
+/** Bounded sequential analysis with a separate skeptical pass. The caller owns I/O and persistence. */
+export declare function automateReviewMemory(options: {
+    packet: unknown;
+    existing: Constraint[];
+    readCurrent: (file: string) => string;
+    generate: (prompt: string) => Promise<string>;
+    provider: string;
+    limit: number;
+    now: string;
+    progress?: (candidate: string, position: number) => void;
+    previous?: AutomaticReviewEntry[];
+    providersUsed?: () => string[];
+}): Promise<{
+    schema: "hunch.automatic-review-memory/1";
+    repository: string;
+    provider: string;
+    providers_used: string[];
+    authority: "advisory";
+    applied: boolean;
+    analyzed: number;
+    entries: AutomaticReviewEntry[];
+    rules: {
+        id: string;
+        type: "security" | "performance" | "correctness" | "architecture" | "compliance";
+        statement: string;
+        scope: string[];
+        severity: "advisory" | "warning" | "blocking";
+        enforcement: "ci" | "advisory_v1" | "manual";
+        match: string | null;
+        forbids: {
+            deps: string[];
+            symbols: string[];
+            patterns: string[];
+        } | null;
+        rationale: string;
+        source_decision: string | null;
+        violations: string[];
+        status: "active" | "retired";
+        valid_to: string | null;
+        provenance: {
+            source: string;
+            confidence: number;
+            evidence: string[];
+            last_verified?: string | undefined;
+        };
+        valid_from?: string | undefined;
+    }[];
+}>;

package/dist/core/autoreview.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Auto-review planner — the pure decision core behind `hunch auto-review`.
+ *
+ * It takes the draft set + a per-draft harness RelevanceVerdict (the "delegate to
+ * the harness" judgment) and folds in the two DETERMINISTIC signals the store
+ * already produces — near-duplicate detection (dupdetect) and grounding/Critic
+ * verification (reviewqueue) — into four disjoint buckets:
+ *
+ *   accept          — confirm to human_confirmed. GATED: only Critic-verified,
+ *                     well-grounded drafts the harness judged relevant + non-dup.
+ *                     This is the dec_a466655539 line — a machine never confirms an
+ *                     UN-audited draft; the harness verdict can only ADD a veto, not
+ *                     substitute for the Critic's grounding.
+ *   rejectDuplicate — reject: a near-duplicate of an accepted record (deterministic
+ *                     dupdetect, OR the harness named an existing decision it restates).
+ *   rejectIrrelevant— reject: the harness judged it not worth keeping, confidently.
+ *   keep            — everything else stays for a human (the safe default).
+ *
+ * No I/O, no LLM calls here — verdicts are passed in — so it's fully unit-testable
+ * and deterministic given its inputs.
+ */
+import type { Decision } from "./types.js";
+import type { RelevanceVerdict } from "../synthesis/provider.js";
+export type AutoReviewAction = "accept" | "rejectDuplicate" | "rejectIrrelevant" | "keep";
+export interface AutoReviewEntry {
+    d: Decision;
+    action: AutoReviewAction;
+    /** human-readable justification for the action (shown in the plan). */
+    reason: string;
+    /** the harness verdict for this draft, when one was obtained. */
+    verdict?: RelevanceVerdict;
+    /** grounded-ness parsed from synth telemetry, when present. */
+    grounded?: number;
+}
+export interface AutoReviewPlan {
+    accept: AutoReviewEntry[];
+    rejectDuplicate: AutoReviewEntry[];
+    rejectIrrelevant: AutoReviewEntry[];
+    keep: AutoReviewEntry[];
+}
+export interface AutoReviewConfig {
+    /** grounded-ness threshold for the accept gate. */
+    minGrounded?: number;
+    /** minimum harness confidence to act on an "irrelevant" verdict (lifecycle rejection).
+     *  Below this the draft is kept for a human — we never reject on a shaky judgment. */
+    minRejectConfidence?: number;
+}
+/** Build the plan. `verdicts` maps draft id → harness verdict (absent → the draft
+ *  was not judged, e.g. no CLI available; the pure plan can still flag a
+ *  deterministic duplicate or keep it). The CLI refuses `--apply` on an incomplete
+ *  requested harness batch; explicit `--no-llm` triage intentionally has no batch. */
+export declare function planAutoReview(drafts: Decision[], allDecisions: Decision[], verdicts: Map<string, RelevanceVerdict>, cfg?: AutoReviewConfig): AutoReviewPlan;
+/** Total drafts the plan would mutate (accept + both rejection buckets). */
+export declare function planMutations(plan: AutoReviewPlan): number;
+/** A caller's EXPLICIT accept/delete choice (from the Review Console's per-card
+ *  override), resolved against the live draft set. Ids that aren't a current draft
+ *  — already accepted/superseded, or plain unknown — land in `unknown` so an
+ *  apply-by-id can never mutate a non-draft record by a stale id (the console holds
+ *  a snapshot; the store may have moved). An id claimed by BOTH lists resolves to
+ *  accept (the safer, non-destructive verb) and is reported as unknown for delete. */
+export interface ResolvedSelection {
+    accept: Decision[];
+    delete: Decision[];
+    unknown: string[];
+}
+export declare function resolveSelection(drafts: Decision[], acceptIds: string[], deleteIds: string[]): ResolvedSelection;

package/dist/core/canonicalOrder.d.ts

@@ -0,0 +1,3 @@
+/** Locale-free UTF-16 code-unit ordering for content-addressed artifacts.
+ * Never use localeCompare where ordering contributes to a hash or selection. */
+export declare function compareCodeUnits(left: string, right: string): number;

package/dist/core/capturetoken.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Capture-session tokens (decision-grounding, DESIGN §5 Stage 1 / §9.3).
+ *
+ * hunch_capture_decision issues a short-lived token; the commit path consumes it, so a
+ * decision written through the capture front door is provably the tail of an interview
+ * — the identity-principle guard against a silent, un-interviewed write. In-memory (the
+ * MCP server is long-lived); tokens are one-time-use and expire so an abandoned
+ * interview can't leak. Absence of a token never BLOCKS a write yet (staged
+ * deprecation §9.3) — the caller decides how to treat an un-gated write.
+ */
+declare const CAPTURE_TOKEN_TTL_MS: number;
+/** Issue a token stamped `now` (epoch ms). Prunes expired tokens first so the map can't
+ *  grow unbounded across a long server life. `mint` supplies the random id (injectable
+ *  for tests); the call site passes crypto.randomUUID. */
+export declare function issueCaptureToken(mint: () => string, now: number): string;
+/** Consume a token iff it is a live, unexpired capture session. One-time use: a second
+ *  consume of the same token returns false. */
+export declare function consumeCaptureToken(token: string | undefined, now: number): boolean;
+export { CAPTURE_TOKEN_TTL_MS };

package/dist/core/changeIdentity.d.ts

@@ -0,0 +1,22 @@
+export declare const CHANGE_IDENTITY_SCHEMA_VERSION: "hunch.change-identity/1";
+export declare const CHANGE_IDENTITY_ALGORITHM: "git-raw-tree-delta-sha256/1";
+export interface ChangeIdentity {
+    schema: typeof CHANGE_IDENTITY_SCHEMA_VERSION;
+    algorithm: typeof CHANGE_IDENTITY_ALGORITHM;
+    change_id: string;
+    base_revision: string;
+    head_revision: string;
+    base_tree: string;
+    head_tree: string;
+    delta_hash: string;
+    /** Git's looser interoperability identifier; never the Hunch authority. */
+    patch_id: string | null;
+    file_count: number;
+    paths_hash: string;
+    content_hash: string;
+}
+/** Derive one deterministic receipt from two commit-ish references. */
+export declare function deriveChangeIdentity(root: string, baseRef: string, headRef?: string): ChangeIdentity;
+/** Validate an identity without trusting any caller-supplied seal. */
+export declare function assertChangeIdentity(value: unknown): asserts value is ChangeIdentity;
+export declare function changesAreEquivalent(left: unknown, right: unknown): boolean;

package/dist/core/changeProof.d.ts

@@ -0,0 +1,14 @@
+import type { HunchStore } from "../store/hunchStore.js";
+import { type ChangeProof } from "./changeProofContract.js";
+export interface DeriveChangeProofOptions {
+    /** Exclude a configured private overlay from the artifact. Required before publication. */
+    publicOnly?: boolean;
+}
+/**
+ * Produce Hunch's standalone semantic proof for one exact committed tree transition.
+ *
+ * The proof is read-only and timestamp-free. It binds source bytes, parsed graph,
+ * current memory records and every explicit gap; it never grants execution, CI,
+ * deployment, merge, ranking, promotion or policy authority.
+ */
+export declare function deriveChangeProof(root: string, store: HunchStore, baseRef: string, resultRef?: string, options?: DeriveChangeProofOptions): ChangeProof;

package/dist/core/checkreport.d.ts

@@ -0,0 +1,140 @@
+/** Rendering for `hunch check` — pure, so the terminal output and the CI/PR
+ *  comment share one source of truth and stay unit-testable. The CLI builds a
+ *  CheckReport from the store (direct/near/regression + the hardened strict gate),
+ *  then renders it as text (terminal, unchanged) or markdown (a PR comment posted
+ *  by the GitHub Action). The exit-code decision lives with the caller. */
+/** The causal chain behind an invariant — the WHY a diff-only reviewer can't see:
+ *  the decision that motivated the guard, and the bug whose root cause spawned it.
+ *  Resolved deterministically from the graph (constraint→source_decision→bug). */
+export interface CausalWhy {
+    constraint_id: string;
+    decision?: {
+        id: string;
+        title: string;
+        decision: string;
+    };
+    bug?: {
+        id: string;
+        title: string;
+        root_cause: string;
+    };
+}
+export interface CheckDirect {
+    id: string;
+    severity: string;
+    statement: string;
+    rationale: string;
+    files: string[];
+    /** Would this invariant FAIL the commit under --strict (direct + high-confidence + non-stale)? */
+    strictBlocks: boolean;
+    /** If a blocking invariant is downgraded to advisory under strict, why. */
+    downgrade?: "stale" | "low-confidence";
+    /** The causal citation (the "why this guard exists") — present when the graph links it. */
+    why?: CausalWhy;
+}
+export interface CheckNear {
+    id: string;
+    severity: string;
+    statement: string;
+    via: string[];
+}
+export interface CheckRegression {
+    kind: string;
+    name: string;
+    decision: string;
+    title: string;
+    reason: string;
+    blocking: boolean;
+}
+/** A diff re-introducing an approach an in-force decision deliberately REJECTED. */
+export interface CheckVeto {
+    decision: string;
+    title: string;
+    alternative: string;
+    chosen: string;
+    tier: string;
+    evidence: string[];
+    blocking: boolean;
+}
+/** A diff that ADDS a symbol already defined elsewhere in the graph — likely a
+ *  re-implementation the local-context-window agent couldn't see. Advisory only. */
+export interface CheckRedundant {
+    name: string;
+    kind: string;
+    existingFile: string;
+}
+export interface CheckReport {
+    fileCount: number;
+    strict: boolean;
+    direct: CheckDirect[];
+    near: CheckNear[];
+    regressions: CheckRegression[];
+    vetoes: CheckVeto[];
+    /** Advisory: symbols this diff adds that already exist elsewhere (possible sprawl). Never blocks. */
+    redundant: CheckRedundant[];
+    /** Count of direct invariants that pass the hardened strict gate. */
+    strictBlockers: number;
+    /** Count of blocking-linked regressions. */
+    regBlocking: number;
+    /** Count of vetoes that pass the veto gate (human-confirmed, in-force, non-stale). */
+    vetoBlocking: number;
+}
+export declare function reportIsClean(r: CheckReport): boolean;
+/** PR impact (read-only, advisory): the dependency + memory surface of a change.
+ *  Composes the SAME primitives as CheckReport so impact and gating never disagree. */
+export interface ImpactReport {
+    files: string[];
+    /** Files whose code (in)directly depends on the changed files — nearest depth wins. */
+    blast: Array<{
+        file: string;
+        via: string;
+        depth: number;
+    }>;
+    report: CheckReport;
+    /** In-force decisions concerning the touched files. */
+    decisions: Array<{
+        id: string;
+        title: string;
+        status: string;
+    }>;
+}
+/** Terminal/markdown-lite rendering of an ImpactReport (hunch impact / hunch_pr_impact). */
+export declare function renderImpact(im: ImpactReport, scope: string): string;
+/** True when --strict should FAIL the commit/PR. */
+export declare function reportFailsStrict(r: CheckReport): boolean;
+/** The deterministic VERDICT for a merge: block (a hard gate fired), warn (touches
+ *  memory but nothing hard-blocks), or pass (touches no recorded memory at all). */
+export declare function verdict(r: CheckReport): "block" | "warn" | "pass";
+export declare function renderText(r: CheckReport): string;
+export declare function renderMarkdown(r: CheckReport): string;
+/** Conformance/policy/scan findings arrive from the CLI already flattened, so this
+ *  renderer stays pure and every output channel shares one gate semantics. */
+export interface SarifExtras {
+    conformance?: Array<{
+        decision: string;
+        title: string;
+        detail: string;
+        why?: string;
+        bug?: string;
+    }>;
+    policies?: Array<{
+        id: string;
+        result: string;
+        explanation: string;
+        blocks: boolean;
+        receipt: string;
+        gateError?: string;
+    }>;
+    scanIssues?: Array<{
+        path: string;
+        detail: string;
+        code: string;
+    }>;
+}
+/** Render the full check verdict as a SARIF 2.1.0 document. Level mapping is
+ *  severity-truth, independent of the exit code: `error` = would fail --strict
+ *  (strict-blocking invariants, blocking-linked regressions/vetoes, conformance
+ *  violations, authorized policy blocks, incomplete scans), `warning` = blocking
+ *  records the strict gate downgraded plus warning-severity hits, `note` = advisory
+ *  (near, redundant, non-blocking receipts). */
+export declare function renderSarif(r: CheckReport, version: string, extras?: SarifExtras): string;

package/dist/core/commitrepair.d.ts

@@ -0,0 +1,171 @@
+import type { Decision } from "./types.js";
+import type { CommitCandidate, CommitRepairStatus } from "../extractors/git.js";
+export interface CommitRewrite {
+    id: string;
+    from: string;
+    to: string;
+}
+/** Bind review to the ordered queue and which targets are currently resolvable.
+ * Queue order matters: duplicate decision ids use first-match selection. */
+export declare function commitRepairReviewHash(queued: readonly CommitRewrite[], withheld?: ReadonlySet<CommitRewrite>): string;
+/** A tombstone: the exact {id, from, to} rewrite a human explicitly rejected
+ *  via `--drop`. Keyed on the full triple, not just {id, from} — the human's
+ *  "no" answers the specific question the commit-repair-pending escalation
+ *  asked ("apply THIS proposed replacement, from -> to?"), not a blanket
+ *  refusal of every future replacement for this decision's still-orphaned
+ *  commit. A later merge proposing a genuinely different `to` for the same
+ *  {id, from} is a NEW proposal — not a repeat of the one that was rejected —
+ *  and surfaces normally. */
+export interface DroppedRewrite {
+    id: string;
+    from: string;
+    to: string;
+}
+export interface CommitRepairPlan {
+    rewrites: CommitRewrite[];
+    records: string[];
+}
+/** 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 declare function orphanedCommitDecisions(decisions: readonly Decision[], status: (sha: string) => CommitRepairStatus): Decision[];
+/** 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 declare function planCommitRepair(orphaned: readonly Decision[], candidates: readonly CommitCandidate[]): CommitRepairPlan;
+/** 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 declare function liveRewrites(queued: readonly CommitRewrite[], decisions: readonly Decision[]): CommitRewrite[];
+/** 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 declare function deadRewrites(queued: readonly CommitRewrite[], decisions: readonly Decision[]): CommitRewrite[];
+/** 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 declare function resolvedRewriteIds(toApply: readonly CommitRewrite[], decisions: readonly Decision[]): Set<string>;
+/** 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 declare function withoutDropped(rewrites: readonly CommitRewrite[], dropped: readonly DroppedRewrite[]): CommitRewrite[];
+/** Append newly-dropped {id, from, to} triples to the tombstone list,
+ *  deduped — same append-only, dedupe-by-key shape as mergeRewrites. */
+export declare function addDropped(newly: readonly DroppedRewrite[], existing: readonly DroppedRewrite[]): DroppedRewrite[];
+/** 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 declare function mergeRewrites(fresh: readonly CommitRewrite[], queued: readonly CommitRewrite[]): CommitRewrite[];
+/** 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 declare function withheldForUnresolvableTo(toApply: readonly CommitRewrite[], existing: Set<string> | null): {
+    applicable: CommitRewrite[];
+    withheld: CommitRewrite[];
+};
+/** 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 declare function firstFor(entries: readonly CommitRewrite[], id: string): CommitRewrite | undefined;
+/** 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 declare function pickRewrite(plan: CommitRepairPlan, id: string): CommitRewrite | undefined;
+/** 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 declare function repairDecisionCommit(d: Decision, plan: CommitRepairPlan): Decision;