nx_enginelab_lib.nx

nx_enginelab_lib.nx -- THE SOVEREIGN ENGINE INSTRUMENT (library half). WHAT THIS IS. The open-source engine-testing field ships five SEPARATE programs with five SEPARATE capture formats: a frame debugger (draw calls + pipeline state), a CPU zone profiler (nanosecond scopes, threads, allocations, lock waits), a telemetry overlay (frame pacing, lows, stutter), a GPU scheduling visualiser (queue slices, vsync, CPU-bound vs GPU-bound), and an automated visual-regression harness (golden images). Each is excellent alone. THE DEFECT THE FIELD LIVES WITH, AND OUR EXCEED. Because those five captures are five files with five clocks, A FRAME-TIME SPIKE CAN NEVER BE JOINED TO THE DRAW CALL THAT CAUSED IT. You see the spike in one tool and go hunting in another, by hand, by eye. Here every subsystem writes into ONE record layout on ONE clock, so the join is arithmetic rather than detective work: el_frame_attr answers 'this frame cost 41ms; of that, N draws, X us of GPU queue, Y us of CPU root zones, Z us of lock wait, B bytes allocated'. That is the whole reason for a single spine, and it is the mechanism no separate-format tool can offer. LAWS MADE STRUCTURAL HERE, not left to the caller to remember: - NO SILENT CAPS. A full store REFUSES and counts the refusal (EL_H_DROP). Every report carries dropped= so a truncated measurement can never read as a complete one. - ABSTAIN, NEVER ACQUIT. Every verdict has a third state. A bound-verdict with no GPU evidence returns UNKNOWN, not CPU-BOUND. A capture diff over ZERO draws returns UNMEASURABLE, not 'identical' -- the empty-set-passes defect wearing a profiler costume. - THE REASON TRAVELS WITH THE COUNT. Errors are split by cause (non-monotonic clock, stack overflow, end-without-begin), never merged into one number nobody can act on. - COMPOSE, NEVER RE-IMPLEMENT. Rolling FPS is nx_fpsmeter (fm_init/fm_tick/fm_fps), the frame budget is nx_frame_budget (fb_budget_us/fb_fits/fb_headroom_us) and image parity is nx_visual_diff (vd_grid_parity). There is exactly one of each ruler in this estate and this file adds none of them. - THRESHOLDS ARE PARAMETERS. Every bar (bound occupancy, stutter multiple, golden pass line) is an argument with a named default const, so it can be driven from conf and never hides in code. license_tier: ORIGINAL No hardware writes (Rule 26): this reads and computes, it never programs a device. Pure integer arithmetic, wasm-friendly, daemon-reusable.