@gjermundgaraba/effect-actions 0.19.0 → 0.21.0

package/dist/contract/implementation.mjs

@@ -1,10 +1,23 @@
-import { Anyone, assertAuthentication } from "./caller.mjs";
+import { Anyone, CallerKeyed } from "./caller.mjs";
 import { Unauthenticated } from "./errors.mjs";
-import { assertDistinct, assertOnce, heldOnce } from "./names.mjs";
 import { projectedErrors } from "./declared.mjs";
-import { Array, Cause, Context, Effect, Exit, Layer, Option, Schema } from "effect";
-//#region src/contract/implementation.ts
+import { checkInput } from "./input-check.mjs";
+import { assertOnce, heldOnce } from "./names.mjs";
+import { reportedTo, streamReportedTo } from "./progress.mjs";
+import { elementOf } from "./stream.mjs";
+import { Array, Cause, Context, Effect, Exit, Layer, Option, Predicate, References, Schema, Stream } from "effect";
+// src/contract/implementation.ts
 const uniqueKey = () => Math.random().toString(36).slice(2);
+const notAStream = /* @__PURE__ */ new Error("A handler answered otherwise than its action's success declares");
+/** The stream of a call of an action answering one, from its `ErasedHandler`'s answer. */
+const elementsOf = (answer) => Stream.unwrap(Effect.filterOrElse(answer, Stream.isStream, () => Effect.die(notAStream)));
+/** The answer of a handler of an action answering one value, a stream refused as a defect. */
+const answered = (answer) => Stream.isStream(answer) ? Effect.die(notAStream) : answer;
+/**
+* `run` as a tool calls it, a tool answering one result: the elements of an action answering a
+* stream collected, in order, into one array once the stream ends.
+*/
+const answeringWhole = (action, run) => elementOf(action.success) === void 0 ? run : (input, reporting) => Stream.runCollect(elementsOf(run(input, reporting)));
 const memoized = (build) => {
 	const key = Context.Service(`effect-actions/Implementation/${uniqueKey()}`);
 	return {
@@ -13,6 +26,48 @@ const memoized = (build) => {
 	};
 };
 /**
+* The builders of an implementation of `contracts` as one layer: what its builder made, and its
+* authorizer where a contract is protected, as only those need one.
+*/
+const builderLayer = (contracts, built, authorizer) => contracts.some((contract) => contract.caller !== Anyone) ? Layer.merge(built.layer, authorizer.layer) : built.layer;
+/** What a surface throws for an implementation some other copy of this module made. */
+const notMadeHere = (module) => /* @__PURE__ */ new Error(`Not an implementation made by this ${module}.implement: pass the value implement returned, not a copy such as a spread; or effect-actions is installed twice`);
+const asDefects = (reason, rejected) => {
+	const trace = Context.makeUnsafe(reason.annotations);
+	return [Cause.makeDieReason(reason.error).annotate(trace), Cause.makeDieReason(Cause.squash(rejected)).annotate(trace)];
+};
+const dispatch = (action, handle, before, keyed) => {
+	const actionAttributes = {
+		"action.name": action.name,
+		"action.read_only": action.readOnly
+	};
+	const authentication = action.caller === Anyone ? Effect.void : Effect.flatMap(Effect.serviceOption(action.caller), (actor) => Option.isSome(actor) ? Effect.void : Effect.fail(new Unauthenticated()));
+	const authorization = action.caller === Anyone ? Effect.void : Effect.suspend(() => before(action));
+	const validate = Schema.decodeUnknownEffect(Schema.toType(Schema.Union(projectedErrors(action))));
+	const declaredOrDefect = Effect.fnUntraced(function* (cause) {
+		const reasons = [];
+		for (const reason of cause.reasons) if (Cause.isFailReason(reason)) {
+			const validated = yield* Effect.exit(validate(reason.error));
+			reasons.push(...Exit.isSuccess(validated) ? [reason] : asDefects(reason, validated.cause));
+		} else reasons.push(reason);
+		return yield* Effect.failCause(Cause.fromReasons(reasons));
+	});
+	const admitted = (input) => Effect.andThen(authentication, Effect.andThen(checkInput(action, input), authorization));
+	const span = { attributes: actionAttributes };
+	const trace = { captureStackTrace: false };
+	if (elementOf(action.success) !== void 0) {
+		const streamed = (answer) => Stream.isStream(answer) ? Stream.scoped(answer) : Stream.die(notAStream);
+		return (input, sink) => Effect.succeed(Stream.unwrap(Effect.map(admitted(input), () => streamReportedTo(action.progress, sink, (reporting) => streamed(handle(input, reporting))))).pipe(Stream.catchCause((cause) => Stream.fromEffect(declaredOrDefect(cause))), Stream.updateService(References.CurrentLogAnnotations, (annotations) => ({
+			...annotations,
+			...actionAttributes
+		})), Stream.withSpan(action.name, {
+			...span,
+			...trace
+		})));
+	}
+	return (input, sink) => Effect.scoped(admitted(input).pipe(Effect.andThen(Effect.suspend(() => reportedTo(action.progress, sink, (reporting) => answered(handle(input, reporting))))), Effect.provideService(CallerKeyed, keyed), Effect.catchCause(declaredOrDefect))).pipe(Effect.annotateLogs(actionAttributes), Effect.withSpan(action.name, span, trace));
+};
+/**
 * Actions bound to their handlers and their authorizer: everything one `Action.implement` call
 * produced, one builder serving every surface. The private fields make this class nominal: a structurally similar object, including one made by
 * spreading an implementation, is not an implementation. Its type parameters may be written
@@ -22,6 +77,7 @@ const memoized = (build) => {
 * failures and services of the authorizer's builder.
 */
 var Implementation = class Implementation {
+	/** The contracts this implementation answers. */
 	actions;
 	#handlers;
 	#authorizer;
@@ -49,28 +105,32 @@ var Implementation = class Implementation {
 	*/
 	static layerOf(app) {
 		const source = Implementation.own(app);
-		return app.actions.some((action) => action.caller !== Anyone) ? Layer.merge(source.#handlers.layer, source.#authorizer.layer) : source.#handlers.layer;
+		return builderLayer(app.actions, source.#handlers, source.#authorizer);
 	}
 	/**
 	* The actions of `app` with their handlers, behind its authorizer, from the context
 	* `layerOf(app)` provides.
 	*/
-	static boundOf(app) {
+	static boundOf(app, keyed) {
 		const { actions } = app;
 		const source = Implementation.own(app);
 		return Effect.gen(function* () {
 			const bound = yield* source.#handlers.key;
 			const before = actions.some((action) => action.caller !== Anyone) ? yield* source.#authorizer.key : () => Effect.void;
-			return actions.flatMap((action) => bound.flatMap(([held, handle]) => held === action ? [[action, dispatch(action, handle, before)]] : []));
+			return actions.flatMap((action) => bound.flatMap(([held, handle]) => held === action ? [[action, dispatch(action, handle, before, keyed)]] : []));
 		});
 	}
 	/** `app`, if this copy of the module made it; another installed copy's cannot be read. */
 	static own(app) {
-		if (!(#handlers in app)) throw new Error("Not an implementation made by this Action.implement: pass the value implement returned, not a copy such as a spread; or effect-actions is installed twice");
+		if (!(#handlers in app)) throw notMadeHere("Action");
 		return app;
 	}
 };
-const toList = (served) => Array.ensure(served);
+/**
+* The action implementations among what a surface is given; `eventsOf` reads the event
+* implementations, by their tag.
+*/
+const toList = (served) => Array.ensure(served).filter((app) => !Predicate.isTagged(app, "EventImplementation"));
 const notHeld = {
 	byImplementation: {
 		why: "no implementation holds it",
@@ -93,15 +153,22 @@ const assertHeld = ({ why, fix, holder }, listed, held) => {
 		throw new Error(`Listed in actions, but ${why}: ${markingOthers(missing, names)} (${fix}${sameName ? `; one marked (another contract) is a contract of that name ${holder}` : ""})`);
 	}
 };
-const select = (apps, listed) => {
+/**
+* The implementations among `apps` holding what `listed` lists, each sharing its builder to hold
+* those alone, or every one where it lists none: action and event implementations alike, by the
+* contracts each `holds` and how it `share`s them.
+*/
+const selectHeld = (apps, listed, holds, share) => {
 	if (listed === void 0) return apps;
-	assertHeld(notHeld.byImplementation, listed, apps.flatMap((app) => app.actions));
+	assertHeld(notHeld.byImplementation, listed, apps.flatMap(holds));
 	return apps.flatMap((app) => {
-		const own = app.actions.filter((action) => listed.includes(action));
+		const held = holds(app);
+		const own = held.filter((contract) => listed.includes(contract));
 		if (own.length === 0) return [];
-		return own.length === app.actions.length ? [app] : [Implementation.share(own, app)];
+		return own.length === held.length ? [app] : [share(own, app)];
 	});
 };
+const select = (apps, listed) => selectHeld(apps, listed, (app) => app.actions, (own, app) => Implementation.share(own, app));
 const servedBy = (what, bound, apps, listed) => {
 	if (listed !== void 0) assertHeld(notHeld.byBinding, listed, bound);
 	const held = apps.flatMap((app) => app.actions);
@@ -114,59 +181,26 @@ const servedBy = (what, bound, apps, listed) => {
 	assertOnce("served action", actions, heldOnce);
 	return served;
 };
-/**
-* What `ActionHttp.layer` and `ActionRpc.layer` serve, with the checks they share;
-* `authentication` is the binding's where a served action is protected.
-*/
-const servingOf = (what, binding, served, options) => {
-	const apps = servedBy(what, binding.actions, toList(served), options.actions);
-	const actions = apps.flatMap((app) => app.actions);
-	assertAuthentication(actions, binding.authentication);
-	assertDistinct("middleware", options.middleware ?? [], (key) => key.key, { fix: "list each middleware once" });
-	return {
-		apps,
-		actions,
-		authentication: actions.some((action) => action.caller !== Anyone) ? binding.authentication : void 0
-	};
-};
-const provideHandlers = (apps) => (layer) => {
-	const [first, ...rest] = apps.map((app) => Implementation.layerOf(app));
+/** Provide `builders`, implementations' builder layers, to a surface's layer. */
+const provideBuilders = (builders) => (layer) => {
+	const [first, ...rest] = builders;
 	return first === void 0 ? layer : Layer.provide(layer, Layer.mergeAll(first, ...rest));
 };
-const builders = (apps) => Layer.empty.pipe(provideHandlers(apps));
-const acquire = (apps) => Effect.map(Effect.forEach(apps, (app) => Implementation.boundOf(app)), (bound) => bound.flat());
-const built = (apps) => {
-	const [first, ...rest] = apps.map((app) => Implementation.layerOf(app));
+const provideHandlers = (apps) => provideBuilders(apps.map((app) => Implementation.layerOf(app)));
+const acquire = (apps, keyed) => Effect.map(Effect.forEach(apps, (app) => Implementation.boundOf(app, keyed)), (bound) => bound.flat());
+/**
+* What `acquisition` reads, once `builders` are built into the layer graph around the caller, and
+* held by its scope.
+*/
+const builtWith = (builders, acquisition) => {
+	const [first, ...rest] = builders;
 	return Effect.gen(function* () {
-		if (first === void 0) return [];
+		if (first === void 0) return yield* acquisition;
 		const current = yield* Effect.serviceOption(Layer.CurrentMemoMap);
 		const memoMap = Option.getOrElse(current, Layer.makeMemoMapUnsafe);
 		const scope = yield* Effect.scope;
 		const context = yield* Layer.buildWithMemoMap(Layer.mergeAll(first, ...rest), memoMap, scope);
-		return yield* Effect.provideContext(acquire(apps), context);
-	});
-};
-const dispatch = (action, handle, before) => {
-	const actionAttributes = {
-		"action.name": action.name,
-		"action.read_only": action.readOnly
-	};
-	const authentication = action.caller === Anyone ? Effect.void : Effect.flatMap(Effect.serviceOption(action.caller), (actor) => Option.isSome(actor) ? Effect.void : Effect.fail(new Unauthenticated()));
-	const authorization = action.caller === Anyone ? Effect.void : Effect.suspend(() => before(action));
-	const validate = Schema.decodeUnknownEffect(Schema.toType(Schema.Union(projectedErrors(action))));
-	const asDefects = (reason, rejected) => {
-		const trace = Context.makeUnsafe(reason.annotations);
-		return [Cause.makeDieReason(reason.error).annotate(trace), Cause.makeDieReason(Cause.squash(rejected)).annotate(trace)];
-	};
-	const declaredOrDefect = Effect.fnUntraced(function* (cause) {
-		const reasons = [];
-		for (const reason of cause.reasons) if (Cause.isFailReason(reason)) {
-			const validated = yield* Effect.exit(validate(reason.error));
-			reasons.push(...Exit.isSuccess(validated) ? [reason] : asDefects(reason, validated.cause));
-		} else reasons.push(reason);
-		return yield* Effect.failCause(Cause.fromReasons(reasons));
+		return yield* Effect.provideContext(acquisition, context);
 	});
-	return (input) => Effect.scoped(authentication.pipe(Effect.andThen(authorization), Effect.andThen(Effect.suspend(() => handle(input))), Effect.catchCause(declaredOrDefect))).pipe(Effect.annotateLogs(actionAttributes), Effect.withSpan(action.name, { attributes: actionAttributes }, { captureStackTrace: false }));
 };
-//#endregion
-export { Implementation, acquire, assertHeld, builders, built, memoized, notHeld, provideHandlers, select, servingOf, toList };
+export { Implementation, acquire, answered, answeringWhole, assertHeld, builderLayer, builtWith, elementsOf, markingOthers, memoized, notHeld, notMadeHere, provideBuilders, provideHandlers, select, selectHeld, servedBy, toList, uniqueKey };

package/dist/contract/input-check.d.mts

@@ -0,0 +1,15 @@
+import { Forbidden } from "./errors.mjs";
+import { Any } from "../Event.mjs";
+import { Any as Any$1 } from "../Action.mjs";
+import { Context, Effect } from "effect";
+/**
+ * A check every call and every subscription runs on its decoded input, on every surface, once the
+ * surface has verified its caller and before its authorizer: what a host provides, as a Durable
+ * Object refuses an input naming another object, to refuse an input it does not serve. Defaults
+ * to none.
+ *
+ * **Gotchas**
+ *
+ * - Provide it to the layer graph the surfaces are built in, as `Layer.succeed(Action.InputCheck)(check)`: provided per request, it misses a socket's later calls.
+ */
+export declare const InputCheck: Context.Reference<(contract: Any$1 | Any, input: Any$1["input"]["Type"]) => Effect.Effect<void, Forbidden>>;

package/dist/contract/input-check.mjs

@@ -0,0 +1,16 @@
+import { Context, Effect } from "effect";
+// src/contract/input-check.ts
+/**
+* A check every call and every subscription runs on its decoded input, on every surface, once the
+* surface has verified its caller and before its authorizer: what a host provides, as a Durable
+* Object refuses an input naming another object, to refuse an input it does not serve. Defaults
+* to none.
+*
+* **Gotchas**
+*
+* - Provide it to the layer graph the surfaces are built in, as `Layer.succeed(Action.InputCheck)(check)`: provided per request, it misses a socket's later calls.
+*/
+const InputCheck = Context.Reference("effect-actions/Action/InputCheck", { defaultValue: () => () => Effect.void });
+/** `contract`'s `input`, as the provided `InputCheck` judges it. */
+const checkInput = (contract, input) => Effect.flatMap(Effect.service(InputCheck), (check) => check(contract, input));
+export { InputCheck, checkInput };

package/dist/contract/lease.mjs

@@ -0,0 +1,28 @@
+import { Context, Duration, Effect, Equal, Hash, RcMap, Scope } from "effect";
+// src/contract/lease.ts
+/** A poll subscription's key, held with the context of the poll that first acquired it. */
+var Lease = class Lease {
+	key;
+	input;
+	context;
+	constructor(key, input, context) {
+		this.key = key;
+		this.input = input;
+		this.context = context;
+	}
+	[Equal.symbol](that) {
+		return that instanceof Lease && that.key === this.key;
+	}
+	[Hash.symbol]() {
+		return Hash.string(this.key);
+	}
+};
+const defaultLease = Duration.minutes(5);
+const makeLeases = (subscription, ttl = defaultLease) => Effect.map(RcMap.make({
+	lookup: (lease) => Effect.provideContext(subscription(lease.input), Context.omit(Scope.Scope)(lease.context)),
+	idleTimeToLive: ttl
+}), (map) => ({
+	hold: (key, input) => Effect.flatMap(Effect.context(), (context) => Effect.scoped(RcMap.get(map, new Lease(key, input, context)))),
+	release: (key) => RcMap.invalidate(map, new Lease(key, void 0, Context.empty()))
+}));
+export { makeLeases };

package/dist/contract/listed.d.mts

@@ -0,0 +1,4 @@
+import "../Event.mjs";
+import "../Action.mjs";
+/** The members of the list `T` that are `U`: `T` itself where every one is, `[]` where none is. */
+export type Only<T extends readonly unknown[], U> = [Exclude<T[number], U>] extends [never] ? Extract<T, readonly U[]> : [Extract<T[number], U>] extends [never] ? readonly [] : ReadonlyArray<Extract<T[number], U>>;

package/dist/contract/listed.mjs

@@ -0,0 +1,22 @@
+import { assertOnce } from "./names.mjs";
+import { isEvent } from "../Event.mjs";
+// src/contract/listed.ts
+/** A list split into its actions and its event types. */
+const split = (contracts) => ({
+	actions: contracts.flatMap((contract) => isEvent(contract) ? [] : [contract]),
+	events: contracts.filter(isEvent)
+});
+/** A binding's list split into its actions and its event types, each name used once. */
+const listed = (contracts) => {
+	assertOnce("action or event", contracts);
+	return split(contracts);
+};
+/**
+* A surface's `actions` option split into the actions and the event types it lists, both absent
+* where it is: a surface given the option serves exactly what it lists.
+*/
+const selection = (contracts) => contracts === void 0 ? {
+	actions: void 0,
+	events: void 0
+} : split(contracts);
+export { listed, selection, split };

package/dist/contract/log.d.mts

@@ -0,0 +1,41 @@
+import { Duration, Effect, Stream } from "effect";
+/** One entry of a log: what was published, and the key it was published to, if any. */
+export interface Logged<A> {
+  readonly value: A;
+  readonly key: string | undefined;
+}
+/** Where a log stands: the epoch its cursors name, and the last sequence number it gave. */
+export interface Position {
+  readonly epoch: string;
+  readonly last: number;
+}
+/** One entry as a log's storage keeps it: when it was appended, and what was published. */
+export interface Stored<A> {
+  readonly at: number;
+  readonly logged: Logged<A>;
+}
+/**
+ * One entry as a log's storage lists it: as it was kept, or with `logged` `undefined` where the
+ * storage could not read it back, such as data an earlier deployment wrote in another shape,
+ * which a subscriber receives as a gap at its cursor.
+ */
+export interface Listed<A> {
+  readonly at: number;
+  readonly logged: Logged<A> | undefined;
+}
+/**
+ * Where a log keeps its position and its entries, by sequence number, as `Event.makeEvents` is
+ * given it: storage alone, the log's cursors, bounds, truncation and expiry being the core's.
+ */
+export interface LogStorage<A> {
+  /** The position `put` last kept, or `undefined` for a storage never written or emptied. */
+  readonly position: Effect.Effect<Position | undefined>;
+  /** Keeps `position`, and `entry` with it where given, at once. */
+  readonly put: (position: Position, entry?: {
+    readonly seq: number;
+    readonly stored: Stored<A>;
+  }) => Effect.Effect<void>;
+  /** The entries kept from sequence number `from` on, at most `limit`, in order. */
+  readonly list: (from: number, limit: number) => Effect.Effect<ReadonlyArray<readonly [seq: number, listed: Listed<A>]>>;
+  readonly delete: (seqs: readonly number[]) => Effect.Effect<void>;
+}

package/dist/contract/log.mjs

@@ -0,0 +1,144 @@
+import { uniqueKey } from "./implementation.mjs";
+import { reported } from "./reported.mjs";
+import { Cause, Clock, Duration, Effect, Option, Queue, Semaphore, Stream } from "effect";
+// src/contract/log.ts
+const defaultBounds = {
+	maxAge: Duration.minutes(10),
+	maxEvents: 1e4
+};
+/** A log storage in memory, for the process that makes it. */
+const memoryStorage = () => {
+	let position;
+	let newest = 0;
+	const entries = /* @__PURE__ */ new Map();
+	return {
+		position: Effect.sync(() => position),
+		put: (next, entry) => Effect.sync(() => {
+			position = next;
+			if (entry === void 0) return;
+			entries.set(entry.seq, entry.stored);
+			newest = Math.max(newest, entry.seq);
+		}),
+		list: (from, limit) => Effect.sync(() => {
+			const listed = [];
+			const oldest = entries.keys().next().value;
+			if (oldest === void 0) return listed;
+			for (let seq = Math.max(from, oldest); seq <= newest && listed.length < limit; seq += 1) {
+				const stored = entries.get(seq);
+				if (stored !== void 0) listed.push([seq, stored]);
+			}
+			return listed;
+		}),
+		delete: (seqs) => Effect.sync(() => {
+			for (const seq of seqs) entries.delete(seq);
+		})
+	};
+};
+const separator = ":";
+const cursorAt = (epoch, seq) => `${epoch}${separator}${seq}`;
+const seqIn = (epoch, cursor) => {
+	const [named, seq, ...rest] = cursor.split(separator);
+	const parsed = Number(seq);
+	return named === epoch && rest.length === 0 && Number.isSafeInteger(parsed) && parsed >= 0 ? parsed : void 0;
+};
+/**
+* A log's entries over `storage`, read by cursor: a cursor is the storage's epoch and the
+* sequence number of the last entry it has seen, so one minted by another epoch, such as a
+* memory log's before a restart or a storage's before it was emptied, reads as truncated, as
+* does one whose next entries were dropped. An epoch is minted where the storage holds none.
+*/
+const makeLogStore = (storage, { maxAge = defaultBounds.maxAge, maxEvents = defaultBounds.maxEvents } = {}) => {
+	if (!Number.isSafeInteger(maxEvents) || maxEvents < 1) throw new Error(`Invalid log maxEvents: ${maxEvents} (give a positive integer)`);
+	const age = Duration.toMillis(Duration.fromInputUnsafe(maxAge));
+	const turn = Semaphore.makeUnsafe(1);
+	const positioned = Effect.flatMap(storage.position, (found) => {
+		if (found !== void 0) return Effect.succeed(found);
+		const minted = {
+			epoch: uniqueKey(),
+			last: 0
+		};
+		return Effect.as(storage.put(minted), minted);
+	});
+	const oldestKept = (last, now) => Effect.gen(function* () {
+		for (let batch = 1;; batch = 64) {
+			const listed = yield* storage.list(0, batch);
+			const young = listed.findIndex(([, { at }]) => at >= now - age);
+			const dropped = young === -1 ? listed : listed.slice(0, young);
+			if (dropped.length > 0) yield* storage.delete(dropped.map(([seq]) => seq));
+			const first = listed[dropped.length];
+			if (first !== void 0) return Math.max(first[0], last - maxEvents + 1);
+			if (listed.length < batch) return last + 1;
+		}
+	});
+	return {
+		append: (logged) => turn.withPermit(Effect.gen(function* () {
+			const { epoch, last } = yield* positioned;
+			const seq = last + 1;
+			const at = yield* Clock.currentTimeMillis;
+			yield* storage.put({
+				epoch,
+				last: seq
+			}, {
+				seq,
+				stored: {
+					at,
+					logged
+				}
+			});
+			if (seq > maxEvents) yield* storage.delete([seq - maxEvents]);
+		})),
+		read: (cursor, limit) => turn.withPermit(Effect.gen(function* () {
+			const { epoch, last } = yield* positioned;
+			const oldest = yield* oldestKept(last, yield* Clock.currentTimeMillis);
+			const seq = cursor === null ? last : seqIn(epoch, cursor);
+			const { after, truncated } = seq === void 0 || seq > last || seq + 1 < oldest ? {
+				after: oldest - 1,
+				truncated: true
+			} : {
+				after: seq,
+				truncated: false
+			};
+			const pending = yield* storage.list(after + 1, limit + 1);
+			const page = pending.slice(0, limit);
+			return {
+				entries: page.map(([at, stored]) => ({
+					seq: at,
+					cursor: cursorAt(epoch, at),
+					at: stored.at,
+					value: stored.logged
+				})),
+				after: cursorAt(epoch, after),
+				cursor: cursorAt(epoch, page.at(-1)?.[0] ?? after),
+				truncated,
+				hasMore: pending.length > limit
+			};
+		}))
+	};
+};
+/** A log over `store`, waking its followers as each entry is appended. */
+const makeLog = (store) => {
+	const followers = /* @__PURE__ */ new Set();
+	const append = (value, key) => Effect.andThen(store.append({
+		value,
+		key
+	}), Effect.sync(() => {
+		for (const woken of followers) Queue.offerUnsafe(woken, void 0);
+	}));
+	const following = Effect.acquireRelease(Effect.tap(Queue.sliding(1), (woken) => Effect.sync(() => followers.add(woken))), (woken) => Effect.sync(() => followers.delete(woken)));
+	return {
+		append,
+		feed: (emit) => emit.pipe(Stream.runForEach(({ value, key }) => append(value, key)), Effect.matchCauseEffect({
+			onFailure: (cause) => Cause.hasInterruptsOnly(cause) ? Effect.void : reported(cause),
+			onSuccess: () => Effect.logWarning("A log source's emit stream ended: it appends nothing more")
+		})),
+		read: store.read,
+		follow: (cursor, limit) => Stream.unwrap(Effect.map(following, (woken) => Stream.paginate({
+			cursor,
+			wait: false
+		}, (state) => Effect.map(Effect.andThen(state.wait ? Queue.take(woken) : Effect.void, store.read(state.cursor, limit)), (answered) => [[answered], Option.some({
+			cursor: answered.cursor,
+			wait: !answered.hasMore
+		})]))))
+	};
+};
+export { makeLog, makeLogStore, memoryStorage };

package/dist/contract/media.d.mts

@@ -1,5 +1,4 @@
 import { Schema, SchemaAST } from "effect";
-//#region src/contract/media.d.ts
 /**
  * An image, a media field of a success: `{ data: Uint8Array, mimeType: string }`, `mimeType` such
  * as `image/png`. A top-level field of a struct success, one, optional, or a required array, or the
@@ -13,5 +12,4 @@ import { Schema, SchemaAST } from "effect";
 export declare const Image: Schema.Struct<{
   readonly data: Schema.Uint8Array;
   readonly mimeType: Schema.String;
-}>;
-//#endregion
+}>;

package/dist/contract/media.mjs

@@ -1,5 +1,5 @@
 import { Schema } from "effect";
-//#region src/contract/media.ts
+// src/contract/media.ts
 const mediaKindAnnotation = "effect-actions/media";
 const Media = Schema.Struct({
 	data: Schema.Uint8Array,
@@ -18,5 +18,4 @@ const Media = Schema.Struct({
 const Image = Media.annotate({ [mediaKindAnnotation]: "image" });
 const isMarked = (ast) => ast.annotations?.[mediaKindAnnotation] === "image";
 const kindOf = (ast) => isMarked(ast) && ast.encoding === void 0 ? "image" : void 0;
-//#endregion
 export { Image, Media, isMarked, kindOf };

package/dist/contract/names.mjs

@@ -1,8 +1,16 @@
-//#region src/contract/names.ts
+// src/contract/names.ts
 const namePattern = "[A-Za-z0-9_-]{1,128}";
-const validName = new RegExp(`^${namePattern}$`);
+const validName = new RegExp(`^${namePattern}$`, "u");
+const reserved = [["then", "which would make a client a thenable, awaited as a promise"], ["watch", "every client's method for events"]];
+const reservedNames = reserved.map(([name]) => name);
+/** The reserved names as a message lists them: `"then" or "watch"`. */
+const reservedList = reservedNames.map((name) => `"${name}"`).join(" or ");
 const assertName = (name) => {
-	if (!validName.test(name) || name === "then") throw new Error(`Invalid action name: ${name} (use ${namePattern}, other than "then")`);
+	if (!validName.test(name) || reservedNames.includes(name)) throw new Error(`Invalid action name: ${name} (use ${namePattern}, other than ${reserved.map(([reservedName, why]) => `"${reservedName}", ${why}`).join(", and ")})`);
+};
+const validEventName = new RegExp(`^[a-z0-9_-]+(\\.[a-z0-9_-]+)*$`, "u");
+const assertEventName = (name) => {
+	if (name.length > 128 || !validEventName.test(name)) throw new Error(`Invalid event name: ${name} (use lowercase dot-separated segments of [a-z0-9_-], at most 128 characters)`);
 };
 const assertDistinct = (what, items, nameOf, { claimantOf = nameOf, labelOf = nameOf, fix }) => {
 	const seen = /* @__PURE__ */ new Map();
@@ -18,10 +26,11 @@ const assertDistinct = (what, items, nameOf, { claimantOf = nameOf, labelOf = na
 	}
 };
 const heldOnce = "pass one implementation of it, or rename one";
-const assertOnce = (what, actions, fix = "list it once, or rename one") => assertDistinct(what, actions, (action) => action.name, { fix });
+const assertOnce = (what, actions, fix = "list it once, or rename one") => {
+	assertDistinct(what, actions, (action) => action.name, { fix });
+};
 const assertKnown = (what, keys, names, fix) => {
 	const unknown = keys.filter((key) => !names.includes(key));
 	if (unknown.length > 0) throw new Error(`Unknown ${what}: ${unknown.join(", ")} (${fix})`);
 };
-//#endregion
-export { assertDistinct, assertKnown, assertName, assertOnce, heldOnce };
+export { assertDistinct, assertEventName, assertKnown, assertName, assertOnce, heldOnce, reservedList, reservedNames };

package/dist/contract/occurrence.d.mts

@@ -0,0 +1,29 @@
+import { Any } from "../Event.mjs";
+import { Effect, Schema } from "effect";
+/**
+ * Occurrences were missed: the cursor resumed from was no longer served, or delivery skipped
+ * some. `cursor` is where delivery continues.
+ */
+export declare const Gap: Schema.TaggedStruct<"Gap", {
+  readonly cursor: Schema.NullOr<Schema.String>;
+}>;
+/** A gap in what a subscriber received. */
+export type Gap = typeof Gap.Type;
+/**
+ * Where a feed has read up to without an occurrence to show for it, such as a quiet page or an
+ * occurrence a subscriber's `match` rejected: a watch keeps it as its cursor and never yields it.
+ */
+export declare const Checked: Schema.TaggedStruct<"Checked", {
+  readonly cursor: Schema.NullOr<Schema.String>;
+}>;
+export type Checked = typeof Checked.Type;
+declare const fieldsOf: <Name extends Schema.Top, Data extends Schema.Top>(name: Name, data: Data) => {
+  eventId: Schema.String;
+  name: Name;
+  timestamp: Schema.DateTimeUtc;
+  data: Data;
+  cursor: Schema.NullOr<Schema.String>;
+};
+/** The schema of an occurrence of `E`. */
+export type OccurrenceSchema<E extends Any> = Schema.TaggedStruct<"Occurrence", ReturnType<typeof fieldsOf<Schema.Literal<E["name"]>, E["payload"]>>>;
+export {};

package/dist/contract/occurrence.mjs

@@ -0,0 +1,45 @@
+import { Effect, Schema, Struct } from "effect";
+// src/contract/occurrence.ts
+/**
+* Occurrences were missed: the cursor resumed from was no longer served, or delivery skipped
+* some. `cursor` is where delivery continues.
+*/
+const Gap = Schema.TaggedStruct("Gap", { cursor: Schema.NullOr(Schema.String) });
+/**
+* Where a feed has read up to without an occurrence to show for it, such as a quiet page or an
+* occurrence a subscriber's `match` rejected: a watch keeps it as its cursor and never yields it.
+*/
+const Checked = Schema.TaggedStruct("Checked", { cursor: Schema.NullOr(Schema.String) });
+const fieldsOf = (name, data) => ({
+	eventId: Schema.String.annotate({ description: "The source's id for it, or one generated: a subscriber deduplicates by it." }),
+	name,
+	timestamp: Schema.DateTimeUtc,
+	data,
+	cursor: Schema.NullOr(Schema.String).annotate({ description: "Where to resume after it, null for an event type that cannot be resumed." })
+});
+/** An occurrence of `event`, as a subscriber decodes it. */
+const OccurrenceOf = (event) => Schema.TaggedStruct("Occurrence", fieldsOf(Schema.Literal(event.name), event.payload));
+/** Any occurrence, its data erased, as a feed makes it. */
+const AnyOccurrence = Schema.TaggedStruct("Occurrence", fieldsOf(Schema.String, Schema.Unknown));
+/** What a subscriber of `event` decodes: an occurrence, or a gap. */
+const ReceivedOf = (event) => Schema.Union([OccurrenceOf(event), Gap]);
+const untaggedOf = (event) => OccurrenceOf(event).mapFields((fields) => ({
+	...Struct.omit(fields, ["_tag"]),
+	timestamp: Schema.DateTimeUtcFromString,
+	data: Schema.toCodecJson(event.payload)
+}));
+/**
+* How a subscriber of `event` decodes an occurrence sent as JSON without its tag, as MCP's
+* notifications and a webhook's body carry one.
+*/
+const untaggedOccurrenceOf = (event) => {
+	const occurrence = OccurrenceOf(event);
+	const decode = Schema.decodeUnknownEffect(untaggedOf(event));
+	return (wire) => Effect.map(decode(wire), (fields) => occurrence.make(fields));
+};
+/** How a surface encodes an occurrence of `event` as JSON without its tag, its counterpart. */
+const encodeUntaggedOf = (event) => {
+	const encode = Schema.encodeEffect(untaggedOf(event));
+	return (occurrence) => Effect.orDie(encode(occurrence));
+};
+export { AnyOccurrence, Checked, Gap, OccurrenceOf, ReceivedOf, encodeUntaggedOf, untaggedOccurrenceOf };

package/dist/contract/pages.d.mts

@@ -0,0 +1,13 @@
+import { Checked } from "./occurrence.mjs";
+import { Any, Occurrence, Received } from "../Event.mjs";
+import { Duration, Effect, Stream } from "effect";
+/** One poll's answer, as a surface sends it and a client reads it. */
+export interface Page {
+  readonly events: ReadonlyArray<Occurrence<Any>>;
+  readonly cursor: string | null;
+  readonly truncated: boolean;
+  readonly hasMore: boolean;
+  readonly nextPoll: Duration.Duration;
+}
+/** What a feed's stream yields: what a subscriber receives, and where it has read up to. */
+export type Fed = Received<Any> | Checked;