@smthrs/gateway 0.34.0 → 1.0.0-rc.3

package/docs/concepts/trust-boundary.md

@@ -0,0 +1,256 @@
+---
+title: "The trust boundary"
+description: "What one gateway credential authorizes, why a network bind needs two opt-ins, which paths are checked at the edge and which authenticate in band, and what a refusal is allowed to say."
+sidebar:
+  order: 3
+---
+
+A gateway is a control plane on a socket. It can launch runs, cancel them,
+steer them, and approve capability grants. Every rule here exists because the
+failure it prevents is silent: an unauthenticated control plane on a laptop's
+network address is a remote execution service that looks like a dev server.
+
+## One credential, one principal
+
+One shared bearer credential authenticates every mount and binds one identity;
+it is not a per-user or per-run authorization system. Approval decisions have a
+separate host-owned `ApprovalAuthority`, checked before reads/replay and again
+at resolution. The default policy permits only the fixed local identities.
+A gateway bearer needs explicit delegation to approve or deny.
+
+That principal is server-owned, never client-supplied. A configured credential
+stamps `{ id: "gateway", kind: "bearer" }`; a loopback bind with no credential
+runs as `{ id: "local", kind: "operator" }`. A decision journaled under the
+composition's default operator when a bearer holder made it would name the
+wrong one, so `Approval.Submit` reads the authenticated principal and passes it
+through to Control rather than letting the runtime default apply.
+
+Delegating approval to `gateway/bearer` delegates it to every holder of that
+credential. In particular, an agent sharing it has the same approval authority
+as a human. Do not describe such a deployment as independent human approval.
+For finer restrictions, supply a host policy over the authenticated principal,
+target, decision, and scope. Approval policy is not a sandbox for callers with
+arbitrary host code or direct database access.
+
+A credential-free loopback gateway treats all native callers that can reach it
+as the local operator. Host/Origin checks block browser-origin attacks; they do
+not distinguish a human from a local agent that can make its own HTTP requests.
+Use authenticated, independently authorized access and restrict that local
+endpoint when human approval must be independent of the agent.
+
+## Scoped, expiring tokens
+
+The bearer credential is one credential, and it grants everything the gateway
+serves for as long as it is configured. `smthrs token mint --scope read:runs
+--ttl 1h` mints a narrower grant under it: an HMAC-SHA256 token carrying the
+procedures the scopes name, an optional run or flow, and an expiry. The gateway
+verifies it with the credential it already holds and stores nothing, so
+rotating the credential revokes every token minted under it, and nothing else
+does.
+
+The edge admits a scoped token on its signature and expiry alone, because an
+upgrade names no procedure, and only toward `/rpc`, `/projections`, their
+sockets, and `/auth/ticket`; journal sync and the runtime bridge take the
+bearer alone, and a ticket issued against a scoped token opens only the
+sockets the token could open itself. Every RPC frame is then judged in band: a procedure
+the token does not name, a run or flow it does not name, or a call that names
+none when the token is confined, is refused with the same typed `Unauthorized`
+a wrong credential earns. A `Watch` or `Projection.Subscribe` opened before the
+expiry keeps streaming after it, since the check runs when the stream opens;
+end the socket to end the grant.
+
+A scoped token stamps `{ id: "gateway", kind: "scoped" }`. Delegating approval
+to `gateway/bearer` does not delegate it to every token minted from the bearer;
+a host that wants an `approve:runs` token to decide delegates to
+`gateway/scoped` explicitly. The runtime bridge accepts the bearer alone.
+
+## Two rules gate a bind, and both fail closed
+
+1. **A non-loopback host requires an explicit `listen` opt-in.** Binding
+   `0.0.0.0` because a port was free is how a workspace gateway ends up on a
+   shared network by accident.
+2. **A non-loopback bind requires a bearer credential.** Reachable from another
+   machine, an unauthenticated control plane is a remote execution service.
+
+A loopback bind with no credential is allowed, and is the local default.
+Loopback alone does not exclude malicious web pages. Every HTTP request and
+WebSocket upgrade must pass the Host allowlist and, when present, an Origin
+check against the request's authority, including its port. Cross-origin and
+opaque (`null`) origins receive 403 before any RPC runs. Native clients may
+omit Origin. Forwarded headers do not override these checks.
+
+A loopback bind with no credential is allowed, and is the local default. The
+trust boundary there is the machine account, so the ingress guard requires a
+loopback `Host` value. A browser request carrying `Origin` must also carry a
+canonical `http` or `https` origin whose host and port equal that `Host`. That
+rejects cross-site WebSockets and DNS-rebound hostnames without
+requiring a CLI to invent a credential: non-browser clients carrying no
+`Origin` remain accepted.
+The default accepted Host names are `127.0.0.1`, `localhost`, and `[::1]`.
+The Node host also admits a concrete bind host. Network and reverse-proxy
+names must be listed explicitly in `NodeGateway.ServerOptions.allowedHosts`
+(hostnames without ports); wildcard binds do not allow arbitrary Host names.
+`NodeGateway.isLoopbackHost` accepts `127.0.0.1`, `::1`, and `localhost`, and
+nothing else.
+
+`NodeGateway.bindRefusal` answers the policy as a value, so a host can inspect
+it before composing anything. `listenOptions` returns the same refusal in its
+typed effect channel, and `layer` fails through its layer channel. Operating
+system listen failures, an address already in use among them, are mapped to the
+same sanitized `bind_failed` contract, so a caller has one shape to handle.
+
+## Local request identity is checked before authentication
+
+`NodeGateway.layer` enables `IngressOptions.loopbackOnly` whenever no bearer
+credential is configured. Before any route, request body, or WebSocket upgrade
+is handled, `layerIngress` refuses a foreign or absent `Host` with 421
+`invalid_host`. It refuses an `Origin` whose host and port differ from the
+request's `Host`, or that is not a canonical HTTP(S) origin, with 403
+`invalid_origin`.
+
+The Origin header is optional on purpose. Browsers attach it to WebSocket and
+cross-origin requests; CLI clients normally do not. A same-origin Origin and an
+Origin-less request both continue to reach the mount. A bearer-protected
+non-loopback gateway does not enable the loopback `Host` rule, but the Origin
+check still runs there: a browser client is served from the gateway's origin or
+through a same-origin proxy.
+
+## Edge authentication, and where it deliberately stops
+
+`GatewayServer.protectedPaths` is checked before a body is read or an upgrade
+is answered: `/projections`, `/sync`, `/rpc/ws`, `/projections/ws`, and
+`/sync/ws`.
+
+`POST /rpc` is deliberately not on that list. The control mount authenticates
+in band through `ControlRpcs.ControlAuth`, whose declared error is
+`ControlError.Unauthorized`, and that typed control error is the refusal
+[the control plane publishes](/docs/guides/control-plane/): missing, malformed,
+empty, and incorrect credentials all return the same typed error.
+
+An edge 401 answered ahead of the mount would erase that. `ControlClient`
+filters a non-2xx status, so every refusal would reach a caller as a
+`TransportError`: the one class `@smthrs/control` reserves for a request that
+failed _before_ a declared control response reached it. It would also make the
+gateway refuse a call differently from `NodeControl.layerServer` hosting the
+very same `ControlRpcs`.
+
+The body limit still applies to `/rpc`, so an unauthenticated caller buys one
+bounded body read and nothing else.
+
+`/rpc/ws` stays edge-authenticated for a different reason. A socket is a
+resource the server holds open, the RPC middleware can only refuse frames on a
+socket that already exists, and a refused handshake has no RPC channel to
+answer a typed error on. Its refusal is a transport fact either way.
+
+## Browsers open sockets with a single-use ticket
+
+A browser `WebSocket` cannot set an `Authorization` header, and a bearer in a
+query string would land in logs and history. A credentialed gateway therefore
+serves `POST /auth/ticket`: a request carrying an accepted bearer receives
+`{ "ticket": "<64 hex>", "expiresInMs": 30000 }`. The client then opens
+`/rpc/ws`, `/projections/ws`, or `/sync/ws` as `<mount>?ticket=<ticket>`.
+
+- The ticket request passes the same Host and Origin checks as every other
+  request, so a page from another origin cannot mint one.
+- The first upgrade that presents a ticket consumes it, whether or not the
+  upgrade completes. A replay, an unknown ticket, or one presented after 30
+  seconds is refused with 401 `unauthorized`.
+- The socket runs under the bearer the ticket was issued for, so every RPC
+  frame authenticates exactly as it would with the header.
+- A ticket opens only those three sockets. It never unlocks a request/response
+  mount.
+- Tickets live in the gateway's memory; a restart invalidates every
+  outstanding one. At most 1,024 are outstanding; the oldest is dropped first.
+
+A gateway with no bearer credential needs no ticket and does not serve
+`/auth/ticket`.
+
+## A path is classified the way the router will resolve it
+
+The guard runs before the router, so it has to reach the router's verdict. An
+alias it did not recognize would walk past the credential check and the body
+limit and be answered by the mount anyway.
+
+Measured against the `HttpRouter` this package is built on, all of `/%72pc`,
+`/rpc;transport-parameter`, `/rpc/`, `//rpc`, `///rpc`, `/rpc//`, `/RPC`,
+`/./rpc`, and `/foo/../rpc` reach the `/rpc` handler, while `/rpc%2f`,
+`/rpc%3Bp`, `/%2frpc`, and `/rpc%20` do not.
+
+`GatewayServer.routedPath` reproduces that. It resolves dot segments with
+`URL`, takes each segment without its `;` parameter, drops empty segments,
+decodes the rest with `decodeURI`, and compares without regard to case.
+`decodeURI` rather than `decodeURIComponent` is what leaves a reserved
+character encoded, which is what keeps `/rpc%2f` a different path here exactly
+as it is to the router. An invalid escape is left as written, because it names
+no mount either way.
+
+This is not only about crafted aliases. `ControlClient`'s HTTP protocol posts
+every call to `/rpc/`, so a literal comparison skipped the body limit on the
+path `@smthrs/control`'s own client uses.
+
+The normalization errs toward matching: a spelling it resolves to a mount that
+the router then refuses is answered 401 rather than 404, which costs an
+unauthenticated caller nothing it was entitled to.
+
+## Ingress runs before the transport parses anything
+
+`GatewayServer.layerIngress` is one global middleware, and it applies these
+checks in order:
+
+1. Refuses a `Host` outside `allowedHosts`, or a non-loopback `Host` when
+   configured as `loopbackOnly`, with 421 `invalid_host`, then a browser
+   `Origin` whose host and port differ from the request's `Host` with 403
+   `invalid_origin`. These checks cover HTTP and WebSocket upgrades alike.
+2. Refuses an unauthenticated request to a protected path with 401
+   `unauthorized`.
+3. For a `POST` to an RPC mount, refuses a declared `content-length` over the limit with 413
+   `request_too_large`. A body that declares no length is measured as it is
+   read; the Node host destroys its source as soon as it crosses the limit, so
+   a streaming client may observe a connection reset instead of a response.
+4. Refuses a body carrying no RPC request message with 400
+   `malformed_request`.
+
+The fourth check exists because `effect/unstable/rpc` hands every decoded
+message to the server loop, and a body that decodes to something else, `{}`,
+`[]`, prose, or nothing at all, reached it as a message with no tag and died
+there. The gateway answered `500 Internal Server Error` with an empty body,
+which is the wrong half of the contract twice over: it tells an operator the
+gateway broke, and it tells a client to retry a request that can never succeed.
+
+The transport's own parser answers that question, not a second reading of the
+wire format, so whatever `RpcSerialization` the host composed is the one
+authority. A body naming a procedure that does not exist is a _yes_: that is an
+RPC-level defect the protocol itself reports. A binary framing is always a yes,
+because its body is not text and the mount owns it.
+
+## Health carries identity and nothing else
+
+`GET /health` is unauthenticated on purpose. A supervisor decides whether to
+keep or replace a gateway process by asking which workspace it belongs to, and
+a probe that needed a credential could not answer that about a gateway it did
+not start.
+
+The response carries the workspace hash, the gateway id, the protocol version,
+and the package version. It never carries a token, a run, or a path. The
+workspace hash is a digest of the resolved project root rather than the root
+itself, because the path names directories on the operator's machine.
+
+`/health` also answers while the rest of the process is degraded. A gateway
+whose read path cannot read still comes up and still answers the identity
+question, because startup must never be blocked by a subsystem that failed to
+recover.
+
+## A refusal says the least it can
+
+`GatewayError.cause` carries a redacted summary of an internal failure: its tag
+and its stable code, never its message, its nested cause, or the SQL and file
+paths a `PersistenceError` carries. Projection logs contain only an
+allowlisted operation identifier and known control error tag/code pairs. The
+runtime bridge answers with a stable code and logs the full cause of any failure
+the caller did not cause to the host log, so a failed launch can be diagnosed
+from the host.
+
+The reason is the error's reach. `GatewayError` is the RPC error schema, so
+anything left on it is serialized to every bearer holder and forwarded to a
+browser by a relay, and a cause JSON cannot encode would make the error frame
+itself fail to encode.

package/docs/guides/diagnose-a-run.md

@@ -0,0 +1,115 @@
+---
+title: "Diagnose what happened to a run"
+description: "Read the verdict and diagnosis a run summary already carries, or fold your own from a run's control events with the Diagnosis module."
+sidebar:
+  order: 6
+---
+
+Every `run-summary` row already answers "what happened to this run". Two of its
+fields are the whole diagnosis:
+
+- `verdict`: one line, the status plus the reason that most explains it.
+- `diagnosis`: the whole card, folded by `Diagnosis.digest`, which is also
+  what [`smthrs runs show`](/cli/runs) folds. The terminal card adds lines a
+  client does not need, such as the command that unblocks a parked run, so the
+  two read the same facts and print different cards.
+
+A client that renders a run card renders those two strings. Nothing else is
+needed, and nothing has to be recomputed.
+
+```json
+"Verdict   completed \u2014 shipped\nRun       run-1 · deploy · opus · 5s\nActivity  1 turns · 1 calls (0 refused) · edits 1/1\nTokens    0 in / 0 out\nOutput    shipped"
+```
+
+## What the verdict leads with
+
+`Diagnosis.verdict` picks the one thing a reader needs first, in this order:
+
+1. A recorded failure cause, or the fact that a failed run recorded none.
+2. A park's question, so a waiting run says what it is waiting for.
+3. The "worked but never edited" pathology, which a green status would
+   otherwise hide.
+4. The resolved output.
+5. The bare status, when none of the above applies.
+
+```json
+[
+  "failed \u2014 could not resolve seat anthropic:claude-sonnet-4-5",
+  "failed \u2014 no cause recorded in the journal",
+  "waiting-approval \u2014 asks: Write to src/index.ts?",
+  "completed \u2014 but 0 of 12 calls attempted an edit; the run only read",
+  "completed \u2014 shipped"
+]
+```
+
+An unlaunched run, one with no status event at all, reads `unlaunched`.
+Status events use the vocabulary from `ControlSchema.RunStatus.literals`.
+
+## Fold your own
+
+The module is exported, so a client holding a run's ordered control events can
+compute the same facts without a served projection:
+
+```ts
+import * as Diagnosis from "@smthrs/gateway/Diagnosis"
+
+const facts = Diagnosis.digest(events)
+const line = Diagnosis.verdict(facts)
+const card = Diagnosis.render({ runId, flowId }, facts)
+const span = Diagnosis.duration(facts)
+```
+
+`Diagnosis.Digest` carries the status, the failure cause, the model seat, turn
+and call counts, edit attempts and successes, token totals, the refusals
+aggregated by message, the final output, the pending question, and the span the
+events cover.
+
+The fold is total on purpose: an event kind outside its vocabulary contributes
+nothing rather than failing it, and a payload that is not a record reads as an
+empty one. A malformed journal produces a sparse digest, never a throw.
+Unknown kinds include `__proto__`, `hasOwnProperty`, and `toString`; none changes
+the digest or its timestamps. The unknown-kind cases in
+[`Diagnosis.test.ts`](../../test/Diagnosis.test.ts) pin this guarantee.
+
+## What counts as an edit
+
+`editsAttempted` counts calls to the `write`, `edit`, and `apply_patch` flows.
+`editsSucceeded` counts the ones that settled without a failure. That pair is
+what makes the "only read" verdict possible, and it is why a run that reported
+success while touching nothing is visible on its own card.
+
+## What counts as time
+
+Only an event kind the fold handles widens the reported span. This matters
+because the gateway merges a keepalive event into every followed `Watch`
+stream, and a fold that let an unhandled kind contribute its timestamp reported
+a run that ran for as long as somebody watched it.
+
+## Refusals
+
+Failed calls are aggregated by their first-line message, descending by count.
+`Diagnosis.render` prints the top three:
+
+```text
+Refusals  3× permission denied: capability "shell" is not in the envelope
+```
+
+## Clipping text for a wire
+
+`Diagnosis.clip(text, width)` is the truncation the card and the verdict use,
+and it is exported because a client rendering its own summary needs the same
+guarantee. The cut is made on code points, never on UTF-16 code units: slicing
+code units splits an astral character in half and puts a lone surrogate on the
+wire, where a Go decoder silently replaces it and a strict decoder rejects the
+whole frame.
+
+A clipped result is exactly `width` code points, so `width` 1 is the ellipsis
+alone, and `width` 0 or any negative width is the empty string.
+
+## Reading further
+
+`run-tree` and `node-output` answer the next two questions a diagnosis raises:
+which calls the run made, and what one of them produced. Both key their rows by
+the ordinal a call opened on, so a node id from the tree is a node id
+[`smthrs runs output`](/cli/runs) accepts. See
+[Projections](../concepts/projections.md#how-a-node-gets-its-id).

package/docs/guides/follow-a-run.md

@@ -0,0 +1,150 @@
+---
+title: "Follow a run over a WebSocket"
+description: "Subscribe to a projection, read the snapshot and delta frames it answers with, resume from a cursor after a disconnect, and keep an idle connection alive."
+sidebar:
+  order: 3
+---
+
+`Projection.Subscribe` answers a snapshot followed by a live tail. Mount it on
+the socket: `/projections/ws` is where the streaming half of the read path
+belongs, because a request/response route would have to buffer the whole
+stream.
+
+## Subscribe
+
+```ts
+import { Projections } from "@smthrs/gateway/Projections"
+import { Effect, Stream } from "effect"
+
+const frames = Effect.gen(function*() {
+  const projections = yield* Projections
+  return projections.subscribe({ _tag: "run-summary", runId })
+})
+```
+
+Over the wire, the request frame is the same shape as a snapshot's, with
+`Projection.Subscribe` as the tag:
+
+```json
+{
+  "_tag": "Request",
+  "id": 1,
+  "tag": "Projection.Subscribe",
+  "payload": { "selector": { "_tag": "run-summary", "runId": "run-1" } },
+  "headers": []
+}
+```
+
+Send it on `/projections/ws` immediately after the upgrade. The socket is a
+protected path, so a gateway bound with a credential needs
+`Authorization: Bearer <token>` on the upgrade request itself. Node's global
+`WebSocket` cannot set headers on an upgrade, so a credentialed client needs a
+socket library that can, or a relay that adds the header for it.
+
+## Read the frames
+
+```text
+snapshot-start   the snapshot begins, at this cursor
+row              one row of the snapshot, repeated
+snapshot-end     the snapshot is complete
+delta            the selector's rows after one change
+heartbeat        nothing changed, the connection is alive
+```
+
+Three rules make the tail easy to consume:
+
+- **A delta is the whole row set**, recomputed rather than patched. Replace
+  what you hold; do not merge. `run-events` is the exception, because its rows
+  are the events themselves, so its delta is the one event that arrived.
+- **The snapshot and the tail share one reconciled event buffer**, so a client that follows
+  from the advertised cursor sees each later change exactly once.
+- **Every frame but the heartbeat carries its selector**, so several
+  subscriptions can share one socket.
+
+## Resume after a disconnect
+
+Keep the cursor from the last frame of a complete snapshot, or from the last
+delta, and pass it as `after`. The subscription skips the snapshot and answers
+only the deltas past it:
+
+```ts
+const resumed = projections.subscribe({ _tag: "run-summary", runId }, lastCursor)
+```
+
+```json
+{
+  "_tag": "Request",
+  "id": 1,
+  "tag": "Projection.Subscribe",
+  "payload": {
+    "selector": { "_tag": "run-summary", "runId": "run-1" },
+    "after": {
+      "selector": { "_tag": "run-summary", "runId": "run-1" },
+      "projection": "run-summary",
+      "runId": "run-1",
+      "value": 6,
+      "offset": 0
+    }
+  },
+  "headers": []
+}
+```
+
+Send back the cursor exactly as it arrived. It embeds the selector that issued
+it, so a cursor from another selector, another run, or another projection is
+refused with `malformed_request` rather than quietly resuming the wrong thing.
+The full refusal list is in
+[Subscriptions and cursors](../concepts/subscriptions.md#resuming).
+
+Every snapshot frame carries the same cursor: the position the whole read
+reached, not progress through delivery. Buffer the rows from `snapshot-start`
+and commit them, and the cursor, only when `snapshot-end` arrives. If the
+connection drops before `snapshot-end`, discard the partial snapshot and
+re-subscribe without `after`. Resuming from a row you received before the cut
+is accepted, because the cursor is valid, and answers only the deltas past the
+snapshot, so the rows you never received are gone from your view until you
+take a fresh snapshot.
+
+A workspace subscription cannot resume. Re-subscribe without `after` and take
+the snapshot again.
+
+## Keep an idle connection alive
+
+A followed subscription that has nothing to report emits a `heartbeat` every 30
+seconds. A relay cuts an idle tunnel at 600 seconds, so this is what keeps a
+quiet run's followers connected. If something in front of your gateway cuts
+sooner, shorten the cadence at the bind:
+
+```ts
+import * as NodeGateway from "@smthrs/gateway/node/NodeGateway"
+
+const gateway = NodeGateway.layer(health, { host: "127.0.0.1", port: 7331, heartbeatMillis: 10_000 })
+```
+
+One option governs both keepalives: the `Projection.Subscribe` heartbeat on
+`/projections/ws` and the `Watch` keepalive on `/rpc/ws`. Unset, `Watch` beats
+every 30 seconds and the projection socket beats at whatever cadence the
+supplied `Projections` service was built with, which is also 30 seconds for
+`Projections.layer`. To shorten the projection cadence alone, build the read
+path with `Projections.layerWith({ heartbeatMillis: 10_000 })` instead.
+
+`heartbeatMillis` must be a positive safe integer. Zero would turn the
+keepalive into a tight loop, so a composition that asks for it is refused with
+`bind_failed` before anything binds.
+
+## Following the control plane instead
+
+`ControlRpcs.Watch` on `/rpc/ws` follows a run's raw control events rather than
+a projection, and the gateway merges the same kind of keepalive into it. It
+arrives as a `ControlEvent` whose kind is
+`GatewayServer.watchHeartbeatKind`, the literal `control.gateway.heartbeat`,
+because `Watch` has no frame type of its own for a keepalive.
+
+Ignore that kind, as every fold in this package already does with an unknown
+kind. It repeats the last delivered sequence, so resuming from the last
+sequence you saw does not rewind, and it carries the watched run id so routing
+by run keeps working. A snapshot read, `follow: false`, never carries one: it
+has to end.
+
+For what `Watch` itself answers, see
+[Watch a run](/pkg/control/guides/watch-a-run).

package/docs/guides/host-the-gateway.md

@@ -0,0 +1,153 @@
+---
+title: "Host the gateway in your own process"
+description: "Compose NodeGateway.layer with the four services the mounts read through, launch it, and read back the port it bound."
+sidebar:
+  order: 1
+---
+
+`NodeGateway.layer` is the whole gateway on a Node HTTP server. It supplies the
+bind policy, the shared-credential authentication both RPC groups run under,
+and newline-delimited JSON as the wire serialization. Four services stay yours,
+because only a project on disk can provide them.
+
+Reach for this when [`smthrs serve`](/cli/serve) is not the host you want: an
+embedded gateway inside a larger process, a test harness, or a deployment that
+already owns its own storage layer.
+
+## Supply the four services
+
+```ts
+import type * as GatewayServer from "@smthrs/gateway/GatewayServer"
+import * as NodeGateway from "@smthrs/gateway/node/NodeGateway"
+import * as GatewayProjections from "@smthrs/gateway/Projections"
+import type * as Journal from "@smthrs/journal/Journal"
+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"
+
+export const gateway = (
+  health: GatewayServer.Health,
+  options: NodeGateway.ServerOptions,
+  journal: Layer.Layer<Journal.Journal>
+) =>
+  NodeGateway.layer(health, options).pipe(
+    Layer.provide([
+      // The read path, over whatever Control the caller provides.
+      GatewayProjections.layer,
+      // The journal read path. A local gateway publishes no catalog and
+      // shares nothing, so both sync ports are the no-op implementations.
+      SyncServer.layer.pipe(Layer.provide([journal, RunCatalog.layerNoop])),
+      SyncAuth.layer.pipe(Layer.provide(WorkspaceShare.layerNoop))
+    ])
+  )
+```
+
+The journal is the host's own, so [`@smthrs/journal`](/api/journal) is a
+dependency you add rather than one this package installs for you.
+
+Those three provisions discharge every gateway input except `Control`, which
+stays a requirement on purpose: a host should serve the same control plane its
+own code talks to rather than opening a second one over the same database.
+Provide it last, from `ControlLive.layer` over your control runtime. See
+[Serve the control plane over RPC](/pkg/control/guides/serve-over-rpc).
+
+`GatewayProjections.layer` reads through the ambient `Control`, so it inherits
+whatever you provide. When a relay in front of you cuts idle connections sooner
+than 600 seconds, set `heartbeatMillis` at the bind, which re-times both the
+projection heartbeat and the `Watch` keepalive, or use
+`GatewayProjections.layerWith({ heartbeatMillis })` to shorten the projection
+heartbeat alone.
+
+## The health identity
+
+`NodeGateway.layer` takes the identity `GET /health` will answer with. It is
+`GatewaySchema.GatewayHealth` plus the version of the package serving it:
+
+```ts
+import type * as GatewayServer from "@smthrs/gateway/GatewayServer"
+import { createHash } from "node:crypto"
+import { resolve } from "node:path"
+
+/** A stable short hash of the project root, so the path is never published. */
+const workspaceHash = (root: string): string => createHash("sha256").update(resolve(root)).digest("hex").slice(0, 16)
+
+export const health = (root: string, version: string): GatewayServer.Health => ({
+  workspaceHash: workspaceHash(root),
+  gatewayId: `host-${process.pid}`,
+  protocolVersion: "1",
+  version
+})
+```
+
+Derive `workspaceHash` from the workspace and from nothing else. A supervisor
+that finds a gateway already on a port asks `/health` whether it is this
+workspace's before deciding to keep or replace it, and an identity derived from
+anything else cannot answer that.
+
+## Launch it
+
+The layer is the server. Launching it serves until the fiber is interrupted:
+
+```ts
+import { Effect, Layer } from "effect"
+
+const program = Layer.launch(gateway(health(root, "1.0.0-rc.0"), { host: "127.0.0.1", port: 7331 }, journal))
+
+Effect.runFork(program.pipe(Effect.provide(control)))
+```
+
+`NodeGateway.defaultServerOptions` is `{ host: "127.0.0.1", port: 7331 }`. The
+CLI binds port 3000 instead; neither is privileged, and the port is yours to
+choose.
+
+## Read back the port you got
+
+The returned layer retains the concrete `HttpServer` service, so a caller that
+bound port 0 can read the ephemeral address the operating system gave it. This
+is what a test harness wants:
+
+```ts
+import { Effect } from "effect"
+import { HttpServer } from "effect/unstable/http"
+
+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}`
+})
+```
+
+## Refuse a bad bind before you compose
+
+Policy refusals and operating system listen failures both fail the layer as
+sanitized `bind_failed` `GatewayError` values. A host that would rather report
+a refusal than fail a layer asks first:
+
+```ts
+import * as NodeGateway from "@smthrs/gateway/node/NodeGateway"
+
+const refusal = NodeGateway.bindRefusal({ host: "0.0.0.0", port: 7331 })
+// GatewayError {
+//   code: "bind_failed",
+//   message: "Refusing non-loopback gateway bind 0.0.0.0 without an explicit --listen opt-in"
+// }
+```
+
+`bindRefusal` answers the same value `listenOptions` fails with and `layer`
+fails through, so there is one rule and one message, not a copy per call site.
+The rules themselves are in [Serve beyond loopback](./serve-beyond-loopback.md).
+
+## Mount only part of the surface
+
+`GatewayServer` exposes each mount as its own layer for a host that assembles
+its own router: `layerControlHttp`, `layerProjectionsHttp`, `layerSyncHttp`,
+`layerHealth`, and `layerIngress`. `GatewayServer.layer` is those five merged,
+and `NodeGateway.layer` is that plus a socket, a serialization, and an
+authentication layer.
+
+Splitting them is for hosts with an existing router, not for dropping a mount:
+the ingress guard reads `rpcPaths` and `protectedPaths`, which name all three
+RPC mounts, and a surface that serves fewer of them still pays the same guard.