mandrel 2.54.0 → 2.56.0

package/.agents/scripts/lib/audit-advisories.js

@@ -0,0 +1,195 @@
+/**
+ * audit-advisories.js — run `npm audit --json` and diff advisories across refs.
+ *
+ * The measuring half of `audit-attribution.js` next door. That module owns the
+ * verdict vocabulary and how a verdict is worded; this one owns what a verdict
+ * is computed FROM.
+ *
+ * The comparison is **per advisory**, not per exit code. Reading only "did the
+ * base audit fail too" collapses the case a busy repository meets most: a base
+ * that is already red for advisory A, and a diff that adds advisory B. That
+ * answered `pre-existing` — a true statement about A, and a misleading one
+ * about the branch, because the author was told their diff was innocent while
+ * it was carrying B. Diffing advisory ids at or above `high` reports both facts
+ * separately: B introduced, A pre-existing.
+ *
+ * The npm spawn is injectable (`.agents/rules/test-seams.md`), so the whole
+ * projection is reachable without a registry round-trip.
+ */
+
+import { spawnCapture } from './child-exec.js';
+
+/** The levels the required SCA step fails on, so the levels attribution reads. */
+const BLOCKING_SEVERITIES = new Set(['critical', 'high']);
+
+/**
+ * The stable identity of one advisory in an `npm audit --json` report.
+ *
+ * `source` is the advisory's own numeric id and is what makes two runs
+ * comparable; the URL and title are fallbacks for a registry that omits it. A
+ * `via` entry that is a bare string names another package rather than an
+ * advisory and is handled by the package-level fallback in
+ * {@link extractBlockingAdvisories}.
+ *
+ * @param {object} via
+ * @returns {string|null}
+ */
+function advisoryIdOf(via) {
+  if (via?.source !== undefined && via.source !== null) {
+    return `advisory:${via.source}`;
+  }
+  if (typeof via?.url === 'string' && via.url.length > 0) return via.url;
+  if (typeof via?.title === 'string' && via.title.length > 0) {
+    return `title:${via.title}`;
+  }
+  return null;
+}
+
+/**
+ * Project an `npm audit --json` report onto the set of advisories at or above
+ * `high`, as `{ id, severity, title }` records sorted by id.
+ *
+ * A vulnerable package whose `via` list carries no advisory object at all — the
+ * transitive case, where `via` is a list of package names — still contributes a
+ * `package:<name>` entry. Dropping it would let a real blocking advisory go
+ * uncounted, and an attribution that under-counts the head is one that reports
+ * a genuine regression as `pre-existing`.
+ *
+ * @param {object|null} report — parsed `npm audit --json` output.
+ * @returns {Array<{ id: string, severity: string, title: string }>}
+ */
+export function extractBlockingAdvisories(report) {
+  const packages = report?.vulnerabilities;
+  if (!packages || typeof packages !== 'object') return [];
+  const found = new Map();
+  for (const [name, entry] of Object.entries(packages)) {
+    if (BLOCKING_SEVERITIES.has(String(entry?.severity ?? '').toLowerCase())) {
+      collectPackageAdvisories(name, entry, found);
+    }
+  }
+  return [...found.values()].sort((a, b) => a.id.localeCompare(b.id));
+}
+
+/**
+ * Add one vulnerable package's blocking advisories to `found`, falling back to
+ * a `package:<name>` entry when its `via` list names packages rather than
+ * advisories.
+ *
+ * @param {string} name
+ * @param {object} entry
+ * @param {Map<string, object>} found
+ */
+function collectPackageAdvisories(name, entry, found) {
+  const before = found.size;
+  for (const via of Array.isArray(entry?.via) ? entry.via : []) {
+    const severity = String(via?.severity ?? entry.severity).toLowerCase();
+    const id = BLOCKING_SEVERITIES.has(severity) ? advisoryIdOf(via) : null;
+    if (id && !found.has(id)) {
+      found.set(id, { id, severity, title: via?.title ?? name });
+    }
+  }
+  if (found.size === before) {
+    found.set(`package:${name}`, {
+      id: `package:${name}`,
+      severity: entry.severity,
+      title: name,
+    });
+  }
+}
+
+/**
+ * Split the head's blocking advisories into the ones this diff **introduced**
+ * (head minus base) and the ones the merge base already carried
+ * (the intersection).
+ *
+ * A `null` base is the degraded read: nothing can be attributed, so neither
+ * list is populated and the caller reports `unknown` rather than guessing.
+ *
+ * @param {{ head?: Array<object>, base?: Array<object>|null }} params
+ * @returns {{ introduced: Array<object>, preExisting: Array<object> }}
+ */
+export function diffAdvisories({ head = [], base = null }) {
+  if (!Array.isArray(base)) return { introduced: [], preExisting: [] };
+  const baseIds = new Set(base.map((a) => a.id));
+  return {
+    introduced: head.filter((a) => !baseIds.has(a.id)),
+    preExisting: head.filter((a) => baseIds.has(a.id)),
+  };
+}
+
+/**
+ * Run `npm audit --json` over a dependency manifest pair and project it.
+ *
+ * `--package-lock-only` audits the committed lockfile without installing, so
+ * the probe never touches the job's own `node_modules`: an attribution
+ * mechanism that could disturb the tree it is reporting on would be a worse
+ * defect than the one it explains. `--json` is what makes the two runs
+ * comparable at all — the human report says which advisories exist, but only
+ * as prose.
+ *
+ * @param {string} dir — directory holding package.json + package-lock.json.
+ * @param {{ spawn?: Function }} [deps]
+ * @returns {{ failed: boolean, advisories: Array<object> }}
+ * @throws {Error} when npm could not evaluate the tree at all.
+ */
+export function auditAdvisories(dir, { spawn = spawnCapture } = {}) {
+  const result = spawn(
+    'npm',
+    ['audit', '--json', '--audit-level=high', '--package-lock-only'],
+    { cwd: dir },
+  );
+  const report = parseAuditJson(result?.stdout);
+  // npm exits non-zero for "advisories found" and for "could not audit" alike.
+  // Only a real audit verdict carries a `vulnerabilities` map; anything else is
+  // a probe failure the caller must read as `unknown`.
+  if (!report) {
+    throw new Error(
+      `npm audit could not evaluate the tree: ${String(result?.stderr ?? '').slice(0, 200)}`,
+    );
+  }
+  const advisories = extractBlockingAdvisories(report);
+  return { failed: advisories.length > 0, advisories };
+}
+
+/**
+ * Parse `npm audit --json` stdout, returning `null` for anything that is not a
+ * real audit report. Never throws: a probe that crashed on its own output would
+ * be the second failure mode this module exists to avoid.
+ *
+ * @param {unknown} stdout
+ * @returns {object|null}
+ */
+function parseAuditJson(stdout) {
+  try {
+    const parsed = JSON.parse(String(stdout ?? ''));
+    return parsed?.vulnerabilities ? parsed : null;
+  } catch (_) {
+    return null;
+  }
+}
+
+/**
+ * Render the per-advisory detail lines that follow the verdict.
+ *
+ * Named lists, not counts: "3 introduced" sends the reader back to the raw
+ * audit output, which is the trip attribution exists to save.
+ *
+ * @param {{ introduced?: Array<object>, preExisting?: Array<object> }} input
+ * @returns {string[]}
+ */
+export function renderAdvisoryDetail({ introduced = [], preExisting = [] }) {
+  const list = (advisories) =>
+    advisories.map((a) => `${a.id} (${a.severity})`).join(', ');
+  const lines = [];
+  if (introduced.length > 0) {
+    lines.push(
+      `Introduced by this diff (${introduced.length}): ${list(introduced)}.`,
+    );
+  }
+  if (preExisting.length > 0) {
+    lines.push(
+      `Already on the merge base (${preExisting.length}): ${list(preExisting)}. Those are not this branch's to fix.`,
+    );
+  }
+  return lines;
+}

package/.agents/scripts/lib/audit-attribution.js

@@ -16,8 +16,25 @@
  * the same audit, evaluated against the pull request's merge base.
  *
  * It buys legibility, never permission — see `attributionExitCode`.
+ *
+ * The comparison is **per advisory**, not per exit code. Reading only "did the
+ * base audit fail too" collapses the case a busy repository meets most: a base
+ * that is already red for advisory A, and a diff that adds advisory B. That
+ * answered `pre-existing` — a true statement about A, and a misleading one
+ * about the branch, because the author was told their diff was innocent while
+ * it was carrying B. Diffing advisory ids at or above `high` reports both
+ * facts separately: B introduced, A pre-existing.
  */
 
+// The per-advisory machinery lives next door and is re-exported here, so this
+// module stays the one import an attribution consumer needs while the audit
+// runner, the projection and the diff keep their own file.
+export {
+  auditAdvisories,
+  diffAdvisories,
+  renderAdvisoryDetail,
+} from './audit-advisories.js';
+
 // The verdict vocabulary. Only `UNKNOWN` is exported: the CLI branches on it
 // to decide whether to audit the base at all, while the other two are read by
 // callers out of the rendered report rather than compared as symbols. Their
@@ -39,6 +56,11 @@ export const UNKNOWN = 'unknown';
  * attribution mechanism must never guess, because the guess it would make
  * (`introduced-by-this-diff`) is an accusation against the author reading it.
  *
+ * `baseAudit.failed` is asked **per advisory** by the CLI: it passes
+ * `{ failed: <the base already carries every advisory the head has> }`, so a
+ * base that is red for its own advisory does not absolve a diff that added a
+ * different one.
+ *
  * @param {{ headFailed: boolean, baseAudit: { failed: boolean } | null }} input
  * @returns {string} one of INTRODUCED / PRE_EXISTING / UNKNOWN
  */

package/.agents/scripts/lib/audit-to-stories/audit-label-taxonomy.js

@@ -26,13 +26,14 @@
  * label spelling — so a rename still lands in one place.
  */
 
+import { auditLabelFooter } from '../findings/route-finding.js';
 import {
   AGENT_LABELS,
   LABEL_COLORS,
   RISK_LABELS,
   TYPE_LABELS,
 } from '../label-constants.js';
-import { AUDIT_LENSES } from './audit-lenses.js';
+import { AUDIT_LENSES, auditLabelsForFindings } from './audit-lenses.js';
 
 /**
  * Per-lens label presentation, keyed by canonical lens name. A lens absent from
@@ -183,3 +184,26 @@ const DEFINED_NAMES = new Set(AUDIT_LABEL_TAXONOMY.map((l) => l.name));
 export function definesAuditLabel(name) {
   return typeof name === 'string' && DEFINED_NAMES.has(name);
 }
+
+/**
+ * Render the `audit-labels` footer for a group of findings.
+ *
+ * The dedup corpus is listed by `audit::*` label, so a Story filed without one
+ * is absent from the pool an indexed run matches against — and with an index in
+ * play the exact lookup is answered locally and never reaches the provider, so
+ * a fingerprint footer alone cannot rescue it. Carrying the labels through the
+ * seed is what lets the chained planning path stamp them without the authoring
+ * agent being asked to notice them (Story #5307).
+ *
+ * Lives here rather than beside {@link auditLabelsForFindings} because it needs
+ * {@link definesAuditLabel}, and the taxonomy already depends on the lens list —
+ * the reverse edge would be a cycle.
+ *
+ * @param {Array<object>} findings
+ * @returns {string} the footer, or '' when no finding resolves to a label.
+ */
+export function auditLabelFooterForFindings(findings) {
+  return auditLabelFooter(
+    auditLabelsForFindings(findings).filter(definesAuditLabel),
+  );
+}

package/.agents/scripts/lib/audit-to-stories/dedupe-against-github.js

@@ -22,11 +22,26 @@
  * reworded finding at an unchanged location still dedupes against its Issue
  * (Story #4626).
  *
- * Pure orchestration: this module performs no network I/O itself.
+ * When the caller injects a `listAuditIssues(labels)` port, the whole dedup
+ * corpus is pre-fetched **once per run** off the list endpoint and indexed by
+ * both provenance footers, so `findIssuesByFingerprint` is answered locally and
+ * the rate-limited search API is spent only on findings with no exact hit.
+ *
+ * A caller that already holds the corpus injects it directly as `issues`
+ * instead (Story #5301) — the host fetched it by whatever access path it has,
+ * which is what lets dedup run on a host with no `gh` CLI at all. That source
+ * needs no provider: with an index in play the exact lookup is answered from
+ * memory and `findIssuesByFingerprint` is never called, so the port is required
+ * only on the un-indexed path where it is genuinely used.
+ *
+ * Pure orchestration: this module performs no network I/O itself, and reads no
+ * file — the caller hands over an array, never a path.
  */
 
-import { routeFinding } from '../findings/route-finding.js';
+import { routeFinding, semanticKeyFor } from '../findings/route-finding.js';
 import { toCanonicalFinding } from './finding-adapter.js';
+import { prepareDedupRouting } from './issue-corpus.js';
+import { lookupLocally } from './issue-index.js';
 
 /**
  * @typedef {object} GroupClassification
@@ -39,6 +54,11 @@ import { toCanonicalFinding } from './finding-adapter.js';
 /**
  * Render a short, operator-legible reason from a dedup-lookup failure. Pure —
  * no imports, no I/O — so the module stays pure orchestration (Story #4678).
+ *
+ * Both degrade paths run through here, so the wording an operator reads for a
+ * failed index pre-fetch matches the wording for a failed per-group lookup:
+ * one vocabulary for "the GitHub read did not complete", whichever read it was.
+ *
  * @param {unknown} err
  * @returns {string}
  */
@@ -76,7 +96,7 @@ function groupLabel(group) {
  */
 async function classifyOneGroup(
   group,
-  { searchIssues, semanticPort, routeOptions },
+  { searchIssues, semanticPort, routeOptions, index },
 ) {
   const findings = group.findings ?? [];
   const matchedIssues = [];
@@ -91,9 +111,7 @@ async function classifyOneGroup(
     const canonical = toCanonicalFinding(finding);
     const { decision, matchedIssue, fingerprint } = await routeFinding(
       canonical,
-      semanticPort
-        ? { searchIssues, searchCandidates: () => semanticPort(canonical) }
-        : { searchIssues },
+      portsFor(canonical, sha, { searchIssues, semanticPort, index }),
       routeOptions,
     );
 
@@ -122,6 +140,33 @@ async function classifyOneGroup(
   return { action, matchedIssues, matchedFingerprints };
 }
 
+/**
+ * The read ports one finding is routed through.
+ *
+ * With no local index this is the historical wiring: the provider answers the
+ * exact lookup and the semantic port always runs. With an index, the exact
+ * lookup is answered from memory, and the semantic port — the only remaining
+ * network call — runs **only** when the index holds no exact fingerprint hit.
+ * That is the whole saving: a finding the sweep has already filed costs zero
+ * requests, and only a genuinely-unrecognised one is worth a search.
+ *
+ * @param {object} canonical — the canonical finding projection.
+ * @param {string} sha — its full fingerprint.
+ * @param {{ searchIssues: Function, semanticPort?: Function, index?: object }} routing
+ * @returns {{ searchIssues: Function, searchCandidates?: Function }}
+ */
+function portsFor(canonical, sha, { searchIssues, semanticPort, index }) {
+  const withSemantic = (ports) =>
+    semanticPort
+      ? { ...ports, searchCandidates: () => semanticPort(canonical) }
+      : ports;
+  if (!index) return withSemantic({ searchIssues });
+
+  const { exact, pool } = lookupLocally(index, sha, semanticKeyFor(canonical));
+  const local = { searchIssues: () => pool };
+  return exact.length > 0 ? local : withSemantic(local);
+}
+
 /**
  * @param {object} params
  * @param {Array<object>} params.groups — output of `groupFindings`.
@@ -130,6 +175,16 @@ async function classifyOneGroup(
  *   Optional meaning-first candidate search (production: `semantic-issue-search.js`).
  *   When supplied, routing runs the Stage-1 semantic pass and opts into
  *   location-based semantic-key confirmation.
+ * @param {(labels: string[]) => Promise<Array<object>>} [params.listAuditIssues]
+ *   Optional list port over the run's `audit::*` labels. When wired, its result
+ *   is fetched once and indexed, and `provider.findIssuesByFingerprint` is not
+ *   called at all — the exact lookup is answered from that index.
+ * @param {Array<object>} [params.issues]
+ *   Optional pre-fetched corpus the caller already holds, used in preference to
+ *   `listAuditIssues`. Supplying it makes `provider` optional: with an index in
+ *   play no provider read port is ever invoked, which is what lets a host with
+ *   no `gh` CLI dedup at all (Story #5301). An empty array is a valid corpus —
+ *   a first sweep — and is NOT read as "no index".
  * @param {(entry: { group: object, reason: string }) => void} [params.onDegraded]
  *   Optional sink notified once per group whose dedup lookup could not complete
  *   (Story #4678). The group is then classified `create` — a soft-fail, never
@@ -142,36 +197,32 @@ export async function classifyGroupsAgainstGitHub({
   provider,
   searchCandidates,
   onDegraded,
+  listAuditIssues,
+  issues,
 }) {
   if (!Array.isArray(groups)) {
     throw new Error('classifyGroupsAgainstGitHub: groups must be an array');
   }
-  if (!provider || typeof provider.findIssuesByFingerprint !== 'function') {
-    throw new Error(
-      'classifyGroupsAgainstGitHub: provider.findIssuesByFingerprint is required',
-    );
-  }
 
-  // Adapt the provider port into the `searchIssues` shape routeFinding wants.
-  // routeFinding hands the port the sha it computed off the canonical
-  // projection, which equals the sha the group already carries (both come
-  // from the same `toCanonicalFinding` projection).
-  const searchIssues = (sha) => provider.findIssuesByFingerprint(sha);
-  const semanticPort =
-    typeof searchCandidates === 'function' ? searchCandidates : undefined;
-  const routing = {
-    searchIssues,
-    semanticPort,
-    routeOptions: { semanticKeyConfirm: Boolean(semanticPort) },
-  };
+  const { routing, summary, error } = await prepareDedupRouting({
+    groups,
+    provider,
+    searchCandidates,
+    listAuditIssues,
+    issues,
+  });
+  if (error) {
+    // Same vocabulary as a per-group failure, but deliberately NOT counted as
+    // a degraded group: the count names groups classified without a check, and
+    // every group still gets one here, off the per-finding search path. Until
+    // Story #5301 this failure was swallowed whole, so the operator saw only
+    // the downstream per-group degradation and could not tell what caused it.
+    const reason = `issue-index pre-fetch failed: ${describeDegradeReason(error)}`;
+    summary.dedupDegraded.indexPrefetch = reason;
+    if (typeof onDegraded === 'function') onDegraded({ group: null, reason });
+  }
 
   const classifications = [];
-  const summary = {
-    create: 0,
-    skipOpen: 0,
-    skipReoccurring: 0,
-    dedupDegraded: { count: 0, groups: [] },
-  };
 
   for (const group of groups) {
     let result;

package/.agents/scripts/lib/audit-to-stories/finding-adapter.js

@@ -62,10 +62,14 @@ export function fingerprintAuditFinding(finding) {
  * shared helper. Stable across a reworded title; used to confirm a dedup
  * match when the fingerprint has drifted (Story #4626).
  *
+ * Module-internal since the ledger moved to the shared findings layer and takes
+ * its projection injected: `renderSemanticKeyFooter` below is the only caller,
+ * and re-exporting it for none would trip `dead-exports:production`.
+ *
  * @param {object} finding
  * @returns {string}
  */
-export function semanticKeyForAuditFinding(finding) {
+function semanticKeyForAuditFinding(finding) {
   return semanticKeyFor(toCanonicalFinding(finding));
 }
 

package/.agents/scripts/lib/audit-to-stories/issue-corpus.js

@@ -0,0 +1,162 @@
+/**
+ * lib/audit-to-stories/issue-corpus.js — where the dedup corpus comes from,
+ * and how a corpus that could not be fetched is described to the operator.
+ *
+ * Dedup needs exactly one thing from GitHub: the Issues carrying an `audit::*`
+ * label. Until Story #5301 the only source was the provider's list port, which
+ * spawns `gh`, so a host without a `gh` CLI — a Claude Code cloud sandbox,
+ * where `gh` is absent and direct API access is disabled while the GitHub MCP
+ * tools work fine — could not dedup at all: every group classified `create`
+ * and a scheduled sweep re-filed what it had already filed.
+ *
+ * Sourcing lives here rather than in `dedupe-against-github.js` so that module
+ * stays what its own header claims — pure routing of findings to verdicts —
+ * and so the empty-corpus and failed-fetch cases cannot diverge between call
+ * sites. Nothing here reaches the network or the filesystem: a caller that
+ * already holds the corpus passes the array in.
+ */
+
+import { auditLabelsForFindings } from './audit-lenses.js';
+import { buildIssueIndex } from './issue-index.js';
+
+/**
+ * Resolve the dedup corpus into an index, from whichever source is wired.
+ *
+ * A corpus the caller already holds (`issues`) wins: the host fetched it by
+ * whatever GitHub access path it has, which is what lets dedup run where there
+ * is no `gh` CLI. Otherwise the run's `audit::*` Issues are pre-fetched off the
+ * list port, once.
+ *
+ * Two results deliberately do NOT collapse to "no index", because a null index
+ * silently returns the run to the per-finding search — which on a
+ * provider-less host is no dedup at all, the failure this path exists to kill.
+ * An **empty** injected corpus is a legitimate first sweep and yields a real
+ * zero-row index. A **failed** pre-fetch hands back its `error` so the caller
+ * can say so in its own words: an operator who cannot see that the pre-fetch
+ * failed cannot tell a checked plan from an unchecked one.
+ *
+ * Module-internal: every caller reaches it through `prepareDedupRouting`, so
+ * the empty-corpus and failed-fetch cases cannot diverge between call sites.
+ *
+ * @param {{ listAuditIssues?: Function, groups?: Array<object>,
+ *   issues?: Array<object> }} params
+ * @returns {Promise<{ index: object|null, source: 'injected'|'prefetch'|'none',
+ *   error?: unknown }>}
+ */
+async function resolveIssueCorpus({ listAuditIssues, groups, issues }) {
+  if (Array.isArray(issues)) {
+    return { index: buildIssueIndex(issues), source: 'injected' };
+  }
+  const labels =
+    typeof listAuditIssues === 'function'
+      ? auditLabelsForFindings(
+          (groups ?? []).flatMap((group) => group?.findings ?? []),
+        )
+      : [];
+  if (labels.length === 0) return { index: null, source: 'none' };
+  try {
+    return {
+      index: buildIssueIndex(await listAuditIssues(labels)),
+      source: 'prefetch',
+    };
+  } catch (err) {
+    return { index: null, source: 'none', error: err };
+  }
+}
+
+/**
+ * Attach the index description to a seeded summary, when there is one to make.
+ *
+ * A run with neither an injected corpus nor a list port has no index to
+ * describe, and `{ source: 'none', size: 0 }` says nothing the field's absence
+ * does not — while inviting the reading "an index was consulted and it was
+ * empty", the exact confusion this whole path exists to remove. Omitting it
+ * also leaves the summary a pure per-finding-search run emits byte-identical
+ * to what it has always been.
+ *
+ * A failed pre-fetch is the one `none` that IS described: there the run ended
+ * *without* an index it expected to have, and the operator needs to see that.
+ *
+ * @param {object} summary — the seeded counters.
+ * @param {{ source: string, index: object|null, error?: unknown }} resolution
+ * @returns {object} the same summary, with `dedupIndex` when applicable.
+ */
+function withIndexDescription(summary, { source, index, error }) {
+  if (source === 'none' && !error) return summary;
+  return { ...summary, dedupIndex: { source, size: index?.size ?? 0 } };
+}
+
+/**
+ * Assemble everything routing needs from the caller's ports and corpus: the
+ * read ports, the resolved index, and the two facts the caller must report —
+ * what the corpus was and whether fetching it degraded.
+ *
+ * The provider port is validated here because this is where "is there a usable
+ * dedup source at all" is actually known. It is required only on the
+ * un-indexed path: once an index exists every exact lookup is answered from
+ * memory and `findIssuesByFingerprint` is never called, so demanding it there
+ * would be the one thing standing between a `gh`-less host and a real dedup
+ * run.
+ *
+ * @param {{ groups?: Array<object>, provider?: object,
+ *   searchCandidates?: Function, listAuditIssues?: Function,
+ *   issues?: Array<object> }} params
+ * The seeded `summary` comes back with it: the corpus is the only thing that
+ * knows what the index was, and returning the counters beside it keeps the
+ * caller from reconstructing a shape it does not own.
+ *
+ * @returns {Promise<{ routing: object, summary: object, error?: unknown }>}
+ * @throws {Error} when neither a provider read port nor a corpus is supplied.
+ */
+export async function prepareDedupRouting({
+  groups,
+  provider,
+  searchCandidates,
+  listAuditIssues,
+  issues,
+}) {
+  const hasProviderPort =
+    Boolean(provider) && typeof provider.findIssuesByFingerprint === 'function';
+  if (!hasProviderPort && !Array.isArray(issues)) {
+    throw new Error(
+      'classifyGroupsAgainstGitHub: provider.findIssuesByFingerprint is required ' +
+        'when no `issues` corpus is supplied',
+    );
+  }
+  const { index, source, error } = await resolveIssueCorpus({
+    listAuditIssues,
+    groups,
+    issues,
+  });
+  const semanticPort =
+    typeof searchCandidates === 'function' ? searchCandidates : undefined;
+  return {
+    routing: {
+      // routeFinding hands the port the sha it computed off the canonical
+      // projection, which equals the sha the group already carries.
+      searchIssues: hasProviderPort
+        ? (sha) => provider.findIssuesByFingerprint(sha)
+        : undefined,
+      semanticPort,
+      // An index carries the semantic-key map, so location-based confirmation
+      // costs nothing once one exists. Without this, confirmation would discard
+      // the `bySemanticKey` half of the pool the local lookup just built, and a
+      // provider-less run would be fingerprint-exact only — strictly weaker
+      // than the path it replaces.
+      routeOptions: {
+        semanticKeyConfirm: Boolean(semanticPort) || Boolean(index),
+      },
+      index,
+    },
+    summary: withIndexDescription(
+      {
+        create: 0,
+        skipOpen: 0,
+        skipReoccurring: 0,
+        dedupDegraded: { count: 0, groups: [] },
+      },
+      { source, index, error },
+    ),
+    error,
+  };
+}