mirror/rea
1
0
Fork 0
mirror of https://github.com/morluto/rea synced 2026-10-26 06:16:17 -04:00
Code Issues Packages Projects Releases Wiki Activity

refactor: remove cross-version investigation workflow

Browse Source
This commit is contained in:
morluto
2026-09-29 08:06:43 +08:00
parent 0d96275b68
commit 81996df7a5
42 changed files with 66 additions and 3750 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/adr/0001-provider-selection-and-analysis-profiles.md
+7 -8
View File
@@ -328,11 +328,11 @@ entries from the previous binding. Auxiliary operations are cacheable only if
their provider defines an equivalent explicit profile commitment; otherwise
they remain Evidence but not snapshot entries.
Snapshot v1 is not silently upgraded. Its `loader_args` cannot prove which
engine version, defaults, or analyzer settings produced the entries. Importing
v1 returns a typed incompatibility with a recapture instruction. Its embedded
Evidence bundle may still be imported separately through the existing explicit
Evidence import flow; it is never promoted into a v2 analysis cache.
Snapshot v1 cannot be parsed as the current snapshot format. Its `loader_args`
cannot prove which engine version, defaults, or analyzer settings produced the
entries, so snapshots must be recaptured before they can be used as a cache.
An embedded Evidence bundle can still be imported separately through the
Evidence import flow; it is never promoted into an analysis cache.
### 8. Add profile commitments to new deep Evidence without rejecting legacy Evidence v2
@@ -457,7 +457,7 @@ snapshot's provider.
| `open_binary` and CLI structured `loaderArgs` output | Retained as a deprecated Hopper-only compatibility projection for 1.x; the analysis profile is authoritative |
| `BinaryTarget.loaderArgs` | Removed; Hopper derives them inside its adapter and commits normalized semantics in the profile |
| Legacy `.hop` input | Classified generically as an analysis database and accepted only by Hopper |
| Snapshot v1 | Rejected for cache replay with explicit recapture guidance; embedded Evidence may be imported separately |
| Snapshot v1 | Not accepted as the current snapshot format; recapture before cache replay |
| Existing Evidence v2 without a profile | Accepted unchanged; profile compatibility is unknown |
| New deep-analysis Evidence v2 | Must include `analysis_profile`; its semantic ID commits the field |
| Existing status fields | Retained for 1.x with additive binding and candidate fields |
@@ -483,7 +483,6 @@ with a separately documented major contract change.
| Same target is reopened without a selector | Existing binding remains unchanged |
| Same bytes are opened with a different profile | Real provider switch and a separate snapshot partition |
| Snapshot provider or profile differs from the binding | Typed `EvidenceIntegrityError` with `profile_mismatch`; nothing is imported |
| Snapshot v1 is supplied | Typed incompatibility with recapture or explicit Evidence-import guidance |
| Artifact-only target has no deep candidate | Target opens unbound; disjoint artifact capabilities remain usable |
| Environment prefers Ghidra for an artifact-only target | Deep selection is `not_applicable`; auxiliary operations remain usable |
| Concrete deep provider is requested for artifact-only data | Typed `target_unsupported`; the request is not silently ignored |
@@ -502,7 +501,7 @@ Positive consequences:
Costs and tradeoffs:
- Multi-provider hosts must choose when more than one candidate is usable.
- Snapshot v1 cannot safely serve as a cache after this migration.
- Snapshots must be recaptured when their provider or profile binding changes.
- Providers must expose deterministic availability, support, version, and
profile resolution before they can be admitted.
- Status and error contracts gain additive structured metadata.
docs/investigation-workspaces.md
-120
View File
@@ -1,120 +0,0 @@
# Persistent investigation workspaces
REA can run a deterministic artifact investigation across two versions and
persist its Evidence beyond a CLI process or MCP session. The CLI and MCP use
the same application workflow.
## CLI
First allow the directory that will own the workspace, then explicitly approve
the write:
```bash
export REA_EVIDENCE_ROOTS_JSON='["/absolute/path/to/evidence"]'
rea investigate-versions \
/absolute/path/to/version-1 \
/absolute/path/to/version-2 \
/absolute/path/to/evidence/releases.json \
--workspace-name releases \
--yes
```
The two versions may be regular artifacts or directories supported by the
artifact graph provider. Workspace files remain restricted by
`REA_EVIDENCE_ROOTS_JSON`; input paths are used directly by the local process.
Use `--expected-revision N` when an external coordinator needs an explicit
compare-and-swap guard. Traversal, byte, page, and comparison controls are
available as CLI options.
After a completed run returns its stable run ID, `--replay-run-id RUN_ID`
selects that exact result without reading or rescanning either version input.
The workspace still requires read authority. REA rejects a selector that is
missing, incomplete, or inconsistent with the requested paths and controls.
## MCP
`find_changed_behavior` retains its existing aggregation mode. Its additive
`investigation_run` mode starts or resumes the same persistent workflow:
```json
{
"investigation_run": {
"approved": true,
"workspace_path": "/absolute/path/to/evidence/releases.json",
"workspace_name": "releases",
"left_path": "/absolute/path/to/version-1",
"right_path": "/absolute/path/to/version-2",
"options": {
"max_entries": 10000,
"max_total_bytes": 1073741824,
"max_entry_bytes": 268435456,
"max_compression_ratio": 1000,
"max_depth": 20,
"max_path_bytes": 4096,
"page_size": 500,
"change_limit": 500
}
}
}
```
Exactly one of `comparisons` or `investigation_run` is accepted. The MCP tool
inventory remains unchanged.
## Checkpoints and reuse
One run has four ordered stages:
1. Inventory the left version.
2. Inventory the right version.
3. Compare the complete artifact Evidence page sets.
4. Derive the changed-behavior report.
The inventory checkpoint is written first, followed by the comparison and final
report checkpoints. A process interrupted after a checkpoint can resume from
the last complete stage. A completed run is reused when both graph commitments
and every bounded option are identical.
By default, REA rescans the version inputs so changed content creates a new
run. For an explicit cache-only replay, add the returned `run_id` as
`investigation_run.replay_run_id`. REA validates the workspace revision and
name, the complete run, its exact paths and controls, and every linked Evidence
record before it skips input-read authorization.
The run ID is a SHA-256 commitment to both root and graph digests plus the
normalized options. Local paths and timestamps do not affect that identity.
Changing either artifact or a budget creates a new run in the same workspace;
it does not overwrite the earlier run.
## Integrity and concurrency
A workspace contains a canonical Evidence v2 bundle plus run manifests. Each
workspace revision has a deterministic digest and points to the prior revision
digest. Parsing verifies:
- the workspace, run, Evidence, graph, and revision identities;
- canonical ordering and unique run IDs;
- every run-to-Evidence reference;
- stage and completion-state consistency.
Writes are canonical JSON, atomic, fsynced, and mode `0600`. REA rejects
workspace paths outside `REA_EVIDENCE_ROOTS_JSON`, symlink destinations,
oversized or deeply nested JSON, stale expected revisions, and concurrent lock
holders. Lock or CAS conflicts fail without mutating the workspace; callers may
retry the same idempotent request.
## Truth boundary
The automatic run currently observes shipped artifact structure. Artifact
changes are static behavior candidates, not runtime observations or causal
claims. Without controlled process comparison Evidence, `behavior_status`
remains `unknown` even when static differences are present. Provider
limitations, incomplete comparison pages, and unsupported container expansion
remain explicit in the final Evidence.
Automatic Hopper function matching, process replay, protocols, UI comparison,
and reconstruction verification are not yet stages of this run. Existing
manual comparison Evidence can still be aggregated through the original
`find_changed_behavior` mode.
docs/mcp-contracts.md
+4 -9
View File
@@ -131,12 +131,7 @@ all three conditions:
2. `integrity_policy=record-and-continue`;
3. explicit per-call `integrity_continue_approved=true`.
Contradictory bytes are quarantined from nested expansion, recorded with declared
and observed hashes, trust, provenance, path, and unpacked state, and bounded by
`max_integrity_mismatches`. Verified siblings continue. Comparisons classify the
result as a contradiction and reconstruction cannot treat it as unchanged.
`investigate-versions` accepts the same policy through
`--integrity-policy record-and-continue --integrity-continue-approved` and
`--max-integrity-mismatches`. Its Evidence pages and CAS-linked workspace retain
contradictions, so a completed run can resume without rescanning or weakening
trust labels.
Contradictory bytes are quarantined from nested expansion and recorded with
declared and observed hashes, trust, provenance, path, and unpacked state.
Verified siblings continue. Comparisons classify the result as a contradiction
and reconstruction cannot treat it as unchanged.
docs/product-catalog.json
+4 -5
View File
@@ -429,7 +429,7 @@
}
],
"cli": {
"primary_count": 68,
"primary_count": 67,
"commands": [
"analyze",
"analyze-javascript-application",
@@ -474,7 +474,6 @@
"inspect-web-page",
"instructions",
"inventory-artifact",
"investigate-versions",
"list-architectures",
"list-browser-targets",
"list-electron-targets",
@@ -509,14 +508,14 @@
},
"runtime_catalog": {
"counts": {
"cli_commands": 68,
"cli_commands": 67,
"mcp_tools": 115,
"mcp_prompts": 6
},
"digests": {
"tools_sha256": "4722f1a2fe1d16d493e4a1f51450376e2cd0c617b9659d292a61908d8bb05fcf",
"tools_sha256": "c0b0319310502e55dd3279361c5a65615a12f25c0e97fb0779b79b7950cecfe0",
"prompts_sha256": "77c76df62f92484a43cebf5ca110bdf562c38fbee2531d293eeb51d6e712d459",
"combined_sha256": "94f7cd1ac629a6bbffa77ba3b3d3f2e208e15df821bc0b14db4f81692d6f8eaa",
"combined_sha256": "85d3e5545b3e01eb22b67a1794fdcb737654a1abbea803e1f2445815ee4f17ff",
"providers_sha256": "7446b51788734ebf6f4f702e3a5a8c9f0b61967490c245f30bd37b2060827e6b"
}
}