Conformance test vectors, and decisions on note-offs, rounding, duplicate mappings, ranged CCs and timescale

[cpmpercussion]

Adds spec/: JSON conformance vectors that record how IMPSY maps input to model input, output back to messages, logs to datasets, and how it reads a .tflite model. It also implements the decisions from #99, #100, #102, #103 and #105, so the vectors describe the behaviour we want, not just what the code happened to do.

Conformance vectors

spec/vectors/ holds 29 cases:

• midi_input.json / websocket_input.json: messages → the [index, value] updates they make to the input vector, or ignored
• midi_output.json / websocket_output.json: output vectors → messages, including clipping, note-offs and polyphony
• pipeline.json: timed MIDI bytes → the [dt, x_1..x_n] vectors sent to the model, plus log rows
• playback.json: model outputs → wait time, values played, and the next model input
• dataset.json: log lines → training rows
• model.json: a fixed-weight 3-d TFLite model in spec/models/. For each step it records the scaled input, raw MDN output, pi/mu/std after temperatures, which output tensor feeds which LSTM state, and which mixture a given uniform draw selects.

impsy/conformance.py defines the cases and runs them through the real MIDIServer, WebSocketServer, InteractionServer, dataset and TfliteMDRNN code with fake ports and a scripted clock. tests/test_conformance.py runs every vector and fails if the committed files are stale. spec/README.md explains the format and how impsy-auv3 and impsy-web should vendor the vectors.

Behaviour changes

• Velocity-0 note-ons are ignored (closes Decide how velocity-0 note-ons are handled on MIDI input #99). By MIDI convention they're note-offs. This applies to MIDI and WebSocket input. WebSocket input now uses the same decoder as MIDI, so a malformed message is skipped instead of ending that client's handler.
• Output rounds to nearest (Decide output quantisation for notes and CCs (ceil vs round, fixed velocity) #100). Notes, CCs and CC min/max scaling use round-half-up instead of ceil. Configurable velocity is still open and waits on midi note and velocity #98.
• Duplicate mappings (closes Specify behaviour for duplicate entries in a MIDI mapping #102).
  • On input, a message mapped to several dimensions sets all of them, as one interaction (one log row, one model input). The sparse callback now takes a list of (index, value) updates.
  • On output, note dimensions that share a channel play polyphonically: each turns off only its own previous note, and no note-off is sent while another dimension holds the same note. MidiOutputState in utils.py replaces the note-off logic that was duplicated across the MIDI, serial MIDI and WebSocket servers.
• Ranged CCs work on input (closes Decide how CC mappings with min/max ranges behave on input #105). A CC mapped as [..., min, max] now matches on input: the raw value is clamped to [min, max] and mapped to (raw - min) / (max - min), which inverts the output scaling. Ranged output now rounds once, round(min + v * (max - min)), instead of rounding twice. Both match what impsy-auv3 and impsy-web already do.
• Timescale is playback speed only (closes Timescale-scaled dt is fed back into the model during playback #103). The model is fed back its own clamped dt; timescale only sets the wait. That step is now InteractionServer.prepare_rnn_playback.
• No change for Specify the initial input vector and first dt before any user input #101. The initial input vector stays random. The pipeline vectors set it explicitly.

docs/config.md describes the new note-off, rounding, duplicate-mapping and ranged-CC behaviour.

Downstream

As they stand, impsy-auv3 and impsy-web will need these changes to pass: rounding (AUv3 already rounds), velocity-0 handling (AUv3 already skips these), one interaction per message, per-dimension note polyphony, and the unscaled dt feedback.

Also un-ignores spec/models/, since models is in .gitignore.

🤖 Generated with Claude Code

[Copilot]

Copilot review overview

🟡 Changes recommended

Unresolved critical pipeline-vector aliasing and moderate WebSocket clipping coverage issues remain.

Review effort: Lite
Findings: 1 · 1 · 1

Open (3)

• Queued model inputs alias mutable arrays across events · New
• WebSocket vectors bypass output clipping behavior · New
• Required model file is missing from copied spec vectors · New

What changed in this PR

Adds machine-readable conformance vectors and tests for IMPSY’s MIDI, WebSocket, pipeline, dataset, and TFLite representations.

Changes:

• Adds JSON conformance vectors and a deterministic model fixture.
• Adds generation and validation runners.
• Documents vector usage and repository conventions.

File	Summary
tests/​test_conformance.py	Validates committed conformance vectors.
spec/​vectors/​websocket_output.json	Defines WebSocket output cases.
spec/​vectors/​websocket_input.json	Defines WebSocket input cases.
spec/​vectors/​pipeline.json	Defines pipeline timing and model-input cases; contains an unresolved aliasing issue.
spec/​vectors/​model.json	Defines TFLite model behavior cases.
spec/​vectors/​midi_output.json	Defines MIDI output cases.
spec/​vectors/​midi_input.json	Defines MIDI input cases.
spec/​vectors/​dataset.json	Defines dataset conversion cases.
spec/​README.md	Documents vector formats and usage; model fixture instructions need correction.
impsy/​conformance.py	Generates conformance vectors; WebSocket clipping coverage is incomplete.
CLAUDE.md	Documents the conformance workflow.
.gitignore	Allows the committed model directory.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.