holon-sh 0.0.1-dev.12 → 0.0.1-dev.14

package/src/ext/events.ts

@@ -1,19 +1,14 @@
 // The server side of MCP Events, as the Triggers & Events Working Group's design sketch defines it:
 // https://github.com/modelcontextprotocol/experimental-ext-triggers-events/blob/main/docs/design-sketch-proposal.md
-// The draft is experimental, so this lives under ext and may change with it.
-// It serves the poll and push delivery modes, and webhook delivery when given a webhookTtl, from a module of its own
-// that reaches the event types through the internals below. Names follow the sketch, and types are the MCP SDK's own
-// wherever it has them.
+// The draft is experimental, so this lives under ext and may change with it. It serves the poll and push delivery
+// modes. Names follow the sketch, and types are the MCP SDK's own wherever it has them.
 import { ProtocolError, ProtocolErrorCode, SUBSCRIPTION_ID_META_KEY } from "@modelcontextprotocol/server";
 import type { AuthInfo, JSONRPCErrorResponse, McpServer, Server, StandardSchemaWithJSON } from "@modelcontextprotocol/server";
-import { webhooks, type WebhookOptions } from "./webhooks.js";
-
-export type { WebhookOptions } from "./webhooks.js";
 
 /** The request a subscription came in, as Holon admitted it: read its caller with getContext. */
 export type SubscriptionContext = { authInfo?: AuthInfo | undefined } | undefined;
 /** How a subscription receives its events. */
-export type DeliveryModeName = "poll" | "push" | (string & {});
+export type DeliveryModeName = "poll" | "push";
 /** A JSON-RPC error, as a subscription that is terminated or fails is told it. */
 export type EventError = JSONRPCErrorResponse["error"];
 /** A subscription as it begins: who asked, for what, and by which delivery mode. */
@@ -39,27 +34,7 @@ export interface EventOccurrence<D = unknown> {
   /** When it happened, in ISO 8601. */
   timestamp: string;
   data: D;
-  cursor?: string | null;
-  _meta?: Record<string, unknown>;
-}
-/**
- * What happened after a cursor, as a check function finds it: the sketch's EventResult. Each event is an
- * EventOccurrence whose name is the type's, and whose `eventId` (the source's own, so a client drops one it has seen)
- * and `timestamp` are made up when not given. An event's `cursor`, the position just after it, lets a batch be cut
- * short; without it a batch is delivered whole.
- */
-export interface EventResult<D> {
-  /**
-   * Empty when the cursor was null: a null cursor asks only for the current position. A source without positions
-   * answers with a null cursor, is asked with null each time, and answers each time with what is new.
-   */
-  events: Array<Omit<EventOccurrence<D>, "name" | "eventId" | "timestamp" | "cursor"> & { eventId?: string; timestamp?: string; cursor?: string }>;
-  /** The position after these events, or null when the source cannot be resumed from a position. */
-  cursor: string | null;
-  /** Events between the cursor and these were skipped, for instance because the source no longer keeps them. */
-  truncated?: boolean;
-  /** More events are ready at once after this batch. */
-  hasMore?: boolean;
+  cursor?: string;
 }
 /** An event type: the arguments a subscription gives, and the data each occurrence carries. */
 export interface EventDefinition<A, D> {
@@ -79,14 +54,7 @@ export interface EventDefinition<A, D> {
   match?: (data: D, args: A, context: SubscriptionContext) => boolean;
   /** The data a subscription with these arguments receives of an emitted event. Without it, the data as emitted. */
   transform?: (data: D, args: A, context: SubscriptionContext) => unknown;
-  /**
-   * What happened after a cursor, for a source that keeps its own history: polls are answered by it, and streams ask
-   * it every second. The cursor is the source's own, so it outlives the process. A null cursor asks for the
-   * current position. The function filters and shapes for the arguments itself; `match` and `transform` apply only to
-   * what is emitted. Without it, emitted events are kept in memory and polls and streams are served from there.
-   */
-  check?: (cursor: string | null, args: A, context: SubscriptionContext) => EventResult<D> | Promise<EventResult<D>>;
-  /** The delivery modes this event type offers. Every mode served unless given, except webhook for a type with a check function, which webhook delivery does not read. */
+  /** The delivery modes this event type offers: poll and push unless given. */
   delivery?: DeliveryModeName[];
   /**
    * Whether the caller may subscribe with these arguments. A subscription is refused with Forbidden when it may not,
@@ -107,86 +75,83 @@ export interface EventDefinition<A, D> {
   onUnsubscribe?: (subscription: Subscription<A>) => void | Promise<void>;
 }
 /** Emits occurrences of one event type to the subscriptions they match, and ends its subscriptions. */
-export interface Emitter<D> {
+export interface Emitter<D, A = unknown> {
   /**
    * `eventId` lets a client drop an occurrence it has seen. Give the source's own id when it has one. With
-   * `subscriptionId`, the sketch's targeted emit, the occurrence goes to that subscription alone, whatever its arguments; it is kept like any
-   * other, so a subscription that reconnects or polls again from its cursor still has it, or is told of a gap. An
-   * event type with a check function pushes what it emits to open streams at once and does not keep it: polls and
-   * reconnecting streams learn of it from the check function, and one emitted to a subscription that does not get it
-   * on a stream is lost, so that subscription's next poll or stream is told of a gap.
+   * `subscriptionId`, the sketch's targeted emit, the occurrence goes to that subscription alone, whatever its
+   * arguments; it is kept like any other, so a subscription that reconnects or polls again from its cursor still has
+   * it, or is told of a gap.
    *
    * Emitting is synchronous. Occurrences emitted one after another in the same synchronous run reach each
    * subscription in that order, with no other occurrence of this type between them, whether polled or pushed. So a
    * group of changes that nothing may come between is either emitted in one run or sent as one occurrence holding a
    * list. A subscription skips part of a group only when it is told of a gap: the group outgrew the events kept, or
-   * the subscription fell behind them. For a type with a check function the order holds among what is emitted, but
-   * not between what is emitted and what the check function finds, which may arrive later or again.
+   * the subscription fell behind them.
    *
    * The data is serialised when it is emitted, so data that cannot be sent as JSON throws here, before anything is
    * kept or sent.
    */
   emit(data: D, options?: { eventId?: string; timestamp?: string; subscriptionId?: string }): void;
   /**
-   * The position after the last occurrence emitted, for a type without a check function. Return it with the state
-   * a tool reads, in the same synchronous run, and a client that subscribes from it hears every change after that
-   * state and none before. A type with a check function has no such position here: its cursor is the source's own,
-   * so read the source's head instead. This throws for such a type.
+   * The position after the last occurrence emitted. Return it with the state a tool reads, in the same synchronous
+   * run, and a client that subscribes from it hears every change after that state and none before.
    */
   cursor(): string;
   /**
-   * Terminates one subscription, or all of this type's: a stream is sent `notifications/events/terminated` with
-   * `error` and closed, and the next poll is answered with it. Forbidden unless given.
+   * Terminates one subscription, or all of this type's: a stream is sent what was emitted to it before, then
+   * `notifications/events/terminated` with `error`, and closed. The next poll is answered with the error. Forbidden
+   * unless given, which ends delivery at once, since access is lost.
    */
   terminate(subscriptionId?: string, error?: EventError): void;
   /**
    * Stops offering this event type: its subscriptions end with NotFound.
    */
   remove(): void;
-}
-export interface EventsOptions {
   /**
-   * The sketch's webhook_ttl, which turns webhook delivery on: the longest lifetime granted to a webhook
-   * subscription, in milliseconds. A client's suggestion is held to it, and every grant expires. Without it, webhook
-   * delivery is not offered.
+   * Keeps a value for each subscriber, such as its status, for as long as it subscribes. A subscriber is named by its
+   * subscription's arguments, so give each one its own, such as an id its client makes: subscriptions with the same
+   * arguments, such as one client's overlapping streams, are one subscriber. `told` makes the data emitted when a
+   * value is set, and, given none, when it leaves.
    */
-  webhookTtl?: number;
-  /** For tests of webhook delivery. */
-  webhook?: WebhookOptions;
+  presence<V>(told: (args: A, value: V | undefined) => D): Presence<A, V>;
 }
-/** A delivery mode besides poll and push: webhook. It registers its requests on each server and is listed by events/list. Not for applications. */
-export interface DeliveryMode {
-  readonly name: string;
-  serve(server: object, internals: Internals): void;
+/** Each subscriber's value, kept while it subscribes. */
+export interface Presence<A, V> {
+  /**
+   * Sets the value of the subscriber these arguments name, and emits it. It stays while a subscription with these
+   * arguments is open, by either delivery mode, and leaves `linger` milliseconds after the last one ends or after it is
+   * last set, whichever is later. So a subscriber that reconnects within the linger keeps it, and a caller that cannot
+   * subscribe keeps it by setting it again.
+   */
+  set(args: A, value: V, linger: number): void;
+  /** The values a subscription with these arguments is shown: those whose data `match` lets it receive, asked with no context. */
+  seen(args: A): V[];
 }
 /** The event types of a process, served by each MCP server it creates. */
 export interface Events {
   /** Declares an event type. Emit its occurrences with the returned emitter. */
-  event<A, D>(name: string, definition: EventDefinition<A, D>): Emitter<D>;
+  event<A, D>(name: string, definition: EventDefinition<A, D>): Emitter<D, A>;
   /** Serves events/list, events/poll and events/stream on an McpServer or a Server, and declares the extension. */
   serve(server: McpServer | Server): void;
-  /** What a delivery mode works with. Not for applications. */
-  readonly [INTERNALS]: Internals;
 }
 
-/** An emitted event: kept, at a sequence, for a type without a check function; pushed only, for one with. */
-export interface Kept { sequence?: number; at?: number; target?: string | undefined; occurrence: EventOccurrence }
-/** What a subscription is owed after a cursor. */
-export interface Owed {
-  events: EventOccurrence[];
-  /** Events that could not be shaped for it, and were skipped. */
-  failures?: EventError[];
-  /** Where delivery starts. */
-  start: string | null;
-  cursor: string | null;
-  truncated: boolean;
-  hasMore: boolean;
+/** The identifier a server declares the Events extension under, in capabilities.extensions. */
+export const EVENTS_EXTENSION = "io.modelcontextprotocol/events";
+
+// The parts of an MCP server and of a request's context this module uses.
+interface Served {
+  registerCapabilities(capabilities: object): void;
+  setRequestHandler(method: string, schemas: object, handler: (request: any, ctx: Context) => unknown): void;
 }
-/** A subscription as a delivery mode holds it. */
-export interface Held {
+interface Context {
+  mcpReq: { id: string | number; signal: AbortSignal; notify(notification: { method: string; params: object }): Promise<void> };
+  http?: SubscriptionContext & object;
+}
+/** An emitted event, kept at its sequence for polls and reconnecting streams. */
+interface Kept { sequence: number; at: number; target: string | undefined; occurrence: EventOccurrence }
+/** A subscription held by a push stream or a poll lease. */
+interface Held {
   readonly id: string;
-  readonly name: string;
-  readonly delivery: DeliveryModeName;
   readonly arguments: unknown;
   readonly context: SubscriptionContext;
   /** Nothing is emitted to it alone: a poll lease shared by callers without an identity. */
@@ -196,58 +161,18 @@ export interface Held {
   /** Says the hold is over. */
   close(): void;
 }
+/** Who an emitted event is shaped for. */
+type Reader = Pick<Held, "id" | "arguments" | "context" | "untargetable">;
 /** The subscription a request asks for, checked. */
-export interface Requested { id: string; lease: string; arguments: unknown; context: SubscriptionContext; untargetable?: boolean }
-/** A declared event type, as the delivery modes see it. */
-export interface EventTypeState {
+interface Requested { id: string; lease: string; arguments: unknown; context: SubscriptionContext }
+interface Type<A = any, D = any> {
   readonly name: string;
-  readonly delivery: DeliveryModeName[];
-  readonly interval: number;
-  readonly check?: EventDefinition<unknown, unknown>["check"];
-  /** Whether the caller may hold the subscription, which a mode that holds subscriptions long asks again. */
-  authorize?(args: unknown, context: SubscriptionContext): boolean | Promise<boolean>;
-  /** Told each event as it is emitted: a push stream is one, and a delivery mode adds its own. */
-  readonly sinks: Set<(kept: Kept) => void>;
-  /** The subscriptions held by every mode, by id. */
-  readonly subscriptions: Map<string, { held: Set<Held>; ready: Promise<unknown> }>;
-}
-/** What a delivery mode works with. */
-export interface Internals {
-  readonly types: Map<string, EventTypeState>;
-  /** Checks a request, names its event type and the subscription's id. */
-  readonly subscription: (request: Record<string, unknown>, context: SubscriptionContext, delivery?: DeliveryModeName) => Promise<{ type: EventTypeState; subscription: Requested }>;
-  /** Begins holding a subscription. */
-  readonly open: (type: EventTypeState, subscription: { id: string; delivery: DeliveryModeName; arguments: unknown; context: SubscriptionContext }, end: (error: EventError) => void) => Promise<Held>;
-  /** What a subscription is owed after a cursor. */
-  readonly read: (type: EventTypeState, subscription: Pick<Held, "id" | "arguments" | "context" | "untargetable">, cursor: string | null | undefined, options?: { maxAgeMs?: number; maxEvents?: number }) => Owed | Promise<Owed>;
-  /** What a subscription is owed of the events emitted. */
-  readonly since: (type: EventTypeState, subscription: Pick<Held, "id" | "arguments" | "context" | "untargetable">, cursor: string | null | undefined, maxAgeMs?: number, limit?: number) => Owed;
-  /** An emitted event as one subscription receives it, or nothing when it is not for it. */
-  readonly shape: (type: EventTypeState, kept: Kept, subscription: Pick<Held, "id" | "arguments" | "context" | "untargetable">, failed?: (error: EventError) => void) => EventOccurrence | undefined;
-  /** A type's current cursor. */
-  readonly position: (type: EventTypeState, sequence?: number) => string;
-}
-
-/** The identifier a server declares the Events extension under, in capabilities.extensions. */
-export const EVENTS_EXTENSION = "io.modelcontextprotocol/events";
-/** Reaches what a delivery mode needs of the events it serves. Not for applications. */
-export const INTERNALS: unique symbol = Symbol.for("holon-sh.events.internals");
-
-// The parts of an MCP server and of a request's context this module uses.
-interface Served {
-  registerCapabilities(capabilities: object): void;
-  setRequestHandler(method: string, schemas: object, handler: (request: any, ctx: Context) => unknown): void;
-}
-interface Context {
-  mcpReq: { id: string | number; signal: AbortSignal; notify(notification: { method: string; params: object }): Promise<void> };
-  http?: SubscriptionContext & object;
-}
-interface Type<A = any, D = any> extends EventTypeState {
   readonly order: number;
   readonly description?: string | undefined;
   readonly inputSchema: StandardSchemaWithJSON<unknown, A>;
   readonly payloadSchema: StandardSchemaWithJSON;
   readonly _meta?: Record<string, unknown> | undefined;
+  readonly delivery: DeliveryModeName[];
   readonly match?: EventDefinition<A, D>["match"];
   readonly transform?: EventDefinition<A, D>["transform"];
   readonly authorize?: EventDefinition<A, D>["authorize"];
@@ -255,11 +180,17 @@ interface Type<A = any, D = any> extends EventTypeState {
   readonly onUnsubscribe?: EventDefinition<A, D>["onUnsubscribe"];
   sequence: number;
   dropped: number;
-  kept: Array<Kept & { sequence: number; at: number }>;
-  /** Subscriptions owed word of a gap, for events emitted to them alone that they could not be given. */
-  owed: Map<string, true>;
+  kept: Kept[];
+  /** Woken by each emitted event: one for each push stream. */
+  readonly sinks: Set<() => void>;
+  /** The subscriptions held by streams and poll leases, by id. */
+  readonly subscriptions: Map<string, { held: Set<Held>; ready: Promise<Subscription<A>> }>;
+  /** How many streams and poll leases are open, by the subscriber their arguments name. */
+  readonly holds: Map<string, number>;
+  /** Told when a subscriber's holds change: one for each presence. */
+  readonly present: Set<(subscriber: string) => void>;
 }
-interface Lease { type: Type; opening?: Promise<Held>; ended?: EventError; release?: () => void; timer?: ReturnType<typeof setTimeout> }
+interface Lease { type: Type; opening: Promise<Held>; ended?: EventError; release?: () => void; timer?: ReturnType<typeof setTimeout> }
 
 const INVALID_PARAMS = ProtocolErrorCode.InvalidParams;
 const INTERNAL_ERROR = ProtocolErrorCode.InternalError;
@@ -294,22 +225,30 @@ const caller = (context: SubscriptionContext): string | null => {
 };
 const hex = (bytes: Uint8Array) => [...bytes].map(byte => byte.toString(16).padStart(2, "0")).join("");
 // A subscription's id is the same for the same caller, event type and arguments, so it survives reconnects and poll
-// leases, as a webhook subscription's does. It is made with the global crypto, which needs no node:crypto at load.
+// leases. It is made with the global crypto, which needs no node:crypto at load.
 const identify = async (who: string | null, name: string, args: unknown) => {
   const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(JSON.stringify([who, name, canonical(args)])));
   return `sub_${hex(new Uint8Array(digest, 0, 16))}`;
 };
 // A caller without an identity gets an id of its own for each stream.
 const unique = () => `sub_${hex(crypto.getRandomValues(new Uint8Array(16)))}`;
+// The subscriber a subscription's arguments name, whoever the caller.
+const named = (args: unknown) => JSON.stringify(canonical(args));
+// Counts up or down under a key, and forgets a key that reaches none.
+const count = (counts: Map<string, number>, key: string, by: number) => {
+  const total = (counts.get(key) ?? 0) + by;
+  if (total) counts.set(key, total);
+  else counts.delete(key);
+};
 // A teardown that fails has nobody to tell, and must not take the process down.
 const settle = (run: () => unknown) => { Promise.resolve().then(run).catch(() => {}); };
 const integer = (value: unknown, minimum: number) => value === undefined || Number.isInteger(value) && (value as number) >= minimum;
 
-// What each type without a check function keeps of what it emits, for polls and reconnecting streams: the sketch's
-// emit buffer.
+const OFFERED: DeliveryModeName[] = ["poll", "push"];
+// What each type keeps of what it emits, for polls and reconnecting streams: the sketch's emit buffer.
 const KEPT_EVENTS = 10_000;
 const KEPT_AGE = 10 * 60_000;
-// How long a poll is told to wait before the next, and how often a stream asks a check function.
+// How long a poll is told to wait before the next.
 const INTERVAL = 1000;
 // How often a stream hears from the server when nothing happens, as the sketch recommends.
 const HEARTBEAT = 30_000;
@@ -332,13 +271,10 @@ const STREAM_BUDGET = 2 ** 20;
  * Event types a process emits and the MCP servers it creates serve, in the poll and push delivery modes of MCP Events,
  * the draft extension of the Triggers & Events Working Group. Each type keeps the last ten thousand events it emits,
  * for ten minutes, for polls and for streams that reconnect: those cursors last as long as the process, and after a
- * restart a client is told that events were skipped. A type with a check function uses its source's cursors instead,
- * which outlive the process. A type is asked again, and a poll told to come back, every second. A stream hears from
- * the server every thirty seconds.
+ * restart a client is told that events were skipped. A poll is told to come back every second, and a stream hears
+ * from the server every thirty seconds.
  */
-export function createEvents({ webhookTtl, webhook }: EventsOptions = {}): Events {
-  const modes = webhookTtl === undefined ? [] : [webhooks({ ...webhook, ttl: webhookTtl, heartbeat: HEARTBEAT })];
-  const offered = ["poll", "push", ...modes.map(mode => mode.name)];
+export function createEvents(): Events {
   // Cursors are positions in this process's memory. One from another process names nothing here. The name is made
   // without node:crypto, which is not there when a server is evaluated for its contract.
   const epoch = `${Date.now().toString(36)}${Math.random().toString(36).slice(2, 10)}`;
@@ -347,33 +283,23 @@ export function createEvents({ webhookTtl, webhook }: EventsOptions = {}): Event
   let subscribed = 0;
   const callers = new Map<string, number>();
 
-  const position = (type: EventTypeState, sequence: number = (type as Type).sequence) => `${epoch}.${sequence}`;
+  const position = (type: Type, sequence = type.sequence) => `${epoch}.${sequence}`;
 
-  // An event emitted to one subscription that it could not be given is owed to it as a gap, on its next poll or
-  // stream. The ids owed one are as many as the events a type keeps.
-  const owe = (type: Type, id: string) => {
-    type.owed.delete(id);
-    type.owed.set(id, true);
-    if (type.owed.size > KEPT_EVENTS) type.owed.delete(type.owed.keys().next().value!);
-  };
-
-  // What a subscription is owed after a cursor from the events emitted: the ones for it, in order, where delivery
-  // starts, and where it now stands. A null cursor starts from now, and so does one from another process. One past
-  // the events still kept starts from the oldest kept, and says that events were skipped.
-  const since: Internals["since"] = (state, subscription, cursor, maxAgeMs, limit = Infinity) => {
-    const type = state as Type;
-    const now = { events: [], start: position(type), cursor: position(type), hasMore: false };
-    if (cursor == null) return { ...now, truncated: false };
-    const [process, text] = cursor.split(".");
-    const sequence = Number(text);
-    if (process !== epoch || !Number.isInteger(sequence) || sequence > type.sequence) return { ...now, truncated: true };
-    const floor = maxAgeMs === undefined ? -Infinity : Date.now() - maxAgeMs;
-    const later = type.kept.filter(kept => kept.sequence > sequence);
+  // What a subscription is owed after a cursor, up to `until`: the events for it, in order, where delivery starts,
+  // and where it now stands. A null cursor starts where the subscription was opened, and so does one from another
+  // process, which says that events were skipped. One past the events still kept starts from the oldest kept, and
+  // says so too.
+  const since = (type: Type, subscription: Reader, cursor: string | null | undefined, { maxAgeMs, maxEvents: limit = Infinity, opened = type.sequence, until = type.sequence }: { maxAgeMs?: number; maxEvents?: number; opened?: number; until?: number } = {}) => {
+    const [process, text] = cursor?.split(".") ?? [];
+    const resumed = cursor != null && process === epoch && Number.isInteger(Number(text)) && Number(text) <= type.sequence;
+    const sequence = resumed ? Number(text) : opened;
+    const floor = maxAgeMs === undefined || !resumed ? -Infinity : Date.now() - maxAgeMs;
+    const later = type.kept.filter(kept => kept.sequence > sequence && kept.sequence <= until);
     const recent = later.filter(kept => kept.at >= floor);
-    const truncated = sequence < type.dropped || recent.length < later.length;
+    const truncated = cursor != null && !resumed || sequence < type.dropped || recent.length < later.length;
     const events: EventOccurrence[] = [];
     const failures: EventError[] = [];
-    let reached = recent.length ? recent[0]!.sequence - 1 : type.sequence;
+    let reached = recent.length ? recent[0]!.sequence - 1 : until;
     const start = position(type, reached);
     for (const kept of recent) {
       if (events.length === limit) return { events, failures, start, cursor: position(type, reached), truncated, hasMore: true };
@@ -381,82 +307,36 @@ export function createEvents({ webhookTtl, webhook }: EventsOptions = {}): Event
       const event = shape(type, kept, subscription, error => failures.push(error));
       if (event) events.push(event);
     }
-    return { events, failures, start, cursor: position(type), truncated, hasMore: false };
-  };
-
-  // What a subscription is owed after a cursor from the type's check function. The cursor is the author's own. Each
-  // event is placed at its own cursor when it has one, so a batch can be cut short; otherwise at the cursor before
-  // the batch, which is safe to resume from. After a gap, delivery starts from the position the check reached.
-  const checked = async (type: Type, { arguments: args, context }: Pick<Held, "arguments" | "context">, cursor: string | null | undefined, maxAgeMs?: number, limit = Infinity): Promise<Owed> => {
-    const result = await type.check!(cursor ?? null, args, context);
-    const next = result?.cursor ?? null;
-    // A null cursor asks for the current position and nothing before it, except of a source that has no positions:
-    // each check of that is asked with null, and answers with what is new.
-    if (cursor == null && next !== null) return { events: [], start: next, cursor: next, truncated: false, hasMore: false };
-    const items = result?.events ?? [];
-    const floor = maxAgeMs === undefined || cursor == null ? -Infinity : Date.now() - maxAgeMs;
-    let truncated = next !== null && Boolean(result.truncated);
-    const events: EventOccurrence[] = [];
-    const failures: EventError[] = [];
-    let reached = cursor ?? null;
-    let cuttable = false;
-    const answer = (end: string | null, hasMore: boolean): Owed => ({ events, failures, start: truncated || !events.length ? end : cursor ?? null, cursor: end, truncated, hasMore });
-    for (const [index, item] of items.entries()) {
-      if (events.length === limit && cuttable) return answer(reached, true);
-      const after = index === items.length - 1 ? next : item.cursor ?? reached;
-      const { eventId = crypto.randomUUID(), timestamp = new Date().toISOString(), data, _meta } = item;
-      if (Date.parse(timestamp) < floor) truncated = next !== null;
-      else if (serialisable(type, eventId, { data, _meta }, error => failures.push(error))) events.push({ eventId, name: type.name, timestamp, data, ...(_meta && { _meta }), cursor: after });
-      reached = after;
-      cuttable = item.cursor != null;
-    }
-    return answer(next, Boolean(result.hasMore));
+    return { events, failures, start, cursor: position(type, until), truncated, hasMore: false };
   };
 
-  // What a subscription is owed after a cursor, whichever way its type learns of events.
-  const read: Internals["read"] = (type, subscription, cursor, { maxAgeMs, maxEvents } = {}) =>
-    type.check ? checked(type as Type, subscription, cursor, maxAgeMs, maxEvents) : since(type, subscription, cursor, maxAgeMs, maxEvents);
-
   // The occurrence a subscription receives, or nothing when it is not for it. An event emitted to one subscription
   // is for that one alone, and its arguments are not asked.
   // An event that cannot be shaped for a subscription, because `match` or `transform` throws or what `transform`
   // returns cannot be sent as JSON, is skipped for that subscription alone, so its cursor moves past it. It is
   // logged, and `failed` hears of it so a stream can say so once.
-  const shape: Internals["shape"] = (state, { sequence, target, occurrence }, { id, untargetable, arguments: args, context }, failed) => {
-    const type = state as Type;
+  const shape = (type: Type, { sequence, target, occurrence }: Kept, { id, untargetable, arguments: args, context }: Reader, failed: (error: EventError) => void): EventOccurrence | undefined => {
     let data: unknown;
     try {
       if (target !== undefined ? untargetable || target !== id : type.match && !type.match(occurrence.data, args, context)) return undefined;
       data = type.transform ? type.transform(occurrence.data, args, context) : occurrence.data;
       if (type.transform) JSON.stringify(data);
-    } catch (error) {
-      skipped(type, occurrence.eventId, error, failed);
+    } catch (error: any) {
+      const { eventId } = occurrence;
+      console.error(`holon-sh/ext/events: event ${eventId} of ${type.name} was skipped for a subscription:`, error);
+      failed({ code: INTERNAL_ERROR, message: `Event ${eventId} could not be delivered and was skipped`, data: { eventId, reason: String(error?.message ?? error) } });
       return undefined;
     }
-    return { ...occurrence, data, ...(sequence !== undefined && { cursor: position(type, sequence) }) };
-  };
-  const skipped = (type: Type, eventId: string, error: any, failed?: (error: EventError) => void) => {
-    console.error(`holon-sh/ext/events: event ${eventId} of ${type.name} was skipped for a subscription:`, error);
-    failed?.({ code: INTERNAL_ERROR, message: `Event ${eventId} could not be delivered and was skipped`, data: { eventId, reason: String(error?.message ?? error) } });
-  };
-  // What a check function found is skipped in the same way when it cannot be sent as JSON.
-  const serialisable = (type: Type, eventId: string, value: unknown, failed: (error: EventError) => void) => {
-    try {
-      JSON.stringify(value);
-      return true;
-    } catch (error) {
-      skipped(type, eventId, error, failed);
-      return false;
-    }
+    return { ...occurrence, data, cursor: position(type, sequence) };
   };
 
   // The event type and arguments a request names, checked as the sketch's errors require, in its order: the type,
   // the delivery mode, the request's own fields, the arguments, and then whether the caller may subscribe. A caller
   // refused loses what it holds of that subscription at once.
-  const subscription: Internals["subscription"] = async ({ name, arguments: args = {}, cursor, maxAgeMs, maxEvents }, context, delivery) => {
+  const subscription = async ({ name, arguments: args = {}, cursor, maxAgeMs, maxEvents }: Record<string, unknown>, context: SubscriptionContext, delivery: DeliveryModeName): Promise<{ type: Type; subscription: Requested }> => {
     const type = types.get(name as string);
     if (!type) throw refusal(removed);
-    if (delivery && !type.delivery.includes(delivery)) throw refusal({ code: UNSUPPORTED, message: "Unsupported", data: { feature: "deliveryMode", value: delivery } });
+    if (!type.delivery.includes(delivery)) throw refusal({ code: UNSUPPORTED, message: "Unsupported", data: { feature: "deliveryMode", value: delivery } });
     if (cursor != null && typeof cursor !== "string") throw new ProtocolError(INVALID_PARAMS, "cursor must be a string or null");
     if (!integer(maxAgeMs, 0)) throw new ProtocolError(INVALID_PARAMS, "maxAgeMs must be a non-negative integer");
     if (!integer(maxEvents, 1)) throw new ProtocolError(INVALID_PARAMS, "maxEvents must be a positive integer");
@@ -474,23 +354,29 @@ export function createEvents({ webhookTtl, webhook }: EventsOptions = {}): Event
     return { type, subscription: { id: who === null ? unique() : lease, lease, arguments: checked.value, context } };
   };
 
-  const endSubscription = (type: EventTypeState, id: string, error: EventError) => {
+  const endSubscription = (type: Type, id: string, error: EventError) => {
     for (const held of [...type.subscriptions.get(id)?.held ?? []]) held.end(error);
   };
 
-  // Begins holding a subscription, by a stream, a poll lease or another delivery mode: counted against the limits
-  // first, so a refused one provisions nothing. The type's onSubscribe is called when the first hold of an id
-  // begins, and its onUnsubscribe when the last ends, so two streams of one subscription set it up once. `end` is how
-  // the delivery mode is told the app terminated it; `close` is how the mode says its hold is over.
-  const open: Internals["open"] = async (state, { id, delivery, arguments: args, context }, end) => {
-    const type = state as Type;
+  // Begins holding a subscription, by a stream or a poll lease: counted against the limits first, so a refused one
+  // provisions nothing. The type's onSubscribe is called when the first hold of an id begins, and its onUnsubscribe
+  // when the last ends, so two streams of one subscription set it up once. `end` is how the holder is told the app
+  // terminated it; `close` is how the holder says its hold is over.
+  const open = async (type: Type, { id, delivery, arguments: args, context }: { id: string; delivery: DeliveryModeName; arguments: unknown; context: SubscriptionContext }, end: (error: EventError) => void): Promise<Held> => {
     if (types.get(type.name) !== type) throw refusal(removed);
     // Callers without an identity cannot be told apart, so they count together as one.
     const who = caller(context) ?? "anonymous";
     if (subscribed >= MAX_SUBSCRIPTIONS) throw refusal({ code: RESOURCE_EXHAUSTED, message: "ResourceExhausted", data: { limit: "subscriptions", max: MAX_SUBSCRIPTIONS } });
     if ((callers.get(who) ?? 0) >= MAX_SUBSCRIPTIONS_PER_CALLER) throw refusal({ code: RESOURCE_EXHAUSTED, message: "ResourceExhausted", data: { limit: "subscriptionsPerCaller", max: MAX_SUBSCRIPTIONS_PER_CALLER } });
     subscribed++;
-    callers.set(who, (callers.get(who) ?? 0) + 1);
+    count(callers, who, 1);
+    // A presence keeps a subscriber's value while any of its streams or leases is open.
+    const subscriber = named(args);
+    const hold = (by: number) => {
+      count(type.holds, subscriber, by);
+      for (const keep of type.present) keep(subscriber);
+    };
+    hold(1);
     let entry = type.subscriptions.get(id);
     if (!entry) {
       const subscription = { subscriptionId: id, name: type.name, delivery, arguments: args, context };
@@ -501,18 +387,17 @@ export function createEvents({ webhookTtl, webhook }: EventsOptions = {}): Event
     }
     const current = entry;
     let closed = false;
-    const held: Held = { id, name: type.name, delivery, arguments: args, context, end, close() {
+    const held: Held = { id, arguments: args, context, end, close() {
       if (closed) return;
       closed = true;
       subscribed--;
-      const count = callers.get(who) ?? 1;
-      if (count === 1) callers.delete(who);
-      else callers.set(who, count - 1);
+      count(callers, who, -1);
+      hold(-1);
       current.held.delete(held);
       if (current.held.size) return;
       if (type.subscriptions.get(id) === current) type.subscriptions.delete(id);
       // Only a subscription that was set up is told it ended.
-      current.ready.then(subscription => { if (type.onUnsubscribe) settle(() => type.onUnsubscribe!(subscription as Subscription<unknown>)); }, () => {});
+      current.ready.then(subscription => { if (type.onUnsubscribe) settle(() => type.onUnsubscribe!(subscription)); }, () => {});
     } };
     current.held.add(held);
     try {
@@ -545,13 +430,12 @@ export function createEvents({ webhookTtl, webhook }: EventsOptions = {}): Event
       lent = undefined;
     }
     if (!lent) {
-      const fresh: Lease = { type };
-      lent = fresh;
-      leases.set(key, fresh);
-      fresh.opening = open(type, { ...subscribed, id: key, delivery: "poll" }, error => {
+      const fresh: Lease = { type, opening: open(type, { ...subscribed, id: key, delivery: "poll" }, error => {
         fresh.ended = error;
         fresh.release?.();
-      });
+      }) };
+      lent = fresh;
+      leases.set(key, fresh);
       fresh.opening.then(held => {
         if (shared) held.untargetable = true;
         fresh.release = () => held.close();
@@ -559,7 +443,7 @@ export function createEvents({ webhookTtl, webhook }: EventsOptions = {}): Event
       }, () => { if (leases.get(key) === fresh) leases.delete(key); });
     }
     const current = lent;
-    const held = await current.opening!;
+    const held = await current.opening;
     // Ended while it was being set up.
     if (current.ended) {
       leases.delete(key);
@@ -574,50 +458,32 @@ export function createEvents({ webhookTtl, webhook }: EventsOptions = {}): Event
     return held;
   };
 
-  // What a delivery mode works with: `subscription` checks a request, names its event type and the subscription's
-  // id, `open` begins holding a subscription, `read` gives a subscription what it is owed after a cursor (`since` and
-  // `shape` for emitted events alone), `position` is a type's cursor, a type's `sinks` hear what is emitted, and its
-  // `subscriptions` are the ones held by every mode, by id.
-  const internals: Internals = { types, subscription, open, read, since, shape, position };
-
   return {
-    [INTERNALS]: internals,
     /**
      * Declares an event type and returns the function that emits it. `match` decides which subscriptions receive an
-     * event from their arguments, and `transform` shapes its data for each. `check` returns what happened after a
-     * cursor, for event types whose source keeps its own history.
+     * event from their arguments, and `transform` shapes its data for each.
      */
-    event<A, D>(name: string, { description, inputSchema, payloadSchema, _meta, match, transform, check, delivery = offered.filter(mode => !check || mode !== "webhook"), authorize, onSubscribe, onUnsubscribe }: EventDefinition<A, D>): Emitter<D> {
+    event<A, D>(name: string, { description, inputSchema, payloadSchema, _meta, match, transform, delivery = OFFERED, authorize, onSubscribe, onUnsubscribe }: EventDefinition<A, D>): Emitter<D, A> {
       if (types.has(name)) throw new Error(`Event ${name} is already declared.`);
-      const unknown = delivery.filter(mode => !offered.includes(mode));
-      if (unknown.length || !delivery.length) throw new Error(`Event ${name} is delivered by ${delivery.join(", ") || "nothing"}, but only ${offered.join(", ")} are served.`);
-      // Webhook delivery sends what is emitted, and does not ask a check function.
-      if (check && delivery.includes("webhook")) throw new Error(`Event ${name} has a check function, which webhook delivery does not read.`);
+      const unknown = delivery.filter(mode => !OFFERED.includes(mode));
+      if (unknown.length || !delivery.length) throw new Error(`Event ${name} is delivered by ${delivery.join(", ") || "nothing"}, but only ${OFFERED.join(", ")} are served.`);
       const type: Type<A, D> = {
-        name, order: ++declared, description, inputSchema, payloadSchema, _meta, match, transform, check: check as Type["check"], interval: INTERVAL, delivery, authorize, onSubscribe, onUnsubscribe,
-        sequence: 0, dropped: 0, kept: [], sinks: new Set(), subscriptions: new Map(), owed: new Map(),
+        name, order: ++declared, description, inputSchema, payloadSchema, _meta, delivery, match, transform, authorize, onSubscribe, onUnsubscribe,
+        sequence: 0, dropped: 0, kept: [], sinks: new Set(), subscriptions: new Map(), holds: new Map(), present: new Set(),
       };
       types.set(name, type);
-      return {
+      const emitter: Emitter<D, A> = {
         emit(data, { eventId = crypto.randomUUID(), timestamp = new Date().toISOString(), subscriptionId: target } = {}) {
           const occurrence = { eventId, name, timestamp, data };
           // Data that cannot be sent as JSON is refused here, before anything is kept or sent.
           JSON.stringify(occurrence);
-          // A type with a check function is asked for what polls are owed, so what it emits is pushed and not kept.
-          if (type.check) {
-            // An event for one subscription that has no stream to take it is lost.
-            if (target !== undefined && ![...type.subscriptions.get(target)?.held ?? []].some(held => held.delivery !== "poll")) owe(type, target);
-            for (const sink of type.sinks) sink({ target, occurrence });
-            return;
-          }
           // An event for one subscription is kept like any other, so the subscription has it when it comes back.
           const kept = { sequence: ++type.sequence, at: Date.now(), target, occurrence };
           type.kept.push(kept);
           while (type.kept.length > KEPT_EVENTS || type.kept[0]!.at < kept.at - KEPT_AGE) type.dropped = type.kept.shift()!.sequence;
-          for (const sink of type.sinks) sink(kept);
+          for (const sink of type.sinks) sink();
         },
         cursor() {
-          if (type.check) throw new Error(`Event ${name} has a check function, whose cursor is its source's own.`);
           return position(type);
         },
         terminate(id, error = forbidden) {
@@ -629,14 +495,43 @@ export function createEvents({ webhookTtl, webhook }: EventsOptions = {}): Event
           types.delete(name);
           for (const each of [...type.subscriptions.keys()]) endSubscription(type, each, removed);
         },
+        presence<V>(told: (args: A, value: V | undefined) => D): Presence<A, V> {
+          const values = new Map<string, { args: A; value: V; linger: number; leaving?: ReturnType<typeof setTimeout> }>();
+          // A value has no timer while its subscriber holds a subscription, and leaves its linger after it stops.
+          const keep = (subscriber: string) => {
+            const shown = values.get(subscriber);
+            if (!shown) return;
+            clearTimeout(shown.leaving);
+            if (type.holds.has(subscriber)) return;
+            shown.leaving = setTimeout(() => {
+              values.delete(subscriber);
+              emitter.emit(told(shown.args, undefined));
+            }, shown.linger);
+            shown.leaving.unref?.();
+          };
+          type.present.add(keep);
+          return {
+            set(args, value, linger) {
+              const subscriber = named(args);
+              values.set(subscriber, { args, value, linger, leaving: values.get(subscriber)?.leaving });
+              keep(subscriber);
+              emitter.emit(told(args, value));
+            },
+            seen(args) {
+              return [...values.values()]
+                .filter(shown => !type.match || type.match(told(shown.args, shown.value), args, undefined))
+                .map(({ value }) => value);
+            },
+          };
+        },
       };
+      return emitter;
     },
 
     /** Serves the declared event types on an MCP server: events/list, events/poll and events/stream. */
     serve(mcp) {
-      const underlying: Server = "server" in mcp ? mcp.server : mcp;
       // The custom methods are registered through the parts of the server this module uses.
-      const server = underlying as unknown as Served;
+      const server = ("server" in mcp ? mcp.server : mcp) as unknown as Served;
       // The sketch declares capabilities.events. The MCP SDK's client drops top-level capabilities it does not know,
       // so the extension is declared under capabilities.extensions too, where SDK clients read it.
       // Clients are never told the event types changed: over Holon's stateless HTTP, the notification reaches none.
@@ -664,33 +559,43 @@ export function createEvents({ webhookTtl, webhook }: EventsOptions = {}): Event
           ...(start + PAGE_SIZE < all.length && { nextCursor: String(page.at(-1)!.order) }),
         };
       });
-      for (const mode of modes) mode.serve(underlying, internals);
 
       server.setRequestHandler("events/poll", { params }, async (request, ctx) => {
         const { type, subscription: subscribed } = await subscription(request, ctx.http, "poll");
-        const held = await lease(type as Type, subscribed);
+        // Taken before the lease, which waits for onSubscribe. The sketch's poll from null returns no events and a
+        // fresh cursor: this one is where the subscription opened, so the next poll has what onSubscribe emitted.
+        const opened = type.sequence;
+        const held = await lease(type, subscribed);
         // Each poll is answered for its own caller, with the lease's id.
-        const { events, start, failures, truncated, ...rest } = await read(type, { ...subscribed, id: held.id, untargetable: held.untargetable }, request.cursor, request);
-        const lost = !held.untargetable && (type as Type).owed.delete(held.id);
+        const { events, start, failures, ...rest } = since(type, { ...subscribed, id: held.id, untargetable: held.untargetable }, request.cursor, { maxAgeMs: request.maxAgeMs, maxEvents: request.maxEvents, opened, ...(request.cursor == null && { until: opened }) });
         // A poll carries its cursor once, for the whole response.
-        return { events: events.map(({ cursor, ...event }) => event), ...rest, truncated: truncated || lost, nextPollMs: type.interval };
+        return { events: events.map(({ cursor, ...event }) => event), ...rest, nextPollMs: INTERVAL };
       });
 
       server.setRequestHandler("events/stream", { params }, async (request, ctx) => {
-        const { type: state, subscription: subscribed } = await subscription(request, ctx.http, "push");
-        const type = state as Type;
+        const { type, subscription: subscribed } = await subscription(request, ctx.http, "push");
         const { signal } = ctx.mcpReq;
         const meta = { [SUBSCRIPTION_ID_META_KEY]: ctx.mcpReq.id };
         let done = false;
         let ending: EventError | undefined;
+        // Set when the app terminates the stream: the last event emitted before, which the stream still sends.
+        let until: number | undefined;
         let wake = () => {};
         const finish = () => {
           done = true;
           wake();
         };
+        // What is emitted from here on is the stream's, so it has what onSubscribe emits to it.
+        const opened = type.sequence;
         const held = await open(type, { ...subscribed, delivery: "push" }, error => {
+          // Lost access ends delivery at once, even while what came before is still being sent. Otherwise only the
+          // first end counts, and the stream first sends what was emitted before it.
+          const lost = error.code === FORBIDDEN;
+          if (ending && !lost) return;
           ending = error;
-          finish();
+          if (lost) return finish();
+          until = type.sequence;
+          wake();
         });
         // A client that left while the subscription was being set up is not waited for.
         if (signal.aborted) {
@@ -715,19 +620,15 @@ export function createEvents({ webhookTtl, webhook }: EventsOptions = {}): Event
           }
           if ((sent += JSON.stringify(params).length) > STREAM_BUDGET) finish();
         };
-        // The stream follows its cursor: emitted events wake it, and a type with a check function is asked again
-        // every interval. What it is owed waits in the buffer or the source, not here, so a slow client is not owed
-        // more memory than one batch; when what it is owed is no longer kept, it is told of the gap.
+        // The stream follows its cursor, and emitted events wake it. What it is owed waits in the buffer, not here, so
+        // a slow client is not owed more memory than one batch; when what it is owed is no longer kept, it is told of
+        // the gap.
         let cursor: string | null = request.cursor ?? null;
         let behind = true;
-        // What a type with a check function emitted and the stream has yet to send. The check function finds it
-        // too, so when too much waits the oldest is let go.
-        const pushed: Kept[] = [];
-        const sink = (kept: Kept) => {
-          if (type.check) {
-            pushed.push(kept);
-            if (pushed.length > KEPT_EVENTS) pushed.shift();
-          } else behind = true;
+        const sink = () => {
+          // Nothing emitted after the app terminated the stream is for it.
+          if (until !== undefined) return;
+          behind = true;
           wake();
         };
         type.sinks.add(sink);
@@ -748,58 +649,29 @@ export function createEvents({ webhookTtl, webhook }: EventsOptions = {}): Event
         }, HEARTBEAT);
         let first = true;
         try {
-          let due = 0;
           while (!done) {
-            if (type.check ? Date.now() >= due : behind) {
+            if (behind) {
               behind = false;
-              let result: Owed | undefined;
-              try {
-                result = await read(type, held, cursor, { ...(first && request.maxAgeMs !== undefined && { maxAgeMs: request.maxAgeMs }) });
-              } catch (error) {
-                // Without a first answer there is no stream to tell, and the request fails.
-                if (first) throw error;
-                await notify("error", { error: described(error) });
-              }
-              due = Date.now() + type.interval;
-              if (result) {
-                // A check function's gap is told after the events that follow it, at the position after them, since
-                // the position before them is not known and the client's cursor must not go back. The stream is
-                // confirmed before anything else is said on it.
-                const after = type.check && result.truncated && !first;
-                const truncated = result.truncated || first && type.owed.delete(held.id);
-                if (first || truncated && !after) await notify("active", { cursor: type.check && result.truncated ? cursor : result.start, truncated });
-                if (first) beat = heartbeats();
-                first = false;
-                for (const error of result.failures ?? []) await notify("error", { error });
-                for (const event of result.events) {
-                  if (done) break;
-                  await notify("event", event);
-                  cursor = event.cursor ?? null;
-                }
+              const result = since(type, held, cursor, { ...(first && request.maxAgeMs !== undefined && { maxAgeMs: request.maxAgeMs }), opened, until });
+              // The stream is confirmed before anything else is said on it.
+              if (first || result.truncated) await notify("active", { cursor: result.start, truncated: result.truncated });
+              if (first) beat = heartbeats();
+              first = false;
+              for (const error of result.failures) await notify("error", { error });
+              for (const event of result.events) {
                 if (done) break;
-                cursor = result.cursor;
-                if (after) await notify("active", { cursor, truncated: true });
-                if (result.hasMore) {
-                  due = 0;
-                  behind = true;
-                }
+                await notify("event", event);
+                cursor = event.cursor ?? null;
               }
+              if (done) break;
+              cursor = result.cursor;
             }
-            // What a type with a check function emits is sent at once, at the cursor the stream has reached.
-            while (pushed.length && !done) {
-              let failure: EventError | undefined;
-              const event = shape(type, pushed.shift()!, held, error => { failure = error; });
-              if (failure) await notify("error", { error: failure });
-              if (event) await notify("event", { ...event, cursor });
-            }
-            if (done) break;
-            let timer: ReturnType<typeof setTimeout> | undefined;
+            // Terminated by the app, the stream ends once it has sent what was emitted before.
+            if (done || until !== undefined && !behind) break;
             await new Promise<void>(resolve => {
               wake = resolve;
-              if (done || pushed.length || (!type.check && behind)) resolve();
-              else if (type.check) timer = setTimeout(resolve, Math.max(0, due - Date.now()));
+              if (done || behind) resolve();
             });
-            clearTimeout(timer);
             wake = () => {};
           }
           if (ending) {
@@ -809,8 +681,6 @@ export function createEvents({ webhookTtl, webhook }: EventsOptions = {}): Event
         } finally {
           clearInterval(beat);
           type.sinks.delete(sink);
-          // What was emitted to this subscription alone and not sent is owed to it as a gap when it comes back.
-          if (held.id === subscribed.lease && pushed.some(kept => kept.target === held.id)) owe(type, held.id);
           held.close();
         }
         // The final frame, sent when the server ends the stream; when the client did, nobody is listening.