Execution Plane Workspace

This repository is a non-umbrella Mix workspace. The repository root is a tooling project only; it is not the execution_plane Hex package.

The historical public execution_plane 0.1.0 Hex package was generated with released Weld 0.8.4 as a monolith. The canonical execution_plane 0.2.0 package publishes directly from the common substrate:

• core/execution_plane

Blitz, Weld, and workspace orchestration live only in the root tooling project and do not enter runtime dependency graphs. Canonical changes stay in the component source homes; projection/execution_plane is historical 0.1.0 release evidence. JSON-RPC and process execution now publish independently as execution_plane_jsonrpc and execution_plane_process.

Execution Plane is the lowest runtime substrate in the ranked stack. It owns packets, lane protocols, placements, target attestations, runtime-client contracts, and raw lower evidence. It does not own product intent, governance policy, connector semantics, or durable workflow truth.

Stack Position

products / AppKit / Mezzanine / Citadel / Jido Integration
  -> ExecutionPlane.Runtime.Client (frozen interactive contract)
      -> execution_plane_node
          -> process, HTTP, JSON-RPC, SSE, WebSocket, terminal lanes
              -> concrete runtimes and targets

Higher layers decide why something should run and what authority applies. Execution Plane decides whether a lower execution request is structurally valid, whether the target and attestation are acceptable, which lane can carry the request, and what lower evidence packet describes the result.

The node is intentionally lane-neutral. It can route to registered lanes and verified targets, but it must not invent fallback ladders or infer business semantics. If a policy owner allows multiple target classes, that owner issues separate runtime-client calls and records each rejected or accepted rung.

What The Public Distribution Carries

The generated execution_plane package carries shared lower values and behaviours:

• admission requests, decisions, and rejections
• authority refs and host-registered authority verifiers
• sandbox profiles and acceptable attestation classes as opaque policy data
• target descriptors, target attestations, target clients, and target verifiers
• execution requests, results, events, refs, evidence, and provenance
• placement descriptors for local, SSH, and guest targets
• lane adapter behaviours and capability descriptions
• lower-boundary simulation and conformance helpers

JSON-RPC framing and process/PTY/stdio transport are owned only by their separate packages. This avoids the duplicate-module graph created by combining those components with the historical 0.1.0 monolith.

The common package does not enforce an OS sandbox by itself. It carries policy and evidence. Real isolation claims must come from a verified target and a lane/host implementation that can substantiate the attestation.

Current Delivery State

The current checkout has a usable common package, process lane, HTTP lane, JSON-RPC lane, SSE/WebSocket stream lanes, runtime node, and operator-terminal package. StackLab currently proves node composition through local process/HTTP execution, target-attestation rejection, authority rejection, and Jido Integration-owned fallback evidence.

Recent work fixed dependency-source fallback behavior, added the local TRE Rhai runner lane under the process package, added target posture attach contracts, required lower authority refs, governed process environment inheritance, and cleaned up atom/regex/env hazards.

The Synapse governed-effect lift adds the deterministic diagnostic lane used by StackLab staged-live proof. ExecutionPlane.Lanes.DiagnosticLane validates a lower execution request, runs the selected diagnostic action, applies timeout and output-size limits, and returns an ExecutionPlane.DiagnosticResult through the common execution result shape. It is deliberately provider-neutral: higher layers decide authority, product meaning, and connector placement; Execution Plane only owns lower request validation, lane execution, and result evidence.

The cross-stack conformance command is:

cd /home/home/p/g/n/stack_lab
MIX_ENV=test mix stack_lab.synapse.staged_live.v1 --json

Maintainers should read Code Smell Remediation before changing subprocess transport state, public starts, OS command ownership, file spooling, or guest bridge state.

Runtime Diagrams

flowchart TD
  Client["Runtime<br/>client"] --> Request["Execution<br/>request"]
  Request --> Authority["Authority<br/>verifier"]
  Request --> Target["Target<br/>verifier"]
  Authority --> Decision["Admission<br/>decision"]
  Target --> Decision
  Decision --> Node["Runtime<br/>node"]
  Node --> Process["Process<br/>lane"]
  Node --> HTTP["HTTP<br/>lane"]
  Node --> JSONRPC["JSON-RPC<br/>lane"]
  Node --> Streams["Stream<br/>lanes"]
  Process --> Evidence["Evidence<br/>packet"]
  HTTP --> Evidence
  JSONRPC --> Evidence
  Streams --> Evidence

Loading

flowchart LR
  Policy["Higher<br/>policy"] --> Calls["Runtime<br/>calls"]
  Calls --> Strong["Strong<br/>rung"]
  Calls --> Weak["Weak<br/>rung"]
  Strong --> Rejected["Rejected<br/>evidence"]
  Weak --> Accepted["Accepted<br/>evidence"]
  Rejected --> Owner["Fallback<br/>owner"]
  Accepted --> Owner

Loading

Developer Flow Diagrams

flowchart TD
  Client["Runtime<br/>client"] --> Node["Runtime<br/>node"]
  Node --> Caps["Lane<br/>capabilities"]
  Caps --> Adapter["Lane<br/>adapter"]
  Adapter --> Events["Runtime<br/>events"]
  Adapter --> Result["Lower<br/>result"]
  Events --> Sink["Evidence<br/>sink"]
  Result --> Sink

Loading

flowchart LR
  Request["Execution<br/>request"] --> Auth["Authority<br/>verify"]
  Request --> Target["Target<br/>verify"]
  Auth --> Sandbox["Sandbox<br/>constraints"]
  Target --> Attest["Attestation<br/>class"]
  Sandbox --> Decision["Admit<br/>or reject"]
  Attest --> Decision
  Decision --> Evidence["Evidence<br/>packet"]

Loading

Mix Projects

The checkout contains exactly eight active component Mix projects:

• core/execution_plane: common substrate selected into execution_plane
• protocols/execution_plane_http: unary HTTP lane
• protocols/execution_plane_jsonrpc: separately published JSON-RPC framing and correlation
• streaming/execution_plane_sse: SSE framing and stream lifecycle lane
• streaming/execution_plane_websocket: WebSocket handshake/frame lane
• runtimes/execution_plane_process: separately published process/PTY/stdio lane and the sole owner of erlexec
• runtimes/execution_plane_node: lane-neutral runtime node and local ExecutionPlane.Node.Client for current admission and one-shot dispatch
• runtimes/execution_plane_operator_terminal: operator-facing terminal runtime, kept separate so base consumers do not inherit ex_ratatui

The root mix.exs is :execution_plane_workspace; it exists to run Blitz workspace tasks, Weld projection/release tasks, root documentation, and repository-level checks.

Installing Packages

Add the common substrate package when you need contracts, codecs, placement descriptors, runtime-client behaviours, evidence envelopes, and pure helpers:

def deps do
  [
    {:execution_plane, "~> 0.2.0"}
  ]
end

Add only the lane and host packages the runtime uses:

def deps do
  [
    {:execution_plane, "~> 0.2.0"},
    {:execution_plane_process, "~> 0.1.0"},
    {:execution_plane_jsonrpc, "~> 0.1.0"}
  ]
end

Downstream SDK users normally should not add Execution Plane deps manually. For example, CLI provider SDKs get local subprocess execution transitively through cli_subprocess_core, and REST/GraphQL-only SDKs should stay above their HTTP or GraphQL family kit.

Development

Run the workspace gate from the repository root:

mix deps.get
mix ci

The root gate unconditionally resolves dependencies for all eight child projects, then uses Blitz to run the impact-selected package-local mix ci aliases. Dependency fetch is deliberately not impact-skippable: fetched trees are disposable checkout state and may be absent even when a prior dependency task passed. Package gates can still be run directly:

cd core/execution_plane && mix ci
cd protocols/execution_plane_http && mix ci
cd protocols/execution_plane_jsonrpc && mix ci
cd streaming/execution_plane_sse && mix ci
cd streaming/execution_plane_websocket && mix ci
cd runtimes/execution_plane_process && mix ci
cd runtimes/execution_plane_node && mix ci
cd runtimes/execution_plane_operator_terminal && mix ci

Publishing

The Weld commands below reproduce the historical 0.1.0 monolith for audit only; do not use that artifact for a new publication:

mix weld.inspect --artifact execution_plane
mix weld.project --artifact execution_plane
mix weld.verify --artifact execution_plane
mix release.prepare --artifact execution_plane

The historical package directory is dist/monolith/execution_plane, and its durable generated branch is projection/execution_plane. Publish execution_plane 0.2.0 from core/execution_plane first:

cd core/execution_plane
mix ci
mix hex.build
mix hex.publish --yes

Then prove each component from a clean standalone checkout/package extraction resolving the actual Hex execution_plane 0.2.0, publish execution_plane_process 0.1.0 and execution_plane_jsonrpc 0.1.0, and only then publish their consumers. A workspace-path compile is necessary local evidence but is not publication evidence.

Sandbox And Target Honesty

The common contracts carry ExecutionPlane.Sandbox.Profile and ExecutionPlane.Sandbox.AcceptableAttestation values as opaque policy and target-selection data. They do not enforce a sandbox by themselves.

local-erlexec-weak means local process execution with weak local attestation. It is not a container, microVM, or cryptographic isolation claim. Stronger target classes must be backed by a host-owned verifier and target protocol evidence before they enter the node routing table.

License

MIT

Persistence Documentation

See docs/persistence.md for tiers, defaults, adapters, unsupported selections, config examples, restart claims, durability claims, debug sidecar behavior, redaction guarantees, migration or preflight behavior, and no-bypass scope when applicable.

Trial Replay & Scoring Lane Role

Execution Plane executes replay and scoring lanes for Chassis Evolution candidates. Chassis.Evolution.Scorer can invoke Execution Plane lanes to replay a failure batch and baseline cases against an isolated trial worker, then return bounded lane evidence to Chassis and Mezzanine for scoring reduction. Lane jobs remain sandboxed replay jobs with explicit authority, target, timeout, output bounds, and evidence packet refs.

ExecutionPlane Executes; Chassis Provisions

Chassis provisions the isolated trial runtime, host placement, mount posture, release/image candidate, and rollback checkpoints. Execution Plane runs the lanes. Chassis does not own job execution semantics; Execution Plane does not own substrate placement, Chassis receipts, or candidate promotion authority.