# Change and evolution

One treats change as a new, fully explained system state—not as an exception to
the model. The same lifecycle applies when changing a field, implementation,
provider, topology, policy, data layout, workflow, or whole release.

## Start from semantic impact

A source transaction produces new exact source revisions. Checking derives
the changed normalized owner values and compares their public meaning. Impact
analysis follows typed references and inclusion proofs to affected roots,
schemas, clients, implementations, providers, artifacts, grants, data,
deployments, and operations.

Repository paths and Git diffs are useful editing clues; they are not semantic
impact evidence. A file can change without changing normalized meaning, and a
small contract change can affect many roots.

## Compatibility is directional

Compatibility is evaluated for a producer, consumer, operation, data set, and
transition direction. Read compatibility, write compatibility, wire
negotiation, stored-data compatibility, workflow replay, and operational
coexistence are separate questions.

A mapping states every preserved, transformed, defaulted, rejected, or lost
value. If two versions must coexist, the plan names the window, participants,
conversion path, rollback limits, and removal condition. Coexistence is not a
permanent second architecture.

## Replan only what changed

Planning incrementally recomputes affected root closures against exact prior
records, but accepts a cached result only after proving its owner inputs are
unchanged. New provider evidence, policy, prices, vulnerabilities, target
facts, or revocations can require a different plan even when source meaning is
unchanged.

The resulting diff explains semantic, implementation, topology, authority,
artifact, resource, cost, rollout, and evidence changes separately. A reviewer
can approve the consequential slice rather than an opaque generated file.

## Run transitions, not replacements

A release change may include data expansion, backfill, shadow traffic,
dual-read, dual-write, canary, progressive delivery, traffic shift, workflow
versioning, credential rotation, and cleanup. Each is an ordered action with
preconditions, a fence, authority, observations, and postconditions.

The old path is removed when no current root, in-flight workflow, retained data,
rollback window, or recovery contract still requires it. One does not keep
aliases, old readers, or parallel plans merely because they make repository
churn easier.

## Revocation can initiate change

A compromised tool, provider, artifact, credential, mapping, or evidence claim
produces a scoped revocation or defect fact. Impact analysis finds the exact
locks, builds, releases, bindings, grants, data, and effect windows that relied
on the invalid premise.

Quarantine, revalidation, rebuild, replan, repair, notification, compensation,
and rotation are new governed actions. Original history remains intact and
records what was known at the time.

## Decommission forward

Removing a source label, deployment manifest, or provider resource is not a
decommission. Retirement is a governed forward lifecycle that preserves the
data, authority, recovery, and History obligations which outlive serving.

```console
one decommission --root OrdersProduction
one inspect plan:<revision> --subject decommission
one approve plan:<revision> --decision approval.json
one apply plan:<revision>
one inspect operation:<revision>
```

The plan announces the retirement, freezes new work, drains and quiesces
in-flight work, releases resources in dependency order, disposes or transfers
data according to policy, revokes credentials and grants, retains required
facts, verifies inactivity, and finally tombstones the root. Irreversible data
destruction and external effects remain separately visible and authorized.

If an outcome becomes unknown, reconcile the existing operation before taking
another action. A tombstone prevents accidental name reuse from being mistaken
for continuity while retained History still explains the former system.

## Example

Illustrative end-product commands inspect impact before applying a transition:

```console
one check --impact
one plan --root OrdersRelease
one inspect plan:sha256:… --subject migration
```

Follow [Evolve a contract and migrate data](/one/examples/change-migration).

Canonical owners:
[Knowledge](https://github.com/muijf/one/blob/main/systems/knowledge/AGENTS.md),
[Planning](https://github.com/muijf/one/blob/main/systems/planning/AGENTS.md),
and [History](https://github.com/muijf/one/blob/main/systems/history/AGENTS.md).