docs: consolidate design documentation and standardize crate English

crates/flow/README.md

@@ -0,0 +1,10 @@
+# flow
+
+`flow` compiles DCDL state graphs into typed definitions and evaluates transitions against pinned definitions and verification results. Callers own Workspace source persistence, Worker Session writes, and internal verifier execution. This crate implements neither role-specific work loops nor state-entry side effects.
+
+## Main entry points
+
+- [`compile_flow_source`](src/definition.rs): Source evaluation and graph validation.
+- [`FlowSelector`](src/selector.rs) / [`ResolvedFlowSource`](src/selector.rs): Explicit source identity and immutable snapshots.
+- [`FlowRuntimeState`](src/coordinator.rs): Instances, transition attempts, and ordered events.
+- [`builtin_flow_source`](src/builtin.rs): Read-only catalog of embedded sources.

crates/flow/src/builtin.rs

@@ -1,3 +1,9 @@
+//! Read-only catalog of embedded Flow sources.
+//!
+//! Provides exact source bytes without copying them into the Workspace DB or
+//! maintaining manual update counters. The Runtime pins the compiled digest,
+//! so resource updates do not change existing instance definitions.
+
 use crate::{CompiledFlowDefinition, FlowCompileError, compile_flow_source};
 
 pub const CODER_REVIEW_FLOW_SLUG: &str = "coder-review";

crates/flow/src/coordinator.rs

@@ -1,3 +1,18 @@
+//! Builds transition attempts from pinned Flow definitions and chooses destinations
+//! from complete verdict sets.
+//!
+//! Callers do not specify a target state: an attempt pins every outgoing condition
+//! of the current state. Each condition needs exactly one result, with no duplicate,
+//! missing, or unknown IDs. Entry requires exactly one Met result and no
+//! Indeterminate results. Verifier failures, cancellations, and incomplete responses
+//! are not successful transitions.
+//!
+//! Checks the instance, active attempt, definition digest, and captured state so old
+//! verifier results cannot apply to new attempts, even after returning to the same
+//! state. Event sequences track append order, not freshness or source identity.
+//! This module performs typed state transformations; callers own persistence,
+//! verifier startup, and business side effects.
+
 use std::collections::{BTreeMap, BTreeSet};
 
 use serde::{Deserialize, Serialize};
@@ -198,11 +213,13 @@ pub struct FlowRuntimeEvent {
     pub event: FlowEventKind,
 }
 
-/// Durable Flow authority owned by one Runtime Worker.
+/// Flow state durably owned by one Runtime Worker.
 ///
-/// Workspace authority resolves the exact source content, but never mutates
-/// this value. Runtime persists the complete snapshot with the Worker session
-/// and replaces it only after the corresponding session-log write succeeds.
+/// Pins the resolved definition and digest to the instance, so source edits do not
+/// change existing instances. Callers prepare new state on a clone and replace live
+/// state only after a successful Session write. Recover verifying attempts after
+/// restoration rather than creating competing attempts. Events reject reused attempt
+/// IDs even after failure/cancellation. Stopping a Worker does not transfer state.
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 pub struct FlowRuntimeState {
     pub definition: CompiledFlowDefinition,
@@ -253,8 +270,7 @@ impl FlowRuntimeState {
         ))
     }
 
-    /// Begin a new attempt, or return the persisted active attempt after a
-    /// Runtime/Worker restore. A recovered attempt is never rewritten.
+    /// Starts a new attempt or returns the restored active attempt unchanged.
     pub fn begin_or_recover_transition(
         &mut self,
         attempt_id: impl Into<String>,

crates/flow/src/definition.rs

@@ -1,3 +1,19 @@
+//! Compiles DCDL sources into typed Flow definitions.
+//!
+//! The source document is the graph authority; states and transitions are not split
+//! into independently editable records. DCDL evaluation passes through private
+//! Serde-compatible values into the source schema, then graph validation produces
+//! a [`CompiledFlowDefinition`]. Intermediate JSON is neither a public API type nor
+//! a persisted Runtime state type. Imports are rejected, and a single document's
+//! content digest pins the execution definition.
+//!
+//! Validates schemas, identifiers, and targets; rejects unreachable states, closed
+//! paths that cannot reach a user-defined terminal, outgoing terminal transitions,
+//! and nonterminal states without transitions. Authored `$cancelled` states are
+//! forbidden; synthetic cancellation transitions are excluded from normal-terminal
+//! reachability checks. Only validated definitions receive a `$cancelled` terminal,
+//! so exceptional cancellation cannot make an invalid normal-completion graph pass.
+
 use std::collections::{BTreeMap, BTreeSet, VecDeque};
 use std::fmt;
 use std::fmt::Write as _;

crates/flow/src/lib.rs

@@ -1,8 +1,4 @@
-//! Declarative Flow definitions and deterministic transition coordination.
-//!
-//! DCDL is a source format only.  The Flow domain owns the typed source
-//! schema, semantic validation, immutable transition snapshots, and state
-//! transition rules.
+#![doc = include_str!("../README.md")]
 
 mod builtin;
 mod coordinator;

crates/flow/src/selector.rs

@@ -1,3 +1,10 @@
+//! Explicit Flow source ownership and immutable source snapshots.
+//!
+//! `builtin:<slug>` and `workspace:<slug>` identify distinct logical records and may
+//! coexist with the same slug. There is no implicit override order or unqualified
+//! selector. Source resolution is separate from execution instance creation and
+//! mutation; the Runtime pins the resolved result before execution.
+
 use std::fmt;
 use std::str::FromStr;
 
@@ -114,11 +121,10 @@ pub struct FlowSourceResolveRequest {
     pub selector: FlowSelector,
 }
 
-/// Immutable source snapshot resolved by Workspace authority for one Runtime.
+/// Immutable source snapshot resolved by the Workspace authority.
 ///
-/// This is read-only source authority. Starting or mutating a Flow instance is
-/// deliberately not part of this response; Runtime persists the snapshot in
-/// the target Worker's durable state before execution.
+/// This read-only source authority creates no instances, attempts, or events.
+/// The Runtime commits the snapshot to the target Worker's Session before execution.
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 pub struct ResolvedFlowSource {
     pub selector: FlowSelector,