stateous 0.2.0__tar.gz → 0.2.2__tar.gz

{stateous-0.2.0 → stateous-0.2.2}/.gitignore

@@ -10,3 +10,4 @@ stateous.db
 try/
 try.db
 .stateous/
+site/

{stateous-0.2.0 → stateous-0.2.2}/PKG-INFO

@@ -1,11 +1,11 @@
 Metadata-Version: 2.5
 Name: stateous
-Version: 0.2.0
+Version: 0.2.2
 Summary: A process as a graph of states. A control plane keeps every token durable.
 Project-URL: Homepage, https://github.com/StateousLabs/stateous
 Project-URL: Source, https://github.com/StateousLabs/stateous
 Project-URL: Issues, https://github.com/StateousLabs/stateous/issues
-Project-URL: Documentation, https://github.com/StateousLabs/stateous/blob/main/docs/guide.md
+Project-URL: Documentation, https://stateouslabs.github.io/stateous/
 Author: The Stateous Authors
 License-Expression: Apache-2.0
 License-File: LICENSE
@@ -38,6 +38,12 @@ Description-Content-Type: text/markdown
 
 # Stateous
 
+[![CI](https://github.com/StateousLabs/stateous/actions/workflows/ci.yml/badge.svg)](https://github.com/StateousLabs/stateous/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/stateous?cacheSeconds=3600)](https://pypi.org/project/stateous/)
+[![Python](https://img.shields.io/pypi/pyversions/stateous?cacheSeconds=3600)](https://pypi.org/project/stateous/)
+[![Docs](https://img.shields.io/badge/docs-GitHub%20Pages-blue)](https://stateouslabs.github.io/stateous/)
+[![License](https://img.shields.io/pypi/l/stateous?cacheSeconds=3600)](https://github.com/StateousLabs/stateous/blob/main/LICENSE)
+
 Stateous runs a process as a graph of states, and keeps every token of it durable.
 
 You write the graph in Python. A control plane keeps every token and chooses each next state. A supervisor, on any computer, does the work and reports what happened. The supervisor never sees the graph. It knows only which states it serves, and which outcomes each state allows.
@@ -53,42 +59,25 @@ pip install stateous            # or: uv add stateous
 pip install "stateous[phd]"     # also PHD, to run agents in routines
 ```
 
-Then run the `stateous` command in that environment. The control plane keeps its data in SQLite or in Postgres.
-
-## The example
+The control plane keeps its data in SQLite or in Postgres.
 
-[`examples/sdlc/`](https://github.com/StateousLabs/stateous/tree/main/examples/sdlc) is a workflow with two states: `coding` and `testing`. [`examples/sdlc-supervisor/`](https://github.com/StateousLabs/stateous/tree/main/examples/sdlc-supervisor) is the supervisor's folder for it.
+## A short example
 
 ```bash
-# on the control plane's computer
-stateous compile sdlc/flow.py                         # writes sdlc/build/sdlc.json
-stateous serve sdlc/build/sdlc.json --listen 0.0.0.0:8080
-
-# on the supervisor's computer
-stateous init supervisor http://cp.internal:8080 sdlc-supervisor  # contract.py, stubs, stateous.yaml, pyproject.toml
-stateous supervise sdlc-supervisor                    # runs the routines
-
-# anywhere
-stateous token start TICKET-1 '{"repo": "acme/api"}' --url http://cp.internal:8080
-stateous token show TICKET-1 --url http://cp.internal:8080
+stateous init workflow orders                               # a starter workflow that compiles
+stateous serve orders/build/orders.json                     # the control plane
+stateous init supervisor orders/flow.py orders-supervisor   # contract.py and a stub for each state
+stateous supervise orders-supervisor                        # runs your routines
+stateous token start ORDER-1 '{"title": "first order"}'     # starts a token
 ```
 
-Stateous has no authentication. Keep a control plane that listens on a wider address behind a VPN or a proxy.
-
-To start a workflow of your own, let Stateous write a starter that compiles:
+Write the routines in `orders-supervisor/` before you run `supervise`. [`examples/sdlc/`](https://github.com/StateousLabs/stateous/tree/main/examples/sdlc) and [`examples/sdlc-supervisor/`](https://github.com/StateousLabs/stateous/tree/main/examples/sdlc-supervisor) are a larger example.
 
-```bash
-stateous init workflow orders                         # orders/flow.py, schemas.py, pyproject.toml, build/orders.json
-stateous serve orders/build/orders.json
-stateous init supervisor orders/flow.py orders-supervisor  # from a local flow.py or graph file, too
-```
-
-To try the example on one computer, follow [the guide](https://github.com/StateousLabs/stateous/blob/main/docs/guide.md#try-it-on-one-computer).
+Stateous has no authentication. Keep a control plane that listens on a wider address behind a VPN or a proxy.
 
-## Learn more
+## Documentation
 
-- [`docs/guide.md`](https://github.com/StateousLabs/stateous/blob/main/docs/guide.md): the guide, on one page.
-- [`examples/`](https://github.com/StateousLabs/stateous/tree/main/examples): the example.
+The documentation is at [stateouslabs.github.io/stateous](https://stateouslabs.github.io/stateous/). It explains the model, then tells you how to do the work, then gives the reference. To run the short example step by step, follow [Getting started](https://stateouslabs.github.io/stateous/getting-started/).
 
 ## Licence
 

stateous-0.2.2/README.md

@@ -0,0 +1,46 @@
+# Stateous
+
+[![CI](https://github.com/StateousLabs/stateous/actions/workflows/ci.yml/badge.svg)](https://github.com/StateousLabs/stateous/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/stateous?cacheSeconds=3600)](https://pypi.org/project/stateous/)
+[![Python](https://img.shields.io/pypi/pyversions/stateous?cacheSeconds=3600)](https://pypi.org/project/stateous/)
+[![Docs](https://img.shields.io/badge/docs-GitHub%20Pages-blue)](https://stateouslabs.github.io/stateous/)
+[![License](https://img.shields.io/pypi/l/stateous?cacheSeconds=3600)](https://github.com/StateousLabs/stateous/blob/main/LICENSE)
+
+Stateous runs a process as a graph of states, and keeps every token of it durable.
+
+You write the graph in Python. A control plane keeps every token and chooses each next state. A supervisor, on any computer, does the work and reports what happened. The supervisor never sees the graph. It knows only which states it serves, and which outcomes each state allows.
+
+> **Status:** alpha. The API can change before version 1.0.
+
+## Install
+
+Stateous needs Python 3.12 or newer.
+
+```bash
+pip install stateous            # or: uv add stateous
+pip install "stateous[phd]"     # also PHD, to run agents in routines
+```
+
+The control plane keeps its data in SQLite or in Postgres.
+
+## A short example
+
+```bash
+stateous init workflow orders                               # a starter workflow that compiles
+stateous serve orders/build/orders.json                     # the control plane
+stateous init supervisor orders/flow.py orders-supervisor   # contract.py and a stub for each state
+stateous supervise orders-supervisor                        # runs your routines
+stateous token start ORDER-1 '{"title": "first order"}'     # starts a token
+```
+
+Write the routines in `orders-supervisor/` before you run `supervise`. [`examples/sdlc/`](https://github.com/StateousLabs/stateous/tree/main/examples/sdlc) and [`examples/sdlc-supervisor/`](https://github.com/StateousLabs/stateous/tree/main/examples/sdlc-supervisor) are a larger example.
+
+Stateous has no authentication. Keep a control plane that listens on a wider address behind a VPN or a proxy.
+
+## Documentation
+
+The documentation is at [stateouslabs.github.io/stateous](https://stateouslabs.github.io/stateous/). It explains the model, then tells you how to do the work, then gives the reference. To run the short example step by step, follow [Getting started](https://stateouslabs.github.io/stateous/getting-started/).
+
+## Licence
+
+Apache License 2.0. See [`LICENSE`](https://github.com/StateousLabs/stateous/blob/main/LICENSE) and [`NOTICE`](https://github.com/StateousLabs/stateous/blob/main/NOTICE).

stateous-0.2.2/docs/concepts/agents.md

@@ -0,0 +1,153 @@
+# Agents, with PHD
+
+## In one sentence
+
+A routine runs a coding agent with the library PHD, and Stateous keeps the agent's task alive, its progress visible and its session safe.
+
+## Why it exists
+
+A coding agent can work for an hour, hang, or crash with its computer. Its answer must be one of the outcomes that the state allows. When it fails, the next try should continue its session, not start again.
+
+Stateous and PHD share this work. PHD runs the agent and checks its answer. Stateous keeps the task, the retries and the session id. PHD knows nothing of workflows, and it does not report to Stateous.
+
+## How it works
+
+| Need | Who does it |
+|---|---|
+| Run the agent | PHD, called by an `async def` routine. |
+| Keep the task's lease alive while the agent runs | The supervisor. It sends heartbeats for each task whose routine still runs. |
+| Stop the agent when the token leaves the state, or is cancelled | The supervisor cancels the routine. PHD's `async with … run(...)` block stops the run when it ends. |
+| Choose the outcome | The agent. PHD's `output_schema` is `states.X.outcome_schema()`, so the agent's answer names one allowed event and its payload. |
+| Check the outcome | PHD checks the answer against the schema. A mismatch is a failed run, so a failed attempt. `states.X.outcome(...)` makes the event, and the control plane checks it again. |
+| See that an agent is stuck | PHD. `Spec.idle_timeout_s` stops a run that sends no event for that long. |
+| Show progress | The routine gives PHD's events to `ctx.note(...)`. |
+| Keep the session for the next attempt | The routine, with `ctx.memory`. |
+| Retry and time out | Stateous, as for each routine. |
+
+```mermaid
+sequenceDiagram
+    participant S as Supervisor
+    participant R as Routine
+    participant P as PHD
+    participant H as Harness (the agent)
+    participant CP as Control plane
+    S->>R: code(ctx)
+    R->>P: Dispatcher(spec).run(inputs, session_id)
+    P->>H: start or resume the session
+    loop while the agent works
+        H-->>P: an event
+        P-->>R: event.summary, handle.session_id
+        R->>CP: ctx.memory["dev"] = session id (once)
+        R->>CP: ctx.note(event.summary)
+    end
+    H-->>P: the final answer
+    P-->>R: result.structured_output, checked
+    R-->>S: states.coding.outcome(...): an event
+    S->>CP: report the event
+    Note over S,H: Cancel: the token leaves the state. The next heartbeat says "lost".<br/>The supervisor cancels the routine, and PHD stops the run.
+```
+
+### The contract's helpers for agents
+
+The contract gives each state two helpers:
+
+- `states.X.outcome_schema()`: the events that state X can emit, with their payloads, as one JSON schema;
+- `states.X.outcome(data)`: the event that `data` names, checked against the schema. It raises `OutcomeError` if `data` does not fit.
+
+### Install PHD
+
+PHD is on PyPI as `poly-harness-dispatcher`. Its import name is `phd`. Install it in the supervisor's environment with the `phd` extra of Stateous:
+
+```bash
+pip install "stateous[phd]"     # or: uv add "stateous[phd]"
+```
+
+From a copy of the Stateous repository, use `uv add --editable path/to/stateous --extra phd`.
+
+Without PHD, the supervisor cannot import a routine that imports `phd`, and it does not start. Then remove that routine, and report its state from outside, as [Try it on one computer](../how-to/run-supervisors.md#try-it-on-one-computer) shows for `coding`.
+
+PHD needs a stack and credentials for each run. `phd.Stack.load("stacks/dev")` loads the agent's stack folder: its identity, skills and tools. The path is relative to the folder where the supervisor runs. `phd.Credentials.from_host("claude")` uses the login of the supervisor's computer. The PHD documentation tells how to write a stack.
+
+### What the routine uses from PHD
+
+- `Dispatcher(spec).run(inputs, session_id=...)` is an `async with` block. If the block ends before the run ends, PHD stops the run.
+- `handle.session_id` is the harness's session id. It is `None` until the harness reports it.
+- `Spec.idle_timeout_s` stops a run that sends no event for that long. The run's status is then `timed_out`, with the error kind `idle`.
+- `Spec.timeout_s` is the longest time for one run. Its default is 1800 seconds. Set it when an agent must work longer.
+- `event.summary` is one line for a `message`, `tool_call` or `tool_result` event. For other events, it is `""`.
+- `result.error.kind` is one of `phd.ERROR_KINDS`. Use the kind, not the message.
+- `Spec.cwd` must be a folder that exists. If it does not exist, PHD refuses the spec (`CwdNotFound`).
+
+### Sessions, crashes and retries
+
+The routine keeps the session id in `ctx.memory`, as soon as the harness reports it. The memory is saved at once, so a crash keeps it. The next attempt gives the session id to `run(...)`, and the agent continues its session.
+
+With the error kind `"session"`, PHD cannot resume the session. The routine then deletes the session id from `ctx.memory`. So the retry starts a new session. With another kind, the retry resumes the same session.
+
+The running agents of a supervisor are its child processes. PHD ties each agent to its caller, so the agents stop when the supervisor crashes. On Windows, a Job Object stops them. On Linux and macOS, a small reaper process stops the agent's process group. If PHD cannot start this protection, the run continues without it, and `result.warnings` says so. Then the agent can continue after a crash of the supervisor.
+
+### Free-form payloads
+
+Codex uses OpenAI's strict structured outputs. These cannot return an object that has no listed properties. So a payload model with a `dict[str, Any]` field cannot run on Codex. PHD refuses such a run before it starts (`UnsupportedFeature`). Claude and OpenCode accept it.
+
+## Example
+
+This is the routine of `coding` in the `sdlc` example:
+
+```python
+# sdlc-supervisor/coding.py: an agent, run by PHD (see the docs, Concepts > Agents, with PHD)
+import phd
+
+from stateous import on_state
+
+from contract import TicketContext, events, states
+
+
+@on_state(states.coding)
+async def code(ctx: TicketContext) -> events.done | events.stuck:
+    spec = phd.Spec(
+        harness="claude",
+        model="sonnet",
+        stack=phd.Stack.load("stacks/dev"),  # the agent: a PHD stack folder
+        cwd=ctx["repo"],
+        credentials=phd.Credentials.from_host("claude"),  # the login of this computer
+        output_schema=states.coding.outcome_schema(),
+        idle_timeout_s=900,  # no event for 15 minutes: stop
+    )
+    inputs = phd.Inputs(msg=f"Implement {ctx['repo']}")
+    # Leaving the block stops an unfinished run:
+    # an error, or the token left the state.
+    async with phd.Dispatcher(spec).run(inputs, session_id=ctx.memory.get("dev")) as handle:
+        async for ev in handle.events():
+            if handle.session_id and "dev" not in ctx.memory:
+                # known when the harness reports it; saved at once, so a crash keeps it
+                ctx.memory["dev"] = handle.session_id
+            ctx.note(ev.summary)  # progress in the token's history; "" gives no note
+        result = await handle.wait()
+    if result.status != "succeeded":
+        if result.error and result.error.kind == "session" and "dev" in ctx.memory:
+            del ctx.memory["dev"]  # the session cannot be resumed: the retry starts fresh
+        raise RuntimeError(result.error)  # a failed attempt
+    return states.coding.outcome(result.structured_output)
+```
+
+- The agent's answer must name `done` or `stuck`, because `output_schema` is `states.coding.outcome_schema()`.
+- A failed run raises an exception, so the attempt fails. `coding` has `retries=2`, so the agent gets two more attempts.
+- The state's `timeout="6h"` covers all attempts.
+
+## Guarantees
+
+- Only an outcome that the state can emit is accepted. PHD checks it, and the control plane checks it again.
+- The task's lease stays alive while the routine runs, for as long as the agent works.
+- When the token leaves the state, or is cancelled, the supervisor cancels the routine at the next heartbeat, and PHD stops the run.
+- The session id in `ctx.memory` stays after a crash, so the next attempt can resume the session.
+- Not guaranteed: that an agent's steps are safe to repeat. After a crash, the agent can repeat its last step or two. Its instructions must make that safe.
+- Not guaranteed: free-form payloads on Codex. A `dict[str, Any]` field fails before the run starts.
+
+## See also
+
+- [Context, notes and memory](context-notes-memory.md): `ctx.memory` and `ctx.note`.
+- [Tasks and routines](tasks-and-routines.md): `async def` routines, cancel, and retries.
+- [Reliability](reliability.md): what happens when the supervisor stops.
+- [Write a routine](../how-to/write-a-routine.md): `outcome_schema()` and `outcome()`.
+- [Limits](../reference/limits.md): the known limits, also on Codex.

stateous-0.2.2/docs/concepts/context-notes-memory.md

@@ -0,0 +1,113 @@
+# Context, notes and memory
+
+## In one sentence
+
+A routine gets `ctx`, which holds the token's context, the routine's own memory, and a way to write notes to the token's history.
+
+## Why it exists
+
+A routine needs three kinds of data, and each one has different rules:
+
+- **The context** is the business data of the token, for example the path of a checkout. The guards read it, so a change to it must agree with the outcome.
+- **A note** tells a person what the routine does now, for example each step of an agent.
+- **The memory** is bookkeeping for the routine, for example an agent's session id. It must stay after a crash, because the next attempt needs it.
+
+## How it works
+
+These are the fields of `ctx`:
+
+| Field | What it gives |
+|---|---|
+| `ctx["key"]` | A value of the token's context. It raises `KeyError` for a key that is not set. |
+| `ctx["key"] = value` | A change to the token's context. It is saved with the outcome, or not at all. |
+| `ctx.get("key", default)` | The same as `ctx["key"]`, with a default value for a key that is not set. |
+| `ctx.memory` | The routine's own memory, for this token and this state. Each change is saved at once. |
+| `ctx.note(text)` | One line of progress in the token's history. It is sent at once. |
+| `ctx.token` | The token's id. |
+| `ctx.task` | The task's id. |
+| `ctx.visit` | 1 the first time the token is in this state, 2 the next time, and so on. |
+| `ctx.attempt` | 1, then 2 after a retry, and so on. |
+| `ctx.entered_by` | The event that brought the token here: `.name` and `.payload`. In the first state, `.name` is `__started__`. |
+| `ctx.schedule(event, after="10m")` | A timer. See [Timers and timeouts](timers.md). |
+
+### The context
+
+A value that you read from `ctx` is a copy. So `ctx["items"].append(2)` changes nothing. Write the new value with `ctx["items"] = ...`. Values must be JSON.
+
+The supervisor sends the changes with the report. The control plane checks them against the context model. Changes that do not agree with the model fail the task. A failed attempt saves no change to the context.
+
+### Notes
+
+`ctx.note(text)` adds one line to the token's history. A note has up to 500 characters. A longer note raises `ValueError`. Empty text does nothing, so you can give each event of an agent to `ctx.note`.
+
+A note is sent at once, through the supervisor's outbox. It does not wait for the outcome.
+
+### The memory
+
+`ctx.memory` is a small key-value store. Stateous keeps one for each token **and** state. Use it for bookkeeping, for example an agent's session id. Do not use it for the workflow's data.
+
+| Property | Rule |
+|---|---|
+| Scope | One token and one state. `TICKET-1` in `coding` and `TICKET-1` in `testing` have different memories. |
+| Saving | At once, with `PUT /tasks/{id}/memory`, not with the outcome. So it stays after a crash. |
+| Keys and values | A key has 1 to 128 characters. A value is JSON. |
+| Delete a key | `del ctx.memory["dev"]`. A value of `None` raises `ValueError`. |
+| Retries | The next attempt sees it, so it can resume a crashed agent session. |
+| Later visits | The token sees it again when it comes back to the state. |
+| Several agents in one state | The routine chooses the keys, for example `memory["dev"]` and `memory["review"]`. |
+| A new session for each visit | Put the visit in the key: `memory[f"dev:{ctx.visit}"]`. |
+| End | It is deleted when the token ends: completed, failed or cancelled. |
+| History | The history records the key of each change, never the value: `memory set: dev (in coding)`. |
+| Guards | They cannot read it. |
+
+The context and the memory follow different rules:
+
+| | The context | The memory |
+|---|---|---|
+| Saved | With the outcome, or not at all | At once |
+| After a failed attempt | The changes are lost | The changes stay |
+| Seen by | The whole token: each state, and the guards | One state of one token |
+| Checked against a model | Yes | No: any JSON value |
+
+## Example
+
+The routine of `coding` in `sdlc` runs an agent. It keeps the agent's session id in `ctx.memory`, and it writes each event of the agent as a note:
+
+```python
+async with phd.Dispatcher(spec).run(inputs, session_id=ctx.memory.get("dev")) as handle:
+    async for ev in handle.events():
+        if handle.session_id and "dev" not in ctx.memory:
+            # known when the harness reports it; saved at once, so a crash keeps it
+            ctx.memory["dev"] = handle.session_id
+        ctx.note(ev.summary)  # progress in the token's history; "" gives no note
+    result = await handle.wait()
+```
+
+If the supervisor stops, the next attempt reads `ctx.memory.get("dev")`, and the agent continues its session. The whole routine is on [Agents, with PHD](agents.md).
+
+A routine can also write the context. Here, the routine of `testing` keeps the last result for a later state:
+
+```python
+@on_state(states.testing)
+def test(ctx: TicketContext) -> events.passed | events.failed:
+    result = run_tests(ctx["repo"])
+    ctx["last_failed"] = result.failed  # saved with the event
+    return events.passed(result) if result.failed == 0 else events.failed(result)
+```
+
+For this, `Ticket` must have a field `last_failed`. Else the control plane refuses the change, and the task fails.
+
+## Guarantees
+
+- Changes to the context are saved with the outcome in one transaction, or not at all.
+- Notes and memory writes are sent in order, before the report of the same task.
+- A memory write is on disk in the supervisor's outbox before it is sent. A crash does not lose it, if the supervisor starts again before the task's lease ends.
+- A note or a memory write for an attempt that is over is refused. An old attempt cannot write to a new one.
+- Not guaranteed: that the memory stays after the token ends. It is deleted when the token ends.
+
+## See also
+
+- [The model](model.md): the words [context](model.md#context), [note](model.md#note) and [memory](model.md#memory).
+- [Agents, with PHD](agents.md): the memory keeps an agent's session.
+- [Reliability](reliability.md): the supervisor's outbox.
+- [Write a routine](../how-to/write-a-routine.md): the routine that reads and writes `ctx`.

stateous-0.2.2/docs/concepts/guards.md

@@ -0,0 +1,97 @@
+# Guards
+
+## In one sentence
+
+A guard is a small condition in `when=` that chooses which transition an event takes, from the data of the token and the event.
+
+## Why it exists
+
+One outcome can lead to different places. For example, a failed test run goes back to `coding` two times, but the third failure ends the token. The routine must not know this rule, because it does not see the graph.
+
+So the graph holds the rule, as a guard on the transition. Stateous checks the guards when you compile, so a token never has two ways to go.
+
+## How it works
+
+A guard is an expression in a small language. It is not Python, and nothing runs it as Python. It can use these items:
+
+| Item | What it reads |
+|---|---|
+| `ctx['key']` | A field of the token's context, with the changes of the routine. |
+| `payload.field` | A field of the payload of the event. |
+| `count('event')` | How many times the token accepted this event, this one included. |
+| `<`, `<=`, `>`, `>=`, `==`, `!=`, `in`, `not in` | Comparisons. |
+| `and`, `or`, `not` | Logic. |
+| `1`, `-2.5`, `'text'`, `true`, `false`, `null`, `[1, 2]` | Numbers, strings, the three names, and lists of these. |
+
+Some rules of the language:
+
+- A guard reads the context as `ctx['key']`, never as `ctx.key`. It cannot read `ctx.memory`.
+- On the right of `in` and `not in`, use a list, or a value from `ctx`, `payload` or `count`. A string is not permitted there.
+- A value that is not set reads as `null`. A comparison of `null` with a number is false, not an error.
+- `count('event')` counts the event over the whole life of the token, not for one visit.
+- A guard on a transition from `START` reads only the context. A new token has no event yet, so it has no payload and no count.
+- A guard on `joined` can also use `branches.all(...)` and `branches.any(...)`. See [Parallel and nested work](parallel.md).
+
+When an event comes, the control plane looks at the transitions from the token's state on that event:
+
+1. If one guard matches, the token takes that transition.
+2. If no guard matches, the token takes the transition with `otherwise=True`.
+3. If no guard matches and there is no `otherwise=True`, the control plane refuses the event. The token stays where it is.
+
+### The overlap check
+
+`stateous compile` makes sure that the guards on one state and one event never overlap. Two guards overlap when some data can make both of them true.
+
+If two guards can overlap, compile stops with an error, and it gives an example of such data. Stateous never chooses between two matching guards at run time.
+
+Compile also stops when it cannot prove that two guards never overlap. This occurs when a guard compares two values with each other, orders a list, or uses `branches`. Then make one transition the fallback with `otherwise=True`.
+
+Next to transitions with guards, a transition without a guard must have `otherwise=True`. Compile stops if it does not.
+
+## Example
+
+In `sdlc`, the event `failed` has two transitions from `testing`:
+
+```python
+flow.transition(testing, coding, on=failed, when="count('failed') < 3")
+flow.transition(testing, END, on=failed, otherwise=True)
+```
+
+The first and second `failed` have a count of 1 and 2, so they go back to `coding`. The third has a count of 3, so the token ends.
+
+A guard can also read the payload and the context. The `orders` starter ends a token when the review approves it:
+
+```python
+flow.transition(review, END, on=reviewed, when="payload.approved == true")
+flow.transition(review, draft, on=reviewed, otherwise=True)
+```
+
+Now give the context of `orders` an `int` field `amount`. These two guards overlap:
+
+```python
+flow.transition(review, END, on=reviewed, when="ctx['amount'] > 100")
+flow.transition(review, draft, on=reviewed, when="ctx['amount'] > 50")
+```
+
+`stateous compile` refuses them, and it gives an amount that makes both of them true:
+
+```text
+error: workflow 'orders' is not valid:
+  - 'reviewed' from 'review': the guards "ctx['amount'] > 100" and "ctx['amount'] > 50" can both be true, e.g. when ctx['amount'] = 101; make them exclusive, or make one the fallback (otherwise=True)
+```
+
+Change the second guard to `ctx['amount'] <= 100`, or make it the fallback.
+
+## Guarantees
+
+- An event takes at most one transition. Compile proves that the guards on one state and event never overlap.
+- A guard has no side effects. It reads data, and it changes nothing.
+- A guard reads only fields that its models have. Compile checks each `ctx['key']` against the context model, and each `payload.field` against the payload model.
+- `count('event')` must name an event of the workflow, or `timeout`, `error` or `joined`.
+- Not guaranteed: that an event finds a transition. With no `otherwise=True`, an event that no guard matches is refused.
+
+## See also
+
+- [The model](model.md): the words [transition](model.md#transition) and [guard](model.md#guard).
+- [Timers and timeouts](timers.md): guards on the events `timeout` and `error`.
+- [Write a workflow](../how-to/write-a-workflow.md): compile errors for guards that overlap.