[GH-ISSUE #722] [Design] Add exact retained-Evidence references to follow-up analysis inputs #321

New issue

Closed

opened 2026-10-15 18:23:50 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-15 18:23:50 +00:00

Owner

Originally created by @N0zoM1z0 on GitHub (Oct 6, 2026).
Original GitHub issue: https://github.com/morluto/rea/issues/722

Before submitting

I searched the open and closed issues and relevant pull requests for a related report.
I removed credentials, tokens, private paths, and sensitive target data.

Decision needed

How should existing trace/compare tools accept an exact record already retained by the same connected investigation, while preserving complete portable inline Evidence inputs?

Context and evidence

The public inputs of trace_application_feature, compare_application_versions, and compare_javascript_export_shapes require full application Evidence. No retained-ID alternative was advertised in the evaluated baseline. A bundle inspection confirmed that the server already held the producer records.

A three-file, 422-byte JS fixture produced an approximately 180 KB normalized analysis. The client unpacked structuredContent.evidence, retained it, and resent full objects. This succeeded with a script, but REA still made the caller handle large round trips for an ordinary next question. No model-host transcription failure was measured.

Boundary and invariants

Resolve references at the shared application/Evidence boundary, with connection-scoped ownership and exact identity. Keep provider protocols out of domain/application workflows.

Preserve inline Evidence for cross-session use and complete next-step results inline. Retain authority, confidence, artifact/source identity, integrity checks, limitations, unknowns, and typed failures. A reference must not execute analysis, change authority, select a backend, or introduce a permission/grant step. CLI/MCP analysis semantics must remain equivalent through the applicable shared workflows.

Options and tradeoffs

Add a discriminated same-session reference alternative to existing inputs; resolve it to the exact canonical record before the current validator/workflow. This avoids repeated transfers but introduces explicit lifetime/not-found semantics.
Reuse an existing canonical Evidence resource URI if it provides exact scoped resolution without requiring an extra resource read merely to form a follow-up call.
Keep inline-only inputs and improve guidance. Compatible, but leaves the measured retransmission burden.

The decision should account for client schema compatibility and avoid a new orchestration language or prepare/execute tool.

Success criteria and open questions

Trace/compare a retained JS result using an exact reference; obtain the same analyst-visible result as the inline form.
Inline Evidence remains valid, including its normalized_result, and cross-session comparison remains possible.
Unknown, expired, mismatched, and cross-connection references fail with their actual reasons and available recovery.
Returned findings remain inline; no mandatory lookup is added for already useful output.
Advertised schemas validate after SDK conversion and generated contracts stay aligned.
Document how reference lifetime interacts with target cleanup; the separate lifecycle decision will track that boundary.

Open question: which existing reference representation best preserves current client compatibility and identity semantics?

References

Hands-on public CLI/MCP evaluation, findings F04. Baseline: REA 4.0.1, source revision c3bc38bf6c74d2175a4680530dcadd6cab0e7791; evaluation date 2026-10-06.

Follow-up to #264, whose 2.0 closure described retained-ID inputs. Current 4.0.1 inputs again require complete inline records. #551 and #585 fixed missing normalized_result; preserve that fix rather than compacting required Evidence fields away. #99 covers resources, which by themselves do not prove these tools accept references. docs/mcp-contracts.md

Related evaluation issues: #721.

Originally created by @N0zoM1z0 on GitHub (Oct 6, 2026). Original GitHub issue: https://github.com/morluto/rea/issues/722 ### Before submitting - [x] I searched the open and closed issues and relevant pull requests for a related report. - [x] I removed credentials, tokens, private paths, and sensitive target data. ### Decision needed How should existing trace/compare tools accept an exact record already retained by the same connected investigation, while preserving complete portable inline Evidence inputs? ### Context and evidence The public inputs of `trace_application_feature`, `compare_application_versions`, and `compare_javascript_export_shapes` require full application Evidence. No retained-ID alternative was advertised in the evaluated baseline. A bundle inspection confirmed that the server already held the producer records. A three-file, 422-byte JS fixture produced an approximately 180 KB normalized analysis. The client unpacked `structuredContent.evidence`, retained it, and resent full objects. This succeeded with a script, but REA still made the caller handle large round trips for an ordinary next question. No model-host transcription failure was measured. ### Boundary and invariants Resolve references at the shared application/Evidence boundary, with connection-scoped ownership and exact identity. Keep provider protocols out of domain/application workflows. Preserve inline Evidence for cross-session use and complete next-step results inline. Retain authority, confidence, artifact/source identity, integrity checks, limitations, unknowns, and typed failures. A reference must not execute analysis, change authority, select a backend, or introduce a permission/grant step. CLI/MCP analysis semantics must remain equivalent through the applicable shared workflows. ### Options and tradeoffs 1. Add a discriminated same-session reference alternative to existing inputs; resolve it to the exact canonical record before the current validator/workflow. This avoids repeated transfers but introduces explicit lifetime/not-found semantics. 2. Reuse an existing canonical Evidence resource URI if it provides exact scoped resolution without requiring an extra resource read merely to form a follow-up call. 3. Keep inline-only inputs and improve guidance. Compatible, but leaves the measured retransmission burden. The decision should account for client schema compatibility and avoid a new orchestration language or prepare/execute tool. ### Success criteria and open questions - Trace/compare a retained JS result using an exact reference; obtain the same analyst-visible result as the inline form. - Inline Evidence remains valid, including its normalized_result, and cross-session comparison remains possible. - Unknown, expired, mismatched, and cross-connection references fail with their actual reasons and available recovery. - Returned findings remain inline; no mandatory lookup is added for already useful output. - Advertised schemas validate after SDK conversion and generated contracts stay aligned. - Document how reference lifetime interacts with target cleanup; the separate lifecycle decision will track that boundary. Open question: which existing reference representation best preserves current client compatibility and identity semantics? ### References Hands-on public CLI/MCP evaluation, findings F04. Baseline: REA 4.0.1, source revision [c3bc38bf6c74d2175a4680530dcadd6cab0e7791](https://github.com/morluto/rea/commit/c3bc38bf6c74d2175a4680530dcadd6cab0e7791); evaluation date 2026-10-06. Follow-up to [#264](https://github.com/morluto/rea/issues/264), whose 2.0 closure described retained-ID inputs. Current 4.0.1 inputs again require complete inline records. [#551](https://github.com/morluto/rea/issues/551) and [#585](https://github.com/morluto/rea/pull/585) fixed missing normalized_result; preserve that fix rather than compacting required Evidence fields away. [#99](https://github.com/morluto/rea/issues/99) covers resources, which by themselves do not prove these tools accept references. [docs/mcp-contracts.md](https://github.com/morluto/rea/blob/c3bc38bf6c74d2175a4680530dcadd6cab0e7791/docs/mcp-contracts.md) Related evaluation issues: [#721](https://github.com/morluto/rea/issues/721).

bsakaguchi

2026-10-15 18:23:50 +00:00