# Plan, build, and apply

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

```console
one plan
```

Planning 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

```console
one build
```

Build 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

```console
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

```console
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](/one/examples/release) for a complete
command-and-evidence walkthrough.

Canonical owners:
[Planning](https://github.com/muijf/one/blob/main/systems/planning/AGENTS.md),
[Build](https://github.com/muijf/one/blob/main/systems/build/AGENTS.md), and
[Deployment](https://github.com/muijf/one/blob/main/systems/deployment/AGENTS.md).