# AquaSynth Verse Service Contract AquaSynth is the synth daemon. It accepts `.aqua` DSL and speech/utterance control documents, compiles Faust-native instruments, returns live instrument handles, and publishes controllable audio/render state through CultMesh. ## Authority Owner: AquaSynth. Inputs: - `.aqua` patch DSL - `weksa.utterance_handoff.v0` - `weksa.utterance_embedding_handoff.v0.1` - learned phonetic realization and synth-driver model state - render, sampling, and live-control requests Outputs: - `aquasynth.patch_graph.v0` - `aquasynth.faust_source.v0` - `aquasynth.compiled_instrument_session.v1` - `aquasynth.live_instrument_session.v1` - `aquasynth.instrument_open_receipt.v1` - `aquasynth.instrument_control_receipt.v1` - `aquasynth.instrument_block_receipt.v1` - `aquasynth.instrument_close_receipt.v1` - `aquasynth.render_sample.v0` Weksa owns conversational intent and utterance lowering. AquaSynth owns the learned utterance embedding, synth-driver automation, Faust compilation, native binary lifetime, live instrument handles, control sessions, and sampled outputs. ## CultCache Witnesses - `.aquasynth/provider-advertisement.cc`: read-only provider advertisement witness. - `.aquasynth/patches/{patchId}.cc`: parsed `.aqua` patch graphs and semantic control catalogs. - `.aquasynth/faust/{compileId}.cc`: emitted Faust source, compile options, diagnostics, and artifact references. - `.aquasynth/instruments/{instrumentId}.cc`: compiled native binary, ABI, control catalog, architecture target, and lifecycle receipts. - `.aquasynth/sessions/{sessionId}.cc`: live instrument handle, lease, control values, transport state, and teardown receipt. - `.aquasynth/live-sessions/{sessionId}.cc`: retained live session state for the service-owned streaming patch instance: open/closed status, current control values, block size, next sequence, and last command/receipt ids. - `.aquasynth/renders/{renderId}.cc`: offline/live sample outputs, feature measurements, and scoring receipts. - `.aquasynth/speech/{utteranceId}.cc`: Weksa handoff consumption, packed utterance embeddings, synth-driver outputs, and render receipts. ## CultMesh Verses - `aquasynth.service`: service identity, version, schema catalog, and health. - `aquasynth.patch`: `.aqua` parse/validation/graph state. - `aquasynth.compile`: Faust emission, native compilation, diagnostics, and artifact handles. - `aquasynth.instrument`: compiled instrument handles, control catalogs, and lifecycle state. - `aquasynth.speech`: utterance embedding, speech-driver, and render-training state. - `aquasynth.operator`: daemon status, queue pressure, toolchain readiness, witness freshness, and degraded-mode visibility. ## Operator Dashboards Eve is deprecated, and Thing 2 is its successor (`thing2:ruling:eve-dashboards-quarantined`, 2026-10-22). AquaSynth advertises no operator-dashboard surface; it publishes typed CultMesh state meanwhile, and its operator view returns on Thing 2. ## Commands - `patch.compile`: parse `.aqua`, emit Faust, compile a native target, and return an instrument handle. - `instrument.open`: allocate or attach to a compiled instrument session. - `instrument.control`: set one or more stable semantic controls. - `instrument.block`: process one fixed block through an open live instrument session and return the block receipt/artifact reference. - `instrument.close`: release an open live instrument session without deleting the compiled instrument product. - `instrument.sample`: sample a live or offline instrument output. - `instrument.stream`: compile/open a streaming instrument session, apply block-indexed automation controls, publish CultMesh-compatible audio/control stream descriptors, and write per-block sample packet receipts. - `speech.realize`: consume a Weksa utterance handoff and produce synth-driver controls plus render receipts. - `provider.advertise`: publish `gamecult.eve.provider_advertisement.v1`. Every command must commit typed receipts through the same derivation path used by any CLI or worker. A dashboard, REPL, worker loop, or native host must not invent a separate truth for compiled products or control state. ## Runnable Daemon Slice `tools/AquaSynthDaemon` is the current local daemon body. It exposes: - `once`: accepts inline `.aqua` or `--script-file`, compiles through the native Faust boundary, renders samples, writes `.f32` and `.wav` artifacts, and commits typed `.cc` witnesses under the configured store root. - `daemon`: reads JSON-lines command envelopes from stdin and writes JSON-lines receipts to stdout. The JSON-lines stream is an edge transport for local smoke and xenos callers; command/session/render authority lives in `AquaSynthDaemonService` and its CultCache witnesses. - `stream`: runs a bounded automation stream locally. It compiles once, opens a native Faust streaming patch, processes fixed-size blocks with optional per-block controls, publishes CultMesh `Audio` and `Tensor` descriptors inside the service, writes block `.f32` packet bodies, and commits one typed stream receipt. - `daemon` and `cultnet-daemon` also accept `instrument.open`, `instrument.control`, `instrument.block`, and `instrument.close` envelopes. These live commands keep and release service-owned native streaming patch instances; closing a live session does not delete the reusable compiled patch witness. Each lifecycle transition also rewrites `.aquasynth/live-sessions/{sessionId}.cc` so clients and operators can inspect the current session truth without replaying receipts. - `cultnet-host`: starts a local CultNet host/database for AquaSynth command and receipt documents, publishes `aquasynth.cultnet_provider.v1`, and watches typed command records until the process is stopped. - `cultnet-once`, `cultnet-stream`, and `cultnet-daemon`: submit the same sample, stream, and JSON-lines command envelopes through the local CultNet database path, then wait for typed receipt records. These modes are operator edges; the database watcher is the command transport owner. Current witness roots: - `.aquasynth/compile/{receiptId}.cc` - `.aquasynth/sessions/{sessionId}.cc` - `.aquasynth/renders/{renderId}.cc` - `.aquasynth/samples/{renderId}.f32` - `.aquasynth/samples/{renderId}.wav` - `.aquasynth/streams/{streamRunId}.cc` - `.aquasynth/streams/{streamRunId}/audio-{sequence}.f32` - `.aquasynth/operator/operator-state.cc` - `.aquasynth/cultnet/aquasynth-daemon.ccmp`: local CultNet/CultCache database for command documents, provider state, and receipt documents. Example: ```powershell dotnet run --project tools\AquaSynthDaemon -- once ` --script-file patches\808\kick.aqua ` --patch-id patches.808.kick ` --faust-name patch_808_kick ` --duration 0.25 ``` The service now makes `instrument.sample` duration authoritative for the render window. Patch-estimated envelope duration remains useful for direct compiler calls, but a daemon sample request owns the number of output frames. The bounded automation stream is the first realtime-shaped CultMesh path. It uses CultMesh stream descriptors and frame handles with `CultCachePage` packet bodies. The local CultNet host now gives AquaSynth a long-lived typed command surface for `patch.compile`, `instrument.sample`, and `instrument.stream`; transport listeners delegate to `AquaSynthDaemonService` and must not become separate audio/session owners. Shared-memory rings and remote process supervision remain future transport work, not command authority. ## Forbidden Writers - Weksa does not compile Faust or own instrument controls. - Dashboard renderers do not own compiled binary lifetime or control truth. - Faust source is an emitted artifact, not the semantic patch owner. - Native host handles cannot silently override CultMesh session state. - Render samples are evidence, not patch identity.