`nx_enginelab.nx` source

↩ module page · 534 lines · 25925 B
1// nx_enginelab.nx -- THE DRIVER: attach the sovereign engine instrument to a REAL renderer.
2//
3// WHAT WAS MISSING AND WHY IT MATTERED. nx_enginelab_lib (the spine), nx_enginelab_store (EL1
4// persistence), nx_enginelab_golden (the O3DE class) and nx_enginelab_analysis (replay, shader
5// binding, sampling, call tree) are roughly 69 KB of gate-proven library. The gate that proves them
6// says so in its own verdict: every tooth asserts an arithmetic property "on fixtures whose answers
7// are known by construction". That is a proof about the INSTRUMENT and it is worth having -- but
8// until this file existed NOTHING drove the instrument over a real frame, so the estate owned a
9// profiler that had never profiled anything. A measurement capability with no driver is
10// BUILT-AND-UNWIRED, and a green gate makes that invisible: the gate passes exactly as well with
11// zero real subjects as with a thousand.
12//
13// THE SUBJECT, AND WHY THIS ONE. nx_wasm_craft is the estate real renderer -- a per-pixel integer
14// DDA raycast over a voxel world plus a skinned-mesh character composite -- and it is the ONE render
15// path reachable natively with no browser (nx_world_snap already drives it that way, which is the
16// standing evidence that init_impl_v / tick_impl / render_impl compose outside a page). Attaching
17// here therefore needs no GUI, no capture harness and no second copy of the engine.
18//
19// WHAT THIS DRIVER MEASURES, AND WHAT IT REFUSES TO. It owns the call sites it wraps: the arena
20// allocation, init, and per frame a tick zone and a render zone. Everything derived from those is a
21// real observation of a real frame. It does NOT own the inside of render_impl, so:
22//   - THE DRAW CLASS IS UNMEASURABLE HERE AND SAYS SO BY NAME. The engine emits no draw stream --
23//     there is no el_draw call anywhere in nx_wasm_craft -- so draws, redundant binds, pipeline
24//     state hashes, capture diff and replay divergence have NO SUBJECT. This driver reports draws=0
25//     with the reason attached and the exact emission site the engine lane owes. It does NOT
26//     reconstruct the engine visibility test from outside: mob_draw culls on 200 < vz < 40*256, and
27//     copying that predicate here would be a duplicate ruler that drifts silently the day the engine
28//     changes it. A NAMED ABSENCE IS A BUILD CONTRACT; A RECONSTRUCTED NUMBER IS A LIE WITH A
29//     DENOMINATOR.
30//   - THE BOUND VERDICT ABSTAINS. This renderer is a CPU integer raycaster; nothing is submitted to
31//     a GPU queue, so el_bound_verdict correctly returns UNKNOWN. Manufacturing a GPU signal to make
32//     the verdict decide would be the acquit-on-no-evidence defect the spine exists to prevent.
33// What it CAN answer, and nothing else in this estate could before: how long a real frame costs,
34// how that cost splits between simulation and rasterisation, what the cost per RAY is, whether the
35// pacing stutters, and whether two independent runs of the same seed produce the same pixels.
36//
37// RAYS ARE THE UNIT OF WORK, AND THE COUNT IS ENGINE-OWNED. wc_rw/wc_rh are the engine own single
38// owner of the written extent (its source says so), so rays-per-frame is READ from the engine rather
39// than recomputed here. ns-per-ray is the figure that survives a resolution change; a bare frame
40// time does not.
41//
42// license_tier: ORIGINAL   No hardware writes (Rule 26): this reads a framebuffer and computes.
43import "nx_syscalls.nx"
44import "nx_enginelab_lib.nx"
45import "nx_enginelab_store.nx"
46import "nx_enginelab_golden.nx"
47import "nx_wasm_craft.nx"
48
49// ---- named parameters. Every bar and every literal below has a name, because a number a reader
50// cannot find again is a number nobody can change on evidence.
51const ELD_ARENA_PAD: i64 = 4096          // the same head-room nx_world_snap allocates beside CRAFT_TOTAL
52const ELD_TID_MAIN: i64 = 1              // one thread: this driver is single-threaded by construction
53const ELD_N_ARENA:  i64 = 1              // interned zone/alloc name ids -- ids, never strings, in a hot loop
54const ELD_N_INIT:   i64 = 2
55const ELD_N_TICK:   i64 = 3
56const ELD_N_RENDER: i64 = 4
57// DERIVED, not guessed: one FRAME record plus a tick zone plus a render zone per frame, and a
58// prologue of arena-alloc + init-zone + the trailing frame mark that closes the last frame. If this
59// arithmetic is ever wrong the store REFUSES the overflow and el_complete reports 0 -- the coverage
60// line below carries it, so an undersized store can never read as a complete measurement.
61const ELD_REC_PER_FRAME: i64 = 3
62const ELD_REC_PROLOGUE:  i64 = 8
63const ELD_FRAMES_DEFAULT: i64 = 4
64const ELD_TICK_MS: i64 = 16              // one 60Hz step, the same dt nx_world_snap ticks with
65const ELD_TARGET_FPS_DEFAULT: i64 = 60
66const ELD_SEED_DEFAULT: i64 = 20260728   // the beach seed the acceptance corpus already uses
67const ELD_Q_DEFAULT: i64 = 1             // native resolution: a capture reduced by a load-sensitive
                                       // governor makes every verdict a function of box load
69const ELD_Q_GOVERNOR_ARG: i64 = 0        // q=0 asks for the engine own adaptive controller instead
70const ELD_MIN_CLOSED_FRAMES: i64 = 2     // fewer than two boundaries is not a pacing measurement
71const ELD_GRID_DEFAULT: i64 = 16         // golden grid, cells per axis
72const ELD_THRESH_DEFAULT: i64 = 4        // per-cell mean tolerance
73const ELD_DEC: i64 = 10
74const ELD_ASCII_0: i64 = 48
75const ELD_DIGIT_TOP: i64 = 9
76const ELD_NUMBUF: i64 = 32
77const ELD_RGB_CH: i64 = 3
78const ELD_BYTE_MASK: i64 = 255
79const ELD_G_SHIFT: i64 = 8
80const ELD_B_SHIFT: i64 = 16
81const ELD_NS_PER_US: i64 = 1000
82const ELD_PERMIL: i64 = 1000
83const ELD_SCRATCH_SLOTS: i64 = 32
84const ELD_ARGV_VERB: i64 = 1
85const ELD_EXIT_OK: i64 = 0
86const ELD_EXIT_FAIL: i64 = 1
87const ELD_EXIT_USAGE: i64 = 2
88const ELD_EXIT_UNMEASURABLE: i64 = 3
89
90// ---- output primitives ---------------------------------------------------------------------------
91func eld_slen(s: *u8) -> i64 { var n: i64 = 0; while s[n] != (0 as u8) { n = n + 1 } return n }
92func eld_puts(s: *u8) -> i64 { sys_write(1, s, eld_slen(s)); return 0 }
93func eld_pn(v: i64) -> i64 {
  if v == 0 { sys_write(1, "0" as *u8, 1); return 0 }
  var m: i64 = v
  if m < 0 { sys_write(1, "-" as *u8, 1); m = 0 - m }
  let t: *u8 = sys_mmap(ELD_NUMBUF)
  var k: i64 = 0
  while m > 0 { t[k] = (ELD_ASCII_0 + (m % ELD_DEC)) as u8; m = m / ELD_DEC; k = k + 1 }
  let o: *u8 = sys_mmap(ELD_NUMBUF)
  var i: i64 = 0
  while i < k { o[i] = t[k - 1 - i]; i = i + 1 }
  sys_write(1, o, k)
  sys_munmap(t, ELD_NUMBUF)
  sys_munmap(o, ELD_NUMBUF)
  return 0
107}
108func eld_kv(label: *u8, v: i64) -> i64 { eld_puts(label); eld_pn(v); eld_puts(" " as *u8); return 0 }
109func eld_nl() -> i64 { eld_puts("\n" as *u8); return 0 }
110func eld_int(s: *u8) -> i64 {
  var v: i64 = 0
  var i: i64 = 0
  while s[i] != (0 as u8) {
      let c: i64 = s[i] as i64
      if c >= ELD_ASCII_0 { if c <= ELD_ASCII_0 + ELD_DIGIT_TOP { v = v*ELD_DEC + (c - ELD_ASCII_0) } }
      i = i + 1
  }
  return v
119}
120func eld_streq(a: *u8, b: *u8) -> i64 {
  var i: i64 = 0
  while a[i] != (0 as u8) {
      if a[i] != b[i] { return 0 }
      i = i + 1
  }
  if b[i] != (0 as u8) { return 0 }
  return 1
128}
129func eld_scratch() -> *i64 { return sys_mmap(ELD_SCRATCH_SLOTS * EL_I64) as *i64 }
130// The interned ids above are printed back as names here, in ONE place, so a report can never name a
131// zone the driver does not actually open.
132func eld_name(id: i64) -> i64 {
  if id == ELD_N_ARENA  { eld_puts("arena" as *u8); return 0 }
  if id == ELD_N_INIT   { eld_puts("init" as *u8); return 0 }
  if id == ELD_N_TICK   { eld_puts("tick" as *u8); return 0 }
  if id == ELD_N_RENDER { eld_puts("render" as *u8); return 0 }
  eld_puts("none" as *u8)
  return 0
139}
140
141// ---- the attachment ------------------------------------------------------------------------------
142func eld_arena_bytes() -> i64 { return CRAFT_TOTAL + ELD_ARENA_PAD }
143func eld_store_cap(frames: i64) -> i64 { return ELD_REC_PROLOGUE + frames * ELD_REC_PER_FRAME }
144// The engine native pixel count, from the engine own frame extent. Read rather than restated, so a
145// change to the engine frame size cannot leave a stale denominator here.
146func eld_native_pixels() -> i64 { return W * H }
147
148// THE FRAME RECORD SPARE PAYLOAD CARRIES THIS DRIVER TWO PER-FRAME FACTS. The spine documents
149// EL_F_C for a FRAME as the ordinal and leaves A and B unused; this driver writes A = the quality
150// level the frame was actually rendered at and B = the rays that quality implies. Declared here
151// rather than discovered by a later reader of a capture.
152const ELD_FRAME_A_Q:    i64 = 5          // == EL_F_A, restated at its meaning
153const ELD_FRAME_B_RAYS: i64 = 6          // == EL_F_B
154
155// Run `frames` real frames of the real engine through the instrument. Returns the arena, or 0.
156func eld_run(st: *i64, v: i64, seed: i64, q: i64, frames: i64) -> i64 {
  let base: i64 = sys_mmap(eld_arena_bytes()) as i64
  if base == 0 { return 0 }
  // A REAL allocation, recorded as one. This is the whole engine arena and by far the largest
  // single allocation on the path, so a memory report that omitted it would be fiction.
  el_alloc(st, sys_now_us(), ELD_TID_MAIN, ELD_N_ARENA, eld_arena_bytes(), base)
  el_zone_begin(st, sys_now_us(), ELD_TID_MAIN, ELD_N_INIT)
  init_impl_v(base, v, seed)
  el_zone_end(st, sys_now_us())
  var i: i64 = 0
  while i < frames {
      let fi: i64 = el_frame_mark(st, sys_now_us())
      el_zone_begin(st, sys_now_us(), ELD_TID_MAIN, ELD_N_TICK)
      tick_impl(base, ELD_TICK_MS)
      el_zone_end(st, sys_now_us())
      // QUALITY IS PINNED AFTER THE TICK, NOT BEFORE IT. The engine adaptive controller writes
      // S_Q during the tick, so a value written before it would be overwritten and the announced
      // quality would not be the quality rendered. q=0 deliberately leaves the governor in charge
      // and the driver RECORDS what it chose instead of dictating one.
      let s: *i64 = wst(base)
      if q > ELD_Q_GOVERNOR_ARG {
          var qq: i64 = q
          if qq > Q_MAX { qq = Q_MAX }
          s[S_Q] = qq
      }
      el_zone_begin(st, sys_now_us(), ELD_TID_MAIN, ELD_N_RENDER)
      render_impl(base)
      el_zone_end(st, sys_now_us())
      if fi >= 0 {
          el_set(st, fi, ELD_FRAME_A_Q, wc_q(base))
          el_set(st, fi, ELD_FRAME_B_RAYS, wc_rw(base) * wc_rh(base))
      }
      i = i + 1
  }
  // THE TRAILING MARK CLOSES THE LAST FRAME. A frame cost is the distance to the next boundary,
  // so without this the final frame has no successor, is reported OPEN, and is excluded from every
  // statistic -- a measurement that silently loses its last sample.
  el_frame_mark(st, sys_now_us())
  return base
195}
196
197// ---- the report ----------------------------------------------------------------------------------
198func eld_zone_line(st: *i64, name: i64) -> i64 {
  let a: *i64 = eld_scratch()
  el_zone_agg(st, name, a)
  eld_kv("calls=" as *u8, a[EL_AGG_CALLS])
  eld_kv("incl_us=" as *u8, a[EL_AGG_INCL])
  eld_kv("self_us=" as *u8, a[EL_AGG_SELF])
  eld_kv("max_us=" as *u8, a[EL_AGG_MAX])
  eld_kv("open=" as *u8, a[EL_AGG_OPEN])
  eld_nl()
  return a[EL_AGG_SELF]
208}
209
210func eld_report(st: *i64, base: i64, v: i64, seed: i64, q_arg: i64, frames: i64, target_fps: i64) -> i64 {
  let rw: i64 = wc_rw(base)
  let rh: i64 = wc_rh(base)
  let rays: i64 = rw * rh
  var q_reason: i64 = EL_Q_EXPLICIT
  if q_arg == ELD_Q_GOVERNOR_ARG { q_reason = EL_Q_GOVERNOR }
  // permil of the engine OWN native pixel count, so a reduced capture can never pass as a full one
  let q_permil: i64 = rays * ELD_PERMIL / eld_native_pixels()
218
  eld_puts("ENGINELAB-SUBJECT organ=nx_wasm_craft entry=render_impl " as *u8)
  eld_kv("v=" as *u8, v)
  eld_kv("seed=" as *u8, seed)
  eld_kv("frames_requested=" as *u8, frames)
  eld_kv("q=" as *u8, wc_q(base))
  eld_kv("rw=" as *u8, rw)
  eld_kv("rh=" as *u8, rh)
  eld_kv("rays_per_frame=" as *u8, rays)
  eld_kv("native_permil=" as *u8, q_permil)
  eld_nl()
229
  // COVERAGE FIRST, ALWAYS. Every number below is a claim about a population, and this line is the
  // only thing that says whether the population is whole.
  eld_puts("ENGINELAB-COVERAGE " as *u8)
  eld_kv("events=" as *u8, el_count(st))
  eld_kv("dropped=" as *u8, el_dropped(st))
  eld_kv("complete=" as *u8, el_complete(st))
  eld_kv("errors=" as *u8, el_errors(st))
  eld_nl()
238
  let fs: *i64 = eld_scratch()
  let closed: i64 = el_frame_stats(st, EL_STUTTER_NUM_DEFAULT, EL_STUTTER_DEN_DEFAULT, fs)
  eld_puts("ENGINELAB-PACING " as *u8)
  if closed < ELD_MIN_CLOSED_FRAMES {
      // A PACING VERDICT ON FEWER THAN TWO CLOSED FRAMES IS THE EMPTY-SET PASS. Refuse it by name.
      eld_kv("closed_frames=" as *u8, closed)
      eld_puts("verdict=UNMEASURABLE reason=fewer-than-two-closed-frames-is-not-a-series\n" as *u8)
  } else {
      eld_kv("closed_frames=" as *u8, fs[EL_FS_FRAMES])
      eld_kv("open=" as *u8, fs[EL_FS_OPEN])
      eld_kv("span_us=" as *u8, fs[EL_FS_SPAN])
      eld_kv("avgfps_x1000=" as *u8, fs[EL_FS_AVGFPS])
      eld_kv("median_us=" as *u8, fs[EL_FS_MEDIAN])
      eld_kv("worst_us=" as *u8, fs[EL_FS_WORST])
      eld_kv("low1_x1000=" as *u8, fs[EL_FS_LOW1])
      eld_kv("low01_x1000=" as *u8, fs[EL_FS_LOW01])
      eld_kv("stutter=" as *u8, fs[EL_FS_STUTTER])
      eld_nl()
  }
258
  // THE JOIN, PER FRAME. One call per frame answers what five separate capture formats cannot:
  // this frame cost N us, of which so much was CPU root time, so much GPU queue, so many draws,
  // so many bytes -- on one clock, from one record layout.
  let fa: *i64 = eld_scratch()
  var k: i64 = 0
  while k < frames {
      if el_frame_attr(st, k, fa) == 1 {
          eld_puts("ENGINELAB-JOIN " as *u8)
          eld_kv("ord=" as *u8, k)
          eld_kv("dur_us=" as *u8, fa[EL_FA_DUR])
          eld_kv("cpu_us=" as *u8, fa[EL_FA_CPUUS])
          eld_kv("gpu_us=" as *u8, fa[EL_FA_GPUUS])
          eld_kv("lock_us=" as *u8, fa[EL_FA_LOCKUS])
          eld_kv("draws=" as *u8, fa[EL_FA_DRAWS])
          eld_kv("alloc_bytes=" as *u8, fa[EL_FA_ALLOCB])
          eld_kv("events=" as *u8, fa[EL_FA_EVENTS])
          let fr: i64 = el_frame_rec(st, k)
          if fr >= 0 {
              eld_kv("q=" as *u8, el_get(st, fr, ELD_FRAME_A_Q))
              eld_kv("rays=" as *u8, el_get(st, fr, ELD_FRAME_B_RAYS))
          }
          eld_puts("hot=" as *u8)
          eld_name(fa[EL_FA_HOTNAME])
          eld_nl()
      }
      k = k + 1
  }
286
  eld_puts("ENGINELAB-ZONE name=init " as *u8)
  let init_us: i64 = eld_zone_line(st, ELD_N_INIT)
  eld_puts("ENGINELAB-ZONE name=tick " as *u8)
  let tick_us: i64 = eld_zone_line(st, ELD_N_TICK)
  eld_puts("ENGINELAB-ZONE name=render " as *u8)
  let rend_us: i64 = eld_zone_line(st, ELD_N_RENDER)
  let hot: *i64 = eld_scratch()
  let hotname: i64 = el_zone_hottest(st, hot)
  eld_puts("ENGINELAB-HOTTEST name=" as *u8)
  eld_name(hotname)
  eld_puts(" " as *u8)
  eld_kv("self_us=" as *u8, hot[0])
  eld_nl()
300
  // NS-PER-RAY IS THE FIGURE THAT SURVIVES A RESOLUTION CHANGE. A frame time alone cannot be
  // compared across two quality levels; a per-unit-of-work cost can.
  eld_puts("ENGINELAB-RAYS " as *u8)
  eld_kv("rays_per_frame=" as *u8, rays)
  eld_kv("render_self_us_total=" as *u8, rend_us)
  if rays > 0 {
      if frames > 0 {
          eld_kv("ns_per_ray=" as *u8, rend_us * ELD_NS_PER_US / (rays * frames))
      }
  }
  eld_kv("sim_us_total=" as *u8, tick_us)
  eld_kv("init_us=" as *u8, init_us)
  eld_nl()
314
  // THE BOUND VERDICT MUST ABSTAIN HERE AND THE REASON TRAVELS WITH IT.
  let bv: *i64 = eld_scratch()
  let bvr: i64 = el_bound_verdict(st, 0, EL_OCC_HI_DEFAULT, bv)
  eld_puts("ENGINELAB-BOUND " as *u8)
  if bvr == EL_BOUND_UNKNOWN {
      eld_kv("code=" as *u8, bvr)
      eld_puts("verdict=UNKNOWN reason=no-GPU-evidence-this-renderer-is-a-CPU-integer-raycaster-nothing-is-submitted-to-a-queue\n" as *u8)
  } else {
      eld_kv("code=" as *u8, bvr)
      eld_kv("gpu_occ_permil=" as *u8, bv[EL_BV_GPUOCC])
      eld_kv("cpu_occ_permil=" as *u8, bv[EL_BV_CPUOCC])
      eld_nl()
  }
328
  let mm: *i64 = eld_scratch()
  el_mem_stats(st, mm)
  eld_puts("ENGINELAB-MEM " as *u8)
  eld_kv("allocs=" as *u8, mm[EL_MEM_NALLOC])
  eld_kv("frees=" as *u8, mm[EL_MEM_NFREE])
  eld_kv("bytes_alloc=" as *u8, mm[EL_MEM_BALLOC])
  eld_kv("bytes_free=" as *u8, mm[EL_MEM_BFREE])
  eld_kv("orphan_frees=" as *u8, mm[EL_MEM_ORPHAN])
  eld_kv("live_bytes=" as *u8, mm[EL_MEM_BALLOC] - mm[EL_MEM_BFREE])
  eld_nl()
339
  // THE NAMED ABSENCE. Reported every run, in the same block as the numbers, so a reader can never
  // mistake draws=0 for a frame that issued no work.
  eld_puts("ENGINELAB-UNMEASURABLE draws=0 redundant_binds=0 pipeline_state=0 capture_diff=UNMEASURABLE replay=UNMEASURABLE " as *u8)
  eld_puts("reason=the-engine-emits-no-draw-stream " as *u8)
  eld_puts("owed=one-el_draw-call-inside-the-mob_draw-vis-branch-and-one-per-voxel-pass-in-render_impl " as *u8)
  eld_puts("owner=engine-lane-nx_wasm_craft\n" as *u8)
346
  let ov: *u8 = sys_mmap(EL_OV_TEXT_MAX)
  let ovn: i64 = el_overlay_emit(st, target_fps, q_permil, q_reason, rays, ov, EL_OV_TEXT_MAX)
  if ovn > 0 { sys_write(1, ov, ovn) }
  return closed
351}
352
353// ---- framebuffer -> image, for the golden verb ---------------------------------------------------
354// The renderer strips its depth plane after the mob composite, so the framebuffer holds packed
355// r | g<<8 | b<<16 and nothing else. Bound by the ENGINE extent (wc_rw x wc_rh), never by W x H:
356// a consumer that assumes the full grid reads unwritten memory and calls it a measurement.
357func eld_img(base: i64) -> *VdImg {
  let rw: i64 = wc_rw(base)
  let rh: i64 = wc_rh(base)
  let f: *i64 = wfb(base)
  let n: i64 = rw * rh
  let im: *VdImg = sys_mmap(VD_IMG_BYTES) as *VdImg
  let px: *u8 = sys_mmap(n * ELD_RGB_CH)
  var i: i64 = 0
  while i < n {
      let c: i64 = f[i]
      px[i*ELD_RGB_CH]     = (c & ELD_BYTE_MASK) as u8
      px[i*ELD_RGB_CH + 1] = ((c >> ELD_G_SHIFT) & ELD_BYTE_MASK) as u8
      px[i*ELD_RGB_CH + 2] = ((c >> ELD_B_SHIFT) & ELD_BYTE_MASK) as u8
      i = i + 1
  }
  im.px = px
  im.w = rw
  im.h = rh
  im.nc = ELD_RGB_CH
  return im
377}
378
379func eld_usage() -> i64 {
  eld_puts("usage: nx_enginelab frame   [v] [seed] [frames] [q] [target_fps]\n" as *u8)
  eld_puts("       nx_enginelab capture <out> [v] [seed] [frames] [q]  -- persist, reopen, prove identical\n" as *u8)
  eld_puts("       nx_enginelab golden  [v] [seed] [frames] [q] [grid] [thresh]  -- two runs, per-cell parity\n" as *u8)
  eld_puts("q=0 leaves the engine adaptive controller in charge and RECORDS what it chose; q>=1 pins it.\n" as *u8)
  return ELD_EXIT_USAGE
385}
386
387func main(argc: i64, argv: *i64) -> i64 {
  if argc < ELD_ARGV_VERB + 1 { sys_exit(eld_usage()) }
  let verb: *u8 = argv[ELD_ARGV_VERB] as *u8
  var ao: i64 = ELD_ARGV_VERB
  var outp: *u8 = 0 as *u8
  var mode_frame: i64 = 0
  var mode_cap: i64 = 0
  var mode_gold: i64 = 0
  if eld_streq(verb, "frame" as *u8) == 1 { mode_frame = 1 }
  if eld_streq(verb, "capture" as *u8) == 1 { mode_cap = 1 }
  if eld_streq(verb, "golden" as *u8) == 1 { mode_gold = 1 }
  if mode_frame + mode_cap + mode_gold == 0 { sys_exit(eld_usage()) }
  if mode_cap == 1 {
      if argc < ao + 2 { sys_exit(eld_usage()) }
      outp = argv[ao + 1] as *u8
      ao = ao + 1
  }
  var v: i64 = 0
  if argc > ao + 1 { v = eld_int(argv[ao + 1] as *u8) }
  var seed: i64 = ELD_SEED_DEFAULT
  if argc > ao + 2 { seed = eld_int(argv[ao + 2] as *u8) }
  var frames: i64 = ELD_FRAMES_DEFAULT
  if argc > ao + 3 { frames = eld_int(argv[ao + 3] as *u8) }
  var q: i64 = ELD_Q_DEFAULT
  if argc > ao + 4 { q = eld_int(argv[ao + 4] as *u8) }
  var target_fps: i64 = ELD_TARGET_FPS_DEFAULT
  var grid: i64 = ELD_GRID_DEFAULT
  var thresh: i64 = ELD_THRESH_DEFAULT
  if mode_frame == 1 { if argc > ao + 5 { target_fps = eld_int(argv[ao + 5] as *u8) } }
  if mode_gold == 1 {
      if argc > ao + 5 { grid = eld_int(argv[ao + 5] as *u8) }
      if argc > ao + 6 { thresh = eld_int(argv[ao + 6] as *u8) }
  }
420
  // NEG-CONTROL BY CONSTRUCTION: a run with no frames has no subject, and the driver refuses rather
  // than reporting a healthy-looking zero.
  if frames < 1 {
      eld_puts("ENGINELAB-REFUSED verdict=UNMEASURABLE frames=0 reason=a-run-with-no-frames-has-no-subject\n" as *u8)
      sys_exit(ELD_EXIT_UNMEASURABLE)
  }
427
  let st: *i64 = el_new(eld_store_cap(frames))
  if el_ok(st) == 0 {
      eld_puts("ENGINELAB-REFUSED verdict=UNMEASURABLE reason=store-allocation-failed\n" as *u8)
      sys_exit(ELD_EXIT_UNMEASURABLE)
  }
  let base: i64 = eld_run(st, v, seed, q, frames)
  if base == 0 {
      eld_puts("ENGINELAB-REFUSED verdict=UNMEASURABLE reason=engine-arena-allocation-failed\n" as *u8)
      sys_exit(ELD_EXIT_UNMEASURABLE)
  }
  let closed: i64 = eld_report(st, base, v, seed, q, frames, target_fps)
439
  if mode_cap == 1 {
      // EL1 ON REAL DATA. Write the capture, reopen it, and compare EVERY field of EVERY record
      // plus the header counters. A round-trip that only checked the count would pass a capture
      // whose payload was scrambled.
      let wr: i64 = el_capture_write(st, outp)
      eld_puts("ENGINELAB-CAPTURE " as *u8)
      eld_kv("write_rc=" as *u8, wr)
      if wr != ELS_OK {
          eld_puts("verdict=WRITE-REFUSED\n" as *u8)
          sys_exit(ELD_EXIT_FAIL)
      }
      let rs: *i64 = eld_scratch()
      let rd: *i64 = el_capture_read(outp, rs)
      if (rd as i64) == 0 {
          eld_kv("read_reason=" as *u8, rs[ELS_R_CODE])
          eld_kv("declared=" as *u8, rs[ELS_R_DECLARED])
          eld_kv("actual=" as *u8, rs[ELS_R_ACTUAL])
          eld_puts("verdict=READ-REFUSED\n" as *u8)
          sys_exit(ELD_EXIT_FAIL)
      }
      var same: i64 = 1
      if el_count(rd) != el_count(st) { same = 0 }
      if el_dropped(rd) != el_dropped(st) { same = 0 }
      if el_complete(rd) != el_complete(st) { same = 0 }
      var ci: i64 = 0
      while ci < el_count(st) {
          var cf: i64 = 0
          while cf < EL_REC {
              if el_get(rd, ci, cf) != el_get(st, ci, cf) { same = 0 }
              cf = cf + 1
          }
          ci = ci + 1
      }
      // AND THE DERIVED FIGURES TOO: identical records that produced a different median would mean
      // the analysis depends on something the capture does not carry.
      let ka: *i64 = eld_scratch()
      let kb: *i64 = eld_scratch()
      el_frame_stats(st, EL_STUTTER_NUM_DEFAULT, EL_STUTTER_DEN_DEFAULT, ka)
      el_frame_stats(rd, EL_STUTTER_NUM_DEFAULT, EL_STUTTER_DEN_DEFAULT, kb)
      var derived_same: i64 = 1
      var sx: i64 = 0
      while sx < EL_FS_SLOTS {
          if ka[sx] != kb[sx] { derived_same = 0 }
          sx = sx + 1
      }
      eld_kv("records=" as *u8, el_count(st))
      eld_kv("records_identical=" as *u8, same)
      eld_kv("derived_identical=" as *u8, derived_same)
      if same == 1 { if derived_same == 1 { eld_puts("verdict=ROUNDTRIP-IDENTICAL\n" as *u8) } }
      if same == 0 {
          eld_puts("verdict=ROUNDTRIP-DIVERGENT\n" as *u8)
          sys_exit(ELD_EXIT_FAIL)
      }
      if derived_same == 0 {
          eld_puts("verdict=DERIVED-DIVERGENT\n" as *u8)
          sys_exit(ELD_EXIT_FAIL)
      }
  }
498
  if mode_gold == 1 {
      // DETERMINISM OF THE REAL RENDERER, PER CELL. Two INDEPENDENT runs in two separate arenas,
      // same v and seed: the estate character bench lists bit-determinism as a HAVE axis, and this
      // is the first time it has been measured on the real render path with a per-cell ruler
      // rather than asserted. A whole-image compare would say only same or different; a grid says
      // WHERE, which is the only form a regression report can act on.
      let ia: *VdImg = eld_img(base)
      let st2: *i64 = el_new(eld_store_cap(frames))
      let base2: i64 = eld_run(st2, v, seed, q, frames)
      if base2 == 0 {
          eld_puts("ENGINELAB-GOLDEN verdict=UNMEASURABLE reason=second-arena-allocation-failed\n" as *u8)
          sys_exit(ELD_EXIT_UNMEASURABLE)
      }
      let ib: *VdImg = eld_img(base2)
      let g: *i64 = eld_scratch()
      let gr: i64 = el_golden(ia, 0, ib, 0, ia.w, ia.h, grid, grid, thresh,
                              EL_GOLD_PASS_PERMIL_DEFAULT, g)
      eld_puts("ENGINELAB-GOLDEN " as *u8)
      eld_kv("w=" as *u8, ia.w)
      eld_kv("h=" as *u8, ia.h)
      eld_kv("grid=" as *u8, grid)
      eld_kv("thresh=" as *u8, thresh)
      eld_kv("cells_total=" as *u8, g[EL_GD_TOTAL])
      eld_kv("cells_matched=" as *u8, g[EL_GD_MATCH])
      eld_kv("permil=" as *u8, g[EL_GD_PERMIL])
      if gr == EL_GOLD_PASS { eld_puts("verdict=PASS subject=engine-determinism-same-seed-two-arenas\n" as *u8) }
      if gr == EL_GOLD_FAIL { eld_puts("verdict=FAIL subject=engine-determinism-same-seed-two-arenas\n" as *u8) }
      if gr == EL_GOLD_UNMEASURABLE { eld_puts("verdict=UNMEASURABLE reason=no-comparable-window\n" as *u8) }
      if gr == EL_GOLD_FAIL { sys_exit(ELD_EXIT_FAIL) }
      if gr == EL_GOLD_UNMEASURABLE { sys_exit(ELD_EXIT_UNMEASURABLE) }
  }
530
  if closed < ELD_MIN_CLOSED_FRAMES { sys_exit(ELD_EXIT_UNMEASURABLE) }
  sys_exit(ELD_EXIT_OK)
  return ELD_EXIT_OK
534}
nx_enginelab.nx source

`nx_enginelab.nx` source
