AquaSynth/state/spine.yaml

project: AquariumSynthCSharp
spine_version: 1
updated: 2026-05-14T14:09: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
  patch_library: patches
  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
  dx7_calibration_plan: docs/dx7-calibration-plan.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 operator output level approximation belongs in reference import/rebuild helpers, not the generic DSL model.
  - DX7 carrier output amplitude follows the measured `2^((outputLevel - 99) / 8)` curve; do not restore the old internal-level proxy.
  - DX7 isolated two-operator modulation uses Aquarium route index `6.275` for full-level modulators; do not apply that blindly to cascaded stacks before algorithm output compensation is modeled.
  - DX7 feedback lowers through `Dx7SysEx.OperatorFeedbackAmount`; do not restore PRC-local `feedback * constant` folklore.
  - DX7 ratio-mode detune lowers through `Dx7SysEx.OperatorFrequencyRatio`; do not silently drop detune from operator graph scripts.
  - DX7 algorithm output compensation lowers through ROM `COM` values relative to the algorithm-32 six-output baseline; do not restore PRC-local carrier scale tables.
  - DX7 route lowering is topology-aware: isolated direct branches use `OperatorModulationRouteIndex` (`6.275`); summed edges and direct edges feeding summed modulation use `SummedOperatorModulationRouteIndex` (`6.0`).
  - `SummedOperatorModulationRouteIndex` is backed by the hard PRC target, a project-authored algorithm-8 stack probe, and split cascade/summed-pair probes; do not restore the older under-bright `1.6` scale.
  - DX7 calibration must proceed through isolated rungs in `docs/dx7-calibration-plan.md`; do not keep tuning hard PRC-specific constants as a substitute for a level/index model.
  - Staged operator envelopes own multi-target operator level contours through `env=rl rates=... levels=...`; do not force DX7-style contours back into the general ADSR voice envelope model.
  - Staged operator envelopes may use per-segment curves through `curves=lin,exp,...`; this belongs to the rate/level contour authority, not to the standard ADSR envelope.
  - DX7 rate/level envelopes may lower to staged operator envelopes or labeled ADSR approximations, but exact DX7 EG timing/gain calibration remains missing pressure.
  - DX7 envelope trace evidence now lives in `Dx7SysEx.TraceEnvelope`, `Dx7SysEx.TraceInterpolatedEnvelope`, and `artifacts/parity/dx7-envelope-trace/egstep.csv`; Dexed-style audio uses block-interpolated applied gain, not the raw EG state alone.
  - Do not add an `env=dx7` runtime surface until it matches Dexed plugin audio with the block-interpolated gain model, not only the raw trace helper.
  - DX7 applied envelope lowering now lives in `Dx7SysEx.ApproximateAppliedRateLevelEnvelope`; it normalizes traced applied gain so operator output level remains a separate authority.
  - 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.
  - Structured `.aqua` stock lives under `patches/` as development source material. Every library patch must parse/export, and the patch library must stay out of the NuGet package unless intentionally promoted.
  - Project-authored Dexed patches may be generated inside tests for calibration; do not ship them in the NuGet package or treat them as runtime dependencies.
  - Harsh calibration probes belong in tests and ignored artifacts, not in the patch library unless they are musically useful stock.
  - Listening WAV artifacts belong under ignored `artifacts/`; keep them out of NuGet and commits unless explicitly promoted as fixtures.
  - 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, project-authored Dexed patch rendering, first thresholded rendered parity test for analog1.syx voice 13, hard PRC SYNTH1 probe with listening WAV artifacts and log-mel <= 0.255, project-authored algorithm-8 summed-stack parity, renderable delayed operator feedback, DX7 effective operator-level approximation, measured carrier output amplitude, isolated route index, feedback table, ratio detune lowering, ROM COM output compensation, staged operator envelopes, DX7 envelope tracing, 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: >
    Listen to the latest generated PRC SYNTH1 WAVs under
    `artifacts/parity/dx7-prc-synth1`. Continue the ladder in
    `docs/dx7-calibration-plan.md` with envelope level curve calibration.
    Single-carrier amplitude, isolated
    two-op modulation index, feedback, ratio detune, ROM COM output
    compensation, and topology-aware route lowering are now fitted or mapped;
    a project-authored algorithm-8 stack test now backs the summed route scale
    outside PRC. Curved applied-envelope lowering plus stronger summed/cascaded
    route scale now gives PRC the same character with closer harsh stacked
    modulation. Split project-authored algorithm-8 cascade and summed-pair
    probes now back the 6.0 summed/cascaded route scale. Next pressure is
    residual PRC high-air/timbre mismatch and high zero-crossing mismatch on
    broader public-domain community voices before broad import.
  must_read:
    - AGENTS.md
    - docs/audio-doctrine.md
    - docs/dx7-calibration-plan.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-14
    summary: >
      Added a rendered public-domain community DX7 parity test against four
      actual `analog1.syx` voices from Musical Artifacts artifact 152:
      `ANLGSYN 1`, `{ Mooger }`, `Piano Bass`, and `RES SYNTH1`. The test
      renders Dexed references, lowers the same voices through the current
      Aquarium DX7 operator-graph path, writes listening WAV/report artifacts
      under `artifacts/parity/dx7-community-analog1/`, and gates broad parity
      at log-mel <= 0.3, envelope <= 0.16, score >= 0.5. First survey also
      tried `DX1 LEAD B` and `MELLOWSOLO`; they remain pressure because
      log-mel/zero-crossing mismatch is too large for the broad gate.
    verification: "AQUARIUM_DX7_PYTHON=<bundled python> dotnet test AquariumSynthCSharp.slnx --no-restore: 70 passed"
  - date: 2026-05-14
    summary: >
      Added split project-authored DX7 algorithm-8 parity probes for the
      cascaded `6 -> 5 -> 3` branch and summed `4 + 5 -> 3` branch. The tests
      render Dexed references, render Aquarium operator-graph candidates, write
      listening WAV/report artifacts under `artifacts/parity/dx7-project-authored/`,
      and gate log-mel at <= 0.06. Latest real-Dexed run: combined stack
      log-mel 0.04029555/score 0.8664546, summed pair 0.042429477/0.870778,
      cascade 0.03811625/0.9157809. The split probes remain test/artifact
      material rather than patch-library stock because they are calibration
      signals, not usable sounds.
    verification: "AQUARIUM_DX7_PYTHON=<bundled python> dotnet test AquariumSynthCSharp.slnx --no-restore: 69 passed"
  - date: 2026-05-14
    summary: >
      Added a structured development patch library under `patches/` with a
      machine-readable `library.yaml`, README, and `.aqua` files exported from
      existing stock/reference catalogs plus the calibrated PRC SYNTH1 parity
      candidate. Added tests so every library `.aqua` parses and exports Faust,
      while package-boundary tests assert `patches/` and `.aqua` files do not
      ship in the AquariumSynth.Dsl NuGet package.
    verification: "dotnet test AquariumSynthCSharp.slnx --no-restore: 67 passed"
  - date: 2026-05-14
    summary: >
      Increased `Dx7SysEx.SummedOperatorModulationRouteIndex` from 1.6 to 6.0
      after listening identified missing harsh stacked-modulation brightness.
      The stronger scale improves PRC log-mel to 0.13874426, envelope distance
      to 0.067291506, centroid ratio to 1.1156512, and score to 0.7546445 with
      RMS ratio 0.9912135. The independent project-authored algorithm-8
      summed-stack test now uses graph gain 0.218 and tighter log-mel/RMS gates.
    verification: "AQUARIUM_DX7_PYTHON=<bundled python> dotnet test AquariumSynthCSharp.slnx --no-restore --filter \"PublicDomainDx7PrcSynth1WritesListeningWavsWhenInstalled|ProjectAuthoredDx7AlgorithmEightSummedStackMeetsParityWhenInstalled\": passed"
  - date: 2026-05-14
    summary: >
      Added `Dx7SysEx.ApproximateAppliedRateLevelEnvelope` and used it in the
      hard PRC SYNTH1 probe. The helper traces Dexed-style block-interpolated
      applied EG gain, normalizes it against Aquarium operator-output scaling,
      and emits curved `env=rl` syntax. PRC log-mel improved from 0.24476814 to
      0.21931955 and envelope distance from 0.43700194 to 0.10271241, with RMS
      ratio near unity. A follow-up fixed the peak picker for slower rising
      envelopes after listening exposed op2's false late swell; PRC now reaches
      log-mel 0.17186502, envelope distance 0.13057204, zero-crossing ratio
      0.7815517, and score 0.6501268.
    verification: "AQUARIUM_DX7_PYTHON=<bundled python> dotnet test AquariumSynthCSharp.slnx --no-restore --filter \"PublicDomainDx7PrcSynth1WritesListeningWavsWhenInstalled|ProjectAuthoredDx7AlgorithmEightSummedStackMeetsParityWhenInstalled|ApproximatesDx7AppliedEnvelopeAsCurvedRateLevelEnvelope\": passed"
  - date: 2026-05-14
    summary: >
      Added per-segment curves to staged operator envelopes. `env=rl` remains
      the same rate/level contour surface, but can now express linear or
      exponential segments with deliberate levels above unity. The DX7 envelope
      trace artifact includes a curved Aquarium candidate that is much closer
      to Dexed's block-interpolated applied gain than the old linear contour.
    verification: "dotnet test AquariumSynthCSharp.slnx --no-restore --filter \"OperatorGraphSyntaxParsesReadableRateLevelEnvelope|OperatorGraphSyntaxParsesCurvedRateLevelEnvelope|ProjectAuthoredDx7EnvelopeTraceWritesComparisonArtifact\": passed"
  - date: 2026-05-14
    summary: >
      Added `Dx7SysEx.TraceInterpolatedEnvelope` and extended the DX7 envelope
      trace artifact with raw and applied gain columns. Dexed-style operator
      rendering samples the EG once per 64-sample block and interpolates the
      applied gain across the block, so matching the raw EG state alone is not
      enough for audio parity.
    verification: "dotnet test AquariumSynthCSharp.slnx --no-restore --filter \"TracesDx7EnvelopeAppliedBlockInterpolatedGain|TracesDx7EnvelopeInternalGainShape|ProjectAuthoredDx7EnvelopeTraceWritesComparisonArtifact\": passed"
  - date: 2026-05-14
    summary: >
      Added `Dx7SysEx.TraceEnvelope` and an envelope trace comparison artifact.
      The trace shows DX7 EG behavior that current `env=rl` cannot express:
      an initial gain spike above 1 followed by millisecond-scale collapse to a
      tiny sustain. A first `env=dx7` runtime lowering attempt was cut because
      matching the local trace did not match Dexed plugin audio.
    verification: "dotnet test AquariumSynthCSharp.slnx --no-restore --filter \"ProjectAuthoredDx7EnvelopeTraceWritesComparisonArtifact|TracesDx7EnvelopeInternalGainShape\": passed"
  - date: 2026-05-14
    summary: >
      Added test-only project-authored Dexed patch rendering and an independent
      algorithm-8 summed-stack parity test. This backs topology-aware summed
      route lowering outside the public-domain PRC hard target. An attempted
      exponential DX7 EG level curve was tested and cut: it improved some
      envelope metrics but failed PRC log-mel, so EG levels remain linear until
      isolated envelope parity can pass without harming PRC.
    verification: "AQUARIUM_DX7_PYTHON=<bundled python> dotnet test AquariumSynthCSharp.slnx --no-restore --filter \"ProjectAuthoredDx7AlgorithmEightSummedStackMeetsParityWhenInstalled|PublicDomainDx7PrcSynth1WritesListeningWavsWhenInstalled|Dx7SysExTests\": passed"
  - date: 2026-05-14
    summary: >
      Moved the remaining PRC cascaded-route scalar into
      `Dx7SysEx.OperatorRouteIndex(topology, edge)`. Isolated direct branches
      use the two-op route scale 6.275; summed edges and direct edges feeding a
      summed branch use the summed/cascaded route scale 1.6. The PRC probe no
      longer owns a private route-index function.
    verification: "AQUARIUM_DX7_PYTHON=<bundled python> dotnet test AquariumSynthCSharp.slnx --no-restore --filter \"Dx7SysExTests|PublicDomainDx7PrcSynth1WritesListeningWavsWhenInstalled\": passed"
  - date: 2026-05-14
    summary: >
      Added DX7 ratio-mode detune and algorithm output compensation to central
      lowering. `Dx7SysEx.OperatorFrequencyRatio` preserves detune in operator
      graph ratios, and `Dx7SysEx.OperatorOutputCompensation` maps ROM `COM`
      output counts relative to the algorithm-32 six-output amplitude baseline.
      The PRC probe no longer carries a manual carrier-level scale table; its
      remaining cascaded-route value is fenced as a hard-target probe scar.
    verification: "AQUARIUM_DX7_PYTHON=<bundled python> dotnet test AquariumSynthCSharp.slnx --no-restore --filter \"Dx7SysExTests|PublicDomainDx7PrcSynth1WritesListeningWavsWhenInstalled\": passed"
  - date: 2026-05-14
    summary: >
      Completed the DX7 feedback calibration rung. Isolated feedback sweeps fit
      Aquarium feedback amounts `0, .01, .02, .05, .10, .19, .38, .66` for DX7
      feedback values 0-7. `Dx7SysEx.OperatorFeedbackAmount` now owns that
      table, and the PRC probe no longer uses a local `feedback * constant`.
    verification: "AQUARIUM_DX7_PYTHON=<bundled python> dotnet test AquariumSynthCSharp.slnx --no-restore --filter \"CalibratesDx7FeedbackToAquariumFeedbackAmount|PublicDomainDx7PrcSynth1WritesListeningWavsWhenInstalled\": passed"
  - date: 2026-05-14
    summary: >
      Completed the isolated two-operator modulation-index rung. Dexed sweeps
      fit full-level modulation at about 12.55 radians, which maps to Aquarium
      route index 6.275 under the current Faust phase formula. The PRC probe
      applies that calibrated route only to the isolated `op2 -> op1` branch;
      applying it to the cascaded stack made metrics worse, leaving algorithm
      output compensation as explicit pressure.
    verification: "AQUARIUM_DX7_PYTHON=<bundled python> dotnet test AquariumSynthCSharp.slnx --no-restore --filter PublicDomainDx7PrcSynth1WritesListeningWavsWhenInstalled: passed"
  - date: 2026-05-14
    summary: >
      Added `docs/dx7-calibration-plan.md` and completed the first calibration
      rung. A project-authored Dexed single-carrier output-level sweep showed
      carrier amplitude follows `2^((outputLevel - 99) / 8)`. `Dx7SysEx` now
      exposes `OperatorOutputAmplitude` and `ApproximateOperatorLevel` uses that
      measured curve instead of the old internal-level proxy. The PRC log-mel
      gate is temporarily 0.26 while the next rung calibrates modulation index.
    verification: "AQUARIUM_DX7_PYTHON=<bundled python> dotnet test AquariumSynthCSharp.slnx --no-restore --filter \"Dx7SysExTests|PublicDomainDx7PrcSynth1WritesListeningWavsWhenInstalled\": passed"
  - date: 2026-05-14
    summary: >
      Reoriented the hard DX7 `PRC SYNTH1` probe around log-mel distance after
      listening confirmed aggregate score was rewarding the wrong thing.
      Spectral diagnosis showed the reference's low body around 131 Hz and
      dominant 393 Hz partial; the candidate now uses the DX7 note basis and
      scaled high modulators to reach log-mel 0.25093183, with remaining
      zero-crossing/centroid mismatch left as explicit pressure.
    verification: "AQUARIUM_DX7_PYTHON=<bundled python> dotnet test AquariumSynthCSharp.slnx --no-restore --filter PublicDomainDx7PrcSynth1WritesListeningWavsWhenInstalled: passed"
  - date: 2026-05-14
    summary: >
      Tightened the hard DX7 `PRC SYNTH1` probe to require score >= 0.60 and
      improved the candidate to 0.6057491. The useful calibration cuts were
      removing Aquarium soft clipping, setting the graph base frequency to 392,
      and boosting the op3 carrier branch for algorithm-8 output/body balance.
      Global detune and per-edge route damping were tested and cut because they
      made the metrics worse.
    verification: "AQUARIUM_DX7_PYTHON=<bundled python> dotnet test AquariumSynthCSharp.slnx --no-restore --filter PublicDomainDx7PrcSynth1WritesListeningWavsWhenInstalled: passed"
  - date: 2026-05-13
    summary: >
      Added a hard DX7 `PRC SYNTH1` rendered parity probe that emits listening
      WAV artifacts under ignored `artifacts/parity/dx7-prc-synth1` when
      dexed-py and Faust are available. The Aquarium candidate uses readable
      operator graph syntax and staged `env=rl` envelopes, asserts a modest
      hard-target score floor, and currently scores 0.4581856 with duration
      close to the Dexed reference but remaining gain/timbre mismatch.
    verification: "AQUARIUM_DX7_PYTHON=<bundled python> dotnet test AquariumSynthCSharp.slnx --no-restore --filter PublicDomainDx7PrcSynth1WritesListeningWavsWhenInstalled: passed"
  - date: 2026-05-13
    summary: >
      Added staged operator envelopes for operator graphs through
      `env=rl rates=... levels=...`, backed by a `RateLevelEnvelope` model,
      parser support, Faust `rl4_env(...)` rendering, and DX7 helper output
      from four-rate/four-level operator EG data. Direct DX7 rate/level
      lowering on `PRC SYNTH1` only reached ~0.316 in quick probes, so the DSL
      surface exists but DX7 EG timing/gain calibration remains the next
      pressure.
    verification: "dotnet test AquariumSynthCSharp.slnx --no-restore: 53 passed"
  - date: 2026-05-13
    summary: >
      Added `Dx7OperatorLevelApproximation`, which maps DX7 operator output
      level plus key/velocity scaling into normal Aquarium operator levels for
      reference rebuild work. Retried `PRC SYNTH1`; static level mapping alone
      did not produce parity, and envelope tweaks only reached ~0.42 score. The
      next pressure is DX7-style operator envelope/gain evolution.
    verification: "dotnet test AquariumSynthCSharp.slnx --no-restore: 50 passed"
  - 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."