AquaSynth/state/map.yaml

project: AquaSynth
mission: >
  C# authoring, analysis, and Faust generation layer for AquaSynth patches,
  targeting the AquaSynth/Vortice engine path without dragging the Rust renderer
  into runtime dependencies.
surfaces:
  instructions: AGENTS.md
  doctrine: docs/audio-doctrine.md
  music_agent_orchestration_lessons: docs/music-agent-orchestration-lessons.md
  memory: state/memory.json
  scratch: state/scratch.md
  evidence: state/evidence.jsonl
  spine: state/spine.yaml
  solution: AquaSynth.sln
  core_library: src/AquaSynth.Core
  faust_library: src/AquaSynth.Faust
  daemon_service: src/AquaSynth.Faust/AquaSynthDaemonService.cs
  cultnet_daemon: src/AquaSynth.Faust/AquaSynthCultNetDaemon.cs
  daemon_tool: tools/AquaSynthDaemon/AquaSynthDaemon.csproj
  dings_mcp_service: tools/AquaSynthDingsMcp
  dings_audio_host: tools/AquaSynthDingsHost
  dings_contract: src/AquaSynth.Dings
  auditory_notification_research: docs/research/auditory-notifications/README.md
  verse_service_contract: docs/verse-service-contract.md
  daemonic_swarm_article: docs/gamecult-daemonic-swarm.md
  daemonic_swarm_prior_work: docs/daemonic-swarm-prior-work.md
  patch_library: patches
  tests: tests/AquaSynth.Dsl.Tests
  reference_roadmap: docs/reference-synth-roadmap.md
  ipa_vocal_tract_roadmap: docs/ipa-vocal-tract-roadmap.md
  utterance_parity_research: docs/utterance-parity-research.md
  pink_trombone_parity: docs/pink-trombone-parity.md
  pink_trombone_dsl_parity_plan: docs/pink-trombone-dsl-parity-plan.md
  acoustic_graph_proprioception: docs/acoustic-graph-proprioception.md
  bird_syrinx_golf_research: research/bird-syrinx-golf/README.md
  syrinx_modeling_research: research/syrinx-modeling/README.md
  wet_voice_witness_fixture: tests/AquaSynth.Dsl.Tests/Fixtures/Speech/WetVoice01
  faust_toolchain_boundary: docs/faust-toolchain-boundary.md
  dx7_public_domain_fixtures: tests/AquaSynth.Dsl.Tests/Fixtures/Dx7/PublicDomain
  zyn_reference_source: external/zynaddsubfx
  zyn_upstream_instrument_bank: external/zynaddsubfx/instruments
  pink_trombone_reference_source: external/pink-trombone-mod
  zyn_reference_build_script: tools/zyn-reference/build-zyn-reference.ps1
  zyn_pad_reference_renderer: tools/zyn-reference/ZynPadReference.cpp
  zyn_voice_reference_renderer: tools/zyn-reference/ZynVoiceReference.cpp
  vocal_tract_playground: tools/vocal-tract-playground/index.html
  tract_graph_renderer: tools/TractGraphRenderer/TractGraphRenderer.csproj
  bird_syrinx_golf_tool: tools/BirdSyrinxGolf/BirdSyrinxGolf.csproj
  zyn_reference_build_patches: tools/zyn-reference/patches
  zyn_project_fixtures: tests/AquaSynth.Dsl.Tests/Fixtures/ZynAddSubFX/ProjectAuthored
  core_package: AquaSynth.Core 0.1.0-alpha.3
  faust_package: AquaSynth.Faust 0.1.0-alpha.4
modules:
  model: src/AquaSynth.Core/Model.cs
  parser: src/AquaSynth.Core/PatchScript.cs
  vocal_tract_model: src/AquaSynth.Core/VocalTractModel.cs
  pink_trombone_reference: src/AquaSynth.Core/PinkTromboneReference.cs
  pink_trombone_reference_renderer: src/AquaSynth.Core/PinkTromboneReferenceRenderer.cs
  packed_neural_network: src/AquaSynth.Core/PackedNeuralNetwork.cs
  utterance_embedding_learning: src/AquaSynth.Core/UtteranceEmbeddingLearning.cs
  speech_backpropagation_pipeline: src/AquaSynth.Core/SpeechBackpropagationPipeline.cs
  speech_distributed_training: src/AquaSynth.Core/SpeechDistributedTraining.cs
  vocal_tract_learning: src/AquaSynth.Core/VocalTractLearning.cs
  tract_voice_model: src/AquaSynth.Core/Model.cs
  tract_shape_model: src/AquaSynth.Core/Model.cs
  acoustic_graph_lowering: src/AquaSynth.Core/FaustExport.cs
  primitive_vocal_model: src/AquaSynth.Core/Model.cs
  primitive_vocal_lowering: src/AquaSynth.Core/FaustExport.cs
  primitive_vocal_timeline: src/AquaSynth.Core/ProbeTimelineReport.cs
  primitive_control_spline_timeline: src/AquaSynth.Core/ControlSplineTimeline.cs
  primitive_vocal_reference_report: src/AquaSynth.Core/PrimitiveReferenceReport.cs
  ipa_gesture_experiment: src/AquaSynth.Core/IpaGestureExperiment.cs
  ipa_trial_results: src/AquaSynth.Core/IpaTrialResults.cs
  ipa_trial_timeline_facts: src/AquaSynth.Core/PrimitiveTimelineFactExtractor.cs
  ipa_trial_orchestrator: src/AquaSynth.Faust/IpaTrialOrchestrator.cs
  ipa_trial_worker: tools/IpaTrialWorker
  ipa_trial_external_loop: tools/run-ipa-trial-loop.ps1
  acoustic_graph_missing_pieces_audit: docs/acoustic-graph-missing-pieces-audit.md
  acoustic_graph_proprioception: docs/acoustic-graph-proprioception.md
  pink_trombone_parity_fixtures: src/AquaSynth.Core/PinkTromboneParityFixtures.cs
  pink_trombone_utterance_fixtures: src/AquaSynth.Core/PinkTromboneUtteranceFixtures.cs
  bird_syrinx_patch: patches/advanced/bird-syrinx.aqua
  pink_trombone_logmel_parity_tests: tests/AquaSynth.Dsl.Tests/PinkTromboneLogMelParityTests.cs
  pink_trombone_utterance_reference_tests: tests/AquaSynth.Dsl.Tests/PinkTromboneUtteranceReferenceTests.cs
  faust_emitter: src/AquaSynth.Core/FaustExport.cs
  faust_compiler: src/AquaSynth.Faust/FaustCompiler.cs
  native_faust_runtime: src/AquaSynth.Faust/NativeFaustRuntime.cs
  aquasynth_daemon_service: src/AquaSynth.Faust/AquaSynthDaemonService.cs
  aquasynth_cultnet_daemon: src/AquaSynth.Faust/AquaSynthCultNetDaemon.cs
  aquasynth_daemon_tool: tools/AquaSynthDaemon
  faust_rendered_speech_loss: src/AquaSynth.Faust/FaustRenderedSpeechLossSurface.cs
  cultcache_sound_claim_document: patches/aquasynth-patch-cultcache.cc
  cultcache_sound_claim_types: src/AquaSynth.Core/CultCachePatchDocument.cs
  dx7_reference_render_tests: tests/AquaSynth.Dsl.Tests/Dx7ReferenceParityTests.cs
  espeak_ng_reference_tests: tests/AquaSynth.Dsl.Tests/EspeakNgReferenceTests.cs
  espeak_ng_gradient_descent_tests: tests/AquaSynth.Dsl.Tests/EspeakNgGradientDescentTests.cs
  zyn_reference_reader: src/AquaSynth.Core/ZynInstrument.cs
  zyn_coverage_survey: src/AquaSynth.Core/ZynInstrument.cs
  ipa_vocal_tract_roadmap: docs/ipa-vocal-tract-roadmap.md
  utterance_parity_research: docs/utterance-parity-research.md
  package_boundary_tests: tests/AquaSynth.Dsl.Tests/PackageBoundaryTests.cs
  vocal_tract_model_tests: tests/AquaSynth.Dsl.Tests/VocalTractModelTests.cs
  utterance_embedding_learning_tests: tests/AquaSynth.Dsl.Tests/UtteranceEmbeddingLearningTests.cs
  speech_backpropagation_pipeline_tests: tests/AquaSynth.Dsl.Tests/SpeechBackpropagationPipelineTests.cs
  speech_distributed_training_tests: tests/AquaSynth.Dsl.Tests/SpeechDistributedTrainingTests.cs
  vocal_tract_learning_tests: tests/AquaSynth.Dsl.Tests/VocalTractLearningTests.cs
  vocal_tract_playground: tools/vocal-tract-playground
  tract_graph_renderer: tools/TractGraphRenderer
  bird_syrinx_golf_tool: tools/BirdSyrinxGolf
  sfxr: src/AquaSynth.Core/SfxrParams.cs
  analysis: src/AquaSynth.Core/AudioAnalysis.cs
  mel_cepstral_warp_effect: src/AquaSynth.Core/MelCepstralWarpEffect.cs
  scoring: src/AquaSynth.Core/ScriptMetrics.cs
  presets: src/AquaSynth.Core/Presets.cs
  built_in_scripts: src/AquaSynth.Core/BuiltInScripts.cs
boundaries:
  leave_in_rust:
    - sample renderer
    - PatchPlayer runtime
    - realtime AudioUnit bridge
    - experimental Rust DSL compiler branch
  own_in_csharp:
    - patch graph contracts
    - patch script surface
    - SFXR parameter mapping and atoms
    - analysis and comparison tools
    - script scoring
    - Faust source generation in AquaSynth.Core
    - target-code generation, compile-product contracts, dynamic patch compilation policy, cache identity, generated artifact manifests, and Faust toolchain selection in AquaSynth.Faust
    - live patch compilation, native Faust factory lifetime, and offline sample-buffer render proof in AquaSynth.Faust
    - AquaSynth daemon command ownership for patch.compile, instrument.sample, bounded instrument.stream automation, and live instrument.open/instrument.control/instrument.block/instrument.close sessions: compile/session/render/stream/live/live-session-state/operator typed receipts and witnesses, requested-duration sample renders, persistent native streaming patch instances for live controls, retained aquasynth.live_instrument_session.v1 state for open/closed status/current controls/next sequence, explicit live-session release without deleting compiled patch witnesses, CultMesh-compatible audio/control stream descriptors, per-block .f32 packet artifacts, JSON-lines local transport through tools/AquaSynthDaemon, and a local CultNet host/database that watches typed command documents and publishes typed receipt/provider documents without becoming a second render/session authority
    - IPA-to-phonetic-feature planning, articulatory gesture planning, and human/alien vocal-tract roadmap design
    - phonetic intent, articulatory plan, morphology capability, and constraint-report contracts for vocal tract synthesis
    - packed-buffer native backprop/Adam as the shared AquaSynth gradient-descent primitive
    - learned utterance embedding encoder from speech text embeddings, prosody/emphasis hints, and Ghostlight/Epiphany-shaped character state vectors
    - learned phonetic-plus-utterance-embedding synth driver with packed-buffer native backprop/Adam for tract, AM/FM, LFO, filter, and mel spectral-envelope controls
    - chained utterance-embedding-to-synth-driver backpropagation that returns synth input gradients and updates the utterance encoder from downstream speech loss
    - external-gradient speech backpropagation entry point for rendered loss surfaces
    - distributed speech render request/result/checkpoint CultCache contracts for multi-machine Faust rendering and local backpropagation
    - extracted primitive timeline facts embedded in IPA trial-result CultCache records for contact release, source flow, branch admittance, radiation output, path energy, and passivity evidence
    - CultMesh speech render/scoring worker orchestration with payload manifests, peer/lease admission receipts, worker assignment, result collection, and central checkpoint application; workers return gradients and receipts, while one authority trainer owns optimizer updates and checkpoint commits
    - optional eSpeak NG generated ground-truth fixture for supervised utterance-embedding and synth-driver gradient descent
    - Faust-rendered speech loss surface in AquaSynth.Faust, using rendered audio analysis and finite-difference controller-output gradients
    - compiled native Faust speech-loss surface with exported /speech/output/N controls for batch candidate rendering without recompiling DSP
    - utterance parity curriculum research and docs for structured metadata -> utterance embedding -> synth automation -> rendered speech loss
    - typed CultCache sound-claim document distributed as a real .cc MessagePack-backed CultCache store via CultLib, bundling the patch database with fixture-backed patch claim cards and speech-lane claim cards
  dev_only:
    - public-domain DX7 SysEx fixtures
    - pinned GPL ZynAddSubFX source for parity tests
    - project-authored ZynAddSubFX .xiz fixtures
    - dexed-py reference renderer
    - structured .aqua patch library
checks:
  default: dotnet test
  core_package: dotnet pack src/AquaSynth.Core/AquaSynth.Core.csproj -c Release
  faust_package: dotnet pack src/AquaSynth.Faust/AquaSynth.Faust.csproj -c Release
  faust_validation: automatic in tests when Faust is installed
  dexed_py_reference: optional in tests when AQUASYNTH_DX7_PYTHON or a Python with dexed-py is available
  zyn_reference_source: pinned submodule used only for parity tests; never package content
  pink_trombone_reference_source: pinned MIT submodule used only for parity renderer source audits and port verification; never package content
  espeak_ng_reference: optional command-line development reference, found through ESPEAK_NG or PATH; never package content
  zyn_upstream_instrument_bank: nested GPL submodule used only for test/development pressure surveys and oracle renders; never package content