Flow documentation

Flow is a small, typed language for orchestrating models, tools and people. A program computes deterministically and reaches the outside world in exactly one way: a typed Tool call, a call to a function whose body lives outside Flow. Every outside observation, and every runtime choice the program could not derive for itself, is retained as semantic history. The same history explains a run afterwards, replays it without calling anything, and resumes it in a new process.

This tree is the design of record for that language. It is one layered chain: each layer has a distinct job and cites the layer above it instead of restating its claims.

How to read this tree

Everything here states target design — what a conforming Flow implementation must do — or explicitly non-normative guidance. A rule is not a claim that today's code satisfies it, and a shipped behavior does not become design by existing.

There is exactly one exception, and it is deliberate: runtime/architecture.md carries the corpus's only implementation ledger. Nothing else in this tree discusses implementation status, and where some other page seems to, the ledger outranks it.

Flow is pre-release. No artifact carries a compatibility promise, no encoding is stable, and versioned stability begins at the first public release.

Every flow code fence in this tree is listed in the documentation manifest, tests/docs/flow-fences.json, which gives each one a disposition and a reason. Until the implementation catches up with the language these documents define, the manifest marks every fence as an illustration: it is written in the decided syntax and checked by reading, not by a toolchain. text fences hold notation and illustrations that are not Flow.

The design chain names no mechanism the language does not have, and the specifications name no kind of application; check_doc_vocabulary.py refuses that vocabulary.

Start here

• getting-started.md — the language walked through one realistic program: a Tool import, the binding the host supplies, typed calls with match, ? and guard, a pause that is an open call, what history records, replay against resume, and checkpoints.
• examples.md — the pattern catalog beside it: fan-out, taking results in completion order, timeouts, selective cancellation, a model choosing an action, structured extraction, people in the loop, bounded loops, uncertain effects, and nested runs of model-written code.

The design chain

1. philosophy.md — why Flow is a language, the two commitments it makes, what it costs, and where its promise stops.
2. foundations.md — the givens about orchestration, the decisions Flow makes, and the requirements those force on every conforming implementation.
3. language/architecture.md — the mechanisms that satisfy those requirements: closed evaluation, Tools as functions whose bodies are outside Flow, one effect, failure as data, tasks that belong to function calls, history of only what cannot be computed, and the line between the language and the application that embeds it.
4. language/spec/ — the exact target contract. Each specification owns one surface, and that index is the full ownership map:
   • writing a program — grammar.md (source text, syntax and the canonical formatter), types.md (records, enums, visibility, generics, the data-type category), effects.md (!tool and purity), data.md (the built-in data types), and modules.md (files, use, versions, the prelude);
   • meaning — semantics.md (functions, evaluation order, tail calls, match, guard, patterns, entry functions), checking.md (what acceptance proves), errors.md (Result, ?, ToolProblem, faults), tools.md (@tool, host types, what crosses, decoding), and concurrency.md (tasks, ownership, stopping, timeouts);
   • continuity — history.md (facts, ids, pauses, checkpoints, replay, forks, holes, integrity);
   • library — stdlib.md (the std modules, the clock Tools, @lang declarations, json).
5. runtime/architecture.md — how the contract maps onto a conforming runtime, and the implementation ledger.
6. runtime/spec/ — the runtime contracts, which refine and never redefine the language: abi.md (the value encoding, the Tool process protocol, schemas, identity and fingerprints, binding, flow-tool.toml, toolkits and adapters), execution.md (entry, run states and exit codes, pause and resume, crashes, replay, forks, nested runs, limits, testing, the CLI and MCP surface), trace.md (the history format), and diagnostics.md (the diagnostic shape, codes and fixes).

Read in that order. A disagreement between two layers is a documentation defect, and the higher layer owns the decision until the lower one is repaired. A disagreement between a rule and an implementation is an implementation gap, not permission to weaken the rule.

The application boundary

Flow owns the meaning of the orchestration written in Flow. Everything around a run — model loops, sessions, tool registries, credentials, approvals, budgets, filesystem, network and process authority, sandboxing, retries, lifecycle and recovery beyond the run, and system-wide telemetry — belongs to the application or host that embeds it. The host binds an implementation to every @tool declaration a program can reach and decides where it lives; Flow prescribes no provider, process, container or transport topology. language/architecture.md draws the line.

Guides

Guides are non-normative. They describe practice around the language, create no semantics, and state no guarantee; where a guide differs from a specification, the specification wins.

• checkpoints.md — shaping a program so its loops can checkpoint: tail calls to top-level functions, and tasks parked on their only call.
• long-running-loops.md — programs that run for days parked on ordinary Tool calls: keeping a pending read alive, stopping finished races by hand, and moving to a new program version by forking.
• tool-registries.md — choosing between an Action enum the program owns and an open registry the host owns, reached through one generic call.
• recursive-delegation.md — delegation that recurses: sub-calls as recursion and tasks, and model-written code as a nested run with its own history.
• implementing-tools.md — writing the process behind a program's Tools with the Python, TypeScript or Rust toolkit: generating its types from flow tools, and choosing its outcomes.
• sharing-types.md — sharing types between modules, repositories and the implementations behind a program's Tools.