kcode-speaker-system 0.1.0

# kcode-speaker-system 0.1.0

Thin deterministic composition facade for the frozen 24-field speaker-classifier packages.

## Managed dependencies

- `kcode-speaker-types = "=0.2.0"`
- `kcode-speaker-extract = "=0.2.0"`
- `kcode-speaker-store = "=0.2.0"`
- `kcode-speaker-dataset = "=0.2.0"`
- `kcode-speaker-model = "=0.2.0"`
- `kcode-speaker-eval = "=0.1.0"`

The facade adds no feature extraction, persistence, dataset, model, or evaluation implementation of its own.

## Public API

The facade re-exports the settled shared feature, identifier, extraction-contract, store-snapshot, dataset, model, and evaluation types. Facade errors are returned as `SystemError`. Successful commits return `CommitReceipt { revision, applied }`.

### Extraction contract

```rust
pub fn cohort_id() -> &'static Key;
pub fn extraction_contract() -> &'static ExtractionContract;
pub fn normalization_prompt(raw_analysis: &str) -> Result<String, SystemError>;
```

`cohort_id` is exactly the normalized schema key exposed by extract 0.2.0. The provider prompt and normalizer are delegated without replacement, extension, or duplicated parsing.

### Store composition

```rust
pub struct SegmentBinding {
    pub event_id: Key,
    pub clip_object: ObjectId,
}

pub struct SourceRegistration {
    pub source_object: ObjectId,
    pub source_duration_ms: u64,
    pub group_id: Key,
    pub recording_kind: RecordingKind,
    pub segments: Vec<SegmentBinding>,
}

pub struct NormalizedAttempt<'a> {
    pub event_id: Key,
    pub attempt_id: Key,
    pub cohort_id: Key,
    pub source_object: ObjectId,
    pub clip_object: ObjectId,
    pub segment_ordinal: u16,
    pub provider_result_object: ObjectId,
    pub recording_quality: Option<u8>,
    pub normalized_response: &'a str,
}

pub struct AttemptSelectionRequest {
    pub event_id: Key,
    pub attempt_id: Key,
    pub cohort_id: Key,
    pub clip_object: ObjectId,
    pub reason: String,
}

pub struct SampleStateRequest {
    pub event_id: Key,
    pub sample_id: Key,
    pub state: SampleState,
    pub reason: String,
}

pub struct SpeakerSystem { /* private store */ }

pub fn open(path: impl AsRef<std::path::Path>) -> Result<SpeakerSystem, SystemError>;

impl SpeakerSystem {
    pub fn register_source(
        &self,
        request: SourceRegistration,
    ) -> Result<CommitReceipt, SystemError>;

    pub fn record_normalized_attempt(
        &self,
        request: NormalizedAttempt<'_>,
    ) -> Result<CommitReceipt, SystemError>;

    pub fn select_attempt(
        &self,
        request: AttemptSelectionRequest,
    ) -> Result<CommitReceipt, SystemError>;

    pub fn change_sample_state(
        &self,
        request: SampleStateRequest,
    ) -> Result<CommitReceipt, SystemError>;

    pub fn attempt(
        &self,
        attempt_id: &Key,
    ) -> Result<Option<AttemptSnapshot>, SystemError>;

    pub fn dataset(&self, cohort_id: &Key) -> Result<Dataset, SystemError>;
}
```

Source registration delegates segment-range planning to extract and event commits to store. The caller explicitly supplies source and clip object IDs, event IDs, leakage group, and recording kind. Clip bindings must exactly match the deterministic plan.

Normalized attempts are accepted only for the frozen normalized cohort and a registered matching source, clip, and ordinal. Complete and additional speakers retain parser-validated ordinals. Complete profiles map field-for-field to store speakers; additional speakers remain attempt evidence and never receive sample IDs.

`recording_quality` is caller or host metadata. It is required for scored outcomes, must be at most 100, and is forbidden for unscorable outcomes so it cannot be silently discarded or invented. The canonical provider-result object remains explicit.

Selection and sample-state changes delegate attempt matching, sample ownership, projection, and caller labels to store. Dataset construction reads active and repeatability projections at one revision and delegates canonical validation to dataset.

### Dataset, model, and evaluation

```rust
pub fn open_set_folds(
    dataset: &Dataset,
    config: FoldConfig,
) -> Result<Vec<OpenSetFold>, SystemError>;

pub fn repeatability_groups(dataset: &Dataset) -> Vec<RepeatabilityGroup>;

pub fn fit(
    dataset: &Dataset,
    cohort_id: &Key,
    config: ModelConfig,
) -> Result<ModelSnapshot, SystemError>;

pub fn identify(
    model: &ModelSnapshot,
    cohort_id: &Key,
    features: &FeatureVector,
) -> Result<Identification, SystemError>;

pub fn snapshot_bytes(model: &ModelSnapshot) -> Result<Vec<u8>, SystemError>;
pub fn snapshot_from_bytes(bytes: &[u8]) -> Result<ModelSnapshot, SystemError>;
pub fn evaluate(plan: EvaluationPlan<'_>) -> Result<EvaluationResult, SystemError>;
```

Fold and repeatability construction delegate to dataset. Fitting, identification, and snapshot bytes delegate to model. Offline evaluation delegates to eval. Facade cohort boundaries require the exact normalized contract key. The shared `FeatureVector` and a compile-time assertion bind the feature count to 24.

## Boundaries and lifecycle

This package performs no provider calls, audio-byte handling, real-inventory construction, replay, artifact activation, host integration, publication, deployment, or lifecycle transition. It invents no provider-absent value. Additional and insufficient-evidence speakers are retained only in stored attempts and never become training samples.

The stop point is checked, source-saved code only. Publication, selection, adoption, integration, deployment, attempted operation, and live operation remain separate and are not claimed.