@gjermundgaraba/effect-actions 0.2.0 → 0.4.0

package/dist/ActionToolkit.d.mts

@@ -1,25 +1,41 @@
-import { Action_d_exports, Any } from "./Action.mjs";
+import { Action_d_exports, Any, Codec } from "./Action.mjs";
 import { AnyImplementation, BuildContext, BuildError, HandlerContext, Implementation } from "./internal/implementation.mjs";
-import { Layer, Schema } from "effect";
+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> ? H : never;
-type ToolForAction<App extends AnyImplementation, A extends Any> = A extends {
+/** 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>>>> : 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>;
@@ -33,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

package/dist/ActionToolkit.mjs

@@ -3,8 +3,13 @@ import { bindTools } from "./internal/tools.mjs";
 import "effect";
 import "effect/unstable/ai";
 //#region src/ActionToolkit.ts
-function make(...apps) {
-	return bindTools(apps, "native");
+function make(options, ...apps) {
+	const before = options.before;
+	const toolOptions = {
+		errors: options.errors,
+		before
+	};
+	return bindTools(apps, "native", toolOptions);
 }
 //#endregion
 export { make };

package/dist/Testing.mjs

@@ -1,6 +1,6 @@
 import { Effect, Layer, Predicate } from "effect";
-import { HttpApiClient } from "effect/unstable/httpapi";
 import { FetchHttpClient } from "effect/unstable/http";
+import { HttpApiClient } from "effect/unstable/httpapi";
 //#region src/Testing.ts
 /**
 * The native grouped HTTP client, calling `handler` in memory instead of the network.

package/dist/internal/actions.mjs

@@ -1,4 +1,10 @@
 //#region src/internal/actions.ts
+/**
+* An action's own failures plus the ones its surface answers with, which is what
+* a projection of that action declares. A schema the action already declares is
+* not repeated.
+*/
+const projectedErrors = (action, surface) => [...action.errors, ...(surface ?? []).filter((error) => !action.errors.includes(error))];
 const validName = /^[A-Za-z0-9_-]+$/;
 /** Names become path segments, OpenAPI identifiers and client method keys. */
 const assertName = (what, name) => {
@@ -13,4 +19,4 @@ const assertDistinct = (what, names) => {
 	}
 };
 //#endregion
-export { assertDistinct, assertName };
+export { assertDistinct, assertName, projectedErrors };

package/dist/internal/implementation.mjs

@@ -23,14 +23,17 @@ var Implementation = class Implementation {
 };
 /**
 * Select and invoke a handler after an adapter has selected a concrete action.
+* The surface's pre-handler hook runs first, outside the action's span, so a
+* refusal is attributed to the surface rather than to a handler that never ran.
 * `R` remains in the returned effect so transport layers cannot erase required
 * per-request services while assembling routes.
 */
-const dispatch = (group, action, handlers) => {
+const dispatch = (group, action, handlers, before) => {
 	const handle = handlers[action.name];
 	if (handle === void 0) throw new Error(`Missing handler: ${action.name}`);
 	return (input) => {
-		return Effect.withSpan(Effect.suspend(() => handle(input)), `${group.name}.${action.name}`, { captureStackTrace: false });
+		const handled = Effect.withSpan(Effect.suspend(() => handle(input)), `${group.name}.${action.name}`, { captureStackTrace: false });
+		return before === void 0 ? handled : Effect.flatMap(before(action), () => handled);
 	};
 };
 //#endregion

package/dist/internal/tools.mjs

@@ -1,3 +1,4 @@
+import { projectedErrors } from "./actions.mjs";
 import { dispatch } from "./implementation.mjs";
 import { Effect, Schema } from "effect";
 import { Tool, Toolkit } from "effect/unstable/ai";
@@ -30,22 +31,22 @@ const annotate = (tool, mcp) => tool.annotate(Tool.Readonly, mcp.readOnly).annot
 * A native Effect AI tool. Its schemas retain action transforms and its result
 * is the action result itself, rather than an MCP response envelope.
 */
-const nativeTool = (action) => annotate(Tool.make(action.mcp.name, {
+const nativeTool = (action, errors) => annotate(Tool.make(action.mcp.name, {
 	description: action.description,
 	parameters: action.input,
 	success: action.success,
-	failure: Schema.Union(action.errors),
+	failure: Schema.Union(errors),
 	failureMode: "return"
 }), action.mcp);
 /**
 * MCP has a JSON-only wire contract. Success uses its documented `{ value }`
 * structured-content envelope; declared failures are returned as JSON text.
 */
-const mcpTool = (action) => annotate(Tool.make(action.mcp.name, {
+const mcpTool = (action, errors) => annotate(Tool.make(action.mcp.name, {
 	description: action.description,
 	parameters: Schema.toCodecJson(action.input),
 	success: Schema.toCodecJson(Schema.Struct({ value: action.success })),
-	failure: Schema.toCodecJson(Schema.Union(action.errors)),
+	failure: Schema.toCodecJson(Schema.Union(errors)),
 	failureMode: "return"
 }), action.mcp);
 /** MCP's input schema must describe a JSON object, including no-argument tools. */
@@ -53,14 +54,15 @@ const assertMcpObjectInput = (action, tool) => {
 	const root = Tool.getJsonSchemaFromSchema(tool.parametersSchema);
 	if (root.$ref === void 0 && root.type !== "object") throw new Error(`${action.name}: MCP input must have an object root; omit input for no arguments`);
 };
-const project = (projection, entry) => {
-	const tool = projection === "native" ? nativeTool(entry.action) : mcpTool(entry.action);
+const project = (projection, entry, options) => {
+	const errors = projectedErrors(entry.action, options.errors);
+	const tool = projection === "native" ? nativeTool(entry.action, errors) : mcpTool(entry.action, errors);
 	if (projection === "native") return tool;
 	assertMcpObjectInput(entry.action, tool);
 	return tool.annotate(Tool.Strict, true);
 };
-const handler = (projection, app, action, handlers) => {
-	const run = (input) => dispatch(app.group, action, handlers)(input);
+const handler = (projection, app, action, handlers, before) => {
+	const run = (input) => dispatch(app.group, action, handlers, before)(input);
 	return projection === "native" ? run : (input) => Effect.map(run(input), (value) => ({ value }));
 };
 /**
@@ -68,16 +70,16 @@ const handler = (projection, app, action, handlers) => {
 * Native and MCP differ only in tool codecs and the MCP success envelope; selection,
 * scoped acquisition, dispatch and native Toolkit binding stay identical.
 */
-const bindTools = (apps, projection) => {
+const bindTools = (apps, projection, options) => {
 	const served = toolApps(apps);
 	const selected = entries(served);
 	assertDistinctToolNames(selected);
-	const toolkit = Toolkit.make(...selected.map((entry) => project(projection, entry)));
+	const toolkit = Toolkit.make(...selected.map((entry) => project(projection, entry, options)));
 	return {
 		toolkit,
 		layer: toolkit.toLayer(Effect.map(Effect.forEach(served, ({ app, actions }) => Effect.map(app.build, (handlers) => {
 			const record = handlers;
-			return actions.map((action) => [action.mcp.name, handler(projection, app, action, record)]);
+			return actions.map((action) => [action.mcp.name, handler(projection, app, action, record, options.before)]);
 		})), (built) => Object.fromEntries(built.flat())))
 	};
 };

package/docs/Action.md

@@ -11,34 +11,39 @@ import * as Action from "@gjermundgaraba/effect-actions/Action";
 /** Any service-free schema. */
 type Codec = Schema.Codec<unknown, unknown, never, never>;
 
-function make<Name, Input = NoInput, Output, Errors = [], Http = true, Mcp = undefined>(
+function make<Name, Input = NoInput, Output, Errors = [], Acc extends Access, Http = true, Mcp = undefined>(
   name: Name,
-  options: Options<Input, Output, Errors, Http, Mcp>,
-): Action<Name, Input, Output, Errors, Http, Mcp>;
+  options: Options<Input, Output, Errors, Acc, Http, Mcp>,
+): Action<Name, Input, Output, Errors, Acc, Http, Mcp>;
 
-interface Options<Input, Output, Errors, Http, Mcp> {
+/** What the action does to its resource. Authorization metadata, not an MCP hint. */
+type Access = "read" | "write";
+
+interface Options<Input, Output, Errors, Acc, Http, Mcp> {
   readonly description: string;
   readonly input?: Input; // omit for an action without arguments
   readonly success: Output;
   readonly errors?: Errors; // ReadonlyArray<Codec>; defaults to []
+  readonly access: Acc; // required, no default
   readonly http?: Http; // false hides the action from HTTP routes and clients
   readonly mcp?: Mcp; // false hides the action from MCP; otherwise McpOptions
 }
 
 interface McpOptions {
   readonly name?: string; // tool name; defaults to the action name; ^[A-Za-z0-9_-]{1,128}$
-  readonly readOnly?: boolean; // readOnlyHint, default false
+  readonly readOnly?: boolean; // readOnlyHint, default access === "read"
   readonly destructive?: boolean; // destructiveHint, default !readOnly
   readonly idempotent?: boolean; // idempotentHint, default false
   readonly openWorld?: boolean; // openWorldHint, default true
 }
 
-interface Action<Name, Input, Output, Errors, Http, Mcp> {
+interface Action<Name, Input, Output, Errors, Acc, Http, Mcp> {
   readonly name: Name;
   readonly description: string;
   readonly input: Input;
   readonly success: Output;
   readonly errors: Errors;
+  readonly access: Acc; // the literal it was declared with
   readonly http: Http;
   readonly mcp: false | { name; readOnly; destructive; idempotent; openWorld }; // resolved
 }
@@ -63,27 +68,41 @@ export class UserNotFound extends Schema.TaggedError<UserNotFound>()(
   { httpApiStatus: 404 },
 ) {}
 
+// `access: "read"` states the fact once: it is what a surface's `before` hook
+// authorizes on, and it is where `mcp.readOnly` comes from.
 export const GetUser = Action.make("getUser", {
   description: "Look up a user in your tenant.",
   input: Schema.Struct({ id: Schema.String }),
   success: Schema.Struct({ id: Schema.String, name: Schema.String }),
   errors: [UserNotFound],
-  mcp: { name: "get_user", readOnly: true },
+  access: "read",
+  mcp: { name: "get_user" },
+});
+
+// A write. Every action says which it is; there is no default to fall back on.
+export const RenameUser = Action.make("renameUser", {
+  description: "Rename a user in your tenant.",
+  input: Schema.Struct({ id: Schema.String, name: Schema.String }),
+  success: Schema.Struct({ id: Schema.String, name: Schema.String }),
+  errors: [UserNotFound],
+  access: "write",
+  mcp: { name: "rename_user", destructive: false },
 });
 
 // No arguments: omit `input`. Identity comes from request context, never from input.
 export const WhoAmI = Action.make("whoAmI", {
   description: "Inspect the authenticated actor.",
   success: Schema.Struct({ id: Schema.String, tenantId: Schema.String }),
-  mcp: { readOnly: true },
+  access: "read",
 });
 
 // MCP-only: no HTTP route, no client method.
 export const ListChanges = Action.make("listChanges", {
   description: "List renames in your tenant, oldest first.",
   success: Schema.Struct({ changes: Schema.Array(Schema.String) }),
+  access: "read",
   http: false,
-  mcp: { name: "list_changes", readOnly: true },
+  mcp: { name: "list_changes" },
 });
 
 // Input decoding is the schema's: "21" on the wire, 21 in the handler.
@@ -91,7 +110,7 @@ export const Double = Action.make("double", {
   description: "Double a finite number supplied as a string.",
   input: Schema.Struct({ value: Schema.FiniteFromString }),
   success: Schema.Finite,
-  mcp: { readOnly: true },
+  access: "read",
 });
 ```
 
@@ -101,13 +120,15 @@ export const Double = Action.make("double", {
 - Omit `input` for a no-argument action. The default is an empty object schema, which satisfies MCP's object-root requirement. Clients still pass `{ payload: {} }`.
 - `errors` is a list of schemas, default none. Each keeps its own `httpApiStatus` annotation; an unannotated error is served as HTTP 500. Group-level `errors` are appended to every action of the group (see [ActionGroup.md](ActionGroup.md)).
 - A handler may fail only with the declared errors. Anything else is a defect.
+- `access` is `"read"` or `"write"` and is required. It stays a literal on the action, so a rule may switch on it at the type level. It is authorization metadata for a surface's `before` hook (see [guarantees.md](guarantees.md)); the library itself authorizes nothing and no adapter reads it.
+- `access` is independent of `mcp`. A local-only action (`mcp: false`) still has one, and an action may set `access: "write"` with `mcp: { readOnly: true }` if the tool hint should say something else. Derive authorization from `access`, never from a tool hint.
 - Both transports are on by default. `http: false` removes the route and the client method. `mcp: false` removes the tool. Both `false` makes a local-only action, reachable through `ActionCli` only.
 - MCP input must have an object-root JSON Schema. Scalar or array input is fine for HTTP, but `ActionMcp.layerHttp`, `ActionMcp.layerStdio`, and `ActionToolkit.make` throw when called with such an action. Success and error schemas may be any shape.
 - `mcp.name` is the tool name, at most 128 characters, unique within the group and within any Toolkit or MCP projection that serves the group. Default is the action name.
-- Hint defaults: `readOnly: false`, `destructive: !readOnly`, `idempotent: false`, `openWorld: true`. Hints are metadata for the model. They do not enforce authorization, approval, or retries.
+- Hint defaults: `readOnly: access === "read"`, `destructive: !readOnly`, `idempotent: false`, `openWorld: true`. Hints are metadata for the model. They do not enforce authorization, approval, or retries.
 - Schemas must be service-free. Put service access in the handler.
 - The group name, not the action, is the OpenAPI tag and operation-ID prefix: `<group>.<action>`.
-- 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`.
+- 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.
 
 ## Failure modes
 
@@ -115,3 +136,5 @@ export const Double = Action.make("double", {
 - Type error `Effect<..., X, ...> is not assignable` in `implement`: the handler fails with an undeclared error `X`. Add it to `errors` or handle it.
 - `<action>: MCP input must have an object root` thrown by `ActionMcp.layerHttp`, `ActionMcp.layerStdio`, or `ActionToolkit.make`: an MCP-enabled action has non-object input. Wrap it in `Schema.Struct` or set `mcp: false`.
 - Handler receives a string where a number was expected: the schema is `Schema.String`, not a transforming codec such as `Schema.FiniteFromString`.
+- `Property 'access' is missing` at `make`: every action declares `"read"` or `"write"`. There is no default.
+- A tool shows `readOnlyHint: false` for a read: the action sets `mcp: { readOnly: false }` explicitly, which wins over `access`.

package/docs/ActionCatalog.md

@@ -46,7 +46,8 @@ process.stdout.write(JSON.stringify(catalog, null, 2));
 - `id` is the stable `<group>.<action>` identity, equal to the HTTP operation ID.
 - Schemas describe encoded action values: the JSON on the wire, not MCP's `{ value }` envelope and not deployment URLs.
 - Each schema owns its `$defs`. Equal schema identifiers in different entries never replace each other. Recursive references stay local to their schema.
-- `errors` includes group-level errors. HTTP schema-policy errors are listed separately in `httpSchemaErrors`.
+- `errors` includes group-level errors. HTTP schema-policy errors are listed separately in `httpSchemaErrors`. Surface errors are not listed: they belong to a binding, not to the contract.
+- `access` is not in the document. It is authorization metadata for a surface's hook, and the catalog is descriptive; read it from the contract (`group.actions`) when you need it.
 - Local-only actions (`http: false`, `mcp: false`) are included. Presence in a catalog is descriptive. It is not authorization, tool publication, or proof that a route is mounted. The host decides what to publish.
 - The package adds no search, no catalog HTTP endpoint, and no TypeScript code generation.
 

package/docs/ActionCli.md

@@ -9,25 +9,30 @@ nothing is fetched over HTTP.
 import * as ActionCli from "@gjermundgaraba/effect-actions/ActionCli";
 
 /** One explicitly selected action. */
-const command: <G, Name extends G["actions"][number]["name"], H, EX, RX, Parameters = never>(
+const command: <G, Name extends G["actions"][number]["name"], H, EX, RX, EB, RB, Parameters = never>(
   app: Implementation<G, H, EX, RX>,
   name: Name,
-  options?: Options<SuccessType, Parameters>,
-) => Command.Command<string, never, {}, EX | SchemaError | DeclaredErrors, Exclude<RX | HandlerContext, Scope>>;
+  options?: Options<SuccessType, EB, RB, Parameters>,
+) => Command.Command<string, never, {}, EX | EB | SchemaError | DeclaredErrors, Exclude<RX | RB | HandlerContext, Scope>>;
 
 /** Every action of the group, including local-only ones, under the group name. */
-const group: <G, H, EX, RX>(
+const group: <G, H, EX, RX, EB, RB>(
   app: Implementation<G, H, EX, RX>,
-  options?: GroupOptions,
-) => Command.Command<string, {}, {}, EX | SchemaError | DeclaredErrors, ...>;
+  options?: GroupOptions<EB, RB>,
+) => Command.Command<string, {}, {}, EX | EB | SchemaError | DeclaredErrors, ...>;
 
-interface GroupOptions {
+/** The hook both projections accept. A CLI encodes nothing, so it declares no errors. */
+interface BeforeOptions<EB, RB> {
+  readonly before?: (action: Action.Any) => Effect.Effect<void, EB, RB>;
+}
+
+interface GroupOptions<EB, RB> extends BeforeOptions<EB, RB> {
   readonly name?: string; // override the group command name
 }
 
-type Options<Output, Parameters extends Command.Command.Config = never> =
-  | JsonOptions<Output>
-  | ParametersOptions<Output, Parameters>;
+type Options<Output, EB, RB, Parameters extends Command.Command.Config = never> =
+  | (JsonOptions<Output> & BeforeOptions<EB, RB>)
+  | (ParametersOptions<Output, Parameters> & BeforeOptions<EB, RB>);
 
 interface JsonOptions<Output> {
   readonly name?: string; // override the command name; default is the action name
@@ -49,21 +54,27 @@ import { Console, Effect, Logger } from "effect";
 import { Command, Flag } from "effect/unstable/cli";
 import { NodeRuntime, NodeServices } from "@effect/platform-node";
 import * as ActionCli from "@gjermundgaraba/effect-actions/ActionCli";
+import { actors, authorize, CurrentActor } from "./auth.js";
 import { UserApp } from "./handlers.js";
 import { Users } from "./users.js";
 
 // Explicit syntax: `double --value 21`. No `--input` on this command.
+// The CLI binds the same hook as the servers; a local caller is not trusted more.
 const command = ActionCli.command(UserApp, "double", {
   parameters: { value: Flag.String("value") },
   input: ({ value }) => ({ value }),
+  before: authorize,
 });
 
 // Default syntax for a whole group: `users double --input '{"value":"21"}'`.
-const all = ActionCli.group(UserApp);
+const all = ActionCli.group(UserApp, { before: authorize });
 
 Command.runWith(command, { version: "0.1.0" })(process.argv.slice(2)).pipe(
   Effect.tapCause((cause) => Console.error(cause)),
   Effect.provideService(Logger.LogToStderr, true),
+  // The hook runs here too, so a local caller supplies the identity it reads
+  // exactly as HTTP middleware does for a request.
+  Effect.provideService(CurrentActor, actors.alice),
   Effect.provide(Users.layerMemory),
   Effect.provide(NodeServices.layer),
   NodeRuntime.runMain({ disableErrorReporting: true }),
@@ -80,6 +91,8 @@ Command.runWith(command, { version: "0.1.0" })(process.argv.slice(2)).pipe(
 - Output is validated and encoded before printing. Default output is JSON. `render(decoded)` gives human output; `--json` selects JSON again. Rendering cannot bypass validation.
 - Explicit flag names must not collide with the renderer's `--json` flag. A payload field named `json` is ordinary data; only the flag name is reserved.
 - Each invocation acquires the implementation in a scope and releases it after the call. Domain services and authority come from the host's provided layers. There is no HTTP fallback.
+- `before` runs before the selected handler, on `command` and on every subcommand of `group`. Its failure joins the command's error channel and its services are the caller's to provide, so a local CLI supplies the identity the hook reads exactly as HTTP middleware does. A CLI is not a trusted bypass.
+- The CLI declares no `errors`: it encodes nothing, so a refusal is simply a typed failure of the command effect. The native parser also decodes `--input` before the command runs, so unlike HTTP the hook runs after input decoding.
 - Group commands use the default JSON syntax. For a custom tree, compose individual `command` results with native `Command` combinators.
 
 ## Failure modes
@@ -88,4 +101,5 @@ Command.runWith(command, { version: "0.1.0" })(process.argv.slice(2)).pipe(
 - Command rejects `--input`: the command was built with `parameters`. Use its flags.
 - Type error: `name` is not an action of the group. Check `group.actions` names, not MCP tool names.
 - Handler cannot find a service: provide its Layer to the runtime (`Effect.provide`) before `runMain`. The command does not supply services.
+- A command requires a request-identity tag no handler yields: the `before` hook yields it. Provide it, or build the command without a hook for local use.
 - `--json` flag conflict at definition: rename the native flag; the config property can keep its name.

package/docs/ActionGroup.md

@@ -2,6 +2,7 @@
 
 A named set of actions. The group is what adapters serve, what clients are grouped by, and
 what `implement` binds handlers to. Shared errors and the HTTP schema-error policy live here.
+The pre-handler hook does not: each surface binds its own (see [guarantees.md](guarantees.md)).
 
 ## API
 
@@ -39,6 +40,13 @@ class Implementation<G, H, EX, RX> {
   readonly group: G;
   get build(): Effect.Effect<H, EX, RX | Scope.Scope>;
 }
+
+/** Every action of the supplied groups, keyed `<group>.<action>`. */
+function contracts<const Groups extends ReadonlyArray<Group>>(
+  ...groups: Groups
+): Contracts<Groups>;
+
+type Contracts<Groups>; // { "users.getUser": typeof GetUser, "users.renameUser": ... }
 ```
 
 `HandlersFrom<Actions>` is `{ [action name]: Handler<Action, R> }`, one key per action,
@@ -50,7 +58,7 @@ all required.
 import { Effect, Schema } from "effect";
 import type { HttpApiError } from "effect/unstable/httpapi";
 import * as ActionGroup from "@gjermundgaraba/effect-actions/ActionGroup";
-import { Forbidden, authorize, CurrentActor } from "./auth.js";
+import { CurrentActor } from "./auth.js";
 import { GetUser, RenameUser, WhoAmI } from "./contracts.js";
 import { Users } from "./users.js";
 
@@ -74,33 +82,24 @@ const schemaError = {
       : new InvalidRequest({ message: "The request does not match the action's input." }),
 };
 
-// `Forbidden` is declared once and joins every action's errors.
 export const UserActions = ActionGroup.make(
-  { name: "users", errors: [Forbidden], schemaError },
+  { name: "users", schemaError },
   GetUser,
   RenameUser,
   WhoAmI,
 );
 
 // Build-time services (Users) are yielded in the builder, once per adapter layer.
-// Request-time services (CurrentActor) are yielded inside handlers.
+// Request-time services (CurrentActor) are yielded inside handlers. Authorization
+// is not here: each adapter binds one `before` hook for every group it serves.
 export const UserApp = UserActions.implement(
   Effect.gen(function* () {
     const users = yield* Users;
 
     return {
-      getUser: ({ id }) =>
-        Effect.gen(function* () {
-          const actor = yield* authorize("users:read");
-
-          return yield* users.get(actor.tenantId, id);
-        }),
+      getUser: ({ id }) => Effect.flatMap(CurrentActor, (actor) => users.get(actor.tenantId, id)),
       renameUser: ({ id, name }) =>
-        Effect.gen(function* () {
-          const actor = yield* authorize("users:write");
-
-          return yield* users.rename(actor, id, name);
-        }),
+        Effect.flatMap(CurrentActor, (actor) => users.rename(actor, id, name)),
       whoAmI: () => Effect.map(CurrentActor, ({ id, tenantId }) => ({ id, tenantId })),
     };
   }),
@@ -108,17 +107,22 @@ export const UserApp = UserActions.implement(
 
 // No build-time services: pass the record directly.
 export const MathApp = MathActions.implement({ double: ({ value }) => Effect.succeed(value * 2) });
+
+// One typed map of every contract, keyed "<group>.<action>".
+export const contracts = ActionGroup.contracts(UserActions, MathActions);
+const renames: "renameUser" = contracts["users.renameUser"].name;
 ```
 
 ## Rules
 
 - `name` matches `[A-Za-z0-9_-]+` and must be unique within one `ActionHttp.make`. Action names must be unique within the group. MCP tool names must be unique within the group and within each Toolkit or MCP projection that serves it. Duplicates fail at `make`.
-- Group `errors` are appended to each action's own `errors`, so every handler of the group may fail with them.
-- `implement` takes a complete record or an Effect producing one. The record must have exactly one handler per action; a missing key is a compile error.
+- Group `errors` are appended to each action's own `errors`, so every handler of the group may fail with them. A failure that only the surface produces belongs on the adapter instead (`ActionHttp.make`'s `errors`, `ActionMcp`'s and `ActionToolkit`'s `errors`), not here.
+- `implement` takes a complete record or an Effect producing one. The record must have exactly one handler per action; a missing key is a compile error. It takes nothing else.
 - The builder Effect runs once per adapter layer that serves the implementation, in that layer's scope. An implementation served by HTTP and MCP is built twice. Acquire shared state in a Layer you provide to the adapters, not in the builder.
 - Services yielded in the builder are build-time requirements (`RX`). Services yielded in a handler are request-time requirements (`R` of the handler). Adapters keep these separate in their types. Use distinct tags for each kind; never provide a request-identity tag at startup (see [guarantees.md](guarantees.md)).
 - `Implementation` is nominal. Spreading its properties does not produce an implementation. Each `implement` call is a separate binding.
-- `build` exists for direct handler tests under `Effect.scoped`. It bypasses transport validation and is not a substitute for adapter tests. There is no public handler service or Layer.
+- `build` exists for direct handler tests under `Effect.scoped`. It bypasses transport validation and the hook, and is not a substitute for adapter tests. There is no public handler service or Layer.
+- `contracts(...groups)` returns one record keyed `<group>.<action>`, with each action's exact contract type. Duplicate group names throw. Use it where routes, tools, jobs or commands must name an action: the key set is derived, so an added action cannot be missed.
 
 ### Schema-error policy
 
@@ -130,6 +134,7 @@ export const MathApp = MathActions.implement({ double: ({ value }) => Effect.suc
 - The policy runs only on the server. Client-side codec failures stay `SchemaError`.
 - HTTP decodes with `errors: "all"`, so `cause` carries every issue. Issues never retain the rejected values.
 - Groups served by one adapter may have different policies; each action answers with its own group's.
+- A `before` hook refuses before decoding, so a refused request never reaches the policy.
 - Domain errors, defects, interruptions, and protocol errors are not remapped. An unencodable declared error is a defect. A broken policy error is not recursively remapped.
 
 ## Failure modes
@@ -137,5 +142,7 @@ export const MathApp = MathActions.implement({ double: ({ value }) => Effect.suc
 - Throws at `make`: duplicate action name, duplicate MCP tool name, invalid group name.
 - `Property 'x' is missing in type` at `implement`: the record lacks a handler for action `x`.
 - Handler compiles but returns an error not in `errors`: type error on the handler's error channel. Declare it on the action or the group.
+- `Expected 1 arguments, but got 2` at `implement`: the second options object is gone. Move `before` to the adapter that serves the group.
 - `map` is not typed from `errors` when declared as a standalone constant: annotate its parameter as `HttpApiError.HttpApiSchemaError` (type import from `effect/unstable/httpapi`).
 - A service is resolved once and shared across requests when it should be per request: it was yielded in the builder. Move the `yield*` into the handler.
+- `Duplicate contract group` thrown by `contracts`: two groups share a name, so their keys would collide. Rename one.