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

package/src/oracle/velocity.ts

@@ -0,0 +1,44 @@
+// Presentation-only velocity helpers (adjudication A7). Finite-difference derivation never
+// feeds back into any engine.
+
+import type { TraceRow } from './types'
+import { ORACLE_FRAME_MS } from './types'
+import { OracleTraceError } from './errors'
+
+/**
+ * Finite-difference velocity (value-units/s) from consecutive samples.
+ * First sample uses 0 (no prior). dt is wall-clock ms between samples.
+ */
+export function finiteDiffVelocity(
+  prev: { t: number; value: number } | undefined,
+  cur: { t: number; value: number },
+  sliceId = 'derived-velocity',
+): number {
+  if (prev === undefined) return 0
+  const dt = cur.t - prev.t
+  if (dt <= 0) {
+    throw new OracleTraceError(
+      sliceId,
+      `non-monotone grid timestamps ${prev.t} -> ${cur.t} while deriving velocity`,
+    )
+  }
+  return ((cur.value - prev.value) / dt) * 1000
+}
+
+/** Rebuild a rows series with derived velocity from the value column (presentation only). */
+export function deriveVelocitySeries(
+  rows: readonly { readonly t: number; readonly value: number }[],
+  sliceId = 'derived-velocity',
+): readonly TraceRow[] {
+  let prev: { t: number; value: number } | undefined
+  return rows.map((r) => {
+    const velocity = finiteDiffVelocity(prev, r, sliceId)
+    prev = { t: r.t, value: r.value }
+    return { t: r.t, value: r.value, velocity }
+  })
+}
+
+/** Default dt for a single frame step when only one sample exists. */
+export function frameDtMs(): number {
+  return ORACLE_FRAME_MS
+}

package/src/parity.ts

@@ -0,0 +1,136 @@
+// Cross-engine parity seam (REQ-CONFORM-002) — ADDITIVE. The M1 fake-host suites record
+// `*.cross-engine-parity` unassertable because no second engine existed. Per the two-class contract
+// (SPEC-CONFORMANCE §3, ratified Option A) this module discharges them TWO ways: (1) SCALAR-COMPARABLE
+// rows are OWNED in-suite — a real second engine produces a ScenarioResult under the SAME scenario id
+// and the aggregator's ownership rule (`unassertable` + a `pass` owner → covered) flips it without
+// touching any scenario (e.g. gesture, via `runGestureParityScenario`). (2) EXTERNAL-EVIDENCE-ONLY rows
+// stay `unassertable` and carry a frozen COUNTERPART record naming the altitude that asserts them
+// (`LAYOUT_PARITY_COUNTERPART` / `LAYOUT_IDENTITY_PARITY_COUNTERPART` → the Playwright Chromium gate) —
+// never an in-suite pass. The web engine is injected as a narrow interface so this package stays free of
+// react/jsdom/motion-react dependencies (REQ-WEB-017: the engine never grades itself).
+
+import {
+  ManualClock,
+  ManualScheduler,
+  constants,
+  createGestureSession,
+  createMotionGraph,
+} from '@unrulysystems/native-motion-core'
+import type { Reading, ScenarioResult } from './runner'
+
+export const GESTURE_PARITY_SCENARIO_ID = 'gesture.cross-engine-parity'
+export const LAYOUT_PARITY_SCENARIO_ID = 'layout.cross-engine-parity'
+
+// One release case: the finger's story (origin, where it let go, how fast) plus the snap set.
+// Same semantics on both engines: value = origin + translation at release; the platform velocity
+// enters the projection UNSCALED (§G).
+export interface GestureParityCase {
+  readonly origin: number
+  readonly releaseTranslation: number
+  readonly releaseVelocity: number
+  readonly snapPoints: readonly number[]
+}
+
+// The injected second engine: given a release case, run the WEB release pipeline (inertia +
+// modifyTarget nearest-snap) to settle and report the landing value.
+export interface GestureWebEngine {
+  readonly id: string
+  releaseEndpoint(c: GestureParityCase): number
+}
+
+// Both engines project with Motion's `power · velocity` model (core pins PROJECTION_POWER from
+// the same motion-dom@12.42.2 source), so each case has ONE correct landing snap. The rows cover
+// a still release, a fling past the nearest point, and a negative-direction fling.
+export const GESTURE_PARITY_CASES: readonly GestureParityCase[] = [
+  { origin: 0, releaseTranslation: 250, releaseVelocity: 0, snapPoints: [0, 300, 600] },
+  { origin: 0, releaseTranslation: 250, releaseVelocity: 500, snapPoints: [0, 300, 600] },
+  { origin: 0, releaseTranslation: 100, releaseVelocity: -400, snapPoints: [0, 300, 600] },
+  // FLAG 5a contention parity (REQ-DRIVER-026): a mid-drag `animate` drifts the LIVE value PAST the
+  // [0,240] snap midpoint (120) before a zero-velocity release. Both engines project from the DRIFTED
+  // origin (145) — reference project-then-snap, web motion-dom `inertia` + `modifyTarget` — to the FAR
+  // snap `240`. The finger-frozen origin (110, the pre-fix skip) would select the NEAR snap `0`; the
+  // contending drift past the midpoint is exactly what flips it. The DRIFT itself is Motion's own
+  // shared-value behavior (pinned oracle, `MotionValue.set` does not stop the animation); this row is
+  // the cross-engine proof of the release-PROJECTION from the drifted value.
+  { origin: 0, releaseTranslation: 145, releaseVelocity: 0, snapPoints: [0, 240] },
+]
+
+// Endpoint tolerance: the reference settles within core's trajectory epsilon of the snap point
+// (EPS_TRAJ) and Motion's inertia stops within its restDelta (0.5) — additive worst case. Not
+// loop-tunable (REQ-CONFORM-014); a bigger gap is a real divergence, recorded, never widened over.
+const MOTION_INERTIA_REST_DELTA = 0.5
+export const GESTURE_ENDPOINT_BAND = constants.EPS_TRAJ + MOTION_INERTIA_REST_DELTA
+
+// The reference engine's landing value: core gesture session — begin, one active sample, release
+// with the platform velocity, then frames to settle (the release spring runs to true settle).
+export function referenceReleaseEndpoint(c: GestureParityCase): number {
+  const clock = new ManualClock(0)
+  const scheduler = new ManualScheduler(clock)
+  const graph = createMotionGraph({ clock, scheduler })
+  const session = createGestureSession({
+    graph,
+    initial: c.origin,
+    snap: { points: [...c.snapPoints] },
+  })
+  session.begin(0)
+  session.active({ t: 16, translation: c.releaseTranslation, velocity: c.releaseVelocity })
+  session.end({ t: 32, translation: c.releaseTranslation, velocity: c.releaseVelocity })
+  scheduler.frames(600, 16.67) // ~10s of frames — far past settle for these springs
+  return session.value()
+}
+
+// Run the parity scenario with the injected web engine. Fail-closed: every case must land within
+// the band on BOTH engines' agreed value; any gap fails with the exact numbers in the detail.
+export function runGestureParityScenario(web: GestureWebEngine): ScenarioResult {
+  const readings: Reading[] = GESTURE_PARITY_CASES.map((c, i) => {
+    const expected = referenceReleaseEndpoint(c)
+    const actual = web.releaseEndpoint(c)
+    return {
+      at: i,
+      kind: 'value',
+      expected,
+      actual,
+      pass: Math.abs(actual - expected) <= GESTURE_ENDPOINT_BAND,
+    }
+  })
+  const failures = readings.filter((r) => !r.pass)
+  return {
+    id: GESTURE_PARITY_SCENARIO_ID,
+    engine: web.id,
+    verdict: failures.length === 0 ? 'pass' : 'fail',
+    readings,
+    ...(failures.length > 0
+      ? {
+          detail: failures
+            .map(
+              (f) =>
+                `case ${f.at}: web landed at ${String(f.actual)}, reference at ` +
+                `${String(f.expected)} (band ${GESTURE_ENDPOINT_BAND})`,
+            )
+            .join('; '),
+        }
+      : {}),
+  }
+}
+
+// Layout parity cannot be asserted under jsdom (no layout engine — onLayout rects would be
+// fiction). The declared counterpart is the Altitude-5 Playwright Chromium run (REQ-CONFORM-002
+// fail-closed accounting: unassertable-here must carry the altitude where it IS assertable).
+export const LAYOUT_PARITY_COUNTERPART = Object.freeze({
+  scenarioId: LAYOUT_PARITY_SCENARIO_ID,
+  altitude: 'alt5-playwright-chromium',
+  reason: 'jsdom has no layout engine; FLIP geometry is asserted in the real-browser gate',
+})
+
+// layoutId crossfade parity cannot execute on the fake host (no second engine there). The
+// declared counterpart is the Altitude-5 Playwright Chromium run
+// (`packages/native-motion-web/e2e/layout-identity-parity.e2e.ts`): real motion/react keeps two
+// components alive through one layoutId exchange and the spec asserts the L2 registry's laws —
+// both-travel crossfade, shared-visual-rect coincidence, exact endpoints (REQ-CONFORM-011).
+export const LAYOUT_IDENTITY_PARITY_COUNTERPART = Object.freeze({
+  scenarioId: 'layout-identity.cross-engine-parity',
+  altitude: 'alt5-playwright-chromium',
+  reason:
+    'the fake host has no second engine; the crossfade laws are asserted against real ' +
+    'motion/react in the real-browser gate',
+})

package/src/runner.ts

@@ -0,0 +1,168 @@
+// The scenario runner: drives a scenario's timeline on one engine and computes the verdict. The
+// runner — never the scenario author — decides pass/fail/unassertable (REQ-CONFORM-011). Accounting
+// is three-valued and fail-closed: a required capability the engine lacks is `unassertable` (a routed
+// obligation, not a silent pass); any failed invariant is `fail`.
+
+import type { EngineAdapter } from './adapter'
+import type {
+  MotionScalar,
+  Scenario,
+  SpringScenario,
+  ToleranceBand,
+  ValueTypeScenario,
+} from './scenario'
+
+export type Verdict = 'pass' | 'fail' | 'unassertable'
+
+// One invariant evaluated against one engine: what the scenario expected, what the engine produced,
+// and whether it fell within tolerance. Retained on the result so the cross-engine comparator can
+// differentiate the two engines' series without re-running them.
+export interface Reading {
+  readonly at: number
+  readonly kind: 'velocity' | 'value'
+  readonly expected: MotionScalar
+  readonly actual: MotionScalar
+  readonly pass: boolean
+}
+
+export interface ScenarioResult {
+  readonly id: string
+  readonly engine: string
+  readonly verdict: Verdict
+  readonly readings: readonly Reading[]
+  readonly detail?: string
+}
+
+export function runScenario(
+  scenario: Scenario,
+  adapter: EngineAdapter,
+  band: ToleranceBand,
+): ScenarioResult {
+  // Capability gate (REQ-CONFORM-012): an engine missing a required capability cannot assert this
+  // scenario. Report `unassertable` — a routed obligation, never a silent skip or pass.
+  const missing = scenario.capabilities.filter((c) => !adapter.capabilities.includes(c))
+  if (missing.length > 0) {
+    return {
+      id: scenario.id,
+      engine: adapter.id,
+      verdict: 'unassertable',
+      readings: [],
+      detail: `missing capabilities: ${missing.join(', ')}`,
+    }
+  }
+
+  const value = adapter.createValue(scenario.initial)
+  const readings: Reading[] = []
+  // Stable sort by `at`: steps sharing a timestamp keep authored order (input before the assertion
+  // that reads it). Each step anchors the engine's clock first, synchronously (motion-dom's
+  // `time.set` microtask-clear cannot interleave within one step).
+  const steps = [...scenario.timeline].sort((a, b) => a.at - b.at)
+  for (const step of steps) {
+    value.setTime(step.at)
+    if ('set' in step) {
+      value.set(step.set)
+    } else if ('jump' in step) {
+      value.jump(step.jump)
+    } else if ('assertVelocity' in step) {
+      const actual = value.getVelocity()
+      readings.push({
+        at: step.at,
+        kind: 'velocity',
+        expected: step.assertVelocity,
+        actual,
+        pass: Math.abs(actual - step.assertVelocity) <= band.velocity,
+      })
+    } else {
+      const actual = value.get()
+      readings.push({
+        at: step.at,
+        kind: 'value',
+        expected: step.assertValue,
+        actual,
+        pass: scalarWithin(actual, step.assertValue, band.value),
+      })
+    }
+  }
+
+  // Fail-closed: a scenario that asserted nothing cannot be a pass.
+  const verdict: Verdict = readings.length > 0 && readings.every((r) => r.pass) ? 'pass' : 'fail'
+  return { id: scenario.id, engine: adapter.id, verdict, readings }
+}
+
+// Run a spring/timing TRAJECTORY scenario on one engine (SPEC-SPRING §5). The engine builds a generator
+// and samples value+velocity on the t-grid; there is no author-supplied expected, so `expected` mirrors
+// `actual` and each per-engine reading passes — the real verdict is the DIFFERENTIAL cross-engine
+// comparison (`compareEngines`) over these readings. An engine lacking `spring-trajectory` is
+// `unassertable` (routed, never a silent pass); an empty grid is fail-closed.
+export function runSpringScenario(
+  scenario: SpringScenario,
+  adapter: EngineAdapter,
+  _band: ToleranceBand,
+): ScenarioResult {
+  const missing = scenario.capabilities.filter((c) => !adapter.capabilities.includes(c))
+  if (missing.length > 0 || adapter.sampleTrajectory === undefined) {
+    return {
+      id: scenario.id,
+      engine: adapter.id,
+      verdict: 'unassertable',
+      readings: [],
+      detail: `missing capabilities: ${missing.join(', ') || 'spring-trajectory'}`,
+    }
+  }
+
+  const points = adapter.sampleTrajectory(scenario.kind, scenario.spec, scenario.tGrid)
+  const readings: Reading[] = []
+  for (const p of points) {
+    // value THEN velocity per point, identical order on every engine so the comparator zips kinds.
+    readings.push({ at: p.t, kind: 'value', expected: p.value, actual: p.value, pass: true })
+    readings.push({
+      at: p.t,
+      kind: 'velocity',
+      expected: p.velocity,
+      actual: p.velocity,
+      pass: true,
+    })
+  }
+  const verdict: Verdict = readings.length > 0 ? 'pass' : 'fail'
+  return { id: scenario.id, engine: adapter.id, verdict, readings }
+}
+
+// Run a value-type MIX scenario on one engine (SPEC-VALUE-TYPES §5). The engine mixes `from`→`to` at
+// each progress fraction and projects the committed value; as with the spring runner there is no
+// author-supplied expected, so `expected` mirrors `actual` and each per-engine reading passes — the real
+// verdict is the DIFFERENTIAL cross-engine comparison (`compareValueTypeSeries`). An engine lacking
+// `value-type-mix` is `unassertable` (routed, never a silent pass); an empty grid is fail-closed.
+// A `'throw'` divergence scenario is NOT run through here (native would throw) — the divergence test
+// asserts the throw directly.
+export function runValueTypeScenario(
+  scenario: ValueTypeScenario,
+  adapter: EngineAdapter,
+): ScenarioResult {
+  const missing = scenario.capabilities.filter((c) => !adapter.capabilities.includes(c))
+  if (missing.length > 0 || adapter.mixValueType === undefined) {
+    return {
+      id: scenario.id,
+      engine: adapter.id,
+      verdict: 'unassertable',
+      readings: [],
+      detail: `missing capabilities: ${missing.join(', ') || 'value-type-mix'}`,
+    }
+  }
+
+  const mixValueType = adapter.mixValueType
+  const readings: Reading[] = scenario.grid.map((p) => {
+    const actual = mixValueType(scenario.from, scenario.to, p)
+    // `at` carries the progress fraction (this altitude has no wall-clock); expected mirrors actual so
+    // the per-engine reading passes — the cross-engine comparator owns the verdict.
+    return { at: p, kind: 'value', expected: actual, actual, pass: true }
+  })
+  const verdict: Verdict = readings.length > 0 ? 'pass' : 'fail'
+  return { id: scenario.id, engine: adapter.id, verdict, readings }
+}
+
+// Scalar equality within a tolerance: numeric within `tol`, otherwise strict equality (non-numeric
+// scalars have no band). Shared with the cross-engine comparator's per-reading check.
+export function scalarWithin(x: MotionScalar, y: MotionScalar, tol: number): boolean {
+  if (typeof x === 'number' && typeof y === 'number') return Math.abs(x - y) <= tol
+  return x === y
+}

package/src/scenario.ts

@@ -0,0 +1,179 @@
+// The engine-agnostic scenario format (REQ-CONFORM-010). A scenario is authored ONCE — a timeline of
+// timestamped inputs interleaved with invariant assertions — and executed against every engine. The
+// author declares inputs and invariants; the runner (not the author) computes the verdict
+// (REQ-CONFORM-011). This file is pure data + types: no engine imports, no I/O.
+
+// State-level motion values are scalars. Numbers track velocity; non-numeric values must report a
+// velocity of 0 on every engine (REQ-VALUE-010) — the non-numeric parity case is a first-class
+// scenario, so the scalar type is a union rather than `number`.
+export type MotionScalar = number | string
+
+// Capabilities an engine PROVIDES; a scenario REQUIRES a subset (REQ-CONFORM-012). The runner runs a
+// scenario on an engine only if the engine provides every required capability; otherwise it reports
+// `unassertable` and routes the obligation to an engine that can (REQ-CONFORM-011). The provisions:
+//   - `numeric-velocity` — tracks numeric velocity from timed samples (both state-level engines).
+//   - `settle-ledger`    — exposes graph settle (native core only; motion-dom's value has no settle).
+//   - `geometry`         — measures rendered geometry (trajectory altitude; NEITHER state-level
+//                          engine — a scenario needing it is unassertable here and owned by the M2
+//                          device/browser harness).
+// M1b's state-level value scenarios need only `numeric-velocity`; the others exist so the three-valued
+// routing (unassertable when a provision is absent) is provable, not theoretical.
+//   - `spring-trajectory` — builds an analytic spring/timing generator from a config and samples
+//                          value+velocity on a t-grid (native core AND motion-dom both provide it;
+//                          it is the SPEC-SPRING §5 cross-engine altitude).
+//   - `value-type-mix`   — parses two raw property values, mixes at a progress fraction, and projects
+//                          the committed value (native core's value-type seam AND motion-dom's `mix`
+//                          both provide it; the SPEC-VALUE-TYPES §5 cross-engine altitude).
+export type Capability =
+  | 'numeric-velocity'
+  | 'settle-ledger'
+  | 'geometry'
+  | 'spring-trajectory'
+  | 'value-type-mix'
+
+// One timeline entry: either an input applied to the value at time `at`, or an invariant asserted
+// against the value at time `at`. A discriminated union keyed by the present property.
+export type TimelineStep =
+  | { readonly at: number; readonly set: MotionScalar }
+  | { readonly at: number; readonly jump: MotionScalar }
+  | { readonly at: number; readonly assertVelocity: number }
+  | { readonly at: number; readonly assertValue: MotionScalar }
+
+export interface Scenario {
+  readonly id: string
+  readonly requirements: readonly string[]
+  readonly capabilities: readonly Capability[]
+  readonly initial: MotionScalar
+  readonly timeline: readonly TimelineStep[]
+}
+
+// A spring/timing TRAJECTORY scenario (SPEC-SPRING §5). Unlike a value scenario, there are no
+// author-supplied expected values: the engine builds a generator from `spec` seeded with [from,
+// velocity] and samples value+velocity at each `tGrid` point; the verdict is the DIFFERENTIAL
+// cross-engine comparison (native vs motion-dom) within the ratified spring band. `pendingDecisionD`
+// marks the two known oracle divergences (#1207 overdamped tail, visualDuration-only) where the pinned
+// motion-dom is buggy (pre-plan-030/031) and native is correct — cross-engine parity is fail-closed
+// until the pin is reconciled (SPEC-SPRING §8), never papered over.
+export type SpringKind = 'spring' | 'timing'
+
+export interface SpringTrajectorySpec {
+  readonly from: number
+  readonly to: number
+  readonly velocity?: number // incoming public velocity, px/s
+  // spring physics OR duration family (resolution precedence is the engine's, REQ-SPRING-006)
+  readonly stiffness?: number
+  readonly damping?: number
+  readonly mass?: number
+  readonly duration?: number // ms
+  readonly bounce?: number
+  readonly visualDuration?: number // seconds
+  // timing only: cubic-bezier control points or a Motion named easing (REQ-TIMING-001 family-2)
+  readonly ease?:
+    | readonly [number, number, number, number]
+    | 'linear'
+    | 'easeIn'
+    | 'easeOut'
+    | 'easeInOut'
+    | 'circIn'
+    | 'circOut'
+    | 'circInOut'
+    | 'backIn'
+    | 'backOut'
+    | 'backInOut'
+    | 'anticipate'
+}
+
+export interface SpringScenario {
+  readonly id: string
+  readonly requirements: readonly string[]
+  readonly capabilities: readonly Capability[] // ['spring-trajectory']
+  readonly kind: SpringKind
+  readonly spec: SpringTrajectorySpec
+  readonly tGrid: readonly number[]
+  readonly pendingDecisionD?: boolean
+}
+
+// A value-type MIX scenario (SPEC-VALUE-TYPES §5). The engine parses `from`/`to`, mixes at each
+// progress fraction in `grid`, and projects the committed value; the verdict is the DIFFERENTIAL
+// cross-engine comparison (native seam vs motion-dom `mix`) with each typed channel checked within its
+// per-type epsilon (EPS_COLOR_CHANNEL / EPS_LENGTH / …), NOT byte-equality. `divergence` marks the
+// intentional, recorded gaps: `'throw'` — native fails loud on a unit/shape mismatch where motion
+// warns+snaps (REQ-VALUETYPE-004/-007/-008); `'snap'` — native mixes a family motion cannot without a
+// host (named colors, REQ-VALUETYPE-005), so the two engines MUST diverge (a documented capability
+// tripwire, flagged as the §8 named-color-completeness vetoable — never papered over).
+export interface ValueTypeScenario {
+  readonly id: string
+  readonly requirements: readonly string[]
+  readonly capabilities: readonly Capability[] // ['value-type-mix']
+  readonly property: string // 'backgroundColor' | 'borderRadius' — informational grouping
+  readonly from: string
+  readonly to: string
+  readonly grid: readonly number[] // progress fractions in [0,1]
+  readonly divergence?: 'throw' | 'snap'
+}
+
+// The per-property cross-engine tolerance band (REQ-CONFORM-014). Ratified, not loop-tunable: a real
+// divergence is a `fail` recorded as a decision, never a widened band. `velocity` ties to the core's
+// pinned `EPS_VELOCITY`; `value` is exact for state-level scalars (see `config.ts`).
+export interface ToleranceBand {
+  readonly velocity: number
+  readonly value: number
+}
+
+// The core-owned state-level scenarios (M1B-BUILD-PACKET table). Authored engine-agnostically; run
+// against both the native core and pinned motion-dom, then differentially compared. Two steps that
+// share an `at` execute in array order (the runner's sort is stable): inputs precede the assertions
+// that read them.
+export const CORE_SCENARIOS: readonly Scenario[] = [
+  {
+    // Velocity from the last two timed samples: (8-0)*1000/16 = 500.
+    id: 'CORE-V1',
+    requirements: ['REQ-VALUE-010'],
+    capabilities: ['numeric-velocity'],
+    initial: 0,
+    timeline: [
+      { at: 0, set: 0 },
+      { at: 16, set: 8 },
+      { at: 16, assertVelocity: 500 },
+    ],
+  },
+  {
+    // Staleness: at t=60 the last update (t=16) is 44ms old, past the 30ms window → velocity 0.
+    id: 'CORE-V2',
+    requirements: ['REQ-VALUE-011'],
+    capabilities: ['numeric-velocity'],
+    initial: 0,
+    timeline: [
+      { at: 0, set: 0 },
+      { at: 16, set: 8 },
+      { at: 60, assertVelocity: 0 },
+    ],
+  },
+  {
+    // Teleport resets velocity: jump commits+notifies, ends any active animation (pinned
+    // order, REQ-VALUE-010 r16), and reads velocity 0 — no successor seeding.
+    id: 'CORE-V3',
+    requirements: ['REQ-VALUE-012'],
+    capabilities: ['numeric-velocity'],
+    initial: 0,
+    timeline: [
+      { at: 0, set: 0 },
+      { at: 16, set: 8 },
+      { at: 20, jump: 20 },
+      { at: 20, assertValue: 20 },
+      { at: 20, assertVelocity: 0 },
+    ],
+  },
+  {
+    // Non-numeric: velocity is undefined for strings → 0 on every engine. Requires no capability.
+    id: 'CORE-V4',
+    requirements: ['REQ-VALUE-010'],
+    capabilities: [],
+    initial: 'a',
+    timeline: [
+      { at: 0, set: 'a' },
+      { at: 16, set: 'b' },
+      { at: 16, assertVelocity: 0 },
+    ],
+  },
+]

package/src/scenarios/appstore-choreography.ts

@@ -0,0 +1,105 @@
+// L4 choreography ordering (specs/SPEC-LAYOUT.md): the trajectory-altitude
+// facts of the App Store card that ARE assertable engine-agnostically, ADDITIVE to the suite.
+// The golden contract's item 3 — "corner radius completes AHEAD of the rect" — is a property of
+// the DRAFT feel constants themselves: the radius channel {900, 60} must settle strictly before
+// the slowest rect channel {550, 45} over the demo-scale deltas, under core's own generators
+// (the native flight's exact math; any engine honoring the constants inherits the ordering).
+// Full composite-flight cross-engine parity is deliberately NOT asserted here: spring-solver
+// parity is already pinned at SPRING altitude against the motion oracle, FLIP geometry at the
+// Chromium layout gate, and the composite aesthetic is the HUMAN-attended golden-frame bar
+// (REQ-ORACLE-005) — recorded unassertable-with-reason below, never silently skipped.
+
+import { resolveSpringGenerator } from '@unrulysystems/native-motion-core'
+import type { ScenarioResult } from '../runner'
+
+interface Outcome {
+  readonly verdict: 'pass' | 'fail' | 'unassertable'
+  readonly detail: string
+}
+const pass = (detail: string): Outcome => ({ verdict: 'pass', detail })
+const fail = (detail: string): Outcome => ({ verdict: 'fail', detail })
+const unassertable = (detail: string): Outcome => ({ verdict: 'unassertable', detail })
+
+// The L4 draft constants (ratified at the packet review) and demo-scale deltas: radius 24 → 0;
+// the rect's largest channel travels ~200 px (thumb → hero on both engines' demo geometry).
+const RECT_SPRING = { stiffness: 550, damping: 45 }
+const RADIUS_SPRING = { stiffness: 900, damping: 60 }
+const DT = 16.67
+const REST_EPSILON = 0.5 // px-scale rest window, the layout epsilon family
+
+function settleFrames(
+  from: number,
+  to: number,
+  spring: { stiffness: number; damping: number },
+): number {
+  const generator = resolveSpringGenerator(to, spring)({ from, velocity: 0 })
+  let elapsed = 0
+  for (let frame = 1; frame <= 2000; frame += 1) {
+    elapsed += DT
+    const sample = generator.sample(elapsed)
+    if (sample.done) return frame
+    if (Math.abs(sample.value - to) < REST_EPSILON && frame > 1) {
+      // Conservative: treat first entry into the rest window as visual completion.
+      return frame
+    }
+  }
+  return Number.POSITIVE_INFINITY
+}
+
+export interface AppstoreChoreographyScenario {
+  readonly id: string
+  readonly requirements: readonly string[]
+  readonly assert: () => Outcome
+}
+
+export const APPSTORE_CHOREOGRAPHY_SCENARIOS: readonly AppstoreChoreographyScenario[] = [
+  {
+    id: 'appstore-choreography.radius-leads-rect',
+    requirements: ['REQ-LAYOUT-014', 'REQ-ORACLE-005'],
+    assert() {
+      const radiusFrames = settleFrames(24, 0, RADIUS_SPRING)
+      const rectFrames = settleFrames(0, 200, RECT_SPRING)
+      if (!(radiusFrames < rectFrames)) {
+        return fail(
+          `radius {900,60} settled in ${radiusFrames} frames but the rect {550,45} in ` +
+            `${rectFrames} — the golden contract needs the radius to complete AHEAD of the rect`,
+        )
+      }
+      return pass(
+        `radius completes ahead: ${radiusFrames} frames vs rect ${rectFrames} at the draft constants`,
+      )
+    },
+  },
+  {
+    id: 'appstore-choreography.cross-engine-parity',
+    requirements: ['REQ-CONFORM-002', 'REQ-ORACLE-005'],
+    assert() {
+      // Every axis of the composite has a named EXECUTING counterpart (REQ-CONFORM-011):
+      // spring feel → the SPRING goldens vs the pinned motion oracle; FLIP geometry →
+      // layout.cross-engine-parity in the Chromium gate; the layoutId crossfade →
+      // layout-identity-parity.e2e.ts (LAYOUT_IDENTITY_PARITY_COUNTERPART); the composite
+      // AESTHETIC → the human-attended golden-frame bar, which REQ-ORACLE-005 defines as the
+      // authoritative altitude for visual judgment. A deterministic composite gate would be
+      // the pixel-diff proxy the golden README forbids.
+      return unassertable(
+        'each axis executes at its own altitude: SPRING goldens (oracle), ' +
+          'layout.cross-engine-parity (Chromium), layout-identity-parity.e2e.ts (Chromium, ' +
+          'LAYOUT_IDENTITY_PARITY_COUNTERPART), and the composite aesthetic at the ' +
+          'REQ-ORACLE-005 human-attended golden-frame altitude',
+      )
+    },
+  },
+]
+
+export function runAppstoreChoreographyScenario(
+  scenario: AppstoreChoreographyScenario,
+): ScenarioResult {
+  const outcome = scenario.assert()
+  return {
+    id: scenario.id,
+    engine: 'fake-host',
+    verdict: outcome.verdict,
+    readings: [],
+    detail: outcome.detail,
+  }
+}