@gjermundgaraba/effect-actions 0.11.0 → 0.12.0

package/docs/CONTEXT.md

@@ -1,29 +1,44 @@
 # Context
 
-Vocabulary for `@gjermundgaraba/effect-actions`. The docs, the code, and the tests use these
-words with these meanings. Module names and Effect's own terms (`HttpApi`, `Tool`, `Toolkit`,
-`McpServer`, `Command`) mean what their modules say.
+Vocabulary for `@gjermundgaraba/effect-actions`. The docs, the examples, the code and the tests
+use these words with these meanings. Module names and Effect's own terms (`HttpApi`, `Tool`,
+`Toolkit`, `McpServer`, `Rpc`, `RpcGroup`, `RpcServer`, `Command`) mean what their modules say.
+
+Read this page alone, in one tool call: pages read together are cut. Tasks are routed from
+[README.md](README.md), and each module's failures from its `-failures.md` page.
 
 ## Terms
 
-- **Action**: one contract. A name, a description, an input schema, a success schema, declared error schemas, `readOnly`, `caller`, and its `mcp` options: how its MCP tool presents itself. Holds no behavior. Made by `Action.make`.
-- **Read-only**: `readOnly`, a boolean required on every action and kept as a literal. States whether the action leaves its resource unchanged. Read by an implementation's `authorize`, and the only source of a tool's read-only hint. It enforces nothing itself.
-- **Caller**: who may call an action, `caller`, required on every contract: `Action.Anyone`, the exported value making it a **public action**, which anyone may call, signed in or not, or the identity service a caller must have, such as `caller: CurrentActor`, a **protected action**. Every surface enforces it: a remote one through authentication, a local one by requiring the host to provide that identity on every call.
-- **Identity**: the service a protected action declares, `Context.Service` only, so a contract importing it stays browser-safe. One per action, and one per remote surface; a tenant or other request context is an ordinary request-time requirement. A **trusted identity** is one only a host supplies on a local surface, such as an operator's on an admin CLI, typed apart from what a verifier returns, so no token names it.
-- **Handler**: a function from decoded input to an Effect of decoded success, failing only with the action's declared errors and the built-in ones. The services it yields, and an authorizer's per call, are **request-time requirements**, supplied per call: over HTTP by authentication and router middleware around the surface; on a local surface by the host.
-- **Implementation**: actions bound to their handlers and, where any is protected, their authorizer, one per `Action.implement` call. Nominal. Every surface that runs handlers takes an implementation or a list; its [selection rules](guarantees.md#names) determine which actions are exposed, each keeping its implementation's handlers, builder and authorizer.
-- **Builder**: the Effect passed to `implement` instead of a plain handler or record. It runs once per layer graph, however many surfaces serve its implementation, and once per invocation of a local CLI command: [guarantees.md](guarantees.md#dependency-lifetimes). The services it yields are **build-time requirements**, or startup services, resolved when its layer is built. An authorizer may be built the same way, the Effect returning it instead ([Action.md](Action.md#built-authorization)); so is a verifier, by `Authentication.layer`.
-- **Layer graph**: the layers Effect builds together, sharing one memo map, so each is built once however many layers use it. `HttpRouter.serve` and `Testing.layer` build their routes in a graph of their own, which reuses what the graph around them has already built, and `Layer.fresh` builds its layer in a new one. `HttpRouter.provideRequest` also builds the layer it provides in a graph of its own, which reuses what the routes' graph has already built. Builders and your own services follow it alike: [dependency lifetimes](guarantees.md#dependency-lifetimes).
-- **Host**: the application that serves the surfaces: it builds their layers, provides their services and middleware, and runs the server, subprocess or CLI.
-- **Surface**: where callers reach actions: HTTP routes, an MCP endpoint, a Toolkit, a CLI command, a client in process. Each serves the implementations passed to it and validates only the names it serves. A **remote surface** has callers it authenticates (`ActionHttp.layer`, `ActionMcp.layerHttp`). A **local surface** has none (`ActionToolkit`, a local `ActionCli` command, `ActionMcp.runStdio`, `Action.client`): nothing authenticates, and the host provides the identity.
-- **Binding**: the value `ActionHttp.make` returns, `{ actions, error, prefix, authentication, api }`, typed `ActionHttp.Binding`. Plain data shared by the server and every client. It decides what HTTP serves: `ActionHttp.layer` serves its actions among the implementations given. No other surface has one.
-- **Client**: one method per action, `client.<action>(input)`, taking its input and answering its decoded success, or failing with its declared errors and the built-in ones as decoded values. `ActionHttp.client` calls a binding's routes and `Testing.mcpClient` an endpoint's tools; `Action.client` calls implementations in process, through the dispatch every surface runs, encoding then decoding the input, the success and the failure as a wire carries them: a local surface for code.
-- **Authorizer**: `authorize`, an Effectful function of the selected action, which each implementation of protected actions states, `Action.implement(actions, handlers, { authorize })`, and every surface serving them runs. It runs only for protected actions, after authentication and input decoding, before the handler, and succeeds or fails with a refusal: [guarantees.md](guarantees.md#authorization). `Action.allowAll` lets every authenticated caller call. An implementation of public actions alone states none.
-- **Authentication descriptor**: what `Authentication.make` returns: a named, browser-safe declaration of how a remote caller proves an identity, by one native scheme, Bearer unless it names another, and what its verifier may fail with besides a refusal. A binding and an MCP endpoint serving protected actions name it, `authentication: Login`. Its name identifies the one provider that satisfies it.
-- **Authentication provider**: what `Authentication.layer` returns for a descriptor: the server-only verifier, built once per layer graph, and the discovery of an OAuth protected resource. Every HTTP or MCP layer serving protected actions requires it, and it authenticates their requests before decoding them. Action-level authorization is the authorizer's; record-level checks belong in handler data access ([authorization](guarantees.md#authorization)).
-- **Layer middleware**: native `HttpApiMiddleware` given to `ActionHttp.layer(binding, apps, { middleware })`, run around every route the layer serves, inside authentication and outside decoding. HTTP only.
-- **Mixed endpoint**: an MCP endpoint serving public and protected tools on one URL. Discovery and public tools' calls answer anyone; every other request authenticates before the endpoint decodes it ([ActionMcp.md](ActionMcp.md#rules)).
-- **Declared error**: an error schema listed in an action's `error`. Its handler may fail with it, a limit such as a rate limit included. HTTP sends its JSON encoding with its `httpApiStatus`, 422 without one; MCP returns the same JSON as an `isError` result; the Toolkit returns it as a failure result; a CLI command prints the same JSON on stderr, failing with Effect CLI's `UserError`, whose `cause` it is.
-- **Built-in errors**: `Action.InvalidInput` (400), `Action.Unauthenticated` (401) and `Action.Forbidden` (403), tagged errors with body `{ _tag, message }` and a default `message`; an `InvalidInput` also lists `issues`, empty when it names none, each an `Action.Issue`: a `path` into the input and a `message`, and a `Forbidden` the OAuth `scopes` a call lacks. The library produces them, and every surface declares them: [guarantees.md](guarantees.md#wire-behavior).
-- **Refusal**: `Action.Refusal`, `Unauthenticated | Forbidden`, a schema and a type, as `Action.BuiltIn` is of every built-in error. What authentication or an authorizer refuses a caller with instead of letting a handler run, and all an authorizer may fail with. A **step-up refusal** is one an OAuth client acts on, `Unauthenticated` or a `Forbidden` naming `scopes`. Its HTTP status, challenge, and the exception for an MCP response that has already started follow the [authorization rules](guarantees.md#authorization).
-- **Media field**: a field of an action's success whose schema is a media kind, `Action.Image`, `{ data: Uint8Array, mimeType: string }`: a top-level field of a struct success, optional or an array, or the whole success or an array of it. An MCP tool **lifts** it out of its result into a content block of its own, an image block, beside the rest of the success; every other surface sends it as JSON, the bytes in base64 ([ActionMcp.md](ActionMcp.md#media)).
+### Contracts and calls
+
+- **Action**: one contract: a name, a description, input, success and declared error schemas, `readOnly`, `caller`, and its `mcp` options. Holds no behavior. Made by `Action.make`.
+- **Read-only**: `readOnly`, required on every action: whether it leaves its resource unchanged. It enforces nothing itself.
+- **Caller**: who may call an action, `caller`. `Action.Anyone` makes a **public action**; an identity service, such as `caller: CurrentUser`, makes a **protected action**.
+- **Identity**: the service a protected action names as its caller. A **trusted identity** is one only a host supplies, on a local surface, which no token names.
+- **Handler**: a function from an action's decoded input to an Effect of its decoded success. The services it yields per call, and an authorizer's, are **request-time requirements**.
+- **Implementation**: what `Action.implement` returns: actions bound to their handlers and, where any is protected, their authorizer. Every surface that runs handlers takes one, or a list.
+- **Builder**: an Effect given to `Action.implement` in place of handlers, which returns them, once per layer graph. The services it yields are **build-time requirements**, or **startup services** ([Action.md](Action.md#implement-actions)).
+- **Layer graph**: the layers Effect builds together, each built once ([Action-in-process.md](Action-in-process.md#share-one-build-across-servers)).
+- **Host**: the application that serves the surfaces: it builds their layers, provides their services and runs the server, subprocess or CLI.
+- **Surface**: where callers reach actions. A **remote surface** authenticates its callers (`ActionHttp.layer`, `ActionMcp.layerHttp`, `ActionRpc.layer`). A **local surface** has no one to authenticate (`ActionToolkit`, a local `ActionCli` command, `ActionMcp.runStdio`, `Action.client`): the host provides the identity.
+- **Binding**: what `ActionHttp.make` or `ActionRpc.make` returns: the actions its surface serves, as browser-safe data the server and every client share.
+- **Client**: one method per action, `client.<action>(input)`: `ActionHttp.client`, `ActionRpc.client`, `Testing.mcpClient` and, in process, `Action.client`.
+- **Authorizer**: `authorize`, a function of the called action that an implementation of protected actions states. It succeeds or fails with a refusal ([Action.md](Action.md#authorize-calls)).
+- **Authentication descriptor**: what `Authentication.make` returns: a named, browser-safe declaration of how a remote caller proves an identity. A binding or an MCP endpoint serving protected actions names it.
+- **Authentication provider**: what `Authentication.layer` returns for a descriptor, holding its **verifier**: the server-only function from a credential to the identity.
+- **Layer middleware**: native `HttpApiMiddleware` or `RpcMiddleware` given to `ActionHttp.layer` or `ActionRpc.layer` as `middleware`, run around every route or rpc the layer serves.
+- **Mixed endpoint**: an MCP endpoint serving public and protected tools on one URL ([ActionMcp.md](ActionMcp.md#protect-tools)).
+- **Declared error**: an error schema listed in an action's `error`, which its handler may fail with ([guarantees.md](guarantees.md#wire-behavior)).
+- **Built-in errors**: `Action.InvalidInput`, `Action.Unauthenticated` and `Action.Forbidden`, together `Action.BuiltIn`: errors the library produces and every surface declares ([Action.md](Action.md#fail-with-declared-and-built-in-errors)).
+- **Refusal**: `Action.Refusal`, `Unauthenticated | Forbidden`: what authentication or an authorizer refuses a caller with. A **step-up refusal** is one an OAuth client acts on: an `Unauthenticated`, or a `Forbidden` naming `scopes` ([Authentication.md](Authentication.md#publish-oauth-discovery)).
+- **Media field**: a field of an action's success whose schema is a media kind, `Action.Image`, which an MCP tool **lifts** into a content block of its own ([ActionMcp.md](ActionMcp.md#return-images-and-other-media)).
+
+### Layout of an application
+
+The parts of the layout every example uses: [examples/README.md](../examples/README.md#how-they-are-laid-out).
+
+- **Domain**: one subject of the application, such as notes or identity, and the folder holding everything about it. A folder is never a mechanism, such as `contracts/` or `handlers/`.
+- **Contract file**: the PascalCase file of a domain, such as `notes/Notes.ts`: its schemas, errors and actions, and the identity and descriptor it declares. It imports no server code.
+- **Routes**: `routes.ts`, the host's surfaces as one Layer. A route, singular, is one HTTP route.
+- **Entrypoint**: a file that runs the application one way, such as `server.ts`, `stdio.ts` or `cli.ts`: the **composition root**, the one place that chooses the services, the platform and, on a local surface, the caller.
+- **Demo shortcut**: what an example does in place of what a deployment needs, marked `DEMO ONLY` in a comment.

package/docs/README.md

@@ -1,47 +1,83 @@
-# effect-actions reference
+# effect-actions
 
-Reference for `@gjermundgaraba/effect-actions`, written for coding agents. Each public-module
-card has the same sections: **API** (inventory and options), **Canonical** (the one right way to write
-it), **Rules** (must and never), **Failure modes** (what you see when it is wrong, and the fix).
-Routing, setup, vocabulary, and shared guarantees use the structure their role needs.
-Read the card for a module before writing code that uses it. Exported TypeScript declarations are the exact signature reference. Vocabulary is defined in
-[CONTEXT.md](CONTEXT.md); the pages use those terms exactly.
+`@gjermundgaraba/effect-actions` defines an Effect action once, as a contract with one
+implementation, and serves it over HTTP, MCP and Effect RPC, gives it to a model as a native
+Toolkit, and runs it from a CLI. Every surface is Effect's own server or client, running the
+same schemas, handler and authorization.
 
-Package facts that apply everywhere:
+## How to read these pages
 
-- Every module is a subpath import: `import * as Action from "@gjermundgaraba/effect-actions/Action"`. There is no package root.
-- The `effect` peer admits the patches of the Effect release the package is tested against, and no later minor until a release is tested against it ([setup.md](setup.md#install)).
-- Action contracts are pure values. Defining contracts and implementations runs neither handlers nor builder Effects. Builder services are acquired when a layer is built, an `Action.client` is acquired, or a local CLI command runs; see [dependency lifetimes](guarantees.md#dependency-lifetimes).
+**Arriving with an error?** Search the `*-failures.md` pages for a fragment of its message
+first (step 5), before the examples and the pages.
+
+1. **Open one page per tool call, with your file-reading tool.** A page fits one read. Several
+   in one call, however many commands it runs, are cut by its output limit, and what is cut goes
+   unnoticed.
+2. **Start from the example closest to what you are building** ([Examples](#examples)). Its
+   README has a layout tree and a "Where to look" table naming the file for each thing. Copy its
+   layout and idioms: the examples are the reference for how code is written.
+3. **Read [Action.md](Action.md) completely.** Every surface builds on it.
+4. **Read the page of each surface you serve** ([Pages](#pages)), and the example files its task
+   sections link.
+5. **When something fails, search the `*-failures.md` pages** for a fragment of the message. Each
+   module page has one beside it, such as [Action-failures.md](Action-failures.md).
+
+A service others call is [notes-service](../examples/notes-service/) plus
+[Action.md](Action.md), [ActionHttp.md](ActionHttp.md), [ActionMcp.md](ActionMcp.md),
+[Authentication.md](Authentication.md) and [Testing.md](Testing.md).
+
+Where things are, in a project that installs the package: these pages in
+`node_modules/@gjermundgaraba/effect-actions/docs/`, the examples in `examples/` beside them, and
+the declarations with their JSDoc, the reference for signatures, in `dist/<Module>.d.mts`, all at
+the installed version. Install first ([setup.md](setup.md#install)): it needs TypeScript 7 and
+one Effect release. Every module is a subpath import, `@gjermundgaraba/effect-actions/Action`;
+there is no package root.
 
 ## Pages
 
-| Read                                   | When you need to                                                                                                                                          |
-| -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| [setup.md](setup.md)                   | install, run the minimal program, pick entry points, bundle a browser client, check package boundaries                                                    |
-| [Action.md](Action.md)                 | define a contract and who may call it, bind its handler and authorization, use built-in errors, call or test implementations in process (`Action.client`) |
-| [ActionHttp.md](ActionHttp.md)         | serve JSON POST routes, answer bad input, publish OpenAPI, call the API with one Effect method per action                                                 |
-| [ActionMcp.md](ActionMcp.md)           | serve MCP tools over Streamable HTTP or stdio                                                                                                             |
-| [ActionToolkit.md](ActionToolkit.md)   | use actions as a native Effect AI `Toolkit` without a server                                                                                              |
-| [ActionCli.md](ActionCli.md)           | run handlers in-process, or call the HTTP API, from a command with derived flags                                                                          |
-| [Authentication.md](Authentication.md) | declare how a remote caller proves its identity, verify it on HTTP and MCP surfaces, refuse with 401/403, publish RFC 9728 discovery                      |
-| [Testing.md](Testing.md)               | call routes and tools in memory through `HttpClient`, or test an implementation in process                                                                |
-| [guarantees.md](guarantees.md)         | rules every surface shares: builder lifetimes, authorization, wire formats, names, spans, the package's scope                                             |
-| [CONTEXT.md](CONTEXT.md)               | look up a term the pages use                                                                                                                              |
+| Read                                                     | When you need to                                                                                                                            |
+| -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| [setup.md](setup.md)                                     | install, import the modules, write the minimal program, lay out an application, bundle a browser client                                     |
+| [Action.md](Action.md)                                   | define a contract and who may call it, implement it, authorize calls, fail with declared and built-in errors                                |
+| [Action-in-process.md](Action-in-process.md)             | call actions from your own code, such as a job; share one build of the implementations across servers and jobs                              |
+| [ActionHttp.md](ActionHttp.md)                           | bind actions to JSON routes, serve them, limit request bodies, publish OpenAPI, call them from Effect or a browser                          |
+| [ActionMcp.md](ActionMcp.md)                             | serve MCP tools over HTTP or stdio, describe them to a model, return images, protect them, allow browser clients, add prompts and resources |
+| [ActionRpc.md](ActionRpc.md)                             | bind actions to Effect rpcs, serve them on a protocol, call them, send request context with a call                                          |
+| [ActionToolkit.md](ActionToolkit.md)                     | give a model actions as a native Effect AI `Toolkit`, name the caller, ask for approval                                                     |
+| [ActionCli.md](ActionCli.md)                             | run actions as local commands, or call a server from commands; shape flags, input and output; add a command of your own                     |
+| [Authentication.md](Authentication.md)                   | declare how callers sign in, verify credentials, publish OAuth discovery, step up for a scope                                               |
+| [Authentication-advanced.md](Authentication-advanced.md) | use an API key or a cookie, read the request in a verifier, protect a route of your own, run a request policy before authentication         |
+| [Testing.md](Testing.md)                                 | test an implementation in process, and routes, tools and rpcs in memory, as a signed-in caller; assert on errors                            |
+| [guarantees.md](guarantees.md)                           | see the status and body of one case, such as bad input, a declared error or a refusal, on each surface; what the library leaves to you      |
+| [CONTEXT.md](CONTEXT.md)                                 | look up a term the pages use                                                                                                                |
 
-## Choose a surface
+## Examples
 
-- Callers speak JSON over HTTP: `ActionHttp`. Clients use `ActionHttp.client(Http)`.
-- Callers are MCP clients: `ActionMcp.layerHttp` for a hosted endpoint, `ActionMcp.runStdio` for a subprocess.
-- Callers are an Effect AI program in the same process: `ActionToolkit`.
-- Callers are humans or scripts in a terminal: `ActionCli`, `make` and `command` from implementations to run handlers locally, or `remote` and `remoteCommand` from the HTTP binding to call a server.
-- Callers are your own code in the same process, such as a test, a job or a command of your own: `Action.client`, with the methods of `ActionHttp.client`.
+| Example                                     | What it is                                                                                                       | Start from it when                                                      |
+| ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
+| [quickstart](../examples/quickstart/)       | One action, served as a JSON route and an MCP tool, called with its typed client.                                | You want the smallest thing that runs.                                  |
+| [notes-service](../examples/notes-service/) | A service with bearer authentication: a JSON API and MCP tools from one implementation, a CLI, a browser client. | You are building a service others call. Most applications are this.     |
+| [mcp-tools](../examples/mcp-tools/)         | An MCP server whose tools wrap an upstream HTTP API, over stdio and over HTTP, with an image result.             | You are putting an existing API in front of a model.                    |
+| [assistant](../examples/assistant/)         | No server: the same implementations as a model's tools, with approval of writes, and as local commands.          | A model calls your code in process, or you are building a local CLI.    |
+| [live-rpc](../examples/live-rpc/)           | Effect RPC over a WebSocket with a browser-shaped client, each message carrying its own token.                   | A client keeps a connection open, or the application speaks Effect RPC. |
+| [kitchen-sink](../examples/kitchen-sink/)   | The reference: a multi-tenant issue tracker using every module and nearly every option, with an index.           | You need a working use of one specific feature.                         |
 
-Every surface that runs handlers takes the same implementations (`Action.implement(...)`), one or a list, with options last. A contract states who may call it, `caller`, and an implementation of protected actions carries its own `authorize`, which every surface runs; surfaces take only their transport's options. A remote surface serving protected actions names their authentication descriptor and requires its verifier, `Authentication.layer`; on a local surface the host provides the identity.
+Each example's README says where to look for what. The index in
+[kitchen-sink](../examples/kitchen-sink/README.md#index) maps every export and option it uses to
+a file. Every token, user and store in the examples is a demo, marked `DEMO ONLY` where it must
+change before a deployment.
 
-For first-time setup, follow the [minimal program](setup.md#minimal-program).
+## Choose a surface
 
-## Runnable examples
+| Callers                                                        | Use                                                                                                                |
+| -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| Speak JSON over HTTP                                           | `ActionHttp`; clients use `ActionHttp.client`, or `ActionHttp.fetchClient` outside an Effect                       |
+| Are Effect programs, such as a page over one WebSocket         | `ActionRpc`; clients use `ActionRpc.client`                                                                        |
+| Are MCP clients                                                | `ActionMcp.layerHttp` for a hosted endpoint, `ActionMcp.runStdio` for a subprocess, which runs the handlers itself |
+| Are a model in the same process                                | `ActionToolkit`                                                                                                    |
+| Are people or scripts in a terminal                            | `ActionCli`: `make` runs handlers locally, `remote` calls a server through its HTTP binding                        |
+| Are your own code in the same process, such as a job or a test | `Action.client`                                                                                                    |
 
-Repository directory `examples/`: the minimal program, an authenticated application served on
-every surface, and one file per other surface, each listed in its
-[README](https://github.com/gjermundgaraba/effect-actions/tree/main/examples#readme).
+Surfaces combine: every one that runs handlers takes the same implementations, one or a list,
+and enforces each contract's `caller` and its implementation's `authorize`
+([Action.md](Action.md#authorize-calls)).

package/docs/Testing-failures.md

@@ -0,0 +1,20 @@
+# Testing failure modes
+
+What you see when something is wrong, and the fix. Search for a fragment of the message.
+The tasks are in [Testing.md](Testing.md).
+
+- A route answers an empty 500: a defect, or a result that does not encode. `Testing.layer` logs the cause as an error, and nothing for a request that succeeds or is refused: read the test's output, or collect it with a `Logger` or an `ErrorReporter` provided around the layer.
+- A client method fails with `Action.Unauthenticated`: routes under `Testing.layer` keep their real authentication. Give the client a credential in `transformClient` ([Test as a signed-in caller](Testing.md#test-as-a-signed-in-caller)).
+- A protected route answers 401 where the test expects 415 or 400: authentication runs before the body is read. Send a valid credential.
+- `Type 'Provider<CurrentUser, "notes-service.Login">' is missing the following properties from type 'Scope'` at `it.effect`, or `… is not assignable to type 'never'` at `Effect.runPromise`: the routes serve a protected action without a provider of its descriptor. Provide the real one or a test verifier to the routes; a caller provided around `Testing.layer` does not satisfy them.
+- `Type 'CurrentUser' is missing the following properties from type 'Scope'` at `it.effect`, or `… is not assignable to type 'never'` at `Effect.runPromise`: the test still owes the identity. An `Action.client` call of a protected action takes its caller per call: provide it around the call. Or a public action's handler reads the identity, which no route provides to it: make the action protected. Or, where the caller is provided already, a builder yields it: move that `yield*` into the handler ([Action-failures.md](Action-failures.md#where-an-implementation-is-served)).
+- `Type '<Service>' is missing the following properties from type 'Scope'` at every `it.effect`, for a service that is no identity, such as a store, a limiter or a `LanguageModel`: a builder now yields it, and the routes require it. Provide its layer to `Testing.layer(routes)`, as the entrypoint provides it to the server.
+- `Type 'unknown' is not assignable to type 'Scope'` at `it.effect`, or `Argument of type 'Effect<…>' is not assignable` at an `Effect.flip` or `Effect.exit`, around a loop over an array of calls to different actions: their successes and errors differ, so the array has no one element type. Annotate it, `ReadonlyArray<Effect.Effect<unknown, unknown>>`, with the caller as a third parameter for `Action.client` calls of protected actions, or assert each call on its own.
+- An rpc call never answers under `Testing.layer`, and nothing is logged: the layer holds the rpc layer twice, under two protocols, and built it for the other one, a WebSocket. Give the rpc layer its WebSocket in the entrypoint, so the routes a test serves hold it once, under the test's protocol ([Serve the rpcs](ActionRpc.md#serve-the-rpcs)).
+- A test passes whatever message an error carries: `toEqual` never compares a tagged error's `message`. Assert it separately ([Assert on errors](Testing.md#assert-on-errors)).
+- The test reads a service the handlers never changed: it was provided inside the routes and again to the test, two instances. Provide it once, around `Testing.layer`, with `Layer.provideMerge`.
+- `MCP tools/call "<name>" answered 404`: the endpoint is not at `/mcp`, the default. Pass `mcpClient` its `url`.
+- `MCP tools/call "<name>" returned an error: Invalid parameters for tool ...`: the endpoint serves another contract under that name. Pass `mcpClient` the served contract value.
+- A builder or handler fails with `NotFound: FileSystem.<method> (<path>)` for a file that exists, or a file route answers 500: with no `FileSystem` provided around `Testing.layer`, the routes read a no-op one. Provide `NodeFileSystem.layer` or `NodeServices.layer`. In a command test, the nearer of two provided is read: provide a fake `FileSystem` on the command, inside `NodeServices.layer`.
+- `Argument of type 'Layer<…, FileSystem | Generator | HttpPlatform | HttpRouter | Path>' is not assignable` at `HttpRouter.toWebHandler(routes)`: a web handler's routes need the platform services `Testing.layer(routes)` supplies itself. Provide `HttpServer.layerServices` to them.
+- `UrlError` from `HttpClientRequest.toWebResult` or `toWeb` of an `mcpRequest`, or an `HttpClientError` whose reason is `InvalidUrlError` from a client method or a sent `mcpRequest`: the `url` is relative, such as the default `/mcp`, which only the `HttpClient` of `Testing.layer` resolves. Pass an absolute one.