[PR #239] [MERGED] docs(architecture): define provider selection and analysis profiles #1890

New issue

Closed

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

bsakaguchi commented

2026-10-16 21:12:14 +00:00

Owner

📋 Pull Request Information

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

Base: main ← Head: agent/define-provider-selection-analysis-profiles

📝 Commits (1)

f9f2fbe docs(architecture): define provider selection and analysis profiles

📊 Changes

4 files changed (+563 additions, -1 deletions)

View changed files

📝 README.md (+1 -1)
➕ docs/adr/0001-provider-selection-and-analysis-profiles.md (+548 -0)
➕ docs/adr/README.md (+9 -0)
📝 docs/provider-evaluation.md (+5 -0)

📄 Description

Problem and product rationale

REA currently composes providers by requiring one provider per operation. Hopper and Ghidra will intentionally overlap on the deep static-analysis family, while BinaryTarget and snapshot v1 still carry Hopper-specific loader state. Implementing a second provider without a prior decision would make array order, startup races, or ad hoc fallback into undeclared product policy.

This PR accepts the architecture decision that later provider-foundation and Ghidra PRs must follow. It does not claim that the new runtime behavior or Ghidra support is shipped.

Contract and behavior decisions

Keeps CompositeProvider strict and limited to disjoint operation families.
Introduces the planned AnalysisProviderRegistry boundary for overlapping Hopper and Ghidra candidates.
Defines request/CLI, REA_ANALYSIS_PROVIDER, and deterministic auto precedence.
Binds one deep provider and one canonical analysis profile to a target until explicit close or switch.
Forbids per-operation borrowing, startup races, and mid-session fallback.
Keeps provider-specific open options inside adapters and removes them from the planned provider-neutral target model.
Defines a concrete, RFC 8785-digested analysis profile envelope.
Defines snapshot v2 provider/profile identity and an explicit non-migration path for unsafe snapshot v1 cache replay.
Preserves legacy Evidence v2 while requiring an additive analysis-profile commitment on new deep observations.
Defines target-free candidate availability, target-support states, rejection codes, binding status, and typed failure ownership.
Records exact operation-family ownership, compatibility behavior, sixteen required scenarios, rejected alternatives, and implementation order.

Compatibility and migration

Stable CLI and MCP tool names remain unchanged. With only Hopper usable and no selector, auto preserves current behavior. Installing a second usable deep provider requires an explicit policy instead of silently changing results. Existing flat status fields and the Hopper-only loaderArgs output remain deprecated 1.x compatibility projections while the future analysis profile becomes authoritative.

Snapshot v1 is deliberately incompatible with profile-exact cache replay because it cannot prove engine version or analyzer semantics. Its embedded Evidence may still be imported explicitly. Existing Evidence v2 remains valid; a missing profile is truthful legacy-unknown provenance.

There is no runtime contract, schema, tool inventory, setup, or provider execution change in this PR.

Verification

npm run check — 106 test files and 724 tests passed; coverage gates passed.
npm run docs:check
Prettier formatting and git diff --check passed.
All relative links in the four changed documentation files were resolved locally.
A decision-completeness audit verified the registry, selectors, binding, no-fallback rule, provider options, profile, snapshot v2, Evidence v2, target-free status, compatibility, and scenario sections.

npm run verify:package was not run locally because this PR changes documentation only and makes no package or runtime claim. The normal GitHub workflow remains authoritative for its configured package jobs.

Real provider verification

Real Hopper: not run; no Hopper behavior changes or new Hopper claims.
Real Ghidra: not run; Ghidra is not implemented by this PR.
Real Browser: not run locally; no browser behavior changes or new browser 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/239 **Author:** [@N0zoM1z0](https://github.com/N0zoM1z0) **Created:** 7/15/2026 **Status:** ✅ Merged **Merged:** 7/15/2026 **Merged by:** [@N0zoM1z0](https://github.com/N0zoM1z0) **Base:** `main` ← **Head:** `agent/define-provider-selection-analysis-profiles` --- ### 📝 Commits (1) - [`f9f2fbe`](https://github.com/morluto/rea/commit/f9f2fbe2fc04bd202d9fd580fc54c30529809fc0) docs(architecture): define provider selection and analysis profiles ### 📊 Changes **4 files changed** (+563 additions, -1 deletions) <details> <summary>View changed files</summary> 📝 `README.md` (+1 -1) ➕ `docs/adr/0001-provider-selection-and-analysis-profiles.md` (+548 -0) ➕ `docs/adr/README.md` (+9 -0) 📝 `docs/provider-evaluation.md` (+5 -0) </details> ### 📄 Description ## Problem and product rationale REA currently composes providers by requiring one provider per operation. Hopper and Ghidra will intentionally overlap on the deep static-analysis family, while `BinaryTarget` and snapshot v1 still carry Hopper-specific loader state. Implementing a second provider without a prior decision would make array order, startup races, or ad hoc fallback into undeclared product policy. This PR accepts the architecture decision that later provider-foundation and Ghidra PRs must follow. It does not claim that the new runtime behavior or Ghidra support is shipped. ## Contract and behavior decisions - Keeps `CompositeProvider` strict and limited to disjoint operation families. - Introduces the planned `AnalysisProviderRegistry` boundary for overlapping Hopper and Ghidra candidates. - Defines request/CLI, `REA_ANALYSIS_PROVIDER`, and deterministic `auto` precedence. - Binds one deep provider and one canonical analysis profile to a target until explicit close or switch. - Forbids per-operation borrowing, startup races, and mid-session fallback. - Keeps provider-specific open options inside adapters and removes them from the planned provider-neutral target model. - Defines a concrete, RFC 8785-digested analysis profile envelope. - Defines snapshot v2 provider/profile identity and an explicit non-migration path for unsafe snapshot v1 cache replay. - Preserves legacy Evidence v2 while requiring an additive analysis-profile commitment on new deep observations. - Defines target-free candidate availability, target-support states, rejection codes, binding status, and typed failure ownership. - Records exact operation-family ownership, compatibility behavior, sixteen required scenarios, rejected alternatives, and implementation order. ## Compatibility and migration Stable CLI and MCP tool names remain unchanged. With only Hopper usable and no selector, `auto` preserves current behavior. Installing a second usable deep provider requires an explicit policy instead of silently changing results. Existing flat status fields and the Hopper-only `loaderArgs` output remain deprecated 1.x compatibility projections while the future analysis profile becomes authoritative. Snapshot v1 is deliberately incompatible with profile-exact cache replay because it cannot prove engine version or analyzer semantics. Its embedded Evidence may still be imported explicitly. Existing Evidence v2 remains valid; a missing profile is truthful legacy-unknown provenance. There is no runtime contract, schema, tool inventory, setup, or provider execution change in this PR. ## Verification - `npm run check` — 106 test files and 724 tests passed; coverage gates passed. - `npm run docs:check` - Prettier formatting and `git diff --check` passed. - All relative links in the four changed documentation files were resolved locally. - A decision-completeness audit verified the registry, selectors, binding, no-fallback rule, provider options, profile, snapshot v2, Evidence v2, target-free status, compatibility, and scenario sections. `npm run verify:package` was not run locally because this PR changes documentation only and makes no package or runtime claim. The normal GitHub workflow remains authoritative for its configured package jobs. ## Real provider verification - Real Hopper: not run; no Hopper behavior changes or new Hopper claims. - Real Ghidra: not run; Ghidra is not implemented by this PR. - Real Browser: not run locally; no browser behavior changes or new browser 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:12:14 +00:00