@gjermundgaraba/effect-actions 0.18.2 → 0.19.0

package/docs/ActionHttp.md

@@ -4,72 +4,36 @@ JSON `POST` routes on Effect's `HttpApi`, one per action. `ActionHttp.make` bind
 mount path; the server mounts that one binding, every client calls it and the OpenAPI document is
 generated from it.
 
-Read this page alone, in one tool call; if its output says it was truncated, read it again alone.
-When something fails, search [ActionHttp-failures.md](ActionHttp-failures.md). Reading order:
-[README.md](README.md).
-
-## API
-
-Import `@gjermundgaraba/effect-actions/ActionHttp`.
-
-| API                                      | Purpose                                                                 |
-| ---------------------------------------- | ----------------------------------------------------------------------- |
-| `make(actions, options?)`                | Bind a list of actions; returns a `Binding`.                            |
-| `Http.actions`                           | The bound actions.                                                      |
-| `Http.error`                             | The errors every endpoint declares besides its action's own, as a list. |
-| `Http.prefix`                            | Where the routes mount.                                                 |
-| `Http.authentication`                    | Its protected actions' authentication descriptor, or `undefined`.       |
-| `Http.api`                               | The native `HttpApi`, for OpenAPI and Effect's own tools.               |
-| `layer(Http, implementations, options?)` | Mount the routes of the bound actions the implementations hold.         |
-| `client(Http, options?)`                 | An Effect of a typed client; requires the native `HttpClient`.          |
-| `fetchClient(Http, options?)`            | The same client over `fetch`, built outside an Effect.                  |
-
-Exported types: `Binding`; `Any`, any binding; `Client<typeof Http>`, a client's type;
-`MethodError`, what one of its calls fails with; `Options` of `make`, `LayerOptions`,
-`ClientOptions` and `FetchClientOptions`.
-
-| Option                      | Meaning                                                                                           |
-| --------------------------- | ------------------------------------------------------------------------------------------------- |
-| `make`: `prefix`            | Mount path of every route; defaults to `/api`. `/` mounts at the root.                            |
-| `make`: `error`             | What middleware around the routes answers with, one schema or a list; every endpoint declares it. |
-| `make`: `authentication`    | The protected actions' descriptor, `Authentication.make(...)`; required with a protected action.  |
-| `layer`: `actions`          | The bound actions it serves: `[GetUser]`. Defaults to every one the implementations hold.         |
-| `layer`: `middleware`       | Native `HttpApiMiddleware` around every route it serves, the first innermost.                     |
-| `client`: `baseUrl`         | What routes resolve against: `https://api.example.com`. Omitted: relative ones, a page's origin.  |
-| `client`: `transformClient` | Wraps the native `HttpClient`: a token, or a sign-in per request, whose failures each call adds.  |
-| `fetchClient`: `fetch`      | Its `fetch`, beside `client`'s options. Omitted: the global `fetch`, looked up on every call.     |
-
-Each action is served at `POST <prefix>/<action>`, a `readOnly` one too. One without `success`
-answers an empty 200, with no body and no content type, so a hand-written client must not parse
-it. One without `input` still takes the body `{}`, typed as JSON. Statuses and bodies:
-[guarantees.md](guarantees.md#wire-behavior).
+A message the library throws says its fix; for a compiler diagnostic or Effect's own error, search
+[ActionHttp-failures.md](ActionHttp-failures.md). For one symbol,
+`grep -rn <symbol> node_modules/@gjermundgaraba/effect-actions/dist/`: each declaration's JSDoc
+carries its rules and gotchas, and this page only what an example cannot show.
 
 ## Bind actions to routes
 
-Call `ActionHttp.make` once, in a file that imports contracts and no server code, and export the
-binding: the server, every client, the CLI and the tests import that one value.
+Call `ActionHttp.make` once, in a contract-only file, and export the binding:
 
-```ts
+```ts example=notes-service/src/Api.ts
+import * as ActionHttp from "@gjermundgaraba/effect-actions/ActionHttp";
+import { Login, WhoAmI } from "./identity/Identity.js";
+import { Notes } from "./notes/Notes.js";
+import { GetStatus } from "./status/Status.js";
+
+// The HTTP binding: every action at `POST /api/<name>`, the protected ones requiring `Login`.
+// It is plain data and imports no server code, so the server, the CLI and a browser page all
+// import this one value, and each gets its routes or its typed methods from it. An action
+// added here is also a `notes` command: commands.ts derives one per action of this binding.
 export const Http = ActionHttp.make([GetStatus, ...Notes, WhoAmI], {
   prefix: "/api",
   authentication: Login,
 });
 ```
 
-Files: [quickstart/src/Api.ts](../examples/quickstart/src/Api.ts) (public actions, no options),
-[notes-service/src/Api.ts](../examples/notes-service/src/Api.ts) (protected actions),
-[kitchen-sink/src/Api.ts](../examples/kitchen-sink/src/Api.ts) (`prefix`, `error`, two bindings).
-
-- To keep an action off HTTP, leave it out of the binding; its implementation may still serve
-  it as a tool or a command.
-- A binding holding a protected action names its descriptor
-  ([Authentication.md](Authentication.md#declare-how-callers-sign-in)), and has only one: a
-  second identity gets a second binding with its own `prefix`. A public action may be in both.
-- `error` declares what middleware answers with on any route, such as a quota's 429. An error a
-  handler fails with goes in its action's `error`
-  ([Action.md](Action.md#fail-with-declared-and-built-in-errors)).
-- Action names are unique within a binding. Split a large API, or two actions sharing a name,
-  into one binding per area, each with its own `prefix` and client; one host serves them all.
+[quickstart/src/Api.ts](../examples/quickstart/src/Api.ts) binds public actions with no options;
+[kitchen-sink/src/Api.ts](../examples/kitchen-sink/src/Api.ts) gives `prefix` and `error` and makes
+two bindings, one per identity. What every endpoint declares is on `ActionHttp.make`, the rules of
+`prefix`, `error` and `authentication` on `ActionHttp.Options`, and a protected action's descriptor
+in [Authentication.md](Authentication.md#declare-how-callers-sign-in).
 
 ## Serve the routes
 
@@ -78,102 +42,146 @@ routes, provide the descriptor's provider
 ([Authentication.md](Authentication.md#verify-credentials)), and serve the result with
 `HttpRouter.serve`.
 
-```ts
+```ts example=notes-service/src/routes.ts
+import { Layer } from "effect";
+import { HttpRouter, HttpServerResponse } from "effect/http";
+import { OpenApi } from "effect/http-api";
+import * as ActionHttp from "@gjermundgaraba/effect-actions/ActionHttp";
+import * as ActionMcp from "@gjermundgaraba/effect-actions/ActionMcp";
+import { Http } from "./Api.js";
+import { identity } from "./identity/handlers.js";
+import { Login } from "./identity/Identity.js";
+import { authenticate } from "./identity/verifier.js";
+import { notes } from "./notes/handlers.js";
+import { status } from "./status/handlers.js";
+
+// Every domain's implementation, once. Each surface below takes the same list.
+const implementations = [status, notes, identity];
+
+// JSON routes at `/api/<action>`, the binding's; `getStatus` answers anyone.
 const api = ActionHttp.layer(Http, implementations);
 
-export const routes = Layer.mergeAll(api, mcp, health, openApi).pipe(Layer.provide(authenticate));
+// The host's own routes sit beside the actions' on the same router.
+const health = HttpRouter.add("GET", "/healthz", HttpServerResponse.text("ok"));
+
+// Served to anyone, which is a choice: it tells a signed-out caller every action's name and
+// shape. To keep them, leave the route out, or provide `Authentication.protect(Login).layer`
+// to it.
+const openApi = HttpRouter.add(
+  "GET",
+  "/api/openapi.json",
+  HttpServerResponse.jsonUnsafe(OpenApi.fromApi(Http.api)),
+);
+
+// What the host serves: the JSON routes, the same actions as MCP tools at `/mcp`, and the host's
+// own routes. The MCP endpoint serves the public `getStatus` beside the protected tools, so a
+// signed-out 2026-07-28 client may list the tools and call `getStatus`; what else needs a token
+// is on `ActionMcp.LayerHttpOptions.authentication`. It still requires `NoteStore`: the
+// entrypoint chooses which one, and a test chooses its own. The entrypoint also chooses how the
+// MCP endpoint runs: one server for every request, or one per request.
+const serving = (requestScoped: boolean) =>
+  Layer.mergeAll(
+    api,
+    ActionMcp.layerHttp(implementations, {
+      name: "notes-service",
+      version: "1.0.0",
+      instructions: "Notes belong to the signed-in user. Read a note before updating it.",
+      authentication: Login,
+      requestScoped,
+    }),
+    health,
+    openApi,
+  ).pipe(Layer.provide(authenticate));
+
+export const routes = serving(false);
+
+export const requestScopedRoutes = serving(true);
 ```
 
-Files: [quickstart/src/routes.ts](../examples/quickstart/src/routes.ts) and
-[quickstart/src/server.ts](../examples/quickstart/src/server.ts);
-[notes-service/src/routes.ts](../examples/notes-service/src/routes.ts) and
-[notes-service/src/server.ts](../examples/notes-service/src/server.ts).
-
-- Pass every surface the same list of implementations: the layer serves the binding's actions
-  among them. Beside rpcs, one provider and one header decoding serve both
-  ([ActionRpc.md](ActionRpc.md#serve-the-rpcs), "The same actions as JSON too";
-  [kitchen-sink/src/server.ts](../examples/kitchen-sink/src/server.ts)).
-- A service a handler or an authorizer reads per request stays owed by the layer until router
-  middleware around it, `HttpRouter.provideRequest` or the layer's own `middleware` provides it.
-  Router middleware is the one that reads the request, such as a header:
-  `HttpRouter.middleware<{ provides: Tenant }>()((route) => …)`, given as
-  `Layer.provide(resolveTenant.layer)`
-  ([kitchen-sink/src/workspaces/tenant.ts](../examples/kitchen-sink/src/workspaces/tenant.ts)).
-  Without the type argument it runs and the layer still owes the service.
-  `HttpRouter.provideRequest(layer)` builds its layer once, at startup, and gives every request
-  that one value: never an identity or a tenant
-  ([Action.md](Action.md#say-who-may-call-an-action)).
-- Give the server a `host`: `NodeHttpServer.layer(createServer, { port })` without one listens on
-  every interface. The examples bind `127.0.0.1`.
-- Two listeners are two `HttpRouter.serve` calls, each building its routes on its own. What they
-  share is provided outside both
-  ([Action-in-process.md](Action-in-process.md#share-one-build-across-servers),
-  [kitchen-sink/src/server.ts](../examples/kitchen-sink/src/server.ts)).
-
-Set a request body limit: a body has none unless the host provides one to `HttpRouter.serve`, as
-below. It covers every route of the server, MCP endpoints included, except a body a route reads
-as a stream. On Node (`NodeHttpServer`), a request over it gets no response, not a 413: its connection is
-closed. `HttpRouter.toWebHandler` ignores it, so limit bodies in the platform serving the handler.
-
-```ts
-Layer.provide(Layer.succeed(HttpServerRequest.MaxBodySize, ByteSize.mebibytes(1))),
+The smallest routes are [quickstart/src/routes.ts](../examples/quickstart/src/routes.ts). What
+each route answers and what an `ErrorReporter` is given are on `ActionHttp.layer`.
+
+The entrypoint serves the routes, with a request body limit; what that limit covers is on
+`ActionHttp.layer`.
+
+```ts example=notes-service/src/server.ts
+import { createServer } from "node:http";
+import { NodeHttpServer, NodeRuntime } from "@effect/platform-node";
+import { ByteSize, Config, Effect, Layer } from "effect";
+import { HttpRouter, HttpServerRequest } from "effect/http";
+import { NoteStore } from "./notes/store.js";
+import { routes } from "./routes.js";
+
+// Entrypoint: `node --import tsx examples/notes-service/src/server.ts`.
+// It chooses the store, reads the configuration and starts Node's HTTP server.
+const server = Layer.unwrap(
+  Effect.gen(function* () {
+    // The loopback default serves this machine alone; HOST=0.0.0.0 lets others reach it.
+    const host = yield* Config.String("HOST").pipe(Config.withDefault("127.0.0.1"));
+    const port = yield* Config.Port("PORT").pipe(Config.withDefault(3000));
+
+    return HttpRouter.serve(routes).pipe(
+      Layer.provide(NodeHttpServer.layer(createServer, { host, port })),
+      // Request bodies have no size limit unless the host sets one. This covers every route that
+      // reads its body whole.
+      Layer.provide(Layer.succeed(HttpServerRequest.MaxBodySize, ByteSize.mebibytes(1))),
+      // DEMO ONLY: notes live in this process's memory; a deployment provides a store that lasts.
+      Layer.provide(NoteStore.layerMemory),
+    );
+  }),
+);
+
+Layer.launch(server).pipe(NodeRuntime.runMain);
 ```
 
-An `ErrorReporter` the server runs with is also given, with severity `Info`, what a handler
-or `authorize` fails with and an input that does not decode, a declared 404, a 403 or a 400:
-Effect's `HttpApi` reports a route's failures, of which a refused credential is none. MCP and
-RPC report a defect alone. To keep a declared error out of a tracker, give its class
-`override readonly [ErrorReporter.ignore] = true`; a built-in error takes no mark, so drop
-`Info` there.
+- A service a verifier, handler or authorizer reads per request is provided by router middleware
+  around the layer
+  ([kitchen-sink/src/workspaces/tenant.ts](../examples/kitchen-sink/src/workspaces/tenant.ts),
+  read by the verifier, provided in
+  [kitchen-sink/src/routes.ts](../examples/kitchen-sink/src/routes.ts)), or, for a handler or
+  authorizer, by `ActionHttp.LayerOptions.middleware`; declaring it, and why not
+  `HttpRouter.provideRequest`, are on `ActionHttp.layer`.
 
 ### Split a binding across layers, and add middleware
 
-Several layers may serve one binding, each with its own `actions` and `middleware`; serve each
-action from exactly one. Files:
+Serve each action from exactly one layer. Files:
 [kitchen-sink/src/routes.ts](../examples/kitchen-sink/src/routes.ts) (`api`),
-[kitchen-sink/src/identity/quota.ts](../examples/kitchen-sink/src/identity/quota.ts).
-
-| Where                                                | Runs                                     | Use it for                                                 |
-| ---------------------------------------------------- | ---------------------------------------- | ---------------------------------------------------------- |
-| Global router middleware                             | before routing, on every route           | a Host or Origin policy, CORS                              |
-| Router middleware provided to a `layer` call         | around its routes, before authentication | a per-request service; a limit on unauthenticated requests |
-| The layer's `middleware`                             | after authentication, before decoding    | a limit keyed by the caller, counting invalid input too    |
-| The handler ([Action.md](Action.md#authorize-calls)) | after decoding and the authorizer        | a limit that holds on every surface, MCP included          |
-
-- A layer middleware requiring the identity needs a layer serving protected actions only. Serve
-  the public actions from a second layer without it.
-- Router middleware answering with a binding error encodes and sends it itself,
-  `HttpServerResponse.schemaJson(QuotaExceeded)(error, { status: 429 })`, at the error's
-  `httpApiStatus`, or 422 without one: at any other status the client fails with an
-  `HttpClientError`.
-- A request policy that must run before authentication and OAuth discovery:
-  [Authentication-advanced.md](Authentication-advanced.md#run-a-request-policy-before-authentication).
+[kitchen-sink/src/identity/quota.ts](../examples/kitchen-sink/src/identity/quota.ts). Where a
+check runs decides what it sees:
+
+| Where                                                    | Runs                                     | Use it for                                                 |
+| -------------------------------------------------------- | ---------------------------------------- | ---------------------------------------------------------- |
+| Global router middleware                                 | before routing, on every route           | a Host or Origin policy, CORS                              |
+| Router middleware provided to an `ActionHttp.layer` call | around its routes, before authentication | a per-request service; a limit on unauthenticated requests |
+| `ActionHttp.LayerOptions.middleware`                     | after authentication, before decoding    | a limit keyed by the caller, counting invalid input too    |
+| The handler ([Action.md](Action.md#authorize-calls))     | after decoding and the authorizer        | a limit that holds on every surface, MCP included          |
+
+What router middleware answering with a binding error must send is on `ActionHttp.Options.error`.
+A request policy that must run before authentication and OAuth discovery:
+[Authentication-advanced.md](Authentication-advanced.md#run-a-request-policy-before-authentication).
 
 ### Publish the OpenAPI document
 
 Give `Http.api`, a plain `HttpApi`, to `OpenApi.fromApi`, `HttpApiSwagger.layer` or
-`HttpApiScalar.layer`, on routes of the host's own. Files:
-[notes-service/src/routes.ts](../examples/notes-service/src/routes.ts) (`openApi`),
-[kitchen-sink/src/routes.ts](../examples/kitchen-sink/src/routes.ts) (`documentation`).
-
-- The document's route is public unless you put middleware around it.
-- A header that middleware reads is not in the document: its operations list no `parameters`.
-  Add it by rewriting the document,
-  `OpenApi.fromApi(Http.api.annotate(OpenApi.Transform, (document) => …))`, or make the value an
-  input.
-- The document and the clients list every action of the binding, served or not. An action no
-  layer serves answers 404.
-- An OAuth protected resource is documented as a bearer scheme: Effect has no OAuth scheme
-  ([Authentication.md](Authentication.md#publish-oauth-discovery)).
-- Serve the binding with `ActionHttp.layer`, never with the native `HttpApiBuilder`.
-- One document over several bindings, `HttpApi.make("app").addHttpApi(A.api).addHttpApi(B.api)`,
-  works only when their prefixes differ and no action name repeats. Otherwise document each alone.
+`HttpApiScalar.layer`, on routes of the host's own: `openApi` above,
+[kitchen-sink/src/routes.ts](../examples/kitchen-sink/src/routes.ts) (`documentation`). What the
+document holds and omits is on `ActionHttp.Binding.api`.
 
 ## Call the API from Effect
 
-`ActionHttp.client` yields a client with one method per action.
+What a call fails with is on `ActionHttp.client`, and a token or a per-request sign-in goes
+through `ActionHttp.ClientOptions.transformClient`.
 
-```ts
+```ts example=quickstart/src/client.ts
+import { NodeRuntime } from "@effect/platform-node";
+import { Console, Effect } from "effect";
+import { FetchHttpClient } from "effect/http";
+import * as ActionHttp from "@gjermundgaraba/effect-actions/ActionHttp";
+import { Http } from "./Api.js";
+
+// Entrypoint: `node --import tsx examples/quickstart/src/client.ts`, with the server running.
+// One typed method per action of the binding.
+// DEMO ONLY: a deployed client reads its `baseUrl` from configuration (kitchen-sink/src/seed.ts).
 Effect.gen(function* () {
   const client = yield* ActionHttp.client(Http, { baseUrl: "http://127.0.0.1:3000" });
 
@@ -181,30 +189,11 @@ Effect.gen(function* () {
 }).pipe(Effect.provide(FetchHttpClient.layer), NodeRuntime.runMain);
 ```
 
-Files: [quickstart/src/client.ts](../examples/quickstart/src/client.ts),
-[kitchen-sink/src/seed.ts](../examples/kitchen-sink/src/seed.ts) (`baseUrl` from `Config`,
-headers, errors by tag).
-
-- Outside a browser, set `baseUrl`. A token or any other header goes through `transformClient`:
-  `HttpClient.mapRequest(HttpClientRequest.bearerToken(token))`. A credential read or refreshed
-  as each request is sent, which may fail, is
-  `(client) => HttpClient.mapRequestEffect(client, authorize)`: each call then also fails with
-  `authorize`'s own errors, as they are, and requires its services. `ActionMcp.client` takes the
-  same transform, and `ActionCli.remote` the client itself as its `client`.
-- Leave the argument out when `{}` is a valid input. A given argument is the decoded input, so
-  it states a defaulted field.
-- A declared error is a typed failure, as its decoded value: the action's own, the binding's,
-  the verifier's, and the built-in `InvalidInput`, `Unauthenticated` and `Forbidden`. Handle
-  each with `Effect.catchTag`.
-- Anything else is Effect's own: an `HttpClientError` when the server could not be reached or
-  answered with a status or body the binding does not declare, such as a defect's empty 500; a
-  `SchemaError` when the success does not decode.
-- The client interprets no status and retries nothing. A failed write may have happened; only a
-  declared error says what the server did.
-- A handler calling another service through this client maps that service's `Unauthenticated`
-  and `Forbidden` before failing with them
-  ([Action.md](Action.md#fail-with-declared-and-built-in-errors)).
-- In a test, provide `Testing.layer(routes)` instead of a network client and leave `baseUrl` out
+[kitchen-sink/src/seed.ts](../examples/kitchen-sink/src/seed.ts) reads `baseUrl` from `Config`,
+sends headers and handles errors by tag. `ActionMcp.client` takes the same `transformClient`, and
+`ActionCli.remote` the unyielded `ActionHttp.client(Http, …)` as its `client`.
+
+- In a test, provide `Testing.layer(routes)` instead of a network client
   ([Testing.md](Testing.md#test-routes-in-memory),
   [notes-service/test/routes.test.ts](../examples/notes-service/test/routes.test.ts)).
 
@@ -215,21 +204,6 @@ with `Effect.runPromise`. Files:
 [notes-service/src/browser.ts](../examples/notes-service/src/browser.ts),
 [kitchen-sink/src/sdk.ts](../examples/kitchen-sink/src/sdk.ts) (a `baseUrl`, two headers).
 
-- A page on another origin passes `baseUrl`, and the server must allow that origin with
-  `HttpRouter.cors`
-  ([kitchen-sink/src/request-policy.ts](../examples/kitchen-sink/src/request-policy.ts), `cors`).
-- A `transformClient` requiring a service, such as the session's token, makes each call require
-  it: provide it on the call before `Effect.runPromise`.
-- An unhandled declared error rejects the promise as its decoded value, so
-  `error instanceof Action.Unauthenticated` works in a `catch`. Handle an expected one by its tag
-  before `Effect.runPromise`.
-- A page on the API's own origin sends its cookies already. From another origin, pass `fetch`:
-  `(input, init) => fetch(input, { ...init, credentials: "include" })`, and allow credentials in
-  the server's CORS, `HttpRouter.cors({ allowedOrigins, credentials: true })`. A `fetch` of your
-  own keeps `init.signal`, which aborts the request when its call is interrupted: a deadline is
-  `Effect.timeout` on the call.
-- A route answers a request not typed as JSON with 415, so what another site's page can send
-  without a CORS preflight, such as a form post carrying the user's cookie, never reaches a
-  handler; the server's CORS policy decides the rest.
-- The page imports the binding from a module with no server code
-  ([setup.md](setup.md#bundle-for-a-browser)).
+- A page on another origin needs the server to allow it with `HttpRouter.cors`; sending cookies
+  from there is on `ActionHttp.FetchClientOptions.fetch`.
+- Bundling the page: [setup.md](setup.md#bundle-for-a-browser).

package/docs/ActionMcp-failures.md

@@ -1,36 +1,16 @@
 # ActionMcp failure modes
 
-Search for a fragment of the message. The tasks are in [ActionMcp.md](ActionMcp.md).
+What you see when something is wrong, and the fix. Search for a fragment of the message. The tasks are in [ActionMcp.md](ActionMcp.md).
 
-- `MCP tool input must be one object with keys, such as a struct: <name>, ...`: those actions' input is a union, an array, a scalar, or an object without keys such as `Schema.Struct({})`. Wrap it in a field, `input: { notification: Schema.Union([Email, Sms]) }`, omit `input` for no arguments, or leave the action out of `actions`.
-- `MCP media must be the success or an array of it, or a top-level field of a struct success, one, optional or a required array: <name>, ...`: those actions hold an `Action.Image` no tool can send as a block. Make it a top-level field of a `Schema.Struct` success, give an optional array as a required one, empty when absent, or leave the action out of `actions`.
-- `Duplicate MCP tool: <name>`: two implementations serve actions of one name. Split the endpoint or rename one. `actions` tells apart only separate contracts sharing a name; of two implementations of one contract, pass one.
-- `Duplicate MCP tool: <name>, claimed by an action and a native feature`, a defect when the endpoint builds: a native tool among `features` has an action's name. Rename it, or leave the action out of `actions`.
-- `Listed in actions, but no implementation holds it: <names>`: those actions are not among the implementations', by identity. `(another contract)` marks one whose name an implementation holds, as a second copy of the contracts module makes. Pass the implementation holding it, or list the contract it implements.
-- `Property 'authentication' is missing` on `layerHttp`'s options: the endpoint serves a protected action and names no descriptor. `Type 'Other' is not assignable to type 'CurrentUser'` on `authentication`: the descriptor is another identity's. Give the protected actions' descriptor.
-- `Authentication "<name>": the binding's descriptor is not its provider's`, a defect when `layerHttp` builds: give the endpoint the descriptor its provider was built from ([Authentication-failures.md](Authentication-failures.md)).
-- `Type 'X' is not assignable to type 'never'` where the server is launched, or `Request<"Requires", X>` in an MCP endpoint's type: a handler or an authorizer yields a request service no middleware around the endpoint provides. Provide it with router middleware; never an identity at startup. `X` the identity, on an endpoint serving public tools: a public handler reads it, which no public tool gets, signed in or not. Make that action protected.
+- `Type 'X' is not assignable to type 'never'` where the server is launched, or `Request<"Requires", X>` in an MCP endpoint's type: a handler or an authorizer yields a request service no middleware around the endpoint provides. Provide it with router middleware. `X` the identity, on an endpoint serving public tools: a public handler reads it, which no public tool gets, signed in or not. Make that action protected.
 - `Type 'CurrentUser' is not assignable to type 'never'` where the server is launched, with `CurrentUser` among an MCP endpoint's startup requirements, not its `Request<"Requires", ...>`: a native feature reads a request service, which features never receive. Serve that content as an action.
 - `Type 'CurrentUser' is not assignable to type 'never'` at a stdio program's `runMain`: it serves a protected tool, whose caller the host supplies. Provide the identity around `runStdio`.
-- A native resource, prompt or toolkit layer is never served (`resources/list` is empty, `prompts/list` is not found, `tools/list` lists only the actions): an endpoint serves only the native layers passed as its `features`; one merged beside it builds without error. Pass it as `features`.
-- A prompt or resource demands credentials: on an endpoint naming `authentication`, every prompt and resource request needs one. Serve them on an endpoint without protected tools.
-- A public tool's call answers 401: a public tool needs no credential, but one a request presents is still verified, and this one failed. Send a valid one, or none.
-- A protected tool's call answers 401 to a signed-in client after a while: its token expired. The client refreshes it, or signs in again, on the challenge's `invalid_token`.
-- An MCP client gets an `isError` refusal, not the 401 or 403 it re-authorizes on: the handler sent a notification first, which starts the response, so its refusal is a tool result. Refuse in `authorize`.
-- A client that opens with `initialize` gets 401 where it lists the tools or calls a public one, on an endpoint that also serves protected tools: a session's every request authenticates. Sign the client in, or serve the public tools on an endpoint of their own.
 - A client that opens with `initialize`, such as Codex, gets 400 with JSON-RPC error `-32020`, `MCP-Protocol-Version header is required`, or 401 signed out where the endpoint serves a protected tool, and a `DELETE` gets 405: the endpoint is `requestScoped`, which speaks MCP 2026-07-28 alone and keeps no session. Connect that client to an endpoint without it, on a host that keeps a process running.
 - `subscriptions/listen` answered with JSON-RPC error `-32601`, Method not found: an endpoint without `features` has no 2026-07-28 subscriptions unless `allowSubscriptions` is `true`, and a `requestScoped` one has none. Pass `true` where a handler changes the server through `McpServer.McpServer`.
 - A request over HTTP answers 400, `MCP-Session-Id header is required; send initialize to start a session`: its `MCP-Protocol-Version` header is absent or names a 2025 revision, so it is a session's request, and it follows no `initialize`. One answering 404 names a session that ended, or one of a process since restarted: the client opens another.
 - A hand-written HTTP request answers 400 with JSON-RPC error `-32602`, `Required request metadata is missing` or `io.modelcontextprotocol/clientCapabilities request metadata is required`: it names 2026-07-28 in `MCP-Protocol-Version` and its `params._meta` lacks `io.modelcontextprotocol/protocolVersion`, for the first message, or `io.modelcontextprotocol/clientCapabilities`, for the second. Build it with `ActionMcp.request`, or copy the `curl` of [mcp-tools](../examples/mcp-tools/README.md#connect-a-client).
 - A hand-written HTTP request answers 400 with JSON-RPC error `-32020`, `MCP-Protocol-Version header is required`, `Mcp-Method header does not match request method` or `Mcp-Name header does not match request parameters`: those headers repeat a 2026-07-28 request's revision, method and `tools/call` name, and one is absent or differs from its body. Build it with `ActionMcp.request`.
 - A hand-written HTTP request answers an empty 406: its `Accept` header does not list both `application/json` and `text/event-stream`, as `*/*` does not. Send both.
-- A client asking for 2025-03-26 or 2024-11-05 is offered 2025-11-25, and disconnects if it cannot speak it: HTTP and stdio serve 2026-07-28, 2025-11-25 and 2025-06-18, a `requestScoped` endpoint 2026-07-28 alone. Update the client.
 - A request written by hand to a stdio server answers JSON-RPC error `-32602`, `Invalid request metadata`: it is neither preceded by `initialize` nor carries the 2026-07-28 metadata. Open with `initialize` and `notifications/initialized`, or give the request's `_meta` its `io.modelcontextprotocol/protocolVersion` and `io.modelcontextprotocol/clientCapabilities`.
-- A client reports a broken transport from a stdio subprocess: something wrote to stdout. The global `console.log` did, or a layer provided around `runStdio` did, through the default logger, or through `Console` or a logger such as `Logger.consoleJson`, which `logToStderr` does not move. Remove the write, apply `ActionCli.logToStderr` last, or log JSON with `Logger.withConsoleError(Logger.formatJson)`.
-- A request carrying an `Origin` gets an empty 403: the origin is not in `allowedOrigins`. Add the exact origin, if the deployment trusts it.
-- A disallowed `Origin` gets 401, not 403: the endpoint's authentication, which runs before its Origin check, refused the request.
-- Browser calls fail despite an allowed origin, the preflight answering 405, or 401 on an endpoint with `authentication`, which every method but `POST` meets first: `allowedOrigins` is no CORS. Add `HttpRouter.cors` ([browser clients](ActionMcp.md#allow-browser-clients)).
 - `Tool <name> has an output schema but did not return structured content` raised by a Python MCP client for an action that returns nothing: its success is sent as `null`, which a Python SDK release before the fix of python-sdk#3345 reads as missing. Update the SDK.
-- `MCP tools/call "<name>" answered 404`: the endpoint is not at `/mcp`, the default. Pass `ActionMcp.client` its `url`.
-- `MCP tools/call "<name>" returned an error: Invalid parameters for tool ...`: the endpoint serves another contract under that name. Pass `ActionMcp.client` the served contract value.
 - `UrlError` from `HttpClientRequest.toWebResult` or `toWeb` of an `ActionMcp.request`, or an `HttpClientError` whose reason is `InvalidUrlError` from a client method or a sent `ActionMcp.request`: the `url` is relative, such as the default `/mcp`, which only the `HttpClient` of `Testing.layer` resolves. Pass an absolute one.