@gjermundgaraba/effect-actions 0.2.0 → 0.4.0

package/README.md

@@ -18,7 +18,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);
@@ -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,8 +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.
+- 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"`, 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

@@ -1,14 +1,19 @@
 import { Effect, Schema } from "effect";
 declare namespace Action_d_exports {
-  export { Action, Any, Codec, Handler, McpOptions, Options, make };
+  export { Access, Action, Any, Codec, Handler, McpOptions, Options, make };
 }
 /** Any service-free schema. Only handlers may require services. */
 export type Codec = Schema.Codec<unknown, unknown, never, never>;
+/**
+ * What an action does to the resource it serves: `"read"` observes, `"write"`
+ * may change it. Authorization metadata, not an MCP hint.
+ */
+export type Access = "read" | "write";
 /** MCP tool metadata; every field has a default derived from the action. */
 export interface McpOptions {
   /** Tool name; defaults to the action name. Must match `^[A-Za-z0-9_-]{1,128}$`. */
   readonly name?: string;
-  /** `readOnlyHint`; defaults to `false`. */
+  /** `readOnlyHint`; defaults to `access === "read"`. */
   readonly readOnly?: boolean;
   /** `destructiveHint`; defaults to `!readOnly`, as the MCP spec only defines it for writes. */
   readonly destructive?: boolean;
@@ -25,30 +30,37 @@ 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;
   readonly success: Output;
   /** 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. 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: 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: 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. */
@@ -57,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,8 @@ import { Schema } from "effect";
 const NoInput = Schema.Record(Schema.String, Schema.Never);
 function make(name, options) {
 	assertName("action name", name);
-	const readOnly = options.mcp === false ? false : options.mcp?.readOnly ?? false;
+	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,
 		readOnly,
@@ -21,6 +22,7 @@ function make(name, options) {
 		input: options.input ?? NoInput,
 		success: options.success,
 		errors: options.errors ?? [],
+		access,
 		http: options.http !== false,
 		mcp
 	};

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, Parameters extends Command.Command.Config = never>(app: Implementation<G, H, EX, RX>, 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<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>(app: Implementation<G, H, EX, RX>, options?: GroupOptions) => Command.Command<string, {}, {}, EX | import("effect/Schema").SchemaError | G["actions"][number]["errors"][number]["Type"], 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)(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)(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

@@ -1,10 +1,11 @@
+import { Action_d_exports, Codec } from "./Action.mjs";
 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> & {
@@ -27,19 +28,19 @@ type Selected<G extends Actions, Name extends G["actions"][number]["name"]> = Ex
 type HttpNames<G extends Actions> = Extract<G["actions"][number], {
   readonly http: true;
 }>["name"];
-type ApiGroups<Groups extends ReadonlyArray<Actions>> = Api<Groups[number]> extends HttpApi.HttpApi<"actions", infer ApiGroups> ? ApiGroups : never;
-type Endpoint<Groups extends ReadonlyArray<Actions>, GroupName extends Groups[number]["name"], ActionName extends HttpNames<Group<Groups, GroupName>>> = Extract<HttpApiGroup.EndpointsWithIdentifier<ApiGroups<Groups>, Extract<GroupName, HttpApiGroup.Identifier<ApiGroups<Groups>>>>, {
+type ApiGroups<Groups extends ReadonlyArray<Actions>, Errors extends ReadonlyArray<Codec>> = Api<Groups[number], Errors[number]> extends HttpApi.HttpApi<"actions", infer ApiGroups> ? ApiGroups : never;
+type Endpoint<Groups extends ReadonlyArray<Actions>, Errors extends ReadonlyArray<Codec>, GroupName extends Groups[number]["name"], ActionName extends HttpNames<Group<Groups, GroupName>>> = Extract<HttpApiGroup.EndpointsWithIdentifier<ApiGroups<Groups, Errors>, Extract<GroupName, HttpApiGroup.Identifier<ApiGroups<Groups, Errors>>>>, {
   readonly identifier: ActionName;
 }>;
-type NativeMethod<Groups extends ReadonlyArray<Actions>, GroupName extends Groups[number]["name"], ActionName extends HttpNames<Group<Groups, GroupName>>> = HttpApiClient.Client.Method<Extract<Endpoint<Groups, GroupName, ActionName>, HttpApiEndpoint.ConstraintRequest>, never, never>;
-type RemoteCommand<Groups extends ReadonlyArray<Actions>, GroupName extends Groups[number]["name"], ActionName extends HttpNames<Group<Groups, GroupName>>> = Command.Command<string, never, {}, Effect.Error<ReturnType<NativeMethod<Groups, GroupName, ActionName>>>, HttpClient.HttpClient | Effect.Services<ReturnType<NativeMethod<Groups, GroupName, ActionName>>>>;
-type RemoteGroupCommand<Groups extends ReadonlyArray<Actions>, GroupName extends Groups[number]["name"]> = Command.Command<string, {}, {}, Effect.Error<ReturnType<NativeMethod<Groups, GroupName, HttpNames<Group<Groups, GroupName>>>>>, HttpClient.HttpClient | Effect.Services<ReturnType<NativeMethod<Groups, GroupName, HttpNames<Group<Groups, GroupName>>>>>>;
+type NativeMethod<Groups extends ReadonlyArray<Actions>, Errors extends ReadonlyArray<Codec>, GroupName extends Groups[number]["name"], ActionName extends HttpNames<Group<Groups, GroupName>>> = HttpApiClient.Client.Method<Extract<Endpoint<Groups, Errors, GroupName, ActionName>, HttpApiEndpoint.ConstraintRequest>, never, never>;
+type RemoteCommand<Groups extends ReadonlyArray<Actions>, Errors extends ReadonlyArray<Codec>, GroupName extends Groups[number]["name"], ActionName extends HttpNames<Group<Groups, GroupName>>> = Command.Command<string, never, {}, Effect.Error<ReturnType<NativeMethod<Groups, Errors, GroupName, ActionName>>>, HttpClient.HttpClient | Effect.Services<ReturnType<NativeMethod<Groups, Errors, GroupName, ActionName>>>>;
+type RemoteGroupCommand<Groups extends ReadonlyArray<Actions>, Errors extends ReadonlyArray<Codec>, GroupName extends Groups[number]["name"]> = Command.Command<string, {}, {}, Effect.Error<ReturnType<NativeMethod<Groups, Errors, GroupName, HttpNames<Group<Groups, GroupName>>>>>, HttpClient.HttpClient | Effect.Services<ReturnType<NativeMethod<Groups, Errors, GroupName, HttpNames<Group<Groups, GroupName>>>>>>;
 /**
  * Project one HTTP action retained by the binding into a native Effect CLI command.
  * Group and action selectors resolve exclusively from `http.groups`; runtime guards
  * keep dynamically supplied selector strings from reaching the native client.
  */
-export declare const command: <const Groups extends ReadonlyArray<Actions>, const GroupName extends Groups[number]["name"], const ActionName extends HttpNames<Group<Groups, GroupName>>, ParsedParameters extends Command.Command.Config = never>(http: Http<Groups>, groupName: GroupName, actionName: ActionName, options?: Options<Selected<Group<Groups, GroupName>, ActionName>["success"]["Type"], ParsedParameters>) => RemoteCommand<Groups, GroupName, ActionName>;
+export declare const command: <const Groups extends ReadonlyArray<Actions>, const Errors extends ReadonlyArray<Codec>, const GroupName extends Groups[number]["name"], const ActionName extends HttpNames<Group<Groups, GroupName>>, ParsedParameters extends Command.Command.Config = never>(http: Http<Groups, Errors>, groupName: GroupName, actionName: ActionName, options?: Options<Selected<Group<Groups, GroupName>, ActionName>["success"]["Type"], ParsedParameters>) => RemoteCommand<Groups, Errors, GroupName, ActionName>;
 /** Project all HTTP-enabled actions retained by one group below its group namespace. */
-export declare const group: <const Groups extends ReadonlyArray<Actions>, const GroupName extends Groups[number]["name"]>(http: Http<Groups>, groupName: GroupName, options?: GroupOptions) => RemoteGroupCommand<Groups, GroupName>;
+export declare const group: <const Groups extends ReadonlyArray<Actions>, const Errors extends ReadonlyArray<Codec>, const GroupName extends Groups[number]["name"]>(http: Http<Groups, Errors>, groupName: GroupName, options?: GroupOptions) => RemoteGroupCommand<Groups, Errors, GroupName>;
 //#endregion

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, 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. */
@@ -22,9 +22,21 @@ export interface Group<Name extends string, Actions$1 extends ReadonlyArray<Any$
   /** Bind every handler at once, resolving build-time services once per adapter layer. */
   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 erased. */
-export type Any = Group<string, ReadonlyArray<Any$1>>;
+/** Any group, with its actions and error schemas erased. */
+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>;
+/** `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

@@ -22,5 +22,9 @@ function make(options, ...declared) {
 	};
 	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,39 +1,59 @@
 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 {
+export interface Options<Errors extends ReadonlyArray<Codec> = []> {
   readonly apiPath: `/${string}`;
+  /**
+   * Failures the surface around these endpoints answers with instead of a
+   * 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 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;
-type ApiGroup<G extends Actions> = G extends Actions ? [Endpoint<G["actions"][number], never>] extends [never] ? never : HttpApiGroup.HttpApiGroup<G["name"], Endpoint<G["actions"][number], PolicyError<G>>> : never;
+type ApiGroup<G extends Actions, E extends Codec> = G extends Actions ? [Endpoint<G["actions"][number], never>] extends [never] ? never : HttpApiGroup.HttpApiGroup<G["name"], Endpoint<G["actions"][number], PolicyError<G> | E>> : never;
 /** The native `HttpApi` of every HTTP-enabled action of `G`, one group per action group. */
-export type Api<G extends Actions> = HttpApi.HttpApi<"actions", ApiGroup<G>>;
+export type Api<G extends Actions, E extends Codec = never> = HttpApi.HttpApi<"actions", ApiGroup<G, E>>;
 /** A namespaced HTTP binding. */
-export interface Http<Groups extends ReadonlyArray<Actions>> {
+export interface Http<Groups extends ReadonlyArray<Actions>, Errors extends ReadonlyArray<Codec> = []> {
   /** The exact contracts bound to this HTTP adapter, in declaration order. */
   readonly groups: Groups;
-  readonly api: Api<Groups[number]>;
+  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
  * <apiPath>/<group>/<action>`, so action names may repeat across groups.
  */
-export declare function make<const G extends ReadonlyArray<Actions>>(options: Options, ...groups: G): Http<G>;
+export declare function make<const G extends ReadonlyArray<Actions>, const E extends ReadonlyArray<Codec> = []>(options: Options<E>, ...groups: G): Http<G, E>;
 //#endregion
 export { ActionHttp_d_exports };

package/dist/ActionHttp.mjs

@@ -1,13 +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);
-const endpoint = (apiPath, group, action) => HttpApiEndpoint.post(action.name, `${apiPath}/${group.name}/${action.name}`, {
+const endpoint = (options, group, action) => HttpApiEndpoint.post(action.name, `${options.apiPath}/${group.name}/${action.name}`, {
 	payload: action.input,
 	success: action.success,
-	error: action.errors
+	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) => {
@@ -17,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.apiPath, group, action));
+	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) {
@@ -47,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)(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) => {
@@ -68,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 };