@gjermundgaraba/effect-actions 0.18.2 → 0.20.0

package/dist/cli/commands.mjs

@@ -1,11 +1,12 @@
 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";
 import { CliError, Command, Flag, Param } from "effect/cli";
-//#region src/cli/commands.ts
+// src/cli/commands.ts
 const kebab = (name) => {
 	const kebabbed = name.replace(/([A-Z]+)([A-Z][a-z])/g, "$1-$2").replace(/([a-z0-9])([A-Z])/g, "$1-$2").replace(/_/g, "-").replace(/^-+|-+$/g, "").toLowerCase();
 	return kebabbed === "" ? name : kebabbed;
@@ -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,6 @@ 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/ast.mjs

@@ -1,10 +1,9 @@
 import { SchemaAST } from "effect";
-//#region src/contract/ast.ts
+// src/contract/ast.ts
 const unsuspended = (ast) => SchemaAST.isSuspend(ast) ? unsuspended(ast.thunk()) : ast;
 const members = (ast) => {
 	const resolved = unsuspended(ast);
 	return SchemaAST.isUnion(resolved) ? resolved.types.flatMap(members) : [resolved];
 };
 const literalValues = (ast) => SchemaAST.isLiteral(ast) ? [ast.literal] : SchemaAST.isEnum(ast) ? ast.enums.map(([, value]) => value) : [void 0];
-//#endregion
 export { literalValues, members, unsuspended };

package/dist/contract/call.d.mts

@@ -2,12 +2,10 @@ import "./errors.mjs";
 import "./implementation.mjs";
 import { Any } from "../Action.mjs";
 import { Effect, Schema } from "effect";
-//#region src/contract/call.d.ts
 /**
  * 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`, `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
+export type Call<A extends Any, R> = {} extends A["input"]["Encoded"] ? (...input: [] | [input: A["input"]["Type"]]) => R : (input: A["input"]["Type"]) => R;

package/dist/contract/call.mjs

@@ -1,6 +1,6 @@
 import { InvalidInput } from "./errors.mjs";
 import { Effect, Schema } from "effect";
-//#region src/contract/call.ts
+// 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.
@@ -19,5 +19,4 @@ 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, decodeInput, inputOf, inputParseOptions };

package/dist/contract/caller.d.mts

@@ -1,9 +1,7 @@
 import "../Action.mjs";
-//#region src/contract/caller.d.ts
 /**
  * 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.
  */
-export declare const Anyone: unique symbol;
-//#endregion
+export declare const Anyone: unique symbol;

package/dist/contract/caller.mjs

@@ -1,4 +1,4 @@
-//#region src/contract/caller.ts
+// src/contract/caller.ts
 /**
 * 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
@@ -6,7 +6,6 @@
 */
 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.d.mts

@@ -1,7 +1,6 @@
 import "./caller.mjs";
 import { Errors } from "../Action.mjs";
 import { Types } from "effect";
-//#region src/contract/declared.d.ts
 type ListOf<G> = G extends Errors ? G : readonly [G];
 /**
  * The errors options `O` declare, as at run time: those `error` always gives, or, where it may
@@ -24,5 +23,4 @@ export interface Declaring {
     readonly error: Errors;
   } | undefined;
 }
-//#endregion
 export {};

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
+// 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,27 @@ 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

@@ -1,5 +1,4 @@
 import { Schema } from "effect";
-//#region src/contract/errors.d.ts
 declare const Issue: Schema.Struct<{
   readonly path: Schema.$Array<Schema.Union<readonly [Schema.String, Schema.Finite]>>;
   readonly message: Schema.String;
@@ -18,27 +17,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 +64,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. */
@@ -75,5 +99,4 @@ export type BuiltIns = (typeof builtIns)[number];
 export declare const BuiltIn: Schema.Union<readonly [typeof InvalidInput, typeof Unauthenticated, typeof Forbidden]>;
 /** A built-in failure: `InvalidInput | Refusal`. */
 export type BuiltIn = (typeof BuiltIn)["Type"];
-//#endregion
 export { Issue };

package/dist/contract/errors.mjs

@@ -1,5 +1,5 @@
 import { Effect, Predicate, Schema, SchemaIssue } from "effect";
-//#region src/contract/errors.ts
+// src/contract/errors.ts
 const defaultedMessage = (fallback) => Schema.String.pipe(Schema.withConstructorDefault(Effect.succeed(fallback)));
 const Issue = Schema.Struct({
 	path: Schema.Array(Schema.Union([Schema.String, Schema.Finite])),
@@ -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,16 +79,14 @@ 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)`. */
 const BuiltIn = Schema.Union(builtIns);
-//#endregion
 export { BuiltIn, Forbidden, InvalidInput, Refusal, Unauthenticated, builtIns, scopeToken };

package/dist/contract/hints.mjs

@@ -1,7 +1,8 @@
-//#region src/contract/hints.ts
+// 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 }) => ({
@@ -10,5 +11,4 @@ const hintsOf = ({ readOnly, mcp }) => ({
 	idempotentHint: mcp.idempotentHint ?? false,
 	openWorldHint: mcp.openWorldHint ?? true
 });
-//#endregion
 export { hintsOf };

package/dist/contract/implementation.d.mts

@@ -2,7 +2,6 @@ import { Anyone } from "./caller.mjs";
 import { Refusal } from "./errors.mjs";
 import { Any } from "../Action.mjs";
 import { Context, Effect, Layer, Scope } from "effect";
-//#region src/contract/implementation.d.ts
 /** Decoded values at the dispatch boundary every surface shares. */
 export type ErasedValue = Any["input"]["Type"];
 /**
@@ -28,22 +27,18 @@ 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;
 }, EX, RX, RA = never, EAX = never, RAX = never> {
   #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;
@@ -55,9 +50,9 @@ export declare class Implementation<A extends Any, RequestServices extends {
   readonly "~authorizeBuildError": EAX;
   /** Type-only: what building its authorizer needs. */
   readonly "~authorizeBuildServices": RAX;
-  constructor(
   /** The contracts this implementation answers. */
-  actions: ReadonlyArray<A>,
+  readonly actions: ReadonlyArray<A>;
+  constructor(actions: ReadonlyArray<A>,
   /** Builds each action paired with its handler: its own builder, or the one it shares. */
   handlers: Memoized<Bound, EX, RX>,
   /** Builds its authorizer. */
@@ -72,8 +67,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>;
   /**
@@ -192,5 +186,4 @@ export type BuildServices<App, Listed extends Any = OwnActions<App>> = App exten
   readonly "~buildServices": infer RX;
   readonly "~authorizeBuildServices": infer RAX;
 } ? RX | ([Protected<Serving<App, Listed>>] extends [never] ? never : RAX) : never;
-//#endregion
 export {};