@gjermundgaraba/effect-actions 0.11.0 → 0.13.0

package/dist/ActionRpc.mjs

@@ -0,0 +1,113 @@
+import { InvalidInput } from "./contract/errors.mjs";
+import { Anyone, assertDistinct, assertOnce, assertOwnTags, errorList, projectedErrors } from "./contract/rules.mjs";
+import { acquire, provideHandlers, servedBy, toList } from "./contract/implementation.mjs";
+import { checked } from "./contract/call.mjs";
+import { assertAuthentication, providerOf, withVerifierErrors } from "./authentication/provider.mjs";
+import { Cause, Effect, ErrorReporter, Layer, Predicate, Result, Schema, SchemaTransformation } from "effect";
+import { HttpClientRequest, HttpServerRequest } from "effect/http";
+import { HttpApiBuilder } from "effect/http-api";
+import { Rpc, RpcClient, RpcGroup, RpcSerialization, RpcServer } from "effect/rpc";
+//#region src/rpc/ActionRpc.ts
+const declaredErrorsOf = (action, errors, authentication) => projectedErrors(action, withVerifierErrors(action, errors, authentication?.error));
+function make(actions, options = {}) {
+	assertOnce("action", actions);
+	const errors = errorList(options.error);
+	assertOwnTags("ActionRpc binding", errors);
+	assertAuthentication(actions, options.authentication);
+	return {
+		actions,
+		error: errors,
+		group: RpcGroup.make(...actions.map((action) => Rpc.make(action.name, {
+			payload: action.input,
+			success: action.success,
+			error: Schema.Union(declaredErrorsOf(action, errors, options.authentication))
+		}))),
+		authentication: options.authentication
+	};
+}
+const credentialFromRpcHeaders = (security, headers) => HttpApiBuilder.securityDecode(security).pipe(Effect.provideService(HttpServerRequest.HttpServerRequest, HttpServerRequest.fromClientRequest(HttpClientRequest.get("/", { headers }))), Effect.provideService(HttpServerRequest.ParsedSearchParams, {}));
+const authenticationStepOf = (authentication) => Effect.map(providerOf(authentication), (provider) => (effect, { headers }) => credentialFromRpcHeaders(authentication.security, headers).pipe(Effect.flatMap(provider.authenticate), Effect.flatMap((actor) => Effect.provideService(effect, authentication.identity, actor))));
+var InternalError = class extends Error {
+	[ErrorReporter.ignore] = true;
+	constructor() {
+		super("Internal server error");
+	}
+};
+var DeclaredFailure = class {
+	json;
+	[ErrorReporter.ignore] = true;
+	constructor(json) {
+		this.json = json;
+	}
+	toString() {
+		return Predicate.isString(this.json) ? this.json : JSON.stringify(this.json);
+	}
+};
+const DeclaredFromJson = Schema.Json.pipe(Schema.decodeTo(Schema.instanceOf(DeclaredFailure), SchemaTransformation.transform({
+	decode: (json) => new DeclaredFailure(json),
+	encode: (failure) => failure.json
+})));
+const callBoundaryOf = (error) => {
+	const encode = Schema.encodeUnknownEffect(Schema.toCodecJson(error));
+	const internal = (cause) => Effect.logError(cause).pipe(Effect.andThen(ErrorReporter.report(cause)), Effect.andThen(Effect.die(new InternalError())));
+	return (effect) => Effect.catchCause(effect, (cause) => {
+		if (Cause.hasDies(cause)) return internal(cause);
+		const failure = Cause.findFail(cause);
+		return Result.isSuccess(failure) ? encode(failure.success.error).pipe(Effect.matchCauseEffect({
+			onFailure: (unencoded) => internal(Cause.combine(cause, unencoded)),
+			onSuccess: (encoded) => Effect.fail(new DeclaredFailure(encoded))
+		})) : Effect.failCause(cause);
+	});
+};
+const handlerOf = (action, run, steps, error) => {
+	const decodeStrictly = Schema.decodeUnknownEffect(Schema.toCodecJson(action.input), {
+		errors: "all",
+		onExcessProperty: "error"
+	});
+	const encode = Schema.encodeUnknownEffect(Schema.toCodecJson(action.success));
+	const boundary = callBoundaryOf(error);
+	return (payload, options) => {
+		const call = Effect.suspend(() => decodeStrictly(payload)).pipe(Effect.mapError(InvalidInput.fromSchemaError), Effect.flatMap(run), Effect.flatMap(encode));
+		const wrapped = steps.reduce((inner, step) => Effect.suspend(() => step(inner, {
+			...options,
+			payload
+		})), call);
+		return boundary(wrapped);
+	};
+};
+function layer(binding, served, options = {}) {
+	const apps = servedBy("RPC binding", binding.actions, toList(served), options.actions);
+	const actions = apps.flatMap((app) => app.actions);
+	assertAuthentication(actions, binding.authentication);
+	const middleware = options.middleware ?? [];
+	assertDistinct("middleware", middleware, (key) => key.key);
+	const auth = actions.some((action) => action.caller !== Anyone) ? binding.authentication : void 0;
+	const jsonGroup = RpcGroup.make(...actions.map((action) => Rpc.make(action.name, {
+		payload: Schema.Json,
+		success: Schema.Json,
+		error: DeclaredFromJson
+	})));
+	const handlers = Layer.unwrap(Effect.gen(function* () {
+		const { codecFor } = yield* RpcServer.Protocol;
+		if (codecFor !== RpcSerialization.json.codecFor) return yield* Effect.die(/* @__PURE__ */ new Error("ActionRpc serves a protocol speaking JSON: RpcSerialization.layerJson, layerNdjson, layerJsonRpc or layerNdJsonRpc, not another codec, such as schema-binary's"));
+		const listedMiddleware = yield* Effect.forEach(middleware, (key) => Effect.service(key));
+		const authenticate = auth === void 0 ? void 0 : yield* authenticationStepOf(auth);
+		const bound = yield* acquire(apps);
+		const byName = Object.fromEntries(bound.map(([action, run]) => [action.name, handlerOf(action, run, action.caller === Anyone || authenticate === void 0 ? listedMiddleware : [...listedMiddleware, authenticate], Schema.Union(declaredErrorsOf(action, binding.error, binding.authentication)))]));
+		return jsonGroup.toLayer(byName);
+	})).pipe(provideHandlers(apps));
+	return RpcServer.layer(jsonGroup, { disableFatalDefects: true }).pipe(Layer.provide(handlers));
+}
+function client(binding, options) {
+	const group = binding.group;
+	return Effect.map(RpcClient.make(group, options), (client) => {
+		const native = client;
+		return Object.fromEntries(binding.actions.map((action) => {
+			const method = native[action.name];
+			if (method === void 0) throw new Error(`No client method for ${action.name}`);
+			return [action.name, checked(action, (payload) => method(payload))];
+		}));
+	});
+}
+//#endregion
+export { client, layer, make };

package/dist/ActionToolkit.d.mts

@@ -1,20 +1,15 @@
-import { BuiltIns } from "./internal/errors.mjs";
-import { ActionOf, BuildError, BuildServices, Holding, Known, Member, Offered, OptionalUnless, RequestOf, SelectedOf, Served, Serving } from "./internal/implementation.mjs";
+import { BuiltIns } from "./contract/errors.mjs";
+import { ActionOf, BuildError, BuildServices, Holding, Known, Member, Offered, OptionalUnless, RequestOf, SelectedOf, Served, Serving } from "./contract/implementation.mjs";
 import { Action_d_exports, Any } from "./Action.mjs";
 import { Effect, Layer, Schema } from "effect";
-import { Tool, Toolkit } from "effect/ai";
-//#region src/ActionToolkit.d.ts
-/** A native tool named after its action, taking and giving JSON. */
+import { Prompt, Tool, Toolkit } from "effect/ai";
+//#region src/toolkit/ActionToolkit.d.ts
 type NativeTool<A extends Any, R> = Tool.Tool<A["name"], {
   readonly parameters: Schema.toCodecJson<A["input"]>;
   readonly success: Schema.toCodecJson<A["success"]>;
   readonly failure: Schema.toCodecJson<Schema.Union<ReadonlyArray<A["error"][number] | BuiltIns>>>;
   readonly failureMode: "return";
 }, R>;
-/**
- * The tool of each action of `App` among `Listed`. A tool needs what its handler and its
- * implementation's authorization need.
- */
 type ToolFor<App, Listed extends Any> = App extends unknown ? Serving<App, Listed> extends (infer A extends Any) ? A extends Any ? NativeTool<A, RequestOf<App, A>> : never : never : never;
 /**
  * Native tools bound to their action implementations: a native `Toolkit` and the layer of
@@ -64,6 +59,30 @@ export interface Options<A extends Any> {
  * when the resulting toolkit handles a call, the identity an implementation's `authorize`
  * reads included: the caller provides it. `needsApproval` marks the calls a model must have
  * approved; it authorizes nothing, which stays `authorize`'s.
+ * Guide: `docs/ActionToolkit.md` in this package; a loop served behind a route, with approval:
+ * `examples/kitchen-sink/src/assistant/`.
  */
 export declare function make<const Apps extends Served, const O extends Options<ActionOf<Member<Apps>>> = {}>(implementations: Apps, ...options: OptionalUnless<O, Options<ActionOf<Member<Apps>>> & O & NoInfer<Known<O, Options<Any>>>>): Tools<{ readonly [T in ToolFor<Member<Apps>, Offered<O, ActionOf<Member<Apps>>>> as T["name"]]: T; }, BuildError<Holding<Member<Apps>, SelectedOf<O, Apps>>, SelectedOf<O, Apps>>, BuildServices<Holding<Member<Apps>, SelectedOf<O, Apps>>, SelectedOf<O, Apps>>>;
+/** A tool call a model asked to have approved, which no answer has resolved yet. */
+export interface Approval {
+  /** What a `tool-approval-response` names to answer it. */
+  readonly approvalId: string;
+  readonly toolCallId: string;
+  /** The tool's name, the action's. */
+  readonly name: string;
+  /** The call's arguments as the model sent them: show them as JSON. */
+  readonly params: unknown;
+}
+/**
+ * The approval requests still open in a conversation's history, such as a `Chat`'s, in the
+ * order they were asked: those with neither an answer nor a tool result. An answer recorded
+ * without a result, as a `streamText` turn that failed while its call ran leaves it, is not
+ * open: the next turn acts on it unasked, and another answer would run the call twice. A turn's
+ * response lists only the requests that turn made, and the answering turn's none, so read every
+ * open one here. Each names the call an answer would run, found as Effect finds it: the last
+ * request with its `approvalId`, listed where it was asked, and the last call with its id.
+ * Guide: `docs/ActionToolkit.md` in this package; in an application:
+ * `examples/kitchen-sink/src/assistant/handlers.ts`.
+ */
+export declare const openApprovals: ({ content: messages }: Prompt.Prompt) => ReadonlyArray<Approval>;
 //#endregion

package/dist/ActionToolkit.mjs

@@ -1,6 +1,6 @@
-import { Implementation, provideHandlers, select, toList } from "./internal/implementation.mjs";
-import { bindTools } from "./internal/tools.mjs";
-//#region src/ActionToolkit.ts
+import { Implementation, provideHandlers, select, toList } from "./contract/implementation.mjs";
+import { bindTools } from "./toolkit/tools.mjs";
+//#region src/toolkit/ActionToolkit.ts
 function make(apps, options) {
 	const served = select(toList(apps), options?.actions);
 	const needsApproval = options?.needsApproval;
@@ -17,5 +17,32 @@ function make(apps, options) {
 		layer: layer.pipe(provideHandlers(served))
 	};
 }
+/**
+* The approval requests still open in a conversation's history, such as a `Chat`'s, in the
+* order they were asked: those with neither an answer nor a tool result. An answer recorded
+* without a result, as a `streamText` turn that failed while its call ran leaves it, is not
+* open: the next turn acts on it unasked, and another answer would run the call twice. A turn's
+* response lists only the requests that turn made, and the answering turn's none, so read every
+* open one here. Each names the call an answer would run, found as Effect finds it: the last
+* request with its `approvalId`, listed where it was asked, and the last call with its id.
+* Guide: `docs/ActionToolkit.md` in this package; in an application:
+* `examples/kitchen-sink/src/assistant/handlers.ts`.
+*/
+const openApprovals = ({ content: messages }) => {
+	const said = messages.flatMap((message) => message.role === "assistant" ? message.content : []);
+	const told = messages.flatMap((message) => message.role === "tool" ? message.content : []);
+	const answered = new Set(told.flatMap((part) => part.type === "tool-approval-response" ? [part.approvalId] : []));
+	const ran = new Set(told.flatMap((part) => part.type === "tool-result" ? [part.id] : []));
+	const calls = new Map(said.flatMap((part) => part.type === "tool-call" ? [[part.id, part]] : []));
+	return said.filter((part) => part.type === "tool-approval-request").filter(({ approvalId }, place, all) => all.findLastIndex((later) => later.approvalId === approvalId) === place).flatMap(({ approvalId, toolCallId }) => {
+		const call = calls.get(toolCallId);
+		return call === void 0 || answered.has(approvalId) || ran.has(toolCallId) ? [] : [{
+			approvalId,
+			toolCallId,
+			name: call.name,
+			params: call.params
+		}];
+	});
+};
 //#endregion
-export { make };
+export { make, openApprovals };

package/dist/Authentication.d.mts

@@ -1,12 +1,12 @@
-import { Refusal } from "./internal/errors.mjs";
-import { Known, OptionalUnless } from "./internal/implementation.mjs";
+import { ErrorsOf } from "./contract/rules.mjs";
+import { Refusal } from "./contract/errors.mjs";
+import { Known, OptionalUnless } from "./contract/implementation.mjs";
 import { Errors } from "./Action.mjs";
-import { Any, Descriptor, Provider, Security } from "./internal/authentication.mjs";
-import { ErrorsOf } from "./internal/declared.mjs";
+import { Any, Descriptor, Provider, Security } from "./authentication/provider.mjs";
 import { Array, Context, Effect, Layer, Option, Redacted, Scope } from "effect";
 import { HttpRouter, HttpServerResponse } from "effect/http";
 import { HttpApiSecurity } from "effect/http-api";
-//#region src/Authentication.d.ts
+//#region src/authentication/Authentication.d.ts
 /**
  * The bearer token of an `Authorization` header, `authorization`, or none, read as Effect's
  * `HttpApiSecurity.bearer` reads it for routes and MCP, which a test holds equal. It is for a
@@ -17,7 +17,10 @@ import { HttpApiSecurity } from "effect/http-api";
 export declare const bearerTokenOf: (authorization: string | null | undefined) => Option.Option<Redacted.Redacted<string>>;
 /** An OAuth protected resource (RFC 9728), as `layer` publishes it. */
 export interface ProtectedResource {
-  /** Exact OAuth resource identifier; its path and query select the discovery path. */
+  /**
+   * Exact OAuth resource identifier; its path and query select the discovery path. It has no
+   * fragment, which no request URL carries, so its discovery would never answer (RFC 9728).
+   */
   readonly resource: string;
   /** Where clients get tokens: nonempty. */
   readonly authorizationServers: Array.NonEmptyReadonlyArray<string>;
@@ -50,7 +53,6 @@ export interface RefusalResponseOptions<D extends Any = Any> {
    */
   readonly authorization?: string | null | undefined;
 }
-/** What the descriptor `D` declares its verifier fails with besides a refusal. */
 type DeclaredOf<D> = D extends {
   readonly error: infer E extends Errors;
 } ? E[number]["Type"] : never;
@@ -76,7 +78,6 @@ export interface Options {
    */
   readonly error?: Errors | Errors[number];
 }
-/** The scheme options `O` give: Bearer too wherever they may leave it out, as at run time. */
 type SecurityOf<O> = O extends {
   readonly security: infer S extends Security;
 } ? S : "security" extends keyof O ? NonNullable<O["security" & keyof O]> | HttpApiSecurity.Http : HttpApiSecurity.Http;
@@ -86,6 +87,7 @@ type SecurityOf<O> = O extends {
  * as `HttpApiSecurity.apiKey({ in: "cookie", key: "session" })`. The literal name
  * identifies the provider, like a native Context.Key name, and the scheme's OpenAPI key, so it
  * holds only letters, digits, `_`, `.` and `-`; reuse one name only for one declaration.
+ * Guide: `docs/Authentication.md` in this package; in an application: `examples/notes-service/src/identity/`.
  */
 export declare const make: <const Name extends string, I, A, const O extends Options = {}>(name: Name, identity: Context.Key<I, A>, ...options: OptionalUnless<O, O & NoInfer<Known<O, Options>>>) => Descriptor<I, A, SecurityOf<O>, Name, ErrorsOf<O>>;
 /**
@@ -97,21 +99,19 @@ export type Verify<A, S extends Security, R, E = never> = (credential: HttpApiSe
 export interface LayerOptions<EP = never, RP = never> {
   readonly protectedResource?: ProtectedResource | Effect.Effect<ProtectedResource | undefined, EP, RP>;
 }
-/**
- * Only a Bearer scheme publishes an OAuth protected resource. The types tell only an `Http`
- * scheme from the others, as its scheme is a `string`: `layer` refuses another `Http` one.
- */
 type ResourceOf<S> = [S] extends [HttpApiSecurity.Http] ? unknown : {
   readonly protectedResource?: undefined;
 };
+type Resource = ProtectedResource | Effect.Effect<ProtectedResource | undefined, unknown, unknown> | undefined;
 /**
  * The provider of `authentication`: `verify`, or an Effect building it once per layer graph, run on
  * each remote request a protected action receives, with the credential the descriptor's
  * scheme decodes. A Bearer scheme answers each 401 with its challenge, and may publish the
- * OAuth protected resource `protectedResource`.
+ * OAuth protected resource `protectedResource`, on the `HttpRouter` it then requires.
  */
-export declare function layer<const Name extends string, I, A, const S extends Security, E extends Errors, R, EX = never, RX = never, EP = never, RP = never>(authentication: Descriptor<I, A, S, Name, E>, verify: Verify<NoInfer<A>, NoInfer<S>, R, NoInfer<E[number]["Type"]>> | Effect.Effect<Verify<NoInfer<A>, NoInfer<S>, R, NoInfer<E[number]["Type"]>>, EX, RX>, options?: LayerOptions<EP, RP> & ResourceOf<S>): Layer.Layer<Provider<I, Name>, EX | EP, HttpRouter.HttpRouter | Exclude<RX | RP, Scope.Scope> | HttpRouter.Request.From<"Requires", Exclude<R, HttpRouter.Provided>>>;
-/** The identity `I`, or none where it is erased to `unknown`. */
+export declare function layer<const Name extends string, I, A, const S extends Security, E extends Errors, R, EX = never, RX = never, P extends Resource = undefined>(authentication: Descriptor<I, A, S, Name, E>, verify: Verify<NoInfer<A>, NoInfer<S>, R, NoInfer<E[number]["Type"]>> | Effect.Effect<Verify<NoInfer<A>, NoInfer<S>, R, NoInfer<E[number]["Type"]>>, EX, RX>, options?: {
+  readonly protectedResource?: P;
+} & ResourceOf<S>): Layer.Layer<Provider<I, Name>, EX | Effect.Error<P>, ([P] extends [undefined] ? never : HttpRouter.HttpRouter) | Exclude<RX | Effect.Services<P>, Scope.Scope> | HttpRouter.Request.From<"Requires", Exclude<R, HttpRouter.Provided>>>;
 type Provides<I> = unknown extends I ? never : I;
 /**
  * What `protect` returns for a descriptor named `Name` authenticating the identity `I`: router

package/dist/Authentication.mjs

@@ -1,18 +1,13 @@
-import { Unauthenticated, scopeToken } from "./internal/errors.mjs";
-import { assertOwnTags, errorList } from "./internal/actions.mjs";
-import { declaredResponse } from "./internal/declared.mjs";
-import { answer, answerStepUp, bearer, challenge, isRefusal, isStepUp, plain } from "./internal/refusal.mjs";
+import { Unauthenticated, scopeToken } from "./contract/errors.mjs";
+import { assertOwnTags, errorList } from "./contract/rules.mjs";
+import { providerOf } from "./authentication/provider.mjs";
+import { answer, answerStepUp, bearer, challenge, isRefusal, isStepUp, plain } from "./authentication/refusal.mjs";
+import { declaredResponse } from "./http/declared.mjs";
 import { Context, Effect, Layer, Match, Option, Predicate, Redacted } from "effect";
 import { HttpEffect, HttpRouter, HttpServerRequest, HttpServerResponse } from "effect/http";
 import { HttpApiBuilder, HttpApiMiddleware, HttpApiSecurity } from "effect/http-api";
-//#region src/Authentication.ts
-/**
-* An `Authorization` header of the `Bearer` scheme, and its token, as Effect's own
-* `HttpApiSecurity.bearer` decodes a request's: the scheme, matched case-insensitively, one or
-* more spaces, then the rest of the header, whatever it holds, a tab included. The whitespace
-* around a header value is no part of it, and an HTTP parser strips it before any route reads it.
-*/
-const bearerScheme = /^[ \t]*Bearer +(.*[^ \t])[ \t]*$/i;
+//#region src/authentication/Authentication.ts
+const bearerAuthorizationHeader = /^[ \t]*Bearer +(.*[^ \t])[ \t]*$/i;
 /**
 * The bearer token of an `Authorization` header, `authorization`, or none, read as Effect's
 * `HttpApiSecurity.bearer` reads it for routes and MCP, which a test holds equal. It is for a
@@ -20,44 +15,24 @@ const bearerScheme = /^[ \t]*Bearer +(.*[^ \t])[ \t]*$/i;
 * own is authenticated by `protect`. The scheme is matched case-insensitively, as RFC 9110
 * requires, and the token is `Redacted`, as Effect's own decoder gives it.
 */
-const bearerTokenOf = (authorization) => Option.map(Option.fromNullishOr(bearerScheme.exec(authorization ?? "")?.[1]), (token) => Redacted.make(token));
-/**
-* The RFC 9728 metadata URL of `options`: `/.well-known/oauth-protected-resource` followed
-* by the resource's path, where MCP clients look when a 401 names no metadata URL.
-*/
-const metadataUrl = (options) => {
+const bearerTokenOf = (authorization) => Option.map(Option.fromNullishOr(bearerAuthorizationHeader.exec(authorization ?? "")?.[1]), (token) => Redacted.make(token));
+const metadataUrlOf = (options) => {
 	const resource = new URL(options.resource);
 	const url = new URL(resource);
 	url.pathname = `/.well-known/oauth-protected-resource${resource.pathname === "/" ? "" : resource.pathname}`;
 	return url;
 };
-/** What challenges about `options` name. */
 const namedOf = (options) => ({
 	scope: options?.scopesRequired?.join(" "),
-	metadataUrl: options === void 0 ? void 0 : metadataUrl(options).href
+	metadataUrl: options === void 0 ? void 0 : metadataUrlOf(options).href
 });
-/** Whether a request whose `Authorization` header is `authorization` presented a bearer token. */
-const tokenPresented = (authorization) => Option.isSome(bearerTokenOf(authorization));
-/**
-* The challenge of a 401: `Bearer`, naming the scopes a client requests and the metadata URL
-* where it finds its authorization server. A request that presented a bearer token is told
-* it is invalid, RFC 6750's `invalid_token`, on which a client may refresh its token before
-* it signs in again; one that presented none names no error code.
-*/
-const challengeOf = (named, presented) => bearer([
+const presentsBearerToken = (authorization) => Option.isSome(bearerTokenOf(authorization));
+const bearerChallengeOf = (named, presented) => bearer([
 	["error", presented ? "invalid_token" : void 0],
 	["scope", named.scope],
 	["resource_metadata", named.metadataUrl]
 ]);
-/**
-* Refuse a protected resource that cannot be published, as `layer` and `refusalResponse` both
-* do: one under a scheme other than Bearer (`oauth` false), a `scopesSupported` or
-* `scopesRequired` that is no list of OAuth scope tokens, as `Forbidden` refuses, and a
-* resource with a fragment, which no request URL carries, so its discovery would never answer
-* (RFC 9728). A resource an Effect builds is checked for its scheme alone, and for the rest
-* once built.
-*/
-const assertResource = (oauth, options) => {
+const assertPublishableResource = (oauth, options) => {
 	if (options === void 0) return;
 	if (!oauth) throw new Error("A protected resource is published only for a Bearer scheme");
 	if (Effect.isEffect(options)) return;
@@ -67,11 +42,7 @@ const assertResource = (oauth, options) => {
 	}
 	if (new URL(options.resource).href.includes("#")) throw new Error(`A protected resource has no fragment: ${options.resource}`);
 };
-/**
-* `response` as the routes of the authentication answer: `no-store` unless it states its
-* own caching, and a 401 challenged with `challenge` unless it names its own.
-*/
-const settle = (response, challenge) => HttpServerResponse.setHeaders(response, {
+const withNoStoreAndChallenge = (response, challenge) => HttpServerResponse.setHeaders(response, {
 	...response.headers["cache-control"] === void 0 ? { "cache-control": "no-store" } : {},
 	...challenge !== void 0 && response.status === 401 && response.headers["www-authenticate"] === void 0 ? { "www-authenticate": challenge } : {}
 });
@@ -89,32 +60,19 @@ const settle = (response, challenge) => HttpServerResponse.setHeaders(response,
 const refusalResponse = (error, options) => {
 	const authentication = options?.authentication;
 	const oauth = authentication === void 0 || isBearer(authentication.security);
-	assertResource(oauth, options?.protectedResource);
+	assertPublishableResource(oauth, options?.protectedResource);
 	const named = namedOf(options?.protectedResource);
-	const challenge = authentication !== void 0 && !oauth ? schemeChallenge(authentication.security, authentication.name) : challengeOf(named, tokenPresented(options?.authorization));
+	const challenge = authentication !== void 0 && !oauth ? nonBearerChallengeOf(authentication.security, authentication.name) : bearerChallengeOf(named, presentsBearerToken(options?.authorization));
 	if (!isRefusal(error)) {
 		const response = declaredResponse(authentication?.error ?? [], error);
 		if (response === void 0) throw new Error("Not a refusal, nor an error the authentication declares");
-		return settle(response, challenge);
+		return withNoStoreAndChallenge(response, challenge);
 	}
-	return settle(oauth ? answer(error, named.metadataUrl) : plain(error), challenge);
+	return withNoStoreAndChallenge(oauth ? answer(error, named.metadataUrl) : plain(error), challenge);
 };
-/**
-* Whether a request URL may resolve to a discovery path, which every other request skips
-* parsing: the URL parser copies `.well-known` as it is, removing only a tab or a newline. Node
-* refuses a target holding those before routing; a platform passing one through still parses.
-*/
-const mayDiscover = /\.well-known|[\t\n\r]/;
-/**
-* RFC 9728 discovery of `options` at its metadata URL, as global router middleware: it
-* answers before routing, so no route middleware, authentication included, ever covers it.
-* The metadata is public to every origin, as a browser client needs it after a 401: it
-* carries `Access-Control-Allow-Origin: *`, and discovery answers its own CORS preflight.
-* Where the host's CORS middleware runs before it, that policy answers the preflight and
-* adds its headers to reads, which keep the `*` where it sets no origin.
-*/
-const discovery = (options) => {
-	const discoveryUrl = metadataUrl(options);
+const mayResolveToDiscoveryPath = /\.well-known|[\t\n\r]/;
+const discoveryMiddleware = (options) => {
+	const discoveryUrl = metadataUrlOf(options);
 	const target = discoveryUrl.href.slice(discoveryUrl.origin.length);
 	const metadata = HttpServerResponse.jsonUnsafe({
 		resource: options.resource,
@@ -123,8 +81,7 @@ const discovery = (options) => {
 		scopes_supported: options.scopesSupported,
 		resource_name: options.resourceName
 	}, { headers: { "access-control-allow-origin": "*" } });
-	/** The preflight of a cross-origin read, allowing the headers it asks for. */
-	const preflight = (request) => {
+	const corsPreflight = (request) => {
 		const requested = request.headers["access-control-request-headers"];
 		return HttpServerResponse.empty({
 			status: 204,
@@ -139,46 +96,36 @@ const discovery = (options) => {
 		});
 	};
 	return (next) => Effect.flatMap(HttpServerRequest.HttpServerRequest, (request) => {
-		const targeted = mayDiscover.test(request.url) && URL.canParse(request.url, discoveryUrl.origin) && new URL(request.url, discoveryUrl.origin).href.slice(discoveryUrl.origin.length) === target;
+		const targeted = mayResolveToDiscoveryPath.test(request.url) && URL.canParse(request.url, discoveryUrl.origin) && new URL(request.url, discoveryUrl.origin).href.slice(discoveryUrl.origin.length) === target;
 		if (targeted && (request.method === "GET" || request.method === "HEAD")) return Effect.succeed(metadata);
-		if (targeted && request.method === "OPTIONS") return Effect.succeed(preflight(request));
+		if (targeted && request.method === "OPTIONS") return Effect.succeed(corsPreflight(request));
 		return next;
 	});
 };
-/**
-* What `layer` answers about the protected resource `options`, written once: its metadata
-* URL, each 401's challenge, to a request that presented a bearer token and to one that did
-* not, and its discovery, none without a resource.
-*/
-const answersOf = (options) => {
+const resourceAnswersOf = (options) => {
 	const named = namedOf(options);
 	return {
 		metadataUrl: named.metadataUrl,
-		invalid: challengeOf(named, true),
-		anonymous: challengeOf(named, false),
-		published: options === void 0 ? void 0 : discovery(options)
+		invalid: bearerChallengeOf(named, true),
+		anonymous: bearerChallengeOf(named, false),
+		published: options === void 0 ? void 0 : discoveryMiddleware(options)
 	};
 };
-/** Whether `security` is the Bearer scheme, the one OAuth challenges and discovery name. */
 const isBearer = (security) => Predicate.isTagged(security, "Http") && security.scheme.toLowerCase() === "bearer";
-/** What an OpenAPI component key may hold, and so a descriptor's name, which is its key. */
-const componentKey = /^[\w.-]+$/;
-/**
-* The challenge of a 401 under a scheme other than Bearer: the scheme an `Http` one names,
-* Basic with its realm, the descriptor's name; an API key has no scheme to name.
-*/
-const schemeChallenge = (security, name) => Match.value(security).pipe(Match.tag("Http", ({ scheme }) => challenge(scheme, [])), Match.tag("Basic", () => challenge("Basic", [["realm", name]])), Match.tag("ApiKey", () => void 0), Match.exhaustive);
+const openApiComponentKey = /^[\w.-]+$/;
+const nonBearerChallengeOf = (security, name) => Match.value(security).pipe(Match.tag("Http", ({ scheme }) => challenge(scheme, [])), Match.tag("Basic", () => challenge("Basic", [["realm", name]])), Match.tag("ApiKey", () => void 0), Match.exhaustive);
 /**
 * Browser-safe declaration shared by clients and remote surfaces: the `identity` it
 * authenticates, by the one native scheme `security`, Bearer unless it names another, such
 * as `HttpApiSecurity.apiKey({ in: "cookie", key: "session" })`. The literal name
 * identifies the provider, like a native Context.Key name, and the scheme's OpenAPI key, so it
 * holds only letters, digits, `_`, `.` and `-`; reuse one name only for one declaration.
+* Guide: `docs/Authentication.md` in this package; in an application: `examples/notes-service/src/identity/`.
 */
 const make = (name, identity, ...options) => {
 	const security = options[0]?.security ?? HttpApiSecurity.bearer;
 	const error = errorList(options[0]?.error);
-	if (!componentKey.test(name)) throw new Error(`Invalid authentication name: ${JSON.stringify(name)}, not an OpenAPI key`);
+	if (!openApiComponentKey.test(name)) throw new Error(`Invalid authentication name: ${JSON.stringify(name)}, not an OpenAPI key`);
 	assertOwnTags(`Authentication "${name}"`, error);
 	if (!Predicate.isTagged(security, "Http") && !Predicate.isTagged(security, "ApiKey") && !Predicate.isTagged(security, "Basic")) throw new Error("Authentication takes one native HttpApiSecurity scheme");
 	return {
@@ -191,27 +138,25 @@ const make = (name, identity, ...options) => {
 		"~verified": Context.Service(`effect-actions/Authentication/Verified/${name}`)
 	};
 };
-/** Whether `credential`, as a native scheme decodes it, holds anything: an absent one is empty. */
 const presented = (credential) => Redacted.isRedacted(credential) ? Redacted.value(credential) !== "" : credential.username !== "" || Redacted.value(credential.password) !== "";
 function layer(authentication, verify, options = {}) {
 	const { security } = authentication;
 	const oauth = isBearer(security);
 	const protectedResource = options.protectedResource;
-	assertResource(oauth, protectedResource);
+	assertPublishableResource(oauth, protectedResource);
 	const resource = Effect.isEffect(protectedResource) ? Effect.map(protectedResource, (built) => {
-		assertResource(oauth, built);
-		return answersOf(built);
-	}) : Effect.succeed(answersOf(protectedResource));
+		assertPublishableResource(oauth, built);
+		return resourceAnswersOf(built);
+	}) : Effect.succeed(resourceAnswersOf(protectedResource));
 	const missing = new Unauthenticated({ message: oauth ? "A bearer token is required." : "A credential is required." });
 	return Layer.effect(authentication["~provider"], Effect.gen(function* () {
-		const router = yield* HttpRouter.HttpRouter;
 		const { metadataUrl, invalid, anonymous, published } = yield* resource;
-		if (published !== void 0) yield* router.addGlobalMiddleware(published);
+		if (published !== void 0) yield* (yield* HttpRouter.HttpRouter).addGlobalMiddleware(published);
 		const verifier = Effect.isEffect(verify) ? yield* verify : verify;
 		if (!Predicate.isFunction(verifier)) return yield* Effect.die(/* @__PURE__ */ new Error("Missing verify: pass a verify function, or an Effect building one"));
 		const authenticate = (credential) => presented(credential) ? verifier(credential) : Effect.fail(missing);
-		const failed = HttpEffect.appendPreResponseHandler((_request, response) => Effect.succeed(HttpServerResponse.setHeader(response, "cache-control", "no-store")));
-		const challengeOf = (credential) => !oauth ? schemeChallenge(security, authentication.name) : presented(credential) ? invalid : anonymous;
+		const noStoreOnFailure = HttpEffect.appendPreResponseHandler((_request, response) => Effect.succeed(HttpServerResponse.setHeader(response, "cache-control", "no-store")));
+		const challengeOf = (credential) => !oauth ? nonBearerChallengeOf(security, authentication.name) : presented(credential) ? invalid : anonymous;
 		const refuse = (error) => isRefusal(error) ? Effect.succeed(oauth ? answer(error, metadataUrl) : plain(error)) : Effect.suspend(() => {
 			const response = declaredResponse(authentication.error, error);
 			return response === void 0 ? Effect.die(error) : Effect.succeed(response);
@@ -221,10 +166,11 @@ function layer(authentication, verify, options = {}) {
 			return Effect.matchEffect(authenticate(credential), {
 				onFailure: refuse,
 				onSuccess: (actor) => Effect.provideService(route, slot, actor)
-			}).pipe(Effect.onError(() => failed), HttpEffect.withPreResponseHandler((_request, response) => Effect.succeed(settle(response, challenge))));
+			}).pipe(Effect.onError(() => noStoreOnFailure), HttpEffect.withPreResponseHandler((_request, response) => Effect.succeed(withNoStoreAndChallenge(response, challenge))));
 		};
 		return {
 			descriptor: authentication,
+			authenticate,
 			middleware: { [authentication.name]: (route, { credential }) => verified(credential, route, authentication.identity) },
 			stepUp: (route) => oauth ? Effect.catchIf(route, isStepUp, (error) => Effect.succeed(answer(error, metadataUrl))) : route,
 			http: ((route, optional) => Effect.flatMap(HttpApiBuilder.securityDecode(security), (credential) => optional && !presented(credential) ? route : verified(credential, oauth ? answerStepUp(route, metadataUrl) : route, authentication["~verified"]))),
@@ -243,6 +189,6 @@ function layer(authentication, verify, options = {}) {
 * `layer(authentication, ...)`. An erased descriptor, `Any`, provides no service the types can
 * name: its identity is `unknown`, which would discharge every request service the route owes.
 */
-const protect = (authentication) => HttpRouter.middleware()(Effect.map(Effect.service(authentication["~provider"]), (runtime) => (route) => runtime.route(route)));
+const protect = (authentication) => HttpRouter.middleware()(Effect.map(providerOf(authentication), (runtime) => (route) => runtime.route(route)));
 //#endregion
 export { bearerTokenOf, layer, make, protect, refusalResponse };