CheckedFlow

Generate a procedure, check it independently, and reuse it with its evidence intact.

CheckedFlow is a Python runtime that records who may do work, what it costs, what was checked, and whether the result is still reusable under a declared contract. It coordinates four administrative organizations through signed commands and a small deterministic state machine. CometBFT orders the commands; workers execute code separately in Linux gVisor sandboxes. Optional A2A and MCP adapters let agent services and agent applications submit the same signed commands and inspect the same committed evidence through standard protocol SDKs.

For example, one worker generates a function that doubles each integer in an array. Independent workers check its actual Python output. After three organizations attest to matching results, the function can become a dependency of a second generated function that also adds one. If the first function expires or is revoked, dependent functions lose their reusable status too.

Version 0.1.0 is an experimental reference implementation. Its complete demonstration uses 31 finite inputs and actual generated Python. See the audit against the original plan and executed validation record for the current scope.

The concepts in one minute

flowchart LR
  M[Approve mission and budget] --> T[Create task]
  T --> L[Commit lease and start]
  L --> G[Generate source]
  G --> C[Propose candidate]
  C --> V[Independent sandbox checks]
  V --> R[Register checked capability]
  R --> T
  V --> U[Retain failure or uncertainty]

There are three different decisions: a signature establishes authority, CometBFT establishes committed order, and verifier attestations establish acceptance under a contract. None substitutes for the others. Concepts and guarantees explains these distinctions.

Try it without running a cluster

Install the SDK and CLI with Python 3.12–3.14:

python -m pip install checkedflow
checkedflow example
python -m checkedflow.data.examples.sdk

For source development with uv, from this directory:

uv sync --frozen --all-extras --group dev
uv run checkedflow example
uv run python -m checkedflow.data.examples.sdk

The first example emits JSON containing Python source and verification: "not_executed". It searches a bounded grammar; it does not execute or approve that source. The SDK example creates ephemeral test keys, obtains three signatures for a worker registration, and applies it to two local runtimes. It prints registered_worker, height: 1, replay_matches: true, and a state hash. Keys are regenerated each run, so that hash varies.

These commands work on Windows and Linux. The step-by-step tutorial explains the output and links to the complete, runnable SDK code. Local replay demonstrates state-machine behavior; it does not establish distributed finality.

To install the locally built package:

uv build
python -m pip install dist/checkedflow-0.1.0-py3-none-any.whl
checkedflow --help

Install checkedflow[distributed] for the ABCI service, RPC client and worker, or checkedflow[agents,distributed] for the agent gateways as well. CometBFT and gVisor are separately provisioned external processes.

Run generation, verification and reuse together

Prepare CometBFT v0.40.0, Docker configured with runsc, and a locally available Python image on Linux, following operation and recovery. Use the inspected image digest:

export CHECKEDFLOW_IMAGE='python@sha256:REPLACE_WITH_YOUR_INSPECTED_DIGEST'
uv run checkedflow demo --directory ./lab-run \
  --image "$CHECKEDFLOW_IMAGE" --cometbft /absolute/path/to/cometbft

The directory must not already exist. The command creates four node stores and laboratory keys, performs three generation rounds with reuse and three from scratch, and stops its processes. It leaves logs, committed source and evidence, and acceptance.json in that directory. The runner uses the fixed local image and refuses execution if gVisor is unavailable.

The domain is arrays of length 0–2 whose elements are integers from −2 through 2. Passing covers those 31 inputs. Both comparison conditions use the same grammar, targets, search ceiling, verification policy and total budget. Work units are declared ceilings, not measured CPU time. See accounting and lifecycle for the exact definitions.

Use or extend the runtime

Connect agents through A2A or MCP

Use A2A when one agent service needs to communicate with another. Use MCP when an agent application needs discoverable tools and resources. Both reach a mission gateway: an adapter bound to one chain and mission, backed by the operator's own validating full node.

For a source checkout, uv sync --frozen --all-extras --group dev includes both adapters. For a local wheel, install ./dist/checkedflow-0.1.0-py3-none-any.whl[agents,distributed] with pip. After configuring a node and mission, an MCP host can launch:

checkedflow mcp --rpc http://127.0.0.1:26657 --chain my-chain --mission array-mission

For A2A, set the private CHECKEDFLOW_AGENT_TOKEN environment variable and run:

checkedflow a2a --rpc http://127.0.0.1:26657 --chain my-chain \
  --mission array-mission --journal ./private/agent.sqlite --grpc-port 8081

It serves its public Agent Card on loopback port 8080, authenticated JSON-RPC at /rpc, HTTP+JSON at /v1, and optional gRPC on port 8081. For MCP HTTP, add --transport http to the MCP command; the endpoint is http://127.0.0.1:8082/mcp. The agent communication guide provides complete setup, request examples, official-client examples, status meanings and recovery steps. checkedflow schema agents exposes the machine-readable profile; checkedflow schema agent-request exposes the request contract.

The gateway holds no signing key and never executes received source. A protocol acknowledgment does not establish verifier acceptance. Push callbacks require an operator allowlist and public HTTPS destinations. Cancellation requires a signed administrative reconciliation. The conformance matrix distinguishes implemented server features from optional client roles and explicitly bounded application behavior. No LLM or arbitrary prompt interpreter is required: agents exchange the same portable signed commands.

Extend the state machine or a domain

The pure SDK interfaces are transition(state, command, context) and replay(initial_state, events). Replay includes explicit BlockHeight events so empty blocks can expire leases and capabilities. A transition context must already be authenticated; Runtime.apply verifies signed envelopes for ordinary SDK callers.

Schemas and vectors are included in the installed package:

checkedflow schema commands
checkedflow schema envelope
checkedflow schema state
checkedflow schema generator
checkedflow schema block
checkedflow schema vectors
checkedflow schema research

Use this project for bounded procedure-generation experiments, shared evidence accounting and portable runtime-adapter development. New problem domains need their own approved contract and worker/checker adapter. The bundled worker supports the integer-array reference verifier and refuses external side effects. Dynamic membership, private computation, a GUI, an artifact service and a general autonomous-agent framework are outside this release.

The core does not depend on the 18 source projects. The research map records the 18 software projects and 19 papers, their observed source hashes, adopted principles and claims this implementation does not establish. A local four-node test cannot establish real organizational independence. A negative verifier vote conservatively quarantines an artifact; one-fault consensus progress does not imply artifact availability under a malicious veto.

Find the right documentation

Run local static, contract, property, coverage and selected fault checks with:

uv run python scripts/check.py --actionlint /absolute/path/to/actionlint

Real Linux qualification and package installation checks are separate required release gates. The Trusted Publisher is kadubon/checkedflow, workflow workflow.yml, environment pypi. Publication is manual and sends the tested wheel and sdist without rebuilding. See releases and PyPI for published artifacts and their provenance.

Licensed under Apache-2.0. NOTICE includes upstream protocol attribution.