formats: self-describing container stamp (TRUST-VERIFY-REFUSE) + FORMATS.md registry (#524) by monotophic · Pull Request #529 · JustVugg/colibri

monotophic · 2026-07-22T20:51:56Z

Authored by Fable 5 in Claude Code (We/our), analysis in partnership with @monotophic (me/my).

Revised per review (2026-07-23): restacked on #528's inverted collision policy — see the comment of this date for the revision + evidence. Where this description says PR 1 "refuses unconditionally" at ambiguous shapes: that predates the inversion. Current behavior: unstamped fmt=1-vs-fmt=7 ambiguity resolves to the incumbent (fmt=1); the stamp lets a stamped fmt=7 at such a shape be read as fmt=7. The fmt=6-vs-fmt=7 (I=98) collision still refuses unstamped, and a stamp there still resolves it.

fmt=7 registry + metadata stamp (TRUST-VERIFY-REFUSE)

Branch: fmt7/stamp-registry, stacked on fmt7/fp8-passthrough (PR 1 — CPU
path, repack tool, Metal kernel, collision/refusal logic; merge that one
first). This PR is the convention discussion the maintainer asked to keep
separate from the implementation: a self-describing container stamp, and the
in-repo format registry it's documented against. Nothing in PR 1's behavior
changes if this PR is never merged — PR 1 stands on its own: unstamped fmt=1-vs-fmt=7 ambiguity resolves to the incumbent, and the narrower fmt=6-vs-fmt=7 collision refuses. This PR's stamp confirms identity where arithmetic already decides, upgrades an ambiguous-shape fmt=7 from incumbent-resolution to its true format, and turns the remaining refusal into a resolution — it never turns a resolution into a refusal, and it never grants a decoder PR 1 doesn't have.

Why a stamp, and why now

QT.fmt is a plain int with no enum declaration and no in-repo list of
what's taken — the process gap that let #465 (E8/IQ3) and this project's own
FP8 proposal both mint fmt=6 independently, in the same week, with neither
author wrong. docs/FORMATS.md (this PR) is the lightweight fix for the
ordinal half of that gap: an in-repo table of what's assigned. The stamp is
the fix for the other half — a container's format identity shouldn't have
to depend on getting the number right by social coordination alone, and PR
1's own collision analysis shows byte arithmetic genuinely can't always
decide identity on its own (three structural ambiguities — one of them,
fmt=1-vs-fmt=7, at a shape GLM-5.2 actually ships: o_proj [6144,16384],
the very case the #528 review surfaced; the other two at shapes no real GLM
tensor has.). A NAME-based stamp is the thing that can actually check a NAME
against the bytes.

TRUST-VERIFY-REFUSE

Writer (tools/repack_fp8_passthrough.py): every tensor it repacks
into the fp8-e4m3-b128 container gets an entry in the output shard's
safetensors __metadata__["colibri.fmt"] — a JSON-encoded map of exact
tensor name → format NAME string ("fp8-e4m3-b128", never the internal
fmt=7 ordinal, which stays a colibri.c-only enum value the container never
depends on). The stamp names the WEIGHT format only, deliberately — not a
scale encoding, since fmt=7 can legitimately carry more than one (see PR 1's
"scale encoding is a declared property"; more below).

Reader (qt_verify_fmt_stamp + qt_resolve_fmt's new stamped_name
parameter, colibri.c):

Agree → silent no-op. A stamped, unambiguous tensor loads exactly as
it would unstamped.
Disagree, or the stamp names a format this build doesn't recognize →
refuse loudly (tensor name + both identities printed, exit(1)) — same
"untrusted container" discipline qt_resolve_fmt already applies
everywhere else.
Absent → zero behavior change. Byte-arithmetic inference alone
decides, exactly as before this feature existed — every container that
predates this PR, or comes from a tool that doesn't stamp, is unaffected.
Resolves an ambiguity (the bonus case): for PR 1's two collision
points — fmt=1-vs-fmt=7 (THE DESIGN LANDMINE) and fmt=6-vs-fmt=7 at
I=98 (SECOND DESIGN LANDMINE) — a stamp naming exactly one live,
decodable candidate resolves it directly instead of refusing. This is
the one case where the stamp becomes load-bearing rather than a
post-hoc cross-check: bytes alone are fundamentally ambiguous at these
shapes, so the stamp is the only thing that CAN decide.

What the stamp cannot do: grant a decoder this build doesn't have. A
tensor whose scale sidecar is UE8M0-shaped still refuses even when
correctly stamped "fp8-e4m3-b128" — in the clean, non-colliding case (PR
1's straightforward "recognized but not implemented" refusal) and in both
places a stamp could otherwise resolve a collision (the small-O
fmt=1-vs-UE8M0 corner, and the O∈(384,512], I=98 fmt=6-vs-UE8M0 corner).
The stamp confirms the WEIGHT format; the scale ENCODING is a separate,
declared property PR 1 only implements one value of. qt_resolve_fmt's own
comments carry the exact case-by-case rule.

The registry: `docs/FORMATS.md`

Adapted from the Feature Request draft already referenced on #524
(upstream_contribution/FORMATS_registry_draft.md on our side) into an
in-repo reference document:

Every format 0–7 in one table: ordinal, name, weight-byte layout,
scale-array layout, status, and the commit/PR it landed in.
fmt=7's row status reads "this PR pair" — the ordinal is public and
the implementation is what's under review, not a proposal anymore.
A dedicated "Scale encoding is a declared property (fmt=7)" section
documenting both values explicitly: f32 (implemented) and UE8M0
(recognized, refused by name, not implemented — the DeepSeek-V4 finding
credited to the maintainer's own Feature request: fp8-e4m3-b128 passthrough weight format — zero loss at int8 cost (repack, not requantize) #524 comment).
The PRIVATE ORDINAL BLOCK convention (100+ scratch-ordinal range for
in-flight branches) is kept intact, updated to cite fmt=7 itself as the
convention's own worked example: minted fmt=6 → collided with engine: fmt=6 E8/IQ3 lattice container — CPU decode kernel and dispatch (#452 step 3) #465 →
re-minted fmt=100 → graduated to the maintainer-assigned fmt=7, a
pure find-and-replace at every step, zero on-disk impact.
"How to add a format" gains one bullet: a Feature Request should
declare which scale/secondary-array encoding(s) it implements, not
just its byte layout — the precedent this PR sets.
Open questions for maintainer review, carried forward: is 100+ the
right private-block convention (or would a different reserved range be
preferred)? Should colibri.fmt become the project's standard stamp key,
or is a different shape preferred? Two questions from earlier drafts are
now resolved-by-events and marked as such (the engine: fmt=6 E8/IQ3 lattice container — CPU decode kernel and dispatch (#452 step 3) #465 sequencing question;
the scale-encoding-as-property question, decided by the maintainer on
Feature request: fp8-e4m3-b128 passthrough weight format — zero loss at int8 cost (repack, not requantize) #524).

Testing

tests/test_fp8_load.c Part D (four stamp outcomes: agreeing, mismatching,
unrecognized-name, absent — fork+waitpid for the two refusing cases) plus
stamped variants added to Part A2 (both collision directions resolve to the
stamped format; an unrelated stamp does NOT resolve; the UE8M0-scaled
corners of both collisions stay refused even when stamped
"fp8-e4m3-b128") and Part A3 (the clean UE8M0 case stays refused when
stamped; the small-O UE8M0-vs-fmt=1 collision DOES resolve when stamped
"int8-row", since that candidate is real and decodable).
tests/test_fp8_repack.py gains two cases (the stamp's tensor-name set
matches selection exactly; the real CLI's output carries a correct,
parseable stamp). tests/test_fp8_e2e_repack_load.py (inherited from PR 1)
now also asserts the real tool's stamp end-to-end against the real C loader.

make glm METAL=1 (clean rebuild): zero warnings, at both commits in
this PR individually.
make test-c: full C suite green, exit 0, at both commits — including
the expanded test_fp8_load (Parts A–D) and test_int3 (its 5
qt_resolve_fmt call sites updated for the new stamped_name
parameter, NULL throughout — this suite predates and is orthogonal to
the stamp feature).
make test-python: 154 tests, 10 skipped, 0 failures, exit 0.
make metal-test under COLI_METAL_RESSET=0 AND =1: both full
green, exit 0 — unaffected by this PR (the stamp is a CPU-side,
pre-Metal-dispatch concern; qt_from_disk resolves fmt before any
Metal call, so the GPU kernel never sees a stamp either way).
Per-commit gates verified in isolation, same discipline as PR 1.

Durable vs. current-state (review map)

	claim	durable / current-state	revisit trigger
1	TRUST-VERIFY-REFUSE discipline (agree=no-op, disagree=refuse, absent=unaffected)	durable	none — this is a correctness posture, not a calibration
2	A stamp resolves THE DESIGN LANDMINE and the SECOND DESIGN LANDMINE (f32-scaled candidates only)	durable	none — follows directly from PR 1's byte-arithmetic facts
3	`colibri.fmt` as the stamp's `__metadata__` key, JSON-map-of-name as its shape	current-state / provisional — explicitly flagged as this PR's proposal, open to revision, in `docs/FORMATS.md`'s own "Open questions" section	the maintainer (or a future project-wide stamp standard) choosing a different key/shape
4	`100+` PRIVATE ORDINAL BLOCK convention	current-state / provisional	maintainer endorsement, or a preferred alternative (negative values, a separate `fmt_ext` field)
5	A stamp cannot resolve any UE8M0-scaled collision (no decoder exists)	current-state, tied to PR 1's row 3	the same UE8M0 decoder that would flip PR 1's refusal flips this PR's stamp-resolution too, once it exists
6	measurement coordinates	checkable	measured 2026-07-22, macOS 26.5.2 (build 25F84), Apple M5 Max (MacBook Pro, Mac17,7), engine base = PR 1 tip

Commits in this PR

fp8: self-describing __metadata__ stamp, trust-verify-refuse reader —
st.h's stamp ingest/lookup, colibri.c's FMT_NAMES table and
qt_verify_fmt_stamp (post-hoc verify only, not yet resolving), the
repack tool's writer side, the two new test_fp8_repack.py cases.
fp8: qt_resolve_fmt lets a metadata stamp resolve byte collisions —
threads stamped_name into qt_resolve_fmt itself, making both
collision points stamp-resolvable (except the UE8M0 corners); updates
the three routed-expert call sites and test_int3.c's five direct
calls for the new signature; test_fp8_load.c Parts A2/A3 gain
stamped cases, new Part D.
docs: add FORMATS.md, the quantized-format registry (fmt=6/fmt=7 + convention) — this PR's own documentation, no code changes.

monotophic · 2026-07-22T21:05:01Z

Working on the Windows / MinGW fail. Will update with a fix shortly.

monotophic · 2026-07-22T21:33:33Z

Fixed and ready for review

JustVugg · 2026-07-22T22:32:23Z

Reviewed alongside #528. Answering the question you asked in #524 first, because it's the one that decides whether this convention is safe:

Does the stamp ever override byte-arithmetic inference? No — verified at every call site. Each stamp-consulting branch is gated on a candidate that is already byte-consistent: the fmt=6 block sits inside ns==4 && nb==O*e8_rowbytes(I); fp8_blk_f32_also and i8_row_also each require nb==O*I plus the matching block count; the landmine block only consults the stamp when both candidates are byte-valid; the UE8M0 branch requires is_row. A stamp disagreeing with an unambiguous inference hits qt_verify_fmt_stamp and refuses; an unrecognised name refuses; absent is a no-op. fp8_blk_f32_also (nblk==1) and fp8_blk_ue8m0_also (nblk==4) are mutually exclusive, so there's no double-resolve. TRUST-VERIFY-REFUSE holds as specified. Nice work — this is the right shape for the convention.

Four notes, none fatal:

It does not rescue fp8-e4m3-b128 passthrough weight format — CPU + Metal + repack tool (#524) #528's regression, and shouldn't be relied on to. Every container written before this convention is unstamped by definition, so the GLM-5.2 o_proj [6144,16384] collision I flagged on fp8-e4m3-b128 passthrough weight format — CPU + Metal + repack tool (#524) #528 still refuses. The registry is not a migration path for existing files — worth saying so explicitly in FORMATS.md, so nobody reads the stamp as retroactive protection.
st_fmt_stamp() is an O(n) linear strcmp scan per qt_from_disk. Fine today (residents only; routed experts pass NULL), but an untrusted container stamping 58k+ expert names makes every resident load walk the whole array. Bounded, not a crash — a hash or a cap on stamp-map size would close it.
st_fmt_stamp_ingest adds a new exit(1) surface at st_init_multi time. Fail-closed is defensible and unstamped containers are untouched, but note it now aborts model discovery, not just tensor load — worth documenting.
Stamps on non-.qs tensors are silently ignored (qt_verify_fmt_stamp is only called inside if(st_has(...))). Harmless, but "TRUST-VERIFY-REFUSE" reads as covering everything stamped; either verify them or scope the claim.

Test coverage is genuinely there and tests what it claims — the fork-based stderr assertions cover both stamp directions, the unrelated-stamp case and the UE8M0-stays-refused-when-stamped cases. The one false claim I found is shared with #528: the comment asserting qt_wire_mmap/qt_unwire_mmap now use qt_scale_bytes(). They still compute t->O*4 on both sides.

Verdict: good to merge on its own merits, but it's stacked on #528, so it goes in after the collision policy there is inverted. If you'd rather land the registry sooner, rebasing this onto dev independently of the fmt=7 work would let it merge on its own — the convention is valuable even before there's a seventh format to describe.

…tVugg#528 restack Maintainer review, JustVugg#529 (shared with JustVugg#528's fix): FORMATS.md cites specific c/colibri.c line numbers and branch/commit SHAs for every format row and for the metadata-stamp mechanism. Restacking fmt7/stamp-registry onto the revised fmt7/fp8-passthrough-rev1 (the JustVugg#528 INVERSION/qt_wire_split/stale-comment commits) shifted every colibri.c line number after qt_bytes(): qt_scale_bytes 216->223, qt_alloc 893->910, qt_resolve_fmt (and its SECOND DESIGN LANDMINE comment) 1144->1161, the FMT_NAMES table 1104->1121. Verified against the actual restacked file (grep for each cited function's definition line), not recomputed by offset arithmetic. The "Known formats" intro and "Sources for all rows" preamble also named the pre-restack branch/commit (fmt7/stamp-registry @ base 9a1690e) -- updated to fmt7/stamp-registry-rev1 @ base 696ce96, restacked on fmt7/fp8-passthrough-rev1 @ a77421d, with a note that these line numbers need re-verifying again if the branch is rebased further. No code changes, no test changes -- doc-only.

…qs scope Maintainer review, JustVugg#529 (four non-fatal notes): 1. Non-retroactivity: FORMATS.md gains an explicit section stating the stamp is a forward convention only -- it describes containers a stamping tool writes going forward, never retroactively. Every pre-convention container (including every container this repo's own tooling has ever produced) is simply unstamped, and byte-arithmetic inference alone decides for it, exactly as before this feature existed. The registry is not a migration path: there is no in-place upgrade for an existing container, only re-producing it through a stamping tool. 2. Stamp-map scan bound (orchestrator decision: CAP, not hash): st.h's st_fmt_stamp_ingest now caps the number of __metadata__["colibri.fmt"] entries it will ingest across a container's shards at ST_FMT_STAMP_MAX (4096) and refuses (exit(1)) past it, naming the bound in the error. Stamps are a resident-tensor convention -- a handful to a few hundred entries per model -- never the tens of thousands of routed-expert tensors a large MoE checkpoint carries; a container exceeding the cap is malformed by construction. tests/test_fp8_load.c tests both sides of the boundary: exactly ST_FMT_STAMP_MAX entries loads fine (no off-by-one false refusal), one more refuses (fork+waitpid, matching this suite's existing exit(1)-testing convention). 3. Discovery-time abort surface: st_fmt_stamp_ingest's exit(1) calls (this commit's cap included) fire from st_init_multi's shard-header-parse loop -- container DISCOVERY time, before any tensor is resolved against the model or a single weight byte is read. Documented at the call site (st.h) and in FORMATS.md: this is coarser-grained and earlier than qt_resolve_fmt/qt_verify_fmt_stamp's own per-tensor refusals, and the two are distinguishable at a glance -- this surface's messages name a shard FILE, the per-tensor surface names a TENSOR. 4. Non-.qs stamps (orchestrator decision: scope the claim, don't widen verification): confirmed at the source that qt_from_disk only ever calls st_fmt_stamp inside its `.qs`-sidecar branch -- a colibri.fmt entry naming any other tensor (raw f32/bf16, norm, router, embed/ lm_head) is ingested and stored like any other entry but never looked up, so it has no effect. FORMATS.md and st_fmt_stamp's own comment now state this scope explicitly rather than leaving it implicit. RAN (this commit): make clean && make portable -> clean rebuild, zero warnings. make test-c -> full C suite green, exit 0 (includes the two new stamp-map-cap cases). make test-python -> 155 tests, 10 skipped, 0 failures, exit 0. make glm METAL=1 -> clean rebuild, zero warnings. make metal-test under COLI_METAL_RESSET=0 AND =1: both full suite green, exit 0.

monotophic · 2026-07-23T06:30:24Z

Authored by Fable 5 in Claude Code, analysis in partnership with @monotophic
(we/our = the joint work; me/my = @monotophic alone).

All four notes taken; restacked on the revised #528. Head fe9ac93 on
9f6b4ab (#528's revised head, both rebased onto dev e4b5bf3).

Non-retroactivity is explicit in FORMATS.md: the stamp is a forward
convention; pre-convention containers resolve by byte arithmetic alone —
the registry is not a migration path and gives no retroactive protection.
Stamp-map lookup bounded: ST_FMT_STAMP_MAX=4096, refuse-on-exceed
with a named error (a container stamping tens of thousands of expert
names is malformed by the convention's own resident-tensor scope);
boundary tested on both sides.
The discovery-time exit(1) documented at the site and in
FORMATS.md — fail-closed at model discovery, not just tensor load.
Stamp scope stated: the convention covers .qs-backed tensors;
stamps on other tensors are ignored by design, and the docs now say so
(verified against the actual lookup gating before writing it).

Also corrected here: two FORMATS.md passages still described the
pre-inversion collision policy; both now state the actual rule (unstamped
ambiguity → incumbent at the reader; writer refuses; a stamp is what makes
an ambiguous-shape fmt=7 readable as fmt=7 going forward).

On your unstacking offer — keeping it stacked, deliberately: after the
inversion, the stamp is the only path by which an ambiguous-shape tensor
can ever legitimately read as fmt=7, so the two PRs define one collision
policy and are best reviewed in order. If your merge window prefers the
registry sooner, say the word and we'll re-derive it standalone.

Verification rode the same upgraded process as #528: the spec-blind
acceptance suite passes on this head (incl. bit-exact fmt=7 decode and the
collision-inversion invariants), the differential container matrix shows
byte-identical temp-0 output vs current dev on both real containers, and
the full gate set is green on fe9ac93 (make check, METAL=1 zero warnings,
metal-test both RESSET states, per-commit builds).

…tVugg#528 restack Maintainer review, JustVugg#529 (shared with JustVugg#528's fix): FORMATS.md cites specific c/colibri.c line numbers and branch/commit SHAs for every format row and for the metadata-stamp mechanism. Restacking fmt7/stamp-registry onto the revised fmt7/fp8-passthrough-rev1 (the JustVugg#528 INVERSION/qt_wire_split/stale-comment commits) shifted every colibri.c line number after qt_bytes(): qt_scale_bytes 216->223, qt_alloc 893->910, qt_resolve_fmt (and its SECOND DESIGN LANDMINE comment) 1144->1161, the FMT_NAMES table 1104->1121. Verified against the actual restacked file (grep for each cited function's definition line), not recomputed by offset arithmetic. The "Known formats" intro and "Sources for all rows" preamble also named the pre-restack branch/commit (fmt7/stamp-registry @ base 9a1690e) -- updated to fmt7/stamp-registry-rev1 @ base 696ce96, restacked on fmt7/fp8-passthrough-rev1 @ a77421d, with a note that these line numbers need re-verifying again if the branch is rebased further. No code changes, no test changes -- doc-only.

…qs scope Maintainer review, JustVugg#529 (four non-fatal notes): 1. Non-retroactivity: FORMATS.md gains an explicit section stating the stamp is a forward convention only -- it describes containers a stamping tool writes going forward, never retroactively. Every pre-convention container (including every container this repo's own tooling has ever produced) is simply unstamped, and byte-arithmetic inference alone decides for it, exactly as before this feature existed. The registry is not a migration path: there is no in-place upgrade for an existing container, only re-producing it through a stamping tool. 2. Stamp-map scan bound (orchestrator decision: CAP, not hash): st.h's st_fmt_stamp_ingest now caps the number of __metadata__["colibri.fmt"] entries it will ingest across a container's shards at ST_FMT_STAMP_MAX (4096) and refuses (exit(1)) past it, naming the bound in the error. Stamps are a resident-tensor convention -- a handful to a few hundred entries per model -- never the tens of thousands of routed-expert tensors a large MoE checkpoint carries; a container exceeding the cap is malformed by construction. tests/test_fp8_load.c tests both sides of the boundary: exactly ST_FMT_STAMP_MAX entries loads fine (no off-by-one false refusal), one more refuses (fork+waitpid, matching this suite's existing exit(1)-testing convention). 3. Discovery-time abort surface: st_fmt_stamp_ingest's exit(1) calls (this commit's cap included) fire from st_init_multi's shard-header-parse loop -- container DISCOVERY time, before any tensor is resolved against the model or a single weight byte is read. Documented at the call site (st.h) and in FORMATS.md: this is coarser-grained and earlier than qt_resolve_fmt/qt_verify_fmt_stamp's own per-tensor refusals, and the two are distinguishable at a glance -- this surface's messages name a shard FILE, the per-tensor surface names a TENSOR. 4. Non-.qs stamps (orchestrator decision: scope the claim, don't widen verification): confirmed at the source that qt_from_disk only ever calls st_fmt_stamp inside its `.qs`-sidecar branch -- a colibri.fmt entry naming any other tensor (raw f32/bf16, norm, router, embed/ lm_head) is ingested and stored like any other entry but never looked up, so it has no effect. FORMATS.md and st_fmt_stamp's own comment now state this scope explicitly rather than leaving it implicit. RAN (this commit): make clean && make portable -> clean rebuild, zero warnings. make test-c -> full C suite green, exit 0 (includes the two new stamp-map-cap cases). make test-python -> 155 tests, 10 skipped, 0 failures, exit 0. make glm METAL=1 -> clean rebuild, zero warnings. make metal-test under COLI_METAL_RESSET=0 AND =1: both full suite green, exit 0.

monotophic · 2026-07-23T19:40:11Z

Authored by Fable 5 in Claude Code, analysis in partnership with @monotophic
(we/our = the joint work; me/my = @monotophic alone).

Restacked on #528's rev3: head 24de8b1. Same re-verification as #528
(gates, acceptance suite, container matrix — all green on this head).
Content unchanged from what your four notes reviewed, per the revision
comment above.

…tVugg#528 restack Maintainer review, JustVugg#529 (shared with JustVugg#528's fix): FORMATS.md cites specific c/colibri.c line numbers and branch/commit SHAs for every format row and for the metadata-stamp mechanism. Restacking fmt7/stamp-registry onto the revised fmt7/fp8-passthrough-rev1 (the JustVugg#528 INVERSION/qt_wire_split/stale-comment commits) shifted every colibri.c line number after qt_bytes(): qt_scale_bytes 216->223, qt_alloc 893->910, qt_resolve_fmt (and its SECOND DESIGN LANDMINE comment) 1144->1161, the FMT_NAMES table 1104->1121. Verified against the actual restacked file (grep for each cited function's definition line), not recomputed by offset arithmetic. The "Known formats" intro and "Sources for all rows" preamble also named the pre-restack branch/commit (fmt7/stamp-registry @ base 9a1690e) -- updated to fmt7/stamp-registry-rev1 @ base 696ce96, restacked on fmt7/fp8-passthrough-rev1 @ a77421d, with a note that these line numbers need re-verifying again if the branch is rebased further. No code changes, no test changes -- doc-only.

…qs scope Maintainer review, JustVugg#529 (four non-fatal notes): 1. Non-retroactivity: FORMATS.md gains an explicit section stating the stamp is a forward convention only -- it describes containers a stamping tool writes going forward, never retroactively. Every pre-convention container (including every container this repo's own tooling has ever produced) is simply unstamped, and byte-arithmetic inference alone decides for it, exactly as before this feature existed. The registry is not a migration path: there is no in-place upgrade for an existing container, only re-producing it through a stamping tool. 2. Stamp-map scan bound (orchestrator decision: CAP, not hash): st.h's st_fmt_stamp_ingest now caps the number of __metadata__["colibri.fmt"] entries it will ingest across a container's shards at ST_FMT_STAMP_MAX (4096) and refuses (exit(1)) past it, naming the bound in the error. Stamps are a resident-tensor convention -- a handful to a few hundred entries per model -- never the tens of thousands of routed-expert tensors a large MoE checkpoint carries; a container exceeding the cap is malformed by construction. tests/test_fp8_load.c tests both sides of the boundary: exactly ST_FMT_STAMP_MAX entries loads fine (no off-by-one false refusal), one more refuses (fork+waitpid, matching this suite's existing exit(1)-testing convention). 3. Discovery-time abort surface: st_fmt_stamp_ingest's exit(1) calls (this commit's cap included) fire from st_init_multi's shard-header-parse loop -- container DISCOVERY time, before any tensor is resolved against the model or a single weight byte is read. Documented at the call site (st.h) and in FORMATS.md: this is coarser-grained and earlier than qt_resolve_fmt/qt_verify_fmt_stamp's own per-tensor refusals, and the two are distinguishable at a glance -- this surface's messages name a shard FILE, the per-tensor surface names a TENSOR. 4. Non-.qs stamps (orchestrator decision: scope the claim, don't widen verification): confirmed at the source that qt_from_disk only ever calls st_fmt_stamp inside its `.qs`-sidecar branch -- a colibri.fmt entry naming any other tensor (raw f32/bf16, norm, router, embed/ lm_head) is ingested and stored like any other entry but never looked up, so it has no effect. FORMATS.md and st_fmt_stamp's own comment now state this scope explicitly rather than leaving it implicit. RAN (this commit): make clean && make portable -> clean rebuild, zero warnings. make test-c -> full C suite green, exit 0 (includes the two new stamp-map-cap cases). make test-python -> 155 tests, 10 skipped, 0 failures, exit 0. make glm METAL=1 -> clean rebuild, zero warnings. make metal-test under COLI_METAL_RESSET=0 AND =1: both full suite green, exit 0.

monotophic · 2026-07-26T14:53:14Z

Authored by Fable 5 in Claude Code, analysis in partnership with @monotophic (We/our = the joint analysis; me/my = @monotophic's own hardware).

Restacked onto #528's rebased head (c635b8d, itself on dev c031307) — new head 8374a43. No conflicts and no content change: git range-diff reports 7/7 commits byte-identical to the reviewed rev3; this is the same patch series on a moved base.

Verification on the new head: fmt-7 acceptance suite (blind-built from the requirements spec) OVERALL: PASS on this tree · make check 211 OK · METAL=1 build zero warnings · metal-test under both COLI_METAL_RESSET states · per-commit bisect builds. Awaiting re-review as before; on merge, docs/FORMATS.md registry goes live unchanged.

…tVugg#528 restack Maintainer review, JustVugg#529 (shared with JustVugg#528's fix): FORMATS.md cites specific c/colibri.c line numbers and branch/commit SHAs for every format row and for the metadata-stamp mechanism. Restacking fmt7/stamp-registry onto the revised fmt7/fp8-passthrough-rev1 (the JustVugg#528 INVERSION/qt_wire_split/stale-comment commits) shifted every colibri.c line number after qt_bytes(): qt_scale_bytes 216->223, qt_alloc 893->910, qt_resolve_fmt (and its SECOND DESIGN LANDMINE comment) 1144->1161, the FMT_NAMES table 1104->1121. Verified against the actual restacked file (grep for each cited function's definition line), not recomputed by offset arithmetic. The "Known formats" intro and "Sources for all rows" preamble also named the pre-restack branch/commit (fmt7/stamp-registry @ base 9a1690e) -- updated to fmt7/stamp-registry-rev1 @ base 696ce96, restacked on fmt7/fp8-passthrough-rev1 @ a77421d, with a note that these line numbers need re-verifying again if the branch is rebased further. No code changes, no test changes -- doc-only.

…qs scope Maintainer review, JustVugg#529 (four non-fatal notes): 1. Non-retroactivity: FORMATS.md gains an explicit section stating the stamp is a forward convention only -- it describes containers a stamping tool writes going forward, never retroactively. Every pre-convention container (including every container this repo's own tooling has ever produced) is simply unstamped, and byte-arithmetic inference alone decides for it, exactly as before this feature existed. The registry is not a migration path: there is no in-place upgrade for an existing container, only re-producing it through a stamping tool. 2. Stamp-map scan bound (orchestrator decision: CAP, not hash): st.h's st_fmt_stamp_ingest now caps the number of __metadata__["colibri.fmt"] entries it will ingest across a container's shards at ST_FMT_STAMP_MAX (4096) and refuses (exit(1)) past it, naming the bound in the error. Stamps are a resident-tensor convention -- a handful to a few hundred entries per model -- never the tens of thousands of routed-expert tensors a large MoE checkpoint carries; a container exceeding the cap is malformed by construction. tests/test_fp8_load.c tests both sides of the boundary: exactly ST_FMT_STAMP_MAX entries loads fine (no off-by-one false refusal), one more refuses (fork+waitpid, matching this suite's existing exit(1)-testing convention). 3. Discovery-time abort surface: st_fmt_stamp_ingest's exit(1) calls (this commit's cap included) fire from st_init_multi's shard-header-parse loop -- container DISCOVERY time, before any tensor is resolved against the model or a single weight byte is read. Documented at the call site (st.h) and in FORMATS.md: this is coarser-grained and earlier than qt_resolve_fmt/qt_verify_fmt_stamp's own per-tensor refusals, and the two are distinguishable at a glance -- this surface's messages name a shard FILE, the per-tensor surface names a TENSOR. 4. Non-.qs stamps (orchestrator decision: scope the claim, don't widen verification): confirmed at the source that qt_from_disk only ever calls st_fmt_stamp inside its `.qs`-sidecar branch -- a colibri.fmt entry naming any other tensor (raw f32/bf16, norm, router, embed/ lm_head) is ingested and stored like any other entry but never looked up, so it has no effect. FORMATS.md and st_fmt_stamp's own comment now state this scope explicitly rather than leaving it implicit. RAN (this commit): make clean && make portable -> clean rebuild, zero warnings. make test-c -> full C suite green, exit 0 (includes the two new stamp-map-cap cases). make test-python -> 155 tests, 10 skipped, 0 failures, exit 0. make glm METAL=1 -> clean rebuild, zero warnings. make metal-test under COLI_METAL_RESSET=0 AND =1: both full suite green, exit 0.

monotophic · 2026-07-28T21:46:22Z

Authored by Fable 5 in Claude Code, analysis in partnership with @monotophic (We/our = the joint work; me/my = @monotophic's own hardware and commitments).

Restacked onto #528 rev5 (dbf8d00, on dev a3a5a75) — rev5, head e0874b2. Clean replay: all 7 commits byte-identical to rev4 (range-diff 7/7 =), zero conflicts.

Verification on e0874b2 (all re-run on this head, macOS 26.5 / M5 Max):

gate	result
METAL=1 build	0 warnings
`make check`	OK (13 skipped)
`metal-test`, both `COLI_METAL_RESSET` states	ok
per-commit bisect builds	7/7, 0 warnings each
fmt-7 acceptance suite (collision/refusal battery)	OVERALL PASS — stamp-resolution and refusal paths exercised on the stacked tree
Windows-CI safety (`fork`/`pipe`/`waitpid` in tests)	comment-aware scan of this branch's changed test files: all code-level POSIX constructs inside `#ifndef _WIN32` (same content passed the Windows leg at rev4)

Stacked on fmt7/fp8-passthrough (PR 1). Ports fmt6/fp8-passthrough-r2's metadata-stamp feature (originally ff4b403, folded here against this branch's fmt=7 renumbering and already-reconciled qt_resolve_fmt) as the first commit of PR 2 (registry + metadata stamp), split out per the maintainer's JustVugg#524 scoping. This commit adds the stamp infrastructure and a POST-HOC verify step; it does NOT yet let a stamp resolve a genuine byte-collision inside qt_resolve_fmt itself -- that is the next commit, mirroring the source branch's own bisectable two-commit shape (stamp scaffolding, then the resolve-power threaded in). st.h: new FORMAT METADATA STAMP fields on `shards` (fmt_name/fmt_val/fmt_n/ fmt_cap) + st_fmt_stamp_ingest (parses each shard's __metadata__["colibri.fmt"] -- itself JSON text, a {tensor_name: format_name} map, since safetensors __metadata__ values are always plain strings) + st_fmt_stamp (lookup). Wired into st_init_multi's real header-parse loop. Absent __metadata__, or absent colibri.fmt key, is NOT an error (unstamped container, byte-arithmetic decides as before); a colibri.fmt key present but malformed IS refused (same untrusted-container discipline as the rest of the loader). Unchanged from the source commit -- this file never touched fmt numbering. colibri.c: FMT_NAMES table (name string <-> internal fmt int, renumbered fp8-e4m3-b128 -> 7) + qt_fmt_by_name/qt_name_by_fmt + qt_verify_fmt_stamp (TRUST-VERIFY-REFUSE: agreeing stamp is a silent no-op; disagreeing or unrecognized-name stamp refuses loudly; absent stamp is a no-op, zero behavior change for unstamped containers). Table includes a placeholder "e8-iq3-lattice" entry for dev's own fmt=6 (dev has no stamp feature of its own). Called from qt_from_disk right after qt_resolve_fmt -- deliberately NOT threaded into the routed-expert loader paths (repack_fp8_passthrough.py never stamps routed experts). tools/repack_fp8_passthrough.py: writer side. FORMAT_NAME="fp8-e4m3-b128" / METADATA_KEY="colibri.fmt" constants; repack_shard() now also returns fmt_map ({weight_name: FORMAT_NAME}, keyed by weight only, never the .qs sidecar); main() JSON-encodes it (sort_keys, deterministic) into the output shard's __metadata__ via safetensors.save_file(metadata=...). tests/test_fp8_repack.py: two new cases (fmt_map covers exactly the selected weight names; end-to-end __metadata__.colibri.fmt present and correct through the real CLI) plus the repack_shard() call sites updated for its new 3-tuple return. tests/test_fp8_e2e_repack_load.py and tests/test_fp8_e2e_loader.c: the stamp-agreement checks this branch's earlier commit (PR 1) deliberately omitted -- since PR 1's tool never wrote a stamp, there was nothing to check -- are restored now that the tool stamps again. Does NOT yet include: qt_resolve_fmt's stamped_name parameter (next commit), test_fp8_load.c's Part D stamp-outcome suite (next commit, since it needs stamped containers exercised through the full qt_from_disk path -- this commit's plumbing is sufficient for that, but it lands with the parameter-threading commit to keep the two reviewable as one coherent "stamp becomes load-bearing" change, matching the source branch's own split). RAN (this commit): make clean && make glm METAL=1 -- clean rebuild, zero warnings. make test-c -> full C suite green, exit 0 (test_fp8_load unaffected -- no stamped fixtures in its current suite, byte-arithmetic inference alone still decides every case). make metal-test under COLI_METAL_RESSET=0: full suite green, exit 0, all fp8 GPU lines ok (unaffected -- Metal-side code never touches the stamp). python3 -m unittest tests.test_fp8_repack -v -> 11/11 pass. python3 -m unittest tests.test_fp8_e2e_repack_load -v -> 1/1 pass (the real repack tool's stamp checked end-to-end against the real C loader, which now verifies it transparently via qt_verify_fmt_stamp). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Stacked on the previous commit. Ports fmt6/fp8-passthrough-r2's qt_resolve_fmt stamp-threading (originally fb3b45d), rebuilt against this branch's already-reconciled qt_resolve_fmt (both THE DESIGN LANDMINE and the SECOND DESIGN LANDMINE, plus the UE8M0 scale-encoding seam added on fmt7/fp8-passthrough) rather than cherry-picked -- the source commit predates all three of those. Closes the gap the previous commit deliberately left open: qt_verify_fmt_stamp only ran AFTER qt_resolve_fmt, so a genuinely ambiguous tensor was refused unconditionally regardless of any stamp. colibri.c: qt_resolve_fmt gains a `stamped_name` parameter (NULL for every routed-expert caller -- repack_fp8_passthrough.py never stamps routed experts). Both collision points now consult it: - THE DESIGN LANDMINE (fmt=1 vs fmt=7-f32): a stamp naming exactly one of "int8-row"/"fp8-e4m3-b128" resolves directly; anything else falls through to the existing refusal. - SECOND DESIGN LANDMINE (fmt=6 vs fmt=7 at I=98): a stamp naming "e8-iq3-lattice"/"int8-row"/"fp8-e4m3-b128" resolves the matching candidate; anything else refuses as before. Neither collision point lets a stamp grant a decoder this build doesn't have: a "fp8-e4m3-b128" stamp on a tensor whose scale sidecar is UE8M0-shaped (not f32-shaped) still refuses in both places -- the stamp confirms the WEIGHT format, not the scale ENCODING, and this build only implements f32 block scales. This is new relative to the source project's original stamp-resolve commit, which predates the UE8M0 seam entirely; it's the direct consequence of keeping "declared property, not guaranteed decodable" honest under a stamp. qt_verify_fmt_stamp's signature is unchanged (name, stamped, fmt) -- qt_from_disk now looks the stamp up via st_fmt_stamp ONCE and passes it to BOTH qt_resolve_fmt (to resolve) and qt_verify_fmt_stamp (to re-confirm, trivially, in the resolved case). The three routed-expert call sites (2x expert_load_impl, uring_finalize_load) gain the new trailing NULL argument with a one-line comment explaining why. tests/test_int3.c (pre-existing, predates the fp8 work entirely) calls qt_resolve_fmt directly in 5 places and would not have compiled against the new 7-argument signature -- fixed by threading stamped_name=NULL through all 5 calls (this suite is orthogonal to the fp8 metadata-stamp feature; none of its calls touch the collisions the stamp parameter exists for). tests/test_fp8_load.c: expect_fmt/expect_refuse split into stamped variants (expect_fmt_stamped/expect_refuse_stamped, taking the new stamped_name parameter) with the original two names becoming thin NULL-stamped wrappers -- every existing call site is therefore unchanged in behavior. test_fmt6_fp8_collision (Part A2) and test_ue8m0_scale_refusal (Part A3) both gain stamped cases: successful resolution where the stamp names a real, decodable candidate; STILL refuses where the only stamped candidate is the ue8m0-scaled one (no decoder); an "unrelated stamp doesn't resolve" case. New Part D (test_stamp_agreeing/mismatching/unrecognized_name/absent) covers qt_verify_fmt_stamp's four outcomes on an otherwise-unambiguous tensor, fork+waitpid for the two refusing cases. RAN (this commit): make clean && make glm METAL=1 -- clean rebuild, zero warnings. ./tests/test_fp8_load -> "fp8 loader-seam tests: ok" (Parts A through D, including every new stamped/collision/ue8m0 case). make test-c -> full C suite green, exit 0 (test_int3/test_int3_load unaffected by the signature change). make test-python -> 154 tests, 10 skipped, 0 failures, exit 0. make metal-test under COLI_METAL_RESSET=0 AND =1: both full suite green, exit 0, all fp8 GPU lines ok, RESSET=1 confirmed active. This completes Branch B / PR 2's colibri.c-side content. docs/FORMATS.md (the registry document) is a separate, following commit. FIX ROUND (Windows CI, rebased onto the fixed fmt7/fp8-passthrough): this commit both renames expect_refuse -> expect_refuse_stamped AND introduces a second fork-based helper, expect_stamp_refuse (Part D) -- both need the same #ifndef _WIN32 gate the previous branch's fix applied to expect_refuse's original body. Gated both, same pattern: POSIX arm unchanged (fork/pipe/waitpid, exit(1) capture), Windows arm prints "skipped on Windows (no fork): <tag>" per case and returns pass-through. colibri.c and test_int3.c carried forward byte-identical to the pre-fix f400fa4 (this cherry-pick's only real conflict was the expect_refuse -> expect_refuse_stamped rename colliding textually with the sibling branch's #ifndef insertion at the same line; resolved by hand, diff-verified against both parents). RAN (fix round, this commit): make glm METAL=1 -- clean rebuild, zero warnings. ./tests/test_fp8_load -> "fp8 loader-seam tests: ok", zero "skipped on Windows" lines (POSIX fork path confirmed still exercised on this platform, not silently bypassed). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

…nvention) Stacked on the previous two commits, closing out Branch B / PR 2's content. Adapts upstream_contribution/FORMATS_registry_draft.md (the Feature Request draft already posted, referenced verbatim on JustVugg#524) into an in-repo reference doc: renumbered fmt=100 -> fmt=7 throughout, line citations re-verified against this branch's actual current colibri.c/quant.h (substantially rewritten from the draft's source tree by the PR-1/PR-2 restructuring), and three content updates specific to this PR pair: - fmt=7's table row status is "this PR pair" (was "proposed"), since the ordinal is no longer private and the implementation is the thing under review. - A new "Scale encoding is a declared property (fmt=7)" section documents both values explicitly: f32 (implemented, what Z.ai's GLM-5.2-FP8 checkpoints ship and what this PR pair's CPU/Metal/repack code reads and writes) and UE8M0 (recognized by its distinct byte signature, refused by name, not implemented -- the DeepSeek-V4 finding the maintainer surfaced on JustVugg#524, credited here). Documents the exact refusal message, the collision check against fmt=1's own ns arithmetic, and that a stamp naming "fp8-e4m3-b128" cannot grant this build a decoder it doesn't have. - "Open questions for maintainer review" gains a second resolved question (scale-encoding-as-declared-property, decided on JustVugg#524) alongside the already-resolved JustVugg#465 sequencing question; the still-open questions (100+ convention acceptability, colibri.fmt key naming) carry forward unchanged. The PRIVATE ORDINAL BLOCK convention section is kept intact (per the task's explicit instruction), updated only to cite fmt=7 as the convention's own worked example of a private ordinal graduating to a public one. "How to add a format" gains one bullet: a format's Feature Request should declare which scale/secondary-array ENCODING(s) it implements, not just its byte layout, matching the precedent this PR pair sets. Read-only source: upstream_contribution/FORMATS_registry_draft.md (untracked, main checkout only) -- consulted for content, not modified; this commit's docs/FORMATS.md is a new, independently-committed file. No code changes in this commit; make glm METAL=1 / make test-c re-run as a sanity check (unaffected by a docs-only change) -- clean rebuild, zero warnings, full C suite green, exit 0. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

…tVugg#528 restack Maintainer review, JustVugg#529 (shared with JustVugg#528's fix): FORMATS.md cites specific c/colibri.c line numbers and branch/commit SHAs for every format row and for the metadata-stamp mechanism. Restacking fmt7/stamp-registry onto the revised fmt7/fp8-passthrough-rev1 (the JustVugg#528 INVERSION/qt_wire_split/stale-comment commits) shifted every colibri.c line number after qt_bytes(): qt_scale_bytes 216->223, qt_alloc 893->910, qt_resolve_fmt (and its SECOND DESIGN LANDMINE comment) 1144->1161, the FMT_NAMES table 1104->1121. Verified against the actual restacked file (grep for each cited function's definition line), not recomputed by offset arithmetic. The "Known formats" intro and "Sources for all rows" preamble also named the pre-restack branch/commit (fmt7/stamp-registry @ base 9a1690e) -- updated to fmt7/stamp-registry-rev1 @ base 696ce96, restacked on fmt7/fp8-passthrough-rev1 @ a77421d, with a note that these line numbers need re-verifying again if the branch is rebased further. No code changes, no test changes -- doc-only.

…qs scope Maintainer review, JustVugg#529 (four non-fatal notes): 1. Non-retroactivity: FORMATS.md gains an explicit section stating the stamp is a forward convention only -- it describes containers a stamping tool writes going forward, never retroactively. Every pre-convention container (including every container this repo's own tooling has ever produced) is simply unstamped, and byte-arithmetic inference alone decides for it, exactly as before this feature existed. The registry is not a migration path: there is no in-place upgrade for an existing container, only re-producing it through a stamping tool. 2. Stamp-map scan bound (orchestrator decision: CAP, not hash): st.h's st_fmt_stamp_ingest now caps the number of __metadata__["colibri.fmt"] entries it will ingest across a container's shards at ST_FMT_STAMP_MAX (4096) and refuses (exit(1)) past it, naming the bound in the error. Stamps are a resident-tensor convention -- a handful to a few hundred entries per model -- never the tens of thousands of routed-expert tensors a large MoE checkpoint carries; a container exceeding the cap is malformed by construction. tests/test_fp8_load.c tests both sides of the boundary: exactly ST_FMT_STAMP_MAX entries loads fine (no off-by-one false refusal), one more refuses (fork+waitpid, matching this suite's existing exit(1)-testing convention). 3. Discovery-time abort surface: st_fmt_stamp_ingest's exit(1) calls (this commit's cap included) fire from st_init_multi's shard-header-parse loop -- container DISCOVERY time, before any tensor is resolved against the model or a single weight byte is read. Documented at the call site (st.h) and in FORMATS.md: this is coarser-grained and earlier than qt_resolve_fmt/qt_verify_fmt_stamp's own per-tensor refusals, and the two are distinguishable at a glance -- this surface's messages name a shard FILE, the per-tensor surface names a TENSOR. 4. Non-.qs stamps (orchestrator decision: scope the claim, don't widen verification): confirmed at the source that qt_from_disk only ever calls st_fmt_stamp inside its `.qs`-sidecar branch -- a colibri.fmt entry naming any other tensor (raw f32/bf16, norm, router, embed/ lm_head) is ingested and stored like any other entry but never looked up, so it has no effect. FORMATS.md and st_fmt_stamp's own comment now state this scope explicitly rather than leaving it implicit. RAN (this commit): make clean && make portable -> clean rebuild, zero warnings. make test-c -> full C suite green, exit 0 (includes the two new stamp-map-cap cases). make test-python -> 155 tests, 10 skipped, 0 failures, exit 0. make glm METAL=1 -> clean rebuild, zero warnings. make metal-test under COLI_METAL_RESSET=0 AND =1: both full suite green, exit 0.

…k tool) FIX ROUND 2, item 2 (clean-room conformance trial finding): docs/FORMATS.md described the PRE-inversion design in two places quoted directly from the file -- (a) the PR-pair intro paragraph ("refusing UNCONDITIONALLY at every ambiguous shape, since it carries no stamp... adds the stamp... that lets those same collisions resolve instead of refuse") and (b) the metadata-stamp section ("a stamp can also resolve a genuine byte-count collision... instead of the collision refusing unconditionally"). Both contradict the code and the document's own provenance note, which already cites the INVERSION elsewhere. Rewrote both to the post-inversion truth: an unstamped ambiguous shape resolves to the incumbent (int8-row) at the reader; the writer refuses to ever emit unstamped ambiguity; a stamp's role for THAT collision is letting a genuinely-stamped fmt=7 tensor still be read as fmt=7 (overriding the unstamped default), not resolving a refusal that no longer happens for the unstamped case. The OTHER collision (fmt=6-vs-fmt=7, SECOND DESIGN LANDMINE) is unchanged by the inversion and still refuses unconditionally unstamped -- kept accurate, not conflated with the first. Found (while fixing the above, same error class, not a new idea) a third instance in the "Sources for all rows" section describing `stamped_name` generically as resolving both collisions "instead of refusing unconditionally" -- corrected for the same reason, so the document doesn't contradict itself internally after the main fix. Found a FOURTH instance while touching tools/repack_fp8_passthrough.py for item 3 (separate commit): that tool's own METADATA STAMP docstring section had the identical stale claim -- corrected there too. docs/FORMATS.md's pre-existing authorship banner and every commit's own trailers are untouched, per the standing rule from the prior fix round. No code changes, no test changes -- doc/docstring-only.

Same Linux pipe short-read fix as expect_refuse's (see the commit below this stack): the Part D stamp refusal tests use the identical single-read capture and would truncate long refusal messages the same way.

…ssignment Registry follow-through for the renumber commit on PR 1's branch: our fp8-e4m3-b128 row moves to fmt=8, and fmt=7 gains its real, factual row -- MXFP4 (e2m1 nibbles + per-32-group f32 scales), Kimi K3's native routed-expert tier, Vulkan backend only, merged via JustVugg#676/JustVugg#705. A registry whose rows disagree with dev at birth would defeat the document's purpose. New "ID assignment" paragraph states the rule the last two weeks demonstrated twice: an ordinal is claimed by the first merge into dev; there is no reservation mechanism; an assignment on an open PR or issue does not survive a competing merge; proposers must scan dev AND open PRs; this registry is the coordination point. Also re-verified every c/colibri.c / c/quant.h line number cited in the Sources section against the current restack (base dev 292ed4c) and updated the verification paragraph accordingly, plus the one stray fmt=7-referencing stamp comment in tests/test_int3.c.

…ision-family pinning Review-round findings on the registry/doc/test layer, one commit: FORMATS.md: the fmt=6 name column said "e8-iq3" while FMT_NAMES -- the string qt_fmt_by_name actually matches -- says "e8-iq3-lattice"; the registry's name column IS the canonical stamp string, so a tool stamping the documented name would have been refused as unrecognized. Fixed at both sites (table row + Sources bullet), and a new python unittest (tests/test_formats_registry.py) pins doc<->FMT_NAMES parity permanently: it regexes the two authoritative texts directly (a generated header would be a third copy that can go stale exactly like the doc did), asserts plausibility floors so anchor drift fails loudly, and requires any doc row without a C-side name to say "no in-tree name string" explicitly. Mutation-proven: reverting the fmt=6 row name fails the test. FORMATS.md MXFP4 row, two precision fixes: the Vulkan host gate is gs >= 8 && gs % 8 == 0 (backend_vulkan.c), and the scale column now documents the CONTAINER layout (one UE8M0 u8 exponent per 32-input group) with the f32 expansion noted as an upload-time transform (kimi_k3.c's mx4_scale loop) -- registry columns describe what is on disk, not the post-upload GPU representation. st.h: the ST_FMT_STAMP_MAX comment overstated what the cap bounds -- the colibri.fmt blob is json_parse'd in full BEFORE the per-entry check fires (that allocation is bounded by ST_MAX_HEADER), so the cap bounds the persistent fmt_name/fmt_val strdup arrays and the later linear scans, not the parse. Reworded factually here and in FORMATS.md's "Stamp-map scan bound" section. Collision-family pinning: the ue8m0-vs-fmt=1 unstamped-refusal family is exactly nb==O*I && ns==O*4 && ceil(O/128)*ceil(I/128)==4*O (is_row && is_blk_ue8m0; is_blk can never co-hold). tests/test_fp8_load.c Part A3b pins the current polarity at two more member shapes -- [2,1024] and [129,33000] (nblkO=2, past the block edge) -- refuse unstamped, resolve under an "int8-row" stamp; RAN-confirmed against real artifacts in both directions (this head refuses by name; a dev 292ed4c build loads the same bytes as fmt=1). The "No real GLM tensor has these shapes" prose in qt_resolve_fmt's comment and FORMATS.md is replaced with the membership condition plus the checked census bound: at I<=16384 membership forces O<=32, and every GLM-5.2 role has O>=576 (tools/fp8_collision_census.py, census run in the rev5 round). Found while pinning the family, same test-vacuity class as the review's findings: expect_refuse's strstr(err,"refus") was satisfied by the test's own TAG echoed through qt_resolve_fmt's leading "%s:" -- and the ue8m0 refusal message itself contained no refusal wording at all, so the check had never actually verified it. The message now ends with an explicit "refusing rather than misreading the sidecar (untrusted container)" (matching every sibling refusal's wording), and expect_refuse_stamped skips the echoed tag before searching, so the assertion reads the ENGINE's words only. Mutation-proven: reverting the message wording fails the ue8m0 suite.

User-ratified design (register D8): at most one DISTINCT format claim per tensor name, container-wide. st_fmt_stamp_ingest now scans the already-ingested map before appending: an entry that repeats an earlier claim verbatim is tolerated and collapsed to one entry (idempotent -- a centralized-manifest writer may stamp the same map into every shard); an entry that CONTRADICTS an earlier claim refuses loudly at discovery time, naming the tensor and both format names. A container that disagrees with itself about a tensor's format is corrupted or hostile; the previous first-wins behavior made the outcome depend on shard enumeration order (st_scan_dir is raw readdir order) and mis-diagnosed the conflict downstream as a stamp/inference mismatch -- or hid it entirely when enumeration favored the agreeing claim. The earlier claim's shard file is not named in the message: per-entry shard provenance isn't stored, and adding it for one message would be new plumbing (only the current shard's path is in scope at the check). Explicit non-goals, now stated in docs/FORMATS.md's stamp rules: no locality constraint (a shard MAY stamp tensors it doesn't contain -- centralized-manifest writers stay legal; that is also exactly what makes cross-shard conflicts reachable), and no coverage requirement at load (unstamped tensors and containers load exactly as before; completeness is a writer-side guarantee, diagnostic deferred). Tests (tests/test_fp8_load.c): a two-shard fixture with the same tensor stamped 'fp8-e4m3-b128' in one shard and 'int8-row' in the other must refuse at st_init with the named conflict message (asserting both format names, either enumeration order); the agreeing-duplicate twin must load normally with the map collapsed to one entry (fmt_n==1); the existing single-stamp and unstamped suites pin the unchanged cases. Proven to bite: the conflict test against the pre-fix head fails -- first-wins survives discovery and the child reaches the must-not-get-here exit.

monotophic · 2026-07-30T19:53:33Z

Authored by Fable 5 in Claude Code, analysis in partnership with @monotophic

rev6: restacked on #528 rev6 + registry corrections + one new refusal

@JustVugg this is now rebased with enhancements/fixes. Head: 38c2185,
stacked on #528 rev6 (bda0ed0); merge #528 first, asbefore. Three
things changed beyond the restack:

Registry corrections. The fmt=6 name now matches the loader's own
table byte-for-byte (e8-iq3-lattice; the rev5 doc said e8-iq3 — a
stamping tool following the registry would have emitted names the loader
refuses, in the artifact whose purpose is preventing exactly that). The
registry's name column is pinned to FMT_NAMES by a new test, so this
class cannot recur. The registry also gains a factual fmt=7 = MXFP4
row (merged Kimi K3 engine: native-MXFP4 expert streaming, KDA + gated NoPE MLA + AttnRes + LatentMoE (#658) #676/Vulkan: fmt=7 MXFP4 decode + Kimi K3 GPU tier (follow-up to #418) #705, Vulkan tier — container carries UE8M0 u8 exponents
per 32-group, expanded to f32 at upload) and an ID-assignment section:
ordinals are claimed by first merge into dev; there is no reservation
mechanism; this registry is the coordination point. Our row moves to
fmt=8 accordingly (see the fp8-e4m3-b128 passthrough weight format — CPU + Metal + repack tool (#524) #528 comment for the renumber record).
Conflicting duplicate stamps now refuse at ingest. Previously the
stamp lookup was first-wins across shards: a container whose shards
disagreed about a tensor's format got shard-enumeration-order-dependent
behavior — demonstrated on the pre-fix build, where the same
self-contradicting container refused with a wrong diagnosis in one
readdir order and loaded silently in the other. Now the contradiction is
named at discovery: agreeing duplicate stamps stay legal and idempotent
(centralized manifest writers remain supported — no shard-locality
constraint), and coverage remains optional at load (unstamped tensors
and containers load exactly as before; completeness is a writer-side
guarantee). Documented in the registry's stamp rules.
Stamp-cap comment corrected to state precisely what the cap bounds
(the persistent name/value arrays and lookup scans — not the header-parse
allocation, which the existing ST_MAX_HEADER bounds).

Claim	Decisive evidence
Registry names are loader-canonical	Parity test parses the registry table and diffs it against `FMT_NAMES`; run against the rev5 defect, it fails with exactly that divergence
Conflict refusal works, order-independently	Two-shard conflicting fixture refuses naming both formats in either enumeration order; same fixture on the pre-fix build survives ingest (pasted); agreeing-duplicate fixture loads
Stamp semantics otherwise unchanged	TRUST-VERIFY-REFUSE suites green and mutation-proven (polarity reversion caught); unstamped behavior byte-identical (A1 matrix in the #528 comment)

Gates: identical record to the #528 comment (this head), plus the stamped
arm of the 13,200-probe resolver sweep and the registry parity suite.

Corrects JustVugg#731, which globbed tests/test_*.c. That was wrong in the opposite direction from the hand-written list it replaced: it promoted files that deliberately have no build rule into gates. On dev the four such files were known and excluded by name, so the set came out identical and the mistake was invisible; on a contributor branch it is not. Merging dev into JustVugg#529 promoted that branch's tests/test_fp8_e2e_loader.c -- a file monotophic has but never gated -- and the build failed on an undefined reference to sqrtf. Having a build rule is the honest definition of a gate, so derive the list from the rules. TEST_EXCLUDE drops from five entries to one: test_uring, which has a rule but is Linux-only and is appended conditionally just below. The property that motivated all of this is unchanged and now stronger: adding a gate means adding your .c and its own rule, which land in different places in the file. There is no shared list left to conflict on at all. Verified identical to current dev (31 entries, same names) and make test-c green. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Resolved by a maintainer instead of asking for another rebase. The only conflicting hunk was the hand-written TEST_BINS line, which dev no longer has: gates are derived from the build rules, so this branch's tests are picked up by their own rules and the manual list entry is dropped. No other file conflicted and no commit on this branch was rewritten. Verified before pushing: every test this branch adds a rule for is in the gate set, and make test-c passes. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

monotophic mentioned this pull request Jul 22, 2026

Feature request: fp8-e4m3-b128 passthrough weight format — zero loss at int8 cost (repack, not requantize) #524

Closed

monotophic force-pushed the fmt7/stamp-registry branch from 902a5ea to a7851fc Compare July 22, 2026 21:24

This was referenced Jul 23, 2026

metal: grouped-int4 (fmt=4) GEMV support + two latent fmt=4 fixes #457

Merged

Metal: platform-aware expert-cache defaults via honest storage probe (#379) #386

Merged

monotophic force-pushed the fmt7/stamp-registry branch from a7851fc to fe9ac93 Compare July 23, 2026 06:23

monotophic force-pushed the fmt7/stamp-registry branch from fe9ac93 to 24de8b1 Compare July 23, 2026 19:27

monotophic mentioned this pull request Jul 24, 2026

[Feature]: Lossless entropy compression for streamed expert traffic (transport layer, any container) #594

Open

monotophic force-pushed the fmt7/stamp-registry branch from 24de8b1 to 8374a43 Compare July 26, 2026 14:45

This was referenced Jul 28, 2026

entropy: in-tree rANS codec, int4-rans256-g0 container format, offline tools #671

Merged

cuda: add experimental lossless compressed expert tier #651

Merged

JustVugg added the enhancement New feature or request label Jul 28, 2026

monotophic force-pushed the fmt7/stamp-registry branch from 8374a43 to e0874b2 Compare July 28, 2026 21:42

JustVugg mentioned this pull request Jul 29, 2026

The learning cache is engine-specific: .coli_usage has two incompatible writers and two engines that cannot produce it at all #700

Closed

terrizoaguimor mentioned this pull request Jul 30, 2026

refactor(telemetry): one expert history for every engine (#700) #716

Merged

monotophic and others added 9 commits July 30, 2026 15:24

tests: drain child stderr to EOF in the stamp-test capture helpers

aad0750

Same Linux pipe short-read fix as expect_refuse's (see the commit below this stack): the Part D stamp refusal tests use the identical single-read capture and would truncate long refusal messages the same way.

monotophic force-pushed the fmt7/stamp-registry branch from e0874b2 to 38c2185 Compare July 30, 2026 19:42

monotophic mentioned this pull request Jul 30, 2026

fp8-e4m3-b128 passthrough weight format — CPU + Metal + repack tool (#524) #528

Merged

JustVugg mentioned this pull request Jul 31, 2026

build: derive TEST_BINS from the build rules, not the .c files (corrects #731) #733

Merged

JustVugg and others added 2 commits August 1, 2026 00:18

JustVugg merged commit 9458439 into JustVugg:dev Jul 31, 2026
10 checks passed

JustVugg mentioned this pull request Aug 1, 2026

Release v1.4.0: Vulkan backend, all four engines in the archives, Kimi K3 GPU tier #711

Merged

monotophic deleted the fmt7/stamp-registry branch August 1, 2026 01:51

This was referenced Aug 1, 2026

[Feature]: nvme to gpu (nvfp4) or nvme + ram to gpu (nvfp4) #734

Open

inkling: shared experts to the GPU, 1.75 to 2.46 tok/s on Apple Silicon #757

Open

Navigation Menu

formats: self-describing container stamp (TRUST-VERIFY-REFUSE) + FORMATS.md registry (#524) - #529

formats: self-describing container stamp (TRUST-VERIFY-REFUSE) + FORMATS.md registry (#524)#529
JustVugg merged 12 commits into
JustVugg:devfrom
monotophic:fmt7/stamp-registry

monotophic commented Jul 22, 2026 •

edited

Loading

Uh oh!

monotophic commented Jul 22, 2026

Uh oh!

monotophic commented Jul 22, 2026

Uh oh!

JustVugg commented Jul 22, 2026

Uh oh!

monotophic commented Jul 23, 2026

Uh oh!

monotophic commented Jul 23, 2026

Uh oh!

monotophic commented Jul 26, 2026

Uh oh!

monotophic commented Jul 28, 2026

Uh oh!

monotophic commented Jul 30, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

monotophic commented Jul 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

fmt=7 registry + metadata stamp (TRUST-VERIFY-REFUSE)

Why a stamp, and why now

TRUST-VERIFY-REFUSE

The registry: docs/FORMATS.md

Testing

Durable vs. current-state (review map)

Commits in this PR

Uh oh!

monotophic commented Jul 22, 2026

Uh oh!

monotophic commented Jul 22, 2026

Uh oh!

JustVugg commented Jul 22, 2026

Uh oh!

monotophic commented Jul 23, 2026

Uh oh!

monotophic commented Jul 23, 2026

Uh oh!

monotophic commented Jul 26, 2026

Uh oh!

monotophic commented Jul 28, 2026

Uh oh!

monotophic commented Jul 30, 2026

rev6: restacked on #528 rev6 + registry corrections + one new refusal

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

monotophic commented Jul 22, 2026 •

edited

Loading

The registry: `docs/FORMATS.md`