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

package/src/oracle/scenarios.ts

@@ -0,0 +1,115 @@
+// Reviewed, provenance-clean judge-visible scenario text. The presenter accepts only these slice
+// identifiers; callers never supply prose that could disclose a source path or alter the prompt.
+
+import { SUBJECTIVE_SLICE_IDS, type OracleTrace, type SubjectiveSliceId } from './types'
+
+export const ORACLE_TRACE_SPANS = ['ends-mid-active', 'ends-at-release', 'settles'] as const
+export type OracleTraceSpan = (typeof ORACLE_TRACE_SPANS)[number]
+
+/** Table-linted words that would promise unseen post-boundary motion in a truncated trace. */
+export const ORACLE_NON_SETTLE_CLAIM_WORDS = [
+  'settle',
+  'settling',
+  'continue',
+  'continuation',
+] as const
+
+const NON_SETTLE_CLAIM_PATTERN = new RegExp(
+  `\\b(?:${ORACLE_NON_SETTLE_CLAIM_WORDS.join('|')})\\b`,
+  'i',
+)
+const TRAILING_SENTENCE_PUNCTUATION = /[.!?]$/
+const SETTLED_TAIL_VALUE_EPSILON = 0.001
+const SETTLED_TAIL_VELOCITY_EPSILON = 0.001
+
+export interface OracleScenarioConstant {
+  readonly scenarioName: string
+  readonly expectedInteraction: string
+  readonly criticalMoment: string
+  /** The frozen trace's real terminal state, independently derived in the scenario-table test. */
+  readonly traceSpan: OracleTraceSpan
+}
+
+export const ORACLE_SCENARIOS = {
+  'gesture.grab-during-animation': {
+    scenarioName: 'Sheet grab during motion',
+    expectedInteraction: 'Grab the moving sheet and re-grab it during motion',
+    criticalMoment: 'the mid-motion re-grab boundary',
+    traceSpan: 'ends-mid-active',
+  },
+  'gesture.velocity-handoff': {
+    scenarioName: 'Sheet velocity handoff',
+    expectedInteraction: 'Fling the sheet through the release handoff',
+    criticalMoment: 'the release handoff',
+    traceSpan: 'ends-at-release',
+  },
+  'gesture.release-seam': {
+    scenarioName: 'Sheet release seam',
+    expectedInteraction: 'Release the sheet at the continuity seam',
+    criticalMoment: 'the release boundary',
+    traceSpan: 'ends-at-release',
+  },
+  'gesture.settle-accounting': {
+    scenarioName: 'Sheet settle after release',
+    expectedInteraction: 'Release the sheet and observe its settle to the target',
+    criticalMoment: 'the final approach to the target',
+    traceSpan: 'settles',
+  },
+  'gesture.hold-then-release': {
+    scenarioName: 'Sheet hold then release',
+    expectedInteraction: 'Hold the sheet still, then release it to settle',
+    criticalMoment: 'the transition from the hold to release',
+    traceSpan: 'settles',
+  },
+  'sheet.open-to-snap': {
+    scenarioName: 'Sheet opens to snap',
+    expectedInteraction: 'Observe the sheet spring to its open snap point',
+    criticalMoment: 'the start and final settle of the spring',
+    traceSpan: 'settles',
+  },
+} as const satisfies Readonly<Record<SubjectiveSliceId, OracleScenarioConstant>>
+
+/**
+ * Derives the trace terminal state from its frozen event sequence and observable settled tail.
+ * No slice identifier participates, so a script and its reviewed prose cannot silently drift apart.
+ */
+export function deriveOracleTraceSpan(trace: OracleTrace): OracleTraceSpan {
+  const final = trace.rows.at(-1)
+  const penultimate = trace.rows.at(-2)
+  if (
+    final !== undefined &&
+    penultimate !== undefined &&
+    Math.abs(final.value - penultimate.value) <= SETTLED_TAIL_VALUE_EPSILON &&
+    Math.abs(final.velocity) <= SETTLED_TAIL_VELOCITY_EPSILON &&
+    Math.abs(penultimate.velocity) <= SETTLED_TAIL_VELOCITY_EPSILON
+  ) {
+    return 'settles'
+  }
+
+  return trace.eventTimes.at(-1)?.kind === 'release' ? 'ends-at-release' : 'ends-mid-active'
+}
+
+/** Keeps prompt fills single-punctuated and forbids truncated traces from promising a settle. */
+export function assertOracleScenarioTableText(): void {
+  for (const sliceId of SUBJECTIVE_SLICE_IDS) {
+    const scenario = ORACLE_SCENARIOS[sliceId]
+    if (TRAILING_SENTENCE_PUNCTUATION.test(scenario.expectedInteraction)) {
+      throw new Error(`${sliceId}: expectedInteraction owns no trailing punctuation`)
+    }
+    if (
+      scenario.traceSpan !== 'settles' &&
+      [scenario.expectedInteraction, scenario.criticalMoment].some((text) =>
+        NON_SETTLE_CLAIM_PATTERN.test(text),
+      )
+    ) {
+      throw new Error(`${sliceId}: non-settling trace description promises unseen motion`)
+    }
+  }
+}
+
+// Closed reviewed constants are rejected at module initialization before a prompt can be assembled.
+assertOracleScenarioTableText()
+
+export function scenarioForSlice(sliceId: SubjectiveSliceId): OracleScenarioConstant {
+  return ORACLE_SCENARIOS[sliceId]
+}

package/src/oracle/scripts/gesture.ts

@@ -0,0 +1,218 @@
+// Gesture subjective-slice scripts — replay the authored inputs from
+// packages/conformance/src/scenarios/gesture.ts exactly. The fixed grid only controls sampling;
+// it never authorizes synthetic inputs or completion after a source scenario has ended.
+
+import {
+  ManualClock,
+  ManualScheduler,
+  createGestureSession,
+  createMotionGraph,
+  type GestureSession,
+} from '@unrulysystems/native-motion-core'
+import { OracleTraceError } from '../errors'
+import { runFrameSweep, type SweepApi } from '../sweep'
+import type { SubjectiveSliceId, TraceEvent, TraceRow, VelocityProvenance } from '../types'
+import { finiteDiffVelocity } from '../velocity'
+
+type SessionOpts = Omit<Parameters<typeof createGestureSession>[0], 'graph'>
+type GestureSliceId = Extract<SubjectiveSliceId, `gesture.${string}`>
+type GestureSample = Parameters<GestureSession['active']>[0]
+
+/** The source-scenario inputs consumed by the exporter, retained solely for replay verification. */
+export type ReplayedGestureInput =
+  | { readonly kind: 'begin'; readonly activationTranslation: number }
+  | { readonly kind: 'active' | 'end'; readonly sample: GestureSample }
+  | { readonly kind: 'frames'; readonly count: number }
+
+interface GestureScript {
+  readonly opts: SessionOpts
+  readonly drive: (replay: GestureReplay) => void
+}
+
+/** Test seam for observing the engine/generator; production samples the real session directly. */
+export interface GestureTraceOptions {
+  readonly sampleEngineVelocity?: (session: GestureSession) => number
+}
+
+/** Applies authored inputs while keeping the exact source sequence observable to the contract test. */
+class GestureReplay {
+  readonly #inputs: ReplayedGestureInput[] = []
+
+  constructor(
+    private readonly session: GestureSession,
+    private readonly scheduler: ManualScheduler,
+    private readonly api: SweepApi,
+  ) {}
+
+  get inputs(): readonly ReplayedGestureInput[] {
+    return this.#inputs
+  }
+
+  begin(activationTranslation: number, mark: 'begin' | 'interrupt'): void {
+    this.#inputs.push({ kind: 'begin', activationTranslation })
+    if (mark === 'interrupt') {
+      // Re-grab stops the generator. Record its last live engine velocity on the pre-seam side;
+      // the first gesture-active row then finite-differences ACROSS the seam against that
+      // adjacent exported value (A7), so real value motion is observed, never reset to a
+      // fabricated 0 (review 5in4om m3d124b45a58c).
+      this.api.sampleBeforeBoundary()
+      this.api.mark(mark)
+      this.session.begin(activationTranslation)
+      return
+    }
+    this.api.mark(mark)
+    this.session.begin(activationTranslation)
+    this.api.sample()
+  }
+
+  active(sample: GestureSample, mark?: 'active-start'): void {
+    this.#inputs.push({ kind: 'active', sample })
+    if (mark !== undefined) this.api.mark(mark)
+    this.session.active(sample)
+    this.api.sample()
+  }
+
+  end(sample: GestureSample): void {
+    this.#inputs.push({ kind: 'end', sample })
+    this.api.mark('release')
+    this.session.end(sample)
+    // The first generator sample is at t=0. Pump it without advancing wall time so the release
+    // row observes the engine's seeded velocity rather than a recognizer input or a later decay.
+    this.scheduler.frame(0)
+    this.api.sample()
+  }
+
+  advance(): void {
+    this.api.advance()
+  }
+
+  frameIndex(): number {
+    return this.api.frameIndex()
+  }
+
+  frames(count: number): void {
+    this.#inputs.push({ kind: 'frames', count })
+    for (let i = 0; i < count; i++) {
+      this.api.advance()
+      this.api.sample()
+    }
+  }
+}
+
+const SCRIPTS: Record<GestureSliceId, GestureScript> = {
+  // scenarios/gesture.ts:67 — source ends during the re-grab; do not manufacture a release.
+  'gesture.grab-during-animation': {
+    opts: { snap: { points: [0, 300, 600] } },
+    drive(replay) {
+      replay.begin(0, 'begin')
+      replay.advance()
+      replay.active({ t: 16, translation: 200, velocity: 2000 }, 'active-start')
+      replay.advance()
+      replay.end({ t: 32, translation: 200, velocity: 2000 })
+      replay.frames(3)
+      replay.begin(1000, 'interrupt')
+      replay.advance()
+      replay.active({ t: 64, translation: 1050, velocity: 0 })
+    },
+  },
+  // scenarios/gesture.ts:87 — one authored post-release frame proves the generator direction.
+  'gesture.velocity-handoff': {
+    opts: { initial: 0, snap: { points: [0, 1600, 3200] } },
+    drive(replay) {
+      replay.begin(0, 'begin')
+      replay.advance()
+      replay.active({ t: 16, translation: 0, velocity: 2000 }, 'active-start')
+      replay.advance()
+      replay.end({ t: 32, translation: 0, velocity: 2000 })
+      replay.frames(1)
+    },
+  },
+  // scenarios/gesture.ts:103 — the source judges the release boundary itself, with no tail.
+  'gesture.release-seam': {
+    opts: { initial: 0, snap: { points: [0, 1600] } },
+    drive(replay) {
+      replay.begin(0, 'begin')
+      replay.advance()
+      replay.active({ t: 16, translation: 30, velocity: 1800 }, 'active-start')
+      replay.advance()
+      replay.active({ t: 32, translation: 60, velocity: 1800 })
+      replay.advance()
+      replay.end({ t: 48, translation: 60, velocity: 1800 })
+    },
+  },
+  // scenarios/gesture.ts:187 — retain its authored settle-accounting frame span exactly.
+  'gesture.settle-accounting': {
+    opts: { initial: 0, snap: { points: [0, 300] } },
+    drive(replay) {
+      replay.begin(0, 'begin')
+      replay.advance()
+      replay.active({ t: 16, translation: 100, velocity: 500 }, 'active-start')
+      replay.advance()
+      replay.end({ t: 32, translation: 100, velocity: 500 })
+      replay.frames(400)
+    },
+  },
+  // scenarios/gesture.ts:223 — no invented active samples while the finger is held still.
+  'gesture.hold-then-release': {
+    opts: { initial: 0, snap: { points: [0, 300, 600] } },
+    drive(replay) {
+      replay.begin(0, 'begin')
+      replay.advance()
+      replay.active({ t: 16, translation: 250, velocity: 500 }, 'active-start')
+      while (replay.frameIndex() < 12) replay.advance()
+      replay.end({ t: 200, translation: 250, velocity: 0 })
+      replay.frames(300)
+    },
+  },
+}
+
+export function exportGestureTrace(
+  sliceId: GestureSliceId,
+  options: GestureTraceOptions = {},
+): {
+  rows: TraceRow[]
+  eventTimes: TraceEvent[]
+  velocityProvenance: VelocityProvenance
+  replayedInputs: readonly ReplayedGestureInput[]
+} {
+  const script = SCRIPTS[sliceId]
+  if (script === undefined) throw new OracleTraceError(sliceId, 'no gesture script registered')
+
+  const clock = new ManualClock(0)
+  const scheduler = new ManualScheduler(clock)
+  const graph = createMotionGraph({ clock, scheduler })
+  const session = createGestureSession({ graph, ...script.opts })
+  const sampleEngineVelocity = options.sampleEngineVelocity ?? ((s) => s.velocity())
+  let replay: GestureReplay | undefined
+
+  const { rows, eventTimes } = runFrameSweep(
+    sliceId,
+    scheduler,
+    {
+      sample: (t, previous) => {
+        const value = session.value()
+        // A recognizer sample is an input, never an observation. While the finger is down the
+        // exported value is the only observable series, so derive its velocity from adjacent rows.
+        const velocity =
+          session.state() === 'active'
+            ? finiteDiffVelocity(previous, { t, value }, sliceId)
+            : sampleEngineVelocity(session)
+        return { value, velocity }
+      },
+      isSettled: () => session.isSettled(),
+    },
+    (api) => {
+      replay = new GestureReplay(session, scheduler, api)
+      script.drive(replay)
+    },
+  )
+
+  if (replay === undefined) throw new OracleTraceError(sliceId, 'script did not initialize replay')
+  // Gesture traces include finite-difference rows while active; animation rows remain direct
+  // engine samples. `derived` makes that presentation-only active-segment derivation explicit.
+  return { rows, eventTimes, velocityProvenance: 'derived', replayedInputs: replay.inputs }
+}
+
+export function isGestureSliceId(id: string): id is GestureSliceId {
+  return Object.hasOwn(SCRIPTS, id)
+}

package/src/oracle/serialize.ts

@@ -0,0 +1,91 @@
+// Canonical byte-stable serialization for oracle traces. Stable top-level and nested key order
+// so two independent export runs compare equal as strings (determinism gate).
+
+import { gridTime, type OracleTrace, type TraceEvent, type TraceRow } from './types'
+import { OracleTraceError } from './errors'
+
+function assertFinite(
+  sliceId: string,
+  field: string,
+  value: number,
+  index: number,
+  collection = 'row',
+): void {
+  if (!Number.isFinite(value)) {
+    throw new OracleTraceError(
+      sliceId,
+      `non-finite ${field} at ${collection} ${index}: ${String(value)}`,
+    )
+  }
+}
+
+function validateRows(trace: OracleTrace): void {
+  if (trace.rows.length === 0) {
+    throw new OracleTraceError(trace.scenarioId, 'trace has no grid rows')
+  }
+  for (let index = 0; index < trace.rows.length; index += 1) {
+    if (!(index in trace.rows)) {
+      throw new OracleTraceError(trace.scenarioId, `sparse grid row at index ${index}`)
+    }
+    const row = trace.rows[index]
+    if (row === null || typeof row !== 'object') {
+      throw new OracleTraceError(trace.scenarioId, `invalid grid row at index ${index}`)
+    }
+    assertFinite(trace.scenarioId, 'timestamp', row.t, index)
+    assertFinite(trace.scenarioId, 'value', row.value, index)
+    assertFinite(trace.scenarioId, 'velocity', row.velocity, index)
+    const expected = gridTime(index)
+    if (row.t !== expected) {
+      throw new OracleTraceError(
+        trace.scenarioId,
+        `fixed-60fps grid timestamp ${row.t} does not equal ${expected} at row ${index}`,
+      )
+    }
+  }
+}
+
+function validateEventTimes(trace: OracleTrace): void {
+  for (let index = 0; index < trace.eventTimes.length; index += 1) {
+    if (!(index in trace.eventTimes)) {
+      throw new OracleTraceError(trace.scenarioId, `sparse event mark at index ${index}`)
+    }
+    const event = trace.eventTimes[index]
+    if (event === null || typeof event !== 'object') {
+      throw new OracleTraceError(trace.scenarioId, `invalid event mark at index ${index}`)
+    }
+    assertFinite(trace.scenarioId, 'eventTimes.t', event.t, index, 'event')
+    if (!trace.rows.some((row) => row.t === event.t)) {
+      throw new OracleTraceError(
+        trace.scenarioId,
+        `event mark at ${event.t} is outside the fixed-60fps grid`,
+      )
+    }
+  }
+}
+
+function serializeRow(row: TraceRow): string {
+  // Fixed key order: t, value, velocity
+  return `{"t":${JSON.stringify(row.t)},"value":${JSON.stringify(row.value)},"velocity":${JSON.stringify(row.velocity)}}`
+}
+
+function serializeEvent(ev: TraceEvent): string {
+  return `{"t":${JSON.stringify(ev.t)},"kind":${JSON.stringify(ev.kind)}}`
+}
+
+/** Canonical JSON: fixed key order at every level. Not `JSON.stringify` of a plain object. */
+export function serializeTrace(trace: OracleTrace): string {
+  validateRows(trace)
+  validateEventTimes(trace)
+  const rows = `[${trace.rows.map(serializeRow).join(',')}]`
+  const events = `[${trace.eventTimes.map(serializeEvent).join(',')}]`
+  return (
+    `{` +
+    `"scenarioId":${JSON.stringify(trace.scenarioId)},` +
+    `"engine":${JSON.stringify(trace.engine)},` +
+    `"grid":${JSON.stringify(trace.grid)},` +
+    `"rows":${rows},` +
+    `"eventTimes":${events},` +
+    `"velocityProvenance":${JSON.stringify(trace.velocityProvenance)}` +
+    `}`
+  )
+}

package/src/oracle/sweep.ts

@@ -0,0 +1,155 @@
+// Fixed-60fps frame sweep under ManualClock + ManualScheduler. Bounded budget; fails loud.
+// Protocol: apply inputs at the current grid time → sample once → advance to the next frame.
+
+import type { ManualScheduler } from '@unrulysystems/native-motion-core'
+import { OracleTraceError } from './errors'
+import { ORACLE_FRAME_MS, gridTime, type TraceEvent, type TraceRow } from './types'
+
+/** Max frames for any subjective-slice sweep (~33s at 60fps) — fail loud past this. */
+export const ORACLE_MAX_FRAMES = 2000
+
+/** Frames to keep after settle becomes true (short tail for the judge). */
+export const ORACLE_SETTLE_TAIL_FRAMES = 6
+
+export interface SweepSample {
+  readonly value: number
+  readonly velocity: number
+}
+
+/**
+ * Run a scripted interaction that records events via `mark`, samples via `sample`, and
+ * advances via `advance`. After the script, call `settleSweep` to frame through settle + tail.
+ */
+export function runFrameSweep(
+  sliceId: string,
+  scheduler: ManualScheduler,
+  driver: {
+    sample: (t: number, previous: TraceRow | undefined) => SweepSample
+    isSettled: () => boolean
+  },
+  script: (api: SweepApi) => void,
+): { rows: TraceRow[]; eventTimes: TraceEvent[] } {
+  const rows: TraceRow[] = []
+  const eventTimes: TraceEvent[] = []
+  let frameIndex = 0
+  let settledAtFrame: number | undefined
+  /** True once a row has been written for the current frameIndex (one sample per grid tick). */
+  let sampledThisFrame = false
+
+  const record = (): void => {
+    // A7: gesture-active velocity is the finite difference of ADJACENT exported values, spanning
+    // every seam — a re-grab whose value continues reads its real motion, and a genuine value
+    // jump stays VISIBLE (observe-never-echo) rather than papered over by a fabricated 0.
+    const previous = rows.at(sampledThisFrame ? -2 : -1)
+    if (sampledThisFrame) {
+      // Overwrite the same-frame sample after late inputs on that tick.
+      const s = driver.sample(gridTime(frameIndex), previous)
+      rows[rows.length - 1] = { t: gridTime(frameIndex), value: s.value, velocity: s.velocity }
+      return
+    }
+    const s = driver.sample(gridTime(frameIndex), previous)
+    rows.push({ t: gridTime(frameIndex), value: s.value, velocity: s.velocity })
+    sampledThisFrame = true
+  }
+
+  const noteSettle = (): void => {
+    if (driver.isSettled()) {
+      if (settledAtFrame === undefined) settledAtFrame = frameIndex
+    } else {
+      settledAtFrame = undefined
+    }
+  }
+
+  const api: SweepApi = {
+    frameIndex: () => frameIndex,
+    now: () => gridTime(frameIndex),
+    mark(kind) {
+      eventTimes.push({ t: gridTime(frameIndex), kind })
+    },
+    sample() {
+      record()
+      noteSettle()
+    },
+    sampleBeforeBoundary() {
+      // A later input on this tick must not overwrite the last running-engine observation.
+      if (!sampledThisFrame) {
+        record()
+        noteSettle()
+      }
+    },
+    advance() {
+      if (frameIndex >= ORACLE_MAX_FRAMES) {
+        throw new OracleTraceError(
+          sliceId,
+          `sweep exceeded frame budget (${ORACLE_MAX_FRAMES}) before settle`,
+        )
+      }
+      if (!sampledThisFrame) {
+        // Ensure every frame the script leaves has a sample before advancing.
+        record()
+        noteSettle()
+      }
+      scheduler.frame(ORACLE_FRAME_MS)
+      frameIndex += 1
+      sampledThisFrame = false
+    },
+    settleSweep() {
+      // Ensure the post-script frame is sampled before the settle loop.
+      if (!sampledThisFrame) {
+        record()
+        noteSettle()
+      }
+      while (true) {
+        if (
+          settledAtFrame !== undefined &&
+          frameIndex - settledAtFrame >= ORACLE_SETTLE_TAIL_FRAMES
+        ) {
+          break
+        }
+        if (frameIndex >= ORACLE_MAX_FRAMES) {
+          throw new OracleTraceError(
+            sliceId,
+            `sweep exceeded frame budget (${ORACLE_MAX_FRAMES}) before settle`,
+          )
+        }
+        // Advance and sample the new frame.
+        scheduler.frame(ORACLE_FRAME_MS)
+        frameIndex += 1
+        sampledThisFrame = false
+        record()
+        noteSettle()
+      }
+    },
+  }
+
+  script(api)
+
+  if (rows.length === 0) {
+    throw new OracleTraceError(sliceId, 'empty sweep — script produced no rows')
+  }
+  if (eventTimes.length === 0) {
+    throw new OracleTraceError(
+      sliceId,
+      'empty eventTimes — script marked no interaction boundaries',
+    )
+  }
+
+  return { rows, eventTimes }
+}
+
+export interface SweepApi {
+  /** Current 0-based frame index. */
+  frameIndex: () => number
+  /** Absolute grid time (ms) at the current frame. */
+  now: () => number
+  /** Record an interaction boundary at the current grid time. */
+  mark: (kind: TraceEvent['kind']) => void
+  /** Sample value+velocity at the current grid time (once per frame; re-sample overwrites). */
+  sample: () => void
+  /** Ensure the current frame holds its pre-boundary observation without overwriting it later. */
+  sampleBeforeBoundary: () => void
+  /** Advance one 60fps frame (auto-samples the left frame if the script forgot). */
+  advance: () => void
+  /** Frame-sweep until settled + tail (fail loud on budget). */
+  settleSweep: () => void
+}

package/src/oracle/types.ts

@@ -0,0 +1,76 @@
+// Oracle M1 trajectory trace schema (REQ-ORACLE-004, M2.7 phase 1).
+// Unit-honest public units only: t in ms, value in the animated axis units at px scale,
+// velocity in value-units per second. No internal-unit leaks.
+
+/** Rhymes with `TrajectoryPoint` in adapter.ts — one dense sample on the fixed grid. */
+export interface TraceRow {
+  readonly t: number
+  readonly value: number
+  readonly velocity: number
+}
+
+/** Interaction boundary mark for the §5 prompt's `{{event_times}}` slot. */
+export type TraceEventKind = 'begin' | 'active-start' | 'animation-start' | 'release' | 'interrupt'
+
+export interface TraceEvent {
+  readonly t: number
+  readonly kind: TraceEventKind
+}
+
+/** Engine that produced the trace (presenter strips this before the judge sees it). */
+export const ORACLE_ENGINES = ['native-core', 'motion-dom'] as const
+export type OracleEngine = (typeof ORACLE_ENGINES)[number]
+
+export function isOracleEngine(engine: string): engine is OracleEngine {
+  return (ORACLE_ENGINES as readonly string[]).includes(engine)
+}
+
+/**
+ * Velocity column provenance (adjudication A7).
+ * - `engine`: every row is sampled from the engine/generator.
+ * - `derived`: gesture-active rows are finite-difference observations of the exported value
+ *   series; release, interruption, and settle rows remain sampled from the engine/generator.
+ */
+export type VelocityProvenance = 'engine' | 'derived'
+
+export interface OracleTrace {
+  readonly scenarioId: string
+  readonly engine: OracleEngine
+  readonly grid: 'fixed-60fps'
+  readonly rows: readonly TraceRow[]
+  readonly eventTimes: readonly TraceEvent[]
+  readonly velocityProvenance: VelocityProvenance
+}
+
+/**
+ * An exported trace is the only valid calibration-control source. The phantom symbol prevents a
+ * planted control from being structurally reused as input to another injector.
+ */
+declare const oracleRealTraceBrand: unique symbol
+export type OracleRealTrace = OracleTrace & {
+  readonly [oracleRealTraceBrand]: 'OracleRealTrace'
+}
+
+/** The M1 trajectory slices: five native gesture replays plus the dual-engine SHEET-01 spring. */
+export const SUBJECTIVE_SLICE_IDS = [
+  'gesture.grab-during-animation',
+  'gesture.velocity-handoff',
+  'gesture.release-seam',
+  'gesture.settle-accounting',
+  'gesture.hold-then-release',
+  'sheet.open-to-snap',
+] as const
+
+export type SubjectiveSliceId = (typeof SUBJECTIVE_SLICE_IDS)[number]
+
+export function isSubjectiveSliceId(id: string): id is SubjectiveSliceId {
+  return (SUBJECTIVE_SLICE_IDS as readonly string[]).includes(id)
+}
+
+/** Fixed 60 fps grid step (ms). Matches Motion's 60 fps golden grid (1000/60). */
+export const ORACLE_FRAME_MS = 1000 / 60
+
+/** Absolute grid time for frame index `i` (stable 6-decimal rounding). */
+export function gridTime(frameIndex: number): number {
+  return Number((frameIndex * ORACLE_FRAME_MS).toFixed(6))
+}