feat(pack): map routed-expert stacks and any decoder-layer naming

[Alberto-Codes]

vramfit pack could not consume a recipe for the chart #158 target.
The GGUF backend matched every non-flag group against
^model\.layers\.(\d+)$ and raised PackError on everything else.
Two names the scan now produces hit that refusal: a stack group from
--group-by stack (#161), and the Nemotron 3.5 Lightning target's
backbone.layers.<n> naming (#160). So no --group-by value packed
that model.

• Derive the layer index from the group name, so .layers.<n>,
  .h.<n>, and .blocks.<n> all become blk.<n>.
• Map a routed-expert stack to its fused GGUF tensor,
  blk.<n>.ffn_up_exps. or blk.<n>.ffn_down_exps. (Can a GGUF recipe address one expert, or does llama.cpp fuse the expert stack? #159)
• Carry the target's backbone.embeddings beside
  model.embed_tokens, so a whole layer-keyed recipe maps
• Refuse a recipe naming two layer stacks — GGUF numbers one stack
  blk.<n>., and the target's mtp.layers.<n> and a multimodal
  vision tower each collide with the backbone
• Order protection, then expert-stack, then layer overrides —
  llama-quantize applies the first matching pattern, and
  blk\.1\. also matches blk.1.ffn_up_exps.weight
• Refuse every other group by name, and clear the caveats in
  docs/reference/sensitivity-map.md and the ADR-0022 amendment

Test: uv run pytest -q, plus -m e2e and a HYPOTHESIS_PROFILE=thorough run

Closes #180

---

PR Review

Checklist

• Self-reviewed my code
• All gates pass (pre-commit run --all-files and a push-stage run)
• Doc statuses promoted/demoted where code moved (CLAUDE.md trust rules)
• New ports have verified-fake contract suites (ADR-0009)
• Breaking changes use ! in title and BREAKING CHANGE: in body

Review Focus

The review cycle ran on the first commit and found two real defects.
Both are fixed in 5e07141, and both are worth a second look.

The embedding group was still a fixed literal. The first commit
generalized the layer prefix and left EMBEDDING_GROUP as
model.embed_tokens. The target's checkpoint index names it
backbone.embeddings, so a layer-keyed recipe still refused on its
53rd group and the claim that the target packs was false. Both
reviewers found this independently. The contract fixture had masked
it by pairing backbone.layers.<n> with the llama-style embedding
name — a recipe no real scan produces. The fixture now uses real
names.

A free layer prefix cannot tell one layer stack from another.
mtp.layers.0 and backbone.layers.0 both mapped to blk\.0\., and
the first-match rule dropped one assignment silently. A multimodal
vision tower does the same, and GGUF names it v.blk.<n>.. Before
this branch those raised. Turning a loud refusal into a silent
mispack is the one outcome this module exists to prevent, so the
backend now refuses a recipe naming two roots. This also constrains
the chart's MTP question: backbone and MTP cannot be scanned together.

What still does not pack. A whole-model stack-keyed recipe.
--group-by stack groups every parameter with 2 or more dimensions,
so the recipe also carries the Mamba in_proj, out_proj, and
conv1d, the attention projections, the router, and the shared
experts. Each refuses by name. #183 carries that table, and it first
needs a ruling on what a recipe does with a group llama-quantize
never quantizes.

The sharpest thing this PR does not fix: #189. QK_K is 256 and
the target's expert rows are 2688 and 1856, so every k-quant this
backend emits is unreachable on 93.0% of its parameters.
tensor_type_fallback runs after a manual --tensor-type
override, so the quantizer substitutes and never errors. Making the
stack addressable makes this reachable for the first time — the
recipe is honoured on paper and rewritten in the artifact.

Related

Chart #158. Evidence: #159 (fusion, 46 stacks, the fallback
mechanism), #160 (architecture, naming), #161 (ADR-0001 amendment,
the stack key). Unblocks #178. Follow-ups filed from the review:
#183, #189, #190. Unrelated find: #185. ADR-0012 decision 2 and the
ADR-0022 amendment both gain a 2026-08-12 amendment here.

[Copilot]

Pull request overview

Updates the GGUF pack backend so vramfit pack can consume recipes for Nemotron-style naming and routed-expert stack groups, while preserving the “refuse unknown groups loudly” guardrail and documenting the remaining limitations.

Changes:

• Generalize decoder-layer group matching to derive blk.<n>. from multiple naming families (.layers.<n>, .h.<n>, .blocks.<n>).
• Add routed-expert stack mapping to fused GGUF tensors (blk.<n>.ffn_{up,down,gate}_exps.) and enforce override ordering (protections → stacks → layers).
• Expand contract/unit/integration coverage and update ADR/reference docs to reflect the new mapping and refusal behavior.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
tests/unit/adapters/test_gguf_types.py	Adds unit coverage for layer-family index derivation, expert-stack mapping, escaping, ordering, and refusal messages.
tests/integration/test_torch_scan_adapter.py	Updates integration assertion to track multiple embedding group names via EMBEDDING_GROUPS.
tests/contract/test_recipe_packer_contract.py	Extends contract suite to verify stack-shaped Nemotron recipes pack and argv ordering is correct.
src/vramfit/domain/pack.py	Clarifies PackResult override ordering semantics in docstring.
src/vramfit/adapters/outbound/gguf/types.py	Implements generalized layer matching, expert-stack mapping, single-root refusal, and embedding group set.
docs/reference/sensitivity-map.md	Updates warning to reflect what stack scans can pack (expert stacks only) and what still refuses.
docs/adr/0022-within-layer-protections.md	Adds 2026-08-12 amendment describing the narrowed-but-not-lifted refusal behavior.
docs/adr/0012-gguf-type-mapping.md	Adds 2026-08-12 amendment detailing new group shapes, ordering, embedding name set, and one-root refusal.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.