ADR-006: Execution Plugin Framework

Status: Accepted Date: 2026-05-25 Sprint: SPRINT_20260525_012_ReleaseOrchestrator_execution_plugin_framework.md Related ADRs: ADR-011 (EPF plugin service contract)

This record unifies the three kinds of out-of-process release work — build, scan, and deploy — behind a single, signed, isolated plugin contract hosted on the existing Plugin SDK. Read it before adding a deploy backend, a build step, or any new execution behaviour, or before touching the agent capability registry.

Context

Stella Ops performs three kinds of out-of-process work on behalf of a release: it builds artifacts, it scans them (SBOM, call-graph), and it deploys them. Today these are implemented by three unrelated mechanisms:

  1. Deployment “capabilities” (docker, compose, ssh, winrm, ecs, nomad) live in src/ReleaseOrchestrator/__Agents/. They implement StellaOps.Agent.Core/Capability/IAgentCapability.cs and are wired into the agent by a hardcoded switchin src/ReleaseOrchestrator/__Agents/StellaOps.Agent.Host/Program.cs (CreateCapabilityRegistry). They are not discovered, not versioned, not signed, not isolated, and adding one requires editing the host.

  2. A container script executor in src/ReleaseOrchestrator/__Libraries/StellaOps.ReleaseOrchestrator.Scripts/Execution/ScriptExecutor.cs already runs operator scripts in isolated, pooled Docker containers (IRuntimeImageManager, IContainerPoolManager) with deterministic capture (ScriptRawOutputProof). It is scoped only to “release scripts”.

  3. A general plugin SDK in src/Plugin/ (StellaOps.Plugin.Abstractions/IPlugin.cs, StellaOps.Plugin.Host/) provides per-plugin AssemblyLoadContext isolation, a v2 manifest (Manifest/PluginManifest.cs: capabilities, dependencies, resource limits, permissions, config schema, signature), three trust levels (PluginTrustLevel.cs: BuiltIn / Trusted / Untrusted with process + overlay-FS + AppArmor/JobObject sandboxing), and X.509+JOSE signature verification (StellaOps.Plugin.Host/Trust/). The Integrations subsystem already loads connectors through this SDK (IntegrationPluginLoader + IIntegrationConnectorPlugin). The deployment capabilities do not use it.

The result is duplicated execution infrastructure, an unsafe and non-extensible deployment capability model, and no single place to add new execution behaviours (e.g. a new deploy backend, a build step, a custom-language step) with isolation, signing, and resource limits.

Decision

Introduce a single Execution Plugin Framework: one plugin contract for build, scan, deploy, and verify steps, hosted on the existing Plugin SDK, with two interchangeable execution backends.

Layer 1 — Plugin runtime (reuse src/Plugin)

Execution plugins are ordinary Plugin SDK plugins: ALC-isolated, manifest-described, signature-verified, with manifest-declared capabilities, permissions, and resource limits, and a trust level. No new loader is introduced.

Layer 2 — Execution contract (new, small)

IExecutionPlugin : IPlugin
    ExecutionKind Kind { get; }            // Build | Scan | Deploy | Verify | Custom
    IReadOnlyList<string> Capabilities { get; }   // e.g. "deploy.compose", "deploy.ansible",
                                                  //      "build.docker", "scan.sbom"
    Task<ExecutionResult> ExecuteAsync(ExecutionContext ctx,
                                       ExecutionInputs inputs,
                                       CancellationToken ct);   // streams progress/logs,
                                                                // returns result + raw-output proof

IExecutionPlugin generalises today’s IAgentCapability. The manifest declares the plugin’s input/output schema. Secrets are resolved by the host/orchestrator and handed to the plugin as scoped inputs — plugins never read ambient credentials.

Layer 3 — Two hosts, one contract

Layer 4 — Orchestration

TargetExecutor selects the plugin by capability / task-type from the registry instead of a switch. Build and scan steps may be invoked from the scan pipeline or JobEngine through the same hosts.

Consequences

Alternatives Considered

References