@gjermundgaraba/effect-actions 0.11.0 → 0.12.0

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;

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

@@ -1,13 +1,8 @@
 import { Unauthenticated } from "./errors.mjs";
-import { Anyone } from "./actions.mjs";
+import { Anyone, assertOnce } from "./rules.mjs";
 import { Array, Context, Effect, Layer, Option } from "effect";
-//#region src/internal/implementation.ts
-/**
-* A random key segment, unique to its caller even across installed copies of this module,
-* where a counter of each copy would repeat another's.
-*/
+//#region src/contract/implementation.ts
 const uniqueKey = () => Math.random().toString(36).slice(2);
-/** What `build` makes, as a layer of its own. */
 const memoized = (build) => {
 	const key = Context.Service(`effect-actions/Implementation/${uniqueKey()}`);
 	return {
@@ -76,12 +71,7 @@ var Implementation = class Implementation {
 		return app;
 	}
 };
-/** A surface's implementations as a list. */
 const toList = (served) => Array.ensure(served);
-/**
-* Refuse an action of `listed` that `held` lacks, by identity, as a stale list, marking one
-* of a held name as another contract's.
-*/
 const assertHeld = (why, listed, held) => {
 	const missing = listed.filter((action) => !held.includes(action));
 	if (missing.length > 0) {
@@ -89,12 +79,6 @@ const assertHeld = (why, listed, held) => {
 		throw new Error(`Listed in actions, but ${why}: ${missing.map(({ name }) => names.has(name) ? `${name} (another contract)` : name).join(", ")}`);
 	}
 };
-/**
-* Each of `apps` narrowed to the actions `listed` holds, matched by identity, behind its own
-* authorization and sharing its builder; one holding none of them is
-* left out, and not built. All of `apps` as they are when nothing is listed. A listed action
-* none of them holds is refused, as a stale list or another contract of its name.
-*/
 const select = (apps, listed) => {
 	if (listed === void 0) return apps;
 	assertHeld("no implementation holds it", listed, apps.flatMap((app) => app.actions));
@@ -104,32 +88,24 @@ const select = (apps, listed) => {
 		return own.length === app.actions.length ? [app] : [Implementation.share(own, app)];
 	});
 };
-/**
-* Provide `layer` the handlers of `apps`. Each implementation's layer is memoized, so its
-* builder runs once per layer graph however many surfaces serve it.
-*/
+const servedBy = (what, bound, apps, listed) => {
+	if (listed !== void 0) assertHeld("the binding does not hold it", 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"}`);
+	}
+	assertOnce("served action", actions);
+	return served;
+};
 const provideHandlers = (apps) => (layer) => {
 	const [first, ...rest] = apps.map((app) => Implementation.layerOf(app));
 	return first === void 0 ? layer : Layer.provide(layer, Layer.mergeAll(first, ...rest));
 };
-/**
-* The builders of `apps` as one layer providing nothing: built above the surfaces, it runs
-* each builder once for all of them, since every surface builds the same memoized layers.
-*/
 const builders = (apps) => Layer.empty.pipe(provideHandlers(apps));
-/**
-* Every action `apps` serve with its handler, behind its authorizer, as `provideHandlers` built
-* them.
-*/
 const acquire = (apps) => Effect.map(Effect.forEach(apps, (app) => Implementation.boundOf(app)), (bound) => bound.flat());
-/**
-* Every action `apps` serve with its handler, behind its authorizer, their builders built as layers
-* of the graph being built around the caller, into its memo map, as `HttpRouter` builds a
-* middleware's dependencies: a builder acquiring them shares each builder's one run with the
-* surfaces of its graph, whichever builds first. Outside any graph, a program under
-* `Effect.provide` shares that layer's, and one under none builds into a map of its own. The
-* caller's scope holds them; a surface serving them too keeps them until it is released.
-*/
 const built = (apps) => {
 	const [first, ...rest] = apps.map((app) => Implementation.layerOf(app));
 	return Effect.gen(function* () {
@@ -141,27 +117,20 @@ const built = (apps) => {
 		return yield* Effect.provideContext(acquire(apps), context);
 	});
 };
-/**
-* One action's handler behind its admission: a protected action's identity, then its
-* `authorize`. These run outside the action's span, so what they fail with is attributed to
-* the surface rather than to a handler that never ran. Each call has a scope of its own, on
-* every surface: what `authorize` and the handler acquire is released when the call ends, the
-* handler's first, so no call needs a `Scope` of its caller.
-*/
 const dispatch = (action, handle, before) => {
-	const attributes = {
+	const actionAttributes = {
 		"action.name": action.name,
 		"action.read_only": action.readOnly
 	};
 	const authentication = action.caller === Anyone ? Effect.void : Effect.flatMap(Effect.serviceOption(action.caller), (actor) => Option.isSome(actor) ? Effect.void : Effect.fail(new Unauthenticated()));
 	const authorization = action.caller === Anyone ? Effect.void : Effect.suspend(() => before(action));
 	return (input) => {
-		const handled = Effect.withSpan(Effect.annotateLogs(Effect.suspend(() => handle(input)), attributes), action.name, {
+		const handled = Effect.withSpan(Effect.annotateLogs(Effect.suspend(() => handle(input)), actionAttributes), action.name, {
 			captureStackTrace: false,
-			attributes
+			attributes: actionAttributes
 		});
 		return Effect.scoped(authentication.pipe(Effect.andThen(authorization), Effect.andThen(handled)));
 	};
 };
 //#endregion
-export { Implementation, acquire, assertHeld, builders, built, memoized, provideHandlers, select, toList, uniqueKey };
+export { Implementation, acquire, assertHeld, builders, built, memoized, provideHandlers, select, servedBy, toList };

package/dist/contract/media.d.mts

@@ -0,0 +1,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
+ * surface sends it as JSON, the bytes in base64. `ActionMcp` refuses it anywhere else.
+ */
+export declare const Image: Schema.Struct<{
+  readonly data: Schema.Uint8Array;
+  readonly mimeType: Schema.String;
+}>;
+//#endregion

package/dist/contract/media.mjs

@@ -0,0 +1,18 @@
+import { Schema } from "effect";
+//#region src/contract/media.ts
+const mediaKindAnnotation = "effect-actions/media";
+const Media = Schema.Struct({
+	data: Schema.Uint8Array,
+	mimeType: Schema.String
+});
+/**
+* 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
+* surface sends it as JSON, the bytes in base64. `ActionMcp` refuses it anywhere else.
+*/
+const Image = Media.annotate({ [mediaKindAnnotation]: "image" });
+const isMarked = (ast) => ast.annotations?.[mediaKindAnnotation] === "image";
+const kindOf = (ast) => isMarked(ast) && ast.encoding === void 0 ? "image" : void 0;
+//#endregion
+export { Image, Media, isMarked, kindOf };

package/dist/contract/rules.d.mts

@@ -0,0 +1,25 @@
+import { Action_d_exports, Errors } from "../Action.mjs";
+import { SchemaAST, Types } from "effect";
+//#region src/contract/rules.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
+ * be absent, those it gives or none, so clients decode each that may arrive.
+ */
+export type ErrorsOf<O> = O extends unknown ? "error" extends keyof O ? O extends {
+  readonly error: infer G extends Errors | Errors[number];
+} ? ListOf<G> : ListOf<Extract<O["error" & keyof O], Errors | Errors[number]>> | [] : [] : never;
+type Single<T> = true extends Types.IsUnion<T> ? never : T;
+/**
+ * The errors a binding of errors `E` surely declares: each slot of one error in a list of
+ * fixed length, never one of an array of unknown length, which may be empty, nor of a list
+ * `E` may be one of several.
+ */
+export type Certain<E extends Errors> = true extends Types.IsUnion<E> ? never : number extends E["length"] ? never : { readonly [K in keyof E]: Single<E[K]>; }[number];
+/**
+ * The 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

package/dist/{internal/actions.mjs → contract/rules.mjs}

@@ -1,37 +1,22 @@
 import { builtIns, statuses } from "./errors.mjs";
 import { Predicate, Schema, SchemaAST } from "effect";
-//#region src/internal/actions.ts
-/**
-* The list an `error` option stands for: one schema, a list as given, or none, as
-* `HttpApiEndpoint` takes it.
-*/
+//#region src/contract/rules.ts
 const errorList = (error) => error === void 0 ? [] : Schema.isSchema(error) ? [error] : error;
-/**
-* What a projection of an action declares: the built-in errors, the action's own, and any
-* its surface adds, such as a binding's. The built-ins come first, since a failure encodes
-* and decodes with the first schema that accepts it, and they are classes, which accept
-* only their own instances: a loose schema of the action's never captures one. A schema
-* listed twice is not repeated.
-*/
 const projectedErrors = (action, surface = []) => [.../* @__PURE__ */ new Set([
 	...builtIns,
 	...action.error,
 	...surface
 ])];
 /**
-* The caller of a public action: anyone, signed in or not. Registered globally, so two copies
-* of the package agree on it, as they agree on a name.
+* 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.
 */
 const Anyone = Symbol.for("@gjermundgaraba/effect-actions/Anyone");
 const validName = /^[A-Za-z0-9_-]{1,128}$/;
-/** Names become path segments, OpenAPI identifiers and client method keys. */
 const assertName = (what, name) => {
 	if (!validName.test(name) || name === "then") throw new Error(`Invalid ${what}: ${name}`);
 };
-/**
-* Names are checked by whoever owns them: an implementation, a binding, a CLI, or the MCP
-* tools. `claimantOf` says who claims a name, so a clash between two claimants names both.
-*/
 const assertDistinct = (what, items, nameOf, claimantOf = nameOf) => {
 	const seen = /* @__PURE__ */ new Map();
 	for (const item of items) {
@@ -45,44 +30,23 @@ const assertDistinct = (what, items, nameOf, claimantOf = nameOf) => {
 		seen.set(name, claimant);
 	}
 };
-/** Refuse an action name `actions` hold twice. */
 const assertOnce = (what, actions) => assertDistinct(what, actions, (action) => action.name);
-/**
-* Refuse a key of options keyed by action name, such as handlers, tools or commands, that no
-* action of `names` has, so a stale option cannot outlive its action.
-*/
 const assertKnown = (what, keys, names) => {
 	const unknown = keys.filter((key) => !names.includes(key));
 	if (unknown.length > 0) throw new Error(`Unknown ${what}: ${unknown.join(", ")}`);
 };
-/** `ast` with any suspension at its top resolved, as a recursive schema's is. */
 const unsuspended = (ast) => SchemaAST.isSuspend(ast) ? unsuspended(ast.thunk()) : ast;
-/** The members of a union, nested and suspended ones included, or the one type otherwise. */
 const members = (ast) => {
 	const resolved = unsuspended(ast);
 	return SchemaAST.isUnion(resolved) ? resolved.types.flatMap(members) : [resolved];
 };
-/**
-* The values a literal or an enum accepts, or `undefined` for any other type, which has no
-* fixed set.
-*/
 const literalValues = (ast) => SchemaAST.isLiteral(ast) ? [ast.literal] : SchemaAST.isEnum(ast) ? ast.enums.map(([, value]) => value) : [void 0];
-/**
-* The `_tag`s a schema's encoding carries: each member's of a union, every value of a union of
-* literals or of an enum, and a suspended schema's, as a recursive error is written.
-*/
-const tagsOf = (ast) => members(SchemaAST.toEncoded(ast)).flatMap((member) => {
+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);
 });
-/**
-* Refuse an error that encodes with a built-in error's `_tag`, the built-in itself included:
-* every endpoint and tool declares the built-in errors already, a client decoding the answer
-* could not tell a look-alike from them, and a look-alike of a refusal would step up. Checked
-* where the action or the binding is made, so every surface and client of it may rely on it.
-*/
 const assertOwnTags = (what, errors) => {
-	const tag = errors.flatMap((error) => tagsOf(error.ast)).find((tag) => Object.hasOwn(statuses, tag));
+	const tag = errors.flatMap((error) => encodedTags(error.ast)).find((tag) => Object.hasOwn(statuses, tag));
 	if (tag !== void 0) throw new Error(`${what}: error _tag "${tag}" is built in, and declared on every surface`);
 };
 //#endregion

package/dist/{internal → http}/client.d.mts

@@ -1,19 +1,17 @@
-import { BuiltIns } from "./errors.mjs";
-import "./implementation.mjs";
-import { Call } from "./call.mjs";
+import { BuiltIns } from "../contract/errors.mjs";
+import { Call } from "../contract/call.mjs";
 import { Action_d_exports, Any, Errors } from "../Action.mjs";
-import { Any as Any$1, VerifierError } from "./authentication.mjs";
+import { Any as Any$1, VerifierError } from "../authentication/provider.mjs";
 import { Effect, Schema } from "effect";
 import { HttpClient, HttpClientError } from "effect/http";
 import { HttpApi, HttpApiClient } from "effect/http-api";
-//#region src/internal/client.d.ts
+//#region src/http/client.d.ts
 /**
  * The native `HttpApiClient.make` options except `transformResponse`: `baseUrl` and
  * `transformClient`. `transformResponse` may change a call's success, failure or
  * services, which the method types cannot follow.
  */
 export type Options = Omit<NonNullable<Parameters<typeof HttpApiClient.make>[1]>, "transformResponse">;
-/** An error schema the binding declares on every endpoint. */
 type BindingError = Errors[number];
 /**
  * What one call of `A` fails with: a declared error value (the action's own, one `E` of the
@@ -22,11 +20,11 @@ type BindingError = Errors[number];
  * the success does not decode. Input that does not encode is `InvalidInput`, and nothing is sent.
  */
 export type MethodError<A extends Any, E extends BindingError = never> = A["error"][number]["Type"] | E["Type"] | BuiltIns["Type"] | HttpClientError.HttpClientError | Schema.SchemaError;
-/** One action as an Effect of its decoded success, failing with `MethodError`. */
 type Method<A extends Any, E extends BindingError> = Call<A, Effect.Effect<A["success"]["Type"], MethodError<A, E>>>;
 /**
- * Any HTTP binding. The API is a native constraint here because native groups are
- * invariant in their endpoints; `actions` carries the types.
+ * Any HTTP binding, with its actions erased: what `layer` and `client` read. The API is a native
+ * constraint here because native groups are invariant in their endpoints; `actions` carries the
+ * types.
  */
 export interface AnyHttp {
   readonly authentication?: Any$1 | undefined;

package/dist/http/client.mjs

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

package/dist/http/declared.mjs

@@ -0,0 +1,20 @@
+import { unsuspended } from "../contract/rules.mjs";
+import { Schema, SchemaAST } from "effect";
+import { HttpServerResponse } from "effect/http";
+import { HttpApiSchema } from "effect/http-api";
+//#region src/http/declared.ts
+const httpApiStatusOf = SchemaAST.resolveAt("httpApiStatus");
+const statusThroughSuspensions = (ast) => httpApiStatusOf(ast) ?? (SchemaAST.isSuspend(ast) ? statusThroughSuspensions(ast.thunk()) : void 0);
+const declared = (error) => {
+	const status = statusThroughSuspensions(error.ast);
+	if (status !== void 0) return [httpApiStatusOf(error.ast) === void 0 ? HttpApiSchema.status(status)(error) : error];
+	const resolved = unsuspended(error.ast);
+	if (SchemaAST.isUnion(resolved) && resolved.checks === void 0 && resolved.encoding === void 0) return resolved.types.flatMap((member) => declared(Schema.make(member)));
+	return [HttpApiSchema.status(422)(error)];
+};
+const declaredResponse = (errors, error) => {
+	const schema = errors.flatMap(declared).find((each) => Schema.is(each)(error));
+	return schema === void 0 ? void 0 : HttpServerResponse.jsonUnsafe(Schema.encodeUnknownSync(Schema.toCodecJson(schema))(error), { status: httpApiStatusOf(schema.ast) ?? 422 });
+};
+//#endregion
+export { declared, declaredResponse };

package/dist/http/schema-errors.mjs

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

package/dist/mcp/protocol.d.mts

@@ -0,0 +1,17 @@
+import "../contract/implementation.mjs";
+import "../contract/media.mjs";
+import "../Action.mjs";
+import { Schema } from "effect";
+import { McpProtocol } from "effect/ai";
+//#region src/mcp/protocol.d.ts
+/**
+ * An MCP request's parameters, as `Testing.mcpRequest` takes them: JSON, with any `_meta`, leaving
+ * out an `undefined` one, as a caller may.
+ */
+export interface Params {
+  readonly _meta?: {
+    readonly [key: string]: Schema.Json;
+  };
+  readonly [key: string]: Schema.Json | undefined;
+}
+//#endregion