feat(backend-api): KernelKey dispatch — declared formats/layouts, rank normalised once, visible adapters, reference matmul (SKEEP-003 P3, S1.7a)

[michalharakal]

Summary

SKEEP-003 slice S1.7a (milestone M1 #1002, PRD M1-F5 / M1-A4): kernel selection on declared descriptors instead of an is-ladder over TensorData subclasses — the reason every quantisation bug was a dispatch bug (#993, #991).

• KernelKey(op, operands, placement) with OperandKey(format, layoutClass) and LayoutClass { CONTIGUOUS, STRIDED, BLOCKED }. Keys are values and print as matmul(Float32/Dense(4B) contiguous × Float32/Q8_0 blocked) @host; UnsupportedKernelException lists what is registered.
• ViewKernel — a kernel declares its key and takes TensorViews; a custom kernel author never sees a TensorData subclass (§5.2).
• ReferenceMatmulKernel — correct for any pair of formats, because it reads through TensorView.get(), which decodes (rule 4). Slow by design: the fallback that turns an unsupported combination into right numbers with a trace event instead of a ClassCastException in layer 17.
• KernelDispatch — normalizeActivation() promotes rank-1 to [1, k] and flattens leading dims as zero-copy views, once, before lookup (Quantized matmul dispatch skips rank-1 (single-token decode) activations, falls through to broken matmulGeneric #993's root cause removed by construction); register/find keep the kernel table; matmul() selects, inserts a gather adapter for a strided operand into the caller's Scope and emits TraceEvent.AdapterInserted (the hidden 12 GB of GGUF DEQUANTIZE_TO_FP32 over-allocates: 1.1B Q4_K_M needs >12 GB heap transiently (~4.4 GB legit) #782 becomes a visible event), then runs the kernel inside a TraceEvent.KernelRun span. TensorView.reshapeContiguous is a view.
• backend-api now wires kotlin-test into commonTest (the module declares its targets by hand, without the sk.ainet.multiplatform convention plugin).

Evidence (KernelKeyDispatchTest, 6/6 on JVM and linuxX64):

• 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 — runs through the registry with no special-casing and produces finite output matching a manual dot product;
• a Q4_K weight (the Quantized matmul dispatch silently falls back to a broken generic kernel for rank>2 attention projections (ClassCastException: Byte cannot be cast to Float) #991 shape: the activation is not the subtype a fast path wanted) decodes correctly through the reference path;
• a registered kernel wins over the reference for the same key;
• a genuinely strided activation gets a visible gather adapter whose byte count and numbers are asserted.

Nothing routes DefaultCpuOps through this yet — that is #1028 (commonMain) and #1029 (JVM packs), where the ladders come out under the golden parity gate.

Test plan

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

Closes #1027

🤖 Generated with Claude Code

[michalharakal]

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

Targeted: KernelKeyDispatchTest 6/6 on JVM and 6/6 on linuxX64.