@loopover/miner 0.1.0

package/lib/pr-disposition-poller.d.ts

@@ -0,0 +1,26 @@
+export type PrDisposition = {
+  state: "open" | "closed";
+  merged: boolean;
+  closedAt: string | null;
+  attempts: number;
+};
+
+export type PollPrDispositionOptions = {
+  apiBaseUrl?: string;
+  fetchFn?: typeof fetch;
+  githubToken?: string;
+  maxAttempts?: number;
+  minIntervalMs?: number;
+  maxIntervalMs?: number;
+  sleepFn?: (delayMs: number) => Promise<void>;
+};
+
+export function pollPrDisposition(
+  repoFullName: string,
+  prNumber: number,
+  options?: PollPrDispositionOptions,
+): Promise<PrDisposition>;
+
+export function classifyPrDisposition(
+  disposition: Pick<PrDisposition, "state" | "merged">,
+): "merged" | "disengaged" | "other";

package/lib/pr-disposition-poller.js

@@ -0,0 +1,163 @@
+// Real PR-disposition poller (#5135, Wave 3.5 -- the autonomous loop). ci-poller.js already polls a PR's CI
+// check-runs, but that answers a DIFFERENT question ("did the checks pass") from what the supervising loop
+// needs at cycle-close time ("did the PR itself get merged or closed"). Nothing in this package answered that
+// second question before this file: pr-outcome.js already has a real store for the classification
+// (recordPrOutcomeSnapshot/readPrOutcomes), but every existing caller of it was a test -- this is the real
+// GitHub fetch that produces the classification pr-outcome.js's writer expects.
+//
+// Deliberately its own module, not folded into ci-poller.js: the two pollers ask genuinely different
+// questions (check-run conclusion vs. PR merge/close disposition) with different terminal conditions (a
+// check-run poll's "pending" means "wait for the SAME head commit's checks to finish"; a disposition poll's
+// "open" means "wait for a human to actually merge or close the PR", a potentially much longer, unbounded
+// wait) -- composing them into one poller would conflate two different backoff/timeout policies.
+
+const defaultApiBaseUrl = "https://api.github.com";
+const defaultMinIntervalMs = 60_000;
+const defaultMaxIntervalMs = 5 * 60_000;
+const defaultMaxAttempts = 1;
+const githubApiVersion = "2022-11-28";
+
+function normalizeApiBaseUrl(value) {
+  if (value === undefined) return defaultApiBaseUrl;
+  if (typeof value !== "string" || !value.trim()) return defaultApiBaseUrl;
+  let parsed;
+  try {
+    parsed = new URL(value.trim());
+  } catch {
+    throw new Error("invalid_api_base_url");
+  }
+  if (parsed.protocol !== "https:" || parsed.hostname !== "api.github.com") {
+    throw new Error("invalid_api_base_url");
+  }
+  parsed.pathname = parsed.pathname.replace(/\/+$/, "");
+  parsed.search = "";
+  parsed.hash = "";
+  return parsed.toString().replace(/\/+$/, "");
+}
+
+function normalizePositiveInt(value, fallback, min, max) {
+  if (!Number.isFinite(value)) return fallback;
+  return Math.min(max, Math.max(min, Math.floor(value)));
+}
+
+function normalizeOptions(options = {}) {
+  return {
+    apiBaseUrl: normalizeApiBaseUrl(options.apiBaseUrl),
+    fetchFn: options.fetchFn ?? fetch,
+    githubToken: typeof options.githubToken === "string" ? options.githubToken.trim() : "",
+    maxAttempts: normalizePositiveInt(options.maxAttempts, defaultMaxAttempts, 1, 20),
+    minIntervalMs: normalizePositiveInt(options.minIntervalMs, defaultMinIntervalMs, 1, 60 * 60_000),
+    maxIntervalMs: normalizePositiveInt(options.maxIntervalMs, defaultMaxIntervalMs, 1, 60 * 60_000),
+    sleepFn:
+      options.sleepFn ??
+      ((delayMs) => new Promise((resolve) => setTimeout(resolve, delayMs))),
+  };
+}
+
+function parseRepoFullName(repoFullName) {
+  if (typeof repoFullName !== "string") throw new Error("invalid_repo_full_name");
+  const [owner, repo, extra] = repoFullName.split("/");
+  if (!owner?.trim() || !repo?.trim() || extra !== undefined) {
+    throw new Error("invalid_repo_full_name");
+  }
+  return { owner: owner.trim(), repo: repo.trim() };
+}
+
+function normalizePullNumber(value) {
+  if (!Number.isInteger(value) || value <= 0) throw new Error("invalid_pr_number");
+  return value;
+}
+
+function githubHeaders(githubToken) {
+  const headers = {
+    accept: "application/vnd.github+json",
+    "user-agent": "loopover-miner",
+    "x-github-api-version": githubApiVersion,
+  };
+  if (githubToken) headers.authorization = `Bearer ${githubToken}`;
+  return headers;
+}
+
+function repoPath(target, suffix) {
+  return `/repos/${encodeURIComponent(target.owner)}/${encodeURIComponent(target.repo)}${suffix}`;
+}
+
+function apiUrl(apiBaseUrl, path) {
+  return `${apiBaseUrl}${path}`;
+}
+
+function githubError(response, payload) {
+  const code = `github_${response.status}`;
+  const githubMessage =
+    typeof payload?.message === "string" && payload.message.trim() ? payload.message : null;
+  const message = githubMessage ? `${code}: ${githubMessage}` : code;
+  return Object.assign(new Error(message), { code, githubMessage });
+}
+
+async function fetchPullRequest(target, prNumber, options) {
+  const response = await options.fetchFn(apiUrl(options.apiBaseUrl, repoPath(target, `/pulls/${prNumber}`)), {
+    method: "GET",
+    headers: githubHeaders(options.githubToken),
+  });
+  const payload = await response.json().catch(() => null);
+  if (!response.ok) throw githubError(response, payload);
+  return payload;
+}
+
+/** GitHub's own vocabulary is `state: "open"|"closed"` plus a separate `merged: boolean` -- "closed and not
+ *  merged" is the disengaged case. A still-open PR is never terminal for this poller's purposes. */
+function normalizeDisposition(payload) {
+  const state = payload?.state === "closed" ? "closed" : "open";
+  const merged = Boolean(payload?.merged);
+  const closedAt = typeof payload?.closed_at === "string" ? payload.closed_at : null;
+  return { state, merged, closedAt };
+}
+
+function backoffDelayMs(attemptIndex, options) {
+  const exponent = Math.min(10, Math.max(0, attemptIndex));
+  return Math.min(options.maxIntervalMs, options.minIntervalMs * 2 ** exponent);
+}
+
+/**
+ * Poll a real PR's own merge/close disposition (distinct from its CI check-run conclusion, ci-poller.js's
+ * concern) with exponential backoff, until it reaches a terminal `state: "closed"` or `maxAttempts` is
+ * exhausted -- whichever comes first. A still-`"open"` PR after the last attempt is returned as-is, not an
+ * error: an unattended loop cycle should treat "still open" as "not yet resolved", not fail.
+ *
+ * @param {string} repoFullName
+ * @param {number} prNumber
+ * @param {{
+ *   apiBaseUrl?: string, fetchFn?: typeof fetch, githubToken?: string, maxAttempts?: number,
+ *   minIntervalMs?: number, maxIntervalMs?: number, sleepFn?: (delayMs: number) => Promise<void>,
+ * }} [options]
+ * @returns {Promise<{ state: "open"|"closed", merged: boolean, closedAt: string|null, attempts: number }>}
+ */
+export async function pollPrDisposition(repoFullName, prNumber, options = {}) {
+  const target = parseRepoFullName(repoFullName);
+  const normalizedPrNumber = normalizePullNumber(prNumber);
+  const normalizedOptions = normalizeOptions(options);
+
+  let latest = { state: "open", merged: false, closedAt: null, attempts: 0 };
+  for (let attempt = 0; attempt < normalizedOptions.maxAttempts; attempt += 1) {
+    const payload = await fetchPullRequest(target, normalizedPrNumber, normalizedOptions);
+    latest = { ...normalizeDisposition(payload), attempts: attempt + 1 };
+    if (latest.state === "closed") return latest;
+    if (attempt === normalizedOptions.maxAttempts - 1) return latest;
+    await normalizedOptions.sleepFn(backoffDelayMs(attempt, normalizedOptions));
+  }
+  return latest;
+}
+
+/**
+ * Classify a real, terminal PR disposition into loop-reentry.js's own `candidate.outcome` vocabulary
+ * (`"merged"|"disengaged"|"other"`). A still-open disposition (not yet resolved) classifies as `"other"` --
+ * the same bucket a runMinerAttempt outcome that never opened a PR at all falls into (nothing to re-enter on
+ * yet, in either case).
+ *
+ * @param {{ state: "open"|"closed", merged: boolean }} disposition
+ * @returns {"merged"|"disengaged"|"other"}
+ */
+export function classifyPrDisposition(disposition) {
+  if (disposition.state !== "closed") return "other";
+  return disposition.merged ? "merged" : "disengaged";
+}

package/lib/pr-number-parse.d.ts

@@ -0,0 +1,4 @@
+export function parsePrNumberFromExecResult(
+  execResult: { stdout?: string | undefined; code?: number | null | undefined; timedOut?: boolean | undefined } | null | undefined,
+  repoFullName: string,
+): number | null;

package/lib/pr-number-parse.js

@@ -0,0 +1,23 @@
+// Shared PR-number extraction from a real `gh pr create` executeLocalWrite result (#4848). `gh pr create`
+// prints the new PR's URL to stdout on success -- this is the one place that URL is authoritatively parsed,
+// so loop-cli.js's CI/gate-status polling and attempt-cli.js's post-submission claim-conflict check agree on
+// exactly how a PR number is recovered from a real command's raw output.
+
+/** `gh pr create` (local-write-tools.ts's `buildOpenPrSpec` -- no `--json` flag) prints the created PR's own
+ *  URL to stdout on success; this is `gh`'s real, documented, stable CLI behavior, not an invented contract.
+ *  Scoped to the exact target repo so an unrelated URL elsewhere in stdout/stderr noise can never match.
+ *
+ * @param {{ stdout?: string, code?: number | null, timedOut?: boolean } | null | undefined} execResult
+ * @param {string} repoFullName
+ * @returns {number | null}
+ */
+export function parsePrNumberFromExecResult(execResult, repoFullName) {
+  if (!execResult || execResult.timedOut || execResult.code !== 0 || typeof execResult.stdout !== "string") {
+    return null;
+  }
+  const escapedRepo = repoFullName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const match = execResult.stdout.match(new RegExp(`github\\.com/${escapedRepo}/pull/(\\d+)`));
+  if (!match) return null;
+  const prNumber = Number(match[1]);
+  return Number.isInteger(prNumber) && prNumber > 0 ? prNumber : null;
+}

package/lib/pr-outcome.d.ts

@@ -0,0 +1,41 @@
+import type { AppendEventInput, LedgerEntry } from "./event-ledger.js";
+
+export const MINER_PR_OUTCOME_EVENT: "pr_outcome";
+export const MINER_PR_OUTCOME_DECISIONS: readonly ["merged", "closed"];
+
+export type MinerPrOutcomeDecision = "merged" | "closed";
+
+export interface NormalizedPrOutcomePayload {
+  prNumber: number;
+  decision: MinerPrOutcomeDecision;
+  closedAt: string | null;
+  reason: string | null;
+}
+
+export interface PrOutcomeInput {
+  repoFullName?: unknown;
+  prNumber?: unknown;
+  decision?: unknown;
+  closedAt?: unknown;
+  reason?: unknown;
+}
+
+export interface RecordPrOutcomeOptions {
+  /** Optional at the type level so a caller can pass an unusable ledger to exercise the fail-closed guard; the
+   *  writer throws `invalid_event_ledger` at runtime when this is absent or lacks `appendEvent`. Reuses the
+   *  real EventLedger#appendEvent signature so a genuine EventLedger (not just a same-shaped stub) type-checks. */
+  eventLedger?: { appendEvent(event: AppendEventInput): LedgerEntry };
+}
+
+export interface PrOutcomeLedgerReader {
+  readEvents(filter?: { since?: number; repoFullName?: string }): unknown[];
+}
+
+export function normalizePrOutcomePayload(payload: unknown): NormalizedPrOutcomePayload | null;
+
+export function recordPrOutcomeSnapshot(input: PrOutcomeInput, options?: RecordPrOutcomeOptions): unknown;
+
+export function readPrOutcomes(
+  eventLedger: PrOutcomeLedgerReader,
+  filter?: { since?: number; repoFullName?: string },
+): Map<string, NormalizedPrOutcomePayload & { repoFullName: string }>;

package/lib/pr-outcome.js

@@ -0,0 +1,90 @@
+// Miner-local PR-outcome record (#4274). The miner's OWN local record of the outcomes of its OWN PRs — merged or
+// closed — written to the miner's local SQLite via the generic append-only event-ledger.js, mirroring how
+// manage-status.js layers a specific typed event (MANAGE_PR_UPDATE_EVENT + a payload normalizer + a thin writer)
+// on top of that same ledger.
+//
+// DISTINCT from the server-side `pr_outcome` concept: src/review/outcomes-wire.ts's `recordPrOutcome` writes
+// `pr_outcome` rows to the HOSTED backend's D1 audit tables from the GitHub App's webhook stream — that is the
+// gittensory SERVER recording ground truth for every contributor. THIS is a laptop-mode miner's local record of
+// its own PRs (it may have no webhook relay at all): same concept name, different codebase layer, no shared code.
+// The distinct `MINER_PR_OUTCOME_EVENT` local constant keeps the two from being conflated.
+
+import { REJECTION_REASONS } from "./rejection-templates.js";
+
+/** Event-ledger vocabulary for a miner-local PR outcome. */
+export const MINER_PR_OUTCOME_EVENT = "pr_outcome";
+
+/** The terminal decisions a miner records for one of its own PRs. */
+export const MINER_PR_OUTCOME_DECISIONS = Object.freeze(["merged", "closed"]);
+
+const decisionSet = new Set(MINER_PR_OUTCOME_DECISIONS);
+const reasonSet = new Set(REJECTION_REASONS);
+
+function optionalString(value) {
+  if (value === undefined || value === null) return null;
+  if (typeof value !== "string") return null;
+  const trimmed = value.trim();
+  return trimmed || null;
+}
+
+/**
+ * Validate + normalize a PR-outcome payload; returns `null` on any malformed shape (mirrors manage-status.js's
+ * `normalizeManageUpdatePayload`, so a bad row can neither be written nor read back). A `closed` decision may carry
+ * a reason bucket drawn from {@link REJECTION_REASONS} (shared with the rejection-state-machine sibling); a `merged`
+ * decision — or an unrecognized reason — normalizes the reason to `null` (a merged PR has no rejection reason).
+ */
+export function normalizePrOutcomePayload(payload) {
+  if (!payload || typeof payload !== "object" || Array.isArray(payload)) return null;
+  if (!Number.isInteger(payload.prNumber) || payload.prNumber <= 0) return null;
+  const decision = optionalString(payload.decision);
+  if (!decision || !decisionSet.has(decision)) return null;
+  const reasonRaw = optionalString(payload.reason);
+  const reason = decision === "closed" && reasonRaw !== null && reasonSet.has(reasonRaw) ? reasonRaw : null;
+  return {
+    prNumber: payload.prNumber,
+    decision,
+    closedAt: optionalString(payload.closedAt),
+    reason,
+  };
+}
+
+/**
+ * Thin writer over an INJECTED event ledger (same dependency-injection shape as manage-poll.js's
+ * `recordManagePollSnapshot`, so it's unit-testable without a real ledger file). Appends one
+ * {@link MINER_PR_OUTCOME_EVENT} scoped to the repo and returns the appended entry. Fail-soft on a malformed
+ * snapshot: a missing repo or an invalid payload returns `null` rather than throwing (an unusable ledger is the
+ * only hard error, since that is a programmer wiring mistake).
+ */
+export function recordPrOutcomeSnapshot(input, options = {}) {
+  const eventLedger = options.eventLedger;
+  if (!eventLedger || typeof eventLedger.appendEvent !== "function") throw new Error("invalid_event_ledger");
+  const repoFullName = typeof input?.repoFullName === "string" ? input.repoFullName.trim() : "";
+  if (!repoFullName) return null;
+  const payload = normalizePrOutcomePayload({
+    prNumber: input?.prNumber,
+    decision: input?.decision,
+    closedAt: input?.closedAt,
+    reason: input?.reason,
+  });
+  if (!payload) return null;
+  return eventLedger.appendEvent({ type: MINER_PR_OUTCOME_EVENT, repoFullName, payload });
+}
+
+/**
+ * Reconstruct the latest outcome per repo/PR from the ledger's ascending append-only event stream (mirrors
+ * manage-status.js's `indexLatestManageUpdates`). Reads via the injected ledger's `readEvents(filter)` and reduces
+ * the pure result — a later event for the same repo/PR supersedes an earlier one. Returns a `Map` keyed by
+ * `repoFullName:prNumber`.
+ */
+export function readPrOutcomes(eventLedger, filter = {}) {
+  const events = eventLedger && typeof eventLedger.readEvents === "function" ? eventLedger.readEvents(filter) : [];
+  const latest = new Map();
+  for (const event of Array.isArray(events) ? events : []) {
+    if (event?.type !== MINER_PR_OUTCOME_EVENT) continue;
+    if (typeof event.repoFullName !== "string" || !event.repoFullName.trim()) continue;
+    const normalized = normalizePrOutcomePayload(event.payload);
+    if (!normalized) continue;
+    latest.set(`${event.repoFullName}:${normalized.prNumber}`, { ...normalized, repoFullName: event.repoFullName });
+  }
+  return latest;
+}

package/lib/prediction-ledger.d.ts

@@ -0,0 +1,47 @@
+export type PredictionLedgerEntry = {
+  id: number;
+  ts: string;
+  repoFullName: string;
+  targetId: number;
+  headSha: string | null;
+  conclusion: string;
+  pack: string;
+  readinessScore: number | null;
+  blockerCodes: string[];
+  warningCodes: string[];
+  engineVersion: string;
+};
+
+export type AppendPredictionInput = {
+  repoFullName: string;
+  targetId: number;
+  headSha?: string | null;
+  conclusion: string;
+  pack: string;
+  readinessScore?: number | null;
+  blockerCodes?: string[];
+  warningCodes?: string[];
+  engineVersion: string;
+};
+
+export type ReadPredictionsFilter = {
+  repoFullName?: string | null;
+};
+
+export type PredictionLedger = {
+  dbPath: string;
+  appendPrediction(input: AppendPredictionInput): PredictionLedgerEntry;
+  readPredictions(filter?: ReadPredictionsFilter): PredictionLedgerEntry[];
+  purgeByRepo(repoFullName: string): number;
+  close(): void;
+};
+
+export function resolvePredictionLedgerDbPath(env?: Record<string, string | undefined>): string;
+
+export function initPredictionLedger(dbPath?: string): PredictionLedger;
+
+export function appendPrediction(input: AppendPredictionInput): PredictionLedgerEntry;
+
+export function readPredictions(filter?: ReadPredictionsFilter): PredictionLedgerEntry[];
+
+export function closeDefaultPredictionLedger(): void;

package/lib/prediction-ledger.js

@@ -0,0 +1,222 @@
+import { chmodSync, mkdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { DatabaseSync } from "node:sqlite";
+import {
+  PREDICTION_LEDGER_PURGE_SPEC,
+  PREDICTION_LEDGER_RETENTION_SPEC,
+  purgeStoreByRepo,
+  pruneLedgerByRetention,
+  resolveLedgerRetentionPolicy,
+} from "./store-maintenance.js";
+
+// Append-only prediction ledger (#4263): every predicted-gate verdict the miner computes for a target lands in
+// a local SQLite table so a later self-improve pass can score the prediction against the realized pr_outcome.
+// IMMUTABILITY INVARIANT: `appendPrediction`/`readPredictions` only ever issue INSERT and SELECT — never
+// UPDATE/DELETE. Two documented exceptions, both separate maintenance operations rather than part of normal
+// ledger operation: opt-in retention pruning (#4834, automatic) and `purgeByRepo` (#5564, always explicit and
+// operator-invoked, never automatic). Rows are kept small and stable for later diffing: blocker/warning CODES
+// only (no free-text detail), plus the ENGINE_VERSION that produced the call so a row self-reports which engine
+// build made it. Mirrors governor-ledger.js's shape; normalization is local (like event-ledger.js) so the
+// offline miner package pulls in no engine module.
+
+const defaultDbFileName = "prediction-ledger.sqlite3";
+let defaultPredictionLedger = null;
+
+export function resolvePredictionLedgerDbPath(env = process.env) {
+  const explicitPath = typeof env.GITTENSORY_MINER_PREDICTION_LEDGER_DB === "string"
+    ? env.GITTENSORY_MINER_PREDICTION_LEDGER_DB.trim()
+    : "";
+  if (explicitPath) return explicitPath;
+
+  const explicitConfigDir = typeof env.GITTENSORY_MINER_CONFIG_DIR === "string"
+    ? env.GITTENSORY_MINER_CONFIG_DIR.trim()
+    : "";
+  if (explicitConfigDir) return join(explicitConfigDir, defaultDbFileName);
+
+  const configHome = typeof env.XDG_CONFIG_HOME === "string" && env.XDG_CONFIG_HOME.trim()
+    ? env.XDG_CONFIG_HOME.trim()
+    : join(homedir(), ".config");
+  return join(configHome, "gittensory-miner", defaultDbFileName);
+}
+
+function normalizeDbPath(dbPath) {
+  const path = (dbPath ?? resolvePredictionLedgerDbPath()).trim();
+  if (!path) throw new Error("invalid_prediction_ledger_db_path");
+  return path;
+}
+
+function normalizeRepoFullName(repoFullName) {
+  if (typeof repoFullName !== "string") throw new Error("invalid_repo_full_name");
+  const [owner, repo, extra] = repoFullName.trim().split("/");
+  if (!owner || !repo || extra !== undefined) throw new Error("invalid_repo_full_name");
+  return `${owner}/${repo}`;
+}
+
+function normalizeOptionalRepoFullName(repoFullName) {
+  if (repoFullName === undefined || repoFullName === null) return undefined;
+  return normalizeRepoFullName(repoFullName);
+}
+
+function requiredNonEmptyString(value, error) {
+  if (typeof value !== "string" || !value.trim()) throw new Error(error);
+  return value.trim();
+}
+
+function optionalString(value) {
+  if (value === undefined || value === null) return null;
+  if (typeof value !== "string") throw new Error("invalid_head_sha");
+  const trimmed = value.trim();
+  return trimmed || null;
+}
+
+// Codes are stored as a JSON array of the non-empty trimmed strings, in order — a stable, small projection of a
+// verdict's blockers/warnings that drops all free-text detail.
+function normalizeCodes(codes, error) {
+  if (codes === undefined || codes === null) return [];
+  if (!Array.isArray(codes)) throw new Error(error);
+  return codes.map((code) => {
+    if (typeof code !== "string" || !code.trim()) throw new Error(error);
+    return code.trim();
+  });
+}
+
+function normalizeReadinessScore(value) {
+  if (value === undefined || value === null) return null;
+  if (typeof value !== "number" || !Number.isFinite(value)) throw new Error("invalid_readiness_score");
+  return value;
+}
+
+/** Validate + normalize an append input, throwing on any invalid field (mirrors normalizeGovernorLedgerEvent). */
+function normalizePredictionInput(input) {
+  if (!input || typeof input !== "object" || Array.isArray(input)) throw new Error("invalid_prediction_input");
+  if (!Number.isInteger(input.targetId) || input.targetId <= 0) throw new Error("invalid_target_id");
+  return {
+    repoFullName: normalizeRepoFullName(input.repoFullName),
+    targetId: input.targetId,
+    headSha: optionalString(input.headSha),
+    conclusion: requiredNonEmptyString(input.conclusion, "invalid_conclusion"),
+    pack: requiredNonEmptyString(input.pack, "invalid_pack"),
+    readinessScore: normalizeReadinessScore(input.readinessScore),
+    blockerCodes: normalizeCodes(input.blockerCodes, "invalid_blocker_codes"),
+    warningCodes: normalizeCodes(input.warningCodes, "invalid_warning_codes"),
+    engineVersion: requiredNonEmptyString(input.engineVersion, "invalid_engine_version"),
+  };
+}
+
+function rowToEntry(row) {
+  let blockerCodes;
+  let warningCodes;
+  try {
+    blockerCodes = JSON.parse(row.blocker_codes_json);
+    warningCodes = JSON.parse(row.warning_codes_json);
+    if (!Array.isArray(blockerCodes) || !Array.isArray(warningCodes)) throw new Error("corrupted_prediction_row");
+  } catch {
+    throw new Error("corrupted_prediction_row");
+  }
+  return {
+    id: row.id,
+    ts: row.ts,
+    repoFullName: row.repo_full_name,
+    targetId: row.target_id,
+    headSha: row.head_sha,
+    conclusion: row.conclusion,
+    pack: row.pack,
+    readinessScore: row.readiness_score,
+    blockerCodes,
+    warningCodes,
+    engineVersion: row.engine_version,
+  };
+}
+
+/**
+ * Opens the append-only prediction ledger, creating the table on first use. Rows are returned in ascending `id`
+ * order (insertion order). (#4263)
+ */
+export function initPredictionLedger(dbPath = resolvePredictionLedgerDbPath()) {
+  const resolvedPath = normalizeDbPath(dbPath);
+  mkdirSync(dirname(resolvedPath), { recursive: true, mode: 0o700 });
+  const db = new DatabaseSync(resolvedPath);
+  chmodSync(resolvedPath, 0o600);
+  db.exec("PRAGMA busy_timeout = 5000");
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS predictions (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      ts TEXT NOT NULL,
+      repo_full_name TEXT NOT NULL,
+      target_id INTEGER NOT NULL,
+      head_sha TEXT,
+      conclusion TEXT NOT NULL,
+      pack TEXT NOT NULL,
+      readiness_score REAL,
+      blocker_codes_json TEXT NOT NULL,
+      warning_codes_json TEXT NOT NULL,
+      engine_version TEXT NOT NULL
+    )
+  `);
+  db.exec("CREATE INDEX IF NOT EXISTS idx_predictions_repo ON predictions (repo_full_name, id)");
+  // Opt-in retention (#4834): prune aged/excess rows when an operator has enabled it; a no-op by default.
+  pruneLedgerByRetention(db, PREDICTION_LEDGER_RETENTION_SPEC, resolveLedgerRetentionPolicy(), Date.now());
+
+  const appendStatement = db.prepare(`
+    INSERT INTO predictions
+      (ts, repo_full_name, target_id, head_sha, conclusion, pack, readiness_score, blocker_codes_json, warning_codes_json, engine_version)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `);
+  const getByIdStatement = db.prepare("SELECT * FROM predictions WHERE id = ?");
+  const readAllStatement = db.prepare("SELECT * FROM predictions ORDER BY id ASC");
+  const readByRepoStatement = db.prepare("SELECT * FROM predictions WHERE repo_full_name = ? ORDER BY id ASC");
+
+  return {
+    dbPath: resolvedPath,
+    appendPrediction(input) {
+      const n = normalizePredictionInput(input);
+      const ts = new Date().toISOString();
+      const result = appendStatement.run(
+        ts,
+        n.repoFullName,
+        n.targetId,
+        n.headSha,
+        n.conclusion,
+        n.pack,
+        n.readinessScore,
+        JSON.stringify(n.blockerCodes),
+        JSON.stringify(n.warningCodes),
+        n.engineVersion,
+      );
+      return rowToEntry(getByIdStatement.get(Number(result.lastInsertRowid)));
+    },
+    readPredictions(filter = {}) {
+      const repoFullName = normalizeOptionalRepoFullName(filter.repoFullName);
+      const rows = repoFullName === undefined ? readAllStatement.all() : readByRepoStatement.all(repoFullName);
+      return rows.map(rowToEntry);
+    },
+    // Explicit, operator-invoked right-to-be-forgotten purge (#5564) — never runs automatically. See the
+    // IMMUTABILITY INVARIANT note above: this is a deliberate, separate exception, not a normal ledger write.
+    purgeByRepo(repoFullName) {
+      return purgeStoreByRepo(db, PREDICTION_LEDGER_PURGE_SPEC, normalizeRepoFullName(repoFullName));
+    },
+    close() {
+      db.close();
+    },
+  };
+}
+
+function getDefaultPredictionLedger() {
+  defaultPredictionLedger ??= initPredictionLedger();
+  return defaultPredictionLedger;
+}
+
+export function appendPrediction(input) {
+  return getDefaultPredictionLedger().appendPrediction(input);
+}
+
+export function readPredictions(filter) {
+  return getDefaultPredictionLedger().readPredictions(filter);
+}
+
+export function closeDefaultPredictionLedger() {
+  if (!defaultPredictionLedger) return;
+  defaultPredictionLedger.close();
+  defaultPredictionLedger = null;
+}

package/lib/pretooluse-hook.d.ts

@@ -0,0 +1,31 @@
+import type { DenyRule } from "./deny-hooks.js";
+import type { AppendGovernorEventInput, GovernorLedgerEntry } from "./governor-ledger.js";
+
+export type BuildHouseRulesPreToolUseHookConfig = {
+  rules?: readonly DenyRule[];
+  repoFullName?: string;
+};
+
+export type BuildHouseRulesPreToolUseHookOptions = {
+  append?: (event: AppendGovernorEventInput) => GovernorLedgerEntry;
+};
+
+/** Minimal shape this module reads from the real Agent SDK `PreToolUseHookInput`. */
+export type PreToolUseHookLikeInput = {
+  tool_name?: string;
+  tool_input?: Record<string, unknown>;
+  hook_event_name?: string;
+};
+
+export type PreToolUseHookJSONOutput = {
+  hookSpecificOutput?: {
+    hookEventName: "PreToolUse";
+    permissionDecision: "deny";
+    permissionDecisionReason: string;
+  };
+};
+
+export function buildHouseRulesPreToolUseHook(
+  config?: BuildHouseRulesPreToolUseHookConfig,
+  options?: BuildHouseRulesPreToolUseHookOptions,
+): (input: PreToolUseHookLikeInput, toolUseId?: string, context?: unknown) => Promise<PreToolUseHookJSONOutput | Record<string, never>>;