Introducing a new way to review your PRs.

Read the announcement

morluto / rea

Reverse engineer anything with agents, from app behavior down to native binaries.

View on GitHub

27 documents · Updated Nov 20, 2026

docs / environment-bundle-and-replay

Environment bundle and replay

Environment bundles turn a captured web or browser session into a portable agent environment. The flow checks and seals its source files, projects the captured API into tools and optional state, writes a runnable bundle, and serves recorded responses over CLI and MCP interfaces. See Analysis environments for the wider environment model.

Environment source

Input snapshots

The source is an authenticated pair: an environment-manifest Evidence file and the capture Evidence file that it names as its parent. The loader accepts a HAR-based web capture or a browser-scenario capture, then indexes the records needed by the manifest's tools for replay. Browser-scenario events that are not represented by an indexed record remain available to build warnings. src/…/environmentSource.ts src/…/environmentSource.ts src/…/environmentBuildReport.ts

The manifest must be an environment-manifest view. Its parent_evidence_id must equal the supplied capture Evidence ID. This cross-check keeps serving, state derivation, comparison, and export tied to the same captured source. src/…/environmentSource.ts src/…/environmentSource.ts

References: src/…/environmentSource.ts• L273-325 src/…/environmentSource.ts• L427-503 src/…/environmentBuildReport.ts• L270-334

Input cleanup

File input is read as one stable regular-file snapshot. The same bytes are used for authentication and for the copy placed in a bundle, so a source file cannot change between those two uses. Parsed Evidence members are also sealed before later checks share them. src/…/environmentExport.ts src/…/environmentExport.ts src/…/environmentSource.ts

The export first admits the full read, parse, and seal against available heap headroom. It refuses inline JSON when a file snapshot is required. A package tarball is also admitted as one retained file instance before it is copied. File handles and output trees remain owned until cleanup completes. A changed file, unreadable path, failed close, insufficient memory, or host write failure becomes a typed refusal with the affected path and recovery details. src/…/environmentExport.ts src/…/environmentBundleWrite.ts src/…/environmentBundleWrite.ts

References: src/…/environmentExport.ts• L200-235 src/…/environmentExport.ts• L253-375 src/…/environmentBundleWrite.ts• L122-153 src/…/environmentBundleWrite.ts• L268-349 src/…/environmentSource.ts• L143-161

Environment build

Capture inputs

environment-build is the one-step path from a recorded capture to a bundle. It accepts a .har file for inspection or capture Evidence from a web capture or browser scenario; a JSON HAR document is not accepted as already-authenticated Evidence. [src/application/environment/environmentBuild.ts#L58-L84] [src/application/environment/environmentBuild.ts#L247-L273]

The build can run as a plan without writing files. A normal build requires a destination and refuses to overwrite an existing destination. Template rules shape the projected manifest, while an optional package tarball changes what the generated image installs. [src/application/environment/environmentBuild.ts#L91-L110] [src/cli/environmentCommands.ts#L488-L555]

References: src/…/environmentBuild.ts• L58-84 src/…/environmentBuild.ts• L247-273 src/…/environmentCommands.ts• L488-555

Manifest and state projection

The build projects an environment manifest from the capture, authenticates that manifest with the capture, and derives the environment state with the manifest's template rules. The state describes the data that the capture observed and identifies which read and confirmed write tools can be served from that state. [src/application/environment/environmentBuild.ts#L273-L326] [src/application/environment/environmentState.ts#L213-L235] [src/application/environment/environmentState.ts#L293-L319]

State input must be valid environment-state Evidence tied to the same capture and template rules. Malformed or unrelated JSON is rejected with structured input issues instead of being treated as served state. [src/application/environment/environmentState.test.ts#L75-L158]

State serving is conservative. A read uses the state only when the captured evidence supports that view; otherwise it uses the matching recording. A write is exposed as a state change only when the capture shows enough later evidence to confirm its effect. The state can preserve captured rules for omitted members, references, derived fields, generated values, and calls that write several named entities. Unsupported, ambiguous, or contradicted writes remain replay-only or are refused without changing the state. [src/application/environment/environmentToolAnswer.ts#L27-L67] [src/application/environment/environmentStateAnswer.ts#L634-L667] [src/application/environment/environmentStateWriteAnswer.ts#L540-L637] [src/application/environment/environmentStateWriteAnswer.ts#L662-L712] [src/application/environment/environmentStateWriteQuery.ts#L13-L49]

Generated values follow the captured shape while avoiding values already held by the live state. The state keeps write history so sequences continue after reset and generated values remain consistent across later calls. A call is refused when its path, query, body, or generated relation cannot be applied safely. This includes a write whose query differs from the captured query or repeats a query name. A bulk call is refused when one call-level generated value cannot safely represent all of its targets. [src/application/environment/environmentStateWriteAnswer.ts#L223-L387] [src/application/environment/environmentStateWriteQuery.ts#L13-L49] [src/application/environment/environmentStateBulkAnswer.ts#L153-L236]

If state derivation fails, or the resulting state or tool catalog cannot fit its serving limits, the build does not invent state. It reports why state is unavailable and the resulting bundle uses replay. State-backed writes are exposed only when the captured response and later reads explain the resulting state, including later field presence and soft-delete behavior. The build also reports possible credential-like names without copying credential values into the report. [src/application/environment/environmentBuild.ts#L315-L355] [src/application/environment/environmentStateAnswer.ts#L380-L450] [src/application/environment/environmentStateWriteAnswer.ts#L746-L861]

References: src/…/environmentBuild.ts• L273-355 src/…/environmentState.ts• L213-319 src/…/environmentState.test.ts• L75-158 src/…/environmentStateAnswer.ts• L380-450 src/…/environmentStateAnswer.ts• L634-667 src/…/environmentStateWriteAnswer.ts• L223-387 src/…/environmentStateWriteAnswer.ts• L540-712 src/…/environmentStateWriteAnswer.ts• L746-861 src/…/environmentStateWriteQuery.ts• L13-49

Build report

The build report connects the source, projected manifest, state choice, coverage summary, warnings, package source, and output files. It gives an operator a clear result before running the bundle and provides the next agent-env run command after a successful write. [src/application/environment/environmentBuild.ts#L326-L420]

Cancellation before bundle writing leaves no output. Cancellation during the write reports that the bundle was written, so the operator can distinguish an absent destination from a usable bundle. [src/application/environment/environmentBuild.test.ts#L348-L391]

Warnings are advisory. They identify credential-like names in captured headers, queries, bodies, and browser-scenario saved values. They also identify retained bodies that were too large for the scan. The captured Evidence still ships in the bundle, so the operator must review it before sharing the result. [src/application/environment/environmentBuildReport.ts#L311-L385]

References: src/…/environmentBuild.ts• L326-420 src/…/environmentBuild.test.ts• L348-391 src/…/environmentBuildReport.ts• L311-385

Bundle export

Bundle contents

An export is a self-contained agent environment folder. It combines the authenticated manifest and capture bytes with the files needed to build, start, and smoke-check the local serving image. If a local package tarball is selected, the export retains the admitted file instance, verifies its complete size and digest, and copies that same instance into the bundle. [src/application/environment/environmentBundle.ts#L358-L417] [src/application/environment/environmentBundleWrite.ts#L122-L153] [src/application/environment/environmentBundleWrite.ts#L155-L246] [src/application/environment/environmentBundleWrite.ts#L309-L349]

The main bundle parts are:

The bundle name is both the folder name and the local environment ID. It must be a portable lower-case kebab-case label that remains a valid service host and cannot be a Windows device name. The destination must be absent or empty, and publication occurs only after the planned tree is complete. A later failure can report the published file receipt when the output is already usable. A retry still requires inspection and cleanup because a non-empty destination is refused. [src/application/environment/environmentBundle.ts#L19-L40] [src/application/environment/environmentBundleWrite.ts#L155-L246] [src/application/environment/environmentExport.ts#L395-L433]

References: src/…/environmentBundle.ts• L19-40 src/…/environmentBundle.ts• L358-417 src/…/environmentBundleWrite.ts• L122-153 src/…/environmentBundleWrite.ts• L155-246 src/…/environmentBundleWrite.ts• L309-349 src/…/environmentExport.ts• L395-433

Provenance and rights

The generated README links the environment to its source with the capture kind and digest, both Evidence IDs, the manifest view digest, the primary origin, the tool count, the state result, and the package source. This record helps an operator identify what the bundle represents without changing the captured data. [src/application/environment/environmentBundle.ts#L269-L365]

The bundle contains application content from the capture. It carries a rights warning and should remain private when the captured application data is restricted. [src/application/environment/environmentBundle.ts#L291-L365]

References: src/…/environmentBundle.ts• L269-365 src/…/environmentBuildReport.ts• L311-385

Replay behavior

Record selection

Replay answers a manifest tool from one retained exchange. It ranks cited records by path matches, exact path spelling, query matches, and observed query order. Repeated query values remain ordered. A call is exact only when all supplied path and query values match; when the observed query is available, its order and presence of the ? delimiter must also match. [src/application/environment/environmentReplay.ts#L57-L170] [src/application/environment/environmentReplay.ts#L181-L260]

When the caller supplies query values but no observed query spelling, two otherwise exact records with different query order or shape make the result ambiguous. Replay still selects the strongest record, but it clears the exact-match flag. [src/application/environment/environmentReplay.ts#L207-L260]

Replay does not run the captured application. It does not reproduce application authorization, validation, response logic, or state transitions. A tool with no usable cited record returns an error instead of a made-up response. [src/application/environment/environmentReplay.ts#L347-L371]

References: src/…/environmentReplay.ts• L57-170 src/…/environmentReplay.ts• L181-260 src/…/environmentReplay.ts• L347-371

Replay values

The replay result carries the recorded status, content type, body, record ordinal, Evidence ID, match quality, encoding, and truncation facts. JSON-like text is returned as JSON when it can be parsed without losing exact numeric values. Binary content is returned as base64. [src/application/environment/environmentReplay.ts#L29-L46] [src/application/environment/environmentSource.ts#L81-L110]

Response bodies are bounded at 256 KiB. Text is cut at a UTF-8 boundary, while base64 is limited by decoded byte size. Recorded paths, queries, and content types are each bounded at 1 KiB in the returned metadata. These limits affect the response view, not the retained Evidence. [src/application/environment/environmentReplay.ts#L311-L345] [src/application/environment/environmentReplay.ts#L347-L410] [src/application/environment/environmentReplay.test.ts#L461-L578]

References: src/…/environmentSource.ts• L49-74 src/…/environmentReplay.ts• L311-345 src/…/environmentReplay.ts• L347-410 src/…/environmentReplay.test.ts• L461-578

Capacity controls

Discovery has a 1 MiB serialization reservation. It covers the environment name, tool descriptions, escaped samples, input names, and schemas before the listener binds. Long captured values use bounded samples, while the full values remain in Evidence. An over-size catalog is refused rather than served in a partial form. [src/application/environment/environmentTools.ts#L110-L175] [src/application/environment/environmentTools.ts#L405-L552]

State serving has its own limits. A loaded or derived state must fit the 32 MiB document that data/add can load back. Served writes refuse changes that would exceed that bound, and distinct generated collection history has a separate 1 MiB budget. A rendered state answer remains within the 256 KiB body limit. The JSON-RPC response budget is 64 MiB, so a state reply or batch cannot grow without bound. [src/application/environment/environmentStateDocument.ts#L36-L38] [src/application/environment/environmentStateStore.ts#L24-L25] [src/application/environment/environmentStateStore.ts#L95-L100] [src/application/environment/environmentStateStore.ts#L257-L299] [src/server/environment/serveEnvironment.ts#L147-L153] [src/server/environment/serveEnvironment.ts#L278-L342]

Reset and state replacement restart generated-value history. This lets a client load a smaller state or clear generated collection history without leaving old write counters active. [src/application/environment/environmentStateStore.ts#L146-L190] [src/application/environment/environmentStateStore.ts#L217-L232]

References: src/…/environmentTools.ts• L405-552 src/…/environmentStateDocument.ts• L36-38 src/…/environmentStateStore.ts• L24-25 src/…/environmentStateStore.ts• L95-100 src/…/environmentStateStore.ts• L146-190 src/…/environmentStateStore.ts• L217-299 src/…/serveEnvironment.ts• L147-153 src/…/serveEnvironment.ts• L278-342

Environment comparison

Probe comparison

Environment comparison runs captured application probes against the environment and reports whether the environment answers the same calls. Each probe is a request sequence from a freshly reset application, and the environment starts from a fresh state for that probe when state serving is available. [src/application/environment/environmentCompare.ts#L476-L557] [src/application/environment/environmentCompare.test.ts#L367-L424]

The comparison follows the environment's own tool matching and input checks. It compares status and response content after it accounts for expected changes such as mapped IDs, generated values, clocks, large bodies, and bodies that the probe did not observe. It reports exact agreement, agreement that ignores item order, difference categories, and records that could not be compared. [src/application/environment/environmentCompare.ts#L71-L125] [src/application/environment/environmentCompareDiff.ts#L554-L625] [src/application/environment/environmentCompareProbe.ts#L117-L180]

ID mapping follows the collection named by the live request. This keeps IDs separate when different collections or parent resources reuse the same value. The comparison learns an ID only from an exact replay of the same call, including its request body, so an answer borrowed from another recording cannot teach a false mapping. [src/application/environment/environmentCompare.ts#L227-L249] [src/application/environment/environmentCompare.ts#L331-L400] [src/application/environment/environmentCompare.test.ts#L455-L506]

Probe captures must include response bodies for content comparison. A probe that includes write calls must also include request bodies, because the environment must receive the same call data. JSON request bodies retain their JSON value when the media type is JSON-like. Records with missing URLs, requests, or responses remain in the report as unobserved rather than counting as agreement. [src/application/environment/environmentCompareProbe.ts#L60-L99] [src/application/environment/environmentCompareProbe.ts#L117-L180] [src/application/environment/environmentCompare.test.ts#L882-L957]

Recorded probe bodies larger than the replay limit are compared by status only. The report counts this normalization so a status match is not mistaken for full body agreement. [src/application/environment/environmentCompareDiff.ts#L546-L624] [src/application/environment/environmentCompareBody.test.ts#L87-L140]

References: src/…/environmentCompare.ts• L71-125 src/…/environmentCompare.ts• L227-249 src/…/environmentCompare.ts• L331-400 src/…/environmentCompare.ts• L476-557 src/…/environmentCompareDiff.ts• L546-625 src/…/environmentCompareProbe.ts• L60-180 src/…/environmentCompare.test.ts• L367-424 src/…/environmentCompareBody.test.ts• L67-140

Comparison report

The report gives results at probe, request-step, tool, and overall levels. A step contains the live and environment status, equality flags, difference categories, a bounded list of differences, and the count of omitted differences. The summary also records ID mappings, conflicts, normalised values, and unobserved records. [src/application/environment/environmentCompare.ts#L71-L125] [src/application/environment/environmentCompare.ts#L288-L310] [src/application/environment/environmentCompare.ts#L403-L474]

Difference detail is bounded for each step, but the report keeps the full difference count and all categories. This lets a caller receive a small response without losing the fact that several kinds of mismatch occurred. [src/application/environment/environmentCompareDiff.ts#L26-L61] [src/application/environment/environmentCompare.ts#L288-L310]

References: src/…/environmentCompare.ts• L71-125 src/…/environmentCompare.ts• L288-310 src/…/environmentCompare.ts• L403-474 src/…/environmentCompareDiff.ts• L26-61

Command interface

Build command

rea environment-build inspects a HAR or reads capture Evidence, projects the manifest, derives state, reports coverage and warnings, and writes the bundle in one flow. Use --dry-run to execute the stages and report planned files without writing them. [src/cli/environmentCommands.ts#L398-L485] [src/cli/environmentCommands.ts#L488-L555]

rea environment-build capture.har BUNDLE_DIR
rea environment-build capture.json --dry-run

Use --template-rule to select projection rules, --format-rules-only to use only the view's format rules, --name to set the environment ID, and --package-tarball to install a local packed CLI in the generated image. [src/cli/environmentCommands.ts#L507-L535]

Environment commands are registered with the application command family. This keeps bundle creation and serving available through the same top-level CLI as the other analysis commands. [src/cli.ts#L227-L239]

References: src/…/environmentCommands.ts• L398-485 src/…/environmentCommands.ts• L488-555 src/cli.ts• L227-239

Compare command

rea environment-compare loads one environment and one or more probe captures. It answers each probe from a reset environment state and returns agreement at request-step, tool, probe, and summary levels. [src/cli/environmentCommands.ts#L557-L620] [src/application/environment/environmentCompare.ts#L476-L571]

rea environment-compare MANIFEST.json \
  --evidence CAPTURE.json \
  --probe PROBE.json

Repeat --probe for each request sequence recorded against a freshly reset application. The command snapshots the manifest, capture, and probe files before comparison, so the report uses stable input bytes. [src/cli/environmentCommands.ts#L551-L620] [src/application/environment/environmentCompare.ts#L476-L571]

References: src/…/environmentCommands.ts• L551-620 src/…/environmentCompare.ts• L476-571 src/…/environmentCompareProbe.ts• L117-180

Export command

rea environment-export exports an existing manifest and its parent capture Evidence. It authenticates both files, copies the exact input bytes, prepares the same serving choice as the server, and reports the bundle path, IDs, state result, package source, and written file sizes. [src/cli/environmentCommands.ts#L265-L319]

rea environment-export MANIFEST.json BUNDLE_DIR \
  --evidence CAPTURE.json

Use --name for the portable environment ID. Use --package-tarball to install a local packed CLI instead of the pinned registry package. The programmatic export_environment_bundle tool accepts either an Evidence file or a retained Evidence reference, checks the destination before reading the capture, and uses the same build and output contract. [src/cli/environmentCommands.ts#L641-L676] [src/application/environment/environmentBundleTool.ts#L23-L82]

References: src/…/environmentCommands.ts• L265-319 src/…/environmentCommands.ts• L641-676 src/…/environmentBundleTool.ts• L23-82

Serve command

rea environment-serve authenticates the same manifest and capture pair, prepares state unless replay-only mode is requested, and serves until cancellation or a process signal. The host and port come from command options first, then MCP_HOST and MCP_PORT, with loopback and an ephemeral port as defaults. [src/cli/environmentCommands.ts#L140-L170] [src/cli/environmentCommands.ts#L172-L263] [src/cli/environmentCommands.ts#L688-L728]

rea environment-serve MANIFEST.json \
  --evidence CAPTURE.json \
  --host 127.0.0.1 --port 0

--replay-only skips state derivation. It exposes every manifest tool through replay and returns method-not-found for /agentenv operations because no state data plane is present. Normal serving adds state-backed tools and data operations when state preparation succeeds. [src/cli/environmentCommands.ts#L134-L170] [src/application/environment/environmentState.ts#L81-L121]

References: src/…/environmentCommands.ts• L134-170 src/…/environmentCommands.ts• L172-263 src/…/environmentCommands.ts• L688-728 src/…/environmentState.ts• L81-121

MCP serving transport

Environment card

The environment card is the discovery surface for agent environment clients. GET /.well-known/agent-env.json reports the environment name, protocol version, tool catalog, input schemas, and the two interfaces: /agentenv for JSON-RPC and /mcp for MCP. A state-served card also declares that data/add replaces the state, data/get returns it, and data/reset restores the initial state. [src/application/environment/environmentTools.ts#L555-L612] [src/server/environment/serveEnvironment.ts#L409-L423]

Captured names, descriptions, samples, and responses are target content. The card and MCP server warn clients to treat this content as data, not as instructions. [src/application/environment/environmentTools.ts#L31-L33] [src/server/environment/serveEnvironment.ts#L103-L145]

References: src/…/environmentTools.ts• L31-33 src/…/environmentTools.ts• L555-612 src/…/serveEnvironment.ts• L103-145

MCP data plane

POST /mcp is the streamable HTTP MCP surface. It lists the tools admitted by the catalog and returns either a state-backed answer or the selected recorded exchange with replay provenance. Tool results and SDK-created tool errors carry target-content handling. [src/server/environment/serveEnvironment.ts#L75-L145] [src/server/environment/serveEnvironment.ts#L454-L512]

MCP tool discovery also carries method hints. Safe methods and query-like POST calls are marked read-only, PUT and DELETE are marked idempotent, and DELETE is marked destructive; all served tools declare that answers come from a closed captured world. These hints are part of MCP discovery and are not added to the environment card. [src/application/environment/environmentTools.ts#L52-L59] [src/application/environment/environmentTools.ts#L99-L108] [src/server/environment/serveEnvironment.test.ts#L343-L404]

POST /agentenv accepts bounded JSON-RPC messages. Normal state serving provides data/reset, data/add, and data/get; replay-only serving has no data methods. Requests over the transport body limit are rejected before JSON parsing. Batches are limited to 100 messages, replies are kept within a response budget, and unknown methods return JSON-RPC method-not-found errors. [src/server/environment/serveEnvironment.ts#L85-L87] [src/server/environment/serveEnvironment.ts#L278-L424] [src/application/environment/environmentTools.ts#L555-L610] [src/server/environment/serveEnvironment.test.ts#L121-L273] [src/server/environment/serveEnvironment.test.ts#L458-L486]

This diagram shows how one authenticated source pair becomes discovery data and answers on the two HTTP surfaces.

flowchart LR
    A[Manifest Evidence] --> C[Authenticated environment source]
    B[Parent capture Evidence] --> C
    C --> D[State preparation or replay source]
    D --> E[Bounded tool catalog]
    E --> F[Environment card]
    D --> G[MCP tool answer]
    F --> H[GET /.well-known/agent-env.json]
    G --> I[POST /mcp]
    D --> J[State data plane when available]
    J --> K[POST /agentenv]

References: src/…/serveEnvironment.ts• L75-145 src/…/serveEnvironment.ts• L409-512 src/…/environmentTools.ts• L52-59 src/…/environmentTools.ts• L555-612

Change checklist

When these files or sections are changed, remember to consider these:

  • Keep manifest parent-ID checks aligned with the Evidence bytes copied into bundles.
  • Keep build projection rules aligned with state derivation, build reports, and bundle README claims.
  • Keep generated Dockerfile paths, copied input paths, and the smoke task environment name aligned.
  • Keep replay body and metadata limits aligned with truncation flags and comparison handling.
  • Keep discovery reservations aligned with both the environment card and MCP tool discovery.
  • Keep state intake, mutation, collection-history, and JSON-RPC response limits aligned.
  • Keep state-backed write admission aligned with later-read confirmation, derived fields, varied call shapes, generated values, query pinning, and replay fallback.
  • Keep bulk-write admission aligned with per-call generated values and the all-or-nothing state update contract.
  • Keep export heap admission aligned with complete input reads, JSON sealing, and the exact bytes copied to the bundle.
  • Keep admitted package tarball identity checks aligned with the bytes and receipt published by the bundle writer.
  • Keep MCP_HOST, MCP_PORT, and allowed-host behavior aligned with bundle listener settings and CLI overrides.
  • Keep target-content markers on normal replay results and SDK-created tool errors.
  • Keep MCP method hints aligned with HTTP method semantics and keep them separate from the environment card.
  • Keep credential warnings clear that Evidence still contains the captured values.
  • Keep --replay-only behavior aligned between CLI loading, bundle documentation, the environment card, and /agentenv methods.
  • Keep cancellation diagnostics aligned with whether the bundle was published before cancellation.
  • Keep probe body requirements aligned with browser capture options and the comparison input contract.
  • Keep comparison reset state, request chronology, collection-scoped ID mapping, request-body matching, and replay exactness aligned with the agreement report.
  • Keep large-body normalization visible in comparison counts and categories.
  • Keep reported difference categories and total counts aligned with the bounded per-step difference list.

Important failure modes

TriggerConsequenceGuard
Manifest and capture Evidence IDs do not matchBuild, serving, and export stop before producing a usable environmentSource loading cross-checks the manifest parent ID against the supplied capture ID.
Input file changes during the readThe operation refuses an unstable source snapshotRegular-file reads verify the selected file remains stable.
Complete input read, parse, and seal exceed heap headroomExport refuses the source before producing a partial bundleExport admits the full file size against available heap headroom.
An admitted package tarball changes during digest or copyExport reports an artifact change and identifies the retained publication when presentThe writer retains one file instance and checks its complete size and digest.
Destination is non-emptyExport does not overwrite the existing directoryOutput admission accepts only an absent or empty destination.
Capture contains credential-like fields or unmarked saved valuesThe bundle may ship sensitive application contentBuild reports field locations and warns the operator to review Evidence before sharing.
State derivation or state capacity admission failsThe environment serves retained replay instead of claiming state supportState preparation reports the reason and selects replay.
A supplied state is malformed or belongs to another captureState loading refuses the input and does not serve itState validation checks Evidence kind, parent capture, template rules, and manifest tools.
A captured write lacks confirming later readsThe tool stays replay-only or refuses a call instead of changing stateState write admission requires a supported, non-contradictory model.
A varied, derived, query-pinned, or bulk write cannot apply its captured rules to the requested targetsThe call is refused and the state remains unchangedWrite planning checks path and query values, body members, held references, generated values, and bulk target rules before commit.
Discovery exceeds its serialization reservationServing fails before the listener bindsTool definitions reserve catalog capacity before building the card.
No cited record can answer a toolThe call returns an error instead of fabricated contentReplay requires a usable retained exchange for the manifest tool.
Replay body or metadata exceeds its limitThe returned view is bounded and marks truncationUTF-8, base64-byte, and metadata limits set explicit flags.
State mutation or RPC response exceeds its budgetThe state change or reply is refused while the service stays boundedState store and response encoding check their budgets before retaining or emitting the result.
An HTTP data-plane request body exceeds the transport boundThe request returns 413 before JSON parsingThe transport checks the declared body size and rejects oversized uploads.
A JSON-RPC request is malformed or a batch has more than 100 messagesThe endpoint returns an invalid-request error instead of processing the batchRPC validation checks member types and batch size before building replies.
Listener host or port is invalid or unavailableThe serve command returns a transport refusalEndpoint parsing and listener classification provide a host or port remedy.
Replay-only mode receives a state methodThe method returns not found because no state data plane existsUse normal serving when clients need data/reset, data/add, or data/get.
A probe has no response bodiesComparison refuses the probe instead of claiming content agreementCapture the probe with capture.network.response_body selected.
A probe makes POST, PUT, or PATCH calls without request bodiesComparison refuses the probe because the environment would receive empty callsCapture the probe with capture.network.request_body selected.
A probe record has no usable request or responseThe record is reported as unobserved and is excluded from step agreementThe comparison report keeps an explicit reason for each unobserved record.
A probe call fails the served tool input schemaThe step is reported as refused instead of being compared as an answered callComparison applies the same input schema check as the serving path.
A step has more differences than the returned detail limitThe detail list is truncated while totals and categories remain availableThe report carries differences_total, differences_omitted, and differences_truncated.
A response body exceeds the replay limitComparison checks status and records the large-body normalization instead of claiming body equalityReplay bounds the body and comparison increments large_bodies.
Cancellation arrives before bundle writingThe build returns cancellation without creating the destinationBuild checks cancellation before the bundle stage.
Cancellation arrives during bundle writingThe build returns cancellation with diagnostics that show the bundle was writtenInspect the output directory and the reported bundle_written status.

Key files

FileWhy to read it
src/…/environmentBuild.tsOne-step capture-to-bundle flow, projection, state choice, warnings, and report
src/…/environmentBuildReport.tsCredential warnings and build naming rules
src/…/environmentExport.tsStable input snapshots, heap admission, authentication handoff, and export result
src/…/environmentSource.tsManifest/capture pairing and retained exchange model
src/…/environmentBundle.tsBundle plan, generated files, launch image, naming, and provenance README
src/…/environmentBundleWrite.tsSafe output publication, retained package identity, and package tarball handling
src/…/environmentBundleTool.tsProgrammatic bundle export contract and Evidence source selection
src/…/environmentReplay.tsRecord matching, replay values, provenance, and output limits
src/…/environmentCompare.tsProbe execution, environment-to-application agreement, ID mapping, and difference reports
src/…/environmentCompareProbe.tsProbe order, request-body capture, and unobserved records
src/…/environmentCompareDiff.tsBody comparison, normalization, difference categories, and detail limits
src/…/environmentTools.tsTool catalog, schemas, discovery reservation, method hints, and environment card
src/…/environmentState.tsState derivation, served tool selection, and state fallback
src/…/environmentStateAnswer.tsState-backed reads, recording fallback, later-read behavior, and answer provenance
src/…/environmentStateStore.tsShared live state, reload behavior, and mutation capacity controls
src/…/environmentStateWriteAnswer.tsConfirmed writes, derived fields, references, generated state values, and later-read effects
src/…/environmentStateWriteQuery.tsQuery restrictions for state-backed writes
src/…/environmentStateBulkAnswer.tsMulti-entity write admission and all-or-nothing bulk updates
src/…/environmentCommands.tsBuild, export, compare, and serve command contracts
src/cli.tsTop-level CLI assembly and environment command registration
src/…/serveEnvironment.tsHTTP routes, MCP tool serving, JSON-RPC limits, and listener lifecycle
src/…/targetContentTransport.tsTarget-content provenance on MCP tool results