nx_jargon.nx source
↩ module page · 305 lines · 13921 B
1// nx_jargon.nx -- substrate-native terminology bridge.
2//
3// Per BRIDGEWORK_DOCTRINE: substrate lets a NEWCOMER and an EXPERT
4// talk about the same concept in their own language. Per discipline
5// + per audience tier. Cross-discipline aliasing first-class.
6//
7// Three sealed enums:
8// Discipline: MATH / PHYSICS / CS / STATS / ENGINEERING / BIOLOGY /
9// ECONOMICS / LINGUISTICS / CHEMISTRY
10// Tier: BEGINNER / INTERMEDIATE / EXPERT
11// Form: DEFINITION / METAPHOR / EXAMPLE / FORMULA / CITATION
12//
13// genealogy_id: feynman_lecturing + popper_clarity + accessibility_research
14// lineage_id: terminology_bridge + translation_layer
15// axioms: NX_AX_LOGIC_IDENTITY (definition equals concept itself)
16
17// nx_safety_envelope:
18// intended_use: AUTO_APPLIED -- primitive-specific tuning queued
19// sil_target: SIL1
20// evidence: [bulk_applied_2026-05-16, see-file-comment-for-detail]
21// verdict: NOT_YET_EVALUATED
22
23import "syscalls.nx"
24import "nx_axioms.nx"
25
26// ===== sealed disciplines ==============================================
27
28const NX_DISC_MATH: i64 = 0
29const NX_DISC_PHYSICS: i64 = 1
30const NX_DISC_CS: i64 = 2
31const NX_DISC_STATS: i64 = 3
32const NX_DISC_ENGINEERING: i64 = 4
33const NX_DISC_BIOLOGY: i64 = 5
34const NX_DISC_ECONOMICS: i64 = 6
35const NX_DISC_LINGUISTICS: i64 = 7
36const NX_DISC_CHEMISTRY: i64 = 8
37
38// ===== sealed tiers ====================================================
39
40const NX_TIER_BEGINNER: i64 = 0 // 12-year-old can follow
41const NX_TIER_INTERMEDIATE: i64 = 1 // undergraduate
42const NX_TIER_EXPERT: i64 = 2 // PhD-level
43
44// ===== sealed forms ====================================================
45
46const NX_FORM_DEFINITION: i64 = 0
47const NX_FORM_METAPHOR: i64 = 1
48const NX_FORM_EXAMPLE: i64 = 2
49const NX_FORM_FORMULA: i64 = 3
50const NX_FORM_CITATION: i64 = 4
51
52// ===== jargon entry ====================================================
53
54struct JargonEntry {
55 term: *u8, // canonical name
56 discipline: i64,
57 tier: i64,
58 form: i64,
59 explanation: *u8, // human text
60 cross_disc_count: i64, // # cross-discipline aliases
61 cross_disc_names: *u8, // packed flat list
62 citation: *u8, // primary source ref
63}
64
65const NX_JARGON_ENTRY_BYTES: i64 = 64
66
67struct JargonDb {
68 entries: *JargonEntry,
69 n_entries: i64,
70 capacity: i64,
71}
72
73const NX_JARGON_MAX_ENTRIES: i64 = 4096
74
75func nx_jargon_db_alloc() -> *JargonDb {
76 let raw: *u8 = sys_mmap(24)
77 let db: *JargonDb = raw as *JargonDb
78 db.entries = (sys_mmap(NX_JARGON_MAX_ENTRIES * NX_JARGON_ENTRY_BYTES)) as *JargonEntry
79 db.n_entries = 0
80 db.capacity = NX_JARGON_MAX_ENTRIES
81 return db
82}
83
84func nx_jargon_entry_at(db: *JargonDb, i: i64) -> *JargonEntry {
85 return (((db.entries as i64) + i * NX_JARGON_ENTRY_BYTES) as *JargonEntry)
86}
87
88// Add a new entry. Returns its index.
89func nx_jargon_add(db: *JargonDb, term: *u8, discipline: i64, tier: i64,
90 form: i64, explanation: *u8, citation: *u8) -> i64 {
91 if db.n_entries >= db.capacity { return -1 }
92 let e: *JargonEntry = nx_jargon_entry_at(db, db.n_entries)
93 e.term = term
94 e.discipline = discipline
95 e.tier = tier
96 e.form = form
97 e.explanation = explanation
98 e.cross_disc_count = 0
99 e.cross_disc_names = (0 as *u8)
100 e.citation = citation
101 let idx: i64 = db.n_entries
102 db.n_entries = db.n_entries + 1
103 return idx
104}
105
106// String equality on null-terminated names (capped at 256).
107func nx_jargon_str_eq(a: *u8, b: *u8) -> i64 {
108 var i: i64 = 0
109 while i < 256 {
110 if a[i] != b[i] { return 0 }
111 if a[i] == 0 { return 1 }
112 i = i + 1
113 }
114 return 1
115}
116
117// Lookup: find the entry matching (term, discipline, tier). Returns
118// the index or -1 if none.
119func nx_jargon_lookup(db: *JargonDb, term: *u8, discipline: i64, tier: i64) -> i64 {
120 var i: i64 = 0
121 while i < db.n_entries {
122 let e: *JargonEntry = nx_jargon_entry_at(db, i)
123 if e.discipline == discipline {
124 if e.tier == tier {
125 if nx_jargon_str_eq(e.term, term) == 1 { return i }
126 }
127 }
128 i = i + 1
129 }
130 return -1
131}
132
133// Explain: returns explanation text for (term, discipline, tier).
134// Returns 0-pointer if no match.
135func nx_jargon_explain(db: *JargonDb, term: *u8, discipline: i64, tier: i64) -> *u8 {
136 let idx: i64 = nx_jargon_lookup(db, term, discipline, tier)
137 if idx < 0 { return 0 as *u8 }
138 let e: *JargonEntry = nx_jargon_entry_at(db, idx)
139 return e.explanation
140}
141
142// Audit: how many tiers does a given term have entries for?
143// Used by acceptance gate per BRIDGEWORK_DOCTRINE.
144func nx_jargon_audit_tier_count(db: *JargonDb, term: *u8, discipline: i64) -> i64 {
145 var count: i64 = 0
146 var t: i64 = 0
147 while t < 3 {
148 if nx_jargon_lookup(db, term, discipline, t) >= 0 { count = count + 1 }
149 t = t + 1
150 }
151 return count
152}
153
154// Count entries by discipline.
155func nx_jargon_count_by_discipline(db: *JargonDb, discipline: i64) -> i64 {
156 var c: i64 = 0
157 var i: i64 = 0
158 while i < db.n_entries {
159 let e: *JargonEntry = nx_jargon_entry_at(db, i)
160 if e.discipline == discipline { c = c + 1 }
161 i = i + 1
162 }
163 return c
164}
165
166// Count entries by tier.
167func nx_jargon_count_by_tier(db: *JargonDb, tier: i64) -> i64 {
168 var c: i64 = 0
169 var i: i64 = 0
170 while i < db.n_entries {
171 let e: *JargonEntry = nx_jargon_entry_at(db, i)
172 if e.tier == tier { c = c + 1 }
173 i = i + 1
174 }
175 return c
176}
177
178// ===== bundled starter corpus ===========================================
179//
180// Returns a DB pre-populated with common math/CS/physics/stats terms,
181// each with at least BEGINNER + EXPERT entries.
182
183func nx_jargon_seed_corpus(db: *JargonDb) -> i64 {
184 // === Math: monoid ===
185 nx_jargon_add(db, "monoid" as *u8, NX_DISC_MATH, NX_TIER_BEGINNER,
186 NX_FORM_METAPHOR,
187 "A thing where you can combine two items into one, with a 'do nothing' identity element. Example: numbers under multiplication (1 is the do-nothing)." as *u8,
188 "Mac Lane 1971 Categories for the Working Mathematician" as *u8)
189 nx_jargon_add(db, "monoid" as *u8, NX_DISC_MATH, NX_TIER_EXPERT,
190 NX_FORM_DEFINITION,
191 "A set M with an associative binary operation *: M×M -> M and an identity element e such that e*m = m*e = m for all m in M." as *u8,
192 "Mac Lane 1971 Categories for the Working Mathematician" as *u8)
193
194 // === Math: epsilon-delta ===
195 nx_jargon_add(db, "epsilon_delta" as *u8, NX_DISC_MATH, NX_TIER_BEGINNER,
196 NX_FORM_METAPHOR,
197 "For any tiny margin around your target value, you can find a tiny range of inputs that keeps you within that margin. It's the formal way to say 'small enough input changes give small enough output changes.'" as *u8,
198 "Cauchy 1821 + Weierstrass 1850s" as *u8)
199 nx_jargon_add(db, "epsilon_delta" as *u8, NX_DISC_MATH, NX_TIER_EXPERT,
200 NX_FORM_DEFINITION,
201 "f is continuous at a iff for every eps > 0 there exists delta > 0 such that |x - a| < delta implies |f(x) - f(a)| < eps." as *u8,
202 "Cauchy 1821 + Weierstrass 1850s" as *u8)
203
204 // === Math: Cauchy-Schwarz ===
205 nx_jargon_add(db, "cauchy_schwarz" as *u8, NX_DISC_MATH, NX_TIER_BEGINNER,
206 NX_FORM_METAPHOR,
207 "If you have two lists of numbers, multiply them pair-by-pair and sum -- you'll never get more than the product of the lists' sizes-as-vectors." as *u8,
208 "Cauchy 1821 + Schwarz 1888" as *u8)
209 nx_jargon_add(db, "cauchy_schwarz" as *u8, NX_DISC_MATH, NX_TIER_EXPERT,
210 NX_FORM_FORMULA,
211 "|<u, v>|^2 <= <u, u> * <v, v> for u, v in any inner product space. Equality iff u and v are linearly dependent." as *u8,
212 "Cauchy 1821 + Schwarz 1888" as *u8)
213
214 // === Math: homeomorphism ===
215 nx_jargon_add(db, "homeomorphism" as *u8, NX_DISC_MATH, NX_TIER_BEGINNER,
216 NX_FORM_METAPHOR,
217 "You can squish/stretch shape A into shape B (and vice versa) without tearing or gluing. A coffee mug and a donut are homeomorphic." as *u8,
218 "Poincare 1895" as *u8)
219 nx_jargon_add(db, "homeomorphism" as *u8, NX_DISC_MATH, NX_TIER_EXPERT,
220 NX_FORM_DEFINITION,
221 "A bijection f: X -> Y between topological spaces such that both f and f^{-1} are continuous." as *u8,
222 "Poincare 1895" as *u8)
223
224 // === Math: group ===
225 nx_jargon_add(db, "group" as *u8, NX_DISC_MATH, NX_TIER_BEGINNER,
226 NX_FORM_METAPHOR,
227 "A collection of things you can combine, where every action can be undone. Like rotating a Rubik's cube: every rotation has a reverse." as *u8,
228 "Cayley 1854" as *u8)
229 nx_jargon_add(db, "group" as *u8, NX_DISC_MATH, NX_TIER_EXPERT,
230 NX_FORM_DEFINITION,
231 "A set G with associative binary op * having identity e and every g in G having an inverse g^-1 with g*g^-1 = e." as *u8,
232 "Cayley 1854" as *u8)
233
234 // === Stats: p-value ===
235 nx_jargon_add(db, "p_value" as *u8, NX_DISC_STATS, NX_TIER_BEGINNER,
236 NX_FORM_METAPHOR,
237 "Probability of seeing data at least this extreme assuming there's actually no effect. Small p-value = either the no-effect hypothesis is wrong OR you got unlucky." as *u8,
238 "Fisher 1925" as *u8)
239 nx_jargon_add(db, "p_value" as *u8, NX_DISC_STATS, NX_TIER_EXPERT,
240 NX_FORM_DEFINITION,
241 "P(T(X) >= t | H_0 true) where T is the test statistic, t the observed value, H_0 the null hypothesis." as *u8,
242 "Fisher 1925 Statistical Methods for Research Workers" as *u8)
243
244 // === CS: type ===
245 nx_jargon_add(db, "type" as *u8, NX_DISC_CS, NX_TIER_BEGINNER,
246 NX_FORM_METAPHOR,
247 "A label on a variable telling what kind of thing it is -- a number, a list, a function -- so the computer can check operations make sense before running." as *u8,
248 "Church 1940 + Curry-Howard correspondence" as *u8)
249 nx_jargon_add(db, "type" as *u8, NX_DISC_CS, NX_TIER_EXPERT,
250 NX_FORM_DEFINITION,
251 "In typed lambda calculus, a syntactic classifier T such that judgement Gamma |- e : T means expression e in context Gamma has type T." as *u8,
252 "Church 1940 + Pierce TAPL 2002" as *u8)
253
254 // === CS: Curry-Howard ===
255 nx_jargon_add(db, "curry_howard" as *u8, NX_DISC_CS, NX_TIER_BEGINNER,
256 NX_FORM_METAPHOR,
257 "A 'proof' and a 'program' are the same thing in disguise. Proving 'A and B' is the same as building a pair (a, b)." as *u8,
258 "Curry 1958 + Howard 1969" as *u8)
259 nx_jargon_add(db, "curry_howard" as *u8, NX_DISC_CS, NX_TIER_EXPERT,
260 NX_FORM_DEFINITION,
261 "Propositions-as-types: each logical proposition corresponds to a type, each proof to a term of that type. Conjunction <-> product, disjunction <-> sum, implication <-> function." as *u8,
262 "Curry 1958 + Howard 1969 + Pierce TAPL 2002" as *u8)
263
264 // === Physics: gauge ===
265 nx_jargon_add(db, "gauge" as *u8, NX_DISC_PHYSICS, NX_TIER_BEGINNER,
266 NX_FORM_METAPHOR,
267 "A choice of 'ruler' or 'reference frame' you can change without affecting the actual physics. Like rotating your coordinate axes -- the laws stay the same." as *u8,
268 "Weyl 1918 + Yang-Mills 1954" as *u8)
269 nx_jargon_add(db, "gauge" as *u8, NX_DISC_PHYSICS, NX_TIER_EXPERT,
270 NX_FORM_DEFINITION,
271 "A principal bundle's local trivialization choice; physically a continuous redundancy in the description of a field theory invariant under local symmetry transformations." as *u8,
272 "Weyl 1918 + Yang-Mills 1954" as *u8)
273
274 // === Math: manifold ===
275 nx_jargon_add(db, "manifold" as *u8, NX_DISC_MATH, NX_TIER_BEGINNER,
276 NX_FORM_METAPHOR,
277 "A space that LOOKS LIKE flat space if you zoom in close enough. Earth's surface looks flat locally even though it's a sphere globally." as *u8,
278 "Riemann 1854" as *u8)
279 nx_jargon_add(db, "manifold" as *u8, NX_DISC_MATH, NX_TIER_EXPERT,
280 NX_FORM_DEFINITION,
281 "A second-countable Hausdorff topological space M with an open cover {U_i} and homeomorphisms phi_i: U_i -> R^n such that transition maps phi_i o phi_j^{-1} are smooth (or C^k, or analytic, depending on the manifold flavor)." as *u8,
282 "Riemann 1854 + Whitney 1936" as *u8)
283
284 // === Math: NP-complete ===
285 nx_jargon_add(db, "np_complete" as *u8, NX_DISC_CS, NX_TIER_BEGINNER,
286 NX_FORM_METAPHOR,
287 "A problem so hard that solving it quickly would solve every other 'hard' problem quickly too. Currently nobody knows how. Examples: scheduling, packing, finding shortest tours." as *u8,
288 "Cook 1971 + Levin 1973" as *u8)
289 nx_jargon_add(db, "np_complete" as *u8, NX_DISC_CS, NX_TIER_EXPERT,
290 NX_FORM_DEFINITION,
291 "A decision problem L is NP-complete iff L is in NP AND every L' in NP polynomial-time reduces to L. The 'hardest' problems in NP." as *u8,
292 "Cook 1971 + Levin 1973 + Karp 1972" as *u8)
293
294 // === Stats: bias-variance ===
295 nx_jargon_add(db, "bias_variance" as *u8, NX_DISC_STATS, NX_TIER_BEGINNER,
296 NX_FORM_METAPHOR,
297 "Two ways an estimator can be wrong: BIAS = systematically off-target on average; VARIANCE = wobbly from sample to sample. Real-world error = both combined." as *u8,
298 "Lehmann-Casella 1998 Theory of Point Estimation" as *u8)
299 nx_jargon_add(db, "bias_variance" as *u8, NX_DISC_STATS, NX_TIER_EXPERT,
300 NX_FORM_FORMULA,
301 "For estimator T-hat of theta: MSE(T-hat) = E[(T-hat - theta)^2] = Var(T-hat) + Bias(T-hat)^2 where Bias = E[T-hat] - theta." as *u8,
302 "Lehmann-Casella 1998" as *u8)
303
304 return db.n_entries
305}