[PR #1892] [CLOSED] fix(firmware): make partial extraction recovery explicit in extraction_gaps #4884

New issue

Closed

opened 2026-10-31 00:56:24 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-31 00:56:24 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/morluto/rea/pull/1892
Author: @BaaRai
Created: 10/11/2026
Status: ❌ Closed

Base: main ← Head: fix/firmware-extraction-gaps

📝 Commits (10+)

76b56eb fix(firmware): make partial extraction recovery explicit in extraction_gaps
8153080 fix(firmware): bind chunk-nested dependency reports to their owning chunk
8c47a8c test(firmware): assert extraction_gaps in the real Binwalk/Unblob lane
e4e720a fix(firmware): cover extractor failures and index dependency gap lookup
5575322 fix(firmware): keep task-wide failures honest in extraction_gaps
d73f6dd test(firmware): keep the standard fixture file off the reentry directory
3fdcdf4 test(firmware): mark the reentry parent task as a directory
c7d7dec test(firmware): honor the depth argument in the reentry fixture
7dba555 fix(firmware): keep region rows and depth re-rooting honest
5f96327 test(firmware): cover self-file re-rooting and the orphan ceiling

📊 Changes

10 files changed (+1638 additions, -23 deletions)

View changed files

📝 docs/firmware-analysis.md (+23 -0)
📝 scripts/verify/firmware/analysis.mjs (+34 -1)
📝 src/contracts/firmware/firmwareToolContracts.ts (+1 -1)
📝 src/domain/firmware/firmwareAnalysis.ts (+31 -0)
📝 src/firmware/FirmwareProvider.ts (+2 -0)
📝 src/firmware/FirmwarePublication.ts (+307 -0)
📝 src/firmware/FirmwareReports.test.ts (+489 -0)
📝 src/firmware/FirmwareReports.ts (+173 -6)
📝 tests/boundary/firmware/firmwareIntegration.test.ts (+304 -0)
📝 tests/fixtures/firmware/producer.mjs (+274 -15)

📄 Description

Summary

Fixes #1853.

extract_firmware already retained partial coverage, raw diagnostics and chunk ranges when an extractor dependency was missing, but nothing explained which dependency was missing, which region stayed carved or unextracted, or what a caller could do next with already configured capabilities.

Problem and expected behavior

A partial result carried the provider's raw JSON diagnostics and chunk records, so the missing dependency and the affected stage had to be reconstructed by hand from free-form rows. The issue asks for an explicit account of the missing dependency and extraction stage, preserved region identity, a supported continuation using already configured capabilities where one exists, and coverage that never implies a corrupt target or an empty filesystem.

Change and scope

The normalized report derives the exact dependency names from the producer's ExtractorDependencyNotFoundReport rows, wherever they appear (standalone reports, ChunkReport and MultiFileReport extraction reports). Rows without dependency names stay in diagnostics and derive nothing.
Publication assembles typed extraction_gaps rows: missing-extractor-dependency, unknown-chunk-handler, encrypted-chunk, depth-limited and unpublished-entry. Each row keeps the chunk's provider identity, byte range and original-file range when the chunk belongs to the selected input; rows sort deterministically.
Every row carries a static continuation that uses already configured capabilities where one exists (higher max_depth, inspect_firmware_regions hypotheses, rerun after adding the named dependency yourself) and states the boundary where none does (encrypted bytes). The missing-dependency continuation states that REA installs nothing.
A retained limitation states that a listed gap does not mean the target is corrupt or that a retained region is empty.

No producer invocation, admission, or publication behavior changes; coverage stays partial under exactly the same conditions as before.

Verification

Locally verified; fork PRs currently receive no CI check runs in this repository (maintainer approval gate), so results below are from this machine:

vitest src/firmware/FirmwareReports.test.ts (new derivation cases: chunk- and multi-file-nested dependency reports, nameless reports derive nothing), tests/boundary/firmware/ (all three partial modes assert their exact extraction_gaps rows), tests/boundary/mcp/firmwareMcp.test.ts: all pass on Linux.
tsc --noEmit clean; oxlint 0 errors on the touched files.
The dependency fixture now reports the gap bound to the exact chunk (gzip handler, its byte range and original-file range) with dependencies: ["sasquatch"] taken from the producer report, not inferred.

_{🔄 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/1892 **Author:** [@BaaRai](https://github.com/BaaRai) **Created:** 10/11/2026 **Status:** ❌ Closed **Base:** `main` ← **Head:** `fix/firmware-extraction-gaps` --- ### 📝 Commits (10+) - [`76b56eb`](https://github.com/morluto/rea/commit/76b56ebd2de54599962a8c209902d862e3d4cd51) fix(firmware): make partial extraction recovery explicit in extraction_gaps - [`8153080`](https://github.com/morluto/rea/commit/8153080c20530a036d7974cf60d8ee22a3aae135) fix(firmware): bind chunk-nested dependency reports to their owning chunk - [`8c47a8c`](https://github.com/morluto/rea/commit/8c47a8c16082addce6517164d51e9f007a48f5d2) test(firmware): assert extraction_gaps in the real Binwalk/Unblob lane - [`e4e720a`](https://github.com/morluto/rea/commit/e4e720adad0e9839b46b3b5328bcd7f88b8b9429) fix(firmware): cover extractor failures and index dependency gap lookup - [`5575322`](https://github.com/morluto/rea/commit/5575322b25e4e188860fb8730250529dbf7f0468) fix(firmware): keep task-wide failures honest in extraction_gaps - [`d73f6dd`](https://github.com/morluto/rea/commit/d73f6dd9bdbf960b64006870d4fbce0ee7a40a87) test(firmware): keep the standard fixture file off the reentry directory - [`3fdcdf4`](https://github.com/morluto/rea/commit/3fdcdf4c77c63d0b059a3cae461c59090deb0ffd) test(firmware): mark the reentry parent task as a directory - [`c7d7dec`](https://github.com/morluto/rea/commit/c7d7dec0a295bddf24e87a0505ad1e1b20b0e382) test(firmware): honor the depth argument in the reentry fixture - [`7dba555`](https://github.com/morluto/rea/commit/7dba5556d5477562a1ee0b5c9f7c47d5e00a9845) fix(firmware): keep region rows and depth re-rooting honest - [`5f96327`](https://github.com/morluto/rea/commit/5f9632739e59c358b3980c65209a0fd638029790) test(firmware): cover self-file re-rooting and the orphan ceiling ### 📊 Changes **10 files changed** (+1638 additions, -23 deletions) <details> <summary>View changed files</summary> 📝 `docs/firmware-analysis.md` (+23 -0) 📝 `scripts/verify/firmware/analysis.mjs` (+34 -1) 📝 `src/contracts/firmware/firmwareToolContracts.ts` (+1 -1) 📝 `src/domain/firmware/firmwareAnalysis.ts` (+31 -0) 📝 `src/firmware/FirmwareProvider.ts` (+2 -0) 📝 `src/firmware/FirmwarePublication.ts` (+307 -0) 📝 `src/firmware/FirmwareReports.test.ts` (+489 -0) 📝 `src/firmware/FirmwareReports.ts` (+173 -6) 📝 `tests/boundary/firmware/firmwareIntegration.test.ts` (+304 -0) 📝 `tests/fixtures/firmware/producer.mjs` (+274 -15) </details> ### 📄 Description ## Summary Fixes #1853. `extract_firmware` already retained partial coverage, raw diagnostics and chunk ranges when an extractor dependency was missing, but nothing explained which dependency was missing, which region stayed carved or unextracted, or what a caller could do next with already configured capabilities. ## Problem and expected behavior A partial result carried the provider's raw JSON diagnostics and chunk records, so the missing dependency and the affected stage had to be reconstructed by hand from free-form rows. The issue asks for an explicit account of the missing dependency and extraction stage, preserved region identity, a supported continuation using already configured capabilities where one exists, and coverage that never implies a corrupt target or an empty filesystem. ## Change and scope - The normalized report derives the exact dependency names from the producer's `ExtractorDependencyNotFoundReport` rows, wherever they appear (standalone reports, `ChunkReport` and `MultiFileReport` extraction reports). Rows without dependency names stay in diagnostics and derive nothing. - Publication assembles typed `extraction_gaps` rows: `missing-extractor-dependency`, `unknown-chunk-handler`, `encrypted-chunk`, `depth-limited` and `unpublished-entry`. Each row keeps the chunk's provider identity, byte range and original-file range when the chunk belongs to the selected input; rows sort deterministically. - Every row carries a static continuation that uses already configured capabilities where one exists (higher `max_depth`, `inspect_firmware_regions` hypotheses, rerun after adding the named dependency yourself) and states the boundary where none does (encrypted bytes). The missing-dependency continuation states that REA installs nothing. - A retained limitation states that a listed gap does not mean the target is corrupt or that a retained region is empty. No producer invocation, admission, or publication behavior changes; coverage stays `partial` under exactly the same conditions as before. ## Verification Locally verified; fork PRs currently receive no CI check runs in this repository (maintainer approval gate), so results below are from this machine: - `vitest` `src/firmware/FirmwareReports.test.ts` (new derivation cases: chunk- and multi-file-nested dependency reports, nameless reports derive nothing), `tests/boundary/firmware/` (all three partial modes assert their exact `extraction_gaps` rows), `tests/boundary/mcp/firmwareMcp.test.ts`: all pass on Linux. - `tsc --noEmit` clean; `oxlint` 0 errors on the touched files. - The dependency fixture now reports the gap bound to the exact chunk (`gzip` handler, its byte range and original-file range) with `dependencies: ["sasquatch"]` taken from the producer report, not inferred. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi

2026-10-31 00:56:24 +00:00