[PR #878] [MERGED] refactor(firmware): group layered source and verification #2314

New issue

Closed

opened 2026-10-16 21:17:08 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-16 21:17:08 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/morluto/rea/pull/878
Author: @N0zoM1z0
Created: 10/7/2026
Status: ✅ Merged
Merged: 10/7/2026
Merged by: @N0zoM1z0

Base: main ← Head: refactor/firmware-capability-layout

📝 Commits (1)

ed155e6 refactor(firmware): group layered source and verification

📊 Changes

24 files changed (+66 additions, -43 deletions)

View changed files

📝 docs/capability-migration.md (+17 -0)
📝 docs/testing.md (+6 -0)
📝 package.json (+2 -2)
📝 scripts/fixtures/firmware/generate.mjs (+1 -1)
📝 scripts/fixtures/firmware/generate.py (+0 -0)
📝 scripts/lib/catalog-core.mjs (+1 -1)
📝 scripts/verify/firmware/analysis.mjs (+4 -4)
📝 src/application/firmware/FirmwareAnalysisPort.ts (+4 -4)
📝 src/application/firmware/FirmwareAnalysisService.ts (+7 -7)
📝 src/cli/firmwareCommands.ts (+2 -2)
📝 src/composition/firmware.ts (+1 -1)
📝 src/contracts/contractSnapshot.test.ts (+1 -1)
📝 src/contracts/firmware/firmwareToolContracts.ts (+4 -4)
📝 src/contracts/toolContracts.test.ts (+1 -1)
📝 src/contracts/toolContracts.ts (+1 -1)
📝 src/domain/firmware/firmwareAnalysis.ts (+2 -2)
📝 src/firmware/FirmwareFiles.ts (+1 -1)
📝 src/firmware/FirmwareProvider.ts (+2 -2)
📝 src/firmware/FirmwarePublication.ts (+1 -1)
📝 src/server/createServer.ts (+2 -2)

...and 4 more files

📄 Description

Summary

Group firmware workflows, semantics, contracts and verification within their existing layers. Incremental T6 work for #740.

Problem and expected behavior

Firmware extension and repair should have one clear capability owner and matching proof entrypoints. Its application/domain/contract files and real verifier/fixture producers were scattered among shared roots.

Change and scope

Move four layer files into firmware subdirectories. Group the real verifier under scripts/verify/firmware and the fixture runner/Python producer under scripts/fixtures/firmware. Update typed composition, both caller adapters, producer imports, generator paths, npm entrypoints and owning docs. Keep the actual provider command/report/publication boundary intact.

Contract and boundary impact

Semantic owner and earliest changed stage: firmware source ownership and local/compiled module resolution.
CLI and MCP/tool-catalog contract: unchanged names, schemas, inline Evidence and complete catalog.
Provider, bridge, target-format, or platform compatibility: unchanged producer/report boundaries and existing Linux scope.
Evidence, artifact, provenance, or reconstruction contract: unchanged source copies/digests, report facts and explicit unknowns.
Process execution, authorization, cleanup, or containment impact: unchanged queues, command/resource limits, publication and owned cleanup; no permissions added.
Generated metadata, package, or installation impact: catalog generator reads the new compiled contract path; generated outputs unchanged. Existing npm command names retained.

Evidence and regression coverage

Tests added or updated: affected imports follow moved layers; original assertions preserved.
Base evidence: unchanged normalized implementation/assertion ASTs for all 17 affected TypeScript files; Python fixture producer byte-identical.
User-visible output: same CLI/MCP behavior. Real verifier still identifies the missing caller-selected tool.
Remaining proof gaps: no available supported Unblob/verified Binwalk pair, so the complete real firmware lane was not run locally. Source-fixture production and synthetic producer success retain their narrower proof levels.
Observed, derived, and inferred claims remain distinguishable.
Artifact identity, source provenance, and failed attempts remain preserved.
Unsupported, incomplete, unavailable, or uncertain outcomes remain visible.

Validation performed

npm run check -- --output-logs=errors-only — five static tasks passed on final source/docs.
npm run docs:check — clean build and unchanged generated documents passed. New compiled layer files exist; old paths are absent.
Exact adapter, producer/publication/lifecycle, SDK, canonical-contract, compiled CLI/catalog and normal/reversed presentation cases — 64 tests passed.
npm run verify:test-discovery — all 506 files discovered exactly once.
Actual relocated Python/host-C fixture generation — passed with both outside-repository cwd default and caller-selected directory; independent gzip/hash oracle checked, files below 3KiB, no ELF target executed and owned workspace cleaned.
Relocated real-verifier missing-tool/import preflight — passed.
npm run verify:package — passed: 129 tools, six prompts, installed CLI/MCP Evidence, target/session lifecycle, setup/backup/recovery and update. Startup to tools/list 4137.51ms; sampled MCP peak RSS 474099712 bytes (~452MiB).
git diff --check and final diff review — passed.

Compatibility, safety, and release

Breaking changes or migration steps: none for CLI/MCP users; internal imports and npm script paths updated together.
Real Hopper/Ghidra, browser, or OS coverage: none newly claimed. The optional ext4/Ghidra lanes retain separate prerequisites. Real Binwalk/Unblob remains unverified locally for this batch.
Package or release metadata impact: one distribution, no dependencies or version change.
Security, privacy, process, or containment review: selected fixture roots preserved; generator default stays cwd-relative, verifier default stays repository-relative. Heavy lanes serial under two-CPU/nice/heap bounds, no Windows host writes or tool installations.

Review checklist

One focused outcome and Conventional Commit title.
Roadmap linked.
Existing behavior and meaningful failure/cleanup/publication boundaries covered.
Owning docs, source/generator/npm paths and generated metadata checked.
CLI/MCP output contracts preserved.
Final diff contains no secrets, binaries, unrelated changes or 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/878 **Author:** [@N0zoM1z0](https://github.com/N0zoM1z0) **Created:** 10/7/2026 **Status:** ✅ Merged **Merged:** 10/7/2026 **Merged by:** [@N0zoM1z0](https://github.com/N0zoM1z0) **Base:** `main` ← **Head:** `refactor/firmware-capability-layout` --- ### 📝 Commits (1) - [`ed155e6`](https://github.com/morluto/rea/commit/ed155e6fb41bc1992d1ff2102eba30778304d420) refactor(firmware): group layered source and verification ### 📊 Changes **24 files changed** (+66 additions, -43 deletions) <details> <summary>View changed files</summary> 📝 `docs/capability-migration.md` (+17 -0) 📝 `docs/testing.md` (+6 -0) 📝 `package.json` (+2 -2) 📝 `scripts/fixtures/firmware/generate.mjs` (+1 -1) 📝 `scripts/fixtures/firmware/generate.py` (+0 -0) 📝 `scripts/lib/catalog-core.mjs` (+1 -1) 📝 `scripts/verify/firmware/analysis.mjs` (+4 -4) 📝 `src/application/firmware/FirmwareAnalysisPort.ts` (+4 -4) 📝 `src/application/firmware/FirmwareAnalysisService.ts` (+7 -7) 📝 `src/cli/firmwareCommands.ts` (+2 -2) 📝 `src/composition/firmware.ts` (+1 -1) 📝 `src/contracts/contractSnapshot.test.ts` (+1 -1) 📝 `src/contracts/firmware/firmwareToolContracts.ts` (+4 -4) 📝 `src/contracts/toolContracts.test.ts` (+1 -1) 📝 `src/contracts/toolContracts.ts` (+1 -1) 📝 `src/domain/firmware/firmwareAnalysis.ts` (+2 -2) 📝 `src/firmware/FirmwareFiles.ts` (+1 -1) 📝 `src/firmware/FirmwareProvider.ts` (+2 -2) 📝 `src/firmware/FirmwarePublication.ts` (+1 -1) 📝 `src/server/createServer.ts` (+2 -2) _...and 4 more files_ </details> ### 📄 Description ## Summary Group firmware workflows, semantics, contracts and verification within their existing layers. Incremental T6 work for #740. ## Problem and expected behavior Firmware extension and repair should have one clear capability owner and matching proof entrypoints. Its application/domain/contract files and real verifier/fixture producers were scattered among shared roots. ## Change and scope Move four layer files into firmware subdirectories. Group the real verifier under scripts/verify/firmware and the fixture runner/Python producer under scripts/fixtures/firmware. Update typed composition, both caller adapters, producer imports, generator paths, npm entrypoints and owning docs. Keep the actual provider command/report/publication boundary intact. ## Contract and boundary impact - Semantic owner and earliest changed stage: firmware source ownership and local/compiled module resolution. - CLI and MCP/tool-catalog contract: unchanged names, schemas, inline Evidence and complete catalog. - Provider, bridge, target-format, or platform compatibility: unchanged producer/report boundaries and existing Linux scope. - Evidence, artifact, provenance, or reconstruction contract: unchanged source copies/digests, report facts and explicit unknowns. - Process execution, authorization, cleanup, or containment impact: unchanged queues, command/resource limits, publication and owned cleanup; no permissions added. - Generated metadata, package, or installation impact: catalog generator reads the new compiled contract path; generated outputs unchanged. Existing npm command names retained. ## Evidence and regression coverage - Tests added or updated: affected imports follow moved layers; original assertions preserved. - Base evidence: unchanged normalized implementation/assertion ASTs for all 17 affected TypeScript files; Python fixture producer byte-identical. - User-visible output: same CLI/MCP behavior. Real verifier still identifies the missing caller-selected tool. - Remaining proof gaps: no available supported Unblob/verified Binwalk pair, so the complete real firmware lane was not run locally. Source-fixture production and synthetic producer success retain their narrower proof levels. - [x] Observed, derived, and inferred claims remain distinguishable. - [x] Artifact identity, source provenance, and failed attempts remain preserved. - [x] Unsupported, incomplete, unavailable, or uncertain outcomes remain visible. ## Validation performed - `npm run check -- --output-logs=errors-only` — five static tasks passed on final source/docs. - `npm run docs:check` — clean build and unchanged generated documents passed. New compiled layer files exist; old paths are absent. - Exact adapter, producer/publication/lifecycle, SDK, canonical-contract, compiled CLI/catalog and normal/reversed presentation cases — 64 tests passed. - `npm run verify:test-discovery` — all 506 files discovered exactly once. - Actual relocated Python/host-C fixture generation — passed with both outside-repository cwd default and caller-selected directory; independent gzip/hash oracle checked, files below 3KiB, no ELF target executed and owned workspace cleaned. - Relocated real-verifier missing-tool/import preflight — passed. - `npm run verify:package` — passed: 129 tools, six prompts, installed CLI/MCP Evidence, target/session lifecycle, setup/backup/recovery and update. Startup to tools/list 4137.51ms; sampled MCP peak RSS 474099712 bytes (~452MiB). - `git diff --check` and final diff review — passed. ## Compatibility, safety, and release - Breaking changes or migration steps: none for CLI/MCP users; internal imports and npm script paths updated together. - Real Hopper/Ghidra, browser, or OS coverage: none newly claimed. The optional ext4/Ghidra lanes retain separate prerequisites. Real Binwalk/Unblob remains unverified locally for this batch. - Package or release metadata impact: one distribution, no dependencies or version change. - Security, privacy, process, or containment review: selected fixture roots preserved; generator default stays cwd-relative, verifier default stays repository-relative. Heavy lanes serial under two-CPU/nice/heap bounds, no Windows host writes or tool installations. ## Review checklist - [x] One focused outcome and Conventional Commit title. - [x] Roadmap linked. - [x] Existing behavior and meaningful failure/cleanup/publication boundaries covered. - [x] Owning docs, source/generator/npm paths and generated metadata checked. - [x] CLI/MCP output contracts preserved. - [x] Final diff contains no secrets, binaries, unrelated changes or unsupported claims. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi

2026-10-16 21:17:08 +00:00