Developer Guide: Runtime Layers and Core Boundaries

This guide explains the internal layer boundaries in cli_subprocess_core.

It is intended for people reviewing the core architecture, extending the core, or trying to understand where a change should land.

The Core Layers

cli_subprocess_core has a small set of important layers:

1. model policy
2. provider profile adaptation
3. command/session normalization
4. execution-surface routing and lower runtime execution
5. normalized event and payload emission

These layers exist so the runtime can stay consistent while still supporting multiple external CLI families.

Schema Ownership Inside The Layers

The shared schema boundary sits beside the existing runtime layers, not above them as a second architecture.

• CliSubprocessCore.Schema owns the shared Zoi validation contract for core-owned dynamic boundaries.
• CliSubprocessCore.Event, CliSubprocessCore.Payload.*, CliSubprocessCore.ModelRegistry.Model, CliSubprocessCore.ModelRegistry.Selection, and CliSubprocessCore.ModelInput use that schema layer at map ingress and then project back into the existing public structs.
• Forward-compatible shared wire surfaces use Zoi.map(..., unrecognized_keys: :preserve) plus projection so future fields survive in extra where the boundary needs them.
• Closed boundaries may still use direct struct validation, but evolving wire surfaces should not depend on Zoi.struct/3.
• Provider-native app-server, control-protocol, and orchestration schemas stay in the downstream repos that own those boundaries.

Layer 1: Model Policy

Owned by:

• CliSubprocessCore.ModelRegistry
• the internal model catalog loader and catalog data under priv/models

This layer answers:

• which models exist
• which model should be used
• whether the request is valid
• which reasoning values are allowed

Layer 2: Provider Profile Adaptation

Owned by:

• CliSubprocessCore.ProviderProfile
• built-in provider profile modules

This layer answers:

• how to translate normalized intent into provider-specific CLI behavior
• how to interpret provider-specific output inside the shared runtime

Layer 3: Command and Session Normalization

Owned by modules such as:

• CliSubprocessCore.Command
• CliSubprocessCore.Command.Options
• CliSubprocessCore.Session
• CliSubprocessCore.Session.Options

This layer gives the core a provider-agnostic API for one-shot commands and longer-lived sessions.

Layer 4: Lower Runtime Execution

Owned by the lower owner for the selected lane:

• ExecutionPlane.Process for the covered local one-shot command lane
• ExecutionPlane.Process.Transport for the shared session-bearing lane and non-local command/session placement

This layer starts the external process, manages stdin/stdout/stderr, and captures process exit information through the shared substrate.

It should remain blind to provider policy.

That includes provider-native approval and sandbox posture. The transport layer owns how the process is attached or started. It does not own whether a particular provider should run with a permissive mode such as "danger full access."

If a remote CLI launched over :ssh_exec later fails inside its own sandbox backend, that is already above the transport-placement boundary. A common real example is a remote Linux host where the provider CLI tries to use bwrap and the host's AppArmor or userns policy blocks the loopback/userns setup. The core transport succeeded; the remote runtime or host policy did not.

Layer 5: Event and Payload Emission

Owned by:

• CliSubprocessCore.Event
• CliSubprocessCore.Payload.*
• CliSubprocessCore.Runtime

This layer turns provider/runtime activity into the shared event model that the rest of the stack consumes.

The Practical Boundary Rule

When deciding where a change belongs, use this rule:

• if the change affects model choice, put it in the registry/catalog
• if the change affects provider CLI syntax, put it in the provider profile
• if the change affects the covered local one-shot subprocess lane, put it in the execution-plane-backed lower runtime
• if the change affects the shared session-bearing or non-local placement transport seam, put it in the execution-plane-backed transport layer
• if the change affects normalized output shape, put it in payload/runtime

That rule prevents policy leakage across layers.

Example Integration Shape

External repos should consume the core in this order:

1. prepare normalized options
2. call the core’s model registry
3. pass the resolved selection into provider-facing command building
4. let the core route the request to the execution-plane-backed command lane or the execution-plane-backed transport lane as appropriate

The core is therefore both:

• a policy owner
• and a command/session boundary above lower runtime owners

But those are still separate internal responsibilities.

What Reviewers Should Watch For

Architecture drift usually shows up as one of these mistakes:

• a provider profile starts choosing fallback models
• transport code learns provider policy
• consumer-facing behavior bypasses normalized payloads
• multiple layers define overlapping defaults

If one layer can be removed without changing the others, the boundaries are probably healthy. If a small change requires editing policy, profile, and transport logic together, the responsibilities are probably leaking.