@gjermundgaraba/effect-actions 0.9.0 → 0.10.0

package/README.md

@@ -1,94 +1,99 @@
 # effect-actions
 
 Define an Effect action once. Serve it over HTTP and MCP, hand it to a model as a native
-Toolkit, run it from a CLI, and publish its contract as JSON. Same schemas, same handler,
-Effect's own servers and clients underneath.
+Toolkit, and run it from a CLI. Same schemas, same handler, Effect's own servers and clients
+underneath.
 
 ## Looks like this
 
-```ts
-import { Effect, Layer, Schema } from "effect";
+```ts example=quickstart.ts
+import { Schema } from "effect";
 import * as Action from "@gjermundgaraba/effect-actions/Action";
-import * as ActionGroup from "@gjermundgaraba/effect-actions/ActionGroup";
 import * as ActionHttp from "@gjermundgaraba/effect-actions/ActionHttp";
-import * as ActionMcp from "@gjermundgaraba/effect-actions/ActionMcp";
 
-const Greet = Action.make("greet", {
+// 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: Schema.Struct({ name: Schema.String }),
+  input: { name: Schema.String },
   success: Schema.String,
-  access: "read",
+  readOnly: true,
+  caller: Action.Anyone,
 });
 
-export const Actions = ActionGroup.make({ name: "greetings" }, Greet);
+export const Http = ActionHttp.make([Greet]);
+```
 
-export const Http = ActionHttp.make({ apiPath: "/api/actions" }, Actions);
+and a server that implements it, in a module of its own:
 
-const app = Actions.implement({
-  greet: ({ name }) => Effect.succeed(`Hello, ${name}!`),
-});
+```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(
-  Http.layer([app]),
-  ActionMcp.layerHttp([app], {
-    name: "greetings",
-    version: "1.0.0",
-    path: "/mcp",
-  }),
+  ActionHttp.layer(Http, greet),
+  ActionMcp.layerHttp(greet, { name: "greetings", version: "1.0.0" }),
 );
 ```
 
-Serve `routes` with Effect's `HttpRouter` and you have `POST /api/actions/greetings/greet`
-and an MCP tool named `greet` at `/mcp`. The same `app` is also:
+Serve `routes` with Effect's `HttpRouter.serve` and a platform server, with a request body
+limit, as [examples/server.ts](examples/server.ts) serves the example application, and you
+have `POST /api/greet` and an MCP tool named `greet` at `/mcp`. The same `greet`
+implementation is also:
 
 ```ts
-const { toolkit, layer } = ActionToolkit.make([app]); // native Effect AI Toolkit and its handler layer
-const cli = ActionCli.group(app); // greetings greet --input '{"name":"Ada"}'
-const remote = ActionCliClient.command(Http, "greetings", "greet"); // same command, over HTTP
-const catalog = ActionCatalog.make(Actions); // offline JSON contract, no handlers acquired
+const { toolkit, layer } = ActionToolkit.make(greet); // native Effect AI Toolkit and its handler layer
+const cli = ActionCli.make(greet, { name: "greetings" }); // greetings greet --name Ada
+const remote = ActionCli.remoteCommand(Http, Greet, { client: { baseUrl } }); // greet --name Ada, over HTTP
+const local = Action.client(greet); // the HTTP client's methods, in process
 ```
 
-And the client is Effect's own, typed from the same contract:
+And the client is Effect's own `HttpApiClient`, typed from the same contract, one method per action:
 
 ```ts
 const greeting = Effect.gen(function* () {
-  const client = yield* HttpApiClient.make(Http.api, { baseUrl });
+  const client = yield* ActionHttp.client(Http, { baseUrl });
 
-  return yield* client.greetings.greet({ payload: { name: "Ada" } });
+  return yield* client.greet({ name: "Ada" });
 });
 ```
 
-Code that does not run Effects, such as a browser page, gets the same calls as Promises:
-`await ActionHttpClient.promise(Http, { baseUrl }).greetings.greet({ name: "Ada" })`.
-
 ## Why
 
-- Input, success, and errors are declared once. Routes, tools, commands, clients, OpenAPI, and the catalog are derived from that declaration, so they cannot disagree.
-- A handler may fail only with the errors its action declares. Each surface binds one `before` hook that runs before every handler it serves — after successful input decoding — so a policy such as scope enforcement is written once per surface and no action of that surface can skip it.
-- The pieces are Effect's own. `Http.api` is a native `HttpApi`, so `OpenApi.fromApi`, Swagger, Scalar, and `HttpApiClient` work on it unchanged. MCP is Effect's native `McpServer`, one `Tool` per action, with no SDK runtime dependency.
-- Every action states its `access` (`"read"` or `"write"`, required), so authorization reads the contract instead of a hand-maintained list of mutation names.
-- Build-time services and per-request services are tracked separately in the types. Middleware is per group, so a public group and an authenticated group can share one mount path.
-- Tests run in memory. Call the routes through a web handler with the same typed client, or drive the official MCP client, without opening a port.
+- Input, success and errors are declared once. Routes, tools, CLI flags, clients and the OpenAPI document are derived from that declaration, so they cannot disagree.
+- A handler can fail only with the errors its action declares and three built-in ones, and every client decodes them as typed values. Bad input, a missing credential and a refusal come back as those built-in errors (400, 401, 403), never as an unreadable body.
+- Every contract states who may call it: `caller: Action.Anyone`, or the identity service a caller must have. A surface serving a protected action authenticates it before decoding its input, through the authentication descriptor its binding names, and the provider the application builds from its own token verifier.
+- Action-level authorization is written once, on the implementation: `Action.implement(actions, handlers, { authorize })`, required for protected actions. Every surface that serves it runs the rule before each handler, so no surface can leave it out and no handler repeats the access policy; `Action.allowAll` admits every authenticated caller. Operational limits, such as a rate limit, and record-level checks stay in the handler, failing with errors the contract lists.
+- Every action states whether it is read-only (`readOnly`), so that rule reads the contract instead of a hand-maintained list of mutation names.
+- A protected action's handler and rule read the identity its contract names, which only authentication of that request supplies; a startup identity never opens a protected route. Public and protected routes share one binding, one mount path, one OpenAPI document, which states the credentials each needs, and one client, and a handler's startup services are built once per [layer graph](docs/guarantees.md#dependency-lifetimes), however many surfaces serve it.
+- The pieces are Effect's own. `Http.api` is a native `HttpApi`, so OpenAPI, Swagger, Scalar and `HttpApiClient` work on it unchanged. MCP is Effect's native `McpServer`, with no SDK runtime dependency.
+- Tests run in memory. `Action.client` calls an implementation in process, with the typed client's methods, behind its `authorize`, as several callers in one test. Provide `Testing.layer(routes)`, then call the routes with the same typed client and the tools with `Testing.mcpClient`, without opening a port.
 
 ## Install
 
 ```sh
-pnpm add @gjermundgaraba/effect-actions effect@^4.0.0
+pnpm add @gjermundgaraba/effect-actions effect@~4.0.0
 ```
 
-Add `@effect/platform-node@^4.0.0` to serve from Node. Every module is a subpath import
-(`.../Action`, `.../ActionHttp`, ...); there is no package root, so a contracts-only bundle
-never loads a server.
+Add `@effect/platform-node@~4.0.0` to serve or run a CLI from Node. Every module is a
+subpath import (`.../Action`, `.../ActionHttp`, ...); there is no package root, so a
+contracts-only bundle never loads a server.
 
 ## Docs
 
 The reference in [docs/](docs/README.md) is written for coding agents: one card per module
 with the API, a canonical snippet, the rules, and the failure modes.
 
-- [docs/README.md](docs/README.md): start here, includes the adapter decision list.
+- [docs/README.md](docs/README.md): start here, includes which module to use for which caller.
 - [docs/guarantees.md](docs/guarantees.md): cross-cutting rules for lifetimes, wire formats, and scope.
 - [docs/CONTEXT.md](docs/CONTEXT.md): the vocabulary the docs and the code use.
-- [examples/](examples/README.md): a runnable authenticated application with three groups, two MCP endpoints, OpenAPI, and every other projection.
+- [examples/](examples/README.md): a runnable authenticated application with public and authenticated actions, an MCP endpoint, OpenAPI, and every other surface.
 
 ## For agents
 
@@ -96,18 +101,20 @@ with the API, a canonical snippet, the rules, and the failure modes.
 npx skills add gjermundgaraba/effect-actions --skill effect-actions
 ```
 
-The skill is generated from `docs/`, so pointing an agent at `docs/` (in this repository or
-in `node_modules/@gjermundgaraba/effect-actions/docs`) gives the same content.
+The skill is generated from `docs/` on the main branch, which can be ahead of the latest
+release; in a project that installs the package, point the agent at
+`node_modules/@gjermundgaraba/effect-actions/docs`, the pages of the installed version.
 
 ## Status
 
-The `effect` peer is `^4.0.0`; the package is built and tested against the Effect release in
-its `devDependencies` (see [docs/setup.md](docs/setup.md)). Actions are unary JSON over HTTP and MCP: no streaming, uploads, prompts, or resources.
-Authentication and authorization belong to the application. See [docs/setup.md](docs/setup.md).
+The `effect` peer is `~4.0.0`, Effect's 4.0.x patches, since the modules the surfaces build on may
+change in a minor release; the package is built and tested against the Effect release in its
+`devDependencies` (see [docs/setup.md](docs/setup.md)). Actions are unary JSON over HTTP and MCP: no streaming, uploads, prompts, or resources.
+Token verification and the authorization rule belong to the application; the library supplies the authentication descriptor and provider, runs the rule, and answers the refusals. See [docs/setup.md](docs/setup.md).
 
 ## Acknowledgements
 
-A few ideas (like the native Toolkit, CLI, and catalog projections) are inspired by the excellent [rat-stack](https://github.com/joelhooks/rat-stack) by Joel Hooks.
+A few ideas (like the native Toolkit and CLI projections) are inspired by the excellent [rat-stack](https://github.com/joelhooks/rat-stack) by Joel Hooks.
 
 ## Contributing
 

package/dist/Action.d.mts

@@ -1,95 +1,301 @@
-import { Effect, Schema } from "effect";
+import { Anyone } from "./internal/actions.mjs";
+import { BuiltIn, BuiltIns, Forbidden, InvalidInput, Issue, Refusal, Unauthenticated } from "./internal/errors.mjs";
+import { ActionOf, AnyImplementation, Authorize, BuildError, BuildServices, Holding, Implementation, Known, Member, Offered, OptionalUnless, Protected, RequestOf, SelectedOf, Served, Serving } from "./internal/implementation.mjs";
+import { Call } from "./internal/call.mjs";
+import { Context, Effect, Layer, Schema, Scope } from "effect";
 declare namespace Action_d_exports {
-  export { Access, Action, Any, Codec, Handler, McpOptions, Options, make };
+  export { Action, Any, AnyImplementation, Anyone, Authorize, BuildError, BuildServices, BuiltIn, Client, ClientOptions, Errors, Forbidden, Handler, Handlers, Implementation, InvalidInput, Issue, Mcp, Options, Refusal, Unauthenticated, allowAll, byName, client, implement, layer, make };
 }
 /** Any service-free schema. Only handlers may require services. */
-export type Codec = Schema.Codec<unknown, unknown, never, never>;
-/**
- * What an action does to the resource it serves: `"read"` observes, `"write"`
- * may change it. Authorization metadata, not an MCP hint.
- */
-export type Access = "read" | "write";
-/** MCP tool metadata; every field has a default derived from the action. */
-export interface McpOptions {
-  /** Tool name; defaults to the action name. Must match `^[A-Za-z0-9_-]{1,128}$`. */
-  readonly name?: string;
-  /** `readOnlyHint`; defaults to `access === "read"`. */
-  readonly readOnly?: boolean;
-  /** `destructiveHint`; defaults to `!readOnly`, as the MCP spec only defines it for writes. */
-  readonly destructive?: boolean;
-  /** `idempotentHint`; defaults to `false`. */
-  readonly idempotent?: boolean;
-  /** `openWorldHint`; defaults to `true`. */
-  readonly openWorld?: boolean;
-  /**
-   * A string field of the encoded success that MCP sends as a raw text block rather
-   * than as structured content, such as a document body. Other surfaces serve the
-   * whole success.
-   */
-  readonly text?: string;
-}
-/** The fields `mcp.text` may name: those an encoded success has as a string. */
-type TextFields<Encoded> = Encoded extends object ? { readonly [K in keyof Encoded]-?: Required<Encoded>[K] extends string ? K : never; }[keyof Encoded] & string : never;
-type ResolvedMcp<Name extends string, Mcp extends false | McpOptions | undefined> = Mcp extends false ? false : {
-  readonly name: Mcp extends McpOptions ? "name" extends keyof Mcp ? Extract<Mcp["name"], string> extends never ? Name : Extract<Mcp["name"], string> | (undefined extends Mcp["name"] ? Name : never) : Name : Name;
-  readonly readOnly: boolean;
-  readonly destructive: boolean;
-  readonly idempotent: boolean;
-  readonly openWorld: boolean;
-  readonly text?: string;
+type Codec = Schema.Codec<unknown, unknown, never, never>;
+/** Struct fields, accepted wherever a struct schema is: `{ name: Schema.String }`. */
+type Fields = {
+  readonly [key: string]: Codec;
 };
+/**
+ * An object without fields: an action without arguments, `{}` given or not. Effect's own
+ * `Tool.EmptyParams`: strict, unlike `Schema.Struct({})`, which accepts any value but `null`,
+ * and the object root MCP requires.
+ */
+declare const NoInput: Schema.$Record<Schema.String, Schema.Never>;
+/** The schema a `Codec | Fields` option stands for: a schema itself, `NoInput` for no fields. */
+type CodecOf<S extends Codec | Fields> = S extends Codec ? S : S extends Schema.Struct.Fields ? keyof S extends never ? typeof NoInput : Extract<Schema.Struct<S>, Codec> : never;
+/**
+ * How the action's tool presents itself over MCP, in MCP's own names; every field is optional
+ * and none enforces anything. A hint left out is MCP's default, but `destructiveHint`, which is
+ * `false` for a read-only action. `readOnlyHint` is not one: it is always the contract's
+ * `readOnly`, so a tool cannot say otherwise than its contract.
+ */
+export interface Mcp {
+  /** The tool's display name, `annotations.title`, beside its name. */
+  readonly title?: string | undefined;
+  /** `annotations.destructiveHint`, meaningful for a write only. */
+  readonly destructiveHint?: boolean | undefined;
+  /** `annotations.idempotentHint`, meaningful for a write only. */
+  readonly idempotentHint?: boolean | undefined;
+  /** `annotations.openWorldHint`: whether the tool reaches entities outside its own domain. */
+  readonly openWorldHint?: boolean | undefined;
+  /** The tool's `_meta`, JSON such as an MCP App's UI resource, sent as given. */
+  readonly _meta?: {
+    readonly [key: string]: Schema.Json;
+  } | undefined;
+}
 /** What `make` needs to define an action. */
-export interface Options<Input extends Codec, Output extends Codec, Errors extends ReadonlyArray<Codec>, Acc extends Access = Access, Mcp extends false | McpOptions | undefined = McpOptions | undefined> {
+export interface Options {
+  /**
+   * Who may call the action: `Action.Anyone`, or the identity service a caller must have,
+   * which every surface enforces. Required: an action that names no caller is not public.
+   */
+  readonly caller: typeof Anyone | Context.Key<unknown, unknown>;
   readonly description: string;
-  /** Omit for an action without arguments. */
-  readonly input?: Input;
-  readonly success: Output;
-  /** One schema per declared failure; each keeps its own HTTP status annotation. Defaults to none. */
-  readonly errors?: Errors;
+  /** A schema or struct fields. Omit, or give `{}`, for an action without arguments. */
+  readonly input?: Codec | Fields | undefined;
+  /** A schema or struct fields. Omit for an action that returns nothing: `Schema.Void`. */
+  readonly success?: Codec | Fields | undefined;
+  /**
+   * The declared failures: one schema, or a list of them, as `HttpApiEndpoint` takes them;
+   * each keeps its own HTTP status annotation. Defaults to none. None with a built-in
+   * error's `_tag`.
+   */
+  readonly error?: Codec | ReadonlyArray<Codec> | undefined;
   /**
-   * What the action does to its resource. Required: an action nobody classified
-   * is the one a reviewer must check. Read by a surface's `before` hook; the
-   * library itself authorizes nothing.
+   * Whether the action leaves its resource unchanged. Required: an action nobody classified
+   * is the one a reviewer must check. An implementation's `authorize` may read it, and MCP's
+   * `readOnlyHint` is it; the library itself authorizes nothing with it.
    */
-  readonly access: Acc;
-  /** `false` hides the action from MCP; otherwise tool metadata. */
+  readonly readOnly: boolean;
+  /** How the action's tool presents itself over MCP, and on a native Toolkit's tools. */
   readonly mcp?: Mcp;
 }
-/** A pure contract: schemas and transport metadata. Implementations are bound by `ActionGroup.implement`. */
-export interface Action<Name extends string, Input extends Codec, Output extends Codec, Errors extends ReadonlyArray<Codec>, Acc extends Access = Access, Mcp extends false | McpOptions | undefined = McpOptions | undefined> {
+/**
+ * The keys beyond `Mcp` in the `mcp` of any member of `O`, given or optional, so a misspelled
+ * one in a conditional spread or in one branch of a ternary is refused too.
+ */
+type UnknownMcp<O> = O extends {
+  readonly mcp?: infer H;
+} ? Exclude<H extends unknown ? keyof H : never, keyof Mcp> : never;
+/** No key beyond `Mcp`, whichever member of `O` gives it. */
+type KnownMcp<O> = {
+  readonly mcp?: { readonly [K in UnknownMcp<O>]: never; };
+};
+/** The schemas an `error` option of type `G` declares: one, or each of a list. */
+type ErrorMembers<G> = G extends ReadonlyArray<infer E> ? E : G;
+/**
+ * The built-in errors, refused in `error`: every surface declares them already. The types
+ * refuse only the built-ins themselves; `make` refuses, when called, an error of your own
+ * that encodes with a built-in `_tag`.
+ */
+type OwnErrors<O> = O extends {
+  readonly error: infer G;
+} ? [Extract<ErrorMembers<G>, BuiltIns>] extends [never] ? unknown : {
+  readonly error: Exclude<ErrorMembers<G>, BuiltIns> | ReadonlyArray<Exclude<ErrorMembers<G>, BuiltIns>>;
+} : unknown;
+/**
+ * No option beyond `Options` in any member of `O`, so a misspelled one is an unknown
+ * property, not ignored: `keyof` a union holds only the keys every member has.
+ */
+type OnlyOptions<O> = { readonly [K in Exclude<O extends unknown ? keyof O : never, keyof Options>]: never; };
+/**
+ * `caller` is a `Context.Service`: a `Context.Reference` is never missing, so its default
+ * would stand in for every caller who supplies none.
+ */
+type ServiceCaller<O> = O extends {
+  readonly caller: {
+    readonly defaultValue: unknown;
+  };
+} ? {
+  readonly caller: "An identity is a Context.Service, not a Context.Reference";
+} : unknown;
+/**
+ * The rules `make` checks beyond `Options`: every option and `mcp` key known, and no built-in
+ * error listed. Options that fail `Options` itself infer as `Options`, whose error the
+ * compiler already reports, so they are not checked again. Checked after inference: `make`'s
+ * options are `O & NoInfer<Rules<O>>`.
+ */
+type Rules<O> = Options extends O ? unknown : OnlyOptions<O> & ServiceCaller<O> & OwnErrors<O> & KnownMcp<O>;
+/**
+ * Option `K` of `O` as given, or also `Default` wherever it may be omitted or undefined, as
+ * at run time, for each member of a union of options.
+ */
+type OptionOf<O, K extends keyof Options, Default> = O extends unknown ? K extends keyof O ? Exclude<O[K], undefined> | ({} extends Pick<O, K> ? Default : undefined extends O[K] ? Default : never) : Default : never;
+/** The schema option `K` of `O`, or `Default` when it is omitted. */
+type SchemaOf<O, K extends "input" | "success", Default extends Codec> = CodecOf<Extract<OptionOf<O, K, Default>, Codec | Fields>>;
+/** The declared errors of `O`, none when omitted. */
+type ErrorsOf<O> = ReadonlyArray<ErrorMembers<Extract<OptionOf<O, "error", []>, Codec | ReadonlyArray<Codec>>>>;
+/** A pure contract: schemas and transport metadata. Handlers are bound by `implement`. */
+export interface Action<Name extends string, Input extends Codec, Success extends Codec, Errors extends ReadonlyArray<Codec>, ReadOnly extends boolean = boolean, Caller extends Options["caller"] = Options["caller"]> {
+  readonly caller: Caller;
   readonly name: Name;
   readonly description: string;
   readonly input: Input;
-  readonly success: Output;
-  readonly errors: Errors;
-  readonly access: Acc;
-  readonly mcp: ResolvedMcp<Name, Mcp>;
+  readonly success: Success;
+  /** The declared failures, as a list: one given alone is a list of one. */
+  readonly error: Errors;
+  readonly readOnly: ReadOnly;
+  /** The `mcp` options as given, none when left out. */
+  readonly mcp: Mcp;
 }
 /** Any action, with its schemas erased. */
-export type Any = Action<string, Codec, Codec, ReadonlyArray<Codec>, Access, false> | Action<string, Codec, Codec, ReadonlyArray<Codec>, Access, McpOptions> | Action<string, Codec, Codec, ReadonlyArray<Codec>, Access, undefined>;
-/** Receives decoded input; may fail only with the declared errors. */
-export type Handler<A extends Any, R = never> = (input: A["input"]["Type"]) => Effect.Effect<A["success"]["Type"], A["errors"][number]["Type"], R>;
-/** An empty object schema that also produces the object root MCP requires. */
-declare const NoInput: Schema.$Record<Schema.String, Schema.Never>;
-type AnyOptions = Options<Codec, Codec, ReadonlyArray<Codec>, Access, false | McpOptions | undefined>;
-/**
- * The `mcp` option `make` received. Only a required literal `false` hides the action:
- * options that may carry something else, such as a conditional spread, `false | undefined`
- * or a broadly typed variable, may serve it, so its requirements are kept.
- */
-type McpOf<O extends AnyOptions> = [O] extends [{
-  readonly mcp: false;
-}] ? false : O extends {
-  readonly mcp: infer Mcp extends false | McpOptions | undefined;
-} ? Mcp : "mcp" extends keyof O ? O["mcp"] | undefined : undefined;
-/**
- * Define an action contract. Names are `[A-Za-z0-9_-]+`, other than `then`.
- * HTTP serves every action of a group it binds; `mcp: false` hides one from MCP.
- */
-export declare function make<const Name extends string, const O extends AnyOptions>(name: Name, options: O & { readonly [K in Exclude<keyof O, keyof AnyOptions>]: never; } & {
-  readonly mcp?: false | (McpOptions & {
-    readonly text?: TextFields<O["success"]["Encoded"]>;
-  }) | undefined;
-}): Action<Name, "input" extends keyof O ? Exclude<O["input"], undefined> : typeof NoInput, O["success"], "errors" extends keyof O ? Exclude<O["errors"], undefined> : [], O["access"], McpOf<O>>;
+export type Any = Action<string, Codec, Codec, ReadonlyArray<Codec>>;
+/**
+ * A list of declared errors, as an action's `error` holds it, and a binding's or an
+ * authentication descriptor's: `<E extends Action.Errors>` constrains one.
+ */
+export type Errors = ReadonlyArray<Codec>;
+/** Receives decoded input; may fail only with the declared errors and the built-in ones. */
+export type Handler<A extends Any, R = never> = (input: A["input"]["Type"]) => Effect.Effect<A["success"]["Type"], A["error"][number]["Type"] | BuiltIn, R>;
+/**
+ * The handlers of the actions `A`, keyed by name, as `implement` takes them: what a builder
+ * written apart from `implement` returns, `satisfies Action.Handlers<typeof actions>`, so its
+ * handlers are typed from their contracts, as another authorizer of the same handlers needs.
+ */
+export type Handlers<A extends ReadonlyArray<Any>, R = never> = { readonly [Action in A[number] as Action["name"]]: Handler<Action, R>; };
+/**
+ * Define an action contract. Names are `[A-Za-z0-9_-]{1,128}`, other than `then`: the name
+ * is also the route segment, the client method and the tool name.
+ */
+export declare function make<const Name extends string, const O extends Options>(name: Name, options: O & NoInfer<Rules<O>>): Action<Name, SchemaOf<O, "input", typeof NoInput>, SchemaOf<O, "success", typeof Schema.Void>, ErrorsOf<O>, O["readOnly"], O["caller"]>;
+/**
+ * `actions` keyed by name, each its exact contract: `byName(actions).getUser`, its schemas
+ * where a test or a mock reads them, and its types where a helper takes a name,
+ * `(typeof contracts)[K]["input"]["Type"]`, which resolves under a generic `K` where
+ * `Extract` over the list does not. The list is typed by its members, as every surface types
+ * one. A name held twice is refused, as a surface refuses it.
+ */
+export declare function byName<const Actions extends ReadonlyArray<Any>>(actions: Actions): { readonly [A in Actions[number] as A["name"]]: A; };
+/** What `implement` binds: one action, or several that share one builder. */
+type Target = Any | ReadonlyArray<Any>;
+/**
+ * A target of public actions only, which takes no `authorize`. Named for what a protected
+ * target lacks there, as the error a call without `authorize` reports names this type.
+ */
+type ProtectedActionsTakeAuthorize = PublicAction | ReadonlyArray<PublicAction>;
+/** An action anyone may call. */
+type PublicAction = Any & {
+  readonly caller: typeof Anyone;
+};
+/**
+ * The actions `T` stands for. One action is extracted rather than taken as it is, so where `T`
+ * is deferred, such as a list of a helper's type parameter, the actions are still actions to
+ * TypeScript, and a selection of them reaches a surface.
+ */
+type ActionsOf<T extends Target> = T extends ReadonlyArray<Any> ? T[number] : Extract<T, Any>;
+/** The names of the actions `T` stands for. */
+type NamesOf<T extends Target> = ActionsOf<T>["name"];
+/**
+ * What a list takes instead of one handler: nothing. A named alias carrying `R`, and it must
+ * stay one: while a builder's inner call, such as `Effect.gen`, is inferred, TypeScript keeps
+ * an alias's arguments marked as not yet inferred, where `never` or this type written inline
+ * becomes a candidate, and the builder's record loses its handlers' parameter types.
+ */
+type NoHandler<R> = {
+  readonly "~list": R;
+};
+/**
+ * One action's handler, owing `R` per request; a list takes none. It is `Handler` written out, as
+ * `Authorizer`'s are. While `implement` infers, an alias whose argument `R` is not yet
+ * inferred is marked, as a whole, as not inferrable (the mark `NoHandler` relies on), so an
+ * `Effect.fn(...)` a builder returns would infer nothing from it and take an `any` input.
+ */
+type Single<T extends Target, R> = T extends Any ? (input: T["input"]["Type"]) => Effect.Effect<T["success"]["Type"], T["error"][number]["Type"] | BuiltIn, R> : NoHandler<R>;
+/**
+ * A record of handlers, one per key of `RequestServices`, each typed from its own action and
+ * owing its entry of `RequestServices` per request. TypeScript infers `RequestServices` from the
+ * record, key by key, so each handler, `Effect.fn` included, is typed from its contract; a key
+ * no action names takes nothing.
+ */
+type Several<T extends Target, RequestServices> = { readonly [K in keyof RequestServices]: K extends NamesOf<T> ? Handler<Extract<ActionsOf<T>, {
+  readonly name: K;
+}>, RequestServices[K]> : never; };
+/** What `implement` binds to `T`: one action's handler, or a list's record. */
+type HandlersOf<T extends Target, R, RequestServices> = Single<T, R> | Several<T, RequestServices>;
+/**
+ * `T`, never inferred from where it stands: an index TypeScript cannot read until `T` is
+ * known, as `NoInfer` would be, but read as `T` itself once it is. So an implementation
+ * written inside a surface's arguments takes nothing from what that surface accepts, and a
+ * union of services is one union, which `Layer.provide` discharges a member at a time.
+ */
+type Deferred<T> = [T][T extends unknown ? 0 : never];
+/**
+ * An authorizer, or an Effect that builds it, as a builder builds handlers: `EAX` and `RAX` are
+ * startup failures and services, `RA` what the authorizer reads per request. Each authorizer is
+ * `Authorize` written out. TypeScript would infer `RA` from only one branch of a conditional
+ * authorizer whose other branch is typed `Authorize`, such as
+ * `enabled ? authorize : Action.allowAll`. While `implement` infers, an alias whose argument `RA`
+ * is not yet inferred is marked, as a whole, as not inferrable, so an `Effect.fn(...)` the
+ * Effect returns would infer nothing from it and take an `any` action.
+ */
+type Authorizer<A extends Any, RA, EAX, RAX> = ((action: A) => Effect.Effect<void, Refusal, RA>) | Effect.Effect<(action: A) => Effect.Effect<void, Refusal, RA>, EAX, RAX>;
+/**
+ * What `implement` returns for `T`: its handlers' per-request requirements keyed by action
+ * name, the authorizer's, and the startup failures and services of the builder and the
+ * authorizer.
+ */
+type Implemented<T extends Target, RequestServices, R, EX, RX, RA, EAX, RAX> = Implementation<ActionsOf<T>, { readonly [K in NamesOf<T>]: Exclude<T extends ReadonlyArray<Any> ? RequestServices[K & keyof RequestServices] : R, Scope.Scope>; }, Deferred<EX>, Deferred<Exclude<RX, Scope.Scope>>, Exclude<RA, Scope.Scope>, Deferred<EAX>, Deferred<Exclude<RAX, Scope.Scope>>>;
+/**
+ * Every authenticated caller may call a protected action. The contract's identity
+ * requirement is enforced independently, including when its handler reads no identity.
+ */
+export declare const allowAll: Authorize<Any>;
+/**
+ * Bind handlers to contracts, behind authorization. Pass one action and its handler, or a list of
+ * actions and a record of handlers keyed by action name. Either may instead be an Effect
+ * that builds them: its services are startup requirements, resolved once per layer graph
+ * however many surfaces serve the result, while services a handler yields are per-request
+ * requirements.
+ *
+ * `authorize` is required when the target includes protected contracts and runs only for
+ * them. `Action.allowAll` permits every authenticated caller. An Effect may build the
+ * authorizer once, with startup requirements separate from its per-call requirements.
+ */
+export declare function implement<const T extends Target, RequestServices extends (T extends ReadonlyArray<Any> ? { readonly [K in NamesOf<T>]: unknown; } : never), R = never, EX = never, RX = never, RA = never, EAX = never, RAX = never>(actions: T, handlers: HandlersOf<T, R, RequestServices> | Effect.Effect<HandlersOf<T, R, RequestServices>, EX, RX>, options: {
+  readonly authorize: [Protected<ActionsOf<T>>] extends [never] ? never : Authorizer<Protected<ActionsOf<T>>, RA, EAX, RAX>;
+}): Implemented<T, RequestServices, R, EX, RX, RA, EAX, RAX>;
+export declare function implement<const T extends ProtectedActionsTakeAuthorize, RequestServices extends (T extends ReadonlyArray<Any> ? { readonly [K in NamesOf<T>]: unknown; } : never), R = never, EX = never, RX = never, RA = never, EAX = never, RAX = never>(actions: T, handlers: HandlersOf<T, R, RequestServices> | Effect.Effect<HandlersOf<T, R, RequestServices>, EX, RX>, options?: {
+  readonly authorize?: never;
+}): Implemented<T, RequestServices, R, EX, RX, RA, EAX, RAX>;
+export declare function implement<const T extends Target, RequestServices extends (T extends ReadonlyArray<Any> ? { readonly [K in NamesOf<T>]: unknown; } : never), R = never, EX = never, RX = never, RA = never, EAX = never, RAX = never>(actions: T, handlers: HandlersOf<T, R, RequestServices> | Effect.Effect<HandlersOf<T, R, RequestServices>, EX, RX>, options: {
+  readonly authorize: [Protected<ActionsOf<T>>] extends [never] ? "A public-only target takes no authorize" : Authorizer<Protected<ActionsOf<T>>, RA, EAX, RAX>;
+}): Implemented<T, RequestServices, R, EX, RX, RA, EAX, RAX>;
+/**
+ * The builders of `implementations`, as one layer providing nothing. Surfaces build them
+ * themselves, once per layer graph, but routes under `HttpRouter.serve` or `Testing.layer`
+ * are built in a graph of their own: provided above both, it runs each builder once for every
+ * surface, with the services it is given.
+ */
+export declare function layer<const Apps extends Served>(implementations: Apps): Layer.Layer<never, BuildError<Member<Apps>>, BuildServices<Member<Apps>>>;
+/**
+ * One call of `A` in process: its decoded success, or its declared errors and the built-in
+ * ones, owing `R` per call, what its handler and its implementation's `authorize` read.
+ */
+type Method<A extends Any, R> = Call<A, Effect.Effect<A["success"]["Type"], A["error"][number]["Type"] | BuiltIn, R>>;
+/**
+ * Every action of the implementations `Apps`, one or a list, as `client.<action>(input)`: what
+ * `client` gives, each method owing per call what its handler and `authorize` read.
+ */
+export type Client<Apps extends Served, Listed extends Any = Extract<ActionOf<Member<Apps>>, Any>> = { readonly [A in Serving<Member<Apps>, Listed> as A["name"]]: Method<A, RequestOf<Member<Apps>, A>>; };
+/** What `client` takes: the actions to call. */
+export interface ClientOptions<A extends Any> {
+  /**
+   * The actions to call, among the implementations': `[GetUser]`. Defaults to every action of
+   * them. Options whose `actions` may be absent are typed as every action, as they may run.
+   */
+  readonly actions?: ReadonlyArray<A> | undefined;
+}
+/**
+ * Call implementations in process: one method per action, taking its input directly, as
+ * `ActionHttp.client`'s methods do, `client.renameUser({ id, name })`, so moving between the
+ * two changes the line acquiring it. A call runs as a remote one does: its input passes through
+ * its JSON codec, encoded then decoded, then the implementation's `authorize` and the handler
+ * run, in a scope of their own, and the success or the failure passes through its
+ * codec. It fails with the action's errors and the built-in ones, and owes, per call, what
+ * they read, the caller's identity included; the caller provides it around the call.
+ *
+ * Acquiring it builds the implementations' builders, as a layer does, into the layer graph it
+ * is acquired in, and its scope holds them: in a builder, it shares their one run with every
+ * surface of that graph. Acquire it where builders live, in a builder, a layer or a scoped
+ * program, never per request.
+ */
+export declare function client<const Apps extends Served, const O extends ClientOptions<ActionOf<Member<Apps>>> = {}>(implementations: Apps, ...options: OptionalUnless<O, ClientOptions<ActionOf<Member<Apps>>> & O & NoInfer<Known<O, ClientOptions<Any>>>>): Effect.Effect<Client<Apps, Offered<O, ActionOf<Member<Apps>>>>, BuildError<Holding<Member<Apps>, SelectedOf<O, Apps>>, SelectedOf<O, Apps>>, BuildServices<Holding<Member<Apps>, SelectedOf<O, Apps>>, SelectedOf<O, Apps>> | Scope.Scope>;
 //#endregion
-export { Action_d_exports };
+export { Action_d_exports, type AnyImplementation, Anyone, type Authorize, type BuildError, type BuildServices, BuiltIn, Forbidden, type Implementation, InvalidInput, type Issue, Refusal, Unauthenticated };