# kcode-k1-audio-classification-format 0.2.0
Pure Rust binary formats for K1 audio-classification transaction payloads and local fragment values. The crate performs no filesystem I/O, provider calls, KTO work, retry execution, persistence, classification, training, or network work.
## Public values
The crate re-exports `TxId`, `ExecutedAnalysis`, `FeatureVector24`, and `LocalSpeakerLabel`.
`AnalysisStageV1` has `GeminiTranscript`, `TerraLabels`, `GeminiFeatures`, and `TerraStructuring` stages. `QueueV1` exposes `audio_object_id`, `duration_ms`, and `filename`. `ProcessedV1`, `FailedV1`, `DiscardedV1`, `ConfirmedSpeakerV1`, and `ConfirmedV1` expose the version-one event fields. `AudioClassificationEventV1` contains `Queue`, `Processed`, `Failed`, `Discarded`, and `Confirmed` variants.
`StagedSpeakerV1` contains a speaker label, language, feature vector, and training-usability flag. `StagedFragmentV1` contains an analysis transaction ID, transcript, and ordered staged speakers. `FinalSpeakerV1` additionally contains a person ID, and `FinalFragmentV1` additionally contains a confirmation transaction ID.
## Transaction event bytes
`encode_event` and `decode_event` use envelope version byte `2`, followed by one stable tag byte and one postcard body for only the selected variant. Tags are `1` Queue, `2` Processed, `3` Failed, `4` Discarded, and `5` Confirmed. Every event `TxId` is serialized by a local Serde adapter as exactly `[u8; 12]`. The dependency does not implement Serde.
Decoding accepts only envelope version 2, a known tag, one structurally valid body, and no trailing bytes. It rejects version 1. It does not perform semantic validation of analysis values.
## Local fragment bytes
`encode_staged_fragment`, `decode_staged_fragment`, `encode_final_fragment`, and `decode_final_fragment` implement the local fragment format. Bytes 0..16 are a header: version `1`, kind `1` for staged or `2` for final, then fourteen zero reserved bytes. Bytes 16..32 contain the aligned analysis `TxIdSlot`. Bytes 32..48 are all zero for staged fragments and contain the aligned confirmation `TxIdSlot` for final fragments. The body starts at byte 48.
Every variable body length and the speaker count is an explicit little-endian `u64`. The body contains transcript UTF-8, speaker count, and ordered speakers. Each speaker contains canonical speaker-label UTF-8, final-only person-ID UTF-8 immediately after the label, language UTF-8, a length-prefixed postcard `FeatureVector24`, and one usability byte restricted to 0 or 1.
`TxIdSlot` provides `LEN` equal to 16, `PADDING_LEN` equal to 4, `new`, `txid`, `encode`, and `decode`. A slot stores the 12 transaction-ID bytes followed by four zero bytes. Decode requires exactly 16 bytes and rejects nonzero padding.
Fragment decode rejects truncation or length overflow, unsupported version or kind, nonzero header reserved bytes, nonzero slot padding, a nonzero staged confirmation slot, malformed UTF-8 or canonical speaker labels, malformed or internally trailing feature postcard bytes, invalid usability bytes, and trailing fragment bytes. It performs structural decoding only and does not call Speaker V3 semantic validators.
## Paths
`txid_path` maps a `TxId` to `<first>/<remaining15>.dat`. The complete name is exactly 16 URL-safe unpadded base64 characters using `ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_`, and the first character selects one of 64 shards. `txid_from_path` accepts exactly that two-component relative shape and reverses it. It rejects wrong component counts, names, extensions, lengths, or alphabet characters. Neither function accesses a filesystem.
## Errors, performance, and concurrency
Fallible encoding, decoding, and path operations return `FormatError`. Its variants distinguish truncation, length overflow, unsupported versions, unknown event tags, invalid event or feature bodies, invalid fragment kinds, nonzero reserved, padding, or staged-confirmation bytes, invalid slot lengths, UTF-8, speaker labels, booleans, trailing bytes, and paths.
Encoding and decoding use O(input plus output) work and O(output) encoding or decoded-value memory. Fixed slots and path conversion use bounded constant work and memory apart from the returned path allocation. Untrusted speaker counts are not used for eager allocation.
The crate is stateless. It owns no lock, queue, wait behavior, callback, or backpressure. Independent operations share no mutable state and cannot block one another except through caller-owned CPU and memory resources.