# Kinematic Validation Harness

Milestone 4 now includes a deterministic kinematic validation layer for the procedural animation demo set. The harness samples each machine cycle at fixed time intervals and verifies mechanical invariants that are easy to regress visually: gear ratios, loop travel, dwell/index profiles, crank-slider displacement, opposed caliper symmetry, bearing rolling ratios, and Wankel eccentric/rotor phasing.

## Running the checks

```bash
npm run test:run -- proceduralKinematicsValidation
```

For local development, use watch mode:

```bash
npm test -- proceduralKinematicsValidation
```

The suite intentionally avoids rendering WebGL. It validates the underlying mechanical timing curves first, so failures are fast, deterministic, and easier to diagnose than visual snapshot drift.

## What is covered

| Machine | Primary invariants |
| --- | --- |
| Four-stroke petrol engine | Crank RPM, cam 1:2 phase ratio, crank-slider piston displacement, intake/exhaust event timing, spark timing |
| Planetary gearbox | Willis equation, fixed-ring carrier ratio, planet spin phase relation |
| Differential gear | Carrier equals average of left/right outputs while wheel speeds split during a turn |
| Centrifugal pump | Constant impeller RPM, bounded pressure/flow pulses, flow marker phase lock |
| Geneva drive | Locked dwell, smooth indexing window, monotonic output, one full output revolution after four drive turns |
| Ball bearing | Inner/outer race behavior, cage speed ratio, ball spin rolling relation |
| Disc brake caliper | Opposed pad symmetry, bounded clamp envelope, positive rotor speed under braking |
| Wankel rotary engine | Eccentric shaft speed, rotor 3:1 phase, rotor-center orbit radius, apex radial geometry |

## Adding a new procedural machine check

1. Define scalar tracks for the animation quantities that matter mechanically: angles, linear travel, normalized envelopes, or pressure/flow pulses.
2. Add constraints from `src/animations/kinematicIntegrity.ts`; prefer physical identities over broad ranges.
3. Register the suite in `proceduralKinematicValidationSuites`.
4. Add or update tests if the machine introduces a new type of invariant.

The validation harness is deliberately tolerant-based rather than snapshot-based. That keeps it useful when animations are refined, while still catching broken RPM scaling, incorrect gear ratios, non-looping cycles, NaN samples, and event timing regressions.