# Track-format conformance tests

Golden-vector suite that pins the track ("program"/"patch") format to a single meaning and
checks that both implementations agree:

- **web** — `src/engine.js`
- **firmware** — `pico-cp/app.py`

The spec is `docs/track-format.md`. Any new implementation (e.g. a Rust engine) must pass the
same vectors — that is what keeps "the same groove on the device and in the browser" true.

## Run

```sh
node tests/run.mjs        # table of pass / known-divergence / FAIL per case
node tests/run.mjs -v     # also print expected-vs-actual diffs for unexpected failures
```

Exit code is non-zero on any **unexpected** failure or round-trip (idempotency) break, so it
works as a CI gate.

## Layout

- `fixtures/track-format.json` — the vectors. Each has `in` (a patch), `norm` (expected
  normalized meaning, see spec §5), a `status`, and optional `expectFail` listing impls known
  to differ today.
- `adapters/js_adapter.mjs` — loads the real `src/engine.js` grammar (no copy) and normalizes.
- `adapters/py_adapter.py` — extracts the real `pico-cp/app.py` grammar functions via `ast`
  (no copy) and normalizes.
- `run.mjs` — runs every vector through both adapters and reports.

## Reading the result

- `✓ pass` — implementation matches the spec for that vector.
- `· known` — a divergence/feature listed in `expectFail`; expected, not a failure.
- `✗ FAIL` — an **unexpected** mismatch (a regression). Investigate.
- `★ fixed` — an impl listed in `expectFail` now passes; remove it from `expectFail`.

When you fix a divergence in code, delete that impl from the case's `expectFail`. When you
implement the `new` playback-flow tokens (`rep` / `end`), those cases flip to `pass`.