Live 12 catalogue + Phase 2 output validator (warn-and-keep), symusic MIDI migration

[slittycode]

Summary

Two related backend efforts on this branch:

1. Live 12 catalogue + Phase 2 output validator (advisory). Extracts the upstream AbletonLive12_MIDIRemoteScripts into a checked-in catalogue of (device, parameter) tuples (data/live12_catalogue.json + schema, built by scripts/build_live12_catalogue.py), then inspects every Phase 2 Gemini recommendation against it. Devices that aren't in the catalogue, parameters not on the device, out-of-range values, or missing phase1Fields citations surface as RECOMMENDATION_UNVERIFIED advisory warnings on the existing validationWarnings channel. This closes the failure mode where Gemini named a device/parameter the user couldn't actually find in Live.

2. symusic MIDI migration. Migrates the backend's MIDI write/parse paths (sample_synthesis.write_midi, the research polyphonic/ground-truth parsers) off pretty_midi onto symusic, making symusic the single canonical MIDI library on the backend. pretty_midi is retained only as the deliberate parity reader in test_sample_synthesis. Pins symusic==0.6.0 in requirements.txt.

Review-driven redesign: drop/rewrite → warn-and-keep

The validator was originally a mutating gate that dropped recommendations and rewrote parameters. Two independent Opus reviews flagged this as a critical, ship-blocking defect:

1. Confidently-wrong rewrites. difflib fuzzy resolution rewrote a producer's "Band 1 Frequency" to "1 Frequency B" on EQ Eight — wrong band and wrong A/B curve — and shipped it with full authority. A rewrite to the wrong control is worse than the gap it tried to close.
2. Silent dropping of valid advice. The statically-extracted (and therefore incomplete) catalogue couldn't confirm legitimate controls like EQ Eight "Band 1 Gain", so it deleted them.
3. Gate exception → 502. The gate ran inside the try block wrapping the Gemini call, so a catalogue load/parse error would convert an otherwise-successful interpretation into a GEMINI_GENERATE_FAILED 502.

Both defects violate the product's measurement-cited specificity invariant (PURPOSE.md #3). The fix converts apply_live12_catalogue_gates to advisory warn-and-keep, matching the sibling _validate_phase2_citation_paths:

• Never drops a recommendation; never rewrites a parameter. phase2_result is no longer mutated.
• fuzzy_resolve is demoted to a warning-suppressor: a close-but-inexact parameter is kept silently (no wrong-band mutation); only a parameter with no close match warns. The fuzzy target is never trusted to rewrite.
• The new RECOMMENDATION_UNVERIFIED code is intentionally not in the frontend SALVAGE_WARNING_CODES set — nothing is salvaged/dropped, so it renders as a plain advisory warning via the existing graceful fallback rather than tripping the "Gemini output was repaired" decision gate. No frontend change required.
• The gate call in server.py is wrapped in its own try/except → a catalogue error degrades to a CATALOGUE_CHECK_UNAVAILABLE warning instead of a 502.

A regression test asserts EQ-band phrasings ("Band 1 Frequency", "Frequency 1", "Band 1 Gain", …) are never rewritten against the real shipped catalogue, plus coverage that no record is ever dropped.

Commits

1. feat(backend): Live 12 catalogue + Phase 2 output validator
2. refactor(backend): migrate sample_synthesis.write_midi to symusic
3. refactor(backend): migrate research MIDI parsers off pretty_midi to symusic
4. docs(backend): drop PR-E (symusic-beat 4th method) — out of scope
5. fix(backend): pin missing symusic dependency after sample_synthesis migration
6. fix(backend): downgrade Live 12 catalogue gate to warn-and-keep (the review fix)

Test plan

• Full backend suite green: 951 pass, 1 skip (./venv/bin/python -m unittest discover -s tests)
• New regression test: EQ-band parameter phrasings are never rewritten against the real shipped catalogue
• New coverage: no recommendation is ever dropped under any failing check
• test_server.py salvage test (COERCED_ENUM_VALUE) still passes — the _valid_phase2_result() fixture produces zero catalogue warnings under warn-and-keep
• Live Gemini smoke on a known track (RUN_GEMINI_LIVE_SMOKE=true) — recommended before merge to confirm advisory warnings render cleanly on the results surface

🤖 Generated with Claude Code

[slittycode]

Verdict: APPROVE (posted as COMMENT — can't approve own PR)

Summary

Two coherent backend changes: a Live 12 source-catalogue validator that annotates Phase 2 recommendations advisory-only (warn-and-keep, never mutates), and a migration of all backend MIDI write/parse paths from pretty_midi to symusic. Phase boundary is clean throughout. The warn-and-keep redesign correctly eliminates the specific failure mode (confident-but-wrong fuzzy rewrites on multi-band EQ parameters) that motivated the change. The PR claims 951 pass / 1 skip; I cannot run the suite in this environment (no venv on this remote checkout), but the test files are present and the parity contract for write_midi is already wired via the pre-existing WriteMidiTests.test_write_midi_emits_expected_note (reads symusic output back with pretty_midi).

Findings

Worth considering

DeviceEntry is dataclass(frozen=True) with a dict field (_parameters_by_name: dict[str, ParamSpec]). frozen=True synthesises __hash__, which would raise TypeError: unhashable type: 'dict' if a DeviceEntry is ever used as a dict key or in a set. It isn't today, so this is latent, not current. MappingProxyType would fix it cleanly, but it's not a ship-blocker.

_FUZZY_MATCH_CUTOFF = 0.7 at live12_catalogue.py:37 is a bare constant with no calibration reference. The comment in phase2_catalogue_gates.py explains the intent (warning suppressor, never rewriter), and the EQ-band regression test in test_live12_catalogue.py asserts the critical non-rewrite invariant. That's sufficient for now, but document the cutoff origin somewhere before raising it — a 0.8 cutoff could miss the "Band 1 Frequency" → near-match suppression that the redesign relies on.

Score(480, ttype="Second") in sample_synthesis.write_midi (sample_synthesis.py:124): the 480 PPQ is stored but its only function when ttype="Second" is as a hint for MIDI serialisation. The WriteMidiTests parity read via pretty_midi confirms the output is spec-conformant. No action needed, just noting what the 480 is doing.

Not flagging

The re-export chain phase2_catalogue_gates → server_phase2 → server is intentional and documented (keeps the gates module stdlib-only for unit-test isolation). Valid pattern.

require_citation=True is hardwired at every call site in phase2_catalogue_gates.py. The parameter exists for future flexibility; not a bug.

pretty_midi remaining in requirements.txt after the migration is correct — it's retained exclusively as the parity reader in WriteMidiTests.

Test results

Suite not runnable (no venv in this environment). PR states 951 pass / 1 skip. The new test files are present and structurally sound: test_live12_catalogue.py (343 lines, covers API surface + generator + curated-catalogue regression), test_phase2_validator_catalogue.py (532 lines, covers all four warning codes + the explicit no-rewrite assertion). test_server.py fixture updated with phase1Fields citations so the warn-and-keep validator doesn't fire false positives against the existing salvage test.

Phase boundary check

Clean. apply_live12_catalogue_gates reads phase2_result without mutating it. The function is explicitly documented and tested for this invariant. server.py wraps the call defensively so a catalogue parse error produces a CATALOGUE_CHECK_UNAVAILABLE advisory warning rather than failing the Gemini interpretation. Phase 1 measurements are not read, modified, or re-derived anywhere in the new code.

---

Generated by Claude Code