[GH-ISSUE #267] Add approval-gated managed-runtime characterization #156

Closed
opened 2026-10-15 18:21:45 +00:00 by bsakaguchi · 0 comments
Owner

Originally created by @morluto on GitHub (Jul 16, 2026).
Original GitHub issue: https://github.com/morluto/rea/issues/267

Problem

Static JavaScript analysis cannot prove runtime module ownership, dynamically selected branches, closure behavior, computed imports, native bridges, or effect ordering. General process capture observes the outside of a process but cannot selectively characterize an internal managed-runtime boundary.

Agents currently compensate by patching formatted bundles to export internal functions, writing temporary harnesses, or attaching ad hoc Node Inspector scripts. Those approaches can lose artifact identity, execute more code than intended, omit cleanup proof, and produce results outside the evidence model.

Outcome

Add an approval-gated, provider-neutral managed-runtime characterization capability. The first provider should support Node.js and JavaScript bundles while keeping the public contract suitable for other managed runtimes.

The capability must bind every observation to an exact artifact digest, an explicit runtime and analysis profile, a finite characterization plan, and an owned contained environment.

Capability model

Support separate operations for:

  • inspect managed-runtime/package metadata without executing the target;
  • prepare a hash-bound characterization workspace;
  • expose selected internal functions or modules through reversible instrumentation;
  • invoke explicitly selected pure or bounded-effect callables with serialized fixtures;
  • observe module loading and export shape;
  • observe declared environment, filesystem, child-process, native-addon, WebAssembly, HTTP, WebSocket, Electron IPC, and timer boundaries;
  • attach through Node Inspector to an owned provider-launched process;
  • compare static semantic claims with controlled runtime observations;
  • export the resulting characterization as Evidence v2 and a reusable fixture.

Preparation and execution must be separate approval and policy decisions.

Exact-artifact instrumentation

When temporary instrumentation is required:

  • verify the source artifact digest before modification;
  • never modify the authoritative artifact in place;
  • copy into an owned temporary root;
  • apply a deterministic, reviewable transformation;
  • record original and instrumented digests plus exact inserted byte/AST locations;
  • preserve a transformation manifest and source map when feasible;
  • expose only explicitly named/hash-addressed targets;
  • reject ambiguous matches;
  • prove the authoritative artifact remained unchanged;
  • remove the instrumented workspace on every exit unless separately approved for export.

Instrumented execution is controlled-replay authority, not shipped-artifact authority. Results must cite both the shipped source evidence and transformation evidence.

Invocation contract

A characterization plan declares:

  • artifact, runtime, entrypoint, working directory, and isolated HOME;
  • selected module/function identity from semantic bundle evidence;
  • serialized arguments and expected serialization bounds;
  • allowed globals, modules, environment keys, roots, loopback endpoints, timers, and native boundaries;
  • maximum calls, processes, files, bytes, handles, duration, and idle time;
  • deterministic clock/randomness/ID policy;
  • secret aliases and redaction;
  • expected effect class: pure, declared bounded effects, or observation-only;
  • cancellation and cleanup requirements.

Unknown return values, thrown values, callbacks, promises, iterators, cyclic objects, functions, handles, and native objects require typed bounded projections. They must not be serialized through unsafe generic inspection.

Isolation and safety

  • Require explicit approval and a matching scoped policy grant.
  • Launch only provider-owned processes.
  • Default to no external network and loopback-only replay.
  • Never attach to unrelated or pre-existing processes.
  • Do not inherit arbitrary environment variables or credentials.
  • Block undeclared module, filesystem, child-process, native, and network boundaries.
  • Bound stdout, stderr, inspector messages, object graphs, source text, protocol bodies, and evidence.
  • Propagate cancellation and prove descendant, socket, timer, inspector, temporary-root, and instrumentation cleanup.
  • Clearly state that this is controlled observation, not a security sandbox, unless a real isolation provider supplies that property.

Evidence

Return:

  • shipped and instrumented artifact identities;
  • runtime/provider/version/profile identities;
  • transformation manifest and limitations;
  • selected callable identity and resolution proof;
  • ordered inputs, outputs, throws, effects, and boundary events;
  • process/environment/isolation identity;
  • completeness, truncation, cancellation, and cleanup;
  • static-to-runtime correlations labeled observation, derivation, or hypothesis;
  • residual unknowns and recommended next probes.

A successful call proves only the declared finite characterization claims, never global behavioral equivalence.

Failure model

Distinguish artifact mismatch, target ambiguity, transformation failure, runtime unavailable, policy denial, unsupported value, undeclared effect, boundary escape attempt, inspector disconnect, timeout, cancellation, truncation, target crash, descendant leak, cleanup failure, and incomplete observation.

Acceptance criteria

  • Provider-neutral contracts are independent of Node Inspector and any specific transformer.
  • A Node provider characterizes selected functions from plain, minified, and bundled fixtures.
  • Every run is bound to exact shipped and instrumented digests.
  • The authoritative artifact is never modified in place and is rehashed after execution.
  • Pure fixtures prove arguments, returns, throws, promises, and deterministic clock/randomness.
  • Bounded-effect fixtures prove module loads, files, children, loopback HTTP/WebSocket, native/Wasm boundary declarations, and cleanup.
  • Undeclared effects fail closed and remain visible.
  • Inspector attach is limited to an owned provider-launched process.
  • Cancellation and all resource-cleanup paths are exercised.
  • Static semantic evidence can be correlated without being promoted to runtime proof.
  • Large records are available through MCP resources.
  • CLI and MCP contracts, typed errors, progress, cancellation, and Tasks behavior are equivalent.
  • A temporary export-instrumentation fixture produces deterministic evidence twice and leaves the source tree byte-identical with no residual instrumented file.

Relationships

  • Parent dynamic-observation policy: #36
  • Static JavaScript semantics: #117 and #68
  • Managed-runtime provider roadmap: #42
  • Provider SDK: #45
  • Evidence resources: #99
  • Scoped approval grants: #96 and #114
  • Long-running work: #97 and #98
  • Fixture export: #62

Non-goals

  • Executing arbitrary bundles without approval.
  • Claiming instrumentation output is unmodified shipped behavior.
  • Attaching to unrelated user processes.
  • Providing a security boundary without a real sandbox or VM.
  • Recovering original names, comments, or source.
  • Replacing external process, browser, Electron, or native-binary observation.
Originally created by @morluto on GitHub (Jul 16, 2026). Original GitHub issue: https://github.com/morluto/rea/issues/267 ## Problem Static JavaScript analysis cannot prove runtime module ownership, dynamically selected branches, closure behavior, computed imports, native bridges, or effect ordering. General process capture observes the outside of a process but cannot selectively characterize an internal managed-runtime boundary. Agents currently compensate by patching formatted bundles to export internal functions, writing temporary harnesses, or attaching ad hoc Node Inspector scripts. Those approaches can lose artifact identity, execute more code than intended, omit cleanup proof, and produce results outside the evidence model. ## Outcome Add an approval-gated, provider-neutral managed-runtime characterization capability. The first provider should support Node.js and JavaScript bundles while keeping the public contract suitable for other managed runtimes. The capability must bind every observation to an exact artifact digest, an explicit runtime and analysis profile, a finite characterization plan, and an owned contained environment. ## Capability model Support separate operations for: - inspect managed-runtime/package metadata without executing the target; - prepare a hash-bound characterization workspace; - expose selected internal functions or modules through reversible instrumentation; - invoke explicitly selected pure or bounded-effect callables with serialized fixtures; - observe module loading and export shape; - observe declared environment, filesystem, child-process, native-addon, WebAssembly, HTTP, WebSocket, Electron IPC, and timer boundaries; - attach through Node Inspector to an owned provider-launched process; - compare static semantic claims with controlled runtime observations; - export the resulting characterization as Evidence v2 and a reusable fixture. Preparation and execution must be separate approval and policy decisions. ## Exact-artifact instrumentation When temporary instrumentation is required: - verify the source artifact digest before modification; - never modify the authoritative artifact in place; - copy into an owned temporary root; - apply a deterministic, reviewable transformation; - record original and instrumented digests plus exact inserted byte/AST locations; - preserve a transformation manifest and source map when feasible; - expose only explicitly named/hash-addressed targets; - reject ambiguous matches; - prove the authoritative artifact remained unchanged; - remove the instrumented workspace on every exit unless separately approved for export. Instrumented execution is controlled-replay authority, not shipped-artifact authority. Results must cite both the shipped source evidence and transformation evidence. ## Invocation contract A characterization plan declares: - artifact, runtime, entrypoint, working directory, and isolated HOME; - selected module/function identity from semantic bundle evidence; - serialized arguments and expected serialization bounds; - allowed globals, modules, environment keys, roots, loopback endpoints, timers, and native boundaries; - maximum calls, processes, files, bytes, handles, duration, and idle time; - deterministic clock/randomness/ID policy; - secret aliases and redaction; - expected effect class: pure, declared bounded effects, or observation-only; - cancellation and cleanup requirements. Unknown return values, thrown values, callbacks, promises, iterators, cyclic objects, functions, handles, and native objects require typed bounded projections. They must not be serialized through unsafe generic inspection. ## Isolation and safety - Require explicit approval and a matching scoped policy grant. - Launch only provider-owned processes. - Default to no external network and loopback-only replay. - Never attach to unrelated or pre-existing processes. - Do not inherit arbitrary environment variables or credentials. - Block undeclared module, filesystem, child-process, native, and network boundaries. - Bound stdout, stderr, inspector messages, object graphs, source text, protocol bodies, and evidence. - Propagate cancellation and prove descendant, socket, timer, inspector, temporary-root, and instrumentation cleanup. - Clearly state that this is controlled observation, not a security sandbox, unless a real isolation provider supplies that property. ## Evidence Return: - shipped and instrumented artifact identities; - runtime/provider/version/profile identities; - transformation manifest and limitations; - selected callable identity and resolution proof; - ordered inputs, outputs, throws, effects, and boundary events; - process/environment/isolation identity; - completeness, truncation, cancellation, and cleanup; - static-to-runtime correlations labeled observation, derivation, or hypothesis; - residual unknowns and recommended next probes. A successful call proves only the declared finite characterization claims, never global behavioral equivalence. ## Failure model Distinguish artifact mismatch, target ambiguity, transformation failure, runtime unavailable, policy denial, unsupported value, undeclared effect, boundary escape attempt, inspector disconnect, timeout, cancellation, truncation, target crash, descendant leak, cleanup failure, and incomplete observation. ## Acceptance criteria - [ ] Provider-neutral contracts are independent of Node Inspector and any specific transformer. - [ ] A Node provider characterizes selected functions from plain, minified, and bundled fixtures. - [ ] Every run is bound to exact shipped and instrumented digests. - [ ] The authoritative artifact is never modified in place and is rehashed after execution. - [ ] Pure fixtures prove arguments, returns, throws, promises, and deterministic clock/randomness. - [ ] Bounded-effect fixtures prove module loads, files, children, loopback HTTP/WebSocket, native/Wasm boundary declarations, and cleanup. - [ ] Undeclared effects fail closed and remain visible. - [ ] Inspector attach is limited to an owned provider-launched process. - [ ] Cancellation and all resource-cleanup paths are exercised. - [ ] Static semantic evidence can be correlated without being promoted to runtime proof. - [ ] Large records are available through MCP resources. - [ ] CLI and MCP contracts, typed errors, progress, cancellation, and Tasks behavior are equivalent. - [ ] A temporary export-instrumentation fixture produces deterministic evidence twice and leaves the source tree byte-identical with no residual instrumented file. ## Relationships - Parent dynamic-observation policy: #36 - Static JavaScript semantics: #117 and #68 - Managed-runtime provider roadmap: #42 - Provider SDK: #45 - Evidence resources: #99 - Scoped approval grants: #96 and #114 - Long-running work: #97 and #98 - Fixture export: #62 ## Non-goals - Executing arbitrary bundles without approval. - Claiming instrumentation output is unmodified shipped behavior. - Attaching to unrelated user processes. - Providing a security boundary without a real sandbox or VM. - Recovering original names, comments, or source. - Replacing external process, browser, Electron, or native-binary observation.
bsakaguchi 2026-10-15 18:21:45 +00:00
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
morluto/rea#156
No description provided.