diff --git a/docs/reference-synth-roadmap.md b/docs/reference-synth-roadmap.md index f1e936b..4ca87af 100644 --- a/docs/reference-synth-roadmap.md +++ b/docs/reference-synth-roadmap.md @@ -2,9 +2,10 @@ AquariumSynthCSharp needs external synthesis references for the same reason the SFXR path was useful: a real target prevents the DSL from becoming a pile of -locally plausible knobs. The goal is not to clone every synth. The goal is to -use known engines and patch formats as pressure tests, then rebuild selected -sounds through Aquarium's own graph until the missing abstractions are obvious. +locally plausible knobs. The goal is not to clone every synth's internals. The +goal is to use known engines and patch formats as pressure tests, then rebuild +selected sounds through Aquarium's own graph until the missing abstractions are +obvious. ## Objective @@ -15,6 +16,8 @@ Build a reference-driven synth library workflow: - Rebuild selected references in Aquarium patch DSL. - Compare audio with analysis metrics and listening notes. - Promote only the abstractions that make repeated reference rebuilds simpler. +- Reject reference targets we cannot turn into parity tests. Parsing a format is + inventory; proving Aquarium can reproduce the behavior is the point. The DSL should grow because a reference target demanded a missing invariant, not because a field name seemed maybe useful at 2 AM. @@ -28,8 +31,10 @@ runtime dependencies. of recompiling the patch. - Reference importers must preserve source provenance, license status, and the source format hash. -- Tests may compare against rendered fixtures, extracted parameter topology, or -known structural expectations. Weak "it parsed" tests do not prove expressivity. +- Tests must compare against rendered fixtures, extracted parameter topology, or +known structural expectations that prove Aquarium can express the same behavior. +Weak "it parsed" tests do not prove expressivity, and references without a +credible parity test path should not be consumed. - Do not add a generic graph escape hatch until a specific family of references forces it. - When a reference target exceeds the current voice-centric DSL, document the diff --git a/state/evidence.jsonl b/state/evidence.jsonl index 86567b8..d6646d3 100644 --- a/state/evidence.jsonl +++ b/state/evidence.jsonl @@ -19,3 +19,4 @@ {"kind":"faust_polyphony","lesson":"Prefer Faust-managed MIDI polyphony over Aquarium graph inflation. Aquarium should emit a single voice graph with standard `freq`, `gain`, and `gate` controls plus `[midi:on][nvoices:n]`; Faust architectures own MIDI decoding and voice allocation unless a concrete target proves the boundary insufficient.","source":"Faust official MIDI/polyphony docs and user preference for Faust support on 2026-05-13"} {"kind":"operator_graph_parameters","lesson":"Readable operator graph fields bind runtime parameters at exact `/opgraphs/...` field paths: graph gain/note fields, operator ratio/level/feedback/envelope fields, and route index fields. Keep compact `ops=`/`edges=` as importer scaffolding and avoid graph-wide macro routing.","source":"operator graph field-site binding slice on 2026-05-13"} {"kind":"dx7_envelopes","lesson":"DX7 four-rate/four-level operator envelopes can be lowered to labeled Aquarium ADSR approximations plus gate duration, but this is not exact DX7 EG execution. Reference rebuilds should record approximation as matched pressure and exactness as still missing.","source":"DX7 envelope approximation slice on 2026-05-13; Yamaha DX7 manual describes EGs as four rates and four levels"} +{"kind":"reference_parity_doctrine","lesson":"External synth references exist to exercise Aquarium DSL expressiveness, not to clone foreign internals. Consume only references that can be backed by parity tests proving Aquarium can reproduce the behavior in terse, readable syntax; parsing a format is inventory, not evidence.","source":"user clarified reference-synth purpose and parity-test requirement on 2026-05-13"} diff --git a/state/memory.json b/state/memory.json index 1b48548..493188b 100644 --- a/state/memory.json +++ b/state/memory.json @@ -41,7 +41,7 @@ "state/spine.yaml" ], "reference_strategy": { - "purpose": "Use external synths and DSP corpora as pressure tests for Aquarium's patch DSL and Faust emitter.", + "purpose": "Use external synths and DSP corpora as parity pressure for Aquarium's patch DSL and Faust emitter: the DSL must reproduce behavior in terse, readable Aquarium syntax, not clone foreign internals.", "priority_order": [ "DX7/Dexed SysEx for FM operator topology", "ZynAddSubFX instruments for additive, subtractive, PAD, formant, and layered patches", @@ -49,7 +49,7 @@ "Surge XT for modern hybrid synth modulation", "Cardinal/VCV-style patches for modular cable/rate semantics" ], - "rule": "Add DSL abstractions only when reference rebuilds prove the missing invariant." + "rule": "Add DSL abstractions only when reference rebuilds prove the missing invariant. Do not consume references that cannot be backed by parity tests; parsing alone is inventory, not evidence of expressivity." }, "dx7_reference_path": { "status": "DX7 SysEx parser extracts voice edit buffers, packed voices, packed 32-voice banks, six operators, envelopes, algorithm, feedback, oscillator sync, LFO, transpose, voice name, checksum validation, ReferencePatch features, algorithm topology from the reverse-engineered OPS algorithm ROM table, envelope-to-ADSR approximations, two Aquarium DSL rebuild attempts, and first-class OperatorGraph support.", @@ -70,6 +70,6 @@ "last_verified": { "command": "dotnet test AquariumSynthCSharp.slnx --no-restore", "result": "43 passed", - "commit": "pending DX7 envelope approximation commit" + "commit": "pending reference parity doctrine update" } } diff --git a/state/scratch.md b/state/scratch.md index 41f8ee7..936744d 100644 --- a/state/scratch.md +++ b/state/scratch.md @@ -5,6 +5,14 @@ targets, not through speculative field sprawl. `state/spine.yaml` and `docs/reference-synth-roadmap.md` are the handoff surfaces for agents working on the synth library while Aquarium work continues elsewhere. +Doctrine update: + +- External synths are parity pressure for Aquarium's DSL, not internals to + clone. Only consume targets that can be backed by parity tests proving + Aquarium can reproduce the behavior in terse, readable syntax. +- Parsing a synth format is inventory. Rebuilding and testing behavior is the + proof. + Completed this slice: - Added `Dx7EnvelopeApproximation`, which lowers a DX7 four-rate/four-level EG diff --git a/state/spine.yaml b/state/spine.yaml index 4db17ca..9dd547f 100644 --- a/state/spine.yaml +++ b/state/spine.yaml @@ -1,6 +1,6 @@ project: AquariumSynthCSharp spine_version: 1 -updated: 2026-05-13T13:11:00+01:00 +updated: 2026-05-13T13:18:00+01:00 prime_directive: > Build coherent synth machinery. References exist to reveal missing structure, @@ -40,6 +40,7 @@ live_invariants: - DX7 rate/level envelopes may lower to labeled ADSR approximations, but exact DX7 EG execution remains missing pressure. - Recompile only for graph shape changes; vary declared parameters through the hosted DSP control API. - Reference fixtures must preserve provenance, license status, source hash, and feature pressure. + - Do not consume external synth targets that cannot be backed by parity tests. Parsing is inventory; reproducing behavior through terse, readable Aquarium DSL is the proof. - Audio metrics are evidence, not final judgment. - Do not add a generic graph escape hatch until specific references force it. - Do not hide missing graph structure behind unrelated voice fields.