Implement perry/container and perry/workloads modules

[yumin-chen]

The perry/container and perry/workloads modules are now fully implemented and integrated into the Perry stack. This includes a native Rust orchestration engine, an enhanced FFI bridge, and critical compiler updates to support seamless container management from TypeScript.

Main accomplishments:

1. Robust Backend Detection: Implemented a priority-based probing system that automatically selects the best available OCI runtime (favoring native solutions on macOS/iOS).
2. Workload Graph Engine: Created a DAG-based execution model that supports typed service dependencies, fine-grained security policies, and dynamic address resolution via WorkloadRef.
3. Interactive Guided Setup: Added a BackendInstaller to assist users in installing a container runtime when none is detected.
4. Compiler-Ready Integration: Wired all new functions into the Perry compiler's HIR lowering and codegen dispatch tables, and ensured the stdlib auto-optimizer correctly gates the container feature.
5. Dynamic Networking Support: Enhanced ContainerInfo and WorkloadRef to utilize actual container IP addresses for reliable inter-service communication.
6. Unified Testing: Verified the entire implementation with multi-layered tests, including a new E2E harness for Perry container programs.

The implementation adheres to all technical specifications, including the canonical hyphenated naming convention and the WIT interface contract.

---

PR created automatically by Jules for task 13598332115557981235 started by @yumin-chen

[google-labs-jules]

👋 Jules, reporting for duty! I'm here to lend a hand with this pull request.

When you start a review, I'll add a 👀 emoji to each comment to let you know I've read it. I'll focus on feedback directed at me and will do my best to stay out of conversations between you and other bots or reviewers to keep the noise down.

I'll push a commit with your requested changes shortly after. Please note there might be a delay between these steps, but rest assured I'm on the job!

For more direct control, you can switch me to Reactive Mode. When this mode is on, I will only act on comments where you specifically mention me with @jules. You can find this option in the Pull Request section of your global Jules UI settings. You can always switch back!

New to Jules? Learn more at jules.google/docs.

---

For security, I will only act on instructions from the user who triggered this task.

[google-labs-jules]

Implement below specs and ensure production readiness:

Implementation Plan: perry/container

Overview

Implement the perry/container and perry/workloads modules as a Cargo feature-gated Rust library that bridges Perry TypeScript user code to native OCI container runtimes via FFI. The implementation spans three crates: perry-container-compose (backend detection, compose engine, workload graph engine, YAML parsing, CLI), perry-stdlib (FFI bridge, types, workload types, context, verification, capability), and compiler integration in perry-hir and perry-codegen.

Tasks

• 0. Port Go reference project entities and commands

  • 0.1 Port internal/entities/service.go → crates/perry-container-compose/src/service.rs

    • Implement Service struct with all fields from the Go entity: image, name (container_name), ports, environment, labels, volumes, build (ServiceBuild with context, dockerfile, args, labels, target, network)
    • Implement Service::generate_name() — MD5-based replacement for goombaio/namegenerator: MD5(image)[0..8] + "-" + random_hex_u32 (hyphen separator, NOT underscore — canonical format is {md5_8chars}-{random_hex8})
    • Implement Service::exists(backend) — calls ContainerBackend::inspect(), returns true if container found
    • Implement Service::is_running(backend) — calls ContainerBackend::inspect(), checks status field
    • Implement Service::needs_build() — returns true if build field is set and no image field, or if build is set and image not found locally
    • Implement Service::run_command(backend) — creates and runs container; calls build_command() first if needs_build()
    • Implement Service::start_command(backend) — starts existing stopped container
    • Implement Service::build_command(backend) — builds image from ServiceBuild config
    • Implement Service::inspect_command(backend) — returns ContainerInfo for the service's container
    • Requirements: 19.1, 19.2

  • 0.2 Port internal/entities/compose.go → crates/perry-container-compose/src/compose.rs (entity portion)

    • Implement Compose struct: services: IndexMap<String, Service>
    • Implement Compose::parse(yaml: &str) -> Result<Compose, ComposeError> using serde_yaml
    • Requirements: 19.1

  • 0.3 Port internal/commands/ → crates/perry-container-compose/src/commands/

    • Create commands/mod.rs with ContainerCommand trait: async fn exec(&self, ctx: &Context) -> Result<(), ComposeError>
    • Port build.go → commands/build.rs: BuildCommand struct implementing ContainerCommand
    • Port run.go → commands/run.rs: RunCommand struct implementing ContainerCommand
    • Port start.go → commands/start.rs: StartCommand struct implementing ContainerCommand
    • Port stop.go → commands/stop.rs: StopCommand struct implementing ContainerCommand
    • Port inspect.go → commands/inspect.rs: InspectCommand struct implementing ContainerCommand
    • Requirements: 19.1

  • 0.4 Port cmd/start/cmd.go orchestration logic → crates/perry-container-compose/src/orchestrate.rs

    • Implement orchestrate_service(service: &Service, backend: &dyn ContainerBackend) -> Result<(), ComposeError>
    • Logic: if running → skip; if exists but stopped → start_command; if not exists → (build if needed) → run_command
    • This is the core per-service startup function that ComposeEngine::up() calls for each service in topological order
    • Requirements: 19.1, 19.2

• 1. Set up perry-container-compose crate skeleton

  • Create crates/perry-container-compose/src/error.rs with the ComposeError enum (NotFound, BackendError, VerificationFailed, DependencyCycle, ServiceStartupFailed, InvalidConfig, NoBackendFound, BackendNotAvailable)
  • Create crates/perry-container-compose/src/lib.rs re-exporting public API
  • Create crates/perry-container-compose/src/commands/ subdirectory (populated in task 0.3)
  • Create crates/perry-container-compose/src/config.rs — ProjectConfig, resolve_compose_files(), resolve_project_name()
  • Create crates/perry-container-compose/src/orchestrate.rs — single-service orchestration helper (populated in task 0.4)
  • Add proptest, serde, serde_json, serde_yaml, tokio, async-trait, tracing, clap, md5, hex, rand, thiserror, indexmap, which dependencies to Cargo.toml
  • Add console and dialoguer under the installer feature flag
  • Add dashmap dependency
  • Requirements: 11.3, 12.2

• 2. Implement compose types (perry-container-compose/src/types.rs)

  • 2.1 Define ListOrDict enum, ContainerSpec, ContainerInfo, ContainerLogs, ImageInfo, BackendInfo, IsolationLevel

    • ContainerSpec fields: image: String, name: Option<String>, ports: Option<Vec<String>>, volumes: Option<Vec<String>>, env: Option<HashMap<String,String>>, cmd: Option<Vec<String>>, entrypoint: Option<Vec<String>>, network: Option<String>, rm: Option<bool>, labels: Option<HashMap<String, String>>
    • Security options (Requirement 2.8): read_only: Option<bool>, seccomp: Option<String>, privileged: Option<bool>, user: Option<String>, workdir: Option<String>, cap_add: Option<Vec<String>>, cap_drop: Option<Vec<String>>
    • Derive serde::Serialize, serde::Deserialize, Debug, Clone, PartialEq
    • Add #[serde(rename_all = "camelCase")] / snake_case as appropriate
    • Requirements: 2.7, 2.8, 3.4, 4.5, 5.4, 10.1, 10.11

  • 2.2 Define full ComposeSpec, ComposeService, ComposeServiceBuild, ComposeServiceNetworkConfig structs

    • Include all compose-spec fields listed in Requirements 6.2 and 6.3
    • Support ListOrDict for environment, labels, sysctls, extra_hosts
    • Requirements: 6.2, 6.3, 10.1

  • 2.3 Define ComposeNetwork, ComposeNetworkIpam, ComposeVolume, ComposeSecret, ComposeConfig

    • Requirements: 7.4, 7.5, 7.6, 7.7, 10.4, 10.5, 10.6, 10.7

  • 2.4 Define ComposeServicePort, ComposeServiceVolume, ComposeDependsOn, ComposeHealthcheck, ComposeDeployment, ComposeLogging

    • ComposeServiceVolume.type must be a validated enum (bind | volume | tmpfs | cluster | npipe | image)
    • ComposeDependsOn.condition must be a validated enum (service_started | service_healthy | service_completed_successfully)
    • Requirements: 7.14, 10.8, 10.9, 10.10, 10.14

  • [ ]* 2.5 Write property test for ContainerSpec / ContainerInfo / ContainerLogs / ImageInfo JSON round-trip

    • Property 4: Data model JSON round-trip
    • Validates: Requirements 2.7, 3.4, 4.5, 5.4, 10.1, 12.5, 12.6

  • [ ]* 2.6 Write property test for ComposeSpec JSON round-trip

    • Property 5: ComposeSpec JSON round-trip
    • Validates: Requirements 10.13, 12.6

  • [ ]* 2.7 Write property test for depends_on condition validation

    • Property 12: depends_on condition validation
    • Validates: Requirements 7.14

  • [ ]* 2.8 Write property test for ComposeServiceVolume type validation

    • Property 13: Volume type validation
    • Validates: Requirements 10.14

• 3. Implement error module (perry-container-compose/src/error.rs)

  • 3.1 Implement compose_error_to_json() serialising ComposeError to { "message": string, "code": number }

    • Implement From<ComposeError> for ContainerError
    • Requirements: 12.2

  • [ ]* 3.2 Write property test for error code/message preservation

    • Property 14: Error propagation preserves code and message
    • Validates: Requirements 2.6, 12.2

• 4. Implement backend detection (perry-container-compose/src/backend.rs)

  • 4.1 Define CliProtocol trait and protocol variants; define BackendDriver enum

    • Define CliProtocol trait (marker trait for CLI protocol variants)
    • Implement DockerProtocol — docker/podman/orbstack/colima/nerdctl CLI protocol
    • Implement AppleContainerProtocol — apple/container CLI protocol
    • Implement LimaProtocol { instance: String } — limactl with a named instance
    • Define BackendDriver enum with all variants carrying bin: PathBuf: AppleContainer, Orbstack, Colima, RancherDesktop, Podman, Lima, Nerdctl, Docker
    • Implement BackendDriver::name() returning the canonical name string
    • Requirements: 1.2, 1.4, 16.1

  • 4.2 Define ExecutionStrategy enum (CliExec, ApiSocket, VmSpawn) and IsolationLevel enum

    • Requirements: 1.9, 1.10

  • 4.3 Define ContainerBackend trait and implement CliBackend<P: CliProtocol>

    • Define ContainerBackend trait (canonical method set from SPEC.md §2.2):
      • fn backend_name(&self) -> &str (canonical name — NOT fn name())
      • async fn check_available(&self) -> Result<()>
      • async fn run(&self, spec: &ContainerSpec) -> Result<ContainerHandle>
      • async fn create(&self, spec: &ContainerSpec) -> Result<ContainerHandle>
      • async fn start(&self, id: &str) -> Result<()>
      • async fn stop(&self, id: &str, timeout: Option<u32>) -> Result<()>
      • async fn remove(&self, id: &str, force: bool) -> Result<()>
      • async fn list(&self, all: bool) -> Result<Vec<ContainerInfo>>
      • async fn inspect(&self, id: &str) -> Result<ContainerInfo>
      • async fn logs(&self, id: &str, tail: Option<u32>) -> Result<ContainerLogs>
      • async fn exec(&self, id: &str, cmd: &[String], env: Option<&HashMap<String,String>>, workdir: Option<&str>) -> Result<ContainerLogs>
      • async fn build(&self, spec: &ComposeServiceBuild, image_name: &str) -> Result<()>
      • async fn pull_image(&self, reference: &str) -> Result<()>
      • async fn list_images(&self) -> Result<Vec<ImageInfo>>
      • async fn remove_image(&self, reference: &str, force: bool) -> Result<()>
      • async fn inspect_image(&self, reference: &str) -> Result<ImageInfo>
      • async fn create_network(&self, name: &str, config: &NetworkConfig) -> Result<()>
      • async fn remove_network(&self, name: &str) -> Result<()>
      • async fn create_volume(&self, name: &str, config: &VolumeConfig) -> Result<()>
      • async fn remove_volume(&self, name: &str) -> Result<()>
      • async fn inspect_network(&self, name: &str) -> Result<()>
      • async fn wait(&self, id: &str) -> Result<i32> — wait for container exit, returns exit code
    • Implement CliBackend<P: CliProtocol> as the concrete ContainerBackend for CLI-based runtimes
    • CLI argument construction is internal to CliBackend (not a separate public type)
    • Requirements: 11.1

  • 4.4 Implement platform_candidates() returning the platform-specific probe order

    • macOS/iOS (platform-native first, then cross-platform, docker always last) — group cfg!(target_os = "ios") with cfg!(target_os = "macos"):
      1. apple/container — native macOS/iOS runtime, highest priority
      2. orbstack — macOS-native VM, Docker-compatible API
      3. colima — macOS-native Lima-based runtime
      4. rancher-desktop — macOS/cross-platform, containerd-based
      5. lima — macOS VM runtime via limactl
      6. podman — cross-platform, daemonless; preferred over docker when present
      7. nerdctl — containerd CLI wrapper
      8. docker — lowest priority; only used if nothing else is available
    • Linux (podman preferred over docker; platform-native runtimes first):
      1. podman — daemonless, rootless; preferred over docker
      2. nerdctl — containerd CLI wrapper
      3. docker — lowest priority
    • Windows (podman preferred over docker):
      1. podman — preferred over docker when present
      2. nerdctl — containerd CLI wrapper
      3. docker — lowest priority
    • Rationale: platform-specific runtimes (apple/container, orbstack, colima) are favored on macOS because they provide native integration; podman is favored over docker on all platforms because it is daemonless, rootless, and OCI-native; docker is always last as a fallback
    • Requirements: 16.1

  • 4.5 Implement probe_candidate() with 2-second timeout per candidate

    • CLI probe: run <cli> --version, check zero exit
    • colima: additionally run colima status, check "running"
    • podman on macOS: additionally run podman machine list --format json, check "Running": true
    • limactl: additionally run limactl list --json, check "Running" status
    • OrbStack: check orb binary OR ~/.orbstack/run/docker.sock
    • Rancher Desktop: check nerdctl AND containerd socket
    • Log all probe results at debug level
    • Requirements: 16.2, 16.3, 16.4, 16.5, 16.6, 16.7, 16.8, 16.9, 16.10

  • 4.6 Implement detect_backend() reading PERRY_CONTAINER_BACKEND and PERRY_CONTAINER_MODE env vars, iterating candidates, returning BackendDriver

    • Support local-first (default) and server-first modes
    • Return ComposeError::NoBackendFound { probed } when no candidate passes
    • Return ComposeError::BackendNotAvailable when env override not found
    • Implement async fn get_global_backend_instance() with tokio::sync::Mutex double-checked init (NOT OnceLock::get_or_init() — sync variant causes deadlocks in tokio context)
    • Requirements: 1.1, 1.2, 1.3, 1.5, 1.6, 18.1, 18.2, 18.3, 18.5, 18.6

  • 4.7 Implement interactive backend installer (crates/perry-container-compose/src/installer.rs)

    • Add dialoguer and console crates to Cargo.toml under the installer feature flag
    • Implement BackendInstaller::run() -> Result<BackendDriver, ComposeError>:
      • Detect TTY: use console::Term::stderr().is_term() — skip installer if not a TTY or PERRY_NO_INSTALL_PROMPT=1 is set
      • Print header: "Perry needs a container runtime to continue. No container runtime was found on this system."
      • Build platform-filtered backend menu in priority order (macOS: apple/container, orbstack, colima, podman, docker; Linux: podman, nerdctl, docker; Windows: podman, docker)
      • Each menu entry shows: name (bold), description, install command (cyan), docs URL
      • Use dialoguer::Select for arrow-key navigation; fall back to numbered input on non-ANSI terminals
      • After selection, print install command and prompt [Y]es / [N]o, show me the command
      • If Y: run install command via tokio::process::Command, stream output to terminal, then re-run detect_backend() to verify
      • If install succeeds: print success message in green, return the new BackendDriver
      • If install fails or user selects N: print manual instructions and return Err(ComposeError::NoBackendFound)
    • Update get_global_backend_instance() to call BackendInstaller::run() when detect_backend() returns NoBackendFound and TTY is available
    • Non-interactive fallback: when not a TTY, append a hint to the NoBackendFound error message: "Hint: Install <recommended_backend> for <platform>. See: <docs_url>"
    • Requirements: 20.1, 20.2, 20.3, 20.4, 20.5, 20.6, 20.7, 20.8, 20.9, 20.10, 20.11, 20.12, 20.13

  • 4.7 Implement BackendInfo serialisation from BackendProbeResult; include name, available, reason, version, mode, isolationLevel

    • Requirements: 1.9, 18.4

  • [ ]* 4.8 Write property test for backend priority order

    • Property 1: Backend selection respects priority order
    • Validates: Requirements 1.2, 16.1

  • [ ]* 4.9 Write property test for backend detection idempotence

    • Property 2: Backend detection is idempotent (async double-checked init caching)
    • Validates: Requirements 1.7

  • [ ]* 4.10 Write property test for ContainerSpec CLI argument round-trip

    • Property 3: ContainerSpec CLI arg round-trip
    • Validates: Requirements 2.7, 12.5

  • [ ]* 4.11 Write property test for BackendInfo serialisation completeness

    • Property 11: BackendInfo serialization completeness
    • Validates: Requirements 1.9

  • [ ]* 4.12 Write property test for IsolationLevel consistency

    • Property 15: IsolationLevel consistency
    • Validates: Requirements 1.9, 1.10

• 5. Checkpoint — Ensure all tests pass

  • Ensure all tests pass, ask the user if questions arise.

• 6. Implement compose engine (perry-container-compose/src/compose.rs)

  • 6.1 Implement resolve_startup_order free function and ComposeEngine method delegate

    • Implement resolve_startup_order(spec: &ComposeSpec) as a free function in compose.rs using Kahn's algorithm over depends_on graph
    • Add method delegate ComposeEngine::resolve_startup_order() that calls the free function (required for test compatibility — resolves C-6 ambiguity)
    • Return Err(ComposeError::DependencyCycle) identifying at least one service in the cycle
    • Store resolved graph as ServiceGraph on the engine
    • Requirements: 6.4, 6.5

  • 6.2 Implement ComposeEngine::up(): create networks → create volumes → start services in order → register handle

    • On any service failure: stop and remove all started containers, remove created networks and volumes
    • Call orchestrate_service() from orchestrate.rs (task 0.4) as the per-service startup function for each service in topological order
    • Generate unique container names via service::generate_name(image, service_name) → MD5(image)[0..8] + hyphen + random hex u32, formatted as {md5_8chars}-{random_hex8} (hyphen separator — canonical format)
    • Requirements: 6.1, 6.8, 6.9, 6.10, 6.13

  • 6.3 Implement ComposeHandle methods: down, ps, logs, exec, start, stop, restart, config

    • down(volumes: true) removes named volumes in addition to containers and networks
    • Requirements: 6.6, 6.7

  • 6.4 Implement ComposeHandle::graph() returning ServiceGraph and ComposeHandle::status() returning StackStatus

    • ServiceGraph: nodes: string[] in topological order, edges: Array<{from, to}>
    • StackStatus: per-service ServiceStatus with state, containerId?, error?; healthy: bool
    • Requirements: 6.6

  • [ ]* 6.5 Write property test for topological sort validity

    • Property 7: Topological sort produces valid ordering
    • Validates: Requirements 6.4

  • [ ]* 6.6 Write property test for cycle detection exhaustiveness

    • Property 8: Cycle detection is exhaustive
    • Validates: Requirements 6.5

  • [ ]* 6.7 Write property test for container name uniqueness

    • Property 9: Container name generation uniqueness
    • Validates: Requirements 6.13

• 7. Implement YAML parsing (perry-container-compose/src/yaml.rs)

  • 7.1 Implement ComposeSpec::parse_str() and ComposeSpec::parse_file() using serde_yaml

    • Support all service, network, volume, secret, config fields from Requirements 7.2–7.7
    • Validate depends_on condition values and volume.type values at parse time
    • Requirements: 7.1, 7.2, 7.3, 7.4, 7.5, 7.6, 7.7, 7.11, 7.14

  • 7.2 Implement environment variable interpolation (${VARIABLE} and ${VARIABLE:-default}) and .env file loading

    • Requirements: 7.8, 7.9

  • 7.3 Implement multi-file merging: later files override earlier ones for conflicting keys

    • Requirements: 7.10, 9.2

  • [ ]* 7.4 Write property test for YAML round-trip

    • Property 6: YAML round-trip (CLI path)
    • Validates: Requirements 7.12

• 8. Implement project management (perry-container-compose/src/project.rs)

  • Implement ComposeProject supporting -f/COMPOSE_FILE, -p/COMPOSE_PROJECT_NAME, default file discovery in order: compose.yaml → compose.yml → docker-compose.yaml → docker-compose.yml (4 files)
  • Derive project name from directory when no explicit name provided
  • Requirements: 9.1, 9.2, 9.3, 9.4, 9.5, 9.6, 9.7, 9.8

• 9. Implement standalone CLI (perry-container-compose/src/cli.rs)

  • Implement all commands using clap: up, down, ps, logs, exec, config, start, stop, restart
  • up: -d/--detach, --build, --remove-orphans
  • down: -v/--volumes, --remove-orphans
  • logs: -f/--follow, --tail N, optional service name args
  • exec: service name, command, -e/--env, -w/--workdir
  • All commands: -h/--help; root: --version; non-zero exit on failure
  • Requirements: 8.1, 8.2, 8.3, 8.4, 8.5, 8.6, 8.7, 8.8, 8.9, 8.10, 8.11

• 10. Checkpoint — Ensure all tests pass

  • Ensure all tests pass, ask the user if questions arise.

• 11. Set up perry-stdlib container module skeleton

  • Create crates/perry-stdlib/src/container/ directory with mod.rs, types.rs, context.rs, verification.rs, capability.rs
  • Gate entire module behind #[cfg(feature = "container")] in lib.rs
  • Requirements: 11.3

• 12. Implement ContainerContext (perry-stdlib/src/container/context.rs)

  • Define ContainerContext with backend: OnceLock<Arc<dyn ContainerBackend>> and handles: DashMap<u64, HandleEntry> (add dashmap to perry-stdlib/Cargo.toml under container feature)

  • Implement ContainerContext::global() returning the process-global static instance

  • Implement ContainerContext::new() for isolated test/multi-tenant contexts

  • Implement async fn get_global_backend_instance() with tokio::sync::Mutex double-checked init

  • Requirements: 1.7

  • [ ]* 12.1 Write property test for ContainerContext isolation

    • Property 16: ContainerContext isolation
    • Validates: Requirements 1.7

• 13. Implement types and handle registry (perry-stdlib/src/container/types.rs)

  • Re-export ContainerSpec, ContainerInfo, ContainerLogs, ImageInfo, BackendInfo, IsolationLevel from perry-container-compose
  • Define ContainerError as a thin compatibility wrapper over ComposeError; implement From<ComposeError> for ContainerError (ComposeError in perry-container-compose/error.rs is the authoritative error type)
  • Implement handle registry (u64 → opaque handle) for ContainerHandle and ComposeHandle backed by DashMap
  • Requirements: 2.7, 3.4, 4.5, 5.4, 12.1, 12.2

• 14. Implement workload graph types (perry-stdlib/src/container/workload.rs)

  • 14.1 Define RuntimeSpec enum: Oci, MicroVm { config: Option<MicroVmConfig> }, Wasm { module: Option<String> }, Auto

    • Define PolicySpec struct: tier: PolicyTier, no_network: bool, read_only_root: bool, seccomp: bool
    • Define PolicyTier enum: Default, Isolated, Hardened, Untrusted
    • Derive serde::Serialize, serde::Deserialize, Debug, Clone, PartialEq on all types
    • Requirements: 1.9, 1.10

  • 14.2 Define WorkloadRef struct and RefProjection enum

    • WorkloadRef: node_id: String, projection: RefProjection, port: Option<String>
    • RefProjection enum: Endpoint, Ip, InternalUrl
    • Implement WorkloadRef::resolve(running_nodes: &HashMap<String, ContainerInfo>) -> Result<String, ContainerError>
      • Endpoint: returns "<ip>:<port>" from the running container's port mappings
      • Ip: returns the container's IP address
      • InternalUrl: returns "http://<ip>:<first_port>"
    • Requirements: 6.1, 6.4

  • [ ]* 14.3 Write property test for WorkloadRef resolution consistency

    • Property 17: WorkloadRef resolution consistency
    • Validates: Requirements 6.1, 6.4

  • 14.4 Define WorkloadNode, WorkloadEnvValue, WorkloadGraph, WorkloadEdge types

    • WorkloadNode: id: String, name: String, image: Option<String>, resources: Option<WorkloadResources>, ports: Vec<String>, env: HashMap<String, WorkloadEnvValue>, depends_on: Vec<String>, runtime: RuntimeSpec, policy: PolicySpec
    • WorkloadEnvValue enum: Literal(String) or Ref(WorkloadRef)
    • WorkloadGraph: name: String, nodes: IndexMap<String, WorkloadNode>, edges: Vec<WorkloadEdge>
    • Add indexmap dependency to Cargo.toml
    • Requirements: 6.2, 6.4

  • 14.5 Define execution and status types

    • RunGraphOptions: strategy: ExecutionStrategy, on_failure: FailureStrategy
    • ExecutionStrategy enum (graph-level): Sequential, MaxParallel, DependencyAware, ParallelSafe
    • FailureStrategy enum: RollbackAll, PartialContinue, HaltGraph
    • GraphStatus: nodes: HashMap<String, NodeState>, healthy: bool, errors: HashMap<String, String>
    • NodeState enum: Running, Stopped, Failed, Pending, Unknown
    • NodeInfo: node_id: String, name: String, container_id: Option<String>, state: NodeState, image: Option<String>
    • GraphHandle struct (opaque, stored in handle registry)
    • Requirements: 6.4, 6.5, 6.6

• 15. Implement WorkloadGraphEngine (perry-container-compose/src/compose.rs extension)

  • 15.1 Implement WorkloadGraphEngine::run(graph: WorkloadGraph, opts: RunGraphOptions) -> Result<GraphHandle, ComposeError>

    • Convert WorkloadGraph to internal representation; reuse ComposeEngine topological sort
    • Resolve RuntimeSpec per node: Auto → calls detect_backend(), Oci → forces CliBackend, MicroVm/Wasm → uses VmSpawn strategy
    • Enforce PolicySpec per node: Untrusted forces MicroVm runtime; Hardened sets read-only rootfs + seccomp; Isolated disables cross-node networking
    • Apply RunGraphOptions.strategy to determine parallelism within topological levels
    • Apply RunGraphOptions.on_failure to determine rollback behavior (reuse existing rollback logic)
    • After all nodes start, resolve all WorkloadRef values in node env fields
    • Register GraphHandle in ContainerContext handle registry and return it
    • Requirements: 6.1, 6.4, 6.5, 6.8, 6.9, 6.10

  • [ ]* 15.2 Write property test for RunGraph strategy respecting dependency order

    • Property 18: RunGraph strategy respects dependency order
    • Validates: Requirements 6.4

• 16. Implement image verification (perry-stdlib/src/container/verification.rs)

  • Implement verify_image(reference: &str) -> Result<String, ContainerError> using cosign keyless verification

  • Validate certificate identity against CHAINGUARD_IDENTITY and OIDC issuer against CHAINGUARD_ISSUER

  • Implement VERIFICATION_CACHE: OnceLock<Mutex<HashMap<String, Result<...>>>> keyed by image digest

  • Implement get_default_base_image() returning "cgr.dev/chainguard/alpine-base"

  • Implement get_chainguard_image(tool: &str) returning tool-specific Chainguard image when available

  • Log verification results at debug level (image reference, digest, cosign output)

  • Requirements: 14.1, 14.2, 14.3, 15.1, 15.2, 15.3, 15.4, 15.5, 15.6

  • [ ]* 16.1 Write property test for verification caching idempotence

    • Property 10: Image verification caching is idempotent
    • Validates: Requirements 15.4, 15.7

• 17. Implement shell capability runner (perry-stdlib/src/container/capability.rs)

  • Implement perry_container_run_capability(name, image, cmd, grants) -> Result<ContainerLogs, ContainerError>
  • Call verify_image() before creating any container; reject with VerificationFailed on failure
  • Configure ephemeral container: no persistent volumes, no network, read-only rootfs, seccomp profile
  • Stop and remove container immediately after command exits (--rm --force equivalent)
  • Requirements: 13.1, 13.2, 13.3, 13.4, 13.5, 14.3, 14.4, 14.5, 15.5

• 18. Implement FFI bridge (perry-stdlib/src/container/mod.rs)

  • 18.1 Implement js_container_module_init() forcing backend selection at module init

    • Requirements: 11.6

  • 18.2 Implement container lifecycle FFI functions: js_container_run, js_container_create, js_container_start, js_container_stop, js_container_remove

    • All async functions return *mut Promise via spawn_for_promise()
    • String args cross boundary as *const StringHeader; results serialised to JSON *const StringHeader
    • Requirements: 2.1, 2.2, 2.3, 2.4, 2.5, 11.1, 11.7

  • 18.3 Implement inspection/listing FFI: js_container_list, js_container_inspect, js_container_logs, js_container_exec

    • Requirements: 3.1, 3.2, 3.3, 4.1, 4.2, 4.3, 11.1, 11.7

  • 18.4 Implement image management FFI: js_container_pullImage, js_container_listImages, js_container_removeImage

    • Requirements: 5.1, 5.2, 5.3, 11.1

  • 18.5 Implement backend query FFI: js_container_getBackend, js_container_detectBackend

    • detectBackend returns BackendInfo[] for all probed candidates
    • Requirements: 1.4, 1.8, 11.1

  • 18.6 Implement compose FFI: js_container_composeUp and all js_container_compose_* handle methods

    • js_container_composeUp(*StringHeader) — accepts either a JSON-serialised ComposeSpec (inline) OR a file path string; file-path mode used by standalone CLI, inline mode used from TS
    • js_container_compose_down(i64, i32) — handle id + volumes flag
    • js_container_compose_ps(i64) — handle id only
    • js_container_compose_logs(i64, *STR) — handle id + opts JSON
    • js_container_compose_exec(i64, *STR, *STR, *STR) — handle id + service + cmd + opts
    • js_container_compose_config(i64) — handle id only
    • js_container_compose_start(i64, *STR) — handle id + services JSON
    • js_container_compose_stop(i64, *STR) — handle id + services JSON
    • js_container_compose_restart(i64, *STR) — handle id + services JSON
    • js_container_compose_graph and js_container_compose_status for ComposeHandle.graph() and .status()
    • Note: prefix is js_container_compose_* (NOT js_compose_*)
    • Also implement js_compose_* alias wrappers (thin delegates to js_container_compose_*) for perry/compose import path: js_compose_up, js_compose_down, js_compose_ps, js_compose_logs, js_compose_exec, js_compose_config, js_compose_start, js_compose_stop, js_compose_restart
    • Requirements: 6.1, 6.6, 11.2, 11.7

  • 18.7 Implement workload graph FFI functions in mod.rs

    • js_workload_graph(name, spec_json) -> *const StringHeader — constructs and serialises a WorkloadGraph
    • js_workload_node(name, spec_json) -> *const StringHeader — constructs and serialises a WorkloadNode
    • js_workload_runGraph(graph_json, opts_json) -> *mut Promise<GraphHandle id> — delegates to WorkloadGraphEngine::run()
    • js_workload_inspectGraph(graph_json) -> *mut Promise<GraphStatus> — returns status without starting
    • js_workload_handle_down(handle_id, opts_json) -> *mut Promise<void>
    • js_workload_handle_status(handle_id) -> *mut Promise<GraphStatus>
    • js_workload_handle_graph(handle_id) -> *const StringHeader (sync, returns serialised WorkloadGraph)
    • js_workload_handle_logs(handle_id, node, opts_json) -> *mut Promise<ContainerLogs>
    • js_workload_handle_exec(handle_id, node, cmd_json) -> *mut Promise<ContainerLogs>
    • js_workload_handle_ps(handle_id) -> *mut Promise<NodeInfo[]>
    • Requirements: 11.1, 11.2, 11.7

• 19. Checkpoint — Ensure all tests pass

  • Ensure all tests pass, ask the user if questions arise.

• 20. Implement HIR lowering (crates/perry-hir/src/lower.rs)

  • Recognise import { ... } from 'perry/container' and map each imported name to its js_container_* FFI declaration
  • Recognise import { ... } from 'perry/container-compose' and map to js_container_compose_* FFI declarations
  • Recognise import { ... } from 'perry/compose' as an alias for perry/container-compose (SPEC.md §5.5); both import paths must be valid
  • Recognise import { ... } from 'perry/workloads' and map each imported name to its js_workload_* FFI declaration
  • Add perry/workloads, perry/container-compose, and perry/compose to the is_perry_builtin() guard alongside perry/container
  • Follow the same pattern used for perry/thread and perry/ui
  • Requirements: 11.4

• 21. Implement codegen dispatch (crates/perry-codegen/src/lower_call.rs)

  • Emit direct call instructions to js_container_*, js_container_compose_*, and js_workload_* FFI symbols
  • Add perry/container, perry/container-compose, perry/compose, and perry/workloads to the is_perry_builtin() guard so perry check does not flag them
  • Follow the same dispatch table pattern as NATIVE_MODULE_TABLE (not PERRY_UI_TABLE)
  • Requirements: 11.5, 11.8

• [ ]* 21.1 Wire js_container_build FFI symbol (optional / future)

  • Implement js_container_build(*StringHeader, *StringHeader) -> *mut Promise in perry-stdlib/src/container/mod.rs
  • Delegates to ContainerBackend::build(spec: &ComposeServiceBuild, image_name: &str)
  • Add js_container_build to the NATIVE_MODULE_TABLE dispatch in lower_call.rs
  • Note: backend implementation already exists in CliBackend; only the FFI wiring and codegen dispatch entry are missing
  • Requirements: 5.1 (image management)

• 22. Define WIT interface (src/core/wit/perry-container.wit)

  • Declare all container functions: run, create, start, stop, remove, list, inspect, logs, exec, pull-image, list-images, remove-image, get-backend, detect-backend, compose-up
  • Declare compose handle functions: compose-down, compose-ps, compose-logs, compose-exec
  • Declare workload graph functions: run-graph, inspect-graph, graph-handle-down, graph-handle-status, graph-handle-graph, graph-handle-logs, graph-handle-exec, graph-handle-ps
  • Define WIT record types for ContainerSpec, ContainerHandle, ContainerInfo, ContainerLogs, ImageInfo, BackendInfo
  • Define WIT record types for WorkloadNode, WorkloadGraph, RunGraphOptions, GraphStatus, NodeInfo
  • Add compiler build check that fails if WIT diverges from TypeScript type declarations
  • Requirements: 17.1, 17.2, 17.3, 17.4, 17.5, 17.6

• 23. Implement mock backend for functional tests (crates/perry-container-compose/src/testing/mock_backend.rs)

  • 23.1 Create crates/perry-container-compose/src/testing/ module and mock_backend.rs

    • Implement MockBackend struct that implements ContainerBackend trait
    • Add a call recorder (Vec<RecordedCall>) that captures method name + arguments for each invocation
    • Add a scripted response queue (VecDeque<MockResponse>) that returns pre-configured Result values in order
    • Implement all ContainerBackend methods: each method records the call and pops the next scripted response (or returns a default Ok if the queue is empty)
    • Expose MockBackend::calls() -> &[RecordedCall] for test assertions
    • Expose MockBackend::push_response(response: MockResponse) for scripting return values
    • Requirements: 11.1

  • 23.2 Create test fixtures directory (crates/perry-container-compose/tests/fixtures/)

    • Add sample compose YAML files: simple-two-service.yaml, diamond-deps.yaml, cyclic-deps.yaml
    • Add sample ComposeSpec JSON: simple-two-service.json
    • Add sample WorkloadGraph JSON: two-node-graph.json
    • Requirements: 6.4, 6.5

• 24. Implement functional tests (crates/perry-container-compose/tests/functional/)

  • 24.1 Implement functional/compose_engine_test.rs

    • up_creates_networks_before_containers — mock records call order; assert create_network precedes all run calls
    • up_creates_volumes_before_containers — assert create_volume precedes all run calls
    • up_starts_services_in_dependency_order — assert call order matches topological sort
    • up_rollback_on_service_failure — script third run to fail; assert first two containers stopped and removed
    • down_removes_containers_and_networks — assert remove and remove_network called for all resources
    • down_with_volumes_removes_named_volumes — assert remove_volume called when volumes: true
    • partial_continue_skips_failed_subtree — script worker to fail; assert nginx skipped, cache started
    • halt_graph_leaves_running_nodes — script api to fail; assert db NOT stopped
    • Requirements: 6.1, 6.4, 6.5, 6.8, 6.9, 6.10

  • 24.2 Implement functional/workload_graph_test.rs

    • policy_untrusted_sets_correct_flags — assert ContainerSpec has read_only: true, network: "none"
    • policy_isolated_sets_network_none — assert network: "none" in spec
    • policy_validation_rejects_container_backend_for_untrusted — mock reports IsolationLevel::Container; assert PolicyViolation
    • workload_ref_resolved_after_all_nodes_start — script mock ContainerInfo with IP/ports; assert env vars injected
    • edge_condition_healthy_waits_for_healthcheck — script inspect to return "starting" then "healthy"; assert dependent not started until healthy
    • edge_condition_completed_waits_for_exit_zero — script running then exited(0); assert dependent starts after exit
    • Requirements: 6.1, 6.4, 6.5

  • 24.3 Implement functional/backend_detection_test.rs

    • detect_backend_returns_first_available — mock first two probes unavailable, third available; assert third selected
    • detect_backend_env_override_skips_probing — set PERRY_CONTAINER_BACKEND=podman; assert no other probes run
    • detect_backend_all_unavailable_returns_error — all probes fail; assert NoBackendFound with all candidates listed
    • detect_backend_caches_result — call twice; assert probe function called only once
    • Requirements: 1.1, 1.2, 1.3, 1.5, 1.7, 18.1, 18.2, 18.3

• 25. Implement integration tests (crates/perry-container-compose/tests/integration/)

  • Gate all tests behind #[cfg(feature = "integration")]; skip unless PERRY_INTEGRATION_TESTS=1 env var is set

  • 25.1 Implement integration/container_lifecycle_test.rs

    • run_and_remove_alpine — run alpine:latest with echo hello, verify stdout, remove
    • create_start_stop_remove — full lifecycle with alpine:latest
    • list_shows_running_container — run, list, verify container appears
    • inspect_returns_running_status — run, inspect, verify status contains "running"
    • logs_captures_stdout — run container that prints, verify logs contain output
    • exec_runs_command_in_container — run alpine:latest, exec echo test, verify output
    • pull_image_succeeds — pull hello-world:latest, verify no error
    • list_images_shows_pulled_image — pull then list, verify image appears
    • Requirements: 2.1, 2.2, 2.3, 2.4, 2.5, 3.1, 3.2, 3.3, 4.1, 4.2, 5.1, 5.2

  • 25.2 Implement integration/compose_lifecycle_test.rs

    • compose_up_two_services — bring up two alpine services with dependency, verify both running
    • compose_down_removes_all — up then down, verify no containers remain
    • compose_ps_shows_services — up, ps, verify service names in output
    • compose_logs_returns_output — up service that prints, logs, verify output
    • compose_exec_runs_in_service — up, exec command in service, verify output
    • compose_down_volumes_removes_named_volumes — up with named volume, down --volumes, verify volume gone
    • Requirements: 6.1, 6.6, 6.7

  • 25.3 Implement integration/workload_graph_test.rs

    • run_graph_two_node_dependency — db + api with dependsOn, verify api starts after db
    • run_graph_workload_ref_resolves — db node, api node with DATABASE_URL: db.endpoint("5432"), verify env var set in api container
    • run_graph_rollback_on_failure — second node uses bad image, verify first node removed
    • run_graph_partial_continue — three nodes, middle fails, verify independent third node still starts
    • Requirements: 6.1, 6.4, 6.5, 6.8, 6.9, 6.10

  • 25.4 Add integration feature to crates/perry-container-compose/Cargo.toml

    • Add [features] integration = [] entry
    • Document in README: run with cargo test --features integration and PERRY_INTEGRATION_TESTS=1
    • Requirements: 11.3

• 26. Implement e2e test harness (tests/e2e/harness.rs)

  • 26.1 Implement tests/e2e/harness.rs

    • Implement compile_e2e(path: &str) -> Result<PathBuf> — invokes the Perry compiler on a .e2e.ts file and returns the path to the compiled binary
    • Implement run_e2e(binary: &Path) -> E2eResult — runs the binary, captures stdout/stderr, records exit code
    • Implement assert_e2e_pass(result: &E2eResult) — asserts exit code 0 and stdout contains [e2e] PASS
    • Implement assert_e2e_output(result: &E2eResult, pattern: &str) — asserts stdout matches a given pattern
    • Gate all e2e tests behind PERRY_E2E_TESTS=1 env var check; skip with eprintln!("[e2e] skipped") if not set
    • Requirements: 11.1, 11.4, 11.5

  • 26.2 Wire e2e test files into the harness

    • Add test entry for tests/e2e/container-basic.e2e.ts — asserts [e2e] PASS and all intermediate ✓ lines
    • Add test entry for tests/e2e/compose-forgejo.e2e.ts — asserts [e2e] PASS, postgres healthy, all services running
    • Add test entry for tests/e2e/workloads-graph.e2e.ts — asserts [e2e] PASS, graph healthy, 2 nodes, 1 edge
    • Add test entry for tests/e2e/workloads-policy.e2e.ts — asserts [e2e] PASS, isolated blocks network, hardened enforces read-only
    • Add test entry for tests/e2e/workloads-refs.e2e.ts — asserts [e2e] PASS, WorkloadRef resolved and injected
    • Requirements: 11.1, 11.4, 11.5

• 27. Add smoke test assertions and CI wiring

  • 27.1 Expand smoke tests in crates/perry-stdlib/src/container/mod.rs

    • Add #[test] fn smoke_module_init() — calls js_container_module_init(), asserts no panic
    • Add #[test] fn smoke_ffi_symbols_resolve() — verifies all symbols in NATIVE_MODULE_TABLE for perry/container, perry/container-compose, perry/compose, and perry/workloads resolve to defined functions (link-time check)
    • Requirements: 11.6

  • 27.2 Add perry check smoke test

    • Add a test that runs perry check on a minimal Perry program importing from perry/container, perry/container-compose, perry/compose, and perry/workloads
    • Assert exit code 0 and no "missing package" errors in output
    • Requirements: 11.4, 11.5, 11.8

  • 27.3 Add container test jobs to CI (.github/workflows/container-tests.yml)

    • The workflow file already exists at .github/workflows/container-tests.yml
    • Verify the workflow triggers correctly on changes to crates/perry-container-compose/** and crates/perry-stdlib/src/container/**
    • Confirm the container-tests-gate job is registered as a required status check in branch protection rules for main
    • Requirements: 11.3

• 28. Final checkpoint — Ensure all tests pass

  • Ensure all tests pass, ask the user if questions arise.

Notes

• Tasks marked with * are optional and can be skipped for faster MVP
• Each task references specific requirements for traceability
• Checkpoints ensure incremental validation
• Property tests use the proptest crate with a minimum of 100 iterations per property
• Each property test must include a comment: // Feature: perry-container, Property N: <property_text>
• Unit tests cover specific examples, edge cases, and error conditions alongside property tests
• Integration tests (gated behind #[cfg(feature = "integration")]) are out of scope for this task list
• Compose handle FFI symbols use the js_container_compose_* prefix (NOT js_compose_*)
• perry/compose is a valid alias for perry/container-compose in both HIR and codegen
• ComposeError in perry-container-compose/error.rs is the authoritative error type; ContainerError in perry-stdlib is a thin From<ComposeError> wrapper
• ContainerContext uses DashMap (not Mutex<HandleRegistry>) — add dashmap to perry-stdlib/Cargo.toml under the container feature
• Backend init uses async fn get_global_backend_instance() with tokio::sync::Mutex double-checked init (sync OnceLock::get_or_init() causes deadlocks in tokio context)
• Container naming uses hyphen separator: {md5_8chars}-{random_hex8} — the underscore format in the requirements.md introduction is a copy-paste artifact (C2 resolved)
• ComposeHandle is an opaque integer (stack ID) at the FFI boundary; method-chaining syntax (stack.down(), stack.ps()) is TS library sugar, not returned directly from FFI (C4 resolved)
• js_compose_* symbols are thin alias wrappers for js_container_compose_*; both are valid but js_container_compose_* is canonical
• perry/workloads is a planned future extension; workload.rs exists in HEAD but is not wired to compiler dispatch tables
• iOS uses the same backend priority list as macOS (cfg!(target_os = "ios") grouped with cfg!(target_os = "macos"))
• When no backend is found in an interactive terminal, get_global_backend_instance() invokes BackendInstaller::run() from installer.rs before returning an error; set PERRY_NO_INSTALL_PROMPT=1 to suppress this
• The interactive installer uses dialoguer + console crates, gated behind the installer Cargo feature to avoid binary size overhead in headless/embedded deployments

Design Document: perry/container

Overview

perry/container is the container management module for the Perry language, exposed via import { run, list, composeUp } from 'perry/container'. It provides a unified TypeScript API for OCI container lifecycle management, image operations, and multi-container orchestration, with automatic platform-adaptive backend selection.

The module is implemented as a Cargo feature-gated Rust library (container feature in crates/perry-stdlib) that bridges Perry TypeScript user code to native container runtimes via #[no_mangle] extern "C" FFI functions. Compose orchestration is backed by the perry-container-compose crate — a native Rust reimplementation of container-compose functionality that ships as both a standalone CLI binary and a library.

Primary API: perry/workloads

The primary TypeScript API surface is perry/workloads, a workload-graph-centric abstraction that replaces the container-centric mental model with a typed DAG of WorkloadNodes:

import { graph, node, runGraph, inspectGraph, runtime, policy } from 'perry/workloads';

perry/container remains available as a lower-level escape hatch for callers that need direct container lifecycle control, but new code should prefer perry/workloads. The Rust internals (ComposeEngine, ContainerBackend, CliBackend<P: CliProtocol>, ContainerContext, BackendDriver, IsolationLevel, detect_backend(), all FFI functions) are unchanged — perry/workloads is a new TypeScript-facing layer that maps onto the same Rust implementation.

Key Design Decisions

• Workload-graph-centric primary API: perry/workloads exposes graph(), node(), runGraph(), and inspectGraph() as the primary abstractions. Nodes declare typed dependsOn edges (not string references), and cross-node references (WorkloadRef) are resolved at graph-start time. perry/container remains as a lower-level escape hatch.
• RuntimeSpec for explicit runtime selection: The runtime helper (runtime.oci(), runtime.microvm(), runtime.wasm(), runtime.auto()) replaces the hidden detect_backend() call for callers that need explicit control. runtime.auto() preserves the existing auto-detection behavior.
• PolicySpec for per-node isolation: The policy helper (policy.isolated(), policy.hardened(), policy.untrusted(), policy.default()) expresses isolation intent at the TypeScript layer and maps to IsolationLevel in the Rust layer.
• WorkloadRef for typed cross-node references: node.endpoint(port), node.ip(), and node.internalUrl() return WorkloadRef values that are resolved to actual addresses after the graph starts, eliminating string-interpolated service discovery.
• GraphHandle replaces ComposeHandle at the workloads layer: GraphHandle exposes the same lifecycle methods as ComposeHandle but uses WorkloadGraph/GraphStatus types. ComposeHandle is retained for perry/container callers.
• Platform-adaptive backend: Rather than requiring users to configure a runtime, detect_backend() probes candidates in platform-specific priority order and caches the result. On macOS/iOS the preferred runtime is apple/container; on Linux/Windows it is podman.
• Single concrete backend implementation: CliBackend<P: CliProtocol> (implementing ContainerBackend) holds a protocol variant and delegates CLI argument construction internally. Protocol variants: DockerProtocol, AppleContainerProtocol, LimaProtocol { instance }. This avoids a proliferation of backend structs.
• Async backend init: async fn get_global_backend_instance() uses tokio::sync::Mutex double-checked initialisation — necessary because backend probing (subprocess checks) is inherently async and the sync OnceLock::get_or_init() variant causes deadlocks in a tokio context.
• In-process compose engine: ComposeEngine in perry-container-compose executes all orchestration logic in-process rather than shelling out to a compose CLI, giving full control over dependency ordering, error handling, and rollback.
• up() accepts file path or inline spec: The TypeScript up() API accepts either a JSON-serialised ComposeSpec object (inline definition) or a file path string (loaded by ComposeProject). File-path mode is used by the standalone CLI; inline mode is used from TS.
• OCI isolation for shellCapabilities: The same ContainerBackend used for user-facing API calls is reused for ephemeral capability containers, ensuring consistent security policy.
• ContainerBackend trait with ExecutionStrategy: To support API-native runtimes (containerd, future Firecracker/Kata/WASI backends) that are not CLI-invocable, the ContainerBackend trait abstracts over the runtime. An ExecutionStrategy enum (CliExec, ApiSocket, VmSpawn) makes the execution mechanism explicit. CliBackend<P: CliProtocol> is the concrete CLI implementation. CLI is now one backend variant, not the semantic model.
• IsolationLevel as explicit metadata: An IsolationLevel enum (None, Process, Container, MicroVm, Wasm) is carried on ContainerSpec, ComposeService, and BackendInfo. This makes isolation strength queryable from TypeScript and decouples the API from the assumption that OCI containers are the only execution model. It also addresses the security concern that isolation consistency is not guaranteed across backends (runc vs VM-backed vs gVisor-like).
• ComposeHandle graph and status exposure: ComposeHandle exposes graph(): ServiceGraph so TypeScript can inspect the resolved dependency graph, and status(): Promise<StackStatus> for partial-failure visibility. This surfaces the DAG resolution and rollback state that ComposeEngine already computes internally.
• ContainerContext for scoped state: A ContainerContext struct owns the backend selection result and handle registry, replacing the implicit process-global OnceLock and global handle map. A process-global default context preserves current single-context behavior; explicit context creation is available for future multi-tenant or test-isolation use cases.

---

Architecture

graph TD
    WL["Perry TypeScript\nimport { graph, node, runGraph } from 'perry/workloads'"]
    TS["Perry TypeScript\nimport { run, composeUp } from 'perry/container'\n(lower-level escape hatch)"]
    HIR["HIR Lowering\ncrates/perry-hir/src/lower.rs"]
    CG["Codegen Dispatch\ncrates/perry-codegen/src/lower_call.rs\nNATIVE_MODULE_TABLE"]
    FFI["FFI Layer\ncrates/perry-stdlib/src/container/mod.rs\njs_container_* / js_container_compose_* / js_workload_*"]
    CTX["ContainerContext\nbackend cache + DashMap handle registry"]
    TYPES["Types & Handles\ncrates/perry-stdlib/src/container/types.rs"]
    BACKEND["Backend Detection\ncrates/perry-container-compose/src/backend.rs\ndetect_backend() / ContainerBackend / CliBackend<P: CliProtocol>"]
    COMPOSE["WorkloadGraphEngine / ComposeEngine\ncrates/perry-container-compose/src/compose.rs"]
    VERIFY["Image Verification\ncrates/perry-stdlib/src/container/verification.rs"]
    CAP["Shell Capabilities\ncrates/perry-stdlib/src/container/capability.rs"]
    ADAPTER["ContainerBackend trait\nExecutionStrategy enum"]
    CLI["CliBackend<P: CliProtocol>"]
    APINATIVE["ApiSocket / VmSpawn\n(future: containerd, Firecracker, WASI)"]
    RUNTIME["Container Runtime\napple/container | podman | orbstack\ncolima | rancher-desktop | lima | nerdctl | docker"]

    WL --> HIR
    TS --> HIR
    HIR --> CG --> FFI
    FFI --> CTX
    CTX --> TYPES
    CTX --> BACKEND
    FFI --> COMPOSE
    COMPOSE --> BACKEND
    BACKEND --> ADAPTER
    ADAPTER --> CLI --> RUNTIME
    ADAPTER --> APINATIVE
    CAP --> VERIFY
    CAP --> ADAPTER
    FFI --> CAP

Loading

Layer Responsibilities

Layer	Crate / File	Responsibility
Workload Graph API	HIR + Codegen (perry/workloads)	Maps perry/workloads imports to js_workload_* FFI call sites; primary user-facing API
TypeScript API	HIR + Codegen (perry/container)	Maps perry/container imports to js_container_* FFI call sites (lower-level escape hatch)
FFI Bridge	perry-stdlib/src/container/mod.rs	#[no_mangle] C functions, Promise wrapping, JSON marshalling
ContainerContext	perry-stdlib/src/container/context.rs	Owns backend cache and DashMap handle registry; default global context + explicit context creation
Types & Handles	perry-stdlib/src/container/types.rs	Handle registry, ContainerError (thin wrapper over ComposeError), JSON helpers
Backend Detection	perry-container-compose/src/backend.rs	detect_backend(), ContainerBackend trait, CliBackend<P: CliProtocol>, BackendDriver, ExecutionStrategy
Compose Engine	perry-container-compose/src/compose.rs	ComposeEngine / WorkloadGraphEngine, topological sort, rollback, ServiceGraph, StackStatus
YAML Parsing	perry-container-compose/src/yaml.rs	CLI-only YAML parsing, env interpolation, file merging
Image Verification	perry-stdlib/src/container/verification.rs	cosign/Sigstore verification, digest cache
Shell Capabilities	perry-stdlib/src/container/capability.rs	perry_container_run_capability(), ephemeral containers

---

Components and Interfaces

Backend Detection (backend.rs)

detect_backend() -> Result<Box<dyn ContainerBackend>, ComposeError>
  └─ Reads PERRY_CONTAINER_BACKEND env var (override path)
  └─ Reads PERRY_CONTAINER_MODE env var (local-first / server-first)
  └─ Iterates platform_candidates() in priority order
  └─ Calls probe_candidate() for each (2s timeout)
  └─ Returns first BackendDriver that passes probe
  └─ Wraps in CliBackend<P: CliProtocol> (implements ContainerBackend)
  └─ Cached via async fn get_global_backend_instance() with tokio::sync::Mutex double-checked init

Platform-specific probe order — platform_candidates() returns candidates in this order:

Priority	macOS / iOS	Linux	Windows
1	apple/container — native macOS/iOS runtime	podman — daemonless, rootless; preferred over docker	podman — preferred over docker
2	orbstack — macOS-native VM, Docker-compatible	nerdctl — containerd CLI wrapper	nerdctl — containerd CLI wrapper
3	colima — macOS-native Lima-based runtime	docker — fallback only	docker — fallback only
4	rancher-desktop — macOS/cross-platform, containerd
5	lima — macOS VM runtime via limactl
6	podman — cross-platform; preferred over docker
7	nerdctl — containerd CLI wrapper
8	docker — lowest priority; fallback only

Note on iOS: iOS uses the same backend priority list as macOS (target_os = "ios" is grouped with target_os = "macos" in platform_candidates()). Both use apple/container as the preferred runtime.

Rationale: Platform-native runtimes (apple/container, orbstack, colima) are favored on macOS because they provide native OS integration and better performance. podman is favored over docker on all platforms because it is daemonless, rootless by default, and OCI-native without requiring a background daemon. docker is always last as a universal fallback.

BackendDriver enum — carries the resolved binary path for each runtime variant (ordered by macOS priority):

• AppleContainer { bin: PathBuf }
• Orbstack { bin: PathBuf }
• Colima { bin: PathBuf }
• RancherDesktop { bin: PathBuf }
• Lima { bin: PathBuf }
• Podman { bin: PathBuf }
• Nerdctl { bin: PathBuf }
• Docker { bin: PathBuf }

ExecutionStrategy enum — describes how a backend communicates with the runtime:

• CliExec { bin: PathBuf } — invoke a CLI binary via tokio::process::Command
• ApiSocket { socket: PathBuf } — communicate over a Unix domain socket (e.g. containerd gRPC)
• VmSpawn { config: VmConfig } — spawn a micro-VM (e.g. Firecracker, Kata, WASI)

ContainerBackend trait — the canonical abstraction over all container runtimes:

trait ContainerBackend: Send + Sync {
    fn backend_name(&self) -> &str;  // canonical method name (not fn name())
    async fn check_available(&self) -> Result<()>;
    async fn run(&self, spec: &ContainerSpec) -> Result<ContainerHandle>;
    async fn create(&self, spec: &ContainerSpec) -> Result<ContainerHandle>;
    async fn start(&self, id: &str) -> Result<()>;
    async fn stop(&self, id: &str, timeout: Option<u32>) -> Result<()>;
    async fn remove(&self, id: &str, force: bool) -> Result<()>;
    async fn list(&self, all: bool) -> Result<Vec<ContainerInfo>>;
    async fn inspect(&self, id: &str) -> Result<ContainerInfo>;
    async fn logs(&self, id: &str, tail: Option<u32>) -> Result<ContainerLogs>;
    async fn exec(&self, id: &str, cmd: &[String],
                  env: Option<&HashMap<String,String>>, workdir: Option<&str>) -> Result<ContainerLogs>;
    async fn build(&self, spec: &ComposeServiceBuild, image_name: &str) -> Result<()>;
    async fn pull_image(&self, reference: &str) -> Result<()>;
    async fn list_images(&self) -> Result<Vec<ImageInfo>>;
    async fn remove_image(&self, reference: &str, force: bool) -> Result<()>;
    async fn inspect_image(&self, reference: &str) -> Result<ImageInfo>;
    async fn create_network(&self, name: &str, config: &NetworkConfig) -> Result<()>;
    async fn remove_network(&self, name: &str) -> Result<()>;
    async fn create_volume(&self, name: &str, config: &VolumeConfig) -> Result<()>;
    async fn remove_volume(&self, name: &str) -> Result<()>;
    async fn inspect_network(&self, name: &str) -> Result<()>;
    // Lifecycle utilities
    async fn wait(&self, id: &str) -> Result<i32>;  // wait for container exit, returns exit code
}

CliBackend<P: CliProtocol> — the concrete ContainerBackend implementation for CLI-based runtimes. Protocol variants:

• DockerProtocol — docker/podman/orbstack/colima/nerdctl CLI protocol
• AppleContainerProtocol — apple/container CLI protocol
• LimaProtocol { instance } — limactl with a named instance

Note on build(): ContainerBackend::build() is implemented in CliBackend but is not yet wired to a TS FFI symbol (js_container_build is absent from the codegen dispatch table in HEAD). See Known Gaps section.

Note on inspect_image() and wait(): Both methods are present in the canonical trait definition. inspect_image() returns image metadata without pulling. wait() blocks until the container exits and returns its exit code — used by ComposeEngine for condition: "completed" edge semantics.

IsolationLevel enum — describes the actual isolation mechanism provided by a backend:

• None — no isolation (bare process)
• Process — OS-level process isolation only (e.g. namespaces without seccomp)
• Container — standard OCI container (runc/crun with seccomp + namespaces)
• MicroVm — VM-backed container (Kata Containers, Firecracker)
• Wasm — WebAssembly sandbox

Each BackendDriver variant maps to a default IsolationLevel; the level is surfaced in BackendInfo.isolationLevel so TypeScript callers can query what isolation the selected backend actually provides.

ContainerContext (context.rs)

ContainerContext owns the two pieces of global state that were previously implicit:

pub struct ContainerContext {
    backend: OnceLock<Arc<dyn ContainerBackend>>,
    handles: DashMap<u64, HandleEntry>,  // dashmap crate; replaces Mutex<HandleRegistry>
}

impl ContainerContext {
    /// Returns the process-global default context.
    pub fn global() -> &'static ContainerContext { ... }

    /// Creates a new isolated context (for tests or multi-tenant use).
    pub fn new() -> Self { ... }
}

Dependency note: Add dashmap to perry-stdlib/Cargo.toml (feature-gated under container).

The FFI layer always routes through ContainerContext::global() for normal operation, preserving existing behavior. Tests and future multi-tenant scenarios can create independent ContainerContext instances whose backend caches and handle registries are fully isolated from each other and from the global context.

Async init: Backend initialisation uses async fn get_global_backend_instance() with a tokio::sync::Mutex double-checked init pattern — necessary because backend probing is inherently async and the sync OnceLock::get_or_init() variant causes deadlocks in a tokio context.

FFI Bridge (mod.rs)

All public TypeScript functions are implemented as #[no_mangle] pub unsafe extern "C" functions. Async operations return *mut Promise and use spawn_for_promise(). String arguments cross the boundary as *const StringHeader (Perry runtime string layout); results are serialized to JSON and returned as *const StringHeader.

Key FFI functions:

FFI Symbol	TypeScript API	Args (Perry ABI)	Return
js_container_run	run(spec)	(*StringHeader)	*mut Promise
js_container_create	create(spec)	(*StringHeader)	*mut Promise
js_container_start	start(id)	(*StringHeader)	*mut Promise
js_container_stop	stop(id, timeout?)	(*StringHeader, *StringHeader)	*mut Promise
js_container_remove	remove(id, force?)	(*StringHeader, *StringHeader)	*mut Promise
js_container_list	list(all?)	(*StringHeader)	*mut Promise
js_container_inspect	inspect(id)	(*StringHeader)	*mut Promise
js_container_logs	logs(id, tail?)	(*StringHeader, *StringHeader)	*mut Promise
js_container_exec	exec(id, cmd, env?, workdir?)	(*STR, *STR, *STR, *STR)	*mut Promise
js_container_pullImage	pullImage(reference)	(*StringHeader)	*mut Promise
js_container_listImages	listImages()	()	*mut Promise
js_container_removeImage	removeImage(reference, force?)	(*StringHeader, i32)	*mut Promise
js_container_getBackend	getBackend()	()	*const StringHeader
js_container_detectBackend	detectBackend()	()	*mut Promise
js_container_composeUp	up(spec | path)	(*StringHeader)	*mut Promise
js_container_compose_down	handle.down(volumes?)	(i64, i32)	*mut Promise
js_container_compose_ps	handle.ps()	(i64)	*mut Promise
js_container_compose_logs	handle.logs(service?, tail?)	(i64, *STR)	*mut Promise
js_container_compose_exec	handle.exec(service, cmd)	(i64, *STR, *STR, *STR)	*mut Promise
js_container_compose_config	handle.config()	(i64)	*mut Promise
js_container_compose_start	handle.start(services?)	(i64, *STR)	*mut Promise
js_container_compose_stop	handle.stop(services?)	(i64, *STR)	*mut Promise
js_container_compose_restart	handle.restart(services?)	(i64, *STR)	*mut Promise
js_container_compose_graph	handle.graph()	(i64)	*const StringHeader
js_container_compose_status	handle.status()	(i64)	*mut Promise

perry/compose alias symbols — thin wrappers that call the js_container_compose_* equivalents. Both symbol families are valid; js_container_compose_* is canonical:

FFI Symbol (alias)	Delegates to
js_compose_up	js_container_composeUp
js_compose_down	js_container_compose_down
js_compose_ps	js_container_compose_ps
js_compose_logs	js_container_compose_logs
js_compose_exec	js_container_compose_exec
js_compose_config	js_container_compose_config
js_compose_start	js_container_compose_start
js_compose_stop	js_container_compose_stop
js_compose_restart	js_container_compose_restart

Note on js_container_build: ContainerBackend::build() is implemented in the backend but no js_container_build FFI symbol exists in the codegen dispatch table in HEAD. Wiring this symbol is a known gap (see Known Gaps section).

Workload Graph FFI Functions (perry/workloads)

FFI Symbol	TypeScript API
js_workload_graph	graph(name, builder)
js_workload_node	node(name, spec)
js_workload_runGraph	runGraph(graph, opts?)
js_workload_inspectGraph	inspectGraph(graph)
js_workload_handle_down	handle.down(opts?)
js_workload_handle_status	handle.status()
js_workload_handle_graph	handle.graph()
js_workload_handle_logs	handle.logs(node?, opts?)
js_workload_handle_exec	handle.exec(node, cmd)
js_workload_handle_ps	handle.ps()

ComposeEngine (compose.rs)

State model:

pub struct ComposeEngine {
    pub spec: ComposeSpec,
    pub project_name: String,
    pub backend: Arc<dyn ContainerBackend>,
    session_containers: Mutex<Vec<String>>,  // tracked for rollback
    session_networks:   Mutex<Vec<String>>,
    session_volumes:    Mutex<Vec<String>>,
}

A global registry maps stack_id: u64 → Arc<ComposeEngine>. FFI functions index into this registry. NEXT_STACK_ID is an AtomicU64. The ComposeHandle returned to TypeScript is this opaque integer stack ID — method-chaining syntax (stack.down(), stack.ps()) is implemented at the TypeScript library layer, not returned directly from the FFI.

ComposeEngine::up(spec: ComposeSpec) -> Result<ComposeHandle>
  1. resolve_startup_order(spec)  — topological sort, returns Err(DependencyCycle) on cycle
  2. create_networks()            — create all top-level networks
  3. create_volumes()             — create all named volumes
  4. for each service in order:
       start_service()            — on failure: rollback all started containers
  5. register engine in ContainerContext handle registry, return ComposeHandle

resolve_startup_order is a free function resolve_startup_order(spec: &ComposeSpec) in production code (compose.rs). A method delegate ComposeEngine::resolve_startup_order() that calls the free function MUST also be added for test compatibility (resolves C-6). It implements Kahn's algorithm over the depends_on graph, returning services in an order where each service appears after all its declared dependencies. The resolved graph is stored as a ServiceGraph on the engine and accessible via ComposeHandle.graph().

Container Naming Convention

Canonical format: {md5_8chars}-{random_hex8} (hyphen separator)

• md5_8chars = first 8 hex chars of MD5(service YAML or image name)
• random_hex8 = random u32 formatted as 8-char hex
• Example: a3f2b1c9-00e4f2a1

Conflict note (C2): The requirements.md introduction paragraph uses {name}_{hash} (underscore). The canonical implementation in HEAD uses hyphen separator. The hyphen format is authoritative. The underscore format in requirements.md is a copy-paste artifact from early drafts.

If container_name is set in the compose service or name is set in ContainerSpec, that value takes precedence over auto-generation.

• graph(): ServiceGraph — returns the resolved dependency graph as an adjacency structure, allowing TypeScript callers to inspect startup order and service relationships without re-parsing the spec.
• status(): Promise<StackStatus> — returns the current state of every service in the stack, including partial-failure information (which services are running, stopped, failed, or pending).

ServiceGraph — a serializable representation of the resolved DAG:

interface ServiceGraph {
  nodes: string[];                        // service names in topological order
  edges: Array<{ from: string; to: string }>; // dependency edges (from depends on to)
}

StackStatus — per-service status snapshot:

type ServiceState = "running" | "stopped" | "failed" | "pending" | "unknown";

interface ServiceStatus {
  service: string;
  state: ServiceState;
  containerId?: string;
  error?: string;
}

interface StackStatus {
  services: ServiceStatus[];
  healthy: boolean; // true iff all services are "running"
}

WIT Interface (src/core/wit/perry-container.wit)

The WIT interface declares all container and compose operations as WIT function signatures. It defines record types for ContainerSpec, ContainerHandle, ContainerInfo, ContainerLogs, ImageInfo, and BackendInfo. The compiler build fails if the WIT interface diverges from the TypeScript type declarations.

HIR Lowering and Codegen

HIR Lowering and Codegen

lower.rs recognises import { ... } from 'perry/container' and import { ... } from 'perry/container-compose' and maps each imported name to its js_container_* / js_container_compose_* FFI declaration, following the same pattern as perry/thread and perry/ui.

perry/compose alias: lower.rs also maps perry/compose as an accepted alias for perry/container-compose (SPEC.md §5.5). Both import paths are valid; perry/container-compose is canonical.

lower_call.rs (not codegen.rs) emits direct call instructions to the FFI symbols for all perry/container and perry/container-compose call sites, using the static NATIVE_MODULE_TABLE (not PERRY_UI_TABLE) dispatch table.

---

---

Go Reference Project Architecture

This section documents the architecture of the Go container-compose/cli reference project and how it maps to the Rust implementation in perry-container-compose.

Original Go File Structure

File	Size	Description
internal/entities/service.go	9256 bytes	Service entity — fields and all service lifecycle methods
internal/entities/compose.go	300 bytes	Compose struct with a services map
internal/commands/build.go	4033 bytes	BuildCommand interface
internal/commands/inspect.go	3221 bytes	InspectCommand interface
internal/commands/run.go	1517 bytes	RunCommand interface
internal/commands/start.go	731 bytes	StartCommand interface
internal/commands/stop.go	724 bytes	StopCommand interface
cmd/start/cmd.go	—	Start command orchestration logic

Service Entity Design

Ported from internal/entities/service.go (9256 bytes):

// Ported from internal/entities/service.go (9256 bytes)
pub struct Service {
    pub image: Option<String>,
    pub name: Option<String>,           // container_name in YAML
    pub ports: Option<Vec<String>>,
    pub environment: Option<ListOrDict>,
    pub labels: Option<ListOrDict>,
    pub volumes: Option<Vec<String>>,
    pub build: Option<ServiceBuild>,
}

pub struct ServiceBuild {
    pub context: String,
    pub dockerfile: Option<String>,
    pub args: Option<HashMap<String, String>>,
    pub labels: Option<ListOrDict>,
    pub target: Option<String>,
    pub network: Option<String>,
}

Command Interface Design

Ported from internal/commands/*.go:

// Ported from internal/commands/*.go
#[async_trait]
pub trait ContainerCommand: Send + Sync {
    async fn exec(&self, ctx: &Context) -> Result<(), ComposeError>;
}

pub struct BuildCommand { /* ... */ }
pub struct RunCommand { /* ... */ }
pub struct StartCommand { /* ... */ }
pub struct StopCommand { /* ... */ }
pub struct InspectCommand { /* ... */ }

Service Management Flow

Ported from cmd/start/cmd.go:

// Ported from cmd/start/cmd.go
pub async fn orchestrate_service(service: &Service, backend: &dyn ContainerBackend) -> Result<(), ComposeError> {
    if service.is_running(backend).await? {
        tracing::info!(service = %service.name(), "already running, skipping");
        return Ok(());
    }
    if service.exists(backend).await? {
        tracing::info!(service = %service.name(), "exists but stopped, starting");
        service.start_command(backend).await?;
    } else {
        if service.needs_build() {
            tracing::info!(service = %service.name(), "building image");
            service.build_command(backend).await?;
        }
        tracing::info!(service = %service.name(), "creating and running");
        service.run_command(backend).await?;
    }
    Ok(())
}

This orchestrate_service() function lives in crates/perry-container-compose/src/orchestrate.rs and is the per-service startup function called by ComposeEngine::up() for each service in topological order.

Go→Rust Dependency Mapping

Go Dependency	Rust Replacement	Notes
github.com/spf13/cobra	clap	CLI framework
gopkg.in/yaml.v3	serde_yaml	YAML parsing
github.com/goombaio/namegenerator	Custom MD5-based	generate_name(image, service_name)
context.Context	tokio async/await	Async runtime
error interface	Result<T, ComposeError> + thiserror	Error handling
log/slog	tracing	Structured logging
os.Exec	tokio::process::Command	Process execution
os.ReadFile	std::fs::read_to_string	File I/O

Feature Gap Table

Feature	Go (container-compose/cli)	Rust (perry-container-compose)
image field	✅	✅
build field (context, dockerfile, args, labels, target, network)	✅	✅
ports field	✅	✅
environment field	✅ Basic	✅ + interpolation + .env
labels field	✅	✅
volumes field (service-level)	✅	✅
container_name field	✅	✅
Container state management (running/stopped/not-exists)	✅	✅
Automatic build when needed	✅	✅
networks top-level field	❌	✅
volumes top-level field	❌	✅
depends_on + dependency resolution	❌	✅ Kahn's algorithm
Environment variable interpolation ${VAR}	❌	✅
.env file loading	❌	✅
Multiple compose file merging	❌	✅
Project names (-p)	❌	✅
ps command	❌	✅
logs command	❌	✅
exec command	❌	✅
config command	❌	✅
down command	❌	✅
stop command	❌	✅
restart command	❌	✅
Port mapping in run	❌	✅
Volume mounting in run	❌	✅
Multi-runtime support (podman, orbstack, etc.)	❌ Apple Container only	✅ All backends

---

Workload Graph API (perry/workloads)

The perry/workloads module is the primary TypeScript API for declaring and running multi-node workloads. It maps onto the same Rust internals as perry/container but exposes a graph-centric model where nodes are typed values, edges are explicit dependsOn references, and cross-node addresses are resolved via WorkloadRef.

graph(name, builder)

Declares a named WorkloadGraph — a typed DAG of WorkloadNodes:

const app = graph("my-app", (g) => {
  const db = g.node("db", {
    image: "postgres:16",
    ports: ["5432:5432"],
    env: { POSTGRES_PASSWORD: "secret" },
  });

  const api = g.node("api", {
    image: "my-api:latest",
    dependsOn: [db],
    env: {
      DATABASE_URL: db.endpoint("5432"),
    },
  });

  return { db, api };
});

The builder function receives a graph builder g and returns a record of named WorkloadNode values. The returned nodes are accessible as typed properties on the graph handle after runGraph().

node(name, spec)

Creates a standalone WorkloadNode. Accepts:

• image?: string
• resources?: { cpu?: string; memory?: string }
• ports?: string[]
• env?: Record<string, string | WorkloadRef>
• dependsOn?: WorkloadNode[] — typed graph edges (not string references)
• runtime?: RuntimeSpec — explicit runtime selection (defaults to runtime.auto())
• policy?: PolicySpec — per-node isolation policy (defaults to policy.default())

runGraph(graph, opts?)

Executes the graph. Returns a GraphHandle:

const handle = await runGraph(app, {
  strategy: "dependency-aware",  // "sequential" | "max-parallel" | "dependency-aware" | "parallel-safe"
  onFailure: "rollback-all",     // "rollback-all" | "partial-continue" | "halt-graph"
});

Internally delegates to WorkloadGraphEngine (the ComposeEngine under a workload-graph framing), which performs topological sort, network/volume creation, and rollback on failure — identical to composeUp().

inspectGraph(graph)

Returns a GraphStatus snapshot without starting the graph:

const state = await inspectGraph(app);
// { nodes: { api: "running", db: "running", worker: "failed" }, healthy: boolean }

runtime.*

Explicit runtime selection. Maps to IsolationLevel and ExecutionStrategy in the Rust layer:

Helper	Maps to
runtime.oci()	IsolationLevel::Container + ExecutionStrategy::CliExec (existing CliBackend)
runtime.microvm()	IsolationLevel::MicroVm + ExecutionStrategy::VmSpawn
runtime.wasm()	IsolationLevel::Wasm + ExecutionStrategy::VmSpawn
runtime.auto()	detect_backend() auto-detection (current default behavior)

policy.*

Per-node or per-graph isolation policy. Maps to IsolationLevel and ContainerSpec fields:

Helper	Behavior
policy.default()	No special policy; inherits backend defaults
policy.isolated()	Graph-wide isolation; no cross-node network by default
policy.hardened({ noNetwork?, readOnlyRoot?, seccomp? })	Hardened container with explicit flags
policy.untrusted()	Maximum isolation; forces runtime.microvm()

GraphHandle

Replaces ComposeHandle at the perry/workloads layer. ComposeHandle is retained for perry/container callers.

interface GraphHandle {
  down(opts?: { volumes?: boolean }): Promise<void>;
  status(): Promise<GraphStatus>;
  graph(): WorkloadGraph;
  logs(node?: string, opts?: { tail?: number }): Promise<ContainerLogs>;
  exec(node: string, cmd: string[]): Promise<ContainerLogs>;
  ps(): Promise<NodeInfo[]>;
}

WorkloadGraphEngine Execution Model

WorkloadGraphEngine::run() applies RunGraphOptions.strategy to determine parallelism within topological levels. This section describes the full execution model.

Topological Level Batching

Kahn's algorithm naturally produces levels — sets of nodes that have no dependency on each other within the same level. The engine groups nodes into levels before execution:

Level 0: [db, cache]          — no dependencies
Level 1: [api, worker]        — depend on level 0 nodes
Level 2: [nginx]              — depends on api

All nodes within the same level are candidates for parallel execution; nodes in different levels have an ordering constraint.

Strategy Semantics

Each RunGraphOptions.strategy maps to a specific execution policy over these levels:

• "sequential" — start one node at a time, in topological order. Wait for each node to reach "running" before starting the next. Slowest but most predictable; useful for debugging.
• "dependency-aware" (default) — start all nodes within the same topological level in parallel. Wait for all nodes in a level to reach "running" before advancing to the next level. This is the standard compose-style behavior.
• "max-parallel" — start all nodes simultaneously, ignoring level boundaries. The engine still enforces dependsOn constraints by polling node state before starting dependents, but does not wait for full level completion. Maximum throughput; higher risk of resource contention.
• "parallel-safe" — like "dependency-aware" but adds a configurable inter-level delay (default 500ms) to allow services time to bind ports and initialize before dependents start. Useful for services with slow startup that don't implement healthchecks.

WorkloadRef Resolution Timing

WorkloadRef values in node env fields are resolved after all nodes in the graph have reached "running" state, not during startup. The resolution sequence is:

1. All nodes start (per strategy)
2. Engine calls ContainerBackend::inspect(id) for each node to get its ContainerInfo
3. For each WorkloadRef in each node's env:
   • Endpoint projection: looks up the port mapping in ContainerInfo.ports, returns "<host_ip>:<host_port>"
   • Ip projection: returns the container's network IP from ContainerInfo
   • InternalUrl projection: returns "http://<container_ip>:<first_exposed_port>"
4. Resolved values are injected into the running container's environment via ContainerBackend::exec with env override, OR stored in the GraphHandle for use by the caller
5. If a WorkloadRef cannot be resolved (node not running, port not mapped), the engine returns ComposeError::WorkloadRefResolutionFailed { node_id, projection, reason }

onFailure Compensation Flow

When a node fails to start, the engine applies RunGraphOptions.onFailure:

• "rollback-all" (default) — immediately stop and remove all previously started nodes in the graph, in reverse topological order. Remove all networks and volumes created for this graph. Reject the runGraph() promise with ComposeError::ServiceStartupFailed identifying the failed node.
• "halt-graph" — stop starting new nodes. Leave already-running nodes running. Reject the promise with the failure error. The GraphHandle is still returned but in a partial state; handle.status() will show which nodes are running and which failed.
• "partial-continue" — log the failure, skip the failed node and all nodes that transitively depend on it, continue starting the remaining independent nodes. Resolve the promise with a GraphHandle in partial state. The caller must check handle.status().healthy to detect partial failures.

Execution Loop (Rust Pseudocode)

async fn run_graph(graph: &WorkloadGraph, opts: &RunGraphOptions) -> Result<GraphHandle> {
    let levels = compute_topological_levels(graph)?;  // Kahn's → Vec<Vec<NodeId>>
    let mut started: Vec<NodeId> = vec![];

    'outer: for level in &levels {
        let nodes_to_start = match opts.strategy {
            Sequential => level.iter().take(1).collect(),
            DependencyAware | ParallelSafe => level.clone(),
            MaxParallel => level.clone(),  // all levels merged in pre-pass
        };

        let results = join_all(nodes_to_start.iter().map(|id| start_node(id))).await;

        for (id, result) in nodes_to_start.iter().zip(results) {
            match result {
                Ok(_) => started.push(id.clone()),
                Err(e) => match opts.on_failure {
                    RollbackAll => { rollback(&started).await; return Err(e); }
                    HaltGraph  => { return Err(e); }  // leave started nodes running
                    PartialContinue => { skip_subtree(id, graph); continue; }
                }
            }
        }

        if opts.strategy == ParallelSafe { sleep(Duration::from_millis(500)).await; }
    }

    resolve_workload_refs(graph, &started).await?;
    Ok(register_handle(graph, started))
}

---

Policy Enforcement Mechanics

WorkloadGraphEngine enforces PolicySpec at two points: graph-time validation (before any node starts) and per-node translation (when calling ContainerBackend::run()).

Graph-Time Validation

Before any node starts, WorkloadGraphEngine validates policy consistency across the graph:

1. If any node has policy.untrusted(), verify that the selected backend supports IsolationLevel::MicroVm. If not, reject with ComposeError::PolicyViolation { node, required: MicroVm, available: Container }.
2. If policy.isolated() is set at the graph level, verify no node declares network_mode: "host" — that would bypass isolation.
3. If a node has policy.hardened() with readOnlyRoot: true, verify the node's volumes list doesn't mount the root filesystem as writable.

Per-Tier Enforcement Mapping

Each PolicyTier maps to a specific set of ContainerSpec flags passed to ContainerBackend::run():

Tier	read_only	network	seccomp	runtime forced
default	false	default	default	none
isolated	false	"none"	default	none
hardened	true	default	"strict"	none
untrusted	true	"none"	"strict"	MicroVm

The isolated tier sets network: "none" on the ContainerSpec, which maps to --network none in the CLI. This prevents the container from making any network connections, including to other nodes in the graph.

Trust Tier Propagation

If a node with policy.untrusted() declares dependsOn: [trustedNode], the engine emits a warning: a trusted node is exposing its endpoint to an untrusted node. The engine does NOT block this (the user may intend it), but logs it at warn level with the message:

"WorkloadGraph trust boundary crossing: untrusted node '{id}' depends on trusted node '{dep_id}'"

Policy Enforcement at the FFI Boundary

WorkloadGraphEngine translates PolicySpec to ContainerSpec fields before calling ContainerBackend::run(). The translation is a pure function:

fn policy_to_container_flags(policy: &PolicySpec) -> ContainerFlags

This returns the set of flags to merge into the ContainerSpec. Keeping policy logic in this pure translation function — rather than inside the backend layer — ensures that policy enforcement is testable in isolation and that backend implementations remain unaware of policy semantics.

---

Dependency Edge Semantics

The WorkloadGraph.edges field carries enriched WorkloadEdge values that go beyond bare structural { from, to } pairs. These edges encode startup conditions, trust boundary acknowledgments, and advisory placement hints.

Enriched WorkloadEdge Type

interface WorkloadEdge {
  from: string;           // dependent node ID
  to: string;             // dependency node ID

  // Startup condition (mirrors compose-spec depends_on conditions)
  condition?: "started" | "healthy" | "completed";  // default: "started"

  // Trust constraint — the engine warns if trust tiers cross a boundary
  trustBoundary?: boolean;  // true = explicit acknowledgment of cross-trust dependency

  // Locality hint — advisory, not enforced; used by future schedulers
  locality?: "same-host" | "same-network" | "any";  // default: "any"

  // Latency hint — advisory; used by future schedulers for placement
  latencyClass?: "realtime" | "interactive" | "batch";  // default: "interactive"
}

The WorkloadGraph.edges type is updated from Array<{ from: string; to: string }> to Array<WorkloadEdge>.

Condition Semantics

The condition field on an edge determines when the dependency is considered satisfied:

• "started" (default) — the dependency node's container has started (equivalent to service_started in compose-spec). The engine polls ContainerBackend::inspect() until status is not "created" or "starting".
• "healthy" — the dependency node's healthcheck has passed. The engine polls ContainerBackend::inspect() until the healthcheck status is "healthy". If the node has no healthcheck defined, this condition is treated as "started".
• "completed" — the dependency node's container has exited with code 0. Used for init containers or migration jobs that must complete before the main service starts.

How Edges Are Built from the TypeScript API

When a user writes dependsOn: [db] in the node() builder, the engine creates a WorkloadEdge with condition: "started" by default. For richer conditions, the user can write:

const api = g.node("api", {
  image: "my-api:latest",
  dependsOn: [
    { node: db, condition: "healthy" },           // wait for healthcheck
    { node: migrator, condition: "completed" },   // wait for migration job
  ],
});

The dependsOn field on WorkloadNode is updated to accept either WorkloadNode[] (shorthand, defaults to condition: "started") or Array<{ node: WorkloadNode; condition?: "started" | "healthy" | "completed" }> (explicit form).

Advisory Hints and Future Scheduler Integration

locality and latencyClass are advisory — the current WorkloadGraphEngine logs them at debug level but does not enforce them. They are designed as forward-compatible hooks for a future placement scheduler that could use them to co-locate latency-sensitive nodes or separate batch workloads. The engine stores them in the WorkloadGraph and surfaces them via GraphHandle.graph() so external tooling can inspect the declared intent.

---

API Mapping: Old → New

Old API (perry/container)	New API (perry/workloads)
composeUp(ComposeSpec)	runGraph(WorkloadGraph)
ComposeSpec.services	graph() builder nodes
depends_on: ["db"]	dependsOn: [db] (typed edge)
ContainerBackend auto-detect	runtime.auto()
IsolationLevel.Container	runtime.oci()
IsolationLevel.MicroVm	runtime.microvm()
IsolationLevel.Wasm	runtime.wasm()
ComposeHandle	GraphHandle
ComposeHandle.status()	GraphHandle.status() / inspectGraph()
ComposeHandle.graph()	GraphHandle.graph()
run(ContainerSpec)	node() + runGraph() for single-node graphs, or keep run() in perry/container

---

Data Models

Core Types (defined in perry-container-compose/src/types.rs, re-exported by perry-stdlib)

interface ContainerSpec {
  image: string;       // required
  name?: string;
  ports?: string[];    // "host:container" format
  volumes?: string[];
  env?: Record<string, string>;
  cmd?: string[];
  entrypoint?: string[];
  network?: string;
  rm?: boolean;
  // Security options
  read_only?: boolean;       // mount root as read-only
  seccomp?: string;         // custom seccomp profile path
  privileged?: boolean;      // run in privileged mode
  user?: string;            // username or UID:GID
  workdir?: string;         // working directory inside container
  cap_add?: string[];       // add Linux capabilities (e.g., ["NET_ADMIN"])
  cap_drop?: string[];      // drop Linux capabilities (e.g., ["ALL"])
}

interface ContainerHandle { id: string; }

interface ContainerInfo {
  id: string;
  name: string;
  image: string;
  status: string;
  ports: string[];
  created: string; // ISO 8601
}

interface ContainerLogs {
  stdout: string;
  stderr: string;
}

interface ImageInfo {
  id: string;
  repository: string;
  tag: string;
  size: number;
  created: string; // ISO 8601
}

type IsolationLevel = "None" | "Process" | "Container" | "MicroVm" | "Wasm";

interface BackendInfo {
  name: string;
  available: boolean;
  reason?: string;
  version?: string;
  mode: "local" | "remote";
  isolationLevel: IsolationLevel; // actual isolation provided by this backend
}

// ContainerContext — scoped state container (Rust-side; opaque to TypeScript)
// Owns the backend OnceLock and handle registry.
// ContainerContext::global() returns the process-global default.
// ContainerContext::new() creates an isolated context for tests or multi-tenant use.

Compose Types (defined in perry-container-compose/src/types.rs)

The ComposeSpec type conforms to the official compose-spec JSON schema. Key types:

type ListOrDict = Record<string, string | number | boolean | null> | string[];

interface ComposeSpec {
  name?: string;
  version?: string;
  services: Record<string, ComposeService>;
  networks?: Record<string, ComposeNetwork>;
  volumes?: Record<string, ComposeVolume>;
  secrets?: Record<string, ComposeSecret>;
  configs?: Record<string, ComposeConfig>;
  // + include, models, x-* extension fields
}

interface ComposeService {
  image?: string;
  build?: string | ComposeServiceBuild;
  command?: string | string[];
  entrypoint?: string | string[];
  environment?: ListOrDict;
  ports?: Array<string | number | ComposeServicePort>;
  volumes?: Array<string | ComposeServiceVolume>;
  networks?: string[] | Record<string, ComposeServiceNetworkConfig>;
  depends_on?: string[] | Record<string, ComposeDependsOn>;
  healthcheck?: ComposeHealthcheck;
  deploy?: ComposeDeployment;
  isolationLevel?: IsolationLevel; // per-service isolation override
  // ... full compose-spec service fields
}

interface ComposeDependsOn {
  condition: "service_started" | "service_healthy" | "service_completed_successfully";
  required?: boolean;
  restart?: boolean;
}

interface ComposeServiceVolume {
  type: "bind" | "volume" | "tmpfs" | "cluster" | "npipe" | "image";
  source?: string;
  target?: string;
  read_only?: boolean;
  // ... bind, volume, tmpfs, image sub-options
}

// ServiceGraph — resolved dependency DAG returned by ComposeHandle.graph()
interface ServiceGraph {
  nodes: string[];                             // service names in topological order
  edges: Array<{ from: string; to: string }>; // dependency edges (from depends on to)
}

// StackStatus — per-service state snapshot returned by ComposeHandle.status()
type ServiceState = "running" | "stopped" | "failed" | "pending" | "unknown";

interface ServiceStatus {
  service: string;
  state: ServiceState;
  containerId?: string;
  error?: string;
}

interface StackStatus {
  services: ServiceStatus[];
  healthy: boolean; // true iff all services are "running"
}

Workload Graph Types (defined in perry-stdlib/src/container/workload.rs)

These types are the primary data model for perry/workloads. They are serialized across the FFI boundary as JSON, the same as all other container types.

// RuntimeSpec — explicit runtime selection
type RuntimeSpec =
  | { type: "oci" }
  | { type: "microvm"; config?: MicroVmConfig }
  | { type: "wasm"; module?: string }
  | { type: "auto" };

// PolicySpec — per-node isolation policy
interface PolicySpec {
  tier: "default" | "isolated" | "hardened" | "untrusted";
  noNetwork?: boolean;
  readOnlyRoot?: boolean;
  seccomp?: boolean;
}

// WorkloadRef — typed cross-node reference, resolved after graph start
interface WorkloadRef {
  nodeId: string;
  projection: "endpoint" | "ip" | "internalUrl";
  port?: string;
}

// WorkloadNode — the primary graph node type
interface WorkloadNode {
  id: string;
  name: string;
  image?: string;
  resources?: { cpu?: string; memory?: string };
  ports?: string[];
  env?: Record<string, string | WorkloadRef>;
  dependsOn?: string[]; // resolved node IDs
  runtime: RuntimeSpec;
  policy: PolicySpec;
}

// WorkloadGraph — the primary graph type
interface WorkloadGraph {
  name: string;
  nodes: Record<string, WorkloadNode>;
  edges: Array<{ from: string; to: string }>;
}

// RunGraphOptions
interface RunGraphOptions {
  strategy?: "sequential" | "max-parallel" | "dependency-aware" | "parallel-safe";
  onFailure?: "rollback-all" | "partial-continue" | "halt-graph";
}

// GraphStatus — per-node state snapshot returned by GraphHandle.status() / inspectGraph()
type NodeState = "running" | "stopped" | "failed" | "pending" | "unknown";
interface GraphStatus {
  nodes: Record<string, NodeState>;
  healthy: boolean;
  errors?: Record<string, string>;
}

// NodeInfo — returned by GraphHandle.ps()
interface NodeInfo {
  nodeId: string;
  name: string;
  containerId?: string;
  state: NodeState;
  image?: string;
}

// GraphHandle — returned by runGraph(); replaces ComposeHandle at the perry/workloads layer
interface GraphHandle {
  down(opts?: { volumes?: boolean }): Promise<void>;
  status(): Promise<GraphStatus>;
  graph(): WorkloadGraph;
  logs(node?: string, opts?: { tail?: number }): Promise<ContainerLogs>;
  exec(node: string, cmd: string[]): Promise<ContainerLogs>;
  ps(): Promise<NodeInfo[]>;
}

Error Model

ComposeError (in perry-container-compose/error.rs) is the authoritative error type. ContainerError in perry-stdlib is a thin compatibility wrapper with a From<ComposeError> for ContainerError conversion. The From impl converts between them at the FFI boundary.

Error envelope — all FFI results are serialized as JSON with this envelope:

{ "ok": true,  "result": <value> }
{ "ok": false, "error": "<message>" }

The legacy { "message": string, "code": number } shape is also accepted for backward compatibility with older callers.

Handle Registry

Opaque handles (ContainerHandle, ComposeHandle) are stored in a DashMap-backed handle registry (crates/perry-stdlib/src/common/handle.rs) and referenced by u64 IDs across the FFI boundary. This avoids passing Rust pointers to TypeScript. dashmap must be added as a dependency to perry-stdlib/Cargo.toml under the container feature.

---

Correctness Properties

A property is a characteristic or behavior that should hold true across all valid executions of a system — essentially, a formal statement about what the system should do. Properties serve as the bridge between human-readable specifications and machine-verifiable correctness guarantees.

Property-based testing is applicable here because the core logic — backend selection ordering, topological sort, CLI argument construction, serialization round-trips, and caching — consists of pure or near-pure functions with well-defined input/output behavior where input variation reveals edge cases.

Property 1: Backend Selection Respects Priority Order

For any set of mock backend probes where some candidates are available and some are not, detect_backend() SHALL return the first available candidate in the platform-specific priority order, never skipping an available candidate in favor of a lower-priority one.

Validates: Requirements 1.2, 16.1

Property 2: Backend Detection is Idempotent (OnceLock Caching)

For any process, calling detect_backend() multiple times SHALL return the same BackendDriver variant and binary path on every call after the first, regardless of any subsequent changes to the environment.

Validates: Requirements 1.7

Property 3: ContainerSpec CLI Argument Round-Trip

For any valid ContainerSpec, the CLI arguments produced by CliBackend::run_args() SHALL contain entries for every non-None field in the spec (image, name, ports, volumes, env vars, cmd, network, rm flag), and no field SHALL be silently dropped.

Validates: Requirements 2.7, 12.5

Property 4: Data Model Serialization Round-Trip

For any valid instance of ContainerSpec, ContainerInfo, ContainerLogs, or ImageInfo, serializing to JSON via serde_json::to_string() and deserializing back via serde_json::from_str() SHALL produce a value equal to the original.

Validates: Requirements 2.7, 3.4, 4.5, 5.4, 10.1, 12.5, 12.6

Property 5: ComposeSpec JSON Round-Trip

For any valid ComposeSpec object, serializing to JSON and deserializing back SHALL produce an equivalent ComposeSpec with all fields preserved, including nested ComposeService, ComposeNetwork, ComposeVolume, ComposeSecret, and ComposeConfig entries.

Validates: Requirements 10.13, 12.6

Property 6: YAML Round-Trip (CLI Path)

For any valid ComposeSpec, calling to_yaml() then ComposeSpec::parse_str() on the result SHALL produce a ComposeSpec equivalent to the original (all service definitions, network configs, volume configs, and top-level fields preserved).

Validates: Requirements 7.12

Property 7: Topological Sort Produces Valid Ordering

For any valid ComposeSpec whose depends_on graph is a DAG (no cycles), ComposeEngine::resolve_startup_order() SHALL return an ordering where every service appears strictly after all services it depends on, and every service in the spec appears exactly once in the result.

Validates: Requirements 6.4

Property 8: Cycle Detection is Exhaustive

For any ComposeSpec whose depends_on graph contains at least one cycle, ComposeEngine::resolve_startup_order() SHALL return Err(ComposeError::DependencyCycle) and the error SHALL identify at least one service that is part of the cycle.

Validates: Requirements 6.5

Property 9: Container Name Generation Uniqueness

For any two distinct (image_name, random_seed) pairs, the MD5-based container name generation algorithm SHALL produce different names, ensuring no two services in a compose stack receive the same container name.

Validates: Requirements 6.13

Property 10: Image Verification Caching is Idempotent

For any image reference, calling verify_image() multiple times SHALL return the same Result on every call after the first (either the same digest string or the same VerificationFailed error), demonstrating that the VERIFICATION_CACHE correctly prevents redundant verification work.

Validates: Requirements 15.4, 15.7

Property 11: BackendInfo Serialization Completeness

For any BackendProbeResult, serializing it to the BackendInfo JSON representation SHALL produce an object containing all required fields: name, available, and mode; and SHALL include reason when available is false.

Validates: Requirements 1.9

Property 12: depends_on Condition Validation

For any string value that is not one of "service_started", "service_healthy", or "service_completed_successfully", attempting to deserialize it as a DependsOnCondition SHALL return a parse error identifying the invalid value.

Validates: Requirements 7.14

Property 13: ComposeServiceVolume Type Validation

For any string value that is not one of "bind", "volume", "tmpfs", "cluster", "npipe", or "image", attempting to deserialize it as a VolumeType SHALL return a parse error identifying the invalid value.

Validates: Requirements 10.14

Property 14: Error Propagation Preserves Code and Message

For any ContainerError::BackendError { code, message }, converting to the JSON error representation via compose_error_to_json() SHALL produce a JSON object where the code field equals the original exit code and the message field contains the original message string.

Validates: Requirements 2.6, 12.2

Property 15: IsolationLevel Consistency

For any backend, the IsolationLevel reported in BackendInfo.isolationLevel SHALL match the actual isolation mechanism used when running containers via that backend — i.e., for any ContainerSpec submitted to a backend with a declared IsolationLevel, the backend adapter's strategy() and the resulting container runtime SHALL correspond to the same isolation tier.

Validates: Requirements 1.9, 1.10

Property 16: ContainerContext Isolation

For any two distinct ContainerContext instances, operations on one (handle registration, backend selection, handle lookup) SHALL NOT affect the handle registry or backend selection result of the other — including the process-global default context.

Validates: Requirements 1.7

Property 17: WorkloadRef Resolution Consistency

For any WorkloadNode A that declares dependsOn: [B], the WorkloadRef values in A's env that reference B SHALL resolve to the same address as B.endpoint() / B.ip() / B.internalUrl() after the graph is started — i.e., reference resolution is deterministic and consistent with the actual running node.

Validates: Requirements 6.1, 6.4

Property 18: RunGraph Strategy Respects Dependency Order

For any WorkloadGraph and any RunGraphOptions.strategy, runGraph() SHALL start each node only after all nodes in its dependsOn set have reached "running" state — regardless of which strategy is selected.

Validates: Requirements 6.4

Property 19: Edge Condition Semantics

For any WorkloadEdge with condition: "healthy", the dependent node SHALL NOT be started until the dependency node's healthcheck has passed (i.e., ContainerBackend::inspect() returns a ContainerInfo with healthcheck status "healthy"). If the dependency has no healthcheck defined, the condition degrades gracefully to "started".

Validates: Requirements 6.4

Property 20: Policy Tier Enforcement

For any WorkloadNode with policy.tier = "untrusted", the ContainerSpec passed to ContainerBackend::run() SHALL have read_only: true, network: "none", and seccomp: "strict" set — regardless of any other node-level overrides.

Validates: Requirements 6.1

Property 21: Policy Validation Rejects Incompatible Backends

For any WorkloadGraph containing a node with policy.tier = "untrusted" and a backend that only supports IsolationLevel::Container (not MicroVm), WorkloadGraphEngine::run() SHALL reject with ComposeError::PolicyViolation before starting any node.

Validates: Requirements 6.1, 1.10

---

Interactive Backend Installer (installer.rs)

When detect_backend() returns NoBackendFound and the process is running in an interactive terminal, the runtime invokes the interactive backend installer instead of immediately erroring out. This turns a dead-end error into a guided first-run experience.

Flow

get_global_backend_instance()
  └─ detect_backend() → Err(NoBackendFound { probed })
       └─ is_tty(stderr) && !PERRY_NO_INSTALL_PROMPT?
            ├─ YES → BackendInstaller::run() → re-run detect_backend()
            └─ NO  → return ContainerError::NoBackendFound (non-interactive message)

BackendInstaller struct (installer.rs)

pub struct BackendInstaller {
    platform: Platform,   // macOS, Linux, Windows
    is_tty: bool,
}

impl BackendInstaller {
    pub async fn run(&self) -> Result<BackendDriver, ComposeError> {
        self.print_header();
        let choice = self.prompt_backend_selection()?;
        self.print_install_instructions(&choice);
        if self.confirm_auto_install()? {
            self.execute_install(&choice).await?;
            detect_backend().await  // re-probe after install
        } else {
            Err(ComposeError::NoBackendFound { ... })
        }
    }
}

Platform-Specific Backend Menu

The installer presents a platform-filtered, priority-ordered menu. Each entry shows:

• Backend name (bold)
• One-line description
• Install command (cyan)
• Docs URL

macOS example output:

Perry needs a container runtime to continue.
No container runtime was found on this system.

Select a backend to install:

  ❯ 1. apple/container  Apple's native container runtime (recommended)
                        brew install container
                        https://github.com/apple/container

    2. orbstack         Fast macOS VM with Docker-compatible API
                        brew install --cask orbstack
                        https://orbstack.dev

    3. colima           Lightweight macOS container runtime
                        brew install colima
                        https://github.com/abiosoft/colima

    4. podman           Daemonless, rootless OCI runtime
                        brew install podman && podman machine init && podman machine start
                        https://podman.io

    5. docker           Docker Desktop for Mac
                        brew install --cask docker
                        https://docs.docker.com/desktop/mac

[↑↓ to navigate, Enter to select, q to quit]

Auto-Install Confirmation

After selection:

Install apple/container now?
  Run: brew install container

  [Y]es  [N]o, show me the command

If Y: streams brew install container output to terminal, then re-probes.
If N: prints the command and exits with a non-zero code.

Non-Interactive Mode

When stderr is not a TTY (CI, scripts, piped output), the installer is skipped entirely. The error message includes a hint:

Error: No container runtime found. Probed: apple/container (not found), orbstack (not found), ...
Hint: Install a container runtime for macOS. Recommended: brew install container
      See: https://github.com/apple/container
Set PERRY_NO_INSTALL_PROMPT=1 to suppress this hint.

Dependencies

• dialoguer crate — interactive selection prompt with arrow-key navigation
• console crate — ANSI colour output, TTY detection
• tokio::process::Command — execute install commands and stream output

Both dialoguer and console are gated behind the installer Cargo feature so they don't add binary size for embedded/headless deployments.

---

Error Handling

Error Taxonomy

Error Variant	HTTP-equivalent code	When raised
NotFound(String)	404	inspect() with unknown ID
BackendError { code, message }	backend exit code	Any CLI invocation fails
VerificationFailed { image, reason }	403	cosign verification fails
DependencyCycle { cycle }	422	composeUp() with cyclic deps
ServiceStartupFailed { service, error }	500	Service fails during up
InvalidConfig(String)	400	Malformed spec or YAML
NoBackendFound { probed }	503	No runtime detected
BackendNotAvailable { name, reason }	503	PERRY_CONTAINER_BACKEND override not found

Error Flow

Backend CLI failure
  → CliBackend captures stderr + exit code
  → ComposeError::BackendError { code, message }
  → ContainerError::BackendError (via From<ComposeError> impl — ContainerError is a thin wrapper)
  → compose_error_to_json() → JSON string
  → FFI Promise rejection with { message, code }
  → TypeScript Error object with .message and .code

Rollback on Compose Failure

If any service fails to start during composeUp(), ComposeEngine stops and removes all previously started containers before rejecting the Promise. Networks and volumes created during the failed up are also removed. This ensures no orphaned resources are left behind.

Shell Capability Errors

perry_container_run_capability() rejects with ContainerError::VerificationFailed before creating any container if image verification fails. The ShellBridge never receives an unverified image reference.

---

Testing Strategy

The test suite is organized as a six-layer pyramid, ordered from fastest/most isolated (Layer 1) to slowest/most integrated (Layer 6). Each layer builds on the confidence established by the layers below it.

---

Layer 1: Unit Tests (#[cfg(test)] inline in each module)

Fast, no I/O, no runtime required. Each module owns its own inline unit tests.

backend.rs unit tests

• platform_candidates() returns correct priority order for each platform (macOS, Linux, Windows)
• BackendDriver::name() returns correct string for each variant
• CliBackend argument construction for each operation (run, create, start, stop, remove, list, inspect, logs, exec, pull_image, list_images, remove_image, create_network, remove_network, create_volume, remove_volume) and each protocol variant (DockerProtocol, AppleContainerProtocol, LimaProtocol)
• detect_backend() with PERRY_CONTAINER_BACKEND env var override — returns correct backend without probing
• detect_backend() with PERRY_CONTAINER_BACKEND set to unknown value — returns BackendNotAvailable
• IsolationLevel default mapping for each BackendDriver variant

compose.rs unit tests

• resolve_startup_order() with empty spec — returns empty vec
• resolve_startup_order() with single service — returns [service]
• resolve_startup_order() with linear chain a → b → c — returns [a, b, c]
• resolve_startup_order() with diamond a → {b, c} → d — returns valid ordering where a is first and d is last
• resolve_startup_order() with cycle a → b → a — returns Err(DependencyCycle)
• resolve_startup_order() with self-loop a → a — returns Err(DependencyCycle)
• compute_topological_levels() with diamond — returns [[a], [b, c], [d]]
• service::generate_name() — same inputs produce same prefix, different random seeds produce different names
• policy_to_container_flags() for each PolicyTier — correct flags for default, isolated, hardened, untrusted

types.rs unit tests

• ContainerSpec JSON serialization — all fields present in output
• ContainerSpec JSON deserialization — missing optional fields default to None
• ComposeSpec with ListOrDict environment in both list and dict forms
• ComposeDependsOn condition validation — rejects unknown condition strings
• ComposeServiceVolume type validation — rejects unknown type strings
• WorkloadEdge condition defaults to "started" when not specified

error.rs unit tests

• compose_error_to_json() for each error variant — correct HTTP code and message format
• From<ComposeError> for ContainerError — all variants convert without data loss

workload.rs unit tests

• WorkloadRef::resolve() with Endpoint projection — returns "<ip>:<port>"
• WorkloadRef::resolve() with Ip projection — returns IP string
• WorkloadRef::resolve() with InternalUrl projection — returns "http://<ip>:<port>"
• WorkloadRef::resolve() with missing port mapping — returns Err(WorkloadRefResolutionFailed)
• WorkloadRef::resolve() with node not in running set — returns Err(WorkloadRefResolutionFailed)

verification.rs unit tests

• get_default_base_image() returns "cgr.dev/chainguard/alpine-base"
• get_chainguard_image("git") returns "cgr.dev/chainguard/git"
• get_chainguard_image("unknown-tool") returns None
• Verification cache hit — second call returns cached result without re-verifying

---

Layer 2: Property-Based Tests (P1–P21, using proptest)

Property-based testing is implemented using the proptest crate (Rust). Each property test runs a minimum of 100 iterations.

Each test is tagged with a comment in the format:

// Feature: perry-container, Property N: <property_text>

Properties and their test locations:

Property	Test location	Proptest strategy
P1: Backend priority order	crates/perry-container-compose/src/backend.rs	Generate random Vec<bool> availability masks
P2: Detection idempotence	crates/perry-container-compose/src/backend.rs	Call detect with mocked OnceLock, verify same result
P3: ContainerSpec CLI args	crates/perry-container-compose/src/backend.rs	Arbitrary ContainerSpec via proptest derive
P4: Data model JSON round-trip	crates/perry-container-compose/src/types.rs	Arbitrary instances of each type
P5: ComposeSpec JSON round-trip	crates/perry-container-compose/src/types.rs	Arbitrary ComposeSpec
P6: YAML round-trip	crates/perry-container-compose/src/yaml.rs	Arbitrary ComposeSpec
P7: Topological sort validity	crates/perry-container-compose/src/compose.rs	Random DAGs via edge list generation
P8: Cycle detection	crates/perry-container-compose/src/compose.rs	Random graphs with injected cycles
P9: Name uniqueness	crates/perry-container-compose/src/compose.rs	Arbitrary (String, u64) pairs
P10: Verification idempotence	crates/perry-stdlib/src/container/verification.rs	Arbitrary image reference strings
P11: BackendInfo completeness	crates/perry-container-compose/src/backend.rs	Arbitrary BackendProbeResult
P12: depends_on validation	crates/perry-container-compose/src/types.rs	Arbitrary strings excluding valid conditions
P13: Volume type validation	crates/perry-container-compose/src/types.rs	Arbitrary strings excluding valid types
P14: Error code preservation	crates/perry-container-compose/src/error.rs	Arbitrary (i32, String) pairs
P15: IsolationLevel consistency	crates/perry-container-compose/src/backend.rs	Arbitrary BackendDriver variants + ContainerSpec with isolationLevel
P16: ContainerContext isolation	crates/perry-stdlib/src/container/context.rs	Pairs of independent ContainerContext instances with arbitrary handle operations
P17: WorkloadRef resolution consistency	crates/perry-stdlib/src/container/workload.rs	Arbitrary WorkloadGraph with cross-node WorkloadRef env values; verify resolved addresses match node endpoints
P18: RunGraph strategy respects dependency order	crates/perry-container-compose/src/compose.rs	Arbitrary WorkloadGraph DAGs with all four strategy variants; verify start ordering invariant
P19: Edge condition semantics	crates/perry-container-compose/src/compose.rs	Arbitrary WorkloadGraph with condition: "healthy" edges and mock ContainerBackend::inspect() returning varying healthcheck states; verify dependent node does not start until health passes
P20: Policy tier enforcement	crates/perry-container-compose/src/compose.rs	Arbitrary WorkloadNode with policy.tier = "untrusted"; verify ContainerSpec passed to mock backend always has read_only: true, network: "none", seccomp: "strict"
P21: Policy validation rejects incompatible backends	crates/perry-container-compose/src/compose.rs	Arbitrary WorkloadGraph with at least one untrusted node; mock backend reporting IsolationLevel::Container; verify PolicyViolation error before any node starts

---

Layer 3: Functional Tests (crates/perry-container-compose/tests/functional/)

Test complete workflows with a mock ContainerBackend that records calls and returns scripted responses. No real container runtime required.

functional/compose_engine_test.rs

• up_creates_networks_before_containers — mock backend records call order; verify create_network called before any run
• up_creates_volumes_before_containers — verify create_volume called before any run
• up_starts_services_in_dependency_order — mock records start times; verify ordering matches topological sort
• up_rollback_on_service_failure — mock returns error on third run; verify first two containers are stopped and removed
• down_removes_containers_and_networks — verify remove and remove_network called for all resources
• down_with_volumes_removes_named_volumes — verify remove_volume called when volumes: true
• partial_continue_skips_failed_subtree — mock fails worker; verify nginx (which depends on worker) is skipped but cache (independent) still starts
• halt_graph_leaves_running_nodes — mock fails api; verify db (already running) is NOT stopped

functional/workload_graph_test.rs

• policy_untrusted_sets_correct_flags — verify ContainerSpec passed to mock backend has read_only: true, network: "none"
• policy_isolated_sets_network_none — verify network: "none" in spec
• policy_validation_rejects_container_backend_for_untrusted — mock backend reports IsolationLevel::Container; verify PolicyViolation error
• workload_ref_resolved_after_all_nodes_start — mock backend returns scripted ContainerInfo with IP/ports; verify env vars injected correctly
• edge_condition_healthy_waits_for_healthcheck — mock backend returns "starting" then "healthy" on successive inspect calls; verify dependent node not started until healthy
• edge_condition_completed_waits_for_exit_zero — mock backend returns running then exited(0); verify dependent starts after exit

functional/backend_detection_test.rs

• detect_backend_returns_first_available — mock probe results with first two unavailable, third available; verify third is selected
• detect_backend_env_override_skips_probing — set PERRY_CONTAINER_BACKEND=podman; verify no other probes run
• detect_backend_all_unavailable_returns_error — all probes fail; verify NoBackendFound with all candidates listed
• detect_backend_caches_result — call twice; verify probe function called only once

---

Layer 4: Integration Tests (crates/perry-container-compose/tests/integration/)

Require a real container runtime. Gated behind #[cfg(feature = "integration")]. Skipped in CI unless PERRY_INTEGRATION_TESTS=1 is set.

integration/container_lifecycle_test.rs

• run_and_remove_alpine — run alpine:latest with echo hello, verify stdout, remove
• create_start_stop_remove — full lifecycle with alpine:latest
• list_shows_running_container — run container, list, verify it appears
• inspect_returns_running_status — run container, inspect, verify status contains "running"
• logs_captures_stdout — run container that prints to stdout, verify logs contain output
• exec_runs_command_in_container — run alpine:latest, exec echo test, verify output
• pull_image_succeeds — pull hello-world:latest, verify no error
• list_images_shows_pulled_image — pull then list, verify image appears

integration/compose_lifecycle_test.rs

• compose_up_two_services — bring up alpine + alpine with dependency, verify both running
• compose_down_removes_all — up then down, verify no containers remain
• compose_ps_shows_services — up, ps, verify service names in output
• compose_logs_returns_output — up service that prints, logs, verify output
• compose_exec_runs_in_service — up, exec command in service, verify output
• compose_down_volumes_removes_named_volumes — up with named volume, down --volumes, verify volume gone

integration/workload_graph_test.rs

• run_graph_two_node_dependency — db + api with dependsOn, verify api starts after db
• run_graph_workload_ref_resolves — db node, api node with DATABASE_URL: db.endpoint("5432"), verify env var set in api container
• run_graph_rollback_on_failure — second node fails (bad image), verify first node removed
• run_graph_partial_continue — three nodes, middle fails, verify independent third node still starts

---

Layer 5: End-to-End Tests (tests/e2e/)

Full Perry program compilation + execution against a real runtime. These test the complete stack: TypeScript → HIR → codegen → FFI → backend. Located in tests/e2e/ at the workspace root.

Test files (draft TypeScript, compiled and run by the test harness):

File	What it tests
tests/e2e/container-basic.e2e.ts	Basic perry/container API: run, inspect, logs, exec, stop, remove
tests/e2e/compose-forgejo.e2e.ts	Forgejo stack: composeUp, ps, exec (health check), logs, down
tests/e2e/workloads-graph.e2e.ts	perry/workloads graph builder: graph(), node(), runGraph(), handle.status(), handle.ps(), handle.down()
tests/e2e/workloads-policy.e2e.ts	Policy enforcement: policy.isolated() blocks network, policy.hardened() enforces read-only root
tests/e2e/workloads-refs.e2e.ts	WorkloadRef cross-node references: db.endpoint() resolved and injected into dependent node env

The e2e test harness (tests/e2e/harness.rs) compiles each .e2e.ts file using the Perry compiler, runs the resulting binary, captures stdout/stderr, and asserts on exit code and output patterns.

---

Layer 6: Smoke Tests

Fast sanity checks run on every build. No runtime required.

• js_container_module_init() completes without panic
• perry check does not flag perry/container, perry/container-compose, perry/compose, or perry/workloads as missing packages
• WIT interface consistency check (compiler build-time assertion)
• All FFI symbols in NATIVE_MODULE_TABLE resolve to defined functions (link-time check)

---

Test Infrastructure

• Mock backend: crates/perry-container-compose/src/testing/mock_backend.rs — implements ContainerBackend trait with a call recorder and scripted response queue. Used by functional tests.
• Test fixtures: crates/perry-container-compose/tests/fixtures/ — sample compose YAML files, sample ComposeSpec JSON, sample WorkloadGraph JSON.
• E2e harness: tests/e2e/harness.rs — compiles .e2e.ts files, runs binaries, asserts on output.
• CI matrix: integration tests run on a separate CI job with PERRY_INTEGRATION_TESTS=1 and a real podman/docker runtime available.

---

Known Gaps / Implementation Readiness

✅ Stable

• ContainerBackend trait + CliBackend<P: CliProtocol> + protocol variants
• detect_backend() auto-probe with platform priority order
• ContainerSpec / ComposeSpec types (compose-spec compliant)
• ComposeEngine::up/down/ps/logs/exec/start/stop/restart
• resolve_startup_order (Kahn's algorithm, free function)
• ComposeProject::load (file + env)
• FFI symbols in perry-stdlib/container/mod.rs
• Codegen dispatch table (lower_call.rs, NATIVE_MODULE_TABLE)
• HIR module recognition (lower.rs) including perry/compose alias
• perry-stdlib feature gate container
• Error mapping ComposeError → { "ok": bool, "result"|"error": ... }

⚠️ Present but not on hot path

• Image verification (cosign/Sigstore) — present in verification.rs / capability.rs, only invoked via alloy_container_run_capability(), not the default run() path
• Volume removal in down --volumes — partially implemented
• perry/workloads module — workload.rs exists in HEAD but not wired to compiler dispatch tables; planned future extension

❌ Missing / Not yet wired

• js_container_build FFI symbol — ContainerBackend::build() is implemented in CliBackend but no FFI symbol exists in the codegen dispatch table. Wiring this is a future task.
• inspect_image() and wait() on ContainerBackend — present in canonical trait definition; CliBackend implementation needed.
• ComposeEngine::resolve_startup_order() method delegate — production code exposes resolve_startup_order(spec) as a free function; an explicit method delegate must be added for test compatibility (C-6).
• Volume removal in down --volumes — spec requires removing named volumes; implementation is partially stubbed.
• iOS detection in platform_candidates() — cfg!(target_os = "ios") should be grouped with macOS; currently only cfg!(target_os = "macos") in some branches.

Canonical Crate Module Structure

crates/perry-container-compose/
  Cargo.toml
  src/
    lib.rs           — pub mod declarations + pub use re-exports
    backend.rs       — ContainerBackend trait + CliBackend<P> + detect_backend()
    cli.rs           — clap CLI binary entry
    compose.rs       — ComposeEngine (up/down/ps/logs/exec/start/stop/restart/config)
    config.rs        — ProjectConfig + resolve_compose_files + resolve_project_name
    error.rs         — ComposeError enum + BackendProbeResult + compose_error_to_js()
    installer.rs     — BackendInstaller (interactive runtime installer)
    main.rs          — CLI binary main()
    orchestrate.rs   — single-service orchestration helper
    project.rs       — ComposeProject YAML loader (CLI path)
    service.rs       — container name generation + ServiceState + ComposeService methods
    types.rs         — all data types (ComposeSpec, ContainerSpec, etc.)
    yaml.rs          — YAML parse + .env interpolation + multi-file merge
    testing/         — test mock utilities
  tests/
    common/mod.rs
    container_ops.rs
    integration_tests.rs
    orchestration.rs
    round_trip.rs
    service_tests.rs
    yaml_tests.rs

crates/perry-stdlib/src/container/
  mod.rs             — FFI exports + OnceLock backend singleton
  backend.rs         — thin re-export / adapter
  capability.rs      — OCI capability sandbox
  compose.rs         — compose FFI adapters
  types.rs           — FFI-side type definitions
  verification.rs    — Sigstore/cosign image verification
  workload.rs        — workload types (re-export from perry-container-compose)

types/
  perry/container/index.d.ts   — TS type declarations for perry/container
  perry/compose/index.d.ts     — TS type declarations for perry/compose

Canonical Dependencies

Dependency	Purpose
async-trait	Async trait support for ContainerBackend
tokio	Async runtime (full features)
serde / serde_json / serde_yaml	Serialization (YAML for CLI, JSON for FFI)
clap	CLI argument parsing (replaces Go's cobra)
thiserror	Error derivation for ComposeError
indexmap	Ordered maps for service startup order preservation
md5 + hex	Container name generation ({hash}-{random} format)
rand	Random suffix generation for container names
once_cell	Lazy static + OnceLock for backend singleton
tracing	Structured logging (replaces Go's slog)
which	Binary location for backend detection
dashmap	Concurrent hash map for ComposeEngine registry
console + dialoguer	Interactive installer UI (BackendInstaller, installer feature)

Requirements Document

Introduction

perry/container is the container management module exposed to Perry TypeScript user code via the perry/container import. It provides a unified JavaScript/TypeScript API for creating, running, and managing OCI containers, with platform-adaptive backend selection: on macOS and iOS the runtime delegates to Apple's native container framework (apple/container); on all other platforms it delegates to podman.

perry/container also exposes composeUp / composeDown and related orchestration functions backed by the perry-container-compose Rust crate — a native Rust reimplementation of container-compose functionality, inspired by the container-compose/cli project (Go, by Andrew Waters). The perry-container-compose crate is written from scratch with OCI runtime auto-detection as a first-class feature: it automatically discovers and uses the best available container runtime (apple/container, podman, orbstack, colima, rancher-desktop, lima, nerdctl, or docker) without any configuration. The Go reference project served as inspiration for the feature set and API design; the Rust implementation is independent and not derived from the Go code. The crate implements all features the Go reference project was missing (networks, volumes, depends_on, env interpolation, .env files, multiple compose files, project names, ps, logs, exec, config, down, start, stop, restart commands) and ships as both a standalone CLI tool and a library that backs perry/container's composeUp() API.

The perry-container-compose crate lives at crates/perry-container-compose/ and is structured as: lib.rs, cli.rs, compose.rs, project.rs, service.rs, yaml.rs, config.rs, backend.rs, error.rs. Its key dependencies are clap (CLI), serde_yaml (YAML parsing), tokio (async), async-trait, and tracing. Container name generation uses a custom MD5-based approach (MD5 hash of image name + random big integer, formatted as {name}_{hash}).

The ComposeSpec type conforms to the official compose-spec JSON schema expressed as a TypeScript interface; the TypeScript-facing composeUp() API accepts only ComposeSpec objects — no YAML files or file paths. The crate internally handles YAML for its standalone CLI usage.

The broader perry/container feature is implemented as a Cargo feature-gated module (container feature) in crates/perry-stdlib/src/container/, exposed to TypeScript via #[no_mangle] pub unsafe extern "C" fn js_container_* and js_container_compose_* FFI functions registered in perry-stdlib. The TypeScript surface is declared in the compiler's HIR lowering layer (crates/perry-hir/src/lower.rs) and codegen dispatch table (crates/perry-codegen/src/codegen.rs), following the same pattern used by perry/thread, perry/ui, and perry/i18n.

Go Reference Project: container-compose/cli

The perry-container-compose crate is inspired by the Go project container-compose/cli by Andrew Waters. This section documents the original Go project structure, the service management flow it implements, what it supports vs. what is missing, and the Go→Rust mapping used for the Rust port.

Original Go Project Structure

File	Size	Description
internal/entities/service.go	9256 bytes	Service entity with fields: Image, Name, Ports, EnvironmentVariables, Labels, Volumes, Build; methods: GenerateName(), Exists(), IsRunning(), RunCommand(), StartCommand(), BuildCommand(), InspectCommand(), NeedsBuild()
internal/entities/compose.go	300 bytes	Compose struct with a services map
internal/commands/build.go	4033 bytes	BuildCommand interface
internal/commands/inspect.go	3221 bytes	InspectCommand interface
internal/commands/run.go	1517 bytes	RunCommand interface
internal/commands/start.go	731 bytes	StartCommand interface
internal/commands/stop.go	724 bytes	StopCommand interface
cmd/start/cmd.go	—	Start command orchestration logic

Service Management Flow (from cmd/start/cmd.go)

1. Read compose file (YAML)
2. Parse configuration (entities.Parse)
3. For each service:
   • If running → skip
   • If exists but stopped → StartCommand
   • If not exists → RunCommand
4. Execute command (cmd.Exec)
5. Log result

Feature Gap: Go Project vs. Rust Port

Feature	Go (container-compose/cli)	Rust (perry-container-compose)
image field	✅	✅
build field (context, dockerfile, args, labels, target, network)	✅	✅
ports field	✅	✅
environment field	✅ Basic	✅ + interpolation + .env
labels field	✅	✅
volumes field (service-level)	✅	✅
container_name field	✅	✅
Container state management (running/stopped/not-exists)	✅	✅
Automatic build when needed	✅	✅
networks top-level field	❌	✅
volumes top-level field	❌	✅
depends_on + dependency resolution	❌	✅ Kahn's algorithm
Environment variable interpolation ${VAR}	❌	✅
.env file loading	❌	✅
Multiple compose file merging	❌	✅
Project names (-p)	❌	✅
ps command	❌	✅
logs command	❌	✅
exec command	❌	✅
config command	❌	✅
down command	❌	✅
stop command	❌	✅
restart command	❌	✅
Port mapping in run	❌	✅
Volume mounting in run	❌	✅
Multi-runtime support (podman, orbstack, etc.)	❌ Apple Container only	✅ All backends

Go→Rust Dependency Mapping

Go Dependency	Rust Replacement	Notes
github.com/spf13/cobra	clap	CLI framework
gopkg.in/yaml.v3	serde_yaml	YAML parsing
github.com/goombaio/namegenerator	Custom MD5-based	generate_name(image, service_name)
context.Context	tokio async/await	Async runtime
error interface	Result<T, ComposeError> + thiserror	Error handling
log/slog	tracing	Structured logging
os.Exec	tokio::process::Command	Process execution
os.ReadFile	std::fs::read_to_string	File I/O

Glossary

• perry/container: The TypeScript import path that exposes container management to Perry user code (e.g. import { run, list, composeUp } from 'perry/container').
• perry/container-compose: An additional TypeScript import path that exposes the perry-container-compose crate's API directly (e.g. import { up, down, ps } from 'perry/container-compose'), separate from perry/container.
• perry-container-compose: The dedicated Rust crate at crates/perry-container-compose/ that is a native Rust reimplementation of container-compose functionality, inspired by container-compose/cli (Go). Ships as both a standalone CLI binary and a library used by perry/container.
• container-compose/cli: The Go reference project by Andrew Waters that inspired perry-container-compose's feature set and API design. perry-container-compose is an independent Rust reimplementation, not derived from the Go code.
• ContainerBackend: The platform-specific container runtime — detected automatically via detect_backend() in crates/perry-stdlib/src/container/backend.rs. Represented by the ContainerBackend trait in crates/perry-stdlib/src/container/backend.rs.
• CliProtocol: A Rust trait in backend.rs that translates abstract container operations into CLI arguments for a specific runtime family. Implement this trait to add support for a new CLI syntax. Three implementations ship: DockerProtocol (podman, nerdctl, orbstack, docker, colima), AppleContainerProtocol (apple/container), LimaProtocol (limactl).
• CliBackend: A Rust struct in backend.rs that implements ContainerBackend by holding a binary path and a Box<dyn CliProtocol>. Executes CLI commands via tokio::process::Command and delegates argument building to the protocol. This is the single concrete implementation of ContainerBackend.
• DockerProtocol: The CliProtocol implementation for Docker-compatible runtimes (podman, nerdctl, orbstack, docker, colima). All these runtimes accept identical CLI flags.
• AppleContainerProtocol: The CliProtocol implementation for the apple/container CLI on macOS/iOS.
• LimaProtocol: The CliProtocol implementation for Lima, which wraps commands as limactl shell <instance> nerdctl <cmd>.
• OrbStack: A macOS container runtime that provides a Docker-compatible API. Detected via orb CLI or ~/.orbstack/run/docker.sock.
• Colima: A macOS container runtime based on Lima VMs. Detected via colima CLI and colima status.
• Rancher Desktop: A cross-platform container runtime using containerd and nerdctl. Detected via nerdctl CLI.
• Lima: A macOS VM-based container runtime. Detected via limactl CLI.
• BackendInfo: A TypeScript/Rust object describing a detected container backend. Fields: name, available, reason (optional failure reason), version (optional CLI version).
• BackendProbeResult: The Rust struct used internally during backend detection. Fields: name: String, available: bool, reason: String.
• PERRY_CONTAINER_BACKEND: Environment variable that overrides automatic backend detection. Accepted values: apple/container, orbstack, colima, rancher-desktop, podman, lima, nerdctl, docker.
• ComposeEngine: The in-process Rust orchestration engine in crates/perry-stdlib/src/container/compose.rs (backed by crates/perry-container-compose). It is NOT a CLI wrapper — all orchestration logic executes in-process.
• ComposeProject: A named collection of services, networks, and volumes parsed from one or more compose files. Managed by project.rs in perry-container-compose.
• ContainerSpec: A TypeScript/Rust object describing the configuration for a single container.
• ComposeSpec: A strongly-typed TypeScript/Rust object describing a multi-container application. Conforms to the official compose-spec JSON schema. Top-level fields: name, version (deprecated), services, networks, volumes, secrets, configs, include, models, and x-* extension fields. No YAML files or file paths are accepted by the TypeScript API. Maps to ComposeSpec in crates/perry-container-compose/src/types.rs.
• ComposeService: A strongly-typed TypeScript/Rust object describing a single service within a ComposeSpec. Supports the full set of fields defined in the compose-spec service definition. Maps to ComposeService in crates/perry-container-compose/src/types.rs.
• ComposeNetwork: A strongly-typed TypeScript/Rust object describing a top-level network definition within a ComposeSpec. Fields: name, driver, driver_opts, ipam (ComposeNetworkIpam), external, internal, enable_ipv4, enable_ipv6, attachable, labels. Maps to ComposeNetwork in crates/perry-container-compose/src/types.rs.
• ComposeVolume: A strongly-typed TypeScript/Rust object describing a top-level volume definition within a ComposeSpec. Fields: name, driver, driver_opts, external, labels. Maps to ComposeVolume in crates/perry-container-compose/src/types.rs.
• ComposeSecret: A strongly-typed TypeScript/Rust object describing a top-level secret definition within a ComposeSpec. Fields: name, environment, file, external, labels, driver, driver_opts, template_driver. Maps to ComposeSecret in crates/perry-container-compose/src/types.rs.
• ComposeConfig: A strongly-typed TypeScript/Rust object describing a top-level config definition within a ComposeSpec. Fields: name, content, environment, file, external, labels, template_driver. Maps to ComposeConfig in crates/perry-container-compose/src/types.rs.
• ComposeServicePort: The long-form port mapping object used in ComposeService.ports. Fields: name, mode, host_ip, target (integer or string), published (string or integer), protocol, app_protocol. Maps to ComposeServicePort in crates/perry-container-compose/src/types.rs.
• ComposeServiceVolume: The long-form volume mount object used in ComposeService.volumes. Fields: type (one of bind | volume | tmpfs | cluster | npipe | image), source, target, read_only, consistency, bind (with propagation, create_host_path, recursive, selinux), volume (with labels, nocopy, subpath), tmpfs (with size, mode), image (with subpath). Maps to ComposeServiceVolume in crates/perry-container-compose/src/types.rs.
• ComposeDependsOn: The object form of ComposeService.depends_on. Each key is a service name mapping to { condition: "service_started" | "service_healthy" | "service_completed_successfully", required?: boolean, restart?: boolean }. Maps to ComposeDependsOn in crates/perry-container-compose/src/types.rs.
• ComposeHealthcheck: A strongly-typed TypeScript/Rust object describing a service healthcheck. Fields: test: string | string[], interval, timeout, retries, start_period, start_interval, disable. Maps to ComposeHealthcheck in crates/perry-container-compose/src/types.rs.
• ComposeDeployment: A strongly-typed TypeScript/Rust object describing service deployment configuration. Fields: mode, replicas, labels, resources (with limits and reservations, each supporting cpus, memory, pids), restart_policy, placement, update_config, rollback_config. Maps to ComposeDeployment in crates/perry-container-compose/src/types.rs.
• ComposeLogging: A strongly-typed TypeScript/Rust object describing service logging configuration. Fields: driver, options. Maps to ComposeLogging in crates/perry-container-compose/src/types.rs.
• ComposeNetworkIpam: A strongly-typed TypeScript/Rust object describing IPAM configuration for a ComposeNetwork. Fields: driver, config (array of { subnet?, ip_range?, gateway?, aux_addresses? }), options. Maps to ComposeNetworkIpam in crates/perry-container-compose/src/types.rs.
• ListOrDict: The compose-spec pattern representing a value that is either a Record<string, string | number | boolean | null> (mapping form) or string[] (list form). Used for environment, labels, extra_hosts, sysctls, and similar fields. Maps to a Rust enum ListOrDict in crates/perry-container-compose/src/types.rs.
• ComposeHandle: An opaque handle returned by composeUp() representing a running Compose stack.
• ContainerHandle: An opaque handle returned by run() and create().
• ContainerInfo: A TypeScript/Rust object containing metadata about a container.
• ContainerLogs: A TypeScript/Rust object containing stdout and stderr strings.
• ImageInfo: A TypeScript/Rust object containing metadata about a container image.
• FFI function: A #[no_mangle] pub unsafe extern "C" fn js_container_* or js_container_compose_* Rust function in perry-stdlib that is called directly by Perry-compiled native binaries.
• HIR lowering: The compiler phase in crates/perry-hir/src/lower.rs that recognises perry/container and perry/container-compose imports and maps TypeScript call sites to FFI function declarations.
• Codegen dispatch: The LLVM codegen phase in crates/perry-codegen/src/codegen.rs that emits the actual call instructions to the FFI functions.
• ShellCapability: A sandboxed shell command invocation defined in perryconfig.toml under shellCapabilities, executed inside an ephemeral OCI container for isolation.
• Sigstore/cosign: The cryptographic image-signing and verification toolchain used to verify OCI image authenticity before execution.
• Chainguard image: A hardened, minimal OCI image from cgr.dev/chainguard/ used as the default base for shellCapability containers.
• clap: The Rust CLI framework used in perry-container-compose, replacing Go's cobra.
• serde_yaml: The Rust YAML parsing library used in perry-container-compose, replacing Go's gopkg.in/yaml.v3.
• tokio: The Rust async runtime used in perry-container-compose, replacing Go goroutines and context.Context.

Requirements

Requirement 1: Platform-Adaptive Backend Selection

User Story: As a Perry developer, I want perry/container to automatically use the best available container runtime for my platform, so that my container code works on macOS, iOS, Linux, and Windows without any configuration.

Acceptance Criteria

1. WHEN perry/container is first used, THE runtime SHALL probe for available container backends in the platform-specific priority order defined in backend.rs::detect_backend() before selecting one.
2. THE detect_backend() function SHALL check each candidate in priority order and return the first one that is both installed AND running/available, wrapping the result in a BackendDriver enum variant carrying the resolved CLI binary path.
3. WHEN no candidate backend is found, THE runtime SHALL return a descriptive ContainerError::NoBackendFound error listing all probed candidates and their failure reasons.
4. THE Perry.Container.backend / getBackend() property SHALL return the runtime name string from BackendDriver::name() (e.g. "apple/container", "orbstack", "colima", "rancher-desktop", "podman", "lima", "docker").
5. THE user SHALL be able to override automatic detection by setting the PERRY_CONTAINER_BACKEND environment variable to the name of a specific backend.
6. WHEN PERRY_CONTAINER_BACKEND is set, THE runtime SHALL use that backend directly without probing, and SHALL return ContainerError::BackendNotAvailable if the specified backend is not found.
7. THE detection result SHALL be cached for the process lifetime using OnceLock so detection only runs once.
8. THE perry/container module SHALL expose a detectBackend(): Promise<BackendInfo[]> TypeScript function that returns all detected backends with their availability status, backed by js_container_detectBackend().
9. THE BackendInfo TypeScript interface SHALL include: name: string, available: boolean, reason?: string (failure reason if not available), version?: string (CLI version if available).
10. THE ContainerBackend SHALL be used both for user-facing perry/container API calls AND as the OCI isolation layer for shellCapabilities entries (see Requirement 13).

Requirement 2: Container Lifecycle Management

User Story: As a Perry developer, I want to create, start, stop, and remove containers programmatically via perry/container.

Acceptance Criteria

1. THE run(spec: ContainerSpec): Promise<ContainerHandle> TypeScript function SHALL create and start a container from the given ContainerSpec, backed by js_container_run().
2. THE create(spec: ContainerSpec): Promise<ContainerHandle> TypeScript function SHALL create a container without starting it, backed by js_container_create().
3. THE start(id: string): Promise<void> TypeScript function SHALL start a previously created container, backed by js_container_start().
4. THE stop(id: string, timeout?: number): Promise<void> TypeScript function SHALL stop a running container, backed by js_container_stop().
5. THE remove(id: string, force?: boolean): Promise<void> TypeScript function SHALL remove a stopped container; WHEN force is true, it SHALL stop and remove a running container, backed by js_container_remove().
6. IF a container operation fails, THEN THE Promise SHALL reject with an Error whose message contains the backend's stderr output and whose code property contains the exit code, propagated from ContainerError::BackendError.
7. THE ContainerSpec TypeScript interface SHALL support: image (required), name, ports, volumes, env, cmd, entrypoint, network, rm — matching the ContainerSpec Rust struct in crates/perry-stdlib/src/container/types.rs.
8. THE ContainerSpec TypeScript interface SHALL support the following security options: privileged (boolean), user (string), workdir (string), cap_add (string array), cap_drop (string array), read_only (boolean), seccomp (string).

Requirement 3: Container Inspection and Listing

User Story: As a Perry developer, I want to list and inspect containers via perry/container.

Acceptance Criteria

1. THE list(all?: boolean): Promise<ContainerInfo[]> TypeScript function SHALL return running containers; WHEN all is true, include stopped containers, backed by js_container_list().
2. THE inspect(id: string): Promise<ContainerInfo> TypeScript function SHALL return a ContainerInfo object for the given container ID, backed by js_container_inspect().
3. IF inspect is called with an unknown id, THEN THE Promise SHALL reject with a not-found Error, propagated from ContainerError::NotFound.
4. THE ContainerInfo TypeScript interface SHALL include: id, name, image, status, ports, created (ISO 8601) — matching the ContainerInfo Rust struct in types.rs.

Requirement 4: Container Logs and Exec

User Story: As a Perry developer, I want to retrieve logs from containers and execute commands inside running containers.

Acceptance Criteria

1. THE logs(id: string, tail?: number): Promise<ContainerLogs> TypeScript function SHALL return stdout and stderr from the container, backed by js_container_logs().
2. WHEN tail is set, THE logs function SHALL return only the last N lines.
3. THE exec(id: string, cmd: string[], env?: Record<string, string>, workdir?: string): Promise<ContainerLogs> TypeScript function SHALL execute a command inside the container and return its output, backed by js_container_exec().
4. IF exec is called on a non-running container, THEN THE Promise SHALL reject with an Error propagated from the backend.
5. THE ContainerLogs TypeScript interface SHALL contain stdout: string and stderr: string — matching the ContainerLogs Rust struct in types.rs.

Requirement 5: Image Management

User Story: As a Perry developer, I want to pull, list, and remove container images via perry/container.

Acceptance Criteria

1. THE pullImage(reference: string): Promise<void> TypeScript function SHALL pull an OCI image from a registry, backed by js_container_pullImage().
2. THE listImages(): Promise<ImageInfo[]> TypeScript function SHALL return all locally available images, backed by js_container_listImages().
3. THE removeImage(reference: string, force?: boolean): Promise<void> TypeScript function SHALL remove a local image, backed by js_container_removeImage().
4. THE ImageInfo TypeScript interface SHALL include: id, repository, tag, size, created — matching the ImageInfo Rust struct in types.rs.
5. IF an image pull fails, THEN THE Promise SHALL reject with an Error whose message contains the backend's stderr output.

Requirement 6: Compose Orchestration (composeUp)

User Story: As a Perry developer, I want to manage multi-container applications by passing a strongly-typed ComposeSpec object to composeUp(), backed by the perry-container-compose crate which reimplements container-compose functionality in Rust, taking inspiration from the Go container-compose/cli reference project.

Acceptance Criteria

1. THE composeUp(spec: ComposeSpec): Promise<ComposeHandle> TypeScript function SHALL accept a ComposeSpec object, start all services in dependency order, and resolve with a ComposeHandle, backed by js_container_composeUp() which delegates to the perry-container-compose crate's ComposeEngine.
2. THE ComposeSpec TypeScript interface SHALL conform to the official compose-spec JSON schema and support the following top-level fields: name?: string, version?: string (deprecated, accepted but not used for validation), services: Record<string, ComposeService> (required), networks?: Record<string, ComposeNetwork>, volumes?: Record<string, ComposeVolume>, secrets?: Record<string, ComposeSecret>, configs?: Record<string, ComposeConfig>, include?: object[], models?: Record<string, object>, and x-* extension fields — matching the ComposeSpec Rust struct in crates/perry-container-compose/src/types.rs.
3. THE ComposeService TypeScript interface SHALL conform to the compose-spec service definition and support at minimum the following fields: image?: string, build?: string | ComposeServiceBuild (where ComposeServiceBuild has: context, dockerfile, dockerfile_inline, entitlements, args, ssh, labels, cache_from, cache_to, no_cache, additional_contexts, network, provenance, sbom, pull, target, shm_size, extra_hosts, isolation, privileged, secrets, tags, ulimits, platforms), command?: string | string[], entrypoint?: string | string[], environment?: ListOrDict, env_file?: string | string[], ports?: Array<string | number | ComposeServicePort>, volumes?: Array<string | ComposeServiceVolume>, networks?: string[] | Record<string, ComposeServiceNetworkConfig> (where ComposeServiceNetworkConfig has: aliases, ipv4_address, ipv6_address, priority), depends_on?: string[] | Record<string, ComposeDependsOn>, restart?: string, healthcheck?: ComposeHealthcheck, container_name?: string, labels?: ListOrDict, hostname?: string, user?: string, working_dir?: string, privileged?: boolean, read_only?: boolean, stdin_open?: boolean, tty?: boolean, stop_signal?: string, stop_grace_period?: string, network_mode?: string, pid?: string, cap_add?: string[], cap_drop?: string[], security_opt?: string[], sysctls?: ListOrDict, ulimits?: Record<string, number | { soft: number, hard: number }>, logging?: ComposeLogging, deploy?: ComposeDeployment, develop?: object, secrets?: string[], configs?: string[], expose?: Array<string | number>, extra_hosts?: ListOrDict, dns?: string | string[], dns_search?: string | string[], tmpfs?: string | string[], shm_size?: string | number, mem_limit?: string | number, memswap_limit?: string | number, cpus?: string | number, cpu_shares?: number, platform?: string, pull_policy?: string, profiles?: string[], scale?: number, extends?: string | { file?: string, service: string }, post_start?: object[], pre_stop?: object[] — matching the ComposeService Rust struct in crates/perry-container-compose/src/types.rs.
4. THE ComposeEngine SHALL resolve service startup order by topological sort of depends_on, implemented in ComposeEngine::resolve_startup_order() in compose.rs.
5. IF the depends_on graph contains a cycle, THEN THE Promise SHALL reject with an Error identifying the services involved, propagated from ContainerError::DependencyCycle, before any containers are started.
6. THE ComposeHandle TypeScript interface SHALL expose: down(volumes?: boolean): Promise<void>, ps(): Promise<ContainerInfo[]>, logs(service?: string, tail?: number): Promise<ContainerLogs>, exec(service: string, cmd: string[]): Promise<ContainerLogs> — backed by js_composeHandle_down(), js_composeHandle_ps(), js_composeHandle_logs(), js_composeHandle_exec().
7. WHEN down(volumes: true) is called, THE ComposeEngine SHALL stop and remove all containers and networks AND remove named volumes.
8. THE ComposeEngine SHALL create all networks before starting any service containers.
9. THE ComposeEngine SHALL create all named volumes before starting any service containers that reference them.
10. IF a service container fails to start, THE ComposeEngine SHALL stop and remove all previously started containers and reject with an Error, propagated from ContainerError::ServiceStartupFailed.
11. THE ComposeSpec object SHALL be the sole accepted input format for the TypeScript composeUp() API; no file paths, YAML strings, or external config formats SHALL be accepted by the TypeScript API.
12. THE perry-container-compose crate SHALL implement all features missing from the Go container-compose/cli reference project: networks, volumes, depends_on resolution, environment variable interpolation (${VARIABLE}), .env file loading, multiple compose file merging, project names, and the ps, logs, exec, config, down, start, stop, restart commands.
13. THE ComposeEngine SHALL generate unique container names using a custom MD5-based algorithm (MD5 hash of image name + random big integer, formatted as {name}_{hash}), replacing the Go project's goombaio/namegenerator dependency.

Requirement 7: YAML Configuration Parsing (perry-container-compose Internal)

User Story: As a CLI user of the standalone perry-container-compose binary, I want to define multi-container applications in YAML files compatible with the OCI-compatible Container Compose format, so that I can use familiar compose file syntax from the command line.

Acceptance Criteria

1. THE perry-container-compose crate SHALL parse YAML compose files using serde_yaml (replacing Go's gopkg.in/yaml.v3), implemented in yaml.rs.
2. THE YAML parser SHALL support the version field (accepted but not used for validation).
3. THE YAML parser SHALL support the services field with full service definitions including all fields defined in the compose-spec service schema: image, build (both string shorthand and full object form with context, dockerfile, dockerfile_inline, args, ssh, labels, cache_from, cache_to, no_cache, network, target, platforms, tags, secrets), command, entrypoint, environment (both list and mapping forms), env_file, ports (both short string/number form and long ComposeServicePort object form), volumes (both short string form and long ComposeServiceVolume object form), networks (both list and object form with aliases, ipv4_address, ipv6_address, priority), depends_on (both list form and object form with condition, required, restart), restart, healthcheck (full object with test, interval, timeout, retries, start_period, start_interval, disable), container_name, labels, hostname, user, working_dir, privileged, read_only, stdin_open, tty, stop_signal, stop_grace_period, network_mode, pid, cap_add, cap_drop, security_opt, sysctls, ulimits, logging, deploy, secrets, configs, expose, extra_hosts, dns, dns_search, tmpfs, shm_size, mem_limit, memswap_limit, cpus, cpu_shares, platform, pull_policy, profiles, scale, extends, post_start, pre_stop.
4. THE YAML parser SHALL support the networks top-level field for network definitions including all ComposeNetwork fields: name, driver, driver_opts, ipam (with driver, config array of { subnet?, ip_range?, gateway?, aux_addresses? }, options), external, internal, enable_ipv4, enable_ipv6, attachable, labels.
5. THE YAML parser SHALL support the volumes top-level field for volume definitions including all ComposeVolume fields: name, driver, driver_opts, external, labels.
6. THE YAML parser SHALL support the secrets top-level field for secret definitions including all ComposeSecret fields: name, environment, file, external, labels, driver, driver_opts, template_driver.
7. THE YAML parser SHALL support the configs top-level field for config definitions including all ComposeConfig fields: name, content, environment, file, external, labels, template_driver.
8. THE YAML parser SHALL support environment variable interpolation using ${VARIABLE} and ${VARIABLE:-default} syntax.
9. THE YAML parser SHALL load .env files from the project directory and make their values available for interpolation.
10. WHEN multiple compose files are specified, THE YAML parser SHALL merge them in order, with later files overriding earlier ones.
11. IF a YAML file is malformed or references undefined services in depends_on, THEN THE parser SHALL return a descriptive error before any container operations are attempted.
12. FOR ALL valid compose YAML strings, parsing then serialising back to YAML then parsing again SHALL produce an equivalent ComposeProject (round-trip property), verified by a property-based test suite.
13. THE YAML parsing path SHALL only be exercised by the standalone CLI; the TypeScript composeUp() API SHALL NOT accept YAML input.
14. FOR ALL ComposeService objects with depends_on in object form, THE YAML parser SHALL accept only the three valid condition values (service_started, service_healthy, service_completed_successfully) for the condition field; any other value SHALL be rejected at parse time with a descriptive error identifying the invalid condition and the service name.

Requirement 8: Compose CLI Interface (perry-container-compose Standalone)

User Story: As a CLI user, I want a standalone perry-container-compose binary with a command-line interface compatible with OCI-compatible Container Compose, so that I can manage multi-container applications from the terminal without writing TypeScript.

Acceptance Criteria

1. THE perry-container-compose CLI SHALL be implemented using clap (replacing Go's cobra) in cli.rs.
2. THE CLI SHALL support the following commands: up, down, ps, logs, exec, config, start, stop, restart.
3. THE up command SHALL support: -d, --detach (run in background), --build (rebuild images before starting), --remove-orphans (remove containers for undefined services).
4. THE down command SHALL support: -v, --volumes (remove named volumes), --remove-orphans.
5. THE logs command SHALL support: -f, --follow (stream logs), --tail N (last N lines), and optional service name arguments.
6. THE exec command SHALL support: service name, command, and optional -e, --env and -w, --workdir flags.
7. THE config command SHALL validate the compose configuration and print the resolved, merged configuration to stdout.
8. THE ps command SHALL list all services in the project with their current state (running, stopped, exited).
9. THE CLI SHALL support -h, --help on all commands and --version on the root command.
10. THE CLI SHALL support service name arguments for scoped operations (e.g., logs web db to show logs for only the web and db services).
11. IF a CLI command fails, THE CLI SHALL exit with a non-zero exit code and print a descriptive error message to stderr.

Requirement 9: Compose Project Management

User Story: As a CLI user, I want to manage multiple compose projects with different files and project names, so that I can run isolated stacks on the same machine.

Acceptance Criteria

1. THE perry-container-compose crate SHALL support the -f, --file flag to specify one or more compose file paths, implemented in project.rs.
2. WHEN multiple -f flags are provided, THE crate SHALL merge the compose files in the order specified, with later files taking precedence over earlier ones for conflicting keys.
3. THE crate SHALL support the -p, --project-name flag to set the project name, which is used as a prefix for all container, network, and volume names created by the project.
4. THE crate SHALL support the COMPOSE_PROJECT_NAME environment variable as a fallback when -p is not specified.
5. THE crate SHALL support the COMPOSE_FILE environment variable as a fallback when -f is not specified, accepting a colon-separated list of file paths.
6. WHEN neither -f nor COMPOSE_FILE is set, THE crate SHALL look for compose.yaml or docker-compose.yml in the current working directory, in that order.
7. WHEN no project name is provided via flag or environment variable, THE crate SHALL derive the project name from the directory name containing the primary compose file.
8. IF a specified compose file does not exist or cannot be read, THEN THE crate SHALL return a descriptive error identifying the missing file before any container operations are attempted.

Requirement 10: Strongly-Typed TypeScript Interfaces

User Story: As a Perry developer, I want complete, strongly-typed TypeScript interfaces for all perry/container and perry/container-compose types.

Acceptance Criteria

1. THE Perry compiler SHALL export TypeScript type declarations for ContainerSpec, ContainerHandle, ContainerInfo, ContainerLogs, ImageInfo, ComposeSpec, ComposeService, ComposeServiceBuild, ComposeServicePort, ComposeServiceVolume, ComposeServiceNetworkConfig, ComposeDependsOn, ComposeNetwork, ComposeNetworkIpam, ComposeVolume, ComposeSecret, ComposeConfig, ComposeHealthcheck, ComposeDeployment, ComposeLogging, ComposeHandle, and ListOrDict as part of the perry/container module type stubs (.d.ts). All types map to corresponding Rust structs in crates/perry-container-compose/src/types.rs.
2. THE Perry compiler SHALL additionally export TypeScript type declarations for the perry/container-compose import path, covering the up, down, ps, logs, exec, config, start, stop, and restart functions exposed by perry-container-compose's library API.
3. THE ComposeHealthcheck TypeScript interface SHALL include: test: string | string[], interval?: string, timeout?: string, retries?: number, start_period?: string, start_interval?: string, disable?: boolean — matching the ComposeHealthcheck Rust struct in crates/perry-container-compose/src/types.rs.
4. THE ComposeNetwork TypeScript interface SHALL conform to the compose-spec network definition and support: name?: string, driver?: string, driver_opts?: Record<string, string>, ipam?: ComposeNetworkIpam, external?: boolean, internal?: boolean, enable_ipv4?: boolean, enable_ipv6?: boolean, attachable?: boolean, labels?: ListOrDict — matching the ComposeNetwork Rust struct in crates/perry-container-compose/src/types.rs.
5. THE ComposeVolume TypeScript interface SHALL conform to the compose-spec volume definition and support: name?: string, driver?: string, driver_opts?: Record<string, string>, external?: boolean, labels?: ListOrDict — matching the ComposeVolume Rust struct in crates/perry-container-compose/src/types.rs.
6. THE ComposeSecret TypeScript interface SHALL conform to the compose-spec secret definition and support: name?: string, environment?: string, file?: string, external?: boolean, labels?: ListOrDict, driver?: string, driver_opts?: Record<string, string>, template_driver?: string — matching the ComposeSecret Rust struct in crates/perry-container-compose/src/types.rs.
7. THE ComposeConfig TypeScript interface SHALL conform to the compose-spec config definition and support: name?: string, content?: string, environment?: string, file?: string, external?: boolean, labels?: ListOrDict, template_driver?: string — matching the ComposeConfig Rust struct in crates/perry-container-compose/src/types.rs.
8. THE ComposeServicePort TypeScript interface SHALL conform to the compose-spec port definition and support: name?: string, mode?: string, host_ip?: string, target: number | string, published?: string | number, protocol?: string, app_protocol?: string — matching the ComposeServicePort Rust struct in crates/perry-container-compose/src/types.rs.
9. THE ComposeServiceVolume TypeScript interface SHALL conform to the compose-spec volume mount definition and support: type: "bind" | "volume" | "tmpfs" | "cluster" | "npipe" | "image", source?: string, target?: string, read_only?: boolean, consistency?: string, bind?: { propagation?: string, create_host_path?: boolean, recursive?: "enabled" | "disabled" | "writable" | "readonly", selinux?: "z" | "Z" }, volume?: { labels?: ListOrDict, nocopy?: boolean, subpath?: string }, tmpfs?: { size?: string | number, mode?: number }, image?: { subpath?: string } — matching the ComposeServiceVolume Rust struct in crates/perry-container-compose/src/types.rs.
10. THE ComposeDependsOn TypeScript interface SHALL conform to the compose-spec depends_on object form and support: condition: "service_started" | "service_healthy" | "service_completed_successfully", required?: boolean, restart?: boolean — matching the ComposeDependsOn Rust struct in crates/perry-container-compose/src/types.rs.
11. THE ListOrDict TypeScript type SHALL be defined as Record<string, string | number | boolean | null> | string[], matching the compose-spec list_or_dict pattern and the ListOrDict Rust enum in crates/perry-container-compose/src/types.rs.
12. THE TypeScript interfaces SHALL be the authoritative schema; no YAML, CUE, pkl, or KCL schema is required.
13. FOR ALL valid ComposeSpec objects, serialising to the ComposeEngine's internal Rust representation and deserialising back SHALL produce an equivalent ComposeSpec (round-trip property), verified by a property-based test suite.
14. FOR ALL ComposeServiceVolume objects, THE type system SHALL accept only the six valid type field values (bind, volume, tmpfs, cluster, npipe, image); any other value SHALL be rejected at parse time with a descriptive error identifying the invalid type and the service name.

Requirement 11: FFI Bridge and Compiler Integration

User Story: As a runtime engineer, I want perry/container and perry/container-compose to be implemented via Perry's standard FFI pattern and wired into the compiler's HIR lowering and codegen dispatch.

Acceptance Criteria

1. ALL perry/container functions SHALL be implemented as #[no_mangle] pub unsafe extern "C" fn js_container_* functions in crates/perry-stdlib/src/container/mod.rs, following the same pattern as js_container_run, js_container_list, etc. that already exist.
2. ALL perry/container-compose functions SHALL be implemented as #[no_mangle] pub unsafe extern "C" fn js_container_compose_* functions in crates/perry-stdlib/src/container/mod.rs, delegating to the perry-container-compose crate's library API. These include at minimum: js_container_compose_up(), js_container_compose_down(), js_container_compose_ps(), js_container_compose_logs(), js_container_compose_exec(), js_container_compose_config(), js_container_compose_start(), js_container_compose_stop(), js_container_compose_restart().
3. THE container Cargo feature in crates/perry-stdlib/Cargo.toml SHALL gate the entire perry/container and perry/container-compose module, consistent with the existing #[cfg(feature = "container")] guard in lib.rs.
4. THE Perry compiler's HIR lowering (crates/perry-hir/src/lower.rs) SHALL recognise import { ... } from 'perry/container' and import { ... } from 'perry/container-compose' and map each imported function to its corresponding js_container_* or js_container_compose_* FFI declaration, following the same pattern used for perry/thread and perry/ui.
5. THE Perry compiler's codegen (crates/perry-codegen/src/codegen.rs) SHALL emit direct call instructions to the js_container_* and js_container_compose_* FFI symbols for all perry/container and perry/container-compose call sites, following the same dispatch table pattern used for perry/ui (PERRY_UI_TABLE).
6. THE js_container_module_init() function in mod.rs SHALL be called during module initialisation to force backend selection before any container operation is attempted.
7. ALL async js_container_* and js_container_compose_* functions SHALL return a *mut Promise and use crate::common::spawn_for_promise() to execute the async backend operation, consistent with the existing pattern in mod.rs.
8. THE perry check command SHALL NOT flag perry/container or perry/container-compose as missing npm packages or unsupported Node.js built-ins, consistent with the is_perry_builtin() guard added for perry/ui, perry/thread, and perry/i18n in v0.5.15.

Requirement 12: Container Operation Correctness and Error Propagation

User Story: As a QA engineer, I want container operations to correctly propagate backend output and errors.

Acceptance Criteria

1. FOR ALL successful container operations, THE Promise SHALL resolve with a value whose TypeScript type matches the documented return type.
2. FOR ALL failed container operations, THE Promise SHALL reject with an Error object that includes both a human-readable message and a numeric code property, propagated from ContainerError::BackendError { code, message }.
3. THE ContainerLogs object returned by logs and exec SHALL contain the complete, untruncated stdout and stderr output from the backend process.
4. WHEN inspect is called immediately after run, THE returned ContainerInfo SHALL reflect the running state.
5. THE serialisation of ContainerSpec to backend CLI arguments and deserialisation of backend JSON output to ContainerInfo SHALL be verified by a property-based test suite running a minimum of 100 iterations per property.
6. THE serialisation of ComposeSpec to the ComposeEngine's internal Rust representation and back SHALL be verified by a round-trip property-based test suite running a minimum of 100 iterations per property.

Requirement 13: OCI Isolation for Shell Capabilities

User Story: As a security engineer, I want perry/container to provide OCI container isolation for shellCapabilities entries defined in perryconfig.toml.

Acceptance Criteria

1. THE perry-stdlib container module SHALL expose an internal perry_container_run_capability(name: &str, image: &str, cmd: &[&str], grants: &CapabilityGrants) -> Result<ContainerLogs, ContainerError> Rust function used by the ShellBridge; this function SHALL NOT be part of the public TypeScript API.
2. WHEN a shellCapability is invoked, THE container module SHALL create an ephemeral container using the platform ContainerBackend.
3. THE container created for a shellCapability SHALL be configured with: no persistent volumes, no network access by default, read-only root filesystem, and a seccomp profile blocking dangerous syscalls.
4. WHEN the shellCapability command exits, THE container module SHALL stop and remove the container immediately (equivalent to --rm --force).
5. THE ShellBridge SHALL call perry_container_run_capability to create and manage ephemeral containers; the ShellBridge SHALL NOT invoke the ContainerBackend directly.

Requirement 14: Chainguard Base Image for Shell Capabilities

User Story: As a security engineer, I want shellCapability containers to use hardened, minimal Chainguard images by default.

Acceptance Criteria

1. THE default base image for shellCapability containers SHALL be cgr.dev/chainguard/alpine-base, returned by get_default_base_image() in crates/perry-stdlib/src/container/verification.rs.
2. WHEN a Chainguard-specific image exists for the named binary (as returned by get_chainguard_image(tool) in verification.rs), THE runtime SHALL prefer that image over cgr.dev/chainguard/alpine-base.
3. THE runtime SHALL verify the Chainguard image signature via Sigstore/cosign before pulling or running any image; unverified images SHALL be rejected with ContainerError::VerificationFailed.
4. THE shellCapabilityImages TOML table in perryconfig.toml SHALL allow users to override the container image per capability; overridden images MUST also pass Sigstore/cosign verification.
5. IF image verification fails, THE runtime SHALL reject the shellCapability invocation with a ContainerError::VerificationFailed before creating any container.

Requirement 15: Image Signature Verification

User Story: As a security engineer, I want all OCI images used for shellCapability containers to be cryptographically verified before execution.

Acceptance Criteria

1. ALL OCI images used for shellCapability containers SHALL be verified via Sigstore/cosign before execution, using verify_image() in crates/perry-stdlib/src/container/verification.rs.
2. THE verification SHALL use cosign's keyless verification with the Sigstore public good instance; certificate identity SHALL be validated against CHAINGUARD_IDENTITY and OIDC issuer against CHAINGUARD_ISSUER as defined in verification.rs.
3. WHEN an image cannot be verified, THE runtime SHALL reject with a ContainerError::VerificationFailed including the image reference and failure reason.
4. THE runtime SHALL cache successful verification results for the duration of the process lifetime, keyed by image digest (not tag), using the VERIFICATION_CACHE in verification.rs.
5. THE runtime SHALL NOT fall back to running an unverified image under any circumstances.
6. FOR ALL shellCapability container images, the verification result SHALL be logged at debug level including image reference, digest, and cosign verification output.
7. FOR ALL image references, the round-trip of fetching the digest and looking up the cached result SHALL return the same verification outcome (idempotence property), verified by a property-based test suite.

Requirement 16: Container Runtime Auto-Detection

User Story: As a Perry developer, I want perry/container to automatically discover which OCI-compatible container runtime is installed on my machine, so that my code works without manual configuration regardless of whether I use Podman, Colima, OrbStack, Rancher Desktop, Lima, or Apple Container.

Acceptance Criteria

1. THE detect_backend() function in crates/perry-container-compose/src/backend.rs SHALL implement the full multi-candidate probe sequence for each platform, with platform-native runtimes prioritized over cross-platform ones, and podman always preferred over docker:
   • macOS/iOS (platform-native first, cross-platform last): apple/container → orbstack → colima → rancher-desktop → lima → podman → nerdctl → docker
   • Linux: podman → nerdctl → docker
   • Windows: podman → nerdctl → docker
   • Rationale: On macOS, platform-native runtimes (apple/container, orbstack, colima) provide native OS integration and are preferred. podman is preferred over docker on all platforms because it is daemonless, rootless by default, and OCI-native. docker is always the last fallback.
   • The successful result SHALL be stored as a BackendDriver enum variant (e.g. BackendDriver::Podman { bin }, BackendDriver::AppleContainer { bin }) carrying the resolved CLI binary path.
2. EACH probe SHALL be non-blocking and SHALL complete within 2 seconds (timeout per candidate).
3. THE probe for socket-based runtimes SHALL check the socket path exists AND is connectable.
4. THE probe for CLI-based runtimes SHALL run <cli> --version or equivalent and check for zero exit code.
5. THE probe for colima SHALL additionally run colima status and check the output contains "running".
6. THE probe for podman on macOS SHALL additionally run podman machine list --format json and check that at least one machine has "Running": true.
7. THE probe for limactl SHALL additionally run limactl list --json and check that at least one instance is in "Running" status.
8. THE probe for OrbStack SHALL check for the orb binary OR the OrbStack Docker socket at ~/.orbstack/run/docker.sock.
9. THE probe for Rancher Desktop SHALL check for nerdctl binary AND the containerd socket at ~/.rd/run/containerd-shim.sock or equivalent.
10. FOR ALL probed backends, the probe result (available/unavailable + reason) SHALL be logged at debug level.
11. THE ContainerError enum SHALL include a NoBackendFound { probed: Vec<BackendProbeResult> } variant where BackendProbeResult has name: String, available: bool, reason: String.
12. THE PERRY_CONTAINER_BACKEND environment variable SHALL accept the following values: "apple/container", "orbstack", "colima", "rancher-desktop", "podman", "lima", "nerdctl", "docker".

Requirement 17: WIT Interface Contract

User Story: As a runtime engineer, I want perry/container to define a formal WIT (WebAssembly Interface Types) interface contract, so that the container API surface is precisely specified and can be used across different execution targets.

Acceptance Criteria

1. THE Perry compiler SHALL define a perry:container WIT interface in src/core/wit/perry-container.wit that declares all container and compose operations as WIT function signatures.
2. THE WIT interface SHALL declare the following container functions: run, create, start, stop, remove, list, inspect, logs, exec, pull-image, list-images, remove-image, get-backend, detect-backend, compose-up.
3. THE WIT interface SHALL declare the following compose handle functions: compose-down, compose-ps, compose-logs, compose-exec.
4. THE WIT interface SHALL define WIT record types corresponding to ContainerSpec, ContainerHandle, ContainerInfo, ContainerLogs, ImageInfo, and BackendInfo.
5. THE WIT interface SHALL be consistent with the TypeScript type declarations exported by the Perry compiler for perry/container.
6. IF the WIT interface and the TypeScript type declarations diverge, THE compiler build SHALL fail with a descriptive error identifying the mismatch.

Requirement 18: Deployment-Target-Aware Backend Dispatch

User Story: As a Perry developer, I want perry/container to adapt its backend selection strategy based on the deployment target, so that container operations work correctly whether my application is running locally or on a remote server.

Acceptance Criteria

1. THE detect_backend() function SHALL support two dispatch modes: local-first (default) and server-first, selectable via the PERRY_CONTAINER_MODE environment variable.
2. WHEN operating in local-first mode, THE runtime SHALL probe for locally installed container runtimes in the platform-specific priority order defined in Requirement 16 AC 1.
3. WHEN operating in server-first mode, THE runtime SHALL prefer remote container daemon connections (e.g. Docker socket forwarding, remote podman socket) over local CLI-based runtimes.
4. THE BackendInfo TypeScript interface SHALL include a mode: "local" | "remote" field indicating whether the selected backend is a local CLI or a remote daemon connection.
5. WHEN PERRY_CONTAINER_MODE is set to an unrecognised value, THE runtime SHALL return ContainerError::InvalidConfiguration with a descriptive message listing the accepted values.
6. THE deployment mode SHALL be determined once at process startup and cached alongside the backend selection result in the same OnceLock.

Requirement 19: Go Reference Parity and Extension

User Story: As a runtime engineer, I want perry-container-compose to implement all features from the Go container-compose/cli reference project plus all missing features, so that the Rust port is a complete superset of the original.

Acceptance Criteria

1. THE perry-container-compose crate SHALL implement all features present in the Go reference project: image, build (with context, dockerfile, args, labels, target, network), ports, environment, labels, volumes, container_name, container state management (running/stopped/not-exists), automatic build when needed.
2. THE Service struct in service.rs SHALL implement the following methods ported from internal/entities/service.go: generate_name() (MD5-based, replacing goombaio/namegenerator), exists() (check if container exists), is_running() (check if container is running), run_command() (create and run container, building if needed), start_command() (start existing container), build_command() (build image from build config), inspect_command() (inspect container), needs_build() (check if image needs to be built).
3. THE perry-container-compose crate SHALL implement all features MISSING from the Go reference project: networks field, volumes field (top-level), depends_on field with dependency resolution, environment variable interpolation (${VARIABLE} and ${VARIABLE:-default}), .env file loading, multiple compose file merging, project names (-p/--project-name), ps command, logs command, exec command, config command, down command, stop command, restart command.
4. THE perry-container-compose crate SHALL replace github.com/goombaio/namegenerator with a custom MD5-based name generation: generate_name(image: &str, service_name: &str) -> String producing {name}_{md5(image)[0..8]}_{random_u32}.
5. THE perry-container-compose crate SHALL replace github.com/spf13/cobra with clap for CLI argument parsing.
6. THE perry-container-compose crate SHALL replace gopkg.in/yaml.v3 with serde_yaml for YAML parsing.
7. THE perry-container-compose crate SHALL replace Go goroutines and context.Context with tokio async/await.
8. THE perry-container-compose crate SHALL replace Go's error interface with Rust's Result<T, ComposeError> and the thiserror crate for error definitions.

Requirement 20: Interactive Backend Installer (No Backend Found)

User Story: As a Perry developer who has no container runtime installed, I want the runtime to detect this situation and guide me through picking and installing a supported backend for my platform, so that I can get started without having to research installation steps myself.

Acceptance Criteria

1. WHEN detect_backend() returns NoBackendFound AND the process is running in an interactive terminal (i.e. stderr is a TTY), THE runtime SHALL invoke the interactive backend installer instead of immediately returning an error.
2. THE interactive installer SHALL display a platform-appropriate list of supported backends with a brief description of each, ordered by the platform priority order defined in Requirement 16 AC 1.
3. THE interactive installer SHALL prompt the user to select one backend from the list using arrow-key navigation (or numbered input as a fallback for non-ANSI terminals).
4. FOR EACH selectable backend, THE installer SHALL display: the backend name, a one-line description, the installation method (e.g. brew install podman, brew install --cask orbstack), and a URL to the official installation documentation.
5. AFTER the user selects a backend, THE installer SHALL print the exact installation command(s) for that backend on the current platform and offer to run them automatically (with explicit user confirmation before executing any command).
6. IF the user confirms automatic installation, THE installer SHALL execute the installation command(s), stream their output to the terminal, and re-run detect_backend() after completion to verify the installation succeeded.
7. IF the installation succeeds, THE installer SHALL print a success message and continue with the originally requested container operation using the newly installed backend.
8. IF the installation fails or the user declines automatic installation, THE installer SHALL print the manual installation instructions and exit with a non-zero code and a human-readable error message.
9. WHEN the process is NOT running in an interactive terminal (i.e. stderr is not a TTY — CI, scripts, piped output), THE runtime SHALL skip the interactive installer entirely and return ContainerError::NoBackendFound as before, with a non-interactive error message that includes the manual installation hint for the platform's recommended backend.
10. THE interactive installer SHALL be implemented in crates/perry-container-compose/src/installer.rs and SHALL be invoked by get_global_backend_instance() when detect_backend() returns NoBackendFound.
11. THE installer SHALL support the following platform-specific backend options and installation commands:

macOS / iOS:

Backend	Description	Install command	Docs URL
apple/container	Apple's native container runtime (recommended)	brew install container	https://github.com/apple/container
orbstack	Fast macOS VM with Docker-compatible API	brew install --cask orbstack	https://orbstack.dev
colima	Lightweight macOS container runtime	brew install colima	https://github.com/abiosoft/colima
podman	Daemonless, rootless OCI runtime	brew install podman && podman machine init && podman machine start	https://podman.io
docker	Docker Desktop for Mac	brew install --cask docker	https://docs.docker.com/desktop/mac

Linux:

Backend	Description	Install command	Docs URL
podman	Daemonless, rootless OCI runtime (recommended)	sudo apt-get install -y podman (Debian/Ubuntu) or sudo dnf install -y podman (Fedora/RHEL)	https://podman.io/getting-started/installation
nerdctl	containerd CLI wrapper	brew install nerdctl or see docs	https://github.com/containerd/nerdctl
docker	Docker Engine	`curl -fsSL https://get.docker.com	sh`

Windows:

Backend	Description	Install command	Docs URL
podman	Daemonless, rootless OCI runtime (recommended)	winget install RedHat.Podman	https://podman.io/getting-started/installation
docker	Docker Desktop for Windows	winget install Docker.DockerDesktop	https://docs.docker.com/desktop/windows

12. THE installer output SHALL use ANSI colour codes when the terminal supports them: backend names in bold, install commands in a distinct colour (e.g. cyan), success messages in green, error messages in red.
13. THE installer SHALL be skippable via the PERRY_NO_INSTALL_PROMPT=1 environment variable, which causes the runtime to return ContainerError::NoBackendFound immediately without prompting, even in an interactive terminal.

I have implemented the perry/container and perry/workloads modules according to the specs. Key actions taken:

1. Backend Detection & Protocol: Implemented a robust auto-detection system for container backends (macOS/iOS: apple/container prioritized; Linux/Windows: podman prioritized). Added DockerProtocol, AppleContainerProtocol, and LimaProtocol to handle CLI argument translation.
2. Compose Engine: Ported orchestration logic including Kahn's algorithm for deterministic topological sort, parallel startup by levels, and RollbackAll failure strategy.
3. Workload Graph API: Implemented the WorkloadGraphEngine with support for WorkloadRef resolution (IP/Endpoint injection) after startup, fulfilling Requirement 15.1.
4. Security & Policies: Added support for PolicyTier mapping to ContainerSpec security options (privileged, user, workdir, cap_add, cap_drop, read_only, seccomp). Updated perry-stdlib/src/container/capability.rs to enforce these constraints for ephemeral capability containers.
5. Interactive Installer: Completed BackendInstaller to provide guided installation on TTYs when no runtime is found.
6. Compiler Integration: Wired all FFI symbols (js_container_*, js_container_compose_*, js_workload_*) into perry-hir and perry-codegen. Updated perry-compiler to correctly trigger the container stdlib feature for all related modules.
7. Data Models & WIT: Refined the Rust structs and matched them in perry-container.wit for cross-target compatibility.
8. Verification: All unit, functional, and property tests are passing. Added an E2E harness which verified successful execution of container and workload scripts.