Implement perry/container and perry/container-compose

[yumin-chen]

Implementation of OCI container management and multi-container orchestration for Perry. Includes a refactored Rust orchestration library, a flexible backend detection system, image building, signature verification, and a standard library FFI bridge. Verified with property-based tests for serialization, dependency resolution, and YAML interpolation.

---

PR created automatically by Jules for task 15047136353880386723 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]

I've completed the implementation and alignment with the design document.

Key accomplishments:

1. Refactored perry-container-compose to the flat layout and generic CliBackend for zero vtable overhead.
2. Implemented lean NetworkConfig and VolumeConfig to decouple OCI from high-level Compose types.
3. Fixed compiler integration in perry-hir (module naming and linking) and perry-codegen (FFI dispatch).
4. Completed the security hardening for shell capabilities, including Sigstore image verification and OCI sandboxing.
5. Added a production-ready Forgejo deployment example in example-code/forgejo-deployment/main.ts.

I've verified the build and ran the property-based tests. Ready for final review!

[google-labs-jules]

Implement as per below specs and ensure production readiness:

Perry Container Subsystem Canonical Specification

---

Table of Contents

1. Scope
2. Core System Behavior
3. Architecture Assumptions
4. ContainerBackend Trait (Canonical Contract)
5. Backend Detection & Priority Order
6. ComposeEngine Orchestration
7. TypeScript API Surface
8. Container Naming Convention
9. FFI Bridge
10. Compiler Integration
11. Optional Variants
12. Conflict Log
13. Confidence Map
14. Drift Analysis

---

1. Scope

This specification covers the Perry container subsystem, consisting of:

Module	Import Path	Backing Crate
Container lifecycle	perry/container	crates/perry-container-compose + crates/perry-stdlib
Compose orchestration	perry/compose	crates/perry-container-compose
Workload graph (optional)	perry/workloads	crates/perry-container-compose + crates/perry-stdlib

The subsystem bridges Perry TypeScript user code → FFI → Rust crate → native OCI container runtime.

---

2. Core System Behavior

2.1 Minimal Required Behavior

1. Run a single OCI container from a ContainerSpec, returning a ContainerHandle.
2. Orchestrate multi-container stacks from a ComposeSpec via ComposeEngine, returning a ComposeHandle (opaque integer stack ID).
3. Auto-detect the best available container runtime with no user configuration required.
4. Resolve service dependencies using Kahn's topological sort algorithm before starting containers.
5. Roll back all session resources (containers, networks, volumes) on orchestration failure.
6. Expose a consistent Promise<T>-returning async API to TypeScript.

2.2 Explicit Constraints

• No YAML files in TS API. The TypeScript-facing composeUp() / up() accepts only ComposeSpec objects (TS object literals). YAML file handling is reserved for the standalone CLI binary.
• Platform adaptation is automatic. Users never call platform-specific code.
• State isolation. Each ComposeEngine instance tracks its own session resources (containers, networks, volumes). Resources from different sessions do not interfere.
• Dependency-correct startup. Services with depends_on must not start before their dependencies. Cycles are errors.
• Idempotent up. If a service is already running, up skips it rather than restarting.

2.3 Expected Inputs / Outputs

run(spec: ContainerSpec) → Promise<ContainerHandle>

• Input: ContainerSpec (JSON-serialized to FFI boundary)
• Output: ContainerHandle { id: string, name?: string }

composeUp(spec: ComposeSpec) → Promise<number> (via perry/container)

up(spec: ComposeSpec) → Promise<ComposeHandle> (via perry/compose)

• Input: ComposeSpec conforming to compose-spec JSON schema
• Output: ComposeHandle (opaque integer stack ID, type number)

down(handle, opts?) → Promise<void>

• Input: Stack handle + optional { volumes?: boolean }
• Effect: Stops and removes containers, networks (and volumes if volumes: true)

ps(handle) → Promise<ContainerInfo[]>

logs(handle, opts?) → Promise<ContainerLogs>

exec(handle, service, cmd) → Promise<ContainerLogs>

start/stop/restart(handle, services?) → Promise<void>

config(handle) → Promise<string> — resolved YAML string

---

3. Architecture Assumptions

TypeScript user code
       │  import { ... } from "perry/container"
       │  import { ... } from "perry/compose"
       ▼
perry-hir (HIR lowering — lower.rs)
  maps TS method names → FFI symbol strings
       │
       ▼
perry-codegen (lower_call.rs)
  emits LLVM calls to FFI symbols
       │
       ▼
perry-stdlib / src / container / (FFI bridge)
  mod.rs        — main FFI exports (js_container_*, js_compose_*)
  compose.rs    — compose logic adapters
  backend.rs    — thin re-export of perry-container-compose backend
  capability.rs — OCI capability sandbox helper
  workload.rs   — workload graph re-exports
  verification.rs — Sigstore/cosign image verification
       │
       ▼
perry-container-compose (Rust crate — business logic)
  backend.rs    — ContainerBackend trait + CliBackend/CliProtocol + detect_backend()
  compose.rs    — ComposeEngine (up/down/ps/logs/exec/start/stop/restart/config)
  types.rs      — ComposeSpec, ContainerSpec, all data types
  service.rs    — service container name generation + state helpers
  project.rs    — ComposeProject YAML loading (CLI-only path)
  yaml.rs       — YAML parsing, .env interpolation, multi-file merge
  error.rs      — ComposeError enum, BackendProbeResult
  installer.rs  — interactive BackendInstaller
  cli.rs        — clap-based standalone CLI
  orchestrate.rs — single-service orchestration helper
       │
       ▼
Native OCI runtime (apple/container, podman, orbstack, colima, …)

Invariant: GUI and engine are fully decoupled. The compiler (HIR + codegen) references only FFI symbol strings. The runtime implementation is swappable without recompilation.

---

4. ContainerBackend Trait (Canonical Contract)

The following method set is stable across all implementations analyzed (high confidence):

#[async_trait]
pub trait ContainerBackend: Send + Sync {
    fn backend_name(&self) -> &str;

    async fn check_available(&self) -> Result<()>;

    // Container lifecycle
    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<()>;

    // Inspection
    async fn list(&self, all: bool) -> Result<Vec<ContainerInfo>>;
    async fn inspect(&self, id: &str) -> Result<ContainerInfo>;

    // I/O
    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>;

    // Image management
    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>;

    // Network / Volume management
    async fn create_network(&self, name: &str, config: &NetworkConfig) -> Result<()>;
    async fn remove_network(&self, name: &str) -> Result<()>;
    async fn inspect_network(&self, name: &str) -> Result<()>;
    async fn create_volume(&self, name: &str, config: &VolumeConfig) -> Result<()>;
    async fn remove_volume(&self, name: &str) -> Result<()>;

    // Lifecycle utilities
    async fn wait(&self, id: &str) -> Result<i32>;
}

Layer 2 — CliProtocol trait (implementation detail, stable):

pub trait CliProtocol: Send + Sync {
    fn protocol_name(&self) -> &str;
    fn subcommand_prefix(&self) -> Option<Vec<String>> { None }
    // ... command building methods
}

Concrete protocol implementations: DockerProtocol, AppleContainerProtocol, LimaProtocol { instance: String }.

Generic executor: CliBackend<P: CliProtocol> — holds bin: PathBuf + protocol, implements ContainerBackend by delegating to tokio::process::Command.

⚠️ Conflict note: One branch (feat/container-workloads-*) used a different internal decomposition (BackendDriver enum + OciCommandBuilder struct) instead of CliBackend<P: CliProtocol>. The canonical version (present in HEAD + requirements.md) uses CliProtocol trait. See §12 for detail.

---

5. Backend Detection & Priority Order

5.1 Auto-detection Algorithm

pub async fn detect_backend() -> Result<Arc<dyn ContainerBackend + Send + Sync>, Vec<BackendProbeResult>>

1. If PERRY_CONTAINER_BACKEND env var is set → probe only that backend (skip priority list).
2. Iterate platform_candidates() in order; for each, tokio::time::timeout(2s, probe_candidate(name)).
3. Return first successful probe. If all fail, return Err(Vec<BackendProbeResult>).
4. On Err, if interactive TTY and PERRY_NO_INSTALL_PROMPT not set → invoke BackendInstaller.

5.2 Platform Priority Order

Platform	Priority (highest → lowest)
macOS / iOS	apple/container → orbstack → colima → rancher-desktop → lima → podman → nerdctl → docker
Linux	podman → nerdctl → docker
Windows	podman → docker

Note: iOS is grouped with macOS (same target_os = "ios" logic). Windows support is required by installer spec but Linux-like backend order applies.

5.3 Per-Backend Liveness Checks

Backend	Probe method
apple/container	which container + check_available()
podman	which podman + check podman machine list --format=json for a running machine
orbstack	which orbstack (or orb) + socket/version check
colima	which colima + colima status check
rancher-desktop	socket verification
lima	limactl list for running instance
nerdctl / docker	which + daemon availability

5.4 BackendInstaller (interactive fallback)

• Invoked when detect_backend() returns no backend found.
• Skipped when: PERRY_NO_INSTALL_PROMPT=1 or stderr is not a TTY.
• Uses ANSI color codes: backend names bold, install commands cyan, success green, error red.
• Implemented in crates/perry-container-compose/src/installer.rs.

5.5 Global Backend Singleton

// In perry-stdlib/src/container/mod.rs
static BACKEND: OnceLock<Arc<dyn ContainerBackend + Send + Sync>> = OnceLock::new();

Double-checked initialization via tokio::sync::Mutex. All FFI calls share one backend instance per process.

---

6. ComposeEngine Orchestration

6.1 State Model

pub struct ComposeEngine {
    pub spec: ComposeSpec,
    pub project_name: String,
    pub backend: Arc<dyn ContainerBackend>,
    session_containers: Mutex<Vec<String>>,
    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.

6.2 up() Startup Sequence

1. resolve_startup_order(&spec) — Kahn's topological sort on depends_on edges; returns Vec<String> or ComposeError::DependencyCycle.
2. Filter to target services (or all if empty).
3. Create networks (skip external: true).
4. Create volumes (skip external: true).
5. Start services in dependency order:
   • If already running → skip (idempotent).
   • If exists but stopped → start.
   • If not exists → optionally build → run.
6. On any failure → rollback (remove session containers, networks, volumes in reverse order).
7. Register engine + return ComposeHandle { stack_id, project_name, services }.

6.3 down() Teardown Sequence

1. Stop all tracked containers (from session_containers, reverse order).
2. Remove all tracked containers.
3. Remove non-external networks.
4. If volumes: true → remove non-external volumes.
5. Unregister engine from global registry.

6.4 Dependency Resolution

Uses Kahn's algorithm (BFS topological sort). Cycles produce ComposeError::DependencyCycle { services: Vec<String> }. Both depends_on: string[] (list form) and depends_on: { service: { condition } } (map form) are supported.

6.5 ComposeProject (CLI-only path)

For the standalone CLI, ComposeProject::load_from_files(files, project_name, env_files) handles:

• Multi-file YAML merging (later files override earlier ones).
• .env file loading with ${VAR} and ${VAR:-default} interpolation.
• Project name resolution: spec > env var > directory name.

---

7. TypeScript API Surface

7.1 perry/container

// Container lifecycle
function run(spec: ContainerSpec): Promise<ContainerHandle>
function create(spec: ContainerSpec): Promise<ContainerHandle>
function start(id: string): Promise<void>
function stop(id: string, timeout?: number): Promise<void>
function remove(id: string, force?: boolean): Promise<void>

// Inspection
function list(all?: boolean): Promise<ContainerInfo[]>
function inspect(id: string): Promise<ContainerInfo>

// I/O
function logs(id: string, options?: { follow?: boolean; tail?: number }): Promise<ContainerLogs | ReadableStream<string>>
function exec(id: string, cmd: string[], options?: { env?: Record<string, string>; workdir?: string }): Promise<ContainerLogs>

// Images
function pullImage(reference: string): Promise<void>
function listImages(): Promise<ImageInfo[]>
function removeImage(reference: string, force?: boolean): Promise<void>

// Compose entry point (convenience alias)
function composeUp(spec: ComposeSpec): Promise<number>

// Backend info
function getBackend(): string
function detectBackend(): Promise<string>  // JSON array of BackendProbeResult

7.2 perry/compose

function up(spec: ComposeSpec, options?: UpOptions): Promise<ComposeHandle>
function down(handle: ComposeHandle, options?: DownOptions): Promise<void>
function ps(handle: ComposeHandle): Promise<ContainerInfo[]>
function logs(handle: ComposeHandle, options?: LogsOptions): Promise<ContainerLogs>
function exec(handle: ComposeHandle, service: string, cmd: string[]): Promise<ContainerLogs>
function config(handle: ComposeHandle): Promise<string>
function start(handle: ComposeHandle, services?: string[]): Promise<void>
function stop(handle: ComposeHandle, services?: string[]): Promise<void>
function restart(handle: ComposeHandle, services?: string[]): Promise<void>

type ComposeHandle = number  // opaque stack ID

7.3 Key Data Types

interface ContainerSpec {
  image: string
  name?: string
  ports?: string[]
  volumes?: string[]
  env?: Record<string, string>
  cmd?: string[]
  entrypoint?: string[]
  network?: string
  rm?: boolean
  labels?: Record<string, string>
  // Security options
  read_only?: boolean
  seccomp?: string           // 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 ComposeSpec {
  version?: string
  services: Record<string, ComposeService>
  networks?: Record<string, ComposeNetwork>
  volumes?: Record<string, ComposeVolume>
}

interface ComposeService {
  image?: string
  build?: { context?: string; dockerfile?: string; args?: Record<string, string>; target?: string; network?: string; labels?: Record<string, string> }
  command?: string | string[]
  entrypoint?: string | string[]
  environment?: Record<string, string> | string[]
  ports?: string[]
  volumes?: string[]
  networks?: string[]
  depends_on?: string[] | Record<string, { condition?: string }>
  restart?: "no" | "always" | "on-failure" | "unless-stopped"
  healthcheck?: ComposeHealthcheck
  container_name?: string
  labels?: Record<string, string>
  // Security options (mapped to ContainerSpec)
  privileged?: boolean
  user?: string
  working_dir?: string
  cap_add?: string[]
  cap_drop?: string[]
}

---

8. Container Naming Convention

8.1 Canonical Format

{md5_8chars}-{random_hex8}

Example: a3f2b1c9-00e4f2a1

• md5_8chars = first 8 hex chars of MD5(service YAML or image name).
• random_hex8 = random u32 formatted as 8-char hex.

Important ambiguity: The requirements.md spec says {name}_{hash} (underscore separator, image-based MD5), while the canonical implementation uses - (hyphen separator, service-YAML-based MD5). The implementation pattern uses hyphens and is more stable (appears in HEAD + recent PRs). The requirements doc underscore format is considered spec noise / copy error.

8.2 Explicit Override

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

---

9. FFI Bridge

9.1 FFI Symbol Table (canonical, from lower_call.rs + perry-hir)

perry/container symbols:

TS method	FFI symbol	Args	Return
run	js_container_run	Str	Promise
create	js_container_create	Str	Promise
start	js_container_start	Str	Promise
stop	js_container_stop	Str, F64	Promise
remove	js_container_remove	Str, F64	Promise
list	js_container_list	F64	Promise
inspect	js_container_inspect	Str	Promise
logs	js_container_logs	Str, F64	Promise
exec	js_container_exec	Str, Str, Str, Str	Promise
pullImage	js_container_pullImage	Str	Promise
listImages	js_container_listImages	(none)	Promise
removeImage	js_container_removeImage	Str, F64	Promise
getBackend	js_container_getBackend	(none)	Str
detectBackend	js_container_detectBackend	(none)	Promise
build	js_container_build	Str, Str	Promise
composeUp	js_container_composeUp	Str	Promise

perry/compose symbols:

TS method	FFI symbol	Args	Return
up	js_compose_up	Str	Promise
down	js_compose_down	F64, F64	Promise
ps	js_compose_ps	F64	Promise
logs	js_compose_logs	F64, Str, F64	Promise
exec	js_compose_exec	F64, Str, Str, Str	Promise
config	js_compose_config	F64	Promise
start	js_compose_start	F64, Str	Promise
stop	js_compose_stop	F64, Str	Promise
restart	js_compose_restart	F64, Str	Promise

Alias pattern: js_compose_* are thin wrappers that call js_container_compose_*. Both symbol names are valid.

9.2 String ABI

• Strings cross the FFI boundary as *const StringHeader (Perry runtime layout).
• StringHeader { length: u32 } followed immediately by UTF-8 bytes.
• Pointer validation: ptr.is_null() || ptr as usize < 0x1000 → reject.
• Results are serialized to JSON strings before return (or *mut Promise for async).

9.3 Error Envelope

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

---

10. Compiler Integration

10.1 HIR Lowering (perry-hir/src/lower.rs)

The HIR layer recognizes "perry/container" and "perry/compose" as native module imports and maps method calls to FFI symbol strings (see §9.1). Pattern:

"perry/container" => match method {
    "run" => Some("js_container_run"),
    // ...
}
"perry/compose" => match method {
    "up" => Some("js_compose_up"),
    // ...
}

10.2 Codegen (perry-codegen/src/lower_call.rs)

Uses UiSig dispatch table with UiArgKind::{Str, F64} and UiReturnKind::{Promise, Str}. The table must be kept in sync with the FFI symbol table in §9.1. Pattern follows perry/plugin, perry/ui, perry/i18n.

10.3 Cargo Feature Gate

The container subsystem is gated behind the container feature in perry-stdlib/Cargo.toml. Not enabled by default in all build targets.

---

11. Optional Variants

Features present in some branches but not yet in HEAD — explicitly annotated as optional / in-progress:

11.1 perry/workloads — Workload Graph API

Appears in: feat/container-workloads-*, multiple Jules bot branches
Not present in: HEAD (as of April 27, 2026)

// perry/workloads (proposed)
function graph(name: string, spec: Record<string, WorkloadNode>): string
function runGraph(graphJson: string, opts: RunGraphOptions): Promise<number>

interface WorkloadNode {
  id: string; image?: string; ports: string[]; env: Record<string, WorkloadEnvValue>
  depends_on: string[]; runtime: RuntimeSpec; policy: PolicySpec
}

type RuntimeSpec = { type: "oci" | "microVm" | "wasm" | "auto"; config?: any; module?: string }
type PolicySpec  = { tier: "default" | "isolated" | "hardened" | "untrusted"; noNetwork: bool; readOnlyRoot: bool; seccomp: bool }
type RunGraphOptions = { strategy: "sequential" | "maxParallel" | "dependencyAware" | "parallelSafe"; onFailure: "rollbackAll" | "partialContinue" | "haltGraph" }

The workload.rs module exists in HEAD but is not wired to compiler dispatch tables.

11.2 Image Signature Verification (Sigstore/cosign)

Appears in: e92ddd02, multiple production-readiness branches
Status in HEAD: crates/perry-stdlib/src/container/verification.rs exists.

// Verify image signature before pulling
async fn verify_image_signature(reference: &str) -> Result<(), VerificationError>

The VerificationFailed error variant exists in ComposeError but integration into the up() flow is not yet enforced in HEAD.

11.3 PERRY_CONTAINER_BACKEND Environment Override

Status: Implemented in HEAD detect_backend(). Feature flag PERRY_NO_INSTALL_PROMPT also implemented.

11.4 Capability Sandbox (perry-stdlib/src/container/capability.rs)

OCI container used as sandboxed shell executor for capability checking. Pin images by digest to prevent TOCTOU attacks. This is internal tooling not exposed to user code.

---

12. Conflict Log

C1 — Backend Internal Architecture (Medium Confidence)

Conflict: Two architectural approaches for the backend implementation layer:

Branch	Approach
HEAD + feat/container-standardization-v1-*	CliBackend<P: CliProtocol> generic type with DockerProtocol, AppleContainerProtocol, LimaProtocol
feat/container-workloads-* (Jules bot)	BackendDriver enum + OciCommandBuilder struct + OciBackend struct

Resolution: HEAD uses CliProtocol trait approach. This is the canonical form per requirements.md §4 task list. The BackendDriver/OciCommandBuilder approach appears to have been a Jules bot refactoring attempt that was not merged.

Origin: Diverged around commit 5e766aac (April 22, 2026).

---

C2 — Container Naming Format (Low→Medium Confidence)

Conflict: The naming format is inconsistently specified:

Source	Format
requirements.md (intro paragraph)	{name}_{hash} (underscore, image-name-based MD5)
requirements.md (Requirement 13 + 19.2)	{name}_{md5(image)[0..8]}_{random_u32}
HEAD service.rs generate_name()	{md5_8chars}-{random_hex8} (hyphen, service-YAML-based MD5)
Commit message e4d84073	{md5_8chars}-{random_hex}

Resolution: Use hyphen separator (-) and MD5 of service YAML (not image name alone), matching HEAD implementation. The requirements doc underscore format is a copy-paste artifact from early drafts.

---

C3 — Module Naming: perry/compose vs perry/container-compose (Low Conflict)

Conflict:

• perry-container-compose is the crate name.
• perry/compose is the TS import path for the compose-level API.
• perry/container includes composeUp as a convenience shortcut.
• Some branches referenced perry/container-compose as an import path (incorrect).

Resolution: TS import paths are perry/container and perry/compose. The crate name perry-container-compose is an internal Rust name only.

---

C4 — composeUp Return Type (Medium Confidence)

Conflict:

• types/perry/container/index.d.ts: composeUp(spec) → Promise<number>
• types/perry/compose/index.d.ts: up(spec) → Promise<ComposeHandle> where type ComposeHandle = number
• Some branches: returned a rich object with .ps(), .down(), .logs() etc. methods (object-oriented handle)

Resolution: The ComposeHandle is an opaque integer (stack ID). The method-chaining pattern (stack.down(), stack.ps()) seen in forgejo-deployment.ts is sugar that must be implemented at the TS library layer, not returned directly from the FFI. The FFI boundary always passes the integer handle as a separate argument.

---

C5 — ios in platform detection (Low Conflict)

Conflict:

• feat/perry-container-7403634740230062412: cfg!(target_os = "macos") || cfg!(target_os = "ios")
• HEAD detect_backend(): cfg!(target_os = "macos") only (iOS not explicitly present)

Resolution: iOS should use the macOS backend priority list (same apple/container). The iOS branch should be merged back with || cfg!(target_os = "ios").

---

13. Confidence Map

High Confidence (strong consensus across history)

• ContainerBackend trait method set (§4) — identical across 8+ implementations
• Kahn's algorithm for depends_on resolution — mentioned in 15+ commit messages
• Backend priority order: apple/container first on macOS — consistent in all non-bot implementations
• ComposeHandle as opaque integer (stack ID) — consistent in all implementations
• JSON serialization at FFI boundary — invariant since first container commit
• PERRY_CONTAINER_BACKEND env override — present in all recent implementations
• PERRY_NO_INSTALL_PROMPT escape hatch — present in all recent implementations
• OnceLock<Arc<dyn ContainerBackend>> singleton in perry-stdlib — consistent
• Rollback on up() failure — consistent in all production-readiness branches

Medium Confidence (partial agreement)

• CliBackend<P: CliProtocol> as the generic executor (C1 above) — 60% of branches use this
• Exact detect_backend() liveness probe per backend — minor variation across branches
• CONTAINER_WORKLOADS / perry/workloads module — present as work-in-progress in ~40% of branches
• seccomp and labels fields on ContainerSpec — present in production-readiness branches
• Interactive BackendInstaller implementation details — slight variation in UX flow

Low Confidence (isolated or contradictory)

• Container naming format (see C2) — underscore vs hyphen conflicts
• iOS detection in platform_candidates() — only some branches include it
• Sigstore/cosign enforcement in up() flow — present but not universally applied
• WorkloadGraphEngine strategy options (maxParallel, parallelSafe) — only in bot branches

---

14. Drift Analysis

14.1 Timeline of Divergence

April 15, 2026  e92ddd02  First large canonical implementation (Yumin Chen)
                          — perry-container-compose + perry-stdlib FFI
                          — Kahn's algorithm, multi-backend, Sigstore
                          
April 22, 2026  e4d84073  Canonical spec alignment commit (Yumin Chen)
                          — Merged multiple improvements into HEAD
                          — Standardized CliBackend<P: CliProtocol> architecture
                          
April 22, 2026  e487f25d  Merge PR #44 (production-ready v1)
                          — Large diff: +875/-366 lines across 14 files
                          — Aligned FFI signatures, added inspect_network
                          
April 23, 2026  ~40 bot commits (google-labs-jules[bot])
                          — Parallel speculative implementations
                          — Introduced: BackendDriver enum, OciCommandBuilder
                          — Introduced: perry/workloads module
                          — Some used `perry/container-compose` import path (wrong)
                          — Multiple "production-ready" variants with minor differences

14.2 Nature of Divergence

The divergence is a combination of both accidental and intentional branching:

1. Intentional exploration — Yumin Chen created multiple branches (feat/container-compose, feat/container-compose-v1-*) to iterate on the API and implementation architecture. These converged into HEAD.

2. Parallel AI-generated drift — The google-labs-jules[bot] account created ~40 branches with competing implementations. These share the same functional intent (implement perry/container) but differ in:

   • Backend layer decomposition (BackendDriver enum vs CliProtocol trait)
   • Whether to include perry/workloads
   • Liveness probe strategies per backend
   • Container naming format

3. Two hidden sub-specs exist:

   • Sub-spec A (Yumin/canonical): perry/container + perry/compose, CliProtocol trait, no perry/workloads in initial release.
   • Sub-spec B (Jules bot): All of A plus perry/workloads graph engine, BackendDriver enum architecture.

   Sub-spec B appears to be a forward-looking exploration of the workloads API that was not yet approved for HEAD.

14.3 Convergence Signal

The most recent authored commits by Yumin Chen all converge on the same architecture. The bot-generated branches have not been merged. This clearly indicates Sub-spec A is the current canonical intent, with Sub-spec B (perry/workloads) as a planned future extension.

---

Appendix A — Crate Module Structure (Canonical)

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
types/perry/compose/index.d.ts      — TS type declarations for perry/compose

---

Appendix B — Key Dependencies

Dependency	Purpose	Notes
async-trait	Async trait support	Required 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	ComposeError
indexmap	Ordered maps	Service startup order preservation
md5 + hex	Container name generation	{hash}-{random} format
rand	Random suffix generation	Container names
once_cell	Lazy static + OnceLock	Backend singleton
tracing	Structured logging	Replaces Go's slog
which	Binary location	Backend detection
dashmap	Concurrent hash map	ComposeEngine registry (some branches)
console + dialoguer	Interactive installer UI	BackendInstaller

---

I have completed the implementation of the perry/container subsystem following the canonical specification. Key highlights:

1. Architecture: Standardized on the CliProtocol trait and CliBackend<P> generic executor in perry-container-compose, providing a robust abstraction for multi-runtime support (apple/container, docker, podman, lima, etc.).
2. Orchestration: ComposeEngine now correctly tracks session-specific containers, networks, and volumes. This ensures proper isolation between concurrent stacks and atomic rollback on startup failure.
3. Dependency Resolution: Kahn's algorithm is used for deterministic topological sorting and comprehensive cycle detection.
4. FFI & Compiler: All js_container_* and js_compose_* symbols are implemented and wired through HIR lowering and codegen dispatch. String headers and JSON serialization are used across the FFI boundary.
5. Security: Hardened capability sandbox implemented in capability.rs with Sigstore/cosign image verification integration.
6. Naming: Aligned with the canonical {md5_8chars}-{random_hex8} format using hyphen separators.

Verified the implementation with a comprehensive suite of unit and property tests. Both perry-container-compose and perry-stdlib compile successfully with the container feature enabled.