# Deployment

Deployment turns realized artifacts and an immutable release plan into placed,
authorized, observed resources. It owns desired and observed state,
reconciliation, rollout, infrastructure lifecycle, and runtime bindings.

## Apply one immutable plan

A release plan fixes artifacts, provider realizations, topology, resource
instances or resolvers, configuration and secret references, proposed grants,
rollout, routing, postconditions, and recovery.

Apply creates a durable operation, journals intent, validates fresh authority,
and performs fenced actions. Repeating `apply` resumes that operation. It does
not reinterpret current source or silently create a new plan.

## Reconcile desired and observed state

The reconciler compares an owner-validated desired record with authenticated,
sufficiently fresh observations. It chooses only transitions admitted by the
plan, records preconditions and results, then verifies semantic postconditions.

Provider acceptance is not convergence. A created object, successful API
response, Git commit, controller pickup, workload readiness, and business
postcondition are separate evidence phases.

## Choose the fitting control plane

The same deployment contract can use direct provider apply, a bounded embedded
reconciler, GitOps, an external durable-workflow controller, a persistent One
controller, or another admitted realization.

The selected provider proves only its supported slice. Exporting manifests can
honestly end at `ExternalApplyRequired`; One does not claim deployment without
attributable application and convergence evidence.

## Place stateless and stateful work honestly

Placement accounts for targets, regions, failure domains, trust, data
residency, latency, cost, capacity, affinity, isolation, and resource
continuity. Stateful scheduling additionally binds volumes, replication,
fencing, identity, migration, backup, restore, and repair.

Autoscaling operates within preplanned artifacts, provider envelopes, quotas,
grants, and data constraints. It cannot turn load into permission to discover a
new provider or region.

## Roll out through observed transitions

Rolling, canary, blue/green, shadow, partitioned, device-fleet, and regional
strategies are plans over exact cohorts and gates. Promotion depends on
declared observations and budgets. Pause, abort, rollback, and compensation are
new recorded transitions.

Configuration and secret rotation use the same staged model. Secret values are
resolved only at the selected runtime boundary and never become plan or
artifact content.

## Provisioning is part of the graph

Networks, identities, databases, queues, buckets, clusters, certificates,
DNS, and other infrastructure resources use typed owner contracts. Outputs
become bindings only after complete validation and authority activation.

Unknown create or delete outcomes are reconciled by provider identity and
observation. Name matching cannot justify adoption or destructive cleanup.

## Example

Illustrative commands apply and resume one immutable deployment operation:

```console
one apply plan:revision:sha256:…
one reconcile deployment:operation:sha256:…
one inspect deployment:operation:sha256:…
```

Follow [Ship and inspect a release](/one/examples/release).

Canonical owner:
[Deployment](https://github.com/muijf/one/blob/main/systems/deployment/AGENTS.md).