[PR #5789] [MERGED] fix(model): preserve unsupported GGUF version diagnostics #7063

New issue

Closed

opened 2026-11-01 21:45:04 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-11-01 21:45:04 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/morluto/rea/pull/5789
Author: @gensokyo-dev
Created: 10/21/2026
Status: ✅ Merged
Merged: 10/21/2026
Merged by: @gensokyo-dev

Base: main ← Head: fix/5749-gguf-version-diagnostic

📝 Commits (1)

f78b0be fix(model): preserve unsupported GGUF version diagnostics

📊 Changes

3 files changed (+68 additions, -7 deletions)

View changed files

📝 docs/model-artifacts.md (+5 -0)
📝 src/model/GgufHeader.ts (+12 -7)
📝 tests/boundary/model/modelArtifact.test.ts (+51 -0)

📄 Description

Summary

Fixes #5749. Unsupported little-endian GGUF version 1 currently claims to be version 16777216, and version 4 becomes 67108864. The parser assumes big-endian whenever it does not recognize a little-endian version.

Change and scope

Select byte order in GgufHeader only after recognizing an existing version encoding. Otherwise preserve the four source bytes, both UINT32 interpretations and explicit unknown byte order in the refusal. For example, 01000000 reports little-endian 1 / big-endian 16777216, with byte order unknown. This agrees with the pinned format specification.

The shared producer supplies CLI/MCP reasons. Typed errors, supported layouts, header/full-hash choices, resource limits and schemas remain unchanged. Existing static file inspection only; no additional maintainer scope decision is applicable. The branch includes upstream #5781 before qualification, without attributing that separate optimization to this fix.

Evidence and validation

npm run test:focused -- tests/boundary/model/modelArtifact.test.ts tests/boundary/model/modelArtifactPartialCancellation.test.ts tests/boundary/mcp/modelArtifactPartialCancellation.test.ts tests/acceptance/modelArtifactCli.test.ts — 78 tests passed on the rebased head. The eight new diagnostic regressions fail on original main and updated d36cb6121; v2 controls pass.
npm run check — passed typecheck, lint, format, knip, metadata and architecture guards. npm run docs:check — passed, including five docs tests.
Actual CLI and SDK stdio MCP: twelve version/endian controls pass their expected outcomes. Unknown versions remain refused; LE v2/v3 and BE v3 succeed; BE v2 retains its existing refusal. Both adapters return identical typed reasons and leave source bytes unchanged.
Real stories260K.gguf, 1,185,376 bytes, SHA-256 047bf46455a544931cff6fef14d7910154c56afbc23ab1c5e56a72e69912c04b. Independent gguf 0.19.0 confirms 48 tensor declarations, all 19 metadata keys and four headline values. CLI summaries, retained MCP pages, full Evidence export, header/full-file hashes and cleanup agree before/after. Header mode continues reading only 14,152 bytes; tensor payloads and inference are not inspected.

Performance and limits

Same updated base, completed known-name workflow: fresh CLI summary + complete Evidence file; fresh MCP handshake, two summaries, a selected tensor page, full-hash summary and full Evidence export, including verification and cleanup. Before/after: 6.525/6.800 s elapsed, 6.450/6.576 s CPU, 935.02/939.50 MiB peak process-family memory. Earlier fresh-process measurements varied from 6.8–15.1 s; OS caches/shared-host conditions are uncontrolled, so no speedup or memory reduction is claimed.

Captured JSON-RPC (including initialization), CLI arguments and compact receipt total 11,433 cl100k_base estimated tokens in each run. No catalog discovery occurs in this known-name task; actual model usage and chat framing are unmeasured. The corrected v1 refusal costs 38 additional estimated tokens per CLI/MCP reply to preserve the source facts and uncertainty. Successful model output and schema context do not grow.

Heavy verification commands use one CPU, 8 GiB memory, a 7 GiB early-stop threshold and no swap; payload-exit cgroup receipts record zero OOM events and cleaned analysis children. Real historical v1 and big-endian models and Windows/macOS runtime verification remain unavailable; BE support is qualified by source-built metadata/tensor and public CLI/MCP header controls. No package metadata or new runtime dependencies.

Author readiness

Human owner: @gensokyo-dev

The session's human owner explicitly delegated completion of these declarations and requested ready publication. This records that standing instruction, without claiming an additional manual human review occurred during this run.

I reviewed the final diff and relevant existing code, understand the change and its edge cases, and take responsibility for the complete PR, including AI-assisted work.
I checked the evidence above, confirmed it supports the current change, and recorded meaningful validation gaps.
I declare this PR ready for initial maintainer review.

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/morluto/rea/pull/5789 **Author:** [@gensokyo-dev](https://github.com/gensokyo-dev) **Created:** 10/21/2026 **Status:** ✅ Merged **Merged:** 10/21/2026 **Merged by:** [@gensokyo-dev](https://github.com/gensokyo-dev) **Base:** `main` ← **Head:** `fix/5749-gguf-version-diagnostic` --- ### 📝 Commits (1) - [`f78b0be`](https://github.com/morluto/rea/commit/f78b0be86a6f7dcb397bcd5ecea44c61321f9cbd) fix(model): preserve unsupported GGUF version diagnostics ### 📊 Changes **3 files changed** (+68 additions, -7 deletions) <details> <summary>View changed files</summary> 📝 `docs/model-artifacts.md` (+5 -0) 📝 `src/model/GgufHeader.ts` (+12 -7) 📝 `tests/boundary/model/modelArtifact.test.ts` (+51 -0) </details> ### 📄 Description ## Summary Fixes #5749. Unsupported little-endian GGUF version 1 currently claims to be version 16777216, and version 4 becomes 67108864. The parser assumes big-endian whenever it does not recognize a little-endian version. ## Change and scope Select byte order in `GgufHeader` only after recognizing an existing version encoding. Otherwise preserve the four source bytes, both UINT32 interpretations and explicit unknown byte order in the refusal. For example, `01000000` reports little-endian 1 / big-endian 16777216, with byte order unknown. This agrees with the [pinned format specification](https://github.com/ggml-org/ggml/blob/da8e2a54b919557b816b1c2beb432ccb766f7ce0/docs/gguf.md#file-structure). The shared producer supplies CLI/MCP reasons. Typed errors, supported layouts, header/full-hash choices, resource limits and schemas remain unchanged. Existing static file inspection only; no additional maintainer scope decision is applicable. The branch includes upstream #5781 before qualification, without attributing that separate optimization to this fix. ## Evidence and validation - `npm run test:focused -- tests/boundary/model/modelArtifact.test.ts tests/boundary/model/modelArtifactPartialCancellation.test.ts tests/boundary/mcp/modelArtifactPartialCancellation.test.ts tests/acceptance/modelArtifactCli.test.ts` — 78 tests passed on the rebased head. The eight new diagnostic regressions fail on original main and updated `d36cb6121`; v2 controls pass. - `npm run check` — passed typecheck, lint, format, knip, metadata and architecture guards. `npm run docs:check` — passed, including five docs tests. - Actual CLI and SDK stdio MCP: twelve version/endian controls pass their expected outcomes. Unknown versions remain refused; LE v2/v3 and BE v3 succeed; BE v2 retains its existing refusal. Both adapters return identical typed reasons and leave source bytes unchanged. - Real [stories260K.gguf](https://huggingface.co/ggml-org/tiny-llamas/blob/99dd1a73db5a37100bd4ae633f4cfce6560e1567/stories260K.gguf), 1,185,376 bytes, SHA-256 `047bf46455a544931cff6fef14d7910154c56afbc23ab1c5e56a72e69912c04b`. Independent gguf 0.19.0 confirms 48 tensor declarations, all 19 metadata keys and four headline values. CLI summaries, retained MCP pages, full Evidence export, header/full-file hashes and cleanup agree before/after. Header mode continues reading only 14,152 bytes; tensor payloads and inference are not inspected. ## Performance and limits Same updated base, completed known-name workflow: fresh CLI summary + complete Evidence file; fresh MCP handshake, two summaries, a selected tensor page, full-hash summary and full Evidence export, including verification and cleanup. Before/after: **6.525/6.800 s elapsed**, **6.450/6.576 s CPU**, **935.02/939.50 MiB peak process-family memory**. Earlier fresh-process measurements varied from 6.8–15.1 s; OS caches/shared-host conditions are uncontrolled, so no speedup or memory reduction is claimed. Captured JSON-RPC (including initialization), CLI arguments and compact receipt total **11,433 cl100k_base estimated tokens in each run**. No catalog discovery occurs in this known-name task; actual model usage and chat framing are unmeasured. The corrected v1 refusal costs 38 additional estimated tokens per CLI/MCP reply to preserve the source facts and uncertainty. Successful model output and schema context do not grow. Heavy verification commands use one CPU, 8 GiB memory, a 7 GiB early-stop threshold and no swap; payload-exit cgroup receipts record zero OOM events and cleaned analysis children. Real historical v1 and big-endian models and Windows/macOS runtime verification remain unavailable; BE support is qualified by source-built metadata/tensor and public CLI/MCP header controls. No package metadata or new runtime dependencies. ## Author readiness Human owner: @gensokyo-dev The session's human owner explicitly delegated completion of these declarations and requested ready publication. This records that standing instruction, without claiming an additional manual human review occurred during this run. - [x] I reviewed the final diff and relevant existing code, understand the change and its edge cases, and take responsibility for the complete PR, including AI-assisted work. - [x] I checked the evidence above, confirmed it supports the current change, and recorded meaningful validation gaps. - [x] I declare this PR ready for initial maintainer review. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi

2026-11-01 21:45:04 +00:00