@gjermundgaraba/effect-actions 0.20.0 → 0.21.0

package/dist/Authentication.d.mts

@@ -1,9 +1,10 @@
+import { Codec } from "./contract/codec.mjs";
 import { Refusal } from "./contract/errors.mjs";
 import { Known, OptionalUnless } from "./contract/implementation.mjs";
 import { Errors } from "./Action.mjs";
-import { Any, Descriptor, Provider, Security } from "./authentication/provider.mjs";
 import { ErrorsOf } from "./contract/declared.mjs";
-import { Array, Context, Effect, Layer, Option, Redacted, Scope } from "effect";
+import { Any, Descriptor, Provider, Security } from "./authentication/provider.mjs";
+import { Array, Context, Effect, Layer, Option, Redacted, Schema, Scope } from "effect";
 import { HttpRouter, HttpServerResponse } from "effect/http";
 import { HttpApiSecurity } from "effect/http-api";
 /**
@@ -13,16 +14,18 @@ import { HttpApiSecurity } from "effect/http-api";
  * which holds the header and no request; a route of the host's own is authenticated by
  * `protect`.
  */
-export declare const bearerTokenOf: (authorization: string | null | undefined) => Option.Option<Redacted.Redacted<string>>;
+export declare const bearerTokenOf: (authorization: string | null | undefined) => Option.Option<Redacted.Redacted>;
 /** An OAuth protected resource (RFC 9728), as `layer` publishes it. */
 export interface ProtectedResource {
   /**
-   * Exact OAuth resource identifier: the public URL of the endpoint clients connect to, such as
-   * `${url}/mcp`. Discovery is served at `/.well-known/oauth-protected-resource` followed by its
-   * path and query.
+   * OAuth resource identifier: the public URL of the endpoint clients connect to, such as
+   * `${url}/mcp`, or its origin, such as `https://api.example.com`, which MCP allows to name one
+   * resource for every endpoint it serves. Discovery is served at
+   * `/.well-known/oauth-protected-resource` followed by its path and query.
    *
    * **Gotchas**
    *
+   * - A client applying RFC 9728 §3.3 strictly finds no authorization server for an origin, since metadata reached from a challenge must name the URL it requested; the official MCP client accepts it, and the endpoint's URL works with both.
    * - Discovery answers 404, and an MCP client finds no authorization server, when a request's path and query differ from this URL's, or when the provider is provided to no served layer.
    * - That it and `authorizationServers` are HTTPS, or loopback HTTP in development, is the deployment's to ensure: nothing checks it.
    */
@@ -33,7 +36,7 @@ export interface ProtectedResource {
    * Every scope the resource accepts, each an OAuth scope token, which a client requests when a
    * 401 names none.
    */
-  readonly scopesSupported?: ReadonlyArray<string>;
+  readonly scopesSupported?: readonly string[];
   /**
    * The scopes every 401 names, each an OAuth scope token: what a client requests when it
    * authenticates, rather than every scope supported.
@@ -78,8 +81,8 @@ type DeclaredOf<D> = D extends {
  * naming scopes. `HttpServerResponse.toWeb` gives it as a web `Response`.
  */
 export declare const refusalResponse: <D extends Any = never>(error: Refusal | DeclaredOf<D>, options?: RefusalResponseOptions<D>) => HttpServerResponse.HttpServerResponse;
-/** What `make` takes besides the name and the identity. */
-export interface Options {
+/** What `make` takes besides the name and the identity `A`. */
+export interface Options<A = unknown> {
   /**
    * The one native scheme a caller proves the identity by, Bearer when left out: an API key in a
    * cookie, a header or the query, such as `HttpApiSecurity.apiKey({ in: "cookie", key: "session" })`,
@@ -100,7 +103,35 @@ export interface Options {
    * - A failure that is not the caller's, such as an issuer the verifier cannot reach, belongs here with `{ httpApiStatus: 503 }`: an `Unauthenticated` would have the caller sign in again.
    */
   readonly error?: Errors | Errors[number];
+  /**
+   * The stable id of an identity, such as its user id: what tells subscribers apart where a
+   * surface keeps a subscription between requests, such as an MCP poll subscription's lease.
+   *
+   * **Gotchas**
+   *
+   * - A surface serving a protected event type whose source has a `subscription` hook refuses to start without it, its message naming this option.
+   * - Two identities with one principal share those subscriptions, so give each its own: a tenant's id alone merges its users.
+   * - Without it no surface offers a protected event by webhook, which a subscription keys by its principal: the listing names no webhook, and a webhook subscription fails with `Event.SubscriptionError`, reason `Unsupported`.
+   * - Without it every caller shares one idempotency key space: another caller sending a key with the same input is given the first call's answer, as `Action.Options.idempotencyKey` says.
+   */
+  readonly principal?: ((identity: A) => string) | undefined;
+  /**
+   * The identity's schema, its `Type` the identity: how a surface keeps an identity past a
+   * restart, as `Webhook.layer` with `persist` keeps each webhook subscriber's, its JSON in the
+   * store.
+   *
+   * **Gotchas**
+   *
+   * - `Webhook.layer` with `persist` refuses to serve a protected event by webhook without it, its message naming this option.
+   */
+  readonly schema?: Codec | undefined;
 }
+type PrincipalOf<A> = NoInfer<Pick<Options<A>, "principal">>;
+type SchemaOf<O, A> = O extends {
+  readonly schema: infer S extends Schema.Top;
+} ? [S["Type"], A] extends [A, S["Type"]] ? unknown : {
+  readonly schema: "a schema whose Type is the identity's";
+} : unknown;
 type SecurityOf<O> = O extends {
   readonly security: infer S extends Security;
 } ? S : "security" extends keyof O ? NonNullable<O["security" & keyof O]> | HttpApiSecurity.Http : HttpApiSecurity.Http;
@@ -111,7 +142,7 @@ type SecurityOf<O> = O extends {
  * one name only for one declaration, whose values a server and a client may hold as `layer` says.
  * Guide: `docs/Authentication.md` in this package; in an application: `examples/notes-service/src/identity/`.
  */
-export declare const make: <const Name extends string, I, A, const O extends Options = {}>(name: Name, identity: Context.Key<I, A>, ...options: OptionalUnless<O, O & NoInfer<Known<O, Options>>>) => Descriptor<I, A, SecurityOf<O>, Name, ErrorsOf<O>>;
+export declare const make: <const Name extends string, I, A, const O extends Options<never> = {}>(name: Name, identity: Context.Key<I, A>, ...options: OptionalUnless<O, O & NoInfer<Known<O, Options>> & PrincipalOf<A> & SchemaOf<O, A>>) => Descriptor<I, A, SecurityOf<O>, Name, ErrorsOf<O>>;
 /**
  * A descriptor's verifier: the credential its scheme decodes, as Effect's own decoder gives
  * it, to the identity, or a refusal, or an error the descriptor declares, `E`. Its services
@@ -154,6 +185,7 @@ type Resource = ProtectedResource | Effect.Effect<ProtectedResource | undefined,
  * **Gotchas**
  *
  * - Call it once per descriptor, and provide that value to every layer serving a protected action: nothing else satisfies the provider they require, neither the identity nor another descriptor's provider, which type-checks under the same name and identity, then dies when the layer builds; only a client may hold another descriptor of the name, such as one of a cookie name the server decides at startup.
+ * - Over `ActionRpc` a verifier reading `HttpServerRequest` reads one holding the message's headers alone, a socket's upgrade headers before its own, at `/` with no query or body, on every protocol: one judging the URL or query sees none of the client's.
  */
 export declare function layer<const Name extends string, I, A, const S extends Security, E extends Errors, R, EX = never, RX = never, P extends Resource = undefined>(authentication: Descriptor<I, A, S, Name, E>, verify: Verify<NoInfer<A>, NoInfer<S>, R, NoInfer<E[number]["Type"]>> | Effect.Effect<Verify<NoInfer<A>, NoInfer<S>, R, NoInfer<E[number]["Type"]>>, EX, RX>, options?: {
   /** The OAuth protected resource to publish: its rules are on `LayerOptions.protectedResource`. */

package/dist/Authentication.mjs

@@ -2,11 +2,11 @@ import { Unauthenticated, builtIns, scopeToken } from "./contract/errors.mjs";
 import { assertDistinctTags, errorList } from "./contract/declared.mjs";
 import { providerOf } from "./authentication/provider.mjs";
 import { answer, answerStepUp, bearer, challenge, declaredResponse, isRefusal, isStepUp, plain } from "./authentication/refusal.mjs";
-import { Context, Effect, Layer, Match, Option, Predicate, Redacted } from "effect";
+import { Context, Effect, Function, Layer, Match, Option, Predicate, Redacted } from "effect";
 import { HttpEffect, HttpRouter, HttpServerRequest, HttpServerResponse } from "effect/http";
 import { HttpApiBuilder, HttpApiMiddleware, HttpApiSecurity } from "effect/http-api";
 // src/authentication/Authentication.ts
-const bearerAuthorizationHeader = /^[ \t]*Bearer +(.*[^ \t])[ \t]*$/i;
+const bearerAuthorizationHeader = /^[ \t]*Bearer +(?<token>.*[^ \t])[ \t]*$/iu;
 /**
 * The bearer token of an `Authorization` header, `authorization`, or none, read as Effect's
 * `HttpApiSecurity.bearer` reads it for routes and MCP: the scheme matched case-insensitively,
@@ -14,7 +14,7 @@ const bearerAuthorizationHeader = /^[ \t]*Bearer +(.*[^ \t])[ \t]*$/i;
 * which holds the header and no request; a route of the host's own is authenticated by
 * `protect`.
 */
-const bearerTokenOf = (authorization) => Option.map(Option.fromNullishOr(bearerAuthorizationHeader.exec(authorization ?? "")?.[1]), (token) => Redacted.make(token));
+const bearerTokenOf = (authorization) => Option.map(Option.fromNullishOr(bearerAuthorizationHeader.exec(authorization ?? "")?.groups?.["token"]), (token) => Redacted.make(token));
 const metadataUrlOf = (options) => {
 	const resource = new URL(options.resource);
 	const url = new URL(resource);
@@ -43,10 +43,13 @@ const assertPublishableResource = (oauth, options) => {
 	if (resource === null) throw new Error(`A protected resource is an absolute URL: ${JSON.stringify(options.resource)} is not one; give the public URL of the endpoint clients connect to, such as https://api.example.com/mcp, read from configuration`);
 	if (resource.href.includes("#")) throw new Error(`A protected resource has no fragment: ${options.resource}; drop the "#", which no request URL carries, so its discovery would never answer`);
 };
-const withNoStoreAndChallenge = (response, challenge) => HttpServerResponse.setHeaders(response, {
+const withNoStoreAndChallenge = (response, wwwAuthenticate) => HttpServerResponse.setHeaders(response, {
 	...response.headers["cache-control"] === void 0 ? { "cache-control": "no-store" } : {},
-	...challenge !== void 0 && response.status === 401 && response.headers["www-authenticate"] === void 0 ? { "www-authenticate": challenge } : {}
+	...wwwAuthenticate !== void 0 && response.status === 401 && response.headers["www-authenticate"] === void 0 ? { "www-authenticate": wwwAuthenticate } : {}
 });
+const isBearer = (security) => Predicate.isTagged(security, "Http") && security.scheme.toLowerCase() === "bearer";
+const openApiComponentKey = /^[\w.-]+$/u;
+const nonBearerChallengeOf = (security, name) => Match.value(security).pipe(Match.tag("Http", ({ scheme }) => challenge(scheme, [])), Match.tag("Basic", () => challenge("Basic", [["realm", name]])), Match.tag("ApiKey", Function.constUndefined), Match.exhaustive);
 /**
 * The response `layer` answers a refusal with, for a caller the router never routes, such as a
 * Node `upgrade` handler admitting a socket, which holds a header and no request: read its token
@@ -60,15 +63,29 @@ const refusalResponse = (error, options) => {
 	const oauth = authentication === void 0 || isBearer(authentication.security);
 	assertPublishableResource(oauth, options?.protectedResource);
 	const named = namedOf(options?.protectedResource);
-	const challenge = authentication !== void 0 && !oauth ? nonBearerChallengeOf(authentication.security, authentication.name) : bearerChallengeOf(named, presentsBearerToken(options?.authorization));
+	const wwwAuthenticate = authentication !== void 0 && !oauth ? nonBearerChallengeOf(authentication.security, authentication.name) : bearerChallengeOf(named, presentsBearerToken(options?.authorization));
 	if (!isRefusal(error)) {
 		const response = declaredResponse(authentication?.error ?? [], error);
 		if (response === void 0) throw new Error("Not a refusal, nor an error the authentication declares: pass the descriptor declaring it as `authentication`, or answer the error yourself");
-		return withNoStoreAndChallenge(response, challenge);
+		return withNoStoreAndChallenge(response, wwwAuthenticate);
 	}
-	return withNoStoreAndChallenge(oauth ? answer(error, named.metadataUrl) : plain(error), challenge);
+	return withNoStoreAndChallenge(oauth ? answer(error, named.metadataUrl) : plain(error), wwwAuthenticate);
+};
+const mayResolveToDiscoveryPath = /\.well-known|[\t\n\r]/u;
+const corsPreflight = (request) => {
+	const requested = request.headers["access-control-request-headers"];
+	return HttpServerResponse.empty({
+		status: 204,
+		headers: {
+			"access-control-allow-origin": "*",
+			"access-control-allow-methods": "GET, HEAD, OPTIONS",
+			...requested === void 0 ? {} : {
+				"access-control-allow-headers": requested,
+				vary: "Access-Control-Request-Headers"
+			}
+		}
+	});
 };
-const mayResolveToDiscoveryPath = /\.well-known|[\t\n\r]/;
 const discoveryMiddleware = (options) => {
 	const discoveryUrl = metadataUrlOf(options);
 	const target = discoveryUrl.href.slice(discoveryUrl.origin.length);
@@ -79,20 +96,6 @@ const discoveryMiddleware = (options) => {
 		scopes_supported: options.scopesSupported,
 		resource_name: options.resourceName
 	}, { headers: { "access-control-allow-origin": "*" } });
-	const corsPreflight = (request) => {
-		const requested = request.headers["access-control-request-headers"];
-		return HttpServerResponse.empty({
-			status: 204,
-			headers: {
-				"access-control-allow-origin": "*",
-				"access-control-allow-methods": "GET, HEAD, OPTIONS",
-				...requested === void 0 ? {} : {
-					"access-control-allow-headers": requested,
-					vary: "Access-Control-Request-Headers"
-				}
-			}
-		});
-	};
 	return (next) => Effect.flatMap(HttpServerRequest.HttpServerRequest, (request) => {
 		const targeted = mayResolveToDiscoveryPath.test(request.url) && URL.canParse(request.url, discoveryUrl.origin) && new URL(request.url, discoveryUrl.origin).href.slice(discoveryUrl.origin.length) === target;
 		if (targeted && (request.method === "GET" || request.method === "HEAD")) return Effect.succeed(metadata);
@@ -109,9 +112,6 @@ const resourceAnswersOf = (options) => {
 		published: options === void 0 ? void 0 : discoveryMiddleware(options)
 	};
 };
-const isBearer = (security) => Predicate.isTagged(security, "Http") && security.scheme.toLowerCase() === "bearer";
-const openApiComponentKey = /^[\w.-]+$/;
-const nonBearerChallengeOf = (security, name) => Match.value(security).pipe(Match.tag("Http", ({ scheme }) => challenge(scheme, [])), Match.tag("Basic", () => challenge("Basic", [["realm", name]])), Match.tag("ApiKey", () => void 0), Match.exhaustive);
 /**
 * Browser-safe declaration shared by clients and remote surfaces: the `identity` it
 * authenticates, and the scheme a caller proves it by, `Options.security`. The literal name
@@ -122,6 +122,8 @@ const nonBearerChallengeOf = (security, name) => Match.value(security).pipe(Matc
 const make = (name, identity, ...options) => {
 	const security = options[0]?.security ?? HttpApiSecurity.bearer;
 	const error = errorList(options[0]?.error);
+	const principal = options[0]?.principal;
+	const schema = options[0]?.schema;
 	if (!openApiComponentKey.test(name)) throw new Error(`Invalid authentication name: ${JSON.stringify(name)}, not an OpenAPI key: use only letters, digits, "_", "." and "-"`);
 	assertDistinctTags(`Authentication "${name}"`, [...builtIns, ...error]);
 	if (!Predicate.isTagged(security, "Http") && !Predicate.isTagged(security, "ApiKey") && !Predicate.isTagged(security, "Basic")) throw new Error("Authentication takes one native HttpApiSecurity scheme as `security`: omit it for Bearer, or give one scheme, such as `HttpApiSecurity.basic`, never a record of them");
@@ -130,6 +132,8 @@ const make = (name, identity, ...options) => {
 		identity,
 		security,
 		error,
+		...principal === void 0 ? {} : { principal },
+		...schema === void 0 ? {} : { schema },
 		"~provider": Context.Service(`effect-actions/Authentication/Provider/${name}`),
 		"~middleware": HttpApiMiddleware.Service()(`effect-actions/Authentication/Security/${name}`, { security: { [name]: security } }),
 		"~verified": Context.Service(`effect-actions/Authentication/Verified/${name}`)
@@ -139,7 +143,7 @@ const presented = (credential) => Redacted.isRedacted(credential) ? Redacted.val
 function layer(authentication, verify, options = {}) {
 	const { security } = authentication;
 	const oauth = isBearer(security);
-	const protectedResource = options.protectedResource;
+	const { protectedResource } = options;
 	assertPublishableResource(oauth, protectedResource);
 	const resource = Effect.isEffect(protectedResource) ? Effect.map(protectedResource, (built) => {
 		assertPublishableResource(oauth, built);
@@ -153,17 +157,20 @@ function layer(authentication, verify, options = {}) {
 		if (!Predicate.isFunction(verifier)) return yield* Effect.die(/* @__PURE__ */ new Error("Missing verify: pass a verify function, or an Effect building one"));
 		const authenticate = (credential) => presented(credential) ? verifier(credential) : Effect.fail(missing);
 		const noStoreOnFailure = HttpEffect.appendPreResponseHandler((_request, response) => Effect.succeed(HttpServerResponse.setHeader(response, "cache-control", "no-store")));
-		const challengeOf = (credential) => !oauth ? nonBearerChallengeOf(security, authentication.name) : presented(credential) ? invalid : anonymous;
+		const challengeOf = (credential) => {
+			if (!oauth) return nonBearerChallengeOf(security, authentication.name);
+			return presented(credential) ? invalid : anonymous;
+		};
 		const refuse = (error) => isRefusal(error) ? Effect.succeed(oauth ? answer(error, metadataUrl) : plain(error)) : Effect.suspend(() => {
 			const response = declaredResponse(authentication.error, error);
 			return response === void 0 ? Effect.die(error) : Effect.succeed(response);
 		});
 		const verified = (credential, route, slot) => {
-			const challenge = challengeOf(credential);
+			const wwwAuthenticate = challengeOf(credential);
 			return Effect.matchEffect(authenticate(credential), {
 				onFailure: refuse,
 				onSuccess: (actor) => Effect.provideService(route, slot, actor)
-			}).pipe(Effect.onError(() => noStoreOnFailure), HttpEffect.withPreResponseHandler((_request, response) => Effect.succeed(withNoStoreAndChallenge(response, challenge))));
+			}).pipe(Effect.onError(() => noStoreOnFailure), HttpEffect.withPreResponseHandler((_request, response) => Effect.succeed(withNoStoreAndChallenge(response, wwwAuthenticate))));
 		};
 		return {
 			descriptor: authentication,

package/dist/Event.d.mts

@@ -0,0 +1,370 @@
+import { Codec, CodecOf, Fields, NoInput } from "./contract/codec.mjs";
+import { Refusal } from "./contract/errors.mjs";
+import { Gap, OccurrenceSchema } from "./contract/occurrence.mjs";
+import { AnyEventImplementation, EventImplementation } from "./contract/feed.mjs";
+import { Listed, LogStorage } from "./contract/log.mjs";
+import { Events, KeyOptions, MakeEventsOptions, RevisionStorage, layerMemory, makeEvents } from "./contract/hub.mjs";
+import { Protected } from "./contract/implementation.mjs";
+import { Authorizer, Deferred as Deferred$1 } from "./contract/authorizer.mjs";
+import { Options as Options$1 } from "./Action.mjs";
+import { DateTime, Duration, Effect, Schema, Scope, Stream } from "effect";
+declare const TypeId = "~@gjermundgaraba/effect-actions/Event";
+/** What `make` needs to define an event type. */
+export interface Options {
+  /**
+   * Who may subscribe: `Action.Anyone`, or the identity service a subscriber must have, as an
+   * action's `caller` says; the rules of an identity are on `Action.Options.caller`.
+   */
+  readonly caller: Options$1["caller"];
+  /** What happens when the event fires; a model and a CLI user read it beside the event's name. */
+  readonly description: string;
+  /**
+   * The subscription's arguments, a schema or struct fields, as an action's `input` is: they may
+   * filter the occurrences, shape them, or configure the subscription. Omit for an event without
+   * arguments. Its rules are `Action.Options.input`'s.
+   */
+  readonly input?: Codec | Fields | undefined;
+  /**
+   * What each occurrence carries, a schema or struct fields: an object, since MCP sends it as an
+   * occurrence's `data`.
+   */
+  readonly payload: Codec | Fields;
+}
+type OnlyOptions<O> = { readonly [K in Exclude<O extends unknown ? keyof O : never, keyof Options>]: never; };
+type Rules<O> = Options extends O ? unknown : OnlyOptions<O>;
+type InputOf<O> = O extends {
+  readonly input?: infer I;
+} ? CodecOf<Extract<Exclude<I, undefined>, Codec | Fields>> | ([undefined] extends [I] ? typeof NoInput : never) : typeof NoInput;
+type PayloadOf<O> = O extends {
+  readonly payload: infer P extends Codec | Fields;
+} ? CodecOf<P> : never;
+/**
+ * A pure contract for something that happens, bound to its source by `implement`: subscribers
+ * receive its occurrences, each carrying a `payload`, filtered and shaped by the subscription's
+ * `input`. Its `name`, `input` and `payload` are public: reuse them, as in
+ * `Schema.Array(NoteCreated.payload)`.
+ */
+export interface Event<Name extends string, Input extends Codec, Payload extends Codec, Caller extends Options["caller"] = Options["caller"]> {
+  readonly [TypeId]: typeof TypeId;
+  readonly caller: Caller;
+  readonly name: Name;
+  readonly description: string;
+  /** The subscription's arguments as a schema, a `Schema.Struct` where fields were given. */
+  readonly input: Input;
+  /** What each occurrence carries, as a schema. */
+  readonly payload: Payload;
+}
+/** Any event type, with its schemas erased. */
+export type Any = Event<string, Codec, Codec>;
+/** Whether `u` is an event type `make` defined: a binding's list tells events from actions by it. */
+export declare const isEvent: (u: unknown) => u is Any;
+/**
+ * Define an event type: what a subscription takes, what each occurrence carries, and who may
+ * subscribe. A surface serving it names it by `name`.
+ * Guide: `docs/Event.md` in this package; in an application: `examples/build-events/src/builds/`.
+ *
+ * **Gotchas**
+ *
+ * - A name is lowercase segments joined by dots, `note.created`: its form is in the message `Invalid event name` throws; it is unique among the events each surface serves, apart from action names.
+ * - Surfaces match an implementation to a contract by object identity, never by name, as for actions.
+ */
+export declare function make<const Name extends string, const O extends Options>(name: Name, options: O & NoInfer<Rules<O>>): Event<Name, InputOf<O>, PayloadOf<O>, O["caller"]>;
+/**
+ * One occurrence as a source produces it: its `data`, and optionally the upstream's own id, which
+ * subscribers deduplicate by, and when it happened. Without them, a log source's occurrence
+ * takes its cursor as its id and the time it was appended, the same on every read; a check's
+ * takes a generated id and the time it is read.
+ */
+export interface Emitted<E extends Any> {
+  readonly data: E["payload"]["Type"];
+  /**
+   * A stable id: give the upstream's own, such as a message or delivery id, so a retry or a replay repeats it.
+   *
+   * **Gotchas**
+   *
+   * - An id given again for another occurrence is dropped as a duplicate by a `watch` and by `Webhook.layerReceiver`, each keeping its last 1,000: an id from a counter that restarts with the process repeats, so leave it out rather than give one.
+   */
+  readonly eventId?: string | undefined;
+  readonly timestamp?: DateTime.Utc | undefined;
+}
+/**
+ * What a check answers for a cursor: the occurrences since it, and the cursor after them.
+ *
+ * **Gotchas**
+ *
+ * - A cursor the upstream no longer serves, such as one older than its retention, is answered with `truncated: true` and a fresh cursor: the subscriber then knows it missed occurrences.
+ * - A `nextPoll` under a second is read as a second, and one over 5 minutes, `Duration.infinity` included, as 5 minutes, by the server's loop and by a polling client alike.
+ */
+export interface Page<E extends Any> {
+  readonly events: ReadonlyArray<Emitted<E>>;
+  readonly cursor: string;
+  readonly truncated?: boolean | undefined;
+  /** More occurrences are ready: the subscriber asks again without waiting. */
+  readonly hasMore?: boolean | undefined;
+  /** How long a subscriber waits before it asks again; defaults to 5 seconds. */
+  readonly nextPoll?: Duration.Input | undefined;
+}
+interface Hooked<E extends Any, R> {
+  /**
+   * What a subscription needs set up upstream while it lasts, such as joining a channel: a scoped
+   * Effect, whose finalizer tears it down, run as the subscriber. A stream's lasts as long as the
+   * stream, a poll subscription's until `lease` after its last poll, or, watched in process, until
+   * the watch ends, and a webhook subscription's until it is unsubscribed or lapses, set up again
+   * as `persist` restores it.
+   *
+   * **Gotchas**
+   *
+   * - Write it so it may run twice for one subscription: a lease does not outlive the process, so a poll after a restart sets it up again.
+   * - A poll subscription's runs in its first poll's context, that request included, held until its lease ends, where a webhook subscription's runs without the request: read what it needs from the request in middleware, which provides it as a service.
+   */
+  readonly subscription?: ((input: E["input"]["Type"]) => Effect.Effect<void, never, R | Scope.Scope>) | undefined;
+  /** How long a poll subscription's `subscription` lasts after its last poll; defaults to 5 minutes. */
+  readonly lease?: Duration.Input | undefined;
+  /**
+   * The key a subscriber of `input` is reached by, run as the subscriber, such as the room it
+   * follows: `Events.notify` and `Events.publish` given a key reach the subscribers of that key
+   * alone, and those it answers `undefined` for, who follow every key. Without it, every
+   * announcement reaches every subscriber.
+   *
+   * **Gotchas**
+   *
+   * - An occurrence a log's `emit` gives without a `key` reaches every subscriber, whatever key it follows: give each one its key.
+   */
+  readonly key?: ((input: E["input"]["Type"]) => string | undefined | Effect.Effect<string | undefined, never, R>) | undefined;
+}
+/**
+ * An event type read from an upstream that can be asked what happened since a cursor, such as a
+ * change feed or a history API: one function answers every subscriber, whatever the surface.
+ *
+ * **Gotchas**
+ *
+ * - An occurrence without `eventId` takes a fresh id at each read, and a page's occurrences before its last are read again from the cursor asked after a reconnect mid-page: give the upstream's ids, or a subscriber receives them again under ids no `watch` drops.
+ */
+export interface Check<E extends Any, R = never> extends Hooked<E, R> {
+  /**
+   * What happened since `cursor`, as the subscriber's `input` selects it, run as the subscriber.
+   * A `null` cursor is a subscriber with no position: answer nothing, so it starts after the last
+   * occurrence. An event whose occurrence is the whole value, such as a status, is a `Current`.
+   */
+  readonly check: (input: E["input"]["Type"], cursor: string | null) => Effect.Effect<Page<E>, Refusal, R>;
+  readonly log?: never;
+  readonly current?: never;
+}
+/**
+ * An event type whose occurrence is the whole value, such as a status or a list small enough to
+ * send whole: a subscriber receives the value as it is first, then again after each
+ * `Events.notify` that reaches it, never a change it missed one by one. The library keeps a
+ * revision per key, which each such notify moves, as the cursor and each occurrence's id.
+ *
+ * **Gotchas**
+ *
+ * - A notify without a change sends the value again, under a new id: notify after a write that changed it.
+ * - The revision is read before `current`, so a value written between them is sent again at the next read, never missed: write the value, then notify.
+ */
+export interface Current<E extends Any, R = never> extends Hooked<E, R> {
+  /** The value as it is, as the subscriber's `input` selects it, run as the subscriber. */
+  readonly current: (input: E["input"]["Type"]) => Effect.Effect<E["payload"]["Type"], Refusal, R>;
+  readonly check?: never;
+  readonly log?: never;
+}
+/**
+ * An event type whose occurrences the library keeps as they are announced, for an upstream with
+ * no history of its own: `Events.publish` appends each, and `log.emit`, where given, a stream of
+ * them. Each subscriber receives the occurrences its `match` accepts, shaped by its `transform`.
+ *
+ * **Gotchas**
+ *
+ * - A cursor is only good where the log that minted it lives, for as long as it keeps its occurrences: after a restart, or once they are dropped, a subscriber resuming from it receives `truncated` and a fresh cursor.
+ * - A subscriber reading slower than occurrences arrive falls behind the log like a resumed one: it receives `truncated`, never a backlog held for it alone.
+ * - An `emit` stream is consumed from startup, in the server's scope, by one build at a time, until it ends, even past its build's release: a failure ends it and is reported, an end is logged, and the next held build's stream, if any, takes over; the log then holds what was published.
+ */
+export interface Log<E extends Any, R = never> extends Hooked<E, R> {
+  /** What the log keeps, and the stream feeding it besides `Events.publish`; `{}` for none. */
+  readonly log: LogOptions<E>;
+  /** Whether a subscriber of `input` receives an occurrence carrying `data`; defaults to every one. */
+  readonly match?: ((input: E["input"]["Type"], data: E["payload"]["Type"]) => boolean | Effect.Effect<boolean, never, R>) | undefined;
+  /** The data a subscriber of `input` receives in place of `data`, such as one with fields removed. */
+  readonly transform?: ((input: E["input"]["Type"], data: E["payload"]["Type"]) => E["payload"]["Type"] | Effect.Effect<E["payload"]["Type"], never, R>) | undefined;
+  readonly check?: never;
+  readonly current?: never;
+}
+/** What a log source keeps, and what feeds it besides `Events.publish`. */
+export interface LogOptions<E extends Any> {
+  /**
+   * A stream of occurrences, such as a message bus's, appended as they arrive from startup, each
+   * reaching the subscribers of its `key`, as `Events.publish` given one does.
+   */
+  readonly emit?: Stream.Stream<Emitted<E> & KeyOptions> | undefined;
+  /**
+   * How long an occurrence is kept for subscribers resuming from a cursor; defaults to 10 minutes.
+   * The first build attached to its log sets it, and later builds share that log.
+   */
+  readonly maxAge?: Duration.Input | undefined;
+  /**
+   * How many occurrences are kept at most, of every key together; defaults to 10,000.
+   *
+   * **Gotchas**
+   *
+   * - A busy key drops a quiet one's occurrences too: a subscriber of the quiet key resuming after them receives a gap, though none of its own was dropped.
+   */
+  readonly maxEvents?: number | undefined;
+}
+/** Where an event type's occurrences come from: exactly one of `check`, `current` or `log`. */
+export type Source<E extends Any, R = never> = Check<E, R> | Current<E, R> | Log<E, R>;
+/**
+ * One occurrence as a subscriber receives it: `eventId`, the source's id or one generated, which
+ * a subscriber deduplicates by; `cursor`, where to resume after it, `null` for an event type that
+ * cannot be resumed.
+ */
+export type Occurrence<E extends Any> = OccurrenceSchema<E>["Type"];
+/** What a subscriber receives: occurrences, and gaps where it missed some. */
+export type Received<E extends Any> = Occurrence<E> | Gap;
+declare const NotServed_base: Schema.Class<NotServed, Schema.TaggedStruct<"NotServed", {}>, import("effect/Cause").YieldableError & {
+  readonly brand: unique symbol;
+}>;
+/** The server serves no event type of that name, or no longer does. */
+export declare class NotServed extends NotServed_base {}
+declare const Unsupported_base: Schema.Class<Unsupported, Schema.TaggedStruct<"Unsupported", {
+  readonly feature: Schema.String;
+  readonly value: Schema.optional<Schema.String>;
+}>, import("effect/Cause").YieldableError & {
+  readonly brand: unique symbol;
+}>;
+/**
+ * The server serves the event type, but not as asked: `feature` names what it does not offer,
+ * such as `deliveryMode`, and `value` which one, such as `push`.
+ */
+export declare class Unsupported extends Unsupported_base {}
+/**
+ * Why a webhook's callback endpoint failed, in SEP-3415's categories: it refused the connection
+ * or was unreachable, timed out, failed TLS, answered a status from 300 to 499 (`http_4xx`, as
+ * the categories name no 3xx) or a 5xx, or did not echo the verification challenge.
+ */
+export declare const CallbackCategory: Schema.Literals<readonly ["connection_refused", "timeout", "tls_error", "http_4xx", "http_5xx", "challenge_failed"]>;
+export type CallbackCategory = typeof CallbackCategory.Type;
+declare const CallbackFailed_base: Schema.Class<CallbackFailed, Schema.TaggedStruct<"CallbackFailed", {
+  readonly category: Schema.Literals<readonly ["connection_refused", "timeout", "tls_error", "http_4xx", "http_5xx", "challenge_failed"]>;
+}>, import("effect/Cause").YieldableError & {
+  readonly brand: unique symbol;
+}>;
+/** A webhook subscription's callback endpoint failed its verification, or was unreachable. */
+export declare class CallbackFailed extends CallbackFailed_base {}
+declare const NotSubscribed_base: Schema.Class<NotSubscribed, Schema.TaggedStruct<"NotSubscribed", {}>, import("effect/Cause").YieldableError & {
+  readonly brand: unique symbol;
+}>;
+/** No webhook subscription matches the one an unsubscribe names. */
+export declare class NotSubscribed extends NotSubscribed_base {}
+declare const Reason: Schema.Union<readonly [typeof NotServed, typeof Unsupported, typeof CallbackFailed, typeof NotSubscribed]>;
+declare const SubscriptionError_base: Schema.Class<SubscriptionError, Schema.TaggedStruct<"SubscriptionError", {
+  readonly event: Schema.String;
+  readonly reason: Schema.Union<readonly [typeof NotServed, typeof Unsupported, typeof CallbackFailed, typeof NotSubscribed]>;
+  readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError & {
+  readonly brand: unique symbol;
+}>;
+/**
+ * A subscription that cannot start or go on: `reason` says why, so a subscriber branches on it
+ * with `Effect.catchReason("SubscriptionError", "NotServed", ...)`; `message` names the event and
+ * the reason. A refusal is `Action.Unauthenticated` or `Action.Forbidden`, and input that does not
+ * decode `Action.InvalidInput`, as for an action.
+ */
+export declare class SubscriptionError extends SubscriptionError_base {
+  /** The error for `event` failing with `reason`, its message built from both. */
+  static of(event: string, reason: (typeof Reason)["Type"]): SubscriptionError;
+}
+/**
+ * Where a watch keeps its cursor: what it kept under a key, and keeping a new one; a failure `E`
+ * of either ends the watch with it.
+ */
+export interface CursorStore<E = never> {
+  readonly get: (key: string) => Effect.Effect<string | undefined, E>;
+  readonly set: (key: string, cursor: string) => Effect.Effect<void, E>;
+}
+declare const WebhookDelivery_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => Readonly<A> & {
+  readonly _tag: "WebhookDelivery";
+} & import("effect/Pipeable").Pipeable;
+/**
+ * A watch delivered by webhook, which `Webhook.delivery` makes: the server POSTs each occurrence
+ * to the route `Webhook.layerReceiver` serves in the watching process, reached under `baseUrl`,
+ * for as long as the watch is read, each grant asking for `ttl`.
+ */
+export declare class WebhookDelivery extends WebhookDelivery_base<{
+  /**
+   * The https URL the server reaches the watching process at: its `layerReceiver` route's path
+   * is appended to it, `https://notifier.example.com` with `/hooks/builds` delivering to
+   * `https://notifier.example.com/hooks/builds`.
+   */
+  readonly baseUrl: string;
+  /** The lifetime each subscribe asks for; omitted, the server's longest. */
+  readonly ttl?: Duration.Input | undefined;
+}> {}
+/**
+ * How a client watches an event type; `E` is what its `resume` store fails with.
+ *
+ * **Gotchas**
+ *
+ * - Each run of a watch's stream starts from these options, a retry or a repeat included: to go on where a failed run stopped, give `resume`, which every run reads.
+ * - `resume` keeps an occurrence's cursor once the next is pulled, so a consumer stopped while handling one receives it again: deduplicate by `eventId` where that matters.
+ */
+export interface WatchOptions<E = never> {
+  /** Where to start: a cursor an occurrence or a gap carried; defaults to now. */
+  readonly cursor?: string | null | undefined;
+  /**
+   * `"stream"` holds one subscription open, `"poll"` asks again and again, and a
+   * `Webhook.delivery` has the server POST each occurrence to a receiver this process serves,
+   * which the watch then requires; left out, a watch streams where its surface can and polls
+   * where the server serves the event by poll alone.
+   */
+  readonly mode?: "stream" | "poll" | WebhookDelivery | undefined;
+  /**
+   * Where to keep the cursor between watches, such as across restarts: it starts from the cursor
+   * kept under `key`, when no `cursor` is given, and keeps each new one there. Effect's
+   * `KeyValueStore` is one: `{ store: yield* KeyValueStore.KeyValueStore, key: "builds" }`.
+   */
+  readonly resume?: {
+    readonly store: CursorStore<E>;
+    readonly key: string;
+  } | undefined;
+}
+/**
+ * Authorization for protected event types: it refuses, and fails with nothing else. It runs for
+ * every subscription of a protected event type, before its source.
+ */
+export type Authorize<E extends Any, R = never> = (event: E) => Effect.Effect<void, Refusal, R>;
+/** Every authenticated subscriber may subscribe to a protected event type. */
+export declare const allowAll: Authorize<Any>;
+type Target = Any | readonly Any[];
+type EventsOf<T extends Target> = T extends readonly Any[] ? T[number] : Extract<T, Any>;
+type TakesNoAuthorize<T extends Target> = [Protected<EventsOf<T>>] extends [never] ? unknown : "A protected event takes { authorize }: your rule, or Event.allowAll";
+type NamesOf<T extends Target> = EventsOf<T>["name"];
+type SourcesOf<T extends Target, R, RequestServices> = T extends Any ? Check<T, R> | Current<T, R> | Log<T, R> : { readonly [K in keyof RequestServices]: K extends NamesOf<T> ? Check<Extract<EventsOf<T>, {
+  readonly name: K;
+}>, RequestServices[K]> | Current<Extract<EventsOf<T>, {
+  readonly name: K;
+}>, RequestServices[K]> | Log<Extract<EventsOf<T>, {
+  readonly name: K;
+}>, RequestServices[K]> : never; };
+type Implemented<T extends Target, RequestServices, R, EX, RX, RA, EAX, RAX> = EventImplementation<EventsOf<T>, { readonly [K in NamesOf<T>]: Exclude<T extends readonly Any[] ? RequestServices[K & keyof RequestServices] : R, Scope.Scope>; }, Deferred$1<EX>, Deferred$1<Exclude<RX, Scope.Scope>> | Events, Exclude<RA, Scope.Scope>, Deferred$1<EAX>, Deferred$1<Exclude<RAX, Scope.Scope>>>;
+/**
+ * Bind sources to event types, behind authorization: one event type and its source, or a list
+ * and a record of sources keyed by event name, given directly or built by an Effect whose
+ * services are startup requirements, while what a source yields per subscriber is a request-time
+ * requirement. `authorize` is required when the list holds a protected event type. Every surface
+ * serving events takes the implementation it returns, beside action implementations in one list.
+ *
+ * **Gotchas**
+ *
+ * - The builder runs once per layer graph, however many surfaces serve it, as the first event type a surface serves attaches; a log source's `emit` starts being consumed once its event type is served or watched, and an event type no surface serves starts nothing.
+ * - `check`, `current`, `match`, `transform`, `key` and `subscription` run as the subscriber: what they yield, such as the caller, is resolved per subscription.
+ * - A source holds exactly one of `check`, `current` or `log`, checked as a surface serving its event type builds, which fails otherwise: a source of an event type no surface serves is not checked.
+ * - Serving or watching an event type needs `Event.Events`, which its source attaches to as it builds: provide `Event.layerMemory` once, around the handlers announcing and the surfaces serving.
+ * - An occurrence whose data breaks the event's payload is reported, and every surface sends a `Gap` in its place, a poll's page `truncated`: the rest of its page is still delivered.
+ * - A read failing with no refusal is reported once, and the subscription reads on from where it reached: a stream a server holds, a webhook's and `Action.client`'s `watch` after 5 seconds, a client's poll, which a server answers with an error, after its reconnect backoff, from 1 second doubling to 30; a refusal ends the subscription.
+ */
+export declare function implement<const T extends Target, RequestServices extends (T extends readonly Any[] ? { readonly [K in NamesOf<T>]: unknown; } : never), R = never, EX = never, RX = never, RA = never, EAX = never, RAX = never>(events: T, sources: SourcesOf<T, R, RequestServices> | Effect.Effect<SourcesOf<T, R, RequestServices>, EX, RX>, options: [Protected<EventsOf<T>>] extends [never] ? {
+  readonly authorize?: "A public-only target takes no authorize";
+} | undefined : {
+  readonly authorize: Authorizer<Protected<EventsOf<T>>, RA, EAX, RAX>;
+}): Implemented<T, RequestServices, R, EX, RX, RA, EAX, RAX>;
+export declare function implement<const T extends Target, RequestServices extends (T extends readonly Any[] ? { readonly [K in NamesOf<T>]: unknown; } : never), R = never, EX = never, RX = never>(events: T & TakesNoAuthorize<T>, sources: SourcesOf<T, R, RequestServices> | Effect.Effect<SourcesOf<T, R, RequestServices>, EX, RX>): Implemented<T, RequestServices, R, EX, RX, never, never, never>;
+export { type AnyEventImplementation as AnyImplementation, Events, Gap, type EventImplementation as Implementation, type KeyOptions, type Listed, type LogStorage, type MakeEventsOptions, type RevisionStorage, layerMemory, makeEvents };