One turns accepted meaning into production through three separate stages. Planning decides. Build materializes. Apply mutates and reconciles. No stage is allowed to impersonate the next.
Plan one exact root
one planPlanning computes the root's requirements to a fixed point, then selects an exact logical composition and physical provider envelope. The immutable result includes:
- normalized semantic and implementation revisions;
- selected mappings and stage contributions;
- implementation candidates and analysis receipts;
- provider profiles and complete transitive support closure;
- topology, conversions, protocols, resource bounds, and placement;
- authority, isolation, compliance, observation, and recovery requirements;
- fixed, marginal, expected, and worst-case cost;
- canonical choices, rejected alternatives, and inclusion proofs;
- exact Build requirements and a selection lock.
Planning is deterministic for the same locked inputs. A user preference is a typed constraint. It cannot override a hard semantic, security, compatibility, or safety invariant.
Build the locked selection
one buildBuild consumes the selection without reselecting. It constructs an exact action graph over source closures, generated contract projections, toolchains, provider materializations, packaging, signing, and verification.
Every action has content-derived identity and declared inputs, outputs, environment, network policy, secrets, tools, and hermeticity grade. The Build result retains:
- artifacts and their complete closure;
- an SBOM and dependency identities;
- toolchain and target evidence;
- source and action provenance;
- signatures and verification results;
- generated-projection manifests and receipts;
- complete realization receipts for the selected providers;
- a canonical realized Build report.
Artifact bytes are not Build evidence by themselves. A generated projection is a disposable cache; its source contract and receipt remain authoritative. Neither a package digest nor a selection-lock reference substitutes for a provider's complete realization receipt.
Create a release plan
one observe production
one release production build:sha256:<build-digest>Pass the exact build:sha256:... reference returned by one build.
release consumes exact realized artifacts, provider realization receipts, and
current owner-qualified observations. It fixes placement, resource instances,
configuration and secret references, network policy, grants, rollout, health,
routing, postconditions, reconciliation, and recovery within the locked
physical envelope.
The plan retains the selected control-plane realization appropriate to the work: direct provider apply, GitOps, bounded embedded reconciliation, a persistent One controller, or an external durable-workflow controller. Changing that selection requires a new physical plan and its applicable Build evidence. That provider remains responsible only for the semantics it proves.
Planning never changes the target. release stops before apply. Persisting,
signing, publishing, or approving a plan are explicit governed actions, and
approval does not itself apply anything.
Apply or resume the immutable plan
one approve plan:<PlanId>
one apply plan:<PlanId>
one reconcile operation:<OperationId>Apply turns the reviewed plan into fenced, journaled reconciliation actions. Every action has preconditions, authority, idempotency class, observation requirements, postconditions, and a durable receipt.
The reconciler compares desired and observed state, performs only admitted transitions, and records causal facts. A crash can resume the same operation through its exact operation identity. An external timeout creates an unknown outcome that must be queried or reconciled before repetition.
Rollout, migration, rollback, compensation, and failover are forward transitions with their own plans and evidence. One never rewinds an external world by deleting history.
Follow Ship and inspect a release for a complete command-and-evidence walkthrough.
Canonical owners: Planning, Build, and Deployment.