@gjermundgaraba/effect-actions 0.4.0 → 0.5.0

package/docs/ActionGroup.md

@@ -6,51 +6,21 @@ The pre-handler hook does not: each surface binds its own (see [guarantees.md](g
 
 ## API
 
-```ts
-import * as ActionGroup from "@gjermundgaraba/effect-actions/ActionGroup";
+Import `@gjermundgaraba/effect-actions/ActionGroup`.
 
-function make<Name, Actions, Errors = [], PolicyErrors = []>(
-  options: Options<Name, Errors, PolicyErrors>,
-  ...actions: Actions
-): Group<Name, WithErrors<Actions, Errors>, PolicyErrors>;
-
-interface Options<Name, Errors, PolicyErrors> {
-  readonly name: Name; // HttpApiGroup identifier, OpenAPI tag, operation-ID prefix
-  readonly errors?: Errors; // added to every action's own errors
-  readonly schemaError?: SchemaErrorPolicy<PolicyErrors>; // HTTP only; MCP keeps native answers
-}
-
-interface SchemaErrorPolicy<Errors extends ReadonlyArray<Codec>> {
-  readonly errors: Errors;
-  readonly map: (failure: HttpApiError.HttpApiSchemaError) => Errors[number]["Type"];
-}
-
-interface Group<Name, Actions, PolicyErrors> {
-  readonly name: Name;
-  readonly actions: Actions;
-  readonly schemaError: SchemaErrorPolicy<PolicyErrors> | undefined;
-  /** Bind every handler at once; build-time services resolve once per adapter layer. */
-  readonly implement: <H extends HandlersFrom<Actions>, EX = never, RX = never>(
-    build: H | Effect.Effect<H, EX, RX>,
-  ) => Implementation<Group<Name, Actions, PolicyErrors>, H, EX, Exclude<RX, Scope.Scope>>;
-}
-
-/** Nominal. `group` is the bound contract; `build` acquires the handler record in a scope. */
-class Implementation<G, H, EX, RX> {
-  readonly group: G;
-  get build(): Effect.Effect<H, EX, RX | Scope.Scope>;
-}
-
-/** Every action of the supplied groups, keyed `<group>.<action>`. */
-function contracts<const Groups extends ReadonlyArray<Group>>(
-  ...groups: Groups
-): Contracts<Groups>;
-
-type Contracts<Groups>; // { "users.getUser": typeof GetUser, "users.renameUser": ... }
-```
+| API                               | Purpose                                                                                 |
+| --------------------------------- | --------------------------------------------------------------------------------------- |
+| `make(options, ...actions)`       | Group actions under a required `name`; optional `errors` are inherited by each action.  |
+| `group.implement(recordOrEffect)` | Bind every action handler; an Effect builder carries startup requirements and failures. |
+| `app.group`, `app.build`          | Bound contract and scoped handler acquisition.                                          |
+| `contracts(...groups)`            | Exact action types keyed by `<group>.<action>`.                                         |
+
+Exported types: `Group`, `Any`, `Options`, `Implementation`, `Contracts`, `SchemaErrorPolicy`.
 
-`HandlersFrom<Actions>` is `{ [action name]: Handler<Action, R> }`, one key per action,
-all required.
+The optional `schemaError` group option contains `errors` (policy error codecs) and
+`map(failure)` (a native `HttpApiSchemaError` to one of their decoded values). It affects HTTP only.
+Handler records require every action key. Each handler's input, success and declared errors
+come from its action; request requirements stay distinct from the builder's requirements.
 
 ## Canonical
 
@@ -115,9 +85,9 @@ const renames: "renameUser" = contracts["users.renameUser"].name;
 
 ## Rules
 
-- `name` matches `[A-Za-z0-9_-]+` 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_-]+`, 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`.
 - 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. The record must have exactly one handler per action; a missing key is a compile error. It takes nothing else.
+- `implement` takes a complete record or an Effect producing one. Every action must have a handler; missing keys are compile errors. 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.
 - 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.
@@ -134,7 +104,7 @@ const renames: "renameUser" = contracts["users.renameUser"].name;
 - 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.
 - Groups served by one adapter may have different policies; each action answers with its own group's.
-- A `before` hook refuses before decoding, so a refused request never reaches the policy.
+- 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

package/docs/ActionHttp.md

@@ -5,41 +5,26 @@ of groups into a contract value shared by the server, every client, and the Open
 
 ## API
 
-```ts
-import * as ActionHttp from "@gjermundgaraba/effect-actions/ActionHttp";
+Import `@gjermundgaraba/effect-actions/ActionHttp`.
 
-function make<const G extends ReadonlyArray<Actions>, const E extends ReadonlyArray<Codec> = []>(
-  options: Options<E>,
-  ...groups: G
-): Http<G, E>;
-
-interface Options<Errors = []> {
-  readonly apiPath: `/${string}`; // no default
-  readonly errors?: Errors; // failures the surface answers with, declared on every endpoint
-}
-
-interface LayerOptions<Errors, RB> {
-  /** Runs before the payload is decoded, on every request this layer answers. */
-  readonly before?: (action: Action.Any) => Effect.Effect<void, Errors[number]["Type"], RB>;
-}
-
-interface Http<Groups, Errors = []> {
-  readonly groups: Groups; // the exact contracts bound, in declaration order
-  readonly api: HttpApi.HttpApi<"actions", ...>; // native HttpApi, one HttpApiGroup per group
-  /** Serve implementations. Errors and requirements are unions over exactly these apps. */
-  readonly layer: <const Apps extends ReadonlyArray<AnyImplementation<Groups[number]>>, RB = never>(
-    options: LayerOptions<Errors, RB>,
-    ...apps: Apps
-  ) => Layer.Layer<
-    never,
-    BuildError<Apps[number]>,
-    | BuildContext<Apps[number]>
-    | HttpRouter.HttpRouter
-    | HttpRouter.Request.From<"Requires", RequestContext<Apps[number]> | RB>
-    | Etag.Generator | FileSystem | HttpPlatform.HttpPlatform | Path
-  >;
-}
-```
+| API                          | Purpose                                                                              |
+| ---------------------------- | ------------------------------------------------------------------------------------ |
+| `make(options, ...groups)`   | Bind contracts and a mount path; returns `Http`.                                     |
+| `Http.groups`                | The exact bound contracts, in declaration order.                                     |
+| `Http.api`                   | Native Effect `HttpApi` for clients and OpenAPI.                                     |
+| `Http.layer(apps, options?)` | Serve a readonly collection of implementations; omit options when no hook is needed. |
+
+Exported types: `Options`, `LayerOptions`, `Http`, `Api`.
+
+| Option            | Meaning                                                                                                                                                     |
+| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `make`: `apiPath` | Required absolute mount path; no default.                                                                                                                   |
+| `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.
 
 Route shape: `POST <apiPath>/<group>/<action>`. Operation ID: `<group>.<action>`.
 
@@ -67,8 +52,8 @@ export const Http = ActionHttp.make(
 // One layer per middleware set and per policy. Middleware provided to a layer
 // applies to that layer only, and so does its `before` hook.
 const routes = Layer.mergeAll(
-  Http.layer({}, PublicApp),
-  Http.layer({ before: authorize }, UserApp).pipe(Layer.provide(authentication.layer)),
+  Http.layer([PublicApp]),
+  Http.layer([UserApp], { before: authorize }).pipe(Layer.provide(authentication.layer)),
 );
 
 // Documents are Effect's own, reading the same contract.
@@ -106,10 +91,10 @@ export const greeting = Effect.gen(function* () {
 - `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(options, ...apps)` mounts only the supplied implementations. A group that is never passed to `layer` has no routes. A group with no HTTP-enabled actions is not built at all. The options object is required; pass `{}` for a surface with no hook.
-- `before` runs once per request, with the selected action contract, **before the payload is decoded**, so an unauthorized caller learns nothing about the input schema and the handler never runs. It fails with the binding's own `errors`, and that failure is encoded exactly like a declared error, with the schema's `httpApiStatus`. Its services are request-time requirements, joined with the handlers'.
+- `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.
+- `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`.
-- Every response with a status of 400 or more carries `cache-control: no-store`, including hook refusals, declared errors and defects. Successful responses are left alone; only the host knows whether they are public.
+- `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`.
@@ -117,14 +102,15 @@ export const greeting = Effect.gen(function* () {
 - 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.
 - 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. The hook, decoding and encoding are outside it, in the request span.
+- 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.
 - 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`. Add the group to `make` or drop the app.
+- `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.

package/docs/ActionMcp.md

@@ -6,51 +6,28 @@ JSON-RPC on standard I/O for a subprocess.
 
 ## API
 
-```ts
-import * as ActionMcp from "@gjermundgaraba/effect-actions/ActionMcp";
-
-function layerHttp<const Apps extends ReadonlyArray<AnyImplementation>, Errors = [], RB = never>(
-  options: Options<Errors, RB>,
-  ...apps: Apps
-): Layer.Layer<
-  never,
-  BuildError<Apps[number]> | Cause.IllegalArgumentError,
-  | BuildContext<Apps[number]>
-  | HttpRouter.HttpRouter
-  | HttpRouter.Request.From<"Requires", RequestContext<Apps[number]> | RB>
->;
-
-function layerStdio<const Apps extends ReadonlyArray<AnyImplementation>, Errors = [], RB = never>(
-  options: StdioOptions<Errors, RB>,
-  ...apps: Apps
-): Layer.Layer<
-  never,
-  BuildError<Apps[number]> | Cause.IllegalArgumentError,
-  BuildContext<Apps[number]> | Stdio | RequestContext<Apps[number]> | RB
->;
-
-/** Both transports share these. */
-interface SurfaceOptions<Errors, RB> {
-  readonly errors?: Errors; // declared on every tool of this transport
-  readonly before?: (action: Action.Any) => Effect.Effect<void, Errors[number]["Type"], RB>;
-}
-
-interface Options<Errors = [], RB = never> extends SurfaceOptions<Errors, RB> {
-  readonly name: string; // server info
-  readonly version: string;
-  readonly protocols: ReadonlyArray<McpProtocol>; // required, e.g. [McpProtocol.v2026_07_28]
-  readonly path: HttpRouter.PathInput; // no default
-  readonly allowedOrigins?: ReadonlyArray<string>; // passed to McpServer.layerHttp
-  readonly instructions?: string;
-}
-
-interface StdioOptions<Errors = [], RB = never> extends SurfaceOptions<Errors, RB> {
-  readonly name: string;
-  readonly version: string;
-  readonly protocols: ReadonlyArray<McpProtocol>;
-  readonly instructions?: string;
-}
-```
+Import `@gjermundgaraba/effect-actions/ActionMcp`.
+
+| API                         | Purpose                                                                       |
+| --------------------------- | ----------------------------------------------------------------------------- |
+| `layerHttp(apps, options)`  | Serve a readonly collection of implementations at a Streamable HTTP endpoint. |
+| `layerStdio(apps, options)` | Serve implementations over a subprocess's standard I/O.                       |
+| `Options`, `StdioOptions`   | Configuration for the two transports.                                         |
+
+| Option            | Meaning                                                                                               |
+| ----------------- | ----------------------------------------------------------------------------------------------------- |
+| `name`, `version` | Required native server information.                                                                   |
+| `protocols`       | Required nonempty list of native protocol adapters.                                                   |
+| `path`            | Required HTTP endpoint path; HTTP only, no default.                                                   |
+| `allowedOrigins`  | Optional exact Origin allowlist; HTTP only, not CORS configuration.                                   |
+| `instructions`    | Optional native server instructions.                                                                  |
+| `errors`          | Optional surface error codecs, declared on every served tool.                                         |
+| `before`          | Optional Effectful hook receiving the selected `Action.Any`; fails only with declared surface errors. |
+
+Both layers retain served implementations' build failures and requirements, plus native
+`IllegalArgumentError`. HTTP needs the router and wraps handler/hook services as request
+requirements. stdio needs `Stdio` and the caller's request services. Native `McpRequestContext`
+is supplied by the server, not owed by the host.
 
 ## Canonical
 
@@ -65,50 +42,100 @@ const allowedOrigins = ["http://localhost:3000"];
 
 // One endpoint is one route: its middleware covers every tool on it.
 // Tools with different middleware needs get their own endpoint.
-const publicMcp = ActionMcp.layerHttp(
-  {
-    protocols: [McpProtocol.v2026_07_28],
-    name: "app-public",
-    version: "1.0.0",
-    path: "/mcp/public",
-    allowedOrigins,
-  },
-  PublicApp,
-);
-
-const mcp = ActionMcp.layerHttp(
-  {
-    protocols: [McpProtocol.v2026_07_28],
-    name: "app",
-    version: "1.0.0",
-    path: "/mcp",
-    allowedOrigins,
-    // The same rule the HTTP binding runs, declared here so a refusal is an
-    // ordinary tool failure rather than a transport error.
-    errors: [Forbidden],
-    before: authorize,
-  },
-  UserApp,
-  AuditApp,
-).pipe(Layer.provide(authentication.layer));
+const publicMcp = ActionMcp.layerHttp([PublicApp], {
+  protocols: [McpProtocol.v2026_07_28],
+  name: "app-public",
+  version: "1.0.0",
+  path: "/mcp/public",
+  allowedOrigins,
+});
+
+const mcp = ActionMcp.layerHttp([UserApp, AuditApp], {
+  protocols: [McpProtocol.v2026_07_28],
+  name: "app",
+  version: "1.0.0",
+  path: "/mcp",
+  allowedOrigins,
+  // The same rule the HTTP binding runs, declared here so a refusal is an
+  // ordinary tool failure rather than a transport error.
+  errors: [Forbidden],
+  before: authorize,
+}).pipe(Layer.provide(authentication.layer));
 
 export const layer = Layer.mergeAll(publicMcp, mcp);
 ```
 
-Subprocess:
+### Cross-origin browsers
+
+`allowedOrigins` alone does not configure CORS. For a stateless browser endpoint, mount
+native router CORS outside the route middleware. This CORS layer is global to the router;
+choose its policy for every route it covers.
+
+```ts
+import { Effect, Layer } from "effect";
+import { McpProtocol } from "effect/unstable/ai";
+import { HttpRouter } from "effect/unstable/http";
+import * as ActionMcp from "@gjermundgaraba/effect-actions/ActionMcp";
+import { Actions } from "./quickstart.js";
+
+const allowedOrigins = ["https://ui.example.com"];
+
+const app = Actions.implement({ greet: ({ name }) => Effect.succeed(`Hello, ${name}!`) });
+
+const mcp = ActionMcp.layerHttp([app], {
+  name: "greetings",
+  version: "1.0.0",
+  path: "/mcp",
+  protocols: [McpProtocol.v2026_07_28],
+  allowedOrigins,
+});
+
+// Global router CORS handles preflight outside route-level authentication.
+// This example is public; protected endpoints still need authentication and a hook.
+export const routes = Layer.mergeAll(
+  mcp,
+  HttpRouter.cors({
+    allowedOrigins,
+    allowedMethods: ["POST"],
+    allowedHeaders: [
+      "Content-Type",
+      "Authorization",
+      "MCP-Protocol-Version",
+      "MCP-Method",
+      "MCP-Name",
+    ],
+    exposedHeaders: ["WWW-Authenticate", "MCP-Protocol-Version"],
+  }),
+);
+```
+
+### Subprocess
 
 ```ts
 import { NodeRuntime, NodeStdio } from "@effect/platform-node";
-import { Console, Effect, Layer, Logger } from "effect";
+import { Console, Effect, Layer, Logger, Schema } from "effect";
 import { McpProtocol } from "effect/unstable/ai";
+import * as Action from "@gjermundgaraba/effect-actions/Action";
+import * as ActionGroup from "@gjermundgaraba/effect-actions/ActionGroup";
 import * as ActionMcp from "@gjermundgaraba/effect-actions/ActionMcp";
 
-const layer = ActionMcp.layerStdio(
-  { name: "app-stdio", version: "1.0.0", protocols: [McpProtocol.v2026_07_28] },
-  app,
-).pipe(Layer.provide(NodeStdio.layer));
+const Status = Action.make("status", {
+  description: "Report whether the subprocess is ready.",
+  success: Schema.Struct({ ready: Schema.Boolean }),
+  access: "read",
+});
+
+const app = ActionGroup.make({ name: "stdio" }, Status).implement({
+  status: () => Effect.log("status called").pipe(Effect.as({ ready: true })),
+});
+
+const layer = ActionMcp.layerStdio([app], {
+  name: "effect-actions-stdio",
+  version: "0.1.0",
+  protocols: [McpProtocol.v2026_07_28],
+}).pipe(Layer.provide(NodeStdio.layer));
 
-// stdout is protocol-only; logs go to stderr.
+// Protocol messages use stdout exclusively. Runtime diagnostics remain on stderr.
 Layer.launch(layer).pipe(
   Effect.tapCause((cause) => Console.error(cause)),
   Effect.provideService(Logger.LogToStderr, true),
@@ -118,11 +145,13 @@ Layer.launch(layer).pipe(
 
 ## Rules
 
-- `protocols` is required and takes Effect's native `McpProtocol` adapters. Effect owns negotiation, revision rejection, and sessions. `[McpProtocol.v2026_07_28]` gives a stateless endpoint that needs no initialize handshake.
+- `protocols` is required and must be a nonempty list of Effect's native `McpProtocol.ProtocolAdapter` values. Effect owns negotiation, revision rejection, and sessions. `[McpProtocol.v2026_07_28]` gives a stateless endpoint that needs no initialize handshake.
 - `path` has no default. `layerHttp` uses the single-endpoint Streamable HTTP transport, never the two-endpoint HTTP+SSE form, whatever revision is negotiated.
+- 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.
-- Every MCP-enabled action must have object-root input. Checked synchronously when `layerHttp` or `layerStdio` is called, before any handler is acquired; a violation throws. The `IllegalArgumentError` in the layer's error channel comes from the native transport, not from this check.
+- 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`.
 - 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.
@@ -132,14 +161,18 @@ Layer.launch(layer).pipe(
 - stdio: the host supplies `Stdio` (`NodeStdio.layer`) and any request-time services explicitly, including the trusted principal. There is no authentication middleware. Tool arguments never establish identity. Keep stdout for protocol messages only and route logs to stderr.
 - Each endpoint or subprocess owns a fresh native tool registry. That isolates tool names, not application context.
 - `errors` are the failures this transport answers with rather than a handler. They join every tool's declared failures, so a refusal is returned exactly like an action's own error and no caller sees a protocol-level error instead. A schema an action already declares is not repeated.
-- `before` runs once per tool call, with the selected action contract, before the handler. The native server decodes the tool arguments first, so unlike HTTP the hook runs after input decoding; it still runs on every call and the handler never runs when it fails. Its services are request-time requirements, joined with the handlers'.
+- `before` runs after successful native argument decoding and before the selected handler, with its action contract. Invalid arguments skip the hook and handler. A hook failure prevents the handler from running; its services join handler request requirements.
 
 ## Failure modes
 
-- `<action>: MCP input must have an object root; omit input for no arguments` thrown at the `layerHttp` or `layerStdio` call: the action has scalar or array input. Wrap it in a struct or set `mcp: false`.
+- 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.
 - 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`.
 - Older MCP client cannot connect: the client expects a revision not listed in `protocols`. Add the adapter for that revision.
+- An Origin-bearing request reaches the native handler and gets an empty 403: its `Origin` is not in `allowedOrigins`. Add the exact origin only if the deployment trusts it.
+- 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.
+- Type error on an empty `protocols` array: provide at least one native protocol adapter.
 - 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

@@ -5,71 +5,53 @@ with `LanguageModel` or by hand. No server, no MCP envelope.
 
 ## API
 
-```ts
-import * as ActionToolkit from "@gjermundgaraba/effect-actions/ActionToolkit";
+Import `@gjermundgaraba/effect-actions/ActionToolkit`.
 
-function make<const Apps extends ReadonlyArray<AnyImplementation>, Errors = [], RB = never>(
-  options: Options<Errors, RB>,
-  ...apps: Apps
-): Binding<
-  ToolkitTools<Apps, Errors[number], RB>,
-  BuildError<Apps[number]>,
-  BuildContext<Apps[number]>
->;
-
-interface Options<Errors = [], RB = never> {
-  readonly errors?: Errors; // declared on every tool of this binding
-  readonly before?: (action: Action.Any) => Effect.Effect<void, Errors[number]["Type"], RB>;
-}
-
-interface Binding<Tools, E, R> {
-  readonly toolkit: Toolkit.Toolkit<Tools>; // native; tool names, schemas and requirements stay typed
-  /** Acquires handlers once in the layer scope; handler requirements remain at invocation. */
-  readonly layer: Layer.Layer<Tool.HandlersFor<Tools>, E, R>;
-}
-
-// Each MCP-enabled action becomes:
-Tool.Tool<
-  McpName,
-  {
-    parameters: A["input"];
-    success: A["success"];
-    failure: Schema.Union<ReadonlyArray<A["errors"][number] | Errors[number]>>;
-    failureMode: "return";
-  },
-  HandlerRequirements | RB
->;
-```
+| API                    | Purpose                                                                                       |
+| ---------------------- | --------------------------------------------------------------------------------------------- |
+| `make(apps, options?)` | Project a readonly collection of implementations; omit options for an unguarded binding.      |
+| `binding.toolkit`      | Native `Toolkit` with typed tool names, schemas and per-tool request requirements.            |
+| `binding.layer`        | Acquire handlers in the layer's scope; requires their startup services, not request identity. |
+| `Options`, `Binding`   | Public configuration and binding types.                                                       |
+
+Options: `errors` declares surface error codecs on every tool; `before` is an Effectful hook
+receiving the selected `Action.Any`, failing only with those errors. Both are optional.
+
+Each tool keeps the action's native input/success codecs, combines action and surface failures
+in a native union, and uses `failureMode: "return"`. Its request requirements are its handler's
+plus the hook's; build failures and services belong to the binding layer.
 
 ## Canonical
 
 ```ts
-import { Effect, Stream } from "effect";
+import { NodeRuntime } from "@effect/platform-node";
+import { Console, Effect, Layer, Stream } from "effect";
 import * as ActionToolkit from "@gjermundgaraba/effect-actions/ActionToolkit";
-import { authorize, Forbidden } from "./auth.js";
+import { actors, authorize, CurrentActor, Forbidden } from "./auth.js";
 import { UserApp } from "./handlers.js";
+import { Users } from "./users.js";
 
-// The in-process caller is not trusted more than a remote one: it binds the same
-// rule, and a refusal is a declared tool failure.
-const binding = ActionToolkit.make({ errors: [Forbidden], before: authorize }, UserApp);
+// The in-process caller binds the same rule as the guarded servers.
+const binding = ActionToolkit.make([UserApp], { errors: [Forbidden], before: authorize });
 
 const program = Effect.gen(function* () {
-  const tools = yield* binding.toolkit; // bound handlers
+  const tools = yield* binding.toolkit;
   const calls = yield* tools.handle("get_user", { id: "1" }); // encoded arguments
   const results = yield* Stream.runCollect(calls);
-
-  return results;
+  yield* Console.log(results);
 }).pipe(
-  Effect.provideService(CurrentActor, actor), // request service, around the whole call
-  Effect.provide(binding.layer), // build services resolved here
+  Effect.provideService(CurrentActor, actors.alice), // identity around the whole invocation
+  Effect.provide(binding.layer.pipe(Layer.provide(Users.layerMemory))), // startup services only
 );
+
+program.pipe(NodeRuntime.runMain);
 ```
 
 With a model: pass `binding.toolkit` as `toolkit` to `LanguageModel.generateText` and provide `binding.layer`.
 
 ## Rules
 
-- Selects MCP-enabled actions only, named by `mcp.name`, with the resolved hints. Groups with no selected tools are not built. The options object is required; pass `{}` for a binding with no hook.
+- 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.
 - `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.
@@ -77,7 +59,7 @@ With a model: pass `binding.toolkit` as `toolkit` to `LanguageModel.generateText
 - Supply identity at invocation, never when building the layer. Native context capture is not a security boundary.
 - This is not an MCP server. Use `ActionMcp` to expose the same actions to external clients.
 - `errors` are the failures the caller answers with rather than a handler. They join every tool's declared failures, so a refusal is an ordinary returned tool failure. A schema an action already declares is not repeated.
-- `before` runs once per call, with the selected action contract, after the arguments are decoded and before the handler. Its services join each tool's requirements, and the caller supplies them as it does a handler's.
+- `before` runs after successful argument decoding and before the selected handler, with its action contract. Invalid arguments skip both. Its services join each tool's requirements, supplied by the caller.
 
 ## Failure modes