AquaSynth/state/spine.yaml

project: AquariumSynthCSharp
spine_version: 1
updated: 2026-05-13T00:49:07+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
  analysis: src/AquariumSynth.Dsl/AudioAnalysis.cs
  built_ins: src/AquariumSynth.Dsl/BuiltInScripts.cs
  dx7_references: src/AquariumSynth.Dsl/Dx7SysEx.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.
  - 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 and algorithm topology extraction exist; tiny Aquarium DSL rebuilds are next."
    first_slice:
      - "Rebuild two small DX7-style references in Aquarium DSL."
      - "Compare rebuilds against DX7 topology features and document missing graph concepts."
  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: >
    Rebuild one or two tiny DX7-style references in Aquarium DSL, using the
    parsed DX7 topology features as pressure evidence. Do not import a giant
    bank.
  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 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."