nx_barfresh_lib.nx source
↩ module page · 403 lines · 18831 B
1// nx_barfresh_lib.nx -- THE ONE RULER FOR BAR AGE ON A /compare BOARD: a bar is the CURRENT MONTH'S, or it is refused.
2//
3// Operator 2026-09-06, verbatim: "make sure its a hard fail to use anything less than current month unless there is
4// nothing current month for these what does x month of x year say is sota" and "this needs to become the way that the
5// logic forces you from the /compare domain and nishi estate as youve invested significantly in 12 year old tech".
6// Measured cost the same day: the intelmine ladder (a tagger, a parser, a clusterer, a CRF, an embedding reader) climbed
7// for a day toward the SemEval-2014 winners' F1 because that paper was the one source the domain had mirrored and the bar
8// carried no month. Nothing in the estate asked how old the bar was: nx_capsearch and nx_spendgate guard ORGAN
9// duplication, nx_sota_status guards CLAIM binding, and bar AGE had no ruler. This lib is that ruler. It is composed by
10// nx_compare_rank, so a stale bar refuses the board's work queue instead of being remembered by a seat.
11//
12// THE DATA (rows in <domain>.plan, pipe-separated, NO pipe inside a field):
13// bar|<id>|<YYYY-MM>|<subject>|<what that month says is the state of the art>|<ref key>|<note>
14// the source MONTH of the bar and the .refs key of the listing it was read from (a mirror of the bytes read)
15// barscan|<YYYY-MM-DD>|<ref key>|newest=<YYYY-MM>|<note>
16// an ATTESTATION: on that date the listing at <ref key> was fetched and read, and its newest entry was in <newest>.
17// This is the only way a bar older than the current month survives: the current month was LOOKED FOR and had nothing.
18// THE STATES, per bar, against the current month (derived from the clock, or handed in by a gate):
19// FRESH the bar's month IS the current month
20// ATTESTED older, and a barscan dated THIS month for the SAME ref reports newest == the bar's month: the fallback is
21// named, "what does <that month> say is sota" is exactly what the row carries
22// STALE older, and a barscan dated this month for the same ref reports a NEWER month than the bar cites: the bar
23// ignores evidence the board already holds
24// UNATTESTED older, and no barscan dated this month for its ref: nobody looked this month. "Nothing newer" is a claim
25// that must be re-earned every month, so this is the hard fail the operator asked for
26// MALFORMED a month that does not parse, or a month after the current one
27// DUPLICATE a sotabar row whose id an EARLIER sotabar row on the same plan already carries: one declaration made
28// twice. MEASURED 2026-09-14 on search.plan: a whole intake landed twice across a transport drop (two
29// bars, two scans, two targets, one rung id reused) and only the rung id was refused, by the plan-graph
30// rule; two rows for one id hand every reader a coin flip, so this ruler refuses them the same way.
31// AND PER ATTESTATION: a barscan row repeating an earlier row's date AND ref is a DUPLICATE SCAN, counted (scans_dup)
32// and refused like a duplicate bar; two scans of one listing on DIFFERENT days are two attestations, not duplicates.
33// THE VERDICT: FRESH (exit 0) when every bar is FRESH or ATTESTED; STALE (exit 1) when any bar is STALE, UNATTESTED,
34// MALFORMED or DUPLICATE or any scan is a duplicate (bf_refusal_rule names WHICH, so a consumer prints the rule from
35// this lib instead of paraphrasing it); NO-BAR (exit 3) when the plan declares no bar rows. A domain opts in by declaring its first bar; a domain
36// that has not is LABELED by its consumers, never acquitted and never refused (a fleet-wide refusal on day one would be
37// the permanently-red detector everyone learns to ignore). The partition bars = fresh + attested + stale + unattested +
38// malformed is printed by every consumer and must sum.
39// COMPOSES, never re-implements: sys_read_file (whole file, cannot short-read), sys_clock_gettime_real (the clock),
40// civil_from_days (nx_timefmt, Hinnant) for the month of an epoch, nx_comparetree_lib for the two-tree plan path.
41// Lines end at a newline OR a NUL, so a caller that NUL-terminated lines in place (the ranker does) hands over its buffer.
42// license_tier: ORIGINAL No hw writes (Rule 26).
43import "nx_syscalls.nx"
44import "nx_timefmt.nx"
45import "nx_comparetree_lib.nx"
46
47const BF_SECS_PER_DAY: i64 = 86400
48const BF_MONTHS_PER_YEAR: i64 = 12
49const BF_PIPE: i64 = 124
50const BF_NL: i64 = 10
51const BF_DASH: i64 = 45
52const BF_DIGIT0: i64 = 48
53const BF_DIGIT9: i64 = 57
54const BF_YM_LEN: i64 = 7 // "YYYY-MM"
55const BF_YM_YEAR_DIGITS: i64 = 4
56const BF_YM_MONTH_AT: i64 = 5
57const BF_YM_MONTH_DIGITS: i64 = 2
58const BF_YM_DASH_AT: i64 = 4
59// sotabar, NOT bar: the plan renderer already owns a bar| kind (bar|label|url|measured-on|theirs|ours, the research bar)
60// and the matrix owns another (an instrument bar). A third meaning under the same tag would render as a garbled
61// research bar on every page and hand the next reader a coin flip wearing a schema.
62const BF_BAR_TAG: *u8 = "sotabar|"
63const BF_SCAN_TAG: *u8 = "barscan|"
64const BF_NEWEST_TAG: *u8 = "newest="
65const BF_NEWEST_TAG_LEN: i64 = 7
66const BF_PLAN_SUFFIX: *u8 = ".plan"
67const BF_I64: i64 = 8
68const BF_CLOCK_WORDS: i64 = 2 // sys_clock_gettime_real fills seconds and nanoseconds
69// field positions
70const BF_F_BAR_ID: i64 = 1
71const BF_F_BAR_YM: i64 = 2
72const BF_F_BAR_SUBJECT: i64 = 3
73const BF_F_BAR_SAYS: i64 = 4
74const BF_F_BAR_REF: i64 = 5
75const BF_F_SCAN_DATE: i64 = 1
76const BF_F_SCAN_REF: i64 = 2
77const BF_F_SCAN_NEWEST: i64 = 3
78// states
79const BF_S_FRESH: i64 = 0
80const BF_S_ATTESTED: i64 = 1
81const BF_S_STALE: i64 = 2
82const BF_S_UNATTESTED: i64 = 3
83const BF_S_MALFORMED: i64 = 4
84const BF_S_DUPLICATE: i64 = 5
85// exits
86const BF_EXIT_FRESH: i64 = 0
87const BF_EXIT_STALE: i64 = 1
88const BF_EXIT_NOBAR: i64 = 3
89// census slots
90const BF_C_BARS: i64 = 0
91const BF_C_FRESH: i64 = 1
92const BF_C_ATTESTED: i64 = 2
93const BF_C_STALE: i64 = 3
94const BF_C_UNATTESTED: i64 = 4
95const BF_C_MALFORMED: i64 = 5
96const BF_C_SCANS: i64 = 6
97const BF_C_SCANS_CUR: i64 = 7
98const BF_C_DUPLICATE: i64 = 8 // sotabar rows whose id an earlier row already carries (state DUPLICATE)
99const BF_C_SCANS_DUP: i64 = 9 // barscan rows repeating an earlier row's date AND ref
100const BF_C_N: i64 = 10
101const BF_NONE: i64 = 0 - 1
102
103func bf_slen(s: *u8) -> i64 {
104 var n: i64 = 0
105 while s[n] != (0 as u8) { n = n + 1 }
106 return n
107}
108
109// a line ends at a newline, a NUL, or the end of the buffer
110func bf_line_end(buf: *u8, n: i64, p: i64) -> i64 {
111 var e: i64 = p
112 var go: i64 = 1
113 while go == 1 {
114 if e >= n { go = 0 } else {
115 if buf[e] == (BF_NL as u8) { go = 0 } else { if buf[e] == (0 as u8) { go = 0 } else { e = e + 1 } }
116 }
117 }
118 return e
119}
120
121// does the line at [p,e) start with tag
122func bf_line_starts(buf: *u8, p: i64, e: i64, tag: *u8) -> i64 {
123 var i: i64 = 0
124 while tag[i] != (0 as u8) {
125 if p + i >= e { return 0 }
126 if buf[p + i] != tag[i] { return 0 }
127 i = i + 1
128 }
129 return 1
130}
131
132// field k (0-based) of the line [p,e): its length, with off[0] = its start; BF_NONE when the line has no field k
133func bf_field(buf: *u8, p: i64, e: i64, k: i64, off: *i64) -> i64 {
134 var i: i64 = p
135 var f: i64 = 0
136 var s: i64 = p
137 while i < e {
138 if buf[i] == (BF_PIPE as u8) {
139 if f == k { off[0] = s; return i - s }
140 f = f + 1
141 s = i + 1
142 }
143 i = i + 1
144 }
145 if f == k { off[0] = s; return e - s }
146 return BF_NONE
147}
148
149func bf_is_digit(b: u8) -> i64 {
150 if (b as i64) < BF_DIGIT0 { return 0 }
151 if (b as i64) > BF_DIGIT9 { return 0 }
152 return 1
153}
154
155func bf_ym_index(y: i64, m: i64) -> i64 {
156 return y * BF_MONTHS_PER_YEAR + (m - 1)
157}
158func bf_ym_year(ix: i64) -> i64 {
159 return ix / BF_MONTHS_PER_YEAR
160}
161func bf_ym_month(ix: i64) -> i64 {
162 return ix - (ix / BF_MONTHS_PER_YEAR) * BF_MONTHS_PER_YEAR + 1
163}
164
165// "YYYY-MM" (or "YYYY-MM-DD...": the day is ignored, the dash after MM is required) -> month index, BF_NONE if malformed
166func bf_parse_ym(s: *u8, len: i64) -> i64 {
167 if len < BF_YM_LEN { return BF_NONE }
168 var i: i64 = 0
169 while i < BF_YM_YEAR_DIGITS { if bf_is_digit(s[i]) == 0 { return BF_NONE } i = i + 1 }
170 if s[BF_YM_DASH_AT] != (BF_DASH as u8) { return BF_NONE }
171 i = 0
172 while i < BF_YM_MONTH_DIGITS { if bf_is_digit(s[BF_YM_MONTH_AT + i]) == 0 { return BF_NONE } i = i + 1 }
173 if len > BF_YM_LEN { if s[BF_YM_LEN] != (BF_DASH as u8) { return BF_NONE } }
174 var y: i64 = 0
175 i = 0
176 while i < BF_YM_YEAR_DIGITS { y = y * 10 + ((s[i] as i64) - BF_DIGIT0); i = i + 1 }
177 var m: i64 = 0
178 i = 0
179 while i < BF_YM_MONTH_DIGITS { m = m * 10 + ((s[BF_YM_MONTH_AT + i] as i64) - BF_DIGIT0); i = i + 1 }
180 if m < 1 { return BF_NONE }
181 if m > BF_MONTHS_PER_YEAR { return BF_NONE }
182 return bf_ym_index(y, m)
183}
184
185// "newest=YYYY-MM" -> month index, BF_NONE if malformed
186func bf_parse_newest(s: *u8, len: i64) -> i64 {
187 if len < BF_NEWEST_TAG_LEN + BF_YM_LEN { return BF_NONE }
188 var i: i64 = 0
189 while i < BF_NEWEST_TAG_LEN { if s[i] != BF_NEWEST_TAG[i] { return BF_NONE } i = i + 1 }
190 return bf_parse_ym((s as i64 + BF_NEWEST_TAG_LEN) as *u8, len - BF_NEWEST_TAG_LEN)
191}
192
193// the month of an epoch-seconds instant, through the estate's Hinnant civil date (nx_timefmt)
194func bf_ym_of_epoch(secs: i64) -> i64 {
195 let y: *i64 = sys_mmap(BF_I64) as *i64
196 let m: *i64 = sys_mmap(BF_I64) as *i64
197 let d: *i64 = sys_mmap(BF_I64) as *i64
198 civil_from_days(secs / BF_SECS_PER_DAY, y, m, d)
199 return bf_ym_index(y[0], m[0])
200}
201
202func bf_now_ym() -> i64 {
203 let ts: *i64 = sys_mmap(BF_CLOCK_WORDS * BF_I64) as *i64
204 ts[0] = 0
205 sys_clock_gettime_real(ts)
206 return bf_ym_of_epoch(ts[0])
207}
208
209// "YYYY-MM" into dst at off (7 bytes), NUL-terminated; returns the new offset
210func bf_ym_write(dst: *u8, off: i64, ix: i64) -> i64 {
211 var y: i64 = bf_ym_year(ix)
212 var m: i64 = bf_ym_month(ix)
213 var o: i64 = off
214 var k: i64 = 1000
215 while k > 0 { dst[o] = ((y / k) - ((y / k) / 10) * 10 + BF_DIGIT0) as u8; o = o + 1; k = k / 10 }
216 dst[o] = BF_DASH as u8; o = o + 1
217 dst[o] = (m / 10 + BF_DIGIT0) as u8; o = o + 1
218 dst[o] = (m - (m / 10) * 10 + BF_DIGIT0) as u8; o = o + 1
219 dst[o] = 0 as u8
220 return o
221}
222
223// how many lines of the buffer start with tag
224func bf_count_rows(buf: *u8, n: i64, tag: *u8) -> i64 {
225 var c: i64 = 0
226 var p: i64 = 0
227 while p < n {
228 let e: i64 = bf_line_end(buf, n, p)
229 if bf_line_starts(buf, p, e, tag) == 1 { c = c + 1 }
230 p = e + 1
231 }
232 return c
233}
234
235// two spans of the buffer byte-equal
236func bf_span_eq(buf: *u8, o1: i64, l1: i64, o2: i64, l2: i64) -> i64 {
237 if l1 != l2 { return 0 }
238 var i: i64 = 0
239 while i < l1 { if buf[o1 + i] != buf[o2 + i] { return 0 } i = i + 1 }
240 return 1
241}
242
243// THE CLASSIFIER. Fills, per bar row in file order: off[i] = the line's start, ym[i] = its month index (BF_NONE when
244// malformed), st[i] = its state, seen[i] = the newest month a THIS-MONTH barscan for the same ref reported (BF_NONE when
245// none). c[] is the census. Returns the number of bar rows found. cur is the current month index.
246func bf_classify(buf: *u8, n: i64, cur: i64, off: *i64, ym: *i64, st: *i64, seen: *i64, c: *i64) -> i64 {
247 var k: i64 = 0
248 while k < BF_C_N { c[k] = 0; k = k + 1 }
249 // pass 1: the attestations
250 let nscan: i64 = bf_count_rows(buf, n, BF_SCAN_TAG)
251 let s_ym: *i64 = sys_mmap((nscan + 1) * BF_I64) as *i64
252 let s_ref_off: *i64 = sys_mmap((nscan + 1) * BF_I64) as *i64
253 let s_ref_len: *i64 = sys_mmap((nscan + 1) * BF_I64) as *i64
254 let s_newest: *i64 = sys_mmap((nscan + 1) * BF_I64) as *i64
255 let s_date_off: *i64 = sys_mmap((nscan + 1) * BF_I64) as *i64
256 let s_date_len: *i64 = sys_mmap((nscan + 1) * BF_I64) as *i64
257 let fo: *i64 = sys_mmap(BF_I64) as *i64
258 var ns: i64 = 0
259 var p: i64 = 0
260 while p < n {
261 let e: i64 = bf_line_end(buf, n, p)
262 if bf_line_starts(buf, p, e, BF_SCAN_TAG) == 1 {
263 var dl: i64 = bf_field(buf, p, e, BF_F_SCAN_DATE, fo)
264 if dl < 0 { dl = 0 }
265 let dof: i64 = fo[0]
266 var sym: i64 = BF_NONE
267 if dl > 0 { sym = bf_parse_ym((buf as i64 + dof) as *u8, dl) }
268 var rl: i64 = bf_field(buf, p, e, BF_F_SCAN_REF, fo)
269 if rl < 0 { rl = 0 }
270 var ro: i64 = fo[0]
271 // a repeated attestation: the same date AND the same ref as an earlier barscan row
272 var sdup: i64 = 0
273 var sq: i64 = 0
274 while sq < ns {
275 if bf_span_eq(buf, s_date_off[sq], s_date_len[sq], dof, dl) == 1 { if bf_span_eq(buf, s_ref_off[sq], s_ref_len[sq], ro, rl) == 1 { sdup = 1; sq = ns } }
276 sq = sq + 1
277 }
278 if sdup == 1 { c[BF_C_SCANS_DUP] = c[BF_C_SCANS_DUP] + 1 }
279 s_date_off[ns] = dof; s_date_len[ns] = dl
280 var nl: i64 = bf_field(buf, p, e, BF_F_SCAN_NEWEST, fo)
281 var nw: i64 = BF_NONE
282 if nl > 0 { nw = bf_parse_newest((buf as i64 + fo[0]) as *u8, nl) }
283 s_ym[ns] = sym; s_ref_off[ns] = ro; s_ref_len[ns] = rl; s_newest[ns] = nw
284 ns = ns + 1
285 c[BF_C_SCANS] = c[BF_C_SCANS] + 1
286 if sym == cur { c[BF_C_SCANS_CUR] = c[BF_C_SCANS_CUR] + 1 }
287 }
288 p = e + 1
289 }
290 // pass 2: the bars
291 let nbar_cap: i64 = bf_count_rows(buf, n, BF_BAR_TAG) + 1
292 let b_idoff: *i64 = sys_mmap(nbar_cap * BF_I64) as *i64
293 let b_idlen: *i64 = sys_mmap(nbar_cap * BF_I64) as *i64
294 var nb: i64 = 0
295 p = 0
296 while p < n {
297 let e2: i64 = bf_line_end(buf, n, p)
298 if bf_line_starts(buf, p, e2, BF_BAR_TAG) == 1 {
299 off[nb] = p
300 // a repeated declaration: the same id as an earlier sotabar row
301 var il: i64 = bf_field(buf, p, e2, BF_F_BAR_ID, fo)
302 if il < 0 { il = 0 }
303 let ido: i64 = fo[0]
304 var dup: i64 = 0
305 var bq: i64 = 0
306 while bq < nb { if bf_span_eq(buf, b_idoff[bq], b_idlen[bq], ido, il) == 1 { dup = 1; bq = nb } bq = bq + 1 }
307 b_idoff[nb] = ido; b_idlen[nb] = il
308 var yl: i64 = bf_field(buf, p, e2, BF_F_BAR_YM, fo)
309 var by: i64 = BF_NONE
310 if yl > 0 { by = bf_parse_ym((buf as i64 + fo[0]) as *u8, yl) }
311 ym[nb] = by
312 var rl2: i64 = bf_field(buf, p, e2, BF_F_BAR_REF, fo)
313 var ro2: i64 = fo[0]
314 var state: i64 = BF_S_UNATTESTED
315 var best: i64 = BF_NONE
316 if dup == 1 { state = BF_S_DUPLICATE }
317 else { if by == BF_NONE { state = BF_S_MALFORMED }
318 else { if by > cur { state = BF_S_MALFORMED }
319 else { if by == cur { state = BF_S_FRESH }
320 else {
321 // an older bar: what did THIS month's scans of the SAME listing report
322 var si: i64 = 0
323 while si < ns {
324 if s_ym[si] == cur { if rl2 > 0 { if bf_span_eq(buf, s_ref_off[si], s_ref_len[si], ro2, rl2) == 1 {
325 if s_newest[si] != BF_NONE { if s_newest[si] > best { best = s_newest[si] } }
326 } } }
327 si = si + 1
328 }
329 if best == BF_NONE { state = BF_S_UNATTESTED }
330 else { if best > by { state = BF_S_STALE } else { if best == by { state = BF_S_ATTESTED } else { state = BF_S_UNATTESTED } } }
331 } } } }
332 st[nb] = state
333 seen[nb] = best
334 c[BF_C_BARS] = c[BF_C_BARS] + 1
335 if state == BF_S_FRESH { c[BF_C_FRESH] = c[BF_C_FRESH] + 1 }
336 if state == BF_S_ATTESTED { c[BF_C_ATTESTED] = c[BF_C_ATTESTED] + 1 }
337 if state == BF_S_STALE { c[BF_C_STALE] = c[BF_C_STALE] + 1 }
338 if state == BF_S_UNATTESTED { c[BF_C_UNATTESTED] = c[BF_C_UNATTESTED] + 1 }
339 if state == BF_S_MALFORMED { c[BF_C_MALFORMED] = c[BF_C_MALFORMED] + 1 }
340 if state == BF_S_DUPLICATE { c[BF_C_DUPLICATE] = c[BF_C_DUPLICATE] + 1 }
341 nb = nb + 1
342 }
343 p = e2 + 1
344 }
345 return nb
346}
347
348// the verdict from the census: the exit code every consumer branches on
349func bf_verdict(c: *i64) -> i64 {
350 if c[BF_C_BARS] == 0 { return BF_EXIT_NOBAR }
351 if c[BF_C_STALE] > 0 { return BF_EXIT_STALE }
352 if c[BF_C_UNATTESTED] > 0 { return BF_EXIT_STALE }
353 if c[BF_C_MALFORMED] > 0 { return BF_EXIT_STALE }
354 if c[BF_C_DUPLICATE] > 0 { return BF_EXIT_STALE }
355 if c[BF_C_SCANS_DUP] > 0 { return BF_EXIT_STALE }
356 return BF_EXIT_FRESH
357}
358
359// WHICH rule refused: the one name every consumer prints, so no consumer paraphrases this lib's verdict (a hand-copied
360// paraphrase is a duplicate ruler made of prose). Duplicates first: a declaration made twice is fixed before its month
361// is argued about. NONE when nothing refuses.
362func bf_refusal_rule(c: *i64) -> *u8 {
363 if c[BF_C_DUPLICATE] > 0 { return "BAR-DUPLICATE" as *u8 }
364 if c[BF_C_SCANS_DUP] > 0 { return "SCAN-DUPLICATE" as *u8 }
365 if c[BF_C_STALE] > 0 { return "BAR-STALE" as *u8 }
366 if c[BF_C_UNATTESTED] > 0 { return "BAR-UNATTESTED" as *u8 }
367 if c[BF_C_MALFORMED] > 0 { return "BAR-MALFORMED" as *u8 }
368 return "NONE" as *u8
369}
370
371func bf_partition_sum(c: *i64) -> i64 {
372 return c[BF_C_FRESH] + c[BF_C_ATTESTED] + c[BF_C_STALE] + c[BF_C_UNATTESTED] + c[BF_C_MALFORMED] + c[BF_C_DUPLICATE]
373}
374
375func bf_state_name(s: i64) -> *u8 {
376 if s == BF_S_FRESH { return "FRESH" as *u8 }
377 if s == BF_S_ATTESTED { return "ATTESTED" as *u8 }
378 if s == BF_S_STALE { return "STALE" as *u8 }
379 if s == BF_S_UNATTESTED { return "UNATTESTED" as *u8 }
380 if s == BF_S_DUPLICATE { return "DUPLICATE" as *u8 }
381 return "MALFORMED" as *u8
382}
383
384func bf_verdict_name(v: i64) -> *u8 {
385 if v == BF_EXIT_FRESH { return "FRESH" as *u8 }
386 if v == BF_EXIT_STALE { return "STALE" as *u8 }
387 return "NO-BAR" as *u8
388}
389
390// the plan file through the two-tree resolver's PUBLISHED order (d1 first, d2 second): the bytes, lenp[0] = length
391// (<= 0 when neither tree has it), which[0] = CT_TREE_PRIMARY when d1 answered, CT_TREE_SECONDARY when d2 did, else
392// CT_TREE_NONE. The dirs are parameters so a gate can hand it /tmp trees.
393func bf_read_plan(d1: *u8, d2: *u8, dom: *u8, lenp: *i64, which: *i64) -> *u8 {
394 let path: *u8 = sys_mmap(CT_PATH_CAP)
395 ct_build_path(d1, dom, BF_PLAN_SUFFIX, path)
396 var buf: *u8 = sys_read_file(path, lenp)
397 if lenp[0] > 0 { which[0] = CT_TREE_PRIMARY; return buf }
398 ct_build_path(d2, dom, BF_PLAN_SUFFIX, path)
399 buf = sys_read_file(path, lenp)
400 if lenp[0] > 0 { which[0] = CT_TREE_SECONDARY; return buf }
401 which[0] = CT_TREE_NONE
402 return buf
403}