@gjermundgaraba/effect-actions 0.18.1 → 0.19.0

package/README.md

@@ -4,21 +4,16 @@ Define an Effect action once. Serve it over HTTP, MCP and Effect RPC, hand it to
 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.
+**If you are a coding agent**, start at [docs/README.md](docs/README.md), not here. It routes
+every task, protecting an action and limiting request bodies included, to its page and its
+example.
 
 ## Looks like this
 
 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";
-
-// 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", {
+```ts
+const Greet = Action.make("greet", {
   description: "Greet someone by name.",
   input: { name: Schema.String },
   success: Schema.String,
@@ -29,43 +24,27 @@ export const Greet = Action.make("greet", {
 
 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}!`));
+```ts
+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]);
+```ts
+const Http = ActionHttp.make([Greet]); // POST /api/greet
 ```
 
 And the same implementation is served on every surface the host wants:
 
-```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 { 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(
+```ts
+const routes = Layer.mergeAll(
   ActionHttp.layer(Http, greeting),
   ActionMcp.layerHttp(greeting, { name: "greetings", version: "1.0.0" }),
 );
 ```
 
 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
+[examples/quickstart](examples/quickstart) does, file by file, and you have
 `POST /api/greet` and an MCP tool named `greet` at `/mcp`. The same `greeting`
 implementation is also:
 
@@ -82,10 +61,10 @@ const rpc = ActionRpc.layer(ActionRpc.make([Greet]), greeting); // Effect RPC, o
 And the client is Effect's own `HttpApiClient`, typed from the same contract, one method per action:
 
 ```ts
-const greeting = Effect.gen(function* () {
+Effect.gen(function* () {
   const client = yield* ActionHttp.client(Http, { baseUrl });
 
-  return yield* client.greet({ name: "Ada" });
+  return yield* client.greet({ name: "Ada" }); // "Hello, Ada!"
 });
 ```
 
@@ -95,7 +74,7 @@ const greeting = Effect.gen(function* () {
 - 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.
+- 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#share-one-build-across-servers), 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.
 
@@ -106,7 +85,7 @@ pnpm add @gjermundgaraba/effect-actions effect@~4.0.4
 ```
 
 It needs TypeScript 7 or newer and is ESM only
-([docs/setup.md](docs/setup.md#install)). Add `@effect/platform-node@~4.0.4` to serve or run a CLI from Node. Every module is a
+([docs/setup.md](docs/setup.md#install)). Add `@effect/platform-node@~4.0.4` to serve or run a CLI from Node, and `@types/node` for its `node:` imports. Every module is a
 subpath import (`.../Action`, `.../ActionHttp`, ...); there is no package root, so a
 contracts-only bundle never loads a server.
 
@@ -130,13 +109,8 @@ type-checked and tested with the library and ship in the package.
 ## Docs
 
 [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: 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.
+task, each linking to the example files that show the task working. Start at
+[docs/README.md](docs/README.md).
 
 ## For agents
 
@@ -169,9 +143,8 @@ the pages of the installed version are beside them, in
 
 ## Status
 
-The `effect` peer admits Effect 4.0.x patches from the oldest whose APIs the package uses, 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, 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).
+The `effect` peer range is in [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 [what the library leaves to you](docs/README.md#what-the-library-leaves-to-you).
 
 ## Acknowledgements
 

package/dist/Action.d.mts

@@ -1,5 +1,5 @@
 import { Anyone } from "./contract/caller.mjs";
-import { BuiltIn, BuiltIns, Forbidden, InvalidInput, Issue, Refusal, Unauthenticated } from "./contract/errors.mjs";
+import { BuiltIn, 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";
@@ -40,28 +40,64 @@ export interface Mcp {
 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.
+   * which every surface enforces whether or not the handler reads it. Required: an action that
+   * names no caller is not public. A remote surface gets the identity by authenticating the
+   * request; on a local surface the host provides it.
+   *
+   * **Gotchas**
+   *
+   * - Declare the identity as a `Context.Service`, in a contract file, apart from its verifier.
+   * - One identity per action, and every protected action one remote surface serves names the same one; a tenant is a request-time requirement of the handler, not a second identity.
+   * - No surface provides a public action an identity: an action whose answer depends on the caller is protected.
+   * - Never provide an identity at startup, to a surface's layer: a call no authentication reaches, a public action's or a local surface's, runs as that identity, and the types do not stop it.
    */
-  readonly caller: typeof Anyone | Context.Key<unknown, unknown>;
+  readonly caller: typeof Anyone | (Context.Key<unknown, unknown> & {
+    readonly defaultValue?: "An identity is a Context.Service, not a Context.Reference";
+  });
+  /** A model reads it beside the tool; a CLI prints it in `--help`. */
   readonly description: string;
   /**
    * 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.
+   *
+   * **Gotchas**
+   *
+   * - Never `Schema.Struct({})` for no arguments: it accepts any value but `null` and `undefined`, and MCP refuses it as a tool's input. Omit `input`: the action then takes `{}`.
+   * - A field callers may omit is `Schema.optional`: on the wire `null` is also accepted and read as left out, as a tool's schema lists, while a typed client refuses `null`. `Schema.optionalKey` takes omission alone; `Schema.NullOr` keeps `null` as a value.
+   * - A field with a decoding default, `Schema.withDecodingDefault`, is still required in a typed client's argument, whose type is the decoded one; the argument itself may be left out only when every field has one, as `{}` then encodes.
+   * - An input that is a class encodes only its instances: a typed client given a plain object fails with `InvalidInput`, `Expected <Class>`.
+   * - A `Schema.makeFilter` check adds nothing to a tool's listed input schema, and `Schema.isPattern` its `pattern` only for a RegExp with the `u` flag: say such a rule in the field's `description`, annotated before the check, since after a custom one it is lost too.
    */
   readonly input?: Codec | Fields | undefined;
-  /** A schema or struct fields. Omit for an action that returns nothing: `Schema.Void`. */
+  /**
+   * A schema or struct fields. Omit for an action that returns nothing, `Schema.Void`; what each
+   * surface answers is on its `layer`, `layerHttp`, `runStdio`, `make` or `command`. A top-level field whose schema is
+   * `Action.Image` is a media field: see `Action.Image`.
+   */
   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, 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`.
+   * `Schema.TaggedError<NoteNotFound>()("NoteNotFound", { id: Schema.String }, { httpApiStatus: 404 })`.
+   * Defaults to none. A handler fails only with these and the built-in errors; every client
+   * decodes each as a typed value.
+   *
+   * **Gotchas**
+   *
+   * - Over HTTP a declared error answers with its `httpApiStatus`, 422 without one; what the other surfaces answer is on their `layerHttp`, `runStdio`, `layer`, `make` or `command`.
+   * - Two schemas sharing a `_tag` throw at `make`, `error _tag "<tag>" names two error schemas`, or at a binding's `make`, `binding of "<name>"`, for one of its errors against the action's or the authentication's; the message says the fix.
+   * - A schema reached twice, listed again, through a union or `Schema.suspend`, is one schema; a union is its members unless it has its own `httpApiStatus`, checks or a transformation, so each member's `_tag` is checked against every other error's.
+   * - Errors without a `_tag` are told apart by their other fields, the first that decodes winning: a failure an earlier schema also accepts is decoded as that one.
+   * - An entry that is a `Schema.suspend` whose thunk reads a `const` declared further down throws a `ReferenceError` at `make`, which reads every `_tag` when called: declare the error first.
+   * - A failure the schemas reject, undeclared or breaking a check, is the call's defect on every surface, beside the `SchemaError` saying why; a class error built with `disableChecks` is accepted and fails to encode instead.
    */
   readonly error?: Codec | ReadonlyArray<Codec> | undefined;
   /**
    * 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.
+   * `readOnlyHint` is it; the library itself authorizes nothing with it. Derive authorization
+   * from it, never from an `mcp` hint: changing an action's `readOnly` then changes who may
+   * call it.
    */
   readonly readOnly: boolean;
   /** How the action's tool presents itself over MCP, and on a native Toolkit's tools. */
@@ -74,24 +110,16 @@ type KnownMcp<O> = {
   readonly mcp?: { readonly [K in UnknownMcp<O>]: never; };
 };
 type ErrorMembers<G> = G extends ReadonlyArray<infer E> ? E : G;
-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;
 type OnlyOptions<O> = { readonly [K in Exclude<O extends unknown ? keyof O : never, keyof Options>]: never; };
-type ServiceCaller<O> = O extends {
-  readonly caller: {
-    readonly defaultValue: unknown;
-  };
-} ? {
-  readonly caller: "An identity is a Context.Service, not a Context.Reference";
-} : unknown;
-type Rules<O> = Options extends O ? unknown : OnlyOptions<O> & ServiceCaller<O> & OwnErrors<O> & KnownMcp<O>;
+type Rules<O> = Options extends O ? unknown : OnlyOptions<O> & KnownMcp<O>;
 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;
 type SchemaOf<O, K extends "input" | "success", Default extends Codec> = CodecOf<Extract<OptionOf<O, K, Default>, Codec | Fields>>;
 type ErrorSchemasOf<O> = ReadonlyArray<ErrorMembers<Extract<OptionOf<O, "error", []>, Codec | ReadonlyArray<Codec>>>>;
-/** A pure contract: schemas and transport metadata. Handlers are bound by `implement`. */
+/**
+ * A pure contract: schemas and transport metadata, bound to handlers by `implement`. Its
+ * `name`, `input`, `success`, `error` and `readOnly` are public: reuse them, as in
+ * `Schema.Array(SaveLink.input)`.
+ */
 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;
@@ -124,9 +152,16 @@ export type Handler<A extends Any, R = never> = (input: A["input"]["Type"]) => E
  */
 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.
+ * Define an action contract: what it takes and answers, whether it changes anything, and who
+ * may call it. 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/`.
+ *
+ * **Gotchas**
+ *
+ * - A name is unique within each binding, MCP endpoint, Toolkit, CLI and client holding it; its form is in the message `Invalid action name` throws.
+ * - A contract says nothing about where it is served: an HTTP or RPC binding, or a surface given `actions`, serves an action only once it is listed; MCP, a Toolkit and a CLI given implementations alone serve every action they hold.
+ * - Surfaces match an implementation to a contract by object identity, never by name: implement, bind and list the one exported value. A list narrowed at run time is still typed as holding every member.
+ * - In a helper whose type parameter stands for `mcp`, `make` refuses the option, since it cannot check the hints: type the parameter `Action.Mcp`, or spread a constant.
  */
 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"]>;
 /**
@@ -152,21 +187,25 @@ type HandlersOf<T extends Target, R, RequestServices> = Single<T, R> | Several<T
 type Deferred<T> = [T][T extends unknown ? 0 : never];
 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>;
 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.
- */
+/** Every authenticated caller may call a protected action. */
 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.
+ * Bind handlers to contracts, behind authorization: one action and its handler, or a list of
+ * actions and a record of handlers keyed by action name, given directly or built by an Effect
+ * whose services are startup requirements, while what a handler yields is a request-time
+ * requirement. `authorize` is required when the list holds a protected contract and runs only
+ * for those.
+ *
+ * **Gotchas**
  *
- * `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.
+ * - A builder runs once per layer graph, however many surfaces serve its implementation; two `implement` calls are two builders, even of one builder Effect.
+ * - What the builder yields is shared by every call; what a handler yields is resolved per call, as the caller must be. A builder yielding the caller is refused where the server is launched.
+ * - Each call has a scope of its own: a resource that must outlive a call is the builder's.
+ * - Pass the builder to `implement` itself: through `.pipe(...)` or a wrapper such as `Effect.withSpan`, an `Effect.fn` handler it returns takes an `any` input. A builder written apart returns its record `satisfies Action.Handlers<typeof actions>`.
+ * - A record holds one own function per action of the list and no other key, or `implement` throws, a builder's when its layer builds; an inherited method does not count.
+ * - Calling the function you passed to `implement` skips authorization and the codecs: call the implementation through `Action.client`.
+ * - What a plain `authorize` yields is a request-time requirement of every surface; to read a store once, make `authorize` an Effect that yields it and returns the function.
+ * - An authorizer fails only with `Unauthenticated` or `Forbidden`; a limit callers should see, such as a rate limit, is the handler's, declared in the action's `error`.
  */
 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";
@@ -177,8 +216,14 @@ export declare function implement<const T extends Target, RequestServices extend
 /**
  * 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.
+ * are built in a graph of their own, sharing nothing they build: provided above the server and
+ * its siblings, it runs each builder once for every surface, with the services it is given.
+ *
+ * **Gotchas**
+ *
+ * - It builds every implementation it is given, those no surface serves included, so it owes their startup services.
+ * - A job merged beside `HttpRouter.serve` with no `Action.layer` above both shares the server's build only when its own side builds first, which depends on timing: put the job inside the layer the server serves, or provide this layer above both.
+ * - Do not wrap a server in `Layer.fresh`: two servers already share no build. It is for two surfaces in one graph that must each have a build of their own; provide what they share, authentication included, outside it.
  */
 export declare function layer<const Apps extends Served>(implementations: Apps): Layer.Layer<never, BuildError<Member<Apps>>, BuildServices<Member<Apps>>>;
 type Method<A extends Any, R> = Call<A, Effect.Effect<A["success"]["Type"], A["error"][number]["Type"] | BuiltIn, R>>;
@@ -196,18 +241,22 @@ export interface ClientOptions<A extends Any> {
   readonly actions?: ReadonlyArray<A> | undefined;
 }
 /**
- * Call implementations in process: one method per action, taking its input directly, as
+ * 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.
+ * two changes the line acquiring it. A call runs as a remote one does, its input and its answer
+ * through their JSON codecs, the implementation's `authorize` and the handler in a scope of
+ * their own, failing with the action's errors and the built-in ones. Acquiring it builds the
+ * implementations' builders into the layer graph it is acquired in, as a layer does, and its
+ * scope holds them: acquire it where builders live.
+ *
+ * **Gotchas**
  *
- * 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.
+ * - Provide the caller around each call, and startup services around the acquisition: a call reads its own context, never the one the client was acquired in, so one client serves every caller.
+ * - Acquiring it needs a `Scope`: `it.effect` supplies one, elsewhere `Effect.scoped` does; acquired in a handler, it builds on every request.
+ * - Two acquisitions share a build only inside one layer graph, such as under a layer provided around the program; with none around them, each builds its own.
+ * - Every implemented action has a method, whether or not a surface serves it; `actions` lists the ones to call, and an implementation holding none of them is left unbuilt.
+ * - It drops undeclared input fields as it encodes, and fails with `InvalidInput`, running nothing, for an input that does not encode.
+ * - A builder acquiring a client of its own implementation is refused by the compiler, TS7022, and with the types bypassed never completes: call the services both use instead.
  */
 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

package/dist/Action.mjs

@@ -1,7 +1,7 @@
 import { Anyone } from "./contract/caller.mjs";
 import { BuiltIn, Forbidden, InvalidInput, Refusal, Unauthenticated } from "./contract/errors.mjs";
-import { assertKnown, assertName, assertOnce } from "./contract/names.mjs";
-import { assertOwnTags, errorList, projectedErrors } from "./contract/declared.mjs";
+import { assertKnown, assertName, assertOnce, heldOnce } from "./contract/names.mjs";
+import { assertDistinctTags, errorList, projectedErrors } from "./contract/declared.mjs";
 import { Implementation, builders, built, memoized, select, toList } from "./contract/implementation.mjs";
 import { inputOf } from "./contract/call.mjs";
 import { Image } from "./contract/media.mjs";
@@ -10,11 +10,11 @@ import { Array as Array$1, Cause, Context, Effect, Predicate, Schema } from "eff
 const NoInput = Schema.Record(Schema.String, Schema.Never);
 const codecOf = (schema) => Schema.isSchema(schema) ? schema : Reflect.ownKeys(schema).length === 0 ? NoInput : Schema.Struct(schema);
 function make(name, options) {
-	assertName("action name", name);
+	assertName(name);
 	const { caller, readOnly } = options;
 	if (caller !== Anyone && !Context.isKey(caller)) throw new Error("Missing caller: declare Action.Anyone or an identity service key");
 	if (caller !== Anyone && Context.isReference(caller)) throw new Error("Invalid caller: an identity is a Context.Service, not a Context.Reference");
-	if (readOnly !== true && readOnly !== false) throw new Error(`Invalid readOnly: ${String(readOnly)}`);
+	if (readOnly !== true && readOnly !== false) throw new Error(`Invalid readOnly: ${String(readOnly)} (set true or false)`);
 	const action = {
 		caller,
 		name,
@@ -25,20 +25,17 @@ function make(name, options) {
 		readOnly,
 		mcp: { ...options.mcp }
 	};
-	assertOwnTags(`Action "${action.name}"`, action.error);
+	assertDistinctTags(`Action "${action.name}"`, projectedErrors(action));
 	return action;
 }
 function byName(actions) {
 	assertOnce("action", actions);
 	return Object.fromEntries(actions.map((action) => [action.name, action]));
 }
-/**
-* Every authenticated caller may call a protected action. The contract's identity
-* requirement is enforced independently, including when its handler reads no identity.
-*/
+/** Every authenticated caller may call a protected action. */
 const allowAll = () => Effect.void;
 const assertAuthorizer = (before) => {
-	if (!Predicate.isFunction(before)) throw new Error("Missing authorize: pass an authorization function, or Action.allowAll");
+	if (!Predicate.isFunction(before)) throw new Error("Missing authorize: not a function (pass your rule, Action.allowAll, or an Effect returning one)");
 	return before;
 };
 const assertAuthorization = (authorize) => {
@@ -46,7 +43,7 @@ const assertAuthorization = (authorize) => {
 	return authorize;
 };
 const assertNoAuthorization = (authorize) => {
-	if (authorize !== void 0) throw new Error("A public-only target takes no authorize");
+	if (authorize !== void 0) throw new Error("A public-only target takes no authorize (remove it, or list a protected action)");
 	return allowAll;
 };
 const authorizerOf = (before) => memoized(Effect.isEffect(before) ? Effect.map(before, assertAuthorizer) : Effect.succeed(assertAuthorizer(before)));
@@ -57,13 +54,13 @@ function implement(actions, handlers, options) {
 	const authorizer = authorizerOf(listed.some((action) => action.caller !== Anyone) ? assertAuthorization(options?.authorize) : assertNoAuthorization(options?.authorize));
 	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);
+		assertKnown("handlers", Object.keys(keyed), names, "remove it, or list its action");
 		const bound = listed.flatMap((action) => {
 			const handle = Object.hasOwn(keyed, action.name) ? keyed[action.name] : void 0;
 			return Predicate.isFunction(handle) ? [[action, handle]] : [];
 		});
 		const missing = names.filter((name) => !bound.some(([action]) => action.name === name));
-		if (missing.length > 0) throw new Error(`Missing handlers: ${missing.join(", ")}`);
+		if (missing.length > 0) throw new Error(`Missing handlers: ${missing.join(", ")} (return the handler for one action, or a record with an own function per listed action)`);
 		return bound;
 	};
 	const recorded = Effect.isEffect(handlers) ? Effect.map(handlers, pairWithActions) : Effect.succeed(pairWithActions(handlers));
@@ -90,7 +87,7 @@ const methodOf = (action, run) => {
 };
 function client(served, options) {
 	const apps = select(toList(served), options?.actions);
-	assertOnce("action", apps.flatMap((app) => app.actions));
+	assertOnce("action", apps.flatMap((app) => app.actions), heldOnce);
 	return Effect.map(built(apps), (bound) => Object.fromEntries(bound.map(([action, run]) => [action.name, methodOf(action, run)])));
 }
 //#endregion