Me Here be524ce1ea Rust port Stage 1: track-format codec crate (passes the golden vectors)

A third implementation of the track DSL alongside engine.js and app.py, validated
against the same tests/fixtures/track-format.json:

- rust/track-format/: pure parse()/serialize() codec (std + alloc for now; no_std is
  a later refinement). Ports the app.py/engine.js semantics exactly — grouping,
  subdivisions, swing, ghost, polymeter, euclid, GM note-number aliases, unknown->beep,
  default groove (group-start accents), tempo clamp, empty->beep, and the playback-flow
  tokens (rep/end/relative-goto). Carries vol/cd too, so it's the most spec-complete
  of the three.
- tests/conformance.rs: the Rust adapter — reads the shared fixtures, asserts each
  case's normalized form (number-tolerant deep-equal) + serialize idempotency.
- rust/Containerfile + run.sh: Rust toolchain in a container (mirrors hardware/eda/),
  with the thumbv8m.main-none-eabihf target for the eventual RP2350 firmware. Never
  on the host.

Verified: ./rust/run.sh -> cargo test -> conformance + idempotent both pass.
docs/rust-port.md Stage 1 marked done.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

2026-05-31 18:36:59 -05:00

4.2 KiB

Raw Blame History

Rust port — staged plan

This is the plan for the native-Rust direction first discussed alongside the A/B-bootloader idea. What changed since then: the track format is now formally specced (docs/track-format.md) with a golden-vector conformance suite (tests/run.mjs). That suite is the thing that makes a port safe — any Rust engine has a precise, executable definition of "correct" to validate against, the same one engine.js and app.py already pass.

The core idea

Port from the inside out, lowest-risk first. The pure logic (track codec, then the scheduler) is host-testable with zero hardware and is gated by the existing golden vectors. Only once that's proven do we touch drivers, A/B, and the actual firmware. We do not rip out CircuitPython until the Rust engine passes the vectors and the drivers are proven on hardware.

Stages

Stage 0 — toolchain in a container

Add a Rust toolchain image (mirroring hardware/eda/): a Containerfile with rustup, the thumbv8m.main-none-eabihf target (RP2350 is Cortex-M33), flip-link, probe-rs, elf2uf2. Driven by a run.sh like the EDA one. Never on the host.

Stage 1 — `track-format` crate ✅ DONE (`rust/track-format/`)

Implemented and passing: ./rust/run.sh builds the container and runs cargo test, which validates the crate against tests/fixtures/track-format.json (conformance + idempotency). The Rust codec agrees with engine.js and app.py on every vector — and carries vol/cd, so it's the most spec-complete of the three. Original scope below.

(original) Stage 1 — `track-format` crate ← the concrete first PR

A pure, no_std-compatible crate: parse(&str) -> Track and serialize(&Track) -> String, plus a normalize() that emits the neutral structure from docs/track-format.md §5. Then a cargo test that reads tests/fixtures/track-format.json and asserts each case's norm and round-trip — i.e. a third adapter alongside js_adapter.mjs / py_adapter.py. When this is green, the Rust engine provably agrees with web + device on every groove, euclid, swing, ghost, polymeter, and the playback-flow tokens. No hardware, fully testable in the container.

This is the highest-value slice: small, gated by work already done, and it proves the toolchain.

Stage 2 — scheduler/engine

Port the look-ahead step scheduler. engine.js already marks these primitives PORTS TO FIRMWARE, and app.py's tick() is the same model. Host-test it by asserting click timings for known patches (e.g. swing ratios, polymeter bar lengths) — still no hardware.

Stage 3 — drivers (hardware)

On embassy / rp-hal:

ST7789 240×320 display → mipidsi + embedded-graphics (mature; the parts are well-supported).
I²S to the PCM5102A → RP2350 PIO.
WS2812 → ws2812-pio. USB-MIDI → usbd-midi / embassy-usb.
GT911 touch (Kit) over I²C.

Stage 4 — native A/B + secure boot

Replace the .mpy-level A/B hack (code.py loads app.mpy, rolls back to app.bak) with the RP2350 bootrom's native partition-table A/B + signed boot, configured via picotool (the chip already provides this — see the earlier hardware discussion). The Rust app is the image in the slot; rollback and version selection move into silicon.

What you keep / lose

Gain: memory safety, native A/B + secure boot, performance headroom, one typed model instead of three hand-written parsers.
Lose: the live one-click .mpy push (Rust is compile→flash→reboot). The editor's data live-sync (tempo/pattern/setlist mirroring) still works — it's a data protocol. Only live logic edits go away, and an embedded wasm3/script module could buy those back if wanted.

Acceptance gate

Every codec/engine change must pass tests/fixtures/track-format.json. The Rust crate joins js/py as a runner adapter, so "same groove on web, device, and the Rust build" is enforced, not hoped for.

Recommendation

Do Stage 1 in a container next — it's small, testable today (given a toolchain), reuses the suite, and produces a real artifact to judge the Rust path on before committing to drivers or a firmware rewrite. Defer Stages 3–4 until Stage 1–2 are green and you've decided the live-push tradeoff is acceptable.

4.2 KiB Raw Blame History Unescape Escape