feat: complete NetEngine v0.3 runtime core

[aidankhogg]

Motivation

• Deliver a provider-neutral runtime core that compiles admitted v0.2 reconciliation plans into provider-bound executable operations and executes them only against non‑operational, in‑memory providers so execution, evidence, retry, compensation, dry‑run, and resume semantics can be exercised without infrastructure mutation.
• Introduce stable provider contracts, deterministic provider resolution, and an explicit execution state model so apply/observation/convergence are distinct and explainable.
• Preserve v0.2 plan provenance and avoid mutating the original plan during compilation, using a generic resource.manage@1.0 capability when the source plan omits explicit capability wiring.
• Keep durability, persistent journals, operational providers, and cross-process recovery out of scope for v0.3 (deferred to v0.4/v0.5).

Description

• Add typed provider contracts and descriptors under src/netsovereign/providers to model CapabilityRequirement, ProviderDescriptor, ProviderContext, ValidationResult, ProviderResult, ObservationResult, and a provider Protocol. (see providers/contracts.py).
• Implement a deterministic, injected ProviderRegistry that rejects duplicates, enforces capability version compatibility, resolves explicit bindings or a single default provider, and produces stable resolution errors (see providers/registry.py).
• Provide an inspectable fake provider suitable for tests and demos that supports validation, idempotent apply, observation, deterministic resource ids, evidence emission, failure injection, compensation, and dry‑run declaration (see providers/fake.py).
• Add a pure compilation stage and in‑memory runtime in src/netsovereign/runtime.py that: topologically orders plan steps, resolves providers, emits an ExecutablePlan with stable ids/fingerprint, implements an explicit OperationState state machine, records attempts/transitions/evidence/observations, supports retry policy and failure postures, performs reverse‑order compensation, and supports interruption‑safe resume against the in‑memory repository.
• Extend the CLI with netsovereign execute <plan.json> [--dry-run] to compile an admitted plan against the fake registry and run or simulate it (see src/netsovereign/cli.py).
• Add focused runtime tests (tests/test_runtime.py) that exercise provider resolution errors, compilation determinism and non‑mutation, state transitions, execution success, dry‑run semantics, retry behavior, observation mismatch handling, compensation, idempotent resume, and interruption recovery.
• Ship documentation and an ADR describing the compile/execute decision and v0.3 boundaries (docs/runtime-core-v0.3.md, docs/adr/0003-compile-admitted-plans-into-provider-bound-operations.md) and bump package metadata to 0.3.0.

Testing

• Unit tests: ran uv run pytest tests/test_runtime.py and the focused runtime tests passed (8 passed), and the full test suite passed (uv run pytest → 56 passed).
• Static analysis and formatting: uv run ruff format --check / uv run ruff check and uv run mypy completed with no issues.
• Packaging: uv build produced a source distribution and wheel for netsovereign-0.3.0.
• CLI smoke: a demonstration sequence using netsovereign plan to produce an admitted plan and netsovereign execute --dry-run produced a structured dry‑run report with evidence and observed no provider mutation.
• Notes: tests and checks above were executed locally in the development environment used for this change; durability and cross‑process resume semantics are intentionally limited to the in‑memory repository as documented and remain deferred to the next milestone.

---

Codex Task

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: f71bf5a1f6

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".