@gjermundgaraba/effect-actions 0.3.0 → 0.4.0

package/README.md

@@ -30,7 +30,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,
@@ -42,7 +42,7 @@ Serve `routes` with Effect's `HttpRouter` and you have `POST /api/actions/greeti
 and an MCP tool named `greet` at `/mcp`. The same `app` is also:
 
 ```ts
-const { toolkit, layer } = ActionToolkit.make(app); // native Effect AI Toolkit and its handler layer
+const { toolkit, layer } = ActionToolkit.make({}, app); // native Effect AI Toolkit and its handler layer
 const cli = ActionCli.group(app); // greetings greet --input '{"name":"Ada"}'
 const remote = ActionCliClient.command(Http, "greetings", "greet"); // same command, over HTTP
 const catalog = ActionCatalog.make(Actions); // offline JSON contract, no handlers acquired
@@ -61,9 +61,9 @@ const greeting = Effect.gen(function* () {
 ## Why
 
 - Input, success, and errors are declared once. Routes, tools, commands, clients, OpenAPI, and the catalog are derived from that declaration, so they cannot disagree.
-- A handler may fail only with the errors its action declares. Shared failures such as `Forbidden` are declared once on the group, and one `before` hook runs on every surface before every handler, so a policy such as scope enforcement is written once and cannot be forgotten.
+- A handler may fail only with the errors its action declares. Each surface binds one `before` hook that runs before every handler it serves — on HTTP before the payload is even decoded — so a policy such as scope enforcement is written once per surface and no action of that surface can skip it.
 - The pieces are Effect's own. `Http.api` is a native `HttpApi`, so `OpenApi.fromApi`, Swagger, Scalar, and `HttpApiClient` work on it unchanged. MCP is Effect's native `McpServer`, one `Tool` per action, with no SDK runtime dependency.
-- Every action states its `access` (`"read"` or `"write"`, defaulting to `"write"`), so authorization reads the contract instead of a hand-maintained list of mutation names.
+- Every action states its `access` (`"read"` or `"write"`, required), so authorization reads the contract instead of a hand-maintained list of mutation names.
 - Build-time services and per-request services are tracked separately in the types. Middleware is per group, so a public group and an authenticated group can share one mount path.
 - Tests run in memory. Call the routes through a web handler with the same typed client, or drive the official MCP client, without opening a port.
 

package/dist/Action.d.mts

@@ -30,7 +30,7 @@ type ResolvedMcp<Name extends string, Mcp extends false | McpOptions | undefined
   readonly openWorld: boolean;
 };
 /** What `make` needs to define an action. */
-export interface Options<Input extends Codec, Output extends Codec, Errors extends ReadonlyArray<Codec>, Http extends boolean = boolean, Mcp extends false | McpOptions | undefined = McpOptions | undefined> {
+export interface Options<Input extends Codec, Output extends Codec, Errors extends ReadonlyArray<Codec>, Acc extends Access = Access, Http extends boolean = boolean, Mcp extends false | McpOptions | undefined = McpOptions | undefined> {
   readonly description: string;
   /** Omit for an action without arguments. */
   readonly input?: Input;
@@ -38,29 +38,29 @@ export interface Options<Input extends Codec, Output extends Codec, Errors exten
   /** One schema per declared failure; each keeps its own HTTP status annotation. Defaults to none. */
   readonly errors?: Errors;
   /**
-   * What the action does to its resource. Defaults to `"write"`, so an action
-   * nobody classified is treated as the more dangerous one. Read by a group's
-   * `before` hook; the library itself authorizes nothing.
+   * What the action does to its resource. Required: an action nobody classified
+   * is the one a reviewer must check. Read by a surface's `before` hook; the
+   * library itself authorizes nothing.
    */
-  readonly access?: Access;
+  readonly access: Acc;
   /** `false` hides the action from HTTP routes and clients. */
   readonly http?: Http;
   /** `false` hides the action from MCP; otherwise tool metadata. */
   readonly mcp?: Mcp;
 }
 /** A pure contract: schemas and transport metadata. Implementations are bound by `ActionGroup.implement`. */
-export interface Action<Name extends string, Input extends Codec, Output extends Codec, Errors extends ReadonlyArray<Codec>, Http extends boolean = boolean, Mcp extends false | McpOptions | undefined = McpOptions | undefined> {
+export interface Action<Name extends string, Input extends Codec, Output extends Codec, Errors extends ReadonlyArray<Codec>, Acc extends Access = Access, Http extends boolean = boolean, Mcp extends false | McpOptions | undefined = McpOptions | undefined> {
   readonly name: Name;
   readonly description: string;
   readonly input: Input;
   readonly success: Output;
   readonly errors: Errors;
-  readonly access: Access;
+  readonly access: Acc;
   readonly http: Http;
   readonly mcp: ResolvedMcp<Name, Mcp>;
 }
 /** Any action, with its schemas erased. */
-export type Any = Action<string, Codec, Codec, ReadonlyArray<Codec>, boolean, false> | Action<string, Codec, Codec, ReadonlyArray<Codec>, boolean, McpOptions> | Action<string, Codec, Codec, ReadonlyArray<Codec>, boolean, undefined>;
+export type Any = Action<string, Codec, Codec, ReadonlyArray<Codec>, Access, boolean, false> | Action<string, Codec, Codec, ReadonlyArray<Codec>, Access, boolean, McpOptions> | Action<string, Codec, Codec, ReadonlyArray<Codec>, Access, boolean, undefined>;
 /** Receives decoded input; may fail only with the declared errors. */
 export type Handler<A extends Any, R = never> = (input: A["input"]["Type"]) => Effect.Effect<A["success"]["Type"], A["errors"][number]["Type"], R>;
 /** An empty object schema that also produces the object root MCP requires. */
@@ -69,6 +69,6 @@ declare const NoInput: Schema.$Record<Schema.String, Schema.Never>;
  * Define an action contract. Names are `[A-Za-z0-9_-]+`, other than `then`.
  * Actions can be local-only by setting both transports to `false`.
  */
-export declare function make<const Name extends string, Input extends Codec = typeof NoInput, Output extends Codec = never, const Errors extends ReadonlyArray<Codec> = [], const Http extends boolean = true, const Mcp extends false | McpOptions | undefined = undefined>(name: Name, options: Options<Input, Output, Errors, Http, Mcp>): Action<Name, Input, Output, Errors, Http, Mcp>;
+export declare function make<const Name extends string, Input extends Codec = typeof NoInput, Output extends Codec = never, const Errors extends ReadonlyArray<Codec> = [], const Acc extends Access = Access, const Http extends boolean = true, const Mcp extends false | McpOptions | undefined = undefined>(name: Name, options: Options<Input, Output, Errors, Acc, Http, Mcp>): Action<Name, Input, Output, Errors, Acc, Http, Mcp>;
 //#endregion
 export { Action_d_exports };

package/dist/Action.mjs

@@ -5,7 +5,7 @@ import { Schema } from "effect";
 const NoInput = Schema.Record(Schema.String, Schema.Never);
 function make(name, options) {
 	assertName("action name", name);
-	const access = options.access ?? "write";
+	const { access } = options;
 	const readOnly = options.mcp === false ? false : options.mcp?.readOnly ?? access === "read";
 	const mcp = options.mcp === false ? false : {
 		name: options.mcp?.name ?? name,

package/dist/ActionCatalog.d.mts

@@ -1,4 +1,4 @@
-import { Access, Action_d_exports, Any } from "./Action.mjs";
+import { Action_d_exports, Any } from "./Action.mjs";
 import { ActionGroup_d_exports, Any as Any$1 } from "./ActionGroup.mjs";
 import { JsonSchema } from "effect";
 //#region src/ActionCatalog.d.ts
@@ -8,8 +8,6 @@ export interface Entry {
   readonly group: string;
   readonly name: string;
   readonly description: string;
-  /** Authorization metadata, resolved: `"write"` unless the contract says `"read"`. */
-  readonly access: Access;
   readonly http: boolean;
   readonly mcp: Any["mcp"];
   readonly input: JsonSchema.JsonSchema;

package/dist/ActionCatalog.mjs

@@ -23,7 +23,6 @@ const make = (...groups) => {
 			group: group.name,
 			name: action.name,
 			description: action.description,
-			access: action.access,
 			http: action.http,
 			mcp: action.mcp,
 			input: jsonSchema(action.input),

package/dist/ActionCli.d.mts

@@ -1,12 +1,22 @@
 import { Action_d_exports, Any, Handler } from "./Action.mjs";
 import { Actions } from "./internal/actions.mjs";
 import { HandlerContext, Handlers, HandlersContext, Implementation } from "./internal/implementation.mjs";
-import { Options } from "./internal/cli.mjs";
-import { Scope } from "effect";
+import { Options as Options$1 } from "./internal/cli.mjs";
+import { Effect, Scope } from "effect";
 import { Command } from "effect/unstable/cli";
 //#region src/ActionCli.d.ts
+/**
+ * The hook a local command runs before the selected handler. A CLI encodes
+ * nothing, so its refusal is a typed failure of the command effect rather than a
+ * declared surface error; the native parser has already decoded the input.
+ */
+interface BeforeOptions<E, R> {
+  readonly before?: (action: Any) => Effect.Effect<void, E, R>;
+}
+/** Parsing, rendering and the pre-handler hook of one local command. */
+export type Options<Output, E = never, R = never, Parameters extends Command.Command.Config = never> = Options$1<Output, Parameters> & BeforeOptions<E, R>;
 /** Configuration for an aggregate group command. */
-export interface GroupOptions {
+export interface GroupOptions<E = never, R = never> extends BeforeOptions<E, R> {
   /** Override the group command name. */
   readonly name?: string;
 }
@@ -18,10 +28,7 @@ type BoundHandler<Name extends string, A extends Any, R> = Readonly<Record<Name,
  * Project one explicitly selected local action into a native Effect CLI command.
  * The action name resolves against the bound group; no HTTP fallback exists.
  */
-export declare const command: <G extends Actions, Name extends G["actions"][number]["name"], H extends BoundHandler<Name, Selected<G, Name>, HandlerContext<H, Name>>, EX, RX, RB, Parameters extends Command.Command.Config = never>(app: Implementation<G, H, EX, RX, RB>, name: Name, options?: Options<Selected<G, Name>["success"]["Type"], Parameters>) => Command.Command<string, never, {}, EX | import("effect/Schema").SchemaError | Extract<G["actions"][number], {
-  readonly name: Name;
-}>["errors"][number]["Type"], Exclude<RB, Scope.Scope> | Exclude<RX, Scope.Scope> | Exclude<HandlerContext<H, Name>, Scope.Scope>>;
+export declare const command: <G extends Actions, Name extends G["actions"][number]["name"], H extends BoundHandler<Name, Selected<G, Name>, HandlerContext<H, Name>>, EX, RX, EB = never, RB = never, Parameters extends Command.Command.Config = never>(app: Implementation<G, H, EX, RX>, name: Name, options?: Options<Selected<G, Name>["success"]["Type"], EB, RB, Parameters>) => Command.Command<string, never, {}, unknown, Exclude<RB, Scope.Scope> | Exclude<RX, Scope.Scope> | Exclude<HandlerContext<H, Name>, Scope.Scope>>;
 /** Project every local action below its group namespace with default CLI options. */
-export declare const group: <G extends Actions, H extends Handlers<HandlersContext<H>>, EX, RX, RB>(app: Implementation<G, H, EX, RX, RB>, options?: GroupOptions) => Command.Command<string, {}, {}, EX | import("effect/Schema").SchemaError | G["actions"][number]["errors"][number]["Type"], Exclude<Exclude<RB, Scope.Scope>, Command.CommandContext<string>> | Exclude<Exclude<RX, Scope.Scope>, Command.CommandContext<string>> | Exclude<Exclude<HandlersContext<H>, Scope.Scope>, Command.CommandContext<string>>>;
-//#endregion
-export type { Options };
+export declare const group: <G extends Actions, H extends Handlers<HandlersContext<H>>, EX, RX, EB = never, RB = never>(app: Implementation<G, H, EX, RX>, options?: GroupOptions<EB, RB>) => Command.Command<string, {}, {}, EB | EX | import("effect/Schema").SchemaError | G["actions"][number]["errors"][number]["Type"], Exclude<Exclude<RB, Scope.Scope>, Command.CommandContext<string>> | Exclude<Exclude<RX, Scope.Scope>, Command.CommandContext<string>> | Exclude<Exclude<HandlersContext<H>, Scope.Scope>, Command.CommandContext<string>>>;
+//#endregion

package/dist/ActionCli.mjs

@@ -8,18 +8,19 @@ const select = (group, name) => {
 	if (action === void 0) throw new Error(`Unknown action "${group.name}.${name}"`);
 	return action;
 };
-const local = (app, action, input) => Effect.scoped(Effect.flatMap(app.build, (handlers) => dispatch(app.group, action, handlers, app.before)(input)));
+const local = (app, action, before, input) => Effect.scoped(Effect.flatMap(app.build, (handlers) => dispatch(app.group, action, handlers, before)(input)));
 /**
 * Project one explicitly selected local action into a native Effect CLI command.
 * The action name resolves against the bound group; no HTTP fallback exists.
 */
 const command = (app, name, options) => {
 	const action = select(app.group, name);
-	return command$1(action, (input) => local(app, action, input), options);
+	return command$1(action, (input) => local(app, action, options?.before, input), options);
 };
 /** Project every local action below its group namespace with default CLI options. */
 const group = (app, options) => {
-	const commands = app.group.actions.map((action) => command$1(action, (input) => Effect.scoped(Effect.flatMap(app.build, (handlers) => dispatch(app.group, action, handlers, app.before)(input)))));
+	const before = options?.before;
+	const commands = app.group.actions.map((action) => command$1(action, (input) => Effect.scoped(Effect.flatMap(app.build, (handlers) => dispatch(app.group, action, handlers, before)(input)))));
 	return Command.make(options?.name ?? app.group.name).pipe(Command.withSubcommands(commands));
 };
 //#endregion

package/dist/ActionCliClient.d.mts

@@ -3,9 +3,9 @@ import { Actions } from "./internal/actions.mjs";
 import { Options as Options$1 } from "./internal/cli.mjs";
 import { ActionHttp_d_exports, Api, Http } from "./ActionHttp.mjs";
 import { Effect } from "effect";
+import { HttpClient } from "effect/unstable/http";
 import { HttpApi, HttpApiClient, HttpApiEndpoint, HttpApiGroup } from "effect/unstable/httpapi";
 import { Command } from "effect/unstable/cli";
-import { HttpClient } from "effect/unstable/http";
 //#region src/ActionCliClient.d.ts
 /** Parsing, rendering and native HTTP-endpoint configuration for one remote action. */
 export type Options<Output, ParsedParameters extends Command.Command.Config = never> = Options$1<Output, ParsedParameters> & {

package/dist/ActionCliClient.mjs

@@ -1,8 +1,8 @@
 import { command as command$1 } from "./internal/cli.mjs";
 import { Effect } from "effect";
+import { HttpClient } from "effect/unstable/http";
 import { HttpApiClient } from "effect/unstable/httpapi";
 import { Command } from "effect/unstable/cli";
-import { HttpClient } from "effect/unstable/http";
 //#region src/ActionCliClient.ts
 /**
 * The native endpoint builder needs string selectors for a runtime-selected route.

package/dist/ActionGroup.d.mts

@@ -3,11 +3,11 @@ import { Actions, SchemaErrorPolicy } from "./internal/actions.mjs";
 import { Implementation } from "./internal/implementation.mjs";
 import { Effect, Scope } from "effect";
 declare namespace ActionGroup_d_exports {
-  export { Any, Group, ImplementOptions, Implementation, Options, SchemaErrorPolicy, make };
+  export { Any, Contracts, Group, Implementation, Options, SchemaErrorPolicy, contracts, make };
 }
 type HandlersFrom<Actions extends ReadonlyArray<Any$1>> = { readonly [A in Actions[number] as A["name"]]: Handler<A, any>; };
 /** Group-level errors join each action's own, so a shared set is declared once. */
-type WithErrors<Actions extends ReadonlyArray<Any$1>, Errors extends ReadonlyArray<Codec>> = { readonly [K in keyof Actions]: Actions[K] extends Action<infer Name, infer Input, infer Output, infer Own, infer Http, infer Mcp> ? Action<Name, Input, Output, readonly [...Own, ...Errors], Http, Mcp> : never; };
+type WithErrors<Actions extends ReadonlyArray<Any$1>, Errors extends ReadonlyArray<Codec>> = { readonly [K in keyof Actions]: Actions[K] extends Action<infer Name, infer Input, infer Output, infer Own, infer Access, infer Http, infer Mcp> ? Action<Name, Input, Output, readonly [...Own, ...Errors], Access, Http, Mcp> : never; };
 /** What `make` needs to define a group. */
 export interface Options<Name extends string, Errors extends ReadonlyArray<Codec>, PolicyErrors extends ReadonlyArray<Codec>> {
   /** The `HttpApiGroup` identifier, and so the OpenAPI tag and operation-ID prefix. */
@@ -17,24 +17,26 @@ export interface Options<Name extends string, Errors extends ReadonlyArray<Codec
   /** How HTTP answers failed decoding or encoding of these actions; MCP keeps its native answers. */
   readonly schemaError?: SchemaErrorPolicy<PolicyErrors>;
 }
-/** What `implement` accepts besides the handlers themselves. */
-export interface ImplementOptions<Errors extends ReadonlyArray<Codec>, R> {
-  /**
-   * Runs once per invocation before the selected handler, on every surface, with
-   * the action contract it is about to run. It may fail only with the group's own
-   * `errors`, because those are the failures every action of the group declares.
-   * Its services are request-time requirements, like a handler's.
-   */
-  readonly before: (action: Any$1) => Effect.Effect<void, Errors[number]["Type"], R>;
-}
 /** A named set of action contracts: what adapters serve and what `implement` binds. */
-export interface Group<Name extends string, Actions$1 extends ReadonlyArray<Any$1>, PolicyErrors extends ReadonlyArray<Codec> = ReadonlyArray<Codec>, Errors extends ReadonlyArray<Codec> = ReadonlyArray<Codec>> extends Actions<Name, Actions$1, PolicyErrors> {
+export interface Group<Name extends string, Actions$1 extends ReadonlyArray<Any$1>, PolicyErrors extends ReadonlyArray<Codec> = ReadonlyArray<Codec>> extends Actions<Name, Actions$1, PolicyErrors> {
   /** Bind every handler at once, resolving build-time services once per adapter layer. */
-  readonly implement: <H extends HandlersFrom<Actions$1>, EX = never, RX = never, RB = never>(build: H | Effect.Effect<H, EX, RX>, options?: ImplementOptions<Errors, RB>) => Implementation<Group<Name, Actions$1, PolicyErrors, Errors>, H, NoInfer<EX>, NoInfer<Exclude<RX, Scope.Scope>>, NoInfer<RB>>;
+  readonly implement: <H extends HandlersFrom<Actions$1>, EX = never, RX = never>(build: H | Effect.Effect<H, EX, RX>) => Implementation<Group<Name, Actions$1, PolicyErrors>, H, NoInfer<EX>, NoInfer<Exclude<RX, Scope.Scope>>>;
 }
 /** Any group, with its actions and error schemas erased. */
-export type Any = Group<string, ReadonlyArray<Any$1>, ReadonlyArray<Codec>, any>;
+export type Any = Group<string, ReadonlyArray<Any$1>, ReadonlyArray<Codec>>;
 /** Define a group. Invalid or duplicate action and MCP names fail here, at definition time. */
-export declare function make<const Name extends string, const Actions extends ReadonlyArray<Any$1>, const Errors extends ReadonlyArray<Codec> = [], const PolicyErrors extends ReadonlyArray<Codec> = []>(options: Options<Name, Errors, PolicyErrors>, ...actions: Actions): Group<Name, WithErrors<Actions, Errors>, PolicyErrors, Errors>;
+export declare function make<const Name extends string, const Actions extends ReadonlyArray<Any$1>, const Errors extends ReadonlyArray<Codec> = [], const PolicyErrors extends ReadonlyArray<Codec> = []>(options: Options<Name, Errors, PolicyErrors>, ...actions: Actions): Group<Name, WithErrors<Actions, Errors>, PolicyErrors>;
+/** `G extends unknown` distributes, so each group maps only its own actions. */
+type PerGroup<G extends Actions> = G extends unknown ? { readonly [A in G["actions"][number] as `${G["name"]}.${A["name"]}`]: A; } : never;
+/** Merges those per-group maps into one, rather than leaving a union of them. */
+type Merged<Maps> = (Maps extends unknown ? (map: Maps) => void : never) extends ((map: infer Merged) => void) ? Merged : never;
+/** Every action of `Groups`, keyed `<group>.<action>`. */
+export type Contracts<Groups extends ReadonlyArray<Actions>> = Merged<PerGroup<Groups[number]>>;
+/**
+ * Project groups into one map of their action contracts, keyed `<group>.<action>`:
+ * the identity routes, tools and commands share. Deriving it from the groups
+ * themselves means an added action cannot be missed.
+ */
+export declare function contracts<const Groups extends ReadonlyArray<Actions>>(...groups: Groups): Contracts<Groups>;
 //#endregion
 export { ActionGroup_d_exports, type Implementation, type SchemaErrorPolicy };

package/dist/ActionGroup.mjs

@@ -15,13 +15,16 @@ function make(options, ...declared) {
 		name,
 		actions,
 		schemaError: options.schemaError,
-		implement: (build, options) => {
+		implement: (build) => {
 			const built = Effect.isEffect(build) ? build : Effect.succeed(build);
-			const before = options?.before;
-			return Implementation.make(group, built, before);
+			return Implementation.make(group, built);
 		}
 	};
 	return group;
 }
+function contracts(...groups) {
+	assertDistinct("contract group", groups.map((group) => group.name));
+	return Object.fromEntries(groups.flatMap((group) => group.actions.map((action) => [`${group.name}.${action.name}`, action])));
+}
 //#endregion
-export { make };
+export { contracts, make };

package/dist/ActionHttp.d.mts

@@ -1,13 +1,13 @@
 import { Action_d_exports, Any, Codec } from "./Action.mjs";
 import { Actions, PolicyError } from "./internal/actions.mjs";
 import { AnyImplementation, BuildContext, BuildError, RequestContext } from "./internal/implementation.mjs";
-import { Layer, Schema } from "effect";
-import { HttpApi, HttpApiEndpoint, HttpApiGroup } from "effect/unstable/httpapi";
+import { Effect, Layer, Schema } from "effect";
 import { Etag, HttpPlatform, HttpRouter } from "effect/unstable/http";
+import { HttpApi, HttpApiEndpoint, HttpApiGroup } from "effect/unstable/httpapi";
 import { FileSystem } from "effect/FileSystem";
 import { Path } from "effect/Path";
 declare namespace ActionHttp_d_exports {
-  export { Api, Http, Options, make };
+  export { Api, Http, LayerOptions, Options, make };
 }
 /** Contract-level configuration: servers and clients must agree on it. */
 export interface Options<Errors extends ReadonlyArray<Codec> = []> {
@@ -17,10 +17,21 @@ export interface Options<Errors extends ReadonlyArray<Codec> = []> {
    * handler: authentication, authorization, rate limits. Declared on every
    * endpoint, so `HttpApiClient` and `ActionCliClient` decode them as typed
    * failures rather than reporting a decode error. Each schema keeps its own
-   * `httpApiStatus`, and no two of them may share a status with an action error.
+   * `httpApiStatus`, and their `_tag`s must be distinct.
    */
   readonly errors?: Errors;
 }
+/** What `Http.layer` binds around the implementations it serves. */
+export interface LayerOptions<Errors extends ReadonlyArray<Codec>, R> {
+  /**
+   * Runs once per request, before the request payload is decoded, with the action
+   * contract it is about to run. It fails with the binding's own `errors`, so an
+   * unauthorized caller learns nothing about the action's input, and the refusal
+   * is encoded exactly like a declared error. Its services are request-time
+   * requirements, like a handler's.
+   */
+  readonly before?: (action: Any) => Effect.Effect<void, Errors[number]["Type"], R>;
+}
 type Endpoint<A extends Any, E extends Codec> = A extends {
   readonly http: false;
 } ? never : A extends Any ? HttpApiEndpoint.HttpApiEndpoint<A["name"], "POST", `/${string}`, never, never, Schema.toCodecJson<A["input"]>, never, Schema.toCodecJson<A["success"]>, Schema.toCodecJson<A["errors"][number] | E>, never> : never;
@@ -33,10 +44,11 @@ export interface Http<Groups extends ReadonlyArray<Actions>, Errors extends Read
   readonly groups: Groups;
   readonly api: Api<Groups[number], Errors[number]>;
   /**
-   * Serve any number of implementations in one layer. Build failures, build
-   * services and request services are unions over precisely those apps.
+   * Serve any number of implementations in one layer, with one pre-handler hook
+   * around every request they answer. Build failures, build services and request
+   * services are unions over precisely those apps and that hook.
    */
-  readonly layer: <const Apps extends ReadonlyArray<AnyImplementation<Groups[number]>>>(...apps: Apps) => Layer.Layer<never, BuildError<Apps[number]>, BuildContext<Apps[number]> | HttpRouter.HttpRouter | HttpRouter.Request.From<"Requires", RequestContext<Apps[number]>> | Etag.Generator | FileSystem | HttpPlatform.HttpPlatform | Path>;
+  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>;
 }
 /**
  * Bind the contract-level configuration once. Every route is `POST

package/dist/ActionHttp.mjs

@@ -1,15 +1,14 @@
-import { assertDistinct } from "./internal/actions.mjs";
+import { assertDistinct, projectedErrors } from "./internal/actions.mjs";
 import { dispatch } from "./internal/implementation.mjs";
 import { Effect, Layer } from "effect";
+import { HttpEffect, HttpRouter, HttpServerResponse } from "effect/unstable/http";
 import { HttpApi, HttpApiBuilder, HttpApiEndpoint, HttpApiGroup, HttpApiMiddleware, OpenApi } from "effect/unstable/httpapi";
 //#region src/ActionHttp.ts
 const httpActions = (group) => group.actions.filter((action) => action.http);
-/** Surface errors join an action's own, without repeating a schema it already declares. */
-const errorsOf = (options, action) => [...action.errors, ...(options.errors ?? []).filter((error) => !action.errors.includes(error))];
 const endpoint = (options, group, action) => HttpApiEndpoint.post(action.name, `${options.apiPath}/${group.name}/${action.name}`, {
 	payload: action.input,
 	success: action.success,
-	error: errorsOf(options, action)
+	error: projectedErrors(action, options.errors)
 }).annotate(OpenApi.Description, action.description);
 /** The native middleware declares the policy's errors on every endpoint it wraps. */
 const schemaErrorMiddleware = (name, policy) => {
@@ -19,18 +18,36 @@ const schemaErrorMiddleware = (name, policy) => {
 		layer: HttpApiMiddleware.layerSchemaErrorTransform(SchemaErrors, (failure) => Effect.fail(policy.map(failure)))
 	};
 };
+/** The hook of one group, applied to every one of its endpoints. */
+const hookMiddleware = (name) => {
+	class Admission extends HttpApiMiddleware.Service()(`effect-actions/http/Admission/${name}`) {}
+	const implementation = (group, before) => {
+		if (before === void 0) return (httpEffect) => httpEffect;
+		const actions = new Map(httpActions(group).map((action) => [action.name, action]));
+		return (httpEffect, { endpoint }) => {
+			const action = actions.get(endpoint.identifier);
+			if (action === void 0) throw new Error(`Missing action: ${endpoint.identifier}`);
+			return Effect.flatMap(before(action), () => httpEffect);
+		};
+	};
+	return {
+		Admission,
+		layer: (group, before) => Layer.succeed(Admission, implementation(group, before))
+	};
+};
 function bind(options, group) {
 	const [first, ...rest] = httpActions(group).map((action) => endpoint(options, group, action));
 	if (first === void 0) return void 0;
-	const native = HttpApiGroup.make(group.name).add(first, ...rest);
+	const bound = HttpApiGroup.make(group.name).add(first, ...rest);
+	const hook = hookMiddleware(group.name);
 	if (group.schemaError === void 0) return {
-		native,
-		policy: Layer.empty
+		native: bound.middleware(hook.Admission),
+		middleware: (before) => hook.layer(group, before)
 	};
 	const policy = schemaErrorMiddleware(group.name, group.schemaError);
 	return {
-		native: native.middleware(policy.SchemaErrors),
-		policy: policy.layer
+		native: bound.middleware(policy.SchemaErrors).middleware(hook.Admission),
+		middleware: (before) => Layer.merge(policy.layer, hook.layer(group, before))
 	};
 }
 function apiOf(groups) {
@@ -49,17 +66,22 @@ const erasedHandlers = (handlers) => {
 	return handlers;
 };
 /** Register one group's handlers. Handler erasure is limited to native dynamic endpoint registration. */
-const groupHandlers = (api, app, policy) => {
-	const entries = (record) => Object.fromEntries(httpActions(app.group).map((action) => [action.name, (request) => dispatch(app.group, action, record, app.before)(request.payload)]));
-	return Layer.unwrap(Effect.map(app.build, (record) => HttpApiBuilder.group(api, app.group.name, (builder) => builder.handleAll(entries(erasedHandlers(record)))))).pipe(Layer.provide(policy));
+const groupHandlers = (api, app, middleware) => {
+	const entries = (record) => Object.fromEntries(httpActions(app.group).map((action) => [action.name, (request) => dispatch(app.group, action, record, void 0)(request.payload)]));
+	return Layer.unwrap(Effect.map(app.build, (record) => HttpApiBuilder.group(api, app.group.name, (builder) => builder.handleAll(entries(erasedHandlers(record)))))).pipe(Layer.provide(middleware));
 };
+/**
+* A refused or failed request is never stored by a shared cache. Successful
+* responses keep whatever the host sets, since only the host knows what is public.
+*/
+const noStore = HttpRouter.middleware((httpEffect) => HttpEffect.withPreResponseHandler(httpEffect, (_request, response) => Effect.succeed(response.status < 400 ? response : HttpServerResponse.setHeader(response, "cache-control", "no-store"))));
 function make(options, ...groups) {
 	assertDistinct("action group", groups.map((group) => group.name));
 	const bound = new Map(groups.flatMap((group) => {
 		const binding = bind(options, group);
 		return binding === void 0 ? [] : [[group, binding]];
 	}));
-	const layer = (...apps) => {
+	const layer = (layerOptions, ...apps) => {
 		assertDistinct("implementation group", apps.map((app) => app.group.name));
 		for (const app of apps) if (!groups.includes(app.group)) throw new Error(`Implementation of group "${app.group.name}" is not served by this adapter`);
 		const served = apps.flatMap((app) => {
@@ -70,7 +92,8 @@ function make(options, ...groups) {
 			}];
 		});
 		const api = apiOf(served.map(({ native }) => native));
-		return served.reduce((layer, { app, policy }) => layer.pipe(Layer.provide(groupHandlers(api, app, policy))), HttpApiBuilder.layer(api));
+		const before = layerOptions.before;
+		return served.reduce((layer, { app, middleware }) => layer.pipe(Layer.provide(groupHandlers(api, app, middleware(before)))), HttpApiBuilder.layer(api)).pipe(Layer.provide(noStore.layer));
 	};
 	return {
 		groups,

package/dist/ActionMcp.d.mts

@@ -1,11 +1,28 @@
+import { Action_d_exports, Any, Codec } from "./Action.mjs";
 import { AnyImplementation, BuildContext, BuildError, RequestContext } from "./internal/implementation.mjs";
-import { Cause, Layer } from "effect";
-import { McpSchema, McpServer } from "effect/unstable/ai";
+import { Cause, Effect, Layer } from "effect";
 import { HttpRouter } from "effect/unstable/http";
+import { McpSchema, McpServer } from "effect/unstable/ai";
 import { Stdio } from "effect/Stdio";
 //#region src/ActionMcp.d.ts
+/** What every MCP transport binds around the tools it serves. */
+interface SurfaceOptions<Errors extends ReadonlyArray<Codec>, R> {
+  /**
+   * Failures the surface answers with instead of a handler: authorization, rate
+   * limits. Declared on every tool of this transport, so a refusal is returned
+   * as an `isError` result exactly like an action's own error.
+   */
+  readonly errors?: Errors;
+  /**
+   * Runs once per tool call, after the native server has decoded the arguments
+   * and before the selected handler, with the action contract it is about to run.
+   * It fails with this transport's `errors`. Its services are request-time
+   * requirements, like a handler's.
+   */
+  readonly before?: (action: Any) => Effect.Effect<void, Errors[number]["Type"], R>;
+}
 /** One Streamable HTTP MCP endpoint; its fields become the native server info. */
-export interface Options {
+export interface Options<Errors extends ReadonlyArray<Codec> = [], R = never> extends SurfaceOptions<Errors, R> {
   readonly name: string;
   readonly version: string;
   /** Native protocol adapters to serve; negotiation and sessions are owned by Effect. */
@@ -17,7 +34,7 @@ export interface Options {
   readonly instructions?: string;
 }
 /** Server information for an MCP subprocess connected through standard I/O. */
-export interface StdioOptions {
+export interface StdioOptions<Errors extends ReadonlyArray<Codec> = [], R = never> extends SurfaceOptions<Errors, R> {
   readonly name: string;
   readonly version: string;
   /** Native protocol adapters to serve; negotiation is owned by Effect. */
@@ -25,19 +42,19 @@ export interface StdioOptions {
   readonly instructions?: string;
 }
 /** The native server supplies its own request context to every tool call. */
-type ToolRequestContext<App> = Exclude<RequestContext<App>, McpSchema.McpRequestContext>;
+type ToolRequestContext<App, RB> = Exclude<RequestContext<App> | RB, McpSchema.McpRequestContext>;
 /**
  * Serve MCP tools over one Streamable HTTP endpoint.
  *
  * Middleware provided around this layer has the normal HTTP lifetime. Native
  * context capture applies: never provide request-identity tags at startup.
  */
-export declare function layerHttp<const Apps extends ReadonlyArray<AnyImplementation>>(options: Options, ...apps: Apps): Layer.Layer<never, BuildError<Apps[number]> | Cause.IllegalArgumentError, BuildContext<Apps[number]> | HttpRouter.HttpRouter | HttpRouter.Request.From<"Requires", ToolRequestContext<Apps[number]>>>;
+export declare function layerHttp<const Apps extends ReadonlyArray<AnyImplementation>, const Errors extends ReadonlyArray<Codec> = [], 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", ToolRequestContext<Apps[number], RB>>>;
 /**
  * Serve MCP tools through newline-delimited JSON-RPC on standard I/O.
  *
  * The host supplies the `Stdio` service. Arguments are tool input only and
  * never establish request identity or authority.
  */
-export declare function layerStdio<const Apps extends ReadonlyArray<AnyImplementation>>(options: StdioOptions, ...apps: Apps): Layer.Layer<never, BuildError<Apps[number]> | Cause.IllegalArgumentError, BuildContext<Apps[number]> | Stdio | ToolRequestContext<Apps[number]>>;
+export declare function layerStdio<const Apps extends ReadonlyArray<AnyImplementation>, const Errors extends ReadonlyArray<Codec> = [], RB = never>(options: StdioOptions<Errors, RB>, ...apps: Apps): Layer.Layer<never, BuildError<Apps[number]> | Cause.IllegalArgumentError, BuildContext<Apps[number]> | Stdio | ToolRequestContext<Apps[number], RB>>;
 //#endregion

package/dist/ActionMcp.mjs

@@ -3,13 +3,21 @@ import { bindTools } from "./internal/tools.mjs";
 import { Layer } from "effect";
 import { McpServer } from "effect/unstable/ai";
 //#region src/ActionMcp.ts
-const registration = (apps) => {
-	const binding = bindTools(apps, "mcp");
+const registration = (apps, options) => {
+	const binding = bindTools(apps, "mcp", options);
 	return Layer.effectDiscard(McpServer.registerToolkit(binding.toolkit)).pipe(Layer.provide(binding.layer));
 };
-const server = (apps, transport) => registration(apps).pipe(Layer.provide(transport), Layer.fresh);
+const server = (apps, options, transport) => registration(apps, options).pipe(Layer.provide(transport), Layer.fresh);
+/** The hook and surface errors an erased transport binds. */
+const toolOptions = (options) => {
+	const before = options.before;
+	return {
+		errors: options.errors,
+		before
+	};
+};
 function layerHttp(options, ...apps) {
-	return server(apps, McpServer.layerHttp({
+	return server(apps, toolOptions(options), McpServer.layerHttp({
 		name: options.name,
 		version: options.version,
 		instructions: options.instructions,
@@ -19,7 +27,7 @@ function layerHttp(options, ...apps) {
 	}));
 }
 function layerStdio(options, ...apps) {
-	return server(apps, McpServer.layerStdio(options));
+	return server(apps, toolOptions(options), McpServer.layerStdio(options));
 }
 //#endregion
 export { layerHttp, layerStdio };

package/dist/ActionToolkit.d.mts

@@ -1,26 +1,41 @@
-import { Action_d_exports, Any } from "./Action.mjs";
-import { AnyImplementation, BeforeContext, BuildContext, BuildError, HandlerContext, Implementation } from "./internal/implementation.mjs";
-import { Layer, Schema } from "effect";
+import { Action_d_exports, Any, Codec } from "./Action.mjs";
+import { AnyImplementation, BuildContext, BuildError, HandlerContext, Implementation } from "./internal/implementation.mjs";
+import { Effect, Layer, Schema } from "effect";
 import { Tool, Toolkit } from "effect/unstable/ai";
 //#region src/ActionToolkit.d.ts
+/** What `make` binds around the implementations it projects. */
+export interface Options<Errors extends ReadonlyArray<Codec> = [], R = never> {
+  /**
+   * Failures the caller answers with instead of a handler: authorization, rate
+   * limits. Declared on every tool, so a refusal is returned as a tool failure
+   * exactly like an action's own error.
+   */
+  readonly errors?: Errors;
+  /**
+   * Runs once per tool call, before the selected handler, with the action contract
+   * it is about to run. It fails with this binding's `errors`. Its services join
+   * each tool's request requirements, like a handler's.
+   */
+  readonly before?: (action: Any) => Effect.Effect<void, Errors[number]["Type"], R>;
+}
 /** A native tool corresponding to an MCP-enabled action. */
-type NativeTool<A extends Any, R> = A extends {
+type NativeTool<A extends Any, E extends Codec, R> = A extends {
   readonly mcp: {
     readonly name: infer Name extends string;
   };
 } ? Tool.Tool<Name, {
   readonly parameters: A["input"];
   readonly success: A["success"];
-  readonly failure: Schema.Union<A["errors"]>;
+  readonly failure: Schema.Union<ReadonlyArray<A["errors"][number] | E>>;
   readonly failureMode: "return";
 }, R> : never;
-type HandlersOf<App extends AnyImplementation> = App extends Implementation<any, infer H, any, any, any> ? H : never;
-/** A tool needs what its handler needs, plus what the group's `before` hook needs. */
-type ToolForAction<App extends AnyImplementation, A extends Any> = A extends {
+type HandlersOf<App extends AnyImplementation> = App extends Implementation<any, infer H, any, any> ? H : never;
+/** A tool needs what its handler needs, plus what the binding's `before` hook needs. */
+type ToolForAction<App extends AnyImplementation, A extends Any, E extends Codec, RB> = A extends {
   readonly mcp: object;
-} ? NativeTool<A, HandlerContext<HandlersOf<App>, Extract<A["name"], keyof HandlersOf<App>>> | BeforeContext<App>> : never;
-type ToolsFor<App extends AnyImplementation> = App extends AnyImplementation ? ToolForAction<App, App["group"]["actions"][number]> : never;
-type ToolkitTools<Apps extends ReadonlyArray<AnyImplementation>> = { readonly [T in ToolsFor<Apps[number]> as T["name"]]: T; };
+} ? NativeTool<A, E, HandlerContext<HandlersOf<App>, Extract<A["name"], keyof HandlersOf<App>>> | RB> : never;
+type ToolsFor<App extends AnyImplementation, E extends Codec, RB> = App extends AnyImplementation ? ToolForAction<App, App["group"]["actions"][number], E, RB> : never;
+type ToolkitTools<Apps extends ReadonlyArray<AnyImplementation>, E extends Codec, RB> = { readonly [T in ToolsFor<Apps[number], E, RB> as T["name"]]: T; };
 /** Native tools and the layer that binds their action implementations. */
 export interface Binding<Tools extends Record<string, Tool.Any>, E = never, R = never> {
   readonly toolkit: Toolkit.Toolkit<Tools>;
@@ -34,5 +49,5 @@ export interface Binding<Tools extends Record<string, Tool.Any>, E = never, R =
  * Build services are needed to construct `layer`; request services are needed
  * when the resulting toolkit handles a call.
  */
-export declare function make<const Apps extends ReadonlyArray<AnyImplementation>>(...apps: Apps): Binding<ToolkitTools<Apps>, BuildError<Apps[number]>, BuildContext<Apps[number]>>;
+export declare function make<const Apps extends ReadonlyArray<AnyImplementation>, const Errors extends ReadonlyArray<Codec> = [], RB = never>(options: Options<Errors, RB>, ...apps: Apps): Binding<ToolkitTools<Apps, Errors[number], RB>, BuildError<Apps[number]>, BuildContext<Apps[number]>>;
 //#endregion