test(enginetest): quant-parity harness — pure-Go affine reference vs BackendQuant (rocm #13)

engine/enginetest had session/textmodel conformance suites but no
quant-parity check. Add one, runnable in CI with no accelerator
present (arithmetic, not throughput):

- quant_reference.go: ReferenceAffineMatVec, a pure-Go, engine-free
  reimplementation of the group-affine dequant+matvec contract
  (model.QuantMatVec.MatVec, model/quant.go) — LSB-first bit-packed
  codes, one bf16 scale+bias per group, float64 accumulation. Imports
  no engine package, so agreement is evidence of correctness, not
  self-consistency.
- quant_parity.go: QuantParity(t, backend) fetches
  model.BackendQuant(backend, "affine"), runs it against a small
  deterministic fixture, and compares to the reference (byte-identical
  fast path, else a documented per-element bf16 tolerance for
  accumulation-order differences). Absent registration skips and
  reports, matching SessionHandle/TextModel's optional-capability shape.
- quant_reference_test.go: self-test of the reference alone — a
  hand-checked single-group case (dot product lands on an
  exactly-bf16-representable value, so the expected bytes are pinned
  exactly), validation-surface and zero-sized cases, and a fixture/
  codec round-trip.
- engine/metal/model_quant_parity_test.go wires engine/metal as the
  proving consumer: TestNativeAffineQuantParity calls
  enginetest.QuantParity(t, "native") against affineQMV.MatVec
  (model_quant.go) — real GPU dispatch via QMVBF16, not a mock.

Metal proof, run on this Mac (MLX_METALLIB_PATH pointed at a
pre-built mlx.metallib from a sibling checkout of this repo; no
special build tag needed — plain darwin/arm64 + the existing
requireNativeRuntime skip-guard, matching qmv_test.go/gemv_test.go):

  MLX_METALLIB_PATH=/Users/snider/Code/core/go-inference/build/dist/lib/mlx.metallib \
    go test -v -count=1 -run TestNativeAffineQuantParity ./engine/metal/...

  === RUN   TestNativeAffineQuantParity
  --- PASS: TestNativeAffineQuantParity (0.05s)
  PASS
  ok  	dappco.re/go/inference/engine/metal	0.482s

go test ./engine/enginetest/...: 36 passed, 0 failed.

Co-Authored-By: Virgil <virgil@lethean.io>

Author: Snider

go/engine/enginetest/quant_parity.go

@@ -0,0 +1,108 @@
+// SPDX-Licence-Identifier: EUPL-1.2
+
+package enginetest
+
+import (
+	"bytes"
+	"math"
+	"testing"
+
+	"dappco.re/go/inference/model"
+)
+
+// affineParityTol bounds the per-element float32 gap QuantParity accepts when a
+// backend's MatVec is not byte-identical to ReferenceAffineMatVec. Two correct
+// implementations of the same group-affine dot product can still land on
+// different bf16 output bytes: a GPU kernel reduces inDim terms with a
+// parallel/tree accumulation order, this reference sums serially in float64 —
+// the two orders round differently at the final bf16 store even when every
+// intermediate is exact. The tolerance is documented, not tuned to pass: it is
+// a small multiple of one bf16 ULP (~2^-7 relative) at the fixture's O(1)
+// output magnitude, not a value picked after the fact to make a divergent
+// implementation pass.
+const affineParityTol = 0.05
+
+// quantAffineFixture builds a small, fully deterministic group-affine
+// fixture — every value is a formula, never randomness, so a divergence
+// between two runs (or two backends) is always a real behavioural
+// difference, never fixture noise. outDim=8, inDim=128, groupSize=64, bits=4
+// mirrors the (groupSize, bits) pairing engine/metal's own real-dispatch
+// quant tests already exercise (qgemv_test.go, arch_session_bench_test.go) —
+// a combination the metallib's compiled kernel templates are known to
+// instantiate — while staying a unit-scale, no-accelerator-required check.
+func quantAffineFixture() (x, packed, scales, biases []byte, outDim, inDim, groupSize, bits int) {
+	outDim, inDim, groupSize, bits = 8, 128, 64, 4
+	groupsPerRow := inDim / groupSize
+	rowPacked := inDim * bits / 8
+	rowSB := groupsPerRow * 2
+	maxCode := uint32(1)<<uint(bits) - 1
+
+	packed = make([]byte, outDim*rowPacked)
+	scales = make([]byte, outDim*rowSB)
+	biases = make([]byte, outDim*rowSB)
+	for r := 0; r < outDim; r++ {
+		pRow := packed[r*rowPacked : (r+1)*rowPacked]
+		sRow := scales[r*rowSB : (r+1)*rowSB]
+		bRow := biases[r*rowSB : (r+1)*rowSB]
+		for g := 0; g < groupsPerRow; g++ {
+			scale := 0.25 + 0.125*float32(g+r)
+			bias := -1 + 0.5*float32((g+r)%3)
+			sh, bh := bf16Encode(scale), bf16Encode(bias)
+			sRow[g*2], sRow[g*2+1] = byte(sh), byte(sh>>8)
+			bRow[g*2], bRow[g*2+1] = byte(bh), byte(bh>>8)
+			for j := 0; j < groupSize; j++ {
+				c := g*groupSize + j
+				code := uint32(c*5+r*3+1) % (maxCode + 1)
+				affineSetCode(pRow, c*bits, bits, code)
+			}
+		}
+	}
+	x = make([]byte, inDim*2)
+	for i := 0; i < inDim; i++ {
+		v := 0.1 * float32((i%7)-3)
+		h := bf16Encode(v)
+		x[i*2], x[i*2+1] = byte(h), byte(h>>8)
+	}
+	return x, packed, scales, biases, outDim, inDim, groupSize, bits
+}
+
+// QuantParity validates a backend's registered "affine" quant compute
+// (model.BackendQuant(backend, "affine"), model/quant.go) against the
+// pure-Go ReferenceAffineMatVec on a small deterministic fixture: it checks
+// arithmetic correctness, not throughput, so it runs in CI with no
+// accelerator present. A backend that has not registered the "affine" kind
+// is reported and skipped — present ⇒ exercised, absent ⇒ skipped and
+// reported, the same optional-capability shape SessionHandle/TextModel use
+// for their own probed capabilities (session.go, textmodel.go).
+func QuantParity(t *testing.T, backend string) {
+	t.Helper()
+	q, ok := model.BackendQuant(backend, "affine")
+	if !ok {
+		t.Skipf("no backend quant registered for (%q, %q) — nothing to check", backend, "affine")
+	}
+
+	x, packed, scales, biases, outDim, inDim, groupSize, bits := quantAffineFixture()
+
+	got, err := q.MatVec(x, packed, scales, biases, outDim, inDim, groupSize, bits)
+	if err != nil {
+		t.Fatalf("%s/affine MatVec: %v", backend, err)
+	}
+	want, err := ReferenceAffineMatVec(x, packed, scales, biases, outDim, inDim, groupSize, bits)
+	if err != nil {
+		t.Fatalf("ReferenceAffineMatVec (harness bug): %v", err)
+	}
+	if len(got) != len(want) {
+		t.Fatalf("%s/affine MatVec output length = %d, want %d", backend, len(got), len(want))
+	}
+	if bytes.Equal(got, want) {
+		return // byte-identical — the strongest receipt
+	}
+	for i := 0; i < outDim; i++ {
+		gv := float64(bf16Decode(got[i*2], got[i*2+1]))
+		wv := float64(bf16Decode(want[i*2], want[i*2+1]))
+		if d := math.Abs(gv - wv); d > affineParityTol {
+			t.Fatalf("%s/affine MatVec[%d] = %v, reference = %v (diff %v > tol %v)",
+				backend, i, gv, wv, d, affineParityTol)
+		}
+	}
+}

go/engine/enginetest/quant_reference.go

@@ -0,0 +1,127 @@
+// SPDX-Licence-Identifier: EUPL-1.2
+
+package enginetest
+
+import (
+	"math"
+
+	core "dappco.re/go"
+)
+
+// quant_reference.go is the pure-Go, engine-independent reference for the
+// group-affine weight-quant decode projection every backend registers against
+// model.BackendQuant(backend, "affine") (model/quant.go): dequantise a packed
+// row — LSB-first bit-packed codes, one bf16 scale+bias per group — to
+// float32, then dot with the bf16 activation vector. It imports no engine
+// package: the group-affine format (MLX's packing scheme) is reimplemented
+// independently here rather than borrowed from any backend's own dequantizer,
+// so agreement between a backend's MatVec and ReferenceAffineMatVec is
+// evidence the backend's arithmetic is correct, not merely self-consistent
+// with itself.
+
+// bf16Decode reads one little-endian bfloat16 (2 bytes: lo, hi) as float32.
+func bf16Decode(lo, hi byte) float32 {
+	return math.Float32frombits(uint32(uint16(lo)|uint16(hi)<<8) << 16)
+}
+
+// bf16Encode converts a float32 to bfloat16 bits with round-to-nearest-even.
+func bf16Encode(v float32) uint16 {
+	bits := math.Float32bits(v)
+	if bits&0x7fffffff > 0x7f800000 { // NaN: keep it quiet, non-zero mantissa
+		return uint16(bits>>16) | 0x0040
+	}
+	rounding := (bits>>16)&1 + 0x7fff
+	return uint16((bits + rounding) >> 16)
+}
+
+// affineExtractCode reads the bits-wide affine code at bit offset bitOff from a
+// packed row, LSB-first contiguous — MLX's group-affine packing (for 4-bit this
+// is the familiar low-nibble-then-high-nibble layout; other widths span byte
+// boundaries the same way).
+func affineExtractCode(p []byte, bitOff, bits int) uint32 {
+	var v uint32
+	for got := 0; got < bits; {
+		bi := (bitOff + got) / 8
+		off := (bitOff + got) % 8
+		take := min(8-off, bits-got)
+		chunk := (uint32(p[bi]) >> uint(off)) & ((1 << uint(take)) - 1)
+		v |= chunk << uint(got)
+		got += take
+	}
+	return v
+}
+
+// affineSetCode writes a bits-wide code at bit offset bitOff within p,
+// LSB-first across byte boundaries — the exact inverse of affineExtractCode.
+// Used only to build this package's own deterministic fixtures (quant_parity.go).
+func affineSetCode(p []byte, bitOff, bits int, code uint32) {
+	for got := 0; got < bits; {
+		bi := (bitOff + got) / 8
+		off := (bitOff + got) % 8
+		take := min(8-off, bits-got)
+		mask := byte((1<<uint(take))-1) << uint(off)
+		shifted := byte((code >> uint(got)) << uint(off))
+		p[bi] = (p[bi] &^ mask) | (shifted & mask)
+		got += take
+	}
+}
+
+// ReferenceAffineMatVec is the pure-Go reference for the group-affine quant
+// decode projection: out = x @ Wᵀ for a group-affine quantised (outDim x inDim)
+// weight — bf16 activations in, bf16 result out — matching model.QuantMatVec's
+// MatVec contract (model/quant.go) exactly, so a backend's registered
+// implementation and this function are directly comparable on the same
+// fixture. packed/scales/biases follow MLX's group-affine layout: packed is
+// outDim*inDim*bits/8 LSB-first bit-packed codes; scales and biases are each
+// outDim*(inDim/groupSize) bf16 values, one pair per group per row; the
+// dequantised weight element is scale*code+bias. The row/activation dot
+// product accumulates in float64 for a stable, order-independent reference sum.
+func ReferenceAffineMatVec(x, packed, scales, biases []byte, outDim, inDim, groupSize, bits int) ([]byte, error) {
+	if outDim < 0 || inDim < 0 {
+		return nil, core.NewError("enginetest.ReferenceAffineMatVec: outDim/inDim must be non-negative")
+	}
+	if outDim == 0 || inDim == 0 {
+		return make([]byte, outDim*2), nil
+	}
+	if bits <= 0 || bits > 8 {
+		return nil, core.NewError("enginetest.ReferenceAffineMatVec: bits must be in 1..8")
+	}
+	if groupSize <= 0 || inDim%groupSize != 0 {
+		return nil, core.NewError("enginetest.ReferenceAffineMatVec: groupSize must be > 0 and divide inDim")
+	}
+	if inDim*bits%8 != 0 {
+		return nil, core.NewError("enginetest.ReferenceAffineMatVec: inDim*bits must be byte-aligned")
+	}
+	if len(x) != inDim*2 {
+		return nil, core.NewError("enginetest.ReferenceAffineMatVec: len(x) must equal inDim bf16 bytes")
+	}
+	rowPacked := inDim * bits / 8
+	rowSB := (inDim / groupSize) * 2
+	if len(packed) != outDim*rowPacked || len(scales) != outDim*rowSB || len(biases) != outDim*rowSB {
+		return nil, core.NewError("enginetest.ReferenceAffineMatVec: packed/scales/biases size mismatch")
+	}
+
+	xf := make([]float64, inDim)
+	for i := range xf {
+		xf[i] = float64(bf16Decode(x[i*2], x[i*2+1]))
+	}
+
+	out := make([]byte, outDim*2)
+	for r := 0; r < outDim; r++ {
+		pRow := packed[r*rowPacked : (r+1)*rowPacked]
+		sRow := scales[r*rowSB : (r+1)*rowSB]
+		bRow := biases[r*rowSB : (r+1)*rowSB]
+		var acc float64
+		for c := 0; c < inDim; c++ {
+			g := c / groupSize
+			scale := bf16Decode(sRow[g*2], sRow[g*2+1])
+			bias := bf16Decode(bRow[g*2], bRow[g*2+1])
+			code := affineExtractCode(pRow, c*bits, bits)
+			w := float64(scale)*float64(code) + float64(bias)
+			acc += w * xf[c]
+		}
+		h := bf16Encode(float32(acc))
+		out[r*2], out[r*2+1] = byte(h), byte(h>>8)
+	}
+	return out, nil
+}

go/engine/enginetest/quant_reference_test.go

@@ -0,0 +1,109 @@
+// SPDX-Licence-Identifier: EUPL-1.2
+
+package enginetest
+
+import "testing"
+
+// TestReferenceAffineMatVec_Good pins the reference's arithmetic on a
+// hand-checkable single-group case: 1 row, 2 columns, one group of 2,
+// scale=2, bias=1, codes [3,5] → dequantised weight [7,11]; x=[1.0,0.5] →
+// dot=12.5, which bf16 represents exactly (its mantissa bits beyond bf16's 7
+// are all zero), so the expected output bytes are pinned exactly rather than
+// tolerance-compared.
+func TestReferenceAffineMatVec_Good(t *testing.T) {
+	const outDim, inDim, groupSize, bits = 1, 2, 2, 4
+	packed := make([]byte, outDim*inDim*bits/8)
+	affineSetCode(packed, 0*bits, bits, 3)
+	affineSetCode(packed, 1*bits, bits, 5)
+	if packed[0] != 0x53 {
+		t.Fatalf("fixture packing: packed[0] = %#x, want 0x53", packed[0])
+	}
+	sh := bf16Encode(2.0)
+	bh := bf16Encode(1.0)
+	scales := []byte{byte(sh), byte(sh >> 8)}
+	biases := []byte{byte(bh), byte(bh >> 8)}
+	xh0, xh1 := bf16Encode(1.0), bf16Encode(0.5)
+	x := []byte{byte(xh0), byte(xh0 >> 8), byte(xh1), byte(xh1 >> 8)}
+
+	got, err := ReferenceAffineMatVec(x, packed, scales, biases, outDim, inDim, groupSize, bits)
+	if err != nil {
+		t.Fatalf("ReferenceAffineMatVec: %v", err)
+	}
+	want := bf16Encode(12.5)
+	if got[0] != byte(want) || got[1] != byte(want>>8) {
+		gv := bf16Decode(got[0], got[1])
+		t.Fatalf("ReferenceAffineMatVec = %v (bytes %#x %#x), want 12.5 (bytes %#x %#x)",
+			gv, got[0], got[1], byte(want), byte(want>>8))
+	}
+}
+
+// TestReferenceAffineMatVec_Bad pins the validation surface: a malformed
+// fixture is rejected with an error, never a panic or a silently wrong answer.
+func TestReferenceAffineMatVec_Bad(t *testing.T) {
+	x, packed, scales, biases, outDim, inDim, groupSize, bits := quantAffineFixture()
+
+	if _, err := ReferenceAffineMatVec(x[:len(x)-1], packed, scales, biases, outDim, inDim, groupSize, bits); err == nil {
+		t.Error("short x must be rejected")
+	}
+	if _, err := ReferenceAffineMatVec(x, packed[:len(packed)-1], scales, biases, outDim, inDim, groupSize, bits); err == nil {
+		t.Error("short packed must be rejected")
+	}
+	if _, err := ReferenceAffineMatVec(x, packed, scales, biases, outDim, inDim, 3, bits); err == nil {
+		t.Error("groupSize not dividing inDim must be rejected")
+	}
+	if _, err := ReferenceAffineMatVec(x, packed, scales, biases, outDim, inDim, groupSize, 0); err == nil {
+		t.Error("bits <= 0 must be rejected")
+	}
+	if _, err := ReferenceAffineMatVec(x, packed, scales, biases, outDim, inDim, groupSize, 9); err == nil {
+		t.Error("bits > 8 must be rejected")
+	}
+}
+
+// TestReferenceAffineMatVec_Ugly pins the zero-sized surprising-but-valid
+// case: outDim or inDim of 0 returns a clean empty result, mirroring the
+// backends' own zero-sized MatVec fast path (e.g. engine/metal's
+// QMVBF16Into), never an error.
+func TestReferenceAffineMatVec_Ugly(t *testing.T) {
+	got, err := ReferenceAffineMatVec(nil, nil, nil, nil, 0, 0, 64, 4)
+	if err != nil {
+		t.Fatalf("zero-sized ReferenceAffineMatVec: %v", err)
+	}
+	if len(got) != 0 {
+		t.Fatalf("zero-sized ReferenceAffineMatVec length = %d, want 0", len(got))
+	}
+}
+
+// TestQuantAffineFixtureRoundTrips_Good checks quant_parity.go's own fixture
+// builder against affineExtractCode — the packer and the reference's own
+// unpacker must agree on every code, or QuantParity would be comparing two
+// backends against a fixture that doesn't mean what it claims to.
+func TestQuantAffineFixtureRoundTrips_Good(t *testing.T) {
+	_, packed, _, _, outDim, inDim, _, bits := quantAffineFixture()
+	rowPacked := inDim * bits / 8
+	maxCode := uint32(1)<<uint(bits) - 1
+	for r := 0; r < outDim; r++ {
+		pRow := packed[r*rowPacked : (r+1)*rowPacked]
+		for c := 0; c < inDim; c++ {
+			want := uint32(c*5+r*3+1) % (maxCode + 1)
+			if got := affineExtractCode(pRow, c*bits, bits); got != want {
+				t.Fatalf("row %d col %d: affineExtractCode = %d, want %d", r, c, got, want)
+			}
+		}
+	}
+}
+
+// TestBF16RoundTrip_Good pins the codec pair this whole file leans on: every
+// value bf16Encode produces, bf16Decode must read back losslessly (bf16
+// encoding is already the lossy step; decoding a valid bf16 value is exact).
+func TestBF16RoundTrip_Good(t *testing.T) {
+	for _, v := range []float32{0, 1, -1, 12.5, 0.25, -3.75, 100, -0.03125} {
+		h := bf16Encode(v)
+		got := bf16Decode(byte(h), byte(h>>8))
+		// bf16 keeps the top 8 bits of mantissa context (7 explicit + implicit
+		// leading 1); values here are chosen exactly representable in bf16, so
+		// the round trip must be exact.
+		if got != v {
+			t.Errorf("bf16 round trip: encode/decode(%v) = %v, want exact", v, got)
+		}
+	}
+}

go/engine/metal/model_quant_parity_test.go

@@ -0,0 +1,24 @@
+// SPDX-Licence-Identifier: EUPL-1.2
+
+//go:build darwin && arm64
+
+package native
+
+import (
+	"testing"
+
+	"dappco.re/go/inference/engine/enginetest"
+)
+
+// TestNativeAffineQuantParity is engine/metal's proving consumer of
+// enginetest.QuantParity (rocm design #13): it fetches this backend's
+// registered "native"/"affine" quant compute (model_quant.go, affineQMV.MatVec)
+// and checks it against the pure-Go group-affine reference on a small
+// deterministic fixture — real GPU dispatch through QMVBF16, not a mock.
+// Skips cleanly without MLX_METALLIB_PATH, exactly like this package's other
+// real-dispatch quant tests (requireNativeRuntime, test_helpers_test.go;
+// e.g. TestQMVBF16AllocationBudget, qmv_test.go).
+func TestNativeAffineQuantParity(t *testing.T) {
+	requireNativeRuntime(t)
+	enginetest.QuantParity(t, "native")
+}