code wiki / _hdl_build / nx_deltaclass.nx
nx_deltaclass.nx source
↩ module page · 299 lines · 13007 B
1// nx_deltaclass.nx -- CLI over nx_deltaclass_lib. Answers, at any time and from the LIVE ledger:
2// did the headline move because we DELIVERED, because the REQUIREMENT moved, or because we thrashed?
3// All logic lives in nx_deltaclass_lib.nx, which the GATE imports too, so what ships is what is graded.
4//
5// VERBS
6// ledger <path> first and last sum-bearing samples in the file
7// window <path> <n> the last <n> sum-bearing samples
8// selftest
9// Beat lines (src=beat) carry NO sums and are SKIPPED -- counting them as samples would manufacture
10// fake idle runs and drown the real signal.
11// expect_exit: 0 license_tier: ORIGINAL No hw writes (Rule 26).
12import "nx_deltaclass_lib.nx"
13const DL_MAGIC_1785608007: i64 = 1785608007
14
15const DL_NL: i64 = 10
16const DL_MINUS: i64 = 45
17const DL_D0: i64 = 48
18const DL_D9: i64 = 57
19const DL_SCRATCH: i64 = 28
20
21func dw(s: *u8) -> i64 { var n: i64 = 0; while s[n] != (0 as u8) { n = n + 1 } sys_write(1, s, n); return 0 }
22func dn(v: i64) -> i64 {
23 let b: *u8 = sys_mmap(DL_SCRATCH)
24 let t: *u8 = sys_mmap(DL_SCRATCH)
25 var m: i64 = v
26 if m < 0 { m = 0 - m; sys_write(1, "-" as *u8, 1) }
27 var k: i64 = 0
28 if m == 0 { t[0] = DL_D0 as u8; k = 1 }
29 while m > 0 { t[k] = (DL_D0 + (m % 10)) as u8; m = m / 10; k = k + 1 }
30 var i: i64 = 0
31 while i < k { b[i] = t[k-1-i]; i = i + 1 }
32 sys_write(1, b, k)
33 sys_munmap(b, DL_SCRATCH)
34 sys_munmap(t, DL_SCRATCH)
35 return 0
36}
37// ONLY for quantities where -1 cannot be a legitimate value (an eta is a count >= 0, so -1
38// unambiguously means "no finite answer").
39func dnu(v: i64) -> i64 {
40 if v == dc_unmeasured() { dw("UNMEASURED" as *u8); return 0 }
41 if v > 0 { dw("+" as *u8) }
42 dn(v)
43 return 0
44}
45// SIGNED DELTA printer. Deltas and permil effects are legitimately -1, which COLLIDES with the
46// unmeasured sentinel. Caught on the live ledger: a real delivery delta of -1 (52 -> 51) printed as
47// UNMEASURED, hiding a regression behind a word meaning "no data".
48// LAW: A SENTINEL INSIDE THE VALUE RANGE IT GUARDS IS NOT A SENTINEL. The denominators are validated
49// ONCE before this block, so every value reaching here IS measured and always prints as a number.
50func dsn(v: i64) -> i64 {
51 if v > 0 { dw("+" as *u8) }
52 dn(v)
53 return 0
54}
55func dstreq(a: *u8, b: *u8) -> i64 {
56 var i: i64 = 0
57 while a[i] != (0 as u8) { if a[i] != b[i] { return 0 } i = i + 1 }
58 if b[i] != (0 as u8) { return 0 }
59 return 1
60}
61func dl_klen(k: *u8) -> i64 { var n: i64 = 0; while k[n] != (0 as u8) { n = n + 1 } return n }
62func dl_key_at(b: *u8, i: i64, k: *u8) -> i64 {
63 var j: i64 = 0
64 while k[j] != (0 as u8) {
65 if b[i + j] != k[j] { return 0 }
66 j = j + 1
67 }
68 return 1
69}
70func dl_num_at(b: *u8, i: i64, lim: i64) -> i64 {
71 var v: i64 = 0
72 var p: i64 = i
73 var neg: i64 = 0
74 if p < lim { if b[p] == (DL_MINUS as u8) { neg = 1; p = p + 1 } }
75 var go: i64 = 1
76 var any: i64 = 0
77 while go == 1 {
78 if p >= lim { go = 0 }
79 if go == 1 {
80 let c: i64 = (b[p] as i64) & 255
81 if c < DL_D0 { go = 0 }
82 if c > DL_D9 { go = 0 }
83 if go == 1 { v = v * 10 + (c - DL_D0); p = p + 1; any = 1 }
84 }
85 }
86 if any == 0 { return dc_unmeasured() }
87 if neg == 1 { return 0 - v }
88 return v
89}
90// value of key within [ls,le); unmeasured when the key is absent -- an ABSENT field must not read as 0
91func dl_val(b: *u8, ls: i64, le: i64, k: *u8) -> i64 {
92 let kl: i64 = dl_klen(k)
93 var i: i64 = ls
94 while i + kl <= le {
95 if dl_key_at(b, i, k) == 1 { return dl_num_at(b, i + kl, le) }
96 i = i + 1
97 }
98 return dc_unmeasured()
99}
100
101func dl_scope_name(c: i64) -> i64 {
102 if c == DCS_ADMIT { dw("ADMIT (new territory scoped in)" as *u8); return 0 }
103 if c == DCS_RAISE { dw("RAISE (same territory, higher target)" as *u8); return 0 }
104 if c == DCS_LOWER { dw("LOWER (requirements cut -- progress can be faked here)" as *u8); return 0 }
105 dw("FLAT" as *u8)
106 return 0
107}
108func dl_verdict_name(v: i64) -> i64 {
109 if v == DCV_CONVERGING { dw("CONVERGING" as *u8); return 0 }
110 if v == DCV_SCOPE_BOUND { dw("SCOPE-BOUND" as *u8); return 0 }
111 if v == DCV_DIVERGING { dw("DIVERGING" as *u8); return 0 }
112 if v == DCV_THRASH { dw("THRASH" as *u8); return 0 }
113 if v == DCV_STALLED { dw("STALLED" as *u8); return 0 }
114 if v == DCV_REGRESSION { dw("REGRESSION" as *u8); return 0 }
115 dw("UNMEASURED" as *u8)
116 return 0
117}
118func dl_advice(v: i64) -> i64 {
119 if v == DCV_DIVERGING { dw(" the bar is growing faster than we close it: there is NO eta at any effort level.\n ENDING THIS MARATHON IS A SCOPE DECISION, not more hours.\n" as *u8); return 0 }
120 if v == DCV_SCOPE_BOUND { dw(" the requirement move dominates delivery. The run ends when the bar stops moving -- a DECISION.\n" as *u8); return 0 }
121 if v == DCV_CONVERGING { dw(" delivery outruns the bar: the eta above is the end of this marathon.\n" as *u8); return 0 }
122 if v == DCV_THRASH { dw(" endpoints equal after real in-window movement: this is CHURN. Stop and re-scope.\n" as *u8); return 0 }
123 if v == DCV_STALLED { dw(" neither the bar nor delivery moved. Nothing is being bought here.\n" as *u8); return 0 }
124 if v == DCV_REGRESSION { dw(" the bar held still and delivery WENT BACKWARDS. This is lost ground, not a pause:\n find what was un-done before adding anything new.\n" as *u8); return 0 }
125 return 0
126}
127
128// tail==0 -> whole file; tail>0 -> last <tail> sum-bearing samples
129func dl_report(path: *u8, tail: i64) -> i64 {
130 let lnb: *i64 = sys_mmap(8) as *i64
131 let buf: *u8 = sys_read_file(path, lnb)
132 let n: i64 = lnb[0]
133 if n <= 0 {
134 dw("NX-DELTACLASS ABSENT: cannot read " as *u8); dw(path); dw("\n" as *u8)
135 dw("verdict=RED (measured NOTHING -- an empty scan is not a clean bill of health)\n" as *u8)
136 return 3
137 }
138 // pass 1: count sum-bearing samples
139 var total: i64 = 0
140 var i: i64 = 0
141 var ls: i64 = 0
142 while i <= n {
143 var end: i64 = 0
144 if i == n { end = 1 }
145 if end == 0 { if buf[i] == (DL_NL as u8) { end = 1 } }
146 if end == 1 {
147 if dl_val(buf, ls, i, "sum_cur=" as *u8) != dc_unmeasured() { total = total + 1 }
148 ls = i + 1
149 }
150 i = i + 1
151 }
152 if total < 2 {
153 dw("NX-DELTACLASS: only " as *u8); dn(total)
154 dw(" sum-bearing sample(s) in " as *u8); dw(path)
155 dw(" -- a delta needs two.\nverdict=RED (insufficient samples; NOT a pass)\n" as *u8)
156 return 4
157 }
158 var start_idx: i64 = 0
159 if tail > 0 { if tail < total { start_idx = total - tail } }
160
161 // pass 2: pull the endpoints and detect real in-window movement
162 var seen: i64 = 0
163 var fc: i64 = 0
164 var fb: i64 = 0
165 var fd: i64 = 0
166 var fe: i64 = 0
167 var lc: i64 = 0
168 var lb: i64 = 0
169 var ld: i64 = 0
170 var le2: i64 = 0
171 var mn: i64 = 0
172 var mx: i64 = 0
173 var got: i64 = 0
174 i = 0
175 ls = 0
176 while i <= n {
177 var end: i64 = 0
178 if i == n { end = 1 }
179 if end == 0 { if buf[i] == (DL_NL as u8) { end = 1 } }
180 if end == 1 {
181 let cur: i64 = dl_val(buf, ls, i, "sum_cur=" as *u8)
182 if cur != dc_unmeasured() {
183 if seen >= start_idx {
184 let bar: i64 = dl_val(buf, ls, i, "sum_bar=" as *u8)
185 let dom: i64 = dl_val(buf, ls, i, "domains=" as *u8)
186 let ep: i64 = dl_val(buf, ls, i, "epoch=" as *u8)
187 if got == 0 { fc = cur; fb = bar; fd = dom; fe = ep; mn = cur; mx = cur; got = 1 }
188 lc = cur; lb = bar; ld = dom; le2 = ep
189 if cur < mn { mn = cur }
190 if cur > mx { mx = cur }
191 }
192 seen = seen + 1
193 }
194 ls = i + 1
195 }
196 i = i + 1
197 }
198 // real movement that netted out == churn, as distinct from a flat line
199 var moved: i64 = 0
200 if mx > mn { moved = 1 }
201
202 dw("=== NX-DELTACLASS -- why the headline moved ===\nsource=" as *u8); dw(path)
203 dw(" samples=" as *u8); dn(total)
204 dw(" window=" as *u8); dn(total - start_idx); dw("\n" as *u8)
205 dw(" from epoch=" as *u8); dn(fe); dw(" domains=" as *u8); dn(fd)
206 dw(" cur=" as *u8); dn(fc); dw(" bar=" as *u8); dn(fb)
207 dw(" -> " as *u8); dn(dc_permil(fc, fb)); dw(" permil\n" as *u8)
208 dw(" to epoch=" as *u8); dn(le2); dw(" domains=" as *u8); dn(ld)
209 dw(" cur=" as *u8); dn(lc); dw(" bar=" as *u8); dn(lb)
210 dw(" -> " as *u8); dn(dc_permil(lc, lb)); dw(" permil\n\n" as *u8)
211
212 // VALIDATE THE DENOMINATORS ONCE, HERE. Downstream every effect is a real number, so the
213 // signed printer can never be ambiguous. Refusing early beats printing a decomposition of
214 // nothing (an unmeasurable window is not a zero-change window).
215 if fb <= 0 {
216 dw("ATTRIBUTION UNMEASURED: the opening bar is " as *u8); dn(fb)
217 dw(" -- a ratio with no denominator cannot be decomposed.\nverdict=RED\n" as *u8)
218 return 5
219 }
220 if lb <= 0 {
221 dw("ATTRIBUTION UNMEASURED: the closing bar is " as *u8); dn(lb)
222 dw(" -- a ratio with no denominator cannot be decomposed.\nverdict=RED\n" as *u8)
223 return 5
224 }
225 let ex: i64 = dc_exec_effect(fc, lc, fb)
226 let sc: i64 = dc_scope_effect(lc, fb, lb)
227 let tt: i64 = dc_total(fc, fb, lc, lb)
228 let rs: i64 = dc_residual(fc, fb, lc, lb)
229 dw("ATTRIBUTION (components computed INDEPENDENTLY; residual printed, never derived away)\n" as *u8)
230 dw(" execution effect " as *u8); dsn(ex); dw(" permil delivery " as *u8); dn(fc); dw(" -> " as *u8); dn(lc); dw(" at a FIXED bar\n" as *u8)
231 dw(" scope effect " as *u8); dsn(sc); dw(" permil bar " as *u8); dn(fb); dw(" -> " as *u8); dn(lb); dw("; class=" as *u8)
232 dl_scope_name(dc_scope_class(fb, lb, fd, ld)); dw("\n" as *u8)
233 dw(" ----\n total " as *u8); dsn(tt); dw(" permil residual=" as *u8); dsn(rs); dw("\n\n" as *u8)
234
235 dw("GAP " as *u8); dn(dc_gap(fc, fb)); dw(" -> " as *u8); dn(dc_gap(lc, lb)); dw(" levels owed\n" as *u8)
236 dw("RATES delivery " as *u8); dsn(lc - fc); dw(" bar " as *u8); dsn(lb - fb)
237 dw(" net " as *u8); dsn((lc - fc) - (lb - fb)); dw("\n" as *u8)
238 dw("ETA " as *u8); dnu(dc_eta(fc, fb, lc, lb)); dw(" windows at the observed net rate\n" as *u8)
239
240 let vd: i64 = dc_verdict(fc, fb, lc, lb, moved)
241 dw("\nVERDICT=" as *u8); dl_verdict_name(vd); dw("\n" as *u8)
242 dl_advice(vd)
243 return 0
244}
245
246func dl_selftest() -> i64 {
247 var pass: i64 = 0
248 var ttl: i64 = 0
249 let s: *u8 = "ECOMAT epoch=1785608007 domains=26 overall_permil=418 sum_cur=51 sum_bar=122 verdict=GREEN" as *u8
250 var sn: i64 = 0
251 while s[sn] != (0 as u8) { sn = sn + 1 }
252
253 ttl = ttl + 1
254 if dl_val(s, 0, sn, "sum_cur=" as *u8) == 51 { pass = pass + 1 }
255 dw(" T1 parses sum_cur=51 out of a real ledger line\n" as *u8)
256 ttl = ttl + 1
257 if dl_val(s, 0, sn, "sum_bar=" as *u8) == 122 { pass = pass + 1 }
258 dw(" T2 parses sum_bar=122\n" as *u8)
259 ttl = ttl + 1
260 if dl_val(s, 0, sn, "domains=" as *u8) == 26 { pass = pass + 1 }
261 dw(" T3 parses domains=26\n" as *u8)
262 ttl = ttl + 1
263 if dl_val(s, 0, sn, "epoch=" as *u8) == DL_MAGIC_1785608007 { pass = pass + 1 }
264 dw(" T4 parses a 10-digit epoch without overflow\n" as *u8)
265 // an ABSENT key must be UNMEASURED, never 0 -- a beat line would otherwise read as cur=0
266 ttl = ttl + 1
267 if dl_val(s, 0, sn, "sum_missing=" as *u8) == dc_unmeasured() { pass = pass + 1 }
268 dw(" T5 an ABSENT key is UNMEASURED, not a silent 0 (beat lines cannot fake a sample)\n" as *u8)
269 ttl = ttl + 1
270 let beat: *u8 = "ECOMAT epoch=1785584402 domains=26 overall_permil=418 src=beat verdict=GREEN" as *u8
271 var bn: i64 = 0
272 while beat[bn] != (0 as u8) { bn = bn + 1 }
273 if dl_val(beat, 0, bn, "sum_cur=" as *u8) == dc_unmeasured() { pass = pass + 1 }
274 dw(" T6 a real beat line yields NO sample\n" as *u8)
275
276 dw("SELFTEST pass=" as *u8); dn(pass); dw("/" as *u8); dn(ttl)
277 if pass == ttl { dw(" verdict=GREEN\n" as *u8); return 0 }
278 dw(" verdict=RED\n" as *u8)
279 return 1
280}
281
282func main(argc: i64, argv: *i64) -> i64 {
283 if argc < 2 {
284 dw("usage: nx_deltaclass ledger <path>\n nx_deltaclass window <path> <n>\n nx_deltaclass selftest\n" as *u8)
285 return 2
286 }
287 let verb: *u8 = argv[1] as *u8
288 if dstreq(verb, "selftest" as *u8) == 1 { return dl_selftest() }
289 if dstreq(verb, "ledger" as *u8) == 1 {
290 if argc < 3 { dw("{\"error\":\"ledger needs <path>\"}\n" as *u8); return 2 }
291 return dl_report(argv[2] as *u8, 0)
292 }
293 if dstreq(verb, "window" as *u8) == 1 {
294 if argc < 4 { dw("{\"error\":\"window needs <path> <n>\"}\n" as *u8); return 2 }
295 return dl_report(argv[2] as *u8, dl_num_at(argv[3] as *u8, 0, 20))
296 }
297 dw("{\"error\":\"unknown verb\"}\n" as *u8)
298 return 2
299}