@gjermundgaraba/effect-actions 0.9.0 → 0.10.0

package/dist/internal/errors.mjs

@@ -0,0 +1,79 @@
+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. */
+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
+});
+const standardIssues = SchemaIssue.makeFormatterStandardSchemaV1();
+/**
+* The request's input does not decode against the action's input. HTTP answers every such
+* request with it, its message the schema's own description of what is wrong, and `issues`
+* the same description an issue at a time, for a caller that points at a field. A handler
+* failing with it for input that decodes but cannot be served may name its own.
+*/
+var InvalidInput = class InvalidInput extends Schema.TaggedError()("InvalidInput", {
+	message: message("The input does not match the action's input."),
+	issues: Schema.Array(Issue).pipe(Schema.withConstructorDefault(Effect.succeed([])))
+}, { httpApiStatus: statuses.InvalidInput }) {
+	/**
+	* The `InvalidInput` for input that did not decode, as every surface answers it: the
+	* schema's message, and each of its issues by path, for code that decodes input of its own,
+	* such as a header or a route parameter. Neither carries a value of the input: decoding
+	* runs without `reportInput`, so no issue holds one to format. A symbol key is sent as its
+	* string form, `Symbol(name)`, as JSON has no symbols, which tells it from a string key of
+	* that name.
+	*/
+	static fromSchemaError = ({ issue, message }) => new InvalidInput({
+		message,
+		issues: standardIssues(issue).issues.map((found) => ({
+			path: (found.path ?? []).map((segment) => {
+				const key = Predicate.isPropertyKey(segment) ? segment : segment.key;
+				return Predicate.isSymbol(key) ? String(key) : key;
+			}),
+			message: found.message
+		}))
+	});
+};
+/** 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 `\`. */
+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.
+*/
+var Forbidden = class extends Schema.TaggedError()("Forbidden", {
+	message: message("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
+* running a handler. An error an action declares, such as a rate limit, is not a refusal. As a
+* schema, it tells a refusal apart: `Schema.is(Action.Refusal)(error)`.
+*/
+const Refusal = Schema.Union(refusals);
+/**
+* The failures every endpoint and tool declares beyond its action's own, and any handler may
+* fail with: bad input, and every refusal. No action or binding declares them itself.
+*/
+const builtIns = [InvalidInput, ...refusals];
+/** The built-in failures as one schema: `Schema.is(Action.BuiltIn)(error)`. */
+const BuiltIn = Schema.Union(builtIns);
+//#endregion
+export { BuiltIn, Forbidden, InvalidInput, Refusal, Unauthenticated, builtIns, scopeToken, statuses };

package/dist/internal/implementation.d.mts

@@ -1,49 +1,179 @@
+import { Anyone } from "./actions.mjs";
+import { Refusal } from "./errors.mjs";
 import { Action_d_exports, Any } from "../Action.mjs";
-import { Actions } from "./actions.mjs";
-import { Effect, Scope } from "effect";
+import { Context, Effect, Layer, Scope } from "effect";
 //#region src/internal/implementation.d.ts
-/** Decoded values at the adapter dispatch boundary. */
+/** Decoded values at the dispatch boundary every surface shares. */
 export type ErasedValue = Any["input"]["Type"];
-type ErasedHandler<R> = {
+export type ErasedHandler<R> = {
   handle(input: ErasedValue): Effect.Effect<ErasedValue, ErasedValue, R>;
 }["handle"];
-/** An adapter's erased view of a record of handlers with request requirements `R`. */
-export type Handlers<R> = Readonly<Record<string, ErasedHandler<R>>>;
-/** Per-request requirements of the handler selected by an action name. */
-export type HandlerContext<H, Name extends keyof H> = H[Name] extends ((input: never) => Effect.Effect<infer _A, infer _E, infer R>) ? R : never;
-/** The union of per-request requirements declared by a handler record. */
-export type HandlersContext<H> = { readonly [K in keyof H]: HandlerContext<H, K>; }[keyof H];
-/**
- * An acquired handler record for a group.
- *
- * The private field makes this class nominal: a structurally similar object,
- * including one made by spreading an implementation, is not an implementation.
- */
-export declare class Implementation<G extends Actions, H, EX, RX> {
+/** Authorization 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> {
+  readonly key: Context.Key<S, S>;
+  readonly layer: Layer.Layer<S, E, R>;
+}
+/**
+ * Actions bound to their handlers and their authorizer: everything one `Action.implement` call
+ * produced, one builder serving every surface.
+ * The private fields make this class nominal: a structurally similar object, including one made by
+ * spreading an implementation, is not an implementation. Its type parameters may be written
+ * out, as a package emitting declarations prints them: `A` its actions, `RequestServices` each
+ * action name's handler's per-request requirements, `EX` and `RX` the failures and services of
+ * its handlers' builder, `RA` what its authorizer reads per request, and `EAX` and `RAX` the
+ * failures and services of the authorizer's builder. Public-only selections do not acquire
+ * authorization. A plain authorization callback builds nothing.
+ */
+export declare class Implementation<A extends Any, RequestServices extends {
+  readonly [name: string]: unknown;
+}, EX, RX, RA = never, EAX = never, RAX = never> {
   #private;
-  /** The group whose exact handler record was built. */
-  readonly group: G;
-  private constructor();
-  /** Acquire the exact handler record in the adapter layer's scope. */
-  get build(): Effect.Effect<H, EX, RX | Scope.Scope>;
-  static make<G extends Actions, H, EX, RX>(group: G, build: Effect.Effect<H, EX, RX | Scope.Scope>): Implementation<G, H, EX, RX>;
+  /** The contracts this implementation answers. */
+  readonly actions: ReadonlyArray<A>;
+  /** Type-only: each action's handler's per-request requirements. */
+  readonly "~request": RequestServices;
+  /** Type-only: what building its handlers fails with. */
+  readonly "~buildError": EX;
+  /** Type-only: what building its handlers needs. */
+  readonly "~buildServices": RX;
+  /** Type-only: what its authorizer reads per request. */
+  readonly "~authorizeRequest": RA;
+  /** Type-only: what building its authorizer fails with. */
+  readonly "~authorizeBuildError": EAX;
+  /** Type-only: what building its authorizer needs. */
+  readonly "~authorizeBuildServices": RAX;
+  constructor(
+  /** The contracts this implementation answers. */
+  actions: ReadonlyArray<A>,
+  /** Builds each action paired with its handler: its own builder, or the one it shares. */
+  handlers: Memoized<Bound, EX, RX>,
+  /** Builds its authorizer. */
+  authorizer: Memoized<ErasedAuthorize, EAX, RAX>);
+  /** Select contracts while retaining their handlers, authorization and shared builder. */
+  static share(actions: ReadonlyArray<Any>, app: AnyImplementation): AnyImplementation;
+  /**
+   * The key of what runs a call of `app`'s actions: its handlers' memoized layer's, which each
+   * `implement` makes, so it is unique to the implementation. Every selection retains it.
+   */
+  static runKey(app: AnyImplementation): string;
+  /**
+   * The builders of `app`, its handlers' and its authorizer's, as a layer. Effect memoizes each
+   * by reference within one layer graph, so every surface serving `app` there, and every
+   * implementation sharing its builder, shares one run. Static, so it stays off the
+   * public instance type.
+   */
+  static layerOf(app: AnyImplementation): Layer.Layer<never, unknown, unknown>;
+  /**
+   * The actions of `app` with their handlers, behind its authorizer, from the context
+   * `layerOf(app)` provides.
+   */
+  static boundOf(app: AnyImplementation): Effect.Effect<Bound, never, unknown>;
+  /** `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. */
+export type AnyImplementation<A extends Any = Any> = Implementation<A, {
+  readonly [name: string]: unknown;
+}, unknown, unknown, unknown, unknown, unknown>;
+/** What a surface serves: one implementation, or a list of them. */
+export type Served = AnyImplementation | ReadonlyArray<AnyImplementation>;
+/** The implementations `S` stands for. */
+export type Member<S> = S extends ReadonlyArray<infer App> ? App : S;
+/** Options that may list actions of `A`, the shape every selecting surface's options share. */
+export interface Selection<A extends Any> {
+  readonly actions?: ReadonlyArray<A> | undefined;
 }
-/** Any nominal implementation of `G`, with its record and channels erased. */
-export type AnyImplementation<G extends Actions = Actions> = Implementation<G, any, any, any>;
-/** What hides an action from MCP and Toolkit types: an `mcp` type of exactly `false`. The one rule both use. */
-export type HiddenFromMcp = {
-  readonly mcp: false;
-};
-/**
- * Names of the actions of `G` a surface serves: all of them, less those matching
- * `Hidden`. An action whose `mcp` may be `false` at runtime does not match, so it keeps
- * its requirements.
- */
-type ServedNames<G extends Actions, Hidden> = Exclude<G["actions"][number], Hidden>["name"];
-/** Per-request requirements of the handlers a surface can invoke, or of a union of implementations. */
-export type RequestContext<App, Hidden = never> = App extends Implementation<infer G, infer H, any, any> ? { readonly [K in Extract<ServedNames<G, Hidden>, keyof H>]: HandlerContext<H, K>; }[Extract<ServedNames<G, Hidden>, keyof H>] : never;
-/** Handler-acquisition failures of the implementations a surface acquires, or of a union of them. */
-export type BuildError<App, Hidden = never> = App extends Implementation<infer G, any, infer EX, any> ? [ServedNames<G, Hidden>] extends [never] ? never : EX : never;
-/** Handler-acquisition requirements of the implementations a surface acquires, or of a union of them. */
-export type BuildContext<App, Hidden = never> = App extends Implementation<infer G, any, any, infer RX> ? [ServedNames<G, Hidden>] extends [never] ? never : RX : never;
+/**
+ * The actions options `O` select, of `All`: those its `actions` lists when it always lists
+ * them, and every one otherwise. Options whose `actions` may be absent, being optional or
+ * a union with options lacking it, select every action at run time, so they narrow nothing.
+ */
+export type Selected<O, All extends Any> = O extends {
+  readonly actions: ReadonlyArray<infer A extends Any>;
+} ? A : All;
+/** The actions options `O` select of the implementations `Apps` stand for. */
+export type SelectedOf<O, Apps extends Served> = Selected<O, ActionOf<Member<Apps>>>;
+/**
+ * The actions a client of options `O` offers methods for, of `All`: those `actions` may
+ * list, wherever some member of `O` may list them, as each is present whether the list is
+ * 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
+ * rather than ignored: options inferred whole, as a type parameter, skip TypeScript's own
+ * check, and `keyof` a union holds only the keys every member has.
+ */
+export type Known<O, Keys> = { readonly [K in Exclude<O extends unknown ? keyof O : never, keyof Keys>]?: never; };
+/**
+ * The parameters of an optional options argument of type `O`: required where `O` names what
+ * only a given argument holds, such as listed actions, so explicit type arguments cannot
+ * narrow what an omitted argument leaves whole.
+ */
+export type OptionalUnless<O, Given> = {} extends O ? [options?: Given] : [options: Given];
+/** The actions of the implementations a surface serves. */
+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
+ * them by identity: an action whose type either is assignable to, or is assigned by, one
+ * listed. So an implementation typed wider than its contract, or a list typed wider than its
+ * actions, an erased one included, still counts, and another contract of a listed name, which
+ * the surface leaves out beside an action it serves, does not.
+ */
+export type Serving<App, Listed extends Any> = ActionOf<App> extends (infer A extends Any) ? A extends unknown ? [A] extends [Listed] ? A : string extends A["name"] ? A : [Extract<A["name"], Listed["name"]>] extends [never] ? never : [Matches<A, Listed>] extends [never] ? never : A : never : never;
+/**
+ * What each implementation among `App` owes per request where a surface serving the actions
+ * `Listed` serves it: its authorizer's services, and the handlers' of the actions it serves.
+ */
+export type ServedRequest<App, Listed extends Any> = App extends unknown ? RequestOf<App, Serving<App, Listed>> : never;
+/** The implementations among `App` holding an action of `Listed`: those a surface builds. */
+export type Holding<App, Listed extends Any> = App extends unknown ? [Serving<App, Listed>] extends [never] ? never : App : never;
+/** 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"]>;
+/**
+ * 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
+ * stand for.
+ */
+export type RequestOf<App, A extends Any> = App extends {
+  readonly "~request": infer R;
+  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. */
+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.
+ */
+export type BuildServices<App, Listed extends Any = OwnActions<App>> = App extends {
+  readonly "~buildServices": infer RX;
+  readonly "~authorizeBuildServices": infer RAX;
+} ? RX | ([Protected<Serving<App, Listed>>] extends [never] ? never : RAX) : never;
 //#endregion

package/dist/internal/implementation.mjs

@@ -1,49 +1,167 @@
-import { Effect, Predicate } from "effect";
+import { Unauthenticated } from "./errors.mjs";
+import { Anyone } from "./actions.mjs";
+import { Array, Context, Effect, Layer, Option } from "effect";
 //#region src/internal/implementation.ts
 /**
-* An acquired handler record for a group.
-*
-* The private field makes this class nominal: a structurally similar object,
-* including one made by spreading an implementation, is not an implementation.
+* 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.
+*/
+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 {
+		key,
+		layer: Layer.effect(key, build)
+	};
+};
+/**
+* Actions bound to their handlers and their authorizer: everything one `Action.implement` call
+* produced, one builder serving every surface.
+* The private fields make this class nominal: a structurally similar object, including one made by
+* spreading an implementation, is not an implementation. Its type parameters may be written
+* out, as a package emitting declarations prints them: `A` its actions, `RequestServices` each
+* action name's handler's per-request requirements, `EX` and `RX` the failures and services of
+* its handlers' builder, `RA` what its authorizer reads per request, and `EAX` and `RAX` the
+* failures and services of the authorizer's builder. Public-only selections do not acquire
+* authorization. A plain authorization callback builds nothing.
 */
 var Implementation = class Implementation {
-	group;
-	#build;
-	constructor(group, build) {
-		this.group = group;
-		this.#build = build;
+	actions;
+	#handlers;
+	#authorizer;
+	constructor(actions, handlers, authorizer) {
+		this.actions = actions;
+		this.#handlers = handlers;
+		this.#authorizer = authorizer;
 	}
-	/** Acquire the exact handler record in the adapter layer's scope. */
-	get build() {
-		return this.#build;
+	/** Select contracts while retaining their handlers, authorization and shared builder. */
+	static share(actions, app) {
+		const source = Implementation.own(app);
+		return new Implementation(actions, source.#handlers, source.#authorizer);
 	}
-	static make(group, build) {
-		return new Implementation(group, build);
+	/**
+	* The key of what runs a call of `app`'s actions: its handlers' memoized layer's, which each
+	* `implement` makes, so it is unique to the implementation. Every selection retains it.
+	*/
+	static runKey(app) {
+		return Implementation.own(app).#handlers.key.key;
+	}
+	/**
+	* The builders of `app`, its handlers' and its authorizer's, as a layer. Effect memoizes each
+	* by reference within one layer graph, so every surface serving `app` there, and every
+	* implementation sharing its builder, shares one run. Static, so it stays off the
+	* public instance type.
+	*/
+	static layerOf(app) {
+		const source = Implementation.own(app);
+		return app.actions.some((action) => action.caller !== Anyone) ? Layer.merge(source.#handlers.layer, source.#authorizer.layer) : source.#handlers.layer;
+	}
+	/**
+	* The actions of `app` with their handlers, behind its authorizer, from the context
+	* `layerOf(app)` provides.
+	*/
+	static boundOf(app) {
+		const { actions } = app;
+		const source = Implementation.own(app);
+		return Effect.gen(function* () {
+			const bound = yield* source.#handlers.key;
+			const before = actions.some((action) => action.caller !== Anyone) ? yield* source.#authorizer.key : () => Effect.void;
+			return bound.filter(([action]) => actions.includes(action)).map(([action, handle]) => [action, dispatch(action, handle, before)]);
+		});
 	}
+	/** `app`, if this copy of the module made it; another installed copy's cannot be read. */
+	static own(app) {
+		if (!(#handlers in app)) throw new Error("Not an implementation made by this Action.implement: is effect-actions installed twice?");
+		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) {
+		const names = new Set(held.map(({ name }) => name));
+		throw new Error(`Listed in actions, but ${why}: ${missing.map(({ name }) => names.has(name) ? `${name} (another contract)` : name).join(", ")}`);
+	}
+};
+/**
+* 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));
+	return apps.flatMap((app) => {
+		const own = app.actions.filter((action) => listed.includes(action));
+		if (own.length === 0) return [];
+		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 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* () {
+		if (first === void 0) return [];
+		const current = yield* Effect.serviceOption(Layer.CurrentMemoMap);
+		const memoMap = Option.getOrElse(current, Layer.makeMemoMapUnsafe);
+		const scope = yield* Effect.scope;
+		const context = yield* Layer.buildWithMemoMap(Layer.mergeAll(first, ...rest), memoMap, scope);
+		return yield* Effect.provideContext(acquire(apps), context);
+	});
 };
 /**
-* Select the handler of a concrete action, once, when an adapter binds its acquired
-* record; `implement` has already refused a record without it. The returned function
-* invokes it: the surface's pre-handler hook runs first, outside the action's span, so a
-* refusal is attributed to the surface rather than to a handler that never ran.
-* `R` remains in the returned effect so transport layers cannot erase required
-* per-request services while assembling routes.
+* 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 = (group, action, handlers, before) => {
-	const handle = Object.hasOwn(handlers, action.name) ? handlers[action.name] : void 0;
-	if (!Predicate.isFunction(handle)) throw new Error(`No handler for ${group.name}.${action.name}`);
+const dispatch = (action, handle, before) => {
 	const attributes = {
-		"action.group": group.name,
 		"action.name": action.name,
-		"action.access": action.access
+		"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), `${group.name}.${action.name}`, {
+		const handled = Effect.withSpan(Effect.annotateLogs(Effect.suspend(() => handle(input)), attributes), action.name, {
 			captureStackTrace: false,
 			attributes
 		});
-		return before === void 0 ? handled : Effect.flatMap(before(action), () => handled);
+		return Effect.scoped(authentication.pipe(Effect.andThen(authorization), Effect.andThen(handled)));
 	};
 };
 //#endregion
-export { Implementation, dispatch };
+export { Implementation, acquire, assertHeld, builders, built, memoized, provideHandlers, select, toList, uniqueKey };

package/dist/internal/mcp.d.mts

@@ -0,0 +1,11 @@
+import { Schema } from "effect";
+import { McpProtocol } from "effect/ai";
+//#region src/internal/mcp.d.ts
+/** An MCP request's parameters: JSON, 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/internal/mcp.mjs

@@ -0,0 +1,52 @@
+import { Predicate } from "effect";
+import { McpProtocol } from "effect/ai";
+//#region src/internal/mcp.ts
+/**
+* The one protocol revision served over HTTP. 2026-07-28 is stateless: every request
+* stands alone. The stateful revisions keep a session per `initialize`, which the native
+* HTTP runtime never expires and which no identity owns. A mixed endpoint's gate relies on it
+* too: it decides from the routing headers, which the native runtime checks against the body
+* of a stateless request alone, so serving a stateful revision over HTTP would open the gate.
+*/
+const httpProtocol = McpProtocol.v2026_07_28;
+/** Where `ActionMcp.layerHttp` serves, and `Testing.mcpClient` calls, by default. */
+const defaultPath = "/mcp";
+/** The parameter a method's `mcp-name` header repeats, as the native runtime routes it. */
+const routed = (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 = routed(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
+				}
+			}
+		}
+	};
+};
+//#endregion
+export { defaultPath, httpProtocol, statelessRequest };

package/dist/internal/memory.d.mts

@@ -0,0 +1,6 @@
+import { Layer } from "effect";
+import { HttpClient, HttpRouter, HttpServer } from "effect/http";
+//#region src/internal/memory.d.ts
+/** What in-memory routes may leave to the host: the router, the platform, nothing per request. */
+export type Served = HttpRouter.HttpRouter | HttpRouter.Request<"Requires", never> | HttpRouter.Request<"GlobalRequires", never> | HttpRouter.Request<"Error", any> | HttpRouter.Request<"GlobalError", any> | Layer.Success<typeof HttpServer.layerServices>;
+//#endregion

package/dist/internal/memory.mjs

@@ -0,0 +1,38 @@
+import { Effect, Layer, Predicate, Stream } from "effect";
+import { FetchHttpClient, HttpBody, HttpClient, HttpClientRequest } from "effect/http";
+//#region src/internal/memory.ts
+/** Where relative request URLs resolve, so a client needs no `baseUrl`. */
+const origin = "http://localhost/";
+/**
+* `request`, a streamed body turned into a web stream in the current context. The native client
+* turns it in its send, under the in-memory `fetch`, where another client the stream calls
+* would send to the routes too.
+*/
+const pulled = (request) => {
+	const body = request.body;
+	if (!Predicate.isTagged(body, "Stream")) return Effect.succeed(request);
+	return Effect.map(Stream.toReadableStreamEffect(body.stream), (readable) => HttpClientRequest.setBody(request, HttpBody.raw(readable, {
+		contentType: body.contentType,
+		contentLength: body.contentLength
+	})).pipe(HttpClientRequest.updateHeaders(() => request.headers)));
+};
+/**
+* The native `HttpClient`, sending every request to `handler` instead of the network. A
+* relative URL resolves against `http://localhost/`, as a page there would resolve it, and a
+* request carries the `Host` header of its URL, as one over the network does. The client is
+* its own: the program's other clients keep their `fetch`, and get none of its requests.
+*/
+const clientOf = (handler) => {
+	const fetch = (input, init) => {
+		const request = new Request(input, init);
+		if (!request.headers.has("host")) request.headers.set("host", new URL(request.url).host);
+		return handler(request);
+	};
+	return Layer.effect(HttpClient.HttpClient, Effect.map(HttpClient.HttpClient, (native) => HttpClient.makeWith((request) => Effect.flatMap(request, (mapped) => {
+		const resolved = URL.canParse(mapped.url) ? null : URL.parse(mapped.url, origin);
+		const sent = resolved === null ? mapped : HttpClientRequest.setUrl(mapped, resolved.href);
+		return Effect.flatMap(pulled(sent), (ready) => native.postprocess(Effect.succeed(ready)).pipe(Effect.provideService(FetchHttpClient.Fetch, fetch)));
+	}), native.preprocess))).pipe(Layer.provide(Layer.fresh(FetchHttpClient.layer)));
+};
+//#endregion
+export { clientOf };