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

package/src/scenarios/presence.ts

@@ -0,0 +1,302 @@
+// SPEC-PRESENCE §4(b) Altitude-2 conformance scenarios (REQ-PRESENCE-011/012/013/015/016/017/018). Authored
+// ONCE, engine-agnostic: each asserts a presence lifecycle law against the reference controller on a fake
+// host — retention, the settle gate, cancel-on-reentry continuity, immediate unmount, manual deferral, wait-
+// mode ordering, concurrent exits, first-commit enter suppression, and popLayout lifecycle ordering. At
+// Milestone 1 the "engine" is the deterministic controller under an injectable clock + MotionGraph, no
+// rendering; host geometry is verified by the real web/native integration floors at Milestone 2.
+
+import {
+  ManualClock,
+  ManualScheduler,
+  type MotionGraph,
+  type Transition,
+  createMotionGraph,
+  createPresenceController,
+} from '@unrulysystems/native-motion-core'
+import type { ScenarioResult, Verdict } from '../runner'
+
+const FAKE_ENGINE = 'fake-host'
+const EPS_X = 1e-3 // of the [0,1] progress range
+
+interface Outcome {
+  readonly verdict: Verdict
+  readonly detail: string
+}
+const pass = (detail: string): Outcome => ({ verdict: 'pass', detail })
+const fail = (detail: string): Outcome => ({ verdict: 'fail', detail })
+
+function harness(): { scheduler: ManualScheduler; graph: MotionGraph } {
+  const clock = new ManualClock(0)
+  const scheduler = new ManualScheduler(clock)
+  const graph = createMotionGraph({ clock, scheduler })
+  return { scheduler, graph }
+}
+
+const tween = (durationS: number): Transition => ({ type: 'tween', duration: durationS })
+const SPRING: Transition = { type: 'spring', stiffness: 180, damping: 20 }
+
+export interface PresenceScenario {
+  readonly id: string
+  readonly requirements: readonly string[]
+  readonly assert: () => Outcome
+}
+
+export const PRESENCE_SCENARIOS: readonly PresenceScenario[] = [
+  {
+    id: 'presence.retention',
+    requirements: ['REQ-PRESENCE-001', 'REQ-PRESENCE-011'],
+    assert() {
+      const { scheduler, graph } = harness()
+      const c = createPresenceController({ graph })
+      c.syncChildren([{ key: 'k', exit: { opacity: 0 }, transition: tween(0.2) }])
+      c.syncChildren([]) // drop
+      if (!c.mountedKeys().includes('k')) return fail('dropped child with an exit was not retained')
+      scheduler.frames(6, 16.67) // ~100ms, mid-exit
+      if (!c.mountedKeys().includes('k')) return fail('unmounted before the exit completed')
+      scheduler.frames(12, 16.67) // ~300ms, past the exit
+      if (c.mountedKeys().includes('k')) return fail('not unmounted after the exit completed')
+      return pass('retained through the exit, unmounted at completion')
+    },
+  },
+  {
+    id: 'presence.settle-gate',
+    requirements: ['REQ-PRESENCE-013'],
+    assert() {
+      const { scheduler, graph } = harness()
+      const c = createPresenceController({ graph })
+      c.syncChildren([{ key: 'k', exit: { opacity: 0 }, transition: tween(0.2) }])
+      c.syncChildren([])
+      if (graph.isSettled()) return fail('graph settled while the exit was in flight')
+      let settledAt = -1
+      let t = 0
+      for (let i = 0; i < 20 && settledAt < 0; i++) {
+        scheduler.frame(16.67)
+        t += 16.67
+        if (graph.isSettled()) settledAt = t
+      }
+      if (settledAt < 200) return fail(`settledAt ${settledAt.toFixed(1)} < exitCompleteAt 200`)
+      return pass(`settledAt ${settledAt.toFixed(1)} >= exitCompleteAt 200`)
+    },
+  },
+  {
+    id: 'presence.cancel-on-reentry',
+    requirements: ['REQ-PRESENCE-012'],
+    assert() {
+      const { scheduler, graph } = harness()
+      const c = createPresenceController({ graph })
+      const ch = { key: 'k', animate: { opacity: 1 }, exit: { opacity: 0 }, transition: SPRING }
+      c.syncChildren([ch])
+      c.syncChildren([]) // drop → exiting
+      scheduler.frames(6, 16.67)
+      const pBefore = c.exitProgress('k') ?? -1
+      c.syncChildren([ch]) // re-add → cancel
+      if (c.stateOf('k') !== 'present') return fail('key not present after cancel')
+      if (!c.mountedKeys().includes('k')) return fail('key unmounted on cancel')
+      const pAfter = c.exitProgress('k') ?? -1
+      if (Math.abs(pAfter - pBefore) > EPS_X)
+        return fail(`continuity break |Δ|=${Math.abs(pAfter - pBefore)}`)
+      scheduler.frames(120, 16.67)
+      if (Math.abs(c.exitProgress('k') ?? 1) > EPS_X)
+        return fail('did not converge back to present')
+      return pass('cancel: never unmounted, continuity held, converged to present')
+    },
+  },
+  {
+    id: 'presence.immediate-unmount',
+    requirements: ['REQ-PRESENCE-011'],
+    assert() {
+      const { graph } = harness()
+      const c = createPresenceController({ graph })
+      c.syncChildren([{ key: 'k' }]) // no exit, not deferred
+      c.syncChildren([])
+      if (c.stateOf('k') !== 'removed') return fail('no-exit child not removed in one commit')
+      if (!graph.isSettled()) return fail('settle disturbed by an immediate unmount')
+      return pass('no-exit child removed in one commit; settle unaffected')
+    },
+  },
+  {
+    id: 'presence.manual-deferral',
+    requirements: ['REQ-PRESENCE-013', 'REQ-PRESENCE-014'],
+    assert() {
+      const { graph } = harness()
+      const c = createPresenceController({ graph })
+      c.syncChildren([{ key: 'k', deferred: true }])
+      c.syncChildren([])
+      if (c.isPresent('k')) return fail('isPresent true after a deferred child was removed')
+      if (!c.mountedKeys().includes('k')) return fail('deferred child not retained')
+      if (graph.isSettled()) return fail('settled while a manual exit was pending')
+      c.safeToRemove('k')
+      if (c.mountedKeys().includes('k')) return fail('still mounted after safeToRemove')
+      if (!graph.isSettled()) return fail('not settled after safeToRemove')
+      c.safeToRemove('k') // idempotent
+      if (!graph.isSettled()) return fail('a second safeToRemove disturbed settle')
+      return pass('deferred child stays unsettled until an idempotent safeToRemove')
+    },
+  },
+  {
+    // A usePresence consumer that registers only AFTER its key dropped (a layoutId introduced
+    // mid-exit) cannot ride the drop-time `deferred` flag: `deferExit` adopts manual authority
+    // into the live animated exit, and removal then requires BOTH the exit animation completing
+    // and the manual release — in either order.
+    id: 'presence.mid-exit-deferral-adoption',
+    requirements: ['REQ-PRESENCE-001', 'REQ-PRESENCE-013', 'REQ-PRESENCE-014'],
+    assert() {
+      const { scheduler, graph } = harness()
+      const c = createPresenceController({ graph })
+      c.syncChildren([
+        { key: 'k', animate: { opacity: 1 }, exit: { opacity: 0 }, transition: tween(0.2) },
+      ])
+      c.syncChildren([]) // drop with NO consumer → animation-driven exit
+      c.deferExit('k') // the consumer joins the live episode
+      scheduler.frames(24, 16.67) // ~400ms, past the 200ms exit
+      if (!c.mountedKeys().includes('k')) return fail('unmounted before the late consumer released')
+      if (graph.isSettled()) return fail('settled while a manual removal was pending')
+      c.safeToRemove('k')
+      if (c.stateOf('k') !== 'removed') return fail('not removed after the conjunction completed')
+      if (!graph.isSettled()) return fail('not settled after the adopted exit resolved')
+
+      // The other order: released while the animation is still in flight → the exit still gates.
+      c.syncChildren([
+        { key: 'j', animate: { opacity: 1 }, exit: { opacity: 0 }, transition: tween(0.2) },
+      ])
+      c.syncChildren([])
+      c.deferExit('j')
+      c.safeToRemove('j')
+      if (c.stateOf('j') !== 'exiting') return fail('early release unmounted mid-exit-animation')
+      scheduler.frames(24, 16.67)
+      if (c.stateOf('j') !== 'removed') return fail('not removed after the exit completed')
+      if (!graph.isSettled()) return fail('not settled after the early-released exit resolved')
+      return pass('mid-exit adoption gates removal on animation ∧ release, either order')
+    },
+  },
+  {
+    id: 'presence.wait-ordering',
+    requirements: ['REQ-PRESENCE-015'],
+    assert() {
+      const events: string[] = []
+      const { scheduler, graph } = harness()
+      const c = createPresenceController({
+        graph,
+        mode: 'wait',
+        onExitComplete: () => events.push('x'),
+      })
+      c.syncChildren([{ key: 'old', exit: { opacity: 0 }, transition: tween(0.2) }])
+      c.syncChildren([{ key: 'new', animate: { opacity: 1 } }]) // old exits, new enters
+      // Snapshot into numeric consts so control-flow does not narrow `events.length` to a literal across the
+      // side-effecting frames() calls (which invoke onExitComplete via the closure).
+      const enteredEarly = c.mountedKeys().includes('new')
+      const firedEarly = events.length
+      scheduler.frames(15, 16.67)
+      c.mountedKeys() // reconcile
+      const firedAfter = events.length
+      const enteredAfter = c.mountedKeys().includes('new')
+      if (enteredEarly) return fail('entering child committed before the exit resolved')
+      if (firedEarly !== 0) return fail('onExitComplete fired before the exit resolved')
+      if (firedAfter !== 1)
+        return fail(`onExitComplete fired ${firedAfter} times, expected exactly 1`)
+      if (!enteredAfter) return fail('entering child not committed after the exit resolved')
+      return pass(
+        'wait defers enters until exits resolve; onExitComplete once, strictly before enters',
+      )
+    },
+  },
+  {
+    id: 'presence.concurrent',
+    requirements: ['REQ-PRESENCE-018'],
+    assert() {
+      const { scheduler, graph } = harness()
+      const c = createPresenceController({ graph })
+      c.syncChildren([
+        { key: 'short', exit: { opacity: 0 }, transition: tween(0.1) },
+        { key: 'long', exit: { opacity: 0 }, transition: tween(0.3) },
+      ])
+      c.syncChildren([])
+      scheduler.frames(8, 16.67) // ~133ms
+      c.mountedKeys()
+      if (c.stateOf('short') !== 'removed')
+        return fail('short exit did not resolve at its own completion')
+      if (c.stateOf('long') !== 'exiting') return fail('long exit resolved early')
+      if (graph.isSettled()) return fail('settled before the last concurrent exit')
+      scheduler.frames(12, 16.67) // ~333ms
+      c.mountedKeys()
+      if (c.stateOf('long') !== 'removed') return fail('long exit did not resolve')
+      if (!graph.isSettled()) return fail('not settled after the last concurrent exit')
+      return pass('concurrent exits resolve independently; settle waits for the last')
+    },
+  },
+  {
+    id: 'presence.initial-false',
+    requirements: ['REQ-PRESENCE-016'],
+    assert() {
+      const { graph } = harness()
+      const c = createPresenceController({ graph, initial: false })
+      c.syncChildren([{ key: 'k', animate: { opacity: 1 } }])
+      if (!c.isPresent('k')) return fail('child not present on the first commit')
+      if (!c.enterSuppressed('k')) return fail('enter not suppressed under initial={false}')
+      return pass('initial={false} suppresses the first-commit enter (mounted at animate)')
+    },
+  },
+  {
+    id: 'presence.pop-layout',
+    requirements: ['REQ-PRESENCE-017', 'REQ-PRESENCE-022'],
+    assert() {
+      const { scheduler, graph } = harness()
+      const c = createPresenceController({ graph, mode: 'popLayout' })
+      c.syncChildren([{ key: 'k', exit: { opacity: 0 }, transition: tween(0.2) }])
+      c.syncChildren([])
+      if (!c.mountedKeys().includes('k'))
+        return fail('popLayout dropped the exiting child immediately')
+      scheduler.frames(20, 16.67)
+      if (c.mountedKeys().includes('k'))
+        return fail('popLayout retained the child after its exit settled')
+      return pass(
+        'popLayout retains exiting children through lifecycle settlement; host geometry is owned by integration floors',
+      )
+    },
+  },
+  {
+    // Family-6 (REQ-PRESENCE-010 propagate): drop-time deferred:true + authored exit is the
+    // consumer ∧ animation conjunction. Nested propagate registers deferred at drop; a short
+    // nested release must not unmount the outer key before its longer exit settles.
+    id: 'presence.deferred-exit-conjunction',
+    requirements: ['REQ-PRESENCE-001', 'REQ-PRESENCE-010', 'REQ-PRESENCE-013', 'REQ-PRESENCE-014'],
+    assert() {
+      const { scheduler, graph } = harness()
+      const c = createPresenceController({ graph })
+      c.syncChildren([
+        {
+          key: 'outer',
+          animate: { opacity: 1 },
+          exit: { opacity: 0 },
+          transition: tween(0.2),
+          deferred: true,
+        },
+      ])
+      c.syncChildren([]) // drop with drop-time deferral + authored exit
+      if (c.stateOf('outer') !== 'exiting') return fail('deferred+exit drop did not enter exiting')
+      c.safeToRemove('outer') // nested consumer released first
+      if (c.stateOf('outer') !== 'exiting')
+        return fail('early safeToRemove unmounted before the exit animation settled')
+      if (!c.mountedKeys().includes('outer')) return fail('key left mounted set mid-exit')
+      if (graph.isSettled()) return fail('settled while exit animation still owns retention')
+      scheduler.frames(24, 16.67) // past 200ms exit
+      if (c.stateOf('outer') !== 'removed')
+        return fail('not removed after exit animation completed')
+      if (!graph.isSettled()) return fail('not settled after the deferred+exit conjunction')
+      return pass('drop-time deferred + authored exit gates on animation ∧ release, either order')
+    },
+  },
+]
+
+// Run one presence scenario against the reference controller, producing a ScenarioResult under the fake-host
+// engine (M1). The controller carries its own deterministic clock/graph — no adapter needed.
+export function runPresenceScenario(scenario: PresenceScenario): ScenarioResult {
+  const outcome = scenario.assert()
+  return {
+    id: scenario.id,
+    engine: FAKE_ENGINE,
+    verdict: outcome.verdict,
+    readings: [],
+    detail: outcome.detail,
+  }
+}

package/src/scenarios/spring.ts

@@ -0,0 +1,180 @@
+// Spring/timing cross-engine conformance scenarios (SPEC-SPRING §5). Authored ONCE, engine-agnostic:
+// each names a generator config + a t-grid; the runner samples it on BOTH the native solver and pinned
+// motion-dom and the comparator differentially checks parity within SPRING_BAND. No expected values are
+// authored here — the two independent engines are each other's oracle (REQ-CONFORM-011/014).
+//
+// The two `pendingDecisionD` scenarios are the known oracle divergences (SPEC-SPRING §8): the
+// overdamped-tail #1207 bug (native exponential 630 vs oracle capped 988) and visualDuration-only
+// (native vd-path vs oracle pre-plan-030 default physics). They FAIL cross-engine — carried fail-closed
+// until the pin is reconciled, never papered over.
+
+import type { SpringScenario } from '../scenario'
+
+const STEP_MS = 1000 / 60 // Motion's 60fps grid
+function grid(tMaxMs: number, extra: readonly number[] = []): number[] {
+  const ts = new Set<number>([0])
+  for (let t = 0; t <= tMaxMs; t += STEP_MS) ts.add(Number(t.toFixed(6)))
+  for (const e of extra) ts.add(e)
+  return [...ts].sort((a, b) => a - b)
+}
+
+const CAP = ['spring-trajectory'] as const
+
+export const SPRING_SCENARIOS: readonly SpringScenario[] = [
+  // ── regime coverage (REQ-SPRING-002/010) ──
+  {
+    id: 'SPRING-underdamped',
+    requirements: ['REQ-SPRING-002'],
+    capabilities: CAP,
+    kind: 'spring',
+    spec: { from: 0, to: 100, stiffness: 100, damping: 10, mass: 1 },
+    tGrid: grid(3000),
+  },
+  {
+    id: 'SPRING-critical',
+    requirements: ['REQ-SPRING-002'],
+    capabilities: CAP,
+    kind: 'spring',
+    spec: { from: 0, to: 100, stiffness: 100, damping: 20, mass: 1 },
+    tGrid: grid(2000),
+  },
+  {
+    id: 'SPRING-overdamped-mild',
+    requirements: ['REQ-SPRING-010'],
+    capabilities: CAP,
+    kind: 'spring',
+    spec: { from: 0, to: 100, stiffness: 100, damping: 30, mass: 1 },
+    tGrid: grid(4000),
+  },
+  // ── config resolution (REQ-SPRING-004/005) ──
+  {
+    id: 'SPRING-duration',
+    requirements: ['REQ-SPRING-004'],
+    capabilities: CAP,
+    kind: 'spring',
+    spec: { from: 0, to: 100, duration: 800, bounce: 0.3 },
+    tGrid: grid(2000),
+  },
+  {
+    id: 'SPRING-visualDuration',
+    requirements: ['REQ-SPRING-005'],
+    capabilities: CAP,
+    kind: 'spring',
+    spec: { from: 0, to: 100, visualDuration: 0.3, bounce: 0 },
+    tGrid: grid(2000),
+  },
+  // ── precedence: a physics key ignores the duration family (REQ-SPRING-006) ──
+  {
+    id: 'SPRING-precedence-physics',
+    requirements: ['REQ-SPRING-006'],
+    capabilities: CAP,
+    kind: 'spring',
+    spec: { from: 0, to: 100, stiffness: 200, duration: 1000 },
+    tGrid: grid(2000),
+  },
+  // ── velocity carry (REQ-SPRING-007) + the interruption re-seed (REQ-SPRING-009): a physics spring
+  //    seeded with incoming velocity is exactly a mid-interruption handoff ──
+  {
+    id: 'SPRING-velocity-carry',
+    requirements: ['REQ-SPRING-007', 'REQ-SPRING-009'],
+    capabilities: CAP,
+    kind: 'spring',
+    spec: { from: 0, to: 100, stiffness: 100, damping: 10, velocity: 800 },
+    tGrid: grid(3000),
+  },
+  // ── unit/sign boundary: a negative incoming velocity (REQ-SPRING-008) ──
+  {
+    id: 'SPRING-sign-negative-v0',
+    requirements: ['REQ-SPRING-008'],
+    capabilities: CAP,
+    kind: 'spring',
+    spec: { from: 0, to: 100, stiffness: 120, damping: 12, velocity: -600 },
+    tGrid: grid(3000),
+  },
+  // ── granular boundary: |delta| < 5 tightens rest thresholds (REQ-SPRING-011) ──
+  {
+    id: 'SPRING-granular',
+    requirements: ['REQ-SPRING-011'],
+    capabilities: CAP,
+    kind: 'spring',
+    spec: { from: 0, to: 3, stiffness: 100, damping: 20 },
+    tGrid: grid(3000),
+  },
+  // ── timing curves (REQ-TIMING-001/002) ──
+  {
+    id: 'TIMING-default-ease',
+    requirements: ['REQ-TIMING-002'],
+    capabilities: CAP,
+    kind: 'timing',
+    spec: { from: 0, to: 100, duration: 300, ease: [0.25, 0.1, 0.35, 1] },
+    tGrid: grid(300, [300, 400]),
+  },
+  {
+    id: 'TIMING-easeInOut',
+    requirements: ['REQ-TIMING-001'],
+    capabilities: CAP,
+    kind: 'timing',
+    spec: { from: 0, to: 200, duration: 500, ease: [0.42, 0, 0.58, 1] },
+    tGrid: grid(500, [500]),
+  },
+  {
+    id: 'TIMING-linear',
+    requirements: ['REQ-TIMING-001'],
+    capabilities: CAP,
+    kind: 'timing',
+    spec: { from: 10, to: 60, duration: 400, ease: 'linear' },
+    tGrid: grid(400, [400]),
+  },
+  // Family-2 named curves (xxytww): exercise expanded Motion EasingDefinition through both adapters.
+  {
+    id: 'TIMING-circOut',
+    requirements: ['REQ-TIMING-001'],
+    capabilities: CAP,
+    kind: 'timing',
+    spec: { from: 0, to: 100, duration: 400, ease: 'circOut' },
+    tGrid: grid(400, [200, 400]),
+  },
+  {
+    id: 'TIMING-backOut',
+    requirements: ['REQ-TIMING-001'],
+    capabilities: CAP,
+    kind: 'timing',
+    spec: { from: 0, to: 100, duration: 400, ease: 'backOut' },
+    tGrid: grid(400, [200, 300, 400]),
+  },
+  {
+    id: 'TIMING-anticipate',
+    requirements: ['REQ-TIMING-001'],
+    capabilities: CAP,
+    kind: 'timing',
+    spec: { from: 0, to: 100, duration: 400, ease: 'anticipate' },
+    tGrid: grid(400, [100, 200, 400]),
+  },
+  {
+    id: 'TIMING-easeIn-named',
+    requirements: ['REQ-TIMING-001'],
+    capabilities: CAP,
+    kind: 'timing',
+    spec: { from: 0, to: 100, duration: 400, ease: 'easeIn' },
+    tGrid: grid(400, [200, 400]),
+  },
+  // ── decision-D divergences (SPEC-SPRING §8) — fail closed cross-engine, never papered over ──
+  {
+    id: 'SPRING-1207-overdamped-tail',
+    requirements: ['REQ-SPRING-010'],
+    capabilities: CAP,
+    kind: 'spring',
+    spec: { from: 0, to: 1000, stiffness: 4, damping: 35, mass: 0.5 },
+    tGrid: grid(9000, [8700]),
+    pendingDecisionD: true,
+  },
+  {
+    id: 'SPRING-visualDuration-only',
+    requirements: ['REQ-SPRING-006'],
+    capabilities: CAP,
+    kind: 'spring',
+    spec: { from: 0, to: 100, visualDuration: 0.3 },
+    tGrid: grid(2000),
+    pendingDecisionD: true,
+  },
+]

package/src/scenarios/value-types.ts

@@ -0,0 +1,107 @@
+// Value-type cross-engine conformance scenarios (SPEC-VALUE-TYPES §5). Authored ONCE, engine-agnostic:
+// each names a property + a from/to pair + a progress grid; the runner mixes it on BOTH the native seam
+// and pinned motion-dom, and the comparator differentially checks per-type-epsilon parity. No expected
+// values are authored — the two independent engines are each other's oracle (REQ-CONFORM-011/014).
+//
+// Divergence scenarios are first-class (never excluded): `'throw'` — native fails loud on a unit/shape
+// mismatch where motion warns+snaps via mixImmediate (REQ-VALUETYPE-004/-007/-008); `'snap'` — native
+// mixes named colors from its own table (REQ-VALUETYPE-005) where motion, lacking a DOM, snaps to the
+// target, so the engines MUST diverge (documented capability tripwire, §8 named-color vetoable).
+
+import type { ValueTypeScenario } from '../scenario'
+
+// Shared progress grid (matches the golden generator's GRID, SPEC-VALUE-TYPES §5).
+const GRID = [0, 0.1, 0.25, 0.5, 0.75, 0.9, 1] as const
+const CAP = ['value-type-mix'] as const
+
+export const VALUE_TYPE_SCENARIOS: readonly ValueTypeScenario[] = [
+  // ── color (gamma-aware RGBA mix), REQ-VALUETYPE-006 ──
+  {
+    id: 'VT-backgroundColor-hex',
+    requirements: ['REQ-VALUETYPE-006'],
+    capabilities: CAP,
+    property: 'backgroundColor',
+    from: '#000000',
+    to: '#ffffff',
+    grid: GRID,
+  },
+  {
+    id: 'VT-backgroundColor-rgba-alpha',
+    requirements: ['REQ-VALUETYPE-006'],
+    capabilities: CAP,
+    property: 'backgroundColor',
+    from: 'rgba(255, 0, 0, 1)',
+    to: 'rgba(0, 0, 255, 0)',
+    grid: GRID,
+  },
+  {
+    id: 'VT-color-hsl',
+    requirements: ['REQ-VALUETYPE-005', 'REQ-VALUETYPE-006'],
+    capabilities: CAP,
+    property: 'color',
+    from: 'hsl(0, 100%, 50%)',
+    to: 'hsl(240, 100%, 50%)',
+    grid: GRID,
+  },
+  // ── unit number (length), REQ-VALUETYPE-003 ──
+  {
+    id: 'VT-width-px',
+    requirements: ['REQ-VALUETYPE-003'],
+    capabilities: CAP,
+    property: 'width',
+    from: '0px',
+    to: '100px',
+    grid: GRID,
+  },
+  // ── complex/compound, REQ-VALUETYPE-007 ──
+  {
+    id: 'VT-borderRadius',
+    requirements: ['REQ-VALUETYPE-007'],
+    capabilities: CAP,
+    property: 'borderRadius',
+    from: '16px 16px 0px 0px',
+    to: '0px 0px 0px 0px',
+    grid: GRID,
+  },
+  {
+    id: 'VT-boxShadow',
+    requirements: ['REQ-VALUETYPE-006', 'REQ-VALUETYPE-007'],
+    capabilities: CAP,
+    property: 'boxShadow',
+    from: '0px 0px 0px rgba(0, 0, 0, 0.5)',
+    to: '10px 10px 20px rgba(255, 0, 0, 1)',
+    grid: GRID,
+  },
+  // ── divergences: native throws (REQ-VALUETYPE-004/-007/-008) ──
+  {
+    id: 'VT-unit-mismatch-throws',
+    requirements: ['REQ-VALUETYPE-004'],
+    capabilities: CAP,
+    property: 'borderRadius',
+    from: '16px 16px',
+    to: '16deg 16deg',
+    grid: GRID,
+    divergence: 'throw',
+  },
+  {
+    id: 'VT-shape-mismatch-throws',
+    requirements: ['REQ-VALUETYPE-007'],
+    capabilities: CAP,
+    property: 'borderRadius',
+    from: '16px',
+    to: '0px 0px 0px 0px',
+    grid: GRID,
+    divergence: 'throw',
+  },
+  // ── divergence: native mixes named colors, motion snaps (REQ-VALUETYPE-005) ──
+  {
+    id: 'VT-named-color-snap',
+    requirements: ['REQ-VALUETYPE-005'],
+    capabilities: CAP,
+    property: 'backgroundColor',
+    from: 'red',
+    to: 'blue',
+    grid: GRID,
+    divergence: 'snap',
+  },
+]

package/src/suite.ts

@@ -0,0 +1,44 @@
+// The suite aggregator (REQ-CONFORM-011). Folds per-(scenario, engine) results into one fail-closed
+// verdict. `unassertable` is a ROUTING obligation, not a pass: a scenario that no engine could assert
+// is an uncovered obligation and fails the suite. The rules:
+//   - any `fail` on any engine → suite `fail`;
+//   - a scenario that is `unassertable` on every engine that ran it (no engine `pass`ed it) has no
+//     owner → suite `fail`;
+//   - otherwise → suite `pass`.
+
+import type { ScenarioResult } from './runner'
+
+export interface SuiteResult {
+  readonly verdict: 'pass' | 'fail'
+  readonly reasons: readonly string[]
+}
+
+export function aggregateSuite(results: readonly ScenarioResult[]): SuiteResult {
+  // Fail-closed on an empty run: zero results means nothing was verified (scenarios filtered out, a
+  // discovery bug, an aborted run). Reporting `pass` here would be the exact fail-open the
+  // three-valued accounting exists to prevent — an unrun suite is never a green one.
+  if (results.length === 0) {
+    return { verdict: 'fail', reasons: ['empty result set — no scenarios ran'] }
+  }
+
+  const reasons: string[] = []
+
+  for (const r of results) {
+    if (r.verdict === 'fail') reasons.push(`${r.id} failed on ${r.engine}`)
+  }
+
+  // Group by scenario so ownership is evaluated across all engines that ran it.
+  const byScenario = new Map<string, ScenarioResult[]>()
+  for (const r of results) {
+    const list = byScenario.get(r.id) ?? []
+    list.push(r)
+    byScenario.set(r.id, list)
+  }
+  for (const [id, list] of byScenario) {
+    const hasUnassertable = list.some((r) => r.verdict === 'unassertable')
+    const hasOwner = list.some((r) => r.verdict === 'pass')
+    if (hasUnassertable && !hasOwner) reasons.push(`${id} unassertable with no owner`)
+  }
+
+  return { verdict: reasons.length === 0 ? 'pass' : 'fail', reasons }
+}