# 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);
}
impl Drop for AudioClassificationDriver;
```
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 from a current engine run or queue-failure submission faults the driver, deactivates all work, and makes `ensure_healthy` and later `start` calls fail. `shutdown`, including shutdown on drop, stops admission and deactivates current work without joining lane threads.
`FragmentEngine::run` receives the fragment's Ogg bytes and an activity predicate that implementations must observe before producing effects. Performance: Not yet benchmarked; execution cost is implementation-defined and may scale with `ogg_bytes`.
`AudioClassificationDriver::open` constructs a driver using the supplied analyzer. Performance: Not yet benchmarked; construction performs bounded local setup without loading a fragment.
`AudioClassificationDriver::with_engine` constructs a driver using the supplied engine. Performance: Not yet benchmarked; construction performs bounded local setup without loading a fragment.
`AudioClassificationDriver::start` admits or queues one fragment. Performance: Not yet benchmarked; admission performs bounded local work and may spawn one lane.
`AudioClassificationDriver::abort` deactivates one fragment. Performance: Not yet benchmarked; work scales linearly with the number of queued fragments.
`AudioClassificationDriver::ensure_healthy` reports the current fault state. Performance: Not yet benchmarked; it performs bounded local state access.
`AudioClassificationDriver::shutdown` stops admission and deactivates work. Performance: Not yet benchmarked; work scales with active and queued fragments and does not wait for lane completion.
Dropping `AudioClassificationDriver` invokes `shutdown`. Performance: Not yet benchmarked; drop has the same work bound as `shutdown`.