@gjermundgaraba/effect-actions 0.8.0 → 0.10.0

package/docs/guarantees.md

@@ -1,65 +1,103 @@
 # Guarantees
 
-Rules that hold across every adapter. Module pages link here rather than repeating them.
+Rules that hold across every surface. Module pages state what is their own and link here for the rest.
 
 ## Dependency lifetimes
 
-- Handlers receive decoded input, return decoded results, and may fail only with declared errors. Anything else is a defect.
-- Each surface binds its own pre-handler hook: `Http.layer(apps, { before })`, `ActionMcp.layerHttp`/`layerStdio`, `ActionToolkit.make`, `ActionCli.command`/`group`. After successful input decoding, a bound hook runs once before the selected handler and outside its span. There is no per-action opt-out; direct `build` calls bypass dispatch.
-- The hook receives the selected action contract (`Action.Any`), so a policy reads `action.access`, `action.name` or `action.mcp` instead of a hand-maintained list. It is not authentication: establish identity in middleware, then let the hook authorize what that identity may do.
-- It fails with the surface's own `errors`, the same list that declares what the surface answers instead of a handler, so a refusal is encoded exactly like a declared error: the schema's `httpApiStatus` on HTTP, an `isError` tool result on MCP, a returned failure on the Toolkit. `ActionCli` declares no surface errors because it does not serialize failures; there a refusal is a typed failure of the command effect.
-- Its services 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.
-- All surfaces decode input before dispatch. Invalid input skips the hook and handler, so unauthorized callers can receive schema errors. Use outer native HTTP middleware for admission that must run before decoding; a pre-handler hook does not provide that guarantee.
-- Build-time services are those yielded in the `implement` builder Effect. They resolve once per adapter layer, in that layer's scope. An implementation served by two adapters is built twice. Share state through a Layer provided to the adapters, never through the builder.
-- Request-time services are those yielded inside a handler. For HTTP-hosted adapters (`ActionHttp`, `ActionMcp.layerHttp`) they appear as `HttpRouter.Request.From<"Requires", R>` and are supplied by router middleware, `HttpRouter.provideRequest`, or request context. For `ActionToolkit`, `ActionCli`, and `ActionMcp.layerStdio` the host supplies them at invocation.
-- Use distinct tags for build-time capabilities and request-scoped identity. Never provide an identity or tenant tag in a startup layer or root context. The adapters use native Effect context capture and merging: a startup value under a tag can shadow a request value or satisfy a missing one. Types verify presence, not provenance.
-- Authentication must establish identity on every protected request. Types cannot verify that a handler performed authorization; the `before` hook is the one place the library guarantees runs before the handler, so put the check there rather than in each handler.
-- `access` is contract metadata, required on every action and kept as a literal type. It supplies the default MCP `readOnly` hint and the `action.access` span/log annotation, but enforces no authorization. A hook can switch on what an action does instead of on its name. The catalog omits it.
-- `ActionCli` acquires the implementation per invocation and releases it after the call. `ActionToolkit.make(...).layer` acquires it once for the layer's lifetime.
+- Handlers receive decoded input, return decoded results, and may fail only with their action's declared errors and the built-in ones. A failure the types let through anyway, such as from plain JavaScript or a cast, is answered as the [wire table](#wire-behavior) says for an undeclared failure.
+- Build-time services are those yielded in the builder Effect passed to `implement`, in an Effect building its authorizer and in a verifier's `Authentication.layer`. Each is a layer Effect memoizes. Within one layer graph it runs once, however many surfaces serve its implementation (HTTP layers, MCP endpoints, a Toolkit) or list its actions, and its scope is the host's. Two `implement` calls are two builders, even of one builder Effect: each runs once per graph.
+- `HttpRouter.serve` and `Testing.layer` each build their routes in a layer graph of their own, which reuses what the host has already built but shares nothing it builds itself: a builder's run, a built authorizer, a service of your own such as an in-memory store. `HttpRouter.provideRequest` also builds the layer it provides in a graph of its own, which reuses what the routes' graph has already built. So one rule places builders and your own services alike: **with one server, put everything the process runs in the layer it serves**, a job or an agent beside the routes included; **otherwise, provide `Action.layer(implementations)` and the services they share above the server and its siblings**, such as a second server, a program running beside it, or several `Testing.layer`s. A sibling given neither builds a builder, and a service whose layer both provide, a second time, with state of its own, whenever the server's graph builds it first: `Layer.mergeAll` builds its layers concurrently, so whichever build reaches the memo map first decides, not the order it lists them in.
+- `Action.layer` builds each builder first, once for every surface and client below it, with the services it is given. Building it acquires every supplied implementation's builder, including implementations no surface serves. Without it, a builder runs only for a surface serving its implementation, or a client of it.
+- A builder runs again only in a separately built layer graph, such as a second `Testing.layer`. A local `ActionCli` command is the exception: it builds the selected implementation, its authorizer included, per invocation, even where the host already built it, and releases it after the call, once the handler's and the authorizer's own finalizers have run.
+- Acquiring an `Action.client` builds its implementations into the layer graph it is acquired in, as a layer of it: in a builder or a layer, the host's graph, where it shares each builder's one run with every surface of that graph, whichever builds first; in a program, the graph of a layer provided around it, which every client acquired there shares; under none, a graph of its own. What it builds stays until its scope closes and nothing else in the graph holds it. Acquired per request, in a handler, it builds for every call unless a surface of the graph serves the same implementation, and its builders' startup services become that handler's request requirements: acquire it where builders live.
+- **Without `Action.layer`, the builder runs with whichever surface's services Effect builds it with first.** Services provided around one surface reach the others too, and so does an `Action.layer` provided to one surface alone: provide its startup services once, to `Action.layer` above every surface that serves it. To give an HTTP or MCP surface a build and startup services of its own, wrap it in `Layer.fresh`, which builds everything inside it anew, and provide what the surfaces share, authentication included, outside it. A Toolkit's tools run on one build of their implementation, whatever layers of it are provided ([ActionToolkit.md](ActionToolkit.md#rules)): separate services take separate implementations.
+- Request-time services are those yielded inside a handler or the authorizer itself. For HTTP-hosted surfaces (`ActionHttp`, `ActionMcp.layerHttp`) they appear as `HttpRouter.Request<"Requires", X>`, one for each service `X`, and are supplied by router middleware around the surface, `HttpRouter.provideRequest`, or request context. A protected action's identity is the exception: only its authentication provider supplies it, so the layer requires that provider instead, and nothing else provided stands in for it. For `ActionToolkit`, `ActionCli`, `ActionMcp.runStdio` and `Action.client` the host supplies them at invocation, the identity of every protected action included, whether or not anything reads it; a client's call reads them from its caller's context alone, never from what the client was acquired with.
+- Each call has a scope of its own, on every surface: what the authorizer and the handler acquire is released when the call ends, the handler's first, before its result is encoded, and over HTTP before the route middleware resumes. A Toolkit call is no exception, whether `tools.handle` makes it or `LanguageModel` runs it, approved or not, and neither is an `Action.client` call. `Scope` is never a request-time requirement. A resource that must outlive a call is the builder's, or a service the host provides around its calls.
+- Use distinct tags for build-time capabilities and request-scoped identity. Everything in a call's context wins over what the surface was built with under the same tag: what authentication, other router middleware, `HttpRouter.provideRequest` or a Toolkit's caller provides, and what the server runs in, as provided around `HttpRouter.serve`, `Testing.layer` or the program. A value provided to one surface's layer only fills in a service or reference the call lacks; to give one surface's requests their own, such as a log level or an `ErrorReporter`, use `HttpRouter.provideRequest` on its layer. So never provide an identity or tenant tag in a server's startup layer or root context: a protected route still requires its authentication provider, and a public handler or a native route reading the tag would serve every caller as that identity. In memory, a test serves protected routes behind an authentication provider, the real one or a test verifier of the same descriptor, and each client sends its own caller's credential ([Testing.md](Testing.md#signed-in-callers)). Types verify presence, not provenance, for every service but a protected action's identity.
+
+## Authorization
+
+- A contract states who may call it, `caller`: `Action.Anyone`, or the identity service a caller must have. Every surface enforces it, whatever the handler and the authorizer read. A remote surface, `ActionHttp.layer` or `ActionMcp.layerHttp`, names the contracts' authentication descriptor (`authentication: Login`), and its layer requires that descriptor's provider, `Authentication.layer`, which verifies each protected request's credential and provides the identity. A local surface requires the identity per call, in the types, and a call that lacks it anyway, as plain JavaScript may, fails with `Unauthenticated` before the authorizer runs. No surface takes an authorization policy of its own, so none can leave one out or loosen it.
+- A call runs, in order: authentication, then over HTTP the layer's own `middleware` ([ActionHttp.md](ActionHttp.md#rules)), then input decoding, then the authorizer, for a protected action only, then the handler. Each step refuses before the next runs. Over HTTP and MCP a protected request is authenticated before its body is read: without a credential, a protected route answers 401 before a 415 or a 400, and a protected tool's call 401 before its arguments are decoded. On a local surface, the identity is checked after decoding.
+- An implementation of protected actions states its authorizer, `Action.implement(actions, handlers, { authorize })`: leaving it out is a type error, and plain JavaScript leaving it out throws at `implement`. `Action.allowAll` lets every authenticated caller call. An implementation of public actions alone takes none, a type error too, and plain JavaScript passing one throws at `implement`. The authorizer never runs for a public action, even one implemented beside protected ones.
+- The authorizer runs once per call, after input decodes, before the handler and outside its span. It runs on `ActionHttp`, `ActionMcp` over HTTP and stdio, `ActionToolkit`, a local `ActionCli` command, and `Action.client`. There is no per-surface override: a caller trusted on one surface, such as an admin CLI's operator, is an identity the host supplies there, which the same authorizer admits ([ActionCli.md](ActionCli.md#trusted-callers)). Calling a handler function directly bypasses dispatch, so call it through `Action.client`.
+- The authorizer receives the selected action contract, typed as the implementation's own, so a policy reads `action.readOnly` or `action.name` instead of a hand-maintained list. It is not authentication: authentication establishes identity, then the authorizer decides what that identity may do. It fails only with a refusal, `Action.Unauthenticated` or `Action.Forbidden`: any other failure is a type error, and a limit on callers is the handler's. HTTP sends a refusal's JSON with 401 or 403, MCP an `isError` tool result, the Toolkit a returned failure, a CLI command the same JSON on stderr. A step-up refusal on a remote surface is the one exception, below.
+- The services the authorizer yields are request-time requirements, like a handler's, and they join the surface's request context. A local caller (`ActionCli`, `ActionToolkit`, stdio, `Action.client`) supplies them itself. What an Effect building the authorizer yields: [dependency lifetimes](#dependency-lifetimes).
+- A CLI command fails with Effect CLI's `UserError`, whose `cause` is what the authorizer or the handler fails with. Every local command may fail with the action's errors and `Action.BuiltIn` ([ActionCli.md](ActionCli.md#rules)).
+- A step-up refusal is one an OAuth client acts on: `Unauthenticated`, or a `Forbidden` naming `scopes`. Step-up is Bearer's and protected actions': on a protected route of `ActionHttp`, or a protected tool's call on an `ActionMcp.layerHttp` endpoint naming a Bearer authentication descriptor, it answers the request with its HTTP status, 401 or 403, its JSON and its challenge, whether authentication, the authorizer or a handler fails with it. Over HTTP it answers the refusal as it leaves the layer's `middleware`: one that recovers from it keeps its own response, and one that turns it into another error the binding declares answers with that error. A public route's or a public tool's refusal never steps up, signed in or not: over HTTP its JSON with its status, over MCP an `isError` tool result.
+- Over MCP that answer replaces the tool result, as MCP authorization defines, unless a handler's notification already started the response ([ActionMcp.md](ActionMcp.md#rules)). On an endpoint without authentication, or naming a descriptor of another scheme, there is no OAuth client to step up: it is answered like a declared error, an `isError` tool result the model reads, and over HTTP its JSON with its status, without an `insufficient_scope` challenge. A refusal of the authentication itself is still its 401 or 403.
+- A `Forbidden` naming scopes carries the `insufficient_scope` challenge an OAuth client re-authorizes on ([Authentication.md](Authentication.md#rules)). A `Forbidden` naming no scopes is always answered like a declared error.
+- Map another service's refusals before failing with them. A handler calling another service through a client that decodes the built-in errors, such as `ActionHttp.client`, gets that service's `Unauthenticated` or `Forbidden` as a value any handler may fail with; passed on as it is, it is this server's own refusal. On a remote surface it steps up: a caller whose token is valid is sent to sign in again, its 401 naming `invalid_token`, or to re-authorize for the other service's scopes. Map it to an error the action declares, or to a defect.
+- Input decodes before the authorizer. Invalid input skips it and the handler, so a caller the authorizer would refuse can receive schema errors (HTTP's `InvalidInput` message describes the input's schema), as can any caller of a public action. To refuse a caller before decoding, over HTTP only, use the layer's `middleware`, inside authentication, or router middleware around the surface: [ActionHttp.md](ActionHttp.md#rules).
+- A limit on callers goes in one of three places. After decoding, on every surface: the handler, failing with an error its action declares, the limiter a startup service its builder yields, so every surface of the graph counts against one ([Action.md](Action.md#implementations)). Before decoding, over HTTP only: the layer's own `middleware`, which runs after authentication and so may key the limit by the caller, or router middleware around the routes, which runs before authentication; either answers with an error of the binding's `error` ([ActionHttp.md](ActionHttp.md#binding-errors)). Input that does not decode never reaches a handler, so only middleware counts it, and a protected request without a valid credential reaches only router middleware.
+- Types cannot verify that a verifier checks what it should, or that an authorizer states the right rule: the authorizer is the one place the library guarantees runs before the handler of a protected action, so put action-level authorization there. A check on one record, such as whether this actor may rename this user, needs the input and its data: make it in the handler's data access.
+- `readOnly` is contract metadata, required on every action and kept as a literal type. It is a tool's read-only hint, a read-only tool's default `destructiveHint` and the `action.read_only` span/log annotation, but enforces no authorization. An authorizer can switch on what an action does instead of on its name.
 
 ## Wire behavior
 
-Defaults without a schema-error policy. HTTP is a native `HttpApi`; MCP is a native `McpServer` with one `Tool` per action. The library defines no error types of its own.
+HTTP is a native `HttpApi`; MCP is a native `McpServer` with one `Tool` per action. The
+built-in errors are `Action.InvalidInput` (400), `Action.Unauthenticated` (401) and
+`Action.Forbidden` (403), each `{ _tag, message }`; an `InvalidInput` also lists `issues`, empty
+when it names none, and a `Forbidden` may add `scopes`.
 
-| Case                        | HTTP                                                                                                  | MCP                                                                                                    |
-| --------------------------- | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
-| Input                       | decoded with the schema's JSON codec; failure is an empty **400**                                     | decoded with the schema's JSON codec; failure is `InvalidParams`, presented as an `isError` result     |
-| Success                     | the success codec's encoding as the body: `{"id":"1","name":"Ada"}`, `42`                             | `structuredContent: <encoded>`, and its JSON as text content; a text field is sent as text instead     |
-| Declared error              | encoded by its schema with its `httpApiStatus` (unannotated: 500): `{"_tag":"UserNotFound","id":"x"}` | `isError: true`; text content is the same JSON; no `structuredContent`                                 |
-| Pre-handler hook failure    | the same, using the hook's error schema, after input decoding; the handler never runs                 | the same `isError` result, after arguments are decoded; the handler never runs                         |
-| Invalid output encoding     | empty **400** (`HttpApiSchemaError`)                                                                  | `isError: true`, text `Tool execution failed due to an internal server error.`; cause logged, not sent |
-| Defect                      | empty **500**                                                                                         | same generic `isError` result; cause logged, not sent                                                  |
-| Unknown path or method      | 404                                                                                                   | n/a                                                                                                    |
-| Invalid JSON / content type | 400 / 415                                                                                             | n/a                                                                                                    |
+| Case                        | HTTP                                                                                                  | MCP                                                                                                                                                                  |
+| --------------------------- | ----------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Input                       | decoded with the schema's JSON codec; failure is **400** `InvalidInput`, `message` the schema issues  | decoded with the schema's JSON codec; failure is an `isError` result from 2025-11-25 on, and a JSON-RPC `InvalidParams` error before                                 |
+| Success                     | the success codec's encoding as the body: `{"id":"1","name":"Ada"}`, `42`                             | `structuredContent: <encoded>` and its JSON as text on 2026-07-28; earlier stdio revisions structure only an object ([ActionMcp.md](ActionMcp.md#rules))             |
+| Declared error              | encoded by its schema with its `httpApiStatus` (unannotated: 422): `{"_tag":"UserNotFound","id":"x"}` | `isError: true`; text content is the same JSON; no `structuredContent`                                                                                               |
+| Authentication              | a protected route without a valid credential: **401** with a challenge, before its body is read       | a request a protected tool's call or a native feature needs: **401** with a challenge, before its body is read ([ActionMcp.md](ActionMcp.md#rules))                  |
+| Authorizer refusal          | its JSON with its status, **401** / **403**, after input decoding; the handler never runs             | the same `isError` result, after arguments are decoded; on a Bearer-authenticated endpoint a protected tool's step-up refusal is **401** / **403**                   |
+| Invalid output encoding     | a defect: empty **500**                                                                               | `isError: true`, text `Tool execution failed due to an internal server error.`; cause logged, not sent                                                               |
+| Defect                      | empty **500**                                                                                         | same generic `isError` result; cause logged, not sent                                                                                                                |
+| Unknown path or method      | 404                                                                                                   | another path: 404, as HTTP; another HTTP method on the endpoint: an empty **405** with `Allow: POST`; an unknown tool: a JSON-RPC `-32602` error, with 200 over HTTP |
+| Invalid JSON / content type | 400 `InvalidInput` / 415 for a missing or non-JSON type, after authentication on a protected route    | over HTTP, a JSON-RPC `Parse error` (`-32700`) with 200 / an empty **415** for a missing or non-JSON type; over stdio, a line that is not JSON goes unanswered       |
 
-- `mcp.text` changes only the MCP success result. HTTP, OpenAPI, typed clients, the Toolkit, the CLI and its client, and the catalog serve and describe the whole success. A text field's other outcomes are answered as in this table.
-- A group `schemaError` policy replaces the empty 400s on HTTP with a declared error and status: its `invalid` error for input that does not decode, its `internal` error for output that does not encode. It never affects MCP. Details in [ActionGroup.md](ActionGroup.md).
-- `ActionHttp` sets no headers of its own. The host owns cache and challenge headers; `Authentication.middleware` marks its responses `cache-control: no-store`. Hook refusals and handler failures are ordinary declared error responses.
-- Routes are `POST <apiPath>/<group>/<action>`. Operation IDs are `<group>.<action>`. Effect generates OpenAPI component names and references.
-- `ActionHttp.make`'s `errors` are declared on every endpoint so clients decode the surface's own failures (401, 403, 429, 503). They are produced by middleware or by the binding's hook, never by a handler. `ActionMcp` and `ActionToolkit` declare their own `errors` the same way, joined into every tool's failure schema. Two errors may share an HTTP status; their `_tag`s must differ, because the client decodes a status by trying the schemas declared for it.
-- Input is closed. Both transports publish `additionalProperties: false` for input (so does the catalog) and refuse undeclared fields: over HTTP an extra field is an input failure (an empty 400, or the group's `schemaError` `invalid` answer); an MCP tool (`Tool.Strict`) returns an invalid-arguments result. Typed HTTP clients encode input from `Http.api` and fail with `SchemaError` on an undeclared field, before sending. The native Toolkit, `ActionCli` and `ActionCliClient` decode input locally with default options, which drop an undeclared field instead of refusing it.
+- The HTTP surfaces set no header of their own; handler failures are ordinary declared error responses. On a route a Bearer descriptor authenticates, a `Forbidden` naming scopes carries `WWW-Authenticate: Bearer error="insufficient_scope", scope="..."`.
+- Authentication marks every response to a request it authenticates, on a protected HTTP route, an MCP endpoint naming a descriptor or a route of the host's own under `Authentication.protect`, `Cache-Control: no-store`, unless its route states its own caching, such as `private, max-age=31536000, immutable` for a content-addressed download. A covered route stating its own says `private` unless its answer is the same for every caller: a credential a proxy forwards is invisible to a cache in front of that proxy, which may store the answer and serve it to anyone. A failure that enclosing middleware serializes always gets `no-store`, whatever caching it states. An MCP endpoint's answer to a request it does not authenticate, discovery, its listing or a public tool's call without a credential, gets none, as a public HTTP route's does: it reads no credential. It gives every 401 among them without a challenge its scheme's, where the scheme has one, whether authentication, the authorizer or a handler answers it, a failure that enclosing middleware serializes included. As a protected resource, it names its metadata URL in every challenge, and a 401's names `scopesRequired`, and `invalid_token` when the request presented credentials ([Authentication.md](Authentication.md#rules)).
+- A 401 carries a challenge only on a route authentication covers, and only where its scheme has one: Bearer's, an `Http` scheme naming itself, or Basic's with its realm, the descriptor's name. An API key's 401 is the same JSON and `Cache-Control: no-store`, without a challenge ([Authentication.md](Authentication.md#rules)).
+- Routes are `POST <prefix>/<action>`; the prefix defaults to `/api`. Operation IDs are the action names. Effect generates OpenAPI component names and references.
+- Effect reads each request body whole, with no size limit unless the host sets one: provide `Layer.succeed(HttpServerRequest.MaxBodySize, ByteSize.mebibytes(1))` to `HttpRouter.serve`'s layer. The limit covers every route on the server, MCP endpoints and the host's own routes included, except a body a route reads as a stream. Node's server (`NodeHttpServer`) closes the connection of a request over it without a response. `HttpRouter.toWebHandler` ignores it: limit bodies in the platform serving the handler.
+- Every HTTP endpoint and every tool declares `InvalidInput`, `Unauthenticated` and `Forbidden` beyond the action's own errors, and an endpoint its binding's too, so typed callers decode them. Any handler may fail with them; no action or binding lists them, and no error of its own may reuse their tags.
+- They are produced by decoding, by authentication, by an authorizer, or by any handler. A client decodes a status by trying the schemas declared for it, as it decodes any union: errors sharing a `_tag` are told apart by their other fields, the first that decodes winning, so make them disjoint, by a literal field for one. A built-in error is always tried first, so a loose schema of an action's, such as `Schema.Struct({ message: Schema.String })`, never captures one.
+- HTTP refuses undeclared input fields, nested ones too, as the OpenAPI document's `additionalProperties: false` says: the request is a 400 `InvalidInput` naming the field's path. A client drops them when it encodes, since TypeScript lets a wider value through. A record accepts every key its key schema does. A CLI command refuses them too, with an `InvalidInput`, in `--input` and in a flag's JSON. A Toolkit drops them, as Effect decodes a model's tool call. An action without input, `input: {}` given or not, accepts only `{}`, on every surface; over HTTP, an empty JSON body is a 400. MCP tools are strict (`Tool.Strict`): undeclared arguments are invalid arguments, an `isError` result from 2025-11-25 on and a JSON-RPC `InvalidParams` error on earlier stdio revisions. An input that declares its fields publishes `additionalProperties: false` in its schema over HTTP and on MCP ([ActionMcp.md](ActionMcp.md#rules)).
+- An `InvalidInput` for input that does not decode lists `issues`, one `{ path, message }` per issue its `message` describes: `path` holds the keys and indexes from the input's root, `["lines", 1, "count"]`, a symbol key as its string form, `Symbol(name)`, and is empty for the input as a whole. Over HTTP a wrong or missing top-level literal field is such an issue, reported as the whole expected shape. A handler failing with `InvalidInput` may give `issues` of its own, sent as written, and `issues: []` without them: the field is always sent, and the OpenAPI document requires it. MCP's and a Toolkit's native answers have a message only.
+- A message for input that does not decode says what the schema expects and, where Effect's decoder reports one, each issue's path, as does each of an `InvalidInput`'s `issues`; never a value sent, on every surface: `InvalidInput` over HTTP, from a CLI command and from `Action.client`, MCP's invalid-arguments result, a Toolkit's `ToolParameterValidationError`. A path names each key it passes through, an undeclared key and a record's keys included, so a record keyed by an email or a token names it. Effect CLI's own parser, which reads a flag before the schema decodes it, names a rejected choice, an unknown flag or an unexpected argument as typed. A schema's own `message` annotation, or a filter's message, is sent as written, so never put the input in one. Declare a secret `Schema.Redacted`, so what a handler logs of its decoded input prints `<redacted>`; a tool call's span holds it all the same ([observability](#observability)).
+- A CLI command prints the success's encoding on stdout, and a failure on stderr as the JSON HTTP sends: the action's declared error, a binding's, a built-in one, `InvalidInput` included. A success that does not encode is a defect there too, which the command does not print ([ActionCli.md](ActionCli.md#rules)).
+- An `Action.client` call passes its input, its success and its failure through their JSON codecs, encoded then decoded, as HTTP carries them, so its handler and its caller get what a remote call's would. A success or a failure that does not pass, an error its action does not declare included, is a defect, as it is an empty 500 over HTTP ([Action.md](Action.md#clients)).
+- A failure an action does not declare, which the types refuse but plain JavaScript or a cast lets through, is answered by each surface its own way: `Action.client` dies with a defect, HTTP answers an empty 500, MCP its internal-error tool result, `Tool execution failed due to an internal server error.`, a local CLI command fails with `UserError` whose `cause` is that failure, and a Toolkit call fails with an `AiError`, `Failed to encode result`. Declare every error a handler may fail with.
 
-## Namespaces
+## Names
 
-- Group names are unique within one `ActionHttp.make`. Action names are unique within a group. MCP tool names are unique within each Toolkit or MCP projection that serves them; a group does not check them.
-- Adapters validate only the namespace they serve. HTTP does not check tool names; MCP does not check route names.
-- Each adapter builds only what it serves. HTTP serves every action of a group it binds, so `Http.layer` builds every implementation it is given (except a group without actions); a group with no tools is not built by MCP or Toolkit.
+- Action names are unique within one HTTP binding; two bindings with different prefixes may reuse one, but then cannot be combined into one `HttpApi`. A tool is named after its action, so action names are also unique within each Toolkit or MCP endpoint that serves them, and kebab-case command names within each aggregate CLI command. A client's method is too, so they are unique within each `Action.client`.
+- Surfaces validate only the names they serve. HTTP does not check tool names; MCP does not check route names.
+- `ActionHttp.layer`, MCP, a Toolkit and `ActionCli.make` expose the actions their `actions` option lists, or every action of the implementations without it, `ActionHttp.layer` only those its binding holds; `ActionCli.command` exposes only its selected action. `Action.client` exposes every action of the implementations passed to it. A selected action keeps its implementation's authorizer, and its builder's one run. Selection never changes policy: an action's `caller` and authorizer are the same wherever it is served. Builder acquisition follows the [dependency lifetimes](#dependency-lifetimes), including explicit `Action.layer` prebuilding and per-invocation CLI selection: a surface's `actions` leaving out every action of an implementation leaves that implementation unbuilt.
+- Surfaces match an implementation to a contract by object identity, never by name. `ActionHttp.layer` refuses implementations holding none of its binding's actions, and serves no action its binding does not hold, whatever its name; an `actions` option refuses a listed action the binding does not hold, or none of the implementations holds, or `ActionCli.remote` one its binding does not, marking one of a held name as another contract; `ActionCli.command` refuses an action with no implementation in its list.
+- An `actions` option narrows a surface's types only where it is always given. Options whose `actions` may be absent, an optional property or a union with options lacking it, serve every action when it is absent and the listed ones when given, so their types owe what every action owes; `Action.client` offers methods, and `ActionToolkit.make` tools, only for the actions such options may list, which it has either way. An explicit type argument names the options' type, not the actions, and requires the options argument: `ActionMcp.layerHttp<typeof app, { readonly actions: readonly [typeof Status] }>(...)`. A misspelled option is a type error on every surface, beside `actions` too, and in any member of a union of options. A CLI's `commands` key naming no action of the binding or the implementations is refused; one naming an action the list leaves out is unused, so one record serves aggregates of several selections.
+- A list of actions is typed by its members, on every surface and in `Action.byName`: `[A, B]` holds `A` and `B`. A list narrowed at runtime, such as an `Array` of a union, a filtered list or a conditional element, is still typed as holding every member, and what it does not hold is absent where it is read: `byName` has no entry for it, a client no method, and `implement` refuses its handler, `Unknown handlers: <name>`. Build a list from the contracts themselves.
 
 ## Observability
 
-- Each handler runs in a span named `<group>.<action>`, a child of the transport's request span, with attributes `action.group`, `action.name` and `action.access`. Every log line the handler writes carries the same three annotations. The pre-handler hook, decoding and encoding happen outside the handler span.
+- Each handler runs in a span named after its action, a child of the transport's request span, or of its caller's through `Action.client`, with attributes `action.name` and `action.read_only`, a boolean. Every log line the handler writes carries the same two annotations. Names are unique per binding; the request span's route tells two bindings' same-named actions apart. Authentication, decoding, the authorizer and encoding happen outside the handler span.
 - MCP defects and encoding failures are logged with their cause and answered generically.
+- Over `ActionHttp` and `ActionMcp.layerHttp`, a handler's defect reaches the `ErrorReporter`s provided to the surface's layer once.
+- Every MCP tool call, over HTTP and over stdio, and every Toolkit call runs through Effect's `Toolkit.handle`, which records the call's arguments as sent on the current span, as the attribute `parameters`: a tracer the host installs receives them, a `Schema.Redacted` field's value included, which a handler's logs print `<redacted>`. HTTP records no request body. Where a tracer exports spans, keep an action that takes a secret off tools ([Action.md](Action.md#contracts)).
 
 ## MCP transport
 
-- MCP 2026-07-28 is the only revision served, on both transports; there is no option to select another. Effect owns version checks and rejects other revisions. Over HTTP the endpoint is stateless: no initialize handshake and no session.
-- `layerHttp` is single-endpoint Streamable HTTP, never two-endpoint HTTP+SSE.
-- Cancellation is Effect's native RPC interruption. Without an HTTP session, `notifications/cancelled` interrupts nothing over HTTP; a call ends with its request.
-- Each endpoint or subprocess owns a fresh native tool registry. That isolates names, not application context.
+Protocol revisions, transport behavior, cancellation, and tool registry isolation are defined
+in [ActionMcp.md](ActionMcp.md#rules).
 
 ## Scope
 
-- HTTP is JSON `POST` on `HttpApi`, not Effect RPC. MCP is native `McpServer`, no SDK runtime dependency.
-- Actions are unary: no streaming, uploads, prompts, resources, retries, or code-execution sandbox.
-- Authentication and authorization are the application's. The library supplies the seams: `Authentication.middleware` for identity, one `before` hook per surface for the authorization rule, `access` for what a rule reads, and each surface's `errors` for what a caller can decode. It defines no error types, no scopes and no verifier. Tool discovery is not filtered by actor. Production needs real token validation, MCP authorization discovery, request limits, and error reporting.
-- The catalog is descriptive. Presence in it grants nothing.
+What the package does, and nothing else:
+
+- HTTP means JSON `POST` endpoints built on Effect's `HttpApi`. It is not Effect RPC.
+- MCP means one native `McpServer` `Tool` per action over HTTP or stdio; supported revisions follow [ActionMcp.md](ActionMcp.md#rules). There is no MCP SDK runtime dependency.
+- Actions are unary: one decoded input, one decoded success or one declared error. No streaming, uploads, prompts, resources, retries, or code-execution sandbox.
+- Authentication and authorization are the application's. The library supplies the seams:
+  - `caller` on each contract, enforced by every surface;
+  - `Authentication.make` and `Authentication.layer`, a named declaration of one native scheme, Bearer by default, and its verifier, enforced and documented with native endpoint security;
+  - one `authorize` for the authorization rule, bound to an implementation of protected actions and run by every surface, `Action.allowAll` where there is none;
+  - `readOnly`, for what a rule reads;
+  - the built-in refusals every caller decodes.
+- It defines no scopes and no verifier: a refusal names the scopes a call lacks, and the library answers with the OAuth challenge. A descriptor names one native scheme, Bearer by default: a session cookie, an API key or Basic is the descriptor's scheme, which its verifier receives decoded. OAuth, its challenges, discovery and step-up, is Bearer's. One identity per action, and one per remote surface. Tool discovery is not filtered by actor. Production needs real token validation, request limits, and error reporting.

package/docs/setup.md

@@ -1,19 +1,19 @@
 # Setup
 
-Install, version pins, entry points, and the boundaries of the package.
+Installation, version pins, entry points, a minimal program, and package boundaries.
 
 ## Install
 
 ```sh
-pnpm add @gjermundgaraba/effect-actions effect@4.0.0-rc.118
+pnpm add @gjermundgaraba/effect-actions effect@~4.0.0
 ```
 
-| Need                           | Add                                                   |
-| ------------------------------ | ----------------------------------------------------- |
-| Node HTTP server or stdio host | `@effect/platform-node@4.0.0-rc.118`                  |
-| `TestingClient.withMcpClient`  | `@modelcontextprotocol/client@^2.0.0` (optional peer) |
+| Need                                | Add                            |
+| ----------------------------------- | ------------------------------ |
+| Node HTTP server, stdio host or CLI | `@effect/platform-node@~4.0.0` |
 
-Node `^22.12.0 || ^24.0.0 || >=26.0.0`. ESM only.
+Node `^22.12.0 || ^24.0.0 || >=26.0.0`. TypeScript 7 or newer; earlier versions are not
+supported. ESM only.
 
 ## Entry points
 
@@ -21,45 +21,108 @@ There is no package root. Import one module per subpath, as a namespace:
 
 ```ts
 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 ActionHttpClient from "@gjermundgaraba/effect-actions/ActionHttpClient";
 import * as ActionMcp from "@gjermundgaraba/effect-actions/ActionMcp";
 import * as ActionToolkit from "@gjermundgaraba/effect-actions/ActionToolkit";
-import * as ActionCatalog from "@gjermundgaraba/effect-actions/ActionCatalog";
 import * as ActionCli from "@gjermundgaraba/effect-actions/ActionCli";
-import * as ActionCliClient from "@gjermundgaraba/effect-actions/ActionCliClient";
 import * as Authentication from "@gjermundgaraba/effect-actions/Authentication";
 import * as Testing from "@gjermundgaraba/effect-actions/Testing";
-import * as TestingClient from "@gjermundgaraba/effect-actions/TestingClient";
 ```
 
-Every module imports from the `effect` package only, with two exceptions worth knowing when
-bundling: `ActionMcp` and `ActionToolkit` are the only modules that import `effect/ai`,
-and `TestingClient` is the only module that imports the optional `@modelcontextprotocol/client`
-peer. Because there is no package root, importing a contract module never pulls in an MCP
-server or the peer.
+Every module imports from the `effect` package only. There is no package root, so importing
+`Action` or `ActionHttp` never pulls in an MCP server or the AI toolkit.
+
+## Minimal program
+
+```ts example=quickstart.ts
+import { Schema } from "effect";
+import * as Action from "@gjermundgaraba/effect-actions/Action";
+import * as ActionHttp from "@gjermundgaraba/effect-actions/ActionHttp";
+
+// The contract and its HTTP binding import no server code, so any client can import them,
+// a browser page included.
+export const Greet = Action.make("greet", {
+  description: "Greet someone by name.",
+  input: { name: Schema.String },
+  success: Schema.String,
+  readOnly: true,
+  caller: Action.Anyone,
+});
+
+export const Http = ActionHttp.make([Greet]);
+```
+
+The server, in its own module, so that a browser client imports the contract alone:
+
+```ts example=quickstart-server.ts
+import { Effect, Layer } from "effect";
+import * as Action from "@gjermundgaraba/effect-actions/Action";
+import * as ActionHttp from "@gjermundgaraba/effect-actions/ActionHttp";
+import * as ActionMcp from "@gjermundgaraba/effect-actions/ActionMcp";
+import { Greet, Http } from "./quickstart.js";
+
+// The contract states who may call it, here anyone, so its implementation takes no `authorize`.
+const greet = Action.implement(Greet, ({ name }) => Effect.succeed(`Hello, ${name}!`));
+
+export const routes = Layer.mergeAll(
+  ActionHttp.layer(Http, greet),
+  ActionMcp.layerHttp(greet, { name: "greetings", version: "1.0.0" }),
+);
+```
+
+Serve `routes` with `HttpRouter.serve` and a platform server layer, with a request body limit ([guarantees.md](guarantees.md#wire-behavior)). Result: `POST /api/greet` and an MCP tool `greet` at `/mcp`. Anything else the process runs, such as a job or an agent, goes inside the layer `HttpRouter.serve` serves, not merged beside it: beside it, the builders and your own services it shares with the routes may run twice, each with state of its own, and nothing reports it ([dependency lifetimes](guarantees.md#dependency-lifetimes)).
+
+## Browser
+
+A browser app calls the server with `ActionHttp.client`, or `ActionHttp.fetchClient` outside an
+Effect. It needs the contracts, their identities, the HTTP binding and its authentication
+descriptor, and nothing else of the server. The package
+declares `"sideEffects": false`, so a bundler may drop what a client does not use. Keep the
+contracts and the binding in modules that import no server code, and import those alone from
+the page, as the minimal program does:
+
+```text
+identity.ts     Context.Service declarations a protected contract names: imports effect only
+contracts.ts    Action.make(...), Authentication.make(...) and ActionHttp.make([...])
+handlers.ts     Action.implement(...): services, database, @effect/platform-node
+server.ts       ActionHttp.layer, ActionMcp, Authentication.layer and its verifier
+```
+
+A module that calls `Action.implement` beside its contracts brings its handlers, and every
+module they import, into the browser bundle: bundlers keep the call as written, even unused.
+Split it. A page on another origin also needs CORS on the host, outside authentication: see
+the browser example in [ActionMcp.md](ActionMcp.md#cross-origin-browsers).
+
+`Action`, `ActionHttp` and `Authentication`, and every module they import, import Effect through three
+specifiers alone: `effect`, `effect/http` and `effect/http-api`. A page that loads Effect from
+an import map rather than its bundle maps those three. A map pointing at Effect 4.0.0's
+published files maps `effect/Cause`, `effect/Effect`, `effect/Exit` and `effect/Function` too,
+to the same files the `effect` barrel loads, as Effect's own `Runtime` module imports them by
+name; a build or CDN that resolves Effect's own imports needs only the three.
+Serve each of the three whole. A page that re-exports only the names it uses, from a vendored
+module or a trimmed bundle, fails at load with `does not provide an export named …` once the
+package imports another name from the same specifier, as a release may: check such a list
+against the package's imports on every upgrade.
 
 Companion Effect modules you will import alongside: `effect/http-api` (`HttpApiClient`, `OpenApi`, `HttpApiSwagger`, `HttpApiScalar`), `effect/http` (`HttpRouter`, `HttpServerResponse`, `FetchHttpClient`, `HttpClientError`), `effect/cli` (`Command`, `Flag`, `Argument`).
 
 ## Rules
 
-- Install a single `effect` version within the peer range, and keep every `@effect/*` package on that same release candidate. Mixed rc versions fail at the type level in ways that look like library bugs.
+- Install a single `effect` version within the peer range, and keep every `@effect/*` package on that same release. Mixed versions can fail at the type level in ways that look like library bugs.
 - Never import from `dist/` paths or from a package root. Only the subpaths above are public.
 - Schemas passed to `Action.make` must be service-free (`Schema.Codec<_, _, never, never>`). Handlers may require services.
 
 ## Scope
 
-What the package does, and nothing else:
-
-- HTTP means JSON `POST` endpoints built on Effect's `HttpApi`. It is not Effect RPC.
-- MCP means one native `McpServer` `Tool` per action, over MCP 2026-07-28 only. There is no MCP SDK runtime dependency.
-- Actions are unary: one decoded input, one decoded success or one declared error. No streaming, uploads, prompts, resources, retries, or code-execution sandbox.
-- Authentication and authorization are the application's. The library provides the seams — `Authentication.middleware` for identity, one `before` hook per surface for the authorization rule, `access` for what that rule reads, each surface's `errors` for what a caller can decode — and no token verifier, error types or scopes of its own. Tool discovery is never filtered by actor.
+What the package does and does not do: [guarantees.md](guarantees.md#scope).
 
 ## Failure modes
 
 - `Cannot find module '@gjermundgaraba/effect-actions'`: there is no root export. Import a subpath.
-- Type errors inside `effect/*` modules after install: `effect` version drift. Install one `effect` release candidate within the peer range for every package.
-- `Cannot find module 'effect/http'` (or `effect/http-api`, `effect/cli`, `effect/ai`): `effect` is older than `4.0.0-rc.118`, which moved these modules out of `effect/unstable/*`. Install a release candidate within the peer range, and import from the new paths.
-- `@modelcontextprotocol/client` resolution errors in a server build: something imported `TestingClient`. Only tests should.
+- A browser build fails with `Could not resolve "node:…"`, or warns `Module "node:…" has been externalized for browser compatibility`: the page imports a module that also holds server code, such as a contract beside its `Action.implement`, or an authentication descriptor beside its `Authentication.layer` verifier. Move the contracts, their identities, the descriptor and the binding to modules that import no server code.
+- A page that loads Effect from an import map still bundles a second copy of Effect, or of some of its modules: a module of the page imports an Effect specifier the map does not serve, such as `effect/Schema`. Serve `effect`, `effect/http` and `effect/http-api`, all `Action`, `ActionHttp` and `Authentication` import, and import Effect through them in the page's own modules too.
+- A page loading Effect from an import map fails before its modules run, with `Failed to resolve module specifier "effect/Cause"` in Chromium: the map points at Effect's published files and lacks a specifier Effect imports itself. Map `effect/Cause`, `effect/Effect`, `effect/Exit` and `effect/Function` to the same files, or serve Effect from a build that resolves its own imports.
+- Type errors inside `effect/*` modules after install: `effect` version drift. Install one `effect` 4.0.x release for every package.
+- An unmet peer warning for `effect@~4.0.0`, such as `found 4.1.0`: the installed Effect is a later minor than this release has been tested against. Install `effect` 4.0.x, with every `@effect/*` package on the same release, until a release of this package admits that minor.
+- `Cannot find module 'effect/unstable/http'` (or `…/httpapi`, `…/cli`, `…/ai`): Effect `4.0.0-rc.118` moved these modules to `effect/http`, `effect/http-api`, `effect/cli` and `effect/ai`. Import the new paths.
+- `Cannot find module 'effect/http'` (or `effect/http-api`, `effect/cli`, `effect/ai`), or at run time `Cannot find module '…/node_modules/effect/dist/http-api.js'` (or `http.js`, `ai.js`, `cli.js`): `effect` is a release candidate older than `4.0.0-rc.118`, which moved these modules out of `effect/unstable/*`. Install `effect` 4.0.0 or later.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gjermundgaraba/effect-actions",
-  "version": "0.8.0",
-  "description": "Define Effect action contracts once and project them onto HTTP, MCP, native Toolkits, catalogs, and CLIs.",
+  "version": "0.10.0",
+  "description": "Define Effect action contracts once and project them onto HTTP, MCP, native Toolkits, and CLIs.",
   "homepage": "https://github.com/gjermundgaraba/effect-actions#readme",
   "bugs": {
     "url": "https://github.com/gjermundgaraba/effect-actions/issues"
@@ -16,42 +16,34 @@
     "docs"
   ],
   "type": "module",
+  "sideEffects": false,
   "exports": {
     "./Action": "./dist/Action.mjs",
-    "./ActionCatalog": "./dist/ActionCatalog.mjs",
     "./ActionCli": "./dist/ActionCli.mjs",
-    "./ActionCliClient": "./dist/ActionCliClient.mjs",
-    "./ActionGroup": "./dist/ActionGroup.mjs",
     "./ActionHttp": "./dist/ActionHttp.mjs",
-    "./ActionHttpClient": "./dist/ActionHttpClient.mjs",
     "./ActionMcp": "./dist/ActionMcp.mjs",
     "./ActionToolkit": "./dist/ActionToolkit.mjs",
     "./Authentication": "./dist/Authentication.mjs",
     "./Testing": "./dist/Testing.mjs",
-    "./TestingClient": "./dist/TestingClient.mjs",
     "./package.json": "./package.json"
   },
   "publishConfig": {
     "access": "public"
   },
   "devDependencies": {
-    "@effect/platform-node": "4.0.0-rc.118",
+    "@effect/platform-node": "4.0.0",
+    "@effect/vitest": "4.0.0",
     "@modelcontextprotocol/client": "2.0.0",
     "@types/node": "26.6.2",
-    "effect": "4.0.0-rc.118",
+    "effect": "4.0.0",
     "tsx": "4.23.15",
     "typescript": "7.0.2",
     "vite": "npm:@voidzero-dev/vite-plus-core@1.0.0",
-    "vite-plus": "1.0.0"
+    "vite-plus": "1.0.0",
+    "vitest": "5.0.1"
   },
   "peerDependencies": {
-    "@modelcontextprotocol/client": "^2.0.0",
-    "effect": ">=4.0.0-rc.118 <4.0.0"
-  },
-  "peerDependenciesMeta": {
-    "@modelcontextprotocol/client": {
-      "optional": true
-    }
+    "effect": "~4.0.0"
   },
   "devEngines": {
     "packageManager": {

package/dist/ActionCatalog.d.mts

@@ -1,30 +0,0 @@
-import { Action_d_exports, Any } from "./Action.mjs";
-import { ActionGroup_d_exports, Any as Any$1 } from "./ActionGroup.mjs";
-import { JsonSchema } from "effect";
-//#region src/ActionCatalog.d.ts
-/** One contract, with independently rooted descriptions of its encoded values. */
-export interface Entry {
-  readonly id: string;
-  readonly group: string;
-  readonly name: string;
-  readonly description: string;
-  readonly mcp: Any["mcp"];
-  readonly input: JsonSchema.JsonSchema;
-  readonly success: JsonSchema.JsonSchema;
-  /** Includes the errors inherited from the group; not HTTP schema-policy errors. */
-  readonly errors: ReadonlyArray<JsonSchema.JsonSchema>;
-  /** HTTP-only decoding/encoding policy errors, separate from handler failures. */
-  readonly httpSchemaErrors: ReadonlyArray<JsonSchema.JsonSchema>;
-}
-/** An offline contract document, not an authorization decision or a mounted endpoint. */
-export interface Catalog {
-  readonly version: "4";
-  readonly actions: ReadonlyArray<Entry>;
-}
-/**
- * Describe the supplied groups without acquiring implementations. Schemas describe
- * encoded action values, not MCP's `{ value }` envelope or deployment-specific URLs.
- * The host chooses what, if anything, to publish.
- */
-export declare const make: (...groups: ReadonlyArray<Any$1>) => Catalog;
-//#endregion

package/dist/ActionCatalog.mjs

@@ -1,39 +0,0 @@
-import { assertDistinct, policyErrors } from "./internal/actions.mjs";
-import { JsonSchema, Schema } from "effect";
-//#region src/ActionCatalog.ts
-/**
-* Describe the JSON wire form closed, as the OpenAPI document does; decoding on the
-* server remains authoritative.
-*/
-const describe = (codec) => {
-	const { schema, definitions } = Schema.toJsonSchemaDocument(codec, { onExcessProperty: "error" });
-	return {
-		$schema: JsonSchema.META_SCHEMA_URI_DRAFT_2020_12,
-		...schema,
-		...Object.keys(definitions).length === 0 ? {} : { $defs: definitions }
-	};
-};
-/**
-* Describe the supplied groups without acquiring implementations. Schemas describe
-* encoded action values, not MCP's `{ value }` envelope or deployment-specific URLs.
-* The host chooses what, if anything, to publish.
-*/
-const make = (...groups) => {
-	assertDistinct("catalog group", groups.map((group) => group.name));
-	return {
-		version: "4",
-		actions: groups.flatMap((group) => group.actions.map((action) => ({
-			id: `${group.name}.${action.name}`,
-			group: group.name,
-			name: action.name,
-			description: action.description,
-			mcp: action.mcp,
-			input: describe(action.input),
-			success: describe(action.success),
-			errors: action.errors.map(describe),
-			httpSchemaErrors: group.schemaError === void 0 ? [] : policyErrors(group.schemaError).map(describe)
-		})))
-	};
-};
-//#endregion
-export { make };

package/dist/ActionCliClient.d.mts

@@ -1,48 +0,0 @@
-import { Action_d_exports, Codec } from "./Action.mjs";
-import { Actions } from "./internal/actions.mjs";
-import { Options as Options$1 } from "./internal/cli.mjs";
-import { ActionHttp_d_exports, Api, Http } from "./ActionHttp.mjs";
-import { Effect } from "effect";
-import { HttpClient } from "effect/http";
-import { HttpApi, HttpApiClient, HttpApiEndpoint, HttpApiGroup } from "effect/http-api";
-import { Command } from "effect/cli";
-//#region src/ActionCliClient.d.ts
-/**
- * What the host configures on Effect's native client: `baseUrl`, `transformClient`,
- * `transformResponse`. The selectors and the client are the command's own.
- */
-export type Connection = NonNullable<globalThis.Parameters<typeof HttpApiClient.make>[1]>;
-/** Parsing, rendering and native HTTP-endpoint configuration for one remote action. */
-export type Options<Output, ParsedParameters extends Command.Command.Config = never> = Options$1<Output, ParsedParameters> & {
-  readonly connection?: Connection;
-};
-/** Configuration for a remote aggregate group command. */
-export interface GroupOptions {
-  /** Override the group command name. */
-  readonly name?: string;
-  /** Shared native HTTP-endpoint configuration for every remote action. */
-  readonly connection?: Connection;
-}
-type Group<Groups extends ReadonlyArray<Actions>, Name extends Groups[number]["name"]> = Extract<Groups[number], {
-  readonly name: Name;
-}>;
-type Selected<G extends Actions, Name extends G["actions"][number]["name"]> = Extract<G["actions"][number], {
-  readonly name: Name;
-}>;
-type ActionNames<G extends Actions> = G["actions"][number]["name"];
-type ApiGroups<Groups extends ReadonlyArray<Actions>, Errors extends ReadonlyArray<Codec>> = Api<Groups[number], Errors[number]> extends HttpApi.HttpApi<"actions", infer ApiGroups> ? ApiGroups : never;
-type Endpoint<Groups extends ReadonlyArray<Actions>, Errors extends ReadonlyArray<Codec>, GroupName extends Groups[number]["name"], ActionName extends ActionNames<Group<Groups, GroupName>>> = Extract<HttpApiGroup.EndpointsWithIdentifier<ApiGroups<Groups, Errors>, Extract<GroupName, HttpApiGroup.Identifier<ApiGroups<Groups, Errors>>>>, {
-  readonly identifier: ActionName;
-}>;
-type NativeMethod<Groups extends ReadonlyArray<Actions>, Errors extends ReadonlyArray<Codec>, GroupName extends Groups[number]["name"], ActionName extends ActionNames<Group<Groups, GroupName>>> = HttpApiClient.Client.Method<Extract<Endpoint<Groups, Errors, GroupName, ActionName>, HttpApiEndpoint.ConstraintRequest>, never, never>;
-type RemoteCommand<Groups extends ReadonlyArray<Actions>, Errors extends ReadonlyArray<Codec>, GroupName extends Groups[number]["name"], ActionName extends ActionNames<Group<Groups, GroupName>>> = Command.Command<string, never, {}, Effect.Error<ReturnType<NativeMethod<Groups, Errors, GroupName, ActionName>>>, HttpClient.HttpClient | Effect.Services<ReturnType<NativeMethod<Groups, Errors, GroupName, ActionName>>>>;
-type RemoteGroupCommand<Groups extends ReadonlyArray<Actions>, Errors extends ReadonlyArray<Codec>, GroupName extends Groups[number]["name"]> = Command.Command<string, {}, {}, Effect.Error<ReturnType<NativeMethod<Groups, Errors, GroupName, ActionNames<Group<Groups, GroupName>>>>>, HttpClient.HttpClient | Effect.Services<ReturnType<NativeMethod<Groups, Errors, GroupName, ActionNames<Group<Groups, GroupName>>>>>>;
-/**
- * Project one action of the binding into a native Effect CLI command.
- * Group and action selectors resolve exclusively from `http.groups`; runtime guards
- * keep dynamically supplied selector strings from reaching the native client.
- */
-export declare const command: <const Groups extends ReadonlyArray<Actions>, const Errors extends ReadonlyArray<Codec>, const GroupName extends Groups[number]["name"], const ActionName extends ActionNames<Group<Groups, GroupName>>, ParsedParameters extends Command.Command.Config = never>(http: Http<Groups, Errors>, groupName: GroupName, actionName: ActionName, options?: Options<Selected<Group<Groups, GroupName>, ActionName>["success"]["Type"], ParsedParameters>) => RemoteCommand<Groups, Errors, GroupName, ActionName>;
-/** Project every action of one bound group below its group namespace. */
-export declare const group: <const Groups extends ReadonlyArray<Actions>, const Errors extends ReadonlyArray<Codec>, const GroupName extends Groups[number]["name"]>(http: Http<Groups, Errors>, groupName: GroupName, options?: GroupOptions) => RemoteGroupCommand<Groups, Errors, GroupName>;
-//#endregion