@gjermundgaraba/effect-actions 0.11.0 → 0.13.0

package/dist/cli/commands.mjs

@@ -0,0 +1,302 @@
+import { InvalidInput } from "../contract/errors.mjs";
+import { assertDistinct, literalValues, members, projectedErrors, unsuspended } from "../contract/rules.mjs";
+import { withStderrConsole } from "../stdio/console.mjs";
+import { Console, Effect, Option, Predicate, Record, Runtime, Schema, SchemaAST, Stdio, Stream, flow } from "effect";
+import { CliError, Command, Flag, Param } from "effect/cli";
+//#region 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;
+};
+const renderedCommandJsonFlag = Flag.Boolean("json").pipe(Flag.withDefault(false), Flag.withDescription("Print machine-readable JSON"));
+const jsonKinds = [
+	"null",
+	"boolean",
+	"number",
+	"string",
+	"array",
+	"object"
+];
+const jsonKindOf = (value) => value === null ? "null" : Predicate.isBoolean(value) ? "boolean" : Predicate.isNumber(value) ? "number" : Predicate.isString(value) ? "string" : Array.isArray(value) ? "array" : "object";
+const acceptedJsonKindsOf = (ast) => members(ast).flatMap((member) => {
+	if (SchemaAST.isLiteral(member)) return [jsonKindOf(member.literal)];
+	if (SchemaAST.isEnum(member)) return member.enums.map(([, value]) => jsonKindOf(value));
+	if (SchemaAST.isNull(member)) return ["null"];
+	if (SchemaAST.isBoolean(member)) return ["boolean"];
+	if (SchemaAST.isNumber(member)) return ["number"];
+	if (SchemaAST.isString(member) || SchemaAST.isTemplateLiteral(member)) return ["string"];
+	if (SchemaAST.isArrays(member)) return ["array"];
+	if (SchemaAST.isObjects(member)) return ["object"];
+	return jsonKinds;
+});
+const jsonOfAcceptedKindOrText = (encoded) => {
+	const accepted = new Set(acceptedJsonKindsOf(encoded));
+	return Schema.Union([Schema.fromJsonString(Schema.Json).check(Schema.makeFilter((json) => accepted.has(jsonKindOf(json)))), Schema.String]);
+};
+const stringChoicesOf = (ast) => {
+	const accepted = members(ast).flatMap(literalValues);
+	return accepted.every(Predicate.isString) ? accepted : void 0;
+};
+const takesTextAsIs = (encoded) => stringChoicesOf(encoded) !== void 0 || SchemaAST.isString(encoded) || SchemaAST.isTemplateLiteral(encoded);
+const valueParam = (kind, name, field) => {
+	const encoded = unsuspended(field);
+	if (takesTextAsIs(encoded)) {
+		const literals = stringChoicesOf(encoded);
+		return literals === void 0 ? Param.String(kind, name) : Param.Literals(kind, name, literals);
+	}
+	if (SchemaAST.isBoolean(encoded)) return Param.Boolean(kind, name);
+	return Param.String(kind, name).pipe(Param.withSchema(jsonOfAcceptedKindOrText(encoded)), Param.withMetavar("value"));
+};
+const withoutOptionalAbsence = (ast) => {
+	const members = SchemaAST.isUnion(ast) ? ast.types.filter((member) => !SchemaAST.isNull(member) && !SchemaAST.isUndefined(member)) : [];
+	return members.length === 1 && members[0] !== void 0 ? members[0] : ast;
+};
+const optionalAddedNull = (plain) => {
+	const types = members(plain);
+	return types.some(SchemaAST.isUndefined) && !types.some(SchemaAST.isNull);
+};
+const repeatedElementOf = (ast) => {
+	const encoded = unsuspended(ast);
+	if (!SchemaAST.isArrays(encoded)) return void 0;
+	const [element, ...after] = encoded.rest;
+	if (element === void 0 || after.length > 0 || !encoded.elements.every((first) => first === element) || !acceptedJsonKindsOf(element).every((kind) => kind === "string" || kind === "number")) return;
+	return {
+		element,
+		min: encoded.elements.length
+	};
+};
+const noElementOccurrence = "[]";
+const jsonHintOf = (encoded) => {
+	const value = unsuspended(encoded);
+	const kinds = new Set(acceptedJsonKindsOf(value));
+	if (kinds.size !== 1) return void 0;
+	if (kinds.has("object")) return "A JSON object.";
+	if (!kinds.has("array")) return void 0;
+	const fields = elementFieldsOf(value);
+	return fields === void 0 ? "A JSON array." : `A JSON array of {${fields.join(", ")}}.`;
+};
+const elementFieldsOf = (array) => {
+	if (!SchemaAST.isArrays(array)) return void 0;
+	const [element, ...others] = [...array.elements, ...array.rest];
+	if (element === void 0 || others.some((other) => other !== element)) return void 0;
+	const fields = namedFieldsOf(unsuspended(element));
+	return fields.size === 0 ? void 0 : Array.from(fields, ([name, field]) => SchemaAST.isOptional(field) ? `${String(name)}?` : String(name));
+};
+const withHint = (description, hint) => {
+	if (hint === void 0 || description === void 0) return description ?? hint;
+	const stated = description.trimEnd();
+	return /[.!?:]$/.test(stated) ? `${stated} ${hint}` : `${stated}. ${hint}`;
+};
+const fieldParam = (kind, name, encoded, plain) => {
+	const optional = SchemaAST.isOptional(encoded);
+	const value = optional && plain !== void 0 && optionalAddedNull(plain) ? withoutOptionalAbsence(encoded) : encoded;
+	const repeats = repeatedElementOf(value);
+	if (repeats !== void 0) {
+		const literals = stringChoicesOf(unsuspended(repeats.element));
+		const elements = literals === void 0 ? valueParam(kind, name, repeats.element) : Param.Literals(kind, name, [...literals, noElementOccurrence]);
+		const listed = (values) => Option.some(values.filter((value) => value !== noElementOccurrence));
+		return {
+			param: optional ? Param.variadic(elements).pipe(Param.map((values) => values.length === 0 ? Option.none() : listed(values))) : Param.variadic(elements, { min: repeats.min }).pipe(Param.map(listed)),
+			repeats: true,
+			hint: kind === Param.flagKind ? "Repeat for each value." : void 0
+		};
+	}
+	if (optional) return {
+		param: Param.optional(valueParam(kind, name, value)),
+		repeats: false,
+		hint: kind === Param.flagKind && SchemaAST.isBoolean(unsuspended(value)) ? `--no-${name} sends false.` : jsonHintOf(value)
+	};
+	const isSwitch = kind === Param.flagKind && SchemaAST.isBoolean(unsuspended(encoded));
+	return {
+		param: isSwitch ? Flag.Boolean(name).pipe(Flag.withDefault(false), Flag.map(Option.some)) : valueParam(kind, name, encoded).pipe(Param.map(Option.some)),
+		repeats: false,
+		hint: isSwitch ? "Left out, it sends false." : jsonHintOf(encoded)
+	};
+};
+const namedFieldsOf = (ast) => {
+	const fields = SchemaAST.isDeclaration(ast) ? ast.typeParameters[0] : ast;
+	return new Map(fields !== void 0 && SchemaAST.isObjects(fields) ? fields.propertySignatures.map((property) => [property.name, property.type]) : []);
+};
+const isTransformedAsWhole = (ast) => (SchemaAST.isDeclaration(ast) ? ast.typeParameters[0] : ast)?.encoding !== void 0;
+const ownOrSuspendedDescriptionOf = (ast) => ast.context?.annotations?.description ?? SchemaAST.resolveDescription(ast) ?? describedBeforeLastCheck(ast) ?? (SchemaAST.isSuspend(ast) ? ownOrSuspendedDescriptionOf(ast.thunk()) : void 0);
+const describedBeforeLastCheck = (ast) => [ast.annotations, ...(ast.checks ?? []).map((check) => check.annotations)].map((annotations) => annotations?.["description"]).findLast(Predicate.isString);
+const describedThroughAbsence = (ast) => ownOrSuspendedDescriptionOf(ast) ?? ownOrSuspendedDescriptionOf(withoutOptionalAbsence(ast));
+const describedByElement = (ast) => {
+	const array = unsuspended(withoutOptionalAbsence(ast));
+	const element = SchemaAST.isArrays(array) ? array.rest[0] : void 0;
+	return element === void 0 ? void 0 : describedThroughAbsence(element);
+};
+const fieldParams = (encoded, input, positional, aliases) => {
+	const plainEncodedFields = namedFieldsOf(SchemaAST.toEncoded(input));
+	const declaredFieldsUnlessRenamed = namedFieldsOf(isTransformedAsWhole(input) ? encoded : SchemaAST.toType(input));
+	return encoded.propertySignatures.map((property) => {
+		const field = String(property.name);
+		const declaredField = declaredFieldsUnlessRenamed.get(property.name);
+		const kind = positional.includes(field) ? Param.argumentKind : Param.flagKind;
+		const { param, repeats, hint } = fieldParam(kind, kebab(field), property.type, plainEncodedFields.get(property.name));
+		const alias = kind === Param.flagKind ? aliases[field] : void 0;
+		const aliased = alias === void 0 ? param : Param.withAlias(param, alias);
+		const documented = declaredField ?? property.type;
+		const description = describedThroughAbsence(documented) ?? describedThroughAbsence(property.type) ?? (repeats ? describedByElement(documented) ?? describedByElement(property.type) : void 0);
+		const help = withHint(description, hint);
+		return {
+			field,
+			param: help === void 0 ? aliased : Param.withDescription(aliased, help),
+			optional: SchemaAST.isOptional(property.type),
+			repeats,
+			hint,
+			description
+		};
+	});
+};
+const positionalOrder = (params, positional) => {
+	assertDistinct("positional argument", positional, (field) => field);
+	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}`);
+		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}`);
+	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}`);
+	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)`.
+*/
+var UserError = class extends CliError.UserError {
+	/**
+	* The action's failure, as Effect names an error's nested one, so the native
+	* `Effect.catchReason("UserError", "UserNotFound", f)` and `catchReasons` match it by tag.
+	*/
+	get reason() {
+		return this.cause;
+	}
+	get [Runtime.errorExitCode]() {
+		return Runtime.getErrorExitCode(this.cause);
+	}
+};
+const ownStringProperty = (error, key) => {
+	if (!Predicate.hasProperty(error, key)) return void 0;
+	const value = error[key];
+	return Predicate.isString(value) ? value : void 0;
+};
+const describedWithoutFields = (error, seen = /* @__PURE__ */ new Set()) => {
+	const name = ownStringProperty(error, "_tag") ?? (error instanceof Error ? error.name : "Error");
+	const message = Predicate.isString(error) ? error : ownStringProperty(error, "message") ?? "";
+	const named = message === "" ? name : `${name}: ${message}`;
+	seen.add(error);
+	return Predicate.hasProperty(error, "cause") && error.cause !== void 0 && !seen.has(error.cause) ? `${named}: ${describedWithoutFields(error.cause, seen)}` : named;
+};
+const userErrorOf = (errors) => {
+	const encode = Schema.encodeUnknownEffect(Schema.fromJsonString(Schema.toCodecJson(Schema.Union(errors))));
+	return (error) => encode(error, { onExcessProperty: "error" }).pipe(Effect.catch(() => encode(error)), Effect.orElseSucceed(() => describedWithoutFields(error)), Effect.flatMap((userMessage) => Effect.fail(new UserError({
+		cause: error,
+		userMessage
+	}))));
+};
+const failingAsDerived = (actions, surfaceErrorsOf) => {
+	const failure = userErrorOf([...new Set(actions.flatMap((action) => projectedErrors(action, surfaceErrorsOf(action))))]);
+	return (self) => Effect.catchIf(self, (error) => !CliError.isCliError(error), failure);
+};
+const unreadableStdinField = (field, message) => new InvalidInput({
+	message,
+	issues: [{
+		path: [field],
+		message
+	}]
+});
+const fieldValueFromText = (field) => {
+	const encoded = unsuspended(field);
+	return takesTextAsIs(encoded) ? (text) => text : Schema.decodeSync(jsonOfAcceptedKindOrText(encoded));
+};
+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 (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]+$/, "");
+});
+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));
+	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) => {
+			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}`);
+			const description = params.find((param) => param.field === field)?.description;
+			return {
+				field,
+				value: fieldValueFromText(property.type),
+				help: `Reads ${kebab(field)} from stdin${description === void 0 ? "." : `: ${description}`}`
+			};
+		});
+		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}`);
+		return {
+			flags: Object.fromEntries(params.flatMap(({ field, param }) => flagged.has(field) ? [[field, param]] : [])),
+			positional: positionalOrder(params, positional),
+			decode: (parsed) => Option.match(fromStdin, {
+				onNone: () => decode(Record.getSomes(parsed)),
+				onSome: ({ field, value }) => Effect.flatMap(stdinTextOf(field), (text) => decode({
+					...Record.getSomes(parsed),
+					[field]: value(text)
+				}))
+			}),
+			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}`);
+	return {
+		flags: { input: wholeInputFlag(encoded) },
+		positional: [],
+		decode: (parsed) => decode(Option.getOrElse(parsed["input"] ?? Option.none(), () => ({}))),
+		stdinHelp: void 0
+	};
+};
+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));
+	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);
+	const args = positional.map(({ param }) => param);
+	const parsedFields = (input, values) => ({
+		...input,
+		...Object.fromEntries(positional.map(({ field }, index) => [field, values[index] ?? Option.none()]))
+	});
+	const run = (parsed, rendered) => decode(parsed).pipe(Effect.flatMap(execute), Effect.catch(failure), Effect.flatMap((value) => printedOutput(action, value, rendered)), withStderrConsole, Effect.flatMap(Option.match({
+		onNone: () => Effect.void,
+		onSome: Console.log
+	})));
+	const command = render === void 0 ? Command.make(name, {
+		input: flags,
+		args
+	}, ({ input, args: values }) => run(parsedFields(input, values), void 0)) : Command.make(name, {
+		input: flags,
+		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));
+};
+//#endregion
+export { UserError, command, failingAsDerived, kebab };

package/dist/{internal → contract}/call.d.mts

@@ -1,12 +1,12 @@
 import "./implementation.mjs";
 import { Action_d_exports, Any } from "../Action.mjs";
 import { Effect, Schema } from "effect";
-//#region src/internal/call.d.ts
+//#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`, `Testing.mcpClient` and `Action.client`.
+ * `ActionHttp.client`, `ActionRpc.client`, `Testing.mcpClient` 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

@@ -0,0 +1,10 @@
+import { InvalidInput } from "./errors.mjs";
+import { Effect, Schema } from "effect";
+//#region src/contract/call.ts
+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 };

package/dist/{internal → contract}/errors.d.mts

@@ -1,14 +1,14 @@
 import { Schema } from "effect";
-//#region src/internal/errors.d.ts
-/**
- * One thing wrong with an input: where, as the keys and indexes leading to it from the input's
- * root, none for the input itself, and what the schema expects there.
- */
+//#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;
 }>;
-/** One thing wrong with an input, as `InvalidInput.issues` lists it. */
+/**
+ * One thing wrong with an input, as `InvalidInput.issues` lists it: where, as the keys and
+ * indexes leading to it from the input's root, none for the input itself, and what the schema
+ * expects there.
+ */
 type Issue = (typeof Issue)["Type"];
 declare const InvalidInput_base: Schema.Class<InvalidInput, Schema.TaggedStruct<"InvalidInput", {
   readonly message: Schema.withConstructorDefault<Schema.String>;
@@ -24,7 +24,7 @@ declare const InvalidInput_base: Schema.Class<InvalidInput, Schema.TaggedStruct<
  * failing with it for input that decodes but cannot be served may name its own.
  */
 export declare class InvalidInput extends InvalidInput_base {
-  private readonly "~builtIn";
+  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,
@@ -40,7 +40,7 @@ declare const Unauthenticated_base: Schema.Class<Unauthenticated, Schema.TaggedS
 }>, import("effect/Cause").YieldableError>;
 /** The caller is not authenticated: authentication or an implementation's `authorize` refuses. */
 export declare class Unauthenticated extends Unauthenticated_base {
-  private readonly "~builtIn";
+  private readonly "~declared in the action's error, or built in";
 }
 declare const Forbidden_base: Schema.Class<Forbidden, Schema.TaggedStruct<"Forbidden", {
   readonly message: Schema.withConstructorDefault<Schema.String>;
@@ -49,10 +49,13 @@ 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.
+ * 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.
  */
 export declare class Forbidden extends Forbidden_base {
-  private readonly "~builtIn";
+  private readonly "~declared in the action's error, or built in";
 }
 /**
  * What authentication or an implementation's `authorize` refuses a caller with, instead of

package/dist/{internal → contract}/errors.mjs

@@ -1,17 +1,11 @@
 import { Effect, Predicate, Schema, SchemaIssue } from "effect";
-//#region src/internal/errors.ts
-/** A message field that defaults, so `new Forbidden()` needs no argument. */
-const message = (fallback) => Schema.String.pipe(Schema.withConstructorDefault(Effect.succeed(fallback)));
-/** Each built-in error's HTTP status, by tag: its annotation, and what a refusal answers. */
+//#region src/contract/errors.ts
+const defaultedMessage = (fallback) => Schema.String.pipe(Schema.withConstructorDefault(Effect.succeed(fallback)));
 const statuses = {
 	InvalidInput: 400,
 	Unauthenticated: 401,
 	Forbidden: 403
 };
-/**
-* One thing wrong with an input: where, as the keys and indexes leading to it from the input's
-* root, none for the input itself, and what the schema expects there.
-*/
 const Issue = Schema.Struct({
 	path: Schema.Array(Schema.Union([Schema.String, Schema.Finite])),
 	message: Schema.String
@@ -24,7 +18,7 @@ const standardIssues = SchemaIssue.makeFormatterStandardSchemaV1();
 * failing with it for input that decodes but cannot be served may name its own.
 */
 var InvalidInput = class InvalidInput extends Schema.TaggedError()("InvalidInput", {
-	message: message("The input does not match the action's input."),
+	message: defaultedMessage("The input does not match the action's input."),
 	issues: Schema.Array(Issue).pipe(Schema.withConstructorDefault(Effect.succeed([])))
 }, { httpApiStatus: statuses.InvalidInput }) {
 	/**
@@ -47,20 +41,21 @@ 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: message("Authentication is required.") }, { httpApiStatus: statuses.Unauthenticated }) {};
-/** An OAuth scope token (RFC 6749 §3.3): printable ASCII but space, `"` and `\`. */
+var Unauthenticated = class extends Schema.TaggedError()("Unauthenticated", { message: defaultedMessage("Authentication is required.") }, { httpApiStatus: statuses.Unauthenticated }) {};
 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.
+* 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.
 */
 var Forbidden = class extends Schema.TaggedError()("Forbidden", {
-	message: message("Not allowed."),
+	message: defaultedMessage("Not allowed."),
 	scopes: Schema.optionalKey(Schema.NonEmptyArray(ScopeToken))
 }, { httpApiStatus: statuses.Forbidden }) {};
-/** The refusals, as schemas. */
 const refusals = [Unauthenticated, Forbidden];
 /**
 * What authentication or an implementation's `authorize` refuses a caller with, instead of

package/dist/{internal → contract}/implementation.d.mts

@@ -1,25 +1,28 @@
-import { Anyone } from "./actions.mjs";
+import { Anyone } from "./rules.mjs";
 import { Refusal } from "./errors.mjs";
 import { Action_d_exports, Any } from "../Action.mjs";
 import { Context, Effect, Layer, Scope } from "effect";
-//#region src/internal/implementation.d.ts
+//#region src/contract/implementation.d.ts
 /** Decoded values at the dispatch boundary every surface shares. */
 export type ErasedValue = Any["input"]["Type"];
+/**
+ * A handler, erased. Method extraction makes the argument bivariant: a surface selects the
+ * action before it invokes a handler, so its decoded input is the matching handler input, and
+ * handlers are not widened at their public API.
+ */
 export type ErasedHandler<R> = {
   handle(input: ErasedValue): Effect.Effect<ErasedValue, ErasedValue, R>;
 }["handle"];
-/** Authorization runs only for protected actions, after authentication and before the handler. */
+/**
+ * Authorization for protected contracts: it refuses, and fails with nothing else. It runs only for
+ * protected actions, after authentication and before the handler.
+ */
 export type Authorize<A extends Any, R = never> = (action: A) => Effect.Effect<void, Refusal, R>;
 /** An implementation's authorizer, erased. */
 export type ErasedAuthorize = (action: Any) => Effect.Effect<void, unknown, unknown>;
 /** Each action of an implementation with its handler, as its builder made them. */
 export type Bound = ReadonlyArray<readonly [Any, ErasedHandler<unknown>]>;
-/**
- * What a layer builds once per layer graph, under a key private to it: an implementation's
- * handlers, or its authorizer. Effect memoizes a layer by reference within one layer graph, so
- * everything in the graph holding this one shares one run.
- */
-export interface Memoized<S, E, R> {
+interface Memoized<S, E, R> {
   readonly key: Context.Key<S, S>;
   readonly layer: Layer.Layer<S, E, R>;
 }
@@ -81,7 +84,13 @@ export declare class Implementation<A extends Any, RequestServices extends {
   /** `app`, if this copy of the module made it; another installed copy's cannot be read. */
   private static own;
 }
-/** Any implementation, with its actions and channels erased. */
+/**
+ * Any implementation, with its actions and channels erased: the constraint of a helper generic over
+ * implementations, `<App extends Action.AnyImplementation>`, whatever surface it passes them to;
+ * `AnyImplementation<A>` is one of the actions `A`. Each parameter is covariant, so `unknown`
+ * admits every implementation, while a value of this type owes `unknown`, which no surface can be
+ * given.
+ */
 export type AnyImplementation<A extends Any = Any> = Implementation<A, {
   readonly [name: string]: unknown;
 }, unknown, unknown, unknown, unknown, unknown>;
@@ -101,6 +110,16 @@ export interface Selection<A extends Any> {
 export type Selected<O, All extends Any> = O extends {
   readonly actions: ReadonlyArray<infer A extends Any>;
 } ? A : All;
+/**
+ * The middleware options `O` install, each a member of `L`: its `middleware` when always given,
+ * an array of unknown length when it may be absent, which installs none or all of them, and
+ * none otherwise.
+ */
+export type MiddlewareOf<O, L extends ReadonlyArray<unknown>> = O extends {
+  readonly middleware: infer M extends L;
+} ? M : O extends {
+  readonly middleware?: infer M extends L | undefined;
+} ? "middleware" extends keyof O ? ReadonlyArray<NonNullable<M>[number]> : [] : [];
 /** The actions options `O` select of the implementations `Apps` stand for. */
 export type SelectedOf<O, Apps extends Served> = Selected<O, ActionOf<Member<Apps>>>;
 /**
@@ -109,7 +128,6 @@ export type SelectedOf<O, Apps extends Served> = Selected<O, ActionOf<Member<App
  * given or not; every one where no member lists any.
  */
 export type Offered<O, All extends Any> = [Listing<O>] extends [never] ? All : Extract<All, Listing<O> extends ReadonlyArray<infer A extends Any> ? A : never>;
-/** The lists of actions the members of `O` may give; none where no member gives one. */
 type Listing<O> = O extends unknown ? NonNullable<O["actions" & keyof O]> : never;
 /**
  * No key of any member of `O` beyond those of `Keys`, so a misspelled option is refused
@@ -127,7 +145,6 @@ export type OptionalUnless<O, Given> = {} extends O ? [options?: Given] : [optio
 export type ActionOf<App> = App extends {
   readonly actions: ReadonlyArray<infer A>;
 } ? A : never;
-/** Whether `A` may be one of `Listed`: either is assignable to the other. */
 type Matches<A extends Any, Listed extends Any> = Listed extends Any ? [A] extends [Listed] ? true : [Listed] extends [A] ? true : never : never;
 /**
  * The actions of `App` a surface given the actions `Listed` may serve, as `select` selects
@@ -147,12 +164,7 @@ export type Holding<App, Listed extends Any> = App extends unknown ? [Serving<Ap
 /** The protected members of a contract union. */
 export type Protected<A extends Any> = A extends unknown ? A["caller"] extends typeof Anyone ? never : A : never;
 type ServiceOf<K> = K extends Context.Key<infer I, unknown> ? I : never;
-/**
- * The identity required by the contract, even when its handler never reads it. A `caller`
- * narrowed to `Anyone`, such as `Action.Any & { caller: typeof Anyone }`'s, which TypeScript
- * keeps as `typeof Anyone | (Key & typeof Anyone)`, requires none.
- */
-export type AuthenticationOf<A extends Any> = A["caller"] extends typeof Anyone ? never : ServiceOf<A["caller"]>;
+type AuthenticationOf<A extends Any> = A["caller"] extends typeof Anyone ? never : ServiceOf<A["caller"]>;
 /**
  * Per-request requirements of `App`'s authorization and handler for each `A` it
  * implements: those of every name `A`'s may be, so a union or an erased name owes each it may
@@ -163,14 +175,18 @@ export type RequestOf<App, A extends Any> = App extends {
   readonly "~authorizeRequest": infer RA;
 } ? A extends Any ? [A["name"] & keyof R] extends [never] ? never : R[A["name"] & keyof R] | (A["caller"] extends typeof Anyone ? never : RA) | AuthenticationOf<A> : never : never;
 type OwnActions<App> = Extract<ActionOf<App>, Any>;
-/** Builder failures include authorization only if selected protected actions need it. */
+/**
+ * What a surface serving the actions `Listed` of the implementations `App` fails with at startup:
+ * their builders' and built authorizers' failures, an authorizer's only if a selected protected
+ * action needs it.
+ */
 export type BuildError<App, Listed extends Any = OwnActions<App>> = App extends {
   readonly "~buildError": infer EX;
   readonly "~authorizeBuildError": infer EAX;
 } ? EX | ([Protected<Serving<App, Listed>>] extends [never] ? never : EAX) : never;
 /**
- * What a surface serving the actions `Listed` reads at startup: the services the builders of
- * their handlers and authorization read.
+ * What a surface serving the actions `Listed` of the implementations `App` reads at startup: their
+ * builders' and built authorizers' services.
  */
 export type BuildServices<App, Listed extends Any = OwnActions<App>> = App extends {
   readonly "~buildServices": infer RX;