From 844ca083159eed8f2dd9149ea47e71a5a21841dd Mon Sep 17 00:00:00 2001 From: Ettore Di Giacinto Date: Sat, 15 Aug 2026 19:26:29 +0000 Subject: [PATCH] policy(porting): a model port documents the WEIGHTS it was fed, not just the code (#672) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Developer-directed. MiniMax-Music3 is the case that made it concrete: the port landed complete, and a reader still could not run it without being told that the 57.4 GB repository is ~28.5 GB in the arm we actually load, split across six component directories, with a native `.pth` layout we refuse by name and thirteen community quantized repositories we do not implement. None of that is inferable from a header file. The code is the easy half to publish; saying WHAT TO FEED IT is the half that makes the port usable, and it was nowhere in the checklist. THE RULE, in `.agents/porting-a-model.md` §2.1 with a checkbox in §2 and a pointer from AGENTS.md's "Shared seams": every ported model documents the checkpoints it was built and gated against in `docs/USAGE.md`, in the SAME change that makes the capability reachable, mirroring the table MiniMax-H3 already carries — file name, size, and a link to the exact HuggingFace repo, grouped by arm. WHAT A ROW OWES, and each clause is there because something bit us: * The repo id AND the revision. A repo id alone is not a pin -- `unsloth/Qwen3.6-27B-NVFP4` was silently re-quantized in place under an unchanged name, and Music3's GGUF lineage is published four different ways under one model (`audiocpp`, `mm3`, `qwen3`, `wan`) with `wan` colliding with genuine Wan video GGUFs. A quantized artifact records its sha256 too. * Which arms are REFUSED, so a user reads the refusal in the docs rather than discovering it at load time -- the same polarity as the refuse-by-name rule one paragraph above it. * The total RESIDENT size, because that is what decides whether a reader can run it at all, and it is not the repository's size. * Whether a THIRD PARTY published it. Community quant repos are the arm most users actually reach for and they carry different provenance from a first-party release. Placed in `porting-a-model.md` rather than in `verification.md` or `benchmarking.md` because it is a property of SHIPPING a model, not of gating or measuring one, and because that file is the checklist an implementer already has open. AGENTS.md carries the rule in prose so it is reachable without opening the guide. Issue: #672 FOLLOWING_AGENTS_PROTOCOL Following-Agents-Protocol: true AI-Assisted: true Assisted-by: AGENT:claude-opus-5 [Claude Code] --- .agents/porting-a-model.md | 30 ++++++++++++++++++++++++++++++ AGENTS.md | 9 +++++++++ 2 files changed, 39 insertions(+) diff --git a/.agents/porting-a-model.md b/.agents/porting-a-model.md index 8650a5149..6971fe66f 100644 --- a/.agents/porting-a-model.md +++ b/.agents/porting-a-model.md @@ -86,6 +86,36 @@ llama.cpp comparison needs. - [ ] A structural gate accounts for **every** tensor in the real checkpoint index — enumerated == present, zero unaccounted — reading headers only, env-gated so CI never needs the asset. +- [ ] **The weights are DOCUMENTED, by repo and revision, in `docs/USAGE.md`.** + See §2.1 — this is a shipping obligation, not a nicety. + +### 2.1 Say which weights, from where — a port nobody can feed is not shipped + +**Every ported model documents the checkpoints it was built and gated against, in +`docs/USAGE.md`, in the same change that makes the capability reachable.** Mirror +the table MiniMax-H3 already carries (`docs/USAGE.md`, the H3 sections): one row +per artifact, with the **file name, its size, and a link to the exact HuggingFace +repo**, grouped by arm (bf16/fp16, GGUF, NVFP4, …). + +What a row owes: + +- [ ] The **repo id and the revision** it was fetched at. A repo id alone is not + a pin: `unsloth/Qwen3.6-27B-NVFP4` was silently re-quantized in place under + an unchanged name, and a Music3 GGUF lineage was published four different + ways under one model. For a quantized artifact, record the **sha256** too. +- [ ] Which arm the artifact belongs to, and **which arms are refused**, so a + user reads the refusal here rather than discovering it at load time. +- [ ] The **total resident size** of the set, because that is what decides + whether a reader can run it at all. +- [ ] Where a **third party** published it rather than the model's own authors, + say so — community quant repos are the arm most users will actually reach + for, and they carry different provenance from a first-party release. + +**Why this is a rule.** Weights are the part of a port a reader cannot infer from +the code. A checkpoint that is 57 GB in total but ~28 GB in the arm we actually +load, split across six component directories, with a native layout we refuse by +name, is not something anyone reconstructs from a header file. The port is the +easy half to publish; saying *what to feed it* is the half that makes it usable. ## 3. Forward diff --git a/AGENTS.md b/AGENTS.md index e87f6105c..ef65a1144 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -318,6 +318,15 @@ unimplemented arm with a message that names the missing part. Record the arm as owed. Never leave the missing path to be discovered later. Use [`.agents/porting-a-model.md`](.agents/porting-a-model.md) as the checklist. +**Say which weights, and from where.** Every ported model documents the +checkpoints it was built and gated against in [`docs/USAGE.md`](docs/USAGE.md), +in the same change that makes the capability reachable: file name, size, and the +exact HuggingFace repo *and revision*, grouped by arm, with a sha256 for a +quantized artifact and the refused arms named beside them. A repo id alone is not +a pin, because checkpoints get re-quantized in place under an unchanged name. +Weights are the one part of a port a reader cannot infer from the code, so code +shipped without them is something nobody can feed. + ## Nothing lands dead A shared seam says where a capability routes. This section says whether anything