sketch_types.nx source
↩ module page · 86 lines · 3631 B
1// sketch_types.nx -- L-4 typed envelope scaffold for streaming sketches.
2//
3// Lossless-language discipline (per nishi-engine docs 17 + 20):
4// every approximate primitive in the substrate ships its loss
5// NAMED, BOUNDED, and QUERYABLE. Sketches are bounded-loss, not
6// silent-loss.
7//
8// Mirrors nishi-engine/packages/core-sketch/src/types.ts so the
9// TS reference layer and the NishiLang sovereign sibling carry
10// identical envelope semantics.
11//
12// All-i64 representation (no f64 source-level types) for C-anchor
13// compatibility. Floating-point quantities (stddev, eps, conf)
14// are stored as fixed-point integers scaled by 10^9 (parts-per-
15// billion). Caller decodes by dividing by 1_000_000_000.
16// stddev_rel = 0.0162 -> stddev_rel_ppb = 16_200_000
17// conf = 0.6827 -> conf_ppb = 682_700_000
18
19import "syscalls.nx"
20
21// === MaturityClass =================================================
22//
23// Per nishi-engine doc 16 substrate-types-roadmap. Declares whether
24// a primitive is paper-only, software-emulated reference, or native
25// production. Substrate refuses MaturityClass<Theoretical> in
26// production-graded compositions.
27
28const NX_MATURITY_THEORETICAL: i64 = 0
29const NX_MATURITY_REFERENCE_IMPL: i64 = 1
30const NX_MATURITY_PRODUCTION: i64 = 2
31
32// === AdversarialSafety =============================================
33//
34// Per core-sketch/types.ts. Honest-only sketches MUST NOT be
35// substituted for Adversarial-required sketches at composition
36// boundaries.
37
38const NX_ADV_HONEST: i64 = 0
39const NX_ADV_ADVERSARIAL: i64 = 1
40
41// === ErrorEnvelope kinds ===========================================
42//
43// Discriminator for the envelope's parameter interpretation:
44// ENV_REL_STDDEV: cardinality / mean -- error as fraction of value
45// (stddev / value). param_a holds stddev_rel * 1e9.
46// ENV_RANK_ERROR: quantile / rank-class -- error as fraction of N
47// (max |rank_est - rank_true| / N). param_a holds
48// eps * 1e9.
49// ENV_ABS: frequency / count -- error in same units as value.
50// param_a holds the additive bound.
51
52const NX_ENV_REL_STDDEV: i64 = 0
53const NX_ENV_RANK_ERROR: i64 = 1
54const NX_ENV_ABS: i64 = 2
55const NX_ENV_REL_RANK_ERROR: i64 = 3 // |rank_est - rank_true| <= eps * min(rank, N-rank)
56 // ReqSketch family: tail-multiplicative,
57 // strictly stronger than RANK_ERROR for tail queries
58
59// === Approximate<i64> typed envelope ==============================
60//
61// 48 bytes = 6 i64 fields. Carries a value + its declared loss.
62// Every sketch's query() function returns this struct (allocated
63// by callee via sys_mmap, owned by caller).
64
65struct ApproxI64 {
66 value: i64,
67 envelope_kind: i64, // 0=rel_stddev, 1=rank_error, 2=abs
68 param_a: i64, // primary envelope parameter (× 1e9 if fp)
69 conf_ppb: i64, // confidence × 1e9 (e.g., 682700000 = 0.6827)
70 maturity: i64, // NX_MATURITY_*
71 adv_safety: i64, // NX_ADV_*
72}
73
74// Allocate + populate.
75func nx_approx_new(value: i64, envelope_kind: i64, param_a: i64,
76 conf_ppb: i64, maturity: i64, adv_safety: i64) -> *ApproxI64 {
77 let raw: *u8 = sys_mmap(48)
78 let a: *ApproxI64 = raw as *ApproxI64
79 a.value = value
80 a.envelope_kind = envelope_kind
81 a.param_a = param_a
82 a.conf_ppb = conf_ppb
83 a.maturity = maturity
84 a.adv_safety = adv_safety
85 return a
86}