@gjermundgaraba/effect-actions 0.19.0 → 0.21.0

package/dist/contract/declared.mjs

@@ -1,13 +1,19 @@
-import { literalValues, members } from "./ast.mjs";
 import { Anyone, assertAuthentication } from "./caller.mjs";
+import { literalValues, members } from "./ast.mjs";
 import { builtIns } from "./errors.mjs";
-import { assertOnce } from "./names.mjs";
 import { httpApiStatusOf } from "./status.mjs";
 import { Predicate, Schema, SchemaAST } from "effect";
-//#region src/contract/declared.ts
-const errorList = (error) => error === void 0 ? [] : Schema.isSchema(error) ? [error] : error;
+// src/contract/declared.ts
+const errorList = (error) => {
+	if (error === void 0) return [];
+	return Schema.isSchema(error) ? [error] : error;
+};
 const ownsNothing = (ast) => httpApiStatusOf(ast) === void 0 && ast.checks === void 0 && ast.encoding === void 0;
-const schemasOf = (ast) => !ownsNothing(ast) ? [ast] : SchemaAST.isSuspend(ast) ? schemasOf(ast.thunk()) : SchemaAST.isUnion(ast) ? ast.types.flatMap(schemasOf) : [ast];
+const schemasOf = (ast) => {
+	if (!ownsNothing(ast)) return [ast];
+	if (SchemaAST.isSuspend(ast)) return schemasOf(ast.thunk());
+	return SchemaAST.isUnion(ast) ? ast.types.flatMap(schemasOf) : [ast];
+};
 /** `errors` as the schemas a call decodes a failure with, in order, each once. */
 const errorSchemas = (errors) => {
 	const schemas = /* @__PURE__ */ new Map();
@@ -24,6 +30,14 @@ const projectedErrors = (action, surface = []) => errorSchemas([
 * binding's and, where `action` is protected, its authentication's.
 */
 const bindingErrors = (action, binding) => projectedErrors(action, action.caller === Anyone || binding.authentication === void 0 ? binding.error : [...binding.error, ...binding.authentication.error]);
+/**
+* Every error a binding's subscription to `event` declares: the built-in ones, the binding's and,
+* where `event` is protected, its authentication's. An event type declares none of its own.
+*/
+const eventErrors = (event, binding) => bindingErrors({
+	error: [],
+	caller: event.caller
+}, binding);
 const encodedTags = (ast) => members(SchemaAST.toEncoded(ast)).flatMap((member) => {
 	const tag = SchemaAST.isObjects(member) ? member.propertySignatures.find((property) => property.name === "_tag")?.type : void 0;
 	return tag === void 0 ? [] : members(tag).flatMap(literalValues).filter(Predicate.isString);
@@ -38,18 +52,19 @@ const assertDistinctTags = (what, errors) => {
 	}
 };
 /**
-* The checks `ActionHttp.make` and `ActionRpc.make` share: each action once, the descriptor every
-* protected action names, and each call's errors distinct by `_tag`. Returns the binding's `error`, as a list, and `authentication`.
+* The checks `ActionHttp.make` and `ActionRpc.make` share: the descriptor every protected action
+* and event type names, and each call's and each subscription's errors distinct by `_tag`.
+* Returns the binding's `error`, as a list, and `authentication`.
 */
-const bindingOf = (what, actions, options) => {
-	assertOnce("action", actions);
+const bindingOf = (what, actions, events, options) => {
 	const bound = {
 		error: errorList(options.error),
 		authentication: options.authentication
 	};
 	assertAuthentication(actions, bound.authentication);
+	assertAuthentication(events, bound.authentication, "event");
 	for (const action of actions) assertDistinctTags(`${what} of "${action.name}"`, bindingErrors(action, bound));
+	for (const event of events) assertDistinctTags(`${what} of event "${event.name}"`, eventErrors(event, bound));
 	return bound;
 };
-//#endregion
-export { assertDistinctTags, bindingErrors, bindingOf, errorList, errorSchemas, projectedErrors };
+export { assertDistinctTags, bindingErrors, bindingOf, errorList, errorSchemas, eventErrors, projectedErrors };

package/dist/contract/digest.mjs

@@ -0,0 +1,6 @@
+import { Effect } from "effect";
+// src/contract/digest.ts
+const encoder = new TextEncoder();
+/** The SHA-256 of `text`, in hex. */
+const sha256Hex = (text) => Effect.promise(async () => Array.from(new Uint8Array(await crypto.subtle.digest("SHA-256", encoder.encode(text))), (byte) => byte.toString(16).padStart(2, "0")).join(""));
+export { sha256Hex };

package/dist/contract/errors.d.mts

@@ -1,5 +1,4 @@
 import { Schema } from "effect";
-//#region src/contract/errors.d.ts
 declare const Issue: Schema.Struct<{
   readonly path: Schema.$Array<Schema.Union<readonly [Schema.String, Schema.Finite]>>;
   readonly message: Schema.String;
@@ -16,7 +15,9 @@ declare const InvalidInput_base: Schema.Class<InvalidInput, Schema.TaggedStruct<
     readonly path: Schema.$Array<Schema.Union<readonly [Schema.String, Schema.Finite]>>;
     readonly message: Schema.String;
   }>>>;
-}>, import("effect/Cause").YieldableError>;
+}>, import("effect/Cause").YieldableError & {
+  readonly brand: unique symbol;
+}>;
 /**
  * The request's input does not decode against the action's input: its message is the schema's
  * own description of what is wrong, and `issues` the same an issue at a time, for a caller that
@@ -45,7 +46,9 @@ export declare class InvalidInput extends InvalidInput_base {
 }
 declare const Unauthenticated_base: Schema.Class<Unauthenticated, Schema.TaggedStruct<"Unauthenticated", {
   readonly message: Schema.withConstructorDefault<Schema.String>;
-}>, import("effect/Cause").YieldableError>;
+}>, import("effect/Cause").YieldableError & {
+  readonly brand: unique symbol;
+}>;
 /**
  * The caller is not authenticated: authentication refuses the credential, or an implementation's
  * `authorize` or a handler fails with it.
@@ -63,7 +66,9 @@ export declare class Unauthenticated extends Unauthenticated_base {
 declare const Forbidden_base: Schema.Class<Forbidden, Schema.TaggedStruct<"Forbidden", {
   readonly message: Schema.withConstructorDefault<Schema.String>;
   readonly scopes: Schema.optionalKey<Schema.NonEmptyArray<Schema.String>>;
-}>, import("effect/Cause").YieldableError>;
+}>, import("effect/Cause").YieldableError & {
+  readonly brand: unique symbol;
+}>;
 /**
  * The caller may not run this action: authentication refuses the credential, an
  * implementation's `authorize` refuses, or a handler fails with it. `scopes`, when given, are every OAuth scope the call needs: a refusal naming
@@ -100,5 +105,4 @@ export type BuiltIns = (typeof builtIns)[number];
 export declare const BuiltIn: Schema.Union<readonly [typeof InvalidInput, typeof Unauthenticated, typeof Forbidden]>;
 /** A built-in failure: `InvalidInput | Refusal`. */
 export type BuiltIn = (typeof BuiltIn)["Type"];
-//#endregion
 export { Issue };

package/dist/contract/errors.mjs

@@ -1,5 +1,5 @@
 import { Effect, Predicate, Schema, SchemaIssue } from "effect";
-//#region src/contract/errors.ts
+// src/contract/errors.ts
 const defaultedMessage = (fallback) => Schema.String.pipe(Schema.withConstructorDefault(Effect.succeed(fallback)));
 const Issue = Schema.Struct({
 	path: Schema.Array(Schema.Union([Schema.String, Schema.Finite])),
@@ -55,7 +55,7 @@ var InvalidInput = class InvalidInput extends Schema.TaggedError()("InvalidInput
 * - From another service's client, such as `ActionHttp.client`, one passed on tells a caller whose token is valid to sign in again: map it to an error the action declares, or to a defect.
 */
 var Unauthenticated = class extends Schema.TaggedError()("Unauthenticated", { message: defaultedMessage("Authentication is required.") }, { httpApiStatus: 401 }) {};
-const scopeToken = /^[\x21\x23-\x5B\x5D-\x7E]+$/;
+const scopeToken = /^[\u0021\u0023-\u005B\u005D-\u007E]+$/;
 const ScopeToken = Schema.String.check(Schema.isPattern(scopeToken));
 /**
 * The caller may not run this action: authentication refuses the credential, an
@@ -89,5 +89,4 @@ const Refusal = Schema.Union(refusals);
 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 };

package/dist/contract/feed.d.mts

@@ -0,0 +1,127 @@
+import { Anyone } from "./caller.mjs";
+import { Fed, Page } from "./pages.mjs";
+import { Any } from "../Event.mjs";
+import { ErasedAuthorize, ErasedValue, Memoized, Protected } from "./implementation.mjs";
+import { Context, Duration, Effect, Layer, Stream } from "effect";
+/**
+ * An implemented event type, behind its authorizer, as a surface serves it: a poll, whose
+ * subscription `subscriber` names, such as its principal, and a stream, which lasts as long as it
+ * is read. Both authenticate and authorize the subscriber first, and run as it.
+ */
+export interface Feed {
+  readonly event: Any;
+  /**
+   * Releases the `subscription` hook `subscriber`'s polls of `input` hold: present exactly where
+   * its source has a hook, held per subscriber.
+   */
+  readonly release?: ((input: ErasedValue, subscriber: string) => Effect.Effect<void>) | undefined;
+  /**
+   * Authenticates the subscriber, checks `input` by `Action.InputCheck` and authorizes it, as
+   * `poll` and `stream` do first.
+   */
+  readonly admit: (input: ErasedValue) => Effect.Effect<void, unknown, unknown>;
+  readonly poll: (input: ErasedValue, cursor: string | null, options: PollOptions) => Effect.Effect<Page, unknown, unknown>;
+  /**
+   * Admits the subscriber, then reads the feed from a cursor, as often as a subscription
+   * reopens it.
+   */
+  readonly stream: (input: ErasedValue) => Effect.Effect<(cursor: string | null) => Stream.Stream<Fed, unknown, unknown>, unknown, unknown>;
+}
+/** Who polls, and how many occurrences at most a log source's page holds. */
+export interface PollOptions {
+  readonly subscriber?: string | undefined;
+  /** Capped at the page a log source reads anyway; a check's page is answered whole. */
+  readonly maxEvents?: number | undefined;
+}
+/** What reads one event type's source, before its subscriber is admitted. */
+export interface Run extends Omit<Feed, "event" | "stream" | "admit"> {
+  readonly stream: (input: ErasedValue, cursor: string | null) => Stream.Stream<Fed, unknown, unknown>;
+}
+/**
+ * Each event of an implementation with what runs its source, each built on its own over the
+ * implementation's one builder, so a selection runs only the sources of the events it holds.
+ */
+export type Running<E = unknown, R = unknown> = ReadonlyArray<readonly [Any, Memoized<Run, E, R>]>;
+/**
+ * Event types bound to their sources and their authorizer: everything one `Event.implement` call
+ * produced. Its type parameters may be written out, as a package emitting declarations prints
+ * them: `E` its event types, `R` what its sources read per subscription, by event name, `EX` and `RX` the
+ * failures and services of its builder, `RA` what its authorizer reads per subscription, and
+ * `EAX` and `RAX` the failures and services of the authorizer's builder.
+ */
+export declare class EventImplementation<E extends Any, R, EX, RX, RA = never, EAX = never, RAX = never> {
+  #private;
+  /** Tells an event implementation from an action implementation among what a surface is given. */
+  readonly _tag = "EventImplementation";
+  /** Type-only: what its sources read per subscription, by event name. */
+  readonly "~eventRequest": R;
+  /** Type-only: what building its sources fails with. */
+  readonly "~eventBuildError": EX;
+  /** Type-only: what building its sources needs. */
+  readonly "~eventBuildServices": RX;
+  /** Type-only: what its authorizer reads per subscription. */
+  readonly "~eventAuthorizeRequest": RA;
+  /** Type-only: what building its authorizer fails with. */
+  readonly "~eventAuthorizeBuildError": EAX;
+  /** Type-only: what building its authorizer needs. */
+  readonly "~eventAuthorizeBuildServices": RAX;
+  /** The event types this implementation answers. */
+  readonly events: readonly E[];
+  constructor(events: readonly E[], running: Running<EX, RX>, authorizer: Memoized<ErasedAuthorize<Any>, EAX, RAX>);
+  /** Select event types while retaining their sources, authorization and shared builder. */
+  static share(events: readonly Any[], app: AnyEventImplementation): AnyEventImplementation;
+  /** The builders of `app`, its sources' and its authorizer's, as one layer. */
+  static layerOf(app: AnyEventImplementation): Layer.Layer<never, unknown, unknown>;
+  /** The event types of `app` with what runs them, behind its authorizer. */
+  static feedsOf(app: AnyEventImplementation): Effect.Effect<readonly Feed[], never, unknown>;
+  /** What runs each event type `app` holds. */
+  private static held;
+  private static own;
+}
+/** Any event implementation, with its events and channels erased. */
+export type AnyEventImplementation<E extends Any = Any> = EventImplementation<E, unknown, unknown, unknown, unknown, unknown, unknown>;
+/** The event types of the implementations `App`. */
+export type EventOf<App> = App extends {
+  readonly events: ReadonlyArray<infer E extends Any>;
+} ? E : never;
+type IdentityOf<K> = K extends Context.Key<infer I, unknown> ? I : never;
+type RequestOf<R, Name> = Name extends keyof R ? R[Name] : never;
+/**
+ * What a subscription of `E` owes per subscriber where the implementations `App` serve it: its
+ * sources' services, and for a protected event its authorizer's and the subscriber's identity.
+ */
+export type EventRequestOf<App, E extends Any> = App extends {
+  readonly events: ReadonlyArray<infer Held>;
+  readonly "~eventRequest": infer R;
+  readonly "~eventAuthorizeRequest": infer RA;
+} ? E extends Held ? RequestOf<R, E["name"]> | (E["caller"] extends typeof Anyone ? never : RA | IdentityOf<E["caller"]>) : never : never;
+/**
+ * The event types of `App` a surface given the event types `Listed` serves, as `selectEvents`
+ * selects them by identity: one whose type either is assignable to, or is assigned by, one
+ * listed, so an implementation or a list typed wider than its event types still counts.
+ */
+export type ServingEvents<App, Listed extends Any> = EventOf<App> extends (infer E extends Any) ? E extends unknown ? [E] extends [Listed] ? E : [Extract<Listed, E>] extends [never] ? never : E : never : never;
+/** The event implementations among `App` holding an event type of `Listed`: those a surface builds. */
+export type HoldingEvents<App, Listed extends Any> = App extends unknown ? [ServingEvents<App, Listed>] extends [never] ? never : App : never;
+type ServesProtected<App, Listed extends Any> = [Protected<ServingEvents<App, Listed>>] extends [never] ? false : true;
+/**
+ * What a remote surface's requests owe the event implementations `App` per subscription where it
+ * serves their event types of `Listed`: their sources' services, and their authorizer's where a
+ * served one is protected; the identity is the endpoint's own to provide.
+ */
+export type EventServedRequest<App, Listed extends Any = EventOf<App>> = App extends {
+  readonly "~eventRequest": infer R;
+  readonly "~eventAuthorizeRequest": infer RA;
+} ? [ServingEvents<App, Listed>] extends [never] ? never : EndpointRequest<R, ServingEvents<App, Listed>> | (ServesProtected<App, Listed> extends true ? Exclude<RA, IdentityOf<Protected<ServingEvents<App, Listed>>["caller"]>> : never) : never;
+type EndpointRequest<R, E extends Any> = E extends unknown ? E["caller"] extends typeof Anyone ? RequestOf<R, E["name"]> : Exclude<RequestOf<R, E["name"]>, IdentityOf<E["caller"]>> : never;
+/** What building the event implementations `App` fails with, where their event types of `Listed` are served. */
+export type EventBuildError<App, Listed extends Any = EventOf<App>> = App extends {
+  readonly "~eventBuildError": infer EX;
+  readonly "~eventAuthorizeBuildError": infer EAX;
+} ? [ServingEvents<App, Listed>] extends [never] ? never : EX | (ServesProtected<App, Listed> extends true ? EAX : never) : never;
+/** What building the event implementations `App` reads at startup, where their event types of `Listed` are served. */
+export type EventBuildServices<App, Listed extends Any = EventOf<App>> = App extends {
+  readonly "~eventBuildServices": infer RX;
+  readonly "~eventAuthorizeBuildServices": infer RAX;
+} ? [ServingEvents<App, Listed>] extends [never] ? never : RX | (ServesProtected<App, Listed> extends true ? RAX : never) : never;
+export {};

package/dist/contract/feed.mjs

@@ -0,0 +1,249 @@
+import { Anyone } from "./caller.mjs";
+import { Unauthenticated } from "./errors.mjs";
+import { checkInput } from "./input-check.mjs";
+import { assertKnown } from "./names.mjs";
+import { builderLayer, memoized, notMadeHere, selectHeld } from "./implementation.mjs";
+import { jsonRoundTrip } from "./call.mjs";
+import { canonicalInput } from "./canonical.mjs";
+import { reported } from "./reported.mjs";
+import { Events, attachmentsOf, reaches } from "./hub.mjs";
+import { makeLeases } from "./lease.mjs";
+import { AnyOccurrence, Gap } from "./occurrence.mjs";
+import { fedOf, pagedFrom } from "./pages.mjs";
+import { Array, DateTime, Duration, Effect, Layer, Option, Predicate, Stream } from "effect";
+// src/contract/feed.ts
+const defaultNextPoll = Duration.seconds(5);
+const longestNextPoll = Duration.minutes(5);
+const logPageSize = 100;
+const pageLimit = (maxEvents) => Math.min(Math.max(Math.floor(maxEvents), 1), logPageSize);
+const occurrencesOf = (event) => {
+	const sent = jsonRoundTrip(event.payload);
+	return (emitted, cursor) => Effect.matchCauseEffect(sent(emitted.data), {
+		onFailure: (cause) => Effect.as(Effect.annotateLogs(reported(cause), "event", event.name), Gap.make({ cursor })),
+		onSuccess: ({ value }) => Effect.map(DateTime.now, (now) => AnyOccurrence.make({
+			eventId: emitted.eventId ?? globalThis.crypto.randomUUID(),
+			name: event.name,
+			timestamp: emitted.timestamp ?? now,
+			data: value,
+			cursor
+		}))
+	});
+};
+const isOccurrence = (fed) => Predicate.isTagged(fed, "Occurrence");
+/** A poll's page of `items`: their occurrences, `truncated` too where a gap stands for one. */
+const pageOf = (items, { truncated, ...page }) => {
+	const events = items.filter(isOccurrence);
+	return {
+		...page,
+		events,
+		truncated: truncated || events.length < items.length
+	};
+};
+const lifted = (value) => Effect.isEffect(value) ? value : Effect.succeed(value);
+/** The key a subscriber of `input` is reached by, as the source's `key` answers it. */
+const keyOf = (source, input) => source.key === void 0 ? Effect.undefined : lifted(source.key(input));
+const leaseKey = (event, subscriber, input) => Effect.map(canonicalInput(event.input, input), (encoded) => `${subscriber ?? ""}\u0000${encoded}`);
+const answeredPage = ({ answered, items }) => pageOf(items, {
+	cursor: answered.cursor,
+	truncated: answered.truncated === true,
+	hasMore: answered.hasMore === true,
+	nextPoll: Duration.min(Duration.fromInputUnsafe(answered.nextPoll ?? defaultNextPoll), longestNextPoll)
+});
+const checkRun = (event, source, { wakes, polls }) => {
+	const occurrenceOf = occurrencesOf(event);
+	const read = (input, cursor) => Effect.flatMap(source.check(input, cursor), (answered) => Effect.map(Effect.forEach(answered.events, (emitted, index) => occurrenceOf(emitted, index === answered.events.length - 1 ? answered.cursor : cursor)), (items) => ({
+		answered,
+		items
+	})));
+	return {
+		poll: (input, cursor) => Effect.map(read(input, cursor), answeredPage),
+		stream: (input, cursor) => Stream.unwrap(Effect.map(Effect.flatMap(keyOf(source, input), wakes), (woken) => pagedFrom((at) => Effect.map(read(input, at), (delivered) => ({
+			...answeredPage(delivered),
+			fed: fedOf({
+				items: delivered.items,
+				truncated: delivered.answered.truncated === true,
+				from: at,
+				to: delivered.answered.cursor
+			})
+		})), cursor, woken, polls)))
+	};
+};
+const currentRun = (event, source, checking) => checkRun(event, {
+	key: source.key,
+	check: (input, cursor) => Effect.gen(function* () {
+		const at = yield* checking.revision(yield* keyOf(source, input));
+		if (cursor === at) return {
+			cursor: at,
+			events: []
+		};
+		return {
+			cursor: at,
+			events: [{
+				eventId: at,
+				data: yield* source.current(input)
+			}]
+		};
+	})
+}, checking);
+const logRun = (event, source, log) => {
+	const occurrenceOf = occurrencesOf(event);
+	const delivered = (input, key, { cursor, at, value: logged }) => Effect.gen(function* () {
+		if (logged === void 0) {
+			yield* Effect.annotateLogs(Effect.logWarning(`An entry of the log of ${event.name} could not be read: sent as a gap`), "event", event.name);
+			return Gap.make({ cursor });
+		}
+		const emitted = logged.value;
+		if (!reaches(logged.key, key)) return;
+		if (source.match !== void 0 && !(yield* lifted(source.match(input, emitted.data)))) return;
+		const data = source.transform === void 0 ? emitted.data : yield* lifted(source.transform(input, emitted.data));
+		return yield* occurrenceOf({
+			data,
+			eventId: emitted.eventId ?? cursor,
+			timestamp: emitted.timestamp ?? DateTime.makeUnsafe(at)
+		}, cursor);
+	});
+	const received = (input, key, read) => Effect.map(Effect.forEach(read.entries, (entry) => delivered(input, key, entry)), (items) => items.filter(Predicate.isNotUndefined));
+	return {
+		poll: (input, cursor, { maxEvents = logPageSize }) => Effect.flatMap(Effect.all([keyOf(source, input), log.read(cursor, pageLimit(maxEvents))]), ([key, read]) => Effect.map(received(input, key, read), (items) => pageOf(items, {
+			cursor: read.cursor,
+			truncated: read.truncated,
+			hasMore: read.hasMore,
+			nextPoll: defaultNextPoll
+		}))),
+		stream: (input, cursor) => Stream.unwrap(Effect.map(keyOf(source, input), (key) => log.follow(cursor, logPageSize).pipe(Stream.mapEffect((read) => Effect.map(received(input, key, read), (items) => fedOf({
+			items,
+			truncated: read.truncated,
+			from: read.after,
+			to: read.cursor
+		}))), Stream.flattenIterable)))
+	};
+};
+/** `run` with the source's `subscription` held while each subscription lasts. */
+const hooked = (event, run, subscription, leases) => ({
+	...run,
+	poll: (input, cursor, options) => Effect.flatMap(leaseKey(event, options.subscriber, input), (key) => Effect.andThen(leases.hold(key, input), () => run.poll(input, cursor, options))),
+	release: (input, subscriber) => Effect.flatMap(leaseKey(event, subscriber, input), leases.release),
+	stream: (input, cursor) => Stream.unwrap(Effect.map(subscription(input), () => run.stream(input, cursor)))
+});
+const isCheck = (source) => Predicate.isFunction(source.check);
+const isCurrent = (source) => Predicate.isFunction(source.current);
+const runOf = (event, source) => Effect.gen(function* () {
+	const attach = yield* Effect.flatMap(Events, attachmentsOf);
+	let run;
+	if (isCheck(source)) run = checkRun(event, source, yield* attach.check(event, false));
+	else if (isCurrent(source)) run = currentRun(event, source, yield* attach.check(event, true));
+	else run = logRun(event, source, yield* attach.log(event, source.log, source.log.emit));
+	if (source.subscription === void 0) return run;
+	return hooked(event, run, source.subscription, yield* makeLeases(source.subscription, source.lease));
+});
+const isSource = (source) => {
+	const log = Predicate.hasProperty(source, "log") ? source.log : void 0;
+	const logged = Predicate.isObject(log) && (!Predicate.hasProperty(log, "emit") || log.emit === void 0 || Stream.isStream(log.emit));
+	return [
+		Predicate.isFunction(Predicate.hasProperty(source, "check") ? source.check : void 0),
+		Predicate.isFunction(Predicate.hasProperty(source, "current") ? source.current : void 0),
+		logged
+	].filter(Boolean).length === 1;
+};
+const assertSource = (event, source) => {
+	if (!isSource(source)) throw new Error(`Event "${event.name}": its source needs exactly one of check, current or log (give check or current a function, or log its options, {} or { emit: stream })`);
+	return source;
+};
+/**
+* The runtime of `events`' sources: one per event, from the source given for one event alone, or
+* from a record keyed by event name, the builder run once for all of them.
+*/
+const sourcesOf = (events, single, sources) => {
+	const names = events.map((event) => event.name);
+	const checked = (built) => {
+		const keyed = single ? Object.fromEntries(names.map((name) => [name, built])) : Object.fromEntries(Predicate.isObject(built) ? Object.entries(built) : []);
+		assertKnown("sources", Object.keys(keyed), names, "remove it, or list its event");
+		const missing = names.filter((name) => !Object.hasOwn(keyed, name));
+		if (missing.length > 0) throw new Error(`Missing sources: ${missing.join(", ")} (give the source of one event, or a record with an own source per listed event)`);
+		return keyed;
+	};
+	const built = memoized(Effect.isEffect(sources) ? Effect.map(sources, checked) : Effect.sync(() => checked(sources)));
+	return events.map((event) => {
+		const run = memoized(Effect.flatMap(Effect.service(built.key), (keyed) => runOf(event, assertSource(event, keyed[event.name]))));
+		return [event, {
+			key: run.key,
+			layer: Layer.provide(run.layer, built.layer)
+		}];
+	});
+};
+const guarded = (event, run, before) => {
+	const attributes = { "event.name": event.name };
+	const admit = (input) => event.caller === Anyone ? checkInput(event, input) : Effect.flatMap(Effect.serviceOption(event.caller), (subscriber) => Option.isSome(subscriber) ? Effect.andThen(checkInput(event, input), Effect.suspend(() => before(event))) : Effect.fail(new Unauthenticated()));
+	return {
+		event,
+		release: run.release,
+		admit,
+		poll: (input, cursor, options) => Effect.andThen(admit(input), () => run.poll(input, cursor, options)).pipe(Effect.annotateLogs(attributes), Effect.withSpan(event.name, { attributes }, { captureStackTrace: false })),
+		stream: (input) => Effect.as(admit(input), (cursor) => run.stream(input, cursor).pipe(Stream.withSpan(event.name, { attributes })))
+	};
+};
+/**
+* Event types bound to their sources and their authorizer: everything one `Event.implement` call
+* produced. Its type parameters may be written out, as a package emitting declarations prints
+* them: `E` its event types, `R` what its sources read per subscription, by event name, `EX` and `RX` the
+* failures and services of its builder, `RA` what its authorizer reads per subscription, and
+* `EAX` and `RAX` the failures and services of the authorizer's builder.
+*/
+var EventImplementation = class EventImplementation {
+	/** Tells an event implementation from an action implementation among what a surface is given. */
+	_tag = "EventImplementation";
+	/** The event types this implementation answers. */
+	events;
+	#running;
+	#authorizer;
+	constructor(events, running, authorizer) {
+		this.events = events;
+		this.#running = running;
+		this.#authorizer = authorizer;
+	}
+	/** Select event types while retaining their sources, authorization and shared builder. */
+	static share(events, app) {
+		const source = EventImplementation.own(app);
+		return new EventImplementation(events, source.#running, source.#authorizer);
+	}
+	/** The builders of `app`, its sources' and its authorizer's, as one layer. */
+	static layerOf(app) {
+		const source = EventImplementation.own(app);
+		const runs = Layer.mergeAll(Layer.empty, ...EventImplementation.held(app).map(([, run]) => run.layer));
+		return builderLayer(app.events, { layer: runs }, source.#authorizer);
+	}
+	/** The event types of `app` with what runs them, behind its authorizer. */
+	static feedsOf(app) {
+		const source = EventImplementation.own(app);
+		return Effect.gen(function* () {
+			const before = app.events.some((event) => event.caller !== Anyone) ? yield* source.#authorizer.key : () => Effect.void;
+			return yield* Effect.forEach(EventImplementation.held(app), ([event, run]) => Effect.map(Effect.service(run.key), (ran) => guarded(event, ran, before)));
+		});
+	}
+	/** What runs each event type `app` holds. */
+	static held(app) {
+		return EventImplementation.own(app).#running.filter(([event]) => app.events.includes(event));
+	}
+	static own(app) {
+		if (!(#running in app)) throw notMadeHere("Event");
+		return app;
+	}
+};
+/**
+* Why `surface` cannot serve `feeds` unless its authentication is `keyed` by a principal: a
+* protected event type whose `subscription` hook is held per subscriber between polls, which a
+* principal names.
+*/
+const unkeyedHook = (surface, feeds, keyed) => keyed ? void 0 : Array.findFirst(feeds, ({ event, release }) => release !== void 0 && event.caller !== Anyone).pipe(Option.map(({ event }) => `${surface} event "${event.name}" is protected and has a subscription hook, so its authentication needs principal to tell poll subscribers apart (give Authentication.make a principal, such as (user) => user.id)`), Option.getOrUndefined);
+/** The event implementations among what a surface is given. */
+const eventsOf = (served) => Array.ensure(served).filter((app) => Predicate.isTagged(app, "EventImplementation"));
+/**
+* The event implementations among `apps` holding an event type of `listed`, each holding those
+* alone, refusing one listed that none holds; every one where `listed` is absent.
+*/
+const selectEvents = (apps, listed) => selectHeld(apps, listed, (app) => app.events, (own, app) => EventImplementation.share(own, app));
+/** The builder layers of event implementations, as a surface provides them. */
+const feedBuilders = (events) => events.map((app) => EventImplementation.layerOf(app));
+/** Every feed of event implementations, from the context their builders provide. */
+const acquireFeeds = (events) => Effect.map(Effect.forEach(events, (app) => EventImplementation.feedsOf(app)), (feeds) => feeds.flat());
+export { EventImplementation, acquireFeeds, defaultNextPoll, eventsOf, feedBuilders, selectEvents, sourcesOf, unkeyedHook };

package/dist/contract/hints.mjs

@@ -1,4 +1,4 @@
-//#region src/contract/hints.ts
+// src/contract/hints.ts
 /**
 * An action's MCP tool hints, MCP's defaults where its `mcp` leaves one out, except that a read
 * is not destructive where MCP's default would say it is: no tool idempotent and every tool
@@ -11,5 +11,4 @@ const hintsOf = ({ readOnly, mcp }) => ({
 	idempotentHint: mcp.idempotentHint ?? false,
 	openWorldHint: mcp.openWorldHint ?? true
 });
-//#endregion
 export { hintsOf };

package/dist/contract/hub.d.mts

@@ -0,0 +1,94 @@
+import { LogStorage } from "./log.mjs";
+import { Any, Emitted } from "../Event.mjs";
+import { Context, Effect, Layer, Scope, Stream } from "effect";
+/** What `notify` and `publish` take: the key whose subscribers they reach. */
+export interface KeyOptions {
+  /**
+   * Reach only the subscribers whose source's `key` answers this, such as one room's; without
+   * it, every subscriber of the event. A subscriber of a source without `key` is reached either way.
+   */
+  readonly key?: string | undefined;
+}
+type ErasedEmitted = Emitted<Any>;
+/**
+ * Where an `Events` keeps its current sources' revisions: counters by name, which only count up,
+ * in an `epoch` telling them from counters that started again.
+ */
+export interface RevisionStorage {
+  /** Changes whenever the counters start again, so a cursor from before is behind every revision. */
+  readonly epoch: string;
+  readonly get: (name: string) => Effect.Effect<number>;
+  /** Adds one to each counter `names` names. */
+  readonly bump: (names: readonly string[]) => Effect.Effect<void>;
+}
+declare const Events_base: Context.ServiceClass<Events, "effect-actions/Event/Events", {
+  /** Wakes the subscribers of `event`'s check source to read it now, rather than at their next poll. */
+  readonly notify: (event: Any, options?: KeyOptions) => Effect.Effect<void>;
+  /** Appends `emitted` to `event`'s log, delivering it to the log source's subscribers now. */
+  readonly publish: <E extends Any>(event: E, emitted: Emitted<E>, options?: KeyOptions) => Effect.Effect<void>;
+}>;
+/**
+ * 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.
+ */
+export declare class Events extends Events_base {}
+/** `makeEvents`' options: where it keeps logs, and whether check sources are read on a timer. */
+export interface MakeEventsOptions {
+  /**
+   * The storage of `event`'s log, made at its first attachment: the core keeps the log's cursors,
+   * bounds and expiry over it.
+   */
+  readonly log: (event: Any) => LogStorage<ErasedEmitted>;
+  /**
+   * Whether a check source's subscribers also read it again on a timer, each page's `nextPoll`,
+   * besides when notified; defaults to `true`. `false` where a pending timer would keep the host
+   * awake, as it keeps a Durable Object from hibernating: its sources are read when notified, and
+   * 5 seconds after a read that fails.
+   */
+  readonly polls?: boolean | undefined;
+  /**
+   * Whether a log source's `emit` is consumed; defaults to `true`. `false` where the host does not
+   * last, as a Durable Object is evicted while idle and misses what a stream sends meanwhile: a
+   * log source fed by `emit` dies as it attaches, naming `publish`.
+   */
+  readonly emits?: boolean | undefined;
+  /**
+   * Where current sources' revisions are kept; defaults to memory, a new epoch with each
+   * `makeEvents`. A host keeping its logs in storage keeps them there too, so a subscriber's
+   * cursor outlives the host.
+   */
+  readonly revisions?: RevisionStorage | undefined;
+}
+/**
+ * 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.
+ */
+export declare const makeEvents: (options: MakeEventsOptions) => Effect.Effect<Events["Service"], never, Scope.Scope>;
+/**
+ * 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.
+ */
+export declare const layerMemory: Layer.Layer<Events>;
+export {};