sketch_stream_stats.nx

sketch_stream_stats.nx -- streaming mean / variance / stddev / min / max. Fundamental single-pass streaming primitive. Maintains six i64 fields across the stream: count = N sum = Σ x_i sum_sq = Σ x_i² min = min over stream max = max over stream Algebraic-identity-based estimators (NOT Welford, which is f64-stable but loses precision when arithmetic is exact-integer): mean = sum / count variance = sum_sq / count - mean² (population) stddev = isqrt(variance) OVERFLOW BUDGET: For sample values bounded by |x| <= V and count N: sum: N * V — must fit i64. Safe to N * V < 2^62. sum_sq: N * V² — same constraint applied to V² instead of V. For V = 2^30 (1 billion): N up to ~2^32 (4 billion) safe for sum, but sum_sq overflows at N * 2^60 -- safe to N=4. For V = 2^20 (~1M): N up to 2^22 (~4M) safe for sum_sq. For V = 2^16 (65K): N up to 2^30 (1B) safe. Caller responsibility to size domain; nx_stats_safe_p returns 1 iff adding `value` would NOT overflow. COMPLEMENTS the sketch suite: - sketch_reservoir: arbitrary-statistic estimation via sample-based math - sketch_kll / sketch_tdigest: quantiles (median, p99) - sketch_stream_stats (here): exact-integer mean/variance over the FULL stream (no sampling, no probabilistic bounds) LOSSLESS-LANGUAGE DISCIPLINE: nx_stats_query_mean and friends return ApproxI64 with envelope_kind = NX_ENV_ABS, param_a = 0 (mean and variance are EXACT under the overflow budget), conf_ppb = 1e9.