h3-blackwell-runtime/research/vortex_exact_attention/README.md

# Vortex Exact Attention

Vortex Exact Attention is a clean-sheet attention research project for MiniMax
H3 on NVIDIA GB10 (`sm_121a`). Its claim target is the fastest reference-exact
MiniMax H3 attention backend for long-context Blackwell inference. This is a
research target, not an achieved performance claim.

## Scope

`vortex_exact` must preserve the observable behavior of SageAttention 2.2.0 at
commit `d1a57a546c3d395b1ffcbeecc66d81db76f3b4b5`. It may change scheduling,
ownership, staging, and physical data movement, but not quantization, rounding,
reduction, traversal, accumulation, or output-conversion semantics.

Excluded from this backend:

- sparsity;
- cache reuse;
- timestep or block skipping;
- changed Q/K/V formats or scaling;
- reordered reductions or approximate quality gates.

Such work belongs in a future `vortex_fast` backend with a separate contract.

## Status

- Phase 0: imported and verified retained Sage2 exactness specification.
- Phase 1: design decision complete; VEA-B is the recommended prototype.
- Phase 2A: capability probes pass with CUDA block-scope mbarriers; one isolated
  aligned-shape prototype is authorized.
- Attention kernel implementation: not started; capability kernels only.
- Production dispatch: unchanged; no `vortex_exact` route exists.

## Authoritative Baseline

| Item | Value |
| --- | ---: |
| Device | NVIDIA GB10, SM121 |
| Workload | 1344x768, 124 frames, 37,810 tokens, 56 heads, D=128 |
| Resident sampling median | `255.447 s` |
| Sage2 share | `62.36%`, approximately `159.3 s` |
| Uninstrumented mainloop | `237.089 ms` |
| NCU grid / block | `(296,56,1)` / `(32,4,1)` |
| KV traversal | 591 increasing 64-row tiles, two explicit stages |
| Registers / dynamic shared memory | 255/thread / 32 KiB |
| Achieved occupancy | `16.65-16.83%` |
| No-eligible scheduler cycles | `63.53%` |
| L2 hit / memory throughput | `98.85%` / approximately `31.74%` |

The target is dependency latency and live-state ownership. Launch overhead,
off-chip bandwidth, ragged tails, and ordinary shared-memory padding are closed
as primary explanations.

## Gates

The first implementation may begin only after the Phase 1 design commit. No
candidate can advance unless its model plausibly reduces simultaneous live
state, avoids material score/probability tensors and catastrophic spilling,
preserves the exact reduction sequence, and has a credible path below `220 ms`.
A model below `190 ms` is preferred.

Executable advancement later requires byte-exact short shapes, canonical
attention, blocks 0/24/49, two-step latents, and 12-step latents, plus sanitizer,
p95, block-level, and resident-service gates.

## Layout

- `NUMERICAL_CONTRACT.md`: imported exact Sage2 semantics and proof limits.
- `DESIGN.md`: state-ownership architectures and selected prototype.
- `PHASE2A_CAPABILITY_REPORT.md`: measured resource, handoff, overlap, sanitizer,
  NCU, and fixture decision.
- `PERFORMANCE_MODEL.md`: resource and latency model.
- `HARDWARE_CAPABILITIES.md`: target-specific hardware facts and unknowns.
- `EXPERIMENT_LOG.md`: append-only research decisions.
- `benchmarks/`: machine-readable models and fixture manifests.
- `kernels/`: isolated capability probes; no attention kernel.
- `tests/`: future parity and sanitizer harnesses.
- `tools/`: project-local verification/modeling utilities.

Phase 1 selects a Q128, ten-warp paired-owner pipeline in which four QK/softmax
warps own `RS/RS_f8/m/d`, four distinct PV warps own `RO`, and two producer
warps own K/V staging. This differs structurally from P3 because complete state
is transferred or partitioned rather than retained in every compute warp. Its
`180-207 ms` mainloop range is a heuristic screening model, not a measured
result. Phase 2A measures 96 registers/thread for the selected mbarrier handoff,
139 for the synthetic combined-ownership probe, zero spills, one ten-warp CTA/SM,
`0.076800 ms` barrier-only p50, and positive INT8/FP8 clock overlap in 48/48
blocks. These measurements advance VEA-B to an isolated prototype, not to a
performance or production claim.

## Provenance

The reference is the public SageAttention repository at the pinned commit above.
No upstream source is copied into this project. Before implementation, every
borrowed algorithmic or source component must record its origin and license.
P1/P2 local code may be reused only as provenance-preserving components inside
an owned pipeline. See `NUMERICAL_CONTRACT.md` and `EXPERIMENT_LOG.md`.