@gjermundgaraba/effect-actions 0.10.0 → 0.12.0

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

package/dist/mcp/protocol.mjs

@@ -0,0 +1,149 @@
+import { unsuspended } from "../contract/rules.mjs";
+import { Media, isMarked, kindOf } from "../contract/media.mjs";
+import { Predicate, Schema, SchemaAST } from "effect";
+import { McpProtocol } from "effect/ai";
+//#region src/mcp/protocol.ts
+const httpProtocol = McpProtocol.v2026_07_28;
+const protocols = [
+	McpProtocol.v2026_07_28,
+	McpProtocol.v2025_11_25,
+	McpProtocol.v2025_06_18
+];
+const defaultPath = "/mcp";
+const mcpNameHeaderOf = (method, params) => method === "resources/read" ? params.uri : params.name;
+/**
+* One stateless MCP request of `method` with `params`, as `ActionMcp.layerHttp` serves it:
+* the headers routing it, which repeat what its body says, and its JSON-RPC body. The client
+* metadata goes in `_meta`, under any given, such as a `progressToken`; the protocol version
+* is always the request's own.
+*/
+const statelessRequest = (method, params) => {
+	const { protocolVersion } = httpProtocol;
+	const name = mcpNameHeaderOf(method, params);
+	return {
+		headers: {
+			accept: "application/json, text/event-stream",
+			"mcp-protocol-version": protocolVersion,
+			"mcp-method": method,
+			...Predicate.isString(name) ? { "mcp-name": name } : {}
+		},
+		body: {
+			jsonrpc: "2.0",
+			id: 1,
+			method,
+			params: {
+				...params,
+				_meta: {
+					"io.modelcontextprotocol/clientCapabilities": {},
+					"io.modelcontextprotocol/clientInfo": {
+						name: "effect-actions",
+						version: "0"
+					},
+					...params._meta,
+					"io.modelcontextprotocol/protocolVersion": protocolVersion
+				}
+			}
+		}
+	};
+};
+const fieldKey = "effect-actions/field";
+const isMedia = Schema.is(Media);
+const isMediaArray = Schema.is(Schema.Array(Media));
+const kindOfUnsuspended = (ast) => kindOf(unsuspended(ast));
+const wholeSuccessMediaOf = (suspended) => {
+	const ast = unsuspended(suspended);
+	const one = kindOf(ast);
+	if (one !== void 0) return {
+		kind: one,
+		many: false
+	};
+	if (!SchemaAST.isArrays(ast) || ast.encoding !== void 0) return void 0;
+	const [kind, ...others] = new Set([...ast.elements, ...ast.rest].map(kindOfUnsuspended));
+	return kind === void 0 || others.length > 0 ? void 0 : {
+		kind,
+		many: true
+	};
+};
+const mediaFieldOf = (field) => {
+	const optional = field.context?.isOptional === true;
+	const ast = unsuspended(field);
+	if (optional && SchemaAST.isUnion(ast) && ast.types.length === 2) {
+		const [definedMember, ...otherDefinedMembers] = ast.types.filter((member) => !SchemaAST.isUndefined(member));
+		const kind = definedMember === void 0 || otherDefinedMembers.length > 0 ? void 0 : kindOfUnsuspended(definedMember);
+		return kind === void 0 ? void 0 : {
+			kind,
+			many: false
+		};
+	}
+	const whole = wholeSuccessMediaOf(ast);
+	return whole === void 0 || optional && whole.many ? void 0 : whole;
+};
+const liftOf = (success) => {
+	const ast = unsuspended(success.ast);
+	const whole = wholeSuccessMediaOf(ast);
+	if (whole !== void 0) return {
+		fields: [{
+			name: void 0,
+			...whole
+		}],
+		rest: void 0
+	};
+	if (!SchemaAST.isObjects(ast) || ast.encoding !== void 0) return {
+		fields: [],
+		rest: success
+	};
+	const fields = ast.propertySignatures.flatMap(({ name, type }) => {
+		const field = mediaFieldOf(type);
+		return field === void 0 ? [] : [{
+			name: String(name),
+			...field
+		}];
+	});
+	if (fields.length === 0) return {
+		fields,
+		rest: success
+	};
+	const names = new Set(fields.map(({ name }) => name));
+	const rest = ast.propertySignatures.filter(({ name }) => !names.has(name));
+	const { identifier: _identifierOfWholeSuccess, ...annotationsOfRest } = ast.annotations ?? {};
+	return {
+		fields,
+		rest: rest.length === 0 && ast.indexSignatures.length === 0 ? void 0 : Schema.make(new SchemaAST.Objects(rest, ast.indexSignatures, annotationsOfRest))
+	};
+};
+const partsAndEncodedSideOf = (ast) => [
+	...SchemaAST.isDeclaration(ast) ? ast.typeParameters : [],
+	...SchemaAST.isArrays(ast) ? [...ast.elements, ...ast.rest] : [],
+	...SchemaAST.isObjects(ast) ? [...ast.propertySignatures, ...ast.indexSignatures].map(({ type }) => type) : [],
+	...SchemaAST.isUnion(ast) ? ast.types : [],
+	...SchemaAST.isSuspend(ast) ? [ast.thunk()] : [],
+	...(ast.encoding ?? []).map(({ to }) => to)
+];
+const holdsMediaAnywhere = (ast) => {
+	const seen = /* @__PURE__ */ new Set();
+	const pending = [ast];
+	for (let next = pending.pop(); next !== void 0; next = pending.pop()) {
+		if (seen.has(next)) continue;
+		seen.add(next);
+		if (isMarked(next)) return true;
+		pending.push(...partsAndEncodedSideOf(next));
+	}
+	return false;
+};
+const isMisplaced = (action, { rest }) => {
+	return [
+		action.input,
+		...action.error,
+		...rest === void 0 ? [] : [rest]
+	].some(({ ast }) => holdsMediaAnywhere(ast));
+};
+const liftedFrom = (lift, success) => lift.fields.flatMap(({ name, kind, many }) => {
+	const value = name === void 0 ? success : Predicate.hasProperty(success, name) ? success[name] : void 0;
+	return (many ? isMediaArray(value) ? value : [] : isMedia(value) ? [value] : []).map((media) => ({
+		kind,
+		field: name,
+		value: media
+	}));
+});
+//#endregion
+export { defaultPath, fieldKey, httpProtocol, isMisplaced, liftOf, liftedFrom, protocols, statelessRequest };