@loopover/miner 0.1.0

package/lib/forge-config.d.ts

@@ -0,0 +1,17 @@
+/** Per-tenant forge configuration (#4784). Every field is a string knob defaulting to the github.com value in
+ * `DEFAULT_FORGE_CONFIG`; a tenant overrides only what differs for their forge. */
+export type ForgeConfig = {
+  apiBaseUrl: string;
+  apiVersion: string;
+  apiVersionHeader: string;
+  acceptHeader: string;
+  userAgent: string;
+  repoPathPrefix: string;
+  searchEndpoint: string;
+  searchQualifiers: string;
+  tokenEnvVar: string;
+};
+
+export const DEFAULT_FORGE_CONFIG: Readonly<ForgeConfig>;
+
+export function resolveForgeConfig(overrides?: Partial<ForgeConfig>): ForgeConfig;

package/lib/forge-config.js

@@ -0,0 +1,37 @@
+/** Per-tenant forge configuration (#4784): the GitHub-specific protocol details that discovery used to hardcode,
+ * gathered behind one resolver so a non-github.com tenant (GitHub Enterprise, or another GitHub-compatible forge)
+ * can override them. gittensory's own github.com conventions survive only as `DEFAULT_FORGE_CONFIG` — calling
+ * `resolveForgeConfig()` with no overrides is byte-identical to the pre-#4784 hardcoded fan-out behavior, which is
+ * what keeps the existing gittensory discovery path unchanged. Executes the #4780 repo-agnostic-capability-audit
+ * checklist (forge abstraction, configurable credential env var, configurable user-agent). */
+
+/** The github.com defaults every forge field falls back to. Frozen so a caller can't mutate the shared baseline. */
+export const DEFAULT_FORGE_CONFIG = Object.freeze({
+  apiBaseUrl: "https://api.github.com",
+  apiVersion: "2022-11-28",
+  apiVersionHeader: "x-github-api-version",
+  acceptHeader: "application/vnd.github+json",
+  userAgent: "loopover-miner",
+  repoPathPrefix: "/repos",
+  searchEndpoint: "/search/issues",
+  searchQualifiers: "state:open type:issue",
+  tokenEnvVar: "GITHUB_TOKEN",
+});
+
+function trimmedStringOr(value, fallback) {
+  return typeof value === "string" && value.trim() ? value.trim() : fallback;
+}
+
+/**
+ * Resolve a full forge config from partial per-tenant overrides. Every field is an independent string knob that
+ * falls back to its github.com default when the override is missing, non-string, or blank — so a partial override
+ * (say, only `apiBaseUrl` for a GitHub Enterprise host) still yields a complete, usable config.
+ */
+export function resolveForgeConfig(overrides = {}) {
+  const source = overrides && typeof overrides === "object" ? overrides : {};
+  const resolved = {};
+  for (const [key, fallback] of Object.entries(DEFAULT_FORGE_CONFIG)) {
+    resolved[key] = trimmedStringOr(source[key], fallback);
+  }
+  return resolved;
+}

package/lib/governor-action-mode.d.ts

@@ -0,0 +1,26 @@
+import type { MinerActionMode, MinerKillSwitchScope } from "@loopover/engine";
+import type { AppendGovernorEventInput, GovernorLedgerEntry } from "./governor-ledger.js";
+
+export type ResolveMinerActionModeGateInput = {
+  killSwitchScope: MinerKillSwitchScope;
+  repoLiveModeOptIn?: unknown;
+  env?: Record<string, string | undefined>;
+};
+
+export type ResolveMinerActionModeGateResult = {
+  mode: MinerActionMode;
+  executes: boolean;
+};
+
+export function resolveMinerActionModeGate(input: ResolveMinerActionModeGateInput): ResolveMinerActionModeGateResult;
+
+export type RecordMinerDryRunShadowInput = {
+  repoFullName?: string;
+  actionClass: string;
+  wouldBeAction: Record<string, unknown>;
+};
+
+export function recordMinerDryRunShadow(
+  input: RecordMinerDryRunShadowInput,
+  options?: { append?: (event: AppendGovernorEventInput) => GovernorLedgerEntry },
+): GovernorLedgerEntry;

package/lib/governor-action-mode.js

@@ -0,0 +1,47 @@
+// Governor dry-run-by-default gate (#2342). Resolves the miner's overall action mode (paused > dry_run > live,
+// "safest wins") and records dry-run SHADOW actions to the append-only governor ledger. A freshly-configured
+// miner defaults to dry_run -- live execution requires explicit, hard-to-fat-finger operator and repo opt-ins.
+
+import {
+  buildMinerDryRunGovernorLedgerEvent,
+  isGlobalMinerLiveModeOptIn,
+  minerActionModeExecutes,
+  resolveMinerActionMode,
+} from "@loopover/engine";
+import { appendGovernorEvent } from "./governor-ledger.js";
+
+/**
+ * Resolve the miner's overall action mode from the kill-switch scope (see `checkMinerKillSwitch` in
+ * `./governor-kill-switch.js`), the repo's own `.gittensory-miner.yml` opt-in, and the operator's global env
+ * opt-in. Both sides must opt in before real writes execute; repo config alone only preserves dry-run.
+ *
+ * @param {object} input
+ * @param {import("@loopover/engine").MinerKillSwitchScope} input.killSwitchScope
+ * @param {unknown} [input.repoLiveModeOptIn] `MinerGoalSpec.execution.liveModeOptIn` from the target repo
+ * @param {Record<string, string | undefined>} [input.env]
+ * @returns {{ mode: import("@loopover/engine").MinerActionMode, executes: boolean }}
+ */
+export function resolveMinerActionModeGate(input) {
+  const env = input.env ?? process.env;
+  const mode = resolveMinerActionMode({
+    killSwitchScope: input.killSwitchScope,
+    repoLiveModeOptIn: input.repoLiveModeOptIn,
+    globalLiveModeOptIn: isGlobalMinerLiveModeOptIn(env),
+  });
+  return { mode, executes: minerActionModeExecutes(mode) };
+}
+
+/**
+ * Record a dry-run shadow action (the WOULD-BE `LocalWriteActionSpec`) to the governor ledger, without ever
+ * invoking the actual command.
+ *
+ * @param {object} input
+ * @param {string} [input.repoFullName]
+ * @param {string} input.actionClass
+ * @param {Record<string, unknown>} input.wouldBeAction
+ * @param {{ append?: typeof appendGovernorEvent }} [options]
+ */
+export function recordMinerDryRunShadow(input, options = {}) {
+  const append = options.append ?? appendGovernorEvent;
+  return append(buildMinerDryRunGovernorLedgerEvent(input));
+}

package/lib/governor-chokepoint-persisted.d.ts

@@ -0,0 +1,18 @@
+import type { GovernorChokepointInput } from "@loopover/engine";
+import type { AppendGovernorEventInput, GovernorLedgerEntry } from "./governor-ledger.js";
+import type { EvaluateGovernorChokepointGateResult } from "./governor-chokepoint.js";
+import type { GovernorState } from "./governor-state.js";
+
+// rateLimitBuckets/rateLimitBackoffAttempts/capUsage are required on GovernorChokepointInput itself, but this
+// wrapper auto-supplies them from persisted state when the caller omits them -- loosen just those three to
+// optional so a caller that WANTS the persisted defaults doesn't have to fake a value just to satisfy the type.
+export type GovernorChokepointInputPersisted = Omit<GovernorChokepointInput, "rateLimitBuckets" | "rateLimitBackoffAttempts" | "capUsage"> &
+  Partial<Pick<GovernorChokepointInput, "rateLimitBuckets" | "rateLimitBackoffAttempts" | "capUsage">>;
+
+export function evaluateGovernorChokepointGatePersisted(
+  input: GovernorChokepointInputPersisted,
+  options?: {
+    governorState?: GovernorState;
+    append?: (event: AppendGovernorEventInput) => GovernorLedgerEntry;
+  },
+): EvaluateGovernorChokepointGateResult;

package/lib/governor-chokepoint-persisted.js

@@ -0,0 +1,46 @@
+import { evaluateGovernorChokepointGate } from "./governor-chokepoint.js";
+import { openGovernorState } from "./governor-state.js";
+
+// The real cross-attempt integration point for #5134: composes governor-chokepoint.js's existing, UNMODIFIED
+// evaluateGovernorChokepointGate (still exactly as pure-per-call as before -- every existing caller/test of
+// it is untouched) with governor-state.js's persistence, so attempt N+1's decision actually sees attempt N's
+// rate-limit/backoff outcome. Kept as a separate composing function rather than changing
+// evaluateGovernorChokepointGate itself: this issue is flagged as the safety-critical core of its gap-fill
+// batch, and a caller-controlled wrapper is a smaller, more isolated surface to review than a behavior change
+// to an already-relied-upon function.
+//
+// capUsage is LOADED here (so a caller that doesn't track its own running totals still gets real prior state
+// instead of silently starting from zero every call) but deliberately NOT saved here: budget-cap.ts's
+// GovernorCapUsage has no mutator (unlike write-rate-limit.ts's buckets/backoff, nothing computes "the next
+// capUsage" from a verdict -- the caller is the only one who knows how much THIS attempt actually spent,
+// which isn't known until after the attempt runs, not at the gate-check moment). Saving the next capUsage is
+// the caller's job via `saveCapUsage` once the attempt's real spend/turns/elapsed are known.
+
+/**
+ * @param {import("./governor-chokepoint-persisted.js").GovernorChokepointInputPersisted} input
+ * @param {{
+ *   governorState?: import("./governor-state.js").GovernorState,
+ *   append?: (event: unknown) => unknown,
+ * }} [options]
+ * @returns {import("./governor-chokepoint.js").EvaluateGovernorChokepointGateResult}
+ */
+export function evaluateGovernorChokepointGatePersisted(input, options = {}) {
+  const ownsGovernorState = options.governorState === undefined;
+  const governorState = options.governorState ?? openGovernorState();
+  try {
+    const persistedRateLimit = governorState.loadRateLimitState();
+    const persistedCapUsage = governorState.loadCapUsage();
+    const resolvedInput = {
+      ...input,
+      rateLimitBuckets: input.rateLimitBuckets ?? persistedRateLimit.buckets,
+      rateLimitBackoffAttempts: input.rateLimitBackoffAttempts ?? persistedRateLimit.backoffAttempts,
+      capUsage: input.capUsage ?? persistedCapUsage,
+    };
+    const gateOptions = options.append === undefined ? {} : { append: options.append };
+    const result = evaluateGovernorChokepointGate(resolvedInput, gateOptions);
+    governorState.saveRateLimitState({ buckets: result.rateLimitBuckets, backoffAttempts: result.rateLimitBackoffAttempts });
+    return result;
+  } finally {
+    if (ownsGovernorState) governorState.close();
+  }
+}

package/lib/governor-chokepoint.d.ts

@@ -0,0 +1,14 @@
+import type { GovernorChokepointInput, GovernorDecision, WriteRateLimitBackoffStore, WriteRateLimitBucketStore } from "@loopover/engine";
+import type { AppendGovernorEventInput, GovernorLedgerEntry } from "./governor-ledger.js";
+
+export type EvaluateGovernorChokepointGateResult = {
+  decision: GovernorDecision;
+  recorded: GovernorLedgerEntry;
+  rateLimitBuckets: WriteRateLimitBucketStore;
+  rateLimitBackoffAttempts: WriteRateLimitBackoffStore;
+};
+
+export function evaluateGovernorChokepointGate(
+  input: GovernorChokepointInput,
+  options?: { append?: (event: AppendGovernorEventInput) => GovernorLedgerEntry },
+): EvaluateGovernorChokepointGateResult;

package/lib/governor-chokepoint.js

@@ -0,0 +1,52 @@
+// The Governor chokepoint gate (#2340). Wraps the pure `evaluateGovernorChokepoint` engine decision with the
+// two stateful side effects every caller needs: persisting the resulting ledger event, and (only when the
+// rate-limit stage actually ran) advancing/backing-off the rate-limit bucket state. This is the ONLY sanctioned
+// call site a real write action (open_pr, file_issue, apply_labels, post_eligibility_comment, create_branch,
+// delete_branch, generate_tests) should be gated through.
+
+import {
+  clearWriteRateLimitBackoff,
+  evaluateGovernorChokepoint,
+  recordWriteRateLimitAllowed,
+  recordWriteRateLimitDenied,
+} from "@loopover/engine";
+import { appendGovernorEvent } from "./governor-ledger.js";
+
+/**
+ * Evaluate a write action against the full Governor precedence ladder, persist the resulting ledger event, and
+ * advance rate-limit bucket/backoff state when the rate-limit stage actually ran (kill-switch and dry-run
+ * short-circuit before rate-limit is evaluated, so bucket state is untouched in those cases).
+ *
+ * @param {import("@loopover/engine").GovernorChokepointInput} input
+ * @param {{ append?: typeof appendGovernorEvent }} [options]
+ * @returns {{
+ *   decision: import("@loopover/engine").GovernorDecision,
+ *   recorded: import("./governor-ledger.js").GovernorLedgerEntry,
+ *   rateLimitBuckets: import("@loopover/engine").WriteRateLimitBucketStore,
+ *   rateLimitBackoffAttempts: import("@loopover/engine").WriteRateLimitBackoffStore,
+ * }}
+ */
+export function evaluateGovernorChokepointGate(input, options = {}) {
+  const append = options.append ?? appendGovernorEvent;
+  const decision = evaluateGovernorChokepoint(input);
+  const recorded = append(decision.ledgerEvent);
+
+  let rateLimitBuckets = input.rateLimitBuckets;
+  let rateLimitBackoffAttempts = input.rateLimitBackoffAttempts;
+  if (decision.detail.rateLimit) {
+    if (decision.detail.rateLimit.allowed) {
+      rateLimitBuckets = recordWriteRateLimitAllowed(
+        input.rateLimitBuckets,
+        input.actionClass,
+        input.repoFullName,
+        input.nowMs,
+        input.rateLimitPolicies,
+      );
+      rateLimitBackoffAttempts = clearWriteRateLimitBackoff(input.rateLimitBackoffAttempts, input.actionClass, input.repoFullName);
+    } else {
+      rateLimitBackoffAttempts = recordWriteRateLimitDenied(input.rateLimitBackoffAttempts, input.actionClass, input.repoFullName);
+    }
+  }
+
+  return { decision, recorded, rateLimitBuckets, rateLimitBackoffAttempts };
+}

package/lib/governor-kill-switch.d.ts

@@ -0,0 +1,26 @@
+import type { MinerKillSwitchScope } from "@loopover/engine";
+import type { AppendGovernorEventInput, GovernorLedgerEntry } from "./governor-ledger.js";
+
+export type CheckMinerKillSwitchInput = {
+  repoPaused?: boolean;
+  env?: Record<string, string | undefined>;
+};
+
+export type CheckMinerKillSwitchResult = {
+  scope: MinerKillSwitchScope;
+  active: boolean;
+};
+
+export function checkMinerKillSwitch(input?: CheckMinerKillSwitchInput): CheckMinerKillSwitchResult;
+
+export type RecordMinerKillSwitchTransitionInput = {
+  repoFullName?: string;
+  actionClass: string;
+  previousScope: MinerKillSwitchScope;
+  scope: MinerKillSwitchScope;
+};
+
+export function recordMinerKillSwitchTransition(
+  input: RecordMinerKillSwitchTransitionInput,
+  options?: { append?: (event: AppendGovernorEventInput) => GovernorLedgerEntry },
+): GovernorLedgerEntry | null;

package/lib/governor-kill-switch.js

@@ -0,0 +1,47 @@
+// Governor kill-switch gate (#2341). Resolves whether miner write activity is currently halted (globally, via
+// env, or for one repo, via its .gittensory-miner.yml MinerGoalSpec) and records STATE TRANSITIONS to the
+// append-only governor ledger. Every-check allow/deny recording for a real write action is the fail-closed
+// Governor chokepoint's job (#2340), which consults this module first in its "safest wins" precedence.
+
+import {
+  buildMinerKillSwitchTransitionGovernorLedgerEvent,
+  isGlobalMinerKillSwitch,
+  isMinerKillSwitchActive,
+  resolveMinerKillSwitch,
+} from "@loopover/engine";
+import { appendGovernorEvent } from "./governor-ledger.js";
+
+/**
+ * Resolve the current kill-switch scope for a repo from process env plus a per-repo paused flag (typically
+ * `MinerGoalSpec.killSwitch.paused` from the repo's parsed `.gittensory-miner.yml`).
+ *
+ * @param {object} [input]
+ * @param {boolean} [input.repoPaused]
+ * @param {Record<string, string | undefined>} [input.env]
+ * @returns {{ scope: import("@loopover/engine").MinerKillSwitchScope, active: boolean }}
+ */
+export function checkMinerKillSwitch(input = {}) {
+  const env = input.env ?? process.env;
+  const global = isGlobalMinerKillSwitch(env);
+  const scope = resolveMinerKillSwitch({ global, repoPaused: input.repoPaused });
+  return { scope, active: isMinerKillSwitchActive(scope) };
+}
+
+/**
+ * Record a kill-switch state transition to the governor ledger. No-op (returns null, appends nothing) when the
+ * scope has not actually changed since the previous check — callers own tracking the previous scope (in-memory
+ * or persisted); this module holds no state of its own.
+ *
+ * @param {object} input
+ * @param {string} [input.repoFullName]
+ * @param {string} input.actionClass
+ * @param {import("@loopover/engine").MinerKillSwitchScope} input.previousScope
+ * @param {import("@loopover/engine").MinerKillSwitchScope} input.scope
+ * @param {{ append?: typeof appendGovernorEvent }} [options]
+ */
+export function recordMinerKillSwitchTransition(input, options = {}) {
+  const event = buildMinerKillSwitchTransitionGovernorLedgerEvent(input);
+  if (!event) return null;
+  const append = options.append ?? appendGovernorEvent;
+  return append(event);
+}

package/lib/governor-ledger-cli.d.ts

@@ -0,0 +1,32 @@
+import type { GovernorLedger, GovernorLedgerEntry } from "./governor-ledger.js";
+import type { GovernorPauseCliOptions } from "./governor-pause-cli.js";
+
+export type GovernorLedgerEventType = "allowed" | "denied" | "throttled" | "kill_switch";
+
+export type ParsedGovernorListArgs =
+  | {
+      json: boolean;
+      repoFullName: string | null;
+      type: GovernorLedgerEventType | null;
+    }
+  | { error: string };
+
+export function parseGovernorListArgs(args: string[]): ParsedGovernorListArgs;
+
+export function filterGovernorEvents(
+  events: GovernorLedgerEntry[],
+  options?: { type?: string | null },
+): GovernorLedgerEntry[];
+
+export function renderGovernorTable(events: GovernorLedgerEntry[]): string;
+
+export function runGovernorList(
+  args: string[],
+  options?: { initGovernorLedger?: () => GovernorLedger },
+): Promise<number>;
+
+export function runGovernorCli(
+  subcommand: string | undefined,
+  args: string[],
+  options?: { initGovernorLedger?: () => GovernorLedger } & GovernorPauseCliOptions,
+): Promise<number>;

package/lib/governor-ledger-cli.js

@@ -0,0 +1,155 @@
+import { runGovernorPause, runGovernorResume, runGovernorStatus } from "./governor-pause-cli.js";
+
+/** Must match `GOVERNOR_LEDGER_EVENT_TYPES` in `@loopover/engine`. */
+import { argsWantJson, describeCliError, reportCliFailure } from "./cli-error.js";
+
+const GOVERNOR_LEDGER_EVENT_TYPES = Object.freeze([
+  "allowed",
+  "denied",
+  "throttled",
+  "kill_switch",
+]);
+
+const GOVERNOR_LIST_USAGE =
+  "Usage: gittensory-miner governor list [--repo <owner/repo>] [--type allowed|denied|throttled|kill_switch] [--json]";
+
+const GOVERNOR_SUBCOMMAND_USAGE = [
+  GOVERNOR_LIST_USAGE,
+  "       gittensory-miner governor pause [--reason <text>] [--json]",
+  "       gittensory-miner governor resume [--json]",
+  "       gittensory-miner governor status [--json]",
+].join("\n");
+
+function parseRepoArg(value, usage) {
+  if (!value) return { error: usage };
+  const trimmed = value.trim();
+  const [owner, repo, extra] = trimmed.split("/");
+  if (!owner || !repo || extra !== undefined) {
+    return { error: "Repository must be in owner/repo form." };
+  }
+  return { repoFullName: `${owner}/${repo}` };
+}
+
+export function parseGovernorListArgs(args) {
+  const options = { json: false, repoFullName: null, type: null };
+  const positional = [];
+
+  for (let index = 0; index < args.length; index += 1) {
+    const token = args[index];
+    if (token === "--json") {
+      options.json = true;
+      continue;
+    }
+    if (token === "--repo") {
+      const repoArg = args[index + 1];
+      if (!repoArg || repoArg.startsWith("-")) return { error: GOVERNOR_LIST_USAGE };
+      const repo = parseRepoArg(repoArg, GOVERNOR_LIST_USAGE);
+      if ("error" in repo) return repo;
+      options.repoFullName = repo.repoFullName;
+      index += 1;
+      continue;
+    }
+    if (token === "--type") {
+      const type = args[index + 1];
+      if (!type || type.startsWith("-")) return { error: GOVERNOR_LIST_USAGE };
+      const trimmed = type.trim();
+      if (!GOVERNOR_LEDGER_EVENT_TYPES.includes(trimmed)) {
+        return {
+          error: `Invalid type: ${trimmed}. Expected one of ${GOVERNOR_LEDGER_EVENT_TYPES.join(", ")}.`,
+        };
+      }
+      options.type = trimmed;
+      index += 1;
+      continue;
+    }
+    if (token.startsWith("-")) return { error: `Unknown option: ${token}` };
+    positional.push(token);
+  }
+
+  if (positional.length > 0) return { error: GOVERNOR_LIST_USAGE };
+  return options;
+}
+
+export function filterGovernorEvents(events, options = {}) {
+  if (!Array.isArray(events)) return [];
+  const type = typeof options.type === "string" && options.type.trim() ? options.type.trim() : null;
+  if (!type) return events;
+  return events.filter((entry) => entry.eventType === type);
+}
+
+function display(value) {
+  if (value === null || value === undefined) return "-";
+  return String(value);
+}
+
+export function renderGovernorTable(events) {
+  if (!Array.isArray(events) || events.length === 0) return "no governor ledger entries";
+  const header = [
+    "id".padStart(4),
+    "type".padEnd(12),
+    "repo".padEnd(24),
+    "action".padEnd(10),
+    "decision".padEnd(10),
+    "ts".padEnd(24),
+  ].join(" ");
+  const lines = events.map((entry) =>
+    [
+      String(entry.id).padStart(4),
+      entry.eventType.padEnd(12),
+      display(entry.repoFullName).padEnd(24),
+      entry.actionClass.padEnd(10),
+      entry.decision.padEnd(10),
+      display(entry.ts).padEnd(24),
+    ].join(" "),
+  );
+  return [header, ...lines].join("\n");
+}
+
+async function withGovernorLedger(options, run) {
+  const ownsLedger = options.initGovernorLedger === undefined;
+  const initGovernorLedger =
+    options.initGovernorLedger ?? (await import("./governor-ledger.js")).initGovernorLedger;
+  const governorLedger = initGovernorLedger();
+  try {
+    return run(governorLedger);
+  } finally {
+    if (ownsLedger) governorLedger.close();
+  }
+}
+
+export async function runGovernorList(args, options = {}) {
+  const parsed = parseGovernorListArgs(args);
+  if ("error" in parsed) {
+    return reportCliFailure(argsWantJson(args), parsed.error);
+  }
+
+  try {
+    return await withGovernorLedger(options, (governorLedger) => {
+      const events = filterGovernorEvents(
+        governorLedger.readGovernorEvents({
+          repoFullName: parsed.repoFullName,
+        }),
+        { type: parsed.type },
+      );
+      if (parsed.json) {
+        console.log(JSON.stringify({ events }, null, 2));
+      } else {
+        console.log(renderGovernorTable(events));
+      }
+      return 0;
+    });
+  } catch (error) {
+    return reportCliFailure(parsed.json, describeCliError(error));
+  }
+}
+
+export async function runGovernorCli(subcommand, args, options = {}) {
+  if (subcommand === "list") return runGovernorList(args, options);
+  if (subcommand === "pause") return runGovernorPause(args, options);
+  if (subcommand === "resume") return runGovernorResume(args, options);
+  if (subcommand === "status") return runGovernorStatus(args, options);
+  return reportCliFailure(
+    argsWantJson(args),
+    `Unknown governor subcommand: ${subcommand ?? ""}.\n${GOVERNOR_SUBCOMMAND_USAGE}`,
+  );
+}

package/lib/governor-ledger.d.ts

@@ -0,0 +1,46 @@
+export type GovernorLedgerEntry = {
+  id: number;
+  ts: string;
+  eventType: string;
+  repoFullName: string | null;
+  actionClass: string;
+  decision: string;
+  reason: string;
+  payload: Record<string, unknown>;
+};
+
+export type AppendGovernorEventInput = {
+  eventType: string;
+  repoFullName?: string | null;
+  actionClass: string;
+  decision: string;
+  reason: string;
+  payload?: Record<string, unknown>;
+};
+
+export type ReadGovernorEventsFilter = {
+  repoFullName?: string | null;
+};
+
+/** The public decision-log projection (#5159): every {@link GovernorLedgerEntry} field EXCEPT `payload`. */
+export type GovernorDecisionEntry = Omit<GovernorLedgerEntry, "payload">;
+
+export type GovernorLedger = {
+  dbPath: string;
+  appendGovernorEvent(event: AppendGovernorEventInput): GovernorLedgerEntry;
+  readGovernorEvents(filter?: ReadGovernorEventsFilter): GovernorLedgerEntry[];
+  /** Read-only decision-log projection; excludes `payload` by construction (explicit named-column SELECT). */
+  readGovernorDecisions(filter?: ReadGovernorEventsFilter): GovernorDecisionEntry[];
+  purgeByRepo(repoFullName: string): number;
+  close(): void;
+};
+
+export function resolveGovernorLedgerDbPath(env?: Record<string, string | undefined>): string;
+
+export function initGovernorLedger(dbPath?: string): GovernorLedger;
+
+export function appendGovernorEvent(event: AppendGovernorEventInput): GovernorLedgerEntry;
+
+export function readGovernorEvents(filter?: ReadGovernorEventsFilter): GovernorLedgerEntry[];
+
+export function closeDefaultGovernorLedger(): void;