@smthrs/flow 0.0.0-stage → 1.0.0-rc.3

package/docs/concepts/the-runtime-port.md

@@ -0,0 +1,110 @@
+---
+title: "The runtime port"
+description: "FlowRuntime is the service the authoring APIs are written against, what it must provide, and why this package depends on nothing that implements it."
+sidebar:
+  order: 6
+---
+
+`FlowRuntime` is the smallest service a `Flow`, an `Action`, a `DurableDeferred`,
+or a `DurableClock` needs in order to be executed, polled, suspended, and
+resumed. This package declares that port and depends on nothing that implements
+it. The dependency runs one way:
+
+```text
+@smthrs/flow          declares FlowRuntime
+      ↓
+@smthrs/engine        implements it
+      ↓
+@smthrs/engine-store  makes the implementation durable
+```
+
+There is deliberately no dependency, type-only or otherwise, from
+`@smthrs/flow` back to `@smthrs/engine`. That is what lets the authoring model
+bundle for a browser, and what lets a test swap a whole engine for a fixture
+without touching a declaration.
+
+## What the port provides
+
+| Method                                                    | What it does                                                                                    |
+| --------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
+| `register`                                                | Binds a flow tag to the behavior that drives it. `Interpreter.layer` is the only public caller. |
+| `execute`                                                 | Starts or joins an execution under a given id, optionally discarding the result.                |
+| `poll`                                                    | Answers the current `Result` of an execution, or nothing when it is known and unsettled.        |
+| `interrupt`, `interruptUnsafe`                            | Requests cancellation. A durable engine records the request before interrupting anything.       |
+| `resume`                                                  | Re-drives a suspended execution.                                                                |
+| `actionExecute`                                           | Dispatches one action attempt and records its exit.                                             |
+| `deferredResult`, `deferredDone`, `deferredDoneIfWaiting` | Reads and writes durable deferred completions.                                                  |
+| `scheduleClock`                                           | Arms a durable timer.                                                                           |
+| `recordNode`                                              | Optional. Records the graph a run was driven from, and how each node settled.                   |
+
+Every method takes a flow whatever its requirement channel says and demands none
+of it. The channel is a compile-time statement about which action implementations
+a body names, and the port sits below where that statement is settled: a runtime
+resolves each call by the tag the node carries, which is the only thing left of a
+plan read back out of a journal. `Flow.execute`, one level up, is where the
+requirements are collected.
+
+`deferredDoneIfWaiting` answers a `DeferredDoneIfWaitingOutcome` of `Completed`,
+`Existing`, or `NotWaiting`. It exists so a completion can be admitted as one
+mutation only while its run is actually parked on that wait, which is what stops
+a guessed or stale token from pre-answering a run. It does not authorize the
+caller: a token is an unsigned address, so the host authorizes whoever
+completes an open wait.
+
+`recordNode` is the one optional method, and optional in the strong sense: a
+runtime that keeps no history leaves it absent and the walk is unchanged, so no
+interpreter behavior may depend on whether one is there. An engine with a
+journal implements it by writing the record. Each record carries its own
+replay-stable `sourceId`, and an implementation must use that as the record's
+producer identity rather than minting one per observation: that is what makes a
+resumed walk collapse onto the rows the first walk wrote instead of recording
+every node twice. It is separate from `actionExecute` because a node is not an
+action, and three of the four records describe nodes no action ever dispatched.
+
+## The per-execution instance
+
+`FlowRuntime.FlowInstance` is one execution's frontier state: its `executionId`,
+`lineageId`, `flow`, a `scope` closed only when the execution fully completes,
+the mutable `suspended`, `interrupted`, `waiting`, `handoff`, and `cause` fields,
+and `actionState`. This package declares the contract; a runtime constructs the
+value. A completion wakes a parked run through `FlowRuntime.resume`.
+
+## Declaring a wait
+
+`FlowRuntime.annotateWaiting(annotation)` is how an implementation tells a
+durable driver what kind of wait is about to happen, so the run parks under that
+reason and token rather than a derived default. A `WaitingAnnotation` is
+`{ reason, wakeAt?, token? }`. `Sleep` declares `timer` with the deadline,
+`WaitFor` declares `event` with the wake token, and `HumanTask` declares
+`approval` with the current attempt's token.
+
+## Failures the port defines
+
+| Failure                 | Raised when                                                                                                                                                                                                    |
+| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `FlowCycleDetected`     | Executing a flow would close a cycle in the persisted parent-execution chain. `path` holds the ordered execution ids from the cycle's target back to itself.                                                   |
+| `FlowExecutionNotFound` | `poll` or `resume` names an execution id the runtime never recorded.                                                                                                                                           |
+| `CancelRequestFailed`   | A durable runtime could not record a cancellation. `cancel_request_failed` is a storage failure; `unsafe_interrupt_unsupported` is the durable engine refusing `interruptUnsafe`, which it does not implement. |
+
+`CancelRequestFailed` is the reason `interrupt` is not fire and forget: the
+request is recorded before anything is interrupted, so a caller that cannot
+record it learns the run is still going instead of being told it stopped.
+
+## Implementing the port
+
+Two implementations ship:
+
+- `FlowEngine.layerMemory` from [`@smthrs/engine`](/api/engine) keeps every
+  recorded step in the process. Use it for tests and local development.
+- The durable engine from [`@smthrs/engine-store`](/api/engine-store) backs the
+  same port with SQLite, which is what turns a suspended run into one a later
+  process resumes.
+
+A third implementation is an ordinary exercise: satisfy the port and every
+declaration in this package runs against it unchanged.
+
+## Related pages
+
+- [Suspension and replay](./suspension-and-replay.md): what the port's park and
+  resume mean to a body.
+- [Testing](../testing.md): running flows against the in-memory implementation.

package/docs/concepts/trampoline-rounds.md

@@ -0,0 +1,151 @@
+---
+title: "Trampoline rounds"
+description: "How a flow loops: one round settles with Done, To, or Park, the engine follows a handoff to the next round, and maxRounds bounds the lineage."
+sidebar:
+  order: 5
+---
+
+A body builds one round. Loops that depend on a runtime value are not written
+inside a round; they are written as a **lineage** of rounds, where each round
+ends by naming the next one. That is a trampoline, and it is why the plan can
+stay static while the loop count cannot.
+
+## The three settlements
+
+A body may settle a round with an ordinary success value, or with one of three
+outcomes:
+
+| Outcome | Constructor                    | What it means                                           |
+| ------- | ------------------------------ | ------------------------------------------------------- |
+| `Done`  | `Flow.done(value)`             | End the lineage with this value.                        |
+| `To`    | `someFlow.to(payload)`         | End this round and open the next one with this payload. |
+| `Park`  | `Flow.park({ reason, token })` | Park this round durably under a waiting reason.         |
+
+A round that hands off settles as `Flow.Handoff`, beside `Complete` and
+`Suspended`. Following the handoff is the engine's job: this package produces the
+settlement, and [`@smthrs/engine`](/api/engine) opens the next round.
+
+A handoff completes the round successfully and discards its `withRollback` registrations.
+It closes the current round's scope with a success exit, running its exit
+finalizers. The next round has a fresh scope, so its failure cannot roll back
+effects from earlier rounds. The engine does not provide lineage-scoped
+compensation; compensation across rounds requires an explicit durable design.
+Suspension keeps the current round's scope open instead. See
+[Scope and cleanup](./suspension-and-replay.md#scope-and-cleanup).
+
+Values are passed in their author-facing form. The engine encodes a `Done` value
+with the settling flow's success schema and a `To` payload with the target flow's
+payload schema, at the settlement boundary. Callers do not pre-encode.
+
+## A loop that counts
+
+```ts
+import { Action, Flow } from "@smthrs/flow"
+import { Node } from "@smthrs/plan"
+import * as Schema from "effect/Schema"
+
+const Increment = Action.make("trampoline/increment", {
+  payload: { value: Schema.Number },
+  success: Schema.Number
+})
+
+type CounterFlow = Flow.Flow<
+  "trampoline/counter",
+  Schema.Struct<{ value: typeof Schema.Number; target: typeof Schema.Number }>,
+  typeof Schema.Number,
+  typeof Schema.Never,
+  Action.Requirement<"trampoline/increment">
+>
+
+const Counter: CounterFlow = Flow.make("trampoline/counter", {
+  payload: { value: Schema.Number, target: Schema.Number },
+  success: Schema.Number,
+  body: ({ target, value }: { readonly value: number; readonly target: number }) =>
+    Increment.call({ value }).pipe(
+      Node.branch({
+        if: (next) => next >= target,
+        then: (next) => Flow.done(next),
+        else: (next) => Counter.to({ value: next, target })
+      })
+    )
+})
+```
+
+Two things about that declaration are load bearing.
+
+The body names the flow it is the body of. That is legal because a body is read
+when a round is planned, long after `Flow.make` returned, so the binding is
+initialized by then. The explicit `CounterFlow` type annotation is what breaks
+the circularity for the compiler.
+
+`.to()` **drops** the requirement channel. A self-handoff that propagated its
+requirements would have to name its own requirements inside them, and the type
+would not be finite. Dropping it is sound because a handoff ends this execution
+and the next round runs under its own driver's context.
+
+## Cancelling a logical run
+
+Keep the execution ID returned at admission. `flow.interrupt(id)` requests
+cancellation across the logical run, even after that round has handed off;
+using a later round ID reaches the same lineage. A completed predecessor is
+historical evidence, not proof the whole job is complete. Its recorded handoff
+is not rewritten as a cancellation.
+
+Cancellation reaches linked children, including children created by earlier
+rounds and their handoff successors. A fork's ancestry does not, by itself,
+create a cancellation link. The durable engine serializes intent with handoff
+admission; the memory engine retains intent before admitting a later round.
+Returning from `interrupt` means the request was recorded, not that user cleanup
+or an owner in another process has finished. It is permanent; `resume` does not
+undo it. Low-level `poll(id)` still reads the named round's result, not a
+consolidated logical-run observation.
+
+## The round budget
+
+`Flow.make`'s `maxRounds` bounds one lineage. It is a budget, not loop detection:
+identical consecutive rounds are legal, so a runaway lineage is stopped by
+counting rounds rather than by comparing them. Absent means unbounded, which is
+the right default for a lineage whose exit condition is its own branch.
+
+`maxRounds` must be a positive safe integer; `Flow.make` throws a `RangeError`
+otherwise. Exceeding it terminates the lineage with a `Flow.MaxRoundsExceeded`
+defect recorded in the execution result. It is not a typed `execute` failure,
+because a lineage that ran away is a declaration bug rather than an outcome a
+caller was told to expect.
+
+## The lineage deadline
+
+A lineage is one run, so `Flow.make`'s `deadline` bounds the whole lineage, not
+each round. The originating round journals its first start; each round that
+hands off stamps that start and the bound on its `Flow.Handoff`, and the next
+round runs under the stamp whatever it declares. Every round therefore expires
+at the originator's start plus the originator's deadline, and settles with
+`Flow.DeadlineExceeded` when it passes.
+
+## Recognizing an outcome
+
+`Flow.isOutcome` does not work by shape. Ordinary success data may carry the same
+`_tag` fields, and treating it as control would let a payload steer a run. Graph
+construction carries a non-enumerable marker from the authoring node to its
+hydrated value, and the guard reads that marker, so
+`{ _tag: "Done", value: 1 }` written by hand is not an outcome.
+
+## What trampolines are for
+
+- **Fan out over discovered data.** `Node.all` fixes its width at plan time. When
+  the width comes from a step result, end the round and carry the list in the
+  next round's payload, where it is real data.
+- **Loop until a runtime condition holds.** `Poll.make` is exactly this,
+  packaged: its body is one attempt that either settles the lineage or sleeps and
+  hands off with the attempt counter raised. See
+  [Poll until something is ready](../guides/poll-until-ready.md).
+- **Park a round for something outside the run** without pretending the wait is a
+  step, with `Flow.park`.
+
+## Related pages
+
+- [Bodies are plans](./bodies-and-plans.md): why width is fixed inside a round.
+- [Suspension and replay](./suspension-and-replay.md): the other two results and
+  what a re-drive does.
+- [Run a flow as a child execution](../guides/run-a-child-flow.md): the other
+  boundary that drops requirements, and how it differs from a handoff.

package/docs/guides/ask-a-person.md

@@ -0,0 +1,184 @@
+---
+title: "Ask a person for a decision"
+description: "Park a run on a typed question, record an answer against the attempt's token, re-ask a refused answer, and give the question a deadline."
+sidebar:
+  order: 6
+---
+
+`HumanTask.action` is a question as a plan node. The run parks under the
+`approval` waiting reason, someone records an answer against the token it parked
+with, and the node settles with that answer. Validation, re-asking, and a
+deadline are part of the declaration rather than something the caller builds.
+
+## Ask the question
+
+```ts
+import { Action, Flow, HumanTask, Interpreter } from "@smthrs/flow"
+import * as Layer from "effect/Layer"
+import * as Schema from "effect/Schema"
+
+export const Release = Flow.make("release/Release", {
+  payload: { build: Schema.String },
+  success: Schema.Json,
+  error: HumanTask.HumanTaskFailed,
+  body: ({ build }) =>
+    HumanTask.action.call({
+      name: "release",
+      kind: "confirm",
+      prompt: `Ship ${build}?`,
+      maxAttempts: 3
+    })
+})
+
+export const layer = Layer.mergeAll(
+  HumanTask.layer,
+  Interpreter.layer(Release)
+).pipe(Layer.provideMerge(Action.layerImplementations))
+```
+
+`name` addresses the question. Two calls naming one question in one execution
+await one answer.
+
+## Choose the shape of the answer
+
+| `kind`    | What the person supplies                | Other fields |
+| --------- | --------------------------------------- | ------------ |
+| `ask`     | Prose.                                  | none         |
+| `confirm` | A boolean.                              | none         |
+| `select`  | One of the strings in `options`.        | `options`    |
+| `json`    | A value the task's JSON Schema accepts. | `schema`     |
+
+A `schema` supplied with any kind other than `json` is refused, because nothing
+would check it. The bounded schema subset is `type` (`object`, `array`, `string`,
+`number`, `integer`, `boolean`, `null`), `enum`, `properties`, `required`,
+`items`, `nullable`, `description`, and `title`. `enum` members may be any JSON
+value, including objects and arrays, and membership is compared structurally
+rather than by reference.
+
+## Give the answer a type
+
+`HumanTask.action` succeeds with `Schema.Json`. `HumanTask.decode` gives that
+answer your own type:
+
+```ts
+const Decision = Schema.Struct({ decision: Schema.Literals(["ship", "hold"]) })
+
+const asked = HumanTask.action.call({
+  name: "release",
+  kind: "json",
+  prompt: "Ship the release?",
+  schema: {
+    type: "object",
+    required: ["decision"],
+    properties: { decision: { enum: ["ship", "hold"] } }
+  },
+  maxAttempts: 3,
+  timeoutMs: 6 * 60 * 60 * 1000
+}).pipe(HumanTask.decode(Decision))
+```
+
+The schema you pass to `decode` and the question's own schema description must
+agree. A disagreement surfaces as a defect rather than as a failure a body could
+catch, because the two descriptions are the same claim written twice.
+
+## Record an answer
+
+The run parks carrying the current attempt's token. Whoever collects the answer
+records it against that token:
+
+```ts
+import { DurableDeferred } from "@smthrs/flow"
+
+const tokenFor = (executionId: string, attempt: number): DurableDeferred.Token =>
+  DurableDeferred.tokenFromExecutionId(HumanTask.deferred("release", attempt), {
+    flow: Release,
+    executionId
+  })
+
+export const answer = (executionId: string, attempt: number) =>
+  HumanTask.answer({ token: tokenFor(executionId, attempt), value: true })
+```
+
+Each attempt is its own durable wait point, named `WaitFor/<name>#<attempt>`,
+because a durable deferred records the first completion and replays it forever.
+The runtime admits an answer only while the run is parked on that exact approval
+wait, and records the completion as one mutation, so a guessed, unopened, or
+stale token cannot pre-answer a run. A token whose deferred name
+`HumanTask.deferred` could not have written fails with
+`DurableDeferred.TokenInvalid` carrying `deferred_mismatch`.
+
+These checks bound when an answer lands, not who sends it. A token is an
+unsigned address the execution id and attempt rebuild, so the endpoint that
+calls `HumanTask.answer` must authorize the person first.
+
+Do not track the attempt number in your own process. Read it back from the
+engine's waiting row, which carries the `approval` reason and the token of the
+one attempt that is open.
+
+## Refuse an answer before it is sent
+
+`HumanTask.validate(value, request)` returns the reason an answer would be
+refused, or `undefined`. Run it in the interface, so a typo is refused while the
+person is still looking at it:
+
+```ts
+const problem = HumanTask.validate(candidate, { kind: "select", options: ["ship", "hold"] })
+```
+
+`HumanTask.validateSchema(schema)` checks that a JSON Schema stays inside the
+bounded subset at every depth, and returns the first reason it does not.
+
+## When the question ends without an answer
+
+A refused answer is recorded under the attempt that refused it, as a sealed step
+named `HumanTask/<name>#<attempt>/rejected` carrying the task, the attempt, and
+the reason. The run then parks on the next attempt's token. A re-driven round
+replays every answer it already has and parks on the first attempt that has none,
+so a restart between the park and the answer resumes on the same token.
+
+`HumanTask.HumanTaskFailed` carries `code`, `task`, `attempts`, the `rejections`
+it collected, and a message:
+
+| Code              | Meaning                                                                                                                                                                                                                                                           |
+| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `request_invalid` | The question was unanswerable before anyone was asked: a `select` with no options, an attempt budget below one or above `HumanTask.maxAttemptBudget`, a `timeoutMs` that is not a length of time, or a schema outside the subset or past its depth or node bound. |
+| `rejected`        | The attempt budget was spent on answers the task refused.                                                                                                                                                                                                         |
+| `timeout`         | The deadline passed with the question still open.                                                                                                                                                                                                                 |
+
+`HumanTask.HumanAnswerInvalid` is the separate refusal an answer earns before it
+can consume durable storage, with `answer_invalid` for an answer outside the
+durable JSON boundary and `answer_not_open` for an attempt that is not waiting.
+
+`maxAttempts` defaults to `HumanTask.defaultMaxAttempts`, which is `10`.
+
+## Put a deadline on it
+
+`timeoutMs` is how long the question stays open across every attempt. It races
+the answer against one `DurableClock` per task through
+`DurableDeferred.raceAll`, and the race parks and settles on whichever arrives
+first. Both shipped engines re-enter a parked race on the next drive,
+re-registering the raced deferreds against their persisted completions, so a
+deadline settles under the in-process engine and the SQLite engine store alike.
+
+A parked dispatch keeps its attempt row and its attempt number, so a question
+that waits out a person costs nothing against the action's retry budget.
+
+## Bounded by construction
+
+One question cannot grow a durable record without limit. The module exports every
+bound as a constant, including `maxAttemptBudget` (1000), `maxSchemaDepth` (32),
+`maxSchemaNodes` (512), `maxAnswerNodes` (10,000), `maxAnswerBytes` (256 KiB),
+`maxPromptBytes` (64 KiB), `maxOptions` (256), `maxDiagnosticChars` (512), and
+`maxRetainedRejectionChars` (8192).
+
+A value echoed into a rejection message is truncated with an explicit marker, and
+the retained `rejections` array records how many further rejections it omitted.
+Only the accumulated array is capped: each per-attempt journal step still records
+its own full reason, so the record shows what was actually said.
+
+## Related pages
+
+- [Wait for an external signal](./wait-for-an-external-signal.md): the wait point
+  and token machinery this is built on.
+- [Suspension and replay](../concepts/suspension-and-replay.md): what the
+  `approval` park does to the run.

package/docs/guides/build-a-body.md

@@ -0,0 +1,161 @@
+---
+title: "Compose a body from branches and fan-out"
+description: "Sequence steps, fan out and join, bound concurrency, decide between two continuations, and recover from a typed failure, all as static topology."
+sidebar:
+  order: 2
+---
+
+A body is written in [`@smthrs/plan`](/api/plan)'s `Node` combinators. This guide
+builds one release gate out of them: two checks in parallel, a report that joins
+them, a decision, and a recovery arm.
+
+Every combinator here is evaluated once, at plan time. Nothing in this file runs
+a step.
+
+## Declare the steps
+
+```ts
+import { Action, Flow } from "@smthrs/flow"
+import { Node } from "@smthrs/plan"
+import * as Schema from "effect/Schema"
+
+export class GateFailed extends Schema.TaggedError<GateFailed>()(
+  "release/GateFailed",
+  { reason: Schema.String }
+) {}
+
+const Lint = Action.make("release/Lint", {
+  payload: { target: Schema.String },
+  success: Schema.String,
+  error: GateFailed
+})
+
+const Types = Action.make("release/Types", {
+  payload: { target: Schema.String },
+  success: Schema.String,
+  error: GateFailed
+})
+
+const Report = Action.make("release/Report", {
+  payload: { lint: Schema.String, types: Schema.String },
+  success: Schema.String
+})
+
+const Ship = Action.make("release/Ship", {
+  payload: { report: Schema.String },
+  success: Schema.String
+})
+
+const Explain = Action.make("release/Explain", {
+  payload: { reason: Schema.String },
+  success: Schema.String
+})
+```
+
+## Fan out, then join
+
+`Node.all` settles its members concurrently and answers a record keyed by member
+name. Reading a field off the result records a reference path, so the join is an
+ordinary step that receives real strings:
+
+```ts
+const checks = (target: string) =>
+  Node.all({
+    lint: Lint.call({ target }),
+    types: Types.call({ target })
+  })
+
+const report = (target: string) =>
+  checks(target).pipe(
+    Node.bindPlanned((settled) => Report.call({ lint: settled.lint, types: settled.types }))
+  )
+```
+
+`settled.lint` is a `Planned<string>`, not a string. Pass it into a payload;
+never build a message out of it. The fan-in is a step for that reason: an action
+that receives two strings, not a function in the body that tries to concatenate
+placeholders.
+
+`Node.all` fixes its width at plan time. To bound concurrency, use one `Node.all`
+per batch and give the next batch the previous batch's result as payload. The
+reference is what sequences them, and an operator reading the plan sees exactly
+how many steps can be in flight.
+
+## Decide between two continuations
+
+`Node.branch` stores both arms. The predicate is digested and evaluated at run
+time on the real value; the arms are built once, here:
+
+```ts
+const gate = (target: string) =>
+  report(target).pipe(
+    Node.branch({
+      if: (text) => text.includes("clean"),
+      then: (text) => Ship.call({ report: text }),
+      else: (text) => Explain.call({ reason: text })
+    })
+  )
+```
+
+Both arms contribute their requirements to the node, because both are topology
+the plan carries. A run takes one of them, but which one is not known until the
+predicate sees the real value.
+
+Write the decision as a `branch`, not as an `if` in the body. An `if` on a
+planned value cannot read it, and an `if` on the payload is fine but produces a
+plan that no longer describes the alternative.
+
+## Recover from a typed failure
+
+`Node.catch` is failure topology. With an `error` schema it handles only the
+failures the schema accepts and leaves the rest in the node's error type:
+
+```ts
+export const Gate = Flow.make("release/Gate", {
+  payload: { target: Schema.String },
+  success: Schema.String,
+  body: ({ target }) =>
+    gate(target).pipe(
+      Node.catch({
+        error: GateFailed,
+        onFailure: (failure) => Explain.call({ reason: failure.reason })
+      })
+    )
+})
+```
+
+Without an `error` schema the whole domain error channel is handled and the
+resulting node has no declared error type. Interpreter refusals still propagate.
+The failure arm is built once at plan time against a planned error placeholder,
+so `failure.reason` is a reference, like every other planned field.
+
+## Compute, and order
+
+Two smaller combinators finish the vocabulary:
+
+- `Node.map(node, f)` computes on a step result. The function is digested and
+  runs later, on the real value. This is where computation belongs, and only
+  computation: a `map` that decides what happens next is a `branch` written
+  wrongly.
+- `Node.priority(node, n)` orders ready work, higher first. It changes latency
+  and nothing else, and it never enters key material, so raising it cannot
+  invalidate a recorded result. Children inherit it lexically, and a child that
+  states its own keeps it.
+
+```ts
+const urgent = Node.priority(Lint.call({ target: "release" }), 9)
+```
+
+## When the shape depends on a result
+
+Every combinator above fixes its topology before the run. When the shape itself
+depends on something a step produced, that is a new round: settle this one and
+carry the data in the next round's payload. See
+[Trampoline rounds](../concepts/trampoline-rounds.md).
+
+## Related pages
+
+- [Bodies are plans](../concepts/bodies-and-plans.md): the rules behind the
+  vocabulary, and the refusals a bad body earns.
+- [Inspect the plan a body builds](./inspect-the-plan.md): read the nodes and
+  edges this body produces without running it.