@loopover/miner 0.1.0

package/lib/manage-status.js

@@ -0,0 +1,241 @@
+import { initEventLedger } from "./event-ledger.js";
+import { initPortfolioQueueStore } from "./portfolio-queue.js";
+import { initRunStateStore } from "./run-state.js";
+import { argsWantJson, reportCliFailure } from "./cli-error.js";
+
+/** Event vocabulary for manage-phase PR snapshots written by manage poll. (#2325) */
+export const MANAGE_PR_UPDATE_EVENT = "manage_pr_update";
+export const MANAGED_PR_IDENTIFIER_PREFIX = "pr:";
+
+export function parseManagedPrIdentifier(identifier) {
+  if (typeof identifier !== "string") return null;
+  const match = identifier.match(/^pr:(\d+)$/);
+  if (!match) return null;
+  const prNumber = Number(match[1]);
+  return Number.isInteger(prNumber) && prNumber > 0 ? prNumber : null;
+}
+
+export function formatManagedPrIdentifier(prNumber) {
+  if (!Number.isInteger(prNumber) || prNumber <= 0) throw new Error("invalid_pr_number");
+  return `${MANAGED_PR_IDENTIFIER_PREFIX}${prNumber}`;
+}
+
+function optionalString(value) {
+  if (value === undefined || value === null) return null;
+  if (typeof value !== "string") return null;
+  const trimmed = value.trim();
+  return trimmed || null;
+}
+
+function normalizeManageUpdatePayload(payload) {
+  if (!payload || typeof payload !== "object" || Array.isArray(payload)) return null;
+  if (!Number.isInteger(payload.prNumber) || payload.prNumber <= 0) return null;
+  return {
+    prNumber: payload.prNumber,
+    branch: optionalString(payload.branch),
+    ciState: optionalString(payload.ciState),
+    gateVerdict: optionalString(payload.gateVerdict),
+    outcome: optionalString(payload.outcome),
+    lastPolledAt: optionalString(payload.lastPolledAt),
+  };
+}
+
+/** Index the latest manage snapshot per repo/PR from ascending ledger events. Pure. */
+export function indexLatestManageUpdates(events) {
+  const latest = new Map();
+  for (const event of Array.isArray(events) ? events : []) {
+    if (event?.type !== MANAGE_PR_UPDATE_EVENT) continue;
+    if (typeof event.repoFullName !== "string" || !event.repoFullName.trim()) continue;
+    const normalized = normalizeManageUpdatePayload(event.payload);
+    if (!normalized) continue;
+    const key = `${event.repoFullName}:${normalized.prNumber}`;
+    latest.set(key, { ...normalized, repoFullName: event.repoFullName });
+  }
+  return latest;
+}
+
+/**
+ * Aggregate managed PR rows from the local portfolio queue and append-only event ledger. Read-only — never calls
+ * GitHub or mutates local stores. (#2325)
+ */
+export function collectManageStatus(sources) {
+  const portfolioQueue = sources?.portfolioQueue;
+  const eventLedger = sources?.eventLedger;
+  if (!portfolioQueue || typeof portfolioQueue.listQueue !== "function") {
+    throw new Error("invalid_portfolio_queue");
+  }
+  if (!eventLedger || typeof eventLedger.readEvents !== "function") {
+    throw new Error("invalid_event_ledger");
+  }
+
+  const rowsByKey = new Map();
+  for (const entry of portfolioQueue.listQueue(null)) {
+    const prNumber = parseManagedPrIdentifier(entry.identifier);
+    if (prNumber === null) continue;
+    const key = `${entry.repoFullName}:${prNumber}`;
+    rowsByKey.set(key, {
+      repoFullName: entry.repoFullName,
+      prNumber,
+      branch: null,
+      ciState: null,
+      gateVerdict: null,
+      outcome: null,
+      lastPolledAt: null,
+      queueStatus: entry.status,
+      priority: entry.priority,
+    });
+  }
+
+  for (const [key, update] of indexLatestManageUpdates(eventLedger.readEvents())) {
+    const existing = rowsByKey.get(key);
+    rowsByKey.set(key, {
+      repoFullName: update.repoFullName,
+      prNumber: update.prNumber,
+      branch: update.branch,
+      ciState: update.ciState,
+      gateVerdict: update.gateVerdict,
+      outcome: update.outcome,
+      lastPolledAt: update.lastPolledAt,
+      queueStatus: existing?.queueStatus ?? null,
+      priority: existing?.priority ?? null,
+    });
+  }
+
+  return [...rowsByKey.values()].sort((left, right) => {
+    const repoCmp = left.repoFullName.localeCompare(right.repoFullName);
+    if (repoCmp !== 0) return repoCmp;
+    return left.prNumber - right.prNumber;
+  });
+}
+
+/**
+ * Fold each tracked repo's current discover/plan/prepare run state alongside its managed PR rows into one
+ * "run portfolio" row per repo (#4279). `collectManageStatus` alone is PR-scoped only and never surfaces the
+ * run-state signal, so a repo actively discovering/planning with zero PRs yet is otherwise invisible. A repo
+ * appears here if it has EITHER a recorded run state OR at least one managed PR row.
+ */
+export function collectRunPortfolio(sources) {
+  const runStateStore = sources?.runStateStore;
+  if (!runStateStore || typeof runStateStore.listRunStates !== "function") {
+    throw new Error("invalid_run_state_store");
+  }
+  const prsByRepo = new Map();
+  for (const row of collectManageStatus(sources)) {
+    const list = prsByRepo.get(row.repoFullName) ?? [];
+    list.push(row);
+    prsByRepo.set(row.repoFullName, list);
+  }
+  // NOTE (#5563): keyed by repoFullName alone, not apiBaseUrl -- this dashboard fold predates multi-forge run
+  // states and produces exactly ONE row per repo name. If the same repo name has a recorded run state on two
+  // different hosts, only one (the later entry in listRunStates' order) survives here; the other's row is still
+  // intact in the store, just not surfaced in this particular view. Safe (no data loss, no write), just a display
+  // limitation -- broadening this fold to be host-aware is a separate, larger dashboard-shape change.
+  const runStateByRepo = new Map(runStateStore.listRunStates().map((entry) => [entry.repoFullName, entry]));
+
+  const repoFullNames = new Set([...prsByRepo.keys(), ...runStateByRepo.keys()]);
+  return [...repoFullNames].sort((left, right) => left.localeCompare(right)).map((repoFullName) => {
+    const prs = prsByRepo.get(repoFullName) ?? [];
+    const runState = runStateByRepo.get(repoFullName);
+    return {
+      repoFullName,
+      runState: runState?.state ?? null,
+      runStateUpdatedAt: runState?.updatedAt ?? null,
+      prCount: prs.length,
+      prs,
+    };
+  });
+}
+
+function display(value) {
+  if (value === null || value === undefined) return "-";
+  return String(value);
+}
+
+export function renderManageStatusTable(rows) {
+  if (!Array.isArray(rows) || rows.length === 0) return "no managed pull requests";
+  const header = [
+    "repo".padEnd(24),
+    "pr".padStart(4),
+    "branch".padEnd(16),
+    "ci".padEnd(10),
+    "gate".padEnd(10),
+    "outcome".padEnd(10),
+    "last-polled".padEnd(20),
+    "queue".padEnd(12),
+    "pri".padStart(4),
+  ].join(" ");
+  const lines = rows.map((row) =>
+    [
+      row.repoFullName.padEnd(24),
+      String(row.prNumber).padStart(4),
+      display(row.branch).padEnd(16),
+      display(row.ciState).padEnd(10),
+      display(row.gateVerdict).padEnd(10),
+      display(row.outcome).padEnd(10),
+      display(row.lastPolledAt).padEnd(20),
+      display(row.queueStatus).padEnd(12),
+      display(row.priority).padStart(4),
+    ].join(" "),
+  );
+  return [header, ...lines].join("\n");
+}
+
+/** One row per tracked repo (run state + PR count), the compact companion to {@link renderManageStatusTable}'s
+ *  per-PR detail (#4279). */
+export function renderRunPortfolioTable(portfolio) {
+  if (!Array.isArray(portfolio) || portfolio.length === 0) return "no tracked repos";
+  const header = [
+    "repo".padEnd(24),
+    "run-state".padEnd(12),
+    "updated".padEnd(20),
+    "prs".padStart(4),
+  ].join(" ");
+  const lines = portfolio.map((entry) =>
+    [
+      entry.repoFullName.padEnd(24),
+      display(entry.runState).padEnd(12),
+      display(entry.runStateUpdatedAt).padEnd(20),
+      String(entry.prCount).padStart(4),
+    ].join(" "),
+  );
+  return [header, ...lines].join("\n");
+}
+
+export function parseManageStatusArgs(args = []) {
+  for (const token of args) {
+    if (token === "--json") continue;
+    if (token.startsWith("-")) return { error: `Unknown option: ${token}` };
+    return { error: "Usage: gittensory-miner manage status [--json]" };
+  }
+  return { json: args.includes("--json") };
+}
+
+export function runManageStatus(args = [], options = {}) {
+  const parsed = parseManageStatusArgs(args);
+  if ("error" in parsed) {
+    return reportCliFailure(argsWantJson(args), parsed.error);
+  }
+
+  const ownsPortfolioQueue = options.initPortfolioQueue === undefined;
+  const ownsEventLedger = options.initEventLedger === undefined;
+  const ownsRunStateStore = options.initRunStateStore === undefined;
+  const portfolioQueue = (options.initPortfolioQueue ?? initPortfolioQueueStore)();
+  const eventLedger = (options.initEventLedger ?? initEventLedger)();
+  const runStateStore = (options.initRunStateStore ?? initRunStateStore)();
+  try {
+    const rows = collectManageStatus({ portfolioQueue, eventLedger });
+    const runPortfolio = collectRunPortfolio({ portfolioQueue, eventLedger, runStateStore });
+    if (parsed.json) {
+      // Additive only (#4279): `rows` keeps its existing shape unchanged; `runPortfolio` is a new key so an
+      // existing consumer parsing this JSON for `rows` alone sees byte-identical output.
+      console.log(JSON.stringify({ rows, runPortfolio }, null, 2));
+    } else {
+      console.log(`${renderManageStatusTable(rows)}\n\n${renderRunPortfolioTable(runPortfolio)}`);
+    }
+    return 0;
+  } finally {
+    if (ownsPortfolioQueue) portfolioQueue.close();
+    if (ownsEventLedger) eventLedger.close();
+    if (ownsRunStateStore) runStateStore.close();
+  }
+}

package/lib/metrics-cli.d.ts

@@ -0,0 +1,9 @@
+import type { MinerPredictionMetricRow } from "@loopover/engine";
+import type { PredictionLedger } from "./prediction-ledger.js";
+
+export function collectPredictionMetricRows(ledger: PredictionLedger): MinerPredictionMetricRow[];
+
+export function runMetrics(
+  args: string[],
+  options?: { initPredictionLedger?: () => PredictionLedger },
+): number;

package/lib/metrics-cli.js

@@ -0,0 +1,50 @@
+import { renderMinerPredictionMetrics } from "@loopover/engine";
+import { initPredictionLedger } from "./prediction-ledger.js";
+import { argsWantJson, describeCliError, reportCliFailure } from "./cli-error.js";
+
+// `metrics` (#4838): render the miner's prediction-calibration counters as Prometheus text-exposition to stdout,
+// for a scrape wrapper or cron redirect. The counters are produced by the engine's already-built
+// renderMinerPredictionMetrics (packages/gittensory-engine/src/miner-prediction-metrics.ts) -- this command only
+// reads the local prediction ledger and feeds it in, never touching the renderer itself. Strictly local + offline:
+// no network, no writes.
+
+const METRICS_USAGE = "Usage: gittensory-miner metrics";
+
+/**
+ * Project prediction-ledger rows onto the engine renderer's metric-row shape -- the predicted `conclusion` only.
+ * The realized-outcome pairing (`correct`) is intentionally left unset: the miner has no outcome-join yet, so the
+ * correct/incorrect counters stay zero and only `predictions_total{conclusion}` moves -- exactly how the renderer
+ * is designed to degrade before outcome-pairing exists (see its header comment).
+ */
+export function collectPredictionMetricRows(ledger) {
+  return ledger.readPredictions().map((entry) => ({ conclusion: entry.conclusion }));
+}
+
+// Open the local prediction ledger (or a test-injected one) for the duration of `run`, closing it only when we
+// opened it -- an injected ledger is owned by the caller. Mirrors event-ledger-cli.js's withEventLedger.
+function withPredictionLedger(options, run) {
+  const ownsLedger = options.initPredictionLedger === undefined;
+  const ledger = (options.initPredictionLedger ?? initPredictionLedger)();
+  try {
+    return run(ledger);
+  } finally {
+    if (ownsLedger) ledger.close();
+  }
+}
+
+export function runMetrics(args, options = {}) {
+  if (args.length > 0) {
+    return reportCliFailure(argsWantJson(args), METRICS_USAGE);
+  }
+
+  try {
+    return withPredictionLedger(options, (ledger) => {
+      // renderMinerPredictionMetrics returns a newline-terminated document; console.log re-adds the terminator, so
+      // trim it to emit exactly one trailing newline.
+      console.log(renderMinerPredictionMetrics(collectPredictionMetricRows(ledger)).trimEnd());
+      return 0;
+    });
+  } catch (error) {
+    return reportCliFailure(argsWantJson(args), describeCliError(error));
+  }
+}

package/lib/migrate-cli.d.ts

@@ -0,0 +1,24 @@
+export type MigrateStatus = "skipped" | "up-to-date" | "migrated" | "failed";
+
+export type MigrateResult = {
+  name: string;
+  dbPath: string;
+  ok: boolean;
+  status: MigrateStatus;
+  detail: string;
+  versionBefore: number | null;
+  versionAfter: number | null;
+};
+
+export type MigrateStoreDescriptor = {
+  name: string;
+  resolveDbPath: (env?: Record<string, string | undefined>) => string;
+  open: (dbPath: string) => { close: () => void };
+};
+
+export function runMigrateChecks(
+  env?: Record<string, string | undefined>,
+  stores?: MigrateStoreDescriptor[],
+): MigrateResult[];
+
+export function runMigrate(args?: string[], env?: Record<string, string | undefined>): number;

package/lib/migrate-cli.js

@@ -0,0 +1,111 @@
+// Proactive schema-migration runner for the miner's local SQLite stores (#4871). Every store already applies
+// its own pending migrations (schema-version.js's applySchemaMigrations) as a side effect of being opened by
+// whatever command happens to touch it first -- this command instead lets an operator PROACTIVELY bring every
+// known store's EXISTING on-disk file up to date in one pass (e.g. right after upgrading, or before starting a
+// fleet), without needing to guess which command happens to touch which store first. Mirrors status.js's
+// storeIntegrityChecks [name, resolve*DbPath(env)] store list exactly (same seven stores `doctor` already
+// covers), but actually OPENS each store (rather than a read-only integrity probe) so its real open/init
+// function's migration path runs for real. A store file that does not exist yet is skipped, not created --
+// "migrate" brings existing files up to date; it is not another way to bootstrap fresh state (that's `init`).
+import { existsSync } from "node:fs";
+import { DatabaseSync } from "node:sqlite";
+import { readSchemaVersion } from "./schema-version.js";
+import { openClaimLedger, resolveClaimLedgerDbPath } from "./claim-ledger.js";
+import { initEventLedger, resolveEventLedgerDbPath } from "./event-ledger.js";
+import { initGovernorLedger, resolveGovernorLedgerDbPath } from "./governor-ledger.js";
+import { initPredictionLedger, resolvePredictionLedgerDbPath } from "./prediction-ledger.js";
+import { initPortfolioQueueStore, resolvePortfolioQueueDbPath } from "./portfolio-queue.js";
+import { initRunStateStore, resolveRunStateDbPath } from "./run-state.js";
+import { openPlanStore, resolvePlanStoreDbPath } from "./plan-store.js";
+
+const STORES = [
+  { name: "event-ledger", resolveDbPath: resolveEventLedgerDbPath, open: initEventLedger },
+  { name: "governor-ledger", resolveDbPath: resolveGovernorLedgerDbPath, open: initGovernorLedger },
+  { name: "prediction-ledger", resolveDbPath: resolvePredictionLedgerDbPath, open: initPredictionLedger },
+  { name: "portfolio-queue", resolveDbPath: resolvePortfolioQueueDbPath, open: initPortfolioQueueStore },
+  { name: "claim-ledger", resolveDbPath: resolveClaimLedgerDbPath, open: openClaimLedger },
+  { name: "run-state", resolveDbPath: resolveRunStateDbPath, open: initRunStateStore },
+  { name: "plan-store", resolveDbPath: resolvePlanStoreDbPath, open: openPlanStore },
+];
+
+/** Read a store file's stamped schema version without ever creating it -- matches checkStoreIntegrity's
+ *  "not created yet" convention: an absent file has nothing to report a version for. */
+function peekSchemaVersion(dbPath) {
+  const db = new DatabaseSync(dbPath, { readOnly: true });
+  try {
+    return readSchemaVersion(db);
+  } finally {
+    db.close();
+  }
+}
+
+/**
+ * Bring one store's EXISTING on-disk schema up to date. Never throws: a store that fails to open/migrate is
+ * reported as a failed result so one bad store cannot abort the whole sweep, matching doctor's per-store
+ * isolation. A store file that does not exist yet is reported as a clean skip (nothing to migrate), never
+ * created as a side effect of running this command.
+ * @returns {{ name: string, dbPath: string, ok: boolean, status: "skipped"|"up-to-date"|"migrated"|"failed", detail: string, versionBefore: number|null, versionAfter: number|null }}
+ */
+function migrateStore({ name, resolveDbPath, open }, env) {
+  const dbPath = resolveDbPath(env);
+  if (!existsSync(dbPath)) {
+    return {
+      name,
+      dbPath,
+      ok: true,
+      status: "skipped",
+      detail: "not created yet",
+      versionBefore: null,
+      versionAfter: null,
+    };
+  }
+  // versionBefore is read INSIDE the same try as the migration itself: a corrupted file can throw on this very
+  // first read (a store that can't even be opened has no readable version either), and that must still surface
+  // as one failed store result rather than an uncaught exception aborting the whole sweep.
+  let versionBefore = null;
+  try {
+    versionBefore = peekSchemaVersion(dbPath);
+    const store = open(dbPath);
+    store.close();
+    const versionAfter = peekSchemaVersion(dbPath);
+    return {
+      name,
+      dbPath,
+      ok: true,
+      status: versionAfter > versionBefore ? "migrated" : "up-to-date",
+      detail: `v${versionBefore} -> v${versionAfter}`,
+      versionBefore,
+      versionAfter,
+    };
+  } catch (error) {
+    return {
+      name,
+      dbPath,
+      ok: false,
+      status: "failed",
+      detail: error instanceof Error ? error.message : String(error),
+      versionBefore,
+      versionAfter: versionBefore,
+    };
+  }
+}
+
+/** `stores` is injectable so tests can exercise a store descriptor's failure paths (e.g. a non-Error throw)
+ *  without depending on real node:sqlite error shapes; defaults to the real seven-store list. */
+export function runMigrateChecks(env = process.env, stores = STORES) {
+  return stores.map((store) => migrateStore(store, env));
+}
+
+export function runMigrate(args = [], env = process.env) {
+  const results = runMigrateChecks(env);
+  const failed = results.filter((result) => !result.ok);
+  if (args.includes("--json")) {
+    console.log(JSON.stringify({ ok: failed.length === 0, stores: results }, null, 2));
+  } else {
+    for (const result of results) {
+      console.log(`${result.ok ? result.status.padEnd(10) : "FAIL      "} ${result.name}: ${result.detail}`);
+    }
+    if (failed.length > 0) console.error(`migrate: ${failed.length} store(s) failed`);
+  }
+  return failed.length === 0 ? 0 : 1;
+}

package/lib/miner-goal-spec.d.ts

@@ -0,0 +1,12 @@
+import type { ParsedMinerGoalSpec } from "@loopover/engine";
+
+export function resolveMinerGoalSpec(
+  repoPath: string,
+  options?: {
+    existsSync?: (path: string) => boolean;
+    openSync?: (path: string, flags: number) => number;
+    fstatSync?: (fd: number) => import("node:fs").Stats;
+    readSync?: (fd: number, buffer: Buffer, offset: number, length: number, position: number | null) => number;
+    closeSync?: (fd: number) => void;
+  },
+): ParsedMinerGoalSpec;

package/lib/miner-goal-spec.js

@@ -0,0 +1,67 @@
+import { closeSync, constants, existsSync, fstatSync, openSync, readSync } from "node:fs";
+import { join } from "node:path";
+import { discoverMinerGoalSpecPath, parseMinerGoalSpecContent } from "@loopover/engine";
+
+const MAX_MINER_GOAL_SPEC_BYTES = 32_768;
+
+// Real local .gittensory-miner.yml resolver (#5132, Wave 3.5 follow-up). MinerGoalSpec's own discovery
+// helper (discoverMinerGoalSpecPath, packages/gittensory-engine) is deliberately IO-free -- the caller
+// injects the existence check. Unlike self-review-context.js/rejection-signal.js/ams-policy.js, which fetch
+// their target repo's files live over raw.githubusercontent.com BEFORE any clone exists, this resolver reads
+// the ALREADY-CLONED repo on disk (attempt-worktree.js's prepareAttemptWorktree runs first in the real
+// attempt-cli.js flow) -- no extra network round trip needed for a file that's already sitting in the
+// worktree.
+
+// Same convention as packages/gittensory-mcp/bin/gittensory-mcp.js's readCliTextFile: O_NOFOLLOW on open
+// atomically rejects a symlinked path (no separate pre-open lstat -- that would be a check-then-open race, since
+// a symlink can be swapped in between the lstat and the open). Bounds the READ itself, not just fstat's
+// reported size, since a regular file can still grow between fstatSync and the read below.
+function readRegularUtf8File(path, options) {
+  const openImpl = options.openSync ?? openSync;
+  const fstatImpl = options.fstatSync ?? fstatSync;
+  const readImpl = options.readSync ?? readSync;
+  const closeImpl = options.closeSync ?? closeSync;
+
+  const fd = openImpl(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+  try {
+    const stats = fstatImpl(fd);
+    if (!stats.isFile() || stats.size > MAX_MINER_GOAL_SPEC_BYTES) return null;
+    const buffer = Buffer.alloc(MAX_MINER_GOAL_SPEC_BYTES + 1);
+    let bytesRead = 0;
+    while (bytesRead < buffer.length) {
+      const n = readImpl(fd, buffer, bytesRead, buffer.length - bytesRead, null);
+      if (n === 0) break;
+      bytesRead += n;
+    }
+    if (bytesRead > MAX_MINER_GOAL_SPEC_BYTES) return null;
+    return buffer.subarray(0, bytesRead).toString("utf8");
+  } finally {
+    closeImpl(fd);
+  }
+}
+
+/**
+ * Resolve the real, parsed MinerGoalSpec for an already-cloned repo at `repoPath`, trying each
+ * MINER_GOAL_SPEC_FILENAMES candidate in the documented discovery order. Never throws: a missing file, an
+ * unreadable file, or malformed content all degrade to the tolerant parser's own absent/safe-default result.
+ *
+ * Injected filesystem operations receive the FULL joined path (same convention as `node:fs`'s own
+ * functions), not a repoPath-relative candidate.
+ *
+ * @param {string} repoPath
+ * @param {{ existsSync?: (path: string) => boolean, openSync?: (path: string, flags: number) => number, fstatSync?: (fd: number) => import("node:fs").Stats, readSync?: (fd: number, buffer: Buffer, offset: number, length: number, position: number | null) => number, closeSync?: (fd: number) => void }} [options]
+ * @returns {import("@loopover/engine").ParsedMinerGoalSpec}
+ */
+export function resolveMinerGoalSpec(repoPath, options = {}) {
+  const existsImpl = options.existsSync ?? existsSync;
+
+  const relativePath = discoverMinerGoalSpecPath((candidate) => existsImpl(join(repoPath, candidate)));
+  if (!relativePath) return parseMinerGoalSpecContent(null);
+
+  try {
+    const content = readRegularUtf8File(join(repoPath, relativePath), options);
+    return parseMinerGoalSpecContent(content);
+  } catch {
+    return parseMinerGoalSpecContent(null);
+  }
+}

package/lib/opportunity-fanout.d.ts

@@ -0,0 +1,86 @@
+import type { ForgeConfig } from "./forge-config.js";
+import type { PolicyDocCache } from "./policy-doc-cache.js";
+import type { PolicyVerdictCache } from "./policy-verdict-cache.js";
+
+export type FanoutTarget = {
+  owner: string;
+  repo: string;
+};
+
+/** Options shared by every fan-out entry point. `apiBaseUrl` is the legacy top-level forge-host override (it still
+ * wins over `forge.apiBaseUrl`); `forge` (#4784) carries the rest of the per-tenant forge knobs. `policyDocCache`,
+ * when supplied, lets discovery revalidate each repo's policy docs with a conditional GET instead of a full
+ * refetch (#4842). `policyVerdictCache`, when supplied, lets discovery reuse an already-resolved verdict once its
+ * deciding doc's ETag is confirmed unchanged, instead of re-resolving it (#4843). */
+export type FanoutOptions = {
+  apiBaseUrl?: string;
+  forge?: Partial<ForgeConfig>;
+  concurrency?: number;
+  rateLimitLowWaterMark?: number;
+  rateLimitHighWaterMark?: number;
+  perPage?: number;
+  maxPages?: number;
+  sleepFn?: (ms: number) => Promise<unknown>;
+  policyDocCache?: PolicyDocCache | null;
+  policyVerdictCache?: PolicyVerdictCache | null;
+};
+
+export type RawCandidateIssue = {
+  owner: string;
+  repo: string;
+  repoFullName: string;
+  issueNumber: number;
+  title: string;
+  labels: string[];
+  commentsCount: number;
+  createdAt: string | null;
+  updatedAt: string | null;
+  htmlUrl: string | null;
+  aiPolicyAllowed: true;
+  aiPolicySource: "AI-USAGE.md" | "CONTRIBUTING.md" | "none";
+};
+
+export type CandidateIssueWarning = {
+  repoFullName: string;
+  stage: string;
+  message: string;
+};
+
+export type CandidateIssueSummary = {
+  issues: RawCandidateIssue[];
+  rateLimitRemaining: number | null;
+  rateLimitResetAt: string | null;
+  warnings: CandidateIssueWarning[];
+};
+
+export function mapWithConcurrency<T, R>(
+  items: T[],
+  maxConcurrency: number,
+  worker: (item: T, index: number) => Promise<R>,
+  resolveLimit: () => number,
+  sleepFn?: (ms: number) => Promise<unknown>,
+): Promise<R[]>;
+
+export function fetchCandidateIssuesWithSummary(
+  targets: FanoutTarget[],
+  githubToken: string,
+  options?: FanoutOptions,
+): Promise<CandidateIssueSummary>;
+
+export function fetchCandidateIssues(
+  targets: FanoutTarget[],
+  githubToken: string,
+  options?: FanoutOptions,
+): Promise<RawCandidateIssue[]>;
+
+export function searchCandidateIssuesWithSummary(
+  searchQuery: string,
+  githubToken: string,
+  options?: FanoutOptions,
+): Promise<CandidateIssueSummary>;
+
+export function searchCandidateIssues(
+  searchQuery: string,
+  githubToken: string,
+  options?: FanoutOptions,
+): Promise<RawCandidateIssue[]>;