AquaSynth/state/spine.yaml

project: AquariumSynthCSharp
spine_version: 1
updated: 2026-05-13T12:36: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
  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
  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.
  - 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.
  - 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.
  - 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, algorithm topology extraction, two Aquarium DSL rebuild attempts, and first-class operator graph support exist."
    first_slice:
      - "Refine operator graph parameter binding and Faust MIDI integration details."
      - "Add rendered/audio comparison once a render path is explicit."
  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: >
    Refine operator graph parameter binding and Faust MIDI integration details.
    Keep readable authoring syntax as operator/route/carrier
    declarations.
  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: >
      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."