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

package/src/index.ts

@@ -0,0 +1,144 @@
+// Public surface of the conformance harness: the engine-agnostic scenario format, the two engine
+// adapters, the runner, and the pure cross-engine comparator. No host dependencies leak here — the
+// package's only engine imports are the core (native, under test) and pinned motion-dom (the oracle).
+
+export type {
+  Capability,
+  MotionScalar,
+  Scenario,
+  SpringKind,
+  SpringScenario,
+  SpringTrajectorySpec,
+  TimelineStep,
+  ToleranceBand,
+  ValueTypeScenario,
+} from './scenario'
+export { CORE_SCENARIOS } from './scenario'
+export { SPRING_SCENARIOS } from './scenarios/spring'
+export { VALUE_TYPE_SCENARIOS } from './scenarios/value-types'
+export type { EngineAdapter, EngineValue, TrajectoryPoint } from './adapter'
+export { nativeAdapter } from './adapters/native'
+export { motionDomAdapter } from './adapters/motion-dom'
+export type { Reading, ScenarioResult, Verdict } from './runner'
+export { runScenario, runSpringScenario, runValueTypeScenario, scalarWithin } from './runner'
+export type { CrossEngineMismatch, CrossEngineResult } from './comparator'
+export { compareEngines, compareValueTypeSeries } from './comparator'
+export type { SuiteResult } from './suite'
+export { aggregateSuite } from './suite'
+export { DEFAULT_BAND, SPRING_BAND } from './config'
+
+// SPEC-UNIVERSAL-SUBSET authoring gate (REQ-SUBSET-018): the registry as the scenario capability
+// whitelist + web-altitude routing. Rejects unknown/off-host capabilities at author time (fail-closed).
+export type { AuthoredScenario, AuthoredTargets, WebAltitude } from './authoring'
+export { authorScenario, webAltitudeFor } from './authoring'
+
+// SPEC-COMPONENT Altitude-2 boundary scenarios (REQ-API-001/002/005/006): first-paint, initial={false},
+// partial-hold, and fail-loud validation, run against the fake host at M1 and both engines at M2.
+// EXCEPTIONS — CMP-R7/CMP-R8/CMP-R9-cross-engine-parity (REQ-API-032/033/034, REQ-CONFORM-002):
+// parity is BETWEEN engines, so no single host asserts it. All three rows stay permanently
+// `unassertable`: R7 is discharged by variants.e2e.ts + PROOF.md §R7; R8 by keyframes.e2e.ts +
+// PROOF.md §R8 device keyframes card; R9 by examples.smoke/text-layout/image-gallery e2e
+// (Chromium 22/22) + PROOF.md §R9 device element cards. None flip to an in-suite pass
+// (R7 M5, ratified Option A — SPEC-CONFORMANCE §3).
+export type { ComponentScenario } from './scenarios/component'
+export { COMPONENT_SCENARIOS, runComponentScenario } from './scenarios/component'
+
+export type { DriverScenario } from './scenarios/driver'
+export { DRIVER_SCENARIOS, runDriverScenario } from './scenarios/driver'
+
+export type { PresenceScenario } from './scenarios/presence'
+export { PRESENCE_SCENARIOS, runPresenceScenario } from './scenarios/presence'
+
+export type { GestureScenario } from './scenarios/gesture'
+export { GESTURE_SCENARIOS, runGestureScenario } from './scenarios/gesture'
+
+export type { LayoutScenario } from './scenarios/layout'
+export { LAYOUT_SCENARIOS, runLayoutScenario } from './scenarios/layout'
+
+export type { LayoutIdentityScenario } from './scenarios/layout-identity'
+export { LAYOUT_IDENTITY_SCENARIOS, runLayoutIdentityScenario } from './scenarios/layout-identity'
+
+// Cross-engine parity seam (REQ-CONFORM-002, additive): lets a real second engine OWN the
+// `*.cross-engine-parity` scenarios via the aggregator's ownership rule. The web engine is
+// injected as a narrow interface; the comparison and band live here (REQ-WEB-017).
+export type { GestureParityCase, GestureWebEngine } from './parity'
+export {
+  GESTURE_ENDPOINT_BAND,
+  GESTURE_PARITY_CASES,
+  GESTURE_PARITY_SCENARIO_ID,
+  LAYOUT_PARITY_COUNTERPART,
+  LAYOUT_PARITY_SCENARIO_ID,
+  referenceReleaseEndpoint,
+  LAYOUT_IDENTITY_PARITY_COUNTERPART,
+  runGestureParityScenario,
+} from './parity'
+export type { AppstoreChoreographyScenario } from './scenarios/appstore-choreography'
+export {
+  APPSTORE_CHOREOGRAPHY_SCENARIOS,
+  runAppstoreChoreographyScenario,
+} from './scenarios/appstore-choreography'
+
+// M2.7 oracle M1 trajectory exporter (REQ-ORACLE-004) — minimal surface for phases 2–4 + tests.
+export type {
+  OracleEngine,
+  OracleRealTrace,
+  OracleTrace,
+  SubjectiveSliceId,
+  TraceEvent,
+  TraceEventKind,
+  TraceRow,
+  VelocityProvenance,
+} from './oracle'
+export {
+  SUBJECTIVE_SLICE_IDS,
+  ORACLE_FRAME_MS,
+  createJudgeBundle,
+  exportTrace,
+  exportTraceRun,
+  serializeTrace,
+  serializeJudgeBundle,
+  isSubjectiveSliceId,
+} from './oracle'
+export type {
+  OracleJudgeBundle,
+  OraclePresentation,
+  OracleUnblindingEntry,
+  OracleUnblindingRecord,
+} from './oracle'
+export type { OracleTraceAttestationRegistry, OracleTraceRun } from './oracle'
+export type {
+  JudgeDispatchOutcome,
+  JudgeVerdictOutcome,
+  JudgeProvider,
+  JudgeProviderConfig,
+  OracleAdvisoryOrdering,
+  OracleGuardInput,
+  OracleGuardOutcome,
+  OracleJudgeDimension,
+  OracleJudgeDimensionVerdict,
+  OracleJudgeIssue,
+  OracleJudgeValue,
+  OracleJudgeVerdict,
+  OracleUnclassifiedFinding,
+  OracleRunBundleInput,
+  OracleRunBundleRecord,
+  OracleRunInputs,
+  OracleRunRecord,
+  OracleRunRecordFile,
+} from './oracle'
+export {
+  buildOracleRunRecord,
+  createCliJudgeProvider,
+  createIsolatedJudgeSpawnOptions,
+  DEFAULT_JUDGE_PROVIDER_CONFIG,
+  decideOracleGuard,
+  dispatchJudge,
+  judgeBundle,
+  OracleJudgeError,
+  ORACLE_JUDGE_DIMENSIONS,
+  ORACLE_JUDGE_VALUES,
+  ORACLE_RUNS_DIRECTORY,
+  OracleRunRecordError,
+  parseJudgeVerdict,
+  serializeOracleRunRecord,
+} from './oracle'

package/src/oracle/attestation.ts

@@ -0,0 +1,100 @@
+// Exporter-issued trace attestations. A registry is created for one run and passed with that run;
+// no process-global registry can accidentally admit a trace from a different run.
+
+import { OracleTraceError } from './errors'
+import { serializeTrace } from './serialize'
+import type { OracleRealTrace, OracleTrace } from './types'
+
+const traceAttestation = Symbol('oracle trace attestation')
+
+type TraceAttestation = {
+  readonly registry: OracleTraceAttestationRegistry
+  readonly hash: string
+}
+
+export interface OracleTraceAttestationRegistry {
+  /** The content hashes issued by the exporter during this run, in deterministic insertion order. */
+  readonly traceHashes: readonly string[]
+}
+
+class RunTraceAttestationRegistry implements OracleTraceAttestationRegistry {
+  readonly #hashes = new Set<string>()
+
+  get traceHashes(): readonly string[] {
+    return [...this.#hashes]
+  }
+
+  register(hash: string): void {
+    this.#hashes.add(hash)
+  }
+
+  contains(hash: string): boolean {
+    return this.#hashes.has(hash)
+  }
+}
+
+/** A fixed 64-bit FNV-1a content hash, deliberately host-crypto independent. */
+export function oracleContentHash(content: string): string {
+  let hash = 0xcbf29ce484222325n
+  for (let index = 0; index < content.length; index += 1) {
+    hash ^= BigInt(content.charCodeAt(index))
+    hash = BigInt.asUintN(64, hash * 0x100000001b3n)
+  }
+  return hash.toString(16).padStart(16, '0')
+}
+
+export function createOracleTraceAttestationRegistry(): OracleTraceAttestationRegistry {
+  return new RunTraceAttestationRegistry()
+}
+
+function mutableRegistry(registry: OracleTraceAttestationRegistry): RunTraceAttestationRegistry {
+  if (!(registry instanceof RunTraceAttestationRegistry)) {
+    throw new OracleTraceError('attestation', 'registry was not issued by the oracle exporter')
+  }
+  return registry
+}
+
+function attestationOf(trace: OracleTrace): TraceAttestation | undefined {
+  return (trace as OracleTrace & { readonly [traceAttestation]?: TraceAttestation })[
+    traceAttestation
+  ]
+}
+
+/** Registers exactly the canonical bytes the exporter produced and retains that ticket privately. */
+export function attestExportedTrace(
+  trace: OracleTrace,
+  registry: OracleTraceAttestationRegistry,
+): OracleRealTrace {
+  const hash = oracleContentHash(serializeTrace(trace))
+  mutableRegistry(registry).register(hash)
+  Object.defineProperty(trace, traceAttestation, {
+    configurable: false,
+    enumerable: false,
+    value: { registry, hash } satisfies TraceAttestation,
+    writable: false,
+  })
+  return trace as OracleRealTrace
+}
+
+/**
+ * Requires the exact exporter-issued trace, not merely an object shaped like one. Spreads and
+ * field stripping intentionally discard the private ticket, so a degraded control cannot re-enter
+ * as a real candidate.
+ */
+export function assertAttestedRealTrace(
+  trace: OracleTrace,
+  context: string,
+): asserts trace is OracleRealTrace {
+  const attestation = attestationOf(trace)
+  if (attestation === undefined) {
+    throw new OracleTraceError(trace.scenarioId, `${context}: trace has no exporter attestation`)
+  }
+  const registry = mutableRegistry(attestation.registry)
+  const actualHash = oracleContentHash(serializeTrace(trace))
+  if (actualHash !== attestation.hash || !registry.contains(actualHash)) {
+    throw new OracleTraceError(
+      trace.scenarioId,
+      `${context}: trace does not match its exporter attestation`,
+    )
+  }
+}

package/src/oracle/constants.ts

@@ -0,0 +1,24 @@
+// Ratified M1 calibration-control constants (M2.7 A5). These are seeded once so oracle
+// calibration stays stable; callers must not tune a defect to make a particular run pass.
+
+/** M1's position-continuity tolerance; C-DISC is deliberately 48 times larger than this. */
+export const ORACLE_CONTROL_POSITION_EPSILON_PX = 0.5
+
+/** C-DISC changes every value at/after its marked boundary by this visible distance. */
+export const ORACLE_CONTROL_DISCONTINUITY_PX = ORACLE_CONTROL_POSITION_EPSILON_PX * 48
+
+/** C-DISC makes the boundary's velocity discontinuity explicit rather than preserving a handoff. */
+export const ORACLE_CONTROL_VELOCITY_RESET = 0
+
+/** C-DISC plants a mid-settle step here when a pure settle has no release or interrupt mark. */
+export const ORACLE_CONTROL_DISC_SETTLE_FRACTION = 0.25
+
+/** Trace timestamps are milliseconds while the public velocity unit is value-units per second. */
+export const ORACLE_CONTROL_MILLISECONDS_PER_SECOND = 1000
+
+/** C-LIN replaces precisely the final boundary-to-end settle segment with an endpoint ramp. */
+export const ORACLE_CONTROL_LINEAR_RAMP_POLICY = {
+  start: 'final-boundary',
+  end: 'trace-end',
+  velocity: 'constant-endpoint-slope',
+} as const

package/src/oracle/controls.ts

@@ -0,0 +1,202 @@
+// M1 planted-defect controls (REQ-ORACLE-006). These are pure trace transforms: the oracle
+// consumes an already-exported real trace and never imports or drives an animation engine.
+
+import {
+  ORACLE_CONTROL_DISC_SETTLE_FRACTION,
+  ORACLE_CONTROL_DISCONTINUITY_PX,
+  ORACLE_CONTROL_MILLISECONDS_PER_SECOND,
+  ORACLE_CONTROL_VELOCITY_RESET,
+} from './constants'
+import { OracleTraceError } from './errors'
+import { assertAttestedRealTrace } from './attestation'
+import { serializeTrace } from './serialize'
+import type { OracleRealTrace, OracleTrace, TraceEvent, TraceRow } from './types'
+
+export const ORACLE_CONTROL_KINDS = ['C-LIN', 'C-DISC'] as const
+export type OracleControlKind = (typeof ORACLE_CONTROL_KINDS)[number]
+
+export function isOracleControlKind(kind: string): kind is OracleControlKind {
+  return (ORACLE_CONTROL_KINDS as readonly string[]).includes(kind)
+}
+
+/** Internal provenance the phase-3 presenter must remove before it constructs a blinded trace. */
+export interface OracleControlMetadata {
+  readonly kind: OracleControlKind
+  readonly derivedFrom: Pick<OracleTrace, 'scenarioId' | 'engine' | 'grid'>
+}
+
+/** A real trace plus its internal-only planted-defect provenance. */
+export type OracleControlTrace = OracleTrace & {
+  readonly control: OracleControlMetadata
+}
+
+/**
+ * The phase-3 blind bundle surface. `never` makes an accidental metadata carry impossible at the
+ * type boundary: a control must be copied into a fresh presenter-owned object before dispatch.
+ */
+export interface BlindedOracleTrace {
+  readonly label: string
+  readonly grid: OracleTrace['grid']
+  readonly rows: readonly TraceRow[]
+  readonly eventTimes: readonly TraceEvent[]
+  readonly scenarioId?: never
+  readonly velocityProvenance?: never
+  readonly engine?: never
+  readonly control?: never
+}
+
+type LinearControlSegment = {
+  readonly start: number
+  readonly startRow: TraceRow
+  readonly endRow: TraceRow
+  readonly durationMs: number
+}
+
+function controlError(
+  trace: OracleTrace,
+  kind: OracleControlKind,
+  message: string,
+): OracleTraceError {
+  return new OracleTraceError(trace.scenarioId, `${kind}: ${message}`)
+}
+
+function findFinalBoundary(trace: OracleTrace): TraceEvent | undefined {
+  for (let index = trace.eventTimes.length - 1; index >= 0; index -= 1) {
+    const event = trace.eventTimes[index]
+    if (
+      event?.kind === 'animation-start' ||
+      event?.kind === 'release' ||
+      event?.kind === 'interrupt'
+    ) {
+      return event
+    }
+  }
+  return undefined
+}
+
+/** Returns the final control boundary's row, or undefined when the trace cannot support controls. */
+function finalBoundaryIndex(trace: OracleTrace): number | undefined {
+  const boundary = findFinalBoundary(trace)
+  if (boundary === undefined) return undefined
+  const index = trace.rows.findIndex((row) => row.t === boundary.t)
+  return index < 0 ? undefined : index
+}
+
+/** The exact C-LIN precondition, shared by eligibility selection and injection. */
+function linearControlSegment(trace: OracleTrace): LinearControlSegment | undefined {
+  const start = finalBoundaryIndex(trace)
+  if (start === undefined || trace.rows.length - start < 3) return undefined
+  const startRow = trace.rows[start]
+  const endRow = trace.rows.at(-1)
+  if (startRow === undefined || endRow === undefined) return undefined
+  const durationMs = endRow.t - startRow.t
+  if (durationMs <= 0) return undefined
+  return { start, startRow, endRow, durationMs }
+}
+
+/** A gesture seam takes precedence; pure settles receive the ratified 25%-of-settle defect. */
+function discontinuityControlIndex(trace: OracleTrace): number | undefined {
+  for (let index = trace.eventTimes.length - 1; index >= 0; index -= 1) {
+    const event = trace.eventTimes[index]
+    if (event?.kind === 'release' || event?.kind === 'interrupt') {
+      const mark = trace.rows.findIndex((row) => row.t === event.t)
+      return mark < 1 ? undefined : mark
+    }
+  }
+
+  const start = finalBoundaryIndex(trace)
+  if (start === undefined) return undefined
+  const end = trace.rows.length - 1
+  const index = Math.round(start + (end - start) * ORACLE_CONTROL_DISC_SETTLE_FRACTION)
+  if (index <= start || index > end) {
+    return undefined
+  }
+  return index
+}
+
+/**
+ * Derives the controls a frozen trace can actually support. The presenter must use this exact
+ * predicate instead of assuming every calibration control applies to every scenario slice.
+ */
+export function eligibleOracleControlKinds(trace: OracleTrace): readonly OracleControlKind[] {
+  const kinds: OracleControlKind[] = []
+  if (discontinuityControlIndex(trace) !== undefined) kinds.push('C-DISC')
+  if (linearControlSegment(trace) !== undefined) kinds.push('C-LIN')
+  return kinds
+}
+
+function controlMetadata(trace: OracleTrace, kind: OracleControlKind): OracleControlMetadata {
+  return {
+    kind,
+    derivedFrom: { scenarioId: trace.scenarioId, engine: trace.engine, grid: trace.grid },
+  }
+}
+
+/** Casts and field stripping cannot make a planted defect a real source; attestation is the gate. */
+function assertRealTraceInput(trace: OracleRealTrace, kind: OracleControlKind): void {
+  assertAttestedRealTrace(trace, `${kind} control source`)
+}
+
+/**
+ * Replaces the final boundary-to-end segment with a constant-velocity endpoint ramp.
+ * Values at both endpoints are deliberately assigned directly, not recomputed, so they remain
+ * exactly equal to the real trace despite floating-point interpolation rounding.
+ */
+export function injectLinearControl(trace: OracleRealTrace): OracleControlTrace {
+  assertRealTraceInput(trace, 'C-LIN')
+  // Reuse phase 1's fail-closed numeric validation before deriving a control from these samples.
+  serializeTrace(trace)
+  const segment = linearControlSegment(trace)
+  if (segment === undefined) {
+    throw controlError(trace, 'C-LIN', 'settle segment is too short for a linear ramp')
+  }
+  const { start, startRow, endRow, durationMs } = segment
+  const velocity =
+    ((endRow.value - startRow.value) / durationMs) * ORACLE_CONTROL_MILLISECONDS_PER_SECOND
+
+  return {
+    ...trace,
+    rows: trace.rows.map((row, index) => {
+      if (index < start) return row
+      if (index === start) return { ...row, value: startRow.value, velocity }
+      if (index === trace.rows.length - 1) return { ...row, value: endRow.value, velocity }
+      const progress = (row.t - startRow.t) / durationMs
+      return {
+        ...row,
+        value: startRow.value + (endRow.value - startRow.value) * progress,
+        velocity,
+      }
+    }),
+    control: controlMetadata(trace, 'C-LIN'),
+  }
+}
+
+/**
+ * Plants a visible position step at the final release/interrupt mark. A gesture-less pure settle
+ * gets the same defect at its ratified fractional grid row. The mark receives the velocity reset;
+ * subsequent rows retain their observed velocity so the control differs only at the planted seam.
+ */
+export function injectDiscontinuityControl(trace: OracleRealTrace): OracleControlTrace {
+  assertRealTraceInput(trace, 'C-DISC')
+  serializeTrace(trace)
+  const mark = discontinuityControlIndex(trace)
+  if (mark === undefined) {
+    throw controlError(trace, 'C-DISC', 'requires a usable boundary mark and prior trace row')
+  }
+
+  return {
+    ...trace,
+    rows: trace.rows.map((row, index) => {
+      if (index < mark) return row
+      if (index === mark) {
+        return {
+          ...row,
+          value: row.value + ORACLE_CONTROL_DISCONTINUITY_PX,
+          velocity: ORACLE_CONTROL_VELOCITY_RESET,
+        }
+      }
+      return { ...row, value: row.value + ORACLE_CONTROL_DISCONTINUITY_PX }
+    }),
+    control: controlMetadata(trace, 'C-DISC'),
+  }
+}

package/src/oracle/errors.ts

@@ -0,0 +1,12 @@
+// Typed fail-loud errors for the oracle trace exporter. Every throw names the slice so a
+// budget overrun or empty sweep is never a silent empty artifact.
+
+export class OracleTraceError extends Error {
+  readonly sliceId: string
+
+  constructor(sliceId: string, message: string) {
+    super(`oracle trace [${sliceId}]: ${message}`)
+    this.name = 'OracleTraceError'
+    this.sliceId = sliceId
+  }
+}

package/src/oracle/exportTrace.ts

@@ -0,0 +1,134 @@
+// Public entry: export a frame-swept oracle trace for one subjective slice (M2.7 phase 1 / A1).
+// The five gesture slices are native-only. SHEET-01 joins both engines through the existing dense
+// spring-trajectory adapter seam; no new host gesture machinery is introduced here.
+
+import { OracleTraceError } from './errors'
+import {
+  attestExportedTrace,
+  createOracleTraceAttestationRegistry,
+  type OracleTraceAttestationRegistry,
+} from './attestation'
+import { exportGestureTrace, isGestureSliceId } from './scripts/gesture'
+import { nativeAdapter } from '../adapters/native'
+import { motionDomAdapter } from '../adapters/motion-dom'
+import { SPRING_SCENARIOS } from '../scenarios/spring'
+import {
+  isSubjectiveSliceId,
+  isOracleEngine,
+  ORACLE_ENGINES,
+  type OracleEngine,
+  type OracleRealTrace,
+  type OracleTrace,
+  type SubjectiveSliceId,
+} from './types'
+
+const SHEET_01_SLICE_ID = 'sheet.open-to-snap'
+const SHEET_01_TRAJECTORY = SPRING_SCENARIOS.find((scenario) => scenario.id === 'SPRING-critical')
+function exportSheet01SpringTrace(engine: OracleEngine): OracleTrace {
+  const scenario = SHEET_01_TRAJECTORY
+  if (scenario === undefined) {
+    throw new OracleTraceError(SHEET_01_SLICE_ID, 'missing reused SPRING-critical trajectory spec')
+  }
+  const adapter = engine === 'native-core' ? nativeAdapter() : motionDomAdapter()
+  if (adapter.sampleTrajectory === undefined) {
+    throw new OracleTraceError(SHEET_01_SLICE_ID, `${engine} has no spring-trajectory seam`)
+  }
+  const samples = adapter.sampleTrajectory(scenario.kind, scenario.spec, scenario.tGrid)
+  const firstSample = samples[0]
+  if (firstSample === undefined) {
+    throw new OracleTraceError(SHEET_01_SLICE_ID, `${engine} returned an empty spring trajectory`)
+  }
+  return {
+    scenarioId: SHEET_01_SLICE_ID,
+    engine,
+    grid: 'fixed-60fps',
+    rows: samples.map(({ t, value, velocity }) => ({ t, value, velocity })),
+    // A gesture-less spring has no release/interrupt seam. Mark its animation origin explicitly
+    // so the calibration controls share the same boundary vocabulary as gesture traces.
+    eventTimes: [{ t: firstSample.t, kind: 'animation-start' }],
+    velocityProvenance: 'engine',
+  }
+}
+
+function exportTraceInto(
+  scenarioId: SubjectiveSliceId | string,
+  registry: OracleTraceAttestationRegistry,
+  engine: OracleEngine = 'native-core',
+): OracleRealTrace {
+  if (!isSubjectiveSliceId(scenarioId)) {
+    throw new OracleTraceError(String(scenarioId), `unknown subjective slice id`)
+  }
+
+  if (!isOracleEngine(engine)) {
+    throw new OracleTraceError(
+      scenarioId,
+      `unsupported engine '${String(engine)}'; allowed: ${ORACLE_ENGINES.join(', ')}`,
+    )
+  }
+
+  if (scenarioId === SHEET_01_SLICE_ID) {
+    return attestExportedTrace(exportSheet01SpringTrace(engine), registry)
+  }
+
+  if (engine === 'motion-dom') {
+    // Dense web gesture sweeps would require forbidden new machinery; only SHEET-01 has its seam.
+    throw new OracleTraceError(
+      scenarioId,
+      `motion-dom trace deferred — no deterministic M1 frame-sweep seam for this gesture slice`,
+    )
+  }
+
+  if (engine !== 'native-core') {
+    throw new OracleTraceError(scenarioId, `unsupported engine '${String(engine)}'`)
+  }
+
+  if (isGestureSliceId(scenarioId)) {
+    const { rows, eventTimes, velocityProvenance } = exportGestureTrace(scenarioId)
+    return attestExportedTrace(
+      {
+        scenarioId,
+        engine: 'native-core',
+        grid: 'fixed-60fps',
+        rows,
+        eventTimes,
+        velocityProvenance,
+      },
+      registry,
+    )
+  }
+
+  throw new OracleTraceError(scenarioId, 'slice registered but no exporter branch')
+}
+
+/** Exports one trace in its own run-scoped registry for focused callers and unit tests. */
+export function exportTrace(
+  scenarioId: SubjectiveSliceId | string,
+  engine: OracleEngine = 'native-core',
+): OracleRealTrace {
+  return exportTraceInto(scenarioId, createOracleTraceAttestationRegistry(), engine)
+}
+
+export interface OracleTraceRun {
+  readonly realTraces: readonly OracleRealTrace[]
+  readonly attestations: OracleTraceAttestationRegistry
+}
+
+/**
+ * Exports every candidate for a judge run into one registry. Gesture slices have their available
+ * native trace; SHEET-01 deliberately contributes both existing trajectory seams.
+ */
+export function exportTraceRun(sliceIds: readonly SubjectiveSliceId[]): OracleTraceRun {
+  const attestations = createOracleTraceAttestationRegistry()
+  const realTraces: OracleRealTrace[] = []
+  for (const sliceId of sliceIds) {
+    if (sliceId === SHEET_01_SLICE_ID) {
+      realTraces.push(
+        exportTraceInto(sliceId, attestations, 'native-core'),
+        exportTraceInto(sliceId, attestations, 'motion-dom'),
+      )
+    } else {
+      realTraces.push(exportTraceInto(sliceId, attestations, 'native-core'))
+    }
+  }
+  return { realTraces, attestations }
+}