@gjermundgaraba/effect-actions 0.3.0 → 0.4.1

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.d.mts

@@ -9,40 +9,31 @@ type ErasedHandler<R> = {
 }["handle"];
 /** An adapter's erased view of a record of handlers with request requirements `R`. */
 export type Handlers<R> = Readonly<Record<string, ErasedHandler<R>>>;
-/**
- * An adapter's erased view of the pre-handler hook. It sees the selected action
- * contract, so a group-wide policy reads `access` rather than the action name.
- */
-export type Before<R> = (action: Any) => Effect.Effect<void, ErasedValue, R>;
 /** Per-request requirements of the handler selected by an action name. */
 export type HandlerContext<H, Name extends keyof H> = H[Name] extends ((input: never) => Effect.Effect<infer _A, infer _E, infer R>) ? R : never;
 /** The union of per-request requirements declared by a handler record. */
 export type HandlersContext<H> = { readonly [K in keyof H]: HandlerContext<H, K>; }[keyof H];
 /**
- * An acquired handler record for a group, with the hook that runs before each of them.
+ * An acquired handler record for a group.
  *
  * The private field makes this class nominal: a structurally similar object,
  * including one made by spreading an implementation, is not an implementation.
  */
-export declare class Implementation<G extends Actions, H, EX, RX, RB> {
+export declare class Implementation<G extends Actions, H, EX, RX> {
   #private;
   /** The group whose exact handler record was built. */
   readonly group: G;
   private constructor();
   /** Acquire the exact handler record in the adapter layer's scope. */
   get build(): Effect.Effect<H, EX, RX | Scope.Scope>;
-  /** Runs once per invocation, before the selected handler, on every surface. */
-  get before(): Before<RB> | undefined;
-  static make<G extends Actions, H, EX, RX, RB>(group: G, build: Effect.Effect<H, EX, RX | Scope.Scope>, before: Before<RB> | undefined): Implementation<G, H, EX, RX, RB>;
+  static make<G extends Actions, H, EX, RX>(group: G, build: Effect.Effect<H, EX, RX | Scope.Scope>): Implementation<G, H, EX, RX>;
 }
 /** Any nominal implementation of `G`, with its record and channels erased. */
-export type AnyImplementation<G extends Actions = Actions> = Implementation<G, any, any, any, any>;
-/** Pre-handler requirements of one implementation, or of a union of them. */
-export type BeforeContext<App> = App extends Implementation<any, any, any, any, infer RB> ? RB : never;
+export type AnyImplementation<G extends Actions = Actions> = Implementation<G, any, any, any>;
 /** Per-request requirements of one implementation, or of a union of them. */
-export type RequestContext<App> = App extends Implementation<any, infer H, any, any, infer RB> ? HandlersContext<H> | RB : never;
+export type RequestContext<App> = App extends Implementation<any, infer H, any, any> ? HandlersContext<H> : never;
 /** Handler-acquisition failures of one implementation, or of a union of them. */
-export type BuildError<App> = App extends Implementation<any, any, infer EX, any, any> ? EX : never;
+export type BuildError<App> = App extends Implementation<any, any, infer EX, any> ? EX : never;
 /** Handler-acquisition requirements of one implementation, or of a union of them. */
-export type BuildContext<App> = App extends Implementation<any, any, any, infer RX, any> ? RX : never;
+export type BuildContext<App> = App extends Implementation<any, any, any, infer RX> ? RX : never;
 //#endregion

package/dist/internal/implementation.mjs

@@ -1,7 +1,7 @@
 import { Effect } from "effect";
 //#region src/internal/implementation.ts
 /**
-* An acquired handler record for a group, with the hook that runs before each of them.
+* An acquired handler record for a group.
 *
 * The private field makes this class nominal: a structurally similar object,
 * including one made by spreading an implementation, is not an implementation.
@@ -9,28 +9,22 @@ import { Effect } from "effect";
 var Implementation = class Implementation {
 	group;
 	#build;
-	#before;
-	constructor(group, build, before) {
+	constructor(group, build) {
 		this.group = group;
 		this.#build = build;
-		this.#before = before;
 	}
 	/** Acquire the exact handler record in the adapter layer's scope. */
 	get build() {
 		return this.#build;
 	}
-	/** Runs once per invocation, before the selected handler, on every surface. */
-	get before() {
-		return this.#before;
-	}
-	static make(group, build, before) {
-		return new Implementation(group, build, before);
+	static make(group, build) {
+		return new Implementation(group, build);
 	}
 };
 /**
 * Select and invoke a handler after an adapter has selected a concrete action.
-* The pre-handler hook runs first, inside the action's span, so every surface
-* applies it exactly once and its failures are declared errors of the 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.
 */
@@ -38,8 +32,8 @@ const dispatch = (group, action, handlers, before) => {
 	const handle = handlers[action.name];
 	if (handle === void 0) throw new Error(`Missing handler: ${action.name}`);
 	return (input) => {
-		const run = () => before === void 0 ? handle(input) : Effect.flatMap(before(action), () => handle(input));
-		return Effect.withSpan(Effect.suspend(run), `${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, app.before)(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,20 +11,20 @@ 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>;
 
 /** What the action does to its resource. Authorization metadata, not an MCP hint. */
 type Access = "read" | "write";
 
-interface Options<Input, Output, Errors, Http, Mcp> {
+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?: Access; // defaults to "write"
+  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
 }
@@ -37,13 +37,13 @@ interface McpOptions {
   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: Access; // resolved
+  readonly access: Acc; // the literal it was declared with
   readonly http: Http;
   readonly mcp: false | { name; readOnly; destructive; idempotent; openWorld }; // resolved
 }
@@ -68,7 +68,7 @@ export class UserNotFound extends Schema.TaggedError<UserNotFound>()(
   { httpApiStatus: 404 },
 ) {}
 
-// `access: "read"` states the fact once: it is what the group's `before` hook
+// `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.",
@@ -79,8 +79,7 @@ export const GetUser = Action.make("getUser", {
   mcp: { name: "get_user" },
 });
 
-// A write. `access` defaults to "write", but say it: the default is a fallback,
-// not a statement, and an unclassified action is the one a reviewer must check.
+// 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 }),
@@ -121,7 +120,7 @@ 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 defaults to `"write"`, so an action nobody classified is treated as the dangerous one. It is authorization metadata for a group's `before` hook (see [ActionGroup.md](ActionGroup.md)); the library itself authorizes nothing and no adapter reads it.
+- `access` is `"read"` or `"write"` and is required. `make` also checks it at runtime, so a caller the compiler never sees cannot define an action no rule classifies. 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.
@@ -133,9 +132,9 @@ export const Double = Action.make("double", {
 
 ## Failure modes
 
-- Throws at `make`: invalid name, name `then`, `mcp.name` longer than 128 characters or not matching the pattern.
+- Throws at `make`: invalid name, name `then`, an `access` that is neither `"read"` nor `"write"`, `mcp.name` longer than 128 characters or not matching the pattern.
 - 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`.
-- A read action is refused by an authorization hook that reads `access`: `access` was omitted, so it defaulted to `"write"`. Declare it.
+- `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

@@ -20,7 +20,6 @@ interface Entry {
   readonly group: string;
   readonly name: string;
   readonly description: string;
-  readonly access: "read" | "write"; // resolved; "write" unless the contract says otherwise
   readonly http: boolean;
   readonly mcp: false | { name; readOnly; destructive; idempotent; openWorld };
   readonly input: JsonSchema.JsonSchema;
@@ -47,8 +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`.
-- `access` is the action's resolved authorization metadata, not a permission. A reader may use it to tell reads from writes; it grants nothing and names no scope.
+- `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, RB, Parameters = never>(
-  app: Implementation<G, H, EX, RX, RB>,
+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 | RB | 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, RB>(
-  app: Implementation<G, H, EX, RX, RB>,
-  options?: GroupOptions,
-) => Command.Command<string, {}, {}, EX | SchemaError | DeclaredErrors, ...>;
+const group: <G, H, EX, RX, EB, RB>(
+  app: Implementation<G, H, EX, RX>,
+  options?: GroupOptions<EB, RB>,
+) => Command.Command<string, {}, {}, EX | EB | SchemaError | DeclaredErrors, ...>;
+
+/** 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 {
+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,24 +54,26 @@ 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, CurrentActor } from "./auth.js";
+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 group's `before` hook runs here too, so a local caller supplies the
-  // identity it reads exactly as HTTP middleware does for a request.
+  // 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),
@@ -84,7 +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.
-- The group's pre-handler hook runs here too, before every command's handler. 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.
+- `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
@@ -93,5 +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 group's `before` hook yields it. Provide it, or bind a separate implementation without the hook for local use.
+- 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

@@ -1,8 +1,8 @@
 # ActionGroup
 
 A named set of actions. The group is what adapters serve, what clients are grouped by, and
-what `implement` binds handlers to. Shared errors, the pre-handler hook, and the HTTP
-schema-error policy live here.
+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
 
@@ -12,7 +12,7 @@ import * as ActionGroup from "@gjermundgaraba/effect-actions/ActionGroup";
 function make<Name, Actions, Errors = [], PolicyErrors = []>(
   options: Options<Name, Errors, PolicyErrors>,
   ...actions: Actions
-): Group<Name, WithErrors<Actions, Errors>, PolicyErrors, Errors>;
+): Group<Name, WithErrors<Actions, Errors>, PolicyErrors>;
 
 interface Options<Name, Errors, PolicyErrors> {
   readonly name: Name; // HttpApiGroup identifier, OpenAPI tag, operation-ID prefix
@@ -25,34 +25,28 @@ interface SchemaErrorPolicy<Errors extends ReadonlyArray<Codec>> {
   readonly map: (failure: HttpApiError.HttpApiSchemaError) => Errors[number]["Type"];
 }
 
-interface ImplementOptions<Errors, RB> {
-  /** Runs before every handler, on every surface. May fail only with the group's `errors`. */
-  readonly before: (action: Action.Any) => Effect.Effect<void, Errors[number]["Type"], RB>;
-}
-
-interface Group<Name, Actions, PolicyErrors, Errors> {
+interface Group<Name, Actions, PolicyErrors> {
   readonly name: Name;
   readonly actions: Actions;
   readonly schemaError: SchemaErrorPolicy<PolicyErrors> | undefined;
   /** Bind every handler at once; build-time services resolve once per adapter layer. */
-  readonly implement: <H extends HandlersFrom<Actions>, EX = never, RX = never, RB = never>(
+  readonly implement: <H extends HandlersFrom<Actions>, EX = never, RX = never>(
     build: H | Effect.Effect<H, EX, RX>,
-    options?: ImplementOptions<Errors, RB>,
-  ) => Implementation<
-    Group<Name, Actions, PolicyErrors, Errors>,
-    H,
-    EX,
-    Exclude<RX, Scope.Scope>,
-    RB
-  >;
+  ) => Implementation<Group<Name, Actions, PolicyErrors>, H, EX, Exclude<RX, Scope.Scope>>;
 }
 
 /** Nominal. `group` is the bound contract; `build` acquires the handler record in a scope. */
-class Implementation<G, H, EX, RX, RB> {
+class Implementation<G, H, EX, RX> {
   readonly group: G;
   get build(): Effect.Effect<H, EX, RX | Scope.Scope>;
-  get before(): ((action: Action.Any) => Effect.Effect<void, unknown, RB>) | undefined;
 }
+
+/** 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,
@@ -64,8 +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 type * as Action from "@gjermundgaraba/effect-actions/Action";
-import { Forbidden, CurrentActor } from "./auth.js";
+import { CurrentActor } from "./auth.js";
 import { GetUser, RenameUser, WhoAmI } from "./contracts.js";
 import { Users } from "./users.js";
 
@@ -89,25 +82,16 @@ 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,
 );
 
-// One rule for the whole group, read from each contract's own `access`. It runs
-// on HTTP, MCP, Toolkit and CLI alike, so no handler contains authorization code.
-const authorize = Effect.fn("authorize")(function* (action: Action.Any) {
-  const permission = action.access === "read" ? "users:read" : "users:write";
-  const actor = yield* CurrentActor;
-
-  if (!actor.permissions.includes(permission)) return yield* new Forbidden({ permission });
-});
-
 // Build-time services (Users) are yielded in the builder, once per adapter layer.
-// Request-time services (CurrentActor) are yielded inside handlers and in `before`.
+// 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;
@@ -119,31 +103,26 @@ export const UserApp = UserActions.implement(
       whoAmI: () => Effect.map(CurrentActor, ({ id, tenantId }) => ({ id, tenantId })),
     };
   }),
-  { before: authorize },
 );
 
 // 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.
-
-### Pre-handler hook
-
-- `implement(handlers, { before })` binds one hook to the whole implementation. It runs once per invocation, immediately before the selected handler, on **every** surface: `ActionHttp`, `ActionMcp.layerHttp`, `ActionMcp.layerStdio`, `ActionToolkit`, and `ActionCli`. There is no surface that skips it and no per-action opt-out.
-- It receives the selected action contract (`Action.Any`), so a policy reads `action.access`, `action.name` or `action.mcp` instead of a hand-maintained list. Write authorization against `access`.
-- It may fail only with the group's own `errors`, because those are the failures every action of the group declares. A hook that fails with anything else is a compile error; a group with no `errors` has no failure a hook could use. Its failure is encoded exactly like a handler's: the error's `httpApiStatus` on HTTP, an `isError` tool result on MCP.
-- Services it yields are request-time requirements, like a handler's, and they join the adapter's request context. A local caller (`ActionCli`, `ActionToolkit`, stdio) supplies them itself.
-- It runs inside the `<group>.<action>` span, before the handler. When it fails, the handler never runs.
-- It is not authentication. Establish identity in middleware, then let the hook authorize what that identity may do.
+- `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
 
@@ -155,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
@@ -162,8 +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.
-- Type error on `before`'s error channel: the hook fails with an error the group does not declare. Add it to the group's `errors` so every action declares it.
-- `Type 'X' is not assignable to type 'never'` on `before` in a group without `errors`: the group declares no shared failure. Declare one.
-- The hook does not run for an action: it cannot happen through an adapter. A handler invoked directly through `build` is not dispatched and is not hooked; use an adapter, or `ActionCli`, in tests that must exercise the policy.
+- `Duplicate contract group` thrown by `contracts`: two groups share a name, so their keys would collide. Rename one.