@gjermundgaraba/effect-actions 0.19.0 → 0.21.0

package/dist/contract/hub.mjs

@@ -0,0 +1,133 @@
+import { makeLog, makeLogStore, memoryStorage } from "./log.mjs";
+import { Context, Effect, Layer, Queue, Stream } from "effect";
+// src/contract/hub.ts
+/** Revisions kept in memory, starting again, in a new epoch, with each call. */
+const memoryRevisions = () => {
+	const counts = /* @__PURE__ */ new Map();
+	return {
+		epoch: globalThis.crypto.randomUUID(),
+		get: (name) => Effect.sync(() => counts.get(name) ?? 0),
+		bump: (names) => Effect.sync(() => {
+			for (const name of names) counts.set(name, (counts.get(name) ?? 0) + 1);
+		})
+	};
+};
+const everyKey = (event) => event.name;
+const noKey = (event) => `${event.name}\u0000`;
+const ofKey = (event, key) => `${event.name}\u0000=${key}`;
+/**
+* Where an event's occurrences are announced as they happen: `notify` wakes the subscribers of a
+* check source to read now, and `publish` appends an occurrence to a log source, both reaching
+* the subscribers of one `key` or every one. Domain code yields it as it yields a store, and an
+* entrypoint provides one implementation: `Event.layerMemory`, kept in a process's memory.
+* Every surface serving events and `Action.client` watching them need it.
+*
+* **Gotchas**
+*
+* - The handlers announcing and the surfaces serving must share one, as they share a store: built separately, as a test building its handlers under a `provide` of their own does, each has its own, and an announcement reaches no subscriber of the other.
+* - An event no implementation attached here has no subscribers here: `publish` does nothing for it, and `notify` only moves its revision, so a current source attached later answers the change.
+* - `notify` of a log source and `publish` to a check source die naming the other: a check source reads your store, so write there and notify; a log source keeps what you publish.
+* - Implementations attach only to one `layerMemory` or `makeEvents` made: built over another, such as `Events.of` in a test, they die, naming both.
+*/
+var Events = class extends Context.Service()("effect-actions/Event/Events") {};
+const attached = /* @__PURE__ */ new WeakMap();
+/** How sources attach to `events`, the `Events` `makeEvents` made; one made otherwise dies. */
+const attachmentsOf = (events) => Effect.suspend(() => {
+	const attachments = attached.get(events);
+	return attachments === void 0 ? Effect.die(/* @__PURE__ */ new Error("This Event.Events serves no event implementation: provide Event.layerMemory, or one Event.makeEvents builds")) : Effect.succeed(attachments);
+});
+/** Whether an announcement to `target` reaches a subscriber of `key`: either absent means every one. */
+const reaches = (target, key) => target === void 0 || key === void 0 || target === key;
+const holding = (set, value) => Effect.acquireRelease(Effect.sync(() => {
+	set.add(value);
+	return value;
+}), () => Effect.sync(() => set.delete(value)));
+/**
+* An `Events` for as long as the scope lasts, over the log storage `log` makes: what a host keeping
+* logs elsewhere, such as a Durable Object's storage, provides as `Events`, its subscribers' wakes
+* in memory and its logs where `log` keeps them.
+*
+* **Gotchas**
+*
+* - Make it once per host, around the handlers that announce and the surfaces that serve, as `layerMemory` is built.
+* - A log's storage is made once per event for the life of the scope, its position read on every append and read: a storage emptied behind its back, as `storage.deleteAll` empties one, starts a new epoch, and a cursor from before reads a gap.
+*/
+const makeEvents = (options) => Effect.gen(function* () {
+	const polls = options.polls ?? true;
+	const emits = options.emits ?? true;
+	const revisions = options.revisions ?? memoryRevisions();
+	const scope = yield* Effect.scope;
+	const checks = /* @__PURE__ */ new Map();
+	const logs = /* @__PURE__ */ new Map();
+	const checkOf = (event) => {
+		const found = checks.get(event) ?? {
+			attached: /* @__PURE__ */ new Set(),
+			waiters: /* @__PURE__ */ new Set()
+		};
+		checks.set(event, found);
+		return found;
+	};
+	const isCheck = (event) => (checks.get(event)?.attached.size ?? 0) > 0;
+	const feed = (kept) => Effect.suspend(() => {
+		const [next] = kept.feeding ? [] : kept.waiting;
+		if (next === void 0) return Effect.void;
+		kept.waiting.delete(next);
+		kept.feeding = true;
+		const fed = Effect.andThen(kept.log.feed(Stream.map(next.emit, ({ key, ...value }) => ({
+			value,
+			key
+		}))), Effect.suspend(() => {
+			kept.feeding = false;
+			return feed(kept);
+		}));
+		return Effect.asVoid(Effect.forkIn(fed, scope));
+	});
+	const fedBy = (kept, emit) => Effect.tap(holding(kept.waiting, { emit }), () => feed(kept));
+	const events = Events.of({
+		notify: (event, notifyOptions) => Effect.suspend(() => {
+			if (!isCheck(event) && logs.has(event)) return Effect.die(/* @__PURE__ */ new Error(`Event "${event.name}" has a log source, which keeps what is published: give each occurrence to publish (Event.Events.publish(event, { data }))`));
+			const key = notifyOptions?.key;
+			return Effect.andThen(checks.get(event)?.current === false ? Effect.void : revisions.bump([everyKey(event), key === void 0 ? noKey(event) : ofKey(event, key)]), Effect.sync(() => {
+				for (const waiter of checkOf(event).waiters) if (reaches(key, waiter.key)) Queue.offerUnsafe(waiter.woken, void 0);
+			}));
+		}),
+		publish: (event, emitted, publishOptions) => Effect.suspend(() => {
+			const kept = logs.get(event);
+			if (kept !== void 0) return kept.log.append(emitted, publishOptions?.key);
+			return isCheck(event) ? Effect.die(/* @__PURE__ */ new Error(`Event "${event.name}" has a check source, which reads your store: write the occurrence there, then wake its subscribers (Event.Events.notify(event))`)) : Effect.void;
+		})
+	});
+	attached.set(events, {
+		check: (event, current) => Effect.map(holding(Object.assign(checkOf(event), { current }).attached, {}), () => ({
+			polls,
+			wakes: (key) => Effect.flatMap(Queue.sliding(1), (woken) => Effect.as(holding(checkOf(event).waiters, {
+				key,
+				woken
+			}), Queue.take(woken))),
+			revision: (key) => key === void 0 ? Effect.map(revisions.get(everyKey(event)), (count) => `${revisions.epoch}:${count}`) : Effect.map(Effect.all([revisions.get(noKey(event)), revisions.get(ofKey(event, key))]), ([unkeyed, keyed]) => `${revisions.epoch}:${unkeyed + keyed}:${key}`)
+		})),
+		log: (event, bounds, emit) => Effect.suspend(() => {
+			if (emit !== void 0 && !emits) return Effect.die(/* @__PURE__ */ new Error(`Event "${event.name}" has a log source fed by emit, which this Event.Events does not consume, as its host does not last between requests (publish each occurrence with Event.Events.publish as the host receives it, such as in a call or a route)`));
+			const kept = logs.get(event) ?? {
+				log: makeLog(makeLogStore(options.log(event), bounds)),
+				waiting: /* @__PURE__ */ new Set(),
+				feeding: false
+			};
+			logs.set(event, kept);
+			return Effect.as(emit === void 0 ? Effect.void : fedBy(kept, emit), kept.log);
+		})
+	});
+	return events;
+});
+/**
+* An `Events` kept in the memory of the process that builds it: for a server holding its
+* subscribers' connections itself, such as Node's, and for tests.
+*
+* **Gotchas**
+*
+* - Build it once, around the handlers that announce and the surfaces that serve, as a store is: each build is its own.
+* - A log lives as long as this build, through rebuilds of the implementations attached to it: a restart forgets it, and a subscriber resuming from one of its cursors receives a gap.
+* - Several builds of one log source share its log, and its `emit` feeds it from one build at a time, so nothing is appended twice.
+*/
+const layerMemory = Layer.effect(Events)(makeEvents({ log: () => memoryStorage() }));
+export { Events, attachmentsOf, layerMemory, makeEvents, reaches };

package/dist/contract/idempotency.d.mts

@@ -0,0 +1,47 @@
+import "./implementation.mjs";
+import "../Action.mjs";
+import { Context, Effect, Layer, Schema } from "effect";
+declare const Kept: Schema.Struct<{
+  readonly input: Schema.String;
+  readonly outcome: Schema.String;
+  readonly at: Schema.Finite;
+}>;
+type Kept = typeof Kept.Type;
+declare const Idempotency_base: Context.ServiceClass<Idempotency, "effect-actions/Action/Idempotency", {
+  /** What was kept under `id`, or `undefined`; one kept longer than 24 hours may be either. */
+  readonly get: (id: string) => Effect.Effect<Kept | undefined>;
+  /** Keeps `kept` under `id`, replacing what was. */
+  readonly set: (id: string, kept: Kept) => Effect.Effect<void>;
+}>;
+/**
+ * Where the answers of calls given an idempotency key are kept, by the action's name and a
+ * SHA-256 digest in hex of the key and its caller's principal, `<action>/<digest>`, for 24 hours
+ * at least: what an implementation of an action naming `idempotencyKey` requires at startup.
+ * `layerIdempotency` keeps them in memory; a Durable Object's `make` and `handlers` provide one
+ * over its storage; another store, shared by several servers, implements `get` and `set`, keeping
+ * `Idempotency.Kept` at least `Idempotency.keptFor` milliseconds.
+ *
+ * **Gotchas**
+ *
+ * - Provide one per server, around the surfaces: an implementation built in another layer graph keeps its own.
+ * - A server waits for a repeat's first call itself, in memory: two servers sharing a store run a call each, the later answer kept.
+ */
+export declare class Idempotency extends Idempotency_base {
+  /**
+   * What is kept of a call answered under its key: the digest of its input, its outcome as JSON,
+   * and when it was kept, in milliseconds since the epoch.
+   */
+  static readonly Kept: Schema.Struct<{
+    readonly input: Schema.String;
+    readonly outcome: Schema.String;
+    readonly at: Schema.Finite;
+  }>;
+  /** How long, in milliseconds, a kept answer is kept at least: 24 hours. */
+  static readonly keptFor: number;
+}
+/**
+ * `Idempotency` in the server's memory, each answer kept 24 hours after it was kept: lost when
+ * the server stops, and kept apart from every other server's.
+ */
+export declare const layerIdempotency: Layer.Layer<Idempotency>;
+export {};

package/dist/contract/idempotency.mjs

@@ -0,0 +1,99 @@
+import { CallerKeyed, principalOf } from "./caller.mjs";
+import { InvalidInput } from "./errors.mjs";
+import { declaredStatus, isTransientStatus } from "./status.mjs";
+import { projectedErrors } from "./declared.mjs";
+import { answered } from "./implementation.mjs";
+import { canonicalInput } from "./canonical.mjs";
+import { sha256Hex } from "./digest.mjs";
+import { Cause, Clock, Context, Deferred, Effect, Exit, Layer, Option, Predicate, Schema } from "effect";
+// src/contract/idempotency.ts
+const Kept = Schema.Struct({
+	input: Schema.String,
+	outcome: Schema.String,
+	at: Schema.Finite
+});
+const keptFor = 864e5;
+/**
+* Where the answers of calls given an idempotency key are kept, by the action's name and a
+* SHA-256 digest in hex of the key and its caller's principal, `<action>/<digest>`, for 24 hours
+* at least: what an implementation of an action naming `idempotencyKey` requires at startup.
+* `layerIdempotency` keeps them in memory; a Durable Object's `make` and `handlers` provide one
+* over its storage; another store, shared by several servers, implements `get` and `set`, keeping
+* `Idempotency.Kept` at least `Idempotency.keptFor` milliseconds.
+*
+* **Gotchas**
+*
+* - Provide one per server, around the surfaces: an implementation built in another layer graph keeps its own.
+* - A server waits for a repeat's first call itself, in memory: two servers sharing a store run a call each, the later answer kept.
+*/
+var Idempotency = class extends Context.Service()("effect-actions/Action/Idempotency") {
+	/**
+	* What is kept of a call answered under its key: the digest of its input, its outcome as JSON,
+	* and when it was kept, in milliseconds since the epoch.
+	*/
+	static Kept = Kept;
+	/** How long, in milliseconds, a kept answer is kept at least: 24 hours. */
+	static keptFor = keptFor;
+};
+/**
+* `Idempotency` in the server's memory, each answer kept 24 hours after it was kept: lost when
+* the server stops, and kept apart from every other server's.
+*/
+const layerIdempotency = Layer.sync(Idempotency)(() => {
+	const held = /* @__PURE__ */ new Map();
+	return Idempotency.of({
+		get: (id) => Effect.sync(() => held.get(id)),
+		set: (id, kept) => Effect.sync(() => {
+			held.delete(id);
+			held.set(id, kept);
+			for (const [oldest, { at }] of held) {
+				if (at > kept.at - keptFor) break;
+				held.delete(oldest);
+			}
+		})
+	});
+});
+/**
+* `handle`, answering a call given `action`'s idempotency key as the first call with it and the
+* same input was answered: from `store`, or, while that call runs, once it has.
+*/
+const keyed = (action, store, handle) => {
+	const field = action.idempotencyKey;
+	if (field === void 0) return handle;
+	const Outcome = Schema.fromJsonString(Schema.toCodecJson(Schema.Exit(action.success, Schema.Union(projectedErrors(action)), Schema.Never)));
+	const encodeOutcome = Schema.encodeUnknownEffect(Outcome);
+	const decodeOutcome = Schema.decodeUnknownOption(Outcome);
+	const isTransientFailure = Schema.is(Schema.Union(projectedErrors(action).filter((error) => isTransientStatus(declaredStatus(error)))));
+	const running = /* @__PURE__ */ new Map();
+	const run = (id, key, digest, answer) => Effect.gen(function* () {
+		const first = running.get(id);
+		if (first !== void 0) {
+			yield* Deferred.await(first).pipe(Effect.withSpan("Idempotency.wait", { attributes: { "action.name": action.name } }));
+			return yield* run(id, key, digest, answer);
+		}
+		const claim = Deferred.makeUnsafe();
+		running.set(id, claim);
+		const release = Effect.andThen(Effect.sync(() => running.delete(id)), Deferred.succeed(claim, void 0));
+		return yield* Effect.gen(function* () {
+			const kept = yield* store.get(id);
+			if (kept !== void 0 && kept.input !== digest) return yield* new InvalidInput({ message: `The idempotency key ${key} of ${action.name} was given with another input (send a new key for another call)` });
+			const replayed = kept === void 0 ? Option.none() : decodeOutcome(kept.outcome);
+			if (Option.isSome(replayed)) return yield* replayed.value;
+			const exit = yield* Effect.exit(answer);
+			const json = Exit.isSuccess(exit) || exit.cause.reasons.every((reason) => Cause.isFailReason(reason) && !isTransientFailure(reason.error)) ? yield* Effect.option(encodeOutcome(exit)) : Option.none();
+			if (Option.isSome(json)) yield* store.set(id, {
+				input: digest,
+				outcome: json.value,
+				at: yield* Clock.currentTimeMillis
+			});
+			return yield* exit;
+		}).pipe(Effect.ensuring(release));
+	});
+	return (input, reporting) => {
+		const key = Predicate.hasProperty(input, field) ? input[field] : void 0;
+		if (!Predicate.isString(key)) return handle(input, reporting);
+		const answer = Effect.suspend(() => answered(handle(input, reporting)));
+		return Effect.flatMap(Effect.all([Effect.service(CallerKeyed).pipe(Effect.flatMap((named) => principalOf(action, named)), Effect.flatMap((principal) => sha256Hex(JSON.stringify([principal ?? null, key])))), Effect.flatMap(canonicalInput(action.input, input), sha256Hex)]), ([id, digest]) => run(`${action.name}/${id}`, key, digest, answer));
+	};
+};
+export { Idempotency, keyed, layerIdempotency };

package/dist/contract/implementation.d.mts

@@ -1,28 +1,41 @@
-import { Anyone } from "./caller.mjs";
+import { Anyone, Keyed } from "./caller.mjs";
 import { Refusal } from "./errors.mjs";
-import { Any } from "../Action.mjs";
-import { Context, Effect, Layer, Scope } from "effect";
-//#region src/contract/implementation.d.ts
+import { AnyEventImplementation, EventOf } from "./feed.mjs";
+import { Any } from "../Event.mjs";
+import { Reporting } from "./progress.mjs";
+import { Any as Any$1 } from "../Action.mjs";
+import { Context, Effect, Layer, Scope, Stream } from "effect";
 /** Decoded values at the dispatch boundary every surface shares. */
-export type ErasedValue = Any["input"]["Type"];
+export type ErasedValue = Any$1["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.
+ * A handler as written, erased: its answer, or the stream of an action answering one. 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>;
+export type WrittenHandler<R> = {
+  handle(input: ErasedValue, reporting?: Reporting): Effect.Effect<ErasedValue, ErasedValue, R> | Stream.Stream<ErasedValue, ErasedValue, R>;
 }["handle"];
+/**
+ * A handler behind its action's authentication, authorization and declared errors, as a surface
+ * calls it. For an action answering a stream it succeeds at once with the call's stream, which
+ * `elementsOf` reads, the refusals included. `reporting` is where its progress goes, ignored for
+ * an action declaring no `progress`, so a surface may hand one to every call.
+ */
+export type ErasedHandler<R> = (input: ErasedValue, reporting?: Reporting) => Effect.Effect<ErasedValue, ErasedValue, R>;
 /**
  * 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>]>;
-interface Memoized<S, E, R> {
+export type Authorize<A extends Any$1, R = never> = (action: A) => Effect.Effect<void, Refusal, R>;
+/** An authorization rule over contracts `C`, erased: it refuses, or lets the call run. */
+export type ErasedAuthorize<C = Any$1> = (contract: C) => Effect.Effect<void, unknown, unknown>;
+/** Each action of an implementation with its handler, as `dispatch` makes it. */
+export type Bound = ReadonlyArray<readonly [Any$1, ErasedHandler<unknown>]>;
+/** Each action of an implementation with its handler as written, as its builder made them. */
+export type Written = ReadonlyArray<readonly [Any$1, WrittenHandler<unknown>]>;
+/** A build shared by every layer an implementation reaches, through the one key it is provided under. */
+export interface Memoized<S, E, R> {
   readonly key: Context.Key<S, S>;
   readonly layer: Layer.Layer<S, E, R>;
 }
@@ -35,12 +48,10 @@ interface Memoized<S, E, R> {
  * its handlers' builder, `RA` what its authorizer reads per request, and `EAX` and `RAX` the
  * failures and services of the authorizer's builder.
  */
-export declare class Implementation<A extends Any, RequestServices extends {
+export declare class Implementation<A extends Any$1, RequestServices extends {
   readonly [name: string]: unknown;
 }, EX, RX, RA = never, EAX = never, RAX = never> {
   #private;
-  /** The contracts this implementation answers. */
-  readonly actions: ReadonlyArray<A>;
   /** Type-only: each action's handler's request-time requirements. */
   readonly "~request": RequestServices;
   /** Type-only: what building its handlers fails with. */
@@ -53,15 +64,15 @@ export declare class Implementation<A extends Any, RequestServices extends {
   readonly "~authorizeBuildError": EAX;
   /** Type-only: what building its authorizer needs. */
   readonly "~authorizeBuildServices": RAX;
-  constructor(
   /** The contracts this implementation answers. */
-  actions: ReadonlyArray<A>,
+  readonly actions: readonly A[];
+  constructor(actions: readonly A[],
   /** Builds each action paired with its handler: its own builder, or the one it shares. */
-  handlers: Memoized<Bound, EX, RX>,
+  handlers: Memoized<Written, 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;
+  static share(actions: readonly Any$1[], 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.
@@ -77,7 +88,7 @@ export declare class Implementation<A extends Any, RequestServices extends {
    * 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>;
+  static boundOf(app: AnyImplementation, keyed: Keyed | undefined): Effect.Effect<Bound, never, unknown>;
   /** `app`, if this copy of the module made it; another installed copy's cannot be read. */
   private static own;
 }
@@ -88,43 +99,55 @@ export declare class Implementation<A extends Any, RequestServices extends {
  * 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, {
+export type AnyImplementation<A extends Any$1 = Any$1> = 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>;
+/** What a surface serves: one implementation, of actions or of events, or a list of them. */
+export type Served = AnyImplementation | AnyEventImplementation | ReadonlyArray<AnyImplementation | AnyEventImplementation>;
+/** What a surface serving no events takes: one action implementation, or a list of them. */
+export type ServedActions = AnyImplementation | readonly 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;
+/**
+ * Options that may list actions and event types of `C`, the shape every selecting surface's
+ * options share.
+ */
+export interface Selection<C extends Any$1 | Any> {
+  readonly actions?: readonly C[] | undefined;
 }
 /**
  * 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.
+ * them, none where it lists event types alone, 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;
+export type Selected<O, All extends Any$1> = O extends {
+  readonly actions: ReadonlyArray<infer C>;
+} ? Extract<C, Any$1> : All;
+/** The event types options `O` select, of `All`, as `Selected` selects actions. */
+export type SelectedEvents<O, All extends Any> = O extends {
+  readonly actions: ReadonlyArray<infer C>;
+} ? Extract<C, Any> : 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 {
+export type MiddlewareOf<O, L extends readonly 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>>>;
+/** The event types options `O` select of the implementations `Apps` stand for. */
+export type SelectedEventsOf<O, Apps extends Served> = SelectedEvents<O, EventOf<Member<Apps>>>;
 /**
- * The actions a client of options `O` offers methods for, of `All`: those `actions` may
+ * The actions or event types a client of options `O` offers, 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>;
+export type Offered<O, All extends Any$1 | Any> = [Listing<O>] extends [never] ? All : Extract<All, Listing<O> extends ReadonlyArray<infer C> ? C : never>;
 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
@@ -142,7 +165,7 @@ export type OptionalUnless<O, Given> = {} extends O ? [options?: Given] : [optio
 export type ActionOf<App> = App extends {
   readonly actions: ReadonlyArray<infer A>;
 } ? A : never;
-type Matches<A extends Any, Listed extends Any> = Listed extends Any ? [A] extends [Listed] ? true : [Listed] extends [A] ? true : never : never;
+type Matches<A extends Any$1, Listed extends Any$1> = Listed extends Any$1 ? [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
@@ -150,34 +173,34 @@ type Matches<A extends Any, Listed extends Any> = Listed extends Any ? [A] exten
  * 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;
+export type Serving<App, Listed extends Any$1> = ActionOf<App> extends (infer A extends Any$1) ? 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;
+export type ServedRequest<App, Listed extends Any$1> = 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;
+export type Holding<App, Listed extends Any$1> = App extends unknown ? [Serving<App, Listed>] extends [never] ? never : App : never;
+/** The protected members of a contract union, of actions or of events. */
+export type Protected<A extends Pick<Any$1, "caller">> = A extends unknown ? A["caller"] extends typeof Anyone ? never : A : never;
 type ServiceOf<K> = K extends Context.Key<infer I, unknown> ? I : never;
-type AuthenticationOf<A extends Any> = A["caller"] extends typeof Anyone ? never : ServiceOf<A["caller"]>;
+type AuthenticationOf<A extends Any$1> = 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 {
+export type RequestOf<App, A extends Any$1> = 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>;
+} ? A extends Any$1 ? [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$1>;
 /**
  * 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 {
+export type BuildError<App, Listed extends Any$1 = OwnActions<App>> = App extends {
   readonly "~buildError": infer EX;
   readonly "~authorizeBuildError": infer EAX;
 } ? EX | ([Protected<Serving<App, Listed>>] extends [never] ? never : EAX) : never;
@@ -185,9 +208,8 @@ export type BuildError<App, Listed extends Any = OwnActions<App>> = App extends
  * 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 {
+export type BuildServices<App, Listed extends Any$1 = OwnActions<App>> = App extends {
   readonly "~buildServices": infer RX;
   readonly "~authorizeBuildServices": infer RAX;
 } ? RX | ([Protected<Serving<App, Listed>>] extends [never] ? never : RAX) : never;
-//#endregion
 export {};