Session evidence and results
REA uses a session-owned evidence ledger to turn tool observations into a durable investigation record. Tools return observations to callers while keeping authenticated records for later analysis, derived work, review, and export. See the parent page MCP server, MCP tool registration, and server lifecycle and policy for the surrounding server model.
Session evidence model
Evidence ledger
An evidence record represents one authenticated observation. It identifies the subject and operation, preserves provider and normalized results, states confidence and limits, and links related records. Its stable ID comes from the record meaning, so later tools can refer to an observation without trusting a caller-created label (src/…/evidence.ts• L123-180, src/…/evidence.ts• L247-276).
The ledger belongs to one investigation session. It accepts a repeated copy of the same record without changing state, but rejects invalid or conflicting bundle state. Accepted records are sealed at the ledger boundary while caller-owned values remain safe to change, and read surfaces return detached values when callers may change them. Bundle imports validate the full candidate state before merging it. This keeps invalid records and broken links out of the session and preserves the history of questions that remain unresolved (src/…/EvidenceLedger.ts• L65-180, src/…/EvidenceLedger.ts• L183-252, src/…/EvidenceLedger.ts• L526-607).
Residual unknowns are kept as revision history with one current head per question. Creation and updates add their mutation evidence as one atomic change, and updates require the expected revision. The ledger checks evidence links and dependency rules before it commits a change, so a stale writer or broken graph cannot leave a partial state (src/…/EvidenceLedger.ts• L284-410, src/…/EvidenceLedger.ts• L517-571).
The investigation record owner separates evidence reads, evidence writes, linked unknown updates, bundle import, and retention admission from target execution and lifecycle control. A derived result can therefore add evidence and a related unresolved question as one record operation instead of exposing a partial state (src/…/InvestigationRecords.ts• L29-49, src/…/InvestigationRecords.ts• L68-148, src/…/InvestigationRecordPort.ts• L13-36, src/…/InvestigationRecordPort.ts• L54-103).
References: src/…/evidence.ts• L123-180 src/…/evidence.ts• L247-276 src/…/EvidenceLedger.ts• L65-180 src/…/EvidenceLedger.ts• L183-252 src/…/EvidenceLedger.ts• L284-410 src/…/EvidenceLedger.ts• L517-607 src/…/InvestigationRecords.ts• L29-49 src/…/InvestigationRecords.ts• L68-148 src/…/InvestigationRecordPort.ts• L13-36 src/…/InvestigationRecordPort.ts• L54-103
Session boundaries
The ledger follows the MCP session, not the currently selected target. A target change or provider restart does not remove retained evidence. A new MCP connection has a new ledger. close_binary clears the ledger, so callers must export the bundle before close if they need the investigation later (docs/mcp-contracts.md• L316-325).
A retained reference is an exact lookup in the current session. It does not select another target or start a provider. If the ID is absent, the caller must provide the full evidence record, repeat the producing operation, or import a bundle into the current session (src/…/EvidenceInputResolver.ts• L6-34).
References: docs/mcp-contracts.md• L316-325 src/…/EvidenceInputResolver.ts• L6-34 src/…/InvestigationRecords.ts• L53-76
Evidence bundles
An evidence bundle is the portable form of the session ledger. It carries evidence records, unresolved-question history, and the manifests needed to describe artifacts, providers, environments, scenarios, and process captures. Import checks record identity, manifests, revision chains, links, resolution rules, and dependency cycles before it changes the session (src/…/evidenceBundle.ts• L42-75, src/…/evidenceBundle.ts• L77-140, src/…/evidenceBundle.ts• L282-405, src/…/evidenceBundle.ts• L510-565).
A bundle can be narrowed to one target. The narrowed view keeps only records and unresolved history whose scope and evidence links remain valid. It also keeps the mutation evidence needed by retained unresolved questions. This prevents a target export from claiming support that it does not carry (src/…/evidenceBundle.ts• L151-220).
Session tools export the canonical bundle to an absolute local path and import it as data. Export and import are atomic. A valid merge can add non-identity metadata to an existing record without changing the record’s meaning, and a record-only import does not alter retained unknown history. Full imports validate the merged dependency graph before committing it, including histories deeper than the normal JavaScript call stack (src/…/registerSessionRecordTools.ts• L44-79, src/…/registerSessionRecordTools.ts• L105-155, src/…/EvidenceLedger.ts• L116-252, src/…/InvestigationRetention.test.ts• L95-119).
References: src/…/evidenceBundle.ts• L42-75 src/…/evidenceBundle.ts• L77-140 src/…/evidenceBundle.ts• L151-220 src/…/evidenceBundle.ts• L282-405 src/…/evidenceBundle.ts• L510-565 src/…/registerSessionRecordTools.ts• L44-79 src/…/registerSessionRecordTools.ts• L105-155 src/…/EvidenceLedger.ts• L116-252 src/…/InvestigationRetention.test.ts• L95-119
Retention allowance
The investigation record owner applies a fixed representation allowance to retained evidence and unresolved-question history. It admits authentication work before state changes, accounts for accepted records, and rejects a change that would exceed the allowance. Existing history is never evicted, so callers must export it or start a new investigation when capacity is exhausted (src/…/InvestigationRetention.ts• L13-109, src/…/InvestigationRecords.ts• L39-66, src/…/EvidenceLedger.ts• L643-705).
The allowance covers retained representation rather than total process memory. Authentication headroom is checked separately before a borrowed or recovered value is materialized. Recovery admission also counts source IDs and generated envelope fields before it constructs a completed record. Statistics expose current and maximum retained representation without building a bundle, and accepted changes update the count atomically with the record state (src/…/InvestigationRetention.ts• L29-84, src/…/admitCompletedAnalysis.ts• L12-54, src/…/InvestigationRecords.ts• L39-66, src/…/EvidenceLedger.ts• L643-705).
References: src/…/InvestigationRetention.ts• L13-109 src/…/admitCompletedAnalysis.ts• L12-54 src/…/EvidenceLedger.ts• L643-705 src/…/InvestigationRecords.ts• L39-66 src/…/InvestigationRetention.test.ts• L60-119
Derived operations
Derived evidence flow
Derived operations answer a new question from existing evidence. They do not silently run the source analysis again. The operation validates its inputs, computes a comparison or workflow result, and creates a new evidence record that links to every source it used. The new record preserves the limits of those sources, so its conclusion does not claim wider coverage than the underlying observations support.
Investigation workflows resolve exact retained dossiers or supplied authenticated records before they compose a result. The evidence closure then follows each selected record’s links, de-duplicates the visited records, and returns the complete transitive source set. A missing record or an identity mismatch stops the operation instead of allowing an incomplete support chain (src/…/InvestigationEvidence.ts• L8-36, src/…/InvestigationEvidence.ts• L65-103). Function comparison creates linked evidence for two function dossiers, while call-path, changed-behavior, and static-runtime workflows preserve the transitive source closure. Each workflow returns the derived evidence with the sources it consumed and may describe an unresolved question when the result is unknown or incomplete (src/…/FunctionComparisonEvidence.ts• L23-81, src/…/InvestigationWorkflows.ts• L44-64, src/…/InvestigationWorkflows.ts• L66-252).
Composed workflows observe each upstream operation and collect its provider limits. If any upstream step uses live data, the workflow result is also live. A non-live workflow can retain an analysis profile for exact replay. Batch results can also retain resolved procedure locations (src/…/WorkflowEvidence.ts• L33-73, src/…/WorkflowEvidence.ts• L76-105, src/…/WorkflowEvidence.ts• L132-168).
Provider source evidence travels with an analysis result until the session record owner can retain it. Source recording requires an explicit owner for provider-owned evidence. Caller-owned sources can remain with the caller when no writer exists. When recording fails after analysis completes, recovery first authenticates and admits the completed source facts before it builds a record. It publishes retained evidence, inline evidence, an unretained observation, or an omitted publication with the failure reason. An earlier analysis or cancellation error remains primary when source recording also fails (src/…/recordEvidenceSources.ts• L8-75, src/…/admitCompletedAnalysis.ts• L12-54, src/…/sourcePublicationRecovery.ts• L22-196).
The flow below shows how source observations become a retained conclusion and, when needed, an unresolved question.
flowchart LR
A[Source evidence] --> B[Validate source]
B --> C[Run derived operation]
C --> D[Create linked evidence]
D --> E[Retain result]
D --> F[Record unresolved question]
D --> G[Return result and reference]
Comparison tools accept exact source IDs or inline records. They retain the sources before they publish the derived record. This keeps the complete support chain available for later review (src/…/registerProcessComparisonTool.ts• L123-190, src/…/registerArtifactComparisonTool.ts• L33-83).
References: src/…/registerProcessComparisonTool.ts• L123-190 src/…/registerProcessComparisonTool.ts• L196-239 src/…/registerArtifactComparisonTool.ts• L33-83 src/…/WorkflowEvidence.ts• L33-168 src/…/InvestigationEvidence.ts• L8-103 src/…/FunctionComparisonEvidence.ts• L23-81 src/…/InvestigationWorkflows.ts• L44-252 src/…/recordEvidenceSources.ts• L8-75 src/…/admitCompletedAnalysis.ts• L12-54 src/…/sourcePublicationRecovery.ts• L22-196
Operation execution
The derived-operation boundary gives comparison and workflow work one cancellation and progress contract. It yields after setup and computation so a request can stop work before computation or publication. It reports bounded progress and maps normal computation or validation failures to typed analysis errors (src/…/runDerivedOperation.ts• L19-75).
Recording is separate from computation. An operation with unresolved or conflicting findings can retain the derived record together with an unresolved question as one atomic update. Workflow operations map residual questions into the shared unknown registry and use the derived record as support. Cancellation before publication does not produce a successful derived result (src/…/recordDerivedEvidence.ts• L7-19, src/…/runDerivedOperation.test.ts• L20-74, src/…/WorkflowEvidence.ts• L171-230).
References: src/…/runDerivedOperation.ts• L19-75 src/…/recordDerivedEvidence.ts• L7-19 src/…/runDerivedOperation.test.ts• L20-74 src/…/WorkflowEvidence.ts• L171-230
Operation availability
The canonical MCP server advertises only the enabled tool families. Out-of-scope tools can remain registered for internal composition, but they do not appear in tools/list and calls to them fail as disabled. This keeps status information from directing a caller to an operation that the server will not accept (src/…/EvidenceMcpServer.ts• L21-62).
References: src/…/EvidenceMcpServer.ts• L21-62
Retained summaries
Summary delivery
Summary delivery returns a smaller view while the session keeps the complete producer record. The summary is a view of retained evidence, not a replacement for it. A later inspect_analysis_view call can select a page or facet by the parent evidence ID without starting the provider again (src/…/AnalysisViewService.ts• L102-160).
Only operations that support retained views accept detail: "summary". The server checks that it can retain and find the complete source before analysis starts. A server without session retention rejects the request and directs the caller to request complete delivery (src/…/retainedSummaryDelivery.ts• L25-52, src/…/AnalysisViewService.ts• L108-137).
References: src/…/AnalysisViewService.ts• L102-160 src/…/retainedSummaryDelivery.ts• L25-52 src/…/AnalysisViewService.ts• L108-137
Bundle discovery
get_evidence_bundle supports complete delivery, summary discovery, complete-record selection, and link inspection. Summary mode returns record identity and metadata without copying large result values. Records mode applies exact filters and can page the complete selected records. Links mode reports link membership and can inspect direct or retained-closure links with missing, retained, or all link status. Exact filters can select an evidence ID, operation, target digest, analysis-profile digest, or native procedure address. The summary describes complete retained records, while native value-flow coverage is reported as separate metadata (src/…/evidenceRecordSummary.ts• L57-78, src/…/evidenceRecordSummary.ts• L117-166, src/…/InspectEvidenceBundle.ts• L12-98).
Complete bundle delivery is the default and returns the canonical bundle without filters. Filters require summary, records, or links detail. Paging requires records or links detail, while link traversal and link status apply only to links detail. The server rejects delivery options sent with the wrong detail mode instead of ignoring them. A discovered ID can then be used with a retained view, or the caller can export the complete bundle when one response cannot carry the payload (src/…/InspectEvidenceBundle.ts• L12-98, src/…/registerSessionRecordTools.ts• L81-103).
References: src/…/evidenceRecordSummary.ts• L57-78 src/…/evidenceRecordSummary.ts• L117-166 src/…/InspectEvidenceBundle.ts• L12-98 src/…/registerSessionRecordTools.ts• L81-103
Result encoding
Successful result shape
An evidence-producing tool returns the complete evidence record in structured content and in the text representation. The structured result also exposes the record ID and, when retention is available, an exact retained-evidence reference. The normalized result is the value used by the operation. raw_result preserves a distinct provider representation when one exists (src/…/toolResult.ts• L67-86, docs/mcp-contracts.md• L9-22).
This shape lets a client use the result at once or pass the full record to a compatible follow-up. A retained reference is only a lookup key in the current session. It does not replace the complete record kept by the ledger.
References: src/…/toolResult.ts• L67-86 src/…/evidence.ts• L123-140 docs/mcp-contracts.md• L9-22
Response budget
Successful MCP results repeat JSON in structured and escaped text forms. REA measures both forms before it allocates the final text. It also counts the JSON-RPC envelope and any untrusted-content marker (src/…/toolResultEncoding.ts• L45-64, src/…/toolResultEncoding.ts• L86-119).
If a complete result does not fit, REA does not cut it. It returns a typed transport error and keeps completed evidence in the session when recording succeeded. The error offers an evidence reference, a retained native continuation, or guidance to export the bundle or use a larger matching client budget (src/…/toolResult.ts• L152-202).
Tool failures use text-only error delivery. An oversized failure can itself become mcp_tool_error evidence so its original diagnostic remains recoverable (src/…/toolResult.ts• L89-149, src/…/EvidenceMcpServer.ts• L391-451).
When a failed operation includes a valid partial observation, delivery tries to record that observation before it returns the error. If the ledger refuses the record, the error preserves the ledger’s exact fact: the observation is retained, unretained, or of unknown retention. A mismatched retained ID is not trusted. The retention refusal is reported without repeating the partial observation inside the nested error (src/…/ToolResultDelivery.ts• L362-410, src/…/ToolResultDelivery.ts• L539-559).
References: src/…/toolResultEncoding.ts• L45-64 src/…/toolResultEncoding.ts• L86-119 src/…/toolResult.ts• L152-202 src/…/EvidenceMcpServer.ts• L391-451 src/…/ToolResultDelivery.ts• L362-410 src/…/ToolResultDelivery.partialRetention.test.ts• L39-79
Target content marker
Results can include text from an analyzed target, provider, launcher, device, or process capture. These results carry _meta.provenance.untrusted_content: true, which lets a host treat the text as data instead of instructions for later tool calls (src/…/toolResultEncoding.ts• L20-43, src/…/toolEffects.ts• L737-760).
Only tools whose successful and failed results contain REA-authored session state or caller data are exempt. The marker also applies to errors because failure diagnostics can contain captured external text (docs/mcp-contracts.md• L154-191).
References: src/…/toolResultEncoding.ts• L20-43 src/…/toolEffects.ts• L737-760 docs/mcp-contracts.md• L154-191
Tool logging
Execution log records
The common tool logger records operational timing, tool name, and final status. Successful calls use an info log. Failed calls use a warning log. The log does not record caller input, result payloads, or evidence content (src/…/toolLogging.ts• L4-20).
Operational logging is separate from evidence retention. A tool can retain a complete observation for investigation while its log contains only timing and status. Lifecycle cleanup can also emit focused warnings when owned resources fail to close (src/…/registerEvidenceTools.ts• L88-145, src/…/registerCloseLifecycleTool.ts• L21-57).
References: src/…/toolLogging.ts• L4-20 src/…/registerEvidenceTools.ts• L88-145 src/…/registerCloseLifecycleTool.ts• L21-57
Change checklist
When these files or sections are changed, remember to consider these:
- When evidence identity fields change, update semantic hashing, bundle authentication, import conflict checks, and every derived
evidence_linkscontract together. - When retained-record admission changes, keep authentication headroom, recovery admission, representation accounting, atomic commits, statistics, and no-eviction behavior aligned.
- When residual-unknown revision rules change, keep optimistic revision checks, mutation-evidence links, current-head reads, dependency checks, and atomic ledger updates aligned.
- When unknown history import changes, preserve record-only merge behavior, divergent revision refusal, metadata replacement rules, and all-or-nothing graph validation.
- When a producer adds summary delivery, keep delivery-only fields out of evidence identity and retain the complete parent before creating the returned view.
- When unresolved-question rules change, keep revision chains, evidence qualification, relationship checks, cycle checks, and atomic ledger updates aligned.
- When a composed workflow changes its upstream calls or result shape, keep limit capture, live-data handling, replay bindings, procedure locations, and unresolved-question mapping aligned with the produced evidence.
- When an investigation workflow changes its selected sources, preserve exact source identity, supplied inline records, transitive closure, derived links, and unresolved-question scope.
- When an analysis adapter can return source evidence, preserve the explicit recorder or caller-owner contract. If recording fails, keep the completed-result recovery states and the earlier analysis or cancellation error primary.
- When result representations or metadata change, recalculate structured and text budget accounting, including the untrusted-content marker.
- When a tool is added or moved, align its output contract, effect audit, target-content classification, evidence recording path, and operational logging wrapper.
- When tool-family advertisement changes, keep
tools/list, disabled-call behavior, and status guidance consistent with the enabled families. - When session close or target-transition policy changes, re-check retained-reference lifetime, export timing, and recovery after provider cleanup failure.
- When
get_evidence_bundledetail modes change, keep complete delivery, summary discovery, record selection, link inspection, filter rules, delivery-specific options, and paging rules consistent. - When partial-observation retention changes, preserve the ledger’s exact retained or unretained fact and do not trust a returned ID that does not match the partial record.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| A retained evidence ID is used from another connection or after close | The reference is missing and no provider lookup occurs | Export and import a bundle, or pass complete evidence in the current session |
| A session exceeds its retained representation allowance | The new evidence or unknown revision is rejected while existing history stays available | Export the investigation or increase the parent process heap before starting a new investigation |
| Summary detail is requested without a retaining session | Analysis does not start and the call returns capability_unavailable | Request complete detail or use a session that retains evidence |
| An analysis adapter returns provider source evidence without an explicit recorder or retention owner | The operation returns capability_unavailable instead of publishing a usable source link | Use an analysis session that retains provider source evidence or supply an Evidence recorder |
| Source recording fails after a completed analysis or cancellation | Recovery may publish retained, inline, unretained, or omitted source publication. An earlier analysis or cancellation error remains primary | Authenticate and admit the completed facts before constructing recovery evidence. Treat the recording error as secondary when an earlier error exists |
| Recovery source IDs are malformed or the completed source evidence fails authentication | The source closure is not established and recovery publishes an unretained observation or an omitted publication | Use authenticated source evidence and preserve the original producer result |
| A closure reference is missing or resolves to a record with another identity | The derived operation fails instead of producing an incomplete or unsupported conclusion | Use the original producer result or an authenticated retained reference with the expected ID |
| Source evidence has a bad digest, wrong operation, or incomplete coverage | The derived operation fails instead of producing an unsupported conclusion | Use the original producer result or an authenticated retained reference |
| A composed workflow uses a source limit but does not carry it into the derived record | The result can claim more coverage than the observations support | Capture limits from each upstream execution and include them in workflow evidence |
| Live upstream work is treated as an exact replay source | The workflow can expose a replay binding for data that is not stable | Mark the composed result as live and omit the replay snapshot |
| A stale unknown revision is submitted | The update is rejected and the current head remains unchanged | Read the current head and submit its expected revision |
| An unknown update omits linked mutation evidence or creates a dependency cycle | The unknown history is rejected instead of entering a partial state | Use authenticated mutation evidence and validate the full dependency graph before commit |
| A complete result exceeds the MCP response budget | The result is not truncated and delivery returns a transport error | Use the retained continuation, export the bundle, or align a larger client buffer and server budget |
| A failed operation includes a partial observation but retention is refused or names another evidence ID | The error reports the exact known retention state, or marks it unknown, without claiming a different retained record | Use the returned inline observation when retention is unknown, or use the named retained ID only when it matches the partial observation |
| Bundle validation or a record conflict fails during import | No partial bundle merge is committed | Re-export or repair the source bundle, then import it again |
| A target bundle includes an unresolved question with out-of-scope evidence or an unavailable related question | The question is removed from the target view instead of being exported as supported state | Export the full session bundle or retain all valid target-scoped dependencies |
| An unresolved-question revision has a broken chain, missing reference, invalid resolution, or dependency cycle | The unresolved state is rejected and cannot enter the ledger | Use the next valid revision and include qualifying evidence for any verified resolution |
| Bundle filters or paging are sent with complete or summary detail | The session query is rejected instead of returning a partial or ambiguous selection | Use summary for discovery or records for filtered and paged complete records |
Key files
| File | Why to read it |
|---|---|
| src/…/evidence.ts | Defines the meaning and identity of one evidence record. |
| src/…/EvidenceLedger.ts | Shows session retention, idempotent recording, import, lookup, unresolved-question updates, and clearing. |
| src/…/InvestigationRetention.ts | Defines authentication headroom and the bounded representation allowance for retained records. |
| src/…/admitCompletedAnalysis.ts | Shows how completed source facts are admitted before recovery materializes a record. |
| src/…/sourcePublicationRecovery.ts | Shows how completed source evidence is authenticated and exposed when normal source recording fails. |
| src/…/InvestigationRecords.ts | Presents the investigation record owner and its evidence, bundle, unknown, recovery, and statistics boundary. |
| src/…/EvidenceLedger.residualUnknown.test.ts | Shows the guarantees for immutable reads, revision history, atomic updates, deep dependency chains, and conflict-safe imports. |
| src/…/InvestigationRecordPort.ts | Defines the read, write, unknown-registry, and bundle-import boundary for investigation records. |
| src/…/FunctionComparisonEvidence.ts | Shows how two retained function dossiers become linked comparison evidence and an optional unknown. |
| src/…/InvestigationWorkflows.ts | Shows how retained dossiers become call-path, changed-behavior, and static-runtime evidence. |
| src/…/InvestigationEvidence.ts | Resolves the exact transitive source closure needed by a derived investigation, including supplied authenticated records. |
| src/…/recordEvidenceSources.ts | Defines how provider source evidence stays linked to analysis results and how recording ownership and failures are reported. |
| src/…/evidenceBundle.ts | Defines portable bundle contents, target scoping, canonical order, and integrity checks. |
| src/…/InspectEvidenceBundle.ts | Defines the allowed bundle views and the filters, paging, and link options for each view. |
| src/…/registerEvidenceTools.ts | Shows the normal provider-observation path from execution to evidence delivery. |
| src/…/runDerivedOperation.ts | Defines cancellation, progress, and publication behavior for derived work. |
| src/…/WorkflowEvidence.ts | Shows how composed workflow limits, live-data status, replay bindings, locations, and residual questions become evidence. |
| src/…/retainedSummaryDelivery.ts | Connects summary requests to complete retained source records. |
| src/…/toolResult.ts | Defines successful and failed MCP result delivery and recovery advice. |
| src/…/ToolResultDelivery.ts | Applies shared result encoding, response recovery, and partial-observation retention rules. |
| src/…/ToolResultDelivery.partialRetention.test.ts | Shows that failed partial observations preserve the ledger’s retention fact without trusting a mismatched ID. |
| src/…/toolResultEncoding.ts | Defines wire-size accounting and target-content metadata. |
| src/…/EvidenceMcpServer.ts | Defines which tool families the canonical server advertises to callers. |
| src/…/toolLogging.ts | Defines the small operational log record for tool execution. |
| src/…/registerSessionRecordTools.ts | Defines bundle export/import and session evidence queries. |