nx_matrix_sym_lib.nx source
↩ module page · 160 lines · 9424 B
1// nx_matrix_sym_lib.nx -- THE ONE READER OF A COMPARE-MATRIX ROW'S SYMBOL FIELD (field 3).
2//
3// WHY THIS LIB EXISTS (measured 2026-08-16). The matrix format documents THREE symbol forms:
4// <real_symbol> the row claims a capability, grounded by finding it in the organ
5// _ABSENT_ a declared gap, owning nothing
6// _ABSENT_:<future_symbol> a WATCH CONTRACT -- the compare hive's build order. The generator
7// measures the named symbol every emit and flips the published cell
8// when the workstream ships it.
9// FIVE separate organs each re-derived that format privately, and EVERY ONE of them knew only the
10// first two forms, so every watch row was misread -- each in its own direction:
11// nx_sota_status `f2l == 8` -> watch row counted as a DELIVERED CAPABILITY. mangagen published
12// cov=1000 gaps=0 with SEVEN unbuilt capabilities. An OVER-CLAIM on the one
13// number whose entire purpose is to refuse over-claiming.
14// nx_domain_admit grounded the literal "_ABSENT_:mp_page_emit" in the organ source -- a string
15// that can never occur -- so every watch row FAILED ITS DOMAIN'S ADMISSION.
16// nx_capgraph_edges watch rows were treated as OWNING their organ, inventing ownership edges.
17// nx_compare_unified / nx_swarm_maturity same exact-equality test, same blind spot.
18//
19// A FORMAT KNOWN IN FIVE PLACES IS FIVE FORMATS, AND THEY DRIFT APART SILENTLY BECAUSE EACH COPY
20// LOOKS CORRECT ON ITS OWN. The tell was that the SAME suffix broke all five the same day it appeared.
21//
22// SCOPE, DELIBERATELY NARROW: this lib owns the FORMAT (what the forms are, where the prefix ends).
23// It does NOT own POLICY, because policy legitimately differs and collapsing it would be a second
24// defect: a purely lexical consumer must treat an unlanded watch row as a gap, while a consumer that
25// already reads the organ should ground the REAL symbol and count a landed contract as delivered.
26// Both are correct; they answer different questions. So the lib returns FACTS, never verdicts.
27//
28// NO FILE IO HERE ON PURPOSE -- that is what makes it usable by the lexical consumers too.
29// license_tier: ORIGINAL
30
31// "_ABSENT_" is 8 bytes; the watch form is that plus one ':' separator. The second length is DERIVED
32// from the first so the pair can never drift -- the exact class of defect that produced this lib.
33const MSYM_ABSENT_LEN: i64 = 8
34const MSYM_WATCH_LEN: i64 = MSYM_ABSENT_LEN + 1
35
36// Does buf[a..b) begin with "_ABSENT_"? Prefix, never exact length -- writing this as `b-a == 8` is
37// precisely the bug this lib was extracted to kill.
38func msym_has_absent_prefix(buf: *u8, a: i64, b: i64) -> i64 {
39 if b - a < MSYM_ABSENT_LEN { return 0 }
40 let lit: *u8 = "_ABSENT_" as *u8
41 var i: i64 = 0
42 while i < MSYM_ABSENT_LEN {
43 if buf[a + i] != lit[i] { return 0 }
44 i = i + 1
45 }
46 return 1
47}
48
49// Exactly "_ABSENT_" and nothing more: a declared gap that names no contract.
50func msym_is_bare_absent(buf: *u8, a: i64, b: i64) -> i64 {
51 if b - a != MSYM_ABSENT_LEN { return 0 }
52 return msym_has_absent_prefix(buf, a, b)
53}
54
55// "_ABSENT_:<future_symbol>" -- a WATCH CONTRACT. Requires at least one byte of symbol after the
56// colon, so a stray "_ABSENT_:" with nothing behind it is NOT reported as a contract: a contract that
57// names no symbol can never be measured, and calling it one would make it permanently unclosable.
58func msym_is_watch(buf: *u8, a: i64, b: i64) -> i64 {
59 if b - a <= MSYM_WATCH_LEN { return 0 }
60 if msym_has_absent_prefix(buf, a, b) == 0 { return 0 }
61 if buf[a + MSYM_ABSENT_LEN] != (58 as u8) { return 0 }
62 return 1
63}
64
65// ---- THE FOURTH FORM (2026-09-01): "_ABSENT_:<symbol>:<precondition-path>" ----
66// A WITHHELD-PROOF CONTRACT. It says: the mechanism SHIPPED and its symbol really is in the organ, but
67// the CLAIM the row makes is not supported yet because a NAMED precondition is unmet -- and that
68// precondition is a path a reader can go and check for themselves.
69//
70// WHY IT IS A SUBFORM OF THE WATCH CONTRACT AND NOT A NEW TOP-LEVEL TOKEN. Measured 2026-09-01:
71// EIGHTEEN organs re-derive the "_ABSENT_:" prefix privately (nx_sota_status, nx_domain_admit_lib,
72// nx_compare_rank, nx_compare_regen, nx_swcompare_lib, nx_market_ladder_lib, nx_accept_lib,
73// nx_firstbyte, nx_frontier_scan and more). A fresh marker such as "_WITHHELD_:" does NOT carry the
74// "_ABSENT_" prefix, so every one of those readers would classify it as an ORDINARY SYMBOL --
75// nx_sota_status returns PRESENT for exactly that case -- and a single data edit would manufacture an
76// over-claim in eighteen places at once. That is precisely the defect this lib was extracted to kill.
77// AS A SUBFORM IT DEGRADES CORRECTLY IN ALL EIGHTEEN WITHOUT ONE OF THEM CHANGING: msym_is_watch is
78// true, so a lexical reader calls it a declared gap; msym_real_start hands an unaware reader
79// "<symbol>:<precondition-path>", a string that can never occur in source, so it grounds as an UNLANDED
80// contract, i.e. an open gap. THE WORST A READER THAT HAS NEVER HEARD OF THIS FORM CAN CONCLUDE IS THE
81// TRUTH, AND IT IS THE CONSERVATIVE HALF OF THE TRUTH.
82//
83// FACTS ONLY, PER THIS LIB'S SCOPE: whether the symbol is really in the organ, and whether the
84// precondition is really unmet, are MEASUREMENTS -- they belong to the consumer that can do file IO.
85const MSYM_SEP: i64 = 58
86
87// Offset of the SECOND colon, the one dividing symbol from precondition, or -1 when this field is not a
88// withheld contract. It requires at least one byte of symbol BEFORE it and at least one byte of path
89// AFTER it: a contract naming no symbol cannot be measured and a precondition naming no path cannot be
90// checked, and either half missing would make the form UNFALSIFIABLE, which is the one thing it must
91// never be -- a row that no reader can refute is a row that silences a gap for free.
92func msym_withheld_sep(buf: *u8, a: i64, b: i64) -> i64 {
93 if msym_is_watch(buf, a, b) == 0 { return 0 - 1 }
94 var i: i64 = a + MSYM_WATCH_LEN
95 while i < b {
96 if (buf[i] as i64) == MSYM_SEP {
97 if i == a + MSYM_WATCH_LEN { return 0 - 1 }
98 if i + 1 >= b { return 0 - 1 }
99 return i
100 }
101 i = i + 1
102 }
103 return 0 - 1
104}
105
106func msym_is_withheld(buf: *u8, a: i64, b: i64) -> i64 {
107 if msym_withheld_sep(buf, a, b) < 0 { return 0 }
108 return 1
109}
110
111// Where the precondition path BEGINS. An OFFSET, never a verdict: whether that path shows the
112// precondition unmet is the caller's measurement, and this lib deliberately performs no file IO.
113func msym_withheld_pre_start(buf: *u8, a: i64, b: i64) -> i64 {
114 let s: i64 = msym_withheld_sep(buf, a, b)
115 if s < 0 { return 0 - 1 }
116 return s + 1
117}
118
119// Where the symbol a consumer should actually look for BEGINS. For a watch row that is past the
120// "_ABSENT_:" prefix; for every other row it is the field start unchanged.
121// RESOLVING THE NAME IS NOT RESOLVING THE THING: this returns an OFFSET, and whether the symbol is
122// present in its organ is the caller's measurement to make.
123func msym_real_start(buf: *u8, a: i64, b: i64) -> i64 {
124 if msym_is_watch(buf, a, b) == 1 { return a + MSYM_WATCH_LEN }
125 return a
126}
127
128// The LEXICAL answer, for consumers that cannot read the organ: a row is a gap if it declares absence
129// in either form. A consumer that CAN read the organ should instead ask msym_is_watch + msym_real_start
130// and ground the real symbol, so that a landed contract counts as delivered rather than as debt.
131func msym_is_declared_gap(buf: *u8, a: i64, b: i64) -> i64 {
132 if msym_is_bare_absent(buf, a, b) == 1 { return 1 }
133 return msym_is_watch(buf, a, b)
134}
135
136// ---- NULL-TERMINATED VARIANTS ----
137// Some consumers already hold the symbol as a copied C string rather than as an offset pair. They get
138// wrappers rather than a second implementation, because "adapt the call site" is how the format came
139// to be known five different ways in the first place.
140func msym_zlen(s: *u8) -> i64 {
141 var n: i64 = 0
142 while s[n] != (0 as u8) { n = n + 1 }
143 return n
144}
145func msym_is_bare_absent_z(s: *u8) -> i64 { return msym_is_bare_absent(s, 0, msym_zlen(s)) }
146func msym_is_watch_z(s: *u8) -> i64 { return msym_is_watch(s, 0, msym_zlen(s)) }
147func msym_is_declared_gap_z(s: *u8) -> i64 { return msym_is_declared_gap(s, 0, msym_zlen(s)) }
148// The symbol a consumer should actually search for: for a watch contract this points PAST the
149// "_ABSENT_:" prefix, for anything else it is the string unchanged. Returns a pointer INTO s, so it
150// stays valid exactly as long as s does and copies nothing.
151func msym_real_z(s: *u8) -> *u8 {
152 return ((s as i64) + msym_real_start(s, 0, msym_zlen(s))) as *u8
153}
154
155// The fourth form's NUL-terminated wrappers, at the tail with their siblings and for the same reason:
156// adapting a call site rather than adding a wrapper is how this format came to be known five ways.
157func msym_is_withheld_z(s: *u8) -> i64 { return msym_is_withheld(s, 0, msym_zlen(s)) }
158// Index of the separating colon INSIDE s, so a caller holding a copied C string can split it in place:
159// write a NUL at this index and s is the bare symbol, while index+1 begins the precondition path.
160func msym_withheld_sep_z(s: *u8) -> i64 { return msym_withheld_sep(s, 0, msym_zlen(s)) }