nx_refbench_lib.nx

nx_refbench_lib.nx -- THE REFERENCE-RETENTION KERNEL (shared by the tool and its gate). Extracted as a lib on day one so the CLI (nx_refbench.nx) and the gate (nx_refbench_gate.nx) measure with the SAME code. A gate that re-implements the thing it is grading proves nothing about the thing that ships. THE QUESTION: when we generate FROM a reference image, how much of the reference actually survived? Prompt-only round-trips were already MEASURED to be a lossy codec (semantics ~85%, geometry ~50%, identity 0%) -- which is why the L2/L3/L4 structure channels exist. But an unmeasured channel is an UNPROVEN channel: without a ruler, "img2img preserved the composition" is an opinion. TWO INDEPENDENT CHANNELS, HEADLINE = MIN. A generator can hold global layout while destroying local structure, or hold local structure while shifting every tone. Those are DIFFERENT failures with DIFFERENT fixes, so they get different numbers and the headline reports the WEAKEST -- per the report-MIN-across-judges discipline. One blended number is not a measurement. * structure = SSIM (Wang 2004) on a common plane: local luminance/contrast/covariance. * perceptual = dHash Hamming (Krawetz 2011): RELATIVE order of adjacent pixels, so it is invariant to uniform brightness/contrast and robust to rescale. Agreement between two independent descriptors is evidence; a single descriptor is a target waiting to be gamed. COMPOSES ONLY PROVEN ORGANS -- zero new ranking or resize math: nx_png_decoder, nx_image (canonical *Image), nx_ssim, nx_phash (whose downscale kernel is reused as the common-resolution plane, so a 2550x3300 reference and a 768x1024 render are compared at ONE scale by ONE kernel instead of growing a second resampler). license_tier: ORIGINAL