mirror of
https://github.com/morluto/rea.git
synced 2026-11-21 14:05:49 +00:00
docs: remove tracked planning and architecture records (#12856)
This commit is contained in:
1 parent
42b36e200b
commit
a1dec2d2d5
362 files changed
+119
-18521
No files matched your search
@@ -14,7 +14,7 @@ Preserve caller-selected inputs and local evidence, including output, URLs, path
|
||||
|
||||
## Architecture and Cleanup
|
||||
|
||||
Dependencies flow inward: domain semantics and contracts, provider adapters, shared application workflows, then CLI/MCP adapters. Keep engine protocols and provider-specific code out of domain/application layers. See [docs/architecture/architecture.mermaid](docs/architecture/architecture.mermaid) when changing composition.
|
||||
Dependencies flow inward: domain semantics and contracts, provider adapters, shared application workflows, then CLI/MCP adapters. Keep engine protocols and provider-specific code out of domain/application layers. Read the relevant wiring in `src/composition/` when changing composition.
|
||||
|
||||
Give each interpretation and resource a clear owner. Consumers must use that owner's parsed facts rather than reinterpret raw source. Preserve identity, omission, uncertainty, and source evidence across boundaries. Retain ownership of resources whose cleanup failed. Reuse `src/process/` supervision and identity primitives; a PID and executable path alone do not establish ownership after exit or reuse.
|
||||
|
||||
@@ -77,11 +77,11 @@ do not establish fewer tokens or faster analysis.
|
||||
|
||||
## Development
|
||||
|
||||
Treat code as the source of truth for implemented behavior and architecture.
|
||||
Keep specs, implementation plans, task lists, ADRs, and architecture diagrams
|
||||
in issue or pull request discussions or in local drafts outside Git.
|
||||
Use the [documentation directory](docs/README.md) and
|
||||
[authoring guide](docs/development/documentation.md) to find the owning page.
|
||||
Follow the [feature lifecycle](docs/development/documentation.md#feature-lifecycle)
|
||||
to decide whether a change needs a feature record. The authoring guide defines
|
||||
the paths for feature records and architecture decisions.
|
||||
[authoring guide](docs/development/documentation.md) for guides and references.
|
||||
|
||||
Use [.nvmrc](.nvmrc) and `package.json#packageManager` for the pinned toolchain. Cursor Cloud may place older Node.js first on `PATH`; environment setup installs the pinned toolchain under `/usr/local/bin`. Prefix `PATH="/usr/local/bin:$PATH"` before `node` and `npm`.
|
||||
|
||||
@@ -105,7 +105,7 @@ Coordinate expensive checks across agents. If a test unexpectedly consumes heavy
|
||||
|
||||
For tool design, follow [docs/development/tool-design.md](docs/development/tool-design.md): start from the analyst question, reuse existing contracts, preserve caller choices, and return useful evidence inline. Limits must follow real format, protocol, authority, or resource constraints. Account for representation expansion before allocation; derive completeness from examined coverage.
|
||||
|
||||
Choose the scope of a new limit from [analysis settings, limits, and recovery](docs/design/limits-and-recovery.md).
|
||||
Choose the scope of a new limit from [analysis settings, limits, and recovery](docs/reference/limits-and-recovery.md).
|
||||
A registered runtime setting may have an optional launch seed. Per-call and
|
||||
launch-only controls have their own contracts. Report the effective limit and
|
||||
recovery for the control that stopped the work, and document the setting ID
|
||||
|
||||
+9
-13
@@ -10,15 +10,14 @@ and maintenance cost. Keep cosmetic polish with useful fixes; confusing or
|
||||
incorrect user instructions warrant standalone corrections. Collect other
|
||||
cosmetic-only suggestions in an issue rather than separate PRs.
|
||||
|
||||
For selected architectural owners and dependency paths, use the
|
||||
[architecture map](docs/architecture/architecture.mermaid). It is not a complete directory or
|
||||
import inventory. For current provider wiring, start with
|
||||
For provider wiring, start with
|
||||
[`src/composition/binary.ts`](src/composition/binary.ts) for deep candidates and
|
||||
the other `src/composition/` factories for tool services, including
|
||||
[`gpu.ts`](src/composition/gpu.ts) and [`model.ts`](src/composition/model.ts).
|
||||
Live Frida, Cutter, GDB and Rizin construction also uses shared composition
|
||||
factories. For service ownership, availability and catalog declarations, follow
|
||||
the [capability composition guide](docs/capability-composition.md).
|
||||
factories. Start with [capability declarations](src/composition/capabilityDeclarations.ts)
|
||||
for catalog metadata and [service bindings](src/composition/capabilityServices.ts)
|
||||
for construction, availability and cleanup.
|
||||
Production factories construct fresh providers without starting engines or
|
||||
acquiring targets; optional adapter failures must preserve successful peers. Run
|
||||
`npm run verify:test-discovery` after adding or moving tests. Resolved import
|
||||
@@ -28,9 +27,8 @@ It also checks each top-level `src/` unit against its layer in
|
||||
directory must declare one) and against the counted outward, mutual,
|
||||
cross-provider and past-entry imports in
|
||||
`scripts/lib/module-layers.baseline.json`. Application, composition and the
|
||||
adapters import a provider through the entry files it declares in that table
|
||||
([decision](docs/adr/architecture/provider-entry-files.md)); a new entry file
|
||||
widens the provider's public surface. The baseline may only shrink: a
|
||||
adapters import a provider through the entry files it declares in that table.
|
||||
A new entry file widens the provider's public surface. The baseline may only shrink: a
|
||||
change that removes such imports lowers it with
|
||||
`node scripts/verify-module-boundaries.mjs --shrink-layer-baseline`.
|
||||
|
||||
@@ -56,9 +54,8 @@ compare equivalent real tasks before claiming an improvement.
|
||||
|
||||
When adding or changing an MCP tool, follow the [tool design guide](docs/development/tool-design.md) and preserve the canonical contracts and generated catalog.
|
||||
When adding or changing an admission ceiling, budget, or deadline, follow
|
||||
[analysis settings, limits, and recovery](docs/design/limits-and-recovery.md)
|
||||
for ownership, operation snapshots, provider integration, and the steps for
|
||||
adding a runtime setting.
|
||||
[analysis settings, limits, and recovery](docs/reference/limits-and-recovery.md)
|
||||
for the steps for adding a runtime setting and documenting recovery.
|
||||
|
||||
## Reporting issues
|
||||
|
||||
@@ -332,8 +329,7 @@ then rerun the command.
|
||||
## Documentation website
|
||||
|
||||
Use the [documentation directory](docs/README.md) and
|
||||
[authoring guide](docs/development/documentation.md) for document ownership,
|
||||
domain-based feature specifications and architectural decision records.
|
||||
[authoring guide](docs/development/documentation.md) for document ownership.
|
||||
|
||||
The VitePress site uses the Markdown files in `docs/`. Run `npm run docs:dev`
|
||||
for live editing and `npm run docs:preview` to serve an existing build at
|
||||
|
||||
@@ -438,7 +438,6 @@ For exact options, prerequisites and result contracts:
|
||||
- [CLI and Evidence](docs/getting-started/cli.md): commands, provider selection, snapshots, import/export and exit statuses.
|
||||
- [MCP contracts](docs/reference/mcp-contracts.md) and [agent prompts](docs/getting-started/mcp-prompts.md): tool results, sessions and guided investigations.
|
||||
- [Tool catalog](docs/reference/mcp-contracts.md#generated-catalog): generated inventory of tools, providers and CLI commands.
|
||||
- [Roadmap](docs/development/roadmap.md): planned work and capability trackers.
|
||||
|
||||
Report vulnerabilities through [SECURITY.md](SECURITY.md).
|
||||
|
||||
@@ -472,9 +471,8 @@ We'd love your help with REA! [Open an issue](https://github.com/morluto/rea/iss
|
||||
report a bug or suggest a feature, or [send a pull request](https://github.com/morluto/rea/pulls)
|
||||
to improve the code or docs.
|
||||
|
||||
See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and checks,
|
||||
[testing](docs/development/testing.md) for verification lanes, and the
|
||||
[architecture map](docs/architecture/architecture.mermaid) for selected layers and dependency paths.
|
||||
See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and checks. See the
|
||||
[testing guide](docs/development/testing.md) for verification lanes.
|
||||
|
||||
## License
|
||||
|
||||
|
||||
@@ -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,
|
||||
|
||||
@@ -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
@@ -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
|
||||
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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`.
|
||||
@@ -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.
|
||||
@@ -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,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
|
||||
|
||||
@@ -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
|
||||
@@ -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`.
|
||||
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -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
|
||||
|
||||
@@ -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.
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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
@@ -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,
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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;
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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) لمسارات التحقق.
|
||||
|
||||
## الترخيص
|
||||
|
||||
|
||||
@@ -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) за
|
||||
избрани слоеве и пътища на зависимостите.
|
||||
проверки.
|
||||
|
||||
## Лиценз
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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) για τις διαδικασίες επαλήθευσης.
|
||||
|
||||
## Άδεια χρήσης
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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) را ببینید.
|
||||
|
||||
## مجوز
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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 への貢献を歓迎しますしてバグや機能の提案を報告したり、[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)を参照してください。
|
||||
|
||||
## ライセンス
|
||||
|
||||
|
||||
@@ -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` 값을 수정하세요.
|
||||
|
||||
|
||||
@@ -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) എന്നിവ കാണുക.
|
||||
|
||||
## ലൈസൻസ്
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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ță
|
||||
|
||||
|
||||
@@ -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).
|
||||
|
||||
## Лицензия
|
||||
|
||||
|
||||
@@ -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) สำหรับแนวทางการตรวจยืนยัน
|
||||
|
||||
## สัญญาอนุญาต
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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).
|
||||
|
||||
## Ліцензія
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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)。
|
||||
|
||||
## 授權條款
|
||||
|
||||
|
||||
@@ -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:
|
||||
@@ -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.
|
||||
@@ -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))
|
||||
@@ -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.
|
||||
Loaded 100 of 362 files, more files were not shown because too many files have changed in this diff.
Show more
Reference in new issue
Block a user