feat(audio): add guest voice controls and reliable lifecycle delivery
Intrepid/Prometeu/Runtime/pipeline/pr-master This commit looks good
Intrepid/Prometeu/Runtime/pipeline/pr-master This commit looks good
This commit is contained in:
+67
@@ -0,0 +1,67 @@
|
||||
---
|
||||
id: LSN-0069
|
||||
ticket: guest-audio-voice-control
|
||||
title: Audio Admission Needs a Delivery Boundary and Independent Lifecycle Control
|
||||
created: 2026-10-14
|
||||
tags: [audio, runtime, lifecycle, host]
|
||||
---
|
||||
|
||||
## Context
|
||||
|
||||
The runtime already played PCM samples on sixteen explicit voices, but the guest could not stop a loop or change an ongoing playback. Exposing four existing mixer operations also exposed a delivery problem: a full desktop ring buffer discarded commands, including a successful stop.
|
||||
|
||||
Source record: DEC-0057 was accepted from AGD-0058 and implemented through PLN-0188 in DSC-0055. The workflow records were completed and pruned after publication. The [audio peripheral specification](../../../docs/specs/runtime/05-audio-peripheral.md) is normative; this lesson explains the resulting implementation.
|
||||
|
||||
## Admission Is Not Application
|
||||
|
||||
A successful audio syscall means that a validated command was admitted into a bounded logical batch. It does not mean the callback has already mixed it or that the device has emitted sound. Keeping those events separate makes overload understandable: an invalid argument consumes no quota, a command beyond the batch quota returns an explicit status, and an accepted command cannot silently disappear because the physical device is slower.
|
||||
|
||||
The guest now has stop, volume, pan and pitch controls beside the two playback calls. All use the same quota and status-first boundary. Explicit voice selection keeps replacement simple: play A, stop, play B leaves B. Setters preserve position and do not establish defaults for a later play. The implementation keeps finite-positive pitch instead of imposing an arbitrary musical range.
|
||||
|
||||
The [driver](../../../crates/console/prometeu-drivers/src/audio.rs) stages commands, while the [transport](../../../crates/console/prometeu-drivers/src/audio/transport.rs) holds one pending frame batch. The producer waits before advancing more guest work when publication is occupied. The callback only tries to take a batch; it never waits for the producer lock. This trades occasional host-side delay for bounded memory and reliable admitted work.
|
||||
|
||||
## Logical Completion Must Match the Runtime's Existing Entry Model
|
||||
|
||||
Physical ticks are not publication boundaries. A logical frame can span multiple host ticks, and debugger stepping can emit commands before normal execution resumes. Clearing staging on every physical tick loses work and resets quota incorrectly.
|
||||
|
||||
The existing runtime completes a logical frame at explicit FRAME_SYNC or normal entry-function return. Both now publish the batch. Treating return as an abort would break return-based cartridges. The [runtime integration](../../../crates/console/prometeu-system/src/services/vm_runtime/tick.rs) also derives entry return and HALT when stepping, because the VM's budgeted runner normally derives those outcomes outside the individual instruction.
|
||||
|
||||
Faults and aborted execution cancel unpublished commands. Tests distinguish cancellation from successful implicit completion, rather than assuming every boundary looks like a FRAME_SYNC opcode.
|
||||
|
||||
## Lifecycle Cannot Compete for the Last Guest Slot
|
||||
|
||||
A paused guest might never execute another FRAME_SYNC. A reset must work even if the last frame filled its entire quota. Therefore pause state and session invalidation do not enter the ordinary guest queue.
|
||||
|
||||
Lifecycle callbacks have their own bounded staging and publication lane. A pending normal frame precedes the subsequent callback batch; callback controls are applied before resumed PCM generation. A successful lifecycle boundary flushes an interrupted frame's pending prefix before the callback commands. Without that exception, a play emitted before Home could be applied after the callback's stop on resume. The combined delivery is still bounded (1,024 frame commands plus 1,024 callback commands). Admission accounting is separate from vector length: flushing the prefix does not replenish the interrupted frame's quota, even across repeated pause/resume transitions. Absent optional hooks still complete this boundary; failed hooks cancel unpublished work. A later fault cannot roll back a prefix already published. A session generation invalidates prior commands and mixer voices together, preventing a delayed play from reviving an ended cartridge.
|
||||
|
||||
Firmware synchronizes resident identity and pause state around its tick, and the explicit reset/termination paths invalidate audio. The desktop continues servicing events during guest backpressure. Missing or failed output consumes silently, and a callback-progress watchdog prevents a stalled device from holding the publication slot forever. These foreground guarantees do not establish ownership among multiple background producers.
|
||||
|
||||
## Completion Ownership Determines Reference Lifetime
|
||||
|
||||
The driver previously mirrored voice state, retaining a sample without receiving the mixer's natural-completion signal. Exporting that mirror as is_playing would have created both an unreliable query and a retention problem.
|
||||
|
||||
The delivered driver owns staged commands rather than a second playback mirror. The mixer owns playback position and observes natural completion. A bank can be unloaded while an admitted command or voice retains its immutable sample; memory becomes reclaimable after the last owner stops, finishes, is replaced or is invalidated. Tests use weak references to verify that distinction directly.
|
||||
|
||||
The mixer also reduces large pitch steps before multiplication when wrapping loops. Merely subtracting one loop length fails when a step crosses several repetitions, and multiplying an arbitrary finite pitch by the sample-rate ratio can overflow. Short-loop tests include f64::MAX and non-unit source/output sample-rate ratios.
|
||||
|
||||
## Evidence and Limits
|
||||
|
||||
Validation was run locally on macOS/aarch64 on 2026-10-14:
|
||||
|
||||
- `cargo test --workspace --all-targets --all-features --no-fail-fast`: **1,016 passed**, zero failed, eleven ignored across 55 reported suites.
|
||||
- `cargo test -p prometeu-host-desktop-winit --lib -- --ignored`: **six passed**, including physical audio output and debugger sockets. The sandbox could not open the device; the authorized run outside it passed.
|
||||
- `cargo clippy --workspace --all-features`: passed without warnings.
|
||||
- `cargo fmt --all -- --check`, `git diff --check`, and `discussion validate`: passed.
|
||||
- Regression coverage includes staged play before Home followed by callback stop, silence after resume and later frame completion, absent optional hooks, independent callback quota, the 2,048-command combined bound, and repeated lifecycle flushes without replenishing frame admission.
|
||||
|
||||
The device smoke initialized a physical stream and observed callback consumption through play, volume/pan/pitch changes and stop. Synthetic PCM assertions establish signal values, silence, position continuity, short-loop wrapping and sample lifetime. No human listening observation or cross-device PCM identity is claimed.
|
||||
|
||||
The API is a foreground PCM control surface. It does not establish musical sequencing, FM synthesis, completion events, playback handles or authoring formats. Reference-game integration remains a separate consumer delivery and cannot be inferred from these provider tests.
|
||||
|
||||
## Reusable Checks
|
||||
|
||||
- Identify the event that admits work separately from the event that makes it observable.
|
||||
- Bound staging as well as transport, and report rejection before mutating state.
|
||||
- Keep shutdown, pause and session invalidation independent of guest saturation.
|
||||
- Place completion-sensitive state with the component that actually observes completion.
|
||||
- Test both explicit and implicit runtime boundaries, including debugger transitions.
|
||||
Reference in New Issue
Block a user