@gjermundgaraba/effect-actions 0.20.0 → 0.21.0

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/names.mjs

@@ -1,8 +1,16 @@
 // 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,9 +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})`);
 };
-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;

package/dist/contract/pages.mjs

@@ -0,0 +1,39 @@
+import { Checked, Gap } from "./occurrence.mjs";
+import { Duration, Effect, Option, Stream } from "effect";
+// src/contract/pages.ts
+/** The shortest wait between polls, whatever a source or a server asks for. */
+const pollFloor = Duration.seconds(1);
+/** What a feed's stream yields of one read: its gap, its items, and where it ends. */
+const fedOf = ({ items, truncated, from, to }) => [
+	...truncated ? [Gap.make({ cursor: items.length === 0 ? to : from })] : [],
+	...items,
+	Checked.make({ cursor: to })
+];
+/**
+* Reads from `cursor` again and again, as long as the stream is read: what each page yields, then
+* a wait of its `nextPoll`, at least `pollFloor`, cut short by `woken`, or none where it has more;
+* where `polls` is `false`, a wait for `woken` alone.
+*/
+const pagedFrom = (read, cursor, woken, polls = true) => Stream.paginate({
+	cursor,
+	delay: Duration.zero
+}, (state) => {
+	const next = Effect.map(Effect.suspend(() => read(state.cursor)), (page) => [page.fed, Option.some({
+		cursor: page.cursor ?? state.cursor,
+		delay: page.hasMore ? Duration.zero : Duration.max(page.nextPoll, pollFloor)
+	})]);
+	const sleep = Effect.sleep(state.delay);
+	if (woken === void 0 || Duration.isZero(state.delay)) return Effect.andThen(sleep, next);
+	return Effect.andThen(polls ? Effect.race(sleep, woken) : woken, next);
+});
+/** Polls from `cursor` as `pagedFrom` reads: each page as its gap, its occurrences, its end. */
+const paged = (poll, cursor) => pagedFrom((at) => Effect.map(poll(at), (page) => ({
+	...page,
+	fed: fedOf({
+		items: page.events,
+		truncated: page.truncated,
+		from: at,
+		to: page.cursor ?? at
+	})
+})), cursor);
+export { fedOf, paged, pagedFrom };

package/dist/contract/progress.d.mts

@@ -0,0 +1,26 @@
+import { Codec } from "./codec.mjs";
+import { ErasedValue } from "./implementation.mjs";
+import { Data, Effect, Scope, Stream } from "effect";
+/** Where a call's progress goes: each value reported, checked by its schema, is given to `progress`. */
+export interface Reporting {
+  readonly progress: (value: ErasedValue) => Effect.Effect<void>;
+}
+/** The second argument of a handler of `A`, where `A` declares `progress`: what it reports by. */
+export type ReportingOf<A extends {
+  readonly progress: Codec | undefined;
+}> = A["progress"] extends undefined ? [] : [reporting: {
+  /** Reports `value` to the caller, never waiting for it: see `Action.Options.progress`. */
+  readonly progress: (value: NonNullable<A["progress"]>["Type"]) => Effect.Effect<void>;
+}];
+/** What a call of an action reporting progress `P` takes after its input. */
+export interface CallOptions<P> {
+  /**
+   * Run with each progress value the handler reports, in order, before the call answers; which
+   * values reach it, and what its failure does, are on `Action.Options.progress`.
+   */
+  readonly onProgress?: ((progress: P) => Effect.Effect<void>) | undefined;
+}
+/** What a call of `A` takes after its input, where `A` declares `progress`. */
+export type ProgressArgs<A extends {
+  readonly progress: Codec | undefined;
+}> = A["progress"] extends undefined ? [] : [options?: CallOptions<NonNullable<A["progress"]>["Type"]>];

package/dist/contract/progress.mjs

@@ -0,0 +1,72 @@
+import { Cause, Data, Effect, Exit, Fiber, Option, Queue, Schema, Stream } from "effect";
+// src/contract/progress.ts
+const capacity = 16;
+/**
+* What a handler reports by, where `progress` is declared: each value checked by the schema, one
+* breaking it a defect, and handed to `sink` from a buffer dropping the oldest, so the handler
+* never waits. Without a `sink`, values are checked and dropped.
+*/
+const buffering = (progress, sink) => {
+	const check = Schema.decodeUnknownEffect(Schema.toType(progress));
+	const checked = (value) => Effect.orDie(check(value));
+	if (sink === void 0) return Effect.succeed({
+		reporting: { progress: (value) => Effect.asVoid(checked(value)) },
+		drained: Effect.void
+	});
+	return Effect.gen(function* () {
+		const buffered = yield* Queue.sliding(capacity);
+		const forwarding = yield* Effect.forkScoped(Stream.runForEach(Stream.fromQueue(buffered), sink.progress));
+		return {
+			reporting: { progress: (value) => Effect.flatMap(checked(value), (each) => Effect.asVoid(Queue.offer(buffered, each))) },
+			drained: Effect.andThen(Queue.end(buffered), Fiber.join(forwarding))
+		};
+	});
+};
+/** Whether what is buffered still reaches the caller after `cause` ends a call. */
+const drainsAfter = (cause) => !Cause.hasInterruptsOnly(cause);
+/**
+* Runs `handle` with what it reports by, as `buffering` makes it; what is buffered when it
+* succeeds or fails reaches `sink` before its answer.
+*/
+const reportedTo = (progress, sink, handle) => {
+	if (progress === void 0) return handle(void 0);
+	return Effect.gen(function* () {
+		const { reporting, drained } = yield* buffering(progress, sink);
+		const exit = yield* Effect.exit(handle(reporting));
+		if (Exit.isSuccess(exit) || drainsAfter(exit.cause)) yield* drained;
+		return yield* exit;
+	});
+};
+/**
+* Runs the stream `handle` gives with what it reports by, as `buffering` makes it, in the
+* stream's scope; what is buffered when it ends or fails reaches `sink` before its end.
+*/
+const streamReportedTo = (progress, sink, handle) => {
+	if (progress === void 0) return handle(void 0);
+	return Stream.unwrap(Effect.map(buffering(progress, sink), ({ reporting, drained }) => handle(reporting).pipe(Stream.onEnd(drained), Stream.catchCause((cause) => drainsAfter(cause) ? Stream.unwrap(Effect.as(drained, Stream.failCause(cause))) : Stream.failCause(cause)))));
+};
+const shown = (onProgress) => (value) => Effect.catchCauseIf(Effect.suspend(() => onProgress(value)), (cause) => !Cause.hasInterruptsOnly(cause), (cause) => Effect.logWarning("onProgress failed", cause));
+/** What a caller in process hands a call for `onProgress`, as `Action.client` and the toolkit do. */
+const progressSink = (onProgress) => onProgress === void 0 ? void 0 : { progress: shown(onProgress) };
+const Progressed = Data.taggedEnum();
+const endedEarly = Effect.die(/* @__PURE__ */ new Error("An answer streamed with its progress ended without its final element"));
+/**
+* A client's answer from a call's `stream`: each `Progress` value handed to `onProgress`, where
+* the call gave one, then the `Final` value. A stream ending without one is a defect.
+*/
+const answerFrom = (stream, onProgress) => {
+	const report = progressSink(onProgress)?.progress ?? (() => Effect.void);
+	return Effect.flatMap(Stream.runFoldEffect(stream, () => Option.none(), (final, element) => Progressed.$is("Final")(element) ? Effect.succeedSome(element.value) : Effect.as(report(element.value), final)), Option.match({
+		onNone: () => endedEarly,
+		onSome: Effect.succeed
+	}));
+};
+/**
+* A client's elements from a call's `stream` of an action answering a stream: each `Progress`
+* value handed to `onProgress`, where the call gave one, and each `Element` value streamed.
+*/
+const elementsFrom = (stream, onProgress) => {
+	const report = progressSink(onProgress)?.progress ?? (() => Effect.void);
+	return Stream.flatMap(stream, (sent) => Progressed.$is("Progress")(sent) ? Stream.fromEffectDrain(report(sent.value)) : Stream.make(sent.value));
+};
+export { Progressed, answerFrom, elementsFrom, progressSink, reportedTo, streamReportedTo };

package/dist/contract/push.d.mts

@@ -0,0 +1,20 @@
+import { Codec } from "./codec.mjs";
+import "./errors.mjs";
+import { OccurrenceSchema } from "./occurrence.mjs";
+import "./pages.mjs";
+import { Any } from "../Event.mjs";
+import { Cause, Effect, Queue, Schema, Stream } from "effect";
+/** What a push subscription of `event` sends, as each surface's stream encodes it. */
+export declare const PushedOf: <E extends Any>(event: E) => Schema.Union<readonly [OccurrenceSchema<E>, Schema.TaggedStruct<"Gap", {
+  readonly cursor: Schema.NullOr<Schema.String>;
+}>, Schema.TaggedStruct<"Checked", {
+  readonly cursor: Schema.NullOr<Schema.String>;
+}>, Schema.TaggedStruct<"Failed", {}>]>;
+/**
+ * What a subscription's request carries: the event's input, and the cursor it resumes from,
+ * `null` where it is omitted.
+ */
+export declare const SubscriptionOf: <E extends Any>(event: E) => Schema.Struct<{
+  readonly input: Codec;
+  readonly cursor: Schema.withDecodingDefaultKey<Schema.NullOr<Schema.String>, never>;
+}>;

package/dist/contract/push.mjs

@@ -0,0 +1,96 @@
+import { Refusal } from "./errors.mjs";
+import { reported } from "./reported.mjs";
+import { Checked, Gap, OccurrenceOf } from "./occurrence.mjs";
+import { defaultNextPoll } from "./feed.mjs";
+import { Cause, Duration, Effect, Latch, Match, Queue, Schema, Stream } from "effect";
+// src/contract/push.ts
+/**
+* A push subscription read on through a failure no refusal explains, such as an upstream's
+* outage: its cause is logged and reported, and reading resumes from the position reached.
+*/
+const Failed = Schema.TaggedStruct("Failed", {});
+/** What a push subscription of `event` sends, as each surface's stream encodes it. */
+const PushedOf = (event) => Schema.Union([
+	OccurrenceOf(event),
+	Gap,
+	Checked,
+	Failed
+]);
+const subscriptionWith = (input) => Schema.Struct({
+	input,
+	cursor: Schema.NullOr(Schema.String).annotate({ description: "Where to resume: a cursor an occurrence or a page carried; null or omitted, from now." }).pipe(Schema.withDecodingDefaultKey(Effect.succeed(null)))
+});
+/**
+* What a subscription's request carries: the event's input, and the cursor it resumes from,
+* `null` where it is omitted.
+*/
+const SubscriptionOf = (event) => subscriptionWith(event.input);
+/** A subscription's request, its input left as JSON for its event's schema to decode. */
+const Subscription = subscriptionWith(Schema.Json);
+const queued = 16;
+const heartbeatEvery = Duration.seconds(30);
+const isFailed = Schema.is(Failed);
+/** Each element of a push stream of `surface`'s event `name` but `Failed`, which is logged. */
+const readOn = (surface, name) => (sent) => sent.pipe(Stream.mapEffect((element) => isFailed(element) ? Effect.as(Effect.logWarning(`${surface} event "${name}" failed to read, and resumes`), []) : Effect.succeed([element])), Stream.flattenIterable);
+const isRefused = Schema.is(Refusal);
+/** The refusal that `cause` fails with, unless it also holds a defect. */
+const refusalIn = (cause) => Cause.hasDies(cause) ? void 0 : cause.reasons.flatMap((reason) => Cause.isFailReason(reason) && isRefused(reason.error) ? [reason.error] : [])[0];
+/**
+* A poll of `name` that answers a failure no refusal explains, reported, as a page of none from
+* the cursor asked, read again after the poll interval: where no network carries a 500 for a
+* client to retry, as in process, it reads on as `pushed` does.
+*/
+const polledOn = (surface, name) => (poll) => (cursor) => Effect.catchCauseIf(poll(cursor), (cause) => !Cause.hasInterruptsOnly(cause) && refusalIn(cause) === void 0, (cause) => Effect.as(Effect.andThen(reported(cause), Effect.logWarning(`${surface} event "${name}" failed to read, and resumes`)), {
+	events: [],
+	cursor,
+	truncated: false,
+	hasMore: false,
+	nextPoll: defaultNextPoll
+}));
+/**
+* One push subscription of a feed `open` reads from a cursor, starting at `cursor`, each thing it
+* sends given to `deliver`. A refusal, an interruption, or, unless `resumesUnconfirmed`, a failure
+* before it is confirmed ends it; any other failure of a read or of its delivery is reported,
+* sent as `Failed`, and reading resumes from the position delivered after the poll interval.
+*/
+const pushed = (open, cursor, deliver, { resumesUnconfirmed = false, inOrder = false } = {}) => Effect.gen(function* () {
+	const confirmed = yield* Latch.make();
+	let reached = cursor;
+	let active = false;
+	let wait = Duration.zero;
+	const movedTo = (at) => Effect.suspend(() => {
+		active = true;
+		reached = at;
+		return confirmed.open;
+	});
+	const sent = (element, at) => Effect.andThen(deliver(element), movedTo(at));
+	const delivered = (fed) => Match.valueTags(fed, {
+		Gap: (gap) => sent(gap, gap.cursor),
+		Checked: (checked) => {
+			if (!active) return sent(checked, checked.cursor);
+			if (checked.cursor === null || checked.cursor === reached) return Effect.void;
+			return inOrder ? sent(checked, checked.cursor) : movedTo(checked.cursor);
+		},
+		Occurrence: (occurrence) => Effect.andThen(active ? Effect.void : sent(Checked.make({ cursor: reached }), reached), Effect.suspend(() => sent(occurrence, occurrence.cursor ?? reached)))
+	});
+	const resumes = (cause) => (active || resumesUnconfirmed) && !Cause.hasInterruptsOnly(cause) && refusalIn(cause) === void 0;
+	const waiting = Effect.sync(() => {
+		wait = defaultNextPoll;
+	});
+	const once = Stream.suspend(() => Duration.isZero(wait) ? open(reached) : Stream.unwrap(Effect.as(Effect.sleep(wait), open(reached)))).pipe(Stream.runForEach(delivered), Effect.catchCauseIf(resumes, (cause) => Effect.andThen(reported(cause), deliver(Failed.make({})))), Effect.andThen(waiting));
+	const heartbeat = Effect.andThen(confirmed.await, Effect.forever(Effect.andThen(Effect.sleep(heartbeatEvery), () => Effect.suspend(() => deliver(Checked.make({ cursor: reached }))))));
+	return yield* inOrder ? Effect.forever(once) : Effect.raceFirst(Effect.forever(once), heartbeat);
+});
+/**
+* A push subscription for a surface's streamed response: read into a bounded queue, each element
+* as `encode` gives it, forked in the current scope.
+*/
+const queuedPush = (open, cursor, encode, { ending = (run) => run, inOrder = false, capacity = queued } = {}) => Effect.gen(function* () {
+	const queue = yield* Queue.bounded(capacity);
+	yield* pushed(open, cursor, (sent) => Effect.flatMap(encode(sent), (element) => Queue.offer(queue, element)), {
+		resumesUnconfirmed: true,
+		inOrder
+	}).pipe(ending, Queue.into(queue), Effect.forkScoped({ startImmediately: true }));
+	return queue;
+});
+export { Failed, PushedOf, Subscription, SubscriptionOf, polledOn, pushed, queuedPush, readOn, refusalIn };

package/dist/contract/receiving.d.mts

@@ -0,0 +1,29 @@
+import "./errors.mjs";
+import "./pages.mjs";
+import "../Event.mjs";
+import { SigningSecret } from "./callback.mjs";
+import { Context, Effect, Schema, Scope } from "effect";
+/** A POST a receiver verified, its JSON body: an occurrence, or an envelope. */
+export interface Delivered {
+  readonly [key: string]: Schema.Json;
+}
+/**
+ * One watch's place at a receiver: the id its delivery URL names in `watchParameter`, and the
+ * secret to subscribe with.
+ */
+export interface Registered {
+  readonly id: string;
+  readonly secret: SigningSecret;
+}
+declare const Receiving_base: Context.ServiceClass<Receiving, "effect-actions/Receiving", {
+  readonly path: `/${string}`;
+  readonly register: (deliver: (body: Delivered) => boolean) => Effect.Effect<Registered, never, Scope.Scope>;
+}>;
+/**
+ * Where a watch by webhook receives its deliveries in this process: `Webhook.layerReceiver`
+ * provides it beside its route at `path`, and `register` keeps a watch's place for its scope,
+ * handing each verified body to `deliver`, which answers `false` while the watch has no room
+ * for it.
+ */
+export declare class Receiving extends Receiving_base {}
+export {};