feat: v0.2 sovereign change planning

CHANGELOG.md

@@ -1,3 +1,8 @@
 # Changelog
+## 0.2.0 - 2026-08-02
+- Added canonical world and manifest digests, revision lineage, semantic change sets, offline observed-state evidence, mandate-aware admission, explicit risks and approvals, and deterministic provider-neutral reconciliation plans.
+- Added `diff`, `admit`, and `plan` commands. Planning is deliberately non-executable and keeps canonical intent, capabilities, provider bindings, and observed drift separate.
+- Added explicit admission/approval states, typed mandate constraints and observation outcomes, lineage validation, separate intent/materialization digests, lifecycle policy, typed plan predicates, semantic dependency graphs, and published planning artifact schemas.
+
 ## 0.1.0 - 2026-08-01
 - Added the v0alpha2 provider-neutral world model, semantic diagnostics, defaults, manifest, graph, resolver derivation, CLI, examples, schema, and documentation.

README.md

@@ -1,6 +1,6 @@
 # NetSovereign
 
-> **Experimental / pre-alpha:** v0.1 models intent only. It provides no operational infrastructure or security guarantees.
+> **Experimental / pre-alpha:** v0.2 models intent and plans change only. It provides no operational infrastructure or security guarantees.
 
 NetSovereign defines sovereign digital worlds. **NetEngine** is the future compiler and reconciliation runtime that may materialise declared authorities through replaceable providers. Sovereignty means that recognised institutions can govern a world's naming, numbering, registry, trust, identity, transit, mail, and catalogue authority without making any particular service canonical.
 
@@ -12,6 +12,12 @@ Requires Python 3.12+. `uv sync --all-extras`, or install the wheel with pip. Co
 netsovereign validate examples/minimal/world.yaml
 netsovereign manifest examples/minimal/world.yaml
 netsovereign explain examples/minimal/world.yaml
+netsovereign diff current.yaml proposed.yaml
+netsovereign admit current.yaml proposed.yaml --observed observed.json
+netsovereign plan current.yaml proposed.yaml --observed observed.json
 ```
 
-See [the domain guide](docs/domain-model.md), [v0alpha2 schema guide](docs/schema-v0alpha2.md), and [roadmap](docs/roadmap.md). The broader example is illustrative: assurance claims and provider-shaped seams are declarations, not implemented guarantees.
+The change commands compare meaning, evaluate declared mandates, classify approval risks and offline
+drift, and describe convergence without executing providers or touching infrastructure.
+
+See [the domain guide](docs/domain-model.md), [v0.2 change-planning guide](docs/change-planning-v0.2.md), [v0alpha2 schema guide](docs/schema-v0alpha2.md), and [roadmap](docs/roadmap.md). The broader example is illustrative: assurance claims and provider-shaped seams are declarations, not implemented guarantees.

docs/change-planning-v0.2.md

@@ -0,0 +1,61 @@
+# Sovereign change planning v0.2
+
+v0.2 is an offline decision surface. It compares declarations, evaluates the authority already
+accepted by the current world, classifies evidence, and emits a provider-neutral plan. It never
+loads providers, contacts a network, invokes a subprocess, or mutates infrastructure.
+
+## Artifact identities
+
+Every revision exposes separate SHA-256 identities:
+
+- **declaration digest** covers the normalized complete declaration;
+- **canonical-intent digest** excludes revision metadata and replaceable provider bindings;
+- **materialization digest** covers capabilities and provider bindings;
+- **manifest digest** exists only for a semantically valid manifest.
+
+A proposal may provide its expected parent revision and declaration digest. A mismatch is rejected
+as stale lineage. Change and drift identifiers use full content digests, so approvals bind to the
+exact reviewed before/after values.
+
+## Admission states and time
+
+Admission has three outcomes: `rejected`, `pending_approval`, and `admitted`. An approval-gated
+proposal is not admitted until matching approval evidence is supplied. `evaluated_at` is an explicit
+input used for mandate validity; observation timestamps describe evidence and never select the
+admission time.
+
+Mandates are matched against authority, governed action, resource classes, jurisdiction, validity,
+and typed constraints (`operations`, `paths`, and `subject_ids`). Current accepted state is validated
+before it can authorise a proposal.
+
+## Observations and plans
+
+Facts use stable semantic paths such as `resources/root-zone`, and distinguish `present`, `absent`,
+`unknown`, and `unreadable`. Unknown or unreadable evidence does not manufacture drift. Actionable
+drift carries its authority and mandate into a convergence step.
+
+Plan preconditions and expected outcomes are typed JSON objects rather than prose. Dependencies form
+a deterministic semantic DAG: for example, a changed provider binding depends on its changed
+capability, while unrelated changes remain independent. Reversibility is explicitly classified and
+remains `unknown` unless v0.2 can justify a stronger provider-neutral statement.
+
+Schemas are published at:
+
+- `schemas/observed-v0.2.schema.json`;
+- `schemas/admission-v0.2.schema.json`;
+- `schemas/plan-v0.2.schema.json`.
+
+## CLI contract
+
+```console
+netsovereign diff current.yaml proposed.yaml
+netsovereign admit current.yaml proposed.yaml \
+  --evaluated-at 2026-08-02T12:00:00Z \
+  --parent-revision 7 --parent-digest sha256:... \
+  --observed observed.json --approval approval.yaml
+netsovereign plan current.yaml proposed.yaml --format yaml --output plan.yaml
+```
+
+`admit` and `plan` exit with `0` when admitted, `1` when rejected, `2` for malformed input or CLI
+usage, and `3` while approval is pending. `--format json|yaml`, `--compact`, and `--output` control
+serialization without changing artifact identity.

docs/roadmap.md

@@ -1,4 +1,40 @@
-# Alpha roadmap
-- **v0.1 (implemented):** offline sovereign domain declaration, validation, manifest, graph, explanation.
-- **Proposed later:** admission against observed state, durable operations, compilation and reconciliation.
-- **Deferred:** containers, DNS/PKI/database/identity/gateway implementations, firewall/routing/NAT/BGP, SMTP, object storage, Kubernetes, WireGuard, public ingress, HA, DNSSEC rotation, OIDC federation, CA cross-signing, management API/UI, and provider execution.
+# NetSovereign roadmap
+
+NetSovereign develops authority and intent before operational adapters. Versions v0.2 through v0.4
+are a single dependency chain: real DNS, PKI, identity, or gateway providers must not begin until
+change planning, the runtime core, and durable local control have established their boundaries.
+
+| Version | Development outcome | Major boundary |
+| --- | --- | --- |
+| **v0.1 — Sovereign Domain Foundation** | Offline declarations, validation, manifests, authority graphs, and explanations. | No planning or infrastructure mutation. |
+| **v0.2 — Sovereign Change Planning** | Compare current, proposed, and observed worlds; admit or reject changes; generate deterministic reconciliation plans. | No provider execution or infrastructure mutation. |
+| **v0.3 — NetEngine Runtime Core** | Provider contracts, compilation pipeline, execution state machine, dry-run/mock provider, evidence, and rollback semantics. | Only simulated or non-operational providers. |
+| **v0.4 — Durable Local Control Plane** | Persistent accepted state, journals, checkpoints, locks, recovery, drift detection, and repeated reconciliation. | Local single-node operation; no HA. |
+| **v0.5 — Authoritative Naming Slice** | Registry/registrar to naming capability to generated authoritative DNS configuration. | Isolated local development environment only. |
+| **v0.6 — Trust Authority** | Certificate policy, issuance lifecycle, revocation, and a replaceable step-ca-style provider. | No cross-world CA trust. |
+| **v0.7 — Identity Authorities** | Separate platform and in-world identity; subjects, claims, credentials, and OIDC provider materialisation. | Federation remains explicitly opt-in. |
+| **v0.8 — Registry and Numbering** | Organisation, name, and number allocation; registration, grant, delegation, and revocation workflows. | No real BGP or public-number claims. |
+| **v0.9 — Boundary and Transit** | Materialise isolated, shadowed, mirrored, and exposed postures through resolver, routing, and policy providers. | Destructive or public exposure requires approval gates. |
+| **v0.10 — Peering and Federation** | Cross-world discovery, signed exchange artefacts, and selective authority import/export. | Peering never implies trust. |
+| **v0.11 — Mail and Service Catalogue** | Activate deferred authority families and their protocol surfaces. | Optional capabilities, not minimal-world requirements. |
+| **v0.12 — Operational Product Surface** | Management API, CLI operations, audit views, lifecycle workflows, backup/restore, and multi-world administration. | Pre-1.0 until security and upgrade guarantees mature. |
+| **v1.0 — Sovereign Runtime** | Stable schemas, migrations, conformance suite, hardened providers, upgrade guarantees, recovery, and documented security model. | Production compatibility commitment begins. |
+
+## v0.2 acceptance boundary
+
+Given an accepted world, a proposed declaration, and optional offline observations, v0.2 returns a
+deterministic account of what changed, whether declared authority admits it, the applicable mandate,
+risk and approval gates, existing drift, and provider-neutral convergence steps. Observations are
+evidence rather than authority, admission does not authenticate a proposer, and plans cannot execute.
+
+The planner distinguishes canonical intent, capabilities, replaceable provider bindings, and observed
+drift. Stable world, authority, and resource identities cannot silently change meaning; retirement is
+preferred to deletion; imported authority cannot silently become local; peering cannot gain trust by
+ordinary update; imports and exports must remain explicit; and reductions in autonomy or new required
+external dependencies are visible approval risks.
+
+## Explicitly deferred from v0.2
+
+Provider SDKs and concrete provider packages; subprocess, container, or network execution; CoreDNS,
+step-ca, Keycloak, nftables, and PostgreSQL; durable databases and daemons; secrets; actual rollback;
+provider discovery; live observation; and management APIs or user interfaces.

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "netsovereign"
-version = "0.1.0"
+version = "0.2.0"
 description = "Provider-neutral domain foundation for sovereign digital worlds"
 readme = "README.md"
 requires-python = ">=3.12"