125 lines
4.7 KiB
Markdown
125 lines
4.7 KiB
Markdown
# 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"]'
|
|
export REA_INVESTIGATION_INPUT_ROOTS_JSON='["/absolute/path/to/releases"]'
|
|
|
|
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. Both must resolve beneath an explicitly configured
|
|
`REA_INVESTIGATION_INPUT_ROOTS_JSON` root. The workspace parent must already
|
|
exist beneath `REA_EVIDENCE_ROOTS_JSON`. REA never creates an allowlisted root
|
|
implicitly.
|
|
|
|
Use `--expected-revision N` when an external coordinator needs an explicit
|
|
compare-and-swap guard. Traversal, byte, page, and comparison limits are also
|
|
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,
|
|
artifact inputs outside `REA_INVESTIGATION_INPUT_ROOTS_JSON`,
|
|
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.
|