nx_enginelab_golden.nx source

1// nx_enginelab_golden.nx -- GOLDEN-IMAGE REGRESSION for the engine instrument (the O3DE class). 2// 3// WHY THIS IS ITS OWN MODULE, EXTRACTED FROM nx_enginelab_lib ON 2026-08-28. It started life inside 4// the core spine, and that was wrong for a measurable reason rather than a stylistic one: the spine 5// is frames, CPU zones, GPU queue slices, draw calls, allocations and lock waits -- ALL PURE INTEGER, 6// and deliberately so, because the natural first consumer of an engine instrument is the engine, and 7// this estate's engines compile to wasm. Golden-image comparison is the one row that needs to read a 8// PNG, so keeping it in the core made EVERY consumer of the integer spine import nx_visual_diff and 9// with it a PNG decoder, for a capability most of them will never call. 10// A CAPABILITY THAT TAXES EVERY CONSUMER FOR A FEATURE MOST OF THEM NEVER CALL BELONGS IN ITS OWN 11// MODULE -- and the cost is not theoretical: it is paid by whichever organ adopts the spine first. 12// Nothing about the behaviour changed in the move. el_golden is byte-for-byte the same function, its 13// refusal still propagates, and the gate that proves it is unchanged -- which is exactly why the 14// extraction is provable: the gate must stay 38 of 38 GREEN across it, and a same-verdict run on a 15// smaller closure is the whole evidence for the split. 16// license_tier: ORIGINAL No hardware writes (Rule 26). 17import "nx_syscalls.nx" 18import "nx_visual_diff.nx" 19import "nx_enginelab_lib.nx" 20 21// COMPOSES nx_visual_diff.vd_grid_parity IN-PROCESS. Not forked: handing a whole-image walker the 22// wrong shape of argument is how a zero-subject run comes back GREEN, and an in-process call cannot 23// silently examine nothing. 24const EL_GOLD_PASS: i64 = 0 25const EL_GOLD_FAIL: i64 = 1 26const EL_GOLD_UNMEASURABLE: i64 = 3 27const EL_GOLD_PASS_PERMIL_DEFAULT: i64 = 1000 // every cell must match by default 28const EL_GD_PERMIL: i64 = 0 29const EL_GD_MATCH: i64 = 1 30const EL_GD_TOTAL: i64 = 2 31const EL_GD_SLOTS: i64 = 3 32 33func el_golden(a: *VdImg, ay: i64, b: *VdImg, by: i64, cw: i64, ch: i64, 34 gx: i64, gy: i64, thresh: i64, pass_permil: i64, out: *i64) -> i64 { 35 // vd_grid_parity's own worst-cell slots ride after our three, so the caller can read which cells 36 // failed from the same buffer. 37 let vout: *i64 = sys_mmap((2 + VD_WORST_SLOTS * 3) * EL_I64) as *i64 38 let r: i64 = vd_grid_parity(a, ay, b, by, cw, ch, gx, gy, thresh, vout) 39 // THE REFUSAL PROPAGATES. vd_grid_parity returns -1 for a window it cannot actually measure, and 40 // it does so because that exact case once banked eight 'perfect' frames that were never compared. 41 // Turning that refusal into a pass here would re-open the defect one layer up. 42 if r < 0 { 43 out[EL_GD_PERMIL] = 0 - 1 44 out[EL_GD_MATCH] = 0 - 1 45 out[EL_GD_TOTAL] = 0 - 1 46 sys_munmap(vout as *u8, (2 + VD_WORST_SLOTS * 3) * EL_I64) 47 return EL_GOLD_UNMEASURABLE 48 } 49 out[EL_GD_PERMIL] = r 50 out[EL_GD_MATCH] = vout[0] 51 out[EL_GD_TOTAL] = vout[1] 52 sys_munmap(vout as *u8, (2 + VD_WORST_SLOTS * 3) * EL_I64) 53 if out[EL_GD_TOTAL] <= 0 { return EL_GOLD_UNMEASURABLE } 54 if r >= pass_permil { return EL_GOLD_PASS } 55 return EL_GOLD_FAIL 56}