@smthrs/gateway 0.34.0 → 1.0.0-rc.3

package/docs/guides/read-a-projection.md

@@ -0,0 +1,138 @@
+---
+title: "Read a projection over HTTP"
+description: "Call Projection.Snapshot for each of the eight selectors, decode the rows with the schema the selector names, and keep the cursor the snapshot answers with."
+sidebar:
+  order: 2
+---
+
+`Projection.Snapshot` answers every row a selector currently projects, plus the
+cursor they were read at. It is the request/response half of the read path, and
+it is what a relay in front of a gateway uses, because a stream belongs on a
+socket rather than in a buffered response.
+
+## Pick a selector
+
+Each selector is a tagged struct. Build one as a value, never as a string:
+
+```ts
+import * as GatewaySchema from "@smthrs/gateway/GatewaySchema"
+
+const everyRun: GatewaySchema.ProjectionSelector = { _tag: "workspace-runs" }
+const oneRun: GatewaySchema.ProjectionSelector = { _tag: "run-summary", runId }
+const itsEvents: GatewaySchema.ProjectionSelector = { _tag: "run-events", runId }
+const itsTranscript: GatewaySchema.ProjectionSelector = { _tag: "transcript", runId }
+const itsCalls: GatewaySchema.ProjectionSelector = { _tag: "run-tree", runId }
+const itsGates: GatewaySchema.ProjectionSelector = { _tag: "approvals", runId }
+const theInbox: GatewaySchema.ProjectionSelector = { _tag: "approvals" }
+const oneOutput: GatewaySchema.ProjectionSelector = { _tag: "node-output", runId, nodeId: "call-1" }
+const itsDurations: GatewaySchema.ProjectionSelector = { _tag: "flow-durations", flowId }
+```
+
+`approvals` is the one selector whose `runId` is optional, and the two forms
+answer different questions. With a run it lists that run's gates including the
+decided ones, which is what a run card renders: a gate a human already answered
+still belongs on the card that asked. Without one it lists the workspace's
+pending gates, which is the approvals inbox.
+
+## Read it in process
+
+```ts
+import { Projections } from "@smthrs/gateway/Projections"
+import { Effect } from "effect"
+
+const rows = Effect.gen(function*() {
+  const projections = yield* Projections
+  const snapshot = yield* projections.snapshot({ _tag: "run-tree", runId })
+  return snapshot.rows
+})
+```
+
+The effect fails with a `GatewayError`. `run_not_found` means the control plane
+does not have that run, and it is answered identically for every run-scoped
+selector: reading a run's events alone cannot tell an unknown run from a run
+with no events.
+
+## Read it over the wire
+
+The mount speaks RPC over newline-delimited JSON. One request is one line:
+
+```bash
+curl -s http://127.0.0.1:3000/projections \
+  -H 'content-type: application/json' \
+  --data-binary '{"_tag":"Request","id":1,"tag":"Projection.Snapshot","payload":{"selector":{"_tag":"run-tree","runId":"run-1"}},"headers":[]}
+'
+```
+
+```text
+{"_tag":"Exit","requestId":1,"exit":{"_tag":"Success","value":{"selector":{"_tag":"run-tree","runId":"run-1"},"cursor":{...},"rows":[...]}}}
+```
+
+A failure arrives as the same envelope with a `Failure` exit carrying the typed
+`GatewayError`. A refusal answered by the ingress guard instead, before the
+mount saw the request, is a plain JSON body under an HTTP status: see
+[the trust boundary](../concepts/trust-boundary.md#ingress-runs-before-the-transport-parses-anything).
+
+If the gateway was bound with a credential, send it:
+
+```bash
+curl -s http://127.0.0.1:3000/projections \
+  -H "authorization: Bearer $SMITHERS_TOKEN" \
+  -H 'content-type: application/json' \
+  --data-binary '{"_tag":"Request","id":1,"tag":"Projection.Snapshot","payload":{"selector":{"_tag":"workspace-runs"}},"headers":[]}
+'
+```
+
+## Decode the rows, do not cast them
+
+`GatewaySchema.rowSchemaFor` maps a selector to the schema its rows decode
+under, so a client that already has the selector does not need a switch of its
+own:
+
+```ts
+import * as GatewaySchema from "@smthrs/gateway/GatewaySchema"
+import { Schema } from "effect"
+
+const decodeRows = (selector: GatewaySchema.ProjectionSelector, rows: unknown) =>
+  Schema.decodeUnknownSync(Schema.Array(GatewaySchema.rowSchemaFor(selector)))(rows)
+```
+
+| Selector                        | Row schema                          |
+| ------------------------------- | ----------------------------------- |
+| `workspace-runs`, `run-summary` | `GatewayProjection.RunSummaryRow`   |
+| `run-events`                    | `ControlSchema.ControlEvent`        |
+| `transcript`                    | `GatewayProjection.TranscriptRow`   |
+| `run-tree`                      | `GatewayProjection.RunTreeRow`      |
+| `approvals`                     | `GatewayProjection.ApprovalRow`     |
+| `node-output`                   | `GatewayProjection.NodeOutputRow`   |
+| `flow-durations`                | `GatewayProjection.FlowDurationRow` |
+
+`GatewaySchema.ProjectionSnapshot` decodes the whole answer, selector and
+cursor included, and it is a union correlated on the selector: a snapshot whose
+rows do not belong to its selector does not decode at all.
+
+## Keep the cursor
+
+Every snapshot carries the cursor its rows were read at. It is not decoration:
+it is the position a subscription resumes from without a second snapshot, and
+the read that produced the rows produced it, so the two cannot disagree. See
+[Follow a run over a WebSocket](./follow-a-run.md).
+
+A workspace cursor is always `value` 0 with a `null` run, and cannot resume
+anything. That is a fact about control journal partitioning, not a gap: see
+[Subscriptions and cursors](../concepts/subscriptions.md#workspace-subscriptions-do-not-resume).
+
+## Fold rows yourself
+
+The folds are exported, so a client that already holds a run summary and its
+events can compute the same rows without a gateway at all:
+
+```ts
+import * as GatewayProjection from "@smthrs/gateway/GatewayProjection"
+
+const tree = GatewayProjection.runTree(run, events)
+const gates = GatewayProjection.approvals(events)
+const lines = GatewayProjection.transcript(events)
+```
+
+This is the same code path the served projection uses, which is what makes an
+offline reader and a served reader agree.

package/docs/guides/serve-beyond-loopback.md

@@ -0,0 +1,166 @@
+---
+title: "Serve beyond loopback"
+description: "Bind a gateway on a network address: the two opt-ins the policy requires, the credential every mount then enforces, and the request limits worth setting at the same time."
+sidebar:
+  order: 5
+---
+
+A loopback gateway needs no credential. Its ingress still accepts only a
+loopback `Host` and, when present, a loopback browser `Origin`; Origin-less CLI
+requests keep working. Anything reachable from another machine needs two
+opt-ins, and the policy refuses the bind rather than serving without them.
+
+## The two rules
+
+1. **A non-loopback host requires an explicit `listen` opt-in.**
+
+   ```text
+   Refusing non-loopback gateway bind 0.0.0.0 without an explicit --listen opt-in
+   ```
+
+2. **A non-loopback bind requires a bearer credential.**
+
+   ```text
+   Refusing non-loopback gateway bind 0.0.0.0 without a bearer credential
+   ```
+
+`NodeGateway.isLoopbackHost` accepts `127.0.0.1`, `::1`, and `localhost`.
+Every other host, a LAN address and a public one alike, is treated as reachable
+from elsewhere.
+
+Both refusals are `bind_failed` `GatewayError` values, answered before anything
+binds.
+
+## Bind it
+
+```ts
+import * as NodeGateway from "@smthrs/gateway/node/NodeGateway"
+
+const gateway = NodeGateway.layer(health, {
+  host: "0.0.0.0",
+  port: 7331,
+  listen: true,
+  credential: process.env.SMITHERS_TOKEN,
+  allowedHosts: ["gateway.example.com"],
+  // Optional, and worth setting behind a relay that cuts idle tunnels sooner
+  // than 600 seconds.
+  heartbeatMillis: 10_000,
+  // Optional. One MiB by default.
+  maxRequestBodyBytes: 256 * 1024
+})
+```
+
+From the command line, bind the machine's concrete LAN address so that address
+is also admitted by the Host policy (replace this example with your address):
+
+```bash
+export SMITHERS_TOKEN="<the bearer token from your secret manager>"
+smthrs serve --host 192.168.1.10 --port 3000 --listen
+```
+
+The server reads the bearer from `SMITHERS_TOKEN`, which keeps it out of the
+long-lived process's argv. See
+[Serve the workspace gateway](/pkg/cli/guides/serve-the-workspace-gateway).
+
+## What the credential then covers
+
+One credential authenticates every mount and binds one principal,
+`{ id: "gateway", kind: "bearer" }`. This authenticator has no per-user or
+per-run identity. Approval authority is separately configured on the owning
+Control runtime: by default the bearer cannot approve or deny. To delegate,
+provide `ApprovalAuthority` with that exact identity and allowed target kinds
+and scopes. Delegation applies to everyone holding the shared credential; it
+does not distinguish a human from an agent. See
+[the approval contract](/pkg/control/guides/approvals/#who-may-decide).
+
+The loopback Host/Origin restriction belongs to the credential-less local
+mode. A bearer-protected non-loopback gateway accepts the network hostname it
+was deployed under and relies on the configured credential instead.
+
+Clients send it as a bearer token:
+
+```bash
+curl -s https://gateway.example.com/projections \
+  -H "authorization: Bearer $SMITHERS_TOKEN" \
+  -H 'content-type: application/json' \
+  --data-binary '{"_tag":"Request","id":1,"tag":"Projection.Snapshot","payload":{"selector":{"_tag":"workspace-runs"}},"headers":[]}
+'
+```
+
+A WebSocket client sends the same header on the upgrade request. A browser's
+`WebSocket` cannot set headers on an upgrade, so it exchanges the credential for
+a single-use ticket first and presents that on the upgrade instead:
+
+```js
+const { ticket } = await (await fetch("https://gateway.example.com/auth/ticket", {
+  method: "POST",
+  headers: { authorization: `Bearer ${token}` }
+})).json()
+const socket = new WebSocket(`wss://gateway.example.com/rpc/ws?ticket=${ticket}`)
+```
+
+The ticket opens one socket within thirty seconds and is refused on replay.
+The socket runs as the credential the ticket was issued against.
+
+## Hand out less than the credential
+
+`smthrs token mint --scope read:runs --ttl 1h` mints a token under
+`SMITHERS_TOKEN` that this gateway accepts for the procedures the scope names
+and nothing else, until it expires. `--run <id>` or `--flow <id>` confines it
+further. The scopes are `read:runs`, `write:runs`, and `approve:runs`; a token
+stamps `gateway/scoped`, so an `approve:runs` token decides only where the host
+delegates to that identity. Rotating `SMITHERS_TOKEN` revokes every token
+minted under it. See [the trust boundary](../concepts/trust-boundary.md#scoped-expiring-tokens).
+
+`/health` stays unauthenticated even here. It answers identity and nothing
+else: no token, no run, no path.
+
+## Two refusals that look alike and are not
+
+`POST /rpc` is not edge-authenticated. It authenticates in band and answers
+`@smthrs/control`'s typed `Unauthorized`, so a caller sees a control error
+rather than a transport error, exactly as it would against a control server
+hosting the same procedures. `/rpc/ws`, `/projections`, `/sync`, and both other
+sockets are checked at the edge and answer 401 with a `unauthorized`
+`GatewayError` body.
+
+Why the two differ, and why it matters to a client's error handling, is in
+[the trust boundary](../concepts/trust-boundary.md#edge-authentication-and-where-it-deliberately-stops).
+
+## Bound the requests while you are here
+
+For a wildcard bind, set `allowedHosts: ["gateway.example.com"]` on
+`NodeGateway.ServerOptions` to admit the hostname clients use. These entries
+contain no ports or wildcards. A concrete bind host and the loopback names are
+also accepted. The Host and Origin checks apply before bearer authentication;
+a browser's Origin must match the requested authority, including its port.
+
+This server binds plain HTTP. For network access, terminate TLS at a trusted
+proxy or use an encrypted tunnel so the bearer token is not sent in cleartext.
+
+An HTTP RPC body is capped at `GatewayServer.defaultMaxRequestBodyBytes`, one
+MiB. A declared `content-length` over the limit is refused without reading the
+body; a body that declares no length, or declares less than it sends, is
+measured as it is read. Declared overflow is 413 `request_too_large`; the Node
+host hard-closes a streaming overflow rather than draining attacker-controlled
+bytes, so that client may see a connection reset. A body the server could not
+read for another reason is 400 `malformed_request`.
+
+`maxRequestBodyBytes` and `heartbeatMillis` are checked the same way and must
+both be positive safe integers. A body limit of zero would refuse every request
+and a cadence of zero would spin, so a composition that asks for either is
+refused with `bind_failed` before it binds rather than after it is serving.
+
+## Check the policy without composing anything
+
+```ts
+const refusal = NodeGateway.bindRefusal(options)
+if (refusal !== undefined) {
+  // refusal.code === "bind_failed", refusal.message names the rule that refused
+}
+```
+
+`bindRefusal` is the same value `listenOptions` fails with and `layer` fails
+through. Operating system listen failures, such as an address already in use,
+are mapped to the same sanitized `bind_failed` shape, so a host has one failure
+contract to handle rather than two.

package/docs/guides/submit-an-approval.md

@@ -0,0 +1,187 @@
+---
+title: "Submit an approval from a client"
+description: "Read a pending gate, submit Approval.Submit with independent approval authority, and handle its typed refusals."
+sidebar:
+  order: 4
+---
+
+`Approval.Submit` is the one mutation this package declares. Every other
+mutation a client makes is [`@smthrs/control`](/api/control) `ControlRpcs`,
+mounted unchanged on `/rpc`, so there is exactly one wire definition of `Plan`,
+`Run`, `Approve`, `Deny`, `Cancel`, `Signal`, `Steer`, `Resume`, `List`, and
+`Watch`.
+
+This one exists because a decision is a composite act a client cannot
+assemble safely on its own: the grant has to be recorded and the parked run
+delegated to resume, atomically. Control owns that as a single domain command.
+The gateway is a transport adapter over it and composes no second mutation.
+
+## Read the gate
+
+The payload a decision needs is published by the `approvals` projection. Do not
+build it:
+
+```ts
+import { Projections } from "@smthrs/gateway/Projections"
+import { Effect } from "effect"
+
+const pending = Effect.gen(function*() {
+  const projections = yield* Projections
+  // No runId: the workspace inbox, which lists only gates a human still owes
+  // an answer to.
+  const snapshot = yield* projections.snapshot({ _tag: "approvals" })
+  return snapshot.rows
+})
+```
+
+Each `GatewayProjection.ApprovalRow` carries:
+
+| Field         | Holds                                                                 |
+| ------------- | --------------------------------------------------------------------- |
+| `runId`       | the run parked on this gate                                           |
+| `waitRunId`   | the execution holding the wait, when it is held below `runId`         |
+| `requestId`   | the gate's own id                                                     |
+| `title`       | the question, as the run asked it                                     |
+| `request`     | the whole journaled request payload, for rendering                    |
+| `payload`     | the `ControlSchema.ApprovalPayload` a decision submits back unchanged |
+| `requestedAt` | when the gate opened                                                  |
+| `status`      | `pending`, `approved`, or `denied`                                    |
+
+`payload` is the point. It is the exact `ApprovalTarget.Node` envelope the run
+published, carrying the target, the grant scope, and the idempotency key. A
+client submits it back byte for byte, so no client reconstructs authority for
+itself.
+
+### Gates held by a nested execution
+
+A flow that calls another flow parks the CHILD execution. A `HumanTask` in a
+nested flow therefore parks a run an operator has never heard of, while the run
+they did open sits at `waiting-approval` with nothing of its own to decide.
+
+The control plane rolls those waits up: `ControlSchema.RunSummary.pendingWaits`
+lists every open human wait in a run's tree, and the run's status rolls up with
+them, so the ordinary `status: "waiting-approval"` filter finds the root. The
+`approvals` projection turns each into a pending row of that root run.
+`waitRunId` names the execution actually holding it; the workspace inbox lists
+one question once, from the outermost run that carries it.
+
+Such a row asks a QUESTION rather than for a grant, and its `request` says
+what kind of answer:
+
+| `request` field | Holds                                                         |
+| --------------- | ------------------------------------------------------------- |
+| `kind`          | `ask`, `confirm`, `select`, or `json`                         |
+| `prompt`        | the question, which is also the row's `title`                 |
+| `name`          | the wait point's own name, which `Signal` addresses           |
+| `attempt`       | which attempt of a re-asked question this is, counting from 1 |
+| `maxAttempts`   | the attempt budget the task declared                          |
+| `options`       | the choices, on a `select`                                    |
+| `token`         | the durable wait address, for a client that prefers it        |
+
+## Submit the decision
+
+`GatewayRpcs.SubmitApprovalInput` is that payload plus one field:
+
+```json
+{
+  "_tag": "Request",
+  "id": 1,
+  "tag": "Approval.Submit",
+  "payload": {
+    "target": {
+      "_tag": "Node",
+      "runId": "run-1",
+      "requestId": "gate",
+      "digest": "gate-digest",
+      "envelope": { "capabilities": ["model:call"], "flows": ["ask"], "budget": {} }
+    },
+    "scope": "run",
+    "idempotencyKey": "approve:gate",
+    "decision": "approve"
+  },
+  "headers": []
+}
+```
+
+Post it to `/projections`, or send it on `/projections/ws`. `decision` is
+`"approve"` or `"deny"`; everything else is the row's `payload` spread in
+place.
+
+### Answering a question
+
+A gate that asks a question needs the value, not the word: add `answer`.
+
+```json
+{
+  "target": {
+    "_tag": "Node",
+    "runId": "run-3",
+    "requestId": "coding-clarification#1",
+    "digest": "<the row's wait token>",
+    "envelope": { "capabilities": [], "flows": [], "budget": {} }
+  },
+  "scope": "once",
+  "idempotencyKey": "answer:run-3:coding-clarification#1",
+  "decision": "approve",
+  "answer": "the scheduler owns it"
+}
+```
+
+Shape the answer for the question's `kind`: prose for `ask`, a boolean for
+`confirm`, one of `options` for `select`, and the decoded JSON value for
+`json`. The mount routes it to `Control.signal`, addressed to `target.runId`
+and naming `target.requestId`, and the control plane finds the execution
+holding that wait. A denial carries no answer: it refuses the question rather
+than answering it, and an unanswered question re-parks or times out on the
+task's own budget.
+
+The answer is `GatewayRpcs.SubmitApprovalOutput`: one field, `decision`, the
+`ControlSchema.Receipt` that is the receipt for the grant or the refusal. There
+is no second call. Approving a parked node delegates its durable resume in the
+same command, and denying it records the refusal the same way.
+
+## Who the decision is journaled as
+
+The handler reads the principal the shared `ControlAuth` middleware
+authenticated and passes it through, exactly as `ControlServer` stamps it on
+`Approve` and `Deny`. This mount is the same decision under a different
+payload, so it is answerable to the same operator. A decision journaled under
+the composition's default operator would name the wrong one.
+
+Authentication is not approval authority. Control checks its host-owned
+`ApprovalAuthority` before mutation or receipt replay, and again at resolution.
+A shared bearer authenticates `gateway/bearer`, which is not an approver by
+default. The host must explicitly delegate that identity and the requested
+scope, or an authorized local operator must decide the gate. Both `/rpc` and
+`/projections`, over HTTP and WebSocket, enforce the same policy. Supplying a
+principal in the payload cannot override the authenticated actor.
+
+## The failures
+
+`Approval.Submit` answers with exactly the union `Control.approve`,
+`Control.deny`, and, for an answer, `Control.signal` declare, because the
+handler adds no failure of its own. A member none of them raises would be a
+recovery branch no client's code could ever reach.
+
+| Failure              | Means                                                     | What to do                                                   |
+| -------------------- | --------------------------------------------------------- | ------------------------------------------------------------ |
+| `Unauthorized`       | the caller lacks approval authority for this target/scope | ask an authorized operator; do not keep retrying unchanged   |
+| `PlanDigestMismatch` | the plan changed since the gate was published             | re-read the gate and show the new plan before deciding again |
+| `EnvelopeMismatch`   | the capability envelope is not the one that was approved  | re-read the gate; do not widen the envelope client-side      |
+| `AlreadyResolved`    | someone already decided this gate                         | refresh the row; the decision stands                         |
+| `PlanNotFound`       | the plan the target names is gone                         | re-plan                                                      |
+| `RunNotFound`        | the run the target names is gone                          | drop the gate from the inbox                                 |
+| `InvalidInput`       | the payload is not a decidable approval payload           | submit the row's `payload` unchanged                         |
+| `PersistenceError`   | the control plane could not write the decision            | retry with the same `idempotencyKey`                         |
+| `Unavailable`        | the control plane is not serving this operation           | retry later                                                  |
+| `NoMatchingWait`     | the question was answered after the run moved on          | re-read the inbox; somebody answered it, or it timed out     |
+
+Retrying is safe. The payload carries an `idempotencyKey`, so a second
+submission of the same decision lands one effect.
+
+## From the command line
+
+The same decision from a terminal is [`smthrs approvals approve`](/cli/approvals) and
+`smthrs approvals deny`, which take the same payload the projection
+publishes. For the domain semantics behind both, see
+[Approvals](/pkg/control/guides/approvals).

package/docs/guides/testing.md

@@ -0,0 +1,148 @@
+---
+title: "Test against a real gateway"
+description: "Stand a gateway up over a real SQLite control plane on an ephemeral port, write the events a projection folds, and control the supervision port from a test."
+sidebar:
+  order: 7
+---
+
+Test a gateway client against one real stack: a durable journal, a durable run
+store, the SQL control runtime, `ControlLive`, the served projections, the sync
+read path, and the assembled HTTP surface bound to an ephemeral loopback port.
+Stub nothing below the control plane.
+
+The behaviours worth pinning are an approval projected out of a parked run, a
+cancellation's attribution, and a child run's visibility. Those are exactly the
+places a mocked control plane agrees with your assertion and disagrees with the
+gateway a real workspace serves.
+
+## Compose the stack
+
+The stack reaches below this package's own dependencies. Add the packages
+that supply storage, the selected SQLite driver, and the control runtime's ports:
+
+```bash
+pnpm add -D \
+  @smthrs/database@1.0.0-rc.0 \
+  @smthrs/journal@1.0.0-rc.0 \
+  @smthrs/notifications@1.0.0-rc.0 \
+  @smthrs/registry@1.0.0-rc.0 \
+  effect@4.0.0-rc.115 \
+  @effect/sql-sqlite-node@4.0.0-rc.115
+```
+
+```ts
+import * as NodeCrypto from "@effect/platform-node/NodeCrypto"
+import * as ControlExecutor from "@smthrs/control/ControlExecutor"
+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 * as Projections from "@smthrs/gateway/Projections"
+import { Migrations, SqlJournal } from "@smthrs/journal"
+import { NotificationQueue } from "@smthrs/notifications"
+import { Registry } from "@smthrs/registry"
+import { Migrations as RunStoreMigrations, RunStore } from "@smthrs/run-store"
+import * as RunCatalog from "@smthrs/sync/RunCatalog"
+import * as SyncAuth from "@smthrs/sync/SyncAuth"
+import * as SyncServer from "@smthrs/sync/SyncServer"
+import * as WorkspaceShare from "@smthrs/sync/WorkspaceShare"
+import { Layer } from "effect"
+
+const storage = (filename: string) =>
+  Layer.mergeAll(SqlJournal.layer({ capacity: 1024, overflow: "reject" }), RunStore.layer).pipe(
+    Layer.provideMerge(
+      Layer.provideMerge(
+        Layer.merge(Migrations.layer, RunStoreMigrations.layer),
+        Layer.provideMerge(DurableWriter.layer(), NodeDatabase.layer({ filename }))
+      )
+    )
+  )
+
+export const stack = (filename: string) =>
+  Layer.mergeAll(
+    // A short cadence, so a keepalive assertion does not wait 30 seconds.
+    Projections.layerWith({ heartbeatMillis: 50 }),
+    SyncServer.layer,
+    SyncAuth.layer
+  ).pipe(
+    Layer.provideMerge(Layer.merge(RunCatalog.layerNoop, WorkspaceShare.layerNoop)),
+    Layer.provideMerge(ControlLive.layer),
+    Layer.provideMerge(
+      Layer.mergeAll(
+        SqlControlRuntime.layer({}).pipe(Layer.orDie),
+        NotificationQueue.layer,
+        ControlExecutor.layer(ControlExecutor.makeNoop()),
+        Registry.layerNoop()
+      )
+    ),
+    Layer.provideMerge(Layer.merge(storage(filename), NodeCrypto.layer))
+  )
+```
+
+A worked version of this helper, with the temporary-file lifecycle around it,
+is [`GatewayStack.ts`](https://github.com/smithersai/smithers/blob/main/packages/smithers/gateway/test/GatewayStack.ts)
+in the package source.
+
+## Bind an ephemeral port and read it back
+
+```ts
+import * as NodeGateway from "@smthrs/gateway/node/NodeGateway"
+import { Effect, Layer } from "effect"
+import { HttpServer } from "effect/unstable/http"
+
+const served = NodeGateway.layer(health, { host: "127.0.0.1", port: 0 }).pipe(Layer.provideMerge(stack(filename)))
+
+const baseUrl = Effect.map(HttpServer.HttpServer, (server) => {
+  if (server.address._tag !== "InetAddressV4" && server.address._tag !== "InetAddressV6") {
+    throw new Error("expected a TCP gateway")
+  }
+  return `http://127.0.0.1:${server.address.port}`
+})
+```
+
+Port 0 lets the operating system pick, and the layer retains the concrete
+`HttpServer`, so a test reads the address it actually got rather than racing
+for a fixed port.
+
+## Give a run something to project
+
+Write events through the journal's durable channel, not its lossy one:
+
+```ts
+import * as Journal from "@smthrs/journal/Journal"
+import * as JournalEvent from "@smthrs/journal/JournalEvent"
+import { Effect } from "effect"
+
+const emit = (runId: string, eventType: string, payload: unknown, sourceSeq: number) =>
+  Effect.flatMap(Journal.Journal, (journal) =>
+    journal.emitDurableUnfenced(
+      new JournalEvent.Input({
+        runId: JournalEvent.RunId.make(runId),
+        sourceId: JournalEvent.SourceId.make("gateway-test"),
+        sourceSeq: JournalEvent.SourceSeq.make(sourceSeq),
+        eventType,
+        payload: JSON.parse(JSON.stringify(payload))
+      })
+    ))
+```
+
+`emitLossy` returns once the optimistic queue accepts an entry, so a projection
+read straight afterwards can legitimately miss it, and a suite built on that
+races its own fixture. Give each event a monotonic `sourceSeq`, or two
+identical fixture events will not both admit.
+
+## Fold without a stack at all
+
+A test that only cares about a fold does not need any of the above. The folds
+are pure functions of a run summary and its events:
+
+```ts
+import * as GatewayProjection from "@smthrs/gateway/GatewayProjection"
+
+const rows = GatewayProjection.runTree(run, events)
+```
+
+This is the same code the served projection runs, so a fold test and an
+end-to-end test cannot disagree about what a row means. Reach for the full
+stack when what you are pinning is the _serving_: a status the run row owns, a
+cursor, a refusal, or an HTTP status.