@gjermundgaraba/effect-actions 0.18.2 → 0.20.0

package/dist/contract/implementation.mjs

@@ -1,9 +1,9 @@
 import { Anyone, assertAuthentication } from "./caller.mjs";
 import { Unauthenticated } from "./errors.mjs";
-import { assertDistinct, assertOnce } from "./names.mjs";
+import { assertDistinct, assertOnce, heldOnce } from "./names.mjs";
 import { projectedErrors } from "./declared.mjs";
 import { Array, Cause, Context, Effect, Exit, Layer, Option, Schema } from "effect";
-//#region src/contract/implementation.ts
+// src/contract/implementation.ts
 const uniqueKey = () => Math.random().toString(36).slice(2);
 const memoized = (build) => {
 	const key = Context.Service(`effect-actions/Implementation/${uniqueKey()}`);
@@ -14,16 +14,15 @@ const memoized = (build) => {
 };
 /**
 * Actions bound to their handlers and their authorizer: everything one `Action.implement` call
-* produced, one builder serving every surface.
-* The private fields make this class nominal: a structurally similar object, including one made by
+* produced, one builder serving every surface. The private fields make this class nominal: a structurally similar object, including one made by
 * spreading an implementation, is not an implementation. Its type parameters may be written
 * out, as a package emitting declarations prints them: `A` its actions, `RequestServices` each
-* action name's handler's per-request requirements, `EX` and `RX` the failures and services of
+* action name's handler's request-time requirements, `EX` and `RX` the failures and services of
 * its handlers' builder, `RA` what its authorizer reads per request, and `EAX` and `RAX` the
-* failures and services of the authorizer's builder. Public-only selections do not acquire
-* authorization. A plain authorization callback builds nothing.
+* failures and services of the authorizer's builder.
 */
 var Implementation = class Implementation {
+	/** The contracts this implementation answers. */
 	actions;
 	#handlers;
 	#authorizer;
@@ -47,8 +46,7 @@ var Implementation = class Implementation {
 	/**
 	* The builders of `app`, its handlers' and its authorizer's, as a layer. Effect memoizes each
 	* by reference within one layer graph, so every surface serving `app` there, and every
-	* implementation sharing its builder, shares one run. Static, so it stays off the
-	* public instance type.
+	* implementation sharing its builder, shares one run.
 	*/
 	static layerOf(app) {
 		const source = Implementation.own(app);
@@ -69,21 +67,36 @@ var Implementation = class Implementation {
 	}
 	/** `app`, if this copy of the module made it; another installed copy's cannot be read. */
 	static own(app) {
-		if (!(#handlers in app)) throw new Error("Not an implementation made by this Action.implement: is effect-actions installed twice?");
+		if (!(#handlers in app)) throw new Error("Not an implementation made by this Action.implement: pass the value implement returned, not a copy such as a spread; or effect-actions is installed twice");
 		return app;
 	}
 };
 const toList = (served) => Array.ensure(served);
-const assertHeld = (why, listed, held) => {
+const notHeld = {
+	byImplementation: {
+		why: "no implementation holds it",
+		fix: "pass the implementation holding it, or list the contract it implements",
+		holder: "they do not hold: list the one they hold"
+	},
+	byBinding: {
+		why: "the binding does not hold it",
+		fix: "add it to the binding's actions",
+		holder: "it does not hold: list the one it holds"
+	}
+};
+/** The actions' names, joined; one whose name another listed contract shares is marked `(another contract)`. */
+const markingOthers = (actions, names) => actions.map(({ name }) => names.has(name) ? `${name} (another contract)` : name).join(", ");
+const assertHeld = ({ why, fix, holder }, listed, held) => {
 	const missing = listed.filter((action) => !held.includes(action));
 	if (missing.length > 0) {
 		const names = new Set(held.map(({ name }) => name));
-		throw new Error(`Listed in actions, but ${why}: ${missing.map(({ name }) => names.has(name) ? `${name} (another contract)` : name).join(", ")}`);
+		const sameName = missing.some(({ name }) => names.has(name));
+		throw new Error(`Listed in actions, but ${why}: ${markingOthers(missing, names)} (${fix}${sameName ? `; one marked (another contract) is a contract of that name ${holder}` : ""})`);
 	}
 };
 const select = (apps, listed) => {
 	if (listed === void 0) return apps;
-	assertHeld("no implementation holds it", listed, apps.flatMap((app) => app.actions));
+	assertHeld(notHeld.byImplementation, listed, apps.flatMap((app) => app.actions));
 	return apps.flatMap((app) => {
 		const own = app.actions.filter((action) => listed.includes(action));
 		if (own.length === 0) return [];
@@ -91,15 +104,15 @@ const select = (apps, listed) => {
 	});
 };
 const servedBy = (what, bound, apps, listed) => {
-	if (listed !== void 0) assertHeld("the binding does not hold it", listed, bound);
+	if (listed !== void 0) assertHeld(notHeld.byBinding, listed, bound);
 	const held = apps.flatMap((app) => app.actions);
 	const served = select(apps, listed ?? bound.filter((action) => held.includes(action)));
 	const actions = served.flatMap((app) => app.actions);
 	if (actions.length === 0 && listed === void 0 && apps.length > 0) {
 		const names = new Set(bound.map(({ name }) => name));
-		throw new Error(`No action of these implementations is in this ${what}: ${held.map(({ name }) => names.has(name) ? `${name} (another contract)` : name).join(", ") || "none"}`);
+		throw new Error(`No action of these implementations is in this ${what}: ${markingOthers(held, names) || "none"} (pass an implementation of a bound action, or bind one of these)`);
 	}
-	assertOnce("served action", actions);
+	assertOnce("served action", actions, heldOnce);
 	return served;
 };
 /**
@@ -110,7 +123,7 @@ const servingOf = (what, binding, served, options) => {
 	const apps = servedBy(what, binding.actions, toList(served), options.actions);
 	const actions = apps.flatMap((app) => app.actions);
 	assertAuthentication(actions, binding.authentication);
-	assertDistinct("middleware", options.middleware ?? [], (key) => key.key);
+	assertDistinct("middleware", options.middleware ?? [], (key) => key.key, { fix: "list each middleware once" });
 	return {
 		apps,
 		actions,
@@ -156,5 +169,4 @@ const dispatch = (action, handle, before) => {
 	});
 	return (input) => Effect.scoped(authentication.pipe(Effect.andThen(authorization), Effect.andThen(Effect.suspend(() => handle(input))), Effect.catchCause(declaredOrDefect))).pipe(Effect.annotateLogs(actionAttributes), Effect.withSpan(action.name, { attributes: actionAttributes }, { captureStackTrace: false }));
 };
-//#endregion
-export { Implementation, acquire, assertHeld, builders, built, memoized, provideHandlers, select, servingOf, toList };
+export { Implementation, acquire, assertHeld, builders, built, memoized, notHeld, provideHandlers, select, servingOf, toList };

package/dist/contract/media.d.mts

@@ -1,13 +1,15 @@
 import { Schema, SchemaAST } from "effect";
-//#region src/contract/media.d.ts
 /**
  * An image, a media field of a success: `{ data: Uint8Array, mimeType: string }`, `mimeType` such
- * as `image/png`. A top-level field of a struct success, optional or an array, or the whole
- * success, one or an array: an MCP tool lifts it into an image block of its own, and every other
+ * as `image/png`. A top-level field of a struct success, one, optional, or a required array, or the
+ * whole success, one or an array: an MCP tool lifts it into an image block of its own, and every other
  * surface sends it as JSON, the bytes in base64. `ActionMcp` refuses it anywhere else.
+ *
+ * **Gotchas**
+ *
+ * - A media field's own `description` reaches no model: describe the image in the action's `description`.
  */
 export declare const Image: Schema.Struct<{
   readonly data: Schema.Uint8Array;
   readonly mimeType: Schema.String;
-}>;
-//#endregion
+}>;

package/dist/contract/media.mjs

@@ -1,5 +1,5 @@
 import { Schema } from "effect";
-//#region src/contract/media.ts
+// src/contract/media.ts
 const mediaKindAnnotation = "effect-actions/media";
 const Media = Schema.Struct({
 	data: Schema.Uint8Array,
@@ -7,12 +7,15 @@ const Media = Schema.Struct({
 });
 /**
 * An image, a media field of a success: `{ data: Uint8Array, mimeType: string }`, `mimeType` such
-* as `image/png`. A top-level field of a struct success, optional or an array, or the whole
-* success, one or an array: an MCP tool lifts it into an image block of its own, and every other
+* as `image/png`. A top-level field of a struct success, one, optional, or a required array, or the
+* whole success, one or an array: an MCP tool lifts it into an image block of its own, and every other
 * surface sends it as JSON, the bytes in base64. `ActionMcp` refuses it anywhere else.
+*
+* **Gotchas**
+*
+* - A media field's own `description` reaches no model: describe the image in the action's `description`.
 */
 const Image = Media.annotate({ [mediaKindAnnotation]: "image" });
 const isMarked = (ast) => ast.annotations?.[mediaKindAnnotation] === "image";
 const kindOf = (ast) => isMarked(ast) && ast.encoding === void 0 ? "image" : void 0;
-//#endregion
 export { Image, Media, isMarked, kindOf };

package/dist/contract/names.mjs

@@ -1,25 +1,26 @@
-//#region src/contract/names.ts
-const validName = /^[A-Za-z0-9_-]{1,128}$/;
-const assertName = (what, name) => {
-	if (!validName.test(name) || name === "then") throw new Error(`Invalid ${what}: ${name}`);
+// src/contract/names.ts
+const namePattern = "[A-Za-z0-9_-]{1,128}";
+const validName = new RegExp(`^${namePattern}$`);
+const assertName = (name) => {
+	if (!validName.test(name) || name === "then") throw new Error(`Invalid action name: ${name} (use ${namePattern}, other than "then")`);
 };
-const assertDistinct = (what, items, nameOf, claimantOf = nameOf) => {
+const assertDistinct = (what, items, nameOf, { claimantOf = nameOf, labelOf = nameOf, fix }) => {
 	const seen = /* @__PURE__ */ new Map();
 	for (const item of items) {
 		const name = nameOf(item);
-		const claimant = claimantOf(item);
 		const other = seen.get(name);
 		if (other !== void 0) {
-			const by = other === claimant ? "" : `, claimed by ${other} and ${claimant}`;
-			throw new Error(`Duplicate ${what}: ${name}${by}`);
+			const claimants = [claimantOf(other), claimantOf(item)];
+			const by = claimants[0] === claimants[1] ? "" : `, claimed by ${claimants.join(" and ")}`;
+			throw new Error(`Duplicate ${what}: ${labelOf(other)}${by} (${fix})`);
 		}
-		seen.set(name, claimant);
+		seen.set(name, item);
 	}
 };
-const assertOnce = (what, actions) => assertDistinct(what, actions, (action) => action.name);
-const assertKnown = (what, keys, names) => {
+const heldOnce = "pass one implementation of it, or rename one";
+const assertOnce = (what, actions, fix = "list it once, or rename one") => assertDistinct(what, actions, (action) => action.name, { fix });
+const assertKnown = (what, keys, names, fix) => {
 	const unknown = keys.filter((key) => !names.includes(key));
-	if (unknown.length > 0) throw new Error(`Unknown ${what}: ${unknown.join(", ")}`);
+	if (unknown.length > 0) throw new Error(`Unknown ${what}: ${unknown.join(", ")} (${fix})`);
 };
-//#endregion
-export { assertDistinct, assertKnown, assertName, assertOnce };
+export { assertDistinct, assertKnown, assertName, assertOnce, heldOnce };

package/dist/contract/status.mjs

@@ -1,18 +1,10 @@
-import { unsuspended } from "./ast.mjs";
-import { Schema, SchemaAST } from "effect";
-//#region src/contract/status.ts
+import { SchemaAST } from "effect";
+// src/contract/status.ts
 const httpApiStatusOf = SchemaAST.resolveAt("httpApiStatus");
 const statusThroughSuspensions = (ast) => httpApiStatusOf(ast) ?? (SchemaAST.isSuspend(ast) ? statusThroughSuspensions(ast.thunk()) : void 0);
-/**
-* `error` as an endpoint declares it: each member of a union without a status of its own apart,
-* each with its status, 422 without one.
-*/
+/** One error schema, from `errorSchemas`, as an endpoint declares it: with its status, 422 without one. */
 const declared = (error) => {
 	const status = statusThroughSuspensions(error.ast);
-	if (status !== void 0) return [httpApiStatusOf(error.ast) === void 0 ? error.annotate({ httpApiStatus: status }) : error];
-	const resolved = unsuspended(error.ast);
-	if (SchemaAST.isUnion(resolved) && resolved.checks === void 0 && resolved.encoding === void 0) return resolved.types.flatMap((member) => declared(Schema.make(member)));
-	return [error.annotate({ httpApiStatus: 422 })];
+	return status === void 0 ? error.annotate({ httpApiStatus: 422 }) : httpApiStatusOf(error.ast) === void 0 ? error.annotate({ httpApiStatus: status }) : error;
 };
-//#endregion
 export { declared, httpApiStatusOf };

package/dist/http/client.d.mts

@@ -5,18 +5,28 @@ import { Any as Any$1, VerifierError } from "../authentication/provider.mjs";
 import { Effect, Schema } from "effect";
 import { HttpClient, HttpClientError } from "effect/http";
 import { HttpApi, HttpApiClient } from "effect/http-api";
-//#region src/http/client.d.ts
 /**
  * The native `HttpApiClient.make` options except `transformResponse`, which may change a call's
  * success, failure or services the method types cannot follow: `baseUrl`, and `transformClient`,
  * which may return a client failing with `E` or requiring `R` of its own, as
  * `HttpApiClient.makeWith` takes one.
  */
-export interface Options<E = HttpClientError.HttpClientError, R = never> extends Pick<NonNullable<Parameters<typeof HttpApiClient.make>[1]>, "baseUrl"> {
+export interface Options<E = HttpClientError.HttpClientError, R = never> {
+  /**
+   * What the routes resolve against: `https://api.example.com`. Omitted: relative routes, which
+   * a page resolves against its own origin.
+   *
+   * **Gotchas**
+   *
+   * - Outside a browser, set it: a relative route has no page to resolve against, and the call fails with an `HttpClientError` whose `reason._tag` is `InvalidUrlError`.
+   */
+  readonly baseUrl?: NonNullable<Parameters<typeof HttpApiClient.make>[1]>["baseUrl"];
   /**
    * Wraps the native `HttpClient` the calls send with: a bearer token is
-   * `HttpClient.mapRequest(HttpClientRequest.bearerToken(token))`. A method also fails with what
-   * the returned client fails with beyond an `HttpClientError`, and requires what it requires.
+   * `HttpClient.mapRequest(HttpClientRequest.bearerToken(token))`, and a credential read or
+   * refreshed as each request is sent `(client) => HttpClient.mapRequestEffect(client, authorize)`.
+   * A method also fails with what the returned client fails with beyond an `HttpClientError`, as
+   * it is, and requires what it requires.
    */
   readonly transformClient?: ((client: HttpClient.HttpClient) => HttpClient.HttpClient.With<E, R>) | undefined;
 }
@@ -25,7 +35,7 @@ type BindingError = Errors[number];
  * What one call of `A` fails with: a declared error value (the action's own, one `E` of the
  * binding's, or a built-in `InvalidInput`, `Unauthenticated` or `Forbidden`), a native
  * `HttpClientError` for a failed request or an undeclared answer, or a `SchemaError` when
- * the success does not decode. Input that does not encode is `InvalidInput`, and nothing is sent.
+ * the success does not decode.
  */
 export type MethodError<A extends Any, E extends BindingError = never> = A["error"][number]["Type"] | E["Type"] | BuiltIns["Type"] | HttpClientError.HttpClientError | Schema.SchemaError;
 type Method<A extends Any, E extends BindingError, CE, CR> = Call<A, Effect.Effect<A["success"]["Type"], MethodError<A, E> | CE, CR>>;
@@ -47,5 +57,4 @@ export interface AnyHttp {
  * what its `transformClient` adds.
  */
 export type Client<H extends AnyHttp, E = never, R = never> = { readonly [A in H["actions"][number] as A["name"]]: Method<A, H["error"][number] | VerifierError<A, H["authentication"]>, E, R>; };
-//#endregion
 export {};

package/dist/http/client.mjs

@@ -2,7 +2,7 @@ import { checked } from "../contract/call.mjs";
 import { Effect } from "effect";
 import { HttpClient } from "effect/http";
 import { HttpApiClient } from "effect/http-api";
-//#region src/http/client.ts
+// src/http/client.ts
 const methodsWith = (http, httpClient, baseUrl) => Effect.map(HttpApiClient.makeWith(http.api, {
 	baseUrl,
 	httpClient
@@ -10,10 +10,9 @@ const methodsWith = (http, httpClient, baseUrl) => Effect.map(HttpApiClient.make
 	const native = client;
 	return Object.fromEntries(http.actions.map((action) => {
 		const method = native[action.name];
-		if (method === void 0) throw new Error(`No client method for ${action.name}`);
+		if (method === void 0) throw new Error(`No client method for ${action.name} (use the binding \`ActionHttp.make\` returned, whose group holds this action)`);
 		return [action.name, checked(action, (payload) => method({ payload }))];
 	}));
 });
 const methods = (http, { baseUrl, transformClient } = {}) => Effect.flatMap(HttpClient.HttpClient, (native) => transformClient === void 0 ? methodsWith(http, native, baseUrl) : methodsWith(http, transformClient(native), baseUrl));
-//#endregion
 export { methods };

package/dist/http/schema-errors.mjs

@@ -1,9 +1,8 @@
 import { InvalidInput } from "../contract/errors.mjs";
 import { Effect } from "effect";
 import { HttpApiMiddleware } from "effect/http-api";
-//#region src/http/schema-errors.ts
+// src/http/schema-errors.ts
 const responseEncodingKinds = /* @__PURE__ */ new Set(["Body", "ResponseHeaders"]);
 var SchemaErrors = class extends HttpApiMiddleware.Service()("effect-actions/http/SchemaErrors", { error: [InvalidInput] }) {};
 const schemaErrors = () => HttpApiMiddleware.layerSchemaErrorTransform(SchemaErrors, (failure) => Effect.fail(responseEncodingKinds.has(failure.kind) ? failure : InvalidInput.fromSchemaError(failure.cause)));
-//#endregion
 export { SchemaErrors, schemaErrors };

package/dist/mcp/client.d.mts

@@ -4,7 +4,6 @@ import { Any } from "../Action.mjs";
 import { Any as Any$1, VerifierError } from "../authentication/provider.mjs";
 import { Effect, Schema } from "effect";
 import { Headers, HttpClient, HttpClientError, HttpClientRequest } from "effect/http";
-//#region src/mcp/client.d.ts
 /**
  * An MCP request's parameters, as `request` takes them: JSON, with any `_meta`, leaving
  * out an `undefined` one, as a caller may. A helper passing on whole params types them as this,
@@ -23,7 +22,8 @@ export interface Params {
 export interface ClientOptions<D extends Any$1 | undefined = Any$1 | undefined, E = HttpClientError.HttpClientError, R = never> {
   /**
    * The endpoint, resolved by the `HttpClient`: relative under `Testing.layer`. Defaults to `/mcp`,
-   * the default `layerHttp` path.
+   * the default `layerHttp` path, so a call to an endpoint on another `path` fails with an
+   * `McpCallError` that `answered 404`.
    */
   readonly url?: string;
   /**
@@ -34,7 +34,8 @@ export interface ClientOptions<D extends Any$1 | undefined = Any$1 | undefined,
   /**
    * The endpoint's descriptor, as `layerHttp` takes it: an error its verifier declares, the
    * endpoint's HTTP answer for a protected tool, is then that error's decoded value, as over
-   * `ActionHttp.client`.
+   * `ActionHttp.client`; without it, the call fails with an `McpCallError` whose `reason` is a
+   * `StatusError`.
    */
   readonly authentication?: D;
 }
@@ -46,6 +47,10 @@ export interface RequestOptions {
    * one.
    */
   readonly url?: string;
+  /**
+   * Headers sent beside the routing ones `request` fills in, such as `Authorization`; a routing
+   * header wins over a given one of its name.
+   */
   readonly headers?: Headers.Input;
 }
 declare const StatusError_base: Schema.Class<StatusError, Schema.TaggedStruct<"StatusError", {
@@ -59,8 +64,7 @@ declare const ProtocolError_base: Schema.Class<ProtocolError, Schema.TaggedStruc
   readonly message: Schema.String;
 }>, import("effect/Cause").YieldableError>;
 /**
- * The endpoint answered with a JSON-RPC error, such as the native server's for invalid arguments
- * or an unknown tool.
+ * The endpoint answered with a JSON-RPC error, such as the native server's for an unknown tool.
  */
 declare class ProtocolError extends ProtocolError_base {}
 declare const NoReply_base: Schema.Class<NoReply, Schema.TaggedStruct<"NoReply", {
@@ -89,6 +93,10 @@ declare const McpCallError_base: Schema.Class<McpCallError, Schema.TaggedStruct<
  * `Effect.catchReason("McpCallError", "StatusError", ...)`. `message` names the tool and the
  * reason. Structured content that does not decode as the success is a `SchemaError` instead,
  * and a request that fails an `HttpClientError`.
+ *
+ * **Gotchas**
+ *
+ * - `returned an error: Invalid parameters for tool …`, an `UndeclaredError`, from a call its types allowed: the endpoint serves another contract under that name; give `client` the served contract value.
  */
 export declare class McpCallError extends McpCallError_base {}
 type CallError<A extends Any, D> = A["error"][number]["Type"] | VerifierError<A, D>["Type"] | BuiltIn | Schema.SchemaError | HttpClientError.HttpClientError | McpCallError;
@@ -103,10 +111,14 @@ export type Client<Actions extends ReadonlyArray<Any>, D = undefined, E = never,
  * encoded with the action's schema, and the success decoded from its structured content, each
  * media field from the blocks whose `_meta` names it, and a success that is media, or whose
  * every field is, from its blocks alone. A declared error the tool returns, the action's own
- * or a refusal, is its decoded value, and so is a refusal the endpoint's authentication
- * answers with, or an error its verifier declares, given the `authentication`: a test telling a 401 or 403 from a tool result asserts the status of a request
- * `request` builds. The argument may be omitted when `{}` is a valid input. Requires the
- * native `HttpClient`, such as the one `Testing.layer` provides.
+ * or a refusal, is its decoded value, and so is a refusal the endpoint's authentication answers
+ * with: a test telling a 401 or 403 from a tool result asserts the status of a request `request`
+ * builds. The argument may be omitted when `{}` is a valid input. Requires the native
+ * `HttpClient`, such as the one `Testing.layer` provides.
+ *
+ * **Gotchas**
+ *
+ * - It drops undeclared input fields as it encodes, and fails with `InvalidInput`, sending nothing, for an input that does not encode.
  */
 export declare function client<const Actions extends ReadonlyArray<Any>, D extends Any$1 | undefined = undefined>(actions: Actions, options?: ClientOptions<D>): Effect.Effect<Client<Actions, D>, never, HttpClient.HttpClient>;
 export declare function client<const Actions extends ReadonlyArray<Any>, E, R, D extends Any$1 | undefined = undefined>(actions: Actions, options: ClientOptions<D, E, R>): Effect.Effect<Client<Actions, D, E, R>, never, HttpClient.HttpClient>;
@@ -123,5 +135,4 @@ export declare function client<const Actions extends ReadonlyArray<Any>, E, R, D
  * a call its types would not send.
  */
 export declare const request: (method: string, params?: Params, { headers, url }?: RequestOptions) => HttpClientRequest.HttpClientRequest;
-//#endregion
 export {};

package/dist/mcp/client.mjs

@@ -8,16 +8,11 @@ import { Effect, Match, Option, Predicate, Schema } from "effect";
 import { McpSchema } from "effect/ai";
 import { HttpClient, HttpClientRequest } from "effect/http";
 import { Sse } from "effect/encoding";
-//#region src/mcp/client.ts
-/**
-* One stateless MCP request of `method` with `params`, as `layerHttp` serves it: the headers
-* routing it, which repeat what its body says, and its JSON-RPC body. The client metadata goes in
-* `_meta`, under any given, such as a `progressToken`; the protocol version is always the
-* request's own.
-*/
+// src/mcp/client.ts
+/** The routing headers and JSON-RPC body of the request `request` builds. */
 const statelessRequest = (method, params) => {
 	const { protocolVersion } = httpProtocol;
-	const name = method === "resources/read" ? params.uri : params.name;
+	const name = method === "resources/read" ? params["uri"] : params["name"];
 	return {
 		headers: {
 			accept: "application/json, text/event-stream",
@@ -50,8 +45,7 @@ var StatusError = class extends Schema.TaggedError()("StatusError", {
 	body: Schema.String
 }) {};
 /**
-* The endpoint answered with a JSON-RPC error, such as the native server's for invalid arguments
-* or an unknown tool.
+* The endpoint answered with a JSON-RPC error, such as the native server's for an unknown tool.
 */
 var ProtocolError = class extends Schema.TaggedError()("ProtocolError", {
 	code: Schema.Finite,
@@ -83,6 +77,10 @@ const sentenceOf = Match.typeTags()({
 * `Effect.catchReason("McpCallError", "StatusError", ...)`. `message` names the tool and the
 * reason. Structured content that does not decode as the success is a `SchemaError` instead,
 * and a request that fails an `HttpClientError`.
+*
+* **Gotchas**
+*
+* - `returned an error: Invalid parameters for tool …`, an `UndeclaredError`, from a call its types allowed: the endpoint serves another contract under that name; give `client` the served contract value.
 */
 var McpCallError = class extends Schema.TaggedError()("McpCallError", {
 	tool: Schema.String,
@@ -161,5 +159,4 @@ const request = (method, params = {}, { headers = {}, url = defaultPath } = {})
 	const { headers: routingHeaders, body } = statelessRequest(method, params);
 	return HttpClientRequest.post(url).pipe(HttpClientRequest.setHeaders(headers), HttpClientRequest.setHeaders(routingHeaders), HttpClientRequest.bodyJsonUnsafe(body));
 };
-//#endregion
 export { McpCallError, client, request, statelessRequest };

package/dist/mcp/protocol.mjs

@@ -3,7 +3,7 @@ import { Media, isMarked, kindOf } from "../contract/media.mjs";
 import { Predicate, Schema, SchemaAST } from "effect";
 import { McpProtocol } from "effect/ai";
 import { Base64 } from "effect/encoding";
-//#region src/mcp/protocol.ts
+// src/mcp/protocol.ts
 const httpProtocol = McpProtocol.v2026_07_28;
 const protocols = [
 	McpProtocol.v2026_07_28,
@@ -133,5 +133,4 @@ const unliftedFrom = (lift, result) => {
 		return field.name === void 0 || value === void 0 ? [] : [[field.name, value]];
 	})]);
 };
-//#endregion
 export { defaultPath, fieldKey, httpProtocol, isMisplaced, liftOf, liftedFrom, protocols, unliftedFrom };

package/dist/stdio/console.mjs

@@ -1,5 +1,5 @@
 import { Clock, Console, Effect, Function, Predicate } from "effect";
-//#region src/stdio/console.ts
+// src/stdio/console.ts
 const stderrConsole = (console, clock) => {
 	const counts = /* @__PURE__ */ new Map();
 	const timers = /* @__PURE__ */ new Map();
@@ -60,5 +60,4 @@ const stderrConsole = (console, clock) => {
 	};
 };
 const withStderrConsole = (effect) => Effect.provideServiceEffect(effect, Console.Console, Effect.zipWith(Effect.service(Console.Console), Effect.service(Clock.Clock), stderrConsole));
-//#endregion
 export { withStderrConsole };

package/dist/testing/memory.d.mts

@@ -1,6 +1,4 @@
 import { Layer } from "effect";
 import { HttpClient, HttpRouter, HttpServer } from "effect/http";
-//#region src/testing/memory.d.ts
 /** What in-memory routes may leave to the host: the router, the platform, nothing per request. */
-export type Served = HttpRouter.HttpRouter | HttpRouter.Request<"Requires", never> | HttpRouter.Request<"GlobalRequires", never> | HttpRouter.Request<"Error", any> | HttpRouter.Request<"GlobalError", any> | Layer.Success<typeof HttpServer.layerServices>;
-//#endregion
+export type Served = HttpRouter.HttpRouter | HttpRouter.Request<"Requires", never> | HttpRouter.Request<"GlobalRequires", never> | HttpRouter.Request<"Error", any> | HttpRouter.Request<"GlobalError", any> | Layer.Success<typeof HttpServer.layerServices>;

package/dist/testing/memory.mjs

@@ -1,6 +1,6 @@
 import { Effect, Layer, Predicate, Stream } from "effect";
 import { FetchHttpClient, HttpBody, HttpClient, HttpClientRequest } from "effect/http";
-//#region src/testing/memory.ts
+// src/testing/memory.ts
 const relativeUrlOrigin = "http://localhost/";
 const withWebStreamBodyInCurrentContext = (request) => {
 	const body = request.body;
@@ -22,5 +22,4 @@ const clientOf = (handler) => {
 		return Effect.flatMap(withWebStreamBodyInCurrentContext(sent), (ready) => native.postprocess(Effect.succeed(ready)).pipe(Effect.provideService(FetchHttpClient.Fetch, fetch)));
 	}), native.preprocess))).pipe(Layer.provide(Layer.fresh(FetchHttpClient.layer)));
 };
-//#endregion
 export { clientOf };

package/docs/Action-failures.md

@@ -6,42 +6,33 @@ The tasks are in [Action.md](Action.md).
 ## At `make`
 
 - `Argument of type 'Struct<…>' is not assignable to parameter of type 'Fields'` at `Schema.Struct(X.input)`, or `Objects property names must be strings` or `Invalid value used as weak map key` thrown: an action's `input` is a schema already, a `Schema.Struct` where fields were given. Use it as it is: `Schema.Array(X.input)`.
-- `Invalid action name: <name>` thrown: an action's name matches `[A-Za-z0-9_-]{1,128}` and is not `then`. Rename the action.
 - `'readOnlyHint' does not exist in type 'Mcp'`, or `Type 'true' is not assignable to type 'never'` on `readOnlyHint` beside another hint: a tool's read-only hint is its action's `readOnly`. Set `readOnly` instead.
 - `'<key>' does not exist in type 'Options'`, or `in type 'Mcp'`, or `Type '...' is not assignable to type 'never'` on the key: `make` takes no such option or hint. The key may be misspelled, such as `destructive` for `destructiveHint`.
-- `Type 'H' is not assignable to type 'H & ...'`, or `… is not assignable to type 'ServiceCaller<…>'`, or `… is not assignable to type '[Extract<ErrorMembers<E>, …>] extends …'`, at `make` in a helper whose type parameter stands for `mcp`, `caller` or `error`, as in `<const H extends Action.Mcp>(mcp: H)`: `make` refuses options a type parameter stands for. Type the parameter concretely, `Action.Mcp` or `typeof CurrentUser`, or spread a constant object into the options.
-- A type error on `error`, `... is not assignable to type 'readonly never[]'` or naming the remaining errors, or `Action "<name>": error _tag "Forbidden" is built in, and declared on every surface` thrown: an action's `error` lists a built-in error, or one of your own that encodes with the `_tag` `InvalidInput`, `Unauthenticated` or `Forbidden`. Drop the built-in error, which a handler may fail with anyway; rename your own.
+- `Type 'H' is not assignable to type 'H & ...'` at `make` in a helper whose type parameter stands for `mcp`, as in `<const H extends Action.Mcp>(mcp: H)`: `make` cannot check the hints of a type parameter. Type the parameter `Action.Mcp`, or spread a constant object into the options.
 - `ReferenceError` thrown where a contract is defined: `make` reads every declared error's `_tag` when it is called, so an entry of `error` that is a `Schema.suspend` whose thunk reads a `const` declared further down fails at once. Declare the error before the action.
 
 ## At `implement`
 
-- `... is not assignable to type '"A protected action takes { authorize }: your rule, or Action.allowAll"'`, or `Protected actions require authorize, or Action.allowAll` thrown: an implementation holding a protected action states `authorize`. Pass `{ authorize }`, or `{ authorize: Action.allowAll }`.
-- `Missing authorize: pass an authorization function, or Action.allowAll` thrown, or a layer build dying with it: `authorize` is neither a function nor an Effect building one, or that Effect built something else.
 - `Type 'undefined' is not assignable to type 'Authorizer<...>'`: `authorize` is never `undefined`. Write `enabled ? authorize : Action.allowAll`.
 - `Parameter 'action' implicitly has an 'any' type`, or an `Effect.fn` authorizer whose `action` is `any`: an authorizer defined apart from `implement` annotates its parameter, `(action: Action.Any)`.
 - `Type 'X' is not assignable to type 'Forbidden | Unauthenticated'`, ending `Property '"~declared in the action's error, or built in"' is missing in type 'X'`: an authorizer fails only with `Action.Unauthenticated` or `Action.Forbidden`, and this one fails with `X`. A limit, or another failure callers should see, is the handler's: declare `X` in the action's `error` and fail with it there.
-- `Argument of type ... is not assignable to parameter of type ...`, or `Type 'Effect<...>' is not assignable to type 'Effect<...>'` at a handler of a record written in place, ending `Property '"~declared in the action's error, or built in"' is missing in type 'X'`, under `Type 'X' is not assignable to type 'Forbidden | InvalidInput | Unauthenticated'` or a longer union: a handler fails only with the errors its action declares and the library's built-in ones, and this one fails with `X`, which may be Effect's `HttpApiError.Forbidden` or a `Forbidden` of your own. Add `X` to the action's `error`, or handle it. A builder's error is reported at the builder and names one handler, in `The types returned by '<handler>(...)'`: the next shows once that one is fixed.
+- `Argument of type ... is not assignable to parameter of type ...`, or `Type 'Effect<...>' is not assignable to type 'Effect<...>'` at a handler of a record written in place, ending `Property '"~declared in the action's error, or built in"' is missing in type 'X'`: the handler fails with `X`, which its action does not declare. Add `X` to the action's `error`, or handle it.
+- `Type 'X' is not assignable to type 'Forbidden | InvalidInput | Unauthenticated'`, or a longer union, under a handler's error: a handler fails only with the errors its action declares and the library's built-in ones, and `X` may be Effect's `HttpApiError.Forbidden` or a `Forbidden` of your own. Add `X` to the action's `error`, or handle it.
+- `The types returned by '<handler>(...)'` at a builder: that handler fails with an error its action does not declare, and the error names one handler at a time; add the error to the action's `error` or handle it, and the next handler's shows.
 - `Binding element '<field>' implicitly has an 'any' type` (TS7031), or `Parameter 'input' implicitly has an 'any' type`, at every handler of a builder: the builder is wrapped, as in `Effect.gen(…).pipe(Effect.provide(layer))`, and its record is no longer typed from the contracts. Give `implement` the builder itself, and provide the layer to the surface's layer or to the server.
-- `Missing handlers: <names>` or `Unknown handlers: <keys>` thrown, also when a builder's layer builds: a record of handlers has one own function for each action of its `implement` call, and no other key. Add a missing handler to the record itself, not to a prototype; remove an unknown one, or add its action to the list.
 - `'<name>' implicitly has type 'any' because it does not have a type annotation and is referenced directly or indirectly in its own initializer` (TS7022), or, with the types bypassed, an acquisition that never completes: a builder acquires an `Action.client` of its own implementation, directly or through another builder. Call the services both use instead.
 
 ## Where an implementation is served
 
 - `Type 'CurrentUser' is not assignable to type 'never'`, or `Request<"Requires", CurrentUser>` still owed, for a layer serving only public actions: no surface provides a public action an identity, and a public action's handler reads one. Make the action protected.
-- `Type '{ readonly "A builder yields the caller, which a server has per request: yield it in a handler or an authorizer": { readonly caller: CurrentUser; readonly builderOf: "createNote" | ...; }; }' is not assignable to type 'never'` where a server is launched, or `is missing the following properties from type 'Scope'` at each `it.effect` that runs the routes, one error for each, all of one cause, the builder of the `implement` call whose actions `builderOf` names, or a service shared across requests that should be resolved per request: what a builder, or the Effect building an authorizer, yields is resolved once, at startup, and a server has the caller per request alone. Move the `yield*` into the handler or the authorizer.
+- `Type '{ readonly "A builder yields the caller, which a server has per request: yield it in a handler or an authorizer": { readonly caller: CurrentUser; readonly builderOf: "createNote" | ...; }; }' is not assignable to type 'never'` where a server is launched: the builder of the `implement` call whose actions `builderOf` names, or the Effect building its authorizer, yields the caller, which a builder would resolve once at startup. Move the `yield*` into the handler or the authorizer.
+- `is missing the following properties from type 'Scope'` at each `it.effect` that runs the routes: a builder, or the Effect building an authorizer, yields the caller or another per-request service, which a builder would resolve once at startup. Move the `yield*` into the handler or the authorizer.
 - `HttpRouter.Request<"Requires", X>` still owed, or `Type 'X' is not assignable to type 'never'` at `runMain`, although `X`, a store the authorizer reads, is provided at startup: what a plain authorizer yields is a request-time requirement, and this one yields `X` on every call. Make `authorize` an Effect that yields `X` once and returns the function ([Authorize calls](Action.md#authorize-calls)).
 - `unknown` among a surface's requirements, and a type error where it is served or run, such as `Argument of type 'Layer<never, unknown, unknown>' is not assignable` at `HttpRouter.toWebHandler` or `Type 'unknown' is not assignable to type 'never'`: the implementations are typed `Action.AnyImplementation`, as a helper's parameter or a list's annotation. Make the helper generic over them, `<const Apps extends Action.AnyImplementation | ReadonlyArray<Action.AnyImplementation>>(apps: Apps)`, or drop the annotation.
 - `Request<"Requires", unknown>` where an implementation is served, or `unknown` among the services a call or a run still requires: TypeScript inferred no requirements for one handler of a record, as a data-first call whose type takes a parameter from no argument causes, `Effect.catchTag(effect, tag, f)` for one. Write that handler's Effect `effect.pipe(Effect.catchTag(tag, f))`, or as a generator.
-- A builder runs twice, or a job, an agent or a second server reads other state than the routes, such as an empty in-memory store: inside one `HttpRouter.serve` or one `Testing.layer` a builder runs once, however many surfaces serve it, but each builds its routes in a layer graph of its own, which shares nothing it builds with a layer merged beside it. A job beside the server shares its build only when the job's side builds first, so it can pass in a test and build twice when the job starts later. Put the job or agent inside the layer the server serves, or provide `Action.layer(implementations)` and the services they share above both ([Share one build across servers](Action-in-process.md#share-one-build-across-servers)).
-- Two surfaces in one layer graph, each given startup services of its own, both answer with one surface's: a builder runs once per layer graph, with the services of its first build. Provide the services once; where the surfaces must differ, wrap each in `Layer.fresh`, providing what they share, authentication included, outside it, or give each an implementation of its own.
-- `Not an implementation made by this Action.implement: is effect-actions installed twice?` thrown by a surface, `client` or `layer`: another installed copy of the package made the implementation, or the value is a copy of one, such as a spread. Install one copy of the package, and pass the value `implement` returned.
 
 ## At `client` and its calls
 
-- `Listed in actions, but no implementation holds it: <names>` thrown by `Action.client`: an action listed in `actions` is none the given implementations hold. Pass the implementation holding it, or list the contract value it implemented.
-- `Duplicate action: <name>` thrown: a list given to `implement` or `byName` names one action twice, or two implementations given to `Action.client` implement an action of that name. Two contracts sharing a name are told apart by `actions`, listing one; two implementations of one contract are not: pass one.
 - `Type 'CurrentUser' is not assignable to type 'never'` where a program calling an `Action.client` runs, or `Type 'CurrentUser' is missing the following properties from type 'Scope'` at `it.effect`: a call to a protected action reads the caller from its own context, never from the one the client was acquired in. Provide the caller around the call.
 - `Type 'Scope' is not assignable to type 'never'` where a program runs, or `Service not found: effect/Scope` in plain JavaScript: acquiring an `Action.client` builds, as a layer does. Acquire it in a builder or a layer, or run the program in `Effect.scoped`.
-- A builder runs on every request, or a route owes `HttpRouter.Request<"Requires", X>` for `X`, a service its builder yields: acquiring an `Action.client` runs the builders, and a handler acquires one on every request. Acquire the client in the builder, and call it in the handler.
 - An `Action.client` call dies with a `SchemaError`: the handler's success, or what it fails with, does not pass through its codec. The cause holds the failure beside the `SchemaError`, as `Cause.pretty` shows: before it for a failure the action's errors reject, undeclared or breaking a check, after it for one they accept that does not encode. Return what the success schema accepts, and fail with an error the action declares.
-- `InvalidInput` with `Expected <Class>` from an `Action.client` call given a plain object: an input that is a class encodes only its instances. Pass `new Class({ ... })`.