investigation-workspaces.md

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:

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:

{
  "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.