@gjermundgaraba/effect-actions 0.6.0 → 0.8.0

package/docs/ActionCli.md

@@ -1,17 +1,17 @@
 # ActionCli
 
 Native Effect CLI commands that run handlers in-process. The host provides every service;
-nothing is fetched over HTTP.
+nothing is fetched over HTTP. Any action runs locally, whether or not HTTP or MCP serves it.
 
 ## API
 
 Import `@gjermundgaraba/effect-actions/ActionCli`.
 
-| API                            | Purpose                                                           |
-| ------------------------------ | ----------------------------------------------------------------- |
-| `command(app, name, options?)` | One selected action as a native Effect `Command`.                 |
-| `group(app, options?)`         | Every action under a group command, including local-only actions. |
-| `Options`, `GroupOptions`      | Configuration for single and aggregate commands.                  |
+| API                            | Purpose                                           |
+| ------------------------------ | ------------------------------------------------- |
+| `command(app, name, options?)` | One selected action as a native Effect `Command`. |
+| `group(app, options?)`         | Every action under a group command.               |
+| `Options`, `GroupOptions`      | Configuration for single and aggregate commands.  |
 
 | Option                | Meaning                                                                                                      |
 | --------------------- | ------------------------------------------------------------------------------------------------------------ |
@@ -28,7 +28,7 @@ scope. Success output is encoded; failures remain failures of the command Effect
 
 ```ts
 import { Console, Effect, Logger } from "effect";
-import { Command, Flag } from "effect/unstable/cli";
+import { Command, Flag } from "effect/cli";
 import { NodeRuntime, NodeServices } from "@effect/platform-node";
 import * as ActionCli from "@gjermundgaraba/effect-actions/ActionCli";
 import { actors, authorize, CurrentActor } from "./auth.js";
@@ -56,7 +56,7 @@ Command.runWith(command, { version: "0.1.0" })(process.argv.slice(2)).pipe(
 
 ## Rules
 
-- `command(app, name)` selects one action by name from the bound group; the name is checked at the type level. `group(app)` puts every action under the group command, including actions with `http: false` and `mcp: false`.
+- `command(app, name)` selects one action by name from the bound group; the name is checked at the type level. `group(app)` puts every action under the group command, including actions with `mcp: false` and groups no HTTP binding serves.
 - Default syntax is `--input '<json>'` or `--input-file <path>` carrying the entire encoded input: nested objects, arrays, scalars. The file is read and JSON-parsed by the native `Flag.FileSchema`. Both are decoded by the native parser; if both are given, the file is used. Omitting both decodes `{}` separately on every invocation; result identity follows the codec's behavior. An action that requires input then fails with a `SchemaError`, exactly as a `parameters` command's mapped input does.
 - `parameters` and `input` are supplied together or not at all. With them, the command has explicit native flags and arguments and neither `--input` nor `--input-file`, so its syntax does not change when the schema changes.
 - `input(parsed)` returns encoded JSON. The action schema decodes it before dispatch; a mismatch is a `SchemaError` at runtime. Action fields are never turned into flags automatically.

package/docs/ActionCliClient.md

@@ -9,8 +9,8 @@ Import `@gjermundgaraba/effect-actions/ActionCliClient`.
 
 | API                                              | Purpose                                                                    |
 | ------------------------------------------------ | -------------------------------------------------------------------------- |
-| `command(http, groupName, actionName, options?)` | Call one HTTP-enabled action through a native Effect `Command`.            |
-| `group(http, groupName, options?)`               | Every HTTP-enabled action of a bound group under one command.              |
+| `command(http, groupName, actionName, options?)` | Call one action of the binding through a native Effect `Command`.          |
+| `group(http, groupName, options?)`               | Every action of a bound group under one command.                           |
 | `Options`, `GroupOptions`, `Connection`          | Single/aggregate command configuration and native HTTP connection options. |
 
 Single-command options: `name`, `render`, paired `parameters`/`input`, and `connection`.
@@ -25,7 +25,7 @@ retain the selected endpoint's client failures and middleware requirements, and
 ## Canonical
 
 ```ts
-import { Command } from "effect/unstable/cli";
+import { Command } from "effect/cli";
 import { Console, Effect, Logger } from "effect";
 import { NodeHttpClient, NodeRuntime, NodeServices } from "@effect/platform-node";
 import * as ActionCliClient from "@gjermundgaraba/effect-actions/ActionCliClient";
@@ -49,15 +49,15 @@ Authentication: `connection: { transformClient: HttpClient.mapRequest(HttpClient
 
 ## Rules
 
-- Selectors resolve from `http.groups` only. `groupName` must be a bound group; `actionName` must be an action of that group with `http: true`. Runtime guards reject dynamically supplied strings that the types would not accept.
+- Selectors resolve from `http.groups` only. `groupName` must be a bound group; `actionName` must be an action of that group. Runtime guards reject dynamically supplied strings that the types would not accept.
 - The host provides `HttpClient` and its configuration. Endpoint selection, credentials, and storage are the host's; nothing is inferred from action arguments.
-- Input is decoded by the action schema before dispatch, then passed to the native client at its normal codec boundary. Do not pre-encode values.
+- Input (`--input`, `--input-file`, or `input(parsed)`) is encoded JSON. The command decodes it with the action schema, and the native client re-encodes it with `Http.api`'s closed payload codec.
 - Input syntax (`--input`, `--input-file`, or `parameters`) and output (`render` and its `--json` flag) are exactly as in `ActionCli`.
-- Errors are the client's: declared errors, policy errors, `SchemaError`, and `HttpClientError`.
+- Errors are the client's: declared errors (the binding's `errors` included), policy errors, `SchemaError`, and `HttpClientError`.
 
 ## Failure modes
 
-- Type error on `actionName`: the action is `http: false`, or the group is not bound in this `Http`.
-- `HttpClient` missing at runtime: provide `NodeHttpClient.layerUndici` (or `FetchHttpClient.layer`) to the runtime.
-- Connection refused: `connection.baseUrl` is absent or wrong. It has no default.
+- Type error on `actionName`: the action is not in that group, or the group is not bound in this `Http`.
+- `HttpClient` unsatisfied (a type error at `runMain`): provide `NodeHttpClient.layerUndici` (or `FetchHttpClient.layer`) to the runtime.
+- `HttpClientError` with `reason._tag` `InvalidUrlError`: `connection.baseUrl` is absent; it has no default. Connection refused: `baseUrl` points at the wrong host or port.
 - 401 from the server: add `transformClient` to `connection`. The command adds no headers on its own.

package/docs/ActionGroup.md

@@ -31,7 +31,7 @@ builder's requirements.
 import { Effect, Schema } from "effect";
 import * as ActionGroup from "@gjermundgaraba/effect-actions/ActionGroup";
 import { CurrentActor } from "./auth.js";
-import { GetUser, RenameUser, WhoAmI } from "./contracts.js";
+import { Double, GetUser, RenameUser, WhoAmI } from "./contracts.js";
 import { Users } from "./users.js";
 
 class InvalidRequest extends Schema.TaggedError<InvalidRequest>()(
@@ -58,6 +58,8 @@ const schemaError = {
   },
 };
 
+export const MathActions = ActionGroup.make({ name: "math" }, Double);
+
 export const UserActions = ActionGroup.make(
   { name: "users", schemaError },
   GetUser,
@@ -91,10 +93,10 @@ const renames: "renameUser" = contracts["users.renameUser"].name;
 
 ## Rules
 
-- `name` matches `[A-Za-z0-9_-]+`, cannot be `then`, and must be unique within one `ActionHttp.make`. Action names must be unique within the group. MCP tool names must be unique within the group and within each Toolkit or MCP projection that serves it. Duplicates fail at `make`.
+- `name` matches `[A-Za-z0-9_-]+` and cannot be `then`. Action names are unique within the group. Group and MCP tool names are checked where they are served; see [guarantees.md](guarantees.md#namespaces).
 - Group `errors` are appended to each action's own `errors`, so every handler of the group may fail with them. A failure that only the surface produces belongs on the adapter instead (`ActionHttp.make`'s `errors`, `ActionMcp`'s and `ActionToolkit`'s `errors`), not here.
-- `implement` takes a complete record or an Effect producing one. Every action must have a handler; missing keys are compile errors. A record that still lacks one at runtime (plain JavaScript, a cast) throws at `implement`; a builder's record fails the adapter layer's build. Nothing is served with a handler missing. Additional keys are not dispatched. It takes nothing else.
-- The builder Effect runs once per adapter layer that serves the implementation, in that layer's scope. An implementation served by HTTP and MCP is built twice. Acquire shared state in a Layer you provide to the adapters, not in the builder.
+- `implement` takes a complete plain record or an Effect producing one. Every action must have a handler; missing keys are compile errors. A handler is an own-property function of the record: an inherited one, such as a class instance's method, does not count. A record that still lacks one at runtime (plain JavaScript, a cast: a missing key, `undefined`, any other non-function, an inherited method) throws at `implement`; a builder's record fails the adapter layer's build. Nothing is served with a handler missing. Handlers are called without a receiver. Additional keys are not dispatched. It takes nothing else.
+- The builder Effect runs once per adapter layer that serves the implementation, in that layer's scope, and once per invocation under `ActionCli`. An implementation served by HTTP and MCP is built twice. Acquire shared state in a Layer you provide to the adapters, not in the builder.
 - Services yielded in the builder are build-time requirements (`RX`). Services yielded in a handler are request-time requirements (`R` of the handler). Adapters keep these separate in their types. Use distinct tags for each kind; never provide a request-identity tag at startup (see [guarantees.md](guarantees.md)).
 - `Implementation` is nominal. Spreading its properties does not produce an implementation. Each `implement` call is a separate binding.
 - `build` exists for direct handler tests under `Effect.scoped`. It bypasses transport validation and the hook, and is not a substitute for adapter tests. There is no public handler service or Layer.
@@ -109,18 +111,18 @@ const renames: "renameUser" = contracts["users.renameUser"].name;
 - MCP is unaffected. The native `McpServer` answers invalid arguments and unencodable results itself.
 - Policy errors extend the transport contract, not the handler contract. A handler cannot return them.
 - The policy runs only on the server. Client-side codec failures stay `SchemaError`.
-- HTTP decodes with `errors: "all"`, so `cause` carries every issue. Issues never retain the rejected values.
+- HTTP decodes input with `errors: "all"`, so an `invalid` `cause` carries every issue. Issues never retain the rejected values.
 - Groups served by one adapter may have different policies; each action answers with its own group's.
 - Input schema-error policies run before the `before` hook. Invalid input is answered by the policy without invoking the hook or handler.
 - Domain errors, defects, interruptions, and protocol errors are not remapped. An unencodable declared error is a defect. A broken policy error is not recursively remapped.
 
 ## Failure modes
 
-- Throws at `make`: duplicate action name, duplicate MCP tool name, invalid group name.
+- Throws at `make`: `Duplicate action: <name>` or `Invalid action group name: <name>`.
 - `Property 'x' is missing in type` at `implement`: the record lacks a handler for action `x`.
 - Handler compiles but returns an error not in `errors`: type error on the handler's error channel. Declare it on the action or the group.
 - `Expected 1 arguments, but got 2` at `implement`: the second options object is gone. Move `before` to the adapter that serves the group.
-- `Parameter 'failure' implicitly has an 'any' type` in a standalone policy constant: a `make` that reads the failure is typed only inline. Annotate the parameter as `HttpApiError.HttpApiSchemaError` (type import from `effect/unstable/httpapi`), or annotate the constant as `ActionGroup.SchemaErrorPolicy<typeof Invalid, typeof Internal>`.
-- `Missing handlers for group "<group>": <actions>` thrown at `implement`, or failing the layer build: the handler record lacks those actions. Add them.
+- `Parameter 'failure' implicitly has an 'any' type` in a standalone policy constant: a `make` that reads the failure is typed only inline. Annotate the parameter as `HttpApiError.HttpApiSchemaError` (type import from `effect/http-api`), or annotate the constant as `ActionGroup.SchemaErrorPolicy<typeof Invalid, typeof Internal>`.
+- `Missing handlers for group "<group>": <actions>` thrown at `implement`, or failing the layer build: the handler record has no own-property function for those actions. Add them to the record itself, not to a prototype.
 - A service is resolved once and shared across requests when it should be per request: it was yielded in the builder. Move the `yield*` into the handler.
 - `Duplicate contract group` thrown by `contracts`: two groups share a name, so their keys would collide. Rename one.

package/docs/ActionHttp.md

@@ -23,9 +23,8 @@ Exported types: `Options`, `LayerOptions`, `Http`, `Api`.
 | `make`: `errors`  | Surface error codecs declared on every endpoint; defaults to none.                                                                                          |
 | `layer`: `before` | Effectful hook receiving the selected `Action.Any`, after successful input decoding and before its handler. Failures must belong to the binding's `errors`. |
 
-Layer failures and startup requirements come from the supplied implementations that actually
-serve HTTP actions. Served handlers' and the hook's request services remain router request
-requirements; router/platform services are also required. No request identity is supplied at startup.
+Layer failures and startup requirements come from the supplied implementations. Every
+handler's and the hook's request services remain router request requirements; router/platform services are also required. No request identity is supplied at startup.
 
 Route shape: `POST <apiPath>/<group>/<action>`. Operation ID: `<group>.<action>`.
 
@@ -33,7 +32,7 @@ Route shape: `POST <apiPath>/<group>/<action>`. Operation ID: `<group>.<action>`
 
 ```ts
 import { Layer } from "effect";
-import { HttpApiScalar, HttpApiSwagger } from "effect/unstable/httpapi";
+import { HttpApiScalar, HttpApiSwagger } from "effect/http-api";
 import * as ActionHttp from "@gjermundgaraba/effect-actions/ActionHttp";
 import { PublicActions, UserActions } from "./contracts.js";
 import { PublicApp, UserApp } from "./handlers.js";
@@ -74,9 +73,9 @@ The client is Effect's native grouped `HttpApiClient` over `Http.api`. Code that
 run Effects uses the Promise client in [ActionHttpClient.md](ActionHttpClient.md).
 
 ```ts
-import { HttpApiClient } from "effect/unstable/httpapi";
+import { HttpApiClient } from "effect/http-api";
 import { Effect } from "effect";
-import { FetchHttpClient } from "effect/unstable/http";
+import { FetchHttpClient } from "effect/http";
 import { Http } from "./quickstart.js";
 
 export const greeting = Effect.gen(function* () {
@@ -88,34 +87,35 @@ export const greeting = Effect.gen(function* () {
 
 ## Rules
 
+- HTTP serves every action of every group passed to `make`; an action has no HTTP switch. To keep an action off HTTP, put it in a group left out of `make` and serve that group elsewhere (MCP, Toolkit, CLI).
 - `apiPath` has no default. Group names must be unique within one `make`. Action names need only be unique within their group; equal action names in different groups do not collide.
 - `errors` declares the failures the surface around these endpoints answers with rather than a handler: authentication, authorization, rate limiting, upstream unavailability. They are added to every endpoint's error schemas, so `HttpApiClient`, `ActionCliClient` and the in-memory `Testing.httpClient` decode them as typed failures, and they appear in OpenAPI on every operation. A schema an action already declares is not repeated.
 - Schemas reachable from one endpoint must have distinct `_tag`s: the client decodes a response by trying the schemas declared for its status, and two errors may share a status. Effect unions them per status.
 - `errors` changes only what is declared. Nothing produces them: the middleware that renders those responses must encode a body that matches the schema, or the client sees a decode error again. Handlers cannot fail with them.
-- `Http.layer(apps, options?)` requires each implementation to reference the exact group object passed to `make`; reconstructing an equal-looking group is not sufficient. Each group may occur only once per call. Only supplied implementations are mounted, and a group with no HTTP-enabled actions is not built. Options are optional.
+- `Http.layer(apps, options?)` requires each implementation to reference the exact group object passed to `make`; reconstructing an equal-looking group is not sufficient. Each group may occur only once per call. Only supplied implementations are mounted, and a group without actions is not built. Options are optional.
 - `before` runs after successful native input decoding and before the selected handler. Invalid input skips the hook and handler. A refusal uses the binding's declared error schema and `httpApiStatus`; its services join handler request requirements. Admission that must precede decoding belongs in outer native HTTP middleware.
 - Middleware and the hook are per layer call. Groups that need different middleware or a different policy go in separate `Http.layer` calls, merged with `Layer.mergeAll`.
 - `ActionHttp` sets no response headers of its own. The host owns cache policy; `Authentication.middleware` marks its responses `cache-control: no-store`.
 - A hook refusal and a handler error are plain declared errors: a JSON body and a status, no other headers. Challenge headers such as `WWW-Authenticate` belong to the admission middleware that runs before the router reaches these routes (see [Authentication.md](Authentication.md)), which sets them on its own response.
 - Request-time handler services are `HttpRouter.Request.From<"Requires", R>`. Supply them with router middleware (`Authentication.middleware`, `HttpRouter.middleware`), `HttpRouter.provideRequest`, or the request context. Build-time services are ordinary layer requirements.
-- `Http.api` is a plain `HttpApi`. Anything Effect can do with an `HttpApi` works: `OpenApi.fromApi`, `HttpApiSwagger.layer`, `HttpApiScalar.layer`, `HttpApi.addHttpApi` to combine with other APIs, `HttpApiClient.make`.
+- `Http.api` is a plain `HttpApi`. Anything Effect can do with an `HttpApi` works: `OpenApi.fromApi`, `HttpApiSwagger.layer`, `HttpApiScalar.layer`, `Http.api.addHttpApi(other)` to combine with other APIs, `HttpApiClient.make`.
 - `Http.openApi(path?)` is `OpenApi.fromApi(Http.api)` as one `GET` route, `<apiPath>/openapi.json` unless a path is given. It documents every bound group, not only the served ones. It is a plain route: middleware provided to its layer covers it, and nothing covers it otherwise.
 - Client calls always take `{ payload }`. No-input actions take `{ payload: {} }`. Pass `null` or `undefined` only when the codec accepts it. There is no flat client.
-- Client effects fail with the declared errors, the group's policy errors, the binding's `errors`, `SchemaError` for local codec failures, and native `HttpClientError`. MCP-only actions are absent from the client.
+- Client effects fail with the declared errors, the group's policy errors, the binding's `errors`, `SchemaError` for local codec failures (including an undeclared input field, before sending), and native `HttpClientError`.
 - Add authentication headers with the native `transformClient` option. Use `HttpApiClient.makeWith` for custom error or service channels. Native per-call response modes are available.
 - Wire format without a policy: input failure is an empty 400, success is the encoded body, a declared error is its JSON encoding with its `httpApiStatus`, an encoding failure is an empty 400, a defect is an empty 500. Full table in [guarantees.md](guarantees.md).
 - Each handler runs in a span named `<group>.<action>`, a child of the request span, attributed with `action.group`, `action.name` and `action.access`; its log lines carry the same annotations. The hook, decoding and encoding are outside it, in the request span.
 
 ## Failure modes
 
-- Route returns 404: the implementation was never passed to `Http.layer`, or the action has `http: false`, or the path lacks the group segment.
+- Route returns 404: the implementation was never passed to `Http.layer`, or its group is not bound by `make`, or the path lacks the group segment.
 - Type error listing `HttpRouter.Request.From<"Requires", CurrentActor>` as unsatisfied: a handler yields a request service and no middleware provides it. Wrap that `Http.layer` call with the middleware's `.layer`.
 - Two groups share a name: `make` throws. Rename one.
 - `Implementation of group "x" is not served by this adapter`: `Http.layer` received an implementation whose group was not passed to `ActionHttp.make`. Implement the exact shared group object bound by `make`, or add a genuinely new group to the binding. Matching names and schemas do not establish identity.
 - `Duplicate implementation group: <name>`: a single `Http.layer` call received more than one implementation of the same group. Pass one implementation per group.
-- Client method missing for an action: the action is `http: false`.
-- Empty 400 on a valid-looking request: input did not decode. Set a `schemaError` policy on the group to get a typed body, and check `Content-Type: application/json`.
-- 415: wrong or missing content type.
+- Client method missing for an action: its group is not bound by `make`.
+- Empty 400 on a valid-looking request: input did not decode, or it carries a field the action does not declare. Set a `schemaError` policy on the group to get a typed body.
+- 415 `Unsupported content-type: <type>`: a content type other than `application/json`. A missing `Content-Type` is read as JSON.
 - `HttpClientError: Decode error (401 POST ...)` from a typed client: the surface answered with a status no endpoint declares. Add that error schema to `ActionHttp.make`'s `errors`.
 - A surface error decodes as the wrong type: two schemas that share a status also share a `_tag`. Give them distinct tags.
 - The hook's services appear as unsatisfied `HttpRouter.Request.From<"Requires", ...>`: the hook yields an identity tag and this `Http.layer` call has no middleware providing it. Wrap that call with the middleware's `.layer`.

package/docs/ActionHttpClient.md

@@ -7,17 +7,21 @@ page. It is Effect's native `HttpApiClient` over `fetch`, built once; each call
 
 Import `@gjermundgaraba/effect-actions/ActionHttpClient`.
 
-| API                       | Purpose                                                                       |
-| ------------------------- | ----------------------------------------------------------------------------- |
-| `promise(http, options?)` | `client.<group>.<action>(input)` for every HTTP-served action of the binding. |
-| `Options`                 | Where and how requests are sent.                                              |
-| `Client`, `Method`        | The client's type, derived from the binding, and one action's method.         |
-
-| Option    | Meaning                                                                                                                         |
-| --------- | ------------------------------------------------------------------------------------------------------------------------------- |
-| `baseUrl` | What routes are resolved against, such as `https://api.example.com`. Omitted: relative routes (the page's origin in a browser). |
-| `token`   | Sent as `Authorization: Bearer <token>` with every call.                                                                        |
-| `fetch`   | The transport. Defaults to the global `fetch`, looked up on each call.                                                          |
+| API                       | Purpose                                                               |
+| ------------------------- | --------------------------------------------------------------------- |
+| `promise(http, options?)` | `client.<group>.<action>(input)` for every action of the binding.     |
+| `Options`                 | Where and how requests are sent.                                      |
+| `Client`, `Method`        | The client's type, derived from the binding, and one action's method. |
+
+The options are the native `HttpApiClient.make` options except `transformResponse`, plus `fetch`.
+`transformResponse` may change a call's success, failure or required services, which neither
+the method types nor a Promise can follow; wrap `fetch` or use `transformClient` instead.
+
+| Option            | Meaning                                                                                                                         |
+| ----------------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| `baseUrl`         | What routes are resolved against, such as `https://api.example.com`. Omitted: relative routes (the page's origin in a browser). |
+| `transformClient` | Wraps the native `HttpClient`. A bearer token: `HttpClient.mapRequest(HttpClientRequest.bearerToken(token))`.                   |
+| `fetch`           | The transport. Defaults to the global `fetch`, looked up on each call.                                                          |
 
 A method takes the action's decoded input and resolves with its decoded success. An action
 whose input may be empty (no `input`, or only optional fields) may be called without an argument.
@@ -25,14 +29,16 @@ whose input may be empty (no `input`, or only optional fields) may be called wit
 ## Canonical
 
 ```ts
-import { HttpClientError } from "effect/unstable/http";
+import { HttpClient, HttpClientError, HttpClientRequest } from "effect/http";
 import * as ActionHttpClient from "@gjermundgaraba/effect-actions/ActionHttpClient";
 import { Http, UserNotFound } from "./contracts.js";
 
 // Promises in, Promises out: for code that does not run Effects, such as a browser page.
+// The options are the native `HttpApiClient.make` options plus `fetch`; a bearer token is
+// a `transformClient`.
 const client = ActionHttpClient.promise(Http, {
   baseUrl: "http://127.0.0.1:3000",
-  token: "alice",
+  transformClient: HttpClient.mapRequest(HttpClientRequest.bearerToken("alice")),
 });
 
 export const userName = async (id: string): Promise<string> => {
@@ -52,22 +58,23 @@ export const userName = async (id: string): Promise<string> => {
 };
 ```
 
-Other headers, or reacting to a response every call may meet (a proxy's 401), go through
-`fetch`: `fetch: (input, init) => { const request = new Request(input, init); request.headers.set("x-agent", agent); return fetch(request); }`.
+Other headers also go through `transformClient` (`HttpClient.mapRequest(HttpClientRequest.setHeader("x-agent", agent))`).
+Reacting to a response every call may meet (a proxy's 401), or a token read per call, goes through
+`fetch`: `fetch: (input, init) => { const request = new Request(input, init); request.headers.set("authorization", "Bearer " + readToken()); return fetch(request); }`.
 
 ## Rules
 
 - A call rejects with exactly what the native client's Effect fails with. Declared errors arrive as their decoded values: the action's own (its group's `errors` included), its group's schema-error policy's, and the binding's surface `errors`. Classify them with `instanceof`, their `_tag`, or `Schema.is`.
-- Anything the contract does not account for rejects with Effect's own error. `HttpClientError`: the server could not be reached (`response` is `undefined`), or answered with a status no schema declares, or with a body that could not be read. `SchemaError`: the input did not encode, or the success body did not decode.
+- Anything the contract does not account for rejects with Effect's own error. `HttpClientError`: the server could not be reached (`response` is `undefined`), or answered with a status no schema declares, or with a body that could not be read. `SchemaError`: the input did not encode (including a field the action does not declare; nothing is sent), or the success body did not decode.
 - The library adds no error type of its own and interprets no status. Which failures mean "signed out" or "try again" is the caller's decision.
 - Nothing is retried. A rejected write may or may not have happened; only a declared error says what the server did.
-- Only HTTP-served actions have methods. An action with `http: false` is absent, and so is a group without HTTP actions.
+- Every action of a bound group has a method. A group without actions has no namespace.
 - The client holds no connections or timers. Making one is synchronous and sends nothing.
 - A method is not an Effect. Code that runs Effects uses `HttpApiClient.make(Http.api)` directly (see [ActionHttp.md](ActionHttp.md)); its methods take `{ payload }`.
 
 ## Failure modes
 
-- Rejects with `HttpClientError` whose `reason._tag` is `StatusCodeError` for a 401 or 403: the surface answered with an error the binding does not declare. Add it to `ActionHttp.make`'s `errors`, and have the middleware encode it.
+- Rejects with `HttpClientError` whose `reason._tag` is `DecodeError` (`Decode error (401 POST ...)`) for a 401 or 403: the surface answered with an error the binding does not declare. Add it to `ActionHttp.make`'s `errors`, and have the middleware encode it.
 - Rejects with `HttpClientError` whose `reason._tag` is `InvalidUrlError` outside a browser: `baseUrl` is omitted, and there is no page to resolve relative routes against. Set `baseUrl`.
 - A stubbed global `fetch` is not used: `fetch` was passed as an option, which takes precedence.
-- Property does not exist on the client: the action is `http: false`, or its group is not bound in this `Http`.
+- Property does not exist on the client: the action's group is not bound in this `Http`.

package/docs/ActionMcp.md

@@ -74,7 +74,7 @@ choose its policy for every route it covers.
 
 ```ts
 import { Effect, Layer } from "effect";
-import { HttpRouter } from "effect/unstable/http";
+import { HttpRouter } from "effect/http";
 import * as ActionMcp from "@gjermundgaraba/effect-actions/ActionMcp";
 import { Actions } from "./quickstart.js";
 
@@ -142,14 +142,16 @@ Layer.launch(layer).pipe(
 
 ## Rules
 
-- Both transports serve MCP 2026-07-28 and no other revision; there is no `protocols` option. Over HTTP the endpoint is stateless: no initialize handshake, no session, and every request stands alone. Effect owns version checks and rejects any other revision.
-- `path` has no default. `layerHttp` uses the single-endpoint Streamable HTTP transport, never the two-endpoint HTTP+SSE form, whatever revision is negotiated.
+- Both transports serve MCP 2026-07-28 and no other revision; there is no `protocols` option. Over HTTP the endpoint is stateless: no initialize handshake, no session, and every request stands alone. Effect owns version checks and rejects any other revision. Stdio has no sessions, so it could serve an older host, but it refuses one deliberately, for uniformity: a client that works over one transport works over the other.
+- `path` has no default. `layerHttp` uses the single-endpoint Streamable HTTP transport, never the two-endpoint HTTP+SSE form.
 - Requests reaching the native MCP handler with an `Origin` header receive **403** unless that exact origin is listed in `allowedOrigins`. Requests without `Origin` pass this check. Authentication middleware wrapping the endpoint runs first and may reject the request before native Origin validation; the allowlist does not protect authentication from untrusted-origin requests.
 - `allowedOrigins` is an Origin allowlist, not CORS configuration. Cross-origin browser clients also need outer CORS middleware or a proxy to handle preflight and add response headers. Without it, an allowed-origin `OPTIONS` request receives **405** and even a successful `POST` has no `Access-Control-Allow-Origin`. Keep preflight outside authentication and apply CORS headers to refusals too.
 - An endpoint is one route. Middleware provided to `layerHttp` covers all of its tools. To serve tools under different middleware, mount them on different paths with separate `layerHttp` calls.
-- Only MCP-enabled actions become tools, under `mcp.name` with the resolved hints. A group with no tools is not built.
+- Only MCP-enabled actions become tools, under `mcp.name` with the resolved hints. A group with no tools is not built. The layer's types drop an action's requirements only when its type is certainly hidden (a literal `mcp: false`, see [Action.md](Action.md)); an `mcp` that may be `false` at runtime keeps them.
 - Every MCP-enabled action must have object-root input; the native server refuses anything else when the layer is built. Omit `input` for a tool with no arguments.
-- Success is `structuredContent: { value: <encoded success> }`. A declared error is an `isError` result whose text content is the error's JSON encoding, the same bytes HTTP sends as the body, and no `structuredContent`.
+- Success is `structuredContent: <encoded success>`, of any JSON type, and one text block holding the same JSON, as the specification recommends. The tool's `outputSchema` describes the encoded success. A declared error is an `isError` result whose text content is the error's JSON encoding, the same bytes HTTP sends as the body, and no `structuredContent`.
+- With a text field (`mcp.text`), a success is `content: [<field>, <JSON of the rest>]` and `structuredContent: <the rest>`. The field is sent once, verbatim, and is left out of `structuredContent` and of the listed `outputSchema`. Use it for a body the model should read raw, such as a page of Markdown: in structured content it would be JSON-escaped, and sent twice. The field must be a top-level property of the success's JSON Schema. A success without the field as a string, such as one that omits an optional field, is sent whole.
+- Besides `content`, `structuredContent` and `isError: false`, the server adds `_meta["io.modelcontextprotocol/serverInfo"]` and `resultType: "complete"` to every result. `serverInfo` is the layer's `name`, `version`, `description`, `websiteUrl` and `icons`, as given, so a result's encoded size is the size of its own fields plus a fixed overhead per endpoint, the same over HTTP and stdio.
 - Invalid arguments and unencodable results are answered by the native `McpServer`: an `isError` result with a message for the model. Group `schemaError` policies do not apply.
 - Defects and encoding failures produce the generic `isError` text `Tool execution failed due to an internal server error.`; the cause is logged, not sent.
 - Tool discovery is not filtered by actor. Every caller sees every tool of the endpoint. Authorization happens in `before`.
@@ -163,7 +165,7 @@ Layer.launch(layer).pipe(
 ## Failure modes
 
 - Layer build dies while registering tools, with a defect whose `SchemaError` message says `Expected "object"` or `Missing key`: an MCP-enabled action has scalar, array, or empty-struct input, which the native server refuses. It is not in the layer's error channel, so it cannot be caught by tag. Wrap the input in a struct with at least one field, omit `input` for no arguments, or set `mcp: false`.
-- `Duplicate MCP tool: <name>` thrown at the `layerHttp` or `layerStdio` call: two apps on one endpoint expose the same tool name. Rename with `mcp.name` or split the endpoint.
+- `Duplicate MCP tool: <name>` thrown at the `layerHttp` or `layerStdio` call: two actions on one endpoint expose the same tool name. Rename with `mcp.name` or split the endpoint.
 - Type error listing `HttpRouter.Request.From<"Requires", ...>`: a handler yields a request service and the endpoint has no middleware providing it. Provide it with `Layer.provide(middleware.layer)` on that `layerHttp`.
 - Public tool requires a token: it shares an endpoint with protected tools. Give it its own path.
 - Client reports a broken transport from a stdio subprocess: something printed to stdout. Set `Logger.LogToStderr` and remove `console.log`.
@@ -172,4 +174,5 @@ Layer.launch(layer).pipe(
 - A disallowed Origin receives 401 instead: wrapping authentication rejected it before the native Origin check. Put any required pre-authentication Host/Origin policy in outer host middleware.
 - Browser calls fail despite an allowed Origin: configure CORS outside authentication and the MCP handler (see the browser example above). The native allowlist alone neither handles preflight nor adds CORS response headers.
 - `Object literal may only specify known properties, and 'protocols'`: the revision is fixed. Delete the option.
+- Layer build dies with `MCP tool '<name>' cannot send '<field>' as text: it is not a top-level property of its success`: the success's JSON Schema has no such top-level property, as for a union of structs. Make the success one struct.
 - A refusal arrives as a generic internal-error result: the hook failed with an error this transport does not declare, which is a defect. Add its schema to `errors`.

package/docs/ActionToolkit.md

@@ -51,8 +51,8 @@ With a model: pass `binding.toolkit` as `toolkit` to `LanguageModel.generateText
 
 ## Rules
 
-- Selects MCP-enabled actions only, named by `mcp.name`, with resolved hints. Groups with no selected tools are not built. `make(apps, options?)` accepts a readonly implementation collection; options may be omitted.
-- Successes are the action's native values. There is no `{ value }` wrapper. Declared failures are returned as native tool results (`failureMode: "return"`), not raised.
+- Selects MCP-enabled actions only, named by `mcp.name`, with resolved hints. Groups with no selected tools are not built. The toolkit's type follows `ActionMcp`'s rule: only an action whose `mcp` type is exactly `false` has no tool; one whose `mcp` may be `false` at runtime is typed as a tool with its handler's requirements. `make(apps, options?)` accepts a readonly implementation collection; options may be omitted.
+- Successes are the action's native values, whole: `mcp.text` does not apply. Declared failures are returned as native tool results (`failureMode: "return"`), not raised.
 - `tools.handle(name, encodedInput)` takes encoded arguments and returns an Effect producing a result stream. The handler starts while that stream is constructed, so request services must be provided around the entire `handle(...).pipe(Effect.flatMap(Stream.runCollect))`, not only around the stream.
 - `binding.layer` acquires each implementation once, in the layer's scope. Build-time requirements belong to the whole selected implementation.
 - Each tool carries only its own handler's request requirements, plus the hook's, not those of sibling or disabled tools.
@@ -65,7 +65,7 @@ With a model: pass `binding.toolkit` as `toolkit` to `LanguageModel.generateText
 
 - Tool missing from the toolkit: the action has `mcp: false`. The Toolkit selects by MCP enablement.
 - Type error on `before`'s error channel: it fails with an error this binding does not declare. Add its schema to `errors`.
-- `Duplicate MCP tool: <name>` thrown at `make`: two apps expose the same tool name. Rename with `mcp.name`.
-- `Service not found` for a request tag at call time: it was provided only to the stream, or only to the layer. Provide it around the whole call effect.
+- `Duplicate MCP tool: <name>` thrown at `make`: two selected actions expose the same tool name. Rename with `mcp.name`.
+- `Service not found` for a request tag at call time: it was provided only to the stream. Provide it around the whole call effect. Providing it to `binding.layer` does not fail: the startup value is captured and served to every call (see [guarantees.md](guarantees.md)).
+- A returned failure that is an `AiError` with reason `ToolParameterValidationError`, not a declared error: the arguments did not decode. The hook and the handler did not run.
 - Type error on `binding.layer` requirements: a build-time service is missing. Provide its Layer before `binding.layer`.
-- Result is `{ value: ... }` when a plain value was expected: you are reading an MCP response, not a Toolkit result. The Toolkit never wraps.

package/docs/Authentication.md

@@ -29,7 +29,7 @@ to routes requiring that identity.
 
 ```ts
 import { Context, Effect, Layer, Option, Schema } from "effect";
-import { HttpServerRequest, HttpServerResponse } from "effect/unstable/http";
+import { HttpServerRequest, HttpServerResponse } from "effect/http";
 import * as Authentication from "@gjermundgaraba/effect-actions/Authentication";
 
 interface Actor {
@@ -84,7 +84,7 @@ export const routes = Layer.mergeAll(
 - Downstream action errors are handled by their transport. They are never serialized as authentication failures.
 - Use distinct tags for startup capabilities and request identities. Never provide `CurrentActor` or any identity or tenant tag in a startup layer or root context. Native context capture can let a startup value shadow the request value or satisfy a missing one, and the adapters add no isolation boundary. Types track that the tag is required, not where its value came from.
 - `protectedResource` publishes what it is given. The deployment must ensure `resource` and `authorizationServers` are valid OAuth URLs (HTTPS, or loopback HTTP in development).
-- Discovery is served at `/.well-known/oauth-protected-resource` followed by the resource's path and query, for `GET` and `HEAD`, matching that literal path and query. Other requests fall through to the host router. Mount `discovery.layer` outside the authenticated layers. Caching policy is the host's.
+- Discovery is served at `/.well-known/oauth-protected-resource` followed by the resource's path and query, for `GET` and `HEAD`, matching that literal path and query. Other requests fall through to the host router. `discovery.layer` is global router middleware: it answers before any route middleware, so authentication never covers it. Caching policy is the host's.
 - `challenge()` quotes and escapes parameter values; it never rejects them. Name only the scopes needed for the request in `scope`; `scopesSupported` advertises the full set in metadata.
 - Tool discovery is never filtered by actor. Authorization belongs in each surface's `before` hook, which runs with the action contract in hand; write the rule against `action.access` rather than repeating a check in each handler.
 - A response this middleware renders is not part of any endpoint's contract. Declare its schema in `ActionHttp.make`'s `errors` so typed clients decode the 401 instead of reporting a decode error ([ActionHttp.md](ActionHttp.md)).
@@ -94,6 +94,5 @@ export const routes = Layer.mergeAll(
 - Handler sees a stale or wrong actor: an identity tag was provided at startup. Remove it from every startup layer; provide it only through the middleware.
 - Type error `HttpRouter.Request.From<"Requires", CurrentActor>` unsatisfied: the layer serving that implementation was not wrapped with `authentication.layer`.
 - Discovery returns 404: the request path does not match `resource`'s path and query exactly, or `discovery.layer` is not merged into the served layer.
-- Discovery requires a token: `discovery.layer` was placed under the authentication middleware. Mount it separately.
 - 401 response lacks `WWW-Authenticate`: the host's failure response did not set it. Use `discovery.challenge(...)` in its headers.
 - A typed client reports `Decode error (401 ...)` instead of the failure schema: the response this middleware renders is not declared. Add it to `ActionHttp.make`'s `errors`.

package/docs/CONTEXT.md

@@ -5,7 +5,7 @@ use these words with these meanings.
 
 ## Terms
 
-- **Action**: one contract. A name, a description, an input schema, a success schema, declared error schemas, authorization metadata (`access`), and transport metadata (`http`, `mcp`). Holds no behavior. Made by `Action.make`.
+- **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.
@@ -16,26 +16,26 @@ use these words with these meanings.
 - **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`); `ActionToolkit.make` returns the Toolkit binding (`toolkit`, `layer`).
+- **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.
-- **Local-only action**: `http: false` and `mcp: false`. Reachable through `ActionCli` and listed in the catalog.
 - **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 HTTP action, for code that does not run Effects. It rejects with what the native client fails with.
+- **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 nothing transport-specific and know nothing about HTTP, MCP, or the CLI.
+- `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 and defines no application error types.
+- 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.

package/docs/README.md

@@ -1,15 +1,16 @@
 # effect-actions reference
 
-Reference for `@gjermundgaraba/effect-actions`, written for coding agents. Every page is a
+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
 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.
 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 accepts any 4.0 release candidate from `4.0.0-rc.116` on (`>=4.0.0-rc.116 <4.0.0`). The package is built and tested against `4.0.0-rc.117`.
+- The `effect` peer accepts any 4.0 release candidate from `4.0.0-rc.118` on (`>=4.0.0-rc.118 <4.0.0`). The package is built and tested against `4.0.0-rc.118`.
 - Contracts are pure values. Nothing runs, binds, or acquires services until an adapter layer is built.
 
 ## Pages
@@ -83,9 +84,8 @@ Repository directory `examples/` ([on GitHub](https://github.com/gjermundgaraba/
 
 - `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`, `handlers.ts`, `app.ts`, `server.ts`: an authenticated application with three groups, per-group middleware, two MCP endpoints, OpenAPI and Swagger.
+- `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.

package/docs/Testing.md

@@ -16,7 +16,7 @@ Import `@gjermundgaraba/effect-actions/Testing`; official-client helpers are in
 | `TestingClient.withMcpClient(options, run)`  | Connect the official client, run an asynchronous callback, then close it.                             |
 
 `httpClient` takes native client options; `baseUrl` defaults to `http://localhost`.
-Its exported `Handler` type is a web request to response Promise.
+Its exported `Handler` type is a web request to response Promise, not an action handler.
 
 | MCP option                            | Meaning                                                     |
 | ------------------------------------- | ----------------------------------------------------------- |
@@ -34,7 +34,7 @@ Exported option/value types: `McpRequestOptions`, `McpRequestParams`, `McpReques
 
 ```ts
 import { Effect, Layer } from "effect";
-import { HttpRouter, HttpServer } from "effect/unstable/http";
+import { HttpRouter, HttpServer } from "effect/http";
 import * as Testing from "@gjermundgaraba/effect-actions/Testing";
 import * as TestingClient from "@gjermundgaraba/effect-actions/TestingClient";
 import { Http, routes } from "./quickstart.js";
@@ -78,17 +78,20 @@ try {
 - `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.value`, 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.
+- `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, and middleware. Keep at least one adapter-level test per transport.
+- 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.
 
 ## Failure modes
 
 - `@modelcontextprotocol/client` not found: only `TestingClient` needs it. Install the peer in devDependencies, or use `Testing.mcpRequest` instead.
-- `withMcpClient` rejects its options with `versionNegotiation`: the revision is fixed at 2026-07-28. Delete the option.
+- 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`.

package/docs/guarantees.md

@@ -24,7 +24,7 @@ Defaults without a schema-error policy. HTTP is a native `HttpApi`; MCP is a nat
 | Case                        | HTTP                                                                                                  | MCP                                                                                                    |
 | --------------------------- | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
 | Input                       | decoded with the schema's JSON codec; failure is an empty **400**                                     | decoded with the schema's JSON codec; failure is `InvalidParams`, presented as an `isError` result     |
-| Success                     | the success codec's encoding as the body: `{"id":"1","name":"Ada"}`, `42`                             | `structuredContent: { value: <encoded> }`                                                              |
+| Success                     | the success codec's encoding as the body: `{"id":"1","name":"Ada"}`, `42`                             | `structuredContent: <encoded>`, and its JSON as text content; a text field is sent as text instead     |
 | Declared error              | encoded by its schema with its `httpApiStatus` (unannotated: 500): `{"_tag":"UserNotFound","id":"x"}` | `isError: true`; text content is the same JSON; no `structuredContent`                                 |
 | Pre-handler hook failure    | the same, using the hook's error schema, after input decoding; the handler never runs                 | the same `isError` result, after arguments are decoded; the handler never runs                         |
 | Invalid output encoding     | empty **400** (`HttpApiSchemaError`)                                                                  | `isError: true`, text `Tool execution failed due to an internal server error.`; cause logged, not sent |
@@ -32,17 +32,18 @@ Defaults without a schema-error policy. HTTP is a native `HttpApi`; MCP is a nat
 | Unknown path or method      | 404                                                                                                   | n/a                                                                                                    |
 | Invalid JSON / content type | 400 / 415                                                                                             | n/a                                                                                                    |
 
+- `mcp.text` changes only the MCP success result. HTTP, OpenAPI, typed clients, the Toolkit, the CLI and its client, and the catalog serve and describe the whole success. A text field's other outcomes are answered as in this table.
 - A group `schemaError` policy replaces the empty 400s on HTTP with a declared error and status: its `invalid` error for input that does not decode, its `internal` error for output that does not encode. It never affects MCP. Details in [ActionGroup.md](ActionGroup.md).
 - `ActionHttp` sets no headers of its own. The host owns cache and challenge headers; `Authentication.middleware` marks its responses `cache-control: no-store`. Hook refusals and handler failures are ordinary declared error responses.
 - Routes are `POST <apiPath>/<group>/<action>`. Operation IDs are `<group>.<action>`. Effect generates OpenAPI component names and references.
 - `ActionHttp.make`'s `errors` are declared on every endpoint so clients decode the surface's own failures (401, 403, 429, 503). They are produced by middleware or by the binding's hook, never by a handler. `ActionMcp` and `ActionToolkit` declare their own `errors` the same way, joined into every tool's failure schema. Two errors may share an HTTP status; their `_tag`s must differ, because the client decodes a status by trying the schemas declared for it.
-- HTTP strips undeclared input fields. MCP tools are strict (`Tool.Strict`): undeclared arguments are an invalid-arguments result and input schemas publish `additionalProperties: false`. HTTP is not strict, and cannot be made strict without a hack: Effect merges one `HttpApi.ParseOptions` per endpoint and uses it for payload decoding _and_ error encoding, so `onExcessProperty: "error"` also rejects a `TaggedError` instance's own `message` and `stack`, turning a declared 409 into an empty 500. Making the payload schema itself strict would require wrapping it in an open schema, which erases its OpenAPI shape. Declare the fields you accept and treat extra HTTP fields as ignored.
+- Input is closed. Both transports publish `additionalProperties: false` for input (so does the catalog) and refuse undeclared fields: over HTTP an extra field is an input failure (an empty 400, or the group's `schemaError` `invalid` answer); an MCP tool (`Tool.Strict`) returns an invalid-arguments result. Typed HTTP clients encode input from `Http.api` and fail with `SchemaError` on an undeclared field, before sending. The native Toolkit, `ActionCli` and `ActionCliClient` decode input locally with default options, which drop an undeclared field instead of refusing it.
 
 ## Namespaces
 
-- Group names are unique within one `ActionHttp.make`. Action names are unique within a group. MCP tool names are unique within a group and within each Toolkit or MCP projection that serves it.
+- Group names are unique within one `ActionHttp.make`. Action names are unique within a group. MCP tool names are unique within each Toolkit or MCP projection that serves them; a group does not check them.
 - Adapters validate only the namespace they serve. HTTP does not check tool names; MCP does not check route names.
-- Each adapter builds only what it serves. A group with no HTTP actions is not built by `Http.layer`; a group with no tools is not built by MCP or Toolkit.
+- Each adapter builds only what it serves. HTTP serves every action of a group it binds, so `Http.layer` builds every implementation it is given (except a group without actions); a group with no tools is not built by MCP or Toolkit.
 
 ## Observability