@smthrs/control 0.0.0-stage → 1.0.0-rc.4

package/docs/concepts/projections.md

@@ -0,0 +1,203 @@
+---
+title: "Journal projections"
+description: "How watch turns committed journal entries into ControlEvent values, why a cursor scopes to one run, how the snapshot hands off to the live tail, and which deltas the plane derives rather than records."
+sidebar:
+  order: 4
+---
+
+`watch` is a projection, not a bus. It reads committed journal entries and maps
+each one onto a `ControlEvent`:
+
+```ts
+interface ControlEvent {
+  readonly sequence: number
+  readonly kind: string
+  readonly runId?: string | undefined
+  readonly occurredAt: number
+  readonly payload: Json
+}
+```
+
+A consumer that subscribes after the fact still receives what it missed,
+because the cursor is durable and the source is a table rather than a live
+fan-out that forgets.
+
+## Partitions, and why a cursor needs a run
+
+The journal is partitioned. Every run is a partition, and each plan gets one of
+its own under the id `plan:<planId>`. Sequences are partition-local: the plan
+partition and every run partition each start at 0.
+
+One scalar cursor applied to all of them would therefore skip every lower
+unseen sequence in every partition but the one the cursor came from. So
+`watch` refuses either `afterSequence` or `afterCursor` without a `runId`:
+
+```text
+InvalidInput: afterSequence: a watch cursor resumes one run, so it requires runId
+```
+
+Exactly-once resumption is a promise about a scoped watch, and only about a
+scoped one.
+
+## Snapshot, follow, and the handoff between them
+
+`WatchFilter.follow` selects the delivery mode.
+
+- `follow: false` asks for a finite snapshot of what is durable when the
+  request is handled. The stream ends. This is the mode a test and a one-shot
+  reader want.
+- Omitting `follow` opens the live stream a UI subscribes to. It does not end.
+
+The live stream is a handoff, not a deduplicated overlap. The projection
+subscribes to journal changes first, then pins a high-water sequence for each
+partition it can see. A row committed at or below its partition's mark is read
+from the finite snapshot; a row above it is read from the buffered tail. An
+entry from a partition the snapshot never read has no mark and passes straight
+through.
+
+The unscoped watch reads eight partition snapshots at a time and keeps one
+reserved slot so the live tail is never starved behind snapshot work. An
+unbounded merge would read every partition of an unbounded database at once,
+which is an allocation a remote watcher could force.
+
+## What the plane writes
+
+These entries are the control plane's own records. With the SQL runtime and
+journal on the same database, each commits inside the same transaction as the
+state change it describes.
+
+| Kind                                                                   | Written by                                          | Partition           |
+| ---------------------------------------------------------------------- | --------------------------------------------------- | ------------------- |
+| `control.plan.created`                                                 | `plan`, on creation or repair of a missing entry    | `plan:<planId>`     |
+| `control.approval.approved`, `control.approval.denied`                 | `approve`, `deny`                                   | the plan or the run |
+| `control.run.accepted`                                                 | `run`, once the row exists                          | the run             |
+| `control.run.running`                                                  | `run`, when the executor took the launch            | the run             |
+| `control.run.pending`                                                  | `run`, when it did not                              | the run             |
+| `control.run.resumed`                                                  | an approval on a node target, naming the delegation | the run             |
+| `control.run.resume`                                                   | `resume`, carrying the principal and the reason     | the run             |
+| `control.run.cancel-requested`                                         | `cancel`, carrying the principal and the reason     | the run             |
+| `control.run.cancelled`, `control.run.completed`, `control.run.failed` | `cancel` and launch settlement                      | the run             |
+| `control.signal.delivered`                                             | `signal`                                            | the run             |
+| `control.steer.enqueued`                                               | `steer`                                             | the run             |
+| `control.steer.woke`                                                   | `steer`, when it ended a park                       | the run             |
+| `control.monitor.beat`, `control.monitor.healed`                       | `Monitor.run`                                       | the run             |
+
+`plan` commits the card, idempotency key, approval token and creation entry in
+one journal transaction. A keyed retry returns the stored card and checks its
+partition for the creation entry. If an older write left that entry missing,
+the retry appends it once before returning.
+
+The memory runtime publishes one card per key, including concurrent requests.
+It cannot roll back its maps with a journal transaction. A keyed retry repairs
+a failed creation entry while retaining the original card.
+
+## What the plane derives
+
+Two kinds are computed from entries other packages wrote, and are emitted
+beside their source entry rather than recorded:
+
+| Derived kind              | Derived from                                                  | Module     |
+| ------------------------- | ------------------------------------------------------------- | ---------- |
+| `control.run.lineage`     | `flows.engine.run-decision`, `flows.time-travel.fork-created` | `Lineage`  |
+| `control.steer.delivered` | `flows/notifications/Promoted`                                | `Steering` |
+
+Deriving rather than re-recording is what keeps the halves honest. The boundary
+that delivers a steer runs in the agent process, not this one, so a control
+plane that wrote its own delivery record would be asserting a fact it did not
+observe.
+
+Each derived event carries its source sequence. `watch` also assigns a
+composite `cursor` that distinguishes members of an expansion. Checkpoint
+`event.cursor` and resume with `afterCursor` to retain unconsumed deltas.
+`afterSequence` skips the whole source entry, including its deltas. Expansion
+runs after the snapshot-to-tail handoff.
+
+`Lineage.derive`, `Lineage.expand`, `Steering.derive`, and `Steering.expand`
+are exported, so a client reading the journal directly reaches the same
+conclusions the server does.
+
+The two foreign event types are named as strings rather than imported. A
+control plane reads journals, not engines, and one that depended on the engine
+could not project a journal a different engine wrote.
+
+## Where to go next
+
+- [Watch a run's events](../guides/watch-a-run.md): the projection as a task.
+- [Run lineage](./lineage.md): what a `control.run.lineage` delta says.
+- [Steer a running agent](../guides/steer-a-run.md): the two moments a steer
+  has, and their two writers.
+
+## Versioned lifecycle and approval producer contract
+
+`ControlFacts` exports the version-1 control producer contract and the shared
+pure run/approval fold consumed by gateway snapshots and subscriptions. This
+version is independent of the harness transcript's `journalVersion` and of
+journal cursor generations. Existing event kind names and source identities
+remain unchanged; old consumers can continue reading their original fields.
+
+A lifecycle fact adds `{factVersion: 1, baseline, run}` to the usual event
+payload. `run` is the complete, detached `RunSummary` returned by that fenced
+control write. `control.run.accepted` starts a `created` baseline. A first
+upgraded status, resume claim, pending handoff, or reconciliation starts a
+`legacy` baseline at its own committed sequence. Earlier history is retained
+without claiming that lost transitions have been reconstructed. Unknown or
+missing lifecycle facts invalidate continuous coverage until another complete
+snapshot establishes a new legacy baseline. No read fabricates migration events.
+
+`ControlFacts.commitRun` commits a control write and its fact with
+`Journal.transact`. `AgentSession` uses it for terminal/parked status and resume
+claims; failure does not leave a newer status with no event. `ControlLive`'s
+normal admission, resume, steer, and cancellation transactions carry the same
+facts, and its exceptional launch settlement and terminal reconciliation also
+join a journal transaction. Low-level `ControlRuntime` calls remain available
+for ownership mechanics and legacy integrations; calling them outside these
+producer boundaries does not establish event coverage.
+
+`commitApprovalRequest` validates and captures the full request, then commits
+its token registration and `control.approval.requested` event together. A
+resolved token does not emit a new pending request. Decisions add
+`{factVersion: 1, tokenId, approvalTarget}` to their existing payload and commit
+with the decision, grant, idempotency receipt, and durable node-resume intent.
+The pure fold joins current requests and decisions by run/request identity and
+digest. Repeated requests do not reopen a decision. Legacy records retain their
+historical read contract; only legacy requests are eligible for unnamed legacy
+decision fallback.
+
+A request a runaway guard makes carries an optional `incident`
+(`ControlFacts.GuardIncident`): its `Runaway` or `Stuck` classification, the
+guard `source` (`tokens`, `usd`, `latency`, `model-call`, `tool-call`, `cell`), the
+triggering `message`, and the numbers frozen when it tripped (`used`,
+`reserved`, `max`, `next`, the `allowance` Continue authorizes, and the
+timed-out `subject`). A host that re-parks the run reuses the recorded request
+and its incident rather than measuring again.
+
+These atomic guarantees require the SQL control runtime and journal to share
+the same database/writer, as the production control composition does. The
+in-memory test runtime has no transactional rollback protocol. `SqlJournal`
+publishes committed rows after the owning writer's COMMIT; a failed insert or
+outer transaction publishes no fact. Followers also replay from disk, so a
+process dying after commit and before an in-process notification does not lose
+the recorded transition.
+
+This is a control-plane boundary, not a claim that all runtime state is now a
+control-event fold. Native lifecycle observations commit with their own fenced
+state in the engine database. The durable engine bridge copies those facts and
+an authenticated `control.engine.bound` root binding into the control journal.
+Gateway snapshots and subscriptions use the shared `ExecutionFact` fold to
+compare that evidence with the executor's coherent root/current-round view.
+The separate `executionProvenance` reports native `events`, `legacy-observation`
+or `unverified-observation`; `lifecycleProvenance` still labels the executor
+overlay `engine-observed` rather than calling it control replay. Bridge lag,
+missing bindings, generation gaps and unknown versions retain explicit fallback.
+The two databases do not become one transaction, and operational ownership,
+heartbeats and protected resolver credentials retain their native authorities.
+
+Authorized native cell calls also commit `flows.harness.call-fact.v1` invocation
+and controller-result facts in their owning action transactions. The immutable
+native journal is their outbox through that same bridge. Shared call projections
+prefer committed facts over matching identified telemetry while preserving
+display identities. Legacy trace producer hashes remain unchanged; unidentified
+calls keep their limited fallback, and low-level custom ports without these
+annotations remain legacy. Model deltas, printed output and other trace records
+still use the best-effort channel. Durable call facts do not reconstruct missing
+trace history or promise exactly-once external effects.

package/docs/concepts/receipts.md

@@ -0,0 +1,128 @@
+---
+title: "Receipts and idempotency"
+description: "The five receipts a control mutation can answer, the bounded identity boundary every mutation crosses first, and why cancel and resume read a run's terminality before replaying a recorded receipt."
+sidebar:
+  order: 2
+---
+
+Every control mutation answers a `Receipt` rather than throwing on a second
+ask. A receipt is the plane's whole answer to "did my request take effect, and
+what happened to it?".
+
+| Receipt          | Meaning                                                                                 |
+| ---------------- | --------------------------------------------------------------------------------------- |
+| `Accepted`       | This call admitted the mutation. Carries `receiptId`, and `runId` when a run exists.    |
+| `AlreadyApplied` | An earlier call under this key admitted the mutation. Carries the same `runId`.         |
+| `Parked`         | The plan is waiting for an approval. Carries `planId` and `status: "waiting-approval"`. |
+| `Conflict`       | The key names a different intent than the one it was first used for. Carries a message. |
+| `Terminal`       | The run had already settled. Carries `runId` and the status it settled with.            |
+
+`plan` is the exception: it returns a `PlanCard`, because a plan is a value to
+review rather than an outcome to acknowledge.
+
+## The identity boundary
+
+Before a mutation waits on anything, it copies its own input and decodes the
+copy. Nothing downstream ever sees the caller's object.
+
+The copy admits only enumerable own data properties, so an accessor, a
+`toJSON`, a sparse array, a symbol key, a cycle, a non-plain object, or
+ill-formed text is refused with `InvalidInput` before a collaborator is
+touched. That is not defensive tidying: a getter that returns one value to the
+fingerprint and another to the write is the whole exploit.
+
+The copy is also bounded:
+
+| Bound                               | Value                             |
+| ----------------------------------- | --------------------------------- |
+| Canonical bytes                     | 4 MiB                             |
+| Nesting depth                       | 128                               |
+| Total JSON values                   | 100,000                           |
+| Total array items and object fields | 100,000                           |
+| Idempotency key length              | 1 to 1,024 well-formed characters |
+
+## What a key identifies
+
+The durable key is the operation, the caller's key, and, when a principal is
+present, a digest of that principal's stable `kind` and `id`. The stamped
+`stampedAt` is deliberately excluded: it is a wall clock, and keeping it made a
+bearer authenticated retry of one cancel look like a different mutation under
+the same key.
+
+Beside the key the runtime stores a **fingerprint**: a canonical SHA-256 digest
+of the operation, the actor's `id` and `kind`, and the decoded mutation with
+its two server-stamped `principal` fields removed. A second call whose
+fingerprint matches replays the recorded receipt. A second call under the same
+key with a different fingerprint answers `Conflict`, which is the honest answer
+to "this key already means something else".
+
+Only `input.principal` and `input.message.principal` are removed, and only at
+their own depth. A `principal` nested inside a signal payload is part of the
+fingerprint, because two signals that differ only there are two different
+signals.
+
+## Replay, and the two mutations that do not replay it
+
+For a mutation that changes something once, the recorded receipt is everything:
+it is the proof the change was made, and replaying it is the whole guarantee.
+
+`cancel` and `resume` are different, because their receipt is an answer _about
+a run_, and the run moves on afterwards. Both read the run's terminality first,
+before the idempotency lookup:
+
+- `cancel` runs with replay disabled. A second ask re-executes, reads the run,
+  and answers what is true now. A replayed answer would describe the moment of
+  the first ask, so a caller could keep cancelling a run that never moved and
+  keep being told it was cancelled.
+- `resume` reads terminality before the replay for the same reason. Asking to
+  restart a completed run must answer `Terminal`, not `AlreadyApplied`, which
+  describes an earlier call and says nothing about the run you named.
+
+Cancellation needs no receipt to be idempotent. The run's own terminality is a
+stronger guarantee, and it is what the second ask reads.
+
+## Run admission precedes execution
+
+The run row, approval facts, and idempotency receipt commit before the plane
+calls the executor. `Accepted` proves admission; the run's current status proves
+whether execution started or finished. Another connection can read the committed
+run as soon as the executor receives it.
+
+If the executor refuses the launch, the plane records the run as failed and
+retains its admission receipt. Repeating the same key returns `AlreadyApplied`
+for that run. An explicit retry uses a new key. A failed admission commit never
+reaches the executor.
+
+If the admitting process dies after the commit and before the executor takes
+the run, the run stays `accepted` under that process. Repeating the same key
+once the process's heartbeat lease has lapsed claims the run and launches it,
+then answers `AlreadyApplied` as usual. A live admitter keeps its run.
+
+## A parked receipt is not recorded
+
+`run` against an undecided plan answers `Parked` and records nothing. That is
+what lets the [Quickstart](../quickstart.md) launch, park, approve, and launch
+again under one key: the key was never spent on the refusal.
+
+## Where a key comes from
+
+A caller chooses it, and the choice is a contract with itself:
+
+- A CLI or an operator uses something that names the intent:
+  `deploy:v1.4.0`, `cancel:run-17`.
+- A [channel](../guides/ingest-a-webhook.md) uses the platform's own delivery
+  id, namespaced by the channel, so a webhook redelivery is the same mutation.
+- A [monitor](../guides/monitor-runs.md) uses
+  `monitor:<monitorId>:<remedy>:<runId>:<beat>`, so two monitors watching one
+  run never share a key.
+
+Reusing a key for a different intent is a caller mistake the plane reports
+rather than absorbs.
+
+## Where to go next
+
+- [Ownership, fences, and claims](./ownership.md): the other reason a mutation
+  refuses.
+- [Cancel a run, and restart one](../guides/cancel-and-resume.md): the two
+  verbs that read terminality first.
+- [Troubleshooting](../troubleshooting.md): what each refusal means in practice.

package/docs/guides/approvals.md

@@ -0,0 +1,284 @@
+---
+title: "Gate work behind an approval"
+description: "Take a plan approval before a run starts, and a node approval inside a run that already started: what each gate pins, how a step registers its own request, and what a decision restarts."
+sidebar:
+  order: 1
+---
+
+Two gates carry an approval, and they are different mechanisms worth keeping
+apart. A **plan approval** decides whether a run starts. A **node approval**
+decides something inside a run that already started.
+
+Both are decided with the same two verbs, `approve` and `deny`, and both pin
+what was reviewed with a digest and an envelope, so a decision cannot be
+re-aimed at a different request afterwards.
+
+## Who may decide
+
+An approval payload identifies the request; it is not permission to decide it.
+Authentication supplies a trusted `Principal`, while `ApprovalAuthority` supplies
+the independent host policy. `Control.approve` and `deny` check that policy before
+target reads or receipt replay, and the runtime checks it again at resolution.
+Refusal is `Unauthorized`; unavailable policy storage fails closed with
+`PersistenceError`.
+
+The default policy recognizes only the fixed local identity `local/operator`.
+The memory adapter's own default also recognizes its `memory/test` identity, and
+no production policy does. A custom `principal` option,
+an actor's `kind`, or a valid bearer credential does not delegate approval.
+Hosts may replace the policy explicitly:
+
+```ts
+import * as ApprovalAuthority from "@smthrs/control/ApprovalAuthority"
+import * as SqlControlRuntime from "@smthrs/control/SqlControlRuntime"
+import { Effect } from "effect"
+
+const runtime = Effect.gen(function*() {
+  const approvalAuthority = yield* ApprovalAuthority.make([
+    {
+      principal: { id: "local", kind: "operator" },
+      scopes: ["once", "run", "remembered"],
+      targets: ["Plan", "Node"]
+    },
+    {
+      principal: { id: "release-bot", kind: "agent" },
+      scopes: ["once"],
+      targets: ["Node"]
+    }
+  ])
+  return yield* SqlControlRuntime.make({ approvalAuthority })
+})
+```
+
+Delegations bind an exact identity tuple, target kind, and approval scope. Scopes
+are not hierarchical. A delegated actor may deny its listed target kinds without
+installing any grant. Delegation is reusable: `scopes: ["once"]` permits
+once-scoped grants; it is not a single-use delegation. A custom host policy must
+enforce expiry, revocation, or one-use delegation when needed.
+A custom `ApprovalAuthority.Service` can additionally
+restrict specific runs, plans, or envelopes. Keep that policy bounded and safe
+inside the writer transaction; never invoke Control recursively from it.
+
+Transport adapters must authenticate identities and overwrite caller-supplied
+principal fields. Direct Control/runtime references and database access are
+trusted host capabilities, not endpoints for untrusted input. In particular,
+`installBulkGrant` is a storage port, not an authorization API. Use Control for
+an atomic durable decision, grant, journal entry, and receipt.
+
+Default MCP surfaces omit approval decisions and auto-approving starts. The
+compatibility server requires both host tool exposure and a separately delegated
+agent identity. Delegating an agent to approve is automated approval, not an
+independent human review. None of these checks sandboxes a caller that already
+has arbitrary host shell, code execution, or direct database write access.
+On loopback, `smthrs serve` prints a fresh per-session approval token to
+stderr (even with `--quiet`). Send `Authorization: Bearer <token>` to approve,
+deny, or answer a human wait over `/rpc` or `/projections`, HTTP or WebSocket.
+Calls without that token retain read access, but cannot decide approvals.
+Keep the token away from agents: a caller holding it has operator approval authority.
+A network bind still requires the configured bearer credential for all protected calls.
+
+## Gate the launch: a plan approval
+
+`plan` produces the reviewable card. `run` against an undecided plan starts
+nothing and says so:
+
+```ts
+import { Control } from "@smthrs/control/Control"
+import * as Effect from "effect/Effect"
+
+const gate = Effect.gen(function*() {
+  const control = yield* Control
+
+  const card = yield* control.plan({ flowId: "ops/Deploy", input: { build: "v1.4.0" } })
+
+  const launch = {
+    _tag: "Plan" as const,
+    planId: card.planId,
+    digest: card.digest,
+    envelope: card.envelope
+  }
+
+  // { _tag: "Parked", planId, status: "waiting-approval" }
+  yield* control.run({ ...launch, idempotencyKey: "deploy:v1.4.0" })
+
+  // The card carries the exact approval payload, so a reviewer resubmits it
+  // unchanged rather than reconstructing authority on the client.
+  yield* control.approve(card.approval)
+
+  // Now the same call launches.
+  return yield* control.run({ ...launch, idempotencyKey: "deploy:v1.4.0" })
+})
+```
+
+Deny it instead and the launch refuses with `PlanDenied` rather than parking.
+A denied plan cannot be revived: create and approve a new plan.
+
+### What the card pins
+
+`PlanCard.digest` covers the flow id, the decoded input, the envelope, the
+deploy-class flag, and the digest of the persisted plan. `nodes` is the keyed
+node graph the plan phase produced, and it is part of the digest because
+"approve this flow with this input" and "approve this graph of keyed work" are
+different promises: a change that re-keys a node changes what will run, and an
+approval taken against the old graph must not authorize the new one. A host
+that has not built a graph reports an empty one and loses nothing.
+
+`Envelope` is the authority itself: the capabilities, the collaborator flows,
+the budget, and the placement being granted.
+
+| Submitted value differs from the stored one | Failure                                                               |
+| ------------------------------------------- | --------------------------------------------------------------------- |
+| `digest`                                    | `PlanDigestMismatch`, carrying `expected` and `actual`                |
+| `envelope`                                  | `EnvelopeMismatch`, compared by canonical bytes rather than key order |
+
+`GrantScope` says how long the grant lasts: `once`, `run`, or `remembered`. The
+card defaults to `run`.
+
+## Gate a step: a node approval
+
+A node approval belongs to a run that already exists, and the _step_ registers
+it. Nothing outside the run asks for it, so `approve` can only decide a request
+a step actually made.
+
+The step registers the token and handles its explicit `Pending`, `Approved`, or
+`Denied` tag. Only approval may open the gate:
+
+```ts
+import * as ControlRuntime from "@smthrs/control/ControlRuntime"
+import type * as ControlSchema from "@smthrs/control/ControlSchema"
+import { Action, DurableDeferred, FlowRuntime } from "@smthrs/flow"
+import * as Effect from "effect/Effect"
+import * as Schema from "effect/Schema"
+
+/** The step that asks, declared like any other. */
+const Clearance = Action.make("ops/Clearance", {
+  payload: { requestId: Schema.String },
+  success: Schema.String,
+  error: Schema.Union([ControlRuntime.ApprovalPending, ControlRuntime.ApprovalDenied])
+})
+
+/**
+ * The wait point the park awaits. Nothing ever completes it, which is the
+ * point: an approval is not a value arriving, it is a decision recorded
+ * somewhere else. The wake is the run being re-driven, and the step reads the
+ * decision off the token rather than off this deferred.
+ */
+const clearanceGate = DurableDeferred.make("Approval/ship-clearance", { success: Schema.Json })
+
+/** The exact request this step registers and an operator decides. */
+const request = (runId: string): Extract<ControlSchema.ApprovalTarget, { readonly _tag: "Node" }> => ({
+  _tag: "Node",
+  runId: runId as ControlSchema.RunId,
+  requestId: "ship-clearance",
+  digest: "ops/Ship:clearance",
+  envelope: { capabilities: [], flows: [], budget: {} }
+})
+
+const clearance = Clearance.toLayer(({ requestId }) =>
+  Effect.gen(function*() {
+    const instance = yield* FlowRuntime.FlowInstance
+    const runtime = yield* ControlRuntime.ControlRuntime
+    const target = request(instance.executionId)
+    let token = yield* Effect.orDie(runtime.registerApproval(target))
+    if (token._tag === "Pending") {
+      yield* FlowRuntime.annotateWaiting({ reason: "approval", token: requestId })
+      yield* DurableDeferred.await(clearanceGate)
+      // Completing a wait point is not approval. Read the durable answer.
+      token = yield* Effect.orDie(runtime.registerApproval(target))
+    }
+    return (yield* ControlRuntime.requireApproved(token)).tokenId
+  })
+)
+```
+
+`registerApproval` is idempotent. It creates the token on the first attempt and
+answers the existing one afterwards. `requireApproved` succeeds only for
+`Approved`, fails with `ApprovalDenied` on denial, and fails with
+`ApprovalPending` if no decision exists. Include these errors in the enclosing
+flow's error schema. Use `Node.andThen(clearance, next)` to gate all of `next`.
+Both terminal tags carry `decisionPrincipal` and `decidedAt`; `Approved` also
+carries the installed grant's `scope`. A denied token cannot be changed to
+approved. A changed target digest or envelope is refused.
+
+The token describes a decision; it is not an authentication credential and
+`requireApproved` does not install permissions or establish who may approve.
+Keep approval authority separate from permission to execute a workflow.
+
+### Upgrading an unfinished run
+
+Migration 6004 adds explicit durable decisions. Old pending tokens remain
+pending. An old resolved token did not retain whether it was approved or
+denied, so reads fail with an actionable `PersistenceError` instead of guessing
+from grants or journal projections. Preserve the database for review and use a
+new run with a new approval request. This is refusal, not automatic migration of
+unfinished executions. The action and flow error schema changes also require
+newly planned/approved work; they do not retrofit old cached action results.
+
+The complete example, with the two drives around the decision, is
+[`examples/src/18-approval-and-signal.ts`](https://github.com/smithersai/smithers/blob/main/examples/src/18-approval-and-signal.ts).
+
+### Decide it from outside the run
+
+```ts
+const receipt = yield * control.approve({
+  target: request("run-17"),
+  scope: "once",
+  idempotencyKey: "approve:ship-clearance"
+})
+```
+
+The node digest is deliberately not the plan's. The two gates are separate
+mechanisms, and a run that was never planned still has steps worth gating.
+
+## What a decision does
+
+For a new decision, the adapter contract follows this order:
+
+| Step                           | Plan target                                                                    | Node target                                                 |
+| ------------------------------ | ------------------------------------------------------------------------------ | ----------------------------------------------------------- |
+| Authenticate and authorize     | Authenticate the principal; `authorizeApproval` before reads or receipt replay | same                                                        |
+| Look the token up              | `lookupApproval` refuses an unknown or already-resolved token                  | same                                                        |
+| Resolve the token              | `resolveApproval` exactly once, with an authority recheck                      | same                                                        |
+| Install the grant, on approval | `installBulkGrant` with the submitted envelope and scope                       | same                                                        |
+| Journal the decision           | `control.approval.approved` or `.denied` on `plan:<planId>`                    | the same kinds, on the run                                  |
+| Record the restart             | nothing to restart                                                             | records a resume delegation, journals `control.run.resumed` |
+
+Commit the decision, grant, journal entry, receipt, and any node resume delegation
+atomically. Resolution must not require an installed grant or a flushed journal
+decision. An authority refusal at resolution prevents grant installation.
+
+A decision on a node target restarts the run the ask parked, in the same call.
+Nothing else wakes that run: without the restart it would sit at
+`waiting-approval` holding a decision it never reads, and a denial it never
+learns about would decide nothing.
+
+The restart is _recorded_, not performed, and the deciding plane does not claim
+the row. See [a resume is a delegation before it is a claim](../concepts/ownership.md).
+
+A decision on a run that has already settled answers `Terminal` and decides
+nothing, read before the idempotency replay so the answer describes the run
+rather than an earlier call.
+
+## Refusals
+
+| Failure              | Cause                                                                    |
+| -------------------- | ------------------------------------------------------------------------ |
+| `Unauthorized`       | The authenticated caller lacks approval authority for this target/scope. |
+| `PlanNotFound`       | No plan or node token with this id. Its `message` names the next action. |
+| `PlanDenied`         | The plan was denied. Create and approve a new one.                       |
+| `PlanDigestMismatch` | The submitted digest is not the stored one.                              |
+| `EnvelopeMismatch`   | The submitted envelope is not the stored one.                            |
+| `AlreadyResolved`    | This token already carries a terminal decision.                          |
+| `RunNotFound`        | A node target names a run this plane cannot find.                        |
+
+`AlreadyResolved` is also the durable evidence that a decision stuck: a second
+`lookupApproval` on a decided token refuses rather than answering.
+
+## Where to go next
+
+- [Receipts and idempotency](../concepts/receipts.md): why the launch and the
+  retry share one key.
+- [Ownership, fences, and claims](../concepts/ownership.md): what the recorded
+  resume reaches.
+- [Plan, approve, run on smithers.sh](/docs/guides/plan-approve-run/): the same
+  gate from the CLI.