# kcode-speaker-types
Validated shared values for speaker-classification package boundaries.
## API
- `FEATURE_COUNT: usize = 24`.
- `Key::parse(&str) -> Result<Key, TypeError>` accepts 1–128 ASCII bytes containing only letters, digits, `.`, `_`, `-`, `/`, or `:`. `Key` has a validated private representation, deterministic ordering and hashing, Serde support, and `AsRef<str>`.
- `ObjectId::parse(&str) -> Result<ObjectId, TypeError>` accepts exactly eight base64url characters (`A-Z`, `a-z`, `0-9`, `-`, `_`). Pending and other locator forms are invalid. `ObjectId` has a validated private representation, deterministic ordering and hashing, Serde support, and `AsRef<str>`.
- `FeatureVector::new([u8; FEATURE_COUNT]) -> Result<FeatureVector, TypeError>` accepts only integer values `0..=100`. It supports Serde and exposes its array through `AsRef<[u8; FEATURE_COUNT]>`. Its frozen field order is:
1. `filler_form_preference`
2. `syntactic_complexity`
3. `clause_completion_habit`
4. `declarative_terminal_rise`
5. `pragmatic_hedging`
6. `speech_burst_contrast`
7. `vocalized_hesitation_prominence`
8. `pitch_expressiveness`
9. `lexical_formality`
10. `vocal_gender_presentation`
11. `perceived_vocal_age_percentile`
12. `pitch_level_percentile`
13. `vocal_weight`
14. `accent_markedness`
15. `resonance_brightness`
16. `articulatory_precision`
17. `rhoticity_level`
18. `loudness_dynamic_range`
19. `articulation_tempo`
20. `vocal_fry`
21. `modal_breathiness`
22. `modal_roughness`
23. `vocal_attack`
24. `sibilant_sharpness`
- `FeatureMask::from_bits(u64) -> Result<FeatureMask, TypeError>` is const-capable, requires at least one set bit, and permits only bits 0–23. It supports Serde, and `u64::from(mask)` returns the bits.
- `RecordingKind` has `VoiceNote`, `Meeting`, `Call`, and `Other` variants.
- `SegmentRef` has exactly these public fields: `source_object: ObjectId`, `clip_object: ObjectId`, `ordinal: u16`, `segment_count: u16`, `start_ms: u64`, `end_ms: u64`, and `policy: Key`. `validate()` requires `ordinal < segment_count` and `start_ms < end_ms`.
- `LabeledSample` has exactly these public fields: `sample_id: Key`, `attempt_id: Key`, `speaker_id: Key`, `cohort_id: Key`, `group_id: Key`, `clip_object: ObjectId`, `primary_language: Key`, `recording_kind: RecordingKind`, `usable_speech_ms: u32`, `recording_quality: u8`, and `features: FeatureVector`.
`RecordingKind`, `SegmentRef`, and `LabeledSample` support Serde serialization and deserialization. Deserializing a validated value applies the same checks as its constructor. `SegmentRef` fields remain directly editable, so callers must invoke `validate` after construction or mutation and before use at a receiving boundary. Cross-record consistency and maximum-duration policy require external context and are enforced by register or system boundaries, not this library.
Errors are returned as `TypeError`. This library performs no I/O, parsing of external formats, persistence, statistics, provider work, replay, adoption, or deployment.