@unrulysystems/native-motion-conformance 0.1.0-alpha.0

package/src/oracle/presenter.ts

@@ -0,0 +1,372 @@
+// The M1 presenter is a closed boundary: slice IDs enter, reviewed constants and exporter output
+// leave. It intentionally has no parser or generic input validator for foreign judge bundles.
+
+import {
+  injectDiscontinuityControl,
+  injectLinearControl,
+  eligibleOracleControlKinds,
+  type BlindedOracleTrace,
+  type OracleControlKind,
+  type OracleControlTrace,
+} from './controls'
+import { assertAttestedRealTrace, oracleContentHash } from './attestation'
+import { exportTraceRun, type OracleTraceRun } from './exportTrace'
+import { deriveOracleTraceSpan, scenarioForSlice, type OracleTraceSpan } from './scenarios'
+import { serializeTrace } from './serialize'
+import {
+  isSubjectiveSliceId,
+  type OracleEngine,
+  type OracleTrace,
+  type SubjectiveSliceId,
+  type TraceEvent,
+  type TraceRow,
+} from './types'
+
+/** The verbatim §5 M1 prompt. Reviewed scenario constants are its only text fills. */
+export const M1_TRAJECTORY_JUDGE_PROMPT_TEMPLATE = `You are an independent motion-quality judge. You did not produce any of the data below and you are
+not told which system produced which trace. Judge only what the numbers show.
+
+Scenario: {{scenario_name}} — {{one_line_description_of_expected_interaction}}.
+You are given {{N}} anonymized traces, labeled A, B, C, ... Each trace is a time series of an
+animated value: rows of (t_ms, value) and (t_ms, velocity), sampled at a fixed step. At least one
+trace may be a deliberately degraded control.
+
+Judge each trace on two dimensions:
+1. Continuity — at every interruption or gesture handoff marked at t={{event_times}}, does value
+   stay continuous (no jump) and does velocity carry through (no reset to zero, no sign flip that
+   the input did not cause)? Flag any discontinuity with its timestamp.
+2. Physical plausibility — does the approach to each target look like a settling spring (a smooth,
+   decaying approach) rather than a linear ramp, an instant snap, or an oscillation that should not
+   be there?
+
+Return ONLY one JSON object — no prose before or after it — with exactly these keys and no others:
+
+{
+  "rankings": {
+    "continuity": [every trace label exactly once, best to worst],
+    "physicalPlausibility": [every trace label exactly once, best to worst]
+  },
+  "traces": {
+    one entry per trace label: {
+      "continuity": { "verdict": "pass" | "borderline" | "fail", "issues": [...] },
+      "physicalPlausibility": { "verdict": "pass" | "borderline" | "fail", "issues": [...] }
+    }
+  }
+}
+
+Every issue is { "timestamps": [t_ms values copied exactly from the trace rows], "description":
+"one line of what looked wrong" }. A "pass" verdict must have "issues": []; a "borderline" or
+"fail" verdict must carry at least one issue naming where it looked wrong. Do not guess which
+system is which. The rankings require a strict order: if two traces are indistinguishable, rank
+them adjacently.`
+
+export class OraclePresenterError extends Error {
+  constructor(message: string) {
+    super(`oracle presenter: ${message}`)
+    this.name = 'OraclePresenterError'
+  }
+}
+
+export interface OracleJudgeScenario {
+  readonly name: string
+  readonly expectedInteraction: string
+}
+
+declare const oracleJudgeBundleBrand: unique symbol
+
+/** The entire judge-readable data surface, constructible only by `createJudgeBundle`. */
+export type OracleJudgeBundle = Readonly<{
+  prompt: string
+  scenario: OracleJudgeScenario
+  traces: readonly BlindedOracleTrace[]
+  readonly [oracleJudgeBundleBrand]: 'OracleJudgeBundle'
+}>
+
+export type OracleUnblindingSource =
+  | { readonly engine: OracleEngine }
+  | { readonly control: OracleControlKind }
+
+export interface OracleUnblindingEntry {
+  readonly source: OracleUnblindingSource
+  readonly traceHash: string
+  /** Guard-only metadata: it is never projected into the blinded judge bundle bytes. */
+  readonly eventTimes: readonly TraceEvent[]
+  readonly traceSpan: OracleTraceSpan
+}
+
+/** Separate from `OracleJudgeBundle`; only the later calibration guard may consume this record. */
+export type OracleUnblindingRecord = Readonly<Record<string, OracleUnblindingEntry>>
+
+export interface OraclePresentation {
+  readonly bundle: OracleJudgeBundle
+  readonly unblinding: OracleUnblindingRecord
+  /** Run-level calibration can query the kinds without adding provenance to judge-readable bytes. */
+  readonly controlKinds: readonly OracleControlKind[]
+  readonly manifestHash: string
+  /** The slice ids this presentation was built from — carried, so callers never re-claim them. */
+  readonly sliceIds: readonly SubjectiveSliceId[]
+  /** The run-scoped exporter registry anchoring every real candidate. */
+  readonly attestations: OracleTraceRun['attestations']
+}
+
+// Chain-of-custody brand: downstream consumers (the run-record builder) admit ONLY presentations
+// this module built. Copies lose membership; deep-freezing below makes in-place mutation throw
+// (review seuljp m18f8b1ed).
+const builtPresentations = new WeakSet<object>()
+
+export function assertPresenterBuiltPresentation(presentation: OraclePresentation): void {
+  if (!builtPresentations.has(presentation)) {
+    throw new OraclePresenterError('presentation was not built by the presenter')
+  }
+}
+
+type PresenterEntry = {
+  readonly trace: OracleTrace | OracleControlTrace
+  readonly source: OracleUnblindingSource
+}
+
+type PresenterEntries = {
+  readonly entries: readonly PresenterEntry[]
+  readonly controlKinds: readonly OracleControlKind[]
+}
+
+function error(message: string): never {
+  throw new OraclePresenterError(message)
+}
+
+function assertDenseSliceIds(sliceIds: readonly SubjectiveSliceId[]): SubjectiveSliceId {
+  if (!Array.isArray(sliceIds)) error('slice IDs must be a dense array')
+  if (sliceIds.length !== 1) {
+    error(`a judge bundle requires exactly one scenario slice; received ${sliceIds.length}`)
+  }
+  if (!(0 in sliceIds)) error('slice IDs contains a sparse entry at index 0')
+  const sliceId = sliceIds[0]
+  if (typeof sliceId !== 'string' || !isSubjectiveSliceId(sliceId)) {
+    error(`unsupported scenario slice '${String(sliceId)}'`)
+  }
+  return sliceId
+}
+
+function sameEvents(a: readonly TraceEvent[], b: readonly TraceEvent[]): boolean {
+  return (
+    a.length === b.length &&
+    a.every((event, index) => event.t === b[index]?.t && event.kind === b[index]?.kind)
+  )
+}
+
+function sameGrid(a: readonly TraceRow[], b: readonly TraceRow[]): boolean {
+  return a.length === b.length && a.every((row, index) => row.t === b[index]?.t)
+}
+
+/** Validates dense, exact fixed-60fps source rows before they can enter a blind bundle. */
+function assertRunTrace(trace: OracleTrace, sliceId: SubjectiveSliceId): void {
+  if (trace.scenarioId !== sliceId) {
+    error(
+      `exported trace scenario '${trace.scenarioId}' does not match requested slice '${sliceId}'`,
+    )
+  }
+  // `serializeTrace` owns the numeric and grid contract: dense arrays, exact 60 fps timestamps,
+  // and event marks landing on rows. It throws a typed `OracleTraceError` for every malformed row.
+  serializeTrace(trace)
+}
+
+function injectEligibleControl(
+  trace: OracleTraceRun['realTraces'][number],
+  kind: OracleControlKind,
+): OracleControlTrace {
+  switch (kind) {
+    case 'C-DISC':
+      return injectDiscontinuityControl(trace)
+    case 'C-LIN':
+      return injectLinearControl(trace)
+  }
+}
+
+function entriesForRun(sliceId: SubjectiveSliceId, run: OracleTraceRun): PresenterEntries {
+  const realTraces = run.realTraces
+  if (realTraces.length === 0) error('exporter returned no real traces')
+  const reference = realTraces[0]
+  if (reference === undefined) error('exporter returned no real traces')
+
+  for (const trace of realTraces) {
+    assertAttestedRealTrace(trace, 'judge bundle real candidate')
+    assertRunTrace(trace, sliceId)
+    if (
+      !sameGrid(trace.rows, reference.rows) ||
+      !sameEvents(trace.eventTimes, reference.eventTimes)
+    ) {
+      error('exporter returned incompatible grids or event marks for one scenario')
+    }
+  }
+
+  // A5 eligibility is a trace property, not a slice-name policy. Mid-active/release-only traces
+  // still carry C-DISC; only traces with the controls module's usable settle segment carry C-LIN.
+  const controlKinds = eligibleOracleControlKinds(reference)
+  const controls = controlKinds.map((kind) => injectEligibleControl(reference, kind))
+  for (const control of controls) {
+    assertRunTrace(control, sliceId)
+    if (
+      !sameGrid(control.rows, reference.rows) ||
+      !sameEvents(control.eventTimes, reference.eventTimes)
+    ) {
+      error(`${control.control.kind} control changed the scenario grid or event marks`)
+    }
+  }
+
+  return {
+    entries: [
+      ...realTraces.map((trace) => ({ trace, source: { engine: trace.engine } }) as const),
+      ...controls.map((trace) => ({ trace, source: { control: trace.control.kind } }) as const),
+    ],
+    controlKinds,
+  }
+}
+
+function labelAt(index: number): string {
+  let current = index
+  let label = ''
+  do {
+    label = String.fromCharCode(65 + (current % 26)) + label
+    current = Math.floor(current / 26) - 1
+  } while (current >= 0)
+  return label
+}
+
+/** Deterministic PRNG seeded by the manifest hash; never use wall-clock time or Math.random here. */
+function seededShuffle<T>(values: readonly T[], manifestHash: string): T[] {
+  let state = Number.parseInt(manifestHash.slice(0, 8), 16) >>> 0
+  const next = (): number => {
+    state = (state + 0x6d2b79f5) >>> 0
+    let value = state
+    value = Math.imul(value ^ (value >>> 15), value | 1)
+    value ^= value + Math.imul(value ^ (value >>> 7), value | 61)
+    return ((value ^ (value >>> 14)) >>> 0) / 0x1_0000_0000
+  }
+  const shuffled = [...values]
+  for (let index = shuffled.length - 1; index > 0; index -= 1) {
+    const swapIndex = Math.floor(next() * (index + 1))
+    const current = shuffled[index]
+    shuffled[index] = shuffled[swapIndex]!
+    shuffled[swapIndex] = current!
+  }
+  return shuffled
+}
+
+function formatEventTimes(events: readonly TraceEvent[]): string {
+  return events.map((event) => `${event.t}ms (${event.kind})`).join(', ')
+}
+
+function fillPrompt(
+  sliceId: SubjectiveSliceId,
+  traceCount: number,
+  events: readonly TraceEvent[],
+): string {
+  const scenario = scenarioForSlice(sliceId)
+  return M1_TRAJECTORY_JUDGE_PROMPT_TEMPLATE.replace('{{scenario_name}}', scenario.scenarioName)
+    .replace('{{one_line_description_of_expected_interaction}}', scenario.expectedInteraction)
+    .replace('{{N}}', String(traceCount))
+    .replace('{{event_times}}', formatEventTimes(events))
+}
+
+function blindedTrace(label: string, trace: OracleTrace): BlindedOracleTrace {
+  return {
+    label,
+    grid: trace.grid,
+    rows: trace.rows.map((row) => ({ t: row.t, value: row.value, velocity: row.velocity })),
+    eventTimes: trace.eventTimes.map((event) => ({ t: event.t, kind: event.kind })),
+  }
+}
+
+function canonicalManifest(sliceId: SubjectiveSliceId, entries: readonly PresenterEntry[]): string {
+  const first = entries[0]?.trace
+  if (first === undefined) error('trace set is empty')
+  const scenario = scenarioForSlice(sliceId)
+  return JSON.stringify({
+    promptTemplate: M1_TRAJECTORY_JUDGE_PROMPT_TEMPLATE,
+    promptFills: {
+      scenarioName: scenario.scenarioName,
+      expectedInteraction: scenario.expectedInteraction,
+      traceCount: entries.length,
+      eventTimes: formatEventTimes(first.eventTimes),
+    },
+    labelVocabulary: entries.map((_, index) => labelAt(index)),
+    entries: entries.map(({ trace, source }) => ({ source, trace: serializeTrace(trace) })),
+  })
+}
+
+/**
+ * Creates one scenario's blind bundle from a closed slice-ID table. The input is deliberately an
+ * ID array so phase 4 can pass its selected run slices without gaining any text or trace surface.
+ */
+export function createJudgeBundle(sliceIds: readonly SubjectiveSliceId[]): OraclePresentation {
+  const sliceId = assertDenseSliceIds(sliceIds)
+  const run = exportTraceRun([sliceId])
+  const { entries, controlKinds } = entriesForRun(sliceId, run)
+  const manifestHash = oracleContentHash(canonicalManifest(sliceId, entries))
+  const shuffled = seededShuffle(entries, manifestHash)
+  const first = shuffled[0]?.trace
+  if (first === undefined) error('trace set is empty')
+
+  const unblinding: Record<string, OracleUnblindingEntry> = {}
+  const traces = shuffled.map((entry, index) => {
+    const label = labelAt(index)
+    unblinding[label] = {
+      source: entry.source,
+      traceHash: oracleContentHash(serializeTrace(entry.trace)),
+      eventTimes: entry.trace.eventTimes.map((event) => ({ ...event })),
+      traceSpan: deriveOracleTraceSpan(entry.trace),
+    }
+    return blindedTrace(label, entry.trace)
+  })
+  const scenario = scenarioForSlice(sliceId)
+  const bundle = {
+    prompt: fillPrompt(sliceId, traces.length, first.eventTimes),
+    scenario: { name: scenario.scenarioName, expectedInteraction: scenario.expectedInteraction },
+    traces,
+  } as unknown as OracleJudgeBundle
+
+  const presentation: OraclePresentation = {
+    bundle,
+    unblinding,
+    controlKinds,
+    manifestHash,
+    sliceIds: Object.freeze([...sliceIds]),
+    attestations: run.attestations,
+  }
+  deepFreezePresentation(presentation)
+  builtPresentations.add(presentation)
+  return presentation
+}
+
+// Runtime immutability for the evidence chain: a frozen presentation cannot be doctored in place
+// (strict-mode assignment throws), and a copy loses the WeakSet brand above.
+function deepFreezePresentation(presentation: OraclePresentation): void {
+  for (const trace of presentation.bundle.traces) {
+    for (const row of trace.rows) Object.freeze(row)
+    for (const event of trace.eventTimes) Object.freeze(event)
+    Object.freeze(trace.rows)
+    Object.freeze(trace.eventTimes)
+    Object.freeze(trace)
+  }
+  Object.freeze(presentation.bundle.traces)
+  Object.freeze(presentation.bundle.scenario)
+  Object.freeze(presentation.bundle)
+  for (const entry of Object.values(presentation.unblinding)) {
+    for (const event of entry.eventTimes) Object.freeze(event)
+    Object.freeze(entry.eventTimes)
+    Object.freeze(entry.source)
+    Object.freeze(entry)
+  }
+  Object.freeze(presentation.unblinding)
+  Object.freeze(presentation.controlKinds)
+  Object.freeze(presentation)
+}
+
+/** Canonical provenance-free bytes for judge dispatch and the immutable run record. */
+export function serializeJudgeBundle(bundle: OracleJudgeBundle): string {
+  return JSON.stringify({
+    prompt: bundle.prompt,
+    scenario: bundle.scenario,
+    traces: bundle.traces,
+  })
+}

package/src/oracle/runRecord.ts

@@ -0,0 +1,307 @@
+// The executed-run record (packet A3/A4). Evidence rides a provenance CHAIN (reviews 0nh3zf +
+// seuljp): presentations must be presenter-built (branded + deep-frozen), verdict outcomes must
+// be judgeBundle-built (branded, carrying the provider config actually used), real-trace hashes
+// are checked against the exporter's attestation registry, raw judge text is re-parsed and
+// compared, and the pure guard is re-run and compared. Nothing is recorded on trust. The module
+// performs no I/O and reads no clock: deterministic bytes plus a dated path are handed to the
+// caller (the phase-5 command) for persistence.
+
+import { oracleContentHash } from './attestation'
+import {
+  assertJudgeVerdictOutcome,
+  decideOracleGuard,
+  parseJudgeVerdict,
+  type JudgeProviderConfig,
+  type JudgeVerdictOutcome,
+  type OracleBlindnessAudit,
+  type OracleGuardOutcome,
+  type OracleJudgeCleanupError,
+  type OracleJudgeVerdict,
+} from './judge'
+import type { OracleControlKind } from './controls'
+import {
+  assertPresenterBuiltPresentation,
+  serializeJudgeBundle,
+  type OracleJudgeScenario,
+  type OraclePresentation,
+  type OracleUnblindingRecord,
+} from './presenter'
+import { SUBJECTIVE_SLICE_IDS, type SubjectiveSliceId } from './types'
+
+export const ORACLE_RUNS_DIRECTORY = 'packages/conformance/oracle-runs'
+
+export class OracleRunRecordError extends Error {
+  constructor(message: string) {
+    super(`oracle run record: ${message}`)
+    this.name = 'OracleRunRecordError'
+  }
+}
+
+/** One judged bundle: the two branded pipeline objects. Everything else is DERIVED from them. */
+export interface OracleRunBundleInput {
+  readonly presentation: OraclePresentation
+  readonly outcome: JudgeVerdictOutcome
+}
+
+export interface OracleRunInputs {
+  readonly bundles: readonly OracleRunBundleInput[]
+  readonly guard: OracleGuardOutcome
+}
+
+/** Per-bundle persisted evidence; every field below is derived inside `buildOracleRunRecord`. */
+export interface OracleRunBundleRecord {
+  readonly sliceIds: readonly SubjectiveSliceId[]
+  readonly scenario: OracleJudgeScenario
+  readonly labels: readonly string[]
+  readonly traceHashes: readonly { readonly label: string; readonly hash: string }[]
+  readonly manifestHash: string
+  readonly controlKinds: readonly OracleControlKind[]
+  /** The judge-visible prompt (provenance-free by construction), retained for re-audit. */
+  readonly prompt: string
+  readonly rawJudgeText: string
+  /** The FULL raw --json event stream, so the no-tool-use claim is independently re-auditable. */
+  readonly rawTranscript: string
+  readonly verdict: OracleJudgeVerdict
+  /**
+   * Post-judgment unblinding (label → source/hash/events/span): the record is the run's human-
+   * facing evidence, so a later reviewer can recompute the calibration guard from the artifact.
+   */
+  readonly unblinding: OracleUnblindingRecord
+  /** The per-run transcript audit — a run without a blindness proof must not record. */
+  readonly blindness: OracleBlindnessAudit
+  readonly cleanupFailed?: OracleJudgeCleanupError
+}
+
+export interface OracleRunRecord {
+  readonly bundles: readonly OracleRunBundleRecord[]
+  readonly guard: OracleGuardOutcome
+  /** Derived from the outcomes' carried configs (all bundles must agree), never claimed. */
+  readonly provider: Pick<JudgeProviderConfig, 'binary' | 'args' | 'timeoutMs'>
+}
+
+export interface OracleRunRecordFile {
+  readonly path: string
+  readonly content: string
+}
+
+// Runtime provenance for the record itself: only builder output may serialize. The brand is a
+// private WeakSet membership (the registry-handle precedent) — JSON round-trips cannot forge it.
+const builtRecords = new WeakSet<OracleRunRecord>()
+
+// Key-sorted stringify so structural equality comparisons are insensitive to construction order.
+function stableStringify(value: unknown): string {
+  return JSON.stringify(value, (_key, node: unknown) => {
+    if (node === null || typeof node !== 'object' || Array.isArray(node)) return node
+    const entries = Object.entries(node as Record<string, unknown>)
+    entries.sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+    return Object.fromEntries(entries)
+  })
+}
+
+/**
+ * Derive-and-bind over the provenance chain. Throws instead of recording when any link fails:
+ * an unbranded presentation or outcome, a real-trace hash absent from the exporter's attestation
+ * registry, raw text that does not re-parse to the recorded verdict, mismatched provider configs
+ * across bundles, or a guard outcome the recomputation does not reproduce.
+ */
+export function buildOracleRunRecord(inputs: OracleRunInputs): OracleRunRecord {
+  if (inputs.bundles.length === 0) {
+    throw new OracleRunRecordError('a run record requires at least one judged bundle')
+  }
+
+  // Full-run slice closure (review c6w0wg m27): an M1 run covers EVERY required slice exactly
+  // once — a partial or duplicated run must never record as an executed oracle run.
+  const covered = inputs.bundles.flatMap((entry) => entry.presentation.sliceIds)
+  if (new Set(covered).size !== covered.length) {
+    throw new OracleRunRecordError('a run must cover each slice exactly once (duplicate slice)')
+  }
+  const missing = SUBJECTIVE_SLICE_IDS.filter((sliceId) => !covered.includes(sliceId))
+  const foreign = covered.filter(
+    (sliceId) => !(SUBJECTIVE_SLICE_IDS as readonly string[]).includes(sliceId),
+  )
+  if (missing.length > 0 || foreign.length > 0) {
+    throw new OracleRunRecordError(
+      `a run must cover every required slice exactly once (missing: ${missing.join(', ') || 'none'}; foreign: ${foreign.join(', ') || 'none'})`,
+    )
+  }
+
+  let provider: OracleRunRecord['provider'] | undefined
+  const bundles: OracleRunBundleRecord[] = inputs.bundles.map((entry, index) => {
+    const { presentation, outcome } = entry
+    try {
+      assertPresenterBuiltPresentation(presentation)
+    } catch (error) {
+      const cause = error instanceof Error ? error.message : String(error)
+      throw new OracleRunRecordError(`bundle ${index}: ${cause}`)
+    }
+    try {
+      assertJudgeVerdictOutcome(outcome)
+    } catch (error) {
+      const cause = error instanceof Error ? error.message : String(error)
+      throw new OracleRunRecordError(`bundle ${index}: ${cause}`)
+    }
+
+    // Outcome↔bundle identity (review c6w0wg m25): the outcome must have judged THESE bytes.
+    if (outcome.bundleHash !== oracleContentHash(serializeJudgeBundle(presentation.bundle))) {
+      throw new OracleRunRecordError(
+        `bundle ${index}: outcome was paired with a presentation it did not judge`,
+      )
+    }
+
+    // Blindness proof (ruling 2026-07-14): REQ-ORACLE-002's void semantics — a judgment
+    // without an audited pure-turn transcript must never record as an executed oracle run.
+    if (outcome.blindness === undefined) {
+      throw new OracleRunRecordError(
+        `bundle ${index}: outcome carries no blindness proof — the judgment cannot be verified path-blind`,
+      )
+    }
+
+    // Execution provenance (review kpp2fg m7f2a61c9): only transcripts read off the pipe of a
+    // process the REAL CLI provider spawned may record as an executed run. Injected providers
+    // are for tests of everything upstream; their outcomes stop here.
+    if (outcome.executionProvenance !== 'cli') {
+      throw new OracleRunRecordError(
+        `bundle ${index}: outcome execution provenance is ${outcome.executionProvenance} — only CLI-executed judgments may record`,
+      )
+    }
+
+    // Real candidates must carry hashes the exporter attested in THIS run; a doctored hash has
+    // no matching attestation. (Controls are verified by injector recomputation at presentation
+    // time; their hashes are presenter-derived and frozen.)
+    const attested = new Set(presentation.attestations.traceHashes)
+    for (const [label, unblindingEntry] of Object.entries(presentation.unblinding)) {
+      if ('engine' in unblindingEntry.source && !attested.has(unblindingEntry.traceHash)) {
+        throw new OracleRunRecordError(
+          `bundle ${index}: real trace ${label} hash is not attested by this run's exporter`,
+        )
+      }
+    }
+
+    let reparsed: OracleJudgeVerdict
+    try {
+      reparsed = parseJudgeVerdict(outcome.rawText, presentation.bundle)
+    } catch (error) {
+      const cause = error instanceof Error ? error.message : String(error)
+      throw new OracleRunRecordError(
+        `bundle ${index}: raw judge text does not parse against its bundle: ${cause}`,
+      )
+    }
+    if (stableStringify(reparsed) !== stableStringify(outcome.verdict)) {
+      throw new OracleRunRecordError(
+        `bundle ${index}: raw judge text does not re-parse to the recorded verdict`,
+      )
+    }
+
+    if (provider === undefined) {
+      provider = outcome.provider
+    } else if (stableStringify(provider) !== stableStringify(outcome.provider)) {
+      throw new OracleRunRecordError(
+        `bundle ${index}: provider config differs from the run's other bundles`,
+      )
+    }
+
+    const entries = Object.entries(presentation.unblinding)
+    entries.sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+    return {
+      sliceIds: presentation.sliceIds,
+      scenario: presentation.bundle.scenario,
+      labels: entries.map(([label]) => label),
+      traceHashes: entries.map(([label, unblindingEntry]) => ({
+        label,
+        hash: unblindingEntry.traceHash,
+      })),
+      manifestHash: presentation.manifestHash,
+      controlKinds: presentation.controlKinds,
+      prompt: presentation.bundle.prompt,
+      rawJudgeText: outcome.rawText,
+      rawTranscript: outcome.transcript,
+      verdict: outcome.verdict,
+      unblinding: presentation.unblinding,
+      blindness: outcome.blindness,
+      ...(outcome.cleanupFailed === undefined ? {} : { cleanupFailed: outcome.cleanupFailed }),
+    }
+  })
+  if (provider === undefined) {
+    throw new OracleRunRecordError('no provider configuration could be derived from the outcomes')
+  }
+
+  const recomputedGuard = decideOracleGuard(
+    inputs.bundles.map((entry) => {
+      assertJudgeVerdictOutcome(entry.outcome)
+      return {
+        verdict: entry.outcome.verdict,
+        unblinding: entry.presentation.unblinding,
+        controlKinds: entry.presentation.controlKinds,
+      }
+    }),
+  )
+  if (stableStringify(recomputedGuard) !== stableStringify(inputs.guard)) {
+    throw new OracleRunRecordError(
+      'supplied guard outcome does not match the recomputed guard decision',
+    )
+  }
+
+  // Store the RECOMPUTED guard, never the caller's object: an alias the caller retains could be
+  // mutated after branding (review fva54q m4). Its whole graph is frozen in deepFreezeRecord.
+  const record: OracleRunRecord = { bundles, guard: recomputedGuard, provider }
+  deepFreezeRecord(record)
+  builtRecords.add(record)
+  return record
+}
+
+// A branded record that could be doctored after building would defeat the brand (review c6w0wg
+// m26): freeze the whole persisted graph. Guard/verdict/provider substructures arrive already
+// frozen from their builders; freeze the record-owned containers here.
+function deepFreezeRecord(record: OracleRunRecord): void {
+  for (const bundle of record.bundles) {
+    for (const traceHash of bundle.traceHashes) Object.freeze(traceHash)
+    Object.freeze(bundle.traceHashes)
+    Object.freeze(bundle.labels)
+    Object.freeze(bundle.sliceIds)
+    Object.freeze(bundle.controlKinds)
+    Object.freeze(bundle.scenario)
+    Object.freeze(bundle.blindness)
+    Object.freeze(bundle)
+  }
+  Object.freeze(record.bundles)
+  // The guard graph: advisory orderings, unclassified findings, and their nested arrays.
+  for (const ordering of record.guard.advisory) {
+    Object.freeze(ordering.bestToWorst)
+    Object.freeze(ordering)
+  }
+  Object.freeze(record.guard.advisory)
+  for (const finding of record.guard.unclassifiedFindings) {
+    Object.freeze(finding.timestamps)
+    Object.freeze(finding)
+  }
+  Object.freeze(record.guard.unclassifiedFindings)
+  Object.freeze(record.guard)
+  Object.freeze(record.provider)
+  Object.freeze(record)
+}
+
+function timestampForPath(clock: Date): string {
+  if (Number.isNaN(clock.valueOf()))
+    throw new OracleRunRecordError('clock returned an invalid date')
+  // Second precision for EVERY clock value: a live clock virtually always carries nonzero
+  // milliseconds, and the record path contract is YYYY-MM-DDTHH-MM-SSZ.json (oracle-runs/README).
+  return clock
+    .toISOString()
+    .replaceAll(':', '-')
+    .replace(/\.\d{3}Z$/, 'Z')
+}
+
+/** Canonical dated path plus JSON bytes; caller owns the filesystem write and supplies the clock. */
+export function serializeOracleRunRecord(
+  record: OracleRunRecord,
+  clock: Date,
+): OracleRunRecordFile {
+  if (!builtRecords.has(record)) {
+    throw new OracleRunRecordError('record was not produced by buildOracleRunRecord')
+  }
+  const timestamp = timestampForPath(clock)
+  return {
+    path: `${ORACLE_RUNS_DIRECTORY}/${timestamp}.json`,
+    content: `${JSON.stringify(record, null, 2)}\n`,
+  }
+}