gguf-export.md (EN+TR) shows verify-gguf checking vocab size, manifest sha256 and tokenizer round-trip, none of which exist (CR-A09-006) #85

Wave 0 · theme D0-2: GGUF integrity chain: the .sha256 sidecar · highest severity High · 1 finding(s) · effort medium

Summary

An exported GGUF carries the wrong tokenizer. verify-gguf exits 0, while the gguf-export page told the operator that verify-gguf checks the tokenizer round-trip and the vocab against the base.

Primary finding

CR-A09-006 — gguf-export.md (EN+TR) shows verify-gguf checking vocab size, manifest sha256 and tokenizer round-trip, none of which exist

severity High · reachability default · intent contract-violation · confidence confirmed · independently confirmed · reproduced end to end · already tracked: KNOWN-OPEN TRUST-04 — docs/roadmap/phase-16-trust-surface-hardening.md:423-424 (S5 open)

What happens. docs/usermanuals/{en,tr}/deployment/gguf-export.md (EN 73-81) illustrate verify-gguf output with vocab-size, manifest and tokenizer round-trip checks, but verify_gguf (forgelm/verify/_gguf.py:46-181) runs only the magic, optional metadata-parse and optional sidecar checks and takes no base-model argument.

Where.

• docs/usermanuals/en/deployment/gguf-export.md:73-79 (output block), 81 (claim sentence)
• docs/usermanuals/tr/deployment/gguf-export.md:75-79 (output block), 81 (claim sentence)
• forgelm/verify/_gguf.py:59-62 (docstring claims the exporter writes the sidecar, which is false)
• forgelm/verify/_gguf.py:184-210
• forgelm/cli/subcommands/_verify_gguf.py:114-129
• docs/usermanuals/en/deployment/gguf-export.md:74-81
• docs/usermanuals/tr/deployment/gguf-export.md:75-79
• forgelm/cli/subcommands/_verify_gguf.py:66-129
• docs/usermanuals/en/deployment/gguf-export.md:22
• docs/usermanuals/en/deployment/gguf-export.md:56-69

Evidence.

• A tiny GGUF written with gguf 0.19.0's GGUFWriter (one tensor, no vocab, no tokenizer) gave forgelm verify-gguf t.gguf -> 'OK: t.gguf / GGUF magic OK, metadata parsed', checks magic_ok/metadata_parsed/metadata_error/sidecar_present/sidecar_match/tensor_count, exit 0. No vocab or tokenizer check exists to fail.
• The verify-gguf run on the exported GGUF listed exactly magic_ok, metadata_parsed, metadata_error, sidecar_present, sidecar_match and tensor_count. The parser accepts only 'path' (forgelm/cli/_parser.py:931-951).
• The real verify-gguf text output prints only 'OK: ', the reason, and the checks keys magic_ok, metadata_parsed, metadata_error, sidecar_present, sidecar_match and tensor_count (observed). export writes only the .gguf file (observed).

Recommended fix. Replace the gguf-export.md example with the real verify-gguf output (as in verify-gguf.md:57-67) and drop the vocab and tokenizer claims in EN and TR, or implement those checks.

Acceptance criteria

• A regression test reproduces the failure scenario and asserts the corrected behaviour.
• Documentation listed above is corrected in English and in its Turkish mirror in the same PR.
• Every finding in this issue is resolved or explicitly closed with a reason.
• The release note names the contract this fix restores.

_{Found by the October 2026 ForgeLM code and documentation review against commit cab2947. Code links point at that commit; line numbers may have moved since. Finding IDs (CR-…, DOC-…, TECH-…) are stable references for this backlog.}