docs: pre-implementation brief for latent_proj_gemm (#386)

[haoruilee]

Research-only brief for RL-Align/RL-Kernel#386 (latent_proj_gemm, claimed by @haoruilee). No kernels.

Context was synced from upstream/main @ ccb70e3 (this fork is 596 commits behind). Implementers should branch from upstream, not from this fork tip.

1. Closest ops / layout to copy

• Kernel family: det_gemm (PR [WS1][kernels] Batch-invariant deterministic GEMM (fwd + bwd) RL-Align/RL-Kernel#180) — mid-split K-tree, no Split-K, CUDA+Triton+gtest+bench+docs.
• Do not wrap det_gemm as-is: BF16-only check_in, BF16 internal tree adds, unbound det_gemm_fwd_fp32.
• Python API: lm_head — HF [out,in], optional bias, forward / forward_fp32.
• PR ceremony: [WS1][kernels] Batch-invariant logprob (CUDA) RL-Align/RL-Kernel#204 — python, triton, cuda, binding, registry, fallback, tests, benchmark, validation-env table.

2. API contract

One registry op, two pinned directions, FP32 throughout:

direction	x	weight (HF)	bias
img_in	[..., 64]	[3072, 64]	[3072] (checkpoint has it)
proj_out	[..., 3072]	[64, 3072]	[64]

Y = X @ W.T + B, mid-split K-tree leaf 32, FP32 leaves and FP32 combines, no BF16 store. CUDA is bit-reference; Triton must match byte-for-byte; no silent fallback; WS2 = no.

Official Diffusers + Qwen/Qwen-Image checkpoint both ship img_in.bias / proj_out.bias even though the issue table omits bias.

3. Files to add/change

New: ops/{pytorch,triton,cuda}/linear/latent_proj_gemm.py, csrc/cuda/gemm/latent_proj_gemm_kernel.cu, tests/test_latent_proj_gemm.py, benchmarks/benchmark_latent_proj_gemm.py, docs/operators/latent-proj-gemm.md.

Edit: csrc/ops.cpp, setup.py (always-on cuda_sources, not SM90-gated), _C.pyi, registry.py, gtest/operator_{specs,inputs}.py, nav/README, __init__.py exports.

4. Test shapes / harness

Packed token counts after VAE /8 + 2×2 pack:

image	M
1024²	4096
1328²	6889
1664×928	6032

Plus M ∈ {1,7,31,64,128,256}. Gold = same mid-split FP32 tree (not torch.matmul). check_operator.py --op latent_proj_gemm --dtype fp32 after OP_SPECS lands.

5. Open questions for RL-Align#386

1. FP32 tensors vs generic “final BF16 cast” rule — recommend stay FP32.
2. Bias — recommend yes (checkpoint).
3. One op vs two names — recommend one.
4. Naive CUDA v1 vs Hopper TMA first — recommend naive.
5. CPU gold = same tree (so bitwise is possible).

Full writeup: docs/design/qwen-image-ws1-latent-proj-gemm-brief.md.