[PR #892] [MERGED] refactor(provider): declare deep capabilities from source #2324

New issue

Closed

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

bsakaguchi commented

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

Owner

📋 Pull Request Information

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

Base: main ← Head: refactor/deep-provider-source-declarations

📝 Commits (1)

c9c63f0 refactor(provider): declare deep capabilities from source

📊 Changes

17 files changed (+219 additions, -132 deletions)

View changed files

📝 docs/capability-migration.md (+21 -0)
📝 scripts/lib/catalog-builders.mjs (+24 -3)
📝 scripts/lib/catalog-core.mjs (+2 -2)
📝 scripts/lib/module-boundaries.d.mts (+2 -1)
📝 scripts/lib/module-boundaries.mjs (+12 -0)
📝 src/ghidra/GhidraAnnotations.test.ts (+2 -6)
📝 src/ghidra/GhidraProvider.behavior.test.ts (+4 -4)
📝 src/ghidra/GhidraProvider.ts (+2 -2)
📝 src/ghidra/GhidraProviderCapabilities.ts (+7 -25)
📝 src/hopper/HopperProvider.test.ts (+4 -7)
📝 src/hopper/HopperProvider.ts (+9 -56)
➕ src/hopper/HopperProviderCapabilities.ts (+86 -0)
➕ src/ida/IdaProviderCapabilities.test.ts (+18 -0)
📝 src/ida/IdaProviderCapabilities.ts (+7 -17)
📝 tests/boundary/cli/productCatalog.test.ts (+4 -4)
📝 tests/boundary/providers/hopper/hopperClient.protocol.test.ts (+3 -5)
📝 tests/evaluation/moduleBoundaries.test.ts (+12 -0)

📄 Description

Summary

Deep analysis adapters now own their operation declarations, and the product catalog derives provider coverage from those source facts. This continues T5/T7 in #740.

Problem and expected behavior

Hopper, Ghidra and IDA imported generated MCP contract subsets even though the catalog generator reads their declarations. Adding a canonical tool could consequently change provider coverage through generated presentation data. Coverage should reflect operations implemented by each adapter.

Change and scope

Introduce a typed, frozen Hopper operation inventory, reuse Ghidra's existing inventory/function operations, and freeze IDA's existing read-only inventory. Existing capability builders retain their effects, limitations and session differences. The catalog generator joins declared operation names to canonical contracts and reports unknown names with the provider identity. A resolved-import guard rejects provider dependencies on the generated MCP catalog.

Contract and boundary impact

Semantic owner and earliest changed stage: provider capability declarations and catalog derivation.
CLI and MCP/tool-catalog contract: identical generated contracts, descriptions, schemas and provider coverage.
Provider, bridge, target-format, or platform compatibility: operation order, Windows Ghidra restrictions and IDA attached/headless/stdio differences preserved.
Evidence, artifact, provenance, or reconstruction contract: none.
Process execution, authorization, cleanup, or containment impact: none; declarations remain passive metadata.
Generated metadata (docs/product-catalog.json), package, or installation impact: generated artifacts are unchanged; generator reads capability modules directly.

Evidence and regression coverage

Tests added or updated: operation-name consumers, eight resolved-boundary probes, and an IDA regression against attempted mutation of declarations.
Base reproduction or other evidence: the new guard rejects the three actual generated-catalog imports on the base revision. Compiled capability JSON matches the original Hopper/Ghidra and all four IDA mode/stdio combinations exactly.
User-visible CLI/MCP output: installed package advertises 130 tools and six prompts; schemas and generated metadata are unchanged.
Remaining proof gaps: real Hopper, IDA and Windows engines were not exercised locally for this increment. The executed Linux Ghidra workflow is narrower than the complete canonical conformance lane.

For evidence-bearing changes:

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 — all five static gates passed.
npm run docs:check — fresh build and all generated documents passed without generated changes.
Exact focused Vitest selection — 162 tests in 18 files passed, including provider behavior, protocol boundaries, product catalog and normal/reordered MCP contract presentation.
Test discovery — all 518 source test files discovered once.
Compiled declaration import-closure inspection — no generated MCP catalog or full canonical inventory is loaded by the capability modules.
Isolated real Linux Ghidra 12.1.4 workflow — CLI inspect and MCP open/list/decompile/read-bytes/address-mapping/close passed; original byte oracle, unchanged digest, preserved caller entries and complete owned-process cleanup verified.
npm run verify:package — installed CLI/MCP, setup, configuration backups/recovery, evidence, lifecycle and update checks passed. Startup to tools/list was 2556.44 ms; sampled MCP peak RSS was 416800768 bytes.

Compatibility, safety, and release

Breaking changes or migration steps: internal *_PROVIDER_TOOL_CONTRACTS exports are replaced by *_OPERATIONS; all repository consumers migrated. Published CLI/MCP contracts are unchanged.
Real Hopper/Ghidra, browser, or OS coverage: bounded Linux Ghidra workflow executed; other real engines were not exercised locally for this increment.
Package or release metadata impact: no dependency, installation or version changes.
Security, privacy, process, or containment review: reviewed passive declarations, immutability and resolved ownership. Heavy verification ran serially with two-CPU affinity and heap limits; real Ghidra's sampled family peak was about 1.05 GiB. No Windows disk writes or engine installation.

Review checklist

The PR has one focused outcome and the title follows type(scope): outcome.
Related issue is linked, or the reason for not linking one is stated above.
Tests cover changed observable behavior and meaningful failure paths.
Owning docs, contracts, and generated metadata are updated where needed.
User-visible CLI/MCP changes include representative output.
I checked the final diff for secrets, unrelated cleanup, 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/892 **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/deep-provider-source-declarations` --- ### 📝 Commits (1) - [`c9c63f0`](https://github.com/morluto/rea/commit/c9c63f0b380c4a9cadab7c615a0db4d92e3b185a) refactor(provider): declare deep capabilities from source ### 📊 Changes **17 files changed** (+219 additions, -132 deletions) <details> <summary>View changed files</summary> 📝 `docs/capability-migration.md` (+21 -0) 📝 `scripts/lib/catalog-builders.mjs` (+24 -3) 📝 `scripts/lib/catalog-core.mjs` (+2 -2) 📝 `scripts/lib/module-boundaries.d.mts` (+2 -1) 📝 `scripts/lib/module-boundaries.mjs` (+12 -0) 📝 `src/ghidra/GhidraAnnotations.test.ts` (+2 -6) 📝 `src/ghidra/GhidraProvider.behavior.test.ts` (+4 -4) 📝 `src/ghidra/GhidraProvider.ts` (+2 -2) 📝 `src/ghidra/GhidraProviderCapabilities.ts` (+7 -25) 📝 `src/hopper/HopperProvider.test.ts` (+4 -7) 📝 `src/hopper/HopperProvider.ts` (+9 -56) ➕ `src/hopper/HopperProviderCapabilities.ts` (+86 -0) ➕ `src/ida/IdaProviderCapabilities.test.ts` (+18 -0) 📝 `src/ida/IdaProviderCapabilities.ts` (+7 -17) 📝 `tests/boundary/cli/productCatalog.test.ts` (+4 -4) 📝 `tests/boundary/providers/hopper/hopperClient.protocol.test.ts` (+3 -5) 📝 `tests/evaluation/moduleBoundaries.test.ts` (+12 -0) </details> ### 📄 Description ## Summary Deep analysis adapters now own their operation declarations, and the product catalog derives provider coverage from those source facts. This continues T5/T7 in #740. ## Problem and expected behavior Hopper, Ghidra and IDA imported generated MCP contract subsets even though the catalog generator reads their declarations. Adding a canonical tool could consequently change provider coverage through generated presentation data. Coverage should reflect operations implemented by each adapter. ## Change and scope Introduce a typed, frozen Hopper operation inventory, reuse Ghidra's existing inventory/function operations, and freeze IDA's existing read-only inventory. Existing capability builders retain their effects, limitations and session differences. The catalog generator joins declared operation names to canonical contracts and reports unknown names with the provider identity. A resolved-import guard rejects provider dependencies on the generated MCP catalog. ## Contract and boundary impact - Semantic owner and earliest changed stage: provider capability declarations and catalog derivation. - CLI and MCP/tool-catalog contract: identical generated contracts, descriptions, schemas and provider coverage. - Provider, bridge, target-format, or platform compatibility: operation order, Windows Ghidra restrictions and IDA attached/headless/stdio differences preserved. - Evidence, artifact, provenance, or reconstruction contract: none. - Process execution, authorization, cleanup, or containment impact: none; declarations remain passive metadata. - Generated metadata (`docs/product-catalog.json`), package, or installation impact: generated artifacts are unchanged; generator reads capability modules directly. ## Evidence and regression coverage - Tests added or updated: operation-name consumers, eight resolved-boundary probes, and an IDA regression against attempted mutation of declarations. - Base reproduction or other evidence: the new guard rejects the three actual generated-catalog imports on the base revision. Compiled capability JSON matches the original Hopper/Ghidra and all four IDA mode/stdio combinations exactly. - User-visible CLI/MCP output: installed package advertises 130 tools and six prompts; schemas and generated metadata are unchanged. - Remaining proof gaps: real Hopper, IDA and Windows engines were not exercised locally for this increment. The executed Linux Ghidra workflow is narrower than the complete canonical conformance lane. For evidence-bearing changes: - [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` — all five static gates passed. - `npm run docs:check` — fresh build and all generated documents passed without generated changes. - Exact focused Vitest selection — 162 tests in 18 files passed, including provider behavior, protocol boundaries, product catalog and normal/reordered MCP contract presentation. - Test discovery — all 518 source test files discovered once. - Compiled declaration import-closure inspection — no generated MCP catalog or full canonical inventory is loaded by the capability modules. - Isolated real Linux Ghidra 12.1.4 workflow — CLI inspect and MCP open/list/decompile/read-bytes/address-mapping/close passed; original byte oracle, unchanged digest, preserved caller entries and complete owned-process cleanup verified. - `npm run verify:package` — installed CLI/MCP, setup, configuration backups/recovery, evidence, lifecycle and update checks passed. Startup to tools/list was 2556.44 ms; sampled MCP peak RSS was 416800768 bytes. ## Compatibility, safety, and release - Breaking changes or migration steps: internal `*_PROVIDER_TOOL_CONTRACTS` exports are replaced by `*_OPERATIONS`; all repository consumers migrated. Published CLI/MCP contracts are unchanged. - Real Hopper/Ghidra, browser, or OS coverage: bounded Linux Ghidra workflow executed; other real engines were not exercised locally for this increment. - Package or release metadata impact: no dependency, installation or version changes. - Security, privacy, process, or containment review: reviewed passive declarations, immutability and resolved ownership. Heavy verification ran serially with two-CPU affinity and heap limits; real Ghidra's sampled family peak was about 1.05 GiB. No Windows disk writes or engine installation. ## Review checklist - [x] The PR has one focused outcome and the title follows `type(scope): outcome`. - [x] Related issue is linked, or the reason for not linking one is stated above. - [x] Tests cover changed observable behavior and meaningful failure paths. - [x] Owning docs, contracts, and generated metadata are updated where needed. - [x] User-visible CLI/MCP changes include representative output. - [x] I checked the final diff for secrets, unrelated cleanup, and 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:16 +00:00