kcode-k1-audio-classification-driver 0.2.2

Bounded isolated execution driver for K1 audio classification
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53

# Consumer contract

Runs audio-classification work in isolated lanes for Objects identified by `FragmentId`.

## Public API

```rust
pub use kcode_k1_audio_fragment_runner::FragmentId;
pub const MAX_ACTIVE_ATTEMPTS: usize = 8;
pub type EngineFuture<'a> = Pin<Box<dyn Future<Output = Result<(), String>> + 'a>>;

pub trait FragmentEngine: Send + Sync + 'static {
    fn run<'a>(
        &'a self, fragment_id: FragmentId, ogg_bytes: &'a [u8],
        is_active: &'a (dyn Fn() -> bool + Send + Sync),
    ) -> EngineFuture<'a>;
}

#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum StartOutcome {
    Started,
    Pending,
    AlreadyActive,
}

pub struct AudioClassificationDriver;
impl AudioClassificationDriver {
    pub fn open(peering: Arc<K1Peering>, objects: Arc<K1Objects>, analyzer: Analyzer) -> Self;
    pub fn with_engine(
        peering: Arc<K1Peering>, objects: Arc<K1Objects>, engine: Arc<dyn FragmentEngine>,
    ) -> Self;
    pub fn start(&self, id: FragmentId) -> Result<StartOutcome, String>;
    pub fn abort(&self, id: FragmentId);
    pub fn ensure_healthy(&self) -> Result<(), String>;
    pub fn shutdown(&self);
}
```

An attempt loads the identified Object, requires media type `audio/ogg`, and records a queue-stage failure when the Object is absent, has another media type, or cannot be loaded while the attempt is active.

`start` returns `Started` when a lane is launched, `Pending` when the eight lanes are occupied and the fragment is queued FIFO, and `AlreadyActive` when that fragment is already running or queued. `abort` removes queued state or deactivates a running generation; a running lane remains occupied until its work returns, and errors from an aborted or replaced generation are ignored.

An error or ordinary unwind panic from a current engine run, or a queue-failure submission error, faults the driver, deactivates all work, and makes `ensure_healthy` and later `start` calls fail. Panics from aborted or replaced generations only release their lanes. Panic payloads are not exposed, and process aborts, OOM, and `panic=abort` remain outside this boundary.

`shutdown`, including shutdown on drop, stops admission and deactivates current work without joining lane threads.

Compatibility: version 0.2.2 requires runner `0.4.2` and audio-fragment-transactions `0.5.2` exactly. It requires speaker-v3-analysis `0.3.0` exactly with default features disabled and only `adapter-providers` enabled. The driver accepts an existing `Analyzer` and constructs no provider.

Performance: Not yet benchmarked. `FragmentEngine::run` cost is implementation-defined and may scale with `ogg_bytes`; `open` and `with_engine` perform bounded local setup without loading a fragment.

`start` performs bounded local admission and may spawn one lane; `abort` scales linearly with queued fragments; `ensure_healthy` performs bounded local state access.

`shutdown` and drop scale with active and queued fragments and do not wait for lane completion.