@gjermundgaraba/effect-actions 0.11.0 → 0.13.0

package/README.md

@@ -1,18 +1,23 @@
 # effect-actions
 
-Define an Effect action once. Serve it over HTTP and MCP, hand it to a model as a native
-Toolkit, and run it from a CLI. Same schemas, same handler, Effect's own servers and clients
+Define an Effect action once. Serve it over HTTP, MCP and Effect RPC, hand it to a model as a
+native Toolkit, and run it from a CLI. Same schemas, same handler, Effect's own servers and clients
 underneath.
 
+**If you are a coding agent**, start at [docs/README.md](docs/README.md), not here, and read
+one page per tool call, again alone if its output says it was truncated. It routes every task,
+protecting an action and limiting request bodies included, to its page and its example.
+
 ## Looks like this
 
-```ts example=quickstart.ts
+A contract says what an action takes and answers, and who may call it:
+
+```ts example=quickstart/src/greeting/Greeting.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.
+// A contract: what the action takes and answers, whether it changes anything, and who may
+// call it. It imports no server code, so any client can import it, a browser page included.
 export const Greet = Action.make("greet", {
   description: "Greet someone by name.",
   input: { name: Schema.String },
@@ -20,38 +25,56 @@ export const Greet = Action.make("greet", {
   readOnly: true,
   caller: Action.Anyone,
 });
+```
+
+An implementation binds it to its handler:
+
+```ts example=quickstart/src/greeting/handlers.ts
+import { Effect } from "effect";
+import * as Action from "@gjermundgaraba/effect-actions/Action";
+import { Greet } from "./Greeting.js";
 
+// The implementation: the contract bound to its handler. Every surface takes this one value.
+export const greeting = Action.implement(Greet, ({ name }) => Effect.succeed(`Hello, ${name}!`));
+```
+
+A binding gives it a route, for the server to serve and a client to call:
+
+```ts example=quickstart/src/Api.ts
+import * as ActionHttp from "@gjermundgaraba/effect-actions/ActionHttp";
+import { Greet } from "./greeting/Greeting.js";
+
+// The HTTP binding: `POST /api/greet`. The server serves it and the client calls it.
 export const Http = ActionHttp.make([Greet]);
 ```
 
-and a server that implements it, in a module of its own:
+And the same implementation is served on every surface the host wants:
 
-```ts example=quickstart-server.ts
-import { Effect, Layer } from "effect";
-import * as Action from "@gjermundgaraba/effect-actions/Action";
+```ts example=quickstart/src/routes.ts
+import { Layer } from "effect";
 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}!`));
+import { Http } from "./Api.js";
+import { greeting } from "./greeting/handlers.js";
 
+// One implementation, two surfaces: a JSON route and an MCP tool at `/mcp`.
 export const routes = Layer.mergeAll(
-  ActionHttp.layer(Http, greet),
-  ActionMcp.layerHttp(greet, { name: "greetings", version: "1.0.0" }),
+  ActionHttp.layer(Http, greeting),
+  ActionMcp.layerHttp(greeting, { name: "greetings", version: "1.0.0" }),
 );
 ```
 
-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`
+Serve `routes` with Effect's `HttpRouter.serve` and a platform server, as
+[examples/quickstart/src/server.ts](examples/quickstart/src/server.ts) does, and you have
+`POST /api/greet` and an MCP tool named `greet` at `/mcp`. The same `greeting`
 implementation is also:
 
 ```ts
-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 { toolkit, layer } = ActionToolkit.make(greeting); // native Effect AI Toolkit and its handler layer
+const cli = ActionCli.make(greeting, { 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
+const local = Action.client(greeting); // the HTTP client's methods, in process
+const rpc = ActionRpc.layer(ActionRpc.make([Greet]), greeting); // Effect RPC, on the protocol the host provides
 ```
 
 And the client is Effect's own `HttpApiClient`, typed from the same contract, one method per action:
@@ -67,49 +90,86 @@ const greeting = Effect.gen(function* () {
 ## Why
 
 - 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.
+- A handler can fail only with the errors its action declares and three built-in ones (400, 401, 403), and every client decodes them as typed values.
+- Every contract states who may call it: `caller: Action.Anyone`, or the identity service a caller must have. A surface authenticates a protected action's request before decoding its input, with the provider the application builds from its own token verifier.
+- Authorization is written once, on the implementation: `Action.implement(actions, handlers, { authorize })`, required for protected actions. Every surface runs it before each handler, and the rule reads the contract's `readOnly` instead of a hand-maintained list of mutation names.
+- Public and protected routes share one binding, one OpenAPI document and one client, and a handler's startup services are built once per [layer graph](docs/Action.md#implement-actions), however many surfaces serve it.
+- The pieces are Effect's own: a native `HttpApi`, `McpServer`, `RpcServer` and `RpcClient`, with no SDK runtime dependency, so OpenAPI, Swagger, Scalar and `HttpApiClient` work unchanged.
+- Tests run in memory: `Action.client` calls an implementation in process, and `Testing.layer(routes)` serves the routes and tools to typed clients without opening a port.
 
 ## Install
 
 ```sh
-pnpm add @gjermundgaraba/effect-actions effect@~4.0.2
+pnpm add @gjermundgaraba/effect-actions effect@~4.0.3
 ```
 
-Add `@effect/platform-node@~4.0.2` to serve or run a CLI from Node. Every module is a
+It needs TypeScript 7 or newer and is ESM only
+([docs/setup.md](docs/setup.md#install)). Add `@effect/platform-node@~4.0.3` 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.
 
+## Examples
+
+[examples/](examples/README.md) holds complete applications, each a directory you can run, with
+its own tests, laid out the way we recommend for an application: a folder per domain, the
+contract in one file a browser can import, one entrypoint per way of running it. They are
+type-checked and tested with the library and ship in the package.
+
+- [quickstart](examples/quickstart/): the program above.
+- [notes-service](examples/notes-service/): a service with bearer authentication, a JSON API
+  and MCP tools from one implementation, a CLI and a browser client. Most applications are this.
+- [mcp-tools](examples/mcp-tools/): an MCP server whose tools wrap an upstream HTTP API.
+- [assistant](examples/assistant/): no server, the same implementations as a model's tools
+  and as local commands.
+- [live-rpc](examples/live-rpc/): Effect RPC over a WebSocket.
+- [kitchen-sink](examples/kitchen-sink/): every module and nearly every option in one
+  application, with an index from each to the file that shows it.
+
 ## 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/](docs/README.md) is written for coding agents: one short page per module, organized by
+task, each linking to the example files that show the task working.
 
-- [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/README.md](docs/README.md): start here: which page answers which task, and which
+  surface to use for which caller.
+- [docs/guarantees.md](docs/guarantees.md): what each case looks like on the wire, on every
+  surface, and what the library leaves to the application.
 - [docs/CONTEXT.md](docs/CONTEXT.md): the vocabulary the docs and the code use.
-- [examples/](examples/README.md): a runnable authenticated application with public and authenticated actions, an MCP endpoint, OpenAPI, and every other surface.
 
 ## For agents
 
+The `effect-actions` skill puts the docs in front of a coding agent. With the
+[skills CLI](https://github.com/vercel-labs/skills), for any agent it supports:
+
 ```sh
 npx skills add gjermundgaraba/effect-actions --skill effect-actions
 ```
 
+As a Claude Code plugin:
+
+```text
+/plugin marketplace add gjermundgaraba/effect-actions
+/plugin install effect-actions@effect-actions-marketplace
+```
+
+As a Codex plugin:
+
+```sh
+codex plugin marketplace add gjermundgaraba/effect-actions
+codex plugin add effect-actions@effect-actions-marketplace
+```
+
 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.
+release. Its links to the examples are paths into the installed package,
+`node_modules/@gjermundgaraba/effect-actions/examples`, which an agent reads without a network;
+the pages of the installed version are beside them, in
+`node_modules/@gjermundgaraba/effect-actions/docs`.
 
 ## Status
 
 The `effect` peer admits the patches of the Effect release the package is tested against, since
-the modules the surfaces build on may change in a minor release (see [docs/setup.md](docs/setup.md#install)). 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).
+the modules the surfaces build on may change in a minor release (see [docs/setup.md](docs/setup.md#install)). Actions are unary JSON over HTTP, MCP and Effect RPC, whose protocols speak JSON alone: no streaming or uploads.
+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/guarantees.md](docs/guarantees.md#scope).
 
 ## Acknowledgements
 
@@ -117,4 +177,5 @@ A few ideas (like the native Toolkit and CLI projections) are inspired by the ex
 
 ## Contributing
 
-See [CONTRIBUTING.md](CONTRIBUTING.md). MIT licensed.
+The rules for changing the library are in
+[AGENTS.md](https://github.com/gjermundgaraba/effect-actions/blob/main/AGENTS.md). MIT licensed.

package/dist/Action.d.mts

@@ -1,25 +1,17 @@
-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 { Image } from "./internal/media.mjs";
+import { Anyone } from "./contract/rules.mjs";
+import { BuiltIn, BuiltIns, Forbidden, InvalidInput, Issue, Refusal, Unauthenticated } from "./contract/errors.mjs";
+import { ActionOf, AnyImplementation, Authorize, BuildError, BuildServices, Holding, Implementation, Known, Member, Offered, OptionalUnless, Protected, RequestOf, SelectedOf, Served, Serving } from "./contract/implementation.mjs";
+import { Call } from "./contract/call.mjs";
+import { Image } from "./contract/media.mjs";
 import { Context, Effect, Layer, Schema, Scope } from "effect";
 declare namespace Action_d_exports {
   export { Action, Any, AnyImplementation, Anyone, Authorize, BuildError, BuildServices, BuiltIn, Client, ClientOptions, Errors, Forbidden, Handler, Handlers, Image, Implementation, InvalidInput, Issue, Mcp, Options, Refusal, Unauthenticated, allowAll, byName, client, implement, layer, make };
 }
-/** Any service-free schema. Only handlers may require services. */
 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
@@ -30,7 +22,12 @@ type CodecOf<S extends Codec | Fields> = S extends Codec ? S : S extends Schema.
 export interface Mcp {
   /** The tool's display name, `annotations.title`, beside its name. */
   readonly title?: string | undefined;
-  /** `annotations.destructiveHint`, meaningful for a write only. */
+  /**
+   * `annotations.destructiveHint`, meaningful for a write only. Left out, a write is listed as
+   * destructive, MCP's default: state `false` for one that only adds, MCP's "only additive
+   * updates". One that replaces, removes or interrupts, such as an edit or a restart, stays
+   * destructive.
+   */
   readonly destructiveHint?: boolean | undefined;
   /** `annotations.idempotentHint`, meaningful for a write only. */
   readonly idempotentHint?: boolean | undefined;
@@ -49,14 +46,18 @@ export interface Options {
    */
   readonly caller: typeof Anyone | Context.Key<unknown, unknown>;
   readonly description: string;
-  /** A schema or struct fields. Omit, or give `{}`, for an action without arguments. */
+  /**
+   * A schema or struct fields. Omit, or give `{}`, for an action without arguments. A field's
+   * `description` annotation is what a model reads in a tool's listing and a flag's help in a CLI.
+   */
   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`.
+   * each keeps its own HTTP status annotation, the third argument of
+   * `Schema.TaggedError<NoteNotFound>()("NoteNotFound", { id: Schema.String }, { httpApiStatus: 404 })`,
+   * and answers 422 without one. Defaults to none. None with a built-in error's `_tag`.
    */
   readonly error?: Codec | ReadonlyArray<Codec> | undefined;
   /**
@@ -68,38 +69,19 @@ export interface Options {
   /** How the action's tool presents itself over MCP, and on a native Toolkit's tools. */
   readonly mcp?: Mcp;
 }
-/**
- * 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;
@@ -107,27 +89,19 @@ type ServiceCaller<O> = O extends {
 } ? {
   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>>>>;
+type ErrorSchemasOf<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;
+  /**
+   * The input as a schema, a `Schema.Struct` where fields were given: reuse it as it is, as in
+   * `Schema.Array(action.input)`.
+   */
   readonly input: Input;
   readonly success: Success;
   /** The declared failures, as a list: one given alone is a list of one. */
@@ -154,8 +128,9 @@ export type Handlers<A extends ReadonlyArray<Any>, R = never> = { readonly [Acti
 /**
  * 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.
+ * Guide: `docs/Action.md` in this package; in an application: `examples/notes-service/src/notes/`.
  */
-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"]>;
+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>, ErrorSchemasOf<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,
@@ -164,74 +139,20 @@ export declare function make<const Name extends string, const O extends Options>
  * 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 TakesNoAuthorize<T extends Target> = [Protected<ActionsOf<T>>] extends [never] ? unknown : "A protected action takes { authorize }: your rule, or Action.allowAll";
 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
@@ -249,15 +170,12 @@ export declare const allowAll: Authorize<Any>;
  * 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>;
+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: [Protected<ActionsOf<T>>] extends [never] ? {
+  readonly authorize?: "A public-only target takes no authorize";
+} | undefined : {
+  readonly authorize: Authorizer<Protected<ActionsOf<T>>, RA, EAX, RAX>;
 }): 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>(actions: T & TakesNoAuthorize<T>, handlers: HandlersOf<T, R, RequestServices> | Effect.Effect<HandlersOf<T, R, RequestServices>, EX, RX>): Implemented<T, RequestServices, R, EX, RX, never, never, never>;
 /**
  * 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`
@@ -265,10 +183,6 @@ export declare function implement<const T extends Target, RequestServices extend
  * 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

package/dist/Action.mjs

@@ -1,20 +1,11 @@
-import { BuiltIn, Forbidden, InvalidInput, Refusal, Unauthenticated } from "./internal/errors.mjs";
-import { Anyone, assertKnown, assertName, assertOnce, assertOwnTags, errorList, projectedErrors } from "./internal/actions.mjs";
-import { inputOf } from "./internal/call.mjs";
-import { Implementation, builders, built, memoized, select, toList } from "./internal/implementation.mjs";
-import { Image } from "./internal/media.mjs";
+import { BuiltIn, Forbidden, InvalidInput, Refusal, Unauthenticated } from "./contract/errors.mjs";
+import { Anyone, assertKnown, assertName, assertOnce, assertOwnTags, errorList, projectedErrors } from "./contract/rules.mjs";
+import { Implementation, builders, built, memoized, select, toList } from "./contract/implementation.mjs";
+import { inputOf } from "./contract/call.mjs";
+import { Image } from "./contract/media.mjs";
 import { Array as Array$1, Cause, Context, Effect, Predicate, Schema } from "effect";
-//#region src/Action.ts
-/**
-* 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.
-*/
+//#region src/contract/Action.ts
 const NoInput = Schema.Record(Schema.String, Schema.Never);
-/**
-* The schema an option stands for: a schema as given, `NoInput` for no fields, or the struct
-* of the fields, which may be keyed by symbols, as in a struct.
-*/
 const codecOf = (schema) => Schema.isSchema(schema) ? schema : Reflect.ownKeys(schema).length === 0 ? NoInput : Schema.Struct(schema);
 function make(name, options) {
 	assertName("action name", name);
@@ -44,36 +35,25 @@ function byName(actions) {
 * requirement is enforced independently, including when its handler reads no identity.
 */
 const allowAll = () => Effect.void;
-/**
-* `authorize`, checked: the types require a function, and plain JavaScript can still pass
-* none, which must not serve every caller.
-*/
 const assertAuthorizer = (before) => {
 	if (!Predicate.isFunction(before)) throw new Error("Missing authorize: pass an authorization function, or Action.allowAll");
 	return before;
 };
-/** `authorize`, present wherever a protected action is implemented. */
 const assertAuthorization = (authorize) => {
 	if (authorize === void 0) throw new Error("Protected actions require authorize, or Action.allowAll");
 	return authorize;
 };
-/** No `authorize` where only public actions are implemented: it would never run. */
 const assertNoAuthorization = (authorize) => {
 	if (authorize !== void 0) throw new Error("A public-only target takes no authorize");
 	return allowAll;
 };
-/**
-* The layer building `authorize`: a plain function as it is, a built one once its Effect
-* runs, checked when the layer builds, as a builder's record is. `Effect.isEffect` tells them
-* apart, so one written with `Effect.fn` stays plain.
-*/
 const authorizerOf = (before) => memoized(Effect.isEffect(before) ? Effect.map(before, assertAuthorizer) : Effect.succeed(assertAuthorizer(before)));
 function implement(actions, handlers, options) {
 	const listed = Array$1.ensure(actions);
 	const names = listed.map((action) => action.name);
 	assertOnce("action", listed);
 	const authorizer = authorizerOf(listed.some((action) => action.caller !== Anyone) ? assertAuthorization(options?.authorize) : assertNoAuthorization(options?.authorize));
-	const record = (built) => {
+	const pairWithActions = (built) => {
 		const keyed = Predicate.isFunction(built) ? Object.fromEntries(Array.isArray(actions) ? [] : listed.map(({ name }) => [name, built])) : built;
 		assertKnown("handlers", Object.keys(keyed), names);
 		const bound = listed.flatMap((action) => {
@@ -84,46 +64,27 @@ function implement(actions, handlers, options) {
 		if (missing.length > 0) throw new Error(`Missing handlers: ${missing.join(", ")}`);
 		return bound;
 	};
-	const recorded = Effect.isEffect(handlers) ? Effect.map(handlers, record) : Effect.succeed(record(handlers));
+	const recorded = Effect.isEffect(handlers) ? Effect.map(handlers, pairWithActions) : Effect.succeed(pairWithActions(handlers));
 	return new Implementation(listed, memoized(recorded), authorizer);
 }
 function layer(implementations) {
 	return builders(toList(implementations));
 }
-/**
-* A value through `schema`'s JSON codec, as a wire carries it: encoded to JSON text, then
-* decoded, so what comes out is what a remote call's other side decodes, `-0` as `0`. Every
-* issue is reported.
-*/
-const wire = (schema) => {
+const jsonRoundTrip = (schema) => {
 	const codec = Schema.fromJsonString(Schema.toCodecJson(schema));
 	const encode = Schema.encodeUnknownEffect(codec, { errors: "all" });
 	const decode = Schema.decodeUnknownEffect(codec, { errors: "all" });
 	return (value) => Effect.flatMap(encode(value), (encoded) => decode(encoded));
 };
-/**
-* `cause` with each failure passed through `failure` where it stands, so it keeps its
-* annotations, the span it failed in among them; failed anew, it would lose them. One that
-* passes keeps the stack of where it was made, where the decoded error's would be the codec's.
-* One that does not, such as an error the action does not declare, is a defect: its
-* `SchemaError`, then the failure itself.
-*/
-const mapFailures = (cause, failure) => Effect.map(Effect.forEach(cause.reasons, (reason) => Cause.isFailReason(reason) ? Effect.match(failure(reason.error), {
+const mapFailuresInPlace = (cause, failure) => Effect.map(Effect.forEach(cause.reasons, (reason) => Cause.isFailReason(reason) ? Effect.match(failure(reason.error), {
 	onFailure: (refused) => Cause.combine(Cause.die(refused), Cause.die(reason.error)),
 	onSuccess: (decoded) => Cause.fail(Predicate.isError(reason.error) && Predicate.isError(decoded) ? Object.assign(decoded, { stack: reason.error.stack }) : decoded)
 }).pipe(Effect.map((mapped) => Cause.annotate(mapped, Cause.reasonAnnotations(reason)))) : Effect.succeed(Cause.fromReasons([reason]))), (causes) => Cause.fromReasons(causes.flatMap(({ reasons }) => reasons)));
-/**
-* `action`'s method, running `run`, its handler behind authorization, as a remote
-* call runs: input that does not pass through its codec is `InvalidInput`, and nothing else
-* runs; a success or a failure that does not is a defect, as it is an empty 500 over HTTP,
-* since the handler broke its contract. A failure passes through the codec of
-* every error the action declares, the built-in ones included.
-*/
 const methodOf = (action, run) => {
-	const input = wire(action.input);
-	const success = wire(action.success);
-	const failure = wire(Schema.Union(projectedErrors(action)));
-	return (...args) => inputOf(action, args).pipe(Effect.flatMap(input), Effect.mapError(InvalidInput.fromSchemaError), Effect.flatMap((value) => Effect.catchCause(run(value), (cause) => Effect.flatMap(mapFailures(cause, failure), Effect.failCause))), Effect.flatMap((value) => Effect.orDie(success(value))));
+	const input = jsonRoundTrip(action.input);
+	const success = jsonRoundTrip(action.success);
+	const failure = jsonRoundTrip(Schema.Union(projectedErrors(action)));
+	return (...args) => inputOf(action, args).pipe(Effect.flatMap(input), Effect.mapError(InvalidInput.fromSchemaError), Effect.flatMap((value) => Effect.catchCause(run(value), (cause) => Effect.flatMap(mapFailuresInPlace(cause, failure), Effect.failCause))), Effect.flatMap((value) => Effect.orDie(success(value))));
 };
 function client(served, options) {
 	const apps = select(toList(served), options?.actions);