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

package/docs/guides/cancel-and-resume.md

@@ -0,0 +1,162 @@
+---
+title: "Cancel a run, and restart one"
+description: "Stop a run you may not own and restart one nobody is driving: what each receipt means, why both verbs read terminality first, and how a cancel reaches a run in another process."
+sidebar:
+  order: 6
+---
+
+`cancel` and `resume` are the two lifecycle verbs, and they share a shape:
+a run id, a caller-stated `reason`, and an idempotency key. Both record who
+asked, and both read the run's terminality before anything else.
+
+## Cancel a run
+
+```ts
+import { Control } from "@smthrs/control/Control"
+import * as Effect from "effect/Effect"
+
+const cancel = Effect.gen(function*() {
+  const control = yield* Control
+  return yield* control.cancel({
+    runId: "run-17",
+    reason: "budget",
+    idempotencyKey: "cancel:run-17"
+  })
+})
+```
+
+The `reason` is free text and it is recorded on the
+`control.run.cancel-requested` entry the mutation writes, then projected back
+onto `RunSummary.cancellation`. An operator reading a cancelled run a week
+later asks "why", and a control plane that never carried the answer cannot
+produce one afterwards.
+
+### What comes back
+
+| Receipt                          | Meaning                                                    |
+| -------------------------------- | ---------------------------------------------------------- |
+| `Terminal` with the run's status | The run settled, either before this call or because of it. |
+| `Accepted`                       | The request is durable and a live peer will act on it.     |
+
+A cancel that this process could interrupt answers `Terminal` naming
+`cancelled`, because the run really did settle in this call. A cancel against a
+run a live peer is holding answers `Accepted`: the request is on the engine
+row, and the owner stops the run at its next cancel poll.
+
+`cancel` deliberately does not replay its recorded receipt. Its answer is a
+statement about a run, and the run moves on. See
+[Receipts and idempotency](../concepts/receipts.md).
+
+### How a cancel reaches another process
+
+Fibers are process-local, so an interrupt only stops a run this process is
+driving. The durable half travels through the executor:
+
+1. `ControlExecutor.requestCancel` writes `cancel_requested_at_ms` on the
+   engine row, inside the mutation's transaction. An engine that refuses rolls
+   the whole cancel back, because a control row that says `cancelled` over an
+   engine row that is still running is the one state an operator cannot
+   recover from.
+2. The attribution entry is written, unless the executor answered
+   `already-requested`, which means the column was already set and the record
+   already exists.
+3. The local fiber is interrupted. A parked run has no owner, so the cancelling
+   process claims the park itself in order to end it.
+4. `ControlExecutor.settleCancelledPark` runs _after_ the mutation commits, so
+   the parked execution is finished before the process that asked goes away.
+   Driving a run re-enters the engine, whose writes would wait on the writer
+   the transaction holds.
+
+An executor that answers with a `CancelTerminal` reports that the engine row
+had already settled. Nothing was cancelled, so no attribution is written, and
+the control row is reconciled onto the engine's own status instead.
+
+## Restart a run
+
+```ts
+const resumed = yield * control.resume({
+  runId: "run-17",
+  reason: "operator retry",
+  idempotencyKey: "resume:run-17"
+})
+```
+
+`run` with a `Resume` input is the same operation:
+
+```ts
+yield * control.run({ _tag: "Resume", runId: "run-17", idempotencyKey: "resume:run-17" })
+```
+
+One resume, one implementation. The two spellings exist because RPC clients and
+the CLI reach for different ones.
+
+### What comes back
+
+| Receipt                 | Meaning                                                                     |
+| ----------------------- | --------------------------------------------------------------------------- |
+| `Terminal`              | The run had already settled. Nothing to restart.                            |
+| `Accepted`              | The run was claimed, or the restart was recorded for the host that owns it. |
+| `Accepted` + `handedTo` | A live host parked the run. The restart was handed to that host.            |
+| `AlreadyApplied`        | An earlier call under this key already restarted it.                        |
+
+`ClaimLost` is the failure, and it names a real peer: a run at `running` or at
+the `accepted` a claim writes is being held by a live process, so there is
+nothing to restart and pretending otherwise would hide the peer.
+
+A run the _engine_ created, a child, a fork, or a later trampoline round, keeps
+its own driver. Both public resume spellings use `scope: "launched"` and journal
+`control.run.resume`; they leave engine-created rows unclaimed to preserve
+the continuation state. The caller or a journal subscriber must drive the
+execution, even when the plane claims a control-launched run. A run the caller
+claims creates no `pendingResumes` entry. An `Accepted` receipt does not
+establish that execution started.
+
+### A run a live host parked
+
+A detached host that parks a run, for example over children released when its
+lease lapsed during a stall, stays alive and keeps the run. Claiming that run
+would take its execution from the host. `resume` hands the restart to the host
+instead:
+
+1. The runtime refuses the claim with `ClaimLost` naming the host in
+   `parkedBy`.
+2. `resume` journals `control.run.resume` with `handedTo` set to that host,
+   then records a durable delegation whose `consent` is that entry's journal
+   sequence.
+3. The receipt is `Accepted` with `handedTo`. The caller holds nothing to
+   drive.
+4. The host polls `pendingResumes` every second and takes the delegation up.
+   Because it carries consent, the host records the per-release retry
+   permission under that sequence, journals `control.run.claimed`, and
+   re-drives the run as an operator resume.
+
+An approval or a wake is background intent and never carries consent, and a
+later approval delegation keeps consent that no host has taken up yet. The
+permission covers the releases that exist when the host takes the delegation
+up. A later lease lapse is a new release, so it needs a new resume. A run whose
+parking host has exited is claimed by the caller as before.
+
+## What the CLI does
+
+[`smthrs runs cancel`](/cli/runs) and `smthrs runs cancel-all` both reach
+`cancel`; [`smthrs runs resume`](/cli/runs) reaches `resume`. Both record the
+principal the CLI authenticated, so `RunSummary.cancellation.principal` names a
+person rather than a process.
+
+`smthrs runs resume` keys each request by the run's latest park, so resuming a
+second park is a new request rather than a replay of the first. A run it claims
+is driven in the foreground until it settles. A run handed to its live host is
+not: the CLI waits up to 15 seconds for the host's `control.run.claimed` and for
+the run to leave its `released` park, then prints the receipt with the run's
+`status` and `waitingReason`. If the host does not take it up in that time, the
+command fails with `resume_not_taken_up`, naming the host's process. The
+request stays recorded for that host.
+
+## Where to go next
+
+- [Cancellation attribution](../concepts/cancellation.md): what the answer to
+  "who cancelled this" is built from.
+- [Ownership, fences, and claims](../concepts/ownership.md): why `ClaimLost` is
+  the right refusal.
+- [Connect an execution engine](./implement-an-executor.md): the four methods
+  these verbs call.

package/docs/guides/durable-storage.md

@@ -0,0 +1,147 @@
+---
+title: "Store control state in a database"
+description: "Compose SqlControlRuntime over a SQL database and the fenced run store: the layer stack, the migration order, the owner identity every claim is stamped with, and what sharing a database with the engine buys."
+sidebar:
+  order: 7
+---
+
+`ControlRuntime.layerMemory` models the production seams in a `Map`, and
+nothing it decides survives the process. `SqlControlRuntime` is the durable
+adapter: the same contract, over a SQL database and the fenced run store from
+[`@smthrs/run-store`](/api/run-store).
+
+## Compose the layer
+
+```ts
+import * as ControlLive from "@smthrs/control/ControlLive"
+import * as SqlControlRuntime from "@smthrs/control/SqlControlRuntime"
+import * as DurableWriter from "@smthrs/database/DurableWriter"
+import * as NodeDatabase from "@smthrs/database/node/NodeDatabase"
+import { NotificationQueue } from "@smthrs/notifications"
+import { Registry } from "@smthrs/registry"
+import { Migrations as RunStoreMigrations, RunStore } from "@smthrs/run-store"
+import * as Layer from "effect/Layer"
+
+const storage = RunStore.layer.pipe(
+  Layer.provideMerge(RunStoreMigrations.layer),
+  Layer.provideMerge(DurableWriter.layer()),
+  Layer.provideMerge(NodeDatabase.layer({ filename: "control.sqlite" }))
+)
+
+const controlPlane = ControlLive.layer.pipe(
+  Layer.provideMerge(
+    Layer.mergeAll(
+      SqlControlRuntime.layer({ owner: { hostId: "gateway", pid: process.pid, nonce: "boot" } })
+        .pipe(Layer.orDie),
+      NotificationQueue.layer,
+      Registry.layerNoop()
+    )
+  )
+)
+```
+
+`SqlControlRuntime.layer` requires `Crypto`, `DurableWriter`, `SqlClient`, and
+`RunStore`, and fails with `PersistenceError` if its migration cannot run.
+`layerWithStore` is the same layer with `RunStore.layer` already provided, for
+a composition that has no other use for the store.
+
+Build the storage once. `Layer.provideMerge` builds what it provides privately,
+so composing it twice hands the control plane its own empty copy of the rows it
+is supposed to be reading.
+
+`SqlControlRuntime` stores the decoded plan input and the plan card summary as
+raw plaintext JSON. The durable adapter does not redact or encrypt those
+columns because the input must be replayed exactly. Never put a credential in
+plan input: store it through `Credential`, pass only a `CredentialRef`, and
+resolve that reference at the adapter boundary that needs the secret.
+
+The Node CLI creates its `.flows/` directory with mode `0700` and, on POSIX,
+repairs existing directory permissions to `0700` and SQLite database, WAL,
+and shared-memory file permissions to `0600` when opening the control store.
+Windows does not use this POSIX chmod policy. If you embed the durable adapter
+with your own database layer, configure equivalent storage access controls.
+
+### Options
+
+| Option      | Meaning                                                                                                                                                                                 |
+| ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `flows`     | The catalog this plane may plan, as `DurableFlow` entries. Defaults to the plannable reserved system flows.                                                                             |
+| `owner`     | The process identity every claim is stamped with. Omitted, one synthetic identity is minted for this runtime only, so separately constructed runtimes cannot cross each other's fences. |
+| `principal` | The fallback identity stamped on a mutation whose caller named none.                                                                                                                    |
+
+Supply a real `owner` whenever the host can report its process identity, so
+liveness probes can reason about the operating-system process.
+
+## Run the migrations
+
+The package reserves a namespaced migration block, and a host composes it
+beside the journal and run-store sets before opening a shared control database:
+
+```ts
+import * as ControlMigrations from "@smthrs/control/Migrations"
+import * as DatabaseMigrations from "@smthrs/database/Migrations"
+import * as JournalMigrations from "@smthrs/journal/Migrations"
+import * as RunStoreMigrations from "@smthrs/run-store/Migrations"
+
+const migrations = DatabaseMigrations.run([
+  JournalMigrations.set,
+  RunStoreMigrations.set,
+  ControlMigrations.set
+])
+```
+
+`ControlMigrations.layer` runs the control set alone before exposing the
+database to control services, and `ControlMigrations.run` is the effect behind
+it.
+
+Each adapter also bootstraps its own tables idempotently, through
+`SqlControlRuntime.migrate` and `SqlCredentialStore.migrate`, so standalone
+construction works. Prefer the composed set: a standalone runtime that recorded
+control's high-offset migration first would make the later journal and
+run-store sets look skipped.
+
+The tables the set creates are `control_plans`, `control_plan_keys`,
+`control_tokens`, `control_grants`, `control_mutations`, `control_runs`,
+`control_run_resumes`, `control_run_messages`, `control_sequences`, and
+`control_credentials`.
+
+## What the durable runtime adds
+
+Several `RunSummary` fields exist only here, because they are read from the
+engine's own columns and journal entries:
+
+| Field                                                | Read from                                                                                     |
+| ---------------------------------------------------- | --------------------------------------------------------------------------------------------- |
+| `waitingReason`                                      | `flows_runs.waiting_reason`                                                                   |
+| `parentRunId`, `lineageId`, `roundOrdinal`, `origin` | the run row's columns and the `flows_run_parents` spawn edges                                 |
+| `cancellation`                                       | `cancel_requested_at_ms`, `flows.engine.interrupted`, and the plane's own attributed requests |
+
+They are read through the `SqlClient` the runtime was built over. A composition
+that wants them must give the control runtime and the engine **one** database.
+The [`smthrs` CLI](/api/cli) does not: it keeps `.flows/control.db` and
+`.flows/engine.db` as two files, so one run has two rows and these projections
+are empty there. Cancellation still converges, because the request travels
+through the [executor port](./implement-an-executor.md) and the owning driver
+settles from it.
+
+The listing covers every row in `flows_runs`, not only the runs this plane
+launched. A run whose `state_json` is not a control summary, an engine-created
+run, is projected from the row's own columns with the engine's `flowName` as
+its `flowId`.
+
+## Reading one run stays cheap
+
+A listing folds the whole database, because every row is going to be answered
+for anyway. Reading one run, which is what every mutation does before it
+writes, reads that run and its ancestor chain and nothing else. The cost of
+steering or cancelling a run therefore does not grow with the size of the
+database.
+
+## Where to go next
+
+- [Ownership, fences, and claims](../concepts/ownership.md): what a fence is
+  and what the status mapping means.
+- [Connect an execution engine](./implement-an-executor.md): the other half of
+  a real deployment.
+- [Store and resolve a credential](./store-credentials.md): the durable
+  credential table lives in this same set.

package/docs/guides/implement-an-executor.md

@@ -0,0 +1,173 @@
+---
+title: "Connect an execution engine"
+description: "Implement ControlExecutor so plan launches start real runs and cancels, signals, and resumes reach the engine: the five methods, the answers each one may give, and why a launch forks."
+sidebar:
+  order: 8
+---
+
+`ControlExecutor` is the seam between authority and execution. The plane hands
+work over and learns only what the executor did with it.
+
+Without it, the plane records facts nobody reads: a cancel that answers
+`ClaimLost` to every process but the owner, a signal a parked run never sees,
+and a resume nothing subscribes to.
+
+## The five methods
+
+```ts
+interface Service {
+  readonly launch: (input: Launch) => Effect.Effect<Acceptance, LaunchFailed>
+  readonly requestCancel: (input: CancelRequest) => Effect.Effect<CancelRecord, PersistenceError>
+  readonly deliverSignal: (input: Signal) => Effect.Effect<SignalDelivery, PersistenceError>
+  readonly resumeRun: (input: ResumeRequest) => Effect.Effect<ResumeUptake, PersistenceError>
+  readonly settleCancelledPark: (input: CancelRequest) => Effect.Effect<void, PersistenceError>
+}
+```
+
+Each answer is a small closed vocabulary, and every value in it is a real
+deployment:
+
+| Method                | Answer                                        | Means                                                                      |
+| --------------------- | --------------------------------------------- | -------------------------------------------------------------------------- |
+| `launch`              | `accepted`                                    | This executor took the launch. The plane writes `running`.                 |
+|                       | `pending`                                     | It queued the launch. The plane releases the row as `control.run.pending`. |
+|                       | fails `LaunchFailed`                          | Nothing will ever drive this run. The plane settles the row as `failed`.   |
+| `requestCancel`       | `recorded`                                    | This call set `cancel_requested_at_ms` on the engine row.                  |
+|                       | `already-requested`                           | The column was already set, so the attribution record already exists.      |
+|                       | `unknown`                                     | This executor's engine has no row for the run.                             |
+|                       | `{ _tag: "Terminal", status }`                | The engine row has already settled.                                        |
+| `deliverSignal`       | `delivered`, `no-match`, `refused`, `unknown` | See [Deliver a signal](./signal-a-run.md).                                 |
+| `resumeRun`           | `resuming`                                    | This executor hosts the run, took the fence, and is re-driving it.         |
+|                       | `unknown`                                     | It drives no execution for this run.                                       |
+| `settleCancelledPark` |                                               | Finishes a parked execution whose cancellation is already durable.         |
+
+`already-requested` is not a detail. The write is first-writer-wins and every
+repeat of `cancel` re-runs the whole mutation, so answering `recorded` to all
+of them journals one `control.run.cancel-requested` per ask for a single
+cancellation.
+
+`settleCancelledPark` exists because a park has no owner, so nothing is driving
+the run and nothing reads the request `requestCancel` wrote. The engine's
+parked-run sweep does, once per heartbeat, but a short-lived `smthrs runs cancel`
+process writes the request at the very end of its life and exits first. The
+plane calls this _after_ the cancel mutation commits, never inside it: driving
+a run re-enters the engine, whose writes would wait on the writer the
+transaction holds.
+
+## Start from the noop
+
+`ControlExecutor.makeNoop` answers the honest absence for every method, so an
+implementation overrides only what it supports:
+
+```ts
+import * as ControlExecutor from "@smthrs/control/ControlExecutor"
+import * as Effect from "effect/Effect"
+
+const executor = ControlExecutor.makeNoop({
+  launch: ({ plan, run }) =>
+    Effect.sync(() => {
+      queue.push({ flowId: plan.card.flowId, runId: run.runId })
+      return "pending" as const
+    })
+})
+```
+
+`ControlExecutor.layer(executor)` and `ControlExecutor.layerNoop(overrides)`
+provide it.
+
+## Start the run the plane minted
+
+`launch` receives the stored plan and the run row the plane has committed, and
+it must start _that_ run: `run.runId` is the execution id, so the events the
+engine journals and the row the plane projects name one run.
+
+```ts
+import * as ControlExecutor from "@smthrs/control/ControlExecutor"
+import * as ControlRuntime from "@smthrs/control/ControlRuntime"
+import type * as ControlSchema from "@smthrs/control/ControlSchema"
+import type { FlowRuntime } from "@smthrs/flow"
+import { Executable, Registry } from "@smthrs/registry"
+import { RunStore } from "@smthrs/run-store"
+import type * as Crypto from "effect/Crypto"
+import * as Effect from "effect/Effect"
+import type * as FileSystem from "effect/FileSystem"
+import * as Layer from "effect/Layer"
+import type * as Path from "effect/Path"
+
+/** How a discovered descriptor is loaded, and what it may delegate to. */
+const bridge: Executable.Options = { delegates: [] }
+
+const executorLayer = Layer.effect(ControlExecutor.ControlExecutor)(
+  Effect.gen(function*() {
+    const plane = yield* ControlRuntime.ControlRuntime
+    const services = yield* Effect.context<
+      | Crypto.Crypto
+      | FileSystem.FileSystem
+      | FlowRuntime.FlowRuntime
+      | Path.Path
+      | Registry.Registry
+      | RunStore.RunStore
+    >()
+
+    return ControlExecutor.makeNoop({
+      launch: ({ plan, run }) =>
+        Effect.gen(function*() {
+          const executable = yield* Executable.fromRegistry(plan.card.flowId, bridge)
+          Effect.runForkWith(services)(
+            executable.flow.execute(
+              { input: plan.decodedInput },
+              { executionId: run.runId, discard: true }
+            ).pipe(Effect.andThen(mirror(plane, run.runId)))
+          )
+          return "accepted" as const
+        }).pipe(Effect.provide(services), Effect.orDie)
+    })
+  })
+)
+```
+
+It forks so launch acceptance does not wait for execution to finish. Admission
+is already committed before `launch` runs. After the executor answers
+`accepted`, the plane marks a still-accepted run as running; an outcome the
+executor has already recorded, including a parked or completed run, is preserved.
+
+## Mirror the engine's status back
+
+The plane cannot see into the engine's database, so an executor that walked
+away after starting a run would leave every run reading `running` forever.
+Reading the engine's own row back and writing the plane's vocabulary onto the
+plane's row is the whole of that duty, and it is the `mirror` the launch above
+chains onto:
+
+```ts
+/** The engine's run vocabulary, in the plane's. */
+const planeStatus = (status: RunStore.RunStatus): ControlSchema.RunStatus =>
+  status === "suspended" ? "parked" : status === "pending" ? "accepted" : status
+
+const mirror = (plane: ControlRuntime.Service, runId: string) =>
+  Effect.gen(function*() {
+    const runs = yield* RunStore.RunStore
+    const row = yield* runs.get(runId)
+    const id = runId as ControlSchema.RunId
+    const fence = yield* plane.claimFence(id)
+    yield* plane.writeStatus(id, fence, planeStatus(row.status))
+  }).pipe(Effect.orDie)
+```
+
+The engine calls a parked run `suspended`; an operator calls it `parked`. The
+two vocabularies are not the same set, so the mapping is explicit: every status
+the engine reports has to land on a member of `ControlSchema.RunStatus`, which
+is the only vocabulary the plane's row accepts.
+
+The complete, runnable bridge, with discovery, two databases, and one shared
+journal, is
+[`examples/src/24-control-plane-and-gateway.ts`](https://github.com/smithersai/smithers/blob/main/examples/src/24-control-plane-and-gateway.ts).
+
+## Where to go next
+
+- [Ownership, fences, and claims](../concepts/ownership.md): what
+  `claimFence` and `writeStatus` are doing.
+- [Cancel a run, and restart one](./cancel-and-resume.md): the sequence
+  `requestCancel` and `settleCancelledPark` sit inside.
+- [Store control state in a database](./durable-storage.md): the other half of
+  a real deployment.

package/docs/guides/ingest-a-webhook.md

@@ -0,0 +1,177 @@
+---
+title: "Accept a webhook as a control request"
+description: "Turn a verified external request into one control mutation: the verify-then-decode order, the durable idempotency a redelivery replays, the headers that may enter identity, and the body ceiling."
+sidebar:
+  order: 11
+---
+
+A channel turns an external request into a control mutation, once. It verifies
+opaque bytes before it decodes them, and it acquires no execution path of its
+own: everything it does, it does through `Control`.
+
+## Build a webhook channel
+
+```ts
+import * as WebhookChannel from "@smthrs/control/WebhookChannel"
+import * as Effect from "effect/Effect"
+import * as Redacted from "effect/Redacted"
+import * as Schema from "effect/Schema"
+
+const Push = Schema.Struct({ ref: Schema.String })
+
+const github = WebhookChannel.make({
+  name: "github",
+  schema: Push,
+  credential: Redacted.make({ id: "github-webhook", name: "GitHub webhook" }),
+  fingerprintHeaders: ["x-github-event"],
+  verify: (raw, credential) => verifySignature(raw, credential),
+  map: (payload) =>
+    Effect.succeed({
+      _tag: "Start" as const,
+      flowId: "ops/Deploy",
+      input: { build: payload.ref }
+    }),
+  project: (run) => ({ cursor: run.status, operation: "post", message: { text: run.runId } })
+})
+```
+
+`map` returns one of two results:
+
+| Result                              | Becomes                                  |
+| ----------------------------------- | ---------------------------------------- |
+| `{ _tag: "Start", flowId, input }`  | `control.plan` followed by `control.run` |
+| `{ _tag: "Signal", runId, signal }` | `control.signal`                         |
+
+`decode` and `map` must be deterministic and free of side effects. A retry may
+evaluate either of them again.
+
+The credential is a redacted `CredentialRef`, never a secret. Resolving it
+belongs at the host adapter boundary, so a webhook's persisted record never
+holds key material. See [Store and resolve a credential](./store-credentials.md).
+
+## Register and mount it
+
+```ts
+import * as Channels from "@smthrs/control/Channels"
+
+const program = Effect.gen(function*() {
+  const channels = yield* Channels.Channels
+  yield* channels.register(github)
+})
+```
+
+`register` accepts `Channel<A>` directly, including typed webhook payloads.
+`lookup` returns a `RegisteredChannel`: the declared schema and transport
+metadata remain available, while `decodeAndMap` keeps the hidden payload type
+inside the adapter. Use `ingest` for verified dispatch through `Control`.
+
+`Channels.layer` builds the coordinator over `ControlRuntime`'s durable
+mutation store, so inbound idempotency survives a coordinator restart. Only
+registration and outbound projection cursors are process-local.
+`Channels.layerMemory` is process-local throughout and exists for adapter unit
+tests.
+
+`WebhookChannel.handler` reads an abstract Effect HTTP request and dispatches
+it, so any Effect HTTP host can mount it:
+
+```ts
+HttpRouter.post("/webhooks/github", WebhookChannel.handler("github", deliveryId))
+```
+
+Take `deliveryId` from the platform's own delivery header. That is what makes a
+redelivery the same mutation instead of a second one.
+
+## The order verification happens in
+
+`ingest` runs one request at a time, and in this order:
+
+1. Copy the request: the bytes, and only the enumerable own string headers,
+   lower-cased, with a duplicate case-insensitive name refused.
+2. Compute the body fingerprint.
+3. **Verify**, with the verifier's own copy of the body. Signature verification
+   is the amplification guard, so it happens before decode and before any
+   `Control` access. The verifier receiving its own copy means even a verifier
+   that edits bytes cannot change what the decoder sees after approval.
+4. Look the durable idempotency record up. A match replays the stored receipt.
+5. Decode, map, and dispatch through `Control`.
+6. Record the receipt, unless it was a `Conflict` or `Parked`. A parked start
+   leaves the ingress key unsettled: approve its stored plan, then redeliver
+   with the same delivery id to retry the launch. Once accepted, later
+   redeliveries return `AlreadyApplied` for the same run.
+
+The receipt handed back carries the platform's own delivery id as its
+`receiptId`, so a caller correlating against its own logs sees the id it sent.
+
+## What enters durable identity
+
+The fingerprint is the SHA-256 of the body plus only the header names the
+adapter declared in `fingerprintHeaders`, matched case-insensitively and sorted.
+
+Declare a header there only when its value changes the decoded command, as
+`x-github-event` does. Signature, authorization, cookie, token, and credential
+headers must not be declared: rotating an excluded credential header leaves the
+delivery identical, which is what you want.
+
+Reusing one delivery id with different declared semantics answers `Conflict`.
+
+## The body ceiling
+
+A webhook is the one control-plane ingress a caller reaches with an arbitrary
+payload, so `handler` bounds the body twice:
+
+- A `content-length` over the limit is refused before the body is read at all,
+  so a declared flood costs nothing.
+- Each streamed chunk is measured before it is retained. Reading stops and the
+  stream is cancelled at the first chunk exceeding the limit, even if the
+  caller understates or omits the length. Verification has not run at this point.
+
+Both refusals are `InvalidInput` naming the two byte counts and no body
+content. The default is `WebhookChannel.maximumBodyBytes`, 1 MiB, and one mount
+lowers it:
+
+```ts
+WebhookChannel.handler("github", deliveryId, { maximumBodyBytes: 256 * 1024 })
+```
+
+The default is deliberately smaller than the 4 MiB mutation identity budget: a
+body that cannot become a durable mutation is refused at the door rather than
+copied, decoded, and refused later.
+
+Malformed JSON returns `InvalidInput` with the fixed issue `invalid webhook
+JSON`. Parser messages and payload fragments are excluded from the error.
+
+## Project a run back out
+
+`project` is side-effect free. It turns a `RunSummary` and the previous
+delivery record into a `DeliveryProjection`, and the transport adapter performs
+the network call after the projection is journaled:
+
+| `operation` | Meaning                               |
+| ----------- | ------------------------------------- |
+| `post`      | Send a new message.                   |
+| `edit`      | Update the message `messageId` names. |
+| `noop`      | Nothing changed worth sending.        |
+
+The coordinator keeps delivery identities for live runs, including parked runs
+and runs waiting for approval, so later projections can edit the same message.
+Completed, failed, and cancelled runs share a FIFO window of 1,024 delivery
+records across channels. Repeated terminal projections do not extend that
+window. A run projected as live again leaves the terminal window.
+
+A `noop` does not create or replace a delivery record. Unchanged cursor and
+message identities reuse the previous record. Terminal status still moves an
+existing record into the retention window even when the projection is a noop.
+
+Outbound records are process-local. After terminal eviction or coordinator
+restart, the adapter receives no previous delivery and may post a new message.
+Hosts needing edits beyond this window must keep remote message identities in
+their own durable transport storage.
+
+## Where to go next
+
+- [Store and resolve a credential](./store-credentials.md): where the verifier's
+  secret comes from.
+- [Receipts and idempotency](../concepts/receipts.md): the store behind a
+  replayed redelivery.
+- [Gate work behind an approval](./approvals.md): an ingested `Start` still
+  parks until somebody approves it.