@davesheffer/hunch 1.46.0 → 1.47.0

package/dist/cli/invocation.d.ts

@@ -11,6 +11,7 @@ export interface ResolvedInvocation {
      * or npx cache), never from a source checkout. */
     installed: boolean;
 }
+/** Faint (dim) ANSI styling. */
 export declare function dim(s: string): string;
 /** Portable invocation written into committed MCP/provider configuration.
  * Keep it independently testable so the distribution pin cannot silently
@@ -20,20 +21,14 @@ export declare function publishedMcpInvocation(): Invocation;
  *  PowerShell can execute the first token; paths and other unsafe tokens use
  *  JSON string quoting, which is accepted by PowerShell, cmd, and POSIX sh. */
 export declare function shellInvocation(inv: Invocation): string;
-/** The doctor command's synthesis-status line(s) for a resolved provider.
- *  Exported for testing — the previous version (a bare provider-name switch,
- *  before the resolveSynthesisProvider preference system existed) had zero
- *  test coverage, which is how issue #8 (openai-compat misreported as "no
- *  assistant CLI found") shipped unnoticed through three review passes. That
- *  bug resurfaces here for the same reason: resolution.statuses carries a
- *  `subscription` field for the CLI providers but openai-compat's is null (it
- *  isn't a subscription), so it must be special-cased explicitly rather than
- *  falling through to the "no assistant CLI" branch. */
+/** Render doctor's synthesis status lines. Exported for testing: an earlier,
+ *  untested version reported openai-compat as "no assistant CLI found". Statuses
+ *  carry a `subscription` for CLI providers but openai-compat's is null, so it is
+ *  special-cased explicitly. */
 export declare function synthesisStatusLines(resolution: ProviderResolution, env: NodeJS.ProcessEnv): string[];
-/** Gate + fetch the Ollama context-window advisory (issue #11): only relevant
- *  for the openai-compat provider, so every other provider is a no-op. Kept
- *  separate from synthesisStatusLines (sync, already fully covered) because
- *  this one makes a best-effort network call. */
+/** Gate + fetch the Ollama context-window advisory. Only openai-compat is
+ *  relevant; kept apart from the sync status lines because it makes a
+ *  best-effort network call. */
 export declare function maybeWarnOllamaContext(providerName: string, env: NodeJS.ProcessEnv): Promise<string | null>;
 /** Classify the entry path without faking import.meta.url in tests. */
 export declare function classifyEntry(entry: string): {

package/dist/cli/invocation.js

@@ -1,12 +1,15 @@
-/** Side-effect-free shared CLI logic — safe for any module (including tests)
- *  to import, unlike src/cli/index.ts, which runs the whole program at
- *  import time. Holds: how to re-invoke this CLI from a git hook / .mcp.json
- *  (working both when running the built dist and in dev via tsx), plus small
- *  formatting helpers (dim(), doctor's synthesisStatusLines()) that need the
- *  same import-safety to be unit-testable. */
+/**
+ * Shared CLI logic that is free of import-time side effects, so any module
+ * (tests included) can import it safely, unlike src/cli/index.ts which runs the
+ * program as soon as it loads. It holds how to re-invoke this CLI from a git hook
+ * or `.mcp.json` (from a built dist and in dev via tsx), plus small formatting
+ * helpers (`dim()`, doctor's `synthesisStatusLines()`) that need the same import
+ * safety to be unit-testable.
+ */
 import { fileURLToPath } from "node:url";
 import { probeOllamaNumCtx } from "../synthesis/provider.js";
 import { HUNCH_NPX_PACKAGE_SPEC } from "../core/version.js";
+/** Faint (dim) ANSI styling. */
 export function dim(s) {
     return `\x1b[2m${s}\x1b[0m`;
 }
@@ -23,15 +26,10 @@ export function shellInvocation(inv) {
     const token = (part) => /^[A-Za-z0-9_@:=+.,/-]+$/.test(part) ? part : JSON.stringify(part);
     return [inv.command, ...inv.args].map(token).join(" ");
 }
-/** The doctor command's synthesis-status line(s) for a resolved provider.
- *  Exported for testing — the previous version (a bare provider-name switch,
- *  before the resolveSynthesisProvider preference system existed) had zero
- *  test coverage, which is how issue #8 (openai-compat misreported as "no
- *  assistant CLI found") shipped unnoticed through three review passes. That
- *  bug resurfaces here for the same reason: resolution.statuses carries a
- *  `subscription` field for the CLI providers but openai-compat's is null (it
- *  isn't a subscription), so it must be special-cased explicitly rather than
- *  falling through to the "no assistant CLI" branch. */
+/** Render doctor's synthesis status lines. Exported for testing: an earlier,
+ *  untested version reported openai-compat as "no assistant CLI found". Statuses
+ *  carry a `subscription` for CLI providers but openai-compat's is null, so it is
+ *  special-cased explicitly. */
 export function synthesisStatusLines(resolution, env) {
     const provider = resolution.provider;
     if (resolution.source === "unavailable-initiator") {
@@ -43,39 +41,38 @@ export function synthesisStatusLines(resolution, env) {
     if (resolution.source === "initiator") {
         return [`            ↳ agent calls remain with ${resolution.initiator}, using that CLI's configured authentication.`];
     }
-    const selected = resolution.statuses.find((s) => s.name === provider.name);
-    if (selected?.subscription) {
-        return [`            ↳ LLM synthesis uses your ${selected.subscription}; provider API credentials are not used.`];
+    const status = resolution.statuses.find((s) => s.name === provider.name);
+    if (status?.subscription) {
+        return [`            ↳ LLM synthesis uses your ${status.subscription}; provider API credentials are not used.`];
     }
     if (provider.name === "openai-compat") {
-        const base = env.HUNCH_SYNTH_BASE_URL ?? "(unset)";
-        const model = env.HUNCH_SYNTH_MODEL ?? "(unset)";
+        const base = env.HUNCH_SYNTH_BASE_URL || "(unset)";
+        const model = env.HUNCH_SYNTH_MODEL || "(unset)";
         const keyNote = env.HUNCH_SYNTH_API_KEY ? " (HUNCH_SYNTH_API_KEY set)" : " (no API key)";
         return [`            ↳ LLM synthesis via local/self-hosted endpoint ${base} (model: ${model})${keyNote}`];
     }
     if (resolution.source === "ambiguous") {
-        const names = resolution.statuses.filter((s) => s.name !== "deterministic" && s.available).map((s) => s.name);
+        const names = resolution.statuses.filter((s) => s.available && s.name !== "deterministic").map((s) => s.name);
         return [
             dim(`            ↳ ${names.join(", ")} are available; Hunch will not guess which provider to use.`),
-            dim(`              choose one locally: ${names.map((name) => `hunch provider ${name}`).join("  or  ")}`),
+            dim(`              choose one locally: ${names.map((n) => `hunch provider ${n}`).join("  or  ")}`),
         ];
     }
     if (resolution.source === "unavailable-preference") {
         return [dim(`            ↳ ${resolution.preference} was selected but is unavailable; using the offline heuristic.`)];
     }
     return [
-        dim(`            ↳ no assistant CLI found — synthesis uses the offline heuristic (advisory, low-confidence).`),
-        dim(`              install or log into Claude Code, Codex, or Cursor; then select one with \`hunch provider <name>\`.`),
+        dim("            ↳ no assistant CLI found — synthesis uses the offline heuristic (advisory, low-confidence)."),
+        dim("              install or log into Claude Code, Codex, or Cursor; then select one with `hunch provider <name>`."),
     ];
 }
-/** Gate + fetch the Ollama context-window advisory (issue #11): only relevant
- *  for the openai-compat provider, so every other provider is a no-op. Kept
- *  separate from synthesisStatusLines (sync, already fully covered) because
- *  this one makes a best-effort network call. */
+/** Gate + fetch the Ollama context-window advisory. Only openai-compat is
+ *  relevant; kept apart from the sync status lines because it makes a
+ *  best-effort network call. */
 export async function maybeWarnOllamaContext(providerName, env) {
     if (providerName !== "openai-compat")
         return null;
-    return probeOllamaNumCtx(env.HUNCH_SYNTH_BASE_URL ?? "", env.HUNCH_SYNTH_MODEL ?? "");
+    return probeOllamaNumCtx(env.HUNCH_SYNTH_BASE_URL || "", env.HUNCH_SYNTH_MODEL || "");
 }
 /** Classify the entry path without faking import.meta.url in tests. */
 export function classifyEntry(entry) {

package/dist/constitution/delta.js

@@ -27,10 +27,10 @@ function view(file, source) {
 }
 function viewOfParsed(parsed) {
     const symbols = new Map(parsed.symbols.map((s) => [symbolKey(s), s]));
-    const byIndex = new Map(parsed.symbols.map((s, i) => [i, s]));
+    const symbolAt = new Map(parsed.symbols.map((s, i) => [i, s]));
     const calls = new Map();
     for (const [index, callees] of attributeCalls(parsed)) {
-        const caller = byIndex.get(index);
+        const caller = symbolAt.get(index);
         if (!caller)
             continue;
         for (const [callee, member] of callees) {

package/dist/constitution/sourceMutation.js

@@ -93,21 +93,23 @@ function parsedSymbolFor(graphSymbol, parsed) {
     const base = symbolId(graphSymbol.file, graphSymbol.name, graphSymbol.kind);
     return matches.find((_symbol, index) => (index === 0 ? base : `${base}_${index}`) === graphSymbol.id) ?? null;
 }
-/** `start`/`end` are JS string (UTF-16 code unit) indices. Despite their
- *  names, parse.ts's startByte/endByte/atByte carry the same units — native
- *  tree-sitter indexes the JS string it was handed, not its UTF-8 encoding —
- *  so every scan and splice against them must be string-based, never Buffer-
- *  based. */
-function spliceChars(source, replacements) {
+/** Apply `{ start, end, text }` replacements to `source`. Offsets are JavaScript
+ *  string (UTF-16 code unit) indices: the parser's `startByte`/`endByte`/`atByte`
+ *  fields, despite their names, carry the same units (tree-sitter indexes the JS
+ *  string it was given, not its UTF-8 bytes), so every scan and splice against
+ *  them must be string-based, never Buffer/byte-based. */
+function applyReplacements(source, replacements) {
     let result = source;
     for (const replacement of [...replacements].sort((a, b) => b.start - a.start)) {
         result = result.slice(0, replacement.start) + replacement.text + result.slice(replacement.end);
     }
     return result;
 }
-/** Where a new top-level statement (an import) can be inserted without splitting a shebang line. */
-function insertionPoint(source) {
-    return source.startsWith("#!") ? Math.max(0, source.indexOf("\n") + 1) : 0;
+/** Offset where a new top-level import may go: 0, or just past a leading shebang line. */
+function importInsertionOffset(source) {
+    if (!source.startsWith("#!"))
+        return 0;
+    return Math.max(0, source.indexOf("\n") + 1);
 }
 function mutateSource(policy, base, sourceFile, source) {
     const assertion = policy.assertion;
@@ -150,10 +152,14 @@ function mutateSource(policy, base, sourceFile, source) {
         const specifier = relativeSpecifier(sourceFile, targetFile);
         if (parsed.imports.some((candidate) => candidate === specifier))
             return { error: "mutation-component-import-already-present" };
-        const insertion = insertionPoint(source);
+        const insertion = importInsertionOffset(source);
         return {
             file: sourceFile,
-            source: spliceChars(source, [{ start: insertion, end: insertion, text: `import ${JSON.stringify(specifier)}; // hunch deterministic component mutation\n` }]),
+            source: applyReplacements(source, [{
+                    start: insertion,
+                    end: insertion,
+                    text: `import ${JSON.stringify(specifier)}; // hunch deterministic component mutation\n`,
+                }]),
         };
     }
     const subject = symbolForSelector(base, assertion.subject);
@@ -166,7 +172,7 @@ function mutateSource(policy, base, sourceFile, source) {
     if (!definition)
         return { error: "mutation-subject-definition-unresolved" };
     if (assertion.kind === "exists") {
-        return { file: subject.file, source: spliceChars(source, [{ start: definition.startByte, end: definition.endByte, text: "" }]) };
+        return { file: subject.file, source: applyReplacements(source, [{ start: definition.startByte, end: definition.endByte, text: "" }]) };
     }
     if (assertion.kind === "not-reaches"
         && assertion.relation.edges.length === 1
@@ -178,10 +184,14 @@ function mutateSource(policy, base, sourceFile, source) {
         if (parsed.imports.some((specifier) => externalPackage(specifier) === dependency)) {
             return { error: "mutation-forbidden-import-already-present" };
         }
-        const insertion = insertionPoint(source);
+        const insertion = importInsertionOffset(source);
         return {
             file: subject.file,
-            source: spliceChars(source, [{ start: insertion, end: insertion, text: `import ${JSON.stringify(dependency)}; // hunch deterministic source mutation\n` }]),
+            source: applyReplacements(source, [{
+                    start: insertion,
+                    end: insertion,
+                    text: `import ${JSON.stringify(dependency)}; // hunch deterministic source mutation\n`,
+                }]),
         };
     }
     const object = symbolForSelector(base, assertion.object);
@@ -198,11 +208,11 @@ function mutateSource(policy, base, sourceFile, source) {
             .map((call) => ({ start: call.atByte, end: call.endByte, text: "hunchMutationRemovedCall" }));
         if (!replacements.length)
             return { error: "mutation-required-call-unresolved" };
-        return { file: subject.file, source: spliceChars(source, replacements) };
+        return { file: subject.file, source: applyReplacements(source, replacements) };
     }
     if (!assertion.relation.edges.includes("calls"))
         return { error: "mutation-call-edge-not-supported" };
-    // String search, matching definition.startByte/endByte's actual units -- see spliceChars' doc comment.
+    // String search: offsets are string indices (see applyReplacements), not bytes.
     const open = source.indexOf("{", definition.startByte);
     if (open < 0 || open >= definition.endByte)
         return { error: "mutation-subject-body-unsupported" };
@@ -210,7 +220,7 @@ function mutateSource(policy, base, sourceFile, source) {
     if (object.file !== subject.file) {
         const specifier = relativeSpecifier(subject.file, object.file);
         if (!parsed.imports.includes(specifier)) {
-            const insertion = insertionPoint(source);
+            const insertion = importInsertionOffset(source);
             replacements.push({
                 start: insertion,
                 end: insertion,
@@ -220,7 +230,7 @@ function mutateSource(policy, base, sourceFile, source) {
     }
     return {
         file: subject.file,
-        source: spliceChars(source, replacements),
+        source: applyReplacements(source, replacements),
     };
 }
 function removeWorktree(root, hooks, env, checkout) {

package/dist/core/commitrepair.d.ts

@@ -1,5 +1,6 @@
 import type { Decision } from "./types.js";
 import type { CommitCandidate, CommitRepairStatus } from "../extractors/git.js";
+/** One proposed provenance fix: decision `id` cites `from`, which should cite `to`. */
 export interface CommitRewrite {
     id: string;
     from: string;
@@ -8,14 +9,12 @@ export interface CommitRewrite {
 /** 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. */
+/**
+ * Tombstone for a rewrite a human explicitly rejected with `--drop`. The key is
+ * the full `{id, from, to}` triple, not just `{id, from}`: a later merge that
+ * proposes a DIFFERENT `to` for the same `{id, from}` is a new proposal and
+ * must surface normally.
+ */
 export interface DroppedRewrite {
     id: string;
     from: string;
@@ -23,12 +22,10 @@ export interface DroppedRewrite {
 }
 export interface CommitRepairPlan {
     rewrites: CommitRewrite[];
+    /** Distinct decision ids the rewrites touch. */
     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. */
+/** Live decisions whose cited commit is orphaned (unresolvable/unknown/current are excluded). */
 export declare function orphanedCommitDecisions(decisions: readonly Decision[], status: (sha: string) => CommitRepairStatus): Decision[];
 /** Match each orphaned decision to exactly one candidate. A candidate with the
  *  same `git patch-id --stable` as the orphaned commit (a rebase- or
@@ -39,139 +36,47 @@ export declare function orphanedCommitDecisions(decisions: readonly Decision[],
  *  patch-id never equals any one of them, but weak: shared files like
  *  CHANGELOG.md often have one wrong superset (#450). */
 export declare function planCommitRepair(orphaned: readonly Decision[], candidates: readonly CommitCandidate[], patchIdOf?: (sha: string) => string | null): 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. */
+/** Queued entries that are still answerable: the decision exists, still cites `from`, and is live. */
 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. */
+/**
+ * Queued entries whose decision IS visible but moved on (different or null
+ * commit) or was superseded/rejected. An id absent from `decisions` is never
+ * dead: absence comes from the reader's view (a branch checkout, an unmounted
+ * private overlay) and the CLI deletes whatever this returns. Caveat: a decision
+ * that differs between branches could still read as "moved on".
+ */
 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. */
+/** Ids of `toApply` whose decision is visible, whether or not the rewrite changed it. */
 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. */
+/** Drop rewrites whose exact {id, from, to} triple is tombstoned. A plain filter: survivors keep identity. */
+export declare function withoutDropped<T extends CommitRewrite>(rewrites: readonly T[], dropped: readonly DroppedRewrite[]): T[];
+/** `existing` followed by the entries of `newly` whose exact triple is not already tombstoned. */
 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. */
+/**
+ * Fresh detections first, then the queued entries they did not override. A fresh
+ * entry overrides only the FIRST queued entry with its id (see `firstFor`);
+ * later duplicate-id siblings survive untouched.
+ */
 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): {
+/**
+ * Split entries by whether their proposed `to` resolves here. `existing === null`
+ * means the check could not run, so it fails open (everything applicable).
+ * Order and object references are preserved.
+ */
+export declare function withheldForUnresolvableTo(toApply: readonly CommitRewrite[], existing: ReadonlySet<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". */
+/** The single first-match rule for duplicate decision ids. */
+export declare function firstFor<T extends {
+    id: string;
+}>(entries: readonly T[], id: string): T | undefined;
+/** The plan's rewrite for `id` (first match). */
 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. */
+/**
+ * Pure: apply the plan's rewrite to a decision. Returns the same reference when
+ * there is no entry or the record moved on (`commit` no longer equals `from`);
+ * otherwise a copy with `commit` and the `commit:<from>` evidence moved to `to`
+ * (deduped if `to` was already cited).
+ */
 export declare function repairDecisionCommit(d: Decision, plan: CommitRepairPlan): Decision;