nx_civicmap_lib.nx source
↩ module page · 1069 lines · 52235 B
1// nx_civicmap_lib.nx -- THE CIVIC QUALITY-OF-LIFE MAP, all of its judgement and none of its plumbing.
2// /compare/civicmap rungs CM1 (cm_layer_admit), CM2 (cm_fips_join), CM3 (cm_choropleth_emit) = milestone M0,
3// "one honest layer on a real map". Admitted 2026-08-27; this is the first organ behind those contracts.
4//
5// THE THESIS, and it is the whole reason this organ exists rather than a spreadsheet and a JS map library:
6// 1. A LAYER IS A DATA ADMISSION, NEVER CODE. Source, url, licence, resolution, cadence and mirror are
7// ROWS. cm_layer_admit REFUSES a row that cannot say its licence or name its mirror, and the refusal
8// NAMES THE RULE THAT FIRED -- a count without a worklist is not actionable. Adding a layer is adding
9// data; a bad layer gets better data, never a deletion (rule 25).
10// 2. ABSENCE IS NOT ZERO. The published record this map is built from is riddled with suppression: county
11// death counts under ten are withheld for confidentiality, and the peer-reviewed finding is that
12// ignoring that censoring SYSTEMATICALLY UNDERSTATES rural mortality. A choropleth that paints a
13// suppressed county with the bottom-bucket colour publishes a lie in the safest-looking direction.
14// ★★★★★★ AN UNOBSERVABLE CELL RENDERED AS A NUMBER IS A FALSE MEASUREMENT WITH AN AUTHORITATIVE
15// COLOUR, AND NOBODY AUDITS THE REASSURING END OF A SCALE. So a county with no observation, or a
16// suppressed one, emits data-state='UNOBSERVABLE' WITH A NAMED REASON AND NO data-value AT ALL --
17// structurally incapable of being read as a quantity. That is a machine-checkable contract, and
18// nx_civicmap_gate bites it in both directions.
19// 3. COVERAGE PRINTS BESIDE EVERY FIGURE. counties=, present=, unobservable= and their SUM are emitted
20// on the page and on stdout. A partition is a claim: the parts must sum, and the sum is printed.
21//
22// COMPOSES, NEVER RE-IMPLEMENTS: geo_spatial_join (nx_geo_join, integer-exact point-in-polygon -- the
23// PostGIS ST_Contains staple with no float, so boundary points can be neither dropped nor double-counted)
24// and ep_artifact_path (nx_estate_path -- a verdict that changes with the caller's working directory is
25// not a measurement). Numbers go out through nxi_fd (zero-alloc); file reads compose sys_read_file, which
26// sizes its buffer from the file and CANNOT short-read, so there is no cap here to guess wrong.
27//
28// SCOPE, STATED SO IT CANNOT BE OVERREAD: this organ renders whatever counties are ADMITTED. It has no
29// opinion about national coverage and never claims any -- the count it loaded is the count it prints.
30// Banking the full public-domain TIGER county set is CM2's DATA half and is deliberately not smuggled in
31// here as a hardcoded table.
32//
33// LIBRARY ONLY: there is deliberately NO main() here. The verbs and argv live in nx_civicmap.nx, so
34// nx_civicmap_gate.nx can import THIS file and exercise every rule IN-PROCESS -- no fork, no deployed
35// binary, and therefore no gate that measures a stale artifact instead of the source under test. It is
36// also what lets the mutation harness reach the logic: a rule behind a fork boundary has zero mutation
37// coverage, which is a defect this estate has already paid for and filed.// license_tier: ORIGINAL No hardware writes (Rule 26).
38import "nx_syscalls.nx"
39import "nx_itoa_lib.nx"
40import "nx_estate_path.nx"
41import "nx_geo_join.nx"
42
43const CM_PIPE: i64 = 124
44const CM_NL: i64 = 10
45const CM_DASH: i64 = 45
46const CM_COMMA: i64 = 44
47const CM_SPACE: i64 = 32
48const CM_PATHCAP: i64 = 1024
49const CM_MODE_644: i64 = 420
50const CM_PROVCAP: i64 = 65536
51
52// ---- CM1 admission verdicts. Each is a NAMED rule, so a refusal is a worklist row, not a tally. ----
53const CM_ADMIT: i64 = 0
54const CM_REF_FIELDS: i64 = 1
55const CM_REF_KEY: i64 = 2
56const CM_REF_URL: i64 = 3
57const CM_REF_LICENCE: i64 = 4
58const CM_REF_RES: i64 = 5
59const CM_REF_CADENCE: i64 = 6
60const CM_REF_MIRROR: i64 = 7
61
62// layer row: layer|key|title|url|licence|resolution|cadence|mirror
63const CM_LF_KEY: i64 = 1
64const CM_LF_TITLE: i64 = 2
65const CM_LF_URL: i64 = 3
66const CM_LF_LICENCE: i64 = 4
67const CM_LF_RES: i64 = 5
68const CM_LF_CADENCE: i64 = 6
69const CM_LF_MIRROR: i64 = 7
70const CM_LF_MIN: i64 = 8
71
72// county row: county|fips|name|state|lat,lon lat,lon ...
73const CM_CF_FIPS: i64 = 1
74const CM_CF_NAME: i64 = 2
75const CM_CF_STATE: i64 = 3
76const CM_CF_RING: i64 = 4
77const CM_CF_MIN: i64 = 5
78
79// value row: value|layerkey|fips|<int or SUPPRESSED>
80const CM_VF_LAYER: i64 = 1
81const CM_VF_FIPS: i64 = 2
82const CM_VF_VAL: i64 = 3
83const CM_VF_MIN: i64 = 4
84
85// ---- value states. ABSENT and SUPPRESSED are DIFFERENT REASONS for the SAME refusal to paint a number.
86// Keeping them apart is the point: "nobody measured this" and "it was measured and withheld to protect
87// small counts" demand different remedies, and a single bucket would hide which one you are looking at.
88const CM_V_PRESENT: i64 = 0
89const CM_V_SUPPRESSED: i64 = 1
90const CM_V_ABSENT: i64 = 2
91// ⚠A ROW WAS OFFERED FOR THIS COUNTY AND THIS ORGAN COULD NOT USE IT. That is NOT 'nobody measured
92// this' -- rendering it as no-observation would be a FALSE named reason on the one page whose whole
93// thesis is that an unobservable cell names a TRUE one. It gets its own state and its own words.
94const CM_V_REJECTED: i64 = 3
95
96const CM_BUCKETS: i64 = 5
97// A ring vertex cannot be written in fewer than 4 bytes ("1,1 "), and a county needs its own line, so
98// these two facts SIZE the loader from its input instead of guessing a ceiling. See cm_load_counties.
99const CM_MIN_BYTES_PER_VERTEX: i64 = 4
100const CM_SCRATCH: i64 = 64
101// the county-load context: 6 handles plus rows_seen plus five NAMED drop reasons. Sized as a const so a
102// caller cannot under-allocate it -- the previous version handed this function a 64-byte scratch.
103const CM_CTX_BYTES: i64 = 128
104const CM_CTX_NC: i64 = 4
105const CM_CTX_POOLUSED: i64 = 5
106const CM_CTX_SEEN: i64 = 6
107const CM_CTX_D_SHAPE: i64 = 7
108const CM_CTX_D_FIPS: i64 = 8
109const CM_CTX_D_RING: i64 = 9
110const CM_CTX_D_SHORT: i64 = 10
111const CM_CTX_D_CAP: i64 = 11
112const CM_H: i64 = 900
113const CM_ASPECT_NUM: i64 = 780
114const CM_ASPECT_DEN: i64 = 1000
115const CM_W_MIN: i64 = 200
116const CM_W_MAX: i64 = 2400
117
118func cm_w(fd: i64, s: *u8) -> i64 { var n: i64 = 0; while s[n] != (0 as u8) { n = n + 1 } sys_write(fd, s, n); return 0 }
119func cm_n(fd: i64, v: i64) -> i64 { nxi_fd(fd, v); return 0 }
120func cm_span(fd: i64, buf: *u8, s: i64, e: i64) -> i64 {
121 if e > s { sys_write(fd, ((buf as i64) + s) as *u8, e - s) }
122 return 0
123}
124
125// scan to the next delimiter. A SEPARATE cursor and an explicit flag: writing the loop-exit into the
126// cursor itself (i = lim) destroys the answer the caller needs, and this estate has written that bug
127// four times in one day.
128func cm_to(buf: *u8, i: i64, lim: i64, d: i64) -> i64 {
129 var e: i64 = i
130 var go: i64 = 1
131 while go == 1 {
132 if e >= lim { go = 0 } else {
133 if buf[e] == (d as u8) { go = 0 } else { e = e + 1 }
134 }
135 }
136 return e
137}
138
139func cm_nfields(buf: *u8, s: i64, e: i64) -> i64 {
140 var c: i64 = 1
141 var p: i64 = s
142 while p < e {
143 if buf[p] == (CM_PIPE as u8) { c = c + 1 }
144 p = p + 1
145 }
146 return c
147}
148
149// field `idx` of a pipe row into out[0]=start out[1]=end. 1 found, 0 absent. The caller owns `out`:
150// allocating scratch per call would leak a page per row, the defect that took 28.5 GB of a 36 GB host.
151func cm_fld(buf: *u8, s: i64, e: i64, idx: i64, out: *i64) -> i64 {
152 var k: i64 = 0
153 var p: i64 = s
154 while k < idx {
155 let q: i64 = cm_to(buf, p, e, CM_PIPE)
156 if q >= e { return 0 }
157 p = q + 1
158 k = k + 1
159 }
160 out[0] = p
161 out[1] = cm_to(buf, p, e, CM_PIPE)
162 return 1
163}
164
165// empty, blank, or the explicit placeholder '-'. A placeholder is an ABSENT value that looks present,
166// which is exactly the shape this whole organ refuses.
167func cm_empty(buf: *u8, s: i64, e: i64) -> i64 {
168 if e <= s { return 1 }
169 var i: i64 = s
170 var seen: i64 = 0
171 while i < e {
172 if buf[i] != (CM_SPACE as u8) { seen = seen + 1 }
173 i = i + 1
174 }
175 if seen == 0 { return 1 }
176 if e - s == 1 { if buf[s] == (CM_DASH as u8) { return 1 } }
177 return 0
178}
179
180func cm_starts(buf: *u8, s: i64, e: i64, lit: *u8) -> i64 {
181 var i: i64 = 0
182 while lit[i] != (0 as u8) {
183 if s + i >= e { return 0 }
184 if buf[s + i] != lit[i] { return 0 }
185 i = i + 1
186 }
187 return 1
188}
189
190func cm_eqlit(buf: *u8, s: i64, e: i64, lit: *u8) -> i64 {
191 if cm_starts(buf, s, e, lit) == 0 { return 0 }
192 var i: i64 = 0
193 while lit[i] != (0 as u8) { i = i + 1 }
194 if s + i != e { return 0 }
195 return 1
196}
197
198func cm_int(buf: *u8, s: i64, e: i64) -> i64 {
199 var neg: i64 = 0
200 var i: i64 = s
201 if s < e { if buf[s] == (CM_DASH as u8) { neg = 1; i = s + 1 } }
202 var v: i64 = 0
203 while i < e {
204 if buf[i] >= (48 as u8) { if buf[i] <= (57 as u8) { v = v * 10 + (buf[i] as i64 - 48) } }
205 i = i + 1
206 }
207 if neg == 1 { return 0 - v }
208 return v
209}
210
211// =====================================================================================================
212// CM1 -- cm_layer_admit. THE REFUSING DOOR. Returns CM_ADMIT or the NAMED rule that refused the row.
213// Order is deliberate: shape first (a malformed row cannot be interrogated), then the two fields whose
214// absence makes the layer unusable at all (licence, mirror), then the two that make it unreadable
215// (resolution, cadence). Every rule is independently checkable and every refusal is one row of work.
216// =====================================================================================================
217func cm_layer_admit(buf: *u8, s: i64, e: i64, f: *i64) -> i64 {
218 if cm_nfields(buf, s, e) < CM_LF_MIN { return CM_REF_FIELDS }
219 if cm_fld(buf, s, e, CM_LF_KEY, f) == 0 { return CM_REF_KEY }
220 if cm_empty(buf, f[0], f[1]) == 1 { return CM_REF_KEY }
221 if cm_fld(buf, s, e, CM_LF_URL, f) == 0 { return CM_REF_URL }
222 if cm_starts(buf, f[0], f[1], "http" as *u8) == 0 { return CM_REF_URL }
223 if cm_fld(buf, s, e, CM_LF_LICENCE, f) == 0 { return CM_REF_LICENCE }
224 if cm_empty(buf, f[0], f[1]) == 1 { return CM_REF_LICENCE }
225 if cm_eqlit(buf, f[0], f[1], "UNKNOWN" as *u8) == 1 { return CM_REF_LICENCE }
226 if cm_fld(buf, s, e, CM_LF_RES, f) == 0 { return CM_REF_RES }
227 if cm_empty(buf, f[0], f[1]) == 1 { return CM_REF_RES }
228 if cm_fld(buf, s, e, CM_LF_CADENCE, f) == 0 { return CM_REF_CADENCE }
229 if cm_empty(buf, f[0], f[1]) == 1 { return CM_REF_CADENCE }
230 if cm_fld(buf, s, e, CM_LF_MIRROR, f) == 0 { return CM_REF_MIRROR }
231 if cm_empty(buf, f[0], f[1]) == 1 { return CM_REF_MIRROR }
232 return CM_ADMIT
233}
234
235// THE REASON TRAVELS WITH THE COUNT. A verdict code nobody can read is a tally.
236func cm_refuse_name(code: i64) -> *u8 {
237 if code == CM_ADMIT { return "ADMIT" as *u8 }
238 if code == CM_REF_FIELDS { return "REFUSED-SHAPE (fewer than 8 pipe fields -- a layer row that cannot be parsed cannot be admitted)" as *u8 }
239 if code == CM_REF_KEY { return "REFUSED-KEY (no layer key -- nothing to cite it by)" as *u8 }
240 if code == CM_REF_URL { return "REFUSED-URL (source url absent or not http -- an unciteable source)" as *u8 }
241 if code == CM_REF_LICENCE { return "REFUSED-LICENCE (absent, placeholder or UNKNOWN -- we do not publish data whose terms we cannot state)" as *u8 }
242 if code == CM_REF_RES { return "REFUSED-RESOLUTION (no declared geographic resolution -- a layer that cannot say what a cell means)" as *u8 }
243 if code == CM_REF_CADENCE { return "REFUSED-CADENCE (no declared update cadence -- freshness would be unstatable on the page)" as *u8 }
244 if code == CM_REF_MIRROR { return "REFUSED-MIRROR (no evidence mirror -- an unmirrored source is a link that will rot)" as *u8 }
245 return "REFUSED-UNKNOWN-RULE" as *u8
246}
247
248// =====================================================================================================
249// CM2 -- cm_fips_join. Point rows to county rows, composing the integer-exact spatial join.
250// Returns the number of points that LANDED in a county; the caller prints it beside the total, because
251// an unjoined point is not a zero, it is a point outside the loaded coverage.
252// =====================================================================================================
253func cm_fips_parse(buf: *u8, s: i64, e: i64) -> i64 {
254 if e <= s { return 0 - 1 }
255 var i: i64 = s
256 while i < e {
257 if buf[i] < (48 as u8) { return 0 - 1 }
258 if buf[i] > (57 as u8) { return 0 - 1 }
259 i = i + 1
260 }
261 return cm_int(buf, s, e)
262}
263
264func cm_fips_index(fipstab: *i64, ncounty: i64, fips: i64) -> i64 {
265 var i: i64 = 0
266 while i < ncounty {
267 if fipstab[i] == fips { return i }
268 i = i + 1
269 }
270 return 0 - 1
271}
272
273func cm_fips_join(pts: *i64, npts: i64, pool: *i64, off: *i64, cnt: *i64, npolys: i64, fipstab: *i64, out: *i64) -> i64 {
274 if npts <= 0 { return 0 }
275 let idx: *i64 = sys_mmap(8 * npts) as *i64
276 geo_spatial_join(pts, npts, pool, off, cnt, npolys, idx)
277 var i: i64 = 0
278 var hit: i64 = 0
279 while i < npts {
280 let p: i64 = idx[i]
281 if p < 0 { out[i] = 0 - 1 } else {
282 out[i] = fipstab[p]
283 hit = hit + 1
284 }
285 i = i + 1
286 }
287 sys_munmap(idx as *u8, 8 * npts)
288 return hit
289}
290
291// =====================================================================================================
292// CM3 -- cm_choropleth_emit. The map, emitted natively: our own projection, our own SVG, no third-party
293// map library anywhere in the chain and no client-side logic that decides anything.
294// =====================================================================================================
295// integer equirectangular projection, guarded: a zero range would divide by zero and take the process
296// with it, so a degenerate bbox is widened to one microdegree rather than trusted.
297func cm_px(lon: i64, lonmin: i64, lonrange: i64, w: i64) -> i64 {
298 var r: i64 = lonrange
299 if r <= 0 { r = 1 }
300 return (lon - lonmin) * w / r
301}
302
303func cm_py(lat: i64, latmax: i64, latrange: i64, h: i64) -> i64 {
304 var r: i64 = latrange
305 if r <= 0 { r = 1 }
306 return (latmax - lat) * h / r
307}
308
309func cm_bucket(v: i64, lo: i64, hi: i64) -> i64 {
310 if hi <= lo { return 0 }
311 var b: i64 = (v - lo) * CM_BUCKETS / (hi - lo)
312 if b < 0 { b = 0 }
313 if b >= CM_BUCKETS { b = CM_BUCKETS - 1 }
314 return b
315}
316
317// a sequential ramp for measured values, and ONE colour that is not on that ramp for the unobservable.
318// The unobservable colour is deliberately outside the sequence: a reader must not be able to place it
319// at either end of the scale by eye.
320func cm_color(b: i64) -> *u8 {
321 if b == 0 { return "rgb(222,235,247)" as *u8 }
322 if b == 1 { return "rgb(158,202,225)" as *u8 }
323 if b == 2 { return "rgb(66,146,198)" as *u8 }
324 if b == 3 { return "rgb(33,89,152)" as *u8 }
325 return "rgb(8,48,107)" as *u8
326}
327
328func cm_state_name(st: i64) -> *u8 {
329 if st == CM_V_PRESENT { return "PRESENT" as *u8 }
330 return "UNOBSERVABLE" as *u8
331}
332
333func cm_state_reason(st: i64) -> *u8 {
334 if st == CM_V_SUPPRESSED { return "suppressed-small-count" as *u8 }
335 if st == CM_V_REJECTED { return "observation-offered-but-unreadable" as *u8 }
336 return "no-observation" as *u8
337}
338
339// one county polygon as an SVG path. THE CONTRACT THE GATE BITES: a PRESENT county carries data-value,
340// an UNOBSERVABLE one carries data-reason and NO data-value at all -- so an absent measurement is
341// structurally incapable of being read as a quantity by anything downstream, human or machine.
342func cm_emit_poly(fd: i64, pool: *i64, base: i64, npts: i64, pj: *i64, fips: i64, val: i64, st: i64) -> i64 {
343 if npts < 3 { return 0 }
344 cm_w(fd, "<path class='c' data-fips='" as *u8)
345 cm_n(fd, fips)
346 cm_w(fd, "' data-state='" as *u8)
347 cm_w(fd, cm_state_name(st))
348 if st == CM_V_PRESENT {
349 cm_w(fd, "' data-value='" as *u8)
350 cm_n(fd, val)
351 } else {
352 cm_w(fd, "' data-reason='" as *u8)
353 cm_w(fd, cm_state_reason(st))
354 }
355 cm_w(fd, "' fill='" as *u8)
356 if st == CM_V_PRESENT {
357 cm_w(fd, cm_color(cm_bucket(val, pj[6], pj[7])))
358 } else {
359 cm_w(fd, "url(#cm-unobs)" as *u8)
360 }
361 cm_w(fd, "' d='M" as *u8)
362 var k: i64 = 0
363 while k < npts {
364 if k > 0 { cm_w(fd, "L" as *u8) }
365 cm_n(fd, cm_px(pool[(base + k) * 2 + 1], pj[0], pj[2], pj[4]))
366 cm_w(fd, " " as *u8)
367 cm_n(fd, cm_py(pool[(base + k) * 2], pj[1], pj[3], pj[5]))
368 cm_w(fd, " " as *u8)
369 k = k + 1
370 }
371 cm_w(fd, "Z'/>\n" as *u8)
372 return 1
373}
374
375// The whole page. Returns the number of counties drawn, or a negative code on failure.
376// pj = [lonmin, latmax, lonrange, latrange, W, H, vlo, vhi].
377func cm_choropleth_emit(outpath: *u8, pool: *i64, off: *i64, cnt: *i64, fipstab: *i64, val: *i64, st: *i64, npolys: i64, pj: *i64, title: *u8, prov: *u8, provn: i64) -> i64 {
378 let fd: i64 = sys_openat_wr(outpath, CM_MODE_644)
379 if fd < 0 { return 0 - 1 }
380 let w: i64 = pj[4]
381 let h: i64 = pj[5]
382 cm_w(fd, "<!DOCTYPE html>\n<html lang='en'><head><meta charset='utf-8'><meta name='viewport' content='width=device-width, initial-scale=1'><title>Nishi Civic Map</title>\n" as *u8)
383 cm_w(fd, "<style>body{font-family:-apple-system,Segoe UI,Roboto,sans-serif;margin:0;background:rgb(10,15,30);color:rgb(219,227,242)}header{padding:16px 22px}h1{margin:0;font-size:1.3rem}.tag{color:rgb(129,144,181);font-size:.9rem;margin-top:4px;max-width:60rem;line-height:1.5}main{padding:0 22px 22px}svg{width:100%;height:auto;background:rgb(10,15,30);border:1px solid rgb(28,41,80);border-radius:8px}.c{stroke:rgb(10,15,30);stroke-width:1}.key{display:flex;gap:14px;flex-wrap:wrap;align-items:center;margin:14px 0;font-size:.8rem;color:rgb(160,175,208)}.sw{display:inline-block;width:15px;height:15px;border-radius:3px;vertical-align:-3px;margin-right:5px}table{border-collapse:collapse;font-size:.78rem;margin-top:8px}th,td{border:1px solid rgb(28,41,80);padding:5px 9px;text-align:left;color:rgb(190,203,229)}th{color:rgb(226,234,248)}.foot{font-size:.78rem;color:rgb(122,138,175);max-width:64rem;line-height:1.6}code{color:rgb(159,176,214)}</style></head><body>\n" as *u8)
384 cm_w(fd, "<header><h1>" as *u8)
385 cm_w(fd, title)
386 cm_w(fd, "</h1><div class='tag'>Rendered natively by <code>nx_civicmap</code>: integer-exact projection and our own SVG. No Leaflet, Mapbox, Google or any third-party map library, and no client-side code that decides anything.</div></header>\n<main>\n" as *u8)
387 cm_w(fd, "<svg viewBox='0 0 " as *u8)
388 cm_n(fd, w)
389 cm_w(fd, " " as *u8)
390 cm_n(fd, h)
391 cm_w(fd, "' xmlns='http://www.w3.org/2000/svg'>\n<defs><pattern id='cm-unobs' width='7' height='7' patternUnits='userSpaceOnUse' patternTransform='rotate(45)'><rect width='7' height='7' fill='rgb(52,59,76)'/><line x1='0' y1='0' x2='0' y2='7' stroke='rgb(96,105,128)' stroke-width='2.5'/></pattern></defs>\n" as *u8)
392 var drawn: i64 = 0
393 var present: i64 = 0
394 var unobs: i64 = 0
395 var p: i64 = 0
396 while p < npolys {
397 if cm_emit_poly(fd, pool, off[p], cnt[p], pj, fipstab[p], val[p], st[p]) == 1 {
398 drawn = drawn + 1
399 if st[p] == CM_V_PRESENT { present = present + 1 } else { unobs = unobs + 1 }
400 }
401 p = p + 1
402 }
403 cm_w(fd, "</svg>\n" as *u8)
404 cm_w(fd, "<div class='key'><span><span class='sw' style='background:rgb(222,235,247)'></span>low</span><span><span class='sw' style='background:rgb(8,48,107)'></span>high</span><span><span class='sw' style='background:rgb(52,59,76)'></span>UNOBSERVABLE — suppressed or unmeasured, never painted as a value</span></div>\n" as *u8)
405 // COVERAGE PRINTS BESIDE THE MAP, AND THE PARTITION SUMS. A figure whose denominator is off the page
406 // is a figure the reader cannot judge.
407 cm_w(fd, "<table><tr><th>counties drawn</th><th>PRESENT</th><th>UNOBSERVABLE</th><th>parts sum</th></tr><tr><td>" as *u8)
408 cm_n(fd, drawn)
409 cm_w(fd, "</td><td>" as *u8)
410 cm_n(fd, present)
411 cm_w(fd, "</td><td>" as *u8)
412 cm_n(fd, unobs)
413 cm_w(fd, "</td><td>" as *u8)
414 if present + unobs == drawn { cm_w(fd, "OK" as *u8) } else { cm_w(fd, "LEAK" as *u8) }
415 cm_w(fd, "</td></tr></table>\n" as *u8)
416 if provn > 0 { sys_write(fd, prov, provn) }
417 cm_w(fd, "<p class='foot'>This map renders exactly the counties admitted into it and claims no coverage beyond them — the count above is the count loaded. An UNOBSERVABLE cell carries a named reason and no value: county statistics are routinely suppressed at small counts, and painting a suppressed county with the bottom colour would publish a false measurement in the most reassuring direction. Every layer above names its licence, resolution, cadence and evidence mirror, because a layer that cannot say those things is refused at the door.</p>\n" as *u8)
418 cm_w(fd, "</main></body></html>\n" as *u8)
419 sys_close(fd)
420 if present + unobs != drawn { return 0 - 2 }
421 return drawn
422}
423
424// =====================================================================================================
425// LOADERS
426// =====================================================================================================
427// parse a ring 'lat,lon lat,lon ...' into pool at *pooln (pairs). Returns the vertex count.
428// BOUNDED AT THE WRITE, not at the caller: an earlier draft of this checked the cap AFTER parsing,
429// which is a check that runs once the overrun has already happened. A cap that is verified after the
430// write is not a cap. Vertices past the pool are DROPPED and the shortfall is visible to the caller as
431// a ring too short to admit, so truncation can never quietly become a smaller, valid-looking polygon.
432func cm_parse_ring(buf: *u8, s: i64, e: i64, pool: *i64, pooln: *i64, maxpts: i64) -> i64 {
433 var p: i64 = s
434 var n: i64 = 0
435 while p < e {
436 let sp: i64 = cm_to(buf, p, e, CM_SPACE)
437 let cm: i64 = cm_to(buf, p, sp, CM_COMMA)
438 if cm < sp {
439 let base: i64 = pooln[0] + n
440 if base >= maxpts { return 0 - 1 }
441 pool[base * 2] = cm_int(buf, p, cm)
442 pool[base * 2 + 1] = cm_int(buf, cm + 1, sp)
443 n = n + 1
444 }
445 p = sp + 1
446 }
447 return n
448}
449
450// bounded append. Returns the new offset; refuses to write past cap rather than trusting the caller's
451// arithmetic. The provenance block grows with the number of admitted layers, which is DATA -- so its
452// buffer is a bound that must hold for any conf, not for the conf that happened to exist today.
453func cm_cat(d: *u8, o: i64, s: *u8, cap: i64) -> i64 {
454 var p: i64 = o
455 var i: i64 = 0
456 while s[i] != (0 as u8) {
457 if p >= cap { return p }
458 d[p] = s[i]
459 p = p + 1
460 i = i + 1
461 }
462 return p
463}
464
465func cm_cat_span(d: *u8, o: i64, src: *u8, s: i64, e: i64, cap: i64) -> i64 {
466 var p: i64 = o
467 var i: i64 = s
468 while i < e {
469 if p >= cap { return p }
470 d[p] = src[i]
471 p = p + 1
472 i = i + 1
473 }
474 return p
475}
476
477// ---- county loader shared by join and emit ----------------------------------------------------------
478// ctx: [0]=pool [1]=off [2]=cnt [3]=fips [4]=ncounty [5]=poolused [6]=rows_seen
479// [7]=drop_shape [8]=drop_fips [9]=drop_ring_absent [10]=drop_ring_short [11]=drop_capacity
480//
481// ★★★★★★ THE CAPS ARE DERIVED FROM THE INPUT, NOT GUESSED -- AND THAT IS THE BUG FIX, NOT A TUNING.
482// The first version of this loader carried CM_MAXPTS=4096 and CM_MAXCOUNTY=4096 and dropped any county
483// that did not fit SILENTLY, through five nested ifs whose every failing branch simply skipped the row.
484// A national county bank is roughly 3,144 counties of tens to hundreds of vertices each, so that ceiling
485// would have discarded most of the country WHILE THE MAP STILL RENDERED AND STILL LOOKED CORRECT -- the
486// exact shape of "a cap reached in silence becomes a measurement nobody knows is partial", committed in
487// a file whose own header preaches coverage honesty. Raising the number would only have moved the guess.
488// A ring vertex cannot be written in fewer than 4 bytes ("1,1 ") and a county needs its own line, so a
489// file of n bytes can describe no more than n/4 vertices and no more counties than it has lines. Sizing
490// from those two facts makes overflow IMPOSSIBLE BY CONSTRUCTION rather than merely detected. The
491// capacity counter below is kept anyway as a NAMED axis: if that arithmetic is ever wrong I want it
492// loud, not silent. Physical pages fault in on demand, so the headroom costs address space, not memory.
493//
494// EVERY DROP IS COUNTED AND NAMED, and the partition must sum: seen = loaded + the five reasons. The
495// reasons are kept apart because they demand different remedies -- a malformed row is an editing error,
496// an unparseable FIPS is a bad key, a degenerate ring is bad geometry, and a capacity drop would be a
497// defect in this function. One bucket would have hidden which one you were looking at.
498func cm_count_lines(buf: *u8, n: i64) -> i64 {
499 var c: i64 = 1
500 var i: i64 = 0
501 while i < n {
502 if buf[i] == (CM_NL as u8) { c = c + 1 }
503 i = i + 1
504 }
505 return c
506}
507
508func cm_load_counties(path: *u8, ctx: *i64) -> i64 {
509 var z: i64 = 0
510 while z < 12 { ctx[z] = 0; z = z + 1 }
511 let ap: *u8 = sys_mmap(CM_PATHCAP)
512 if ep_artifact_path(ap, path) == 0 { return 0 - 3 }
513 let ln: *i64 = sys_mmap(8) as *i64
514 let buf: *u8 = sys_read_file(ap, ln)
515 let n: i64 = ln[0]
516 if n <= 0 { return 0 - 3 }
517 let maxpts: i64 = n / CM_MIN_BYTES_PER_VERTEX + 1
518 let maxcty: i64 = cm_count_lines(buf, n)
519 let pool: *i64 = sys_mmap(8 * 2 * maxpts) as *i64
520 let off: *i64 = sys_mmap(8 * maxcty) as *i64
521 let cnt: *i64 = sys_mmap(8 * maxcty) as *i64
522 let fips: *i64 = sys_mmap(8 * maxcty) as *i64
523 let pooln: *i64 = sys_mmap(8) as *i64
524 pooln[0] = 0
525 let f: *i64 = sys_mmap(CM_SCRATCH) as *i64
526 var nc: i64 = 0
527 var seen: i64 = 0
528 var d_shape: i64 = 0
529 var d_fips: i64 = 0
530 var d_ring: i64 = 0
531 var d_short: i64 = 0
532 var d_cap: i64 = 0
533 var p: i64 = 0
534 while p < n {
535 let le: i64 = cm_to(buf, p, n, CM_NL)
536 if le > p {
537 if cm_starts(buf, p, le, "county|" as *u8) == 1 {
538 seen = seen + 1
539 var done: i64 = 0
540 if cm_nfields(buf, p, le) < CM_CF_MIN {
541 d_shape = d_shape + 1
542 done = 1
543 }
544 if done == 0 {
545 if nc >= maxcty {
546 d_cap = d_cap + 1
547 done = 1
548 }
549 }
550 var fp: i64 = 0 - 1
551 if done == 0 {
552 if cm_fld(buf, p, le, CM_CF_FIPS, f) == 1 { fp = cm_fips_parse(buf, f[0], f[1]) }
553 if fp < 0 {
554 d_fips = d_fips + 1
555 done = 1
556 }
557 }
558 if done == 0 {
559 if cm_fld(buf, p, le, CM_CF_RING, f) == 0 {
560 d_ring = d_ring + 1
561 done = 1
562 }
563 }
564 if done == 0 {
565 let base: i64 = pooln[0]
566 let k: i64 = cm_parse_ring(buf, f[0], f[1], pool, pooln, maxpts)
567 if k < 0 { d_cap = d_cap + 1 } else {
568 if k < 3 { d_short = d_short + 1 } else {
569 off[nc] = base
570 cnt[nc] = k
571 fips[nc] = fp
572 pooln[0] = base + k
573 nc = nc + 1
574 }
575 }
576 }
577 }
578 }
579 p = le + 1
580 }
581 ctx[0] = pool as i64
582 ctx[1] = off as i64
583 ctx[2] = cnt as i64
584 ctx[3] = fips as i64
585 ctx[CM_CTX_NC] = nc
586 ctx[CM_CTX_POOLUSED] = pooln[0]
587 ctx[CM_CTX_SEEN] = seen
588 ctx[CM_CTX_D_SHAPE] = d_shape
589 ctx[CM_CTX_D_FIPS] = d_fips
590 ctx[CM_CTX_D_RING] = d_ring
591 ctx[CM_CTX_D_SHORT] = d_short
592 ctx[CM_CTX_D_CAP] = d_cap
593 return nc
594}
595
596// ONE reporter for every caller, so coverage is printed identically everywhere and cannot drift between
597// the join lane and the emit lane. Returns 1 when the partition sums, 0 when it leaks -- and a partition
598// that does not sum is a leak, not a rounding detail.
599func cm_load_report(fd: i64, ctx: *i64) -> i64 {
600 let seen: i64 = ctx[CM_CTX_SEEN]
601 let sum: i64 = ctx[CM_CTX_NC] + ctx[CM_CTX_D_SHAPE] + ctx[CM_CTX_D_FIPS] + ctx[CM_CTX_D_RING] + ctx[CM_CTX_D_SHORT] + ctx[CM_CTX_D_CAP]
602 cm_w(fd, " counties seen=" as *u8)
603 cm_n(fd, seen)
604 cm_w(fd, " loaded=" as *u8)
605 cm_n(fd, ctx[CM_CTX_NC])
606 cm_w(fd, " dropped_shape=" as *u8)
607 cm_n(fd, ctx[CM_CTX_D_SHAPE])
608 cm_w(fd, " dropped_fips=" as *u8)
609 cm_n(fd, ctx[CM_CTX_D_FIPS])
610 cm_w(fd, " dropped_ring_absent=" as *u8)
611 cm_n(fd, ctx[CM_CTX_D_RING])
612 cm_w(fd, " dropped_ring_short=" as *u8)
613 cm_n(fd, ctx[CM_CTX_D_SHORT])
614 cm_w(fd, " dropped_capacity=" as *u8)
615 cm_n(fd, ctx[CM_CTX_D_CAP])
616 cm_w(fd, " vertices=" as *u8)
617 cm_n(fd, ctx[CM_CTX_POOLUSED])
618 cm_w(fd, " parts_sum=" as *u8)
619 if sum == seen {
620 cm_w(fd, "OK\n" as *u8)
621 return 1
622 }
623 cm_w(fd, "LEAK\n" as *u8)
624 return 0
625}
626
627// equality of two byte spans that may live in DIFFERENT buffers -- an axis key declared in the spec file
628// versus the same key written in an observation row. cm_eqlit compares against a NUL-terminated literal
629// and structurally cannot answer this, so reaching for it here would have silently compared the wrong
630// thing. Length first: two spans of different length are never equal and the loop must not run.
631func cm_eqspan(a: *u8, a0: i64, a1: i64, b: *u8, b0: i64, b1: i64) -> i64 {
632 if a1 - a0 != b1 - b0 { return 0 }
633 var i: i64 = 0
634 while a0 + i < a1 {
635 if a[a0 + i] != b[b0 + i] { return 0 }
636 i = i + 1
637 }
638 return 1
639}
640// =====================================================================================================
641// CM11 -- cm_qol_index. THE COMPOSITE SCORE THAT ALWAYS CARRIES ITS DENOMINATOR.
642// =====================================================================================================
643// Composite county indices are the most quietly dishonest object in civic data. A county measured on
644// nine axes and a county measured on two get printed as the same kind of number, ranked against each
645// other, and the reader is never told which is which -- so the county with the least data is the one
646// whose rank is most confidently wrong. County Health Rankings publishes a rank; it does not publish,
647// per county, how much of the instrument was actually observed.
648//
649// ★★★★★★ A SCORE WITHOUT ITS DENOMINATOR IS NOT A MEASUREMENT, IT IS AN OPINION WITH A NUMBER ON IT.
650// So this index refuses to produce a bare scalar. Every county's result carries:
651// * observed / declared -- how much of the instrument reached this county AT ALL
652// * the decomposition -- every axis that contributed, its raw value and its signed contribution,
653// so the score can be taken apart by anyone who doubts it
654// * UNOBSERVABLE -- when nothing was observed, which is NOT a zero and never ranks
655// A missing axis is DROPPED FROM THE DENOMINATOR, never imputed and never treated as zero: imputing a
656// missing axis invents data, and scoring it zero punishes a county for not being measured. Both are
657// ways of turning "we do not know" into a number, which is the one thing this board exists to refuse.
658//
659// DIRECTION IS DECLARED PER AXIS, NOT ASSUMED. Bridges in poor condition and jobs per capita move the
660// opposite way; an index that hardcodes "bigger is better" silently inverts half its inputs.
661// Rows (DATA, never code):
662// axis|<key>|<title>|<dir higher|lower>|<weight>
663// obs|<fips>|<axiskey>|<value_permil 0..1000>
664const CM_AX_KEY: i64 = 1
665const CM_AX_TITLE: i64 = 2
666const CM_AX_DIR: i64 = 3
667const CM_AX_WEIGHT: i64 = 4
668const CM_AX_MIN: i64 = 5
669const CM_OB_FIPS: i64 = 1
670const CM_OB_AXIS: i64 = 2
671const CM_OB_VAL: i64 = 3
672const CM_OB_MIN: i64 = 4
673const CM_DIR_HIGHER: i64 = 0
674const CM_DIR_LOWER: i64 = 1
675const CM_PERMIL: i64 = 1000
676// the index context: [0]=score_permil [1]=observed [2]=declared [3]=weight_seen [4]=measured(1/0)
677const CM_IX_SCORE: i64 = 0
678const CM_IX_OBSERVED: i64 = 1
679const CM_IX_DECLARED: i64 = 2
680const CM_IX_WEIGHT: i64 = 3
681const CM_IX_MEASURED: i64 = 4
682const CM_IX_BADAXIS: i64 = 5
683const CM_IX_SLOTS: i64 = 8
684const CM_IX_BYTES: i64 = 64
685
686// orient one raw permil reading so that HIGHER always means BETTER, per the axis's declared direction.
687// Pure and total: every input in 0..1000 maps into 0..1000, and out-of-range readings are clamped rather
688// than allowed to drag a score outside the scale they are printed on.
689func cm_orient(v: i64, dir: i64) -> i64 {
690 var x: i64 = v
691 if x < 0 { x = 0 }
692 if x > CM_PERMIL { x = CM_PERMIL }
693 if dir == CM_DIR_LOWER { return CM_PERMIL - x }
694 return x
695}
696
697// THE INDEX. Returns 1 MEASURED, 0 UNOBSERVABLE (no axis reached this county -- not a zero score).
698// out[] carries the score AND the denominator, because they must never travel apart.
699// The weighted mean is taken over the OBSERVED axes only: sum(w*oriented)/sum(w).
700func cm_qol_index(abuf: *u8, an: i64, obuf: *u8, on: i64, fips: i64, f: *i64, out: *i64) -> i64 {
701 var i: i64 = 0
702 while i < CM_IX_SLOTS { out[i] = 0; i = i + 1 }
703 var declared: i64 = 0
704 var badaxis: i64 = 0
705 var observed: i64 = 0
706 var wsum: i64 = 0
707 var acc: i64 = 0
708 var p: i64 = 0
709 while p < an {
710 let le: i64 = cm_to(abuf, p, an, CM_NL)
711 if le > p {
712 if cm_starts(abuf, p, le, "axis|" as *u8) == 1 {
713 if cm_nfields(abuf, p, le) >= CM_AX_MIN {
714 declared = declared + 1
715 // this axis's key, direction and weight
716 var dir: i64 = CM_DIR_HIGHER
717 var w: i64 = 1
718 var ks: i64 = 0
719 var ke: i64 = 0
720 if cm_fld(abuf, p, le, CM_AX_KEY, f) == 1 {
721 ks = f[0]
722 ke = f[1]
723 }
724 // ⚠FAIL CLOSED ON AN UNRECOGNISED DIRECTION. The first version tested only for
725 // "lower" and let everything else fall through to higher-is-better -- so "Lower",
726 // a trailing space, a typo or an ABSENT field would silently INVERT that axis's
727 // contribution to every county, which is precisely what the section comment above
728 // says this design exists to prevent. Same class as a routing mode that defaults to
729 // the permissive value on an unknown token: an unknown token must REFUSE.
730 // A refused axis is DROPPED from `declared` and counted under its own reason, so it
731 // cannot quietly widen or narrow anyone's denominator either.
732 var dirok: i64 = 0
733 if cm_fld(abuf, p, le, CM_AX_DIR, f) == 1 {
734 if cm_eqlit(abuf, f[0], f[1], "lower" as *u8) == 1 { dir = CM_DIR_LOWER; dirok = 1 }
735 if cm_eqlit(abuf, f[0], f[1], "higher" as *u8) == 1 { dir = CM_DIR_HIGHER; dirok = 1 }
736 }
737 if dirok == 0 {
738 declared = declared - 1
739 badaxis = badaxis + 1
740 }
741 if cm_fld(abuf, p, le, CM_AX_WEIGHT, f) == 1 {
742 let ww: i64 = cm_int(abuf, f[0], f[1])
743 if ww > 0 { w = ww }
744 }
745 // find THIS county's observation on THIS axis, if there is one
746 var found: i64 = 0
747 var raw: i64 = 0
748 var q: i64 = 0
749 while q < on {
750 let oe: i64 = cm_to(obuf, q, on, CM_NL)
751 if oe > q {
752 if found == 0 {
753 if cm_starts(obuf, q, oe, "obs|" as *u8) == 1 {
754 if cm_nfields(obuf, q, oe) >= CM_OB_MIN {
755 var same: i64 = 0
756 if cm_fld(obuf, q, oe, CM_OB_FIPS, f) == 1 {
757 if cm_fips_parse(obuf, f[0], f[1]) == fips { same = 1 }
758 }
759 if same == 1 {
760 var akey: i64 = 0
761 if cm_fld(obuf, q, oe, CM_OB_AXIS, f) == 1 {
762 if cm_eqspan(obuf, f[0], f[1], abuf, ks, ke) == 1 { akey = 1 }
763 }
764 if akey == 1 {
765 if cm_fld(obuf, q, oe, CM_OB_VAL, f) == 1 {
766 if cm_empty(obuf, f[0], f[1]) == 0 {
767 raw = cm_int(obuf, f[0], f[1])
768 found = 1
769 }
770 }
771 }
772 }
773 }
774 }
775 }
776 }
777 q = oe + 1
778 }
779 // AN AXIS THAT DID NOT REACH THIS COUNTY LEAVES THE DENOMINATOR ALTOGETHER.
780 // It is not imputed (that invents data) and not scored zero (that punishes a county
781 // for not being measured). It is simply absent, and the printed denominator says so.
782 if found == 1 {
783 if dirok == 1 {
784 observed = observed + 1
785 wsum = wsum + w
786 acc = acc + w * cm_orient(raw, dir)
787 }
788 }
789 }
790 }
791 }
792 p = le + 1
793 }
794 out[CM_IX_BADAXIS] = badaxis
795 out[CM_IX_DECLARED] = declared
796 out[CM_IX_OBSERVED] = observed
797 out[CM_IX_WEIGHT] = wsum
798 if observed <= 0 { return 0 }
799 if wsum <= 0 { return 0 }
800 out[CM_IX_SCORE] = (acc + wsum / 2) / wsum
801 out[CM_IX_MEASURED] = 1
802 return 1
803}
804
805// THE SCORE AND ITS DENOMINATOR ARE PRINTED BY ONE FUNCTION so they can never be separated by a caller
806// that only wanted "the number". An UNOBSERVABLE county prints no score at all -- there is nothing to
807// round, and a dash cannot be mistaken for a low rank.
808func cm_index_print(fd: i64, fips: i64, out: *i64) -> i64 {
809 cm_w(fd, " county=" as *u8)
810 cm_n(fd, fips)
811 if out[CM_IX_MEASURED] == 1 {
812 cm_w(fd, " score_permil=" as *u8)
813 cm_n(fd, out[CM_IX_SCORE])
814 } else {
815 cm_w(fd, " score=UNOBSERVABLE" as *u8)
816 }
817 cm_w(fd, " observed=" as *u8)
818 cm_n(fd, out[CM_IX_OBSERVED])
819 cm_w(fd, " of_declared=" as *u8)
820 cm_n(fd, out[CM_IX_DECLARED])
821 cm_w(fd, " weight=" as *u8)
822 cm_n(fd, out[CM_IX_WEIGHT])
823 if out[CM_IX_MEASURED] == 1 {
824 if out[CM_IX_OBSERVED] < out[CM_IX_DECLARED] {
825 cm_w(fd, " PARTIAL-INSTRUMENT (this score is over fewer axes than another county's may be -- the two are not directly comparable)" as *u8)
826 }
827 }
828 cm_w(fd, "\n" as *u8)
829 return 0
830}
831
832// =====================================================================================================
833// CM15 -- cm_acre_truth. THE DOLLARS-PER-ACRE RULER, AND THE THREE THINGS IT REFUSES TO DO.
834// =====================================================================================================
835// The operator's complaint is concrete: listing platforms let a seller publish a per-acre number that no
836// recorded transaction supports. The obvious build is a fraud detector. That build would be wrong, and
837// this one deliberately is not it:
838//
839// 1. IT NEVER ALLEGES FRAUD. The only thing this can honestly say is "this asking price per acre lies
840// outside the band of RECORDED SALES in this county". That is a measurement. Why it lies outside --
841// a genuinely better parcel, a motivated seller, a mistake, or a lie -- is not in the data, and a
842// ruler that guesses at intent manufactures the accusation it claims to detect.
843// 2. IT REFUSES WHERE THE GROUND TRUTH DOES NOT EXIST. Eleven states are NON-DISCLOSURE: sale prices
844// are not public record there [@ndstates], so no distribution can be built and there is nothing to
845// be outside of. Those counties return UNPROVABLE. ★★★★★★ THE HONEST ANSWER TO "IS THIS PRICE
846// REASONABLE?" IN A NON-DISCLOSURE STATE IS THAT NOBODY CAN KNOW, AND A RULER THAT ANSWERS ANYWAY
847// IS WORSE THAN NO RULER -- it would be most confident exactly where it is least entitled to be.
848// 3. IT REFUSES ON A THIN COMPARABLE SET. A band built from two sales is not a band. Below the declared
849// minimum the verdict is UNPROVABLE-THIN, never "looks fine" -- a check that passes on an empty or
850// near-empty population is the gate-passes-on-the-empty-set defect wearing a market costume.
851//
852// THE MEDIAN, NOT THE MEAN, AND THAT IS THE WHOLE ANTI-GAMING PROPERTY. A mean moves with every outlier,
853// so a handful of inflated comparables drags the reference toward the very number being checked -- the
854// ruler would learn the manipulation and then bless it. A median of recorded transfers cannot be moved
855// by a minority of extreme values at all, so a seller cannot lift the band by posting more listings:
856// listings are not sales and only sales enter the distribution.
857// The band edges are DECLARED as percentiles in a conf row, never baked here -- a threshold nobody can
858// point at is a magic number, and this one decides whether a listing gets flagged.
859// Rows: sale|<fips>|<price_usd>|<acres_milli> nd|<state2> band|<lo_permil>|<hi_permil>|<min_sales>
860const CM_SL_FIPS: i64 = 1
861const CM_SL_PRICE: i64 = 2
862const CM_SL_ACRES: i64 = 3
863const CM_SL_MIN: i64 = 4
864const CM_MILLI: i64 = 1000
865// verdicts. UNPROVABLE-ND and UNPROVABLE-THIN are kept APART on purpose: one is a permanent property of
866// the state's law and can never be fixed by gathering data, the other is a temporary property of this
867// county's sample and is fixed by exactly one thing -- more recorded sales. Folding them into a single
868// "unknown" would hide which of those two situations a reader is in.
869const CM_AT_INSIDE: i64 = 0
870const CM_AT_ABOVE: i64 = 1
871const CM_AT_BELOW: i64 = 2
872const CM_AT_ND: i64 = 3
873const CM_AT_THIN: i64 = 4
874const CM_AT_BADINPUT: i64 = 5
875const CM_AT_TRUNC: i64 = 6
876// out[]: [0]=verdict [1]=per_acre [2]=lo [3]=hi [4]=median [5]=n_sales
877const CM_AT_V: i64 = 0
878const CM_AT_PA: i64 = 1
879const CM_AT_LO: i64 = 2
880const CM_AT_HI: i64 = 3
881const CM_AT_MED: i64 = 4
882const CM_AT_N: i64 = 5
883const CM_AT_DROP_NOACRE: i64 = 6
884const CM_AT_DROP_CAP: i64 = 7
885const CM_AT_SLOTS: i64 = 8
886const CM_AT_BYTES: i64 = 64
887
888// dollars per acre from a price in whole dollars and an area in MILLI-acres, integer and total.
889// Returns -1 when the area is zero or negative -- a parcel with no stated area has no price per acre,
890// and inventing one (by treating 0 as 1, say) would fabricate the exact quantity under test.
891func cm_per_acre(price: i64, acres_milli: i64) -> i64 {
892 if acres_milli <= 0 { return 0 - 1 }
893 if price < 0 { return 0 - 1 }
894 return price * CM_MILLI / acres_milli
895}
896
897// is this 2-letter state code on the declared non-disclosure list?
898func cm_is_nondisclosure(nbuf: *u8, nn: i64, st: *u8, stlen: i64) -> i64 {
899 var p: i64 = 0
900 while p < nn {
901 let le: i64 = cm_to(nbuf, p, nn, CM_NL)
902 if le > p {
903 if cm_starts(nbuf, p, le, "nd|" as *u8) == 1 {
904 let s: i64 = p + 3
905 if le - s == stlen {
906 var same: i64 = 1
907 var i: i64 = 0
908 while i < stlen {
909 if nbuf[s + i] != st[i] { same = 0 }
910 i = i + 1
911 }
912 if same == 1 { return 1 }
913 }
914 }
915 }
916 p = le + 1
917 }
918 return 0
919}
920
921// collect this county's recorded per-acre values into out[], ascending. Returns the count.
922// Insertion sort: the comparable set for one county is small, and a sort whose behaviour is obvious
923// beats a fast one whose correctness has to be argued about in a ruler that decides accusations.
924// drops[0]=no stated acreage (unpriceable per acre), drops[1]=dropped past the caller's cap.
925// COUNTED, because a band built from an arbitrary PREFIX of a sales file is a biased band and the
926// caller must be able to tell "this county has 9 recorded sales" from "it has 4000 and I read 64".
927func cm_acre_samples(sbuf: *u8, sn: i64, fips: i64, f: *i64, out: *i64, cap: i64, drops: *i64) -> i64 {
928 drops[0] = 0
929 drops[1] = 0
930 var n: i64 = 0
931 var p: i64 = 0
932 while p < sn {
933 let le: i64 = cm_to(sbuf, p, sn, CM_NL)
934 if le > p {
935 if cm_starts(sbuf, p, le, "sale|" as *u8) == 1 {
936 if cm_nfields(sbuf, p, le) >= CM_SL_MIN {
937 var same: i64 = 0
938 if cm_fld(sbuf, p, le, CM_SL_FIPS, f) == 1 {
939 if cm_fips_parse(sbuf, f[0], f[1]) == fips { same = 1 }
940 }
941 if same == 1 {
942 var price: i64 = 0 - 1
943 var acres: i64 = 0 - 1
944 if cm_fld(sbuf, p, le, CM_SL_PRICE, f) == 1 { price = cm_int(sbuf, f[0], f[1]) }
945 if cm_fld(sbuf, p, le, CM_SL_ACRES, f) == 1 { acres = cm_int(sbuf, f[0], f[1]) }
946 let pa: i64 = cm_per_acre(price, acres)
947 if pa < 0 { drops[0] = drops[0] + 1 }
948 if pa >= 0 {
949 if n >= cap { drops[1] = drops[1] + 1 }
950 if n < cap {
951 // ⚠SEPARATE FLAG, NEVER THE CURSOR. The first version of this loop broke
952 // out by assigning the sentinel INTO j -- which destroyed the very value
953 // the line after it needs, so every element landed at index 0 and silently
954 // overwrote its predecessor. The gate caught it as median=0 band=[9000,0].
955 // ★A LOOP THAT EXITS BY CLOBBERING ITS OWN CURSOR CANNOT ALSO REPORT WHERE
956 // IT STOPPED -- and here "where it stopped" IS the answer.
957 var j: i64 = n
958 var placing: i64 = 1
959 while placing == 1 {
960 if j <= 0 { placing = 0 } else {
961 if out[j - 1] > pa { out[j] = out[j - 1]; j = j - 1 } else { placing = 0 }
962 }
963 }
964 out[j] = pa
965 n = n + 1
966 }
967 }
968 }
969 }
970 }
971 }
972 p = le + 1
973 }
974 return n
975}
976
977// the percentile value of an ASCENDING array, by nearest-rank. Total for any n >= 1.
978func cm_pctl(sorted: *i64, n: i64, permil: i64) -> i64 {
979 if n <= 0 { return 0 - 1 }
980 var idx: i64 = (permil * n) / CM_PERMIL
981 if idx >= n { idx = n - 1 }
982 if idx < 0 { idx = 0 }
983 return sorted[idx]
984}
985
986// THE RULER. Returns the verdict code and fills out[] with every number behind it, because a flag whose
987// grounds are not printed beside it is an accusation rather than a measurement.
988func cm_acre_truth(sbuf: *u8, sn: i64, nbuf: *u8, nn: i64, fips: i64, st: *u8, stlen: i64,
989 ask_price: i64, ask_acres: i64, lo_permil: i64, hi_permil: i64, min_sales: i64,
990 f: *i64, samples: *i64, cap: i64, out: *i64) -> i64 {
991 var i: i64 = 0
992 while i < CM_AT_SLOTS { out[i] = 0 - 1; i = i + 1 }
993 let pa: i64 = cm_per_acre(ask_price, ask_acres)
994 out[CM_AT_PA] = pa
995 // THE LAW FIRST, BEFORE ANY ARITHMETIC. In a non-disclosure state there is no recorded distribution
996 // to be outside of, so no amount of computation could make an answer here honest.
997 if cm_is_nondisclosure(nbuf, nn, st, stlen) == 1 {
998 out[CM_AT_V] = CM_AT_ND
999 return CM_AT_ND
1000 }
1001 if pa < 0 {
1002 out[CM_AT_V] = CM_AT_BADINPUT
1003 return CM_AT_BADINPUT
1004 }
1005 let drops: *i64 = sys_mmap(16) as *i64
1006 let n: i64 = cm_acre_samples(sbuf, sn, fips, f, samples, cap, drops)
1007 out[CM_AT_N] = n
1008 out[CM_AT_DROP_NOACRE] = drops[0]
1009 out[CM_AT_DROP_CAP] = drops[1]
1010 // A BAND BUILT FROM A PREFIX IS NOT THE COUNTY'S BAND. If the cap was reached, the sample is
1011 // whatever happened to come first in the file -- and a sales export sorted by price or date makes
1012 // that prefix systematically biased, which would flag honest listings in one direction. Refuse.
1013 if drops[1] > 0 {
1014 out[CM_AT_V] = CM_AT_TRUNC
1015 return CM_AT_TRUNC
1016 }
1017 if n < min_sales {
1018 out[CM_AT_V] = CM_AT_THIN
1019 return CM_AT_THIN
1020 }
1021 out[CM_AT_MED] = cm_pctl(samples, n, CM_PERMIL / 2)
1022 let lo: i64 = cm_pctl(samples, n, lo_permil)
1023 let hi: i64 = cm_pctl(samples, n, hi_permil)
1024 out[CM_AT_LO] = lo
1025 out[CM_AT_HI] = hi
1026 if pa > hi {
1027 out[CM_AT_V] = CM_AT_ABOVE
1028 return CM_AT_ABOVE
1029 }
1030 if pa < lo {
1031 out[CM_AT_V] = CM_AT_BELOW
1032 return CM_AT_BELOW
1033 }
1034 out[CM_AT_V] = CM_AT_INSIDE
1035 return CM_AT_INSIDE
1036}
1037
1038// the verdict in words, with its grounds. Every branch names what would change the answer, so a reader
1039// is never left with a bare label they cannot act on or argue with.
1040func cm_acre_verdict_name(v: i64) -> *u8 {
1041 if v == CM_AT_INSIDE { return "INSIDE-RECORDED-BAND (this asking price per acre sits within what recorded transfers in this county actually show)" as *u8 }
1042 if v == CM_AT_ABOVE { return "ABOVE-RECORDED-BAND (asking more per acre than any but the top recorded transfers -- a FACT about the record, not an allegation about the seller)" as *u8 }
1043 if v == CM_AT_BELOW { return "BELOW-RECORDED-BAND (asking less per acre than nearly every recorded transfer -- worth reading as closely as a high one)" as *u8 }
1044 if v == CM_AT_ND { return "UNPROVABLE-NON-DISCLOSURE (this state does not make sale prices public, so no recorded band exists here and none can be built -- gathering more data cannot fix this)" as *u8 }
1045 if v == CM_AT_TRUNC { return "UNPROVABLE-TRUNCATED-SAMPLE (the comparable set hit its cap, so this band would be built from an arbitrary PREFIX of the sales file -- a biased sample flags honest listings in one direction) " as *u8 }
1046 if v == CM_AT_THIN { return "UNPROVABLE-THIN-COMPARABLES (fewer recorded sales than the declared minimum -- a band from this few is not a band; more recorded sales WOULD fix it)" as *u8 }
1047 return "REFUSED-BAD-INPUT (no stated acreage, so there is no price per acre to judge)" as *u8
1048}
1049
1050func cm_acre_print(fd: i64, v: i64, out: *i64) -> i64 {
1051 cm_w(fd, " " as *u8)
1052 cm_w(fd, cm_acre_verdict_name(v))
1053 cm_w(fd, "\n asking_per_acre=" as *u8)
1054 cm_n(fd, out[CM_AT_PA])
1055 cm_w(fd, " recorded_n=" as *u8)
1056 cm_n(fd, out[CM_AT_N])
1057 cm_w(fd, " median=" as *u8)
1058 cm_n(fd, out[CM_AT_MED])
1059 cm_w(fd, " band=[" as *u8)
1060 cm_n(fd, out[CM_AT_LO])
1061 cm_w(fd, "," as *u8)
1062 cm_n(fd, out[CM_AT_HI])
1063 cm_w(fd, "] dropped_no_acreage=" as *u8)
1064 cm_n(fd, out[CM_AT_DROP_NOACRE])
1065 cm_w(fd, " dropped_over_cap=" as *u8)
1066 cm_n(fd, out[CM_AT_DROP_CAP])
1067 cm_w(fd, "\n" as *u8)
1068 return 0
1069}