Skip to content

Real Execution Backends

Jump to bottom
coo1white edited this page Jun 8, 2026 · 1 revision

Real Execution Backend Integrations (v0.1.34)

The v0.1.29 delegating drivers (container/remote/ci) become REAL — they actually drive docker/podman, a remote runner, and a CI job — opt-in, fail-closed, with evidence byte-stable against node. Shipped in v0.1.34. Repo doc: docs/real-execution-backends.7.md.

In v0.1.29 the three delegating drivers were contract-conformant stubs: delegate() built a handle and returned completed with delegated:/handle: evidence without running anything. v0.1.34 replaces that no-op so a delegated task really executes, recording the SAME canonical evidence as the local drivers.

Design Mantra

Drivers really execute now.
Same evidence, any backend.
The handle is provenance, not evidence.
Fail closed; never a fabricated completion.

The Borrowed Idea: Identical Envelopes, Any Backend

A real delegated run records the SAME canonical evidence executeLocal produces — command: / exitCode: / stdoutSha256: — so a container run of a task is byte-stable against node after stripping provenance. The execution handle (image@digest, endpoint#jobId) lives in provenance.handle and the sandbox attestation in provenance.attestation — never in evidence. Eval/replay, the verifier gates, the v0.1.28 registry, and the Workbench stay backend-agnostic.

Principles

  1. container — real docker/podman run under the sandbox contract: --network none when the profile restricts it, read-only workspace mount, filtered env (only the profile's exposed names; the image supplies its own PATH/HOME).
  2. Daemon pre-flight (load-bearing fail-closed) — a present CLI with an unreachable daemon must fail closed. version --format {{.Server.Version}} returns the server version only when reachable; the container run's own exit code is not a reliable daemon-down signal across runtimes, so it is not relied upon.
  3. remote / ci — real HTTP POST-and-poll via a self-contained Node child (global fetch; portable, synchronous from CW's view). The runner's {exitCode, stdout} becomes the canonical evidence.
  4. Fail closed — delegation-target-missing / no-command / runtime-unavailable / delegation-failed → status: "refused" with a refused:<code> line and no stdoutSha256:. A container command that genuinely runs and exits non-zero is failed (a real result), distinct from refused (never ran).
  5. CW delegates; it is not the executor — it drives docker/podman, a remote runner, or a CI job through a thin adapter and captures verifiable evidence; it never reimplements a container runtime or a CI system.
  6. Backward compatible — node stays the default and reproduces pre-v0.1.29 behavior; real execution is strictly opt-in (explicit backend + a configured, available target). The ResultEnvelope schema is unchanged.

Why It Matters

This is what makes the v0.1.29 driver layer real without breaking its invariant: because evidence is identical across backends, you can move a workload onto a container or a remote/CI runner and every downstream system — replay, verifier, registry, Workbench — behaves exactly the same. Verified live: CW's own node dist/cli.js list through a real container produced byte-identical evidence to the node backend.

See Also

Organized from local Obsidian notes and reconciled with the current coo1white/cool-workflow repository state.

Cool Workflow

Start here

Go deeper

Source docs

Clone this wiki locally