feat(ops)!: matmulWeightTransposed as the primitive; transpose refuses a packed weight (#973.3) - #1105

Closes #1096 — the last slice of #973

⚠️ Breaking. ops.transpose now throws for a heap block-quantized weight. Confirmed acceptable: downstream is pinned and will be updated.

The operation that never existed

ops.transpose on block-quantized data was never a transpose. Blocks quantize runs along the input dimension, so a real transpose needs requantization. What happened instead was a layout conversion wearing transpose's name, with a shape label that lied about the bytes — and:

• it was not an involution: transpose(transpose(W)) is a different matrix for a non-square block grid, and nothing detected it;
• since fix: physically reorder packed-quant blocks in ops.transpose (all-zero matmul, not just Q5_0/Q5_1) #969 it was an O(bytes) copy on every call, which for Linear.onForward meant every forward pass;
• its result's [in, out] shape had no self-consistent packed interpretation, so toFloatArray() on it was garbage.

What replaces it

• TensorOps.matmulWeightTransposed(x, weight) — x · Wᵀ with the weight as [out, in]: the primitive ggml (mul_mat) and BLAS (op(B)) actually have. Defaulted to matmul(x, transpose(w)), so no implementation has to change; DefaultCpuOps overrides it to relayout a packed weight once per weight and reuse it.
• TensorOps.relayoutPackedWeightForKernels(weight) — the conversion under its own name, for callers who want permuted bytes rather than a product. Defaults to refusing.
• DefaultCpuOps.transpose throws for a heap packed weight, naming the primitive, the explicit relayout, and why the operation is not definable.
• Linear.onForward asks for the product instead of transposing.

A distinction this made explicit

The refusal is scoped to the heap tier. The MemorySegment kernels read canonical bytes, so for those a shape swap is genuinely correct — that is census contradiction #3, and it is now stated in code instead of being implied by which marker interface a class happens to have. Narrow floats keep their view rewrap (#888). Both of those came out of test failures while doing this, not from reading.

The cache, and its bound

The relayout is memoized per weight, keyed by the identity of the packed bytes, bounded at 64. A model's weights are stable, so the first forward converts and every later one reuses. Past the bound the oldest is dropped and reconverted — which is exactly the old per-call behaviour, so the failure mode of the cache is "as slow as before", never "wrong".

Migration

27 in-repo call sites moved to one of the two entry points, and the choice per site was not mechanical: a test asserting "transpose keeps packed bytes and swaps the shape" wants relayoutPackedWeightForKernels; one computing a product wants matmulWeightTransposed; a MemSeg or narrow-float site wants plain transpose and was reverted after I over-migrated it.

Acceptance

MatmulWeightTransposedTest: the primitive computes exactly what relayout-then-matmul did; repeated calls keep agreeing with the explicit relayout (the cache is not stale); transpose refuses with a message naming the primitive, the relayout and the reason; a dense weight transposes as it always did.

Gate

scripts/pr-gate.sh — all legs passed. --golden — passed: no packed byte layout moved.

#973 is now complete

🤖 Generated with Claude Code