stateous 0.2.2__tar.gz → 0.3.0__tar.gz

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

@@ -11,3 +11,5 @@ try/
 try.db
 .stateous/
 site/
+.coverage
+.coverage.*

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: stateous
-Version: 0.2.2
+Version: 0.3.0
 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

{stateous-0.2.2 → stateous-0.3.0}/docs/concepts/agents.md

@@ -6,7 +6,7 @@ A routine runs a coding agent with the library PHD, and Stateous keeps the agent
 
 ## 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.
+A coding agent can work for an hour, hang, or crash with its computer. Its answer must name one of the events 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.
 
@@ -137,7 +137,7 @@ async def code(ctx: TicketContext) -> events.done | events.stuck:
 
 ## Guarantees
 
-- Only an outcome that the state can emit is accepted. PHD checks it, and the control plane checks it again.
+- Only an event 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.

{stateous-0.2.2 → stateous-0.3.0}/docs/concepts/context-notes-memory.md

@@ -27,7 +27,7 @@ These are the fields of `ctx`:
 | `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.entered_by` | The name of the event that brought the token here, as `ctx.entered_by.name`. In the first state, it is `__started__`. A routine does not get the payload: an event whose payload the token keeps declares `into=`. See [Where data goes](data.md). |
 | `ctx.schedule(event, after="10m")` | A timer. See [Timers and timeouts](timers.md). |
 
 ### The context

stateous-0.3.0/docs/concepts/data.md

@@ -0,0 +1,115 @@
+# Where data goes
+
+## In one sentence
+
+A routine reads and writes only the context: an event says why a token moved, and `into=` keeps its payload in the context.
+
+## Why it exists
+
+A token carries data from state to state. Without one rule, data can go to many places, and you must choose each time.
+
+Stateous has two rules, and the API follows them:
+
+1. **Data.** A routine reads and writes only the context. An event's name and payload say *why* the token moved. Guards and the history read the payload. If the token must keep a payload, the event declares `into=`.
+2. **Decisions.** Routines decide, and guards only route. A routine returns the event that names its decision. A guard only chooses a transition, from data that is already there.
+
+## How it works
+
+| Place | What it is for | Who reads it | When it is saved |
+|---|---|---|---|
+| The context, `ctx["key"]` | The data of the token: all that later states need. | Each routine of the token, and the guards. | With the event, or not at all. |
+| An event's payload | Why the token moved, for example a `Verdict`. | The guards, and the history. Not the routines. | With the event, in the history. |
+| `into="key"` on an event | Keeps the event's payload in the context, as `ctx["key"]`. | Each later routine, through the context. | With the event, before the guards run. |
+| `ctx.memory` | The routine's own bookkeeping, for example an agent's session id. | The routine of the same state, on a retry or a later visit. | At once. |
+| `ctx.note(text)` | One line of progress, for people. | People, in the history. | At once. |
+| `inputs=` on a parallel state | Data that goes down, from the parent's context to each child's context. | The routines of the child. | When the child starts. |
+| `into="key"` on a parallel state | Data that comes back up: the `Branches` of the join, with each child's context. | Each later routine of the parent. | When the join is met. |
+
+Some facts:
+
+- A routine knows which event brought the token in: `ctx.entered_by.name`, for example `timeout`. It does not get that event's payload. For the payload, declare `into=`.
+- `into=` works for each source of the event: a routine's report, `stateous token fire`, a timer and a resume.
+- If a routine writes the same key that the event's `into=` names, the payload wins.
+- `stateous compile` checks `into=`. The field must be in the context model, and its type must take the payload model, for example `Verdict` or `Verdict | None`.
+- `stateous token show` prints the context, so you can see what each routine wrote.
+
+## Example
+
+This is a `triage` workflow for support tickets. `classify` decides if a ticket is urgent. `escalate` pages an engineer. `answer` writes the reply.
+
+```python
+# triage/schemas.py
+from pydantic import BaseModel
+
+
+class Ticket(BaseModel):
+    title: str
+    body: str
+    on_call: str = ""  # escalate writes it
+    reply: str = ""  # answer writes it
+```
+
+The rule "the body has the word 'down'" is a decision. So a routine makes it, and returns `urgent` or `normal`. A guard does not search the text.
+
+```python
+# triage-supervisor/classify.py
+import re
+
+from stateous import on_state
+
+from contract import TicketContext, events, states
+
+
+@on_state(states.classify)
+def classify(ctx: TicketContext) -> events.urgent | events.normal:
+    if re.search(r"\bdown\b", ctx["body"].lower()):
+        return events.urgent()
+    return events.normal()
+```
+
+`escalate` writes the engineer's name to the context. `answer`, a later state, reads it there:
+
+```python
+# triage-supervisor/escalate.py
+from stateous import on_state
+
+from contract import TicketContext, events, states
+
+
+@on_state(states.escalate)
+def escalate(ctx: TicketContext) -> events.paged:
+    ctx["on_call"] = "Ada"
+    ctx.note("paged Ada")
+    return events.paged()
+```
+
+```python
+# triage-supervisor/answer.py
+from stateous import on_state
+
+from contract import TicketContext, events, states
+
+
+@on_state(states.answer)
+def answer(ctx: TicketContext) -> events.replied:
+    if ctx["on_call"]:
+        ctx["reply"] = f"This is urgent. {ctx['on_call']} works on it now."
+    else:
+        ctx["reply"] = "Thank you. We reply soon."
+    return events.replied()
+```
+
+`stateous token show TICKET-1` then prints the context with `on_call` and `reply`.
+
+## Guarantees
+
+- A routine's context changes and an event's `into=` are saved in one transaction with the event, or not at all.
+- A routine never sees a payload. So it cannot depend on data that the token does not keep.
+- `stateous compile` refuses an `into=` whose field is not in the context model. It also refuses a field whose type does not take the payload.
+
+## See also
+
+- [Context, notes and memory](context-notes-memory.md): each field of `ctx`.
+- [Guards](guards.md): what a guard can read.
+- [Parallel and nested work](parallel.md): `inputs=` and `into=` on a parallel state.
+- [The model](model.md): the words context, payload and event.

{stateous-0.2.2 → stateous-0.3.0}/docs/concepts/guards.md

@@ -6,10 +6,12 @@ A guard is a small condition in `when=` that chooses which transition an event t
 
 ## 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.
+One event 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.
 
+Routines decide, and guards only route. A decision about the work, such as "the body of the ticket has the word 'down'", is the work of a routine. The routine returns the event that names the decision, for example `urgent` or `normal`. A guard only chooses a transition from data that is already there: a count, a field of the payload, a field of the context. So the guard language has no text search and no arithmetic. See [Where data goes](data.md).
+
 ## 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:
@@ -38,6 +40,14 @@ When an event comes, the control plane looks at the transitions from the token's
 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 rule of `otherwise=True`.** This is the one place where the docs give this rule:
+
+- A transition that is the only one from its state on its event needs no guard and no `otherwise=True`.
+- When a state has two or more transitions on one event, each has a guard, except at most one. That one has no guard, and it must have `otherwise=True`: it is the fallback.
+- The fallback is optional. With no fallback, an event that no guard matches is refused.
+
+Compile stops if a transition breaks this rule.
+
 ### 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.
@@ -46,8 +56,6 @@ If two guards can overlap, compile stops with an error, and it gives an example
 
 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`:

{stateous-0.2.2 → stateous-0.3.0}/docs/concepts/model.md

@@ -10,7 +10,7 @@ A long process has many steps, and each step can take minutes or days. A step ca
 
 Stateous puts the process in one graph. The graph tells all the places where a run can be, and all the ways to go on. A run never moves in a way that the graph does not show.
 
-This page defines each word of Stateous. Every other page uses each word in the same sense.
+This page defines each word that you need to build with Stateous. Every other page uses each word in the same sense. The words of how Stateous works inside, such as lease and outbox, are on [The words inside](../inside/words.md).
 
 ## How it works
 
@@ -44,7 +44,7 @@ Two states are Stateous's own. `START` is where each token begins, and `END` is
 
 ### event
 
-An outcome of a state, for example `passed` or `failed`. Only an event moves a token. An event can have a payload.
+What happened in a state, for example `passed` or `failed`. Only an event moves a token. Its name and its payload say why the token moved.
 
 Stateous has three events of its own: `timeout`, `error` and `joined`. Your transitions use them by name. You cannot declare them, and you cannot fire them.
 
@@ -62,25 +62,20 @@ The status is `active`, `paused`, `completed`, `failed` or `cancelled`. A token
 
 ### context
 
-The business data of a token, for example the path of a checkout. A pydantic model gives its fields. A routine reads it as `ctx["key"]`, and can write it.
+The business data of a token, for example the path of a checkout. A pydantic model gives its fields. A routine reads it as `ctx["key"]`, and can write it. It is the only data that a routine reads and writes. See [Where data goes](data.md).
 
 ### payload
 
-The data of one event, for example the numbers of tests that passed and failed. A pydantic model gives its fields. An event without a payload model has no payload.
+The data of one event, for example the numbers of tests that passed and failed. A pydantic model gives its fields. An event without a payload model has no payload. Guards and the history read the payload. To keep it for later states, the event declares `into="key"`, and the context keeps it as `ctx["key"]`.
 
 ### task
 
 "Do state S for token T". The control plane queues one task each time a token enters a state. A supervisor claims the task and runs its routine.
 
-
 ### visit
 
 One stay of a token in one state. The first time that a token enters a state is visit 1, the next time is visit 2. A routine reads it as `ctx.visit`. The history shows it, for example `entered coding (visit 2)`.
 
-### claim
-
-A supervisor's request for a task of the states that it serves. The control plane answers with a grant: one queued task, its token, its visit, its attempt and its context. The task is then claimed.
-
 ### routine
 
 Your function that does the work of one state. It gets the token's context as `ctx`, and it returns an event. It is in the supervisor's folder, and it is marked with `@on_state(states.X)`.
@@ -97,45 +92,22 @@ The process that keeps every token, and chooses each next state. You start it wi
 
 The compiled workflow, as JSON, for example `sdlc/build/sdlc.json`. `stateous compile` writes it, and `stateous serve` serves it.
 
-
-### checksum
-
-The hash of the whole graph file, for example `sha256:...`. Each change to the graph file changes it. A supervisor's `contract.py` is for one checksum.
-
-### structure
-
-The hash of the graph file without the `timeout=` and `retries=` of its states. A database serves one structure at a time. See [Change a workflow](../how-to/change-a-workflow.md).
-
 ### contract
 
 The file `contract.py` in the supervisor's folder. `stateous init supervisor` writes it from the graph. It gives the states, the events that each state can emit, and the models. It is all that a supervisor knows of the workflow.
 
-### ledger
-
-The history of each token. Each change adds one row, and the rows are never changed. `stateous token show` prints the ledger of a token.
-
 ### guard
 
-A condition on a transition, written in `when=`. It reads the context, the payload and counts of events. See [Guards](guards.md).
+A condition on a transition, written in `when=`. It reads the context, the payload and counts of events. A guard only routes: a routine makes the decisions. See [Guards](guards.md).
 
 ### timer
 
 An event that the clock fires later, if the token is still in the same state. A state's `timeout=` is a timer too. See [Timers and timeouts](timers.md).
 
-### lease
-
-The time for which a supervisor holds a claimed task. A heartbeat renews it. See [Tasks and routines](tasks-and-routines.md).
-
-
-### heartbeat
-
-The message that a supervisor sends every 30 seconds for all the tasks that it holds. It renews their leases. Its answer names each task that the supervisor does not hold now, for example because the token left the state.
-
 ### attempt
 
 One try of a task. The first claim is attempt 1. When an attempt fails and the state has retries left, the next claim is attempt 2.
 
-
 ### retries
 
 The number of more attempts that a state gives after a failed attempt: `retries=2` gives three attempts in all. After the last failed attempt, the token gets the event `error`.
@@ -156,24 +128,10 @@ A state whose work is other workflows, which run at the same time. It has no tas
 
 A token that a parallel state starts, one for each workflow of the state. Its parent is the token in the parallel state.
 
-
 ### join
 
 The rule that tells when a parallel state is done. `join="all"` waits for each child token to end. `join="any"` continues when the first child token ends. When the join is met, the control plane fires `joined` on the parent.
 
-### outbox
-
-The supervisor's local file of messages that the control plane did not answer yet: `.stateous/outbox.db`. See [Reliability](reliability.md).
-
-### idempotency key
-
-A key that you give with an event from outside. A second event with the same key applies nothing, and gets the answer "duplicate". See [Reliability](reliability.md).
-
-
-### held event
-
-An event that comes to a paused token. The control plane keeps it, and applies it on resume, in the order of arrival. The history shows `done held while paused`. See [Pause, resume and cancel](pause-resume-cancel.md).
-
 ## Example
 
 The `sdlc` workflow has two states. In `coding`, an agent writes code. In `testing`, a routine runs the tests.
@@ -240,7 +198,7 @@ stateDiagram-v2
 - A token is in one state at a time. Only an event moves it, and only along a transition of the graph.
 - An event that the token's state cannot take is refused. The token stays where it is, and the ledger records the refusal.
 - The ledger keeps each change. Stateous never changes or deletes a row of the ledger.
-- Not guaranteed: that your routine does the right work. Stateous makes sure only that its outcome is one that the graph allows.
+- Not guaranteed: that your routine does the right work. Stateous makes sure only that its event is one that the graph allows.
 
 ## See also
 

{stateous-0.2.2 → stateous-0.3.0}/docs/concepts/parallel.md

@@ -47,9 +47,11 @@ When the join is met, the control plane fires the event `joined` on the parent.
 - `token`: the child's id;
 - `status`: `completed` or `failed`;
 - `final`: the state that the child was in when it ended;
-- `payload`: the payload of the event that brought the child into that state.
+- `context`: the child's context when it ended.
 
-A guard on `joined` can use `branches.all(...)` and `branches.any(...)`. In the parentheses, use `workflow`, `token`, `status`, `final` and `payload.field`. The guard can also use `ctx` and `count`.
+A guard on `joined` can use `branches.all(...)` and `branches.any(...)`. In the parentheses, use `workflow`, `token`, `status`, `final` and `context.field`. `stateous compile` checks that a child workflow of the state has the field. The guard can also use `ctx` and `count`.
+
+To keep the results of the children for later states, give the parallel state `into="reviews"`. The parent's context then keeps the payload of `joined` as `ctx["reviews"]`. Its type in the context model is `Branches` (from `stateous`), or `Branches | None`. So data goes down to the children with `inputs=`, and comes back with `into=`, always through the context. See [Where data goes](data.md).
 
 `stateous compile` cannot prove that two guards with `branches` never overlap. So give the guard to one transition, and make the other the fallback with `otherwise=True`. If no transition takes `joined`, the parent fails.
 

{stateous-0.2.2 → stateous-0.3.0}/docs/concepts/pause-resume-cancel.md

@@ -103,6 +103,10 @@ error: the control plane at http://127.0.0.1:8080 refused (409): token 'TICKET-3
 
 ```text
 TICKET-3: testing, cancelled
+context:
+  {
+    "repo": "acme/api"
+  }
 22:39:47  #1  started
 22:39:47  #2  __started__ in START
 22:39:47  #3  entered coding

{stateous-0.2.2 → stateous-0.3.0}/docs/concepts/reliability.md

@@ -130,7 +130,7 @@ build-box-2 took task 1 (attempt 2)
 
 ## See also
 
-- [The model](model.md): the words [ledger](model.md#ledger), [lease](model.md#lease), [outbox](model.md#outbox) and [idempotency key](model.md#idempotency-key).
+- [The words inside](../inside/words.md): [ledger](../inside/words.md#ledger), [lease](../inside/words.md#lease), [outbox](../inside/words.md#outbox) and [idempotency key](../inside/words.md#idempotency-key).
 - [Tasks and routines](tasks-and-routines.md): claims, heartbeats and attempts.
 - [Context, notes and memory](context-notes-memory.md): the routine's memory.
 - [Pause, resume and cancel](pause-resume-cancel.md).

{stateous-0.2.2 → stateous-0.3.0}/docs/concepts/tasks-and-routines.md

@@ -20,7 +20,7 @@ A task goes through these steps:
 4. **Heartbeat.** While the routine runs, the supervisor sends a heartbeat every 30 seconds. One heartbeat names all of its running tasks, and it renews their leases.
 5. **Report.** The routine returns, and the supervisor reports the outcome. An event moves the token, and the task is done.
 
-The supervisor reports one of three kinds of outcome:
+The supervisor reports the **outcome** of the task. An outcome is one of three kinds:
 
 | Outcome | When | What the control plane does |
 |---|---|---|
@@ -128,9 +128,9 @@ build-box-2 took task 1 (attempt 2)
 
 ## See also
 
-- [The model](model.md): the words [task](model.md#task), [routine](model.md#routine), [lease](model.md#lease) and [attempt](model.md#attempt).
+- [The model](model.md): the words [task](model.md#task), [routine](model.md#routine), [lease](../inside/words.md#lease) and [attempt](model.md#attempt).
 - [The two sides](two-sides.md): what crosses the network.
 - [Timers and timeouts](timers.md): a state's `timeout=` covers all attempts.
 - [Context, notes and memory](context-notes-memory.md): every field of `ctx`.
 - [Reliability](reliability.md): leases, the outbox, and what happens when a supervisor stops.
-- [Write a routine](../how-to/write-a-routine.md): mark a routine, return an outcome, and fail.
+- [Write a routine](../how-to/write-a-routine.md): mark a routine, return an event, and fail.

{stateous-0.2.2 → stateous-0.3.0}/docs/concepts/two-sides.md

@@ -12,7 +12,7 @@ So Stateous has two sides. The control plane decides, and the supervisors do the
 
 The supervisor never sees the graph, for two reasons:
 
-- A routine cannot depend on the next state. It can only return an outcome, so you can change the graph without a change to the routines.
+- A routine cannot depend on the next state. It can only return an event, so you can change the graph without a change to the routines.
 - A supervisor has only the information that its work needs. The rest of the process stays on the control plane.
 
 ## How it works

{stateous-0.2.2 → stateous-0.3.0}/docs/getting-started.md

@@ -36,48 +36,99 @@ Next steps:
 
 On Windows, the paths in these lines have `\` in place of `/`.
 
-This is `orders/flow.py`:
+This is `orders/flow.py`, as `init` writes it:
 
 ```python
 # orders/flow.py: the workflow. `stateous compile orders/flow.py` checks it and writes
 # the graph file, orders/build/orders.json.
 from stateous import END, START, Workflow
 
+from schemas import Job, Result
+
+# The workflow. Each token has a context: a Job (see schemas.py). The context is
+# the data of a token. A routine reads and writes only the context.
+flow = Workflow("orders", context=Job)
+
+# The states. A token is in one state at a time. A routine does the work of a state.
+work = flow.state("work")
+
+# The events. An event moves a token. Its payload says why the token moved.
+# `into="result"` keeps the payload in the context, as ctx["result"].
+done = flow.event("done", payload=Result, into="result")
+
+# The transitions: where each event takes a token. START and END begin and end each token.
+# A routine decides which event to return. A guard (`when=`) only chooses a transition.
+# See https://stateouslabs.github.io/stateous/concepts/data/
+flow.transition(START, work)
+flow.transition(work, END, on=done)
+```
+
+The starter has one state, `work`, and one event, `done`. Its comments give two rules:
+
+- **Where data goes.** The context is the data of a token. A routine reads and writes only the context. An event's payload says why the token moved. `into=` keeps a payload in the context. See [Where data goes](concepts/data.md).
+- **Who decides.** A routine decides, and returns the event that names its decision. A guard only chooses a transition.
+
+## Make it yours
+
+Now change the starter into `orders`. Replace `orders/schemas.py` with this:
+
+```python
+# orders/schemas.py (your version)
+from pydantic import BaseModel
+
+
+class Verdict(BaseModel):
+    """The payload of the event `reviewed`."""
+
+    approved: bool
+    note: str = ""
+
+
+class Item(BaseModel):
+    """The context of each token of `orders`."""
+
+    title: str
+    verdict: Verdict | None = None  # `reviewed` keeps its payload here
+```
+
+Replace `orders/flow.py` with this:
+
+```python
+# orders/flow.py (your version)
+from stateous import END, START, Workflow
+
 from schemas import Item, Verdict
 
-# The workflow and its name. Each token has a context: an Item (see schemas.py).
 flow = Workflow("orders", context=Item)
 
-# The states. A token is in one state at a time. A routine does the work of a state.
-# `timeout=` and `retries=` are optional. See
-# https://stateouslabs.github.io/stateous/how-to/write-a-workflow/
 draft = flow.state("draft")
 review = flow.state("review")
 
-# The events: the outcomes that move a token. A payload is optional.
 submitted = flow.event("submitted")  # no payload
-reviewed = flow.event("reviewed", payload=Verdict)  # the payload is a Verdict
+reviewed = flow.event("reviewed", payload=Verdict, into="verdict")
 
-# The transitions: where each event takes a token. START and END begin and end each token.
 flow.transition(START, draft)  # a new token goes to `draft` at once
 flow.transition(draft, review, on=submitted)
-# A guard (`when=`) is optional. Here, the payload of `reviewed` chooses the target.
+# The routine of `review` decides. The guard only routes on its Verdict.
 flow.transition(review, END, on=reviewed, when="payload.approved == true")
-# `otherwise=True` marks the transition to use when no guard matches.
 flow.transition(review, draft, on=reviewed, otherwise=True)
 ```
 
+Then compile it again:
+
+```bash
+stateous compile orders/flow.py
+```
+
 What each part does:
 
 - `Workflow("orders", context=Item)` makes the workflow. A **token** is one run of the workflow. Each token has a **context**: here, an `Item`.
 - `flow.state(...)` adds a **state**. A token is in one state at a time. When a token enters a state, the control plane makes a **task** for it.
-- `flow.event(...)` adds an **event**: an outcome of a state. Only an event moves a token. An event can have a **payload**, for example a `Verdict`.
+- `flow.event(...)` adds an **event**. Only an event moves a token. An event can have a **payload**, for example a `Verdict`. With `into="verdict"`, the context keeps the `Verdict` as `ctx["verdict"]`.
 - `flow.transition(...)` tells where an event takes a token. `START` is where each token begins, and `END` is where it ends.
 - `when=` is a **guard**: a condition on the payload or the context. Here, an approved `Verdict` ends the token.
 - `otherwise=True` marks the transition that applies when no guard matches. Here, a `Verdict` that does not approve sends the token back to `draft`.
 
-`orders/schemas.py` holds the two models. `Item` has one field, `title`. `Verdict` has the fields `approved` and `note`.
-
 This is the graph of `orders`:
 
 ```mermaid
@@ -88,7 +139,7 @@ stateDiagram-v2
     review --> draft: reviewed (otherwise)
 ```
 
-`init` also compiled `flow.py` to the graph file `orders/build/orders.json`. After you change `flow.py`, compile it again with `stateous compile orders/flow.py`.
+`stateous compile` writes the graph file `orders/build/orders.json`. After each change to `flow.py` or `schemas.py`, compile again.
 
 ## Terminal 1: serve the workflow
 
@@ -161,10 +212,18 @@ stateous token start ORDER-1 '{"title": "first order"}'
 stateous token show ORDER-1
 ```
 
-`token start` prints `ORDER-1: draft, active`. One or two seconds later, `token show` prints the token and its history:
+`token start` prints `ORDER-1: draft, active`. One or two seconds later, `token show` prints the token, its context and its history:
 
 ```text
 ORDER-1: review, completed
+context:
+  {
+    "title": "first order",
+    "verdict": {
+      "approved": true,
+      "note": ""
+    }
+  }
 22:23:31  #1  started
 22:23:31  #2  __started__ in START
 22:23:31  #3  entered draft
@@ -175,9 +234,10 @@ ORDER-1: review, completed
 22:23:32  #8  entered review
 22:23:32  #9  task 2 queued for review
 22:23:32  #10  build-box-1 took task 2 (attempt 1)
-22:23:32  #11  reviewed in review: {"approved": true, "note": ""}
-22:23:32  #12  task 2 done
-22:23:32  #13  completed
+22:23:32  #11  context changed: verdict
+22:23:32  #12  reviewed in review: {"approved": true, "note": ""}
+22:23:32  #13  task 2 done
+22:23:32  #14  completed
 ```
 
 The first line gives the last state and the status. `build-box-1` is the name of the supervisor: by default, the host name of its computer.
@@ -193,6 +253,14 @@ The review sends `ORDER-2` back to `draft`. There, `draft` returns `None`, so th
 
 ```text
 ORDER-2: draft (visit 2), active
+context:
+  {
+    "title": "reject me",
+    "verdict": {
+      "approved": false,
+      "note": ""
+    }
+  }
 22:23:40  #1  started
 22:23:40  #2  __started__ in START
 22:23:40  #3  entered draft
@@ -203,13 +271,14 @@ ORDER-2: draft (visit 2), active
 22:23:40  #8  entered review
 22:23:40  #9  task 4 queued for review
 22:23:40  #10  build-box-1 took task 4 (attempt 1)
-22:23:40  #11  reviewed in review: {"approved": false, "note": ""}
-22:23:40  #12  task 4 done
-22:23:40  #13  entered draft (visit 2)
-22:23:40  #14  task 5 queued for draft
-22:23:40  #15  build-box-1 took task 5 (attempt 1)
-22:23:40  #16  the review sent this order back: a person must change it
-22:23:40  #17  task 5 waits: the work goes on outside
+22:23:40  #11  context changed: verdict
+22:23:40  #12  reviewed in review: {"approved": false, "note": ""}
+22:23:40  #13  task 4 done
+22:23:40  #14  entered draft (visit 2)
+22:23:40  #15  task 5 queued for draft
+22:23:40  #16  build-box-1 took task 5 (attempt 1)
+22:23:40  #17  the review sent this order back: a person must change it
+22:23:40  #18  task 5 waits: the work goes on outside
 ```
 
 The token stays in `draft` until a person acts. For example, `stateous token cancel ORDER-2` cancels it. [Steer tokens](how-to/steer-tokens.md) tells what else a person can do.

{stateous-0.2.2 → stateous-0.3.0}/docs/how-to/steer-tokens.md

@@ -47,16 +47,22 @@ The duplicate shows the token as it is now. A key stays used for the life of the
 
 ```bash
 stateous token show TICKET-1
+stateous token show TICKET-1 --json
 stateous token show
 stateous token show --graph
 ```
 
-- With an id, `show` prints the token's line, its children, and its history. The times are local.
+- With an id, `show` prints the token's line, its context, its children, and its history. The times are local.
+- With an id and `--json`, it prints the same as one JSON object, for scripts.
 - With no id, it lists the tokens, at most 100, the most recently moved first.
 - `--graph` draws the workflow as a Mermaid diagram.
 
 ```text
 TICKET-1: testing, completed
+context:
+  {
+    "repo": "acme/api"
+  }
 23:43:39  #1  started
 23:43:39  #2  __started__ in START
 23:43:39  #3  entered coding
@@ -157,6 +163,6 @@ The `Idempotency-Key` header is the key. A payload goes in the body, as `{"paylo
 - [Pause, resume and cancel](../concepts/pause-resume-cancel.md): held events, and the order of replay.
 - [Reliability](../concepts/reliability.md): idempotency keys.
 - [Tasks and routines](../concepts/tasks-and-routines.md): tasks that wait.
-- [The model](../concepts/model.md): the words [token](../concepts/model.md#token) and [idempotency key](../concepts/model.md#idempotency-key).
+- [The model](../concepts/model.md): the words [token](../concepts/model.md#token) and [idempotency key](../inside/words.md#idempotency-key).
 - [The commands](../reference/cli.md): every `token` command and its options.
 - [The HTTP API](../reference/http.md): every route, and the refusal codes.