Crate stratifykit_core 

Domain-agnostic distribution-control primitives: bounded top-K sampling, group-aware quota fill, and coverage classification. No knowledge of any particular record type – callers supply plain closures (bucket_key_fn, group_key_fn) to map their own domain’s rows onto the generic FeatureKey/BucketKey/GroupKey string concepts used here.

Structs

GroupAwareFillResult

Outcome of group_aware_fill: kept items (original input order) plus the diversity/quota stats a caller typically wants to report (e.g. in a run manifest).

HeapEntry

One candidate in a bounded top-K stream. key carries every tie-break the equivalent full-materialize-then-sort_by code would apply; index is always the final tiebreak layer, reproducing sort_by’s stability – which a heap has no notion of on its own, since two records can otherwise agree on every field key compares. record is left generic (R) rather than fixed to any one domain’s row type, so this heap is reusable outside shogiesa.

QuotaSpec

A hand-editable quota file: observed (or desired) per-bucket target counts. quotas’ keys are caller-defined bucket-key strings, reused verbatim (not trimmed/reparsed) so there is never a second representation of “what bucket is this” that could drift from the first. by makes the file self-describing: a caller reconstructs its own bucketing dimensions from this field alone, never from separately-passed flags, so an apply-time mismatch between flags and file is structurally impossible.

TotalF32

f32 wrapper with a total order (via total_cmp) for callers ranking by a plain fraction (e.g. a 0..=1 quality score) that is never NaN in practice but has no Ord impl of its own.

Enums

BucketStatus

Coverage classification for one bucket in an enumerated bucket space – e.g. “every phase x side x eval-bucket combination”, where a combination nobody observed still needs a verdict (Missing), not just silent absence from a tally.

Functions

bucket_floor

floor(value / bucket_size) * bucket_size. bucket_size == 0 is a caller error, expected to be checked and rejected at the caller’s entry point, not deep inside this pure helper.

classify_bucket

Ratio-to-mean classification: count == 0 is always Missing; otherwise Under/Over when count falls outside [under_ratio, over_ratio] * mean, else Ok.

group_aware_fill

Group-aware bounded-heap quota fill: streams items once, assigns each a bucket via bucket_key_fn, and – among items whose bucket has a quota in quotas – fills that bucket’s quota preferring group diversity (group_key_fn) over first-come-first-served.

mean_of

push_bounded

Keeps the count smallest HeapEntrys seen so far – the standard bounded-heap top-K algorithm: push while under capacity, otherwise evict the current worst-kept entry if entry ranks ahead of it. Provably identical final set (and, via BinaryHeap::into_sorted_vec, identical order) to “collect everything, sort ascending by the same key, truncate” – at O(count) memory instead of O(n).

reservoir_sample

Bounded top-K reservoir sample: keeps count items keyed by seeded_hash(seed, key_fn(item)), restoring original input order in the result (an A-Res-style weighted reservoir sample, streamed at O(count) memory instead of materializing the whole input).

seeded_hash

Deterministic hash of (seed, s) – the tie-breaking/spreading mechanism bounded top-K sampling uses to pick “which items” deterministically. Each part is hashed with an explicit length prefix so a naive concatenation can’t collide across the seed/string boundary.

Type Aliases

BucketKey

A composite bucket identifier a caller’s sampling/coverage quota is keyed on.

FeatureKey

A single dimension’s value for one record (e.g. a phase name, a side name) – callers compose these into a BucketKey however their domain defines “bucket”.

GroupKey

Identifies which correlated group (e.g. one source game) a record belongs to, for group-aware sampling that keeps one group from consuming an entire bucket’s quota.