README: ring3 per-layer-type SDPA bundles

README.md

@@ -404,3 +404,47 @@ dimension appears in either entrypoint of either bundle.
 > host-side work can be developed against the contract over a smaller download. It carries
 > real weights for the layers it keeps and produces low-quality text; do not evaluate
 > quality from it.
+
+
+## `ring3/` — per-layer-type SDPA form
+
+> **EXPERIMENTAL — gated in torch, no on-device numbers yet.** Same weights, same
+> quantization, same host contract as `ring/`. One thing changes inside the graph: the
+> grouped-query expansion is folded into the query **only in the full-attention layers**,
+> and the sliding layers keep the stock gathered form.
+
+**Why the split.** Folding the GQA expansion into the query removes the gathered copies and
+the broadcast index tensor, but it also turns G independent per-head matmuls into a single
+batch-1 matmul with G times the rows. That trade is worth taking when the key length is long
+(the full-attention layers read the whole capacity) and not worth taking when it is short
+(the sliding layers read a fixed 576-slot ring, where the operation is short enough that
+losing the per-head parallelism costs more than the bytes it saves). `ring/` applied the fold
+everywhere; `ring3/` applies it only where the key length is long.
+
+Both forms compute the same dot products in the same order. The equality gate below is run
+against the shipped graph, not against `ring/`.
+
+**Contract: unchanged.** Same four inputs in the same order, same two KV states in the same
+positional order, `position_ids` carrying the absolute position of each of the S tokens in
+the call, the mask derived inside the graph, the same requirement that a `prefill` call start
+at a multiple of 64. A host driving `ring/` drives these with no change.
+
+**Equality.** Gated in eager torch against the shipped graph before conversion: 1,600 prompt
+tokens as 25 chunks of 64 then 32 greedy decode steps, final position 1,631, so the sliding
+ring wraps about three times. fp32, 57 comparisons per run, **0 argmax mismatches** on every
+bundle below. No dynamic dimension appears in either entrypoint of any of them.
+
+| Bundle | Context | KV state shape | KV bytes, both states | Sliding / full slots |
+|---|---:|---|---:|---|
+| `ring3/gpu-pipelined/gemma4_e2b_qat_decode_int4lin_tbl_pf64_ring_c4096_gqafull` | 4,096 | `[1, 1, 1, 19200, 512]` x2 | 39.3 MB | 12 x 576 + 3 x 4,096 |
+| `ring3/gpu-pipelined/gemma4_e2b_qat_decode_int4lin_tbl_pf64_ring_c2048_gqafull` | 2,048 | `[1, 1, 1, 13056, 512]` x2 | 26.7 MB | 12 x 576 + 3 x 2,048 |
+
+E2B runs 28 sliding and 7 full attention layers; in these bundles the 28 keep the gathered
+form and the 7 use the folded one.
+
+## `ring3-smoke/` — truncated proving asset
+
+> **EXPERIMENTAL — not a usable model.** A 5-layer truncation of the E2B decoder at the 4,096
+> capacity (`[1, 1, 1, 6400, 512]` states, 4 x 576 + 1 x 4,096), published only so host-side
+> work can be developed against the contract over a smaller download. It carries real weights
+> for the layers it keeps and produces low-quality text; do not evaluate quality from it.