@gjermundgaraba/effect-actions 0.18.2 → 0.19.0

package/dist/cli/commands.mjs

@@ -1,6 +1,7 @@
 import { literalValues, members, unsuspended } from "../contract/ast.mjs";
 import { InvalidInput } from "../contract/errors.mjs";
 import { assertDistinct } from "../contract/names.mjs";
+import { errorSchemas } from "../contract/declared.mjs";
 import { decodeInput } from "../contract/call.mjs";
 import { withStderrConsole } from "../stdio/console.mjs";
 import { Console, Effect, Option, Predicate, Record, Runtime, Schema, SchemaAST, Stdio, Stream } from "effect";
@@ -152,28 +153,30 @@ const fieldParams = (encoded, input, positional, aliases) => {
 	});
 };
 const positionalOrder = (params, positional) => {
-	assertDistinct("positional argument", positional, (field) => field);
+	assertDistinct("positional argument", positional, (field) => field, { fix: "list each field once" });
 	const ordered = positional.map((field) => {
 		const found = params.find((param) => param.field === field);
-		if (found === void 0) throw new Error(`Not an input field: ${field}`);
+		if (found === void 0) throw new Error(`Not an input field: ${field} (positional names fields of the action's input)`);
 		return found;
 	});
 	const firstOptional = ordered.findIndex((param) => param.optional);
 	const misplaced = ordered.slice(firstOptional === -1 ? ordered.length : firstOptional).find((param) => !param.optional);
-	if (misplaced !== void 0) throw new Error(`Required positional argument after an optional one: ${misplaced.field}`);
+	if (misplaced !== void 0) throw new Error(`Required positional argument after an optional one: ${misplaced.field} (list every required field first)`);
 	const repeatedBeforeLast = ordered.slice(0, -1).find((param) => param.repeats);
-	if (repeatedBeforeLast !== void 0) throw new Error(`Repeated positional argument before another one: ${repeatedBeforeLast.field}`);
+	if (repeatedBeforeLast !== void 0) throw new Error(`Repeated positional argument before another one: ${repeatedBeforeLast.field} (list an array field last)`);
 	return ordered;
 };
 const wholeInputFlag = (encoded) => Flag.String("input").pipe(Flag.withSchema(jsonOfAcceptedKindOrText(encoded)), Flag.withDescription("Whole action input as JSON; omitted, {}"), Flag.optional);
 const printedOutput = (action, value, render) => Effect.map(Effect.orDie(Schema.encodeEffect(Schema.toCodecJson(action.success))(value)), (encoded) => render === void 0 && SchemaAST.isVoid(action.success.ast) ? Option.none() : Option.some(render === void 0 ? JSON.stringify(encoded, null, 2) : render(value)));
 /**
 * What a command fails with when its action fails: Effect CLI's `UserError`, typed with the
-* action's failure as its `cause` and `reason`, and whose message is its JSON, which `Command.run`
-* prints on stderr and marks reported, so `runMain` does not print it again. The process exits with
-* the cause's `Runtime.errorExitCode`, 1 by default. A type only: after `Command.run`, match the
-* reason by its tag, `Effect.catchReason("UserError", "UserNotFound", f)`. A command of your own
-* fails with one through `toUserError`; any other failure is reported as a crash, `ERROR (#n)`.
+* action's failure as its `cause` and `reason`, and whose `userMessage` is its JSON, or for a
+* failure no schema encodes, as `command` says. A type only.
+*
+* **Gotchas**
+*
+* - `Command.run` has printed it before a recovery runs, so a recovery decides what follows, such as the exit code, not the text: for text of your own, provide `CliOutput.layer(Object.assign({}, CliOutput.defaultFormatter(), { formatError }))`, or pass `renderErrors: false` to `Command.run` and print every failure, the parser's too.
+* - A run also fails with Effect CLI's own errors, such as a flag that does not parse, and only a `UserError` has a `userMessage`: match `Effect.catchTag("UserError", …)` before reading one.
 */
 var UserError = class extends CliError.UserError {
 	/**
@@ -207,7 +210,7 @@ const userErrorOf = (errors) => {
 	}))));
 };
 const failingAsDerived = (errors) => {
-	const failure = userErrorOf([...new Set(errors)]);
+	const failure = userErrorOf(errorSchemas(errors));
 	return (self) => Effect.catchIf(self, (error) => !CliError.isCliError(error), failure);
 };
 const unreadableStdinField = (field, message) => new InvalidInput({
@@ -223,7 +226,7 @@ const fieldValueFromText = (field) => {
 };
 const stdinTextOf = (field) => Effect.gen(function* () {
 	const stdio = yield* Effect.serviceOption(Stdio.Stdio);
-	if (Option.isNone(stdio)) return yield* Effect.die(/* @__PURE__ */ new Error("Stdio is not provided"));
+	if (Option.isNone(stdio)) return yield* Effect.die(/* @__PURE__ */ new Error("Stdio is not provided (provide NodeServices.layer, or Stdio.layerTest in a test)"));
 	if (yield* stdio.value.stdinIsTerminal) return yield* unreadableStdinField(field, `${field} is read from stdin, which is a terminal: pipe it in`);
 	return (yield* stdio.value.stdin.pipe(Stream.decodeText(), Stream.mkString, Effect.mapError((error) => unreadableStdinField(field, `stdin cannot be read: ${error.message}`)))).replace(/[\r\n]+$/, "");
 });
@@ -235,8 +238,8 @@ const inputConfig = (action, positional, aliases, stdin) => {
 		const params = fieldParams(encoded, unsuspended(action.input.ast), positional, aliases);
 		const fromStdin = Option.map(Option.fromUndefinedOr(stdin), (field) => {
 			const property = encoded.propertySignatures.find(({ name }) => name === field);
-			if (property === void 0 || SchemaAST.isOptional(property.type)) throw new Error(`Not a required input field: ${field}`);
-			if (positional.includes(field)) throw new Error(`Both positional and stdin: ${field}`);
+			if (property === void 0 || SchemaAST.isOptional(property.type)) throw new Error(`Not a required input field: ${field} (stdin names a required field of the action's input)`);
+			if (positional.includes(field)) throw new Error(`Both positional and stdin: ${field} (take it from one of them)`);
 			const description = params.find((param) => param.field === field)?.description;
 			return {
 				field,
@@ -246,7 +249,7 @@ const inputConfig = (action, positional, aliases, stdin) => {
 		});
 		const flagged = new Set(params.map(({ field }) => field).filter((field) => !positional.includes(field) && field !== stdin));
 		const stray = Object.keys(aliases).find((field) => !flagged.has(field));
-		if (stray !== void 0) throw new Error(`Not a flag's input field: ${stray}`);
+		if (stray !== void 0) throw new Error(`Not a flag's input field: ${stray} (aliases name fields read from flags, neither positional nor stdin)`);
 		return {
 			flags: Object.fromEntries(params.flatMap(({ field, param }) => flagged.has(field) ? [[field, param]] : [])),
 			positional: positionalOrder(params, positional),
@@ -260,9 +263,10 @@ const inputConfig = (action, positional, aliases, stdin) => {
 			stdinHelp: Option.getOrUndefined(Option.map(fromStdin, ({ help }) => help))
 		};
 	}
-	if (positional.length > 0) throw new Error(`Positional arguments need named input fields: ${positional.join(", ")}`);
-	if (Object.keys(aliases).length > 0) throw new Error(`Aliases need named input fields: ${Object.keys(aliases).join(", ")}`);
-	if (stdin !== void 0) throw new Error(`Stdin needs named input fields: ${stdin}`);
+	const asWhole = "(the input is not a struct, so it is one --input flag: drop the option)";
+	if (positional.length > 0) throw new Error(`Positional arguments need named input fields: ${positional.join(", ")} ${asWhole}`);
+	if (Object.keys(aliases).length > 0) throw new Error(`Aliases need named input fields: ${Object.keys(aliases).join(", ")} ${asWhole}`);
+	if (stdin !== void 0) throw new Error(`Stdin needs named input fields: ${stdin} ${asWhole}`);
 	return {
 		flags: { input: wholeInputFlag(encoded) },
 		positional: [],
@@ -270,16 +274,37 @@ const inputConfig = (action, positional, aliases, stdin) => {
 		stdinHelp: void 0
 	};
 };
+const aliasFlag = (alias) => alias.length === 1 ? `-${alias}` : `--${alias}`;
 const command = (action, execute, options, errors) => {
 	const name = options?.name ?? kebab(action.name);
+	const description = options?.description ?? action.description;
 	const render = options?.render;
 	const { flags, positional, decode, stdinHelp } = inputConfig(action, options?.positional ?? [], options?.aliases ?? {}, options?.stdin);
 	const failing = failingAsDerived(errors);
 	assertDistinct("flag", [
-		...Object.keys(flags).map((field) => [`--${kebab(field)}`, `field ${field}`]),
-		...render === void 0 ? [] : [["--json", "render's --json"]],
-		...Object.entries(options?.aliases ?? {}).flatMap(([field, alias]) => Predicate.isString(alias) ? [[`--${alias.replace(/^-+/, "")}`, `alias of field ${field}`]] : [])
-	], ([flag]) => flag, ([, claimant]) => claimant);
+		...Object.keys(flags).map((field) => [
+			kebab(field),
+			`--${kebab(field)}`,
+			`field ${field}`
+		]),
+		...render === void 0 ? [] : [[
+			"json",
+			"--json",
+			"render's --json"
+		]],
+		...Object.entries(options?.aliases ?? {}).flatMap(([field, alias]) => {
+			const bare = Predicate.isString(alias) ? alias.replace(/^-+/, "") : void 0;
+			return bare === void 0 ? [] : [[
+				bare,
+				aliasFlag(bare),
+				`alias of field ${field}`
+			]];
+		})
+	], ([key]) => key, {
+		labelOf: ([, label]) => label,
+		claimantOf: ([, , claimant]) => claimant,
+		fix: render === void 0 ? "rename the field or the alias" : "rename the field or the alias, or drop `render`"
+	});
 	const args = positional.map(({ param }) => param);
 	const parsedFields = (input, values) => ({
 		...input,
@@ -297,7 +322,7 @@ const command = (action, execute, options, errors) => {
 		args,
 		json: renderedCommandJsonFlag
 	}, ({ input, args: values, json }) => run(parsedFields(input, values), json ? void 0 : render));
-	return stdinHelp === void 0 ? Command.withDescription(command, action.description) : command.pipe(Command.withDescription(`${action.description}\n\n${stdinHelp}`), Command.withShortDescription(action.description));
+	return stdinHelp === void 0 ? Command.withDescription(command, description) : command.pipe(Command.withDescription(`${description}\n\n${stdinHelp}`), Command.withShortDescription(description));
 };
 //#endregion
 export { UserError, command, failingAsDerived, kebab };

package/dist/contract/caller.mjs

@@ -6,7 +6,7 @@
 */
 const Anyone = Symbol.for("@gjermundgaraba/effect-actions/Anyone");
 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`);
+	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 (give it the authentication whose identity the action's caller names)`);
 };
 //#endregion
 export { Anyone, assertAuthentication };

package/dist/contract/declared.mjs

@@ -2,14 +2,23 @@ import { literalValues, members } from "./ast.mjs";
 import { Anyone, assertAuthentication } from "./caller.mjs";
 import { builtIns } from "./errors.mjs";
 import { assertOnce } from "./names.mjs";
+import { httpApiStatusOf } from "./status.mjs";
 import { Predicate, Schema, SchemaAST } from "effect";
 //#region src/contract/declared.ts
 const errorList = (error) => error === void 0 ? [] : Schema.isSchema(error) ? [error] : error;
-const projectedErrors = (action, surface = []) => [.../* @__PURE__ */ new Set([
+const ownsNothing = (ast) => httpApiStatusOf(ast) === void 0 && ast.checks === void 0 && ast.encoding === void 0;
+const schemasOf = (ast) => !ownsNothing(ast) ? [ast] : SchemaAST.isSuspend(ast) ? schemasOf(ast.thunk()) : SchemaAST.isUnion(ast) ? ast.types.flatMap(schemasOf) : [ast];
+/** `errors` as the schemas a call decodes a failure with, in order, each once. */
+const errorSchemas = (errors) => {
+	const schemas = /* @__PURE__ */ new Map();
+	for (const error of errors) for (const ast of schemasOf(error.ast)) if (!schemas.has(ast)) schemas.set(ast, ast === error.ast ? error : Schema.make(ast));
+	return [...schemas.values()];
+};
+const projectedErrors = (action, surface = []) => errorSchemas([
 	...builtIns,
 	...action.error,
 	...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.
@@ -19,24 +28,28 @@ 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) => builtInTags.has(tag));
-	if (tag !== void 0) throw new Error(`${what}: error _tag "${tag}" is built in, and declared on every surface`);
+const builtInTags = new Set(builtIns.flatMap((schema) => encodedTags(schema.ast)));
+/** Throws where two of the schemas in `errors` encode with one `_tag`. */
+const assertDistinctTags = (what, errors) => {
+	const seen = /* @__PURE__ */ new Set();
+	for (const schema of errorSchemas(errors)) for (const tag of new Set(encodedTags(schema.ast))) {
+		if (seen.has(tag)) throw new Error(`${what}: error _tag "${tag}" names two error schemas, which a client cannot tell apart (reuse one schema value, or merge them into one whose fields tell them apart${builtInTags.has(tag) ? "; for a built-in's tag, fail with the built-in itself" : ""})`);
+		seen.add(tag);
+	}
 };
 /**
-* 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.
+* The checks `ActionHttp.make` and `ActionRpc.make` share: each action once, the descriptor every
+* protected action names, and each call's errors distinct by `_tag`. Returns the binding's `error`, as a list, and `authentication`.
 */
 const bindingOf = (what, actions, options) => {
 	assertOnce("action", actions);
-	const error = errorList(options.error);
-	assertOwnTags(what, error);
-	assertAuthentication(actions, options.authentication);
-	return {
-		error,
+	const bound = {
+		error: errorList(options.error),
 		authentication: options.authentication
 	};
+	assertAuthentication(actions, bound.authentication);
+	for (const action of actions) assertDistinctTags(`${what} of "${action.name}"`, bindingErrors(action, bound));
+	return bound;
 };
 //#endregion
-export { assertOwnTags, bindingErrors, bindingOf, errorList, projectedErrors };
+export { assertDistinctTags, bindingErrors, bindingOf, errorList, errorSchemas, projectedErrors };

package/dist/contract/errors.d.mts

@@ -18,27 +18,45 @@ declare const InvalidInput_base: Schema.Class<InvalidInput, Schema.TaggedStruct<
   }>>>;
 }>, import("effect/Cause").YieldableError>;
 /**
- * The request's input does not decode against the action's input. HTTP answers every such
- * request with it, its message the schema's own description of what is wrong, and `issues`
- * the same description an issue at a time, for a caller that points at a field. A handler
- * failing with it for input that decodes but cannot be served may name its own.
+ * The request's input does not decode against the action's input: its message is the schema's
+ * own description of what is wrong, and `issues` the same an issue at a time, for a caller that
+ * points at a field. A handler fails with it, naming `issues` of its own, for input that decodes
+ * but cannot be served, instead of declaring a second error for bad input.
+ *
+ * **Gotchas**
+ *
+ * - Raised by the library for input that does not decode, before `authorize` and the handler; what each surface answers is on `ActionHttp.layer`, `ActionMcp.layerHttp` and `runStdio`, `ActionRpc.layer`, `ActionToolkit.make` and `ActionCli.command`.
+ * - Failed by a handler, it is answered as a declared error on every surface.
+ * - What receives encoded input, a route, an MCP tool, an rpc, a CLI flag or `--input`, refuses an undeclared field with it, nested ones too, naming its path; a typed client drops such a field instead, as its JSDoc says.
+ * - Its message and `issues` name paths and what the schema expects, never a field's value; a path names every key it passes through, a record's keys included, so never key a record by a secret such as an email or a token.
+ * - A check's message, or a schema's `message` annotation, is sent as written: never put the input in one.
  */
 export declare class InvalidInput extends InvalidInput_base {
   private readonly "~declared in the action's error, or built in";
   /**
    * 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,
-   * such as a header or a route parameter. Neither carries a value of the input: decoding
-   * runs without `reportInput`, so no issue holds one to format. A symbol key is sent as its
-   * string form, `Symbol(name)`, as JSON has no symbols, which tells it from a string key of
-   * that name.
+   * such as a header or a route parameter:
+   * `Schema.decodeUnknownEffect(schema)(value, { errors: "all" }).pipe(Effect.mapError(Action.InvalidInput.fromSchemaError))`.
+   * A symbol key is sent as its string form, `Symbol(name)`, as JSON has no symbols, which
+   * tells it from a string key of that name.
    */
   static readonly fromSchemaError: ({ issue, message }: Schema.SchemaError) => InvalidInput;
 }
 declare const Unauthenticated_base: Schema.Class<Unauthenticated, Schema.TaggedStruct<"Unauthenticated", {
   readonly message: Schema.withConstructorDefault<Schema.String>;
 }>, import("effect/Cause").YieldableError>;
-/** The caller is not authenticated: authentication or an implementation's `authorize` refuses. */
+/**
+ * The caller is not authenticated: authentication refuses the credential, or an implementation's
+ * `authorize` or a handler fails with it.
+ *
+ * **Gotchas**
+ *
+ * - Over HTTP its JSON with a 401: from authentication before the body is read, from a protected action's `authorize` or handler after the input is decoded, each with the scheme's challenge, none for an API key.
+ * - Over MCP: from authentication, the same HTTP 401 in place of a JSON-RPC answer, before the arguments are decoded; from a protected tool's `authorize` or handler, the HTTP 401 with the challenge on an endpoint under Bearer, otherwise an `isError: true` tool result in a 200.
+ * - Over RPC the typed failure, never a status; on a Toolkit and in a CLI as a declared error.
+ * - From another service's client, such as `ActionHttp.client`, one passed on tells a caller whose token is valid to sign in again: map it to an error the action declares, or to a defect.
+ */
 export declare class Unauthenticated extends Unauthenticated_base {
   private readonly "~declared in the action's error, or built in";
 }
@@ -47,26 +65,33 @@ declare const Forbidden_base: Schema.Class<Forbidden, Schema.TaggedStruct<"Forbi
   readonly scopes: Schema.optionalKey<Schema.NonEmptyArray<Schema.String>>;
 }>, import("effect/Cause").YieldableError>;
 /**
- * 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. What it answers on each surface: `docs/guarantees.md` in this
- * package.
+ * The caller may not run this action: authentication refuses the credential, an
+ * implementation's `authorize` refuses, or a handler fails with it. `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,
+ * which only a server publishing discovery can follow up, so name them only where
+ * re-authorizing can grant them; with fixed tokens, such as API keys, leave them out
+ * (`scopes: []` is a type error).
+ *
+ * **Gotchas**
+ *
+ * - Over HTTP its JSON with a 403: from authentication before the body is read, from `authorize` or a handler after the input is decoded; on a protected route under Bearer, one naming `scopes` also carries the challenge.
+ * - Over MCP, from authentication the HTTP 403 before the arguments are decoded; from `authorize` or a handler an `isError: true` tool result holding its JSON as text, in a **200**, not a 403; only on an endpoint under Bearer is a protected tool's refusal naming `scopes` the HTTP 403 with the challenge instead.
+ * - Over RPC the typed failure, never a status or a challenge; on a Toolkit and in a CLI as a declared error.
+ * - From another service's client, such as `ActionHttp.client`, one passed on becomes this server's own refusal: map it to an error the action declares, or to a defect.
  */
 export declare class Forbidden extends Forbidden_base {
   private readonly "~declared in the action's error, or built in";
 }
 /**
  * What authentication or an implementation's `authorize` refuses a caller with, instead of
- * running a handler. An error an action declares, such as a rate limit, is not a refusal. As a
- * schema, it tells a refusal apart: `Schema.is(Action.Refusal)(error)`.
+ * running a handler. As a schema, it tells a refusal apart: `Schema.is(Action.Refusal)(error)`.
  */
 export declare const Refusal: Schema.Union<readonly [typeof Unauthenticated, typeof Forbidden]>;
 /** A refusal: `Unauthenticated | Forbidden`. */
 export type Refusal = (typeof Refusal)["Type"];
 /**
  * The failures every endpoint and tool declares beyond its action's own, and any handler may
- * fail with: bad input, and every refusal. No action or binding declares them itself.
+ * fail with: bad input, and every refusal. An action or a binding need not declare them; one listed is accepted.
  */
 export declare const builtIns: readonly [typeof InvalidInput, typeof Unauthenticated, typeof Forbidden];
 /** The built-in failures' schemas. */

package/dist/contract/errors.mjs

@@ -7,10 +7,18 @@ const Issue = Schema.Struct({
 });
 const standardIssues = SchemaIssue.makeFormatterStandardSchemaV1();
 /**
-* The request's input does not decode against the action's input. HTTP answers every such
-* request with it, its message the schema's own description of what is wrong, and `issues`
-* the same description an issue at a time, for a caller that points at a field. A handler
-* failing with it for input that decodes but cannot be served may name its own.
+* The request's input does not decode against the action's input: its message is the schema's
+* own description of what is wrong, and `issues` the same an issue at a time, for a caller that
+* points at a field. A handler fails with it, naming `issues` of its own, for input that decodes
+* but cannot be served, instead of declaring a second error for bad input.
+*
+* **Gotchas**
+*
+* - Raised by the library for input that does not decode, before `authorize` and the handler; what each surface answers is on `ActionHttp.layer`, `ActionMcp.layerHttp` and `runStdio`, `ActionRpc.layer`, `ActionToolkit.make` and `ActionCli.command`.
+* - Failed by a handler, it is answered as a declared error on every surface.
+* - What receives encoded input, a route, an MCP tool, an rpc, a CLI flag or `--input`, refuses an undeclared field with it, nested ones too, naming its path; a typed client drops such a field instead, as its JSDoc says.
+* - Its message and `issues` name paths and what the schema expects, never a field's value; a path names every key it passes through, a record's keys included, so never key a record by a secret such as an email or a token.
+* - A check's message, or a schema's `message` annotation, is sent as written: never put the input in one.
 */
 var InvalidInput = class InvalidInput extends Schema.TaggedError()("InvalidInput", {
 	message: defaultedMessage("The input does not match the action's input."),
@@ -19,10 +27,10 @@ var InvalidInput = class InvalidInput extends Schema.TaggedError()("InvalidInput
 	/**
 	* 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,
-	* such as a header or a route parameter. Neither carries a value of the input: decoding
-	* runs without `reportInput`, so no issue holds one to format. A symbol key is sent as its
-	* string form, `Symbol(name)`, as JSON has no symbols, which tells it from a string key of
-	* that name.
+	* such as a header or a route parameter:
+	* `Schema.decodeUnknownEffect(schema)(value, { errors: "all" }).pipe(Effect.mapError(Action.InvalidInput.fromSchemaError))`.
+	* A symbol key is sent as its string form, `Symbol(name)`, as JSON has no symbols, which
+	* tells it from a string key of that name.
 	*/
 	static fromSchemaError = ({ issue, message }) => new InvalidInput({
 		message,
@@ -35,16 +43,34 @@ var InvalidInput = class InvalidInput extends Schema.TaggedError()("InvalidInput
 		}))
 	});
 };
-/** The caller is not authenticated: authentication or an implementation's `authorize` refuses. */
+/**
+* The caller is not authenticated: authentication refuses the credential, or an implementation's
+* `authorize` or a handler fails with it.
+*
+* **Gotchas**
+*
+* - Over HTTP its JSON with a 401: from authentication before the body is read, from a protected action's `authorize` or handler after the input is decoded, each with the scheme's challenge, none for an API key.
+* - Over MCP: from authentication, the same HTTP 401 in place of a JSON-RPC answer, before the arguments are decoded; from a protected tool's `authorize` or handler, the HTTP 401 with the challenge on an endpoint under Bearer, otherwise an `isError: true` tool result in a 200.
+* - Over RPC the typed failure, never a status; on a Toolkit and in a CLI as a declared error.
+* - From another service's client, such as `ActionHttp.client`, one passed on tells a caller whose token is valid to sign in again: map it to an error the action declares, or to a defect.
+*/
 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. What it answers on each surface: `docs/guarantees.md` in this
-* package.
+* The caller may not run this action: authentication refuses the credential, an
+* implementation's `authorize` refuses, or a handler fails with it. `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,
+* which only a server publishing discovery can follow up, so name them only where
+* re-authorizing can grant them; with fixed tokens, such as API keys, leave them out
+* (`scopes: []` is a type error).
+*
+* **Gotchas**
+*
+* - Over HTTP its JSON with a 403: from authentication before the body is read, from `authorize` or a handler after the input is decoded; on a protected route under Bearer, one naming `scopes` also carries the challenge.
+* - Over MCP, from authentication the HTTP 403 before the arguments are decoded; from `authorize` or a handler an `isError: true` tool result holding its JSON as text, in a **200**, not a 403; only on an endpoint under Bearer is a protected tool's refusal naming `scopes` the HTTP 403 with the challenge instead.
+* - Over RPC the typed failure, never a status or a challenge; on a Toolkit and in a CLI as a declared error.
+* - From another service's client, such as `ActionHttp.client`, one passed on becomes this server's own refusal: map it to an error the action declares, or to a defect.
 */
 var Forbidden = class extends Schema.TaggedError()("Forbidden", {
 	message: defaultedMessage("Not allowed."),
@@ -53,13 +79,12 @@ var Forbidden = class extends Schema.TaggedError()("Forbidden", {
 const refusals = [Unauthenticated, Forbidden];
 /**
 * What authentication or an implementation's `authorize` refuses a caller with, instead of
-* running a handler. An error an action declares, such as a rate limit, is not a refusal. As a
-* schema, it tells a refusal apart: `Schema.is(Action.Refusal)(error)`.
+* running a handler. As a schema, it tells a refusal apart: `Schema.is(Action.Refusal)(error)`.
 */
 const Refusal = Schema.Union(refusals);
 /**
 * The failures every endpoint and tool declares beyond its action's own, and any handler may
-* fail with: bad input, and every refusal. No action or binding declares them itself.
+* fail with: bad input, and every refusal. An action or a binding need not declare them; one listed is accepted.
 */
 const builtIns = [InvalidInput, ...refusals];
 /** The built-in failures as one schema: `Schema.is(Action.BuiltIn)(error)`. */

package/dist/contract/hints.mjs

@@ -1,7 +1,8 @@
 //#region src/contract/hints.ts
 /**
-* 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
+* An action's MCP tool hints, MCP's defaults where its `mcp` leaves one out, except that a read
+* is not destructive where MCP's default would say it is: 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 }) => ({

package/dist/contract/implementation.d.mts

@@ -28,14 +28,12 @@ interface Memoized<S, E, R> {
 }
 /**
  * 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.
  */
 export declare class Implementation<A extends Any, RequestServices extends {
   readonly [name: string]: unknown;
@@ -43,7 +41,7 @@ export declare class Implementation<A extends Any, RequestServices extends {
   #private;
   /** The contracts this implementation answers. */
   readonly actions: ReadonlyArray<A>;
-  /** Type-only: each action's handler's per-request requirements. */
+  /** Type-only: each action's handler's request-time requirements. */
   readonly "~request": RequestServices;
   /** Type-only: what building its handlers fails with. */
   readonly "~buildError": EX;
@@ -72,8 +70,7 @@ export declare class Implementation<A extends Any, RequestServices extends {
   /**
    * 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: AnyImplementation): Layer.Layer<never, unknown, unknown>;
   /**

package/dist/contract/implementation.mjs

@@ -1,6 +1,6 @@
 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
@@ -14,14 +14,12 @@ 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 {
 	actions;
@@ -47,8 +45,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 +66,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 +103,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 +122,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,
@@ -157,4 +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

@@ -2,9 +2,13 @@ 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;

package/dist/contract/media.mjs

@@ -7,9 +7,13 @@ 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";