@gjermundgaraba/effect-actions 0.1.0-rc.0 → 0.1.0-rc.1

package/README.md

@@ -2,17 +2,35 @@
 
 Define an Effect action once, implement it once, expose it over **HTTP and MCP**.
 
-**Experimental release candidate.** The repository currently uses Effect snapshot
-[`4e4a3a6`](https://pkg.pr.new/Effect-TS/effect/effect@4e4a3a6). The MCP adapter
-requires APIs missing from published `4.0.0-rc.115`, despite that being the current
-peer declaration. Until these versions are aligned, use the pinned snapshot;
-the declared peer version alone is not sufficient.
+**Snapshot-dependent preview.** This release requires Effect snapshot
+[`9ad9891`](https://pkg.pr.new/Effect-TS/effect/effect@9ad9891). The published npm
+version `effect@4.0.0-rc.115` is not compatible: it lacks APIs required by the MCP
+adapter. Install both packages explicitly:
+
+```sh
+pnpm add @gjermundgaraba/effect-actions@rc \
+  'effect@https://pkg.pr.new/Effect-TS/effect/effect@9ad9891'
+```
+
+The snapshot reports version `4.0.0-rc.115`, so the package retains that nominal
+peer declaration. A semver peer cannot distinguish the snapshot from the npm
+build; satisfying the peer declaration alone does **not** ensure compatibility.
+Installation requires access to `pkg.pr.new`, not just the npm registry.
+
+For Node server wiring, use the matching platform snapshot too:
+
+```sh
+pnpm add '@effect/platform-node@https://pkg.pr.new/Effect-TS/effect/@effect/platform-node@9ad9891'
+```
 
 ## Quickstart
 
 ```ts
 import { Effect, Layer, Schema } from "effect";
-import { Action, ActionGroup, ActionHttp, ActionMcp } from "@gjermundgaraba/effect-actions";
+import * as Action from "@gjermundgaraba/effect-actions/Action";
+import * as ActionGroup from "@gjermundgaraba/effect-actions/ActionGroup";
+import * as ActionHttp from "@gjermundgaraba/effect-actions/ActionHttp";
+import * as ActionMcp from "@gjermundgaraba/effect-actions/ActionMcp";
 
 const Greet = Action.make("greet", {
   description: "Greet someone by name.",
@@ -21,36 +39,42 @@ const Greet = Action.make("greet", {
   mcp: { readOnly: true },
 });
 
-export const Actions = ActionGroup.make(Greet);
+export const Actions = ActionGroup.make({ name: "greetings" }, Greet);
+
+export const Http = ActionHttp.make({ apiPath: "/api/actions" }, Actions);
+
 const app = Actions.implement({
   greet: ({ name }) => Effect.succeed(`Hello, ${name}!`),
 });
 
 export const routes = Layer.mergeAll(
-  ActionHttp.layer(app, {
-    apiPath: "/api/actions",
-    openapiPath: "/openapi.json",
-  }),
-  ActionMcp.layer(app, { name: "greetings", version: "1.0.0", path: "/mcp" }),
+  Http.layer(app),
+  ActionMcp.layer({ name: "greetings", version: "1.0.0", path: "/mcp" }, app),
 );
 ```
 
-Serve `routes` with Effect's `HttpRouter`. This creates `POST /api/actions/greet`,
-`GET /openapi.json`, and an MCP endpoint at `/mcp`. The HTTP response is
-`"Hello, Ada!"`; MCP returns `structuredContent: { value: "Hello, Ada!" }`.
+Serve `routes` with Effect's `HttpRouter`. This creates `POST /api/actions/greet` and an
+MCP endpoint at `/mcp`. The HTTP response is `"Hello, Ada!"`; MCP returns
+`structuredContent: { value: "Hello, Ada!" }`.
 See [examples/server.ts](examples/server.ts) for Node server wiring and the
 [authenticated demo](examples/README.md) for a runnable application.
 
 ### Contracts
 
-- `input` defaults to `Action.NoInput` for actions without arguments.
-- `error` is a list of failure schemas, defaulting to none. Each schema retains
+- Omit `input` for an action without arguments.
+- `errors` is a list of failure schemas, defaulting to none. Each schema retains
   its own `httpApiStatus` annotation.
+- A group's `errors` are added to every one of its actions, so a shared set, such as
+  authorization failures, is declared once. Its `schemaError` policy decides how both
+  transports answer failed decoding or encoding; see
+  [schema-error policies](docs/behavior.md#schema-error-policies).
 - Actions default to both transports; use `http: false` or `mcp: false` to opt out.
+  An action exposed on neither is rejected.
 - MCP input must have an object-root JSON Schema; declared errors must encode to
   objects. The MCP adapter checks this at Layer construction. HTTP allows scalars.
 - `mcp.name` overrides the tool name. `destructive` defaults to `!readOnly`.
 - Schemas must be service-free. Handlers may require services.
+- The group name is the OpenAPI tag and operation-ID prefix (`greetings.greet`).
 
 ## HTTP client
 
@@ -59,37 +83,84 @@ Save the quickstart above as `quickstart.ts`. Once its routes are served:
 ```ts
 import { Effect } from "effect";
 import { FetchHttpClient } from "effect/unstable/http";
-import { ActionHttp } from "@gjermundgaraba/effect-actions";
-import { Actions } from "./quickstart.js";
+import { Http } from "./quickstart.js";
 
 export const greeting = Effect.gen(function* () {
-  const client = yield* ActionHttp.client(Actions, {
-    apiPath: "/api/actions",
-    baseUrl: "http://127.0.0.1:3000",
-  });
+  const client = yield* Http.client({ baseUrl: "http://127.0.0.1:3000" });
+
   return yield* client.greet({ name: "Ada" });
 }).pipe(Effect.provide(FetchHttpClient.layer));
 ```
 
 Run `greeting` with `Effect.runPromise`. Methods take decoded inputs and return
-decoded results; MCP-only actions are excluded. Authentication
-headers can be added with `transformClient`. See [client details](docs/behavior.md#http-client-details)
+decoded results; MCP-only actions are excluded. `ActionHttp.make` binds the mount path the
+server and its clients must agree on, so `client` accepts only connection options. Authentication headers can be added with
+`transformClient`. See [client details](docs/behavior.md#http-client-details)
 for error types, optional inputs, and native grouped clients.
 
+## Multiple groups
+
+An application can split its contracts and handlers into groups without splitting its
+endpoints. Configuration comes first, then the groups or implementations:
+
+```ts
+const Http = ActionHttp.make({ apiPath: "/api/actions" }, PublicActions, UserActions);
+
+const routes = Layer.mergeAll(
+  Http.layer(PublicApp),
+  Http.layer(UserApp).pipe(Layer.provide(authentication.layer)),
+  ActionMcp.layer({ name: "my-app", version: "1.0.0", path: "/mcp" }, UserApp, AuditApp),
+);
+```
+
+- **One layer per group.** `Http.layer(app)` registers the routes of one group, and router
+  middleware provided to a layer applies to that layer alone: above, only the user group
+  requires authentication. A group that is never mounted has no routes.
+- **Each adapter reads only what it serves.** A group without HTTP actions registers nothing
+  and is not built by `Http.layer`, nor one without tools by `ActionMcp.layer`.
+- **Names.** Routes and client methods are flat (`POST /api/actions/<action>`,
+  `client.<action>()`), so group names and HTTP action names must be unique within one
+  `ActionHttp.make`, and tool names within one `ActionMcp.layer`. Duplicates throw at
+  construction; neither adapter looks at the other's names.
+- **MCP middleware is per endpoint.** An MCP endpoint is one route, so middleware provided
+  to `ActionMcp.layer`, authentication included, covers all of its tools. Handlers can still
+  authorize each tool differently. Only tools that need different middleware, such as none
+  at all, need their own endpoint: one `ActionMcp.layer` per `path`.
+
+Each group is its own native `HttpApiGroup`, so a host can also combine separately made
+`Http.api` values with `HttpApi.addHttpApi`. See [examples/app.ts](examples/app.ts).
+
+## Serving the document
+
+`Http.api` is a native `HttpApi`, carrying every route, description, declared error and
+policy error. Documents and documentation UIs are therefore Effect's own:
+
+```ts
+import { HttpRouter, HttpServerResponse } from "effect/unstable/http";
+import { HttpApiScalar, HttpApiSwagger, OpenApi } from "effect/unstable/httpapi";
+
+const documentation = Layer.mergeAll(
+  HttpRouter.add("GET", "/openapi.json", HttpServerResponse.jsonUnsafe(OpenApi.fromApi(Http.api))),
+  HttpApiSwagger.layer(Http.api, { path: "/docs" }),
+  HttpApiScalar.layer(Http.api, { path: "/reference" }),
+);
+```
+
+Each is an ordinary route layer, so it takes whatever middleware it is provided. The same
+value gives Effect's grouped client: `HttpApiClient.make(Http.api)`.
+
 ## Adapter options
 
-| API                          | Options                                                                                 |
-| ---------------------------- | --------------------------------------------------------------------------------------- |
-| `ActionHttp.layer`           | `apiPath`, `openapiPath`, `schemaError`                                                 |
-| `ActionHttp.api` / `openapi` | `apiPath`, `schemaError`                                                                |
-| `ActionHttp.client`          | `apiPath`, `schemaError`, `baseUrl`, `transformClient`, `transformResponse`             |
-| `ActionMcp.layer`            | `name`, `version`, `path`, `protocols`, `allowedOrigins`, `instructions`, `schemaError` |
+| API                                   | Options                                                                  |
+| ------------------------------------- | ------------------------------------------------------------------------ |
+| `ActionGroup.make(options, …actions)` | `name`, `errors`, `schemaError`                                          |
+| `ActionHttp.make(options, …groups)`   | `apiPath`                                                                |
+| `Http.layer(app)`                     | None                                                                     |
+| `Http.client(options?)`               | `baseUrl`, `transformClient`, `transformResponse`                        |
+| `ActionMcp.layer(options, …apps)`     | `name`, `version`, `path`, `protocols`, `allowedOrigins`, `instructions` |
 
-`apiPath`, `openapiPath` (on `layer` / `configure`), and MCP `path` are required —
-the library has no defaults. `ActionHttp.configure(options)` binds HTTP configuration
-for its `layer`, `api`, `openapi`, and `client` methods. Configured clients accept
-only connection options. Set `openapiPath: false` when the host serves a combined
-document.
+`apiPath` and MCP `path` have no defaults. `Http` has three members: `api`, `layer` and
+`client`.
 
 See [adapter behavior](docs/behavior.md) for shared schema-error policies,
 dependency lifetimes, wire formats, and MCP protocol support.
@@ -118,11 +189,13 @@ vp run example
 ```
 
 `vp run dev` watches the library build. `vp check` also verifies the compile-time
-assertions in `tests/types.ts`. Tests cover both transports, official MCP clients,
+assertions in `tests/types.spec.ts`. Tests cover both transports, official MCP clients,
 context isolation, schema-error policies, and cancellation.
 
-`vp run build` emits ESM and declarations into `dist/`. Public entry points are the
-package root, `/Action`, `/ActionGroup`, `/http`, `/mcp`, `/authentication`, `/testing`, and `/testing/client`.
+`vp run build` emits ESM and declarations into `dist/`. The entry points are one subpath per
+module: `/Action`, `/ActionGroup`, `/ActionHttp`, `/ActionMcp`, `/Authentication`, `/Testing`,
+and `/TestingClient`. There is no package root, so a contracts-only or browser bundle never
+loads the MCP server or the optional client peer.
 `vp run test:package` builds and checks a tarball in an isolated consumer using the pinned
 Effect snapshot; it does not establish compatibility with the published peer.
 
@@ -142,7 +215,7 @@ Use `.combine(...)` with middleware that provides them. Acquired resources stay
 until the request scope closes. Downstream action errors are handled by their transport,
 not serialized as authentication failures.
 
-`ActionMcp.protectedResource({ resource, authorizationServers, scopesSupported })`
+`Authentication.protectedResource({ resource, authorizationServers, scopesSupported })`
 returns `{ layer, metadataUrl, challenge }`. Mount its public `layer` separately from
 protected routes. It publishes [RFC 9728 metadata](https://www.rfc-editor.org/rfc/rfc9728.html)
 at `/.well-known/oauth-protected-resource` followed by the resource path and query. Discovery
@@ -155,16 +228,48 @@ The helper supports HTTPS URLs and loopback HTTP for development, with no creden
 or fragment. Resource identifiers may include a query; authorization-server issuers may not.
 Your application owns login, consent, and token verification.
 
-## MCP testing
+```ts
+const discovery = Authentication.protectedResource({
+  resource: "https://api.example.com/mcp",
+  authorizationServers: ["https://auth.example.com"],
+});
 
-Import `mcpRequest` from `@gjermundgaraba/effect-actions/testing`; it requires no MCP client dependency.
-Import `withMcpClient` from `@gjermundgaraba/effect-actions/testing/client` and install
-its optional peer `@modelcontextprotocol/client@^2.0.0`. Only the client entry point loads this peer.
+const authentication = Authentication.middleware(CurrentActor, {
+  authenticate,
+  errors: [Unauthenticated],
+  headers: () => ({ "www-authenticate": discovery.challenge({ error: "invalid_token" }) }),
+});
+
+const routes = Layer.mergeAll(
+  discovery.layer,
+  protectedRoutes.pipe(Layer.provide(authentication.layer)),
+);
+```
+
+## Testing
+
+Import from `@gjermundgaraba/effect-actions/Testing`; it requires no MCP client dependency.
+`withMcpClient` lives in `@gjermundgaraba/effect-actions/TestingClient` and needs the optional
+peer `@modelcontextprotocol/client@^2.0.0`. Only that entry point loads the peer.
+
+```ts
+const web = HttpRouter.toWebHandler(routes.pipe(Layer.provide(HttpServer.layerServices)));
+
+const greeting = Effect.gen(function* () {
+  const client = yield* httpClient(Http, web.handler);
+
+  return yield* client.greet({ name: "Ada" });
+});
+```
 
-- `mcpRequest(method, params?, { url, headers? })` builds a stateless 2026-07-28 request.
-  `url` is required. Caller `params._meta` fields override the default client capabilities
+- `httpClient(Http, handler, options?)` is the typed HTTP client calling a web handler in
+  memory. `options` are the client's connection options; `baseUrl` defaults to `http://localhost`.
+- `mcpRequest({ url, method, params?, headers? })` builds a stateless 2026-07-28 request.
+  `params` takes whatever `JSON.stringify` accepts, `undefined` fields included, so tests can
+  send malformed arguments.
+  Caller `params._meta` fields override the default client capabilities
   and information; application metadata is preserved. The protocol version stays pinned to
   2026-07-28 in both the request header and metadata. Metadata is merged shallowly.
-- `withMcpClient(fetch, async client => ..., { path, mode?, baseUrl?, headers? })`
-  connects the official client and closes it in a `finally` block. `path` is required.
+- `withMcpClient({ fetch, path, mode?, baseUrl?, headers? }, async client => ...)`
+  connects the official client and closes it in a `finally` block.
   `mode` defaults to `"modern"` (2026-07-28); use `"legacy"` to exercise session negotiation.

package/dist/Action-CXsfTEhx.d.mts

@@ -0,0 +1,54 @@
+import { Effect, Schema } from "effect";
+declare namespace Action_d_exports {
+  export { Action, Any, Codec, Handler, McpOptions, Options, SchemaErrorPolicy, SchemaFailure, make };
+}
+type Codec = Schema.Codec<unknown, unknown, never, never>;
+/** Failed request decoding or successful-result encoding, independent of transport terminology. */
+interface SchemaFailure {
+  readonly phase: "input" | "output";
+  /** May contain sensitive values. Do not reflect it in public error messages. */
+  readonly cause: Schema.SchemaError;
+}
+/** Pure application-owned mapping, set on a group and applied by both adapters. */
+interface SchemaErrorPolicy<Errors extends ReadonlyArray<Codec>> {
+  readonly errors: Errors;
+  readonly map: (failure: SchemaFailure) => NoInfer<Errors[number]["Type"]>;
+}
+interface McpOptions {
+  readonly name?: string;
+  readonly readOnly?: boolean;
+  /** Defaults to `!readOnly`; the MCP spec only defines it for non-read-only tools. */
+  readonly destructive?: boolean;
+}
+interface Options<Input extends Codec, Output extends Codec, Errors extends ReadonlyArray<Codec>, Http extends boolean = boolean> {
+  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;
+  readonly http?: Http;
+  readonly mcp?: false | McpOptions;
+}
+/** A pure contract: schemas and transport metadata. Implementations are bound by `ActionGroup.implement`. */
+interface Action<Name extends string, Input extends Codec, Output extends Codec, Errors extends ReadonlyArray<Codec>, Http extends boolean = boolean> {
+  readonly name: Name;
+  readonly description: string;
+  readonly input: Input;
+  readonly success: Output;
+  readonly errors: Errors;
+  readonly http: Http;
+  readonly mcp: false | {
+    readonly name: string;
+    readonly readOnly: boolean;
+    readonly destructive: boolean;
+  };
+}
+type Any = Action<string, Codec, Codec, ReadonlyArray<Codec>>;
+/** Receives decoded input; may fail only with the declared errors. */
+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. */
+declare const NoInput: Schema.$Record<Schema.String, Schema.Never>;
+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>(name: Name, options: Options<Input, Output, Errors, Http>): Action<Name, Input, Output, Errors, Http>;
+//#endregion
+export { Handler as a, SchemaErrorPolicy as c, __exportAll as d, Codec as i, SchemaFailure as l, Action_d_exports as n, McpOptions as o, Any as r, Options as s, Action as t, make as u };

package/dist/Action.d.mts

@@ -1,54 +1,2 @@
-import { Effect, Schema } from "effect";
-declare namespace Action_d_exports {
-  export { Action, Any, Codec, Handler, McpOptions, NoInput, Options, SchemaErrorPolicy, SchemaFailure, make };
-}
-export type Codec = Schema.Codec<unknown, unknown, never, never>;
-/** Failed request decoding or successful-result encoding, independent of transport terminology. */
-export interface SchemaFailure {
-  readonly phase: "input" | "output";
-  /** May contain sensitive values. Do not reflect it in public error messages. */
-  readonly cause: Schema.SchemaError;
-}
-/** Pure application-owned mapping, shared by the HTTP and MCP adapters. */
-export interface SchemaErrorPolicy<Errors extends ReadonlyArray<Codec>> {
-  readonly errors: Errors;
-  readonly map: (failure: SchemaFailure) => NoInfer<Errors[number]["Type"]>;
-}
-export interface McpOptions {
-  readonly name?: string;
-  readonly readOnly?: boolean;
-  /** Defaults to `!readOnly`; the MCP spec only defines it for non-read-only tools. */
-  readonly destructive?: boolean;
-}
-export interface Options<Input extends Codec, Output extends Codec, Errors extends ReadonlyArray<Codec>, Http extends boolean = boolean> {
-  readonly description: string;
-  /** Defaults to `NoInput`. */
-  readonly input?: Input;
-  readonly success: Output;
-  /** One schema per declared failure; each keeps its own HTTP status annotation. Defaults to none. */
-  readonly error?: Errors;
-  readonly http?: Http;
-  readonly mcp?: false | McpOptions;
-}
-/** 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> {
-  readonly name: Name;
-  readonly description: string;
-  readonly input: Input;
-  readonly success: Output;
-  readonly errors: Errors;
-  readonly http: Http;
-  readonly mcp: false | {
-    readonly name: string;
-    readonly readOnly: boolean;
-    readonly destructive: boolean;
-  };
-}
-export type Any = Action<string, Codec, Codec, ReadonlyArray<Codec>>;
-/** 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. */
-export declare const NoInput: Schema.$Record<Schema.String, Schema.Never>;
-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>(name: Name, options: Options<Input, Output, Errors, Http>): Action<Name, Input, Output, Errors, Http>;
-//#endregion
-export { Action_d_exports as t };
+import { a as Handler, c as SchemaErrorPolicy, i as Codec, l as SchemaFailure, o as McpOptions, r as Any, s as Options, t as Action, u as make } from "./Action-CXsfTEhx.mjs";
+export { Action, Any, Codec, Handler, McpOptions, Options, SchemaErrorPolicy, SchemaFailure, make };

package/dist/Action.mjs

@@ -1,14 +1,10 @@
-import { t as __exportAll } from "./rolldown-runtime-D7D4PA-g.mjs";
 import { Schema } from "effect";
 //#region src/Action.ts
-var Action_exports = /* @__PURE__ */ __exportAll({
-	NoInput: () => NoInput,
-	make: () => make
-});
 /** An empty object schema that also produces the object root MCP requires. */
 const NoInput = Schema.Record(Schema.String, Schema.Never);
 function make(name, options) {
 	if (!/^[A-Za-z][A-Za-z0-9_-]*$/.test(name)) throw new Error(`Invalid action name: ${name}`);
+	if (options.http === false && options.mcp === false) throw new Error(`Action ${name} is exposed on no transport`);
 	const readOnly = options.mcp === false ? false : options.mcp?.readOnly ?? false;
 	const mcp = options.mcp === false ? false : {
 		name: options.mcp?.name ?? name,
@@ -21,10 +17,10 @@ function make(name, options) {
 		description: options.description,
 		input: options.input ?? NoInput,
 		success: options.success,
-		errors: options.error ?? [],
+		errors: options.errors ?? [],
 		http: options.http !== false,
 		mcp
 	};
 }
 //#endregion
-export { NoInput, make, Action_exports as t };
+export { make };

package/dist/ActionGroup.d.mts

@@ -1,21 +1,29 @@
-import { Any, Handler, t as Action_d_exports } from "./Action.mjs";
-import { t as Implementation } from "./implementation-D75QAcD3.mjs";
+import { a as Handler, c as SchemaErrorPolicy, i as Codec, n as Action_d_exports, r as Any$1, t as Action } from "./Action-CXsfTEhx.mjs";
+import { i as Implementation, o as Actions } from "./implementation-DTqp_0DW.mjs";
 import { Effect, Scope } from "effect";
-declare namespace ActionGroup_d_exports {
-  export { Group, Implementation, make };
-}
-type HandlersFrom<Actions extends ReadonlyArray<Any>> = { readonly [A in Actions[number] as A["name"]]: Handler<A, any>; };
+//#region src/ActionGroup.d.ts
+type HandlersFrom<Actions extends ReadonlyArray<Any$1>> = { readonly [A in Actions[number] as A["name"]]: Handler<A, any>; };
 type HandlersContext<H> = { [K in keyof H]: H[K] extends ((input: never) => Effect.Effect<infer _A, infer _E, infer R>) ? R : never; }[keyof H];
-export interface Group<Actions extends ReadonlyArray<Any>> {
-  readonly actions: Actions;
+/** 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> ? Action<Name, Input, Output, readonly [...Own, ...Errors], Http> : never; };
+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. */
+  readonly name: Name;
+  /** Failures every action of the group may have, added to each action's own. */
+  readonly errors?: Errors;
+  /** How both transports answer failed decoding or encoding of these actions. */
+  readonly schemaError?: SchemaErrorPolicy<PolicyErrors>;
+}
+export interface Group<Name extends string, Actions$1 extends ReadonlyArray<Any$1>, PolicyErrors extends ReadonlyArray<Codec> = ReadonlyArray<Codec>> extends Actions<Name, Actions$1, PolicyErrors> {
   /**
    * Bind every handler at once. Pass an Effect to resolve build-time services
    * once (`const users = yield* Users`); services yielded inside a handler are
    * request-scoped instead. Scoped acquisition lasts for the adapter runtime.
    */
-  readonly implement: <H extends HandlersFrom<Actions>, EX = never, RX = never>(build: H | Effect.Effect<H, EX, RX>) => Implementation<Actions, HandlersContext<H>, EX, Exclude<RX, Scope.Scope>>;
+  readonly implement: <H extends HandlersFrom<Actions$1>, EX = never, RX = never>(build: H | Effect.Effect<H, EX, RX>) => Implementation<Group<Name, Actions$1, PolicyErrors>, HandlersContext<H>, NoInfer<EX>, NoInfer<Exclude<RX, Scope.Scope>>>;
 }
+export type Any = Group<string, ReadonlyArray<Any$1>>;
 /** Duplicate action and MCP names fail at definition time. */
-export declare const make: <const Actions extends ReadonlyArray<Any>>(...actions: Actions) => Group<Actions>;
+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>;
 //#endregion
-export { type Implementation, ActionGroup_d_exports as t };
+export type { Implementation };

package/dist/ActionGroup.mjs

@@ -1,27 +1,25 @@
-import { t as __exportAll } from "./rolldown-runtime-D7D4PA-g.mjs";
-import { t as Implementation } from "./implementation-BkLqMWtv.mjs";
+import { n as assertDistinct, t as Implementation } from "./implementation-4Q2BESw5.mjs";
 import { Effect } from "effect";
 //#region src/ActionGroup.ts
-var ActionGroup_exports = /* @__PURE__ */ __exportAll({ make: () => make });
-/** Duplicate action and MCP names fail at definition time. */
-const make = (...actions) => {
-	const names = /* @__PURE__ */ new Set();
-	const toolNames = /* @__PURE__ */ new Set();
-	for (const action of actions) {
-		if (names.has(action.name)) throw new Error(`Duplicate action: ${action.name}`);
-		names.add(action.name);
-		if (action.mcp !== false) {
-			if (toolNames.has(action.mcp.name)) throw new Error(`Duplicate MCP tool: ${action.mcp.name}`);
-			toolNames.add(action.mcp.name);
-		}
-	}
-	return {
+function make(options, ...declared) {
+	const { name } = options;
+	if (!/^[A-Za-z][A-Za-z0-9_-]*$/.test(name)) throw new Error(`Invalid action group name: ${name}`);
+	const actions = declared.map((action) => ({
+		...action,
+		errors: [...action.errors, ...options.errors ?? []]
+	}));
+	assertDistinct("action", actions.map((action) => action.name));
+	assertDistinct("MCP tool", actions.flatMap((action) => action.mcp === false ? [] : [action.mcp.name]));
+	const group = {
+		name,
 		actions,
+		schemaError: options.schemaError,
 		implement: (build) => {
 			const built = Effect.isEffect(build) ? build : Effect.succeed(build);
-			return Implementation.make(actions, built);
+			return Implementation.make(group, built);
 		}
 	};
-};
+	return group;
+}
 //#endregion
-export { make, ActionGroup_exports as t };
+export { make };

package/dist/ActionHttp.d.mts

@@ -0,0 +1,52 @@
+import { d as __exportAll, i as Codec, n as Action_d_exports, r as Any } from "./Action-CXsfTEhx.mjs";
+import { a as RequestContext, n as BuildContext, o as Actions, r as BuildError, s as PolicyError, t as AnyImplementation } from "./implementation-DTqp_0DW.mjs";
+import { Effect, Layer, Schema } from "effect";
+import { HttpApi, HttpApiClient, HttpApiEndpoint, HttpApiGroup } from "effect/unstable/httpapi";
+import { Etag, HttpClient, HttpPlatform, HttpRouter } from "effect/unstable/http";
+import { FileSystem } from "effect/FileSystem";
+import { Path } from "effect/Path";
+declare namespace ActionHttp_d_exports {
+  export { Api, Client, ClientOptions, Http, Options, make };
+}
+/** Contract-level configuration: servers and clients must agree on it. */
+export interface Options {
+  readonly apiPath: `/${string}`;
+}
+/** Distribute over the tuple so each name retains its own codecs. */
+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;
+/** One native group per action group; groups without HTTP actions are omitted. */
+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;
+export type Api<G extends Actions> = HttpApi.HttpApi<"actions", ApiGroup<G>>;
+type Served<G extends Actions> = G extends Actions ? G["actions"][number] extends (infer Item) ? Item extends Any ? {
+  readonly action: Item;
+  readonly policyError: PolicyError<G>;
+} : never : never : never;
+/** Direct decoded-input methods of every group, excluding MCP-only actions. */
+export type Client<G extends Actions> = { readonly [Pair in Served<G> as Pair["action"]["http"] extends false ? never : Pair["action"]["name"]]: (...args: {} extends Pair["action"]["input"]["Type"] ? [input?: Pair["action"]["input"]["Type"]] : [input: Pair["action"]["input"]["Type"]]) => HttpApiClient.Client.MethodReturn<Endpoint<Pair["action"], Pair["policyError"]>, never, never, "decoded-only">; };
+/** Native connection options: `baseUrl`, `transformClient`, `transformResponse`. */
+export type ClientOptions = NonNullable<Parameters<typeof HttpApiClient.make>[1]>;
+export interface Http<G extends Actions> {
+  /**
+   * The native `HttpApi` for every HTTP-enabled action: `POST <apiPath>/<name>`.
+   * Documents, documentation UIs and native clients are Effect's own, from this value.
+   */
+  readonly api: Api<G>;
+  /**
+   * The routes of one group. Merge one per group; router middleware provided
+   * to a layer applies to that group only. Handler requirements are
+   * request-level requirements, exactly as native `HttpApiBuilder` handlers'
+   * are. A group without HTTP actions registers nothing and is not acquired.
+   */
+  readonly layer: <App extends AnyImplementation<G>>(app: App) => Layer.Layer<never, BuildError<App>, BuildContext<App> | HttpRouter.HttpRouter | HttpRouter.Request.From<"Requires", RequestContext<App>> | Etag.Generator | FileSystem | HttpPlatform.HttpPlatform | Path>;
+  /** Direct action methods backed by the native HTTP client and its codecs. */
+  readonly client: (options?: ClientOptions) => Effect.Effect<Client<G>, never, HttpClient.HttpClient>;
+}
+/**
+ * Bind the contract-level configuration once. The native API is built here and
+ * shared by the routes and clients, so they cannot disagree.
+ */
+export declare function make<const G extends ReadonlyArray<Actions>>(options: Options, ...groups: G): Http<G[number]>;
+//#endregion
+export { ActionHttp_d_exports as t };

package/dist/ActionHttp.mjs

@@ -0,0 +1,74 @@
+import { n as assertDistinct, r as served, t as Implementation } from "./implementation-4Q2BESw5.mjs";
+import { Context, Effect, Layer, Schema } from "effect";
+import { HttpApi, HttpApiBuilder, HttpApiClient, HttpApiEndpoint, HttpApiGroup, HttpApiMiddleware, OpenApi } from "effect/unstable/httpapi";
+//#region src/ActionHttp.ts
+const endpoint = (apiPath, action, errors) => HttpApiEndpoint.post(action.name, `${apiPath}/${action.name}`, {
+	payload: action.input,
+	success: action.success,
+	error: [...action.errors, ...errors]
+}).annotate(OpenApi.Description, action.description);
+function erasedApi(views, options) {
+	const [first, ...rest] = views.flatMap(({ group, actions }) => {
+		const [head, ...tail] = actions.map((action) => endpoint(options.apiPath, action, group.schemaError?.errors ?? []));
+		return head === void 0 ? [] : [HttpApiGroup.make(group.name).add(head, ...tail)];
+	});
+	const empty = HttpApi.make("actions");
+	return first === void 0 ? empty : empty.add(first, ...rest);
+}
+const schemaErrorMiddleware = (policy) => {
+	class SchemaErrors extends HttpApiMiddleware.Service()("effect-actions/http/SchemaErrors", { error: policy?.errors ?? [] }) {}
+	return {
+		SchemaErrors,
+		layer: HttpApiMiddleware.layerSchemaErrorTransform(SchemaErrors, (failure) => Effect.fail(policy === void 0 ? failure : policy.map({
+			phase: failure.kind === "Body" || failure.kind === "ResponseHeaders" ? "output" : "input",
+			cause: failure.cause
+		})))
+	};
+};
+/** One group registers its own routes, so middleware provided to this layer is its alone. */
+const erasedLayer = (binding, app) => {
+	if (!binding.groups.includes(app.group)) throw new Error(`Implementation of group "${app.group.name}" is not served by this adapter`);
+	const view = binding.views.find(({ group }) => group === app.group);
+	if (view === void 0) return Layer.empty;
+	const schemaErrors = schemaErrorMiddleware(view.group.schemaError);
+	const httpApi = erasedApi([view], binding.options).middleware(schemaErrors.SchemaErrors);
+	return Implementation.register([{
+		app,
+		actions: view.actions
+	}], (bound) => {
+		const handlers = bound.map((implementation) => HttpApiBuilder.group(httpApi, implementation.group.name, (builder) => builder.handleAll(Object.fromEntries(implementation.actions.map((action) => {
+			const handle = implementation.handle(action);
+			return [action.name, (request) => handle(request.payload)];
+		})))));
+		const isolated = Layer.fromBuildMemo((memoMap, scope) => Layer.buildWithMemoMap(Layer.mergeAll(Layer.empty, ...handlers).pipe(Layer.provide(schemaErrors.layer)), memoMap, scope).pipe(Effect.setContext(Context.empty())));
+		return HttpApiBuilder.layer(httpApi).pipe(Layer.provide(isolated));
+	});
+};
+const erasedClient = (api, views, connection) => Effect.map(HttpApiClient.make(api, connection), (native) => {
+	const acceptsUndefined = new Set(views.flatMap(({ actions }) => actions.flatMap((action) => Schema.is(action.input)(void 0) ? [action.name] : [])));
+	return Object.fromEntries(Object.values(native).flatMap((methods) => Object.entries(methods).map(([name, method]) => {
+		if (name === "then") throw new Error("Action \"then\" requires the native grouped HttpApiClient");
+		return [name, (input) => method({
+			payload: input === void 0 && !acceptsUndefined.has(name) ? {} : input,
+			responseMode: "decoded-only"
+		})];
+	})));
+});
+function make(options, ...groups) {
+	const views = served(groups, (action) => action.http);
+	assertDistinct("action group", groups.map((group) => group.name));
+	assertDistinct("action", views.flatMap(({ actions }) => actions.map((action) => action.name)));
+	const api = erasedApi(views, options);
+	const binding = {
+		groups,
+		views,
+		options
+	};
+	return {
+		api,
+		layer: (app) => erasedLayer(binding, app),
+		client: (connection) => erasedClient(api, views, connection)
+	};
+}
+//#endregion
+export { make };