diff --git a/AGENTS.md b/AGENTS.md index 5611b78db2..8119f534a7 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -14,7 +14,7 @@ Preserve caller-selected inputs and local evidence, including output, URLs, path ## Architecture and Cleanup -Dependencies flow inward: domain semantics and contracts, provider adapters, shared application workflows, then CLI/MCP adapters. Keep engine protocols and provider-specific code out of domain/application layers. See [docs/architecture/architecture.mermaid](docs/architecture/architecture.mermaid) when changing composition. +Dependencies flow inward: domain semantics and contracts, provider adapters, shared application workflows, then CLI/MCP adapters. Keep engine protocols and provider-specific code out of domain/application layers. Read the relevant wiring in `src/composition/` when changing composition. Give each interpretation and resource a clear owner. Consumers must use that owner's parsed facts rather than reinterpret raw source. Preserve identity, omission, uncertainty, and source evidence across boundaries. Retain ownership of resources whose cleanup failed. Reuse `src/process/` supervision and identity primitives; a PID and executable path alone do not establish ownership after exit or reuse. @@ -77,11 +77,11 @@ do not establish fewer tokens or faster analysis. ## Development +Treat code as the source of truth for implemented behavior and architecture. +Keep specs, implementation plans, task lists, ADRs, and architecture diagrams +in issue or pull request discussions or in local drafts outside Git. Use the [documentation directory](docs/README.md) and -[authoring guide](docs/development/documentation.md) to find the owning page. -Follow the [feature lifecycle](docs/development/documentation.md#feature-lifecycle) -to decide whether a change needs a feature record. The authoring guide defines -the paths for feature records and architecture decisions. +[authoring guide](docs/development/documentation.md) for guides and references. Use [.nvmrc](.nvmrc) and `package.json#packageManager` for the pinned toolchain. Cursor Cloud may place older Node.js first on `PATH`; environment setup installs the pinned toolchain under `/usr/local/bin`. Prefix `PATH="/usr/local/bin:$PATH"` before `node` and `npm`. @@ -105,7 +105,7 @@ Coordinate expensive checks across agents. If a test unexpectedly consumes heavy For tool design, follow [docs/development/tool-design.md](docs/development/tool-design.md): start from the analyst question, reuse existing contracts, preserve caller choices, and return useful evidence inline. Limits must follow real format, protocol, authority, or resource constraints. Account for representation expansion before allocation; derive completeness from examined coverage. -Choose the scope of a new limit from [analysis settings, limits, and recovery](docs/design/limits-and-recovery.md). +Choose the scope of a new limit from [analysis settings, limits, and recovery](docs/reference/limits-and-recovery.md). A registered runtime setting may have an optional launch seed. Per-call and launch-only controls have their own contracts. Report the effective limit and recovery for the control that stopped the work, and document the setting ID diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a3c9e66b46..9824faf4e2 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -10,15 +10,14 @@ and maintenance cost. Keep cosmetic polish with useful fixes; confusing or incorrect user instructions warrant standalone corrections. Collect other cosmetic-only suggestions in an issue rather than separate PRs. -For selected architectural owners and dependency paths, use the -[architecture map](docs/architecture/architecture.mermaid). It is not a complete directory or -import inventory. For current provider wiring, start with +For provider wiring, start with [`src/composition/binary.ts`](src/composition/binary.ts) for deep candidates and the other `src/composition/` factories for tool services, including [`gpu.ts`](src/composition/gpu.ts) and [`model.ts`](src/composition/model.ts). Live Frida, Cutter, GDB and Rizin construction also uses shared composition -factories. For service ownership, availability and catalog declarations, follow -the [capability composition guide](docs/capability-composition.md). +factories. Start with [capability declarations](src/composition/capabilityDeclarations.ts) +for catalog metadata and [service bindings](src/composition/capabilityServices.ts) +for construction, availability and cleanup. Production factories construct fresh providers without starting engines or acquiring targets; optional adapter failures must preserve successful peers. Run `npm run verify:test-discovery` after adding or moving tests. Resolved import @@ -28,9 +27,8 @@ It also checks each top-level `src/` unit against its layer in directory must declare one) and against the counted outward, mutual, cross-provider and past-entry imports in `scripts/lib/module-layers.baseline.json`. Application, composition and the -adapters import a provider through the entry files it declares in that table -([decision](docs/adr/architecture/provider-entry-files.md)); a new entry file -widens the provider's public surface. The baseline may only shrink: a +adapters import a provider through the entry files it declares in that table. +A new entry file widens the provider's public surface. The baseline may only shrink: a change that removes such imports lowers it with `node scripts/verify-module-boundaries.mjs --shrink-layer-baseline`. @@ -56,9 +54,8 @@ compare equivalent real tasks before claiming an improvement. When adding or changing an MCP tool, follow the [tool design guide](docs/development/tool-design.md) and preserve the canonical contracts and generated catalog. When adding or changing an admission ceiling, budget, or deadline, follow -[analysis settings, limits, and recovery](docs/design/limits-and-recovery.md) -for ownership, operation snapshots, provider integration, and the steps for -adding a runtime setting. +[analysis settings, limits, and recovery](docs/reference/limits-and-recovery.md) +for the steps for adding a runtime setting and documenting recovery. ## Reporting issues @@ -332,8 +329,7 @@ then rerun the command. ## Documentation website Use the [documentation directory](docs/README.md) and -[authoring guide](docs/development/documentation.md) for document ownership, -domain-based feature specifications and architectural decision records. +[authoring guide](docs/development/documentation.md) for document ownership. The VitePress site uses the Markdown files in `docs/`. Run `npm run docs:dev` for live editing and `npm run docs:preview` to serve an existing build at diff --git a/README.md b/README.md index 6cbd8d77f7..93e1e27259 100644 --- a/README.md +++ b/README.md @@ -438,7 +438,6 @@ For exact options, prerequisites and result contracts: - [CLI and Evidence](docs/getting-started/cli.md): commands, provider selection, snapshots, import/export and exit statuses. - [MCP contracts](docs/reference/mcp-contracts.md) and [agent prompts](docs/getting-started/mcp-prompts.md): tool results, sessions and guided investigations. - [Tool catalog](docs/reference/mcp-contracts.md#generated-catalog): generated inventory of tools, providers and CLI commands. -- [Roadmap](docs/development/roadmap.md): planned work and capability trackers. Report vulnerabilities through [SECURITY.md](SECURITY.md). @@ -472,9 +471,8 @@ We'd love your help with REA! [Open an issue](https://github.com/morluto/rea/iss report a bug or suggest a feature, or [send a pull request](https://github.com/morluto/rea/pulls) to improve the code or docs. -See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and checks, -[testing](docs/development/testing.md) for verification lanes, and the -[architecture map](docs/architecture/architecture.mermaid) for selected layers and dependency paths. +See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and checks. See the +[testing guide](docs/development/testing.md) for verification lanes. ## License diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts index e70fc03571..c4b5fc0886 100644 --- a/docs/.vitepress/config.ts +++ b/docs/.vitepress/config.ts @@ -10,8 +10,6 @@ const documentationRoot = fileURLToPath(new URL("..", import.meta.url)); const rewrites: Record = { ...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, diff --git a/docs/.vitepress/documentation.ts b/docs/.vitepress/documentation.ts index a0e9e34d39..d6fdd377a1 100644 --- a/docs/.vitepress/documentation.ts +++ b/docs/.vitepress/documentation.ts @@ -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", diff --git a/docs/README.md b/docs/README.md index 85ee66b5d9..f3858a8bc9 100644 --- a/docs/README.md +++ b/docs/README.md @@ -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) - ## Generated files and release records diff --git a/docs/adr/README.md b/docs/adr/README.md deleted file mode 100644 index 16c75811f4..0000000000 --- a/docs/adr/README.md +++ /dev/null @@ -1,9 +0,0 @@ -# Architectural decision records - -Store one actual decision per `docs/adr//.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. diff --git a/docs/adr/architecture/domain-subsystems.md b/docs/adr/architecture/domain-subsystems.md deleted file mode 100644 index 1c8781ae81..0000000000 --- a/docs/adr/architecture/domain-subsystems.md +++ /dev/null @@ -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. diff --git a/docs/adr/architecture/provider-entry-files.md b/docs/adr/architecture/provider-entry-files.md deleted file mode 100644 index dbcfba9455..0000000000 --- a/docs/adr/architecture/provider-entry-files.md +++ /dev/null @@ -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//`. 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. diff --git a/docs/adr/evidence/target-identity.md b/docs/adr/evidence/target-identity.md deleted file mode 100644 index 178e0a7a91..0000000000 --- a/docs/adr/evidence/target-identity.md +++ /dev/null @@ -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. diff --git a/docs/adr/javascript/pushed-effect-invalidation.md b/docs/adr/javascript/pushed-effect-invalidation.md deleted file mode 100644 index e34b3ec160..0000000000 --- a/docs/adr/javascript/pushed-effect-invalidation.md +++ /dev/null @@ -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. diff --git a/docs/adr/native/typed-operation-facts.md b/docs/adr/native/typed-operation-facts.md deleted file mode 100644 index 7772b9fd77..0000000000 --- a/docs/adr/native/typed-operation-facts.md +++ /dev/null @@ -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`. diff --git a/docs/adr/setup/client-table.md b/docs/adr/setup/client-table.md deleted file mode 100644 index a821b54091..0000000000 --- a/docs/adr/setup/client-table.md +++ /dev/null @@ -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. diff --git a/docs/agent-environments-quickstart.md b/docs/agent-environments-quickstart.md index 666133f74a..7aef716299 100644 --- a/docs/agent-environments-quickstart.md +++ b/docs/agent-environments-quickstart.md @@ -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). diff --git a/docs/agent-environments.md b/docs/agent-environments.md index af128be676..58d85c8fcc 100644 --- a/docs/agent-environments.md +++ b/docs/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 diff --git a/docs/architecture/architecture.mermaid b/docs/architecture/architecture.mermaid deleted file mode 100644 index 4c4f2f39eb..0000000000 --- a/docs/architecture/architecture.mermaid +++ /dev/null @@ -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/
One-shot CLI adapter
setup, diagnostics, analysis, decompilation
cliLoader: recorded registrar per command, complete CLI otherwise"] - MAIN["src/main.ts + src/main/
MCP server adapter: stdio default, streamable HTTP opt-in
config, session, process lifetime"] - DISPATCH["scripts/rea.mjs
Executable dispatcher
routes mcp / mcp --http / one-shot"] - end - - subgraph "Production Composition" - COMPOSITION["src/composition/
fresh typed provider and session factories
one-shot binding and independent optional loading
typed capability bindings: construction, availability and retryable lifetimes
pure capability declarations feed provider catalogs"] - end - - subgraph "Adapters" - SERVER["src/server/
MCP request translation
createServer, tool registration, toolResult
http/: streamable HTTP listener and node:http bridge"] - HOPPER_BRIDGE["bridge/hopper_bridge.py
Runs inside Hopper
adapts operations to Hopper Python API"] - GHIDRA_BRIDGE["bridge/ghidra/ReaGhidraBridge.java
Packaged HeadlessScript
inventory, decompiler, references, CFG"] - INSTALL["src/cli/ + src/application/Setup*
Host installation adapters
macOS: verified vendor DMG to ~/Applications
Linux: verified vendor package + apt/dnf/pacman"] - end - - subgraph "Application Layer" - APP["src/application/
Shared CLI/MCP workflows
enhanced analysis and investigations"] - SESSION["SessionProviderRouter + BinarySession
one immutable deep binding per target
disjoint auxiliary routing"] - REGISTRY["AnalysisProviderRegistry
sorted deep candidates
deterministic selection, no fallback
ProviderInspectionScope: prerequisite observation lifetime"] - RECORDS["src/application/investigation/
composed InvestigationRecords + narrow ports
EvidenceLedger and Unknown ownership"] - LIFETIMES["CapabilityScope
host-owned service close capabilities
released peers removed; failed cleanup retained for retry"] - SNAPSHOT["BinarySessionRecords + AnalysisSnapshotCache
binary target/profile snapshots and session file ownership
record coordination and post-commit notifications"] - JS_RECON["src/application/javascript/ + src/artifacts/javascript/
JavaScript artifact reconstruction
directory/ASAR reads
AST-only bundle projection"] - end - - subgraph "Provider Layers (selected adapters)" - PROVIDER_OWNERS["src/providers/
shared deferred client owners
exact cleanup retry and attributed failures"] - PWNTOOLS["src/native/pwntools/ + src/native/pwndbg/
BYO offline ELF/core adapters
owned snapshots/Python and optional core-only GDB
unchanged upstream parsers, ABI structures and mapping API"] - WASM["src/wasm/
caller-supplied WABT; immutable artifact inspection
owned process supervision and retryable workspace cleanup"] - APKSIG["src/apkSignature/
in-process APK Signing Block + v1 reader
bounded single read, no device or execution"] - EVM["src/evm/
unchanged EVMole/WASM in bounded owned worker
explicit carrier parsing and inferred interface adapter"] - HOPPER["src/hopper/
Hopper launch & Unix-socket protocol
BridgeLauncher, HopperClient, protocol"] - GHIDRA["src/ghidra/
Ghidra discovery, profile & function analysis
snapshot, Unix/Windows transport, bounded lifecycle"] - IDA["src/ida/
Upstream MCP contract adaptation
live GUI binding or owned headless database"] - IDA_MCP["External ida-pro-mcp
GUI proxy or database supervisor
upstream installation and engine lifecycle"] - - KUNA["src/kuna/
BYO Kuna decompiler, a deep analysis candidate
discovery reads metadata only; version probe when a target opens"] - AUX["src/artifacts/ + src/native/
artifact inventory, bounded directory triage and extraction
format readers and native capabilities"] - - - BROWSER["src/browser/
CDP / Playwright capture
captured scripts and native module resolution
execution/: coverage, listener and source attribution"] - JS_CODEC["src/javascript/sourceMaps/
pinned upstream map codec
owned heap-limited Node process, complete point evidence"] - INSPECTOR["src/inspector/
passive V8 Inspector discovery and capture
script and target locations"] - DOTNET["src/dotnet/
Managed static metadata provider
PE/CLI metadata inventory, members, IL"] - OBJDUMP["src/objdump/
GNU objdump command profile"] - RIZIN["src/rizin/
Static command profile and persistent debugger sessions"] - GDB["src/gdb/
Persistent GDB/MI sessions
owned process lifecycle and target state"] - - FIRMWARE["src/firmware/
Binwalk / Unblob adapters
owned processes, report normalization, private extraction"] - ANDROID["src/android/
Static APK adapter
owned SDK stdio, pinned headless JADX, normalization"] - REFERENCE["src/reference/
Filesystem reference-source reader
bounded traversal, validation, errors"] - - ANDROID_TOOLS["src/adb/ + src/apktool/ + src/jeb/
BYO device, resource-decoding and JEB adapters
owned adb and Apktool processes; JEB engine client over MCP"] - CAPTURE_TOOLS["src/captures/ + src/pcap/ + src/signals/ + src/sqlite/
BYO tshark, pcap, sigrok and SQLite child inspection
selected captures, recordings and databases; owned processes"] - NATIVE_READERS["src/go/ + src/rust/ + src/il2cpp/ + src/flutter/ + src/gpu/
Bundled in-process binary metadata readers
Go build info, Rust dependencies, IL2CPP, Dart build ID, GPU code objects"] - FORMAT_READERS["src/model/ + src/python/ + src/erlang/ + src/electron/
Bundled in-process format readers
GGUF and safetensors headers, Python .pyc, Erlang BEAM, Electron fuses"] - RUNTIME["src/frida/ + src/cutter/
Frida instrumentation sessions and live Cutter bridge client"] - end - - subgraph "Provider Process Foundation" - PROCESS["src/process/
owned process groups, private roots
deadlines, bounded file reads and diagnostics, cleanup"] - WINDOWS["src/windows/
Windows host boundary adapters
package loader, opaque handles, owned jobs and private runtimes"] - WINDOWS_NATIVE["native/windows/src/
Node-API implementation
NTFS/ReFS admission, protected DACLs and atomic Job Object assignment"] - FILESYSTEM["src/filesystem/
owned file and directory handles
stable reads, staged output, caller paths"] - HOPPER_PATHS["src/hopperPaths/
Hopper install paths and launcher discovery
read by the Hopper provider, doctor and setup"] - RESOURCES["src/resources/
shared analysis resource owners
cleanup leases, artifact reader contract, resource scope, owned file operations, stable reads, atomic text writes"] - end - - subgraph "Contracts Layer" - CONTRACTS["src/contracts/
Caller-visible schemas for analysis, reverse engineering, managed, browser, Electron, application, and session tools"] - ERRORS["src/contracts/errorSchemas.ts
CLI error envelope and published error JSON Schema
projection schema owned by src/domain/analysisErrorProjectionSchema.ts"] - end - - subgraph "Domain Layer" - DOMAIN["src/domain/
Pure side-effect-free modules
format declarations, provider selection, Evidence, comparisons, application graphs"] - end - - subgraph "Configuration" - CONFIG["src/config/
Zod-validated env parsing
provider settings and origins"] - end - - subgraph "Tests" - TESTS["tests/
Vitest suite
fixtures/ holds fake launcher, bridge, and CDP seams"] - end - - subgraph "Development Evaluation" - EVALUATION["tests/evaluation/model-evals/
Agent release evaluation
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 diff --git a/docs/bun-standalone.md b/docs/bun-standalone.md index d6f694745a..c34a04d711 100644 --- a/docs/bun-standalone.md +++ b/docs/bun-standalone.md @@ -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`. diff --git a/docs/capability-composition.md b/docs/capability-composition.md deleted file mode 100644 index e39076993f..0000000000 --- a/docs/capability-composition.md +++ /dev/null @@ -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. diff --git a/docs/desktop-build-computer.md b/docs/desktop-build-computer.md index 8c6d97be97..4bf4156825 100644 --- a/docs/desktop-build-computer.md +++ b/docs/desktop-build-computer.md @@ -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. diff --git a/docs/desktop-build-witness.md b/docs/desktop-build-witness.md index d8968cea8e..fb82c0b6e5 100644 --- a/docs/desktop-build-witness.md +++ b/docs/desktop-build-witness.md @@ -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. diff --git a/docs/development/documentation.md b/docs/development/documentation.md index ad4dba7884..da689f78ab 100644 --- a/docs/development/documentation.md +++ b/docs/development/documentation.md @@ -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//` | -| 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///` | -| One architectural decision | `docs/adr//.md` | +| Document | Destination | +| -------------------------------------------------------- | ----------------------- | +| Installation, client setup and first CLI/MCP steps | `docs/getting-started/` | +| Analyst workflows and evidence interpretation | `docs/guides//` | +| 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///`. 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//.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 diff --git a/docs/development/roadmap.md b/docs/development/roadmap.md deleted file mode 100644 index 338c99e1ff..0000000000 --- a/docs/development/roadmap.md +++ /dev/null @@ -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. diff --git a/docs/development/tool-design.md b/docs/development/tool-design.md index 4406985eba..60b95db3eb 100644 --- a/docs/development/tool-design.md +++ b/docs/development/tool-design.md @@ -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 diff --git a/docs/elf-dependencies.md b/docs/elf-dependencies.md index ecfc80573d..ccf4b2b2d4 100644 --- a/docs/elf-dependencies.md +++ b/docs/elf-dependencies.md @@ -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`. diff --git a/docs/elf-notes.md b/docs/elf-notes.md index 8f2110b67a..8bac2ca8fd 100644 --- a/docs/elf-notes.md +++ b/docs/elf-notes.md @@ -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, diff --git a/docs/getting-started/client-configuration.md b/docs/getting-started/client-configuration.md index 8b01621e4a..a2821da5d3 100644 --- a/docs/getting-started/client-configuration.md +++ b/docs/getting-started/client-configuration.md @@ -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 diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md index 48ea581353..5ab24b42b4 100644 --- a/docs/getting-started/installation.md +++ b/docs/getting-started/installation.md @@ -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 diff --git a/docs/guides/android/android-analysis.md b/docs/guides/android/android-analysis.md index 30610a607d..50c14cf39a 100644 --- a/docs/guides/android/android-analysis.md +++ b/docs/guides/android/android-analysis.md @@ -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 diff --git a/docs/guides/javascript/electron-observation.md b/docs/guides/javascript/electron-observation.md index 496f07fece..6756f8a6e4 100644 --- a/docs/guides/javascript/electron-observation.md +++ b/docs/guides/javascript/electron-observation.md @@ -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 diff --git a/docs/guides/javascript/javascript-artifact-reconstruction.md b/docs/guides/javascript/javascript-artifact-reconstruction.md index 2440a53c27..67c6463094 100644 --- a/docs/guides/javascript/javascript-artifact-reconstruction.md +++ b/docs/guides/javascript/javascript-artifact-reconstruction.md @@ -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. diff --git a/docs/guides/native/native-investigation.md b/docs/guides/native/native-investigation.md index d56c0b0e8d..3f7e8bfc57 100644 --- a/docs/guides/native/native-investigation.md +++ b/docs/guides/native/native-investigation.md @@ -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 diff --git a/docs/guides/wasm/wasm-artifacts.md b/docs/guides/wasm/wasm-artifacts.md index d685485ee0..8b02b9a869 100644 --- a/docs/guides/wasm/wasm-artifacts.md +++ b/docs/guides/wasm/wasm-artifacts.md @@ -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; diff --git a/docs/guides/web/web-network-captures.md b/docs/guides/web/web-network-captures.md index 0df94ac0ee..6b0f60ba1f 100644 --- a/docs/guides/web/web-network-captures.md +++ b/docs/guides/web/web-network-captures.md @@ -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 diff --git a/docs/providers/ghidra-provider.md b/docs/providers/ghidra-provider.md index 0542099910..c58bdfbc28 100644 --- a/docs/providers/ghidra-provider.md +++ b/docs/providers/ghidra-provider.md @@ -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 diff --git a/docs/readme/README_ar.md b/docs/readme/README_ar.md index b5a7cf021b..5c98ad89cb 100644 --- a/docs/readme/README_ar.md +++ b/docs/readme/README_ar.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) لمسارات التحقق. ## الترخيص diff --git a/docs/readme/README_bg.md b/docs/readme/README_bg.md index 17d9a94924..7305681c8a 100644 --- a/docs/readme/README_bg.md +++ b/docs/readme/README_bg.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) за -избрани слоеве и пътища на зависимостите. +проверки. ## Лиценз diff --git a/docs/readme/README_de.md b/docs/readme/README_de.md index 8b2cc399e1..adeeee4851 100644 --- a/docs/readme/README_de.md +++ b/docs/readme/README_de.md @@ -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 diff --git a/docs/readme/README_el.md b/docs/readme/README_el.md index bfea42f0a8..abdcd9f551 100644 --- a/docs/readme/README_el.md +++ b/docs/readme/README_el.md @@ -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) για τις διαδικασίες επαλήθευσης. ## Άδεια χρήσης diff --git a/docs/readme/README_es.md b/docs/readme/README_es.md index 47066c4419..b958cacd95 100644 --- a/docs/readme/README_es.md +++ b/docs/readme/README_es.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 diff --git a/docs/readme/README_fa.md b/docs/readme/README_fa.md index 0db4eb496a..d8fd292864 100644 --- a/docs/readme/README_fa.md +++ b/docs/readme/README_fa.md @@ -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) را ببینید. ## مجوز diff --git a/docs/readme/README_fr.md b/docs/readme/README_fr.md index d8ff7e3130..9a06158df9 100644 --- a/docs/readme/README_fr.md +++ b/docs/readme/README_fr.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 diff --git a/docs/readme/README_id.md b/docs/readme/README_id.md index e8d8bc5616..ba1e3fd471 100644 --- a/docs/readme/README_id.md +++ b/docs/readme/README_id.md @@ -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 diff --git a/docs/readme/README_it.md b/docs/readme/README_it.md index f11455bf14..7b5ebab96c 100644 --- a/docs/readme/README_it.md +++ b/docs/readme/README_it.md @@ -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 diff --git a/docs/readme/README_ja.md b/docs/readme/README_ja.md index 74443eca79..37900f94f9 100644 --- a/docs/readme/README_ja.md +++ b/docs/readme/README_ja.md @@ -364,7 +364,6 @@ npx rea-agents@latest setup - [CLI と Evidence](../getting-started/cli.md):コマンド、プロバイダーの選択、スナップショット、インポート/エクスポート、終了ステータス。 - [MCP 契約](../reference/mcp-contracts.md)と[エージェント向けプロンプト](../getting-started/mcp-prompts.md):ツールの結果、セッション、ガイド付き調査。 - [ツールカタログ](../reference/mcp-contracts.md#generated-catalog):ビルド時に生成されるツール、プロバイダー、CLI コマンドの一覧。 -- [ロードマップ](../development/roadmap.md):計画中の作業と機能の進捗。 脆弱性の報告は [SECURITY.md](../../SECURITY.md) に従ってください。 @@ -394,7 +393,7 @@ REA は、法令に従った研究、教育、相互運用性の確保、ソフ REA への貢献を歓迎します![issue を作成](https://github.com/morluto/rea/issues)してバグや機能の提案を報告したり、[pull request を送信](https://github.com/morluto/rea/pulls)してコードやドキュメントを改善したりできます。 -開発環境とチェックは [CONTRIBUTING.md](../../CONTRIBUTING.md)、検証レーンは[テストガイド](../development/testing.md)、プロジェクト構造は[アーキテクチャ図](../architecture/architecture.mermaid)を参照してください。 +開発環境とチェックは [CONTRIBUTING.md](../../CONTRIBUTING.md)、検証レーンは[テストガイド](../development/testing.md)を参照してください。 ## ライセンス diff --git a/docs/readme/README_ko.md b/docs/readme/README_ko.md index ed0b0ebbd8..232d17d234 100644 --- a/docs/readme/README_ko.md +++ b/docs/readme/README_ko.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` 값을 수정하세요. diff --git a/docs/readme/README_ml.md b/docs/readme/README_ml.md index d40deeccfe..39d9e1fa2e 100644 --- a/docs/readme/README_ml.md +++ b/docs/readme/README_ml.md @@ -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) എന്നിവ കാണുക. ## ലൈസൻസ് diff --git a/docs/readme/README_pl.md b/docs/readme/README_pl.md index 3c9c61c56d..22072fc0bc 100644 --- a/docs/readme/README_pl.md +++ b/docs/readme/README_pl.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 diff --git a/docs/readme/README_pt-BR.md b/docs/readme/README_pt-BR.md index d9ed630148..afc8887323 100644 --- a/docs/readme/README_pt-BR.md +++ b/docs/readme/README_pt-BR.md @@ -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 diff --git a/docs/readme/README_ro.md b/docs/readme/README_ro.md index 5e7105a3d3..ac3049b3a2 100644 --- a/docs/readme/README_ro.md +++ b/docs/readme/README_ro.md @@ -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ță diff --git a/docs/readme/README_ru.md b/docs/readme/README_ru.md index 68ee1b8418..d3fd3a7a9f 100644 --- a/docs/readme/README_ru.md +++ b/docs/readme/README_ru.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). ## Лицензия diff --git a/docs/readme/README_th.md b/docs/readme/README_th.md index 22ff66d254..57847e87f7 100644 --- a/docs/readme/README_th.md +++ b/docs/readme/README_th.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) สำหรับแนวทางการตรวจยืนยัน ## สัญญาอนุญาต diff --git a/docs/readme/README_tr.md b/docs/readme/README_tr.md index 40bd42fbb4..530c3fc862 100644 --- a/docs/readme/README_tr.md +++ b/docs/readme/README_tr.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 diff --git a/docs/readme/README_uk.md b/docs/readme/README_uk.md index a434852d8b..c1255ba808 100644 --- a/docs/readme/README_uk.md +++ b/docs/readme/README_uk.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). ## Ліцензія diff --git a/docs/readme/README_ur-Latn.md b/docs/readme/README_ur-Latn.md index d3bf6422ee..0d875c0359 100644 --- a/docs/readme/README_ur-Latn.md +++ b/docs/readme/README_ur-Latn.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 diff --git a/docs/readme/README_vi.md b/docs/readme/README_vi.md index 29762b46dd..9093c81ffb 100644 --- a/docs/readme/README_vi.md +++ b/docs/readme/README_vi.md @@ -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 diff --git a/docs/readme/README_zh-TW.md b/docs/readme/README_zh-TW.md index 1c472451c1..f94bba6e49 100644 --- a/docs/readme/README_zh-TW.md +++ b/docs/readme/README_zh-TW.md @@ -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)。 ## 授權條款 diff --git a/docs/readme/README_zh.md b/docs/readme/README_zh.md index 7ac9510b01..b47aef42b7 100644 --- a/docs/readme/README_zh.md +++ b/docs/readme/README_zh.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)。 ## 许可证 diff --git a/docs/design/limits-and-recovery.md b/docs/reference/limits-and-recovery.md similarity index 61% rename from docs/design/limits-and-recovery.md rename to docs/reference/limits-and-recovery.md index ae82bf79ab..16122ac9e2 100644 --- a/docs/design/limits-and-recovery.md +++ b/docs/reference/limits-and-recovery.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=`) 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: diff --git a/docs/reference/mcp-contracts.md b/docs/reference/mcp-contracts.md index 2c5a6adada..d4ea34d2ab 100644 --- a/docs/reference/mcp-contracts.md +++ b/docs/reference/mcp-contracts.md @@ -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. diff --git a/docs/design/rea-limit-inventory.md b/docs/reference/rea-limit-inventory.md similarity index 86% rename from docs/design/rea-limit-inventory.md rename to docs/reference/rea-limit-inventory.md index 33bb96b558..71f873cb44 100644 --- a/docs/design/rea-limit-inventory.md +++ b/docs/reference/rea-limit-inventory.md @@ -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 diff --git a/docs/specs/2356-wasm-interface-comparison/plan.md b/docs/specs/2356-wasm-interface-comparison/plan.md deleted file mode 100644 index a5b9e8ac3a..0000000000 --- a/docs/specs/2356-wasm-interface-comparison/plan.md +++ /dev/null @@ -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. diff --git a/docs/specs/2356-wasm-interface-comparison/spec.md b/docs/specs/2356-wasm-interface-comparison/spec.md deleted file mode 100644 index 419ae96c88..0000000000 --- a/docs/specs/2356-wasm-interface-comparison/spec.md +++ /dev/null @@ -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 diff --git a/docs/specs/2356-wasm-interface-comparison/tasks.md b/docs/specs/2356-wasm-interface-comparison/tasks.md deleted file mode 100644 index 722ace2c95..0000000000 --- a/docs/specs/2356-wasm-interface-comparison/tasks.md +++ /dev/null @@ -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. diff --git a/docs/specs/2356-wasm-interface-comparison/verification.md b/docs/specs/2356-wasm-interface-comparison/verification.md deleted file mode 100644 index ca531e8e4a..0000000000 --- a/docs/specs/2356-wasm-interface-comparison/verification.md +++ /dev/null @@ -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. diff --git a/docs/specs/README.md b/docs/specs/README.md deleted file mode 100644 index f5092859b9..0000000000 --- a/docs/specs/README.md +++ /dev/null @@ -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)) diff --git a/docs/specs/agent-environments/README.md b/docs/specs/agent-environments/README.md deleted file mode 100644 index c67f2596b8..0000000000 --- a/docs/specs/agent-environments/README.md +++ /dev/null @@ -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) diff --git a/docs/specs/agent-environments/environment-build/plan.md b/docs/specs/agent-environments/environment-build/plan.md deleted file mode 100644 index 65b156bbda..0000000000 --- a/docs/specs/agent-environments/environment-build/plan.md +++ /dev/null @@ -1,25 +0,0 @@ -# Plan - -1. Add `environmentCoverageView.ts`: the request schema, the result fields, the - hint per write reason (`satisfies Record`), 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. diff --git a/docs/specs/agent-environments/environment-build/spec.md b/docs/specs/agent-environments/environment-build/spec.md deleted file mode 100644 index 0a52152fc2..0000000000 --- a/docs/specs/agent-environments/environment-build/spec.md +++ /dev/null @@ -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 [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. diff --git a/docs/specs/agent-environments/environment-build/tasks.md b/docs/specs/agent-environments/environment-build/tasks.md deleted file mode 100644 index 1ee2e8380b..0000000000 --- a/docs/specs/agent-environments/environment-build/tasks.md +++ /dev/null @@ -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. diff --git a/docs/specs/agent-environments/environment-build/verification.md b/docs/specs/agent-environments/environment-build/verification.md deleted file mode 100644 index 88639e0a66..0000000000 --- a/docs/specs/agent-environments/environment-build/verification.md +++ /dev/null @@ -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 --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 `. 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 ---name --package-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. diff --git a/docs/specs/agent-environments/environment-export/plan.md b/docs/specs/agent-environments/environment-export/plan.md deleted file mode 100644 index b3515ad768..0000000000 --- a/docs/specs/agent-environments/environment-export/plan.md +++ /dev/null @@ -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. diff --git a/docs/specs/agent-environments/environment-export/spec.md b/docs/specs/agent-environments/environment-export/spec.md deleted file mode 100644 index 5831904f89..0000000000 --- a/docs/specs/agent-environments/environment-export/spec.md +++ /dev/null @@ -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 --evidence -[--package-tarball ] [--name ]` writes the manifest and -capture pair that `environment-serve` serves as a bundle folder the agentenv -framework runs with `agent-env run `: 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//Dockerfile`, `envs//env.toml`, - `envs//manifest.json` and `envs//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_/verify.py` and - `tasks/smoke.json`, where `` 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,`, installs Debian's `python3` for the - framework's readiness probe, installs - `rea-agents@` 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": , "description": }]`; with no - such tool it checks the count only and says so. -- `tasks/smoke.json` is `deploy_env` of `` on the local sandbox followed - by `env_outcome_verifier` with `file_artifact_id` `check_` 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 --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. diff --git a/docs/specs/agent-environments/environment-export/tasks.md b/docs/specs/agent-environments/environment-export/tasks.md deleted file mode 100644 index f1a0a4a211..0000000000 --- a/docs/specs/agent-environments/environment-export/tasks.md +++ /dev/null @@ -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. diff --git a/docs/specs/agent-environments/environment-export/verification.md b/docs/specs/agent-environments/environment-export/verification.md deleted file mode 100644 index 100bbc512d..0000000000 --- a/docs/specs/agent-environments/environment-export/verification.md +++ /dev/null @@ -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 `, 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: 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@` -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 /grafana-example --package-tarball --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 /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=/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[-]` 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**. diff --git a/docs/specs/agent-environments/environment-prompt/plan.md b/docs/specs/agent-environments/environment-prompt/plan.md deleted file mode 100644 index e25f19d838..0000000000 --- a/docs/specs/agent-environments/environment-prompt/plan.md +++ /dev/null @@ -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. diff --git a/docs/specs/agent-environments/environment-prompt/spec.md b/docs/specs/agent-environments/environment-prompt/spec.md deleted file mode 100644 index e55061042c..0000000000 --- a/docs/specs/agent-environments/environment-prompt/spec.md +++ /dev/null @@ -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. diff --git a/docs/specs/agent-environments/environment-prompt/tasks.md b/docs/specs/agent-environments/environment-prompt/tasks.md deleted file mode 100644 index a0487aaa16..0000000000 --- a/docs/specs/agent-environments/environment-prompt/tasks.md +++ /dev/null @@ -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. diff --git a/docs/specs/agent-environments/environment-prompt/verification.md b/docs/specs/agent-environments/environment-prompt/verification.md deleted file mode 100644 index cf8f86c8b3..0000000000 --- a/docs/specs/agent-environments/environment-prompt/verification.md +++ /dev/null @@ -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. diff --git a/docs/specs/agent-environments/environment-serve/plan.md b/docs/specs/agent-environments/environment-serve/plan.md deleted file mode 100644 index 43cec174b3..0000000000 --- a/docs/specs/agent-environments/environment-serve/plan.md +++ /dev/null @@ -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. diff --git a/docs/specs/agent-environments/environment-serve/spec.md b/docs/specs/agent-environments/environment-serve/spec.md deleted file mode 100644 index ed88d2aaaf..0000000000 --- a/docs/specs/agent-environments/environment-serve/spec.md +++ /dev/null @@ -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 --evidence [--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_`, a query name - longer than 64 characters becomes `query_`, 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. diff --git a/docs/specs/agent-environments/environment-serve/tasks.md b/docs/specs/agent-environments/environment-serve/tasks.md deleted file mode 100644 index 1a9d8e0ee1..0000000000 --- a/docs/specs/agent-environments/environment-serve/tasks.md +++ /dev/null @@ -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. diff --git a/docs/specs/agent-environments/environment-serve/verification.md b/docs/specs/agent-environments/environment-serve/verification.md deleted file mode 100644 index fe74d78f00..0000000000 --- a/docs/specs/agent-environments/environment-serve/verification.md +++ /dev/null @@ -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. diff --git a/docs/specs/agent-environments/fidelity-compare/plan.md b/docs/specs/agent-environments/fidelity-compare/plan.md deleted file mode 100644 index 703d71744b..0000000000 --- a/docs/specs/agent-environments/fidelity-compare/plan.md +++ /dev/null @@ -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. diff --git a/docs/specs/agent-environments/fidelity-compare/spec.md b/docs/specs/agent-environments/fidelity-compare/spec.md deleted file mode 100644 index 56fce988eb..0000000000 --- a/docs/specs/agent-environments/fidelity-compare/spec.md +++ /dev/null @@ -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. diff --git a/docs/specs/agent-environments/fidelity-compare/tasks.md b/docs/specs/agent-environments/fidelity-compare/tasks.md deleted file mode 100644 index 33343cd19f..0000000000 --- a/docs/specs/agent-environments/fidelity-compare/tasks.md +++ /dev/null @@ -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. diff --git a/docs/specs/agent-environments/fidelity-compare/verification.md b/docs/specs/agent-environments/fidelity-compare/verification.md deleted file mode 100644 index 72ab493b47..0000000000 --- a/docs/specs/agent-environments/fidelity-compare/verification.md +++ /dev/null @@ -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 `""` (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. diff --git a/docs/specs/agent-environments/http-transport/plan.md b/docs/specs/agent-environments/http-transport/plan.md deleted file mode 100644 index 1592063474..0000000000 --- a/docs/specs/agent-environments/http-transport/plan.md +++ /dev/null @@ -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. diff --git a/docs/specs/agent-environments/http-transport/spec.md b/docs/specs/agent-environments/http-transport/spec.md deleted file mode 100644 index 3c59819310..0000000000 --- a/docs/specs/agent-environments/http-transport/spec.md +++ /dev/null @@ -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. diff --git a/docs/specs/agent-environments/http-transport/tasks.md b/docs/specs/agent-environments/http-transport/tasks.md deleted file mode 100644 index 07981bff35..0000000000 --- a/docs/specs/agent-environments/http-transport/tasks.md +++ /dev/null @@ -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. diff --git a/docs/specs/agent-environments/http-transport/verification.md b/docs/specs/agent-environments/http-transport/verification.md deleted file mode 100644 index 68dcdfb998..0000000000 --- a/docs/specs/agent-environments/http-transport/verification.md +++ /dev/null @@ -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. diff --git a/docs/specs/agent-environments/list-lines/plan.md b/docs/specs/agent-environments/list-lines/plan.md deleted file mode 100644 index 53046a4bd8..0000000000 --- a/docs/specs/agent-environments/list-lines/plan.md +++ /dev/null @@ -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. diff --git a/docs/specs/agent-environments/list-lines/spec.md b/docs/specs/agent-environments/list-lines/spec.md deleted file mode 100644 index 156c8d4165..0000000000 --- a/docs/specs/agent-environments/list-lines/spec.md +++ /dev/null @@ -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. diff --git a/docs/specs/agent-environments/list-lines/tasks.md b/docs/specs/agent-environments/list-lines/tasks.md deleted file mode 100644 index cac18cf2bd..0000000000 --- a/docs/specs/agent-environments/list-lines/tasks.md +++ /dev/null @@ -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. diff --git a/docs/specs/agent-environments/list-lines/verification.md b/docs/specs/agent-environments/list-lines/verification.md deleted file mode 100644 index 9c9c16328a..0000000000 --- a/docs/specs/agent-environments/list-lines/verification.md +++ /dev/null @@ -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. diff --git a/docs/specs/agent-environments/list-queries/plan.md b/docs/specs/agent-environments/list-queries/plan.md deleted file mode 100644 index 9387a09201..0000000000 --- a/docs/specs/agent-environments/list-queries/plan.md +++ /dev/null @@ -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. diff --git a/docs/specs/agent-environments/list-queries/spec.md b/docs/specs/agent-environments/list-queries/spec.md deleted file mode 100644 index ebd2e96b59..0000000000 --- a/docs/specs/agent-environments/list-queries/spec.md +++ /dev/null @@ -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. diff --git a/docs/specs/agent-environments/list-queries/tasks.md b/docs/specs/agent-environments/list-queries/tasks.md deleted file mode 100644 index 1857d34210..0000000000 --- a/docs/specs/agent-environments/list-queries/tasks.md +++ /dev/null @@ -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. diff --git a/docs/specs/agent-environments/list-queries/verification.md b/docs/specs/agent-environments/list-queries/verification.md deleted file mode 100644 index 09a98de8aa..0000000000 --- a/docs/specs/agent-environments/list-queries/verification.md +++ /dev/null @@ -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. diff --git a/docs/specs/agent-environments/manifest-view/plan.md b/docs/specs/agent-environments/manifest-view/plan.md deleted file mode 100644 index a55e807631..0000000000 --- a/docs/specs/agent-environments/manifest-view/plan.md +++ /dev/null @@ -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. diff --git a/docs/specs/agent-environments/manifest-view/spec.md b/docs/specs/agent-environments/manifest-view/spec.md deleted file mode 100644 index fc20092629..0000000000 --- a/docs/specs/agent-environments/manifest-view/spec.md +++ /dev/null @@ -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. diff --git a/docs/specs/agent-environments/manifest-view/tasks.md b/docs/specs/agent-environments/manifest-view/tasks.md deleted file mode 100644 index cb50220f91..0000000000 --- a/docs/specs/agent-environments/manifest-view/tasks.md +++ /dev/null @@ -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. diff --git a/docs/specs/agent-environments/manifest-view/verification.md b/docs/specs/agent-environments/manifest-view/verification.md deleted file mode 100644 index 068bbbb433..0000000000 --- a/docs/specs/agent-environments/manifest-view/verification.md +++ /dev/null @@ -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. diff --git a/docs/specs/agent-environments/prefix-variance/plan.md b/docs/specs/agent-environments/prefix-variance/plan.md deleted file mode 100644 index 206d7329c7..0000000000 --- a/docs/specs/agent-environments/prefix-variance/plan.md +++ /dev/null @@ -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. diff --git a/docs/specs/agent-environments/prefix-variance/spec.md b/docs/specs/agent-environments/prefix-variance/spec.md deleted file mode 100644 index a6baf4e5e3..0000000000 --- a/docs/specs/agent-environments/prefix-variance/spec.md +++ /dev/null @@ -1,59 +0,0 @@ -# Share templated positions across tools - -Issue: https://github.com/morluto/rea/issues/4933 - -## Outcome - -A session usually edits one scratch entity: it creates it, then updates and -deletes it at a fixed path such as `/api/v1/collections/0RZ576QZQA5KG`. The -manifest templates a segment only when sibling routes of the same method vary -there, so those writes stay literal tools (`patch_collections_0rz576qzqa5kg`) -even though the reads of the same collection were templated as -`/api/v1/collections/{collection_id}`. A literal write tool addresses one -entity that may not exist in a later state, and nothing can model its effect. - -A new opt-in template rule, `prefix-variance`, templates such a literal with -the parameter another tool already uses at that position, so the write becomes -`patch_collections_by_collection_id` on the same template as the read. - -## Requirements - -- `prefix-variance` applies only when listed, after every other opt-in rule, so - it can share the parameters they produce. -- A literal at position `p` is templated when another tool on the same origin, - of any method and any segment count, has a parameter at `p` from one of the - other opt-in rules, after the same preceding parts. Parameters in the - preceding parts compare by the rule that names them, so a position templated - by `prefix-variance` matches the parameter it shares. -- The literal qualifies when it is one of the values such a parameter - observed at that position, when it carries a digit and has the length and - character classes (digits, lower case, upper case, each other character) of - one of them, or when every value the parameter observed, one or more, has one - length of eight or more characters, as generated identifiers often do, and - the literal has that length and uses only their character classes, so an - identifier that happens to hold no digit still qualifies. An empty literal, a - stop word or a `v1`-style version never qualifies. Each parameter's spelling - is summarised once, so a literal is checked without rescanning its values, - and a value longer than 128 characters is compared only exactly, so a huge - segment costs no classification. -- Positions templated by the four format rules are never shared, so - `/api/teams/{numeric}` still absorbs no literal. -- Values stay with the parameter that observed them: when parameters of - different rules share a position, the literal shares the one that observed - it, else the earliest one it is spelled like. -- The parameter takes the name of the parameter it shares (`collection_id`, - `uid`, a pair's `_namespace` and `_name`) and is labelled `prefix-variance`. -- Tools whose routes now match, by method and by the rule that names each - parameter, merge. A merged parameter keeps the rule of a tool that templated - that position itself, when one did. -- Like the sibling rules, it compares routes of at most 32 segments and says so - in a limitation when a longer route exists. - -## Non-goals - -- No change to the default rules or to any other rule: manifests that do not - list `prefix-variance` are byte-for-byte unchanged. -- No templating from response bodies, such as an id a create returned; the - manifest reads request lines only. -- No change to which groups are excluded: a write whose response has no body - or content type outside `/api/` is still excluded as `non-json`. diff --git a/docs/specs/agent-environments/prefix-variance/tasks.md b/docs/specs/agent-environments/prefix-variance/tasks.md deleted file mode 100644 index 9708eff558..0000000000 --- a/docs/specs/agent-environments/prefix-variance/tasks.md +++ /dev/null @@ -1,10 +0,0 @@ -# Tasks - -- [x] Record the outcome, requirements and non-goals. -- [x] Move tool naming into its own module. -- [x] Add the `prefix-variance` rule, its names, its merge and its limitation. -- [x] Document the rule in the schema and the capture guide. -- [x] Add rule tests. -- [x] Run static, formatting, duplication, documentation and test gates. -- [x] Project the 51 corpus captures with and without the rule and record the results. -- [x] Rebuild five randomly drawn environments end to end and compare them with their published versions and the live applications. diff --git a/docs/specs/agent-environments/prefix-variance/verification.md b/docs/specs/agent-environments/prefix-variance/verification.md deleted file mode 100644 index d337159d1a..0000000000 --- a/docs/specs/agent-environments/prefix-variance/verification.md +++ /dev/null @@ -1,149 +0,0 @@ -# Verification - -Verified base: 33b0643e on main 1629266e (the rule, the alias removal `knip` -asked for, and the fixed-length clause the end-to-end runs below led to). Executed on macOS with Node v22.23.1 (the repository pins -24.18.0 in `.nvmrc`, which was not installed). - -## 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.49% duplicated lines over 3561 files with 3067 clones; - main measures 3.49% with 3068, since the shared segment-limit split removes - one clone. -- oxlint reports no new finding on the changed files. The manifest accumulator - keeps main's three warnings (file length, and the complexity and parameter - count of its record append), one line longer. -- `npx vitest run --project domain --project services`: 7119 passed, 5 - pre-existing skips. -- `npm run test:prepare`, then `npm run test:focused --` the analysis-view MCP - and CLI boundaries, the compact input schema and tool schema validity - boundaries, and the environment serve and export boundaries: - 7 files, 76 passed. - -New tests in `environmentManifestView.test.ts` cover: - -- a literal shared across methods and depths, and the same capture without the rule; -- the spelling condition: same classes and length, case, missing digit, a colon word, a version; -- a digit-free member of a fixed-length identifier family, against a shorter word, a hyphenated - value and a family shorter than eight characters; -- merges that keep a tool's own rule, including a sibling-variance parameter under a shared one; -- both halves of a templated pair; -- format-rule positions and the segment limit. - -## The showcase captures - -The 50 showcase captures (45 HAR inspections and 5 `capture_browser_scenario` -captures) were projected with main's build and this branch's. - -- Without the rule, both builds give identical results for every capture: the - manifest with no rules, the manifest with `after-uid-literal`, - `opaque-token`, `sibling-variance` and `sibling-pair-variance`, and the - environment-state view. 150 of 150 outputs hash equal. -- With `prefix-variance` added to `after-uid-literal`, `opaque-token` and - `sibling-variance`, 69 literal tools in 10 captures are templated, 25 of them - writes: - - Komga: collection and readlist `PATCH` and `DELETE`, book pages. - - n8n: workflow `PATCH`, `DELETE` and archive, and the reads of a workflow - whose id holds no digit. - - Memos: memo `PATCH` and `DELETE`, user settings reads, and the reads of - two memos whose ids hold no digit. - - Navidrome: playlist `PUT` and `DELETE`. - - Mealie: recipe `PATCH` and `DELETE`. - - Grist: document `PATCH` and `DELETE`, and table record writes. - - Redpanda Console: subject and topic writes. - - Sentry: release `PUT` and `DELETE`. - - Shlink: short URL `PATCH`. - - Mattermost: `me` reads, which `sibling-variance` already folds into the - user parameter. - - Tools go from 1591 to 1578, because Redpanda Console's per-subject reads and - the per-memo and per-workflow reads merge. - -- Literals the rule leaves alone, as intended, include Espo CRM `layout`, - Federal Register `facets`, Ghost `slug`, Shlink `stats`, Lychee - `Metrics::photo` and Vault's path names. -- The environment-state view succeeds on every capture with the rule. Its types - move to the templated collections (531 become 526 as literal ones merge); the - one fewer item view is the Redpanda Console merge. - -With the write plans of #5600 (its branch with this commit and main merged in, -locally): - -- Served write tools rise from 33 to 39: Komga collection create, update and - delete; n8n workflow delete; Sentry release update and delete. -- Write tools with no state target fall from 102 to 87. -- The newly modelled tools that stay unserved are limited by the capture: - - no read after the write: Komga readlists, Mealie, Navidrome, Redpanda Console; - - n8n's item read shows an expanded `shared` relation its create response - never returned; - - Shlink returns `tags` sorted while the update echoes the request's order. - -## Five environments end to end - -Five of the ten environments the rule changes were drawn at random, redrawing -until the draw held one whose new writes are served: Komga, Mealie, n8n, -Sentry and Shlink. Each was rebuilt on its own Linux VM with `npm pack` of -#5600, main and this branch merged locally, from the same scoped HAR as its -published version: manifest with `prefix-variance`, exported bundle, smoke -task, the generated retrieval tasks for `gpt-oss-120b` and `GLM-5.3-Flash`, and -a dry-run dataset. Where writes are served, hand-written write tasks ask for a -change in plain language and are graded from the environment's state through -`data/get`. The first n8n run found that a digit-free workflow id stayed -literal; the fixed-length clause fixed it, and n8n was rebuilt. - -| Environment | Tools (published → rebuilt) | Served from state (reads / writes) | Retrieval gpt-oss | Retrieval GLM | Writes gpt-oss | Writes GLM | -| ----------- | --------------------------- | ---------------------------------- | ----------------- | ------------- | -------------- | ---------- | -| Komga | 42 → 46 | 26 / 3 | 12/12 (was 11/12) | 12/12 (11/12) | 3/4 | 4/4 | -| Mealie | 39 → 39 | 36 / 0 | 12/12 (12/12) | 12/12 (12/12) | – | – | -| n8n | 30 → 33 | 17 / 1 | 9/9 (9/9) | 9/9 (9/9) | 2/2 | 2/2 | -| Sentry | 34 → 34 | 26 / 3 | 12/12 (12/12) | 11/12 (12/12) | 2/4, rerun 0/4 | 4/4 | -| Shlink | 17 → 17 | 5 / 0 | 5/7, rerun 7/7 | 7/7 (7/7) | – | – | - -Every smoke task passed. The misses: - -- Sentry writes with gpt-oss: every failed episode passed `id: "sentry"` for - the `/api/0/` segment the tool schema describes as `observed: 0`, so its calls - addressed `/api/sentry/…`; every passing episode, and every GLM episode, passed - `0`. The served tools work; the format-rule parameter for a segment that only - ever held `0` invites the guess. -- Komga update with gpt-oss and Shlink's first gpt-oss run: the model provider - rejected tool calls the model generated (`null` and `undefined` for optional - query arguments) before the environment saw them. -- Sentry `qa-03` with GLM: the model never called the alert-rules tool. - -The same calls were also replayed against the live applications, seeded by -the same scripts (ids differ, so each side maps its ids to names): - -- Komga 1.29.1, 9 of 12 steps equal: create, update and delete of a - collection and the reads after them agree except for the generated id. The - collection list after a create omits the new collection, because that list - keeps its recorded membership, and the 404 for a deleted collection replays - the recorded body with its path and timestamp. -- n8n 1.123.85, 3 of 8 steps equal: n8n refuses to delete a workflow that is - not archived (400) and the environment deletes it; the workflow list replays - its recorded response, so a delete does not show in it; archiving is not - served. The read of the digit-free workflow failed in the first build (the - state held only its list fields) and agrees in the second, apart from ids the - seed generates. - -## After the review round - -The branch merged main at 52c84f6f, then kept each shared position's values -with the parameter that observed them (one donor per naming rule, the literal -taking the donor that observed it, else the earliest it is spelled like), -summarised each donor's spelling once, and let one observation form a -fixed-length family, as the requirement states. Two new tests, a mixed-rule -position and a single observed workflow id, fail on the previous head and pass -here. The gates above passed again (domain and services 7255 passed with 5 -pre-existing skips; the focused boundaries 76; `jscpd` 3.49%). Over the 50 -showcase captures the tools with and without `prefix-variance` are unchanged, -name for name: 69 literal tools templated, 25 of them writes. - -A second review round bounded the spelling summary: characters are classified -in one pass, and a value longer than 128 characters is compared only exactly. -Its test fails on the previous head, the gates passed again (domain and -services 7257, focused boundaries 76, `jscpd` 3.49%), and the census over the 50 -captures is again unchanged. diff --git a/docs/specs/agent-environments/rich-captures/plan.md b/docs/specs/agent-environments/rich-captures/plan.md deleted file mode 100644 index 830f32fd91..0000000000 --- a/docs/specs/agent-environments/rich-captures/plan.md +++ /dev/null @@ -1,18 +0,0 @@ -# Plan - -1. Add the `evidence-file` source to `analysisViewSourceSchema` - (`src/domain/analysisView/analysisView.ts`). -2. Add `inspectAnalysisViewWithFiles` / `inspectAnalysisViewValidatedWithFiles` - to `AnalysisViewService`: read with `readJsonFile`, authenticate with - `parseEvidence`, then project through the retained path with a lookup that - returns the file's Evidence. The synchronous path refuses an unread file - source. -3. Route the CLI command (with `source.path` resolved against the working - directory) and the MCP tool through the file-aware entry point. -4. Add `sibling-pair-variance` to `TEMPLATE_RULES`, with its merge pass before - `sibling-variance`, its parameter names and its segment-limit limitation. -5. Document both in the tool contract, `docs/getting-started/cli.md` and - `docs/guides/web/web-network-captures.md`. -6. Tests: service (file equals inline; a capture refused inline is accepted - from a file; refusals), CLI and MCP boundaries, and the pair rule's merges - and non-merges. diff --git a/docs/specs/agent-environments/rich-captures/spec.md b/docs/specs/agent-environments/rich-captures/spec.md deleted file mode 100644 index f669c5d714..0000000000 --- a/docs/specs/agent-environments/rich-captures/spec.md +++ /dev/null @@ -1,56 +0,0 @@ -# Rich captures for the environment manifest - -Issue: https://github.com/morluto/rea/issues/4933 - -## Outcome - -A capture large enough to hold a rich application state can be projected into -an environment manifest whose tool list stays within what model providers -accept. Two changes: - -- `inspect_analysis_view` accepts a third source, - `{"kind": "evidence-file", "path": ""}`. REA reads one - completed Evidence JSON file, authenticates it, and projects it like retained - Evidence, so its strings are bounded by the file reader instead of being - charged as inline input. -- The environment-manifest view gains an opt-in template rule, - `sibling-pair-variance`, that templates two adjacent literal segments after a - plural literal, such as `/repos/{owner}/{repo}/…`. - -## Requirements - -- An `evidence-file` path must be absolute and free of NUL bytes; the CLI - resolves a relative path against the working directory before validation, - and MCP clients pass an absolute path. -- The file is read through the shared JSON file reader (regular file, heap and - string-length guards) and parsed as complete Evidence. A missing or unreadable - file is an `EvidenceFileError`; JSON that is not complete Evidence is invalid - input reported under `source.path`. -- Over MCP the read follows the request's cancellation and the server's - resource scope, so a failed descriptor close stays owned for retry; a request - cancelled before authentication, before projection or during projection - returns typed cancellation and records nothing. Before authentication, which - copies and hashes the parsed Evidence, REA checks that live heap headroom holds - those copies and otherwise returns `resource_constraint`. -- A file source projects exactly what the same Evidence projects inline or - retained, with the same parent Evidence ID, view parameters and result. -- The synchronous projection API refuses an unread `evidence-file` source with - a typed capability error; the CLI and MCP adapters read files first. -- `sibling-pair-variance` applies only when listed, before `sibling-variance`, so - a single-position merge cannot template one half of a pair first. It - compares groups equal in method, origin and segment count except at two - adjacent literal positions at index 2 or later that follow a plural literal - and precede another literal (a trailing pair, such as - `/users/alice/followers`, names a sub-resource rather than a namespace and - name), and merges a bucket only when it holds at least three distinct pairs and both - positions vary. Stop words and `v1`-style versions never qualify, and routes - of more than 32 segments are not compared, with a limitation saying so. -- Its parameters are named from the plural literal, singular plus `_namespace` - and then `_name`, and labelled `sibling-pair-variance`. - -## Non-goals - -- No change to the 96 MiB projection budget or to inline admission. -- No change to `sibling-variance`; pairs are a separate rule so every inferred - parameter keeps naming the rule that produced it. -- No inference of semantic names (`owner`, `repo`) beyond the plural literal. diff --git a/docs/specs/agent-environments/rich-captures/tasks.md b/docs/specs/agent-environments/rich-captures/tasks.md deleted file mode 100644 index 4683b6971a..0000000000 --- a/docs/specs/agent-environments/rich-captures/tasks.md +++ /dev/null @@ -1,10 +0,0 @@ -# Tasks - -- [x] Record the outcome, requirements and non-goals. -- [x] Add the `evidence-file` source and the file-aware service entry point. -- [x] Route the CLI command and the MCP tool through it. -- [x] Add the `sibling-pair-variance` rule, its names and its limitation. -- [x] Document both; extend the tool contract text. -- [x] Add service, CLI, MCP and rule tests. -- [x] Run static, formatting, duplication, documentation and test gates. -- [x] Rebuild a rich capture with both changes and record the results. diff --git a/docs/specs/agent-environments/rich-captures/verification.md b/docs/specs/agent-environments/rich-captures/verification.md deleted file mode 100644 index 3a6e5d4fe6..0000000000 --- a/docs/specs/agent-environments/rich-captures/verification.md +++ /dev/null @@ -1,104 +0,0 @@ -# Verification - -Verified commit: a64367a9 on main 2dd5effe. - -## Gates - -Run on macOS 26.5.1 with Node 22.23.1 on that tree: `npm run typecheck`, `lint` -(oxlint plus `verify:module-boundaries`, 2172 files), `format:check`, `knip`, -`metadata:check`, `docs:check`, `jscpd` (3.43% duplicated lines), `scan:todos` -and `mcp-catalog:check` all exit 0. oxlint on the 12 changed TypeScript files -reports no finding that main does not already report for the same files. - -`npm run test:prepare`, then `npm run test:changed` (the tests related to the -changed files): 84 files, 1531 passed, 3 skipped, 0 failed. They include: - -- the service: an Evidence file projects exactly what the same Evidence projects - inline; a capture whose response text exceeds the inline budget is refused - inline with `resource_constraint` and projected from its file; a relative - path, a missing file and JSON that is not Evidence are refused; the - synchronous API refuses an unread file source; -- the compiled CLI: a request naming an Evidence file projects the same - manifest as the same Evidence inline; -- MCP: inline, retained and file sources give identical manifests, outputs - validate against the advertised schema, and a relative path is refused; -- the file source module: the size estimate, the authentication headroom - refusal, a cancelled request refused before reading, and a read within the - caller's resource scope; the service returns typed cancellation for a - cancelled file request; a request aborted while it runs, even after its read, returns typed - cancellation because the service yields before each check; -- the pair rule: three owner/repo pairs merge for collection and numeric detail - routes, while two pairs, or three pairs sharing one namespace, stay literal; - with `sibling-variance` also selected the pair still merges, because pairs - are merged first. Each pair parameter keeps its role when - `sibling-variance` later templates the segment before the pair. - -## A rich capture - -A Gitea 28.1.0 instance seeded through its API with an invented world (12 -people, 4 organisations, 16 public repositories, 320 issues with about 600 -comments, labels, milestones, commits, pull requests and releases) was read by -one `capture-browser-scenario` run of 1,217 API reads: 1,218 transactions in -24 s, 10.7 MB of Evidence, nothing dropped. Scenario parents are not on main, -so this run used this commit merged onto the scenario-capture change -(morluto/rea#5182) and packed for the host. - -| | Inline source, previous rules | Evidence-file source with `sibling-pair-variance` | -| --------------------- | ------------------------------------- | ------------------------------------------------- | -| Manifest | `resource_constraint` (96 MiB budget) | built in 4.1 s, 459 MB maximum RSS | -| Tools | 446 (with the budget raised by hand) | 63 | -| Recorded exchanges | 1,218 | 1,218 | -| Tools with one record | 77% | 49% | - -The pair rule templated 25 route families as `{repo_namespace}/{repo_name}`. -A model provider that accepts at most 128 tools refused every request for the -446-tool manifest with HTTP 400. - -The 63-tool environment was then exported, and in the AgentEnv runner its -smoke task passed and twelve generated retrieval tasks scored 12/12 with -`openai/gpt-oss-120b` and 12/12 with `zai-org/GLM-5.3-Flash`, with no provider -errors. The 446-tool manifest had scored 0/12 and 8/12 on its own generated -tasks, the 0 being the provider's tool limit rather than the model. - -Review then found that the rule as run here also merged one id's -sub-resources (`/users/alice/followers`, `/users/bob/following` and -`/users/carol/starred` became one tool), and a pair now qualifies only when a -literal follows it. The Gitea capture above predates that guard and has not -been projected with it: whether any of the 63 tools merged sub-resources this -way, and the tool count with bare `/repos/{owner}/{repo}` routes kept one per -pair, are not established here. - -## Linux follow-up (2026-10-20) - -Based on `dd2bf3565`, including main `5fa4defcb`, with Node 24.18.0 and npm -11.16.0. The file reader now owns authentication; invalid Evidence returns the -selected file path and file-relative `content_issues`. Service and advertised -MCP error-envelope regressions cover this boundary. - -- Domain analysis views, application analysis views and error projection: - 16 files, 298 tests passed. -- Compiled analysis-view CLI/MCP and environment serve/export boundaries: - 5 files, 48 tests passed. -- Serial Turbo run: typecheck, lint, format, knip, package metadata and required - runtime/contract artifacts: 11 tasks passed. Documentation/catalog validation: - 8 tasks passed. Architecture guards passed across 1,595 source files. -- Real Gitea 28.2.0 official Linux binary (published compressed SHA-256 checked), - isolated SQLite database, two users and three public repositories with large - issue bodies. Actual Chromium navigation captured nine API transactions, - 45 events, no drops, 12,584,312 bytes of Evidence. Inline manifest projection - was refused with `resource_constraint`; file CLI and default stdio MCP - projections agreed on five tools with all template rules selected. The - three trailing user sub-resources stayed separate. Malformed file diagnostics - named the file's JSON root. HTTP SDK replay verified six complete small - responses and twelve exact 256 KiB prefixes of large responses, each marked - truncated. Owned Gitea, browser and replay-server processes were stopped. - -One CPU and one test worker were used. Sampled sum of descendant RSS every -50 ms (shared pages can count twice): focused tests 15.834 s / 15.327 CPU s / -764.69 MiB peak; boundaries 194.916 s / 190.121 CPU s / 1,795.15 MiB; -static/build 266.311 s / 259.658 CPU s / 4,677.44 MiB; real Gitea workflow -31.631 s / 24.999 CPU s / 2,146.29 MiB. These are individual runs, not a -cold/warm comparison; model token usage was not measured. The first external -probe stopped at the expected CLI refusal because its driver rejected exit 1; -the driver was corrected and the complete workflow passed. No new macOS, -Windows, model-task scoring or AgentEnv runner verification is claimed here. diff --git a/docs/specs/agent-environments/scenario-capture/plan.md b/docs/specs/agent-environments/scenario-capture/plan.md deleted file mode 100644 index c287a7d4ce..0000000000 --- a/docs/specs/agent-environments/scenario-capture/plan.md +++ /dev/null @@ -1,20 +0,0 @@ -# Implementation plan - -1. Add `src/domain/analysisView/scenarioCaptureRecords.ts`: index scenario - events by transaction, project each request event as a HAR-shaped - `WebNetworkCaptureRecord`, and admit a scenario parent for the manifest - view (clone budget, schema, network-content selection). -2. Route `projectEnvironmentManifestView` through one capture-parent gate that - selects the HAR or scenario admission by parent operation, and widen the - environment-manifest result's `parent_operation`. -3. Branch `parseCaptureEvidence` in `environmentSource.ts` on the Evidence - operation, carry the capture kind and digest on the source, and word the - bundle README and CLI help for both kinds. -4. Add a schema-valid scenario capture fixture and domain and services tests: - the record projection, the manifest from a scenario parent, the refusal, - replay of UTF-8 and binary bodies, and the bundle README. -5. Document scenario parents in `docs/agent-environments.md` and - `docs/guides/web/web-network-captures.md`, extend the tool contract text, and record - the spec. - -No new dependency is introduced and no command is added. diff --git a/docs/specs/agent-environments/scenario-capture/spec.md b/docs/specs/agent-environments/scenario-capture/spec.md deleted file mode 100644 index 9a8ce2f93d..0000000000 --- a/docs/specs/agent-environments/scenario-capture/spec.md +++ /dev/null @@ -1,68 +0,0 @@ -# Build environments from browser scenario captures - -Issue: https://github.com/morluto/rea/issues/4933 - -## Outcome - -The `environment-manifest` view, `environment-serve` and `environment-export` -accept `capture_browser_scenario` Evidence as the manifest's parent, in -addition to `inspect_web_network_capture` HAR Evidence. A session REA records -itself, in a browser it launches, with credential headers and declared secrets -redacted, becomes an agent environment without an external capture script or -HAR scrubbing step. The replay, the tool surface and the bundle layout do not -change. - -## Requirements - -- A scenario parent is admitted only when its scenario selected - `capture.network.response_body` or `header_values`, because tools are chosen - by response media type; otherwise the view refuses with - `unsupported_target`. -- Each network transaction becomes one record in request order; its ordinal - is the zero-based position of its `request` event, and its location is the - JSON pointer of that event in the capture. The record is shaped like a HAR - entry: request method and URL, the request body as `postData` when it was - captured and decodes as UTF-8, the response status, and the response media - type with its retained bytes as base64 content and a retained binary field. -- A transaction whose URL the scenario redacted keeps a null URL, so no path - template is formed from a redaction marker. A transaction that does not - resolve to exactly one request event, at most one response event and at most - one content event per phase keeps no request line. Both are counted as - unrepresented records, as HAR records without a usable request line are. -- The response media type is the captured body's `media_type`, or the - `content-type` header value when only headers were captured. -- The existing projection representation budget reserves, before schema body - validation or request-body decoding and for retained and file parents alike, - the scratch of validating the largest body (two bytes per base64 character) - and the decoded text of every request body; response bodies stay borrowed, - as HAR response text does, so a large capture read from its file is not - charged per character for them. Over-budget captures return - `resource_constraint` before those allocations. Replay projection omits the - request text used only for manifest body-shape inference; retained response - bytes and their integrity checks are unchanged. -- The manifest result names `parent_operation: "capture_browser_scenario"`, - carries an empty `artifact` (`path: ""`, `sha256: null`) and states, as - limitations, the ordinal rule, any dropped capture events, how many - transactions with a usable request line retained no response body (tools - citing them replay only the recorded status and content type, either of - which may be absent) and how many retained response bodies carry redaction - markers. Both counts use the same request-line admission as manifest grouping, - so unredacted URLs without a usable transport origin and recorded path contribute - to neither numerator nor denominator. A body that redaction emptied, because a declared secret could not - be cut out, is treated as not retained rather than replayed as an empty - reply. -- `environment-serve` and `environment-export` authenticate either parent - kind through the same loader, project scenario transactions through the same - adapter, and keep the cross-check that the manifest's parent is the supplied - Evidence. The bundle README names the capture kind and, for a scenario, the - SHA-256 of the scenario definition in place of a capture artifact digest. - -## Non-goals - -- No new browser action: scenarios still cover what the UI requests plus GET - reads through `goto`. A fetch or script action would be a new effect and - needs its own scope decision. (The `request` action was later scoped and - added by [environment-prompt](../environment-prompt/spec.md).) -- No change to what the scenario redacts. Values the application returns in - response bodies are retained, as they are in HAR captures. -- The api-surface view keeps HAR parents only. diff --git a/docs/specs/agent-environments/scenario-capture/tasks.md b/docs/specs/agent-environments/scenario-capture/tasks.md deleted file mode 100644 index bdc8ecf0d6..0000000000 --- a/docs/specs/agent-environments/scenario-capture/tasks.md +++ /dev/null @@ -1,10 +0,0 @@ -# Tasks - -- [x] Record the scenario-parent contract, requirements and non-goals. -- [x] Project scenario transactions as HAR-shaped records and admit scenario parents. -- [x] Route the manifest view through one capture-parent gate and widen its result schema. -- [x] Load scenario Evidence in serve and export; name the capture kind in the README and help. -- [x] Add the scenario capture fixture and domain and services tests. -- [x] Document scenario parents and extend the tool contract text. -- [x] Run static, formatting, duplication, documentation and test gates. -- [x] Build environments from real browser scenario captures and record the results. diff --git a/docs/specs/agent-environments/scenario-capture/verification.md b/docs/specs/agent-environments/scenario-capture/verification.md deleted file mode 100644 index d85376eefe..0000000000 --- a/docs/specs/agent-environments/scenario-capture/verification.md +++ /dev/null @@ -1,144 +0,0 @@ -# Verification - -Verified commit: 3c2a8db2, this increment on top of the environment-export increment (481c9883). - -## Gates - -Run on macOS 26.5.1 with Node 22.23.1 on that tree: - -- `npx tsc --noEmit`: no errors. -- `oxfmt --check`: all files formatted. `oxlint` on the changed files: no new findings. - `npm run verify:module-boundaries`: 2133 files checked. -- `npm run jscpd`: 3.35% duplicated lines, unchanged. `npm run scan:todos`: none. - `npm run mcp-catalog:check`: passed. `npx knip`: one unresolved import that predates - this change (`#javascript-analysis-worker`). -- `npm run test:prepare`, then vitest over `src/domain/analysisView`, `src/application`, - `src/contracts`, `src/server/environment`, `tests/conformance` and the analysis-view, - environment-serve, environment-export and browser-scenario boundary tests: 1946 tests in - 157 files, 1941 passed, 5 skipped, 0 failed. - -## Real browser captures - -`npm pack` of this commit (`rea-agents-6.7.0.tgz`) was installed on Ubuntu 24.04 amd64 hosts -(8 vCPU, 32 GB) with Chromium 155.0.8059.79 at `/snap/bin/chromium`, Node 24, Docker and -`agentenv-framework` 0.9.1334. Every capture below is `rea capture-browser-scenario` output; -no HAR was recorded, scoped or edited. - -### Fixture - -A loopback fixture served a page that lists photos from `/api/photos`, three PNG thumbnails, and -a form that POSTs JSON to `/api/albums`. The scenario waited for the list, opened -`/api/photos/1..3` with `goto`, filled and submitted the form. - -- Capture: 14 transactions, 70 events, 0 dropped, authority `controlled-replay`. -- `environment-manifest`: `parent_operation` `capture_browser_scenario`, origin - `http://127.0.0.1:3199`, confidence `inferred`. Tools `get_photos` (records 1, 9), - `get_photos_by_id` (`{numeric}` id, records 5, 6, 7) and `post_albums` (record 13, body shape - `title: string`). The page and the three PNGs were excluded as `ui-page-or-asset`. -- `environment-serve`: `get_photos_by_id {id: "3"}` returned the recorded JSON with - `record_ordinal` 7 and `exact_match` true. -- The POST's response body was missing: the scenario ended at the action that sent it, the - transaction was still unfinished, and the observer does not read bodies of unfinished - responses. The manifest stated "1 of 14 scenario transactions retained no response body" and - `post_albums` replayed status 201 with no body. Ending the scenario with a 1.5 s - `wait_for_timeout` finished all 14 transactions and retained the body. -- `environment-export` of that capture wrote a README naming the browser scenario capture and the - scenario definition's SHA-256; `agent-env run --task smoke` passed in 30.4 s. - -### Five applications - -Each environment ran manifest, export, the bundle's smoke task and 6 to 12 generated retrieval -tasks, with one run per task for two models through the Hugging Face router. - -| Application | Capture | Actions | Transactions | Tools (rules / none) | Smoke | Retrieval tasks | gpt-oss-120b | GLM-5.3-Flash | -| ---------------------------- | ------------------------------------------------------------------ | ------- | ------------ | -------------------- | ------ | --------------- | ------------ | ------------- | -| PhotoPrism 261007 | self-hosted, no login (public mode) | 55 | 277 | 13 / 28 | passed | 10 | 10/10 | 10/10 | -| Lychee 6.10.4 | self-hosted, session cookie seeded from a declared secret | 152 | 134 | 15 / 27 | passed | 12 | 11/12 | 12/12 | -| Pinry 2.1.13 | self-hosted, session and CSRF cookies seeded from declared secrets | 148 | 568 | 12 / 12 | passed | 6 | 6/6 | 6/6 | -| Art Institute of Chicago API | public, `goto` per URL | 52 | 26 | 11 / 12 | passed | 12 | 11/12 | 12/12 | -| Library of Congress JSON API | public, `goto` per URL | 55 | 29 | 11 / 11 | passed | 12 | 11/12 | 12/12 | - -Every scenario step completed and no capture dropped events. Each self-hosted capture includes -one create, one edit and one delete made through the application's own forms; all three became -tools with their recorded statuses, including a 204 DELETE without a content type. Declared -secrets did not appear in any capture; where the application echoed a declared value in a -response body (PhotoPrism's session reply, Pinry's owner token) the capture held the redaction -marker instead. - -Two other targets were tried and replaced. The Met Collection API projected 3 tools: its data -paths are `/departments`, `/objects/{id}` and a search, and numeric object ids merge into one -tool. The NASA Image and Video Library projected 16 tools, but its Collection+JSON bodies nest -record fields deeper than the task generator reads, so no tasks could be derived. - -## Observed limits - -These were observed during the runs and are outside this increment: - -- A scenario's last action can lose its response body unless the scenario ends with a wait - (above). -- Large asset bodies count against the analysis-view budget. One Pinry capture at - `max_network_body_bytes` 262144 held 12.5 MB of Evidence, mostly CSS and JavaScript reloaded - on 33 page loads, and the manifest view returned `resource_constraint`. A 20,000-byte body - limit kept it within budget. Scenarios have no per-origin or per-media-type body selection. -- Image responses outside an API path are excluded as UI assets, so their bytes are replayable - only when an API path serves them (PhotoPrism's `/api/v1/t/...` tiles became tools). -- With the default `max_total_event_allocation_bytes`, one PhotoPrism capture dropped its last - 68 transactions, including all three writes, while the command exited 0; 64 MiB dropped none. -- Actions have no default deadline: two runs waited on a locator for 277 s and 7.5 min until - cancelled. Every scenario above sets `timeout_ms` on its actions. -- A redirect is its own transaction; Django's trailing-slash 301 produced a second tool - (`get_pins_by_id` and `get_pins_by_id_2`) for one resource. - -## Linux followup verification (2026-10-19) - -The original PR was merged with current main `7a0c47bfa`, after #4955, #4975 -and #4999 merged. The export filesystem ownership, mode, tarball, cleanup and -caller-path fixes from main are retained. Default MCP remains stdio. - -The retained-parent projection previously decoded every request body before -per-record budget checks. It now reserves copied/transformed text through the -shared admission owner before schema validation or decoding, including retained -parents. Replay projection omits request text used only for body-shape inference; -response bytes still undergo the producer schema's integrity validation. The -intermediate projected-array copy and unused capture wrapper were removed. -Windows test inventories normalize filesystem separators to the portable bundle -path representation. CI selects the agentenv lane for the new projection and its -shared admission dependencies. - -Executed on Linux x64, Node 24.18.0 / npm 11.16.0, Chrome for Testing -156.0.8078.4: - -- `turbo run typecheck lint:built format:check docs:check:built knip artifacts:skills artifacts:mcp-catalog --concurrency=1 --summarize`: eleven tasks passed, one cached, 210.023 s elapsed / 209.860 s CPU / 4562.07 MiB peak process-family RSS. This first complete gate preceded the final lint cleanup and CI-selection additions; later checks are reported on the PR. -- Initial source verification passed 111 tests in 13 files, including HAR/manifest regressions, scenario loading/replay/export and new capacity/replay-mode tests. CI-selection verification passed 235 cases. -- Real public CLI capture of the source-owned interactive browser network site: ten transactions, fifty events, two tools, no dropped events. Its POST response replayed twice through the official HTTP SDK with exact body/status/Evidence ordinal and untrusted-content provenance. Declared secrets and transport credentials were excluded; the ordinary selected `password` field value remained in retained body bytes. -- Real public CLI capture of three live GitHub API responses in Chromium, without a HAR: three transactions, fifteen events, three tools, no dropped events. Every response replayed twice through the HTTP SDK with exact body/status/Evidence/provenance. Explicit navigation waits let response-body capture settle. Complete two-scenario capture/projection/serve task: **22.527 s / 16.678 s CPU / 1397.93 MiB** peak process-family RSS, including owned browser processes. Both listeners exited 143 and newly owned browser profiles were gone. -- The same two actual captures produced identical manifest results through CLI and official SDK **stdio** MCP, with HTTP environment variables present: **2.795 s / 2.778 s CPU / 476.67 MiB**. This verifies adapter parity and default transport independently of explicit environment HTTP. - -The first local probe mistakenly searched base64 body content for plaintext; its -assertion was corrected to inspect decoded retained bytes. A later SDK probe -initially imported stdio transport from the SDK root instead of its documented -subpath; the corrected probe passed. An early live navigation also reported one -`body-read-failed` response, which the projection preserved as unavailable. No -browser-provider behavior was changed; the successful run used explicit waits. -These earlier attempts are not counted as passing runs. - -A matched retained-scenario projection comparison bundles the original helper -from `3aae3579e` and the followup helper, supplies the same 72,771-byte capture -with three JSON writes, and completes one cold plus 100 warm full manifest -projections. Both outputs have the same SHA-256 -`990ac431670374ff68c77a20d77985f626e4681bb0e2f491e5af18f45ce79991`. -Before/after process totals: **0.970/0.876 s elapsed, 0.934/0.865 s CPU, -184.89/184.39 MiB** RSS. First task: **17.378/13.073 ms**; 100 warm tasks: -**261.419/236.131 ms**. Single samples do not establish a speed or memory -improvement. Bundle preparation is excluded; process totals include fixture -startup. CLI, provider and transport costs are excluded from this comparison. - -Heavy work is serialized on one CPU with one test worker. RSS sums sampled -process descendants every 50 ms and can double-count shared pages. Agent token -usage is unmeasured. These followups do not rerun the author's five application -reconstruction/model tasks, nor establish Windows or macOS behavior. Historical -response replay does not reconstruct application state. - -A retained-parent counterexample used a 128 KiB projection budget and one 16 KiB JSON request: the original helper admitted it and decoded once; the repaired helper returned `AnalysisResourceConstraintError` with zero UTF-8 decodes. The test intentionally uses a small budget without inducing an OOM. Final targeted verification passed 242 tests (including 235 CI-selection cases): 41.042 s / 40.666 s CPU / 644.37 MiB peak process-family RSS. - -The broader d2416ca54 regression run passed 657 tests in 47 files plus ten product-catalog cases (295.763 s / 293.370 s CPU / 1921.69 MiB family RSS; catalog checked separately). The author then pushed 655e62334 with redaction/body-budget documentation and withheld-empty-body behavior. That commit was retained; the followup counts bodiless/redacted observations against represented transactions, preserving the complete request ordinals. The related source run passed 145 tests in 14 files (9.793 s / 9.618 s CPU / 688.66 MiB). Docker execution was held at this author-update checkpoint, so no earlier bundle is attributed to the new source. Final committed checks and actual scenario-container/framework results are reported on the PR. diff --git a/docs/specs/agent-environments/scenario-saved-values/plan.md b/docs/specs/agent-environments/scenario-saved-values/plan.md deleted file mode 100644 index bab1e29f72..0000000000 --- a/docs/specs/agent-environments/scenario-saved-values/plan.md +++ /dev/null @@ -1,23 +0,0 @@ -# Plan - -1. Schema: `save` on request steps, `save_response` on click and press, the - `saved` value source in headers and credential parts, `basic_credentials` - with two parts, and the `{saved:name}` placeholder. -2. Validation: every saved value a step sends was saved by an earlier step. -3. Runtime: read the response body when a step saves, start waiting for a UI - step's response before it acts, keep saved values with their JSON type, - fill placeholders, build Basic credentials, and redact secret saves. -4. Evidence: record the current parsed step, including an empty `save` list; - preserve the representation and identity of retained Evidence. -5. Environment build: warn about credential-named saved values not marked - secret. -6. Skill and docs: write through the UI first and save ids instead of guessing - them; bump the skill version. -7. Tests: schema, runtime with a fake page, Evidence parameters, the build - warning, the catalog budget, and a real-Chrome recording. -8. Write model: compose strings from generated ids and other fields, learn the - `&` spelling of slugs, tell apart addresses whose parts are the same text, - and check templates on later creates; census every recorded capture. -9. End to end: agents build environments from prompts with main and with this - branch on the same applications, and the branch's recordings are rebuilt - before and after the write-model changes. diff --git a/docs/specs/agent-environments/scenario-saved-values/spec.md b/docs/specs/agent-environments/scenario-saved-values/spec.md deleted file mode 100644 index 4983ba6580..0000000000 --- a/docs/specs/agent-environments/scenario-saved-values/spec.md +++ /dev/null @@ -1,73 +0,0 @@ -# Saved values in browser scenarios - -## Outcome - -A browser scenario could not carry a value from one step to a later one. An -agent recording an application from a prompt therefore guessed the id of the -object it had just created, created probe objects to learn the next id, or -read the object back by list only. An API that takes Basic auth, or a header a -frontend builds from a login token, could not be sent at all, so the agent -stopped and asked for an API key. - -Steps now save strings and numbers from JSON responses, and later steps send -them. A click or key press saves from a newly observed matching response, -so a scenario can create an object the way the application's UI does and then -open, read, edit or delete it by the id the application assigned. A request -header can send Basic credentials built from literal, secret, saved or page -values. - -## Requirements - -- A `request` step saves `[{name, json_pointer, secret}]` from its own JSON - response. A `click` or `press` step's `save_response: {method, path, save}` - saves from the first response that matches its method and a path on the start - origin (`{*}` matches one segment; the query is ignored), which must be 2xx - JSON. The wait starts before the step acts, and the step fails, saving - nothing, unless such a response arrives and is read before its timeout or - cancellation. -- A pointer that names no string or number, a number that is not finite (such as - `1e400`), a response that is not JSON or is larger than 4,000,000 characters - (a UI step reads none received as more than 12,000,000 bytes, three per - character), and a non-2xx `save_response` fail the step. -- `{saved:name}` sends a saved value, percent-encoded, in a request path and its - query and in a goto URL, and in a request's JSON body: a string that is only - the placeholder becomes the saved value with its JSON type, and a placeholder - inside a longer string is filled as text. Header values and Basic credential - parts send `{source: "saved", name}`. Other braces are sent as written. A - saved value that makes a path segment `.` or `..`, alone or with the text - beside it, fails the step. -- `basic_credentials` sends the base64 of `username:password` from `parts: - [username, password]`, each a literal, declared secret, saved value, cookie or - local storage entry. The encoded value and parts read from the page are - redacted as page values are. A username with a colon fails the step. -- Validation refuses a saved value no earlier step saves. -- A scenario keeps at most 4,000,000 characters of saved values at once, counting - the redaction spellings of values saved as secret; a save past that fails its - step before the value is kept. -- A value saved with `secret: true` is redacted from the selected source response - before retention and from subsequent records. The environment build warns about saved values named like credentials - that are not marked secret (`credential-named-saved-values`). -- New Evidence records the current parsed request step, including an empty - `save` list, in its parameters and `scenario_sha256`. Retained Evidence keeps - its original representation and identity. -- The compact MCP catalog stays under its measured one-megabyte frame. -- The skill records writes the way the application's UI does and falls back to - request steps when the UI cannot reach an operation or coverage withholds the - UI-shaped write. -- A UI-made create must be served as faithfully as one made through the API: - - a string composed from a generated id and another field, such as Grafana's - folder address, is learned as composed, not as a template around the id; - - a slug learns how the application spells `&` from the call that shows it, - and held entities that spell it both ways leave no slug rule; - - an id that equals the title's slug is told apart by the entities the type - holds, or by a later create; - - a template a later create answers otherwise is withheld, as a composed - string is. - -## Non-goals - -- No general value transforms, string templates or script steps: the value - kinds are fixed. -- No saved values in `fill` or `select_option` values. -- No retroactive redaction of earlier unrelated records. -- No multi-factor sign-in. diff --git a/docs/specs/agent-environments/scenario-saved-values/tasks.md b/docs/specs/agent-environments/scenario-saved-values/tasks.md deleted file mode 100644 index c5a4915539..0000000000 --- a/docs/specs/agent-environments/scenario-saved-values/tasks.md +++ /dev/null @@ -1,15 +0,0 @@ -# Tasks - -- [x] Record the outcome, requirements and non-goals. -- [x] Add saved values, `save_response` and Basic credentials to the scenario schema. -- [x] Validate that saved values are saved before use. -- [x] Save and send values in the Playwright runtime. -- [x] Keep scenarios that save nothing byte-identical in Evidence. -- [x] Warn about credential-named saved values not marked secret. -- [x] Update the skill and docs. -- [x] Add unit, boundary and real-browser checks. -- [x] Run the gates. -- [x] Build prompt-recorded environments with main and with this branch. -- [x] Make the skill's recording example write through the UI. -- [x] Learn the addresses a UI-made create spells, and check templates on later creates. -- [x] Rebuild the branch's recordings with the write-model changes and record every application again. diff --git a/docs/specs/agent-environments/scenario-saved-values/verification.md b/docs/specs/agent-environments/scenario-saved-values/verification.md deleted file mode 100644 index bba226d037..0000000000 --- a/docs/specs/agent-environments/scenario-saved-values/verification.md +++ /dev/null @@ -1,138 +0,0 @@ -# Verification - -This is Edgar Arakelyan's historical verification record from upstream PR #7162 -(head `d39f386d202fe8e98592fb2d9d26e43d8d0fb94f`), retained with attribution. -These multi-application and model evaluations were not rerun during integration. -The independent integration measurements and their limits are recorded in -[saved-values integration verification](../../../verification/browser-saved-values-2026-10-26.md). - -Executed on macOS with Node v24.22.1 at `feat/recorder-saved-values` e42362c9 (on main 2b84efe0), and on Ubuntu 24.04 -VMs with snap Chromium for the agent recordings. - -## Gates - -- `npm run typecheck`, `lint:built`, `format:check`, `metadata:check`, `verify:architecture-guards`, `knip:production`, - `lint:typed`, `docs:check`, `mcp-catalog:check`, `verify:test-discovery`, `scan:todos` and `jscpd`: passed. - `knip` reports one unused export, `isToolFamilyId` in `src/contracts/toolFamilies.ts`, which this branch does not - touch and main 2b84efe0 reports too. -- `npx vitest run --project domain --project services --project adapters`: 18,261 passed and 1 failed, "stops Inspector - target authorization after the current stat settles", which fails the same way on main in this environment. -- Browser scenario CLI and MCP boundaries, scenario input diagnostics, cancellation and cleanup, the analysis-view CLI - and MCP boundaries, the environment build, export and serve CLI boundaries, the environment serve, served-writes and - bundle MCP boundaries, tool schema validity, MCP schema validation, and output schema constraints and profile: 17 - files, 128 passed. -- The compact MCP catalog must stay under the one-megabyte frame `outputSchemaProfile.test.ts` measures. A first - design with `path_params` on request and goto steps, `json_values`, and separate `username` and `password` unions - added 9,391 bytes on main ff6d96bc and failed the test, which then had 5,731 bytes to spare. Saved values now travel - as `{saved:name}` placeholders, Basic credentials repeat their part union once, and repeated inner descriptions were - dropped: on main 2b84efe0 the catalog takes 1,038,975 bytes and this branch 1,042,639. - -## Compatibility - -- Scenarios that save nothing record the same Evidence parameters and `scenario_sha256` on main and on this branch: a - UI-only scenario with a goto to a URL holding literal braces, and a request step with a secret query value, a cookie - header, and literal braces in its path and JSON body. -- Main reads a capture that uses saved values: `environment-build --dry-run` of the real-Chrome capture below gives the - same manifest, state, coverage and file plan on main and on this branch. This branch adds the - `credential-named-saved-values` warning. -- Write plans for 109 captures (the 50 published captures, 29 earlier agent recordings and the 30 recorded in the - comparison below), built by main and by this branch: 524 plans and 247 served on each. Three plans differ, all - Grafana folder creates recorded below, whose `url` the branch composes from the uid and the title's slug where main - learned a template or nothing. - -## Real Chrome - -A local application with a cookie-session UI and an API that takes only Basic auth, recorded with Google Chrome: - -- fill a name and click Save with `save_response` on `POST /ui/items`, saving the new id; -- `goto` `/items/{saved:item1}` and wait for the item's page; -- `GET /api/items/{saved:item1}` with Basic credentials whose username comes from local storage and password from a - declared secret; -- `POST /api/tokens`, saving the token both as a secret and, unmarked, as `session_token`; -- `POST /api/items` with the saved token in a header and `{"name": "Child of {saved:item1}", "ref": "{saved:item1}"}`; -- `PATCH /api/items/{saved:child}` and `GET /api/items?parent={saved:item1}`. - -All 11 steps completed. The requests went to `/items/101`, `/api/items/101`, `/api/items/108` and `?parent=101`, and the -body sent was `{"name":"Child of 101","ref":101}`. The Evidence parameters keep the placeholders, the password appears -nowhere in the capture, and the token header is recorded as `[REDACTED:page:token.api_token]`. The token's own response -was redacted too in this run; the docs say it may not be, since the recorder reads bodies on their own schedule. -`environment-build` warned about `/parameters/actions/7/save/1`. - -## Agent-built environments, main and this branch - -Claude Code (`claude-sonnet-5-5`) built an environment of each application from the same prompt, with REA main -ff6d96bc (skill 49) and with this branch (skill 50), on freshly seeded instances. Each bundle was rebuilt by the REA it -was recorded with, and its write tasks run with `fireworks_ai/gpt-oss-120b` and `fireworks_ai/glm-5p3-flash`. Each task -checks its result from the environment's state, including that nothing else changed. - -The branch was recorded three times as it changed: - -1. With the skill as first written, EspoCRM's agent wrote through request steps with Basic credentials instead of the - UI, and EspoCRM's API answers in a shape the write model withholds (0/3). The skill's recording example created its - object with a request step, which agents copy; it now creates through the UI with `save_response`. -2. With that example, Grafana's agent created folders through the UI, where Grafana generates the uid. REA then learned - the folder's `url` as a template around the uid that kept the first folder's slug, and coverage did not check the - template against the second folder, so served creates answered with wrong addresses (0/2). The write-model fixes - in this PR compose the address from the uid and the title's slug, learn Grafana's `&` spelling, and check templates - on later creates. -3. With both, every application was recorded again. - -**The same recordings, before and after the write-model fixes.** Run 2's captures, rebuilt by this branch before and -after the fixes (gpt-oss, GLM): - -| Application | Before | After | -| ----------- | ------------- | ------------- | -| Miniflux | 3/3 3/3 | 3/3 3/3 | -| Paperless | 1/3 2/3 | 1/3 1/3 | -| Vikunja | 1/3 1/3 + 0/2 | 1/3 1/3 + 0/2 | -| Linkding | 0/2 0/2 | 0/2 0/2 | -| Homebox | 0/2 0/2 | 0/2 0/2 | -| Grafana | 0/2 0/2 | 2/2 2/2 | -| EspoCRM | 1/3 1/3 | 1/3 1/3 | - -Only Grafana's plans change, and its tasks pass. Paperless's plans are identical in both builds; its GLM difference is -the eval model's. - -**Fresh recordings, main and the final branch:** - -| Application | Write tasks | Main: served, tasks | Branch: served, tasks | -| ----------- | ----------- | ---------------------- | --------------------- | -| Miniflux | 3 | no bundle | 4, 3/3 3/3 | -| Paperless | 3 | 3, 1/3 1/3; 6, 2/3 2/3 | 6, 1/3 2/3 | -| Vikunja | 3 + 2 | 1, 0/3 0/3 + 0/2 0/2 | 3, 1/3 1/3 + 2/2 2/2 | -| Linkding | 2 | 0, 0/2 0/2 | 3, 0/2 0/2 | -| Homebox | 2 | 1, 0/2 0/2 | 5, 0/2 0/2 | -| Grafana | 2 | 2, 2/2 2/2; 3, 2/2 2/2 | 1, 1/2 1/2 | -| EspoCRM | 3 | 2, 1/3 1/3 | 2, 0/3 0/3 | -| Total | 20 | 9, 4/20 4/20 | 24, 8/20 9/20 | - -"Served" counts the write tools the final capture serves; tasks are gpt-oss then GLM, and Miniflux's count as failed -without a bundle. Paperless and Grafana were recorded twice on main; totals use the first run. - -- **Miniflux:** main's agent stopped and asked for an API key, since the API takes Basic auth. With Basic credentials - the branch served category create, rename and delete in all three runs, and every category task passed with both - models. -- **Vikunja:** label edits and deletes are served and pass in two of the three branch runs, and task deletes in the - last two. -- **Saved ids:** every branch agent saved ids, with `save_response` on UI writes, and read objects back by them. On main - no step can carry a value to a later one, so agents chose their own ids or read lists back instead. -- **Paperless:** the two main runs differ as much as main and the branch do. -- **Linkding and Homebox** serve more writes, but their create tasks still fail. Linkding's served create requires every - member its recorded calls sent (`description`, `notes`, `unread`, `shared`, `tag_names`), so a task that sends a URL - and a title is refused. -- **Grafana:** the folder create is served with the right address and its task passes. The rename is withheld: - Grafana lists folders sorted by title, the recording renamed a folder to a title that sorts first, and REA keeps an - updated entity where it was in a list. Main's REA reads this recording the same way, and serves its create with the - template that keeps the first folder's slug, so the create task would fail too. Main's two recordings passed because - their titles kept their order. -- **EspoCRM:** the recording started with a contact an earlier attempt in the same session created and left, so the - environment holds it as seeded data and every task's "nothing else changed" check fails. The skill now asks agents to - delete what an earlier attempt created before recording again; that change was not measured. -- Agents spent $9.98 and 3,149 seconds in total on the fresh branch run, against $7.45 and 2,235 on main, a third of it - Homebox's. - -## Not verified - -- One fresh recording per application and version, two for Paperless and Grafana on main; agent runs vary. -- Lists sorted by a field that an update changes, and the skill's cleanup of earlier attempts. -- Multi-factor sign-in, and saved values in `fill` or `select_option` steps, which this change does not add. diff --git a/docs/specs/agent-environments/scenario-timing/plan.md b/docs/specs/agent-environments/scenario-timing/plan.md deleted file mode 100644 index 3d2646c6ea..0000000000 --- a/docs/specs/agent-environments/scenario-timing/plan.md +++ /dev/null @@ -1,23 +0,0 @@ -# Plan - -1. Schema: optional `observed_at` (ISO date-time) on `request` events, and - `started_at` (ISO date-time) and `elapsed_ms` (non-negative number) on - `request-finished` and `request-failed` events. -2. Collector: stamp `observed_at` when a request is observed and copy the - browser's `timing().startTime` and `responseEnd` into `started_at` and - `elapsed_ms` when it reports them, admitting the strings with the other - metadata. -3. Records: index each transaction's single finished or failed start and - duration and give each attributable record `startedDateTime` and `time`; - add a limitation when any record is timed. -4. Comparison: drop both fields from network evidence before fingerprinting and - commit the rule in the built-in list and the comparison limitation. -5. Docs: the scenario contract's network evidence and the environment docs' - browser scenario section. -6. Tests: the collector stamps both fields, records take them, the state learns - the HAR's clock and verdicts from a timed scenario and none from an untimed - or partly untimed one, a request that never ended or ended twice falls back - to its observation with unknown duration omitted, an explicit zero remains - observed, comparisons ignore the times (also against an untimed - capture), and the real-Chrome network lane checks every request is observed - and every finished request carries the browser's start and duration. diff --git a/docs/specs/agent-environments/scenario-timing/spec.md b/docs/specs/agent-environments/scenario-timing/spec.md deleted file mode 100644 index b604ffadd0..0000000000 --- a/docs/specs/agent-environments/scenario-timing/spec.md +++ /dev/null @@ -1,44 +0,0 @@ -# Time browser scenario records - -## Outcome - -Browser scenario network events record no times, so every record a scenario -projects is untimed. The environment-state view then orders records by -position, detects no overlapping requests and learns no write clock: an update -whose response carries a modification time the application sets is withheld as -`unexplained-change` however it is recorded, while a HAR of the same session -serves it with a clock rule. - -Scenario network events now record when each request was observed and how long -the browser took, and scenario records carry them as HAR entries do, so a -scenario capture learns the clock a HAR does. - -## Requirements - -- Each `request` event carries `observed_at`, the ISO wall-clock time the - provider observed the request start; Playwright reports the browser's start - only once a request ends. -- Each `request-finished` and `request-failed` event carries `started_at`, the - browser's wall-clock start (`timing().startTime > 0`), and `elapsed_ms`, its - time from that start to the end of the response (`timing().responseEnd >= 0`), - when the browser reports them. -- The fields are optional in the schema, so Evidence captured before them still - parses and is read exactly as before. REA versions before them refuse - Evidence that carries them. -- Scenario records take `startedDateTime` from the transaction's single - finished or failed event's `started_at`, else from `observed_at`, and `time` - from its `elapsed_ms`, omitted without a unique reported duration, and say so - in a limitation. An explicit zero remains zero. Complete starts establish the - recorded-start-time timeline; a write clock also requires known completions. -- Scenario comparisons ignore both fields, as a committed built-in rule - (`ignore_network_request_timing`). -- The added metadata is charged to the event budgets as other metadata is. - -## Non-goals - -- No change to HAR captures, to how the state uses times, or to what a - record's timing means for overlap or clock rules. -- No retroactive timing of captures made before this change. -- No browser start for a request that never ended: its record starts at - `observed_at`, which can trail the browser's start by tens of milliseconds - while the provider reads other responses, with no duration. diff --git a/docs/specs/agent-environments/scenario-timing/tasks.md b/docs/specs/agent-environments/scenario-timing/tasks.md deleted file mode 100644 index ab09524d98..0000000000 --- a/docs/specs/agent-environments/scenario-timing/tasks.md +++ /dev/null @@ -1,13 +0,0 @@ -# Tasks - -- [x] Record the outcome, requirements and non-goals. -- [x] Add the optional timing fields to scenario network events. -- [x] Stamp them in the Playwright network collector. -- [x] Time scenario records from them. -- [x] Leave them out of scenario comparisons. -- [x] Document the fields and the timed records. -- [x] Add unit, view and real-browser checks. -- [x] Run the gates. -- [x] Re-record stale scenario environments and compare them with their published versions. -- [x] Build prompt-recorded environments with and without request times. -- [x] Address the independent review. diff --git a/docs/specs/agent-environments/scenario-timing/verification.md b/docs/specs/agent-environments/scenario-timing/verification.md deleted file mode 100644 index 5591b9da8c..0000000000 --- a/docs/specs/agent-environments/scenario-timing/verification.md +++ /dev/null @@ -1,73 +0,0 @@ -# Verification - -Executed on macOS with Node v24.22.1 at `feat/scenario-request-timing` b92a11b6 (on main d87e73f2), and on Ubuntu 24.04 -VMs with snap Chromium 155 for the recordings. - -## Gates - -- `npm run -s typecheck`, `lint`, `format:check`, `docs:check`, `mcp-catalog:check`, `verify:test-discovery`, - `scan:todos` and `npx knip`: passed. -- `npx vitest run --project domain --project services --project adapters`: 16,380 passed and 1 failed, "stops Inspector - target authorization after the current stat settles", which fails the same way on main in this environment. -- Browser and scenario MCP and CLI boundaries, tool schema validity and the analysis-view MCP boundary: passed. -- `npm run -s verify:browser:network` in real Chrome: every one of the 10 requests carries `observed_at`, and every - finished request carries the browser's `started_at` and `elapsed_ms` (9 of 10; the tenth is the fixture's deliberately - unfinished stream). -- Captures made before this change parse and project exactly as before: the published Pinry (568 requests), PhotoPrism - (277) and Lychee (134) captures give byte-identical manifest and state views, Evidence ids and digests included, on - main and on this branch. - -## The same capture with and without request times - -Each capture below was recorded with this branch, then built twice: as recorded, and with its request times removed and -the Evidence sealed again as the provider seals it. The difference is this change alone. - -| Capture | Records | Timeline without / with times | Writes served without / with times | -| ---------------------------------------------- | ------- | ----------------------------- | ---------------------------------- | -| Linkding, agent-recorded from a prompt | 60 | record order / start time | 1 / 4 | -| Linkding, agent-recorded from a prompt (again) | 65 | record order / start time | 3 / 3 | -| Homebox, agent-recorded from a prompt | 263 | record order / start time | 2 / 3 | -| Homebox, agent-recorded from a prompt (again) | 275 | record order / start time | 2 / 2 | -| Pinry, its published scenario re-recorded | 568 | record order / start time | 0 / 0 (1 clock rule learned) | -| PhotoPrism, its published scenario re-recorded | 273 | record order / start time | 2 / 2 (2 clock rules learned) | - -- With times, Linkding's bookmark and bundle edits and Homebox's tag edit are served: their responses carry a - modification time the application sets, which only a clock explains. PhotoPrism's served album create now stamps - `CreatedAt` and `UpdatedAt` from the clock instead of replaying the recorded values. No capture served fewer writes. -- The second Linkding and Homebox recordings gain nothing because their gaps are elsewhere (`unconfirmed` and `contradicted` - writes): an agent's recording choices move coverage more than timing does. -- The prompt-built recordings used a local, unpushed build of this branch merged with the prompt PR (#6946), which adds - the `request` scenario action they need. Claude Code (`claude-sonnet-5-5`) recorded each app from a one-paragraph - prompt, as in that PR's end-to-end check. -- The Linkding bundle with four served writes passes all three of the application's write tasks with - `fireworks_ai/gpt-oss-120b` and `fireworks_ai/glm-5p3-flash` (with the tasks' entity counts taken relative to the - bundle's own state, which holds active and archived bookmarks as two types); the earlier prompt-built Linkding bundles, - recorded without times, passed none. The Homebox bundle passes both of its write tasks with gpt-oss and one with GLM - (GLM deleted the wrong item). The final build's prompt-recorded bundles start and answer retrieval: Linkding - passed its smoke task and 8/8 and 7/8 retrieval tasks, Homebox its smoke task and 3/3 and 3/3. - -## Stale published environments - -Pinry and PhotoPrism are the oldest published environments recorded as browser scenarios (version 0.1.0, replay only). -Both were re-recorded with this branch from their published scenarios on fresh seeded instances and rebuilt with the -publishing pipeline: - -| App | Published 0.1.0 | Rebuilt with this branch | -| ---------- | ------------------------------------------- | ---------------------------------------------------------------------------------- | -| Pinry | 12 tools, replay, retrieval 6/6 and 6/6 | 12 tools, state and clock, no writes served; retrieval 6/6 and 4/6 | -| PhotoPrism | 13 tools, replay, retrieval 10/10 and 10/10 | 14 tools, state and clock, album create and rename served; retrieval 8/10 and 5/10 | - -Neither improves, so neither was republished. The retrieval drops do not come from timing: the timed and untimed states -are identical in every view these tasks read. PhotoPrism's album list is answered from the state in name order while -the recorded response that generated the task listed another album first; Pinry's two GLM misses are tool calls -rejected for passing `limit` and `offset` as numbers, under the same tool schemas the published version had. - -## Review - -An independent review rebuilt the branch and tried to refute it. It confirmed byte-identical views for earlier captures, -that comparisons with and without times compare alike, that each record's duration comes only from its own -transaction, and that both fields are charged to the event budgets. Its findings are addressed: records now start at the -browser's own start time rather than the provider's observation, which trailed it by up to 36 ms while other responses -were read; the docs give the fallback's lag, that earlier REA versions refuse captures carrying the fields, and that the -comparison's normalization digest changes; and tests cover the fallbacks, partly untimed captures and comparisons with -untimed captures. diff --git a/docs/specs/agent-environments/state-coverage/plan.md b/docs/specs/agent-environments/state-coverage/plan.md deleted file mode 100644 index dfe6d688da..0000000000 --- a/docs/specs/agent-environments/state-coverage/plan.md +++ /dev/null @@ -1,32 +0,0 @@ -# Implementation plan - -1. In `environmentStateRules.ts`, parse pointers into tokens and let `at` and - `replaceAt` read and replace element 0 of a one-element array at the root - or in one member; extend `locateItem` with those forms after the object - forms, requiring an identity name there; add `identityCandidates`, the - identity names then suffix-named fields, and let `locateList` prefer arrays - identified by name, then arrays of two or more items identified by suffix. -2. In `EnvironmentStateExtraction.ts`, plan lists with the shared candidates, - treat an empty recording as unconstraining, accept a suffix-named field only - once a recording shows it distinct across two or more items, leave reads - without a list or identity to documents, drop the written-path requirement - and the `not-entity` fallback, record `path-varies` apart from - `query-varies`, and keep each entity's earliest sighting; - `environmentStateMerge.ts` cites records in timeline order. Remove - `not-entity` from the reason type and result schema, add `path-varies`, and - describe the new pointer forms and `field-name` basis. -3. Move the classification of retained bodies (none, base64, cut, JSON, text) - into `replayedBody` in `environmentSource.ts`, which owns recorded - exchanges; replay renders from it and tool descriptions read its JSON case. -4. Make `environmentToolDefinitions` take the `EnvironmentSource`; describe the - first `2xx` JSON record, else the first JSON record labelled with its status, - one level deep with the state's list rule and the existing sample budget; - list the manifest tool's statuses; and charge the whole description and the - tool's MCP annotations to the catalog reservation. Update the serve and - bundle callers. -5. Let the tool definitions own the MCP annotations derived from the method and - the query-`POST` rule; `serveEnvironment.ts` registers them and the card - leaves them out. -6. Cover domain, services, adapters and the compiled MCP boundary; document the - rules in the capture guide, descriptions and hints in the agent environments - guide, and the contract text. diff --git a/docs/specs/agent-environments/state-coverage/spec.md b/docs/specs/agent-environments/state-coverage/spec.md deleted file mode 100644 index b4157ed7d3..0000000000 --- a/docs/specs/agent-environments/state-coverage/spec.md +++ /dev/null @@ -1,101 +0,0 @@ -# Wider environment state coverage and tool descriptions - -Issue: https://github.com/morluto/rea/issues/4933 - -## Outcome - -The `environment-state` view backs more read tools with state, and a served -environment tells agents more about each tool. Read-only paths whose responses -are not entities become documents, listed items may be identified by an -`…Id` or `…_id` field, an item wrapped in a one-element array is located -inside it, and reads that vary by path get their own recorded reason. Each tool description says what the tool returns and which statuses -were recorded, and every MCP tool carries method hints. This increment adds no -tool, view kind, provider, network activity or write effect. - -## Requirements - -- A `GET` list tool (its template does not end in a parameter) that yields no - item or list plan holds its latest initial value as a `document` when its - initial reads have one request line, whether or not the capture writes its - path, unless its value changed between two of those reads across any - recorded write (even under another root), which leaves it `fields-differ`. A - value whose rendered JSON exceeds 256 KiB stays `rendered-oversize` and is - replayed from the recorded body, which itself fit. More request lines give - `path-varies` when they differ by path (a template with a parameter before - its end) and `query-varies` when they share one path. With every such read - now a document, `path-varies`, `query-varies`, `body-unusable` or - `rendered-oversize`, the unreachable `not-entity` reason leaves the result - schema, and `no-identity` names item tools only. A document holds the value - of its one `path`. -- When no path parameter proves an identity and no identity name identifies - the listed items, the `field-name` identity is the first key of the first - listed item, in its order, whose name ends in `Id` or `_id`, that every item - carries as a distinct string or number, and that at least one initial - recording shows distinct across two or more items. The last condition goes - beyond "every item carries it distinctly": one item satisfies that - vacuously, and a lone item's suffix-named fields are often foreign keys (a - reaction keyed by its user, a comment by its post), so a list that only ever - held one item stays a document. Empty recordings constrain no field. - Identity names keep precedence, also when choosing among an envelope's - arrays, where a suffix-named field identifies only an array of two or more - items. -- An item response that is a root array of exactly one object, or an object - with one member holding such an array, locates its entity at `/0` or - `//0` when one of the identity names in that object repeats the path - value. Objects at the root or in one member keep precedence. `at` and - `replaceAt` read and replace exactly these forms besides the root and one - member, so the gate and renderers run unchanged. -- An entity's state order is its place on the first whole line its collection's - application order lists, else its earliest sighting on the timeline (see - the state view); it cites its records in timeline order, whichever plan - observed it first. -- Each tool description reads `METHOD template; ; recorded statuses - …; replays retained records […]; evidence ev_…` after the untrusted-catalog - warning. `` describes one level deep the first cited `2xx` record - replay answers as JSON: an object's fields, an array of objects' fields, or - an envelope whose member lists objects, where a list is an array of objects - found by the state's list rule; an empty field set reads `with no fields`. - Only when no `2xx` record replays as JSON does the first cited JSON record of - another status give it, labelled `status returns …`; with no JSON - record it is omitted. The statuses are the manifest tool's `statuses`, the - one owner of that set (`no recorded status` when it is empty). Field names - and statuses are sampled within the description sample budget and charged - with the whole description to the catalog reservation before it is retained. - One owner in the environment source classifies each retained body as none, - base64, cut, JSON or text; replay answers from that classification and - descriptions read only its JSON case. -- MCP tools carry `readOnlyHint` (true for the safe methods `GET`, `HEAD`, - `OPTIONS` and `TRACE`, and for query `POST`s), - `destructiveHint: true` for `DELETE` (unset for other writes, so the MCP - default applies, and for reads, where clients ignore it), `idempotentHint` - (true for the safe methods, `PUT` and `DELETE`) and `openWorldHint: false`. The - tool definitions own the hints and charge them to the catalog reservation; - the environment card keeps its `name`, `description`, `inputSchema` tool - shape. - -## Acceptance and limits - -Synthetic captures cover read-only documents, `path-varies` and -`query-varies`, suffix-named identities with their key order, their -two-item proof, empty first recordings and their precedence (including the -choice between an envelope's arrays), a Ghost-like `{"posts":[...]}` item under -a trailing-slash path merging with its list view, a root one-element array, a -one-element filtered list that stays unidentified, and the pointer forms. The -Grafana-shaped fixture covers documents for its read-only paths (its one-member -team list among them) and object, array and enveloped-list descriptions; -synthetic sources cover the `2xx` preference over an earlier error body, the -first of several JSON records, the labelled fallback, the manifest's statuses, -empty, scalar and fieldless bodies, a truncated member name, a name whose -JSON quoting exceeds the sample, a recorded body under 256 KiB whose rendered -JSON exceeds it, non-JSON bodies and the catalog budget; the in-process and -compiled MCP servers advertise the -hints. A filtered list may still answer with one element whose identity name -repeats the requested value; list filters, pagination, lossless big integers -and cross-endpoint entity linking remain out of scope. Documents inline whole -recorded values and enlarge the state result; agent tokens, CPU time and peak -memory of the state and description build were not measured. - -## Deferred issue criteria - -Serving from the state, the AgentEnv data plane and write effects remain later -increments of #4933. This PR must reference rather than close the issue. diff --git a/docs/specs/agent-environments/state-coverage/tasks.md b/docs/specs/agent-environments/state-coverage/tasks.md deleted file mode 100644 index d2abdab579..0000000000 --- a/docs/specs/agent-environments/state-coverage/tasks.md +++ /dev/null @@ -1,16 +0,0 @@ -# Tasks - -- [x] Record the coverage and description contract and its limits. -- [x] Extend pointers, item location and identity candidates. -- [x] Require two distinct items before a suffix-named field identifies a list. -- [x] Hold read-only non-entity reads as documents, retire `not-entity` and - separate `path-varies` from `query-varies`. -- [x] Order entities by earliest sighting and cite records in timeline order. -- [x] Classify retained bodies in one owner and describe tool responses, - preferring `2xx` records, with the manifest's statuses. -- [x] Advertise MCP tool annotations, charged to the catalog, without changing - the card. -- [x] Add domain, services, adapters and compiled-boundary coverage. -- [x] Document the rules, descriptions and hints; update the contract text. -- [x] Run static, formatting, duplication, documentation and test gates and the - real-capture measurement. diff --git a/docs/specs/agent-environments/state-coverage/verification.md b/docs/specs/agent-environments/state-coverage/verification.md deleted file mode 100644 index 2ecb0b5047..0000000000 --- a/docs/specs/agent-environments/state-coverage/verification.md +++ /dev/null @@ -1,123 +0,0 @@ -# Verification - -Verified base: 7a668b73f4783b42eb0e8ce1eeff079f86d53e22 (the environment-state -view branch). - -Executed on the implementation worktree with its existing locked installation -under Node.js v22.23.1 (the repository pins 24.18.0, which was not available); -every check below ran as written in this pass, after the last source change. - -- `npm run format` then `npm run format:check`: passed. -- `npm run check:fast`: typecheck and lint passed (3959 files, no errors). The - touched files carry two lint warnings, both present on the base: `max-params` - in `environmentReplay.ts` and an unused `_` in `environmentCapacity.test.ts`. -- `npx knip`: passed (exit 0). -- `npm run jscpd`: 3.40% duplicated lines over 3348 files, under the 3.5% - gate. The three clones that touch changed test files pair the same blocks as - on the base; none involves code this change adds. -- `npm run scan:todos`: no markers. -- `npm run docs:check`: the built documentation checks and the README - consistency conformance test (5 tests) passed. -- `npx vitest run --project domain --project services`: 341 files, 5859 tests - passed, 5 pre-existing skips. -- `npm run build:cached`: passed. -- `npm run test:focused --` the environment serve adapters and capacity tests, - the environment serve MCP boundary, the environment serve and export CLI - boundaries, the environment serve shutdown process boundary, the - analysis-view MCP and CLI boundaries, the compact input-schema contract and - MCP boundary, the tool-schema validity boundary, the analysis-detail and - advertised-input-example contracts and the qlog acceptance test: 14 files, - 113 tests passed, 1 pre-existing skip. - -Real captures (outside the test suite): the built view ran through the -application service on the same 44 recorded captures (39 HAR, 5 browser -scenario) with all three template rules, in 7 to 50 ms each. 42 produced a -state, and the same two browser-scenario captures are refused with -`resource_constraint` as on the base. The base column is the brief's baseline, -which the same script reproduced on the base build in an earlier pass; this -pass did not rebuild the base. - -| Measure | Base | This change | -| ---------------------------------- | ----- | ----------- | -| Types | 568 | 576 | -| Entities | 2,213 | 2,246 | -| Documents | 2 | 299 | -| Item views | 211 | 213 | -| List views | 497 | 504 | -| Document views | 2 | 299 | -| State-backed read tools (of 1,258) | 710 | 1,016 | -| Recorded: `not-entity` | 306 | (retired) | -| Recorded: `no-identity` | 129 | 32 | -| Recorded: `path-varies` | (new) | 32 | -| Recorded: `query-varies` | 5 | 69 | -| Recorded: `body-unusable` | 32 | 32 | -| Recorded: `list-differs` | 31 | 31 | -| Recorded: `no-init-recording` | 26 | 26 | -| Recorded: `query-body` | 12 | 12 | -| Recorded: `fields-differ` | 3 | 4 | -| Recorded: `envelope-varies` | 4 | 4 | - -Seven list types gained a suffix-named identity (`permissionId`, `product_id`, -`ItemId`, `user_id`, `channel_id`, `spl_id` and `eventId`). Seven more had one -before the two-item proof and lost it, because every initial response listed a -single item: an Airbyte organization, a Mattermost reaction and team -membership, and a Redpanda broker and schema reference became documents; a -NOAA station read is `query-varies` and a Redpanda consumer read -`path-varies`. Two Ghost item tools render from `/members/0` and `/tags/0`. A -third Ghost item tool is located at `/posts/0` but stays `fields-differ`: its -recordings differ by an `include` query. - -State result size, as the JSON length of each Evidence summed over the 42 -states: 2,677 KiB on the base and 3,196 KiB now (+19%), measured by the same -script. The largest growth per capture is Metabase (133 to 236 KiB), Directus -(21 to 93), Redpanda Console (26 to 68) and Vault (9 to 43). Documents take -492,516 of the 3,274,243 UTF-8 bytes of the results now; the base held two. -Agent tokens, CPU time and peak memory of the state view were not measured. - -Tool descriptions on the 44 captures' manifests: all 44 catalogs were admitted -within their reservation. 1,336 of 1,400 tools state what they return: 1,333 -from a `2xx` record and three labelled with another status (Miniflux and -NocoDB 404, Shlink 501), because none of their records succeeded as JSON. The -summaries add 261,502 bytes to a 1,185,893-byte catalog of names, descriptions -and input schemas (median 136, 95th percentile 554, maximum 1,133 bytes per -tool); five reached the field sample bound (one Keycloak, one Lychee and three -Sentry tools with 46 to 105 fields). The MCP annotations add 113,182 bytes to -`tools/list` and none to the card. Building a catalog took a median 1.6 ms and -at most 7.6 ms (Metabase), after the source was loaded. Agent tokens, CPU time -and peak memory of the description build were not measured. - -After merging the environment state view's review fixes (its branch at -6ad63bcc, which also brings main's evidence-file sources), every gate ran -again on the merged tree: `npm run check:fast`, `npm run format:check`, -`npx knip`, `npm run scan:todos` and `npm run docs:check` passed; `npm run -jscpd`: 3.39% duplicated lines over 3362 files; `npx vitest run --project -domain --project services`: 344 files, 5914 tests passed, 5 pre-existing -skips; `npm run build:cached`, then `npm run test:focused --` the serve and -tool-definition adapters, the serve MCP and CLI boundaries, the export CLI -boundary, the analysis-view MCP and CLI boundaries, the compact input-schema -budget and the analysis-detail and advertised-input-example contracts: 10 -files, 98 tests passed. - -The real-capture comparison was repeated on the merged code, with the base -measured on the merged state view without this change: all 44 captures now -produce a state, and 1,011 of 1,277 read tools are state-backed against 625 -on the base (216 item, 416 list and 379 document views against 214, 409 and -2). Recorded reasons: `no-identity` 216 to 32 and `not-entity` 310 to none; -`query-varies` 5 to 76 and `path-varies` 36 are document reads under more -than one query or path; `list-differs` 35, `body-unusable` 33, -`no-init-recording` 28, `query-body` 12, `envelope-varies` 4 are unchanged, -and `fields-differ` is 9 to 10. - -Not covered here: serving from the state, the AgentEnv data plane and write -effects, which are later increments. - -## After the squash onto main - -The branch was squashed onto main once the state-serve branch merged (166fb082). Against a merge of the previous head -into that main, the squash keeps both sides of every conflict and drops nothing of this branch. Two tests then failed -on it and were refitted with the oversized-document fix in 2a926a0a: the bundle test of a state catalog over the -discovery budget uses 300 read tools, inside the window where the state's catalog is refused and replay's, with its -response summaries, still fits (280–320 by a probe), and the rea-state validation test names the pushed document by -the count of documents the state holds. The replay-only card test pinned main's 11,131-byte card; it now pins this -branch's 12,818-byte card, whose descriptions name each tool's recorded responses. The branch then merged main at -d7ca93cc without conflicts. diff --git a/docs/specs/agent-environments/state-serve/plan.md b/docs/specs/agent-environments/state-serve/plan.md deleted file mode 100644 index a0e77e13a9..0000000000 --- a/docs/specs/agent-environments/state-serve/plan.md +++ /dev/null @@ -1,45 +0,0 @@ -# Implementation plan - -1. Export the Evidence file authenticator from `environmentSource.ts` with a - `state` role, and validate a HAR capture there with the owned borrowing - parse so later views reuse it. Add `environmentState.ts` to check state - Evidence against a loaded source, build the served catalog (the tools a - state serves and the data plane its card declares), derive the state from - the capture through the analysis view service with the capture as retained - Evidence, and prepare it: unavailable when its catalog exceeds the - discovery budget under the served name or it cannot be derived. -2. Add `environmentStateDocument.ts` to validate `rea-state/v1` documents - against the served types and views, and `environmentStateStore.ts` for the - live store with reset, atomic replace and the `data/get` snapshot. -3. Export `selectsRecordedLine` and the body-taking `replayAnswer` from - `environmentReplay.ts`, reuse `pathSegmentMatches` from the state rules, - export one recorded-body - predicate `stateBodyJson` from the state accumulator and `changesState` from - the state rules, and widen `collectionPathOf` to any value with a path, so - state answers reuse selection, matching, body and write rules. -4. Add `environmentStateAnswer.ts` for item, list and document answers, the - recorded fallback and the answer function serve and export share. -5. Declare the state data plane on the card in `environmentTools.ts`, taking - the data plane in an options object so the discovery budget reserves the - card and descriptions actually served. -6. Add `stateIntake.ts` for parts, files on this host and downloads - (injectable fetcher and timeout, cancellation, coarse failure categories) - and `environmentDataPlane.ts` for the three methods, run one at a time in - arrival order and cancelled by the server's stop or the caller's - departure; let `serveEnvironment.ts` serve the shared catalog and answer - function, queue every message of a batch at arrival, bound the replies of - one response and stop the data plane before closing the listener. -7. Make `environment-serve` prepare the state under its served name after - loading the source, add `--replay-only`, log an unavailable state as a - warning before binding, and report `state` in the stopped document. -8. Let `environment-export` prepare the state the same way under the bundle - name, only after the name checks, and plan the served - tool count, the verifier check from the shared answer function, the `serve` - verifier and the README's serving section from it; report `state` in the - export output and expect the served count in the hosted-lane script. -9. Cover services, adapters, cli-boundary, mcp-boundary and process-boundary - behaviour; document default serving, `--replay-only`, the fallback, the - answers, the data plane, the card and the export. - -No dependency, provider or REA tool contract changes. The only new network -activity is an `https://` download that a `data/add` call names. diff --git a/docs/specs/agent-environments/state-serve/spec.md b/docs/specs/agent-environments/state-serve/spec.md deleted file mode 100644 index 3ebf83c42b..0000000000 --- a/docs/specs/agent-environments/state-serve/spec.md +++ /dev/null @@ -1,198 +0,0 @@ -# Serve the environment from its state by default - -Issue: https://github.com/morluto/rea/issues/4933 - -## Outcome - -`rea environment-serve --evidence ` serves the environment -from the initial state the capture observed, with nothing else to supply: at -startup it derives the `environment-state` view of the capture in-process with -the manifest's `template_rules`. Read tools whose views are state-backed answer -from one live state, the `/agentenv` data plane implements `data/reset`, -`data/add` and `data/get` against it, and the card advertises those operations -and an intake declaration. `--replay-only` serves exactly the stateless replay -main serves: every manifest tool replays its recordings, `/agentenv` answers every method as not found and the card is -byte-identical. A state that cannot be derived, or whose catalog exceeds the -discovery budget, starts the server in replay mode, logs why and reports it. Exported bundles serve the state by default, -and their verifier and README match what they serve. Serving is read-only in -this increment: write tools are not served from the state. - -## Requirements - -- Derive the state in the application layer, shared by serve and export: - `deriveEnvironmentState(source, capture, operation)` authenticates the - capture value the command already read (an owned snapshot authenticated by - the source load is reused, not parsed again), projects the - `environment-state` view with the manifest's `template_rules` through - `inspectAnalysisViewValidated` with the capture as retained Evidence (the - Evidence id equals that of a projection by hand, and the capture's strings - are not charged again as inline input, which refuses captures of a few MiB), - then applies `loadEnvironmentState`: `inspect_analysis_view` Evidence of kind - `environment-state`, its `parent_evidence_id` equal to the capture's, its - `template_rules` equal to the manifest's in the same order, and every view - naming a manifest tool, refusing otherwise with `invalid_request` whose issue - path starts with `state`. The source validates a HAR capture with the owned - borrowing parse, so the view reuses that validation. -- `prepareServedState(source, capture, {name, operation})` first builds the - state catalog under the served name, then derives the state, and reports - `{served: true, evidence_id}` or - `{served: false, reason: "unavailable", code, message}` with the refusal's - projected code and message: a state catalog over the discovery budget is - unavailable with `resource_constraint`, and no state is derived for it. A - derived state whose catalog fits always serves from the state. The CLI - reports `{served: false, reason: "replay-only"}` itself for `--replay-only` - and derives nothing. -- Keep one state store per server process, shared by every MCP session and the - data plane: entities keyed by type, collection and id with per-collection - order taken from the entities array, documents keyed by tool. `reset` - restores the Evidence state, `replace` installs a validated document whole, - and mutations are synchronous. -- Answer item views by rendering the entity the path arguments name into the - recorded envelope of `envelope_ordinal`. Match arguments as replay does: a - held collection segment equal to the argument as written or after - percent-decoding, preferring verbatim spellings, and the identity as the last - argument percent-decoded, then as written, never re-split on `/`. Any held - entity answers, and query arguments only set `replay.exact_match`. Refuse an - entity the state does not hold, or one lacking a required field, as a tool - error and never invent a body. -- Answer list views from the state only when the arguments name one of the - view's `checked_record_ordinals` exactly (every path and query value equal and - no recorded query parameter unsupplied), choosing among them as replay - chooses: every collection entity in state order for `membership: "all"`, - otherwise the recorded members the state still holds. A member lacking one - of the view's `required_fields` makes the call a tool error stating that the - state holds no complete member, never a partial body, as for items. Lines - recorded after a write or with other filters were never checked and answer - from recordings. -- Answer document views with the state's value when the arguments name the - document's checked line exactly. -- Answer recorded views, tools without a view and unrecorded requests from the - recording, labelled `state: {source: "recording", reason}`; label state - answers `state: {source: "state", view, …}` with the base record's replay - provenance and `truncated: false`; refuse a state answer over 256 KiB as a - tool error rather than cut it. -- Serve `data/reset` (`{}`), `data/add` with exactly one `data` or `file` part - (`bytes`, a `file://` regular file or an `https://` download with a 30 s - timeout covering the body, no redirects and a streamed 32 MiB cap; - `mimeType` when given is `application/json`) and `data/get` (`{parts: - [{kind: "data", data: rea_state}]}`). A `file://` uri whose host is neither - empty nor `localhost`, or whose path is a UNC path, is `-32602` before - anything is opened. A document that `data/get` would write back past 32 MiB, - once it adds the members a document may omit, is `-32602`, so a reported - state always loads again. Anything else is `-32602`, including empty `parts`; a - failed download is `-32000`; errors never echo a uri or content and name a - coarse failure category in `error.data.reason`. Calls run one at a time in - arrival order across requests; every message of a batch is queued when the - batch arrives, so no other request's call lands between them, and - notifications run without a reply. -- Stopping the server (`close` or `prepareShutdown`) aborts the data plane's - stop signal, and a request's own signal aborts when its client leaves: the - download in progress ends with reason `cancelled`, queued calls are answered - `-32000` with reason `cancelled` without running, and a `data/add` whose - file read finished after the cancellation does not replace the state. -- A `file://` read whose descriptor close fails answers `-32000` and keeps the - descriptor in a server-lifetime owner. The next file read retries the close - first and, while it still fails, answers `-32000` without opening the file. - `close` retries it again and rejects while it is still open. -- Bound one `/agentenv` response to 64 MiB of replies (twice the intake - limit). Each reply is measured in bounded JSON parts as it is produced, in - message order, and assembled only when it fits, so a reply past the budget is - counted but never serialized whole. Room is kept for every later reply's - budget error and for a batch's brackets and commas, so the body never - passes the budget; a reply that does not fit is replaced by `-32000` with - `data: {max_response_bytes, reply_bytes}`, unless that error is no smaller - than the reply, so the body is never built past the budget and small write - replies are kept. -- Validate `rea-state/v1` documents against the served types and views: known - types, collections that instantiate their template, ids equal to the identity - field, unique keys, `view_fields` naming item or list views of the type - without setting the type's identity field to a value whose scalar text - differs from the entity's id (refused at that view's `fields`), - documents naming document views once at the initial path, and the optional - `state_evidence_id` and `types` that `data/get` reports equal to the served - ones. Refuse numbers without an exact native value. Preserve all own JSON - members in caller data, including `__proto__`, and reject unknown structural - members before projecting the document's declared fields. - Name the first problem by JSON pointer, never deeper than a caller-data - member (`fields`, `value`, `types`), and leave the state unchanged. -- Keep record citations Evidence provenance: refuse `record_ordinals` or a - `record_ordinal` other than the Evidence's for that entity or document, and - hold the Evidence's citations only for loaded values equal to the Evidence's; - edited or added values cite none. -- In state mode, declare `operations: ["data/reset", "data/add", "data/get"]` - and the `urn:agentenv:intake/v1` extension, describe tools as answering from - the state where it backs them, and leave out `POST`, `PUT`, `PATCH` and - `DELETE` tools other than query `POST`s. The discovery budget reserves the - card and descriptions actually served (`servedCatalog` returns the tools and - the data plane the card declares). A state catalog can exceed the budget a - replay catalog fits, so such a state is unavailable and the environment and - its export serve replay: everything main served and exported is still - served and exported. -- The CLI has no `--state`; `--replay-only` (default false) serves replay - without deriving. Otherwise it prepares the state under the name it serves - (`ENVIRONMENT_NAME` or the manifest's). When the state is unavailable the - command logs a warning with the code and message through its listener logger - before binding, and serves replay. The stopped document's `state` member is - the report. `serveEnvironment` keeps taking an optional prepared state and - serves replay without one; the served catalog (`servedCatalog`) and the - answer function (`environmentToolAnswer`) are shared with export. -- `environment-export` keeps the bundle command - `rea environment-serve /env/manifest.json --evidence /env/evidence.json` and, - after its name checks, prepares the state under the bundle name as that - server will, to predict what it serves, so a refused `--name` derives - nothing; its report is served or unavailable, never replay-only. The - verifier's `TOOL_COUNT` and the command's `tool_count` are the served tool - count, and its check tool and expected status come from calling the server's - answer function with `{}` on the first served `GET` tool without path - parameters whose answer is not an error. The verifier and smoke task use the - id `serve`. The README's "What the environment serves" section describes - serving from the state, the replay fallback and `--replay-only`, says which - applies to the bundle (with the code and message when the state is - unavailable), and keeps the not-emulation and untrusted-content caveats. The - export output adds `state`. The hosted-lane verifier script expects the - served count. - -## Acceptance and limits - -Services tests cover derivation (the by-hand Evidence id and state, a capture -the manifest was not projected from, a capture inline admission refuses), -the prepared reports (served, unavailable for a `capture_browser_scenario` -capture with header values but no response bodies, unavailable with -`resource_constraint` for a 350-tool read-only manifest whose replay catalog -fits), bundle plans served from the state and in replay (tool count, check tool -and status, a check whose state answer differs from replay's in record and -status, a check that skips a tool the server cannot answer, the replay fallback -of that 350-tool manifest, name refusals before any preparation, a manifest -neither mode admits, verifier, smoke task and README wording), the loader -refusals, store reset, order, round trip and -atomic replace, the first-problem pointers, citation provenance after a load and -every answer path: item (including percent-encoded collection segments and -ids), list `all`, list `recorded`, lines recorded after a write or with other -filters, a line replay's tie-break would not pick, document, recorded view, tool -without a view, unrecorded request, missing entity, missing required field and -the body limit, a view value that changes an entity's identity, and a list -member missing a required field. Adapters tests cover the data-plane shapes, -`-32602` for empty and malformed parts and invalid documents, inexact numbers, -bytes, `file://` and its failure categories, `file://` uris naming another -host or a UNC path, injected https downloads (status, declared and streamed -size, the timeout whether or not the fetcher honours its signal), the default -fetch's refused redirects, arrival-order application across requests, a batch -another request's reset cannot split, cancellation by the server's stop and by -a departed caller, a server that closes while a download is stalled, a -retained state-file close that the next file read and `close` retry, the -response budget, batches and notifications, the card declaration, absent write -tools, a served query `POST`, the per-mode discovery reservation and a -`data/add` that changes the next tool answer over MCP. The mcp-boundary tests serve the state the -built CLI derives from only a manifest and a capture, and `--replay-only` with -every manifest tool, `-32601` data-plane answers and a card whose SHA-256 -equals that of the card main serves for the fixture; the process-boundary test checks the stopped document's -`state` for a derived state, `--replay-only` and an unavailable state, and the -warning logged before binding; the cli-boundary export test checks the served -tool count, the verifier and the README of an exported bundle. No test reaches -an external network. Write effects, list filters beyond recorded lines and -`tables` in the intake declaration are out of scope. - -## Deferred issue criteria - -Write effects are a later increment of #4933. This PR must reference rather -than close the issue. diff --git a/docs/specs/agent-environments/state-serve/tasks.md b/docs/specs/agent-environments/state-serve/tasks.md deleted file mode 100644 index 52a01b0774..0000000000 --- a/docs/specs/agent-environments/state-serve/tasks.md +++ /dev/null @@ -1,32 +0,0 @@ -# Tasks - -- [x] Record the serving contract, requirements and deferred increments. -- [x] Load and cross-check state Evidence for a served source. -- [x] Add the store, the document validator and the snapshot. -- [x] Answer item, list and document views from the state with recorded - fallbacks. -- [x] Serve the data plane and declare it on the card; leave write tools out. -- [x] Address review: answer lists and documents only from checked lines, - match item arguments as replay does, reserve the served card only, keep - record citations Evidence provenance, and run data-plane calls in arrival - order with a tested download timeout. -- [x] Derive the state from the capture at startup, as retained Evidence, with - the loader's checks; reuse the capture's validation. -- [x] Replace `--state` with `--replay-only`, fall back to replay with a logged - warning when no state can be derived, and report `state` when stopped. -- [x] Derive the state in `environment-export` to plan the served tool count, - the verifier check and the README; report `state` in its output. -- [x] Add services, adapters and boundary coverage; remove the `--state` flag - tests. -- [x] Document default serving, `--replay-only`, the fallback, answers, data - plane, document format, card and export. -- [x] Address review: serve and export replay when the state's catalog - exceeds the discovery budget, check the bundle name before preparing the - state, keep replay-only out of export plans, test a check the state - answers differently from replay, and pin main's replay card digest. -- [x] Address review: bound one `/agentenv` response's replies, queue a - batch's messages together at arrival, cancel the running download and - queued calls when the server stops or the caller leaves, refuse - `file://` uris naming another host or a UNC path, refuse view values - that change an entity's identity, and apply list views' required fields. -- [x] Run static, formatting, duplication, documentation and test gates. diff --git a/docs/specs/agent-environments/state-serve/verification.md b/docs/specs/agent-environments/state-serve/verification.md deleted file mode 100644 index 7fff3cf9b1..0000000000 --- a/docs/specs/agent-environments/state-serve/verification.md +++ /dev/null @@ -1,79 +0,0 @@ -# Verification - -Verified base: 6676582675e08574146a812ae58cff67e2e53282 (this branch's head), -with the review fixes of this pass uncommitted. - -Executed on the implementation worktree on macOS with Node v22.23.1 (the -repository pins 24.18.0 in `.nvmrc`, which was not installed). Every check -below ran as written after the last source change, in this order. - -- `npm run format` then `npm run format:check`: passed (4330 files). -- `npm run check:fast`: typecheck and lint passed. The lint report holds 0 - errors and no diagnostic in any file this pass touches. -- `npx knip`: passed (exit 0, no findings). -- `npm run jscpd`: 3.37% duplicated lines over 3373 files (2800 clones), under - the 3.5% gate; no clone involves a file this pass changed. -- `npm run scan:todos`: passed, no markers. -- `npm run docs:check`: the built documentation checks (6 tasks) and the README - consistency conformance test (5 tests) passed. -- `npx vitest run --project domain --project services`: 347 files, 5948 tests - passed, 5 pre-existing skips. -- `npm run build:cached` (the built output already included this pass's - sources), then `npm run test:focused --` the serve CLI, MCP and process - boundaries, the export CLI boundary, the CLI startup imports, the agentenv - verifier identity boundary, the bundle package pin conformance test, the CI - change scope boundary, the analysis-view CLI and MCP boundaries, and the - `serveEnvironment`, `serveEnvironmentState`, `environmentCapacity` and - `stateIntake` adapters tests: 14 files, 335 tests passed. -- After this file was written: `npm run format`, `npm run format:check`, - `npm run scan:todos` and `npm run docs:check` passed again. - -The review fixes are covered by these tests, all passing in the runs above: - -- Response budget: a batch of four `data/get`s over a loaded state of about a - third of the budget keeps two results, answers the other two with `-32000` - and `max_response_bytes`, keeps the trailing reset's `{}`, and its body stays - within the budget. -- Batch order: a batch `[data/add (gated download), data/get]` with a - `data/reset` from another request sent while the download is held reports - the loaded state from its `data/get`, and the reset applies last. -- Cancellation: aborting the data plane's stop signal ends a stalled download - (its fetcher's signal is aborted) and answers the queued reset as - `cancelled` without running it; a call made after the stop does not run; a - caller whose request signal aborts gets `cancelled` and the state is - unchanged. Over loopback HTTP, `close()` of a served state returned while a - download that never answers was in progress, and that download's signal was - aborted. -- File closes: with an injected close failure, `data/add` of a `file://` uri - answered `-32000` without echoing the uri. The descriptor stayed open, and - the next file load closed it before loading. While the close kept failing, - over loopback HTTP the next file load answered `-32000` ("still open") and - an inline `data` part still loaded. `close()` rejected with the unfinished - close, then resolved and closed the descriptor once the close succeeded. - Both tests fail on the previous head, which dropped the descriptor. -- File hosts: `file://remote.example.test/...` and - `file:////remote.example.test/...` are refused with the network-share - message and no failure category; a `file://localhost/...` uri loads. -- Loaded identity: `view_fields` setting `id` to `3`, `"3"` or `null` on user 2 - is refused at `/rea_state/entities/7/view_fields/0/fields`; `"2"` loads. -- List required fields: a folder without `title` makes `get_folders` a tool - error naming the incomplete entity. - -That each test fails without its fix is source-derived; the fixes were not -reverted to show it. - -Not covered here: a Windows host (the UNC refusal ran on macOS, where -`file:////host/share` converts to `//host/share`; the host check runs before -any path conversion on every platform), a real `https://` download (tests -inject the fetcher), the memory and time of a budgeted batch (not measured), -agent token usage, a real AgentEnv framework run, a real-world capture, and -write effects, which are a later increment. - -After refusing bodies too deep for the state's own nesting (a recorded body -must nest at most the JSON depth limit minus 16 levels to enter the state): -`npm run check:fast`, `npm run format:check`, `npx knip`, `npm run scan:todos` -passed; `npm run jscpd`: 3.37% over 3373 files; `npx vitest run --project -domain --project services`: 347 files, 5950 tests passed, 5 pre-existing -skips; `npm run build:cached`, then `npm run test:focused --` the serve CLI, -MCP and process boundaries, the export CLI boundary and the two serve adapter -tests: 6 files, 48 tests passed. diff --git a/docs/specs/agent-environments/state-targets/plan.md b/docs/specs/agent-environments/state-targets/plan.md deleted file mode 100644 index 30f9509982..0000000000 --- a/docs/specs/agent-environments/state-targets/plan.md +++ /dev/null @@ -1,14 +0,0 @@ -# Implementation plan - -1. **Read-only POSTs.** A module decides once per extraction which POST tools only read, used by the write filter, - init cutoffs and the write simulation. -2. **Adoption.** The write simulation tracks held entities and writes no built plan models, and takes an unseen - entity at its first successful item read. -3. **Linked creates.** A module links a POST's returned id to the state type it is first read under; the extraction - cuts that type's initial window at the POST, and the create plan records the read's collection. -4. **Rewrite cuts.** The merge reports the spans behind a type's rewrite; the extraction cuts the type's initial window - at the earliest write within them and plans once more. -5. **Variant lines.** A module classifies request lines by the members their objects show; plans drop variants, views - name them with their query keys, and serving and the write gate replay calls that match. -6. **Tests and docs.** Each step's tests fail on the step before; the state-view, state-writes, list-queries and - write-coverage specs and the environment docs describe the new behaviour. diff --git a/docs/specs/agent-environments/state-targets/spec.md b/docs/specs/agent-environments/state-targets/spec.md deleted file mode 100644 index f673633778..0000000000 --- a/docs/specs/agent-environments/state-targets/spec.md +++ /dev/null @@ -1,66 +0,0 @@ -# Give more write tools a state target - -Issue: https://github.com/morluto/rea/issues/4933 - -## Outcome - -Across the 50 published capture-built environments, 91 of 195 write tools got no state target: the gate refused them -before looking at their evidence, because their path named no state type, item or document. A diagnosis traced each to -its cause in the recordings and the code. The five largest shared causes: - -- **Read-only POSTs counted as writes.** A lookup, an RPC tunnel naming read operations, or a session refresh was - planned as an unserved write and cut initial windows. -- **Entities a write the gate does not model made.** A later read of such an entity failed its check instead of - holding it, so writes to it stayed unobserved. -- **Creates read under another path.** A create whose path is no state type (`POST /Playlists` read as `/Items/{Id}`) - had no target, and its entity leaked into the initial state of the type it is read under. -- **Types whose reads disagree across an unrelated write.** Every view of the type stayed replayed. -- **Request lines that show entities in another form.** An extra query parameter that adds or drops members - (`?counts=true`, `?expand=`, `?fields=`) failed the whole view. - -## Behaviour - -- **Read-only calls.** A POST is not a state write when its response repeats the read of its path that finished last - before it began, with no write between, it tunnels only read operations, its last literal segment names a lookup and - no write, or it renews a session; it is replayed. It stays a write when one of its calls was redirected or unanswered, - or when a related read line changes across one of its calls, or finds its entity there on one side only, with no write - but other read-only calls between; a read overlapping the call counts on neither side. Each response body compared is - parsed once and kept only as its canonical digest, charged to the view's budget until the decision ends. -- **Adopted entities.** A successful item read of an entity the gate's copy never held, after a write no built plan - models or one redirected or unanswered, puts the entity into the copy within the view's budget; an entity a modelled - write touched is never taken back. -- **Linked creates.** A POST whose path names no state type becomes a create into the type whose item read first names - an id its response returned, before any other tool's write, when the id is new: no read finished before it began - showed it, whether an item read of the id under that type or collection whose body shows the item, a list of the type - or a read of that collection. Its observation is a read of an id its response returned, in an envelope too. Serving - creates in that read's collection, for the exemplar's path arguments only (segment by segment, in either spelling), - and fills path fields with its exemplar's path values decoded once. A successful POST that returned an id a type's - reads only show once it began ends that type's initial window: a read still running then may show it, and a list read - shows its listed entities' own ids (identity-named, or a suffix-named field such as `projectId` distinct across two or - more when no id-named field identifies them), not those they nest. A read at or after the write that ends the initial - reads is not parsed for that cut, since it cannot show a new id. -- **Rewrite cuts.** When a type's reads disagree across a write under another root, the type's initial window ends at - the earliest write within the change and the state is extracted again. The earlier of this and the creation cut wins. -- **Variant lines.** A read line that shows the same entities in another form is a variant: it leaves the view's checks, - the entity observations (an entity's first sighting comes from the lines left) and the membership changes that cut a - type's initial window, and the view names it with the query keys that pick it out (`projected_query_keys`, on item and - list views). Beside a line showing whole entities, a list line asking for some fields only (a projection value other - than `*`) is set aside before the identity proof the same way. A call matching those keys replays its recording, so it - does not show served writes; a 400, 404 or 410 on such a line is still evidence. A call asking for some fields only - replays unless every value it gives is `*` or one a checked line gave, and no replayed read gave it. The write gate - skips exactly the successful reads serving replays, by the same decision. A filter role whose name matches no field - needs two agreeing values. A tool whose lines would take more than 2^24 line pairs and entity lookups to compare - pairwise keeps every line checked; otherwise lines are compared only with those showing one of the same entities, - through an index charged to the budget while it is held. The base lines' queries are parsed once for every variant - they key. An item line first recorded after the initial window is a variant too, judged against the lines left once - variants are dropped: when it names a new shaping parameter and its object carries or lacks members theirs do not, or - selects some fields and leaves out members they always show, and an item only a replayed line showed, which the state - never started with and in whose type no served create has added an entity since, answers with its own recording. - -## Acceptance - -- Over the 50 published captures, write tools with no state target fall from 91 to 61 and served write tools rise from - 46 to 61, with none lost; every served write tool applies. -- Read calls recorded before the first write that state serving answers keep matching their recordings; each newly - state-backed view answers them as recorded, except where replay itself does not. -- The Grafana and Mailpit environments no longer hold, in their initial state, entities their captures created. diff --git a/docs/specs/agent-environments/state-targets/tasks.md b/docs/specs/agent-environments/state-targets/tasks.md deleted file mode 100644 index 890980ae40..0000000000 --- a/docs/specs/agent-environments/state-targets/tasks.md +++ /dev/null @@ -1,10 +0,0 @@ -# Tasks - -- [x] Keep read-only POSTs out of the write list. -- [x] Take an entity a write no plan models made when a read first shows it. -- [x] Plan a create into the type its returned id is read under, and cut that type's initial window. -- [x] End a type's initial reads at the write its reads disagree across. -- [x] Replay request lines that show entities in another form. -- [x] Add tests that fail on the step before each change. -- [x] Measure the 50 published captures, the served smoke and the serving of recorded reads after each step. -- [x] Run static, formatting, duplication, documentation and test gates. diff --git a/docs/specs/agent-environments/state-targets/verification.md b/docs/specs/agent-environments/state-targets/verification.md deleted file mode 100644 index b218220552..0000000000 --- a/docs/specs/agent-environments/state-targets/verification.md +++ /dev/null @@ -1,98 +0,0 @@ -# Verification - -Executed on macOS with Node v22.23.1, one change at a time on main, over the 50 published capture-built environments -(each app's latest capture). The served smoke rebuilds each manifest with the tree under test and applies every served -write tool; the serving check answers every recorded read made before the capture's first write through state serving -and compares it with the recording. The serving check reads no records from the five browser-scenario captures (Art -Institute collection, LoC photos, Lychee, PhotoPrism, Pinry), so its read counts cover 45 apps; their 41 views count -among the state-backed views. - -## Gates - -- `npm run build:cached`, `npm run check:fast` (typecheck and lint, no new warnings in the changed files), - `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.49% duplicated lines over 4074 files. -- `npx vitest run --project domain --project services`: 8992 passed, 6 pre-existing skips, on main `ed069bb9`. -- `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, 88 passed. - -## Measurements - -| Step | Write tools | Served | No state target | State-backed read views | Recorded reads matching | -| --------------- | ----------- | ------ | --------------- | ----------------------- | ----------------------- | -| main | 195 | 46 | 91 | 1,098 | 1,833 of 1,886 | -| read-only POSTs | 189 | 46 | 84 | 1,104 | 1,911 of 1,964 | -| adoption | 189 | 47 | 84 | 1,104 | 1,911 of 1,964 | -| linked creates | 189 | 48 | 80 | 1,105 | 1,911 of 1,964 | -| rewrite cuts | 189 | 51 | 77 | 1,110 | 1,922 of 1,975 | -| variant lines | 189 | 61 | 61 | 1,150 | 2,068 of 2,126 | -| review fixes | 189 | 61 | 61 | 1,151 | 2,075 of 2,133 | -| third round | 189 | 61 | 62 | 1,151 | 2,075 of 2,133 | - -The served smoke applies every served write tool at each step. No read view loses its state backing, and no served -write tool is lost. - -- **Read-only POSTs:** six tools leave the write list (Mattermost `members/ids`, Miniflux `discover`, NocoDB's two - internal tunnels, Paperless `selection_data`, PocketBase `auth-refresh`); Paperless's notes create gains a target. - Grafana's `query-history` stays a write. Nomad `jobs/statuses` repeats its GET, but its integers exceed JSON's - exact range, so it stays a write. -- **Adoption:** Grocy's product delete is served; Mealie's recipe delete moves from no observation to unconfirmed. -- **Linked creates:** Jellyfin's item delete is served; its playlist create and item update, and Mailpit's send, gain - targets. Grafana's `/api/search` and Mailpit's messages no longer hold the dashboard and message their captures - created. -- **Rewrite cuts:** Tandoor's recipe create, update and delete are served. -- **Variant lines:** Baserow's row create, update and delete, Keycloak's user delete, Miniflux's category create and - update, PocketBase's create, update and delete, and Vikunja's task delete are served. Ghost's post create and update, - Keycloak's user update, Miniflux's category delete, n8n's tag create and Vikunja's task update gain targets. -- **Review fixes:** no write verdict changes. A NocoDB records list whose `fields` line had rejected it becomes - state-backed, and all 7 of its recorded reads match. Without its guard, a short id would cut 23 Tandoor views' - initial windows at a `POST /api/view-log/` returning `{"id":1}`. - The second round (the gate skipping exactly the reads serving replays, earlier reads vetoing a linked create, whole - RPC batches, and releasing a discarded planning pass) changes no measurement. -- **Third round:** Mailpit's send, a linked create that was never observed, loses its target: other writes (marking - messages read, tagging) ran between it and the item read naming its id. No served write, read view or matching read - changes. -- **Fourth round:** no verdict, read view or recorded read changes. A purge of temporary files removed 32 of the local - captures, so this round was measured on captures restored from the published datasets, byte-identical where a local - copy survived; Baserow's, Grocy's and Keycloak's published captures predate the ones measured above. On that set the - previous head and this one both give 187 write tools, 62 served (smoke 62 of 62), 1,151 views and 2,085 of 2,155 - recorded reads matching. -- **Fifth round** (on main `6a34be41`): no verdict, read view or recorded read changes on the same restored captures, - once the serving check passes a repeated query value as an array, as main now expects. -- **Sixth round:** no verdict, read view or recorded read changes on the restored captures. -- **Seventh round** (on main `96ea32b7`): WordPress's post create moves from side-effect to unconfirmed, still unserved: - its only later read, `/wp-json/wp/v2/posts/22?context=edit`, shows the edit representation (`generated_slug`), so it - is now replayed rather than checked. No served write, read view or recorded read changes. -- **Eighth round** (on main `3e7e102a`): no verdict, read view or recorded read changes on the restored captures. -- **Ninth round** (on main `b7ebccf8`): no verdict, read view, recorded read or session replay changes on the restored - captures (187 write tools, 62 served, 1,151 views, 2,085 of 2,155 initial reads and 2,764 of 3,022 session reads - matching). -- **Tenth round** (on main `a2235b09`): no verdict, read view, recorded read or session replay changes on the restored - captures. -- **Eleventh round** (on main `2968d1e9`, performance review): variant lines compare only lines that share an entity, - read-only decisions parse each body once and keep its digest, and the creation cut skips reads that cannot count. - Every census, serving-check and session-replay row equals the previous head's. On a synthetic capture of a list and - 1,000 items read plainly and with `?expand=`, the variant pass falls from 401 ms to 2 ms and the state build from 659 - ms to 216 ms (Node v22.23.1). -- **Twelfth round** (on main `d87e73f2`, second performance review): the write gate lists a type's collections only when - the path's own collection holds no id, and the variant pass parses base lines once. Every census, serving-check and - session-replay row equals the previous head's. The synthetic 1,000-item capture takes 259–264 ms against main's - 244–247 ms (378–397 ms before this round; Node v22.23.1, medians of seven warm runs). Over the 50 captures, the - environment-state and environment-manifest views together take 2.96 s wall and 3.82 s CPU with a 540 MiB peak RSS, - against main's 2.61 s, 3.41 s and 516 MiB (one Node v24.22.1 process per sweep, warm medians of three runs; the cold - first run is within 2% of them); the environment-state view alone takes 2,093 ms against 1,791 ms, and its results - grow from 3.69 MB to 3.84 MB. Agent tokens were not measured. - -Of the 40 views variant lines make state-backed, 146 of 151 recorded reads before the first write match; the other five -(Sentry projects) are replayed, and replay returns the first of several differing recordings, as before. A paged -Paperless document list answers all five documents, a PocketBase item without `expand` answers without it, and a -NetBox `site_id` filter learned from one line is not adopted. - -## Not included - -- Making a value that differs between two request lines volatile: it contradicts the spec's distinct query strings and - made 11 recorded reads answer otherwise than replay. -- Item actions (`/{type}/{id}/archive`), bulk writes at a collection path, templating literal ids by value, and - envelope masking: each needs further recording evidence or a separate change. diff --git a/docs/specs/agent-environments/state-view/plan.md b/docs/specs/agent-environments/state-view/plan.md deleted file mode 100644 index 518e6b35ec..0000000000 --- a/docs/specs/agent-environments/state-view/plan.md +++ /dev/null @@ -1,28 +0,0 @@ -# Implementation plan - -1. Move response-body decoding from the environment source into - `recordedResponseBody.ts` with the caller's byte limit, and exact JSON - parsing into `exactJsonNumber.ts`, so replay and state extraction share one - owner each. -2. Add `environmentStateRules.ts` as pure helpers: write classification, API - bases and roots, entity location, identity names, JSON pointers of depth one, - value bytes and the entity and list renderers. -3. Add `EnvironmentStateExtraction.ts` for planning item and list tools, - observing entities and assembling the result, `environmentStateMerge.ts` for - merging observations, and `environmentStateGate.ts` for reproducing each - plan's recordings; every body is parsed through a budget callback and - released before the next. -4. Add `EnvironmentStateAccumulator.ts`, extending the manifest accumulator so - grouping is shared, retaining record lines and references to the admitted - records, and charging bodies and kept values. -5. Add `environmentStateView.ts` with the request schema (sharing the - manifest's `template_rules` schema), the result fields and the projector; - share capture admission and record grouping with the manifest view; register - the kind and pass accumulators to `projectAnalysisView` as one object; - always seal the result inferred. -6. Cover domain, service, MCP, CLI, catalog and acceptance behavior; document - the view in the capture guide, the agent environments guide, the contracts - reference and the authored skill. - -No new tool, provider, side effect or network activity is introduced. The state -is a projection of already retained Evidence; serving it is deferred. diff --git a/docs/specs/agent-environments/state-view/spec.md b/docs/specs/agent-environments/state-view/spec.md deleted file mode 100644 index 33bf005cf7..0000000000 --- a/docs/specs/agent-environments/state-view/spec.md +++ /dev/null @@ -1,173 +0,0 @@ -# Environment state view from captures - -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 - -`inspect_analysis_view` accepts `view: {"kind": "environment-state"}` for the -parents the environment manifest accepts and extracts the initial state the -capture's reads observed: entity types with an identity field, entities with -their recorded values, documents for written paths whose reads are not -entities, and a render plan per read tool that reproduces the tool's latest -initial recordings from the state, or a recorded view with the reason it -cannot. This increment adds the view kind only; serving from the state, loading -another state through the AgentEnv data plane and modelling write effects are -later increments. - -Safe `HEAD`, `OPTIONS` and `TRACE` tools have recorded views with reason -`method-replay`; state rendering currently applies only to `GET` reads. - -## Requirements - -- Accept `inspect_web_network_capture` HAR parents and - `capture_browser_scenario` parents that selected response bodies, with the - manifest's admission: the same format, subject and sensitive-value refusals. -- Group records exactly as the manifest does for the same `template_rules`, so - tool names match the manifest the state accompanies. -- Order primary-origin records by recorded start time, or by record order when - any start time is missing, and say which. Bound each type's state by the first - write under its root (API base, version segments, one segment); a query - `POST` is not a write, a read overlapping the write is left out, and a write - whose URL was redacted bounds every type, with a limitation counting it. A - successful `POST` elsewhere bounds a type's state too when its response named - an id (an identity member, or a bare or sole scalar of four characters or - more) that the type's reads show only once it began: the `POST` made that - entity, so it is not in the initial state. A read finished before the `POST` - began shows what was there, and one still running may show its effect. A list - read shows the ids its listed entities carry as their own identity members, an - item read its path's id only when its body shows the item (a JSON `null` shows - none), and - across two or more of them, when no id-named field (`id`, `uuid`, …; not `key`, - `slug` or `name`) identifies them, the first suffix-named field (`projectId`) - distinct on each, so a foreign key beside an `id` is none of theirs, nor are the - ids of entities they nest. An id shorter than four characters counts only - when the type was read before the `POST` and an item read names it after. -- Prove an item type's identity field from the requested path value its - responses repeat; otherwise infer it from a fixed list of identity names that - every listed item carries distinctly, which needs at least one listed item. - An item read that asked for some fields only (`fields`, `fields[...]`, - `select`, `$select`) and does not return the item is left out of the proof - and of the view's checks; the view lists it in `projected_record_ordinals`. - Beside a line showing whole entities, a list line asking for some fields only - (a projection value other than `*`, which asks for all) is listed there too, - and proves no identity or membership. So is an item line first recorded after - the type's initial reads, judged against the lines left once variants are - dropped: one that names a shaping parameter none of them named while its - object carries or lacks members theirs do not, such as a later - `?expand=shelf` read, or one that selects some fields and leaves out members - they always show, such as a later `?fields=id,name` read. On a view with - such replayed reads, serving replays a call naming a projection parameter for - an entity the state holds unless every value it gives is `*` or one a checked - line gave, and no replayed read gave it. The write gate leaves out exactly - the successful reads serving replays, and any read that names one and leaves - out a field its view requires, which serving would answer whole. -- A request line of an item or list view is a representation variant when it - shows an entity another line shows with other members, or names a parameter - the base lines do not (paging aside) while its objects carry a member no base - object carries or lack one every base object carries. Base lines are taken - first: lines naming no such parameter, then lines asking for every field, - then the line most others agree with. A variant leaves the view's checks, the - entity observations and the membership changes that would end the type's - initial reads when a query key tells it apart: a parameter only - variants name, a value no base line gives a parameter, or a parameter every - base line names that a variant leaves out. The view lists its latest - recordings in `projected_record_ordinals` and the keys in - `projected_query_keys`; serving replays a call matching a key with the reason - `variant` (`projection` when it leaves out a projection parameter every base - line names; a projection value is tested as above), so the - answer is a recording and shows no served write. The write gate neither - checks nor learns from a successful read serving replays; a 400, 404 or 410 - such a read answers is still the absence it checks. -- A field every recording of a view carried is required: serving refuses an - entity lacking it. Once a successful read the write gate checks, naming no - projection parameter, shows the application leaves the field out of an entity - the state holds (APIs that omit empty or false members), no view of the type - requires it. - Never treat an envelope that is itself an entity as a list. -- A top-level UUID or clock member that differs on every repeat of a path's - successful GET lines with no write between, and across the capture differed - on at least two repeats and never stayed the same, is minted per response - there (a request id). A view names it in `per_response_members` only when - every concrete path the view answers independently proves it minted. A - collection's proof does not establish that its item paths mint the same - member. The shared envelope compares without these common members, and - serving keeps their recorded values; an unproved envelope difference stays - recorded rather than borrowing another path's value. -- Merge observations into one entity per collection and identity: item views' - latest values win over list views', differing views keep their own values, - and a value that changed between repeats of one request line with no recorded - write is volatile and keeps the latest; a change across a write under another - root, including between two tools of the type, ends the type's initial reads - at the earliest write within the change, and the state is extracted again - once; a type whose reads still disagree keeps every tool recorded. Compare list membership, including empty lists, and field presence before selecting each request line's latest recording; a change across a write ends the type's initial reads the same way. Different query strings remain distinct; omitted fields do not erase their earlier observations on other request lines. -- An item or list view whose recordings always spell a clock field's instant - otherwise than the entity's stored value (`Z` against `+00:00`, another - separator or fraction width) names that spelling in `clock_formats`; a field - it also shows as stored, or spells two ways (counting values at another - instant), gets none. A stored value the view never recorded, such as one a - write made, is rendered in that spelling: its wall clock in the view's zone, - under the view's separator, with its own fraction digits padded with zeros to - the view's width and none dropped; an epoch spelling is computed from the - instant. -- An item or list view names in `sorted_arrays` the fields it lists as string - arrays in code-point order whatever order they were written in (tags kept as - a set). Only the write gate learns it. A field is a candidate when every - initial entity shows it as a sorted string array or null, one with two - distinct strings, and no read the gate counts has listed it unsorted with two - distinct strings. It is learned from a counted read that fails with the - stored order and passes with the field sorted, and only when that read lists - a written array in an order that is neither the written one nor values the - initial state held first, then the new ones as written (an application - ordering by tag id or creation shows that order too). The stored value keeps - the written order, so a write's own answer echoes it; every view of the type - for which the field is still a candidate sorts it as well. -- A collection's initial order is the order of the first line that lists every - entity any initial read shows in it and names no sort, direction (`sort[]`, - `_sort`, `sort-column`, `sortKey`, `orderBy` and like spellings) or random - parameter (`random`, `rand`, `shuffle`, `seed`); a collection without such a - line keeps its entities' earliest sightings. -- A list has `all` membership only when no item-total envelope member (`total`, - `count` and their compounds, not page counts), at the top level or in a - top-level object beside the list such as `pageInfo.totalRows`, differs from - the number of entities it lists and no `has_more`, `next` or next-page token - is set. Such a member that equals the number listed is a counter; a nested - one is named by its pointer (`/pageInfo/totalRows`), and members beside it - such as `isLastPage` stay as recorded. -- Keep an item or list plan only when it reproduces each request line's latest - initial recording from the state, comparing JSON values without regard to - member order; otherwise record the tool with a reason. Parse bodies only when - JSON-like, UTF-8, at most 256 KiB and exactly representable. Preserve all own - JSON members, including `__proto__`, through extraction and normalization. -- Mark the Evidence inferred; state unknowns for authorization, response - semantics and write effects. -- Charge the manifest's admission and grouping, every record line, every body - as temporary bytes before decoding and parsing, and every kept value, within - the existing 96 MiB budget. A planning pass that a rewrite cut discards - releases its charges before the state is extracted again. -- Read response bodies through one domain owner shared with replay, and parse - exact JSON through the owner of the exact-number policy. - -## Acceptance and limits - -The Grafana-shaped HAR fixture with distinct start times drives domain, -service, MCP, CLI and acceptance coverage: folders merge their detail and list -views under a proved `uid`, the dashboard entity is read from its `/dashboard` -wrapper, and the annotation list after the annotation write has no initial -recording. Synthetic captures cover write bounds, volatile fields, complete -lists with counters, each recorded reason and documents; the scenario fixture -covers record order and the response-body requirement. The view performs no -network activity and serves nothing. Values copied outside entity objects, -derived values and cross-type effects are not tied to the state. - -## Deferred issue criteria - -Serving tool calls from the state, `data/reset`, `data/add` and `data/get` on -the environment data plane, exporting the state with a bundle, and write -effects are later increments of #4933. So are documents for item-shaped -written paths (one per identity rather than per template) and for paths that -are only deleted; until then their reads stay recorded. This PR must reference rather than -close the issue. diff --git a/docs/specs/agent-environments/state-view/tasks.md b/docs/specs/agent-environments/state-view/tasks.md deleted file mode 100644 index 10605c5b07..0000000000 --- a/docs/specs/agent-environments/state-view/tasks.md +++ /dev/null @@ -1,12 +0,0 @@ -# Tasks - -- [x] Record the view contract, requirements and deferred increments. -- [x] Move body decoding and exact JSON parsing to their domain owners without - changing replay. -- [x] Implement the extraction rules, merge, gate and accumulator. -- [x] Register the `environment-state` kind, result schema, service wiring and - confidence rule. -- [x] Add the timed Grafana-shaped fixture and synthetic captures. -- [x] Add domain, service, MCP, CLI, catalog and acceptance coverage. -- [x] Document the view in the guides, contracts reference and skill. -- [x] Run static, formatting, duplication, documentation and test gates. diff --git a/docs/specs/agent-environments/state-view/verification.md b/docs/specs/agent-environments/state-view/verification.md deleted file mode 100644 index 48db9935b2..0000000000 --- a/docs/specs/agent-environments/state-view/verification.md +++ /dev/null @@ -1,156 +0,0 @@ -# Verification - -Verified base: bf1eeee9 (fetched main). - -Executed on the implementation worktree after `npm ci` and `npm run -build:cached`; every check below ran as written in this pass, after the last -source change. - -- `npm run check:fast`: typecheck and lint passed. -- `npm run format:check`: passed. -- `npx knip`: passed (exit 0). -- `npm run jscpd`: 3.40% duplicated lines over 3331 files, under the 3.5% - gate; no clone involves a file this change adds. -- `npm run scan:todos`: passed. -- `npm run docs:check`: the built documentation checks and the README - consistency conformance test (5 tests) passed. -- `npx vitest run --project domain --project services`: 338 files, 5830 tests - passed, 5 pre-existing skips. -- `npm run test:focused --` the analysis-view MCP and CLI boundaries, the - environment serve and export CLI boundaries, the environment serve MCP - boundary, the compact input-schema MCP budget, the analysis-detail and - advertised-input-example contracts and the qlog acceptance test: 9 files, 68 - tests passed, 1 pre-existing skip. - -Real captures (outside the test suite): the built view ran through the -application service on 44 recorded captures (39 HAR, 5 browser scenario) with -all three template rules, in 7 to 46 ms each. 42 produced a state: 568 types, -2,213 entities, 2 documents, and 710 of 1,258 read tools state-backed (211 -item, 497 list, 2 document views). The other read tools are recorded views: -306 not entities (singletons, configuration and computed views), 129 without -an identity field, 32 with unusable bodies (most are Nomad bodies with -integers beyond exact native conversion), 31 lists and 7 items that do not -reproduce, 26 without an initial recording, 12 query `POST`s and 5 documents -read under several queries. The two browser-scenario captures that did not -produce a state are refused inline with `resource_constraint`, as the -environment manifest view refuses them on unchanged main. - -Not covered here: serving tool calls from the state, the AgentEnv data plane -and write effects, which are later increments. - -## Linux follow-up (2026-10-20) - -Node 24.18.0 / npm 11.16.0, with the author's `47f8a27a9` main integration -preserved and main `d72021b0d` integrated. Eight regression cases failed across -two pre-fix runs: membership additions/removals across a write, field presence, -sparse field observations, and compact compound totals. The fixes compare -membership before selecting latest recordings, retain each field's observation -across sparse reads, and recognize `totalcount`/`itemcount`. API-base grouping -appends to its owned arrays; identity intersection uses a set and skips the -first response's self-intersection. - -Executed checks: - -- Relevant domain, application and contract suites: 39 files, 493 passed, - 3 existing skips. Includes empty/stable lists, query variants, field additions - and removals, sparse reads, identity proof and deferred document paths. -- Broader compiled CLI/MCP/environment, compact schema and qlog acceptance: - 7 files, 65 passed, 1 existing skip. After the final state fixes, both selected - compiled state CLI/MCP cases passed again (36 other cases deselected). -- Final serial static/build/artifact gate: 11 tasks passed. Typecheck, lint, - format, knip, package metadata and runtime/catalog generation all ran. -- Final documentation/catalog/format validation: 9 tasks passed; architecture - guards passed across 1,602 source files; README consistency: 5 tests passed. - -Real Gitea 28.2.0 used an isolated SQLite database. An owned Node fetch HAR -recorder captured actual API exchanges, omitting transport credentials: - -- Three exchanges: empty repository search, creation through `/user/repos`, - then the same search. On exactly the same authenticated Evidence, pre-fix - `29e745923` published one created repository as initial state; the final - source publishes none and keeps the search recorded with `fields-differ`. -- Eleven exchanges: initial issue list/details and topics, PATCH, PUT and - DELETE, then subsequent reads. The state keeps the two original issues - before ordinal 4 and the original topics document at ordinal 3. File CLI and - default stdio MCP agree; six HTTP SDK replays reproduce original responses. -- Actual Chromium `capture_browser_scenario`: two transactions, eight events, - zero dropped. The state uses record order, extracts one issue, and keeps list - and item plans; file CLI and default stdio MCP agree. The earlier 12.6 MB - real browser capture also projects, keeping oversized bodies recorded with - `body-unusable` rather than parsing them into state. Owned servers and browser - processes were stopped. - -### Resource and performance measurements - -One CPU and one worker. Process-family RSS sums were sampled every 50 ms and -may count shared pages twice. Final source suites: 39.669 s wall / 39.486 CPU s / -898.42 MiB peak; broader boundaries: 270.171 s / 267.136 CPU s / 2,130.78 MiB; -final static/build: 199.683 s / 199.523 CPU s / 4,689.07 MiB; final live HAR -workflow: 22.836 s / 19.880 CPU s / 1,072.43 MiB; actual browser-state workflow: -12.734 s / 10.941 CPU s / 1,549.80 MiB. The qlog acceptance lane intentionally -exhausts an isolated decoder heap and verifies that MCP remains usable; no -workspace OOM occurred. - -The first follow-up benchmark used pre-fix `29e745923` and `6ad63bcc2`, the same -completed Evidence files, Node and CPU affinity. One fresh process per revision, -with a first call and two warm repeats; filesystem caches were not cleared. -Complete normalized output digests matched for both synthetic projection tasks. - -| Work | Before: first / warm (ms) | After: first / warm (ms) | -| ----------------------------------------------- | ------------------------- | ------------------------ | -| Group 8,000 templates (helper only) | 320.08 / 81.01–81.46 | 11.89 / 3.88–4.33 | -| File-to-state projection, 2,000 collections | 1,321.57 / 732.00–939.57 | 1,268.76 / 781.34–811.05 | -| File-to-state projection, one 15,001-field item | 657.05 / 494.82–501.19 | 377.78 / 347.62–380.87 | - -Combined benchmark processes, including imports, three helper calls, six -projections and the live-capture comparison: before 6.536 s wall / 6.496 CPU s / -370.82 MiB peak; after 5.077 s / 5.056 CPU s / 386.53 MiB. Grouping and wide -identity inference improved; the 2,000-collection projection has overlapping -warm timings, and peak memory did not decrease. These few runs do not establish -a general speedup. Model token usage was not measured; no model-task scoring -was run. Initial external probe attempts had incorrect CLI positional arguments -and assumed coverage counted records rather than grouped tools; those driver -errors were corrected before the successful complete runs. - -No new macOS/Windows runtime, state serving, AgentEnv data-plane or write-effects -claim is made. A type first observed only after an unrelated-root write may -still lack the earlier observation needed to detect its effect. Item-shaped -and delete-only document paths remain recorded, as specified. - -## Post-merge write-cutoff follow-up - -Base `3fca2e0ca` includes #5319 and the validated immutable-capture reuse from -#5349. The remaining review finding was repeated write-root parsing for each -read type and again during output assembly. One admitted prefix/wildcard index -now owns parsed write roots, with per-projection positive/negative cutoff -caching. Backed type membership is collected once, replacing another plan scan. -The old linear matcher is removed. Prefix, parameter, redacted-root and timeline -semantics are preserved; no cross-request cache or new authority is introduced. - -- Source checks: 41 files, 508 passed, 3 existing skips, including independent - matching-oracle and 12,000-segment iterative-lookup checks. -- Serial static/build/artifact gate: 11 tasks passed, 197.356 s wall / - 197.195 CPU s / 4,744.92 MiB peak process-family RSS. -- Both selected compiled state CLI/MCP cases passed after rebuilding. -- Live Gitea HAR workflows and fresh actual Chromium capture passed again: - initial values, recorded fallbacks, CLI/default stdio parity and six exact - HTTP replays. HAR workflow: 22.834 s wall / 19.623 CPU s / 1,067.36 MiB; - browser workflow: 22.858 s / 20.912 CPU s / 1,546.59 MiB. Owned processes stopped. - -The same completed Evidence with 1,000 collection reads and 1,000 unrelated -writes was projected before and after on one CPU. Two larger full-HAR inputs -(3,000/4,000 total records) were refused by the existing 96 MiB admission budget; -the limit was retained. One fresh process per revision, first call plus one -warm repeat, filesystem caches not cleared: - -| Complete file-to-state projection | Main before | Follow-up | -| -------------------------------------------------------- | ------------------- | ------------------- | -| First call wall / CPU (ms) | 1,727.89 / 1,727.36 | 1,244.82 / 1,244.05 | -| Warm call wall / CPU (ms) | 1,300.84 / 1,300.42 | 624.01 / 623.89 | -| Process wall / CPU (s), including imports and both calls | 4.690 / 4.363 | 3.370 / 3.062 | -| Sampled process-family peak RSS (MiB) | 365.84 | 360.03 | - -Parent Evidence IDs and complete normalized output digests were identical. -RSS sampling is every 50 ms, includes descendants and can double-count shared -pages; these few runs do not establish a general memory reduction. Model token -usage remains unmeasured. No workspace OOM occurred. diff --git a/docs/specs/agent-environments/state-writes/plan.md b/docs/specs/agent-environments/state-writes/plan.md deleted file mode 100644 index e8550238b2..0000000000 --- a/docs/specs/agent-environments/state-writes/plan.md +++ /dev/null @@ -1,45 +0,0 @@ -# Implementation plan - -The branch builds on the state-serving and coverage branches (merged into it). - -1. **Write plan types and request bodies.** Add the plan, rule and reason types - beside the state rules, and have the state accumulator lend extraction - parsed request bodies under the same budget, admitted like response bodies. -2. **Field rules.** Add a module that explains an observed entity against the - call that wrote it (echo, copy, path, slug, clock, sequence, unique, - template and constant) and that recognises and formats clock values, - UUIDs and tokens. -3. **Effects.** Add one apply module that both the gate and the server use. It - applies a create, update, delete or document write to a writable state - interface from a plan, a call and a value source: the recorded values in - the gate, the store's generators when served. -4. **Gate.** Add a simulation that: - - classifies every write tool; - - builds each plan from its exemplar; - - walks the timeline over a copy of the initial state; - - checks state-answered reads; - - attributes passes and mismatches; - - learns the insert rule; - - records verdicts. - - Extraction runs it after the read gate and returns `writes` and - `write_clock`; the view schema and its unknowns state the write model. - -5. **Serving.** - - The loaded state carries the plans and the clock. - - The store gains atomic mutations, the clock and the counter (all reset by - `data/reset` and `data/add`). - - A write answer module validates the body, applies the effect and renders - the response. - - Item reads of missing entities answer recorded 404s. - - The served catalog adds served write tools, with descriptions charged to - the discovery budget. -6. **Export.** Count served write tools in the bundle plan and README. -7. **Tests.** Domain, services, adapters and MCP-boundary coverage as the - spec's acceptance lists. -8. **Documentation.** Document the write model in the environment-state and - serving sections, and record the real-capture results, the AgentEnv run - and the live comparison in `verification.md`. - -There are no dependency, provider or REA tool contract changes beyond the -`environment-state` result members, and no new network activity. diff --git a/docs/specs/agent-environments/state-writes/spec.md b/docs/specs/agent-environments/state-writes/spec.md deleted file mode 100644 index 0a0cf81316..0000000000 --- a/docs/specs/agent-environments/state-writes/spec.md +++ /dev/null @@ -1,720 +0,0 @@ -# Apply write effects to the served state - -Issue: https://github.com/morluto/rea/issues/4933 - -## Outcome - -An environment served from its state also serves the write tools whose effects -the capture itself confirms: - -- a create adds an entity; -- an update changes the fields the call sends; -- a delete removes the entity; -- a document write changes a document. - -Later reads, list membership and `data/get` show the change, and `data/reset` -undoes it. - -The `environment-state` view decides which write tools are served. It replays -the capture's own timeline on the extracted initial state: each recorded write -applies its modelled effect, and each later read that the state answers is -rendered and compared with the recorded response. A write tool is served only -when at least one later read reproduces after its effect and none contradicts -it. Every other write tool stays unserved, listed with the reason. - -Values the application generates are deterministic: identities, sequences and -clock values follow the formats the capture recorded, so the same calls after -a reset give the same state. - -## Write plans - -The view adds two members to its result: - -- `writes`: one plan per manifest tool whose method may change state - (`changesState`), less the `POST` tools the capture shows only reading (below); -- `write_clock`: the instant the served clock starts from. - -**Calls that only read.** A `POST` tool whose calls read state is no write: it -gets no plan, stays a recorded view with the reason `query-body`, is served by -replay, and its calls bound no initial-recording window and end no observation -search. The capture shows it by the first of these that applies: - -1. every successful call answers as the successful `GET` of its path that - finished last before the call began, of those with no write between, did (a - status lookup posting the jobs it names); -2. every call names read operations only, in its body's `operation` or - `operations[].operation`, else its query's `operation`, `op` or `action` - (`batch` and similar only wrap them, in either place, so a call needs at - least one other, and every `operations` entry must name one of its own, so - an entry with no string operation or another container keeps the call a - write); an operation reads when its words name one of `list`, - `get`, `count`, `aggregate`, `info`, `search`, `find`, `read`, `query`, - `schema`, `describe`, `fetch` or `lookup`, and none of `create`, `insert`, - `update`, `modify`, `replace`, `delete`, `remove`, `upsert`, `add`, `set`, - `save` and similar, so `findAndModify` and `findOneAndReplace` stay writes; -3. the path's last literal segment has a query word as its last meaningful - word, split on `_`, `-`, `.` and case and skipping trailing `data`, `info` - and `results` (`search`, `query`, `list`, `find`, `lookup`, `count`, - `aggregate`, `stats`, `ids`, `selection`, `discover`, …), and no write word: - `selection_data` names a lookup, while `query-history` names a history, - `create_lookup` a create and `selection_data/import` an import, and each - stays a write; -4. the path's last literal segment renews or opens a session: `auth-refresh`, - `auth-with-password`, `login`, `logout`, `refresh` or `token`. - -A tool stays a write when one of its calls was redirected or went unanswered, -since nothing shows what it did. It also stays a write when a `GET` line whose -path its call's path relates to (segment by segment, a parameter matching any -value) reads differently just before and just after one of its calls, or finds -its entity on one side only (a 400, 404 or 410 on the other), with no other -write between; the other read-only tools' calls are no writes there, so the -tools are dropped until none is vetoed. Those reads are the one that finished -last before the call began, of those no other write follows, and the first that -began after it ended, since one overlapping the call may show either state. Reads of unrelated paths do not -count, so a session renewal stays read-only although an endpoint under the -same root regenerates values on every read. - -**Effects.** Each plan classifies its tool: - -| Effect | Tool | Target | -| ---------- | --------------------------------------------------------------------- | ------------------------- | -| `create` | `POST` to a state type's `collection_template` | an entity of that type | -| `update` | `PUT`, `PATCH` or `POST` to that template plus one trailing parameter | the entity the path names | -| `delete` | `DELETE` to that same item template | the entity the path names | -| `document` | `PUT`, `PATCH` or `POST` to a document view's path | that document | -| `none` | anything else | reason `no-state-target` | - -**Item actions.** A `POST`, `PUT` or `PATCH` to an item path plus one literal -segment (`/{type}/{id}/archive`) is an `update` of the entity the item path -names, recorded as `address: {by: "action", segment}`, when the segment names -no collection (no state type ends in it, and it is not `delete`, `remove` or -`destroy`) and every successful call answered nothing or that entity: never a -201, and an object holding the id at the type's id field where an item read of -the type shows its entity, with every field that read always shows. A call -answering anything else made a sub-resource, as a comment `POST` does, and -stays `none`. An action's unsent change of a scalar that no other rule -explains takes the value its observation showed, a `set` rule applied on every -call (`archived: true`); a changed object, list or instant has no rule, so the -plan is `unexplained-change`. An action is served only when it sets something -and a recorded call found every field it sets already at that value, since one -change cannot tell a set from a toggle; otherwise it stays `unconfirmed`. Its -call may send no body. An action is observed in its own response, or in a -later item read only while no other tool's modelled write to the entity awaits -a check: that read then checks the other write, and the action's call is one -the gate does not model. - -**Bulk writes.** A `DELETE`, `PUT` or `PATCH` at a type's -`collection_template`, or a `POST` to it plus `delete`, `remove` or `destroy`, -names its entities in its body: an array of ids of one JSON kind, or of -objects carrying the type's `id_field`, at the root or as the body's one array -member (`{"IDs": […], "Read": true}`, `[{"Id": 9}]`). Every successful call -must name them the same way, recorded as `address: {by: "ids", member, kind}` -or `{by: "elements", member}`. A path whose last segment is the type's -singular or plural (`/messages` for `/message`) writes that type. An `ids` -member applies the body's other members to every id, an element its own -members; a root id array updates nothing. Each named entity gets the effect as -an item call would, checked by the same reads; one the state does not hold -leaves the call unmodelled there. A bulk update's observation must show the -members the call sent. Serving answers any ids only when the exemplar's -response fits: no body, a body naming none of the recorded ids and holding no -number equal to how many it named (a count), or an array with one element per -id, each showing it as the first does; otherwise the reason is -`body-unusable`. - -A `POST` whose path gives it no target is a `create` into the type its returned -id is read under: its exemplar's response names an id (an identity member of the -body or of an object member, or a scalar body or sole member of four characters -or more), and the first later successful item read naming that id, whose body -shows the item (a JSON `null` read is passed over), belongs to a state type. That read must come before any other tool's write, which may have -made what it shows, as a publish call makes a note from a draft. The entity must -be new: neither the initial state nor any read finished before the call began -holds that id (one still running may show what the call made): an item read of -it under the item read's type or collection whose body shows the item (a JSON -`null` is an absence), a list read of its type, or any read of that collection, whether an -item read of it, a list read of its type, or any read of the item read's -collection, with or without a query, that lists it under an identity member of -its own (a body with no list counts an identity member at any depth). An id shorter than four characters may be any type's, -so it links only to a type a successful read showed before the call. The plan -records that read's collection, and serving creates there, since the call's own -path names no collection of the type. That collection holds only for the -exemplar's path arguments, compared segment by segment, each as recorded or in -the other spelling once percent-decoded: serving refuses a call with others, and the gate counts such a -recorded call as a write no built plan models. Its path fields take the -exemplar's path values decoded once, the source it accepts, whichever spelling -the call sends. A linked create's call is -observed only in a read of an id its response returned, at the top or in an -envelope member, so another unseen item's read is never taken for it. - -**Exemplar.** A plan is built from its first successful (2xx) recorded call, -the exemplar. - -- **Request body.** The exemplar's request body must be a JSON object that - could enter the state: a JSON-like media type, complete UTF-8 text within - 256 KiB and exact numbers. All own JSON member names are retained. Otherwise the reason is - `body-unusable`. A `DELETE` takes no body. A create's or update's body - whose only member wraps one object in a one-element array (Ghost's - `{"posts":[{...}]}`) is that object, and the plan records the member as - `body.envelope`: serving takes only a body wrapped that way. -- **Query.** Serving takes only the query parameters the exemplar sent, with - its values, since they may change what the body does (Ghost reads `html` - only with `?source=html`): a parameter a call leaves out takes the recorded - value, as the recording sent it, and a call with another value or parameter - is refused, a bulk call included. The gate treats a later recorded call sent - with another query, or wrapped otherwise, as a write its plan does not - explain: it brings the entity to what the call recorded, without - attribution, and a bulk call leaves the entities it names unmodelled. -- **The written entity.** The entity is observed in the exemplar's response, - located by its identity value at the root, in one member, or in a - one-element array, as item views locate it. When the response does not carry - it, the entity is observed in the first later read that shows it: an item - read of that entity, or for a create, the one entity a collection read newly - lists. A create whose response names its id alone (a scalar, the identity - field, or one member) is observed only through a read of that id. With - neither, the reason is `no-observation`. - -**Field rules for creates.** Each field of the observed entity gets the first -rule that explains its value. Rules that read the call come first, so an -identity the client sends is an echo: - -1. **Echo.** A body member of the same name with an equal value. -2. **Copy.** A body string of 8 or more characters, found at a JSON pointer of - the body (the shallowest match). -3. **Path.** The value of a path parameter of the call, percent-decoded. - Serving decodes it from the collection the call names, whichever spelling - the call uses, and the gate fills a recorded call's path fields from that - collection too. -4. **Slug.** The slug of a body string member: lower case, runs of other - characters joined by `-`. -5. **Identity.** The type's `id_field` is generated. A sequence when it is an - integer (or a string of digits); otherwise a UUID when it has the - `8-4-4-4-12` hex shape; otherwise a token of the same length and character - classes. -6. **Clock.** A timestamp within 10 minutes of the exemplar's start time. The - format is kept: ISO-8601 with its separator, fraction digits and zone, or - epoch seconds or milliseconds. An object whose every clock lies between 1 - second before the start time (a whole second's truncation) and 2 seconds - after it, in one format, is a nested clock when the type's other entities - hold that field as objects agreeing with it in every other member and - holding other clocks: served, those members take the write's clock and the - others are kept. A reference to another entity, which differs by entity or - was made before the request, is not one. -7. **Sequence.** An integer one greater than the largest value of the field in - the collection, else in the type. The integer may be written as `-`-separated - digit groups of one width of at least two digits (an asset number `000-005`; - not a date, version or address); a served value keeps the recorded value's - groups and zero padding, and digits that outgrow them lead. A later call must - record the value spelled that way. -8. **Unique.** A UUID-shaped string that no other entity of the type shares, - or an opaque token (16 to 64 letters, digits, `_` or `-`, with letters and - digits both) that no other field of the entity repeats, where every other - entity of the type holds a token of the same length and none this one. - Serving generates a token of the same length, character classes and - separator positions. -9. **Template.** A string containing a generated value, or else a copied - value, as a delimited token (for example a URL that ends in the new id or in - a slug the call sent under another name). It is rebuilt around the new - value. An echoed value is not a token, nor is a copy of one: it may recur in - unrelated text. A copied or echoed member whose value also sits in text no - template rebuilds around it (beside another source in one template, or in a - constant) is accepted only with its recorded value. -10. **Constant.** Otherwise the exemplar's value. - -When a constant, or the text a template keeps, contains a path value of the -exemplar's call as a delimited token, the create is served only for calls -naming the exemplar's collection. - -A constant may also derive from a member without holding its text, when the -constant is named after the member: with a reference's `Id` or `_id` left off, -one name's letters and digits begin the other's (`parentId` and `parentName`, -`dateEndDate` and `dateEnd`), three or more of them. Such a member is accepted -only with its recorded value when it names another entity the copy holds (by -its id, among the types whose paths hold the member's name when any does; a -value shorter than 8 characters only under a member named as a reference, such -as `parentId` or `parent_id`) whose own string of 8 or more characters the -constant repeats under another name, neither name reading as a reference; or -when it sends a date or time that the constant's instant lies within two days -of (an end date stored as a time in another zone). - -**Body members of a create.** A member is either accepted or not: - -- **Accepted.** An echoed member, a member copied whole into a field of another - name and stored under none of its own, or the identity field's value. A - member copied whole must have the JSON type of the field it is copied into. - Every member the exemplar sent is required. -- **Accepted only as recorded.** An echoed member naming the object the entity - nests under the field it refers to (`collection_id` and a `collection` - object), whose other members serving would keep as recorded; and a state - word other fields go with: a lowercase word several entities share, where - every entity in another state holds a field the new one leaves null, or the - reverse (Ghost's `status: "draft"` beside `published_at: null`), unless the - tool's recorded calls sent other values of it. Updates take a member naming - a nested object only as recorded too. -- **Not accepted.** A member the application stored with a different value - (transformed), or one it did not show. A call that sends such a member is a - tool error naming the accepted members. - -**Updates.** Body members follow the same accepted and not-accepted rules, -except that a member the application stored differently is accepted only with -the value a recorded call sent it with, and then stores the value that call -recorded (its `constant` rule carries it). The type's identity field never -takes a rule: sent as the path's id it is the identity member, sent as another -value the application ignored it is accepted with that value and stores -nothing, and a stored id that changed is `unexplained-change`. A plan whose -calls use a member both as the identity and as a fixed member, or fix it at -different values, is `unexplained-change`, as serving could not take every -recorded call. So is an update a later read shows dropped a field the -entity held, since serving keeps every field an update does not write; a write's -own response may leave fields out. A member the application replaced -with a fresh UUID (`unique`, below) is accepted with any value; a UUID stored -as sent in another letter case is the sent value, not a fresh one. A member a later call is the first to store, -which the plan's observation does not show, keeps the JSON type that call stored -it as (the body's `kinds`), as an exemplar's member keeps the observation's. -`PUT` requires every member the exemplar sent; `PATCH` and `POST` require at -least one. A sent clock the call left as it was, stored in whole seconds and -naming the second the call ran in, is a `held-clock` the application stamps -anew (Ghost's `updated_at`, which a client sends back as it read it), when it is -the only such member the call sent: a call must send it as the entity holds it, -or it is refused, and it is served as the write's clock. An unsent clock the -call left as it was, stored in whole seconds and naming the second the call ran -in, cannot show whether the update stamps it, unless it names when the entity -was made (`createdAt`, `row_created_timestamp`): the plan stays `unconfirmed` -until another call shows it stamped, and that call's clock rule then holds -without the first call contradicting it. A field the exemplar's update changed -without sending it is explained as one of: - -- clock; -- a nested clock: an object the entity held whose only changes are clocks - within 10 minutes of the start time, in one format, where the type's other - entities hold that field as objects agreeing in every other member. The gate - stores the object the first later read of the entity shows when it differs - from the write's only in those members, each within 2 seconds, as Metabase - answers an update with one instant and stores another. Serving refuses it on - an entity holding no such object; -- an increment by one; -- a slug of an echoed member, judged before a token, since a renamed slug is - spelled like one; -- `unique`: a UUID in place of another UUID, or an opaque token in place of - another of the same length, that no other entity of the type holds and the - call sent nowhere in its body (a version the application assigns on every - update); -- `stamp`: the acting user on a field named `modified…by`, `updated…by`, - `edited…by` or `changed…by` (or `last…`), stored on every call, when the - entity already held the value under its `created…by` counterpart - (`modifiedByName` and `createdByName`), and the call sent no member naming - the same thing (`modifiedById`). The other `…by` field naming the same user - (`modifiedById` beside `modifiedByName`) is stamped with it when the call - showed it at its own `created…by` counterpart's value, even where the entity - lacked it before; -- `derived`: when the call sent exactly one member the entity stores nowhere, - a value showing that member's text, markup aside (at least 8 characters): a - field Ghost derives from the `html` it was sent. The member is accepted only - with its recorded value, and a call sending it is served only on an entity - holding the value the recorded call found (`from`), else refused; -- `renewed`: an array or object whose only changes are UUIDs replaced by ones - that neither it nor another entity of the type held, as child rows an update - rewrites are. The rule names the pointers it renewed at (`*` for any array - index): every UUID at them is new, each old UUID by a single new one, and - UUIDs elsewhere, such as a row's references, are kept. One call renews a - UUID alike in every field and in either letter case, and never two old UUIDs - into one new one. - -A field the entity lacked before is a change too when the view that observed -the update had shown the entity, so a field the application fills in on update -follows its rule. Any other change is `unexplained-change`. An increment, a slug, a stamp or a derived value applies to -every call that could take it, and `unique` and `renewed` to every call, so the -plan is also `unexplained-change` when such a rule would give a call of the -tool another value than the one it recorded, a recorded call kept a `unique` or -`renewed` field, or a later call treats a member otherwise than the plan: one -call echoes it and another stores something else, or the two rule it -differently. - -**Deletes.** A delete removes the entity. Its response is the exemplar's -response, with the entity re-rendered when the response carries it. - -**Documents.** A document write merges the body's members (replaces them, for -`PUT`) into the document object that holds most of them: the root or one -member. Later calls write at the exemplar's object. Document reads answer only on their recorded line, so a write is -served only at the path the state holds the document at, each segment verbatim -or either spelling once percent-decoded, and the gate treats a recorded write -at another path as an unmodelled write. A recorded write whose -body serving would refuse (a member of another JSON type than the document -holds) is `unexplained-change`. - -**Responses.** A write answers with the status and content type of one -recorded response: - -| Response | Body | -| ---------- | --------------------------------------------------------------------------------------------------------- | -| `entity` | the written entity, rendered into the recorded envelope at the plan's pointer through the recorded fields | -| `identity` | the recorded body with the new identity at the plan's pointer | -| `empty` | no body | -| `recorded` | the recorded body | - -A rendered body missing a field the recorded response carried is a tool error, -and the state is left unchanged. - -**List position.** A create's `insert` rule places the new entity in its -collection's order: sorted by the identity field or a clock field (ascending -or descending), `first` or `last`. The rule is the first candidate consistent -with both the initial `all`-membership recordings and the position a later -recorded list shows. With no evidence, the rule is `last`. A sort by a -random identity (version 4 UUIDs, or generated ids every creation clock lists -in another order) is a candidate only after `last`: the recorded order by it is -a coincidence until a list shows a create placed by it; time-ordered ids -(ObjectId, ULID, TSID, version 7 UUIDs) keep it. When the sorts the recorded -order admits would place the created entity differently, none is claimed -before `last` until a later list settles it. - -## The gate - -The view replays every primary-origin record in timeline order on a copy of -the initial state. - -**Writes.** Only a 2xx write is modelled. A modelled write applies its effect, using the values it recorded -for generated fields and the stored values for fields it transformed. A -modelled write whose call the plan does not explain brings its entity to the -recorded outcome instead, without attribution. So does an update of an unknown -entity (below): its call cannot be checked, so it adds nothing to a built plan. -A later create whose generated -values take another form than serving gives them (a sequence value out of -order, a clock in another format, a non-UUID unique value) makes the plan -`unexplained-change`; integer identities are left to the id mapping. A later -create outside the collection a tied plan permits is unmodelled, as serving -refuses that call, so a read of what it recorded does not confirm the plan. The -gate picks that collection among equal spellings in serving's order (below). An update or -delete names its entity as an item read does (below). A later update that does -not answer with its entity is observed only by a read whose view shows every -clock the plan learned, since serving stamps them; without one it is unmodelled. - -Any other write that may have changed state, including a redirected or -unanswered one, is unmodelled, and what it may have changed -depends on where its path lies relative to each type's collection paths -(segment-prefix related, parameters matching any segment): - -- **Below an item path:** the named entity is unknown until a read shows it - again. When the path names no held entity, every entity of that collection - is unknown. -- **At a collection path:** that collection is not checked again. -- **Above collection paths:** everything under the path is not checked again. - -The path names its entity as an update's does and its collection as a create's -does, so a plain spelling reaches a collection held under an encoded one; a -path above collections covers each collection whose segments are its own -verbatim or once percent-decoded. - -An item read of an unknown entity shows it again: the copy takes its recorded -values. A failed read that is no absence shows nothing, and the entity stays -unknown. Writes that changed it since its last check are checked only on the -members they sent, less those the view treats as volatile, which show nothing -of a write. - -A write no built plan models can also make an entity the copy never held, such -as a row an import or a nested create added: a write of a tool with no create, -update, delete or document plan, a call of a tool whose plan was never built, a -linked create's call that serving would refuse, or any write redirected or left -unanswered. -A successful item read of an entity the copy has never held (no initial entity, -and none a modelled write created, changed or removed) that names it by the -type's identity, when such a write ran since that entity or its collection was -last checked, shows that entity: the copy takes its recorded values instead of -failing the read, and later writes to it are modelled and checked as usual. The -taken entity counts against the view's budget as a created one does. An -entity a modelled write touched is never taken back this way, and a built plan's -call that serving would not apply, such as a create outside its tied -collection, keeps its evidence. - -**Reads.** A read is checked when the served environment would answer it -from the state (an item, list or document read compares without the view's -`per_response_members`): - -- an item read of a state-backed item view, of the entity serving would name: - in a held collection the read's path matches, each segment verbatim or either - spelling once percent-decoded and verbatim spellings first, the id - percent-decoded once, then as written; -- a list or document read on one of its view's checked request lines, - chosen as replay chooses the line for the read's call: each path parameter - the read's value verbatim or either spelling once percent-decoded, preferring verbatim - spellings, then recorded order, and the query values decoded, in any order. - A read with no query on a whole list falls back, as serving does, on a - checked line that only pages it. A line whose query repeats a name with - different values is never chosen, since no call's arguments can name it; one - repeating a name with one value is, as a call naming it matches both. A list - is compared as served from the collection of that line. A read on a page - (`limit`, `size`, `per_page` and the like, or a `_start`–`_end` range; a size - of zero is no bound on a line whose recording listed items under it, while its - other sizes and range still bound the page) of a - whole list checks nothing once the collection holds more entities than the - page, which serving then answers from its recording. A line without proof of - whole membership lists its recorded members still held, unless a learned - query evaluates the read over the state. An empty later page therefore does - not contradict a create outside that page. -- A read made while a modelled write to its entity or collection was still - running, starting before that write ended, checks nothing: it may show the - state before or after the write. Nor does such a read show an unknown entity - again. -- A read a write's effect was learned from checks nothing of that write, but - still contradicts the other writes it exercises. - -**Comparison.** The read's answer is the full response serving would give from -the copy: an item read's entity rendered into its item view's base recording, -or a list read's members as serving would list them (so a member the copy no -longer holds fails the check) rendered into its line's base recording. It is -compared with the recording, as the read gate compares, with volatile fields taking the -observed values. A recorded 400, 404 or 410, or a 2xx with a JSON `null` -body, for an entity the copy does not hold agrees with it. A successful read -whose usable body no longer holds the entity or the list fails, as does one of -an entity lacking a field every recording of its view carried, which serving -refuses to answer with. - -**Attribution.** - -- A check exercises the write tools that changed its entity or collection - since the previous check of it, less those whose effect later writes erased. - An update's effect is the fields it sent or changed, derived ones included. - A later update overwrites the fields it sets (an increment adds to its field - instead), a recorded outcome every field, and a create or delete the whole - entity. A document write's effect is the members it merged at its - object, or everything under the object it replaces, the whole document at the - root; an entity's fields match by name only, whatever their names look like. A write with nothing left on an entity no - longer counts there, nor in a collection where no entity it changed keeps any - of its effect. A mismatch contradicts them. A pass confirms those it shows - something of: a create's or delete's membership, or a changed field the - read's view shows and does not treat as volatile; a read that shows none of - an update's changes confirms nothing of it, and leaves it for a later check - of that entity or collection. -- A mismatch contradicts each exercised write that no unmodelled write came - after its latest call on any of the read's entities or collections where its - effect survives, whatever earlier write is still pending. For a failed list read the unmodelled write must - also follow the last check and pending writes of each member that differs, so an older change elsewhere - does not excuse a newer write the list shows undone. An item read checks the writes an unmodelled - write did follow only on the members they sent, and a list with such a write - is not checked again: the unmodelled write may explain the rest. -- A failed item read with no such unmodelled write contradicts the writes that - changed the whole entity (its create or delete). When one of them is - exercised, each exercised update is checked instead on the fields its effect - holds, and confirmed when those show as the copy holds them and its latest - call's response shows every other field it and the read both show (but - volatile ones and those other updates wrote) as the read does: serving - answers an update from the copy, so a response that shows the entity - otherwise would be answered wrongly. A field the copy lacks that the read and - an exercised update's response both show, with the same value other than - null, is that update's change: an update whose effect does not hold it is - neither confirmed nor contradicted by the read, and when such changes are - the read's whole difference the entity's own writer is not contradicted. - When the read differs on a field the copy holds that no exercised update - wrote, any of the writes may have caused it, and each is contradicted. -- A failed item read whose field newly embeds an entity a create made (an - object in the field, or within it, naming it by its id and by another of its - strings of 3 or more characters, 8 or more when the id is shorter than 8), - which the copy's value lacks, contradicts that create: serving would not show - the change it made there. -- A mismatch on an entity or collection that no write changed contradicts, - as `side-effect`, the modelled writes since that previous check whose paths - are segment-prefix related to the read's path. When a refused write's - recorded outcome since then left the entity lacking a field every recording - of its view carried, the create that made it is contradicted too: an outcome - merges only what its answer showed. -- After a failed item check, the copy takes the read's recorded values (or - drops the entity on a recorded absence). A list whose check failed is not - checked again. -- A failed item or list read the gate counts passes when the view lists some - string-array fields sorted and its order rules out the written one and the - order the values were first held in (see `sorted_arrays` in the state view); - the type's views keep the fewest such fields the read needs, and the read - checks the writes it exercises. A counted read listing such a field unsorted - rules it out for its view. -- A list that fails only for where one create placed its entity passes when - another of that create's insert candidates reproduces it, which then - becomes the plan's rule, unless an earlier list check relied on the rule - (an item read's confirmation does not fix it). -- The read that supplied a create's or update's observation does not check - it, but checks the other writes it exercises. - -**Verdicts.** A plan is served when at least one check confirms it and none -contradicts it. Otherwise the reason, in this precedence, is: - -1. the first build reason; -2. `contradicted`, with `contradicted_by` naming the first contradicting read; -3. `side-effect`; -4. `unconfirmed`; -5. `incomplete-entities`: an update or delete that answers with the entity, - when no initial entity holds every field its recorded answer shows (for - example a delete that answers with an edit view of the entity the reads - never showed), so it could answer only for entities the environment itself - created. An update's answer renders the entity it wrote, so a field one of - its rules writes counts as held, except an increment's, which adds only to - a held value; -6. `unknown-clock`: an otherwise servable plan needs `clock`, `held-clock`, or - `nested-clock`, but the capture establishes no global served clock start. - Its learned rules and confirming reads remain retained, and plans without - this clock dependency remain eligible for serving. - -`checked_record_ordinals` lists the confirming reads. - -## Serving - -**Catalog.** In state mode, the catalog adds the write tools whose plan is -served. Their descriptions say the tool: - -- applies its effect to the served state; -- names its target type; -- lists its required and accepted body members, quoted and sampled within the - description budget as response fields are, the members it accepts only with - their recorded value, with that value when its JSON text is 120 characters - or less, and the envelope a body wraps its object in; -- names the query its recording sent. - -The input schema says the same: each query parameter the recording sent is -optional, defaulting at execution to its recorded value, with a nonempty value -as the only `enum` member; an empty value is described and enforced at execution -because some clients reject empty literals. A body that wraps its -object requires that member, an array of one object; and a member accepted -only with its recorded value carries that value as `const` when it is short -and neither a boolean nor an empty string (some clients reject these literals), else a description -saying it must equal the recorded value. A refused member's message names the -recorded value the same way. - -The discovery budget charges them. `--replay-only` and the replay fallback are -unchanged. - -**Calls.** A served write answers synchronously against the live store and -changes it atomically, so every MCP session and `data/get` see one state. - -**Refusals.** These are tool errors that leave the state unchanged: - -- a body that is not an object; -- a missing required member; -- a member that is not accepted; -- a value of another JSON type than the exemplar's (for a member only a later - update stored, that call's), for documents as well as entities; -- an update or delete of an entity the state does not hold; -- a create in another collection when the plan is tied to its own; -- a document write at a path other than the one the state holds it at; -- a body member or a resulting value `data/add` would refuse (a number not - exact as `data/get` writes it or nesting past the - limit), increments included, so `data/get` always loads back; -- a create, update or document write that would take what `data/get` reports - past the 32 MiB `data/add` intake limit, as a `resource_constraint` error; -- a rendered response missing a recorded field. - -When the tool, or else an item view of the type, recorded a 400, 404 or 410 -response, an update or delete of a missing entity answers with the latest such -recording instead. - -A create in a collection held under more than one spelling (`acme1` and -`%61cme1`) goes to the one the call spells verbatim, as item calls choose their -entity; a collection keeps its spelling after its last entity is deleted. A -reset or load knows the spellings of the Evidence's state, of the state it -installs and of the type's checked list lines (so a collection the capture -listed empty keeps its spelling), never those of a state it replaced. When two -spellings fit a call equally, the one holding entities wins, the earlier first -entity in state order among held ones and the earlier known among emptied ones. `data/add` refuses a document that `data/get` would write back past the -32 MiB intake limit once it adds the members a document may omit, such as -`types` and the state Evidence id. A derived state `data/get` would write -past that limit is not served: the environment serves replay and reports the -state `unavailable`. - -**Clock and generators.** The store's clock starts at `write_clock` and -advances one second before each served write; clock fields take its value in -their recorded format. - -- **Sequences:** one more than the largest current value in their scope, the - largest the state started with at its last reset or load, and the largest - value they generated, so a deleted entity's value is not reused, as database - sequences do not reuse values. -- **UUIDs and tokens:** derived from a SHA-256 of the state Evidence id, the - tool, the field and a write counter, skipping values the type already holds. -- **Renewed fields:** the entity's current value with each UUID at the rule's - pointers replaced by one derived from a SHA-256 of the state Evidence id, the - tool, the write counter and the UUID's order in the call, the same - replacement wherever the call renews that UUID in either letter case, spelled - in each place's case; held values are not skipped. - An entity without the field is left without it. - -`data/reset` and `data/add` restart the clock, the counter and the -sequences. - -**Missing entities.** An item read of an entity the state does not hold -answers with the tool's latest recorded 400, 404 or 410 response, or 2xx JSON -`null` response, the absences the gate accepts, when it has one, labelled -`state.view: "missing"`. Otherwise it stays a tool error. - -**Lists of a whole collection.** Written entities matter only if lists show -them, so the read gate's `membership: "all"` also covers a line that only pages -its list (`limit`, `offset`, `page`, `per_page`, `perpage`, `page_size`, -`pagesize`, `size`, `start`, `_start`, `_end`) when its recording listed the -whole collection at a proved zero start. Positive `page` values do not prove -the beginning, because their base is unknown. Whole membership is per line: -`all_record_ordinals` can name whole lines within a recorded-membership view. -A learned query can filter, search, sort and page the state; otherwise a later -page lists its recorded members still held. A list call with no query argument -answers from a whole line of the collection its path arguments name, with -`replay.exact_match` false; a collection with no such line answers from its -recording. A call that asks for a page evaluates a learned query when one -covers its arguments; otherwise it keeps the recorded page members. - -**Provenance.** Write answers carry `state: {source: "state", view: "create" | -"update" | "delete", type, collection, id}`, or `{source: "state", view: -"document-write", path}`. A bulk answer adds `ids`, every entity it wrote in -body order, `id` naming the first. - -**Bulk and action calls.** A served bulk tool takes its body as recorded (an -array of objects or of ids of the recorded kind, or an object), a `DELETE` -included, and `environment-compare` sends a probe's body to it; every id must -name an entity the state holds, else the call is refused and the state is -unchanged. A bulk -update with a `unique` or `renewed` rule writes one entity per call, since one -call draws those values once. A bulk write changes or removes its entities in -one step, so a call the state cannot hold changes none of them. A served item action's path names its entity -before the action segment. - -**Data plane and export.** - -- `data/get` reports written entities without record citations; they load - back through `data/add` unchanged. -- `environment-export` counts served write tools in the bundle's tool count - and README. Its check stays a read tool. - -## Not modelled - -These stay unserved, or are labelled in the description: - -- side effects on counters, relations and copies of entities in other - collections; -- inputs the application transforms; -- members the capture never sent; -- reordering after an update; -- membership of filtered or paged lists, which answer their recorded members; -- write paths the manifest left literal; -- writes whose request body the capture did not retain; -- referential rules on delete: a delete removes the entity alone, so an - application that refuses to delete a referenced entity, or deletes its - dependents with it, is not modelled; -- authorization. - -## Acceptance - -- **Domain tests:** classification, every field rule, request-body admission, - observation from a later read, the insert rules, every verdict and reason, - attribution and resynchronisation, and taint by an unmodelled write. -- **Services tests:** - - store mutations and their atomicity; - - every refusal; - - generated values and their determinism across reset; - - `data/get` round trips of written entities; - - the recorded 404 for missing entities; - - the catalog and descriptions in each mode. -- **Boundary test:** a write tool changes the next read over MCP. - -**Real captures.** - -- The view runs over every showcase capture within its budget, and the - verification reports, per capture, the write tools served and the reasons - for the rest. -- One environment, chosen at random among those serving a write tool, is - exported, run in the AgentEnv framework, and graded from `data/get` after an - agent's create, update and delete. -- The served model is compared with that application running live on the same - calls. - -No test reaches an external network. diff --git a/docs/specs/agent-environments/state-writes/tasks.md b/docs/specs/agent-environments/state-writes/tasks.md deleted file mode 100644 index c3d238ab67..0000000000 --- a/docs/specs/agent-environments/state-writes/tasks.md +++ /dev/null @@ -1,22 +0,0 @@ -# Tasks - -- [x] Record the write model, the gate and the serving contract. -- [x] Admit request bodies and add the plan types. -- [x] Explain created and updated entities with field rules. -- [x] Apply create, update, delete and document effects in one shared module. -- [x] Simulate the capture's timeline and decide each plan's verdict. -- [x] Leave entities below an unmodelled write unknown until a read shows them - again, and check writes such a write follows only on the members they - sent. -- [x] Serve gated write tools from the live store with deterministic values. -- [x] Answer recorded 400, 404 and 410 responses for missing entities. -- [x] Let lines that only page a whole collection back `membership: "all"`, - and answer argument-less list calls from them. -- [x] Count served write tools in exports and describe them in bundle READMEs. -- [x] Add domain, services, adapters and boundary coverage. -- [x] Document the write model and serving. -- [x] Run the view over every showcase capture and report per-capture verdicts. -- [x] Export one randomly chosen environment, run write tasks in the AgentEnv - framework and grade them from `data/get`. -- [x] Compare the served model with the live application on the same calls. -- [x] Run static, formatting, duplication, documentation and test gates. diff --git a/docs/specs/agent-environments/state-writes/verification.md b/docs/specs/agent-environments/state-writes/verification.md deleted file mode 100644 index dfcb16bc03..0000000000 --- a/docs/specs/agent-environments/state-writes/verification.md +++ /dev/null @@ -1,376 +0,0 @@ -# Verification - -Verified base: cbb7b613 (this branch before this file). Executed on macOS with -Node v22.23.1 (the repository pins 24.18.0 in `.nvmrc`, which was not -installed); the AgentEnv runs and the live comparison ran on a disposable Linux -VM. Every check below ran as written after the last source change. - -## 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` - and `npm run verify:test-discovery`: passed. -- `npm run jscpd`: 3.43% duplicated lines over 3538 files, under the 3.5% gate. -- `npx vitest run --project domain --project services`: 7407 passed, 5 - pre-existing skips. -- `npm run test:prepare`, then `npm run test:focused --` the new write MCP - boundary, the serve MCP, CLI and process boundaries, the export CLI - boundary, the analysis-view CLI and MCP boundaries, the compact input schema - boundary and the contract description tests: 10 files, 72 passed. -- `npm run mcp-catalog:check`: passed. - -New tests: `environmentStateWriteValues` (94), `environmentStateWriteExplain` -(101), `environmentStateWriteApply` (52), `environmentStateWrites` (16, the gate -through the view), `environmentStateWriteAnswer` (14, serving) and -`environmentServeWritesMcp` (1, the built CLI over MCP). The replay card pinned -by the serve MCP boundary changed with the response summaries tool descriptions -carry; its digest now matches the combined branch. - -## Real captures - -The `environment-state` view ran over the 50 showcase captures (45 HAR -inspections and 5 `capture_browser_scenario` captures), each within its budget in -8–110 ms. It served 33 write tools in 16 captures (11 creates, 12 updates, 10 -deletes). Of the other 150 state-changing tools, 102 name no state type or -document (most write to literal single-entity paths the manifest left -untemplated, or to collections whose reads are not state-backed), and 48 are -modelled but not served: - -- 15 unconfirmed (no later read checked them); -- 13 no-observation; -- 8 contradicted, for example a deleted Airbyte source and EspoCRM task still - readable, Immich and BookStack item reads showing fields the create - response lacked, and Sonarr's tag list ordering; -- 7 unexplained-change, such as BookStack's description_html and Paperless's - derived text colour; -- 4 side-effect, for example a Sonarr tag also listed by `/tag/detail`; -- 1 incomplete-entities: WordPress answers a delete with the post in its edit - context, which the reads never showed for seeded posts. - -| Capture | Served (create / update / delete) | Not served | -| ---------------- | --------------------------------- | ----------------------------------------------------------------------------------------------- | -| airbyte | 2 / 2 / 0 | create contradicted, delete contradicted, delete unconfirmed | -| baserow | none | no-state-target ×3 | -| bookstack | 0 / 0 / 1 | create contradicted, create side-effect, update unexplained-change | -| directus | none | no-state-target ×2 | -| espocrm | none | create unconfirmed, delete contradicted, update unexplained-change | -| ghost | none | no-state-target ×2 | -| gitea | 1 / 1 / 0 | no-state-target ×2 | -| grafana | none | create unconfirmed, no-state-target ×5 | -| grist | none | create no-observation, no-state-target ×5 | -| grocy | none | create no-observation, delete no-observation, update no-observation, no-state-target ×2 | -| healthchecks | none | create no-observation, delete no-observation, update no-observation, no-state-target ×2 | -| homebox | none | document no-observation, no-state-target ×3 | -| immich | 0 / 0 / 1 | create contradicted, update contradicted | -| jellyfin | none | no-state-target ×2 | -| keycloak | none | no-state-target ×1 | -| komga | none | create unconfirmed ×2, no-state-target ×4 | -| linkding | 2 / 2 / 2 | create unconfirmed, delete unconfirmed, update unconfirmed, no-state-target ×2 | -| listmonk | 1 / 1 / 1 | — | -| lychee | none | no-state-target ×4 | -| mailpit | none | document no-observation, no-state-target ×5 | -| mattermost | 1 / 1 / 1 | no-state-target ×3 | -| mealie | none | create no-observation, no-state-target ×2 | -| memos | none | no-state-target ×3 | -| metabase | 0 / 0 / 1 | create side-effect, update unexplained-change | -| miniflux | 0 / 1 / 0 | no-state-target ×3 | -| n8n | none | create unconfirmed, no-state-target ×6 | -| navidrome | none | create no-observation, no-state-target ×2 | -| netbox | 1 / 1 / 1 | — | -| nocodb | none | create no-observation, no-state-target ×4 | -| nomad | none | no-state-target ×4 | -| paperless | 0 / 0 / 1 | create unconfirmed, update unexplained-change, no-state-target ×3 | -| photoprism | 1 / 1 / 0 | delete unconfirmed | -| pinry | none | create unconfirmed, delete unconfirmed, update unexplained-change | -| pocketbase | none | no-state-target ×4 | -| redpanda-console | none | document no-observation, no-state-target ×5 | -| sentry | 1 / 0 / 0 | update unexplained-change, no-state-target ×3 | -| shlink | none | create unconfirmed, no-state-target ×1 | -| sonarr | 0 / 1 / 0 | create contradicted, create side-effect, update contradicted | -| tandoor | none | no-state-target ×4 | -| umami | 1 / 1 / 1 | — | -| vault | none | no-state-target ×7 | -| vikunja | none | no-state-target ×4 | -| wordpress | none | create side-effect, delete incomplete-entities, document unconfirmed, update unexplained-change | - -An in-process smoke derived each capture's served state and called every served -write tool once with a varied body: all 33 applied (status equal to the -recording), and every created or updated entity read back from the state; -deleted entities answered the recorded 400 or 404 where one was recorded. Eight -older published manifests no longer match the tool names the current view -derives, so their state is unavailable and they serve replay, as designed; -none of them has a served write tool. - -## End to end on a published environment - -Five published environments serve a create, an update and a delete (Linkding, -Listmonk, Mattermost, NetBox, Umami); `random.SystemRandom().choice` picked -NetBox (NetBoxEnv-REA, NetBox 4.7.3). - -- `rea environment-export` (packed from this branch) wrote the bundle; its - smoke task passed in AgentEnv framework 0.9.1334 with 42 served tools (39 - reads and `post_dcim_sites`, `patch_dcim_sites_by_id`, - `delete_dcim_sites_by_id`). -- Four write tasks, each graded by an `env_outcome_verifier` that reads the - environment's state through `/agentenv` `data/get` (not the agent's reply), - with the replay-qa agent over the Hugging Face router, one run per task and - model: - -| Task | gpt-oss-120b | GLM-5.3-Flash | Tool calls (gpt-oss) | -| ----------------------------------------------- | ------------ | ------------- | ------------------------------------------------------------ | -| Create a site in the Copper Valley region | 1.0 | 1.0 | get_dcim_regions, post_dcim_sites | -| Update a seeded site's facility and description | 1.0 | 1.0 | get_dcim_sites, patch_dcim_sites_by_id | -| Delete one seeded site and only it | 1.0 | 1.0 | get_dcim_sites, delete_dcim_sites_by_id | -| Create a site, then set its facility | 1.0 | 1.0 | get_dcim_regions, post_dcim_sites, patch_dcim_sites_by_id ×2 | - -- The bundle's 12 retrieval tasks (one per seeded object) passed 12/12 for both - models, as they did on the published replay bundle. - -## The served model against the live application - -The same NetBox 4.7.3 image ran on the VM, seeded by the capture's own seed -script (the same ids), and one scenario ran against both the live API and the -environment served from the capture. Only `created` and `last_updated` were -normalised; every other member had to be equal: - -| Step | Live | Environment | Equal | -| ----------------------------------------- | ---- | ----------- | ---------------------------- | -| List sites | 200 | 200 | yes | -| Create Tide Gauge Annex (id 5) | 201 | 201 | yes | -| Read it | 200 | 200 | yes | -| List after the create (sorted by name) | 200 | 200 | yes | -| Patch its description and facility | 200 | 200 | yes | -| Read after the patch | 200 | 200 | yes | -| Create Granite Spur (id 6) | 201 | 201 | yes | -| Patch a seeded site | 200 | 200 | yes | -| Delete Tide Gauge Annex | 204 | 204 | yes | -| Read the deleted site | 404 | 404 | yes | -| Create Ledger Point (id 7, not reusing 5) | 201 | 201 | yes | -| Delete a seeded site with devices | 409 | 204 | no | -| Final list | 200 | 200 | no (follows from the delete) | - -11 of 13 steps were equal. The difference is NetBox's referential protection: -it refuses to delete a site that devices reference, while the environment's -delete removes the entity alone. The capture only deleted a scratch site with -no dependents, so the gate could not see the rule; it is listed under what is -not modelled. - -## Not covered - -- A run of the hosted `real-agentenv` lane in CI (the AgentEnv runs here used - the published framework release on a VM). -- Document writes on a real capture: the four modelled ones are unserved. -- Collections tied to a create's own collection on a real capture, and UUID - or token identities through an AgentEnv run (both are covered by tests). -- Agent token usage and cost. - -## After merging the base branches and main - -The branch then merged the serving branch at 5a61853a, the coverage branch at -b4b7ebc7 (their review fixes) and main at edbd291a, then main at 17f581ff -(the analysis-view tool description string, which main changes often). The gates above ran again -and passed: `npm run jscpd` 3.44% over 3579 files; domain and services 7442 -passed with 5 pre-existing skips; the focused boundary set 72 passed. The -write verdicts over the 50 captures were unchanged plan by plan, and the -in-process smoke again applied all 33 served write tools. The AgentEnv runs -and the live comparison above ran on cbb7b613, before these merges. -After the second main merge: `npm run check:fast`, `npm run format:check`, -`npm run docs:check` and `npm run mcp-catalog:check` passed; the contracts, -analysis-view and environment tests 857 passed with 3 pre-existing skips; the -analysis-view and environment MCP and CLI boundaries 53 passed. - -## After the review round - -The branch then merged the serving branch at c00fde41, the coverage branch at -f6c756aa and main at 1629266e, and took the review fixes (82556cd5, 138ea4b1, -6d21b62e). The coverage branch quotes field names in response summaries, so the -replay card pinned by the serve MCP boundary is now 12,818 bytes; removing -those quotes gives back the previous 12,618-byte digest exactly. The gates ran -again and passed: `npm run check:fast`, `npm run format:check`, `npx knip`, -`npm run scan:todos`, `npm run docs:check`, `npm run verify:test-discovery`, -`npm run verify:module-boundaries` and `npm run mcp-catalog:check`; -`npm run jscpd` 3.47% over 3601 files; domain and services 7463 passed with 5 -pre-existing skips; the focused boundary set 75 passed; conformance 279 -passed. The gate is stricter, but the write verdicts over the 50 captures were -unchanged plan by plan, and the in-process smoke again applied all 33 served -write tools. The AgentEnv runs and the live comparison above ran on cbb7b613, -before these merges and fixes. - -A second review round then made the gate and serving agree in five more places -(reads matched to checked lines as serving matches calls, increments and slugs -held for every call, insert rules still learned after an item read, the -document body check in the gate, and decoded parent path values). Each new test -fails on the previous head and passes here. The same gates passed again -(domain and services 7468 passed with 5 pre-existing skips, the focused -boundary set 75, conformance 279, `jscpd` 3.47%), the write verdicts over the 50 -captures were again unchanged plan by plan, and the smoke applied all 33 served -write tools. - -A third round kept a checked line's path spelling (replay prefers a verbatim -one, so two spellings of one parent stay separate lines) and compared a later -slug rule with the values earlier calls recorded rather than only their member -names; both new tests fail on the previous head. A fourth round chose a read's -line as replay does, so a read spelled plainly is checked against the encoded -line that answers it, and its list against that line's collection; its test -fails on the previous head. - -A review of the fidelity branch built on this one found four more places: a -document write at another path is now unmodelled in the gate, a create picks -the collection the call spells verbatim, a missing entity is answered with a -recorded 2xx `null` the gate accepted as an absence, and `data/add` refuses a -document whose `data/get` form would exceed the intake limit. Each new test -fails on the previous head. The gates passed again (domain and services 7475 -with 5 pre-existing skips, boundaries 75, conformance, `jscpd` 3.46%), the -verdicts over the 50 captures were unchanged plan by plan, and the smoke -applied all 33 served write tools. - -A sixth round, after merging the serving and coverage branches and main -335c042d, settled five more findings: a read whose usable body no longer holds -the entity or list fails its check, an entity lacking a field its view always -carried confirms nothing, a write a later write replaced is not confirmed by -reads of the replacement, sequences never reuse a value the state started -with, and a collection keeps its spelling after it empties. Each new test fails -on the previous head. Over the 50 captures one capture's verdicts change: -Linkding's bundle create and patch, confirmed only by a list read after the -same bundle was deleted, are now unconfirmed, so 31 write tools are served (10 -creates, 11 updates, 10 deletes) and the in-process smoke applies all 31. The -gates passed again (domain and services, boundaries, conformance and `jscpd`). - -A seventh round settled two more findings. An update keeps its confirmation -when a later write overwrites only part of what it changed: a derived change, -such as an incremented version, counts as part of the update's effect, and a -later increment adds to the field rather than replacing it. A reset or load -forgets the collection spellings of the state it replaced. Both new tests fail -on the previous head. The verdicts over the 50 captures are unchanged plan by -plan, the in-process smoke applies all 31 served write tools, and the gates -passed again. - -An eighth round settled three more. A later write erases the fields of an -earlier effect it overwrites, so two writes that together overwrite all of an -update's changes leave it nothing to be confirmed by. A recorded outcome erases -what earlier writes changed on its entity. A load keeps the Evidence's own -collection spellings, so a create in a collection the loaded state does not -hold keeps its recorded spelling. Each new test fails on the previous head. The -verdicts over the 50 captures are unchanged plan by plan, the smoke applies all -31 served write tools, and the gates passed again. - -A ninth round made a create prefer a collection the state holds over an equally -fitting spelling known only from the Evidence, so a create after a load lands in -the loaded collection and reads back. Its test fails on the previous head; the -verdicts and the smoke are unchanged and the gates passed again. - -A tenth round settled six findings Greptile raised on the list-lines branch -against this branch's code: - -- a read with no query on a whole list is checked on the paging line serving - answers it from, and a line whose query repeats a name is never checked; -- a read made while a write to its targets was still running checks nothing; -- a later call that stores a member otherwise than the plan refuses the plan; -- a create keeps the spelling of a collection the capture listed empty; -- a wide array no longer overflows the stack while checking path-dependent - values; -- the guide counts served write tools among the catalog's. - -Each new test fails on the previous head. The verdicts over the 50 captures -are unchanged plan by plan, the smoke applies all 31 served write tools, and -the gates passed again. - -An eleventh round settled six more findings, five raised on this branch and one on the fidelity branch: - -- a passing read confirms only the writes it shows something of; -- an item read names its entity as serving does, percent-decoded spellings included; -- a read a write's effect was learned from still contradicts the other writes; -- a line repeating a query name with one value stays checkable; -- document writes join the effect tracking, so a replacement overwrites an earlier merge; -- a call naming a page that the collection has outgrown answers from its recording (`page-exceeded`), and the gate does not check such reads. - -Each new test fails on the previous head. The verdicts over the 50 captures are unchanged plan by plan, the smoke -applies all 31 served write tools, and the gates passed again. - -A twelfth round settled four findings Greptile raised on the list-lines branch against this branch's code: - -- a create that answers with its id alone is observed only through a read of that id; -- a later call that is the first to send the path's id in its body adds the identity member to the plan; -- the copy search walks a request body with an index, so a wide body no longer takes quadratic time (500,000 zeros: 63 s - before, 74 ms after); -- the sent values of fixed members a plan keeps are counted against the view's allowance. - -Each new test fails on the previous head. The verdicts over the 50 captures are unchanged plan by plan, the smoke -applies all 31 served write tools, and the gates passed again. - -A thirteenth round settled seven findings Greptile raised on this branch, the fidelity branch and the list-lines branch: - -- a passing read that shows nothing of a write leaves it for a later check, instead of clearing it; -- a read begun while a write to an unknown entity still ran neither checks nor shows the entity again; -- a later create whose sequence fields do not follow the learned sequence refuses the plan; -- a document replacement below the root overwrites only what it replaced; -- a built document plan writes later calls at its own object, even one sharing no member with the document; -- an update or delete finds its entity as an item read does, percent-decoded spellings included; -- a `_start`–`_end` range bounds a page as `limit` does, in serving and in the gate. - -Each new test fails on the previous head. The verdicts over the 50 captures are unchanged plan by plan, the smoke -applies all 31 served write tools, and the gates passed again. - -A fourteenth round settled two findings Greptile raised on the list-queries branch against this branch's code: - -- the type's identity field never becomes a constant: an update whose id member the application ignored no longer - writes the exemplar's id into the entity another call names; -- a page size of zero bounds nothing, so a whole line recorded with `limit=0` answers from the state. - -Both tests fail on the previous head. The verdicts over the 50 captures are unchanged plan by plan, the smoke applies -all 31 served write tools, and the gates passed again. - -A fifteenth round settled nine findings Greptile raised on this branch, the fidelity branch and the list-lines branch, -five of them on the previous rounds' own changes: - -- an entity field whose name looks like a pointer is matched by name; only a document's pointers cover the members - under them; -- a failed read contradicts each exercised write no unmodelled write came after, rather than skipping all of them - when the oldest pending write came before one; -- an item read, update or delete names its entity as serving does, decoding the id once, so `book%2531` no longer - reaches `book1`; -- a plan whose calls use a member both as the identity and as a fixed member, or fix it at different values, is - refused; -- a size of zero bounds nothing only on a line whose recording listed items under it; -- an update whose observation drops a field the entity held is refused; -- a later create whose clock takes another format, or whose unique value is not a UUID, is refused; -- a derived state `data/get` would write past 32 MiB is not served. - -Each new test fails on the previous head. The verdicts over the 50 captures are unchanged plan by plan, the smoke -applies all 31 served write tools, and the gates passed again. - -A sixteenth round settled four findings Greptile raised on the fifteenth round's changes, here and on the fidelity, -list-lines and list-queries branches: - -- a size of zero is no bound only by itself: a range or another size on the same line still bounds the page; -- an update is refused for a dropped field only when a later read shows it dropped, since a write's own response may - leave fields out; -- interference is weighed against a tool's latest call on the read's entity or collection, not its latest call - anywhere. - -Each new test fails on the previous head. The verdicts over the 50 captures are unchanged plan by plan, the smoke -applies all 31 served write tools, and the gates passed again. - -A seventeenth round settled two more findings Greptile raised on the list-queries branch against this branch's -interference rule: an unmodelled write counts against a tool when it followed the tool's call on any target the read -covers, so a later call on another entity does not hide it; and a failed item read contradicts the writes no -unmodelled write followed, checking only the others on their members. Both tests fail on the previous head. The -verdicts over the 50 captures are unchanged plan by plan, the smoke applies all 31 served write tools, and the gates -passed again. A follow-up weighs interference only on targets where the tool's effect survives, so a call -whose effect a later write overwrote no longer excuses a later mismatch; its test fails on the previous head. - -## Collection-history accounting check - -On 2026-10-22, Node 24.18.0, I compared the source before the write-history -change (`cfb42ddde`) with the bounded-history implementation. Each operation -inserted an entity at a new collection path with a 128-character repeated -suffix and immediately deleted it. Across five fresh Vitest worker processes, -the median for 1,000 completed cycles was 14.57 ms wall / 23,867 us CPU before -and 9.98 ms / 16,914 us after. The process RSS samples were 381.1–387.9 MiB -before and 380.9–387.6 MiB after. This fixture benchmark measures one matched -completed trace, not a representative user task or process-family peak memory. -The values include Vitest and V8 and are noisy; they do not establish a memory -bound. The 1 MiB policy is a deterministic accounting allowance for -additional identifier history, set to 1/32 of the separate 32 MiB state-intake -ceiling; it is not derived from RSS samples and does not bound total store or -process memory. diff --git a/docs/specs/agent-environments/view-clock-spelling/plan.md b/docs/specs/agent-environments/view-clock-spelling/plan.md deleted file mode 100644 index ef10bf2263..0000000000 --- a/docs/specs/agent-environments/view-clock-spelling/plan.md +++ /dev/null @@ -1,8 +0,0 @@ -# Implementation plan - -1. **Re-spelling.** A values helper spells a clock in another format: its wall clock in the format's zone, with its own - fraction digits padded to the format's width. -2. **Learning.** The gate notes, per view, the spelling of each clock field that differs from the stored value, while it - checks the view's recordings; the view gains `clock_formats` when any field always differs. -3. **Rendering.** Entity rendering spells a stored value in the view's spelling when the view has no value of its own. -4. **Schema, tests and docs.** The view schema, gate, serving and unit tests, and the state-view docs. diff --git a/docs/specs/agent-environments/view-clock-spelling/spec.md b/docs/specs/agent-environments/view-clock-spelling/spec.md deleted file mode 100644 index c64970aea2..0000000000 --- a/docs/specs/agent-environments/view-clock-spelling/spec.md +++ /dev/null @@ -1,37 +0,0 @@ -# Spell a written clock as each view spells it - -Issue: https://github.com/morluto/rea/issues/4933 - -## Outcome - -Some applications spell one instant differently by view. Mealie's recipe reads end timestamps in `Z` -(`2026-10-21T17:06:13.710410Z`) and its recipe list in `+00:00`. The state keeps each view's own values for the entities -it recorded, so those render as recorded, but a created or updated entity has only the values the write showed. A list -read after a create therefore rendered the new recipe's clocks in the item spelling. The write gate saw a contradiction -and left the create unserved, and serving would have listed the wrong spelling. - -## Behaviour - -- **Learning.** While checking that an item or list view reproduces its recordings, the gate compares each recorded - object's clock fields with the entity's stored values. A field whose recorded value always names the same instant in - one other spelling gets that spelling in the view's optional `clock_formats`. A field the view also shows as stored, or - spells two ways, counting values that name another instant, gets none. A spelling has at most nine fraction digits. - Instant equality includes all recorded fraction digits, not just milliseconds; offset changes and trailing zeros - alone do not change the instant. The clock parser owns this precision and rendering reuses its parsed facts. -- **Bounds.** Each field retains at most one matching and one other-instant spelling, or a permanent mixed marker - for either category. Rejected formats do not accumulate. The existing projection budget covers the learner's maps, - keys, formats and returned view members before retention; exhaustion keeps the existing typed resource refusal. - Preliminary list-query probes do not learn or retain clock state; only the final admitted view does. -- **Rendering.** A stored value the view never recorded, such as one a write made, is rendered in the view's spelling: - its wall clock in the view's zone, under the view's separator, with its own fraction digits padded with zeros to the - view's width. No digit is dropped, so a width learned from whole seconds does not cut a later value's fraction. An - epoch spelling is computed from the instant. - -The gate and serving render through the same function, so a served create lists with the list's spelling and reads back -with the item's. `data/get` returns the stored values. - -## Acceptance - -- The pilot recording's Mealie create is served on the list-query stack. -- Over the 50 published captures, one view learns a spelling (Mealie's recipe list), and every write verdict is unchanged. -- Every served write tool of the 50 captures still applies. diff --git a/docs/specs/agent-environments/view-clock-spelling/tasks.md b/docs/specs/agent-environments/view-clock-spelling/tasks.md deleted file mode 100644 index 193cd291c3..0000000000 --- a/docs/specs/agent-environments/view-clock-spelling/tasks.md +++ /dev/null @@ -1,9 +0,0 @@ -# Tasks - -- [x] Re-spell a clock in another format, keeping digits past milliseconds. -- [x] Learn each view's clock spellings while checking its recordings. -- [x] Render stored values a view never recorded in its spelling. -- [x] Add gate, serving and unit tests, failing on the previous head. -- [x] Document the view member. -- [x] Measure the pilot recordings, the 50 published captures and the served smoke. -- [x] Run static, formatting, duplication, documentation and test gates. diff --git a/docs/specs/agent-environments/view-clock-spelling/verification.md b/docs/specs/agent-environments/view-clock-spelling/verification.md deleted file mode 100644 index d2c86695aa..0000000000 --- a/docs/specs/agent-environments/view-clock-spelling/verification.md +++ /dev/null @@ -1,44 +0,0 @@ -# Verification - -Executed on macOS with Node v22.23.1 on this branch with the write-plan branch's head `45a5c8b9` merged in. The pilot recordings -were made against live applications on six disposable Linux VMs, each restored from a snapshot first. - -## Gates - -- `npm run build:cached`, `npm run check:fast` (typecheck and lint, no warnings in the changed files), - `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.43% duplicated lines over 3753 files. -- `npx vitest run --project domain --project services`: 7755 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, 79 passed. - -## Tests - -- Gate: a list that spells clocks `+00:00` where item reads spell `Z` learns both spellings, the item view learns none, - and a create read back by both is served; a create whose clock has a fraction is served where the list's spelling was - learned from whole seconds; a list that spells a field both ways, at the stored instant or another, learns nothing. -- Serving: a served create lists with the list's spelling and reads back with the item's. -- Unit: re-spelling keeps a value's fraction digits at any offset and across a date change, pads them to the format's - width without dropping any, and formats an epoch spelling from the instant; an epoch value's milliseconds become - fraction digits. -- Schema: a view clock spelling wider than nine fraction digits is refused. -- The gate and serving tests fail on `264ce410`, the write-plan head they were written on. - -## Pilot recordings - -Mealie's recipe reads spell clocks `Z` and its recipe list `+00:00`. On this branch alone the list line the create is -read back on keeps its recorded members, so the create stays unserved; per-line list membership and list queries -(#5787, #5800) answer that line from the state. Built on the list-query stack (#5800 with #5699 merged): - -- Mealie's `post_recipes` goes from `contradicted` to served, and Mealie's held-out sessions agree on 298 of 310 steps, - up from 294. -- With the assigned-values branch (#6136) too, all three Mealie write tools are served, at 302 of 310. -- The other five applications are unchanged. - -## Published captures - -- Over the 50 published captures, one view learns a spelling: Mealie's recipe list (`dateUpdated`, `createdAt`, - `updatedAt`). Every write verdict is unchanged. -- The served smoke applies all 31 served write tools. diff --git a/docs/specs/agent-environments/write-assigned-values/plan.md b/docs/specs/agent-environments/write-assigned-values/plan.md deleted file mode 100644 index ed4e862590..0000000000 --- a/docs/specs/agent-environments/write-assigned-values/plan.md +++ /dev/null @@ -1,9 +0,0 @@ -# Implementation plan - -1. **Explanation.** Creates accept members a whole-member copy stores and template text around copied values. - Updates rule a fresh UUID `unique`, accepting a sent member so replaced, and child rows with only renewed UUIDs - `renewed`; the update reads the type's other entities to tell a fresh UUID from a reference. -2. **Values.** Helpers find the UUIDs a value renewed and renew the UUIDs of a value. -3. **Apply and serve.** Updates take `unique` and `renewed` from the generator; serving renews the current entity's - UUIDs. -4. **Schema, tests and docs.** The view's rule schema, unit, gate and serving tests, and the write specs. diff --git a/docs/specs/agent-environments/write-assigned-values/spec.md b/docs/specs/agent-environments/write-assigned-values/spec.md deleted file mode 100644 index 5bed7cec40..0000000000 --- a/docs/specs/agent-environments/write-assigned-values/spec.md +++ /dev/null @@ -1,52 +0,0 @@ -# Serve writes whose values the application renames or regenerates - -Issue: https://github.com/morluto/rea/issues/4933 - -## Outcome - -Recordings made to show each write's effect, with every write read back at once and two scratch objects per tool, -still left writes unserved where the application stored a value in a way the write rules did not explain: - -- a create's member stored under another name: Shlink stores `customSlug` as `shortCode`, and its `shortUrl` ends in - it, so every slug but the recorded one was refused; -- an update that gives a field a fresh UUID each time: n8n's `versionId`, which the client sends back with the - version it read; -- an update that rewrites child rows with new UUIDs: Mealie gives a recipe's instructions new ids on every update. - -These writes are now explained, and served where every recorded call agrees with the explanation. - -## Rules - -- **Creates.** A member copied whole into a field of another name, and stored under none of its own, is accepted with - any value of that field's JSON type. A string that contains a copied value as a delimited token is a template of - the copying field and is rebuilt around the new value; the copied value has the copy rule's 8 characters at least. - Echoed values, and copies of them, make no templates, since an echoed name may recur in unrelated text. - Each text containing a copied value must rebuild that copy; rebuilding it in one text does not make occurrences - in other templates safe. Otherwise the member remains fixed to its recorded value. -- **Updates.** - - `unique`: a field that held a UUID and now holds another, which the call did not send (in any letter case) and - no other entity of the type holds. A sent member replaced this way is accepted with any value. - A value shared with another output field is not independent generation: scalar and nested generators cannot - reproduce that relation, so the update remains unexplained rather than serving disconnected UUIDs. - - `renewed`: an array or object whose only changes are UUIDs replaced by ones neither it nor another entity of the - type held, at the pointers the rule names (`*` for any array index): every UUID there is new, each old UUID by a - single new one, and UUIDs elsewhere are kept. A lone UUID is never renewed: it is either `unique` or unexplained. - Renewal identity is canonical and case-insensitive, including repeated mixed-case occurrences within one field; - source spelling remains in the retained entity and is preserved by serving. Fresh values must not be sent in the - request, owned by an earlier or another entity, or shared with non-renewed output fields. Such relations remain - unexplained until a generation rule can reproduce them. Nested renewed fields may still share one fresh replacement. -- **Serving.** A `unique` field gets a UUID derived as for creates. A `renewed` field keeps the entity's current - value with each UUID at the rule's pointers replaced by one seeded by the call, the same replacement wherever the - call renews that UUID; an entity without the field stays without it. - -The gate takes the recorded values for both, as for other generated fields. A later call must rule a field the same -way, and no recorded call may keep a `unique` or `renewed` field, since serving changes it on every call. - -## Acceptance - -- The pilot recordings' Shlink create and n8n update are served. Mealie's update stays unserved: one recorded call keeps - the ingredient ids the gate's copy of the recipe shows renewed, and no other verdict changes. -- The 50 published captures keep every verdict; only Shlink's unserved create plan changes, accepting - `customSlug` and templating `shortUrl`. -- Every served write tool of the 50 captures still applies. -- A unit test shows a UUID another entity holds is not `unique`, and a child row whose text changed is not `renewed`. diff --git a/docs/specs/agent-environments/write-assigned-values/tasks.md b/docs/specs/agent-environments/write-assigned-values/tasks.md deleted file mode 100644 index 0a8eada536..0000000000 --- a/docs/specs/agent-environments/write-assigned-values/tasks.md +++ /dev/null @@ -1,9 +0,0 @@ -# Tasks - -- [x] Accept a create member stored under another name, and template text around copied values. -- [x] Rule fresh UUIDs on update as `unique`, and rewritten child rows as `renewed`. -- [x] Apply and serve both rules. -- [x] Add unit, gate and serving tests, each failing on the previous head. -- [x] Document the rules. -- [x] Measure the pilot recordings, the 50 published captures and the served smoke. -- [x] Run static, formatting, duplication, documentation and test gates. diff --git a/docs/specs/agent-environments/write-assigned-values/verification.md b/docs/specs/agent-environments/write-assigned-values/verification.md deleted file mode 100644 index 06994cfcc0..0000000000 --- a/docs/specs/agent-environments/write-assigned-values/verification.md +++ /dev/null @@ -1,60 +0,0 @@ -# Verification - -Executed on macOS with Node v22.23.1 on this branch with the write-plan branch's head `45a5c8b9` merged in. The pilot recordings -were made against live applications on six disposable Linux VMs, each restored from a snapshot first. - -## Gates - -- `npm run build:cached`, `npm run check:fast` (typecheck and lint, no warnings in the changed files), - `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.43% duplicated lines over 3754 files. -- `npx vitest run --project domain --project services`: 7769 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, 79 passed. - -## Tests - -- Gate: a renamed book renewing a sent `version_id` and its chapters' ids is served with `unique` and `renewed` - rules; two creates sending a `handle` stored as `code` and embedded in `link` are served with `copy` and - `template` rules. -- Serving: each served update gets a fresh version and new chapter ids that keep their titles; a served create with - a new handle stores it as the code and rebuilds the link. -- Unit: the explanation, including a UUID another entity holds (not `unique`), a child row whose text changed (not - `renewed`), and a member copied only in part (still fixed); the renewal helpers; applying both update rules. -- The four gate and serving tests fail on `43d98ea9`. -- Review round (on `a477b21d`, where each fails): serving renews only the UUIDs at the pointers the recording renewed, - keeps an author id each chapter names, gives one UUID the same replacement in every renewed field, and gives no rows - to an entity that holds none; a recorded call that keeps a renewed value refuses the plan; a renewal that keeps, - moves or borrows a UUID is not one; a copied member is type-checked against its stored field; a member stored - otherwise under its own name is not accepted; an echoed value's copy is no template source; a sent UUID stored in - another letter case is not a generated one. - -## Pilot recordings - -Each application was reset, then recorded with the capture's reads and, per write target, two scratch objects whose -every write was read back at once (item and list), deletes read back as 404. - -| Application | Write | Before | After | -| ----------- | ------------------------------------- | -------------------- | -------------------- | -| Shlink | `post_rest_short_urls` | `unexplained-change` | served | -| n8n | `patch_rest_workflows_by_workflow_id` | `unexplained-change` | served | -| Mealie | `patch_recipes_by_recipe_id` | `unexplained-change` | `unexplained-change` | - -No other verdict of the six recordings changed. Mealie's update was served by an earlier version of this branch with -`recipeIngredient` renewed. Each of its two recorded updates keeps the ingredient ids; the gate's copy of the second -recipe held the first recipe's ids, because the read that showed it was the create's observation and was not adopted. -Each renewed field now needs every recorded call to renew it, so the plan is refused rather than served regenerating -ingredient ids. Built on the list-query stack (#5800 with #5699 merged), the held-out sessions agreed on two more -steps each for n8n (127 to 129 of 143) and Shlink (126 to 128 of 137) with the earlier version; Komga, NetBox and -Sentry were unchanged. - -## Published captures - -- Over the 50 published captures, every write verdict is unchanged: 31 served write tools. The only plan that - changes is Shlink's unserved create, which now accepts `customSlug` and templates `shortUrl`. -- An earlier version also made echoed values template sources. It templated Grafana's folder `url` around `uid` - (the URL also holds a slug of the title) and BookStack's page HTML around its markdown. Echoed values are no - longer sources. -- The served smoke applies all 31 served write tools, as on `43d98ea9`. diff --git a/docs/specs/agent-environments/write-call-values/plan.md b/docs/specs/agent-environments/write-call-values/plan.md deleted file mode 100644 index b0a4da6b4d..0000000000 --- a/docs/specs/agent-environments/write-call-values/plan.md +++ /dev/null @@ -1,13 +0,0 @@ -# Implementation plan - -1. **Query values.** Widen the query property schema and spell numbers and booleans as JSON text where a call enters - serving. -2. **Sequence start.** `start` on sequence rules and their schema; the exemplar records integer fields above every held - value; serving and replay floor the next value at `start`. -3. **Later rules.** Merging a later create adopts its `composed`, `template` or started `sequence` rule when it spells - the exemplar's value. -4. **Made objects.** The `made-object` rule and schema; its explanation, merge, later-call check, counts taken, serving - and own members. -5. **Bulk link.** `respondedIds` reads the object of a one-element array member; `anyLinkedSource` lets a linked - create take any path values its plan stores in fields, in replay and serving. -6. **Skill, tests and docs.** diff --git a/docs/specs/agent-environments/write-call-values/spec.md b/docs/specs/agent-environments/write-call-values/spec.md deleted file mode 100644 index 7ff8f1b88d..0000000000 --- a/docs/specs/agent-environments/write-call-values/spec.md +++ /dev/null @@ -1,46 +0,0 @@ -# Serve the calls agents make and the values applications count - -Issue: https://github.com/morluto/rea/issues/4933 - -## Outcome - -Eval agents' trajectories on rebuilt environments, and the write plans of the recordings they ran on, showed three -gaps REA could close: - -- **Query values.** Served tools typed each query parameter as a string or an array of strings, while agents send page - sizes and flags as JSON numbers and booleans (`maxSize: 50`, `withItems: true`). The MCP server refused those calls - before REA saw them: 63 of 418 stored eval runs hit it, in EspoCRM, Homebox and PhotoPrism, and 18 never got the tool - to answer. -- **Counted and made values.** Vikunja numbers a project's tasks past those deleted earlier, so a created task's - `index` is not one past what the state holds; its `identifier` spells that index; and each created task gets a - `subscription` object the application makes with it. A second create disagreed with the first on all three, so - task creates were withheld. -- **Bulk creates.** Vikunja's UI creates a task through `POST /projects/{id}/tasks/bulk`, sending and answering the - task wrapped in `tasks: [ … ]`. The answer's id sat inside the array, so REA linked the call to no type. - -The diagnosis also found that a recorded update stores only what it sent (EspoCRM's updates never changed an email -address), and that an object known only from a list that leaves out fields its own read shows can be neither read by -id nor updated. Both are recording gaps the skill now addresses. - -## Behaviour - -- **Query values.** A query parameter accepts a number or boolean besides a string or an array of strings, and serving - sends it as its JSON text. -- **Sequences from a start.** A field the first create showed above every value its type held, which a later create - shows one past the first's, is a `sequence` with that `start`: serving never goes below it. -- **Rules that spell the first create.** A field the plan kept as shown takes a later create's rule when that rule also - spells the first create's value: a `composed` or `template` string, or the `sequence` above. -- **Made objects.** A created object no other entity of the type holds otherwise, with a member the request stamped, is - a `made-object`: stamped members take the write's clock, members holding the entity's identity take its id, counts - go one past the largest value held objects show from a `start`, and other members stay as recorded. -- **Linked bulk creates.** A create's answer names the id of the one object a one-element array member holds. A linked - create accepts any path values when it creates into its type's own collection, whose path has no parameters, and - stores each path value in a field, as a Vikunja task stores its project: no path value changes where it creates. -- **Skill.** Recordings read each listed object by id, up to ten per collection, before writing. - -Plans and views that need none of this are unchanged. - -## Acceptance - -- No write tool of the 130 recorded captures goes from served to withheld. -- Rebuilt from the same recordings, the branch passes at least the write tasks #7274 passes. diff --git a/docs/specs/agent-environments/write-call-values/tasks.md b/docs/specs/agent-environments/write-call-values/tasks.md deleted file mode 100644 index 6ceed72189..0000000000 --- a/docs/specs/agent-environments/write-call-values/tasks.md +++ /dev/null @@ -1,13 +0,0 @@ -# Tasks - -- [x] Accept numbers and booleans for query parameters. -- [x] Start a sequence from the value its first create took. -- [x] Adopt a later create's rule that spells the first create's value. -- [x] Learn, check and serve objects made with an entity. -- [x] Link creates whose answer wraps the entity in a one-element array, and let a linked create take path values - it stores. -- [x] Ask recordings to read each listed object by id. -- [x] Add view, serving, MCP boundary and unit tests. -- [x] Document the rules and the query argument types. -- [x] Measure the recorded captures and served write tasks. -- [x] Run static, formatting, documentation and test gates. diff --git a/docs/specs/agent-environments/write-call-values/verification.md b/docs/specs/agent-environments/write-call-values/verification.md deleted file mode 100644 index a2aad7b67f..0000000000 --- a/docs/specs/agent-environments/write-call-values/verification.md +++ /dev/null @@ -1,88 +0,0 @@ -# Verification - -Executed on macOS with Node v24.22.1 on this branch merged with #7274 at `45832406` (main `8706068b`), and on Ubuntu -24.04 VMs for the task runs. - -## Diagnosis - -The 418 eval runs stored on the comparison VMs, with their agent trajectories: - -- 63 runs had a call refused before REA saw it because a query value came as a JSON number or boolean (`maxSize`, - `pageSize`, `withItems`, `isLocation`, PhotoPrism's `count`, `offset`, `merged`, `public`), and in 18 the agent never - got that tool to answer. -- EspoCRM's contact update fails in every run: the served update accepts only the members recorded updates stored - (`description`, `name`, `lastName`), and a seeded contact known only from lists can be neither read by id nor - answered for. On #7274, gpt-oss passes the task by creating a replacement contact and deleting the original. -- Vikunja's task creates were withheld by an unexplained `index`, `identifier` and `subscription` (main's recording), - or had no state target, being bulk creates (four recordings). - -## Gates - -- `npm run -s check:fast`, `format:check`, `scan:todos`, `docs:check`, `verify:test-discovery`, `mcp-catalog:check` and - `jscpd`: passed. `npx knip` reports `staticFileUrlPath` and `ObjcClassImportBindingCoverage`, which main `8706068b` - added and this branch does not touch. -- `npx vitest run --project domain --project services`: 11,430 passed, 6 skipped. `--project adapters`: 7,437 passed, 19 - skipped, 3 failed: the Inspector cancellation test and two AppKit asset-catalog tests, which fail the same way on - #7274 at `e29e9c74`. -- `npm run -s test:focused --` the environment build, export and serve CLI boundaries, the analysis-view CLI and MCP - boundaries and the environment serve MCP boundary: passed. `outputSchemaProfile`, `toolSchemaValidity`, - `mcpSchemaValidation` and `outputSchemaSemanticConstraints`: passed; the compact catalog stays under its frame. - -## Tests - -- View: two task creates at a project path learn `index` as a `sequence` from 15, `identifier` as a `template` around - it and `subscription` as a `made-object` whose `id` counts from 21 and whose `entity_id` holds the task's own id; one - create alone keeps `index` as recorded; a bulk create whose body and answer wrap the task in `tasks` links to the - tasks type and is served; an object with no member the request stamped makes no rule. -- Serving: created tasks take index 15 then 16, `#15` then `#16`, and a subscription numbered 22 holding the second - task's id; a bulk create answers in its envelope, and one into another project stores that project. -- Query values: a number or boolean query value is spelled as its JSON text, and a list paged by a number answers as - with the same text; through the MCP server, `maxSize: 2` and `withItems: true` replay their recording exactly. The - served card of the `renamed` fixture grows 637 bytes, 91 for each of its seven query parameters. -- The seven behaviour tests fail on #7274 at `4ede1305`. - -## Write plans and views over recorded captures - -The 130 captures #7274 measured, built by #7274 at `45832406` and by this branch: 615 plans, 332 served and 333. - -- No write goes from served to withheld. Newly served: Vikunja's bulk task create in #7260's final recording. -- Vikunja's task create in main's recording is now explained, by its counter, template and made subscription, but - main's `unknown-clock` withholds it in both builds, as that capture has no clock anchor. Measured on #7274 at - `4ede1305`, before that rule, it was served too (339 to 341). -- Six plans that stay withheld explain more: Homebox entity creates learn `assetId` as a counter from 5 in four - recordings, and Vikunja task creates in two. -- In #7260's two Vikunja recordings whose UI writes lost their bodies, the bulk create now counts as a task write, so - the scratch task it made is no longer held as seeded (35 to 34 and 36 to 35 initial entities), a read tool that read - only that task replays its recordings, and later reads check fewer lines. Every other view is unchanged. - -## The same recordings, built by #7274 and by this branch - -Claude Code (`claude-sonnet-5-5`) recordings from earlier rounds, rebuilt by #7274 at `e839af3f` (its last two merges -change no census) and by this branch, their write tasks run with `fireworks_ai/gpt-oss-120b` then -`fireworks_ai/glm-5p3-flash`, each checked from the environment's state: - -| Recording | Write tasks | #7274 | This branch | -| ---------------------------------------------------------- | ----------- | ----------- | ----------- | -| Vikunja: #7260 final (bulk creates) | 3 + 2 | 1/5 1/5 | 2/5 2/5 | -| Vikunja: main (two), saved-values (two), #7260 (first two) | 6 × (3 + 2) | 6/30 6/30 | 6/30 6/30 | -| EspoCRM: main, #7260 (three), saved-values | 5 × 3 | 15/15 10/15 | 15/15 10/15 | -| Homebox: main, #7260 final, saved-values (two) | 4 × 2 | 6/8 6/8 | 6/8 6/8 | -| Total | 58 | 28/58 23/58 | 29/58 24/58 | - -No recording passes fewer tasks with this branch. - -- **Vikunja, bulk creates:** the create task passes with both models. The served bulk create numbers the task and makes - its subscription, and creates into Lighthouse Rota though the recording created into the inbox. -- **Refused calls:** agents' calls were refused at input validation 34 times with #7274 (30 in Vikunja) and once with - this branch, and agents made 286 tool calls against 317. -- **Main's `unknown-clock`** withholds Vikunja's task create and Homebox's tag create in main's recordings in both - builds, so those tasks fail in both. Rebuilt by #7274 at `4ede1305`, before that rule, this branch without the - linked-path change made main's Vikunja create task pass with both models (1/3 to 2/3) and changed no other result - among the recordings that finished. - -## Not verified - -- A fresh recording with skill 52, which reads each listed object by id. -- Path parameters given as numbers stay refused: they are required properties, which REA keeps free of combinators. -- A counter one create alone shows, and linked creates into a collection whose path has parameters, which still take - only their recorded path values. diff --git a/docs/specs/agent-environments/write-coverage/plan.md b/docs/specs/agent-environments/write-coverage/plan.md deleted file mode 100644 index d18be7a89a..0000000000 --- a/docs/specs/agent-environments/write-coverage/plan.md +++ /dev/null @@ -1,12 +0,0 @@ -# Implementation plan - -1. **Bodiless writes.** The manifest accumulator tracks, per write group, whether every response was empty, and keeps - the group when one succeeded. -2. **Omitted fields.** The write simulation records required fields its successful reads show missing, and the - extracted state's views drop them. -3. **Projected reads.** Item planning sets aside unlocated projected reads and the view records their ordinals; the gate - skips them, and serving replays projected calls to such a view. -4. **Sequences.** A values helper reads a digit-group value as an integer and fills the next one into its mask; the - write rules, the gate and serving number sequences through it. -5. **Schema, tests and docs.** The view schema, manifest, gate, serving and unit tests, and the manifest, capture, - state-view and state-writes docs. diff --git a/docs/specs/agent-environments/write-coverage/spec.md b/docs/specs/agent-environments/write-coverage/spec.md deleted file mode 100644 index c02f452e3a..0000000000 --- a/docs/specs/agent-environments/write-coverage/spec.md +++ /dev/null @@ -1,54 +0,0 @@ -# Wider write coverage - -Issue: https://github.com/morluto/rea/issues/4933 - -## Outcome - -Four recording shapes kept write tools out of the manifest or left their writes unserved, although the recordings showed -what the writes did: - -- **Bodiless replies.** A write answered `204` with no body (Jellyfin's and Shlink's deletes, Miniflux's and Keycloak's - updates) had no JSON-like content type, so its group was excluded as `non-json` and never became a tool. -- **Omitted fields.** A field every recording of a view carried was required, so an application that leaves empty or - false members out of some entities (Go's `omitempty`) made the write gate refuse its own read-backs. -- **Projected reads.** An item read asking for some fields only (Directus's `/items/provisions/2?fields=title`) does not - repeat the requested id, so it blocked the identity proof of the whole item view, and the view's writes had no state - target. -- **Digit-group sequences.** A sequence spelled in digit groups (Homebox's asset number `000-005`) was not an integer, so - a create that numbers it had no rule for it and was contradicted. - -## Behaviour - -- **Manifest.** A write group (`POST`, `PUT`, `PATCH`, `DELETE`) is kept as a tool when every response had no body (a - `204` or `205`, an empty text, or a recorded size of zero) and one succeeded. A missing text alone does not count. -- **Omitted fields.** The write gate notes required fields missing from the entities the state holds that successful - reads it checks return, when the read names no projection parameter: the item whose id the path names, or the listed - items. No view of the type requires them any more. A read that checks nothing, such as one begun while a modelled - write to its targets still ran or a page the collection has outgrown, notes none. - Established omissions apply when classifying subsequent reads and choosing later write observations, not just - when serializing final views. A complete `fields=*` read is not partial solely for lacking a known optional field. -- **Projected reads.** An item read naming `fields`, `fields[...]`, `select` or `$select` that does not return the item - is left out of the identity proof and the view's checks. The view lists it in `projected_record_ordinals`, and serving - replays a call to that tool naming such a parameter, for an entity the state holds, with the reason `projection`; - the replay shows the recording, not served writes. The write gate neither checks nor learns a write's effect from a - successful read serving replays, nor from one that names such a parameter and leaves out a field its view requires; a - 400, 404 or 410 such a read answers is still the absence it checks. - Identity-free projection evidence after the initial-state cutoff is retained too, without seeding later values - into initial entities. Failed responses are classified before the projection-replay shortcut, so a projected - absence can confirm a delete or contradict an unexplained disappearance. - A list line asking for some fields only beside one showing whole entities is replayed the same way and proves no - identity or membership; an item or list line showing its entities in another representation (an expanding or - reducing query) is replayed when a query key tells it from the view's other lines (`projected_query_keys`, reason - `variant`). A call asking for some fields only replays unless every value it gives is `*` or one a checked line - gave, and no replayed read gave it; such calls replay recordings and do not show served writes. -- **Sequences.** A sequence value may be `-`-separated digit groups of one width of at least two digits, not a date, - version or address. The next value keeps the exemplar's groups and zero padding; digits that outgrow them lead. A - later create must record its value spelled that way. A held value whose digits outgrew the mask (`100-00` after - `99-99`) counts only when it is the exemplar's spelling of its number, so a reloaded state numbers on from it. - -## Acceptance - -- Over the 50 published captures, no write group is excluded as `non-json`, served write tools rise from 35 to 39, and - no write tool is served on the base and unserved here. -- The re-recorded Homebox capture's create is served. -- Every served write tool of those captures applies. diff --git a/docs/specs/agent-environments/write-coverage/tasks.md b/docs/specs/agent-environments/write-coverage/tasks.md deleted file mode 100644 index 1df7c84182..0000000000 --- a/docs/specs/agent-environments/write-coverage/tasks.md +++ /dev/null @@ -1,10 +0,0 @@ -# Tasks - -- [x] Keep write groups answered with no body as tools. -- [x] Stop requiring fields a successful read shows the application leaves out. -- [x] Set projected item reads aside from the identity proof and replay projected calls. -- [x] Number sequences spelled in digit groups. -- [x] Add manifest, gate, serving and unit tests, failing on the previous head. -- [x] Document the manifest rule, the view member, the replay reason and the sequence spelling. -- [x] Measure the 50 published captures, the re-recorded Homebox capture and the served smoke. -- [x] Run static, formatting, duplication, documentation and test gates. diff --git a/docs/specs/agent-environments/write-coverage/verification.md b/docs/specs/agent-environments/write-coverage/verification.md deleted file mode 100644 index f80493df64..0000000000 --- a/docs/specs/agent-environments/write-coverage/verification.md +++ /dev/null @@ -1,74 +0,0 @@ -# Verification - -Executed on macOS with Node v22.23.1 on this branch, whose base is the write-plan branch's head `ad8f674d`. - -## Gates - -- `npm run build:cached`, `npm run check:fast` (typecheck and lint, no new warnings in the changed files), - `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 3776 files. -- `npx vitest run --project domain --project services`: 7808 passed, 5 pre-existing skips. Two unrelated heavy tests - (keyed-archive traversal, a 125,000-dependent Evidence graph) passed only with a longer timeout on a loaded machine. -- `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, 79 passed; the analysis-view MCP file needed a longer timeout on the loaded machine. - -## Tests - -- Manifest: a `204` write with no body is kept as a tool whatever its content type, and a write only redirected is not. -- Gate: - - a field a read-back leaves out stops being required, and a create lacking it is served only when its own read - leaves it out too; - - an item view proves its identity past a read that asked for some fields only, which is left to replay; - - creates numbered in digit groups are served. -- Serving: a created entity is served without the omitted field while seeded ones keep it; a call naming `fields` - replays with the reason `projection` while other calls answer from the state; creates take the next number in the - held value's digit groups. -- Unit: `-`-separated digit groups of one width read as a sequence, and a date, version, address or decimal does not; - the next value keeps the groups, overflow leading. -- The gate, serving and manifest tests fail on `ad8f674d`. - -Review fixes, each with a test that fails on `a4c4a23b`: - -- Gate: - - a read naming `fields`, or of a book the state no longer holds, notes no omission, and a create read back only - through `?fields=id,name` is not served; - - an omission an item read shows stops every view of the type requiring the field; - - a read naming `fields` that leaves a required field out neither resynchronises an entity nor serves as a write's - observation, so a `204` update read back first through `?fields=id,name` learns its effect from the whole read; - - a later create whose sequence value serving would spell otherwise (`00-04` or `4` after `000-003`) withholds the - plan. -- Serving: an empty projection argument replays; a projection of a deleted book answers as missing; a created book - without the omitted field lists. - -## Published captures - -Over the 50 published captures, against `ad8f674d`: - -- Write groups excluded as `non-json` go from 13 in five captures to none. Directus, Jellyfin, Keycloak, Miniflux and - Shlink gain those tools, so their manifests change. -- Served write tools go from 35 to 39; none is lost: - - Directus's provisions item view proves its identity past `GET /items/provisions/2?fields=title`, so its create and - update are served; - - Jellyfin's `DELETE /Items/{id}` and Shlink's `DELETE /rest/v3/short-urls/{slug}` are served. -- Airbyte's job item view stops requiring two fields its reads leave out; its verdicts are unchanged. -- Six states change: those five captures and Airbyte. -- A served smoke with manifests rebuilt by each tree applies all 39 served write tools here and all 35 on the base. - -## Re-recorded captures - -Captures re-recorded with a read-back after each first write and two scratch objects per write tool: - -- A Homebox pilot recording numbers assets in digit groups (`000-001`, `000-002`, …). Its create goes from - `contradicted` to served with a `sequence` rule on `assetId`, and the smoke applies it and the delete. -- Five published environments rebuilt from such recordings (Navidrome, Lychee, Homebox, Directus, Linkding) go from 9 - served write tools to 11, and the smoke applies all 11: - - Navidrome's playlist views stop requiring `imageAbsent`, which its new playlists leave out, so its playlist update is - served; - - Homebox's create is served, as in the pilot recording. -- Jellyfin and Memos, re-recorded and rebuilt end to end with this change (manifest, bundle, smoke and both evaluation - models on 12 retrieval tasks each), serve no new write: - - Jellyfin's four bodiless write groups become tools, all withheld. Its playlists are created through - `POST /Playlists` but read back only through `/Items/{id}`, which stops that item view rendering from the state. - - Memos has none of the four shapes; it names items `memos/`, which the identity proof does not match. diff --git a/docs/specs/agent-environments/write-create-calls/plan.md b/docs/specs/agent-environments/write-create-calls/plan.md deleted file mode 100644 index f495592330..0000000000 --- a/docs/specs/agent-environments/write-create-calls/plan.md +++ /dev/null @@ -1,12 +0,0 @@ -# Implementation plan - -1. **Defaults.** `WriteBody.defaults` and its schema; a create's echo of a member a call leaves out takes its default. -2. **Merging.** Explain a later create on its own and merge it: agreeing rules, references one call shows alone, joined - bodies and defaults, the plan's rule order. -3. **Sorted echoes.** Learn `sorted` for creates and updates, store sorted strings when serving, and agree plain and - sorted echoes in update and create plans. -4. **References.** A references module that learns and resolves them; created and updated fields resolve them against - the replayed or live state; the members they read are accepted. -5. **Nested view keys.** The gate's view spelling learner, moved to its own module, notes object keys; rendering - applies them. -6. **Schema, tests and docs.** diff --git a/docs/specs/agent-environments/write-create-calls/spec.md b/docs/specs/agent-environments/write-create-calls/spec.md deleted file mode 100644 index b84fc52a56..0000000000 --- a/docs/specs/agent-environments/write-create-calls/spec.md +++ /dev/null @@ -1,48 +0,0 @@ -# Learn creates from every call, sorted arrays and referenced entities - -Issue: https://github.com/morluto/rea/issues/4933 - -## Outcome - -After the derived-values change, the creates prompt-built environments still withheld failed for four reasons the -write model did not cover: - -- A create plan was learned from the tool's first call alone, so a later call that sent a member the first did not - (Linkding's `shared`), or left one out, was refused even when it agreed with the plan everywhere else. -- Linkding stores `tag_names` sorted, so a call that sent its tags in another order did not echo them, and its create - was withheld or contradicted. -- Homebox's item create answers its parent and type as whole objects (`parent`, `location`, `entityType`) beside the - `parentId` and `entityTypeId` it sent. Kept as constants, they pinned those members to their recorded values. -- Lists show some objects with fewer keys than an entity holds: Homebox lists an item's parent without the parent's - own type, and Keycloak lists a user's `access` with one key. A created entity's object rendered whole, so the list - check failed. - -## Behaviour - -- **Every call.** A later create is explained on its own and merged into the plan when both calls show the same fields, - but for a reference whose member a call without it did not send (one an earlier create added stays), every field - both rule they rule alike, and a field neither rules holds one value. Members either call sent are accepted, only - those every call sent are required, and an echoed member a call left out takes the value that call stored - (`body.defaults`). A clock widens to `trimmed` only when no held entity or earlier call showed it at a fixed width. A - later create that disagrees leaves the plan as it was and is judged as before; one that left out a member the plan - fills while showing that field otherwise is `unexplained-change`. Merged rules keep the plan's order. -- **Sorted arrays.** An echo is `sorted` when the application stored the sent strings in code-point order rather than - as sent; serving stores them sorted. A plain echo and a sorted one agree, and the plan keeps the sorted one, since a - call whose array was already in order cannot show it; once a call stored strings out of order as sent, they disagree. -- **References.** A created or updated object field that holds fields of the entity a sent member names, as the state - holds it, is a `reference` (member, type, fields). Several members naming such entities resolve to the one named like - the field. The member is accepted with any value. Replay and serving look the entity up in the state they hold; - serving refuses a call naming one the environment does not hold or holds in more than one collection, and the field - is absent, from the entity and the create's answer, when the call does not send the member. An update that sends the - member naming the entity the field already repeats keeps a reference an earlier call showed. -- **Nested view keys.** A view that always shows a field's objects with the same keys, in any order, and fewer than - an entity stores, names them in `nested_fields` in the first recording's order, and a stored object it never - recorded renders with those keys. - -Plans and views that need none of this are unchanged. - -## Acceptance - -- Linkding's prompt-recorded bookmark create whose read-back lists tags sorted is served, and Homebox's item create is - explained without pinning its parent or type. -- No write tool of the 69 recorded captures goes from served to withheld. diff --git a/docs/specs/agent-environments/write-create-calls/tasks.md b/docs/specs/agent-environments/write-create-calls/tasks.md deleted file mode 100644 index 136bd78fde..0000000000 --- a/docs/specs/agent-environments/write-create-calls/tasks.md +++ /dev/null @@ -1,10 +0,0 @@ -# Tasks - -- [x] Merge later create calls into the plan, with defaults for members a call leaves out. -- [x] Learn and serve sorted echoes. -- [x] Learn, replay and serve references to held entities. -- [x] Learn the keys views show of nested objects and render written objects with them. -- [x] Add view, serving and unit tests. -- [x] Document the rules and view member. -- [x] Measure the recorded captures and served write tasks. -- [x] Run static, formatting, documentation and test gates. diff --git a/docs/specs/agent-environments/write-create-calls/verification.md b/docs/specs/agent-environments/write-create-calls/verification.md deleted file mode 100644 index baa0fd4e28..0000000000 --- a/docs/specs/agent-environments/write-create-calls/verification.md +++ /dev/null @@ -1,61 +0,0 @@ -# Verification - -Executed on macOS with Node v24.22.1 at `043053d1` (main `79845063`, the derived-values branch `8ce1127b` and this -branch). Recorded captures and served write tasks were measured with a local, unpushed build of this branch merged with -the scenario-timing branch (#6967), as the derived-values branch was; its baseline is the derived-values branch with the -same merge. - -## Gates - -- `npm run -s typecheck`, `lint`, `format:check`, `docs:check`, `mcp-catalog:check`, `verify:test-discovery`, - `scan:todos` and `npx knip`: passed. -- `npx vitest run --project domain --project services --project adapters`: 17,258 passed, 25 skipped, 1 failed ("stops - Inspector target authorization after the current stat settles"), which fails the same way on main in this environment. -- `npm run test:focused --` the environment build, export and serve CLI boundaries, the analysis-view CLI and MCP - boundaries, the environment serve, served-writes and bundle MCP boundaries, MCP schema validation and output schema - constraints: 10 files, 82 passed. - -## Tests - -- View: a later create sending a member the first did not, or leaving one out, widens the plan with the member's default; - a later create storing a member otherwise than sent stays unexplained; sent tags stored sorted give a sorted echo; a - create embedding the shelf its `shelf_id` names gives a reference, and the list that shows the shelf by id and name - learns `nested_fields`. -- Serving: a create leaving the member out stores its default and one sending it stores it; a create embeds the named - shelf as the environment holds it, lists it with the listed keys, and is refused for a shelf it does not hold; sent - tags are stored sorted. -- Unit: references (the member named like the field among several, too few keys, a disagreeing value, an unheld entity) - and merges (a constant that differs, a member one fixes and the other accepts, a reference one call shows alone). - -## Write plans over recorded captures - -The 69 captures the derived-values branch measured: 50 published, 18 Claude Code recorded from a prompt, and one timed -Grafana recording. After merging main `ed79bf93` (which bounds create learning), the census was run again against main -with the scenario-timing branch: 124 served there, 132 with both branches, no write going from served to withheld; the -columns below are the measurements before that merge, whose totals it reproduces. - -| Captures | Write plans | Served before both branches | Derived values | This branch | -| ------------------------- | ----------- | --------------------------- | -------------- | ----------- | -| 50 published | 187 | 68 | 68 | 70 | -| 19 recorded from a prompt | 120 | 56 | 61 | 62 | - -- No write goes from served to withheld. -- Gains: Keycloak's published user create and update, whose list shows each user's `access` with one key, so a created - user now lists as recorded and its plan's sorted insert checks; and the round-4 Linkding bookmark create, whose tags - the application stores sorted. -- Explained but still withheld: Homebox's item create now merges with the location create, with references for - `parent`, `location` and `entityType` and `parentId` and `entityTypeId` accepted with any value. Its read-back list - answers items only, sorted by name, from a line with no parameter saying so, which the list model does not cover. -- Linkding's create whose later call sends `shared` merges too, and is withheld as `side-effect`: the recording also - added a bookmark through the UI that no recorded write explains. - -## Served write tasks - -The same captures rebuilt by the baseline and by this branch, with `fireworks_ai/gpt-oss-120b` and -`fireworks_ai/glm-5p3-flash`. The tasks are new; each checks the result from the environment's state, including that -nothing else changed. - -| Capture | Tasks | Baseline (gpt-oss, GLM) | This branch (gpt-oss, GLM) | -| --------------------------- | ------------------------------------------ | ----------------------- | -------------------------- | -| Linkding, recorded round 4 | 2 bookmark creates, one with two tags | 0/2, 0/2 | 2/2, 2/2 | -| Keycloak, published capture | create a user, change another user's email | 0/2, 0/2 | 2/2, 2/2 | diff --git a/docs/specs/agent-environments/write-derived-values/plan.md b/docs/specs/agent-environments/write-derived-values/plan.md deleted file mode 100644 index a5ae3f29f8..0000000000 --- a/docs/specs/agent-environments/write-derived-values/plan.md +++ /dev/null @@ -1,12 +0,0 @@ -# Implementation plan - -1. **Clock formats.** A `trimmed` ISO format, `fixedWidth` on a clock reading, fitting a format to another value, and - calendar digits, in a clock formats module. -2. **Composed strings.** A module that indexes a create's candidate parts once, segments a string, checks the type's - other entities and an update's before value, and spells the string from written fields. -3. **Explaining.** Create explanation composes unexplained strings after templates, learns trimmed clocks from the - type and generated integers; update explanation composes unsent changes after the existing rules. -4. **Later calls.** A later create or update widens the plan's clocks to a trimmed spelling it shows; a later create's - unique value may be a generated integer. -5. **Serving.** Derived fields are rebuilt after other rules; unique integers are seeded by length and kind. -6. **Schema, tests and docs.** The plan schema, view, serving and unit tests, and the write-plan docs. diff --git a/docs/specs/agent-environments/write-derived-values/spec.md b/docs/specs/agent-environments/write-derived-values/spec.md deleted file mode 100644 index efc90d707a..0000000000 --- a/docs/specs/agent-environments/write-derived-values/spec.md +++ /dev/null @@ -1,59 +0,0 @@ -# Explain values an application derives from other fields - -Issue: https://github.com/morluto/rea/issues/4933 - -## Outcome - -Environments an agent built from a prompt withheld creates in three of five applications, each for a value the write -model could not explain, though the application derives it deterministically: - -- Linkding's `web_archive_snapshot_url` is `https://web.archive.org/web//`. - The plan kept it as a constant, which pinned `url` to its recorded value, so a later create with another URL was - refused. -- Grafana's folder `url` is `/dashboards/f//`, which pinned `uid` the same way, and its numeric - `id` is a large time-based integer the plan copied from the first create, which the second create's read-back - contradicted. -- Homebox, written in Go, spells nanosecond clocks with trailing fraction zeros dropped (`…34.38812218Z`), so a later - create's clock did not follow the format learned from the first. - -## Behaviour - -- **Composed strings.** A created field no other rule explains may be a `composed` string: literal text and parts read - from the fields other rules write, each a field's value, its slug, or a clock's calendar digits (`YYYYMMDDhhmmss`, - `YYYYMMDD`, `YYYY-MM-DD`, `YYYY/MM/DD`, in the clock's zone). Parts are found left to right, longest first, delimited - by non-alphanumerics; generated values may be short, other values need eight characters, as a copy does. A create - composes a string only when at least one other entity of the type spells it with the same parts and none spells it - otherwise, and never when one text comes from two sources serving could tell apart (two clocks the write stamps are - one source when they spell the same zone), and never when another entity holds the field as something other than the - parts spell, a non-string value included. An update's unsent change may be composed from members it stored as sent and - fields it left as they were, when the same parts also spell the value before the call and no other entity spells it - otherwise. Serving rebuilds the string from the written fields after every other rule and refuses a call when a part's - field holds nothing to spell, and a composed field no longer pins the members it reads. A composition learned on a - later call is checked against every earlier call, and a later create whose response spells a composed field otherwise - is withheld. -- **Trimmed clocks.** A clock format may be `trimmed`: its values differ only in how many fraction digits they show and - none ends a fraction in a zero. It is learned from the type's held values of the field, from a later create, and from - a later update; other clocks the plan stamps take the spelling too, and no clock takes it once a held entity, the - exemplar or any call the plan accepted showed the field at a fixed width; a later call that then shows it shorter is - withheld. `fraction` is the most digits shown, and serving drops trailing zeros and the point with them. -- **Generated integers.** A created integer of 10 to 20 digits that no entity of the type holds, where every held entity - holds a distinct one of the same length and JSON kind and none is a clock, is `unique`. Serving draws a seeded integer - of that length and kind that no held entity has. One that another field of the created entity also holds, as a value, - a number at any depth or a delimited part of a nested string, is not `unique`, and the create is withheld as - `unexplained-change`, since seeding cannot keep the two equal. A create is also withheld when another string holds its - digits and no `template` or `composed` rule rebuilds that string from it, or when a later create answers the field - with anything but an integer of the same length and kind. Compare treats two such integers of one JSON kind and length - under a `unique` rule as generated values. - -Plans that need none of this are unchanged. - -Later creates must retain the exemplar's unique-value family (UUID, integer with -the same digit count and JSON kind, or opaque token). Their recorded composed -fields must equal the values the plan rebuilds; simulation cannot replace a -contradictory captured value and then count that replacement as confirmation. - -## Acceptance - -- The prompt-built Linkding, Homebox and Grafana captures serve the creates and renames they withheld, and write - tasks that use them pass. -- No write tool of the 50 published captures or the earlier prompt-built captures goes from served to withheld. diff --git a/docs/specs/agent-environments/write-derived-values/tasks.md b/docs/specs/agent-environments/write-derived-values/tasks.md deleted file mode 100644 index ae9e074b47..0000000000 --- a/docs/specs/agent-environments/write-derived-values/tasks.md +++ /dev/null @@ -1,10 +0,0 @@ -# Tasks - -- [x] Read and fit trimmed clock formats, and spell calendar digits. -- [x] Compose created strings and unsent update changes from other fields. -- [x] Learn generated integers as unique values and serve them by length and kind. -- [x] Widen plan clocks on later creates and updates, and spread a trimmed spelling to the plan's other clocks. -- [x] Add view, serving and unit tests. -- [x] Document the rules. -- [x] Measure the prompt-built captures, the 50 published captures and the served write tasks. -- [x] Run static, formatting, documentation and test gates. diff --git a/docs/specs/agent-environments/write-derived-values/verification.md b/docs/specs/agent-environments/write-derived-values/verification.md deleted file mode 100644 index 5f74a2d775..0000000000 --- a/docs/specs/agent-environments/write-derived-values/verification.md +++ /dev/null @@ -1,91 +0,0 @@ -# Verification - -Executed on macOS with Node v24.22.1 at `a1edeafd` (main `79845063` plus this branch). The prompt-built recordings and -evaluations used a local, unpushed build of this branch merged with the scenario-timing branch (#6967), whose request -times the clock rules need from browser scenarios, on Ubuntu 24.04 VMs with snap Chromium 155. The baseline is the same -merge without this branch. - -## Gates - -Follow-up on 2026-10-25, after merging main `a5bfd0440`, with Node 24.22.1 and npm 11.16.0 on macOS: - -- Environment write/compare source tests: 26 files, 839 passed. -- Analysis-view CLI/MCP, environment served-write MCP, environment-compare CLI, managed bundle read guards, and setup - registration prewarm boundaries: 6 distinct files, 77 passed. The managed low-headroom failure is fixed by main's - Evidence ownership change (#7036); the setup tests share host preparation to satisfy lint without removing cases. -- `check:fast`, `format:check`, and `docs:check`: passed. -- New capture-to-plan regressions reproduce missing composition parts on earlier updates (null and structured sources) - and fixed-width clock evidence from either the selected entity or another held entity. Rule tests exercise several - separator/zone groups in both orders, choosing each group's widest trimmed peer while preserving fixed-width fields. -- Compare uses the domain clock matcher on parsed readings. Tests cover shorter fractions, absent fractions, maximum - width, trailing zeros, separators, zones, and response-entity scope; the compiled CLI accepts a Go-style create whose - live clocks have eight digits and served clocks have none, preserving all input Evidence files. -- The original application's recordings and model evaluations below were not rerun in this follow-up. - -Original author validation: - -- `npm run -s typecheck`, `lint`, `format:check`, `docs:check`, `mcp-catalog:check`, `verify:test-discovery`, - `scan:todos` and `npx knip`: passed. -- `npx vitest run --project domain --project services --project adapters`: 17,246 passed, 25 skipped, 1 failed ("stops - Inspector target authorization after the current stat settles"), which fails the same way on main in this environment. -- `npm run test:prepare`, then `npm run test:focused --` the environment build, export and serve CLI boundaries, the - analysis-view CLI and MCP boundaries, the environment serve, served-writes and bundle MCP boundaries, MCP schema - validation and output schema constraints: 10 files, 82 passed. - -## Tests - -- View: Go-spelled tag creates and renames are served with a trimmed clock; bookmark creates are served with a composed - snapshot address and accept any URL; folder creates and renames are served with a composed address and a generated - integer id. -- Serving: a served tag create spells its clocks without trailing zeros; a served bookmark create composes its snapshot - address from the served clock and the sent URL; a served folder create gets a fresh sixteen-digit id and an address - that follows its uid and title, and a rename moves the address. -- Unit: fitting clock formats (trimmed, fixed width, separator and zone), calendar digits, seeded integers, generated - integer detection, composition and its refusals (one call alone, a held entity spelling otherwise, two sources with - one text, a member stored otherwise than sent, a value the parts do not spell before the call), and a wide body - composed within the existing time limit. - -## Write plans over recorded captures - -Every write plan of 69 captures, built by the baseline and by this branch: the 50 published captures, 18 captures -Claude Code recorded from a prompt for the prompt branch's checks, and one new timed Grafana recording. - -| Captures | Write plans | Served on the baseline | Served on this branch | -| ------------------------- | ----------- | ---------------------- | --------------------- | -| 50 published | 187 | 68 | 68 | -| 19 recorded from a prompt | 120 | 56 | 61 | - -- No write goes from served to withheld. The five gains are Linkding's bookmark create, Homebox's tag create, and - Grafana's folder create in two recordings and folder rename in the timed one. -- Published plans change only where a value is now composed: Linkding's bookmark create and BookStack's book create and - update (`description_html` as `

` around the description) now accept the member they read. -- Unchanged by design: Grafana's published folder, whose uid and title slug are the same text, so its address names two - sources; Ghost's post update, whose `lexical` keeps the `derived` rule that explained it before; BookStack's page HTML - and Jellyfin's playlist path, which other pages and playlists of the capture spell otherwise. -- What still withholds a create the composed value now explains: a later Linkding create that sends a member the first - did not (`shared`), Homebox item creates that differ from the first location create, and a Linkding create whose - read-back lists `tag_names` sorted. - -## Served write tasks - -The same timed captures, rebuilt by the baseline and by this branch, with the models `fireworks_ai/gpt-oss-120b` and -`fireworks_ai/glm-5p3-flash`. Create tasks are new; recorded write tasks are the applications' existing ones with entity -counts taken relative to each bundle's state. - -| Application | Tasks | Baseline (gpt-oss, GLM) | This branch (gpt-oss, GLM) | -| ----------- | ---------------------------------- | ----------------------- | -------------------------- | -| Linkding | 2 bookmark creates | 0/2, 0/2 | 2/2, 2/2 | -| Linkding | 3 recorded (update, notes, delete) | 3/3, 3/3 | 3/3, 3/3 | -| Homebox | 2 tag creates | 0/2, 0/2 | 2/2, 2/2 | -| Homebox | 2 recorded deletes | 0/2, 0/2 | 0/2, 0/2 | -| Grafana | folder create and rename | not served | 1/2, 2/2 | -| Grafana | 2 recorded deletes | | 2/2, 2/2 | - -- Smoke and retrieval match on both builds (Linkding 9/9 and 8/9, Homebox 3/3 and 3/3); Grafana's new recording passes - its smoke task and 9/9 retrieval with both models. -- gpt-oss missed the Grafana rename by sending the update without the title it was asked to change, ten times; the - served environment refused each call with the members it accepts. -- Homebox's recorded deletes fail on both builds: this recording's served entity list holds its locations only, so the - models never find the item to delete. -- The created bookmarks' snapshot addresses and the created and renamed folders' addresses are checked from the - environment's state. diff --git a/docs/specs/agent-environments/write-form-calls/plan.md b/docs/specs/agent-environments/write-form-calls/plan.md deleted file mode 100644 index ea420c4540..0000000000 --- a/docs/specs/agent-environments/write-form-calls/plan.md +++ /dev/null @@ -1,10 +0,0 @@ -# Implementation plan - -1. **Blank members.** `WriteBody.blank` and its schema; creates explain empty members as blank; merges join them; - created fields apply a left-out blank member as sent. -2. **Listed ids.** `listed_ids` on list views and its schema; the gate learns them; list rendering sets them. -3. **Sorted collections.** The replayed state moves an entity whose sorted field changed; update plans carry the - type's sort; serving moves updated entities; a failed whole-collection read after an update can teach the sort. -4. **Observations.** A create's item read-back accepts unloaded answer values; updates treat empty-container - respellings as unchanged; later creates check unruled fields. -5. **Skill, schema, tests and docs.** diff --git a/docs/specs/agent-environments/write-form-calls/spec.md b/docs/specs/agent-environments/write-form-calls/spec.md deleted file mode 100644 index f3fee2d1da..0000000000 --- a/docs/specs/agent-environments/write-form-calls/spec.md +++ /dev/null @@ -1,56 +0,0 @@ -# Serve the writes callers make without recorded form fields - -Issue: https://github.com/morluto/rea/issues/4933 - -## Outcome - -Agents now record writes through an application's UI, and environments built that way refused most of the creates -natural-language tasks ask for, or withheld them: - -- A form sends every field it shows, the ones left alone as `""`, `null`, `false`, `[]` or `{}`. Every member a - recorded create sent was required, so a call naming only a title was refused (Homebox tags required `color` and - `icon`, Linkding bookmarks `notes`, `unread` and `shared`, EspoCRM contacts about twenty members). -- Paperless-ngx answers lists with `all`, the ids of the listed entities in list order. The state did not render it, - so the first list read after every Paperless create contradicted the create. -- Grafana lists folders by title and Paperless lists tags by name. An update kept its entity where it was, so a rename - that sorted elsewhere contradicted the update, and a served rename listed in the wrong order. -- A Vikunja create answers before it loads what it stored: the owner with empty fields and Go's zero time, and empty - lists as `[]` where reads show `null`. The later item read was not taken as the observation, so it contradicted the - create; an update whose answer spelled an empty list `[]` was unexplained. - -## Behaviour - -- **Blank members.** A create member a recorded call sent empty is not required. A call that leaves it out is applied - as sending that value (`body.blank`), so the entity, the answer and every rule reading the member come out as for - the recorded call. A member a later call left out takes the default it showed instead. A call may send a member as - any recorded call sent it empty, such as `null` where another stored a string, even once a default is learned, and - one leaving it out without a default is applied as the earliest did. Updates are unchanged. -- **Listed ids.** A list view names top-level envelope members that list two or more listed entities' identity values - in list order (`listed_ids`). A rendered list sets them to its own entities' values, unless it is a page of more - matches, which keeps the recorded value as a partial page's total does. -- **Sorted collections.** An update that writes the field its type's creates are sorted by moves its entity to where - the new value sorts, in replay and serving (a bulk update moving each entity in turn), and its plan carries that - `insert`. When a read listing the whole collection in collection order (not sorted by its query) fails after an - update and the type's creates are not sorted by a - field the update writes, replay tries the collection sorted by such a field when the entities no exercised write - changed already follow it, as serving moves only written entities, and unless a create was placed by a sort - that excludes it or a whole-collection read in collection order (not sorted by its query) that placed a create did - not follow it; on a match, the type's creates and updates take that order. -- **Unloaded answers.** A create's later item read is taken as its observation when it differs from the answer only in - values the answer had not loaded: empty, zero, `false` or Go's zero time, or objects whose members are each the same - or loaded so; the plan points to those values (`observation.read.unloaded`), which a served create's answer keeps as - the recorded answer showed them, unless the call sent one the plan stores as sent, while the state holds the read's. An unsent update field that changes only between - `null`, `[]` and `{}` is unchanged. Write answers, bulk answers and replay's checks of them included, spell empty - lists and maps the call did not send as their recorded answers did, and a sent one as sent. -- **Unruled fields.** A later create that stored a field no rule writes otherwise than the plan keeps it is - `unexplained-change` at the create, so its recorded entity is held and later reads check other writes as before. -- **Skill.** The two scratch creates differ in what they send, the second only what a person must give, however they - are made; the skill shows how to read signed-in pages' accessibility trees from a scenario, and re-records once with - request steps a UI write whose body the browser did not expose. - -Plans and views that need none of this are unchanged. - -## Acceptance - -- No write tool of the 109 recorded captures goes from served to withheld. -- Rebuilt from the same recordings, the branch passes at least the write tasks main passes. diff --git a/docs/specs/agent-environments/write-form-calls/tasks.md b/docs/specs/agent-environments/write-form-calls/tasks.md deleted file mode 100644 index a97673c1e6..0000000000 --- a/docs/specs/agent-environments/write-form-calls/tasks.md +++ /dev/null @@ -1,11 +0,0 @@ -# Tasks - -- [x] Learn blank create members and apply them when a call leaves them out. -- [x] Learn and render list envelope members listing the listed ids. -- [x] Move updated entities in sorted collections, in replay and serving, and learn a sort from a rename. -- [x] Take item read-backs over unloaded create answers and empty-container respellings. -- [x] Withhold later creates that store an unruled field otherwise. -- [x] Add view, serving and unit tests. -- [x] Document the rules and view member, and update the skill. -- [x] Measure the recorded captures and served write tasks. -- [x] Run static, formatting, documentation and test gates. diff --git a/docs/specs/agent-environments/write-form-calls/verification.md b/docs/specs/agent-environments/write-form-calls/verification.md deleted file mode 100644 index e0e5614687..0000000000 --- a/docs/specs/agent-environments/write-form-calls/verification.md +++ /dev/null @@ -1,124 +0,0 @@ -# Verification - -Executed on macOS with Node v24.22.1 at `5a3c6762` (main `99062fea`), and on Ubuntu 24.04 VMs with snap Chromium for -the agent recordings. - -## Gates - -- `npm run -s check:fast`, `format:check`, `scan:todos`, `docs:check`, `verify:test-discovery`, `mcp-catalog:check` and - `jscpd`: passed. `npx knip` reports one unused export, `isToolFamilyId` in `src/contracts/toolFamilies.ts`, which this - branch does not touch and main reports too. -- `npx vitest run --project domain --project services --project adapters`: 18,281 passed, 25 skipped, 1 failed ("stops - Inspector target authorization after the current stat settles"), which fails the same way on main in this environment. -- `npm run -s test:focused --` the environment build, export and serve CLI boundaries, the analysis-view CLI and MCP - boundaries and the environment serve MCP boundary: 7 files, 75 passed. `outputSchemaProfile.test.ts`: 4 passed; the - full catalog grows 648 bytes and the compact catalog, 554,640 bytes, does not change. - -## Tests - -- View: form creates whose empty members differ require only the member both filled and apply the others as sent; a - create with only a last name, sending `null` for strings and for a flag another create sent `false`, merges and is - served; a rename moves a label in a collection its - creates sort by name; a rename that sorts first teaches a folder collection's title order to its creates and updates; - a list envelope's `all` is learned and creates there are confirmed; a create answer with an unloaded owner and `[]` - for `null` takes its item read; an update answer spelling an empty list `[]` is unchanged; a later create storing a - derived field otherwise is withheld at the create and later deletes stay confirmed. -- Serving: a label created from its name alone stores the empty members as sent and is inserted by name, and one - without the required name is refused; renamed labels and folders move to where their new names sort, and a bulk - rename of two labels moves each; a created tag's id appears in the list envelope's `all` in list order; a note sent - `null` as one recording did is accepted after a later call taught `""` as its default, which a note left out takes; - a created and an updated task answer `assignees: []` as their recordings did while reads show `null`. -- Review cases: a member's recorded empty value stays accepted once a default is learned; a rename teaches title order - where the creates fit both id and title order; moving written entities in turn sorts `[a, b, c, d]` with `b→h` and - `c→i` as `[a, d, h, i]`. The plan and serving tests for these fail on the branch's first head `0ceff6fa`. - -## Write plans over recorded captures - -The 109 captures the saved-values branch measured: 50 published captures and 59 Claude Code recorded from a prompt, -built by main and by this branch. - -| Captures | Write plans | Served on main | This branch | -| ------------------------- | ----------- | -------------- | ----------- | -| 50 published | 187 | 70 | 70 | -| 59 recorded from a prompt | 337 | 177 | 209 | - -No write goes from served to withheld. The 32 newly served are 23 Paperless creates (tags, correspondents and document -types, every recording), 3 Vikunja label creates, a Vikunja task update, Grafana's folder rename and delete, a Homebox -tag delete, and a Linkding bundle update and delete. 65 plans require fewer members and 66 carry `body.blank`; 30 plans -change `insert`, mostly updates that now move their entity by the field their type's creates sort by. - -## Agent-built environments - -Claude Code (`claude-sonnet-5-5`) built an environment of each of seven applications from the same prompt, as the -saved-values branch measured, and each bundle's write tasks ran with `fireworks_ai/gpt-oss-120b` and -`fireworks_ai/glm-5p3-flash`. Each task checks its result from the environment's state, including that nothing else -changed. - -The Homebox and Linkding task specs used until now checked for seed objects an earlier round's recordings left behind -("Rec Fragile", `scratch-two.example.test`), which no current recording holds, so their "nothing else changed" check -could not pass. They now check the current seed. With the corrected specs, main passes both Homebox and both Linkding -tasks on the saved-values branch's recordings, so earlier rounds' 0/2 for those applications measured the specs, not -the required members. - -**The same recordings, built by main and by this branch** (gpt-oss, GLM): - -| Recording | Write tasks | Main | This branch | -| ----------------------------- | ----------- | --------- | ----------- | -| Paperless, saved-values | 3 | 1/3 2/3 | 3/3 3/3 | -| Paperless, main (two) | 3 + 3 | 3/6 3/6 | 5/6 5/6 | -| Grafana, saved-values | 2 | 0/2 0/2 | 1/2 1/2 | -| Grafana, main (two) | 2 + 2 | 3/4 3/4 | 4/4 3/4 | -| Vikunja, saved-values + main | 5 + 5 | 3/10 3/10 | 3/10 3/10 | -| EspoCRM, saved-values + main | 3 + 3 | 1/6 1/6 | 1/6 1/6 | -| Homebox, saved-values + main | 2 + 2 | 2/4 2/4 | 2/4 2/4 | -| Linkding, saved-values + main | 2 + 2 | 2/4 2/4 | 2/4 2/4 | -| Miniflux, saved-values | 3 | 3/3 3/3 | 3/3 3/3 | -| Total | 42 | 18 19 | 24 23 | - -No recording passes fewer tasks with this branch. Paperless creates pass once served. The saved-values Grafana -recording's rename is served and passes; its create still needs the saved-values branch's composed address. -Vikunja's task create, EspoCRM's leftover contact (held as seeded data, so every "nothing else changed" check fails) -and the main Homebox recording, which wrote no tags, are unchanged. - -**Fresh recordings.** Each application was recorded afresh with main (skill 49) and with this branch. The branch was -recorded again for the four applications whose first branch recording passed fewer tasks, and a third time after the -skill's sixth step was reworded; the final skill's recordings are the last column (served writes, then tasks): - -| Application | Write tasks | Main | Branch, first two recordings | Branch, final skill | -| ----------- | ----------- | -------------------- | ---------------------------- | -------------------- | -| Paperless | 3 | 2, 1/3 2/3 | 8, 1/3 2/3 | | -| Linkding | 2 | 0, 0/2 0/2 | 5, 2/2 2/2 | | -| Miniflux | 3 | no bundle | 4, 3/3 3/3 | | -| Grafana | 2 | 3, 2/2 2/2 | 1, 0/2 1/2; 3, 1/2 2/2 | 0, 0/2 0/2 | -| Vikunja | 3 + 2 | 3, 1/3 1/3 + 2/2 2/2 | 0, 0/5 0/5; 0, 0/5 0/5 | 1, 1/3 1/3 + 0/2 0/2 | -| EspoCRM | 3 | 2, 1/3 1/3 | 2, 1/3 1/3; 2, 1/3 1/3 | 2, 1/3 1/3 | -| Homebox | 2 | 4, 2/2 2/2 | 1, 0/2 0/2; 1, 0/2 0/2 | 3, 2/2 2/2 | - -Every fresh recording builds the same plans with main and with this branch, except Paperless (main serves 0 of the -branch recording's writes and 2 of 3 of its own), Vikunja's main recording (3 to 4) and the EspoCRM recordings below; -the per-application differences are what each agent recorded: - -- **Paperless:** the branch recording serves creates, renames and deletes of tags, correspondents and document types. - Its two tag creates used a light and a dark color, whose derived `text_color` differs, so the tag create stays - withheld and the tasks, which create a tag, score as on main. -- **Linkding:** main's agent recorded no writes. The branch's second bookmark create sent only `url` and `title`, so - the served create requires only those. -- **Miniflux:** main's agent stopped and asked for an API key. The branch's agent created a token in the UI and sent it - as a literal header value, which REA recorded as written; the instance and its token were destroyed afterwards. -- **EspoCRM:** following the sixth step, the branch's second contact sent only a last name, with `null` for strings the - first stored and for flags it sent `false`. That merge was refused until the empty-spelling fix in this PR; with it, - the create requires only `lastName` and `name` and its task passes, as on main. -- **Vikunja:** the first two branch agents wrote through the UI, whose request bodies Chromium did not expose, so every - write was `body-unusable`. The sixth step then read "fill every field the form offers"; reworded to say how the - creates differ, not where they are made, the third agent wrote with request steps. It recorded no label writes. -- **Homebox:** the first two branch agents recorded item writes only, the third tags as main's did. -- **Grafana:** the branch agents created folders with request steps and their own uids. The second create's address - needs the saved-values branch's composed-address fixes to be explained, so the create is withheld here. - -## Not verified - -- One to three fresh recordings per application and version; agent runs vary more than the builds do. -- Request bodies Chromium does not expose for some UI writes (Vikunja's); the skill now re-records such a write once - with request steps. -- Paperless derives `text_color` from `color`, so a create whose two recorded colors differ in brightness stays - withheld; EspoCRM's create still requires `name` and `emailAddressData`, which it derives from other members. diff --git a/docs/specs/agent-environments/write-later-reads/plan.md b/docs/specs/agent-environments/write-later-reads/plan.md deleted file mode 100644 index 3bf2ede604..0000000000 --- a/docs/specs/agent-environments/write-later-reads/plan.md +++ /dev/null @@ -1,10 +0,0 @@ -# Implementation plan - -1. **Soft deletes.** `markedDeleted` reads the deleted flags; item-read checks, adoption and replay's resync treat a - marked object as absent. -2. **Page sizes.** Add the names to the paging and query `limit` sets. -3. **Later fields.** Extraction collects the members later plain item reads show; the gate adds those no merged entity - holds to the item view without requiring them. -4. **Answers.** `laterItemFields` names the item view's fields no initial entity holds; write answers and the verdict's - `incomplete-entities` check skip them for entities without them. -5. **Skill, tests and docs.** diff --git a/docs/specs/agent-environments/write-later-reads/spec.md b/docs/specs/agent-environments/write-later-reads/spec.md deleted file mode 100644 index e411ae81d7..0000000000 --- a/docs/specs/agent-environments/write-later-reads/spec.md +++ /dev/null @@ -1,42 +0,0 @@ -# Serve the writes that later reads explain - -Issue: https://github.com/morluto/rea/issues/4933 - -## Outcome - -Environments built from a prompt withheld some writes in every recording of an application, though the recordings read -each write back: - -- EspoCRM keeps a deleted record. A read of it answers `200` with the record and `deleted: true`, which replay took - as the record still being there, so contact and task deletes were contradicted or left unconfirmed. -- EspoCRM pages its lists with `maxSize`, which REA did not know as a page size, so a list read after a delete was not - taken as listing the whole collection and confirmed nothing. -- Vikunja shows `subscription` only on tasks created after the recording started. The tasks' item view did not show - it, so reads of created tasks disagreed with the state and contradicted the task update before them; and an update - whose recorded answer shows it could not answer for a seeded task, which lacks it. - -## Behaviour - -- **Soft deletes.** An item read whose object is marked deleted (`deleted`, `isDeleted` or `is_deleted` set to `true`) - agrees with an entity the state does not hold, as a `404` does. Replay drops the entity such a read names, and such - an object never seeds or adopts an entity. The item view records the flag its reads set as `deleted_flag`, and - serving keeps an entity a served delete removed from such a type until a reset or load, so a read of it by id answers - its last fields with the flag `true`, as the application does. -- **Page sizes.** `maxSize`, `max_results` and `maxResults` are page sizes, for a list read's whole-collection - membership and for a list query's `limit` role. -- **Fields only later reads show.** An item view also shows the members that reads after its type's first write show - of the entities they name, when no initial entity holds them. They are never required. An update or delete that - answers with the entity, a bulk update's answer included, leaves such a field out when the entity does not hold it, - and the field no longer makes the write `incomplete-entities`. A field some initial entity holds keeps the existing rule: an answer showing it is - refused for an entity without it. -- **Skill.** Updates change the fields a person would change (a name, an email address, a status, a due date) rather - than only a description, since a served update accepts only the members a recorded update stored, and a deleted - object may read back marked deleted instead of `404`. - -Plans and views that need none of this are unchanged. - -## Acceptance - -- No write tool of the 130 recorded captures goes from served to withheld, and no plan's rules, body or `insert` - changes. -- Rebuilt from the same recordings, the branch passes at least the write tasks #7260 passes. diff --git a/docs/specs/agent-environments/write-later-reads/tasks.md b/docs/specs/agent-environments/write-later-reads/tasks.md deleted file mode 100644 index 17f01cf5fd..0000000000 --- a/docs/specs/agent-environments/write-later-reads/tasks.md +++ /dev/null @@ -1,11 +0,0 @@ -# Tasks - -- [x] Treat item reads of objects marked deleted as absent in checks, adoption and replay. -- [x] Answer a read of a served-deleted entity of such a type marked deleted, until a reset or load. -- [x] Learn `maxSize`, `max_results` and `maxResults` as page sizes. -- [x] Add fields only later item reads show to item views, unrequired. -- [x] Leave those fields out of write answers for entities without them, and stop them withholding updates. -- [x] Add view, serving and unit tests. -- [x] Document the rules and update the skill. -- [x] Measure the recorded captures and served write tasks. -- [x] Run static, formatting, documentation and test gates. diff --git a/docs/specs/agent-environments/write-later-reads/verification.md b/docs/specs/agent-environments/write-later-reads/verification.md deleted file mode 100644 index 231683e86a..0000000000 --- a/docs/specs/agent-environments/write-later-reads/verification.md +++ /dev/null @@ -1,84 +0,0 @@ -# Verification - -Executed on macOS with Node v24.22.1 on this branch, built on #7260's head `053264bd` (main `662ec2e4`), and on -Ubuntu 24.04 VMs for the task runs. - -## Gates - -- `npm run -s check:fast`, `scan:todos`, `docs:check`, `verify:test-discovery`, `mcp-catalog:check` and `jscpd`: - passed. -- `npx oxfmt --check .` reports `scripts/verify-apk-signature.mjs` only, which this branch does not touch and - `053264bd` reports too. `npx knip` reports `isToolFamilyId` in `src/contracts/toolFamilies.ts` only, as main does. -- `npx vitest run --project domain --project services --project adapters`: 18,420 passed, 25 skipped, 1 failed ("stops - Inspector target authorization after the current stat settles"), which fails the same way on main in this - environment. -- `npm run -s test:focused --` the environment build, export and serve CLI boundaries, the analysis-view CLI and MCP - boundaries and the environment serve MCP boundary: 7 files, 75 passed. - -## Tests - -- View: a contact delete whose item read answers the record with `deleted: true` is served, confirmed by that read and - the list; only a `true` `deleted`, `isDeleted` or `is_deleted` marks an object deleted; a delete is confirmed by a - list read paged with `maxSize`; a field only created tasks show joins the task item view without being required; a - task update whose answers show it is served. -- Serving: a deleted contact leaves the served list; an update of a seeded task, single or bulk, answers without the - field only created tasks show (the bulk case fails on `4515a000`, before the review fix). -- The six behaviour tests fail on `053264bd`. -- The existing serving test that refuses to give chapter rows to a book the state holds without them still passes. A - first version of the answer rule left out every field the item view does not require, which served that update; the - rule now covers only fields no initial entity holds. - -## Write plans and views over recorded captures - -The 109 captures #7260 measured and #7260's 21 fresh recordings, built by `053264bd` and by this branch: - -| Captures | Write plans | Served on #7260 | This branch | -| ------------------------- | ----------- | --------------- | ----------- | -| 50 published | 187 | 70 | 71 | -| 80 recorded from a prompt | 428 | 258 | 268 | - -- No write goes from served to withheld, and no plan's rules, body or `insert` changes. The 11 newly served are - EspoCRM contact deletes in seven recordings, the published EspoCRM capture's task delete, and Vikunja task updates - in three recordings. -- With main `c6893d1a` merged, whose `unknown-clock` withholds clock writes without an anchor on both builds, #7260 - serves 322 and this branch 332. One of the Vikunja task updates is among the writes it withholds, so this branch - gains 10, and none goes from served to withheld. -- 73 list views learn a page size they held as `inert`, valid only for its recorded values, as `limit`: 72 EspoCRM - lists (`maxSize`) and one Umami list (`maxResults`). One EspoCRM stream list now counts a line paged only by - `maxSize` as listing the whole collection and explains its other line's query; no view explains fewer lines. -- Six item views gain a field only later reads show, never required: Vikunja's tasks `subscription` in four recordings, - a Homebox entity's `children` and Mattermost's posts `has_reactions`. Every other view is unchanged. - -## The same recordings, built by #7260 and by this branch - -Claude Code (`claude-sonnet-5-5`) recordings from earlier rounds, rebuilt by each version, their write tasks run with -`fireworks_ai/gpt-oss-120b` then `fireworks_ai/glm-5p3-flash`, each checked from the environment's state: - -| Recording | Write tasks | #7260 | This branch | -| ---------------------------------------------- | ----------- | ----------- | ----------- | -| EspoCRM: main, #7260 (three), saved-values | 5 × 3 | 5/15 5/15 | 15/15 10/15 | -| EspoCRM: saved-values, leftover contact | 3 | 0/3 0/3 | 0/3 0/3 | -| Vikunja: main, #7260 final, saved-values (two) | 4 × (3 + 2) | 8/20 8/20 | 8/20 8/20 | -| Homebox: main | 2 | 2/2 2/2 | 2/2 2/2 | -| Total | 40 | 15/40 15/40 | 25/40 20/40 | - -No recording passes fewer tasks with this branch. - -- **EspoCRM:** the contact delete passes with both models on all five recordings. The contact update passes with - gpt-oss on all five only by replacing the contact: the served update refuses `emailAddress`, which no recorded update - stored, so the agent created a contact with the new address and deleted the old one, which the task's check, by name - and address, accepts. The update itself is refused in both builds, as is a read of a seeded contact by id, since the - state knows seeded contacts only from list reads, which lack fields the item reads show. GLM's update fails in both - builds the same way, and it often ends a turn at the eval agent's 1,024-token completion limit. -- **EspoCRM, leftover contact:** the recording started with a contact an earlier attempt left, held as seeded data, so - every "nothing else changed" check fails in both builds. -- **Vikunja:** the newly served task update accepts the members the recorded update stored (`title`, `description`, - `priority`), so the task asking to mark a task done is refused in both builds. The skill now asks for updates that - change a status, an email address or a due date. Task creates are unchanged. -- **Homebox:** the entity view's new `children` field changes no task. - -## Not verified - -- An application answering `deleted: true` for a record it still lists, as a trash view might: such a read counts as - absent. No recorded capture does this. -- The skill's update wording, which no fresh recording has used yet. diff --git a/docs/specs/agent-environments/write-rules/plan.md b/docs/specs/agent-environments/write-rules/plan.md deleted file mode 100644 index 3912789f3e..0000000000 --- a/docs/specs/agent-environments/write-rules/plan.md +++ /dev/null @@ -1,14 +0,0 @@ -# Implementation plan - -1. **Blame and the constant guard.** A module attributes a failed item read to the writes whose fields it disagrees on, - and create explanation pins members a constant derives from. -2. **Update rules.** A module holds the stamp, derived, held-clock, nested-clock, token and envelope rules; write - plans record the recorded query and pinned members, and serving and the gate apply them alike. -3. **View order.** A module orders collections by whole order-free lines, another learns sorted string arrays from - read-backs, and the list query and the initial order share one order vocabulary. -4. **Bulk writes and item actions.** A module addresses writes at a collection or an action path; the gate applies - them per entity and serving answers them atomically. -5. **Per-response members.** A module finds members a path mints anew and leaves them out of that path's comparisons. -6. **Nested counters.** List facts and rendering read and write totals through JSON pointers. -7. **Tests and docs.** Each step's tests fail on the step before; the state-view, state-writes, list-queries and - state-coverage specs and the environment docs describe the new behaviour. diff --git a/docs/specs/agent-environments/write-rules/spec.md b/docs/specs/agent-environments/write-rules/spec.md deleted file mode 100644 index 3f3d470018..0000000000 --- a/docs/specs/agent-environments/write-rules/spec.md +++ /dev/null @@ -1,88 +0,0 @@ -# Serve writes by what their recordings show - -Issue: https://github.com/morluto/rea/issues/4933 - -## Outcome - -After state targets, 30 write tools across the 50 published capture-built environments had a state target but were -refused (contradicted, an unexplained change, or a side effect), and 59 still had none. A diagnosis traced each -refused tool to the fields that differed between the gate's state and the recorded read, and named seven shared -causes. Seven of the 30 are refusals REA should keep (asynchronous jobs, rendered markup, reverse embeds, appended -relation rows), and six need only a better recording. This change addresses the causes REA can fix: - -- **Blame too broad.** A failed read contradicted every write it exercised, whatever fields differed. -- **Unsent update changes.** An update changing a field it did not send had no rule unless the change was a top-level - clock, unique value, slug, renewal or increment. -- **View order.** Collections took their initial order from the earliest sighting, and arrays a view lists sorted were - compared in written order. -- **Targets at a collection or an action path.** Bulk writes naming entities in the body, and actions at - `/{type}/{id}/{verb}`, had no target. -- **Per-response members.** A UUID or clock minted on every response made a view's envelope vary. -- **Nested counters.** A list total inside a paging object (`pageInfo.totalRows`) stayed at its recorded value. - -## Behaviour - -- **Blame.** A failed item read with no interfering unmodelled write contradicts the creates and deletes it exercised. - It contradicts an update only on a field that update wrote or its response showed, and a field the state lacks that - the read and the update's response both show is the update's change. A read that embeds a created entity elsewhere - and the state does not contradicts the create. -- **Constant guard.** A create member is accepted only with its recorded value when a constant derives from it: its - echoed text inside the constant, a referenced entity's string, or an instant beside a sent date, matched by related - field names. Only successful calls sent with the exemplar's query show that a member may vary. -- **Update rules.** An update's unsent change can be a modified-by stamp beside a created-by counterpart (with its id - sibling), a value derived from the one sent member stored nowhere (accepted only while the target holds the recorded - before-value), or a sent clock other than a creation clock left in the call's own second, which every call must then - send with the value the entity holds. An unsent clock left in the call's own second keeps the update unconfirmed until - another call shows it stamped. Objects whose clocks moved with the request are nested clocks, stored from the - read-back on creates and updates and refused once any call left the object as it was; opaque tokens of a type's own - length are generated; an enveloped body is learned as its one object. A write takes only its recorded query, and a - call sent with another neither confirms nor teaches its plan: a create or update only brings the state to what it - recorded, and a delete, document or bulk call leaves its target unknown. An echoed reference to a nested object or a - state word paired with other fields stays at its recorded value. The served catalog names these values. -- **View order.** A collection's initial order comes from the first list line that shows every entity its type's - sightings do and applies no order. A view renders a string array sorted only after a counted read-back shows an - order that neither the written order nor existing-values-first explains, among the entities that read covers in its - own collection. A later read contradicting a learned sort makes that view recorded and removes its earlier - write confirmations and saved overrides; types and entities with no surviving state view leave the snapshot. - The read's formerly sorted fields are compared as string multisets, so inconsistent ordering supplies no new - proof and does not hide real value mismatches or contradict an independent view's valid write confirmation. - Retired views keep a comparison-only representation to check later reads for value contradictions; they never - regain serving authority or confirm writes through those checks. - Sort and direction parameters share one vocabulary and are never learned as inert. A create placed by disagreeing - sorts or a random id falls back to `last`. -- **Bulk writes.** A write at a type's collection whose body names entities by id, as an id array or objects carrying - the id field, deletes or updates each one, all or none; serving refuses it unless every id is held. Body ids are taken - as written, and a call naming one entity twice is refused. Each entity's generated values come from that entity, - sharing the call's clock and counters. A delete requires the members its exemplar sent besides the ids, with their - recorded values. A recorded response is served when it names none of the ids and counts nothing, or is an array with - one element per entity the body names, in the body's order, each that entity with the first element's members or its - id spelled as the first spells its own; serving renders each element from the entity the call wrote, and any other - response naming the ids refuses the tool. Comparison translates a bulk body's ids with the mapping of the collection - the write targets. -- **Item actions.** A write to an item path plus a literal segment that names no collection, whose calls answer - nothing or the entity (never a 201, and with every field its item read always shows), updates that entity; a scalar - it changes without sending is set on every call. It is served only once a call found every field it sets already at - that value, so a toggle is never served. An action never takes a read another write to the entity still needs. -- **Per-response members.** A top-level member whose value is a UUID or a clock is minted per response on a path when - it differs on every repeat of that path's successful GET lines with no write between, and across the capture it - differed on at least two repeats and never stayed the same. A shared view leaves it out only when every concrete - path it answers independently proves it minted; a collection's proof never transfers to its item paths. Item - envelopes and the write gate's item, list and document reads compare without these common proved members. - The view names it in `per_response_members`, and serving keeps the recorded value. -- **Nested counters.** An item total in a top-level object beside the list is a counter on the same evidence as a - top-level one, rendered from the state through its pointer. A top-level member whose name starts with `/` is named by - its pointer (`/~1total`). - -## Acceptance - -- Over the 50 published captures, served write tools rise and none is lost except where the evidence cannot show the - write's own effect; write tools with no state target fall. -- Read calls that state serving answers keep matching their recordings, before the first write and across sessions. -- Every newly served write answers a call other than the recorded one correctly, or refuses it. - -## Not included - -- Soft deletes, appended relation rows, rendered markup and reverse embeds; creates completed from later reads. -- Templating literal ids by value (an opt-in rule served two deletes whose targets came from unserved writes wrongly). -- Identity aliases and resource names; per-response values that differ as instants. -- A replayed write leaves the state as it was, so a served write on an entity only a replayed write made refuses. diff --git a/docs/specs/agent-environments/write-rules/tasks.md b/docs/specs/agent-environments/write-rules/tasks.md deleted file mode 100644 index fb2a5a43b0..0000000000 --- a/docs/specs/agent-environments/write-rules/tasks.md +++ /dev/null @@ -1,14 +0,0 @@ -# Tasks - -- [x] Blame a failed read on the writes whose fields it disagrees on, and pin members constants derive from. -- [x] Explain unsent update changes, nested clocks, tokens and envelopes by what the recording shows. -- [x] Order collections by whole lines and sort only arrays a read-back proves sorted. -- [x] Serve bulk writes at a collection and target item actions. -- [x] Set aside response members a path mints anew on every read. -- [x] Count a list total nested in a paging object. -- [x] Take a created entity's nested clocks from its read-back. -- [x] Confirm no update whose clocks or fields the evidence cannot show it writing. -- [x] Show pinned query and body values in the served catalog, and apply bulk writes atomically. -- [x] Add tests that fail on the step before each change. -- [x] Measure the 50 published captures, the served smoke and recorded-read serving after each step. -- [x] Run static, formatting, duplication, documentation and test gates. diff --git a/docs/specs/agent-environments/write-rules/verification.md b/docs/specs/agent-environments/write-rules/verification.md deleted file mode 100644 index 489a572ed3..0000000000 --- a/docs/specs/agent-environments/write-rules/verification.md +++ /dev/null @@ -1,180 +0,0 @@ -# Verification - -Executed on macOS with Node v22.23.1, one change at a time on the state-targets branch, over the 50 published -capture-built environments (each app's latest capture). The served smoke rebuilds each manifest with the tree under -test and applies every served write tool. The serving check answers every recorded read made before the capture's -first write through state serving and compares it with the recording; it reads no calls from the five -browser-scenario captures. The session replay answers every recorded call in order, writes included, through state -serving, reading records with REA's own capture parser, and compares the reads; it covers all 50 captures. - -## 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.57% duplicated lines over 4235 files. -- `npx vitest run --project domain --project services`: 9545 passed, 6 pre-existing skips. The 10 failures (JavaScript - Map endpoints, a returned invocation's alias graph, Frida cleanup) fail the same way on main. -- `npm run -s test:prepare`, then `npm run -s 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, 91 passed. - -## Measurements - -| Step | Served | No state target | State-backed read views | Reads before first write | Session reads | -| ---------------------------- | ------ | --------------- | ----------------------- | ------------------------ | -------------- | -| state targets | 62 | 59 | 1,151 | 2,085 of 2,155 | 2,764 of 3,022 | -| blame and constant guard | 63 | 59 | 1,151 | 2,085 of 2,155 | 2,764 of 3,022 | -| update rules | 68 | 59 | 1,151 | 2,085 of 2,155 | 2,763 of 3,022 | -| view order | 69 | 59 | 1,151 | 2,085 of 2,155 | 2,763 of 3,022 | -| bulk writes and item actions | 71 | 48 | 1,151 | 2,085 of 2,155 | 2,763 of 3,022 | -| per-response members | 71 | 46 | 1,153 | 2,087 of 2,162 | 2,766 of 3,031 | -| nested counters | 71 | 46 | 1,153 | 2,087 of 2,162 | 2,766 of 3,031 | -| created nested clocks | 71 | 46 | 1,153 | 2,087 of 2,162 | 2,766 of 3,031 | -| unshown writes refused | 69 | 46 | 1,153 | 2,087 of 2,162 | 2,766 of 3,031 | -| catalog values, atomic bulk | 69 | 46 | 1,153 | 2,087 of 2,162 | 2,766 of 3,031 | -| review fixes | 69 | 46 | 1,153 | 2,087 of 2,162 | 2,766 of 3,031 | -| scoped envelopes, bulk rows | 69 | 48 | 1,151 | 2,085 of 2,155 | 2,763 of 3,022 | - -All 187 write tools are counted at every step, and the served smoke applies every served write tool. - -- **Scoped envelopes, bulk rows:** a shared envelope masks only members minted on every path, so Vault's identity entity - and group item views, which matched one of four and one of three recorded reads from the state, replay their - recordings, and Vault's entity update and delete lose their state target. Serving bulk responses that list each - written entity changes no capture's verdict. -- **Review fixes:** literal bulk ids, per-entity bulk values, pinned bulk delete members, comparison ids per - collection, echoed creation clocks, required held clocks, nested clocks checked against every call, learned sorts - kept open to contrary reads and limited to the read's own entities, one query check per recorded call, guards - relaxed only by successful calls with the exemplar's query, and slash-named counters. No tool's verdict and no - session read changed; each fix has a test that fails without it. - -- **Newly served:** Ghost's post create and update, Metabase's card create and update, n8n's workflow update, - Navidrome's playlist create, and the NocoDB and Mailpit bulk deletes. -- **No longer served:** Gitea's issue update. Its create, update and read share one second, so the evidence cannot show - the update stamping `updated_at`, and serving it left the clock as it was. -- **Refused that were briefly served on this branch:** EspoCRM's task update, for the same reason, with `modifiedById` - absent from its create response. -- **Session reads:** one read is lost at Ghost #74, a 404 right after the served create whose delete the recording - lacks; Vault #80 answers 404 after an unserved create, as a served read on an entity only a replayed write made does. -- Ghost's create and update accept only the recorded html, and Metabase's create only the recorded collection, - display, type and query; the served catalog shows those values. - -Every change had an independent review that rebuilt it and tried to refute it; the corrections they found are part of -the change. A final review of the whole branch found one wrongly served update (EspoCRM) and the hidden pinned values, -both fixed. - -## Cost - -Over the 50 captures, one Node v24.22.1 process per sweep builds the environment-state and environment-manifest views -of every capture (macOS arm64, warm medians of three runs; the cold first run is within 2% of them): - -| Tree | Wall | CPU | Peak RSS | Environment-state view | Its results | -| ----------------------- | ------ | ------ | -------- | ---------------------- | ----------- | -| main `d87e73f2` | 2.61 s | 3.41 s | 516 MiB | 1,791 ms | 3.69 MB | -| state targets (`#6385`) | 2.96 s | 3.82 s | 540 MiB | 2,093 ms | 3.84 MB | -| this branch | 3.06 s | 4.07 s | 601 MiB | 2,224 ms | 3.85 MB | - -The write rules add 0.10 s wall, 0.25 s CPU and 61 MiB of peak memory to the sweep while serving 7 more write tools. -Agent tokens were not measured; the views' results grow by 0.3%. - -## Not included - -- Templating literal ids by value: an opt-in rule served Grafana's folder delete and Vault's policy delete, but both - targets came from unserved writes, so serving them answered their own recorded calls wrongly. -- Completing a created entity from a later read: it served Bookstack's page create wrongly. -- Soft deletes, appended relation rows, rendered markup, reverse embeds, identity aliases and resource names. - -## Linux integration and review corrections, 2026-10-24 - -The following is separate from the historical 50-capture measurements above. -Node 24.22.1, baseline `3ce311757`, reviewed implementation `352c0278d`: - -- 1,236 selected source tests passed. Typecheck, built lint/module boundaries, - format, knip, metadata, architecture guards and documentation checks passed. -- Seven review regression checks failed before correction and passed after it. - Earlier structured update values now retain canonical equality digests within - the history budget. A shared envelope masks only members independently proved - minted on every concrete path. Empty advertised literals are widened while - execution enforces their values, and pinned queries are optional so their - execution defaults can run. Numeric and string bulk id arrays stay distinct. -- Nineteen compiled SDK/schema checks passed, including real HTTP MCP discovery, - empty fixed values, omitted empty and nonempty queries, and unchanged state - after refused writes. Live Gemini API execution was not performed. -- Four public datasets were downloaded at immutable Hugging Face revisions: - NocoDB `d0f7e040`, Ghost `6d5b2d1c`, Metabase `fa2aa0fd`, and Mailpit - `416b29be`, under `earakely-scale/*Env-REA`. Capture hashes, full calls, - independent recorded JSON comparisons, runtime identities and resource - receipts were retained locally. These were recorded real applications; - the original applications were not re-recorded in this verification. - -| Capture | Eligible write tools before / after | Initial reads matching | Session reads matching | -| -------- | ----------------------------------- | ---------------------- | ---------------------- | -| NocoDB | 0 / 3 | 20 / 20 | 80 / 92 | -| Ghost | 1 / 1 | 19 / 20 | 72 / 88 | -| Metabase | 1 / 2 | 19 / 22 | 99 / 122 | -| Mailpit | 0 / 1 | 51 / 52 | 51 / 56 | - -Every previously matching read remains matching, record by record. Real CLI -listeners and the MCP SDK reproduce the shared application's outcomes. The -feature session applies six NocoDB mutations, one Ghost deletion and one -Metabase update; the baseline applies only the Ghost deletion. A `state` -answer with view `missing` is not counted as an applied write. Mailpit exchange -65 is refused because its target was introduced only by an unserved create. -Eligibility does not establish that every recorded write can run on the initial -state, and the remaining read mismatches are preserved coverage gaps. - -Three alternating fresh producer sweeps over all four captures had median -wall/CPU/cgroup peak of 5.360 s / 4.263 s / 327.3 MiB before and -4.960 s / 4.357 s / 323.1 MiB after. Ranges overlap. One complete SDK session -per app/revision, 403 versus 413 calls, took 20.905 s / 19.039 s / 508.7 MiB -before and 23.426 s / 19.396 s / 462.8 MiB after; these are single observations -with different write coverage, not a speed or memory improvement claim. - -Catalog estimates (`cl100k_base`) were 8,630 / 9,408 tokens for NocoDB, -11,355 / 11,355 for Ghost, 12,162 / 12,648 for Metabase and 2,955 / 3,138 -for Mailpit. Arguments, instructions and text replies were also counted in -retained receipts; actual model usage, prompts and client rendering were not -measured. No token saving is claimed. - -Processes were fresh, OS caches warm or uncontrolled, on a shared Linux host. -Each task used one CPU, a 3 GiB early stop / 4 GiB hard limit and zero swap. -All eight recorded-data task groups exited zero, verified payload cleanup, -and observed no OOM or limit events. Payload-exit counters were verified; -final whole-scope counters were unavailable. Downloads, builds and runtime -identity preparation are excluded from task measurements. The current -four-capture verification does not requalify the earlier 50-capture totals. - -### Bulk-response follow-up qualification - -The follow-up at `f4bc513dd` classifies every returned bulk element and checks -all recorded calls with the shared serving renderer. Nested parsed-body leases -retain their enclosing scratch charge. Literal JSON IDs never pass through a -synthetic URL. The author's subsequent bulk regressions and measurement note -were retained when integrating `a319ba1af`; their historical census does not -measure this follow-up. - -A fresh four-capture producer sweep and real CLI/MCP replay retained every -previously matching read (109/114 initial, 302/358 session). NocoDB, Ghost and -Metabase plans and complete SDK calls equal `9942863b2`. Mailpit's text/plain -`ok` deletion acknowledgement is not parsed by the state JSON owner, so its -contents remain unknown and its write tool is now withheld as `body-unusable`. -The prior session already refused this deletion for a missing target; no -previously applied mutation was lost. Plain-text acknowledgement support remains -unverified rather than treating unknown contents as empty. The three other -captures retain the same eight applied mutations. - -This qualification-only sweep took 5.857 s wall / 5.413 s CPU / 329.9 MiB peak; -the complete SDK replay took 23.264 s / 22.298 s / 474.0 MiB. These single -observations are not pooled with the earlier performance cohort. Payload cleanup -and payload-exit resource counters were verified, with no OOM/limit events; -final whole-scope counters and actual model token usage remain unmeasured. - -## Review round on main `3d84215b`, 2026-10-24 - -Three automated review findings were fixed in `d0198389f` and `7c25ad4dc`: a create compares the other calls' request -bodies one at a time inside their parsing reservations, an echoed reference to a nested object stays pinned when the -plan cannot rebuild the object, and a sorted read view a later read contradicts is recorded and loses the -confirmations it gave. On macOS with Node v24.22.1 at `05566419e`, the static gates passed, `npx vitest run --project -domain --project services` passed (10,164, 6 skipped; the reference-lifetimes file whose worker crashes on main was -excluded) and the focused build, export, serve and analysis-view boundaries passed (10 files, 93). Over the same 50 -captures every write plan, session replay and served read equals `0895c89bc`'s: 187 write tools with 68 served, 68 of -68 smoke calls, 1,151 views, and 2,085 of 2,155 initial and 2,763 of 3,022 session reads matching. diff --git a/docs/specs/agent-environments/write-sorts-references-toggles/plan.md b/docs/specs/agent-environments/write-sorts-references-toggles/plan.md deleted file mode 100644 index 80cfd70c25..0000000000 --- a/docs/specs/agent-environments/write-sorts-references-toggles/plan.md +++ /dev/null @@ -1,11 +0,0 @@ -# Implementation plan - -1. **Sorted creates.** Placed creates whose confirming read was a whole listing in collection order may be placed - again; narrowing keeps the sorts a later listing follows and adds those its items show, the type's id field last. -2. **Listed references.** `referenceRule` reads a sent list of ids; `many` on the reference rule and its schema; - `referencedValue` maps each id; the create merge lets an empty reference agree and frees the members it fixed. -3. **Hidden bodies.** Scenario records give a request with a body Playwright did not expose, and no `Content-Type`, a - `bodySize` of 0. -4. **Toggles.** `toggledRules` turns a plan's `set` and a later call's opposite `set` into `toggle`; the rule's schema, - serving, later-call checks and the action verdict. -5. **Skill, tests and docs.** diff --git a/docs/specs/agent-environments/write-sorts-references-toggles/spec.md b/docs/specs/agent-environments/write-sorts-references-toggles/spec.md deleted file mode 100644 index 75e1fa64b3..0000000000 --- a/docs/specs/agent-environments/write-sorts-references-toggles/spec.md +++ /dev/null @@ -1,41 +0,0 @@ -# Serve sorted creates, listed references and toggles - -Issue: https://github.com/morluto/rea/issues/4933 - -## Outcome - -Over 148 recorded captures (the 130 measured before and 18 from a fresh recording round), #7539 withholds 302 of 694 -write plans. A short diagnosis of the largest clusters found three gaps REA could close: - -- **A create's sort learned too late.** Grafana lists folders by title. A recording's first scratch folder sorted - after the one seeded folder, so the plan placed creates last; the second sorted before the first, the list after it - contradicted the plan, and the update and delete after that went unconfirmed. -- **Lists of references.** Homebox creates an item from `parentId` and `tagIds` and answers with the parent and tag - objects. REA modelled a parent but not a list of tags, and a create that sent `null` and `[]` disagreed with one that - named both. -- **Toggles.** Miniflux stars and unstars an entry with a body-less `PUT /v1/entries/{id}/bookmark`. Chromium exposes - no body for it, which REA read as unusable, and an action flipping a flag back was taken to contradict the call that - set it. - -## Behaviour - -- **Sorted creates.** A create a whole listing in collection order placed last is placed again by a field a later such - listing shows it sorted by, the type's id field last. A sort an earlier such listing did not follow stays ruled out, - though the entity that showed it is gone. A create another read placed keeps its place. -- **Listed references.** A field holding one object per id a sent list names, in that order, is a `reference` with - `many`. A create that sent the member as `null` or `[]` and stored the field so agrees with one that named entities, - whichever create first showed the reference; - serving stores the entities a call names, or the empty value as that create did. A `null` id stays refused where - no recorded create sent one, and a call leaving the member out stores no field where the observed create showed - none. -- **Hidden bodies.** A scenario request whose body Playwright did not expose and that names no `Content-Type` sent no - body. -- **Toggles.** An item action a later call shows flipping back a boolean an earlier call set, when no call found it - already set, has a `toggle` rule: serving flips the field, refusing an entity that holds no boolean there. -- **Skill.** Recordings run an action twice in a row on one object, reading it back after each (skill 55). - -Plans and views that need none of this are unchanged. - -## Acceptance - -- No write of the 148 captures goes from served to withheld, and no view changes. diff --git a/docs/specs/agent-environments/write-sorts-references-toggles/tasks.md b/docs/specs/agent-environments/write-sorts-references-toggles/tasks.md deleted file mode 100644 index 3fb6efc9ea..0000000000 --- a/docs/specs/agent-environments/write-sorts-references-toggles/tasks.md +++ /dev/null @@ -1,11 +0,0 @@ -# Tasks - -- [x] Place a create again by the sort a later whole listing shows. -- [x] Learn and serve references a sent list of ids names, and let an empty reference agree. -- [x] Treat a hidden request body without a `Content-Type` as absent. -- [x] Learn, check and serve toggles. -- [x] Ask recordings to run an action twice on one object. -- [x] Add view, serving, record and unit tests. -- [x] Document the rules. -- [x] Measure the recorded captures. -- [x] Run static, formatting, documentation and test gates. diff --git a/docs/specs/agent-environments/write-sorts-references-toggles/verification.md b/docs/specs/agent-environments/write-sorts-references-toggles/verification.md deleted file mode 100644 index c499b2beca..0000000000 --- a/docs/specs/agent-environments/write-sorts-references-toggles/verification.md +++ /dev/null @@ -1,88 +0,0 @@ -# Verification - -Executed on macOS with Node v24.22.1 on this branch and on #7539 at `30e2a582`; the census and the base reproduction -were repeated after merging #7539 at `2817665d`, `174a0ff2`, `5691f97f` (which merges main with #7332) -and `3b800a10`. - -## Diagnosis - -Over 148 recorded captures, #7539 withholds 302 of 694 write plans. The largest clusters: Homebox item writes (36), -unconfirmed deletes (23), Grafana's feature-flag evaluation calls (15, which change no state), Linkding renumbering -bundles after a delete (7) and Miniflux's bookmark toggle (5). - -- **Grafana.** A fresh recording created "Scratch Pier 3", which the list after it showed after the one seeded folder, - then "Scratch Meadow Notes 4", which the list after it showed before the first, by title. The create plan had settled - on `last` when the first list confirmed it, so the second list contradicted it, and the folder update and delete - after it went unconfirmed. -- **Homebox.** Item creates send `parentId` and `tagIds` and answer with `parent` and `tags` objects. The recording - that created one item with neither (`null` and `[]`) and one with both was withheld: `tags` had no rule, and the - first create fixed both members to their empty values. -- **Miniflux.** `PUT /v1/entries/{id}/bookmark` sends no body and answers `204`. Chromium exposes no body for it and - the request names no `Content-Type`; REA read the body as unusable. Across the captures, every `POST`, `PUT` or - `PATCH` whose body was captured names `content-type` among its request header names (835 of 835). - -## Gates - -- `npm run -s check:fast`, `format:check`, `knip`, `scan:todos`, `docs:check`, `verify:test-discovery`, - `mcp-catalog:check` and `jscpd`: passed. -- `npx vitest run --project domain --project services`: 11,886 passed, 6 skipped, merged with `3b800a10`. An earlier run of the suite failed a - `SetupRegistrationPrewarm` runner test whose child process outran its 5-second timeout; alone it passes on this - branch and on #7539 (3.0 to 4.7 seconds). -- `npm run -s test:focused --` the environment build, export and serve CLI boundaries, the analysis-view CLI and MCP - boundaries and the environment serve MCP boundary: 7 files, 81 passed. `outputSchemaProfile`, `toolSchemaValidity`, - `mcpSchemaValidation`, `outputSchemaSemanticConstraints` and `analysisViewMcp`: 5 files, 54 passed; the compact - catalog stays under its frame. - -## Tests - -- View: a create placed last, then a create a later whole listing shows before it by title, learns `title` ascending - and its delete is served; an item create naming its parent and tags by id, after one naming none, learns - `reference` rules for `parent` and for `tags` (`many`) and is served; a body-less action two calls show starring - then unstarring an entry learns `toggle` and is served, and is not when its calls flip the flag one way only or a - later call leaves it unchanged. -- Serving: a create stores the parent and the tags its ids name, in the order sent; a create leaving out both, or - sending them as `null` and `[]`, stores `null` and `[]`; a tag the environment does not hold is refused, and so is a - `null` shelf where every recorded create named one; an entry the recording never starred flips on each call. -- Records: a hidden request body is absent when the request names no `Content-Type`, and stays unusable when it names - one. -- The nine behaviour tests fail on #7539 at `30e2a582`, `2817665d`, `174a0ff2`, `5691f97f` and `3b800a10`; the three that guard toggles and `null` ids - pass there too. - -## Write plans and views over recorded captures - -The 148 captures, built by #7539 and by this branch: 694 plans, 392 served and 399, both at `30e2a582` and after -merging `2817665d`, `174a0ff2`, `5691f97f` and -`3b800a10`. - -- No write goes from served to withheld, and no served plan changes. Newly served: Grafana's folder create, update and - delete in a fresh recording; Homebox's item create in another; Miniflux's bookmark toggle in three recordings. -- Five withheld plans explain more. Two Miniflux recordings learn the toggle but stay withheld: a list of starred - entries with no `order` parameter lists them by `published_at`, which REA answers in state order. Linkding's - unarchive learns its body-less call and stays `unconfirmed`, seen once. Two Homebox item writes learn their tag - references and stay withheld for other members. -- Views are unchanged: 3,188 views across the captures. - -## Review round - -Greptile's review of `4e777d28` raised five findings. Two were in this branch's code and are fixed: - -- A sort an earlier whole listing ruled out could come back from a later listing once the entity that ruled it out was - deleted, and a create's retry could adopt it. Each create now keeps the sorts its whole listings did not follow. -- A create sending a reference's member as `null` after a later create added the reference, the first having shown no - such field, was withheld: the empty-reference agreement now applies there too. - -Both tests fail on `4e777d28` and on #7539 at `174a0ff2`; the census is unchanged. The other three were in #7332's and -#7539's code: `308aebf0` (#7332), already here, covers the made-object count, and #7539's `174a0ff2`, merged here, -fixes the update default and the read clock spelling. - -Greptile's review of `f7c1bfe9` raised one more, fixed: once a later create sent a reference's member as `null`, a -served create leaving the member out stored `null`, though the create the plan observes left it out and stored no such -field. Serving now leaves the field out there, and still stores `null` for a call that sends it; the serving test fails -on `f7c1bfe9`. The census is unchanged. - -## Not verified - -- No environment was rebuilt and run with agents for this branch, and no recording was made with skill 55. -- The order an application gives a list read with no sort parameter (Miniflux's `published_at`) when it is not state - order. -- The rest of the Homebox cluster: `assetId` numbering and item updates; Linkding renumbering bundles after a delete. diff --git a/docs/specs/agent-environments/write-varied-calls/plan.md b/docs/specs/agent-environments/write-varied-calls/plan.md deleted file mode 100644 index 93e9255730..0000000000 --- a/docs/specs/agent-environments/write-varied-calls/plan.md +++ /dev/null @@ -1,9 +0,0 @@ -# Implementation plan - -1. **Update members.** `refinedBody` keeps only the required members a later update also sent. -2. **Numbered unless sent.** `sent` on sequence rules and their schema; the create merge adopts it for an echoed member - and a sequence from a call that left the member out; serving and replay take the sent value when there is one. -3. **Cleared by a PUT.** `explainUpdate` records a `PUT`'s left-out member cleared to an empty value as a default; - update refinement keeps defaults from later calls; `updatedFields` applies them to members a call leaves out. -4. **Update clocks.** `restampedFields` respells clocks from the first later read as it does nested clocks. -5. **Skill, tests and docs.** diff --git a/docs/specs/agent-environments/write-varied-calls/spec.md b/docs/specs/agent-environments/write-varied-calls/spec.md deleted file mode 100644 index 4458a29f52..0000000000 --- a/docs/specs/agent-environments/write-varied-calls/spec.md +++ /dev/null @@ -1,56 +0,0 @@ -# Serve writes whose calls send different members - -Issue: https://github.com/morluto/rea/issues/4933 - -## Outcome - -A fresh recording round of seven applications, main against #7332, showed the recording skill now varies what the two -creates and two updates of a type send, as it asks. Where the second call left out a member the first sent, REA -withheld the write: - -- **Updates.** An update plan required every member its first call sent and never narrowed that, so EspoCRM's second - contact update, which changed only an email address, was refused in both recordings of the branch. -- **Members numbered when left out.** Linkding stores a bundle's `order` as sent, or one past the others when a call - leaves it out. One create showed the first and another the second, which the create merge took as a disagreement. - -The same recordings and the 130 earlier captures showed two more update gaps: - -- **Whole-object PUTs.** Paperless clears a tag's, correspondent's or document type's `owner` when a `PUT` leaves it - out, and Homebox an item's `assetId`, so those updates were `unexplained-change`. -- **Update clocks read at another precision.** Vikunja answers a task update with `done_at` to the nanosecond while its - reads spell it to the second, so the read after the update contradicted it. - -The round also found two creates of EspoCRM contacts in one second, which a list sorted newest first shows in an order -the application breaks ties in. The skill now spaces creates. - -## Behaviour - -- **Update members.** A later update narrows the plan's required members to those every call sent. -- **Numbered unless sent.** A member one create sent and stored as sent, and another left out and the application - numbered one past the others, is a `sequence` with `sent`, in either order: serving stores the value a call sends, - else the next number, and a later call that sends it must have stored what it sent. The next number follows the - largest value any call took, a deleted entity's included, in replay as in serving. -- **Cleared by a PUT.** A field a `PUT` left out that the application cleared to an empty value (`""`, `null`, `false`, - `[]` or `{}`) is that member's default (`body.defaults`) when every call that left it out stored that value, as its - answer shows it or, where the answer leaves the member out, the read after it: serving stores it for an update that - leaves the member out. Calls that left it out and stored it otherwise withhold the plan. -- **Update clocks.** The state holds an update's clock as the first read of the entity after it spells the same instant - at a coarser precision in the same zone and separator, as it already does for nested clocks: replay and serving store - every update's clocks in the spelling of the read the plan keeps as `observation.read`, so a later update whose read - spells them otherwise contradicts the plan, while answers keep the update's own. A create's clocks stay as answered, - as serving makes them. -- **Skill.** Recordings leave more than a second between two creates, as between a create and its first edit. - -Plans and views that need none of this are unchanged. - -## Not covered - -- Vikunja numbers tasks per project. Creates into projects the recording did not list cannot be numbered, so its task - creates stay withheld. -- Linkding renumbers bundles' `order` after a delete, which no rule models. -- Homebox item creates expand sent tag ids into tag objects and pin `parentId`; they stay withheld. - -## Acceptance - -- No write tool of the recorded captures goes from served to withheld. -- The writes the diagnosis named are served where their recordings show nothing else against them. diff --git a/docs/specs/agent-environments/write-varied-calls/tasks.md b/docs/specs/agent-environments/write-varied-calls/tasks.md deleted file mode 100644 index 446d670a0d..0000000000 --- a/docs/specs/agent-environments/write-varied-calls/tasks.md +++ /dev/null @@ -1,11 +0,0 @@ -# Tasks - -- [x] Narrow an update plan's required members to those every call sent. -- [x] Serve a member the value a call sends, else the next number, when calls showed both. -- [x] Learn and serve the value a `PUT` stores for a member it leaves out. -- [x] Hold an update's clock as the read after it spells it. -- [x] Ask recordings to space creates. -- [x] Add view, serving and unit tests. -- [x] Document the rules. -- [x] Measure the recorded captures. -- [x] Run static, formatting, documentation and test gates. diff --git a/docs/specs/agent-environments/write-varied-calls/verification.md b/docs/specs/agent-environments/write-varied-calls/verification.md deleted file mode 100644 index 506b581e1f..0000000000 --- a/docs/specs/agent-environments/write-varied-calls/verification.md +++ /dev/null @@ -1,95 +0,0 @@ -# Verification - -Executed on macOS with Node v24.22.1 on this branch, on #7332 at `7d01a5d5` (main `5aa23c3d`), and on Ubuntu 24.04 VMs -with snap Chromium for the recording round. - -## Diagnosis - -Claude Code (`claude-sonnet-5-5`) built an environment of each of seven applications from the same prompt, once with -REA main `5aa23c3d` (skill 50) and once with #7332 at `7d01a5d5` (skill 53). Each bundle's write tasks ran with -`fireworks_ai/gpt-oss-120b` and `fireworks_ai/glm-5p3-flash`, which scored alike: - -| Application | Write tasks | Main | #7332 | -| ----------- | ----------- | ------- | ------- | -| Miniflux | 3 | 3/3 | 3/3 | -| Grafana | 2 | 2/2 | 2/2 | -| Vikunja | 3 + 2 | 0/3 0/2 | 1/3 2/2 | -| Paperless | 3 | 1/3 | 2/3 | -| Linkding | 2 | 0/2 | 2/2 | -| Homebox | 2 | 2/2 | 0/2 | -| EspoCRM | 3 | 1/3 | 0/3 | -| Total | 20 | 9/20 | 12/20 | - -Served writes were 14 and 25. Recorded again, Homebox and EspoCRM gave main 2/2 and 1/3 and #7332 2/2 and 3/3: the -first losses were the agents' runs, not REA. Built with both versions, none of the 18 recordings served fewer writes -with #7332 (44 and 53 in all). - -Replaying #7332's recordings with failing checks and refusals logged gave the causes this branch takes: EspoCRM's -second contact update left out `addressCity` and was refused for lacking a required member (both recordings); Linkding's -second bundle create left `order` to the application, which the merge took as disagreeing with the first create's -echo; Vikunja's task update stamped `done_at` to the nanosecond where the read after it showed seconds. Over the -earlier captures, 14 withheld updates were `PUT`s whose application cleared a member they left out (Paperless `owner`, -Homebox `assetId`). - -## Gates - -- `npm run -s check:fast`, `format:check`, `scan:todos`, `docs:check`, `verify:test-discovery`, `mcp-catalog:check` and - `jscpd`: passed. `npx knip` reports `staticFileUrlPath`, `ObjcClassImportBindingCoverage` and - `AndroidManifestComponentInventory`, as main `5aa23c3d` does. -- `npx vitest run --project domain --project services`: 11,694 passed, 8 failed (`appleApplication.test.ts`), which fail - the same way on main `5aa23c3d`. -- `npm run -s test:focused --` the environment build, export and serve CLI boundaries, the analysis-view CLI and MCP - boundaries and the environment serve MCP boundary: 80 passed. `outputSchemaProfile`, `toolSchemaValidity`, - `mcpSchemaValidation`, `outputSchemaSemanticConstraints` and `analysisViewMcp`: 54 passed; the compact catalog stays - under its frame. -- The seven new view and serving tests fail on #7332 at `7d01a5d5` and pass here. - -## Write plans over recorded captures - -The 130 captures #7332 measured and the round's 18 recordings, built by #7332 at `7d01a5d5` and by this branch: 694 -plans, 386 served and 398. No write goes from served to withheld and every view is unchanged. Newly served: - -- Paperless correspondent, document type and tag updates in four recordings, whose `PUT` clears `owner`. -- EspoCRM's contact update and Linkding's bundle create in #7332's recordings of the round. -- Grafana's folder update and delete in a fresh recording whose second update sent fewer members. -- Homebox's item update in the published capture, whose `PUT` clears `assetId`. - -Vikunja's task update reads back confirmed, but stays withheld: the task creates before it are not modelled (per-project -numbers), so their entities carry the creates' answer spellings into later reads. - -## Review round - -- Greptile's first review: a `sequence` with `sent` now accepts a value a later create sent, whichever create came - first; a default must agree with every update that left its member out, else the plan is withheld; and serving - stores an update's clocks as the update plan's read-back spells them (`observation.read`). Their four tests fail on - `6300ec80`. #7332's made-object clock check, merged in, has its test there. -- Gates as above: `domain` + `services` 11,699 passed, 8 failed (main's `appleApplication.test.ts`); focused boundaries - 80 passed; the five MCP schema files 54 passed. The census stays at 694 plans and 398 served, with no plan or view - changing. - -Greptile's review after main `21b19270` was merged in (`467ac78f`) raised three more, fixed: - -- A member a call left out and the application stored a fixed value for (`body.defaults`) is no longer turned into a - `sequence` with `sent` by a later call that left it out and got the next number. -- Serving stores an update's clock at a coarser read's precision from the answer's own digits, so an answer to the - nanosecond read back to the microsecond keeps its microseconds. -- A `PUT` that names a `reference` field's entity by its member supplies that field: it is not checked against, or - given, the default a `PUT` that left the field out showed, whichever of the two calls came first. - -Their tests fail on `467ac78f`, and the reference case with the clearing call first on `7030ca4d`. Gates pass but -`knip`, whose one finding main `21b19270` reports too; `domain` + `services` 12,046 passed; focused boundaries 82 passed; the five MCP schema files 55 passed. Over the 148 captures, main -serves 380 writes and this branch 392, with no plan or view changing from `467ac78f`. - -Greptile's review of `b56f8924` raised two more on numbered members, fixed: a member a call sent empty (`""`) is no -longer filled in for a call that leaves it out when a `sequence` with `sent` numbers it; and a later create the -application numbered at or below a value an earlier create sent (9 sent and deleted, then 2) no longer turns the echo -into a numbered `sequence`, since serving counts past every value a call sent. Their tests fail on `b56f8924`; gates -pass but `knip` (main's finding), `domain` + `services` 12,048 passed, and the census is unchanged. Greptile's next -review found that check counting values sent in other collections, which withheld a create numbered within its own -collection; the check now counts them in the sequence's scope, and its test fails on `d4922b3d`. - -## Not verified - -- No recording round ran with this branch, so its write tasks are not measured. -- The skill's spacing of creates. -- Vikunja per-project task numbers, Linkding's renumbering after a delete and Homebox item creates, which stay withheld. diff --git a/docs/specs/agent-environments/write-views/plan.md b/docs/specs/agent-environments/write-views/plan.md deleted file mode 100644 index 195b41a46a..0000000000 --- a/docs/specs/agent-environments/write-views/plan.md +++ /dev/null @@ -1,8 +0,0 @@ -# Implementation plan - -1. **Read-backs.** A create's observation looks for the first read of its entity before the next write; an item read's - fields and clock spellings are taken when it agrees otherwise, and the read observes; a list read adds fields only. The plan's observation records the - read and its shape, and serving merges the same objects. -2. **Sent members.** An update's sent member stored as a fresh clock after it sent back the held one is a `clock`; one - stored as the slug of another member stored as sent is a `slug`. -3. **Schema, tests and docs.** diff --git a/docs/specs/agent-environments/write-views/spec.md b/docs/specs/agent-environments/write-views/spec.md deleted file mode 100644 index 9e47ccfa1a..0000000000 --- a/docs/specs/agent-environments/write-views/spec.md +++ /dev/null @@ -1,47 +0,0 @@ -# Writes whose answers show the entity otherwise than reads, and whole-object updates - -Issue: https://github.com/morluto/rea/issues/4933 - -## Outcome - -Agents built environments from a prompt for five applications the prompt flow had never seen (Vikunja, Ghost, EspoCRM, -Paperless-ngx and Miniflux). Two write-model gaps withheld most of their creates and edits: - -- **A create's answer is another view of the entity than its reads.** Paperless answers a tag create without the - `document_count` its item read shows. EspoCRM answers a contact create without nine fields its item read shows. - Vikunja answers a label create with a partial `created_by` and clocks to the nanosecond, where reads show the full - user and whole seconds. Ghost answers a tag create without the `count` its list shows. The state built the entity from - the answer alone, so the read-back contradicted the create. -- **A whole-object update sends back what the application derives.** Paperless's UI sends the tag's old `slug` with a - new name, and the application slugs the name anew. Ghost's UI sends the `updated_at` it read, and the application - stamps a new one. The update was withheld as `unexplained-change`, or its first call's value was pinned so that later - calls conflicted. - -## Behaviour - -- **Read-backs.** When the first read of a created entity before the next write shows fields the create's answer lacks, - or spells its clocks to another precision, the observed entity takes them, and the plan records the read - (`observation.read`, with its shape). - - An item read that agrees with the answer otherwise lends its fields and its clock spellings (whole seconds of a - nanosecond clock, or microseconds of one), and no longer confirms the create. One that disagrees on another value, - or omits an answer field its item view renders, still checks the create, which it contradicts. - - A list read, which may show fewer keys of an object, only adds fields the answer lacks and still checks the create. - - A read that shows nothing new leaves the observation as it was and still confirms the create. - - Serving merges the same two recorded objects, so a served create answers in its answer's shape and stores the - fields of both. Generated clocks in the create answer retain that answer's recorded precision independently of - the stored read-back precision. -- **Restamped clocks.** An update member sent back as the clock the entity held, and stored as a fresh clock near the - call, is a `clock` rule, accepted with any value. -- **Re-derived slugs.** An update member stored as the slug of another member the call stored as sent is a `slug` rule - from that member, accepted with any value. -- **Compatible saves.** A call that echoes an already-derived slug or holds a clock in its own recorded second does - not conflict with a demonstrated derivation, in either call order. A slug derivation must reproduce earlier saves - as well; an explicit custom slug that disagrees still withholds the update. - -Plans and views that need none of this are unchanged. - -## Acceptance - -- The held-out recordings serve EspoCRM's contact create and Paperless's tag edit. -- A create whose item read-back disagrees with its answer on another value is still contradicted. -- No write tool of the 69 recorded captures goes from served to withheld. diff --git a/docs/specs/agent-environments/write-views/tasks.md b/docs/specs/agent-environments/write-views/tasks.md deleted file mode 100644 index 3090587da7..0000000000 --- a/docs/specs/agent-environments/write-views/tasks.md +++ /dev/null @@ -1,8 +0,0 @@ -# Tasks - -- [x] Take a create's read-back fields into its observation, and serve the same merge. -- [x] Learn restamped clocks and re-derived slugs for sent update members. -- [x] Add view and serving tests that fail without the change. -- [x] Document the observation member and the rules. -- [x] Measure the held-out and recorded captures. -- [x] Run static, formatting, documentation and test gates. diff --git a/docs/specs/agent-environments/write-views/verification.md b/docs/specs/agent-environments/write-views/verification.md deleted file mode 100644 index 23971dad13..0000000000 --- a/docs/specs/agent-environments/write-views/verification.md +++ /dev/null @@ -1,48 +0,0 @@ -# Verification - -Executed on macOS with Node v24.22.1 at `2f807efb` (main `8e6a9578` and this branch). - -## Gates - -- `npm run check` (build, typecheck, format, lint, typed lint, module boundaries, architecture guards) and - `npm run docs:check`: passed. -- `npx vitest run --project domain --project services --project adapters`: 17,624 passed, 25 skipped, 1 failed ("stops - Inspector target authorization after the current stat settles"), which fails the same way on main in this environment. -- `npm run test:focused --` the analysis-view, environment build, compare, export and serve CLI boundaries, the - analysis-view, environment bundle, serve and served-writes MCP boundaries, tool schema validity, output schema profile - and MCP schema validation: 12 files, 106 passed. -- The eight new view and serving tests fail on main and pass here. - -## Recorded captures - -The 69 recorded captures and the five held-out agent recordings, built as environment-state views on main and on this -branch: - -| Captures | Served on main | Served here | Served to withheld | -| ----------------------------------------- | -------------- | ----------- | ------------------ | -| 69 recorded | 132 | 132 | none | -| 5 held-out (20 write tools with a target) | 8 | 10 | none | - -- **Now served:** EspoCRM's contact create (its read-back adds nine fields the answer lacks) and Paperless's tag edit - (the stale slug is slugged anew from the name). -- **Past the read-back, withheld by other gaps:** - - Paperless's tag create: its list's `all` member lists every id, which state rendering does not model. - - Ghost's tag create and edit: the state does not list the created tags in Ghost's tag lists. -- **Still contradicted:** Vikunja's label create, whose item read-back shows a fully loaded `created_by` where the answer - showed a partial one. -- Three plans of the recorded captures (Airbyte, BookStack, PhotoPrism) now record a read-back; their served state is - unchanged. - -## Served write tasks - -The held-out round's write tasks, rebuilt from the same agent recordings with this branch, with -`fireworks_ai/gpt-oss-120b` and `fireworks_ai/glm-5p3-flash`: - -| Application | Main (gpt-oss, GLM) | This branch (gpt-oss, GLM) | -| ---------------------------------------------- | ------------------- | -------------------------- | -| EspoCRM contacts: create, update email, delete | 0/3, 0/3 | 1/3, 1/3 (create) | -| Paperless tags: create, rename, delete | 1/3, 1/3 | 1/3, 2/3 (rename with GLM) | - -- gpt-oss's rename did not apply. Its trajectory was not kept, so the cause is unconfirmed. A served `PUT` requires - every member the recorded call sent (about 14 here), and GLM sent them all. -- EspoCRM's served update accepts only the members its recording edited, so the email change is refused, as on main. diff --git a/docs/specs/analysis-views/cyclonedx-dependencies/plan.md b/docs/specs/analysis-views/cyclonedx-dependencies/plan.md deleted file mode 100644 index 1d71e4e320..0000000000 --- a/docs/specs/analysis-views/cyclonedx-dependencies/plan.md +++ /dev/null @@ -1,40 +0,0 @@ -# Implementation plan - -## Boundary and contract - -Add the `cyclonedx` view kind to `src/domain/analysisView/analysisViewRequest.ts`, -`analysisViewResult.ts`, `analysisView.ts` and `analysisViewParent.ts`, and to -the MCP contract in `src/contracts/analysisViewToolContracts.ts`. The CLI uses -the existing `inspect-analysis-view` request file. No new tool, provider or -parser is added. - -Implement `projectCycloneDxView` and the document schema in -`src/domain/analysisView/cyclonedxView.ts`. It reads only parsed parent Evidence -and derives the serial number from the parent Evidence digest. Package URL -encoding lives in `src/domain/packageUrl.ts` (`golangPackageUrl`, -`cargoPackageUrl`). Move the shared subject checks of the Go, Rust and CycloneDX -views into `src/domain/analysisView/metadataReportSubject.ts` so -`goBinaryView.ts` and `rustBinaryView.ts` use the same owner. - -## Incremental work and validation - -1. Define the view request, result and MCP contract, with a typed - unsupported-target error for other parents. -2. Implement Package URL encoding for Go module paths and crate names. -3. Project Go modules and Rust packages into components, properties, edges and - compositions with conservative identity, and refuse oversized documents from - a lower bound before building Package URLs or expanding edges. -4. Add domain, Package URL and service tests, CLI acceptance tests and MCP - boundary tests for Go and Rust parents. -5. Add `scripts/verify-cyclonedx-view.mjs` (`npm run verify:cyclonedx:view`) - to build real Go and `cargo auditable` fixtures and validate the documents - against pinned CycloneDX 1.6.1 schema files and a CycloneDX consumer. -6. Add the [CycloneDX guide](../../../guides/native/cyclonedx-view.md), link it from the CLI, - Go and Rust guides and the skill reference, and register its route. - -## Effects and compatibility - -The view reads retained Evidence only; targets are not read or executed, and -the Go and Rust readers are unchanged. -The verifier fetches schema files, checks their SHA-256 and installs its -validators only inside its temporary directory. diff --git a/docs/specs/analysis-views/cyclonedx-dependencies/spec.md b/docs/specs/analysis-views/cyclonedx-dependencies/spec.md deleted file mode 100644 index 60d9c8ad22..0000000000 --- a/docs/specs/analysis-views/cyclonedx-dependencies/spec.md +++ /dev/null @@ -1,61 +0,0 @@ -# CycloneDX dependency view - -## Problem and outcome - -REA recovers Go modules and Rust crates from shipped binaries but reports them -only in its own Evidence format, so a team feeding software composition tools -writes its own conversion, which can overstate what a binary proves. Add an -`inspect_analysis_view` / `inspect-analysis-view` kind `cyclonedx` that projects -one retained `inspect_go_binary` or `inspect_rust_binary` parent into one -deterministic CycloneDX 1.6 JSON document, with no new parser and no target -access. - -## Requirements - -- Accept only Go and Rust binary parents; other parents get a typed - unsupported-target error. Read no target bytes and do not repeat the analysis. -- Produce byte-identical output for the same Evidence: no timestamp, and a - `serialNumber` UUID derived from the parent Evidence digest. -- Describe the binary file in `metadata.component` with its file name and - artifact SHA-256, name the parent Evidence's recorded provider in `metadata.tools`, and - name a selected universal Mach-O slice with `rea:macho:*` properties. -- Identify Go modules as `pkg:golang/@` and crates.io - packages as `pkg:cargo/@`. Keep a Go `h1:` sum as the property - `rea:go:sum`, not a `hashes` entry. Make a module-path replacement the - component and keep the replaced module in `rea:go:original*` properties. -- Give local Go replacements, malformed module paths (empty, `.` or `..` - segments) and non-crates.io Rust sources no Package URL: use an indexed - `bom-ref`, keep the source in a property and leave identity unknown. -- Set `scope: excluded` only for Rust packages whose kind is `build`. Follow the - embedded Rust package indices for dependency edges, and relate - `metadata.component` to a recorded Rust root package with a dependency entry - and `rea:cargo:root`; a null root stays unknown. Record only main-module - edges for Go and mark them with `rea:go:graph`; omit the empty `dependsOn` - entry for a Go record that did not parse completely. Relate - `metadata.component` to a decoded Go main module with a dependency entry and - `rea:go:main`, even when that list is omitted; add neither without one. -- Report `compositions` as `incomplete` for partial coverage and `unknown` - otherwise, never `complete`. -- Keep artifact identity, the parent Evidence id, a view digest, coverage, - limitations and parent unknowns in the view, and copy unknowns and - limitations into the document as `rea:unknown` and `rea:limitation`. -- Do not page. Refuse a document over 1,048,576 bytes with a typed error that - names `export_evidence_bundle`, counted from a lower bound before Package URLs - are built or edges expanded. - -## Acceptance - -Domain, Package URL and analysis-view service tests cover Go and Rust -projection, the digest-derived serial number, Mach-O slice properties, -replacements, local and malformed paths, a local Rust source, build scope, -edges, compositions, unsupported parents and the size refusals. CLI acceptance -and MCP boundary tests return the view for Go and Rust parents. -`npm run verify:cyclonedx:view` projects a real Go module and a `cargo auditable` -binary, checks that each projection is deterministic, and validates both -documents against the CycloneDX 1.6.1 schema and `@cyclonedx/cyclonedx-library` -([verification record](../../../verification/cyclonedx-view-2026-10-31.md)). - -## Out of scope - -SPDX, VEX, vulnerability lookup, signing, merging several parents, other -artifact types, and any change to the Go and Rust readers. diff --git a/docs/specs/analysis-views/cyclonedx-dependencies/tasks.md b/docs/specs/analysis-views/cyclonedx-dependencies/tasks.md deleted file mode 100644 index fde0fe1f34..0000000000 --- a/docs/specs/analysis-views/cyclonedx-dependencies/tasks.md +++ /dev/null @@ -1,10 +0,0 @@ -# Tasks - -- [x] Define single-feature scope, contracts and implementation plan (`spec.md`, `plan.md`). -- [x] Add the `cyclonedx` view kind to the analysis-view request, result, parent and MCP contracts. -- [x] Implement Package URL encoding in `src/domain/packageUrl.ts`. -- [x] Implement deterministic projection, conservative identity, compositions and the size refusal in `src/domain/analysisView/cyclonedxView.ts`. -- [x] Share subject checks with the Go and Rust views in `metadataReportSubject.ts`. -- [x] Add domain, Package URL, service, CLI acceptance and MCP boundary tests for Go and Rust parents. -- [x] Validate real Go and `cargo auditable` documents with `npm run verify:cyclonedx:view` ([record](../../../verification/cyclonedx-view-2026-10-31.md)). -- [x] Add the CycloneDX guide, link it from the CLI, Go and Rust guides and skill reference; pass documentation checks. diff --git a/docs/specs/analysis/recoverable-budgets/plan.md b/docs/specs/analysis/recoverable-budgets/plan.md deleted file mode 100644 index 3f4af38a09..0000000000 --- a/docs/specs/analysis/recoverable-budgets/plan.md +++ /dev/null @@ -1,27 +0,0 @@ -# Implementation plan - -Use the existing named domain contracts and runtime settings owner. Prefer -per-call selection or cohesive resource policies where they express analyst -intent. Extend the runtime registry for ASAR listing admission, which already -flows through the shared archive admission owner. - -Implement independent owner slices: kernel metadata; GDB/Ghidra; desktop and -generated Python; Apktool; JavaScript precision; source maps; historical -captures; artifacts/managed/Rust; live capture; and producer limits. Coordinate -shared schema/configuration files centrally and review cross-slice changes -before broad checks. - -Remove superseded literals, representations and misleading recovery rather -than adding downstream prose repairs. Use the repository's Result/error algebra, -existing process supervision, and existing CLI/MCP registration paths. - -Validate focused boundaries first, then build, type/lint checks and generated -documentation consistency. Document unavailable native/provider lanes. No -performance claim or benchmark is required for correctness and policy ownership. - -For default calibration, compare representative completed tasks, including -recovery calls and complete replies. Record artifact identity, an independent -coverage oracle, estimated tokens, elapsed/CPU time and sampled process-family -memory. Separate artifact admission from delivery size; do not raise defaults -merely to make a large response fit. Keep unmeasured defaults explicitly -provisional rather than presenting inherited numbers as optimal. diff --git a/docs/specs/analysis/recoverable-budgets/spec.md b/docs/specs/analysis/recoverable-budgets/spec.md deleted file mode 100644 index eff7431370..0000000000 --- a/docs/specs/analysis/recoverable-budgets/spec.md +++ /dev/null @@ -1,69 +0,0 @@ -# Recoverable analysis budgets - -## Problem - -Several analysis workflows discard selected facts at fixed retention boundaries. -Existing runtime settings control only some resources. Increasing a deadline, -heap, or header allowance cannot repair an independent count or representation -limit. Desktop readers also duplicate policy in generated Python. - -Related discussions: [#6176](https://github.com/morluto/rea/issues/6176), -[#8434](https://github.com/morluto/rea/issues/8434), -[#5808](https://github.com/morluto/rea/issues/5808), and -[#8978](https://github.com/morluto/rea/issues/8978). - -## Requirements - -1. Preserve defaults unless representative completed-task measurements justify - a calibration; preserve caller selections, Evidence identity, omission, - unknown coverage, and cleanup authority. Changes must not grant new target - execution, injection, mutation, installation, or network authority. -2. Keep source validity independent of retention completeness. In particular, - an overlong but terminated kernel modinfo value is not malformed merely - because REA omitted its text. -3. Preserve exact exhaustion causes and give a next action addressing that - resource. GDB byte, record-count, and single-line limits must remain distinct. -4. Offer caller selection, continuation, or a bounded policy override for the - reviewed desktop projections, Apktool string tables, JavaScript semantic - precision, source maps, historical captures, provider capture retention, - artifact/managed representations, and producer admission/output limits. -5. Interpret each policy at its owner. Parent and child process checks consume - the same accepted values; generated Python consumes the desktop policy rather - than maintaining independent numeric defaults. Reject invalid values rather - than clamping or silently falling back. -6. Retain justified format, runtime, protocol, and ownership constraints. - Distinguish them from adjustable resource policy and external client budgets. - A larger delivery page cannot recover facts already discarded by a producer. -7. A runtime default update affects new accepted operations only. Explicit - per-call choices win. Report effective value, units, applicable control and - retry/restart scope without claiming active-worker telemetry. -8. Artifact recognition that cannot examine the selected carrier within its - accepted resource policy remains limited/unknown, never examined absence. - Preserve the exhausted cause through classification and retained probe facts. - Add cohesive per-call Bun, .NET bundle, Node SEA and Godot admission controls - at their producing owners, including preallocation and expansion checks. -9. Desktop task checks must admit the actual shipped seed representation under - the same selected view policy as the generated reader. Acquisition/export - budgets remain separate from runtime view admission. -10. Local source-location tracing offers opt-in compact retained delivery and - bounded access to mapping alternatives and embedded text. Preserve complete - Evidence, source identity, selected positions, unknowns and every equal-point - mapping; compact output must not repeat the raw map or entire source text. -11. Desktop SQLite projections share a configurable per-table encoded-view - allowance with generated readers and check it before retaining rows. Keep - the independent native SQLite value/record and worker-reply envelopes - explicit; a projected-view override does not raise those constraints. - -## Acceptance - -Exercise the exhausted boundary and its advertised repair through the strongest -practical public or production workflow. Use small lowered-budget fixtures when -they prove the same boundary without large allocations. Preserve independent -malformed-input, cancellation, identity, cleanup and fixed-protocol controls. -Record real-provider coverage separately from simulated process/protocol tests. - -## Non-goals - -Unbounded analysis, changing all numeric constants, treating format bit widths as -preferences, raising another application's client buffer/deadline, recovering -lost live observations retroactively, or adding new execution authority. diff --git a/docs/specs/analysis/recoverable-budgets/tasks.md b/docs/specs/analysis/recoverable-budgets/tasks.md deleted file mode 100644 index 3df5da27dc..0000000000 --- a/docs/specs/analysis/recoverable-budgets/tasks.md +++ /dev/null @@ -1,126 +0,0 @@ -# Tasks - -- [x] Separate source validity from retained modinfo fields. -- [x] Preserve GDB exhaustion causes and improve Ghidra value-flow recovery. -- [x] Consolidate desktop policy with emitted Python and expose caller controls. -- [x] Make Apktool string omissions reachable through caller selection. -- [x] Thread JavaScript semantic precision policy through actual evaluators. -- [x] Coordinate source-map parent, codec and fetch budgets. -- [x] Coordinate historical-capture parent and decoder budgets. -- [x] Expose independent artifact/managed admission and preserve partial Rust facts. -- [x] Expose capture retention policy without changing target authority. -- [x] Expose producer resource/output controls with exact recovery. -- [x] Integrate ASAR runtime setting, launch validation and setup forwarding. -- [x] Complete focused and integrated checks, update product docs and report gaps. -- [x] Repair reviewed managed CLI decimal parsing and selected-budget provenance. -- [x] Preserve Go/Rust owner-supplied exhaustion facts through summary views. -- [x] Preserve selected desktop policy separately from effective policy and bound - the emitted reader's initial probe during file growth. -- [x] Compare representative completed Flutter and source-map tasks before - calibrating defaults; retain reproducible inputs, oracles and receipts. -- [x] Preserve limited Bun recognition through inventory and probe facts. -- [x] Add per-call artifact admission policies and exact same-artifact recovery. -- [x] Align shipped desktop seed task admission with generated reader policy. -- [x] Add retained source-location summaries, paged matches and bounded text. -- [x] Verify compact point tracing on the pinned public maps and refresh native - provider recovery coverage; complete coordinated integration checks. - -## Validation - -Executed with the pinned Node 24.22.1 / npm 11.16.0 toolchain: - -- Runtime build and packaged skill generation through the focused-test - prerequisite. -- `npm run check:fast`: typecheck, lint and module boundaries pass. -- `npm run format:check`: passes. -- `npm run test:python`: bridge and analysis-efficiency suites pass. -- `npm run verify:test-discovery`: all 3,218 test files discovered exactly once. -- `npm run knip:production`: passes; advisory candidates were inspected rather - than removed without runtime/verifier ownership evidence. -- `npm run docs:generate` and `npm run docs:check`: pass, including the managed - conformance generator and README consistency checks. Removed obsolete ignored - managed-verifier argument bags instead of adding permissive budget fallbacks. - -Focused tests ran in batches across CLI, MCP, worker, parser, lifecycle and -provider boundaries. The primary 28-file run passed 726 tests, with six failures -and one host skip. Those failures were repaired and every affected file passed -its targeted rerun. The supplementary producer run passed 512 tests with five -failures and 120 platform skips; every affected file then passed its rerun. -The final capture-only run passed all 45 tests. This is a record of separate -executed runs, not an aggregate unique-test count or a claim that `check:pr` ran. - -Recovery checks include the same retained target after raised admission, -explicit selection reaching an omitted item, lower-budget cache re-admission, -worker-policy changes without stale results, generated Python parity, exact -exhaustion causes, and malformed/cancellation/cleanup controls. Integration -review also found and fixed XML/JSON view and historical-capture nesting budgets -that initially failed to reserve complete Evidence wrapper depth. - -The subsequent review fixes passed all 50 tests across six compiled acceptance, -CLI, MCP and emitted-Python boundary files. Typecheck and lint also passed after -those fixes. The source-map default and explicit smaller-budget recovery passed -all six compiled source-location CLI tests. The final formatting, type/lint, -generated-documentation and README consistency checks passed. - -The final follow-up adds per-call artifact admission, limited recognition, -shipped-seed policy agreement, bounded SQLite views and retained source-location -delivery. The 12-file compiled CLI/MCP run passed 56 tests and exposed four stale -fixed-limit expectations; those owner expectations were updated to structured -resource facts and all five rerun files passed 60 tests, including the shared -analysis-view integration suite. The SEA MCP matrix separately passed both full -and compact schema profiles with same-session lower/raise/lower admission. -The final SQLite worker/emitted-reader checks passed all four scenarios. These -are separate executed runs, not an aggregate unique-test count. - -Native capture qualification and the live same-Program Ghidra receipt -are linked from the [runtime verification report](../../../verification/runtime-analysis-settings.md). -The Python gate passed all 102 tests; architecture guards passed across 2,571 -source files. Formatting, type/lint, generated docs, README consistency and -production reachability checks passed. Reachability advisory candidates were -reviewed without deleting runtime/verifier-owned exports. The complete -`check:pr` gate was not run. - -## Integration onto current main for the PR - -Integrated onto main `8dfc47b107afc0cf4b53322a10b94c666fe9e18b`, preserving its -new desktop secret isolation, custom task readers, gzip support, Deno recognition, -signed bundle validation and chunked I/O. Incomplete Bun/SEA recognition now -keeps known native or other confirmed-pack observations with an explicit unknown -cause; it never caches unexamined data as absence. Main's malformed-directory -validation continues to take precedence over adjustable Godot retention. - -The fresh 11-file compiled integration run passed 118 tests with one host skip, -covering artifact admission, retained source locations, desktop seed/SQLite/CLI, -Go/Rust snapshots, runtime settings and setup forwarding. Separate owner checks -passed for new main's desktop secret/custom-reader/gzip and JavaScript -enumerable-copy/require-drain behavior. Source-map fetch-budget omission, empty -selection and partial selection now also remain distinct in browser Evidence. - -On this integrated branch, Python passed 102 tests; discovery found all 3,343 -test files exactly once; architecture guards passed across 2,696 source files. -The runtime/skill build, type/lint and generated-documentation checks passed. -The retained native Ghidra lane was rerun against the integrated code and again -confirmed live budget recovery, unchanged target bytes, Program continuity and -cleanup; see its [integration receipt](https://github.com/morluto/rea/blob/main/docs/verification/runtime-analysis-settings-ghidra-integration-2026-11-09.json). -Historical calibration and earlier receipts retain their original runtime pins; -they are not performance measurements of the integrated head. `check:pr` was -not run. - -## Verification limits - -The follow-up verified all packaged Java sources against installed Ghidra 12.1.4 -and exercised live operation/input/edge, native payload and deadline recovery on -the same Program with unchanged target bytes. The target was not executed. -The [dated native receipt](../../../verification/runtime-analysis-settings.md) -records exact versions, observations and verified cleanup; this does not qualify -Windows or every public transport/provider combination. Real local Frida and -LLDB producer-boundary budget checks also passed with explicitly controlled test -processes and confirmed cleanup. Full AgentEnv execution was not exercised; -desktop checks ran real SQLite workers and emitted reader helpers. Linux-only -native lanes and real Apktool, WABT, pwntools, pwndbg, sigrok and TShark remain -unverified. Source-owned codec/worker and simulated checks are labeled separately. -No native-provider performance improvement is claimed. Source-owned workflow -calibration measures a bounded public-artifact corpus, including complete -replies and recovery calls; it does not establish universally optimal defaults. -Ghidra function dossiers now reobserve accepted budgets while retaining the -native decompiler cache; the native latency cost of that change is unmeasured. diff --git a/docs/specs/apk-signature/spec.md b/docs/specs/apk-signature/spec.md deleted file mode 100644 index facf5f1126..0000000000 --- a/docs/specs/apk-signature/spec.md +++ /dev/null @@ -1,113 +0,0 @@ -# Inspect APK signature schemes (v1–v3.1) - -## Outcome and scope - -Answer, statically, **who signed a selected local APK, under which schemes, and -whether the declared content digests match the current bytes**. This closes a gap REA's own -Android inventory documents: "ZIP inventory cannot see the APK Signing Block, so -an empty signing array does not mean the APK is unsigned" -(`src/domain/android/androidApplication.ts`). - -Static format inspection within existing offline-artifact authority: no Android -code executes, no device or `adb`, no acquisition, no mutation. - -## Inspection contract - -- v1 (JAR) signing detected from the central directory as apksig selects it: - `META-INF/` entries at any depth ending in `.SF` or `.RSA`/`.DSA`/`.EC` - (case-sensitive), present only when a block has its matching `.SF`. -- Each paired v1 block's PKCS#7 `SignedData` read with bounded DER (BER - indefinite lengths accepted): every carried certificate, and per - `SignerInfo` the certificate it names by `issuerAndSerialNumber` or - `subjectKeyIdentifier` plus its digest/signature algorithm OIDs (apksig - resolves only `issuerAndSerialNumber`, so a `subjectKeyIdentifier` signer is - reported as declared, with a limitation, and is unknown to the posture's v1 - comparison). The signer - `certificate` goes through the same X.509 owner as v2/v3; it is `null` when - there is not exactly one `SignerInfo` or it names no carried certificate. A - block that cannot be read (including a local header that disagrees with - the central directory, as apksig checks) carries - `decode_error`, never an absent signer; so does a signer whose block, - `.SF` or `META-INF/MANIFEST.MF` name is duplicated. Duplicate names are - found among all central-directory entries, as apksig rejects the v1 - signature for any of them ("Duplicate entry"), and a limitation names the - first few (JSON-quoted, cut at 256 bytes with the stored length) and counts - the rest. Names are compared as apksig's Java UTF-8 decoding makes them, so - malformed bytes that decode to the same string are duplicates; where Zip64 - declares more records than the classic end-of-central-directory count that - apksig reads, duplicates only past those records are named separately. As - apksig does, the ZIP encryption flag is - ignored: the block is read and its decoding decides, with a limitation. -- The APK Signing Block located from the ZIP end-of-central-directory (Zip64 - followed) and framed into id-value pairs; v2, v3 and v3.1 signers decoded: - digests by signature-algorithm id, X.509 certificate DER, v3 min/max SDK, - additional attributes. -- Certificate identity as SHA-256 over the raw embedded DER (as apksig - hashes it); subject, issuer, serial, ISO 8601 validity and key algorithm via - the platform X.509 parser, each `null` when unreadable rather than guessed. -- The v3/v3.1 proof-of-rotation lineage (version 1) decoded into nodes: - certificate and the capability flags retained by that node's certificate. - Node signatures are not verified: the lineage is what the APK declares. A - lineage that cannot be decoded is reported with `decode_error`. -- Source-stamp presence and the declared stamp certificate (V2 block - preferred), or a `decode_error` when it cannot be read. -- Declared digest consistency: the v2/v3 content digest is recomputed for - SHA-256/SHA-512 and compared with each declared digest (`matches_apk`), - rolled up into `posture.self_consistent`. This is not a signature - verification: an attacker who changes the bytes can recompute and replace - the declared digest. Verity digests are not recomputed (`null`). -- A derived posture that keeps observation and declaration apart: - `schemes_agree_on_signer` compares each block scheme's signer certificate - _set_; `signer_change_declared_by_rotation` says whether every differing - signer appears in a declared lineage (`null` when identity or a needed - lineage is unknown); `v1_signers_match_block_signers` compares the v1 - signer set with what the lowest block scheme that has signers (v2, else - v3, else v3.1) expects: its signers, or the first (original) certificate - of a v3/v3.1 signer's declared lineage, as apksig requires; `null` when - either side's identity is unknown, with a limitation when the lineage - origin is the unknown side. Also `v1_only` (which cannot distinguish a v1-only APK - from one whose v2/v3 block was removed, since `X-Android-APK-Signed` is not - read), strongest scheme, rotation and source-stamp presence. -- Unknown is never reported as absent: a central directory that cannot be - walked, or whose record count does not consume its declared extent, is an - input error (v1 presence would otherwise be guessed); a signer without a - certificate makes agreement `null`; scheme errors name the scheme and reason. - -## Authority - -Declared identity and digest consistency, never trust: no cryptographic signature -verification, no certificate-chain or revocation evaluation, no authenticity -claim. A full verifier would be a separate scope decision. - -## Resource admission - -One bounded read of the archive (512 MiB cap, no-follow, change-detected). -Every ZIP-tail and signing-block size/offset is checked against the buffer. -Signers per scheme, v1 signers and lineage nodes are capped at 32 -(format-justified: one node per rotation, one v3 signer per SDK range; apksig -accepts at most 10 v1 signers); pairs and per-signer elements at 4096. Each v1 -block inflates to at most 1 MiB (bounded by the inflater, not by the declared -size), and its DER is read within 32 nesting levels and 65,536 elements, with -at most 32 certificates and 32 `SignerInfo`s. The result size is projected from decoded counts before -materialisation (an upper bound), and the exact serialized size of the result and its limitations is checked against -the 8 MiB output budget (authoritative); over-budget is a capacity refusal, not -truncation. The content digest is -computed at most once per algorithm in 1 MiB chunks. Peak memory is about -2.5 times the file size (the shared stable read keeps its chunks and then -concatenates them; 1.25 GiB measured for a 500 MiB APK, about 1.3 GB at the -cap) plus bounded decoding overhead; the digest passes run synchronously (a streamed positioned-read design is -a follow-up). - -## Verification - -`npm run verify:apk-signature` (Android SDK `apksigner` + `aapt2`, JDK -`keytool`): builds a real minimal APK, signs default v2+v3, v1-only (RSA and -EC), v1+v2+v3 on a legacy target, a rotated lineage with and without v1, rotation carried by v3.1, a source stamp and a copy with one changed byte, and cross-checks REA against `apksigner verify`, -`apksigner lineage` and `keytool -printcert -jarfile` through CLI and MCP in Evidence parity, with the advertised -schema validated. SDK-free unit and adapter tests cover framing (including Zip64 -and damaged archives), signer and lineage decoding with caps, the digest -algorithm (including a pooled-Buffer regression), set-based posture, the output -budget, and the provider's error surfaces. Independent review before handoff. - -Format reference: APK Signature Scheme v2/v3 — -https://source.android.com/docs/security/features/apksigning diff --git a/docs/specs/artifacts/deno-standalone/plan.md b/docs/specs/artifacts/deno-standalone/plan.md deleted file mode 100644 index 26636873f2..0000000000 --- a/docs/specs/artifacts/deno-standalone/plan.md +++ /dev/null @@ -1,56 +0,0 @@ -# Implementation plan - -## Boundary and contract - -Register `deno-standalone` in the existing artifact format owners: -`src/artifacts/artifactFormats.ts`, `ArtifactEmbeddedFormatProbes.ts`, -`ArtifactReader.ts`, `ArtifactReaderAdmission.ts`, `inventory/classify.ts`, -`inventory/scanReader.ts` and `extraction/ArtifactExtraction.ts`. Add the format -metadata and member roles to `src/domain/artifactFormatMetadata.ts`, -`artifactGraph.ts`, `artifactInspection.ts` and `evidenceSubject.ts`, and accept -the format in `src/contracts/artifactToolContracts.ts`. No new tool, provider or -bridge is added; the CLI and MCP changes are additive. - -Split the layout into owners under `src/artifacts/deno/`, following Deno -`cli/lib/standalone/binary.rs` and `virtual_fs.rs` at 2.9.8 with libsui 0.16.4 -section placement: - -- `DenoStandaloneLocation.ts` confirms the carrier name before claiming a file. - It reads ELF and note headers, walks PE resource directories to the named - payload through `src/domain/pe/peResourceLayout.ts`, and scans Intel trailers - to the slice start so an enclosing app wins over a stored executable. -- `DenoSectionLayout.ts` parses metadata JSON, the virtual-filesystem header, - specifier, redirect and remote tables, and the npm snapshot length. -- `DenoVirtualFs.ts` walks directories, files and symlinks into safe logical - paths with indexed fallbacks, using `ArtifactPathRegistry.conflicts` in - `src/resources/ArtifactPaths.ts` to avoid occupied paths. -- `DenoStandaloneAdmission.ts` binds the located carrier to the admitted file. - -`src/artifacts/DenoStandaloneArtifactReader.ts` projects members, metadata, -limitations and extraction regions through the existing stable artifact read and -safe output tree. - -## Incremental work and validation - -1. Define the format, member roles and contracts, preserving native inventory - for files with no confirmed carrier. -2. Implement carrier location for Mach-O, Intel trailer, ELF and PE, with - duplicate-section checks that reject unequal lengths before hashing. -3. Implement section parsing and the bounded virtual-filesystem walk with - indexed path fallbacks and remote specifier encoding. -4. Add the reader, inventory and extraction wiring with retained environment - and CA limitations. -5. Add synthetic layout, location, virtual-filesystem and reader tests, CLI - acceptance, filesystem boundary and MCP boundary tests. -6. Add `scripts/verify-deno-standalone.mjs` (`npm run verify:deno:standalone`) - for real Deno 2.9.8 host and cross-target compiles without execution. -7. Update the [usage guide](../../../deno-standalone.md), CLI guide, limits, - READMEs and skill references. - -## Effects and compatibility - -Inventory reads existing local files only; nothing is executed, injected or -downloaded. A `deno compile` executable that inventoried as a native binary now -reports `deno-standalone`, and a damaged section keeps the native format. There -is no runtime override for the named ceilings. Deno is a fixture producer for -the verifier only and is not installed by REA. diff --git a/docs/specs/artifacts/deno-standalone/spec.md b/docs/specs/artifacts/deno-standalone/spec.md deleted file mode 100644 index cefdd7b78d..0000000000 --- a/docs/specs/artifacts/deno-standalone/spec.md +++ /dev/null @@ -1,58 +0,0 @@ -# Deno compile executable inventory and extraction - -## Problem and outcome - -`deno compile` embeds an application's metadata, virtual filesystem and remote -modules in a section of a native Mach-O, ELF or PE runtime. REA inventories such -a file as an ordinary native binary, so the embedded application stays hidden. -Let `inspect-artifact` / `inspect_artifact` report the file as root format -`deno-standalone` and `extract-artifact` write its embedded files through the -existing safe output tree, without running the executable or the Deno runtime. - -## Requirements - -- Recognize the Deno 2.9.8 / libsui 0.16.4 carriers: a Mach-O `__SUI` section - named `d3n0l4nd`, an Intel Mach-O `<~sui-data~>` trailer, an ELF `PT_NOTE` or - `SHT_NOTE` owned by `SUI` with type `0x53554901` and descriptor name - `d3n0l4nd`, and a PE `RT_RCDATA` resource named `D3N0L4ND`. Other layouts, - including older eszip trailers, are `unsupported`. -- Report root metadata: carrier, embedding, entry point, argv, V8 flags, - permission options, unstable configuration, application name, self-extracting - marker, virtual-filesystem case sensitivity and npm snapshot byte length. Keep - the compiler version unknown, because the metadata JSON has no version field. -- Report each virtual file as one occurrence with logical path, size and SHA-256, - and its transpiled output, CJS export analysis and source map as separate - occurrences with the same `index` and their own `role`. -- Keep logical paths safe and unique: unsafe, deep, colliding or over-long names - (255-byte component, 512-byte path, including `.deno-*` suffixes) use indexed - `deno-vfs/` or `deno-remote/` paths and retain the original - spelling when it fits the name allowance. Percent-encode colons, backslashes - and control characters in remote specifiers and keep the original in - `source_path`. Never follow symlink targets. -- Retain `Metadata.env_vars_from_env_file` values and `ca_data` bytes in local - Evidence with their counts and byte lengths, say so in the inventory - limitation, and do not write them as extracted files. -- Report a virtual filesystem that cannot be listed as `vfs_listing: - unsupported` with unknown coverage while remote modules still extract. -- Claim a file only after confirming the carrier name. A malformed table before - confirmation keeps the native inventory; a confirmed section that cannot be - parsed fails closed. Side-by-side trailers with different bytes fail closed. -- Bound metadata, header, table, specifier, remote body, virtual-filesystem - record, depth, retained-unit and retained-byte work with named allowances, - documented in [Deno compile sections](../../../deno-standalone.md#deno-compile-sections). - -## Acceptance - -Synthetic fixtures cover every carrier, nested and side-by-side Intel trailers, -malformed and duplicate declarations, path indexing and encoding, unlistable -virtual filesystems, remote modules, npm snapshots and `ca_data`. Boundary tests -cover CLI inventory/extraction and MCP `inspect_artifact`. A real Deno 2.9.8 -compile of the host and Linux, Windows and Intel macOS targets is inspected and -extracted by `npm run verify:deno:standalone` without running the output -([verification record](../../../verification/deno-standalone-2026-10-31.md)). - -## Out of scope - -Running the target, decoding npm snapshots, downloading remote modules, -withholding embedded environment values by default, and layouts other than Deno -2.9.8. diff --git a/docs/specs/artifacts/deno-standalone/tasks.md b/docs/specs/artifacts/deno-standalone/tasks.md deleted file mode 100644 index 82db370369..0000000000 --- a/docs/specs/artifacts/deno-standalone/tasks.md +++ /dev/null @@ -1,10 +0,0 @@ -# Tasks - -- [x] Define single-feature scope, contracts and implementation plan (`spec.md`, `plan.md`). -- [x] Register `deno-standalone` in the artifact format, inventory, extraction, domain and tool contract owners. -- [x] Implement carrier location for Mach-O sections, Intel trailers, ELF notes and PE resources in `src/artifacts/deno/DenoStandaloneLocation.ts`. -- [x] Implement bounded section parsing and the virtual-filesystem walk with indexed and percent-encoded logical paths. -- [x] Retain environment-file values and CA bytes in local Evidence with inventory limitations, and keep them out of extraction. -- [x] Add synthetic layout, location, virtual-filesystem and reader tests, CLI acceptance, filesystem boundary and MCP boundary tests. -- [x] Verify real Deno 2.9.8 host and cross-target compiles with `npm run verify:deno:standalone` ([record](../../../verification/deno-standalone-2026-10-31.md)). -- [x] Update the usage guide, CLI guide, limits, READMEs and skill references; pass documentation checks. diff --git a/docs/specs/artifacts/maven-gradle-metadata/plan.md b/docs/specs/artifacts/maven-gradle-metadata/plan.md deleted file mode 100644 index 604d0a9093..0000000000 --- a/docs/specs/artifacts/maven-gradle-metadata/plan.md +++ /dev/null @@ -1,30 +0,0 @@ -# Plan - -## Shape - -The document formats are the only thing this feature knows, so the parser owns -them and everything else consumes its facts. - -- `src/domain/java/mavenGradleMetadata.ts` holds the schema and version-kind - helpers, so a reader and a test share one definition of the report. -- `src/java/MavenGradleMetadataParser.ts` decodes UTF-8 bytes into coordinates, - dependencies, and unresolved references. It is given bytes only; it never - opens a file. -- `src/java/MavenGradleMetadataProvider.ts` owns the file read and the - file-size budget. It is the boundary that turns bytes into a reported fact. -- `src/cli/mavenGradleMetadataCommands.ts` and the MCP registration are thin - adapters over the same service, so both surfaces report the same facts. - -## Order - -1. Pin the report in the domain schema so later steps cannot disagree about it. -2. Write the parser against tiny valid POM and Gradle `.module` fixtures. -3. Add the provider and the file-size budget. -4. Expose the CLI command, then the MCP tool, over the same provider. -5. Document the command and the report, and link the guide from both indexes. - -## Budget - -The only unbounded part of the read is the selected file size, so it is bounded -by `max_file_bytes` (default 1 MiB, ceiling 16 MiB). Exceeding it fails without -partial success. diff --git a/docs/specs/artifacts/maven-gradle-metadata/spec.md b/docs/specs/artifacts/maven-gradle-metadata/spec.md deleted file mode 100644 index 805acb783a..0000000000 --- a/docs/specs/artifacts/maven-gradle-metadata/spec.md +++ /dev/null @@ -1,45 +0,0 @@ -# Inspect Maven POM and Gradle module metadata - -This specification records an implementation increment and its original problem -statement. For current behavior and limitations, see the -[current guide](../../../maven-gradle-metadata.md). - -## Outcome - -Java dependency declarations often live outside a JAR, in a Maven POM or a -Gradle module-metadata file. Looking only at archive contents misses declared -coordinates, BOM imports, version ranges, exclusions, and variant constraints. - -`rea inspect-maven-gradle-metadata ` reads one explicitly selected POM or -`.module` file as static bytes and reports coordinates, dependency -declarations, BOM or platform notes, and unresolved property or parent -references, without running Maven or Gradle, resolving a tree, or contacting a -repository. The same facts are available through the -`inspect_maven_gradle_metadata` MCP tool. - -## Requirements - -- Classification is from content, not the suffix. -- Coordinates, packaging, parent, properties, dependencies, dependencyManagement, - exclusions, BOM imports, and version ranges are recorded as spelled. -- Gradle variants, rich versions, constraints, and `available-at` coordinates - are recorded as spelled; named module files are not fetched. -- Property spellings and missing parent-inherited coordinates remain explicit - unknowns. Interpolation and inheritance are not performed. -- Malformed XML/JSON fails closed. Unrecognized documents are unsupported. - Document types are rejected. No network is used. - -## Non-goals - -- Resolving a dependency tree or selecting versions. -- Running Maven or Gradle, executing plugins, or reading a credential store. -- Comparing two metadata snapshots. -- Associating metadata with a JAR or AAR. -- Activating POM profiles or applying packaging defaults. - -## Verification - -- Parser fixtures cover a parent POM with properties, a BOM import, an - exclusion, a version range, and a Gradle 1.1 module with library and platform - variants. -- CLI, MCP, and absolute-path boundary contracts have their own tests. diff --git a/docs/specs/artifacts/maven-gradle-metadata/tasks.md b/docs/specs/artifacts/maven-gradle-metadata/tasks.md deleted file mode 100644 index b2fa502f3d..0000000000 --- a/docs/specs/artifacts/maven-gradle-metadata/tasks.md +++ /dev/null @@ -1,11 +0,0 @@ -# Tasks - -- [x] Record the outcome, requirements and non-goals. -- [x] Add the domain schema, version-kind helpers and unresolved-reference shape. -- [x] Add the parser for Maven POM XML and Gradle module metadata JSON. -- [x] Add the provider with the file-size budget and its remediation. -- [x] Add the CLI command and register the MCP tool over the same provider. -- [x] Document the command, the report and the bounds. -- [x] Link the guide from `docs/README.md` and the VitePress index. -- [x] Add parser, CLI, MCP and absolute-path tests. -- [x] Run the static, formatting and focused test gates. diff --git a/docs/specs/artifacts/nuget-nupkg/plan.md b/docs/specs/artifacts/nuget-nupkg/plan.md deleted file mode 100644 index a7dcc601b9..0000000000 --- a/docs/specs/artifacts/nuget-nupkg/plan.md +++ /dev/null @@ -1,30 +0,0 @@ -# Implementation plan - -## Boundary and contract - -Add the result and input schemas in `src/domain/nuget/nupkg.ts` and the tool -contract in `src/contracts/nuget/nupkgToolContracts.ts`, registered with the -tool families, effects and capability declarations. The application port and -service live in `src/application/nuget/`; the service admits one absolute path -and delegates to the parser. The CLI command is `src/cli/nugetNupkgCommands.ts`. - -`src/nuget/NugetNupkgParser.ts` owns ZIP enumeration, `.nuspec` selection and -decoding, member roles and limitation wording. Capacity and format failures are -typed in `src/nuget/NugetNupkg.errors.ts`. - -## Incremental work and validation - -1. Define the domain schema, tool contract and capability registration. -2. Implement bounded ZIP enumeration that stops once the entry allowance is - exceeded, then OPC and root `.nuspec` selection. -3. Decode identity, license, repository and dependency groups with DOCTYPE - rejection. -4. Add the service, composition and CLI wiring. -5. Add parser, domain and service tests with synthetic fixtures in - `src/nuget/NugetNupkg.fixture.ts`. -6. Update the usage guide, CLI guide, README and skill references. - -## Effects and compatibility - -The tool reads one existing local file. Nothing is executed, restored or -downloaded. The change is additive to the CLI and MCP surfaces. diff --git a/docs/specs/artifacts/nuget-nupkg/spec.md b/docs/specs/artifacts/nuget-nupkg/spec.md deleted file mode 100644 index b4f987868e..0000000000 --- a/docs/specs/artifacts/nuget-nupkg/spec.md +++ /dev/null @@ -1,45 +0,0 @@ -# NuGet package inspection - -## Problem and outcome - -A `.nupkg` is a ZIP with a `.nuspec` manifest, but REA has no owner that reads -package identity, dependency groups or NuGet folder roles. Let -`inspect_nuget_nupkg` / `inspect-nuget-nupkg` report that metadata and a -contents inventory for one selected local file, without restoring the package, -executing anything in it or contacting a NuGet feed. - -## Requirements - -- Report the artifact path, SHA-256 and byte length. -- Select the `.nuspec` from a unique OPC `_rels/.rels` relationship with Type - `http://schemas.microsoft.com/packaging/2010/07/manifest` when that target exists, otherwise from a unique root - `.nuspec`. Missing, ambiguous or malformed manifests succeed with the ZIP - inventory, `identity: null` and an explicit limitation. -- Report the `identity`, `license`, `repository` and `dependency_groups` - declared in the `.nuspec`. Normalize the named license types `expression` - and `file` case-insensitively. Without any ``, ungrouped dependencies - form a group with `target_framework: null`. Beside groups, in any - `` element, they are omitted with a limitation that counts - them, as NuGet's restore-time reader ignores them. Version ranges stay text; - restore results are unknown. -- List file ZIP members with sizes, an `encrypted` flag and a path-derived - NuGet folder `role`. `[Content_Types].xml`, `.rels` parts, and members under - `_rels/` or `package/` are OPC packaging parts. Omit directory markers. -- Bound the file size, ZIP entry count and `.nuspec` bytes with named - allowances. Enforce the entry allowance while enumerating the ZIP. Refuse a - file that is not a valid ZIP without a partial inventory. -- Reject a DOCTYPE in the `.nuspec` and report it as a limitation. - -## Acceptance - -Synthetic fixtures cover a complete package, ungrouped dependencies and -missing, ambiguous and malformed manifests. Tests cover non-ZIP refusal, the -entry, file and `.nuspec` allowances, service path admission, and the domain -schema. Limitation delivery is asserted through the parser-owned -`NUPKG_LIMITATIONS` wording. The [usage guide](../../../guides/managed/nuget-nupkg.md) -documents the result and limits. - -## Out of scope - -Restore-time asset selection, signature verification, feed lookups, extraction -of package members and any judgment of package safety. diff --git a/docs/specs/artifacts/nuget-nupkg/tasks.md b/docs/specs/artifacts/nuget-nupkg/tasks.md deleted file mode 100644 index 2c1ac72218..0000000000 --- a/docs/specs/artifacts/nuget-nupkg/tasks.md +++ /dev/null @@ -1,9 +0,0 @@ -# Tasks - -- [x] Define single-feature scope, contracts and implementation plan (`spec.md`, `plan.md`). -- [x] Add the domain schema, tool contract and capability registration. -- [x] Implement bounded ZIP enumeration and `.nuspec` selection in `src/nuget/NugetNupkgParser.ts`. -- [x] Decode identity, license, repository and dependency groups with DOCTYPE rejection. -- [x] Wire the service, composition and CLI command. -- [x] Add parser, domain and service tests with synthetic fixtures. -- [x] Update the usage guide, CLI guide, README and skill references. diff --git a/docs/specs/artifacts/release-exposure/plan.md b/docs/specs/artifacts/release-exposure/plan.md deleted file mode 100644 index 2da1841360..0000000000 --- a/docs/specs/artifacts/release-exposure/plan.md +++ /dev/null @@ -1,42 +0,0 @@ -# Implementation plan - -## Boundary and contract - -`src/domain/releaseExposure.ts` owns the report schema, check ids, statuses, -severities and read allowances. `src/domain/releaseExposureCredentialMarkers.ts` -owns the provider-prefixed marker rules. `src/artifacts/ReleaseExposureReader.ts` -owns the bounded scan of the selected artifact and its members. -`src/application/releaseExposure/ReleaseExposureService.ts` composes the existing -owners through `ReleaseExposurePort` and decides each check from their results. -`src/contracts/releaseExposureToolContracts.ts`, `src/cli/releaseExposureCommands.ts` -and its `audit_release_exposure` binding in `src/server/createServer.ts` are thin adapters over the same -service. - -## Changes to existing owners - -- `inventoryArtifact` gains optional `acquisitionLimits`. Only this audit sets - them. Exhausting one keeps a partial inventory with unknown coverage. Other - callers are unchanged. -- `src/domain/binaryTarget.ts` adds `inspectPeCodeViewFromBuffer`, which - separates absent CodeView records from incomplete parsing. - `parsePeCodeViewFromBuffer` keeps its behavior on top of it. -- `src/artifacts/inventory/classify.ts` exports - `classifyEmbeddedExecutablePackage`, so the audit recognizes a packaged - executable with the same probes as inventory. -- Declared integrity uses `record-and-continue` for this audit only. - -## Change detection - -Every file read is bound to its inventoried digest. A file or container whose -bytes differ from inventory at read time adds a change diagnostic and leaves the -affected checks `unknown`. An unpacked ASAR member is read from its companion -on disk rather than the captured archive, so its bytes are compared with the -member digest that inventory recorded, and findings cannot mix an inventoried -release with bytes written later. Native images carry their -inventory digest into the Go, Rust and fuse reads. - -## Effects and compatibility - -The tool is read-only, local and additive to the CLI and MCP catalogs. It adds no -provider and no runtime dependency. `verify:release-exposure` installs -`@electron/fuses` into a temporary prefix when it runs. diff --git a/docs/specs/artifacts/release-exposure/spec.md b/docs/specs/artifacts/release-exposure/spec.md deleted file mode 100644 index 73dd59802e..0000000000 --- a/docs/specs/artifacts/release-exposure/spec.md +++ /dev/null @@ -1,77 +0,0 @@ -# Release exposure audit - -Pull request: https://github.com/morluto/rea/pull/8525 - -## Problem and outcome - -REA can show what static analysis recovers from a shipped application, but a -developer who wants that answer for their own release has to run several tools -and combine the results by hand. Add one read-only audit that reads a single -shipped artifact through the existing readers and reports, per named check, -what was observed, so a team can review or gate a release before it ships. - -## Requirements - -- Accept one local `.app` bundle, install directory, ASAR or single executable - through `audit_release_exposure` (MCP, absolute path) and - `rea audit-release-exposure` (CLI, path resolved against the caller's working - directory). Both adapters return the same report. -- Report a fixed set of checks, each with a stable id, a status of `exposed`, - `not_observed`, `not_applicable`, `unknown` or `not_assessed`, the observation - behind it, its locations and fixed remediation text. Severity is `null` unless - the status is `exposed`. -- Report no pass verdict, score or grade. The report states that it does not - establish that an application is secure, and `unknown` and `not_assessed` - counts stay beside the findings. -- Compose existing owners: artifact inventory, Electron fuses, Go build info, - cargo-auditable metadata, PE CodeView, embedded package classification and - source-map parsing. Do not reimplement their parsing. -- Never execute, modify or rewrite the artifact, and make no network request. -- Bound every read. Inventory stops at 65,536 entries or 2 GiB of hashed bytes. - Text, source-map and packaged-image reads have separate allowances reported - under `coverage.allowances`; skipped members are listed under - `coverage.omitted`. An exhausted bound leaves the affected checks `unknown`. - An unpacked ASAR companion is compared with its inventoried digest only when - it ends within the read allowance; one past the allowance is not read further - to finish the digest and stays over its allowance, unverified. -- Fail toward `unknown`: a read that could not be completed, a file or member - whose bytes no longer match the inventoried digest, an unresolved or oversized - source map, or missing metadata never becomes `not_observed`. - Ordinary UTF-8/UTF-16 text and source maps that cannot be decoded completely - remain unassessed; observations recovered from their decoded text are retained. -- For `text.credential_markers`, report the rule id and location only. Matched - bytes, previews, lengths and hashes of matched bytes are omitted. Source-map - text is counted and then dropped. -- Without `--fail_on`, the CLI exit status reflects only whether the audit - finished. With `--fail_on high|medium|low`, a completed audit exits `3` when an - `exposed` check meets that severity. A tool failure exits `1`. -- A declared integrity value that disagrees with the bytes is recorded as a - limitation and the audit continues. -- Cancellation during a composed owner returns the typed cancellation error with - the partial report attached. - -## Acceptance - -- Domain tests cover status aggregation, severity, `--fail_on` thresholds and the - absence of a verdict. -- Reader tests cover source maps with and without `sourcesContent`, inline - `data:` maps, HTML and SVG script loading, debug companions, credential markers - in text members and binary plists, UTF-16 and NUL handling, read allowances, - same-name package members, packaged native images and changed bytes after - inventory, including an unpacked ASAR companion replaced after inventory and - an oversized companion that is not read past its allowance. -- Service tests cover Electron fuse decisions, Go and Rust metadata, partial - inventory and cancellation with a partial report. -- CLI and MCP return the same report; `--max-file-bytes` accepts the documented - decimal token form. -- `npm run verify:release-exposure` audits real fixtures, recorded in - [the verification record](../../../verification/release-exposure-2026-10-31.md). -- The [release exposure guide](../../../release-exposure.md) documents current - behavior and limitations. - -## Non-goals - -Obfuscation, stripping, signing, active protection, modifying the artifact, -running the target, network calls and a security verdict. `native.hardening`, -`macho.hardened_runtime` and `android.manifest` stay `not_assessed` and name -their next probes instead. diff --git a/docs/specs/artifacts/release-exposure/tasks.md b/docs/specs/artifacts/release-exposure/tasks.md deleted file mode 100644 index 7f372b1ff4..0000000000 --- a/docs/specs/artifacts/release-exposure/tasks.md +++ /dev/null @@ -1,10 +0,0 @@ -# Tasks - -- [x] Define the report contract, checks, statuses and read allowances (FR: report, bounds). -- [x] Add the bounded reader and the service that composes existing owners (FR: compose, fail toward unknown). -- [x] Add CLI and MCP adapters with `--fail_on` exit status 3 (FR: exit status). -- [x] Add domain, reader and service tests listed under acceptance. -- [x] Verify real fixtures with `npm run verify:release-exposure`. -- [x] Document current behavior in the release exposure guide. -- [x] Accept decimal `--max-file-bytes` tokens through `cliDecimalField`. -- [x] Bind unpacked ASAR member reads to their inventoried digests. diff --git a/docs/specs/desktop-app-environments/README.md b/docs/specs/desktop-app-environments/README.md deleted file mode 100644 index cdfdd851a7..0000000000 --- a/docs/specs/desktop-app-environments/README.md +++ /dev/null @@ -1,86 +0,0 @@ -# Desktop application environments - -This roadmap records the planned implementation sequence. It does not establish -current completion, review approval or verification status. For current workflows, -see [desktop capture](../../desktop-application-capture.md), -[build computers](../../desktop-build-computer.md), -[tasks](../../desktop-application-tasks.md) and -[export](../../desktop-application-export.md). Individual verification records -retain their original scope and limitations. - -Goal: REA turns an application installed and used on a Linux desktop into an -agent environment's computer application. The real application installs into -a computer image, launches to ready, exposes reset, load and get over its own -state, and ships with tasks graded through that state. - -The planned sequence was one PR per step: - -1. Pin the real agent environment lane to the framework release that carries - the computer application contract. -2. [Capture](capture/spec.md): launch the application on the user's desktop - and record its inventory, windows and home-directory state at checkpoints. -3. [State view](state-view/spec.md): decide which paths are the application's - state and read their formats into a typed JSON view. -4. [Export](export/spec.md): write the computer application class, environment - card, skill and seed. -5. Verification inside an agent environment computer: put, boot, ready, reset - equals the seed, grader checks. -6. [Tasks](tasks/spec.md): an agent writes a prompt and declarative checks - from the observed change, REA keeps the task when the checks fail on the - seed and pass on the captured end state, and a run of the bundle measures - an agent's solve rate. -7. Three applications end to end: Mousepad (plain files), GnuCash saving to - SQLite, and Joplin (Electron, SQLite). -8. [Vendor packages](vendor-packages/spec.md): closed-source applications from - a vendor apt repository, with its verified signing key and the packages of - the libraries they load, starting with Typora. -9. [Vendor .deb files](vendor-deb-files/spec.md): closed-source applications - installed from a downloaded `.deb` file, which the computer downloads from - an operator's URL and checks by its captured SHA-256, starting with - VariCAD. -10. [Document views](document-views/spec.md): documents saved as zip - archives (FreeCAD, OpenDocument, Office Open XML, EPUB) read as their - entries, checked by name rather than position, namespaced XML included, - and numbers compared within a tolerance, starting with FreeCAD. -11. [Capture for building](capture-for-building/spec.md): one capture makes - the seed and then the change, at checkpoints the export and the task - draft are told; apt lists from a user-space `apt-get update` are found; - the application does not inherit the computer's control token; and the - bundle holds neither the capture host's name nor its user's. -12. [Build computer](build-computer/spec.md): an agentenv computer REA keeps - up from a request or a bundle, with REA installed inside for building, - driven through REA's MCP tools while an agent builds the environment. -13. [Build and witness](build-witness/spec.md): REA's capture, task draft - and export run inside the build computer with acknowledged checkpoints, - the bundle comes back to the host, and the task is witnessed live in a - fresh computer of it: seed, edit, near miss and reset, recorded. -14. [XML text checks](xml-text-checks/spec.md): XML whose DOCTYPE only names - its DTD read as XML, starting with AbiWord, and checks of an element's - whole text across the runs an app splits a paragraph into. -15. [Download installs](download-installs/spec.md): applications no package - offers, from their project's AppImage or tarball pinned by URL and - SHA-256, unpacked under `/opt/rea-apps` by the build computer and the - export alike, starting with FreeCAD. -16. [Readers](file-readers/spec.md): checks of a file REA reads as binary, - such as GIMP's `.xcf` or Blender's `.blend`, through the app's own - headless command, run in the computer on a private copy of the file. -17. [Screen judges](screen-judge/spec.md): checks of state no file shows, - such as a calculator's result, by a model judging a screenshot against - the build's labelled seed and end screenshots. -18. [Secrets typed unseen](build-secrets/spec.md): a password or key the - person keeps in a file on the build host, typed by its handle, which no - result, log, record or exported bundle holds; sign-in and licence state - withheld from the seed and supplied at run time, seeded only with the - person's recorded consent; known handle values are checked explicitly. -19. [Several tasks](several-tasks/spec.md): one capture yields several - tasks, each checked at its own end checkpoint and, when one was taken, - failing at its near miss; the eval lists them all and each is witnessed - on its own fresh computer. -20. [Task difficulty](task-difficulty/spec.md): a build tool solves a - bundle's task in fresh computers for a model, 3 times and 2 more unless - they passed none or all, within a budget, and records its band, cost, - turns and failures per check in the bundle. - -Version 1 covers Linux with X11, applications whose state lives in files or -SQLite under the home directory, and real applications from public packages. -It uses the user's real state and keeps everything local. diff --git a/docs/specs/desktop-app-environments/build-computer/plan.md b/docs/specs/desktop-app-environments/build-computer/plan.md deleted file mode 100644 index 35e1f6a7d1..0000000000 --- a/docs/specs/desktop-app-environments/build-computer/plan.md +++ /dev/null @@ -1,21 +0,0 @@ -# Plan - -1. Domain: the build request schema and the bundle renderer beside the - export's renderers, reusing their env.toml, apt source, install script, - smoke task and naming helpers; the action schema, per-action argument - admission and key translation. -2. Helper: `bridge/agentenv/computer.py`, shipped in the package, with its - exit statuses (0 torn down, 1 left up, 2 nothing came up). -3. Adapter: `src/desktop/AgentEnvComputer.ts` finds the runner's Python, - spawns and supervises the helper, reads the handshake, waits for readiness, - holds the driver MCP session and the token, serves the recording hooks and - releases the computer, removing its containers by name and label when needed. -4. Application: `DesktopBuildComputers` renders request bundles into a private - folder, starts and holds computers, forwards actions with their log, and - closes them, keeping unconfirmed ones for retry. -5. MCP: contracts, effects, the `application` family, the capability service, - registration, image pass-through in `ToolResultDelivery`, and the MCP-only - list for CLI parity. -6. Docs and tests: the guide; renderer and key tests; boundary tests with a - fake driver and a fake `agent_env` behind the real helper; an opt-in real - test with agentenv and Docker. diff --git a/docs/specs/desktop-app-environments/build-computer/spec.md b/docs/specs/desktop-app-environments/build-computer/spec.md deleted file mode 100644 index 02d594a912..0000000000 --- a/docs/specs/desktop-app-environments/build-computer/spec.md +++ /dev/null @@ -1,77 +0,0 @@ -# Build computer - -## Outcome - -An agent that builds a desktop app environment, such as Claude Code, drives a -real agentenv computer through REA's own MCP tools: REA keeps the computer up, -forwards each computer-use action to its driver and returns the driver's answer, -screenshots included, then tears the computer down. The computer starts from a -request (the app's install source and desktop entry), with REA installed inside -it for building, or from an existing bundle folder. - -## Requirements - -- MCP-only session tools in the `application` family: `start_build_computer`, - `act_on_build_computer` and `close_build_computer`, held by one owner per - server and closed with it. -- Lifecycle: one helper process per computer, `bridge/agentenv/computer.py`, - spawned with REA's owned-process supervision and run with the agentenv - runner's Python, found from the absolute `REA_AGENT_ENV_COMMAND`. It calls - `run_bundle(, tasks=["smoke"], keep=True, emulate=False, - sandbox="local")`, prints one JSON line (base URL, MCP URL, control token, - sandbox id) on a private copy of stdout, sends everything else to stderr, - and tears down on stdin EOF, SIGTERM or SIGINT. REA waits for - `GET /agentenv/ext/computer-ready/status` with the token, then holds one MCP - session to the driver's `/mcp`. -- Teardown: closing stdin, then SIGTERM, then the process group. When the helper - does not confirm the teardown, REA removes the containers of the exact - sandbox id it reported, the one named `agent-` and any labelled - `agentenv.sandbox=`, through the absolute `REA_DOCKER_COMMAND`. An - unconfirmed teardown keeps the computer listed for a retried close. - Cancelling a start stops the helper, whose deploy tears down what it began; - a helper that reported its failure finishes its own teardown first. The owner - holds each start from its helper's spawn: a failed start whose teardown is - unconfirmed stays held under the `computer_id` its error names, and shutdown - cancels and joins starts in progress before closing every computer. -- Diagnostics: the helper's stderr is kept as its last 16 KiB, through the - shared supervisor's tail retention, so a failed build reports its error - rather than its first package downloads. -- The control token never appears in a result, an error or a log; the helper's - stderr is redacted of it. -- Build bundle from a request: the app from the Ubuntu archive, with up to 16 - extra archive packages beside it, an apt repository with its key file, or a - `.deb` URL with its SHA-256, dependencies and architecture, rendered with - the export's install shapes and Python helpers; `Launch(at="demand")` through - `gtk-launch`; no seed and no data hooks. When the request sets `electron`, the - install rewrites that desktop entry's command with the export's launch policy - (`--no-sandbox` right after the program, unless the command already has it) - before `gtk-launch`; REA in a build-only layer, with Node.js 24.22.1 downloaded per - architecture and checked, and REA's payload a parameter: a local archive - shipped in the environment folder (`REA_BUILD_COMPUTER_REA_ARCHIVE`) or, - later, a released download. -- Actions: one tool with an `action` (screenshot, click, drag, scroll, type, - key, wait) and the driver's own arguments, passed through, frame or `norm` - coordinates included. Common key spellings become W3C names. An argument the - action does not take is refused before sending. Results carry the driver's - content blocks unchanged after REA's JSON, which `ToolResultDelivery` measures - against the response budget as a whole; a response over it is refused with - REA's own result, `computer_id` included, kept in the error. The first - screenshot takes `region`, `format` and `quality`. Each action is logged per - computer within a fixed allowance: the latest 256 actions in 256 KiB of JSON, - oldest dropped first, each string argument cut to 1 KiB and each list to 64 - items with the cut arguments named, beside a count of every action and the - index of the last applied action of each kind. -- Recording hooks, internal: start and end `computer-recording/v1` under REA's - request id, and fetch the segments through the driver's `data/get` one per - request, each answer read within its segment's base64 size and the segment - checked against the manifest's size and SHA-256, before teardown. A - recording over the caller's allowance, a quarter of the V8 heap by default, - is refused before any read. - -## Non-goals - -- Capture checkpoints, the apt lists folder, the capture's launch environment - and the host scrub, which a sibling change owns. -- The witness and its record, which read the action log and recordings. -- Remote sandbox providers, emulated architectures, VNC, and reaping orphans - left by an earlier REA process. diff --git a/docs/specs/desktop-app-environments/build-computer/tasks.md b/docs/specs/desktop-app-environments/build-computer/tasks.md deleted file mode 100644 index 43c330665c..0000000000 --- a/docs/specs/desktop-app-environments/build-computer/tasks.md +++ /dev/null @@ -1,10 +0,0 @@ -# Tasks - -- [x] Record the outcome, requirements and non-goals. -- [x] Render the build bundle from a request and admit actions. -- [x] Keep a computer up with the helper and tear it down, by name and label when needed. -- [x] Forward actions with images and log them; add the recording hooks. -- [x] Register the MCP tools and their catalog entries. -- [x] Document the tools. -- [x] Add boundary tests with a fake driver and an opt-in real test. -- [x] Run the opt-in real test on an amd64 host and record it here. diff --git a/docs/specs/desktop-app-environments/build-computer/verification.md b/docs/specs/desktop-app-environments/build-computer/verification.md deleted file mode 100644 index 0d7579bdf6..0000000000 --- a/docs/specs/desktop-app-environments/build-computer/verification.md +++ /dev/null @@ -1,77 +0,0 @@ -# Verification - -Run on 2026-11-05 on macOS 26.5 with Node v24.22.1 and Python 3.11. Docker and -agentenv were not used by the gates or the boundary tests. - -## Tests - -- `src/domain/desktop/appBuild.test.ts`: the bundle for an archive package, an - apt repository with its key and a `.deb` with a downloaded REA; the Node.js - pin matches REA's; refused desktop entries, credentialed or non-http URLs and - relative bundle paths. -- `src/domain/desktop/computerActions.test.ts`: key translation, argument - pass-through and refusal of an argument the action does not take. -- `tests/boundary/mcp/buildComputerMcp.test.ts`, through the public MCP tools - with REA's real helper, a fake `agent_env` package on `PYTHONPATH` and a fake - driver serving readiness, `computer_*` tools over streamable HTTP, - recording and `data/get`: start with readiness polling, the image pass-through, - argument pass-through and key translation, a driver refusal, a refused - argument, close and a later unknown id; a request bundle with REA's payload, - compiled by the fake runner; the missing payload and runner settings; a - runner failure with its output; removal by name and label; an unconfirmed teardown - retried after Docker recovers; cancellation of a start stopping the helper; - a long build's failure reported from the end of its output; a first - screenshot too large for the response that keeps `computer_id` for act and - close; the first screenshot's options. No result carries the control token. -- `tests/boundary/providers/buildComputerRecording.test.ts`: recording start, - end and one fetch per segment under REA's request id, the action log, a - long session's log kept within its allowance with every action counted and - the driver still getting each argument whole, a segment that differs from - its manifest, a recording over the allowance refused before any read, and an - answer outgrowing its segment's size. -- `src/application/desktop/DesktopBuildActionLog.test.ts`: the log names only - the arguments it cut, cuts text without splitting a character, and records - the outcome of an action dropped while it was pending. -- `tests/boundary/providers/buildComputerLifecycle.test.ts`: shutdown cancels - and joins a start in progress and refuses later starts; a failed start whose - teardown is unconfirmed stays held under the id its error names, keeps its - primary failure, and is released by a retried close and by shutdown. -- `src/process/ProviderProcessOutput.test.ts`: the supervisor's tail retention - keeps each stream's latest bytes, reports checkpoints over dropped bytes as - incomplete, and drops a UTF-8 character the cut would split. -- `tests/boundary/providers/buildComputerReal.test.ts`: opt-in with - `REA_BUILD_COMPUTER_REAL=1`, `REA_AGENT_ENV_COMMAND`, `REA_DOCKER_COMMAND` and - `REA_BUILD_COMPUTER_REA_ARCHIVE`; skipped here. - -## Checks against agentenv - -- `python -m agentenv_protocol.computer._declare` from agentenv-framework - 0.9.1431 declared both a Mousepad archive bundle and a `.deb` bundle with a - downloaded REA: packages, downloads per architecture, both run scripts and - the demand launch. -- `install-rea.sh` ran as root with the network off in a local Ubuntu 24.04 - container against a Node.js-shaped and an REA-shaped archive: it unpacked - both into `/opt/rea`, put `node` and `rea` on `PATH` and removed the - archives. - -## Real computer - -Run on 2026-11-05 on Ubuntu 24.04 amd64 with Docker, agentenv-framework -0.9.1431 and Node v24.22.1. REA's archive was packed from this tree with -`npm pack`, then `npm ci --omit=dev --omit=optional` in its `rea-prod` folder, -18.5 MB as `.tar.xz`. - -- `tests/boundary/providers/buildComputerReal.test.ts` passed in 25 s with the - image built; the first run, which builds it, took 109 s. -- Through `rea mcp` over stdio: `start_build_computer` from the Mousepad - request came up in 31 s with its first screenshot as a PNG. Mousepad opened - from Applications, Other, `mousepad`; a typed line was saved with `ctrl+s` - through the Save As dialog; actions took 6 to 60 ms beside the driver's own - typing and waits. `rea --version` answered 6.8.0 in the computer for its user - and root. `close_build_computer` took 0.5 s with `teardown: "agentenv"` and - left no container. The exported Inkscape bundle started cold in 59 s and - closed the same way; a start cancelled at 60 s left nothing up. -- With the helper killed, close removed the computer's container by its name, - `agent-`: agentenv labels only its VM and closed-network - containers. -- No result or log held the control token. diff --git a/docs/specs/desktop-app-environments/build-secrets/plan.md b/docs/specs/desktop-app-environments/build-secrets/plan.md deleted file mode 100644 index f60703218d..0000000000 --- a/docs/specs/desktop-app-environments/build-secrets/plan.md +++ /dev/null @@ -1,29 +0,0 @@ -# Plan - -1. Domain: `buildSecrets.ts` holds the handle schema, the value rules, the - spellings, `secretsIn` over bytes and a gzip file's inside, and - `redactSecrets` and `redactSecretsInJson` over text and JSON. -2. Host files: `BuildSecretFiles.ts` resolves the folder from the server's - environment, reads one handle's file under the ownership and permission - rules, and lists the handles the folder holds. -3. Typing: `computerActions.ts` adds `type_secret`, which `driverCall` maps to - `computer_type` with its handle; `DesktopBuildSecrets.ts` keeps the values - a server types and types one, shaping the result and refusals itself; - `DesktopBuildComputers.ts` logs the handle and sends the value. -4. Redaction: the action log, the witness record and the build tools' - registration redact each typed value. -5. Export: `DesktopBuildExport.ts` scans each fetched file before writing it - and refuses the bundle when one holds a secret. -6. Contract, skill, the build computer guide and this spec; unit tests for - the spellings and the files, and MCP boundary tests for typing, the - witness record and the export. -7. Withheld state: `appWithheld.ts` finds the files and names their - settings; `DesktopExportWithheld.ts` leaves them out of the seed, reads - them for the copy, and checks the consent; the class, `env.toml` and the - README declare them; the draft and the task admission leave them out. -8. Host: the capture passes the sign-in window, the files named and the - consents to the draft and the export, keeps the withheld files as - secrets, and supplies a bundle's settings at its start; - `record_build_consent` records the person's words. -9. Preserve values without inferring secrecy from their shape; only declared - handles and transport credentials are redacted. diff --git a/docs/specs/desktop-app-environments/build-secrets/spec.md b/docs/specs/desktop-app-environments/build-secrets/spec.md deleted file mode 100644 index c6f0df4acf..0000000000 --- a/docs/specs/desktop-app-environments/build-secrets/spec.md +++ /dev/null @@ -1,106 +0,0 @@ -# Secrets typed unseen - -## Outcome - -An agent building an environment for an app that asks for a password, a -licence key or a sign-in types it through REA without seeing it. The person -keeps the secret in a file on the build host; the agent names it by a handle; -REA types its value into the build computer. No tool result, action log, -witness record or exported bundle holds the value, and an export refuses a -bundle that does. The sign-in or licence state the app writes is withheld -from the bundle and supplied by whoever runs it, unless the person consents -to seed it. REA does not infer secrecy from a value or name. - -## Requirements - -- Secret files: one per handle, in `$XDG_CONFIG_HOME/rea/build-secrets/`, or - `~/.config/rea/build-secrets/` when `XDG_CONFIG_HOME` is unset or relative, - as the REA server's environment gives them. A handle is - `^[a-z0-9][a-z0-9._-]{0,62}$`. REA reads a handle's file when it types it - and refuses it unless the folder is a real folder, not a symbolic link, and - the file is a regular file, opened without following a link and without - blocking, owned by the server's user, with no group or other permission - bit, of at most one secret's size, and UTF-8. Its text, without one final - `\n` or `\r\n`, must hold 8 to 1024 characters and no control character. - A refusal names the file and the reason, never its text. -- `act_on_build_computer` action `type_secret`, taking only `secret`, a - handle, and refusing `screenshot`, `text` or any other field, and its - absence: REA sends `computer_type` with the value as `text`. Its result is - REA's own: `summary` `Typed the secret ` and the driver's - `applied`, `delivery` and `others_since_frame`, one text block saying the - same, and no image. A driver refusal, or a call that fails, is REA's own - error naming the handle, without the driver's words or the cause, since - either could quote the value; a cancelled call stays a cancellation. -- Action log: a `type_secret` entry records `{"secret": ""}` and - counts as an input for the witness's edit and near miss, as `type` does. - Every string the log keeps, member names included, has each secret typed - on the server replaced by `>`. -- Results and records: every string in each build tool's text content and - structured content, errors included, and in `witness.json`'s record, has - each secret typed on the server, in each text spelling below, replaced by - `>`. Images pass as they are. After this server uses a - declared secret, automatic task drafting is withheld before it runs; the - capture remains available for a manually written task and export. Check - descriptions redact complete known values before shortening them. Ordinary - text is never redacted merely because it resembles part of a secret. The - host redacts the app's stderr and capture progress before quoting their end. -- Export scan: before writing a bundle on the host, REA searches each file's - path and bytes for every secret typed on the server and every other one the - folder holds, whatever its permissions, in these spellings: as it is, - escaped in JSON, UTF-16LE and UTF-16BE, lower- and upper-case hex of its - UTF-8, base64 in either alphabet of the characters that depend on the - value alone at each of the three byte alignments, and URL-encoded with - upper- or lower-case escapes and with `+` for a space; and the same inside - a gzip file, decompressed up to 64 MiB. A bundle holding one is refused as - an invalid request naming each secret's handle and the files, each value - in a file's name shown as `>`, and nothing is written to - the folder. A gzip file that expands past 64 MiB, which the scan cannot see inside, is refused by name when known secrets are checked. -- The skill asks the person for a secret's file instead of the secret, types - it only into a masked field, and stops when an export finds a secret. -- Withheld state: files under the owned paths that changed after checkpoint - `pre-sign-in` up to `post-sign-in`, by the capture's recorded changes, and - those `withhold` names, are withheld. With only one of the two checkpoints - the export is refused, and so is a window in which a walk, from - `pre-sign-in` to `post-sign-in`, stopped at its entry limit, could not list - a directory or check a path, or left a change unconfirmed, since it may - have missed a file the sign-in wrote. The draft leaves the withheld files - out and lists them as `withheld_files`; a task check naming one is - refused. An export is refused, too, for a dconf key of the app that the - window changed and the seed holds other than before it, since the class - seeds dconf keys and cannot withhold them, unless the withheld state is - seeded with consent. Each withheld file present at - the seed is left out of it and becomes a `SecretStr` field of the class's - `Settings`, named as Python takes an argument and distinct within the app, - which `env.toml`'s `[settings]` sets to `env:REA__`, so a - deploy without the variable is refused with its name. At first boot, - before `keep_initial`, the class writes each from its setting, the file's - bytes in base64, mode `0600`; `data/get` serves it neither as a part nor in - the views, and `data/reset` restores it. The README names each variable and - how to fill it. A file larger than 48 KiB is refused. The CLI copies the - withheld files to `--withheld-copy`, outside the bundle, and the build host - keeps each one's base64 as the secret `rea--`, or the first - `rea---` holding no other value (`0600`), never replacing a - secret file, named in the export's `withheld_files`. -- The export refuses a seed file whose bytes equal a withheld file's, by - SHA-256, naming both files; a backup that differs from the withheld file is - not caught, so the agent trashes backups before `seed`. -- Witness: `start_build_computer` from a bundle takes `settings`, each - `REA_*` variable mapped to a handle, whose value, up to 64 Ki characters, - REA puts in the deploy's environment only. -- Consent: `record_build_consent` keeps the person's words, kind `licence` or - `seed_sign_in`, with the computer, `source: "relayed"`. The export writes - every consent into the bundle's `consent.json`. `seed_sign_in: true` seeds - the withheld files instead, refused unless a `seed_sign_in` consent was - recorded; the CLI refuses `--seed-withheld` without one in `--consent`. - -## Non-goals - -- Redacting images: screenshots and the witness's recording show whatever - the screen shows, so a secret stays unseen only in a field that masks it. -- Finding a value inside a zip archive's compressed entries, or a token an - app derives from a secret, such as a session token after a sign-in. -- Keeping the secrets folder from the building agent's own shell on the same - host; the client's permission rules do that. -- Asking the person through the client itself: the agent relays their - words, so a consent is only as true as the agent's relay. -- Withholding state outside the owned paths, which the bundle never seeds. diff --git a/docs/specs/desktop-app-environments/build-secrets/tasks.md b/docs/specs/desktop-app-environments/build-secrets/tasks.md deleted file mode 100644 index 6d77da2a29..0000000000 --- a/docs/specs/desktop-app-environments/build-secrets/tasks.md +++ /dev/null @@ -1,40 +0,0 @@ -# Tasks - -- [x] Record the outcome, requirements and non-goals. -- [x] Handles, value rules, spellings, the scan and redaction in - `buildSecrets.ts` (secret files, export scan; `buildSecrets.test.ts`). -- [x] Read, list and keep a handle's file under the ownership and permission - rules (secret files; `BuildSecretFiles.test.ts`). -- [x] Type a secret by its handle with `type_secret`, REA shaping its result - and refusals (`type_secret`; `computerActions.test.ts`, - `buildSecretsMcp.test.ts`). -- [x] Redact typed values in the action log, the witness record and every - build tool result (action log, results and records; - `DesktopBuildActionLog.test.ts`, `buildWitness.test.ts`, - `buildSecretsMcp.test.ts`). -- [x] Scan the bundle for every secret before writing it, and refuse one - that holds any (export scan; `buildSecretsMcp.test.ts`). -- [x] Document the tools, the skill and the build computer guide. -- [x] Run the KeePassXC build, export and witness on an arm64 host and record - it in `verification.md`. -- [x] Withhold the sign-in window's files and those named: the class's - settings, `env.toml`, the README, the draft and the task admission - (withheld state; `appWithheld.test.ts`, `DesktopExportWithheld.test.ts`, - `ExportedAppPython.test.ts`). -- [x] Keep withheld files as secrets on the host, supply a bundle's settings - to its witness and record consent (withheld state, witness, consent; - `buildWithheldMcp.test.ts`). -- [x] Preserve unmarked token-shaped values and scan declared handles. - -- [x] Run the KeePassXC and Typora withheld-state builds and record them in - `verification.md`. -- [x] Fix the review's gaps: refuse a sign-in window a walk may have missed a - change in, and dconf keys the window changed; refuse a gzip file too - large to check; keep each withheld file under a handle of its own; name - settings Python takes (withheld state, export scan; - `appWithheld.test.ts`, `DesktopExportWithheld.test.ts`, - `DesktopBuildSecrets.test.ts`, `buildSecretsMcp.test.ts`, - `buildWithheldMcp.test.ts`). -- [x] Withhold automatic drafting before it runs after a declared secret; - preserve the capture and manual task export. Redact full check values - before shortening descriptions, without matching partial secret prefixes. diff --git a/docs/specs/desktop-app-environments/build-secrets/verification.md b/docs/specs/desktop-app-environments/build-secrets/verification.md deleted file mode 100644 index 7f6bc71d07..0000000000 --- a/docs/specs/desktop-app-environments/build-secrets/verification.md +++ /dev/null @@ -1,152 +0,0 @@ -# Verification - -## Tests - -- `src/domain/desktop/buildSecrets.test.ts`: handles; values too short, too - long or holding a control character; each spelling found, base64 at every - alignment in both alphabets and a gzip file's inside included; a near miss - and unrelated bytes not found; text and JSON redacted, member names too; - the start of a value each of REA's cuts leaves, a draft value's, a - reference's, a view's and a check's, hidden at any length and through an - XML or JSON escape, as a string, a JSON member and a result's JSON text; - ordinary text ending in `…`, such as `Please…`, left whole; an unclosed - quote before 64 KiB of escaped quotes scanned in linear time. -- `src/application/desktop/DesktopBuildOutputRead.test.ts`: a secret the - app's stderr or the capture's progress holds, redacted before the quote of - their end cuts it. -- `src/desktop/BuildSecretFiles.test.ts`: the folder from `XDG_CONFIG_HOME` - or `~/.config`; a `0600` or `0400` file read without its final line break; - a file others can read, a symbolic link, a linked folder, a missing file - and values it cannot type refused, no refusal quoting the value. -- `src/domain/desktop/computerActions.test.ts`, `buildWitness.test.ts` and - `src/application/desktop/DesktopBuildActionLog.test.ts`: `type_secret` - takes only `secret`, maps to `computer_type` and counts as an edit; the log - keeps the handle and redacts a typed value. -- `tests/boundary/mcp/buildSecretsMcp.test.ts`, over MCP with a fake driver: - the driver receives the value as `text` while no result holds it or an - image; `screenshot`, a file others can read and a missing file are - refused; a driver refusal quoting the value shows REA's words; a later - refusal quoting it shows the handle; `witness.json` records the handle and - a `type` holding the value redacted; and an export whose bundle holds a - secret's value is refused, naming its files with the value redacted, and - writes nothing, as is one holding a gzip file that expands past 64 MiB. - -Each of these failed against the code before the change. - -## KeePassXC on an arm64 build host - -KeePassXC 2.7.6 from the Ubuntu 24.04 archive, on an arm64 Ubuntu 24.04 host -with agentenv-framework 0.9.1431 and a REA server whose `XDG_CONFIG_HOME` -held one `0600` file, `keepassxc-master`, with a made-up 30-character -password. - -- Build computer: a new database's password and its confirmation were typed - with `type_secret`; each result read `Typed the secret keepassxc-master` - with `applied: "yes"`, and the screenshot afterwards showed 30 dots in each - field. `type_secret` with `screenshot: true` was refused. The database was - saved to `Documents/e-test.kdbx`, `seed` marked, a setting changed and - `end` marked. -- Export: with a second secret file holding `keepassxc`, a string the bundle - holds in its paths and files, the export was refused naming that handle - and ten files, `envs//env.toml` among them, and no folder - was written. With that file removed, the bundle of 10 files was written. -- Witness, in a computer of the bundle: the seeded database opened locked, - `type_secret` and Return unlocked it, and seed, after edit, near miss and - after reset all held. `witness.json` records the action as - `{"secret": "keepassxc-master"}`. -- Leaks: every request, result, the driver's and REA server's logs, - `witness.json`, the recording and the bundle (131 files) held the password - in none of the spellings the export searches, UTF-16 included; nor did - either computer's `docker logs` or any file in either container. A probe - file holding the password's hex and UTF-16 was found by the same scan. - -## Withheld state and consent - -The real-provider observations below predate removal of shape-based credential -classification. They describe that earlier build and do not verify current behavior. - -### Tests - -- `src/domain/desktop/appWithheld.test.ts`: the owned files changed in the - window, and those named; a window missing a checkpoint or out of order, or - one a walk may have missed a change in; a path outside the owned paths; - settings, variables and handles, a long path hashed and like paths kept - apart, and settings that are neither Python keywords nor alike in any - order. -- `src/application/desktop/DesktopExportWithheld.test.ts`: a withheld file - left out of the seed, declared a secret setting from `env:`, copied aside - and named in the README; seeding it refused without a consent and done with - one, `consent.json` shipped; a check on it refused; the draft leaving out - the window's files; dconf keys the window changed refused unless the seed - holds them as before it or they are seeded with consent. -- `src/application/desktop/DesktopBuildSecrets.test.ts`: a kept file's - handle that names a path refused, nothing written outside the folder. -- `src/desktop/BuildSecretFiles.concurrent.test.ts`: an export never given - the handle of another whose different bytes are still being written. -- `tests/boundary/application/buildExportGzipScans.test.ts`: a gzip seed - file decompressed once for its known-secret and size checks. -- `src/desktop/ExportedAppPython.test.ts`: `_write_withheld` writes the - decoded bytes `0600` and `_views` leaves the file out. -- `tests/boundary/mcp/buildWithheldMcp.test.ts`: the named file's bytes kept - as a `0600` secret and supplied to a witness's deploy by handle, a variable - other than `REA_*` refused; a later build's bytes kept under a handle of - their own, an earlier build's secret left as it was; consent recorded and - required for `seed_sign_in`, and the sign-in window passed to the draft and - the export; one sign-in checkpoint alone refused. - -Each of these failed against the code before the change. - -### KeePassXC on an arm64 build host - -- Build: `pre-sign-in` marked, a database created with its password typed by - handle and saved, `post-sign-in` marked, which acknowledged - `Documents/e-test.kdbx` among its changes, then `seed`, a setting changed - and `end`. The draft listed `withheld_files: ["Documents/e-test.kdbx"]`, - and showed the KeeShare key KeePassXC generated as - ``. -- Export: refused with `seed_sign_in` and no consent. Without it, the seed - held only `keepassxc.ini`; `env.toml` set `documents_e_test_kdbx` to - `env:REA_KEEPASSXC_DOCUMENTS_E_TEST_KDBX`; agentenv's `_declare` read the - setting as a required `writeOnly` string; the README named the variable; - and the host kept the database's base64 as the `0600` secret - `rea-keepassxc-documents-e-test-kdbx`. -- Deploy without the variable: refused at the probe with - `Unresolved env:REA_KEEPASSXC_DOCUMENTS_E_TEST_KDBX reference`. -- Witness, from a copy of the bundle with `settings` naming that handle: the - computer wrote `Documents/e-test.kdbx`, mode `0600`, byte for byte the kept - file; the agent opened it and unlocked it with `type_secret`; seed, after - edit, near miss and after reset held, and the file was still there after - the reset. -- Leaks: no host file of the run but the secret's own, 146 in all, held the - password in any spelling; neither bundle held the database's bytes; and - neither computer's logs nor files held the password. - -- The same build, export and witness ran again on the final code with a new - password: every stage held, and 124 host files, both bundles and both - computers held neither the password nor the database's bytes. - -### Typora 1.14.9 on an arm64 build host - -- Installed from `typora_1.14.9_arm64.deb` by URL and SHA-256, on its trial. - Its licence file was `~/.config/Typora/rXMW4iG3Bl`, hex of - `{"SLicense":""}`; it was `mAxvdiPNmi` on an amd64 host, so the name - differs by machine. Typora writes it at first launch, before any - checkpoint, so the export named it in `withhold`: it was left out of the - 84-file seed, declared as `REA_TYPORA_CONFIG_TYPORA_RXMW4IG3BL`, and kept - as the secret `rea-typora-config-typora-rxmw4ig3bl`. -- Booted from the bundle's image with a made-up licence in the setting, the - initial state the class keeps before the app starts held the made-up file, - mode `0600`; Typora then found no valid licence and wrote an empty one over - the live file, which `data/reset` would put back. -- A witness through `start_build_computer` failed agentenv's first-boot - probe (`P4 a click in frame space hits its cell`), also for a bundle of the - same capture exported without withholding, so no stage ran. - -## Limits of this verification - -- Only a masked field was used: a field that shows its text shows a typed - secret in screenshots and in the recording. -- A deploy refused for want of a variable leaves agentenv's build of that - bundle failed; a later run needs `agent-env env build` or a fresh copy of - the bundle. -- The person's consent was relayed in a test; no person was asked. diff --git a/docs/specs/desktop-app-environments/build-witness/plan.md b/docs/specs/desktop-app-environments/build-witness/plan.md deleted file mode 100644 index 6697176a27..0000000000 --- a/docs/specs/desktop-app-environments/build-witness/plan.md +++ /dev/null @@ -1,32 +0,0 @@ -# Plan - -1. Capture acknowledgement: `desktopCaptureEventSchema` and - `desktopCaptureProgressSchema` in the capture's domain schema; the session - reports `window_open` and `checkpoint_refused`, the capture a - `checkpoint` event after each checkpoint is taken; the CLI writes the event - in its progress line. -2. Controller: `bridge/agentenv/capture.py`, with `start`, `mark`, `stop`, - `run` and `list`, each answering one JSON line. -3. Adapter: `AgentEnvComputer` gains `exec`, `homeFiles`, `appData` and - `waitUntilReady`, and reports start progress; - `src/desktop/BuildComputerController.ts` runs the controller and fetches a - home folder in bounded, checked batches. -4. Domain: `buildCapture.ts` (checkpoint names, `seed` and `end`) and - `buildWitness.ts` (stages, their order and expectations, the app's state - views); `computerActions.ts` gains `reset`. -5. Application: `DesktopBuildCapture` (start, mark, stop and draft) with - `DesktopBuildExport` and the shared `DesktopBuildCommands`, and - `DesktopBuildWitness` with `DesktopBuildWitnessRecord`, held per live - computer by `DesktopBuildComputers`, which also resets; - `DesktopBuildSteps` serves the step tools by `computer_id`. The output - tree writer moves to `DesktopOutputTree.ts` for the export, the build - export and the witness record. -6. MCP: contracts, effects, CLI-parity list, registration with heartbeat - progress. -7. Launch from the home in `launchCommand` and the build bundle; the packing - script. -8. Docs: the guide, the capture, export and build computer guides, this spec. -9. Tests first: the witness rules, the reset action, the launch commands, the - capture's acknowledgements on Linux, and boundary tests through the MCP - tools with a fake computer that runs the real controller against a REA - stand-in printing the real CLI's outputs; then the amd64 VM. diff --git a/docs/specs/desktop-app-environments/build-witness/spec.md b/docs/specs/desktop-app-environments/build-witness/spec.md deleted file mode 100644 index cd1fe5aa74..0000000000 --- a/docs/specs/desktop-app-environments/build-witness/spec.md +++ /dev/null @@ -1,215 +0,0 @@ -# Build and witness - -## Outcome - -An agent that builds a desktop app environment on a build computer captures -the app with REA inside the computer, marks the seed and the end and gets an -acknowledgement for each, drafts the task, exports the bundle with the task -it wrote and brings the bundle back to the host, all through REA's MCP tools. -It then witnesses the task live in a fresh computer of that bundle: the seed -fails a check, the edit made from the prompt passes every check, a near miss -fails one, and after `data/reset` one fails again. REA keeps the action log -and the recording and writes the record as Evidence. - -## Requirements - -- MCP-only session tools in the `application` family, on a build computer's - `computer_id`: `start_build_capture`, `mark_build_checkpoint`, - `stop_build_capture`, `export_build_environment` and `check_build_task`, and - a `reset` action of `act_on_build_computer`. -- Commands in the computer go through agentenv's `computer-exec/v1` route - with the control token, which stays in REA and is removed from any output - REA reports. A controller, `bridge/agentenv/capture.py`, travels with each - command as `python3 -I -c`; it runs REA as the session user in the home - without `AGENTENV_*` variables and with `APT_CONFIG` naming apt lists it - downloads into `~/.rea-build/apt` before the first capture. -- The capture runs detached, its stdin a FIFO it holds open for reading and - writing; a shell around it records its exit status. `~/.rea-build` is left - out of every walk. A start returns once the capture reports the window - open; a refused or early-ended start stops the capture and reports its - output. -- `start_build_capture` takes `state_paths`, at most 16 files or folders in - the home, relative to it, after `~/` or absolute, without `..` and not the - home itself; the controller resolves each under the computer's home, both - as named and with its links followed (a path not there yet through its - nearest existing folder), refuses one outside it or in `~/.rea-build` - either way before launching anything, and passes each as named to the - capture as `--state-path`. A selected file is a document, or the app's own - state under a hidden folder of the home as named, before links, or when it - is a lock the app holds, such as LibreOffice's `.~lock.#`. -- Acknowledgement: `capture-desktop-application` reports, beside each progress - message, an `event`: `window_open`; `checkpoint` with its name, trigger, - time, entries walked, changes and retained files and bytes, and up to ten - changed files, home-relative, those under a selected path first, then - those the app held open, caches and browser-engine storage last, with a count - of the rest, once it is taken, the baseline, `stop` and `exit` included; - and `checkpoint_refused` with the reason. `mark_build_checkpoint` writes - `checkpoint ` and waits for the event naming it, returning its counts - and changed files, both `null` when the REA in the computer predates them - and its event leaves them out. Names follow a narrow pattern, without the capture's own - names; a name already taken is refused. -- `stop_build_capture` sends `stop`, waits for the exit status, reads the - capture's Evidence and, when `seed` and `end` were acknowledged, runs - `describe-desktop-application-task --seed-checkpoint seed --end-checkpoint - end` and returns the changed files, their net change and suggested checks. - A draft with no files carries `notes`, coded `no_change`, - `unowned_changes` (up to five changed home paths with their roles, and a - count of the rest), `uncheckable_changes` (dconf databases whose app keys - were read and changed, which no check reads; a version kept without its - bytes is unreadable, not empty), `unreadable_changes` (dconf - databases that changed but could not be read, with the read `error`) and - `no_document`; a drafted file whose suggestions are thin carries one - naming its `file`, coded `by_position`, `view_state_only`, `long_text`, - `cut_view` or `unreadable_view`. -- `export_build_environment` writes the agent's task under `~/.rea-build`, - runs `export-desktop-application` with it and the same checkpoints into a - new folder there, reports a refused task with the export's own reason, - lists the bundle with sizes and SHA-256, fetches it through the driver's - `data/get` in answers of at most 8 MiB, checks each file and writes the - caller's new or empty folder through the safe output tree. The export - leaves lock files the app holds while it runs out of the seed, but never a - document or selected path, listing them in its limitations and README; a - start from a bundle whose computer never gets ready names the files its - seed holds by a profile lock's name, as a document lock or as a - `.lck` beside a seeded file. -- `check_build_task` reads the one app's `data/get` through the card's - child URL, takes the state views beside its files and evaluates the task's - checks with `evaluateTaskChecks`, one result per check. With `stage`, the - checks file a witness stage: `seed` (with `directory`) starts a recording - and must fail a check; `after_edit` must pass all; `near_miss` must fail - one; `after_reset` must give each check its seed result. Stages come in order, for one task; the - edit and the near miss each need an applied input action since the stage - before, `after_reset` a reset as the last change. A stage that does not hold, - or the last, ends the witness: the recording ends, its segments are fetched - and checked, and `directory` gets the segments and `witness.json`, Evidence - of the verdict, the stages, the action log and the recording. -- The `reset` action calls the app's `data/reset`, then waits for the - computer's readiness checks, since the reset relaunches the app. -- Gaps of the build computer's first real run: a packing script for - `REA_BUILD_COMPUTER_REA_ARCHIVE`; build and exported apps start in the home - (the captured working directory), not in agentenv's folder for the app; and - MCP progress notifications every five seconds while a computer starts and - while the capture, draft, export and witness tools work. - -- Retries keep ownership: a start whose answer is lost stops its capture, - and REA keeps a capture whose stop is unconfirmed, retrying that stop - before another start; a lost checkpoint acknowledgement comes back from - the capture's log; a stop resumes reading its result or repeats it; the - draft and export read the checkpoints from the capture's Evidence; a seed - check that failed after opening is asked again with its task and folder; - a record whose save failed is written again on a repeat of its stage. -- The edit and the near miss count only click, drag, scroll, type and key, - and a reset after the last of them refuses the stage. -- A `.deb` app's file is kept in the build layer for `--package-file`, and - its URL reaches the export's `--package-url` only when the capture's - package facts say apt does not install it, as the export itself decides. - A failed `apt-get update` reports its status and last lines, and the next - start runs it again. The bundle is - written as it arrives. -- Gaps of a blind validation run: the desktop Trash is never the app's state - or a document, so a file the builder trashed is neither owned nor seeded, - and the export's limitations name what the Trash held at the seed; a - start from a bundle folder writes no bytecode into it; the first - screenshot waits, briefly and bounded, until the frame is not one colour. -- Gaps of the blind validation's solve runs: the exported app opens the - seed's one document at launch, when its desktop entry takes files, so a - solving agent starts in the document rather than on the app's start - screen; and `export_build_environment` passes `--synthetic-seed`, so the - README says the seed was made for the task instead of calling it the - user's real data. - -- Gaps of the second review: calls on one computer (actions, capture - steps, checks and close) run one at a time in arrival order, so a stage's - admission, read and filing see no other call, while computers run side by - side; a close cancels the call in progress and refuses those waiting. The - witness's recording has one request id per computer, so a seed retried - after a lost reply asks for the recording it began. A check that fails for - want of a readable or whole view is `undecided` and proves nothing; a - stage only such checks would settle files nothing and can be checked - again. Undecided includes a failure to find a line, row or value that may - lie in what a cut view left out, and any text check of an element in a cut - view, which may have lost text from between the element's runs; any other - check that passes on what the view kept stays decided. The export likewise keeps a task only when a check - fails on what the seed's view shows. The controller writes a folder's file - list to a file that REA reads through `data/get`, so a large bundle's list - is not cut at the 1 MiB of a command's output. -- Gaps of the build batches: an archive request takes up to 16 - `extra_packages`, archive package names validated as its `package` is, - installed beside the app and listed in `start_build_computer`'s result - (a `.deb` request's `dependencies` are listed there too), for a runtime - piece the app needs that its package does not install (MyPaint's SVG icon - loader `librsvg2-common`, which GTK only recommends; a Java 17 for - Freeplane, whose launcher refuses noble's Java 21). The export takes them - as repeatable `--extra-package` and installs them beside the app, and the - build export passes them, and a `.deb` request's `dependencies` too, so a - `.deb` apt also offers no longer loses them when it is installed by name. - The limitations and the README name them, leaving out only what the - bundle installs anyway: the app's own package and, when it is installed - from its `.deb`, the dependencies the `Packages` line names. A package the - captured `.deb` lists only as one alternative stays, since apt may pick - another, such as `openjdk-17-jre | java-runtime`. -- Gaps of the third batch's GnuCash build: the build bundle installs - `dconf-cli`, so the capture reads the app's dconf settings, such as - GnuCash's "Show tips at startup" unticked before `seed`, and the seed - keeps them; an export whose dconf database changed by the seed but could - not be read names it, with the read error, in its limitations. A - `.lck` or `.LCK` beside a file the capture recorded in the - same folder, as GnuCash's `household.gnucash.LCK`, is a lock left out of - the seed; a lone `notes.lck` is seeded. -- Gaps of the fourth batch: a desktop entry that is not reverse-DNS names - the environment whole, without a trailing version, so `glabels-3.0` gives - `glabels` rather than `0`, in the build computer and the export alike. The - capture launches the app with `LIBC_FATAL_STDERR_=1`, so a glibc abort's - reason reaches the app-exit error. A `..lock` or `..lck` beside - its file, as Grisbi's `.household.gsb.lock`, is a lock too, left out of the - seed and its text seeds; a lone `.notes.lock` is seeded. A seeded - LibreOffice `registrymodifications.xcu` ships without its `RecoveryList` - items, which started an Impress bundle into document recovery, and a - limitation and the README name the file. A checkpoint ranks caches and - browser-engine storage last under a selected folder too, unless named - themselves, so LibreOffice's icon cache no longer fills `changed_files`. -- Gaps of the fifth batch: a checkpoint names first the files the app's - window titles have named so far, which the session now hands each - checkpoint, so a document saved and no longer held open (Gnumeric, LyX, - Tiled) leads; then files selected themselves; then those held open, under - a selected folder or in state directories; then the rest; then caches and - browser storage, which now include a whole `QtWebEngine` profile and - Chromium's `Visited Links`, `Platform Notifications` and `user_prefs.json`. - Example prompts name the app, and the export's limitations say when a - task's prompt names neither the app's title, environment nor package: a - solving agent's shell cannot see the computer's files. The unowned paths - limitation counts files or folders. -- Gaps of the published bundles: app-state logs are retained because their - names alone do not distinguish diagnostic output from user history or - database writes. Locks remain excluded under the lock ownership rules. - LibreOffice's recovery list items are found with the shared XML parser and - cut by their source ranges, so quoting, spacing, comments and CDATA cannot fool the match, - and a registry that is not well-formed ships unchanged. -- Gaps of the seventh batch: a window title names a file only by its whole - name, or its `~/` or absolute path, never by a folder of a path it shows, - and an extensionless name only standing alone; files under `~/.cache` and - dconf's databases are never named. CherryTree's title, which shows - `/home/user/Documents`, made `~/.cache/dconf/user` a second document, so - its bundle opened none; the state role and the checkpoint ranking share - the fix. VYM's `.vym.lock` beside the map is a lock too, while a - project's `Gemfile.lock` beside its `Gemfile` stays seeded. -- Gaps of the eighth batch (Poedit): a `*.lock` or `*.lck` directly in the - home and Lucene's `write.lock` anywhere are locks; a lock or log never - becomes an owned path, is never named among the unowned paths, and makes - no folder count as held open, so neither the capture nor the export points - `state_paths` at the home. A seed file keeps its permission bits at the - seed where the capture recorded them, through the module's `SEED_MODES`, - so a `0600` file an app checks boots `0600`; a file the capture never saw - change has no recorded mode. -- The witness reads the build computer's bounded action log: its stage rules - use the log's count and the last applied action of each kind, and the - record holds the entries the log keeps, `actions_dropped`, and a - limitation when the log dropped actions or cut arguments. - -## Non-goals - -- Running the exported `verify.py` in the witness; REA's evaluator is the - one it mirrors, and the Python parity tests cover the port. -- A witness by a separate solving agent, remote sandbox providers, emulated - architectures, and choosing the near miss for the agent. -- Recording the build itself; only the witness is recorded. diff --git a/docs/specs/desktop-app-environments/build-witness/tasks.md b/docs/specs/desktop-app-environments/build-witness/tasks.md deleted file mode 100644 index 83b153c760..0000000000 --- a/docs/specs/desktop-app-environments/build-witness/tasks.md +++ /dev/null @@ -1,19 +0,0 @@ -# Tasks - -- [x] Record the outcome, requirements and non-goals. -- [x] Acknowledge checkpoints from the capture with their counts. -- [x] Run capture, draft and export in the computer and bring the bundle back. -- [x] Check a task against a live app and witness it with a recording. -- [x] Reset the app's data and wait for it to be ready. -- [x] Pack REA's runtime, start apps in the home, report start progress. -- [x] Document the tools. -- [x] Add the tests and run the build and witness on an amd64 host. -- [x] Fix the blind validation run's gaps and the export's install source for a `.deb`. -- [x] Fix the second review's gaps: one call at a time per computer, the recording's request id, undecided checks and the bundle's file list. -- [x] Leave a failure that a cut view may have caused undecided: a missing line, row or value. -- [x] Open the seed's one document at launch, and word a seed made for the task as such. -- [x] Install a request's extra packages beside the app, in the build computer and the export, and keep a `.deb` request's dependencies when apt installs it by name. -- [x] Read dconf in the build computer, name dconf settings the export could not read, and leave a `.LCK` beside its file out of the seed. -- [x] Name a version-dotted desktop entry's environment whole, send glibc's fatal errors to the captured app's stderr, leave Grisbi's `..lock` and LibreOffice's recovery list out of the seed, and rank caches last under a selected folder. -- [x] Rank a checkpoint's changed files by window titles first and QtWebEngine storage last, name the app in prompts, and say when a prompt does not. -- [x] Retain app-state logs without inferring their purpose from filenames; leave owned locks out of the seed. diff --git a/docs/specs/desktop-app-environments/build-witness/verification.md b/docs/specs/desktop-app-environments/build-witness/verification.md deleted file mode 100644 index d6e697b92e..0000000000 --- a/docs/specs/desktop-app-environments/build-witness/verification.md +++ /dev/null @@ -1,548 +0,0 @@ -# Verification - -Run on 2026-11-05: gates and source tests on macOS 26.5 with Node v22.23.1 -and Python 3.11; Linux tests and the real run on Ubuntu 24.04 amd64 with -Docker, agentenv-framework 0.9.1431 and Node v24.22.1. - -## Tests - -Each new test fails on the code before this change, run from that code with -only the new tests and fixtures added: on macOS, and on Linux for the -capture's acknowledgements. - -- `src/application/desktop/DesktopApplicationCapture.test.ts` (Linux): the - capture reports the baseline, `window_open`, `seed` with the counts its - checkpoint recorded, a refused second `seed`, then `stop` and `exit`. - Before, no event reached the driver and the test ran out of time. -- `src/domain/desktop/buildWitness.test.ts`: each stage's expectation, the - order of stages with the actions each needs, and the app's state views. -- `src/domain/desktop/computerActions.test.ts`: `reset` maps to - `data/reset` and takes only `screenshot`. -- `src/domain/desktop/appExport.test.ts`, `appBuild.test.ts`: exported and - build apps start in the captured working directory, `"$HOME"` for the home. -- `tests/boundary/mcp/buildCaptureMcp.test.ts`: through the MCP tools, a - request computer whose `computer-exec` runs REA's real controller on this - host, against a REA stand-in that acknowledges requests as the capture - does and prints what the real CLI wrote for a seed-and-end capture: package - lists under `APT_CONFIG` (compressed, as Ubuntu keeps them), the start with - a screenshot, `seed` with its counts, a repeated and a reserved name - refused, `end`, the draft, and the export with the task, whose files arrive - byte for byte. REA ran without `AGENTENV_*`, in the home, with - `--exclude ~/.rea-build` and both checkpoints. Steps out of order and a - capture on a bundle's computer are refused. No result holds the token. -- `tests/boundary/mcp/buildWitnessMcp.test.ts`: a plain check; the witness - with a fake app whose state the test changes; the edit refused before an - action, `after_reset` before a reset; the reset relaunch; the record with - four held stages, the action log, the recording segment and - `witness.json` read back as Evidence; a seed that already passes ends the - witness as failed and later stages are refused; `directory` missing or not - empty is refused. -- PR 2's boundary tests now share `tests/fixtures/buildComputerMcp.ts`. - -## Gates - -`typecheck`, `format:check`, `build:cached`, `knip`, `jscpd`, `docs:check`, -`docs:build`, `verify:test-discovery`, `verify:architecture-guards`, -`verify:module-boundaries` and `mcp-catalog:check` passed. `lint` and -`lint:typed` fail only on main's `tests/acceptance/webSourceLocationCli.test.ts`. -jscpd's one clone in a touched file is the existing pair of cancellation -tests in `DesktopApplicationCapture.test.ts`. The desktop, contract, schema, -CLI-parity and build boundary tests passed on macOS (Linux-only cases -skipped) and, on Linux, the desktop and build tests ran 467 passed. - -## Real computer - -REA's archive was packed from this tree with `npm run -pack:build-computer-runtime`, 16.8 MiB in 54 s. Through `rea mcp` over stdio, -driven as the building agent: - -- `start_build_computer` from the Mousepad request built its image and came - up in 80 s, with an MCP progress notification every 5 s naming agentenv's - stage. A later start took 22.5 s. -- `start_build_capture` returned in 7.3 s with Mousepad open under capture. - A typed two-line list saved through Save As, which opened on the home, as - `~/Documents/todo.txt`; `seed` was acknowledged in 0.45 s (54 entries, 7 - changes, 4 files retained) and a second `seed` refused; a third line saved, - `end` in 0.45 s. -- `stop_build_capture` took 1.7 s: checkpoints `baseline`, `seed`, `end`, - `stop`, `exit`; `mousepad` 0.6.1-1build2 from `noble/universe`; the draft's - one file, `Documents/todo.txt`, with the line added and a suggested - `lines_present`. This run counted 0 package lists, because apt keeps them - as `*_Packages.lz4`; the count was fixed and a later start reported 15. -- `export_build_environment` refused a `line_count` without `exact` or - `contains` with the export's reason, then exported the task in 1.3 s: 9 - files, 50,846 bytes, `failing_on_seed` `dentist` and `one-dentist`, seed - `Documents/todo.txt`, nothing left unscrubbed, and the app launched with - `cd "$HOME"`. `close_build_computer` took 0.5 s. -- A fresh computer of the bundle came up in 72 s. The witness held: seed - failed two checks; the line added through Open and Save passed all three; - `call the dentists` failed `dentist`; the reset, ready in 0.8 s, relaunched - Mousepad and its check failed two again. The record has 15 actions and 5 - recording segments, 68.6 s and 1.2 MB, written with `witness.json`. -- Every computer closed with `teardown: "agentenv"`; Docker held only the - local registry it had before. The MCP server's log never names a token. - -## Review fixes - -Run on macOS after the first review; the VM was not used. Each new test -failed on the reviewed head, with only the new tests and fixtures added, and -passes now. The fake computer now runs a command and then loses its reply -when a test asks, fails an app's `data/get` and keeps a relaunched app -unready for some polls. - -- `buildWitness.test.ts`: a reset is neither the edit nor the near miss, and - a reset after the last input refuses them; a near miss made after a reset - is admitted. -- `appBuild.test.ts`: the build layer copies a `.deb` to - `/opt/rea/package.deb` before the app's own install removes it. -- `BuildComputerController.test.ts`: each checked answer is handed over - before the next is fetched. -- `buildCaptureRetryMcp.test.ts`: a start whose reply was lost stops its - capture, and while that stop's reply is lost too REA refuses another start - naming the capture, then retries the stop first; a lost checkpoint reply - comes back on a repeat; a stop whose draft reply was lost finishes on a - repeat and repeats its result, and the export follows; apt's exit 100 and - message reach `package_lists_error`; a `.deb` request captures with - `--package-file` and exports with `--package-url`. -- `buildWitnessMcp.test.ts`: a seed whose read failed is checked again with - the one recording; a record whose save was refused is saved on a repeat of - `after_reset` without reading the app again; a slow reset sends progress. - -## Validation-run fixes - -Run on macOS after a blind validation run of the build flow and a review -finding; the VM was not used. Each new test failed on be30603ec with only it -and its fixture changes added, unless noted, and passes now. - -- `stateRoles.test.ts`: a path in `~/.local/share/Trash` has the reason - `desktop_trash` and the role `shared_desktop`, whatever else names it, - a window title included; `~/.local/share/Trashcan` is not the Trash. -- `DesktopApplicationExport.test.ts`: a file named in the window title and - moved to the Trash before the seed checkpoint is neither owned nor seeded, - and a limitation names both of the Trash's files. Before, - `.local/share/Trash/files` was owned and the file seeded, as the run saw - with `poster.svg`. -- `buildComputerMcp.test.ts`: the fake runner loads each of the bundle's - Python files in a child Python as agentenv's `_declare` does, and a start - from a bundle folder leaves its file list unchanged. Before, - `envs/notes/__pycache__/notes_app.cpython-311.pyc` appeared. In - agentenv-framework 0.9.1444 that child is the only Python that imports the - bundle's files, and it inherits the helper's environment. -- `buildComputerMcp.test.ts`: after two black frames, the start returns the - third, drawn one; a `region`, `format` or `quality` applies to a screenshot - taken after it. The fake's frame is now a 2x1 PNG of two colours. - `PngVisualDiff.test.ts` covers the new one-colour check. -- `buildComputerMcp.test.ts`, after review: with every frame black and the - third screenshot's reply a minute late, the start returns the second frame - at the 10 s bound and reports `waiting for the desktop to draw` as - progress meanwhile. Before, the retry kept its 120 s request timeout and - progress stopped once readiness passed, so the test ran out of time. -- `buildCaptureRetryMcp.test.ts`: a `.deb` request whose captured package - apt also offers exports without `--package-url`; one that no apt source - offers exports with it, from the real CLI's output for that capture (this - case passed before too). `appExportInstall.test.ts`: the new check agrees - with the export's own install choice. - -`typecheck`, `format:check`, `build:cached`, `knip`, `jscpd`, `docs:check`, -`docs:build`, `verify:test-discovery`, `verify:architecture-guards`, -`verify:module-boundaries` and `mcp-catalog:check` passed; `lint` and -`lint:typed` fail only on main's `tests/acceptance/webSourceLocationCli.test.ts`. -The desktop source tests ran 453 passed (Linux-only cases skipped), and the -build and desktop boundary tests 67 passed with the real test skipped. - -Not verified on a real computer: that the first frame not of one colour -shows the panel on the computer's desktop. - -## Second review fixes - -Run on macOS after the second review; the VM was not used. Each new -boundary test failed on the reviewed head, with only the new tests and -fixtures added, and passes now. The fake computer now cuts a command's -stdout at 1 MiB as the computer does, loses a recording start's reply when -a test asks, and a bundle folder can name the fake computer its start -hands out, so one server can hold two. - -- `buildWitnessMcp.test.ts`: two `after_edit` checks sent together file - one stage, the other is refused as out of order, and `after_reset` stays - refused until a near miss. Before, both were filed, and after a reset the - record held with the stages `seed`, `after_edit`, `after_edit`, - `after_reset`. An `after_reset` check sent while a reset relaunches the - app waits for it and is admitted; before, it ran during the reset and was - refused. A seed retried after its recording's start reply was lost asks - for the same request id; before, a new one. A seed and a near miss whose - only failing check could not read its file are refused and filed once - the file reads; before, the read error was filed as the failure. -- `buildComputerMcp.test.ts`: a screenshot sent behind a slow reset on one - computer answers after it, while a screenshot on another computer answers - first, and the waiting action sends progress; a close during a reset - cancels it and refuses an action and a capture step waiting behind it, - and tears the computer down. Before, the screenshot answered first and - the close left the reset running. -- `buildComputerLifecycle.test.ts`: the owner's shutdown cancels a call in - progress and the one waiting behind it. -- `buildCaptureRetryMcp.test.ts`: an export whose bundle's file list is - about 1.1 MB brings every file back. Before, the list was cut at 1 MiB and - the export failed with the controller not answering. -- `DesktopBuildTurns.test.ts`: calls run one at a time in arrival order, a - call that throws frees its turn, a call cancelled while it waits keeps its - place until the one before it ends, and a close runs once the call it - cancelled has ended. -- `buildWitness.test.ts` and `appTaskChecks.test.ts`: the three-way stage - verdict, and which failures are `undecided`. - -## Bounded action log - -Run on macOS after merging the build computer's bounded action log; the VM -was not used. The stage rules now read the log's count and the last applied -action of each kind, and the record its kept entries. - -- `buildWitness.test.ts`: every earlier admission case, through the log a - list of actions makes, and the rules over a log of 1,000 actions whose - earliest are dropped. -- `buildWitnessMcp.test.ts`: a witness of 263 actions, one typing 2 KiB, - is admitted at every stage and held; its record keeps 256 actions from - index 7 with `actions_dropped` 7, names `text` in the typed action's - `truncated_arguments`, and its Evidence states both limitations. - -## Failures on cut views - -Run on macOS; the VM was not used. The first three tests failed on the -reviewed head, with only the tests and fixtures added, and pass now. - -- `appTaskChecks.test.ts`: `lines_present` missing line 5,500 of a - 6,000-line file, `row_present` missing row 501 of a table cut at 500, and - `value_equals` whose pointer names nothing in a cut text, SQLite, XML or - zip listing view are undecided; a line, row or value the view kept stays - decided. Before, each was a decided failure. -- `buildWitnessMcp.test.ts`: a seed and a near miss whose only failing check - misses `eggs` in a text view cut at 5,000 lines are refused and filed once - the view is whole. Before, the seed was filed as held. -- `DesktopTaskExport.test.ts`: a task whose only seed failure misses `milk` - in a 6,000-line note is refused, naming the failure, and with a row check - that fails on the seed too it is kept with only that check in - `failing_on_seed`. Before, the export kept the first task. -- `desktopTaskPython.test.ts`: the exported verifier fails the same cut-view - cases with the same descriptions, as it did before. - -## Cancellation after a step - -Run on macOS; the VM was not used. A step returns what it saved even when -its call is cancelled or the computer closes as the save finishes; only -`start_build_capture`, which saves nothing, checks after its last await, the -screenshot of the opened app, and ends cancelled. Each test below except the -first failed on the head that cancelled every aborted turn, with only the -tests added, and passes now. - -- `buildCaptureRetryMcp.test.ts`: a close while `start_build_capture` waits - for that screenshot makes it return `cancelled`. Before the start's own - check, it returned success for the computer being removed. A close while - an export's bundle commits still returns the bundle; before, `cancelled`. -- `buildWitnessMcp.test.ts`: a close while the witness record commits still - returns the record, and a check cancelled while it commits gets the saved - record when asked again; a saved witness's repeated final check returns the - same record without checking or writing. Before, `cancelled`, and the - repeat was refused as ended. -- `DesktopBuildTurns.test.ts`: a running call that finishes after a close - keeps its result. - -## Opening the seed's document - -Run on 2026-11-05: source tests and gates on macOS; the desktop source tests -again on the Ubuntu 24.04 amd64 VM (40 files, 422 passed, none skipped). - -- `seedDocument.test.ts`: the seed's one document is appended when `Exec` - holds `%F`, `%U`, `%f` or `%u`, and the launch respells it as - `"$HOME"/'Documents/poster.svg'`; two documents, none, an `Exec` without a - file field code and a capture without a desktop entry keep the command and - give the reason; a command already naming a file under the home is kept. -- `appExport.test.ts`: the README says what the launch opens, or why it - opens nothing; a seed made for the task is worded as such in the README - and the class, and a captured one as the user's real data. -- `DesktopApplicationExport.test.ts`: from a seed-and-end capture launched - through `notes %U`, the class launches `notes` with the note; through - `notes`, or without a desktop entry, and from a baseline seed with no - document, it launches as captured and a limitation says why; - `--synthetic-seed` changes the limitation and the README and is recorded - as `synthetic_seed`. -- `buildCaptureMcp.test.ts`: `export_build_environment` runs the export - with `--synthetic-seed`, and the real CLI's README for that capture says - the seed was made for the task. - -The blind Inkscape build's capture was gone with its build computer, so the -bundle could not be exported again. Instead, a copy of that bundle had only -its `Launch` command replaced by the one this code renders for its seed (one -document, `Documents/poster.svg`; the image's `Exec=inkscape %F`). A computer -of it came up in 47 s with Inkscape showing `poster.svg` and no Welcome -screen, and `data/reset` relaunched it on the poster again. Three Claude Code -runs with Sonnet 5.5 all passed, in 11, 9 and 10 turns for $0.70, $0.46 and -$0.72 ($0.63 on average); the same bundle opening on the Welcome screen had -taken 18, 23 and 21 turns for $0.70, $1.55 and $0.51 ($0.92). Cache reads -fell from 585-714K tokens to 181-225K; the cost is mostly cache writes, -which varied from 17K to 189K tokens whatever the turns. - -## Naming the app's state - -Run on macOS with source tests and gates; no build computer was started. -Each test below failed on the head before this change, with only the tests -and their fixtures added, and passes now. - -- `buildCaptureStatePathsMcp.test.ts`: `start_build_capture` with - `state_paths` passes the note's path to the capture as `--state-path`, the - draft covers it as a document with no notes, and an export with a check on - it is accepted; without it the draft is empty with `unowned_changes` - (the note, `unrelated`) and `no_document`, and the export's refusal names - `state_paths`. A path through `..`, the home itself and 17 paths are - refused by the schema, `/etc/hosts` by the computer, and none starts a - capture. Before, `state_paths` was an unknown argument. -- `DesktopTaskDraftNotes.test.ts`: a draft with files has no notes; one with - no change between seed and end has only `no_change`; one whose changes lie - outside the owned paths lists five with their roles, desktop files last, - and counts two more, beside `no_document`. -- `stateRoles.test.ts`: a selected file under a hidden folder of the home is - application state, elsewhere a document. -- `DesktopApplicationExport.test.ts`, `appExportUnowned.test.ts`: the export's - limitations and README name folders the capture saw change outside the - owned paths, collapsed to their top folder and without desktop caches, up - to eight and a count, and the seeded lock file, WebKit storage and cache - folders. - -## Lock files, changed files and held-open folders - -Run on macOS with source tests and gates; no build computer was started. A -hold-out LibreOffice Calc bundle seeded `~/.config/libreoffice/4/.lock` and -showed no window at boot; its export also said nothing in `~/Documents` was -seeded while `seed_files` held `Documents/q1-sales.ods`. Each test below -failed on the head before this change, with only the tests and their -fixtures added, and passes now. - -- `DesktopApplicationExport.test.ts`: a capture whose seed holds a profile - `.lock` and a document lock `.~lock.today.txt#` exports without either in - `seed_files` or the bundle, and lists both after "Left out of the seed" in - one limitation and the README; with `~/Documents` held open, its - limitation names `~/Documents/today.txt` as seeded from there. -- `appExportUnowned.test.ts`: profile, browser and document locks are lock - files, and `*.lock` or `*.lck` only in a hidden folder, so `Cargo.lock` - and `yarn.lock` in a project are not; the capture's limitation names the - held-open folders from `~/`, and the export's names the seed files there - or says there are none. -- `desktopCapture.test.ts`: a checkpoint's acknowledgement names its changed - files home-relative, the held-open document first, then state, then the - rest, without folders, and names ten of thirteen with three more. -- `buildCaptureMcp.test.ts`: `mark_build_checkpoint` returns the changed - files the capture acknowledged. -- `buildComputerMcp.test.ts`: a bundle's start that never got ready names - the lock files its seed holds; one without locks, or failing otherwise, - names none. - -The Linux-only capture test's acknowledgement now expects the changed state -file; it is skipped on macOS and was not run. - -## Linked state paths, dconf changes, project lock files and older checkpoint replies - -Run on macOS with source tests and gates; no build computer was started. -Each test below failed on the head before this change, with only the tests -and their fixtures added, and passes now. - -- `buildCaptureStatePathsMcp.test.ts`: the computer refuses state paths that - a link leads out of the home, existing or not yet (through the nearest - existing folder, or a dangling link), or into `~/.rea-build`, and starts - nothing; a link that stays in the home is followed and the path passed to - the capture as named. Before, the first such path started a capture. -- `DesktopCaptureScope.test.ts`: the capture scope records each selected - path as named beside the physical path it walks. -- `DesktopApplicationExport.test.ts`: with `~/.config/MuseScore` selected as - a link to `~/settings/MuseScore` beside a selected note, the bundle's - launch opens the note. With only the capture's record of selected paths - added, the settings file was still a document and the launch opened none. -- `DesktopTaskDraftNotes.test.ts`: a draft whose only change between `seed` - and `end` is to the app's keys in dconf carries `uncheckable_changes` - naming `~/.config/dconf/user`, not `no_change`; one where only another - group's keys changed still has `no_change`. -- `appExportUnowned.test.ts`: `*.lock` and `*.lck` are locks only directly - in a state directory, so `Projects/.repo/Cargo.lock` is not; and 20,000 - separate unowned folders collapse in tens of milliseconds, where comparing - every pair took 12.9 seconds. -- `DesktopApplicationExport.test.ts`: `Projects/.repo/Cargo.lock` and - `.dotfiles/web/yarn.lock`, which the capture recognized as documents, and - a lock-named file the caller selected are seeded, a `*.lock` directly in a - state directory is left out, and the profile and document locks still are. -- `buildCaptureMcp.test.ts`: checkpoints acknowledged without - `changed_files` and `more_changed_files`, as the previous REA in a build - computer does, are taken with both `null`, also when a lost reply is read - again from the capture's log. Before, the host refused the acknowledgement - although the checkpoint was taken. -- `desktopCapture.test.ts`: a checkpoint's changed files name a document - under a selected path first, though the app did not hold it open, and - caches and browser-engine storage last, even one the app held open or in a - state directory, so ten KDE service-cache files no longer push the saved - document past the cut, as they did in a held-out Tellico build. -- `DesktopApplicationExport.test.ts`: with `~/.config/MuseScore` selected as - a link to `~/Documents` and the note inside it selected itself, the - launch opens the note while the settings beside it stay the app's; before, - the link's hidden name made the note application state and the launch - opened none. -- `DesktopTaskDraftNotes.test.ts`: a dconf database that changed but could - not be read gives `unreadable_changes` with the reader's error, not - `uncheckable_changes`. -- `buildCaptureMcp.test.ts`: `stop_build_capture` on a capture whose only - change between `seed` and `end` is a dconf database the draft cannot read - (no `dconf` on its `PATH`) returns the `unreadable_changes` note with its - `error`; before, the build tool dropped the field. -- `LinuxApplicationInventory.test.ts`: the inventory lists KDE's - `~/.config/rc` before it exists, so a Tellico capture owns - `~/.config/tellicorc`, whose absence brought back Tip of the Day at boot; - `DesktopApplicationExport.test.ts` shows such a file, written during the - capture, owned and seeded (that test passed before, given the inventory). - -The capture's recording of selected paths runs only on Linux; its scope is -tested on macOS, and the capture itself was not run. - -## GnuCash's dconf settings and book lock - -Run on macOS with source tests and gates; no build computer was started, so -dconf-cli reading a real build computer's database is not verified here. -Each test below failed before the change and passes now. - -- `appBuild.test.ts`, `buildComputerMcp.test.ts`: the build bundle installs - `dconf-cli` beside `libgtk-3-bin`, read from the module the fake runner - received. -- `desktopCaptureCli.test.ts`: a dconf database created before `seed` that - the export cannot read (`REA_DCONF_COMMAND` names no program) leaves - `DCONF = ""` and one limitation naming `~/.config/dconf/user` with the read - error; exported with the seed at `baseline`, when it did not exist yet, no - limitation names it. -- `appExportUnowned.test.ts`, `DesktopApplicationExport.test.ts`: - `Documents/household.gnucash.LCK` beside `Documents/household.gnucash` is - left out of the seed and listed after "Left out of the seed", in either - letter case, while a lone `Documents/notes.lck` is seeded and a `.LCK` whose - file lies in another folder is no lock. -- `buildComputerMcp.test.ts`: a bundle start that never got ready names a - seeded `q1.ods.LCK` beside `q1.ods`, and not a lone `notes.lck`. - -## Version-dotted entries, glibc's fatal errors and Grisbi's lock - -Run on macOS with source tests and gates; no build computer was started. -Each test below failed before the change and passes now. - -- `appExport.test.ts`: `org.gnumeric.gnumeric`, `com.github.xournalpp.xournalpp`, - `glabels-3.0`, `gimp-2.10`, `display-im6.q16` and `mousepad` name - `gnumeric`, `xournalpp`, `glabels`, `gimp`, `display-im6-q16` and - `mousepad`; before, `glabels-3.0` gave `app-0`. -- `buildComputerMcp.test.ts`: `start_build_computer` with `glabels-3.0` - returns `environment: "glabels"` and renders `envs/glabels`; the - reverse-DNS and plain entries keep their names. -- `DesktopApplicationExport.test.ts`: a capture whose desktop entry is - `glabels-3.0` exports as `glabels`, not `app-0`. With Grisbi's empty - `.household.gsb.lock` beside `household.gsb`, the lock is neither seeded, - in the bundle, nor named in the class module's text seeds, and is listed - after "Left out of the seed"; a lone `.notes.lock` is seeded. -- `appExportUnowned.test.ts`: `.household.gsb.lock` and `.household.gsb.lck` - beside `household.gsb` are locks; `.notes.lock` and `household.gsb.lock` - are not. -- `DesktopApplicationSession.test.ts`: the launched app's environment holds - `LIBC_FATAL_STDERR_=1`, read back from its stderr; this test runs on macOS - too. A real glibc abort was not reproduced. -- `DesktopApplicationExport.test.ts`: a seeded `registrymodifications.xcu` - ships without its `RecoveryList` item and keeps its other items; one - limitation and the README name it, and with the item's home path gone the - file is not listed as scrubbed. -- `desktopCapture.test.ts`: with `.config/libreoffice` selected, a file - there and a document the app held open precede twelve icons under its - `cache` folder, while a cache file selected itself still comes first. - -## Checkpoint order by window titles, and prompts that name the app - -Run on macOS with source tests and gates; no build computer was started. -Each test below failed before the change and passes now. - -- `desktopCapture.test.ts`: eight changed files come back in the wanted - order: a document only a window title names, a file selected itself, one - the app held open, one under the selected `.config/libreoffice`, one in a - state directory, the rest, a LibreOffice icon cache, and ghostwriter's - `QtWebEngine/Default/Visited Links` though it lies in a state directory. -- `DesktopApplicationSession.test.ts`: a checkpoint receives the titles the - app's own window has shown, not another app's; this runs on macOS too. - With the session's titles left out, it failed. -- `appExportUnowned.test.ts`: a whole `QtWebEngine` profile collapses to - that folder as browser storage, as do Chromium's `Visited Links`, - `Platform Notifications` and `user_prefs.json` elsewhere; the unowned - limitation counts "file(s) or folder(s)". -- `DesktopTaskExport.test.ts`: a task whose prompt does not name the app - gets one limitation naming the app; "In Notes, ..." gets none. - -## The app's logs - -Historical note: the filename-based exclusions described below were later removed; app-state logs are now retained. - -Run on macOS with source tests and gates. Each test below failed before the -change and passes now. - -- `appExportUnowned.test.ts`: `log.0`, `log.0.lck`, `20261106.log`, - `App.LOG`, `log.12`, `app.log.lock` and a file under `logs/` are logs; - `catalog.xml`, `logo.png`, `changelog`, `logs.json`, `blog.0`, `log.txt` - and `settings.lck` are not. -- `DesktopApplicationExport.test.ts`: Freeplane's `1.7.x/logs/log.0` and - its `log.0.lck` in a state directory, and QElectroTech's `.qet/20261106.log` - the app held open, are neither seeded nor in the bundle, and one limitation - and the README list them apart from the lock files; a selected `notes.log` - in the state directory and a document `build.log` are seeded. - -## Database journals and the recovery list's XML - -Run on macOS with source tests and gates. Each test below failed before the -change and passes now, except the parser's own range test, which is new -with the function. - -- `appExportUnowned.test.ts`, `DesktopApplicationExport.test.ts`: - `Local Storage/leveldb/000003.log`, a `000007.log` under a `leveldb` - folder and a `000005.log` beside `CURRENT` or `MANIFEST-*` are seeded; - Freeplane's and QElectroTech's logs and a numbered log with no LevelDB - beside it are still left out. -- `seedRecoveryList.test.ts`: recovery list items with single quotes, extra - whitespace and another prefix for the registry's namespace are cut, with - every other byte kept; the same text in a comment or CDATA is kept; a - registry that is not well-formed ships unchanged. -- `xmlDocument.test.ts`: element ranges run from the start tag's `<` to the - element's last `>` through CRLF and astral characters, the outermost - picked element only, and a malformed source is refused. - -## Titles that show a folder's path - -Run on macOS with source tests and gates. Each test below failed on the old -title rule and passes now. - -- `stateRoles.test.ts`: CherryTree's title names `home-notebook.ctd` but not - `~/.cache/dconf/user`, `~/.config/dconf/user`, a file named `Documents` or - a `.ctd` under `~/.cache`; `Makefile - Editor` and `~/src/Makefile - Editor` - name `~/src/Makefile`, and `/srv/Makefile - Editor` names no `~/Makefile`. -- `DesktopApplicationExport.test.ts`: with that title shape and both dconf - files changed, the export has one document and the launch opens it. -- `desktopCapture.test.ts`: the checkpoint leads with the document, not - `.cache/dconf/user`. -- `appExportUnowned.test.ts`: `plan.vym.lock` beside `plan.vym` and - `household.gsb.lock` beside `household.gsb` are locks; a lone - `notes.txt.lock`, and `Gemfile.lock` and `Cargo.lock` beside `Gemfile` and - `Cargo.toml`, are not. - -## Poedit's locks and seed modes - -Run on macOS with source tests and gates. Each test below failed before the -change and passes now. - -- `appExportUnowned.test.ts`: `poedit.lock`, `app.LCK` in the home and - `TranslationMemory/write.lock` are locks, while `Projects/*/Cargo.lock` - stays a project's; the held-open folders leave out the home for - `~/poedit.lock` and Lucene's folder, and keep `~/Documents` and - `/usr/lib/python3.12`. -- `DesktopApplicationExport.test.ts`: with Poedit's shapes the export seeds - the index segments but neither lock, does not own `poedit.lock`, lists - `write.lock` as left out, and names `~/poedit.lock` in no limitation; a - `0600` and a `0755` seed are listed in `SEED_MODES`, a `0644` one is not. -- `desktopExportPython.test.ts`: `_seed_home` gives each file in - `SEED_MODES` its mode. - -## Limits of this verification - -- The witness acts were scripted by this agent from the task's prompt; no - separate solving agent ran, and the exported `verify.py` was not run. -- Only the local provider on amd64, and only Mousepad. diff --git a/docs/specs/desktop-app-environments/capture-for-building/plan.md b/docs/specs/desktop-app-environments/capture-for-building/plan.md deleted file mode 100644 index b05887eb01..0000000000 --- a/docs/specs/desktop-app-environments/capture-for-building/plan.md +++ /dev/null @@ -1,23 +0,0 @@ -# Plan - -1. Checkpoints: `versionAt` and `StateEnds` beside the state view's schema - in `src/domain/desktop/desktopState.ts`, since the draft is domain code; - `selectStateEnds` in `DesktopStateVersions.ts` turns names into positions - and refuses under the calling operation. The export's plan, its task - validation and the draft read every file through `versionAt`. -2. apt folders: `parseAptConfigShell` in `aptRepositories.ts` and - `resolveAptLocations` in `AptRepositoryInventory.ts`, called once per - Debian package with the host's folders as the fallback. -3. Launch: `applicationEnvironment` in `DesktopApplicationSession.ts` filters - the environment the owned process is spawned with. -4. Identity: `host.hostname` and `host.user` in the capture schema and - record; `src/domain/desktop/hostIdentity.ts` owns the matching rules, the - replacements and the per-seed decision, used by the export and by the task - refusal. The bundle files move to `DesktopExportFiles.ts`, which rewrites - seeds as it copies them and writes the README last, listing them. -5. CLI options, the guides, this spec and its verification. -6. Tests first: domain rules, the seed and end scenario through the export - and the draft, the export's scrub with a dconf database and a binary seed, - apt folders from a stub and from real `apt-config`, the launch environment - and the recorded host on Linux, and the CLI options; then Mousepad in the - Ubuntu 24.04 container. diff --git a/docs/specs/desktop-app-environments/capture-for-building/spec.md b/docs/specs/desktop-app-environments/capture-for-building/spec.md deleted file mode 100644 index 6ea8b9a8cc..0000000000 --- a/docs/specs/desktop-app-environments/capture-for-building/spec.md +++ /dev/null @@ -1,76 +0,0 @@ -# Capture for building - -## Outcome - -REA's capture, state view, task draft and export fit a build in which an -agent drives the application inside an agentenv computer, makes the seed and -then the change in one capture, and exports a bundle that can be shared. The -seed is the state at a checkpoint the agent names rather than the state before -launch; the capture finds the package's sources from lists an ordinary user -downloaded; the application does not inherit the computer's control token; -and the bundle holds neither the capture host's name nor its user's. - -## Requirements - -- Checkpoints: the export takes `--seed-checkpoint` and `--end-checkpoint`, - and the task draft the same two options. The seed checkpoint chooses the - seed files, their text formats, the unseeded files and the dconf keys; the - end checkpoint is where a task's checks must all pass, the seed where at - least one must fail; the draft compares the two. A file's state at a - checkpoint is its last version recorded at or before it. Without the - options they are the baseline and the capture's last checkpoint, so earlier - captures export and draft as before. A name the capture does not hold - exactly once, and an end before the seed, are refused naming the option. - The export reports both names in `checkpoints`, and the draft in its own - `checkpoints` as `baseline` and `final`. -- apt folders: the lists folder, the trusted parts folder and the trusted - keyring are where `apt-config shell` resolves `Dir::State::Lists/d`, - `Dir::Etc::TrustedParts/d` and `Dir::Etc::Trusted/f`, so an `APT_CONFIG` - file that moves them is followed; each is apt's default when `apt-config` is - missing, fails or names no absolute path. -- Launch environment: the application gets REA's environment without any - variable whose name starts with `AGENTENV_`, plus the run token. -- Host identity: the capture records `host.hostname` and `host.user`, each - optional, so captures written before parse; one is left out when the system - cannot say. -- Scrub: the export replaces `user@host` with `user@localhost`, the host name - as a whole name with `localhost`, and the captured home where a whole path - segment ends after it with `/home/user`, in seeded text files read as - UTF-8, in UTF-16 seeds with a byte-order mark, and in the dconf keys. A - host named `localhost` keeps that name, but its captured `user@localhost` - is still replaced. The user name alone is never replaced. JSON is scrubbed - by its string values, decoded, never its member names, and XML by its - decoded character data and attribute values, plus comments and CDATA, so - neither's syntax or names change and escapes hide nothing; a UTF-16 seed is - scrubbed by the format its text would have in UTF-8. dconf keys are - scrubbed by their decoded GVariant strings, never group names, keys, - dictionary keys or other values, and a value that does not parse or holds - an object path or signature ships as captured. A rewritten seed is a - generated file with its own SHA-256. The class's `SEED_HOME` is `/home/user`, which it respells - to the computer's home at boot as before. A capture whose home is already - `/home/user`, as inside a computer, has no home to replace. A capture - without the host's name and user has only its home replaced, with a - limitation. -- Leftovers: every shipped file, generated ones included, is searched in its - path and content, escapes decoded, for the host name and `user@host` - anywhere and the captured home as a whole path, with the replacements set - aside. `scrubbed_files` lists the rewritten seeds and `unscrubbed_files` - every file found, by bundle path; the README lists both. gzip seeds - compressed again only to clear their headers, their documents unchanged, - are in `recompressed_files` instead, which the README counts. -- Tasks: checks whose values name `user@host` or the host name by that rule - are refused, like those that name the captured home, but not for their - field names, kind or id; and the checks that must fail on the seed are - evaluated on the seed as the bundle ships it. A value check is refused as - pointing into text only when its file is text at the seed or the end - checkpoint, so versions before or after them do not count. - -## Non-goals - -- No MCP tools, no build computer, no control channel with acknowledgements - and no witness; later steps own those. -- No change to captured Evidence or the state view's views: they keep the - captured bytes, and only the bundle is scrubbed. -- No rewriting of binary files, SQLite databases or file names, and no - replacement of the user name standing alone. -- No change to the draft's field names, `baseline` and `final`. diff --git a/docs/specs/desktop-app-environments/capture-for-building/verification.md b/docs/specs/desktop-app-environments/capture-for-building/verification.md deleted file mode 100644 index 0adce414ee..0000000000 --- a/docs/specs/desktop-app-environments/capture-for-building/verification.md +++ /dev/null @@ -1,186 +0,0 @@ -# Verification - -Run on 2026-11-05 on top of the namespaced XML and capture fixes branches: -gates and source tests on macOS 26.5 with Node v22.23.1 and Python 3.11.14; -Linux tests and the end-to-end capture in an Ubuntu 24.04.5 arm64 container -with Node v24.22.1, Python 3.12.3, apt 2.8.3, Xvfb, xfwm4 and Mousepad -0.6.1-1build2, run as the ordinary user `ada` on a container whose host name -is its id. - -## Gates - -- `npm run typecheck`, `format:check`, `build:cached`, `knip`, `jscpd`, - `docs:check`, `docs:build`, `verify:test-discovery` and - `verify:architecture-guards`: passed. `lint` and `lint:typed` fail only on - main's own `tests/acceptance/webSourceLocationCli.test.ts`, with no - diagnostics in the touched files. Of the two clones jscpd lists in touched - files, one is a new test's nine-line import block and the other a pair of - cancellation tests already in `DesktopApplicationCapture.test.ts`. -- `npx vitest run src/domain/desktop src/application/desktop src/desktop` - with `tests/boundary/providers/desktop*.test.ts` and the desktop CLI - boundary tests `cliStartupImports`, `desktopCaptureCli`, - `desktopApplicationCli`, `cliInputSchemaRequired` and `cliToolCoverage`: - 468 passed and 20 skipped on macOS (the Linux-only cases); 485 passed and 3 - skipped in the container. - -## Tests - -Each new test fails on the code before this change, run from that code with -only the new tests and fixtures added: on macOS for the source and CLI tests, -in the container for the three Linux-only ones. - -- The scenario: a capture where the app saves a new note before `seed`, edits - it before `end`, and writes its settings as it exits. Exported with - `--seed-checkpoint seed --end-checkpoint end`, the bundle seeds the note as - saved at `seed` and the settings as they were then, and a task whose check - of the edit fails at `seed` and passes at `end` is kept. A check that holds - only at `exit` is refused with the end at `end` and kept with the end left - to default. Without the options the seed is the baseline, without the note. - The draft between the two lists only the note, with `eggs` added. An - unknown name and an end before the seed are refused naming the option, - under the export's and the draft's own operations, and write no bundle. - The same options through the public CLI, with a refusal's structured - issue. -- The scrub's rules: Geany's `pref_template_mail=ada@e81232be457d` becomes - `user@localhost` while `pref_template_developer=ada` stays; the host name - alone becomes `localhost` but not inside `xe81232be457d`, before `-2` or in - `e81232be457d.local`, and a host named `ubuntu` leaves - `ports.ubuntu.com/ubuntu-ports` alone; the home where a path segment ends, - not `/home/adam` or `/home/ada.bak`; only the home for a capture without - the host's name and user; a UTF-8 byte-order mark kept; UTF-16 seeds in - both byte orders; leftovers found in a binary database and in - `e81232be457d.local`; nothing to replace in a capture whose home is - `/home/user`. -- Through the export: a capture whose settings file, SQLite database and - dconf keys name the host and user. No bundle file but the database holds - the host name, `ada@` or `/home/ada`; the settings seed is rewritten, the - class holds `SEED_HOME = "/home/user"` and the scrubbed dconf keys, and the - result and README list the rewritten settings and the database. Checks - naming `ada@e81232be457d` or the host name are refused; a capture written - before the host was recorded still parses and has its home replaced. -- apt folders: lists in the folder a stubbed `apt-config` names, with a - quoted `'` in its name, are found, and the default folder is used when - `apt-config` fails or is missing (adapter test); on Linux, real - `apt-config` under an `APT_CONFIG` file resolves `Dir::State::Lists` - relative to `Dir::State`, and a missing `apt-config` gives the defaults. -- Linux: a launched shell's environment has no `AGENTENV_*` variable while - it keeps the others and the run token; a capture of the fake application - records the host's name and user as Node reads them. - -## Mousepad end to end - -As `ada`, with no apt lists in `/var/lib/apt/lists`, an `apt-get update` -under an `APT_CONFIG` naming `/tmp/apt-user/lists` and `/tmp/apt-user/cache` -wrote 15 Packages lists there. With that `APT_CONFIG` and -`AGENTENV_CONTROL_TOKEN` set, `capture-desktop-application --desktop-entry -org.xfce.mousepad` ran while `xdotool` typed `milk` and -`from ada@`, saved the file as `~/Documents/list.txt`, sent -`checkpoint seed`, typed `eggs`, saved, sent `checkpoint end` and then -`stop`. - -- Mousepad's environment held the run token and no `AGENTENV_*` variable. -- The package is `mousepad` 0.6.1-1build2 from - `http://ports.ubuntu.com/ubuntu-ports noble/universe arm64 Packages`, origin - `Ubuntu`, with `package_lists_present` true and no apt limitation. -- `host` records `/home/ada`, the container's host name and `ada`; the - checkpoints are `baseline`, `seed`, `end`, `stop` and `exit`. -- The draft between `seed` and `end` lists `Documents/list.txt` with `eggs` - added and suggests `lines_present` of `eggs`. -- The export with `--seed-checkpoint seed --end-checkpoint end` and that check - kept the task (`failing_on_seed: ["eggs"]`), seeded `list.txt` as - `milk\nfrom user@localhost\n` and listed it in `scrubbed_files`; - `unscrubbed_files` is empty and no bundle file holds the host name, `ada@` - or `/home/ada`. The dconf keys' recent file is - `file:///home/user/Documents/list.txt`. A task checking the line - `from ada@` was refused, and the export without options seeded - nothing, since the note did not exist at the baseline. -- The exported module's own `_seed_home` wrote `list.txt` unchanged into - another home and respelled the dconf keys' path to it. - `python -m agentenv_protocol.computer._declare` of agentenv-framework - 0.9.1431 declared the class, and `agent-env run --task smoke --dry-run` - planned the deploy. - -## Review fixes - -Run on 2026-11-05 on the same toolchains, after the first review. Each new -test failed on the reviewed head, with only the new tests added, and passes -now. - -- A task's seed checks read the seed as the bundle ships it. A mail setting - changed from `ada@e81232be457d` to `user@localhost` already reads - `user@localhost` in the scrubbed seed, so its check is no longer counted as - failing there: `failing_on_seed` went from `mail` and `note` to `note`. -- JSON is scrubbed by its strings' decoded values, so a host named `true` - leaves `{"enabled": true}` valid and a `\u0065` escape no longer hides the - host; an untouched string keeps its escapes. XML is scrubbed in its decoded - character data and attribute values, comments and CDATA, so a host named - `item` leaves `` alone and `e` references hide nothing; the - output is still read as XML. -- One search for what is left covers every shipped file, in its path and its - content: a clean seed named `e81232be457d-notes.txt`, the class module - whose dconf keys hold `ada@e81232be457d.local` and the README that lists - them are listed in `unscrubbed_files`, which now names bundle paths and - equals an independent search of the bundle. A task check holding - `e81232be457d.local` is refused by the same rule. The replacements are set - aside, so a host named `host` is not found in `localhost`. -- A host named `localhost` keeps that name, but `ada@localhost` becomes - `user@localhost`, and a binary file holding it is reported. -- A second review found member names rewritten too: on a host named - `ubuntu`, `{"ubuntu": 1, "localhost": 2}` got two `localhost` keys. Names - are now kept, an escaped one before a colon on the next line included, and - a seed whose JSON key holds the host ships as captured and is listed in - `unscrubbed_files`. -- The same review found that the regular expression that found JSON strings - threw `RangeError: Maximum call stack size exceeded` on one string of - 16,000,000 characters, which a 64 MiB capture can retain, so such a seed - stopped the export. The scrub now walks the document one string at a - time, and that seed is scrubbed in about 20 ms. The XML expressions, run on - a comment, CDATA section, processing instruction, attribute value and text - of the same length, finished within 6 ms each. - -The gates passed as before, `lint` and `lint:typed` again failing only on -main's `webSourceLocationCli.test.ts` with no diagnostics in this change's -files; the desktop tests ran 483 passed and 20 skipped on macOS, and 500 -passed and 3 skipped in the container, where the Mousepad run above gave the -same result, its rewritten seed now listed by bundle path. - -A third review found four more. Each new test failed on the reviewed head and -passes now; `src/domain/desktop`, `src/application/desktop` and -`tests/boundary/providers/desktop` ran 404 passed and 11 skipped on macOS. - -- dconf keys were scrubbed as one text, so on a host named `true` the setting - `wrap=true` became `wrap=localhost`, which `dconf compile` refuses, and - keys and group names could be renamed. Only decoded GVariant strings change - now; a value that does not parse ships as captured and the class module is - listed in `unscrubbed_files`. -- A task's check was searched as serialized JSON, so on a host named `file` - or `kind` every check was refused for its field names. Only its values are - searched now, not its field names, kind or id. -- A value check was refused when its file was text at any recorded version; - an empty `.json` before `seed` or after `end` refused a task whose file is - JSON at both. Only the seed, as shipped, and the end are read now. -- UTF-16 JSON and XML were scrubbed as plain text, so on a host named - `ubuntu` `{"ubuntu": 1, "localhost": 2}` got two `localhost` keys. They are - scrubbed by the format their text would have in UTF-8, in their own byte - order. - -## UTF-16 format detection - -- A decoded UTF-16 seed's scrubber is chosen by a syntax pass that builds - no value or document (`textSyntaxFormat`: the JSON token scan, and the - XML parser's events with only the open elements kept), and the XML - scrubber copies out only changed spans. A UTF-16 XML seed of a million - elements is scrubbed in a 24 MiB heap, where the previous code needed - more than 768 MiB; `desktopStateHeap.test.ts` runs it in 32 MiB and failed - on the previous code. On 200,000 random XML-like inputs and 80 UTF-16 - cases the output is byte-identical to the previous code's. - -## Limits of this verification - -- The bundle was not run in an agentenv computer, and REA was not run inside - one; the build computer is a later step. -- Geany's leak is covered by a fixture with its line, not by capturing - Geany. No real application was captured with a UTF-16 seed or a binary - file holding the host name. -- The apt-config fallback for a missing command and a failing one is covered - by the adapter test, and the real command only on Ubuntu 24.04. diff --git a/docs/specs/desktop-app-environments/capture/plan.md b/docs/specs/desktop-app-environments/capture/plan.md deleted file mode 100644 index d71954fe57..0000000000 --- a/docs/specs/desktop-app-environments/capture/plan.md +++ /dev/null @@ -1,15 +0,0 @@ -# Plan - -1. Pure parsers: desktop entries and `Exec` lines, `xprop` output, dpkg and - apt-cache output, package kinds from paths, and the walk diff. -2. Host adapters: the home walk, the content store, the application - inventory, the `xprop` window observer and the session loop. -3. Application service: host checks, checkpoints, Evidence and the capture - folder. -4. CLI: `capture-desktop-application`, stdin requests and progress lines. -5. Docs: the user guide and links from the index, sidebar, README and CLI - reference. -6. Tests: parser units, adapter tests on temporary trees, service refusals, - and two Linux captures of a fake application with a stub `xprop`. -7. End to end: Mousepad in an Ubuntu 24.04 container under Xvfb and xfwm4, - driven by `xdotool`, with a screen recording. diff --git a/docs/specs/desktop-app-environments/capture/spec.md b/docs/specs/desktop-app-environments/capture/spec.md deleted file mode 100644 index 06ba4ca40c..0000000000 --- a/docs/specs/desktop-app-environments/capture/spec.md +++ /dev/null @@ -1,136 +0,0 @@ -# Capture a Linux desktop application in use - -## Outcome - -`rea capture-desktop-application` launches an installed Linux desktop -application on the user's X11 display, watches it while a person or a driver -uses it, and writes a capture folder: Evidence in `capture.json` and the bytes -of retained files in `content/`. The Evidence says what the -application is and how it was installed, how to launch and recognise it, when -its window appeared, and how files under the home directory changed between -checkpoints, with the content of the files involved. Later steps read this -folder to build the environment; this step builds nothing. - -## Requirements - -- The baseline records each observed non-file path and its type without - following symlinks, so a later state reader can distinguish an absent SQLite - sidecar from an observed non-file. - -- The command is CLI only. A capture is a long interactive session whose - checkpoints come from stdin lines (empty, `checkpoint [name]` or other - text) and which ends on `stop` or the end of stdin, when the launched - process has exited and the application's processes and windows are gone, - or at the time limit. One queued line is handled per sample, and stdin - reading pauses while 16 wait. A repeated name or one of the capture's own - names (`baseline`, `stop`, `time-limit`, `exit`) is refused on stderr and - the session continues. The application has exited only after two - consecutive samples with the launched process gone, no process carrying the - run token left, and a window list that was read and holds none of its - windows; an unreadable list counts as unknown and is named in the - limitations. -- It runs only on Linux with `DISPLAY` set and `xprop` available (or - `REA_XPROP_COMMAND`). Before writing or launching anything it refuses other - hosts, a request naming neither or both of `--desktop-entry` and - `--executable`, an empty `--state-path`, `--exclude` or `--output` value, - a program found only through a relative or empty entry of the host's - `PATH` (lookup follows the launch's search order; an `env` prefix's `PATH` - travels with the command and may hold such entries), - an output folder that is not new or empty or is owned by another user, an - unreadable window list, a window manager that does not publish - `_NET_CLIENT_LIST` (EWMH), and an application that already has a window - open. The output folder is made private (0700) and its files are - created exclusively (0600). -- The inventory resolves a desktop entry id through `$XDG_DATA_HOME` and - `$XDG_DATA_DIRS`, following an entry installed as a symbolic link, expands - its `Exec` line with no files and appends `--argument` values, resolves the - program on `PATH` (the one an `env NAME=value` prefix sets, whose XDG - folders also name the state directories), and identifies the package: - snap, flatpak and AppImage from paths (and the AppImage magic, and a - `flatpak run` launch), otherwise - the dpkg owner of the launched desktop entry, or else of the executable, - with its version, architecture, the apt sources listing the - installed version and the `o=` origin apt reports for each source. An XDG - base folder variable names a folder only when its value is an absolute - path, as the XDG Base Directory Specification requires, so a relative value - leaves the home default in use instead of naming a folder under the working - directory. The entry's package is the one that installs the application: - LibreOffice Writer's entry belongs to `libreoffice-writer`, while the - `libreoffice` it runs belongs to `libreoffice-common`, which does not - depend on Writer. When the two differ, `executable_package` names the executable's, with - `executable_package_reason` when neither the Ubuntu 24.04 archive nor a - declared vendor repository offers it or apt could not say; each vendor - repository records in `supplies` the library packages and executable's - package only vendor repositories offer that its package files list. When - a package owns the entry but none owns the program, nor the file it resolves - to, `executable_package_reason` says so without `executable_package`. A - `dpkg-query` lookup that does not finish or exits with an error leaves the - package - `unknown`, with a limitation naming the path. It marks - Electron applications by the fuse sentinel or `resources/app.asar`, and - lists candidate state directories under the XDG folders and dot-folders - named after the package, executable, desktop entry's full id and last part, - and name, and every folder present there whose name is one of those in - another letter case, such as GIMP's `~/.config/GIMP`, and KDE's - `rc` in the config folder, such as `~/.config/tellicorc`; a `flatpak run` - launch uses the application id (its first operand - after options and their values) instead of the launcher's name and adds - `~/.var/app/`. An `--executable` runs from the caller's - directory, which also resolves a relative path to it. -- Paths are compared in their physical spelling. The walked roots are the - home directory and every content root outside it: the state directories, - `--state-path` values and absolute arguments other than `/` or a directory - containing the home directory, which the limitations name instead, plus the - `-wal` and `-journal` paths beside each of those selected paths that is not - a directory, so a database selected on its own is captured with its logs. - Each selected path is also recorded as named, beside its physical - spelling, so a role can follow from the name the caller gave it. The - baseline walk runs before launch and retains every file under the content - roots; each later checkpoint reports created, modified, deleted and retyped - paths against the previous walk and retains every changed file. A creation - or deletion is reported only where the walk listed the path's nearest - existing directory completely; the rest are counted as unconfirmed. Walks - do not follow symbolic links, do not enter a directory on another device - than their root (the limitations name each such mount point), leave out the - output folder and `--exclude` paths, which the capture records as - `excluded`, and stop at `--max-entries`, roots included. -- Retention opens files without following links or blocking, keeps a file - only if it is still the version the walk recorded and does not change while - read, respects `--max-file-bytes`, and charges `--max-content-bytes` only - for content not already stored. A file over the remaining budget is not - read unless stored content of the same size could make it a duplicate. - Every omission is recorded with its reason. -- The application is launched through REA's owned process path: its own - process group and a run token in its environment. Every half second the - session reads its process tree from procfs, the client list with `xprop`, - and the files its processes hold open under the walked roots. A window - belongs to the application by live owner pid or by class (including the - entry's full id and a flatpak's application id), re-evaluated every sample; - a flatpak's windows are matched by class only. A matching window's pid is - followed too. Processes are identified by pid and start time, and each - records whether the capture started it: the launched process, a run-token - carrier or a descendant of one. -- When the session ends it records a `stop` or `time-limit` checkpoint if the - application is still running, sends SIGTERM to the launched process, its - process group and every process carrying the run token, waits up to five - seconds, removes every process still carrying the run token, and records an - `exit` checkpoint. Processes without the token are never signalled outside - the launch group. Cancellation ends the session without further - checkpoints, releases the application the same way, and still writes the - capture with end reason `cancelled`; cancellation before launch writes no - capture and removes the retained content. Any other failure before `capture.json` is written releases the - application the same way and removes the retained content; processes or - files that remain are reported as cleanup facts with the failure. -- The Evidence uses provider `rea-desktop` version 1, operation - `capture_desktop_application` and predicate type - `rea.desktop-application-capture`; its parameters carry only counts and the - launch kind. - -## Non-goals - -- No state view, format readers, export, tasks or verification; later steps - own those. -- No click or keystroke recording, no Wayland-native windows, no MCP tool. -- No writer attribution. State-directory and open-file markers are evidence, - not proof. -- No redaction of the user's files. The capture folder is private data. diff --git a/docs/specs/desktop-app-environments/capture/tasks.md b/docs/specs/desktop-app-environments/capture/tasks.md deleted file mode 100644 index 05b57f9db5..0000000000 --- a/docs/specs/desktop-app-environments/capture/tasks.md +++ /dev/null @@ -1,14 +0,0 @@ -# Tasks - -- [x] Record the outcome, requirements and non-goals. -- [x] Parse desktop entries, `Exec` lines, `xprop`, dpkg and apt-cache output. -- [x] Walk home state, diff walks and retain content by SHA-256. -- [x] Build the inventory: entry, launch command, program, package, Electron markers, state directories. -- [x] Watch processes, windows and open files; take checkpoints from stdin; stop and terminate. -- [x] Write `capture.json` Evidence and the content folder. -- [x] Register the CLI command and document it. -- [x] Add unit, adapter, service and Linux capture tests. -- [x] Capture Mousepad end to end in a container. -- [x] Run the gates and record verification. -- [x] Take a Debian package from the launched desktop entry's owner (LibreOffice Writer). -- [x] Find state folders named after the application in another letter case (GIMP). diff --git a/docs/specs/desktop-app-environments/capture/verification.md b/docs/specs/desktop-app-environments/capture/verification.md deleted file mode 100644 index 1a1aea1553..0000000000 --- a/docs/specs/desktop-app-environments/capture/verification.md +++ /dev/null @@ -1,138 +0,0 @@ -# Verification - -Run on 2026-11-03 against main `d7df9df33`: gates and source tests on macOS 26.5 -with Node v22.23.1; Linux tests and the end-to-end captures in an Ubuntu 24.04.5 -arm64 container with Node v24.22.1, Xvfb, xfwm4 and Mousepad 0.6.1-1build2. - -## Gates - -- `npm run typecheck`, `lint`, `lint:typed`, `format:check`, `knip`, - `knip:production`, `jscpd`, `docs:check`, `mcp-catalog:check`, - `verify:test-discovery`, `verify:architecture-guards` and `scan:todos`: - passed. Lint and typed lint report no diagnostics in the new files. -- `npx vitest run --project domain --project services --project adapters` on - macOS: 21,581 passed, 29 skipped, 5 failed. The same 5 fail on main in the - same environment (two zstd cases, Inspector target authorization - cancellation, and two `setupEnvironment` cases). -- `npx vitest run --project cli-boundary` on macOS: 1,499 passed, 5 skipped, 39 - failed. 38 of them fail on main in the same environment (client profiles, - setup, doctor and version reports). The 39th, `closedStdout`, passed three - runs out of three when rerun alone. -- The new domain, adapter and service tests on Linux: 51 passed, including - five captures of a fake application with a stub `xprop`: a requested - checkpoint with the state change and its content, an application that exits - on its own, a refusal while the application's window is already open, a - refusal when the window list cannot be read, and a cancellation after a - checkpoint that still writes the capture and verifies cleanup. - -## Mousepad end to end - -`capture-desktop-application --desktop-entry org.xfce.mousepad` ran as an -ordinary user while `xdotool` typed a line, sent `typed`, saved the file as -`~/Documents/groceries.txt` through the Save As dialog, sent `checkpoint saved` -and then `stop`. The session was recorded with `ffmpeg` (30 seconds). - -- Inventory: the entry's `Exec=mousepad %U` became `["mousepad"]`; the - package is `mousepad` 0.6.1-1build2 from - `http://ports.ubuntu.com/ubuntu-ports noble/universe arm64 Packages`; no - Electron markers. -- Session: the first window appeared after about 530 ms; the Mousepad window's - titles went from `Untitled 1 - Mousepad` to `*Untitled 1 - Mousepad` to - `~/Documents/groceries.txt - Mousepad`; the `Save As` dialog was recorded as a - dialog of the application; the progress terminal's window was recorded and - not attributed. The window match is class `Mousepad`, instance `mousepad`. - The session ended on `stop` after 25.9 s and Mousepad exited with code 0. -- Cleanup: verified; the only process recorded was `mousepad`, carrying the - run token. -- State: checkpoints `baseline`, `typed`, `saved`, `stop` and `exit`, none - with unconfirmed changes. `saved` holds `~/Documents/groceries.txt` as - created, and its retained content is `Groceries: milk, eggs, coffee` with a - matching SHA-256. `exit` holds `~/.config/Mousepad/accels.scm`, marked as a - state directory. The dconf database, the window manager's settings and GTK's - recently used list also changed and are not marked. Nine files were retained - and none were omitted. - -A second run started Mousepad before the capture. The capture refused with -`The application is already open: "Untitled 1 - Mousepad" (pid 35).` and wrote -nothing to the output folder. Before that refusal existed, the same setup -showed Mousepad handing the launch to the running instance, which opened a new -tab in its existing window while the launched process exited at once. - -## Fixes after the five-application test - -Run on 2026-11-05 on macOS 26.5 with Node v22.23.1. A test that captured and -exported five applications found two inventory gaps: - -- LibreOffice Writer, captured with `--desktop-entry libreoffice-writer`, - recorded `libreoffice-common`, the owner of the `/usr/bin/libreoffice` its - entry runs, which does not depend on Writer. The exported computer installed - only that package and failed its readiness check with - `no window with class 'libreoffice-writer'`. The package is now the entry's - owner, with the executable's in `executable_package`. Adapter tests on a - fake dpkg host whose entry and program have different owners cover an entry - launch, an `--executable` launch, an entry no package owns and a - `--package-file` matched against the entry's package. -- GIMP 2.10 keeps its profile in `~/.config/GIMP/2.10`, which no candidate - name (`gimp`) matched, so it was neither seeded nor reset. A folder in the - XDG folders or the home whose name is one of the candidate names in another - letter case is now a state directory, and the state view counts a path in a - folder beside a state directory that differs from it only in case as in it. - An adapter test with GIMP's layout and a domain test cover both, and leave - out `GIMPshop`, `MyGIMP` and a nested `Other/GIMP`. - -Review of those fixes found three more gaps, each now covered by a test that -failed on the first fix: - -- The entry's package need not depend on the program's (`vim-common` owns - Vim's entry, `vim` its program), so the export now installs - `executable_package` by name beside the app's package, for archive, vendor - repository and package-file installs alike. The capture checks it by the - library packages' rule and records `executable_package_reason` when neither - the archive nor a declared repository offers it, or apt could not say; the - export then refuses. Adapter, domain and export service tests cover the - record, the three install paths, the refusal and the rendered - `Packages(apt=[...])`. -- A profile folder created during the capture in another letter case than its - candidate was application state but owned as the folder of its first file - (`.config/GIMP/2.10`), so later files elsewhere in it escaped `data/get` and - `data/reset`. Owned paths now use the same match as roles and own - `.config/GIMP` in the files' spelling; a domain test and an export service - test of a created profile cover it. -- A `dpkg-query -S` that timed out or exited with an error counted as "no - owner", so a failed entry lookup quietly recorded the program's package. It - now leaves the package `unknown` with a limitation naming the path, for the - entry and the executable, after a timeout or an exit status of 2. - -A later review found that both the program's package and library packages -were approved at capture against every repository with a verified key, while -the content budget can then drop a repository's key and the export leaves that -repository out. Repositories now record what they `supply`, and the export -leaves out library packages, and refuses a program's package, that only -repositories it leaves out supply. A capture adapter test, two export domain -tests and a key-retention service test that drops one of two keys under the -per-file limit cover it. - -A third review found that an entry owned by a package whose program no -package owns, such as a `~/.local/bin` program found first on `PATH`, was -recorded as the entry's package alone, which the export then installed though -it does not bring that program. The capture now records that no package owns -the program, and the export refuses it. An adapter test, an export domain test -and an export service test cover it, and an adapter test keeps a program link -whose resolved file dpkg owns counted as owned. - -Each new test failed on the code before its fix, run in a copy of that commit -with only the new tests added. `npm run typecheck`, `lint`, `lint:typed` -(no diagnostics in the touched files), `format:check`, `build:cached`, -`knip`, `jscpd`, `docs:check`, `docs:build`, `verify:test-discovery` and -`verify:architecture-guards` passed, and -`npx vitest run src/domain/desktop src/application/desktop src/desktop tests/boundary/cli/cliStartupImports.test.ts` -ran 351 passed and 18 skipped. Neither application was captured again. - -## Limits of this verification - -- Only Mousepad was captured end to end, on arm64 in a container. GnuCash, - Joplin and a full desktop VM are for later steps. -- No real snap, flatpak or AppImage application was captured; those paths are - covered by parser tests only. -- The time limit is covered by code review, not by a test. Cancellation is - covered by a Linux test with a fake application, not by Ctrl-C on Mousepad. diff --git a/docs/specs/desktop-app-environments/document-views/plan.md b/docs/specs/desktop-app-environments/document-views/plan.md deleted file mode 100644 index 45d4cee6fc..0000000000 --- a/docs/specs/desktop-app-environments/document-views/plan.md +++ /dev/null @@ -1,26 +0,0 @@ -# Plan - -1. Format and reader: `zip` detected by its local file header or an empty - classic/Zip64 archive signature; the text, JSON, - key file and XML readers shared as `textualView`, so a file and an entry - read alike; a domain module for the entry limits, the entry view and the - archive view, and an application reader that walks the verified bytes with - zip.js under the options and name decoding `ZipArtifactReader` uses. -2. Selectors: `locatePointer` in `src/domain/desktop/viewPointer.ts`, used by - REA's evaluator and the draft, and `_locate` in the exported verifier, with - the same messages; `tolerance` in the task schema and both evaluators. -3. Changes and draft: member keys chosen per array from the candidate - selectors of both versions, a keyed walk for zip views in `compareTrees`, - and a walk that notes a member added or removed whole once for the draft's - archive suggestions. -4. Exported module: `_zip` and `_entry_view` beside `_view`, with - `zipfile`, `zlib` and `hashlib` imported at the top. -5. Docs and tests: real FreeCAD 0.21 and 1.0 `Document.xml` files zipped into - `.FCStd` archives and checked by both evaluators, an `.odt` built in the - test, archives crafted for each limit, and the shared check cases run - through both evaluators. -6. Namespaced XML: the exported module reads XML with `expat` rather than - `ElementTree`, one pass with namespace processing to check the document and - one without to build the view as REA's DOM does, names and text nodes - alike; the export's namespace refusal and the draft's namespace gate go. - Parity tests read real Inkscape and LibreOffice Writer saves. diff --git a/docs/specs/desktop-app-environments/document-views/spec.md b/docs/specs/desktop-app-environments/document-views/spec.md deleted file mode 100644 index af4012add2..0000000000 --- a/docs/specs/desktop-app-environments/document-views/spec.md +++ /dev/null @@ -1,110 +0,0 @@ -# Documents saved as zip archives - -## Outcome - -A document an application saves as a zip archive, first FreeCAD's `.FCStd`, -is read into a view of its entries, so a task can check what the user did in -it. Checks name the XML elements they read by tag and attribute rather than by -position, so the same check holds across application versions that write the -document in another order, and compare numbers written as text within a -tolerance. XML that uses namespaces, as OpenDocument's `content.xml` and -Inkscape's SVG do, is named by the prefixes the document spells. Both -evaluators, REA's and the exported verifier's, agree. - -## Requirements - -- Format: a file starting with a zip local file header (`PK\x03\x04`), or - a classic/Zip64 empty-archive signature with at least 22 bytes, is `zip`, - whatever its name. A signature is not proof of directory validity. Its view is - `{entries, entry_count, truncated}`: the file entries in archive order, - directories left out, each `{name, size, sha256, format, view, view_error}`. -- Reading: from the retained bytes already checked against their digest, in - memory, with REA's zip reader options (CRC-32 and overlap checks, CP437 or - UTF-8 names); nothing is extracted. Each entry's format and view come from - the state view's own readers and limits, with the entry name in place of the - file name. A SQLite or dconf database, or an archive, inside an archive is - not read and says so. -- Limits: at most 1,000 entries listed (`entry_count` counts all); an entry is - read only when it is unencrypted, stored or deflated, at most 16 MiB - uncompressed and at most 100 times its compressed size, and while the - archive has read at most 64 MiB. An entry over a limit, or whose data fails - its checks, has `sha256`, `format` and `view` null and a `view_error`. -- Exported module: `data/get` gives the same view, read with Python's - `zipfile` from the file in place with the same limits, order of checks and - wording; parity tests compare the two readers on the same archives. -- XML names: both readers name elements and attributes as the document spells - them, prefix included (`text:p`, `sodipodi:docname`), an element in a - default namespace by its bare name (`svg`), and keep namespace declarations - as the attributes `xmlns` and `xmlns:PREFIX`, in document order. The - exported module reads XML with `expat` twice: with namespace processing, to - refuse what REA's parser refuses, then without, for the names. Text splits - into nodes as REA's DOM splits it: at CDATA sections, comments and - processing instructions, an empty CDATA section joining the text around it. -- Parsed views: a JSON or key file entry or file over the 4 MiB limit is - refused before its value is built, in both readers. Its format is told - apart from text by a token scan that builds no value and holds a byte per - open container, which the exported reader also uses when Python's parser - reaches its recursion limit, so deeply nested text is JSON only when all of - it is. -- Selectors: on an array, a pointer segment `[KEY=VALUE]` names the member - whose string field `KEY` is `VALUE`, `[@KEY=VALUE]` the member whose - `attributes` hold it, `[>PATH=VALUE]` the member holding it one to three - `/`-separated steps inside (in XML a descendant element's collapsed text - or, ending `NAME@ATTR`, a child's attribute; in JSON the string at those - keys), and conditions can follow one another. A selector must - match exactly one member; several, or none before the last segment, fail the - check with a message naming the selector. None at the last segment names no - value, so `value_absent` passes and `value_equals` fails. -- Tolerance: `value_equals` takes an optional non-negative `tolerance`, with a - number `value`, and passes when the value found is a number, or a decimal - numeral string, at most `tolerance` from it. -- Truncation: a check decided by what a zip view leaves out depends on the - entry its pointer goes into: that entry's view missing or truncated, or the - listing truncated when the entry is not listed. A pointer whose selector - searches an array the view may hold only part of (any array of a truncated - XML view or entry view, or a cut listing) fails as undecided in both - evaluators. A check into the view of an entry without one (binary, or with a - `view_error`) fails in both evaluators, while checks on its metadata read; - the draft checks only entries with a view, and an absence only where the - entry still has one. -- Changes: `values` between zip versions pair array members one to one, by - the first selector naming a member alone in its version and one unpaired - member of the other (entries by name, XML elements by tag and attribute), - even when a selector before it names nothing there, then by position; a - member left unpaired is keyed by a selector naming it alone and nothing in - the other version. Identity comes first: an element with identifying - attributes (`name`, `id`, `xid`, or a prefixed `id` such as `xml:id`) is - keyed by its tag and those alone, so one whose identifiers name nothing in - the other version is added or removed; its other attributes (`type`, - `color`) key only elements without one. A selector is used only when it - matches one sibling, counted over every attribute of every sibling, - identified ones included. Selectors are spelled only once chosen, so a - long tag is not copied per attribute. A comparison is incomplete when - either view leaves something out. -- Draft: for a zip document, checks inside its entries' JSON, key file and - XML views, through no object or array by position and no array a view may - cut: an element added whole exists, one removed whole is absent, then values - changed, added and removed, with an entry or a JSON value added whole checked - through its members. -- Export refusals: a `tolerance` whose value is not a number. A pointer into - XML that uses namespaces is accepted, in a file or an archive entry. -- Reading: the exported reader reads an entry in bounded chunks, at most one - byte past its declared size, so a forged small size cannot make it expand - the rest of the stream. -- Directory: both readers read the central directory themselves, a record at a - time through the Zip64 end record whenever a Zip64 locator precedes the end - record, whatever the end record holds, count the file entries (directories told - apart as zip.js does: a final slash, a Unix directory mode, or the MS-DOS - attribute), and give zip.js or `zipfile` only the first 1,000 records, so - memory does not grow with the number of entries. - -## Non-goals - -- No reading of an archive inside an archive, or of a database inside one. -- No names by namespace URI: a check names the prefix the document uses, so - one written for a document that binds another prefix to the same namespace - does not match it. -- No other compression methods (bzip2, LZMA, Zstandard) and no encrypted - entries. -- No selectors over non-string values, nested fields other than `attributes`, - or values holding `][`. diff --git a/docs/specs/desktop-app-environments/document-views/verification.md b/docs/specs/desktop-app-environments/document-views/verification.md deleted file mode 100644 index 390c335d03..0000000000 --- a/docs/specs/desktop-app-environments/document-views/verification.md +++ /dev/null @@ -1,221 +0,0 @@ -# Verification - -Run on 2026-11-05 on top of the vendor .deb files branch, on macOS with Node -v22.23.1 and Python 3.11.14. - -## Gates - -- `npm run typecheck`, `lint`, `lint:typed`, `format:check`, `knip` (after - `build:cached`), `jscpd`, `docs:check`, `docs:build`, - `verify:test-discovery` and `verify:architecture-guards`: passed, with no - lint or typed-lint diagnostics in the touched files. The one clone jscpd - lists in a touched file, `DesktopApplicationState.ts` against - `GpgvKeyCheck.ts`, was there before. After main was merged in, `lint` and - `lint:typed` fail only on main's own `tests/acceptance/webSourceLocationCli.test.ts`. -- `npx vitest run src/domain/desktop src/application/desktop src/desktop` with - `tests/boundary/providers/desktopExportPython.test.ts`, - `desktopTaskPython.test.ts` and `tests/boundary/cli/cliStartupImports.test.ts`: - 377 passed and 18 skipped (Linux-only cases). The new - `tests/boundary/providers/desktopZipPython.test.ts`: 13 passed, under - Python 3.9.6, 3.10, 3.11, 3.12, 3.13 and 3.14 alike; - `desktopStateHeap.test.ts`: 2 passed, and `desktopZipHeap.test.ts`: 1. The desktop - CLI boundary tests `desktopApplicationCli`, `cliInputSchemaRequired` and - `cliToolCoverage`: 28 passed. -- Namespaced XML, on the same day and toolchain: the same gates passed, with - no lint, typed-lint or jscpd findings in the touched files, and the desktop - tests with the four provider parity files, `desktopXmlPython.test.ts` among - them: 370 passed and 18 skipped. - -## Tests - -Each new test fails on the code before this change, run from a copy of that -commit with only the new tests and fixtures added; the tests already in the -touched files still pass there. - -- Parity of the two zip readers, REA's and the exported module's, on the same - archives: entries in order with JSON, key file, XML, text, UTF-8-named and - binary entries, a directory left out, and an archive, a SQLite database and - an inexact JSON number inside, each not read for its reason; an encrypted - entry, bzip2, a declared 17 MiB entry, a 943-times expansion, a bad CRC-32 - and a short declared size; a damaged archive; 1,002 entries; and the 64 MiB - archive budget through both readers' refusal functions. -- FreeCAD: the real `Document.xml` of FreeCAD 0.21 and 1.0, before and after - the hole, zipped into `.FCStd` archives. Both readers give the same views, - and both evaluators give the same results and descriptions: a `Part::Cut` - exists, the `Hole` radius is 5 ± 0.01 and the cut's tool links `Hole` all - fail before the edit and pass after it, in both versions, by the same - pointers. -- OpenDocument: an `.odt` built in the test reads as `mimetype` text and - `content.xml` and `META-INF/manifest.xml` as XML, with the paragraph's text - in the view; the readers give the same view, namespaced names included, and - the export keeps a check of the paragraph by `[name=text:p]`. -- Namespaced XML, in `desktopXmlPython.test.ts`: the real saves of an - Inkscape 1.2.2 poster and a LibreOffice 24.2 Writer flyer, before and after - one edit, read alike by both readers, the SVG as a file and `content.xml` - in an `.odt` built in the test. Both evaluators give the same results and - descriptions: the headline `[name=text][@id=headline]` under the layer - `[@inkscape:label=Layer 1]` and the `[@text:style-name=Subtitle]` date fail - before the edit and pass after it, and `inkscape:document-units` passes in - both. Built documents cover `xmlns` declarations in document order, an - undeclared default namespace, `xml:` attributes, CDATA, comments and - processing instructions, what both parsers refuse (an undeclared prefix, - one attribute twice under two prefixes, a prefix bound to `""`, two colons - in a name, a colon in a processing instruction's target, a DOCTYPE with an - internal subset), - and the node and depth limits on prefixed names. -- Selectors and tolerance in the shared check cases both evaluators run: one - member matched, several, none before or at the last segment, a malformed - selector, an escaped `/` in an entry name, an entry by index, a selector - over strings in an array, per-entry truncation, an entry the listing left - out; numbers and numeral strings within a tolerance, outside it, a string - and a boolean that are not numbers, and `tolerance: 0`. -- `locatePointer` and the member keys: the most general selector unique among - siblings, passed over when it names several members of the other version, - and values that hold `][` or look like a time left out. -- The keyed zip diff: an object inserted before another shifts nothing, and a - comparison is incomplete when an entry is unread, truncated or not listed. -- The draft: an archive's added and removed elements and changed values by - selector, inside namespaced XML too, where a paragraph is named by - `[name=text:p][@text:style-name=Subtitle]`; and through the application, a - capture with a FreeCAD document and an `.odt` whose draft, with a check of - the list's paragraph, the export then accepts. - -## Review fixes - -Each fix has a regression test that fails on the reviewed commit and passes -after it: - -- A selector over an array a view may hold only part of is undecided in both - evaluators: a truncated XML view, a cut listing searched by entry name, and - a truncated entry's XML, beside positions into the same views that stay - decided. -- The zip diff pairs members one to one: an element whose attributes split - across two new siblings leaves one paired and the other added. -- The draft checks an entry or a JSON value added whole through its members, - and suggests nothing that reaches an element by position, the last step - included. -- The export accepts a check on the whole listing whose value holds - namespaced XML, since both readers name it alike. -- The exported reader keeps a JSON entry nested 1,100 deep on that entry, - with its siblings read, and refuses JSON nested more than 500 levels as REA - does, 501 levels read and 502 refused, in a file or an entry. -- The exported reader reports an entry damaged when its declared size is - short and its checksum is the prefix's, deflated or stored, as REA does. -- An array that becomes an object with the same keys, or the reverse, is a - changed value, with nothing in it added or removed, so the draft suggests no - absence the end state contradicts. -- The draft checks an empty array or object added to a JSON entry as it is. -- An entry REA could not read, whose `view` is therefore `null`, gets no - drafted check, and both evaluators fail `value_equals null` into its view, - while a JSON entry holding `null` still passes it. -- The exported reader's depth check holds one iterator per level: on a - 4,000,001-byte array of 800,000 nulls, `_text_view` peaks at 6.7 MB of - traced allocations, as before the check, against 58.2 MB when it queued - every member. -- A binary entry fails `value_equals null` and `value_absent` into its view in - both evaluators, its `size` still checked, and the draft suggests no absence - in an entry that ends binary. -- REA's shared JSON depth check also holds one iterator per level: on 800,000 - nulls it grows the heap by 7.3 MB of short-lived iterator results, against - 72.7 MB when it queued a pair per member, and runs under an 18 MiB old-space - limit where the queue needed more than 64 MiB. A test runs it under a 32 MiB - limit. -- The exported reader reads an entry in 64 KiB chunks up to a byte past its - declared size: a 32,731-byte archive holding 32 MiB of zeros declared as one - byte peaks at 0.1 MiB of traced allocations, against 77.5 MiB when it read - the stream whole before clipping it, both reporting the entry damaged as REA - does. An 8.7 MiB text entry peaks at 48.5 MiB against 47.6 MiB. REA's zip.js - reader already stops at the first chunk past the declared size: reading that - archive grows the peak resident size by 0.8 MiB, as a one-byte archive does. -- A check of a namespaced entry's `size`, of its absence, or comparing the - entry whole exports, since both readers name namespaced XML alike. -- The diff finds a counterpart by the evaluator's own step: a bracketed key - against an array is a selector, so `{"[name=x]": 1}` becoming - `[{"name": "x"}]` reports nothing removed, in an archive or a JSON file, and - the draft suggests no absence of a value the selector still names. -- Both readers bound the central directory: an archive of 600,000 empty - entries (52.4 MiB) reads in a 24 MiB V8 old space against more than 48 MiB - when zip.js parsed every record, and grows peak RSS by 37 MiB against - 184 MiB; the exported reader peaks at 1.3 MiB of traced allocations against - 293.6 MiB, and at 1.3 MiB against 25.1 MiB for 50,000 entries. Directories - are told apart as zip.js tells them in both. -- Both readers follow a Zip64 locator whether or not the classic end record - holds sentinels, as `zipfile` does: an archive whose classic record keeps its - own counts, size and offset, which `zipfile` and zip.js both read, was - unreadable to both readers and now lists its entries in both. A last name - ending in bytes that only look like a locator keeps the classic values in - both, and the exported module gives `zipfile` real Zip64 end records for the - directory it shows it, so `zipfile` no longer refuses such an archive; the - parity tests pass under Python 3.9 to 3.14. -- A diff comparing an object of selector-shaped keys with an array indexes the - array once per set of selector fields: 2,000 keys read its members 4,000 - times against 4,002,000, and 8,000 and 20,000 keys diff in 19 and 31 ms - against 980 ms and 5.4 s. -- The keys are resolved together, their conditions sorted and de-duplicated, - holding only the values they ask for rather than an index of the array per - set of fields. 127 field combinations over 5,000 members grow the heap by - 5.5 MB against 68.0 MB, in 138 ms against 174 ms; 160 spellings of one - selector over 800 members by 4.9 MB against 75.9 MB, in 4 ms against - 388 ms, reading the members 1,600 times against 128,800. Both diff in a - 16 MiB V8 old space where they needed more than 48 MiB; a test runs them - under a 32 MiB limit. -- Member pairing keeps an element's tag apart from its attribute conditions - and spells a selector only once it is chosen: an element with a - 38,588-character tag and 2,000 attributes pairs with itself in 4 ms, - growing the heap by 1.1 MiB, against 7.2 s and 148 MiB when the tag was - copied into a selector per attribute. A test pairs two such elements under - a 32 MiB V8 old space. -- An element pairs by its identifiers first, and by a later selector both - versions share before one that names nothing in the other version keys it - as added: `` becoming `` beside another `item` is a changed `color` under - `[name=item][@id=1]`, in the diff and the draft, rather than one element - removed and another added. A FreeCAD `Hole` deleted and a `Hole001` added, - both `Part::Cylinder`, stay one removal and one addition rather than a - rename found by their shared `type`. An identified element's other - attributes still count against its siblings' selectors: `[@color=blue]` is - not reported removed when it moves to the identified `item`, and - `[@role=body]`, `[@role=second]` and an Inkscape group's - `[@inkscape:label=note]` key their elements rather than a `color`, `class` - or `fill` an identified sibling shares, which would match both. The real - FreeCAD 0.21 - and 1.0 documents, and the Inkscape, LibreOffice and AbiWord ones of the - branches built on this one, zipped as entries, give the same diffs, drafts - and member keys as before. -- Both readers refuse a JSON or key file over 4 MiB before building its value, - telling JSON from text by a token scan. REA's reader detects a - 4,200,004-byte array of empty objects in 58 ms, growing the heap by 4.2 MiB - (the decoded text), against 129 ms and 85.5 MiB when detection parsed it, - and a test reads it under a 32 MiB V8 old space. The exported reader's - entry peaks at 8.4 MB of traced allocations against 110.0 MB, a 16 MiB one - at 35.2 MB against 442.5 MB, and a 4.9 MB key file at 10.4 MB against - 86.7 MB; its scan takes 0.9 s and 3.5 s for those entries against 0.7 s and - 2.7 s for the parse. The exported reader now applies the limit to files as - REA does, where it read them whole before. -- The exported reader takes text nested past Python's recursion limit as JSON - only when the token scan finds all of it JSON, as REA does: 1,100 opening - brackets and 1,099 closing ones are text in both readers, where the export - called them JSON nested too deeply, and 1,100 of each are still refused for - their depth in both. - -## FreeCAD captures - -The real `.FCStd` files the FreeCAD investigation captured, from FreeCAD 0.21 -(Ubuntu 24.04 with the FreeCAD PPA) and 1.0 (Ubuntu 25.10), read by the built -CLI: - -- `inspect-desktop-application-state`: `plate.FCStd` is `zip` in every - version, 2 entries before and 15 or 16 after, with a complete `values` - change listing `/entries/[name=Document.xml]/view/root/children/[name=Objects]/children/[name=Object][@name=Hole]` - among the added values; the `.FCBak` backups are `zip` too. -- REA's evaluator and the exported module's, each on its own view of the - retained bytes: identical views, and the hole task's two checks fail before - and pass after in both versions. -- `export-desktop-application --task` on the 0.21 capture keeps the task with - both checks failing on the seed and writes the selectors and the tolerance - into `verify.py`. The 1.0 capture is not exported, as before this change: - its package installs only on Ubuntu 25.10. -- `describe-desktop-application-task` on the 0.21 capture drafts ten checks on - `plate.FCStd`, all by selector (the six objects and dependencies FreeCAD - added, then counts and statuses), and the export keeps that draft with all - ten failing on the seed. diff --git a/docs/specs/desktop-app-environments/download-installs/plan.md b/docs/specs/desktop-app-environments/download-installs/plan.md deleted file mode 100644 index 0d788269cc..0000000000 --- a/docs/specs/desktop-app-environments/download-installs/plan.md +++ /dev/null @@ -1,18 +0,0 @@ -# Plan - -1. Shared install: `appDownloadInstall.ts` holds the download schema, the - folder and file names, and the renderer of `install-download.sh` and a - tarball's entry, which the build computer and the export both use. -2. Request: the `appimage` and `tarball` kinds in the build request, their - `Download`, run script order (REA, `.deb`, download, Electron) and files. -3. Threading: the build capture passes the request's download to the export, - which takes it as `--download-install` in a file it writes beside the - task. -4. Export: the install decision for a download, its refusals, the class's - `downloads` and `run`, the README and limitations, and the CLI flag. -5. Docs: the skill's install choice, the build computer and export guides. -6. Tests first: the bundle's declarations and order, the schema's refusals, - both scripts run under `sh` against a stub AppImage and a real `.tar.xz`, - the export's declarations, its script equal to the build's and its - refusals, and the MCP build passing the download to the export. Then - FreeCAD's AppImage, a tarball and draw.io's `.deb` on a real build host. diff --git a/docs/specs/desktop-app-environments/download-installs/spec.md b/docs/specs/desktop-app-environments/download-installs/spec.md deleted file mode 100644 index c3bc883c94..0000000000 --- a/docs/specs/desktop-app-environments/download-installs/spec.md +++ /dev/null @@ -1,64 +0,0 @@ -# Applications from an AppImage or tarball - -## Outcome - -A build computer installs an application that no package offers from its -project's AppImage or tarball, first FreeCAD 1.1.4's AppImage, pinned by URL -and SHA-256, and the exported bundle installs the same file the same way, -with neither the build nor the bundle holding the application. - -## Requirements - -- Request: `install` takes `{"kind": "appimage", "url", "sha256", - "architecture", "extra_packages"}` and `{"kind": "tarball", "url", - "sha256", "architecture", "program", "name", "extra_packages"}`. The URL is - `http://` or `https://` in lowercase without a user name or password, the - SHA-256 is lowercase hex, the architecture is `amd64` or `arm64`, and a - tarball's `program` is a path inside the archive whose segments start with - neither a dot nor a slash. `name`, optional, is one line of at most 128 - characters. The request's `desktop_entry` names the entry: an AppImage's - own, or the one REA writes for a tarball. -- Install: agentenv downloads the file when the bundle is put, refusing other - bytes, to `vendor/app.AppImage` or `vendor/app.tar`; the bundle supports - only its architecture. A root run script, `install-download.sh`, unpacks it - with the network off under `/opt/rea-apps/`, removes the - download and makes the folder readable to the session user. - - An AppImage is extracted with its own `--appimage-extract`. Its top-level - `.desktop` is installed under - `/usr/local/share/applications` with each `Exec` program replaced by the - extracted `AppRun`, after any `env` prefix and its assignments, and - `TryExec` removed, with its `Icon`'s SVG or PNG; an - image without that entry fails the build, naming the entries it has. - - A tarball is read with Python's `tarfile` and its `data` filter, since the - computer has no `xz` program. The filter refuses links that point outside - the folder, absolute ones included, and special files, failing the build. Its program must be an executable file; the - entry REA writes into the environment folder, `applications/.desktop`, runs it with `%F`, named by `name` or the entry's last - part, and the script installs it. -- Build computer: the script runs after REA's own layer and before the - Electron rewrite, which edits the entry the script installed. -- Export: the build computer passes the request's download to the export in - a file, `--download-install`, which the CLI also takes. The export renders - the same files from it: `downloads=[Download(...)]`, - `run=[RunScript(script="install-download.sh")]`, a tarball's entry, and no - apt package for the application, beside the extra packages and dconf. -- Refusals (`download_install`, each with its remediation): a file that is - not JSON or names no AppImage or tarball install; a capture that launched - another desktop entry; a captured program outside the download's folder; - a capture host of another architecture. `--package-url` beside it is - refused (`package_url`). -- README and limitations: the computer downloads the URL when the bundle is - put and checks its SHA-256; the bundle does not contain the application; - the URL must keep serving those bytes; the licence is the operator's. - -## Non-goals - -- Flatpak: bubblewrap needs user namespaces that the computer's container - (Docker's default seccomp and AppArmor) and an Ubuntu 24.04 host - (`kernel.apparmor_restrict_unprivileged_userns=1`) refuse, and neither is - REA's to change. -- Snaps, zstd tarballs, AppImages without `--appimage-extract`, and - installers. -- One request for both architectures. -- Reclaiming the downloaded file's space in the image: agentenv copies it - into the app's layer before the script runs. diff --git a/docs/specs/desktop-app-environments/download-installs/tasks.md b/docs/specs/desktop-app-environments/download-installs/tasks.md deleted file mode 100644 index d5fc3d634c..0000000000 --- a/docs/specs/desktop-app-environments/download-installs/tasks.md +++ /dev/null @@ -1,26 +0,0 @@ -# Tasks - -Requirements are in [spec.md](spec.md#requirements); evidence is in -[verification.md](verification.md). - -- [x] Record the outcome, requirements and non-goals. -- [x] Share the download schema, folder and file names and the - `install-download.sh` renderer between the build computer and the export - (Install). -- [x] Take `appimage` and `tarball` kinds in the build request, with their - `Download`, run script order and files (Request, Build computer). -- [x] Pass the request's download from the build capture to the export as - `--download-install` (Export). -- [x] Render the export's download, run script, tarball entry, refusals, - README and limitations from it (Export, Refusals, README and - limitations). -- [x] Document the install choice in the skill and the build computer and - export guides. -- [x] Add tests that fail first, the scripts run under `sh` against a stub - AppImage and a real `.tar.xz` ([Tests](verification.md#tests)). -- [x] Build and witness FreeCAD's AppImage, a VSCodium tarball and draw.io's - `.deb` on an arm64 host ([verification](verification.md)). -- [x] Fix the review's findings: a URL that ended the docstring, an `env` - prefix, links out of a tarball's folder, and `Exec` and `TryExec` keys - spaced around their `=`. -- [x] Run the gates and record verification ([Gates](verification.md#gates)). diff --git a/docs/specs/desktop-app-environments/download-installs/verification.md b/docs/specs/desktop-app-environments/download-installs/verification.md deleted file mode 100644 index 8443a2fa37..0000000000 --- a/docs/specs/desktop-app-environments/download-installs/verification.md +++ /dev/null @@ -1,119 +0,0 @@ -# Verification - -Run on 2026-11-06 and 2026-11-07 on top of the build-and-witness branch: -gates and source tests on macOS with Node v22.23.1; real builds on an arm64 -Ubuntu 24.04 host with agentenv-framework 0.9.1431 and Docker. No amd64 host -was available, so amd64 is unverified; FreeCAD, VSCodium and draw.io publish -x86_64 builds of the same releases. - -## Gates - -- `npm run typecheck`: no errors outside `src/domain/apiContract`, whose - `graphql` dependency is missing here, as before the change. -- `npx oxfmt --check .`: clean. -- oxlint on the changed and new source and test files: no diagnostics. The - first version added size warnings (`max-lines` on `appExport.ts`, - `appExportInstall.ts` and `DesktopApplicationExport.ts`, function length, - `max-params`); the README install text moved to `appExportInstallText.ts`, - the export's decision to `appExportDownload.ts`, and `admitApplication` - takes an options object. -- `npx knip`: the same two unresolved worker aliases as before the change, - which need build artifacts; nothing new. -- `npm run verify:module-boundaries`: passed. -- `npx vitest run src/domain/desktop src/application/desktop - tests/boundary/providers tests/boundary/mcp/build tests/boundary/cli/desktop - tests/boundary/mcp/advertisedPatternsVMode.test.ts`: 12 files and 51 tests - fail, the same files and tests as on the unchanged branch (Ghidra, IDA, - Kuna, ADB and SQLite provider tests, and two desktop CLI tests, which need - tools or a build this host lacks); 11 more tests pass. - -## Tests - -Each failed on the unchanged code first: - -- the bundle declares an AppImage's `Download` for its architecture, runs - `install-download.sh` after REA's layer and before the Electron rewrite, - and passes its `extra_packages` (the request was rendered as an archive); -- a tarball's `Download` and the entry REA writes for its program; -- the schema refuses a program outside the archive, an uppercase SHA-256, a - URL with credentials or not over http or https, a two-line name and another - architecture; -- the AppImage script, run under `sh` against a stub AppImage, installs its - entry with each `Exec` program replaced by `AppRun`, no `TryExec`, its SVG - icon, a readable folder and no download (the script did not exist); -- an image without the requested entry fails, naming those it has; -- the tarball script unpacks a real `.tar.xz` with Python, installs the entry - and removes the download; a missing program fails, naming the archive's top; -- the export from `--download-install` declares the download and writes the - same script the build computer ran; a tarball's entry is written beside it - (the export refused the capture as not an apt package); -- the export refuses a program outside `/opt/rea-apps/`, writing - nothing, `--package-url` beside the download, and a file naming no download; -- through MCP, an AppImage request's export receives `--download-install` - with the request's download in a file, and its bundle downloads the image. - -After review, four more, each failing on the first version: - -- a URL holding `"`, `\` and `"""` ended the class's docstring and made the - module invalid Python; now the docstring shows it with those characters - replaced, Python parses one expression, the docstring, and `Download`'s - literal holds the exact URL; -- an entry's `Exec=env QT_QPA_PLATFORM=xcb "GTK_THEME=Adwaita dark" drawio %U` - lost its `env` prefix; it now keeps both assignments before `AppRun`; -- a crafted tarball with an absolute hardlink, then a file of the same name, - overwrote the outside file through the link as the script ran; with the - `data` filter it and a symlink out of the folder fail the build, and the - outside file keeps its content; -- an entry's `Exec = drawio %U` and indented `TryExec =drawio`, which the - desktop entry parser reads, were left as they were; the script now reads - the key and the spaces around its `=` before rewriting `Exec` or dropping - `TryExec`. - -## FreeCAD 1.1.4 (AppImage) - -The request named the release's aarch64 AppImage and its published SHA-256. -The start took 714 s, 436 s of them waiting for other agents' builds; the -resolve took 35 s since agentenv had stored the 756 MB image, and the image -build 205 s. The capture opened FreeCAD in 7.7 s and recorded its package as -`unknown`. A seed of a cube and a cylinder in `Documents/block.FCStd`, and the -cube's Length changed from 10 to 25 mm, gave a draft check on -`Document.xml`'s `Box` Length through the `.FCStd` view. The export declared -the download with no apt package, its `install-download.sh` byte-identical to -the build computer's, and a boot launch of `AppRun` on the document. - -The bundle's computer started in 267 s. agentenv's probe passed with FreeCAD -launched at boot, so the boot launch needs nothing from REA. The witness held: -the seed failed the Length check, the edit passed all three checks, 24 mm -failed, and the reset restored 10 mm. - -## VSCodium 1.143.17232 (tarball) - -The request named `VSCodium-linux-arm64-1.143.17232.tar.gz`, its published -SHA-256 and `program: codium`, with `electron: true`. The first computer's -installed entry read `Exec=/opt/rea-apps/codium/codium --no-sandbox %F`, so -the Electron rewrite ran on the entry the download step wrote. Its capture -failed with `libnspr4.so: cannot open shared object file`; `ldd` named NSS -and ALSA, and a new computer with `extra_packages: ["libnss3", -"libasound2t64"]` ran it. VSCodium's main process runs without REA's run -token, so a capture stopped while it ran failed to clean up and left its -window crashed; quitting it with Ctrl+Q after `end` lets the capture stop. -The skill says so. A list in `Documents/todo.txt` with "olive oil" added -exported with its two packages, the tarball download, REA's entry and an -Electron launch. The witness computer passed the probe with VSCodium at boot, -and the witness held: seed, edit, "olive oils" as the near miss, reset. - -## draw.io 32.6.10 (`.deb`, unchanged path) - -The upstream arm64 `.deb` with its Depends and `libasound2t64`, which it -lacks, built through `package_file`; agentenv resolved the virtual -`libgtk-3-0`. A box renamed from Draft to Approved exported with -`install-package.sh`, and the witness held all four stages. - -## Not verified - -- amd64 builds, and AppImages without `--appimage-extract` (type 1). -- A zstd tarball, which the script refuses through Python's `tarfile`. -- Flatpak, out of scope: bubblewrap failed in the computer with `No - permissions to create new namespace`, and with seccomp and AppArmor - unconfined still failed on the host's - `kernel.apparmor_restrict_unprivileged_userns=1`. diff --git a/docs/specs/desktop-app-environments/export/plan.md b/docs/specs/desktop-app-environments/export/plan.md deleted file mode 100644 index f3c3674653..0000000000 --- a/docs/specs/desktop-app-environments/export/plan.md +++ /dev/null @@ -1,12 +0,0 @@ -# Plan - -1. Pure renderers: environment and class names, owned paths, the launch - command, env.toml, the Python class with its seed and view helpers, the - skill, the README and the smoke task. -2. Service: read the capture and its state view, plan the bundle, refuse what - v1 cannot install, and write it through the safe output tree. -3. CLI: `export-desktop-application`, composing the state readers. -4. Docs: a user page and links. -5. Tests: renderers and the service on a synthetic capture; Mousepad end to end - checked with agentenv's own declaration reader and a dry run, plus the - generated helpers run against real files. diff --git a/docs/specs/desktop-app-environments/export/spec.md b/docs/specs/desktop-app-environments/export/spec.md deleted file mode 100644 index c0c79d73d1..0000000000 --- a/docs/specs/desktop-app-environments/export/spec.md +++ /dev/null @@ -1,55 +0,0 @@ -# Export a captured application as a computer app - -## Outcome - -`rea export-desktop-application ` writes an -agentenv bundle with one `computer_app` environment for the captured -application: installed from the distribution archive on the `ubuntu-24.04` -base with the `reference` driver, launched at boot and ready when its window -appears, seeded with the user's state from before the capture, and serving that -state through `data/add`, `data/get` and `data/reset`. - -## Requirements - -- CLI only. It reads the capture and its state view and runs nothing else. - The output directory must be new or empty; files are written through the - shared safe output tree. -- It refuses applications not installed from a Debian package archive, captures - without an application window, and environment names that are not portable. -- The class declares the apt package, the packages `--extra-package` names - beside it (refused unless each is a Debian package name), and the package of - the program the desktop entry runs when another one owns it (refused when - the capture found no source the computer can install that package from, or only repositories - the export leaves out supply it, as library packages so supplied are left - out; a capture whose entry runs a program no package owns is refused), the - captured launch - command with - arguments under the captured home respelled under `$HOME`, an exact window - class match with a window ready check, `paths` from the state view's roles - (state directories of application state files, or a folder beside one that - differs only in letter case in the files' spelling, and folders of - documents, nested ones collapsed) and the skill file. When the seed holds - exactly one document and the desktop entry's `Exec` takes files, the - launch appends its path under `$HOME`; a command that already names a - document, absolute or from its working directory, is kept, a seed with no document launches as captured, - and otherwise the README and the limitations say why the app opens no - document. -- With paths, it declares all three data hooks and calls agentenv's helpers: - seed the home once per boot then `keep_initial`, `add`, `reset`, and `get` - plus a data part holding a typed JSON view of each file. Without paths it - declares no hooks. -- The seed is the baseline version of every state view path under `paths`, - copied from retained content after its digest is checked; text files have the - captured home path respelled when seeded. Baseline dconf keys of the - application are compiled into the user's dconf database with `dconf-cli`, - without D-Bus. -- The README and the result state the agentenv-framework release the class - targets (0.9.1485), and that the seed is real user data, unless - `--synthetic-seed` says it was made for the task. - -## Non-goals - -- No image build, deploy or run; verification inside a computer is the next - step. -- No tasks beyond a deploy smoke task. -- No pinned package version, other package kinds, or redaction of the seed. diff --git a/docs/specs/desktop-app-environments/export/tasks.md b/docs/specs/desktop-app-environments/export/tasks.md deleted file mode 100644 index 8c26706477..0000000000 --- a/docs/specs/desktop-app-environments/export/tasks.md +++ /dev/null @@ -1,9 +0,0 @@ -# Tasks - -- [x] Record the outcome, requirements and non-goals. -- [x] Render env.toml, the class, the skill, the README and the smoke task. -- [x] Plan owned paths, the seed and the launch command from the capture and state view. -- [x] Write the bundle through the safe output tree and add the CLI command. -- [x] Document the command. -- [x] Add renderer and service tests; check a Mousepad bundle with agentenv. -- [x] Run the gates and record verification. diff --git a/docs/specs/desktop-app-environments/export/verification.md b/docs/specs/desktop-app-environments/export/verification.md deleted file mode 100644 index c3892c7565..0000000000 --- a/docs/specs/desktop-app-environments/export/verification.md +++ /dev/null @@ -1,49 +0,0 @@ -# Verification - -Run on 2026-11-04 on top of the state view branch: gates and source tests on -macOS 26.5 with Node v22.23.1; the end-to-end run in an Ubuntu 24.04.5 arm64 -container with Node v24.22.1, Mousepad 0.6.1 and agentenv-framework 0.9.1431 -installed from PyPI into a virtual environment. - -## Gates - -- `npm run typecheck`, `lint`, `lint:typed`, `format:check`, `knip`, `jscpd`, - `docs:check`, `mcp-catalog:check`, `verify:test-discovery`, - `verify:architecture-guards` and `scan:todos`: passed, with no lint - diagnostics in the new source files. -- New tests: names, owned paths, the launch command, env.toml and the class - with and without data hooks; the service writing a bundle from a synthetic - capture, and refusing an application with no package archive source. - -## Mousepad end to end - -`~/Documents/todo.txt` held `buy bread`. Mousepad was captured opening it -(`--argument /home/ada/Documents/todo.txt`) while `xdotool` added `buy milk` -and saved; the capture was exported, then checked with agentenv: - -- The export wrote `envs/mousepad/{env.toml, mousepad_app.py, SKILL.md, - seed/Documents/todo.txt}`, `tasks/smoke.json` and `README.md`. Owned paths: - `.config/Mousepad` and `Documents`; seed: `Documents/todo.txt`. -- `python -m agentenv_protocol.computer._declare . mousepad_app.py Mousepad` - exited 0 and declared apt `mousepad`, the launch with window class - `Mousepad` and a window ready check, both paths, the skill file and - `data/add`, `data/get` and `data/reset`. -- `agent-env run --dry-run` exited 0, planning `envs/mousepad` and - `tasks/smoke.json` on the `ubuntu-24.04` computer with the `reference` - driver. -- Importing the class and calling its helpers: the typed view of - `Documents/todo.txt` on the capture host was `["buy bread", "buy milk"]`; - seeding a fresh home wrote `Documents/todo.txt` with `buy bread`; the launch - command is `sh -c "exec 'mousepad' \"$HOME\"/'Documents/todo.txt'"`. -- The generated dconf loader, run on its own: on a fresh home it compiled the - captured keys into `~/.config/dconf/user`; over an existing database the - captured keys won and other groups stayed; with no `dconf` binary it printed - one warning and returned. - -## Limits of this verification - -- The bundle was not deployed: no image was built and the app did not boot in - a computer. That is the next step, with its recording. -- The output tree refused a bind-mounted macOS folder as the bundle directory - (its directory identity is not stable there), so the run wrote the bundle - inside the container and copied it out. diff --git a/docs/specs/desktop-app-environments/file-readers/plan.md b/docs/specs/desktop-app-environments/file-readers/plan.md deleted file mode 100644 index 7967c322d3..0000000000 --- a/docs/specs/desktop-app-environments/file-readers/plan.md +++ /dev/null @@ -1,18 +0,0 @@ -# Plan - -1. Schema: `readers` and the `reader` field in `appTask.ts`, with - `readersProblem` for ids, files, `{file}`, kinds by output and unread - readers; `DesktopTask.readers` only when the file has some. -2. Runner: `PYTHON_READER_RUNNER`, `readerCommand`, `readerArguments` and - `readerAnswerView` in `appTaskReaders.ts`. -3. Evaluators: `evaluateTaskChecks` takes the readers' views by id, and the - verifier's `evaluate_with_readers` does, leaving `evaluate` as it was. -4. Verifier: `appTaskPython.ts` renders `READER_RUNNER`, `READERS`, - `_reader_views` and `evaluate_with_readers` only for a task with readers, - so a task without renders as before. -5. Application: `readerViewsOfBytes` in `DesktopTaskReaders.ts`; - `runReaderHere` in `src/desktop/TaskReaderProcess.ts`; - the witness runs readers through `AgentEnvComputer.exec`; the export runs - them on `shippedSeedBytes` and the end's retained content. -6. Docs: the tasks reference, the witness page, the build skill's recipes for - GIMP, Blender and LibreOffice, and the draft note. diff --git a/docs/specs/desktop-app-environments/file-readers/spec.md b/docs/specs/desktop-app-environments/file-readers/spec.md deleted file mode 100644 index 751bb80bd8..0000000000 --- a/docs/specs/desktop-app-environments/file-readers/spec.md +++ /dev/null @@ -1,78 +0,0 @@ -# Readers: checking files REA cannot read - -## Outcome - -A task can check a file REA reads as binary, such as GIMP's `.xcf` or -Blender's `.blend`, through a reader: the app's own headless command, run in -the computer on a private copy of the file, whose marked output becomes a -view that the existing check kinds read. The export validates such checks on -the seed and the end, the witness checks them live, and the exported verifier -grades them in the solving agent's computer, all through one runner. - -## Requirements - -- Task file: an optional `readers` array of 1 to 8 - `{id, file, argv, stdin?, output, timeout_s?, display?}`. `id` is lowercase - letters, digits and hyphens and unique; `file` is a path under the home; - `argv` holds 1 to 64 non-empty strings; `stdin` at most 64 KiB; `output` - is `json` or `lines`; `timeout_s` is 1 to 300, 60 when omitted; `display` - is false when omitted. The argv or the stdin names the file as `{file}`. -- Checks: `lines_present`, `lines_absent` and `line_count` take an optional - `reader` naming a `lines` reader; `value_equals`, `value_absent` and - `member_count` one naming a `json` reader. The check's `file` is the - reader's. Other kinds take none. Every reader is read by a check. The parser - refuses each breach with the check or reader it names. -- Runner: one Python program, embedded in REA and in each verifier that needs - it, run as `python3 -I -c ` in the computer's session. - It answers with one JSON line: `{"view"}`, `{"absent": true}` when the file - is not there, or `{"error"}`. It copies the file into a new temporary folder, - runs the command there with `{file}` replaced by the copy's path in argv and - stdin, `HOME` and the four `XDG_` folders in that folder, without - `DISPLAY`, `WAYLAND_DISPLAY` or `XAUTHORITY` unless `display` is true, and - never with `DBUS_SESSION_BUS_ADDRESS`, `SESSION_MANAGER`, - `XDG_RUNTIME_DIR` or any `AGENTENV_` variable. Past `timeout_s` it kills - the command's whole session. It deletes the folder afterwards. -- View: each output line starting with `REA ` is a line of the view, without - the marker. A `lines` reader's view is a text view (`lines`, `line_count`, - `truncated` past 5,000 lines); a `json` reader's is the marked lines joined - by line feeds, read as one JSON value, refusing NaN, infinities and - integers past 2^53. A command that cannot start, exits other than 0, runs - past its timeout, prints more than 1 MiB, prints no marked line or prints a - `json` view that does not parse gives an error view, with the last 1 KiB of - its stderr; so does an answer past 960 KiB. -- Evaluators: REA's and the verifier's read a check with `reader` from the - reader's view, by id, instead of the file's. A missing reader view reads as - an absent file; an error view fails the check as undecided, worded as an - unreadable file's, in both. -- Export: the export runs each reader on this host, in the build computer, - on the file's bytes at the seed as the bundle ships them and at the end - checkpoint as retained; a file not retained at the end gives an error view. - It refuses a reader of a file outside the owned paths or naming the - captured home or the host's identity. A check through a reader that fails - on the end adds what the reader printed to the refusal. -- Witness: once the app's files settle, `check_build_task` runs the readers - through the computer's `computer-exec/v1`, and a runner that does not - answer fails the check call as a failed read of the app's state. -- Verifier: a task with readers holds the runner once and each reader's - arguments; after its files settle it runs each through `computer-exec/v1` - under the run's grant, with a request id of its own and the reader's - timeout plus 30 s, and raises when the computer offers no such route or - the runner does not answer, so the run fails rather than scoring the agent. - It grades through `evaluate_with_readers`, which only such a verifier holds: - a task without readers renders the verifier byte for byte as before, so a - bundle exported earlier witnesses as the same task. -- Cleanup: the witness and verifier own each remote reader's temporary copy - until the command finishes and its folder is removed. They report failed - cleanup with its folder and retain it for retry; an interrupted command is - not assumed to have stopped. The witness retries on check or close, and - the verifier on a later call in the same process. -- Draft: a file REA reads as binary is noted as checkable through a reader. - -## Non-goals - -- Drafting checks from a reader's output: the building agent writes the - reader and its checks; the export's refusals show what it read. -- XML output from a reader, and text checks through one. -- Shipping readers maintained by REA for known formats; the skill gives - recipes. -- A screen judge for state no file holds; that is the next step. diff --git a/docs/specs/desktop-app-environments/file-readers/tasks.md b/docs/specs/desktop-app-environments/file-readers/tasks.md deleted file mode 100644 index b870a14968..0000000000 --- a/docs/specs/desktop-app-environments/file-readers/tasks.md +++ /dev/null @@ -1,9 +0,0 @@ -# Tasks - -- [x] Record the outcome, requirements and non-goals. -- [x] Add readers to the task schema and the parser. -- [x] Write the runner and read its answers. -- [x] Read checks through readers in both evaluators and the verifier. -- [x] Run readers in the export, on the seed and the end, and in the witness. -- [x] Document readers and give the build skill recipes. -- [x] Build GIMP and Blender environments with readers on an arm64 host, witness them and run solves. diff --git a/docs/specs/desktop-app-environments/file-readers/verification.md b/docs/specs/desktop-app-environments/file-readers/verification.md deleted file mode 100644 index a7f22239a7..0000000000 --- a/docs/specs/desktop-app-environments/file-readers/verification.md +++ /dev/null @@ -1,77 +0,0 @@ -# Verification - -Run on 2026-11-06 on top of the integration of the desktop build stack, on -macOS with Node v22.23.1 and Python 3, and on an arm64 Ubuntu 24.04 build -host with agentenv-framework 0.9.1431. - -## Tests - -- `src/domain/desktop/appTaskReaders.test.ts`: the parser keeps readers and - refuses an undefined reader, a check whose file is not its reader's, a - reader naming no `{file}`, repeated ids, an unread reader, a reader file - with a leading slash, a kind its output does not serve and a text check - with a reader; the evaluator reads a check through its reader rather than - the file's binary view, fails it undecided with the reader's error, and - as decided on an absent file; the runner's command and answers. -- `tests/boundary/providers/desktopTaskReaderRunner.test.ts`: the runner, - run with `python3` as computer-exec runs it, gives the reader a private - copy in a fresh home without `DISPLAY`, the session bus or the control - token, keeps the display only when asked, reads a path in place of the - home's file, keeps only marked lines, answers absent without running the - reader, reports a non-zero exit, no marked line, a view that is not JSON, - an inexact number, more than 1 MiB and a command that cannot start, and - kills a reader and what it started past its timeout. -- `tests/boundary/providers/desktopTaskPython.test.ts`: the exported - verifier runs each reader through `computer-exec/v1` with the runner's - command, a fresh request id and the reader's timeout plus 30 s, grades - every reader check as REA's evaluator does, with the same descriptions, and - raises when the computer offers no `computer-exec/v1` or the runner does - not answer. -- `src/application/desktop/DesktopTaskExport.test.ts`: the export runs a - reader on the seed as shipped and on the end, keeps the task and ships the - reader in the verifier and the README; it refuses a check that fails on - the end with what the reader printed, a reader that exits non-zero with - its error, a task that already passes on the seed and a reader outside - the owned paths. -- `tests/boundary/mcp/buildWitnessMcp.test.ts`: a witness of a task whose - check reads a binary file through a reader, run by the fake computer's - computer-exec, holds at all four stages and returns no control token. -- `src/domain/desktop/appTaskDraftFileNotes.test.ts`: a binary file's draft - note points at readers. -- `src/domain/desktop/appTaskReaders.test.ts` also pins the SHA-256 of a - reader-less task's verifier as the tree before readers renders it, - `91821c46…`; the rendering with `evaluate`'s reader argument failed it. - -Each failed on the unchanged code: the reader module did not exist, the -schema refused `reader` and `readers`, and the note named no reader. - -## Real apps - -On the arm64 host, each through `start_build_computer`, the app's own -interface, `start_build_capture`, `seed` and `end` checkpoints, -`stop_build_capture` (whose draft noted the file as `unreadable_view` and -pointed at readers), `export_build_environment` and a witness in a fresh -computer of the bundle: - -| App | Document | Task | Reader | Export | Witness | -| ------------- | ----------------------- | ------------------------------------- | --------------------------------------- | --------------------------------- | ---------------------------- | -| GIMP 2.10.36 | `Documents/poster.xcf` | rename the Headline layer Summer Sale | Script-Fu through `gimp-console-2.10` | kept; 2 of 3 checks fail on seed | held; each stage about 5.6 s | -| Blender 4.0.2 | `Documents/scene.blend` | move the Crate to x = 2 m | `blender -b --factory-startup` with bpy | kept; 1 of 3 checks fails on seed | held; each stage about 4.4 s | - -A stage's time is the 3 s the app's files must hold plus the reader: about -2.5 s for GIMP and 1.4 s for Blender. The near misses were Summer Sail and -x = 2.5 m. - -Then three solves of each bundle with Claude Code on Claude Sonnet 5.5, -through `agent-env run`, each graded by the exported verifier, which ran the -reader through the computer's `computer-exec/v1`: - -| Task | Passed | Verifier step | Cost | -| ----------------------- | ------ | ------------- | ----- | -| `rename-headline-layer` | 3 of 3 | 5.6 to 5.7 s | $1.94 | -| `move-crate` | 3 of 3 | 4.5 s | $2.31 | - -Blender 4.0.2 writes its preferences only when they are saved, so its seed -held no `userpref.blend` and every boot showed the Quick Setup splash, which -the witness dismissed with Continue; the solves passed with it there. The -build skill now saves Blender's preferences before `seed`. diff --git a/docs/specs/desktop-app-environments/screen-judge/plan.md b/docs/specs/desktop-app-environments/screen-judge/plan.md deleted file mode 100644 index 0ea1183be6..0000000000 --- a/docs/specs/desktop-app-environments/screen-judge/plan.md +++ /dev/null @@ -1,16 +0,0 @@ -# Plan - -1. Schema: `screen_judge` in `appTask.ts`, with `screenProblem` keeping such - tasks to screen judges alone. -2. Judge: `appTaskScreen.ts` renders the screen verifier, finds the files a - check could read change in (`readableChanges`) and the examples a bundle - holds (`screenExamplesOf`); `renderTaskVerifier` dispatches to it. -3. Build computer: `DesktopBuildCapture.mark` keeps a screenshot through - `AgentEnvComputer.addHomeFiles`; the export takes `--screens`. -4. Export: `admitScreenTask` in `DesktopTaskExport.ts`; the relaunch reset in - `ownlessBody` of `appExportPython.ts`. -5. Witness: `judgeScreenTask` and `bundleTaskDifference` in - `DesktopBuildWitnessBundle.ts`, with `screenJudgeProcess` in - `src/desktop/ScreenJudgeProcess.ts`. -6. Docs: the tasks reference, the witness page, the build skill and the - doctor's endpoint check. diff --git a/docs/specs/desktop-app-environments/screen-judge/spec.md b/docs/specs/desktop-app-environments/screen-judge/spec.md deleted file mode 100644 index c702f04882..0000000000 --- a/docs/specs/desktop-app-environments/screen-judge/spec.md +++ /dev/null @@ -1,53 +0,0 @@ -# Screen judges: checking state no file shows - -## Outcome - -A task can check what an app keeps only on screen, such as a calculator's -result, through a screen judge: a model answers a yes-or-no question on a -screenshot of the computer, calibrated by two labelled screenshots from the -build. The export ships the judge in the bundle, the witness runs that same -judge on fresh screenshots, and the verifier runs it at grading time. REA -calls no model itself. - -## Requirements - -- Task file: a check `{id?, kind: "screen_judge", question}`, the question - 1 to 2,000 characters after trimming. A task with one holds only screen - judges and no readers. -- Build computer: at each acknowledged checkpoint REA takes a JPEG - screenshot (quality 70) through the driver and writes it under the home at - `/screens/.jpg` with `data/add`; a screenshot - that fails leaves the checkpoint as it is. The export runs with - `--screens /screens`. -- Export: a screen-judged task is refused when an owned file changed between - the seed and the end in a way a check could read (readable or absent at - both ends, and different), naming the files, and when the seed's or the - end's screenshot is missing. It judges nothing: `failing_on_seed` is empty - and a limitation says the witness checks the questions. `verify.py` holds - the questions, the seed's screenshot as the failing example and the end's - as the passing one. An app that owns no files gets a reset that only - relaunches it, so the witness can take `after_reset`. -- Verifier: once the agent stops it waits 1 s, takes a JPEG screenshot - through the computer's `computer_screenshot` tool and asks each question 3 - times; a question passes when at least 2 answers are yes. Each vote shows - the instructions, the two labelled examples and the screenshot, and asks - for `{verdict, reason}` by JSON schema; a failed call is asked again, up to - 3 times, then the verifier raises. The model is `[model.roles] judge`, else - `[model] default`, else `anthropic/claude-sonnet-5-5`, through agentenv's - `resolve_model_call`; without an endpoint it raises, so the run fails - rather than scoring the agent. `agent-env run --judge-model` does not reach - it. -- Witness: for a screen-judged task, `check_build_task` waits 1 s, takes a - screenshot, and runs the bundle's `verify.py judge ` - with the agentenv runner's Python and REA's environment; it refuses on a - computer not started from the bundle, and a judge that fails fails the - check call. On a bundle computer it compares the bundle's verifier with the - task's using the examples the bundle holds. -- Doctor: the model endpoint check names screen-judged tasks as needing it. - -## Non-goals - -- Judging the screen in the export or drafting questions. -- Mixing screen judges with file checks or readers in one task. -- Passing `--judge-model` through; agentenv gives an outcome verifier no run - overrides. diff --git a/docs/specs/desktop-app-environments/screen-judge/tasks.md b/docs/specs/desktop-app-environments/screen-judge/tasks.md deleted file mode 100644 index b576dc01c3..0000000000 --- a/docs/specs/desktop-app-environments/screen-judge/tasks.md +++ /dev/null @@ -1,9 +0,0 @@ -# Tasks - -- [x] Record the outcome, requirements and non-goals. -- [x] Add `screen_judge` to the task schema and the evaluator. -- [x] Render the judge into the verifier, with the build's examples. -- [x] Keep a screenshot at each checkpoint and admit screen-judged tasks in the export. -- [x] Run the bundle's judge in the witness. -- [x] Document screen judges. -- [x] Build a GNOME Calculator environment on an arm64 host, witness it and run solves. diff --git a/docs/specs/desktop-app-environments/screen-judge/verification.md b/docs/specs/desktop-app-environments/screen-judge/verification.md deleted file mode 100644 index 5b8fd8c91f..0000000000 --- a/docs/specs/desktop-app-environments/screen-judge/verification.md +++ /dev/null @@ -1,58 +0,0 @@ -# Verification - -Run on 2026-11-06 on top of the readers commit, on macOS with Node v22.23.1 -and Python 3, and on an arm64 Ubuntu 24.04 build host with -agentenv-framework 0.9.1431. - -## Tests - -- `src/domain/desktop/appTaskScreen.test.ts`: the parser keeps a task of - screen judges and refuses one beside a file check, with readers, with a - blank question or with a `file`; REA's evaluator leaves a screen judge - undecided; the rendered verifier screenshots the computer, names the - judge's role, default model and votes, says `--judge-model` does not reach - it, and holds the examples `screenExamplesOf` reads back; `readableChanges` - counts only changes a check could read. -- `tests/boundary/providers/desktopScreenJudgePython.test.ts`: the verifier, - run with stand-ins for the MCP client, litellm and agentenv's config, - takes one screenshot, asks three votes each showing the seed's and the - end's examples before the screenshot, passes on two yes and fails on two - no, asks the `[model.roles] judge` model, asks a failed call again, raises - when no vote answers or no endpoint is set, and judges a given screenshot - when run as a script. -- `src/application/desktop/DesktopTaskExport.test.ts`: the export ships the - seed's and the end's screenshots in order with an empty `failing_on_seed` - and the witness limitation, and refuses a task whose capture shows a - readable file change or lacks a screenshot. -- `tests/boundary/mcp/buildCaptureMcp.test.ts`: marking `seed` and `end` - writes `screens/seed.jpg` and `screens/end.jpg` in the computer, and the - export is given `--screens`. -- `tests/boundary/mcp/buildWitnessMcp.test.ts`: a screen-judged witness runs - the bundle's verifier with the runner's Python at each stage, three votes a - stage, each with three images, and holds. -- `src/domain/desktop/appExport.test.ts`: an app owning no files gets a - relaunch-only reset only for a screen-judged task. -- `src/application/DesktopBuildDoctor.test.ts`: the endpoint check names - screen judges. - -Each failed on the readers commit before the change. - -## Real app - -GNOME Calculator 46.3 on the arm64 host. The capture's draft noted -`no_change` and `no_document`. The task `tip-amount` asks to work out 18% of -47.60 and leave the result showing, with one question, "Does the -calculator's display show the result 8.568?". The export kept it in 1.8 s -with the 39 KB seed and 41 KB end screenshots as examples, and gave the app, -which owns no files, a relaunch-only reset. - -| Stage | Screen | Judge | Held | Time | -| ------------- | -------------------------------- | ----------- | ---- | ------ | -| `seed` | empty display | no, 3 of 3 | yes | 10.7 s | -| `after_edit` | 47.6×0.18 = 8.568 | yes, 3 of 3 | yes | 9.7 s | -| `near_miss` | 47.6×0.17 = 8.092 | no, 3 of 3 | yes | 9.7 s | -| `after_reset` | empty display after the relaunch | no, 3 of 3 | yes | 9.8 s | - -Three solves with Claude Code on Claude Sonnet 5.5 all passed, the judge -saying yes in 3 of 3 votes each time; the verifier step took 8.1 to 9.1 s and -the solves cost $1.72, besides about $0.02 of judge calls per grade. diff --git a/docs/specs/desktop-app-environments/several-tasks/plan.md b/docs/specs/desktop-app-environments/several-tasks/plan.md deleted file mode 100644 index 2f2b8bb9d7..0000000000 --- a/docs/specs/desktop-app-environments/several-tasks/plan.md +++ /dev/null @@ -1,20 +0,0 @@ -# Plan - -1. Export: `admitDesktopTasks` in `DesktopTaskExport.ts` reads every task - file, resolves each task's end and near miss among the capture's - checkpoints with `selectStateEnds`, evaluates the checks at the seed, its - end and its near miss, and renders every task with one eval. -2. CLI: `--task-end` on `export-desktop-application`; the request carries - it to the export, and the result reports `tasks`. -3. Build: `DesktopBuildExport` writes one file per task and passes - `--task-end`; `DesktopBuildCapture` refuses an untaken end; - `DesktopBuildSummary` drafts each later end from the end before it. -4. Contracts: `export_build_environment` takes and reports `tasks`; - `stop_build_capture` reports `later_drafts`; `mark_build_checkpoint` - names `end-` and `near-`. -5. Docs: the building guide, the tasks, export and build-witness guides, - and this spec. -6. Tests first: the export of two tasks from one capture with a near miss, - and its refusals; the build tools' later draft, export and refusal - through the MCP with the real CLI's outputs; then TreeLine on the arm64 - VM with three tasks in one capture, each witnessed. diff --git a/docs/specs/desktop-app-environments/several-tasks/spec.md b/docs/specs/desktop-app-environments/several-tasks/spec.md deleted file mode 100644 index 7da922ce86..0000000000 --- a/docs/specs/desktop-app-environments/several-tasks/spec.md +++ /dev/null @@ -1,53 +0,0 @@ -# Several tasks - -## Outcome - -One capture yields an environment with several tasks. The building agent -makes each task's change on top of the last in one capture and marks its own -end checkpoint, and may mark a near miss of any task. The export checks each -task against the seed, its own end and its near miss, writes every task's -steps and verifier, and lists them all in the bundle's eval. Each task is -then witnessed on its own fresh computer of the bundle. - -## Requirements - -- `export-desktop-application` takes `--task` once per task and - `--task-end NAME=CHECKPOINT`, repeatable, for each task checked at a - checkpoint other than `--end-checkpoint`. It refuses two tasks of one name, - an end not in `NAME=CHECKPOINT` form or naming none of the tasks, two ends - for one task, and a checkpoint the capture does not hold once at or after - the seed. -- Each task's checks are evaluated at the seed, as the bundle ships it, and - at its own end, and the existing rules hold per task: a check failing at - its end, every check passing on the seed, or no check failing on what the - seed's views show refuses the task. Each refusal names the task and the - end checkpoint it was checked at. -- A checkpoint `near-NAME` is task NAME's near miss. When the capture took - it, at or after the seed, the export refuses the task unless a check fails - on what the near miss's views show; a failure for want of a whole or - readable view does not count. -- The result's `tasks` lists, per task, its name, number of checks, end - checkpoint, the checks failing on the seed, and the near miss's checkpoint - or null with the checks failing there. The bundle holds every task's - `tasks/NAME.json` and `artifacts/NAME-check/verify.py`, one - `evals/ENV.toml` naming them in the order given, and a README section per - task saying where it was checked. -- `export_build_environment` takes `tasks`, at most 8, each - `{task, end_checkpoint}`, the end `end` by default, and refuses an end the - stopped capture did not take before running anything in the computer. It - writes each task to its own file in the computer and passes each task's - end as `--task-end`. Its result's `tasks` is the export's. -- `stop_build_capture` returns `later_drafts`: one per checkpoint named - `end-` taken after `end`, drafted with - `describe-desktop-application-task` from the end checkpoint before it, so - it shows only that task's change, with the draft or the reason there is - none. -- `check_build_task` needs no change: on a computer of the bundle it takes - any task the bundle holds, by its rendered steps and verifier, and a - computer is witnessed once, so each task is witnessed on its own computer. - -## Non-goals - -- No reset inside a capture: later tasks are made on top of earlier ones, - and their checks should not read what a later task changes. -- No measured difficulty; solves stay outside REA here. diff --git a/docs/specs/desktop-app-environments/several-tasks/tasks.md b/docs/specs/desktop-app-environments/several-tasks/tasks.md deleted file mode 100644 index 64a9a5a10c..0000000000 --- a/docs/specs/desktop-app-environments/several-tasks/tasks.md +++ /dev/null @@ -1,8 +0,0 @@ -# Tasks - -- [x] Record the outcome, requirements and non-goals. -- [x] Export several tasks from one capture, each at its own end and near miss, with one eval listing them all. -- [x] Take each task's end with `--task-end`, and refuse duplicate names, malformed or unknown ends, and untaken checkpoints. -- [x] Export several tasks from a build computer and draft each later task from the end before it. -- [x] Document the flow in the building guide and the tasks, export and build-witness guides. -- [x] Add the tests and build TreeLine with three tasks on the arm64 VM, witnessing each. diff --git a/docs/specs/desktop-app-environments/several-tasks/verification.md b/docs/specs/desktop-app-environments/several-tasks/verification.md deleted file mode 100644 index e3b967d314..0000000000 --- a/docs/specs/desktop-app-environments/several-tasks/verification.md +++ /dev/null @@ -1,54 +0,0 @@ -# Verification - -## Tests - -- `src/application/desktop/DesktopSeveralTasks.test.ts` exports two tasks - from one capture, `add-eggs` at `end` and `add-bread` at `end-add-bread`, - with a near miss of the eggs at `near-add-eggs`, and checks the result's - `tasks`, both tasks' files, the eval naming both and the README's two - sections. It refuses `add-bread` checked at `end`, before its change; a - near miss every check of `add-bread` passes; two tasks of one name; an end - for a task not given; an end without `=`; and an untaken checkpoint. Each - of the seven failed on the code before this change, which refused a - second task file. -- `tests/boundary/mcp/buildSeveralTasksMcp.test.ts` runs the build tools - against the real CLI's outputs for that capture: `stop_build_capture` - returns one later draft, from `end` to `end-add-bread`, and - `export_build_environment` writes both tasks to the computer, passes each - end as `--task-end` and reports both; an untaken end is refused before the - export runs. Both failed before the change. - -## TreeLine, arm64 - -On the arm64 Ubuntu 24.04 build host with agentenv-framework 0.9.1431, one -capture of TreeLine 3.1.5 from the Ubuntu archive, through REA's MCP tools: - -- Seed: the Book List template saved as `Documents/books.trln`, one category - `SF Books` with two authors and two books. -- `rename-category` at `end`: the category renamed `Science Fiction`. -- `set-foundation-year` at `end-set-foundation-year`: Foundation's copyright - 1951 to 1952. -- `add-asimov-book` at `end-add-asimov-book`: I, Robot added under Isaac - Asimov with copyright 1950. -- Near misses, after the last end: Foundation 1925 and I, Robot 1905, marked - `near-set-foundation-year` and `near-add-asimov-book`, then the category - `Science Fictoin`, marked `near-rename-category`. - -`stop_build_capture` drafted the first task from `seed` to `end` and the two -later ones each from the end before it, each showing only its own change: -the category's name, Foundation's copyright, and the new book with Asimov's -second child. `export_build_environment` kept all three, each failing on the -seed and at its near miss, and wrote one eval: -`tasks = ["rename-category", "set-foundation-year", "add-asimov-book"]`. - -Each task was then witnessed on its own fresh computer of the bundle, from -its prompt: the seed failed a check, the edit passed every check, a near -miss (`Science Fictoin`, 1925, 1905) failed one and the reset seed failed -again, so all three records, `witness-rename-category`, -`witness-set-foundation-year` and `witness-add-asimov-book`, hold. -`agent-env run --dry-run` of the bundle plans the eval's three tasks. No -solver ran. - -Not tested: a near miss whose only failures come from a view that could not -be read or is cut short, which the export refuses like such a seed, and an -`end-` taken before `end`, which gets no later draft. diff --git a/docs/specs/desktop-app-environments/state-view/plan.md b/docs/specs/desktop-app-environments/state-view/plan.md deleted file mode 100644 index 38cd0978b3..0000000000 --- a/docs/specs/desktop-app-environments/state-view/plan.md +++ /dev/null @@ -1,12 +0,0 @@ -# Plan - -1. Pure modules: format detection and views (text, JSON, key file, XML), - kinds of change per format, and roles from reasons. -2. Readers: dconf through a private file profile, SQLite through the shared - SQLite service with the database and its log staged together. -3. Service: admit the capture Evidence, list paths and versions, read - verified content, and build the Evidence. -4. CLI: `inspect-desktop-application-state`, composing the readers. -5. Docs: a user page and links. -6. Tests: parsers, changes and roles; the service on a synthetic capture with - fake readers; Mousepad and a SQLite-editing script end to end on Linux. diff --git a/docs/specs/desktop-app-environments/state-view/spec.md b/docs/specs/desktop-app-environments/state-view/spec.md deleted file mode 100644 index 3e980fc124..0000000000 --- a/docs/specs/desktop-app-environments/state-view/spec.md +++ /dev/null @@ -1,66 +0,0 @@ -# Read a captured application's state - -## Outcome - -`rea inspect-desktop-application-state ` turns a capture -folder into the application's state: every retained or changed file with a -role, a typed JSON view of each version and the kinds of change between -versions. Export reads this to choose the seed and the data paths; task -generation reads the kinds of change. - -## Requirements - -- CLI only, like the capture. The folder's `capture.json` must be - `capture_desktop_application` Evidence from provider `rea-desktop` v1 with a - valid result, including its baseline non-file inventory; anything else is - refused as invalid input. Captures from before that inventory was recorded - must be made again. -- Retained bytes are read without following links and used only when their - SHA-256 matches the name they are stored under. -- A path in a folder beside a state directory whose name differs from it only - in letter case, such as GIMP's `~/.config/GIMP` beside `~/.config/gimp`, - lies in that state directory. -- Each path gets the reasons the capture supports (state directory, open file, - window title, selected path, dconf application keys, shared desktop - location) and one role derived from them. -- Each version is the baseline or the file after a checkpoint that changed it. - Formats: SQLite through REA's worker on a private copy with any retained - `-wal` or `-journal` beside it (a hot journal is refused by the worker), - refused when either existed but was not retained or the capture did not - record whether it existed (unknown is never read as absent; absence holds - only under content roots the baseline walked completely, with no truncation, - unreadable directory or unchecked path, outside recorded exclusions). A - later incomplete walk leaves a database or sidecar unconfirmed until an - explicit change records it; a subsequent complete walk alone cannot recover - a change the incomplete walk missed. Read SQLite only when the database and - both sidecars are confirmed at that version; dconf through - `dconf dump /` on a private file profile, keeping only - groups whose path names the application; JSON up to 4 MiB and 500 levels - with exact numbers; XML through the shared strict parser, a DOCTYPE read - only when it has no internal subset and its DTD never read - ([XML text checks](../xml-text-checks/spec.md)); key files up to 4 MiB - whose every line parses; zip archives by - their local file header or empty archive signature, as their entries with each entry's own format and - view ([document views](../document-views/spec.md)); text; binary. A gzip - file, told by its magic bytes, is read as the document inside, its members - joined, within a zip entry's 16 MiB and 100-times limits, and its version - records `compression: "gzip"` beside that document's format; past the - limits, or damaged, it has a `view_error`. -- Changes between versions are created, deleted, or lines, values, keys or - rows with added, removed and changed lists (100 each, with counts); content - for binary files and unreadable when a view is missing. Values are JSON - pointers to every value, containers included, compared on one shared path - so memory follows depth, and a pointer over 4096 characters is counted but - not listed; keys are `group/key` with the key escaped as a JSON pointer - segment, so distinct entries never share a name. Zip values name array - members by selector where one names a member in both versions. -- The Evidence has operation `inspect_desktop_application_state`, predicate - type `rea.desktop-application-state` and confidence `inferred`. - -## Non-goals - -- No export, seed selection or task generation. -- No parsing of other binary formats (GVDB other than dconf, LevelDB, Realm, - protobuf), or of compression other than gzip (xz, Zstandard, bzip2); they - are listed as binary. -- No redaction: views contain the user's real data, as the capture does. diff --git a/docs/specs/desktop-app-environments/state-view/tasks.md b/docs/specs/desktop-app-environments/state-view/tasks.md deleted file mode 100644 index 337af55698..0000000000 --- a/docs/specs/desktop-app-environments/state-view/tasks.md +++ /dev/null @@ -1,10 +0,0 @@ -# Tasks - -- [x] Record the outcome, requirements and non-goals. -- [x] Detect formats and read text, JSON, key file and XML views. -- [x] Read dconf and SQLite through private copies. -- [x] Assign reasons and roles; describe kinds of change. -- [x] Build the service and CLI command. -- [x] Document the command. -- [x] Add unit and service tests; run Mousepad and SQLite end to end. -- [x] Run the gates and record verification. diff --git a/docs/specs/desktop-app-environments/state-view/verification.md b/docs/specs/desktop-app-environments/state-view/verification.md deleted file mode 100644 index f645788f26..0000000000 --- a/docs/specs/desktop-app-environments/state-view/verification.md +++ /dev/null @@ -1,52 +0,0 @@ -# Verification - -Run on 2026-11-04 on top of the capture branch (`def249ef5`): gates and source -tests on macOS 26.5 with Node v22.23.1; the end-to-end runs in an Ubuntu -24.04.5 arm64 container with Node v24.22.1, Xvfb, xfwm4, Mousepad 0.6.1, -`dconf-cli` and `sqlite3`. - -## Gates - -- `npm run typecheck`, `lint`, `lint:typed`, `format:check`, `knip`, `jscpd`, - `docs:check`, `mcp-catalog:check`, `verify:test-discovery`, - `verify:architecture-guards` and `scan:todos`: passed, with no lint - diagnostics in the new source files. -- New domain and service tests: format detection and views, kinds of change - for every format (including SQLite rows with and without a primary key), - roles and dconf group matching, and the service on a synthetic capture folder - with fake readers, plus refusal of Evidence from another operation. -- CLI boundary: tool coverage, startup imports and required input schemas - passed (30 tests). - -## Mousepad end to end - -A fresh Mousepad capture (type a line, save `~/Documents/groceries.txt`, stop) -was read with `inspect-desktop-application-state`: - -- `Documents/groceries.txt`: `document` (named in a window title), text view - `["Groceries: milk, eggs, coffee"]`, created between the baseline and - `saved`. -- `.config/Mousepad/accels.scm`: `application_state` (state directory), text. -- `.config/dconf/user`: `application_state` through Mousepad's own dconf - groups, read with `dconf dump`. The `saved` view holds - `org/xfce/mousepad/state/application` with the session naming - `groceries.txt`, and lists the GTK file chooser group separately. Its - `typed` version has no view: dconf replaced the file between the walk and - the read, so the capture left it out as changed since the walk. -- The window manager's xfconf files and GTK's `recently-used.xbel` are - `shared_desktop`; the xbel change lists the `modified` attributes it touched. - -## SQLite end to end - -A script captured with `--executable notesapp` inserted a row and updated -another in `~/.local/share/notesapp/notes.db`, then deleted the first, with a -checkpoint after each step. Read through REA's SQLite worker, the database is -`application_state`, and its changes are `rows`: `notes:[2]` added and -`notes:[1]` changed, then `notes:[1]` removed. - -## Limits of this verification - -- Only Mousepad and a script application were captured; JSON and key-file - state come from unit tests. -- A database in WAL mode with a retained `-wal` file was not exercised end to - end. diff --git a/docs/specs/desktop-app-environments/task-difficulty/cleanup-qualification-2026-11-10.json b/docs/specs/desktop-app-environments/task-difficulty/cleanup-qualification-2026-11-10.json deleted file mode 100644 index 63318b3a34..0000000000 --- a/docs/specs/desktop-app-environments/task-difficulty/cleanup-qualification-2026-11-10.json +++ /dev/null @@ -1,59 +0,0 @@ -{ - "framework": "0.9.1485", - "platform": "linux", - "python": "3.12.16", - "docker_server": "29.1.3", - "cases": [ - { - "stage": "allocation", - "helper_exit": -9, - "cleanup": "verified", - "private_root_removed": true, - "owned_containers": 0, - "owned_networks": 0, - "marked_processes": 0, - "foreign_container_preserved": true, - "failure_retained_folder": false, - "elapsed_seconds": 1.217 - }, - { - "stage": "active", - "helper_exit": -9, - "cleanup": "verified", - "private_root_removed": true, - "owned_containers": 0, - "owned_networks": 0, - "marked_processes": 0, - "foreign_container_preserved": true, - "failure_retained_folder": false, - "elapsed_seconds": 0.968 - }, - { - "stage": "refusal-retry", - "helper_exit": -9, - "cleanup": "verified", - "private_root_removed": true, - "owned_containers": 0, - "owned_networks": 0, - "marked_processes": 0, - "foreign_container_preserved": true, - "failure_retained_folder": true, - "elapsed_seconds": 1.516 - } - ], - "limitations": [ - "Uses actual published LocalSandbox/LocalSandboxProvider and REA's cleanup helper with real Docker resources; no paid model or complete run_bundle solve.", - "Linux process qualification runs inside the isolated test container's process namespace." - ], - "image_repo_digests": [ - "python@sha256:5e2bdb1b0d542d5039cffb8181c65930093949194a65c365dfb1b0fe13a4fa5b" - ], - "framework_wheel_sha256": "14768f69fa9c48c3e4aec2224161747d3643e77a711848e9079dfd62aa5fcca9", - "rea_cleanup_helper_sha256": "789ebeb1de83764a9a274616289e57800ac4631559fc00f8664f262d1893333d", - "observed_at_utc": "2026-11-10T08:43:41.806755+00:00", - "upstream": [ - "https://github.com/scaleapi/agentenv-framework/issues/546", - "https://github.com/scaleapi/agentenv-framework/pull/555", - "https://github.com/scaleapi/agentenv-framework/pull/561" - ] -} diff --git a/docs/specs/desktop-app-environments/task-difficulty/plan.md b/docs/specs/desktop-app-environments/task-difficulty/plan.md deleted file mode 100644 index 042a7a5e54..0000000000 --- a/docs/specs/desktop-app-environments/task-difficulty/plan.md +++ /dev/null @@ -1,16 +0,0 @@ -# Plan - -1. Domain: `taskDifficulty.ts` holds the band, the next-solve decision under - the budget, the record and its README section. -2. Helper: `bridge/agentenv/solve.py` runs one solve with `run_bundle` and - reports it; `AgentEnvSolveHelper.ts` spawns it as an owned process with the - runner's Python and reads its report. -3. Application: `DesktopBuildSolves.ts` measures a task and writes - `difficulty.json` and the README; `DesktopBuildOwnedWork.ts` holds the work - closing REA stops, now shared by a computer's start and a measure. -4. MCP: the contract, its effects, registration with heartbeat progress, and - the CLI-parity list. -5. Docs: the building guide's Measure and Harder tasks sections, the witness, - tasks and build computer guides, and this spec. -6. Tests first: the band and budget rules, and the tool through the MCP with - a stand-in agentenv; then TreeLine tasks on the arm64 VM. diff --git a/docs/specs/desktop-app-environments/task-difficulty/spec.md b/docs/specs/desktop-app-environments/task-difficulty/spec.md deleted file mode 100644 index a6bfcbb5c0..0000000000 --- a/docs/specs/desktop-app-environments/task-difficulty/spec.md +++ /dev/null @@ -1,53 +0,0 @@ -# Task difficulty - -## Outcome - -The building agent can tell how hard a bundle's task is for a model, and -harden it until it lands in a band worth evaluating or training on. One MCP -tool solves the task in fresh computers, adaptively and within a budget, and -records the result in the bundle. - -## Requirements - -- `measure_build_task` takes `bundle` (an absolute folder on the host), - `task`, `model`, `agent` (`claude-code` by default) and `budget_usd`. It - refuses a task whose `tasks/NAME.json` or `artifacts/NAME-check/verify.py` - the bundle lacks, before any solve. -- Each solve runs `bridge/agentenv/solve.py` with the agentenv runner's - Python, which calls `run_bundle` for the one task with the model and agent, - `sandbox="local"` and `emulate=False`, and prints one JSON line: the run's - outcome, instance id, seconds, each check's result from the instance's - verifications, the solver's turns and cost from the last record of its - local trajectory, and agentenv's version; or the error that kept it from - running. The endpoint is whatever agentenv reads where REA starts; REA holds - no model client and passes the environment on unread. -- Solves run one at a time. The band: 3 finished solves with 0 passes is - `too_hard` and with 3 is `too_easy`; otherwise 2 more, and 1 to 3 of 5 is - `in_band`, 4 `too_easy`. A solve that did not finish (`failed`, `unscored`, - `cancelled`) is run again, at most twice, and not counted. Before each solve - the measure stops when the largest cost so far would take the total past the - budget, and after a solve that reports no cost. -- The result and `difficulty.json` at the bundle's root keep, per task: model, - agent, time, band, why it stopped, finished solves (`k`), passes, - unfinished solves, cost and budget, each finished solve's turns, failures - per check, each solve, the task's digest (SHA-256 of its steps file then its - verifier) and REA's and agentenv's versions. A task measured again replaces - its own record. The README's Measured difficulty section lists each task. -- A solve that could not run ends the measure with its error and writes - nothing. A `difficulty.json` or README that exists but cannot be read - or parsed is refused before any solve and again before writing, and left - as it is; record writes to one bundle run one at a time. -- A helper still running after the stop grace has its process group cleared - before REA reads its report, and that read waits at most 5 s. A helper whose - cleanup fails raises a cleanup error naming its process group, and REA keeps - it so closing retries the cleanup. Cancelling, or REA closing its build computers, stops the running - solve, whose run tears its computer down. -- The building guide tells the agent how to measure, how to read failures per - check for brittle checks, and how to harden a task that is too easy while - keeping it sound. - -## Non-goals - -- No parallel solves, no other model than the solver's, and no judge: the - verifier's checks decide every solve. -- No cost cap inside a solve: the budget is checked between solves. diff --git a/docs/specs/desktop-app-environments/task-difficulty/tasks.md b/docs/specs/desktop-app-environments/task-difficulty/tasks.md deleted file mode 100644 index ad7911118e..0000000000 --- a/docs/specs/desktop-app-environments/task-difficulty/tasks.md +++ /dev/null @@ -1,8 +0,0 @@ -# Tasks - -- [x] Record the outcome, requirements and non-goals. -- [x] Decide the band and the budget stop from the solves so far. -- [x] Run a solve in a fresh computer through REA's helper and read its report. -- [x] Record the measure in `difficulty.json` and the README. -- [x] Document measuring and hardening in the building guide. -- [x] Add the tests, measure TreeLine tasks on the arm64 VM and harden one. diff --git a/docs/specs/desktop-app-environments/task-difficulty/verification.md b/docs/specs/desktop-app-environments/task-difficulty/verification.md deleted file mode 100644 index 5187b594e3..0000000000 --- a/docs/specs/desktop-app-environments/task-difficulty/verification.md +++ /dev/null @@ -1,90 +0,0 @@ -# Verification - -## Tests - -- `src/domain/desktop/taskDifficulty.test.ts`: the band for 0 and 3 of 3, - 1 and 2 of 3, 1, 3 and 4 of 5 and an unfinished solve beside finished ones; - 3 solves, 2 more, then a stop; an unfinished solve run again at most twice; - the stop before a solve the largest cost so far would take past the budget, - and after one of unknown cost; the record's counts, cost, turns and - failures per check; and the README section replaced in place. -- `tests/boundary/mcp/buildMeasureMcp.test.ts` calls `measure_build_task` - through the MCP with a stand-in agentenv whose `run_bundle` answers solves - in order: 1 of 3 then 2 more keeps the task at 2 of 5, each solve run once - in the bundle with the model, `claude-code`, `sandbox="local"`, - `emulate=False` and the endpoint REA started with, and `difficulty.json` - and the README record it with the task's digest; 3 of 3 stops as too easy - after running an unfinished solve again; the budget stops before a third - solve; a task the bundle lacks is refused before any solve. All of them - failed before the change: the module and the tool did not exist. After - review, the unfinished solve's error, `RuntimeError: deploy`, is kept in - the result and `difficulty.json`; that test failed first, since the record - dropped every solve's error. - -## TreeLine, arm64 - -On the arm64 Ubuntu 24.04 build host with agentenv-framework 0.9.1431, REA's -MCP server started with `LITELLM_BASE_URL` and `LITELLM_API_KEY`, each task -measured with `anthropic/claude-sonnet-5-5`: - -| Bundle | Task | Budget | Solves | Passes | Band | Turns | Cost | -| -------- | --------------------- | ------ | ------ | ------ | ---------------------- | ----------- | ----- | -| `d-tl3` | `rename-category` | $2.50 | 2 | 2 | undecided, budget stop | 16, 20 | $2.02 | -| `d-tl3` | `set-foundation-year` | $2.50 | 3 | 3 | too easy | 17, 18, 22 | $1.89 | -| `d-tl3` | `add-asimov-book` | $2.50 | 3 | 3 | too easy | 17, 17, 17 | $1.64 | -| `d-hard` | `apply-corrections` | $9 | 3 | 3 | too easy | 106, 61, 74 | $5.14 | - -`rename-category` stopped before a third solve because the largest cost so -far, $1.06, would have taken $2.02 past $2.50. `apply-corrections` hardens -the 15-book reading list with a second document the solver opens in TreeLine, -`Documents/corrections.trln`, listing ten corrections to apply: eight years -and two authors across all three categories, one of them "the same year as -The Quiet Glacier's", with guards on three books left alone. Checked offline -against the app's own views, it fails on the seed, passes when applied, and -fails each near miss: a correction left out, an author without its hyphen, -the cross-reference given another book's new year, and an untouched book -changed. Every solve opened the corrections in a second window and applied -all ten; one typed a year into the tree, saw the stray node and undid it. - -No task landed in the band: the four measures cost $10.69 of the $15 the -validation allowed, and the $4.31 left could not cover 3 solves of another -hardened task at the $1.50 to $2.07 a solve `apply-corrections` cost. Each -solve's computer was torn down by its run. `difficulty.json` and the README -of each bundle list the tasks measured. - -## Forced-stop cleanup qualification, 2026-11-10 - -The original missing-identity review concern is addressed by the private root -owned by each `SolveSandboxRoot` and the provider guarantees shipped in the -pinned `agentenv-framework==0.9.1485`. -[Upstream #555](https://github.com/scaleapi/agentenv-framework/pull/555) exposes -`local_sandbox_ids()` for that root; -[#561](https://github.com/scaleapi/agentenv-framework/pull/561) makes incomplete -termination raise, so the teardown owner retains the work folder for retry. -[Issue #546](https://github.com/scaleapi/agentenv-framework/issues/546) is closed. -The published wheel was inspected, including folder creation before resource -startup, provider termination, and task teardown's folder-removal ordering. - -The [qualification record](https://github.com/morluto/rea/blob/main/docs/specs/desktop-app-environments/task-difficulty/cleanup-qualification-2026-11-10.json) records the -wheel digest and observations. In an isolated Linux arm64 container with the -published provider, Python 3.12 and Docker Desktop's Linux daemon: - -- A helper created a provider-owned folder and was killed with SIGKILL before - returning any sandbox report. REA's cleanup helper discovered and removed it. -- Another helper started a real named/labeled Docker container, labeled network, - and detached Linux process carrying the sandbox marker. After its process - group was killed, REA's cleanup helper removed all three and emptied the root. -- A controlled Docker removal refusal made cleanup fail while preserving the - work folder and container. Removing the refusal and retrying that same root - removed the resources and folder. -- A separate unrelated container stayed running through every case and was - removed by the qualification's own final cleanup. - -The probe invoked the production `solve_cleanup.py` and actual published -`LocalSandbox`/`LocalSandboxProvider` with real Docker resources. It did not run -a paid model or a complete `run_bundle` solve. Linux process checks were inside -the qualification container's process namespace; this does not qualify native -macOS host-process cleanup. Existing conservative REA checks remain in place. -Controlled TypeScript cleanup/report/cancellation regressions also passed: -22 tests across `AgentEnvSolveHelper`, `SolveSandboxRoot`, and -`DesktopBuildSolves`. diff --git a/docs/specs/desktop-app-environments/tasks/plan.md b/docs/specs/desktop-app-environments/tasks/plan.md deleted file mode 100644 index 060cb9ed4c..0000000000 --- a/docs/specs/desktop-app-environments/tasks/plan.md +++ /dev/null @@ -1,15 +0,0 @@ -# Plan - -1. Domain: the task schema and its refusals (`appTask.ts`), the TypeScript - evaluator (`appTaskChecks.ts`), the Python verifier and the task, eval and - README renderers (`appTaskPython.ts`), and the net change with suggested - checks (`appTaskDraft.ts`). -2. Export: share the owned paths and state files by home path between the - export and the draft, read and validate the task file against the seed - and end views, and write its files with the bundle. -3. CLI: `describe-desktop-application-task` and the export's `--task`. -4. Docs and skill: the user guide, links, and a skill reference for agents. -5. Tests: one fixture of views and checks of every kind with expected - outcomes, asserted for the TypeScript evaluator and for the rendered - `verify.py` under `python3 -I`; suggestions per format; the export and the - draft on the synthetic capture; the real Mousepad and LibreCAD captures. diff --git a/docs/specs/desktop-app-environments/tasks/spec.md b/docs/specs/desktop-app-environments/tasks/spec.md deleted file mode 100644 index 65a718ac79..0000000000 --- a/docs/specs/desktop-app-environments/tasks/spec.md +++ /dev/null @@ -1,94 +0,0 @@ -# Tasks for an exported desktop application - -## Outcome - -Each capture yields one agentenv task in its exported bundle, or several, -as [several tasks](../several-tasks/spec.md) describes. An agent writes -the task's prompt and declarative checks from the change the capture -recorded; REA validates the task against the capture and keeps it only if its -checks fail on the seed and pass on the captured end state. The bundle runs -the task with a computer-use agent and grades it with a verifier that reads -the app's `data/get` and evaluates the same checks. REA stays model-free and -never runs code the agent wrote. - -## Requirements - -- `rea describe-desktop-application-task CAPTURE` (CLI only) returns Evidence - with operation `describe_desktop_application_task` and predicate type - `rea.desktop-application-task-draft`: the environment name, title and window - class; the export's owned paths; each file under them whose state differs - between its first and last version, with role, both versions and the net - change from `diffStateViews` (text listing each line once, plus the lines at - both ends whose count changed); and a draft task with a placeholder prompt - and checks suggested from the net change of documents, or of application - state when no document changed. Views are shown only for those files, cut at - 200 items and 2,000 characters. A draft with no files says why in `notes`: - `no_change`, `unowned_changes` with up to five changed home paths and their - roles, `uncheckable_changes` with the dconf databases whose application - keys were read and changed, `unreadable_changes` with the dconf databases - that changed but could not be read and the read `error`, and - `no_document`; a drafted file whose suggestions are thin gets one naming - its `file`: `by_position`, `view_state_only`, `long_text`, `cut_view` or - `unreadable_view`. -- The task file is JSON with a portable `name` other than `smoke`, a `prompt` - and 1 to 32 `checks`, parsed by a zod schema in `src/domain/desktop/`. Check - kinds: `file_present`, `file_absent`, `lines_present`, `lines_absent`, - `line_count` (`exact` or `contains`; `equals`, `at_least` or `at_most`), - `value_equals` (optional numeric `tolerance`) and `value_absent` (RFC 6901 - pointer, with selectors on arrays: `[KEY=VALUE]` by a field, `[@KEY=VALUE]` - by an attribute, `[>PATH=VALUE]` by what one to three `/`-separated steps - inside the member hold: in XML a child element's text with its whitespace - collapsed, a grandchild's (`A/B`) or, ending `NAME@ATTR`, a child's - attribute; in JSON the string at those keys), `text_equals` and - `text_contains` (an XML element's - whole text at a pointer, optional `normalize_whitespace`; see - [XML text checks](../xml-text-checks/spec.md); with `text_attribute`, the - values of that attribute on the element and its descendants in document - order instead of its text nodes, as Scribus's ``), - `member_count` (the members of the array at a pointer, a JSON array or an - element's `children`, or of those an optional `matching` selector matches; - `equals`, `at_least` or `at_most`), `row_present`, `row_absent` and - `row_count` (SQLite table, `where` by column). Ids default to `check-N` and - must be unique. -- Semantics: an absent file reads as empty; a file without a view fails every - check but presence; line checks need a text view and row checks a SQLite - view; JSON equality by value, never a boolean for a number; `contains` - matches a line holding it; checks decided by what a view leaves out, and - `value_equals` of a whole object or array, fail on a truncated view; - `member_count` fails when its pointer names no array, an absent file's - included, and its empty pointer names the whole file. No - regular expressions: a pattern run on agent-written text can stall the - verifier, and the two evaluators would read some differently. -- Refusals, each naming the check: a file outside the owned paths or not - spelled as a home path; the empty pointer, except in `member_count`; a - pointer not starting with `/` or into text; a `matching` that is no - selector; a repeated line; a count without exactly one comparison; an - empty `text_attribute`; a `tolerance` whose value is not a number; a - value that names the captured home or looks like a date and time (ISO - 8601, or C's `asctime` form); - the draft's placeholder prompt. -- `export-desktop-application --task FILE` evaluates the checks on the state - view's first versions (the seed) and last versions (the end), refuses a - task whose every check passes on the seed and a check that fails at the end, - and, before [several tasks](../several-tasks/spec.md), refused more than - one task file. It writes `tasks/NAME.json` (deploy_env, - deploy_agent, add_skills, start_computer_recording, prompt_agent, - env_outcome_verifier, end_computer_recording), - `artifacts/NAME-check/verify.py` and `evals/ENV.toml` naming the task, and a - README section with the prompt, the checks and the solve-rate recipe. -- The verifier finds the app among the computer's child environments, calls - its `data/get` and evaluates the checks in Python with the TypeScript - evaluator's semantics, one result per check; it raises when the app cannot - be reached. -- The product skill tells an agent how to describe the change, write the - prompt and the checks, and export. - -## Non-goals - -- No REA CLI command that runs agents; the user guide gives the - `agent-env run` recipe, and the build tools measure a solve rate with - [task difficulty](../task-difficulty/spec.md). -- No checks over dconf keys, which `data/get` serves as binary, or over files - outside the owned paths. -- No timestamp detection beyond ISO 8601 and `asctime` date-times; other volatile values - are left to the author. diff --git a/docs/specs/desktop-app-environments/tasks/verification.md b/docs/specs/desktop-app-environments/tasks/verification.md deleted file mode 100644 index a5f229a02a..0000000000 --- a/docs/specs/desktop-app-environments/tasks/verification.md +++ /dev/null @@ -1,132 +0,0 @@ -# Verification - -Run on 2026-11-04 on top of the vendor packages branch (`7a6ac88ab`): gates -and source tests on macOS with Node v22.23.1 and Python 3.11; Linux tests in -the `rea-desktop-e2e` Ubuntu 24.04 arm64 container with Node v24.22.1 and -Python 3.12.3; agentenv-framework 0.9.1431 from the runner virtual -environment, with local Docker for the computer run. - -## Gates - -- `npm run typecheck`, `lint`, `lint:typed`, `format:check`, `build:cached` - then `knip`, `jscpd`, `docs:check`, `verify:test-discovery` and - `verify:architecture-guards`: passed, with no lint, typed-lint or - duplication findings in the new or touched files. -- `docs:build`: passed, including the new guide and this step's spec pages. -- `npx vitest run src/domain/desktop src/application/desktop src/desktop` - with the two Python boundary tests: 261 passed and 14 skipped on macOS; 274 - passed and 1 skipped in the container. -- CLI boundary tests `cliInputSchemaRequired`, `cliToolCoverage` and - `cliStartupImports`, `setupSkill`, and the Python boundary tests - `desktopExportPython` and `desktopTaskPython` (macOS and container): passed. -- New tests: 68 checks covering every kind against views of every format - (text, a truncated text view, JSON with numbers, booleans, arrays and - escaped pointers, a key file, a truncated XML view, SQLite with a truncated - and an unreadable table and a database whose tables were cut, binary, a - view error, an absent file), asserted for the TypeScript evaluator and for - the rendered `verify.py` under `python3 -I` with a stub protocol client, - which agree on every result and description and call the app at - `/svc/notes`, including `contains` given a pattern-like string and whole - objects and arrays on truncated XML and SQLite views; 19 task refusals, - among them a `regex` field; suggestions for text, a format rewrite, key - files, SQLite rows and created and deleted files, and drafts that keep a - database whose rows changed under an unchanged hash and a file whose - truncated views match while it changed, and that leave out a database with - one version; the export with a task and nine - refusals, among them a byte-order mark reported with the reader's fix, none - writing a bundle; and a draft the export accepts. - -## Real captures - -- Mousepad (`~/Documents/todo.txt`, "buy bread" then "buy bread" and "buy - milk"): the draft lists `Documents/todo.txt` (document, `lines`, added "buy - milk") and `.config/Mousepad/accels.scm` (application state, created, no - view), and suggests `lines_present` "buy milk". A task with that check and - "buy bread" kept was exported; its checks fail on the seed (`milk-listed`) - and pass at the end. A task checking only "buy bread" was refused as - passing on the seed, one checking "buy eggs" as failing at the end, and two - `--task` flags as more than one task. agentenv's dry run planned the task, - the verifier artifact and the eval, leaving the smoke task to - `--task smoke`. -- LibreCAD (`~/Documents/plate.dxf`, four holes added, rewritten from DXF R12 - to 2007: 2,944 lines added, 86 removed): the draft lists the 11 lines found - at both ends whose count changed and suggests counts of `SECTION`, `ENDSEC` - and `CIRCLE`. A task with `CIRCLE` equals 9 was exported: 5 on the seed, 9 - at the end. -- Typora, captured again (`~/Documents/trip.md`, a to-do "Buy trail snacks" - and a table row "Sun | Lake swim" added): among about 25 changed files - under `.config/Typora`, the draft suggested only the document's two new - lines. A task checking both, with "- [ ] Book the cabin" kept, was exported - (`snacks` and `sunday` failing on the seed); tasks checking only the cabin - or a kayak to-do were refused. The capture made before the vendor package - fields is refused as malformed (`apt_repositories.0.architectures`), as - expected. -- The generated verifiers, run under agentenv-protocol 0.9.1431 against homes - holding the seed and the captured end state, read through the generated - class's own `_views`: Mousepad and LibreCAD each fail on the seed and pass - at the end. - -## In an agentenv computer - -The CLI-exported Mousepad bundle, with two model-free tasks added on a -scratch copy, ran with `agent-env run --no-emulate` on local Docker (arm64): -the app image built and reached ready, and the generated verifier reached the -app through the computer's card at `/svc/mousepad` under the run's grant. On -the seed it scored 0 (`milk-listed` false, `bread-kept` true); after -`load_artifact` put the captured end-state `todo.txt` in `Documents` it -scored 1. Both sandboxes were torn down. - -A fresh capture of the same edit, exported with a task of three checks -(`milk` and `bread` present, `one-milk` counting exactly one "buy milk" -line), was then run without an agent and driven through the computer's own -input tools: - -- `agent-env run --dry-run` of the bundle planned the eval's one task, - `add-milk`, with Claude Code as the solver. -- A probe task (`deploy_env`, then the exported verifier) ran with `--keep`: - the `env_outcome_verifier` step scored 0, recording `milk` and `one-milk` - false and `bread` true. -- On that computer, `computer_click`, `computer_key` and `computer_type` - added "buy milk" in Mousepad and saved it with Control+S. The exported - `verify.py`, called under the computer's control-token grant as the step - calls it, then passed all three checks. A second "buy milk" line failed - only `one-milk` (2 lines), and after `data/reset` the checks read as on the - seed again. -- The sandbox was torn down with no container left. - -The Typora bundle ran the same way, its build installing Typora from the -vendor repository: the probe's verifier step scored 0 (`snacks` and `sunday` -false, `cabin-kept` true); the same input sequence as the capture (Control+Home, -two ArrowDown, End, Enter, the to-do, Control+End, Control+Enter, the row, -Control+S) made all three checks pass; and after `data/reset` they read as on -the seed. That sandbox was torn down too. - -## Solve rate - -The three bundles, exported again from this branch's final code, ran with the -documented recipe: `agent-env run --task NAME --agent claude-code ---model anthropic/claude-sonnet-5-5 --no-emulate`, three times each, on local -Docker through a LiteLLM endpoint. - -| Task | Runs passed | Cost per run (USD) | -| -------------------- | ----------- | ------------------ | -| Mousepad `add-milk` | 3 of 3 | 0.91, 0.39, 0.39 | -| Typora `plan-sunday` | 3 of 3 | 0.77, 0.31, 0.43 | -| LibreCAD `add-holes` | 3 of 3 | 0.81, 0.32, 0.34 | - -Costs are Claude Code's own totals, $4.67 for the nine runs. Every run worked -through the computer's input tools only (screenshots, clicks, keys, typing; -in LibreCAD, circle commands typed into its command line), loaded the app's -skill first, and passed every check of its task. None failed to finish. - -Each task is a single change the user made in one sitting, so Claude Sonnet -5.5 solves all three every time: they show the exported environments work -end to end, not how hard a task can be. - -## Limits of this verification - -- SQLite and dconf readers were not exercised on the host captures, which - hold text files; SQLite checks are covered by synthetic views. -- Namespaced XML and CDATA, which the export once refused or read - differently, are covered by the document views' parity tests on real - Inkscape and LibreOffice saves, not by a host capture. diff --git a/docs/specs/desktop-app-environments/vendor-deb-files/plan.md b/docs/specs/desktop-app-environments/vendor-deb-files/plan.md deleted file mode 100644 index 6e2a3082fc..0000000000 --- a/docs/specs/desktop-app-environments/vendor-deb-files/plan.md +++ /dev/null @@ -1,24 +0,0 @@ -# Plan - -1. Schema: optional `package_file` (name, SHA-256, size, package, version, - architecture, Depends and Pre-Depends entries) and `package_file_reason` in - the capture's package section, so captures written before them still - parse. -2. Pure readers: `dpkg-deb --field` output on the deb822 paragraph reader the - apt sources parser already uses, the match against the installed version, - and the names apt installs before the file. -3. Host adapter: `dpkg-deb` through the inventory's query runner, then the - shared stable-file hash for the SHA-256 and size, with a failed close - carried by its cleanup lease; `capture-desktop-application --package-file`. - The library walk also runs for a local install, with apt's origins read for - it. -4. Export: the install decision takes `--package-url` and its refusals carry - their field and remediation; the class renders `downloads=[Download(...)]` - and `run=[RunScript(...)]` beside `packages`, the export writes - `install-package.sh`, and the README and limitations say what the bundle - does not hold and what the operator answers for. -5. Docs and tests: real `dpkg-deb` output for the parser, a fake query runner - for the inventory, the export service for a local-deb capture and its - refusals, the run script under `sh` with a stub `dpkg`, a package built by - `dpkg-deb` on Linux, and the class declared with agentenv-framework - 0.9.1431. A real VariCAD capture and export follow. diff --git a/docs/specs/desktop-app-environments/vendor-deb-files/spec.md b/docs/specs/desktop-app-environments/vendor-deb-files/spec.md deleted file mode 100644 index c6c198a17d..0000000000 --- a/docs/specs/desktop-app-environments/vendor-deb-files/spec.md +++ /dev/null @@ -1,94 +0,0 @@ -# Applications installed from a downloaded .deb file - -## Outcome - -A closed-source application the user installed from a `.deb` file they -downloaded, which no apt repository lists, first VariCAD from varicad.com, is -captured with that file's control fields, SHA-256 and size and the packages of -the libraries it loads, and exported as a computer app that downloads exactly -that file from a URL the operator chooses when the bundle is put, installs its -dependencies with apt, installs the file with dpkg, and starts it. Neither the -capture nor the bundle holds the package. - -## Requirements - -- Capture: `--package-file PATH` names the `.deb` file, made absolute against - the caller's directory. REA reads its control fields with - `dpkg-deb --field PATH Package Version Architecture Depends Pre-Depends`, - through the inventory's query runner and without a shell. When its Package, - Version and Architecture are the installed package's name (without an - architecture qualifier), version and architecture as dpkg reports them, REA - streams the file once through one admitted descriptor, which must hold still - while it is read, for its SHA-256 and size. The package section then records - `package_file`: `name` (the file name without its folder), `sha256`, `size`, - `package`, `version`, `architecture`, and `depends` and `pre_depends`, the - entries of each relationship field as the file declares them. Otherwise - `package_file_reason` says why: dpkg reports no installed version of the - application, the path is not a regular file, `dpkg-deb` is missing or cannot - read it, the reported fields contain invalid UTF-8 or lack one of the three - identity fields, it holds another package, version or architecture, or it - could not be read. A descriptor whose close fails - fails the capture with its owner. The file is never copied into the capture - folder. -- Library packages are walked as for a vendor repository's package also for a - local install, a `deb` package whose installed version no apt source lists, - since a vendor-built binary may load libraries its Depends leaves out. They - are matched against the origin `apt-cache policy` reports for every package - file, so a local install's library packages from the Ubuntu archive count as - installable. -- Export: `--package-url URL` names where the computer downloads the file. - When the package is a `deb` that neither the Ubuntu 24.04 archive nor a - declarable vendor repository installs, the capture recorded `package_file`, - and the URL is given, the class declares: - - `Download(url=URL, sha256=..., to="vendor/", arch=...)`, which - agentenv fetches once when the bundle is put and refuses unless its - SHA-256 is the captured file's; - - `Packages(apt=[...])` with the first alternative of each Depends and - Pre-Depends entry, without its version constraint or architecture - qualifier, once each, then the capture's library packages, and - `dconf-cli` when settings are loaded; - - `RunScript(script="install-package.sh")`, a script the export writes into - the environment folder: `#!/bin/sh`, `set -eu`, `dpkg -i` of the - download, then `rm -f` of it, each path shell-quoted. agentenv runs it as - root with `cd && ./install-package.sh` once the apt packages are - installed and the download is placed, with the network off. - - The bundle supports only the file's architecture: `amd64` or `arm64`, or the - capture host's for an `all` package. When a recorded vendor repository could - not be declared, the file is used instead and the repository is left out - with a limitation. - -- Refusals, each naming the input to change and how: a local install exported - without `--package-url`, which says to capture with `--package-file` and - export with `--package-url`, or only the latter once the capture recorded the - file; `--package-url` when the capture recorded no package file, or recorded - `package_file_reason`, which the refusal repeats; `--package-url` for a - package the archive or a declared repository installs; a URL that is not - written as `http://` or `https://`, or that holds a user name or password; - and a file built for an architecture no computer runs. -- README and limitations: the computer downloads the URL when the bundle is - put and checks its SHA-256; the bundle does not contain the package; vendor - sites may refuse automated downloads, so the URL must point at a copy of the - file the operator may use; the package's licence, such as a trial's terms, - is the operator's to check; and the computer installs exactly that file's - version. A dependency entry whose first alternative names no package is - listed as not installed. - -- Found by VariCAD, the first such application, and needed by any like it: - - The capture's state roots include dotfiles in the home named after the - application (`.rc`, or `.` followed by `-`, `.` or `_`), so a - file it writes on its first run and only reads afterwards is seeded. - - Seeding respells the captured home in UTF-16 text files that start with a - byte-order mark, keeping the mark. - - Readiness also waits for a window of the application's class that the - taskbar lists, so a splash screen of the class does not count as the - application being ready. - -## Non-goals - -- Downloading the package from the vendor's site, or keeping it in the - capture or the bundle. -- Checking that the Ubuntu 24.04 archive offers every dependency, choosing an - alternative other than the first, or resolving virtual packages. -- Pinning the dependencies' versions. -- Other package formats: RPMs, tarballs and installers. diff --git a/docs/specs/desktop-app-environments/vendor-deb-files/verification.md b/docs/specs/desktop-app-environments/vendor-deb-files/verification.md deleted file mode 100644 index b47a701172..0000000000 --- a/docs/specs/desktop-app-environments/vendor-deb-files/verification.md +++ /dev/null @@ -1,163 +0,0 @@ -# Verification - -Run on 2026-11-04 on top of the desktop tasks branch: gates and source tests on -macOS with Node v22.23.1; Linux runs in the `rea-desktop-e2e` Ubuntu 24.04 -arm64 container with Node v24.22.1 and dpkg 1.22.6. The real VariCAD run was on -an x86_64 Ubuntu 24.04 EC2 host, VariCAD being amd64 only; see -[VariCAD](#varicad). - -## Gates - -- `npm run typecheck`, `lint`, `lint:typed`, `format:check`, `knip` (after - `build:cached`), `jscpd`, `docs:check`, `docs:build`, - `verify:test-discovery` and `verify:architecture-guards`: passed, with no - lint or typed-lint diagnostics in the touched files. jscpd reports no clone - in the new code; the one clone it lists in a touched file, - `DesktopApplicationCapture.test.ts` against itself, was there before. -- `npx vitest run src/domain/desktop src/application/desktop src/desktop` with - `tests/boundary/providers/desktopInstallScript.test.ts`, - `desktopExportPython.test.ts` and `desktopTaskPython.test.ts`, with the CLI - boundary tests below: on macOS 325 passed and 15 skipped (Linux-only cases, - the real `dpkg-deb` one among them). Without the CLI tests, in the container - on the x86_64 host, 309 passed and 1 skipped (a checkpoint recorder case - skipped there before this change). -- The CLI boundary tests `cliInputSchemaRequired`, `cliToolCoverage` and - `cliStartupImports`: 30 passed. - -## Tests - -- The `dpkg-deb --field` reader on dpkg 1.22.6's output for a package whose - Depends has alternatives, version constraints and a `:any` qualifier, with - Pre-Depends; a field the file lacks, a folded field, and output without - Package, Version or Architecture. `dpkg-deb` itself prints a relationship - field on one line, also for a hand-built archive whose control file folds - it. -- The match against the installed version, an architecture-qualified dpkg - name included, and its reason when the version, architecture or name - differs; the dependency names (first alternative, no version or qualifier, - once each) and entries that name no package. -- The package file adapter with a fake query runner: the facts and the exact - `dpkg-deb` arguments; another version; `dpkg-deb` missing or exiting 2; an - application dpkg did not install (no `dpkg-deb` call); a directory. On Linux, - a package built with `dpkg-deb --build` read by the real `dpkg-deb`. -- The inventory: a local install, which no apt source lists, walks its - libraries and matches them to the archive by origin, and records its package - file through `inspectLinuxApplication`. -- The capture schema: an inventory without the new fields, with - `package_file` and with `package_file_reason` parses; a file name that is a - path, `..` or empty does not. -- The install decision: a local-deb capture with a URL (the download, its - path and architecture, the apt packages, the library packages); an `all` - package on the capture host's architecture; a recorded vendor repository - that cannot be declared, left out in favour of the file; each refusal (no - URL with and without a recorded file, a URL without a recorded file and - with `package_file_reason`, a URL for an archive or a declared repository - package, `ftp://`, `HTTPS://`, a bare host and path, a URL with a password, - which the refusal does not repeat, and an `i386` file); the limitations. -- The renderers: the `@linux(...)` declaration, the import, the run script and - its quoting, and the README. The export service: a local-deb capture with a - URL writes `install-package.sh` and no `vendor/` folder, and declares the - download; without a URL it refuses with the `package_url` field and writes - nothing. -- The run script, run as agentenv runs it (`cd && ./install-package.sh`) - with a stub `dpkg`, on a download named `vendor/vari'cad $HOME *.deb`: - `dpkg -i` receives that one path and the file is removed; when `dpkg` fails - the script fails and the file stays. - -## Checks beyond the tests - -- A sample class for VariCAD's file (Depends `libc6 (>= 2.34)`, - `libgl1 | libgl1-mesa-glx`, `libstdc++6:any (>= 12)`, `libx11-6`; library - packages `libglu1-mesa`, `libxt6t64`) renders: - - ```python - @computer_app(supports=[{"os": {"type": "linux", "display": ["x11"]}, "arch": ["amd64"]}]) - @linux( - packages=Packages(apt=["libc6", "libgl1", "libstdc++6", "libx11-6", "libglu1-mesa", "libxt6t64"]), - downloads=[Download(url="https://mirror.example.com/varicad/varicad2026-en_2.03_amd64.deb", sha256="5f5f…5f", to="vendor/varicad2026-en_2.03_amd64.deb", arch="amd64")], - run=[RunScript(script="install-package.sh")], - launch=Launch(at="boot", command=["varicad"], window={"class": "Varicad"}, ready=Ready(window=True)), - paths=PATHS, - skill="SKILL.md", - ) - ``` - - `python -m agentenv_protocol.computer._declare` from agentenv-framework - 0.9.1431 exited 0 and declared that download (`arch` `amd64`), the run - script with scope `system`, and the packages. - -- `rea export-desktop-application` on a hand-written local-deb capture with - `--package-url` wrote `envs/varicad/install-package.sh` and listed the - download, SHA-256 and licence limitations; `agent-env run --dry-run` - with 0.9.1431 exited 0. Without `--package-url` the export failed with - `invalid_request` on path `package_url` and wrote no bundle. -- In the container, as root: a `rea-sample` package built from `/usr/bin/true` - and installed with `dpkg -i` was inventoried with `packageFile` naming its - file. The inventory recorded `package_file` (its SHA-256, size, and - `libc6 (>= 2.34)`, `libgl1 | libgl1-mesa-glx`), walked the local install's - libraries to `library_packages: ["libc6"]` once apt's lists were present, - explained a rebuilt `1.0-2` file as holding another version than the - installed `1.0-1`, and a text file as one `dpkg-deb` could not read. -- In a container with `--network none`, as root, the exported script - installed `vendor/rea sample_1.0-1.deb` from `/opt/app`, which dpkg then - reported as `install ok installed`, and removed it. - -## VariCAD - -VariCAD 2026.2.05 (`varicad_2026.2.05_amd64.deb`, 153,794,020 bytes, SHA-256 -`1d73f297…6e72`), downloaded from varicad.com in a browser and installed with -`apt-get install ./varicad_2026.2.05_amd64.deb` in the `rea-desktop-e2e` image, -built natively on the x86_64 host. `apt-cache policy` listed only -`/var/lib/dpkg/status` for it: a local install. - -VariCAD runs only after logging in to a VariCAD account, which starts its -30-day trial. Before the capture, as prior use, VariCAD was run once: its -first-run dialogs, the login, the trial and its licence, then DXF output set to -AutoCAD R12 in the save dialog's settings. VariCAD's default, DXF 2004, writes -about 20,700 lines, past the 5,000 the text view keeps, so the circles would -fall outside it. - -- **Capture.** `capture-desktop-application --desktop-entry varicad - --argument /home/ada/Documents/plate.dxf --package-file - /home/ada/Downloads/varicad_2026.2.05_amd64.deb` while four mounting holes were - added to the LibreCAD plate and it was saved over `Documents/plate.dxf` as DXF. - The package section recorded `package_file` (`varicad` 2026.2.05 amd64, the - file's SHA-256 and 35 Depends entries), no apt sources, 79 library packages - and nothing missing, unpackaged or uninstallable. The account's name and - password appear nowhere in the capture. -- **First run in the computer.** The first export left out - `~/.varicad-cfg.ini` and `~/.varicad-work.ini`, which VariCAD writes on its - first run and only reads afterwards. In the computer it showed its first-run - dialogs again, and its splash screen, a window of class `varicad` kept above - the others, counted as the app being ready. The capture now treats dotfiles - named after the application as state roots. `~/.varicad-work.ini` is UTF-16 - and names `/home/ada/.varicad`, so seeding now respells UTF-16 text with a - byte-order mark. Readiness now also waits for a window of the class that the - taskbar lists. -- **Export.** `export-desktop-application ... --task task.json --package-url - http://127.0.0.1:8765/varicad_2026.2.05_amd64.deb`, a copy served on the - host's loopback interface, since varicad.com refuses automated downloads. The - owned paths were `.varicad`, `.varicad-cfg.ini`, `.varicad-work.ini` and - `Documents`. The task `add-holes` checks `CIRCLE` lines equal 9 and failed on - the seed (`nine-circles`). -- **Computer.** `agent-env run --task seed-probe --keep --no-emulate` - with agentenv-framework 0.9.1431 on local Docker: the build fetched the file - from the URL and checked its SHA-256, installed the apt packages, and ran - `install-package.sh`'s `dpkg -i`. The image passed agentenv's probe. VariCAD - booted logged in, on its trial reminder, with the plate open, its path - respelled to `/home/user/Documents/plate.dxf`. The exported verifier scored 0 - on the seed (5 `CIRCLE` lines). -- **The edit in the computer.** Driven through `computer_click`, `computer_key` - and `computer_type` only: Continue, OK, `ccr` four times in the command line - with radius 5, then Control+S, the DXF type and the overwrite. The verifier - then passed (9 lines), and after `data/reset` it failed again (5 lines). -- Only one computer ran VariCAD at a time, as its licence requires. - -## Limits of this verification - -- The package file was downloaded from a loopback copy, not from the vendor, - whose site refuses automated clients. -- No agent was run on the VariCAD task, so it has no solve rate. -- The dependencies' first alternatives were not checked against the Ubuntu - 24.04 archive; one the archive lacks fails the build. -- Library packages of a local install were mapped on Ubuntu 24.04 arm64 only. diff --git a/docs/specs/desktop-app-environments/vendor-packages/plan.md b/docs/specs/desktop-app-environments/vendor-packages/plan.md deleted file mode 100644 index 1e96629977..0000000000 --- a/docs/specs/desktop-app-environments/vendor-packages/plan.md +++ /dev/null @@ -1,33 +0,0 @@ -# Plan - -1. Schema: optional `apt_repositories` (each with its entry, key, and an - architecture restriction and release that older captures omit), - `library_packages`, - `uninstallable_library_packages`, `missing_libraries`, - `unpackaged_libraries` and `library_packages_reason` in the capture's - package section. -2. Pure readers: apt sources (one-line and deb822, with apt's entry - positions), `apt-get indextargets` output, apt's list file names, gpgv's - status and ASCII armor, an OpenPGP packet splitter that fingerprints each - transferable key; ELF DT_NEEDED and RUNPATH/RPATH on the shared ELF - header, program header, dynamic entry and string table readers; the - `ldconfig -p` cache, `apt-cache policy` for several packages, and the - library walk with host reads injected. -3. Host adapters: an apt repository inventory that matches sources through - `apt-get indextargets` and runs gpgv on private keyring copies whose folder - is released through `ArtifactResourceScope`, a library package inventory - that reads ELF images through owned file handles and batches - `dpkg-query -S` and `apt-cache policy`, and Debian package identification - split out of the Linux inventory, with an injectable query runner and apt - folders. -4. Capture: retain each verified key in the content store before the - baseline; a key over `--max-file-bytes` or the content budget is recorded - as unverified. -5. Export: decide the install (archive, usable vendor repositories, or a - refusal), copy keys from retained content, render `AptSource` once per URI - and suite, the package as `/`, the host's architecture - and library packages, add `--no-sandbox` for Electron, and state each in - the README and limitations. -6. Docs and tests: real-format fixtures from the Typora container for the - parsers, fake query runners for the inventory, the export service for a - vendor capture and its refusal, and a real Typora capture and export. diff --git a/docs/specs/desktop-app-environments/vendor-packages/spec.md b/docs/specs/desktop-app-environments/vendor-packages/spec.md deleted file mode 100644 index 92ec44ea41..0000000000 --- a/docs/specs/desktop-app-environments/vendor-packages/spec.md +++ /dev/null @@ -1,134 +0,0 @@ -# Applications from a vendor apt repository - -## Outcome - -A closed-source application installed from its vendor's apt repository, first -Typora from `https://downloads.typora.io/linux`, is captured with the -repository, the key that signs it and the packages of the libraries it loads, -and exported as a computer app that installs it from that repository, trusting -that key, with those libraries, and starts it. - -## Requirements - -- Capture: for each apt source of the installed version whose origin is not - `Ubuntu`, the package section records a repository in `apt_repositories`: - the source as `apt-cache policy` lists it, and the sources file entry - `apt-get indextargets` names for it (its `Sourcesentry` file and line or - deb822 stanza; `sources.list`, one-line `*.list` or deb822 `*.sources`) with - its authored URI, suite and components, and its architecture restriction. The optional - `repo_uri` field records the index's sanitized `Repo-URI` independently of - the authored URI. When APT selects a different suite, `repo_suite` - records the index's source suite separately from the authored value. - One-line source words keep their authored spelling, including quotes and - escapes. `repo_components` records the effective component words when - one-line parsing changes their spelling. Architecture and signing-key options - use APT's decoded option values. Undecodable UTF-8 entries and index - paragraphs are withheld without substituting replacement characters. - A policy query with undecodable bytes leaves repository attribution unknown. - Flat repositories - (suite `./` or `/`, no components), `[signed-by=…]` and `Signed-By:` options - and architecture options are read; a deb822 stanza's URIs and suites are - kept as lists, never expanded into every pair. REA matches `$(ARCH)` in - a URI or suite against the effective architecture read from `apt-config` - and keeps the authored URI and suite. A template match requires that - configuration fact. `release` is the release's - Suite (`a=`), or else its Codename, from the same index target. A user name - or password in a URI, up to the last `@` before its path as apt reads it, - is removed from every sources entry, from `apt-get indextargets`' - `Description`, `Repo-URI` and `Base-URI`, and from the sources - `apt-cache policy` lists, as they are parsed, so no stanza, entry, record, - reason or limitation holds it and entries match whether or not apt prints - it. `uri_credentials_removed` records credentials seen in the entry or - index URI. If APT reveals encoded credentials without a safely identifiable - boundary in the authored token, the capture omits that token's value. - Older captures may omit `architectures`, `release`, `repo_uri` and - `uri_credentials_removed`. -- The repository's key is the candidate that verifies the release beside the - index in apt's lists folder (`InRelease`, or `Release` with `Release.gpg`, - named from the target's `Base-URI`) with - `gpgv --status-fd 1 --keyring KEYRING`, where KEYRING is the candidate as a - binary keyring, run through the inventory's query runner without a shell. - A VALIDSIG counts whatever gpgv's exit status, unless a BADSIG, EXPSIG, - EXPKEYSIG, REVKEYSIG or ERRSIG names the same key. Candidates are the - entry's Signed-By keyrings, or every `.gpg` and `.asc` key in - `/etc/apt/trusted.gpg.d` and `/etc/apt/trusted.gpg`. A deb822 Signed-By that - holds an armored key block, as `add-apt-repository ppa:…` writes it, is the - entry's only candidate: its continuation lines are stripped, a `.` line read - as an empty one, from the `BEGIN` line to the last `END` line, and the key's - path is the entry's sources file; a held key that does not verify is refused - with a reason naming that file and the release file, and no URL. Each is - written into a private temporary folder, an armored key decoded to binary in - REA, and the folder is removed; a failed removal fails the capture with the - folder's owner and cleanup facts, as does a sources file, key or library - whose handle cannot be closed. When the repository check and the library walk - both fail, the failure keeps both causes and every owner. The verified - key's path, SHA-256, format and primary fingerprint are recorded and its - bytes retained in the capture's content store, within `--max-file-bytes` - and the content budget. A key file holding one key is retained as it is; - from a file holding several, only transferable key blocks whose primary - fingerprint matches are retained, in binary. All versions of that primary - key are kept, including versions carrying different signing subkeys; other - primary keys are excluded. Without a verified key, - `signing_key` is null and `signing_key_reason` says why. Ubuntu Pro ESM - repositories are not checked, with a reason naming the Ubuntu Pro - credentials a computer lacks. -- Library packages, only when the installed version has apt sources and none - is the Ubuntu 24.04 archive, walked beside the repository check: from the - resolved executable, DT_NEEDED is read with REA's ELF readers, at most 512 - distinct needed names per image, recursively. Each soname is resolved as - ld.so does: the RPATH of the needing image and of each loader up to the - executable when the needing image has no RUNPATH, then its RUNPATH - (`$ORIGIN` expanded, paths normalized), then the `ldconfig -p` cache; - libraries in the executable's own folder are the application's. Resolved - libraries are mapped to packages with batched `dpkg-query -S`, and a batched - `apt-cache policy` keeps those the Ubuntu 24.04 archive offers, or any - component of a vendor repository's entry with a verified key, since the - export declares every component. The capture records - `library_packages` (sorted, without architecture qualifiers or the - application's own package), `uninstallable_library_packages`, - `missing_libraries`, `unpackaged_libraries`, and `library_packages_reason` - when the walk was skipped (not an ELF image), stopped at 512 libraries, or - could not read a library. -- Export: a package from the Ubuntu 24.04 archive installs by name as before, - for amd64 and arm64. Otherwise each usable vendor repository is declared as - `AptSource(apt, suite, components, key="apt-keys/.gpg|.asc")` with the - retained key copied into the environment folder (`.asc` for an armored key, - such as one a PPA's Signed-By held), one source per URI and suite; the - package is named `/` from the first declared repository, - so its release wins over the archive, and the bundle supports - only the capture host's architecture. A repository is usable when its key - was verified, its sources entry's URI held no user name or password - (`uri_credentials_removed`; a capture written before that field whose - `uri` still holds them is refused whole, since its library packages counted - that repository), it is reached over http or https, and its architecture - restriction includes the host's. AgentEnv writes a deb822 source. The - exporter and package attribution share the URI, concrete suite and - components that reproduce the observed index identity. A capture with - a templated suite needs `repo_suite` to replay it. A legacy one-line URI - with percent escapes needs a new capture with `repo_uri`. Older captures - can replay complete one-line words. When a word was split during capture, - capture the application again. A value that cannot be represented as - one deb822 token is withheld with the reason. With none usable, the export is refused - naming each repository, by its URI without credentials, and its reason; the - credentials reason names no URI. A capture written before - restrictions and releases were recorded counts its repositories as - unrestricted and names the package alone. For a vendor package, library - packages follow the application's package in `Packages(apt=[…])`, and - uninstallable ones are reported as a limitation; an archive package's - declared dependencies are trusted as they are. -- Electron: when the capture marked the application as Electron and its - command lacks `--no-sandbox`, the launch adds it right after the program, - after any `env` assignments; the README and the export's limitations say - Chromium's sandbox is off and why. -- `data/get` waits a quarter of a second for a write lock on an SQLite file. - -## Non-goals - -- Signed-By fingerprints matched against the signing key, and repositories - reached over anything but http or https. -- Pinning the captured version, carrying the host's apt pinning over, or - checking that the capture host's suite suits Ubuntu 24.04. -- Ubuntu Pro repositories, which need the host's credentials, and other - repositories that need a user name or password: one held in an entry's URI - is refused, and apt's `auth.conf` is not read. -- Libraries an application opens with `dlopen` rather than DT_NEEDED. diff --git a/docs/specs/desktop-app-environments/vendor-packages/verification.md b/docs/specs/desktop-app-environments/vendor-packages/verification.md deleted file mode 100644 index d1928017e0..0000000000 --- a/docs/specs/desktop-app-environments/vendor-packages/verification.md +++ /dev/null @@ -1,131 +0,0 @@ -# Verification - -Run on 2026-11-04 on top of the export branch: gates and source tests on -macOS with Node v22.23.1; Linux runs in an Ubuntu 24.04 arm64 container with -Node v24.22.1 and Typora 1.14.9-1 installed from -`https://downloads.typora.io/linux` as Typora's instructions say (key in -`/etc/apt/trusted.gpg.d/typora.gpg`, `deb https://downloads.typora.io/linux ./`), -plus the Electron runtime libraries and gnupg. - -## Gates - -- `npm run typecheck`, `lint`, `lint:typed`, `format:check`, `knip` (after - `build:cached`, which its `#…-worker` imports resolve into), `jscpd`, - `docs:check`, `verify:test-discovery` and `verify:architecture-guards`: - passed, with no lint or typed-lint diagnostics in the touched files; jscpd - reports one 8-line block, the private folder's release in `GpgvKeyCheck`, - which follows `DesktopApplicationState`'s use of `ArtifactResourceScope`. -- `npx vitest run src/domain/desktop src/application/desktop src/desktop - src/process/TokenOwnedTermination.test.ts` on macOS and in the container, - and the CLI boundary tests `cliInputSchemaRequired`, `cliToolCoverage` and - `cliStartupImports`: passed. -- New tests: the sources parsers on Ubuntu 24.04's own `ubuntu.sources`, - Typora's flat entry and `[arch=… signed-by=…]` options, with apt's entry - positions; `apt-get indextargets` output from the containers for Typora's - `./`, pkgs.k8s.io's `/` and Ubuntu's suites, and the release file names it - gives; gpgv status for a release signed by two keys and checked with one - (exit 2), and bad, expired and revoked signatures; the OpenPGP keyring - splitter on GnuPG-made keys, OpenPGP.js rewrites of them with new-format - headers, and refused malformed packets; ASCII armor; DT_NEEDED, RUNPATH - over RPATH, a table repeating one name 60,000 times and one naming 513; - the library walk on `ldconfig -p` lines from the container, a normalized - `$ORIGIN/..` path and inherited RPATH; `apt-cache policy` for several - packages; the inventory with a fake query runner (binary, armored and - multi-key keyrings, a flat `/` suite, an ESM repository, gpgv and ldconfig - missing, no key verifying, an archive package not walked, a PPA library - package set aside); with real gpgv, the two-signature release and a - two-key keyring; a keyring folder whose removal fails keeping its owner, - and the capture's failure keeping it; key retention within and over the - content budget and the per-file limit; the install decision (one source per - URI and suite, the release, the host's architecture, an `env`-wrapped - Electron launch) and its limitations; the renderers; the exported `_sqlite` - under python3 waiting out a 20 ms write lock and reporting a lasting one in - about 0.3 s; the export service writing a vendor bundle and refusing an - unverified key. On Linux, the library inventory maps the node binary's - libraries with the host's `ldconfig` and `dpkg-query`. -- Second review round: a deb822 stanza with 500 URIs and 500 suites parses - as one stanza and still resolves a target's pair (it made 250,000 entries - before); a library package only another component of the vendor entry - offers is kept; a vendor capture written without `architectures` and - `release` exports, its package named alone; the repository check and the - library walk each failing on a close are reported together with both - handles, which their leases then close. Each failed before its fix. The - desktop suites passed on macOS (222 tests, 14 skipped) and in the container - (235, 1 skipped). - -## Typora - -- The inventory, run as a normal user in the container, recorded the - repository from `/etc/apt/sources.list.d/typora.list` with release - `stable` and `/etc/apt/trusted.gpg.d/typora.gpg` (fingerprint - `4AC441BE68B4ADAB7439FBF9BA300B7755AFCFAE`) verified by gpgv against - `downloads.typora.io_linux_._InRelease`, 85 library packages all offered by - the Ubuntu archive, no missing or unpackaged libraries, in 2.2 s, and left - no temporary folder. With the key converted to an armored `typora.asc`, and - with it moved to `/usr/share/keyrings/typora.gpg` named by - `[signed-by=…]`, the same key was verified. With the key appended to a - legacy `/etc/apt/trusted.gpg` after Ubuntu's 2018 archive key, only - Typora's key was retained, byte for byte the original file - (`06bbbb36…`). -- With pkgs.k8s.io's flat `/` repository added - (`deb [signed-by=/etc/apt/keyrings/kubernetes-apt-keyring.gpg] - https://pkgs.k8s.io/core:/stable:/v1.30/deb/ /`) and kubectl installed, the - inventory matched policy's `https://pkgs.k8s.io/core:/stable:/v1.30/deb - Packages` to that entry (suite `/`, release `deb`, the codename, since its - Release has no Suite) and gpgv verified its key against - `pkgs.k8s.io_core:_stable:_v1.30_deb_InRelease`. -- apt in the container: `apt-get install -s --reinstall typora/stable` - selected 1.14.9-1 from `Typora:stable`, `kubectl/deb` selected kubectl from - pkgs.k8s.io, and an unknown release failed with `Release 'nosuch' for - 'typora' was not found`. Two deb822 sources for Typora's URI and suite with - different `Signed-By` keyrings, as agentenv would write duplicate - `AptSource`s, failed with `Conflicting values set for option Signed-By`. - `apt-get indextargets` counted deb822 stanzas from 1, a disabled one - included, and printed no Signed-By, which the sources entry still gives. -- A capture of Typora editing `~/Documents/trip.md` (launched with - `--no-sandbox`, which the container needs) retained the key under - `content/06bbbb36…`. The export wrote `envs/typora/apt-keys/typora.gpg` with - that digest, declared `AptSource(apt="https://downloads.typora.io/linux", - suite="./", components=[], key="apt-keys/typora.gpg")` and the 85 library - packages after `typora`, and listed the sandbox and the repository version - in its limitations. -- `python -m agentenv_protocol.computer._declare . typora_app.py Typora` with - agentenv-framework 0.9.1431 exited 0 and declared the source, the packages - and the launch; `agent-env run --dry-run` exited 0. -- agentenv's own resolver (`resolve_in_base.py` from 0.9.1431), run with the - bundle's packages and source in a fresh `ubuntu:24.04` container with - python3 added, wrote the key and a `Signed-By` source, fetched Typora's - InRelease, installed typora 1.14.9-1 with 125 packages, and `ldd` found - every library of `/usr/share/typora/Typora`. - -## Typora in an agentenv computer - -The bundle from a recorded capture (Typora editing `~/Documents/trip.md`) ran -unchanged with `agent-env run --keep --no-emulate` on local Docker -(agentenv-framework 0.9.1431, arm64): - -- The build fetched `https://downloads.typora.io/linux ./ InRelease` and - installed typora 1.14.9-1 from it with no signature warning; a control run - with an empty keyring failed with `NO_PUBKEY BA300B7755AFCFAE`, and with the - bundled key gpgv reported `VALIDSIG 4AC441BE68B4ADAB7439FBF9BA300B7755AFCFAE`. -- Of the 85 library packages, the computer base lacked `libasound2t64`, - `libnspr4` and `libnss3`, which the build added; `ldd` on Typora then found - every library. -- The app reached ready on its `typora` window. Launched without - `--no-sandbox` it exits 133 with Chromium's namespace error. -- Driven through the computer's input operations (a task and a table row - added, then saved), `data/get` read `Documents/trip.md` as 8 lines before and - 10 after; `data/reset` relaunched Typora and restored all 79 seeded files - byte for byte. - -## Limits of this verification - -- The agentenv computer run above used the bundle exported before the review - round: `Packages(apt=["typora", …])` and both architectures. The pinned - `typora/stable`, single-architecture bundle was checked with apt in the - container but not deployed. - -- The export's own `--no-sandbox` insertion was checked in tests; the real - capture already had it, since Typora does not start in the container - without it. -- Library packages were mapped on Ubuntu 24.04 only. diff --git a/docs/specs/desktop-app-environments/xml-text-checks/plan.md b/docs/specs/desktop-app-environments/xml-text-checks/plan.md deleted file mode 100644 index 55f48fac32..0000000000 --- a/docs/specs/desktop-app-environments/xml-text-checks/plan.md +++ /dev/null @@ -1,29 +0,0 @@ -# Plan - -1. Parser: `parseXmlDocument` in `src/domain/xmlDocument.ts` gains the - DOCTYPE policy `external`, which refuses a DOCTYPE whose text holds a `[` - outside its quoted literals with the reason `internal-subset`, and - `declaredDocumentType` reads the DOM's name and identifiers, unquoted, the - public one normalized. saxes and xmldom read no DTD and already refuse any - entity but XML's five. -2. State view: `detectStateFormat` and `xmlView` in `stateFormats.ts` use the - `external` policy, and the view adds `doctype` when one is declared. One - predicate, XML whitespace, decides both whether text is formatting and - whether an element is mixed content. -3. Exported module: `_expat` in `appExportPythonXml.ts` turns parameter entity - parsing off, refuses an internal subset, an external entity and a skipped - entity, and passes the declaration to the reader; the namespace pass checks - start tags through a default handler; `_XmlReader` tracks per element - whether it holds text other than XML whitespace. -4. Checks: `text_equals` and `text_contains` in the schema, `textVerdict` - with `isXmlElement` and `elementText` in `appTaskChecks.ts`, and - `_whole_text` in the verifier's evaluator, in the same order of failures; - the export's refusal of a pointer into text covers them. -5. Draft: `wholeTextSuggestions` in `appTaskDraftText.ts`, and the archive's - suggestions in `appTaskDraft.ts` generalized to a check tree, an archive's - entries or an XML file's root, over the keyed diff `diffNamedMembers`; - `isTimestamp` also reads `asctime`'s form. -6. Docs and tests: a synthetic AbiWord save and a Writer `content.xml` split - into runs, read alike by both readers and checked alike by both - evaluators; the DOCTYPE cases each parser accepts and refuses; the shared - check cases. diff --git a/docs/specs/desktop-app-environments/xml-text-checks/spec.md b/docs/specs/desktop-app-environments/xml-text-checks/spec.md deleted file mode 100644 index 34cfdc5996..0000000000 --- a/docs/specs/desktop-app-environments/xml-text-checks/spec.md +++ /dev/null @@ -1,120 +0,0 @@ -# XML with a DOCTYPE, and whole-text checks - -## Outcome - -A document saved as XML that begins with a DOCTYPE naming its DTD, first -AbiWord's `.abw`, is read as XML rather than text, so a task can check what -the user wrote in it. A check can compare an element's whole text, so it holds -however an app splits a paragraph into runs as it saves: AbiWord's `c` -elements, Writer's `text:span`. Both evaluators, REA's and the exported -verifier's, agree. - -## Requirements - -- DOCTYPE: one with a name and, optionally, a `PUBLIC` or `SYSTEM` external - identifier is read as XML by both readers. The DTD it names is never fetched - or read. One with an internal subset (`[ … ]`), even an empty one, is - refused, so a document can declare no entity, and a reference to any entity - but XML's five (`amp`, `lt`, `gt`, `apos`, `quot`) is refused, in content - or in an attribute value, though the DTD a DOCTYPE names might declare it. - A refused document is no XML view, so the file reads as text, as a malformed - one does, in both readers. -- View: the element tree is the one the document has without its DOCTYPE, - within REA's node and depth limits; the declaration is no node. The view - records it beside `root` as - `doctype: {name, public_id, system_id}`, an identifier `null` when the - DOCTYPE gives none, the public one normalized as XML matches it: each run - of spaces and line breaks one space, the ends trimmed. The system one keeps - its spaces, each line ending a line feed as XML reads the document, which - the exported module does itself since `expat` passes the literal as - written. A document without a DOCTYPE has no `doctype`. -- Exported module: `expat` with parameter entity parsing off, and handlers - that refuse an internal subset, an external entity and a skipped entity. The - pass with namespace processing also checks each start tag for a reference - to an undeclared entity, which `expat` drops from an attribute value without - calling a handler when a DOCTYPE names a DTD. -- Whitespace in the view: whitespace-only text between child elements is - formatting, and dropped, only in an element that holds no other text, - outside `xml:space="preserve"`; in mixed content, an element holding text - beside its children, it is kept, so the space between two runs is part of - the text. Whitespace is XML's: space, tab, carriage return and line feed. A - no-break space and other Unicode spaces are text, in both readers alike. -- Checks: `text_equals` and `text_contains`, - `{id, kind, file, pointer, value, normalize_whitespace?}`. The pointer, with - selectors as for `value_equals`, names an element of an XML view, in a file - or an archive entry's `view`, or a text node or attribute value in one. An - element's text is XPath's `string()` of what the view keeps: every text node - in it and its descendants, CDATA included, in document order; a text node's - or an attribute's is its value. `text_equals` passes when that text equals - `value`, `text_contains` when it holds `value`, exactly, case and all. - `normalize_whitespace: true` collapses each run of XML whitespace in both - the text and `value` to one space and trims their ends before comparing, as - `normalize-space()` does. -- Failures, worded alike in both evaluators: an absent file; a file of another - format; a pointer into an archive outside an entry's `view`, or into an - entry of another format; a value that is neither an element, a text node - (a string among an element's `children`) nor an attribute's value (one among - its `attributes`), so an element's `name` and the `doctype`'s fields fail; - and, as undecided, in a view that leaves something out, either check of an - element, even one whose kept text holds the value, since the cut may have - dropped text from between the runs it kept; a pointer naming nothing; or a - selector searching an array such a view may cut. A text node or an - attribute's value is whole, so it is decided on a truncated view. -- Refusals: the task parser refuses the empty pointer, a pointer not starting - with `/`, an empty `text_contains` value or one that is only whitespace - with `normalize_whitespace`, and a value that looks like a date and time, - in ISO 8601 or C's `asctime` form (`Www Mmm dd hh:mm:ss yyyy`, as AbiWord - stamps a save); the export refuses a text check into a file read as text. -- Draft: an XML file is drafted as an archive's entries are, from the keyed - diff that names members by selector: never through an element by position, - an element added or removed whole checked once, and no check of - whitespace-only text between elements. In XML, each element holding a text - node that the diff lists with more than whitespace in it, at either end of a - changed value, and the nearest ancestor both ends hold of each element the - diff lists added or removed whole with such text anywhere in it, gets - `text_equals` with its final text, ahead of the other checks, so a run - added or removed with its words marks its paragraph. That ancestor is not - the document's root unless the root holds text of its own. The check goes - up from an element in mixed content (its parent holds text beside it, the - root included) to the nearest that is not, then from one named by its tag - or position alone to the nearest ancestor below the root named by an - attribute, as AbiWord's `p` by `xid`, so it names a paragraph rather than a - run a later save may split or merge. An element passed on the way that an - identifier of its own (`id`, `xml:id`, `xid` or one ending in `:id`) names - goes ahead of that ancestor, the outermost first, as an SVG `text` by its - `id` in a layer named by its label, unless an identifier names the ancestor - too, as the `text` above a `tspan` with an `id` of its own; one that only - another attribute names, such as `xml:space`, goes after it, for when the - ancestor cannot take the check, as when its text is too long. Either - attribute holds the same value at both ends and names the element alone - among its siblings at each. The check is kept when that element is the - outermost such, at both ends, named without positions, held whole by the - final view, its text changed, at most 2,000 characters and no timestamp. - Where none can take it, an element added whole, named without positions, - gets `text_equals` with its own text instead of a check that it is there, - as a new paragraph in a section too long to check. The text nodes and runs - inside a checked element, added and removed ones included, get no other - check, but a changed name or attribute of an element inside it that both - ends hold, such as a link's `href`, keeps its own, and so does an element - added or removed there whose text is only whitespace, such as an image or a - line break, which the text check never reads. - -## Non-goals - -- No DTD processing: no default attributes, entities, validation or catalog - lookup, from an internal subset or an external DTD. -- No characters from elements that stand for them, such as Writer's `text:s`, - `text:tab` and `text:line-break`, which are elements rather than text. -- No space between runs in an element that holds no text of its own outside - `xml:space="preserve"`: a paragraph made only of runs separated by a bare - space reads without it, since nothing tells that space from formatting. -- No regular expressions, case folding or Unicode normalization in text - checks. -- No rule for save bookkeeping other than timestamps: a counter an app bumps - on save, such as AbiWord's `history` `version`, `edit-time` and - `last-saved`, is still suggested, by name, for the author to drop, since a - number that went up is as often the user's edit. -- No paragraph for the changed text of a run named by an attribute of its - own, such as a run among others of different formatting, in a paragraph - holding no text of its own: its check names that run. A run added or - removed whole is checked at its paragraph. diff --git a/docs/specs/desktop-app-environments/xml-text-checks/verification.md b/docs/specs/desktop-app-environments/xml-text-checks/verification.md deleted file mode 100644 index 4dd78eadcf..0000000000 --- a/docs/specs/desktop-app-environments/xml-text-checks/verification.md +++ /dev/null @@ -1,167 +0,0 @@ -# Verification - -Run on 2026-11-05 on top of the namespaced XML views branch, on macOS with -Node v22.23.1 and Python 3.11.14 (expat 2.7.4). - -## Gates - -- `npm run typecheck`, `format:check`, `build:cached` then `knip`, `jscpd`, - `docs:check`, `docs:build`, `verify:test-discovery`, - `verify:architecture-guards` and `verify:module-boundaries`: passed. - `lint` and `lint:typed` on the touched source and test files: no - diagnostics; jscpd lists no clone in a touched file. -- `npx vitest run src/domain/desktop src/application/desktop src/desktop - src/domain/xmlDocument.test.ts` with the eight `tests/boundary/providers/desktop*` - files and the CLI boundary tests `cliStartupImports`, - `desktopApplicationCli`, `cliInputSchemaRequired` and `cliToolCoverage`: - 492 passed and 18 skipped (Linux-only cases). -- The parity files `desktopXmlTextPython`, `desktopXmlPython`, - `desktopTaskPython`, `desktopZipPython` and `desktopExportPython`: 34 passed - under each of Python 3.9.6 (expat 2.2.8), 3.10, 3.11, 3.12, 3.13 and 3.14. - -## Tests - -Each new test fails on the code before this change, run from an export of -that commit with only the new tests, fixtures and test support added: 31 -failed and the 112 tests already there passed. - -- AbiWord, in `desktopXmlTextPython.test.ts`: a synthetic `.abw` in the form - AbiWord 3.0 saves, with its AWML DOCTYPE, before and after the meeting time - changed to `3:30`, which the edit split into `c` runs. Both readers give the - same `xml` view with the same `doctype`; before this change it was text. - Both evaluators give the same results and descriptions: `text_equals` and - `text_contains` on `[name=p][@xid=3]` fail before the edit and pass after - it, while `value_equals` on its `children/0` fails after it too. -- Writer runs: a Writer `content.xml` derived from the real 24.2 save, its body - paragraph split into `T1` spans with a bare space between two of them, - zipped into an `.odt`. Both readers give the same view, the space kept as - mixed content; `text_equals`, `text_contains` with `normalize_whitespace` - and a reflowed `text_equals` fail before and pass after in both evaluators, - and `children/0` does not pass. -- DOCTYPE: built documents both readers read alike (a name only, `SYSTEM` - with `[` in its literal, `PUBLIC` with whitespace to normalize, empty - literals, a prefixed name, a name that differs from the root's) and refuse - alike (an empty internal subset, entity declarations with and without a - reference, an external general entity, a parameter entity, an undeclared - entity in content and in an attribute value with an external DTD, a - `PUBLIC` without a system literal, an illegal public identifier character, - a DOCTYPE after the root, two DOCTYPEs). A DTD written to disk and named by - its `file:` URL is not read: its entity stays undeclared and its default - attribute absent, in both readers. -- Whitespace: mixed content keeps the space between runs and element content - drops formatting, in both readers; a no-break space, U+0085 and U+FEFF - between elements are kept as text in both. Before, both dropped the - no-break space, REA also U+FEFF and the exported module U+0085, so the two - disagreed on those. -- Shared check cases both evaluators run: the whole text of a split - paragraph, with nested elements, empty, a text node, an attribute value, - exact and collapsed, equal and contained; an absent file, JSON and text - files, a non-element value, a selector matching nothing, an element of a - truncated view and a selector over it (undecided) beside a text node there - (decided), an archive's XML entry, its JSON entry, its binary entry, a - pointer to an entry's name, and a truncated entry. -- Parser: the `external` policy reads a DOCTYPE without an internal subset and - refuses one with it, `]` in a literal included, and `declaredDocumentType` - reports the identifiers unquoted, the public one normalized. -- Task file: the empty pointer, a pointer without `/`, an empty or - whitespace-only `text_contains` value, a time-like value and a non-boolean - `normalize_whitespace` are refused; the export refuses a text check into a - text file. -- Draft: an element's whole text by selector in an SVG, in an archive's - namespaced XML and in the AbiWord note, with nothing suggested inside the - paragraph, and no text check where only whitespace text changed; through - the application, a capture whose `.odt` paragraph an edit split into runs - drafts `text_equals` on it, and the export keeps a task with it, failing on - the seed, while `value_equals` on its first run fails at the end. - -## Review fixes - -Run on 2026-11-05 with the same toolchain. Each fix has tests that fail on the -reviewed commit, run from an export of it with only the changed tests and -fixtures added (8 failed, 64 passed), and pass after it. The gates above pass -again: lint and typed lint report nothing in the touched files, and the -desktop set gives 497 passed and 18 skipped, the parity files 34 under each -of Python 3.9 to 3.14. - -- A drafted text check names the paragraph, not a run. A changed value is read - at both ends, so text an app wraps in a run (`

old

` becoming - `

new

`) still marks its paragraph; the check goes up from an - element in mixed content, and from one named by its tag or position alone - to the nearest ancestor named by an attribute, as AbiWord's `p` by `xid`. Edits - that replace text with a run, change the text of a paragraph's only run, or - of a run among the paragraph's own text all draft `text_equals` on - `[name=p][@xid=6]`, which passes on the edited save and on one splitting the - text into other runs; in an archive, text turned into two spans drafts the - `text:p`. A link whose label and `href` both change drafts the paragraph's - text and keeps `value_equals` on the new `href`. -- Text checks read only an element, a text node or an attribute's value: an - element's `name` and the `doctype`'s fields fail in both evaluators, in a - file or an archive entry, while an attribute's value in an entry passes. -- The tests of text checks assert outcomes and the facts in a description (the - pointer, the text found, the value compared) rather than its wording. - Rewording the descriptions in both evaluators passes them; showing the value - uncollapsed fails them. -- The draft leaves out times in C's `asctime` form, as AbiWord stamps - `abiword.date_last_changed`, which the task parser also refuses, and drafts - an XML file as an archive's entries are: by selector, never through an - element by position, and without whitespace text between elements. For the - AbiWord note it suggests the paragraph's text first and no save time; - `history`'s `version`, `edit-time` and `last-saved` remain, named. - -## Second review fixes - -Run on 2026-11-05 with the same toolchain. The new draft tests fail on the -reviewed commit, run with only the changed test file (6 failed, 23 passed), -and pass after it. `npm run typecheck`, `docs:check`, and lint and format on -the touched files pass; the desktop set (`src/domain/desktop`, -`src/domain/xmlDocument.test.ts` and the `tests/boundary/providers/desktop*` -files) gives 329 passed, and `src/application/desktop` with `src/desktop` -141 passed and 18 skipped. The drafts for the Inkscape, AbiWord, Writer and -FreeCAD fixtures are the same as on the reviewed commit. - -- A run added or removed whole marks its paragraph, the nearest ancestor both - ends hold, by the text anywhere in it. `Meeting at ` gaining - `3:30` drafts `text_equals` `Meeting at 3:30` on `[name=p][@xid=6]` - and no check that the run is there: a save splitting the text into other - runs passes it and `13:30` in the run fails it. So does a bold run added to - a paragraph made only of runs, though its `props` name it. Removing a run - drafts the paragraph's remaining text instead of the run's absence. - `

Hello

` gaining ` world`, or ` world` in a `b` inside - the span, drafts `Hello world` on the paragraph, in a body and as the - document's root, which `WRONG` in the span fails. -- A new paragraph `p[@xid=7]` drafts its section's text where the section is - short enough to check, and its own text where it is not, instead of a check - that it is there; other words in it and the seed fail both. -- An element the diff names by its tag alone, and an identifier of its own - names, takes the check ahead of the ancestor named by another attribute: an - SVG headline, the only `text` in a layer, drafts `text_equals` on - `[name=text][@id=headline]` rather than the layer, the `text`'s `id` chosen - over its `tspan`'s, and Inkscape's own save keeps its check on the - `text`, which the diff already names by its `id`. Another attribute names - it only where the layer cannot take the check: with only `xml:space`, the - check stays on a short layer, and on the `text` by `xml:space` past 2,000 - characters, where it had fallen back to `value_equals` on the `tspan`'s - first text node. A save splitting the headline across two `tspan`s passes - it and the old headline fails it. When the edit also changed the `id`, no - text check is drafted. - -## Third review fixes - -Run on 2026-11-06 with the same toolchain. Each new case fails on the -reviewed commit and passes after it. The desktop set gives 873 passed, with -only `desktopExportSqliteMetadata.test.ts` failing, as it does on `main` in -this environment; the XML parity files give 16 passed under each of Python 3.9 -to 3.14. The drafts for the Inkscape, AbiWord, Writer and FreeCAD fixtures, -as files and as archive entries, are the same as on the reviewed commit. - -- A paragraph's text check no longer stands in for an element holding no text - that an edit adds or removes in it. In an archive, `Hello` becoming - `Hello there` with a `draw:frame` holding an image drafts the paragraph's - text and the frame's presence, and the frame removed drafts its absence; in - an AbiWord paragraph, an `image` added or a `br` removed beside the text - edit does the same. A save with the new text alone fails the presence or - absence check, and a run holding text added in the same edit still gets no - check of its own. -- The exported module reports a DOCTYPE's system identifier with each line - ending a line feed, as REA's parser does: `"x\r\ny\rz\n"` reads as - `x\ny\nz\n` in both, where `expat` had passed it as written. diff --git a/docs/specs/documentation/organization/plan.md b/docs/specs/documentation/organization/plan.md deleted file mode 100644 index 9b886a5b4d..0000000000 --- a/docs/specs/documentation/organization/plan.md +++ /dev/null @@ -1,43 +0,0 @@ -# Implementation plan - -## Layout and ownership - -Keep `docs/index.md` as the website landing page. Group authored documents under -`getting-started/`, `guides//`, `providers/`, `reference/`, -`development/` and `migrations/`. Keep the architecture map under -`architecture/`. Add a linked directory describing every category and its files. - -Leave `assets/`, `public/`, `verification/`, `releases/`, -`error-contract.schema.json` and `user-visible-errors.csv` at their owned paths. -The schema generator and catalog/evidence writers retain their current contracts. -No root document is converted into a feature specification merely to fit a folder. - -## Link and route contracts - -Preserve moved basenames. Convert local Markdown links using each document's old -and new location, including links to assets and generated references. Update -literal physical paths in documentation checks, release tooling and tests. -VitePress rewrites map categorized Markdown sources to their original root route, -so existing public guide links and anchors remain available. Site navigation -continues using public routes; edit links use the actual source path. - -Keep the independent native/Pascal work in PR #2400 mergeable by limiting changes -to required links in its moved guide. The EVM guide follows the same rule. - -## Verification - -Run documentation-fact checks and the affected README, release and filesystem -boundary tests. Build the complete VitePress site with dead-link checks enabled, -then compare emitted HTML routes with the pre-migration guide inventory. Inspect -the diff for unintended text rewrites and retained generated ownership. Run the -repository static checks before requesting review. - -Keep a reproducible built-HTML verifier with an independent 58-route baseline, -including the new upstream signal guide. Verify physical edit targets, local -published files/images and fragment IDs rather than treating a successful build -as sufficient link verification. Normalize references to docs/public at the -renderer boundary, where VitePress publishes them at the site root. Preserve a -legacy managed/native fragment alias while retaining the existing heading. -Run this verification in documentation CI and the manual documentation build. -Changes to the verifier itself must select the documentation lane; cover this -using the actual CI planner against an isolated Git fixture. diff --git a/docs/specs/documentation/organization/spec.md b/docs/specs/documentation/organization/spec.md deleted file mode 100644 index 58059d6679..0000000000 --- a/docs/specs/documentation/organization/spec.md +++ /dev/null @@ -1,38 +0,0 @@ -# Documentation organization - -## Problem and outcome - -The authored documentation root mixes user workflows, provider setup, contracts, -development instructions and release migrations. Several existing guides are -missing from site navigation. A contributor needs one documented destination for -each kind of document without breaking reader links or automated path consumers. - -Tracking issue: . - -## Requirements - -1. Categorize every existing authored guide while preserving its basename, - substantive content and heading anchors. -2. Preserve existing public guide URLs; update physical repository links and - tests, release instructions and documentation-fact readers together. -3. Expose every existing guide through a documentation directory and categorized - site navigation. -4. Specify one feature/domain per `docs/specs///`, with `spec.md`, - exactly one `plan.md` and `tasks.md`. Broad specification roadmaps only list - child specifications, order and dependencies. Architectural decisions use - individual Michael Nygard ADRs under `docs/adr//.md`. -5. Preserve machine-owned catalog, evidence, schema and release-manifest paths; - explain their owners and regeneration commands separately from authored guides. - -## Acceptance - -- Every pre-existing authored Markdown guide has a categorized destination. -- All local Markdown file references resolve after migration. -- A production VitePress build emits all pre-existing guide routes. -- Documentation facts and relevant physical-path consumer tests pass. -- The organization has one implementation plan and incremental task list. - -## Out of scope - -Provider integration, runtime behavior, analysis contracts, new language support, -rewriting guide claims, deployment and generated-output ownership changes. diff --git a/docs/specs/documentation/organization/tasks.md b/docs/specs/documentation/organization/tasks.md deleted file mode 100644 index f071866bd9..0000000000 --- a/docs/specs/documentation/organization/tasks.md +++ /dev/null @@ -1,13 +0,0 @@ -# Tasks - -- [x] Inspect documentation owners, navigation and path consumers; publish #2401. -- [x] Define this feature specification and its single implementation plan. -- [x] Move existing authored documents into their categorized destinations. -- [x] Update local links and physical-path consumers; preserve public routes. -- [x] Add the documentation directory and canonical authoring conventions. -- [x] Run documentation checks, path-consumer tests, site build and static checks. -- [x] Validate the merged upstream signal guide and all 57 published routes. -- [x] Add built-HTML route/edit/file/anchor regression verification. -- [x] Require the published-page verification in documentation CI and manual builds. -- [x] Resolve and validate the doubled catalog base URL and legacy managed anchor. -- [x] Prepare the signed conflict-resolution update for the existing PR. diff --git a/docs/specs/documentation/organization/verification.md b/docs/specs/documentation/organization/verification.md deleted file mode 100644 index ea7cd1d6fc..0000000000 --- a/docs/specs/documentation/organization/verification.md +++ /dev/null @@ -1,32 +0,0 @@ -# Verification after upstream integration - -Integrated upstream c462a4ebd, preserving its new signal-recording guide, managed -summary documentation, current translations and unknown-head pagination contract. - -- Documentation facts and README consistency checks passed. -- Production VitePress build passed. -- Independent built-HTML verification passed for 57 stable public routes, - 56 physical source-edit links and 507 distinct internal file/anchor targets. -- The new regression caught a doubled catalog base path and a missing historical - managed/native fragment. Both were corrected without weakening assertions. -- All six static tasks and architecture guards passed. -- 167 relevant catalog, release, documentation, signal-MCP, target-framing, - managed-summary, Worker-URL CLI and CI-planner regression tests passed across - ten files. CLI runs need process-table access for actual ownership/cleanup - verification; restricted execution failed with spawn EPERM, while the normal - host run passed without changing timeouts or assertions. -- After the subsequent upstream advance, 14 tests across unknown-head pagination, - workflow replay and target-content framing passed. Static checks, documentation - facts and all 57 published routes passed again against that base. -- Documentation CI and the manual build require the built-page verifier. - An actual CI-planner regression ensures edits to the verifier select that lane. - -The renderer treats physical docs/public references as site-root assets. -The managed guide retains its original heading and an explicit historical fragment -alias. External HTTP targets were not fetched; this verification concerns actual -local production HTML and source files. - -The HTTP/3 lab was added to the documentation directory, navigation, and the -independent route baseline. The built-HTML verifier passed for 58 stable routes, -76 HTML pages, 74 physical edit links, and 627 distinct local targets or anchors. -The documentation and translated README consistency checks also passed. diff --git a/docs/specs/evm/producer-limits/plan.md b/docs/specs/evm/producer-limits/plan.md deleted file mode 100644 index a28a731602..0000000000 --- a/docs/specs/evm/producer-limits/plan.md +++ /dev/null @@ -1,6 +0,0 @@ -# Plan - -1. Give EVM defaults and per-call policy one domain owner using the shared producer schema. -2. Resolve the accepted policy before resource selection and carry byte limits to the worker request; retain tighter inherited soft and hard bounds. -3. Preserve exact budgets through read/reply/diagnostic/resource recovery, CLI and Evidence. Replace the failure owner's positional argument list with a typed context. -4. Verify policy recovery and existing malformed/cancellation/cleanup behavior with focused checks. diff --git a/docs/specs/evm/producer-limits/spec.md b/docs/specs/evm/producer-limits/spec.md deleted file mode 100644 index c7b4f4a954..0000000000 --- a/docs/specs/evm/producer-limits/spec.md +++ /dev/null @@ -1,7 +0,0 @@ -# Per-call EVM producer budgets - -An analyst can raise or lower carrier, reply, diagnostic, address-space, file-output and CPU budgets without changing the selected artifact or restarting REA. Defaults stay 4 MiB carrier, 16 MiB reply/file, 1 MiB diagnostics, 3 GiB address space and 30 CPU seconds. `timeout_ms` remains the separate worker deadline. - -Use the shared typed `producer_limits` contract, advertising only fields enforced by EVM. If `file_bytes` is omitted, it follows the selected `output_bytes`; an explicit file budget stays independent. Linux soft/hard limits retain the tighter inherited value, and failures distinguish configured from unknown effective limits and signal causes. Resource guidance identifies the exhausted field, its selected value and whether inherited restrictions can prevent repair. The 256 MiB worker heap stays explicit and independent. - -Preserve carrier/decoded identities, metadata, target-free offline authority, cancellation, final cleanup and partial facts. Verify same-target recovery with a small selected allowance and narrower inherited-limit controls; report unavailable real Linux coverage. diff --git a/docs/specs/evm/producer-limits/tasks.md b/docs/specs/evm/producer-limits/tasks.md deleted file mode 100644 index 90b500a8c8..0000000000 --- a/docs/specs/evm/producer-limits/tasks.md +++ /dev/null @@ -1,6 +0,0 @@ -# Tasks - -- [x] Declare defaults and exact per-call policy. -- [x] Wire parent, worker and inherited resource enforcement. -- [x] Update exact recovery, CLI and Evidence. -- [x] Run focused regressions and report platform gaps. diff --git a/docs/specs/firmware/android-boot-image/plan.md b/docs/specs/firmware/android-boot-image/plan.md deleted file mode 100644 index eae12f681f..0000000000 --- a/docs/specs/firmware/android-boot-image/plan.md +++ /dev/null @@ -1,55 +0,0 @@ -# Implementation plan - -One format-aware parser normalizes the header, vendor ramdisk table, and AVB -footer. The artifact reader consumes that result. Registration follows the -uImage reader. Requirements are numbered in [spec.md](spec.md). - -## Boundary and contract - -1. Keep parsing in `src/artifacts/AndroidBootImageFormat.ts`, using shared - `Result`, `ParseFailureError`, and bounded `BinaryReader` primitives. - Keep magic recognition in `src/domain/androidBootImageFormat.ts`. Export - `parseAndroidBootHeader`, `parseVendorRamdiskTable`, `inspectAvbFooter`, - and `compressionFromPrefix` from the parser. Preserve parser failure kinds - through the shared artifact failure owner. -2. Add `AndroidBootImageArtifactReader` with format `android-boot-image`. It - probes at most 4096 header bytes, reads a 64-byte tail for the AVB check, - and streams member bytes on demand. Table admission uses the 4096-entry, - 4096-byte entry, and 1 MiB header caps before any table read. -3. Add `androidBootImageMetadataSchema` and - `androidBootImageEntryMetadataSchema` as `strictObject` members of the - kind-discriminated artifact metadata union. Catalog order does not select - the schema. -4. Add `android-boot-image` to `ARTIFACT_FORMATS` with the same container - flags as uImage: `roleContainer`, `retainClassifiedSource`, `extractable`, - and `absentInventory: "unavailable"`. `createArtifactReader`, inventory - classification, and extraction follow that registry. - `ArtifactGraphConstruction` and `BinaryTargetResolver` call - `hasAndroidBootImageMagic`. Add the kind to `ArtifactReader`, the artifact - graph, evidence subject, analysis snapshot, live target summary, and - binary target types. -5. Carry untrusted target-derived strings and the unknown boot, init_boot, or - recovery role in reader limitations. CLI and MCP preserve that Evidence. - Summary detail keeps the full Evidence and uses `inspect_analysis_view` - for paging. -6. Reuse `ArtifactFileSource`, ranged reads, chunk reads, and - `ArtifactResourceScope`. A failed close stays owned so a later close can - retry. Cancellation covers admission, paused inventory, buffered bytes, - and multi-chunk reads. - -## Validation - -Synthetic fixtures live in `tests/fixtures/androidBootImage.ts`: version 0, -version 2 with a DTB, versions 3 and 4 boot, version 4 vendor_boot with two -ramdisk table entries, and truncated and overlapping-range negatives. Cover -the parser, the reader, filesystem boundaries, CLI acceptance, and MCP -boundary output, including matching Evidence limitations and unsupported, -truncated, and malformed refusals. Use pinned AOSP generation and unpacking -with small inert component inputs as an independent byte oracle. State that -no device-dumped image was checked. - -## Effects and compatibility - -The reader only reads an admitted local file. It introduces no execution, -boot, decompression, digest check, or signature check. The new metadata kinds -are additive. Other artifact formats keep their existing schemas. diff --git a/docs/specs/firmware/android-boot-image/spec.md b/docs/specs/firmware/android-boot-image/spec.md deleted file mode 100644 index 39f1c64407..0000000000 --- a/docs/specs/firmware/android-boot-image/spec.md +++ /dev/null @@ -1,122 +0,0 @@ -# Android boot and vendor_boot images - -## Problem and outcome - -Android firmware inspection starts from `boot.img`, `init_boot.img`, -`recovery.img`, and `vendor_boot.img`. REA inventories APKs, devicetree blobs, -legacy uImage containers, and FIT images. It has no reader for an Android boot -image, so `inspect_artifact` and `extract_artifact` cannot expose the kernel, -ramdisk, or DTB stored in one. - -This feature adds a provider-less artifact reader for `ANDROID!` headers -(versions 0 through 4) and `VNDRBOOT` headers (versions 3 and 4). Header facts -and component children use the existing artifact inventory, extraction, CLI, -and MCP path. - -[Android boot and vendor_boot images](../../../android-boot-image.md) describes -the current behavior and limitations. This directory is the feature -specification, implementation plan, and task list. The guide does not replace -these files. - -## Requirements - -1. Classification uses the 8-byte magic `ANDROID!` or `VNDRBOOT`, independent - of filename. `hasAndroidBootImageMagic` is the only magic owner. Target - resolution and artifact-graph construction call it. -2. `src/artifacts/AndroidBootImageFormat.ts` decodes the header, the vendor - ramdisk table, and the AVB footer once. The reader consumes those facts. - Header multi-byte fields are little-endian. AVB footer sizes and versions - are big-endian. `u64`, `alignUp`, and range ends reject values that are not - safe integers. Parse failures return `Result` with shared `ParseFailureError` - facts. The artifact error owner preserves `malformed`, `truncated`, - `unsupported`, and `limit` through CLI/MCP projection and cleanup retry. -3. Boot versions 0 through 2 take a power-of-two page size from 2048 through 65536. The header occupies the first page. Kernel, ramdisk, and second - stage follow, each padded to the next page. Version 1 adds a recovery DTBO - at a page-aligned file offset. Version 2 adds a DTB after that offset. The - 32-byte header digest is recorded. Boot versions 3 and 4 use a fixed - 4096-byte page. Kernel and ramdisk follow the header page. Version 4 can - append a signature as a stored range with a size. -4. Vendor_boot versions 3 and 4 record kernel, ramdisk, and tags load - addresses, the board name, a 2048-byte command line, the vendor ramdisk, - and a DTB. The vendor page size is a power of two from 2048 through 65536. - Version 3 exposes one `vendor_ramdisk` child when that section is - non-empty. Version 4 exposes each ramdisk table entry as - `vendor_ramdisk/`, then the DTB, then bootconfig. The table itself - stays metadata. Each entry is at least the 108-byte v4 structure: size, - offset, type, a 32-byte name, and 16 board-id words. A larger `entry_size` - keeps those fields and leaves the trailing bytes undecoded. An empty name, - `.`, `..`, or a name containing `/` becomes `ramdisk-`. A repeated - name gains `-`, then further numeric suffixes until the path is - unique. -5. OS version and security patch level come from the packed `os_version` word - on a boot image. A month outside 1 through 12 leaves the patch level null - and keeps the raw word. Vendor_boot has no OS version field. Versions 0 - through 2 concatenate `cmdline` and `extra_cmdline` with no separator. - Versions 3 and 4 store one combined command line. Invalid UTF-8 leaves the - text null and keeps the raw field bytes as hex. Command line, board name, - and vendor ramdisk names are target-derived and untrusted. An `ANDROID!` - image covers boot, init_boot, and recovery; the header leaves that role - unknown. -6. Non-empty components become children: `kernel`, `ramdisk`, `second`, - `recovery_dtbo`, `dtb`, `vendor_ramdisk`, `vendor_ramdisk/`, - `bootconfig`, and `signature`. A prefix of gzip (`1f 8b`), an lz4 frame - (`04 22 4d 18`), legacy lz4 (`02 21 4c 18`), or zstd (`28 b5 2f fd`) - records that compression. Any other prefix leaves compression null. Null - means none of those magics matched. Stored bytes stay compressed. A kernel - that starts with ELF magic is classified as `elf` by the existing content - check. A `dtb` child stays a file for a later `inspect-devicetree` on the - extracted file. -7. When bytes follow the page-aligned image, the last 64 bytes are compared - with `AVBf`. A match records footer version, original image size, and - vbmeta offset and size. The footer and vbmeta stay header facts. A shorter - tail, or a tail that does not start with `AVBf`, is undecoded trailing - bytes. A vbmeta range that overlaps the header, a component, or the footer - is malformed. -8. The header probe is at most 4096 bytes. The reader admits at most 4096 - vendor ramdisk table entries, an entry size of at most 4096 bytes, and a - vendor `header_size` of at most 1 MiB. The per-version single-page boot - header bound is a format constraint. The vendor header allowance applies - only after the declared header extent fits the file. These checks run before - the table is read. Truncated declared structures return `truncated`; the page - padding after the last component may be absent. Unsupported - revisions return `unsupported_target`; malformed layouts return - `invalid_request`. Gaps inside a vendor ramdisk - section, and bytes between the sequential layout and a recovery DTBO, are - named in limitations. Member bytes stream on demand. -9. CLI and MCP return the same Evidence shape, including the untrusted-string - limitation and the unknown boot role. `androidBootImageMetadataSchema` and - `androidBootImageEntryMetadataSchema` are `strictObject` members of the - kind-discriminated artifact metadata union. Summary detail retains - Evidence. `inspect_analysis_view` pages it. -10. The reader reuses `ArtifactFileSource`, `readArtifactFileBytes`, - `readFileHandleChunks`, and `ArtifactResourceScope`. Close rethrows a - scope or source close failure and keeps the handle for retry. - Cancellation applies during admission, paused inventory, buffered reads, - and multi-chunk reads. A source change after prepare fails closed. - -## Acceptance - -Synthetic fixtures cover a version 0 image, a version 2 image with a DTB, -version 3 and version 4 boot images, and a version 4 vendor_boot image with -two ramdisk table entries, plus truncated and overlapping-range inputs. -Parser tests, reader tests, boundary tests, the CLI acceptance test, and the -MCP boundary test cover those images, compression magics, capacity limits, -cancellation, and cleanup retry. CLI and MCP tests assert the same Evidence -limitations. Temp directories use `createTestTempDirectory` without an -`afterEach` root removal. The MCP extraction cleanup removes the extraction -output root. - -Fixtures are synthetic headers and stored payloads. An independent offline -check also generates boot v0-v4 and vendor_boot v3-v4 images with pinned AOSP -`mkbootimg.py`, then compares REA ranges and digests with the known inputs and -official `unpack_bootimg.py` output. This feature includes no device-dumped -image. No signature check, AVB digest check, or payload decompressor runs. - -## Non-goals - -- Decompressing ramdisk, kernel, or bootconfig bytes. -- Checking the header digest, the version 4 boot signature, or the AVB footer. -- A separate `inspect_android_boot_image` tool. -- A Binwalk or Unblob adapter. -- Assigning boot, init_boot, or recovery from the header. -- Executing, booting, or modifying the image. diff --git a/docs/specs/firmware/android-boot-image/tasks.md b/docs/specs/firmware/android-boot-image/tasks.md deleted file mode 100644 index dc97e0333d..0000000000 --- a/docs/specs/firmware/android-boot-image/tasks.md +++ /dev/null @@ -1,30 +0,0 @@ -# Tasks - -Requirement numbers refer to [spec.md](spec.md). Verification names the test -that covers the step. - -- [x] Record this specification, [plan](plan.md), and task list for the - Android boot image reader. (Requirements 1-10) -- [x] Decode `ANDROID!` versions 0-4 and `VNDRBOOT` versions 3-4 in the artifact - parser, including safe integer ranges, packed `os_version`, UTF-8 - failure, vendor ramdisk names, and tagged parse errors. - (Requirements 1-5, 7-8; `src/artifacts/AndroidBootImageFormat.test.ts`) -- [x] Map non-empty components to children, record compression from the - leading magic, stream member bytes, and enforce probe and table caps - before the table read. (Requirements 6 and 8; - `src/artifacts/AndroidBootImageArtifactReader.test.ts`) -- [x] Register metadata schemas and the reader on the uImage inventory, - extraction, and target-resolution path. (Requirement 9; - `tests/acceptance/androidBootImageCli.test.ts`, - `src/application/binary/TargetFormatVocabularies.test.ts`) -- [x] Preserve untrusted-string and unknown-role limitations through CLI and - MCP Evidence. (Requirements 5 and 9; - `tests/acceptance/androidBootImageCli.test.ts`, - `tests/boundary/mcp/androidBootImageMcp.test.ts`) -- [x] Cover close retry, cancellation during admission and paused inventory, - cancel with buffered bytes, source change after prepare, and multi-chunk - cancel. (Requirement 10; - `src/artifacts/AndroidBootImageArtifactReader.boundaries.test.ts`) -- [x] Describe current behavior and the capacity bounds in - `docs/android-boot-image.md`, and link that guide from the documentation - directory, CLI guide, and firmware guide. (Acceptance) diff --git a/docs/specs/firmware/android-ota-payload/plan.md b/docs/specs/firmware/android-ota-payload/plan.md deleted file mode 100644 index a56d908257..0000000000 --- a/docs/specs/firmware/android-ota-payload/plan.md +++ /dev/null @@ -1,43 +0,0 @@ -# Implementation plan - -## Boundary and contract - -Follow the existing artifact readers. `src/domain/firmware/androidOtaPayload.ts` -owns CrAU header and `DeltaArchiveManifest` decode, recognition, reconstruction -and capacity ceilings. `src/domain/artifactFormatMetadata.ts` owns the -`android-ota-payload` and `android-ota-partition` result schemas. -`AndroidOtaPayloadArtifactReader` reads the admitted file through -`ArtifactFileSource`, inventories partitions from the manifest, and -reconstructs extractable images on `open()`. - -Recognition lives in `recognizeAndroidOtaPayload` and is applied in the -shared `ARTIFACT_FORMAT_RECOGNIZERS` table immediately after uImage, so -inventory classification and binary target resolution share one verdict. -A v1 (or other non-v2) header is refused like an ESP8266 image: nested -classification keeps a plain file; `open_binary` reports the unsupported -version. - -Field numbers are taken from AOSP `system/update_engine/update_metadata.proto` -(`chromeos_update_engine`). Unknown protobuf fields are skipped. The proto -is not vendored. - -## Incremental work and validation - -1. Define header, manifest, signature-count and reconstruction contracts with - synthesized CrAU fixtures. -2. Implement parse, recognition and REPLACE/ZERO/REPLACE_ZSTD reconstruction - with typed format, unsupported-version, capacity, unsupported-operation - and integrity failures. -3. Add the reader, format descriptor and byte classification. -4. Wire CLI/MCP through the existing inspect/extract artifact contracts. -5. Document the workflow and limits. - -## Effects and compatibility - -The inventory reads one caller-selected payload file. Nested zip members -named `payload.bin` classify by magic when the zip reader already surfaces -them; zip inventory does not recurse into partitions. The change adds no -target execution, injection, mutation, protection recovery, network access -or live device update, so no maintainer scope decision is required. -Existing format routing is unchanged; the new format id appears only for -CrAU v2 bytes. diff --git a/docs/specs/firmware/android-ota-payload/spec.md b/docs/specs/firmware/android-ota-payload/spec.md deleted file mode 100644 index f51ce18d3d..0000000000 --- a/docs/specs/firmware/android-ota-payload/spec.md +++ /dev/null @@ -1,49 +0,0 @@ -# Android OTA payload inspection - -This specification records an implementation increment and its original -problem statement. For current behavior and limitations, see -[Android OTA update payloads](../../../guides/firmware/android-ota-payload.md). - -## Problem and outcome - -REA has no reader for Android A/B OTA `payload.bin` files (update_engine, -magic `CrAU`). An analyst holding a payload cannot ask which partitions it -writes, what sizes and hashes the manifest declares, whether the payload is -full or delta, or which operations are present. Add a read-only inspector -that inventories the header and `DeltaArchiveManifest` and, when cheap, -reconstructs REPLACE/ZERO/REPLACE_ZSTD partition images. - -## Requirements - -- Recognize CrAU v2 from leading bytes under any file name. Report a - readable major version other than 2 as an unsupported-version refusal. -- Decode the v2 header and the manifest fields listed in the product guide: - block size, minor version, timestamps, partial update, security patch, - per-partition identities, operation counts, Virtual A/B groups and - apex_info. -- Count metadata and payload signature blobs without verifying them. -- Reconstruct a partition only when every operation is REPLACE, ZERO or - REPLACE_ZSTD, the new size is known and within the extract ceiling, and - needed blob extents are present. Bound REPLACE_ZSTD decode to destination - extent bytes, never above the extract ceiling, and refuse a partition - open when distinct operation blob bytes exceed the operation-data - budget. Verify the image against the declared hash when present. Other - operation types stay inventoried and refuse content reads. -- Keep a complete manifest inventory when the blob is truncated. Refuse - malformed magic, truncated headers or manifests, oversize counts, and - operation extents that overrun the blob, without inventing zeros. - -## Acceptance - -Synthesized fixtures cover a full payload with REPLACE and ZERO operations, -dynamic groups and apex_info; a delta payload with SOURCE_COPY and -BROTLI_BSDIFF; an unknown operation type; v1 refusal; truncated blob with -complete manifest; oversize manifest; malformed protobuf; and hash -match/mismatch. Reader, CLI and MCP tests use those fixtures. Nested zip -`payload.bin` members classify by magic. - -## Non-goals - -Signature verification, applying delta or compressed operations other than -REPLACE_ZSTD, reading `payload_properties.txt` or zip metadata, recursive -zip inventory of partitions, and device-side update_engine execution. diff --git a/docs/specs/firmware/android-ota-payload/tasks.md b/docs/specs/firmware/android-ota-payload/tasks.md deleted file mode 100644 index df97e4745b..0000000000 --- a/docs/specs/firmware/android-ota-payload/tasks.md +++ /dev/null @@ -1,11 +0,0 @@ -# Tasks - -- [x] Define the first-step scope, contract and limits. -- [x] Parse the CrAU v2 header and DeltaArchiveManifest with synthesized - fixtures and explicit limitations. -- [x] Reconstruct REPLACE, ZERO and REPLACE_ZSTD partitions with hash - verification; refuse other operation types. -- [x] Add the reader, format descriptor and byte classification. -- [x] Cover CLI inspect/extract and MCP open/inspect/extract on fixtures, - including v1 refusal and truncated-blob inventory. -- [x] Document the workflow, limits and verification scope. diff --git a/docs/specs/javascript/v8-cached-data/plan.md b/docs/specs/javascript/v8-cached-data/plan.md deleted file mode 100644 index 3b3bb2c17c..0000000000 --- a/docs/specs/javascript/v8-cached-data/plan.md +++ /dev/null @@ -1,10 +0,0 @@ -# Implementation plan - -1. Derive VM callable identity and intact option objects from existing semantic - owners after mutation indexing; retain unresolved spreads as unknown. -2. Retain proven cache reads and their parsed bases through the named worker - contract. Resolve only source-directory paths against admitted inventory. -3. Project declarations into explicit graph unknowns and compilation summaries, - preserving source ranges, unresolved paths and execution limitations. -4. Verify negative mutation/spread controls and public filesystem workflows; - document runtime qualification separately from static analysis. diff --git a/docs/specs/javascript/v8-cached-data/spec.md b/docs/specs/javascript/v8-cached-data/spec.md deleted file mode 100644 index 90d74ba9d5..0000000000 --- a/docs/specs/javascript/v8-cached-data/spec.md +++ /dev/null @@ -1,43 +0,0 @@ -# V8 cached-data compilation boundaries - -## Analyst question - -Which source-visible Node VM compilation sites declare or may receive cached -bytes, and which admitted artifact can be associated with those bytes? - -## Scope and authority - -Static application analysis recognizes member calls to `vm.Script` and -`vm.compileFunction` when the shared built-in callable owner establishes their -identity. Analysis reads admitted source and inventory only. It does not invoke -the target, validate V8 cache bytes, establish cache acceptance, or execute code. -Node separates compilation, cache rejection and subsequent execution; see the -[Node VM contract](https://nodejs.org/docs/latest-v24.x/api/vm.html). - -## Owning facts - -- Resolve complete callable identity after shared mutation facts settle. ESM - default/namespace imports and proven CommonJS bindings use the same owner. - Replaced methods do not establish VM authority. -- `cached_data_status` is `declared` for an explicit cachedData property, - `absent` for proven omission or a proven undefined cache value, and `unknown` for unresolved options or argument - spreads that can supply or shift the options position. Declaration does not - prove a valid runtime value or successful cache use. -- A proven `fs.readFileSync` or awaited `fs/promises.readFile` can identify a - cache path. Unawaited promises and unproven readers retain bounded source - expressions. A supplied string alone is not proof that a file was read. -- Preserve the parsed path base through the worker boundary. Only a proven - source-directory base permits an application inventory lookup. Relative - literal paths depend on the unknown target working directory; source paths - and unresolved expressions stay separate from resolved artifact identity. -- Graph cache boundaries remain explicit unknowns with source provenance. - Absent sites do not add cache-boundary uncertainty. Summary counts describe - declared compilations, never observed executions. - -## Compatibility and verification - -Existing source declarations and inventory remain available. Optional path-base -facts may be absent in historical analyses; omission does not prove a base. -Public application workflows verify worker serialization, summary and graph -projection with local files. No test that merely supplies cache-shaped bytes -establishes real V8 acceptance or target execution. diff --git a/docs/specs/javascript/v8-cached-data/tasks.md b/docs/specs/javascript/v8-cached-data/tasks.md deleted file mode 100644 index 5ce42c9495..0000000000 --- a/docs/specs/javascript/v8-cached-data/tasks.md +++ /dev/null @@ -1,10 +0,0 @@ -# Tasks - -- [x] Model declared, absent and unknown cached-data sites. -- [x] Reuse built-in callable and option-object ownership. -- [x] Retain synchronous and awaited promise read provenance and path bases. -- [x] Carry facts through worker serialization to summary and graph consumers. -- [x] Exercise malformed authority, argument spreads and unresolved paths. -- [x] Verify public filesystem application workflows and document limitations. - -Real V8 acceptance and execution remain outside this static feature's scope. diff --git a/docs/specs/native/android-elf-ident-note/plan.md b/docs/specs/native/android-elf-ident-note/plan.md deleted file mode 100644 index 5f6dd30141..0000000000 --- a/docs/specs/native/android-elf-ident-note/plan.md +++ /dev/null @@ -1,37 +0,0 @@ -# Implementation plan - -## Boundary and contract - -Extend `ELF_NOTE_TYPE_NAMES`, `androidNoteTypeName`, and `elfNotesSchema` in -`src/domain/native/elfNotes.ts` with `"android_ident"` and nullable -`android: { android_api, ndk_version, ndk_build_number }` on each note entry. - -Implement `scanAndroidIdentSlot` and `decodeAndroid` in -`src/native/elf/ElfNoteParser.ts`, invoked from `toEntry` alongside `decodeGnu` -and `decodeCore`. Cache the 128-byte fixed-slot scan per descriptor range under -`android:${byteOffset}:${length}` in `TextBudget.scans`, charge `scanned` once -per distinct range, and charge retained `ndk_version` and `ndk_build_number` -lengths to `TextBudget.used`. Update the `inspect_elf_notes` description in -`src/contracts/native/binaryDiagnosticsToolContracts.ts` and the owning guide -[ELF note tables](../../../elf-notes.md). - -## Incremental work and validation - -1. Extend `src/domain/native/elfNotes.ts` and add unit tests in - `src/domain/native/elfNotes.test.ts`. -2. Add `androidIdentNote` fixture support in `src/native/elf/ElfNotes.fixture.ts` - and implement `decodeAndroid` in `src/native/elf/ElfNoteParser.ts` with - endianness, malformed-slot degradation, and `TextBudget` accounting tests in - `src/native/elf/ElfNoteParser.test.ts`. -3. Add MCP boundary tests (`tests/boundary/mcp/elfNotesMcp.test.ts`) and - CLI/stdio-MCP parity acceptance tests (`tests/acceptance/elfNotesAndroid.test.ts`) - importing `BINARY_DIAGNOSTICS_TOOL_CONTRACTS`. -4. Update [ELF note tables](../../../elf-notes.md) and the feature specification - index; pass formatting, static, typed-lint, test, and documentation gates. - -## Effects and compatibility - -`inspect_elf_notes` / `inspect-elf-notes` entries gain additive `"android_ident"` -and nullable `android` fields while preserving existing `gnu`, `core`, and -raw `descriptor` provenance. No external tools, network calls, or target -execution are introduced. diff --git a/docs/specs/native/android-elf-ident-note/spec.md b/docs/specs/native/android-elf-ident-note/spec.md deleted file mode 100644 index c0a7d8428a..0000000000 --- a/docs/specs/native/android-elf-ident-note/spec.md +++ /dev/null @@ -1,52 +0,0 @@ -# Android `.note.android.ident` ELF note decoding - -## Problem and outcome - -Android NDK shared libraries and executables linked with Bionic `crtbegin_so.o` -or `crtbrand.S` embed an ELF note with `owner === "Android"` and `n_type === 1` -(`NT_ANDROID_TYPE_IDENT`) inside `.note.android.ident` (`SHT_NOTE` and/or -`PT_NOTE`). Legacy Android NDK (`< r14`) and unbranded platform builds store a -4-byte `uint32_t android_api` descriptor, while modern NDK (`r14+`) builds -store a 132-byte (or extended `>= 132`-byte) descriptor containing -`uint32_t android_api` (`0..4`), `char ndk_version[64]` (`4..68`), and -`char ndk_build_number[64]` (`68..132`). - -Previously, `inspect_elf_notes` / `inspect-elf-notes` mapped only `GNU` and -`CORE` note owners, leaving `Android` type `1` entries as `type_name: "unknown"` -with `descriptor.hex: null` for 132-byte notes (above the 64-byte inline hex -preview ceiling). Extend `inspect_elf_notes` to decode `NT_ANDROID_TYPE_IDENT` -into `type_name: "android_ident"` and a nullable `android` object across -32-/64-bit and little-/big-endian ELF targets without executing the image. - -## Requirements - -- Map `owner === "Android"` and `type === 1` to `type_name: "android_ident"`; - other `Android` note types remain `type_name: "unknown"` with `android: null`, - and non-`Android` owners keep `android: null`. -- Decode 4-byte `NT_ANDROID_TYPE_IDENT` descriptors in the ELF image's byte - order as `{ android_api, ndk_version: null, ndk_build_number: null }`. -- Decode `>= 132`-byte `NT_ANDROID_TYPE_IDENT` descriptors in the ELF image's - byte order when both 64-byte fixed slots (`4..68` and `68..132`) contain - printable ASCII (`0x20..0x7e`) terminated by `0x00` and padded solely with - `0x00` through the end of each 64-byte slot. -- Degrade truncated (`0..3` or `5..131` bytes), unterminated, control-byte, or - non-zero-padded `NT_ANDROID_TYPE_IDENT` descriptors to `android: null` while - preserving raw note header fields, descriptor SHA-256, and `<= 64`-byte hex - preview. -- Account for fixed-slot scanning (`128` bytes cached per descriptor slice in - `TextBudget.scans`) and retained `ndk_version` / `ndk_build_number` text in - `TextBudget.used` under the shared `max_file_bytes` ceiling. - -## Acceptance - -Domain, parser, MCP boundary, and CLI/stdio-MCP acceptance tests cover -little-endian ELF64 (`aarch64`, `x86_64`) and big-endian ELF32/ELF64 images -across 132-byte, 152-byte extended, and legacy 4-byte descriptors, unknown -`Android` note types, malformed/truncated/non-ASCII descriptors, and shared -`TextBudget` scan, scan-cache, and retained-string limits. - -## Out of scope - -Decoding other `NT_ANDROID_*` note types (such as `NT_ANDROID_TYPE_MEMTAG` or -`NT_ANDROID_TYPE_KUSER`), executing target binaries, or invoking external -disassemblers. diff --git a/docs/specs/native/android-elf-ident-note/tasks.md b/docs/specs/native/android-elf-ident-note/tasks.md deleted file mode 100644 index 1a98f43b5d..0000000000 --- a/docs/specs/native/android-elf-ident-note/tasks.md +++ /dev/null @@ -1,8 +0,0 @@ -# Tasks - -- [x] Define single-feature scope, contracts, and implementation plan (`spec.md`, `plan.md`). -- [x] Add `"android_ident"` type name mapping and nullable `android` schema on `elfNotesSchema` (`src/domain/native/elfNotes.ts`). -- [x] Implement endian-aware `decodeAndroid` with printable-ASCII / zero-padding validation and `TextBudget` scan/used accounting (`src/native/elf/ElfNoteParser.ts`). -- [x] Update `inspect_elf_notes` contract metadata (`src/contracts/native/binaryDiagnosticsToolContracts.ts`). -- [x] Add domain, parser, MCP boundary, and CLI/stdio-MCP acceptance tests (`elfNotes.test.ts`, `ElfNoteParser.test.ts`, `elfNotesMcp.test.ts`, `elfNotesAndroid.test.ts`). -- [x] Update `docs/elf-notes.md` and `docs/specs/README.md`; pass all verification gates. diff --git a/docs/specs/native/call-source-locations/plan.md b/docs/specs/native/call-source-locations/plan.md deleted file mode 100644 index 1c019948aa..0000000000 --- a/docs/specs/native/call-source-locations/plan.md +++ /dev/null @@ -1,39 +0,0 @@ -# Implementation plan - -## Boundary and contract - -Extend nativeCodeLocationSchema in src/domain/native/nativeCallObservation.ts. -Reuse that shape for events, breakpoint locations, backtraces and retained journal -events. Keep the field optional for older evidence and nullable for current LLDB -observations with unavailable metadata. Each inner facet can be independently -unavailable; avoid dropping a valid line number because a file path is absent. - -Read SBAddress.GetLineEntry once in the existing Python _location producer. A -valid SBFileSpec supplies its displayed path without filesystem access. Convert -zero line/column to null. An invalid entry returns null. Existing estimation and -serialization budget checks already traverse the location object recursively. - -## Incremental work and validation - -1. Define contracts and criteria before code; add failing producer tests. -2. Extend the canonical schema and _location producer. Update existing fake - address objects to implement the actual LLDB line-entry interface. -3. Extend provider/MCP boundary coverage and retained-journal coverage for the - additive field; preserve omission compatibility. -4. Extend the existing real macOS verifier with source-coordinate assertions - against its own Objective-C/C fixture built with debug information. -5. Update the native investigation guide; run Python tests, focused TypeScript - tests, repository checks and the real verifier if host authority permits. - -## Effects and compatibility - -The existing LLDB operation already owns its breakpoint callbacks and process -lifecycle. This adds a metadata read within that observation. It does not introduce -target execution or a new provider beyond existing behavior. No source file is -acquired from a path in debug information. Consumers of historical evidence retain -omission; consumers of new captures see either a partial/full object or null. - -## References - -- https://lldb.llvm.org/python_api/lldb.SBAddress.html -- https://lldb.llvm.org/python_api/lldb.SBLineEntry.html diff --git a/docs/specs/native/call-source-locations/spec.md b/docs/specs/native/call-source-locations/spec.md deleted file mode 100644 index b3e9debaef..0000000000 --- a/docs/specs/native/call-source-locations/spec.md +++ /dev/null @@ -1,36 +0,0 @@ -# Native call source coordinates - -Issue: https://github.com/morluto/rea/issues/2382 - -## Problem and outcome - -The existing bounded macOS LLDB call observation retains module, symbol and -addresses, but loses compiler-provided source coordinates. Retain line-entry -metadata at the same producer boundary for breakpoint locations, call entries -and caller frames. - -## Requirements - -- Add optional nullable source_location to the canonical native code location. - A present object contains nullable file_path, line and column. Positive line - and column values are one-based. Provider zero values mean unavailable. -- Preserve partial facts from a valid line entry. Invalid entries or entries - without any usable facet produce null. Historical captures may omit the field. -- Read only SBAddress line metadata; do not resolve paths, read source contents, - evaluate expressions or change the existing launch, stop or cleanup policy. -- The field establishes LLDB line-table attribution, not verified source bytes. -- Existing trace and breakpoint byte budgets include the new representation. - -## Acceptance - -Producer tests cover valid, invalid and partial entries, Unicode paths and absent -coordinates. Existing evidence without the field remains accepted. CLI/MCP and -partial retained-journal paths preserve the canonical field. The real native-call -verifier checks source coordinates for its owned debug build, including caller -frames and breakpoint locations, and reports actual host/provider coverage. - -## Out of scope - -New debugger adapters, interactive stepping, source breakpoints, source-file -association verification, source reads, Pascal/Delphi compatibility claims and -Java/Android/CLR runtime support. diff --git a/docs/specs/native/call-source-locations/tasks.md b/docs/specs/native/call-source-locations/tasks.md deleted file mode 100644 index ce193e6175..0000000000 --- a/docs/specs/native/call-source-locations/tasks.md +++ /dev/null @@ -1,14 +0,0 @@ -# Tasks - -The checked items below record work completed on an earlier revision. The -current revision's final caller-frame assertions, marker-derived line -expectations, timeout handling, and Unicode budget case remain source-reviewed -only; the full native-call verifier is incomplete. - -- [x] Define the single-feature scope, contract and implementation plan. -- [x] Reproduce lost source coordinates with producer regression tests. -- [x] Retain line-entry metadata in the producer and canonical schema. -- [x] Verify boundary/MCP propagation and historical omission. -- [x] Historical: verify real CLI/MCP call coordinates on an owned Free Pascal 3.2.2 program. -- [x] Historical: update documentation; pass Python, focused TypeScript, static and discovery checks. -- [ ] Complete the full native-call verifier after investigating #2397. diff --git a/docs/specs/native/call-source-locations/verification.md b/docs/specs/native/call-source-locations/verification.md deleted file mode 100644 index 0de6f2db1a..0000000000 --- a/docs/specs/native/call-source-locations/verification.md +++ /dev/null @@ -1,45 +0,0 @@ -# Historical verification - -The records below describe earlier revisions, before the final caller-frame -assertions, marker-derived line expectations, forced compiler timeout termination, -and large Unicode source-location budget coverage. They do not validate the -current revision. Those final changes were reviewed from source only; tests and -automated checks were not run at the user’s explicit request. - -Host: macOS ARM64. Compiler: caller-installed Free Pascal 3.2.2, Darwin AArch64. -Debugger: LLDB 2103.0.34.103 from Command Line Tools. - -- Python producer/budget/output tests: 10 passed. -- Focused native provider, retained-journal and MCP tests: 18 passed. -- Real Pascal CLI and stdio MCP: three expected calls, integer register values - 0/1/2, source path and positive line attribution, successful target exit. -- Repository static checks: six tasks and architecture guards passed. -- Test discovery: all 982 test files discovered exactly once. - -The complete native-call verifier did not pass. One run reported exited instead -of event-limit for capped overlapping breakpoints. Another reported unavailable -launch start identity in a later capped scenario. Investigation: -https://github.com/morluto/rea/issues/2397. These results have not yet been isolated -on unchanged upstream. The source-coordinate PR was draft at that historical checkpoint. - -The first real native scenario and CLI/MCP source-coordinate comparisons completed -before those broader failures. The Pascal lane verifies bounded native call -observation; it does not establish typed Pascal local values, source breakpoints, -interactive stepping, Delphi compatibility or a GDB provider. - -## Unmeasured costs and outstanding execution - -Repeated source paths expand event, caller-frame and breakpoint-location payloads. -`nativeCallObservation.test.ts` measures that growth as UTF-8 JSON bytes: three -copies of one location grow by three times the difference between the -`source_location` object and `null`. That byte delta is not a token count. -Equivalent before/after completed workflows have not been measured for agent tokens, -elapsed time, CPU time or peak process-family memory, for either cold or warm runs. -The first compiler probe is only `fpc -iV` with a 30s deadline. Darwin ownership-helper -compilation uses `REA_SWIFTC_COMPILE_TIMEOUT_MS`, default 120s, inside the later -180s `observe-native-calls` run. - -The current caller-frame equality checks, marker-derived source lines, forced -compiler timeout termination and Unicode source-path budget case remain unverified -by execution. Earlier Pascal CLI/MCP observations establish only the historical -coverage described above. diff --git a/docs/specs/native/dwarf-units/plan.md b/docs/specs/native/dwarf-units/plan.md deleted file mode 100644 index 0686cd6244..0000000000 --- a/docs/specs/native/dwarf-units/plan.md +++ /dev/null @@ -1,46 +0,0 @@ -# Implementation plan - -## Boundary and contract - -Define the report in `src/domain/native/dwarfUnits.ts`: artifact identity, -container `format`, byte order and architecture, `sections` with stored name, -file offset, stored size and `compression`, `omissions`, the requested `units` -page with per-attribute state and `issues`, `total_units` and `coverage`. -Schema refinements tie attribute state to value presence and require a reason -for `partial` coverage. Add the MCP contract in -`src/contracts/native/binaryDiagnosticsToolContracts.ts` and the CLI command in -`src/cli/binaryDiagnosticsCommands.ts`, registered in the existing binary -diagnostics group. - -Parse in `src/native/dwarf/`: `DwarfSections` locates and decompresses debug -sections through `BinaryContainer`, `DwarfAbbrev` decodes abbreviation tables -under a shared work budget, `DwarfReader` is the bounded cursor, -`DwarfUnitParser` frames units and reads the unit DIE, and `DwarfUnitsProvider` -assembles the report. `DwarfUnitsService` in `src/application/binaryDiagnostics/` -reads the selected path through the stable artifact read. - -Shared changes stay with their owners: `ElfCompressedSection.ts` and -`ElfSectionNameTable.ts` for section decoding, `MachoImage.ts` and -`BinaryContainer.ts` for an `on_disk` section fact so an unmapped Mach-O -`__DWARF` segment is read by file range, and `artifactOperationError.ts` for a -typed allowance failure. - -## Incremental work and validation - -1. Define the domain schema, limits, coverage states and MCP/CLI contracts. -2. Implement section location and decompression, abbreviation decoding, the - bounded reader and the unit parser with synthetic fixtures for each form, - version and failure path. -3. Wire the provider, service, composition, capability inventory and server - registration; add boundary, MCP and CLI acceptance tests. -4. Add `scripts/verify-dwarf-units.mjs` to compare compiled fixtures with - `llvm-dwarfdump`, and record the run. -5. Add the [DWARF compile units guide](../../../guides/native/dwarf-units.md), - CLI guide entry, README rows and skill guidance; run documentation checks. - -## Effects and compatibility - -The tool is additive and read-only over one local file. No provider, bridge or -external tool runs at inspection time, the target is never executed, and no -resources are retained. Existing readers keep their output; the `on_disk` -section fact is additive. diff --git a/docs/specs/native/dwarf-units/spec.md b/docs/specs/native/dwarf-units/spec.md deleted file mode 100644 index b4053644a3..0000000000 --- a/docs/specs/native/dwarf-units/spec.md +++ /dev/null @@ -1,66 +0,0 @@ -# DWARF compile-unit inspection - -## Problem and outcome - -Learning what a native binary was built from currently needs a deep provider or -GNU objdump through `inspect_with_objdump`, which returns `-W` text the caller -has to parse. Add `inspect_dwarf_units` / `inspect-dwarf-units`, a built-in -reader of DWARF 2 through 5 compile units in one selected local ELF, Mach-O or -PE image. It returns structured unit facts with no provider installed and never -executes the target. - -## Requirements - -- Read compile-unit headers and the unit-level DIE only. Each unit reports - version, unit type when the header has one, address size, `name`, - `comp_dir`, `producer`, language code and DWARF 5 language name, `dwo_name` - (`DW_AT_dwo_name` or `DW_AT_GNU_dwo_name`), `stmt_list` and whether - `DW_AT_low_pc` is present. -- Each attribute carries an explicit `present`, `absent`, `unresolved` or - `unknown` state. A value that cannot be trusted is never returned as a fact. -- Locate `.debug_info`, `.debug_abbrev`, `.debug_str`, `.debug_line_str` and - `.debug_str_offsets` by container. Mach-O sections are read only from the - `__DWARF` segment, by file range rather than VM mapping. Decompress ELF - `SHF_COMPRESSED` zlib and zstd, and GNU `.zdebug_*` and Mach-O `__zdebug_*` - zlib, within a fixed `256 MiB` decompressed allowance; a larger declared - size fails the call. -- Bound DWARF 5 `strx` indexes to their `.debug_str_offsets` contribution and - apply `DW_AT_str_offsets_base` regardless of attribute order. Decode chained - `DW_FORM_indirect` within the unit. An unknown form becomes a unit issue that - names the form code. -- Identify ELF relocation sections by type and `sh_info` target. In an ET_REL - image with unapplied debug relocations, relocated fields stay `unresolved`; - when `.debug_abbrev` holds more than one table, `abbrev_offset` is null, the - unit reports `unapplied_relocation` and its DIE is not read. -- Page units with `offset` and `limit` (default `32`, maximum `256`). Bound the - walk (`100,000` units), abbreviation entries (`8,192`) and attributes - (`256`), retained string bytes (`64 KiB`), unit issues (`32`) and the input - read (`512 MiB`). Decompression attempts and abbreviation parsing share - aggregate work allowances. Form reads and `DW_FORM_indirect` hops share a - `1,048,576`-step allowance per walk; exhaustion is a `decode_budget` unit - issue with `partial` coverage. -- Report `coverage.status` from the shared coverage vocabulary (`complete`, - or `partial` with a reason) and `debug_info` as `present` or `absent`. - `absent` does not establish that a separate debug file is absent; ELF and PE limitations name whether `.gnu_debuglink` was - observed. A `.dwo` object is `partial` because `.debug_info.dwo` is not read. -- A universal Mach-O requires `architecture`; the value is rejected for every - other image. MCP requires an absolute path. - -## Acceptance - -Unit, provider, boundary, MCP and CLI acceptance tests cover DWARF 2 through 5, -64-bit offsets, compressed sections, split skeletons, unknown forms, truncated -units, abbreviation budgets, relocatable objects and the decompressed-size -allowance. `npm run verify:dwarf-units` builds owned C fixtures and compares -every unit's version, name, comp_dir, producer and dwo_name with -`llvm-dwarfdump` across Mach-O objects and linked ELF and PE images, and checks -fixed expectations for an ELF relocatable object, an `ld.lld -r` merge and a -`.dwo` object. The [verification record](../../../verification/dwarf-units-2026-10-31.md) -lists the variants run and those skipped. - -## Out of scope - -Line tables, types, functions, child DIEs and location expressions; following -`.dwo` files, `.gnu_debuglink` or build-id links; decoding `.gnu_debuglink` -contents or GNU build-id notes; applying relocations; opening `.dSYM` bundles; -and target execution. diff --git a/docs/specs/native/dwarf-units/tasks.md b/docs/specs/native/dwarf-units/tasks.md deleted file mode 100644 index cd348fce7a..0000000000 --- a/docs/specs/native/dwarf-units/tasks.md +++ /dev/null @@ -1,10 +0,0 @@ -# Tasks - -- [x] Define single-feature scope, contracts and implementation plan (`spec.md`, `plan.md`). -- [x] Define the DWARF unit report schema, limits and coverage states in `src/domain/native/dwarfUnits.ts`. -- [x] Locate and decompress ELF, Mach-O and PE debug sections, including the Mach-O `on_disk` file-range fact. -- [x] Decode abbreviations, framed units and unit DIEs with bounded `strx`, `DW_FORM_indirect` and relocation handling. -- [x] Register the MCP tool and CLI command; add provider, boundary, MCP and CLI acceptance tests. -- [x] Compare compiled fixtures with `llvm-dwarfdump` in `scripts/verify-dwarf-units.mjs` and record the run. -- [x] Add the DWARF compile units guide, CLI and README entries and skill guidance. -- [ ] Compare a GCC-produced object, a linked Mach-O image and a `.dSYM` DWARF file; the recorded run covered none of them. diff --git a/docs/specs/native/elf-debug-link/plan.md b/docs/specs/native/elf-debug-link/plan.md deleted file mode 100644 index f9fc5e7056..0000000000 --- a/docs/specs/native/elf-debug-link/plan.md +++ /dev/null @@ -1,38 +0,0 @@ -# Implementation plan - -## Boundary and contract - -`src/domain/native/elfDebugLink.ts` owns the input and result schemas, limits -and limitations. Inputs use `absoluteLocalPathStringSchema`, the shared owner of -the MCP absolute-path rule. - -`src/native/elf/ElfDebugLink.ts` decodes the image. Sections come from -`readElfImage` and build-ids from `parseElfNotes`, so ELF headers and note -tables are not re-parsed here. `src/native/elf/ElfDebugLinkProvider.ts` reads -the image and candidate through the stable artifact read. The candidate is -streamed by `streamStableArtifact` in `src/artifacts/readStableArtifact.ts`, -which hashes and CRCs bounded chunks and retains only a caller-sized prefix. - -`src/application/binaryDiagnostics/ElfDebugLinkService.ts` depends on the -domain and the `ElfDebugLinkPort`. It is composed in -`src/composition/binaryDiagnostics.ts` and registered through -`capabilityDeclarations.ts`, `capabilityServices.ts` and `createServer.ts`, -beside the sibling binary diagnostics tools. - -## Incremental work and validation - -1. Define the schemas, limits and limitations, with domain tests. -2. Decode `.gnu_debuglink`, `.gnu_debugaltlink`, `.gnu_debugdata` and build-ids - over synthetic ELF fixtures for both widths and endiannesses. -3. Add the candidate stream and verification, with service tests for each - status and for cancellation. -4. Register the CLI command and MCP tool, then add acceptance, filesystem and - MCP boundary tests, including the absolute-path schema test. -5. Write the guide and the CLI reference entry, update the skill reference, - and run focused tests, lint, typecheck and test discovery. - -## Effects and compatibility - -Additive: one new read-only tool and CLI command. Existing tools and Evidence -shapes do not change. The candidate is never executed, and lookup paths are -reported, not opened. diff --git a/docs/specs/native/elf-debug-link/spec.md b/docs/specs/native/elf-debug-link/spec.md deleted file mode 100644 index 0857343dea..0000000000 --- a/docs/specs/native/elf-debug-link/spec.md +++ /dev/null @@ -1,74 +0,0 @@ -# ELF separate debug-file linkage - -## Problem and outcome - -A stripped ELF often names a separate debug file through `.gnu_debuglink`, -`.gnu_debugaltlink`, or its GNU build-id. REA reports ELF notes and layout, but -it has no workflow that answers which debug file an image names or whether a -file the caller already has is that debug file. An agent has to guess from -file names. - -This feature adds `inspect_elf_debug_link` and `inspect-elf-debug-link`. They -read one selected ELF32 or ELF64 image, report its debug-file linkage, and, when -the caller supplies one candidate file, check whether the candidate matches. - -[ELF debug files](../../../guides/native/elf-debug-link.md) describes the current behavior and -limitations. This directory is the feature specification, implementation plan -and task list. The guide does not replace these files. - -## Requirements - -1. The image is a local ELF32 or ELF64 file, read through the stable artifact - read. It is never executed. Nothing is searched for on the filesystem or - the network. -2. `.gnu_debuglink` reports its NUL-terminated file name and the CRC32 that - follows the 4-byte padding, in the image endianness. -3. `.gnu_debugaltlink` reports its NUL-terminated file name and the raw - build-id bytes that follow it. -4. The GNU build-id is read from `PT_NOTE` and `SHT_NOTE` tables through the - existing ELF note parser. The same build-id from both tables is one - observation. Distinct build-ids are listed and none is selected. -5. `.gnu_debugdata` reports presence, file offset, stored size, and whether the - first six bytes are the xz magic. The payload is not decoded. -6. `lookup_paths` lists the conventional GNU/Linux strings derived from the - build-id, the debuglink name, and the alternate build-id. These strings are - not opened. A debuglink name that is empty, `.`, `..`, or contains a path - separator does not produce the directory-derived strings. -7. A missing named section is observed absence only when section names are - complete. Incomplete names make it `unknown`. A malformed or truncated - section is `malformed`, not absence. -8. With a candidate, the CRC32 over the whole candidate and the image and - candidate GNU build-ids are compared. Any mismatch is `does_not_match`. A - match with no mismatch is `matches`. If neither check can run, the status is - `cannot_verify`. The candidate's `.debug_info` and `.symtab` presence is - reported. -9. The candidate is streamed in bounded chunks. Candidates within - `max_file_bytes` are also decoded for sections and build-id. Larger ones get - CRC32 and SHA-256 over the whole file and an ELF header decode only. A - missing, unreadable, changed, or over-limit candidate returns - `cannot_verify` with `candidate_unreadable`, and the image linkage is still - reported. A candidate that exceeds the `max_entries` or ELF decoding budget - keeps the image linkage and the CRC32 check; its build-id check is - `unavailable` with `candidate_build_id_unknown`, and sections that were not - decoded are `unknown`. -10. Names, build-ids and note scans are bounded: 4096-byte names, 256-byte - build-ids, and a `max_entries` note budget. Target-derived names and lookup - paths are marked untrusted. -11. MCP requires absolute paths through `absoluteLocalPathStringSchema`, and the - advertised schema carries that constraint. The CLI resolves relative paths - against the working directory. - -## Acceptance - -- Unit tests cover each section layout, both endiannesses, malformed and - truncated sections, conflicting build-ids, and lookup path derivation. -- Service tests cover candidate match, mismatch, unreadable, oversized, and late - cancellation. -- CLI acceptance, filesystem boundary, and MCP boundary tests exercise the - public contract, including the absolute-path schema. - -## Non-goals - -- Searching debug directories or debuginfod for a candidate. -- Decoding the `.gnu_debugdata` xz payload. -- Loading DWARF from the candidate. diff --git a/docs/specs/native/elf-debug-link/tasks.md b/docs/specs/native/elf-debug-link/tasks.md deleted file mode 100644 index 3989fdf695..0000000000 --- a/docs/specs/native/elf-debug-link/tasks.md +++ /dev/null @@ -1,9 +0,0 @@ -# Tasks - -- [x] Define the single-feature scope, contract and implementation plan. -- [x] Decode debuglink, debugaltlink, debugdata and build-id facts with unit tests. -- [x] Stream and verify a caller-selected candidate with service tests. -- [x] Register the CLI command and MCP tool with acceptance and boundary tests. -- [x] Carry the absolute-path rule in the MCP input schema. -- [x] Document the guide, CLI reference and skill reference. -- [x] Verify against a real stripped binary and its `llvm-objcopy --only-keep-debug` file. diff --git a/docs/specs/native/elf-dependencies/plan.md b/docs/specs/native/elf-dependencies/plan.md deleted file mode 100644 index d795742adc..0000000000 --- a/docs/specs/native/elf-dependencies/plan.md +++ /dev/null @@ -1,38 +0,0 @@ -# Implementation plan - -## Boundary and contract - -`src/domain/native/elfDependencies.ts` owns the input and result schemas, -limits and the shared limitation strings, and -`src/domain/analysisView/elfDependenciesView.ts` owns the retained-Evidence -view. `src/native/elf/ElfDependencyParser.ts` decodes the dynamic table, -GNU version tables and dynamic symbols over the existing ELF image reader, and -`src/native/elf/ElfDependenciesProvider.ts` admits the selected file and -applies the budgets. - -`src/application/binaryDiagnostics/ElfDependenciesService.ts` depends on the -domain and `src/ports/binaryDiagnostics/ElfDependenciesPort.ts` and validates -the report shape. It is composed beside the sibling binary diagnostics tools in -`src/composition/binaryDiagnostics.ts` and bound in -`src/server/serviceToolBindings.ts`. - -## Incremental work and validation - -1. Define the schemas, limits and limitations, with domain tests. -2. Decode `PT_DYNAMIC`, the `DT_*` strings and flags, and `PT_INTERP` over - synthetic fixtures for both widths and endiannesses. -3. Walk `.gnu.version_r` and `.gnu.version_d`, derive the per-namespace - maxima, and join undefined `.dynsym` imports to `library@version`. -4. Locate tables from section headers only when they agree with `DT_*`, and - from `PT_LOAD` when section headers are stripped, with partial coverage - for anything unreadable. -5. Add the summary view and its `inspect_analysis_view` collections. -6. Register the CLI command and MCP tool, then add acceptance, filesystem and - MCP boundary tests. -7. Write the guide and the CLI reference entry, update the skill reference, - and run focused tests, lint, typecheck and docs checks. - -## Effects and compatibility - -Additive: one new read-only tool, one CLI command and one analysis view kind. -Existing tools and Evidence shapes do not change. diff --git a/docs/specs/native/elf-dependencies/spec.md b/docs/specs/native/elf-dependencies/spec.md deleted file mode 100644 index b306770468..0000000000 --- a/docs/specs/native/elf-dependencies/spec.md +++ /dev/null @@ -1,82 +0,0 @@ -# ELF dynamic dependencies - -## Problem and outcome - -An agent looking at a Linux program often needs to know what it loads before -it runs: the libraries it names, the paths it searches, its interpreter and the -GNU symbol versions it requires. Today that means `ldd`, which invokes the -dynamic loader, or `readelf`, which is not always installed and is not -Evidence. - -This feature adds `inspect_elf_dependencies` and `inspect-elf-dependencies`. -They read the load-time dynamic-dependency inventory of one selected local -ELF32 or ELF64 `ET_EXEC` or `ET_DYN` image, without executing it, invoking the -dynamic loader or opening a disassembler. - -[ELF dynamic dependencies](../../../elf-dependencies.md) describes the current -behavior and limitations. This directory is the feature specification, -implementation plan and task list. The guide does not replace these files. - -## Requirements - -1. `needed[]` lists every `DT_NEEDED` string in dynamic-table order, keeping - duplicates. `DT_SONAME`, `DT_RPATH` and `DT_RUNPATH` are reported as - written, with `:`-split entries that keep empties and `$ORIGIN`, `$LIB` and - `$PLATFORM` tokens unexpanded, including `${...}` forms. -2. `DT_FLAGS` and `DT_FLAGS_1` decode into named `DF_*` and `DF_1_*` bits; - unrecognized bits stay numeric. `PT_INTERP` is reported when present. -3. `version_requirements` walks `.gnu.version_r` / `DT_VERNEED` with each - needed file's version names, hashes, weak flags and indices. - `version_definitions` summarizes `.gnu.version_d` and `VER_FLG_BASE`. -4. `derived_version_maxima` takes the highest `NAME_x.y` requirement per - namespace and is labelled `evidence_kind: "derived"`. Names outside that - pattern stay out of the derived set, and maxima do not establish ABI - compatibility. -5. `imports[]` lists undefined `.dynsym` symbols. With `.gnu.version`, each - keeps its version index, hidden bit and a resolved `library@version` when a - matching verneed record exists. Indices 0 and 1 are `unversioned`; a - missing record is `unknown` and an issue. -6. `DT_*` entries are the load-time facts. A section header is used for a - table only when it agrees with the `DT_*` address, file bytes, size and - entry width; a disagreeing section is an issue and the `DT_*` declaration - is used. Without section headers, tables are located from `PT_DYNAMIC` and - `DT_*` addresses through `PT_LOAD`. -7. A missing `PT_DYNAMIC` is an observed empty inventory. A table that cannot - be located, an unreadable string, an unterminated `PT_INTERP`, a hash-table - symbol count past the located `.dynsym`, or a GNU version chain whose links - and count disagree make coverage `partial` with issues. Complete coverage - never retains issues. -8. Budgets bound the file size (64 MiB default, 512 MiB maximum), `DT_NEEDED` - entries, GNU version records and undefined dynamic symbols, and each string - scan to 65536 bytes. Decoded strings share one scan and retained-text budget - fixed by the admitted image length. Exceeding a named budget fails with no - partial success. Cyclic version chains, duplicate unique dynamic tags, - malformed headers and unsupported extended numbering return no complete - inventory. -9. `detail: "summary"` retains the complete Evidence and returns identity, - counts and coverage. `inspect_analysis_view` with `kind: - "elf-dependencies"` pages `needed`, `versions`, `definitions`, `maxima`, - `imports` and `issues`. CLI summary requires `--evidence_output`. -10. Library, symbol and version names are target-derived and untrusted. MCP - requires an absolute path; the CLI resolves relative paths against the - caller's working directory. - -## Acceptance - -- Parser unit tests cover both widths and endiannesses, duplicate needed - names, search-path tokens, flag decoding, verneed and verdef walks, import - version joins, stripped section headers, disagreeing sections, budgets and - partial coverage. -- Domain and service tests validate the report shape and the derived maxima. -- View tests and application acceptance tests cover summary delivery and the - `inspect_analysis_view` collections. -- CLI acceptance, filesystem boundary and MCP boundary tests exercise the - public contract. - -## Non-goals - -- Resolving `DT_NEEDED` names or expanding search-path tokens against the - host filesystem. -- Invoking the dynamic loader or `ldd`, or executing the image. -- Relocatable objects and core dumps, which `inspect_kernel_module` and - `inspect_recorded_crash` cover. diff --git a/docs/specs/native/elf-dependencies/tasks.md b/docs/specs/native/elf-dependencies/tasks.md deleted file mode 100644 index be8d9e17c6..0000000000 --- a/docs/specs/native/elf-dependencies/tasks.md +++ /dev/null @@ -1,10 +0,0 @@ -# Tasks - -- [x] Define the single-feature scope, contract and implementation plan. -- [x] Decode `DT_NEEDED`, `DT_SONAME`, search paths, flags and `PT_INTERP`. -- [x] Walk GNU version requirements and definitions, and derive the maxima. -- [x] Join undefined `.dynsym` imports to `library@version`. -- [x] Locate tables without section headers and report partial coverage. -- [x] Add the summary view and its analysis-view collections. -- [x] Register the CLI command and MCP tool with acceptance and boundary tests. -- [x] Document the guide, CLI reference and skill reference. diff --git a/docs/specs/native/elf-unwind-ranges/plan.md b/docs/specs/native/elf-unwind-ranges/plan.md deleted file mode 100644 index 255029271f..0000000000 --- a/docs/specs/native/elf-unwind-ranges/plan.md +++ /dev/null @@ -1,35 +0,0 @@ -# Implementation plan - -## Boundary and contract - -`src/domain/native/elfUnwindRanges.ts` owns the input and result schemas, -limits and the shared limitation strings. `src/native/elf/ElfUnwindTables.ts` -decodes `.eh_frame` and `.eh_frame_hdr` over the existing ELF image reader. -Dynamic entries use the shared `readElfDynamicEntry`. -`src/native/elf/ElfIntervalIndex.ts` builds the section address and file-offset -indexes once per image. - -`src/application/binaryDiagnostics/ElfUnwindRangesService.ts` depends on the -domain and its port and validates the report shape. It is composed and -registered beside the sibling binary diagnostics tools in -`src/composition/` and `src/server/createServer.ts`. - -## Incremental work and validation - -1. Define the schemas, limits and limitations, with domain tests. -2. Decode CIEs and FDEs over synthetic fixtures for both widths and - endiannesses, including pointer encodings and extended lengths. -3. Decode `.eh_frame_hdr`, compare it with the FDEs, and bound the search - table. -4. Resolve symbols and containing sections through indexes, with a combined - symbol budget. -5. Register the CLI command and MCP tool, then add acceptance, filesystem and - MCP boundary tests. -6. Add the `verify:elf:unwind-ranges` script against a compiled C++ program. -7. Write the guide and the CLI reference entry, update the skill reference, - and run focused tests, lint, typecheck and docs checks. - -## Effects and compatibility - -Additive: one new read-only tool, one CLI command and one verifier script. -Existing tools and Evidence shapes do not change. diff --git a/docs/specs/native/elf-unwind-ranges/spec.md b/docs/specs/native/elf-unwind-ranges/spec.md deleted file mode 100644 index e0f9e7b1f7..0000000000 --- a/docs/specs/native/elf-unwind-ranges/spec.md +++ /dev/null @@ -1,92 +0,0 @@ -# ELF unwind function ranges - -## Problem and outcome - -A stripped ELF often has no symbol table, but its `.eh_frame` still names the -start and end of nearly every function so exceptions can unwind. REA can list -symbols and disassemble with a provider, but it cannot recover function -boundaries from unwind tables, so an agent without a disassembler has no -function list for a stripped binary. - -This feature adds `inspect_elf_unwind_ranges` and -`inspect-elf-unwind-ranges`. They read `.eh_frame` and `.eh_frame_hdr` from one -selected local ELF32 or ELF64 image and list the function ranges those tables -name, without executing the image. - -[ELF unwind function ranges](../../../guides/native/elf-unwind-ranges.md) describes the -current behavior and limitations. This directory is the feature -specification, implementation plan and task list. The guide does not replace -these files. - -## Requirements - -1. `.eh_frame` comes from section headers, or from `PT_GNU_EH_FRAME` when - section headers are missing. The source and examined file range are - reported. `SHT_NOBITS`, out-of-file and truncated tables are `incomplete`. - Program headers come from the shared section directory, which rejects an - unreadable program-header table, so a missing `PT_GNU_EH_FRAME` is observed - absence. An `.eh_frame` located only through the header's `eh_frame_ptr` - is read no further than the last FDE a decoded search table names. Without - a usable table it stops at the first undecodable record, including a CIE - with an unrecognized augmentation and its FDEs, or at the end of - its `PT_LOAD` without a terminator, and coverage is `partial`. -2. CIEs report version, augmentation, alignment factors, return-address - register, pointer and LSDA encodings, personality, and signal-frame and - B-key flags. A page returns only the CIEs its ranges name, so CIE output is - bounded by `limit`, and `coverage.total_cies` counts every decoded CIE. - CFA programs are counted, not evaluated. A CIE with an - unrecognized augmentation letter is not decoded, its FDEs are skipped - with a counted limitation, and coverage is `partial`. -3. FDEs become ranges with start, end, size, containing `SHF_ALLOC` section, an exact - symbol name when one starts at that address (a function, then an - `STT_GNU_IFUNC` resolver, then an untyped symbol), CIE index, LSDA and - personality, paged by `offset` and `limit`. -4. Encoded pointers follow the `DW_EH_PE` rules. A raw zero is a null pointer. - Resolved addresses and FDE ends wrap at the ELF32 or ELF64 address width. - `datarel` in `.eh_frame` resolves against `DT_PLTGOT`, then `.got.plt` or - `.got`, and an unresolved base leaves the record out with coverage - `partial`. Indirect pointers are not dereferenced: an FDE with an - indirect initial location is skipped with a counted limitation, and an - indirect `eh_frame_ptr` does not locate `.eh_frame`, and a search table - with an indirect encoding is neither compared nor used as a scan bound. - Each leaves coverage `partial`. -5. A 64-bit extended length keeps the `.eh_frame` CIE ID and pointer at 4 - bytes. -6. An FDE with a zero initial location is a discarded function. It is counted - as examined, not reported, and a limitation gives the count. -7. `.eh_frame_hdr` is decoded and its search table compared with the decoded - FDEs as `agree`, `disagree` or `unavailable`. The table is read for at most - `max_ranges` rows and no more rows than its bytes hold. A larger declared - count makes the header `incomplete` with a limitation. A declared count - with an omitted table is a `present` header with comparison - `unavailable`. A non-zero indirect count is not followed, so the count is - unknown and the header `incomplete`. -8. `.debug_frame` presence is reported but not decoded. -9. Budgets bound the file size, CIE and FDE counts, page size and the symbol - lookup across `.symtab` and `.dynsym`. Only symbols at decoded FDE starts - are kept, names are decoded only for the returned page, and that text has a - fixed 16 MiB allowance whose recovery is a smaller `limit`. Only the first `PT_GNU_EH_FRAME` is read; a - duplicate one that supplies the header makes coverage `partial`. Section and symbol lookups use - indexes built once per image, so cost does not grow as sections times - entries. Address translation uses `SHF_ALLOC` sections, then - `PT_LOAD`; a non-ALLOC section's `sh_addr` is never used. -10. Symbol names, section names and augmentation strings are marked - target-derived and untrusted. MCP requires an absolute path. - -## Acceptance - -- Unit tests cover CIE and FDE decoding for both widths and endiannesses, - pointer encodings, extended lengths, zero pointers, discarded FDEs, header - agreement and caps, and the GOT base. -- Service tests validate the report shape, including incomplete headers and - null LSDAs. -- CLI acceptance, filesystem boundary and MCP boundary tests exercise the - public contract. -- `npm run verify:elf:unwind-ranges` compares the reported FDE starts with - `readelf` or `llvm-dwarfdump` on a compiled C++ program. - -## Non-goals - -- Decoding `.debug_frame` or evaluating CFA programs. -- Applying relocations in relocatable objects. -- Following indirect EH pointers. diff --git a/docs/specs/native/elf-unwind-ranges/tasks.md b/docs/specs/native/elf-unwind-ranges/tasks.md deleted file mode 100644 index db7cc27214..0000000000 --- a/docs/specs/native/elf-unwind-ranges/tasks.md +++ /dev/null @@ -1,9 +0,0 @@ -# Tasks - -- [x] Define the single-feature scope, contract and implementation plan. -- [x] Decode CIEs and FDEs with pointer encodings and extended lengths. -- [x] Decode and bound `.eh_frame_hdr`, and compare it with the FDEs. -- [x] Resolve symbols and sections through per-image indexes. -- [x] Register the CLI command and MCP tool with acceptance and boundary tests. -- [x] Verify FDE starts against `llvm-dwarfdump` on a C++ program built with zig. -- [x] Document the guide, CLI reference and skill reference. diff --git a/docs/specs/native/gdb-executable/plan.md b/docs/specs/native/gdb-executable/plan.md deleted file mode 100644 index 3314dd5d5b..0000000000 --- a/docs/specs/native/gdb-executable/plan.md +++ /dev/null @@ -1,23 +0,0 @@ -# Implementation plan - -The contract owns the optional input. MCP bindings and the one-shot CLI forward -it to `GdbSessionManager`; the manager owns path admission, file observation, -protocol startup and publication. - -Extract Rizin's existing stable launch-file observation into one shared debugger -helper. Each manager retains failed file handles in its existing resource scope -or an equivalent startup scope drained by shutdown and cleanup retry. Preserve -Rizin's current outcome policy and caller-path semantics. -Completed hash facts also survive cancellation or failed final descriptor close -in both managers; startup still fails, retaining the exact failed cleanup owner. - -Observe the file once per admitted GDB start, before dialect negotiation. Pass -the same observation into each protocol attempt. The adapter quotes the load -path using its MI string owner and requires a complete successful reply. A -refused file load is a semantic startup failure, not a reason to repeat it with -another MI dialect. - -One GDB Evidence producer attaches the session's immutable initial selection and -its provenance to ordinary and partial observations. Native and simulated tests -exercise the public adapters and the startup lifecycle boundaries. Update the -owning CLI/Evidence documentation and regenerate ignored catalogs as required. diff --git a/docs/specs/native/gdb-executable/spec.md b/docs/specs/native/gdb-executable/spec.md deleted file mode 100644 index 104f7d1e80..0000000000 --- a/docs/specs/native/gdb-executable/spec.md +++ /dev/null @@ -1,42 +0,0 @@ -# Bind a GDB session to its selected load file - -Scope: [#11581](https://github.com/morluto/rea/issues/11581), approved in the -2026-11-16 maintainer handoff and recorded in -[#11682](https://github.com/morluto/rea/issues/11682#needs-an-owner-decision). - -`start_gdb_session` currently records an unknown target because it accepts no -file. An analyst who selects a file at startup needs subsequent command Evidence -to identify that initial file, separately from the current inferior. - -## Requirements - -1. Accept an optional absolute `executable` path on `start_gdb_session`. - The one-shot `debug-with-gdb` command exposes the same selection as - `--executable`, accepting a caller-relative local path. -2. Hash the selected regular file with the existing stable-file owner before - GDB loads it. Share hash outcome and failed-close interpretation with Rizin. - A physical hash failure leaves identity unknown with its reason; cancellation - and outstanding descriptor cleanup fail startup and retain cleanup ownership. - If hashing completed before final close failed or was cancelled, preserve its - SHA-256 and byte count in the startup error, including after cleanup retry. -3. Disable automatic loading before issuing the MI file-load request. Publish - readiness only after the load completes successfully. Loading does not issue - an inferior run, attach or shell command. -4. Bind command and partial startup Evidence to the initial file observation. - Preserve original and absolute startup paths as provenance. Later console - loads and attaches do not rebind it. Omission preserves an unknown target. -5. Preserve cancellation, startup reservations, failed-start cleanup retention, - cleanup retry and shutdown draining through the new stages. - -## Acceptance - -Public MCP and CLI workflows expose the input and retain the initial file hash -in Evidence. A real Linux GDB load of an owned executable leaves its execution -marker absent. Deterministic provider tests cover refused loading, cancellation -during loading and failed cleanup retry. Existing GDB lifecycle and Rizin hash -cleanup regressions continue to pass. Report simulated and real-provider -verification separately. - -This increment leaves unrestricted `gdb_console` authority and the session -identity rules in the [target identity ADR](../../../adr/evidence/target-identity.md) -in place. diff --git a/docs/specs/native/gdb-executable/tasks.md b/docs/specs/native/gdb-executable/tasks.md deleted file mode 100644 index 0b9e3e2eac..0000000000 --- a/docs/specs/native/gdb-executable/tasks.md +++ /dev/null @@ -1,34 +0,0 @@ -# Tasks - -- [x] Add the optional contract/CLI input and forward it to GDB startup (R1). -- [x] Share stable launch-file observation with Rizin and retain failed cleanup - through retry and shutdown (R2, R5). -- [x] Load after automatic loading is disabled, then publish readiness (R3). -- [x] Bind ordinary and partial Evidence to initial selection and provenance; - preserve unknown omission and later-command semantics (R4). -- [x] Verify public MCP/CLI behavior, refused/cancelled loading, cleanup retry, - and the affected existing lifecycle suites (R1–R5). -- [x] Run a real Linux GDB load-only workflow and record its limits; update - product documentation and required static/generated checks (acceptance). - -## Verification (2026-11-16) - -- Serial typecheck/lint and architecture guards passed. -- Ten focused files passed 301 tests before the completed-hash review fix, including advertised-schema/client - admission, CLI selection, late loading/cancellation, retained file and - debugger cleanup, and existing GDB/Rizin lifecycle behavior. -- Temporarily permitting MI2 retry after file-load refusal made the dedicated - regression fail with two loads instead of one; source was restored exactly. -- A public stdio MCP workflow with GNU GDB 13.1 on Linux loaded an owned ELF - whose path contained spaces and quotes. Evidence matched its SHA-256, - Python automatic loading was off, its execution marker remained absent, - and the session closed successfully. Native Rizin was not exercised. -- Six additional GDB/Rizin cases preserve completed hash facts when final close - fails, is cancelled, or both, through public error projection and cleanup retry. - All six fail against the pre-fix shared observer; the twelve-case file passed - with the fix. A broader rerun passed 306/307 tests; the remaining fixture - observed an empty asynchronous signal marker. Publishing that marker - synchronously removed the observation race, and both affected files passed - all 32 tests on the final source. Final CI is recorded in the PR. -- Documentation/generated checks and final native recheck are recorded in the - PR validation evidence. diff --git a/docs/specs/native/go-string-literals/plan.md b/docs/specs/native/go-string-literals/plan.md deleted file mode 100644 index 4ee6646e2a..0000000000 --- a/docs/specs/native/go-string-literals/plan.md +++ /dev/null @@ -1,47 +0,0 @@ -# Implementation plan - -## Boundary and contract - -Extend `goBinarySchema` in `src/domain/go/goBinary.ts` with optional -`string_literals` (`evidence_kind: "inferred"`, `items`, `discovered_count`, -`aggregate_bytes`, `max_items`, `truncated`, optional `limits_reached`), plus -`include_string_literals` and the Go-owned per-call budget controls on `src/contracts/go/goToolContracts.ts` and -`src/cli/goCommands.ts`. Add the `string_literals` view projection to -`src/domain/analysisView/goBinaryView.ts` so callers can page recovered literals -from retained Evidence without repeating file parsing. - -Implement `recoverGoStringLiterals` in `src/go/GoStringLiterals.ts` on top of -`BinaryContainer` and `createFileMappingIndex`. Pre-index readable `LoadRegion` -intervals once in `O(R log R)` so Mach-O section eligibility runs in `O(log R)` -with periodic `checkActive` cancellation checks. Normalize header-scan spans by -pointer alignment phase, merge overlaps, and sort by ascending file offset so -`reference_count` counts each physical header once and `first_header_offset` is -minimal. Deduplicate target slices in memory with bounded candidate and rejection -caches before sorting deterministically by `(location.offset, location.bytes)`. -Use exact offset/length keys, so configurable string lengths cannot collide in -an arithmetic key encoding. Resolve budget defaults once in the image reader -and pass that policy to string recovery. - -## Incremental work and validation - -1. Define domain/MCP/CLI schemas, limitation notes and `string_literals` analysis - view behavior while preserving default omission when not requested. -2. Implement `recoverGoStringLiterals` and wire `GoBinaryImage`, - `GoBinaryProvider` and `GoBinaryService` with cooperative cancellation. -3. Add unit fixtures across ELF/PE/Mach-O, Unicode format-control filtering, - budget/cap truncation, overlapping ELF spans, bounded negative caching and - 25,000-section Mach-O indexing/cancellation. -4. Extend `scripts/verify-go-binary.mjs` via `artifactMcpCall` so real compiled Go - targets verify both CLI and advertised MCP `outputSchema` parity. -5. Update the [Go binary guide](../../../guides/native/go-binaries.md), skill - guidance, generated catalogs and documentation route checks. - -## Effects and compatibility - -Default `inspect_go_binary` calls omit `string_literals` and preserve historical -Evidence compatibility. No external tool or target execution is introduced; only -bounded offline byte slicing over the admitted stable image buffer runs. The -input default remains `256 MiB`; callers can select byte and work budgets within -the advertised runtime representability. Count normalized report bytes before -allocating its JSON serialization. Every exhausted limit carries its own next -request repair, independently of transport delivery. diff --git a/docs/specs/native/go-string-literals/spec.md b/docs/specs/native/go-string-literals/spec.md deleted file mode 100644 index d4e6b79018..0000000000 --- a/docs/specs/native/go-string-literals/spec.md +++ /dev/null @@ -1,62 +0,0 @@ -# Go static string-header literal recovery - -## Problem and outcome - -Go compilers pack static string contents contiguously in read-only sections -(`.rodata`, `__TEXT,__rodata` / `__TEXT,__const`, `.rdata`) without NUL -terminators. Generic C-string scans merge adjacent Go literals into multi-kilobyte -runs. Extend `inspect_go_binary` / `inspect-go-binary` with opt-in, bounded -`(ptr, len)` `reflect.StringHeader` recovery across ELF, PE and thin Mach-O -images so static string slices are recovered at their exact boundaries. - -## Requirements - -- Keep `include_string_literals` opt-in (`false` by default) so existing - build-metadata output and payload size are unchanged unless requested. -- Scan only pointer-aligned non-executable initialized data spans (with indexed - `O(log R)` readable segment checks on Mach-O and sectionless/unnamed-ELF - load-region fallbacks) in deduplicated ascending file-offset order. -- Admit candidate `[ptr, ptr + len)` slices only inside single read-only - non-executable mapped spans with `1 <= len <= max_string_literal_bytes` - (default `4096`), non-overlapping with the - header itself, and valid printable UTF-8 (allowing `\t`, `\n`, `\r`, `U+200C` - and `U+200D` while rejecting control, surrogate, noncharacter, private-use and - invisible/bidi `\p{Cf}` code points). -- Keep the existing defaults for header-scan work (`64 MiB`), tracked candidates - (`100,000`), returned items (`2,000`), and aggregate returned UTF-8 bytes - (`512 KiB`). Expose each independent boundary as the positive-safe-integer - per-call controls `max_string_header_scan_bytes`, `max_string_candidates`, - `max_string_literals`, `max_string_literal_bytes` and `max_string_bytes`. - String-byte maxima follow the runtime's string representability; there is no - separate fixed 10,000-item ceiling. The bounded negative-slice cache (`4,096`) - affects reuse only and must not discard valid later candidates. -- Report `evidence_kind: "inferred"`, `discovered_count`, `aggregate_bytes`, - `truncated` and the exact exhausted `limits_reached` controls honestly. - Increasing a named control and inspecting the same complete artifact can - recover omitted facts; output paging cannot recover facts never retained. -- Deduplicate candidates by their complete offset and length independently of - the selected literal-length allowance; raising that allowance cannot merge - distinct slices or inflate their reference counts. -- Share one Go analysis budget owner with build-info input, representation and - search controls. Omitted selections keep defaults and remain omitted from - request Evidence. Representation maxima account for base64 expansion; no - setting changes the separate shared native structural decoder or MCP budget. -- Record limitation notes when Mach-O `LC_DYLD_CHAINED_FIXUPS` encodes rebases in - pointer slots or when truncation occurs, and expose a focused `string_literals` - projection in `inspect_analysis_view`. - -## Acceptance - -Unit, boundary and CLI acceptance tests cover ELF/PE/Mach-O (32/64-bit, little -and big endian), sectionless and unreadable-`.shstrtab` ELF images, overlapping -spans, `U+200C`/`U+200D` versus disallowed `\p{Cf}` controls, negative-cache and -output defaults, named budget recovery, long-literal candidate identity, and -25,000-region Mach-O indexing/cancellation. Service and provider tests cover -malformed numeric controls and same-artifact retries with larger budgets. The real Go binary -verifier validates CLI and advertised-schema MCP parity across compiled targets. - -## Out of scope - -Instruction-operand immediate string recovery (stack/register `MOV`/`LEA` pairs -without static two-word headers), Mach-O chained-fixup rebase decoding, binary -execution, and non-UTF-8 byte-slice guessing. diff --git a/docs/specs/native/go-string-literals/tasks.md b/docs/specs/native/go-string-literals/tasks.md deleted file mode 100644 index 41a2294ecc..0000000000 --- a/docs/specs/native/go-string-literals/tasks.md +++ /dev/null @@ -1,13 +0,0 @@ -# Tasks - -- [x] Define single-feature scope, contracts and implementation plan (`spec.md`, `plan.md`). -- [x] Extend `goBinarySchema`, MCP contracts, CLI flags and `inspect_analysis_view` (`string_literals`). -- [x] Implement bounded `(ptr, len)` recovery in `src/go/GoStringLiterals.ts` with `O(R log R)` Mach-O region indexing and non-overlapping file-order header scanning. -- [x] Add unit, provider, MCP view and CLI acceptance tests for multi-format recovery, Unicode `\p{Cf}` / ZWNJ / ZWJ filtering, caps, negative-cache bounds and 25,000-section Mach-O scaling. -- [x] Verify CLI and `artifactMcpCall` advertised-schema MCP parity across compiled targets in `scripts/verify-go-binary.mjs`. -- [x] Update the Go binary guide, skill reference and generated catalogs; pass documentation route and static checks. - -- [x] Consolidate Go-owned budgets and expose per-call input/report/build-info/search and inferred-string controls in CLI/MCP without changing defaults. -- [x] Preserve source validity and exact exhausted controls, remove the fixed 10,000-item schema ceiling, and deduplicate variable-length candidates with complete offset/length identity. -- [x] Run focused source string/service tests and production service budget-recovery checks over temporary offline fixture files. -- [ ] Run the compiled CLI/MCP boundary lanes and real Go verifier for the new budget selections; source checks do not establish those workflows. diff --git a/docs/specs/native/kernel-build-config/plan.md b/docs/specs/native/kernel-build-config/plan.md deleted file mode 100644 index cffee82882..0000000000 --- a/docs/specs/native/kernel-build-config/plan.md +++ /dev/null @@ -1,34 +0,0 @@ -# Implementation plan - -## Boundary and contract - -`src/domain/native/kernelBuildConfig.ts` owns the input and result schemas, -reasons, limits and limitations. `src/native/elf/KernelBuildConfig.ts` parses -the banner, the IKCFG framing and the bzImage setup header. -`src/native/elf/KernelCompressionCodec.ts` owns compression magic detection and -is shared with `KernelModuleParser.ts`, so the two parsers name codecs the same -way. `src/native/elf/KernelBuildConfigProvider.ts` reads the file through the -stable artifact read and passes the cancellation signal to the parser. - -`src/application/binaryDiagnostics/KernelBuildConfigService.ts` depends on the -domain and `KernelBuildConfigPort`. It is composed in -`src/composition/binaryDiagnostics.ts` and registered through -`capabilityDeclarations.ts`, `capabilityServices.ts` and `createServer.ts`, -beside the sibling binary diagnostics tools. - -## Incremental work and validation - -1. Define the schemas, reasons and limits, with domain tests. -2. Parse the banner and IKCFG framing over synthetic fixtures, including - malformed, truncated and decoy members. -3. Add bzImage payload handling and the shared codec detection. -4. Add search budgets and cancellation, with tests for each. -5. Register the CLI command and MCP tool, then add acceptance, filesystem and - MCP boundary tests. -6. Write the guide and the CLI reference entry, update the skill reference, - and run focused tests, lint, typecheck and docs checks. - -## Effects and compatibility - -Additive: one new read-only tool and CLI command. The kernel module parser's -codec detection moves to the shared owner with no change in its output. diff --git a/docs/specs/native/kernel-build-config/spec.md b/docs/specs/native/kernel-build-config/spec.md deleted file mode 100644 index 7527bd4e25..0000000000 --- a/docs/specs/native/kernel-build-config/spec.md +++ /dev/null @@ -1,80 +0,0 @@ -# Linux kernel build config - -## Problem and outcome - -Analysing a Linux kernel image usually starts with two questions: which kernel -version is this, and how was it configured. A kernel built with -`CONFIG_IKCONFIG` embeds its `.config` as a gzip blob between `IKCFG_ST` and -`IKCFG_ED`. REA reports kernel modules and ELF notes, but it cannot read the -version banner or the embedded config, so an agent needs a Linux host and -`scripts/extract-ikconfig`. - -This feature adds `inspect_kernel_build_config` and -`inspect-kernel-build-config`. They read one selected local kernel image and -report its `Linux version` banner and embedded build config, without -executing or booting it. - -[Linux kernel build config](../../../guides/native/kernel-build-config.md) describes the -current behavior and limitations. This directory is the feature -specification, implementation plan and task list. The guide does not replace -these files. - -## Requirements - -1. Accepted inputs are a `vmlinux` ELF, a raw arm64 `Image`, an x86 `bzImage` - or `zImage` whose payload is gzip, and a `configs.ko` module. The file is - read through the stable artifact read and never executed. -2. The banner is the first printable `Linux version ` string followed by a - version token that starts with a digit and ends at a NUL or newline within - 512 bytes. Version, builder and compiler are split from it. A banner with a - space right after `#` or at its end is the kbuild placeholder from - `init/version.o`, built without a build number or timestamp; a later banner - that repeats its text up to `#` without that gap replaces it. The scan is - linear in the searched bytes. -3. A config is `present` only when `IKCFG_ST` is followed by a gzip member that - ends exactly at the next `IKCFG_ED`, inflates within `max_config_bytes`, - passes its CRC-32 and ISIZE checks, and parses as `.config` text. Inflation - reads only the bytes up to that marker. -4. Framing that fails its checks or grammar, including a framed deflate stream - that does not decode or is cut off by `IKCFG_ED`, is `malformed`, never - `absent`. An unframed `IKCFG_ST` string is skipped. A valid config later in the bytes - still wins. -5. Entries report name, kind (`y`, `m`, `number`, `string`, `not_set`) and - value, with an exact `name` filter and `offset`/`limit` paging. -6. A bzImage setup header from boot protocol 2.08 locates the payload. A gzip - payload is inflated within `max_payload_bytes` and searched, with locations - marked `inflated_payload`. Other payload codecs, and a file that is itself a - compressed stream such as `Image.gz`, are `unsupported` and name the codec, - using the codec detection shared with the kernel module parser. -7. Budgets bound file size, config and payload inflate size, option count and - page size. The config search inflates at most 16 candidates and at most - four times `max_config_bytes` in total, charging a stream that fails - partway through its full per-candidate allowance. Exhausting the search budget is - `incomplete` with `config_search_exhausted` and coverage `partial`; a - member cut by the searched bytes is also `partial`. A malformed framed - config, or a payload that could not be searched, has coverage `unknown`. A member past - `max_config_bytes` fails the budget only when no later candidate is - accepted. -8. Cancellation is checked between candidates, between banner hits, while - scanning long text and while parsing config lines. Inflation runs off the - event loop and each scan, including marker searches that find nothing, text - checks, validation of a single long value and hashing, yields to it at least once per MiB, so a live - cancellation reaches those checks. -9. Banner text and config values are marked target-derived and untrusted. -10. MCP requires an absolute path. The CLI resolves relative paths against the - working directory. - -## Acceptance - -- Unit tests cover banner parsing, config framing, grammar, malformed and - truncated members, decoy candidates, search budgets, cancellation, and - bzImage payload handling. -- Service tests cover each status and reason. -- CLI acceptance, filesystem boundary and MCP boundary tests exercise the - public contract. - -## Non-goals - -- Decompressing xz, lz4, lzma, zstd, bzip2 or lzo payloads. -- Comparing the config with a source tree or evaluating Kconfig dependencies. -- Executing or booting the image. diff --git a/docs/specs/native/kernel-build-config/tasks.md b/docs/specs/native/kernel-build-config/tasks.md deleted file mode 100644 index a195392304..0000000000 --- a/docs/specs/native/kernel-build-config/tasks.md +++ /dev/null @@ -1,9 +0,0 @@ -# Tasks - -- [x] Define the single-feature scope, contract and implementation plan. -- [x] Parse the banner and IKCFG framing with unit tests. -- [x] Inflate gzip bzImage payloads and share codec detection with the kernel module parser. -- [x] Bound the config search and honor cancellation. -- [x] Register the CLI command and MCP tool with acceptance and boundary tests. -- [x] Document the guide, CLI reference and skill reference. -- [x] Verify against a real distribution kernel (Alpine 6.12 linux-virt bzImage and its `configs.ko`). diff --git a/docs/specs/native/native-initializers/plan.md b/docs/specs/native/native-initializers/plan.md deleted file mode 100644 index 0bbf718211..0000000000 --- a/docs/specs/native/native-initializers/plan.md +++ /dev/null @@ -1,44 +0,0 @@ -# Implementation plan - -## Boundary and contract - -The domain contract lives in -[`src/domain/native/nativeInitializers.ts`](https://github.com/morluto/rea/blob/main/src/domain/native/nativeInitializers.ts): -input schema, entry and coverage schemas, kinds, resolutions, standing -limitations and budgets. `NativeInitializersService` validates caller input, -re-parses provider output, checks paging and artifact identity, and builds -Evidence with a file-offset location per returned slot. CLI and MCP adapters -call the same service; the tool is registered with the `evidence` effect. - -## Parsers - -`NativeInitializersProvider` selects one image (thin or universal slice) and -dispatches to the ELF or Mach-O parser. Both produce `CollectedInitializer` -rows, and `finishInitializerReport` pages them, counts examined slots and -appends limitations after the standing ones. Both parsers record observations -through `InitializerNotes`, which keeps distinct messages to the note budget -and tallies per-row reasons, so the limitations list stays bounded. - -- `ElfInitializers.ts` reads the consumed `DT_*` tags once, builds sources in - declaration order with a shared slot budget, and resolves each slot. Dynamic - relocation writes come from the owner, - `readElfRelocationWritesSteps` in `ElfPointerRelocations.ts`; the RELATIVE - type per machine and ELF class comes from the same owner's - `elfRelativeRelocationType`. That owner also distinguishes RISC-V TLS from - other architectures' GLOB_DAT and records full COPY/TLS descriptor extents. - Section names and fallback file offsets come from an `addressRangeIndex` - built once over the section headers and searched by address. -- `ElfInitializerSymbols.ts` loads symbol tables under one total symbol - budget and decodes section REL / RELA records under one total record budget, - checking the caller signal during that walk. - `elfSymbolSectionIndex.ts` owns companion-table framing and tagged section - references shared with CUDA, so reserved markers never become directory indices. -- `MachoInitializers.ts` reuses the shared Mach-O container and chained-fixup - decoders, reads symbols under one budget across every `LC_SYMTAB`, and - names target sections through the same address index. - -## Effects and compatibility - -The tool reads one stable local file and never executes it. It adds a new -contract and changes no existing tool. `slot_va` is nullable only for -`DT_INIT` / `DT_FINI` whose value field is unmapped. diff --git a/docs/specs/native/native-initializers/spec.md b/docs/specs/native/native-initializers/spec.md deleted file mode 100644 index 961059350d..0000000000 --- a/docs/specs/native/native-initializers/spec.md +++ /dev/null @@ -1,110 +0,0 @@ -# Native initializer and finalizer functions - -## Problem and outcome - -Analysts reviewing a native image need the functions it declares to run before -`main` and at exit, without executing it or opening a disassembler provider. -`inspect_native_initializers` / `inspect-native-initializers` lists the -initializer and finalizer slots of one local ELF or Mach-O image, with each -slot's location, resolved target and how that target was obtained. The -[user guide](../../../guides/native/native-initializers.md) documents the result. - -## Requirements - -- Accept one local ELF32, ELF64, thin Mach-O or universal Mach-O image. A - universal Mach-O requires `architecture` to select one slice; other inputs - reject it. The CLI resolves relative paths; MCP requires an absolute path. -- ELF sources, in order: `DT_PREINIT_ARRAY`, `DT_INIT`, `DT_INIT_ARRAY`, legacy - `.ctors`, `DT_FINI`, `DT_FINI_ARRAY`, legacy `.dtors`. Without the dynamic tag, - fall back to `SHT_*_ARRAY` sections or `.init_array*` / `.fini_array*` / - `.preinit_array` names. Mach-O sources are sections typed - `S_MOD_INIT_FUNC_POINTERS`, `S_INIT_FUNC_OFFSETS` and - `S_MOD_TERM_FUNC_POINTERS`. -- Resolve values through RELATIVE and RELR dynamic relocations, then section - REL / RELA records for slots no dynamic relocation covers, then the stored - word when relocation coverage is known. Mach-O uses chained-fixup rebases, - `LC_DYLD_INFO` rebases (reported separately), `MH_OBJECT` section - relocations and `__init_offsets` image-base offsets. Anything else is - `unresolved`, never a stored zero. -- Resolve `SHN_XINDEX` through a uniquely linked, complete `SHT_SYMTAB_SHNDX` - table. Keep actual section indices separate from raw absolute/common/reserved - markers. Unreadable extensions preserve unknowns and independent ordinary symbols. -- Select ELF relocation rules by machine and word size, including RV32/RV64 - RELATIVE, RELR and word-sized absolute records. RISC-V TLS and resolver - relocations retain unknown values and their known write extents. -- Relocation coverage is per slot. A slot that a dynamic or section relocation - only partly overwrites or writes more than once is `unresolved`, and so is an - absolute relocation against an `STT_GNU_IFUNC` resolver. On 32-bit ARM the - Thumb bit is cleared for target section and file-offset lookup only. A slot with no - relocation found is `unresolved` when a dynamic table, or a section table - that could reach it, was not fully read; such a `.ctors` slot is not dropped - as a sentinel. A `COPY` relocation covers the bytes of its symbol's size and - a TLS descriptor two words. The size comes from the dynamic symbol table for - a dynamic record and from the table's linked symbols for a section record of - a linked image; an unread size leaves coverage unknown. A linked image's - section record that writes memory with no file bytes covers only the slots - it overlaps there when its extent is established, by a fixed width or a - `COPY` size, and otherwise leaves its table not fully read. A - linked image's non-`SHF_ALLOC` relocation sections were - applied at link time and are not reapplied. A Mach-O stored pointer word is - used only when no undecoded bind stream or external relocation could - replace it. -- Relocatable objects (`ET_REL`) report section-relative offsets and say so. -- `.ctors` / `.dtors` sentinels are 0 and all ones at the image's pointer width; - they are omitted and counted in a limitation. -- `DT_INIT` / `DT_FINI` have no slot pointer: their slot is the dynamic value - field, and `slot_va` / `slot_section` are null when that field is outside - every load segment. -- Names are exact untrusted file text marked `observed-untrusted`. A target is - named only by a defined symbol whose value equals it, or by the import name - of an unresolved symbolic relocation or chained bind. An unreadable name - (missing string table or offset outside it) is reported as no name and makes - the report `incomplete`. -- Bounds: 64 MiB default file budget (512 MiB maximum); 65536 slots in total; - 65536 symbols across all ELF symbol tables; 65536 symbols across all - Mach-O `LC_SYMTAB` commands; 1048576 section relocation records across all - relocation sections; 1024-byte names. Reaching a bound makes the report - `incomplete` with a limitation. -- Legacy Mach-O bind lookup permits at most 4096 candidate runs per query - and twice the file byte count across image queries. Exhaustion leaves - affected pointers unresolved; stream parsing and slot batches yield. -- Limitations are bounded: at most 24 distinct image observations, repeated - per-row reasons reported once with a count, and at most 40 lines in total. -- Section lookups for slot and target addresses use an index built once per - image, so their cost does not grow with headers times slots. -- Paging uses `offset` / `limit` (default 64, maximum 4096) over a stable - ordered index. `coverage.examined_entries` counts every slot read, including - omitted sentinels; `total_entries` is set only when the inventory is complete. - `coverage.status` is `partial` when declared slots or names were examined but - not reported (budgets, unreadable arrays, withheld names) and `unknown` when - completeness cannot be determined (relocation, fixup, symbol or mapping - coverage, duplicate or unterminated dynamic tags); unknown wins when both - occur. -- Malformed headers, multiple `PT_DYNAMIC` segments and truncated dynamic - sections fail without partial success. Cancellation is honored during slot - collection, the section relocation walk and the dynamic relocation walk, - which yields to other work at the shared reader's step boundaries. - -## Acceptance - -Parser tests cover ELF64 PIE (RELA, RELR, imports, `DT_INIT` / `DT_FINI`), -ELF32 REL in-place addends, `ET_REL` section relocations and sentinels, -unsupported relocation machines, slot, symbol and relocation budgets, -over-long names, tallied repeated observations, a near-maximal section table -with a full slot budget, cancellation in the relocation walks, skipped section -relocation tables, partly overwritten slots, `COPY` and TLS descriptor extents, -section `COPY` records sized by their symbol, section records that write -memory without file bytes, retained link-time -relocations, unreadable names, Mach-O chained fixups, `LC_DYLD_INFO` rebases, 32-bit images -with undecoded binds, `MH_OBJECT` section relocations, `__init_offsets`, the -shared and repeated `LC_SYMTAB` budget, and universal slices. CLI acceptance, filesystem boundary -and MCP boundary tests exercise the public workflows and Evidence output. - -## Out of scope - -Executing the image or proving that a listed address runs; runtime ordering -(file order is reported); disassembling initializer bodies; PE/COFF TLS -callbacks; Android packed relocations and machines other than x86-64, i386, -AArch64, 32-bit ARM and RV32/RV64 for relocation decoding; Mach-O fixup decoding for -images other than little-endian 64-bit arm64 and x86-64, and legacy -`LC_DYSYMTAB` external relocations. diff --git a/docs/specs/native/native-initializers/tasks.md b/docs/specs/native/native-initializers/tasks.md deleted file mode 100644 index 91e7de141f..0000000000 --- a/docs/specs/native/native-initializers/tasks.md +++ /dev/null @@ -1,16 +0,0 @@ -# Tasks - -- [x] Define the domain contract, budgets and standing limitations. -- [x] Decode ELF dynamic tags, arrays, legacy `.ctors` / `.dtors` and - `DT_INIT` / `DT_FINI` with a shared slot budget. -- [x] Resolve ELF slots through the shared dynamic relocation owner, then - section REL / RELA records, under total symbol and relocation budgets. -- [x] Decode Mach-O initializer pointers, `__init_offsets` and terminators. -- [x] Page results and count every examined slot, including sentinels. -- [x] Wire the shared service into CLI and MCP with Evidence provenance. -- [x] Cover parsers, service, CLI acceptance, filesystem and MCP boundaries. -- [x] Document the tool in the native initializers guide and CLI reference. -- [x] Resolve extended ELF symbol sections through a shared owner, preserving - special markers and partial facts, with CLI/MCP and real assembler controls. -- [x] Resolve RV32/RV64 pointer relocations through the shared owner, with - public CLI/MCP controls and independent Clang/LLD producer checks. diff --git a/docs/specs/native/ntfs-mft/plan.md b/docs/specs/native/ntfs-mft/plan.md deleted file mode 100644 index f6e6fdc681..0000000000 --- a/docs/specs/native/ntfs-mft/plan.md +++ /dev/null @@ -1,68 +0,0 @@ -# Implementation plan - -## Boundary and contract - -Follow the existing artifact readers. `src/domain/windows/ntfsMft.ts` owns FILE -record bytes and coverage; `src/domain/artifactFormatMetadata.ts` owns the -`ntfs-mft` result schema. `ntfsMftAttributes.ts` owns verified attribute -values and descriptor contracts. Journal joins retain an ordered identity/header -index and its reference lookup per validated acquisition pair. MFT detail pages -select at most 32 records from this index and decode only their retained source -bytes; page selection never triggers a new whole-MFT scan. `NtfsMftArtifactReader` reads the admitted file -through `ArtifactFileSource` and exposes its facts through `formatMetadata()`. -A record stream is its own content, so the root occurrence carries every fact -and no members are enumerated. - -Recognition lives in `hasMftFileRecordSignature` and is applied in -`classifyArtifactBytes`, next to the other unambiguous magic probes. - -## Incremental work and validation - -1. Define the first-step contract, limits and observations; add parser fixtures. -2. Implement the FILE record header and update-sequence fixup parse with - explicit limitations. -3. Add the reader, format descriptor and byte classification. -4. Decode attribute records, then `$FILE_NAME` attributes so a record's parent - reference, names and timestamps become explicit; keep hard links separate. -5. Parse `$UsnJrnl:$J` records and correlate them to records by full file - reference, including sequence numbers, reporting unresolved references. -6. Document the workflow in a native Windows artifact guide. - -## Effects and compatibility - -The inventory reads one caller-selected MFT file; the journal workflow reads -the explicitly paired MFT and journal files. It adds no target execution, -injection, mutation, protection recovery, network access, volume mount or live -filesystem access, so no maintainer scope decision is required. -`inspect_artifact` routing for every existing format is unchanged, and the new -format id appears only for bytes whose first record carries the `FILE` -signature. - -## References - -- https://learn.microsoft.com/en-us/windows/win32/fileio/master-file-table -- https://github.com/libyal/libfsntfs/blob/main/documentation/New%20Technologies%20File%20System%20(NTFS).asciidoc - -Current analyst behavior and limitations live in the -[NTFS guide](../../../guides/native/ntfs-metadata.md). - -## Acquired extension metadata - -The MFT owner resolves attribute-list graphs for selected base records, using -its existing verified record decoder and a page-local cache. The scanner's -bounded sample and the journal's independent detail projection share this rule. -The acquisition cache continues retaining only headers and raw validated bytes. -Typed reference outcomes and linked attribute/name schemas belong to -`ntfsMftAttributes.ts` and are consumed by the common metadata contract. Global -physical counts stay independent of bounded reference delivery. - -A page decodes at most 32 additional records beyond its selected physical -records. Each base emits at most 32 reference results, retaining source list -entries and explicit discovered omissions. This adds no volume reads, path -reconstruction, nonresident payload recovery or target execution. Real extension -captures and Windows-host execution remain unverified; source-built fixtures -exercise reference ownership, malformed prefixes, cycles and resource bounds. - -Journal and extension joins share `hasVerifiedMftRecordIdentity` at the MFT -owner. It consumes parsed sequence, slot verdict, extent and fixup facts; each -consumer keeps its separate base-versus-extension ownership rule. diff --git a/docs/specs/native/ntfs-mft/spec.md b/docs/specs/native/ntfs-mft/spec.md deleted file mode 100644 index 4a75696daa..0000000000 --- a/docs/specs/native/ntfs-mft/spec.md +++ /dev/null @@ -1,93 +0,0 @@ -# NTFS $MFT and USN Journal inspection - -This specification records an implementation increment and its original problem -statement. For current behavior and limitations, see the -[NTFS workflow guide](../../../guides/native/ntfs-metadata.md). - -## Problem and outcome - -REA has no reader for acquired NTFS metadata artifacts. An analyst holding a -captured `$MFT` stream cannot ask which FILE records it contains, whether their -update-sequence fixups survived acquisition, or which records are directories, -extensions of another record, or no longer in use. Add offline, read-only -inventory of a selected `$MFT` file, delivered in steps so each one merges on -its own. - -## Requirements - -- Recognize a `$MFT` stream by a plausible first `FILE` record header under - any file name. CLI and MCP target admission route it to the artifact reader. -- Validate each FILE record header: the `FILE` signature, sequence number, flags, - used and total byte counts, base record reference, and the update-sequence - array's offset, count and array bounds. -- Verify the update-sequence fixups: every sector trailer the array covers must - hold the array's sequence number. A mismatch keeps the record's header facts - and is reported per record and in the metadata count. -- Report a missing, misplaced or short update-sequence array as unverified - rather than as a clean record, and a trailing partial record as a byte count. -- Report the first invalid record signature and the number of invalid slots. - Continue at the next slot when the stream declared a supported record size. - With a fallback record size, stop at the first invalid signature. -- Bound the whole file at a fixed 512 MiB ceiling and report the ceiling as a - `limit` failure with its boundary. -- Return the first 32 decoded record headers with their source offsets and the - number of omitted headers. Aggregate counts cover the full parsed stream. -- Restore verified sector trailers in a per-record scratch buffer before - scanning attributes. The domain decoder retains resident `$FILE_NAME` - names, namespaces, parent references and source offsets. Report incomplete - coverage when the walk cannot finish or an attribute list may refer to - extensions. The first 32 record samples expose individual names, parent - references, namespaces, FILETIME values, sizes and attribute bits. Keep each - name attribute separate, including multiple names for one record. - -- Resolve a selected base record's resident attribute lists only within the - supplied MFT. Require full sequence/slot identity, verified fixups, base - ownership and exact attribute type/name/ID/VCN. Preserve physical and linked - facts separately, including each source offset. -- Share at most 32 additional record decodes per detail page, and deliver at - most 32 reference results per base. Preserve discovered-entry omissions, - unavailable list values, ambiguity and partial record facts. Visit list source - identities once, including cyclic graphs. Nonresident volume payload recovery - remains outside the acquired-metadata boundary. - -## Acceptance - -Synthesized fixtures cover a clean record, a failed fixup, a missing update -sequence array, an array shorter than the record's sector count, extension and -directory records, a record whose signature is wrong mid-stream, a trailing -partial record, an undeclared record size, a 4 KiB record, a stream shorter than -one header, bytes without the `FILE` signature, and the file-size ceiling. -Inventory tests cover the root occurrence's metadata and the coverage status -when a fixup fails, and classification tests cover several file names for the -same bytes. - -The paired acquisition workflow is available through -`rea inspect-ntfs-journal ./mft ./journal --maxRows 50 --json` and MCP -`inspect_ntfs_journal` with `mft_path` and `journal_path`. Select an acquired -logical MFT stream and the journal data stream from the same volume. Each -file has a 64 MiB working-set admission limit. Follow `nextFileOffset` as -`start_file_offset` on MCP or `--startFileOffset` on CLI and compare the two -input digests between pages. - -USN V2, V3 and V4 records are supported. V3/V4 opaque IDs remain unresolved -against MFT references; V4 delivers bounded extent samples with omission counts. -Both the journal events and the MFT metadata have independent continuation -positions. Padding, malformed records and truncation appear as coverage rows. -Record order follows the acquisition, and history completeness remains unknown. - -Automated CLI/MCP workflow tests use synthesized acquisitions. Real Windows 11 MFT -records were inspected through the packaged Linux CLI; see the -[verification record](../../../verification/ntfs-metadata-2026-11-11.md). -Paired V2 streams from a public NTFS volume fixture also passed CLI/MCP -verification against an independent parser. The fixture's original acquisition -environment and Windows-host execution remain unverified. - -## Page reuse lifetime - -Use one MCP session for multi-page traversal. Its shared acquisition scope keeps -one successful digest-bound pair and MFT/reference lookup, validates selected -file state before each reuse, refuses changed/unverifiable sources, and clears -retained data at scope shutdown or pair eviction. Failed acquisitions are not -cached. Each fresh CLI process reacquires its inputs. See the -[completed-task comparison](../../../verification/ntfs-journal-paging-2026-11-11.md) -for measurements, lifecycle regressions and verification limits. diff --git a/docs/specs/native/ntfs-mft/tasks.md b/docs/specs/native/ntfs-mft/tasks.md deleted file mode 100644 index 24dd4b0bea..0000000000 --- a/docs/specs/native/ntfs-mft/tasks.md +++ /dev/null @@ -1,18 +0,0 @@ -# Tasks - -- [x] Define the first-step scope, contract and limits. -- [x] Parse FILE record headers and update-sequence fixups with synthesized - fixtures and explicit limitations. -- [x] Add the reader, format descriptor and byte classification. -- [x] Decode attribute records, then `$FILE_NAME` attributes with parent - references, names, hard links and timestamps. -- [x] Parse `$UsnJrnl:$J` V2 records and correlate them by full file reference. -- [x] Return a bounded source-order page through CLI and MCP, preserving both - input digests and explicit coverage rows. -- [x] Decode V3/V4 layouts, bound extent samples, and report unknown history coverage. -- [x] Page MFT metadata independently of journal events. -- [x] Decode resident standard information, attribute-list references and nonresident mapping metadata. -- [x] Resolve resident attribute-list graphs into acquired extension metadata with full ownership checks, bounded decoding and explicit partial coverage. -- [x] Verify Windows 11 MFT records through the packaged Linux CLI, with pinned provenance and digests. -- [x] Verify paired logical MFT/journal streams from a public NTFS volume fixture on Linux against an independent parser. -- [ ] Verify Windows-host execution. diff --git a/docs/specs/native/ppc64-elfv2/plan.md b/docs/specs/native/ppc64-elfv2/plan.md deleted file mode 100644 index cde7fd0cd7..0000000000 --- a/docs/specs/native/ppc64-elfv2/plan.md +++ /dev/null @@ -1,38 +0,0 @@ -# Implementation plan - -## Boundary and contract - -`src/ghidra/GhidraPowerPcProfile.ts` owns PPC64 admission -(`ghidraPowerPcUnsupportedReason`), the pinned language -(`ghidraPowerPcLanguage`), and the profile facts -(`ghidraPowerPcProfileParameters`). `ghidraPinnedLanguage`, the analysis -profile, and the processor gate already route `powerpc` through these -functions. Callers keep the selected inputs. No CLI or MCP schema changes. - -The optional verifier `scripts/verify-real-ghidra-ppc64.mjs` obtains its -runner from `createVerifierCommands`. Clang launches, including those inside -`buildPowerPc64Fixture`, GNU readelf and the one-shot CLI use that runner. The verifier -closes the owner before `completeVerifierRun`. A failed close stays registered -on the fixture for retry, and the diagnostic workspace is retained. - -## Incremental work and validation - -1. Admit ELF64 `ET_EXEC` ELFv2 in both byte orders and refuse the other PPC64 - shapes from the PowerPC profile, without changing the 32-bit lane. -2. Pin `PowerPC:LE:64:A2ALT` or `PowerPC:BE:64:A2ALT` with compiler spec - `default`, and commit `powerpc_support_lane: "elf64-elfv2-exec-isa3"` with - the header facts. -3. Extend the profile tests for admission, a configured replacement language, - the refused shapes, and Hopper/IDA decline. -4. Extend the independent readelf and probe checks for the 64-bit fixture, - including a VSX word that is not in the listing and the global-entry thunk - fields. -5. Add `verify:ghidra:ppc64`. Own its compiler, reader and CLI processes with the - shared command runner, and describe the lane in the PowerPC guide. - -## Effects and compatibility - -ELF64 `ET_EXEC` ELFv2 targets move from refused to supported. Existing 32-bit -profiles are unchanged. The import stays read-only: the lane does not execute -the image, and Hopper, IDA, and Windows Ghidra P0 are unchanged. The verifier -adds no process authority beyond the shared command owner. diff --git a/docs/specs/native/ppc64-elfv2/spec.md b/docs/specs/native/ppc64-elfv2/spec.md deleted file mode 100644 index 8a59f19f14..0000000000 --- a/docs/specs/native/ppc64-elfv2/spec.md +++ /dev/null @@ -1,76 +0,0 @@ -# PPC64 ELFv2 Power ISA 3.0 lane - -## Problem and outcome - -`EM_PPC64` is already classified in the provider-neutral `powerpc` family, but -the Ghidra lane refused every ELF64 file. This feature admits ELF64 `ET_EXEC` -files that declare the ELFv2 ABI, in either byte order, through the existing -Ghidra provider. `rea analyze`, `rea function`, and the MCP session tools then -work on those executables. The lane does not execute PowerPC code. - -[PowerPC ELF analysis through Ghidra](../../../ghidra-ppc.md) describes the -current behavior. This directory is the feature specification, implementation -plan, and task list. The guide does not replace these files. - -The 32-bit big-endian lane remains the first milestone of -[#1741](https://github.com/morluto/rea/issues/1741). This lane answers -[#12085](https://github.com/morluto/rea/issues/12085). - -## Requirements - -1. Admit an ELF64 `ET_EXEC` whose `e_flags` ABI field (the low two bits) is 2 - (ELFv2), for little-endian and big-endian images. The family stays - `powerpc`. An ELF32 header that claims `EM_PPC64` stays unrecognized. -2. Import with `PowerPC:LE:64:A2ALT` or `PowerPC:BE:64:A2ALT` by byte order and - compiler spec `default`, committed as `language_selection: - "provider-pinned"`. A2ALT is the Power ISA 3.0 language. The G2-era - `PowerPC:LE:64:default` and `PowerPC:BE:64:default` languages are not the - lane default: they do not decode VSX, including the lane's `xxlor` probe. - Passing A2ALT explicitly keeps a later loader preference from changing how - these files decode. `REA_GHIDRA_LANGUAGE_ID` replaces the pin and is - recorded as `language_selection: "configured"`. Readback checks the observed - `language_id` and `compiler_spec_id`. -3. Commit `powerpc_support_lane: "elf64-elfv2-exec-isa3"` and the header facts - (`elf_class`, `byte_order`, `type`, `flags`) on the analysis profile, so the - interpretation is part of snapshot identity. A 32-bit profile stays - `elf32-be-exec-generic` and is otherwise unchanged. -4. Refuse every other PPC64 shape before provider startup. Support status is - `unsupported` with code `architecture_unsupported`, and profile resolution - fails with `AnalysisUnsupportedTargetError`. The refused shapes are an ELFv1 - ABI (1), an undeclared ABI (0), any other value in the ABI field, `e_flags` - bits outside that field, `ET_DYN` (shared objects and position-independent - executables), and `ET_REL`. -5. Report an ELFv2 global entry as Ghidra models it: `classification.thunk` is - true and `classification.thunk_target` is the local entry. Direct calls - resolve to the callee's local entry. Pseudocode presence is a liveness - check, not semantic equivalence. -6. Leave the 32-bit lane, Hopper, and IDA unchanged. Hopper and IDA still - report the `powerpc` family unsupported. Windows Ghidra P0 stays PE - x86/x86-64 only. -7. Real-provider acceptance is `npm run verify:ghidra:ppc64` on a - caller-supplied Linux or macOS Ghidra host. Clang, GNU readelf and the one-shot CLI run - through the shared command owner, including the runner passed into the - shared fixture builder. That owner is closed before the process-lineage - check. A failed close stays registered for retry and the diagnostic - workspace is retained. The fixtures are never executed. - -## Acceptance - -- Profile tests cover both byte orders' pinned language, compiler spec, - `language_selection`, `powerpc_support_lane`, and header facts; a configured - language replacing the pin; and refusal of the shapes above with status - `unsupported` and `AnalysisUnsupportedTargetError`. Hopper and IDA stay - `unsupported` for the family, including an admitted PPC64 target. -- The independent readelf boundary, probe words in file byte order, a VSX word - whose status is `not-in-listing`, the doubleword in both byte orders, and the - thunk fields are covered without a Ghidra-derived oracle. -- The real-provider verifier checks the observed language, the lane id, the - thunk pair, and an `ET_DYN` refusal before provider startup, then confirms an - empty process lineage. Compiler, reader and CLI process groups are owned by the - shared command runner. - -## Non-goals - -ELFv1 (including `.opd` function descriptors), `ET_DYN` and PIE load -verification, `ET_REL`, 32-bit little-endian PowerPC, VLE, XCOFF, executing the -image, and any new CLI command, MCP tool, or schema. diff --git a/docs/specs/native/ppc64-elfv2/tasks.md b/docs/specs/native/ppc64-elfv2/tasks.md deleted file mode 100644 index ab13e5940b..0000000000 --- a/docs/specs/native/ppc64-elfv2/tasks.md +++ /dev/null @@ -1,21 +0,0 @@ -# Tasks - -- [x] Define the single-feature scope, contract, and implementation plan. -- [x] Admit ELF64 `ET_EXEC` ELFv2 in both byte orders, and refuse ELFv1, an - undeclared ABI, other `e_flags` bits, `ET_DYN`, and `ET_REL`. -- [x] Pin `PowerPC:LE:64:A2ALT` and `PowerPC:BE:64:A2ALT` as `provider-pinned`, - and record `REA_GHIDRA_LANGUAGE_ID` as `configured`. -- [x] Commit `powerpc_support_lane: "elf64-elfv2-exec-isa3"` and the header - facts on the analysis profile. -- [x] Cover admission, the configured language, refusals, and Hopper/IDA - decline in `src/ghidra/GhidraPowerPcProfile.test.ts`. -- [x] Cover the readelf boundary, probe words, a `not-in-listing` VSX word, the - doubleword, and the thunk fields in the PowerPC conformance checks. -- [x] Add `verify:ghidra:ppc64`, and run its compiler and CLI through the shared - command owner, closed before the process-lineage check. -- [x] Update the PowerPC guide and index this feature record. -- [x] Record the contributor's Ghidra 12.2 Linux x86-64 runs of the PPC32 and - PPC64 verifiers in [the pull request](https://github.com/morluto/rea/pull/12517). - Those runs preceded the verifier ownership changes. -- [ ] Rerun both verifiers on a real Ghidra installation after the ownership - changes. A macOS real-provider run is also unrecorded. diff --git a/docs/specs/native/rust-wasm-auditable/plan.md b/docs/specs/native/rust-wasm-auditable/plan.md deleted file mode 100644 index e657317a09..0000000000 --- a/docs/specs/native/rust-wasm-auditable/plan.md +++ /dev/null @@ -1,51 +0,0 @@ -# Implementation plan - -## Boundary and contract - -`src/rust/RustWasmImage.ts` owns WebAssembly section framing: the preamble, -layer and version, section sizes read with the shared `readLeb128`, -custom-section names, the `.dep-v0` payload ranges and the data-section range. It reports failures through the -`ParseFailure` algebra with format `wasm`, and the section bound as a -`max_wasm_sections` decode limit. - -`src/rust/RustBinaryImage.ts` builds one layout for either container: identity -facts, the dependency span and the spans searched for compiler paths. The -native layout comes from `readBinaryContainer`; the WebAssembly layout comes -from `RustWasmImage`. The dependency decoder, PE alignment allowance and rustc -path retention are shared and unchanged. - -`src/domain/rust/rustBinary.ts` owns the report contract: `format` gains -`wasm`, and `bits` is explicitly `32 | 64 | null`. Null is valid only when -`format` is `wasm` and is not a number. Refinements bind `bits`, -`architecture`, `byte_order` and the dependency section name to the container. -`rustDependencySectionName` is the one owner of that name for the reader and -the schema. `metadataReportSubjectFormat` in -`src/domain/apple/machoTargetSelection.ts` maps a `wasm` report to the `file` -subject, and `requireMetadataReportSubject` accepts it, so the service, the -retained views and the CycloneDX view agree on one mapping. - -`src/rust/RustBinaryProvider.ts` projects the section-bound limit with -`parseLimitConstraint` as a `cpu` constraint and a fixed work ceiling, and -names the searched compiler-path source in limitations. - -## Incremental work and validation - -1. Walk section framing with boundary tests over synthetic modules. -2. Read `.dep-v0` and data-section rustc paths through the shared layout, and - widen the report contract. -3. Bound the section walk after review showed a 256 MiB module of three-byte - sections kept the synchronous walk busy for seconds. -4. Map the Evidence subject once and run the retained-view workflow on a - module. -5. Bind the remaining container facts in the report schema. -6. Update the guide, README rows, skill instructions, tool description and CLI - help, then run focused tests, `check`, `docs:check` and the source group. - -## Effects and compatibility - -Output widening only: `format` gains `wasm` and `bits` is `32 | 64 | null` -on the report and its summary view. Null is admitted only for `wasm` -reports, which were previously refused. ELF, PE and Mach-O reports remain -32 or 64. No new tool, input, subprocess, -temporary file or network access. Native reports change only in limitation -wording. diff --git a/docs/specs/native/rust-wasm-auditable/spec.md b/docs/specs/native/rust-wasm-auditable/spec.md deleted file mode 100644 index e441c6b29c..0000000000 --- a/docs/specs/native/rust-wasm-auditable/spec.md +++ /dev/null @@ -1,83 +0,0 @@ -# Rust dependency metadata in WebAssembly modules - -## Problem and outcome - -`cargo auditable build` for a `wasm32` target stores the same zlib-compressed -`.dep-v0` JSON that native builds carry, in a WebAssembly custom section. -`inspect_rust_binary` and `inspect-rust-binary` recognized only ELF, PE and -Mach-O containers, so every `.wasm` input was refused as an unsupported target -and an agent could not read a module's embedded crate list. - -This feature lets the existing tool and command read that list from a -WebAssembly core module. It adds no tool, command or input. - -[Rust binary dependency metadata](../../../rust-binaries.md#webassembly-modules) -describes the current behavior and limitations. This directory is the feature -specification, implementation plan and task list. The guide does not replace -these files. - -This record was written on 2026-11-17, during review, after the repository -adopted feature records. The requirements restate the contract the -implementation already had; no earlier plan is reconstructed. - -## Requirements - -1. The module is a local file read through the stable artifact read. It is not - validated, instantiated or executed. Only section framing is walked. -2. A version 1 core module is accepted. A component (layer 1) and any other - module version are unsupported targets, because a component embeds several - core modules and no input selects one. -3. A custom section named `.dep-v0` supplies the dependency list, and the - report's `section_name` is `.dep-v0`; the report schema binds each - container to its section name. `file_offset` and `section_bytes` locate the - payload after the section name, in the original file. A second `.dep-v0` - section is malformed; the walk ends there, so a later failure such as the - section bound does not replace it. -4. A missing `.dep-v0` section is null metadata with a limitation. It is not - evidence that the module has no dependencies. -5. `format` and `architecture` are `wasm` and `byte_order` is `little`. - `bits` is `32 | 64 | null`, and is `null` for this container because - WebAssembly declares no container word size and memory address types are - not inspected. Null is not a number and must not be coerced. ELF, PE and - Mach-O reports stay 32 or 64. The report schema, its field description and - the summary view refuse any report that combines these facts differently. -6. The rustc commit is inferred from `/rustc/<40-hex>/` paths in the module's - data section. Limitations name that source. A second data section is - malformed. -7. A header, section or section size that ends past the file is truncated. A - size or name length that does not fit a 32-bit LEB128 integer, a - custom-section name or name length that extends past its section, and a - name that is not UTF-8 are malformed. Integers are decoded by the shared - LEB128 reader. -8. The synchronous walk admits up to 65,536 section payloads. It checks the - length and file extent of the next section before returning a `cpu` resource - constraint. Malformed or truncated framing retains its format diagnosis. - This allowance is fixed, so `producer_limits` does not raise it. Retained - state is at most two `.dep-v0` ranges and one data-section range. -9. The Evidence subject format is `file`, as for `inspect_wasm_artifact`, with - no architecture. Retained summaries, package and edge pages and the - CycloneDX view accept a WebAssembly parent. -10. `architecture` on a module is rejected, as on any image that is not a - universal Mach-O. -11. ELF, PE and Mach-O reports are unchanged apart from limitation wording - that names where compiler paths were searched. - -## Acceptance - -- Boundary tests cover a module with and without `.dep-v0`, each refusal in - requirements 2, 3, 6 and 7 by failure kind, format, offset and field, and - the section bound at 65,536 and 65,537 sections. -- CLI acceptance covers a module report, its `file` subject and the component - refusal. The retained-view acceptance workflow runs on a module. -- MCP boundary tests validate a module report against the advertised output - schema and check the section-bound refusal through the public error - contract. -- A view test refuses imported reports whose container facts contradict - requirements 3 and 5. - -## Non-goals - -- Reading a component's embedded core modules. -- Validating, instantiating or executing a module. -- Decoding memory address types or any section other than the framing, the - `.dep-v0` payload and the data-section byte range. diff --git a/docs/specs/native/rust-wasm-auditable/tasks.md b/docs/specs/native/rust-wasm-auditable/tasks.md deleted file mode 100644 index 2dcf4bed21..0000000000 --- a/docs/specs/native/rust-wasm-auditable/tasks.md +++ /dev/null @@ -1,11 +0,0 @@ -# Tasks - -- [x] Walk core-module section framing and refuse components and other versions (requirements 1, 2 and 7). -- [x] Read `.dep-v0` and data-section rustc paths through the shared layout (requirements 3, 4 and 6). -- [x] Widen the report contract and bind its container facts (requirements 5 and 11). -- [x] Bound the synchronous section walk (requirement 8). -- [x] Map the Evidence subject once for the service, retained views and CycloneDX (requirements 9 and 10). -- [x] Cover the public contract with CLI acceptance and MCP boundary tests. -- [x] Document the guide, README rows, skill instructions, tool description and CLI help. -- [x] Verify on 2026-10-18 against `wasm32-wasip1` and `wasm32-unknown-unknown` builds from rustc 1.97.0 and cargo-auditable 0.7.7, comparing each field with an independent LEB128, zlib and JSON reader. -- [ ] Verify against wasm-bindgen or wasm-opt output, `wasm32-wasip1-threads`, `wasm64-unknown-unknown`, and macOS or Windows hosts. diff --git a/docs/specs/native/windows-refs/plan.md b/docs/specs/native/windows-refs/plan.md deleted file mode 100644 index 304b47cc8b..0000000000 --- a/docs/specs/native/windows-refs/plan.md +++ /dev/null @@ -1,234 +0,0 @@ -# Windows ReFS Filesystem Authority Implementation Plan - -> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. - -**Goal:** Admit fixed local ReFS volumes through REA's existing Windows native authority while preserving NTFS behavior and every current security invariant. - -**Architecture:** Extend the existing native admission owner instead of creating a ReFS backend. Record the observed filesystem on native `File`/`Runtime` owners and pass it through every identity projection, while the TypeScript contract accepts only the same two values. Prove the behavior with an independent Win32 volume observer and the existing full native and Ghidra verifiers on both filesystems. - -**Tech Stack:** C++17 Win32/Node-API, TypeScript/Zod/Vitest, Node.js 24.22.1, WSL Ubuntu with MinGW-w64, real Windows NTFS/ReFS volumes and Ghidra 12.1.4. - -**Spec:** [spec.md](spec.md) - -## Global Constraints - -- Accept only fixed local `NTFS` and `ReFS` volumes reporting `FILE_PERSISTENT_ACLS`; every other filesystem fails closed. -- Preserve native ABI version `1` and the existing identity fields; only the filesystem value domain expands. -- Do not weaken path, reparse, sharing, DACL, snapshot, cancellation, ownership or cleanup checks. -- Use Node.js `24.22.1`; Windows and WSL have independent `node_modules` and work areas. Generated native artifacts remain uncommitted. -- Do not claim a check that did not run. Do not mark the PR ready for the human owner and do not merge it. - -## Review Focus - -- Cross-volume snapshots: source and destination must retain different observed filesystem values rather than inheriting one global value; Task 2 asserts both. -- Less visible identity producers: native inspection, `runtime_open` and Cutter bridge verification must use the same owner-recorded value; Task 2 asserts each. -- Reparse and cleanup adversarial behavior on ReFS: Task 2 keeps the existing ancestor-conversion and cleanup-escape controls intact and runs them on both volumes. -- Unsupported values and stale consumers: Task 1 rejects an unknown filesystem at the schema boundary, Task 2 keeps the native allowlist/ACL predicates, and Task 3 pins user-facing NTFS/ReFS wording. -- Generated artifacts and package identity: Task 4 verifies the manifest, package contents, clean Git state and actual ReFS CLI scenario rather than relying on compilation alone. - ---- - -### Task 1: Filesystem identity contract - -**Files:** - -- Modify: `src/windows/WindowsNativeLoader.ts` -- Modify: `src/windows/WindowsNativeLoader.test.ts` - -**Interfaces:** - -- Consumes: the existing `WindowsNativeLoadHost` inspection fixture and `loadWindowsNativeAuthority`. -- Produces: `windowsFileIdentitySchema.filesystem` accepting exactly `"NTFS" | "ReFS"`; unsupported values produce `failureStage: "inspection"`. - -- [ ] **Step 1: Prepare isolated toolchains and establish a clean baseline** - -Use `nvm install 24.22.1 && nvm use 24.22.1`, then `npm ci` and `npm run check:fast` in the Windows ReFS worktree and in a separate WSL clone. Do not share `node_modules` between them. Record any pre-existing failure instead of attributing it to this change. - -- [ ] **Step 2: Write the failing ReFS contract tests** - -Extend the test fixture's capability overrides with `filesystem?: string`, applied to its identity. Add: - -```ts -it.each(["NTFS", "ReFS"])("admits %s filesystem identities", (filesystem) => { - const result = loadWindowsNativeAuthority(fixture({ filesystem }).host); - expect(result).toMatchObject({ - available: true, - authority: { inspection: { filesystem: { filesystem } } }, - }); -}); - -it("rejects an unsupported filesystem identity", () => { - expect( - loadWindowsNativeAuthority(fixture({ filesystem: "exFAT" }).host), - ).toMatchObject({ available: false, failureStage: "inspection" }); -}); -``` - -- [ ] **Step 3: Run the tests to verify the new ReFS case fails** - -Run: `npm run test:focused -- src/windows/WindowsNativeLoader.test.ts` -Expected: the ReFS case fails because `z.literal("NTFS")` rejects it; NTFS and exFAT controls retain their expected outcomes. - -- [ ] **Step 4: Implement the minimal schema change** - -Change the field to `z.enum(["NTFS", "ReFS"])` and update its identity comment to local NTFS/ReFS objects. Do not change the ABI constants or any other schema field. - -- [ ] **Step 5: Verify and commit** - -Run `npm run test:focused -- src/windows/WindowsNativeLoader.test.ts` and `npm run check:fast`; expect PASS. Commit: - -```bash -git add src/windows/WindowsNativeLoader.ts src/windows/WindowsNativeLoader.test.ts -git commit -m "feat(native): admit ReFS filesystem identities" -``` - -### Task 2: Native admission, owned identity and real-volume verification - -**Files:** - -- Modify: `native/windows/src/authority.hpp` -- Modify: `native/windows/src/filesystem.cc` -- Modify: `native/windows/src/process.cc` -- Modify: `tests/fixtures/windows/processBoundary.cc` -- Modify: `scripts/verify-windows-native.mjs` - -**Interfaces:** - -- Produces: `File.filesystem: std::wstring` and `Runtime.filesystem: std::wstring`, assigned at admission and inherited by handle-relative children. -- Produces: `napi_value identity(napi_env env, HANDLE handle, const std::wstring& path, const std::wstring& filesystem)`. -- Produces: `process-boundary.exe volume-semantics ` returning `{"filesystem":"NTFS|ReFS|OTHER","persistentAcls":boolean}` through an independent `GetVolumeInformationByHandleW` observation. - -- [ ] **Step 1: Add the independent observer and failing native assertions** - -Add the `volume-semantics` command to `processBoundary.cc`. In `verify-windows-native.mjs`, require `persistentAcls === true` and compare its filesystem string with the `.filesystem` property of `sourceIdentity`, `native.inspection.filesystem`, `driveRootRuntime`, `snapshot.source`, `snapshot.snapshot`, `readback`, `snapshotOwner.observation` and the Cutter bridge identity. Record the independently observed filesystem and an `observedFilesystemIdentity` control in the report when the boundary fixture is supplied. - -- [ ] **Step 2: Build the unmodified native artifact and verify the ReFS failure** - -Use WSL Node 24.22.1 for `npm run build:windows-native`, and compile the fixture with: - -```bash -mkdir -p .cache/windows-process-boundary -x86_64-w64-mingw32-g++ -municode -std=c++17 -O2 -static -Wall -Wextra \ - -o .cache/windows-process-boundary/process-boundary.exe \ - tests/fixtures/windows/processBoundary.cc -ladvapi32 -``` - -Run `node scripts/verify-windows-native.mjs . .cache/windows-process-boundary/process-boundary.exe` with `TEMP` and `TMP` set to an ignored directory on ReFS. Expected: FAIL before target analysis with the original `Backing volume must be NTFS with persistent ACLs` constraint, proving the old native admission still blocks ReFS. - -- [ ] **Step 3: Implement native admission and identity propagation** - -In `openFile`, split the two failures into `Backing volume filesystem is outside the verified NTFS/ReFS profile` and `Backing volume does not support persistent ACLs`, then store the observed name on `File`. Replace NTFS-only path wording with fixed-local wording while leaving all other checks unchanged. - -Add `filesystem` to `File` and `Runtime`. Set `Runtime.filesystem = parent->filesystem` in `createRuntime`, propagate `root.filesystem` in `runtimeDirectory`, and update every `identity` caller in `filesystem.cc` and `process.cc` to pass the owning value: open, inspection, runtime creation/open, Cutter verification, snapshot source and snapshot destination. Update NTFS-specific comments to the verified NTFS/ReFS boundary without altering cleanup behavior. - -- [ ] **Step 4: Rebuild and verify ReFS, then NTFS** - -Rebuild the native artifact and boundary fixture in WSL. Run `npm run verify:windows-native:artifact` and the full native verifier on ReFS; expect all existing controls plus `observedFilesystemIdentity` to pass with `filesystem: "ReFS"`. - -Create a detached NTFS worktree at `C:\Users\oi\AppData\Local\Temp\rea-windows-refs-ntfs` for the same revision, install its Windows dependencies, and copy the same generated native artifact and boundary fixture into it. Run the full verifier there with `TEMP`/`TMP` on NTFS; expect `filesystem: "NTFS"` and no regression. - -- [ ] **Step 5: Commit native code and its regression coverage** - -```bash -git add native/windows/src/authority.hpp native/windows/src/filesystem.cc \ - native/windows/src/process.cc tests/fixtures/windows/processBoundary.cc \ - scripts/verify-windows-native.mjs -git commit -m "feat(native): support ReFS filesystem authority" -``` - -### Task 3: Capability declarations, diagnostics and documentation - -**Files:** - -- Modify: `src/windows/WindowsNativeLoader.ts` -- Modify: `src/windows/WindowsNativeLoader.test.ts` -- Modify: `src/ghidra/GhidraProviderCapabilities.ts` -- Create: `src/ghidra/GhidraProviderCapabilities.test.ts` -- Modify: `src/ghidra/GhidraDoctor.ts` -- Modify: `src/ghidra/GhidraDoctor.test.ts` -- Modify: `scripts/verify-real-ghidra-windows.mjs` -- Modify: `scripts/verify-windows-native-inspection.mjs` -- Modify: `native/windows/README.md` -- Modify: `docs/providers/windows-ghidra-p0.md` -- Modify: `docs/providers/ida-provider.md` -- Modify: `docs/getting-started/installation.md` -- Modify: `docs/guides/native/native-investigation.md` -- Modify: `docs/testing-lanes.md` - -**Interfaces:** - -- Produces: user-facing capability and recovery text limited to fixed local NTFS/ReFS, with no remaining NTFS-only claim in the touched Windows native/Ghidra workflows. -- Produces: the real Ghidra verifier limitation `windows-x64-local-ntfs-refs-only`. - -- [ ] **Step 1: Add failing wording tests** - -Assert that the loader self-test remediation contains `writable local NTFS/ReFS temporary directory`, `windowsP0Limitations` contains `local NTFS/ReFS targets and runtimes`, and a passing doctor's `native_authority` detail contains `local NTFS/ReFS only`. Keep all existing diagnostic behavior assertions unchanged. - -- [ ] **Step 2: Run focused tests and confirm the old wording fails** - -Run: `npm run test:focused -- src/windows/WindowsNativeLoader.test.ts src/ghidra/GhidraProviderCapabilities.test.ts src/ghidra/GhidraDoctor.test.ts` -Expected: FAIL on the NTFS-only strings. - -- [ ] **Step 3: Update declarations and every owning document** - -Apply the exact NTFS/ReFS wording from Step 1, update the inspection script's host/error and retained-handle comments, and replace the Ghidra report limitation. Update the listed guides to describe the same fixed-local boundary and record the independent volume-semantics observer. Do not alter NTFS MFT/USN functionality or unrelated historical specifications. - -- [ ] **Step 4: Verify wording, discovery and static checks** - -Run the focused tests, `npm run verify:test-discovery`, `npm run check:fast`, and a scoped search for `local NTFS`, `NTFS only`, `NTFS-only`, `fixed local NTFS` and `local-ntfs`. Expect PASS with no stale claim except the approved historical statement in `docs/specs/native/windows-refs/spec.md` and unrelated formats. - -- [ ] **Step 5: Commit** - -```bash -git add src/windows/WindowsNativeLoader.ts src/windows/WindowsNativeLoader.test.ts \ - src/ghidra/GhidraProviderCapabilities.ts src/ghidra/GhidraProviderCapabilities.test.ts \ - src/ghidra/GhidraDoctor.ts src/ghidra/GhidraDoctor.test.ts \ - scripts/verify-real-ghidra-windows.mjs scripts/verify-windows-native-inspection.mjs \ - native/windows/README.md docs/providers/windows-ghidra-p0.md \ - docs/providers/ida-provider.md docs/getting-started/installation.md \ - docs/guides/native/native-investigation.md docs/testing-lanes.md -git commit -m "feat(native): advertise ReFS Windows support" -``` - -### Task 4: Final verification and Draft PR - -**Files:** - -- Modify: `docs/specs/native/windows-refs/tasks.md` -- Create locally, never commit: `.cache/windows-refs-pr.md` and verification reports under `.cache/`. - -**Interfaces:** - -- Produces: one reviewed feature branch, a linked Draft PR, and reproducible NTFS/ReFS verification evidence. No generated binaries enter Git. - -- [ ] **Step 1: Run source, documentation and package checks on the final revision** - -In the independent WSL clone run `npm run check`, `npm run docs:check`, and `npm run verify:package`. On Windows run `npm run verify:test-discovery`, `npm run verify:windows-native:artifact`, `npm run verify:package:windows`, and `npm pack --dry-run`. Record actual results; investigate failures rather than weakening checks. - -- [ ] **Step 2: Repeat all real Windows lanes on both filesystems at the final commit** - -Build `.cache/windows-native-inspection-fixture` through WSL, then run `node scripts/verify-windows-native-inspection.mjs` with `TEMP`/`TMP` on each filesystem. Repeat the full `verify:windows-native` matrix with the independent boundary fixture. - -Run `npm run verify:ghidra:windows` in each worktree with `GHIDRA_INSTALL_DIR=D:\工具\ghidra_12.1.4_PUBLIC`, `JAVA_HOME=C:\Program Files\Zulu\zulu-25`, and `TEMP`/`TMP` on the corresponding filesystem. Expect complete operation coverage, cleanup completion and `windows-x64-local-ntfs-refs-only`. - -- [ ] **Step 3: Exercise the original ReFS user scenario through the source CLI** - -In the ReFS worktree run `node scripts/rea.mjs analyze D:\项目\逆向分析\魔塔\TSW.exe` with `REA_ANALYSIS_PROVIDER=ghidra`, the Ghidra/Java settings above, and ReFS `TEMP`/`TMP`. Expect the original target SHA-256 `41cb9844d9bdcf2641a34d4b152d6fbbb0455077abe0e9d7bfed77761a4d2779`, a completed overview, and no snapshot-admission failure. Close the session and confirm owned runtime paths are removed. - -- [ ] **Step 4: Review the final diff and synchronize upstream** - -Run `git diff --check`, `git status --short`, `git diff upstream/main...HEAD`, and a generated-file sweep. Fetch `upstream/main`; if it moved, rebase this branch and rerun every affected real-world check. Update `tasks.md` to mark only completed items and commit it as `docs(native): record ReFS verification tasks`. - -- [ ] **Step 5: Push and create the Draft PR** - -Push `feat/windows-refs-support` to `QianNangong/rea`. Create a Draft PR to `morluto/rea:main` titled `feat(native): support ReFS filesystem authority`, linking #289 and summarizing the baseline failure, design, exact checks and remaining gaps. Use `.cache/windows-refs-pr.md` for the body and leave every human **Author readiness** declaration unchecked for the owner. - -- [ ] **Step 6: Hand off for human ownership** - -Ask the human owner to review the final diff and verification evidence, complete the readiness declarations themselves, and decide whether to mark the PR ready. Do not merge or represent maintainer approval as obtained. - -## References - -- [Windows ReFS specification](spec.md) -- [REA #289: handle-based reparse-safe filesystem authority](https://github.com/morluto/rea/issues/289) -- [Windows native build and verification guide](https://github.com/morluto/rea/blob/main/native/windows/README.md) diff --git a/docs/specs/native/windows-refs/spec.md b/docs/specs/native/windows-refs/spec.md deleted file mode 100644 index 8a60081167..0000000000 --- a/docs/specs/native/windows-refs/spec.md +++ /dev/null @@ -1,86 +0,0 @@ -# Windows ReFS filesystem authority - -## Problem and outcome - -The Windows native authority currently admits only fixed local NTFS volumes. -Its `openFile` admission combines the filesystem-name check and the persistent -ACL check in one failure, so a ReFS target is rejected with `Backing volume must -be NTFS with persistent ACLs` even when ReFS reports `FILE_PERSISTENT_ACLS` and -the target's DACL is readable. The rejection occurs while creating the protected -target snapshot, before Ghidra starts. - -Extend the existing shared Windows filesystem authority to fixed local ReFS -volumes without weakening its handle, identity, DACL, snapshot or cleanup -boundaries. NTFS behavior must remain unchanged, and every other filesystem must -continue to fail closed. This increment belongs to the additional-filesystem -acceptance direction in -[#289](https://github.com/morluto/rea/issues/289). - -## Requirements - -- Admit a fixed local volume only when its filesystem is `NTFS` or `ReFS` and it - reports `FILE_PERSISTENT_ACLS`. Keep the existing fixed-drive, path-component, - reparse-point and sharing admission rules unchanged. -- Report unsupported filesystems and missing persistent ACL support as distinct - constraints. Do not imply that ReFS lacks ACL support. -- Record the observed filesystem in the native `File` or `Runtime` owner at - admission. Handle-relative private children inherit the runtime's filesystem; - snapshot sources and destinations report their respective observed values. - Remove the hardcoded `NTFS` identity projection. -- Accept exactly `NTFS` and `ReFS` in `windowsFileIdentitySchema`; unknown values - remain invalid. Preserve the existing native observation structure and ABI - version. An older consumer that only understands NTFS must continue to fail - closed when it encounters ReFS. -- Reuse the existing handle-relative implementation rather than adding a second - filesystem backend. Do not add an environment override or a fallback that - bypasses source admission, private DACLs, stable file identity, reparse - rejection, immutable snapshots or owned cleanup. -- Extend the independent Windows verifier fixture to report volume semantics, - and make the real native verifier check source, runtime and snapshot - filesystem identities against that independent observation. -- Run the complete native conformance lane on NTFS and ReFS at the same revision, - including DACL readback, source replacement denial, unrelated sibling rename, - ancestor reparse denial, snapshot digest/cancellation and cleanup containment. - Run the complete real Windows Ghidra lane on ReFS and repeat it on NTFS. -- Update the Windows native build guide, Windows Ghidra P0 limitations, recovery - guidance and verifier reports to say fixed local NTFS/ReFS only. Preserve all - unrelated NTFS documentation and claims. - -## Acceptance - -Focused TypeScript tests accept NTFS and ReFS identities and reject unsupported -filesystem values. The native build produces the Windows x64 artifact through -the existing Linux/MinGW lane with Node 24.22.1, and generated artifacts remain -uncommitted. - -The same revision passes the complete native verifier on both filesystems and -the real Windows Ghidra verifier on both filesystems. Source and snapshot -filesystem identities are observed independently rather than asserted only from -REA's own output. Relevant source, boundary, documentation, artifact and package -checks pass; any unrun or failed check is reported explicitly and prevents a -complete-support claim. - -## Evidence already obtained - -A disposable independent Win32 probe, built with the WSL MinGW toolchain and run -without elevation, completed 24 checks on each filesystem. Both NTFS and ReFS -reported persistent ACLs; created and read back protected private DACLs; -provided stable 128-bit file IDs and final handle paths; denied source writes, -source replacement and ancestor replacement through sharing violations; allowed -an unrelated sibling rename; rejected conversion of a pinned nonempty ancestor -into a reparse point with `ERROR_DIR_NOT_EMPTY`; and removed junctions by handle -without modifying an external sentinel. The probe source, executable and owned -test directories were removed. These observations support feasibility but do -not replace the complete REA verification required above. - -## Out of scope - -- SMB, UNC, exFAT, FAT32 and other filesystems or namespace variants. -- Admitting reparse components, SUBST aliases, mounted-folder aliases or a - mutable-path/provider authority expansion. -- A separate ReFS backend, changed process-execution authority, Ghidra database - mutation, or a native ABI version/structure change. -- Weakening a failing assertion or omitting a required verification lane to make - ReFS appear supported. -- Marking the upstream pull request ready on behalf of the human owner or - merging it. diff --git a/docs/specs/native/windows-refs/tasks.md b/docs/specs/native/windows-refs/tasks.md deleted file mode 100644 index 8f287d9bd1..0000000000 --- a/docs/specs/native/windows-refs/tasks.md +++ /dev/null @@ -1,11 +0,0 @@ -# Tasks - -- [x] Confirm the upstream NTFS-only boundary, record the approved feature - specification and validate the disposable Win32 feasibility probe. -- [x] Extend the filesystem identity contract with focused failing/passing tests. -- [x] Implement shared native NTFS/ReFS admission and owner-bound identity; - verify it with the independent volume observer and full native lanes. -- [x] Update capability declarations, diagnostics and owning documentation. -- [x] Complete final source, documentation, artifact, package, native, Ghidra and - original ReFS CLI verification on the same revision. -- [x] Review and synchronize the branch, then create a Draft PR linked to #289. diff --git a/docs/specs/native/windows-shortcut/plan.md b/docs/specs/native/windows-shortcut/plan.md deleted file mode 100644 index ad065f5a3a..0000000000 --- a/docs/specs/native/windows-shortcut/plan.md +++ /dev/null @@ -1,38 +0,0 @@ -# Implementation plan - -## Boundary and contract - -Follow the existing binary-diagnostics inspectors. `parseWindowsShortcut` in -`src/native/windows/WindowsShortcutParser.ts` owns Shell Link bytes and -coverage; `src/domain/native/windowsShortcut.ts` owns the result schema. -`WindowsShortcutProvider` (`rea-windows-shortcut`, built in) owns path -validation and the stable regular-file read through `readStableArtifact` and -`ArtifactResourceScope`. `WindowsShortcutService` owns Evidence provenance with -`subject.identity.format: "file"`. The CLI command and MCP tool consume that Evidence -and add no interpretation. - -ANSI strings use a byte-preserving Latin1 projection because the original -system code page is not observable from the file. `IsUnicode` selects -UTF-16LE. Missing optional sections are reported as observed absence only. - -## Incremental work and validation - -1. Define the contract, limits and observations; add failing parser fixtures. -2. Implement the parser for the header, IDList, LinkInfo, StringData and - ExtraData with budgets and partial coverage. -3. Add the provider, service, composition, capability declaration and tool - effects; cover cancellation, symlink rejection and finalization cleanup. -4. Add the CLI command and MCP tool; cover acceptance and advertisement. -5. Update the guide, CLI page, README rows and the authored skill; run focused - tests, repository checks and the documentation route build. - -## Effects and compatibility - -The workflow reads one caller-selected local file. It adds no target execution, -injection, mutation, protection recovery or network access, so no maintainer -scope decision is required. Existing tools and `inspect_artifact` routing are -unchanged. - -## References - -- https://learn.microsoft.com/en-us/openspecs/windows_protocols/ms-shllink/ diff --git a/docs/specs/native/windows-shortcut/spec.md b/docs/specs/native/windows-shortcut/spec.md deleted file mode 100644 index 41eacbb3a5..0000000000 --- a/docs/specs/native/windows-shortcut/spec.md +++ /dev/null @@ -1,55 +0,0 @@ -# Windows Shell Link shortcut inspection - -This specification records an implementation increment and its original problem -statement. For current behavior and limitations, see the -[current guide](../../../guides/native/windows-shortcut.md). - -## Problem and outcome - -REA has no Shell Link reader. An analyst holding a local `.lnk` file cannot ask -which target, arguments, working directory, icon location, volume or network -names, and ExtraData blocks it records without resolving the target, calling -COM or using a Windows host. Add one static inspector that reads a selected -local file and returns those facts as inline Evidence. - -## Requirements - -- Add `inspect_windows_shortcut` (MCP) and `inspect-windows-shortcut` (CLI). - MCP requires an absolute path; the CLI resolves a relative path against the - caller's working directory. -- Accept only a regular file. Reject symbolic links, UNC and other - host-prefixed device paths before any filesystem call, and on Windows a path - whose parent is a symbolic link or junction. -- Validate the 76-byte `ShellLinkHeader` (`HeaderSize` `0x4C` and the Shell - Link CLSID) and decode `LinkFlags`, `FileAttributes`, FILETIMEs, file size, - icon index, `ShowCommand` and hotkey. -- Decode `LinkTargetIDList` items whose layouts match documented shell-item - headers; keep every other item raw with a SHA-256 of its payload. -- Decode `LinkInfo` volume and network names, `StringData` per `LinkFlags`, and - enumerate every ExtraData block. Unknown signatures stay raw with SHA-256. - Tracker version-1 MAC and timestamp values are labelled derived. -- Emit only documented-field observations: argument presence and length, - target extension, minimized `ShowCommand`, and whether the icon location - differs from a recorded full target path (`null` when not comparable). -- Bound file size, IDList items, ExtraData blocks and retained string bytes, - with caller-adjustable limits and documented maximums. Honor cancellation. -- Never open, resolve or execute the link target, call COM or contact a network - for a local-volume path. - -## Acceptance - -Synthesized fixtures cover a hidden-window PowerShell shortcut with an icon -mismatch, network-share `LinkInfo`, Tracker version 1, ANSI strings, truncated -`StringData`, an unknown ExtraData signature and a wrong CLSID. Malformed -headers and exhausted budgets fail without partial success; truncation after a -valid header returns partial coverage with `coverage.failing_offset`, and -coverage is never `complete` when issues are present. CLI and stdio MCP -acceptance, MCP advertisement, filesystem symlink, budget and cancellation -boundaries, stable-artifact consumers and native acquisition finalization are -covered. - -## Out of scope - -Resolving or launching the target, COM `IShellLink` calls, Windows SDK use, -recovering the original system ANSI code page, verdicts about intent, and -routing `.lnk` files through `inspect_artifact`. diff --git a/docs/specs/native/windows-shortcut/tasks.md b/docs/specs/native/windows-shortcut/tasks.md deleted file mode 100644 index 17fd7ce6ad..0000000000 --- a/docs/specs/native/windows-shortcut/tasks.md +++ /dev/null @@ -1,11 +0,0 @@ -# Tasks - -- [x] Define the single-feature scope, contract, limits and plan. -- [x] Parse the header, IDList, LinkInfo, StringData and ExtraData with - synthesized fixtures, budgets and partial coverage. -- [x] Add the provider, service and Evidence provenance; verify symlink, UNC, - budget, cancellation and finalization boundaries. -- [x] Add the CLI command and MCP tool; verify acceptance and advertisement. -- [x] Document the workflow in the native Windows shortcut guide. -- [ ] Verify against real Explorer-written `.lnk` files and non-Latin1 system - ANSI code pages. diff --git a/docs/specs/solidity/cbor-metadata/plan.md b/docs/specs/solidity/cbor-metadata/plan.md deleted file mode 100644 index 04b601b668..0000000000 --- a/docs/specs/solidity/cbor-metadata/plan.md +++ /dev/null @@ -1,33 +0,0 @@ -# Implementation plan - -1. Use cborg 6.1.3 (Apache-2.0) as a pinned format decoder, with a bounded - tokenizer at its owning adapter boundary. Decode maps as Map, preserve integer - precision and strictly validate emitted text bytes before conversion. -2. Add the portable metadata-result schema in src/domain/evm/. Use exact byte - ranges into the already retained bytecode rather than copying an opaque CBOR - hex payload into every selected summary. -3. Add src/evm/SolidityMetadata.ts to interpret the terminal length/root-map - candidate. Return unavailable, decoded, partial or not-decoded facts; keep - unsupported nested values explicit instead of recursively expanding them. -4. Compute the facts in EvmoleInterfaceWorker from its selected bytes. The host - provider validates ranges/identity and projects the additive metadata field. - Preserve raw engine output without rewriting its unknown-precision metadata. -5. Ensure the canonical EVM bytecode shape carries the optional field into complete - and summary Evidence. Include decoding profile, coverage and limitations. -6. Add producer, worker, historical contract and public MCP boundary coverage. - Compile an owned Solidity fixture with a pinned caller-supplied solc module, - and verify its CBOR compiler version. Run relevant static/architecture checks. -7. Extend the existing real Linux CLI/MCP verifier with independent metadata - assertions. Run the compiler-setting matrix in its CI lane and classify its - verifier as EVM-owned, with a production CI-planner regression. - -No new execution provider or target authority is introduced: a format parser is -added inside the existing EVM worker. Linux x64 provider admission, target-free -semantics, cleanup, limits and complete original Evidence remain unchanged. -No metadata JSON or source URL is automatically acquired. - -The parser bounds nesting to 64 and token/collection growth to the selected -terminal payload's byte count (the format's terminal length is at most 65535). -Every data item consumes encoded bytes; broad declared collection lengths cannot -justify allocation without that lower bound. Expanded results still pass the -worker's existing 16 MiB output check. diff --git a/docs/specs/solidity/cbor-metadata/spec.md b/docs/specs/solidity/cbor-metadata/spec.md deleted file mode 100644 index ea08dcc904..0000000000 --- a/docs/specs/solidity/cbor-metadata/spec.md +++ /dev/null @@ -1,43 +0,0 @@ -# Solidity terminal metadata inspection - -Issue: https://github.com/morluto/rea/issues/2388 - -## Outcome - -The existing EVM interface operation should retain independently decoded terminal -CBOR candidate facts from the exact selected bytes instead of relying on precision -unknowns in the engine's reported metadata. This increment covers trailer ranges, -bounded decoding, exact integer/non-text scalar key evidence and compiler-version -representations. - -## Requirements - -- Preserve the existing carrier/decoded identities and original full bytecode. -- Report a plausible terminal root-map candidate separately from proof of Solidity - origin. Missing or non-map trailers remain unavailable, not proven absent. -- Interpret scalar root-map keys/values losslessly: integers as decimal strings, - bytes as hex, strings, booleans and null. Preserve undecoded/unsupported values - through the original bytecode plus exact candidate offset/length. -- Report partial and not-decoded coverage, parser/profile failures and unsupported - CBOR forms explicitly. Do not silently coerce unknown keys into object properties. -- Interpret admitted solc release/prerelease representations only from observed - entries; preserve ambiguity if duplicate compiler-version keys occur. -- Keep the additive field compatible with historical Evidence and retain - it through selected summary delivery and public CLI/MCP. - Historical omission parses as a null unknown facet without mutating the source. -- Bound nesting before decoder recursion and collection lengths before allocation. - Keep parsing inside the existing owned worker and its resource/output budgets. -- Do not fetch metadata or source content, contact RPC or execute contract code. - -## Acceptance and limits - -Owned compiler fixtures and malformed/synthetic trailers cover integers beyond -Number precision, non-text keys, nested/uninterpreted values, invalid UTF-8, -invalid lengths, unsupported tags and nesting bounds. Public boundary tests -preserve the field and older omission. A real pinned solc artifact verifies actual -metadata facts; the existing Linux-only EVM host profile remains unchanged. - -## Deferred issue criteria - -Binding a supplied metadata JSON to IPFS/Swarm commitments is a later independent -increment of #2388. This PR must reference rather than close the whole issue. diff --git a/docs/specs/solidity/cbor-metadata/tasks.md b/docs/specs/solidity/cbor-metadata/tasks.md deleted file mode 100644 index e80aefa01d..0000000000 --- a/docs/specs/solidity/cbor-metadata/tasks.md +++ /dev/null @@ -1,8 +0,0 @@ -# Tasks - -- [x] Define single-feature requirements and implementation plan before code. -- [x] Add the pinned decoder and bounded owner boundary. -- [x] Implement lossless scalar metadata facts and compiler-version evidence. -- [x] Integrate worker/provider contracts and summary/historical compatibility. -- [x] Verify producer, worker and public boundary behavior with owned fixtures. -- [x] Run relevant repository checks and prepare a separately scoped PR. diff --git a/docs/specs/solidity/cbor-metadata/verification.md b/docs/specs/solidity/cbor-metadata/verification.md deleted file mode 100644 index dae558d945..0000000000 --- a/docs/specs/solidity/cbor-metadata/verification.md +++ /dev/null @@ -1,43 +0,0 @@ -# Verification - -After integrating upstream c462a4ebd, 47 tests passed -across the parser, domain contract, application service, compiled worker and MCP -boundary (five files). Compiled-worker goldens include BOM text, partial nested -values, unavailable trailers, malformed UTF-8 and unsupported floats. Five -upstream adapter tests also passed after its stricter integer validation landed. -All six static tasks and architecture guards -passed. After integration, test discovery found all 1004 files exactly once. -The CI-planner selection passed all 85 tests, including the new EVM-verifier case. - -The parser regressions cover exact large integers and typed keys, malformed UTF-8, -duplicate keys, excessive nesting, unsupported tags/floats, length bounds and -historical omission. A real defect in the decoder's default text handling removed -an initial U+FEFF. The owning tokenizer now validates and decodes the retained -text bytes with BOM preservation; independent fixtures check both values and -compiler-key identity. - -The owned fixture was compiled with caller-selected solc 0.8.30, using unoptimized, -optimized via-IR, content-hash-free and CBOR-free settings. All four metadata -checks passed again after integration. No contract was executed. Local first decode -took approximately 0.81 ms or less. The originally reported approximately 2.92 ms -for 100 warm iterations included equality assertions and is not a decode-only -measurement. The verifier now measures parsing separately from those assertions; -updated warm timings have not been collected. These historical figures describe -these fixtures and this host, not a general workload. -Peak process RSS -included the compiler (299536 KiB); complete process-family CPU/memory and agent -token costs were not measured. - -Compiled worker tests exercise unchanged EVMole WASM on this macOS host. MCP tests -use the production server and contracts with an injected provider seam. The full -Linux-only provider CLI/MCP, resource-limit and cleanup lane remains unverified -here. Metadata JSON commitment binding remains deferred under issue #2388. - -The Linux CLI/MCP verifier asserts exact compiler bytes, declared version and -candidate ranges for its existing owned raw/hex artifacts. Its CI lane additionally -runs the new compiler-setting matrix. A regression using the actual CI planner -checks that edits to the new verifier select the EVM lane. - -The later merge/review correction adds decoded-summary and omitted historical -metadata coverage. Tests and provider reruns for that correction were skipped at -the maintainer's request; the earlier runs above do not validate the changed head. diff --git a/docs/specs/v8/code-cache-inspection/plan.md b/docs/specs/v8/code-cache-inspection/plan.md deleted file mode 100644 index d780e5ad01..0000000000 --- a/docs/specs/v8/code-cache-inspection/plan.md +++ /dev/null @@ -1,40 +0,0 @@ -# Plan - -## Shape - -The container format is the only thing this feature knows, so the parser owns it and -everything else consumes its facts. - -- `src/domain/v8/v8CodeCache.ts` holds the schema, the bit constants and the bounds, so a - reader and a test share one definition of what a container is. -- `src/v8/V8CodeCacheParser.ts` decodes a `Buffer` into retained strings and producer - facts. It is given bytes only; it never opens a file. -- `src/v8/V8CodeCacheProvider.ts` owns the observation budget, the file read and the - remediation text. It is the boundary that turns bytes into a reported fact. -- `src/cli/v8CodeCacheCommands.ts` and the MCP registration are thin adapters over the - provider, so both surfaces report the same facts. - -## Measured premises - -Each of these was measured on Node 24.22.1 before the parser was written, because the -container is undocumented and the layout had to be derived rather than assumed: - -- `vm.Script.createCachedData()` writes `0x…|length` for its producer word. -- `vm.compileFunction` sets `0x20000000`, and `vm.SourceTextModule` sets `0x40000000`. -- The payload retains UTF-8 strings above the threshold, and the retained set grows with - the source's literals rather than with the bytecode size. - -## Order - -1. Pin the format in the domain schema so later steps cannot disagree about it. -2. Write the parser against the measured producer words. -3. Add the provider, the budget and its remediation. -4. Expose the CLI command, then the MCP tool, over the same provider. -5. Document the command and the report, and link the guide from both indexes. - -## Budget - -The retained-string scan is the only unbounded part of the read, so it is bounded on three -axes at once: a maximum string count, a minimum string length, and a maximum artifact size. -The provider reports which of the three was reached and whether raising or lowering it is -the caller's next step, so a refusal is actionable rather than a bare truncation. diff --git a/docs/specs/v8/code-cache-inspection/spec.md b/docs/specs/v8/code-cache-inspection/spec.md deleted file mode 100644 index 8dbb879e9e..0000000000 --- a/docs/specs/v8/code-cache-inspection/spec.md +++ /dev/null @@ -1,60 +0,0 @@ -# Inspect a V8 code cache container - -This specification records an implementation increment and its original problem -statement. For current behavior and limitations, see the -[current guide](../../../guides/javascript/v8-code-cache.md). - -## Outcome - -A bytenode `.jsc`, the bytes `vm.Script.createCachedData()` writes, and a code cache -carried inside a Node single-executable application or an Electron application are all -opaque today: the analysis reports the containing file and nothing about the cache. An -analyst has to install bytenode, guess a V8 version, and run the file to learn anything, -which executes attacker-controlled code and changes the state under study. - -`rea inspect-v8-code-cache [--minStringBytes ]` reads one explicitly selected -container as static bytes and reports its producer, the strings it retains above a -threshold, and the recoverable source metadata, without executing the file, starting a -V8 runtime, installing bytenode, or invoking a decompiler. The same facts are available -through the `inspect_v8_code_cache` MCP tool. - -## Requirements - -- The reader accepts a file whose first words describe a V8 code cache header; anything - else is refused before the payload is walked, so an unrelated file cannot be read as a - cache by accident. -- The producer is decided from the header's producer bits, not from the file extension: - a module bit means `vm.SourceTextModule`, a compile-function bit means - `vm.compileFunction`, and neither bit means `unknown`. The unflagged case is not - `vm.Script` by inference — whether V8 marks a function cache is a build detail. A - `vm.compileFunction` cache reads `0x20000004` for a 4-unit source on Node 24.22.1 and - `0x00000004` on Node 22.23.4, so an unflagged word could be either producer. The - observed word stays in `header.fields` for a caller that trusts a specific build - fingerprint. -- Retained strings are reported above the caller's byte threshold, with - `--minStringBytes` bounded so a pathological threshold cannot make the read unbounded. -- Observation is bounded by a budget that reports which bound it hit and how to raise it, - rather than silently truncating. -- The container's file location is reported as given, and the payload is never written - back or repaired. - -## Non-goals - -- Decoding the payload back into source. The container's bytecode is version-specific and - the tool does not attempt to reconstruct source from it. -- Executing the container to obtain runtime facts. -- Recognising an encrypted or compressed wrapper around a cache. - -## Verification - -- The `vm.Script` producer word and its retained strings come from output this suite - generates through `vm.Script.createCachedData()`, and the `vm.compileFunction` case - compiles through `vm.compileFunction` for the same reason. -- The `vm.SourceTextModule` producer bit is checked by setting the measured bit on a real - `vm.Script` cache rather than by compiling through `vm.SourceTextModule`, so that case - covers the bit's meaning and not a cache from that producer. -- The CLI, MCP, absolute-path and decimal-argument boundary contracts have their own - tests. -- Budget tests pin the structured exhaustion facts and verify that recovery only - recommends admitted changes. When both options are at their ceilings, the - recovery directs the caller to a smaller artifact. diff --git a/docs/specs/v8/code-cache-inspection/tasks.md b/docs/specs/v8/code-cache-inspection/tasks.md deleted file mode 100644 index dd509ccb6f..0000000000 --- a/docs/specs/v8/code-cache-inspection/tasks.md +++ /dev/null @@ -1,14 +0,0 @@ -# Tasks - -- [x] Record the outcome, requirements and non-goals. -- [x] Measure the producer words and the retained-string layout on Node 24.22.1. -- [x] Add the domain schema, the bit constants and the observation bounds. -- [x] Add the parser, reading the payload by index into the integer table. -- [x] Add the provider with the budget and its remediation. -- [x] Add the CLI command and register the MCP tool over the same provider. -- [x] Document the command, the report and the bounds. -- [x] Link the guide from `docs/README.md` and the VitePress index. -- [x] Add parser, CLI, MCP, absolute-path and decimal-argument tests. -- [x] Hold the budget advice to the recovery struct rather than to its wording. -- [x] Run the static, formatting, duplication, documentation and test gates. -- [x] Address the independent review. diff --git a/docs/specs/web/historical-capture-budgets/plan.md b/docs/specs/web/historical-capture-budgets/plan.md deleted file mode 100644 index 152f7216b1..0000000000 --- a/docs/specs/web/historical-capture-budgets/plan.md +++ /dev/null @@ -1,5 +0,0 @@ -# Implementation plan - -1. Declare caller budgets in the domain input and derive one immutable provider policy with existing defaults. -2. Carry that policy in private child requests and scope all parser/read/reply consumers to it without global mutable state. -3. Update exact recovery, CLI controls and Evidence parameters; verify selected-budget recovery and default regressions. diff --git a/docs/specs/web/historical-capture-budgets/spec.md b/docs/specs/web/historical-capture-budgets/spec.md deleted file mode 100644 index fb89865775..0000000000 --- a/docs/specs/web/historical-capture-budgets/spec.md +++ /dev/null @@ -1,9 +0,0 @@ -# Historical capture admission budgets - -Allow an analyst to inspect the same retained HAR, SAZ, qlog or native mitmproxy capture after explicitly increasing an exhausted input, reply or nesting budget. Keep existing defaults, producer identity, sensitive-value handling and complete-or-failure semantics. - -The public contract accepts positive safe-integer `max_input_bytes` and `max_reply_bytes`, and `max_nesting_depth` up to REA's JSON representation depth minus the four enclosing record/reply/Evidence levels (996). Selected values apply to the admitted operation and its child decoder, source and reply readers, archive expansion and protobuf interpretation. They do not raise the separately owned worker heap, CPU or client transport limits. - -Failures name the exhausted parameter and value and the next-call repair. Omitted values retain 32 MiB input, 96 MiB reply and 64 nesting levels. Evidence preserves explicit selections and omission. - -Acceptance: the same valid capture rejected by a deliberately small selected budget succeeds after changing only that budget. A malformed control remains malformed. The child and parent enforce the same selected facts, and parallel operations keep distinct policies. diff --git a/docs/specs/web/historical-capture-budgets/tasks.md b/docs/specs/web/historical-capture-budgets/tasks.md deleted file mode 100644 index cdd84131db..0000000000 --- a/docs/specs/web/historical-capture-budgets/tasks.md +++ /dev/null @@ -1,6 +0,0 @@ -# Tasks - -- [x] Add input contracts and canonical policy selection. -- [x] Connect parent, Node/Python decoder, archive and protobuf boundaries. -- [x] Expose CLI controls and preserve request provenance. -- [x] Verify same-input recovery, malformed controls and parser regressions. diff --git a/docs/specs/web/source-map-budget-recovery/plan.md b/docs/specs/web/source-map-budget-recovery/plan.md deleted file mode 100644 index bdbac1aa96..0000000000 --- a/docs/specs/web/source-map-budget-recovery/plan.md +++ /dev/null @@ -1,9 +0,0 @@ -# Plan - -Use one domain policy and schema for defaults, selection and recovery. Publish -local and fetch projections that reject fields their path does not consume. -Thread selected values through existing acquisition/codec/process/format owners, -including independently validated child request budgets. CLI exposes named -numeric options and MCP derives its inputs from canonical source contracts. -Existing guides own product behavior. Verify finite budget recovery through -production boundaries and the public CLI; keep resource/lifecycle regressions. diff --git a/docs/specs/web/source-map-budget-recovery/spec.md b/docs/specs/web/source-map-budget-recovery/spec.md deleted file mode 100644 index e428cc925e..0000000000 --- a/docs/specs/web/source-map-budget-recovery/spec.md +++ /dev/null @@ -1,34 +0,0 @@ -# Per-call source-map budget recovery - -## Problem - -Local tracing and bundle source-map collection discard or refuse useful facts -at independent fixed byte, structural and codec-heap ceilings. A longer timeout -cannot admit the same map. Related: #6176, #8434, #8978. - -## Requirements - -- Preserve defaults unless representative calibration justifies a change; - preserve selected artifact identities, source declarations, - unknown coverage and cleanup ownership. -- Admit explicit bounded per-call budgets at the producing owners, and propagate - the same policy through acquisition, structural preflight, codec child and - complete request/reply checks. -- Reject inapplicable fields; preserve omission in Evidence parameters. -- Explain the exact exhausted control, effective value, range, application point - and recovery. Retain real representation and client constraints. -- Keep upstream decoding unchanged and preflight rows/segments before allocation. - -## Acceptance - -A valid local map fails at an explicitly lowered admission, names map_bytes, -and succeeds for the same point through the public CLI after increasing that -budget. The 8 MiB default admits a complete map above 4 MiB while -preserving an explicit smaller selection. -A finite fetched map similarly recovers after increasing decoded_records. -Malformed maps, cancellation and failed cleanup retain their existing semantics. - -## Non-goals - -No source fetching beyond existing origin authority, application execution, -implicit retries, unbounded allocation or change to client deadlines. diff --git a/docs/specs/web/source-map-budget-recovery/tasks.md b/docs/specs/web/source-map-budget-recovery/tasks.md deleted file mode 100644 index 5259b503f1..0000000000 --- a/docs/specs/web/source-map-budget-recovery/tasks.md +++ /dev/null @@ -1,10 +0,0 @@ -# Tasks - -- [x] Define shared source-map policy with existing defaults and typed selections. -- [x] Propagate local budgets through acquisition, service, codec and process owner. -- [x] Propagate fetched response, record and representation budgets. -- [x] Expose exact CLI/MCP contracts and actionable recovery. -- [x] Add finite structural/fetch and public large-map recovery regressions. -- [x] Update source-location and browser guides. -- [x] Run compiled CLI/codec recovery and coordinated type/lint/documentation gates. -- [x] Calibrate local map admission against shipped maps; retain other budgets. diff --git a/docs/verification/browser-saved-values-2026-10-26.md b/docs/verification/browser-saved-values-2026-10-26.md index 925d863907..d1da9c3061 100644 --- a/docs/verification/browser-saved-values-2026-10-26.md +++ b/docs/verification/browser-saved-values-2026-10-26.md @@ -22,7 +22,7 @@ and subsequent fixes through `9f5191ab0` were compared. Its query redaction and pinning were incorporated. Existing heap-derived URL/JSON/envelope admission remains the owner of expansion bounds, rather than adding the upstream fixed fill ceiling. Original multi-app/model -results are [attributed historical evidence](../specs/agent-environments/scenario-saved-values/verification.md), +results are [attributed historical evidence](https://github.com/morluto/rea/blob/3fcbabe593611435ebc26e1eac86706fe60abb6e/docs/specs/agent-environments/scenario-saved-values/verification.md), not executions performed here. ## Real application and correctness oracles diff --git a/scripts/lib/docs-facts.mjs b/scripts/lib/docs-facts.mjs index 1ebfb9b622..983bbc1f1c 100644 --- a/scripts/lib/docs-facts.mjs +++ b/scripts/lib/docs-facts.mjs @@ -94,8 +94,7 @@ export const skillReferenceIssues = async (skillRoot) => { }; // Living prose that would restate the catalog size. Dated records keep the -// count they measured: release notes, feature specs, verification records and -// decision records describe a past build. +// count they measured in release notes and verification records. export const LIVING_PROSE_ROOTS = [ "README.md", "CONTRIBUTING.md", @@ -104,8 +103,7 @@ export const LIVING_PROSE_ROOTS = [ ".agents/skills", "website/public", ]; -const SKIPPED_PROSE = - /^docs\/(?:releases|specs|verification|adr|\.vitepress\/dist)\//u; +const SKIPPED_PROSE = /^docs\/(?:releases|verification|\.vitepress\/dist)\//u; const PROSE_FILE = /\.(?:md|html)$/u; // A count of ten or more tools, such as "240 tools" or "all 1,024 MCP tools". const LITERAL_TOOL_COUNT = diff --git a/scripts/lib/module-layers.mjs b/scripts/lib/module-layers.mjs index 7709b8b2a0..4bd16a97fd 100644 --- a/scripts/lib/module-layers.mjs +++ b/scripts/lib/module-layers.mjs @@ -4,13 +4,9 @@ * layer. An undeclared unit fails the check, so a new directory must choose * its layer when it is added. * - * The order follows docs/architecture/architecture.mermaid: the dependency-free - * kernel helpers that every layer may use, domain and - * contracts at the centre, the process/filesystem foundation, the ports - * that providers implement and application consumes, the shared provider - * core (src/providers), provider adapters, - * shared application workflows, production composition, then the CLI and - * MCP entry points. + * The order starts with dependency-free kernel helpers that every layer may + * use, then the domain, contracts, process/filesystem foundation, and ports. + * Providers implement the ports and application workflows consume them. */ export const LAYER_ORDER = Object.freeze([ "kernel", diff --git a/scripts/verify-documentation-routes.mjs b/scripts/verify-documentation-routes.mjs index a4e41f18f8..240890cd8c 100644 --- a/scripts/verify-documentation-routes.mjs +++ b/scripts/verify-documentation-routes.mjs @@ -15,7 +15,7 @@ javascript-application-graph javascript-application-workflows javascript-artifac javascript-recovery javascript-runtime-observation javascript-runtime-reconciliation jeb-analysis managed-code-analysis mcp-contracts mcp-prompts migration-6.2 native-investigation packet-captures pcap-analysis process-capture raw-binary reconstruction-obligation-ledgers -reconstruction-readiness recorded-crashes releasing roadmap signal-recordings sqlite-databases +reconstruction-readiness recorded-crashes releasing signal-recordings sqlite-databases testing tool-design wasm-artifacts web-network-captures web-runtime web-source-location website-module-trace website-script-export windows-ghidra-p0 binary-hardening desktop-application-capture desktop-application-export desktop-application-state @@ -24,7 +24,7 @@ design/limits-and-recovery ` .trim() .split(/\s+/u); -assert.equal(routes.length, 67); +assert.equal(routes.length, 66); assert.equal(new Set(routes).size, routes.length); const documentation = resolve( @@ -36,7 +36,7 @@ const checked = new Set(); let internalTargets = 0; let sourceLinks = 0; // Legacy public routes remain an independent baseline; all generated pages also -// participate so newly authored directories/specifications cannot escape checks. +// participate so newly authored guides cannot escape checks. for (const route of routes) { const html = await readFile(resolve(output, route + ".html"), "utf8"); const edit = physicalEditSource(html, route); diff --git a/scripts/verify/architecture-guards.mjs b/scripts/verify/architecture-guards.mjs index c41634fbf9..927fb95a45 100644 --- a/scripts/verify/architecture-guards.mjs +++ b/scripts/verify/architecture-guards.mjs @@ -93,7 +93,6 @@ check( check("NUL-joined list key (use compositeKey)", files, /\.join\(["']\\0["']\)/); -// Pushed effect invalidation (docs/adr/javascript/pushed-effect-invalidation.md). // Opaque-effect checks are private to javascriptSemanticEffectLog.ts, so the // compiler keeps readers on its questions, and only the log and its record // module read the recorded sites. A method read on an intrinsic @@ -290,9 +289,9 @@ check( ], ); -// Native inventory results parse once against their named fact contract -// (docs/adr/native/typed-operation-facts.md). Hopper's reply table and the -// advertised output schemas own their own protocol and catalog contracts. +// Native inventory results parse once against their named fact contract. +// Hopper's reply table and the advertised output schemas own their protocol +// and catalog contracts. check( "native inventory rows parsed outside their fact contract (use executeFact or a contract from src/domain/native/nativeOperationFacts)", files, @@ -396,7 +395,6 @@ checkCounted( ["src/process/capturedProviderOutput.ts"], ); -// Pushed effect invalidation (docs/adr/javascript/pushed-effect-invalidation.md). // Recorded effects belong to the effect log. A reader that reads an effect // index itself decides on its own which effect kinds and proofs apply; readers // ask the log instead. Every reader has moved; the remaining counts are the diff --git a/scripts/verify/rea-numeric-limits.mjs b/scripts/verify/rea-numeric-limits.mjs index 95897bed6d..a2a0d31d41 100644 --- a/scripts/verify/rea-numeric-limits.mjs +++ b/scripts/verify/rea-numeric-limits.mjs @@ -8,7 +8,7 @@ import ts from "typescript6"; // reported separately and are not verified by this Node-only scan. // Per-call limits belong to ANALYSIS_SETTINGS. // A name in REQUIRED_RUNTIME_LIMITS that is absent from source fails closed. -// Each default, floor, and maximum in docs/design/rea-limit-inventory.md must +// Each default, floor, and maximum in docs/reference/rea-limit-inventory.md must // equal ANALYSIS_SETTINGS or the owner export the parser enforces. const root = fileURLToPath(new URL("../../", import.meta.url)); @@ -949,7 +949,7 @@ export const parseDocumentedNumericLimits = (markdown) => { const heading = lines.findIndex((line) => line.trim() === `## ${title}`); if (heading < 0) throw new Error( - `docs/design/rea-limit-inventory.md is missing "## ${title}"`, + `docs/reference/rea-limit-inventory.md is missing "## ${title}"`, ); let index = heading + 1; while (index < lines.length && !lines[index].startsWith("|")) { @@ -1092,7 +1092,7 @@ export const compareDocumentedNumericLimits = (rows, bounds, names) => { ? `${bound.name} (${bound.aliases.join(", ")})` : bound.name; failures.push( - `${label}: code exports default ${showLimitValue(bound.defaultValue)}, floor ${showLimitValue(bound.minimum)}, maximum ${showLimitValue(bound.maximum)}, but docs/design/rea-limit-inventory.md has no row`, + `${label}: code exports default ${showLimitValue(bound.defaultValue)}, floor ${showLimitValue(bound.minimum)}, maximum ${showLimitValue(bound.maximum)}, but docs/reference/rea-limit-inventory.md has no row`, ); } return failures; @@ -1373,7 +1373,7 @@ if (direct) { )) { if (!runtime.has(name) && !listed.has(name)) failures.push( - `${name} in ${file.path} is neither an analysis setting nor docs/design/rea-limit-inventory.md via src/domain/numericLimitRegistry.ts`, + `${name} in ${file.path} is neither an analysis setting nor docs/reference/rea-limit-inventory.md via src/domain/numericLimitRegistry.ts`, ); } for (const name of listed.keys()) { @@ -1453,7 +1453,7 @@ if (direct) { if (checkout) { try { const inventory = await readFile( - join(root, "docs/design/rea-limit-inventory.md"), + join(root, "docs/reference/rea-limit-inventory.md"), "utf8", ); const exported = await loadExportedNumericLimitBounds(); diff --git a/src/domain/evidenceFormat.ts b/src/domain/evidenceFormat.ts index 76167a6168..06317ac33a 100644 --- a/src/domain/evidenceFormat.ts +++ b/src/domain/evidenceFormat.ts @@ -18,7 +18,7 @@ import { ParseFailureError, unsupportedInput } from "./parseFailure.js"; * summary identities are no longer rebuilt. * * Revision 2: the Evidence subject names its target identity - * (`subject.identity`, docs/adr/evidence/target-identity.md). The Evidence ID + * (`subject.identity`). The Evidence ID * commits to that identity, including its kind and selection, instead of the * subject's digest, format and architecture, so every Evidence ID changes. * Each record also declares `evidence_format`, so a standalone record names diff --git a/src/domain/javascript/javascriptSemanticEffectLog.ts b/src/domain/javascript/javascriptSemanticEffectLog.ts index 0ae011fc1d..280d2fb036 100644 --- a/src/domain/javascript/javascriptSemanticEffectLog.ts +++ b/src/domain/javascript/javascriptSemanticEffectLog.ts @@ -1,6 +1,6 @@ /** * The effect log: one owner of the questions readers ask about recorded - * effects (docs/adr/javascript/pushed-effect-invalidation.md). Readers ask + * effects. Readers ask * whether a read may observe an effect; the timing, capture and path proofs * stay here. Recorded opaque sites live in javascriptSemanticEffectRecord.ts. */ diff --git a/src/domain/javascript/javascriptSemanticEffectRecord.ts b/src/domain/javascript/javascriptSemanticEffectRecord.ts index f28d019963..d45667307c 100644 --- a/src/domain/javascript/javascriptSemanticEffectRecord.ts +++ b/src/domain/javascript/javascriptSemanticEffectRecord.ts @@ -8,8 +8,7 @@ import type { * Storage of the opaque effects (`eval`, `Function`) recorded for one source. * Only this module and the effect log (javascriptSemanticEffectLog.ts) read * the recorded sites; the timing producer, which the effect log builds on, - * asks the accessors below - * (docs/adr/javascript/pushed-effect-invalidation.md). + * asks the accessors below. */ export const createSemanticOpaqueEffects = (): JavaScriptOpaqueScopeEffects => ({ diff --git a/src/domain/numericLimitRegistry.test.ts b/src/domain/numericLimitRegistry.test.ts index 42e43d1262..08bccf4e91 100644 --- a/src/domain/numericLimitRegistry.test.ts +++ b/src/domain/numericLimitRegistry.test.ts @@ -5,7 +5,7 @@ import { ANALYSIS_SETTINGS } from "./analysisSettingDefinitions.js"; import { NUMERIC_LIMIT_REGISTRY } from "./numericLimitRegistry.js"; const inventory = readFileSync( - join(import.meta.dirname, "../../docs/design/rea-limit-inventory.md"), + join(import.meta.dirname, "../../docs/reference/rea-limit-inventory.md"), "utf8", ); diff --git a/src/domain/numericLimitRegistry.ts b/src/domain/numericLimitRegistry.ts index fb1d481c85..e44fc928b9 100644 --- a/src/domain/numericLimitRegistry.ts +++ b/src/domain/numericLimitRegistry.ts @@ -8,7 +8,7 @@ * checked on each call belong in `ANALYSIS_SETTINGS` instead of this list. * * Narrative bounds, owners, and the non-numeric settings live in - * `docs/design/rea-limit-inventory.md`. That same script compares each + * `docs/reference/rea-limit-inventory.md`. That same script compares each * documented default, floor, and maximum with the exported value. */ export interface NumericLimitRegistryEntry { diff --git a/src/domain/targetIdentity.ts b/src/domain/targetIdentity.ts index 9ae5e44a0d..2a73593e98 100644 --- a/src/domain/targetIdentity.ts +++ b/src/domain/targetIdentity.ts @@ -187,8 +187,7 @@ export interface SessionTargetIdentity { } /** - * What an observation or cache entry is about. Tagged by `kind`; see - * docs/adr/evidence/target-identity.md for the kinds later slices add. + * What an observation or cache entry is about. Tagged by `kind`. */ export type TargetIdentity = | FileTargetIdentity diff --git a/tests/evaluation/ciTestSelection.test.ts b/tests/evaluation/ciTestSelection.test.ts index e580c13e2d..08354512ca 100644 --- a/tests/evaluation/ciTestSelection.test.ts +++ b/tests/evaluation/ciTestSelection.test.ts @@ -119,8 +119,8 @@ it("lets checker-only inputs and prose select nothing by themselves", () => { const sources = { "src/domain/Value.test.ts": "", "tests/boundary/filesystem/docs.test.ts": 'read("docs/guide.md");', - "tests/boundary/filesystem/mermaid.test.ts": - 'read("docs/architecture/architecture.mermaid");', + "tests/boundary/filesystem/docsAsset.test.ts": + 'read("docs/assets/example.png");', "tests/boundary/filesystem/licenses.test.ts": 'read("licenses/npm-dependencies.txt"); read("LICENSE");', "tests/boundary/filesystem/issueTemplate.test.ts": @@ -146,9 +146,9 @@ it("lets checker-only inputs and prose select nothing by themselves", () => { expect(selectedFiles(plan(["docs/guide.md"], sources))).toEqual([ "tests/boundary/filesystem/docs.test.ts", ]); - expect( - selectedFiles(plan(["docs/architecture/architecture.mermaid"], sources)), - ).toEqual(["tests/boundary/filesystem/mermaid.test.ts"]); + expect(selectedFiles(plan(["docs/assets/example.png"], sources))).toEqual([ + "tests/boundary/filesystem/docsAsset.test.ts", + ]); expect( selectedFiles(plan(["licenses/npm-dependencies.txt"], sources)), ).toEqual(["tests/boundary/filesystem/licenses.test.ts"]); diff --git a/tests/evaluation/numericLimitCheck.test.ts b/tests/evaluation/numericLimitCheck.test.ts index f96fd9b9f8..9888d81267 100644 --- a/tests/evaluation/numericLimitCheck.test.ts +++ b/tests/evaluation/numericLimitCheck.test.ts @@ -642,7 +642,7 @@ it("names a documented limit the code does not export", () => { it("matches the inventory to the exported analysis settings and owner bounds", async () => { const inventory = await readFile( - new URL("../../docs/design/rea-limit-inventory.md", import.meta.url), + new URL("../../docs/reference/rea-limit-inventory.md", import.meta.url), "utf8", ); const exported = await loadExportedNumericLimitBounds();