stratifykit_core/lib.rs
1//! Domain-agnostic distribution-control primitives: bounded top-K sampling, group-aware quota
2//! fill, and coverage classification. No knowledge of any particular record type -- callers
3//! supply plain closures (`bucket_key_fn`, `group_key_fn`) to map their own domain's rows onto
4//! the generic `FeatureKey`/`BucketKey`/`GroupKey` string concepts used here.
5
6mod coverage;
7mod hash;
8mod heap;
9mod quota;
10mod sampling;
11
12pub use coverage::{BucketStatus, bucket_floor, classify_bucket, mean_of};
13pub use hash::seeded_hash;
14pub use heap::{HeapEntry, TotalF32, push_bounded};
15pub use quota::QuotaSpec;
16pub use sampling::{GroupAwareFillResult, group_aware_fill, reservoir_sample};
17
18/// A single dimension's value for one record (e.g. a phase name, a side name) -- callers compose
19/// these into a [`BucketKey`] however their domain defines "bucket".
20pub type FeatureKey = String;
21/// A composite bucket identifier a caller's sampling/coverage quota is keyed on.
22pub type BucketKey = String;
23/// Identifies which correlated group (e.g. one source game) a record belongs to, for
24/// group-aware sampling that keeps one group from consuming an entire bucket's quota.
25pub type GroupKey = String;
26
27#[cfg(test)]
28mod tests {
29 /// This crate's whole reason to exist is being usable by a future non-shogi consumer
30 /// (masstrust/quietset-style products, per its README) -- a `shogiesa-*` dependency creeping
31 /// into `Cargo.toml` would silently break that promise. `include_str!` reads the file at
32 /// compile time, so this fails the moment such a dependency is added, not just when someone
33 /// remembers to check.
34 #[test]
35 fn cargo_toml_has_no_shogiesa_dependency() {
36 let manifest = include_str!("../Cargo.toml");
37 assert!(
38 !manifest.contains("shogiesa"),
39 "stratifykit-core must stay zero-shogi-vocabulary; found a `shogiesa` reference in Cargo.toml"
40 );
41 }
42}