8a65f5876a
Per thing2:ruling:eve-dashboards-quarantined. Removes cultMeshSurfaceKeys, the eve witness family and the eve surface schema from the exporter and fixture; the contract names the quarantine. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
166 lines
7.7 KiB
Markdown
166 lines
7.7 KiB
Markdown
# 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.
|