Environment

An Environment is a prepared execution filesystem and tool inventory. It owns immutable image selection, preparation and recovery using caller-supplied execution capabilities and policy.

Source and concrete API: environment.go.

Properties

Image and Platform: the requested base and execution platform.
LockPath, Key and Recipe: the preparation record and its semantic identity inputs.
Frozen: require the exact recorded prepared image.
Executor and Prepare: supplied image operations and preparation callback.
Log and Progress: optional observation sinks.

Behavior

Environment.Resolve reuses an applicable pin or prepares and records a successful snapshot. Image identity is immutable and platform-specific. Preparation occurs separately from application source; application source must not be copied into the prepared image.

Preparation may use package managers according to caller policy. Mutable repositories are not reproducible merely because the script and base image stayed unchanged: the actual resulting snapshot is pinned. Failure or cancellation must discard incomplete work and release temporary resources.

Environment.Ensure checks that the selected image remains available. Only an unavailable image permits recovery; transport and daemon failures propagate. Frozen mode requires the exact recorded identity, including after attempted recreation. It must not accept newly resolved software silently.

Boundary

A prepared image provides files and process defaults; it does not replace the kernel executing them. The caller is responsible for checking runtime requirements. Fully verified result reuse can defer image availability checks until execution is actually necessary.