Reverse engineer anything with agents, from app behavior down to native binaries.
TypeScript agent-skillsai-agentsbinary-analysisclaude-codeclicodexcordisdecompilerdeveloper-toolsdshdsh-pluginghidrahopperllmmcpmodel-context-protocolreareverse-engineeringstatic-analysistouhou
fix(mcp): retain complete application results across response limits
Ysopwnablea1ed4232de63
diff --git a/docs/javascript-artifact-reconstruction.md b/docs/javascript-artifact-reconstruction.mdindex f3eda9698..90dbb92ef 100644--- a/docs/javascript-artifact-reconstruction.md+++ b/docs/javascript-artifact-reconstruction.md@@ -100,17 +100,22 @@ a temporary output file larger than the running engine's string limit, verifiesits bytes and digest, and removes it. Use `-- jsonl` for the compact JSONL check.Each check needs space for one output file plus a 1 GiB free-space reserve.-Other CLI formats, `--token-count`, and MCP transport serialization still-assemble whole strings. Field selection remains useful when the caller needs a+Other CLI formats and `--token-count` still assemble whole strings.+Field selection remains useful when the caller needs asmaller view, for example `--format json --filter-outputevidence_id,normalized_result.statistics`. Streaming output does not bound thememory needed to construct the analysis graph itself.-The separate large-response transport work is tracked in-[#1053](https://github.com/morluto/rea/issues/1053) and+MCP prepares the complete repeated response incrementally against the pinned+SDK's 10 MiB stdio receive-buffer budget. Oversized results return an actionable+transport constraint and the exact same-session Evidence reference. Use+`trace_application_feature` to inspect a selected module's relationships, or+`export_evidence_bundle` to write the complete canonical bundle without a+document-sized allocation. Same-session analysis reads reuse authenticated+immutable snapshots; foreign inline Evidence is still parsed and authenticated.+See [MCP tool results](mcp-contracts.md#tool-results) for larger client buffers+and `REA_MCP_MAX_RESPONSE_BYTES`. Follow-up results remain complete and can also+exceed the transport budget. Compact result views are tracked separately in[#1050](https://github.com/morluto/rea/issues/1050).-Client framing limits also apply: the pinned Node MCP SDK's stdio transport-defaults to a 10 MiB buffer. Its caller-selected `maxBufferSize` must accommodate-the complete response, including text and structured Evidence projections.## What is reconstructeddiff --git a/docs/mcp-contracts.md b/docs/mcp-contracts.mdindex 2ce8f5c3d..7445df1e6 100644--- a/docs/mcp-contracts.md+++ b/docs/mcp-contracts.md@@ -164,6 +164,26 @@ directly to `compare_functions`, and `inspect_artifact` Evidence to`compare_artifacts`. Use `get_evidence_bundle` when the task needs broaderretained session history or an explicit bundle for transfer.+REA prepares complete MCP results within the pinned stdio client's 10 MiB+receive-buffer budget, including both text and structured representations and+room for the JSON-RPC envelope. If a result cannot fit, REA returns+`resource_constraint` with `details.resource: "transport"` before constructing+a document-sized string. Analysis Evidence remains complete in the current+session. Its exact reference is reported in+`details.reported_limits.evidence_reference`; use it with a focused application+workflow, or call `export_evidence_bundle` with a destination path. Complete+bundle exports stream canonical JSON into an atomically published file. A broad+follow-up or `get_evidence_bundle` can also exceed the response budget; exporting+preserves the complete session without sending it through a single MCP frame.++Clients that explicitly configure a larger receive buffer can set the REA+server's `REA_MCP_MAX_RESPONSE_BYTES` environment variable to the same byte+count. This setting must be a safe decimal integer at least 10485760; REA+reserves 1024 bytes for the envelope. Raising it restores complete inline+delivery for responses that fit that buffer and Node's single-string limit.+It does not change the client's buffer, analysis coverage, or retained content.+Ordinary responses keep their existing complete result contract.+## Retained application Evidence inputs`trace_application_feature`, `trace_javascript_semantics`,diff --git a/scripts/lib/browser-screenshot-e2e.mjs b/scripts/lib/browser-screenshot-e2e.mjsindex e7da037ab..9eed016c4 100644--- a/scripts/lib/browser-screenshot-e2e.mjs+++ b/scripts/lib/browser-screenshot-e2e.mjs@@ -1,5 +1,8 @@import assert from "node:assert/strict";import { execFile } from "node:child_process";+import { mkdtemp, readFile, rm } from "node:fs/promises";+import { tmpdir } from "node:os";+import { join } from "node:path";import { promisify } from "node:util";import { fileURLToPath } from "node:url";import { chromium } from "playwright-core";@@ -62,13 +65,21 @@ export async function verifyLargeScreenshotE2e(endpoint, origin) {);assert.equal(bytes.readUInt32BE(16), 2048);assert.equal(bytes.readUInt32BE(20), 1536);+ await verifyDefaultScreenshotDelivery({+ entrypoint,+ environment: env,+ endpoint,+ targetId: target.id,+ screenshot,+ });+ const maxBufferSize = 64 * 1024 * 1024;transport = new StdioClientTransport({command: process.execPath,args: [entrypoint, "mcp"],- env,+ env: { ...env, REA_MCP_MAX_RESPONSE_BYTES: String(maxBufferSize) },stderr: "pipe",// The SDK defaults to a 10 MiB receive buffer; inline PNG output is larger.- maxBufferSize: 64 * 1024 * 1024,+ maxBufferSize,});client = new Client({ name: "browser-screenshot-real-e2e", version: "1" });await client.connect(transport);@@ -102,6 +113,9 @@ export async function verifyLargeScreenshotE2e(endpoint, origin) {mocked: false,cli: true,stdio_mcp: true,+ default_buffer_recovery: true,+ complete_export: true,+ matched_large_buffer: true,png_bytes: bytes.byteLength,};} finally {@@ -117,3 +131,73 @@ export async function verifyLargeScreenshotE2e(endpoint, origin) {}}}++const verifyDefaultScreenshotDelivery = async ({+ entrypoint,+ environment,+ endpoint,+ targetId,+ screenshot,+}) => {+ const workspace = await mkdtemp(join(tmpdir(), "rea-screenshot-delivery-"));+ const transport = new StdioClientTransport({+ command: process.execPath,+ args: [entrypoint, "mcp"],+ env: environment,+ stderr: "pipe",+ });+ const client = new Client({+ name: "browser-screenshot-default-e2e",+ version: "1",+ });+ try {+ await client.connect(transport);+ const constrained = await client.callTool(+ {+ name: "capture_web_screenshot",+ arguments: { cdp_endpoint: endpoint, target_id: targetId },+ },+ { timeout: 60000 },+ );+ assert.equal(constrained.isError, true);+ assert.equal(+ constrained.structuredContent?.error?.details?.resource,+ "transport",+ );+ const reference =+ constrained.structuredContent?.error?.details?.reported_limits+ ?.evidence_reference;+ assert.equal(reference?.kind, "retained-evidence");+ await client.ping();+ const exported = await client.callTool({+ name: "export_evidence_bundle",+ arguments: { path: join(workspace, "screenshot-evidence.json") },+ });+ assert.notEqual(exported.isError, true, JSON.stringify(exported));+ const bundle = JSON.parse(+ await readFile(join(workspace, "screenshot-evidence.json"), "utf8"),+ );+ const record = bundle.records.find(+ (record) => record.evidence_id === reference.evidence_id,+ );+ assert.ok(+ record,+ "Full screenshot Evidence must remain exportable after the delivery constraint",+ );+ const retained = webScreenshotSchema.parse(+ parseEvidence(record).normalized_result,+ );+ assert.deepEqual(retained.artifact, screenshot.artifact);+ await client.ping();+ } finally {+ try {+ await client.close();+ } finally {+ try {+ await transport.close();+ } finally {+ await rm(workspace, { recursive: true, force: true });+ }+ }+ }+};diff --git a/scripts/lib/large-result-mcp.mjs b/scripts/lib/large-result-mcp.mjsindex d7a4ab30f..2d304110e 100644--- a/scripts/lib/large-result-mcp.mjs+++ b/scripts/lib/large-result-mcp.mjs@@ -10,7 +10,10 @@ export const withLargeResultMcp = async (const transport = new StdioClientTransport({command: process.execPath,args: [entrypoint, "mcp"],- env: environment,+ env: {+ ...environment,+ REA_MCP_MAX_RESPONSE_BYTES: String(maxBufferSize),+ },stderr: "inherit",maxBufferSize,});diff --git a/skill-src/reverse-engineer-anything/SKILL.md b/skill-src/reverse-engineer-anything/SKILL.mdindex 629a72731..d1b369060 100644--- a/skill-src/reverse-engineer-anything/SKILL.md+++ b/skill-src/reverse-engineer-anything/SKILL.md@@ -144,6 +144,13 @@ Start with the default result and use its inline Evidence and graph context.Do not repeat an identical tool call. Make a focused follow-up only when thereturned result leaves a specific question unanswered.+If MCP reports `resource_constraint` with `details.resource: "transport"`, use+its reported same-session Evidence reference with a focused application tool,+or call `export_evidence_bundle` to write the complete session to a selected+path. The analysis remains complete in the ledger; avoid repeating it merely+to request the same oversized response. Complete CLI JSON output also streams+without a single MCP frame.+Every conclusion must distinguish observations, inferences, and unknowns. CiteEvidence IDs, preserve limitations and incomplete coverage, and never implythat static analysis observed execution. Runtime requests execute the declareddiff --git a/skill-src/reverse-engineer-anything/references/javascript-applications.md b/skill-src/reverse-engineer-anything/references/javascript-applications.mdindex e19c3cdc8..03868c10c 100644--- a/skill-src/reverse-engineer-anything/references/javascript-applications.md+++ b/skill-src/reverse-engineer-anything/references/javascript-applications.md@@ -2,10 +2,17 @@Use `analyze_javascript_application` directly on the operator-supplied ASAR orextracted tree. The complete result, graph, and Evidence context are returned-inline. Source-map contents are part of the static analysis. Start from its+inline when they fit the MCP frame. Source-map contents are part of the static analysis. Start from itsfindings, coverage, unknowns, and graph context, then make a focused follow-uponly when a specific question remains unanswered.+An oversized response reports `resource_constraint` and+`details.resource: "transport"`. Reuse+`details.reported_limits.evidence_reference` with `trace_application_feature`+for the module or feature under investigation. `export_evidence_bundle` writes+the complete canonical session to a caller-selected file. Both workflows keep+the original Evidence and coverage; a broad follow-up can also exceed framing.+BrowserWindow preferences, preload and contextBridge surfaces, IPCregistrations, utility processes, and native binding requests are static syntaxobservations. Only a unique exact literal IPC channel match supports an inferreddiff --git a/src/application/EvidenceBundleFiles.ts b/src/application/EvidenceBundleFiles.tsindex 6e4c7cda0..57eeb1397 100644--- a/src/application/EvidenceBundleFiles.ts+++ b/src/application/EvidenceBundleFiles.ts@@ -2,7 +2,6 @@ import {describeEvidenceBundleFailure,describeValidationFailure,parseEvidenceBundle,- serializeEvidenceBundle,type EvidenceBundle,} from "../domain/evidenceBundle.js";import {@@ -11,7 +10,11 @@ import {} from "../domain/evidenceErrors.js";import { err, ok, type Result } from "../domain/result.js";import { parseProcessCapture } from "../domain/process/processCapture.js";-import { readJsonFile, writeTextFile } from "./JsonFiles.js";+import {+ bufferedJsonParts,+ canonicalJsonParts,+} from "../domain/jsonSerialization.js";+import { readJsonFile, writeTextParts } from "./JsonFiles.js";type EvidenceReadFailure = EvidenceFileError | EvidenceIntegrityError;type EvidenceWriteFailure = EvidenceFileError | EvidenceIntegrityError;@@ -60,9 +63,9 @@ export const writeEvidenceBundle = async (EvidenceWriteFailure>> => {- let encoded: string;+ let checked: EvidenceBundle;try {- encoded = serializeEvidenceBundle(bundle);+ checked = parseEvidenceBundle(bundle);} catch (cause: unknown) {return err(new EvidenceIntegrityError("Evidence bundle validation failed", {@@ -70,5 +73,9 @@ export const writeEvidenceBundle = async (}),);}- return writeTextFile(encoded, path, overwrite);+ return writeTextParts(+ bufferedJsonParts(canonicalJsonParts(checked)),+ path,+ overwrite,+ );};diff --git a/src/application/JsonFiles.ts b/src/application/JsonFiles.tsindex 4fea078a8..079d2c9d1 100644--- a/src/application/JsonFiles.ts+++ b/src/application/JsonFiles.ts@@ -1,8 +1,15 @@-import { link, lstat, mkdtemp, readFile, realpath, rm } from "node:fs/promises";+import {+ link,+ lstat,+ mkdtemp,+ open,+ readFile,+ realpath,+ rename,+ rm,+} from "node:fs/promises";import { basename, dirname, resolve } from "node:path";-import writeFileAtomic from "write-file-atomic";-import { EvidenceFileError } from "../domain/evidenceErrors.js";import { err, ok, type Result } from "../domain/result.js";@@ -52,8 +59,16 @@ export const writeTextFile = async (overwrite: boolean,): Promise<Result<{ readonly path: string; readonly bytes: number }, EvidenceFileError>+> => writeTextParts([encoded], path, overwrite);++/** Publish complete streamed text atomically, keeping only one encoded part in memory. */+export const writeTextParts = async (+ parts: Iterable<string>,+ path: string,+ overwrite: boolean,+): Promise<+ Result<{ readonly path: string; readonly bytes: number }, EvidenceFileError>> => {- const bytes = Buffer.byteLength(encoded, "utf8");const requestedPath = resolve(path);try {const canonicalParent = await realpath(dirname(requestedPath));@@ -72,13 +87,7 @@ export const writeTextFile = async (new EvidenceFileError("write", "not-file", { path: requestedPath }),);}- if (overwrite)- await writeFileAtomic(destination, encoded, {- encoding: "utf8",- mode: 0o600,- fsync: true,- });- else await publishNewFile(destination, encoded);+ const bytes = await publishFile(destination, parts, overwrite);return ok({ path: requestedPath, bytes });} catch (cause: unknown) {if (!overwrite && fileErrorCode(cause) === "EEXIST")@@ -103,22 +112,31 @@ const missingOrIo = (cause: unknown): "missing" | "io" => {return code === "ENOENT" || code === "ENOTDIR" ? "missing" : "io";};-const publishNewFile = async (+const publishFile = async (destination: string,- encoded: string,-): Promise<void> => {+ parts: Iterable<string>,+ overwrite: boolean,+): Promise<number> => {const stagingDirectory = await mkdtemp(resolve(dirname(destination), ".rea-write-"),);try {const staged = resolve(stagingDirectory, "content");- await writeFileAtomic(staged, encoded, {- encoding: "utf8",- mode: 0o600,- fsync: true,- });+ const file = await open(staged, "wx", 0o600);+ let bytes = 0;+ try {+ for (const part of parts) {+ await file.writeFile(part, { encoding: "utf8" });+ bytes += Buffer.byteLength(part, "utf8");+ }+ await file.sync();+ } finally {+ await file.close();+ }+ if (overwrite) await rename(staged, destination);// A hard link publishes complete bytes atomically and cannot replace an existing name.- await link(staged, destination);+ else await link(staged, destination);+ return bytes;} finally {await rm(stagingDirectory, { recursive: true, force: true });}diff --git a/src/application/binary/BinarySessionRecords.ts b/src/application/binary/BinarySessionRecords.tsindex 581f45b84..ecde344f6 100644--- a/src/application/binary/BinarySessionRecords.ts+++ b/src/application/binary/BinarySessionRecords.ts@@ -69,10 +69,20 @@ export abstract class BinarySessionRecords {return this.#records.evidenceById(evidenceId);}+ /** Borrow immutable investigation Evidence without copying a complete graph. */+ evidenceForAnalysis(evidenceId: string): Evidence | undefined {+ return this.#records.evidenceForAnalysis(evidenceId);+ }+exportEvidenceBundle(): EvidenceBundle {return this.#records.exportEvidenceBundle();}+ /** Borrow a sealed bundle for complete serialization without cloning retained graphs. */+ evidenceBundleForSerialization(): EvidenceBundle {+ return this.#records.evidenceBundleForSerialization();+ }+importEvidenceBundle(bundle: unknown,): Result<number, EvidenceIntegrityError> {diff --git a/src/application/investigation/EvidenceLedger.test.ts b/src/application/investigation/EvidenceLedger.test.tsindex 2eeb94616..c65c5e181 100644--- a/src/application/investigation/EvidenceLedger.test.ts+++ b/src/application/investigation/EvidenceLedger.test.ts@@ -116,6 +116,36 @@ describe("evidence ledger recording", () => {ledger.clear();expect(ledger.export().records).toEqual([]);});++ it("protects borrowed snapshots while preserving detached mutable public reads", () => {+ const evidence = createEvidence(TARGET, PROVIDER, {+ operation: "health",+ parameters: {},+ result: { nested: { value: "original" } },+ });+ const ledger = new EvidenceLedger();+ expect(ledger.record(evidence).ok).toBe(true);+ const borrowed = ledger.forAnalysis(evidence.evidence_id);+ if (borrowed === undefined) throw new Error("Missing recorded Evidence");+ expect(Object.isFrozen(borrowed)).toBe(true);+ expect(Object.isFrozen(borrowed.normalized_result)).toBe(true);+ expect(Reflect.set(borrowed, "operation", "forged")).toBe(false);+ expect(ledger.forAnalysis(evidence.evidence_id)).toBe(borrowed);+ expect(ledger.record(borrowed)).toEqual({ ok: true, value: "duplicate" });+ const detached = ledger.get(evidence.evidence_id);+ if (detached === undefined) throw new Error("Missing detached Evidence");+ expect(Reflect.set(detached, "operation", "forged")).toBe(true);+ expect(ledger.record(detached).ok).toBe(false);+ expect(ledger.forAnalysis(evidence.evidence_id)).toBe(borrowed);+ const snapshot = ledger.forSerialization();+ expect(snapshot).toEqual(ledger.export());+ expect(snapshot.records[0]).toBe(borrowed);+ expect(Object.isFrozen(snapshot.records)).toBe(true);+ ledger.clear();+ expect(ledger.forAnalysis(evidence.evidence_id)).toBeUndefined();+ expect(ledger.forSerialization().records).toEqual([]);+ expect(snapshot.records).toEqual([evidence]);+ });});describe("evidence ledger metadata imports", () => {diff --git a/src/application/investigation/EvidenceLedger.ts b/src/application/investigation/EvidenceLedger.tsindex 60fcc0ebd..6a2900c6f 100644--- a/src/application/investigation/EvidenceLedger.ts+++ b/src/application/investigation/EvidenceLedger.ts@@ -2,6 +2,7 @@ import canonicalize from "canonicalize";import {createEvidenceBundle,+ createImmutableEvidenceBundle,describeEvidenceBundleFailure,parseEvidenceBundle,validateResidualUnknownAddition,@@ -9,7 +10,11 @@ import {} from "../../domain/evidenceBundle.js";import { EvidenceIntegrityError } from "../../domain/evidenceErrors.js";import { UnknownRegistryError } from "../../domain/unknownRegistryError.js";-import { parseEvidence, type Evidence } from "../../domain/evidence.js";+import {+ immutableEvidence,+ parseEvidence,+ type Evidence,+} from "../../domain/evidence.js";import {createResidualUnknown,updateResidualUnknown,@@ -42,7 +47,7 @@ export class EvidenceLedger {record(input: Evidence): RecordResult {let evidence: Evidence;try {- evidence = parseEvidence(input);+ evidence = immutableEvidence(input);} catch (cause: unknown) {return err(new EvidenceIntegrityError("Evidence record validation failed", {@@ -52,6 +57,10 @@ export class EvidenceLedger {}const existing = this.#records.get(evidence.evidence_id);if (existing !== undefined) {+ // A borrowed record is already authenticated and deeply immutable. Its+ // identity cannot change between reads, so comparing document-sized+ // canonical strings again would add no integrity check.+ if (existing === evidence) return ok("duplicate");return recordsAgree(existing, evidence)? ok("duplicate"): err(new EvidenceIntegrityError("Conflicting evidence record"));@@ -97,8 +106,9 @@ export class EvidenceLedger {additions.set(evidence.evidence_id, evidence);}for (const [id, evidence] of replacements)- this.#records.set(id, evidence);- for (const [id, evidence] of additions) this.#records.set(id, evidence);+ this.#records.set(id, immutableEvidence(evidence));+ for (const [id, evidence] of additions)+ this.#records.set(id, immutableEvidence(evidence));return ok({recordsAdded: additions.size,unknownsAdded: 0,@@ -165,6 +175,14 @@ export class EvidenceLedger {);}+ /** Borrow a sealed canonical bundle for serialization without copying its records. */+ forSerialization(): EvidenceBundle {+ return createImmutableEvidenceBundle(+ [...this.#records.values()],+ [...this.#unknownRevisions.values()],+ );+ }+/** Check whether one immutable Evidence ID is present in this ledger. */has(evidenceId: string): boolean {return this.#records.has(evidenceId);@@ -176,6 +194,11 @@ export class EvidenceLedger {return evidence === undefined ? undefined : structuredClone(evidence);}+ /** Borrow authenticated immutable Evidence for read-only analysis without a full clone. */+ forAnalysis(evidenceId: string): Evidence | undefined {+ return this.#records.get(evidenceId);+ }+/** Create one approved unknown and atomically append its mutation evidence. */recordUnknown(input: RecordUnknownInput,@@ -380,7 +403,8 @@ export class EvidenceLedger {} catch (cause: unknown) {return err(new UnknownRegistryError("integrity", { cause }));}- for (const [id, evidence] of additions) this.#records.set(id, evidence);+ for (const [id, evidence] of additions)+ this.#records.set(id, immutableEvidence(evidence));if (unknown !== undefined && unknownKey !== undefined) {this.#unknownRevisions.set(unknownKey, unknown);this.#unknownHeads.set(unknown.unknown_id, unknown);@@ -407,7 +431,8 @@ export class EvidenceLedger {unknowns: ReadonlyMap<string, ResidualUnknown>,): void {this.#records.clear();- for (const [id, evidence] of records) this.#records.set(id, evidence);+ for (const [id, evidence] of records)+ this.#records.set(id, immutableEvidence(evidence));this.#unknownRevisions.clear();this.#unknownHeads.clear();for (const [key, unknown] of unknowns) {diff --git a/src/application/investigation/InvestigationRecordPort.ts b/src/application/investigation/InvestigationRecordPort.tsindex a99542b5c..aacf8fa26 100644--- a/src/application/investigation/InvestigationRecordPort.ts+++ b/src/application/investigation/InvestigationRecordPort.ts@@ -15,6 +15,10 @@ import type { Result } from "../../domain/result.js";export interface EvidenceReader {hasEvidence(evidenceId: string): boolean;evidenceById(evidenceId: string): Evidence | undefined;+ /** Optional immutable analysis read; older adapters can keep detached reads. */+ evidenceForAnalysis?(evidenceId: string): Evidence | undefined;+ /** Optional immutable bundle snapshot for complete serialization without graph copies. */+ evidenceBundleForSerialization?(): EvidenceBundle;exportEvidenceBundle(): EvidenceBundle;}diff --git a/src/application/investigation/InvestigationRecords.ts b/src/application/investigation/InvestigationRecords.tsindex 9b612f11c..b8a1dea99 100644--- a/src/application/investigation/InvestigationRecords.ts+++ b/src/application/investigation/InvestigationRecords.ts@@ -51,11 +51,21 @@ export class InvestigationRecordsreturn this.#evidence.get(evidenceId);}+ /** Borrow an immutable authenticated record for a read-only application workflow. */+ evidenceForAnalysis(evidenceId: string): Evidence | undefined {+ return this.#evidence.forAnalysis(evidenceId);+ }+/** Export a detached deterministic bundle of Evidence and Unknown revisions. */exportEvidenceBundle(): EvidenceBundle {return this.#evidence.export();}+ /** Borrow a sealed bundle snapshot for complete JSON serialization. */+ evidenceBundleForSerialization(): EvidenceBundle {+ return this.#evidence.forSerialization();+ }+/** Atomically merge a bundle and report changes for the owner's post-commit observers. */mergeEvidenceBundle(bundle: unknown,diff --git a/src/application/javascript/JavaScriptApplicationEvidence.ts b/src/application/javascript/JavaScriptApplicationEvidence.tsindex c291f7673..53d7087e0 100644--- a/src/application/javascript/JavaScriptApplicationEvidence.ts+++ b/src/application/javascript/JavaScriptApplicationEvidence.ts@@ -8,6 +8,18 @@ import type {JavaScriptApplicationAnalysisResult,} from "../../domain/javascript/javascriptApplicationAnalysis.js";import { JAVASCRIPT_APPLICATION_PROVIDER } from "../InvestigationProviders.js";+import { freezeJsonSnapshot } from "../../domain/immutableJson.js";+import { rememberOwnedApplicationGraphEvidence } from "./JavaScriptApplicationEvidenceGraph.js";++/** Transfer an already validated, application-owned result into immutable analysis Evidence. */+export const createOwnedJavaScriptApplicationEvidence = (+ input: AnalyzeJavaScriptApplicationInput,+ result: JavaScriptApplicationAnalysisResult,+): Evidence =>+ rememberOwnedApplicationGraphEvidence(+ createJavaScriptApplicationEvidence(input, freezeJsonSnapshot(result)),+ result,+ );/** Create Evidence for one deterministic local JavaScript application graph. */export const createJavaScriptApplicationEvidence = (diff --git a/src/application/javascript/JavaScriptApplicationEvidenceGraph.test.ts b/src/application/javascript/JavaScriptApplicationEvidenceGraph.test.tsnew file mode 100644index 000000000..1db99dcbd--- /dev/null+++ b/src/application/javascript/JavaScriptApplicationEvidenceGraph.test.ts@@ -0,0 +1,47 @@+import { describe, expect, it } from "vitest";++import { JAVASCRIPT_APPLICATION_EVIDENCE_EXAMPLE } from "../../contracts/javascript/javascriptRuntimeReconciliationExample.js";+import { parseEvidence } from "../../domain/evidence.js";+import {+ analyzeJavaScriptApplicationInputSchema,+ javascriptApplicationAnalysisResultSchema,+} from "../../domain/javascript/javascriptApplicationAnalysis.js";+import {+ createJavaScriptApplicationEvidence,+ createOwnedJavaScriptApplicationEvidence,+} from "./JavaScriptApplicationEvidence.js";+import {+ parseApplicationGraphEvidence,+ rememberOwnedApplicationGraphEvidence,+} from "./JavaScriptApplicationEvidenceGraph.js";++describe("owned application graph Evidence", () => {+ it("reuses the exact authenticated graph and preserves ordinary wire identity", () => {+ const result = javascriptApplicationAnalysisResultSchema.parse(+ JAVASCRIPT_APPLICATION_EVIDENCE_EXAMPLE.normalized_result,+ );+ const input = analyzeJavaScriptApplicationInputSchema.parse({+ input_path: result.input_path,+ ...JAVASCRIPT_APPLICATION_EVIDENCE_EXAMPLE.parameters,+ });+ const ordinary = createJavaScriptApplicationEvidence(input, result);+ const owned = createOwnedJavaScriptApplicationEvidence(input, result);+ expect(owned.evidence_id).toBe(ordinary.evidence_id);+ expect(JSON.stringify(owned)).toBe(JSON.stringify(ordinary));+ const parsed = parseApplicationGraphEvidence(owned);+ expect(parsed.evidence).toBe(owned);+ expect(parsed.graph).toBe(result.graph);+ expect(parsed.semanticGraph).toBe(result.semantic_graph);+ expect(Object.isFrozen(parsed.graph.nodes)).toBe(true);+ expect(parseApplicationGraphEvidence(owned)).toBe(parsed);+ const wire: unknown = JSON.parse(JSON.stringify(owned));+ expect(parseApplicationGraphEvidence(wire)).toEqual(parsed);+ expect(parseApplicationGraphEvidence(wire).graph).not.toBe(parsed.graph);+ expect(() =>+ rememberOwnedApplicationGraphEvidence(ordinary, result),+ ).toThrow("exact validated immutable result");+ const tampered = { ...owned, normalized_result: {} };+ expect(() => parseEvidence(Object.freeze(tampered))).toThrow();+ expect(() => parseApplicationGraphEvidence(tampered)).toThrow();+ });+});diff --git a/src/application/javascript/JavaScriptApplicationEvidenceGraph.ts b/src/application/javascript/JavaScriptApplicationEvidenceGraph.tsindex 8d9106359..459c226ac 100644--- a/src/application/javascript/JavaScriptApplicationEvidenceGraph.ts+++ b/src/application/javascript/JavaScriptApplicationEvidenceGraph.ts@@ -3,7 +3,11 @@ import {JAVASCRIPT_RUNTIME_RECONCILIATION_PROVIDER,MANAGED_WORKFLOW_PROVIDER,} from "../InvestigationProviders.js";-import { parseEvidence, type Evidence } from "../../domain/evidence.js";+import {+ isImmutableEvidence,+ parseEvidence,+ type Evidence,+} from "../../domain/evidence.js";import {analyzeJavaScriptApplicationInputSchema,javascriptApplicationAnalysisResultSchema,@@ -26,11 +30,39 @@ export interface ApplicationGraphEvidenceSource {readonly semanticGraph: JavaScriptSemanticGraph | null;}+const ownedApplicationSources = new WeakMap<+ Evidence,+ ApplicationGraphEvidenceSource+>();++/** Retain the producer-validated meaning of its exact immutable result snapshot. */+export const rememberOwnedApplicationGraphEvidence = (+ evidence: Evidence,+ result: JavaScriptApplicationAnalysisResult,+): Evidence => {+ if (+ !isImmutableEvidence(evidence) ||+ evidence.normalized_result !== result ||+ evidence.operation !== "analyze_javascript_application" ||+ !providerMatches(evidence, JAVASCRIPT_APPLICATION_PROVIDER)+ )+ throw new TypeError(+ "Owned application Evidence must bind its exact validated immutable result",+ );+ ownedApplicationSources.set(+ evidence,+ Object.freeze(staticApplicationSourceForResult(evidence, result)),+ );+ return evidence;+};+/** Parse and authenticate one REA-produced JavaScript Application Graph Evidence. */export const parseApplicationGraphEvidence = (input: unknown,): ApplicationGraphEvidenceSource => {const evidence = parseEvidence(input);+ const owned = ownedApplicationSources.get(evidence);+ if (owned !== undefined) return owned;if (evidence.operation === "analyze_javascript_application" &&evidence.predicate_type === "rea.javascript-application-analysis" &&@@ -56,6 +88,16 @@ export const parseApplicationGraphEvidence = (const staticApplicationSource = (evidence: Evidence,+): ApplicationGraphEvidenceSource => {+ const result = javascriptApplicationAnalysisResultSchema.parse(+ evidence.normalized_result,+ );+ return staticApplicationSourceForResult(evidence, result);+};++const staticApplicationSourceForResult = (+ evidence: Evidence,+ result: JavaScriptApplicationAnalysisResult,): ApplicationGraphEvidenceSource => {if (evidence.authority !== "shipped-artifact" ||@@ -64,9 +106,6 @@ const staticApplicationSource = (throw new TypeError("JavaScript application Evidence authority or confidence is invalid",);- const result = javascriptApplicationAnalysisResultSchema.parse(- evidence.normalized_result,- );if (evidence.predicate_type !== "rea.javascript-application-analysis")throw new TypeError("JavaScript application Evidence predicate does not match its result shape",diff --git a/src/application/javascript/JavaScriptApplicationService.ts b/src/application/javascript/JavaScriptApplicationService.tsindex b1b180383..76583e476 100644--- a/src/application/javascript/JavaScriptApplicationService.ts+++ b/src/application/javascript/JavaScriptApplicationService.ts@@ -16,7 +16,7 @@ import { projectInputIssues } from "../../domain/inputIssueProjection.js";import { err, ok, type Result } from "../../domain/result.js";import { ProviderAdapterError } from "../../domain/providerAdapterError.js";import type { ExecutionOptions } from "../AnalysisProvider.js";-import { createJavaScriptApplicationEvidence } from "./JavaScriptApplicationEvidence.js";+import { createOwnedJavaScriptApplicationEvidence } from "./JavaScriptApplicationEvidence.js";import { reconstructJavaScriptArtifact } from "./JavaScriptArtifactReconstruction.js";import { JAVASCRIPT_APPLICATION_PROVIDER } from "../InvestigationProviders.js";@@ -77,7 +77,7 @@ export const analyzeJavaScriptApplicationValidated = async (total: 1,message: "Creating and hashing application analysis Evidence",});- const evidence = createJavaScriptApplicationEvidence(input, result);+ const evidence = createOwnedJavaScriptApplicationEvidence(input, result);await options.progress?.report({phase: "analyze_javascript_application",completed: 1,diff --git a/src/cli/jsonOutput.ts b/src/cli/jsonOutput.tsindex cc401ee32..93df9abd3 100644--- a/src/cli/jsonOutput.ts+++ b/src/cli/jsonOutput.ts@@ -1,5 +1,7 @@import type { Writable } from "node:stream";+import { bufferedJsonParts, jsonParts } from "../domain/jsonSerialization.js";+type JsonOutputFormat = "json" | "jsonl";/** Write ordinary JSON without constructing a document-sized string. */@@ -8,7 +10,7 @@ export const writeJsonOutput = async (destination: Writable,format: JsonOutputFormat = "json",): Promise<void> => {- for (const part of bufferedParts(documentParts(value, format)))+ for (const part of bufferedJsonParts(documentParts(value, format)))await writePart(destination, part);};@@ -39,115 +41,11 @@ function* documentParts(): Generator<string> {if (format === "jsonl" && Array.isArray(value)) {for (const item of value) {- yield* encodeValue(item, false, 0, new Set());+ yield* jsonParts(item);yield "\n";}return;}- yield* encodeValue(value, format === "json", 0, new Set());+ yield* jsonParts(value, format === "json");yield "\n";}--function* bufferedParts(parts: Iterable<string>): Generator<string> {- let buffer = "";- for (const part of parts) {- if (buffer.length + part.length > 64 * 1024 && buffer !== "") {- yield buffer;- buffer = "";- }- buffer += part;- }- if (buffer !== "") yield buffer;-}--function* encodeString(value: string): Generator<string> {- if (value.length <= 8192) {- yield JSON.stringify(value);- return;- }- yield '"';- for (let start = 0; start < value.length;) {- let end = Math.min(start + 8192, value.length);- const last = value.charCodeAt(end - 1);- const next = value.charCodeAt(end);- // Keep a surrogate pair in the same JSON.stringify and UTF-8 write.- if (- end < value.length &&- last >= 0xd800 &&- last <= 0xdbff &&- next >= 0xdc00 &&- next <= 0xdfff- )- end -= 1;- yield JSON.stringify(value.slice(start, end)).slice(1, -1);- start = end;- }- yield '"';-}--function* encodeValue(- value: unknown,- pretty: boolean,- depth: number,- ancestors: Set<object>,-): Generator<string> {- if (typeof value === "string") {- yield* encodeString(value);- return;- }- if (value === null || typeof value === "boolean") {- yield value === null ? "null" : String(value);- return;- }- if (typeof value === "number" && Number.isFinite(value)) {- yield String(value);- return;- }- if (typeof value !== "object" || value === null)- throw new TypeError("CLI JSON output requires ordinary JSON values");- if (ancestors.has(value))- throw new TypeError("CLI JSON output contains a circular reference");- if (- !Array.isArray(value) &&- Object.prototype.toString.call(value) !== "[object Object]"- )- throw new TypeError("CLI JSON output requires ordinary JSON objects");- ancestors.add(value);- try {- const array = Array.isArray(value);- const keys = array- ? undefined- : Object.keys(value).filter((key) => {- const item: unknown = Reflect.get(value, key);- // Incur's filter can select inherited methods. Match native JSON's- // omission of fields that have no JSON representation.- return (- item !== undefined &&- typeof item !== "function" &&- typeof item !== "symbol"- );- });- const count = array ? value.length : (keys?.length ?? 0);- yield array ? "[" : "{";- for (let index = 0; index < count; index += 1) {- if (index > 0) yield ",";- if (pretty) yield `\n${" ".repeat(depth + 1)}`;- let item: unknown;- if (array) {- item = value[index];- } else {- const key = keys?.[index];- if (key === undefined)- throw new TypeError("CLI JSON object changed during serialization");- yield* encodeString(key);- yield pretty ? ": " : ":";- item = Reflect.get(value, key);- }- yield* encodeValue(item, pretty, depth + 1, ancestors);- }- if (pretty && count > 0) yield `\n${" ".repeat(depth)}`;- yield array ? "]" : "}";- } finally {- ancestors.delete(value);- }-}diff --git a/src/config/environment.ts b/src/config/environment.tsindex e292f7f3f..aebcd5be5 100644--- a/src/config/environment.ts+++ b/src/config/environment.ts@@ -4,9 +4,11 @@ import { isAbsolute } from "node:path";import { ConfigurationError } from "../domain/configurationErrors.js";import { err, ok, type Result } from "../domain/result.js";import { analysisProviderSelectorSchema } from "../contracts/providerSelection.js";+import { mcpResponseBudgetSchema } from "./mcpResponseBudget.js";const environmentSchema = z.object({REA_ANALYSIS_PROVIDER: analysisProviderSelectorSchema.default("auto"),+ REA_MCP_MAX_RESPONSE_BYTES: mcpResponseBudgetSchema.optional(),REA_IDA_MCP_CONFIG: z.string().min(1)diff --git a/src/config/mcpResponseBudget.ts b/src/config/mcpResponseBudget.tsnew file mode 100644index 000000000..01d69db97--- /dev/null+++ b/src/config/mcpResponseBudget.ts@@ -0,0 +1,31 @@+import { z } from "zod";++import { ConfigurationError } from "../domain/configurationErrors.js";+import { err, ok, type Result } from "../domain/result.js";++// This override supports clients with larger frames. Keep the configuration+// parser independent of the SDK's eager server imports; conformance verifies+// this floor against the pinned SDK's actual default receive-buffer size.+const MINIMUM_RESPONSE_BYTES = 10 * 1024 * 1024;++/** Optional stdio response budget, including room for the protocol envelope. */+export const mcpResponseBudgetSchema = z+ .string()+ .regex(/^[1-9]\d*$/u)+ .transform(Number)+ .pipe(z.number().int().safe().min(MINIMUM_RESPONSE_BYTES));++/** Parse only the MCP-specific budget without loading unrelated provider settings. */+export const parseMcpResponseBudget = (+ value: string | undefined,+): Result<number | undefined, ConfigurationError> => {+ if (value === undefined) return ok(undefined);+ const parsed = mcpResponseBudgetSchema.safeParse(value);+ return parsed.success+ ? ok(parsed.data)+ : err(+ new ConfigurationError(+ `REA_MCP_MAX_RESPONSE_BYTES must be a decimal safe integer at least ${String(MINIMUM_RESPONSE_BYTES)} bytes, the default stdio receive-buffer size.`,+ ),+ );+};diff --git a/src/domain/analysisErrorCore.ts b/src/domain/analysisErrorCore.tsindex 03835a2b3..47f0e0867 100644--- a/src/domain/analysisErrorCore.ts+++ b/src/domain/analysisErrorCore.ts@@ -17,13 +17,13 @@ export class AnalysisUnsupportedTargetError extends AnalysisError {}}-/** Provider reported a resource failure, distinct from malformed input or unsupported coverage. */+/** An analysis or transport resource failure, distinct from malformed input or unsupported coverage. */export class AnalysisResourceConstraintError extends AnalysisError {readonly _tag = "AnalysisResourceConstraintError";constructor(readonly operation: string,- readonly resource: "memory" | "cpu" | "file-size",+ readonly resource: "memory" | "cpu" | "file-size" | "transport",readonly reason: string,readonly reportedLimits: Readonly<Record<string, JsonValue>> | null,options?: AnalysisErrorOptions,diff --git a/src/domain/analysisErrorPresentation.ts b/src/domain/analysisErrorPresentation.tsindex 76cd82b8f..f8684605a 100644--- a/src/domain/analysisErrorPresentation.ts+++ b/src/domain/analysisErrorPresentation.ts@@ -37,11 +37,13 @@ export const analysisErrorRemediationAction = (if (error instanceof AnalysisUnsupportedTargetError)return "Select a target supported by this operation or choose an operation supporting the reported target format.";if (error instanceof AnalysisResourceConstraintError)- return error.resource === "cpu"- ? "Review the reported worker CPU limits and observed signal. Retry with sufficient CPU time or a smaller artifact; REA retains tighter inherited limits."- : error.resource === "file-size"- ? "Review the reported worker file-size limits and write failure. Retry with a sufficient file-size allowance for the evidence reply; REA retains tighter inherited limits."- : "Review the reported worker memory limits and available host memory. Retry with sufficient memory or a smaller artifact; REA retains tighter inherited limits.";+ return error.resource === "transport"+ ? "Use the reported Evidence reference with a focused analysis tool when retained in this session, or export the session through export_evidence_bundle to a caller-selected path. Complete CLI JSON output is also available. The connection remains usable."+ : error.resource === "cpu"+ ? "Review the reported worker CPU limits and observed signal. Retry with sufficient CPU time or a smaller artifact; REA retains tighter inherited limits."+ : error.resource === "file-size"+ ? "Review the reported worker file-size limits and write failure. Retry with a sufficient file-size allowance for the evidence reply; REA retains tighter inherited limits."+ : "Review the reported worker memory limits and available host memory. Retry with sufficient memory or a smaller artifact; REA retains tighter inherited limits.";if (error instanceof HopperTimeoutError)return error.providerState === "busy"? "Check binary_session.analysis_activity, wait for the active Hopper request to finish, then retry."diff --git a/src/domain/analysisErrorProjection.test.ts b/src/domain/analysisErrorProjection.test.tsindex 392b97966..3bf294386 100644--- a/src/domain/analysisErrorProjection.test.ts+++ b/src/domain/analysisErrorProjection.test.ts@@ -62,6 +62,7 @@ it.each([["cpu", { cpu_seconds: 1 }],["file-size", null],["file-size", { file_size_bytes: 1024 }],+ ["transport", { result_budget_bytes: 10485760 }],] as const)("projects reported %s constraints with observed or unknown limits: %j",(resource, limits) => {@@ -89,9 +90,11 @@ it.each([expect(projected.remediation.action).toContain(resource === "cpu"? "CPU"- : resource === "file-size"- ? "file-size"- : "memory",+ : resource === "transport"+ ? "Evidence reference"+ : resource === "file-size"+ ? "file-size"+ : "memory",);expect(projected.remediation.action).not.toContain("doctor");expect(analysisErrorProjectionSchema.safeParse(projected).success).toBe(diff --git a/src/domain/evidence.test.ts b/src/domain/evidence.test.tsindex 95dabcc1a..85bdb33aa 100644--- a/src/domain/evidence.test.ts+++ b/src/domain/evidence.test.ts@@ -3,9 +3,15 @@ import { describe, expect } from "vitest";import { createAnalysisProfile } from "./analysisProfile.js";import type { BinaryTarget } from "./binaryTarget.js";-import { createEvidence, evidenceSchema, parseEvidence } from "./evidence.js";-import { MAX_JSON_DEPTH } from "./jsonValue.js";+import {+ createEvidence,+ evidenceRecordSchema,+ evidenceSchema,+ parseEvidence,+} from "./evidence.js";+import { MAX_JSON_DEPTH, type JsonValue } from "./jsonValue.js";import { createEvidenceBundle } from "./evidenceBundle.js";+import { freezeJsonSnapshot } from "./immutableJson.js";const TARGET: BinaryTarget = {path: "/tmp/fixture",@@ -18,6 +24,90 @@ const TARGET: BinaryTarget = {const PROVIDER = { id: "fixture", name: "Fixture provider", version: "1" };const PROFILE = createAnalysisProfile(PROVIDER, { loader: "default" });+it("preserves identity and bytes when reusing an owned immutable result", () => {+ const value = { nested: { values: ["observed", 1] } };+ const mutable = createEvidence(TARGET, PROVIDER, {+ operation: "inspect",+ parameters: {},+ result: value,+ });+ const frozen = createEvidence(TARGET, PROVIDER, {+ operation: "inspect",+ parameters: {},+ result: freezeJsonSnapshot(value),+ });+ expect(JSON.stringify(frozen)).toBe(JSON.stringify(mutable));+ expect(frozen.normalized_result).toBe(value);+ expect(Object.isFrozen(frozen)).toBe(true);+ expect(parseEvidence(frozen)).toEqual(mutable);+ const wire: unknown = JSON.parse(JSON.stringify(frozen));+ expect(parseEvidence(wire)).toEqual(mutable);+ expect(() =>+ parseEvidence({ ...frozen, normalized_result: { changed: true } }),+ ).toThrow("semantic identifier");+});++it("applies the JSON depth boundary to owned immutable results", () => {+ let result: JsonValue = 1;+ for (let index = 0; index <= MAX_JSON_DEPTH; index += 1)+ result = { nested: result };+ const observe = () =>+ createEvidence(TARGET, PROVIDER, {+ operation: "inspect",+ parameters: {},+ result,+ });+ expect(observe).toThrow("maximum nesting depth");+ freezeJsonSnapshot(result);+ expect(observe).toThrow("maximum nesting depth");+});++it("preserves prototype-named own members when reusing an owned result", () => {+ const result = { ["__proto__"]: { preserved: 7 }, constructor: "ordinary" };+ const observation = { operation: "inspect", parameters: {}, result };+ const ordinary = createEvidence(TARGET, PROVIDER, observation);+ const owned = createEvidence(TARGET, PROVIDER, {+ ...observation,+ result: freezeJsonSnapshot(result),+ });+ expect(owned.normalized_result).toBe(result);+ expect(owned).toEqual(ordinary);+ expect(parseEvidence(JSON.parse(JSON.stringify(owned)))).toEqual(owned);+ expect(Object.getPrototypeOf(owned.normalized_result)).toBe(Object.prototype);+ expect(Reflect.get(Object.prototype, "preserved")).toBeUndefined();+});++it("preserves producer envelope admission and profile validation", () => {+ const legacy = createEvidence(TARGET, PROVIDER, {+ operation: "inspect",+ parameters: {},+ result: { observed: [1, 2, 3] },+ });+ const profiled = createEvidence(TARGET, PROVIDER, {+ operation: "inspect",+ parameters: {},+ result: { observed: [1, 2, 3] },+ analysisProfile: PROFILE,+ });+ const candidates: unknown[] = [+ legacy,+ profiled,+ { ...legacy, analysis_profile: undefined },+ { ...legacy, analysis_profile: null },+ {+ ...profiled,+ analysis_profile: { ...PROFILE, provider: { ...PROVIDER, id: "other" } },+ },+ { ...legacy, unexpected: true },+ ];+ for (const candidate of candidates) {+ const canonical = evidenceRecordSchema.safeParse(candidate);+ if (canonical.success)+ expect(parseEvidence(candidate)).toEqual(canonical.data);+ else expect(() => parseEvidence(candidate)).toThrow();+ }+});+it("snapshots caller-owned payloads before deriving their identity", () => {const result = { nested: { values: ["observed"] } };const rawResult = { entries: [{ value: "raw" }] };diff --git a/src/domain/evidence.ts b/src/domain/evidence.tsindex a634d0c3b..8c6b0fb01 100644--- a/src/domain/evidence.ts+++ b/src/domain/evidence.ts@@ -10,8 +10,13 @@ import type { BinaryTarget } from "./binaryTarget.js";import {jsonObjectSchema,jsonValueSchema,+ jsonValueValidationIssue,type JsonValue,} from "./jsonValue.js";+import {+ freezeJsonSnapshot,+ isImmutableJsonSnapshot,+} from "./immutableJson.js";import { digestSchema } from "./../domain/digests.js";import { prefixedDigestSchema } from "./../domain/digests.js";@@ -144,6 +149,14 @@ export const evidenceRecordSchema = z.union([]);export type Evidence = z.infer<typeof evidenceRecordSchema>;+const immutableEvidenceSnapshots = new WeakMap<object, Evidence>();+const immutableResultSchema = z+ .custom<JsonValue>(isImmutableJsonSnapshot)+ .superRefine((value, context) => {+ const issue = jsonValueValidationIssue(value);+ if (issue !== undefined)+ context.addIssue({ code: "custom", message: issue });+ });export type EvidenceLocation = z.infer<typeof evidenceLocationSchema>;/** Minimal immutable local artifact identity accepted by Evidence. */@@ -216,7 +229,19 @@ const computeEvidenceId = (evidence: EvidenceWithoutId): string =>/** Parse evidence and reject a syntactically valid but tampered semantic ID. */export const parseEvidence = (input: unknown): Evidence => {- const evidence = evidenceRecordSchema.parse(input);+ const immutable =+ typeof input === "object" && input !== null+ ? immutableEvidenceSnapshots.get(input)+ : undefined;+ if (immutable !== undefined) return immutable;+ // Select the producer's envelope before traversing its payload. A legacy+ // record cannot satisfy the required-profile branch, whose failed parse+ // would otherwise clone the entire normalized result before trying legacy.+ const schema =+ typeof input === "object" && input !== null && "analysis_profile" in input+ ? profiledEvidenceSchema+ : evidenceBaseSchema;+ const evidence = schema.parse(input);const { evidence_id: evidenceId, ...withoutId } = evidence;if (computeEvidenceId(withoutId) !== evidenceId)throw new TypeError(@@ -225,6 +250,20 @@ export const parseEvidence = (input: unknown): Evidence => {return evidence;};+/** Authenticate and seal a ledger-owned snapshot; external mutable values are copied first. */+export const immutableEvidence = (input: unknown): Evidence =>+ rememberImmutableEvidence(parseEvidence(input));++/** Recognize authenticated Evidence whose complete reachable JSON data is immutable. */+export const isImmutableEvidence = (evidence: Evidence): boolean =>+ immutableEvidenceSnapshots.has(evidence);++const rememberImmutableEvidence = (evidence: Evidence): Evidence => {+ freezeJsonSnapshot(evidence);+ immutableEvidenceSnapshots.set(evidence, evidence);+ return evidence;+};+/** Build deterministic Evidence from an immutable artifact subject. */export const createEvidence = (target: EvidenceSubjectTarget | BinaryTarget | undefined,@@ -285,7 +324,14 @@ export const createEvidence = (observation.analysisProfile === undefined? evidenceBaseSchema: profiledEvidenceSchema;- const normalized = schema.parse({+ const sharedResult =+ typeof observation.result === "object" &&+ observation.result !== null &&+ isImmutableJsonSnapshot(observation.result);+ const selectedSchema = sharedResult+ ? schema.safeExtend({ normalized_result: immutableResultSchema })+ : schema;+ const normalized = selectedSchema.parse({...semantic,evidence_id: `ev_${"0".repeat(64)}`,subject,@@ -293,8 +339,9 @@ export const createEvidence = (// The envelope has already been parsed into an independent snapshot. Only// its derived identifier changes here; parsing again clones the full payload// and recomputes the same digest while the previous snapshot is still live.- return {+ const evidence = {...normalized,evidence_id: computeEvidenceId(normalized),};+ return sharedResult ? rememberImmutableEvidence(evidence) : evidence;};diff --git a/src/domain/evidenceBundle.test.ts b/src/domain/evidenceBundle.test.tsindex 00e5f7b4f..ff6fc38e2 100644--- a/src/domain/evidenceBundle.test.ts+++ b/src/domain/evidenceBundle.test.ts@@ -3,6 +3,7 @@ import { describe, expect, it } from "vitest";import { createEvidence } from "./evidence.js";import {createEvidenceBundle,+ createImmutableEvidenceBundle,evidenceBundleForTarget,parseEvidenceBundle,} from "./evidenceBundle.js";@@ -118,3 +119,26 @@ describe("evidenceBundleForTarget", () => {);});});++describe("immutable serialization bundles", () => {+ it("authenticates sealed records while revalidating detached and malformed input", () => {+ const evidence = createEvidence(undefined, provider, {+ operation: "health",+ parameters: {},+ result: { nested: [true] },+ });+ const bundle = createImmutableEvidenceBundle([evidence]);+ expect(parseEvidenceBundle(bundle)).toBe(bundle);+ expect(Object.isFrozen(bundle.records[0]?.normalized_result)).toBe(true);+ const detached: unknown = JSON.parse(JSON.stringify(bundle));+ expect(parseEvidenceBundle(detached)).toEqual(bundle);+ expect(parseEvidenceBundle(detached)).not.toBe(bundle);+ const tampered = {+ ...bundle,+ records: [{ ...evidence, normalized_result: false }],+ };+ expect(() => parseEvidenceBundle(Object.freeze(tampered))).toThrow();+ expect(() => createImmutableEvidenceBundle(tampered.records)).toThrow();+ expect(() => createImmutableEvidenceBundle([evidence, evidence])).toThrow();+ });+});diff --git a/src/domain/evidenceBundle.ts b/src/domain/evidenceBundle.tsindex 807781b66..e6f3a6806 100644--- a/src/domain/evidenceBundle.ts+++ b/src/domain/evidenceBundle.ts@@ -4,6 +4,7 @@ import canonicalize from "canonicalize";import {evidenceEnvelopeSchema,evidenceRecordSchema,+ immutableEvidence,parseEvidence,providerSchema,type Evidence,@@ -12,6 +13,7 @@ import {residualUnknownSchema,type ResidualUnknown,} from "./residualUnknown.js";+import { freezeJsonSnapshot } from "./immutableJson.js";const artifactManifestSchema = evidenceEnvelopeSchema.shape.subject.unwrap()@@ -44,6 +46,29 @@ export const evidenceBundleSchema = z.object({});export type EvidenceBundle = z.infer<typeof evidenceBundleSchema>;+const immutableBundles = new WeakMap<object, EvidenceBundle>();++/** Build and authenticate a sealed bundle while reusing immutable Evidence records. */+export const createImmutableEvidenceBundle = (+ records: readonly Evidence[],+ unknowns: readonly ResidualUnknown[] = [],+): EvidenceBundle => {+ const checkedRecords = records.map(immutableEvidence);+ if (+ new Set(checkedRecords.map(({ evidence_id }) => evidence_id)).size !==+ checkedRecords.length+ )+ throw new TypeError("Evidence bundle contains duplicate record IDs");+ const checkedUnknowns = unknowns.map((unknown) =>+ residualUnknownSchema.parse(unknown),+ );+ validateUnknownGraph(checkedUnknowns, checkedRecords);+ const bundle = freezeJsonSnapshot(+ createEvidenceBundle(checkedRecords, checkedUnknowns),+ );+ immutableBundles.set(bundle, bundle);+ return bundle;+};/** Project records into a deterministic bundle whose order has no semantics. */export const createEvidenceBundle = (@@ -212,6 +237,10 @@ export const describeValidationFailure = (cause: unknown): string => {/** Parse records, verify semantic IDs, and reject inconsistent manifests. */export const parseEvidenceBundle = (input: unknown): EvidenceBundle => {+ if (typeof input === "object" && input !== null) {+ const owned = immutableBundles.get(input);+ if (owned !== undefined) return owned;+ }const parsed = evidenceBundleSchema.parse(input);const recordIds = parsed.records.map(({ evidence_id: id }) => id);if (new Set(recordIds).size !== recordIds.length)diff --git a/src/domain/immutableJson.test.ts b/src/domain/immutableJson.test.tsnew file mode 100644index 000000000..16e524a96--- /dev/null+++ b/src/domain/immutableJson.test.ts@@ -0,0 +1,64 @@+import { describe, expect, it } from "vitest";++import type { JsonValue } from "./jsonValue.js";+import {+ freezeJsonSnapshot,+ isImmutableJsonSnapshot,+} from "./immutableJson.js";++describe("owned immutable JSON snapshots", () => {+ it("seals reachable data and preserves repeated references", () => {+ const shared = { values: [1, "observed"] };+ const value = { left: shared, right: shared };+ const encoded = JSON.stringify(value);+ expect(freezeJsonSnapshot(value)).toBe(value);+ expect(value.left).toBe(value.right);+ expect(Object.isFrozen(value)).toBe(true);+ expect(Object.isFrozen(shared.values)).toBe(true);+ expect(Reflect.set(shared.values, 0, 9)).toBe(false);+ expect(JSON.stringify(value)).toBe(encoded);+ expect(isImmutableJsonSnapshot(value)).toBe(true);+ });++ it("does not mistake a shallow freeze for validated immutable data", () => {+ const value = Object.freeze({ nested: { value: 1 } });+ expect(isImmutableJsonSnapshot(value)).toBe(false);+ freezeJsonSnapshot(value);+ expect(Object.isFrozen(value.nested)).toBe(true);+ expect(isImmutableJsonSnapshot(value)).toBe(true);+ });++ it("composes sealed roots without changing the nested data or authenticating a shallow freeze", () => {+ const nested = freezeJsonSnapshot({ values: [1, "observed"] });+ const outer = freezeJsonSnapshot({ nested });+ expect(outer.nested).toBe(nested);+ expect(Object.isFrozen(outer)).toBe(true);+ expect(Object.isFrozen(nested.values)).toBe(true);+ expect(isImmutableJsonSnapshot(outer)).toBe(true);+ expect(isImmutableJsonSnapshot(nested)).toBe(true);+ const unowned = Object.freeze({ nested: { value: 1 } });+ expect(isImmutableJsonSnapshot(unowned)).toBe(false);+ });++ it("rejects cycles without registering or partially freezing the snapshot", () => {+ const value: Record<string, JsonValue> = {};+ value.self = value;+ expect(() => freezeJsonSnapshot(value)).toThrow("circular");+ expect(isImmutableJsonSnapshot(value)).toBe(false);+ expect(Object.isFrozen(value)).toBe(false);+ });++ it("rejects mutable accessor behavior and sparse arrays", () => {+ const accessor = {+ get value() {+ return 1;+ },+ };+ expect(() => freezeJsonSnapshot(accessor)).toThrow("accessors");+ expect(isImmutableJsonSnapshot(accessor)).toBe(false);+ expect(() => freezeJsonSnapshot(new Array<number>(2))).toThrow("sparse");+ expect(() => freezeJsonSnapshot({ number: Number.NaN })).toThrow(+ "JSON values",+ );+ });+});diff --git a/src/domain/immutableJson.ts b/src/domain/immutableJson.tsnew file mode 100644index 000000000..4c0579e71--- /dev/null+++ b/src/domain/immutableJson.ts@@ -0,0 +1,74 @@+import type { JsonValue } from "./jsonValue.js";++const immutableSnapshots = new WeakSet<object>();++/** Recognize an owned JSON snapshot sealed by this module, or an immutable scalar. */+export const isImmutableJsonSnapshot = (value: unknown): value is JsonValue =>+ value === null ||+ typeof value === "string" ||+ typeof value === "boolean" ||+ (typeof value === "number" && Number.isFinite(value)) ||+ (typeof value === "object" && immutableSnapshots.has(value));++/** Seal an already parsed, owned JSON snapshot for immutable zero-copy reuse. */+export const freezeJsonSnapshot = <T extends JsonValue>(value: T): T => {+ const pending: { value: unknown; exiting: boolean }[] = [+ { value, exiting: false },+ ];+ // These sets exist only during traversal, while the owned root already+ // retains every child. Strong sets avoid per-node ephemeron GC work.+ const visited = new Set<object>();+ const ancestors = new Set<object>();+ const objects: object[] = [];+ while (pending.length > 0) {+ const entry = pending.pop();+ if (entry === undefined) break;+ const item = entry.value;+ if (entry.exiting && typeof item === "object" && item !== null) {+ ancestors.delete(item);+ visited.add(item);+ objects.push(item);+ continue;+ }+ if (isImmutableJsonSnapshot(item)) continue;+ if (typeof item !== "object" || item === null)+ throw new TypeError("Immutable JSON snapshots require JSON values");+ const prototype: unknown = Object.getPrototypeOf(item);+ if (+ !Array.isArray(item) &&+ prototype !== Object.prototype &&+ prototype !== null+ )+ throw new TypeError("Immutable JSON snapshots require ordinary objects");+ if (ancestors.has(item))+ throw new TypeError(+ "Immutable JSON snapshots cannot contain circular references",+ );+ if (visited.has(item)) continue;+ ancestors.add(item);+ pending.push({ value: item, exiting: true });+ if (Array.isArray(item))+ for (let index = 0; index < item.length; index += 1)+ if (!Object.hasOwn(item, index))+ throw new TypeError(+ "Immutable JSON snapshots cannot contain sparse arrays",+ );+ for (const key of Object.getOwnPropertyNames(item)) {+ const descriptor = Object.getOwnPropertyDescriptor(item, key);+ if (descriptor === undefined || !Object.hasOwn(descriptor, "value"))+ throw new TypeError(+ "Immutable JSON snapshots cannot contain accessors",+ );+ const child: unknown = descriptor.value;+ pending.push({ value: child, exiting: false });+ }+ }+ // Register only after every value is checked and every object is frozen.+ // An arbitrary Object.freeze call cannot forge this snapshot identity.+ for (const item of objects) Object.freeze(item);+ // Register the requested root, rather than retaining weak entries for every+ // nested object. Sealing an Evidence or bundle skips previously sealed roots.+ if (typeof value === "object" && value !== null)+ immutableSnapshots.add(value);+ return value;+};diff --git a/src/domain/jsonSerialization.test.ts b/src/domain/jsonSerialization.test.tsnew file mode 100644index 000000000..bca145a95--- /dev/null+++ b/src/domain/jsonSerialization.test.ts@@ -0,0 +1,61 @@+import { describe, expect, it } from "vitest";+import canonicalize from "canonicalize";++import {+ bufferedJsonParts,+ canonicalJsonParts,+ jsonParts,+} from "./jsonSerialization.js";++describe("streamed JSON representation", () => {+ it.each([+ null,+ true,+ -0,+ [1, false, null, 'quotes: " / slash: \\ / newline: \n'],+ { nested: { value: "中文 😀 \ud800" }, items: [1, 2] },+ JSON.parse('{"__proto__":{"value":1},"constructor":2,"10":3,"2":4}'),+ ])("matches native JSON for ordinary values: %j", (value: unknown) => {+ expect([...bufferedJsonParts(jsonParts(value))].join("")).toBe(+ JSON.stringify(value),+ );+ expect([...jsonParts(value, true)].join("")).toBe(+ JSON.stringify(value, null, 2),+ );+ });++ it("preserves surrogate pairs across string and buffer boundaries", () => {+ const value = { text: `${"x".repeat(8190)}😀${'中文\n"'.repeat(20000)}` };+ const parts = [...bufferedJsonParts(jsonParts(value))];+ expect(+ Buffer.concat(parts.map((part) => Buffer.from(part))).toString(),+ ).toBe(JSON.stringify(value));+ expect(JSON.parse(parts.join(""))).toEqual(value);+ });++ it("rejects a cycle while allowing repeated references", () => {+ const shared = { value: 1 };+ expect([...jsonParts({ left: shared, right: shared })].join("")).toBe(+ JSON.stringify({ left: shared, right: shared }),+ );+ const cycle: { self?: unknown } = {};+ cycle.self = cycle;+ expect(() => [...jsonParts(cycle)]).toThrow("circular reference");+ });++ it("matches existing canonical bytes for numeric keys, Unicode, and shared values", () => {+ const shared = { z: -0, a: [1e-7, 1e30, "雪😀\ud800"] };+ const ownKeys: unknown = JSON.parse(+ '{"__proto__":1,"constructor":2,"10":3,"2":4}',+ );+ const value = {+ z: shared,+ a: shared,+ keys: ownKeys,+ long: '雪😀"'.repeat(20000),+ };+ expect([...bufferedJsonParts(canonicalJsonParts(value))].join("")).toBe(+ canonicalize(value),+ );+ });+});diff --git a/src/domain/jsonSerialization.ts b/src/domain/jsonSerialization.tsnew file mode 100644index 000000000..57462f254--- /dev/null+++ b/src/domain/jsonSerialization.ts@@ -0,0 +1,118 @@+/** Encode ordinary JSON as bounded string parts without a document-sized allocation. */+export function* jsonParts(value: unknown, pretty = false): Generator<string> {+ yield* encodeValue(value, pretty, 0, new Set(), false);+}++/** Encode validated JSON with canonical key ordering without allocating the whole document. */+export function* canonicalJsonParts(value: unknown): Generator<string> {+ yield* encodeValue(value, false, 0, new Set(), true);+}++/** Buffer JSON parts while preserving complete UTF-16 surrogate pairs. */+export function* bufferedJsonParts(parts: Iterable<string>): Generator<string> {+ let buffer = "";+ for (const part of parts) {+ if (buffer.length + part.length > 64 * 1024 && buffer !== "") {+ yield buffer;+ buffer = "";+ }+ buffer += part;+ }+ if (buffer !== "") yield buffer;+}++function* encodeString(value: string): Generator<string> {+ if (value.length <= 8192) {+ yield JSON.stringify(value);+ return;+ }+ yield '"';+ for (let start = 0; start < value.length;) {+ let end = Math.min(start + 8192, value.length);+ const last = value.charCodeAt(end - 1);+ const next = value.charCodeAt(end);+ // Keep a surrogate pair in the same JSON.stringify and UTF-8 write.+ if (+ end < value.length &&+ last >= 0xd800 &&+ last <= 0xdbff &&+ next >= 0xdc00 &&+ next <= 0xdfff+ )+ end -= 1;+ yield JSON.stringify(value.slice(start, end)).slice(1, -1);+ start = end;+ }+ yield '"';+}++function* encodeValue(+ value: unknown,+ pretty: boolean,+ depth: number,+ ancestors: Set<object>,+ canonical: boolean,+): Generator<string> {+ if (typeof value === "string") {+ yield* encodeString(value);+ return;+ }+ if (value === null || typeof value === "boolean") {+ yield value === null ? "null" : String(value);+ return;+ }+ if (typeof value === "number" && Number.isFinite(value)) {+ yield String(value);+ return;+ }+ if (typeof value !== "object" || value === null)+ throw new TypeError("JSON output requires ordinary JSON values");+ if (ancestors.has(value))+ throw new TypeError("JSON output contains a circular reference");+ if (+ !Array.isArray(value) &&+ Object.prototype.toString.call(value) !== "[object Object]"+ )+ throw new TypeError("JSON output requires ordinary JSON objects");+ ancestors.add(value);+ try {+ const array = Array.isArray(value);+ const keys = array ? undefined : Object.keys(value);+ if (canonical) keys?.sort();+ const count = array ? value.length : (keys?.length ?? 0);+ let written = 0;+ yield array ? "[" : "{";+ for (let index = 0; index < count; index += 1) {+ let item: unknown;+ let key: string | undefined;+ if (array) {+ item = value[index];+ } else {+ key = keys?.[index];+ if (key === undefined)+ throw new TypeError("JSON object changed during serialization");+ item = Reflect.get(value, key);+ // Incur's filter can select inherited methods. Match native JSON's+ // omission without eagerly reading the rest of a bounded result.+ if (+ item === undefined ||+ typeof item === "function" ||+ typeof item === "symbol"+ )+ continue;+ }+ if (written > 0) yield ",";+ if (pretty) yield `\n${" ".repeat(depth + 1)}`;+ if (key !== undefined) {+ yield* encodeString(key);+ yield pretty ? ": " : ":";+ }+ yield* encodeValue(item, pretty, depth + 1, ancestors, canonical);+ written += 1;+ }+ if (pretty && written > 0) yield `\n${" ".repeat(depth)}`;+ yield array ? "]" : "}";+ } finally {+ ancestors.delete(value);+ }+}diff --git a/src/domain/jsonValue.ts b/src/domain/jsonValue.tsindex 7b6f6f649..721c22c53 100644--- a/src/domain/jsonValue.ts+++ b/src/domain/jsonValue.ts@@ -16,7 +16,8 @@ const isRecord = (value: unknown): value is Record<string, unknown> =>typeof value === "object" && value !== null && !Array.isArray(value);const recordShape = z.record(z.string(), z.unknown());-const jsonValidationIssue = (root: unknown): string | undefined => {+/** Validate JSON meaning and nesting without cloning a trusted immutable value. */+export const jsonValueValidationIssue = (root: unknown): string | undefined => {const pending: { value: unknown; depth: number }[] = [{ value: root, depth: 0 },];@@ -59,9 +60,10 @@ const preserveJsonValue = (value: JsonValue): JsonValue => {};const validatedJsonValue = z.custom<JsonValue>(- (value) => jsonValidationIssue(value) === undefined,+ (value) => jsonValueValidationIssue(value) === undefined,{- error: (issue) => jsonValidationIssue(issue.input) ?? "Invalid JSON value",+ error: (issue) =>+ jsonValueValidationIssue(issue.input) ?? "Invalid JSON value",},);// Keep both stages nonrecursive in public and Standard Schema projections.diff --git a/src/server/createServer.ts b/src/server/createServer.tsindex fd71d210c..73d724ffd 100644--- a/src/server/createServer.ts+++ b/src/server/createServer.ts@@ -294,7 +294,9 @@ const createSessionRecorders = (evidenceById:session === undefined? undefined- : (evidenceId: string) => session.evidenceById(evidenceId),+ : (evidenceId: string) =>+ session.evidenceForAnalysis?.(evidenceId) ??+ session.evidenceById(evidenceId),activeTarget:session === undefined ? undefined : () => session.activeTarget(),recordEvidence:diff --git a/src/server/registerApplicationTools/helpers.ts b/src/server/registerApplicationTools/helpers.tsindex d65f5b966..0a68d97f0 100644--- a/src/server/registerApplicationTools/helpers.ts+++ b/src/server/registerApplicationTools/helpers.ts@@ -21,7 +21,13 @@ export const recordResult = ();if (recorded !== undefined && !recorded.ok)return toCallToolResult(recorded, contract);- return toCallToolResult({ ok: true, value: evidence }, contract);+ return toCallToolResult(+ { ok: true, value: evidence },+ contract,+ recorded === undefined+ ? undefined+ : { retainedEvidenceId: evidence.evidence_id },+ );};const unknownRegistration = (diff --git a/src/server/registerBrowserTools.ts b/src/server/registerBrowserTools.tsindex 498dd098b..55a065a03 100644--- a/src/server/registerBrowserTools.ts+++ b/src/server/registerBrowserTools.ts@@ -208,5 +208,11 @@ const evidenceResult = (const recorded = options.recordEvidence?.(evidence);return recorded !== undefined && !recorded.ok? toCallToolResult(recorded, contract)- : toCallToolResult({ ok: true, value: evidence }, contract);+ : toCallToolResult(+ { ok: true, value: evidence },+ contract,+ recorded === undefined+ ? undefined+ : { retainedEvidenceId: evidence.evidence_id },+ );};diff --git a/src/server/registerElectronTools.ts b/src/server/registerElectronTools.tsindex c7766feb7..e338eff4a 100644--- a/src/server/registerElectronTools.ts+++ b/src/server/registerElectronTools.ts@@ -168,5 +168,11 @@ const evidenceResult = (const recorded = options.recordEvidence?.(evidence);return recorded !== undefined && !recorded.ok? toCallToolResult(recorded, contract)- : toCallToolResult({ ok: true, value: evidence }, contract);+ : toCallToolResult(+ { ok: true, value: evidence },+ contract,+ recorded === undefined+ ? undefined+ : { retainedEvidenceId: evidence.evidence_id },+ );};diff --git a/src/server/registerSessionRecordTools.ts b/src/server/registerSessionRecordTools.tsindex b7508cd25..8e777a64f 100644--- a/src/server/registerSessionRecordTools.ts+++ b/src/server/registerSessionRecordTools.ts@@ -43,7 +43,7 @@ const registerExportEvidenceTool = ({exportContract.name,toolRegistrationOptions(exportContract),async (input) => {- const bundle = session.exportEvidenceBundle();+ const bundle = bundleForSerialization(session);const written = await writeEvidenceBundle(bundle,input.path,@@ -73,7 +73,7 @@ const registerSnapshotEvidenceTool = ({snapshotContract.name,toolRegistrationOptions(snapshotContract),() =>- toCallToolResult(ok(session.exportEvidenceBundle()), snapshotContract),+ toCallToolResult(ok(bundleForSerialization(session)), snapshotContract),);};@@ -90,9 +90,9 @@ const registerImportEvidenceTool = ({const loaded = await readEvidenceBundle(path);if (!loaded.ok) return toCallToolResult(loaded, importContract);const retainedUnknownRevisions = new Set(- session- .exportEvidenceBundle()- .unknowns.map((unknown) => unknownRevisionKey(unknown)),+ bundleForSerialization(session).unknowns.map((unknown) =>+ unknownRevisionKey(unknown),+ ),);const imported = session.importEvidenceBundle(loaded.value);return imported.ok@@ -103,7 +103,7 @@ const registerImportEvidenceTool = ({(unknown) =>!retainedUnknownRevisions.has(unknownRevisionKey(unknown)),).length,- total: session.exportEvidenceBundle().records.length,+ total: bundleForSerialization(session).records.length,}),importContract,)@@ -112,6 +112,9 @@ const registerImportEvidenceTool = ({);};+const bundleForSerialization = (session: BinarySessionPort): EvidenceBundle =>+ session.evidenceBundleForSerialization?.() ?? session.exportEvidenceBundle();+const unknownRevisionKey = (unknown: EvidenceBundle["unknowns"][number],): string => `${unknown.unknown_id}:${String(unknown.revision)}`;diff --git a/src/server/toolResult.ts b/src/server/toolResult.tsindex ca2319bdd..6beb1e54d 100644--- a/src/server/toolResult.ts+++ b/src/server/toolResult.ts@@ -1,10 +1,18 @@import type { CallToolResult } from "@modelcontextprotocol/server";+import { STDIO_DEFAULT_MAX_BUFFER_SIZE } from "@modelcontextprotocol/server";import type { ToolContract } from "../contracts/toolContracts.js";import { projectAnalysisError } from "../domain/analysisErrorProjection.js";import { type AnalysisError } from "../domain/analysisErrorBase.js";import type { JsonValue } from "../domain/jsonValue.js";import type { Result } from "../domain/result.js";+import { AnalysisResourceConstraintError } from "../domain/analysisErrorCore.js";+import { parseMcpResponseBudget } from "../config/mcpResponseBudget.js";+import {+ encodeToolResult,+ MCP_RESULT_BUDGET_BYTES,+ MCP_RESULT_STRING_LIMIT,+} from "./toolResultEncoding.js";/*** Serialize an application result as MCP text and structured content.@@ -14,8 +22,11 @@ import type { Result } from "../domain/result.js";export const toCallToolResult = (result: Result<JsonValue, AnalysisError>,contract: ToolContract,+ context?: { readonly retainedEvidenceId: string },): CallToolResult =>- result.ok ? successResult(result.value, contract) : errorResult(result.error);+ result.ok+ ? successResult(result.value, contract, context)+ : errorResult(result.error);const errorResult = (error: AnalysisError): CallToolResult => {const projected = projectAnalysisError(error);@@ -35,21 +46,73 @@ const errorResult = (error: AnalysisError): CallToolResult => {const successResult = (value: JsonValue,contract: ToolContract,+ context: { readonly retainedEvidenceId: string } | undefined,): CallToolResult => {const candidate =projectEvidence(value) ??(contract.kind === "session" ? { result: value } : value);+ const configured = parseMcpResponseBudget(+ process.env.REA_MCP_MAX_RESPONSE_BYTES,+ );+ if (!configured.ok) return errorResult(configured.error);+ const budget =+ configured.value === undefined+ ? MCP_RESULT_BUDGET_BYTES+ : configured.value - 1024;+ const encoded = encodeToolResult(candidate, budget);+ if (!encoded.ok)+ return errorResult(+ new AnalysisResourceConstraintError(+ contract.name,+ "transport",+ encoded.constraint === "string-length"+ ? "The complete MCP response exceeds Node's single-string representation limit. Use a focused retained-Evidence query or export to consume the complete analysis."+ : "The complete MCP response exceeds the stdio response budget. The analysis result was not truncated; use a focused retained-Evidence query or export to consume it.",+ {+ boundary: "mcp-response",+ default_receive_buffer_bytes: STDIO_DEFAULT_MAX_BUFFER_SIZE,+ result_budget_bytes: budget,+ max_string_code_units: MCP_RESULT_STRING_LIMIT,+ response_bytes_at_least: encoded.bytesAtLeast,+ response_code_units_at_least: encoded.codeUnitsAtLeast,+ constraint: encoded.constraint,+ ...evidenceRecovery(value, context?.retainedEvidenceId),+ },+ ),+ );return {content: [{type: "text",- text: JSON.stringify(candidate),+ text: encoded.text,},],structuredContent: candidate,};};+const evidenceRecovery = (+ value: JsonValue,+ retainedEvidenceId: string | undefined,+): Record<string, JsonValue> => {+ const projected = projectEvidence(value);+ if (+ projected === undefined ||+ typeof projected !== "object" ||+ projected === null ||+ Array.isArray(projected)+ )+ return {};+ if (projected.evidence_id !== retainedEvidenceId)+ return { evidence_id: projected.evidence_id ?? null };+ return {+ evidence_reference: {+ kind: "retained-evidence",+ evidence_id: projected.evidence_id ?? null,+ },+ };+};+const projectEvidence = (value: JsonValue): JsonValue | undefined => {if (typeof value !== "object" ||diff --git a/src/server/toolResultEncoding.test.ts b/src/server/toolResultEncoding.test.tsnew file mode 100644index 000000000..367d1bfe9--- /dev/null+++ b/src/server/toolResultEncoding.test.ts@@ -0,0 +1,55 @@+import { describe, expect, it } from "vitest";++import type { JsonValue } from "../domain/jsonValue.js";+import { encodeToolResult } from "./toolResultEncoding.js";++const projectedResult = (candidate: JsonValue) => ({+ content: [{ type: "text", text: JSON.stringify(candidate) }],+ structuredContent: candidate,+});++describe("MCP result encoding budget", () => {+ it.each([+ { result: { value: 1 } },+ { result: ["中文", "😀", "\ud800", '"\\\n'] },+ { result: "x".repeat(8191) + "😀" + '中文\n"'.repeat(20000) },+ ])("counts actual UTF-8 structured and escaped text bytes", (candidate) => {+ const encoded = encodeToolResult(candidate);+ expect(encoded.ok).toBe(true);+ if (!encoded.ok) throw new Error("Expected complete encoding");+ expect(encoded.text).toBe(JSON.stringify(candidate));+ expect(encoded.bytes).toBe(+ Buffer.byteLength(JSON.stringify(projectedResult(candidate))),+ );+ });++ it("accounts for repeated Evidence representations", () => {+ const normalized = { value: '中文"'.repeat(30000) };+ const candidate = {+ result: normalized,+ evidence: { normalized_result: normalized },+ };+ const completeBytes = Buffer.byteLength(+ JSON.stringify(projectedResult(candidate)),+ );+ expect(encodeToolResult(candidate, completeBytes).ok).toBe(true);+ expect(encodeToolResult(candidate, completeBytes - 1)).toMatchObject({+ ok: false,+ bytesAtLeast: completeBytes,+ });+ });++ it("stops before reading the remainder of an oversized result", () => {+ const candidate: JsonValue = { text: "x".repeat(1000000) };+ Object.defineProperty(candidate, "remainder", {+ enumerable: true,+ get() {+ throw new Error("The remainder must not be read");+ },+ });+ // Only an already-known first property is visited before exhausting the+ // budget. The serializer's property discovery must not eagerly read values.+ expect(() => encodeToolResult(candidate, 1000)).not.toThrow();+ expect(encodeToolResult(candidate, 1000).ok).toBe(false);+ });+});diff --git a/src/server/toolResultEncoding.ts b/src/server/toolResultEncoding.tsnew file mode 100644index 000000000..496adb3ef--- /dev/null+++ b/src/server/toolResultEncoding.ts@@ -0,0 +1,55 @@+import { STDIO_DEFAULT_MAX_BUFFER_SIZE } from "@modelcontextprotocol/server";+import { constants as bufferConstants } from "node:buffer";++import type { JsonValue } from "../domain/jsonValue.js";+import { bufferedJsonParts, jsonParts } from "../domain/jsonSerialization.js";++// Leave room for the SDK's JSON-RPC envelope and protocol metadata. This budget+// follows the pinned client's actual default framing limit, not a result-row cap.+export const MCP_RESULT_BUDGET_BYTES = STDIO_DEFAULT_MAX_BUFFER_SIZE - 1024;+export const MCP_RESULT_STRING_LIMIT = bufferConstants.MAX_STRING_LENGTH - 1024;++const RESULT_ENVELOPE_BYTES =+ Buffer.byteLength(+ JSON.stringify({+ content: [{ type: "text", text: "" }],+ structuredContent: null,+ }),+ ) - 4;++/** Result of encoding the complete repeated MCP representations within a wire budget. */+export type ToolResultEncoding =+ | { readonly ok: true; readonly text: string; readonly bytes: number }+ | {+ readonly ok: false;+ readonly bytesAtLeast: number;+ readonly codeUnitsAtLeast: number;+ readonly constraint: "receive-buffer" | "string-length";+ };++/** Account for structured JSON and escaped text before allocating the complete text. */+export const encodeToolResult = (+ value: JsonValue,+ budgetBytes = MCP_RESULT_BUDGET_BYTES,+): ToolResultEncoding => {+ const parts: string[] = [];+ let bytes = RESULT_ENVELOPE_BYTES;+ let codeUnits = RESULT_ENVELOPE_BYTES;+ for (const part of bufferedJsonParts(jsonParts(value))) {+ const escapedPart = JSON.stringify(part);+ bytes += Buffer.byteLength(part) + Buffer.byteLength(escapedPart) - 2;+ codeUnits += part.length + escapedPart.length - 2;+ if (bytes > budgetBytes || codeUnits > MCP_RESULT_STRING_LIMIT)+ return {+ ok: false,+ bytesAtLeast: bytes,+ codeUnitsAtLeast: codeUnits,+ constraint:+ codeUnits > MCP_RESULT_STRING_LIMIT+ ? "string-length"+ : "receive-buffer",+ };+ parts.push(part);+ }+ return { ok: true, text: parts.join(""), bytes };+};diff --git a/tests/boundary/filesystem/evidenceBundleFiles.test.ts b/tests/boundary/filesystem/evidenceBundleFiles.test.tsindex efc1cd08f..716c65880 100644--- a/tests/boundary/filesystem/evidenceBundleFiles.test.ts+++ b/tests/boundary/filesystem/evidenceBundleFiles.test.ts@@ -1,4 +1,11 @@-import { mkdir, readdir, readFile, symlink, writeFile } from "node:fs/promises";+import {+ mkdir,+ readdir,+ readFile,+ stat,+ symlink,+ writeFile,+} from "node:fs/promises";import { join } from "node:path";import { describe, expect, it } from "vitest";@@ -12,6 +19,7 @@ import {import { compareEvidenceBundlesCommand } from "../../../src/application/EvidenceBundleCommands.js";import { projectAnalysisError } from "../../../src/domain/analysisErrorProjection.js";import { createEvidence } from "../../../src/domain/evidence.js";+import { writeTextParts } from "../../../src/application/JsonFiles.js";import {createEvidenceBundle,serializeEvidenceBundle,@@ -27,6 +35,39 @@ const bundle = (result = true) =>]);describe("evidence bundle publication", () => {+ it.each([false, true])(+ "never publishes a partial streamed file (overwrite: %s)",+ async (overwrite) => {+ const root = await createTestTempDirectory("rea-stream-publication-");+ const path = join(root, "bundle.json");+ if (overwrite) await writeFile(path, "original");+ function* brokenParts() {+ yield "partial";+ throw new Error("Source stream failed");+ }+ expect(+ await writeTextParts(brokenParts(), path, overwrite),+ ).toMatchObject({+ ok: false,+ error: { _tag: "EvidenceFileError", reason: "io" },+ });+ expect(await readdir(root)).toEqual(overwrite ? ["bundle.json"] : []);+ if (overwrite) expect(await readFile(path, "utf8")).toBe("original");+ },+ );++ it("counts complete Unicode bytes and publishes a private file", async () => {+ const root = await createTestTempDirectory("rea-stream-bytes-");+ const path = join(root, "bundle.json");+ const parts = ["雪", "😀", "\n"];+ expect(await writeTextParts(parts, path, false)).toEqual({+ ok: true,+ value: { path, bytes: Buffer.byteLength(parts.join("")) },+ });+ expect(await readFile(path, "utf8")).toBe(parts.join(""));+ if (process.platform !== "win32")+ expect((await stat(path)).mode & 0o777).toBe(0o600);+ });it("allows only one simultaneous export without overwrite approval", async () => {const root = await createTestTempDirectory("rea-evidence-exclusive-");const path = join(root, "bundle.json");diff --git a/tests/boundary/mcp/largeToolResult.test.ts b/tests/boundary/mcp/largeToolResult.test.tsnew file mode 100644index 000000000..0bf82e4c0--- /dev/null+++ b/tests/boundary/mcp/largeToolResult.test.ts@@ -0,0 +1,69 @@+import { describe, expect, it } from "vitest";+import { STDIO_DEFAULT_MAX_BUFFER_SIZE } from "@modelcontextprotocol/server";++import { toolContract } from "../../../src/contracts/toolContracts.js";+import { createEvidence, parseEvidence } from "../../../src/domain/evidence.js";+import { ok } from "../../../src/domain/result.js";+import { toCallToolResult } from "../../../src/server/toolResult.js";+import { EvidenceLedger } from "../../../src/application/investigation/EvidenceLedger.js";++describe("large complete Evidence MCP delivery", () => {+ it("preserves retained content and returns an actionable framing constraint", () => {+ const normalized = {+ payload: "x".repeat(Math.ceil(STDIO_DEFAULT_MAX_BUFFER_SIZE / 3)),+ };+ const evidence = createEvidence(+ undefined,+ { id: "fixture", name: "Fixture", version: "1" },+ {+ operation: "analyze_javascript_application",+ parameters: {},+ result: normalized,+ },+ );+ const ledger = new EvidenceLedger();+ expect(ledger.record(evidence).ok).toBe(true);+ const result = toCallToolResult(+ ok(evidence),+ toolContract("analyze_javascript_application"),+ { retainedEvidenceId: evidence.evidence_id },+ );+ expect(result.isError).toBe(true);+ expect(result.structuredContent).toMatchObject({+ error: {+ code: "resource_constraint",+ category: "resource_constraint",+ details: {+ resource: "transport",+ reported_limits: {+ boundary: "mcp-response",+ constraint: "receive-buffer",+ evidence_reference: {+ kind: "retained-evidence",+ evidence_id: evidence.evidence_id,+ },+ },+ },+ },+ });+ expect(Buffer.byteLength(JSON.stringify(result))).toBeLessThan(+ STDIO_DEFAULT_MAX_BUFFER_SIZE,+ );+ expect(result.content).toEqual([+ { type: "text", text: JSON.stringify(result.structuredContent) },+ ]);+ const retained = ledger.get(evidence.evidence_id);+ expect(parseEvidence(retained)).toEqual(evidence);+ expect(retained?.normalized_result).toEqual(normalized);+ const detached = toCallToolResult(+ ok(evidence),+ toolContract("analyze_javascript_application"),+ );+ expect(detached.structuredContent).toMatchObject({+ error: {+ details: { reported_limits: { evidence_id: evidence.evidence_id } },+ },+ });+ expect(JSON.stringify(detached)).not.toContain("retained-evidence");+ });+});diff --git a/tests/conformance/contracts/mcpResponseBudget.test.ts b/tests/conformance/contracts/mcpResponseBudget.test.tsnew file mode 100644index 000000000..206f8b930--- /dev/null+++ b/tests/conformance/contracts/mcpResponseBudget.test.ts@@ -0,0 +1,49 @@+import { describe, expect, it } from "vitest";+import { STDIO_DEFAULT_MAX_BUFFER_SIZE } from "@modelcontextprotocol/server";++import { parseMcpResponseBudget } from "../../../src/config/mcpResponseBudget.js";++describe("MCP response budget configuration", () => {+ it("leaves the default policy to the MCP adapter", () => {+ expect(parseMcpResponseBudget(undefined)).toEqual({+ ok: true,+ value: undefined,+ });+ });++ it("requires the override to accommodate the pinned transport's default frames", () => {+ expect(+ parseMcpResponseBudget(String(STDIO_DEFAULT_MAX_BUFFER_SIZE)).ok,+ ).toBe(true);+ expect(+ parseMcpResponseBudget(String(STDIO_DEFAULT_MAX_BUFFER_SIZE - 1)).ok,+ ).toBe(false);+ });++ it.each(["10485760", "268435456", "1073741824"])(+ "accepts an explicit complete-response budget: %s",+ (value) => {+ expect(parseMcpResponseBudget(value)).toEqual({+ ok: true,+ value: Number(value),+ });+ },+ );++ it.each([+ "",+ "0",+ "-1",+ "1024",+ "1.5",+ "1e8",+ " 10485760",+ "Infinity",+ "9007199254740992",+ ])("rejects malformed or unusable budgets: %j", (value) => {+ const parsed = parseMcpResponseBudget(value);+ expect(parsed.ok).toBe(false);+ if (parsed.ok) throw new Error("Expected invalid budget");+ expect(parsed.error.message).toContain("REA_MCP_MAX_RESPONSE_BYTES");+ });+});