@loopover/miner 0.1.0

package/lib/calibration-cli.js

@@ -0,0 +1,92 @@
+// `gittensory-miner calibration [--json]` (#4849): a read-only report joining the miner's own predicted gate
+// verdicts (prediction-ledger) with the realized PR outcomes it later observed (event-ledger `pr_outcome`
+// events), via the pure buildCalibrationReport join. Opens both local stores, maps their rows to the
+// calibration record shapes, renders, and closes. Never modifies the live scoring/calibration logic.
+import { buildCalibrationReport } from "./calibration.js";
+import { initEventLedger, resolveEventLedgerDbPath } from "./event-ledger.js";
+import { MINER_PR_OUTCOME_EVENT } from "./pr-outcome.js";
+import { initPredictionLedger, resolvePredictionLedgerDbPath } from "./prediction-ledger.js";
+import { reportCliFailure, describeCliError } from "./cli-error.js";
+
+const CALIBRATION_USAGE = "Usage: gittensory-miner calibration [--json]";
+
+/** Map prediction-ledger rows to predicted-verdict records: the target id becomes a string key and the recorded
+ *  prediction verdict is the `conclusion`. */
+function toPredictionRecords(rows) {
+  return rows.map((row) => ({
+    project: row.repoFullName,
+    targetId: String(row.targetId),
+    predictedDecision: row.conclusion,
+    recordedAt: row.ts,
+  }));
+}
+
+/** Reduce the append-only `pr_outcome` event stream to the LATEST observed outcome per (repo, PR), as
+ *  observed-outcome records. `recordedAt` comes from the event's own timestamp (always present), so an outcome is
+ *  never dropped for lacking a `closedAt`. Malformed payloads are skipped. */
+function toOutcomeRecords(events) {
+  const latest = new Map();
+  for (const event of events) {
+    if (event?.type !== MINER_PR_OUTCOME_EVENT) continue;
+    const payload = event.payload;
+    if (!payload || !Number.isInteger(payload.prNumber) || typeof payload.decision !== "string") continue;
+    latest.set(`${event.repoFullName}:${payload.prNumber}`, {
+      project: event.repoFullName,
+      targetId: String(payload.prNumber),
+      outcomeDecision: payload.decision,
+      recordedAt: event.createdAt,
+    });
+  }
+  return [...latest.values()];
+}
+
+function renderReportText(report) {
+  if (!report.hasSignal) {
+    console.log("calibration: no decided predictions yet (predictions need a realized merge/close outcome).");
+    return;
+  }
+  for (const row of report.rows) {
+    const merge = row.mergePrecision === null ? "n/a" : `${Math.round(row.mergePrecision * 100)}%`;
+    const close = row.closePrecision === null ? "n/a" : `${Math.round(row.closePrecision * 100)}%`;
+    console.log(
+      `${row.project}: ${row.decided} decided | ` +
+        `merge ${row.mergeConfirmed}/${row.wouldMerge} (${merge}) | ` +
+        `close ${row.closeConfirmed}/${row.wouldClose} (${close}) | hold ${row.hold}`,
+    );
+  }
+}
+
+/**
+ * Run `gittensory-miner calibration [--json]`. Reads the prediction ledger + PR-outcome events, joins them into a
+ * calibration report, and prints it (a JSON dump under `--json`, else a per-project text summary). Returns the
+ * process exit code: 0 on success, 1 on an unknown option.
+ * @param {string[]} [args]
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {number}
+ */
+export function runCalibrationCli(args = [], env = process.env) {
+  const json = args.includes("--json");
+  const unknown = args.find((token) => token.startsWith("-") && token !== "--json");
+  if (unknown) {
+    return reportCliFailure(json, `Unknown option: ${unknown}. ${CALIBRATION_USAGE}`, 1);
+  }
+
+  let predictionStore;
+  let eventLedger;
+  try {
+    predictionStore = initPredictionLedger(resolvePredictionLedgerDbPath(env));
+    eventLedger = initEventLedger(resolveEventLedgerDbPath(env));
+    const report = buildCalibrationReport(
+      toPredictionRecords(predictionStore.readPredictions()),
+      toOutcomeRecords(eventLedger.readEvents()),
+    );
+    if (json) console.log(JSON.stringify(report, null, 2));
+    else renderReportText(report);
+    return 0;
+  } catch (error) {
+    return reportCliFailure(json, describeCliError(error));
+  } finally {
+    predictionStore?.close();
+    eventLedger?.close();
+  }
+}

package/lib/calibration-run.d.ts

@@ -0,0 +1,161 @@
+import type {
+  HistoricalReplayCalibrationInput,
+  Phase7CalibrationConfig,
+  Phase7CalibrationLoopResult,
+  Phase7CalibrationManifest,
+  PrOutcomeCalibrationInput,
+  ReplayHarnessStatus,
+} from "@loopover/engine";
+
+import type { AppendEventInput, LedgerEntry } from "./event-ledger.js";
+import type {
+  ObjectiveAnchorResult,
+  ReplayPlanInput,
+  RevealedHistoryEntry,
+} from "./replay-objective-anchor.js";
+
+export const MINER_CALIBRATION_SNAPSHOT_EVENT: "calibration_snapshot";
+
+/** One completed replay-run task result: what the replay targeted, and the revealed post-T history to score it. */
+export interface ReplayTaskResult {
+  replayPlan?: ReplayPlanInput | null;
+  revealedHistory?: RevealedHistoryEntry[] | RevealedHistoryEntry | null;
+}
+
+export interface ScoreCompositeOptions {
+  computeObjectiveAnchor?: (
+    input: { replayPlan?: ReplayPlanInput | null; revealedHistory?: RevealedHistoryEntry[] | RevealedHistoryEntry | null },
+  ) => ObjectiveAnchorResult;
+}
+
+export interface HistoricalReplayCompositeScore {
+  compositeScore: number | null;
+  sampleSize: number;
+  scores: number[];
+}
+
+export function scoreHistoricalReplayComposite(
+  replayResults: readonly ReplayTaskResult[] | null | undefined,
+  options?: ScoreCompositeOptions,
+): HistoricalReplayCompositeScore;
+
+/** A completed replay run's descriptor: its per-task results plus the run's identity/freshness/harness health. */
+export interface ReplayRunDescriptor {
+  replayResults?: readonly ReplayTaskResult[] | null;
+  replayRunId?: string;
+  observedAt?: string;
+  harnessStatus?: ReplayHarnessStatus;
+}
+
+export interface BuiltHistoricalReplayInput {
+  historicalReplay: HistoricalReplayCalibrationInput | null;
+  compositeScore: number | null;
+  sampleSize: number;
+  scores: number[];
+}
+
+export function buildHistoricalReplayCalibrationInput(
+  replayRun: ReplayRunDescriptor | null | undefined,
+  options?: ScoreCompositeOptions,
+): BuiltHistoricalReplayInput;
+
+/** The persisted, public-safe projection of a Phase7CalibrationLoopResult. */
+export interface CalibrationSnapshotPayload {
+  enabled: boolean;
+  combinedAccuracy: number | null;
+  baselineAccuracy: number;
+  deltaFromBaseline: number | null;
+  autonomyIncreasePermitted: boolean;
+  replayHarnessHold: boolean;
+  replayHarnessStatus: string;
+  replayRunDue: boolean;
+  holdReasons: string[];
+  contributingSources: string[];
+  replayRunId: string | null;
+  observedAt: string | null;
+  replaySampleSize: number;
+}
+
+export interface SnapshotMeta {
+  replayRunId?: string | null;
+  observedAt?: string | null;
+  sampleSize?: number;
+}
+
+export function snapshotPayloadFromResult(
+  result: Phase7CalibrationLoopResult,
+  meta?: SnapshotMeta,
+): CalibrationSnapshotPayload;
+
+export function normalizeCalibrationSnapshotPayload(payload: unknown): CalibrationSnapshotPayload | null;
+
+export interface RecordCalibrationSnapshotOptions {
+  /** 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`. */
+  eventLedger?: { appendEvent(event: AppendEventInput): LedgerEntry };
+  repoFullName?: string;
+}
+
+export function recordCalibrationSnapshot(
+  input: unknown,
+  options?: RecordCalibrationSnapshotOptions,
+): LedgerEntry | null;
+
+export interface CalibrationSnapshotReader {
+  readEvents(filter?: { since?: number | null; repoFullName?: string | null }): unknown[];
+}
+
+export interface CalibrationSnapshotFilter {
+  since?: number | null;
+  repoFullName?: string | null;
+}
+
+export interface PersistedCalibrationSnapshot extends CalibrationSnapshotPayload {
+  repoFullName: string | null;
+  seq: number | null;
+  createdAt: string | null;
+}
+
+export function readCalibrationSnapshots(
+  eventLedger: CalibrationSnapshotReader,
+  filter?: CalibrationSnapshotFilter,
+): PersistedCalibrationSnapshot[];
+
+export function latestCalibrationSnapshot(
+  eventLedger: CalibrationSnapshotReader,
+  filter?: CalibrationSnapshotFilter,
+): PersistedCalibrationSnapshot | null;
+
+export interface RunCalibrationCycleInput {
+  config?: Phase7CalibrationConfig | Phase7CalibrationManifest | Record<string, unknown> | null;
+  prOutcome?: PrOutcomeCalibrationInput | null;
+  replayRun?: ReplayRunDescriptor | null;
+  now?: string | Date | null;
+  observedAt?: string | null;
+  repoFullName?: string;
+}
+
+export interface RunCalibrationCycleDeps extends ScoreCompositeOptions {
+  computeLoop?: (input: {
+    config?: Phase7CalibrationConfig | Phase7CalibrationManifest | Record<string, unknown> | null;
+    prOutcome?: PrOutcomeCalibrationInput | null;
+    historicalReplay?: HistoricalReplayCalibrationInput | null;
+    now?: string | Date | null;
+  }) => Phase7CalibrationLoopResult;
+  eventLedger?: { appendEvent(event: AppendEventInput): LedgerEntry };
+}
+
+export interface RunCalibrationCycleResult {
+  result: Phase7CalibrationLoopResult;
+  snapshot: CalibrationSnapshotPayload;
+  recorded: LedgerEntry | null;
+  historicalReplay: HistoricalReplayCalibrationInput | null;
+  compositeScore: number | null;
+  sampleSize: number;
+  scores: number[];
+}
+
+export function runHistoricalReplayCalibrationCycle(
+  input?: RunCalibrationCycleInput,
+  deps?: RunCalibrationCycleDeps,
+): RunCalibrationCycleResult;

package/lib/calibration-run.js

@@ -0,0 +1,232 @@
+// Phase 7 calibration runner (#4248): the miner-side runner that finally CONNECTS the two finished-but-unwired
+// halves #3014 left apart. #3014 landed the engine's pure calibration *combine* contract
+// (`computePhase7CalibrationLoop`, packages/gittensory-engine/src/phase7-calibration-loop.ts) and #3012 landed the
+// deterministic replay *scorer* (`computeObjectiveAnchor`, ./replay-objective-anchor.js), but nothing ever called
+// one with the other -- #3014's issue claimed "wired" while only the engine side shipped. This module is the
+// missing runner: it scores a completed historical-replay run with the objective-anchor scorer, folds the
+// resulting composite into the `HistoricalReplayCalibrationInput` shape the engine expects, calls the combine with
+// the existing pr_outcome signal, and PERSISTS the combined snapshot to the local append-only event ledger (a typed
+// event layered on event-ledger.js exactly like pr-outcome.js's MINER_PR_OUTCOME_EVENT), queryable via
+// `gittensory-miner ledger list --type calibration_snapshot`.
+//
+// SCOPE: this runner is read/measure-only. It produces and persists the tracked calibration metric; it NEVER acts
+// on it (no autonomy-level bump, no gate-threshold tune) -- that enforcement is maintainer-only and fail-closed
+// (see docs/miner-selfimprove-calibration.md's maintainer-only boundary). The engine owns the deterministic
+// combine/freshness/threshold/hold-reason logic; this module owns scheduling the score and persisting the row.
+
+import { computePhase7CalibrationLoop } from "@loopover/engine";
+import { computeObjectiveAnchor } from "./replay-objective-anchor.js";
+
+/** Event-ledger vocabulary for a persisted Phase 7 calibration snapshot (mirrors MINER_PR_OUTCOME_EVENT). */
+export const MINER_CALIBRATION_SNAPSHOT_EVENT = "calibration_snapshot";
+
+const SCORE_PRECISION = 1e6;
+
+function roundScore(value) {
+  return Math.round(Math.min(1, Math.max(0, value)) * SCORE_PRECISION) / SCORE_PRECISION;
+}
+
+function isFiniteNumber(value) {
+  return typeof value === "number" && Number.isFinite(value);
+}
+
+function numberOrNull(value) {
+  return isFiniteNumber(value) ? value : null;
+}
+
+function optionalString(value) {
+  if (typeof value !== "string") return null;
+  const trimmed = value.trim();
+  return trimmed || null;
+}
+
+/**
+ * Score a completed replay run's per-task results with the deterministic objective-anchor scorer and reduce them to
+ * one composite `[0, 1]` accuracy (the mean of the per-task scores). `replayResults` is a list of
+ * `{ replayPlan, revealedHistory }` pairs; each non-object entry is defensively skipped. Returns `compositeScore:
+ * null` (never a fabricated 0) when there is no scorable task. Pure aside from the injected scorer.
+ */
+export function scoreHistoricalReplayComposite(replayResults, options = {}) {
+  const scoreOne = options.computeObjectiveAnchor ?? computeObjectiveAnchor;
+  const list = Array.isArray(replayResults) ? replayResults : [];
+  const scores = [];
+  for (const entry of list) {
+    if (!entry || typeof entry !== "object" || Array.isArray(entry)) continue;
+    const { score } = scoreOne({ replayPlan: entry.replayPlan, revealedHistory: entry.revealedHistory });
+    if (isFiniteNumber(score)) scores.push(score);
+  }
+  const sampleSize = scores.length;
+  const compositeScore = sampleSize === 0 ? null : roundScore(scores.reduce((sum, s) => sum + s, 0) / sampleSize);
+  return { compositeScore, sampleSize, scores };
+}
+
+/**
+ * Build the engine's `HistoricalReplayCalibrationInput` from a replay run descriptor
+ * (`{ replayResults, replayRunId, observedAt, harnessStatus }`). Returns `historicalReplay: null` when no run
+ * descriptor is supplied (the engine then holds `no_historical_replay_signal` when the loop is enabled). When a run
+ * IS supplied its `harnessStatus` flows through verbatim so a degraded/unavailable harness still reaches the
+ * engine's fail-closed hold path even if it scored zero tasks; a null composite becomes `0` only for the engine's
+ * numeric contract (the un-fabricated `compositeScore`/`sampleSize` are returned alongside for the snapshot).
+ */
+export function buildHistoricalReplayCalibrationInput(replayRun, options = {}) {
+  if (!replayRun || typeof replayRun !== "object" || Array.isArray(replayRun)) {
+    return { historicalReplay: null, compositeScore: null, sampleSize: 0, scores: [] };
+  }
+  const composite = scoreHistoricalReplayComposite(replayRun.replayResults, options);
+  return {
+    historicalReplay: {
+      compositeScore: composite.compositeScore ?? 0,
+      replayRunId: replayRun.replayRunId,
+      observedAt: replayRun.observedAt,
+      harnessStatus: replayRun.harnessStatus,
+    },
+    compositeScore: composite.compositeScore,
+    sampleSize: composite.sampleSize,
+    scores: composite.scores,
+  };
+}
+
+/**
+ * Derive a JSON-safe, public-safe snapshot payload from a computed `Phase7CalibrationLoopResult`. Only accuracies,
+ * the documented baseline, hold-reason CODES, and provenance are surfaced -- never raw replay scores or rewards.
+ * Every field is a number/null, boolean, string/null, or string[] so it round-trips through the event ledger's
+ * verbatim-JSON serializer unchanged.
+ */
+export function snapshotPayloadFromResult(result, meta = {}) {
+  return {
+    enabled: result.enabled === true,
+    combinedAccuracy: numberOrNull(result.combinedAccuracy),
+    baselineAccuracy: isFiniteNumber(result.baselineAccuracy) ? result.baselineAccuracy : 0,
+    deltaFromBaseline: numberOrNull(result.deltaFromBaseline),
+    autonomyIncreasePermitted: result.autonomyIncreasePermitted === true,
+    replayHarnessHold: result.replayHarnessHold === true,
+    replayHarnessStatus: optionalString(result.replayHarnessStatus) ?? "missing",
+    replayRunDue: result.replayRunDue === true,
+    holdReasons: Array.isArray(result.holdReasons) ? result.holdReasons.map(String) : [],
+    contributingSources: Array.isArray(result.audit?.contributingSources)
+      ? result.audit.contributingSources.map(String)
+      : [],
+    replayRunId: optionalString(meta.replayRunId),
+    observedAt: optionalString(meta.observedAt),
+    replaySampleSize: Number.isInteger(meta.sampleSize) && meta.sampleSize >= 0 ? meta.sampleSize : 0,
+  };
+}
+
+/**
+ * Validate + normalize a calibration-snapshot payload, returning `null` on any malformed shape (mirrors
+ * pr-outcome.js's `normalizePrOutcomePayload`, so a corrupted row can neither be written nor read back). Skipped
+ * rows are dropped by the reader rather than throwing.
+ */
+export function normalizeCalibrationSnapshotPayload(payload) {
+  if (!payload || typeof payload !== "object" || Array.isArray(payload)) return null;
+  if (payload.combinedAccuracy !== null && !isFiniteNumber(payload.combinedAccuracy)) return null;
+  if (!isFiniteNumber(payload.baselineAccuracy)) return null;
+  if (payload.deltaFromBaseline !== null && !isFiniteNumber(payload.deltaFromBaseline)) return null;
+  if (typeof payload.autonomyIncreasePermitted !== "boolean") return null;
+  const replayHarnessStatus = optionalString(payload.replayHarnessStatus);
+  if (!replayHarnessStatus) return null;
+  if (!Array.isArray(payload.holdReasons) || payload.holdReasons.some((code) => typeof code !== "string")) {
+    return null;
+  }
+  const contributingSources = Array.isArray(payload.contributingSources)
+    ? payload.contributingSources.filter((code) => typeof code === "string")
+    : [];
+  return {
+    enabled: payload.enabled === true,
+    combinedAccuracy: payload.combinedAccuracy,
+    baselineAccuracy: payload.baselineAccuracy,
+    deltaFromBaseline: payload.deltaFromBaseline,
+    autonomyIncreasePermitted: payload.autonomyIncreasePermitted,
+    replayHarnessHold: payload.replayHarnessHold === true,
+    replayHarnessStatus,
+    replayRunDue: payload.replayRunDue === true,
+    holdReasons: payload.holdReasons,
+    contributingSources,
+    replayRunId: optionalString(payload.replayRunId),
+    observedAt: optionalString(payload.observedAt),
+    replaySampleSize:
+      Number.isInteger(payload.replaySampleSize) && payload.replaySampleSize >= 0 ? payload.replaySampleSize : 0,
+  };
+}
+
+/**
+ * Persist one calibration snapshot to an INJECTED event ledger (same dependency-injection shape as pr-outcome.js's
+ * `recordPrOutcomeSnapshot`, so it's unit-testable without a real SQLite file). Fail-soft: a malformed payload
+ * returns `null` without appending. An unusable ledger is the only hard error (a programmer wiring mistake).
+ */
+export function recordCalibrationSnapshot(input, options = {}) {
+  const eventLedger = options.eventLedger;
+  if (!eventLedger || typeof eventLedger.appendEvent !== "function") throw new Error("invalid_event_ledger");
+  const payload = normalizeCalibrationSnapshotPayload(input);
+  if (!payload) return null;
+  const repoFullName = optionalString(options.repoFullName);
+  return eventLedger.appendEvent({
+    type: MINER_CALIBRATION_SNAPSHOT_EVENT,
+    ...(repoFullName ? { repoFullName } : {}),
+    payload,
+  });
+}
+
+/**
+ * Read every persisted calibration snapshot from the injected ledger's ascending append-only stream (mirrors
+ * pr-outcome.js's `readPrOutcomes`). Foreign event types and malformed payloads are skipped; a ledger that cannot
+ * read reduces to an empty list. Returns snapshots in ledger order (oldest first).
+ */
+export function readCalibrationSnapshots(eventLedger, filter = {}) {
+  const events =
+    eventLedger && typeof eventLedger.readEvents === "function" ? eventLedger.readEvents(filter) : [];
+  const snapshots = [];
+  for (const event of Array.isArray(events) ? events : []) {
+    if (event?.type !== MINER_CALIBRATION_SNAPSHOT_EVENT) continue;
+    const normalized = normalizeCalibrationSnapshotPayload(event.payload);
+    if (!normalized) continue;
+    snapshots.push({
+      ...normalized,
+      repoFullName: typeof event.repoFullName === "string" ? event.repoFullName : null,
+      seq: Number.isInteger(event.seq) ? event.seq : null,
+      createdAt: optionalString(event.createdAt),
+    });
+  }
+  return snapshots;
+}
+
+/** The most recent persisted calibration snapshot, or `null` when none exist. */
+export function latestCalibrationSnapshot(eventLedger, filter = {}) {
+  const snapshots = readCalibrationSnapshots(eventLedger, filter);
+  return snapshots.length > 0 ? snapshots[snapshots.length - 1] : null;
+}
+
+/**
+ * The runner. Scores the replay run (via the objective-anchor scorer), calls the engine's calibration combine with
+ * the resulting historical-replay composite plus the existing pr_outcome signal, and -- when an event ledger is
+ * injected -- persists the combined snapshot. Returns the engine result, the derived snapshot payload, the recorded
+ * ledger entry (or null when no ledger was injected or the payload was malformed), and the un-fabricated
+ * composite/sample provenance. The engine combine (`computeLoop`) is injectable so unit tests can pin it.
+ */
+export function runHistoricalReplayCalibrationCycle(input = {}, deps = {}) {
+  const computeLoop = deps.computeLoop ?? computePhase7CalibrationLoop;
+  const built = buildHistoricalReplayCalibrationInput(input.replayRun, deps);
+  const result = computeLoop({
+    config: input.config,
+    prOutcome: input.prOutcome,
+    historicalReplay: built.historicalReplay,
+    now: input.now,
+  });
+  const snapshot = snapshotPayloadFromResult(result, {
+    replayRunId: built.historicalReplay?.replayRunId ?? null,
+    observedAt: input.observedAt ?? built.historicalReplay?.observedAt ?? null,
+    sampleSize: built.sampleSize,
+  });
+  const recorded = deps.eventLedger
+    ? recordCalibrationSnapshot(snapshot, { eventLedger: deps.eventLedger, repoFullName: input.repoFullName })
+    : null;
+  return {
+    result,
+    snapshot,
+    recorded,
+    historicalReplay: built.historicalReplay,
+    compositeScore: built.compositeScore,
+    sampleSize: built.sampleSize,
+    scores: built.scores,
+  };
+}

package/lib/calibration-types.d.ts

@@ -0,0 +1,46 @@
+/** A single gate-prediction row the miner will replay against observed outcomes. */
+export type PredictedVerdictRecord = {
+  targetId: string;
+  project: string;
+  predictedDecision: string;
+  recordedAt: string;
+  source?: string;
+};
+
+/** The realized human outcome for a previously predicted target. */
+export type ObservedOutcomeRecord = {
+  targetId: string;
+  project: string;
+  outcomeDecision: string;
+  recordedAt: string;
+};
+
+/** Per-project confusion-matrix row — field names mirror `GateEvalRow` in `src/review/parity.ts`. */
+export type CalibrationRow = {
+  project: string;
+  wouldMerge: number;
+  mergeConfirmed: number;
+  mergeFalse: number;
+  wouldClose: number;
+  closeConfirmed: number;
+  closeFalse: number;
+  hold: number;
+  decided: number;
+  mergePrecision: number | null;
+  closePrecision: number | null;
+};
+
+/** Aggregate calibration report over one or more projects. */
+export type CalibrationReport = {
+  rows: CalibrationRow[];
+  /** True once at least one project has enough decided samples to read meaningfully. */
+  hasSignal: boolean;
+};
+
+export function isPredictedVerdictRecord(value: unknown): value is PredictedVerdictRecord;
+
+export function isObservedOutcomeRecord(value: unknown): value is ObservedOutcomeRecord;
+
+export function isCalibrationRow(value: unknown): value is CalibrationRow;
+
+export function isCalibrationReport(value: unknown): value is CalibrationReport;

package/lib/calibration-types.js

@@ -0,0 +1,74 @@
+// Shared calibration shapes for the miner self-improvement phase (#2332). Types-only scaffolding —
+// report/ledger/metrics issues build on this module. Field names mirror `GateEvalRow` /
+// `GateEvalReport` in `src/review/parity.ts` for easy mental mapping without importing cloud code.
+
+function isNonEmptyString(value) {
+  return typeof value === "string" && value.trim().length > 0;
+}
+
+function isOptionalString(value) {
+  return value === undefined || isNonEmptyString(value);
+}
+
+function isNonNegativeInteger(value) {
+  return typeof value === "number" && Number.isInteger(value) && value >= 0;
+}
+
+function isNullableRatio(value) {
+  return value === null || (typeof value === "number" && Number.isFinite(value) && value >= 0 && value <= 1);
+}
+
+/** @param {unknown} value */
+export function isPredictedVerdictRecord(value) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return false;
+  const record = /** @type {Record<string, unknown>} */ (value);
+  return (
+    isNonEmptyString(record.targetId)
+    && isNonEmptyString(record.project)
+    && isNonEmptyString(record.predictedDecision)
+    && isNonEmptyString(record.recordedAt)
+    && isOptionalString(record.source)
+  );
+}
+
+/** @param {unknown} value */
+export function isObservedOutcomeRecord(value) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return false;
+  const record = /** @type {Record<string, unknown>} */ (value);
+  return (
+    isNonEmptyString(record.targetId)
+    && isNonEmptyString(record.project)
+    && isNonEmptyString(record.outcomeDecision)
+    && isNonEmptyString(record.recordedAt)
+  );
+}
+
+/** @param {unknown} value */
+export function isCalibrationRow(value) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return false;
+  const row = /** @type {Record<string, unknown>} */ (value);
+  return (
+    isNonEmptyString(row.project)
+    && isNonNegativeInteger(row.wouldMerge)
+    && isNonNegativeInteger(row.mergeConfirmed)
+    && isNonNegativeInteger(row.mergeFalse)
+    && isNonNegativeInteger(row.wouldClose)
+    && isNonNegativeInteger(row.closeConfirmed)
+    && isNonNegativeInteger(row.closeFalse)
+    && isNonNegativeInteger(row.hold)
+    && isNonNegativeInteger(row.decided)
+    && isNullableRatio(row.mergePrecision)
+    && isNullableRatio(row.closePrecision)
+  );
+}
+
+/** @param {unknown} value */
+export function isCalibrationReport(value) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) return false;
+  const report = /** @type {Record<string, unknown>} */ (value);
+  return (
+    typeof report.hasSignal === "boolean"
+    && Array.isArray(report.rows)
+    && report.rows.every((row) => isCalibrationRow(row))
+  );
+}

package/lib/calibration.d.ts

@@ -0,0 +1,24 @@
+import type {
+  CalibrationReport,
+  ObservedOutcomeRecord,
+  PredictedVerdictRecord,
+} from "./calibration-types.js";
+
+export type {
+  CalibrationReport,
+  CalibrationRow,
+  ObservedOutcomeRecord,
+  PredictedVerdictRecord,
+} from "./calibration-types.js";
+
+export {
+  isCalibrationReport,
+  isCalibrationRow,
+  isObservedOutcomeRecord,
+  isPredictedVerdictRecord,
+} from "./calibration-types.js";
+
+export function buildCalibrationReport(
+  predictions: PredictedVerdictRecord[],
+  outcomes: ObservedOutcomeRecord[],
+): CalibrationReport;