AquaSynth/docs/faust-toolchain-boundary.md

# Faust Toolchain Boundary

AquaSynth owns the path from patch intent to loadable DSP product. Aquarium
Engine owns audio hosting. That split keeps the compiler brain near the patch
model and keeps the engine from becoming a synth compiler with a game loop
stapled to it.

Package ownership follows that boundary:

- `AquaSynth.Core` owns patch meaning: model records, `.aqua` parsing, analysis,
  presets, and Faust source emission.
- `AquaSynth.Faust` depends on Core and owns toolchain/rendering: Faust CLI
  validation, target-code generation, live patch compilation, native `libfaust`
  loading, compile manifests, factory lifetime, and offline/sample rendering.

## Pipeline Map

1. AquaSynth parses `.aqua` script into an explicit `SynthPatch`.
2. AquaSynth emits stable, inspectable Faust source.
3. AquaSynth resolves a pinned Faust toolchain or caller-provided Faust path.
4. AquaSynth compiles the patch into a target artifact.
5. AquaSynth emits a manifest for parameters, buses, MIDI behavior, sample-rate
   assumptions, cache keys, diagnostics, and artifact provenance.
6. Aquarium loads the artifact, binds parameters, schedules notes and buffers,
   and calls the DSP from its realtime path.

Aquarium may request compilation, cache lookup, reload, or diagnostics. It
should not need to know how AquaSynth chooses Faust flags, target languages,
architecture files, generated source layout, or artifact identity.

## Ownership

AquaSynth owns:

- patch graph contracts
- Faust source emission
- Faust toolchain selection and version pinning
- compile cache keys
- generated source/native artifact layout
- parameter and bus manifests
- diagnostics and compile provenance
- dynamic patch compilation outside the realtime callback
- native Faust factory lifetime and offline/sample-buffer rendering for hosts
- live patch compiler sessions requested by engine hosts

Aquarium owns:

- device I/O
- buffer scheduling
- audio-thread rules
- note/event delivery
- plugin or engine integration
- artifact loading policy for its platform
- presentation and editor UX

## Runtime Rule

Compilation is never an audio-thread operation. Dynamic patches compile in a
background worker or build step, then Aquarium swaps in a finished DSP artifact
through a realtime-safe handoff.

Parameter changes are not recompiles. Recompile only when graph shape changes;
ordinary patch controls move through the compiled DSP parameter API.

## Target Lanes

- Authoring/tests may use Faust-generated C# because it is easy to render,
  inspect, and compare inside the .NET test suite.
- Browser-hosted tools should use Faust-generated WebAssembly plus Faust JSON UI
  metadata. AquaSynth owns those artifacts; the web app owns WebAudio loading,
  scheduling, user gesture unlocking, and parameter binding.
- Shipping builds should prefer Faust-generated native targets when the platform
  permits it.
- A bundled Faust compiler belongs in an AquaSynth toolchain package or
  installer lane, not as an accidental dependency of the core DSL package.
- Consumer runtimes should normally bundle compiled DSP artifacts plus manifests,
  not the compiler itself, unless live user patch authoring is a product feature.

Current API foothold: `AquaSynthPatchCompiler` is the host-facing live compiler
surface. It owns lazy `libfaust` loading through AquaSynth, compiles `.aqua`
scripts into native Faust factories, writes optional `.dsp` artifacts, and
returns `AquaSynthCompiledPatch` products with `AquaSynthNativeManifest`.
`AquaSynthRenderSession` is only a render-proof convenience wrapper for tests
and offline one-shot buffers.

Library lookup is platform-aware: `libfaust.so` on Linux, `libfaust.dylib` on
macOS, `libfaust.dll` (then `faust.dll`) on Windows, always at `<home>/lib` with
`<home>/share/faust` beside it. `AquaSynthNativeOptions.FaustLibraryPath` or
`AQUASYNTH_FAUST_LIBRARY` names the library file directly and overrides the home
search; `FaustHome` then supplies `share/faust` if the prefix is not the file's
grandparent. The loader prepends `lib` and `bin` to `PATH` using the platform
path separator.

## Invariants

- AquaSynth remains the authority for what a patch means.
- Faust remains the pure DSP target, not the host runtime.
- Aquarium remains the realtime host, not the compiler.
- Generated artifacts are reproducible from script, AquaSynth version, Faust
  version, target, compile options, and architecture inputs.
- Licenses and provenance travel with toolchains, reference inputs, generated
  artifacts, and packaged output.