@gjermundgaraba/effect-actions 0.13.0 → 0.15.0

package/dist/Testing.d.mts

@@ -1,15 +1,11 @@
-import { BuiltIn } from "./contract/errors.mjs";
-import { Call } from "./contract/call.mjs";
-import { Action_d_exports, Any } from "./Action.mjs";
-import { Params } from "./mcp/protocol.mjs";
 import { Served } from "./testing/memory.mjs";
-import { Cause, Effect, Layer, Schema } from "effect";
-import { Headers, HttpClient, HttpClientError, HttpClientRequest, HttpRouter } from "effect/http";
+import { Layer } from "effect";
+import { HttpClient, HttpRouter } from "effect/http";
 //#region src/testing/Testing.d.ts
 /**
  * For a web handler the test already owns; most tests want `layer(routes)`, below, with
- * `ActionHttp.client` and `mcpClient`. The native `HttpClient`, answered by `handler` instead of
- * the network: a web handler the test serves, which other tests may share, such as
+ * `ActionHttp.client` and `ActionMcp.client`. The native `HttpClient`, answered by `handler`
+ * instead of the network: a web handler the test serves, which other tests may share, such as
  * `HttpRouter.toWebHandler(routes.pipe(Layer.provide(HttpServer.layerServices))).handler`,
  * the routes' platform services provided, as `layer(routes)` provides them itself. It is the
  * client `layer(routes)` gives, without building anything: the test owns the handler, and
@@ -18,7 +14,7 @@ import { Headers, HttpClient, HttpClientError, HttpClientRequest, HttpRouter } f
 export declare function layer(handler: (request: Request) => Promise<Response>): Layer.Layer<HttpClient.HttpClient>;
 /**
  * The native `HttpClient`, answered in memory by `routes` instead of the network: provide
- * it to `ActionHttp.client` and to `mcpClient`. The routes are built with this layer and
+ * it to `ActionHttp.client` and to `ActionMcp.client`. The routes are built with this layer and
  * released with its scope, without request logs: only the cause of a defect, of a result that
  * does not encode or of a failure a route of your own leaves unhandled is logged, as an error,
  * where a server's request logger would show it, on the process console even under `it.effect`
@@ -36,67 +32,4 @@ export declare function layer(handler: (request: Request) => Promise<Response>):
  * A type error at `it.effect`, such as one naming `Scope`: `docs/Testing-failures.md`.
  */
 export declare function layer<A, E, R>(routes: Layer.Layer<A, E, R>): Layer.Layer<HttpClient.HttpClient, E, Exclude<HttpRouter.Request.Without<R> | HttpRouter.Request.Only<"Requires", R> | HttpRouter.Request.Only<"GlobalRequires", R>, Served>>;
-/** Where `mcpClient` sends, and through what client. */
-export interface McpClientOptions {
-  /**
-   * The endpoint, resolved by the `HttpClient`: relative under `layer`. Defaults to `/mcp`,
-   * the default `ActionMcp.layerHttp` path.
-   */
-  readonly url?: string;
-  /**
-   * Wraps the native `HttpClient`, as `ActionHttp.client` takes it: a bearer token is
-   * `HttpClient.mapRequest(HttpClientRequest.bearerToken(token))`.
-   */
-  readonly transformClient?: (client: HttpClient.HttpClient) => HttpClient.HttpClient;
-}
-/** Where an `mcpRequest` goes, and with what headers. */
-export interface McpRequestOptions {
-  /**
-   * The endpoint, resolved by the `HttpClient` that sends the request: relative under `layer`.
-   * Defaults to `/mcp`, as `mcpClient`'s does; converting to a web `Request` needs an absolute
-   * one.
-   */
-  readonly url?: string;
-  readonly headers?: Headers.Input;
-}
-declare const McpCallError_base: Schema.Class<McpCallError, Schema.TaggedStruct<"McpCallError", {
-  readonly message: Schema.String;
-}>, Cause.YieldableError>;
-/**
- * An answer a client method cannot read as the action's success or a declared error, such as
- * the native server's message for invalid arguments or an unknown tool, or a result without
- * its structured content. Its message holds the answer. Structured content that does not
- * decode as the success is a `SchemaError` instead, and a request that fails an
- * `HttpClientError`.
- */
-export declare class McpCallError extends McpCallError_base {}
-type CallError<A extends Any> = A["error"][number]["Type"] | BuiltIn | Schema.SchemaError | HttpClientError.HttpClientError | McpCallError;
-/** Every action of `Actions` as `client.<action>(input)`, calling its tool. */
-export type McpClient<Actions extends ReadonlyArray<Any>> = { readonly [A in Actions[number] as A["name"]]: Call<A, Effect.Effect<A["success"]["Type"], CallError<A>>>; };
-/**
- * A client of an MCP endpoint served by `ActionMcp.layerHttp`, one method per action calling
- * its tool with one stateless request, as `ActionHttp.client` calls routes: the input is
- * 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: a test telling a 401 or 403 from a tool result asserts the status of a request
- * `mcpRequest` builds. The argument may be omitted when `{}` is a valid input. Requires the
- * native `HttpClient`, such as the one `layer` provides.
- */
-export declare function mcpClient<const Actions extends ReadonlyArray<Any>>(actions: Actions, options?: McpClientOptions): Effect.Effect<McpClient<Actions>, never, HttpClient.HttpClient>;
-/**
- * One stateless MCP request of `method` with `params`, as `ActionMcp.layerHttp` serves it,
- * as the native request value: the JSON-RPC envelope, the 2026-07-28 headers (`Accept`,
- * `MCP-Protocol-Version`, `MCP-Method`), `mcp-name` from
- * `params.uri` for `resources/read` and `params.name` otherwise, and the client metadata in
- * `_meta` are filled in, under any `_meta` given, such as a `progressToken`; the protocol
- * version is always the request's own. The test sends it: `HttpClient.execute` answers the
- * response as the endpoint sent it, whatever its status, and `HttpClientRequest.toWebResult`
- * gives the web `Request` a web handler or `fetch` takes, once `url` is absolute. It is for a test
- * asserting on what `mcpClient` decodes away, such as `tools/list`, a refusal's challenge, or
- * a call its types would not send.
- */
-export declare const mcpRequest: (method: string, params?: Params, { headers, url }?: McpRequestOptions) => HttpClientRequest.HttpClientRequest;
-//#endregion
-export type { Params as McpParams };
+//#endregion

package/dist/Testing.mjs

@@ -1,12 +1,6 @@
-import { Refusal } from "./contract/errors.mjs";
-import { assertOnce, projectedErrors } from "./contract/rules.mjs";
-import { checked } from "./contract/call.mjs";
-import { defaultPath, liftOf, statelessRequest } from "./mcp/protocol.mjs";
 import { clientOf } from "./testing/memory.mjs";
-import { Cause, Console, Context, Effect, ErrorReporter, FileSystem, Layer, Option, Path, Predicate, Schema, identity } from "effect";
-import { McpSchema } from "effect/ai";
-import { Etag, HttpClient, HttpClientRequest, HttpEffect, HttpPlatform, HttpRouter } from "effect/http";
-import { Base64, Sse } from "effect/encoding";
+import { Cause, Console, Context, Effect, ErrorReporter, FileSystem, Layer, Option, Path } from "effect";
+import { Etag, HttpEffect, HttpPlatform, HttpRouter } from "effect/http";
 //#region src/testing/Testing.ts
 function layer(routes) {
 	if (!Layer.isLayer(routes)) return clientOf(routes);
@@ -19,98 +13,5 @@ function layer(routes) {
 	}));
 }
 const isReported = (cause) => cause.reasons.some((reason) => Cause.isFailReason(reason) && !ErrorReporter.isIgnored(reason.error) || Cause.isDieReason(reason) && !ErrorReporter.isIgnored(reason.defect));
-/**
-* An answer a client method cannot read as the action's success or a declared error, such as
-* the native server's message for invalid arguments or an unknown tool, or a result without
-* its structured content. Its message holds the answer. Structured content that does not
-* decode as the success is a `SchemaError` instead, and a request that fails an
-* `HttpClientError`.
-*/
-var McpCallError = class extends Schema.TaggedError()("McpCallError", { message: Schema.String }) {};
-const textOf = (block) => block?.type === "text" ? block.text : void 0;
-const ToolCallReply = Schema.Union([Schema.Struct({ result: McpSchema.CallToolResult }), Schema.Struct({ error: Schema.Struct({
-	code: Schema.Finite,
-	message: Schema.String
-}) })]);
-const decodeReply = Schema.decodeUnknownOption(Schema.fromJsonString(ToolCallReply));
-const replyOf = (response, text) => {
-	if (!(response.headers["content-type"] ?? "").startsWith("text/event-stream")) return decodeReply(text);
-	const data = [];
-	Sse.makeParser((event) => {
-		if (Predicate.isTagged(event, "Event")) data.push(event.data);
-	}).feed(text);
-	return Option.fromNullishOr(data.flatMap((message) => Option.toArray(decodeReply(message))).at(-1));
-};
-const mediaFromBlocks = ({ name, kind, many }, result) => {
-	const values = result.content.flatMap((block) => block.type === kind && block._meta?.["effect-actions/field"] === name ? [{
-		data: Base64.encode(block.data),
-		mimeType: block.mimeType
-	}] : []);
-	return many || values.length > 1 ? values : values[0];
-};
-const encodedSuccessOf = (lift, result) => {
-	const [whole] = lift.fields;
-	if (whole !== void 0 && whole.name === void 0) return mediaFromBlocks(whole, result);
-	const { structuredContent = {} } = result;
-	if (!Predicate.isObject(structuredContent)) return structuredContent;
-	const lifted = new Set(lift.fields.map(({ name }) => name));
-	return Object.fromEntries([...Object.entries(structuredContent).filter(([key]) => !lifted.has(key)), ...lift.fields.flatMap((field) => {
-		const value = mediaFromBlocks(field, result);
-		return field.name === void 0 || value === void 0 ? [] : [[field.name, value]];
-	})]);
-};
-const failWith = (errors, text, otherwise) => Schema.decodeUnknownEffect(Schema.fromJsonString(Schema.toCodecJson(Schema.Union(errors))))(text).pipe(Effect.mapError(() => otherwise), Effect.flatMap(Effect.fail));
-const callTool = (client, url, action, lift, input) => {
-	const { name } = action;
-	const other = (answer) => new McpCallError({ message: `MCP tools/call "${name}" ${answer}` });
-	return Effect.gen(function* () {
-		const encoded = yield* Schema.encodeEffect(Schema.toCodecJson(action.input))(input);
-		const response = yield* client.execute(mcpRequest("tools/call", {
-			name,
-			arguments: encoded
-		}, { url }));
-		const text = yield* response.text;
-		if (response.status !== 200) return yield* failWith(Refusal.members, text, other(`answered ${response.status}: ${text}`));
-		const reply = replyOf(response, text);
-		if (Option.isNone(reply)) return yield* Effect.fail(other(`had no reply: ${text}`));
-		if ("error" in reply.value) {
-			const { code, message } = reply.value.error;
-			return yield* Effect.fail(other(`failed with ${code}: ${message}`));
-		}
-		const { result } = reply.value;
-		if (result.isError === true) {
-			const error = textOf(result.content.find((block) => block.type === "text")) ?? "";
-			return yield* failWith(projectedErrors(action), error, other(`returned an error: ${error}`));
-		}
-		if (result.structuredContent === void 0 && lift.rest !== void 0) return yield* Effect.fail(other(`returned no structured content: ${text}`));
-		return yield* Schema.decodeUnknownEffect(Schema.toCodecJson(action.success))(encodedSuccessOf(lift, result));
-	});
-};
-function mcpClient(actions, { url = defaultPath, transformClient = identity } = {}) {
-	assertOnce("action", actions);
-	return Effect.map(HttpClient.HttpClient, (native) => {
-		const client = transformClient(native);
-		return Object.fromEntries(actions.map((action) => {
-			const lift = liftOf(action.success);
-			return [action.name, checked(action, (input) => callTool(client, url, action, lift, input))];
-		}));
-	});
-}
-/**
-* One stateless MCP request of `method` with `params`, as `ActionMcp.layerHttp` serves it,
-* as the native request value: the JSON-RPC envelope, the 2026-07-28 headers (`Accept`,
-* `MCP-Protocol-Version`, `MCP-Method`), `mcp-name` from
-* `params.uri` for `resources/read` and `params.name` otherwise, and the client metadata in
-* `_meta` are filled in, under any `_meta` given, such as a `progressToken`; the protocol
-* version is always the request's own. The test sends it: `HttpClient.execute` answers the
-* response as the endpoint sent it, whatever its status, and `HttpClientRequest.toWebResult`
-* gives the web `Request` a web handler or `fetch` takes, once `url` is absolute. It is for a test
-* asserting on what `mcpClient` decodes away, such as `tools/list`, a refusal's challenge, or
-* a call its types would not send.
-*/
-const mcpRequest = (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, layer, mcpClient, mcpRequest };
+export { layer };

package/dist/authentication/provider.mjs

@@ -1,12 +1,7 @@
 import { Unauthenticated } from "../contract/errors.mjs";
-import { Anyone } from "../contract/rules.mjs";
 import { Effect, Option } from "effect";
 //#region src/authentication/provider.ts
-const withVerifierErrors = (action, errors, verifierErrors) => action.caller === Anyone || verifierErrors === void 0 ? errors : [...errors, ...verifierErrors];
-const assertAuthentication = (actions, auth) => {
-	for (const action of actions) if (action.caller !== Anyone && (auth === void 0 || action.caller.key !== auth.identity.key)) throw new Error(`Protected action '${action.name}' requires its matching authentication descriptor`);
-};
 const providerOf = (auth) => Effect.flatMap(Effect.service(auth["~provider"]), (provider) => provider.descriptor === auth ? Effect.succeed(provider) : Effect.die(/* @__PURE__ */ new Error(`Authentication "${auth.name}": the binding's descriptor is not its provider's; build both from one descriptor`)));
 const promote = (auth, run) => Effect.flatMap(Effect.serviceOption(auth["~verified"]), (actor) => Option.isSome(actor) ? Effect.provideService(run, auth.identity, actor.value) : Effect.fail(new Unauthenticated()));
 //#endregion
-export { assertAuthentication, promote, providerOf, withVerifierErrors };
+export { promote, providerOf };

package/dist/authentication/refusal.mjs

@@ -1,14 +1,20 @@
-import { Refusal, statuses } from "../contract/errors.mjs";
+import { Forbidden, Refusal, Unauthenticated } from "../contract/errors.mjs";
+import { declared, httpApiStatusOf } from "../contract/rules.mjs";
 import { Cause, Context, Effect, Exit, Option, Predicate, Ref, Schema } from "effect";
 import { HttpServerResponse } from "effect/http";
 //#region src/authentication/refusal.ts
+const responseOf = (schema, error) => HttpServerResponse.jsonUnsafe(Schema.encodeUnknownSync(Schema.toCodecJson(schema))(error), { status: httpApiStatusOf(schema.ast) ?? 422 });
+/** `error` answered as an endpoint declaring `errors` answers it, if one of them declares it. */
+const declaredResponse = (errors, error) => {
+	const schema = errors.flatMap(declared).find((each) => Schema.is(each)(error));
+	return schema === void 0 ? void 0 : responseOf(schema, error);
+};
 const rfc6750ErrorDescriptionCharacters = /^[\x20\x21\x23-\x5B\x5D-\x7E]+$/;
 const challenge = (scheme, parameters) => {
 	const given = parameters.flatMap(([name, value]) => value === void 0 ? [] : [`${name}="${value.replace(/["\\]/g, "\\$&")}"`]);
 	return given.length === 0 ? scheme : `${scheme} ${given.join(", ")}`;
 };
 const bearer = (parameters) => challenge("Bearer", parameters);
-const encode = Schema.encodeSync(Refusal);
 const isRefusal = Schema.is(Refusal);
 const insufficientScopeChallenge = (error, metadataUrl) => Predicate.isTagged(error, "Forbidden") && error.scopes !== void 0 ? bearer([
 	["error", "insufficient_scope"],
@@ -16,7 +22,11 @@ const insufficientScopeChallenge = (error, metadataUrl) => Predicate.isTagged(er
 	["resource_metadata", metadataUrl],
 	["error_description", rfc6750ErrorDescriptionCharacters.test(error.message) ? error.message : void 0]
 ]) : void 0;
-const plain = (error) => HttpServerResponse.jsonUnsafe(encode(error), { status: statuses[error._tag] });
+const refusalSchemas = {
+	Unauthenticated,
+	Forbidden
+};
+const plain = (error) => responseOf(refusalSchemas[error._tag], error);
 const answer = (error, metadataUrl) => {
 	const response = plain(error);
 	const scoped = insufficientScopeChallenge(error, metadataUrl);
@@ -33,4 +43,4 @@ const answerStepUp = (route, metadataUrl) => Effect.gen(function* () {
 	return Option.isSome(refused) && !diedOrInterruptedAfterRefusal ? answer(refused.value, metadataUrl) : yield* exit;
 });
 //#endregion
-export { answer, answerStepUp, bearer, challenge, isRefusal, isStepUp, plain, recordStepUp };
+export { answer, answerStepUp, bearer, challenge, declaredResponse, isRefusal, isStepUp, plain, recordStepUp };

package/dist/cli/commands.mjs

@@ -1,7 +1,8 @@
 import { InvalidInput } from "../contract/errors.mjs";
-import { assertDistinct, literalValues, members, projectedErrors, unsuspended } from "../contract/rules.mjs";
+import { assertDistinct, literalValues, members, unsuspended } from "../contract/rules.mjs";
+import { decodeInput } from "../contract/call.mjs";
 import { withStderrConsole } from "../stdio/console.mjs";
-import { Console, Effect, Option, Predicate, Record, Runtime, Schema, SchemaAST, Stdio, Stream, flow } from "effect";
+import { Console, Effect, Option, Predicate, Record, Runtime, Schema, SchemaAST, Stdio, Stream } from "effect";
 import { CliError, Command, Flag, Param } from "effect/cli";
 //#region src/cli/commands.ts
 const kebab = (name) => {
@@ -204,8 +205,8 @@ const userErrorOf = (errors) => {
 		userMessage
 	}))));
 };
-const failingAsDerived = (actions, surfaceErrorsOf) => {
-	const failure = userErrorOf([...new Set(actions.flatMap((action) => projectedErrors(action, surfaceErrorsOf(action))))]);
+const failingAsDerived = (actions, errorsOf) => {
+	const failure = userErrorOf([...new Set(actions.flatMap(errorsOf))]);
 	return (self) => Effect.catchIf(self, (error) => !CliError.isCliError(error), failure);
 };
 const unreadableStdinField = (field, message) => new InvalidInput({
@@ -228,8 +229,7 @@ const stdinTextOf = (field) => Effect.gen(function* () {
 const inputConfig = (action, positional, aliases, stdin) => {
 	const codec = Schema.toCodecJson(action.input);
 	const encoded = unsuspended(SchemaAST.toEncoded(codec.ast));
-	const decodeRefusingUndeclared = Schema.decodeUnknownEffect(codec, { onExcessProperty: "error" });
-	const decode = flow(decodeRefusingUndeclared, Effect.mapError(InvalidInput.fromSchemaError));
+	const decode = decodeInput(action);
 	if (SchemaAST.isObjects(encoded) && encoded.indexSignatures.every((signature) => SchemaAST.isNever(signature.type))) {
 		const params = fieldParams(encoded, unsuspended(action.input.ast), positional, aliases);
 		const fromStdin = Option.map(Option.fromUndefinedOr(stdin), (field) => {
@@ -269,11 +269,11 @@ const inputConfig = (action, positional, aliases, stdin) => {
 		stdinHelp: void 0
 	};
 };
-const command = (action, execute, options, errors = []) => {
+const command = (action, execute, options, errors) => {
 	const name = options?.name ?? kebab(action.name);
 	const render = options?.render;
 	const { flags, positional, decode, stdinHelp } = inputConfig(action, options?.positional ?? [], options?.aliases ?? {}, options?.stdin);
-	const failure = userErrorOf(projectedErrors(action, errors));
+	const failure = userErrorOf(errors);
 	assertDistinct("flag", [
 		...Object.keys(flags).map((field) => [`--${kebab(field)}`, `field ${field}`]),
 		...render === void 0 ? [] : [["--json", "render's --json"]],

package/dist/contract/call.d.mts

@@ -1,3 +1,4 @@
+import "./errors.mjs";
 import "./implementation.mjs";
 import { Action_d_exports, Any } from "../Action.mjs";
 import { Effect, Schema } from "effect";
@@ -6,7 +7,7 @@ import { Effect, Schema } from "effect";
  * A call of `A` answering `R`. It may leave its input out when `{}` is a valid encoded input,
  * such as for an action declared without `input` or one whose every field has a decoding
  * default, and then sends the input `{}` decodes to. Every client shares this rule:
- * `ActionHttp.client`, `ActionRpc.client`, `Testing.mcpClient` and `Action.client`.
+ * `ActionHttp.client`, `ActionRpc.client`, `ActionMcp.client` and `Action.client`.
  */
 export type Call<A extends Any, R> = {} extends A["input"]["Encoded"] ? (...input: [] | [input: A["input"]["Type"]]) => R : (input: A["input"]["Type"]) => R;
 //#endregion

package/dist/contract/call.mjs

@@ -1,10 +1,23 @@
 import { InvalidInput } from "./errors.mjs";
 import { Effect, Schema } from "effect";
 //#region src/contract/call.ts
+/**
+* How HTTP, RPC, MCP and a command decode a request's input: reporting every issue, and refusing a
+* field the input does not declare.
+*/
+const inputParseOptions = {
+	errors: "all",
+	onExcessProperty: "error"
+};
+/** Decode `action`'s input from its JSON form by `inputParseOptions`, or fail with `InvalidInput`. */
+const decodeInput = (action) => {
+	const decode = Schema.decodeUnknownEffect(Schema.toCodecJson(action.input), inputParseOptions);
+	return (encoded) => Effect.mapError(decode(encoded), InvalidInput.fromSchemaError);
+};
 const inputOf = (action, args) => args.length === 0 ? Schema.decodeUnknownEffect(Schema.toCodecJson(action.input))({}) : Effect.succeed(args[0]);
 const checked = (action, send) => {
 	const encode = Schema.encodeUnknownEffect(Schema.toCodecJson(action.input), { errors: "all" });
 	return (...args) => inputOf(action, args).pipe(Effect.tap(encode), Effect.mapError(InvalidInput.fromSchemaError), Effect.flatMap(send));
 };
 //#endregion
-export { checked, inputOf };
+export { checked, decodeInput, inputOf, inputParseOptions };

package/dist/contract/errors.d.mts

@@ -50,9 +50,8 @@ declare const Forbidden_base: Schema.Class<Forbidden, Schema.TaggedStruct<"Forbi
  * The caller may not run this action: an implementation's `authorize` refuses. `scopes`,
  * when given, are every OAuth scope the call needs: a refusal naming them is answered with
  * the `insufficient_scope` challenge an OAuth client re-authorizes on, so name them only where
- * re-authorizing can grant them. Over HTTP it is a 403 either way. Over MCP, from an authorizer
- * or a handler, it is a 403 only when it names scopes on an endpoint under Bearer, and
- * otherwise a tool result with `isError: true`, in a 200 response.
+ * re-authorizing can grant them. What it answers on each surface: `docs/guarantees.md` in this
+ * package.
  */
 export declare class Forbidden extends Forbidden_base {
   private readonly "~declared in the action's error, or built in";

package/dist/contract/errors.mjs

@@ -1,11 +1,6 @@
 import { Effect, Predicate, Schema, SchemaIssue } from "effect";
 //#region src/contract/errors.ts
 const defaultedMessage = (fallback) => Schema.String.pipe(Schema.withConstructorDefault(Effect.succeed(fallback)));
-const statuses = {
-	InvalidInput: 400,
-	Unauthenticated: 401,
-	Forbidden: 403
-};
 const Issue = Schema.Struct({
 	path: Schema.Array(Schema.Union([Schema.String, Schema.Finite])),
 	message: Schema.String
@@ -20,7 +15,7 @@ const standardIssues = SchemaIssue.makeFormatterStandardSchemaV1();
 var InvalidInput = class InvalidInput extends Schema.TaggedError()("InvalidInput", {
 	message: defaultedMessage("The input does not match the action's input."),
 	issues: Schema.Array(Issue).pipe(Schema.withConstructorDefault(Effect.succeed([])))
-}, { httpApiStatus: statuses.InvalidInput }) {
+}, { httpApiStatus: 400 }) {
 	/**
 	* The `InvalidInput` for input that did not decode, as every surface answers it: the
 	* schema's message, and each of its issues by path, for code that decodes input of its own,
@@ -41,21 +36,20 @@ var InvalidInput = class InvalidInput extends Schema.TaggedError()("InvalidInput
 	});
 };
 /** The caller is not authenticated: authentication or an implementation's `authorize` refuses. */
-var Unauthenticated = class extends Schema.TaggedError()("Unauthenticated", { message: defaultedMessage("Authentication is required.") }, { httpApiStatus: statuses.Unauthenticated }) {};
+var Unauthenticated = class extends Schema.TaggedError()("Unauthenticated", { message: defaultedMessage("Authentication is required.") }, { httpApiStatus: 401 }) {};
 const scopeToken = /^[\x21\x23-\x5B\x5D-\x7E]+$/;
 const ScopeToken = Schema.String.check(Schema.isPattern(scopeToken));
 /**
 * The caller may not run this action: an implementation's `authorize` refuses. `scopes`,
 * when given, are every OAuth scope the call needs: a refusal naming them is answered with
 * the `insufficient_scope` challenge an OAuth client re-authorizes on, so name them only where
-* re-authorizing can grant them. Over HTTP it is a 403 either way. Over MCP, from an authorizer
-* or a handler, it is a 403 only when it names scopes on an endpoint under Bearer, and
-* otherwise a tool result with `isError: true`, in a 200 response.
+* re-authorizing can grant them. What it answers on each surface: `docs/guarantees.md` in this
+* package.
 */
 var Forbidden = class extends Schema.TaggedError()("Forbidden", {
 	message: defaultedMessage("Not allowed."),
 	scopes: Schema.optionalKey(Schema.NonEmptyArray(ScopeToken))
-}, { httpApiStatus: statuses.Forbidden }) {};
+}, { httpApiStatus: 403 }) {};
 const refusals = [Unauthenticated, Forbidden];
 /**
 * What authentication or an implementation's `authorize` refuses a caller with, instead of
@@ -71,4 +65,4 @@ const builtIns = [InvalidInput, ...refusals];
 /** The built-in failures as one schema: `Schema.is(Action.BuiltIn)(error)`. */
 const BuiltIn = Schema.Union(builtIns);
 //#endregion
-export { BuiltIn, Forbidden, InvalidInput, Refusal, Unauthenticated, builtIns, scopeToken, statuses };
+export { BuiltIn, Forbidden, InvalidInput, Refusal, Unauthenticated, builtIns, scopeToken };

package/dist/contract/implementation.mjs

@@ -1,6 +1,6 @@
 import { Unauthenticated } from "./errors.mjs";
-import { Anyone, assertOnce } from "./rules.mjs";
-import { Array, Context, Effect, Layer, Option } from "effect";
+import { Anyone, assertAuthentication, assertDistinct, assertOnce, projectedErrors } from "./rules.mjs";
+import { Array, Cause, Context, Effect, Exit, Layer, Option, Schema } from "effect";
 //#region src/contract/implementation.ts
 const uniqueKey = () => Math.random().toString(36).slice(2);
 const memoized = (build) => {
@@ -62,7 +62,7 @@ var Implementation = class Implementation {
 		return Effect.gen(function* () {
 			const bound = yield* source.#handlers.key;
 			const before = actions.some((action) => action.caller !== Anyone) ? yield* source.#authorizer.key : () => Effect.void;
-			return bound.filter(([action]) => actions.includes(action)).map(([action, handle]) => [action, dispatch(action, handle, before)]);
+			return actions.flatMap((action) => bound.flatMap(([held, handle]) => held === action ? [[action, dispatch(action, handle, before)]] : []));
 		});
 	}
 	/** `app`, if this copy of the module made it; another installed copy's cannot be read. */
@@ -100,6 +100,21 @@ const servedBy = (what, bound, apps, listed) => {
 	assertOnce("served action", actions);
 	return served;
 };
+/**
+* What `ActionHttp.layer` and `ActionRpc.layer` serve, with the checks they share;
+* `authentication` is the binding's where a served action is protected.
+*/
+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);
+	return {
+		apps,
+		actions,
+		authentication: actions.some((action) => action.caller !== Anyone) ? binding.authentication : void 0
+	};
+};
 const provideHandlers = (apps) => (layer) => {
 	const [first, ...rest] = apps.map((app) => Implementation.layerOf(app));
 	return first === void 0 ? layer : Layer.provide(layer, Layer.mergeAll(first, ...rest));
@@ -124,13 +139,26 @@ const dispatch = (action, handle, before) => {
 	};
 	const authentication = action.caller === Anyone ? Effect.void : Effect.flatMap(Effect.serviceOption(action.caller), (actor) => Option.isSome(actor) ? Effect.void : Effect.fail(new Unauthenticated()));
 	const authorization = action.caller === Anyone ? Effect.void : Effect.suspend(() => before(action));
+	const validate = Schema.decodeUnknownEffect(Schema.toType(Schema.Union(projectedErrors(action))));
+	const asDefects = (reason, rejected) => {
+		const trace = Context.makeUnsafe(reason.annotations);
+		return [Cause.makeDieReason(reason.error).annotate(trace), Cause.makeDieReason(Cause.squash(rejected)).annotate(trace)];
+	};
+	const declaredOrDefect = Effect.fnUntraced(function* (cause) {
+		const reasons = [];
+		for (const reason of cause.reasons) if (Cause.isFailReason(reason)) {
+			const validated = yield* Effect.exit(validate(reason.error));
+			reasons.push(...Exit.isSuccess(validated) ? [reason] : asDefects(reason, validated.cause));
+		} else reasons.push(reason);
+		return yield* Effect.failCause(Cause.fromReasons(reasons));
+	});
 	return (input) => {
 		const handled = Effect.withSpan(Effect.annotateLogs(Effect.suspend(() => handle(input)), actionAttributes), action.name, {
 			captureStackTrace: false,
 			attributes: actionAttributes
 		});
-		return Effect.scoped(authentication.pipe(Effect.andThen(authorization), Effect.andThen(handled)));
+		return Effect.scoped(authentication.pipe(Effect.andThen(authorization), Effect.andThen(handled), Effect.catchCause(declaredOrDefect)));
 	};
 };
 //#endregion
-export { Implementation, acquire, assertHeld, builders, built, memoized, provideHandlers, select, servedBy, toList };
+export { Implementation, acquire, assertHeld, builders, built, memoized, provideHandlers, select, servingOf, toList };

package/dist/contract/rules.d.mts

@@ -16,6 +16,13 @@ type Single<T> = true extends Types.IsUnion<T> ? never : T;
  * `E` may be one of several.
  */
 export type Certain<E extends Errors> = true extends Types.IsUnion<E> ? never : number extends E["length"] ? never : { readonly [K in keyof E]: Single<E[K]>; }[number];
+/** The errors a binding declares for every call, and its protected actions' authentication's. */
+export interface Declaring {
+  readonly error: Errors;
+  readonly authentication?: {
+    readonly error: Errors;
+  } | undefined;
+}
 /**
  * The caller of a public action, `caller: Action.Anyone`: anyone, signed in or not, and no
  * authorizer runs for it. Registered globally, so two copies of the package agree on it, as they

package/dist/contract/rules.mjs

@@ -1,4 +1,4 @@
-import { builtIns, statuses } from "./errors.mjs";
+import { builtIns } from "./errors.mjs";
 import { Predicate, Schema, SchemaAST } from "effect";
 //#region src/contract/rules.ts
 const errorList = (error) => error === void 0 ? [] : Schema.isSchema(error) ? [error] : error;
@@ -8,6 +8,14 @@ const projectedErrors = (action, surface = []) => [.../* @__PURE__ */ new Set([
 	...surface
 ])];
 /**
+* Every error a binding's call of `action` declares: the built-in ones, the action's, the
+* binding's and, where `action` is protected, its authentication's.
+*/
+const bindingErrors = (action, binding) => projectedErrors(action, action.caller === Anyone || binding.authentication === void 0 ? binding.error : [...binding.error, ...binding.authentication.error]);
+const assertAuthentication = (actions, authentication) => {
+	for (const action of actions) if (action.caller !== Anyone && (authentication === void 0 || action.caller.key !== authentication.identity.key)) throw new Error(`Protected action '${action.name}' requires its matching authentication descriptor`);
+};
+/**
 * The caller of a public action, `caller: Action.Anyone`: anyone, signed in or not, and no
 * authorizer runs for it. Registered globally, so two copies of the package agree on it, as they
 * agree on a name.
@@ -45,9 +53,48 @@ const encodedTags = (ast) => members(SchemaAST.toEncoded(ast)).flatMap((member)
 	const tag = SchemaAST.isObjects(member) ? member.propertySignatures.find((property) => property.name === "_tag")?.type : void 0;
 	return tag === void 0 ? [] : members(tag).flatMap(literalValues).filter(Predicate.isString);
 });
+const builtInTags = new Set(builtIns.flatMap((error) => encodedTags(error.ast)));
 const assertOwnTags = (what, errors) => {
-	const tag = errors.flatMap((error) => encodedTags(error.ast)).find((tag) => Object.hasOwn(statuses, tag));
+	const tag = errors.flatMap((error) => encodedTags(error.ast)).find((tag) => builtInTags.has(tag));
 	if (tag !== void 0) throw new Error(`${what}: error _tag "${tag}" is built in, and declared on every surface`);
 };
+/**
+* The checks `ActionHttp.make` and `ActionRpc.make` share: each action once, no built-in error in
+* `error`, and the descriptor every protected action names. Returns `error` as a list.
+*/
+const bindingOf = (what, actions, options) => {
+	assertOnce("action", actions);
+	const error = errorList(options.error);
+	assertOwnTags(what, error);
+	assertAuthentication(actions, options.authentication);
+	return {
+		error,
+		authentication: options.authentication
+	};
+};
+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.
+*/
+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 })];
+};
+/**
+* An action's MCP tool hints, MCP's defaults where its `mcp` leaves one out: a write destructive,
+* a read not, no tool idempotent and every tool open-world. A given value passes through, as MCP
+* calls `destructiveHint` and `idempotentHint` meaningless on a read-only tool.
+*/
+const hintsOf = ({ readOnly, mcp }) => ({
+	readOnlyHint: readOnly,
+	destructiveHint: mcp.destructiveHint ?? !readOnly,
+	idempotentHint: mcp.idempotentHint ?? false,
+	openWorldHint: mcp.openWorldHint ?? true
+});
 //#endregion
-export { Anyone, assertDistinct, assertKnown, assertName, assertOnce, assertOwnTags, errorList, literalValues, members, projectedErrors, unsuspended };
+export { Anyone, assertAuthentication, assertDistinct, assertKnown, assertName, assertOnce, assertOwnTags, bindingErrors, bindingOf, declared, errorList, hintsOf, httpApiStatusOf, literalValues, members, projectedErrors, unsuspended };

package/dist/http/client.mjs

@@ -2,16 +2,13 @@ import { checked } from "../contract/call.mjs";
 import { Effect } from "effect";
 import { HttpApiClient } from "effect/http-api";
 //#region src/http/client.ts
-const assertInBinding = (actions, action) => {
-	if (!actions.includes(action)) throw new Error(`Action "${action.name}" is not in this HTTP binding`);
-};
 const methods = (http, options = {}) => Effect.map(HttpApiClient.make(http.api, options), (client) => {
 	const native = client;
-	return (action) => {
+	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}`);
-		return checked(action, (payload) => method({ payload }));
-	};
+		return [action.name, checked(action, (payload) => method({ payload }))];
+	}));
 });
 //#endregion
-export { assertInBinding, methods };
+export { methods };