# The exl3 kernel-shape FAMILY pin, re-measured per bit width.
#   tools/exl3_pin_record.py, RTX 4090 (128 SMs, sm_89), box 100, sole tenant
#   verified at both ends, clocks idling at 210-285 MHz against 3105 MHz max,
#   12 whole races per geometry, unanimity AND a bootstrap interval on the
#   paired margin, target 0.5%.
#
# WHY. #1904 established on the INT8 kernel that a ladder chosen at K=4 does
# not transfer: shape 30 gets 3 blocks/SM at K=4 and 2 at every other width,
# a pure register effect (168 regs at K=4, 200-217 elsewhere) that a
# SMEM-only calculation cannot see. The shipped exl3 pin table had entries
# for K=4 only -- and the pin space is already partitioned by K
# (custom_op: key = (*_inner_kernel_dims(inner), int(inner.K))) -- so the
# question "does the pin transfer across K" had a mechanism, a machinery and
# no entries.
#
# THE ANSWER IS NO FOR THE INT8 KERNEL AND, ON THIS CARD, YES FOR EXL3'S.
# Every geometry that exists at two widths draws the SAME family at both:
#
#   Step-Audio-2-mini-exl3-4.15bpw -- one checkpoint, three widths
#     3584x3584   K5 -> K32N128     K6 -> K32N128
#     3584x512    K5 -> K16N128     K6 -> K16N128
#     3584x18944  K4 -> K16N512     K5 -> K16N512
#   across checkpoints, same geometry, different width
#     17408x5120  K4 -> K32N128     K6 -> K32N128
#     5120x17408  K4 -> K16N512     K6 -> K16N512
#
# That is a NEGATIVE for the transfer hypothesis as applied to exl3's family
# ladder, and it is worth stating plainly rather than filing as "no change":
# the #1904 effect is a property of the int8 kernel's own instantiation set --
# one templated mainloop whose register allocation moves with the unpack
# width -- and exl3's families are separate compiled kernels selected by tile
# geometry, where K changes the trellis stride and not the register budget.
#
# WHAT DID CHANGE IS THAT THE ENTRIES NOW EXIST. Before this, a K=6 drafter or
# a 4.15bpw checkpoint raced every one of its families live at boot and kept
# whatever the first draw gave it (#1879: the race is a deterministic function
# of LOAD, and the pin cache makes the first draw permanent). The margins are
# not small -- these are the geometries where getting it wrong costs most:
#
#   Qwen3.8-27B-DFlash2-exl3-6.0bpw   (all K=6, 47 linears, 8 geometries)
#     5120x4096xK6    K32N128  12/12  20.567% [20.141, 20.997]  RECORDED
#     4096x5120xK6    K32N128  12/12  19.684% [19.350, 20.011]  RECORDED
#     17408x5120xK6   K32N128  12/12  10.989% [10.615, 11.335]  RECORDED
#     25600x5120xK6   K32N128  12/12   9.705% [ 9.479,  9.921]  RECORDED
#     5120x17408xK6   K16N512  12/12   9.081% [ 8.600,  9.432]  RECORDED
#     5120x1280xK6    K32N128  12/12   5.669% [ 4.887,  6.685]  RECORDED
#     5120x1024xK6    K32N128  12/12   4.962% [ 4.539,  5.496]  RECORDED
#     5120x256xK6     K16N128  11/12   0.800% [ 0.355,  1.253]  REFUSED
#
#   Step-Audio-2-mini-exl3-4.15bpw    (K=4/5/6 mix, 197 linears, 8 geometries)
#     3584x3584xK6    K32N128  12/12  13.336% [12.750, 13.941]  RECORDED
#     3584x3584xK5    K32N128  12/12  13.296% [12.730, 13.843]  RECORDED
#     3584x18944xK5   K16N512  12/12  10.696% [10.594, 10.812]  RECORDED
#     18944x3584xK4   K32N128  12/12   9.858% [ 8.504, 10.701]  RECORDED
#     3584x512xK5     K16N128  12/12   2.771% [ 2.401,  3.197]  RECORDED
#     3584x512xK6     K16N128  12/12   2.650% [ 2.028,  3.230]  RECORDED
#     3584x18944xK4   K16N512  12/12   2.342% [ 2.157,  2.520]  RECORDED
#     3584x158720xK6  K16N512  12/12   1.372% [ 1.202,  1.546]  RECORDED
#
#   THE PAIRED CELLS ARE THE READING. 3584x3584 at K=5 and K=6 is one
#   geometry at two widths on one checkpoint: same family, and margins that
#   agree to 0.04pp (13.296% vs 13.336%) with overlapping intervals. Same for
#   3584x512 (2.771 vs 2.650). 3584x18944 at K=4 vs K=5 keeps the family and
#   the margin moves 2.34% -> 10.70%, so the SIZE of the win does track the
#   width even where the WINNER does not -- which is the honest shape of the
#   negative: K moves how much the choice is worth, not what it is.
#
# A K=4 GEOMETRY THE SHIPPED TABLE CLAIMS AND THIS RUN CANNOT: 5120x1024xK4,
# the k_proj/v_proj pair, came back 8/12 with a margin of 0.252%
# [-1.019, +1.261] -- an interval that straddles zero. The shipped entry
# records K32N128 on #1879's 12/12, and it is LEFT ALONE: an unresolvable
# re-reading is not evidence for the other family, and churning a recorded
# decision that deployments already serve would be the flip this table exists
# to stop. It is named here because the grid width recorded beside it was
# raced under K32N128, and if a later re-record ever moves that family the
# width must move with it -- which the loader enforces (the width is gated on
# the same family check) and tools/exl3_pin_force.py honours (it drops the
# width when it forces a family).
#
# 5120x12288xK4 is the other refusal: 10/12, 1.160% [0.653, 1.566].

# ===================================================================
# 2026-09-02, #1861: THE NEMOTRONH LIGHTNING-30B-A3B MoE CHECKPOINT.
#   /mnt/k8scache/models/NVIDIA-Nemotron-3.5-Lightning-30B-A3B-exl3-4bpw
#   tools/exl3_pin_record.py, RTX 4090 (sm_89) on 206 gpu0, sole tenant
#   verified at both ends, clocks idling at 210 MHz against 3165 max,
#   12 whole races per geometry, unanimity AND a bootstrap interval on
#   the paired margin, target 0.5%.
#
# WHY THIS CHECKPOINT. It is the first one here whose DENSE linears the
# int8 prefill leg can serve and whose widths are not K=4. Its 4.09 bpw
# is an AVERAGE: the allocator spent 4 bits on the routed experts, which
# are 5888 of its 6005 linears, and 6 bits on every dense linear --
# mamba in/out, the shared expert's up/down, attention q/k/v/o and the
# head. So no geometry here can borrow a K=4 entry, and before this the
# whole dense side raced live at every boot.
#
#   2688x10368xK6   K32N128  12/12  31.284% [30.498, 32.121]  RECORDED
#   2688x4096xK6    K32N128  12/12  17.265% [16.105, 18.625]  RECORDED
#   4096x2688xK6    K32N128  12/12  15.113% [14.816, 15.358]  RECORDED
#   3712x2688xK6    K32N128  12/12  14.921% [14.065, 15.813]  RECORDED
#   2688x3712xK6    K32N128  12/12  14.632% [14.061, 15.135]  RECORDED
#   2688x256xK6     K16N128  12/12   1.266% [ 0.949,  1.599]  RECORDED
#   2688x131072xK6  K16N512  10/12   0.439% [ 0.205,  0.703]  REFUSED
#
# THE MARGINS ARE THE READING. 14.6-31.3% on the five load-bearing
# geometries, against 4.9-20.6% across the 27B's eight. The table stops
# being "removes a boot-to-boot variable" here and becomes "removes a
# boot-to-boot variable worth up to 31%". 2688x10368 is the mamba
# in_proj, 23 of them and 22.0% of prefill FLOPs per token; getting its
# family from a live race was the single largest unpinned decision in
# this deployment.
#
# THE REFUSAL IS THE HEAD, and it refuses for the reason the standard
# exists: 10/12 is not unanimous, so the ordering is unresolved even
# though the interval clears zero. It races live and that is correct.
#
# A GEOMETRY THAT NEEDED THE PER-FAMILY WIDTH, AND GOT IT. 2688x256xK6
# is the k_proj/v_proj pair and it is the 5120x1024 hazard again: a grid
# width worth 1.75x, gated on a family whose race margin is 1.266%.
# Issue comment 5510306250 asks for a width recorded for EVERY family
# such a geometry can draw. All three of its legal families were raced:
#
#   K16N128  num_sms 16  12/12  74.56% [73.83, 75.23]  decode -67.06%
#   K32N128  num_sms 16  12/12  75.83% [75.76, 75.89]  decode -70.04%
#   K32N256  num_sms 16  12/12  74.39% [74.34, 74.44]  decode -69.78%
#
# They all want the SAME width, so the answer is stronger than the ask:
# the width does not depend on the family here, and no draw forfeits it.
# The decode column is negative -- this width makes decode cheaper too,
# so there is no band to guard. Per-width timings (K32N128, ms) say why:
# default 0.2733 against 16 -> 0.0661, 32 -> 0.0858, 64 -> 0.1413,
# 112 -> 0.2308, monotone in the grid width. At N=256 there is not
# enough work to fill a wide grid and every extra block is launch and
# reduction cost.
#
# THE OTHER FIVE KEEP THE DEFAULT GRID, measured not assumed: the
# default won 12/12, 12/12, 12/12, 10/12 and 12/12 of its races at
# margins of -0.76% to -6.50%, and 2688x10368's best candidate taxed
# decode +1.44% besides.
