memlnaut-nisps/manifold/tests/fixtures/README.md

# Pipeline golden fixtures

Originally captured **2026-07-13** from the TypeScript engine implementations,
**before** the P4 "one core engine" migration
(`docs/specs/plans/one-core-engine-refactor.md` §P4). As of **2026-07-18** that
migration has landed: the curve / input-pipeline / output-pipeline maths now
live solely in the C++/WASM core (`nisps/pipeline/*`, `nisps/core/math.hpp`),
and the TS `curves.ts` / `input-pipeline.ts` / `output-pipeline.ts` are deleted.

These fixtures are the recorded-gesture pre/post-migration regression P4's gate
calls for: *"same pointer trace → same routed output pre/post migration."* The
test (`../pipeline-golden.test.ts`) now drives the WASM chains against them.

## What is here

| File | What it pins | Driven through (now) |
|---|---|---|
| `gesture-trace.json` | One canonical synthetic pointer trace (288 events, fixed 120 Hz dt) over the input pipeline's native `[0,1]²` domain: h/v sweeps, diagonal, spiral, figure-eight, dwell + abrupt corner jumps. Pure formula — no `Math.random`, no `Date.now`. | (input to the input chain) |
| `curves-golden.json` | The curve catalog, 129 samples of `x ∈ [0,1]` inclusive. **See "Curves re-baselined" below.** | `nisps_curve_apply` (WASM) |
| `input-pipeline-golden.json` | The gesture trace run through the input pipeline under 14 representative configs (default, deadzone, zoom, sticky anchor, per-axis, curves, smoothing, invert, momentum gentle/strong, frozen axis, fully frozen, combined). Records `{x, y, frozen}` per event. Configs embedded. **FROZEN** pre-migration capture. | `nisps_input_*` (WASM) |
| `output-pipeline-golden.json` | A deterministic raw-output sequence (120 vectors × 8 channels of offset sines, quantised to f32) run through the output pipeline under 8 configs (default, curves, smoothing, slew, global-freeze toggled mid-sequence, per-output freeze mask, combined). Records the processed vector per step. Configs embedded. **FROZEN** pre-migration capture. | `nisps_output_*` (WASM) |

## The regression guard

`../pipeline-golden.test.ts` (`bun test`) loads the built WASM
(`../../public/nisps.{js,wasm}`) via the indirect-eval shim (`../wasm-load.ts`,
same technique as `tests/cpp/parity_wasm.mjs`), creates a pipeline handle, and
re-runs the **committed fixtures** through the C++ chains. The fixtures are
authoritative: the trace, raw sequence, and per-run configs are read FROM the
JSON, so the config lists in `pipeline-golden-lib.ts` cannot mask a regression.

### Tolerances (f32 WASM vs f64-captured fixtures)

- **Input / output pipelines: `1e-5`.** Measured max non-momentum drift `<5e-7`.
- **Momentum configs (`momentum-gentle` / `momentum-strong` / `combined`):
  `1e-2`.** This is proven-inherent f32 drift, **not** a core bug. The velocity
  ring's window-membership test (`now − t ≤ window`) is a DISCRETE boundary that
  f32 rounding can flip during fast gestures, shifting which sample is the
  window's oldest by a whole frame (~8 ms) → a step change in the measured speed
  → integrated by the momentum-zoom IIR. A byte-faithful f32 port of the exact
  original TS algorithm reproduces the WASM to `<6e-8` while both diverge from
  the f64 capture by the same `~7–9e-3` (measured max `8.6e-3` on
  momentum-strong). Reconciling it would require f64 momentum maths, which would
  break firmware parity — so the momentum runs are guarded at `1e-2` (the core
  is still tightly pinned to the algorithm by the `<6e-8` faithful-f32 identity;
  a real behavioural regression would blow far past `1e-2`).

## Curves re-baselined (2026-07-18)

`curves-golden.json` is now a MIX, recorded in its `provenance` field:

- **`linear` / `square` / `sqrt` / `centered_power`** — the ORIGINAL 2026-07-13
  f64 TS captures, kept unchanged. The C++ core reproduces them within `1e-5`
  (measured `<3e-8`), proving **no behaviour change** for these curves.
- **`exp` / `log` / `sigmoid` / `cubic`** — **RE-BASELINED from the WASM.** The
  browser deliberately adopted the canonical firmware-exact maths: the old TS
  `curves.ts` used `k=4` exp/log, slope-8 sigmoid, and a smoothstep "cubic"; the
  canonical `nisps/core/math.hpp` catalog uses `k=1`-normalised exp/log, a
  slope-6 sigmoid, and a true cubic `x³`. The test asserts WASM stability
  against these regenerated values.

## Contracts you must reproduce to consume these

### State contract (both chains are stateful, C++-side per pipeline handle)
- **Input:** EMA-smoothed x/y, a velocity ring, and a momentum-zoom multiplier.
- **Output:** `prev` + `smoothed` buffers driving slew/freeze.

Each config **run resets state** (`nisps_input_reset` / `nisps_output_reset`)
at step 0. Runs are independent; do not carry state between them.

### Clock contract (input pipeline only)
The C++ input chain accumulates its own clock from the per-call `dt` (seconds)
for the momentum velocity window; it takes **no** wall clock. To reproduce the
capture, the test feeds each event's `dt` = the per-event `t_ms` delta in
seconds, with the **first event's `dt` = 0** (matching the original TS capture,
which pinned `performance.now()` to each event's `t_ms`). The output chain uses
a constant per-step `dt` of `1000/60` ms (→ seconds).

### JSON encodings
- `slewRate: null` in an output spec means `Infinity` (JSON has no `Infinity`);
  it maps to the wire's `slew_rate <= 0 ⇒ unlimited`.
- Output raw values are pre-quantised with `Math.fround` so they equal exactly
  what a `Float32Array` holds.

## Re-capture

`bun tests/fixtures/_generate.ts` regenerates `gesture-trace.json` (pure data)
and re-baselines the 4 changed curves in `curves-golden.json` from the WASM
(preserving the 4 unchanged f64 entries + provenance). It does **not** rewrite
the input/output pipeline goldens — those are the frozen pre-migration capture
the regression is measured against; there is no TS pipeline left to capture
from. `scripts/build-wasm.sh` must have run first.