Skip to content

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

Merged
szmyty merged 2 commits into
mainfrom
feat/flow-49-durable-state
Sep 26, 2026
Merged

szmyty merged 2 commits into
mainfrom
feat/flow-49-durable-state

Conversation

@szmyty

@szmyty szmyty commented Sep 26, 2026 •

Copy link
Copy Markdown
Contributor

Flow previously kept execution history in memory, so a host restart lost the distinction between prepared, interrupted, and accepted work. This adds a durable coordinator for prepared process steps and the state foundation required by #31.

  • Add eight closed flow.run-*/v1 contracts for plans, state, checkpoints, artifacts, authority, validation, recovery, and snapshots; advance the provisional contract set to 0.7.0.
  • Persist intent and authority before launch, then persist success only after the existing transcript and artifact acceptance gates pass. Keep the in-memory seams available.
  • Commit immutable, digest-linked snapshots under an OS-backed workspace lock. Reopen validates the complete retained history and refuses partial writes, corruption, unsupported schemas, and concurrent opens.
  • Bind eligibility to the complete plan, input bytes, provider/version, capability, actual configuration, authority, validator identity, and freshly observed artifacts. Recovery requires a recorded, explicit choice; completed steps cannot be launched again.
  • Document privacy, retention, migration, rollback, and filesystem guarantees in the canonical architecture, integration guide, and proposed ADR-0011.

Validation (current review head 948eb4dfeb17e701bae61978bd6d593d28ee85e8):

  • Rust 1.85.0 and stable: strict Clippy and all-target tests passed, including all 81 acceptance scenarios twice in fresh roots.
  • Commit interruption, abrupt exit/reopen, workspace contention, cancellation/timeout, stale evidence, failed terminal commits, explicit retry/abandon, record budgets, and privacy tests passed.
  • All 24 contracts, 34 positive fixtures, 21 negative fixtures, Python regression tests, deterministic sources, and repository validators passed.
  • Documentation tests, three executable examples, and package verification passed locally (--allow-dirty before publishing the identical tree).
  • Hosted CI run 36211631846 passed at head 948eb4dfeb17e701bae61978bd6d593d28ee85e8: Rust 1.85.0, Rust stable, repository validators, macOS durable state, and Windows durable state. Both Linux jobs also passed documentation, examples, and clean package verification.
  • The first Windows run exposed a test helper reading the exclusively locked coordination file; it now checks that empty file's metadata. The portable suite and strict Clippy passed again locally. Platform jobs select stable Rust explicitly; production behavior is unchanged.

Limits: this is a trusted local, single-writer store. Windows guarantees process-crash consistency, not power-loss durability. Digests are correlation evidence, not authentication. V1 never repairs/prunes state or repeats uncertain effects automatically. General scheduling, downstream invalidation, real adapters, and the public CLI remain later checkpoints. ADR-0011 is proposed for maintainer review.

Rollback: revert this implementation while preserving run workspaces and artifacts. Older state or code never authorizes repeated provider effects; resolve uncertain work before restoring a prior workspace.

Closes #49. Parent #3; suite roadmap #11. After merge and green default-branch CI, #31 is next.

Record versioned intent, authority, accepted checkpoints, and explicit recovery
choices in locked immutable local snapshots. Refuse stale evidence and unsafe
reopen; prove interruption boundaries and portable locking in CI.

Closes #49
Roadmap-Step: FLO-Q03
Inspect the empty coordination file through metadata instead of reading it
through a second handle while Windows holds a byte-range lock. Select stable
explicitly for the macOS and Windows portability jobs.

Roadmap-Step: FLO-Q03
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[FLO-3.3] Persist versioned plans, runs, checkpoints, and recovery decisions

1 participant