experimental-a2 0.20.0 → 0.22.0

package/dist/{server-DYAATFuT.d.ts → server-qgez0Xny.d.ts}

@@ -1,7 +1,7 @@
-import { c as ContractEvent, d as PresenceDefs, f as PresenceMap, g as WithPresence, m as PresenceSnapshot, o as AppendInput, p as PresencePatch, r as RegisteredReducer, s as Contract, t as Reducer, u as EventDefs } from "./reducer-CqA59Q6U.js";
-import { t as A2Store } from "./store-CyLUy86v.js";
-import { t as SessionCleared } from "./session-clear-C-QwTXV1.js";
-import { i as A2Telemetry } from "./telemetry-Cyfqo6Qt.js";
+import { c as ContractEvent, d as PresenceDefs, f as PresenceMap, g as WithPresence, m as PresenceSnapshot, o as AppendInput, p as PresencePatch, r as RegisteredReducer, s as Contract, t as Reducer, u as EventDefs } from "./reducer-CYPHsSmd.js";
+import { t as A2Store } from "./store-D0MhBvg6.js";
+import { t as SessionCleared } from "./session-clear-D1PFe7xl.js";
+import { i as A2Telemetry } from "./telemetry-CWwsh-Gx.js";
 //#region src/session-socket.d.ts
 /**
  * The structural socket `sessionsSocket` speaks against — satisfied
@@ -69,7 +69,7 @@ type ScheduledEvent = {
   type: string;
   payload: unknown;
 };
-/** A durable wake-up for pending handler work. */
+/** A durable wake-up for pending consumer work. */
 type SchedulerDrainTask = {
   version: 1;
   kind: "drain";
@@ -89,7 +89,7 @@ type SchedulerAppendTask = {
   /** Earliest useful delivery as epoch milliseconds. */
   dueAt: number;
   events: readonly ScheduledEvent[];
-  /** The scheduling handler's event; delivery skips once it is cleared. */
+  /** The scheduling consumer's event; delivery skips once it is cleared. */
   originIndex?: number;
 };
 /** A durable conditional clear. */
@@ -112,31 +112,35 @@ type SchedulerTask = SchedulerDrainTask | SchedulerAppendTask | SchedulerClearTa
 type PublicState<R> = undefined extends R ? never : R extends {
   initialState: infer S;
 } ? S : never;
-/** What every handler receives. */
-type HandlerContext<D extends EventDefs, K extends keyof D & string = keyof D & string, P extends PresenceDefs = Record<never, never>, S = never> = {
+/** What every consumer's `run` receives. */
+type ConsumerContext<D extends EventDefs, K extends keyof D & string = keyof D & string, P extends PresenceDefs = Record<never, never>, S = never> = {
   /** The triggering event. */
   event: ContractEvent<D, K>;
   /** Durable, 1-based dispatch ordinal for this event. */
   attempt: number;
-  /** This session, with handler-scoped idempotent append. */
-  session: Session<D, HandlerAppend<D>, P, S>;
+  /** This session, with consumer-scoped idempotent append. */
+  session: Session<D, ConsumerAppend<D>, P, S>;
   /** Fires on `abortOn` events (cancellation slice); dormant otherwise. */
   signal: AbortSignal;
 };
-type Handler<D extends EventDefs, K extends keyof D & string = keyof D & string, P extends PresenceDefs = Record<never, never>, S = never> = (ctx: HandlerContext<D, K, P, S>) => Promise<void | AppendInput<D> | readonly AppendInput<D>[]>;
 type LaneContext<D extends EventDefs, K extends keyof D & string = keyof D & string> = {
   sessionId: string;
   event: Pick<ContractEvent<D, K>, "type" | "payload"> & {
     id?: string;
   };
 };
-type Lane<D extends EventDefs, K extends keyof D & string = keyof D & string> = string | ((context: LaneContext<D, K>) => string);
+/**
+ * A consumer's lane: a string runs every event it takes in log order on one
+ * cursor; a function returns each event's lane, or null to run it
+ * concurrently.
+ */
+type ConsumerLane<D extends EventDefs, K extends keyof D & string = keyof D & string> = string | ((context: LaneContext<D, K>) => string | null);
 type SessionDispatch<D extends EventDefs> = (...events: AppendInput<D>[]) => Promise<ContractEvent<D>[]>;
 type SessionAppend<D extends EventDefs> = SessionDispatch<D> & {
   /** Commit, then hand pending work directly to configured scheduler. */
   dispatch: SessionDispatch<D>;
 };
-type HandlerAppend<D extends EventDefs> = (name: string, ...events: AppendInput<D>[]) => Promise<ContractEvent<D>[]>;
+type ConsumerAppend<D extends EventDefs> = (name: string, ...events: AppendInput<D>[]) => Promise<ContractEvent<D>[]>;
 type ScheduleDelay = `${number}${"ms" | "s" | "m" | "h" | "d"}`;
 type ScheduleTiming = {
   delay: ScheduleDelay;
@@ -168,25 +172,41 @@ type SessionClearResult = {
   index: number;
 };
 type SessionRedriveOptions = {
-  /** `retry` runs the handler again with a fresh failure budget; `skip` settles the event without running it. */
+  /** `retry` runs the consumer again with a fresh failure budget; `skip` settles the event without running it. */
   action: "retry" | "skip";
 };
 type SessionRedriveResult = {
   /** Whether the event was dead-lettered and is now resolved. */
   redriven: boolean;
 };
+type SessionConsumeOptions = {
+  /**
+   * Run until the consumer has handled every event it takes through this
+   * index. Default: the session's head when the call starts. An index past
+   * the head counts as the head.
+   */
+  through?: number;
+  /** Stops waiting: the call throws the signal's reason. */
+  signal?: AbortSignal;
+};
+type SessionConsumeResult = {
+  /** The consumer has handled every event it takes through this index. */
+  index: number;
+};
 /** A dead-lettered event, with what an operator needs to resolve it. */
 type DeadLetter<D extends EventDefs> = ContractEvent<D> & {
+  /** The consumer this event is dead for; it may be done for others. */
+  consumer: string;
   lane: string | null;
   /** Durable dispatch claims, including claims abandoned by hard kills. */
   attemptCount: number;
   /**
    * Failed attempts since the event was appended or last retried: caught
-   * handler failures, and attempts that ended before they finished.
+   * consumer failures, and attempts that ended before they finished.
    */
   failureCount: number;
   /**
-   * The last error a handler threw, stringified; null when every failed
+   * The last error the consumer threw, stringified; null when every failed
    * attempt ended before it finished.
    */
   lastError: string | null;
@@ -200,7 +220,10 @@ type SessionDeadLetters<D extends EventDefs> = {
    * Atomically resolve one dead-lettered event, then wake the session like
    * an append. Any other event is left alone and reports `redriven: false`.
    */
-  redrive(index: number, options: SessionRedriveOptions): Promise<SessionRedriveResult>;
+  redrive(target: {
+    consumer: string;
+    index: number;
+  }, options: SessionRedriveOptions): Promise<SessionRedriveResult>;
 };
 /**
  * The presence members of a session — intersected in via
@@ -248,6 +271,14 @@ type Session<D extends EventDefs, Append = SessionAppend<D>, P extends PresenceD
     gte?: number;
     lte?: number;
   }): Promise<ContractEvent<D>[]>;
+  /**
+   * Run a consumer with a string lane on this session, here, until it has
+   * handled every event it takes through `through`. The server's own
+   * consumer shares its cursor with background work, so this waits for
+   * whichever invocation holds it. A consumer the server doesn't run is
+   * pulled only by `consume`, and keeps its place between calls.
+   */
+  consume(consumer: Consumer<D>, options?: SessionConsumeOptions): Promise<SessionConsumeResult>;
   state: {
     <T>(reducer: Reducer<D, T, Record<never, never>>, options?: StateOptions): Promise<{
       state: T;
@@ -271,7 +302,7 @@ type Session<D extends EventDefs, Append = SessionAppend<D>, P extends PresenceD
   }): AsyncIterable<ContractEvent<D> | SessionCleared>;
 };
 /**
- * The public server shape scheduler handlers accept. It stays structural so
+ * The public server shape scheduler consumers accept. It stays structural so
  * servers of any contract mix in one route; A2's private server internals add
  * delayed-append delivery without exposing an untyped append method here.
  */
@@ -327,29 +358,66 @@ declare function deliverSchedulerAppend(server: DrainableServer, task: Scheduler
  */
 declare function deliverSchedulerClear(server: DrainableServer, task: SchedulerClearTask): Promise<void>;
 /**
- * Which events fire `ctx.signal` while a handler runs — the preemption
+ * Which events fire `ctx.signal` while a consumer runs — the preemption
  * channel for user cancellation. The array form matches by type; the
  * object form takes per-type predicates for targeted cancellation
- * (`(event, trigger) => event.payload.of === trigger.id`). Handlers
- * without `abortOn` pay nothing. An aborted handler should catch and
+ * (`(event, trigger) => event.payload.of === trigger.id`). Consumers
+ * without `abortOn` pay nothing. An aborted consumer should catch and
  * return normally; throwing means "retry me".
  */
 type AbortSpec<D extends EventDefs, K extends keyof D & string> = Array<keyof D & string> | { [T in keyof D & string]?: true | ((event: ContractEvent<D, T>, trigger: ContractEvent<D, K>, context: {
   attempt: number;
 }) => boolean); };
-type HandlerEntry<D extends EventDefs, K extends keyof D & string = keyof D & string, P extends PresenceDefs = Record<never, never>, S = never> = Handler<D, K, P, S> | {
+/** What a consumer's `run` returns: nothing, one event, or a batch. */
+type ConsumerResult<D extends EventDefs> = Promise<void | AppendInput<D> | readonly AppendInput<D>[]>;
+/** How `createServer` runs a consumer. Built by `consumer().run()`. */
+type ConsumerSpec<D extends EventDefs> = {
+  readonly types: readonly (keyof D & string)[] | null;
+  readonly lane: ConsumerLane<D> | null;
+  readonly backfill: boolean;
+  readonly abortOn: AbortSpec<D, keyof D & string> | null;
+  readonly run: (ctx: ConsumerContext<D>) => ConsumerResult<D>;
+};
+/** A named reader of a session's log with its own durable cursors. */
+type Consumer<D extends EventDefs> = {
+  readonly name: string;
+  readonly contract: {
+    readonly name: string;
+  };
+  readonly spec: ConsumerSpec<D>;
+};
+type ConsumerOptions<D extends EventDefs, P extends PresenceDefs, R extends RegisteredReducer<D, P> | undefined, K extends keyof D & string> = {
+  /** The contract whose events it reads. */
+  contract: Contract<D, P, R>;
+  /** Its identity, unique per server. A new name is a new consumer. */
+  name: string;
+  /** The event types it runs on; default every type. */
+  types?: readonly K[];
+  /** Omitted: concurrent. A string: one ordered lane. A function: per event. */
+  lane?: ConsumerLane<D, K>;
+  /** A new consumer starts at the beginning of the log. Needs a string lane. */
+  backfill?: boolean;
   abortOn?: AbortSpec<D, K>;
-  /** Session-scoped FIFO key, resolved and persisted when the event lands. */
-  lane?: Lane<D, K>;
-  handler: Handler<D, K, P, S>;
-};
-type HandlerFunction = (ctx: never) => Promise<unknown>;
-declare function handler<H extends HandlerFunction | {
-  handler: HandlerFunction;
-}>(entry: H): H extends HandlerFunction ? {
-  handler: H;
-} : H;
-type ServerOptions<D extends EventDefs, P extends PresenceDefs = Record<never, never>, R extends RegisteredReducer<D, P> | undefined = RegisteredReducer<D, P> | undefined> = {
+};
+/**
+ * A consumer written in `createServer({ consumers })`: `consumer()`'s
+ * options without the contract, which is the server's, and its `run`.
+ */
+type InlineConsumer<D extends EventDefs, P extends PresenceDefs, R extends RegisteredReducer<D, P> | undefined, K extends keyof D & string> = Omit<ConsumerOptions<D, P, R, K>, "contract"> & {
+  run: (ctx: ConsumerContext<D, K, P, PublicState<R>>) => ConsumerResult<D>;
+};
+/** The types an inline consumer takes: the ones it lists, or every type. */
+type InlineTypes<D extends EventDefs, X> = unknown extends X ? keyof D & string : Extract<X, keyof D & string>;
+/**
+ * `createServer`'s consumers: each a `consumer()` or written inline. `C` is
+ * inferred per entry, so an inline `run` sees only the types it lists.
+ */
+type ServerConsumers<D extends EventDefs, P extends PresenceDefs, R extends RegisteredReducer<D, P> | undefined, C extends readonly unknown[]> = { readonly [I in keyof C]: InlineConsumer<D, P, R, InlineTypes<D, C[I]>> | Extract<C[I], Consumer<D>>; };
+/** Define a consumer: a named reader of each session's log. */
+declare function consumer<D extends EventDefs, P extends PresenceDefs, R extends RegisteredReducer<D, P> | undefined, const K extends keyof D & string = keyof D & string>(options: ConsumerOptions<D, P, R, K>): {
+  run(fn: (ctx: ConsumerContext<D, K, P, PublicState<R>>) => ConsumerResult<D>): Consumer<D>;
+};
+type ServerOptions<D extends EventDefs, P extends PresenceDefs = Record<never, never>, R extends RegisteredReducer<D, P> | undefined = RegisteredReducer<D, P> | undefined, C extends readonly unknown[] = readonly Consumer<D>[]> = {
   /** The contract this server implements (see `a2.contract`). */
   contract: Contract<D, P, R>;
   /** Where events live. Defaults: sqlite in dev, memory in tests, required in prod. */
@@ -372,15 +440,14 @@ type ServerOptions<D extends EventDefs, P extends PresenceDefs = Record<never, n
     ttlMs?: number;
   };
   /**
-   * The reactions, keyed by event type — all present at construction,
-   * so a handler can never be silently missing because its module
-   * wasn't imported. Compose across files by spreading objects (note:
-   * a duplicate key under spread silently last-wins).
+   * The consumers, each a named reader of every session's log with its own
+   * cursors: a `consumer()`, or its options and `run` written inline, on this
+   * contract. Names are unique; a duplicate throws.
    */
-  handlers?: { [K in keyof D & string]?: HandlerEntry<D, K, P, PublicState<R>>; };
+  consumers?: ServerConsumers<D, P, R, C> | readonly Consumer<D>[];
 };
 /** Implement a contract: bind its vocabulary to storage and reactions. */
-declare function createServer<D extends EventDefs, P extends PresenceDefs = Record<never, never>, R extends RegisteredReducer<D, P> | undefined = RegisteredReducer<D, P> | undefined>(options: ServerOptions<D, P, R>): A2Server<D, P, R>;
+declare function createServer<D extends EventDefs, P extends PresenceDefs = Record<never, never>, R extends RegisteredReducer<D, P> | undefined = RegisteredReducer<D, P> | undefined, const C extends readonly unknown[] = readonly Consumer<D>[]>(options: ServerOptions<D, P, R, C>): A2Server<D, P, R>;
 //#endregion
-export { ScheduledEvent as A, A2Socket as B, SessionRedriveResult as C, deliverSchedulerAppend as D, createServer as E, A2Operation as F, A2PushEvent as I, A2PushPresence as L, SchedulerClearTask as M, SchedulerDrainTask as N, deliverSchedulerClear as O, SchedulerTask as P, ServerFetchOptions as R, SessionRedriveOptions as S, StateOptions as T, SessionClearOptions as _, DrainableServer as a, SessionDispatch as b, HandlerContext as c, LaneContext as d, ScheduleDelay as f, SessionAppend as g, Session as h, DeadLetter as i, SchedulerAppendTask as j, handler as k, HandlerEntry as l, ServerOptions as m, A2Server as n, Handler as o, ScheduleTiming as p, AbortSpec as r, HandlerAppend as s, A2Scheduler as t, Lane as u, SessionClearResult as v, SessionSchedule as w, SessionPresence as x, SessionDeadLetters as y, UpgradeWebSocket as z };
-//# sourceMappingURL=server-DYAATFuT.d.ts.map
+export { SessionSchedule as A, SchedulerTask as B, SessionConsumeOptions as C, SessionPresence as D, SessionDispatch as E, deliverSchedulerClear as F, UpgradeWebSocket as G, A2PushEvent as H, ScheduledEvent as I, A2Socket as K, SchedulerAppendTask as L, consumer as M, createServer as N, SessionRedriveOptions as O, deliverSchedulerAppend as P, SchedulerClearTask as R, SessionClearResult as S, SessionDeadLetters as T, A2PushPresence as U, A2Operation as V, ServerFetchOptions as W, ServerConsumers as _, ConsumerAppend as a, SessionAppend as b, ConsumerOptions as c, DeadLetter as d, DrainableServer as f, ScheduleTiming as g, ScheduleDelay as h, Consumer as i, StateOptions as j, SessionRedriveResult as k, ConsumerResult as l, LaneContext as m, A2Server as n, ConsumerContext as o, InlineConsumer as p, AbortSpec as r, ConsumerLane as s, A2Scheduler as t, ConsumerSpec as u, ServerOptions as v, SessionConsumeResult as w, SessionClearOptions as x, Session as y, SchedulerDrainTask as z };
+//# sourceMappingURL=server-qgez0Xny.d.ts.map

package/dist/server-qgez0Xny.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-qgez0Xny.d.ts","names":[],"sources":["../src/session-socket.ts","../src/server-fetch.ts","../src/scheduler-task.ts","../src/server.ts"],"mappings":"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"}

package/dist/server.browser.js

@@ -3,7 +3,7 @@
 * The browser build of experimental-a2/server. There isn't one — on purpose.
 * Contracts and reducers (from `experimental-a2`) and the session client (from
 * `experimental-a2/client` / `experimental-a2/react`) are the isomorphic surface; the server is
-* where handlers and storage live. This module existing in a client
+* where consumers and storage live. This module existing in a client
 * bundle means a `'use client'` file (or something it imports)
 * value-imported your server module.
 */

package/dist/server.browser.js.map

@@ -1 +1 @@
-{"version":3,"file":"server.browser.js","names":[],"sources":["../src/server.browser.ts"],"sourcesContent":["/**\n * The browser build of experimental-a2/server. There isn't one — on purpose.\n * Contracts and reducers (from `experimental-a2`) and the session client (from\n * `experimental-a2/client` / `experimental-a2/react`) are the isomorphic surface; the server is\n * where handlers and storage live. This module existing in a client\n * bundle means a `'use client'` file (or something it imports)\n * value-imported your server module.\n */\nthrow new Error(\n  'experimental-a2/server is server-only — a client bundle imported it. Import the contract (a2) or the session client (experimental-a2/client, experimental-a2/react) in browser code instead.',\n)\nexport {}\n"],"mappings":";;;;;;;;;AAQA,MAAM,IAAI,MACR,8LACF"}
+{"version":3,"file":"server.browser.js","names":[],"sources":["../src/server.browser.ts"],"sourcesContent":["/**\n * The browser build of experimental-a2/server. There isn't one — on purpose.\n * Contracts and reducers (from `experimental-a2`) and the session client (from\n * `experimental-a2/client` / `experimental-a2/react`) are the isomorphic surface; the server is\n * where consumers and storage live. This module existing in a client\n * bundle means a `'use client'` file (or something it imports)\n * value-imported your server module.\n */\nthrow new Error(\n  'experimental-a2/server is server-only — a client bundle imported it. Import the contract (a2) or the session client (experimental-a2/client, experimental-a2/react) in browser code instead.',\n)\nexport {}\n"],"mappings":";;;;;;;;;AAQA,MAAM,IAAI,MACR,8LACF"}

package/dist/server.d.ts

@@ -1,4 +1,4 @@
-import { c as ContractEvent, d as PresenceDefs, f as PresenceMap, m as PresenceSnapshot, o as AppendInput, p as PresencePatch, s as Contract, u as EventDefs } from "./reducer-CqA59Q6U.js";
-import { a as EventCause, c as PresenceRow, d as StoreStateRead, f as StoredEvent, i as Event, l as StoreAppendResult, n as AppendEvent, o as FailAttemptResult, r as Clock, s as IdSource, t as A2Store, u as StoreClaimAvailableResult } from "./store-CyLUy86v.js";
-import { A as ScheduledEvent, B as A2Socket, C as SessionRedriveResult, D as deliverSchedulerAppend, E as createServer, F as A2Operation, I as A2PushEvent, L as A2PushPresence, M as SchedulerClearTask, N as SchedulerDrainTask, O as deliverSchedulerClear, P as SchedulerTask, R as ServerFetchOptions, S as SessionRedriveOptions, T as StateOptions, _ as SessionClearOptions, a as DrainableServer, b as SessionDispatch, c as HandlerContext, d as LaneContext, f as ScheduleDelay, g as SessionAppend, h as Session, i as DeadLetter, j as SchedulerAppendTask, k as handler, l as HandlerEntry, m as ServerOptions, n as A2Server, o as Handler, p as ScheduleTiming, r as AbortSpec, s as HandlerAppend, t as A2Scheduler, u as Lane, v as SessionClearResult, w as SessionSchedule, x as SessionPresence, y as SessionDeadLetters, z as UpgradeWebSocket } from "./server-DYAATFuT.js";
-export { type A2Operation, type A2PushEvent, type A2PushPresence, A2Scheduler, A2Server, type A2Socket, type A2Store, AbortSpec, type AppendEvent, type AppendInput, type Clock, type Contract, type ContractEvent, DeadLetter, DrainableServer, type Event, type EventCause, type EventDefs, type FailAttemptResult, Handler, HandlerAppend, HandlerContext, HandlerEntry, type IdSource, Lane, LaneContext, type PresenceDefs, type PresenceMap, type PresencePatch, type PresenceRow, type PresenceSnapshot, ScheduleDelay, ScheduleTiming, type ScheduledEvent, type SchedulerAppendTask, type SchedulerClearTask, type SchedulerDrainTask, type SchedulerTask, type ServerFetchOptions, ServerOptions, Session, SessionAppend, SessionClearOptions, SessionClearResult, SessionDeadLetters, SessionDispatch, SessionPresence, SessionRedriveOptions, SessionRedriveResult, SessionSchedule, StateOptions, type StoreAppendResult, type StoreClaimAvailableResult, type StoreStateRead, type StoredEvent, type UpgradeWebSocket, createServer, deliverSchedulerAppend, deliverSchedulerClear, handler };
+import { c as ContractEvent, d as PresenceDefs, f as PresenceMap, m as PresenceSnapshot, o as AppendInput, p as PresencePatch, s as Contract, u as EventDefs } from "./reducer-CYPHsSmd.js";
+import { a as EventCause, c as PresenceRow, d as StoreStateRead, f as StoredEvent, i as Event, l as StoreAppendResult, n as AppendEvent, o as FailAttemptResult, r as Clock, s as IdSource, t as A2Store, u as StoreClaimAvailableResult } from "./store-D0MhBvg6.js";
+import { A as SessionSchedule, B as SchedulerTask, C as SessionConsumeOptions, D as SessionPresence, E as SessionDispatch, F as deliverSchedulerClear, G as UpgradeWebSocket, H as A2PushEvent, I as ScheduledEvent, K as A2Socket, L as SchedulerAppendTask, M as consumer, N as createServer, O as SessionRedriveOptions, P as deliverSchedulerAppend, R as SchedulerClearTask, S as SessionClearResult, T as SessionDeadLetters, U as A2PushPresence, V as A2Operation, W as ServerFetchOptions, _ as ServerConsumers, a as ConsumerAppend, b as SessionAppend, c as ConsumerOptions, d as DeadLetter, f as DrainableServer, g as ScheduleTiming, h as ScheduleDelay, i as Consumer, j as StateOptions, k as SessionRedriveResult, l as ConsumerResult, m as LaneContext, n as A2Server, o as ConsumerContext, p as InlineConsumer, r as AbortSpec, s as ConsumerLane, t as A2Scheduler, u as ConsumerSpec, v as ServerOptions, w as SessionConsumeResult, x as SessionClearOptions, y as Session, z as SchedulerDrainTask } from "./server-qgez0Xny.js";
+export { type A2Operation, type A2PushEvent, type A2PushPresence, A2Scheduler, A2Server, type A2Socket, type A2Store, AbortSpec, type AppendEvent, type AppendInput, type Clock, Consumer, ConsumerAppend, ConsumerContext, ConsumerLane, ConsumerOptions, ConsumerResult, ConsumerSpec, type Contract, type ContractEvent, DeadLetter, DrainableServer, type Event, type EventCause, type EventDefs, type FailAttemptResult, type IdSource, InlineConsumer, LaneContext, type PresenceDefs, type PresenceMap, type PresencePatch, type PresenceRow, type PresenceSnapshot, ScheduleDelay, ScheduleTiming, type ScheduledEvent, type SchedulerAppendTask, type SchedulerClearTask, type SchedulerDrainTask, type SchedulerTask, ServerConsumers, type ServerFetchOptions, ServerOptions, Session, SessionAppend, SessionClearOptions, SessionClearResult, SessionConsumeOptions, SessionConsumeResult, SessionDeadLetters, SessionDispatch, SessionPresence, SessionRedriveOptions, SessionRedriveResult, SessionSchedule, StateOptions, type StoreAppendResult, type StoreClaimAvailableResult, type StoreStateRead, type StoredEvent, type UpgradeWebSocket, consumer, createServer, deliverSchedulerAppend, deliverSchedulerClear };

package/dist/server.js

@@ -1,2 +1,2 @@
-import { i as handler, n as deliverSchedulerAppend, r as deliverSchedulerClear, t as createServer } from "./server-qyb5aJJG.js";
-export { createServer, deliverSchedulerAppend, deliverSchedulerClear, handler };
+import { i as deliverSchedulerClear, n as createServer, r as deliverSchedulerAppend, t as consumer } from "./server-DtFrWxi3.js";
+export { consumer, createServer, deliverSchedulerAppend, deliverSchedulerClear };

package/dist/{session-clear-C-QwTXV1.d.ts → session-clear-D1PFe7xl.d.ts}

@@ -1,4 +1,4 @@
-import { i as Event } from "./store-CyLUy86v.js";
+import { i as Event } from "./store-D0MhBvg6.js";
 //#region src/session-clear.d.ts
 /** Reserved type of the marker a clear appends. */
 declare const CLEAR_EVENT_TYPE = "a2.cleared";
@@ -9,4 +9,4 @@ type SessionCleared = Event & {
 };
 //#endregion
 export { SessionCleared as t };
-//# sourceMappingURL=session-clear-C-QwTXV1.d.ts.map
+//# sourceMappingURL=session-clear-D1PFe7xl.d.ts.map

package/dist/session-clear-D1PFe7xl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-clear-D1PFe7xl.d.ts","names":[],"sources":["../src/session-clear.ts"],"mappings":";;;cAOa;;KAGD,iBAAiB;EAC3B,aAAa;EACb"}

package/dist/{session-clear-DGI4jTQ5.js → session-clear-wHd5GCpZ.js}

@@ -10,9 +10,10 @@ var A2Error = class extends Error {
 		this.details = options?.details;
 	}
 };
-/** A handler write whose attempt no longer owns its triggering event. */
+/** A consumer write whose attempt no longer owns its triggering event. */
 function supersededAttemptError(sessionId, cause) {
-	return new A2Error("SUPERSEDED_ATTEMPT", `attempt ${cause.attempt} no longer owns event ${cause.index} in session '${sessionId}'`);
+	const of = cause.consumer === void 0 ? "" : ` for consumer '${cause.consumer}'`;
+	return new A2Error("SUPERSEDED_ATTEMPT", `attempt ${cause.attempt} no longer owns event ${cause.index}${of} in session '${sessionId}'`);
 }
 /**
 * Wrap an arbitrary thrown value as STORE_UNAVAILABLE, preserving the
@@ -24,7 +25,7 @@ function asStoreUnavailable(err) {
 	return new A2Error("STORE_UNAVAILABLE", "the store backend failed", { cause: err });
 }
 /**
-* Throw from a handler to reject retrying: the failure is adjudicated
+* Throw from a consumer to reject retrying: the failure is adjudicated
 * terminal immediately (dead-lettered on the first throw) instead of
 * consuming the ten-failure retry budget. For deterministic failures —
 * a guard that will refuse identically on every attempt — retrying is
@@ -51,4 +52,4 @@ function sessionClearedError(message) {
 //#endregion
 export { NonRetriableError as a, A2Error as i, isSessionCleared as n, asStoreUnavailable as o, sessionClearedError as r, supersededAttemptError as s, CLEAR_EVENT_TYPE as t };
 
-//# sourceMappingURL=session-clear-DGI4jTQ5.js.map
+//# sourceMappingURL=session-clear-wHd5GCpZ.js.map

package/dist/session-clear-wHd5GCpZ.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-clear-wHd5GCpZ.js","names":[],"sources":["../src/errors.ts","../src/session-clear.ts"],"sourcesContent":["export type A2ServerErrorCode =\n  | 'INVALID_PAYLOAD' // schema validation failed — thrown before anything is written\n  | 'FORBIDDEN' // external ingress was denied by server.fetch authorization\n  | 'UNKNOWN_EVENT_TYPE' // event type not in the machine's `events` map\n  | 'PARTIAL_DUPLICATE_BATCH' // batch mixed already-appended and fresh events\n  | 'SUPERSEDED_ATTEMPT' // consumer append from an attempt a recovery claim or a clear replaced\n  | 'SESSION_CLEARED' // a read or call reached across the session's latest clear\n  | 'CLAIM_EXPIRED' // ctx.signal abort reason: the attempt's lease lapsed without renewal\n  | 'STORE_UNAVAILABLE' // store backend failure — retryable, nothing was written\n  | 'STORE_NOT_CONFIGURED' // no `store` in production, a missing peer dependency, or Postgres lacks A2's tables\n  | 'UNKNOWN_PRESENCE_FIELD' // presence field not in the contract's `presence` map\n  | 'PRESENCE_NOT_SUPPORTED' // contract declares presence but the store lacks the capability\n  | 'CONSUMER_DEAD_LETTERED' // session.consume reached a head that dead-lettered for that consumer\n\nexport type A2ErrorCode =\n  A2ServerErrorCode | 'TIMEOUT' | 'HTTP_ERROR' | 'CONNECTION_FAILED' | 'UNKNOWN'\n\nexport class A2Error extends Error {\n  readonly code: A2ErrorCode\n  /** e.g. the Standard Schema issues for INVALID_PAYLOAD */\n  readonly details: unknown\n\n  constructor(\n    code: A2ErrorCode,\n    message: string,\n    options?: { details?: unknown; cause?: unknown },\n  ) {\n    super(\n      message,\n      options && 'cause' in options ? { cause: options.cause } : undefined,\n    )\n    this.name = 'A2Error'\n    this.code = code\n    this.details = options?.details\n  }\n}\n\n/** A consumer write whose attempt no longer owns its triggering event. */\nexport function supersededAttemptError(\n  sessionId: string,\n  cause: { consumer?: string; index: number; attempt: number },\n): A2Error {\n  const of =\n    cause.consumer === undefined ? '' : ` for consumer '${cause.consumer}'`\n  return new A2Error(\n    'SUPERSEDED_ATTEMPT',\n    `attempt ${cause.attempt} no longer owns event ${cause.index}${of} in session '${sessionId}'`,\n  )\n}\n\n/**\n * Wrap an arbitrary thrown value as STORE_UNAVAILABLE, preserving the\n * original as `cause`. A2Errors pass through untouched — they already\n * carry their own meaning.\n */\nexport function asStoreUnavailable(err: unknown): A2Error {\n  if (err instanceof A2Error) return err\n  return new A2Error('STORE_UNAVAILABLE', 'the store backend failed', {\n    cause: err,\n  })\n}\n\n/**\n * Throw from a consumer to reject retrying: the failure is adjudicated\n * terminal immediately (dead-lettered on the first throw) instead of\n * consuming the ten-failure retry budget. For deterministic failures —\n * a guard that will refuse identically on every attempt — retrying is\n * waste and dead-lettering is the honest outcome. Matched by\n * `instanceof`, so subclasses carry domain meaning.\n */\nexport class NonRetriableError extends Error {\n  constructor(message: string, options?: { cause?: unknown }) {\n    super(message, options)\n    this.name = 'NonRetriableError'\n  }\n}\n","import { A2Error } from './errors.ts'\nimport type { Event } from './store.ts'\n\n/** A2's own event types start with this; application contracts cannot. */\nexport const RESERVED_EVENT_PREFIX = 'a2.'\n\n/** Reserved type of the marker a clear appends. */\nexport const CLEAR_EVENT_TYPE = 'a2.cleared'\n\n/** The marker `session.stream()` yields where a clear ended a lifetime. */\nexport type SessionCleared = Event & {\n  type: typeof CLEAR_EVENT_TYPE\n  payload: null\n}\n\n/** Accepts any stream item, including presence patches and snapshots. */\nexport function isSessionCleared(item: object): item is SessionCleared {\n  return (item as { type?: unknown }).type === CLEAR_EVENT_TYPE\n}\n\nexport function sessionClearedError(message: string): A2Error {\n  return new A2Error('SESSION_CLEARED', message)\n}\n"],"mappings":";AAiBA,IAAa,UAAb,cAA6B,MAAM;CACjC;;CAEA;CAEA,YACE,MACA,SACA,SACA;EACA,MACE,SACA,WAAW,WAAW,UAAU,EAAE,OAAO,QAAQ,MAAM,IAAI,KAAA,CAC7D;EACA,KAAK,OAAO;EACZ,KAAK,OAAO;EACZ,KAAK,UAAU,SAAS;CAC1B;AACF;;AAGA,SAAgB,uBACd,WACA,OACS;CACT,MAAM,KACJ,MAAM,aAAa,KAAA,IAAY,KAAK,kBAAkB,MAAM,SAAS;CACvE,OAAO,IAAI,QACT,sBACA,WAAW,MAAM,QAAQ,wBAAwB,MAAM,QAAQ,GAAG,eAAe,UAAU,EAC7F;AACF;;;;;;AAOA,SAAgB,mBAAmB,KAAuB;CACxD,IAAI,eAAe,SAAS,OAAO;CACnC,OAAO,IAAI,QAAQ,qBAAqB,4BAA4B,EAClE,OAAO,IACT,CAAC;AACH;;;;;;;;;AAUA,IAAa,oBAAb,cAAuC,MAAM;CAC3C,YAAY,SAAiB,SAA+B;EAC1D,MAAM,SAAS,OAAO;EACtB,KAAK,OAAO;CACd;AACF;;;;ACpEA,MAAa,mBAAmB;;AAShC,SAAgB,iBAAiB,MAAsC;CACrE,OAAQ,KAA4B,SAAS;AAC/C;AAEA,SAAgB,oBAAoB,SAA0B;CAC5D,OAAO,IAAI,QAAQ,mBAAmB,OAAO;AAC/C"}