Module local_runtime 

Local-container runtime: detect an orbstack/docker-desktop/colima/podman/docker socket per .yah/infra/providers/orbstack.toml, then drive appliance containers (miniflare, MinIO) for the pond mirror shape.

Shells out to the docker CLI rather than linking a Docker REST client. OrbStack, Docker Desktop, Colima, and Podman all expose a Docker-compatible socket; the call sites here are few enough that per-invocation process overhead is invisible inside the container spin-up budget (few seconds).

Provider cascade

RuntimeProvider is the probe contract each back-end implements. LocalContainerSpec::build_cascade returns the ordered provider list; LocalRuntime::detect walks it and picks the first available one. Default Auto order: OrbStack → Docker Desktop → Colima → Podman → Docker → custom DOCKER_HOST.

Module shape

• LocalContainerSpec carries a runtime preference + socket discovery map. The cloud crate provides the kind = "local-container" ProviderConfig adapter via cloud::local_container_spec_from_provider.
• LocalRuntime::detect probes sockets in preference order, expands ~ in paths, and returns a handle that downstream callers feed every docker invocation through.
• LocalRuntime exposes the lifecycle primitives R256-T3 will compose into a reconciler: ensure_image, run, stop_and_remove, container_state, list_owned.

Container naming + orphan cleanup

Every container this module starts gets:

• A canonical name: yah-pond-<service>-<env>-<slot> via canonical_name. The yah-pond- prefix is grep-friendly in docker ps output.
• A docker label yah.pond = <service>:<env>:<slot> for filtered queries via docker ps --filter label=yah.pond.

After a crash that misses graceful shutdown, LocalRuntime::list_owned enumerates leftovers and the caller can reap them before starting a fresh up cycle.

@yah:relay(R275, “Tier 2 — Container substrate: provider trait + non-orbstack fallbacks”) @yah:at(2026-05-21T21:56:51Z) @yah:status(review) @yah:parent(Q273) @yah:next(“F1: promote local_runtime probe into RuntimeProvider trait with explicit OrbStack / Docker Desktop / Colima / Podman / custom DOCKER_HOST providers (per visiting doc)”) @yah:next(“F2: settings-panel UX surfacing Detected/Current/Mode in rig-prefs”) @yah:next(“F3: spike built-in macOS VM via Virtualization.framework — go/no-go + scoping estimate; defer build until a real ‘Nothing found’ case”) @yah:next(“F4: route reconciler/local_sim.rs Caddy+MinIO path through the new trait (currently calls orbstack-via-docker-CLI directly)”) @yah:gotcha(“Today only orbstack-via-docker-CLI is exercised in practice; the cascade exists implicitly. Don’t assume other backends work until F1 lands.”) @arch:see(visiting/container-runtime-strategy.md) @arch:see(.yah/docs/working/W080-dev-yah-static-demo.md) @arch:see(.yah/docs/architecture/A031-yah-cloud-config-shape.md) @yah:handoff(“F1 + F4 landed: RuntimeProvider trait (name/available/docker_host), SocketRuntimeProvider, CustomDockerHostProvider — all in local_runtime.rs. RuntimePref/DetectedRuntime expanded with DockerDesktop, Podman, Custom variants. LocalContainerSpec gains custom_docker_host: Option and build_cascade() (returns ordered Vec<(DetectedRuntime, Box)> for settings-panel use). LocalRuntime.socket: PathBuf replaced by docker_host: String; cmd() uses it directly. local_sim.rs F4 log line updated. lib.rs re-exports updated. 164 tests pass.”) @yah:next(“F2: settings-panel UX — build_cascade() returns the provider list; surface Detected/Current/Mode in rig-prefs UI (packages/yah/ui)”) @yah:next(“F3: spike built-in macOS VM via Virtualization.framework — go/no-go + scoping estimate; defer build until a real ‘Nothing found’ case arises in dogfood”) @yah:handoff(“F1 + F4 already landed (prior session). F2 now landed: local_runtime_probe Tauri command in app/yah/desktop/src/local_runtime_cmd.rs probes all kind=local-container providers (build_cascade + detect); wire types WireLocalRuntimeCandidate/WireLocalRuntimeStatus in env/types.ts; LocalRuntimeRpc interface added to Rpc in env/index.ts; tauri.ts + browser.ts stub wired; LocalRuntimePanel component at packages/yah/ui/src/components/shell/LocalRuntimePanel.tsx; Settings → Container Runtime section added to SettingsView (SettingsSection type, SECTIONS array, panel render). RuntimePref::as_str() added to local_runtime.rs. 164 cloud lib tests + bun typecheck both pass clean.”) @yah:next(“F3 (built-in macOS VM via Virtualization.framework): deferred — arch doc (visiting/container-runtime-strategy.md) covers the go/no-go and scoping; defer build until a real Nothing-found case surfaces in dogfood. File as a child spike if/when dogfood hits that case.”) @yah:handoff(“All deliverable features shipped: F1 (RuntimeProvider trait + SocketRuntimeProvider/CustomDockerHostProvider + full cascade), F2 (LocalRuntimePanel settings UI + Tauri command + wire types), F4 (local_sim.rs routed through trait). F3 (macOS Virtualization.framework spike) remains deferred until dogfood surfaces a Nothing-found case. This session fixed the only remaining breakage: mesofact_static_e2e.rs was missing the adopt_only field added to LocalStaticOptions — fixed with ..LocalStaticOptions::default(). cargo test -p cloud: all pass. bun typecheck: R275 files clean (pre-existing PartyView/test errors from other in-flight work).”)

Structs

ContainerRunSpec

Run-time spec for a single container managed by LocalRuntime::run.

CustomDockerHostProvider

RuntimeProvider for a raw DOCKER_HOST string supplied by the operator (e.g. "tcp://localhost:2375" or "unix:///path/to/custom.sock"). Always reported as available — the operator opted in explicitly; failures surface as docker CLI errors rather than probe misses.

LocalContainerSpec

Probe spec lifted from a kind = "local-container" provider TOML.

LocalDockerRuntime

WorkloadRuntime implementation backed by the docker CLI.

LocalRuntime

Reachable local container daemon — the winning provider from the cascade.

OwnedContainer

A container managed by this module, as observed via LocalRuntime::list_owned.

SocketRuntimeProvider

RuntimeProvider backed by a Unix socket path. Available iff the tilde-expanded path exists on disk.

Enums

ContainerState

Container State.Status from docker inspect. Anything the docs don’t enumerate lands in [Unknown].

DetectedRuntime

Which runtime answered the probe cascade.

RuntimePref

Operator-declared runtime preference from the provider TOML’s top-level runtime field. auto walks the full cascade; any pinned value probes only that runtime.

Constants

LABEL_KEY

Docker label key applied to every container this module owns. The value is <service>:<env>:<slot> so docker ps --filter label=yah.pond=<v> scopes orphan cleanup to a specific mirror.

LEGACY_LABEL_KEY

Legacy label key from before the sim→pond rename. Used by list_owned to detect old-generation containers during the transition period.

LEGACY_NAME_PREFIX

Legacy name prefix from before the sim→pond rename (R362-F5). Used by orphan reconciliation to detect and reap old-generation containers.

NAME_PREFIX

Canonical name prefix for every container managed by this module.

Traits

ContainerLauncher

The three container operations the pond bring-up sequences need, factored out of LocalRuntime so a caller can supply a different launcher.

RuntimeProvider

Probe contract for a single Docker-compatible runtime back-end. Each implementation knows its socket path (or raw DOCKER_HOST) and can report whether it is currently reachable.

Functions

canonical_label

Build the canonical label value for the same triple.

canonical_name

Build the canonical container name for a (service, env, slot) triple.

pond_network_name

Canonical per-cell bridge network name. Every container in a pond cell (MinIO, miniflare, mesofact-dev, …) joins this network so they reach each other by their --network-alias (R455-F1). One network per (service, env) pair lets two services’ ponds coexist without per-port collision juggling.