kcode-k1-audio-classification 0.5.4

Durable K1 audio classification facade
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
54
55
56

# K1 audio classification

Durable facade for the exact KTO subsystem `audio-classification`. It exposes audio intake and fragment operations while delegating projection, replay, recovery, provider execution, health, and shutdown to the coordinator. It does not expose providers, deployment, networking, or service integration.

## Public API

```rust
pub use kcode_k1_audio_classification_projection::{
    ExecutedAnalysis, FragmentId, FragmentStageV1, FragmentStatus, LlmJobState,
    LlmJobStatus, OverallState, SpeakerLabelV1, StageState, StageStatus,
};
pub use kcode_k1_audio_fragment_transactions::PersonId;

pub struct AudioClassification;

impl AudioClassification {
    pub fn open(
        root: &Path,
        ordering: Arc<K1TxnOrdering>,
        peering: Arc<K1Peering>,
        objects: Arc<K1Objects>,
        analyzer: Analyzer,
    ) -> Result<Self, String>;
    pub fn submit(&self, ogg_bytes: &[u8]) -> Result<FragmentId, String>;
    pub fn status(&self, fragment_id: FragmentId) -> Result<Option<FragmentStatus>, String>;
    pub fn retry(&self, fragment_id: FragmentId) -> Result<(), String>;
    pub fn discard(&self, fragment_id: FragmentId) -> Result<(), String>;
    pub fn submit_labels(
        &self,
        fragment_id: FragmentId,
        labels: Vec<SpeakerLabelV1>,
    ) -> Result<(), String>;
}
```

The re-exported declarations and implemented traits are defined by their owning contracts. `FragmentId` is the immutable audio Object transaction ID. `PersonId` is the exact identity type carried by `SpeakerLabelV1`, whose `person_id` is `Option<PersonId>`: `Some` supplies a known identity and `None` explicitly means Unknown. Status includes overall state, all six exact stage statuses, retained per-attempt LLM jobs, interim transaction ID and analysis, confirmed labels and deterministic final transcript, and the oldest 5,000 canonical errors plus truncation state.

`submit` strictly validates one complete positive-duration non-chained Ogg Opus fragment of at most 150 seconds, stores its exact bytes as an `audio/ogg` Object, and queues it. A Queue failure after Object persistence can leave a harmless orphan Object. `retry` accepts only Failed work, reserves concurrent retry admission, and durably submits exactly one existing Queue event; its callback performs the Failed-to-Queued transition and starts the new generation. `discard` rejects unknown fragments, is idempotent in Discarded state, admits at most one simultaneous discard transaction, and permanently suppresses late results. `submit_labels` accepts only Completed work, admits at most one simultaneous label transaction, and requires exactly one shared typed label for every interim speaker in interim order. It forwards known and Unknown identities unchanged and performs no Persons lookup, discovery, canonicalization, or authority decision.

The facade accepts an existing `Analyzer` and constructs no providers.

## Persistence and lifecycle

Opening delegates registration, replay, projection recovery, interrupted-attempt failure, and queued-work startup to the coordinator. Replay never starts provider work. Recoverable projection invalidity rebuilds from genesis. Projection, callback-effect, driver, reorganization, and ambiguously committed submission failures fault the facade and require reopen; ambiguous submissions are never retried.

Up to eight fragment attempts execute in independent lanes with FIFO overflow. A blocked attempt does not delay unrelated facade operations or available lanes. Drop delegates bounded shutdown and does not wait for provider return. Generation activity suppresses delivery after abort, replacement, shutdown, or drop.

Facade locks protect only short operation reservations and span no external call. Projection serialization is limited to the coordinator's bounded SQLite owner operation. KTO, Peering, Objects, filesystem, provider, and SQLite latency has no finite bound. Encoding and projection work are linear in addressed bounded values, submission is linear in audio bytes plus dependency persistence, and startup replay is linear in matching canonical history.

## Provider-free acceptance

The test-only exact dependency `kcode-k1-audio-classification-test-adapter = 0.2.1` runs the complete provider-free facade conformance suite through ordinary `submit`, `status`, `retry`, `discard`, and `submit_labels` methods. Its cycle-free bridge builds the facade from the supplied coordinator, Peering, and Objects instances, uses the coordinator test hook only for ordered error injection, and covers typed known and Unknown identities, final transcript, retry, discard, restart, rebuild, isolation, and errors without changing production behavior.

## Compatibility

Release 0.5.4 preserves the public API, source behavior, persisted and wire schemas, status and error propagation, retry, discard, label, scheduling, and eight-lane concurrency contracts of 0.5.3. It exact-pins audio-fragment-transactions 0.5.2, projection 0.4.2, coordinator 0.2.3, format 0.6.1, Speaker V3 analysis 0.3.0, and the provider-free test adapter 0.2.1 for the Audio Codex-adapter cutover; audio-fragment-submit remains 0.4.0. The production analysis edge disables default features and enables only `adapter-providers`; it does not select the analysis `providers` feature or `kcode-codex-terra`. The coordinator supplies its required driver closure. The subsystem identity remains exactly `audio-classification`. This facade uses only event envelope version 5, local fragment format version 2, and projection schema version 2, with no migration or legacy path.