feat(flow): persist versioned plans, checkpoints, and recovery decisions

.github/workflows/ci.yml

@@ -93,6 +93,9 @@ jobs:
       - name: Reject incomplete acceptance reports
         run: python3 tools/test_acceptance_report.py
 
+      - name: Check durable contract references and closed shapes
+        run: python3 tools/test_durable_contracts.py
+
       - name: Validate architecture specifications
         run: python3 .agents/specs/validate-specs.py
 
@@ -101,3 +104,29 @@ jobs:
 
       - name: Validate repository agents
         run: python3 .agents/agents/validate-agents.py
+
+  durable-portability:
+    name: Durable state ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 10
+    env:
+      RUSTUP_TOOLCHAIN: stable
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [macos-latest, windows-latest]
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Install stable Rust
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Cache Cargo data
+        uses: Swatinem/rust-cache@v2
+
+      - name: Verify atomic commit interruption boundaries
+        run: cargo test --lib state::store::tests --locked
+
+      - name: Verify portable state, process crashes, and workspace locking
+        run: cargo test --test durable_state --locked

Cargo.toml

@@ -15,6 +15,7 @@ test = false
 bench = false
 
 [dependencies]
+fs2 = "0.4.3"
 semver = "1.0.26"
 serde = { version = "1.0.219", features = ["derive"] }
 serde_json = "1.0.140"

README.md

@@ -27,7 +27,10 @@ subjects; require exact correlated process authority/isolation evidence; accept
 explicitly bound artifacts; and validate a closed scenario manifest for
 synthetic orchestration fixtures. It does not copy holon source or claim a
 product orchestrator, CLI, real provider adapter, operating-system sandbox,
-scenario runner, durable run state, or resume support.
+general scenario executor, automatic recovery scheduler, or public resume CLI.
+Prepared process execution now has [durable run state](docs/integrations/durable-state.md)
+with immutable plans, atomic snapshots, verified checkpoints, status inspection,
+and explicit recovery decisions.
 
 ## Executable checkpoint
 
@@ -58,6 +61,8 @@ binary is a synthetic conformance provider; it is not a public Flow CLI:
 - artifact bindings map immutable input and candidate-output IDs to portable
   root-relative locators; Flow observes file/directory bytes beneath one root
   and returns an accepted set only after exact host/provider correlation;
+- `RunStore` persists prepared intent and authority before launch, records accepted
+  checkpoints after validation, and reopens with typed stale/corrupt-state refusal;
 - `flow.scenario-manifest/v1` pins synthetic inputs, providers, topology,
   expectations, resource budgets, coverage gaps, and cross-language canonical
   digests without defining plans or runs; and
@@ -75,6 +80,7 @@ cargo run --example hermetic_extension --locked
 cargo run --example hermetic_process_transport --locked
 cargo run --example scenario_manifest --locked
 cargo test --test hermetic_provider_kit --locked
+cargo test --test durable_state --locked
 ```
 
 `EventSink` is a fallible, authoritative execution observer, not a best-effort

ROADMAP.md

@@ -30,18 +30,19 @@ supersedes: []
 > older active-checkpoint and queue text below where they conflict. Re-query
 > live issue, release, and CI state before starting a branch.
 
-PR #60 merged on 2026-09-24 as
-[`c653c3667dd1879bd7009f83a4906ab6ae9ba832`](https://github.com/egohygiene/flow/commit/c653c3667dd1879bd7009f83a4906ab6ae9ba832),
-completing the hermetic provider-kit closeout. The exact next Flow checkpoint is
-[#30](https://github.com/egohygiene/flow/issues/30).
-
-The #30 review candidate adds the
-[executable acceptance matrix](docs/integrations/acceptance-scenarios.md):
-versioned deterministic recipes, exact typed outcomes, two fresh-root receipts
-per case, PR budgets, and machine-readable coverage/gaps. Its scope ends at
-single-execution acceptance and refusal. After this candidate merges and the
-default-branch gate passes, #49 is next. FLO-Q03 remains active until the later
-real released-provider adapters satisfy its two-adapter exit criterion.
+#30 is complete: [PR #61](https://github.com/egohygiene/flow/pull/61) merged as
+`dfb16b347975e3292dc2928c8c48463f51dcf6d1`, with green
+[default-branch CI](https://github.com/egohygiene/flow/actions/runs/36209682152).
+Its [acceptance matrix](docs/integrations/acceptance-scenarios.md) proves 81
+scenarios twice on Rust 1.85 and stable.
+
+The #49 review candidate adds [durable prepared execution](docs/integrations/durable-state.md):
+versioned plans and state, atomic immutable snapshots, workspace locking,
+accepted checkpoints, fresh resume eligibility, and explicit recovery decisions.
+After this candidate merges and the default-branch gate passes, #31 is next.
+FLO-Q03 remains active until real released-provider adapters satisfy its
+remaining exit criteria. [#62](https://github.com/egohygiene/flow/issues/62) is
+later documentation visualization work and does not block this sequence.
 
 ### Central Flow chain
 

contracts/README.md

@@ -1,7 +1,7 @@
 # Flow contract set
 
 This directory contains Flow-owned suite interchange contracts. The initial
-contract set is version `0.6.0`, status `provisional`, in the v1 compatibility
+contract set is version `0.7.0`, status `provisional`, in the v1 compatibility
 family. Provisional means versioned and testable, not stable for production.
 
 | Contract | Purpose |
@@ -22,6 +22,14 @@ family. Provisional means versioned and testable, not stable for production.
 | `flow.extension-result/v1` | partial/final outcomes, failures, validation, provenance, and explanation |
 | `flow.extension-resolution/v1` | deterministic selection, rejection, conflict, and fallback evidence |
 | `flow.scenario-manifest/v1` | stable scenario identity, immutable fixture topology, typed expectations, execution budgets, and bounded coverage claims |
+| `flow.run-plan/v1` | immutable prepared execution intent and exact step context |
+| `flow.run-state/v1` | durable step state, decisions, checkpoints, and predecessor identity |
+| `flow.run-checkpoint/v1` | accepted artifacts and validation bound to plan, context, and attempt |
+| `flow.run-artifact/v1` | input/output role and retained host observation |
+| `flow.run-authority/v1` | launch grant or explicit operator denial |
+| `flow.run-validation/v1` | accepted evidence and validator implementation identities |
+| `flow.run-recovery/v1` | explicit retry/abandon decision and uncertainty acknowledgement |
+| `flow.run-snapshot/v1` | atomic-storage envelope with state integrity digest |
 
 `contract-set.v1.json` is the machine-readable index. Schemas live in
 `schemas/`; deterministic examples live in `examples/`; extension compatibility
@@ -79,6 +87,13 @@ The Rust and Python implementations independently reproduce the checked-in
 SHA-256 catalog. CI validates drift but never regenerates or rewrites canonical
 fixtures.
 
+The durable state contracts are described in
+[`docs/integrations/durable-state.md`](../docs/integrations/durable-state.md).
+Their schemas reuse repository-local schema references; the validator resolves
+these offline and never retrieves arbitrary URLs. The Rust state/store validators
+also enforce context, digest, and transition invariants. Examples under
+`fixtures/state/` are synthetic data, not current execution attestations.
+
 `compatibility.flow_version_requirement` is parsed with Rust's `semver`
 `VersionReq` grammar and must use comma-separated comparators. For example,
 `>=0.1.0, <0.2.0` is a bounded range; `>=0.1.0 <0.2.0` is invalid. Invalid or
@@ -100,7 +115,9 @@ package/executable observer, authority preflight, and bounded
 `trusted-unconfined` local runner are not real provider adapters. They do not
 prove publisher authenticity, signatures, transparency, domain-output
 validity, operating-system sandboxing, authenticated host evidence,
-descriptor-bound launch, descendant containment, checkpoints, or resume.
+descriptor-bound launch, or descendant containment. The durable coordinator adds
+Flow-owned checkpoints and resume eligibility; provider-native checkpoint restore,
+automatic recovery scheduling, and real-provider lifecycle proof remain later work.
 
 For this checkpoint, the caller owns configuration canonicalization and digest
 generation plus authorization issuance, authorization ID, and grants digest.

contracts/contract-set.v1.json

@@ -1,6 +1,6 @@
 {
   "schema_version": "flow.contract-set/v1",
-  "contract_set_version": "0.6.0",
+  "contract_set_version": "0.7.0",
   "status": "provisional",
   "contracts": [
     {
@@ -124,6 +124,73 @@
         "fixtures/scenarios/mutable-reference.v1.invalid.json",
         "fixtures/scenarios/unknown-version.v1.invalid.json"
       ]
+    },
+    {
+      "id": "flow.run-plan/v1",
+      "schema": "schemas/run-plan.v1.schema.json",
+      "example": "examples/run-plan.v1.example.json",
+      "invalid_examples": [
+        "fixtures/state/run-plan.v2.invalid.json"
+      ]
+    },
+    {
+      "id": "flow.run-artifact/v1",
+      "schema": "schemas/run-artifact.v1.schema.json",
+      "example": "examples/run-artifact.v1.example.json",
+      "invalid_examples": [
+        "fixtures/state/run-artifact.v2.invalid.json"
+      ]
+    },
+    {
+      "id": "flow.run-validation/v1",
+      "schema": "schemas/run-validation.v1.schema.json",
+      "example": "examples/run-validation.v1.example.json",
+      "invalid_examples": [
+        "fixtures/state/run-validation.v2.invalid.json"
+      ]
+    },
+    {
+      "id": "flow.run-checkpoint/v1",
+      "schema": "schemas/run-checkpoint.v1.schema.json",
+      "example": "examples/run-checkpoint.v1.example.json",
+      "invalid_examples": [
+        "fixtures/state/run-checkpoint.v2.invalid.json"
+      ]
+    },
+    {
+      "id": "flow.run-authority/v1",
+      "schema": "schemas/run-authority.v1.schema.json",
+      "example": "examples/run-authority.v1.example.json",
+      "invalid_examples": [
+        "fixtures/state/run-authority.v2.invalid.json"
+      ]
+    },
+    {
+      "id": "flow.run-recovery/v1",
+      "schema": "schemas/run-recovery.v1.schema.json",
+      "example": "examples/run-recovery.v1.example.json",
+      "invalid_examples": [
+        "fixtures/state/run-recovery.v2.invalid.json"
+      ]
+    },
+    {
+      "id": "flow.run-state/v1",
+      "schema": "schemas/run-state.v1.schema.json",
+      "example": "examples/run-state.v1.example.json",
+      "invalid_examples": [
+        "fixtures/state/run-state.v2.invalid.json"
+      ],
+      "fixtures": [
+        "fixtures/state/completed.v1.fixture.json"
+      ]
+    },
+    {
+      "id": "flow.run-snapshot/v1",
+      "schema": "schemas/run-snapshot.v1.schema.json",
+      "example": "examples/run-snapshot.v1.example.json",
+      "invalid_examples": [
+        "fixtures/state/run-snapshot.v2.invalid.json"
+      ]
     }
   ]
 }

contracts/examples/run-artifact.v1.example.json

@@ -0,0 +1,14 @@
+{
+  "schema_version": "flow.run-artifact/v1",
+  "role": "input",
+  "observation": {
+    "artifact_id": "artifact:synthetic-collection",
+    "port": "port:collection",
+    "media_type": "application/vnd.flow.collection-reference+json",
+    "kind": "file",
+    "locator": "inputs/source collection.json",
+    "digest": "2222222222222222222222222222222222222222222222222222222222222222",
+    "size_bytes": 128,
+    "manifest": []
+  }
+}

contracts/examples/run-authority.v1.example.json

@@ -0,0 +1,10 @@
+{
+  "schema_version": "flow.run-authority/v1",
+  "step_id": "step:inspect",
+  "attempt": 1,
+  "granted": true,
+  "authorization_id": "authorization:durable-example",
+  "profile_digest": "5555555555555555555555555555555555555555555555555555555555555555",
+  "enforcement_digest": "6666666666666666666666666666666666666666666666666666666666666666",
+  "grants_digest": "7777777777777777777777777777777777777777777777777777777777777777"
+}

contracts/examples/run-checkpoint.v1.example.json

@@ -0,0 +1,66 @@
+{
+  "schema_version": "flow.run-checkpoint/v1",
+  "checkpoint_id": "checkpoint:example",
+  "plan_digest": "0e91d3a2af624fd222d6cf2aa1b005b8d9b3ad2f3e9951cde35b2e9e99b102d1",
+  "context_digest": "216e6c91a49e420820ba87e6add8824c06cc279bf413f67529f276afde1f2049",
+  "attempt": 1,
+  "artifacts": [
+    {
+      "schema_version": "flow.run-artifact/v1",
+      "role": "input",
+      "observation": {
+        "artifact_id": "artifact:synthetic-collection",
+        "port": "port:collection",
+        "media_type": "application/vnd.flow.collection-reference+json",
+        "kind": "file",
+        "locator": "inputs/source collection.json",
+        "digest": "2222222222222222222222222222222222222222222222222222222222222222",
+        "size_bytes": 128,
+        "manifest": []
+      }
+    },
+    {
+      "schema_version": "flow.run-artifact/v1",
+      "role": "output",
+      "observation": {
+        "artifact_id": "artifact:synthetic-collection-evidence",
+        "port": "port:evidence",
+        "media_type": "application/vnd.optiflow.collection-evidence+json",
+        "kind": "directory",
+        "locator": "outputs/evidence bundle",
+        "digest": "51495603e74938fc7b5f86c3ae1d01ba4f9aaccf29dfe8ad26ea49bbd1ca864a",
+        "size_bytes": 384,
+        "manifest": [
+          {
+            "locator": "summary.json",
+            "kind": "file",
+            "digest": "5555555555555555555555555555555555555555555555555555555555555555",
+            "size_bytes": 256
+          },
+          {
+            "locator": "évidence",
+            "kind": "directory",
+            "digest": "1e1b8003aaea7b8f60b4481e20c3ad61e627d84d54d2d459109d41b3b01799c2",
+            "size_bytes": 128
+          },
+          {
+            "locator": "évidence/details.json",
+            "kind": "file",
+            "digest": "6666666666666666666666666666666666666666666666666666666666666666",
+            "size_bytes": 128
+          }
+        ]
+      }
+    }
+  ],
+  "validation": {
+    "schema_version": "flow.run-validation/v1",
+    "profile": "flow.accept-artifacts/v1",
+    "implementation_version": "0.1.0",
+    "implementation_digest": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+    "platform": "linux",
+    "invocation_digest": "1111111111111111111111111111111111111111111111111111111111111111",
+    "execution_digest": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
+    "artifacts_digest": "b054d38b4f2ca943473fab2217e6386c642b3e4bce46e3b43ef07bcfabae6022"
+  }
+}