v0.4.1: add integrity envelopes, typed approvals, runtime preconditions and executable-plan artifacts

[aidankhogg]

Motivation

• Provide end-to-end integrity for admission decisions and reconciliation plans so loaded artefacts can be cryptographically referenced and fail closed on tampering.
• Introduce typed approval evidence, a canonicalisation profile and stable revision record IDs to make activation into a durable control-plane explicit and safe.
• Enforce runtime preconditions and capability constraints at compilation and execution time to avoid engines inferring sovereign facts or silently accepting unsafe provider semantics.

Description

• Bump package version to 0.4.1 and add release notes and documentation (CHANGELOG.md, README.md, docs/artefact-chain-v0.4.1.md, SECURITY.md).
• Add canonicalisation constants and digest configuration in canonical.py and use CANONICALIZATION_PROFILE/sha256 across artefacts.
• Extend admission and plan models with envelope fields and integrity helpers: AdmissionDecision now computes decision_digest/decision_id and exposes integrity_payload/verify_integrity, and ReconciliationPlan exposes plan_digest with integrity_payload/verify_integrity; add verify_admission_integrity and verify_plan_integrity in planning.py.
• Add typed approval schema and model properties (ApprovalEvidence) including subject_digest, gate_id, approver, expires_at, verification_status, and verification helper logic to enforce verified, unexpired approvals.
• Introduce a typed control-plane adapter desired_revision_from_admission in controlplane/models.py that validates the admission envelope before constructing DesiredRevision records and introduced LegacyAdmissionRecord read-adapter.
• Strengthen planning and compilation pipeline: admit_change now binds and validates approvals, computes decision envelope; build_plan enforces admission integrity and emits integrity-bound plan envelopes; compile_plan validates plan integrity, resolves capability declarations, enforces idempotency/compensation constraints and emits executable fingerprints.
• Add runtime-side immutable RuntimeFacts and offline_demo_facts to explicitly inject sovereign facts into the executor; runtime executor now requires facts, evaluates preconditions (_failed_precondition) and records precondition failures as evidence; enforce provider dry-run/idempotency/compensation semantics before invoking providers.
• Extend fake provider and provider contracts to expose richer capability declarations, preserve prior_value for compensation, and support a broader capability set used by compilation.
• Add and update JSON schemas for new/changed artefacts: approval-v0.4.1.schema.json, desired-revision-v0.4.1.schema.json, executable-plan-v0.4.1.schema.json, and numerous updates to existing admission, plan, observed schemas.
• Add tests and adjust existing tests to cover integrity, precondition enforcement and compilation/execution semantics (new tests/test_chain_integrity.py, updates to tests/test_planning.py and tests/test_runtime.py).

Testing

• Ran the automated test suite with pytest -q; the full test suite including tests/test_chain_integrity.py, tests/test_planning.py, and tests/test_runtime.py executed and passed.
• Unit tests exercise admission and plan integrity verification, desired_revision_from_admission activation guards, compile-time capability checks, and runtime precondition failures and compensation behavior; all assertions succeeded.
• CLI demo execution paths that use offline_demo_facts were exercised by tests covering dry-run, retry, observation, resume and compensation semantics and reported as passing.

---

Codex Task

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: fe06c492a1

ℹ️ 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".

[chatgpt-codex-connector]

Check expiration against the actual evaluation time

When callers omit evaluated_at, this substitutes the latest approval's own approved_at timestamp rather than the time admission is being evaluated. Consequently, evidence approved on January 1 and expired on January 2 remains valid when the same proposal is admitted months later, because valid_for evaluates it at January 1. Use a trusted current/evaluation time, or require evaluated_at, so expired approval evidence cannot admit governed changes.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Match approval evidence by gate ID

For normal evidence where approval_id is a unique evidence identifier and gate_id names the gate being approved, this passes approval_id as the expected gate and later compares approval IDs with the outstanding gate strings. Such valid evidence can never clear its gate unless clients duplicate the gate string into both fields, defeating the newly distinct typed identifiers. Validate each item against its gate_id and collect the matching gate IDs instead.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Include the admission binding in the executable fingerprint

The newly added admission_decision_digest is forwarded to providers as provenance, but it is assigned only after the fingerprint core has been computed. A loaded executable plan can therefore have this field changed without changing fingerprint, and the executor's integrity check still passes before sending the forged decision digest in ProviderContext. Bind this field into the fingerprint payload so executable provenance cannot be altered independently.

Useful? React with 👍 / 👎.