Skip to content

Add checkpointed execution and a resumable Renderflow provider seam for Flow #358

Description

@szmyty

Outcome

Make Renderflow interruption-safe and expose a stable provider contract that egohygiene/flow can plan, execute, assess, and resume without parsing console text or reaching into Renderflow internals.

Renderflow continues to own transform-domain execution. Flow owns cross-holon orchestration, execution state, recovery decisions, and suite-level provenance.

Flow alignment

Flow's roadmap explicitly requires stable provider seams, resumable work, explicit evidence, and a later Renderflow integration that passes an end-to-end resumability fixture. Its current artifact contract already defines content identity and producer/source relationships.

This issue implements the Renderflow-owned side of that boundary. It must not import Flow source or move orchestration logic into Renderflow.

Scope

Checkpoints

  • Persist node completion only after output artifacts are atomically written and validated.
  • Record the exact input artifacts, transform/config digest, implementation/tool version, outputs, and validation evidence required to decide whether a checkpoint remains compatible.
  • Make checkpoint writes atomic and corruption-detectable.
  • Support explicit cache/checkpoint invalidation.

Resume

  • Assess a saved run against current inputs, config, implementation versions, toolchain, and outputs.
  • Reuse only compatible completed work.
  • Distinguish retry, reuse, recompute, skip, and terminal incompatibility.
  • Never silently reuse missing or invalidated outputs.

Provider seam

Expose versioned structured operations equivalent to:

inspect capabilities
plan request -> plan + digest
run plan -> events + result
assess saved run -> recovery decision
resume saved run -> result

Support this through the public Rust SDK and/or a versioned JSON CLI contract suitable for Flow. Human console formatting is not a contract.

Events and cancellation

  • Provide stable machine-readable progress/state events.
  • Carry run ID, step ID, artifact IDs, state transitions, and diagnostics.
  • Honor bounded cancellation and return explicit cancelled state.

Acceptance criteria

  • An induced failure after at least one completed transform can be resumed without repeating compatible work.
  • Changing a source artifact invalidates every dependent checkpoint and only those dependent checkpoints.
  • Changing transform configuration or relevant tool/provider version invalidates affected work.
  • Missing/corrupt outputs are never treated as valid checkpoints.
  • The public result and event contracts are versioned and documented.
  • Flow can consume the contract without parsing human stdout/stderr.
  • A compatibility fixture projects produced artifacts into the supported Flow artifact contract.
  • Cancellation produces a resumable/terminal state intentionally rather than ambiguous partial success.
  • Repeated resume is idempotent under unchanged inputs and environment.
  • No source files are mutated by resume/recovery.
  • Contract and resumability fixtures run in CI.
  • Formatting, Clippy, tests, examples, and CI pass.

Dependencies

Depends on #354 and #355; plugin-provided work should use #357 contracts. Full cross-repository Flow E2E validation remains gated by Flow's own roadmap through FLO-Q04/FLO-Q05.

Metadata

Metadata

Assignees

Labels

No labels
No labels

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions