experimental-a2 0.4.0 → 0.5.1

package/dist/scheduler-vercel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scheduler-vercel.js","names":[],"sources":["../src/scheduler-vercel.ts"],"sourcesContent":["/**\n * experimental-a2/scheduler-vercel — queue-backed scheduler over Vercel Queues.\n *\n * `vercelQueues()` returns an `A2Scheduler` (a2-implementation.md §9):\n *\n * - drain tasks round the requested watchdog time up to a one-second slot.\n *   One message per `(topic, contract, session, dueAt)` coalesces appends,\n *   claim renewals and racing callbacks. `DuplicateMessageError` is\n *   success because that due-time slot is already durable.\n * - append tasks hash their stable task id with the topic for provider\n *   deduplication. Their six-day maximum delay leaves a full day for\n *   delivery and retries inside the provider's seven-day retention.\n *   They target the publishing deployment unless explicitly configured\n *   as deploymentless. Drain tasks always remain deployment-scoped.\n * - `handler(...servers)` is the delivery route: look up the server for\n *   the contract named in the message and drain it. Settled drains ack;\n *   contention arms a later watchdog before acking; handler failure keeps\n *   the current message and redelivers with backoff.\n *\n * `@vercel/queue` is an optional peer dependency, imported lazily. The\n * `transport` option is the injection seam — tests run a real little\n * in-memory queue through the same interface.\n */\n\nimport { createHash } from 'node:crypto'\nimport { SYSTEM_CLOCK, type Clock } from './store.ts'\nimport {\n  assertSchedulerTargets,\n  classifySchedulerSendFailure,\n  DRAIN_TIMINGS,\n  serverInternals,\n} from './internal.ts'\nimport { retryableLazy } from './retryable-lazy.ts'\nimport {\n  normalizeSchedulerTask,\n  type SchedulerDrainTask,\n  type SchedulerTask,\n} from './scheduler-task.ts'\nimport {\n  deliverSchedulerAppend,\n  type A2Scheduler,\n  type DrainableServer,\n} from './server.ts'\n\n/**\n * The \"not settled yet\" signal for a stalled handler — an expected state,\n * not a transport failure. The default transport classifies it in\n * `@vercel/queue`'s `retry` option and reschedules the delivery quietly\n * (`{ afterSeconds }` → visibility change → 200 response, no error log)\n * instead of letting it surface as a thrown 500. Busy deliveries use a\n * fresh watchdog instead. Custom transports should treat this class the\n * same way when their protocol has a polite reschedule.\n */\nexport class DrainUnsettled extends Error {}\n\nexport type QueueDeliveryMetadata = {\n  messageId: string\n  deliveryCount: number\n}\n\ntype VercelQueueMessage = SchedulerTask & {\n  /** Provider-private state used to address callback lease operations. */\n  _a2Vercel?: {\n    version: 1\n    deployment: 'deployment' | 'deploymentless'\n  }\n}\n\n/** What this module needs from a Vercel Queues-compatible transport. */\nexport type QueueTransport = {\n  send(\n    topic: string,\n    message: SchedulerTask,\n    options?: {\n      delaySeconds?: number\n      idempotencyKey?: string\n      retentionSeconds?: number\n    },\n    /** Resolved A2 affinity. Custom transports own its provider mapping. */\n    routing?: {\n      deployment: 'deployment' | 'deploymentless'\n    },\n  ): Promise<unknown>\n  /**\n   * Wrap the delivery handler into a route. The handler throws\n   * `DrainUnsettled` when the session needs redelivery — transports\n   * with a polite reschedule (visibility change) should use it there\n   * instead of surfacing an error; anything else thrown is a genuine\n   * failure and should stay loud.\n   */\n  handleCallback(\n    handler: (\n      message: unknown,\n      metadata: QueueDeliveryMetadata,\n    ) => Promise<void>,\n  ): (req: Request) => Promise<Response>\n  /** Is this send error the idempotency-key collision? (= success) */\n  isDuplicate(error: unknown): boolean\n}\n\nexport type VercelQueuesOptions = {\n  /** Queue topic matching `[A-Za-z0-9_-]+`. Default `'a2'`. */\n  topic?: string\n  /**\n   * Deployment affinity for scheduled append tasks. Recovery drain tasks\n   * always target the publishing deployment. Default `'deployment'`.\n   */\n  scheduledAppends?: 'deployment' | 'deploymentless'\n  /** Injectable transport (tests). Default: `@vercel/queue`. */\n  transport?: QueueTransport\n  /** Injectable clock for due-time calculations (tests). */\n  clock?: Clock\n}\n\n/** Vercel Queues rejects shorter visibility changes. */\nconst MIN_VISIBILITY_SECONDS = 30\n\n/** Vercel Queues' maximum message retention and delivery delay. */\nconst MAX_RETENTION_SECONDS = 7 * 24 * 60 * 60\n\n/** Leave the final retention day for delivery and retries. */\nconst MAX_DELAY_SECONDS = 6 * 24 * 60 * 60\n\nconst TOPIC_PATTERN = /^[A-Za-z0-9_-]+$/\nconst RETRYABLE_HTTP_CLIENT_STATUSES = new Set([408, 409, 425, 429])\n/** The SDK's send path maps these statuses to name-only error instances. */\nconst TERMINAL_VERCEL_SEND_ERROR_NAMES = new Set([\n  'BadRequestError',\n  'UnauthorizedError',\n  'ForbiddenError',\n])\n\nconst recordOf = (value: unknown): Record<string, unknown> | null =>\n  value !== null && typeof value === 'object' && !Array.isArray(value)\n    ? (value as Record<string, unknown>)\n    : null\n\nconst httpStatusOf = (error: unknown): number | undefined => {\n  try {\n    const record = recordOf(error)\n    if (!record) return undefined\n    const response = recordOf(record['response'])\n    const statuses = [\n      record['status'],\n      record['statusCode'],\n      response?.['status'],\n    ].filter(\n      (value): value is number =>\n        typeof value === 'number' &&\n        Number.isInteger(value) &&\n        value >= 100 &&\n        value <= 599,\n    )\n    const [status] = statuses\n    if (status === undefined) return undefined\n    return statuses.every((candidate) => candidate === status)\n      ? status\n      : undefined\n  } catch {\n    return undefined\n  }\n}\n\nconst errorNameOf = (error: unknown): string | undefined => {\n  try {\n    const name = recordOf(error)?.['name']\n    return typeof name === 'string' ? name : undefined\n  } catch {\n    return undefined\n  }\n}\n\nconst classifyVercelSendFailure = (error: unknown): unknown => {\n  const status = httpStatusOf(error)\n  const terminal =\n    status === undefined\n      ? TERMINAL_VERCEL_SEND_ERROR_NAMES.has(errorNameOf(error) ?? '')\n      : status >= 400 &&\n        status < 500 &&\n        !RETRYABLE_HTTP_CLIENT_STATUSES.has(status)\n  return classifySchedulerSendFailure(\n    error,\n    terminal ? 'terminal' : 'retryable',\n  )\n}\n\nconst digestId = (parts: readonly string[]): string =>\n  `a2_${createHash('sha256').update(JSON.stringify(parts)).digest('hex')}`\n\n/** Base of the unsettled redelivery backoff, doubled per delivery. */\nconst UNSETTLED_BACKOFF_BASE_SECONDS = 5\n\n/** Redelivery backoff for retry states: base, 2×, 4×… bounded. */\nconst unsettledBackoffSeconds = (deliveryCount: number): number =>\n  Math.min(\n    Math.max(\n      UNSETTLED_BACKOFF_BASE_SECONDS * 2 ** Math.max(deliveryCount - 1, 0),\n      MIN_VISIBILITY_SECONDS,\n    ),\n    60,\n  )\n\nconst vercelQueueTransport = async (): Promise<QueueTransport> => {\n  const queue = await import('@vercel/queue').catch(() => {\n    throw classifySchedulerSendFailure(\n      new Error(\n        \"experimental-a2/scheduler-vercel needs the '@vercel/queue' package (optional peer dependency) — install it, or inject a transport\",\n      ),\n      'terminal',\n    )\n  })\n  const deploymentClient = new queue.QueueClient()\n  const deploymentlessClient = new queue.QueueClient({ deploymentId: null })\n  return {\n    send: (topic, message, options, routing) => {\n      const deployment = routing?.deployment ?? 'deployment'\n      const body: VercelQueueMessage = {\n        ...message,\n        _a2Vercel: { version: 1, deployment },\n      }\n      return (\n        deployment === 'deploymentless'\n          ? deploymentlessClient\n          : deploymentClient\n      ).send(topic, body, options)\n    },\n    handleCallback: (handler) => {\n      const callbackOptions = {\n        // A hard-killed callback normally has a fresh claim watchdog. If\n        // its successor send also failed, make the old unacked delivery's\n        // fallback as prompt as Vercel Queues permits.\n        visibilityTimeoutSeconds: MIN_VISIBILITY_SECONDS,\n        // Not-settled-yet is an expected state: reschedule the (still\n        // unacked) delivery via a visibility change — 200, no error\n        // log. Everything else returns undefined → the SDK's default\n        // throw path, which is loud on purpose.\n        retry: (error: unknown, metadata: QueueDeliveryMetadata) =>\n          error instanceof DrainUnsettled\n            ? {\n                afterSeconds: unsettledBackoffSeconds(metadata.deliveryCount),\n              }\n            : undefined,\n      }\n      const deploymentHandler = deploymentClient.handleCallback(\n        handler,\n        callbackOptions,\n      ) as (req: Request) => Promise<Response>\n      const deploymentlessHandler = deploymentlessClient.handleCallback(\n        handler,\n        callbackOptions,\n      ) as (req: Request) => Promise<Response>\n      return async (req: Request): Promise<Response> => {\n        let delivered: unknown\n        try {\n          delivered = await req.clone().json()\n        } catch {\n          return deploymentlessHandler(req)\n        }\n        const metadata = recordOf(recordOf(delivered)?.['_a2Vercel'])\n        const routing =\n          metadata?.['version'] === 1 ? metadata['deployment'] : undefined\n        return routing === 'deployment'\n          ? deploymentHandler(req)\n          : deploymentlessHandler(req)\n      }\n    },\n    isDuplicate: (error) => error instanceof queue.DuplicateMessageError,\n  }\n}\n\nexport function vercelQueues(options: VercelQueuesOptions = {}): A2Scheduler {\n  const topic = options.topic ?? 'a2'\n  if (typeof topic !== 'string' || !TOPIC_PATTERN.test(topic)) {\n    throw new TypeError('vercelQueues() topic must match [A-Za-z0-9_-]+')\n  }\n  const scheduledAppends = options.scheduledAppends ?? 'deployment'\n  if (\n    scheduledAppends !== 'deployment' &&\n    scheduledAppends !== 'deploymentless'\n  ) {\n    throw new TypeError(\n      \"vercelQueues() scheduledAppends must be 'deployment' or 'deploymentless'\",\n    )\n  }\n  const clock = options.clock ?? SYSTEM_CLOCK\n\n  // Lazy: constructing the scheduler value does no I/O and works without\n  // the peer dep until the first task or delivery.\n  const transport = retryableLazy(() =>\n    options.transport\n      ? Promise.resolve(options.transport)\n      : vercelQueueTransport(),\n  ).get\n\n  const sendTask = async (task: SchedulerTask): Promise<void> => {\n    const nowMs = clock.now().getTime()\n    const requestedDueAt = task.dueAt\n    if (!Number.isFinite(requestedDueAt)) {\n      throw classifySchedulerSendFailure(\n        new TypeError('vercel scheduler dueAt must be a finite number'),\n        'terminal',\n      )\n    }\n    const dueAt =\n      requestedDueAt <= nowMs\n        ? Math.floor(nowMs / 1_000) * 1_000\n        : Math.ceil(requestedDueAt / 1_000) * 1_000\n    const deliveryTargetAt = task.kind === 'append' ? requestedDueAt : dueAt\n    const deliveryDelaySeconds = Math.max(\n      0,\n      Math.ceil((deliveryTargetAt - nowMs) / 1_000),\n    )\n    if (deliveryDelaySeconds > MAX_DELAY_SECONDS) {\n      throw classifySchedulerSendFailure(\n        new RangeError(\n          'vercelQueues() tasks cannot be delayed more than 6 days',\n        ),\n        'terminal',\n      )\n    }\n    const deployment = task.kind === 'append' ? scheduledAppends : 'deployment'\n    const message: SchedulerTask = { ...task, dueAt }\n    const idempotencyKey =\n      task.kind === 'drain'\n        ? digestId([\n            'a2:scheduler-vercel:drain:v1',\n            topic,\n            task.contract,\n            task.sessionId,\n            String(dueAt),\n          ])\n        : digestId(['a2:scheduler-vercel:append:v1', topic, task.id])\n    const t = await transport()\n    try {\n      await t.send(\n        topic,\n        message,\n        {\n          delaySeconds: deliveryDelaySeconds,\n          idempotencyKey,\n          retentionSeconds: MAX_RETENTION_SECONDS,\n        },\n        { deployment },\n      )\n    } catch (err) {\n      if (t.isDuplicate(err)) return\n      throw classifyVercelSendFailure(err)\n    }\n  }\n\n  const successorDueAt = (message: SchedulerDrainTask): number => {\n    const minimumDueAt =\n      clock.now().getTime() +\n      DRAIN_TIMINGS.claimTtlMs +\n      DRAIN_TIMINGS.watchdogGraceMs\n    const beats = Math.max(\n      1,\n      Math.ceil(\n        (minimumDueAt - message.dueAt) / DRAIN_TIMINGS.claimHeartbeatMs,\n      ),\n    )\n    return message.dueAt + beats * DRAIN_TIMINGS.claimHeartbeatMs\n  }\n\n  return {\n    async schedule(task) {\n      await sendTask(task)\n    },\n\n    handler(...servers: DrainableServer[]) {\n      assertSchedulerTargets(servers, { allowStructural: true })\n      const byContract = new Map<string, DrainableServer>()\n      for (const server of servers) {\n        byContract.set(server.contract.name, server)\n      }\n      return async (req: Request): Promise<Response> => {\n        const t = await transport()\n        return t.handleCallback(async (delivered) => {\n          const task = normalizeSchedulerTask(delivered)\n          if (!task) {\n            throw new TypeError('a2 scheduler received an invalid task')\n          }\n          const server = byContract.get(task.contract)\n          if (!server) {\n            // A message for a contract this route doesn't serve is a\n            // wiring bug — throw so it redelivers and stays visible in\n            // queue observability instead of vanishing on an ack.\n            throw new Error(\n              `a2 scheduler: no server for contract '${task.contract}' — pass it to schedulerHandler(...)`,\n            )\n          }\n          const internals = serverInternals.get(server)\n          if (task.kind === 'append') {\n            await deliverSchedulerAppend(server, task)\n            return\n          }\n\n          const nextDueAt = successorDueAt(task)\n          const result = internals\n            ? await internals.schedulerDrain(task.sessionId, {\n                watchdogDueAt: nextDueAt,\n              })\n            : {\n                ...(await server.drain(task.sessionId)),\n                outcome: 'unknown' as const,\n              }\n          if (result.settled) return\n\n          if (result.outcome === 'busy') {\n            // The live owner normally arms its own claim windows.\n            // Ensure a later slot here as well before relinquishing this\n            // durable delivery. If the queue is down, the throw leaves the\n            // current message unacked for visibility-timeout redelivery.\n            if (result.schedulerArm) await result.schedulerArm\n            else {\n              await sendTask({\n                version: 1,\n                kind: 'drain',\n                contract: task.contract,\n                sessionId: task.sessionId,\n                dueAt: nextDueAt,\n              })\n            }\n            return\n          }\n\n          // Handler failure keeps the current durable message and uses the\n          // transport retry path. Dead-lettered sessions count as settled\n          // above, so retries stop there.\n          throw new DrainUnsettled(\n            `a2 scheduler: session '${task.sessionId}' of '${task.contract}' not settled yet (${result.outcome}) — rescheduled for redelivery`,\n          )\n        })(req)\n      }\n    },\n  }\n}\n"],"mappings":"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"}

package/dist/{server-YtPq7hjw.d.ts → server-DpvjhdoE.d.ts}

@@ -1,6 +1,6 @@
 import { a as EventDefs, c as PresencePatch, d as WithPresence, l as PresenceSnapshot, n as Contract, o as PresenceDefs, p as Reducer, r as ContractEvent, s as PresenceMap, t as AppendInput } from "./contract-jIfaR085.js";
-import { t as A2Store } from "./store-C3sNAaBT.js";
-import { i as A2Telemetry } from "./telemetry-BjYHTfh2.js";
+import { t as A2Store } from "./store-DysUkTH3.js";
+import { i as A2Telemetry } from "./telemetry-CpeclqB2.js";
 //#region src/scheduler-task.d.ts
 /** One event carried by a delayed append task. */
 type ScheduledEvent = {
@@ -154,8 +154,8 @@ type Session<D extends EventDefs, Append = SessionAppend<D>, P extends PresenceD
   }>;
   /**
    * A live feed of this session's events, starting after `startAfter`
-   * (exclusive). Server-side only — expose it over SSE with
-   * `sseResponse` from experimental-a2/http.
+   * (exclusive). Server-side only — `handle` from experimental-a2/http
+   * exposes it over SSE as the route's stream lane.
    */
   stream(opts?: {
     startAfter?: number;
@@ -257,4 +257,5 @@ type ServerOptions<D extends EventDefs, P extends PresenceDefs = Record<never, n
 /** Implement a contract: bind its vocabulary to storage and reactions. */
 declare function createServer<D extends EventDefs, P extends PresenceDefs = Record<never, never>>(options: ServerOptions<D, P>): A2Server<D, P>;
 //#endregion
-export { deliverSchedulerAppend as C, SchedulerTask as D, SchedulerDrainTask as E, createServer as S, SchedulerAppendTask as T, Session as _, Handler as a, SessionPresence as b, HandlerEntry as c, PushValidationContext as d, PushedEvent as f, ServerOptions as g, ScheduleTiming as h, DrainableServer as i, Lane as l, ScheduleDelay as m, A2Server as n, HandlerAppend as o, PushedPresence as p, AbortSpec as r, HandlerContext as s, A2Scheduler as t, LaneContext as u, SessionAppend as v, ScheduledEvent as w, SessionSchedule as x, SessionDispatch as y };
+export { deliverSchedulerAppend as C, SchedulerTask as D, SchedulerDrainTask as E, createServer as S, SchedulerAppendTask as T, Session as _, Handler as a, SessionPresence as b, HandlerEntry as c, PushValidationContext as d, PushedEvent as f, ServerOptions as g, ScheduleTiming as h, DrainableServer as i, Lane as l, ScheduleDelay as m, A2Server as n, HandlerAppend as o, PushedPresence as p, AbortSpec as r, HandlerContext as s, A2Scheduler as t, LaneContext as u, SessionAppend as v, ScheduledEvent as w, SessionSchedule as x, SessionDispatch as y };
+//# sourceMappingURL=server-DpvjhdoE.d.ts.map

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

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

package/dist/{server-CcNnFnoW.js → server-Duw6MVlB.js}

@@ -1,8 +1,8 @@
 import { n as validateSync } from "./validate-XKT4FSNn.js";
 import { n as asStoreUnavailable, t as A2Error } from "./errors-BQuJpe82.js";
-import { g as nullProtoRecord, h as markSchedulerSendFailure, i as POLL_TIMINGS, o as RESERVED_PARTICIPANT_IDS, t as DRAIN_TIMINGS, v as serverInternals, y as serverSchedulerBindings } from "./internal-aEotMzu_.js";
+import { g as nullProtoRecord, h as markSchedulerSendFailure, i as POLL_TIMINGS, o as RESERVED_PARTICIPANT_IDS, t as DRAIN_TIMINGS, v as serverInternals, y as serverSchedulerBindings } from "./internal-DstsI6Re.js";
 import { n as InspectionUnsupportedError, r as serverInspection } from "./inspection-DaxB5jM2.js";
-import { t as defaultSleep } from "./store-polling-DgrrAE3d.js";
+import { t as defaultSleep } from "./store-polling-dSeLxzfb.js";
 import { r as platformWaitUntil, t as invocationDeadlineMs } from "./platform-B4TnJtWu.js";
 import { t as retryableLazy } from "./retryable-lazy-DZWmHpii.js";
 //#region src/deterministic-id.ts
@@ -66,12 +66,18 @@ async function deterministicScheduledEventId(scheduleId, itemOrdinal) {
 }
 //#endregion
 //#region src/telemetry.ts
-const NOOP_HANDLE = {
+/**
+* The default when no telemetry is configured. Spans cost nothing, but
+* `recordError` prints: it only ever receives errors a2 swallows by
+* design, so without a configured sink the console is the one place
+* they can surface. Passing `telemetry` replaces this sink wholesale.
+*/
+const CONSOLE_TELEMETRY = { span: (name, attributes, fn) => fn({
 	setAttribute: () => {},
-	recordError: () => {}
-};
-/** The zero-cost default when no telemetry is configured. */
-const NOOP_TELEMETRY = { span: (_name, _attributes, fn) => fn(NOOP_HANDLE) };
+	recordError: (error) => {
+		console.error(`[a2] error in ${name}`, attributes, error);
+	}
+}) };
 //#endregion
 //#region src/server.ts
 /**
@@ -230,7 +236,7 @@ function createServer(options) {
 		};
 	}
 	const resolveStore = retryableLazy(makeStore).get;
-	const telemetry = options.telemetry ?? NOOP_TELEMETRY;
+	const telemetry = options.telemetry ?? CONSOLE_TELEMETRY;
 	const scheduler = options.scheduler;
 	const handlers = /* @__PURE__ */ new Map();
 	for (const [type, entry] of Object.entries(options.handlers ?? {})) {
@@ -440,59 +446,109 @@ function createServer(options) {
 			throw asStoreUnavailable(err);
 		}
 	};
-	const readState = async (sessionId, reducer) => {
-		const store = await resolveStore();
-		return telemetry.span("a2.state", {
-			"a2.contract": name,
-			"a2.session_id": sessionId,
-			"a2.state.reducer": reducer.name
-		}, async (span) => {
-			let state = cloneInitial(reducer.initialState);
-			let index = 0;
-			let snapshotOutcome = "miss";
-			let stateRead;
+	const readCachedState = async (store, sessionId, reducerName) => {
+		try {
+			return await store.readState(nsId(sessionId), reducerName);
+		} catch {
 			try {
-				stateRead = await store.readState(nsId(sessionId), reducer.name);
-			} catch {
-				try {
-					stateRead = {
-						snapshot: null,
-						events: await store.read(nsId(sessionId))
-					};
-				} catch (err) {
-					throw asStoreUnavailable(err);
-				}
+				return {
+					snapshot: null,
+					events: await store.read(nsId(sessionId))
+				};
+			} catch (err) {
+				throw asStoreUnavailable(err);
 			}
-			const snap = stateRead.snapshot;
-			let rows = stateRead.events;
-			if (snap) {
-				if (reducer.stateSchema) {
-					const result = validateSync(reducer.stateSchema, snap.state, "the stateSchema");
-					if (result.issues) snapshotOutcome = "rejected";
-					else {
-						state = result.value;
-						index = snap.index;
-						snapshotOutcome = "hit";
-					}
-				} else {
-					state = snap.state;
+		}
+	};
+	const foldStateRead = async (store, sessionId, reducer, stateRead, span) => {
+		let state = cloneInitial(reducer.initialState);
+		let index = 0;
+		let snapshotOutcome = "miss";
+		const snap = stateRead.snapshot;
+		let rows = stateRead.events;
+		if (snap) {
+			if (reducer.stateSchema) {
+				const result = validateSync(reducer.stateSchema, snap.state, "the stateSchema");
+				if (result.issues) snapshotOutcome = "rejected";
+				else {
+					state = result.value;
 					index = snap.index;
 					snapshotOutcome = "hit";
 				}
+			} else {
+				state = snap.state;
+				index = snap.index;
+				snapshotOutcome = "hit";
 			}
-			span.setAttribute("a2.state.snapshot", snapshotOutcome);
-			if (snapshotOutcome === "rejected") try {
-				rows = await store.read(nsId(sessionId));
-			} catch (err) {
-				throw asStoreUnavailable(err);
-			}
-			for (const row of rows) {
-				state = reducer.fold(state, toPublic(row));
-				index = row.index;
+		}
+		span.setAttribute("a2.state.snapshot", snapshotOutcome);
+		if (snapshotOutcome === "rejected") try {
+			rows = await store.read(nsId(sessionId));
+		} catch (err) {
+			throw asStoreUnavailable(err);
+		}
+		for (const row of rows) {
+			state = reducer.fold(state, toPublic(row));
+			index = row.index;
+		}
+		span.setAttribute("a2.state.folded", rows.length);
+		span.setAttribute("a2.state.index", index);
+		return {
+			state,
+			index,
+			folded: rows.length
+		};
+	};
+	const pendingStateReads = /* @__PURE__ */ new Map();
+	const flushStateReads = async (store, reducerName, batch) => {
+		let reads;
+		try {
+			reads = store.readStates ? await store.readStates(batch.map((entry) => nsId(entry.sessionId)), reducerName) : null;
+		} catch {
+			reads = null;
+		}
+		if (!reads || reads.length !== batch.length) {
+			for (const entry of batch) entry.resolve(readCachedState(store, entry.sessionId, reducerName));
+			return;
+		}
+		const seen = /* @__PURE__ */ new Set();
+		for (const [position, entry] of batch.entries()) {
+			const shared = seen.has(entry.sessionId);
+			seen.add(entry.sessionId);
+			try {
+				const read = reads[position];
+				entry.resolve(shared ? structuredClone(read) : read);
+			} catch {
+				entry.resolve(readCachedState(store, entry.sessionId, reducerName));
 			}
-			span.setAttribute("a2.state.folded", rows.length);
-			span.setAttribute("a2.state.index", index);
-			if (rows.length > 0) {
+		}
+	};
+	const enqueueStateRead = (store, sessionId, reducerName) => new Promise((resolve) => {
+		let batch = pendingStateReads.get(reducerName);
+		if (!batch) {
+			const opened = [];
+			pendingStateReads.set(reducerName, opened);
+			queueMicrotask(() => {
+				pendingStateReads.delete(reducerName);
+				flushStateReads(store, reducerName, opened);
+			});
+			batch = opened;
+		}
+		batch.push({
+			sessionId,
+			resolve
+		});
+	});
+	const readState = async (sessionId, reducer) => {
+		const store = await resolveStore();
+		return telemetry.span("a2.state", {
+			"a2.contract": name,
+			"a2.session_id": sessionId,
+			"a2.state.reducer": reducer.name
+		}, async (span) => {
+			const stateRead = store.readStates ? await enqueueStateRead(store, sessionId, reducer.name) : await readCachedState(store, sessionId, reducer.name);
+			const { state, index, folded } = await foldStateRead(store, sessionId, reducer, stateRead, span);
+			if (folded > 0) {
 				const snapshotState = cloneInitial(state);
 				const write = Promise.resolve().then(() => store.putSnapshot(nsId(sessionId), reducer.name, index, snapshotState)).catch(() => {});
 				track(write);
@@ -1403,3 +1459,5 @@ function cloneInitial(initial) {
 }
 //#endregion
 export { deliverSchedulerAppend as n, createServer as t };
+
+//# sourceMappingURL=server-Duw6MVlB.js.map