[PR #5603] [MERGED] feat(model): inspect GGUF and safetensors declarations #6991

New issue

Closed

opened 2026-11-01 21:44:33 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-11-01 21:44:33 +00:00

Owner

📋 Pull Request Information

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

Base: main ← Head: feat/3323-model-artifacts

📝 Commits (9)

a4d2edf feat(model): inspect GGUF and safetensors declarations
4f004f3 chore: merge main for model artifact integration
49b016d fix(model): classify truncation after admission as an artifact change
6108352 chore: refresh main before model format review fixes
a15c1af fix(model): validate format keys and header budget origins
8556837 fix(model): validate retained identities and bound selected views
b8ae48f chore: refresh main before final model integration checks
097771f fix(model): accept empty GGUF tensors and bound summary headlines
62b640a chore: qualify model inspection with current main

📊 Changes

60 files changed (+3835 additions, -3 deletions)

View changed files

📝 .agents/skills/reverse-engineer-anything/SKILL.md (+9 -0)
📝 .agents/skills/reverse-engineer-anything/references/native-and-artifacts.md (+10 -0)
📝 README.md (+1 -0)
📝 docs/.vitepress/config.ts (+1 -0)
📝 docs/cli.md (+13 -0)
➕ docs/model-artifacts.md (+145 -0)
📝 docs/readme/README_ar.md (+1 -0)
📝 docs/readme/README_de.md (+1 -0)
📝 docs/readme/README_el.md (+1 -0)
📝 docs/readme/README_es.md (+1 -0)
📝 docs/readme/README_fa.md (+1 -0)
📝 docs/readme/README_fr.md (+1 -0)
📝 docs/readme/README_id.md (+1 -0)
📝 docs/readme/README_it.md (+1 -0)
📝 docs/readme/README_ja.md (+1 -0)
📝 docs/readme/README_ko.md (+1 -0)
📝 docs/readme/README_ml.md (+1 -0)
📝 docs/readme/README_pl.md (+1 -0)
📝 docs/readme/README_pt-BR.md (+1 -0)
📝 docs/readme/README_ru.md (+1 -0)

...and 40 more files

📄 Description

Closes #3323.

Problem and outcome

Bundled model files previously reached an unsupported-binary result. inspect_model_artifact / inspect-model-artifact now exposes GGUF v2/v3 (both byte orders) and safetensors declarations through one local workflow: typed metadata, tensor identity/shape/type/ranges, and explicitly derived element/storage totals.

Default hash: "header" reads only the header/directory. It returns a scoped header digest, exact path/extent and bytes read; full-file SHA-256 and the Evidence subject remain null. Explicit hash: "full" streams every file byte for full SHA-256 without interpreting weights. Metadata arrays retain typed counts and eight-element previews with omissions recorded; scalar values, integer widths and negative zero survive JSON delivery.

Optional view returns selected rows plus model context in the initial call. Retained model-artifact views support batched names/keys/types/indices, fields, storage-validation states and pagination. Complete Evidence remains accessible. Unknown types keep their identity; declared ranges and unknown storage-size validation stay separate. Historical pages use validated positional indexes and unique names/keys/types, cached with immutable parent facts; they never reopen the file. Only the source-scoped index is mandatory: long labels obey field selection. Bounded view warnings link to complete parent Evidence.

Boundary and scope

The format readers own interpretation; application services own Evidence and delivery; CLI/MCP share both. One admitted descriptor/inspection, bounded prefix reads, a 100,000,000-byte GGUF prefix/safetensors JSON ceiling (excluding its 8-byte length field) and separate 32 MiB retained representation budget constrain work before expansion. File replacement/truncation, cancellation and failed-close ownership use existing filesystem/resource primitives. The EOF follow-up distinguishes concurrent truncation from initially malformed declarations.

This is built-in static format inspection within the supported contribution scope. Inspection reads existing local files. CLI compact delivery and explicit Evidence export create caller-selected output files through existing atomic publication. Model execution, target attachment, inference, external-file traversal and runtime network access are outside the operation; no new runtime dependency or installer behavior.

Executed validation

Final integration 62b640a60, tree 9a5a4d7a9, main 5b676ba9f: 54 reader tests + 5 public model CLI/MCP workflows passed. check:ci 8 tasks + architecture guards across 1,665 files passed, duplication 3.47%; generated docs and 5 README tests passed. No new test files; prior discovery found every test exactly once.
Shared-workflow coverage: 190 tests / 6 files passed at 85568378c, following 214 / 9 on the earlier main integration. After newer main, 21 generic MCP cases + 5 model workflows passed in isolation. One preceding constrained attempt hit two generic 30 s timeouts; deadlines were unchanged. New-main Apple producers passed 31 tests. Its evaluation helper suite passed 7 cases and failed one 1 s preparation deadline; the helper, test and process/filesystem/artifact dependencies are identical to main, with no model path involved. That single case then passed in isolation without changing deadlines. Failed attempts are retained; these are scoped passes, not a green full-suite claim.
Actual stdio SDK catalogs and replies validate through Ajv2020. Covered endian/quantized/scalar/empty/packed declarations, malformed headers/UTF-8/duplicate JSON keys, unsafe extents and preallocation, sparse 1 GiB input, overlaps/gaps, unknown storage, field/empty/batched selections, source removal, authenticated imported identities, Evidence portability, cancellation and failed-close retention/retry. Long unselected labels and warnings remain below 16 KB in the regression; full parent Evidence preserves source values.
Pre-fix regressions: two real truncation cases fail at 4f004f392; fourteen format cases, two imported/oversized-response MCP cases and two empty-GGUF cases fail at 49b016d1b. Independent official GGUFReader accepts five empty/quantized-empty/scalar declarations in each byte order; the old actual CLI refused them and the corrected CLI agrees on every shape/count/byte length.
Three real public models: all 161 tensors and 40 metadata entries match official gguf 0.19.0 / safetensors 0.8.0 readers, including ranges, shapes, types, element counts and scalar/array previews. Header/full scopes and independent whole-file SHA-256 pass. Final valid results exactly match their corresponding earlier header/full baselines. One verifier comparison initially mixed header/full limitations; the corrected corresponding-mode oracle passes, and the failed attempt is retained. No model was executed.

Pinned samples: stories15M Q4_0 (19,077,344 B, header 727,132 B, SHA-256 66967fbece6d…); stories260K big-endian (1,185,376 B, header 14,152 B, 276d6f9d9050…); MiniLM L3 (69,569,488 B, header 6,096 B, cf1e4e2d420c…). Reference packages and binaries stayed outside the repository.

Completed-task measurements and limits

Caller supplies two tensor names. Both strategies return the same format, scoped identity, selected metadata, declared totals and tensor facts, and export complete Evidence. 62b640a60, Linux / Node 24.18.0, fresh MCP processes; all steps include SDK, catalog/AJV, parsing, projection, serialization, token instrumentation, export and teardown.

Tokenx estimates count arguments and complete replies plus either used-tool input declarations or every input declaration. Wire estimates additionally count catalog output schemas, initialization and other messages. These are not actual model tokens or successful-agent/tool-selection measurements. Whole catalog cost remains visible.

Sample	Delivery	RPCs	Used declarations + calls, tokens	All input declarations + calls, tokens	Whole wire, tokens	Wall s	Family CPU s	Peak family RSS GiB
gguf	complete	2	20,684	264,181	1,072,515	7.224	6.801	0.660
gguf	direct	2	4,861	248,358	1,056,694	7.221	6.801	0.658
safetensors	complete	2	18,877	262,374	1,070,708	7.772	7.475	0.662
safetensors	direct	2	4,272	247,769	1,056,105	7.788	7.542	0.661
small	complete	2	4,675	248,172	1,056,506	7.396	7.083	0.661
small	direct	2	4,543	248,040	1,056,376	6.807	6.771	0.663

Historical measurements at 4f004f392 also covered both execution orders and all three samples; they are not cross-revision speed comparisons. The four-call summary-plus-generic-queries route took 7.13–7.55 s / 8.78–9.33 family CPU s / 0.89–0.93 GiB; direct selection used two calls. Complete versus direct cold timings were similar on real samples; tiny input had fixed-cost variance, so no universal speedup is claimed. Twelve historical GGUF probes per strategy gave 20.49 ms median for full tensor pages and 9.40 ms for selected pages; the first generic-query use took 1.79/1.62 s and is included in those probe sets, not presented as steady warm latency. No source was reopened for these probes.

Two-CPU affinity, 3 GiB V8 heaps and an 8 GiB process-family guard; all six final paired measurements passed first attempt without OOM or guard stops. Family RSS was sampled every 20 ms and can double-count shared pages or miss brief peaks. OS caches/host load, token-instrumentation overhead and engine-only costs were not isolated. There was no prior REA model-reader implementation; these compare equivalent delivery strategies. The small sample is authored, not real-model coverage.

Limits: Linux public workflows were executed; Windows/macOS were not. Storage sizes are derived from pinned ggml layouts or checked against safetensors declarations; runtime compatibility, weight values, model quality and effective/tied parameter counts are unverified. Array previews do not expose a complete vocabulary. Read guards detect observed filesystem changes, not adversarial changes that evade filesystem metadata. Generated catalogs/skills and all models remain ignored build/verification artifacts.

Author readiness

Human owner: @gensokyo-dev

The owner explicitly authorized the work, delegated technical review/validation to Codex and directed these declarations and ready submission. This records that instruction; it does not assert an independent human review.

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.

Before merge

This PR addresses a concrete problem or an agreed enhancement.
Material scope and authority questions are resolved; static format reading requires no execution/protection-recovery scope decision.
One focused outcome, Conventional Commit title and linked issue.
Tests cover changed behavior and meaningful failures; owning contracts, docs and generated metadata are current.
Final diff checked for credentials, unrelated changes and unsupported claims.

_{🔄 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/5603 **Author:** [@gensokyo-dev](https://github.com/gensokyo-dev) **Created:** 10/20/2026 **Status:** ✅ Merged **Merged:** 10/20/2026 **Merged by:** [@gensokyo-dev](https://github.com/gensokyo-dev) **Base:** `main` ← **Head:** `feat/3323-model-artifacts` --- ### 📝 Commits (9) - [`a4d2edf`](https://github.com/morluto/rea/commit/a4d2edfa057a5c1e4d270bac3a69cb0050b3fd04) feat(model): inspect GGUF and safetensors declarations - [`4f004f3`](https://github.com/morluto/rea/commit/4f004f39280a9e445503687c3e7ad3e16bf13a28) chore: merge main for model artifact integration - [`49b016d`](https://github.com/morluto/rea/commit/49b016d1b88404274ceb0044616eb935710fac15) fix(model): classify truncation after admission as an artifact change - [`6108352`](https://github.com/morluto/rea/commit/61083529b2ea08e63c51662b58aa8cddee528c78) chore: refresh main before model format review fixes - [`a15c1af`](https://github.com/morluto/rea/commit/a15c1afea1cad6c8c9ab4851011e5bb0407cfdfc) fix(model): validate format keys and header budget origins - [`8556837`](https://github.com/morluto/rea/commit/85568378c6d86023191d847b218f3ee49cc10e0e) fix(model): validate retained identities and bound selected views - [`b8ae48f`](https://github.com/morluto/rea/commit/b8ae48f89fd998ed9037748ad879b0fd40094085) chore: refresh main before final model integration checks - [`097771f`](https://github.com/morluto/rea/commit/097771f89da010afcc16f7b85c1b389944208bfa) fix(model): accept empty GGUF tensors and bound summary headlines - [`62b640a`](https://github.com/morluto/rea/commit/62b640a60599dbd536965b1737987b0dfc9df8ea) chore: qualify model inspection with current main ### 📊 Changes **60 files changed** (+3835 additions, -3 deletions) <details> <summary>View changed files</summary> 📝 `.agents/skills/reverse-engineer-anything/SKILL.md` (+9 -0) 📝 `.agents/skills/reverse-engineer-anything/references/native-and-artifacts.md` (+10 -0) 📝 `README.md` (+1 -0) 📝 `docs/.vitepress/config.ts` (+1 -0) 📝 `docs/cli.md` (+13 -0) ➕ `docs/model-artifacts.md` (+145 -0) 📝 `docs/readme/README_ar.md` (+1 -0) 📝 `docs/readme/README_de.md` (+1 -0) 📝 `docs/readme/README_el.md` (+1 -0) 📝 `docs/readme/README_es.md` (+1 -0) 📝 `docs/readme/README_fa.md` (+1 -0) 📝 `docs/readme/README_fr.md` (+1 -0) 📝 `docs/readme/README_id.md` (+1 -0) 📝 `docs/readme/README_it.md` (+1 -0) 📝 `docs/readme/README_ja.md` (+1 -0) 📝 `docs/readme/README_ko.md` (+1 -0) 📝 `docs/readme/README_ml.md` (+1 -0) 📝 `docs/readme/README_pl.md` (+1 -0) 📝 `docs/readme/README_pt-BR.md` (+1 -0) 📝 `docs/readme/README_ru.md` (+1 -0) _...and 40 more files_ </details> ### 📄 Description Closes #3323. ## Problem and outcome Bundled model files previously reached an unsupported-binary result. `inspect_model_artifact` / `inspect-model-artifact` now exposes GGUF v2/v3 (both byte orders) and safetensors declarations through one local workflow: typed metadata, tensor identity/shape/type/ranges, and explicitly derived element/storage totals. Default `hash: "header"` reads only the header/directory. It returns a scoped header digest, exact path/extent and bytes read; full-file SHA-256 and the Evidence subject remain null. Explicit `hash: "full"` streams every file byte for full SHA-256 without interpreting weights. Metadata arrays retain typed counts and eight-element previews with omissions recorded; scalar values, integer widths and negative zero survive JSON delivery. Optional `view` returns selected rows plus model context in the initial call. Retained `model-artifact` views support batched names/keys/types/indices, fields, storage-validation states and pagination. Complete Evidence remains accessible. Unknown types keep their identity; declared ranges and unknown storage-size validation stay separate. Historical pages use validated positional indexes and unique names/keys/types, cached with immutable parent facts; they never reopen the file. Only the source-scoped index is mandatory: long labels obey field selection. Bounded view warnings link to complete parent Evidence. ## Boundary and scope The format readers own interpretation; application services own Evidence and delivery; CLI/MCP share both. One admitted descriptor/inspection, bounded prefix reads, a 100,000,000-byte GGUF prefix/safetensors JSON ceiling (excluding its 8-byte length field) and separate 32 MiB retained representation budget constrain work before expansion. File replacement/truncation, cancellation and failed-close ownership use existing filesystem/resource primitives. The EOF follow-up distinguishes concurrent truncation from initially malformed declarations. This is built-in static format inspection within the supported contribution scope. Inspection reads existing local files. CLI compact delivery and explicit Evidence export create caller-selected output files through existing atomic publication. Model execution, target attachment, inference, external-file traversal and runtime network access are outside the operation; no new runtime dependency or installer behavior. ## Executed validation - Final integration `62b640a60`, tree `9a5a4d7a9`, main `5b676ba9f`: **54 reader tests + 5 public model CLI/MCP workflows passed**. `check:ci` **8 tasks + architecture guards across 1,665 files passed**, duplication **3.47%**; generated docs and **5 README tests passed**. No new test files; prior discovery found every test exactly once. - Shared-workflow coverage: **190 tests / 6 files passed** at `85568378c`, following **214 / 9** on the earlier main integration. After newer main, **21 generic MCP cases + 5 model workflows passed** in isolation. One preceding constrained attempt hit two generic 30 s timeouts; deadlines were unchanged. New-main Apple producers passed **31 tests**. Its evaluation helper suite passed 7 cases and failed one 1 s preparation deadline; the helper, test and process/filesystem/artifact dependencies are identical to main, with no model path involved. That single case then passed in isolation without changing deadlines. Failed attempts are retained; these are scoped passes, not a green full-suite claim. - Actual stdio SDK catalogs and replies validate through Ajv2020. Covered endian/quantized/scalar/empty/packed declarations, malformed headers/UTF-8/duplicate JSON keys, unsafe extents and preallocation, sparse 1 GiB input, overlaps/gaps, unknown storage, field/empty/batched selections, source removal, authenticated imported identities, Evidence portability, cancellation and failed-close retention/retry. Long unselected labels and warnings remain below 16 KB in the regression; full parent Evidence preserves source values. - Pre-fix regressions: two real truncation cases fail at `4f004f392`; fourteen format cases, two imported/oversized-response MCP cases and two empty-GGUF cases fail at `49b016d1b`. Independent official GGUFReader accepts five empty/quantized-empty/scalar declarations in each byte order; the old actual CLI refused them and the corrected CLI agrees on every shape/count/byte length. - **Three real public models: all 161 tensors and 40 metadata entries match official `gguf` 0.19.0 / `safetensors` 0.8.0 readers**, including ranges, shapes, types, element counts and scalar/array previews. Header/full scopes and independent whole-file SHA-256 pass. Final valid results exactly match their corresponding earlier header/full baselines. One verifier comparison initially mixed header/full limitations; the corrected corresponding-mode oracle passes, and the failed attempt is retained. No model was executed. Pinned samples: [stories15M Q4_0](https://huggingface.co/ggml-org/models/blob/499bc8821c6b12b4e53c5bffcb21ec206f212d81/tinyllamas/stories15M-q4_0.gguf) (19,077,344 B, header 727,132 B, SHA-256 `66967fbece6d…`); [stories260K big-endian](https://huggingface.co/ggml-org/models/blob/499bc8821c6b12b4e53c5bffcb21ec206f212d81/tinyllamas/stories260K-be.gguf) (1,185,376 B, header 14,152 B, `276d6f9d9050…`); [MiniLM L3](https://huggingface.co/sentence-transformers/paraphrase-MiniLM-L3-v2/blob/4ca70771034acceecb2e72475f72050fcdde4ddc/model.safetensors) (69,569,488 B, header 6,096 B, `cf1e4e2d420c…`). Reference packages and binaries stayed outside the repository. <details> <summary>Completed-task measurements and limits</summary> Caller supplies two tensor names. Both strategies return the same format, scoped identity, selected metadata, declared totals and tensor facts, and export complete Evidence. `62b640a60`, Linux / Node 24.18.0, fresh MCP processes; all steps include SDK, catalog/AJV, parsing, projection, serialization, token instrumentation, export and teardown. Tokenx estimates count arguments and complete replies plus either used-tool input declarations or every input declaration. Wire estimates additionally count catalog output schemas, initialization and other messages. These are not actual model tokens or successful-agent/tool-selection measurements. Whole catalog cost remains visible. |Sample|Delivery|RPCs|Used declarations + calls, tokens|All input declarations + calls, tokens|Whole wire, tokens|Wall s|Family CPU s|Peak family RSS GiB| |---|---|---:|---:|---:|---:|---:|---:|---:| |gguf|complete|2|20,684|264,181|1,072,515|7.224|6.801|0.660| |gguf|direct|2|4,861|248,358|1,056,694|7.221|6.801|0.658| |safetensors|complete|2|18,877|262,374|1,070,708|7.772|7.475|0.662| |safetensors|direct|2|4,272|247,769|1,056,105|7.788|7.542|0.661| |small|complete|2|4,675|248,172|1,056,506|7.396|7.083|0.661| |small|direct|2|4,543|248,040|1,056,376|6.807|6.771|0.663| Historical measurements at `4f004f392` also covered both execution orders and all three samples; they are not cross-revision speed comparisons. The four-call summary-plus-generic-queries route took 7.13–7.55 s / 8.78–9.33 family CPU s / 0.89–0.93 GiB; direct selection used two calls. Complete versus direct cold timings were similar on real samples; tiny input had fixed-cost variance, so no universal speedup is claimed. Twelve historical GGUF probes per strategy gave 20.49 ms median for full tensor pages and 9.40 ms for selected pages; the first generic-query use took 1.79/1.62 s and is included in those probe sets, not presented as steady warm latency. No source was reopened for these probes. Two-CPU affinity, 3 GiB V8 heaps and an 8 GiB process-family guard; all six final paired measurements passed first attempt without OOM or guard stops. Family RSS was sampled every 20 ms and can double-count shared pages or miss brief peaks. OS caches/host load, token-instrumentation overhead and engine-only costs were not isolated. There was no prior REA model-reader implementation; these compare equivalent delivery strategies. The small sample is authored, not real-model coverage. </details> Limits: Linux public workflows were executed; Windows/macOS were not. Storage sizes are derived from pinned ggml layouts or checked against safetensors declarations; runtime compatibility, weight values, model quality and effective/tied parameter counts are unverified. Array previews do not expose a complete vocabulary. Read guards detect observed filesystem changes, not adversarial changes that evade filesystem metadata. Generated catalogs/skills and all models remain ignored build/verification artifacts. ## Author readiness Human owner: @gensokyo-dev The owner explicitly authorized the work, delegated technical review/validation to Codex and directed these declarations and ready submission. This records that instruction; it does not assert an independent human review. - [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. ## Before merge - [x] This PR addresses a concrete problem or an agreed enhancement. - [x] Material scope and authority questions are resolved; static format reading requires no execution/protection-recovery scope decision. - [x] One focused outcome, Conventional Commit title and linked issue. - [x] Tests cover changed behavior and meaningful failures; owning contracts, docs and generated metadata are current. - [x] Final diff checked for credentials, unrelated changes and unsupported claims. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi

2026-11-01 21:44:33 +00:00