AquaSynth/state/spine.yaml

project: AquariumSynthCSharp
spine_version: 1
updated: 2026-05-13T15:16:00+01:00

prime_directive: >
  Build coherent synth machinery. References exist to reveal missing structure,
  not to justify piling parameters onto the current patch DSL.

current_objective: >
  Turn AquariumSynthCSharp into a reference-driven patch authoring and Faust
  generation library. Use external synths and DSP corpora as pressure tests so
  Aquarium's DSL grows only when a real target proves the abstraction belongs.

current_mechanism:
  parser: src/AquariumSynth.Dsl/PatchScript.cs
  model: src/AquariumSynth.Dsl/Model.cs
  faust_emitter: src/AquariumSynth.Dsl/FaustExport.cs
  faust_renderer: src/AquariumSynth.Dsl/FaustExport.cs
  operator_graph_model: src/AquariumSynth.Dsl/Model.cs
  analysis: src/AquariumSynth.Dsl/AudioAnalysis.cs
  built_ins: src/AquariumSynth.Dsl/BuiltInScripts.cs
  dx7_references: src/AquariumSynth.Dsl/Dx7SysEx.cs
  dx7_reference_fixtures: tests/AquariumSynth.Dsl.Tests/Fixtures/Dx7/PublicDomain
  dx7_reference_renderer_tests: tests/AquariumSynth.Dsl.Tests/Dx7ReferenceParityTests.cs
  reference_rebuilds: src/AquariumSynth.Dsl/ReferenceRebuilds.cs
  tests: tests/AquariumSynth.Dsl.Tests/PatchScriptTests.cs
  doctrine: docs/audio-doctrine.md
  roadmap: docs/reference-synth-roadmap.md
  parameter_contracts: src/AquariumSynth.Dsl/Model.cs

live_invariants:
  - Aquarium owns its patch graph; external synths are references, not runtime dependencies.
  - Patch scripts lower into explicit graph records before Faust emission.
  - Operator graphs own FM topology: operators, modulation edges, carriers, and feedback. Do not hide this authority inside Voice fields.
  - Readable operator graph authoring uses `operator`, `route`, and `carrier` declarations; compact `ops=`/`edges=` is only scaffolding/interchange.
  - Notes own frequency, gate duration, and host/MIDI source; envelopes own ADSR level shape. Do not put note duration or SFXR punch back into the general envelope model.
  - Faust-managed MIDI polyphony is preferred: emit one voice graph with standard `freq`, `gain`, and `gate` controls plus `[midi:on][nvoices:n]` instead of inflating Aquarium graphs for local allocation.
  - Generated Faust should remain inspectable and deterministic.
  - Aquarium Faust output may be rendered through Faust-generated C# for candidate audio comparison; reference parity still needs a real external render or captured licensed fixture.
  - Reference-patch correctness and synth parity tests live in AquariumSynthCSharp, not Aquarium.
  - Exposed patch parameters are runtime controls, not compile-time constants.
  - Parameter binding uses field-site references like `lpf=@/macro/brightness`; do not add target-routing semantics unless a later map proves a new authority is needed.
  - Operator graph parameter binding also uses exact field-site paths under `/opgraphs/...`; do not add graph-wide macro routing.
  - Operator feedback must render through Faust as delayed recursion, not as a direct cyclic self-reference.
  - 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.
  - Public-domain reference fixtures and dexed-py helpers are test/development material only; the NuGet package must ship only AquariumSynth.Dsl.
  - 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.

reference_targets:
  dx7_dexed:
    priority: 1
    purpose: "Structured FM/operator graph pressure test."
    source: "https://github.com/asb2m10/dexed"
    status: "DX7 SysEx parser, public-domain SysEx fixture, dexed-py reference rendering, first thresholded rendered parity test for analog1.syx voice 13, renderable delayed operator feedback, algorithm topology extraction, envelope-to-ADSR approximation, two Aquarium DSL rebuild attempts, first-class operator graph support, and Aquarium candidate rendering through Faust-generated C# exist."
    first_slice:
      - "Add a harder public-domain DX7 parity target that audibly needs operator routing."
  zynaddsubfx:
    priority: 2
    purpose: "Additive, subtractive, PAD, formant, kit, and layered-instrument pressure test."
    source: "https://github.com/zynaddsubfx/zynaddsubfx"
    first_slice:
      - "Parse selected instrument XML files into neutral reference records."
      - "Classify additive, PAD, formant, and effect usage before translation."
  faust:
    priority: 3
    purpose: "General DSP graph topology pressure test."
    sources:
      - "https://github.com/grame-cncm/faust"
      - "https://faustlibraries.grame.fr/"
    first_slice:
      - "Add ExternalFaustReference catalog entries."
      - "Compile selected official examples as external references."
      - "Use failures to decide whether Aquarium needs a lower-level graph DSL."
  surge_xt:
    priority: 4
    purpose: "Modern hybrid synth and modulation matrix pressure test."
    source: "https://github.com/surge-synthesizer/surge"
    first_slice:
      - "Inspect factory patch format and license/provenance."
      - "Build feature extractor before translation."
  cardinal:
    priority: 5
    purpose: "Modular graph and cable/rate semantics pressure test."
    source: "https://github.com/DISTRHO/Cardinal"
    first_slice:
      - "Defer until a lower-level graph layer exists."

next_agent_start_here:
  recommended_first_task: >
    Choose a harder public-domain DX7 fixture voice whose rendered audio needs
    audible operator routing, rebuild it with a readable Aquarium operator
    graph, and compare dexed-py reference audio against Faust-rendered Aquarium
    candidate audio with explicit parity thresholds.
  must_read:
    - AGENTS.md
    - docs/audio-doctrine.md
    - docs/reference-synth-roadmap.md
    - state/spine.yaml
    - state/memory.json
    - state/evidence.jsonl
  verification:
    - "dotnet test AquariumSynthCSharp.slnx --no-restore"

completed_slices:
  - date: 2026-05-13
    summary: >
      Probed the harder `analog1.syx` voice 17 (`PRC SYNTH1`) and found the
      routed candidate failed badly instead of being thresholdable. The useful
      cut was feedback: operator feedback now emits as Faust delayed recursion
      instead of a direct cyclic self-reference, and a render test covers it.
      Exact DX7 feedback scaling and EG behavior remain pressure.
    verification: "dotnet test AquariumSynthCSharp.slnx --no-restore: 49 passed"
  - date: 2026-05-13
    summary: >
      Added the first thresholded rendered DX7 parity rebuild for
      `analog1.syx` voice 13, `MC-MM 5-3`. The candidate is a terse Aquarium
      sine-like behavioral match and the test compares dexed-py reference audio
      against Faust-rendered Aquarium audio using score, log-mel, envelope,
      duration, RMS, zero-crossing, and centroid thresholds. It does not claim
      exact DX7 operator execution.
    verification: "dotnet test AquariumSynthCSharp.slnx --no-restore: 48 passed; focused dexed-py parity test passed with bundled Python"
  - date: 2026-05-13
    summary: >
      Added a public-domain DX7 SysEx fixture from Musical Artifacts artifact
      152, provenance metadata, and a test-only dexed-py renderer. The render
      test uses `AQUARIUM_DX7_PYTHON` when set and otherwise stays optional.
      Added a package-boundary test that packs `AquariumSynth.Dsl` and asserts
      fixtures, SysEx banks, and Python helpers do not ship in the NuGet package.
    verification: "dotnet test AquariumSynthCSharp.slnx --no-restore: 47 passed; dexed-py render test passed with bundled Python"
  - date: 2026-05-13
    summary: >
      Added `FaustCompiler.RenderAsync`, which compiles Aquarium Faust source to
      Faust-generated C#, runs it in a temp .NET project, and returns mono float
      samples. The first render test checks non-silent generated audio and feeds
      the buffer through `AudioAnalyzer`; DX7 audio parity remains blocked on a
      chosen reference renderer or captured fixture.
    verification: "dotnet test AquariumSynthCSharp.slnx --no-restore: 44 passed"
  - date: 2026-05-13
    summary: >
      Added `Dx7EnvelopeApproximation`, a labeled helper that lowers DX7
      four-rate/four-level envelopes to Aquarium ADSR plus gate duration.
      Reference rebuilds now distinguish approximated envelope lowering from
      still-missing exact DX7 EG execution.
    verification: "dotnet test AquariumSynthCSharp.slnx --no-restore: 43 passed"
  - date: 2026-05-13
    summary: >
      Added field-site parameter binding for readable operator graphs. Graph
      gain/note fields, operator ratio/level/feedback/envelope fields, and route
      index fields now bind through exact `/opgraphs/...` paths, and Faust
      emission substitutes those bound expressions in operator graph output.
    verification: "dotnet test AquariumSynthCSharp.slnx --no-restore: 42 passed"
  - date: 2026-05-13
    summary: >
      Added a patch-level Playback contract and `instrument` authoring surface
      for Faust-managed MIDI mono/polyphony. `instrument midi=true polyphony=8`
      emits `[midi:on][nvoices:8]` and standard `freq`, `gain`, and `gate`
      controls instead of Aquarium-owned voice allocation.
    verification: "dotnet test AquariumSynthCSharp.slnx --no-restore: 41 passed"
  - date: 2026-05-13
    summary: >
      Standardized the live envelope model as ADSR and added explicit Note
      records for frequency, one-shot gate duration, and host/MIDI source.
      SFXR sustain now maps to note gate duration; SFXR punch maps to lower
      ADSR sustain level plus voice gain compensation as compatibility import
      behavior. Generated Faust can emit one-shot ADSR envelopes or host
      gate/frequency controls.
    verification: "dotnet test AquariumSynthCSharp.slnx --no-restore: 40 passed"
  - date: 2026-05-13
    summary: >
      Added readable operator graph authoring syntax with `operator`, `route`,
      and `carrier` declarations, plus `env=ad:attack:decay` and
      `env=adsr:attack:decay:sustain:release` forms. Converted the DX7
      algorithm-8 rebuild away from compact number soup.
    verification: "dotnet test AquariumSynthCSharp.slnx --no-restore: 36 passed"
  - date: 2026-05-13
    summary: >
      Added first-class OperatorGraph support with operators, modulation edges,
      carriers, operator feedback, parser syntax, and Faust emission mixed with
      normal voices. Updated the DX7 algorithm-8 rebuild to use the operator
      graph; remaining pressure is exact DX7 feedback-register timing and
      rate/level envelopes.
    verification: "dotnet test AquariumSynthCSharp.slnx --no-restore: 35 passed"
  - date: 2026-05-13
    summary: >
      Added ReferenceRebuild catalog entries and two DX7-style Aquarium DSL
      rebuilds. Algorithm 32 maps cleanly to six additive voices; algorithm 8
      exposes missing operator graph concepts including explicit modulation
      edges, summed modulators, and operator-local self-feedback.
    verification: "dotnet test AquariumSynthCSharp.slnx --no-restore: 34 passed"
  - date: 2026-05-13
    summary: >
      Added DX7 algorithm topology metadata for algorithms 1-32 from the
      reverse-engineered OPS algorithm ROM table. Topology exposes carrier
      operators, modulation edges, feedback-register writers, self-feedback
      operators, delayed-feedback targets, raw ROM steps, and ReferencePatch
      feature pressure.
    verification: "dotnet test AquariumSynthCSharp.slnx --no-restore: 31 passed"
  - date: 2026-05-13
    summary: >
      Added DX7 SysEx records and parsing for 155-byte voice edit buffers,
      128-byte packed voices, and 4104-byte packed 32-voice banks. Extracted
      operators, envelopes, algorithm, feedback, oscillator sync, LFO,
      transpose, voice name, checksum validation, and ReferencePatch features.
    verification: "dotnet test AquariumSynthCSharp.slnx --no-restore: 28 passed"
  - date: 2026-05-13
    summary: >
      Added PatchParameter and ReferencePatch contracts, `param` script parsing,
      duplicate path validation, and Faust hslider emission for declared
      controls. Parameter binding uses field-site references such as
      `lpf=@/macro/brightness`; the emitter substitutes the parameter only at
      the exact bound field site and warns for unbound parameters.
    verification: "dotnet test AquariumSynthCSharp.slnx --no-restore: 23 passed"

cut_line:
  - "Cut any importer that cannot state source provenance and license."
  - "Cut weak tests that only prove parser leniency."
  - "Cut voice-field sprawl when a target needs topology."
  - "Cut any design that requires recompiling a patch to move an exposed musical parameter."
  - "Split a lower-level graph DSL if Faust/Cardinal-style references make the voice DSL lie."