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

package/CHANGELOG.md

@@ -0,0 +1,14 @@
+# @unrulysystems/native-motion-conformance
+
+## 0.1.0-alpha.0
+
+### Minor Changes
+
+- Initial alpha prerelease: the M3-era public surface (layout, presence, drag, gestures, variants,
+  orchestration, value types) with the cross-engine conformance suite published alongside the
+  runtime packages.
+
+### Patch Changes
+
+- Updated dependencies
+  - @unrulysystems/native-motion-core@0.1.0-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Unruly Systems LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,66 @@
+# @unrulysystems/native-motion-conformance
+
+The cross-engine conformance harness (SPEC-CONFORMANCE, private). One engine-agnostic scenario
+format, authored once, executed against two engines — the native core and the pinned web oracle
+(`motion-dom@12.42.2`, see [SEAMS.md](./SEAMS.md)) — then differentially compared within
+ratified tolerance bands. Its job is to make "the loop can never widen a band or silently skip
+a check" mechanical.
+
+## The accounting model (the load-bearing idea)
+
+Every scenario run returns one of three verdicts — `pass` / `fail` / `unassertable` — and the
+RUNNER, never the scenario author, decides. `aggregateSuite` (`src/suite.ts`) folds all
+per-(scenario, engine) results fail-closed:
+
+- any `fail` → suite fails; an empty result set → suite fails;
+- `unassertable` is a ROUTED obligation, not a skip. Cross-engine-parity rows discharge in one of
+  two ways (SPEC-CONFORMANCE §3, ratified Option A — R7 M5):
+  - **Scalar-comparable → owned in-suite.** When the comparison reduces to a scalar, a real second
+    engine is injected and its SAME-ID `pass` is ADDED via the parity seam (`src/parity.ts`), never
+    edited in, so the row flips `unassertable` → owned without touching any scenario.
+    `gesture.cross-engine-parity` works this way (native core vs an injected motion/react web engine).
+  - **External-evidence-only → stays `unassertable`, discharged elsewhere.** When parity needs a real
+    DOM/layout engine, real host components, or composite aesthetic judgment, no in-process engine can
+    assert it, so the deterministic suite keeps the row `unassertable` and it is asserted at a NAMED
+    external altitude — declared either as a frozen counterpart record (`LAYOUT_PARITY_COUNTERPART` /
+    `LAYOUT_IDENTITY_PARITY_COUNTERPART` → the Playwright Chromium gate) or, for
+    `CMP-R7-cross-engine-parity`, an owner-naming reason pointing at its executed legs
+    (`variants.e2e.ts` + `PROOF.md §R7`), or for `CMP-R8-cross-engine-parity`, its executed Chromium
+    web leg (`keyframes.e2e.ts`, 20/20) and executed M5 `PROOF.md §R8` device keyframes card
+    (Android real-touch verdicts + measured arcs; iOS AUTO-RUN 13/13 + measured peaks), or for
+    `CMP-R9-cross-engine-parity`, its executed Chromium legs
+    (`examples.smoke.e2e.ts` + `text-layout.e2e.ts` + `image-gallery.e2e.ts`, 22/22) and
+    executed M5 `PROOF.md §R9` device element cards (Android gallery 17/17 including stable
+    image-gallery post-fix; iOS AUTO-RUN COMPLETE 17/17 with wallpaper loaded).
+    `appstore-choreography.cross-engine-parity` is likewise external (SPRING goldens +
+    Chromium). These never flip to an in-suite `pass`; `routed > 0 → FAIL` still binds.
+
+## Surface map
+
+| Area            | Role                                                                                | Key files                       |
+| --------------- | ----------------------------------------------------------------------------------- | ------------------------------- |
+| scenario format | Pure-data timelines + invariants + declared capabilities                            | `scenario.ts`, `scenarios/*.ts` |
+| adapters        | Per-engine determinism-fixed wrappers (native core; motion-dom under manual timing) | `adapter.ts`, `adapters/`       |
+| runner          | Drives one scenario on one engine → three-valued verdict                            | `runner.ts`                     |
+| comparator      | Pure cross-engine differential                                                      | `comparator.ts`                 |
+| suite           | Fail-closed aggregation                                                             | `suite.ts`                      |
+| config          | Ratified tolerance bands — never loop-tunable                                       | `config.ts`                     |
+| authoring       | Registry-backed capability gate at author time                                      | `authoring.ts`                  |
+| parity          | The additive cross-engine ownership seam                                            | `parity.ts`                     |
+
+Reader note: `runSpringScenario`/`runValueTypeScenario` mark per-engine readings `pass: true`
+by construction — for those kinds the real verdict is the cross-engine DIFFERENTIAL, not the
+single-engine run (`runner.ts` explains this inline).
+
+## Verification
+
+113 tests / 17 files: 10 cross-engine conformance suites (L2's `layout-identity` and L4's
+`appstore-choreography` are the ninth and tenth), 5 harness unit suites (including the
+fail-closed accounting proofs), 1 wiring smoke, and `motion-seams.canary.test.ts` — canaries
+that pin the exact motion internals the harness drives, so a `motion` upgrade fails loudly
+BEFORE it can skew a verdict. `scripts/gen-*-goldens.mjs` (not CI gates) regenerate core's
+golden files from the pinned oracle on an intentional bump.
+
+```bash
+cd packages/conformance && bunx vitest run
+```

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@unrulysystems/native-motion-conformance",
+  "version": "0.1.0-alpha.0",
+  "license": "MIT",
+  "files": [
+    "src",
+    "CHANGELOG.md",
+    "!src/**/*.test.*"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./adapter": "./src/adapter.ts",
+    "./adapters/motion-dom": "./src/adapters/motion-dom.ts",
+    "./adapters/native": "./src/adapters/native.ts",
+    "./comparator": "./src/comparator.ts",
+    "./config": "./src/config.ts",
+    "./declarations": "./src/declarations.ts",
+    "./runner": "./src/runner.ts",
+    "./scenarios/*": "./src/scenarios/*.ts"
+  },
+  "scripts": {
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@unrulysystems/native-motion-core": "0.1.0-alpha.0",
+    "motion-dom": "12.42.2",
+    "motion-utils": "12.39.0"
+  },
+  "devDependencies": {
+    "vitest": "^4.1.9"
+  }
+}

package/src/adapter.ts

@@ -0,0 +1,42 @@
+// The engine adapter seam (REQ-CONFORM-013). A thin, canary-guarded wrapper that drives ONE engine
+// along a scenario timeline. Each engine gets exactly one determinism mechanism, fixed here and never
+// crossed: the native core uses the injectable `ManualClock`; motion-dom uses
+// `MotionGlobalConfig.useManualTiming` + `time.set`. The runner talks only to this interface, so it
+// stays engine-agnostic.
+
+import type { Capability, MotionScalar, SpringKind, SpringTrajectorySpec } from './scenario'
+
+// A single value under an engine's control, with the engine's clock exposed as `setTime` so the
+// runner can anchor time before each input/assertion. `getVelocity` is always numeric.
+export interface EngineValue {
+  // Anchor the engine's clock to absolute time `tMs` (monotonic, non-decreasing within a scenario).
+  setTime(tMs: number): void
+  set(v: MotionScalar): void
+  jump(v: MotionScalar): void
+  get(): MotionScalar
+  getVelocity(): number
+}
+
+// One sampled point of a spring/timing trajectory: the engine's value and velocity at time `t`.
+export interface TrajectoryPoint {
+  readonly t: number
+  readonly value: number
+  readonly velocity: number
+}
+
+export interface EngineAdapter {
+  readonly id: string
+  readonly capabilities: readonly Capability[]
+  createValue(initial: MotionScalar): EngineValue
+  // Present iff the engine provides the `spring-trajectory` capability: build a generator from `spec`
+  // seeded with [from, velocity] and sample value+velocity at each `tGrid` point (SPEC-SPRING §5).
+  sampleTrajectory?(
+    kind: SpringKind,
+    spec: SpringTrajectorySpec,
+    tGrid: readonly number[],
+  ): readonly TrajectoryPoint[]
+  // Present iff the engine provides the `value-type-mix` capability: parse two raw property values, mix
+  // at `progress` ∈ [0,1], and project the committed value (SPEC-VALUE-TYPES §5). May throw on an
+  // intentional loud failure (unit/shape mismatch) — the runner surfaces that to the divergence test.
+  mixValueType?(from: string, to: string, progress: number): MotionScalar
+}

package/src/adapters/motion-dom.ts

@@ -0,0 +1,96 @@
+// motion-dom engine adapter: drives the pinned web reference engine (motion-dom@12.42.2). Determinism
+// for state-level VALUE scenarios has two parts (REQ-CONFORM-013b): (1) PRIMARY — the runner reads
+// synchronously right after each `time.set(t)`, so Motion's `time.now()` returns exactly `t` (the set
+// value persists until a microtask clears it, and the runner never yields mid-scenario); (2) DEFENSE
+// — `useManualTiming = true` so that IF `now` is ever cleared, `time.now()` falls back to the
+// controlled `frameData.timestamp` rather than `performance.now()` (wall time), which would
+// false-stale every velocity. This is Motion's production JS path for velocity/handoffs, so it is
+// state-level authoritative. (Frame stepping — where `useManualTiming` becomes load-bearing on its
+// own — arrives with the animation/spring scenarios, not this state-level slice.)
+
+import { motionValue, spring, mix, time } from 'motion-dom'
+import { cubicBezier, easingDefinitionToFunction, MotionGlobalConfig } from 'motion-utils'
+import type { EngineAdapter, EngineValue, TrajectoryPoint } from '../adapter'
+import type { MotionScalar, SpringKind, SpringTrajectorySpec } from '../scenario'
+
+// Timing defaults must match the native timing generator (REQ-TIMING-002): ease [0.25,0.1,0.35,1],
+// duration 300ms. Velocity is Motion's 5ms finite-diff of the value; the spring path uses Motion's
+// ANALYTIC gen.velocity(t) — both are the native solver's parity targets from the M1/M3 goldens.
+const DEFAULT_TIMING_EASE = [0.25, 0.1, 0.35, 1] as const
+const DEFAULT_TIMING_DURATION_MS = 300
+const VELOCITY_SAMPLE_MS = 5
+const clamp01 = (v: number): number => Math.max(0, Math.min(1, v))
+
+// Set the defense ONCE at module init; never toggled (the `motion-seams.canary` proves it is on).
+MotionGlobalConfig.useManualTiming = true
+
+export function motionDomAdapter(): EngineAdapter {
+  return {
+    id: 'motion-dom',
+    capabilities: ['numeric-velocity', 'spring-trajectory', 'value-type-mix'],
+    // Motion's 2-arg `mix(from, to)` returns a mixer that dispatches on value family (number/color/
+    // complex); call it at `progress` for the committed value (SPEC-VALUE-TYPES §5). Motion never throws
+    // here — a unit/shape mismatch warns+snaps, and named colors (no DOM) snap to the target.
+    mixValueType(from: string, to: string, progress: number): MotionScalar {
+      return mix(from, to)(progress) as MotionScalar
+    },
+    sampleTrajectory(
+      kind: SpringKind,
+      spec: SpringTrajectorySpec,
+      tGrid: readonly number[],
+    ): readonly TrajectoryPoint[] {
+      if (kind === 'timing') {
+        const duration = spec.duration ?? DEFAULT_TIMING_DURATION_MS
+        const ease = spec.ease ?? DEFAULT_TIMING_EASE
+        // Family-2: named curves (circ*/back*/anticipate/ease*) via motion-utils lookup;
+        // cubic tuples still go through cubicBezier (REQ-TIMING-001).
+        const easeFn =
+          typeof ease === 'string'
+            ? easingDefinitionToFunction(ease)
+            : cubicBezier(ease[0], ease[1], ease[2], ease[3])
+        const value = (t: number): number => mix(spec.from, spec.to, easeFn(clamp01(t / duration)))
+        return tGrid.map((t) => {
+          const prevT = Math.max(t - VELOCITY_SAMPLE_MS, 0)
+          const dt = t - prevT
+          const velocity = dt ? ((value(t) - value(prevT)) / dt) * 1000 : 0
+          return { t, value: value(t), velocity }
+        })
+      }
+      const gen = spring({
+        keyframes: [spec.from, spec.to],
+        velocity: spec.velocity ?? 0,
+        ...(spec.stiffness !== undefined ? { stiffness: spec.stiffness } : {}),
+        ...(spec.damping !== undefined ? { damping: spec.damping } : {}),
+        ...(spec.mass !== undefined ? { mass: spec.mass } : {}),
+        ...(spec.duration !== undefined ? { duration: spec.duration } : {}),
+        ...(spec.bounce !== undefined ? { bounce: spec.bounce } : {}),
+        ...(spec.visualDuration !== undefined ? { visualDuration: spec.visualDuration } : {}),
+      })
+      // gen.velocity is Motion's ANALYTIC generator velocity (px/s); typed optional, always present
+      // for a physics spring.
+      return tGrid.map((t) => ({ t, value: gen.next(t).value, velocity: gen.velocity?.(t) ?? 0 }))
+    },
+    createValue(initial: MotionScalar): EngineValue {
+      const value = motionValue(initial)
+      return {
+        // `time.set` schedules a `queueMicrotask(clearTime)`; the runner reads synchronously right
+        // after, before the microtask can clear the anchored timestamp (see M1B packet gotchas).
+        setTime(tMs: number): void {
+          time.set(tMs)
+        },
+        set(v: MotionScalar): void {
+          value.set(v)
+        },
+        jump(v: MotionScalar): void {
+          value.jump(v)
+        },
+        get(): MotionScalar {
+          return value.get()
+        },
+        getVelocity(): number {
+          return value.getVelocity()
+        },
+      }
+    },
+  }
+}

package/src/adapters/native.ts

@@ -0,0 +1,95 @@
+// Native engine adapter: drives @unrulysystems/native-motion-core (the engine under test) through
+// its PUBLIC surface only — no reach into `MotionValueImpl` internals. Determinism mechanism: the
+// injectable `ManualClock` (REQ-CONFORM-013a). Each value gets its own graph + clock so scenarios are
+// isolated and time advances independently.
+
+import {
+  createMotionGraph,
+  ManualClock,
+  ManualScheduler,
+  mix,
+  parseValue,
+  resolveSpringGenerator,
+  timingGenerator,
+  transformValue,
+} from '@unrulysystems/native-motion-core'
+import type { SpringConfig, TimingConfig } from '@unrulysystems/native-motion-core'
+import type { EngineAdapter, EngineValue, TrajectoryPoint } from '../adapter'
+import type { MotionScalar, SpringKind, SpringTrajectorySpec } from '../scenario'
+
+export function nativeAdapter(): EngineAdapter {
+  return {
+    id: 'native',
+    // The native core also owns a graph settle ledger (createMotionGraph.whenSettled/isSettled),
+    // which motion-dom's value has no analogue for — declared so settle scenarios route to native.
+    // `spring-trajectory`: the core's analytic solver/timing generators (SPEC-SPRING §5).
+    // `value-type-mix`: the core value-type seam parseValue→mix→transformValue (SPEC-VALUE-TYPES §5).
+    capabilities: ['numeric-velocity', 'settle-ledger', 'spring-trajectory', 'value-type-mix'],
+    // Parse both raw values, mix at `progress`, project the committed value. Throws on an intentional
+    // loud failure (per-slot unit mismatch, complex-shape mismatch) — surfaced to the divergence test.
+    mixValueType(from: string, to: string, progress: number): MotionScalar {
+      return transformValue(mix(parseValue(from), parseValue(to), progress))
+    },
+    sampleTrajectory(
+      kind: SpringKind,
+      spec: SpringTrajectorySpec,
+      tGrid: readonly number[],
+    ): readonly TrajectoryPoint[] {
+      const seed = { from: spec.from, velocity: spec.velocity ?? 0 }
+      const factory =
+        kind === 'timing'
+          ? timingGenerator(spec.to, timingConfigOf(spec))
+          : resolveSpringGenerator(spec.to, springConfigOf(spec))
+      const gen = factory(seed)
+      return tGrid.map((t) => {
+        const s = gen.sample(t)
+        return { t, value: s.value, velocity: s.velocity }
+      })
+    },
+    createValue(initial: MotionScalar): EngineValue {
+      const clock = new ManualClock()
+      const scheduler = new ManualScheduler(clock)
+      const graph = createMotionGraph({ clock, scheduler })
+      const value = graph.motionValue<MotionScalar>(initial)
+      return {
+        // Absolute-time anchor: the injectable clock only moves on advance, so step to `tMs`.
+        setTime(tMs: number): void {
+          clock.advance(tMs - clock.now())
+        },
+        set(v: MotionScalar): void {
+          value.set(v)
+        },
+        jump(v: MotionScalar): void {
+          value.jump(v)
+        },
+        get(): MotionScalar {
+          return value.get()
+        },
+        getVelocity(): number {
+          return value.getVelocity()
+        },
+      }
+    },
+  }
+}
+
+// Build a core SpringConfig / TimingConfig from a scenario spec, omitting undefined keys so
+// resolution precedence (REQ-SPRING-006) sees only the keys the scenario actually set
+// (`exactOptionalPropertyTypes` also forbids passing explicit `undefined`).
+function springConfigOf(spec: SpringTrajectorySpec): SpringConfig {
+  const c: SpringConfig = {}
+  if (spec.stiffness !== undefined) c.stiffness = spec.stiffness
+  if (spec.damping !== undefined) c.damping = spec.damping
+  if (spec.mass !== undefined) c.mass = spec.mass
+  if (spec.duration !== undefined) c.duration = spec.duration
+  if (spec.bounce !== undefined) c.bounce = spec.bounce
+  if (spec.visualDuration !== undefined) c.visualDuration = spec.visualDuration
+  return c
+}
+
+function timingConfigOf(spec: SpringTrajectorySpec): TimingConfig {
+  const c: TimingConfig = {}
+  if (spec.duration !== undefined) c.duration = spec.duration
+  if (spec.ease !== undefined) c.ease = spec.ease
+  return c
+}

package/src/authoring.ts

@@ -0,0 +1,78 @@
+// SPEC-UNIVERSAL-SUBSET §5.5 — the conformance authoring gate (REQ-SUBSET-018). The scenario author
+// consumes the frozen universal-subset registry as its capability whitelist: every capability a scenario
+// references must be a registry member (else it is rejected as unknown), and — when a host is given —
+// must be declared by that host (else rejected as off-host). Rejection is a THROWN error at author time:
+// a scenario over an unknown or off-host capability is not silently skipped and does not count toward
+// coverage (fail-closed). Each referenced capability's web assertion is routed to the altitude the
+// registry prescribes via webEnginePath. Kept out of `scenario.ts` (which is pure engine-free data) so
+// that file stays import-free; this module is the registry-consuming author.
+
+import {
+  type HostCapabilities,
+  UNIVERSAL_SUBSET,
+  resolveCapability,
+} from '@unrulysystems/native-motion-core'
+
+// The web assertion altitude a scenario's property is checked at (REQ-SUBSET-015/-018): an accelerated
+// property is scrubbed as a real-browser WAAPI trajectory plus a jsdom WAAPI-contract/end-state check; a
+// JS-path property is state-asserted in jsdom. A shipping:'deferred' member is neither — it is
+// EXPECTED-LOUD (REQ-SUBSET-012): the scenario asserts it FAILS LOUD on both engines until its rung, never
+// that it animates (coverage). The registry's `shipping` field gates first, then `webEnginePath`.
+export type WebAltitude = 'real-browser-trajectory+jsdom-contract' | 'jsdom-state' | 'expected-loud'
+
+// The animation targets a scenario declares. Keys are capability keys; values are irrelevant to the
+// membership gate (the gate validates KEYS, the value types are VALUE-TYPES' concern).
+export interface AuthoredTargets {
+  readonly initial?: Readonly<Record<string, unknown>>
+  readonly animate?: Readonly<Record<string, unknown>>
+  readonly exit?: Readonly<Record<string, unknown>>
+}
+
+export interface AuthoredScenario {
+  readonly keys: readonly string[]
+  readonly webAltitudes: ReadonlyMap<string, WebAltitude>
+}
+
+// Route a capability's web assertion by its registry web-engine path. Throws for an unknown key so a
+// mis-typed capability cannot be silently routed to a default altitude.
+export function webAltitudeFor(key: string): WebAltitude {
+  const entry = UNIVERSAL_SUBSET.get(key)
+  if (entry === undefined) {
+    throw new Error(`unknown capability '${key}': cannot route a web assertion altitude for it.`)
+  }
+  // Shipping gates FIRST (REQ-SUBSET-012, r11 major 33): a deferred member is expected-loud, never a
+  // coverage altitude, regardless of its JS/accelerated path — a coverage altitude would assert it
+  // animates, but a deferred surface fails loud on both engines until its rung.
+  if (entry.shipping === 'deferred') return 'expected-loud'
+  return entry.webEnginePath === 'accelerated'
+    ? 'real-browser-trajectory+jsdom-contract'
+    : 'jsdom-state'
+}
+
+// Author-time capability gate. Collects every key across initial/animate/exit, rejects any that is not a
+// registry member (unknown) or — with a host — not declared by the host (off-host), and returns the
+// referenced keys with their routed altitudes. Fails closed on the FIRST offending key.
+export function authorScenario(
+  targets: AuthoredTargets,
+  host?: HostCapabilities,
+): AuthoredScenario {
+  const keys = new Set<string>()
+  for (const target of [targets.initial, targets.animate, targets.exit]) {
+    if (target === undefined) continue
+    for (const key of Object.keys(target)) keys.add(key)
+  }
+
+  const webAltitudes = new Map<string, WebAltitude>()
+  for (const key of keys) {
+    if (host !== undefined) {
+      // resolveCapability enforces BOTH unknown (registry membership) and off-host (host declaration),
+      // with the descriptive REQ-SUBSET-014 message naming the key + supporting hosts.
+      resolveCapability(host, key)
+    } else if (!UNIVERSAL_SUBSET.has(key)) {
+      throw new Error(`unknown capability '${key}': not in the universal-subset registry.`)
+    }
+    webAltitudes.set(key, webAltitudeFor(key))
+  }
+
+  return { keys: [...keys], webAltitudes }
+}

package/src/comparator.ts

@@ -0,0 +1,129 @@
+// The independent cross-engine comparator (REQ-CONFORM-014). A PURE function over two engines'
+// reading series for the SAME scenario: neither engine grades itself; this differentiates the two
+// independent makers' outputs within the ratified tolerance band. Both results must come from the
+// same scenario (same timeline → same reading order), so readings are zipped by index.
+
+import {
+  EPS_ANGLE,
+  EPS_COLOR_CHANNEL,
+  EPS_LENGTH,
+  EPS_UNITLESS,
+  parseValue,
+  type TypedValue,
+} from '@unrulysystems/native-motion-core'
+import { scalarWithin, type ScenarioResult } from './runner'
+import type { MotionScalar, ToleranceBand } from './scenario'
+
+export interface CrossEngineMismatch {
+  readonly at: number
+  readonly kind: 'velocity' | 'value'
+  readonly a: MotionScalar
+  readonly b: MotionScalar
+}
+
+export interface CrossEngineResult {
+  readonly id: string
+  readonly agree: boolean
+  readonly mismatches: readonly CrossEngineMismatch[]
+}
+
+export function compareEngines(
+  a: ScenarioResult,
+  b: ScenarioResult,
+  band: ToleranceBand,
+): CrossEngineResult {
+  const mismatches: CrossEngineMismatch[] = []
+  const n = Math.min(a.readings.length, b.readings.length)
+  for (let i = 0; i < n; i++) {
+    const ra = a.readings[i]
+    const rb = b.readings[i]
+    if (ra === undefined || rb === undefined) continue
+    const tol = ra.kind === 'velocity' ? band.velocity : band.value
+    if (ra.kind !== rb.kind || !scalarWithin(ra.actual, rb.actual, tol)) {
+      mismatches.push({ at: ra.at, kind: ra.kind, a: ra.actual, b: rb.actual })
+    }
+  }
+  // Fail-closed: differing reading counts are a structural disagreement even if the common prefix
+  // matches (the engines ran different assertion sets).
+  const agree = mismatches.length === 0 && a.readings.length === b.readings.length
+  return { id: a.id, agree, mismatches }
+}
+
+// The per-type tolerance for a numeric slot's unit (SPEC-VALUE-TYPES §5): lengths within EPS_LENGTH,
+// angles within EPS_ANGLE, unitless/percent within EPS_UNITLESS — the ratified floors, never widened.
+function epsForUnit(unit: string): number {
+  if (unit === 'px' || unit === 'vw' || unit === 'vh') return EPS_LENGTH
+  if (unit === 'deg' || unit === 'rad') return EPS_ANGLE
+  return EPS_UNITLESS
+}
+
+// Flatten a typed value into its scalar channels, each with its own per-type tolerance. A color yields
+// its four channels at EPS_COLOR_CHANNEL; a complex yields each slot's channels.
+// auto/calc (REQ-VALUETYPE-013) are measure-resolved to px BEFORE mix — unresolved they have no
+// comparable scalar channels. Empty channel lists force a structural mismatch (fail-closed), never
+// a silent partial parse of interior %/px tokens.
+function channelsOf(tv: TypedValue): readonly { readonly value: number; readonly eps: number }[] {
+  switch (tv.kind) {
+    case 'numeric':
+      return [{ value: tv.value.value, eps: epsForUnit(tv.value.unit) }]
+    case 'color':
+      return [
+        { value: tv.value.red, eps: EPS_COLOR_CHANNEL },
+        { value: tv.value.green, eps: EPS_COLOR_CHANNEL },
+        { value: tv.value.blue, eps: EPS_COLOR_CHANNEL },
+        { value: tv.value.alpha, eps: EPS_COLOR_CHANNEL },
+      ]
+    case 'complex':
+      return tv.value.slots.flatMap((s) =>
+        s.kind === 'color'
+          ? [
+              { value: s.value.red, eps: EPS_COLOR_CHANNEL },
+              { value: s.value.green, eps: EPS_COLOR_CHANNEL },
+              { value: s.value.blue, eps: EPS_COLOR_CHANNEL },
+              { value: s.value.alpha, eps: EPS_COLOR_CHANNEL },
+            ]
+          : [{ value: s.value, eps: epsForUnit(s.unit) }],
+      )
+    case 'auto':
+    case 'calc':
+    // Discrete keywords have no scalar channels either (T23 B) — the empty list rides the same
+    // fail-closed arm below: a discrete reading never agrees by equal-zero length.
+    case 'discrete':
+      return []
+  }
+}
+
+// Cross-engine value-type comparison (SPEC-VALUE-TYPES §5, REQ-CONFORM-014). Zips two engines' recomposed
+// value series by index, DECOMPOSES each committed string via the core parser, and checks every typed
+// channel within its per-type epsilon (EPS_COLOR_CHANNEL / EPS_LENGTH / …) — never byte-equality, never a
+// widened band. Neither engine grades itself: parseValue is a neutral structural decomposition applied
+// symmetrically to both outputs. A differing channel count (e.g. a snap to a different family) is a
+// structural mismatch.
+export function compareValueTypeSeries(a: ScenarioResult, b: ScenarioResult): CrossEngineResult {
+  const mismatches: CrossEngineMismatch[] = []
+  const n = Math.min(a.readings.length, b.readings.length)
+  for (let i = 0; i < n; i++) {
+    const ra = a.readings[i]
+    const rb = b.readings[i]
+    if (ra === undefined || rb === undefined) continue
+    const ca = channelsOf(parseValue(String(ra.actual)))
+    const cb = channelsOf(parseValue(String(rb.actual)))
+    // Unresolved auto/calc yield empty channel lists — never agree by equal-zero length
+    // (fail-closed: measure-resolve to px before cross-engine compare).
+    if (ca.length === 0 || cb.length === 0 || ca.length !== cb.length) {
+      mismatches.push({ at: ra.at, kind: 'value', a: ra.actual, b: rb.actual })
+      continue
+    }
+    for (let k = 0; k < ca.length; k++) {
+      const xa = ca[k]
+      const xb = cb[k]
+      if (xa === undefined || xb === undefined) continue
+      if (Math.abs(xa.value - xb.value) > Math.max(xa.eps, xb.eps)) {
+        mismatches.push({ at: ra.at, kind: 'value', a: ra.actual, b: rb.actual })
+        break
+      }
+    }
+  }
+  const agree = mismatches.length === 0 && a.readings.length === b.readings.length
+  return { id: a.id, agree, mismatches }
+}

package/src/config.ts

@@ -0,0 +1,22 @@
+// The ratified cross-engine tolerance band (REQ-CONFORM-014). Not loop-tunable: the loop may never
+// widen these to force a green — a real divergence is a `fail` recorded as a decision, then the core
+// is adjusted. `velocity` is bound to the core's pinned `EPS_VELOCITY` (its at-rest velocity epsilon)
+// so the band tracks a single source of truth rather than a duplicated magic number; `value` is exact
+// for state-level scalars (no interpolation at this altitude).
+
+import { constants } from '@unrulysystems/native-motion-core'
+import type { ToleranceBand } from './scenario'
+
+export const DEFAULT_BAND: ToleranceBand = {
+  velocity: constants.EPS_VELOCITY,
+  value: 0,
+}
+
+// Spring/timing cross-engine band (SPEC-SPRING §5): the ratified physics-parity tolerance —
+// restDelta (0.5) on value, restSpeed (2, the default rest speed from REQ-SPRING-003) on velocity.
+// `value` ties to the core's `EPS_TRAJ`; the velocity floor is stated here because the core does not
+// export its internal rest thresholds. Not loop-tunable — a real divergence is a fail, never a widen.
+export const SPRING_BAND: ToleranceBand = {
+  value: constants.EPS_TRAJ,
+  velocity: 2,
+}

package/src/declarations.ts

@@ -0,0 +1,21 @@
+// The doctrine-census declarations the conformance differentials cite by id.
+//
+// This is one half of a two-package pair, and it lives in a MODULE rather than in the test file
+// that uses it so the other half can import the actual values. The differential
+// (`mix-polymorphic.conformance.test.ts`) builds every non-`match` row's `owner` string from these
+// ids; `packages/example-harness/src/parity/doctrine.test.ts` asserts every id here resolves to a
+// LIVE census declaration. Neither half can live in the other package — example-harness depends on
+// conformance, never the reverse.
+//
+// The direction that matters is the one the harness cannot already see. A census id renamed in
+// `census.ts` already fails `check:parity-doctrine` through `REQUIRED_SEMANTIC_CENSUS_IDS`; what
+// nothing caught before is a CITATION here going stale, leaving a differential row attributing its
+// debt to a declaration that no longer exists. Asserting these values against the live census is
+// that check. Asserting them against the owner strings built from them is NOT — that is a
+// tautology, and it passed a deliberately dead id (H1 round-3 review MAJOR).
+export const CENSUS_DECLARATIONS = {
+  seam: 'motion.value-seam-strictness',
+  color: 'motion.color-syntax-capability',
+} as const
+
+export type CensusDeclarationKey = keyof typeof CENSUS_DECLARATIONS