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
@@ -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.
|
||||
@@ -1,12 +0,0 @@
|
||||
# Tasks
|
||||
|
||||
- [x] Record the view contract, requirements and deferred increments.
|
||||
- [x] Factor shared route, media-type and budget helpers out of the api-surface
|
||||
accumulator without changing its behavior.
|
||||
- [x] Implement the opt-in template rules, naming and manifest accumulator.
|
||||
- [x] Register the `environment-manifest` kind, result schema, service wiring and
|
||||
confidence rule.
|
||||
- [x] Port the Grafana-shaped HAR fixture and publish a reproducible example.
|
||||
- [x] Add domain, service, MCP, CLI and acceptance coverage.
|
||||
- [x] Document the view in the capture guide, contracts reference and skill.
|
||||
- [x] Run static, formatting, duplication, documentation and test gates.
|
||||
@@ -1,186 +0,0 @@
|
||||
# Verification
|
||||
|
||||
Verified base: 18aa9af2b2c26fd114113dd39528a91224801840 (fetched main).
|
||||
|
||||
Executed on the implementation worktree after `npm ci`, `npm run build` and
|
||||
`npm run test:prepare`; every check below ran as written in this pass. The
|
||||
built-group projects and the built-CLI checks ran against a `dist/` rebuilt
|
||||
after the last source change.
|
||||
|
||||
- `npm run check:fast`: typecheck and lint passed (2 tasks successful).
|
||||
- `npm run format` then `npm run format:check`: all 4028 matched files use the
|
||||
correct format.
|
||||
- `npx knip`: ok (exit 0, no unused files, exports or dependencies reported).
|
||||
- `npm run check:ci:tasks`: typecheck, lint:built (3730 files, 0 errors), format:check, knip,
|
||||
metadata:check, jscpd (3.35% duplicated lines over 3140 files and 2581
|
||||
clones, under the 3.5% gate) and the tech-debt marker scan passed (8 tasks,
|
||||
3 replayed from this worktree's cache).
|
||||
- `npm run docs:check`: the six built documentation checks and the README
|
||||
consistency conformance test (5 tests) passed; no tracked generated file
|
||||
changed.
|
||||
- `npx vitest run --project domain --project services` (full source group):
|
||||
312 files, 5412 tests passed, 3 pre-existing skips.
|
||||
- `npx vitest run --project cli-boundary` (full project): 111 files; 659 tests passed, 2
|
||||
pre-existing skips, 8 failed in three files that drive no analysis-view
|
||||
command (`closedStdout`, `commandFinalizationCancellation`,
|
||||
`javascriptApplicationJsonOutput`). Re-run in isolation on this worktree the
|
||||
three WASM interrupt cases and the four JavaScript JSON-output cases passed
|
||||
and only `closedStdout` "stops quietly when the reader closes during streamed
|
||||
JSON" (`inspect-sqlite-database`) exited 1 instead of 141. The same three
|
||||
files run on a clean export of 18aa9af2 (`git archive`, fresh `npm ci`,
|
||||
`npm run build`, `npm run test:prepare`, nothing from this slice) reproduced
|
||||
exactly that one failure and passed the other 16, so none of the eight is
|
||||
attributable to this slice and none was changed here.
|
||||
- `npx vitest run --project mcp-boundary` (full project): 153 files passed, 2
|
||||
pre-existing file skips; 901 tests passed, 7 pre-existing skips, no failures.
|
||||
- `npx vitest run --project acceptance` (full project): 123 files passed, 1
|
||||
pre-existing file skip; 608 tests passed, 13 pre-existing skips, no failures.
|
||||
- Built CLI end-to-end on the 28-record Grafana-shaped capture:
|
||||
`inspect-web-network-capture ... har --format json` then
|
||||
`inspect-analysis-view` with `environment-manifest`, with and without the
|
||||
three opt-in rules, and with `api-surface`, twice each. Without rules the 22
|
||||
tool templates plus the 3 primary-origin exclusions equal the 25 api-surface
|
||||
groups on that origin and every `path_template` equals its
|
||||
`api_surface_template`; with rules `/api/dashboards/uid/{uid}`,
|
||||
`/api/folders/{uid}` (observed values `fg1jo91e57e2ob` and `general`, records
|
||||
12 and 13), `/api/plugins/{plugin_id}/settings` and
|
||||
`/api/datasources/uid/{uid}/health` appear across 19 tools with 13 templated
|
||||
groups; `normalized_result` and `evidence_id` are identical across the two
|
||||
runs of each view; records carry only pointer keys; no recorded body or query
|
||||
value appears; three unknowns and `view_digest` are present; confidence is
|
||||
`inferred` with authority `historical-reference`.
|
||||
- Built CLI on the same capture extended with `GET /api/teams/search` and
|
||||
`GET /api/teams/mine` (30 records), all three rules selected:
|
||||
`/api/teams/{numeric}` keeps observed value `1` only and `get_teams_search`
|
||||
and `get_teams_mine` stay their own tools; 21 tools, 13 templated groups.
|
||||
|
||||
## Independent review
|
||||
|
||||
Findings repaired at their owning boundary:
|
||||
|
||||
1. A `__proto__` key in a recorded JSON body became a prototype rather than an
|
||||
own property, and the schema clone then dropped it silently. The manifest
|
||||
accumulator builds body shapes with `Object.fromEntries`, omits that key and
|
||||
states the omission as a limitation; a domain regression covers it.
|
||||
2. The contract example carried a readonly tuple that the mutable JSON example
|
||||
type rejects; the example keeps a literal-typed mutable tuple.
|
||||
3. Folding a literal sibling into an already templated position took the parts
|
||||
of the earliest group, so a literal recorded before the token kept its
|
||||
literal, dropped the parameter and claimed the token's record under a
|
||||
template it does not match. `mergeGroups` now takes the templated group as
|
||||
the shape for parts while the earliest group still names
|
||||
`api_surface_template`, `body_shape` and record order; a domain regression
|
||||
with the literal recorded first covers it.
|
||||
4. The request-body parse accepted `text/plain` and `text/markdown` bodies; it
|
||||
accepts only `application/json` and `application/*+json`, and the capture
|
||||
guide states the earliest-record rule; a domain test covers both media
|
||||
types.
|
||||
5. A repeated entry in `template_rules` was accepted, echoed and hashed into
|
||||
`view_digest` while the accumulator deduplicated it; the request schema
|
||||
refuses repeats with `template_rules must not repeat a rule`.
|
||||
6. The sibling-variance fold-in absorbed a non-conforming literal into a
|
||||
parameter produced by one of the four format rules, so `/api/teams/mine`
|
||||
became an observed value of `/api/teams/{numeric}` and the published rule no
|
||||
longer described every observed value. Fold-in is restricted to parameters
|
||||
produced by the opt-in rules; literal siblings of a format-rule parameter
|
||||
stay their own tools or merge among themselves under `sibling-variance`
|
||||
only when identifier-like. A domain test with `/api/teams/1`,
|
||||
`/api/teams/2`, `/api/teams/search` and `/api/teams/mine`, the capture
|
||||
guide and the spec state the rule; the built-CLI check above exercises it.
|
||||
|
||||
## Hosted lane
|
||||
|
||||
- `real-web-network-captures` (hosted ubuntu-24.04, workflow run
|
||||
https://github.com/earakely-scale/rea/actions/runs/39097105064 on the fork
|
||||
at 2d95597f) passed with the manifest block of
|
||||
`scripts/verify-web-network-captures.mjs` executed against the lane's
|
||||
producer and mitmproxy captures. The first run at 61d35369 failed only in
|
||||
that block: the refusal check stringified the whole MCP result, so the
|
||||
declared `[` literal matched the result envelope; the follow-up compares the
|
||||
parsed refusal as the api-surface branch does.
|
||||
|
||||
## Scope and measurement limits
|
||||
|
||||
macOS `/usr/bin/time -l`, command accounting only: `npm run check:fast`
|
||||
reported 5.23 seconds elapsed, 24.20 user and 2.92 system seconds, and
|
||||
4449140736 bytes maximum RSS; `npm run format` 0.74 seconds elapsed, 4.14
|
||||
user and 0.73 system seconds, and 223363072 bytes maximum RSS;
|
||||
`npm run format:check` 0.66 seconds elapsed, 4.03 user and 0.61 system
|
||||
seconds, and 218759168 bytes maximum RSS; the full source group reported
|
||||
25.10 seconds elapsed, 67.26 user and 2.72 system seconds, and 2659172352
|
||||
bytes maximum RSS; `npx knip` 3.68 seconds elapsed, 5.24 user and 0.70 system
|
||||
seconds, and 865599488 bytes maximum RSS; `npm run check:ci:tasks` 4.65
|
||||
seconds elapsed, 15.03 user and 4.36 system seconds, and 843333632 bytes
|
||||
maximum RSS; `npm run docs:check` 3.61 seconds elapsed, 3.81 user and 0.99
|
||||
system seconds, and 289472512 bytes maximum RSS; the full `cli-boundary`
|
||||
project 425.66 seconds elapsed, 703.52 user and 206.77 system seconds, and
|
||||
630456320 bytes maximum RSS; the full `mcp-boundary` project 164.19 seconds
|
||||
elapsed, 302.85 user and 47.08 system seconds, and 4457529344 bytes maximum
|
||||
RSS; the full `acceptance` project 960.25 seconds elapsed, 1520.91 user and
|
||||
520.68 system seconds, and 800063488 bytes maximum RSS. `npx knip` ran while
|
||||
the `cli-boundary` project was executing, and the clean 18aa9af2 export's
|
||||
`npm ci`, build and test preparation overlapped the `mcp-boundary` and
|
||||
`acceptance` runs, so those elapsed figures include host contention. Token usage and full process-family peak are
|
||||
unmeasured. Local real-tool verification ran on macOS arm64; the hosted Linux lane result is recorded above.
|
||||
|
||||
## Automated review findings on the PR (2026-10-18)
|
||||
|
||||
Codex and Greptile left seven inline findings on morluto/rea#4954 at
|
||||
b6d18d23; each was checked against the code and addressed in one follow-up
|
||||
commit, with a regression test where the behaviour is observable:
|
||||
|
||||
- Body shapes walked nested values (both reviewers, P1): `#bodyShape` passed
|
||||
the text to `inferJsonShape`, whose per-node path copies grow with the square
|
||||
of depth, so a small deeply nested body could exceed the budget it had
|
||||
reserved. The reader now parses once and reads top-level key types from the
|
||||
parsed object; a test feeds a 2,500-level nested body and gets the four
|
||||
top-level types back.
|
||||
- Literal route parts were not admitted (Codex, P2): a path of many short
|
||||
literal segments materialized one part object per segment without a charge.
|
||||
Every route part is now charged before the group is created; a test shows a
|
||||
5,000-segment path refused under a 1 MiB budget while a 100-segment path is
|
||||
retained.
|
||||
- `sibling-variance` rebuilt a key over the whole route at every position
|
||||
(Greptile, P1): routes longer than 32 segments are no longer compared, the
|
||||
manifest states it in a limitation, and a test shows two 39-segment siblings
|
||||
left unmerged beside a merged short pair.
|
||||
- `after-uid-literal` templated stop words (Greptile, P1): the rule now skips
|
||||
them; a test keeps `/api/items/uid/search` literal beside
|
||||
`/api/items/uid/{uid}`.
|
||||
- Tool-name suffixes restarted at 2 on every collision (Greptile, P2): the
|
||||
registry keeps the next suffix per base; a test projects 300 dotted literals
|
||||
into `get_item` and `get_item_2` through `get_item_300`.
|
||||
- An exclusion row could lose its templated flag when two groups printed the
|
||||
same row (Codex, P2): the flag is now the logical or of both. The scenario
|
||||
needs a literal segment spelled `{numeric}`, which the WHATWG URL parser
|
||||
percent-encodes in recorded paths, so no capture reaches it; the one-line
|
||||
defence is kept without a test.
|
||||
|
||||
Checks after the change: `oxfmt --check .` clean; `tsc --noEmit` clean;
|
||||
`npm run lint` and `verify:module-boundaries` clean (the complexity warnings
|
||||
on `#append` predate the change); `npx knip` no findings; `npm run jscpd`
|
||||
3.35 % duplicated lines; `scan:todos` none; `verify:test-discovery` 1,580
|
||||
files once; `vitest run` over the view, accumulator, JSON-shape and contract
|
||||
example tests 32 passed in 4 files; `vitest run` over the service, CLI and
|
||||
MCP boundary tests for analysis views 73 passed in 3 files.
|
||||
|
||||
A sixth automated finding (Codex) was addressed after the collaborator's
|
||||
merge of main: `sibling-variance` merged a whole bucket when any one literal
|
||||
carried a digit, so `/api/items/mine` could be folded into `{item_id}`. The
|
||||
rule now partitions the bucket and merges only the identifier-like siblings
|
||||
(each with a digit or colon, or three or more hyphenated names under a plural
|
||||
literal), leaving the other literals as their own tools; with the rule alone
|
||||
the fixture therefore keeps `/api/folders/general` and
|
||||
`/api/folders/fg1jo91e57e2ob` separate, while all three rules still fold
|
||||
`general` into `/api/folders/{uid}` through the opaque-token parameter. Tests:
|
||||
the new partition case and the updated single-rule table.
|
||||
|
||||
Follow-up mixed-cohort regressions reproduced two omissions on `dd87f54e`
|
||||
with main `8307ea37`: two coded siblings prevented three qualifying hyphenated
|
||||
siblings from joining the parameter, and one coded sibling was omitted when
|
||||
three hyphenated siblings merged. Eligibility now belongs to one Set that
|
||||
combines both qualifying cohorts before the minimum group size is checked.
|
||||
The consumer reuses that Set and materializes its merge order once. Three
|
||||
cases cover both omissions and preserve the three-hyphen minimum when only
|
||||
two hyphenated siblings accompany coded identifiers; `mine` and `search`
|
||||
remain literal and every source record remains represented.
|
||||
@@ -1,18 +0,0 @@
|
||||
# Plan
|
||||
|
||||
1. Move tool naming (`parameterNames`, `pathTemplate`, `toolName`,
|
||||
`compareTools`) from `environmentManifestRules.ts` to a new
|
||||
`environmentManifestNames.ts`, so the rules module has room for the rule.
|
||||
2. Add `prefix-variance` to `TEMPLATE_RULES`. A `prefix-variance` parameter
|
||||
records the rule it shares (`sharedRule`), which names it and keys it.
|
||||
3. Add the pass after `sibling-variance`: walk positions in order, index the
|
||||
opt-in parameters at each position by their preceding parts, template
|
||||
qualifying literals, then rebucket by naming key, keeping a tool's own rule
|
||||
for each merged position.
|
||||
4. Share the 32-segment split between the three comparing passes and list the
|
||||
segment-limited rules once for the limitation.
|
||||
5. Document the rule in the view schema description and in
|
||||
`docs/guides/web/web-network-captures.md`.
|
||||
6. Tests: shared positions across methods and depths, the spelling condition,
|
||||
merges that keep a tool's own rule, pairs, format-rule positions and the
|
||||
segment limit.
|
||||
Loaded 100 of 362 files, more files were not shown because too many files have changed in this diff.
Show more
Reference in new issue
Block a user