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

Pipeline golden fixtures

Captured 2026-07-13 from the current TypeScript engine implementations, before the P4 "one core engine" migration (docs/specs/plans/one-core-engine-refactor.md §P4) replaces the TS curve/input/output code with calls into the C++/WASM core.

P4's own gate reads: "recorded-gesture regression: same pointer trace → same routed output pre/post migration (capture fixture before starting)." These files are that capture.

What is here

File	What it pins	Source under test
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 pipeline)
curves-golden.json	applyCurve(name, x) for every curve id in curves.ts, 129 samples of x ∈ [0,1] inclusive, at each curve's default param.	src/engine/curves.ts
input-pipeline-golden.json	The gesture trace run through processInput 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.	src/engine/input-pipeline.ts
output-pipeline-golden.json	A deterministic raw-output sequence (120 vectors × 8 channels of offset sines, quantised to f32) run through processOutput under 8 configs (default, curves, smoothing, slew limiting, global-freeze toggled mid-sequence, per-output freeze mask, combined). Records the processed vector per step. Configs embedded.	src/engine/output-pipeline.ts

The drift guard

../pipeline-golden.test.ts (bun test) re-runs the current TS implementations against these fixtures and asserts equality within 1e-9. It reads the trace, raw sequence, and configs from the JSON — the fixtures are authoritative, so editing pipeline-golden-lib.ts config lists cannot mask a regression. Any change to curves.ts / input-pipeline.ts / output-pipeline.ts that alters numeric behaviour breaks this test until the goldens are deliberately re-captured.

To re-capture (only when intended): cd manifold && bun tests/fixtures/_generate.ts.

Contracts you must reproduce to consume these

State contract (both pipelines are stateful)

• 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 (defaultInputState() / defaultOutputState()) at step 0. Runs are independent; do not carry state between them.

Clock contract (input pipeline only)

input-pipeline.ts's momentum-zoom path reads performance.now() (wall clock) for its 150 ms velocity window. To make the momentum configs reproducible, the capture pins performance.now() to each event's t_ms before processing it, so the velocity window slides over the gesture's own timescale. dt passed to processInput is the per-event t_ms delta in seconds (fixed 1000/120 ms). A future consumer that ports this to C++ must feed the same per-event timestamps (the trace's t_ms) into whatever owns the velocity ring, or the momentum runs will not match. The output pipeline uses no wall clock; its dtMs is a fixed 1000/60.

JSON encodings

• slewRate: null in an output spec means Infinity (JSON has no Infinity).
• Output raw values are pre-quantised with Math.fround so they equal exactly what a Float32Array holds.

How P4 should consume these

After the input/output/curve logic moves into the C++/WASM core, flip pipeline-golden.test.ts to drive the WASM implementations (via the main-thread nisps instance) instead of the TS run* helpers, keeping the same fixtures as the expected values. That proves same pointer trace → same routed output across the migration.

Tolerance: these goldens were produced in TS f64. The WASM core computes in f32 for many paths, so exact 1e-9 equality will not hold post-migration — relax the comparison to about 1e-5 (and expect the sigmoid/exp/log curve tails and long smoothing/slew accumulations to be the widest-drifting points). If any value drifts materially beyond that, it is a real behavioural divergence, not float noise, and must be reconciled in the core rather than by widening tolerance.