@gjermundgaraba/effect-actions 0.9.0 → 0.11.0

package/docs/CONTEXT.md

@@ -1,41 +1,29 @@
 # Context
 
-Vocabulary and seams for `@gjermundgaraba/effect-actions`. The docs, the code, and the tests
-use these words with these meanings.
+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.
 
 ## Terms
 
-- **Action**: one contract. A name, a description, an input schema, a success schema, declared error schemas, authorization metadata (`access`), and MCP metadata (`mcp`). Holds no behavior. Made by `Action.make`.
-- **Access**: `"read"` or `"write"`, required on every action and kept as a literal. States what the action does to its resource. Authorization metadata read by a pre-handler hook, independent of the MCP `readOnly` hint, which defaults from it.
-- **Group**: a named, ordered set of actions plus group-level errors and an optional schema-error policy. Adapters serve groups, clients are organized by group, and the group name is the OpenAPI tag. Made by `ActionGroup.make`.
-- **Contract**: an action or a group. Pure data; safe to import anywhere, including browsers.
-- **Handler**: a function from decoded input to an Effect of decoded success, failing only with the action's declared errors, possibly requiring services.
-- **Implementation**: a nominal binding of a complete handler record to a group, made by `group.implement`. Carries build-time error and requirement channels. Adapters accept implementations; `ActionCatalog` accepts contracts.
-- **Builder**: the record or Effect passed to `implement`. Runs once per adapter layer that serves the implementation.
-- **Pre-handler hook**: the `before` function an adapter binds. Runs once after successful input decoding, with the selected action contract, before its handler. Invalid input skips the hook. Fails with the surface's own errors. Its services are request-time requirements.
-- **Build-time requirement**: a service yielded in the builder. Resolved when an adapter layer is built.
-- **Request-time requirement**: a service yielded inside a handler. Supplied per invocation: by router middleware for HTTP-hosted adapters, by the host for Toolkit, CLI, and stdio.
-- **Adapter** (also **projection**): a module that maps implementations or contracts onto one surface: `ActionHttp`, `ActionMcp`, `ActionToolkit`, `ActionCli`, `ActionCliClient`, `ActionCatalog`. Each adapter reads only what it serves and validates only its own namespace.
-- **Binding**: the value an adapter returns before anything runs. `ActionHttp.make` returns the HTTP binding (`groups`, `api`, `layer`, `openApi`); `ActionToolkit.make` returns the Toolkit binding (`toolkit`, `layer`).
-- **Contract map**: the record `ActionGroup.contracts` returns, keyed `<group>.<action>`, with each action's exact type. The shared identity of an action across routes, tools and commands.
-- **Declared error**: an error schema listed on an action or inherited from its group. Handlers may fail with it. HTTP encodes it with its `httpApiStatus`; MCP returns encoded error text in an `isError` result. Toolkit returns a native failure result, and CLI fails its command Effect without serializing the error.
-- **Schema-error policy**: a group option answering Effect's `HttpApiSchemaError` with a declared policy error and its status: `invalid` when the request did not decode, `internal` when the handler's result did not encode. The library decides which applies. HTTP only.
-- **Policy error**: an error a schema-error policy may answer with. Part of the transport contract, never returnable by a handler.
-- **Surface error**: an error declared on an adapter binding rather than on an action. Produced by middleware around the surface or by its pre-handler hook, never by a handler; declared so typed callers decode it.
-- **Tool**: the MCP or Toolkit projection of an MCP-enabled action, named by `mcp.name` and carrying its hints.
-- **Text field**: the string field of an action's encoded success that `mcp.text` names. When a success has it, MCP sends it once, raw, as a text block, and leaves it out of the structured content. Every other surface serves the whole success.
-- **Endpoint**: one `ActionMcp.layerHttp` mount. One route, one middleware set, one tool registry.
-- **Document**: the OpenAPI output of `Http.api`, produced by Effect (`OpenApi.fromApi`) and served by `Http.openApi`.
-- **Promise client**: `ActionHttpClient.promise(Http)`, the native `HttpApiClient` as one Promise method per action of the binding, for code that does not run Effects. It rejects with what the native client fails with.
-- **Catalog**: the offline JSON description of groups produced by `ActionCatalog.make`, with standalone JSON Schemas for encoded values. Descriptive only.
-- **Identity**: the per-request principal, provided by `Authentication.middleware` under an application-owned tag. Never provided at startup.
-
-## Seams
-
-- `src/Action.ts` and `src/ActionGroup.ts` are contracts. They import no transport runtime. They carry only transport metadata (`mcp`, `httpApiStatus`, the HTTP schema-error policy).
-- `src/internal/actions.ts` and `src/internal/implementation.ts` hold the shared shapes adapters consume: the contract half of a group, the schema-error policy, and the nominal `Implementation` class. Everything under `src/internal` is not public API; the public modules re-export the types consumers need.
-- Each adapter owns its own mapping from contracts to its surface and never reaches into another adapter. HTTP does not know about tool names; MCP does not know about routes.
-- Adapters build on Effect's own servers and clients: `HttpApi` for HTTP, `McpServer` for MCP, `Toolkit` for the AI toolkit, `Command` for the CLI. The library adds no protocol runtime.
-- Authentication is router middleware plus discovery metadata. Verification, login, and consent stay in the application. Authorization is the application's pre-handler hook, bound to each surface, which the library runs but never writes.
-- `Testing` depends only on `effect`. `TestingClient` is the single module that loads the optional MCP client peer.
-- Docs: `README.md` is the pitch for humans. `docs/` is the reference for agents, one card per module. `skills/effect-actions` is a copy of `docs/`, with this vocabulary included. `CONTRIBUTING.md` and `AGENTS.md` are for maintainers.
+- **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)).

package/docs/README.md

@@ -1,91 +1,47 @@
 # effect-actions reference
 
-Reference for `@gjermundgaraba/effect-actions`, written for coding agents. Every module page is a
-card with the same sections: **API** (inventory and options), **Canonical** (the one right way to write
+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).
-[setup.md](setup.md), [guarantees.md](guarantees.md), and [CONTEXT.md](CONTEXT.md) are cross-cutting pages with their own structure.
+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.
 
 Package facts that apply everywhere:
 
 - Every module is a subpath import: `import * as Action from "@gjermundgaraba/effect-actions/Action"`. There is no package root.
-- The `effect` peer is `^4.0.0`. The package is built and tested against `4.0.0`.
-- Contracts are pure values. Nothing runs, binds, or acquires services until an adapter layer is built.
+- 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).
 
 ## Pages
 
-| Read                                       | When you need to                                                                       |
-| ------------------------------------------ | -------------------------------------------------------------------------------------- |
-| [setup.md](setup.md)                       | install, pin versions, pick entry points, know what the package does not do            |
-| [Action.md](Action.md)                     | define one contract: input, success, errors, read/write access, HTTP and MCP flags     |
-| [ActionGroup.md](ActionGroup.md)           | group contracts, declare shared errors, bind handlers, map every contract by name      |
-| [ActionHttp.md](ActionHttp.md)             | serve JSON POST routes, declare surface errors and one hook, publish OpenAPI, call it  |
-| [ActionHttpClient.md](ActionHttpClient.md) | call the HTTP API with Promises, from code that does not run Effects                   |
-| [ActionMcp.md](ActionMcp.md)               | serve MCP 2026-07-28 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 from a terminal command                                        |
-| [ActionCliClient.md](ActionCliClient.md)   | call the HTTP API from a terminal command                                              |
-| [ActionCatalog.md](ActionCatalog.md)       | export contracts as an offline JSON document                                           |
-| [Authentication.md](Authentication.md)     | provide a per-request identity, publish RFC 9728 discovery, build bearer challenges    |
-| [Testing.md](Testing.md)                   | call routes and tools in memory, build MCP requests, drive the official MCP client     |
-| [guarantees.md](guarantees.md)             | cross-cutting rules: dependency lifetimes, wire formats, spans, request context, scope |
-
-## Choose an adapter
-
-- Callers speak JSON over HTTP: `ActionHttp`. Clients use Effect's `HttpApiClient` on `Http.api`, or `ActionHttpClient.promise(Http)` where nothing runs Effects.
-- Callers are MCP clients: `ActionMcp.layerHttp` for a hosted endpoint, `ActionMcp.layerStdio` for a subprocess.
+| 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                                                                                                                              |
+
+## Choose a surface
+
+- 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, handlers run locally: `ActionCli`.
-- Callers are humans or scripts in a terminal, handlers run on a server: `ActionCliClient`.
-- Nothing runs, only the contract is published: `ActionCatalog`.
-
-One implementation (`group.implement(...)`) feeds every adapter.
-
-## Minimal program
-
-```ts
-import { Effect, Layer, Schema } from "effect";
-import * as Action from "@gjermundgaraba/effect-actions/Action";
-import * as ActionGroup from "@gjermundgaraba/effect-actions/ActionGroup";
-import * as ActionHttp from "@gjermundgaraba/effect-actions/ActionHttp";
-import * as ActionMcp from "@gjermundgaraba/effect-actions/ActionMcp";
+- 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`.
 
-const Greet = Action.make("greet", {
-  description: "Greet someone by name.",
-  input: Schema.Struct({ name: Schema.String }),
-  success: Schema.String,
-  access: "read",
-});
+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.
 
-export const Actions = ActionGroup.make({ name: "greetings" }, Greet);
-
-export const Http = ActionHttp.make({ apiPath: "/api/actions" }, Actions);
-
-const app = Actions.implement({
-  greet: ({ name }) => Effect.succeed(`Hello, ${name}!`),
-});
-
-export const routes = Layer.mergeAll(
-  Http.layer([app]),
-  ActionMcp.layerHttp([app], {
-    name: "greetings",
-    version: "1.0.0",
-    path: "/mcp",
-  }),
-);
-```
-
-Serve `routes` with `HttpRouter.serve` and a platform server layer. Result: `POST /api/actions/greetings/greet` and an MCP tool `greet` at `/mcp`.
+For first-time setup, follow the [minimal program](setup.md#minimal-program).
 
 ## Runnable examples
 
-Repository directory `examples/` ([on GitHub](https://github.com/gjermundgaraba/effect-actions/tree/main/examples)):
-
-- `quickstart.ts`, `quickstart-client.ts`: the minimal program and its typed client.
-- `promise-client.ts`: the Promise client, with a declared error and an unreachable server.
-- `contracts.ts`, `auth.ts`, `users.ts`, `handlers.ts`, `app.ts`, `server.ts`, `client.ts`: an authenticated application with three groups, per-group middleware, two MCP endpoints, OpenAPI and Swagger.
-- `toolkit.ts`, `catalog.ts`, `cli.ts`, `cli-client.ts`, `mcp-stdio.ts`: one file per other projection.
-- `mcp-browser.ts`: a stateless MCP endpoint with a separate browser CORS policy.
-- `toolkit-authorized.ts`: native Toolkit invocation with authorization and correctly scoped identity.
-- `testing.ts`: in-memory HTTP and MCP calls with cleanup.
+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).

package/docs/Testing.md

@@ -1,97 +1,174 @@
 # Testing
 
-In-memory calls against served layers. `Testing` needs no extra dependency. `TestingClient`
-loads the optional `@modelcontextprotocol/client` peer and nothing else does.
+In-memory calls against served layers, through Effect's own `HttpClient`. Needs no extra
+dependency and opens no port. It tests what the wire does: routes and tools, authentication,
+statuses and codecs as sent. What an implementation does, its authorization and its handlers, is tested in process with `Action.client` ([Implementations](#implementations)).
 
 ## API
 
-Import `@gjermundgaraba/effect-actions/Testing`; official-client helpers are in the separate
-`@gjermundgaraba/effect-actions/TestingClient` subpath.
+Import `@gjermundgaraba/effect-actions/Testing`.
+
+| API                                     | Purpose                                                                             |
+| --------------------------------------- | ----------------------------------------------------------------------------------- |
+| `layer(routes)`                         | A `Layer<HttpClient>` answering requests with `routes` in memory.                   |
+| `layer(handler)`                        | A `Layer<HttpClient>` answering requests with a web handler the test serves.        |
+| `mcpClient(actions, options?)`          | An Effect of a client calling each action's tool, like `ActionHttp.client`.         |
+| `mcpRequest(method, params?, options?)` | One request an `ActionMcp` endpoint serves, as the native request the test sends.   |
+| `McpCallError`                          | What a client method fails with for an answer it cannot decode; `message` holds it. |
+
+| Option                         | Meaning                                                                                                                                               |
+| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `url`                          | The endpoint, resolved by the `HttpClient` (relative under `layer`, or one prepending a base URL); default `/mcp`, the `ActionMcp.layerHttp` default. |
+| `mcpClient`: `transformClient` | Wraps the native `HttpClient`, as `ActionHttp.client` takes it: `HttpClient.mapRequest(HttpClientRequest.bearerToken(token))`.                        |
+| `mcpRequest`: `headers`        | Request headers.                                                                                                                                      |
+
+Exported types: `McpClient<Actions>`, a client's type; `McpClientOptions` of `mcpClient`; `McpRequestOptions` of `mcpRequest`, and `McpParams`, its `params`.
+
+`mcpClient(actions, options)` builds a client on the `HttpClient` in context, one method per
+action, called as a client method is: `mcp.getUser({ id })`. For every tool one implementation
+serves, pass its actions: `Testing.mcpClient(userActions.actions)`. A method succeeds with the
+action's decoded success. It fails with the action's declared errors and the built-in ones as
+decoded values, `SchemaError`, `HttpClientError`, or `McpCallError` for any other answer.
+Only a tool result carries the action's own errors; any other response decodes only as a
+refusal, as authentication and an authorizer send. The input may be left out when `{}` is a valid
+input, sending the input `{}` decodes to, and a given input is sent as given, as for a client's
+method.
 
-| API                                          | Purpose                                                                                               |
-| -------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
-| `Testing.httpClient(api, handler, options?)` | Native grouped `HttpApiClient` over an in-memory web handler; retains client middleware requirements. |
-| `Testing.mcpRequest(options)`                | Build a stateless MCP JSON-RPC `Request`.                                                             |
-| `Testing.mcpCall(handler, options)`          | Call one tool in memory and return its outcome without the wire envelope.                             |
-| `TestingClient.withMcpClient(options, run)`  | Connect the official client, run an asynchronous callback, then close it.                             |
+## Canonical
 
-`httpClient` takes native client options; `baseUrl` defaults to `http://localhost`.
-Its exported `Handler` type is a web request to response Promise, not an action handler.
+```ts example=testing.ts
+import { Effect } from "effect";
+import * as ActionHttp from "@gjermundgaraba/effect-actions/ActionHttp";
+import * as Testing from "@gjermundgaraba/effect-actions/Testing";
+import { Greet, Http } from "./quickstart.js";
+import { routes } from "./quickstart-server.js";
 
-| MCP option                            | Meaning                                                     |
-| ------------------------------------- | ----------------------------------------------------------- |
-| `mcpRequest`: `url`, `method`         | Required destination and JSON-RPC method.                   |
-| `mcpRequest`: `params`, `headers`     | Optional parameters and request headers.                    |
-| `mcpCall`: `url`, `name`              | Required endpoint URL and tool name (`mcp.name`).           |
-| `mcpCall`: `arguments`, `headers`     | Optional tool arguments (default `{}`) and request headers. |
-| `withMcpClient`: `fetch`, `path`      | Required in-memory request handler and endpoint path.       |
-| `withMcpClient`: `baseUrl`, `headers` | Optional base URL (default `http://localhost`) and headers. |
+const program = Effect.gen(function* () {
+  const client = yield* ActionHttp.client(Http);
+  const greeting = yield* client.greet({ name: "Ada" });
 
-Exported option/value types: `McpRequestOptions`, `McpRequestParams`, `McpRequestValue`,
-`McpCallOptions`, `McpCallResult` from `Testing`, and `McpClientOptions` from `TestingClient`.
+  // The same action as a tool of `/mcp`, called like the client's method.
+  const mcp = yield* Testing.mcpClient([Greet]);
+  const called = yield* mcp.greet({ name: "Ada" });
 
-## Canonical
+  return { greeting, called };
+});
+
+// The routes answer in memory for the program's scope, and are released after it.
+console.log(await Effect.runPromise(program.pipe(Effect.provide(Testing.layer(routes)))));
+```
+
+### Implementations
+
+What an implementation does, with no transport between: `Action.client` gives the methods
+`ActionHttp.client` gives, and each call runs the authorizer and the handler, with every
+check a surface makes on its input, its success and its failure ([Action.md](Action.md#clients)). Each
+call takes its caller, so one test has several, and an action no binding holds, such as a
+tool, has a method like any other.
+
+```ts example=in-process.ts
+import { Effect } from "effect";
+import * as Action from "@gjermundgaraba/effect-actions/Action";
+import { actors, CurrentActor } from "./authorization.js";
+import { userActions } from "./handlers.js";
+import { Users } from "./users.js";
+
+// Each call names its caller, as authentication names one per request.
+const asAlice = Effect.provideService(CurrentActor, actors.alice);
+
+const asReader = Effect.provideService(CurrentActor, actors.reader);
+
+const program = Effect.gen(function* () {
+  // Acquired once, as a layer is built: the builders run here, not per call.
+  const users = yield* Action.client(userActions);
+
+  // The methods of `ActionHttp.client(Http)`, with no transport between: each call decodes
+  // its input, runs `authorize`, then the handler, and checks the success or the failure.
+  const renamed = yield* users.renameUser({ id: "1", name: "Bea" }).pipe(asAlice);
+  const refused = yield* Effect.flip(users.renameUser({ id: "1", name: "Cy" }).pipe(asReader));
+  const { changes } = yield* users.listChanges().pipe(asReader); // not an HTTP route
 
-```ts
+  return { renamed, refused, changes };
+});
+
+// The builders are released with the program's scope, before the services they captured.
+console.log(
+  await Effect.runPromise(program.pipe(Effect.scoped, Effect.provide(Users.layerMemory))),
+);
+```
+
+### Signed-in callers
+
+Protected routes on the wire: serve them behind their authentication, the real provider or a
+test verifier of the same descriptor, and give each client its caller's credential. One `layer`
+serves every caller; the test program shares what the routes read, such as `Users`.
+
+```ts example=testing-caller.ts
 import { Effect, Layer } from "effect";
-import { HttpRouter, HttpServer } from "effect/http";
+import { HttpClient, HttpClientRequest } from "effect/http";
+import * as ActionHttp from "@gjermundgaraba/effect-actions/ActionHttp";
 import * as Testing from "@gjermundgaraba/effect-actions/Testing";
-import * as TestingClient from "@gjermundgaraba/effect-actions/TestingClient";
-import { Http, routes } from "./quickstart.js";
-
-const web = HttpRouter.toWebHandler(routes.pipe(Layer.provide(HttpServer.layerServices)));
-
-try {
-  const greeting = await Effect.runPromise(
-    Effect.gen(function* () {
-      const client = yield* Testing.httpClient(Http.api, web.handler);
-
-      return yield* client.greetings.greet({ payload: { name: "Ada" } });
-    }),
-  );
-
-  // Raw MCP request; this stateless revision needs no initialize handshake.
-  const listed = await web.handler(
-    Testing.mcpRequest({ url: "http://localhost/mcp", method: "tools/list" }),
-  );
-
-  // One tool call, answered as `{ isError: false, value: "Hello, Ada!" }`.
-  const called = await Testing.mcpCall(web.handler, {
-    url: "http://localhost/mcp",
-    name: "greet",
-    arguments: { name: "Ada" },
-  });
-
-  // The official client uses the same in-memory handler.
-  const result = await TestingClient.withMcpClient({ fetch: web.handler, path: "/mcp" }, (client) =>
-    client.callTool({ name: "greet", arguments: { name: "Ada" } }),
-  );
-
-  console.log({ greeting, listStatus: listed.status, called, result });
-} finally {
-  await web.dispose();
-}
+import { authenticate } from "./authentication.js";
+import { Http } from "./binding.js";
+import { userActions } from "./handlers.js";
+import { Users } from "./users.js";
+
+// The routes behind their real authentication; the caller is the token each client sends.
+const routes = Testing.layer(
+  ActionHttp.layer(Http, userActions).pipe(Layer.provide(authenticate)),
+).pipe(Layer.provideMerge(Users.layerMemory));
+
+const as = (token: string) => ({
+  transformClient: HttpClient.mapRequest(HttpClientRequest.bearerToken(token)),
+});
+
+const program = Effect.gen(function* () {
+  const reader = yield* ActionHttp.client(Http, as("reader"));
+  const refused = yield* Effect.flip(reader.renameUser({ id: "1", name: "Bea" })); // Forbidden
+  const users = yield* Users;
+
+  return { refused, unchanged: yield* users.get("acme", "1") };
+});
+
+console.log(await Effect.runPromise(program.pipe(Effect.provide(routes))));
 ```
 
+A verifier needing infrastructure in production is replaced, for a test, by another `layer` of the
+same descriptor: `Authentication.layer(Login, (token) => ...)`.
+Any provider of that descriptor satisfies the routes; nothing else does.
+
 ## Rules
 
-- `httpClient` is the same `HttpApiClient` consumers use, with its transport replaced by `handler`. Same `{ payload }` calls, same error channel.
-- `mcpRequest` pins protocol version 2026-07-28 in both the header and `_meta`. Caller `params._meta` fields override the defaulted client capabilities and info; the merge is shallow. Application metadata is preserved.
-- `params` accepts what `JSON.stringify` accepts, so tests can send malformed arguments on purpose. `undefined` fields are dropped.
-- `mcpCall` sends one `tools/call` through `mcpRequest` and resolves with `{ isError: false, value }`, the success taken from `structuredContent`, with `text` holding the text field when a success with `mcp.text` sent one, or `{ isError: true, error }`, the result's error text parsed as JSON. A declared error or a hook refusal is its JSON encoding, the same body HTTP sends; the native server's own messages (invalid arguments, defects) are not JSON and stay text. It reads a JSON or an event-stream response.
-- To assert on a result's exact bytes, such as a size bound, send `mcpRequest` through the handler and parse the reply: `JSON.stringify` of the parsed message reproduces the message the server wrote, so `JSON.stringify(message.result)` is the result as encoded.
-- `mcpCall` throws when the answer is not a tool result: a status other than 200 (an authentication refusal), or a JSON-RPC error (an unknown tool). Use `mcpRequest` to assert on those responses.
-- `withMcpClient` pins the official client to MCP 2026-07-28, the only revision `ActionMcp` serves, and closes the transport in a `finally` block.
-- Add `Authorization` through `headers` in the MCP helpers, or through `transformClient` in `httpClient` options.
-- Direct handler tests can use `app.build` under `Effect.scoped`, but they bypass decoding, encoding, middleware, and the `before` hook. Keep at least one adapter-level test per transport.
+- `layer(routes)` builds the routes with request logging off, and releases them with the layer's scope. What the routes still require is the layer's, as under `HttpRouter.serve`: their builders' services, and any per-request service no middleware of theirs provides, including one a global middleware reads. Provide them around it, with `Layer.provideMerge` where the program reads them too, so the handlers and the program share one instance. A per-request service provided there, such as a tenant, reaches every request. A protected action's identity is not such a service: its routes require their authentication provider, which nothing provided around `layer` replaces ([Signed-in callers](#signed-in-callers)). Each `layer` builds the routes anew, builders included, unless `Action.layer` built them above it. Requests run in the context the layer is built in, as under `HttpRouter.serve`: a `TestClock` or a reference provided around the program reaches middleware and handlers.
+- `layer` never requires the platform services `FileSystem`, `Path`, `HttpPlatform` and `Etag.Generator`, but they follow the same rule: at build and per request, the routes get the ones provided around `layer`, and `HttpServer.layerServices`' defaults for the rest, whose `FileSystem` is a no-op. The default `HttpPlatform` reads files through the `FileSystem` provided around `layer`.
+- A relative URL resolves against `http://localhost`, once any `baseUrl` a client adds is applied, so `ActionHttp.client(Http)` needs no `baseUrl` under `layer`, and one given is kept. Every request on this client is answered by the routes, whatever its host, so the native `HttpApiClient` and a remote `ActionCli` command work in memory too.
+- The client is `layer`'s own: the program's other HTTP clients get none of its requests, and it none of theirs, whether a `FetchHttpClient` is built before or after it or a `FetchHttpClient.Fetch` is provided around the program.
+- `layer(handler)` gives the same client, answered by a web handler the test serves, such as `HttpRouter.toWebHandler(routes.pipe(Layer.provide(HttpServer.layerServices))).handler` shared with tests that send it `Request`s: the routes are built once, by the handler, for every `layer` given it. The web handler needs the routes' platform services, which `HttpServer.layerServices` provides and `layer(routes)` supplies itself. The test owns the handler: `layer` neither builds nor disposes it, so the test calls `dispose` when it is done.
+- A client method sends one stateless `tools/call` for the action's tool, at the protocol version `ActionMcp.layerHttp` serves, 2026-07-28, in both the header and `_meta`. It encodes the input with the action's schema, and decodes the success from `structuredContent`, as `ActionHttp.client` does for a route. A media field it takes only from the blocks whose `_meta` names it, `{ "effect-actions/field": "image" }`, in order, never from the structured content, and a success that is media, or whose every field is, from its blocks alone ([ActionMcp.md](ActionMcp.md#media)): the method succeeds with the success as the handler returned it, the image's `data` a `Uint8Array`, an optional image returned as `undefined` absent, as no block tells the two apart. It reads a JSON or an event-stream response.
+- A declared error, the action's own or a built-in one, is a typed failure of its decoded value: an `isError` result from the tool, or a 401 or 403 from the endpoint's authentication or an authorizer, whose body is the same JSON. Match it with `Effect.catchTag`, exactly as on the HTTP client.
+- Any other answer fails with `McpCallError`, whose `message` holds it: another status, the native server's own text (invalid arguments, a defect), no reply, a result without the `structuredContent` its success is sent as, or a JSON-RPC error (an unknown tool). Match it with `Effect.catchTag("McpCallError", ...)`. A success that does not decode, such as one missing the blocks of its media fields, fails with `SchemaError`, as it does from `ActionHttp.client`.
+- The input is typed, so a malformed call cannot be sent through a client method. To assert on a malformed call, another MCP method or the response itself, such as a refusal's status and `WWW-Authenticate` challenge, send `mcpRequest(method, params, options)`.
+- `mcpRequest` is one stateless request as a client method sends it, a native `HttpClientRequest` the test sends itself: with `mcp-name` from `params.uri` for `resources/read` and from `params.name` otherwise, and the client metadata in `_meta`. A `_meta` in `params`, such as a `progressToken`, is merged over the client metadata, and the protocol version is always the request's own.
+- Under `layer`, send it with `HttpClient.execute(Testing.mcpRequest("tools/list"))`, which succeeds with the response whatever its status.
+- A Promise test sends it as a web `Request`, to a web handler or to `fetch`, for a web `Response` back: `handler(Result.getOrThrow(HttpClientRequest.toWebResult(Testing.mcpRequest(method, params, { url: "http://localhost/mcp" }))))`. The `url` is absolute, the handler's origin or a listening server's, since a web `Request` has no `HttpClient` to resolve a relative one.
+- A tool call the typed client would not send is `mcpRequest("tools/call", { name, arguments })`, its result read from the response's JSON: `result.structuredContent`, or `result.isError` and `result.content`.
+- To assert on a result's exact bytes, such as a size bound, parse the text of an `mcpRequest`'s JSON response: `JSON.stringify` of the parsed message reproduces what the server wrote, less its final newline, so `JSON.stringify(message.result)` is the result as encoded.
+- A request under `layer` carries the `Host` header of its URL, `localhost` for a relative one, unless it sets its own, so middleware checking the host answers as it would over the network.
+- Add `Authorization` through `transformClient`, the same options for `mcpClient` and `ActionHttp.client`: one client per caller, `const alice = { transformClient: HttpClient.mapRequest(HttpClientRequest.bearerToken("alice")) }`. `mcpRequest` takes `headers`.
+- A client names each tool by its action and holds no connection. Duplicate action names throw `Duplicate action: <name>`.
+- Test what an implementation does in process, with `Action.client`: its authorizer, its handlers, and the checks every surface makes on input, success and failure, with several callers, an action no binding holds included. Test what a surface adds under `layer`: authentication, statuses, headers, bodies as sent and MCP results. The two call the same methods. Cover each surface the application exposes.
 
 ## Failure modes
 
-- `@modelcontextprotocol/client` not found: only `TestingClient` needs it. Install the peer in devDependencies, or use `Testing.mcpRequest` instead.
-- Type error on `versionNegotiation` in `withMcpClient` options: the revision is fixed at 2026-07-28. Delete the option.
-- `MCP tools/call "<name>" answered 401`: the call reached authentication without a credential. Pass `headers: { authorization: "Bearer ..." }`.
-- `MCP tools/call "<name>" failed with <code>: <message>`: a JSON-RPC error, such as an unknown tool. Assert on it with `mcpRequest`.
-- `MCP tools/call "<name>" had no reply` or `returned no structured content`: the response was not a tool result. Inspect it with `mcpRequest`.
-- Handler leaks between tests: `web.dispose()` was not called. Register it with the test runner's cleanup hook.
-- 404 from `httpClient`: the requested route was not mounted, or the path/base URL is wrong. Include `Http.layer([app])` in the served routes.
-- Missing platform-service requirements when constructing the web handler: provide `HttpServer.layerServices` to the routes before `toWebHandler`.
+- Fails with `Action.Unauthenticated`: the call reached authentication without a valid credential. Give the client a `transformClient` adding it, such as `HttpClient.mapRequest(HttpClientRequest.bearerToken(token))`.
+- `MCP tools/call "<name>" returned an error: Invalid parameters for tool ...`: the endpoint serves a different contract under that name than the one passed. Call it with the served contract value.
+- 404 from a client method: the action's implementation was not passed to any `ActionHttp.layer` call of its binding in the served routes, or `baseUrl` adds a path the routes do not have. Include `ActionHttp.layer(Http, implementations)` in the routes.
+- The program reads a service the handlers never changed: it was provided inside the routes and again to the program, two instances. Provide it once, around `layer`, with `Layer.provideMerge`.
+- `Type 'Provider<CurrentActor, "example.Login">' is not assignable to type 'never'` where the test runs, such as at `Effect.runPromise`: the routes serve a protected action and no provider of its descriptor is provided to them. Provide it to the routes, `ActionHttp.layer(Http, app).pipe(Layer.provide(authenticate))`, or a test verifier of the same descriptor. A caller provided around `layer` does not satisfy it ([Signed-in callers](#signed-in-callers)).
+- `Type 'CurrentActor' is not assignable to type 'never'` where the test runs: a public action's handler reads the identity, which no route provides it. Make the action protected.
+- A protected route answers 401 where the test expects a 415 or a 400: the request carries no credential that verifies, and authentication runs first. Send a token with requests about something else.
+- `Argument of type 'Layer<…, FileSystem | Generator | HttpPlatform | HttpRouter | Path>' is not assignable` at `HttpRouter.toWebHandler(routes)`, then `No overload matches this call` at `layer(web.handler)`, its last overload naming `Layer<unknown, unknown, unknown>`, or `Expected 2 arguments, but got 1` at `web.handler(request)`: the web handler's routes lack their platform services. Provide them: `HttpRouter.toWebHandler(routes.pipe(Layer.provide(HttpServer.layerServices)))`.
+- A builder or handler finds no file where one exists, failing with `NotFound: FileSystem.<method> (<path>)`, or a file route answers 500: nothing provided a `FileSystem` around `layer`, so the routes read a no-op one. Provide `NodeFileSystem.layer` or `NodeServices.layer` around it, with `Layer.provideMerge` where the program reads files too.
+- `MCP tools/call "<name>" answered 404`: the endpoint is not at `/mcp`. Pass its `url`.
+- `HttpClientRequest.toWebResult` or `toWeb` of an `mcpRequest` fails with `UrlError`: its `url` is the relative default. Pass an absolute `url`.
+- An `HttpClientError` whose reason is `InvalidUrlError`, from a client method or a sent `mcpRequest` on an `HttpClient` that prepends no base URL: a relative `url` resolves under `layer`, and under a client that prepends one, such as `NodeHttpServer.layerTest`'s. Pass an absolute `url`.