rea/docs/migration-6.2.md

Upgrading from REA 6.1 to 6.2

REA 6.2 includes stability fixes and changes to public result and saved-data contracts. The repository uses always-bump-minor, including breaking releases; the minor version increment does not imply backward compatibility. Refresh cached MCP tool definitions after upgrading and adapt custom consumers using this guide.

MCP results and Evidence

Evidence-producing tools now return the complete Evidence record directly in structuredContent and JSON text. The old { result, evidence_id, evidence } wrapper is gone. For a successful Evidence-producing call, change:

// 6.1
const value = reply.structuredContent.result;
const evidence = reply.structuredContent.evidence;

// 6.2
const evidence = reply.structuredContent;
const value = evidence.normalized_result;
const evidenceId = evidence.evidence_id;

Check isError before reading success fields. Error results have isError: true and carry their typed JSON diagnostic in a text content block; they omit structuredContent so they cannot violate the advertised success output schema.

if (reply.isError === true) {
  const text = reply.content.find((part) => part.type === "text");
  if (text === undefined) throw new Error("REA error has no text diagnostic");
  const { error: diagnostic } = JSON.parse(text.text);
  // Handle diagnostic.code, diagnostic.message and diagnostic.details.
}

Lifecycle and other non-Evidence tools still use their own advertised output contracts. Do not assume every successful tool returns Evidence. Consult tools/list and the result guide.

A transport resource_constraint error can include a retained details.reported_limits.evidence_reference. Use inspect_analysis_view or export_evidence_bundle on the same connection to consume the complete retained Evidence. Response-budget settings are captured when the server starts; recreate the server to change them, and keep the client's receive budget aligned. Raising the server budget does not change the client's limit or analysis coverage.

Every Evidence record now requires analysis_profile, either its observed profile object or null. The field participates in Evidence identity. Records that omitted it cannot be migrated by inserting null while retaining the old evidence_id. Keep the original files and regenerate affected observations with 6.2; use the new returned identities when linking or comparing them. Existing records that already satisfy the complete canonical contract remain usable.

The binary_session result removes the redundant top-level provider and providers aliases. Read analysis_provider_binding, analysis_provider_candidates and per-operation capabilities for selection and availability. Select a deep provider through open_binary.provider_id or CLI --provider, using the advertised values.

These changes establish one complete result representation and explicit provider/profile ownership rather than accepting incomplete producer records. See 63bf914 and #1277.

Saved snapshots and artifact inventories

Analysis snapshots require workflow_entries and a corresponding profile-bound Evidence record for every cached query. Import rejects incomplete bindings instead of silently discarding them. Preserve an incompatible snapshot and choose a new output path when rerunning analysis, for example:

rea analyze /absolute/path/to/program --provider ghidra --snapshot /absolute/path/to/analysis/program-6.2.json

In MCP, open the target without the incompatible snapshot_path, run the required queries, then save to a new path through close_binary.snapshot_path. Do not fabricate missing provider profiles or query bindings. See snapshot usage.

Artifact inventory nodes identify content bytes. Path-specific role and permissions now belong to each occurrence:

Previously read	Read in 6.2
nodes[].kind	occurrences[].artifact_kind
Path-specific nodes[].format	occurrences[].artifact_format
nodes[].executable	occurrences[].executable
Content identity and byte format	nodes[].artifact_id, sha256, format

Join an occurrence to its content node using artifact_id; inspect the selected occurrence's role rather than choosing one role for all paths with equal bytes. An executable binary format can have artifact_kind: "executable" while its current filesystem permission produces executable: false. A .js and .txt file with identical bytes can share a node and retain different roles. Regenerate old inventories: a merged content node alone cannot recover the per-path facts that were lost. These changes are part of 63bf914.

Process captures and cleanup failures

REA no longer converts legacy v3 process captures on import. Captures require explicit selected/launch executable identity and event_journal; missing data is rejected instead of being filled during parsing. Preserve old captures for historical reference and recapture with 6.2 when current comparisons are needed. Do not infer the original launched binary from a later file digest, or invent event ordering from independently recorded collections. An explicitly empty journal is valid under its advertised contract; the field cannot be omitted. See 2a77469.

Filesystem effects can now report status: "unknown" with a reason when a partial snapshot cannot establish creation or deletion. Update exhaustive status readers and retain observed facts separately from absence assumptions.

A completed one-shot analysis can report cleanup_incomplete rather than silently returning success when provider cleanup fails. Preserve its details.partial_observation or primary execution diagnostics, inspect the reported owned resources, and address cleanup before retrying. A successful analysis observation does not prove successful cleanup. This behavior is covered by #1211. That change also makes configured agent-evaluation fixture checks grade cited Evidence; routing or answer wording alone no longer passes an assessed fixture.

JavaScript and function comparisons

JavaScript return-field projections require presence with present, absent or unknown-coverage. Export-shape change rows retain both sides' presence, and property_inventories report examined properties and coverage. Unknown values and unknown presence are distinct; callers must not treat an unknown value as a missing property. Semantic object-operation graph observations use properties.property_path, an array of complete path segments or null, rather than a flattened property name. Regenerate old application analysis before depending on nested mutation or presence facts. See 475a0f8.

Function comparison dimension statuses are unchanged, changed or unknown. The unreachable truncated status and summary.truncated counter have been removed. Update exhaustive enum handling and display logic; unavailable facts remain unknown. See 5510b27.

Historical-source symlinks

Source graph symlinks with target_state: "unreadable" or "unknown" require target: null. Internal, external and missing targets retain their actual recorded target strings. External targets use the observed absolute target; display placeholders such as <outside-root> cannot serve as lookup data. Reimport the source tree when the old graph retained only a placeholder, and handle nullable targets in custom readers. See b7b4333.

Keep original saved artifacts until their replacements and consuming workflows have been checked. Fresh analysis may establish different facts if the target, source tree or runtime changed; it does not rewrite what an older capture proved.