Product ladder

This file is the SOURCE OF TRUTH for what a hipfire quant product name promises. It is the product-facing sibling of qt-register.txt, which owns wire-format numbers.

Three namespaces, deliberately separate. Conflating them is what produced the current zoo (mq4, mq4r, mq4p, mq2lloyd, mq4v2, mq4c, …), where a codec generation, a calibration recipe, and a layer ladder all competed for the same token.

MQ (Magnum, i.e. FWHT-rotated — see ../../PRIOR-ART.md) stays the family name in both the product and format columns. What leaves the product name is everything that is not a tier: codec generations (v2, C, planar, pad) and calibration recipes (Lloyd, GL, sel, AWQ alpha) are how you buy a rung more cheaply, not which rung it is.

The product number is a bpw class, not a codec. mq5 means “measured 5.x bpw,” whichever codec produced it. MQ5G256 (qt=31) is a format that may or may not be used to build an mq5-class product. Today the measured mq5 cells use MQ5G256V2 (qt=48).

1 · The honesty invariant

mq<N> means measured model bpw ∈ [N, N+1). No exceptions.

Model bpw, not codec bpw. These differ and only one of them is the product’s promise:

• Codec bpw — what the encoding costs per weight it covers. MQ4G256V2 is 136 B per 256 weights = 4.25 bpw.
• Model bpw — total artifact bytes × 8 ÷ parameter count. Lands at 4.46–4.90 for the same codec under the three rungs below, because embeddings, lm_head, and (on pro) recurrent/SSM lifts sit above base width and the structural F16 tensors add a sliver.

The product quotes model bpw, because that is what the user downloads and holds in VRAM. Codec bpw is what you would get if every weight used the base format with no role lifts.

This is the one rule that must be machine-checked rather than promised, because it is the rule the rest of the industry breaks. Enforcement is the same both-directions shape scripts/check-quant-registry.py already applies to the qt register: reject a publish whose product name’s leading digit disagrees with the artifact’s measured model bpw.

Measured 2026-08-20 on Qwen3.8-27B (26,895,998,464 parameters), showing the failure mode this rule exists to prevent — all three are named .mq4:

Legitimate internal experiments. None may ship under a 4-bit name.

2 · Rungs

A rung names which tensor roles are held above the base width. Roles are architecture-neutral; each arch maps its own tensors into them. This is what makes a label portable — today mq2r on DeepSeek-V4 means lm_head at Q8 while historical mq4r on Qwen3.8 meant lm_head not at Q8, because the suffix fused a Redline route claim with a role ladder. The product ladder below separates those concerns: three rungs, role lifts only.

Three rungs per bit width. No more, no fourth. Every rung carries a claim, which is why there is no “truly uniform, no guarantee” tier — a rung that promises nothing is not a product, and the base-width-everywhere point is what the codec bpw already describes. There is no xtx (or any other fourth speed suffix): speed claims live in measured AR/DFlash columns, not in the product name.

xt denotes the faster variant, matching its GPU meaning: it drops the lm_head to base width. Historical .mq4r paired that recipe with a retained- Redline admission, which is what r denoted. The new V2 XT cells are not automatically Redline-admitted; transport eligibility remains a separate, fixture-bound certification decision. pro takes the precision direction.

The structural F16 tensors — norms, A_log, dt_bias, AWQ scale vectors — are never quantized at any rung. On Qwen3.8-27B they total 679,424 elements, about 0.0025% of parameters, and are not a ladder axis. On Qwen3.8, linear-attn conv1d is held at Q8F16 on every rung (not a ladder axis); it is listed in the role recipes so the census is exact.

Qwen3.8-27B role recipes (this campaign)

Architecture-neutral product tiers map to these encoder lifts on Qwen3.8-27B (quantize log product tier: lines; recipe census is deterministic):

Fixed-tier overrides used on the measured ladder (manifest fixed_tier; keeps the product inside its bpw class when a full Q8 lift would overshoot or when low-bit heads need a mid ladder step):

Roles are per-architecture categories

A dense model’s roles are embeddings, lm_head, and recurrent/SSM state. A MoE’s ladder is dominated by an expert role the dense model does not have — on Qwen3.6-35B-A3B the experts are 93% of parameters — so its three rungs order experts before embeddings. The rung names stay portable because they name a position on the ladder, not a tensor list.

The product grid

Fifteen products plus the ceiling, and every cell has a defined meaning for any architecture. q8 carries no rungs: lifting above Q8 means F16, which is a different product, and uniform Q8 already is q8.

Rungs lift into each other. What a rung lifts to is drawn from the same published set, one or two classes up: mq2 pro lifts head/ssm_out to MQ6, mq3 pro lifts ssm_out to MQ6, mq4/mq5/mq6 pro lift ssm_out to Q8. The ladder terminates at Q8 rather than at an unrelated format, so no codec sits outside the ladder and the § 1 budget governs each step.

Why there is no rung above pro

A product that lifts attention costs 5.162 bpw on the dense 27B, so it is an mq5-class product. There is no XL/XXL.

The counter-argument is real and worth recording: an explicit oversize suffix would make lineage visible — a 3-bit base grown fat is not the same animal as a native 4-bit quant, even at equal bytes — and reclassifying it hides that.

It loses anyway, on two grounds:

1. An oversize suffix breaks the only checkable promise. mq4 pro xl at 5.16 bpw means the leading digit no longer predicts size. That is precisely the llama.cpp failure mode, with a warning label attached — and the people most harmed by the zoo are the ones who do not decode suffixes. A class defined by measured bpw cannot drift: growth reclassifies.
2. Lineage does not need to live in the name. At equal class the KLD column picks the winner, and a lifted-3-bit only ships at all if it beats a native 4-bit at equal bytes — otherwise you would ship the native one. § 3 makes base codec a required column so the two animals stay distinguishable.

3 · Required columns

Every published product row carries, per model:

Rows are filled from the routes in ../VALIDATION.md. A rung without a measured KLD on a given model is not publishable for that model. Do not infer a KLD from a sibling model or a sibling codec.

Measured grid — Qwen3.8-27B MQ V2 family (2026-08-20)

Authoritative evidence: hiptrx ssh://hiptrx/home/kaden/qcal/ladder-v2/ (summary.md / summary.json / summary.csv), generated 2026-08-20T14:13:16Z, commit bfe3cfead5856c5ee85e972b609712b0badbd1b1, params 26,895,998,464. Host: 4×gfx1201, ROCm/HIP 7.14. KLD protocol: WT2 + v6sel, 24 chunks, prefill scoring, kv-mode q8. Prompt fixture benchmarks/prompts/merge_sort_thinking_off.txt md5 253c7ac50857fe6d0e10fb0d2c5e35c0 (sha256 d671894964cb957643fcb961151f3d1b407cb5c206766eaed60e9c593e6ed9d0). Binaries (sha256): hipfire-quantize 8e123d06d481d91c43e0a70ba383d0ee6e37b1be0bf3390ef1b4a95707d59661, hipfire c005c4dd7fba4794fb107348f1d1a12d6a05d7e8e89a11e6dd41135adf275fdd, eval_hipfire 53f9b948355756a1f6ed7e27d84d485fb6f4815d7e9643e660be7678d06e7de2, dflash_convert ebbe90cfcdd28365e507d751fa45477c918317b5af0b88a40a97b01ae7f2bc31.

Status is evidence status, not registry publication. No cell below is declared shipping or registry-published from this table alone. AR acceptance is null (unavailable_in_native_generate_v1) for every cell — never derived. DFlash τ is recorded in the remote summary; acceptance remains unavailable.

Every row satisfies § 1: measured bpw ∈ [N, N+1) for product mqN.

mq2 rejection (product admission, not measurement failure). All three mq2 cells were built, KLD-scored, AR-benched, and serve-probed. WT2/v6sel KLD is catastrophic (~12–14 nats). Decoded serve text is coherent enough to read but degraded/repetitive (serve-mq2.json: no attractor/empty flags; content quality is not shipping-grade). Do not call MQ2V2 a shipping product. The rows stay on the grid so the class is defined and the failure is dated.

mq3–mq6 candidates. Serve batteries on the base artifact of each class (serve-mq{3,4,5,6}.json): coherent completions, no attractor/empty. KLD is in a usable range and improves monotonically with class. Still candidates, not registry cards — publication requires the separate registry/validation path.

Artifact digests (sha256 of each cell’s .hfq; full rows also carry md5/bytes in summary.json):

Paths are under /home/kaden/qcal/ladder-v2/artifacts/ on hiptrx.

DFlash same-bit vs mq4 control (decode tok/s median)

Lifecycle: fresh-process DFlash bench, 3 reps × 5 samples, choose higher same-bit vs mq4v2 control median (tie → smaller draft). Draft control sha256 d0a74a232a0e2166d889f823e91e0fbf778d21dd9668d7de055cdecb065401bc. Acceptance null on every arm.

Worked example — Qwen3.6-35B-A3B as billed today

Nine product labels in registry/v1.json, 34,660,610,688 parameters. Measured:

Every label already lands inside its own bpw class — the A3B ladder is honest on § 1 today. The defect is legibility: nine labels where p, r, and mfp are opaque, and where mq4p and mfp4 are the same rung differing only by codec.

The mq2r adjudication. Its ladder is five precisions deep:

A third of the experts are lifted to 3-bit Lloyd, and the artifact is 0.165 bpw heavier than mq2. By content and by bytes that is a pro. The r suffix was specified to mean the lighter, Redline-oriented variant. Artifact and spec disagree about which direction the label points, and the file cannot tell us which one drifted.

That is the case for this table. With the rung declared at build time and bpw measured at publish, the disagreement is a build failure on the day it appears rather than something reconstructed from expert-tensor counts months later.

Hybrid lifts — what the roles are lifted to

A rung says which roles sit above base width. The precision they are lifted to is an encoder decision and may legitimately differ per architecture. Q8F16 costs about 8.5 bpw per weight against MQ4G256V2’s 4.25, measured as the 0.203 bpw step between mq4 (4.659) and mq4-xt (4.456), which differ primarily in the lm_head.

Lifting to MQ6 or MQ5 instead of Q8 therefore buys a rung back, and the size of that rebate depends entirely on how much of the model the lifted roles are:

On the dense model that is nearly a whole rung — the measured mq4 → mq4 pro step is 0.238 bpw — so an MQ6 lift can fund pro where only the base rung fit before (see mq2 pro / mq3 pro fixed-tier overrides). On the MoE it is noise, because the experts dominate the budget. Same product name either way, which is the reason codec is kept out of it.

4 · Orientation for people arriving from llama.cpp

Approximate neighbours by size. hipfire quotes measured model bpw, so these are comparable on bytes; compare quality on the published KLD, not on the tier name. Three rungs only:

Codec bpw (~4.25 for MQ4G256V2) is not a product rung; it is the encoding cost before role lifts.

5 · Migration

• File extensions do not move. mq4r_redline_default keys on the .mq4r extension, and the golden fixtures are SHA-256 pinned. Renaming artifacts would break sealed evidence. The product name lives in the registry card.
• qt numbers never move. Existing files keep loading forever.
• Withdraw codec generations from user-facing names (mq4v2, mq4c). They are days old and cost nothing to retire; the qt rows stay permanently.
• New quantizer output is named by rung, and the encoder is free to improve underneath without renaming the product.