packages/sparse-attention-kit/README.md

@szl-holdings/sparse-attention-kit

Typed sparse-attention envelope + receipt layer. No CUDA kernel ships here.

Re-expressed from the 2025 sparse-attention wave (MiniMax M1/M2, DeepSeek NSA, Moonshot MoBA, Tri Dao FlashAttention, Songlin Yang FLA) against Doctrine V6. The non-negotiable design decision is documented in docs/research/sparse-attention-synthesis-2026.md:

MiniMax M2 reverted to full attention after hybrid-sparse matched full attention on small benchmarks but degraded measurably on multi-hop reasoning at scale. The lesson is not "sparse is the answer" — it is "sparse without a contradiction detector and an escalation path is a benchmark trick that fails industrial validation."

So this kit ships five primitives and twelve sparse.*.v1 receipt classes that make that lesson structural rather than folk:

Primitive	Source	Doctrine V6 receipts
envelope	MiniMax M2 "no-free-lunch"	sparse.regime.admitted.v1, sparse.regime.rejected.v1, sparse.regime.demoted.v1
contradiction-probe	MiniMax M2 + ROSIE	sparse.contradiction.v1, sparse.escalated.v1
two-level-commit	DeepSeek NSA	sparse.index.score.v1, sparse.topk.commit.v1, sparse.execute.v1, sparse.budget.exhausted.v1
recorded-router	Moonshot MoBA	sparse.router.trace.v1
io-budget	FlashAttention (Tri Dao)	sparse.io.budget.v1, sparse.io.overrun.v1

Usage

import {
  admit, probe, scoreIndex, topKCommit, executeSparse,
  recordedRouter, recordIo,
} from "@szl-holdings/sparse-attention-kit";

Every function is pure — no transport, no logger, no side effect. The caller writes the returned receipt to the ledger; the api-server owns the persist/emit transport.

Doctrine contract

• A sparse plan that lacks sparse.regime.admitted.v1 MUST NOT execute.
• A sparse step that lacks a fresh sparse.topk.commit.v1 parent MUST NOT execute (sparse.execute.v1 is rejected at receipt-write).
• A sparse.contradiction.v1 without a paired sparse.escalated.v1 is a doctrine violation.
• A sparse.router.trace.v1 whose blocksSelected.length > envelope.maxBlocks MUST trigger router demotion (NOT silent truncation).
• A sparse.io.overrun.v1 with overrunRatio > 1 is a Sentra fail-closed event for the next admission attempt from that tenant.