docs: remove tracked planning and architecture records (#12856)

This commit is contained in:
morluto authored and GitHub committed 2026-11-20 09:47:41 -05:00
1 parent 42b36e200b
commit a1dec2d2d5
362 files changed
+119 -18521

No files matched your search

+2 -8
View File
@@ -10,8 +10,6 @@ const documentationRoot = fileURLToPath(new URL("..", import.meta.url));
const rewrites: Record<string, string> = {
...documentationRewrites,
"README.md": "documentation.md",
"specs/README.md": "specs/index.md",
"adr/README.md": "adr/index.md",
};
export default defineConfig({
@@ -86,16 +84,12 @@ export default defineConfig({
{ text: "Get started", link: "/installation" },
{ text: "Documentation", link: "/documentation" },
{ text: "Reference", link: "/mcp-contracts" },
{ text: "Roadmap", link: "/roadmap" },
{ text: "Issues", link: "https://github.com/morluto/rea/issues" },
],
sidebar: [
{
text: "Documentation directory",
items: [
{ text: "All guides", link: "/documentation" },
{ text: "Feature specifications", link: "/specs/" },
{ text: "Architecture decisions", link: "/adr/" },
],
items: [{ text: "All guides", link: "/documentation" }],
},
...documentationSections.map((section) => ({
text: section.text,
+2 -12
View File
@@ -670,12 +670,12 @@ export const documentationSections = [
},
{
text: "Settings and recovery",
source: "design/limits-and-recovery.md",
source: "reference/limits-and-recovery.md",
route: "/design/limits-and-recovery",
},
{
text: "REA limit inventory",
source: "design/rea-limit-inventory.md",
source: "reference/rea-limit-inventory.md",
route: "/design/rea-limit-inventory",
},
{
@@ -703,16 +703,6 @@ export const documentationSections = [
source: "development/releasing.md",
route: "/releasing",
},
{
text: "REA roadmap",
source: "development/roadmap.md",
route: "/roadmap",
},
{
text: "Capability composition and ownership",
source: "capability-composition.md",
route: "/capability-composition",
},
{
text: "Testing lanes and provider verification",
source: "testing-lanes.md",
+2 -10
View File
@@ -176,15 +176,13 @@ The [REA website](https://rea.tools/) has worked examples and product pages.
## Development and verification
- [Documentation ownership and authoring](development/documentation.md)
- [Settings and recovery](design/limits-and-recovery.md)
- [REA limit inventory](design/rea-limit-inventory.md)
- [Settings and recovery](reference/limits-and-recovery.md)
- [REA limit inventory](reference/rea-limit-inventory.md)
- [MCP tool design](development/tool-design.md)
- [Testing REA](development/testing.md)
- [Client and agent verification](development/client-verification.md)
- [Reconstruction readiness conformance](development/reconstruction-readiness.md)
- [Releasing REA](development/releasing.md)
- [REA roadmap](development/roadmap.md)
- [Capability composition and ownership](capability-composition.md)
- [Testing lanes and provider verification](testing-lanes.md)
- [Measure MCP catalog costs in Codex](mcp-catalog-evaluation.md)
- [Static analysis in GitHub Actions](ci-analysis.md)
@@ -197,12 +195,6 @@ The [REA website](https://rea.tools/) has worked examples and product pages.
- [Recorded signal inspection](guides/signals/signal-recordings.md)
## Architecture and authoring
- [Architecture map](https://github.com/morluto/rea/blob/main/docs/architecture/architecture.mermaid)
- [Feature specifications](specs/README.md)
- [Architectural decision records](adr/README.md)
<a id="machine-owned-documentation"></a>
## Generated files and release records
-9
View File
@@ -1,9 +0,0 @@
# Architectural decision records
Store one actual decision per `docs/adr/<domain>/<decision-slug>.md`, without a
global sequence number. Use meaningful names and the Michael Nygard sections:
Status, Context, Decision and Consequences. Link each decision from its owning
feature specification.
See [the authoring guide](../development/documentation.md#feature-lifecycle) for
the distinction between specifications, roadmaps and isolated decisions.
-102
View File
@@ -1,102 +0,0 @@
# Split `src/domain` by subsystem behind one entry point
## Status
Proposed, 2026-11. Moves are scheduled one subtree per change after the open
JavaScript-analyzer and output-view work on the same files has merged.
## Context
`src/domain` is the pure layer: it may import only `domain` and `contracts`, and
the module-boundary check enforces that. Because purity was the only rule, any
I/O-free code moved there regardless of its role. Measured on 2026-11-15:
| Subtree | Production files | Lines | Role |
| ------------------------ | ------------------------------------------------------------------------ | ----- | ---------------------------------------------------------------------------- |
| `domain/javascript/` | 180 | 62.8K | static JavaScript analysis engine |
| `domain/analysisView/` | 147 | 43.5K | output projection: summaries, paging and row selection for retained Evidence |
| `domain/desktop/` (part) | `appBuild`, `appExport*`, `appDownloadInstall`, `appTask*`, `shellQuote` | — | shell, Python and inline Node script generation for desktop environments |
Outside the subtree, 108 production files import 64 different modules inside
`domain/javascript/`, and 70 files import 42 modules inside
`domain/analysisView/`. Nothing states which of those modules are the
subsystem's interface, so every internal module is public by accident and a
refactor inside the engine can break any of 108 importers.
Splitting `src/domain` into layer folders such as `analysis/` and
`presentation/` would only rename the problem: each would again collect
unrelated subsystems with no interface.
## Decision
Each large subsystem in `src/domain` becomes its own top-level module with one
public entry point. Code outside the module imports only its `index.ts`; files
inside the module import each other directly.
| Module | Moves from | Public entry |
| ----------------------- | ---------------------------------------------------- | ------------------------------- |
| `src/javascriptEngine/` | `src/domain/javascript/` | `src/javascriptEngine/index.ts` |
| `src/analysisView/` | `src/domain/analysisView/` | `src/analysisView/index.ts` |
| `src/desktopScripts/` | the script-generation files of `src/domain/desktop/` | `src/desktopScripts/index.ts` |
- **Names.** Top-level `src/` directories are camelCase. `src/javascript/`
already names the JavaScript artifact provider, so the engine is
`javascriptEngine`.
- **Layers.** Each module is declared in `scripts/lib/module-layers.mjs`. The
engine and the view projection are pure and stay in the `domain` layer (the
contracts layer imports their schemas today); the module-boundary purity rule
extends to them. `desktopScripts` is pure as well. A later change may give a
module its own layer once its schema consumers in `contracts` are resolved.
- **Entry point rule.** The boundary check gains a table of subsystem modules
and their entry file. An import that resolves into a module from outside it
must resolve to the entry file, including type imports, re-exports and
`#`-mapped specifiers. Undeclared directories already fail the layer check,
so a new subsystem chooses a layer and, if it has an interface, an entry.
- **Entry contents.** `index.ts` re-exports exactly the symbols used outside the
module at the time of the move; it is the only barrel the module has. A new
external use adds an export there, which makes interface growth visible in
review.
- **Moves.** Files move with `git mv`; each move commit contains only renames,
import specifier updates and the new `index.ts`, and is listed in
`.git-blame-ignore-revs` once it has merged. One subtree per change, in the
order `desktopScripts`, `analysisView`, `javascriptEngine`, each after the
open changes that edit that subtree have merged.
- **Not part of this decision.** No npm workspace or package split. Wire
schemas that `contracts` reads from these modules stay where they are until
the operation registry decides their owner.
### TypeScript project references
Project references split the program into separately built projects and allow
incremental type checks per module. They do not enforce the entry rule: a
project that references another may import any of its files, not only
`index.ts`. The entry rule therefore stays in the boundary check whether or not
references are adopted. They are not adopted now:
- **Cost.** Each module needs its own `tsconfig` with `composite: true` and
declaration emit; `tsconfig.json`, `tsconfig.build.json` and the two
verification configs, the turbo typecheck task and `scripts/run-typescript.mjs`
change from one program to a `tsc --build` graph. References may not form
cycles, and `contracts` and `domain` import each other today, so the engine
and view modules cannot be referenced projects until that cycle is gone.
Test files that import module internals would need their own project per
module.
- **Benefit.** The compiler refuses an import from a project that is not
referenced, which checks dependency direction between modules (the layer
check already does this), and warm type checks may be faster. The type-check
time benefit is unmeasured.
- **Revisit** when `contracts <-> domain` has no mutual imports, starting with
`javascriptEngine` (the largest and most self-contained module), and measure
cold and warm `npm run typecheck` before and after.
## Consequences
- Each subsystem has a written interface; internal refactors cannot break
outside importers without changing `index.ts`.
- `src/domain` shrinks to Evidence, results, errors, identity, comparisons and
format declarations, matching its description in the architecture map.
- The moves touch every importer once; changes in flight on the same files need
a rebase. Scheduling one subtree per change after the related open work
merges limits that cost.
- The entry barrel adds one hop for readers and a re-export list to maintain;
the alternative, every module public, is what produced 64 imported internals.
@@ -1,63 +0,0 @@
# Declare each provider's entry files instead of a provider barrel
## Status
Accepted, 2026-11-15. Decided in issues #11358 and #11360.
## Context
Application, composition and the CLI/MCP adapters import provider folders
(`src/ghidra/`, `src/native/`, ...) directly. On 2026-11-15, 238 such imports
reached 167 files in 39 provider folders. Nothing stated which of those files a
provider meant to expose.
The rule for `src/domain` subsystems in
[domain-subsystems.md](domain-subsystems.md) is one `index.ts` per module.
A prototype with an `index.ts` for each provider showed that this does not fit
providers. Composition, the capability declarations and the CLI load single
provider files on purpose: some through dynamic `import()`, some for metadata
only, so that unused providers are never loaded. A barrel pulls in everything
it re-exports. Static runtime import closure, measured on the prototype:
| Importer | Single files | Through `index.ts` |
| --------------------------------- | ------------ | ------------------ |
| `capabilityDeclarations` | 55 | 1408 |
| `doctorRuntime.ts` | 1081 | 1255 |
| `javascriptAnalysisWorkerProcess` | 225 | 334 |
| `webSourceLocations` | 161 | 226 |
A separate metadata entry kept `capabilityDeclarations` at 87 files, but it
would need two entries and a barrel discipline in every provider.
## Decision
`ENTRY_FILES` in `scripts/lib/module-layers.mjs` lists each provider's entry
files, relative to `src/<provider>/`. These are the files that composition and
the adapters wire: provider classes, identities, metadata, worker servers,
doctors and commands. The module-boundary check counts every application,
composition or adapter import of any other provider file in the `entry` map of
`scripts/lib/module-layers.baseline.json`. That count may only shrink.
- **Seed.** The entry files are the provider files that composition and the
adapters imported when the rule was added. Application imports of other
provider files stay counted (67 imports: 41 into `desktop`, 11 into
`artifacts`, 8 into `reference`, 3 into `dotnet`, 2 into `browser` and 2
into `frida`), because application should reach that code through ports.
- **Surface growth.** A new entry file is a reviewed change to the provider's
public surface, and it appears in the diff of `module-layers.mjs`.
- **Other units.** `src/resources`, the shared provider toolkit, declares its
`index.ts` as its only entry file. Every other unit reaches it through that
file.
- **Provider to provider.** The entry rule does not apply here. Every import of
another provider folder is already counted in the `crossProvider` map.
- **Not decided here.** No `index.ts` per provider, and no change to the domain
subsystem rule.
## Consequences
- Each provider's public surface is written down, and lazy and metadata-only
loading stays as it is.
- A rename of an entry file must update the table. A unit test fails when an
entry file does not exist.
- The table states only which files are public, not which symbols. Symbol
growth inside an entry file is not reported.
-135
View File
@@ -1,135 +0,0 @@
# Evidence names its subject with one tagged target identity
## Status
Accepted (2026-11-15). Implementation lands in slices: the first slice does not
change Evidence IDs, and the slice that does is breaking (marked `!`, with
recreate-observations migration notes) and ships with the next Evidence format
revision.
## Context
"The target" is defined three ways, with different fields:
| Definition | Fields | Owner |
| ---------------------------- | ------------------------------------------------------------------------------------------------ | ----------------------------------------------------- |
| Evidence subject identity | `digest.sha256`, `format`, `architecture` | `evidenceSubjectIdentity` in `src/domain/evidence.ts` |
| Snapshot target | `sha256`, `kind`, `architecture`, `format`, plus `entry_point` (raw, DOL) or flash offsets (ESP) | `snapshotTarget` in `src/domain/analysisSnapshot.ts` |
| Snapshot cache stage compare | `JSON.stringify` of the snapshot target (key-order sensitive) | `AnalysisSnapshotCache.stage` |
The Evidence subject schema can only describe a hashed local file. Of 120
non-test `createEvidence` calls, 50 pass no subject and receive the generic
limitation "Artifact identity is unavailable for this observation." (measured
on main at c56fffcd75): application 29, contracts 7, gdb 6, server 3, domain 3,
rizin 1, cutter 1. Every gdb, rizin, live-browser and process-capture record is
subject-less, because a URL, a running process or a debugger session cannot be a
subject. Comparison and workflow records are subject-less because they derive
from several linked records.
Consequences today:
- Two raw-binary observations of the same bytes at different entry points share
an Evidence subject identity unless the operation echoes the entry point into
`parameters`. The snapshot target keeps them apart.
- Debugger, browser and process Evidence cannot be bound to what it observed.
A rebuilt binary under the same path, or a different page at the same tool
input, is indistinguishable in the record.
- Consumers that compare targets each reimplement the comparison.
The Evidence format revision (`src/domain/evidenceFormat.ts`, #10861) gives
Evidence one place to evolve. Phase 5 deferred two items to this decision: the
target identity, and a per-record format marker. A standalone record (outside a
bundle) does not declare its format today.
## Decision
1. **One tagged identity.** `src/domain/targetIdentity.ts` owns
`TargetIdentity`, discriminated by `kind`:
- `file`: `sha256`, `format`, `architecture` (nullable) and `selection`.
`selection` holds the facts that select what was analysed in the bytes:
the raw or DOL entry point, ESP flash and partition-table offsets, and a
universal-binary slice. It is `null` when nothing is selected.
- `url`: the URL with userinfo removed and its `origin`. Userinfo is a
transport credential and is never part of an identity.
- `process`: `pid`, `start_time` (the platform start identity the
`src/process/` identity primitives read for that PID), and
`executable_sha256` (nullable when the executable could not be read
stably). A PID alone does not identify a process after exit or reuse, so
the start time is required: a producer that did not read it names an
`unknown` (`not-observed`) target rather than claiming an identity it
does not have.
- `session`: the `session_kind` (`rizin`, `gdb`; later kinds such as
`browser-scenario` are added when a producer needs them), the session
`id` REA minted, and the `target` the session was opened on: the launch
file hashed when the session started, or `unknown`. Later debugger
commands do not rebind the session.
- `unknown`: a `reason` from a closed set:
`derived-from-linked-evidence` (comparisons and workflows; their sources
are already committed through `evidence_links`), `not-observed`,
`unsupported-subject`, and `withheld-by-caller` (REA observed the
identity and the caller chose not to record it, for example process
capture PID normalization).
Display facts (`name`, `local_path`) stay beside the identity and are not
committed, as today.
2. **One key.** `targetIdentityKey(identity)` is the RFC 8785 canonical digest
of the identity. Evidence, analysis snapshots, caches and session binding
compare targets only through it. `evidenceSubjectIdentity`,
`sameEvidenceSubjectTargetIdentity`, `snapshotTarget`'s field-by-field
`snapshotMatchesTarget` and the `JSON.stringify` compare are deleted.
3. **Every record has a subject.** `createEvidence` takes a `TargetIdentity`,
not `undefined`. A producer that cannot name its subject passes
`unknown` with a reason, so "no identity" is an explicit, reasoned value.
`MISSING_EVIDENCE_SUBJECT_LIMITATION` is removed; the reason replaces it.
4. **Evidence format revision 2.** The new subject changes the committed
content of every Evidence ID, including file subjects (which gain `kind` and
`selection`). It therefore ships as one breaking revision:
- `EVIDENCE_FORMAT_REVISION` becomes 2 and its revision note names the
subject change.
- Every Evidence record carries `evidence_format: 2`, so a standalone record
declares its format too. The marker is not part of the ID's committed
content; it selects the reader, and `admitEvidenceBundleFormat` gains a
per-record check with the same refusal.
- Analysis snapshots embed Evidence and target identities, so snapshot
files from revision 1 are refused at open.
5. **No migration of stored Evidence.** An Evidence ID is a content
commitment. Rewriting a revision 1 record under a new subject would claim an
observation REA did not make. Revision 1 bundles, records and snapshots are
refused with `RECREATE_EVIDENCE_GUIDANCE` (recreate the observations with the
current release). The bundle reader already does this for pre-revision
bundles.
### Slices
1. Introduce `TargetIdentity` and `targetIdentityKey`. Use them for snapshot
and cache comparison (replacing the `JSON.stringify` compare), and let
`BinaryTargetResolver` produce the file identity through the shared stable
file hasher. No Evidence ID changes; not breaking.
2. Evidence format revision 2 (breaking, `!`): the subject becomes
`TargetIdentity` plus display facts; the per-record marker is added; the 50
subject-less sites pass an explicit identity: `unknown`
(`derived-from-linked-evidence`) for comparisons and workflows, and the
best identity each producer already holds for the rest.
3. Producers gain real identities where they have the facts: gdb and rizin
`session` identities bound to the opened file, live browser `url`, process
capture `process`. Each is its own PR and changes only that producer's IDs,
which is still within revision 2 if it lands before the release; otherwise
it needs its own revision.
## Consequences
- Every Evidence ID changes once, in the release that ships revision 2.
Callers that stored Evidence IDs or bundles must recreate them; the release
notes carry the `BREAKING CHANGE` footer and this migration.
- Debugger, browser and process Evidence can be bound to what it observed, and
two observations that differ only in their selection (entry point, slice,
flash offset) no longer share a subject.
- Target comparison has one owner. Session registries can store the identity at
open and revalidate it before each call (a follow-up, not part of this
decision).
- `unknown` keeps "the identity was not observed" visible as a fact with a
reason, instead of an absent field with a generic limitation.
- Revision 2 also takes the remaining fields that are optional only because
older Evidence may omit them. Those that every producer writes become
required in the same revision.
@@ -1,203 +0,0 @@
# JavaScript effects invalidate reads through one effect log
## Status
Accepted (2026-11-15) for plan W10 step 3. Implementation lands in slices, one
target kind per PR. Each slice removes the reader-side checks it replaces and
reports its corpus measurement.
## Context
The semantic engine records effects while it indexes a source:
- binding writes;
- member writes and escapes from the member-mutation phase;
- ambient writes and escapes;
- direct `eval` sites that may rebind names in visible activations;
- global-code sites (`eval`, `Function`) that may replace globals.
Readers then pull invalidation by calling one helper per effect kind before
they trust a value. Measured at `104b1a35b4`, outside the owner module
`javascriptSemanticOpaqueEffects.ts`, 32 calls in 14 files make this check:
| Helper | Calls | Files |
| ----------------------------------------- | ----: | ----: |
| `referenceMayHaveChangedAt` | 12 | 8 |
| `semanticOpaqueBindingReadMayHaveChanged` | 7 | 5 |
| `semanticOpaqueGlobalMayHaveChanged` | 4 | 4 |
| `semanticBindingMayHaveOpaqueEffect` | 4 | 2 |
| `semanticOpaqueNameMayHaveChanged` | 3 | 2 |
| `semanticOpaqueBindingEffects` | 2 | 1 |
Most readers combine two to four of these calls. For example, an intrinsic
read combines `semanticOpaqueNameMayHaveChanged`,
`semanticOpaqueGlobalMayHaveChanged` and `ambientEscapes.covers`, and a
receiver walk calls `referenceMayHaveChangedAt` for both the method and
`__proto__`.
A reader that omits one of these calls reports a stale fact with complete
coverage. The direct-eval invalidation fix had to land twice, six days apart:
`9ac76d3d94` for semantic values and `26e155987f` (#7053) for Electron reads.
The structural audit (report 14, C1 point 5) records this as "readers must
ask".
The classification of implicit execution (#10605, #10631) and the
member-mutation work allowance (#11144) do not replace these checks. They
decide where code may run and bound the work, but readers still decide
separately whether a recorded effect applies to their read.
## Decision
1. **One effect log owner.** `javascriptSemanticEffectLog.ts` holds every
recorded effect, keyed by its target:
- a binding id;
- an ambient root path;
- an activation scope, for name introduction by sloppy direct `eval`;
- global code.
Each entry keeps the effect node, its kind and its property path.
Producers append to the log when they record an effect. Nothing else
writes to it.
2. **One read query.** Readers ask whether a read of a target, at a site and
for a property path, may observe an earlier effect:
`effectLog.mayObserve(read, target, path)`. They state the value they
read, not the effect kinds that could change it.
The owner keeps the existing proofs inside this query: effect timing,
capture-before-effect, read-before-effect within one activation, strict
and sloppy `eval`, and path disjointness. No reader evaluates these
proofs.
3. **Caches keep the whole-state clear.** Recording an effect still calls
`clearSemanticValueCaches`, which drops every cached value. Per-target
invalidation was measured and declined; see
[Per-target cache invalidation](#per-target-cache-invalidation). A
value-engine read that consults a cache therefore sees every earlier
effect without asking for it.
4. **Completeness is explicit.** The log records which producer phases are
complete. Before the member-mutation phase completes, a member-path query
answers "may observe", which is the current conservative
`referenceMayHaveChangedAt` behavior when nothing is indexed. A phase
refused by its work allowance never completes.
5. **Guard.** After each slice, an architecture guard forbids importing the
superseded helpers outside the effect log. When the last slice lands, the
helpers are deleted and the guard prevents a new reader-side check from
returning.
## Migration
Slices move one target kind at a time, so each stays reviewable and
measurable:
1. Global code and introduced names. This covers
`semanticOpaqueGlobalMayHaveChanged` and `semanticOpaqueNameMayHaveChanged`
at intrinsic and global reads (typed arrays, timers, async effects, module
interop and expression shapes).
2. Binding rebinding. This covers `semanticBindingMayHaveOpaqueEffect`,
`semanticOpaqueBindingReadMayHaveChanged` and `semanticOpaqueBindingEffects`.
3. Member paths. This covers `referenceMayHaveChangedAt` (receiver walks,
network, Electron, map, route and resource readers) and the effects view in
`visitSemanticReferenceEffectsAtSite`.
Each slice is measured cold on the 14 published bundles of the W10 corpus,
before and after. The measurement covers per-value status digests, the total
`unknown` count, elapsed and CPU time, and peak RSS. A slice that changes no
proof should change no status.
The slice stops and is reported, not merged, if it shows either of these:
- `unknown` rises by more than 0.1% of examined values on the corpus, or on
any single bundle;
- a status changes from `unknown` to a definite value. That is a soundness
regression and is never accepted.
Merging `JavaScriptSymbolicBindings` (W10 step 4, audit C2) follows the last
slice, because its one consumer should read values through the same log.
## Rejected alternatives
### Folding global-code effects into `isUnmodifiedGlobalReference`
One prototype added the global-code check (`eval`, `Function`) to
`isUnmodifiedGlobalReference`, so that every caller of that helper would
refuse a global that opaque code may replace. It was measured at `3d9d35ab26`
on the 14 corpus bundles:
- Static findings and value statuses did not change. No status changed from
`unknown` to a definite value, and the `unknown` count stayed at 69,348.
- The full semantic IR changed on the 4 bundles that contain `Function(`.
Callers of the helper dropped operation records without recording an
`unknown` in their place:
- handlebars: boundary operations fell from 9 to 3.
- isomorphic-git: boundary operations fell from 37 to 10 and timer
operations from 6 to 0. Of the promise operations, 26 were removed and
17 became unresolved awaited expressions.
- underscore: timer operations fell from 7 to 0 and boundary operations
from 3 to 0.
- vue: boundary operations fell from 36 to 2, timer operations from 9 to 0
and promise operations from 29 to 23.
The only `Function(` site in handlebars is `Function("return this")()`, which
cannot replace a global, so none of the handlebars removals is justified.
The fold is rejected: it silently drops records instead of marking them
unknown. A read that opaque code may change must stay in the IR and be
reported as unknown, not omitted. Global-code reads go through the effect log
query (decision 2) instead.
### Exempting constant-source `Function` bodies
Exempting constant `Function` bodies that cannot write, such as
`return this`, would have removed the handlebars regressions. The rule is
not adopted: it adds a new precision proof for one observed pattern and is
not needed once readers ask the effect log. It can be proposed separately
with its own measurement.
### Per-target cache invalidation
The first draft of decision 3 invalidated only the cached values that
depend on an effect's target. Existing caches store a result under the
binding it was computed for (`bindingId`), even when it read other bindings,
and the expression and capture caches have the same shape. Per-target
invalidation would therefore need every cached value to record the targets
it read, plus a reverse index from target to dependents.
It was measured at the head of #11282 (effect log slice 1) on the 14 corpus bundles, with
`clearSemanticValueCaches` instrumented locally:
- Clears per bundle range from 1,340 (underscore) to 32,269 (openpgp).
Almost all come from the member-mutation phase, which clears once per
recorded effect.
- The binding values those clears discard are few: 0 to 306 primitive and
36 to 1,391 caller-independent values per bundle. The expression and
capture caches are `WeakMap`s, so their entries were not counted.
- Upper bound: with every clear disabled (unsound; the IR changes on all 5
measured bundles), CPU time fell by 9% on zip.js and isomorphic-git, 8% on
openpgp and 4% on rxjs, and did not change measurably on vue. Peak RSS did
not change. These are 2 alternating runs per bundle under a load average
of 9 to 11, so the smaller figures are within noise.
Per-target invalidation could recover only part of that 4 to 9% bound, at
the cost of dependency tracking in every value cache and a reverse index.
It is declined.
Clearing once per member-mutation convergence round instead of once per
effect is also declined. Values read later in the same round would be stale,
and there is no argument yet that the round's fixed point makes them safe.
## Consequences
- A new reader cannot forget an effect kind, because it asks one question
about the value it reads.
- Effect proofs have one owner. A precision fix, such as a new disjointness
proof, applies to every reader at once.
- Cache invalidation is unchanged: every recorded effect still clears the
whole value state. Removing every clear would save at most 9% CPU on the
measured bundles.
- The log retains effect entries until the source's analysis ends. They are
already retained today in `bindingWrites`, `memberWrites`, `escapedPaths`,
the ambient effect lists and `opaqueEffects`. The log replaces those
indexes rather than adding a copy.
- Until the last slice lands, readers use both forms. The guard's counted
baseline can only shrink.
-99
View File
@@ -1,99 +0,0 @@
# Native operation results are parsed once at the operation port
## Status
Accepted (2026-11-15). The maintainer decisions are recorded under
[Decision](#decision); implementation lands one reader per PR.
## Context
`AnalysisOperationPort.execute` returns `AnalysisExecution` whose `result` is
an untyped `JsonValue`. Four provider-neutral readers parse that value again,
each with its own schema and failure policy:
| Reader | Operation | Schema applied | On mismatch |
| ---------------------------------- | ------------------------------------- | ------------------------------------------------------------- | ------------------------------------------- |
| `EnhancedLiteralTracing` | `search_strings`, `search_procedures` | `nativeInventoryRowsSchemas.*` | `AnalysisOutputError` |
| `NativeDispatchMetadataInspection` | `list_names` | `names.element.strict()` | `AnalysisOutputError` with partial Evidence |
| `functionInventory` | retained `list_procedures` Evidence | `names.element.extend({ address: nativeAddressInputSchema })` | throws the payload error |
| `nativeInventoryView` | retained `list_*` Evidence | `nativeInventoryRowsSchemas.*` | view error |
Ghidra and Hopper already validate these replies at their clients against the
same domain schemas; other providers do not. A consumer therefore cannot know
whether a `JsonValue` it receives was checked, so each one checks again with a
slightly different contract. A "validated" marker on the execution was
considered and rejected: it adds a second representation of the same fact and
consumers would still need the typed value.
## Decision
1. **Named operation contracts.** `src/domain/native/nativeOperationFacts.ts`
exports one named contract per native inventory operation (`list_names`,
`list_procedures`, `search_procedures`, `list_strings`, `search_strings`).
Each contract carries its operation name and its row schema from
`nativeInventoryRowsSchemas`, with the exact fact type. Readers import the
contract they need; nothing looks a contract up by operation name or by
catalog order. Other operations gain a contract only when a reader needs
one.
2. **Name rows are lenient.** A row with fields the contract does not name is
accepted and the unknown fields are dropped from the typed fact, for
forward compatibility with provider extensions. This matches three of the
four readers today. `NativeDispatchMetadataInspection`'s `.strict()` row
check is removed.
3. **The port parses once: `executeFact`.** The application port module
`src/application/AnalysisOperationFacts.ts` exports
`executeFact(port, contract, parameters, options)`. It runs the
operation through the given port's `execute` and parses the result with the
contract once, returning
`{ execution: AnalysisExecution; fact: Fact }`. A mismatch is an
`AnalysisOutputError` naming the operation, keeping the source execution as
partial observed Evidence. The policy is the same for every provider and
every reader. Because it runs through the port's own `execute`, a wrapping
port (`WorkflowEvidence`, admission, managed-tool wrappers) observes and
records the call exactly as it does today, with no forwarding code.
4. **Evidence keeps the source value.** The typed fact is a projection for
consumers. `AnalysisExecution.result` and the Evidence built from it keep
the provider's value unchanged, including the unknown fields that the
lenient contract drops from the fact. Nothing writes the parsed fact back
into Evidence.
5. **Readers consume facts.** The four readers drop their local schemas.
Live readers call `executeFact`. Retained-Evidence readers
(`nativeInventoryView`, `functionInventory`) read the payload of Evidence
the port produced through the same contract's schema, keyed by the parent
operation's contract. Reader-specific requirements stay with the reader as
a step over typed rows, not as a different parse of the raw value:
`functionInventory` parses each row's address with
`nativeAddressInputSchema`. Evidence produced before this change still
parses, because the contracts are the schemas those readers used.
6. **Provider protocol checks stay.** Hopper's reply table
(`HopperReplyContracts`) and Ghidra's per-operation result schemas remain:
each owns its raw provider protocol and rejects a malformed reply at the
client with provider-specific recovery. The port parse is the
provider-neutral fact parse and is not a duplicate of either; no reader
re-parses after it.
## Alternatives considered
- **A required `executeFact` method on every `AnalysisOperationPort`.**
Measured on 4b31661441: making the method required on the port (with
provider clients moved to an execute-only base) produced 626 type errors in
242 files, almost all test fakes and object-literal ports that would each
forward the same derived function. A wrapping port that forwarded the
method to its inner port would also bypass its own observation, so each
wrapper would have to re-derive it from its own `execute` anyway. The
port-module function gives every port the same typed read with one
implementation.
- **Make `AnalysisExecution` generic in its operation.** Rejected: every
provider and Evidence projection would carry a type parameter for a fact
only four readers consume.
## Consequences
- One contract and one failure policy per operation; a provider that returns
malformed rows fails at the port with the same error for every consumer.
- Unknown row fields stay visible in Evidence and disappear only from the
typed fact.
- Implementation order: contracts and `executeFact` with no consumer change,
then one PR per reader, deleting its local schema: `nativeInventoryView`,
`functionInventory`, `NativeDispatchMetadataInspection`,
`EnhancedLiteralTracing`.
-61
View File
@@ -1,61 +0,0 @@
# One client table for setup, maintenance and `rea mcp add`
## Status
Accepted, 2026-11.
## Context
`rea mcp add` kept its own table of clients, locations and file dialects,
separate from the table that setup, doctor, update and uninstall read. A client
registered through `mcp add` was invisible to the lifecycle commands, and each
table interpreted the same configuration files independently. Some clients
(Gemini, Junie, Goose, Kilo) decide which registration they load from more than
one file, from environment variables, or from layers REA must not change, so
two interpretations drifted in where to write and what the effective entry is.
## Decision
[`SupportedClients.ts`](https://github.com/morluto/rea/blob/main/src/application/SupportedClients.ts)
is the single client table. Each row is the owner of one client's user-scope
registration, and every command reads that row:
- **Dialect and reader facts are separate fields.** `format` names the file
dialect REA parses and writes. Read-scope facts that decide what the client
loads without being write targets (`geminiSettings`, `junieSettings`,
`zcodeFallbackPath`, the ordered `configPaths`) are separate fields, so a
consumer never infers loading rules from the dialect.
- **`mcpAdd` exposes a row to `rea mcp add`.** It adds aliases and project paths
only; the user-scope registration uses the row's location, format, profile and
read-scope facts, so `mcp add` does not keep a second definition of a table
client.
- **Locations that depend on observed layers use one asynchronous hook.**
A row's `layeredLocation` returns the write target and every layer in load
order once present files are observed. `resolveSupportedClients` applies it
for setup, doctor, update and uninstall, and `mcp add` resolves Kilo's user
scope through the same location owner; the synchronous row keeps the default
target and every candidate layer.
- **Lower layers can be read-only.** A row with `readOnlyLowerLayers` has
layers before `configPath` that belong to the system or an administrator. REA
reads them to compute the effective registration and writes only
`configPath`. An inline layer that a client reads from its environment
(Kilo's `KILO_CONFIG_CONTENT`) is `inlineConfiguration`: the
highest-precedence layer, read for the effective registration and never
written.
- **Uninstall refuses rather than misreport.** When a read-only layer would keep
REA's enabled registration in effect, or removing the user entry would expose
one, uninstall makes no change and names the layer's owner as the recovery.
When only an inline layer sets REA's enabled entry, uninstall reports that
client as failed and names the variable to edit, as doctor does.
An unreadable layer leaves the outcome unknown and also stops uninstall.
## Consequences
- Doctor, update and uninstall see every registration `mcp add` writes, and a
client added to the table is available to all commands at once.
- A client-specific loading rule has one parser, owned by the row's field;
consumers use its parsed facts instead of rereading raw files.
- Commands that need the layered location must call `resolveSupportedClients`;
the synchronous `supportedClients` view is not sufficient for those rows.
- Uninstall can report a registration it cannot remove; that client then needs
its layer owner's action before uninstall completes.
+1 -3
View File
@@ -201,6 +201,4 @@ Credential-name warnings point to values worth reviewing; they do not remove
those values or establish that the recording contains no credentials.
For direct MCP serving, replay behavior, state controls, and resource limits,
see the [environment reference](agent-environments.md). The
[implementation index](specs/agent-environments/README.md) links the contributing
PRs and their verification records.
see the [environment reference](agent-environments.md).
-3
View File
@@ -3,9 +3,6 @@
For a first environment, start with the
[quickstart](agent-environments-quickstart.md): record an app or use a saved
session, build and run the environment, and add tasks and reward checks.
The [implementation index](specs/agent-environments/README.md) links
the contributing PRs and their verification records. This page is the detailed
command and behavior reference.
Use `rea environment-build` to turn one recorded capture into an agent
environment bundle in one offline step: a folder `agent-env run` builds and
-236
View File
@@ -1,236 +0,0 @@
graph TD
%% Selected layer owners and dependency/wiring paths, not a directory or import inventory.
%% Current deep-provider candidates are wired in src/composition/binary.ts.
%% Layers, innermost first: kernel (src/kernel/: dependency-free helpers such as
%% errorMessage and Node codec-result decoding), domain, contracts, foundation, ports (src/ports/:
%% interfaces providers implement), providerCore (src/providers/: the shared
%% provider core), providers, application, composition, adapters. An import may point to the same or an
%% inner layer. scripts/lib/module-layers.mjs declares the layer of every
%% top-level src/ directory and root file; verify:module-boundaries fails on
%% an undeclared unit and ratchets the recorded outward imports and mutual
%% imports in scripts/lib/module-layers.baseline.json.
%% Provider boundary: a provider folder (src/ghidra/, src/native/, ...)
%% imports inner layers, including the shared provider core (src/providers/,
%% which may not import a provider folder), and its own files. Importing another provider folder is recorded debt
%% unless PROVIDER_DEPENDENCIES declares the file (inspector -> browser CDP
%% client, browser and desktop -> electron fuse reader, captures -> pcap
%% tshark configuration); shared pieces belong in
%% ports, foundation or the provider core. Application, composition and
%% adapters reach a provider through the entry files it declares in
%% scripts/lib/module-layers.mjs (ENTRY_FILES; no per-provider barrel).
%% Every unit reaches the shared provider toolkit (src/resources/) through
%% src/resources/index.ts.
%% The baseline counts both kinds of import per unit pair; both only shrink.
subgraph "Entry Points"
CLI["src/cli.ts + src/cli/<br/>One-shot CLI adapter<br/>setup, diagnostics, analysis, decompilation<br/>cliLoader: recorded registrar per command, complete CLI otherwise"]
MAIN["src/main.ts + src/main/<br/>MCP server adapter: stdio default, streamable HTTP opt-in<br/>config, session, process lifetime"]
DISPATCH["scripts/rea.mjs<br/>Executable dispatcher<br/>routes mcp / mcp --http / one-shot"]
end
subgraph "Production Composition"
COMPOSITION["src/composition/<br/>fresh typed provider and session factories<br/>one-shot binding and independent optional loading<br/>typed capability bindings: construction, availability and retryable lifetimes<br/>pure capability declarations feed provider catalogs"]
end
subgraph "Adapters"
SERVER["src/server/<br/>MCP request translation<br/>createServer, tool registration, toolResult<br/>http/: streamable HTTP listener and node:http bridge"]
HOPPER_BRIDGE["bridge/hopper_bridge.py<br/>Runs inside Hopper<br/>adapts operations to Hopper Python API"]
GHIDRA_BRIDGE["bridge/ghidra/ReaGhidraBridge.java<br/>Packaged HeadlessScript<br/>inventory, decompiler, references, CFG"]
INSTALL["src/cli/ + src/application/Setup*<br/>Host installation adapters<br/>macOS: verified vendor DMG to ~/Applications<br/>Linux: verified vendor package + apt/dnf/pacman"]
end
subgraph "Application Layer"
APP["src/application/<br/>Shared CLI/MCP workflows<br/>enhanced analysis and investigations"]
SESSION["SessionProviderRouter + BinarySession<br/>one immutable deep binding per target<br/>disjoint auxiliary routing"]
REGISTRY["AnalysisProviderRegistry<br/>sorted deep candidates<br/>deterministic selection, no fallback<br/>ProviderInspectionScope: prerequisite observation lifetime"]
RECORDS["src/application/investigation/<br/>composed InvestigationRecords + narrow ports<br/>EvidenceLedger and Unknown ownership"]
LIFETIMES["CapabilityScope<br/>host-owned service close capabilities<br/>released peers removed; failed cleanup retained for retry"]
SNAPSHOT["BinarySessionRecords + AnalysisSnapshotCache<br/>binary target/profile snapshots and session file ownership<br/>record coordination and post-commit notifications"]
JS_RECON["src/application/javascript/ + src/artifacts/javascript/<br/>JavaScript artifact reconstruction<br/>directory/ASAR reads<br/>AST-only bundle projection"]
end
subgraph "Provider Layers (selected adapters)"
PROVIDER_OWNERS["src/providers/<br/>shared deferred client owners<br/>exact cleanup retry and attributed failures"]
PWNTOOLS["src/native/pwntools/ + src/native/pwndbg/<br/>BYO offline ELF/core adapters<br/>owned snapshots/Python and optional core-only GDB<br/>unchanged upstream parsers, ABI structures and mapping API"]
WASM["src/wasm/<br/>caller-supplied WABT; immutable artifact inspection<br/>owned process supervision and retryable workspace cleanup"]
APKSIG["src/apkSignature/<br/>in-process APK Signing Block + v1 reader<br/>bounded single read, no device or execution"]
EVM["src/evm/<br/>unchanged EVMole/WASM in bounded owned worker<br/>explicit carrier parsing and inferred interface adapter"]
HOPPER["src/hopper/<br/>Hopper launch & Unix-socket protocol<br/>BridgeLauncher, HopperClient, protocol"]
GHIDRA["src/ghidra/<br/>Ghidra discovery, profile & function analysis<br/>snapshot, Unix/Windows transport, bounded lifecycle"]
IDA["src/ida/<br/>Upstream MCP contract adaptation<br/>live GUI binding or owned headless database"]
IDA_MCP["External ida-pro-mcp<br/>GUI proxy or database supervisor<br/>upstream installation and engine lifecycle"]
KUNA["src/kuna/<br/>BYO Kuna decompiler, a deep analysis candidate<br/>discovery reads metadata only; version probe when a target opens"]
AUX["src/artifacts/ + src/native/<br/>artifact inventory, bounded directory triage and extraction<br/>format readers and native capabilities"]
BROWSER["src/browser/<br/>CDP / Playwright capture<br/>captured scripts and native module resolution<br/>execution/: coverage, listener and source attribution"]
JS_CODEC["src/javascript/sourceMaps/<br/>pinned upstream map codec<br/>owned heap-limited Node process, complete point evidence"]
INSPECTOR["src/inspector/<br/>passive V8 Inspector discovery and capture<br/>script and target locations"]
DOTNET["src/dotnet/<br/>Managed static metadata provider<br/>PE/CLI metadata inventory, members, IL"]
OBJDUMP["src/objdump/<br/>GNU objdump command profile"]
RIZIN["src/rizin/<br/>Static command profile and persistent debugger sessions"]
GDB["src/gdb/<br/>Persistent GDB/MI sessions<br/>owned process lifecycle and target state"]
FIRMWARE["src/firmware/<br/>Binwalk / Unblob adapters<br/>owned processes, report normalization, private extraction"]
ANDROID["src/android/<br/>Static APK adapter<br/>owned SDK stdio, pinned headless JADX, normalization"]
REFERENCE["src/reference/<br/>Filesystem reference-source reader<br/>bounded traversal, validation, errors"]
ANDROID_TOOLS["src/adb/ + src/apktool/ + src/jeb/<br/>BYO device, resource-decoding and JEB adapters<br/>owned adb and Apktool processes; JEB engine client over MCP"]
CAPTURE_TOOLS["src/captures/ + src/pcap/ + src/signals/ + src/sqlite/<br/>BYO tshark, pcap, sigrok and SQLite child inspection<br/>selected captures, recordings and databases; owned processes"]
NATIVE_READERS["src/go/ + src/rust/ + src/il2cpp/ + src/flutter/ + src/gpu/<br/>Bundled in-process binary metadata readers<br/>Go build info, Rust dependencies, IL2CPP, Dart build ID, GPU code objects"]
FORMAT_READERS["src/model/ + src/python/ + src/erlang/ + src/electron/<br/>Bundled in-process format readers<br/>GGUF and safetensors headers, Python .pyc, Erlang BEAM, Electron fuses"]
RUNTIME["src/frida/ + src/cutter/<br/>Frida instrumentation sessions and live Cutter bridge client"]
end
subgraph "Provider Process Foundation"
PROCESS["src/process/<br/>owned process groups, private roots<br/>deadlines, bounded file reads and diagnostics, cleanup"]
WINDOWS["src/windows/<br/>Windows host boundary adapters<br/>package loader, opaque handles, owned jobs and private runtimes"]
WINDOWS_NATIVE["native/windows/src/<br/>Node-API implementation<br/>NTFS/ReFS admission, protected DACLs and atomic Job Object assignment"]
FILESYSTEM["src/filesystem/<br/>owned file and directory handles<br/>stable reads, staged output, caller paths"]
HOPPER_PATHS["src/hopperPaths/<br/>Hopper install paths and launcher discovery<br/>read by the Hopper provider, doctor and setup"]
RESOURCES["src/resources/<br/>shared analysis resource owners<br/>cleanup leases, artifact reader contract, resource scope, owned file operations, stable reads, atomic text writes"]
end
subgraph "Contracts Layer"
CONTRACTS["src/contracts/<br/>Caller-visible schemas for analysis, reverse engineering, managed, browser, Electron, application, and session tools"]
ERRORS["src/contracts/errorSchemas.ts<br/>CLI error envelope and published error JSON Schema<br/>projection schema owned by src/domain/analysisErrorProjectionSchema.ts"]
end
subgraph "Domain Layer"
DOMAIN["src/domain/<br/>Pure side-effect-free modules<br/>format declarations, provider selection, Evidence, comparisons, application graphs"]
end
subgraph "Configuration"
CONFIG["src/config/<br/>Zod-validated env parsing<br/>provider settings and origins"]
end
subgraph "Tests"
TESTS["tests/<br/>Vitest suite<br/>fixtures/ holds fake launcher, bridge, and CDP seams"]
end
subgraph "Development Evaluation"
EVALUATION["tests/evaluation/model-evals/<br/>Agent release evaluation<br/>session transcript scoring"]
end
DISPATCH --> CLI
DISPATCH --> MAIN
MAIN --> CONFIG
MAIN --> SERVER
MAIN --> APP
CLI --> APP
MAIN --> COMPOSITION
CLI --> COMPOSITION
SERVER --> COMPOSITION
COMPOSITION --> LIFETIMES
COMPOSITION --> SESSION
APP --> FIRMWARE
FIRMWARE --> PROCESS
FIRMWARE --> CONTRACTS
APP --> ANDROID
ANDROID --> PROCESS
ANDROID --> CONTRACTS
ANDROID --> DOMAIN
CLI --> ERRORS
APP --> SESSION
SESSION --> REGISTRY
SESSION --> SNAPSHOT
SNAPSHOT --> RECORDS
APP -->|record callbacks| RECORDS
SERVER -->|narrow record ports| RECORDS
RECORDS --> DOMAIN
COMPOSITION --> WASM
COMPOSITION --> APKSIG
APKSIG --> DOMAIN
WASM --> PROCESS
WASM --> DOMAIN
COMPOSITION --> PWNTOOLS
PWNTOOLS --> PROCESS
PWNTOOLS --> DOMAIN
COMPOSITION --> HOPPER
COMPOSITION --> GHIDRA
COMPOSITION --> IDA
COMPOSITION --> KUNA
COMPOSITION --> AUX
IDA --> IDA_MCP
IDA --> CONTRACTS
IDA --> DOMAIN
SESSION --> AUX
APP --> JS_RECON
APP --> INSTALL
SERVER --> CONTRACTS
SERVER --> APP
APP --> BROWSER
APP -->|source-map codec port| JS_CODEC
JS_CODEC --> PROCESS
JS_CODEC --> DOMAIN
APP -->|runtime observation port| INSPECTOR
INSPECTOR -->|shared CDP and file-location helpers| BROWSER
INSPECTOR --> DOMAIN
APP --> DOTNET
DOTNET --> DOMAIN
COMPOSITION --> OBJDUMP
OBJDUMP --> DOMAIN
COMPOSITION --> RIZIN
RIZIN --> DOMAIN
COMPOSITION --> GDB
GDB --> PROCESS
GDB --> DOMAIN
HOPPER --> HOPPER_BRIDGE
GHIDRA --> GHIDRA_BRIDGE
HOPPER --> PROCESS
GHIDRA --> PROCESS
KUNA --> PROCESS
GHIDRA --> PROVIDER_OWNERS
APP --> PROVIDER_OWNERS
PROVIDER_OWNERS --> PROCESS
PROVIDER_OWNERS --> AUX
PROVIDER_OWNERS --> DOMAIN
GHIDRA --> WINDOWS
PROCESS --> WINDOWS
WINDOWS --> WINDOWS_NATIVE
APP --> PROCESS
APP --> DOMAIN
JS_RECON --> AUX
JS_RECON --> DOMAIN
APP --> REFERENCE
REFERENCE --> DOMAIN
CONTRACTS --> DOMAIN
HOPPER --> DOMAIN
GHIDRA --> DOMAIN
KUNA --> DOMAIN
AUX --> DOMAIN
BROWSER --> DOMAIN
PROCESS --> DOMAIN
TESTS -.-> MAIN
TESTS -.-> HOPPER
TESTS -.-> GHIDRA
TESTS -.-> IDA
TESTS -.-> PROCESS
TESTS -.-> BROWSER
TESTS -.-> EVALUATION
TESTS -.-> ERRORS
COMPOSITION --> EVM
APP -->|EVM interface port| EVM
EVM --> PROCESS
EVM --> DOMAIN
KUNA --> FILESYSTEM
COMPOSITION --> ANDROID_TOOLS
ANDROID_TOOLS --> PROCESS
ANDROID_TOOLS --> DOMAIN
COMPOSITION --> CAPTURE_TOOLS
CAPTURE_TOOLS --> PROCESS
CAPTURE_TOOLS --> DOMAIN
COMPOSITION --> NATIVE_READERS
NATIVE_READERS --> DOMAIN
COMPOSITION --> FORMAT_READERS
FORMAT_READERS --> DOMAIN
COMPOSITION --> RUNTIME
RUNTIME --> DOMAIN
PROCESS --> FILESYSTEM
PROCESS --> RESOURCES
HOPPER --> HOPPER_PATHS
APP --> HOPPER_PATHS
HOPPER_PATHS --> FILESYSTEM
AUX --> FILESYSTEM
APP --> FILESYSTEM
+1 -1
View File
@@ -70,7 +70,7 @@ the effective limit and exact repair; accepted overrides are reported separately
from caller selections. Changes apply on the next call without restarting REA.
Summary and selected extraction do not change the producer's admission.
Module-graph admission ceilings are in [Bun standalone module graphs](#bun-standalone-module-graphs). Shared artifact-reader admission stays in [limits and recovery](design/limits-and-recovery.md#artifact-reader-admission).
Module-graph admission ceilings are in [Bun standalone module graphs](#bun-standalone-module-graphs). Shared artifact-reader admission stays in [limits and recovery](reference/limits-and-recovery.md#artifact-reader-admission).
Synthetic tests cover the carriers and malformed declarations. Run
`node scripts/verify-bun-standalone.mjs` after `npm run build:cached` for local Bun
verification, and add `--docker` to compile a Linux fixture with `oven/bun:1.4.0`.
-107
View File
@@ -1,107 +0,0 @@
# Capability composition and ownership
REA keeps domain contracts and shared workflows separate from provider adapters
and CLI/MCP translation. A capability can have several provider identities; a
provider can contribute operations to several capabilities. Those associations
are source facts, while host availability is an observation.
## Source declarations and runtime bindings
`src/composition/capabilityDeclarations.ts` contains static provider identities,
named contract-group references and precise operation subsets. Complete groups
refer to `TOOL_CONTRACT_GROUPS` in the existing contract owner; family definitions
and provider catalogs read the same arrays, so a new group operation is included
without updating a copied provider list. Metadata imports only the group ID type
and pure metadata leaves; it must not load factories, schemas, engines or
generated catalogs. Catalog generation resolves groups and subsets against the
canonical contracts and rejects unknown groups/operations and conflicting
identities. New provider provenance must come from the implementation
that actually produces the Evidence, including format-specific capture adapters
and derived workflows.
`src/composition/capabilityServices.ts` binds typed service factories to those
capability keys. Each runtime entry owns construction, cleanup and any available
host/configuration facts or live probes. A service entry requires a close
capability; entries adapting managers retain their existing `closeAll` operation.
The host maps entries without erasing their individual service/port types. There
is no generic JSON operation dispatcher.
These two declarations have different loading needs. Static facts can be read
without loading a schema or provider graph. The full runtime composition is
materialized only when the MCP runtime needs it. One-shot CLI adapters import the
selected factory rather than constructing a complete capability host. CLI and MCP
reuse the same provider/service factories and application workflows, while
keeping their respective argument translation and lifetime.
## Resource lifetime
`CapabilityScope` registers a module's actual close capability when its instance
is composed. There is no independent server provider-close list to update.
Concurrent shutdown calls join the same cleanup attempt. A successful peer is
removed from pending cleanup; failed peers remain owned and are retried on the
next close. Synchronous throws and rejections without a reason remain failures,
and cannot prevent other peers from attempting cleanup. Shutdown seals further
ownership registration.
The host distinguishes these lifetimes:
- Host-owned service instances are released by that host.
- Caller-owned optional observations remain borrowed by SDK server instances;
their process-level owner closes them, including discarded discovery probes.
- CLI invocations use their existing finalizers to join cleanup and preserve the
original observation, cancellation and cleanup errors.
- Binary engines, bundle readers and investigation records retain their existing
owners. The `BinarySession` transition/drain barrier still coordinates target
changes, reset and disposal. A module refactor must not create independent
barriers that allow late work to repopulate reset records.
An application workflow may borrow a shared resource scope, such as byte entropy
using the host's artifact scope. Its wrapper does not acquire a second ownership
claim over the borrowed scope.
## Availability and registration
Module bindings provide host support, selected configuration and precisely typed
live availability probes through `CapabilityAvailabilityFacts`. Constructors do
not run these probes or launch engines. Session discovery invokes the existing
provider-owned probes only for advertised families; live failures remain fresh
observations. Caller policy, selected environments and injected providers retain
their existing precedence.
MCP registration remains in the MCP adapter. It consumes composed services,
record ports, admission and logging; it must not add fallback constructors that
can escape the host owner. Named contracts bind handlers and schemas. The complete
tool-family registrar map is checked by TypeScript, and catalog order never
selects a handler or schema.
## Extending a capability
1. Add or reuse the domain contract and application workflow, with explicit
Evidence provenance, coverage, unknowns and caller choices.
2. Put concrete construction in `src/composition/` and keep its default factory
lazy. Reference adapter-owned pure identity metadata from both the provider
and its static capability declaration.
3. Add the runtime binding if a host-owned service is needed. Bind cleanup and
availability/probes there, preserving borrowed versus owned resources.
4. Add the CLI/MCP argument adapters and their named registrations. A one-shot
command uses the shared selected factory and existing finalization helpers.
5. Run source-boundary, discovery, SDK-schema and relevant public workflow checks.
Exercise partial cleanup, retry, cancellation and caller-owned peers at the
applicable production seam; use actual applications/providers for routing and
complete Evidence verification. Recording ports do not prove real providers.
The constructor boundary guard covers the centralized Frida, Cutter, GDB and
Rizin constructors without rejecting legitimate type-only injected interfaces.
Other settled pure/provider boundaries continue checking type imports too. The
shared parser records module-edge erasure once. Whole-declaration type imports
are erased; inline type bindings retain their runtime module edge under
`verbatimModuleSyntax`. Static dynamic imports remain runtime edges too.
Tests belong with their semantic owner and must be
found exactly once; provider roots need the corresponding adapter discovery lane.
This is an internal composition contract. External plugin distribution, automatic
provider installation and a universal provider interface are separate concerns.
The [initial verification report](verification/capability-composition-2026-11-01.md)
records the executed public workflows, cleanup boundaries, resource measurements
and remaining provider qualification gaps for this composition increment.
-3
View File
@@ -379,6 +379,3 @@ the computer up so that reader can be retried.
The control token that guards the computer's framework-only routes stays in
REA: no result, error or log carries it. Code running in the computer as its
user can still read it, which is acceptable for a local build.
See the [specification](specs/desktop-app-environments/build-computer/spec.md)
for scope and verification.
+2 -5
View File
@@ -231,9 +231,9 @@ Then, with the task exactly as exported:
beside the files and evaluates each check with REA's evaluator, the one the
export validates tasks with and the exported verifier mirrors, one result per
check. Once the files settle it runs the task's
[readers](specs/desktop-app-environments/file-readers/spec.md) in the computer through
[readers](desktop-application-tasks.md#readers) in the computer through
`computer-exec/v1`, as the verifier does, and a check through a reader reads
that reader's view. A task of [screen judges](specs/desktop-app-environments/screen-judge/spec.md)
that reader's view. A task of [screen judges](desktop-application-tasks.md#screen-judges)
reads no files: REA takes a screenshot and runs the bundle's own judge on it
with the agentenv runner's Python and model endpoint. Like the verifier, it grades only once the app's files settle, since an
app such as Gnote saves a few seconds after the last key. It reads `data/get`
@@ -369,6 +369,3 @@ keeps the others. A `difficulty.json` or README REA cannot read or parse is refu
before any solve and left as it is, and measures of one bundle write one at a
time, so neither loses the other's record. The README gets a Measured difficulty section with one
line per task, which agentenv ignores like the file.
See the [specification](specs/desktop-app-environments/build-witness/spec.md)
for scope and verification.
+16 -49
View File
@@ -11,56 +11,23 @@ so readers can reach it from the task they are performing.
## Choose a destination
| Document | Destination |
| -------------------------------------------------------- | -------------------------------------- |
| Installation, client setup and first CLI/MCP steps | `docs/getting-started/` |
| Analyst workflows and evidence interpretation | `docs/guides/<domain>/` |
| Analysis-engine configuration and format prerequisites | `docs/providers/` |
| Shared runtime contracts and evidence semantics | `docs/reference/` |
| Development, testing, release and authoring instructions | `docs/development/` |
| Composition diagrams | `docs/architecture/` |
| Compatibility changes for a released version | `docs/migrations/` |
| One feature specification, plan and tasks | `docs/specs/<domain>/<feature-slug>/` |
| One architectural decision | `docs/adr/<domain>/<decision-slug>.md` |
| Document | Destination |
| -------------------------------------------------------- | ----------------------- |
| Installation, client setup and first CLI/MCP steps | `docs/getting-started/` |
| Analyst workflows and evidence interpretation | `docs/guides/<domain>/` |
| Analysis-engine configuration and format prerequisites | `docs/providers/` |
| Shared runtime contracts and evidence semantics | `docs/reference/` |
| Development, testing, release and authoring instructions | `docs/development/` |
| Compatibility changes for a released version | `docs/migrations/` |
Use meaningful, lowercase domain and feature slugs. Global numeric prefixes are
unnecessary: different domains can add features independently, and branches do
not compete for the next sequence number. Check the existing domain directory
and linked issues before creating a feature with the same slug.
Use meaningful, lowercase slugs. Guides describe current workflows, behavior and
limitations. Ground their claims in the implementation and verify examples
through the supported entry points.
Guides describe existing behavior and limitations. Specs define one proposed
feature or domain change; an existing guide does not become a specification by
moving it into `specs/`.
## Feature lifecycle
Create a feature record before implementation when the change adds a new MCP
tool or CLI command, a new provider lane or format reader, or a new public
contract. A bug fix inside an existing contract does not require a record.
Records nest under `docs/specs/<domain>/<slug>/`. Every new record gets a
`docs/specs/README.md` entry in the same pull request.
Create the specification before implementation. Each feature directory contains:
- `spec.md`: problem, desired behavior, requirements, acceptance and non-goals.
- `plan.md`: the single implementation plan, contracts and architectural choices.
- `tasks.md`: incremental, testable implementation and verification steps linked
to requirements. Do not record pull-request process or review steps.
Split independent domains or separately reviewable features before writing their
specs. A broad `ROADMAP.md`, when useful, only lists child specifications, order
and dependencies; requirements and implementation tasks belong to each child.
Cross-repository contracts have one producer-owned specification. Consumers link
to that contract instead of maintaining competing copies.
Record an isolated architectural decision separately in
`docs/adr/<domain>/<decision-slug>.md`, with **Status**, **Context**,
**Decision** and **Consequences**. Link the ADR from affected specifications.
Do not create decision records for routine file moves or invent past decisions.
Specs do not replace the contribution-scope decision required for a new provider
or expanded execution authority. Follow
[contribution scope](https://github.com/morluto/rea/blob/main/CONTRIBUTING.md#contribution-scope).
Follow the [repository guidance on where to keep planning and architecture records](https://github.com/morluto/rea/blob/main/AGENTS.md#development)
and the
[contribution scope](https://github.com/morluto/rea/blob/main/CONTRIBUTING.md#contribution-scope)
for proposals that require a maintainer decision.
## Links and public routes
@@ -90,7 +57,7 @@ or its inputs and regenerate.
Do not write the number of tools in living prose; link the generated catalog
instead. `docs:check` refuses a count of ten or more tools outside dated
records (`docs/releases/`, `docs/specs/`, `docs/verification/`, `docs/adr/`).
records (`docs/releases/` and `docs/verification/`).
Run `npm run docs:check` for documentation facts and generated consistency, and
`npm run verify:docs:routes` to build the complete production site and check local
-35
View File
@@ -1,35 +0,0 @@
# REA roadmap
The [platform tracker](https://github.com/morluto/rea/issues/32),
[process/Hopper tracker](https://github.com/morluto/rea/issues/48), and
[browser tracker](https://github.com/morluto/rea/issues/39) track capability and
verification work. Available tools and setup are documented in the
[investigation guides](https://rea.tools/guides/),
[installation guide](../getting-started/installation.md), and
[generated catalog](../reference/mcp-contracts.md#generated-catalog).
## Priorities
- Expand native architecture, type, and indirect-call verification.
- Connect static findings and runtime observations across application layers.
- Improve obfuscated managed-code comparisons and verified native links.
- Extend process, protocol, filesystem, reconnect, and build-comparison coverage.
- Evaluate additional providers and targets when an analyst workflow demonstrates
a capability gap.
## Admission criteria
New capabilities must return useful evidence through shared CLI/MCP workflows,
preserve observations and unknowns, and declare actual authority and lifecycle
constraints. Agents compose experiments using ordinary commands, scripts, and
fixture servers; custom orchestration needs a demonstrated requirement.
Provider and platform claims require their corresponding
[real verification lanes](../testing-lanes.md#real-toolchain-verification-lanes).
See [tool design](tool-design.md) for choosing a tool boundary and
[Ghidra semantics](../providers/ghidra-provider.md) for the existing deep-provider contract.
Setup remains additive, reuses existing tools, and requires approval for disclosed
configuration and Hopper installation changes. Additional installer choices need
an implemented toolchain and explicit scope; setup does not install or upgrade
unrelated runtimes or dependencies.
+1 -1
View File
@@ -207,7 +207,7 @@ does not establish another instance.
constraints. Report pagination, truncation, cancellation, and partial failure.
An assumed agent budget is insufficient justification for a limit. Name the
ceiling and its recovery as described in
[admission limits and recovery](../design/limits-and-recovery.md).
[admission limits and recovery](../reference/limits-and-recovery.md).
### Compose declared Evidence inputs
-5
View File
@@ -21,11 +21,6 @@ requires an absolute filesystem path and preserves that exact selection:
}
```
The [feature specification](specs/native/elf-dependencies/spec.md),
[plan](specs/native/elf-dependencies/plan.md) and
[tasks](specs/native/elf-dependencies/tasks.md) record the requirements and
verification.
Relocatable objects are not this inventory; use `inspect_kernel_module` for
Linux kernel modules. Core dumps are not this inventory; use
`inspect_recorded_crash`.
+1 -1
View File
@@ -119,7 +119,7 @@ descriptor consumes projected bytes for each entry that includes it. Metadata
that would exceed the Evidence JSON nesting allowance is also left undecoded.
Zstandard section-name tables also use a 128 MiB decoder window limit and the
shared [`zstd.max_frames` work limit](design/limits-and-recovery.md#runtime-settings-through-mcp).
shared [`zstd.max_frames` work limit](reference/limits-and-recovery.md#runtime-settings-through-mcp).
`SHF_COMPRESSED` note sections return `unsupported_target` before their payload
is interpreted or decompressed. Their compression header is storage metadata,
+2 -1
View File
@@ -94,7 +94,8 @@ raising a REA startup or operation deadline, separately ensure the client allows
enough time for the full request. Use `inspect_analysis_settings` for the running
server's defaults; `rea doctor` checks launch configuration and cannot observe
another process's runtime overrides. See the
[settings design](../design/limits-and-recovery.md) for ownership and lifetime.
[analysis settings and recovery](../reference/limits-and-recovery.md#precedence-and-lifetime)
for precedence and lifetime.
## Client tool names and discovery
+1 -1
View File
@@ -1563,7 +1563,7 @@ invocation instead. In MCP, `ghidra.decompile_timeout_seconds` can override the
value for newly accepted operations on the existing Program; explicit `null`
removes the deadline. A transient timeout remains uncached so the same function
can be retried after an update. See the
[settings design](../design/limits-and-recovery.md#runtime-settings-through-mcp).
[analysis settings and recovery](../reference/limits-and-recovery.md#runtime-settings-through-mcp).
Codex/Kimi registrations derived by `rea setup` add the selected launch value
to the tool deadline as a single-decompile estimate; a runtime update does not
change that registration. A bulk call can need that limit for
+1 -1
View File
@@ -711,7 +711,7 @@ bounds each upstream call. Timeout recovery reports the effective milliseconds
and range, with `details.limit` identifying the runtime setting. An invalid
provider-local launch value can also be repaired by a runtime override; reset
exposes that invalid launch value again. See the
[settings design](../../design/limits-and-recovery.md#invalid-launch-configuration).
[analysis settings and recovery](../../reference/limits-and-recovery.md#invalid-launch-configuration).
A passing JADX configuration check in `rea doctor` reports its launch-derived
`operation_timeout_ms`; it does not inspect another running server's overrides. Explicit
cancellation still ends the operation immediately, and partial observations
@@ -341,7 +341,7 @@ budget used by static ASAR reads: 16 MiB / 16777216 bytes by default, seeded by
`update_analysis_settings` can override `asar.max_header_bytes` for new
operations without restarting REA. Cached headers are checked against each
operation's admission, including after a decrease. See the
[settings design](../../design/limits-and-recovery.md#failure-and-retry).
[analysis settings and recovery](../../reference/limits-and-recovery.md#failure-and-retry).
An oversized header is
not parsed; selecting a member path does not bypass admission, and the page
stays unauthorized. The header cache separately retains at most that many bytes
@@ -167,7 +167,7 @@ must also satisfy the new admission. For CLI or future MCP processes, set
`REA_ASAR_MAX_HEADER_BYTES` in the launch environment. Changing that environment
requires a new REA process. Invalid launch values are configuration errors,
never a silent fallback. See the
[settings design](../../design/limits-and-recovery.md#failure-and-retry) for recovery
[analysis settings and recovery](../../reference/limits-and-recovery.md#failure-and-retry) for recovery
metadata, precedence, and reset behavior.
The archive index is read before any member can be selected, so
@@ -579,9 +579,6 @@ prefix is never presented as a complete stable fingerprint.
## Cached-data compilation boundaries
The [feature specification](../../specs/javascript/v8-cached-data/spec.md) defines
the static admission and uncertainty contract.
A `node:vm` compilation reports whether `cachedData` is declared, absent or
unknown. Explicitly supplied undefined bytes are treated as absent; shadowed
identifiers remain declarations. Source syntax alone does not establish valid cache bytes, V8 acceptance
@@ -962,7 +959,7 @@ analyzer; the caller's `NODE_OPTIONS` still controls the CLI/MCP process heap.
For defaults across new MCP operations, use `update_analysis_settings` with
`javascript.max_heap_mb` or `javascript.analysis_timeout_ms`. Explicit per-call
arguments take precedence, and accepted work keeps its original settings. See
the [settings design](../../design/limits-and-recovery.md#precedence-and-lifetime).
the [analysis settings and recovery](../../reference/limits-and-recovery.md#precedence-and-lifetime).
V8 old-space limits do not impose a process RSS limit. When REA runs on Bun,
the analyzer ignores the V8 heap flags; resource failures then report
`worker_heap_limit_bytes` as null instead of a requested or V8-reported limit.
+1 -1
View File
@@ -456,7 +456,7 @@ configuration errors and do not fall back to 128. The setting is read from
the environment that starts REA, while MCP `regex.worker_heap_request_mib`
can override it for workers belonging to newly accepted searches. Use
`update_analysis_settings` for either runtime control; accepted work keeps its
budget. See the [settings design](../../design/limits-and-recovery.md).
budget. See the [analysis settings and recovery](../../reference/limits-and-recovery.md).
A heap failure names the effective request, known source, default, floor, and
maximum. A positive Node.js
`--max-old-space-size` on the process that starts
+1 -1
View File
@@ -130,7 +130,7 @@ To change the default across new MCP operations, set `wasm.command_timeout_ms`
through `update_analysis_settings`. An explicit `command_timeout_ms` still wins;
correct that argument if it caused the timeout. Runtime defaults do not insert
omitted arguments into Evidence parameters. See the
[settings design](../../design/limits-and-recovery.md#precedence-and-lifetime).
[analysis settings and recovery](../../reference/limits-and-recovery.md#precedence-and-lifetime).
For example, `rea inspect-wasm-artifact /artifacts/module.wasm
--command-timeout-ms 60000 --format json` uses a 60-second per-command deadline;
+1 -1
View File
@@ -1136,7 +1136,7 @@ host memory or `NODE_OPTIONS` does not raise the old-generation heap. Update
`capture.decoder_old_generation_mib` through MCP, or set
`REA_CAPTURE_DECODER_OLD_GENERATION_MIB` before starting a new REA process.
Retry after owned cleanup completes; the update does not release resources.
See the [settings design](../../design/limits-and-recovery.md#failure-and-retry).
See the [analysis settings and recovery](../../reference/limits-and-recovery.md#failure-and-retry).
Record selection happens after complete decoding and does not reduce that
workload. Use a smaller capture exported by its producer or another decoder
with sufficient capacity, retaining the original for provenance. Subsets do
+2 -2
View File
@@ -318,8 +318,8 @@ Runtime updates apply to newly accepted operations on the existing Program.
They preserve accepted budgets and do not clear cleanup blockers or change the
client deadline. Transient decompile timeout failures remain uncached so the
same function can be retried after raising the limit. See the
[settings design](../design/limits-and-recovery.md) for snapshots, precedence,
and provider integration.
[analysis settings and recovery](../reference/limits-and-recovery.md#precedence-and-lifetime)
for precedence and lifetime.
Every Ghidra analysis profile commits `producer`: the REA release and a SHA-256
of the packaged bridge scripts. A snapshot replays only under the same
+1 -2
View File
@@ -362,7 +362,6 @@ npx rea-agents@latest setup
- [CLI وEvidence](../getting-started/cli.md): الأوامر، واختيار الموفّر، واللقطات، والاستيراد/التصدير، وحالات الخروج.
- [عقود MCP](../reference/mcp-contracts.md) و[تعليمات الوكلاء](../getting-started/mcp-prompts.md): نتائج الأدوات، والجلسات، والاستقصاءات الموجّهة.
- [كتالوج الأدوات](../reference/mcp-contracts.md#generated-catalog): قائمة الأدوات والموفّرين وأوامر CLI المولّدة أثناء البناء.
- [خطة العمل](../development/roadmap.md): الأعمال المخطط لها ومتابعة القدرات.
أبلغ عن الثغرات وفق [SECURITY.md](../../SECURITY.md).
@@ -394,7 +393,7 @@ applicable licenses.
نرحّب بمساعدتك في تطوير REA! [افتح issue](https://github.com/morluto/rea/issues) للإبلاغ عن خطأ أو اقتراح ميزة، أو [أرسل pull request](https://github.com/morluto/rea/pulls) لتحسين الشيفرة أو التوثيق.
راجع [CONTRIBUTING.md](../../CONTRIBUTING.md) لإعداد بيئة التطوير والفحوص، و[دليل الاختبار](../development/testing.md) لمسارات التحقق، و[خريطة البنية](../architecture/architecture.mermaid) لهيكل المشروع.
راجع [CONTRIBUTING.md](../../CONTRIBUTING.md) لإعداد بيئة التطوير والفحوص، و[دليل الاختبار](../development/testing.md) لمسارات التحقق.
## الترخيص
+1 -3
View File
@@ -462,7 +462,6 @@ npx rea-agents@latest setup
- [CLI и Evidence](../getting-started/cli.md): команди, избор на доставчик, моментни снимки, импорт/експорт и изходни статуси.
- [MCP договори](../reference/mcp-contracts.md) и [подсказки за агенти](../getting-started/mcp-prompts.md): резултати от инструментите, сесии и насочвани изследвания.
- [Каталог с инструменти](../reference/mcp-contracts.md#generated-catalog): генериран списък с инструменти, доставчици и CLI команди.
- [Пътна карта](../development/roadmap.md): планирана работа и проследяване на възможностите.
Съобщавайте за уязвимости чрез [SECURITY.md](../../SECURITY.md).
@@ -501,8 +500,7 @@ REA е предназначен за законни изследвания, об
Вижте [CONTRIBUTING.md](../../CONTRIBUTING.md) за настройка на средата за
разработка и проверките, [тестване](../development/testing.md) за видовете
проверки и [картата на архитектурата](../architecture/architecture.mermaid) за
избрани слоеве и пътища на зависимостите.
проверки.
## Лиценз
+1 -2
View File
@@ -362,7 +362,6 @@ Beginne mit den [praxisnahen Anleitungen](https://rea.tools/de/guides/) auf der
- [CLI und Evidence](../getting-started/cli.md): Befehle, Provider-Auswahl, Snapshots, Import/Export und Exit-Status.
- [MCP-Kontrakte](../reference/mcp-contracts.md) und [Agenten-Prompts](../getting-started/mcp-prompts.md): Werkzeugergebnisse, Sitzungen und geführte Untersuchungen.
- [Werkzeugkatalog](../reference/mcp-contracts.md#generated-catalog): Beim Build erzeugtes Inventar von Werkzeugen, Providern und CLI-Befehlen.
- [Roadmap](../development/roadmap.md): Geplante Arbeiten und Fortschrittsübersichten zu Fähigkeiten.
Melde Sicherheitslücken gemäß [SECURITY.md](../../SECURITY.md).
@@ -394,7 +393,7 @@ applicable licenses.
Wir freuen uns über deine Hilfe bei REA! [Öffne ein Issue](https://github.com/morluto/rea/issues), um einen Fehler zu melden oder eine Funktion vorzuschlagen, oder [sende einen Pull Request](https://github.com/morluto/rea/pulls), um Code oder Dokumentation zu verbessern.
Die Entwicklungsumgebung und Prüfungen beschreibt [CONTRIBUTING.md](../../CONTRIBUTING.md), die Verifikationspfade der [Testleitfaden](../development/testing.md) und die Projektstruktur die [Architekturübersicht](../architecture/architecture.mermaid).
Die Entwicklungsumgebung und Prüfungen beschreibt [CONTRIBUTING.md](../../CONTRIBUTING.md), die Verifikationspfade der [Testleitfaden](../development/testing.md).
## Lizenz
+1 -2
View File
@@ -364,7 +364,6 @@ npx rea-agents@latest setup
- [CLI και Evidence](../getting-started/cli.md): εντολές, επιλογή παρόχου, στιγμιότυπα, εισαγωγή/εξαγωγή και κωδικοί εξόδου.
- [Προδιαγραφές MCP](../reference/mcp-contracts.md) και [prompts για agents](../getting-started/mcp-prompts.md): αποτελέσματα εργαλείων, συνεδρίες και καθοδηγούμενες διερευνήσεις.
- [Κατάλογος εργαλείων](../reference/mcp-contracts.md#generated-catalog): αυτόματα παραγόμενος κατάλογος εργαλείων, παρόχων και εντολών CLI.
- [Οδικός χάρτης](../development/roadmap.md): προγραμματισμένες εργασίες και παρακολούθηση της ανάπτυξης δυνατοτήτων.
Ανάφερε ευπάθειες ακολουθώντας το [SECURITY.md](../../SECURITY.md).
@@ -394,7 +393,7 @@ npx rea-agents@latest setup
Θα χαρούμε να βοηθήσεις στο REA! [Άνοιξε ένα issue](https://github.com/morluto/rea/issues) για να αναφέρεις ένα σφάλμα ή να προτείνεις μια λειτουργία, ή [στείλε ένα pull request](https://github.com/morluto/rea/pulls) για να βελτιώσεις τον κώδικα ή την τεκμηρίωση.
Δες το [CONTRIBUTING.md](../../CONTRIBUTING.md) για τη ρύθμιση του περιβάλλοντος ανάπτυξης και τους ελέγχους, τον [οδηγό δοκιμών](../development/testing.md) για τις διαδικασίες επαλήθευσης και τον [χάρτη αρχιτεκτονικής](../architecture/architecture.mermaid) για τη δομή του έργου.
Δες το [CONTRIBUTING.md](../../CONTRIBUTING.md) για τη ρύθμιση του περιβάλλοντος ανάπτυξης και τους ελέγχους, τον [οδηγό δοκιμών](../development/testing.md) για τις διαδικασίες επαλήθευσης.
## Άδεια χρήσης
+1 -2
View File
@@ -362,7 +362,6 @@ Empieza con las [guías prácticas](https://rea.tools/es/guides/) del sitio web.
- [CLI y Evidence](../getting-started/cli.md): comandos, selección de proveedores, instantáneas, importación/exportación y estados de salida.
- [Contratos de MCP](../reference/mcp-contracts.md) y [prompts para agentes](../getting-started/mcp-prompts.md): resultados de herramientas, sesiones e investigaciones guiadas.
- [Catálogo de herramientas](../reference/mcp-contracts.md#generated-catalog): inventario de herramientas, proveedores y comandos de CLI generado durante la compilación.
- [Hoja de ruta](../development/roadmap.md): trabajo previsto y seguimiento de capacidades.
Informa de vulnerabilidades siguiendo [SECURITY.md](../../SECURITY.md).
@@ -394,7 +393,7 @@ applicable licenses.
¡Nos encantaría que ayudaras con REA! [Abre una issue](https://github.com/morluto/rea/issues) para comunicar un error o proponer una función, o [envía una pull request](https://github.com/morluto/rea/pulls) para mejorar el código o la documentación.
Consulta [CONTRIBUTING.md](../../CONTRIBUTING.md) para preparar el entorno de desarrollo y las comprobaciones, la [guía de pruebas](../development/testing.md) para los procesos de verificación y el [mapa de arquitectura](../architecture/architecture.mermaid) para la estructura del proyecto.
Consulta [CONTRIBUTING.md](../../CONTRIBUTING.md) para preparar el entorno de desarrollo y las comprobaciones, la [guía de pruebas](../development/testing.md) para los procesos de verificación.
## Licencia
+1 -2
View File
@@ -347,7 +347,6 @@ npx rea-agents@latest setup
- [CLI و شواهد](../getting-started/cli.md): دستورات، انتخاب ارائه‌دهنده، snapshotها، ورود/خروج داده و وضعیت‌های خروج.
- [قراردادهای MCP](../reference/mcp-contracts.md) و [پرامپت‌های ایجنت](../getting-started/mcp-prompts.md): نتایج ابزارها، نشست‌ها و بررسی‌های هدایت‌شده.
- [فهرست ابزارها](../reference/mcp-contracts.md#generated-catalog): فهرست تولیدشده هنگام build از ابزارها، ارائه‌دهندگان و دستورات CLI.
- [نقشهٔ راه](../development/roadmap.md): برنامه‌های آینده و پیگیری قابلیت‌ها.
آسیب‌پذیری‌ها را از طریق [SECURITY.md](../../SECURITY.md) گزارش کنید.
@@ -373,7 +372,7 @@ applicable licenses.
از کمک شما به REA استقبال می‌کنیم! برای گزارش خطا یا پیشنهاد قابلیت، یک [issue باز کنید](https://github.com/morluto/rea/issues) یا برای بهبود کد و مستندات [pull request بفرستید](https://github.com/morluto/rea/pulls).
برای راه‌اندازی محیط توسعه و بررسی‌ها، [CONTRIBUTING.md](../../CONTRIBUTING.md)، برای مراحل اعتبارسنجی [آزمایش‌ها](../development/testing.md) و برای ساختار پروژه [نقشهٔ معماری](../architecture/architecture.mermaid) را ببینید.
برای راه‌اندازی محیط توسعه و بررسی‌ها، [CONTRIBUTING.md](../../CONTRIBUTING.md)، برای مراحل اعتبارسنجی [آزمایش‌ها](../development/testing.md) را ببینید.
## مجوز
+1 -2
View File
@@ -359,7 +359,6 @@ Commencez par les [guides pas à pas](https://rea.tools/fr/guides/) du site web.
- [CLI et Evidence](../getting-started/cli.md) : commandes, choix du fournisseur, snapshots, import/export et codes de sortie.
- [Contrats MCP](../reference/mcp-contracts.md) et [prompts pour agents](../getting-started/mcp-prompts.md) : résultats des outils, sessions et investigations guidées.
- [Catalogue des outils](../reference/mcp-contracts.md#generated-catalog) : inventaire des outils, fournisseurs et commandes CLI, généré lors du build.
- [Feuille de route](../development/roadmap.md) : travaux prévus et suivi des capacités.
Signalez les vulnérabilités via [SECURITY.md](../../SECURITY.md).
@@ -391,7 +390,7 @@ applicable licenses.
Votre aide sur REA est la bienvenue ! [Ouvrez une issue](https://github.com/morluto/rea/issues) pour signaler un bug ou proposer une fonctionnalité, ou [envoyez une pull request](https://github.com/morluto/rea/pulls) pour améliorer le code ou la documentation.
Consultez [CONTRIBUTING.md](../../CONTRIBUTING.md) pour l'environnement de développement et les vérifications, la page [tests](../development/testing.md) pour les procédures de vérification, et la [carte de l'architecture](../architecture/architecture.mermaid) pour la structure du projet.
Consultez [CONTRIBUTING.md](../../CONTRIBUTING.md) pour l'environnement de développement et les vérifications, la page [tests](../development/testing.md) pour les procédures de vérification.
## Licence
+1 -2
View File
@@ -380,7 +380,6 @@ Untuk mengetahui opsi, prasyarat, dan kontrak hasil secara tepat:
- [CLI dan Bukti](../getting-started/cli.md): perintah, pemilihan penyedia, snapshot, impor/ekspor, dan status keluar.
- [Kontrak MCP](../reference/mcp-contracts.md) dan [prompt agen](../getting-started/mcp-prompts.md): hasil alat, sesi, dan investigasi terpandu.
- [Katalog alat](../reference/mcp-contracts.md#generated-catalog): inventaris alat, penyedia, dan perintah CLI yang dibuat secara otomatis.
- [Peta jalan](../development/roadmap.md): pekerjaan yang direncanakan dan pelacak kemampuan.
Laporkan kerentanan melalui [SECURITY.md](../../SECURITY.md).
@@ -412,7 +411,7 @@ applicable licenses.
Kami sangat menghargai bantuan Anda untuk REA! [Buat issue](https://github.com/morluto/rea/issues) untuk melaporkan bug atau menyarankan fitur, atau [kirim pull request](https://github.com/morluto/rea/pulls) untuk meningkatkan kode atau dokumentasi.
Lihat [CONTRIBUTING.md](../../CONTRIBUTING.md) untuk penyiapan pengembangan dan pemeriksaan, [pengujian](../development/testing.md) untuk tahapan verifikasi, serta [peta arsitektur](../architecture/architecture.mermaid) untuk struktur proyek.
Lihat [CONTRIBUTING.md](../../CONTRIBUTING.md) untuk penyiapan pengembangan dan pemeriksaan, [pengujian](../development/testing.md) untuk tahapan verifikasi.
## Lisensi
+1 -2
View File
@@ -359,7 +359,6 @@ Inizia dalle [guide pratiche](https://rea.tools/it/guides/) del sito web. Per op
- [CLI ed Evidence](../getting-started/cli.md): comandi, selezione provider, snapshot, import/export e stati di uscita.
- [Contratti MCP](../reference/mcp-contracts.md) e [prompt agente](../getting-started/mcp-prompts.md): risultati degli strumenti, sessioni e indagini guidate.
- [Catalogo strumenti](../reference/mcp-contracts.md#generated-catalog): inventario generato di strumenti, provider e comandi CLI.
- [Roadmap](../development/roadmap.md): lavoro pianificato e tracker delle capacità.
Segnala vulnerabilità tramite [SECURITY.md](../../SECURITY.md).
@@ -391,7 +390,7 @@ applicable licenses.
Apprezzeremmo il tuo aiuto con REA! [Apri un issue](https://github.com/morluto/rea/issues) per segnalare un bug o suggerire una funzionalità, oppure [invia una pull request](https://github.com/morluto/rea/pulls) per migliorare il codice o la documentazione.
Vedi [CONTRIBUTING.md](../../CONTRIBUTING.md) per la configurazione di sviluppo e i controlli, [testing](../development/testing.md) per le lane di verifica e la [mappa dell'architettura](../architecture/architecture.mermaid) per la struttura del progetto.
Vedi [CONTRIBUTING.md](../../CONTRIBUTING.md) per la configurazione di sviluppo e i controlli, [testing](../development/testing.md) per le lane di verifica.
## License
+1 -2
View File
@@ -364,7 +364,6 @@ npx rea-agents@latest setup
- [CLI と Evidence](../getting-started/cli.md):コマンド、プロバイダーの選択、スナップショット、インポート/エクスポート、終了ステータス。
- [MCP 契約](../reference/mcp-contracts.md)と[エージェント向けプロンプト](../getting-started/mcp-prompts.md):ツールの結果、セッション、ガイド付き調査。
- [ツールカタログ](../reference/mcp-contracts.md#generated-catalog):ビルド時に生成されるツール、プロバイダー、CLI コマンドの一覧。
- [ロードマップ](../development/roadmap.md):計画中の作業と機能の進捗。
脆弱性の報告は [SECURITY.md](../../SECURITY.md) に従ってください。
@@ -394,7 +393,7 @@ REA は、法令に従った研究、教育、相互運用性の確保、ソフ
REA への貢献を歓迎します![issue を作成](https://github.com/morluto/rea/issues)してバグや機能の提案を報告したり、[pull request を送信](https://github.com/morluto/rea/pulls)してコードやドキュメントを改善したりできます。
開発環境とチェックは [CONTRIBUTING.md](../../CONTRIBUTING.md)、検証レーンは[テストガイド](../development/testing.md)、プロジェクト構造は[アーキテクチャ図](../architecture/architecture.mermaid)を参照してください。
開発環境とチェックは [CONTRIBUTING.md](../../CONTRIBUTING.md)、検証レーンは[テストガイド](../development/testing.md)を参照してください。
## ライセンス
+1 -2
View File
@@ -362,7 +362,6 @@ npx rea-agents@latest setup
- [CLI 및 Evidence](../getting-started/cli.md): 명령, 제공자 선택, 스냅샷, 가져오기/내보내기, 종료 상태.
- [MCP 계약](../reference/mcp-contracts.md) 및 [에이전트 프롬프트](../getting-started/mcp-prompts.md): 도구 결과, 세션, 안내에 따른 조사.
- [도구 카탈로그](../reference/mcp-contracts.md#generated-catalog): 빌드 시 생성되는 도구, 제공자, CLI 명령 목록.
- [로드맵](../development/roadmap.md): 계획된 작업과 기능 진행 상황.
취약점은 [SECURITY.md](../../SECURITY.md)에 따라 보고하세요.
@@ -392,7 +391,7 @@ REA는 법을 준수하는 연구, 교육, 상호운용성 확보, 소프트웨
REA에 도움을 보태 주세요! [issue를 등록](https://github.com/morluto/rea/issues)해 버그나 기능을 제안하거나, [pull request를 보내](https://github.com/morluto/rea/pulls) 코드와 문서를 개선할 수 있습니다.
개발 환경과 검사 항목은 [CONTRIBUTING.md](../../CONTRIBUTING.md), 검증 절차는 [테스트 가이드](../development/testing.md), 프로젝트 구조는 [아키텍처 지도](../architecture/architecture.mermaid)를 참고하세요.
개발 환경과 검사 항목은 [CONTRIBUTING.md](../../CONTRIBUTING.md), 검증 절차는 [테스트 가이드](../development/testing.md)를 참고하세요.
한국어 번역도 개선할 수 있습니다. 이 README를 수정할 때는 [영문 README](../../README.md)의 명령어, 요구 사항, 분석 범위와 일치하는지 확인하세요. 웹사이트 번역은 `website/locales/ko/messages.po`의 `msgstr` 값을 수정하세요.
+1 -2
View File
@@ -367,7 +367,6 @@ npx rea-agents@latest setup
- [CLI and Evidence](../getting-started/cli.md): commands, provider തിരഞ്ഞെടുക്കൽ, snapshots, import/export, exit statuses.
- [MCP contracts](../reference/mcp-contracts.md), [agent prompts](../getting-started/mcp-prompts.md): tool results, sessions, guided investigations.
- [Tool catalog](../reference/mcp-contracts.md#generated-catalog): tools, providers, CLI commands എന്നിവയുടെ സ്വയമേവ സൃഷ്ടിച്ച പട്ടിക.
- [Roadmap](../development/roadmap.md): ആസൂത്രണം ചെയ്ത പ്രവർത്തനങ്ങളും capability trackers-ഉം.
സുരക്ഷാ ദുർബലതകൾ [SECURITY.md](../../SECURITY.md) വഴി റിപ്പോർട്ട് ചെയ്യുക.
@@ -397,7 +396,7 @@ REA ഉപയോഗിക്കുന്നവർക്കും, bugs റിപ
REA-യ്ക്കായി നിങ്ങളുടെ സഹായം ഞങ്ങൾ സ്വാഗതം ചെയ്യുന്നു! bug റിപ്പോർട്ട് ചെയ്യാനോ feature നിർദ്ദേശിക്കാനോ [issue തുറക്കുക](https://github.com/morluto/rea/issues), code അല്ലെങ്കിൽ docs മെച്ചപ്പെടുത്താൻ [pull request അയയ്ക്കുക](https://github.com/morluto/rea/pulls).
Development setup-നും checks-നും [CONTRIBUTING.md](../../CONTRIBUTING.md), verification lanes-നായി [testing](../development/testing.md), project ഘടനയ്ക്കായി [architecture map](../architecture/architecture.mermaid) എന്നിവ കാണുക.
Development setup-നും checks-നും [CONTRIBUTING.md](../../CONTRIBUTING.md), verification lanes-നായി [testing](../development/testing.md) എന്നിവ കാണുക.
## ലൈസൻസ്
+1 -2
View File
@@ -362,7 +362,6 @@ Zacznij od [przewodników z przykładami](https://rea.tools/pl/guides/) na stron
- [CLI i Evidence](../getting-started/cli.md): polecenia, wybór dostawcy, migawki, import/eksport i kody zakończenia.
- [Kontrakty MCP](../reference/mcp-contracts.md) i [prompty dla agentów](../getting-started/mcp-prompts.md): wyniki narzędzi, sesje i prowadzone analizy.
- [Katalog narzędzi](../reference/mcp-contracts.md#generated-catalog): generowany podczas kompilacji wykaz narzędzi, dostawców i poleceń CLI.
- [Plan rozwoju](../development/roadmap.md): planowane prace i śledzenie funkcjonalności.
Zgłaszaj podatności zgodnie z [SECURITY.md](../../SECURITY.md).
@@ -394,7 +393,7 @@ applicable licenses.
Chętnie przyjmiemy Twoją pomoc w rozwoju REA! [Otwórz zgłoszenie](https://github.com/morluto/rea/issues), aby poinformować o błędzie lub zaproponować funkcję, albo [wyślij pull request](https://github.com/morluto/rea/pulls) z ulepszeniami kodu lub dokumentacji.
Zobacz [CONTRIBUTING.md](../../CONTRIBUTING.md), aby poznać konfigurację środowiska programistycznego i kontrole, [testowanie](../development/testing.md), aby poznać ścieżki weryfikacji, oraz [mapę architektury](../architecture/architecture.mermaid), aby poznać strukturę projektu.
Zobacz [CONTRIBUTING.md](../../CONTRIBUTING.md), aby poznać konfigurację środowiska programistycznego i kontrole, [testowanie](../development/testing.md), aby poznać ścieżki weryfikacji.
## Licencja
+1 -2
View File
@@ -362,7 +362,6 @@ Comece pelos [guias práticos](https://rea.tools/pt-BR/guides/) do site. Para op
- [CLI e Evidence](../getting-started/cli.md): comandos, seleção de provedores, snapshots, importação/exportação e status de saída.
- [Contratos MCP](../reference/mcp-contracts.md) e [prompts para agentes](../getting-started/mcp-prompts.md): resultados das ferramentas, sessões e investigações guiadas.
- [Catálogo de ferramentas](../reference/mcp-contracts.md#generated-catalog): inventário de ferramentas, provedores e comandos da CLI gerado durante o build.
- [Roadmap](../development/roadmap.md): trabalho planejado e acompanhamento das capacidades.
Relate vulnerabilidades conforme [SECURITY.md](../../SECURITY.md).
@@ -394,7 +393,7 @@ applicable licenses.
Sua ajuda com o REA é bem-vinda! [Abra uma issue](https://github.com/morluto/rea/issues) para relatar um bug ou sugerir uma funcionalidade, ou [envie um pull request](https://github.com/morluto/rea/pulls) para melhorar o código ou a documentação.
Consulte [CONTRIBUTING.md](../../CONTRIBUTING.md) para configurar o ambiente de desenvolvimento e as verificações, o [guia de testes](../development/testing.md) para os fluxos de verificação e o [mapa da arquitetura](../architecture/architecture.mermaid) para a estrutura do projeto.
Consulte [CONTRIBUTING.md](../../CONTRIBUTING.md) para configurar o ambiente de desenvolvimento e as verificações, o [guia de testes](../development/testing.md) para os fluxos de verificação.
## Licença
+1 -4
View File
@@ -439,7 +439,6 @@ Pentru opțiunile exacte, cerințele preliminare și contractele rezultatelor:
- [CLI și Evidence](../getting-started/cli.md): comenzi, selectarea motorului, instantanee, import/export și coduri de ieșire.
- [Contracte MCP](../reference/mcp-contracts.md) și [prompturi pentru agenți](../getting-started/mcp-prompts.md): rezultatele uneltelor, sesiuni și investigații ghidate.
- [Catalogul uneltelor](../reference/mcp-contracts.md#generated-catalog): inventarul generat al uneltelor, motoarelor de analiză și comenzilor CLI.
- [Plan de dezvoltare](../development/roadmap.md): lucrări planificate și urmărirea progresului funcționalităților.
Raportează vulnerabilitățile conform [SECURITY.md](../../SECURITY.md).
@@ -478,9 +477,7 @@ pentru a raporta o eroare sau a propune o funcționalitate ori
codul sau documentația.
Consultă [CONTRIBUTING.md](../../CONTRIBUTING.md) pentru pregătirea mediului de dezvoltare
și verificări, [ghidul de testare](../development/testing.md) pentru categoriile de verificări
și [diagrama arhitecturii](../architecture/architecture.mermaid) pentru anumite straturi și
relații de dependență.
și verificări, [ghidul de testare](../development/testing.md) pentru categoriile de verificări.
## Licență
+1 -2
View File
@@ -362,7 +362,6 @@ npx rea-agents@latest setup
- [CLI и Evidence](../getting-started/cli.md): команды, выбор провайдера, снимки, импорт/экспорт и коды завершения.
- [Контракты MCP](../reference/mcp-contracts.md) и [промпты агентов](../getting-started/mcp-prompts.md): результаты инструментов, сеансы и исследования с подсказками.
- [Каталог инструментов](../reference/mcp-contracts.md#generated-catalog): создаваемый при сборке перечень инструментов, провайдеров и команд CLI.
- [План развития](../development/roadmap.md): запланированные работы и отслеживание возможностей.
Сообщайте об уязвимостях согласно [SECURITY.md](../../SECURITY.md).
@@ -394,7 +393,7 @@ applicable licenses.
Будем рады вашей помощи с REA! [Откройте issue](https://github.com/morluto/rea/issues), чтобы сообщить об ошибке или предложить функцию, либо [отправьте pull request](https://github.com/morluto/rea/pulls) с улучшениями кода или документации.
Настройка среды разработки и проверки описаны в [CONTRIBUTING.md](../../CONTRIBUTING.md), направления проверки — в [руководстве по тестированию](../development/testing.md), а структура проекта — на [схеме архитектуры](../architecture/architecture.mermaid).
Настройка среды разработки и проверки описаны в [CONTRIBUTING.md](../../CONTRIBUTING.md), направления проверки — в [руководстве по тестированию](../development/testing.md).
## Лицензия
+1 -2
View File
@@ -362,7 +362,6 @@ npx rea-agents@latest setup
- [CLI และ Evidence](../getting-started/cli.md): คำสั่ง การเลือกผู้ให้บริการ สแนปช็อต การนำเข้า/ส่งออก และรหัสการสิ้นสุด
- [สัญญา MCP](../reference/mcp-contracts.md) และ[พรอมป์ต์สำหรับเอเจนต์](../getting-started/mcp-prompts.md): ผลลัพธ์เครื่องมือ เซสชัน และการตรวจสอบตามคำแนะนำ
- [แค็ตตาล็อกเครื่องมือ](../reference/mcp-contracts.md#generated-catalog): รายการเครื่องมือ ผู้ให้บริการ และคำสั่ง CLI ที่สร้างระหว่างการบิลด์
- [แผนพัฒนา](../development/roadmap.md): งานที่วางแผนไว้และรายการติดตามความสามารถ
รายงานช่องโหว่ผ่าน [SECURITY.md](../../SECURITY.md)
@@ -394,7 +393,7 @@ applicable licenses.
เรายินดีรับความช่วยเหลือในการพัฒนา REA! [เปิด issue](https://github.com/morluto/rea/issues) เพื่อรายงานบั๊กหรือเสนอฟีเจอร์ หรือ[ส่ง pull request](https://github.com/morluto/rea/pulls) เพื่อปรับปรุงโค้ดหรือเอกสาร
ดู [CONTRIBUTING.md](../../CONTRIBUTING.md) สำหรับการตั้งค่าสภาพแวดล้อมพัฒนาและการตรวจสอบ ดู[การทดสอบ](../development/testing.md) สำหรับแนวทางการตรวจยืนยัน และ[แผนผังสถาปัตยกรรม](../architecture/architecture.mermaid) สำหรับโครงสร้างโปรเจกต์
ดู [CONTRIBUTING.md](../../CONTRIBUTING.md) สำหรับการตั้งค่าสภาพแวดล้อมพัฒนาและการตรวจสอบ ดู[การทดสอบ](../development/testing.md) สำหรับแนวทางการตรวจยืนยัน
## สัญญาอนุญาต
+1 -2
View File
@@ -356,7 +356,6 @@ Web sitesindeki [uygulamalı rehberlerden](https://rea.tools/tr/guides/) başlay
- [CLI ve Evidence](../getting-started/cli.md): komutlar, sağlayıcı seçimi, anlık görüntüler, içe/dışa aktarma ve çıkış durumları.
- [MCP sözleşmeleri](../reference/mcp-contracts.md) ve [ajan istemleri](../getting-started/mcp-prompts.md): araç sonuçları, oturumlar ve yönlendirmeli araştırmalar.
- [Araç kataloğu](../reference/mcp-contracts.md#generated-catalog): derleme sırasında oluşturulan araç, sağlayıcı ve CLI komutu envanteri.
- [Yol haritası](../development/roadmap.md): planlanan çalışmalar ve yetenek takibi.
Güvenlik açıklarını [SECURITY.md](../../SECURITY.md) üzerinden bildirin.
@@ -388,7 +387,7 @@ korur.
REA'ya katkınızı bekliyoruz! Hata bildirmek veya özellik önermek için bir [issue açın](https://github.com/morluto/rea/issues); kodu veya belgeleri geliştirmek için bir [pull request gönderin](https://github.com/morluto/rea/pulls).
Geliştirme ortamı ve kontroller için [CONTRIBUTING.md](../../CONTRIBUTING.md), doğrulama süreçleri için [test rehberi](../development/testing.md) ve proje yapısı için [mimari harita](../architecture/architecture.mermaid) belgelerine bakın.
Geliştirme ortamı ve kontroller için [CONTRIBUTING.md](../../CONTRIBUTING.md), doğrulama süreçleri için [test rehberi](../development/testing.md) belgelerine bakın.
## Lisans
+1 -2
View File
@@ -362,7 +362,6 @@ npx rea-agents@latest setup
- [CLI та Evidence](../getting-started/cli.md): команди, вибір провайдера, знімки, імпорт/експорт і статуси завершення.
- [Контракти MCP](../reference/mcp-contracts.md) і [промпти агентів](../getting-started/mcp-prompts.md): результати інструментів, сеанси й керовані дослідження.
- [Каталог інструментів](../reference/mcp-contracts.md#generated-catalog): створюваний під час збірки перелік інструментів, провайдерів і команд CLI.
- [План розвитку](../development/roadmap.md): заплановані роботи й відстеження можливостей.
Повідомляйте про вразливості згідно з [SECURITY.md](../../SECURITY.md).
@@ -394,7 +393,7 @@ applicable licenses.
Будемо раді вашій допомозі з REA! [Відкрийте issue](https://github.com/morluto/rea/issues), щоб повідомити про помилку чи запропонувати функцію, або [надішліть pull request](https://github.com/morluto/rea/pulls) з поліпшеннями коду чи документації.
Налаштування середовища розробки й перевірки описано в [CONTRIBUTING.md](../../CONTRIBUTING.md), шляхи верифікації — у [посібнику тестування](../development/testing.md), а структуру проєкту — на [схемі архітектури](../architecture/architecture.mermaid).
Налаштування середовища розробки й перевірки описано в [CONTRIBUTING.md](../../CONTRIBUTING.md), шляхи верифікації — у [посібнику тестування](../development/testing.md).
## Ліцензія
+1 -3
View File
@@ -443,7 +443,6 @@ Exact options, prerequisites aur result contracts ke liye:
- [CLI aur Evidence](../getting-started/cli.md): commands, provider selection, snapshots, import/export aur exit statuses.
- [MCP contracts](../reference/mcp-contracts.md) aur [agent prompts](../getting-started/mcp-prompts.md): tool results, sessions aur guided investigations.
- [Tool catalog](../reference/mcp-contracts.md#generated-catalog): tools, providers aur CLI commands ki generated inventory.
- [Roadmap](../development/roadmap.md): planned work aur capability trackers.
Security vulnerabilities [SECURITY.md](../../SECURITY.md) ke zariye report karein.
@@ -481,8 +480,7 @@ karne ke liye [issue kholein](https://github.com/morluto/rea/issues), ya code au
docs behtar karne ke liye [pull request bhejein](https://github.com/morluto/rea/pulls).
Development setup aur checks ke liye [CONTRIBUTING.md](../../CONTRIBUTING.md),
verification lanes ke liye [testing](../development/testing.md) aur project structure ke
liye [architecture map](../architecture/architecture.mermaid) dekhein.
verification lanes ke liye [testing](../development/testing.md) dekhein.
## License
+1 -2
View File
@@ -362,7 +362,6 @@ Bắt đầu với [hướng dẫn thực hành](https://rea.tools/vi/guides/) t
- [CLI và Evidence](../getting-started/cli.md): lệnh, lựa chọn trình phân tích, ảnh chụp trạng thái, nhập/xuất và trạng thái thoát.
- [Hợp đồng MCP](../reference/mcp-contracts.md) và [prompt cho tác nhân](../getting-started/mcp-prompts.md): kết quả công cụ, phiên làm việc và điều tra có hướng dẫn.
- [Danh mục công cụ](../reference/mcp-contracts.md#generated-catalog): danh sách công cụ, trình phân tích và lệnh CLI được tạo khi dựng dự án.
- [Lộ trình](../development/roadmap.md): công việc dự kiến và theo dõi các khả năng.
Báo cáo lỗ hổng theo [SECURITY.md](../../SECURITY.md).
@@ -394,7 +393,7 @@ applicable licenses.
Chúng tôi hoan nghênh bạn giúp phát triển REA! [Mở issue](https://github.com/morluto/rea/issues) để báo lỗi hoặc đề xuất tính năng, hoặc [gửi pull request](https://github.com/morluto/rea/pulls) để cải thiện mã hay tài liệu.
Xem [CONTRIBUTING.md](../../CONTRIBUTING.md) về thiết lập môi trường phát triển và các bước kiểm tra, [hướng dẫn kiểm thử](../development/testing.md) về các luồng xác minh và [sơ đồ kiến trúc](../architecture/architecture.mermaid) về cấu trúc dự án.
Xem [CONTRIBUTING.md](../../CONTRIBUTING.md) về thiết lập môi trường phát triển và các bước kiểm tra, [hướng dẫn kiểm thử](../development/testing.md) về các luồng xác minh.
## Giấy phép
+1 -2
View File
@@ -362,7 +362,6 @@ npx rea-agents@latest setup
- [CLI 與 Evidence](../getting-started/cli.md):命令、提供者選擇、快照、匯入/匯出和退出狀態。
- [MCP 契約](../reference/mcp-contracts.md)和[AI 代理提示詞](../getting-started/mcp-prompts.md):工具結果、會話和引導式調查。
- [工具目錄](../reference/mcp-contracts.md#generated-catalog):建置時生成的工具、提供者和 CLI 命令清單。
- [路線圖](../development/roadmap.md):計劃中的工作和能力跟蹤。
請按照 [SECURITY.md](../../SECURITY.md) 報告漏洞。
@@ -393,7 +392,7 @@ REA 用於合法的研究、教育、互通性、軟體保存,以及分析你
歡迎幫助改進 REA!你可以[提交 issue](https://github.com/morluto/rea/issues) 報告錯誤或建議功能,也可以[提交 pull request](https://github.com/morluto/rea/pulls) 改進程式碼或文件。
開發設定和檢查見 [CONTRIBUTING.md](../../CONTRIBUTING.md),驗證流程見[測試指南](../development/testing.md),專案結構見[架構圖](../architecture/architecture.mermaid)。
開發設定和檢查見 [CONTRIBUTING.md](../../CONTRIBUTING.md),驗證流程見[測試指南](../development/testing.md)。
## 授權條款
+1 -2
View File
@@ -360,7 +360,6 @@ npx rea-agents@latest setup
- [CLI 与 Evidence](../getting-started/cli.md):命令、提供方选择、快照、导入/导出和退出状态。
- [MCP 契约](../reference/mcp-contracts.md)和[智能体提示词](../getting-started/mcp-prompts.md):工具结果、会话和引导式调查。
- [工具目录](../reference/mcp-contracts.md#generated-catalog):构建时生成的工具、提供方和 CLI 命令清单。
- [路线图](../development/roadmap.md):计划中的工作和能力跟踪。
请按照 [SECURITY.md](../../SECURITY.md) 报告漏洞。
@@ -391,7 +390,7 @@ REA 用于合法的研究、教育、互操作性、软件保存,以及分析
欢迎帮助改进 REA!你可以[提交 issue](https://github.com/morluto/rea/issues) 报告错误或建议功能,也可以[提交 pull request](https://github.com/morluto/rea/pulls) 改进代码或文档。
开发设置和检查见 [CONTRIBUTING.md](../../CONTRIBUTING.md),验证流程见[测试指南](../development/testing.md),项目结构见[架构图](../architecture/architecture.mermaid)。
开发设置和检查见 [CONTRIBUTING.md](../../CONTRIBUTING.md),验证流程见[测试指南](../development/testing.md)。
## 许可证
@@ -1,168 +1,17 @@
# Analysis settings, limits, and recovery
This guide explains the runtime settings design for maintainers and developers:
who owns each value, when an update takes effect, how providers enforce it, and
how to extend the system. The public tool contract is in
[MCP contracts](../reference/mcp-contracts.md#editable-analysis-settings); recorded runtime
checks and their limitations are in the
[verification report](../verification/runtime-analysis-settings.md). The
[limit inventory](rea-limit-inventory.md) lists every numeric `REA_` limit, which
of them are runtime settings, and which stay restart-only.
## Problem and design boundary
A valid workload can exceed a conservative default. An oversized ASAR header
may prevent analysis of the entire archive; a slow Ghidra function may exceed
its decompile deadline. Requiring a new REA process to change either budget
interrupts the investigation and can discard reusable provider state.
REA exposes a curated set of analysis defaults through MCP so callers can
adjust a reported limit and retry the same workload in the running runtime.
Each setting has a typed value, resource bounds, an enforcement owner, and a
defined application point. The design applies across archive admission,
provider startup, operation deadlines, and worker memory requests.
The setter changes in-memory defaults. It does not edit arbitrary environment
variables, configuration files, MCP registrations, or provider installations.
Those mechanisms have different owners and lifetimes. It also cannot change a
client deadline, extend accepted work, release retained resources, or remove a
fixed representation limit. Exposing a setting requires a working enforcement
path, not just an entry in the tool schema.
Further ceilings that should become settings are tracked in
[#6176](https://github.com/morluto/rea/issues/6176). Naming honesty for limit
errors is [#5910](https://github.com/morluto/rea/issues/5910).
## Ownership and data flow
| Owner | Responsibility |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [Domain definitions](https://github.com/morluto/rea/blob/main/src/domain/analysisSettingDefinitions.ts) and [types](https://github.com/morluto/rea/blob/main/src/domain/analysisSettings.ts) | Exact setting IDs, value types, shared bounds/defaults, units, provider/operation associations, application points, and structured limit metadata. Numeric constants stay with their domain owner. |
| [Launch parser](https://github.com/morluto/rea/blob/main/src/config/analysisSettings.ts) | Parse selected launch values once, preserving an invalid value as a typed configuration failure rather than substituting a default. |
| [AnalysisSettings](https://github.com/morluto/rea/blob/main/src/application/AnalysisSettings.ts) | Own one runtime's launch baseline, immutable override revisions, atomic updates, inspection, and accepted-operation snapshots. It does not own provider lifecycle or cleanup. |
| [Composition](https://github.com/morluto/rea/blob/main/src/main/eagerRuntime.ts) and [typed configuration views](https://github.com/morluto/rea/blob/main/src/config/runtimeAnalysisSettings.ts) | Inject the same settings reader into providers and workflows; translate overrides into the configuration each consumer understands. |
| Provider or resource owner | Resolve the effective budget, enforce it at the applicable boundary, and attach the actual value and known source to failures. |
| [MCP registration boundary](https://github.com/morluto/rea/blob/main/src/server/EvidenceMcpServerCore.ts) | Enter the operation's settings scope before invoking its handler. |
| [Settings contracts](https://github.com/morluto/rea/blob/main/src/contracts/analysisSettingsContracts.ts) and [settings tool bindings](https://github.com/morluto/rea/blob/main/src/server/serviceToolBindings.ts) | Validate named requests and deliver inspection/update results without requiring an open target or healthy analysis provider. |
The normal path is: composition creates the store, an MCP handler captures its
current revision, and providers read that snapshot when resolving budgets.
If an owner rejects work, it reports the effective limit through the shared
error projection. A subsequent settings update publishes a new revision for
later handlers. It does not reach into the failed operation or retry it.
### Accepted-operation snapshots
`AnalysisSettings.run()` installs the current immutable snapshot in
`AsyncLocalStorage`. Its `read` function returns that snapshot inside the
operation and the latest revision outside it. Providers depend on the reader
contract rather than on the mutable store or an ambient environment lookup.
Acceptance here is entry into the registered handler's settings scope, not
arrival of bytes at the MCP transport. Work queued or awaited within that scope
keeps its snapshot. Deferred server initialization must still dispatch through
the canonical scoped handler.
| Event | Revision used |
| --------------------------------------------------------- | ----------------------------------- |
| Operation A enters its handler, then waits for a provider | Current revision 0 |
| A settings update publishes revision 1 | Future handlers can read revision 1 |
| Operation A resumes and starts its worker | Its accepted revision 0 |
| Operation B enters its handler | Revision 1 |
This gives each operation stable budget semantics even if another connection
updates settings while it waits. `next_worker` and `next_startup` describe where
an accepted value is applied; they do not cause workers or startups belonging
to an older operation to adopt a newer revision.
Inspection deliberately reads the store's current defaults, rather than the
calling operation's snapshot. It reports `active_values.status: "not_observed"`:
an inspection result cannot establish the budget or remaining time of an
already-running worker.
### Composition and embedding
The MCP runtime creates one store and supplies its reader to provider factories.
`createServer` uses a supplied store or creates one, and wires its default
providers to that store. An embedder supplying a custom binary session or other
provider must also inject the same reader into that provider's composition and
pass the store to `createServer`. Merely exposing the settings tools cannot
make a custom provider consume updates.
Keep default factories, explicitly supplied providers, transport composition,
and deferred handler dispatch covered separately where their wiring differs.
Resolve settings at the operation boundary; copying a runtime value into a
provider constructor would freeze it at launch. For entrypoints outside the
MCP wrapper, an embedder needing the same snapshot guarantee must establish
the operation scope with `AnalysisSettings.run()`.
## Turn a hardcoded limit into a runtime setting
A hardcoded limit becomes an `REA_` runtime setting. Give it a default, a
floor, and a maximum. An error names the setting, the effective value, the
source, and the range.
Put the number in a named constant with a unit. Do not leave it as a magic
number at the call site. The setting's unset value is that constant. Pure
numeric contracts live in `src/domain/analysisResourceLimits.ts`
or their existing domain owner. `analysisSettingDefinitions.ts` binds the
curated runtime IDs to those same bounds, defaults and application points.
Environment parsers and recovery text stay under `src/config/`; register launch
schemas on `environmentSchema` so startup and doctor agree. Add launch settings
to `SELECTED_REGISTRATION_SETTINGS` when setup should forward them. Unset keeps
today's behavior. An invalid launch value remains a configuration failure,
never a silent fallback; its validation boundary determines whether MCP can
start (see [invalid launch configuration](#invalid-launch-configuration)). An
invalid runtime write is `invalid_request` and changes nothing.
For example, `regex.matching_deadline_ms` and its launch seed
`REA_REGEX_MATCHING_DEADLINE_MS` share a 5000 ms default, 1 ms floor and
2147483647 ms maximum. Node schedules a longer `setTimeout` delay as 1 ms.
Changing the runtime setting affects the next accepted search; changing the
launch environment affects the next REA process.
[`REA_MCP_MAX_RESPONSE_BYTES`](https://github.com/morluto/rea/blob/main/src/config/mcpResponseBudget.ts)
is the byte-budget shape: a decimal safe integer with a 10 MiB floor
(`MINIMUM_RESPONSE_BYTES`), the same shared schema, and no silent fallback. A
change needs a REA restart and a matching client receive buffer. It does not
raise REA's reserved string limit or Node's string ceiling. Like the regex
deadline, it is in `SELECTED_REGISTRATION_SETTINGS`, so setup forwards an
explicit selection into the client registration.
Windows ChangeTime admission waits out a fresh timestamp before recording a
baseline. `REA_WINDOWS_CHANGE_TIME_DRIFT_MS` (default 2000 ms, floor 1 ms,
maximum 60000 ms), `REA_WINDOWS_CHANGE_TIME_SETTLE_POLL_MS` (default 25 ms,
floor 1 ms, maximum 1000 ms), and `REA_WINDOWS_CHANGE_TIME_SETTLE_MAX_POLLS`
(default 40, floor 1, maximum 1000) are runtime settings. Unset keeps those
defaults. An invalid launch value is a configuration error: it names the
setting, the rejected value, source `setting`, the default, the floor, the
maximum, and `update_mode: "runtime"`. It omits `pending_restart` because
the rejected value is not an accepted configuration. Change the
active value with `update_analysis_settings`. The launch seed must be a
positive decimal integer in that range. Setup forwards an explicit selection.
When the poll budget runs out, admission keeps the last observation
instead of failing the readable file. Raising a setting only changes how long
that wait can last. It does not change Windows ChangeTime itself.
A per-call budget can have a runtime default without having an environment
setting. JavaScript `max_heap_mb`
(CLI `--max-heap-mb`) is an integer from 128 to 16384 MiB, default 1024. It
applies on the next analysis, which starts a new worker, and does not restart
REA. It does not raise the parent result budget, transfer ceilings, or fixed
parser limits.
Host memory and `NODE_OPTIONS` do not raise a REA admission unless that
admission's recovery says so. The JavaScript parent result budget is one that
does: its recovery says to set `NODE_OPTIONS` (for example
`--max-old-space-size=<MiB>`) on the process that starts REA, then restart
that process. `max_heap_mb` does not raise it.
Use this guide to inspect and change REA analysis budgets, and to recover from
a resource limit. See the [MCP contracts](mcp-contracts.md#editable-analysis-settings),
the [limit inventory](rea-limit-inventory.md), and the
[verification report](../verification/runtime-analysis-settings.md).
## Runtime settings through MCP
`inspect_analysis_settings` lists the curated settings, their current and launch
values, source, bounds, application point and relevant operation names. Filters
by exact setting IDs, provider or operation intersect. Active worker values are explicitly `not_observed`; a configured default is
not a measurement of active work. Inspection also separates known server limits from unknown client deadlines and receive buffers.
by exact setting IDs, provider or operation intersect. Inspection marks active
worker values as `not_observed` and distinguishes known server limits from
unknown client deadlines and receive buffers.
`update_analysis_settings` accepts an atomic `changes` array. Each entry names
an exact `setting` and either `action: "set"` with a schema-validated `value`, or
@@ -178,23 +27,6 @@ checks all happen before publishing the replacement snapshot; a rejected batch
cannot partially apply. Clients coordinating writes can supply
`expected_revision`; without it, valid updates apply to the current state.
| Runtime setting | Application point |
| --------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| `asar.max_header_bytes` | Next archive operation, including full JavaScript application analysis |
| `asar.max_listing_bytes` | Next expanded ASAR listing, independently of packed header bytes |
| `ghidra.startup_timeout_ms`, `hopper.startup_timeout_ms` | Next provider startup attempt |
| `ghidra.decompile_timeout_seconds` | Next operation on the existing Ghidra Program; `null` means unbounded |
| `ghidra.decompile_max_payload_mib` | Next native decompile; `null` preserves the selected provider's payload default |
| `ghidra.value_flow_max_operations`, `ghidra.value_flow_max_inputs_per_operation`, `ghidra.value_flow_max_edges` | Next function value-flow projection on the existing Program |
| `jadx.operation_timeout_ms` | Next JADX operation |
| `regex.matching_deadline_ms`, `regex.worker_heap_request_mib` | Next search / new regex worker |
| `capture.decoder_old_generation_mib` | Next owned capture decoder |
| `javascript.analysis_timeout_ms`, `javascript.max_heap_mb` | Next source analysis / new JavaScript worker |
| `javascript.member_mutation_alias_states` | Next JavaScript application, web bundle or reference-source analysis |
| `wasm.command_timeout_ms` | Next WABT operation |
| `native.matching_representation_bytes` | Next `match_native_functions` request |
| `zstd.max_frames` | Next exact Zstandard decode for an ELF section, OTA `REPLACE_ZSTD` operation, or GPU payload |
### Precedence and lifetime
Where a setting supports an explicit per-call argument, precedence is:
+2 -5
View File
@@ -1757,11 +1757,8 @@ failing owner supports runtime recovery; `inspect_analysis_settings` is optional
when those facts are supplied. Updates are atomic, apply to new work, survive
target close/open, and vanish when REA exits. Explicit per-call arguments take
precedence. Neither tool changes host deadlines or resolves retained cleanup.
See [runtime settings and recovery](../design/limits-and-recovery.md#runtime-settings-through-mcp)
for the full setting list, reset/revision semantics and ASAR retry example.
For implementation ownership, accepted-operation snapshots, provider wiring,
and extension guidance, see the
[maintainer design](../design/limits-and-recovery.md#ownership-and-data-flow).
See [runtime settings and recovery](limits-and-recovery.md#runtime-settings-through-mcp)
for inspection, reset and revision semantics and an ASAR retry example.
Ghidra and Hopper startup updates apply to the next startup attempt without
restarting REA. Ghidra decompile timeout updates apply on the existing Program.
@@ -32,23 +32,9 @@ The other values reported here are in force, so `pending_restart` is false. Pros
restart REA is marked `prose`. `mcp_server_restart_required` is a
server-identity alignment state in `src/process/ServerIdentity.ts`, not a setting field.
None pending. No numeric `REA_` limit is absent from this tree.
## Counts
| Category | Count |
| --------------------------------------------------------------------- | ---------------------------------------------------------------------------: |
| Runtime analysis settings | 32 (29 have an `REA_` seed; 3 have a per-call override and no launch seed) |
| Per-call numeric `REA_` limits still read from the launch environment | 0 |
| Restart-only numeric `REA_` limits | 15 |
| Numeric `REA_` candidates recognized in TypeScript source | 41 |
| Numeric `REA_` controls with external or generated-reader provenance | 2 |
| Non-numeric `REA_` settings kept restart-only | 52 caller settings, plus process-protocol names that are not caller settings |
| Hardcoded ceilings left for follow-up | grouped below; none converted in the inventory change |
## Runtime analysis settings
Both runtime tables cover the 32 `ANALYSIS_SETTINGS` entries adjustable with
These tables cover the `ANALYSIS_SETTINGS` entries adjustable with
`update_analysis_settings`. Each call reads the snapshot
accepted for that operation. Launch source is `default` or `setting`; a runtime
override is `source: "runtime"`. The structured field is `update_mode: "runtime"` and `pending_restart: false`.
@@ -204,29 +190,6 @@ such as `REA_COMMAND_COMPLETE_`, and the `ERR_REA_WINDOWS_NATIVE` code.
without the `REA_` prefix. Paths and the provider choice among them stay
restart-only for the same reason as the table above.
## Hardcoded ceilings left for follow-up
These are checked per call and tell the caller this release has no runtime
override. They are not `REA_` settings, so the numeric-limit check does not
list them. Each family has its own owner. Turning one into a setting needs that
owner's default, floor, maximum, and an error that carries the setting id,
value, source, and range. Format and protocol ceilings that the
[limits guide](limits-and-recovery.md) already calls fixed stay fixed. In
particular, JSON nesting stops at `MAX_JSON_DEPTH` (1000) and the debugger
control-reply budget stays separate from
`REA_DEBUGGER_MAX_COMMAND_OUTPUT_BYTES`.
| Family | Examples | Follow-up |
| ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------- |
| Native structural input ceilings | PE resources, imports, load config, certificates, exports, initializers, binary hardening, Windows shortcuts | One setting per ceiling, or a shared input budget only where the owners match. |
| Native plist | `MAX_NATIVE_PLIST_BYTES`, decode bytes, nesting depth | Separate from JSON depth. |
| SQLite inspection | concurrent inspections, input bytes, diagnostic bytes | Pool width stays restart-only if it sizes the worker set; byte budgets can become settings. |
| Producer command allowances | fixed command deadline and retained output where the text says there is no runtime override | Distinct from per-call `producer_limits`. |
| Hopper caller-scan retention and page allowances | `HOPPER_CALLER_SCAN_RETENTION_BYTES`, `HOPPER_CALLER_PAGE_ALLOWANCE_BYTES` | Explicitly not raised by the scan time budget. |
| Rizin frame protocol | `MAX_FRAME_BYTES`, queued frames | Protocol bounds, not caller budgets. |
| Debugger detach and control replies | `DETACH_TIMEOUT_MS`, `DEBUGGER_CONTROL_REPLY_BYTES` | Ownership deadlines, not the shared command deadline. |
| Web network capture nesting | `max_nesting_depth` already has a per-call parameter | The fixed depth maximum is the follow-up, not the parameter. |
## Static check
`npm run lint` owns this check: it runs
@@ -1,10 +0,0 @@
# Plan
1. Check issue/timeline and complete open/closed PR searches; review #2406.
2. Extend the existing core-module WABT inspection in an isolated worktree.
3. Extend producer-owned inspection with optional typed interface facts;
preserve unknown unsupported signatures and exact WAT forms.
4. Add shared Evidence-only comparator and strict input/output contracts.
5. Register additive CLI/MCP workflow and documentation.
6. Validate original-module workflows, malformed/unknown/cancellation cases;
run checks, independent review, repair findings and rerun affected checks.
@@ -1,63 +0,0 @@
# Core WebAssembly interface comparison (#2356)
## Outcome and scope
Compare two exact authenticated `inspect_wasm_artifact` Evidence inputs, inline
or retained session references, under required `scope: imports | exports | both`.
No module acquisition or execution occurs during comparison. This is a derived
workflow within existing WABT inspection authority, not a new provider.
Producer-owned typed `interface` facts are additive and optional in historical
inspection Evidence. WABT's validated canonical WAT owns decoding; exact original
forms and names remain available. Comparison never reparses retained display text.
Function/tag signatures resolve type uses; memory page size defaults to 65536 bytes and explicit custom page sizes are retained; table/memory limits and global types
are compared exactly. Unsupported type/proposal forms remain unknown rather than
being compared by raw text or inferred compatible. Names are exact decoded UTF-8,
without normalization, including empty names, escapes, punctuation and BOM.
## Comparison contract
Return both Evidence IDs and original artifact path/digest/length. Group imports
by exact module/name and exports by exact name, independently of kind, so a kind
change is reported as changed. Unique admitted signatures yield added, removed,
changed or unchanged. Duplicate keys retain every original occurrence and yield
unknown; no Cartesian pairing or deduplication. Missing historical facets and
incomplete inventories prevent absence claims. Unknown signatures do not erase
independently observed entries. Ordering is deterministic by direction and names.
Both subject digest/path and inspection parameters must match normalized artifact
identity. Authenticate Evidence before projection; summary Evidence must be
resolved to its retained complete parent by the caller. Report unknown coverage
and explicit limitations. Exact static equality is not runtime compatibility,
ABI compatibility, linking success or source identity.
## Authority and overlap
Reads supplied Evidence only. MCP records derived Evidence through the existing
handler/ledger; CLI accepts portable inline Evidence from an explicit JSON input.
No new provider, implicit fetch, target mutation or foreign-code execution.
PR #2406 (head 86865035) adds component inspection, preamble routing and embedded
core-module inspection. Its component parser is not required or duplicated here;
shared contract/CLI registration changes remain additive. Core GC/recursive types
are outside admitted signature semantics and keep unknown mappings.
## Resource admission
Typed producer rows, names and declaration tokenization are admitted before
allocation against the selected `max_interface_bytes` allowance (default 32 MiB).
Inspection and comparison select this allowance independently; comparison cannot
restore producer facts omitted under a smaller inspection allowance.
Comparison uses linear grouping and cooperative transport yields; it never
builds Cartesian duplicate pairings. CLI JSON input retains the shared file
admission gate. Token usage and peak process-family memory remain unmeasured.
## Verification
Original owned modules assembled using WABT 1.0.42 cover semantically equivalent
encodings, changes of kind/signature, names/duplicates, imported index spaces,
tables/memory/globals/tags, unknown types and historical incomplete Evidence.
Exercise authenticated identity, cancellation, retained lookup, CLI/MCP parity
and advertised schemas. Run focused existing WASM/Evidence tests, repository
checks and docs validation; independent subagent review before handoff.
Format reference: https://webassembly.github.io/spec/core/binary/modules.html
@@ -1,8 +0,0 @@
# Tasks
- [x] Confirm scope and overlap boundaries against #2406.
- [x] Record spec and implementation plan.
- [x] Implement typed producer interface and shared comparison.
- [x] Add CLI/MCP contracts and public workflow tests.
- [x] Run focused, static and documentation checks.
- [x] Resolve independent review findings and rerun relevant checks.
@@ -1,47 +0,0 @@
# Verification
Verified base: a2d8b94dd50dab8d966239dd63ab84718aa8b4b4 (fetched main).
The change was reapplied without conflicts and relevant checks rerun.
- Focused existing/new parser, provider, service, contract and CLI/MCP tests:
8 files / 56 tests passed.
- After the final partial-uniqueness correction, reran service and compiled
CLI/MCP boundary tests: 2 files / 5 tests passed.
- `npm run check`: typecheck, lint, formatting, knip, module boundaries and
architecture guards passed. Lint reports warnings; no errors.
- `npm run docs:generate`, `npm run docs:check` and
`npm run verify:test-discovery` passed; every test file was discovered exactly once.
- Real WABT 1.0.42 comparison through compiled CLI and stdio MCP passed:
equivalent padded LEB128 original encodings, function signatures, all admitted
kinds, custom memory page size, escaped/BOM names, empty interfaces, explicit
scope, duplicate imports and unadmitted exception reference signatures.
- Existing real WABT artifact verifier passed after correcting its stale inline
partial-observation assumption to resolve the MCP retained reference from the
Evidence bundle and authenticate the original record.
## Independent review
Three findings repaired at their owning boundary:
1. Memory page size omitted: now preserved, default 65536 canonicalized.
2. Shared signature expansion undercounted: charge every retained occurrence.
Reviewer independently measured the 1000-params/10000-exports case: original
262956-byte WAT produced 61824014-byte JSON before correction. It now retains
1949 observations in a partial facet, with 12046676-byte JSON and an explicit
capacity issue. Original WAT stays available; incomplete coverage prevents
absence and uniqueness claims.
3. Partial singleton uniqueness: comparison now returns unknown whenever either
selected inventory is incomplete, including matched names.
Final independent source review reported no actionable findings. Review does not
replace the executed tests or real-tool evidence.
## Scope and measurement limits
On the original implementation base f254f5a, the complete comparison verifier reported 7.98 seconds elapsed, 6.56 user and
3.13 system seconds, and 429441024 bytes maximum RSS via macOS `/usr/bin/time -l`.
These are command-accounting measurements, not aggregate concurrent process-family
memory or model tokens. Token usage and full process-family peak are unmeasured.
Real-tool verification covers macOS arm64 only; Linux/Windows remain unverified.
No module was instantiated/executed and no source was fetched. Static equality
is not runtime compatibility. Full CI is separate from this local verification record.
-54
View File
@@ -1,54 +0,0 @@
# Feature specifications
This directory indexes proposals and implementation records. It is not a catalog
of current capabilities; use the [documentation directory](../README.md) for
current guides. Preserve original requirements and dated verification evidence
when later increments change behavior.
New feature directories use one `spec.md`, one `plan.md` and one `tasks.md`.
Some historical records have fewer artifacts; their presence or absence does not
establish completion. Do not invent past plans or completed tasks to fill gaps.
Follow [documentation ownership and authoring](../development/documentation.md#feature-lifecycle)
for new work, roadmap granularity and producer-owned contracts.
## Environment roadmaps
- [Agent environments](agent-environments/README.md)
- [Desktop application environments](desktop-app-environments/README.md)
## Other feature records
- [GDB executable selection](native/gdb-executable/spec.md) ([plan](native/gdb-executable/plan.md), [tasks](native/gdb-executable/tasks.md))
- [Core WebAssembly interface comparison (#2356)](2356-wasm-interface-comparison/spec.md) ([plan](2356-wasm-interface-comparison/plan.md), [tasks](2356-wasm-interface-comparison/tasks.md), [verification](2356-wasm-interface-comparison/verification.md))
- [Inspect APK signature schemes (v1–v3.1)](apk-signature/spec.md)
- [Documentation organization](documentation/organization/spec.md) ([plan](documentation/organization/plan.md), [tasks](documentation/organization/tasks.md), [verification](documentation/organization/verification.md))
- [Android boot and vendor_boot images](firmware/android-boot-image/spec.md) ([plan](firmware/android-boot-image/plan.md), [tasks](firmware/android-boot-image/tasks.md))
- [V8 cached-data compilation boundaries](javascript/v8-cached-data/spec.md) ([plan](javascript/v8-cached-data/plan.md), [tasks](javascript/v8-cached-data/tasks.md))
- [Android `.note.android.ident` ELF note decoding](native/android-elf-ident-note/spec.md) ([plan](native/android-elf-ident-note/plan.md), [tasks](native/android-elf-ident-note/tasks.md))
- [Native call source coordinates](native/call-source-locations/spec.md) ([plan](native/call-source-locations/plan.md), [tasks](native/call-source-locations/tasks.md), [verification](native/call-source-locations/verification.md))
- [DWARF compile-unit inspection](native/dwarf-units/spec.md) ([plan](native/dwarf-units/plan.md), [tasks](native/dwarf-units/tasks.md))
- [ELF separate debug-file linkage](native/elf-debug-link/spec.md) ([plan](native/elf-debug-link/plan.md), [tasks](native/elf-debug-link/tasks.md))
- [Go static string-header literal recovery](native/go-string-literals/spec.md) ([plan](native/go-string-literals/plan.md), [tasks](native/go-string-literals/tasks.md))
- [Windows Shell Link shortcut inspection](native/windows-shortcut/spec.md) ([plan](native/windows-shortcut/plan.md), [tasks](native/windows-shortcut/tasks.md))
- [NTFS $MFT and USN Journal inspection](native/ntfs-mft/spec.md) ([plan](native/ntfs-mft/plan.md), [tasks](native/ntfs-mft/tasks.md))
- [Solidity terminal metadata inspection](solidity/cbor-metadata/spec.md) ([plan](solidity/cbor-metadata/plan.md), [tasks](solidity/cbor-metadata/tasks.md), [verification](solidity/cbor-metadata/verification.md))
- [Inspect a V8 code cache container](v8/code-cache-inspection/spec.md) ([plan](v8/code-cache-inspection/plan.md), [tasks](v8/code-cache-inspection/tasks.md))
- [Deno compile executable inventory and extraction](artifacts/deno-standalone/spec.md) ([plan](artifacts/deno-standalone/plan.md), [tasks](artifacts/deno-standalone/tasks.md))
- [Inspect Maven POM and Gradle module metadata](artifacts/maven-gradle-metadata/spec.md) ([plan](artifacts/maven-gradle-metadata/plan.md), [tasks](artifacts/maven-gradle-metadata/tasks.md))
- [ELF dynamic dependencies](native/elf-dependencies/spec.md) ([plan](native/elf-dependencies/plan.md), [tasks](native/elf-dependencies/tasks.md))
- [ELF unwind function ranges](native/elf-unwind-ranges/spec.md) ([plan](native/elf-unwind-ranges/plan.md), [tasks](native/elf-unwind-ranges/tasks.md))
- [Linux kernel build config](native/kernel-build-config/spec.md) ([plan](native/kernel-build-config/plan.md), [tasks](native/kernel-build-config/tasks.md))
- [Native initializers](native/native-initializers/spec.md) ([plan](native/native-initializers/plan.md), [tasks](native/native-initializers/tasks.md))
- [Rust dependency metadata in WebAssembly modules](native/rust-wasm-auditable/spec.md) ([plan](native/rust-wasm-auditable/plan.md), [tasks](native/rust-wasm-auditable/tasks.md))
- [PPC64 ELFv2 Power ISA 3.0 lane](native/ppc64-elfv2/spec.md) ([plan](native/ppc64-elfv2/plan.md), [tasks](native/ppc64-elfv2/tasks.md))
- [Release exposure audit](artifacts/release-exposure/spec.md) ([plan](artifacts/release-exposure/plan.md), [tasks](artifacts/release-exposure/tasks.md))
- [CycloneDX dependency view](analysis-views/cyclonedx-dependencies/spec.md) ([plan](analysis-views/cyclonedx-dependencies/plan.md), [tasks](analysis-views/cyclonedx-dependencies/tasks.md))
- [NuGet package inspection](artifacts/nuget-nupkg/spec.md) ([plan](artifacts/nuget-nupkg/plan.md), [tasks](artifacts/nuget-nupkg/tasks.md))
- [Recoverable analysis budgets](analysis/recoverable-budgets/spec.md) ([plan](analysis/recoverable-budgets/plan.md), [tasks](analysis/recoverable-budgets/tasks.md))
- [Per-call EVM producer budgets](evm/producer-limits/spec.md) ([plan](evm/producer-limits/plan.md), [tasks](evm/producer-limits/tasks.md))
- [Android OTA payload inspection](firmware/android-ota-payload/spec.md) ([plan](firmware/android-ota-payload/plan.md), [tasks](firmware/android-ota-payload/tasks.md))
- [Windows ReFS filesystem authority](native/windows-refs/spec.md) ([plan](native/windows-refs/plan.md), [tasks](native/windows-refs/tasks.md))
- [Historical capture admission budgets](web/historical-capture-budgets/spec.md) ([plan](web/historical-capture-budgets/plan.md), [tasks](web/historical-capture-budgets/tasks.md))
- [Per-call source-map budget recovery](web/source-map-budget-recovery/spec.md) ([plan](web/source-map-budget-recovery/plan.md), [tasks](web/source-map-budget-recovery/tasks.md))
-95
View File
@@ -1,95 +0,0 @@
# Agent environment implementation index
This index covers all 26 PRs authored by
[earakely-scale](https://github.com/morluto/rea/pulls?q=is%3Apr+author%3Aearakely-scale)
in `morluto/rea`, checked on 2026-10-25 against main
`5d428390996498bc4dcca4da934641557f9109bc`. Twenty-five were merged; #5722
was closed without merging. The table describes the resulting work rather
than treating each original PR proposal as the current contract.
Start with the [quickstart](../../agent-environments-quickstart.md) for a
user workflow or the [reference](../../agent-environments.md) for current
contracts. [Design issue #4933](https://github.com/morluto/rea/issues/4933)
records the original four-part proposal. Its stateless replay description
predates state serving and confirmed writes.
## PR map
All entries are merged unless marked otherwise. Verification links point
to the corresponding slice's recorded checks, with their original versions,
platforms, failures, and limitations.
| PR | Contribution | Verification |
| -------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| [#4954](https://github.com/morluto/rea/pull/4954) | Project HAR Evidence into an environment manifest with inferred tool templates and explicit unknowns. | [Manifest view](manifest-view/verification.md) |
| [#4955](https://github.com/morluto/rea/pull/4955) | Add explicit streamable HTTP serving for REA MCP; stdio remains the default. | [HTTP transport](http-transport/verification.md) |
| [#4975](https://github.com/morluto/rea/pull/4975) | Serve retained exchanges as MCP tools, with the environment card and replay data-plane stub. | [Environment serve](environment-serve/verification.md) |
| [#4999](https://github.com/morluto/rea/pull/4999) | Export authenticated capture/manifest pairs as pinned AgentEnv bundles with a verifier and smoke task. | [Environment export](environment-export/verification.md) |
| [#5182](https://github.com/morluto/rea/pull/5182) | Accept browser-scenario Evidence as a manifest, serve, and export input. | [Scenario capture](scenario-capture/verification.md) |
| [#5293](https://github.com/morluto/rea/pull/5293) | Accept Evidence-file sources for richer captures and add opt-in sibling-pair path templating. | [Rich captures](rich-captures/verification.md) |
| [#5319](https://github.com/morluto/rea/pull/5319) | Extract initial entities, documents, and checked read plans with the environment-state view. | [State view](state-view/verification.md) |
| [#5351](https://github.com/morluto/rea/pull/5351) | Make state serving the default; add reset/load/get operations, replay fallback, and `--replay-only`. | [State serve](state-serve/verification.md) |
| [#5352](https://github.com/morluto/rea/pull/5352) | Back more read shapes with state and describe tool responses and annotations. | [State coverage](state-coverage/verification.md) |
| [#5600](https://github.com/morluto/rea/pull/5600) | Apply create, update, delete, and document effects only when later reads confirm them without contradiction. | [State writes](state-writes/verification.md) |
| [#5664](https://github.com/morluto/rea/pull/5664) | Share inferred path positions across tools with opt-in `prefix-variance`, connecting literal writes to templated reads. | [Prefix variance](prefix-variance/verification.md) |
| [#5699](https://github.com/morluto/rea/pull/5699) | Compare the environment offline against separately recorded probe sequences from the application. | [Fidelity compare](fidelity-compare/verification.md) |
| [#5722 (closed, unmerged)](https://github.com/morluto/rea/pull/5722) | Proposed independently reset recording sessions. The author closed it after six applications showed no held-out agreement gain; identified model gaps took priority. | [Closure explanation](https://github.com/morluto/rea/pull/5722#issuecomment-6305512072) |
| [#5787](https://github.com/morluto/rea/pull/5787) | Decide whole-list membership per request line so mixed filtered/unfiltered tools can show new entities. | [List lines](list-lines/verification.md) |
| [#5800](https://github.com/morluto/rea/pull/5800) | Learn supported list filters, substring search, sorting, paging, and counters from recordings. | [List queries](list-queries/verification.md) |
| [#6136](https://github.com/morluto/rea/pull/6136) | Explain copied or renamed values and regenerated scalar or nested UUIDs while withholding unsupported links. | [Assigned values](write-assigned-values/verification.md) |
| [#6138](https://github.com/morluto/rea/pull/6138) | Preserve the clock spelling and precision each read view shows after a write. | [View clock spelling](view-clock-spelling/verification.md) |
| [#6169](https://github.com/morluto/rea/pull/6169) | Handle bodiless write replies, proven omitted fields, projected reads, and digit-group sequences. | [Write coverage](write-coverage/verification.md) |
| [#6385](https://github.com/morluto/rea/pull/6385) | Find more state targets, distinguish read-only POSTs, and handle variant views and differing create/read paths. | [State targets](state-targets/verification.md) |
| [#6897](https://github.com/morluto/rea/pull/6897) | Extend evidence-gated rules for bulk writes, item actions, generated values, query constraints, and ordering. | [Write rules](write-rules/verification.md) |
| [#6929](https://github.com/morluto/rea/pull/6929) | Bound create learning and invalidate stale write proofs. The original branch also developed the one-step builder and coverage report, integrated through stacked #6946 before this PR merged. | [Build workflow and verification](environment-build/verification.md), [final PR scope](https://github.com/morluto/rea/pull/6929) |
| [#6946](https://github.com/morluto/rea/pull/6946) | Complete the agent workflow with same-origin scenario request actions, `export_environment_bundle`, and recording instructions; integrate `environment-build` and coverage from its stack. | [Environment from a prompt](environment-prompt/verification.md) |
| [#6967](https://github.com/morluto/rea/pull/6967) | Retain browser request timing so scenario-derived environments can learn write clocks. | [Scenario timing](scenario-timing/verification.md) |
| [#7025](https://github.com/morluto/rea/pull/7025) | Explain composed response strings, trimmed fractional clocks, and generated integer identities. | [Derived values](write-derived-values/verification.md) |
| [#7034](https://github.com/morluto/rea/pull/7034) | Learn compatible create variations across calls, sorted echoes, referenced entities, and nested view projections. | [Create calls](write-create-calls/verification.md) |
| [#7080](https://github.com/morluto/rea/pull/7080) | Reconcile lighter create responses with read-backs and learn re-derived slugs and clocks in whole-object updates. | [Write views](write-views/verification.md) |
Multi-session capture fusion from #5722 is not a shipped capability. Repeated
calls inside one supported capture, as learned by #7034, are a separate feature.
## Evidence to use when describing the feature
The contributor's [example repository](https://github.com/earakely-scale/rea-environments)
contains the original capture/export/evaluation pipeline and links to published
bundles. Its Grafana row records 105 exchanges and 48 manifest tools, matching
the capture count in the demo. The README describes an earlier replay workflow;
its counts and model scores should remain attributed to that snapshot.
The [prompt workflow verification](environment-prompt/verification.md) records
five applications built by an agent from individual prompts: every exported
bundle passed smoke, while three of the five served writes. Later
[timing](scenario-timing/verification.md),
[derived-value](write-derived-values/verification.md), and
[create-call](write-create-calls/verification.md) work addresses specific gaps
found in those recordings. The earlier write counts are not current limits.
The [write-view verification](write-views/verification.md) records a later
held-out round where 10 of 20 targeted write tools were served, up from 8.
Its original census retained 132 served writes across 69 existing captures.
These are source-reported measurements at the recorded revisions. The
[merged PR's review follow-up](https://github.com/morluto/rea/pull/7080)
explicitly says its real-application census and agent tasks were not rerun
after the final fixes; the local CLI/MCP regressions cover those fixes.
Smoke checks demonstrate bundle/framework compatibility for the tested
configuration. Retrieval rewards demonstrate particular task outcomes.
`environment-compare` measures agreement on recorded probes, with explicit
normalizations and omissions. Keep these claims separate, and retain the
version and coverage limits when quoting any result. This index is a source
and PR review; it does not constitute a new real-application or benchmark run.
## Additional feature records
These feature directories supplement the dated census above; this list does not
assert merge or verification status.
- [Saved values in browser scenarios](scenario-saved-values/spec.md)
- [Serve the calls agents make and the values applications count](write-call-values/spec.md)
- [Serve the writes callers make without recorded form fields](write-form-calls/spec.md)
- [Serve the writes that later reads explain](write-later-reads/spec.md)
- [Serve writes whose calls send different members](write-varied-calls/spec.md)
- [Serve sorted creates, listed references and toggles](write-sorts-references-toggles/spec.md)
@@ -1,25 +0,0 @@
# Plan
1. Add `environmentCoverageView.ts`: the request schema, the result fields, the
hint per write reason (`satisfies Record<WriteReason, string>`), a
summarizer over state views and write plans, and the projector, which
projects the environment-state view and summarizes it. Register the kind in
the view unions, the grouping dispatch and the view service (state
accumulator, inferred confidence).
2. Split the export's input read into `readEnvironmentExportFile` and
`environmentExportFile` (parse and seal bytes), both naming the calling
operation, and let the export take an already prepared state.
3. Add `environmentBuild.ts`: classify the capture, project the manifest from
the in-memory Evidence, serialize it as `--format json` writes it to a file,
authenticate the pair from those bytes, name the environment, prepare the
state as the export does, summarize coverage, scan credential names, then
plan (dry run) or export. `environmentBuildReport.ts` holds the scan and the
naming helpers.
4. Register `environment-build` in the CLI: inspect a HAR through the capture
service as `inspect-web-network-capture` does, or read Evidence once as the
export does, and log stages at info.
5. Switch `scripts/verify-agentenv-environment.mjs` to the build command.
6. Document the command, the report, the hints, what ships, and the view.
7. Tests: coverage summary and hint completeness, the view against the state
view, build equivalence with the three-step path in process and through the
CLI, dry run, naming, refusals, the credential scan, and the view over MCP.
@@ -1,96 +0,0 @@
# Build an environment in one step
Issue: https://github.com/morluto/rea/issues/4933
## Outcome
Building an agent environment bundle takes three commands and a hand-written
view request that embeds the whole capture inline, so large captures hit inline
input accounting. The views apply no opt-in template rules by default, while the
published capture-built environments all use the same four, and a local capture
is named after its origin host (`127-0-0-1-3105`). Nothing reports which tools
an environment serves from its state, or why a write tool is withheld.
`rea environment-build <capture> [directory]` builds the bundle in one offline
step and reports what it serves. A new `environment-coverage` analysis view
reports the same summary for any capture, so an agent can check a recording
before building.
## Requirements
- The capture is a `.har` file, inspected as `inspect-web-network-capture`
inspects it, or capture Evidence JSON from `inspect_web_network_capture` or
`capture_browser_scenario`; any other extension is refused before it is
read, and a HAR document saved as `.json` is refused with a hint.
- The manifest is projected from the in-memory capture as retained Evidence,
with the default rules `after-uid-literal`, `opaque-token`,
`sibling-variance` and `prefix-variance` unless `--template-rule` or
`--format-rules-only` selects others; rules apply in the views' order and a
repeated rule is refused, as the views refuse it.
- For the same capture path, every bundle file is byte-identical to what
`inspect-web-network-capture --format json`, `inspect-analysis-view --format
json` (the same rules in the views' order) and `environment-export` (the
build's name) write, Evidence ids included. The Evidence is serialized once
into one exactly sized buffer, whose bytes are both authenticated and shipped.
- The name is `--name`, else the manifest's, unless the origin is a loopback
name or IP literal: then the capture file's name, with a warning; a file name
that yields no portable bundle name is refused, asking for `--name`.
- The report carries the export's tool count, state, package source and files,
plus the capture and manifest identities, `coverage`, warnings and the next
command, shell-quoted. `coverage`
counts read tools answered from the state and replayed (per view reason), and
lists write tools as served or withheld with their reason, plan record, the
contradicting read and a hint; it is null when the state is unavailable.
- Every write reason has a hint; a reason without one fails to compile.
- Credential-named header names, query parameter names and JSON or form body
members that hold a value are reported as a count and the first 20 record or
event pointers, never values, and never refuse a build; the scan cannot
overflow the stack on deeply nested bodies. A body is read as a form
(`application/x-www-form-urlencoded`, by `URLSearchParams`) or as JSON (the
media types replay parses as JSON) by its recorded media type; a body with
none, or one naming neither, is JSON when it starts with `{` or `[` and a form
when it contains `=` and no whitespace, so plain text and empty bodies yield
no pointers. A browser scenario is scanned by event rather than by record:
every retained request and response network-content event's header values and
body, including a response whose request began before the browser was attached
and a transaction that cannot be attributed to one request and response, and
each transaction URL's query parameters once; its pointers name the event's
index in `events.items` (`event 4 response /token`). Each occurrence of a
repeated form field counts, as each repeated header or query parameter does. A
HAR request recorded with structured form parameters and no text, or the null
text mitmproxy's SaveHar records, is scanned by those parameters. Text bodies
over the 4 MiB scan limit, measured in UTF-8 bytes, including a response body
decoded only as a prefix, are not scanned; they are reported as a
`credential-scan-incomplete` warning with a count and the first 20 record or
event and side pointers (`record 3 response`, `event 4 response`), never
contents, and never refuse a build. Binary bodies hold no JSON or form text
and are neither scanned nor reported.
- The inspected HAR's Evidence and the projected manifest are admitted against
the live heap headroom for parsing and sealing before either is serialized, as
a capture Evidence file is before it is read; one that does not fit is refused
as `resource_constraint` before anything is written.
- An empty or NUL-containing capture, directory or package tarball argument is
refused as invalid input; it is never resolved to the working directory.
- Nothing is written before the bundle stage; `--dry-run` writes nothing,
reports the files a build would write and refuses the package tarballs a build
refuses, admitting, reading and hashing, and releasing the tarball as a build
does before copying it, so a tarball whose contents cannot be read is refused:
a close it cannot confirm is reported as incomplete cleanup that keeps its
owner. The directory must be absent or empty.
- SIGINT is checked between stages and after a dry run's last step: a build
cancelled before the bundle stage writes nothing, and one cancelled during the
write names the written bundle.
- The `environment-coverage` view summarizes the environment-state view with
the same rules, refuses what it refuses and is inferred. It does not apply the
serve-time catalog and state admission checks, and says so in a limitation.
- The `real-agentenv` lane builds its bundle with `environment-build`.
## Non-goals
- No change to the three existing commands' contracts, or to what any view
derives or any environment serves.
- No browser launch or network access: scenarios are recorded with
`capture-browser-scenario` first.
- No `--replace`, no refusal on credential names, and no rewriting of the
capture's absolute path, which Evidence identity includes.
- No MCP export tool; that is a separate change.
@@ -1,13 +0,0 @@
# Tasks
- [x] Record the outcome, requirements and non-goals.
- [x] Add the environment-coverage view and register it.
- [x] Split the export's input read and accept a prepared state.
- [x] Add the build module, its report helpers and the CLI command.
- [x] Switch the real-agentenv lane to the build command.
- [x] Document the command, the report, the hints and the view.
- [x] Add domain, service, CLI and MCP tests.
- [x] Run static, formatting, duplication, documentation and test gates.
- [x] Build the 50 published captures and compare them with the three-step path.
- [x] Build environments end to end on Linux VMs and run them with agents.
- [x] Address the independent review.
@@ -1,113 +0,0 @@
# Verification
Executed on macOS with Node v24.22.1 (the checkout's `.nvmrc`) on main `3d4f5565`, and on Ubuntu 24.04 VMs for the
end-to-end runs.
## Gates
- `npm run -s check:fast`, `npm run -s format:check`, `npx knip`, `npm run -s scan:todos`, `npm run -s docs:check`,
`npm run -s verify:test-discovery` and `npm run -s mcp-catalog:check`: passed.
- `npm run jscpd`: 3.52% duplicated lines over 4348 files, as on main (3.52% over 4341).
- `npx vitest run --project domain --project services`: 9537 passed, 6 skipped and 151 failed. The same 151 fail on main
`3d4f5565` in this environment (9513 passed there); none is new.
- `npm run -s test:prepare`, then `npm run -s test:focused --` the environment build, export, export-inputs and serve CLI
boundaries, the analysis-view CLI and MCP boundaries and the environment serve MCP boundary: 7 files, 67 passed and 1
failed, "projects portable artifact inventory after the original ZIP is removed", which fails the same way on main.
- `npm run verify:agentenv:environment` (the `real-agentenv` lane) passed on Ubuntu 24.04 with `agent-env 0.9.1334`.
## Equivalence and coverage over the published captures
Each of the 50 published capture-built environments' captures (capture Evidence JSON) and four scoped HAR recordings
(EspoCRM, Ghost, NocoDB, Sonarr) was built twice: once with `rea environment-build <capture> <dir> --json`, and once
with the three CLI steps, `inspect-web-network-capture --format json` (HAR only), `inspect-analysis-view` with an
`evidence-file` source and the four default rules, and `environment-export --name <the build's name>`. Every file of
every bundle was compared by SHA-256.
| Inputs | Bundles identical | State served | Read tools from state / replayed | Write tools served / withheld | Build / three steps |
| ------------------------- | ----------------- | ------------ | -------------------------------- | ----------------------------- | ------------------- |
| 50 capture Evidence files | 50 of 50 | 50 | 1,100 / 290 | 50 / 143 | 32.9 s / 59.2 s |
| 4 scoped HARs | 4 of 4 | 4 | 166 / 21 | 5 / 12 | 8.3 s / 12.4 s |
- The coverage of every capture equals an independent census of the environment-state view with the same rules (read
views by shape, write plans by verdict and reason).
- 43 of the 50 captures have a loopback origin and are named after their file (`grafana.capture.json` becomes `grafana`)
with a `name-from-file` warning. 20 carry a `credential-named-members` warning; the published captures were scrubbed by
their pipeline, whose placeholder strings still count.
- The withheld writes' reasons: no-state-target 86, contradicted 16, unconfirmed 14, no-observation 13,
unexplained-change 8, side-effect 4, body-unusable 1, incomplete-entities 1.
## End to end
Five environments last rebuilt on 10-23 were built again with this branch's packed CLI on disposable Ubuntu VMs, four
from their scoped HAR recordings and Metabase from its capture Evidence, with `rea environment-build <capture> <dir>
--name <app> --package-tarball <tarball>`. Each bundle then ran its smoke task, a retrieval eval generated from the
bundle's own manifest and capture, and the write eval from its recorded write spec, with two models through a LiteLLM
proxy (`fireworks_ai/gpt-oss-120b`, `fireworks_ai/glm-5p3-flash`), one run per task.
| App | Input | Served tools of manifest | Served writes (build report) | Smoke | Retrieval gpt-oss / GLM | Writes gpt-oss / GLM |
| -------- | -------- | ------------------------ | -------------------------------------------------- | ------ | ----------------------- | -------------------- |
| Ghost | HAR | 35 of 38 | 0 (3 no-state-target) | passed | 12/12 / 8/12 | 0/2 / 0/2 |
| Metabase | Evidence | 40 of 42 | 1 (create contradicted, update unexplained-change) | passed | 12/12 / 12/12 | 1/2 / 1/2 |
| EspoCRM | HAR | 85 of 88 | 0 (2 contradicted, 1 unexplained-change) | passed | 12/12 / 10/12 | 0/2 / 0/2 |
| NocoDB | HAR | 23 of 28 | 0 (4 no-state-target, 1 unconfirmed) | passed | 6/6 / 5/6 | 0/3 / 0/3 |
| Sonarr | HAR | 49 of 50 | 5 (1 side-effect) | passed | 12/12 / 12/12 | 3/3 / 3/3 |
- Every write task passed with both models when the build report listed its tool as served (Metabase's card delete and
Sonarr's release-profile create, update and delete), and failed when it listed it as withheld: 8 of 24 write episodes
passed, exactly the served ones. On main these apps' other writes are withheld; the published v0.2.0 versions were
built with the state-target and write-rule changes, which serve more of them.
- The retrieval misses are GLM answers on bundles byte-identical to the three-step path's; gpt-oss passed all 54.
- The `real-agentenv` lane, switched to `environment-build`, passed from a fresh checkout on Ubuntu with
`agent-env 0.9.1334` and the host's Docker: five public cases, the smoke task passed in 26.6 s, no new containers.
## Review
An independent review rebuilt the branch and tried to refute it. It confirmed byte-equality for pretty-printed,
CRLF and newline-free Evidence, Unicode HARs across output part boundaries, inline and file view sources, browser
scenario Evidence and relative or symlinked paths, and that the refactored export answers 16 success and refusal cases
exactly as main does. Its findings, all addressed:
- The credential scan recursed and a 4 KB body nested 5,000 deep crashed the build; it now walks with its own stack, and
also scans header names, query names and form bodies.
- SIGINT after the capture was read was ignored; the build now checks the signal between stages and writes nothing when
cancelled before the bundle stage.
- The coverage view does not apply the serve-time catalog and state admission checks; a limitation and the docs now say
so.
- A dry run accepted a tarball the build refuses; it now opens it for reading.
- Repeated `--template-rule` values were deduplicated; they are refused as the views refuse them. A HAR saved as `.json`
gets a hint, file-derived names follow the bundle name rules, `localhost.` is anonymous, and the next command is
shell-quoted.
- The `no-observation` hint now covers updates and deletes of entities the state never held; the docs no longer claim
the build launches no process, state the conditions of byte-equality, and name the headers inspection excludes; the
MCP tool description names the view.
## Review round on main `584120e8`
The branch merged main `584120e8`: the export's file read now returns permission refusals through `Result`, as main
does, under the build's operation name, and the `environment-coverage` sentence sits in main's `inspect_analysis_view`
description. Four automated review findings were fixed, each with a test that fails on the merge:
- A browser scenario's retained header values and the query parameters of its recorded URLs are scanned for credential
names as a HAR's are; the manifest and replay record projections are unchanged.
- `--dry-run --package-tarball` admits and releases the tarball through the export's own regular-file scope, so a close
it cannot confirm is retried and then reported as incomplete cleanup that keeps its owner.
- A dry run checks for cancellation after reading the tarball, before it reports a plan.
- Evidence is serialized into one exactly sized buffer instead of chunks joined by a copy. Those bytes are still parsed
and sealed before authentication, so authentication reads exactly what ships.
On macOS with Node v22.23.1: the static gates passed (`npm run jscpd`: 3.53%), `npx vitest run --project domain
--project services` passed (9753, 6 skipped), the environment boundary projects passed (102), and the focused build,
export, export-inputs, serve and analysis-view boundaries with tool schema validity passed (9 files, 96). Rebuilt over
the same 50 captures and four HARs, all 54 bundles are byte-identical to the three-step path's, with the same coverage,
served writes and warnings as before the round.
## Review round on main `3d84215b`
The branch merged main through `3d84215b`: #6946, which carries this builder, in `27a4e3986`, then #7008. Integrating
#6946 took main's event-based credential scan, which also answers the review finding that a scenario transaction with
duplicate responses or content events hid their credential names; a test that both content events of a transaction
recorded twice are scanned fails on `0895c89bc`. The integration had dropped `0895c89bc`'s tests for form text recorded
without a media type and its `body-unusable` hint; both are restored, and main's scan passes the tests.
Rebuilt at `05566419e` over the same 50 captures and four HARs, all 54 bundles are byte-identical to the three-step
path's, and their warnings and credential counts equal the previous round's.
@@ -1,25 +0,0 @@
# Implementation plan
1. Extend `src/application/environment/environmentSource.ts` so
`loadEnvironmentSource` takes the reporting operation and retains the
capture artifact's SHA-256, letting the export reuse the serve command's
authentication and cross-check unchanged.
2. Add `environmentBundle.ts` to plan the bundle from the source alone: the
name rule, the Dockerfile for the registry and tarball package sources, the
verifier, the smoke task, the README and the copy targets.
3. Add `environmentExport.ts` to read each input once through the
regular-file reader, refuse an occupied directory, a missing tarball or an
unreadable input before writing, then write the planned files with
exclusive creation and copy the authenticated bytes and the tarball
byte-exact.
4. Register `environment-export` in `src/cli/environmentCommands.ts` beside
`environment-serve`, sharing the argument descriptions, and in
`CLI_COMMANDS`.
5. Add the `agentenv` scope, `real-agentenv.yml`, the package script and
`scripts/verify-agentenv-environment.mjs`, wire `ci.yml` and extend the
`ciRequiredLanes` and `ciChangeScope` tables.
6. Add services, conformance and cli-boundary tests; document the command in
`docs/getting-started/cli.md`, the bundle and lane in `docs/agent-environments.md` and
`docs/development/testing.md`; record the spec.
No new dependency is introduced; the CLI inventory gains one command.
@@ -1,119 +0,0 @@
# Export an environment manifest as an agent environment bundle
Issue: https://github.com/morluto/rea/issues/4933
## Outcome
`rea environment-export <manifest.json> --evidence <capture.json> <dir>
[--package-tarball <path>] [--name <override>]` writes the manifest and
capture pair that `environment-serve` serves as a bundle folder the agentenv
framework runs with `agent-env run <dir>`: a README with provenance, an env
folder whose Dockerfile installs this exact `rea-agents` version and serves the
copied pair, a Python replay verifier and a smoke task. The hosted
`real-agentenv` lane exports such a bundle from the source-owned Grafana-shaped
capture through the built CLI, packs the checkout into the image and runs it
with the pinned framework release on the runner's Docker. This increment
completes the agent-environment work of the issue; serving came in the
previous increment.
## Requirements
- Read each of the two files once through the regular-file reader, parse it
from those bytes and authenticate and cross-check the pair with
`loadEnvironmentSource` as `environment-serve` does, so the bytes copied into
the bundle are the bytes that were authenticated; every refusal reports
operation `environment-export`, and a manifest projected from a different
capture is refused before anything is written.
- Refuse a bundle directory that exists and is not empty, or that names a file,
with an `invalid_request` whose issue path is `directory`; an absent or empty
directory is accepted. Write every file with the exclusive-create flag so
nothing is ever overwritten.
- Write `README.md`, `envs/<name>/Dockerfile`, `envs/<name>/env.toml`,
`envs/<name>/manifest.json` and `envs/<name>/evidence.json` as byte-exact
copies of the inputs (mode `0600` on POSIX; Windows retains inherited ACLs
and does not provide an owner-only guarantee), `artifacts/check_<name>/verify.py` and
`tasks/smoke.json`, where `<name>` defaults to the manifest's kebab-case name
and `--name` must be a kebab-case label of at most 63 characters for its DNS label that is not a
device name Windows reserves (`con`, `prn`, `aux`, `nul`, `com1`–`com9`,
`lpt1`–`lpt9`). Its HTTP hostname identity must remain unchanged, so numeric
labels interpreted as IP addresses are refused before planning.
- The Dockerfile uses the Node version pinned in `.nvmrc` with the
`bookworm-slim` variant, sets
`MCP_HOST=0.0.0.0`, `MCP_PORT=18765`, and
`MCP_ALLOWED_HOSTS=127.0.0.1,localhost,<name>`, installs Debian's `python3` for the
framework's readiness probe, installs
`rea-agents@<PRODUCT_IDENTITY.packageVersion>` from the registry or, with
`--package-tarball`, copies the tarball as `rea-agents.tgz`, installs it
from `/tmp/` and removes it in the same layer, copies the pair to `/env/`,
switches to the image's `node` user
and runs `rea environment-serve /env/manifest.json --evidence
/env/evidence.json`.
- `verify.py` mirrors the framework's echo example: `async def verify(mcp_url)`
over `mcp.client.streamable_http`, lists the tools and checks the count
equals the manifest's, calls the first `GET` tool without path parameters
with no arguments and checks the replayed `status` equals the recorded status
of that tool's first cited record, prints the description and returns
`[{"id": "replay", "result": <bool>, "description": <both checks>}]`; with no
such tool it checks the count only and says so.
- `tasks/smoke.json` is `deploy_env` of `<name>` on the local sandbox followed
by `env_outcome_verifier` with `file_artifact_id` `check_<name>` and
`verifier_id` `replay`. The README records the capture artifact SHA-256, both
Evidence ids, the manifest view digest, the tool count and the package
source, states what replay does and does not establish, names the run
command as `agent-env run .` from the bundle root (the folder it sits in,
whatever the caller named it), and carries the rights note.
- Print one JSON document with `status: "exported"`, the directory, name, tool
count, both Evidence ids, the pinned `package_source` and the written files
with sizes. Register the flat `environment-export` command in the CLI
inventory; no MCP tool is added.
- Add the `agentenv` CI scope, the reusable `real-agentenv.yml` workflow
(`workflow_dispatch` and `workflow_call` with `build_cache_artifact`,
`ubuntu-24.04`, SHA-pinned actions, `setup-python` 3.12, a virtual
environment with `agentenv-framework==0.9.1431`, the runner's Docker, 30
minutes), the `verify:agentenv:environment` script and
`scripts/verify-agentenv-environment.mjs`, which requires absolute
`REA_AGENT_ENV_COMMAND` and `REA_DOCKER_COMMAND` like every other lane
verifier, runs `agent-env run <dir> --sandbox local` bounded to 15 minutes
and resolves nothing from `PATH`; wire `ci.yml` at the four spots and extend
the two CI guard tests.
## Acceptance and limits
Services tests cover the planned file set, the Dockerfile for both package
sources, the verifier text, the smoke task, the README, the name override and
its refusals, writing into an absent and an empty directory with byte-exact
copies and correct sizes, the tarball copy, and the refusals of a non-empty
directory, a file path, a missing tarball and an inline manifest. The
conformance test pins the registry install to the `package.json` version. The
cli-boundary test writes the folder from the fixture pair through the built
CLI, refuses a non-empty directory leaving it unchanged, and refuses a
mismatched pair without creating the directory. The CI guard tests enumerate
the new consumer, route and classification cases. The local end-to-end run
recorded in `verification.md` is the proof that one exported bundle runs under
`agent-env run` with the smoke task passed and no container left behind.
The export copies bytes and never inspects the tarball; it does not build or
run the image itself. Its writes are not transactional: a host failure after
the first file leaves the partial folder for inspection, as `docs/getting-started/cli.md`
states. The verifier checks one replayed status and the tool count, not every
tool. The lane passes `--sandbox local` as designed although
`tasks/smoke.json` already pins `sandbox_type: local` on its deploy step, so
the flag restates what the task fixes. The lane verifier imports the
Grafana-shaped HAR builder from `tests/fixtures/historicalHar.ts` through
Node's type stripping rather than carrying a second copy under `scripts/`; the
`agentenv` scope lists that fixture so a change to it runs the lane. The lane
proves one framework release on one hosted runner and claims nothing about
any hosted platform. Three additions to the
designed Dockerfile and file set were needed by the framework, each found by
the local run: `MCP_PORT=18765` as the listener default for the port the
framework maps, Debian's `python3` because the framework's local sandbox
probes readiness with `python3 -c "import socket; …"` inside the container and
the slim Node image has none, and `env.toml` naming the environment, because
the framework otherwise reads the name from Python sources the Node image does
not have.
## Deferred issue criteria
This increment closes the agent-environment scope of #4933 together with the
previous three. Running the lane on the maintainer's CI and any follow-up on
hosted platforms are outside this PR.
@@ -1,12 +0,0 @@
# Tasks
- [x] Record the export contract, requirements and the lane.
- [x] Thread the operation name and capture digest through the source loader.
- [x] Plan the bundle: name rule, Dockerfile for both package sources, verifier, smoke task, README.
- [x] Write the bundle with directory, tarball and input refusals and exclusive creation.
- [x] Register the flat CLI command with described arguments and options.
- [x] Add the agentenv scope, workflow, package script and verifier; wire ci.yml; extend the guard tests.
- [x] Add services, conformance and cli-boundary coverage.
- [x] Document the command, the bundle and the lane; record the spec.
- [x] Run static, formatting, duplication, documentation and test gates and the local end-to-end run.
- [x] Repair the review findings (README run command, absolute tool paths, single read, tarball cleanup) and re-run the gates and the end-to-end run.
@@ -1,362 +0,0 @@
# Verification
The initial author record below describes the original macOS tree. The Linux
followup record at the end covers the integrated serve changes and subsequent
repairs in this PR. The two records have different toolchains and cache states.
Verified base: 24574576e4fa74ff56eda965ae287555b7552c03, the tip of the environment-serve increment on fetched main b83b9caf (this increment builds on it).
The worktree carries the manifest-view, streamable-HTTP and serve increments
as commits on upstream main b83b9caf; this increment's changes are uncommitted
edits on top. Every check below ran as written on this tree after the review
repairs; nothing is reported that did not run. Timings are macOS
`/usr/bin/time -l` command accounting (elapsed, user, system seconds and
maximum resident set size of the command and the children it waited for) on
macOS 26.5.1 with Node 22.23.1, npm 12.0.2, Docker 29.5.3 and a Python 3.12.12
virtual environment holding `agentenv-framework 0.9.1334`.
## Review findings addressed
An adversarial review of the first pass found two should-fix findings and
seven nits; each was repaired at its owning boundary before the gates below
ran.
- The bundle README told the reader to run `agent-env run <name>`, which only
works from the bundle's parent when the folder happens to carry the env's
name. The README now says `agent-env run .` from the bundle root and names
the folder's path for any other working directory; the services test
asserts the new block and the absence of the old command.
- The lane verifier resolved `agent-env` and `docker` from `PATH` when the
`REA_*` variables were unset. It now requires absolute
`REA_AGENT_ENV_COMMAND` and `REA_DOCKER_COMMAND`, throwing the standard
actionable message naming the npm script and that nothing is installed, and
checks both paths exist; the workflow exports `REA_DOCKER_COMMAND` from
`command -v docker` beside the virtual environment's `agent-env`;
`docs/development/testing.md` names both variables and drops the `PATH` default. No
Linux preflight was added, so the lane stays runnable on a macOS host.
- The brittle `assert.doesNotMatch(stdout, /failed/)` is gone; exit code `0`
and the `tasks/smoke.json v<n>: passed` summary already decide the case.
- The inner `agent-env run` timeout is 15 minutes inside the 30-minute job,
so a hung run ends with the verifier's failed receipt rather than the
runner's kill; `docs/development/testing.md` says so.
- The pair was read twice: parsed once for authentication and re-read from
disk for the byte-exact copies, so a file replaced between the reads was
copied unchecked. `readEnvironmentExportInputs` now reads each file once
through the regular-file reader, parses the value from those bytes with the
shared UTF-8 JSON parser, and the command passes the same buffers to the
export, which copies them; the refusals of inline JSON, a directory and a
file that is not JSON are typed by role, and the spec, plan and both guides
state the single read.
- The tarball Dockerfile left the 6 MB `rea-agents.tgz` in `/tmp` of the
image; the install layer now removes it (`&& rm /tmp/rea-agents.tgz`),
confirmed by listing `/tmp` in the built image below.
- The verifier passes `--sandbox local` as the design specifies; the spec
records that the task's `sandbox_type: local` already pins the provider and
the flag restates it.
- The verifier's import of the HAR builder from `tests/fixtures/` through
Node's type stripping is kept and recorded in the spec's limits with the
reason (no second copy under `scripts/`; the scope lists the fixture).
- Writes are not transactional; `docs/getting-started/cli.md` now states that a host failure
after the first file leaves the partial folder for inspection and that the
next attempt refuses the non-empty directory, and the spec's limits say so.
## Setup
`npm ci` completed (exit 0; 373 top-level entries). `/usr/bin/time -l npm run
build` passed with 3 tasks successful in 7.60 s elapsed (14.81 s user, 2.69 s
sys, 3013410816 bytes); `/usr/bin/time -l npm run test:prepare` passed with 6
tasks successful, 3 cached, in 1.63 s (3.47 s user, 0.81 s sys, 400752640
bytes).
## Static gates
Every gate ran on the final tree after the last source edit, sequentially:
`npm run check:fast` (typecheck and lint with module boundaries; 2 tasks
successful; 5.28 s elapsed, 23.22 s user, 2.93 s sys, 4564680704 bytes);
`npm run format` rewrote nothing outside this increment's files ("Finished in
635ms on 4077 files"), and `npm run format:check` passed ("All matched files
use the correct format"; 0.87 s, 4.30 s user, 0.64 s sys, 224051200 bytes);
`npx knip` reported no findings (3.49 s, 5.04 s user, 0.72 s sys, 805191680
bytes); `npm run verify:test-discovery` reported "Discovered all 1597 test
files exactly once" (0.55 s, 0.38 s user, 0.14 s sys, 141492224 bytes);
`npm run check:ci:tasks` (typecheck, lint:built, format:check, knip,
metadata:check, jscpd, scan:todos) passed with 8 tasks successful, lint "3764
files, 0 errors, 1690 warnings" and jscpd "3171 files, 2587 clones, 3.34%
duplicated lines" under the 3.5% threshold (4.89 s elapsed, 15.19 s user,
3.86 s sys, 874627072 bytes); `npm run docs:check` passed including the README
consistency test (6 tasks, 5 tests; 4.00 s elapsed, 3.86 s user, 0.94 s sys,
290111488 bytes). `actionlint 1.7.7` (`-shellcheck= -pyflakes=`, from the
review's scratch virtual environment) reported no findings on
`.github/workflows/real-agentenv.yml` and `.github/workflows/ci.yml`. A
case-insensitive grep for the forbidden words and marker comments over the 23
new or modified files matched only the `scan:todos` script name in
`package.json` and this file.
## Test projects
Source group: `/usr/bin/time -l npx vitest run --project services --project
conformance` passed 122 files, 1524 tests in 11.08 s elapsed, 23.10 s user,
2.24 s sys, 1631240192 bytes. The increment's files are
`environmentBundle.test.ts` (7 tests: the planned file set and copy targets,
the registry Dockerfile pinned to `PACKAGE_METADATA.version` with the
readiness-probe layer, the tarball Dockerfile installing and removing
`/tmp/rea-agents.tgz`, the verifier text naming `get_annotations` as the
first parameterless `GET` tool with recorded status 200 of record 25, the
smoke task, the README's provenance, `agent-env run .` block and rights note,
the name override and six refused names), `environmentExport.test.ts` (6
tests: the reader returning each file's bytes and parsed value, its refusals
of inline JSON, a directory and malformed JSON by role, writing into an absent
directory with the read bytes copied unchanged and reported sizes, the
tarball copy, the refusals of a non-empty directory, a file path and a missing
tarball with nothing written, and an existing empty directory accepted),
`environmentSource.test.ts` (4 tests; the loader takes the reporting
operation) and the conformance test `environmentBundlePackagePin.test.ts` (1
test: the registry install line ends with `rea-agents@<package.json version>`
and never uses `latest` or a range).
Built group after `npm run test:prepare`: `/usr/bin/time -l npx vitest run
--project cli-boundary --project boundary` over `environmentExportCli` (3),
`ciChangeScope` (228), `ciRequiredLanes` (17), `workflowActionPinning` (5),
`ciCachePolicy` (6), `cliToolCoverage` (1), `cliStartupImports` (5) and
`ciTestProjects` (11) passed 8 files, 276 tests in 432.80 s elapsed, 303.47 s
user, 92.63 s sys, 422412288 bytes; `tests/boundary/filesystem/productCatalog`
passed separately (10 tests, 5.32 s). The cli-boundary file writes the folder
from the fixture pair through the built CLI and checks the seven written
paths, the byte-exact copies and the Dockerfile's first line and `CMD`;
refuses a non-empty directory leaving its one file in place; and refuses a
mismatched pair without creating the directory.
## Local end-to-end run
With the built CLI in this worktree, from a fresh scratch directory:
`inspect-web-network-capture grafana-like.har har --format json --json` wrote
capture Evidence `ev_4ee4759b…` (28 records); `inspect-analysis-view` with the
inline source and all three template rules wrote manifest Evidence
`ev_6553a8e5…` naming that parent, `grafana-example`, 19 tools, view digest
`8d1eb3ee…`. `npm pack --ignore-scripts` of the checkout produced
`rea-agents-6.6.0.tgz` (6039238 bytes). `environment-export manifest.json
--evidence capture.json <tmp>/grafana-example --package-tarball <tgz> --json`
exited 0 and printed `status: exported`, `tool_count: 19`, `package_source:
{kind: tarball}` and eight files: `README.md` (2076 bytes),
`envs/grafana-example/env.toml` (37), `envs/grafana-example/Dockerfile` (441),
`artifacts/check_grafana-example/verify.py` (1534), `tasks/smoke.json` (291),
`envs/grafana-example/manifest.json` (15701),
`envs/grafana-example/evidence.json` (58296) and
`envs/grafana-example/rea-agents.tgz` (6039238); `cmp` confirmed the two
Evidence copies and the tarball byte-identical to the inputs. The Dockerfile's
install line reads `RUN npm install -g --ignore-scripts --no-fund --no-audit
/tmp/rea-agents.tgz && rm /tmp/rea-agents.tgz`, and the README's run section
is the `agent-env run .` block.
`/usr/bin/time -l agent-env run <tmp>/grafana-example` exited 0 in 43.66 s
elapsed (5.19 s user, 3.26 s sys, 129318912 bytes), output
```text
[tasks/smoke.json] step 1/2 env done in 25.1s
[tasks/smoke.json] step 2/2 replay (env_outcome_verifier)
replay: listed 19 tools, expected 19; get_annotations replayed status 200, recorded 200
[tasks/smoke.json] passed in 25.1s
Tasks:
tasks/smoke.json v1: passed (replay: 1), 25.1s, instance @local/…/grafana-example/smoke-nwvvojs7
Tore down 1 sandbox.
```
`docker ps -aq` before and after the run listed the same three pre-existing
containers (a Grafana container, an exited container and the framework's
registry from earlier sessions, unrelated to this run); no container was
added, and the image count rose from 19 to 20 for the built env image
`5a5b3bf62aae`. `docker run --rm --entrypoint sh 5a5b3bf62aae -c 'ls -la
/tmp; rea --version; id -un'` listed only `node-compile-cache` in `/tmp` (no
`rea-agents.tgz`), printed `6.6.0` and ran as `node`.
`REA_AGENT_ENV_COMMAND=<venv>/bin/agent-env REA_DOCKER_COMMAND=$(command -v
docker) /usr/bin/time -l node scripts/verify-agentenv-environment.mjs` exited
0 in 37.24 s elapsed (10.42 s user, 4.45 s sys, 268533760 bytes) and printed
the receipt `status: passed`, `public_cases: 5`, `upstream: agentenv-framework
0.9.1334`, `runner: darwin arm64; host Docker`, `docker_before: {containers:
3, images: 20}`, `agent_env_run: {exit_code: 0, seconds: 32}` with the same
passed summary in its stdout tail, `docker_after: {containers: 3, images: 21,
new_containers: []}` and `process_lineage.status: verified` with no
descendants. The first hosted run of the lane, on a runner with no prior
framework state, created the framework's image-store helper `agentenv-registry`
(`registry:2`, container `b2e047f4c6cd`) during `agent-env run`; the run itself
passed (`exit_code: 0`, 354 s, `tasks/smoke.json v1: passed`, "Tore down 1
sandbox.") but the first form of the leak check counted the helper and failed.
The check now lists containers with their names, excludes
`agentenv-registry[-<port>]` and reports it under `image_store_helpers`; the
local receipt gained `image_store_helpers: []` because the helper already
existed before the run here. Public ECR's anonymous pull quota refused the
framework's `postgres:16-alpine` pull with `429 Too Many Requests, Data limit
exceeded` on two hosted runs out of six (the second and, after the stack was
rebuilt, the sixth); the verifier now retries the run once, after 90 seconds,
when the failure carries that registry's signature, and records
`attempts: 2` with `retried_for` in the receipt. The local receipt reports
`attempts: 1`. Removing that helper (`docker rm -f
agentenv-registry`) and running the verifier again reproduced the fresh-host
path locally: the run recreated it and the receipt passed with
`image_store_helpers: ["agentenv-registry"]`, `new_containers: []`
(`agent_env_run: {exit_code: 0, seconds: 33}`). Without `REA_DOCKER_COMMAND` the verifier exited 1 before
touching anything with "verify:agentenv:environment requires absolute
REA_DOCKER_COMMAND; see docs/testing.md. No dependencies are installed by this
verifier."; with a relative `REA_AGENT_ENV_COMMAND=agent-env` it exited 1 with
the same sentence naming that variable.
Refusals through the built CLI: exporting into the already written bundle
directory exited 1 with `invalid_request`, issue path `["directory"]` and the
message "is not empty (4 entries); choose an absent or empty directory";
exporting the manifest against the capture of one selected record
(`--record 0`, `ev_3249d233…`) exited 1 with `invalid_request`, issue path
`["evidence", "evidence_id"]` and "The manifest was projected from a
different capture than the supplied evidence file.", creating no directory;
a truncated `broken.json` as the evidence exited 1 with `invalid_request`,
issue path `["evidence"]`, reason `invalid_format` and "broken.json is not
valid JSON: Unexpected end of JSON input", creating no directory. An export
without `--package-tarball` wrote a Dockerfile whose install line is
`RUN npm install -g --ignore-scripts --no-fund --no-audit rea-agents@6.6.0`,
the `package.json` version, with no tarball beside it; the tarball variant
copies `rea-agents.tgz` and installs and removes `/tmp/rea-agents.tgz`.
## Independent review
The adversarial review of the first pass is the independent review of this
increment; its findings and their repairs are listed above. One further
observation surfaced while repairing them: the single-read helper routes the
export's input refusals through the export module rather than the CLI's
shared JSON-input parser, so the inline-JSON refusal is now a typed
`invalid_request` on the `manifest` or `evidence` issue path instead of the
parser's `input_path`/`input_reason` envelope; the cli-boundary tests did not
depend on that envelope.
## Scope and measurement limits
The framework readiness probe, the port variable default and the `env.toml`
name were found by running the bundle in the first pass, not by reading a
published contract; they are recorded in the spec as the three additions to
the designed file set. The local run and the verifier used the host's Docker
with the framework's gateway and service-database images already built from
earlier sessions, so the "first run also builds the infrastructure" path was
not timed here. The verifier's container check compares `docker ps -aq`
before and after; images built by the run remain by design and are only
counted. `npm pack --json` has the npm 12 object shape on this host and the
npm 11 array shape on the hosted runner; the verifier accepts both but only
the former was exercised locally. The hosted `real-agentenv` workflow was not
dispatched from this tree. The built projects ran on this host's Node 22.23.1
rather than the pinned 24.18.0. The `/usr/bin/time -l` figures account for
each command and the children it waited for; Docker's own work runs in the
daemon and is outside them. Windows was not run.
## Linux followup verification (2026-10-19)
The original PR was updated from main after #4955 and #4975 merged. The
followups retain the author's commits and portable-name checks, seal private
JSON parser output once for shared immutable authentication/replay, reserve
sealing work before reading, preflight the served catalog before exporting,
translate changed-file failures by input role, defer export imports during CLI
registration, and verify the supplied framework executable before attributing
its results. The default `rea mcp` transport remains stdio.
Executed on Linux x64 with Node 24.18.0, npm 11.16.0, Docker 20.10.24,
Python 3.12.13 and an isolated `agentenv-framework==0.9.1334` environment:
- `turbo run typecheck lint:built format:check docs:check:built knip metadata:check artifacts:skills --concurrency=1`: ten tasks passed, one cached, 289.315 s elapsed, 284.552 s CPU, 4450.18 MiB peak process-family RSS.
- The focused source/compiled CLI/SDK/lifecycle/configuration run passed 399 tests in 24 files. A later run passed the updated 231 CI-selection cases, three executable-identity cases and ten product-catalog cases. The latter needed its generated catalog first; its initial missing-file failure was preparation, not a passing check.
- Four previously recorded, unauthenticated real GitHub API responses were exported with the checkout tarball. The generated Dockerfile built unchanged. A fresh non-root container replayed every response twice through the official MCP SDK, matching body, status, Evidence ordinal/id and untrusted-content provenance. Discovery/card parity and tarball removal passed. The standalone test supplies `ENVIRONMENT_NAME` as the framework does. Runtime verification with the built image took 12.393 s / 6.002 s CPU / 313.11 MiB process-family RSS; image-build cost is excluded. A Docker stats sample was 250.5 MiB, not a measured container peak.
- The production `verify-agentenv-environment.mjs` observed `agent-env 0.9.1334`, exported its 28-record source-owned Grafana-shaped fixture, deployed it with the real framework and passed `tasks/smoke.json`. The receipt reported five public cases, one sandbox torn down, no new task containers and no supervised descendants. This successful run used already prepared infrastructure: 141.697 s / 101.971 s CPU / 501.61 MiB process-family RSS. Earlier attempts failed because this host's proxy environment required optional SOCKS support and its default home sandbox directory was unwritable. Only the test process's proxy variables were cleared; supported `XDG_STATE_HOME` and `AGENT_ENV_LOCAL_SANDBOX_DIR` pointed into temporary storage. The shared Docker daemon was not reconfigured or restarted. The framework's persistent registry helper and images remain as its documented behavior.
A matched public `environment-serve`/SDK task compared the pre-followup serve
build with the final implementation. Both used the same GitHub capture with
1,000 synthetic HAR-extension items (each containing additional containers),
one first call and twenty warm identical replays. Fixture generation was
excluded. This is controlled stress data, not newly observed application data.
Larger 25,000/75,000-item projection attempts returned the existing typed
representation-budget refusal; that budget was not relaxed.
| Measurement | Before | After |
| ----------------------- | ----------: | ----------: |
| Cold listener startup | 2189.064 ms | 2862.860 ms |
| First call | 76.950 ms | 45.265 ms |
| Twenty warm calls | 324.119 ms | 267.132 ms |
| Completed task elapsed | 3.229 s | 3.885 s |
| Completed task CPU | 3.196 s | 3.827 s |
| Peak process-family RSS | 466.43 MiB | 470.21 MiB |
These single completed samples do not establish an overall speed or memory
improvement. Separate identity regressions establish that large reported JSON
trees are shared rather than copied and that caller-owned mutable trees are
not frozen. Token usage was not measured. CPU is child user+system time;
process-family memory sums sampled descendant RSS every 50 ms and may count
shared pages twice. Docker daemon/container CPU and peaks are outside that
process-family measurement and remain unmeasured. Builds used one task at a
time, one CPU and a soft 3 GiB Go limit; Docker builds were serialized and
limited to one CPU/4 GiB, and the standalone replay container to one CPU/2 GiB.
Windows execution and the published registry package were not tested in this
followup; the checkout tarball proves the code before its release.
### Output ownership and final review followups
The output boundary now uses the existing `SafeOutputTree` owner instead of
separate directory admission and pathname writes. It checks the admitted root,
parents, file identities and complete entry inventory around publication, keeps
failed-close authority, and preserves an existing empty caller root on rollback.
The optional package is held as one regular-file descriptor before output
writes, streamed with hash/readback verification, and checked for changes before
release. POSIX file modes are set and verified as `0600` independently of umask;
newly owned directories are `0700`. Existing root permissions remain caller owned.
Windows privacy depends on the selected destination ACL; no owner-only Windows
ACL guarantee or Windows runtime validation is claimed. Portable pathname
operations still require a trusted destination and parents against concurrent
replacement.
A compiled CLI counterexample under umask `0400` failed before the mode fix and
succeeded afterward with every generated file readable at `0600` and exact
Evidence bytes. Public CLI coverage also verifies that `symlink/..` retains its
filesystem meaning for the destination and package path. Real-filesystem tests
exercise destination replacement, foreign entries, parent symlinks, read-only
permissions and admitted-tarball replacement. Controlled close failures exercise
post-publication recovery and persistent retained ownership.
The inventory owner accepts canonically equivalent Unicode directory listings
without collapsing distinct filenames: an NFC multiset comparison is followed
by the original path identity checks. Tests simulate decomposed `readdir`
spelling over a real owned file and create an extra distinct Linux decomposed
foreign file. These establish the boundary behavior, not actual HFS+ execution.
Manifest, Evidence and tarball descriptors use the shared resource scope's close
retry. Persistent failures retain the canonical cleanup lease and produce a
tagged `environment-export` error. The compiled JSON CLI regression injects a
persistent manifest close failure before any destination write.
The framework verifier reuses `execNpm` and honors selected `npm_execpath`.
Four process-boundary attribution cases pass, including a conflicting PATH npm.
Those controlled executables verify attribution only.
After merging main `b4938aed5`, the generated Dockerfile built unchanged with the
checkout package and replayed all four captured public GitHub API responses
twice through the official MCP SDK in a fresh non-root container. Input bytes,
status/body/Evidence/provenance, discovery/card parity and package removal passed.
Warm base-image build plus pack/export/runtime verification: **40.699 s elapsed,
8.274 s process CPU, 421.04 MiB peak process-family RSS**. The real pinned
`agent-env 0.9.1334` verifier then passed all five public cases and the smoke task,
tore down its sandbox, and reported no new task containers or supervised
descendants: **156.895 s / 102.871 s CPU / 500.34 MiB**. Framework infrastructure
was already prepared. The later Unicode, close-failure and npm-selection repairs
have separate boundary regressions; they do not establish new real-platform
coverage.
A matched export comparison before the main merge used the same manifest
(6,416 bytes), capture (98,519 bytes) and checkout tarball (6,221,957 bytes), with
all copied inputs byte-exact. Before/after the output-owner repair: **1.827/2.604
s elapsed, 1.807/2.545 s CPU, 316.43/334.11 MiB** peak process-family RSS. These are
single process samples with uncontrolled host filesystem cache; the additional
ownership checks increased measured cost. They do not establish a speed or
memory improvement.
All followup heavy work uses one CPU and one test/build task at a time. Docker
builds are limited to one CPU/4 GiB, standalone runtime containers one CPU/2 GiB.
Process-family RSS is sampled every 50 ms and may double-count shared pages.
Docker daemon/container CPU and peak memory, agent tokens and fresh-framework
infrastructure cost are unmeasured. The previously documented early catalog
heap refusal is not represented as a passing run.
Final focused verification on the reviewed source passed **452 tests in 33 files** (including 232 CI-selection cases and the compiled CLI regressions): **161.276 s elapsed / 159.900 s CPU / 1242.43 MiB** peak process-family RSS. The final typecheck/build/lint gate passed: **218.427 s / 218.130 s CPU / 4449.45 MiB**.
@@ -1,21 +0,0 @@
# Plan
1. Add the `request` action to the scenario schema: methods, path, query,
headers with page value sources, JSON body and expected statuses; validate
the origin and the body against the start URL; include query and header
secrets in the declared-secret check.
2. Add `PlaywrightScenarioRequest.ts`: check the page's origin, build the URL,
resolve header values (admitting values read from the page to the scenario's
redaction), fetch in the page with a timeout and read the whole response,
then check the status. Dispatch it from the action runner with the start
origin, and add the limitation when a scenario has a request step.
3. Add a real-browser lane, `verify:browser:request`: a fixture item API that
requires a CSRF cookie header and a stored bearer token for writes, a write
session recorded through the CLI, the build's served writes, and a failing
expected status.
4. Add the `export_environment_bundle` contract, effects, CLI alias, catalog
family and handler: check the destination as other MCP output tools do,
resolve the capture bytes, and call the build with an exclusive destination.
5. Write the skill reference, route it from SKILL.md and install it with setup.
6. Document the request step, the MCP tool and recording writes.
7. Tests: request step unit tests, the MCP tool boundary, setup's skill files.
@@ -1,83 +0,0 @@
# Build an environment from a prompt
## Outcome
`rea environment-build` builds a bundle from one capture, but an agent asked to
"make an environment of this app" still cannot finish the job through REA's MCP
server. A browser scenario can only reach an application's API through the UI or
a `goto` GET, so recording the writes an environment serves means scripting every
form, and there is no MCP tool that writes a bundle. Nothing tells the agent how
to record a session the state can learn writes from, or when to stop recording.
A `request` scenario action sends one same-origin request through the page's own
`fetch`, so a scenario can sign in through the UI and then call the application's
API, writes included, with the session's cookies and the CSRF or bearer values
the application's own requests send. An `export_environment_bundle` MCP tool
builds the bundle from capture Evidence, as `environment-build` does. A skill
reference walks an agent from the prompt to a bundle: map, record, check
coverage, re-record by reason, export and hand off.
## Requirements
- A `request` step names a method (`GET`, `HEAD`, `POST`, `PUT`, `PATCH`,
`DELETE`), a path on the start URL's origin, ordered query entries, headers,
an optional JSON body and optional expected statuses. Validation refuses a
path that resolves to another origin, a body on `GET` or `HEAD`, a 3xx
expected status, header names a page's `fetch` cannot set or Chrome drops
(`User-Agent`), a header name given twice, line breaks or control characters
in literal values and prefixes, and a path the URL parser rejects, as a field
issue at the step's path.
- Header values are literals, declared secrets, a cookie the browser holds for
the request URL, or a local storage value on the start origin, optionally read
at a JSON pointer, with an optional prefix; local storage values are read only
while the page is on the start origin. Values read from the page are redacted
like declared secrets from records made after they are read, as stored and as
sent; a value read again keeps its first marker, a colliding label never
unredacts an earlier value, and values shorter than 8 characters are not
redacted.
- The request runs through the page's `fetch` with same-origin credentials, from
a page on the start origin (checked again in the page as it is sent), follows
no redirects, and completes when the response has been read to its end,
without keeping its body. A redirect, a status outside `expected_status`, a
network error or the step timeout fails the step; later steps are cancelled as
for other actions. The page sends only before the step's deadline, which it
receives as an absolute time, and within one second of being handed the
request; a busy page that starts later sends nothing, and the step hands the
request over again while it is neither cancelled nor out of time. A step
cancelled or out of time before the page starts its request sends nothing,
except a request the page starts within that second of being handed it. A
browser whose clock runs ahead of the host's fails the step. Its network
events are attributed to the step.
- Captures with request steps say so in a limitation. A scenario without one
validates, runs and records exactly as before.
- `export_environment_bundle` takes retained capture Evidence or a capture
Evidence file, an absolute output directory that does not exist and whose
parent does, and the build's name, template rules, package tarball and dry
run. It writes the bundle `environment-build` writes from the same Evidence
bytes (retained Evidence serialized as `--format json` writes it) and returns
the same report, validated by its output schema. It refuses an existing
directory, empty or not, a parentless or relative one, unknown Evidence, an
unnamed loopback capture and repeated rules, and writes nothing when it
refuses. Retained Evidence is refused for heap headroom before it is
serialized, as an Evidence file is before it is read. `environment-build` is
its CLI command.
- The skill reference `references/environments.md` is installed with the skill
and routed from SKILL.md. It covers disposable instances only, credentials
from environment variables, the recording rules the state needs, coverage, the
stop rule, the hand-off, and how to reach objects by id when the server
assigns ids: ids the caller chooses, a second scenario, or the UI.
- Coverage of a capture whose records are not all timed, which includes every
browser scenario capture, says the state learns no write clock.
- Stop rule: re-record a withheld write at most twice for a recording gap
(`no-state-target`, `no-observation`, `unconfirmed`, `incomplete-entities`),
once for `unexplained-change` and `no-call`, and stop at once for application
behaviour (`side-effect`, `contradicted`, `body-unusable`).
## Non-goals
- No cross-origin requests, form or multipart bodies, or arbitrary script
actions.
- No retroactive redaction of values a request step reads: a login response
recorded before the step keeps the token it returned, as captures do today.
- No application start, seed or reset, and no publishing of bundles.
- No change to what any view derives or any environment serves.
@@ -1,11 +0,0 @@
# Tasks
- [x] Record the outcome, requirements and non-goals.
- [x] Add the request action, its validation and its Playwright runner.
- [x] Add the real-browser request lane.
- [x] Add the export_environment_bundle tool.
- [x] Write and install the skill reference.
- [x] Document the request step, the tool and recording writes.
- [x] Run static, formatting, documentation and test gates, and the existing browser lanes.
- [x] Build environments from prompts with an agent against live applications on Linux VMs.
- [x] Address the two independent reviews.
@@ -1,82 +0,0 @@
# Verification
Executed on macOS with Node v24.22.1 at `feat/environment-prompt` 8dfd5a4d (stacked on the environment-build branch at
eeab0bda), and on Ubuntu 24.04 VMs for the end-to-end runs.
## Gates
- `npm run -s typecheck`, `lint`, `format:check`, `docs:check`, `mcp-catalog:check`, `verify:test-discovery` and
`npx knip`: passed.
- `npx vitest run --project domain --project services --project adapters`: 16,347 passed and 1 failed,
"stops Inspector target authorization after the current stat settles", which fails the same way on the base fce1aba8
in this environment (16,326 passed, 2 failed there); none is new.
- Boundaries: the bundle tool, analysis view, tool schema validity, environment-build CLI, setup skill and client
lifecycle suites (123 passed), and every browser and scenario MCP and CLI boundary suite (68 passed).
- Real Chrome: `verify:browser:request` (new: 22 request steps, the CSRF cookie and stored token authenticate seven
writes and never reach the Evidence, two queued writes are refused, the build serves the three write tools, an unexpected status fails the step and
cancels the rest, and a redirect to another origin is not followed, the other origin receiving nothing) and
`verify:browser:network` passed. `verify:browser` stops at "Real Chrome stable capture identities did not
reconcile", an `inspect_web_page` comparison this change does not touch, and fails the same way on the base.
- `verify:browser:request` runs each CLI call under the shared package verifier command owner, which stops the CLI and
the browser it launched on timeout, output overflow or failure before the lane's private root is removed, and reports
a failed stop with the root retained; `browserRequestVerifierOwnership.test.ts` proves a still-running CLI's
separately grouped browser is stopped before the root goes.
Scenarios without request steps are unchanged: the action union gains a member, the secrets refactor compiles the same
patterns, the request-step limitation appears only with request steps, and the browser suites and the network lane pass.
## End to end: environments from a prompt
Five self-hosted applications were brought up fresh and seeded on four disposable VMs, loopback only. Claude Code 2.1.310
(`claude-sonnet-5-5` through a LiteLLM proxy) got this branch's packed CLI, registered with `rea setup --client
claude_code` (the MCP server and the skill), and one prompt per application: build an agent environment of the app at
this URL, cover these entities, the instance is disposable but leave the seeded data as found, sign in as this user, the
password is in `APP_PASSWORD`, Chromium is here, write the bundle there. The prompt did not mention the skill. The agent
could use the REA tools, the skill and file tools; Bash and web tools were disabled.
Each bundle was then rebuilt with `environment-build` from its own `evidence.json` and this branch's tarball (the
registry's `rea-agents@6.7.0` has no `environment-serve`); `manifest.json` and `evidence.json` were byte-identical to
the agent's in all five. It ran its smoke task, a retrieval eval generated from its manifest and capture, and the
application's recorded write eval with `fireworks_ai/gpt-oss-120b` and `fireworks_ai/glm-5p3-flash`, one run per task.
| App | Agent run | Recordings | Records | Tools (state / replayed reads) | Served writes | Smoke | Retrieval gpt-oss / GLM | Writes gpt-oss / GLM |
| -------- | --------- | ---------- | ------- | ------------------------------ | ------------- | ------ | ----------------------- | -------------------- |
| Linkding | 182 s | 9 | 66 | 8 (7 / 1) | 0 | passed | 9/9 / 8/9 | 0/3 / 0/3 |
| Grocy | 253 s | 7 | 154 | 22 (16 / 0) | 6 | passed | 10/11 / 10/11 | 3/3 / 3/3 |
| Homebox | 391 s | 9 | 268 | 13 (11 / 2) | 0 | passed | 9/9 / 9/9 | 0/2 / 0/2 |
| Directus | 202 s | 7 | 100 | 25 (16 / 4) | 5 | passed | 12/12 / 11/12 | 2/2 / 2/2 \* |
| Grafana | 143 s | 4 | 100 | 15 (12 / 2) | 1 | passed | 5/5 / 5/5 | 2/2 / 2/2 |
\* The Directus write eval checks that the state holds exactly the provisions the scripted recording read (2); the
agent's recording read all 5, so its count checks fail although every field check passes (0/2 with both models). With
the counts relative to the state's own provisions it passes 2/2 with both.
- Write tasks passed exactly when the build served their tool, with both models.
- The skill loaded unprompted in every run. All five agents signed in through the form with the declared secret,
recorded the API with request steps, checked coverage, stopped by the withheld reasons and exported with
`export_environment_bundle`; each reported the credential-named warning pointers, and none published anything.
- The scripted recordings the published environments were built from, built with this branch, read more (11, 39, 21,
31 and 35 state-backed reads) and serve 7, 3, 2, 2 and 0 writes; the prompted recordings serve 0, 6, 0, 5 and 1.
- Linkding's and Homebox's updates are withheld because a browser scenario carries no request times: the state learns
no clock, so an update the application stamps with a modification time is `unexplained-change`. Linkding's scripted
HAR serves the same PATCH with a clock rule. The coverage view now says so; recording request times on scenario
network events would lift it. Linkding derives each bookmark's archive URL from its creation time, so its create is
`contradicted` in both recordings.
Earlier rounds: in the first, two agents hung on steps without `timeout_ms` and most guessed the scenario schema, so the
reference now starts from a whole scenario with a timeout on every step; the second (same five apps, before the review
fixes) served 1, 6, 0, 5 and 0 writes with the same eval pattern.
## Review
Two independent reviews tried to refute the change.
- The first found a 302 that took a request step to another origin, page values left unredacted under a repeated or
colliding header label, short page values that rewrote ids and hosts across the capture, `User-Agent` accepted but
dropped by Chrome, a request that could still be sent after its step timed out, an origin check separated from the
send, a literal query re-encoded, line breaks accepted in header values, and CLI wording in MCP refusals. All are
fixed and tested; redirects are now checked in real Chrome.
- The second confirmed those fixes and found query entries mishandled after a path ending in `?` or `#`, 3xx expected
statuses that can never match, and padded stored values escaping redaction (fixed), plus the body cost of reading a
page value, short values kept in plain text and the MCP dry run checking its directory (documented). In the
prompted captures, only static assets lost bodies to the size limits.
@@ -1,36 +0,0 @@
# Implementation plan
1. Add `src/application/environment/environmentSource.ts` to authenticate the
two Evidence files, require the manifest view kind and the capture
operation, refuse a parent mismatch, and reduce every cited record to its
request line, status, content type and retained response text through the
slice-1 request-line reader, so the server holds only what replay returns.
2. Add `environmentTools.ts` to map manifest tools to MCP tool definitions with
one hand-built JSON Schema per tool that both `registerTool` (through the
SDK's `fromJsonSchema`) and the card consume, and to build the card in the
echo example's key order.
3. Add `environmentReplay.ts` to score cited records by path-segment matches,
then query matches, keep manifest order on ties, and shape the replay result
with JSON-like parsing, UTF-8-safe truncation and the replay provenance
block; export the slice-1 JSON-like predicate instead of restating it.
4. Add `src/server/environment/serveEnvironment.ts` to build the `McpServer`
whose handlers attach REA's target-content `_meta`, the card and `/agentenv`
routes (the latter reading its body through the SDK's bounded reader), and
to serve them through the slice-2 `serveStreamableHttp` with its `routes`
and `onerror` seams; add `src/config/environmentName.ts` for
`ENVIRONMENT_NAME`.
5. Add `src/cli/environmentCommands.ts` registering `environment-serve` through
`withCommandCancellation` and `logCliCommand`, resolving host and port with
the slice-2 endpoint parser, reading files through `parseCliJsonInput`,
importing the listener lazily, awaiting the cancellation signal or a
listener failure and returning one `stopped` document or a typed error;
register the name in `CLI_COMMANDS` and the lazy module in the startup
import probe.
6. Share the fixture pair through `tests/fixtures/environmentServe.ts` and the
listener spawn through a generalised `startListeningProcess`; add services,
adapters, mcp-boundary, cli-boundary and process-boundary tests.
7. Document the command in `docs/getting-started/cli.md`, add `docs/agent-environments.md` with
its sidebar and index entries, and record the spec.
No new dependency is introduced. REA's tool contracts, catalog digests and the
stdio transport are unchanged; the CLI inventory gains one command.
@@ -1,139 +0,0 @@
# Serve an environment manifest as a replay environment
This specification records an implementation increment and its original problem
statement. For current behavior and limitations, see the
[current guide](../../../agent-environments.md).
Issue: https://github.com/morluto/rea/issues/4933
## Outcome
`rea environment-serve <manifest.json> --evidence <capture.json> [--host H]
[--port N]` serves an environment manifest, projected by `inspect-analysis-view`
from retained HAR capture Evidence, as an agent environment: an MCP server at
`/mcp` with one tool per manifest tool that replays the retained records the
tool cites, the environment card at `/.well-known/agent-env.json` in the shape
the agentenv framework's echo example publishes, and a `/agentenv` data plane
that answers every JSON-RPC method as not found. Nothing is fetched from the
recorded application; every answer is retained Evidence marked as target
content. This increment adds the serve command only; exporting a bundle is a
later increment.
## Requirements
- Read both files as bounded JSON input, authenticate each as REA Evidence and
require `inspect_analysis_view` Evidence of kind `environment-manifest` and
complete `inspect_web_network_capture` Evidence; refuse any other pair with an
`invalid_request` whose issue path names the offending file.
- Forward caller cancellation to file reads and check startup boundaries before
authentication/listener work; an already observed abort must not bind or
announce a listener.
- Refuse a manifest whose `parent_evidence_id` differs from the evidence file's
`evidence_id` before binding any port; Evidence authentication covers the
capture's records, so no further record-coverage refusal is defined.
- Build an `McpServer` from the manifest alone: each tool's input schema lists
every path parameter as a required string described by its segment index,
rule and observed values, every observed query name as an optional string,
and an optional `body` object for `POST`, `PUT` and `PATCH` (a query name
that collides with a path parameter becomes `query_<name>`, a query name
longer than 64 characters becomes `query_<n>`, and the body
becomes `request_body` when a query parameter is named `body`), closed with
`additionalProperties: false` so unknown arguments are refused; the
description reads `METHOD template; replays retained records [ordinals];
evidence ev_…`. The served catalog stays separate from REA's own tool
contracts and digests.
- Prefix tool descriptions with the shared captured-catalog warning so
standalone card readers receive the trust notice before MCP initialization.
- Bound each path-observation, body-key and cited-ordinal description sample to 1 KiB
of UTF-8 whole values before joining them, with a separate omitted-count and
manifest-Evidence notice. Keep complete arrays and replay semantics unchanged.
- Bound captured method, path and query-name prose to UTF-8-safe display prefixes
under the same budget, with an explicit full-value Evidence notice. Preserve
complete lookup values; long path and query names use collision-safe aliases.
- Parse a recorded query only when supplied query arguments can affect selection.
- Replay by selecting, among the tool's cited records, the one whose path
segments at the parameter indexes match the most supplied values, then the
most of those segments equal to the value as written rather than only after
percent-decoding, then the most supplied query values, keeping manifest order
on ties; return `status`,
`content_type`, `body` (parsed JSON for JSON-like content types with safe numeric conversion,
else text; bodies over 256 KiB cut at a UTF-8 boundary with
`truncated: true`) and `replay` with `record_ordinal`, `evidence_id`,
`exact_match`, `recorded_path` and `recorded_query` (each cut to 1 KiB, with
`recorded_line_truncated`; an explicit empty query is `?`), `body_recorded` (false
when the capture kept no response body, so a `null` body is not mistaken for
a recorded one), `body_encoding` (`base64` when the retained bytes are not
UTF-8, so they are returned exactly rather than decoded lossily) and
`truncated` (a large retained base64 body is decoded only up to that limit),
as both
structured content and text, with REA's existing target-content provenance
marker in `_meta`.
- Serve the card with exactly the echo example's keys and nesting: `name`
(`ENVIRONMENT_NAME` from the environment snapshot, else the manifest name; a
set but blank value is refused as `configuration_invalid`),
`protocolVersion` `1.0`, `url` `/agentenv`, `preferredTransport` `JSONRPC`,
`additionalInterfaces` `[{url: /mcp, transport: mcp}]`, `capabilities` with
`extensions: null`, the tools and `operations: []`, and
`children_environments: null`. Read the `/agentenv` body within the SDK's
4 MiB bound and answer `413` with JSON-RPC `-32000` beyond it.
- Resolve host and port as `rea mcp --http` does (flags, `MCP_HOST`/`MCP_PORT`,
then `127.0.0.1` and port `0`), announce the bound URL as one pino JSON line
on stderr, serve through the shared streamable HTTP listener, and run until
SIGINT or SIGTERM only, then close, print one `stopped` document and exit
`130` or `143` through the shared command cancellation handler; a signal
during loading returns `cancelled` before binding; a listener
failure after binding is logged and ends the command with a
`resource_constraint` error and exit `1`.
- Register the flat `environment-serve` command in the CLI inventory with
described arguments and no MCP tool contract; keep the CLI wiring thin, the
mapping and replay in the application layer and the server assembly in the
server layer; load the listener lazily so the command catalog registers
without it.
## Acceptance and limits
Services tests cover source loading and each refusal, tool mapping and schema
derivation, the card shape, exact and best-effort selection, query matching,
tie order, text and non-parsing bodies, truncation at a UTF-8 boundary and
base64 content. Adapters tests byte-compare the served card with the echo card
shape carrying the fixture tools, drive `/agentenv` including a body over the
bound, and call tools over the SDK streamable HTTP client with provenance and
the unknown-argument refusal asserted. The mcp-boundary test
spawns the built CLI on a manifest and capture produced from the slice-1
Grafana-shaped fixture and asserts tool count, an exact `get_users_by_id`
replay with `body.login === "probe"`, an inexact replay, the card under
`ENVIRONMENT_NAME` and the data-plane refusal; the cli-boundary test covers
the mismatched-parent refusal, the missing `--evidence` usage error and an
unreadable path; the process-boundary test asserts a `143` exit with a
released port. Replay validates no supplied values, performs no network
activity and establishes no authorization, response semantics or state
transitions. One MCP client is served at a time, as the shared listener
defines. Non-loopback binds require `MCP_ALLOWED_HOSTS` and retain both Host
and Origin checks. Shared listener regressions exercise a wildcard bind,
configuration refusal, port release and admitted/foreign request headers;
the original environment-serving fixture runs below used loopback.
## Resource and cancellation boundaries
- Whole discovery admission reserves at most 1 MiB using six bytes per UTF-16
unit plus schema overhead before retaining each schema property. Aggregate
tools, arguments and selected environment identity participate; oversized
catalogs fail with a non-retryable capacity error before bind. The calibration
used 1500 query fields with eight concurrent discovery requests; compact wire
size can be smaller than the conservative reservation.
- Query matching scans selected names one field at a time; path scoring scans
once and retains only supplied parameter coordinates. Native form-decoding
semantics, malformed escape handling and complete captured facts are preserved.
- Content-type display is bounded to 1 KiB and reports `content_type_truncated`;
complete media-type semantics remain available to body interpretation.
- Cancellation also owns DNS/listen startup; an observed abort closes the
listener before its URL is announced.
## Deferred issue criteria
Exporting a manifest and its evidence as an agent-environment bundle with a
verifier, and the hosted verification lane, are later independent increments
of #4933. This PR must reference rather than close the whole issue.
Numeric data-plane IDs that lose value through JSON number conversion are invalid
requests with null response IDs, rather than silently changed correlation values.
@@ -1,12 +0,0 @@
# Tasks
- [x] Record the serve contract, requirements and deferred increments.
- [x] Load and cross-check the manifest and capture Evidence with typed refusals.
- [x] Map manifest tools to MCP input schemas and the environment card.
- [x] Select and shape replayed records with exact-match, truncation and provenance.
- [x] Assemble the MCP server, card and data-plane routes on the shared listener.
- [x] Register the flat CLI command with host, port and environment-name resolution.
- [x] Add services, adapters, mcp-boundary, cli-boundary and process-boundary coverage.
- [x] Document the command and the agent environment page; record the spec.
- [x] Run static, formatting, duplication, documentation and test gates and the
built-CLI exchange with the Python MCP client.
@@ -1,247 +0,0 @@
# Verification
Verified base: cf4cc6faab0fb2c444ca054db8b98cb981bae6c9 (fetched main).
The worktree carries the manifest-view and streamable-HTTP increments as
commits on that base; this increment's changes are uncommitted edits on top.
Every check below ran as written on this tree in the review-response pass;
nothing is reported that did not run. Timings are macOS `/usr/bin/time -l`
command accounting (elapsed, user, system seconds and maximum resident set
size of the command and the children it waited for).
## Review findings addressed
An adversarial review of the first pass found one should-fix and six nits;
each was repaired at its owning boundary before the gates below ran.
- `POST /agentenv` read its body with `request.json()` on the streamed
`node:http` body, so a 60 MB payload was buffered before the `-32700`
answer. The route now reads through the SDK's `readRequestBody` with
`DEFAULT_MAX_REQUEST_BODY_SIZE`, answering `413` with JSON-RPC `-32000`
(`id: null`) before parsing, and parses within the bound through the
domain's `safeParseJson`. The JSON-RPC error helper of the shared listener
is exported as `jsonRpcErrorResponse` and reused rather than restated.
- A set but blank `ENVIRONMENT_NAME` refuses with `configuration_invalid`,
as a blank `MCP_HOST` does in the sibling parser; `docs/getting-started/cli.md` and
`docs/agent-environments.md` now say so, and the spec records the
divergence from the design's `||` reading as deliberate.
- The record-coverage refusal in `loadEnvironmentSource` was unreachable for
authenticated pairs (the Evidence id is computed over `normalized_result`,
so a matching parent id implies identical records, each with a request
line by construction of the projector). The branch is gone: cited records
are indexed unconditionally, a record without a request line is left out
and the tool refuses at call time through the existing no-record path. The
claim was removed from `docs/agent-environments.md` and `spec.md`, and the
services test now asserts an empty manifest indexes nothing and a tampered
capture is refused by authentication.
- Every advertised input schema closes with `additionalProperties: false`,
so an unknown argument is refused as invalid arguments instead of silently
degrading to an omitted one. The agentenv framework's card consumers
(`verify_env_card.py`, the gateway's `tool.inputSchema` pass-through and
the spec-conformance normaliser) read `properties` and `required` only, so
the extra key does not disturb them; the guide names it as a key the echo
schema does not carry.
- The tool description now reads `METHOD template; replays retained records
[ordinals]; evidence ev_…`, as the design text specifies.
- `serveEnvironment` passes an `onerror` to the shared listener that logs
`{ error }` at `error` level and forwards to the caller; the command races
the cancellation signal against that failure and, on a listener failure
after binding, closes the listener and returns the same typed
`resource_constraint` error the bind failure returns (exit `1`) instead of
serving nothing. The two constructions share one `transportError` helper.
- `tests/boundary/cli/cliStartupImports.test.ts` lists
`dist/server/environment/serveEnvironment.js` as `environment-server` in
`DEFERRED_IMPORTS`, so the `--help` probe would fail if the serve command
ever imported the listener eagerly.
## Setup
`npm ci` exited 0 (540 packages added, 541 audited; 4.79 s elapsed, 3.46 s
user, 7.34 s sys, 880803840 bytes). After the edits above, `npm run build`
exited 0 (three turbo tasks; 4.61 s elapsed, 14.76 s user, 3.23 s sys,
3053060096 bytes) and `npm run test:prepare` exited 0 (six tasks; 1.28 s
elapsed, 2.94 s user, 0.67 s sys, 424935424 bytes), so every built-group run
and built-CLI check below used a `dist/` carrying the revised serve command.
## Static gates
Each exit 0 on the final tree: `npm run check:fast` (typecheck and lint,
2 tasks; 4.76 s elapsed, 23.36 s user, 2.56 s sys, 4458840064 bytes). `npm run
format` (4064 files; 0.93 s elapsed, 4.12 s user, 0.76 s sys, 226344960
bytes) then `npm run format:check` (all 4064 files formatted; 0.64 s elapsed,
4.19 s user, 0.66 s sys, 219906048 bytes). `npx knip` (no findings; 3.49 s
elapsed, 4.92 s user, 0.63 s sys, 871645184 bytes). `npm run check:ci:tasks`
(8 tasks successful, 2 served from the turbo cache; `lint:built` 3756 files,
0 errors; jscpd 3164 files, 2583 clones, 3.34% duplicated lines under the
3.5% threshold; the stray-marker scan; 7.16 s elapsed, 26.46 s user, 5.88 s
sys, 2939142144 bytes). `npm run verify:architecture-guards` passed across
1523 source files and `npm run verify:test-discovery` discovered all 1592
test files exactly once. `npm run docs:check` (six tasks plus the README
consistency test, 5 cases; 3.37 s elapsed, 3.49 s user, 0.84 s sys,
291618816 bytes). After the last edit of this record, `npm run format`,
`npm run format:check` and `npm run docs:check` were rerun (each exit 0) and
the same static set was rerun uncached as `npx turbo run typecheck lint:built
format:check knip metadata:check jscpd scan:todos --force` (8 tasks
successful, 0 cached, 3.34% duplication; 8.40 s elapsed, 48.82 s user, 7.77 s
sys, 4638474240 bytes). A case-insensitive grep for the forbidden words and
marker comments over all 28 new or modified files found nothing.
## Test projects
Source group on the final tree: `/usr/bin/time -l npx vitest run --project
services --project adapters` passed 343 files, 5196 tests with 8 skipped, in
99.55 s elapsed, 93.60 s user, 28.88 s sys, 1781055488 bytes. The increment's
files are `environmentSource.test.ts` (4 tests: pair authentication and
exchange indexing, parent mismatch as `invalid_request` with path
`["evidence","evidence_id"]`, other view kind, non-capture evidence and
non-Evidence JSON, an empty manifest indexing nothing with a tampered capture
refused by authentication), `environmentTools.test.ts` (5 tests: ordered
mapping and the `; evidence` description, required path parameters with rule,
observed values and `additionalProperties: false`, optional query strings
without a body for reads, a body object for writes, the card's key order),
`environmentReplay.test.ts` (7 tests, unchanged in this pass) and
`serveEnvironment.test.ts` (5 adapters tests: the card text byte-equal to the
echo card shape with the fixture tools, `/agentenv` answering `-32601` with
`-32700` for a malformed body, a route-level body of
`DEFAULT_MAX_REQUEST_BODY_SIZE` plus envelope answered `413` `-32000` with
`id: null`, a full listener driven by the SDK streamable HTTP client with
`_meta` equal to `TARGET_CONTENT_RESULT_META`, exact and inexact replays, an
argument-less call and an unknown argument both refused with `isError`, and
the `renamed` override with an oversized body answered `413` through
`node:http` and a released port).
Focused built group after `test:prepare`: `npx vitest run --project
cli-boundary --project mcp-boundary --project process-boundary --project
boundary` over `environmentServeCli`, `environmentServeMcp`,
`environmentServeShutdown`, `mcpHttpShutdown`, `streamableHttpMcp`,
`cliToolCoverage`, `cliStartupImports` (now carrying the `environment-server`
deferred import), `dispatcher`, `productCatalog`, `documentationFacts` and
`ciTestProjects` passed 11 files, 33 tests (16.38 s elapsed, 25.77 s user,
5.94 s sys, 941948928 bytes).
Full built-group projects ran one after another on the final `dist/` from a
background shell while the built-CLI exchange below ran in the foreground.
`/usr/bin/time -l npx vitest run --project mcp-boundary` passed 156 files
with 2 skipped, 914 tests with 7 skipped, in 166.23 s elapsed, 319.51 s user,
46.18 s sys, 4452171776 bytes. `/usr/bin/time -l npx vitest run --project
cli-boundary` exited 1: 109 files passed and 3 failed, 663 tests passed,
2 skipped and 7 failed, in 432.45 s elapsed, 725.28 s user, 213.32 s sys,
641597440 bytes. No failing file belongs to this increment.
`javascriptApplicationJsonOutput.test.ts` (4 cases) and
`javascriptApplicationProgress.test.ts` (2 cases) failed with the worker's
result-capacity constraint ("The parent's result capacity was exhausted
after retaining static facts for main.js"); rerun together on the idle host
after the chain they passed 2 files, 17 tests (17.05 s elapsed, 26.40 s user,
8.47 s sys, 282394624 bytes), the load classification the previous pass
recorded. `closedStdout.test.ts` "stops quietly when the reader closes during
streamed JSON" exits `1` instead of `141` with 1009 bytes received, alone as
well as in the project, the environmental failure the previous pass
reproduced on a clean clone (macOS, Node 22.23.1, npm 12.0.2).
`commandFinalizationCancellation.test.ts`, which the previous pass saw fail
on worker order, passed in this run.
`/usr/bin/time -l npx vitest run --project process-boundary` exited 1: 56
files passed, 2 skipped and 3 failed, 463 tests passed, 19 skipped and 5
failed, in 431.71 s elapsed, 148.34 s user, 114.81 s sys, 710000640 bytes.
`environmentServeShutdown.test.ts` and `mcpHttpShutdown.test.ts` passed inside
it. `jadxIntegration.test.ts` failed three cases at the 30 s test and 10 s
hook timeouts ("retires an idle engine", "completes large class inventories",
"close cancels active and queued work"), the lane the previous pass recorded
as moving between runs on this host. `releaseArtifactCanary.test.ts` fails
parsing `npm pack --json` ("expected tuple, received object"), the npm 12.0.2
shape the previous pass reproduced on a clean clone.
`processCaptureLifecycle.test.ts` "keeps the process deadline bounded when the
wall clock moves backward" failed with `expected false to be true` on
`result.ok`; rerun alone on the idle host it failed the same way with 23
passed (38.12 s elapsed, 9.84 s user, 18.07 s sys, 323076096 bytes). The file
and `src/process/` are untouched by this increment and the case mocks
`Date.now` around a real process capture with a 1.5 s fallback abort; it is
recorded as a host-dependent failure of that lane, not classified further
here.
## Built-CLI exchange on the prototype capture
`node scripts/rea.mjs inspect-web-network-capture grafana-like.har har
--format json` wrote capture Evidence `ev_4ee4759b…` with 28 records;
`inspect-analysis-view` with the inline source and all three template rules
wrote manifest Evidence `ev_6553a8e5…` naming that parent, `grafana-example`,
19 tools. `environment-serve manifest.json --evidence capture.json --port 0
--json < /dev/null` announced one stderr line
`{"transport":"streamable-http","url":"http://127.0.0.1:62305/mcp","msg":"MCP transport listening"}`
and nothing on stdout until shutdown.
`GET /.well-known/agent-env.json` returned a card whose top-level keys,
`capabilities` keys and tool keys equal the echo card's in order; its
`inputSchema` keys are `type`, `properties`, `required` and
`additionalProperties`, the echo card's three plus the closing key. Fixed
fields: `protocolVersion` `1.0`, `url` `/agentenv`, `preferredTransport`
`JSONRPC`, `additionalInterfaces` `[{url:/mcp,transport:mcp}]`, `extensions`
null, `operations` `[]`, `children_environments` null, 19 tools, with
`get_users_by_id` described as `GET /api/users/{numeric}; replays retained
records [5, 6]; evidence ev_4ee4759b…`.
The Python `mcp` 1.30.0 client (httpx 0.28.1) initialised against
`grafana-example 6.6.0` (protocol 2025-11-25), listed 19 tools, called
`get_users_by_id {"id":"2"}` and read `body.login == "probe"`,
`replay.exact_match == True`, `_meta.provenance.untrusted_content == True`
with `source == "analysis_target"`; `{"id":"999"}` gave `exact_match ==
False`; `get_folders_by_uid {"uid":"general"}` gave `recorded_path ==
"/api/folders/general"`; `get_search {"query":"probe","type":"dash-db"}`
returned a list body whose first title is `probe dashboard` with
`recorded_query == "?query=probe&type=dash-db"`; `get_users_by_id
{"id":"2","unknown":"x"}` returned `isError == True` with no structured
content.
`POST /agentenv {"jsonrpc":"2.0","id":1,"method":"data/reset"}` returned
`{"jsonrpc":"2.0","id":1,"error":{"code":-32601,"message":"method not found: data/reset"}}`.
A 60 MB non-JSON POST with a `Content-Length` header was answered `413`
`{"jsonrpc":"2.0","error":{"code":-32000,"message":"Request body must not exceed 4194304 bytes"},"id":null}`
after curl had sent 768332 bytes, in 1.4 ms, with the server's resident set
269024 KiB before and 269040 KiB after; the same file sent chunked without a
length was answered `413` after 5237311 bytes in 9.9 ms, resident set 267952
KiB before and 274208 KiB after, so the read stops at the bound on both
paths. A malformed body within the bound (`{`) was answered `400`
`{"jsonrpc":"2.0","error":{"code":-32700,"message":"parse error"},"id":null}`.
SIGTERM ended the process with status 143 after one stdout document
`{"status":"stopped","url":"http://127.0.0.1:62305/mcp","environment":"grafana-example","tools":19,"evidence_id":"ev_4ee4759b…","manifest_evidence_id":"ev_6553a8e5…"}`.
A restart with `ENVIRONMENT_NAME=renamed` served a card named `renamed`,
reported `"environment":"renamed"` in its stopped document and also exited 143. `ENVIRONMENT_NAME=` (set, blank) exited 1 before binding with
`{"code":"configuration_invalid","details":{"settings":[{"setting":"ENVIRONMENT_NAME",…}]}}`.
The manifest served against the capture of one selected record (`--record
0`, `ev_3249d233…`) was refused with exit 1 and
`{"code":"invalid_request","details":{"operation":"environment-serve","issues":[{"path":["evidence","evidence_id"],"reason":"invalid_value","expected":"ev_4ee4759b…",…}]}}`
whose message names both identifiers; omitting `--evidence` exited 1 with
Incur's `VALIDATION_ERROR` naming `evidence`. No `rea.mjs` process or
listener remained after these runs.
## Independent review
The adversarial review of the first pass is the independent review of this
increment; its findings and their repairs are listed above. One further
observation surfaced while repairing them: the byte-identical card assertion
in `serveEnvironment.test.ts` compares the `inputSchema` object exactly, so
closing the schema required extending that expectation as well as the
services tests, which is the intended coupling between the card and the
advertised MCP schema.
## Scope and measurement limits
The echo-card comparison is exact on keys, nesting and tool entries; the
property names inside `inputSchema.properties` necessarily differ from the
echo tool's single `text` property, and `inputSchema` carries one key the echo
schema does not. `exact_match` is defined over supplied values only; omitted
parameters cannot mismatch, and a call without arguments is exact on the
tool's first record. Request bodies on write tools are accepted and ignored.
The post-bind listener `error` path is wired and type-checked but not
provoked by a test, since the shared listener does not expose its
`node:http` server. These recorded runs predate the required non-loopback Host/Origin allowlist;
the Python exchange, curl checks and tests recorded here used `127.0.0.1`.
The current contract and later non-loopback coverage are described in the
[transport specification](../http-transport/spec.md).
Replay selection and body parsing were measured on the 28-record fixture
only; no large-capture timing was taken. Resident-set figures are `ps` samples
of the serving process before and after one request each. Token usage and
full process-family peak are unmeasured; the `/usr/bin/time -l` figures
account for each command and the children it waited for. Windows was not
run.
@@ -1,12 +0,0 @@
# Plan
1. Export the capture parser from `environmentSource.ts` so a probe loads like a capture.
2. `environmentCompareMatch.ts`: a probe request to a tool and its arguments.
3. `environmentCompareIds.ts`: the id map, natural-key pairing, learning from two answers, translating arguments.
4. `environmentCompareDiff.ts`: normalisation and categorised differences.
5. `environmentCompare.ts`: per probe, reset the state, answer each request, compare and learn; the report.
6. `rea environment-compare` in `src/cli/environmentCommands.ts`, documented in `docs/agent-environments.md` and
`docs/getting-started/cli.md`.
7. Tests: matching, pairing, normalisation and categories as unit tests; the command over a fixture capture and probes.
8. Verification on VMs: six applications brought up and seeded as for their capture, reset from a snapshot per sequence,
driven by a script that records each sequence as a HAR; baseline reports per environment.
@@ -1,98 +0,0 @@
# Compare an environment with the application it came from
Issue: https://github.com/morluto/rea/issues/4933
## Outcome
An environment is only as useful as it is faithful: an agent trained or graded on it should meet the behaviour of the
application it was captured from. REA checks an environment only against its own capture, so nothing says how far it
drifts from the application on calls the capture did not make, after writes, or on errors.
`rea environment-compare` measures that. It takes an environment (a manifest and its capture Evidence) and one or more
**probe captures**, each a recording of one call sequence made against the live application, and reports how many of the
probe's calls the environment answers as the application did, which tools disagree and how.
The command only reads Evidence: it makes no network call. Whoever records the probes drives the application with its own
credentials and resets it between sequences.
## Requirements
- Inputs: the manifest Evidence, its capture Evidence (`--evidence`), and one or more probe capture Evidence files
(`--probe`, repeatable), each `inspect-web-network-capture` or `capture-browser-scenario` Evidence of one sequence.
- Each probe is one sequence run against a freshly reset application. Before each probe the environment's state is reset,
so sequences are independent on both sides.
- Requests are taken in the probe's order (start time, then ordinal; ordinal alone when any record lacks a start
time, as state extraction orders them). A request is matched to the manifest tool of the
same method whose path template it fits with the most literal segments; format-rule parameters must fit their format
once percent-decoded, as replay reads them.
Query values the tool takes and a JSON body become the tool's arguments. A path argument is the raw segment: the
environment decodes it once, so a segment encoded twice is not read as a second decoding. Replay matches that raw
argument against a recorded segment that equals it, equals its one decoding, or decodes once to it.
- A record without a usable request line (a redacted URL, a transaction the capture cannot attribute, an unparseable
URL or no method) is not replayed, nor is a request to another origin than the probe's application (`other-origin`),
which is the origin with the most JSON-like records, as the manifest chooses its own. A request with no recorded
answer is made, since it may have changed the application, but not compared. Each is listed per probe with its
reason and left out of agreement.
- A request no tool matches is reported `no-tool`; a matched tool the environment does not offer, such as a write it
withholds, is reported `not-served`. Neither is answered.
- Ids differ between a re-seeded application and the capture. The comparison maps them:
- seeded entities pair across the two answers by a natural key: a field present on every element of both arrays whose
string values are unique on each side and shared between them;
- identifier fields (`id`, `uuid`, `guid`, and names ending in `_id`, `Id`, `ID`, `_uuid` or `Uuid`) of paired objects,
and of the two answers to the same call, map the live value to the environment's value; a create's two answers map
the new ids, including a response that is only that id at the write plan's identity location. The `id`, `uuid` or
`guid` of the answer's own entities (at the read view's entity or list location, a write's response location, or
else the root) also maps within the collection the call names, since two collections can reuse a live id for
different entities. An equal pair is kept in that collection, so another collection's mapping of the same live id
does not replace it. Global mappings are one-to-one and first-pair-wins; equal global pairs also reserve both ids.
If an equal pair conflicts with another pairing, its contested live or environment id is not used to normalize
either pair, in either observation order. Only non-identity, unconflicted mappings count as mapped ids. Outside
identifier fields, a string maps only at a field where learning found it held as an id in environment state. The
keys of two objects keyed by ids map
when their values pair (keys that partly overlap only when they are digits, UUIDs or their entries' identities, and
every value pairs);
- ids are learned only from an answer the environment gave this call, from its state or from a recording of exactly
this call, its whole request line and its request body: a recording of another call that replay answers with
instead holds other entities. A tool that takes a body does not match a recording whose body the probe did not send;
- path, query and body values equal to a mapped live id are translated before the environment answers, a path
parameter by the collection it names, except query values that page a list (`limit`, `offset`, `page` and the
like), which count items rather than name one. A literal route segment is not translated. A nested collection is
the live path's concrete parent values, each parameter decoded once, so two parents do not share one child map and
spellings replay treats as equal name one. A second encoding stays a different parent. Learning and translation use
that same live path.
A path value the map does not know, and the environment's state does not hold, is reported `unmapped-id`.
- A call is checked against the served tool's input schema first, as the MCP server checks it; a call it refuses is
reported `refused`. A browser probe keeps its request bodies; one captured without response bodies is refused, since
only statuses would compare, and so is one that makes POST, PUT or PATCH calls without recorded request bodies, since
those calls would be made empty.
- Answers compare after normalisation: empty response text and JSON `null` equal no body (a JSON empty string stays one);
decoded JSON values compare structurally, plain text compares as text, and retained base64 bodies compare as bytes
(including against UTF-8 text with the same bytes), without treating a base64 spelling as text. Mapped ids compare
equal in identifier fields, in `ids`/`uuids`/`guids` scalar lists, and for an entity's own identity within the call's
collection; other numeric fields stay literal. Any other id compares by the
probe's mapping, and an entity's own identity both sides hold verbatim differs when its collection's mapping gives it
another environment value (a reference keeps raw equality, as the probe's mapping cannot tell which collection it
names); an object's members compare under the environment's mapped keys only when it is keyed by learned ids as
learning reads one, and any other object compares field by field; two clock values (ISO-8601 strings, or epoch numbers under
time-named fields) compare by format only; numeric array elements remain literal.
Different strings normalize as generated only at direct entity fields where
the executed served write plan proves a unique token or UUID/token identity
generator, and neither side participates in an ID mapping. A UUID or token
shape alone is insufficient evidence. A body over the replay
limit, text or binary, compares by status only, as does a live body the probe did not record, unless the answer has
none by definition (204, 205, 304, or an answer to `HEAD`). Both are counted.
- A step agrees when the statuses are equal and the normalised bodies are. Differences are categorised: `status`,
`missing-field` (the application had it), `extra-field`, `value`, `length`, `order`, `clock-format`, `refused` (the
environment refused the call), `not-served`, `no-tool` and `unmapped-id`, each with a JSON pointer and short values.
- The report gives agreement overall, per probe and per tool, agreement ignoring item order beside it, the counts per
category, the ids mapped and the values normalised, the records left uncompared, and each step's differences (at most
20 per step). Each step gives `differences_total` before that cap, `differences_omitted`, and
`differences_truncated`, true when entries were omitted. Equality and categories use all differences.
Omitted entries are not retained and `--full-output` cannot recover them; further investigation uses the original
capture and probe Evidence.
## Non-goals
- No network access, no credentials, no reset of the application: probes are recorded outside REA.
- No generation of call sequences; a later change generates them where the environment disagrees.
- No change to how environments serve.
@@ -1,12 +0,0 @@
# Tasks
- [x] Record the outcome, requirements and non-goals.
- [x] Load probes as captures.
- [x] Match probe requests to tools.
- [x] Map ids and translate arguments.
- [x] Normalise and categorise differences.
- [x] Compare per probe and report.
- [x] Add the command and its documentation.
- [x] Add unit and command tests.
- [x] Run the gates.
- [x] Measure six environments against their live applications and record the results.
@@ -1,146 +0,0 @@
# Verification
Verified commit: 235b22f2 on the write-plan branch at 7056f5ff. Executed on macOS with Node v22.23.1 (the repository
pins 24.18.0 in `.nvmrc`, which was not installed); the live applications ran on six disposable Linux VMs.
## Gates
- `npm run build:cached`, `npm run check:fast` (typecheck and lint), `npm run format:check`, `npx knip`,
`npm run scan:todos`, `npm run docs:check`, `npm run verify:test-discovery` and `npm run mcp-catalog:check`: passed.
- `npm run jscpd`: 3.46% duplicated lines over 3609 files, under the 3.5% gate.
- `npx vitest run --project domain --project services`: 7487 passed, 5 pre-existing skips.
- `npm run test:prepare`, then `npm run test:focused --` the environment-compare, export and serve CLI boundaries, the
serve MCP boundary and the tool schema validity boundary: 5 files, 30 passed.
New tests: matching, id mapping and translation, pairing guards, normalisation and every category as unit tests
(`environmentCompareIds`, `environmentCompareDiff`, `environmentCompare`, 19 tests), and the command through the built
CLI (`environmentCompareCli`, 2 tests): a probe of the books application re-seeded under other ids agrees on every step
with 2 ids mapped, and a probe that is not capture Evidence is refused with its index.
## Six environments against their live applications
Six published environments were compared with the application each was captured from: NetBox 4.7.3, Komga 1.29.1,
Mealie 3.28.0, n8n 1.123.85, Shlink 5.1.7 and self-hosted Sentry 26.9.0, the same images, brought up and seeded by the
same scripts as for their captures, on loopback. Each was snapshotted after seeding and restored from that snapshot
before every sequence (7 to 80 s), so every sequence met the same application.
A driver outside REA ran three kinds of sequence per application, each starting with the capture's read-only prefix:
the capture re-run in order; per served write type, a list, create, read, update, read, delete, read and list, then a
second create with changed free text; and a read of every seeded entity through its item tool. It translated the
environment's ids to the application's as it learned them, signed in with the application's own credentials, and wrote
each sequence as a HAR without headers or cookies, which `inspect-web-network-capture` turned into probe Evidence. The
environments' manifests use `prefix-variance`, so the comparison ran on a local build of this branch with that rule's
branch merged.
| Environment | Steps | Agreement | Ignoring order | Against its own capture |
| ----------- | ----: | --------: | -------------: | ----------------------: |
| NetBox | 370 | 99.2% | 99.2% | 100% |
| Komga | 356 | 93.8% | 93.8% | 93.1% |
| Mealie | 301 | 96.0% | 97.0% | 97.1% |
| Shlink | 133 | 89.5% | 92.5% | 92.4% |
| n8n | 202 | 74.8% | 87.6% | 87.5% |
| Sentry | 230 | 23.9% | 46.5% | 84.7% |
The last column compares each environment with its own capture as the probe: what it cannot reproduce even of the
session it was built from. The disagreements fall into four groups.
- Environment gaps, the ones to fix:
- write tools the environment withholds, and the reads after them: readlists and collections (Komga), recipes (Mealie), short URLs
(Shlink), workflow and tag writes (n8n);
- preconditions: n8n refuses to delete a workflow that is not archived and the environment deletes it;
- lists: a create does not appear in a list that keeps its recorded members (Komga), a filtered list is answered
without the filter (Shlink), a replayed search ignores its body (Komga);
- a domain-scoped short URL answered without its `domain` parameter, where Shlink answers 404;
- state rendering: a project field two recorded views disagree on is rendered with one value, and an organisation
read whose shape depends on a query parameter is answered the same either way (Sentry);
- a tag read refused for want of the fields its item view always carried (Mealie);
- time: per-hour event counts move with the current time, while the environment's clock is frozen at the capture
(Sentry);
- a field the capture's scrubbing replaced, answered as `"<scrubbed>"` (Sentry).
- The application differing from itself between seedings: Sentry returns permission lists in no fixed order and
reseeding changed release first-event times, feature lists and profile flags; n8n's executions and NetBox's running
worker count differ from the captured instance.
- The probe observing itself: Komga and Sentry report the driver's own sign-in user agent.
- Driver gaps: ids the driver never mapped (Mealie units, Sentry events by hash) were sent as the environment's ids.
## What the runs fixed in the comparison
Each live run found a way the comparison itself was wrong, fixed with a test before the next run: requests are matched
to tools in the environment's terms, so a tool whose path holds a seeded id literally matches; ids are learned outside
identifier fields only from strings, after NetBox's worker count of 1 mapped a live 0 to entity 1; items paired only by
position teach ids only when no key is shared and the lengths agree, after a filtered Shlink list mapped one short URL to
another; objects keyed by ids pair their entries (n8n data tables); reordered scalar sets differ in order only and epoch
numbers in arrays are clocks (Sentry); and bodies over the replay limit compare by status.
## After the review round
The branch merged the write-plan branch at b6c3b168 (four serving and gate fixes its review found), then changed the
comparison in nine places: ids are learned only from answers to the call itself and also per collection, paging values
are never translated, calls go through the served tools' input schemas, browser probes keep their request bodies, empty
bodies and large binary bodies compare as the server answers them, scalar sets compare after mapping, and id-keyed
objects pair when some keys overlap. Each new test fails on the previous head. The gates above passed again (domain and
services 7504 passed with 5 pre-existing skips; the focused boundaries 80; conformance; `jscpd` 3.46%). Re-run on the
same probes with this branch and the template rule's merged, the six environments compare exactly as in the table above,
step for step, with the same ids mapped and the same values normalised.
A second round, on Greptile's review of those changes, learned ids from a replay only when the whole recorded line and
request body match the call, compared an entity's own identity within the call's collection and other ids by the probe's
mapping, read overlapping keys as ids only when they evidently are ids, and kept a JSON empty string apart from empty
text. Its four tests fail on the previous head; the six environments again compare exactly as in the table.
A third round located the answer's own entities where the served environment does, at the read view's entity or list
pointer or the write's response pointer, so an entity inside an envelope keeps its collection's mapping. Its test fails
on the previous head; the gates passed again (domain and services 7509, boundaries 80, conformance, `jscpd` 3.46%) and
the six environments again compare exactly as in the table.
A fourth round, on Greptile's next review, kept what a probe did not observe out of the agreement figures. Records
without a usable request line, and requests without a recorded answer, are listed per probe with the reason and left
uncompared. A live body the probe did not record compares by status only and is counted. A browser probe captured
without response bodies is refused. A format-rule path parameter fits by its decoded value, as replay reads it. The
branch also merged the write-plan branch at 1d1c4787, whose gate no longer confirms a write by a read of a state that a
later write replaced. Each new test fails on the previous head. The gates passed again (domain and services
7647, 5 pre-existing skips; the compare, export, serve and analysis-view boundaries 69; conformance 279; `jscpd` 3.44%).
On the same probes, the six environments have no unobserved records or bodies, and five compare exactly as before.
Komga now withholds its collection create and patch. The only read the gate could check them by is the 404 after the
collection is deleted, because the read after the patch is the patch's own observation. Its agreement falls from
96.9% to 93.8%: the three creates and two patches the probes make are not served, and the six reads and deletes of
those collections that follow fail. Against its own capture it falls from 96.6% to 93.1%. The table shows the new
figures.
A fifth round merged the write-plan branch at dc5e2aad, which weighs an update's derived changes when a later write
replaces it and resets collection spellings on reset or load. It also makes a request whose answer the probe lost,
still uncompared, so that a later read sees its effect: a lost delete followed by a 404 now agrees. Its test fails on
the previous head. The six environments compare as in the table.
A sixth round merged the write-plan branch at fe8ab584, whose gate erases the fields later writes and recorded
outcomes overwrite from earlier write effects. The six environments again compare exactly as in the table.
A seventh round merged the write-plan branch at 3580d85c and main d8a9673f. That brought the gate's fix for overwritten
document writes, which Greptile raised here against the write-plan code, among others. It also fixed two findings of
its own:
- a probe with any undated record keeps its recorded order, as state extraction does;
- a browser probe that makes POST, PUT or PATCH calls without recorded request bodies is refused.
Both tests fail on the previous head. The six environments compare exactly as in the table, on the probes and against
their own captures.
An eighth round merged the write-plan branch at 43d98ea9 and 264ce410. They bring the gate's fixes for three findings
Greptile raised here against the write-plan code: a passing read that shows nothing of a write leaves it pending, an
update or delete finds its entity as an item read does, and a built document plan writes later calls at its own
object. It also fixed one finding of its own: a request to another origin than the probe's application is neither
made nor compared, so another server's `DELETE /api/books/2` no longer deletes the environment's book. Its test fails
on the previous head. The six environments compare exactly as in the table, on the probes and against their own
captures, with no unobserved records.
It then merged the write-plan branch at 0ae64400 and 6257de93: an update's identity member never takes a rule, a page
size of zero bounds nothing, and the paging rules, with this branch's `isPagingParameter`, move to
`environmentStatePaging.ts`. The six environments again compare exactly as in the table.
A ninth round merged the write-plan branch at 466ed8b4, which fixes two findings Greptile raised here against its
code (entity fields that look like pointers match by name; a zero page size bounds nothing only where a recording
listed items under it) among others. The six environments compare exactly as in the table, on the probes and against
their own captures. It then merged 7cef2fb2, whose fixes settle three more findings Greptile raised here against that branch's code:
zero page sizes erasing another bound, partial write responses taken for removals, and interference timed by a tool's
call elsewhere. The six environments again compare exactly as in the table.
@@ -1,32 +0,0 @@
# Implementation plan
1. Widen the runtime `serve` dependency to a transport-neutral factory that may
bind asynchronously. `startMcpTransport` awaits it, hands it the server
logger, and keeps stdio as the default; the shutdown handle type loses its
stdio name.
2. Add `src/server/http/nodeHttpBridge.ts` to turn an IncomingMessage into a web
Request (headers, streamed body, abort on client close) and to pipe a web
Response back with flushed headers, and `src/server/http/serveStreamableHttp.ts`
to own one `McpServer` instance and one stateful transport per session,
ended by `DELETE` or replaced by the next client's `initialize` without
running the instance's shutdown hooks, plus plain routes, loopback Host
validation, the listening log line and idempotent close. The typed listen
error lives in its own module so the stdio entry never loads the listener.
3. Parse `--http`, `--host` and `--port` in `src/main/mcpHttpArguments.ts` from
one schema that also renders help; resolve `MCP_HOST`/`MCP_PORT` in
`src/config/mcpHttpEndpoint.ts` as a `Result` that names rejected settings
without their values.
4. Route the dispatcher to `runMcpHttpEntrypoint` when the `mcp` entry carries
`--http`; compose HTTP dependencies in `src/main.ts` with the shared
`run()` path so configuration, session, providers and shutdown stay common.
5. Register signals only for HTTP mode through `registerSignalShutdown`, a
projection of `registerProcessShutdown` without stdin that sets the signal
exit status before the idempotent shutdown runs; stdio keeps its stdin
end/close triggers.
6. Document the transport in docs/reference/mcp-contracts.md and docs/cli.md, relabel the
architecture diagram, and cover each boundary with adapters, dispatcher,
mcp-boundary and process-boundary tests plus a Python SDK client exchange.
No new dependency is introduced: the transport, Host validation and body bound
come from the already pinned `@modelcontextprotocol/server` root export. Tool
contracts, catalog digests, response budgets and stdio behaviour are unchanged.
@@ -1,82 +0,0 @@
# Streamable HTTP transport for the MCP server
Issue: https://github.com/morluto/rea/issues/4933
## Outcome
`rea mcp --http [--host H] [--port N]` serves the existing MCP tool catalog over
the pinned SDK's streamable HTTP transport instead of stdio, so an agent
environment runtime or any HTTP MCP client can reach REA on a local URL. The
listener is opt-in: bare `rea mcp`, `rea mcp doctor`, `rea mcp add` and every
client registration keep stdio.
## Requirements
- Route `mcp --http ...` and `--mcp --http ...` to the MCP runtime in the
dispatcher without changing bare `mcp`, `mcp doctor` or `mcp add`.
- Resolve host and port from the flags, then `MCP_HOST`/`MCP_PORT` from the
environment snapshot, then `127.0.0.1` and port `0`; announce the bound URL as
one pino JSON line on stderr at every log level and leave stdout unused.
- Use `WebStandardStreamableHTTPServerTransport` in stateful mode around one
server instance built once, after the listener has bound. `DELETE` ends the session on its transport without
running the instance's shutdown hooks, so the same instance keeps its
providers and serves the next client on a fresh transport; the hooks run when
the listener closes.
- Let a new client's `initialize` replace a session that is still open, closing
the earlier transport the same way, so a client that left without `DELETE`
cannot block the listener; the replaced client's later requests are refused
(`404` while the replacing session is open).
- Bridge node:http to web Request/Response in `src/server/http/`, streaming
response chunks as they are produced and turning a client disconnect into a
request abort and body cancellation.
- Classify a loopback bind by the actual bound IP (`127.0.0.0/8`, `::1`, or
IPv4-mapped loopback), without using the configured DNS name as evidence; validate
the `Host` and `Origin` headers with the SDK loopback allowlist plus the
configured name and the bound address on such binds, and relax both for
other binds and log that relaxation. Refuse scoped IPv6 literals before
binding, close the listener if its URL cannot be formed, and forward
listener errors to `onerror` only after a successful bind.
- Let the caller own instance cleanup (`closeInstance: false`) when its factory
owner already closes every instance, as the MCP runtime does.
- Let only an `initialize` that carries the streamable headers and passes those
checks replace an open session; refuse requests once the slot is closed, join
an arming session during shutdown, and keep close stages retryable.
- End the HTTP listener on SIGINT/SIGTERM only, never on stdin EOF, and exit with
the signal status (`130`/`143`) after cleanup settles; latch a signal that
arrives during startup so it is acted on as soon as the lifecycle owner exists,
and exit at once on a second one.
- Export `serveStreamableHttp({ host, port, createMcpServer, routes, logger })`
returning `{ url, close }` so an agent environment server can add plain routes
beside `/mcp` without a second bridge.
- Keep listener failure causes out of stderr behind a fixed message while the
typed listen error carries the system cause (such as `EADDRINUSE`) into the
error-level log line.
## Acceptance and limits
Adapters tests cover the bridge (method, URL, headers, body, GET without body,
incremental streaming, abort and cancel) and the listener (listening line, one
factory call across three sessions, replacement of an open session by the next
`initialize`, two `initialize` requests racing to replace one session while the
instance's shutdown hook stays installed, a working tool call after `DELETE`,
the instance's shutdown hook firing only when the listener closes, plain
routes, 404, Host refusal, port release, typed bind failure naming
`EADDRINUSE`). The dispatcher test covers the new routes and keeps `mcp add
--http` with the CLI. An mcp-boundary test spawns the built CLI and drives
initialize, tools/list, `binary_session` and `DELETE` with the SDK streamable
HTTP client, then proves `binary_session` still answers in the next session and
in a session that replaced one left open; a process-boundary test asserts
`143`/`130` exits and a released port. Concurrent clients are not supported:
the newest `initialize` owns the server. Non-loopback binds require the
operator's parsed hostname allowlist, retain Host/Origin gates, and announce a
client URL admitted by that list. Current listener regressions exercise a
wildcard bind, refusal/port release and a direct SDK connection to the
announced endpoint. Response
budgets keep their stdio-derived floor; registrations, `rea mcp doctor` and
`server.json` stay stdio.
## Deferred issue criteria
Serving an environment manifest with replayed records, its environment card and
the exported bundle are later increments of #4933. This PR must reference rather
than close the issue.
@@ -1,11 +0,0 @@
# Tasks
- [x] Define single-feature requirements and implementation plan before code.
- [x] Widen the runtime serve seam and shutdown handle to transport-neutral types.
- [x] Implement the node:http bridge and the streamable HTTP listener module.
- [x] Parse flags and `MCP_HOST`/`MCP_PORT`, route the dispatcher, add signals-only shutdown.
- [x] Document the transport, CLI entry, exit status and architecture label.
- [x] Verify bridge, listener, dispatcher, SDK client, Python client and shutdown behavior.
- [x] Keep providers alive across sessions, replace a session left open, name the bind cause in the log.
- [x] Resolve the re-review: capture the shutdown hook once, one shutdown registration primitive, flags-only HTTP routing.
- [x] Run relevant repository checks and prepare a separately scoped PR.
@@ -1,297 +0,0 @@
# Verification
Verified base: 18aa9af2b2c26fd114113dd39528a91224801840 (fetched main).
The worktree was moved onto that base with the slice's changes kept
uncommitted, then reinstalled with `npm ci` (exit 0; 540 packages added, 541
audited; 6.56 s elapsed, 3.85 s user, 8.07 s sys, 881459200 bytes maximum
resident set size). After the edits of this pass the tree was rebuilt with
`npm run build` (exit 0, three turbo tasks; 5.23 s elapsed, 13.94 s user,
2.93 s sys, 2964652032 bytes) and `npm run test:prepare` (exit 0, six tasks
with three cache hits; 1.37 s elapsed, 3.07 s user, 0.76 s sys, 422625280
bytes); `dist/mcp/` carries the rebuilt `serveStreamableHttp-*.js` chunk beside
`main.js`.
Static gates on the final tree: `npm run check:fast` passed (typecheck and
lint, two tasks; 4.69 s elapsed, 24.25 s user, 3.00 s sys, 4480139264 bytes).
`npx oxlint` over the files touched in this pass reported no findings. After
the last edit, including this record, `npm run format` ran over 4032 files
(0.68 s elapsed, 4.11 s user, 0.74 s sys, 227393536 bytes) and `npm run
format:check` passed (0.69 s elapsed, 4.09 s user, 0.62 s sys, 216989696
bytes). `npx knip` exited 0 (3.80 s elapsed, 5.10 s user, 0.72 s sys,
868679680 bytes). `npm run check:ci:tasks` passed all eight tasks, seven of
them turbo cache hits from the run on the same sources (0.88 s elapsed, 4.52 s
user, 1.04 s sys, 215171072 bytes): jscpd reported 2576 clones and 3.35%
duplicated lines across 3143 files under the 3.5% threshold, lint:built 0
errors over 3734 files, and format:check ran fresh. `npm run docs:check`
passed, including the README consistency test (5 cases; 3.27 s elapsed,
3.43 s user, 0.80 s sys, 288866304 bytes). `git diff --stat` lists 13 tracked
files, none under `src/domain/`.
Source-group tests: `/usr/bin/time -l npx vitest run --project adapters
src/server/http src/server/shutdownRegistration.test.ts` passed 3 files, 17
tests in 2.74 s elapsed, 3.12 s user, 0.93 s sys, 289767424 bytes.
`serveStreamableHttp.test.ts` gained the concurrent case: a slot with one open
session receives two `initialize` requests through `Promise.all`, exactly one
answers `200` with a session id and the other `400`, the instance's `onclose`
hook has fired zero times, and `slot.close()` fires it once. Run before the fix
against the same file, that case failed with the hook count `0` instead of `1`
(1 failed, 5 passed; 1.07 s elapsed, 0.84 s user, 0.21 s sys, 158187520
bytes), which is the pinned no-op hook the review described.
`shutdownRegistration.test.ts` asserts that `registerProcessShutdown` hands
the handler `SIGINT`/`SIGTERM` by name and `undefined` for stdin end, that
omitting stdin registers no input listener, and that `registerSignalShutdown`
reports `143`/`130`.
Built-group tests ran after `npm run test:prepare`. The targeted dispatcher
run, `/usr/bin/time -l npx vitest run --project cli-boundary
tests/boundary/cli/dispatcher.test.ts`, passed 3 tests in 1.08 s elapsed,
0.89 s user, 0.26 s sys, 153026560 bytes, now including `mcp add --http`
routed to the CLI beside `mcp --http --port 0`, `--mcp --http` and `mcp --host
127.0.0.1 --http` routed to the HTTP entry and `mcp doctor --http`, `mcp add`
and `--mcp extra` keeping their routes.
The four full projects ran in sequence while a sibling worktree ran its own
`cli-boundary`, `mcp-boundary` and `acceptance` chain on the same host.
`/usr/bin/time -l npx vitest run --project adapters` passed 247 files, 3945
tests with 8 skipped, in 93.77 s elapsed, 80.21 s user, 30.69 s sys, 344260608
bytes. `/usr/bin/time -l npx vitest run --project mcp-boundary` passed 155
files with 2 skipped, 910 tests with 7 skipped, in 167.51 s elapsed, 321.24 s
user, 51.30 s sys, 4923490304 bytes (the Vitest parent, its workers and the
spawned CLI children). `/usr/bin/time -l npx vitest run --project
process-boundary` exited 1: 56 files passed, 2 skipped and 2 failed, 460 tests
passed, 19 skipped and 7 failed, in 544.81 s elapsed, 160.89 s user, 133.49 s
sys, 1028931584 bytes. `/usr/bin/time -l npx vitest run --project
cli-boundary` exited 1: 108 files passed and 3 failed, 658 tests passed, 2
skipped and 7 failed, in 452.34 s elapsed, 734.29 s user, 234.02 s sys,
648495104 bytes. No failing file belongs to this slice.
The failures split into two kinds. Load: six `jadxIntegration.test.ts` cases
hit the 30 s test or 10 s hook timeout, and six `javascriptApplication*.test.ts`
cases failed with the worker's result-capacity constraint; re-run alone in this
worktree after the other chains ended, `jadxIntegration.test.ts` passed all 48
tests and both JavaScript files passed all 20 tests (`cli-boundary` three files:
20 passed, 1 failed, 23.38 s elapsed, 32.99 s user, 10.97 s sys, 343244800
bytes; `process-boundary` two files: 48 passed, 1 failed, 62.48 s elapsed,
21.89 s user, 17.55 s sys, 686620672 bytes). Pre-existing on main in this
environment: `closedStdout.test.ts` "stops quietly when the reader closes
during streamed JSON" exits `1` instead of `141` with 1009 bytes received and
empty stderr, and `releaseArtifactCanary.test.ts` fails parsing `npm pack
--json`, which npm 12.0.2 emits as an object keyed by package name rather than
the tuple the test expects. Both reproduce identically on the clean sibling
clone at `52b73ee857029a3ab8f5c6eeef233b295951a46c` (no tracked or untracked
changes; `closedStdout` 1 failed, 3 passed, 8.86 s elapsed, 6.98 s user, 2.29 s
sys, 348012544 bytes; the canary 1 failed, 7.91 s elapsed, 7.76 s user, 1.84 s
sys, 668729344 bytes). That clone predates the verified base by 15 commits,
none touching either test or `scripts/rea.mjs`. Because the dispatcher is on
the `closedStdout` path, its scenario was also replayed against this
worktree's built `dist/` with the `18aa9af2` `scripts/rea.mjs` and with the
edited one, three runs each: all six exited `1` with 1009 bytes received and
empty stderr. Nothing in this pass was changed for these failures.
Cross-implementation check with the Python `mcp` 1.30.0 client (httpx 0.28.1,
Python 3.12.12) against the built `node scripts/rea.mjs mcp --http --port 0 <
/dev/null`: stderr announced
`{"transport":"streamable-http","url":"http://127.0.0.1:57093/mcp","msg":"MCP transport listening"}`.
Session A: `initialize` POST returned `200 text/event-stream` with
`mcp-session-id`; `notifications/initialized` returned `202` with no body; the
standalone GET and the `tools/list` and `tools/call` POSTs returned `200
text/event-stream`; `tools/list` reported 207 tools including
`binary_session`; `binary_session` with `{}` returned `isError=False`; `DELETE
/mcp` returned `200`. Session B, opened after that `DELETE`, initialized with a
new session id, listed the same 207 tools, and `binary_session` again returned
`isError=False` before its own `DELETE` returned `200`. The server logged two
`MCP HTTP session opened` and two `MCP HTTP session closed by the client`
lines, SIGTERM then exited it with status `143`, and stdout stayed empty. The
methods, statuses and session-id handling of session A match the recorded
reference exchange step for step; the reference's echo server labelled its
`202` and `DELETE` replies `application/json`, where this listener sends no
content type for those bodiless replies.
## Independent review
An adversarial review of the first implementation reproduced that, after a
`DELETE`, the next session could initialize and list tools but every tool call
failed with a `cancelled` error because the SDK's `DELETE` handling closed the
transport and the server's `onclose` hooks ran provider teardown. It also found
that a session ended without `DELETE` blocked the listener until restart, that
the bind-failure log line omitted the system cause, a duplicated foreign-`Host`
probe, a missing trailing newline on `rea mcp --http --help`, and a static
import of the HTTP listener on the stdio path. Each finding is addressed and
covered by the adapters, mcp-boundary and Python checks in this document.
The re-review of the rebased tree raised four points, all resolved here. Two
concurrent `initialize` POSTs could leave the no-op `onclose` hook installed,
because each session end captured the hook current at that moment and the
later `finally` restored the other call's no-op; `McpSessionSlot` now captures
the instance's hook once, after the factory returns the fully wrapped server,
and every session end restores exactly that, with the adapters case above
failing before and passing after the change. The optional stdin parameter of
`registerProcessShutdown` was dead in production; `registerSignalShutdown` is
now a projection of `registerProcessShutdown(handler, { signals })`, so one
primitive owns registration while the handler learns the signal and keeps
`130`/`143`. The dispatcher routed any `mcp` invocation containing `--http` to
the HTTP entry; it now does so only when the first token after `mcp` or
`--mcp` is a flag, so `rea mcp add --http` keeps the CLI's own diagnostic, and
the dispatcher test covers that case. The formatter hunk in
`src/domain/propertyListXml.test.ts` noted in the earlier record is gone after
the rebase, as `git diff --stat` confirms. The replacement rule stays as
documented, and `docs/reference/mcp-contracts.md` now states it in one sentence with its
rationale so maintainers can decide on it.
## Scope and measurement limits
The concurrent-`initialize` case is exercised at the slot with in-memory
`Request` objects, where both calls advance in lockstep; over TCP two
connections are served in separate event-loop turns, so the race is reachable
only in-process and the listener-level behaviour remains "the newest client
owns the server, the other sees `400` or `404`". Those recorded runs predate the mandatory non-loopback allowlist and did not
exercise a wide bind. The current requirement and later listener regression
coverage are described in the [specification](spec.md). Sessions are served one at a time;
concurrent clients are not supported. The two failures that reproduce on the
clean clone are environmental (macOS with Node 22.23.1 and npm 12.0.2) and are
left for their owners; the load-induced timeouts were classified by isolated
re-runs, not by repeating the full projects on an idle host. The error-level
log line that names the bind cause was observed in earlier runs, not asserted
by `mainErrors.test.ts`. Response budgets keep the stdio-derived floor and were
not re-measured over HTTP. Windows was not run.
## Automated review findings on the PR (2026-10-18)
Codex and Greptile left eight inline findings on morluto/rea#4955 at
46dd8f0e; each was checked against the code and addressed in one follow-up
commit, with a regression test where the behaviour is observable:
- A late `initialize` could arm a fresh transport after shutdown (Codex, P1):
the slot now records that it is closed, `close()` joins an arming session
before ending it, and every request after that is refused with `503`. Test:
an initialize racing `close()` gets `503`, the shutdown hook fires once, and
the next request gets `503`.
- A failed `close()` was memoized forever (both reviewers, P1): the close runs
three stages once each and a failed stage is retried by the next call. Test:
the instance's first `close()` rejects, the second call resolves and the port
is released.
- Loopback aliases skipped Host validation (both reviewers, P2 and P1): a bind
is now loopback by address class (`127.0.0.0/8`, `::1`, IPv4-mapped loopback,
`localhost` names) after the same normalization the SDK applies to the Host
header, and the allowlist adds the bind's own hostname so requests to
`127.0.0.2` or `localhost.` are still served. Test: twelve spellings.
- A sessionless POST could close the live session before any header check
(Greptile, P1): on loopback binds the route validates `Origin` with the same
allowlist as `Host`, and only a POST carrying `Content-Type:
application/json` and an `Accept` naming both `application/json` and
`text/event-stream` may replace a session; others reach the live transport,
which refuses them. Test: a `text/plain` initialize and one with a foreign
`Origin` are refused (4xx and 403) while the connected client keeps echoing.
- The bound URL disappeared at quiet log levels (Greptile, P2): the listening
line is written through a child logger pinned to `info`. Test: a `warn`
logger still receives the line with the URL.
- `rea mcp -h --http` reached the ordinary CLI (Greptile, P2): the dispatcher
predicate accepts any flag after the entry. Test: the dispatcher case.
Checks after the change: `oxfmt --check .` clean; `tsc --noEmit` clean;
`oxlint` on the touched sources clean after extracting the staged close into
its own function; `npx knip` no findings; `npm run jscpd` 3.35 % duplicated
lines; `scan:todos` none; `verify:test-discovery` 1,583 files once; `vitest
run` over the listener and bridge adapters tests 14 passed in 2 files; after
`npm run build:cached`, `vitest run` over the dispatcher, option, streamable
HTTP, shutdown and main-error boundary tests 22 passed in 5 files.
A second automated round on the fix (Codex, two P2 findings) was addressed in
the next commit: the replacement guard compares the media type proper, so
`application/json-patch+json` no longer counts as JSON (test: such an
initialize is refused while the connected client keeps echoing), and the
server instance is created only after the listener has bound, so a bind
failure has nothing to clean up and a factory failure releases the listener
and rethrows (test: a throwing factory rejects without announcing a URL).
A third round (Greptile and Codex, five findings) was addressed next: the
listener's `error` forwarding to `onerror` is registered after the bind, so
`EADDRINUSE` prints only the listen-failure message (test: an occupied port
rejects without calling `onerror`); scoped IPv6 literals are refused before
binding and a URL that cannot be formed from the bound address closes the
listener (test: `fe80::1%lo0` rejects before the factory runs); loopback is
classified from the bound address with the configured name added to the
allowlist (test: `ip6-localhost` bound to `::1`, `dev.local` bound to
`127.0.0.1`); and the MCP runtime passes `closeInstance: false` so the factory
owner in `startMcpTransport` remains the single owner of instance cleanup
(test: `close` leaves the instance open until its owner closes it).
A fourth round (Codex, two findings) was addressed next: the replacement
guard parses `Accept` into media ranges and requires exact `application/json`
and `text/event-stream` entries (test: `application/json-patch+json,
text/event-streaming` is refused while the connected client keeps echoing),
and a session whose transport shutdown rejected stays owned so the next close
retries it (test: a failing transport close rejects `close()` once, the second
call completes, the shutdown hook fires once and later requests get `503`).
A fifth round (Codex, three findings) was addressed next: the instance's
shutdown hook now runs exactly once even when the listener closes without a
live session (test: two closes of an idle slot fire it once; an idle listener
close fires it once); the initialize probe no longer awaits cancelling its
cloned body, which is one branch of a tee and would wait for the original
request to drain (test: a 4.5 MB sessionless initialize is refused promptly
while the connected client keeps echoing); and the node:http bridge passes
repeated `Set-Cookie` values as an array instead of collapsing them (test: two
cookies from a composed route both arrive).
A sixth round (Codex, one P1) was addressed next: signal handlers were only
installed after the asynchronous startup returned, so a SIGINT or SIGTERM
during target opening, provider loading or the HTTP bind ended the process
without cleanup. The HTTP entry now latches signals before startup, the
lifecycle owner picks the recorded signal up as soon as it registers, and a
second signal during startup exits at once (test: the latch records `143`,
exits on the second signal, hands the status over on release and leaves no
listeners behind).
Both reviewers then noted that the latched signal's status was overwritten by
the entry's normal `0` return: the HTTP entry now owns its exit status through
`createExitStatus`, where a `0` after a recorded signal keeps the signal's
status and a real failure still wins (unit test), and a process test sends the
signal the moment the listening line appears and asserts the signal status.
An eighth finding (Codex): a reply sent before the MCP handler read the body
left that body unread on a paused bridged stream, so a slow uploader could
hold the socket. The bridge now closes the connection after any reply whose
request body was never read (test: an unknown-route POST and a foreign-Host
POST are answered with `Connection: close`, while a keep-alive GET without a
body keeps its connection).
A ninth round (Greptile and Codex): request conversion ran outside the guard,
so a method Fetch refuses (`TRACE`) could crash the process; the conversion is
now guarded and answered with `405` and a closed connection (test: `TRACE`
gets `405` and the next client still echoes). The unread-body decision now
comes from the incoming message's own body declaration, so a `GET` or `HEAD`
that carries a body also closes, and the regression uses a keep-alive agent
and checks that the socket actually closes after the early reply while a
bodiless `GET` keeps its socket.
A tenth round (Codex, three findings): the takeover guard now requires a lone
`initialize`, mirroring the transport (test: a batch of `initialize` plus
`notifications/initialized` is refused while the connected client keeps
echoing); the shutdown hook records completion only after it returns, so a
hook that threw stays eligible for the next close (test: a hook that throws
once runs twice across two closes and then no more); and the bridge joins the
request target onto the listener's origin verbatim, refusing absolute-form
targets (test: `//attacker.example/card` is a 404 for that path, a plain route
sees the bound host only, and `http://attacker.example/card` gets `400`).
An eleventh finding (Codex): URL construction canonicalized dot segments, so
`/public/../mcp` reached `/mcp`. The bridge now refuses any target whose path
differs after URL parsing, so routing always sees the path the client sent
(test: `/public/../mcp`, `/public/%2e%2e/mcp` and `/./mcp` get `400`; `/card?x=1`
still routes).
A twelfth finding (Codex): `bodyUsed` means disturbed, not consumed, so a
composed route that read one chunk of an upload left the rest paused on a
keep-alive socket. The close decision now uses the incoming message's end of
stream (test: a route that reads one chunk of a 256 KiB upload is answered
with `Connection: close` and a closed socket; a route that reads it all keeps
the connection).
A thirteenth round (Codex): an `Accept` range with `q=0` no longer counts toward
the takeover guard (test: `application/json;q=0, text/event-stream` is refused
while the connected client keeps echoing). The same round noted that a failed
startup leaves cleanup of the already opened session and providers to a single
attempt; that path is the pre-existing stdio startup-failure cleanup, which the
HTTP mode now reaches on `EADDRINUSE`, and is left for the maintainers to decide.
@@ -1,12 +0,0 @@
# Implementation plan
1. **Gate.** Judge each latest list recording on its own for paging-only query, totals, next page and state order;
keep `all` when every line passes and otherwise name the passing lines in `all_record_ordinals`; reproduce each
line with its own membership.
2. **Counters.** Count `number`-of-items members as item totals.
3. **Consumers.** One helper says whether a view lists all on a line; serving, the write gate's list checks and the
insert retry use it, and an argument-less call may answer on any such line.
4. **Absences.** When a read shows an entity absent, drop it from every write's claim on its collection, so a write
left with none no longer counts there.
5. **Tests and docs.** Domain and serving tests as the acceptance lists; the membership row of the environment-state
docs and the list answer row of the agent-environment docs.
@@ -1,49 +0,0 @@
# Decide a list's whole-collection membership per line
Issue: https://github.com/morluto/rea/issues/4933
## Outcome
A list view reproduces its lines from the state with one of two memberships: `all`, every entity of the collection in
state order, or `recorded`, the entities each recording listed. The view was `all` only when every checked line listed
its whole collection. A list tool often also has a filtered line (`?library_id=…`, `?name=…`), and that one line kept
every line of the tool to its recorded members. An entity the environment created then never appeared in a list,
though the unfiltered line of the same tool had shown the application listing every entity.
Each checked line is now judged on its own. A recorded-membership view names, in `all_record_ordinals`, the checked
lines that each meet the conditions `all` asks of every line: the line has no query or only paging parameters starting
at zero, lists
exactly the entities of its collection in state order, and shows no total that differs from the number listed and no
next page. A call answered on such a line lists every entity of the collection, the write gate checks a read on it
against the whole collection, and a create's insert rule may be retried on it, as for an `all` view. Other lines keep
their recorded members. Without such a line, or when every line is one, the view is unchanged and the member is absent,
so existing states keep their values.
Positive or malformed `offset`, `start`, `_start`, and `page` positions do not establish whole membership, even for an
empty collection. Positive page numbers are ambiguous without a recorded zero-/one-based convention. These lines keep
recorded membership rather than inventing earlier items after a write or `data/add`; all paging values must be safe
nonnegative integers. Repeated positions must all be zero.
A whole line's read checks the collection, so it exercises every write that changed the collection since it was last
read. A write whose entity a read has since shown absent, for example a create an unmodelled delete removed and a 404
then showed gone, no longer counts there, as when a modelled delete replaces it. The same holds when a failed item check
takes the read's answer and that answer holds no entity. Otherwise a whole list taken after the entity was gone would
confirm a create it cannot show.
`numberOfElements` and similar number-of-items members (`number` with `elements`, `entries`, `items` or `results`)
count the listed entities, so a whole line's counter follows the state as `totalElements` does. A view with whole lines
takes the counters that equal the number listed on each of them, since a partial page's total counts more than the page;
a view without one keeps those that do on every line. A line is answered with each counter set to the number listed
only when its own recording showed that counter equal to the number it listed, so a partial page keeps its recorded
total.
## Acceptance
- Domain: a tool with a whole line and a filtered line names the whole one; a create the whole line later lists is
confirmed; a tool whose lines are all whole, or none, names none; a whole list taken after a read showed the created
entity gone confirms no create.
- Serving: after a served create, the whole line lists the created entity with its counters, and the filtered line
keeps its recorded members; beside a partial page whose total counts the collection, the whole line's total follows
the state and the page keeps its recorded total.
- Measured: the six published environments compared with the application before and after, on the probes of the
fidelity comparison and the held-out sessions recorded since.
@@ -1,10 +0,0 @@
# Tasks
- [x] Judge whole-collection membership per checked line.
- [x] Count number-of-items members.
- [x] Serve, check and place creates per line.
- [x] Drop a write from its collection once a read shows its entity absent.
- [x] Add domain and serving tests.
- [x] Document per-line membership.
- [x] Measure the six published environments before and after.
- [x] Run static, formatting, duplication, documentation and test gates.
@@ -1,103 +0,0 @@
# Verification
Verified commit: 40800631 (this branch with the write-plan branch's head `dc5e2aad` merged in). Executed on macOS with
Node v22.23.1 (the repository pins 24.18.0 in `.nvmrc`, which was not installed); the probes were recorded earlier
against the live applications on six disposable Linux VMs.
## Gates
- `npm run build:cached`, `npm run check:fast` (typecheck and lint), `npm run format:check`, `npx knip`,
`npm run scan:todos`, `npm run docs:check`, `npm run verify:test-discovery` and `npm run mcp-catalog:check`: passed.
- `npm run jscpd`: 3.45% duplicated lines over 3646 files, under the 3.5% gate.
- `npx vitest run --project domain --project services`: 7616 passed, 5 pre-existing skips.
- `npm run test:prepare`, then `npm run test:focused --` the environment serve and export CLI boundaries, the serve
and served-writes MCP boundaries, the analysis-view CLI and MCP boundaries, the compact input schema boundary and
tool schema validity: 8 files, 78 passed.
New tests: three domain tests in `environmentStateWrites` (a tool with a whole line and a filtered line names the whole
one, with `numberOfElements` and `totalElements` as counters, and a create the whole line lists is confirmed; a whole
list taken after a read showed the created entity gone confirms no create, which fails without the absence rule; a
tool whose lines are all whole, or none, names none) and one serving test in `environmentStateWriteAnswer` (after a served
create, the whole line lists the created book with its counters, and the filtered line keeps its recorded member).
## Fifty published captures
The environment-state view ran over the 50 published captures with each manifest's template rules, on builds with and
without this change. Both merged the prefix-variance branch, which some manifests need.
- 47 list views in 20 environments gain a whole line, among them Komga's books, series, collections and read lists,
BookStack's books, chapters and pages, Mealie's cookbooks, shopping lists, categories and tags, WordPress's posts and
comments, Vikunja's labels and Paperless's groups. On that line a call now lists the state's entities, including
those a task loads with `data/add` and those served writes create or delete, where it listed only the recorded
members. Three of them belong to a type with a served write: Airbyte's tags, BookStack's books and Linkding's tags.
- Served write tools stay at 31, with two changes:
- Airbyte's tag delete is now served. A whole list after the delete shows the tag gone.
- Sentry's release create is now unconfirmed, in the pool's earlier manifest, where the release's update and delete
are literal tools and not modelled. Its only confirmation had been a whole list taken after the delete and a 404
showed the release gone. The write-plan branch already refuses such a list after a modelled delete; this change
refuses it after an observed absence too.
- Komga's list views also count `numberOfElements`. No other view or write plan changed.
- Every write verdict is unchanged for the six environments republished with newer manifests (NetBox, Komga, Mealie,
n8n, Shlink, Sentry). Komga gains 6 whole-line lists, Mealie 4 and Sentry 1.
## Six environments against their applications
The six environments of the fidelity comparison (NetBox, Komga, Mealie, n8n, Shlink, self-hosted Sentry) were compared
with their applications by `environment-compare` with and without this change. The probes were the comparison's capture
re-run, create/read/update/delete scenario and read of every seeded entity, and held-out sessions recorded later with
values no capture sent. Both builds merged the environment-compare and prefix-variance branches.
| Environment | Steps | Before | After | Ignoring order, before | After |
| ----------- | ----: | -----: | ----: | ---------------------: | ----: |
| NetBox | 479 | 98.5% | 98.5% | 98.5% | 98.5% |
| Komga | 600 | 91.5% | 91.5% | 91.5% | 91.5% |
| Mealie | 449 | 94.0% | 94.0% | 94.9% | 94.9% |
| n8n | 278 | 71.6% | 71.6% | 84.2% | 84.2% |
| Shlink | 202 | 87.1% | 87.1% | 90.1% | 90.1% |
| Sentry | 372 | 24.5% | 24.5% | 47.6% | 47.6% |
No step changed. This Komga environment's capture creates, updates and deletes a collection before any whole list, so
with the write-plan branch's head its create and update are unconfirmed and serve nothing a list could show. Before
that head (at `f2b95351`), when a list taken after the delete still confirmed them, the same comparison moved Komga
from 94.7% to 95.2%: three list reads after creates agreed and two more differed only in where the created collection
was placed. None of the other five environments has a list tool with both kinds of line and a served write on its type.
## Review round
The branch merged the write-plan branch at 73c0e9b5 and 6d28aa78 and main at 4dfa1c67. Six of Greptile's eight
findings were in the write-plan branch's code and were fixed there. This branch fixed the other two:
- a view with whole lines takes its counters from them, and each line updates only the counters its own recording
counted, so a partial page no longer drops a whole line's total;
- a failed item check that takes an answer with no entity drops the writes that claimed it from its collection, as an
absence does, so a whole list cannot confirm the create.
Both new tests fail on the previous head. Over the 50 published captures, the merges changed no view or write plan,
and these two fixes add one counter each to BookStack's pages (`total`) and Linkding's tags (`count`), both views with
a whole line beside partial ones. Served write tools stay at 31. The six environments compare exactly as in the table
above, step for step. The gates passed again.
A second round merged the write-plan branch at 43d98ea9, which carries main d8a9673f and that branch's fixes for the
four findings Greptile raised here against its code. Its page cap applies on every line that lists its whole
collection: a call naming such a page that the collection has outgrown answers from its recording, and the gate skips
such reads. Over the 50 captures no view or write plan changed and served write tools stay at 31; the six environments
compare exactly as before.
A third round merged the write-plan branch at 264ce410. Greptile's finding here, that a `_start`–`_end` range escaped
the page cap, was in that branch's code and was fixed there: the range's width bounds a page as `limit` does, so a
whole line naming a range the collection has outgrown answers from its recording, and the gate checks nothing by it.
The merge also brings that branch's other fixes: unseen writes stay pending, later creates follow their sequences, and
later document writes stay at their object. Over the 50 captures no view or write plan changed and served write tools
stay at 31; the six environments compare exactly as before.
It then merged that branch at 0ae64400 and 6257de93: an update's identity member never takes a rule, a page size of
zero bounds nothing, and the paging rules move to `environmentStatePaging.ts`. Over the 50 captures again no view or
write plan changed, and the six environments compare exactly as before.
A fourth round merged the write-plan branch at 466ed8b4, which fixes four findings Greptile raised here against its
code: an update whose observation drops a field is refused, entities are named as serving names them, a later
create's generated values must keep their forms, and a derived state too large to load back is not served. The page
cap here now uses that branch's `pageBound`. Over the 50 captures no view or write plan changed and served write tools
stay at 31; the six environments compare exactly as before. It then merged 7cef2fb2, whose fixes settle two more findings Greptile raised here against that branch's code: zero
page sizes erasing positive bounds, and interference timed by a tool's call on another collection. Over the 50
captures again no view or write plan changed, and the six environments compare exactly as before.
@@ -1,14 +0,0 @@
# Implementation plan
1. **Query module.** A domain module holds the roles, explains one line (trying roles by parameter name, filters and
inert for any parameter, at most 256 combinations), merges lines, evaluates a query over entities, and renders an
answer with counters and totals.
2. **Gate.** The list plan learns the query from the lines that are not whole, reading each body once for its listed
identities, role choices and counts; demotes a line whose envelope or fields do not reproduce; and adds `query` to
the view.
3. **Write gate.** A read on a query line is checked against the query over the replayed state, covering the
collection only for sort- and page-only answers that hold every match.
4. **Serving.** Line selection moves to its own module and gains the query line; list answers choose whole,
query or recorded members and render totals.
5. **Tests and docs.** Unit, domain and serving tests; the environment-state and agent-environment docs and the
analysis-view tool description.
@@ -1,92 +0,0 @@
# Answer list filters, search, sorting and paging from the state
Issue: https://github.com/morluto/rea/issues/4933
## Outcome
Agents list, filter, search and sort constantly. A list view answered a recorded request line from the state only when
that line listed the whole collection; any other line, such as `?shelf=a`, `?q=tide` or `?orderBy=name`, kept the
members it recorded, and a call with a value no line recorded replayed whichever recording was closest. A filtered
list therefore never showed what a write created or changed, and a search for anything new answered with an
unrelated recording.
A list view now learns what each of its query parameters does, from the lines it recorded, and answers those lines,
and calls with new values, by evaluating the query over the live state.
## Learning
For each checked line that does not list the whole collection, the first combination of roles that lists exactly what
the line recorded, from the collection's initial entities, explains it:
- `filter` on a field every listed item holds the value in: equal as text, or in an array directly or as an object's
`id`, `slug` or `name`;
- `search` for plain substring terms over the string fields the term matched in the listed items, ignoring case (URL fields only for an item
nothing else matched); an empty term matches everything, and a term that matched no field leaves the parameter inert
until another line's term does;
- `sort` by the field the value names, with `-` or an `asc`/`desc` suffix, and `direction` for a separate `asc`/`desc`
(or `ascending`/`descending`) parameter: numbers by value, text ignoring case, null last ascending, ties (case-only differences included) in state
order; an empty selection needs no sort;
- `limit`, `offset` and `page` (counted from 1 or 0 only when the line distinguishes them) for paging; zero or a negative limit
lists every match;
- `inert` for a parameter that changes nothing, valid only for the values it recorded.
Search values resembling operators, field syntax, tags, quotes or wildcards replay rather than asserting a literal-substring result.
Paging values must be safe integers; malformed positions are not learned as inert flags. Identical decoded repeats
of a query value impose one constraint; conflicting repeated values remain unknown. Counter presence belongs to
each response envelope: page counters update where observed, and serving never adds a query-only total to another envelope.
Query totals retain their numeric or canonical decimal-string type. Unknown or differently formatted strings
(such as padded `"03"`) are not assigned an unverified formatting rule and stay as recorded.
`state.source` distinguishes a computed response from recording replay; `replay.exact_match` describes only the
retained source envelope and can be false for a correctly computed new query.
Parameter names decide which roles are tried (`sort` for `orderBy`, `search` for `q`), and any other parameter may be a
filter or inert. A name asking for an order in any common spelling (`_sort`, `sort[]`, `sort[0][field]`, `sorters[...]`,
`sort-column`, `sortKey`, `orderBy`) is only a `sort`; a direction name (`_order`, `sortDirection`, `dir`) given a direction
is only a `direction`, and given anything else is an ordinary parameter; `reverse` is never inert unless false. The same
vocabulary decides which lines set a collection's initial order (see the state view). No two parameters of one call take the same `sort`, `direction` or paging role: the answer would
depend on which applied last, and serving supplies a call's values in name order rather than as recorded, so such a
combination explains no line and such a call replays its recording. A line with more than 12 query parameters is left
unexplained, which bounds the search; names such as `__proto__` are kept as the query's own members. The lines' roles
merge: lines that disagree drop the parameter, inert values gather, search fields unite. A filter on a field not
named like its parameter (`shelf`, or `shelf_id`, for `shelf`) can match by coincidence, so it stands only when lines
giving the parameter two different values agree on it; otherwise the parameter takes no role. The merged query keeps the
lines it reproduces, envelope and fields included; any other line keeps its recorded members. The view's `query` names
the roles, those lines, and the envelope members that count every match before paging (`totals`), top-level or one
level down in a paging object (`/pageInfo/totalRows`); a `number`-of-items member such as `numberOfElements` counts the
page.
## Serving and the write gate
- A call that names a query line exactly, or whose every query argument has a role (an argument-less call keeps
answering on a whole line), is answered by evaluating the query over the state, in the envelope of a query or whole
line of its collection, with counters at the number listed and totals at the number matched. The answer's state
provenance says `membership: "query"`.
- A value an inert parameter never recorded, or a parameter without a role, replays its recording as before.
- The write gate checks a read on a query line, or one whose every query parameter has a role on a line it did not
name, against the query over its copy of the state, as serving answers it: on the line replay ranks first, by the
most verbatim path values, then the most query values the read shares, then recorded order. Only a line whose
parameters all sort or page, and whose answer holds every match, covers the collection; any other covers the
entities it lists and those the line or the read listed that the state no longer holds, so a filtered list shows
whether a delete or create took effect without speaking for the rest of the collection. A failed read also covers
the held entities it listed that the answer leaves out, as a write may have moved them out of it. A read on a line
it did not name counts as gone only what it listed itself, since the line lists another call's members. A read with
no query answered on a query line, as serving does when no whole line fits, is checked against that line's recorded
members, as serving lists them. A read on a line that keeps its recorded members is compared with the totals it
recorded, as serving answers it. A read on a line it did not name is compared in its own envelope: that line's
envelope, such as a `next` link naming the line's own values, comes from another call, so it says nothing of a
write. A read whose query applies a sort shows where a create put its entity only when the sort leaves that entity
tied with another, and an unsorted one only when more than its entity matches, so only then does it fix the create's
insert position.
The roles are inferences from recorded behaviour and are stated as such. Nothing changes for a list whose lines all
list the whole collection, or that no role explains.
## Acceptance
- Unit tests: each role found from a line, including filters on arrays and object ids, search ignoring URLs, sort
spellings and nulls, paging by offset and by page, inert values; merging lines; values a role cannot apply.
- Domain: a tool recorded whole, filtered, searched, sorted and with a flag learns all four, and a create the filter
later lists is confirmed.
- Serving: after a served create, new filter, search and sort values list it; an unrecorded inert value replays.
- Measured: the fifty published captures' learned queries and write verdicts, and the six environments compared with
their applications, before and after.
@@ -1,11 +0,0 @@
# Tasks
- [x] Explain recorded list lines with filter, search, sort, direction, paging and inert roles.
- [x] Merge roles across lines and keep the lines the query reproduces.
- [x] Count matches before paging in the envelope's totals.
- [x] Check reads on query lines in the write gate.
- [x] Serve query lines and calls with new values from the state.
- [x] Add unit, domain and serving tests.
- [x] Document list queries.
- [x] Measure the published captures and the six environments before and after.
- [x] Run static, formatting, duplication, documentation and test gates.
@@ -1,233 +0,0 @@
# Verification
## Maintainer integration, 2026-10-22
Review of `62a9adf6c` found one attributable retry-coverage defect: a successful
insertion-order retry returned only a boolean, so confirmation and pending-write
cleanup still used the failed query page's covered entities. Two deterministic
guards failed (2 failures/82 passes): an unseen update was falsely confirmed,
and a later actual item read could no longer confirm it. The retry now returns
its successful `CheckOutcome`; guards, targets, exercised writes, interference,
placement and cleanup use that result. No duplicate post-retry analysis is added.
All 623 adjacent source tests, three 161-test stability runs, 8 compiled served
workflow boundaries, pinned static/build/docs/9 README checks and native public
pagination pass. Independent targeted Codex source review reports no definite
remaining defect. Public sample: 20.19s wall/28.63s CPU/490.31MiB sampled family
RSS, no observed descendants left. Earlier CI `39776472358` passed on `62a9adf6c`,
but cannot replace CI for the subsequent correction. Live application-write
fidelity remains unverified; the failed-candidate policy already in main is
unchanged, not a newly qualified rollback guarantee.
Representation cross-check found and reproduced one further stale counter on
`1c9bb2e7`: canonical string total `"3"` remained `"3"` after removing an entity
(one failure, 42 passes). Query-total interpretation now has one shared owner for
inference and rendering, preserving number versus canonical decimal-string type.
Unknown, padded, nonintegral or unsafe representations stay unmodeled/recorded;
no display convention is guessed. The updated 621-test source batch and pinned
typecheck/lint pass. The 102 query/write tests pass three consecutive runs, as do
build, docs/9 README, format and native held-out pagination. Independent targeted
Codex source review found no definite remaining format defect. This later public
run took 20.13s wall/28.72s CPU/492.53MiB sampled family RSS, all observed children
exited; it must not be hidden by the earlier faster runs or called a speedup.
Historical counts below are pinned to their stated heads.
Latest-main integration: main advanced to `e93e3b1e7` (APK signing declarations).
Merged it without dropping that feature; the sole conflict was the shared tool
description, resolved from main with only the existing list-query clause added.
The integrated tree passes all 619 adjacent source tests, pinned typecheck/lint,
build, docs/9 README checks and format validation. All 80 CLI/MCP/schema boundaries
also passed on `02ff6304d` before this main merge. An interleaved pre-merge docs
attempt saw stale generated skill output, and format saw the temporary conflict;
both attempts are retained and the completed integration checks pass. They are
not attributed to a defect in main. Fresh-head CI and compiled schema verification
remain necessary. Earlier CI run `39773075218` succeeded on `665ec74c6`, not on
the subsequent corrections or integration.
Independent read-only Codex review of `665ec74c6` found one additional omission
case: intersecting query-total names discarded a valid total when another envelope
omitted it. A new service guard failed on that head (one failure, 41 passes).
The producer now gathers supported totals and rejects actual contradictory counts,
not absent members; the existing projection guard preserves omission. The updated
527-test adjacent batch passes, including deleting a locally loaded entity and
observing the remaining total, plus an explicit contradictory-count control.
This review was source-derived until the regression was run; no live application
mutation was used. The original 618-test/80-boundary counts below describe the
prior reviewed head, not a newly invented final-head run.
The historical contributor runs below are not newly executed checks. This integration
uses main `2c3dd946d` and contributor head `30e90fc64`, retaining main's zero-position
whole-list guard and shared path decoder. New deterministic guards reproduced five
failures before correction: unsupported search syntax, identical repeated constraints,
stale query-only counts, and ambiguous empty-page membership. They now pass. Related
cleanup gives decoded single-valued queries one owner, preserves per-envelope counter
omission, and uses safe numeric precision instead of a nine-digit paging limit.
Executed with pinned Node 24.18.0/npm 11.16.0 on Linux: 526 adjacent source tests,
92 catalog/schema/server source tests, 80 public CLI/MCP/schema boundary tests, and 9 README
checks; typecheck/lint, runtime build, docs and format checks passed. Compilation is
not evidence of live deep-provider behavior. The 99 query/write regressions also
passed three consecutive runs; reordered constraints and equivalent encodings are
covered without weakening conflicting-value or whole-page assertions.
Real-data oracle: five read-only GitHub labels observations, including a repeated
complete collection to check snapshot stability. Only three requests enter the HAR;
the native `per_page=3&page=2` response is held out. CLI and MCP views agree; serving
returns the exact three native label facts with Evidence, and reordered query names
and three warm reads agree. Main needs replay plus a full-list read/client slice;
the query model needs one read. Structured replies total 13,282 versus 1,383 bytes;
catalog discovery is 1,057 versus 1,090 bytes after provenance clarification.
| Completed task | Wall seconds | CPU seconds | Sampled family RSS MiB |
| ------------------------------------------------------- | -----------: | ----------: | ---------------------: |
| Main public workflow | 10.01 | 15.46 | 490.16 |
| Candidate public workflow, before catalog clarification | 10.33 | 16.19 | 495.90 |
| Main plus actual Codex task | 31.55 | 22.56 | 958.68 |
| Candidate plus Codex, original catalog | 31.09 | 18.77 | 1,006.82 |
| Candidate plus Codex, clarified catalog | 27.65 | 19.56 | 952.25 |
| 526-test source batch | 8.75 | 20.64 | 1,513.68 |
RSS is a 500 ms PID/start-identity process-family sample, not a kernel peak or hard
cap. Fresh runtime processes are separate from three later warm calls; OS/dependency
caches and host load are uncontrolled. No speedup or cache claim follows from these
single runs. All observed descendants exited. Node heap allowance was 2 GiB, 1 GiB
for runtime/model children; no ambient environment was persisted.
Actual Codex CLI (`gpt-6.1-sol`) returned correct IDs, names, Evidence and local/not-live
semantics in all three sessions. Main used two calls and 94,649 input tokens
(66,816 cached), 246 output. Candidate initially still made two calls: 79,752 input
(59,904 cached), 284 output. After clarifying that `state.source`, not
`replay.exact_match`, identifies computed answers, the unchanged prompt used one
call: 53,308 input (46,848 cached), 205 output. These are whole-session usage,
including common runner context, not reply-byte token estimates or a universal
agent-efficiency guarantee. Raw prompts, traces, exits and measurements were retained
locally, including intermediate failed test/typecheck attempts.
No GitHub mutation, live-application write fidelity, full fifty-capture census,
exhaustive search-language support or real deep-provider qualification was performed
in this integration. Unchanged-main create-response and ignored-write-query findings
are tracked separately in #6262 and are not claimed repaired by this PR.
Verified commit: 6db41d29 (this branch before this file, with #5787 and the write-plan branch's head `fe8ab584` merged in). Executed on macOS with Node v22.23.1 (the repository pins 24.18.0 in `.nvmrc`, which was
not installed); the probes were recorded against the live applications on six disposable Linux VMs.
## Gates
- `npm run build:cached`, `npm run check:fast` (typecheck and lint), `npm run format:check`, `npx knip`,
`npm run scan:todos`, `npm run docs:check`, `npm run verify:test-discovery` and `npm run mcp-catalog:check`: passed.
- `npm run jscpd`: 3.44% duplicated lines over 3650 files, under the 3.5% gate.
- `npx vitest run --project domain --project services`: 7630 passed, 5 pre-existing skips.
- `npm run test:prepare`, then `npm run test:focused --` the environment serve and export CLI boundaries, the serve
and served-writes MCP boundaries, the analysis-view CLI and MCP boundaries, the compact input schema boundary and
tool schema validity: 8 files, 78 passed.
New tests: `environmentStateListQuery` (9 unit tests: each role found from a line, including filters on arrays and
object ids, search that leaves out URLs, sort spellings and nulls, paging by offset and by page, inert values, a filter
that excludes nothing kept inert, merging lines and refusals), one domain test in `environmentStateWrites` (a tool
recorded whole, filtered, searched, sorted and with a flag learns all four, and a create the filter later lists is
confirmed) and one serving test in `environmentStateWriteAnswer` (after a served create, new filter, search and sort
values list it; an unrecorded inert value replays).
## Fifty published captures
The environment-state view ran over the 50 published captures with each manifest's template rules, on builds with and
without this change (both with the prefix-variance branch merged, which some manifests need).
- 161 list views in 37 environments learn a query, and 223 checked lines are now answered by evaluating it. Roles
learned: 27 filters, 37 searches, 35 sorts, 26 directions, 66 limits, 32 offsets, 25 page parameters and 220 inert
parameters (each valid only for its recorded values).
- No other view changed shape and every write verdict is unchanged (31 served write tools).
## Six environments against their applications
The six environments of the fidelity comparison (NetBox, Komga, Mealie, n8n, Shlink, self-hosted Sentry) were compared
with their applications by `environment-compare`, with and without this change, on the comparison's probes and the
held-out sessions recorded since: NetBox 98.5%, Komga 91.5%, Mealie 94.0%, n8n 71.6%, Shlink 87.1% and Sentry 24.5%,
unchanged. Those probes repeat the capture's own query values, which recorded members already answer, so they cannot
show this change.
New held-out probes were therefore recorded against Komga and Mealie, the two applications whose list views learned
queries a new value can exercise, each restored from its snapshot first. After the capture's read-only prefix (so the
driver learns the application's ids), each learned query was called with values no recording used: other search terms
and filter values drawn from the seeded entities, the other sort direction, a page size of 1 and the second page.
| Application | Query calls | Exact before | Exact after | Right entities in the right order, before | After |
| ----------- | ----------: | -----------: | ----------: | ----------------------------------------: | ----: |
| Mealie | 38 | 2 | 17 | 2 | 38 |
| Komga | 9 | 0 | 0 | 0 | 8 |
Every Mealie call now lists the entities the application lists, in its order, where 36 of them listed the recorded
members before: sorts in the other direction (9) and new recipe searches and category filters (6) now match exactly.
The calls that still differ, and 8 of Komga's 9, differ only in paging members of the envelope: `per_page`, `page`,
`total_pages` and `next`/`previous` (Komga's `pageable` and `totalPages`) keep the base line's values when a call asks
for another page size or page. One Komga search term matched more series than the learned `name`/`url` fields, since
Komga also searches fields the list does not show. Over the whole probe Mealie went from 133 to 148 of 171 steps.
## What a run found
The first census learned Komga's `unpaged=false` as a filter on a field that is false for every entity, so `true` would
have emptied the list. A filter that excludes nothing is now inert, and a parameter filters only where a line shows it
excluding something: 37 of the census's 64 filters became inert values this way. A `-name` sort value matched the field loosely before its sign was read, so it sorted ascending;
the sign is now read first.
## Review round
The branch merged the list-lines branch at de13b0c5, which carries the write-plan branch through 43d98ea9 and main
d8a9673f. The gate's line selection, moved here to `environmentStateCheckedLines.ts`, takes the newer rules there, and
serving answers a whole line's outgrown page from its recording before the query selection. It also fixed seven
findings Greptile raised on this branch:
- a sort of an emptied collection answers no entities;
- an empty or unmatched search term stays inert;
- the gate checks a read with new query values as serving answers it;
- a recorded-member line keeps its recorded totals in the gate;
- a line with more than 12 query parameters is left unexplained, bounding the search;
- `__proto__` and similar names stay the query's own members;
- case-only ties sort in state order.
Each new test fails on the previous head. The partial-page counter test from the list-lines branch now expects the
page, a query line here, to answer from the state with the state's total.
The census on this head, with the fidelity branch's compare command merged in as before, at first served 29 of 183
writes, two fewer than at d5a07e7a. Airbyte's `GET /sources?workspaceIds=…` names a workspace no line recorded, so the
gate now checked it on the other workspace's line, whose `next` link names that workspace. The read listed the right
sources, but with no write exercised the failure marked the create and patch before it as side effects, and tainted
the created source so the read after its delete went unchecked. A read on a line it did not name is now compared in
its own envelope, which a test that fails on the previous head covers. The census again serves 31 of 183, every
verdict as at d5a07e7a. Its 160 query views (161 before) differ from d5a07e7a only as the findings intend:
- empty search terms are inert in Keycloak, PhotoPrism's albums and labels, Tandoor's keywords and Umami;
- Gitea, Grafana and Tandoor's units drop a search term that matched no shown field, with the line that carried it
(Tandoor's units keep no query);
- PhotoPrism's photo query leaves line 199 and its 17 parameters unexplained, and learns lines 225 and 226 instead;
- the list-lines merge adds Bookstack's `total` and Linkding's `count` counters.
The six environments compare as before: NetBox 472 of 479 steps, Komga 549/600, Mealie 422/449, n8n 199/278, Shlink
176/202 and Sentry 91/372.
A second review round merged the list-lines branch at c68c63be, which carries the write-plan branch through 6257de93:
an update's identity member never takes a rule and a page size of zero bounds nothing, fixing two findings Greptile
raised here against that branch's code, and the paging rules move to `environmentStatePaging.ts`, which this branch's
line selection now imports. It also fixed three findings in this branch's gate:
- a read with no query answered on a query line is checked against that line's recorded members, as serving lists
them, rather than against every entity;
- a query read on a line it did not name counts as gone only what it listed, so it cannot confirm a delete of a book
that line listed;
- a read whose query applies a sort no longer fixes a create's insert position, so a later whole list can still try
another rule.
Each new test fails on the previous head. Over the 50 captures every view and write verdict is as on the previous head,
and the six environments compare exactly as before.
It then merged the list-lines branch at ed4b6dbb, which carries the write-plan branch through 466ed8b4: entities named
as serving names them, interference weighed per write, a zero page size bounding nothing only where a recording listed
items under it, and the other fixes of that branch's fifteenth round. Over the 50 captures every view and write verdict
is again as before, and the six environments compare exactly as before.
A third review round merged the list-lines branch at 8eea9f6d, which carries the write-plan branch through 7cef2fb2,
and fixed Greptile's finding on the second round's sort rule: a sorted read whose values tie shows the state's order
among them, so it still fixes a create's insert position, and a later whole list can no longer move the create where
that read showed otherwise. Its test fails on the previous head. Over the 50 captures every view and write verdict is
as before, and the six environments compare exactly as before. A follow-up narrowed it per entity: a sorted read fixes a create's position only when the
sort leaves the created entity itself tied, so a tie between other books no longer locks it. It also merged
the list-lines branch at 27dd6062, carrying the write-plan branch through 45a5c8b9.
@@ -1,29 +0,0 @@
# Implementation plan
1. Lift the api-surface accumulator's shared pieces into
`webNetworkRouteTemplates.ts` (format rules, media-type essence, request-line
and query-name readers, route scanning, byte allowances) and an abstract
`WebNetworkProjectionAccumulator` (retained/temporary budget, admission,
limitations) with `admitHarCaptureParent` for the shared parent guards, so
both grouping views own one interpretation.
2. Add `environmentManifestRules.ts` as pure functions: the opt-in template
rules, re-bucketing and sibling merging, parameter naming, path templates and
deterministic tool names.
3. Add `EnvironmentManifestAccumulator.ts`: per-record pointers, group state,
primary-origin selection, body-shape parsing through `parseJsonObject` with
top-level key types only, without walking nested values, exclusion reasons,
fixed unknowns and the finished manifest fields.
4. Add `environmentManifestView.ts` with the strict request schema (defaults
applied in the echoed view), the result fields and the projector; register
the kind first in `projectAnalysisView`, extend the result union and
`UnsignedAnalysisView`, and wire the accumulator and confidence rule in
`AnalysisViewService`.
5. Publish the `inspect_analysis_view` description and a fixture-generated
example; port the Grafana-shaped HAR into a source-owned TypeScript builder.
6. Cover domain, accumulator budget, service, MCP boundary, CLI boundary and
acceptance behavior; extend the real-capture verifier; document the view in
the capture guide, the contracts reference and the authored skill.
No new tool, provider, side effect or network activity is introduced. The
manifest is a projection of already retained Evidence; replaying or serving it
is deferred.
@@ -1,67 +0,0 @@
# Environment manifest view from web network captures
Issue: https://github.com/morluto/rea/issues/4933
## Outcome
`inspect_analysis_view` accepts `view: {"kind": "environment-manifest"}` for
retained HAR Evidence and projects the primary origin's recorded request lines
into a replayable tool surface: deterministic tool names, path templates,
parameters, observed query names, value-free body shapes, status and
content-type sets and record pointers, with excluded groups, three fixed
unknowns and the shared projection representation budget. This increment adds
the view kind only; serving and exporting an agent environment from the
manifest are later increments.
## Requirements
- Accept only `inspect_web_network_capture` HAR parents; refuse native
mitmproxy, SAZ and qlog parents, and parents whose Evidence does not record
`sensitive_value_count: 0`, with the same typed unsupported errors as the
api-surface view.
- Without opt-in rules, every tool template must equal the api-surface template
of the same group; the four format rules always apply with `basis: inferred`.
- Apply `after-uid-literal`, `opaque-token` and `sibling-variance` only when
listed, each at most once, in that order. With `sibling-variance` selected,
fold literal siblings within its comparison scope into existing opt-in
parameters unless they are stop words, whichever was recorded first. With only
`opaque-token`, a non-opaque literal remains a separate tool. Never fold a
literal into a format-rule parameter or template a stop word;
`sibling-variance` compares routes of at most 32 segments and the manifest
states when a route exceeded that.
- Derive tool names from the method and route literals deterministically, at
most 60 characters, unique within one manifest.
- Derive `body_shape` for `POST`, `PUT` and `PATCH` from the tool's earliest
record when it carries a JSON-typed request body, as top-level key types
only without walking nested values; copy no header, cookie, query or body
value anywhere in the result.
- List records as pointers (`ordinal`, `method`, `path`, `status`,
`content_type`) and excluded groups with reason `other-origin`,
`ui-page-or-asset` or `non-json`. A write group (`POST`, `PUT`, `PATCH`,
`DELETE`) whose every response had no body (a 204 or 205, an empty text or a
recorded size of zero) and at least one succeeded is kept whatever its content
type: the empty reply is its answer. A missing body text alone does not count,
as it may be a body the capture did not keep.
- Mark the Evidence inferred whenever any tool or excluded group is templated,
derived otherwise; keep the parent's authority.
- Admit the capture clone, the inline envelope, every retained pointer, group,
route part, observed value, query name and body-shape key before allocation,
and charge body parsing as temporary bytes, within the existing 96 MiB budget.
## Acceptance and limits
A source-owned Grafana-shaped HAR fixture (28 recorded exchanges on two
origins) drives domain, service, MCP, CLI and acceptance coverage. Without
rules the templates equal the api-surface grouping; with all three rules the
fixture yields `/api/dashboards/uid/{uid}`, `/api/folders/{uid}` folding
`general`, `/api/plugins/{plugin_id}/settings` and
`/api/datasources/uid/{uid}/health`. A published contract example is
reproduced byte-for-byte from fixture bytes through the real decoder and view
service. The view performs no network activity and replays nothing; it does
not establish handler identity, schemas, authorization or state transitions.
## Deferred issue criteria
Serving a manifest over streamable HTTP, exporting an agent environment from a
manifest and the hosted verification lane are later independent increments of
#4933. This PR must reference rather than close the whole issue.
@@ -1,12 +0,0 @@
# Tasks
- [x] Record the view contract, requirements and deferred increments.
- [x] Factor shared route, media-type and budget helpers out of the api-surface
accumulator without changing its behavior.
- [x] Implement the opt-in template rules, naming and manifest accumulator.
- [x] Register the `environment-manifest` kind, result schema, service wiring and
confidence rule.
- [x] Port the Grafana-shaped HAR fixture and publish a reproducible example.
- [x] Add domain, service, MCP, CLI and acceptance coverage.
- [x] Document the view in the capture guide, contracts reference and skill.
- [x] Run static, formatting, duplication, documentation and test gates.
@@ -1,186 +0,0 @@
# Verification
Verified base: 18aa9af2b2c26fd114113dd39528a91224801840 (fetched main).
Executed on the implementation worktree after `npm ci`, `npm run build` and
`npm run test:prepare`; every check below ran as written in this pass. The
built-group projects and the built-CLI checks ran against a `dist/` rebuilt
after the last source change.
- `npm run check:fast`: typecheck and lint passed (2 tasks successful).
- `npm run format` then `npm run format:check`: all 4028 matched files use the
correct format.
- `npx knip`: ok (exit 0, no unused files, exports or dependencies reported).
- `npm run check:ci:tasks`: typecheck, lint:built (3730 files, 0 errors), format:check, knip,
metadata:check, jscpd (3.35% duplicated lines over 3140 files and 2581
clones, under the 3.5% gate) and the tech-debt marker scan passed (8 tasks,
3 replayed from this worktree's cache).
- `npm run docs:check`: the six built documentation checks and the README
consistency conformance test (5 tests) passed; no tracked generated file
changed.
- `npx vitest run --project domain --project services` (full source group):
312 files, 5412 tests passed, 3 pre-existing skips.
- `npx vitest run --project cli-boundary` (full project): 111 files; 659 tests passed, 2
pre-existing skips, 8 failed in three files that drive no analysis-view
command (`closedStdout`, `commandFinalizationCancellation`,
`javascriptApplicationJsonOutput`). Re-run in isolation on this worktree the
three WASM interrupt cases and the four JavaScript JSON-output cases passed
and only `closedStdout` "stops quietly when the reader closes during streamed
JSON" (`inspect-sqlite-database`) exited 1 instead of 141. The same three
files run on a clean export of 18aa9af2 (`git archive`, fresh `npm ci`,
`npm run build`, `npm run test:prepare`, nothing from this slice) reproduced
exactly that one failure and passed the other 16, so none of the eight is
attributable to this slice and none was changed here.
- `npx vitest run --project mcp-boundary` (full project): 153 files passed, 2
pre-existing file skips; 901 tests passed, 7 pre-existing skips, no failures.
- `npx vitest run --project acceptance` (full project): 123 files passed, 1
pre-existing file skip; 608 tests passed, 13 pre-existing skips, no failures.
- Built CLI end-to-end on the 28-record Grafana-shaped capture:
`inspect-web-network-capture ... har --format json` then
`inspect-analysis-view` with `environment-manifest`, with and without the
three opt-in rules, and with `api-surface`, twice each. Without rules the 22
tool templates plus the 3 primary-origin exclusions equal the 25 api-surface
groups on that origin and every `path_template` equals its
`api_surface_template`; with rules `/api/dashboards/uid/{uid}`,
`/api/folders/{uid}` (observed values `fg1jo91e57e2ob` and `general`, records
12 and 13), `/api/plugins/{plugin_id}/settings` and
`/api/datasources/uid/{uid}/health` appear across 19 tools with 13 templated
groups; `normalized_result` and `evidence_id` are identical across the two
runs of each view; records carry only pointer keys; no recorded body or query
value appears; three unknowns and `view_digest` are present; confidence is
`inferred` with authority `historical-reference`.
- Built CLI on the same capture extended with `GET /api/teams/search` and
`GET /api/teams/mine` (30 records), all three rules selected:
`/api/teams/{numeric}` keeps observed value `1` only and `get_teams_search`
and `get_teams_mine` stay their own tools; 21 tools, 13 templated groups.
## Independent review
Findings repaired at their owning boundary:
1. A `__proto__` key in a recorded JSON body became a prototype rather than an
own property, and the schema clone then dropped it silently. The manifest
accumulator builds body shapes with `Object.fromEntries`, omits that key and
states the omission as a limitation; a domain regression covers it.
2. The contract example carried a readonly tuple that the mutable JSON example
type rejects; the example keeps a literal-typed mutable tuple.
3. Folding a literal sibling into an already templated position took the parts
of the earliest group, so a literal recorded before the token kept its
literal, dropped the parameter and claimed the token's record under a
template it does not match. `mergeGroups` now takes the templated group as
the shape for parts while the earliest group still names
`api_surface_template`, `body_shape` and record order; a domain regression
with the literal recorded first covers it.
4. The request-body parse accepted `text/plain` and `text/markdown` bodies; it
accepts only `application/json` and `application/*+json`, and the capture
guide states the earliest-record rule; a domain test covers both media
types.
5. A repeated entry in `template_rules` was accepted, echoed and hashed into
`view_digest` while the accumulator deduplicated it; the request schema
refuses repeats with `template_rules must not repeat a rule`.
6. The sibling-variance fold-in absorbed a non-conforming literal into a
parameter produced by one of the four format rules, so `/api/teams/mine`
became an observed value of `/api/teams/{numeric}` and the published rule no
longer described every observed value. Fold-in is restricted to parameters
produced by the opt-in rules; literal siblings of a format-rule parameter
stay their own tools or merge among themselves under `sibling-variance`
only when identifier-like. A domain test with `/api/teams/1`,
`/api/teams/2`, `/api/teams/search` and `/api/teams/mine`, the capture
guide and the spec state the rule; the built-CLI check above exercises it.
## Hosted lane
- `real-web-network-captures` (hosted ubuntu-24.04, workflow run
https://github.com/earakely-scale/rea/actions/runs/39097105064 on the fork
at 2d95597f) passed with the manifest block of
`scripts/verify-web-network-captures.mjs` executed against the lane's
producer and mitmproxy captures. The first run at 61d35369 failed only in
that block: the refusal check stringified the whole MCP result, so the
declared `[` literal matched the result envelope; the follow-up compares the
parsed refusal as the api-surface branch does.
## Scope and measurement limits
macOS `/usr/bin/time -l`, command accounting only: `npm run check:fast`
reported 5.23 seconds elapsed, 24.20 user and 2.92 system seconds, and
4449140736 bytes maximum RSS; `npm run format` 0.74 seconds elapsed, 4.14
user and 0.73 system seconds, and 223363072 bytes maximum RSS;
`npm run format:check` 0.66 seconds elapsed, 4.03 user and 0.61 system
seconds, and 218759168 bytes maximum RSS; the full source group reported
25.10 seconds elapsed, 67.26 user and 2.72 system seconds, and 2659172352
bytes maximum RSS; `npx knip` 3.68 seconds elapsed, 5.24 user and 0.70 system
seconds, and 865599488 bytes maximum RSS; `npm run check:ci:tasks` 4.65
seconds elapsed, 15.03 user and 4.36 system seconds, and 843333632 bytes
maximum RSS; `npm run docs:check` 3.61 seconds elapsed, 3.81 user and 0.99
system seconds, and 289472512 bytes maximum RSS; the full `cli-boundary`
project 425.66 seconds elapsed, 703.52 user and 206.77 system seconds, and
630456320 bytes maximum RSS; the full `mcp-boundary` project 164.19 seconds
elapsed, 302.85 user and 47.08 system seconds, and 4457529344 bytes maximum
RSS; the full `acceptance` project 960.25 seconds elapsed, 1520.91 user and
520.68 system seconds, and 800063488 bytes maximum RSS. `npx knip` ran while
the `cli-boundary` project was executing, and the clean 18aa9af2 export's
`npm ci`, build and test preparation overlapped the `mcp-boundary` and
`acceptance` runs, so those elapsed figures include host contention. Token usage and full process-family peak are
unmeasured. Local real-tool verification ran on macOS arm64; the hosted Linux lane result is recorded above.
## Automated review findings on the PR (2026-10-18)
Codex and Greptile left seven inline findings on morluto/rea#4954 at
b6d18d23; each was checked against the code and addressed in one follow-up
commit, with a regression test where the behaviour is observable:
- Body shapes walked nested values (both reviewers, P1): `#bodyShape` passed
the text to `inferJsonShape`, whose per-node path copies grow with the square
of depth, so a small deeply nested body could exceed the budget it had
reserved. The reader now parses once and reads top-level key types from the
parsed object; a test feeds a 2,500-level nested body and gets the four
top-level types back.
- Literal route parts were not admitted (Codex, P2): a path of many short
literal segments materialized one part object per segment without a charge.
Every route part is now charged before the group is created; a test shows a
5,000-segment path refused under a 1 MiB budget while a 100-segment path is
retained.
- `sibling-variance` rebuilt a key over the whole route at every position
(Greptile, P1): routes longer than 32 segments are no longer compared, the
manifest states it in a limitation, and a test shows two 39-segment siblings
left unmerged beside a merged short pair.
- `after-uid-literal` templated stop words (Greptile, P1): the rule now skips
them; a test keeps `/api/items/uid/search` literal beside
`/api/items/uid/{uid}`.
- Tool-name suffixes restarted at 2 on every collision (Greptile, P2): the
registry keeps the next suffix per base; a test projects 300 dotted literals
into `get_item` and `get_item_2` through `get_item_300`.
- An exclusion row could lose its templated flag when two groups printed the
same row (Codex, P2): the flag is now the logical or of both. The scenario
needs a literal segment spelled `{numeric}`, which the WHATWG URL parser
percent-encodes in recorded paths, so no capture reaches it; the one-line
defence is kept without a test.
Checks after the change: `oxfmt --check .` clean; `tsc --noEmit` clean;
`npm run lint` and `verify:module-boundaries` clean (the complexity warnings
on `#append` predate the change); `npx knip` no findings; `npm run jscpd`
3.35 % duplicated lines; `scan:todos` none; `verify:test-discovery` 1,580
files once; `vitest run` over the view, accumulator, JSON-shape and contract
example tests 32 passed in 4 files; `vitest run` over the service, CLI and
MCP boundary tests for analysis views 73 passed in 3 files.
A sixth automated finding (Codex) was addressed after the collaborator's
merge of main: `sibling-variance` merged a whole bucket when any one literal
carried a digit, so `/api/items/mine` could be folded into `{item_id}`. The
rule now partitions the bucket and merges only the identifier-like siblings
(each with a digit or colon, or three or more hyphenated names under a plural
literal), leaving the other literals as their own tools; with the rule alone
the fixture therefore keeps `/api/folders/general` and
`/api/folders/fg1jo91e57e2ob` separate, while all three rules still fold
`general` into `/api/folders/{uid}` through the opaque-token parameter. Tests:
the new partition case and the updated single-rule table.
Follow-up mixed-cohort regressions reproduced two omissions on `dd87f54e`
with main `8307ea37`: two coded siblings prevented three qualifying hyphenated
siblings from joining the parameter, and one coded sibling was omitted when
three hyphenated siblings merged. Eligibility now belongs to one Set that
combines both qualifying cohorts before the minimum group size is checked.
The consumer reuses that Set and materializes its merge order once. Three
cases cover both omissions and preserve the three-hyphen minimum when only
two hyphenated siblings accompany coded identifiers; `mine` and `search`
remain literal and every source record remains represented.
@@ -1,18 +0,0 @@
# Plan
1. Move tool naming (`parameterNames`, `pathTemplate`, `toolName`,
`compareTools`) from `environmentManifestRules.ts` to a new
`environmentManifestNames.ts`, so the rules module has room for the rule.
2. Add `prefix-variance` to `TEMPLATE_RULES`. A `prefix-variance` parameter
records the rule it shares (`sharedRule`), which names it and keys it.
3. Add the pass after `sibling-variance`: walk positions in order, index the
opt-in parameters at each position by their preceding parts, template
qualifying literals, then rebucket by naming key, keeping a tool's own rule
for each merged position.
4. Share the 32-segment split between the three comparing passes and list the
segment-limited rules once for the limitation.
5. Document the rule in the view schema description and in
`docs/guides/web/web-network-captures.md`.
6. Tests: shared positions across methods and depths, the spelling condition,
merges that keep a tool's own rule, pairs, format-rule positions and the
segment limit.
Loaded 100 of 362 files, more files were not shown because too many files have changed in this diff. Show more