AquaSynth/docs/verse-service-contract.md

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:

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.