feat(orb): capture the decision-time wall clock so staleness rules are replayable (#9028)

gate.requireFreshRebaseWindow compared the base branch's tip against an inline Date.now()
read inside maybeForceFreshRebase. Time is a decision INPUT, and nothing recorded which
instant the comparison used — so re-deriving such a decision later could silently reach the
opposite answer purely because the wall clock had moved, and report it as a match.

The decision pass now takes ONE Date.now() reading, records it into
decision_replay_inputs.replay_json as `clock`, and passes it to every clock-dependent rule
instead of each calling the clock itself. Both staleness rules move to a pure, clock-injected
module: isWithinFreshRebaseWindow takes the instant explicitly, and isBaseStaleByAheadBy is
stated as the commit-count comparison it is — provably instant-independent, not merely
assumed so.

replayDecision gains a stage-0 `clock` check: replaying at the recorded instant (the CLI
default) is bit-exact, while naming a different instant reports a `clock` divergence rather
than silently certifying a re-derivation that never reproduced the original evaluation.
Records written before this change carry no instant, so the stage is skipped rather than
guessed. The CLI exposes it as `--at <epoch ms>`.

Also corrects the decision_replay_inputs migration reference in two doc comments (0181 is
alert_dedup_claims; the table is created in 0182).

Author: JSONbored

scripts/replay-decision.ts

@@ -4,6 +4,12 @@
 //
 //   node --experimental-strip-types scripts/replay-decision.ts <bundle.json>
 //   ... | node --experimental-strip-types scripts/replay-decision.ts -
+//   node --experimental-strip-types scripts/replay-decision.ts <bundle.json> --at <epoch ms>
+//
+// #9028: `--at` names the instant to replay AT. Omit it to replay at the instant the decision itself recorded
+// (`replayInput.clock.nowMs`) — the bit-exact case. Passing a DIFFERENT instant exits 1 with a `clock`
+// divergence rather than reporting a match: time is a decision INPUT, and a clock-dependent rule
+// (`gate.requireFreshRebaseWindow`) can flip purely because the wall clock moved.
 //
 // The bundle is one JSON object: { record: {...decision_records row}, replayInput: {...replay_json} }.
 // EXTRACT (operator, against the instance DB):
@@ -24,8 +30,13 @@
 import { readFileSync } from "node:fs";
 import { replayDecision, type DecisionReplayInput, type ReplayableRecord } from "../src/review/decision-replay";
 
-/** Parse + normalize a bundle (snake_case SQL rows accepted) and replay it. Exported for tests. */
-export function runReplayBundle(raw: string): { outcome: ReturnType<typeof replayDecision> | null; error?: string } {
+/** Parse + normalize a bundle (snake_case SQL rows accepted) and replay it. Exported for tests.
+ *
+ *  #9028: `atMs` names the instant to replay AT. Omitted (the default) replays at the instant the decision
+ *  recorded, which is the bit-exact case. Supplying a DIFFERENT instant is reported as a `clock` divergence,
+ *  never silently accepted — a clock-dependent rule can legitimately flip its answer as the wall clock moves,
+ *  so "it still matches at a different instant" is not a re-derivation of the original decision. */
+export function runReplayBundle(raw: string, atMs?: number): { outcome: ReturnType<typeof replayDecision> | null; error?: string } {
   let bundle: { record?: Record<string, unknown>; replayInput?: unknown };
   try {
     bundle = JSON.parse(raw) as never;
@@ -47,18 +58,25 @@ export function runReplayBundle(raw: string): { outcome: ReturnType<typeof repla
   if (!record || !replayInput || !Array.isArray(replayInput.findings) || typeof replayInput.evaluated !== "object") {
     return { outcome: null, error: "bundle must carry {record: {id, reason_code|reasonCode, action}, replayInput: {findings, policy, evaluated}}" };
   }
-  return { outcome: replayDecision(record, replayInput) };
+  return { outcome: replayDecision(record, replayInput, atMs === undefined ? {} : { nowMs: atMs }) };
 }
 
 const invokedDirectly = process.argv[1]?.endsWith("replay-decision.ts") === true;
 if (invokedDirectly) {
-  const source = process.argv[2];
+  const argv = process.argv.slice(2);
+  const atIndex = argv.indexOf("--at");
+  const atRaw = atIndex === -1 ? undefined : argv[atIndex + 1];
+  if (atIndex !== -1 && (atRaw === undefined || !Number.isFinite(Number(atRaw)))) {
+    console.error("replay-decision: --at requires a Unix-epoch-milliseconds value");
+    process.exit(2);
+  }
+  const source = argv.filter((arg, index) => index !== atIndex && index !== atIndex + 1)[0];
   if (!source) {
-    console.error("usage: replay-decision.ts <bundle.json | ->");
+    console.error("usage: replay-decision.ts <bundle.json | -> [--at <epoch ms>]");
     process.exit(2);
   }
   const raw = source === "-" ? readFileSync(0, "utf8") : readFileSync(source, "utf8");
-  const { outcome, error } = runReplayBundle(raw);
+  const { outcome, error } = runReplayBundle(raw, atRaw === undefined ? undefined : Number(atRaw));
   if (!outcome) {
     console.error(`replay-decision: ${error}`);
     process.exit(2);

src/queue/processors.ts

@@ -663,6 +663,7 @@ import {
 import { AI_JUDGMENT_BLOCKER_CODES } from "../rules/advisory";
 import { computeSalvageabilityForTarget } from "../review/salvageability-wire";
 import { deriveDecisionReasonCode, persistDecisionReplayInputForGate } from "../review/decision-replay";
+import { isWithinFreshRebaseWindow, type DecisionClockCapture } from "../review/staleness-clock";
 import { recordVerdictFlip } from "../review/verdict-flip-store";
 import { resolveAutomaticCloseConfidence } from "../review/risk-control-wire";
 import { maybeApplyCloseAuditHoldout } from "../review/close-audit-holdout";
@@ -3175,6 +3176,12 @@ async function runAgentMaintenancePlanAndExecute(
   },
 ): Promise<void> {
   const { installationId, repoFullName, pr, settings, otherOpenPullRequests, deliveryId, gate } = args;
+  // #9028: ONE wall-clock read for this whole decision pass, recorded into the replay input below and passed
+  // to every clock-dependent gate rule (today `gate.requireFreshRebaseWindow` via maybeForceFreshRebase)
+  // instead of each of them calling Date.now() independently. Two rules reading the clock at two different
+  // moments cannot both be replayed from one recorded instant — and an unrecorded instant is an unrecorded
+  // decision INPUT, which is exactly what makes a time-dependent decision unreplayable.
+  const decisionClock: DecisionClockCapture = { nowMs: Date.now() };
 
   // Convergence safety: feed the planner the PR's changed paths + the repo's hard-guardrail globs so guarded
   // paths force manual review, and flag owner-authored PRs so they are never auto-closed (standing rule).
@@ -3761,13 +3768,13 @@ async function runAgentMaintenancePlanAndExecute(
       divertedByHoldout: closeAuditHoldout?.diverted ?? false,
     });
     const recordId = await persistDecisionRecord(env, record, recordDigest);
-    // #8838: persist the evaluation's own exact inputs beside the record (PRIVATE sibling, migration 0181)
+    // #8838: persist the evaluation's own exact inputs beside the record (PRIVATE sibling, migration 0182)
     // so the replay harness can re-derive this decision bit-exactly. Best-effort, like the record itself;
     // the no-replay no-op (synthetic content-lane/bridge evaluations) lives inside the helper. Keyed to the
     // id persistDecisionRecord actually wrote (#9123: a supersession at the same head gets a revisioned id,
     // not the base one this used to always recompute independently). #9135: the holdout outcome rides along
     // so `holdout_consistency` has something to check the public record against.
-    if (recordId !== null) await persistDecisionReplayInputForGate(env, recordId, gate, policyCloseKind ?? null, closeAuditHoldout ?? null);
+    if (recordId !== null) await persistDecisionReplayInputForGate(env, recordId, gate, policyCloseKind ?? null, closeAuditHoldout ?? null, decisionClock);
   }
   // #2349 (PR 1): additive per-contributor calibration data, gated identically to recordNativeGateDecision
   // above -- see src/review/contributor-calibration.ts's doc comment. Currently write-only; nothing reads
@@ -3897,6 +3904,7 @@ async function runAgentMaintenancePlanAndExecute(
       token,
       admissionKey,
       deliveryId,
+      nowMs: decisionClock.nowMs,
     }))
   ) {
     return;
@@ -4806,17 +4814,20 @@ async function maybeForceFreshRebase(
     token: string | undefined;
     admissionKey: GitHubRateLimitAdmissionKey | undefined;
     deliveryId: string;
+    // #9028: the decision pass's single captured instant — this rule reads it instead of the clock, so the
+    // window comparison is replayable from `decision_replay_inputs.replay_json`.
+    nowMs: number;
   },
 ): Promise<boolean> {
-  const { installationId, repoFullName, pr, settings, windowMinutes, baseRef, token, admissionKey, deliveryId } = args;
+  const { installationId, repoFullName, pr, settings, windowMinutes, baseRef, token, admissionKey, deliveryId, nowMs } = args;
   /* v8 ignore next -- structurally unreachable: the caller only invokes this after confirming
    * (liveMergeState ?? pr.mergeableState) === "clean", which GitHub can never compute for a PR with no
    * head commit; the null check is belt-and-suspenders against the field's optional TS type. */
   if (!pr.headSha) return false;
   const advancedAt = await fetchLiveBaseBranchAdvancedAt(env, repoFullName, baseRef, token, admissionKey);
   if (!advancedAt) return false; // fail-open: unreadable base commit -> no forced rebase
   const advancedAtMs = Date.parse(advancedAt);
-  if (!Number.isFinite(advancedAtMs) || Date.now() - advancedAtMs >= windowMinutes * 60_000) return false;
+  if (!isWithinFreshRebaseWindow({ baseAdvancedAtMs: advancedAtMs, windowMinutes, nowMs })) return false;
 
   const countKey = freshRebaseForceCountKey(repoFullName, pr.number);
   const storedCount = Number(await getTransientKey(env, countKey));

src/review/decision-replay.ts

@@ -8,6 +8,10 @@
 // guarantee is by construction, not by flag.
 //
 // Stages, compared in pipeline order (the first mismatch wins — everything after it is downstream noise):
+//   0. `clock`           — #9028: the instant the caller asked to replay AT vs the instant the live decision
+//                          recorded. Time is a decision input, so replaying a clock-dependent rule at a
+//                          DIFFERENT instant is never silently accepted as a match. Skipped when the caller
+//                          names no instant (replay at the recorded one) or the record predates #9028.
 //   1. `conclusion`      — re-evaluated gate conclusion vs the decision-time snapshot.
 //   2. `blocker_codes`   — ordered blocker code list (order IS meaning: blockerClass is the first code).
 //   3. `reason_code`     — re-derived exactly as the finalize site derives it (blockerClass →
@@ -32,6 +36,7 @@
 // and file it; there is no "close enough" outcome.
 import { evaluateGateCheck, type GateCheckPolicy } from "../rules/advisory";
 import { neutralHoldReasonCode } from "./parity-wire";
+import type { DecisionClockCapture } from "./staleness-clock";
 import type { Advisory, AdvisoryFinding } from "../types";
 import { errorMessage, nowIso } from "../utils/json";
 
@@ -60,6 +65,12 @@ export type DecisionReplayInput = {
    *  this decision (ε absent/0, close autonomy not auto, or no eligible close) — the overwhelmingly common
    *  case, and the SAME zero-I/O common path `maybeApplyCloseAuditHoldout` already guarantees. */
   holdout?: DecisionReplayHoldout | null | undefined;
+  /** #9028: the decision-time wall clock — ONE `Date.now()` read per pass, which every clock-dependent gate
+   *  rule (today: `gate.requireFreshRebaseWindow`) reads instead of calling the clock itself. Recorded here so
+   *  a replay evaluates time-dependent rules at the instant the LIVE decision used, not at replay time.
+   *  undefined/null for a pre-#9028 record — such a record simply has no recorded instant, so the `clock`
+   *  stage cannot check anything and is skipped rather than guessed. */
+  clock?: DecisionClockCapture | null | undefined;
 };
 
 /** The slice of the PUBLIC decision record replay verifies against. */
@@ -79,11 +90,18 @@ export type ReplayOutcome =
       verdict: "divergence";
       recordId: string;
       /** The FIRST divergent stage — later stages are downstream of it and not reported. */
-      stage: "conclusion" | "blocker_codes" | "reason_code" | "holdout_consistency";
+      stage: "clock" | "conclusion" | "blocker_codes" | "reason_code" | "holdout_consistency";
       expected: string;
       actual: string;
     };
 
+/** #9028: options for a replay run. `nowMs` names the instant the caller wants to replay AT — supply it only
+ *  to assert the recorded instant, or to deliberately probe a different one (which must FAIL, never silently
+ *  pass). Omitted (the default) means "replay at the recorded instant", which is the bit-exact case. */
+export type ReplayOptions = {
+  nowMs?: number | undefined;
+};
+
 /** The finalize site's reasonCode derivation, extracted verbatim so replay and live can never disagree
  *  about the mapping itself (single source of truth — processors.ts finalize imports this too). */
 export function deriveDecisionReasonCode(blockerClass: string, policyCloseKind: string | null | undefined, conclusion: string): string {
@@ -97,7 +115,19 @@ export function deriveBlockerClass(evaluation: { blockers: Array<{ code: string
 }
 
 /** PURE bit-exact replay. See the module doc for the stage contract. */
-export function replayDecision(record: ReplayableRecord, input: DecisionReplayInput): ReplayOutcome {
+export function replayDecision(record: ReplayableRecord, input: DecisionReplayInput, options: ReplayOptions = {}): ReplayOutcome {
+  // #9028 stage 0: TIME IS AN INPUT. A caller that names the instant it is replaying at must be told when
+  // that instant is not the one the live decision used — a clock-dependent rule (today
+  // `gate.requireFreshRebaseWindow`) can legitimately flip its answer purely because the wall clock moved, so
+  // silently replaying at "now" and reporting `match` would certify a re-derivation that never actually
+  // reproduced the original evaluation. Checked FIRST: every later stage is evaluated as of this instant.
+  // A caller that supplies no instant is replaying at the recorded one by definition, which is the bit-exact
+  // path and the CLI's default. A pre-#9028 record has no recorded instant, so there is nothing to contradict
+  // and the stage is skipped rather than guessed.
+  const recordedNowMs = input.clock?.nowMs;
+  if (typeof recordedNowMs === "number" && typeof options.nowMs === "number" && options.nowMs !== recordedNowMs) {
+    return { verdict: "divergence", recordId: record.id, stage: "clock", expected: String(recordedNowMs), actual: String(options.nowMs) };
+  }
   const advisory: Advisory = {
     id: `replay-${record.id}`,
     targetType: "pull_request",
@@ -141,7 +171,7 @@ export function replayDecision(record: ReplayableRecord, input: DecisionReplayIn
   return { verdict: "match", recordId: record.id, conclusion: evaluation.conclusion, blockerCodes, reasonCode, pinnedAction: record.action };
 }
 
-/** Persist the replay input beside its record (PRIVATE sibling — see migration 0181). Best-effort: replay
+/** Persist the replay input beside its record (PRIVATE sibling — see migration 0182). Best-effort: replay
  *  legibility must never break finalization, mirroring persistDecisionRecord's posture. Accepts the gate
  *  EVALUATION and owns the no-replay no-op: content-lane/bridge evaluations are synthetic (their verdicts
  *  come from their own deterministic pipelines, not the advisory evaluator) and carry no replay input —
@@ -154,6 +184,8 @@ export async function persistDecisionReplayInputForGate(
   // #9135: the close-audit holdout's decision-time outcome for this same decision, when it drew — threaded
   // straight through to the persisted replay input so `holdout_consistency` has something to check against.
   holdout?: DecisionReplayHoldout | null,
+  // #9028: the decision pass's single captured wall-clock instant, so time-dependent rules are replayable.
+  clock?: DecisionClockCapture | null,
 ): Promise<void> {
   if (!gate.replay) return;
   await persistDecisionReplayInput(env, recordId, {
@@ -162,6 +194,7 @@ export async function persistDecisionReplayInputForGate(
     policyCloseKind,
     evaluated: { conclusion: gate.conclusion, blockerCodes: gate.blockers.map((blocker) => blocker.code) },
     holdout: holdout ?? null,
+    clock: clock ?? null,
   });
 }
 

src/review/staleness-clock.ts

@@ -0,0 +1,56 @@
+// Clock-injected staleness rule evaluation (#9028, epic #8828 Phase 4) — the two `gate.*` staleness rules
+// as PURE functions of their inputs plus an explicitly supplied instant.
+//
+// Why this module exists: `requireFreshRebaseWindowMinutes` was evaluated by reading `Date.now()` inline
+// inside an IO helper (processors.ts `maybeForceFreshRebase`). That made the rule structurally unreplayable
+// — nothing recorded WHICH instant the comparison used, so re-deriving the decision later could silently
+// reach the opposite answer purely because the wall clock had moved. Time is a decision INPUT; an input that
+// is not recorded is not replayable. The engine now reads one decision-time instant per pass, records it into
+// `decision_replay_inputs.replay_json`, and every clock-dependent rule reads THAT instant rather than the
+// clock (see `DecisionReplayInput.clock`).
+//
+// `staleBaseAheadByThreshold` is deliberately included here even though it reads NO clock: it is a commit-COUNT
+// comparison (`aheadBy >= threshold`), so it is instant-independent by construction. Stating that as a pure,
+// tested function is what makes the property provable rather than assumed — the replay suite pins it by
+// evaluating the same inputs at wildly different instants and asserting an identical answer.
+
+/** Minutes → milliseconds, named so the fresh-rebase window's unit conversion has exactly one definition. */
+export const MS_PER_MINUTE = 60_000;
+
+/** The decision-time wall clock, captured ONCE per evaluation pass and recorded with the replay input. Every
+ *  clock-dependent gate rule reads this instead of calling `Date.now()` itself, so a replay re-derives the
+ *  same answer the live pass reached instead of whatever the clock happens to say at replay time. */
+export type DecisionClockCapture = {
+  /** Unix epoch milliseconds, from a single `Date.now()` read at the top of the decision pass. */
+  nowMs: number;
+};
+
+/**
+ * `gate.requireFreshRebaseWindow` (#2552): true when the base branch's tip commit landed WITHIN
+ * `windowMinutes` of `nowMs` — i.e. the base moved so recently that a `mergeable_state: clean` read may
+ * predate it, so a merge should be preceded by a forced rebase + CI recheck.
+ *
+ * PURE and total: an unparseable/non-finite `baseAdvancedAtMs` returns false (fail-open to today's behavior —
+ * an unreadable base commit must never manufacture a rebase), matching the live call site's own guard. A base
+ * commit dated in the FUTURE relative to the captured instant (clock skew between GitHub and this engine)
+ * yields a negative age, which is inside any positive window and therefore correctly reads as "just moved".
+ */
+export function isWithinFreshRebaseWindow(args: { baseAdvancedAtMs: number; windowMinutes: number; nowMs: number }): boolean {
+  const { baseAdvancedAtMs, windowMinutes, nowMs } = args;
+  if (!Number.isFinite(baseAdvancedAtMs)) return false;
+  return nowMs - baseAdvancedAtMs < windowMinutes * MS_PER_MINUTE;
+}
+
+/**
+ * `gate.staleBaseAheadByThreshold` (#review-grounding stale-base fact): true when the repo's default branch
+ * has advanced at least `threshold` commits beyond this PR's head, so the PR should be updated before review.
+ *
+ * PURE, total, and deliberately CLOCK-FREE — a commit count carries no notion of "now", so this rule's answer
+ * is identical at every instant. A non-finite `aheadBy` (an unreadable compare API response) returns false,
+ * fail-open, matching the live call site's `typeof aheadBy === "number"` guard.
+ */
+export function isBaseStaleByAheadBy(args: { aheadBy: number; threshold: number }): boolean {
+  const { aheadBy, threshold } = args;
+  if (!Number.isFinite(aheadBy)) return false;
+  return aheadBy >= threshold;
+}