@gjermundgaraba/effect-actions 0.2.0 → 0.4.0

package/docs/ActionHttp.md

@@ -8,24 +8,34 @@ of groups into a contract value shared by the server, every client, and the Open
 ```ts
 import * as ActionHttp from "@gjermundgaraba/effect-actions/ActionHttp";
 
-function make<const G extends ReadonlyArray<Actions>>(options: Options, ...groups: G): Http<G>;
+function make<const G extends ReadonlyArray<Actions>, const E extends ReadonlyArray<Codec> = []>(
+  options: Options<E>,
+  ...groups: G
+): Http<G, E>;
 
-interface Options {
+interface Options<Errors = []> {
   readonly apiPath: `/${string}`; // no default
+  readonly errors?: Errors; // failures the surface answers with, declared on every endpoint
 }
 
-interface Http<Groups> {
+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]>>>(
+  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]>>
+    | HttpRouter.Request.From<"Requires", RequestContext<Apps[number]> | RB>
     | Etag.Generator | FileSystem | HttpPlatform.HttpPlatform | Path
   >;
 }
@@ -42,15 +52,23 @@ import { HttpApiScalar, HttpApiSwagger, OpenApi } from "effect/unstable/httpapi"
 import * as ActionHttp from "@gjermundgaraba/effect-actions/ActionHttp";
 import { PublicActions, UserActions } from "./contracts.js";
 import { PublicApp, UserApp } from "./handlers.js";
-import { authentication } from "./auth.js";
-
-// Contract: shared by server and clients.
-export const Http = ActionHttp.make({ apiPath: "/api/actions" }, PublicActions, UserActions);
+import { authentication, authorize, Forbidden, Unauthenticated } from "./auth.js";
+
+// Contract: shared by server and clients. `errors` are the failures the surface
+// itself renders — here the 401 from `authentication` and the 403 from the hook
+// below — so a typed client decodes them instead of reporting a decode error on
+// an unexpected status.
+export const Http = ActionHttp.make(
+  { apiPath: "/api/actions", errors: [Unauthenticated, Forbidden] },
+  PublicActions,
+  UserActions,
+);
 
-// One layer per middleware set. Middleware provided to a layer applies to that layer only.
+// 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(UserApp).pipe(Layer.provide(authentication.layer)),
+  Http.layer({}, PublicApp),
+  Http.layer({ before: authorize }, UserApp).pipe(Layer.provide(authentication.layer)),
 );
 
 // Documents are Effect's own, reading the same contract.
@@ -85,15 +103,21 @@ export const greeting = Effect.gen(function* () {
 ## Rules
 
 - `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.
-- `Http.layer(...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.
-- Middleware is per layer call. Groups that need different middleware go in separate `Http.layer` calls, merged with `Layer.mergeAll`.
+- `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'.
+- 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.
+- 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`.
 - 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, `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, 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. Decoding and encoding are outside it.
+- 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.
 
 ## Failure modes
 
@@ -104,3 +128,7 @@ export const greeting = Effect.gen(function* () {
 - 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.
+- `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`.
+- A refusal returns 500 instead of its status: the hook failed with an error the binding does not declare. Add its schema to `ActionHttp.make`'s `errors`.

package/docs/ActionMcp.md

@@ -9,27 +9,33 @@ JSON-RPC on standard I/O for a subprocess.
 ```ts
 import * as ActionMcp from "@gjermundgaraba/effect-actions/ActionMcp";
 
-function layerHttp<const Apps extends ReadonlyArray<AnyImplementation>>(
-  options: Options,
+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]>>
+  | HttpRouter.Request.From<"Requires", RequestContext<Apps[number]> | RB>
 >;
 
-function layerStdio<const Apps extends ReadonlyArray<AnyImplementation>>(
-  options: StdioOptions,
+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]>
+  BuildContext<Apps[number]> | Stdio | RequestContext<Apps[number]> | RB
 >;
 
-interface Options {
+/** 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]
@@ -38,7 +44,7 @@ interface Options {
   readonly instructions?: string;
 }
 
-interface StdioOptions {
+interface StdioOptions<Errors = [], RB = never> extends SurfaceOptions<Errors, RB> {
   readonly name: string;
   readonly version: string;
   readonly protocols: ReadonlyArray<McpProtocol>;
@@ -53,7 +59,7 @@ import { Layer } from "effect";
 import { McpProtocol } from "effect/unstable/ai";
 import * as ActionMcp from "@gjermundgaraba/effect-actions/ActionMcp";
 import { AuditApp, PublicApp, UserApp } from "./handlers.js";
-import { authentication } from "./auth.js";
+import { authentication, authorize, Forbidden } from "./auth.js";
 
 const allowedOrigins = ["http://localhost:3000"];
 
@@ -77,6 +83,10 @@ const mcp = ActionMcp.layerHttp(
     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,
@@ -116,11 +126,13 @@ Layer.launch(layer).pipe(
 - 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.
-- Tool discovery is not filtered by actor. Every caller sees every tool of the endpoint. Authorization happens in the handler.
+- Tool discovery is not filtered by actor. Every caller sees every tool of the endpoint. Authorization happens in `before`.
 - Cancellation is Effect's native RPC interruption.
 - Handlers may yield `McpSchema.McpRequestContext` for the client's declared information; the native server supplies it to every tool call, so it is never a router or host requirement.
 - 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'.
 
 ## Failure modes
 
@@ -130,3 +142,4 @@ Layer.launch(layer).pipe(
 - 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.
+- 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

@@ -8,9 +8,19 @@ with `LanguageModel` or by hand. No server, no MCP envelope.
 ```ts
 import * as ActionToolkit from "@gjermundgaraba/effect-actions/ActionToolkit";
 
-function make<const Apps extends ReadonlyArray<AnyImplementation>>(
+function make<const Apps extends ReadonlyArray<AnyImplementation>, Errors = [], RB = never>(
+  options: Options<Errors, RB>,
   ...apps: Apps
-): Binding<ToolkitTools<Apps>, BuildError<Apps[number]>, BuildContext<Apps[number]>>;
+): 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
@@ -24,10 +34,10 @@ Tool.Tool<
   {
     parameters: A["input"];
     success: A["success"];
-    failure: Schema.Union<A["errors"]>;
+    failure: Schema.Union<ReadonlyArray<A["errors"][number] | Errors[number]>>;
     failureMode: "return";
   },
-  HandlerRequirements
+  HandlerRequirements | RB
 >;
 ```
 
@@ -36,9 +46,12 @@ Tool.Tool<
 ```ts
 import { Effect, Stream } from "effect";
 import * as ActionToolkit from "@gjermundgaraba/effect-actions/ActionToolkit";
+import { authorize, Forbidden } from "./auth.js";
 import { UserApp } from "./handlers.js";
 
-const binding = ActionToolkit.make(UserApp);
+// 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);
 
 const program = Effect.gen(function* () {
   const tools = yield* binding.toolkit; // bound handlers
@@ -56,17 +69,20 @@ With a model: pass `binding.toolkit` as `toolkit` to `LanguageModel.generateText
 
 ## Rules
 
-- Selects MCP-enabled actions only, named by `mcp.name`, with the resolved hints. Groups with no selected tools are not built.
+- 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.
 - 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.
-- Each tool carries only its own handler's request requirements, not those of sibling or disabled tools.
+- Each tool carries only its own handler's request requirements, plus the hook's, not those of sibling or disabled tools.
 - 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.
 
 ## Failure modes
 
 - 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.
 - Type error on `binding.layer` requirements: a build-time service is missing. Provide its Layer before `binding.layer`.

package/docs/Authentication.md

@@ -2,7 +2,8 @@
 
 Two helpers for hosts that own identity: router middleware that provides a request-scoped
 identity service, and RFC 9728 protected-resource discovery with bearer challenges. Token
-verification, login, and consent stay in the application.
+verification, login, and consent stay in the application. Authorization is a group's
+pre-handler hook ([ActionGroup.md](ActionGroup.md)), not part of this module.
 
 ## API
 
@@ -103,7 +104,8 @@ export const routes = Layer.mergeAll(
 - `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.
 - `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 is a handler concern (`yield* CurrentActor`, then check).
+- 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)).
 
 ## Failure modes
 
@@ -112,3 +114,4 @@ export const routes = Layer.mergeAll(
 - 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,19 +5,23 @@ use these words with these meanings.
 
 ## Terms
 
-- **Action**: one contract. A name, a description, an input schema, a success schema, declared error schemas, 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 transport metadata (`http`, `mcp`). Holds no behavior. Made by `Action.make`.
+- **Access**: `"read"` or `"write"`, required on every action and kept as a literal. States what the action does to its resource. Authorization metadata read by a pre-handler hook, independent of the MCP `readOnly` hint, which defaults from it.
 - **Group**: a named, ordered set of actions plus group-level errors and an optional schema-error policy. Adapters serve groups, clients are organized by group, and the group name is the OpenAPI tag. Made by `ActionGroup.make`.
 - **Contract**: an action or a group. Pure data; safe to import anywhere, including browsers.
 - **Handler**: a function from decoded input to an Effect of decoded success, failing only with the action's declared errors, possibly requiring services.
 - **Implementation**: a nominal binding of a complete handler record to a group, made by `group.implement`. Carries build-time error and requirement channels. Adapters accept implementations; `ActionCatalog` accepts contracts.
 - **Builder**: the record or Effect passed to `implement`. Runs once per adapter layer that serves the implementation.
+- **Pre-handler hook**: the `before` function an adapter binds. Runs once per invocation of that surface, with the selected action contract, before its handler. Fails with the surface's own errors. Its services are request-time requirements.
 - **Build-time requirement**: a service yielded in the builder. Resolved when an adapter layer is built.
 - **Request-time requirement**: a service yielded inside a handler. Supplied per invocation: by router middleware for HTTP-hosted adapters, by the host for Toolkit, CLI, and stdio.
 - **Adapter** (also **projection**): a module that maps implementations or contracts onto one surface: `ActionHttp`, `ActionMcp`, `ActionToolkit`, `ActionCli`, `ActionCliClient`, `ActionCatalog`. Each adapter reads only what it serves and validates only its own namespace.
 - **Binding**: the value an adapter returns before anything runs. `ActionHttp.make` returns the HTTP binding (`groups`, `api`, `layer`); `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. Encoded on every transport with its `httpApiStatus`.
 - **Schema-error policy**: a group option mapping Effect's `HttpApiSchemaError` (decode or encode failure) to a declared policy error with a status. 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.
 - **Endpoint**: one `ActionMcp.layerHttp` mount. One route, one middleware set, one tool registry.
@@ -31,6 +35,6 @@ use these words with these meanings.
 - `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.
-- Authentication is router middleware plus discovery metadata. Verification, login, and consent stay in the application.
+- 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

@@ -17,9 +17,9 @@ Package facts that apply everywhere:
 | Read                                     | When you need to                                                                       |
 | ---------------------------------------- | -------------------------------------------------------------------------------------- |
 | [setup.md](setup.md)                     | install, pin versions, pick entry points, know what the package does not do            |
-| [Action.md](Action.md)                   | define one contract: input, success, errors, HTTP and MCP flags, tool hints            |
-| [ActionGroup.md](ActionGroup.md)         | group contracts, declare shared errors, set a schema-error policy, bind handlers       |
-| [ActionHttp.md](ActionHttp.md)           | serve JSON POST routes, publish OpenAPI, call the API with `HttpApiClient`             |
+| [Action.md](Action.md)                   | define one contract: input, success, errors, read/write access, HTTP and MCP flags     |
+| [ActionGroup.md](ActionGroup.md)         | group contracts, declare shared errors, bind handlers, map every contract by name      |
+| [ActionHttp.md](ActionHttp.md)           | serve JSON POST routes, declare surface errors and one hook, publish OpenAPI, call it  |
 | [ActionMcp.md](ActionMcp.md)             | serve MCP tools over Streamable HTTP or stdio                                          |
 | [ActionToolkit.md](ActionToolkit.md)     | use actions as a native Effect AI `Toolkit` without a server                           |
 | [ActionCli.md](ActionCli.md)             | run handlers in-process from a terminal command                                        |
@@ -54,7 +54,7 @@ const Greet = Action.make("greet", {
   description: "Greet someone by name.",
   input: Schema.Struct({ name: Schema.String }),
   success: Schema.String,
-  mcp: { readOnly: true },
+  access: "read",
 });
 
 export const Actions = ActionGroup.make({ name: "greetings" }, Greet);
@@ -66,7 +66,7 @@ const app = Actions.implement({
 });
 
 export const routes = Layer.mergeAll(
-  Http.layer(app),
+  Http.layer({}, app),
   ActionMcp.layerHttp(
     { protocols: [McpProtocol.v2026_07_28], name: "greetings", version: "1.0.0", path: "/mcp" },
     app,

package/docs/Testing.md

@@ -88,4 +88,4 @@ const result = await TestingClient.withMcpClient(
 - `@modelcontextprotocol/client` not found: only `TestingClient` needs it. Install the peer in devDependencies, or use `Testing.mcpRequest` instead.
 - Official client fails negotiation against a stateless endpoint: set `versionNegotiation: { mode: { pin: "2026-07-28" } }`.
 - Handler leaks between tests: `web.dispose()` was not called. Register it with the test runner's cleanup hook.
-- 404 from `httpClient`: `routes` did not include `Http.layer(app)`, or `HttpServer.layerServices` was not provided to `toWebHandler`.
+- 404 from `httpClient`: `routes` did not include `Http.layer({}, app)`, or `HttpServer.layerServices` was not provided to `toWebHandler`.

package/docs/guarantees.md

@@ -5,10 +5,16 @@ Rules that hold across every adapter. Module pages link here rather than repeati
 ## Dependency lifetimes
 
 - Handlers receive decoded input, return decoded results, and may fail only with declared errors. Anything else is a defect.
+- Each surface binds its own pre-handler hook: `Http.layer({ before }, ...)`, `ActionMcp.layerHttp`/`layerStdio`, `ActionToolkit.make`, `ActionCli.command`/`group`. A bound hook runs once per invocation, before the selected handler and outside its span, for every action that surface serves. There is no per-action opt-out and no group that escapes it; only calling `build` directly does, and that is not dispatch.
+- The hook receives the selected action contract (`Action.Any`), so a policy reads `action.access`, `action.name` or `action.mcp` instead of a hand-maintained list. It is not authentication: establish identity in middleware, then let the hook authorize what that identity may do.
+- It fails with the surface's own `errors`, the same list that declares what the surface answers instead of a handler, so a refusal is encoded exactly like a declared error: the schema's `httpApiStatus` on HTTP, an `isError` tool result on MCP, a returned failure on the Toolkit. `ActionCli` declares no errors because it encodes nothing; there a refusal is a typed failure of the command effect.
+- Its services are request-time requirements, like a handler's, and they join the adapter's request context. A local caller (`ActionCli`, `ActionToolkit`, stdio) supplies them itself.
+- Ordering differs by surface, because each hooks into its own transport: HTTP runs the hook **before** the request payload is decoded, so an unauthorized caller learns nothing about the input schema. MCP, the Toolkit and the CLI run it after the native transport has decoded the arguments, since decoding is the transport's own first step there.
 - Build-time services are those yielded in the `implement` builder Effect. They resolve once per adapter layer, in that layer's scope. An implementation served by two adapters is built twice. Share state through a Layer provided to the adapters, never through the builder.
 - Request-time services are those yielded inside a handler. For HTTP-hosted adapters (`ActionHttp`, `ActionMcp.layerHttp`) they appear as `HttpRouter.Request.From<"Requires", R>` and are supplied by router middleware, `HttpRouter.provideRequest`, or request context. For `ActionToolkit`, `ActionCli`, and `ActionMcp.layerStdio` the host supplies them at invocation.
 - Use distinct tags for build-time capabilities and request-scoped identity. Never provide an identity or tenant tag in a startup layer or root context. The adapters use native Effect context capture and merging: a startup value under a tag can shadow a request value or satisfy a missing one. Types verify presence, not provenance.
-- Authentication must establish identity on every protected request. Types cannot verify that a handler performed authorization.
+- Authentication must establish identity on every protected request. Types cannot verify that a handler performed authorization; the `before` hook is the one place the library guarantees runs first, so put the check there rather than in each handler.
+- `access` is contract metadata, required on every action and kept as a literal type. Nothing in the library reads it: adapters ignore it and the catalog omits it. It exists so a hook can switch on what an action does instead of on its name.
 - `ActionCli` acquires the implementation per invocation and releases it after the call. `ActionToolkit.layer` acquires it once for the layer's lifetime.
 
 ## Wire behavior
@@ -20,14 +26,17 @@ Defaults without a schema-error policy. HTTP is a native `HttpApi`; MCP is a nat
 | 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> }`                                                              |
 | 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, before the payload is decoded; 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 |
 | Defect                      | empty **500**                                                                                         | same generic `isError` result; cause logged, not sent                                                  |
 | Unknown path or method      | 404                                                                                                   | n/a                                                                                                    |
 | Invalid JSON / content type | 400 / 415                                                                                             | n/a                                                                                                    |
 
 - A group `schemaError` policy replaces the empty 400s on HTTP with a declared error and status. It never affects MCP. Details in [ActionGroup.md](ActionGroup.md).
+- Every HTTP response with a status of 400 or more carries `cache-control: no-store`. Successful responses are left to the host. An error response has no other added headers: a hook refusal and a handler error are plain declared errors, and challenge headers such as `WWW-Authenticate` belong to the admission middleware that answers before the router reaches these routes.
 - Routes are `POST <apiPath>/<group>/<action>`. Operation IDs are `<group>.<action>`. Effect generates OpenAPI component names and references.
-- 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 cannot be strict natively: `HttpApi.ParseOptions` also governs error encoding, where `onExcessProperty: "error"` rejects an error's own `stack`.
+- `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.
 
 ## Namespaces
 
@@ -37,7 +46,7 @@ Defaults without a schema-error policy. HTTP is a native `HttpApi`; MCP is a nat
 
 ## Observability
 
-- Each handler runs in a span named `<group>.<action>`, a child of the transport's request span. Decoding and encoding happen outside the handler span.
+- Each handler runs in a span named `<group>.<action>`, a child of the transport's request span. The pre-handler hook, decoding and encoding happen outside the handler span.
 - MCP defects and encoding failures are logged with their cause and answered generically.
 
 ## MCP transport
@@ -51,5 +60,5 @@ Defaults without a schema-error policy. HTTP is a native `HttpApi`; MCP is a nat
 
 - HTTP is JSON `POST` on `HttpApi`, not Effect RPC. MCP is native `McpServer`, no SDK runtime dependency.
 - Actions are unary: no streaming, uploads, prompts, resources, retries, or code-execution sandbox.
-- Authentication and authorization are the application's. Tool discovery is not filtered by actor. Production needs real token validation, MCP authorization discovery, request limits, and error reporting; the package supplies shapes for the first two only.
+- Authentication and authorization are the application's. The library supplies the seams: `Authentication.middleware` for identity, one `before` hook per surface for the authorization rule, `access` for what a rule reads, and each surface's `errors` for what a caller can decode. It defines no error types, no scopes and no verifier. Tool discovery is not filtered by actor. Production needs real token validation, MCP authorization discovery, request limits, and error reporting.
 - The catalog is descriptive. Presence in it grants nothing.

package/docs/setup.md

@@ -54,7 +54,7 @@ What the package does, and nothing else:
 - HTTP means JSON `POST` endpoints built on Effect's `HttpApi`. It is not Effect RPC.
 - MCP means one native `McpServer` `Tool` per action. There is no MCP SDK runtime dependency.
 - Actions are unary: one decoded input, one decoded success or one declared error. No streaming, uploads, prompts, resources, retries, or code-execution sandbox.
-- Authentication and authorization are the application's. The library provides a middleware shape and discovery metadata, not a token verifier. Tool discovery is never filtered by actor.
+- Authentication and authorization are the application's. The library provides the seams — `Authentication.middleware` for identity, one `before` hook per surface for the authorization rule, `access` for what that rule reads, each surface's `errors` for what a caller can decode — and no token verifier, error types or scopes of its own. Tool discovery is never filtered by actor.
 
 ## Failure modes
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gjermundgaraba/effect-actions",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Define Effect action contracts once and project them onto HTTP, MCP, native Toolkits, catalogs, and CLIs.",
   "homepage": "https://github.com/gjermundgaraba/effect-actions#readme",
   "bugs": {