code wiki / _hdl_build / nx_wasm_vm_verify.nx
`nx_wasm_vm_verify.nx` source

↩ module page · 330 lines · 20274 B
1// nx_wasm_vm_verify.nx -- RUN ANY SHIPPED WASM MODULE IN THE MEMORY IT DECLARES.
2//
3// WHY THIS IS GENERIC AND NOT A SEVENTEENTH COPY. On 2026-08-14 /craft shipped black TWICE. Every
4// stage of its emit pipeline was GREEN and its NATIVE gate reported 59/59, because a native gate
5// sys_mmaps its own arena and therefore never meets the wasm memory bound at all. The browser did,
6// and trapped on the first frame with "index out of bounds".
7// Measured the same day: the estate has ELEVEN *_wasm_vm_gate organs and NOT ONE of them is for a
8// game. They cover the sims and some crypto/codec modules. Every browser-playable wasm game ships a
9// module that byte-checks pass and nobody ever executes -- the identical blind spot, ~17 times over.
10//
11// ★SO THE RULER IS PARAMETERISED, NOT DUPLICATED. One organ, a path argument, no per-module
12// constants anywhere in it. The declared memory is NOT mirrored from the module's source either --
13// wm_parse already reads the wasm memory section and sizes mod.mem from it, so this asks the
14// ARTIFACT what it declares rather than trusting a number typed in a second file. A mirrored page
15// count is exactly the kind of constant that goes stale in one place and takes a page down.
16//
17// WHAT IT PROVES, and only this:
18//   PARSES   -- the image is a real module
19//   DECLARES -- it names a linear memory, and the VM allocates exactly that much
20//   RUNS     -- the exported entry points execute without leaving that memory (the VM bounds-checks)
21//   PAINTS   -- for a FRAMEBUFFER module (ww/hh/fb_off exported) the frame carries >1 colour
22// A module with no framebuffer surface is not a renderer, and this says NOT-A-RENDERER and abstains
23// rather than inventing a verdict about a subject it cannot see.
24//
25// usage: nx_wasm_vm_verify <path.wasm> [noinit]
26//   noinit -- skip init(), for modules whose world generation cannot finish in an interpreter.
27//             nx_wasm_craft is the measured case: 786,432 voxels of noise, >120s. Its own gate
28//             (nx_wasm_craft_vm_gate) seeds a minimal scene instead; this flag is the generic
29//             escape so a slow init cannot be mistaken for a broken module.
30// exit: 0 GREEN | 1 RED | 3 the file could not be read
31// license_tier: ORIGINAL
32import "nx_syscalls.nx"
33import "nx_wasm_vm.nx"
34import "nx_gate_verdict.nx"
35import "nx_base64.nx"
36
37const WV_COLCAP: i64 = 4096
38// ★THE GAMES DO NOT SHIP A .wasm FILE -- they ship it EMBEDDED, base64, inside the page, which is
39// why a verifier that only takes a path reaches almost none of them. Measured 2026-08-14: nine
40// standalone .wasm exist estate-wide, while ~17 browser-playable games carry theirs inline. Taking
41// the PAGE as input is what makes this cover the artifact a visitor actually downloads.
42// The emitter writes it as: const B="<base64>"  (nx_game_page_emit), so that literal is the anchor.
43// ★★★★★★ANCHOR ON THE PAYLOAD, NEVER ON THE EMITTER'S SPELLING. This was `const B="` -- one
44// emitter's variable name -- and MEASURED 2026-08-15 that read 9 pages while 67 shipped pages call
45// WebAssembly.instantiate: racing, pong, explorer, adventure, td, city, shmup, voxelworld, sudoku and
46// viz-zoom all embed via `var b64='...'` and were INVISIBLE. A census built on it reported 4/4 GREEN
47// over 13% of its own subject and said nothing about the rest.
48// Every wasm module begins with the 8 bytes 00 61 73 6D 01 00 00 00 ("\0asm" + version 1), and since
49// the base64 encodes the module from byte zero that prefix is ALWAYS "AGFzbQEAAAA". It is a property
50// of the thing being carried, so it identifies an embedded module in any page from any emitter, past
51// or future, without this tool having to know the template.
52const WV_WASM_B64_MAGIC: *u8 = "AGFzbQEAAAA"
53const WV_APOS: i64 = 39
54const WV_QUOTE: i64 = 34
55// ★THE INTERPRETER'S FRAME BUDGET, set from what the estate's existing wasm-VM gates actually
56// complete: every one of them verifies a 256x256 = 65,536 pixel frame in milliseconds. Four times
57// that is the ceiling here, so a module rendering up to 512x512 is still measured directly and
58// anything larger is DECLINED OUT LOUD rather than left to hang. This bounds OUR throughput, not
59// the module -- which is why it is named for the interpreter and why the refusal prints the number.
60const WV_FRAME_BUDGET: i64 = 262144
61
62// ★★★★★A BUG YOU FIX BY REWRITING THE LINE, RATHER THAN BY EXTRACTING THE FIX, IS A BUG YOU WILL
63// WRITE AGAIN. These two were hand-rolled here, and the identical allocating formatter was hand-rolled
64// again in nx_wasmpage_census and again in nx_wasmfit -- three copies in one session, and nx_mmapbal
65// flagged every one of them as `mmap=2 munmap=0`, a leak per number printed. This file already imports
66// nx_gate_verdict, whose gv_puts/gv_num are measured CLEAN by the same scanner, so the fix is to DELETE
67// the duplicate rather than balance it. Thin wrappers keep every existing call site untouched while
68// there is exactly one implementation underneath.
69func wv_w(s: *u8) -> i64 { return gv_puts(s) }
70func wv_n(v: i64) -> i64 { return gv_num(v) }
71func wv_rd64(m: *u8, o: i64) -> i64 { var v: i64=0; var i: i64=0; while i<8 { v = v | ((m[o+i] as i64) << (i*8)); i=i+1 } return v }
72func wv_slen(s: *u8) -> i64 { var n: i64=0; while s[n]!=(0 as u8){n=n+1} return n }
73func wv_eq(a: *u8, b: *u8) -> i64 {
  var i: i64 = 0
  var r: i64 = 2
  while r == 2 {
      if a[i] != b[i] { r = 0 } else {
          if a[i] == (0 as u8) { r = 1 } else { i = i + 1 }
      }
  }
  return r
82}
83// first offset of needle in buf, or -1
84func wv_find(buf: *u8, len: i64, needle: *u8) -> i64 {
  let nl: i64 = wv_slen(needle)
  if nl == 0 { return 0 - 1 }
  var i: i64 = 0
  while i + nl <= len {
      var k: i64 = 0
      var m: i64 = 1
      while k < nl { if buf[i+k] != needle[k] { m = 0; k = nl } else { k = k + 1 } }
      if m == 1 { return i }
      i = i + 1
  }
  return 0 - 1
96}
97
98func main(argc: i64, argv: *i64) -> i64 {
  let ctr: *i64 = gv_ctr()
  if argc < 2 {
      wv_w("usage: nx_wasm_vm_verify <path.wasm|page.html> [noinit] [nopaint]\n" as *u8)
      wv_w("  noinit  -- do not call init(); report the FINEST geometry the module can ask for\n" as *u8)
      wv_w("  nopaint -- answer only whether the framebuffer fits; never attempt a frame\n" as *u8)
      return 3
  }
  let path: *u8 = argv[1] as *u8
107
  // ★★★★★★A FLAG THAT ACCEPTS ANY SPELLING CANNOT REPORT A TYPO, AND THE CALLER THEN BELIEVES IT
  // ASKED FOR SOMETHING IT DID NOT. The first cut of this parse was `if argc >= 3 { noinit = 1 }` --
  // it never looked at the token at all, so ANY third argument (a misspelling, a stray path, a flag
  // meant for something else) silently turned init off, and a caller that asked for "nopaint" would
  // have got "noinit" and no warning. An unrecognised flag is now a refusal, because the alternative
  // is a tool that answers a different question than the one it was asked and says nothing about it.
  var noinit: i64 = 0
  var nopaint: i64 = 0
  var badflag: i64 = 0
  var ai: i64 = 2
  while ai < argc {
      let f: *u8 = argv[ai] as *u8
      if wv_eq(f, "noinit" as *u8) == 1 { noinit = 1 } else {
          if wv_eq(f, "nopaint" as *u8) == 1 { nopaint = 1 } else {
              badflag = 1
              wv_w("  unrecognised flag: " as *u8); wv_w(f); wv_w("\n" as *u8)
          }
      }
      ai = ai + 1
  }
  if badflag == 1 {
      wv_w("  refusing rather than guessing which question you meant -- known flags: noinit nopaint\n" as *u8)
      return 3
  }
132
  wv_w("=== nx_wasm_vm_verify " as *u8); wv_w(path); wv_w(" ===\n" as *u8)
134
  let box: *i64 = sys_mmap(16) as *i64
  var img: *u8 = sys_read_file(path, box)
  if (img as i64) == 0 {
      wv_w("  cannot read the module -- nothing to verify\n" as *u8)
      return 3
  }
  wv_w("  file bytes = " as *u8); wv_n(box[0]); wv_w("\n" as *u8)
142
  // ★IF THIS IS A PAGE, VERIFY THE MODULE THE PAGE ACTUALLY CARRIES. A wasm game does not ship as
  // a file next to its html -- it is base64 INSIDE it. Reading the page and decoding the embedded
  // module means this tool measures the exact bytes a visitor downloads, not a build artifact that
  // may or may not have been the one emitted.
  let anchor: i64 = wv_find(img, box[0], WV_WASM_B64_MAGIC)
  if anchor >= 0 {
      // The magic sits at the START of the base64 literal, so the delimiter is the byte before it --
      // but walk back rather than assume, and accept EITHER quote: emitters here use both `"` and `'`.
      // ⚠The scan uses its own cursor and an explicit flag; writing the exit into the cursor would
      // destroy the position that IS the answer.
      var qc: i64 = 0
      var s: i64 = anchor
      var b: i64 = anchor
      var scan: i64 = 1
      while scan == 1 {
          if b == 0 { scan = 0 } else {
              let c: i64 = img[b-1] as i64
              if c == WV_QUOTE { qc = WV_QUOTE; s = b; scan = 0 } else {
                  if c == WV_APOS { qc = WV_APOS; s = b; scan = 0 } else { b = b - 1 }
              }
          }
      }
      if qc == 0 {
          wv_w("  found a wasm magic but no enclosing string literal -- refusing to guess its extent\n" as *u8)
          return 3
      }
      var fin: i64 = s
      var stop: i64 = 0
      while stop == 0 {
          if fin >= box[0] { stop = 1 } else {
              if (img[fin] as i64) == qc { stop = 1 } else { fin = fin + 1 }
          }
      }
      let b64n: i64 = fin - s
      // 3 bytes out per 4 chars in; allocate the ceiling, never a guessed constant
      let dec: *u8 = sys_mmap((b64n/4 + 2) * 3)
      let dn: i64 = b64_decode(((img as i64) + s) as *u8, b64n, dec)
      wv_w("  EMBEDDED module found: base64 chars = " as *u8); wv_n(b64n)
      wv_w("  decoded bytes = " as *u8); wv_n(dn); wv_w("\n" as *u8)
      if dn <= 0 {
          wv_w("  the embedded blob did not decode -- refusing to guess what shipped\n" as *u8)
          return 3
      }
      img = dec
      box[0] = dn
  }
189
  let mod: *WasmMod = wm_new(img, box[0])
  let parsed: i64 = (wm_parse(mod) == 0) as i64
  gv_check("PARSES: the image is a real wasm module" as *u8, parsed, ctr)
193
  // ★ASK THE ARTIFACT, NOT A SECOND FILE. wm_parse reads the memory section and allocates mod.mem
  // to exactly the declared minimum, so this number comes from the bytes that ship.
  wv_w("  declared linear memory = " as *u8); wv_n(mod.mem_bytes)
  wv_w(" bytes (" as *u8); wv_n(mod.mem_bytes/65536); wv_w(" pages)\n" as *u8)
  gv_check("DECLARES: the module names a linear memory and the VM sized itself to it" as *u8, (mod.mem_bytes > 0) as i64, ctr)
199
  let fw: i64 = wm_find_export(mod, "ww" as *u8)
  let fh: i64 = wm_find_export(mod, "hh" as *u8)
  let fo: i64 = wm_find_export(mod, "fb_off" as *u8)
  let fr: i64 = wm_find_export(mod, "render" as *u8)
  let fi: i64 = wm_find_export(mod, "init" as *u8)
  var isfb: i64 = 0
  if fw>=0 { if fh>=0 { if fo>=0 { if fr>=0 { isfb = 1 } } } }
  wv_w("  exports: ww=" as *u8); wv_n(fw); wv_w(" hh=" as *u8); wv_n(fh)
  wv_w(" fb_off=" as *u8); wv_n(fo); wv_w(" render=" as *u8); wv_n(fr)
  wv_w(" init=" as *u8); wv_n(fi); wv_w("\n" as *u8)
210
  if isfb == 0 {
      // ★ABSTAIN, DO NOT INVENT -- BUT NAME WHAT IS ACTUALLY THERE. This module exposes no
      // framebuffer surface, so "does it paint" is not a question about it. Answering anyway is how
      // a gate ends up reporting a narrower subject than its name implies.
      // ★AND PRINT THE EXPORTS. A bare "NOT-A-RENDERER" cannot be checked by its reader: it looks
      // identical whether the module genuinely has no display surface or merely spells its entry
      // points differently. Listing them turns an assertion into evidence, and the difference
      // decides whether this tool needs a second naming convention or the module needs a surface.
      wv_w("  NOT-A-RENDERER: no ww/hh/fb_off/render surface. Its " as *u8); wv_n(mod.n_exports)
      wv_w(" exports are:\n" as *u8)
      var e: i64 = 0
      while e < mod.n_exports {
          wv_w("    " as *u8)
          sys_write(1, ((mod.bytes as i64) + mod.exp_name_off[e]) as *u8, mod.exp_name_len[e])
          wv_w("\n" as *u8)
          e = e + 1
      }
      gv_need("RUNS+PAINTS: needs a framebuffer surface (ww/hh/fb_off/render)" as *u8, 0, ctr)
      return gv_verdict("WASM-VM-VERIFY" as *u8, ctr, "module parsed and declared its memory; it exposes no framebuffer so rendering was not claimed either way" as *u8)
  }
231
  if noinit == 0 { if fi >= 0 { wm_run(mod, "init" as *u8, 0,0,0,0,0, 0) } }
233
  // ⚠SIZE THE WORK BEFORE DOING IT. ww/hh/fb_off are trivial accessors; render is the expensive
  // call, so every decision about whether the frame is affordable has to happen BEFORE it. The
  // first cut of this tool checked the budget AFTER rendering, which is no check at all -- it hung
  // on craft's 900,000-pixel frame exactly as if the budget did not exist. Cheap questions first.
  let off: i64 = wm_run(mod, "fb_off" as *u8, 0,0,0,0,0, 0)
  let w: i64 = wm_run(mod, "ww" as *u8, 0,0,0,0,0, 0)
  let h: i64 = wm_run(mod, "hh" as *u8, 0,0,0,0,0, 0)
  let need: i64 = off + w*h*8
  wv_w("  frame " as *u8); wv_n(w); wv_w("x" as *u8); wv_n(h)
  wv_w(" at fb_off=" as *u8); wv_n(off); wv_w(" needs=" as *u8); wv_n(need)
  wv_w(" headroom=" as *u8); wv_n(mod.mem_bytes - need); wv_w("\n" as *u8)
  let fits: i64 = (need <= mod.mem_bytes) as i64
  gv_check("RUNS: the framebuffer the module reports lies inside the memory it declares -- a browser traps the instant it does not" as *u8, fits, ctr)
247
  // ★★★★★★AN ABSTENTION ON A LATER QUESTION MUST NOT ERASE A DEFINITIVE ANSWER TO AN EARLIER ONE.
  // gv_verdict tests ctr[2] FIRST and returns 3/SKIP before it ever compares passed-vs-run, which is
  // correct for a gate whose preconditions failed -- but here the fit question is ALREADY ANSWERED at
  // this point, and answered NO. Falling through to the frame-budget gv_need below would report the
  // exact /craft outage this tool was built to catch as "I could not look", and any census reading
  // exit codes would score it as an honest abstention. ★A SKIP THAT CAN SWALLOW A RED IS NOT A THIRD
  // STATE, IT IS AN AMNESTY. So a module that does not fit returns RED here, unconditionally, before
  // any question about affordability is even raised.
  if fits == 0 {
      wv_w("  the framebuffer does NOT fit: a browser traps on the first out-of-bounds store,\n" as *u8)
      wv_w("  which is a BLACK PAGE, not a slow one. Frame affordability is not asked -- the module\n" as *u8)
      wv_w("  is already refuted.\n" as *u8)
      return gv_verdict("WASM-VM-VERIFY" as *u8, ctr, "the module reports a framebuffer outside the linear memory it declares" as *u8)
  }
262
  // ★ANSWER ONLY WHAT WAS ASKED. A census over every shipped page wants the STRUCTURAL question --
  // does the framebuffer fit -- and that question is fully answered by the check above, which needs
  // no frame at all. Attempting one anyway is what turned four world pages into TIMEOUTs on the
  // first census run: the interpreter is orders of magnitude slower per pixel than the browser the
  // module actually ships to, and a raycasting frame under the pixel budget can still take minutes.
  // ★A TIMEOUT IS A NON-ANSWER, AND A NON-ANSWER ON THE PAGES THAT MATTER IS A CENSUS THAT MEASURED
  // NOTHING. Frame CONTENT remains each module's own gate's job, where a cheap frame can be seeded.
  if nopaint == 1 {
      wv_w("  nopaint: the caller asked only whether the framebuffer fits, and it does. No frame\n" as *u8)
      wv_w("  was attempted, so nothing is claimed about what this module draws.\n" as *u8)
      gv_need("PAINTS: not attempted -- caller asked the structural question only" as *u8, 0, ctr)
      return gv_verdict("WASM-VM-VERIFY" as *u8, ctr, "the module declares a linear memory and reports a framebuffer that fits inside it" as *u8)
  }
276
  // ★REFUSE RATHER THAN HANG, AND SAY THE NUMBER. This VM is an INTERPRETER, so frame cost is not
  // a detail -- it decides whether this tool answers at all. Measured 2026-08-14: the estate's
  // existing wasm-VM gates all verify 256x256 = 65,536 pixel frames and complete in milliseconds,
  // while craft with no init() clamps its quality slot to 1 and asks for 1200x750 = 900,000, which
  // does not finish. A tool that silently sits there is worse than one that declines: the caller
  // cannot tell "slow" from "broken", which is exactly the ambiguity that let a black page ship.
  // The bound is on OUR interpreter's throughput, not on the module, so it is named for that and
  // the refusal names the remedy: a module this large needs its own gate, which can seed a cheap
  // frame the way nx_wasm_craft_vm_gate does.
  if w*h > WV_FRAME_BUDGET {
      wv_w("  frame is " as *u8); wv_n(w*h); wv_w(" pixels, over the interpreter budget of " as *u8)
      wv_n(WV_FRAME_BUDGET); wv_w(" -- REFUSING to attempt it.\n" as *u8)
      wv_w("  remedy: give this module a gate that seeds a cheaper frame (see nx_wasm_craft_vm_gate),\n" as *u8)
      wv_w("  or call render after an init() that leaves a coarser quality setting.\n" as *u8)
      gv_need("PAINTS: frame within the interpreter budget" as *u8, 0, ctr)
      return gv_verdict("WASM-VM-VERIFY" as *u8, ctr, "module parsed, declared its memory and reported a framebuffer that fits; the frame itself was too large for this VM to render inside a gate" as *u8)
  }
  wm_run(mod, "render" as *u8, 0,0,0,0,0, 0)
295
  let seen: *i64 = sys_mmap(WV_COLCAP*8) as *i64
  var distinct: i64 = 0
  var p: i64 = 0
  while p < w*h {
      let c: i64 = wv_rd64(mod.mem, off + p*8)
      var j: i64 = 0
      var dup: i64 = 0
      while j < distinct { if seen[j]==c { dup=1; j=distinct } else { j=j+1 } }
      if dup==0 { if distinct < WV_COLCAP { seen[distinct]=c; distinct=distinct+1 } else { p = w*h } }
      p = p + 1
  }
  wv_w("  distinct colours = " as *u8); wv_n(distinct); wv_w("\n" as *u8)
308
  // ★★★★★★A TOOTH THAT FAILS BECAUSE THE HARNESS REMOVED ITS PRECONDITION IS MEASURING THE HARNESS.
  // MEASURED 2026-08-15 on voxelworld/index.html: fit PASSED with 1,875,968 bytes of headroom, then
  // PAINTS failed on a uniform frame and the caller's bucket reported "does not run in the memory it
  // declares" -- a live, healthy page indicted for a defect it does not have. TWO causes, both in
  // this tool: `noinit` had deliberately skipped the world generation the frame draws, and render()
  // is invoked here with all-zero arguments while that module's render takes seven camera
  // parameters. Under either condition a blank frame is the EXPECTED result of how it was called.
  // ★A DETECTOR WITH FALSE POSITIVES IS WORSE THAN NONE -- it teaches everyone to ignore it, and this
  // one would have sent the next reader hunting a bug that was never there.
  if noinit == 1 {
      if distinct <= 1 {
          wv_w("  the frame is uniform, but init() was SKIPPED at this caller's request and render was\n" as *u8)
          wv_w("  driven with zero arguments, so a blank frame is the expected outcome of HOW IT WAS\n" as *u8)
          wv_w("  CALLED, not evidence about the module. Drive it from its own gate to ask this.\n" as *u8)
          gv_need("PAINTS: not observable -- init skipped and render not driven with real arguments" as *u8, 0, ctr)
          return gv_verdict("WASM-VM-VERIFY" as *u8, ctr, "the module declares a linear memory and reports a framebuffer that fits inside it" as *u8)
      }
  }
  gv_check("PAINTS: the module wrote a VARIED frame -- one that trapped, or wrote nothing, cannot" as *u8, (distinct > 1) as i64, ctr)
328
  return gv_verdict("WASM-VM-VERIFY" as *u8, ctr, "the shipped module was executed in the memory it declares, not merely inspected as bytes" as *u8)
330}
nx_wasm_vm_verify.nx source

`nx_wasm_vm_verify.nx` source
