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

package/src/scenarios/driver.ts

@@ -0,0 +1,322 @@
+// SPEC-NATIVE-DRIVER §4 Altitude-2 conformance scenarios (REQ-DRIVER-012/013/017/020). Authored ONCE,
+// engine-agnostic: each asserts a driver design-law against the reference in-core Driver — the JS-crossing
+// contract (one seeded command drives every frame), dt-cadence invariance, quiesce-before-teardown,
+// trajectory parity vs the built generators (the driver forks no math), and prop-tier routing. At Milestone
+// 1 the "engine" is the deterministic reference driver on a fake clock, no rendering; the IDENTICAL
+// scenarios re-run against the native worklet + web drivers at Milestone 2 (one contract, many substrates).
+// Fail-closed: a gate passes ONLY if the observed behavior holds; a driver that cannot run a gate would be
+// `unassertable`, never a silent pass.
+
+import {
+  type Driver,
+  type Transition,
+  constants,
+  createReferenceDriver,
+  resolveSpringGenerator,
+  selectReleaseTarget,
+  tierFor,
+  timingGenerator,
+} from '@unrulysystems/native-motion-core'
+import { toTimingLaneConfig } from '@unrulysystems/native-motion-core/internal-driver'
+import type { ScenarioResult, Verdict } from '../runner'
+
+// The engine label these deterministic-interior results are recorded under (M1). M2 adds 'native' / 'web'.
+const FAKE_ENGINE = 'fake-host'
+
+// Trajectory tolerance — the ratified CORE epsilon (single-sourced; never widened to force a pass).
+const EPS = constants.EPS_TRAJ
+
+const TWEEN: Transition = { type: 'tween', duration: 0.2 } // 200ms
+const SPRING: Transition = { type: 'spring', stiffness: 180, damping: 20 }
+
+// A single deterministic-interior gate outcome. `unassertable` distinguishes "could not run here" from a
+// genuine pass/fail (three-valued accounting), reserved for M2 engines that lack a capability.
+interface Outcome {
+  readonly verdict: Verdict
+  readonly detail: string
+}
+const pass = (detail: string): Outcome => ({ verdict: 'pass', detail })
+const fail = (detail: string): Outcome => ({ verdict: 'fail', detail })
+
+// Wrap a Driver so the JS→UI boundary is observable: a `command` is a JS-thread hop; a `step` is a UI-thread
+// frame. REQ-DRIVER-013 requires O(1) hops per logical command and ZERO per frame — one seeded command must
+// drive an entire animation. The counters make a per-frame hop (the forbidden anti-pattern) visible: a
+// correct driver animates N frames while `commands()` stays at the number of logical commands, independent
+// of N.
+function countingDriver(inner: Driver): {
+  readonly driver: Driver
+  readonly commands: () => number
+  readonly steps: () => number
+  readonly writes: () => number
+  readonly liveReads: () => number
+} {
+  let commands = 0
+  let steps = 0
+  let writes = 0
+  let liveReads = 0
+  const driver: Driver = {
+    register: (initial) => inner.register(initial),
+    command: (handle, command) => {
+      commands += 1
+      inner.command(handle, command)
+    },
+    step: (elapsedMs) => {
+      steps += 1
+      inner.step(elapsedMs)
+    },
+    committed: (handle) => inner.committed(handle),
+    setActive: (handle, active) => inner.setActive(handle, active),
+    isActive: (handle) => inner.isActive(handle),
+    // The FLAG 5a gesture lane is a boundary hop too: a write is O(1) per recognizer EVENT
+    // (REQ-DRIVER-024) and a live-read O(1) per gesture EDGE (REQ-DRIVER-025) — counted so a
+    // scenario can assert the crossing budget exactly like commands-vs-frames.
+    write: (handle, values, velocities) => {
+      writes += 1
+      inner.write(handle, values, velocities) // forward the gesture-phase velocity (r4 c14e15)
+    },
+    liveFor: (handle, key) => {
+      liveReads += 1
+      return inner.liveFor(handle, key)
+    },
+  }
+  return {
+    driver,
+    commands: () => commands,
+    steps: () => steps,
+    writes: () => writes,
+    liveReads: () => liveReads,
+  }
+}
+
+export interface DriverScenario {
+  readonly id: string
+  readonly requirements: readonly string[]
+  readonly assert: () => Outcome
+}
+
+export const DRIVER_SCENARIOS: readonly DriverScenario[] = [
+  {
+    // REQ-DRIVER-013 — ZERO per-frame JS crossings, O(1) hops per command. One seeded command must drive an
+    // entire multi-frame animation with no further commands.
+    id: 'DRV-js-crossing-zero-per-frame',
+    requirements: ['REQ-DRIVER-013'],
+    assert() {
+      const { driver, commands, steps } = countingDriver(createReferenceDriver())
+      const h = driver.register({ x: 0 })
+      driver.command(h, { kind: 'start', targets: { x: { to: 100, from: 0 } }, transition: TWEEN })
+      const FRAMES = 120 // ~2s at 60Hz, well past the 200ms tween
+      for (let i = 0; i < FRAMES; i++) driver.step(16.67)
+      if (commands() !== 1) {
+        return fail(`expected O(1) = 1 command, got ${commands()} (a per-frame JS crossing)`)
+      }
+      if (steps() !== FRAMES) return fail(`expected ${FRAMES} UI-thread steps, got ${steps()}`)
+      if (driver.committed(h)['x'] !== 100) {
+        return fail('animation did not reach target from a single seeded command')
+      }
+      return pass(`${FRAMES} frames driven by 1 command (0 per-frame JS crossings), reached target`)
+    },
+  },
+  {
+    // REQ-DRIVER-012 — end-to-end dt-cadence invariance: the same spec to the same total elapsed under a
+    // uniform vs a variable/duplicated frame cadence lands on the same value (time-integrated, not frame-
+    // counted; reproduces the gesture-speedup class the reference upstream regresses on).
+    id: 'DRV-dt-cadence-invariance',
+    requirements: ['REQ-DRIVER-012'],
+    assert() {
+      const uniform = createReferenceDriver()
+      const hu = uniform.register({ x: 0 })
+      uniform.command(hu, {
+        kind: 'start',
+        targets: { x: { to: 100, from: 0 } },
+        transition: SPRING,
+      })
+      for (let i = 0; i < 9; i++) uniform.step(16.67) // 150.03ms
+
+      const variable = createReferenceDriver()
+      const hv = variable.register({ x: 0 })
+      variable.command(hv, {
+        kind: 'start',
+        targets: { x: { to: 100, from: 0 } },
+        transition: SPRING,
+      })
+      for (const dt of [40, 0, 30, 20, 0, 30, 30.03]) variable.step(dt) // sums to 150.03ms, all ≤ ceiling
+
+      const du = uniform.committed(hu)['x'] as number
+      const dv = variable.committed(hv)['x'] as number
+      return Math.abs(du - dv) <= EPS
+        ? pass(`uniform ${du.toFixed(3)} ≈ variable ${dv.toFixed(3)} within ε=${EPS}`)
+        : fail(`dt-cadence divergence: uniform ${du} vs variable ${dv} (> ${EPS})`)
+    },
+  },
+  {
+    // REQ-DRIVER-020 — an element is active while animating and quiesces (isActive→false) once settled, so a
+    // consumer can safely tear it down only after quiesce. A never-quiescing element would strand resources.
+    id: 'DRV-quiesce-before-teardown',
+    requirements: ['REQ-DRIVER-020'],
+    assert() {
+      const d = createReferenceDriver()
+      const h = d.register({ x: 0 })
+      d.command(h, { kind: 'start', targets: { x: { to: 100, from: 0 } }, transition: TWEEN })
+      d.step(16.67)
+      if (!d.isActive(h)) return fail('element reported inactive while still animating')
+      for (let i = 0; i < 30; i++) d.step(16.67) // past the 200ms tween → settle
+      if (d.isActive(h))
+        return fail('element never quiesced after settling (teardown would strand it)')
+      return d.committed(h)['x'] === 100
+        ? pass('active while animating, quiesced at settle, committed == target')
+        : fail(`quiesced but committed ${String(d.committed(h)['x'])} != target 100`)
+    },
+  },
+  {
+    // REQ-DRIVER-003/012 — the driver forks no trajectory math: its committed value matches the built
+    // SPRING and TIMING generators sampled at the same cumulative elapsed, at every grid point.
+    id: 'DRV-trajectory-parity',
+    requirements: ['REQ-DRIVER-003', 'REQ-DRIVER-012'],
+    assert() {
+      const cases: ReadonlyArray<{ transition: Transition; ref: (t: number) => number }> = [
+        {
+          transition: SPRING,
+          ref: (() => {
+            const g = resolveSpringGenerator(100, { stiffness: 180, damping: 20 })({
+              from: 0,
+              velocity: 0,
+            })
+            return (t: number) => g.sample(t).value
+          })(),
+        },
+        {
+          transition: TWEEN,
+          // The reference resolves the SAME bag through the SAME ONE config builder the drivers
+          // read (`toTimingLaneConfig`) — never a hand-written config. Hand-deriving it re-asks
+          // the question at a different altitude: the pin applies its `easeOut` base at the
+          // bag->options seam (`animateMotionValue`), which a direct `timingGenerator({duration})`
+          // call bypasses, landing on the generator-level DEFAULT_EASE instead. That skew broke
+          // this gate when the base landed, reporting a driver fork that did not exist. Deriving
+          // from TWEEN also kills the duplicated 200ms literal and its manual seconds->ms crossing.
+          ref: (() => {
+            const g = timingGenerator(100, toTimingLaneConfig(TWEEN))({ from: 0, velocity: 0 })
+            return (t: number) => g.sample(t).value
+          })(),
+        },
+      ]
+      for (const { transition, ref } of cases) {
+        const d = createReferenceDriver()
+        const h = d.register({ x: 0 })
+        d.command(h, { kind: 'start', targets: { x: { to: 100, from: 0 } }, transition })
+        let cumulative = 0
+        for (let i = 0; i < 12; i++) {
+          d.step(16.67)
+          cumulative += 16.67
+          const got = d.committed(h)['x'] as number
+          const want = ref(cumulative)
+          if (Math.abs(got - want) > EPS) {
+            return fail(
+              `${transition.type} parity break at t=${cumulative.toFixed(1)}ms: driver ${got} vs generator ${want}`,
+            )
+          }
+        }
+      }
+      return pass(
+        'driver trajectory matches the built spring + tween generators within ε (no forked math)',
+      )
+    },
+  },
+  {
+    // REQ-DRIVER-017 — every animatable prop routes to a substrate tier: non-layout → fast, layout-affecting
+    // → commit; a non-animatable prop fails loud (no silent mis-route).
+    id: 'DRV-tier-routing-fail-loud',
+    requirements: ['REQ-DRIVER-017'],
+    assert() {
+      if (tierFor('x') !== 'fast' || tierFor('opacity') !== 'fast') {
+        return fail('transform/opacity not routed to the fast (non-layout) tier')
+      }
+      if (tierFor('width') !== 'commit' || tierFor('height') !== 'commit') {
+        return fail('width/height not routed to the commit (layout-affecting) tier')
+      }
+      let threw = false
+      try {
+        tierFor('whileTap')
+      } catch {
+        threw = true
+      }
+      if (!threw) return fail('a non-animatable gesture prop did not fail loud (fail-open)')
+      return pass('non-layout → fast, layout → commit, and an untiered prop fails loud')
+    },
+  },
+  {
+    // REQ-DRIVER-026 (+ REQ-GESTURE-022) — Gesture↔declarative same-axis contention, the FLAG 5a
+    // parity oracle. Reproduces the full cross-engine sequence deterministically against the
+    // reference driver (the shared contract seam both substrates honor): the driver integrates the
+    // CONTENDING generator while the finger holds, and core's shared `selectReleaseTarget` projects
+    // the release. The load-bearing point is Motion's shared-value model — a mid-drag `animate` drifts
+    // the LIVE value past the snap midpoint, so the release origin (the live value, REQ-GESTURE-022),
+    // not the frozen finger, selects the far snap. The pre-fix "skip declarative on a held prop" froze
+    // the origin at the finger and selected the NEAR snap — the counterfactual asserted below.
+    id: 'DRV-contention-release-snap',
+    requirements: ['REQ-DRIVER-026', 'REQ-GESTURE-022'],
+    assert() {
+      const SNAP = { points: [0, 240] } as const // midpoint 120: origin < 120 ⇒ 0, > 120 ⇒ 240
+      const FINGER = 110 // dragged-to position, held (release velocity 0)
+      const d = createReferenceDriver()
+      const h = d.register({ x: 0 })
+      // Grab + drag to the finger position, held (a write is O(1) per recognizer event, velocity 0).
+      d.write(h, { x: FINGER }, { x: 0 })
+      // While held, `animate.x = 200` — a declarative retarget that CONTENDS (never skipped).
+      d.command(h, { kind: 'retarget', targets: { x: 200 }, transition: SPRING })
+      // Dwell: the contending generator drifts the live value from 110 toward 200, PAST the 120
+      // midpoint (bounded loop — a scenario read, not the frame path).
+      let dwell = 0
+      while (d.committed(h)['x']! <= 130 && dwell < 120) {
+        d.step(16.67)
+        dwell += 1
+      }
+      const releaseOrigin = d.liveFor(h, 'x').value // the drifted LIVE value (REQ-GESTURE-022 origin)
+      if (releaseOrigin <= 120) {
+        return fail(`dwell did not drift past the midpoint: live=${releaseOrigin.toFixed(2)} ≤ 120`)
+      }
+      // Non-vacuity: the frozen finger (pre-fix origin) selects the NEAR snap; the drifted live value
+      // selects the FAR snap. The contention drift is exactly what flips 0 → 240.
+      if (selectReleaseTarget(FINGER, 0, undefined, SNAP) !== 0) {
+        return fail('counterfactual broken: a finger-frozen origin (110) must select snap 0')
+      }
+      const target = selectReleaseTarget(releaseOrigin, 0, undefined, SNAP)
+      if (target !== 240) {
+        return fail(
+          `drifted origin ${releaseOrigin.toFixed(2)} selected snap ${target}, expected 240`,
+        )
+      }
+      // Release: seeded start ends the hold and settles to the selected snap (velocity 0).
+      d.command(h, {
+        kind: 'start',
+        targets: { x: { to: target, from: releaseOrigin, velocity: 0 } },
+        transition: SPRING,
+        releasesGesture: true,
+      })
+      let settle = 0
+      while (d.isActive(h) && settle < 600) {
+        d.step(16.67)
+        settle += 1
+      }
+      const settled = d.committed(h)['x']!
+      return Math.abs(settled - 240) <= EPS
+        ? pass(
+            `drag→110, animate→200 drifted live to ${releaseOrigin.toFixed(2)} (past 120), ` +
+              `release v0 settled at ${settled.toFixed(3)} (snap 240); finger-frozen counterfactual → 0`,
+          )
+        : fail(`settled at ${settled.toFixed(3)}, expected snap 240 (±${EPS})`)
+    },
+  },
+]
+
+// Run one driver scenario against the reference driver, producing a ScenarioResult under the fake-host
+// engine (M1). No adapter/clock needed — the reference driver carries its own deterministic integration.
+export function runDriverScenario(scenario: DriverScenario): ScenarioResult {
+  const outcome = scenario.assert()
+  return {
+    id: scenario.id,
+    engine: FAKE_ENGINE,
+    verdict: outcome.verdict,
+    readings: [],
+    detail: outcome.detail,
+  }
+}

package/src/scenarios/gesture.ts

@@ -0,0 +1,363 @@
+// SPEC-GESTURE §4(b) Altitude-2 conformance scenarios (REQ-GESTURE-010..018 / G-INV-*). Authored ONCE,
+// engine-agnostic: each drives a recognizer sample stream through the reference gesture session on a fake
+// host and asserts a lifecycle law — grab continuity, mid-flight re-grab, velocity handoff, the release
+// seam, project-then-snap selection + monotonicity, hard clamp, rubber-band + spring-back, settle
+// accounting, cancelation, and hold-then-release. At Milestone 1 the "engine" is the deterministic session
+// under an injectable clock + MotionGraph, no rendering; the IDENTICAL scenarios re-run against motion/react
+// (web) + the native runtime at Milestone 2. `gesture.cross-engine-parity` is scalar-comparable → additively
+// OWNED in-suite by parity.ts (native core vs an injected web engine); routed here only when no web engine is
+// injected (this fake host, the on-device banner), recorded with its owner named — never a silent pass.
+
+import {
+  ManualClock,
+  ManualScheduler,
+  type MotionGraph,
+  createGestureHandoffSession,
+  createGestureSession,
+  createMotionGraph,
+  resolveViewportConstraints,
+} from '@unrulysystems/native-motion-core'
+import type { ScenarioResult, Verdict } from '../runner'
+
+const FAKE_ENGINE = 'fake-host'
+const EPS_X = 0.5 // px
+const EPS_V = 2 // px/s
+
+interface Outcome {
+  readonly verdict: Verdict
+  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 })
+
+type SessionOpts = Parameters<typeof createGestureSession>[0]
+
+function harness(opts: Omit<SessionOpts, 'graph'>): {
+  scheduler: ManualScheduler
+  graph: MotionGraph
+  session: ReturnType<typeof createGestureSession>
+} {
+  const clock = new ManualClock(0)
+  const scheduler = new ManualScheduler(clock)
+  const graph = createMotionGraph({ clock, scheduler })
+  const session = createGestureSession({ graph, ...opts })
+  return { scheduler, graph, session }
+}
+
+export interface GestureScenario {
+  readonly id: string
+  readonly requirements: readonly string[]
+  readonly assert: () => Outcome
+}
+
+export const GESTURE_SCENARIOS: readonly GestureScenario[] = [
+  {
+    id: 'gesture.grab-continuity',
+    requirements: ['REQ-GESTURE-011'],
+    assert() {
+      const { session } = harness({ initial: 100 })
+      session.begin(20) // non-zero activation dead zone
+      session.active({ t: 16, translation: 20, velocity: 0 })
+      if (Math.abs(session.value() - 100) >= EPS_X) return fail('first active frame jumped from P0')
+      session.active({ t: 32, translation: 70, velocity: 900 }) // +50 since activation
+      if (Math.abs(session.value() - 150) > EPS_X)
+        return fail(`value ${session.value()} != P0+D (150)`)
+      return pass('grab seeds from the delta since activation (C0 across the dead zone)')
+    },
+  },
+  {
+    id: 'gesture.grab-during-animation',
+    requirements: ['REQ-GESTURE-012'],
+    assert() {
+      const { scheduler, graph, session } = harness({ snap: { points: [0, 300, 600] } })
+      session.begin(0)
+      session.active({ t: 16, translation: 200, velocity: 2000 })
+      session.end({ t: 32, translation: 200, velocity: 2000 })
+      if (graph.activeAnimationCount() !== 1) return fail('release animation not counted')
+      scheduler.frames(3, 16.67)
+      const vi = session.value()
+      session.begin(1000) // re-grab mid-flight
+      if (graph.activeAnimationCount() !== 0) return fail('animation not stopped at re-grab')
+      if (Math.abs(session.value() - vi) >= EPS_X) return fail('re-grab jumped the value')
+      session.active({ t: 64, translation: 1050, velocity: 0 }) // +50 since activation
+      if (Math.abs(session.value() - (vi + 50)) > EPS_X)
+        return fail('did not continue from the live value')
+      return pass('mid-flight re-grab stops the animation and continues from the live value')
+    },
+  },
+  {
+    id: 'gesture.velocity-handoff',
+    requirements: ['REQ-GESTURE-010'],
+    assert() {
+      const { scheduler, session } = harness({ initial: 0, snap: { points: [0, 1600, 3200] } })
+      session.begin(0)
+      session.active({ t: 16, translation: 0, velocity: 2000 })
+      session.end({ t: 32, translation: 0, velocity: 2000 })
+      if (session.handoffVelocity() !== 2000)
+        return fail(`handoff ${session.handoffVelocity()} != 2000 (unscaled)`)
+      const before = session.value()
+      scheduler.frame(16.67)
+      if (session.value() <= before) return fail('value did not move in the +velocity direction')
+      return pass('the platform velocity is handed off UNSCALED with sign')
+    },
+  },
+  {
+    id: 'gesture.release-seam',
+    requirements: ['REQ-GESTURE-013'],
+    assert() {
+      const { session } = harness({ initial: 0, snap: { points: [0, 1600] } })
+      session.begin(0)
+      session.active({ t: 16, translation: 30, velocity: 1800 })
+      session.active({ t: 32, translation: 60, velocity: 1800 })
+      const xMinus = session.value()
+      session.end({ t: 48, translation: 60, velocity: 1800 })
+      if (Math.abs(session.value() - xMinus) >= EPS_X)
+        return fail('C0 broken — position jumped at release')
+      if (Math.abs((session.handoffVelocity() as number) - 1800) > EPS_V)
+        return fail('C1 broken — handoff != platform velocity')
+      return pass('release is a zero-discontinuity seam (C0 position, C1 velocity)')
+    },
+  },
+  {
+    id: 'gesture.projected-snap',
+    requirements: ['REQ-GESTURE-017'],
+    assert() {
+      const { scheduler, session } = harness({ initial: 0, snap: { points: [0, 300, 600] } })
+      session.begin(0)
+      session.active({ t: 16, translation: 50, velocity: 400 }) // at 50, nearest snap is 0
+      session.end({ t: 32, translation: 50, velocity: 400 }) // project(50,400)=370 ⇒ snap 300
+      scheduler.frames(300, 16.67)
+      if (Math.abs(session.value() - 300) > 1)
+        return fail(`landed at ${session.value()}, expected the projected snap 300`)
+      return pass(
+        'project-then-snap selects the projected snap (300), not the nearest-to-release (0)',
+      )
+    },
+  },
+  {
+    id: 'gesture.projection-monotonicity',
+    requirements: ['REQ-GESTURE-017'],
+    assert() {
+      const points = [0, 300, 600, 900]
+      let prevIndex = -1
+      for (const v of [0, 200, 500, 1000, 1500, 2500]) {
+        const { scheduler, session } = harness({ initial: 0, snap: { points } })
+        session.begin(0)
+        session.active({ t: 16, translation: 50, velocity: v })
+        session.end({ t: 32, translation: 50, velocity: v })
+        scheduler.frames(400, 16.67)
+        const index = points.indexOf(Math.round(session.value() / 300) * 300)
+        if (index < prevIndex) return fail(`snap index decreased at v=${v} (non-monotone)`)
+        prevIndex = index
+      }
+      if (prevIndex <= 0) return fail('snap index never advanced (vacuous)')
+      return pass('the selected snap index is monotone non-decreasing in |v|')
+    },
+  },
+  {
+    id: 'gesture.hard-clamp',
+    requirements: ['REQ-GESTURE-015'],
+    assert() {
+      const { session } = harness({ initial: 0, constraints: { min: 0, max: 100 } })
+      session.begin(0)
+      session.active({ t: 16, translation: 150, velocity: 0 })
+      if (session.value() !== 100) return fail('not clamped at max')
+      session.active({ t: 32, translation: -50, velocity: 0 })
+      if (session.value() !== 0) return fail('not clamped at min')
+      return pass('hard clamp holds min <= value <= max on every active frame')
+    },
+  },
+  {
+    id: 'gesture.one-sided-open-constraints',
+    requirements: ['REQ-API-024', 'REQ-GESTURE-015', 'REQ-GESTURE-023'],
+    assert() {
+      // REQ-API-024 shipping slice: open upper (max=+∞) clamps only min live; open-side release
+      // settles at the free projected landing (finite — never ±Infinity / non-settle).
+      const { scheduler, session } = harness({
+        initial: 0,
+        constraints: { min: 0, max: Number.POSITIVE_INFINITY, elastic: 0 },
+      })
+      session.begin(0)
+      session.active({ t: 16, translation: -40, velocity: 0 })
+      if (session.value() !== 0) return fail(`finite side not clamped: ${session.value()}`)
+      session.active({ t: 32, translation: 40, velocity: 500 })
+      if (session.value() !== 40) return fail(`open upper wrongly clamped live: ${session.value()}`)
+      session.end({ t: 48, translation: 40, velocity: 500 })
+      // ideal = 40 + 0.8*500 = 440
+      scheduler.frames(400, 16.67)
+      if (!Number.isFinite(session.value()))
+        return fail(`release endpoint non-finite: ${session.value()}`)
+      if (Math.abs(session.value() - 440) > 1)
+        return fail(`open-side release landed at ${session.value()}, expected ~440`)
+      if (!session.isSettled()) return fail('open-side release did not settle')
+      return pass('one-sided open bounds clamp the finite side and free-release to a finite ideal')
+    },
+  },
+  {
+    id: 'gesture.rubber-band',
+    requirements: ['REQ-GESTURE-016'],
+    assert() {
+      const { scheduler, session } = harness({
+        initial: 0,
+        constraints: { min: 0, max: 100, elastic: 0.5 },
+      })
+      session.begin(0)
+      session.active({ t: 16, translation: 160, velocity: 1000 }) // 100 + 0.5*60 = 130
+      if (Math.abs(session.value() - 130) > EPS_X)
+        return fail(`rubber-band overshoot wrong: ${session.value()}`)
+      session.end({ t: 32, translation: 160, velocity: 1000 })
+      scheduler.frames(400, 16.67)
+      if (Math.abs(session.value() - 100) > 1) return fail('did not spring back to the bound')
+      return pass('elastic overshoot = e·excess, springs back to settle exactly at the bound')
+    },
+  },
+  {
+    id: 'gesture.settle-accounting',
+    requirements: ['REQ-GESTURE-003'],
+    assert() {
+      const { scheduler, session } = harness({ initial: 0, snap: { points: [0, 300] } })
+      session.begin(0)
+      session.active({ t: 16, translation: 100, velocity: 500 })
+      if (session.isSettled()) return fail('settled while a finger is down (G-INV-7)')
+      session.end({ t: 32, translation: 100, velocity: 500 })
+      let transitions = 0
+      let prev = false
+      for (let i = 0; i < 400; i++) {
+        scheduler.frame(16.67)
+        const now = session.isSettled()
+        if (now && !prev) transitions++
+        prev = now
+      }
+      if (!session.isSettled()) return fail('stuck unsettled')
+      if (transitions !== 1) return fail(`settled ${transitions} times, expected exactly 1`)
+      return pass('unsettled while down + in flight; settles exactly once')
+    },
+  },
+  {
+    id: 'gesture.cancelation',
+    requirements: ['REQ-GESTURE-018'],
+    assert() {
+      const { scheduler, session } = harness({ initial: 0, snap: { points: [0, 300] } })
+      session.begin(0) // pre-grab value 0
+      session.active({ t: 16, translation: 100, velocity: 500 })
+      session.cancel()
+      scheduler.frames(400, 16.67)
+      if (Math.abs(session.value()) > 1) return fail('cancel did not return to the pre-grab value')
+      if (!session.isSettled()) return fail('cancel left the graph unsettled')
+      return pass('cancel returns to the pre-grab value and settles')
+    },
+  },
+  {
+    id: 'gesture.hold-then-release',
+    requirements: ['REQ-GESTURE-014'],
+    assert() {
+      const { scheduler, session } = harness({ initial: 0, snap: { points: [0, 300, 600] } })
+      session.begin(0)
+      session.active({ t: 16, translation: 250, velocity: 500 }) // dragged to 250 (nearest snap 300)
+      session.end({ t: 200, translation: 250, velocity: 0 }) // held ⇒ ~0 velocity ⇒ ideal = 250
+      scheduler.frames(300, 16.67)
+      if (Math.abs(session.value() - 300) > 1)
+        return fail(`landed at ${session.value()}, expected nearest snap 300`)
+      return pass('a ~0-velocity release snaps to the nearest point (project = origin)')
+    },
+  },
+  {
+    id: 'gesture.both-axes-per-axis-channels',
+    requirements: ['REQ-GESTURE-024', 'REQ-API-041'],
+    assert() {
+      // R15 D1: one recognizer stream drives one independent channel PER AXIS — a bounded axis
+      // clamps and springs to its bound while the free axis projects its own landing. The wiring
+      // composes two of these per-axis sessions over one Pan stream (dragGestureWiring.test.ts
+      // pins that composition); this scenario pins the per-axis SEMANTIC they compose.
+      const xHarness = harness({ initial: 0, constraints: { min: 0, max: 100, elastic: 0 } })
+      const yHarness = harness({ initial: 0 })
+      xHarness.session.begin(0)
+      yHarness.session.begin(0)
+      xHarness.session.active({ t: 16, translation: 250, velocity: 900 })
+      yHarness.session.active({ t: 16, translation: 250, velocity: 900 })
+      if (xHarness.session.value() !== 100)
+        return fail(`bounded axis not clamped live: ${xHarness.session.value()}`)
+      if (yHarness.session.value() !== 250)
+        return fail(`free axis wrongly clamped: ${yHarness.session.value()}`)
+      xHarness.session.end({ t: 32, translation: 250, velocity: 900 })
+      yHarness.session.end({ t: 32, translation: 250, velocity: 900 })
+      xHarness.scheduler.frames(400, 16.67)
+      yHarness.scheduler.frames(400, 16.67)
+      // Bounded axis: past the max at release → spring-back settles exactly at 100
+      // (REQ-GESTURE-016). Free axis: projected landing 250 + 0.8·900 = 970 (REQ-GESTURE-023).
+      if (Math.abs(xHarness.session.value() - 100) > 1)
+        return fail(`bounded axis settled at ${xHarness.session.value()}, expected 100`)
+      if (Math.abs(yHarness.session.value() - 970) > 1)
+        return fail(`free axis landed at ${yHarness.session.value()}, expected 970`)
+      return pass(
+        'per-axis channels: the bounded axis clamps + springs to its bound while the free axis projects its own landing',
+      )
+    },
+  },
+  {
+    id: 'gesture.ref-constraints-viewport',
+    requirements: ['REQ-GESTURE-028', 'REQ-API-042'],
+    assert() {
+      // R15 D2: the element-ref channel computes the pin's viewport constraints from the
+      // measured boxes — bounds relative to the draggable's current layout, flipped per axis
+      // when the container is shorter than the child — then the session clamps with them.
+      const xBounds = resolveViewportConstraints({ min: 100, max: 180 }, { min: 50, max: 250 })
+      if (xBounds.min !== -50 || xBounds.max !== 70)
+        return fail(`bounds ${xBounds.min}..${xBounds.max} != -50..70`)
+      const flipped = resolveViewportConstraints({ min: 0, max: 400 }, { min: 50, max: 250 })
+      if (flipped.min !== -150 || flipped.max !== 50)
+        return fail(`flipped ${flipped.min}..${flipped.max} != -150..50`)
+      // The per-grab override clamps THIS grab with the measured bounds. Native-motion
+      // re-measures at every grab, so the runtime carries them on the DRIVER-INTEGRATED
+      // handoff session (the wiring's session) — a pure event fold, no graph/scheduler.
+      const session = createGestureHandoffSession({})
+      session.begin(0, { value: 100 }, { constraints: { min: -50, max: 70, elastic: 0 } })
+      session.active(30) // raw 130 → hard max clamp
+      if (session.value() !== 70) return fail(`no max clamp live: ${session.value()}`)
+      session.active(-160) // raw -60 → hard min clamp
+      if (session.value() !== -50) return fail(`no min clamp live: ${session.value()}`)
+      session.end(0, -50)
+      // Elastic: the finger rests past the bound rubber-banded; the release hands off the bound
+      // as its target (REQ-GESTURE-016's spring-back seam — the integrator owns the spring, so
+      // the law asserts on the handed-off target).
+      session.begin(0, { value: 100 }, { constraints: { min: -50, max: 70, elastic: 0.35 } })
+      session.active(-160) // raw -60 → -50 − 0.35·10 = -53.5
+      const past = session.value()
+      if (Math.abs(past - -53.5) > EPS_X) return fail(`no rubber-band past the min: ${past}`)
+      const handoff = session.end(0, past)
+      if (handoff.target !== -50) return fail(`release target ${handoff.target} != the bound -50`)
+      return pass(
+        'viewport constraints: pin bounds computed from measured boxes (incl. the smaller-container flip), the per-grab override clamps live, and a release past the bound hands off the bound as its target',
+      )
+    },
+  },
+  {
+    id: 'gesture.cross-engine-parity',
+    requirements: ['REQ-CONFORM-002'],
+    assert() {
+      // G-INV-10 parity is scalar-comparable → additively OWNED in-suite; the REAL motion/react web
+      // engine is constructed and executed in native-motion-web/src/gestureParity.test.ts (parity.ts is
+      // the comparator seam it drives). This fake host injects no web engine, so the row is routed here.
+      return unassertable(
+        'Owner: packages/native-motion-web/src/gestureParity.test.ts — it constructs the REAL ' +
+          "motion/react web engine (motion's inertia) and runs runGestureParityScenario (the " +
+          'src/parity.ts comparator) vs the native-core reference, GESTURE_PARITY release-endpoint ' +
+          'band; owned in-suite there. Routed here: this fake host injects no web engine.',
+      )
+    },
+  },
+]
+
+// Run one gesture scenario against the reference session, producing a ScenarioResult under the fake-host
+// engine (M1). The session carries its own deterministic clock/graph — no adapter needed.
+export function runGestureScenario(scenario: GestureScenario): ScenarioResult {
+  const outcome = scenario.assert()
+  return {
+    id: scenario.id,
+    engine: FAKE_ENGINE,
+    verdict: outcome.verdict,
+    readings: [],
+    detail: outcome.detail,
+  }
+}