feat(backend-cpu): route the generic matmul path through the kernel registry (SKEEP-003 P3, S1.7b)

[michalharakal]

Summary

SKEEP-003 slice S1.7b (milestone M1 #1002, PRD M1-F5 / M1-A4): the generic matmul path in DefaultCpuOps (commonMain) now goes through the kernel registry — the first slice where behaviour actually moves, kept deliberately narrow.

What does not change: the packed-quant fast paths (chooseQuantizedMatmulHeap → the registered scalar/vector kernels) and the FP32 2D×2D fast path run exactly as before. No hot path is touched, so the benchmarks stay where they were.

What changes: the fallback — the path where #993 crashed. matmul now tries dispatchMatmulViaRegistry() before matmulGeneric():

• both operands describe themselves as TensorViews (TensorData.view, from feat(memory): TensorData exposes a zero-copy TensorView — dense, narrow-float and MemorySegment façades (SKEEP-003 P2, S1.4a) #1068/feat(memory): packed TensorData façades — every GGML block format and ternary expose a zero-copy, bit-identical TensorView (SKEEP-003 P2, S1.4b) #1069);
• the weight is transposed as a view (no copy);
• the activation is normalised once: rank-1 → [1, k], batched → [rows, k] (zero-copy views, §5.1);
• KernelDispatch selects a registered kernel or the decoding ReferenceMatmulKernel.

So a packed weight is decoded, never read as a raw byte, whatever the activation's rank or TensorData subtype — #993 (rank-1 decode step) and #991 (unexpected activation subtype) stop being crash classes and become ordinary dispatch. The output shape is restored from the normalisation ([k] × [k, n] → [n], batched dims preserved), so callers see no difference.

DispatchMode (backend-api, expect/actual over the platforms): -Dskainet.dispatch.registry=false forces the legacy per-element fallback, and overrideEnabled lets a test pin either path. The legacy code stays until the migration is complete (#1029 does the JVM packs), then it goes.

Evidence — RegistryMatmulDispatchTest (4/4):

• the Quantized matmul dispatch skips rank-1 (single-token decode) activations, falls through to broken matmulGeneric #993 repro — rank-1 decode-step activation × Q8_0 packed weight — produces finite output matching a manual dot product;
• registry and legacy agree elementwise on identical inputs (the same test pins each path via DispatchMode);
• batched [2, 3, 32] activations flatten and reshape to [2, 3, n];
• a Q4_K weight decodes correctly through the registry.

Plus the golden parity tests pass unchanged — the guard that matters for a behaviour-moving slice — along with the rest of the gate.

Test plan

Full local gate (scripts/pr-gate.sh, JDK 25) — all legs passed, including the packed-encoding golden parity tests; results in the first comment.

Closes #1028

🤖 Generated with Claude Code

[michalharakal]

Local gate scripts/pr-gate.sh (JDK 25) on c570a34: all legs passed — jvmTest (incl. the packed-encoding golden parity tests) · apiCheck · JS/Wasm · linuxX64Test · assemble · Java consumer API tests.

Targeted: RegistryMatmulDispatchTest 4/4. A JMH check of the untouched fast paths follows in a comment.

[michalharakal]

Fast paths unchanged — targeted JMH on this branch (c570a34) vs docs/design/memory/baseline-2026-08-22.md (same machine, idle):

Benchmark	Params	Mode	Pre-M0	Post-M0	Δ	Units
add_1M_fp32 ElementwiseAdd1MBench	vectorEnabled=false	thrpt	1.217 ± 0.011	1.235 ± 0.031	-1.5%	ops/ms
add_1M_fp32 ElementwiseAdd1MBench	vectorEnabled=true	thrpt	1.705 ± 0.030	1.716 ± 0.024	-0.6%	ops/ms
matmul_q4k_panama QuantizedMatmulBench	shape=1024-1024	avgt	0.112 ± 0.017	0.111 ± 0.018	-0.9%	ms/op
matmul_q4k_panama QuantizedMatmulBench	shape=4096-1024	avgt	0.336 ± 0.003	0.334 ± 0.001	-0.6%	ms/op
matmul_q4k_panama QuantizedMatmulBench	shape=4096-4096	avgt	1.223 ± 0.017	1.226 ± 0.017	+0.2%	ms/op

worst slowdown: +0.2% (positive = slower after M0)

Worst movement +0.2 %, everything inside the error bars — as expected: the packed-quant kernels and the FP32 2D×2D path are untouched by this slice, only the generic fallback was rerouted.