@gjermundgaraba/effect-actions 0.4.1 → 0.6.0

package/dist/internal/tools.mjs

@@ -1,4 +1,4 @@
-import { projectedErrors } from "./actions.mjs";
+import { assertDistinct, projectedErrors } from "./actions.mjs";
 import { dispatch } from "./implementation.mjs";
 import { Effect, Schema } from "effect";
 import { Tool, Toolkit } from "effect/unstable/ai";
@@ -17,15 +17,6 @@ const entries = (apps) => apps.flatMap(({ app, actions }) => actions.map((action
 	app,
 	action
 })));
-/** Fail before acquiring handlers when two exposed tools share a name. */
-const assertDistinctToolNames = (tools) => {
-	const names = /* @__PURE__ */ new Set();
-	for (const { action } of tools) {
-		const name = action.mcp.name;
-		if (names.has(name)) throw new Error(`Duplicate MCP tool: ${name}`);
-		names.add(name);
-	}
-};
 const annotate = (tool, mcp) => tool.annotate(Tool.Readonly, mcp.readOnly).annotate(Tool.Destructive, mcp.destructive).annotate(Tool.Idempotent, mcp.idempotent).annotate(Tool.OpenWorld, mcp.openWorld);
 /**
 * A native Effect AI tool. Its schemas retain action transforms and its result
@@ -49,20 +40,14 @@ const mcpTool = (action, errors) => annotate(Tool.make(action.mcp.name, {
 	failure: Schema.toCodecJson(Schema.Union(errors)),
 	failureMode: "return"
 }), action.mcp);
-/** MCP's input schema must describe a JSON object, including no-argument tools. */
-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, 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, before) => {
-	const run = (input) => dispatch(app.group, action, handlers, before)(input);
+	const run = dispatch(app.group, action, handlers, before);
 	return projection === "native" ? run : (input) => Effect.map(run(input), (value) => ({ value }));
 };
 /**
@@ -73,7 +58,7 @@ const handler = (projection, app, action, handlers, before) => {
 const bindTools = (apps, projection, options) => {
 	const served = toolApps(apps);
 	const selected = entries(served);
-	assertDistinctToolNames(selected);
+	assertDistinct("MCP tool", selected.map(({ action }) => action.mcp.name));
 	const toolkit = Toolkit.make(...selected.map((entry) => project(projection, entry, options)));
 	return {
 		toolkit,

package/docs/Action.md

@@ -5,56 +5,25 @@ metadata. An action holds no behavior; handlers are bound by `ActionGroup.implem
 
 ## API
 
-```ts
-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 = [], Acc extends Access, Http = true, Mcp = undefined>(
-  name: Name,
-  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, 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 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, 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
-}
-
-/** 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>;
-
-type Any; // any action with its schemas erased
-```
+Import `@gjermundgaraba/effect-actions/Action`.
+
+| Export                                     | Purpose                                                                            |
+| ------------------------------------------ | ---------------------------------------------------------------------------------- |
+| `make(name, options)`                      | Define a pure contract; literal names, access and transport exclusions stay typed. |
+| `Action`, `Any`, `Options`                 | Concrete contracts, erased contracts and construction options.                     |
+| `Codec`, `Handler`, `Access`, `McpOptions` | Service-free codecs, typed handlers, read/write classification and tool metadata.  |
+
+| Option                             | Meaning                                                                      |
+| ---------------------------------- | ---------------------------------------------------------------------------- |
+| `description`, `success`, `access` | Required description, success codec and `"read"` / `"write"` classification. |
+| `input`                            | Optional codec; omission means an empty object.                              |
+| `errors`                           | Declared error codecs; defaults to none.                                     |
+| `http`                             | Defaults to enabled; `false` removes routes and client methods.              |
+| `mcp`                              | Defaults to enabled; `false` removes tools, otherwise accepts `McpOptions`.  |
+
+MCP options: `name` defaults to the action name; `readOnly` to `access === "read"`;
+`destructive` to `!readOnly`; `idempotent` to `false`; `openWorld` to `true`.
+Handlers receive decoded input and return decoded success, failing only with declared errors.
 
 ## Canonical
 
@@ -120,11 +89,11 @@ 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. `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 `"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. Its only built-in uses are default MCP hints and span/log annotations; adapters never enforce an authorization rule from 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.
+- MCP input must have an object-root JSON Schema, an identified or recursive root included. Scalar or array input is fine for HTTP and for a native Toolkit, but the native MCP server refuses it when an `ActionMcp` layer is built. Success and error schemas may be any shape.
+- `mcp.name` is the tool name, matches `[A-Za-z0-9_-]+` except `then`, is 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: 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>`.
@@ -134,7 +103,6 @@ export const Double = Action.make("double", {
 
 - 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`.
 - `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

@@ -1,57 +1,54 @@
 # ActionCatalog
 
-An offline JSON document describing groups: identities, metadata, and standalone JSON
-schemas. Built from contracts alone. No implementation, service, or server is involved.
+An offline JSON document of contract identities, metadata and encoded-value JSON Schemas.
+Built from contracts alone: no implementation, service or server is involved.
 
 ## API
 
-```ts
-import * as ActionCatalog from "@gjermundgaraba/effect-actions/ActionCatalog";
+Import `@gjermundgaraba/effect-actions/ActionCatalog`.
 
-const make: (...groups: ReadonlyArray<ActionGroup.Any>) => Catalog;
-
-interface Catalog {
-  readonly version: "1";
-  readonly actions: ReadonlyArray<Entry>;
-}
-
-interface Entry {
-  readonly id: string; // "<group>.<action>"
-  readonly group: string;
-  readonly name: string;
-  readonly description: string;
-  readonly http: boolean;
-  readonly mcp: false | { name; readOnly; destructive; idempotent; openWorld };
-  readonly input: JsonSchema.JsonSchema;
-  readonly success: JsonSchema.JsonSchema;
-  readonly errors: ReadonlyArray<JsonSchema.JsonSchema>; // own + inherited group errors
-  readonly httpSchemaErrors: ReadonlyArray<JsonSchema.JsonSchema>; // policy errors, HTTP only
-}
-```
+`make(...groups)` returns `Catalog`: `version: "3"` and an ordered `actions` array of `Entry`.
+
+| Entry field                          | Meaning                                                                      |
+| ------------------------------------ | ---------------------------------------------------------------------------- |
+| `id`, `group`, `name`, `description` | Stable `<group>.<action>` identity and contract metadata.                    |
+| `http`, `mcp`                        | HTTP enablement and resolved MCP enablement/name/hints.                      |
+| `input`, `success`                   | Standalone draft 2020-12 JSON Schema objects, not wrappers.                  |
+| `errors`                             | JSON Schema objects for own and inherited group errors.                      |
+| `httpSchemaErrors`                   | JSON Schema objects for HTTP policy errors; empty for HTTP-disabled actions. |
+
+Exported types are `Catalog` and `Entry`.
 
 ## Canonical
 
 ```ts
+import { NodeRuntime } from "@effect/platform-node";
+import { Console } from "effect";
 import * as ActionCatalog from "@gjermundgaraba/effect-actions/ActionCatalog";
 import { AuditActions, PublicActions, UserActions } from "./contracts.js";
 
-const catalog = ActionCatalog.make(PublicActions, UserActions, AuditActions);
-
-process.stdout.write(JSON.stringify(catalog, null, 2));
+// Contract inspection requires no implementation or domain-service Layer.
+Console.log(
+  JSON.stringify(ActionCatalog.make(PublicActions, UserActions, AuditActions), null, 2),
+).pipe(NodeRuntime.runMain);
 ```
 
 ## Rules
 
 - Takes groups, not implementations. Nothing is acquired or started.
+- Group names must be unique. Entries preserve group declaration order, then action declaration order.
 - `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`. 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.
+- Schemas describe encoded action values through native `Schema.toJsonSchemaDocument`, which lowers to the JSON codec first. A `Date` is a string, an `Option` a tagged union, a `bigint` a string of digits. These are action values, not MCP's `{ value }` envelope or deployment URLs.
+- JSON Schema does not preserve arbitrary Effect transformations or filters. Checks on the decoded side of a transformation, such as `FiniteFromString.check(isGreaterThan(0))`, are not described. The server's decode remains authoritative.
+- Each schema root includes its own `$schema` and, where needed, `$defs`. Equal identifiers across entries or fields cannot replace each other; recursive references resolve locally.
+- The catalog contains JSON Schema only. Use Effect's `SchemaRepresentation` directly when native schema persistence or revival is needed.
+- `errors` includes group-level errors. HTTP schema-policy errors are separate in `httpSchemaErrors`. Surface errors belong to bindings and are not listed.
+- `access` is omitted; read it from the contract when needed. Local-only actions are included. Presence grants no authorization or proof that an endpoint is mounted; the host decides what to publish.
+- No search, catalog HTTP endpoint, or TypeScript code generation is provided.
 
 ## Failure modes
 
-- Type error passing an implementation: `make` takes groups. Pass `app.group` or the group value itself.
-- Consumers see `{ value }` in MCP responses but not in the catalog: expected. The catalog describes action values; MCP wraps them.
+- `Duplicate catalog group: <name>`: two supplied groups share a name, including a group passed twice.
+- Type error passing an implementation: pass `app.group` or the group value itself.
+- Native JSON Schema conversion throws: the codec or its annotations cannot be converted.
+- JSON Schema accepts a value the server rejects: custom validation or a decoded-side check is not expressible in the wire schema. Server validation remains authoritative.

package/docs/ActionCli.md

@@ -5,47 +5,24 @@ nothing is fetched over HTTP.
 
 ## API
 
-```ts
-import * as ActionCli from "@gjermundgaraba/effect-actions/ActionCli";
-
-/** One explicitly selected action. */
-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, 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, EB, RB>(
-  app: Implementation<G, H, EX, RX>,
-  options?: GroupOptions<EB, RB>,
-) => Command.Command<string, {}, {}, EX | EB | SchemaError | DeclaredErrors, ...>;
+Import `@gjermundgaraba/effect-actions/ActionCli`.
 
-/** 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>;
-}
+| API                            | Purpose                                                           |
+| ------------------------------ | ----------------------------------------------------------------- |
+| `command(app, name, options?)` | One selected action as a native Effect `Command`.                 |
+| `group(app, options?)`         | Every action under a group command, including local-only actions. |
+| `Options`, `GroupOptions`      | Configuration for single and aggregate commands.                  |
 
-interface GroupOptions<EB, RB> extends BeforeOptions<EB, RB> {
-  readonly name?: string; // override the group command name
-}
+| Option                | Meaning                                                                                                      |
+| --------------------- | ------------------------------------------------------------------------------------------------------------ |
+| `name`                | Override the command/group name.                                                                             |
+| `before`              | Hook receiving the selected `Action.Any`; its failures and services join the command's channels.             |
+| `render`              | Single command only: decoded success to human-readable string; adds `--json`.                                |
+| `parameters`, `input` | Single command only; supply together. Native flag/argument config and parsed-config-to-encoded-JSON mapping. |
 
-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
-  readonly render?: (output: Output) => string; // human output; --json still prints JSON
-}
-
-interface ParametersOptions<Output, Parameters> {
-  readonly name?: string;
-  readonly render?: (output: Output) => string;
-  readonly parameters: Parameters; // native Effect Flag / Argument config
-  readonly input: (parsed: Command.Command.Config.Infer<Parameters>) => Schema.Json; // encoded action input
-}
-```
+Without `parameters`/`input`, a command accepts `--input` and `--input-file`. Commands retain
+handler, builder and hook requirements/failures, plus codec failures. The invocation owns its
+scope. Success output is encoded; failures remain failures of the command Effect.
 
 ## Canonical
 
@@ -58,7 +35,6 @@ 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") },
@@ -66,13 +42,10 @@ const command = ActionCli.command(UserApp, "double", {
   before: authorize,
 });
 
-// Default syntax for a whole group: `users double --input '{"value":"21"}'`.
-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
+  // The hook runs here too, so a local caller supplies an identity for it
   // exactly as HTTP middleware does for a request.
   Effect.provideService(CurrentActor, actors.alice),
   Effect.provide(Users.layerMemory),
@@ -84,22 +57,22 @@ Command.runWith(command, { version: "0.1.0" })(process.argv.slice(2)).pipe(
 ## Rules
 
 - `command(app, name)` selects one action by name from the bound group; the name is checked at the type level. `group(app)` puts every action under the group command, including actions with `http: false` and `mcp: false`.
-- Default syntax is `--input '<json>'` carrying the entire encoded input: nested objects, arrays, scalars. Omitting `--input` supplies `{}`, which must still satisfy the input schema.
-- `parameters` and `input` are supplied together or not at all. With them, the command has explicit native flags and arguments and no `--input`, so its syntax does not change when the schema changes.
+- Default syntax is `--input '<json>'` or `--input-file <path>` carrying the entire encoded input: nested objects, arrays, scalars. The file is read and JSON-parsed by the native `Flag.FileSchema`. Both are decoded by the native parser; if both are given, the file is used. Omitting both decodes `{}` separately on every invocation; result identity follows the codec's behavior. An action that requires input then fails with a `SchemaError`, exactly as a `parameters` command's mapped input does.
+- `parameters` and `input` are supplied together or not at all. With them, the command has explicit native flags and arguments and neither `--input` nor `--input-file`, so its syntax does not change when the schema changes.
 - `input(parsed)` returns encoded JSON. The action schema decodes it before dispatch; a mismatch is a `SchemaError` at runtime. Action fields are never turned into flags automatically.
 - Native `Flag` and `Argument` own names, aliases, ordering, defaults, and optionality. Use `Flag.optional` when omission must stay distinct from a default, and map the `Option` to a present or omitted field.
-- 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.
+- Output is validated and encoded before printing. Default output is JSON. `render(decoded)` gives human output and adds a `--json` flag to that command, which selects JSON again. Rendering cannot bypass validation.
+- `--json` is a regular flag of the rendered command only, placed after the command name on a `group` path. A command without `render` has no such flag: its output is JSON already. Nothing is declared tree-wide, so a host CLI may declare its own `--json`, global or not. A rendered `parameters` command reserves the flag name; a payload field named `json` is ordinary data.
 - 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.
+- The CLI declares no surface `errors`: it does not serialize failures, so a refusal is simply a typed failure of the command effect. Success values are still validated and encoded for output. The native parser also decodes `--input` and `--input-file` before the command runs, so invalid input skips the hook and handler.
 - Group commands use the default JSON syntax. For a custom tree, compose individual `command` results with native `Command` combinators.
 
 ## Failure modes
 
-- `SchemaError` on a valid-looking `--input`: the JSON is decoded input, so transforming codecs expect the encoded form (`"21"` for `FiniteFromString`, not `21`).
-- Command rejects `--input`: the command was built with `parameters`. Use its flags.
+- Native `CliError.ShowHelp` containing `InvalidValue` for a supplied `--input` or `--input-file`: the parser rejected its JSON or schema before the command handler ran. Supply encoded input (`"21"` for `FiniteFromString`, not `21`). With neither flag, decoding the default `{}` can fail with `SchemaError`; so can a `parameters` command's mapped input or an invalid success value.
+- Command rejects `--input` or `--input-file`: 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.
+- A command requires a request-identity tag no handler yields: the `before` hook yields it. Provide a trusted identity around the invocation; do not remove the authorization hook just to satisfy the service requirement.
+- `--json` flag conflict at definition on a rendered `parameters` command: rename the native flag; the config property can keep its name.

package/docs/ActionCliClient.md

@@ -5,37 +5,22 @@ handler locally and manages no credentials.
 
 ## API
 
-```ts
-import * as ActionCliClient from "@gjermundgaraba/effect-actions/ActionCliClient";
-
-/** One HTTP-enabled action retained by the binding. */
-const command: <const Groups, const GroupName, const ActionName, Parameters = never>(
-  http: Http<Groups>,
-  groupName: GroupName,
-  actionName: ActionName, // only actions with http: true
-  options?: Options<SuccessType, Parameters>,
-) => Command.Command<string, never, {}, ClientErrors, HttpClient.HttpClient | ClientServices>;
+Import `@gjermundgaraba/effect-actions/ActionCliClient`.
 
-/** Every HTTP-enabled action of one group under the group name. */
-const group: <const Groups, const GroupName>(
-  http: Http<Groups>,
-  groupName: GroupName,
-  options?: GroupOptions,
-) => Command.Command<string, {}, {}, ClientErrors, HttpClient.HttpClient | ClientServices>;
+| API                                              | Purpose                                                                    |
+| ------------------------------------------------ | -------------------------------------------------------------------------- |
+| `command(http, groupName, actionName, options?)` | Call one HTTP-enabled action through a native Effect `Command`.            |
+| `group(http, groupName, options?)`               | Every HTTP-enabled action of a bound group under one command.              |
+| `Options`, `GroupOptions`, `Connection`          | Single/aggregate command configuration and native HTTP connection options. |
 
-type Options<Output, Parameters> = ActionCli.Options<Output, Parameters> & {
-  /** Passed directly to HttpApiClient.make: baseUrl, transformClient, transformResponse. */
-  readonly connection?: Parameters<typeof HttpApiClient.make>[1];
-};
-
-interface GroupOptions {
-  readonly name?: string;
-  readonly connection?: Parameters<typeof HttpApiClient.make>[1]; // shared by every action
-}
-```
+Single-command options: `name`, `render`, paired `parameters`/`input`, and `connection`.
+Group options: `name` and `connection`. Parsing/rendering semantics match [ActionCli.md](ActionCli.md).
+`connection` accepts native `HttpApiClient.make` configuration, including `baseUrl`,
+`transformClient` and `transformResponse`.
 
-Parsing and rendering options (`name`, `render`, `parameters`, `input`) are the same as
-[ActionCli.md](ActionCli.md).
+Remote commands have no local `before` hook: the server owns authorization. Their Effects
+retain the selected endpoint's client failures and middleware requirements, and require an
+`HttpClient` supplied by the host. Group/action selectors stay checked against the bound API.
 
 ## Canonical
 
@@ -53,7 +38,8 @@ const command = ActionCliClient.command(Http, "public", "status", {
 Command.runWith(command, { version: "0.1.0" })(process.argv.slice(2)).pipe(
   Effect.tapCause((cause) => Console.error(cause)),
   Effect.provideService(Logger.LogToStderr, true),
-  Effect.provide(NodeHttpClient.layerUndici), // the host supplies HttpClient
+  // The host supplies the native client and its connection configuration.
+  Effect.provide(NodeHttpClient.layerUndici),
   Effect.provide(NodeServices.layer),
   NodeRuntime.runMain({ disableErrorReporting: true }),
 );
@@ -66,7 +52,7 @@ Authentication: `connection: { transformClient: HttpClient.mapRequest(HttpClient
 - Selectors resolve from `http.groups` only. `groupName` must be a bound group; `actionName` must be an action of that group with `http: true`. Runtime guards reject dynamically supplied strings that the types would not accept.
 - The host provides `HttpClient` and its configuration. Endpoint selection, credentials, and storage are the host's; nothing is inferred from action arguments.
 - Input is decoded by the action schema before dispatch, then passed to the native client at its normal codec boundary. Do not pre-encode values.
-- Output is validated and printed as JSON, or through `render` with `--json` available, exactly as in `ActionCli`.
+- Input syntax (`--input`, `--input-file`, or `parameters`) and output (`render` and its `--json` flag) are exactly as in `ActionCli`.
 - Errors are the client's: declared errors, policy errors, `SchemaError`, and `HttpClientError`.
 
 ## Failure modes

package/docs/ActionGroup.md

@@ -6,57 +6,29 @@ The pre-handler hook does not: each surface binds its own (see [guarantees.md](g
 
 ## API
 
-```ts
-import * as ActionGroup from "@gjermundgaraba/effect-actions/ActionGroup";
+Import `@gjermundgaraba/effect-actions/ActionGroup`.
 
-function make<Name, Actions, Errors = [], PolicyErrors = []>(
-  options: Options<Name, Errors, PolicyErrors>,
-  ...actions: Actions
-): Group<Name, WithErrors<Actions, Errors>, PolicyErrors>;
-
-interface Options<Name, Errors, PolicyErrors> {
-  readonly name: Name; // HttpApiGroup identifier, OpenAPI tag, operation-ID prefix
-  readonly errors?: Errors; // added to every action's own errors
-  readonly schemaError?: SchemaErrorPolicy<PolicyErrors>; // HTTP only; MCP keeps native answers
-}
-
-interface SchemaErrorPolicy<Errors extends ReadonlyArray<Codec>> {
-  readonly errors: Errors;
-  readonly map: (failure: HttpApiError.HttpApiSchemaError) => Errors[number]["Type"];
-}
-
-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>(
-    build: H | Effect.Effect<H, EX, RX>,
-  ) => 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> {
-  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": ... }
-```
+| API                               | Purpose                                                                                 |
+| --------------------------------- | --------------------------------------------------------------------------------------- |
+| `make(options, ...actions)`       | Group actions under a required `name`; optional `errors` are inherited by each action.  |
+| `group.implement(recordOrEffect)` | Bind every action handler; an Effect builder carries startup requirements and failures. |
+| `app.group`, `app.build`          | Bound contract and scoped handler acquisition.                                          |
+| `contracts(...groups)`            | Exact action types keyed by `<group>.<action>`.                                         |
+
+Exported types: `Group`, `Any`, `Options`, `Implementation`, `Contracts`, `SchemaErrorPolicy`,
+`SchemaErrorAnswer`.
 
-`HandlersFrom<Actions>` is `{ [action name]: Handler<Action, R> }`, one key per action,
-all required.
+The optional `schemaError` group option is a `SchemaErrorPolicy`: two answers, `invalid` and
+`internal`, each a `schema` (a declared error codec) and `make(failure)` (the native
+`HttpApiSchemaError` to that error's decoded value). The library decides which answer applies.
+It affects HTTP only. Handler records require every action key. Each handler's input, success
+and declared errors come from its action; request requirements stay distinct from the
+builder's requirements.
 
 ## Canonical
 
 ```ts
 import { Effect, Schema } from "effect";
-import type { HttpApiError } from "effect/unstable/httpapi";
 import * as ActionGroup from "@gjermundgaraba/effect-actions/ActionGroup";
 import { CurrentActor } from "./auth.js";
 import { GetUser, RenameUser, WhoAmI } from "./contracts.js";
@@ -73,13 +45,17 @@ class InternalError extends Schema.TaggedError<InternalError>()(
   { httpApiStatus: 500 },
 ) {}
 
-// Shared across groups: annotate the parameter. Inline, `map` is inferred from `errors`.
+// A request that does not decode is the caller's fault; a result that does not
+// encode is the server's. Shared across groups as a constant.
 const schemaError = {
-  errors: [InvalidRequest, InternalError],
-  map: ({ kind }: HttpApiError.HttpApiSchemaError) =>
-    kind === "Body" || kind === "ResponseHeaders"
-      ? new InternalError({ message: "The request could not be completed." })
-      : new InvalidRequest({ message: "The request does not match the action's input." }),
+  invalid: {
+    schema: InvalidRequest,
+    make: () => new InvalidRequest({ message: "The request does not match the action's input." }),
+  },
+  internal: {
+    schema: InternalError,
+    make: () => new InternalError({ message: "The request could not be completed." }),
+  },
 };
 
 export const UserActions = ActionGroup.make(
@@ -115,9 +91,9 @@ 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`.
+- `name` matches `[A-Za-z0-9_-]+`, cannot be `then`, 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. 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.
+- `implement` takes a complete record or an Effect producing one. Every action must have a handler; missing keys are compile errors. A record that still lacks one at runtime (plain JavaScript, a cast) throws at `implement`; a builder's record fails the adapter layer's build. Nothing is served with a handler missing. Additional keys are not dispatched. 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.
@@ -127,14 +103,15 @@ const renames: "renameUser" = contracts["users.renameUser"].name;
 ### Schema-error policy
 
 - Without a policy, HTTP answers decoding and encoding failures with Effect's native empty 400.
-- With a policy, `map` receives the native `HttpApiSchemaError` (`kind`, `cause`) and returns one of `errors`. HTTP uses that error's `httpApiStatus`, and the error appears in `Http.api`, in clients, and in OpenAPI.
-- `kind` values: `Payload` (input decoding) and `Body` (success encoding). Actions declare no parameters, query, or headers, so no other kind occurs.
+- With a policy, the library picks the answer from the native `HttpApiSchemaError`'s `kind`. Request-side kinds (`Payload`, `Params`, `Headers`, `Query`: the request did not decode) get `invalid`; response-side kinds (`Body`, `ResponseHeaders`: the handler's result did not encode) get `internal`. `make` receives the failure (`kind`, `cause`) and returns its schema's value. HTTP uses that error's `httpApiStatus`, and both errors appear in `Http.api`, in clients, and in OpenAPI.
+- In practice only `Payload` and `Body` occur: actions declare no parameters, query, or headers, and no response headers.
+- `invalid` and `internal` may share one schema; it is declared once.
 - MCP is unaffected. The native `McpServer` answers invalid arguments and unencodable results itself.
 - Policy errors extend the transport contract, not the handler contract. A handler cannot return them.
 - 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.
+- Input schema-error policies run before the `before` hook. Invalid input is answered by the policy without invoking the hook or handler.
 - 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
@@ -143,6 +120,7 @@ const renames: "renameUser" = contracts["users.renameUser"].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`).
+- `Parameter 'failure' implicitly has an 'any' type` in a standalone policy constant: a `make` that reads the failure is typed only inline. Annotate the parameter as `HttpApiError.HttpApiSchemaError` (type import from `effect/unstable/httpapi`), or annotate the constant as `ActionGroup.SchemaErrorPolicy<typeof Invalid, typeof Internal>`.
+- `Missing handlers for group "<group>": <actions>` thrown at `implement`, or failing the layer build: the handler record lacks those actions. Add them.
 - 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.