experimental-a2 0.3.0 → 0.5.0

package/dist/http.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.js","names":[],"sources":["../src/sse.ts","../src/push-envelope.ts","../src/session-socket.ts","../src/http.ts"],"sourcesContent":["/**\n * The SSE response protocol — framing, heartbeat, deadline, and\n * teardown for the live stream lane. Internal module: `handle`'s\n * stream branch is the one sanctioned caller; the framing rules stay\n * documented on `sseResponse` because the client's parser (and the\n * stall watchdog) depend on them.\n */\n\nimport { STREAM_TIMINGS } from './internal.ts'\nimport type { Event } from './store.ts'\nimport type { PresencePatch, PresenceSnapshot } from './contract.ts'\nimport { invocationDeadlineMs } from './platform.ts'\nimport {\n  eventToWire,\n  presencePatchToWire,\n  presenceSnapshotToWire,\n} from './wire.ts'\n\n/**\n * Pipe a live event iterable into an SSE `Response`. Each event is one\n * frame — `id:` carries the event-log index, `data:` the JSON event. A\n * `stream({ presence: true })` iterable also yields presence items,\n * which ride as named frames old clients skip: `event:\n * presence-snapshot` first (the map, ISO dates), then `event: presence`\n * per patch — no `id:`, presence never advances the resume frontier. A\n * disconnecting client cancels the stream, which closes the underlying\n * subscription. Two kinds of comment frames ride along: a `: connected`\n * prelude that flushes headers immediately, and a `: ping` heartbeat\n * every 15 seconds so clients (and proxies) can tell a quiet stream\n * from a dead connection — the session client's stall watchdog counts\n * on it. When the platform exposes an invocation deadline, the response\n * closes cleanly one second before it so the client reconnects without\n * a platform-timeout failure.\n */\nexport function sseResponse(\n  iterable: AsyncIterable<Event | PresencePatch | PresenceSnapshot>,\n): Response {\n  const iterator = iterable[Symbol.asyncIterator]()\n  const encoder = new TextEncoder()\n  let heartbeat: ReturnType<typeof setInterval> | undefined\n  let deadlineTimer: ReturnType<typeof setTimeout> | undefined\n  let closed = false\n  let iteratorReturned = false\n  const stopTimers = (): void => {\n    if (heartbeat !== undefined) clearInterval(heartbeat)\n    if (deadlineTimer !== undefined) clearTimeout(deadlineTimer)\n    heartbeat = undefined\n    deadlineTimer = undefined\n  }\n  const returnIterator = async (): Promise<void> => {\n    if (iteratorReturned) return\n    iteratorReturned = true\n    await iterator.return?.()\n  }\n  const stream = new ReadableStream<Uint8Array>({\n    start(controller) {\n      // Prelude comment frame: flushes headers immediately (a fresh\n      // session may otherwise send nothing for a long time — some\n      // servers buffer headers until the first byte, and clients can't\n      // report \"live\" until they see the response), and gives proxies\n      // early proof this is a stream. Comment frames are invisible to\n      // SSE consumers.\n      controller.enqueue(encoder.encode(': connected\\n\\n'))\n      // Heartbeat: comment frames are ignored by SSE parsers but are\n      // bytes on the wire — liveness proof for the client's watchdog\n      // and for idle-timeout-happy intermediaries.\n      heartbeat = setInterval(() => {\n        try {\n          controller.enqueue(encoder.encode(': ping\\n\\n'))\n        } catch {\n          // The stream closed underneath the timer.\n          stopTimers()\n        }\n      }, STREAM_TIMINGS.sseHeartbeatMs)\n      ;(heartbeat as { unref?: () => void }).unref?.()\n\n      const invocationDeadline = invocationDeadlineMs()\n      if (invocationDeadline !== null) {\n        const delay = Math.max(\n          0,\n          invocationDeadline - Date.now() - STREAM_TIMINGS.sseDeadlineGraceMs,\n        )\n        deadlineTimer = setTimeout(() => {\n          if (closed) return\n          closed = true\n          stopTimers()\n          void returnIterator().catch(() => {})\n          try {\n            controller.close()\n          } catch {\n            // The response already closed underneath the timer.\n          }\n        }, delay)\n        ;(deadlineTimer as { unref?: () => void }).unref?.()\n      }\n    },\n    async pull(controller) {\n      try {\n        const { value, done } = await iterator.next()\n        if (closed) return\n        if (done) {\n          closed = true\n          stopTimers()\n          controller.close()\n          return\n        }\n        controller.enqueue(encoder.encode(frameFor(value)))\n      } catch (error) {\n        if (closed) return\n        closed = true\n        stopTimers()\n        void returnIterator().catch(() => {})\n        throw error\n      }\n    },\n    async cancel() {\n      if (closed) return\n      closed = true\n      stopTimers()\n      await returnIterator()\n    },\n  })\n  return new Response(stream, {\n    status: 200,\n    headers: {\n      'content-type': 'text/event-stream',\n      'cache-control': 'no-cache, no-transform',\n      connection: 'keep-alive',\n    },\n  })\n}\n\nfunction frameFor(item: Event | PresencePatch | PresenceSnapshot): string {\n  if ('snapshot' in item) {\n    return `event: presence-snapshot\\ndata: ${JSON.stringify(presenceSnapshotToWire(item))}\\n\\n`\n  }\n  if ('participant' in item) {\n    return `event: presence\\ndata: ${JSON.stringify(presencePatchToWire(item))}\\n\\n`\n  }\n  return `id: ${item.index}\\ndata: ${JSON.stringify(eventToWire(item))}\\n\\n`\n}\n","/**\n * The push envelope's trust boundary — parsing and provenance-branding\n * for `{ sessionId, events, presence? }`, shared verbatim by the HTTP\n * POST lane and the socket's push/presence frames so INVALID_PAYLOAD\n * shapes are one implementation. Internal module — `handle` (and the\n * socket handler) compose it; it is not part of the public surface.\n */\n\nimport { A2Error } from './errors.ts'\nimport { MAX_DATE_MS, RESERVED_PARTICIPANT_IDS } from './internal.ts'\nimport type { PushedEvent, PushedPresence } from './server.ts'\n\nexport const invalidPushBody = (message: string): A2Error =>\n  new A2Error('INVALID_PAYLOAD', `malformed push body: ${message}`)\n\nconst invalid = invalidPushBody\n\nexport type PushBody = {\n  sessionId: string\n  /** Branded: `session.append` accepts these directly (the push route\n   * path); schema validation still happens inside `append`. Empty only\n   * for a presence-only push. */\n  events: PushedEvent[]\n  /** Branded like `events`: `session.setPresence` accepts it whole;\n   * field validation still happens inside `setPresence`. */\n  presence?: PushedPresence\n}\n\nexport function parsePresenceSibling(\n  value: unknown,\n): PushedPresence | undefined {\n  if (value === undefined) return undefined\n  if (value === null || typeof value !== 'object' || Array.isArray(value)) {\n    throw invalid('presence must be an object when present')\n  }\n  const { participant, values, seen, at } = value as Record<string, unknown>\n  if (typeof participant !== 'string' || participant.length === 0) {\n    throw invalid('presence.participant must be a non-empty string')\n  }\n  if (RESERVED_PARTICIPANT_IDS.has(participant)) {\n    throw invalid(`presence.participant must not be '${participant}'`)\n  }\n  if (values === null || typeof values !== 'object' || Array.isArray(values)) {\n    throw invalid('presence.values must be an object')\n  }\n  if (\n    seen !== undefined &&\n    (typeof seen !== 'number' || !Number.isFinite(seen) || seen < 0)\n  ) {\n    throw invalid('presence.seen must be a non-negative number when present')\n  }\n  if (\n    at !== undefined &&\n    (typeof at !== 'number' ||\n      !Number.isFinite(at) ||\n      at < 0 ||\n      at > MAX_DATE_MS)\n  ) {\n    throw invalid(\n      'presence.at must be a non-negative epoch-milliseconds timestamp within the Date range when present',\n    )\n  }\n  const out: {\n    participant: string\n    values: Record<string, unknown>\n    seen?: number\n    at?: number\n  } = { participant, values: values as Record<string, unknown> }\n  if (seen !== undefined) out.seen = seen\n  if (at !== undefined) out.at = at\n  Object.defineProperty(out, '~a2.pushed', { value: true })\n  return out as PushedPresence\n}\n\n/** The events half of the envelope — shared verbatim by the POST body\n * and the socket's `push` frames, so the provenance brand and the\n * INVALID_PAYLOAD shapes are one implementation. */\nexport function parsePushEvents(events: unknown): PushedEvent[] {\n  if (!Array.isArray(events) || events.length === 0) {\n    throw invalid('events must be a non-empty array')\n  }\n  return events.map((event, i) => {\n    if (event === null || typeof event !== 'object') {\n      throw invalid(`events[${i}] must be an object`)\n    }\n    const { type, payload, id } = event as Record<string, unknown>\n    if (typeof type !== 'string' || type.length === 0) {\n      throw invalid(`events[${i}].type must be a non-empty string`)\n    }\n    if (id !== undefined && typeof id !== 'string') {\n      throw invalid(`events[${i}].id must be a string when present`)\n    }\n    const out: { type: string; payload: unknown; id?: string } = {\n      type,\n      payload,\n    }\n    if (id !== undefined) out.id = id\n    Object.defineProperty(out, '~a2.pushed', { value: true })\n    return out as PushedEvent\n  })\n}\n\n/**\n * Validate the push envelope — `{ sessionId, events, presence? }` —\n * throwing `INVALID_PAYLOAD` on a malformed body. Payload validation\n * against the machine's schemas happens in `append` and `setPresence`,\n * not here. Either plane may appear alone: a presence-only push has no\n * (or empty) `events`.\n */\nexport async function parsePushBody(req: Request): Promise<PushBody> {\n  let body: unknown\n  try {\n    body = await req.json()\n  } catch (cause) {\n    throw new A2Error('INVALID_PAYLOAD', 'push body is not valid JSON', {\n      cause,\n    })\n  }\n  if (body === null || typeof body !== 'object') {\n    throw invalid('expected an object')\n  }\n  const { sessionId, events, presence } = body as Record<string, unknown>\n  if (typeof sessionId !== 'string' || sessionId.length === 0) {\n    throw invalid('sessionId must be a non-empty string')\n  }\n  const parsedPresence = parsePresenceSibling(presence)\n  if (\n    parsedPresence !== undefined &&\n    (events === undefined || (Array.isArray(events) && events.length === 0))\n  ) {\n    return { sessionId, events: [], presence: parsedPresence }\n  }\n  const parsed = parsePushEvents(events)\n  return parsedPresence !== undefined\n    ? { sessionId, events: parsed, presence: parsedPresence }\n    : { sessionId, events: parsed }\n}\n","/**\n * The A2 socket protocol's server half (specs/a2-api.md §13): the\n * per-socket shell — teardown, backpressure, heartbeat, the malformed\n * budget, the in-flight bound — and `sessionsSocket`, the multiplexed\n * frame handler riding it. Internal module: `handle`'s upgrade lane is\n * the sanctioned mount; only `A2Socket` (the structural socket the\n * platform hands over) is re-exported as public surface.\n */\n\nimport { A2Error } from './errors.ts'\nimport { SOCKET_TIMINGS, STREAM_TIMINGS } from './internal.ts'\nimport type { Event } from './store.ts'\nimport type { EventDefs, PresencePatch, PresenceSnapshot } from './contract.ts'\nimport type { PushedEvent, PushedPresence, Session } from './server.ts'\nimport { parsePresenceSibling, parsePushEvents } from './push-envelope.ts'\nimport {\n  SOCKET_PING_FRAME,\n  asA2Error,\n  socketAckFor,\n  socketErrorAckFor,\n  socketFrameFor,\n  socketSubscribedFor,\n  socketUnsubscribedFor,\n} from './wire.ts'\n\n// ── the ws wire ───────────────────────────────────────────────────────\n\n/**\n * The structural socket `sessionsSocket` speaks against — satisfied\n * by `ws` and by `@vercel/functions`' upgraded socket alike, so the\n * platform upgrade API stays out of the library. `message` data\n * arrives as whatever the platform delivers (string, Buffer,\n * ArrayBuffer, or fragments); the handler normalizes defensively.\n */\nexport type A2Socket = {\n  send(data: string): void\n  on(event: 'message', listener: (data: unknown) => void): void\n  on(event: 'close', listener: () => void): void\n  on(event: 'error', listener: (error: unknown) => void): void\n  close(code?: number, reason?: string): void\n  /** Bytes queued but not yet transmitted — when exposed, the down\n   * pump uses it for backpressure (`SOCKET_TIMINGS`). */\n  bufferedAmount?: number\n}\n\nconst messageText = (data: unknown): string | null => {\n  if (typeof data === 'string') return data\n  if (data instanceof ArrayBuffer) return new TextDecoder().decode(data)\n  if (ArrayBuffer.isView(data)) return new TextDecoder().decode(data)\n  if (Array.isArray(data) && data.every(ArrayBuffer.isView)) {\n    // ws delivers fragmented messages as a Buffer array; stream-decode\n    // so multi-byte characters can span fragment boundaries.\n    const decoder = new TextDecoder()\n    let text = ''\n    for (const part of data) text += decoder.decode(part, { stream: true })\n    return text + decoder.decode()\n  }\n  return null\n}\n\n/**\n * How many unparseable or invalid frames a socket may send before it\n * is closed (1008): the budget absorbs isolated client bugs without\n * letting a broken peer spin the validation path forever. Push frames\n * with a usable `req` never count — their failures are answered with\n * error acks, exactly like the POST path's 4xx bodies.\n */\nconst MAX_MALFORMED_FRAMES = 5\n\n/**\n * The pump's runtime view of a session. The presence members are\n * conditional on the public surface (`WithPresence`) and therefore\n * invisible on a generic `Session<D>`, so capability is checked at\n * runtime (`setPresence` present) — the same resolution as the docs'\n * route sample. The casts live in `sessionsSocket` and `handle`.\n */\nexport type SocketSession = {\n  stream(opts: {\n    startAfter: number\n    presence?: boolean\n  }): AsyncIterable<Event | PresencePatch | PresenceSnapshot>\n  append(...events: PushedEvent[]): Promise<Event[]>\n  setPresence?(patch: PushedPresence): Promise<void>\n}\n\n/**\n * The per-socket machinery `sessionsSocket` builds on: the torn flag\n * with a release-once teardown, the backpressure-aware send with its\n * non-reader ceiling, the malformed budget, the in-flight bound, the\n * message normalization, the heartbeat, and the optional deadline.\n */\ntype SocketShell = {\n  torn(): boolean\n  send(data: string): void\n  shutdown(code: number, reason?: string): void\n  malformedFrame(reason: string): void\n  buffered(): number\n  overCap(): boolean\n  track(work: Promise<void>): void\n}\n\nfunction socketShell(\n  socket: A2Socket,\n  release: () => void,\n  onFrame: (frame: Record<string, unknown>) => void,\n  deadlineAt: number | undefined,\n): SocketShell {\n  let torn = false\n  let malformed = 0\n  let heartbeat: ReturnType<typeof setInterval> | undefined\n  let deadline: ReturnType<typeof setTimeout> | undefined\n\n  const teardown = (): void => {\n    if (torn) return\n    torn = true\n    if (heartbeat !== undefined) clearInterval(heartbeat)\n    if (deadline !== undefined) clearTimeout(deadline)\n    release()\n  }\n\n  const shutdown = (code: number, reason?: string): void => {\n    if (torn) return\n    teardown()\n    try {\n      socket.close(code, reason)\n    } catch {\n      // Already closed underneath us — teardown has run either way.\n    }\n  }\n\n  const send = (data: string): void => {\n    if (torn) return\n    // The pump parks at the high-water mark, but acks and pings are\n    // exempt (small, correctness-relevant) — so a peer that never\n    // reads while it keeps uploading grows the buffer through its own\n    // acks. The ceiling closes the class: past it, the peer is not a\n    // slow reader, it is a non-reader (adversarial F4).\n    if (\n      typeof socket.bufferedAmount === 'number' &&\n      socket.bufferedAmount > SOCKET_TIMINGS.disconnectWaterMarkBytes\n    ) {\n      shutdown(1008, 'backpressure: peer not reading')\n      return\n    }\n    try {\n      socket.send(data)\n    } catch {\n      // The platform closed the socket without an event; closing it\n      // again would throw the same way, so just tear down.\n      teardown()\n    }\n  }\n\n  const malformedFrame = (reason: string): void => {\n    malformed += 1\n    if (malformed >= MAX_MALFORMED_FRAMES) {\n      shutdown(1008, `too many malformed frames (last: ${reason})`)\n    }\n  }\n\n  // The up-lane bound (adversarial F3): one socket must not hold\n  // unbounded concurrent appends. Shedding is per-plane semantics —\n  // pushes are TOLD (retryable error ack, ids make the retry safe),\n  // presence is silently dropped (a lost update is repainted by the\n  // next one). Sheds are our load decision, never the peer's\n  // malformedness, so they spend no budget.\n  let inFlight = 0\n  const track = (work: Promise<void>): void => {\n    inFlight += 1\n    void work.finally(() => {\n      inFlight -= 1\n    })\n  }\n\n  const handleMessage = (data: unknown): void => {\n    if (torn) return\n    const text = messageText(data)\n    if (text === null) {\n      malformedFrame('non-text frame')\n      return\n    }\n    let parsed: unknown\n    try {\n      parsed = JSON.parse(text)\n    } catch {\n      malformedFrame('frame is not valid JSON')\n      return\n    }\n    if (\n      parsed === null ||\n      typeof parsed !== 'object' ||\n      Array.isArray(parsed)\n    ) {\n      malformedFrame('frame is not an object')\n      return\n    }\n    onFrame(parsed as Record<string, unknown>)\n  }\n\n  socket.on('message', handleMessage)\n  socket.on('close', teardown)\n  socket.on('error', teardown)\n\n  heartbeat = setInterval(\n    () => send(SOCKET_PING_FRAME),\n    STREAM_TIMINGS.sseHeartbeatMs,\n  )\n  ;(heartbeat as { unref?: () => void }).unref?.()\n\n  if (deadlineAt !== undefined) {\n    deadline = setTimeout(\n      () => shutdown(1000, 'deadline'),\n      Math.max(0, deadlineAt - Date.now()),\n    )\n    ;(deadline as { unref?: () => void }).unref?.()\n  }\n\n  return {\n    torn: () => torn,\n    send,\n    shutdown,\n    malformedFrame,\n    buffered: () =>\n      typeof socket.bufferedAmount === 'number' ? socket.bufferedAmount : 0,\n    overCap: () => inFlight >= SOCKET_TIMINGS.maxInFlightMessages,\n    track,\n  }\n}\n\n/**\n * The per-session authorization seam of `sessionsSocket`: called once\n * per `subscribe` entry (and never for the pushes and presence that\n * ride an accepted subscription). `null` rejects that session — the\n * socket answers `unsubscribed` with a rejection reason and every\n * other session on it is untouched.\n */\nexport type SessionsSocketResolve<D extends EventDefs> = (\n  sessionId: string,\n  /** The entry's resume frontier — `stream({ startAfter })`. */\n  startAfter: number,\n) => Session<D> | null | Promise<Session<D> | null>\n\nexport type SessionsSocketOptions = {\n  /** The `stream()` presence opt-in for every session on the socket —\n   * the server decides, same rule as the SSE route. */\n  presence?: boolean\n  /** Epoch ms: close cleanly (code 1000) at this time, ahead of a known\n   * platform deadline, so clients reconnect on our schedule. */\n  deadline?: number\n  /**\n   * Per-frame push gate — policy's seam on the up lane, the socket\n   * counterpart of a POST route's checks (`handle`'s `before` rides\n   * it). Runs after the frame parses and before `append`: return an\n   * `A2Error` to answer the push with that error ack (nothing\n   * appended), `null` to allow. Absent, every push on an accepted\n   * subscription is allowed — the prior behavior, unchanged.\n   */\n  gatePush?(\n    sessionId: string,\n    events: PushedEvent[],\n  ): A2Error | null | Promise<A2Error | null>\n}\n\ntype SocketSubscription = {\n  target: SocketSession\n  iterator: AsyncIterator<Event | PresencePatch | PresenceSnapshot>\n  stopped: boolean\n}\n\nconst stopSubscription = (subscription: SocketSubscription): void => {\n  subscription.stopped = true\n  void subscription.iterator.return?.()?.catch(() => {})\n}\n\nconst parseSubscribeEntries = (\n  value: unknown,\n): Array<{ id: string; index: number }> | null => {\n  if (!Array.isArray(value) || value.length === 0) return null\n  const entries: Array<{ id: string; index: number }> = []\n  for (const entry of value) {\n    if (entry === null || typeof entry !== 'object') return null\n    const { id, index } = entry as Record<string, unknown>\n    if (typeof id !== 'string' || id.length === 0) return null\n    if (typeof index !== 'number' || !Number.isInteger(index) || index < 0) {\n      return null\n    }\n    entries.push({ id, index })\n  }\n  return entries\n}\n\n/**\n * Speak the multiplexed A2 socket protocol (specs/a2-api.md §13)\n * against many sessions on one socket. `subscribe` frames open a\n * per-session pump at that session's own resume frontier; push and\n * presence frames route by `sessionId` through the same validation\n * seams as the POST lane; every down frame carries the `sessionId` it\n * belongs to. One heartbeat, one\n * malformed budget, one in-flight bound, one backpressure gauge — per\n * socket, shared by all sessions. A session's stream ending or failing\n * answers `unsubscribed` for that session; only the peer, the\n * deadline, the malformed budget, or backpressure closes the socket.\n */\nexport function sessionsSocket<D extends EventDefs>(\n  resolve: SessionsSocketResolve<D>,\n  socket: A2Socket,\n  options?: SessionsSocketOptions,\n): void {\n  const presence = options?.presence === true\n  const subscriptions = new Map<string, SocketSubscription>()\n\n  const retire = (id: string, subscription: SocketSubscription): void => {\n    if (subscriptions.get(id) === subscription) subscriptions.delete(id)\n  }\n\n  const pump = async (\n    id: string,\n    subscription: SocketSubscription,\n  ): Promise<void> => {\n    for (;;) {\n      for (;;) {\n        if (\n          shell.torn() ||\n          subscription.stopped ||\n          shell.buffered() <= SOCKET_TIMINGS.highWaterMarkBytes\n        )\n          break\n        // oxlint-disable-next-line no-await-in-loop -- backpressure park\n        await new Promise((wake) =>\n          setTimeout(wake, SOCKET_TIMINGS.resumePollMs),\n        )\n      }\n      if (shell.torn() || subscription.stopped) return\n      // oxlint-disable-next-line no-await-in-loop -- stream pump\n      const { value, done } = await subscription.iterator.next()\n      if (shell.torn() || subscription.stopped) return\n      if (done) return\n      shell.send(socketFrameFor(value, id))\n    }\n  }\n\n  const runSubscription = async (\n    id: string,\n    subscription: SocketSubscription,\n  ): Promise<void> => {\n    try {\n      await pump(id, subscription)\n      if (shell.torn() || subscription.stopped) return\n      retire(id, subscription)\n      shell.send(socketUnsubscribedFor(id))\n    } catch {\n      if (shell.torn() || subscription.stopped) return\n      retire(id, subscription)\n      shell.send(socketUnsubscribedFor(id, 'stream failed'))\n    }\n  }\n\n  const startSubscription = async (\n    id: string,\n    index: number,\n  ): Promise<void> => {\n    let session: Session<D> | null\n    try {\n      session = await resolve(id, index)\n    } catch {\n      session = null\n    }\n    if (shell.torn()) return\n    if (session === null) {\n      shell.send(socketUnsubscribedFor(id, 'subscribe rejected'))\n      return\n    }\n    const target = session as unknown as SocketSession\n    const existing = subscriptions.get(id)\n    if (existing) stopSubscription(existing)\n    const iterator = (\n      presence\n        ? target.stream({ startAfter: index, presence: true })\n        : target.stream({ startAfter: index })\n    )[Symbol.asyncIterator]()\n    const subscription: SocketSubscription = {\n      target,\n      iterator,\n      stopped: false,\n    }\n    subscriptions.set(id, subscription)\n    shell.send(socketSubscribedFor(id))\n    void runSubscription(id, subscription)\n  }\n\n  // Control frames (subscribe/unsubscribe) run in arrival order — an\n  // unsubscribe can never overtake the subscribe it targets while the\n  // resolve hook is still pending.\n  let controlTail: Promise<void> = Promise.resolve()\n  const control = (work: () => Promise<void> | void): void => {\n    controlTail = controlTail.then(work).catch(() => {})\n  }\n\n  const handlePush = async (\n    frame: Record<string, unknown>,\n    req: number,\n    sessionId: string,\n  ): Promise<void> => {\n    const subscription = subscriptions.get(sessionId)\n    if (subscription === undefined) {\n      // Retryable: the client re-subscribes on reconnect and the retry\n      // rides the same client-generated event ids.\n      shell.send(\n        socketErrorAckFor(\n          req,\n          new A2Error(\n            'STORE_UNAVAILABLE',\n            'session is not subscribed on this socket',\n          ),\n          sessionId,\n        ),\n      )\n      return\n    }\n    try {\n      const events = parsePushEvents(frame['events'])\n      const denial = (await options?.gatePush?.(sessionId, events)) ?? null\n      if (denial !== null) {\n        shell.send(socketErrorAckFor(req, denial, sessionId))\n        return\n      }\n      const appended = await subscription.target.append(...events)\n      shell.send(socketAckFor(req, appended, sessionId))\n    } catch (err) {\n      shell.send(socketErrorAckFor(req, asA2Error(err), sessionId))\n    }\n  }\n\n  const handlePresence = async (\n    frame: Record<string, unknown>,\n    sessionId: string,\n  ): Promise<void> => {\n    const subscription = subscriptions.get(sessionId)\n    // An unsubscribe race, not malformedness — the plane repaints.\n    if (subscription === undefined) return\n    if (typeof subscription.target.setPresence !== 'function') {\n      shell.malformedFrame('presence frame on a presence-less session')\n      return\n    }\n    try {\n      const patch = parsePresenceSibling(frame)\n      if (patch) await subscription.target.setPresence(patch)\n    } catch {\n      shell.malformedFrame('invalid presence frame')\n    }\n  }\n\n  const handleFrame = (frame: Record<string, unknown>): void => {\n    switch (frame['kind']) {\n      case 'subscribe': {\n        const entries = parseSubscribeEntries(frame['sessions'])\n        if (entries === null) {\n          shell.malformedFrame('malformed subscribe frame')\n          return\n        }\n        for (const entry of entries) {\n          control(() => startSubscription(entry.id, entry.index))\n        }\n        return\n      }\n      case 'unsubscribe': {\n        const ids = frame['sessions']\n        if (\n          !Array.isArray(ids) ||\n          ids.length === 0 ||\n          !ids.every((id) => typeof id === 'string')\n        ) {\n          shell.malformedFrame('malformed unsubscribe frame')\n          return\n        }\n        for (const id of ids as string[]) {\n          control(() => {\n            const subscription = subscriptions.get(id)\n            if (subscription === undefined) return\n            stopSubscription(subscription)\n            subscriptions.delete(id)\n          })\n        }\n        return\n      }\n      case 'push': {\n        const req = frame['req']\n        const sessionId = frame['sessionId']\n        if (shell.overCap()) {\n          if (typeof req === 'number') {\n            shell.send(\n              socketErrorAckFor(\n                req,\n                new A2Error(\n                  'STORE_UNAVAILABLE',\n                  'push shed: too many in flight on this socket',\n                ),\n                typeof sessionId === 'string' ? sessionId : undefined,\n              ),\n            )\n          } else {\n            shell.malformedFrame('push frame without a numeric req')\n          }\n          return\n        }\n        if (typeof req !== 'number') {\n          shell.malformedFrame('push frame without a numeric req')\n          return\n        }\n        if (typeof sessionId !== 'string' || sessionId.length === 0) {\n          shell.send(\n            socketErrorAckFor(\n              req,\n              new A2Error('INVALID_PAYLOAD', 'push frame without a sessionId'),\n            ),\n          )\n          return\n        }\n        shell.track(handlePush(frame, req, sessionId))\n        return\n      }\n      case 'presence': {\n        if (shell.overCap()) return\n        const sessionId = frame['sessionId']\n        if (typeof sessionId !== 'string' || sessionId.length === 0) {\n          shell.malformedFrame('presence frame without a sessionId')\n          return\n        }\n        shell.track(handlePresence(frame, sessionId))\n        return\n      }\n      default:\n        return // unknown kinds are skipped — the forward-compatibility rule\n    }\n  }\n\n  const shell = socketShell(\n    socket,\n    () => {\n      for (const subscription of subscriptions.values()) {\n        stopSubscription(subscription)\n      }\n      subscriptions.clear()\n    },\n    (frame) => handleFrame(frame),\n    options?.deadline,\n  )\n}\n","/**\n * experimental-a2/http — the wire's server half (specs/a2-api.md §9–10, §13).\n *\n * A thin public assembly. The surface: `handle` — GET, POST, and the\n * socket's frames parsed into intents (stream, history, push,\n * ws-upgrade) with `before`/`after` hooks around them for policy —\n * plus `A2Intent`/`A2Outcome`/`UpgradeFn`/`A2Socket` (its argument\n * types), `errorResponse`/`deserializeError` (the A2Error wire pair\n * both sides branch on), and `schedulerHandler` (the scheduler\n * callback mount). The machinery lives in internal modules — the SSE\n * framing in sse.ts, the push-envelope trust boundary in\n * push-envelope.ts, the socket shell and multiplexed handler in\n * session-socket.ts — because nothing outside `handle` is sanctioned\n * to compose them. Policy — auth, caching, quotas — never enters this\n * module: the hooks own it.\n */\n\nimport { A2Error } from './errors.ts'\nimport {\n  assertServerSchedulerBindings,\n  assertSchedulerTargets,\n  schedulerForServer,\n} from './internal.ts'\nimport type { ContractEvent, EventDefs, PresenceDefs } from './contract.ts'\nimport type {\n  A2Server,\n  DrainableServer,\n  PushedEvent,\n  PushedPresence,\n} from './server.ts'\nimport { sseResponse } from './sse.ts'\nimport { invalidPushBody, parsePushBody } from './push-envelope.ts'\nimport {\n  sessionsSocket,\n  type A2Socket,\n  type SocketSession,\n} from './session-socket.ts'\nimport {\n  asA2Error,\n  errorFromWire,\n  errorStatus,\n  errorToWire,\n  eventToWire,\n} from './wire.ts'\n\nexport type { A2Socket } from './session-socket.ts'\n\n/**\n * Create one scheduler callback route for servers sharing the same configured\n * scheduler. Configuration mistakes throw immediately while the route module\n * is evaluated, before a delivery can be acknowledged by the wrong adapter.\n */\nexport function schedulerHandler(\n  firstServer: DrainableServer,\n  ...servers: DrainableServer[]\n): (req: Request) => Promise<Response> {\n  if (firstServer === undefined) {\n    throw new TypeError('schedulerHandler() requires at least one A2 server')\n  }\n  const scheduler = schedulerForServer(firstServer)\n  const targets = [firstServer, ...servers]\n  assertSchedulerTargets(targets, { allowStructural: false })\n  assertServerSchedulerBindings(scheduler, targets)\n  return scheduler.handler(...targets)\n}\n\n/**\n * Serialize an error into the documented wire shape,\n * `{ error: { code, message, details } }`, with the mapped status\n * (400 for caller bugs, 503 for STORE_UNAVAILABLE). Non-A2Errors become a\n * 503 STORE_UNAVAILABLE — from the client's perspective an unknown server\n * failure is retryable-once, not a protocol contract. The natural\n * return value of a `before` hook that wants the wire's own error\n * shapes.\n */\nexport function errorResponse(error: unknown): Response {\n  const a2error = asA2Error(error)\n  return Response.json(errorToWire(a2error), {\n    status: errorStatus(a2error.code),\n  })\n}\n\n/**\n * The other half of the wire pair: rebuild an `A2Error` from a response\n * body, or null if the body isn't one. Client `push` uses it so both\n * sides branch on identical codes.\n */\nexport function deserializeError(body: unknown): A2Error | null {\n  return errorFromWire(body)\n}\n\n// ── handle: the request protocol, parsed ────────────────────────\n\n/**\n * What a request (or socket frame) asks of a session, parsed — the\n * argument policy hooks branch on. `stream` covers the SSE GET and the\n * socket's subscribe frames; `push` covers the HTTP POST and the\n * socket's push frames; `history` is the bounded cold read the\n * client's `loadHistory` rides; `ws-upgrade` is the upgrade GET before\n * any frame flows.\n */\nexport type A2Intent<D extends EventDefs = EventDefs> =\n  | { type: 'ws-upgrade' }\n  | {\n      type: 'stream'\n      sessionId: string\n      startAfter: number\n      transport: 'sse' | 'ws'\n    }\n  | { type: 'history'; sessionId: string; gte: number; lte: number }\n  | {\n      type: 'push'\n      sessionId: string\n      /** Parsed and branded, payloads not yet validated — `type`\n       * autocompletes the contract's names but is any string off the\n       * wire; `append` rejects unknown types after the hooks run. */\n      events: Array<PushedEvent & { type: SuggestedEventType<D> }>\n      presence?: PushedPresence\n      transport: 'http' | 'ws'\n    }\n\n/** The contract's event names for editor completion, without excluding\n * the wire's reality (any string can arrive; validation is later). */\ntype SuggestedEventType<D extends EventDefs> =\n  (keyof D & string) | (string & Record<never, never>)\n\n/** What the library did with an allowed intent — `after`'s view.\n * `covered` = the closed range is fully present (an immutable slice of\n * the append-only log), the one caching-relevant fact the library\n * owns; policy over it belongs to the app's `after`. */\nexport type A2Outcome<D extends EventDefs = EventDefs> =\n  | { type: 'stream' }\n  | { type: 'history'; covered: boolean; events: ContractEvent<D>[] }\n  | { type: 'push'; appended: ContractEvent<D>[] }\n\n/**\n * The platform's socket-upgrade seam: given the attach callback, return\n * the 101 response. On Vercel:\n * `upgrade: (attach) => experimental_upgradeWebSocket(attach)`.\n */\nexport type UpgradeFn = (\n  attach: (socket: A2Socket) => void,\n) => Response | Promise<Response>\n\nconst parseHistoryBounds = (\n  gte: string | null,\n  lte: string | null,\n): { gte: number; lte: number } => {\n  if (gte === null || lte === null) {\n    throw new A2Error(\n      'INVALID_PAYLOAD',\n      'a history read takes both gte and lte',\n    )\n  }\n  const bounds = { gte: Number(gte), lte: Number(lte) }\n  for (const [name, value] of Object.entries(bounds)) {\n    if (!Number.isSafeInteger(value) || value < 0) {\n      throw new A2Error(\n        'INVALID_PAYLOAD',\n        `history ${name} must be a non-negative safe integer`,\n      )\n    }\n  }\n  if (bounds.gte > bounds.lte) {\n    throw new A2Error(\n      'INVALID_PAYLOAD',\n      'history gte must be less than or equal to lte',\n    )\n  }\n  return bounds\n}\n\nconst parseResumeIndex = (raw: string | null): number => {\n  if (raw === null) return 0\n  const index = Number(raw)\n  if (!Number.isSafeInteger(index) || index < 0) {\n    throw new A2Error(\n      'INVALID_PAYLOAD',\n      'stream index must be a non-negative safe integer',\n    )\n  }\n  return index\n}\n\n/** One bag: the policy hooks and the capability options — the names\n * distinguish them, so `handle(server, { presence: true })` and\n * `handle(server, { before, upgrade })` both read naturally. */\nexport type HandleOptions<D extends EventDefs = EventDefs> = {\n  /** Return a Response to deny; thrown errors are treated as\n   * infrastructure failures and answer with the retryable wire shape. */\n  before?(args: {\n    request: Request\n    intent: A2Intent<D>\n  }): Response | undefined | void | Promise<Response | undefined | void>\n  after?(args: {\n    request: Request\n    intent: A2Intent<D>\n    outcome: A2Outcome<D>\n    response: Response\n  }): Response | undefined | void | Promise<Response | undefined | void>\n  upgrade?: UpgradeFn\n  presence?: boolean\n  deadline?: number\n}\n\n/**\n * The session route pair as one call: `export const { GET, POST } =\n * handle(server, options?)` serves the live stream (SSE GET, resumed\n * at `index`), the history slice (GET with `gte`/`lte`), the push\n * envelope (POST), and — with `options.upgrade` — the multiplexed\n * WebSocket, all through one pair of policy hooks.\n *\n * Parsing is protocol, hooks are policy: a request that fails to parse\n * (missing sessionId, malformed bounds, bad push envelope) answers\n * INVALID_PAYLOAD on the wire before any hook runs. `before` sees\n * every parsed intent — HTTP requests and socket frames alike, with\n * `request` always the original (for socket frames: upgrade) Request —\n * and short-circuits by returning a Response: over HTTP it is the\n * response verbatim; over the socket it is translated to the wire's\n * own vocabulary (subscribe → `unsubscribed { reason: 'subscribe\n * rejected' }`, push → an INVALID_PAYLOAD error ack), because a\n * Response body cannot cross a socket. `after` runs only where the\n * library produced an HTTP response — never after a short-circuit,\n * never for socket frames — and may mutate `response.headers` in place\n * or return a replacement (history caching policy lives here, on\n * `outcome.covered`). `options.deadline` (epoch ms) closes sockets\n * cleanly ahead of a known platform deadline, so clients reconnect on\n * our schedule.\n */\nexport function handle<\n  D extends EventDefs,\n  P extends PresenceDefs = Record<never, never>,\n>(\n  server: A2Server<D, P>,\n  options?: HandleOptions<D>,\n): {\n  GET(req: Request): Promise<Response>\n  POST(req: Request): Promise<Response>\n} {\n  const presence = options?.presence === true\n\n  const before = async (\n    request: Request,\n    intent: A2Intent<D>,\n  ): Promise<Response | null> => {\n    const result = await options?.before?.({ request, intent })\n    return result instanceof Response ? result : null\n  }\n\n  const decorate = async (\n    request: Request,\n    intent: A2Intent<D>,\n    outcome: A2Outcome<D>,\n    response: Response,\n  ): Promise<Response> => {\n    const replaced = await options?.after?.({\n      request,\n      intent,\n      outcome,\n      response,\n    })\n    return replaced instanceof Response ? replaced : response\n  }\n\n  // Socket frames re-enter `before` with the upgrade Request — one\n  // policy point for both wires, and the fix for pushes that were\n  // gated only at subscribe time.\n  const attach =\n    (request: Request) =>\n    (socket: A2Socket): void => {\n      sessionsSocket<D>(\n        async (sessionId, startAfter) => {\n          const short = await before(request, {\n            type: 'stream',\n            sessionId,\n            startAfter,\n            transport: 'ws',\n          })\n          return short === null ? server.session(sessionId) : null\n        },\n        socket,\n        {\n          presence,\n          ...(options?.deadline === undefined\n            ? {}\n            : { deadline: options.deadline }),\n          gatePush: async (sessionId, events) => {\n            const short = await before(request, {\n              type: 'push',\n              sessionId,\n              events,\n              transport: 'ws',\n            })\n            // The denial Response cannot cross the socket; INVALID_PAYLOAD\n            // is the one caller-fault code the client never retries — a\n            // retryable code would spin retries against a standing denial.\n            return short === null\n              ? null\n              : new A2Error('INVALID_PAYLOAD', 'push rejected')\n          },\n        },\n      )\n    }\n\n  return {\n    async GET(req: Request): Promise<Response> {\n      try {\n        if (req.headers.get('upgrade')?.toLowerCase() === 'websocket') {\n          const short = await before(req, { type: 'ws-upgrade' })\n          if (short !== null) return short\n          if (options?.upgrade === undefined) {\n            return new Response(\n              \"WebSocket upgrade requested, but handle() has no upgrade implementation — pass options.upgrade, e.g. { upgrade: (attach) => experimental_upgradeWebSocket(attach) } from '@vercel/functions'\",\n              { status: 426 },\n            )\n          }\n          return await options.upgrade(attach(req))\n        }\n        const { searchParams } = new URL(req.url)\n        const sessionId = searchParams.get('sessionId')\n        if (sessionId === null || sessionId.length === 0) {\n          throw new A2Error('INVALID_PAYLOAD', 'missing sessionId')\n        }\n        const gteRaw = searchParams.get('gte')\n        const lteRaw = searchParams.get('lte')\n        if (gteRaw !== null || lteRaw !== null) {\n          const bounds = parseHistoryBounds(gteRaw, lteRaw)\n          const intent: A2Intent<D> = { type: 'history', sessionId, ...bounds }\n          const short = await before(req, intent)\n          if (short !== null) return short\n          const events = await server.session(sessionId).history(bounds)\n          const covered = events.length === bounds.lte - bounds.gte + 1\n          return await decorate(\n            req,\n            intent,\n            { type: 'history', covered, events },\n            Response.json(events.map(eventToWire)),\n          )\n        }\n        const startAfter = parseResumeIndex(searchParams.get('index'))\n        const intent: A2Intent<D> = {\n          type: 'stream',\n          sessionId,\n          startAfter,\n          transport: 'sse',\n        }\n        const short = await before(req, intent)\n        if (short !== null) return short\n        const target = server.session(sessionId) as unknown as SocketSession\n        const response = sseResponse(\n          presence\n            ? target.stream({ startAfter, presence: true })\n            : target.stream({ startAfter }),\n        )\n        return await decorate(req, intent, { type: 'stream' }, response)\n      } catch (err) {\n        return errorResponse(err)\n      }\n    },\n\n    async POST(req: Request): Promise<Response> {\n      try {\n        const body = await parsePushBody(req)\n        const intent: A2Intent<D> = {\n          type: 'push',\n          sessionId: body.sessionId,\n          events: body.events,\n          ...(body.presence === undefined ? {} : { presence: body.presence }),\n          transport: 'http',\n        }\n        const short = await before(req, intent)\n        if (short !== null) return short\n        const session = server.session(body.sessionId)\n        if (body.presence !== undefined) {\n          const target = session as unknown as SocketSession\n          if (typeof target.setPresence !== 'function') {\n            throw invalidPushBody('presence is not declared by this contract')\n          }\n          await target.setPresence(body.presence)\n        }\n        const appended =\n          body.events.length === 0 ? [] : await session.append(...body.events)\n        return await decorate(\n          req,\n          intent,\n          { type: 'push', appended },\n          Response.json(appended),\n        )\n      } catch (err) {\n        return errorResponse(err)\n      }\n    },\n  }\n}\n"],"mappings":"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"}

package/dist/{idempotent-replay-BMyHrP0L.js → idempotent-replay-DuqEkYA7.js}

@@ -1,8 +1,8 @@
-import { t as A2Error } from "./errors-BJRMd-h6.js";
+import { t as A2Error } from "./errors-BQuJpe82.js";
 //#region src/idempotent-replay.ts
 const canonicalJson = (value) => JSON.stringify(value, (_key, candidate) => {
 	if (candidate === null || typeof candidate !== "object" || Array.isArray(candidate)) return candidate;
-	return Object.fromEntries(Object.entries(candidate).toSorted(([left], [right]) => left.localeCompare(right)));
+	return Object.fromEntries(Object.entries(candidate).toSorted(([left], [right]) => left < right ? -1 : left > right ? 1 : 0));
 }) ?? "null";
 const idempotentReplay = (events, existing) => {
 	const byId = new Map(existing.map((event) => [event.id, event]));
@@ -17,3 +17,5 @@ const idempotentReplay = (events, existing) => {
 };
 //#endregion
 export { idempotentReplay as t };
+
+//# sourceMappingURL=idempotent-replay-DuqEkYA7.js.map

package/dist/idempotent-replay-DuqEkYA7.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"idempotent-replay-DuqEkYA7.js","names":[],"sources":["../src/idempotent-replay.ts"],"sourcesContent":["import { A2Error } from './errors.ts'\nimport type { AppendEvent, StoredEvent } from './store.ts'\n\nconst canonicalJson = (value: unknown): string =>\n  JSON.stringify(value, (_key, candidate: unknown) => {\n    if (\n      candidate === null ||\n      typeof candidate !== 'object' ||\n      Array.isArray(candidate)\n    ) {\n      return candidate\n    }\n    return Object.fromEntries(\n      Object.entries(candidate).toSorted(([left], [right]) =>\n        left < right ? -1 : left > right ? 1 : 0,\n      ),\n    )\n  }) ?? 'null'\n\nexport const idempotentReplay = (\n  events: readonly AppendEvent[],\n  existing: readonly StoredEvent[],\n): StoredEvent[] => {\n  const byId = new Map(existing.map((event) => [event.id, event]))\n  const ordered = events.map((event) =>\n    event.id === undefined ? undefined : byId.get(event.id),\n  )\n  const firstIndex = ordered[0]?.index\n  const batchSize = events[0]?.cause?.batchSize\n\n  if (\n    firstIndex === undefined ||\n    (batchSize !== undefined && batchSize !== events.length) ||\n    ordered.some((stored, index) => {\n      const event = events[index]!\n      return (\n        stored === undefined ||\n        stored.index !== firstIndex + index ||\n        stored.type !== event.type ||\n        stored.lane !== (event.lane ?? null) ||\n        stored.cause?.batchSize !== event.cause?.batchSize ||\n        canonicalJson(stored.payload) !== canonicalJson(event.payload)\n      )\n    })\n  ) {\n    throw new A2Error(\n      'PARTIAL_DUPLICATE_BATCH',\n      'already-appended events do not match the retried batch',\n    )\n  }\n\n  return ordered as StoredEvent[]\n}\n"],"mappings":";;AAGA,MAAM,iBAAiB,UACrB,KAAK,UAAU,QAAQ,MAAM,cAAuB;CAClD,IACE,cAAc,QACd,OAAO,cAAc,YACrB,MAAM,QAAQ,SAAS,GAEvB,OAAO;CAET,OAAO,OAAO,YACZ,OAAO,QAAQ,SAAS,CAAC,CAAC,UAAU,CAAC,OAAO,CAAC,WAC3C,OAAO,QAAQ,KAAK,OAAO,QAAQ,IAAI,CACzC,CACF;AACF,CAAC,KAAK;AAER,MAAa,oBACX,QACA,aACkB;CAClB,MAAM,OAAO,IAAI,IAAI,SAAS,KAAK,UAAU,CAAC,MAAM,IAAI,KAAK,CAAC,CAAC;CAC/D,MAAM,UAAU,OAAO,KAAK,UAC1B,MAAM,OAAO,KAAA,IAAY,KAAA,IAAY,KAAK,IAAI,MAAM,EAAE,CACxD;CACA,MAAM,aAAa,QAAQ,EAAE,EAAE;CAC/B,MAAM,YAAY,OAAO,EAAE,EAAE,OAAO;CAEpC,IACE,eAAe,KAAA,KACd,cAAc,KAAA,KAAa,cAAc,OAAO,UACjD,QAAQ,MAAM,QAAQ,UAAU;EAC9B,MAAM,QAAQ,OAAO;EACrB,OACE,WAAW,KAAA,KACX,OAAO,UAAU,aAAa,SAC9B,OAAO,SAAS,MAAM,QACtB,OAAO,UAAU,MAAM,QAAQ,SAC/B,OAAO,OAAO,cAAc,MAAM,OAAO,aACzC,cAAc,OAAO,OAAO,MAAM,cAAc,MAAM,OAAO;CAEjE,CAAC,GAED,MAAM,IAAI,QACR,2BACA,wDACF;CAGF,OAAO;AACT"}

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { a as EventDefs, c as Reducer, i as EventBatchFactory, l as ReducerBuilder, n as Contract, o as ReducerOptions, r as ContractEvent, s as contract, t as AppendInput, u as StandardSchemaV1 } from "./contract-C_3dIIEU.js";
-import { a as Event } from "./log-ldf5g8Cx.js";
-import { i as A2Telemetry, n as A2SpanHandle, r as A2SpanName, t as A2AttributeValue } from "./telemetry-Cso0qyHQ.js";
-import { n as A2ErrorCode, t as A2Error } from "./errors-xL_JTXsY.js";
-export { type A2AttributeValue, A2Error, type A2ErrorCode, type A2SpanHandle, type A2SpanName, type A2Telemetry, type AppendInput, type Contract, type ContractEvent, type Event, type EventBatchFactory, type EventDefs, type Reducer, type ReducerBuilder, type ReducerOptions, type StandardSchemaV1, contract };
+import { a as EventDefs, c as PresencePatch, f as contract, h as StandardSchemaV1, i as EventBatchFactory, l as PresenceSnapshot, m as ReducerBuilder, n as Contract, o as PresenceDefs, p as Reducer, r as ContractEvent, s as PresenceMap, t as AppendInput, u as ReducerOptions } from "./contract-jIfaR085.js";
+import { a as Event } from "./store-DysUkTH3.js";
+import { i as A2Telemetry, n as A2SpanHandle, r as A2SpanName, t as A2AttributeValue } from "./telemetry-BjYHTfh2.js";
+import { n as A2ErrorCode, t as A2Error } from "./errors-W6nwJ-fm.js";
+export { type A2AttributeValue, A2Error, type A2ErrorCode, type A2SpanHandle, type A2SpanName, type A2Telemetry, type AppendInput, type Contract, type ContractEvent, type Event, type EventBatchFactory, type EventDefs, type PresenceDefs, type PresenceMap, type PresencePatch, type PresenceSnapshot, type Reducer, type ReducerBuilder, type ReducerOptions, type StandardSchemaV1, contract };

package/dist/index.js

@@ -1,3 +1,3 @@
-import { t as contract } from "./contract-CG_adnu_.js";
-import { t as A2Error } from "./errors-BJRMd-h6.js";
+import { t as contract } from "./contract-48bUMgcL.js";
+import { t as A2Error } from "./errors-BQuJpe82.js";
 export { A2Error, contract };

package/dist/{inspection-E7qbD0Xj.js → inspection-DaxB5jM2.js}

@@ -1,4 +1,5 @@
 //#region src/inspection.ts
+var InspectionUnsupportedError = class extends Error {};
 const serverInspection = /* @__PURE__ */ new WeakMap();
 /** Owned live-inspection cadence; mutable only for white-box tests. */
 const DEVTOOLS_TIMINGS = {
@@ -7,4 +8,6 @@ const DEVTOOLS_TIMINGS = {
 	heartbeatMs: 15e3
 };
 //#endregion
-export { serverInspection as n, DEVTOOLS_TIMINGS as t };
+export { InspectionUnsupportedError as n, serverInspection as r, DEVTOOLS_TIMINGS as t };
+
+//# sourceMappingURL=inspection-DaxB5jM2.js.map

package/dist/inspection-DaxB5jM2.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inspection-DaxB5jM2.js","names":[],"sources":["../src/inspection.ts"],"sourcesContent":["/**\n * Private bridge between `createServer` and `experimental-a2/devtools/server`.\n * Servers keep their store closure private; the WeakMap grants A2's own\n * read-only devtools entry point access without adding public methods to\n * application server handles.\n */\n\nimport type { StoredEvent, StoredSessionPage, StoredSnapshot } from './store.ts'\n\nexport class InspectionUnsupportedError extends Error {}\n\nexport type ServerInspection = {\n  listSessions(options: {\n    cursor?: string\n    limit: number\n  }): Promise<StoredSessionPage>\n  readSessionPage(\n    sessionId: string,\n    options: { afterIndex: number; throughIndex?: number; limit: number },\n  ): Promise<{\n    events: StoredEvent[]\n    snapshots: StoredSnapshot[]\n    throughIndex: number\n    nextIndex: number | null\n  }>\n}\n\nexport const serverInspection: WeakMap<object, ServerInspection> = new WeakMap()\n\n/** Owned live-inspection cadence; mutable only for white-box tests. */\nexport const DEVTOOLS_TIMINGS: {\n  activeMs: number\n  idleMs: number\n  heartbeatMs: number\n} = {\n  activeMs: 250,\n  idleMs: 1_000,\n  heartbeatMs: 15_000,\n}\n"],"mappings":";AASA,IAAa,6BAAb,cAAgD,MAAM,CAAC;AAkBvD,MAAa,mCAAsD,IAAI,QAAQ;;AAG/E,MAAa,mBAIT;CACF,UAAU;CACV,QAAQ;CACR,aAAa;AACf"}

package/dist/internal-DstsI6Re.js

@@ -0,0 +1,211 @@
+//#region src/internal.ts
+/**
+* A null-prototype record for maps keyed by caller-controlled strings
+* (participant ids, presence field names). On a normal object,
+* assigning to '__proto__' rewrites the prototype instead of creating
+* an own property — the prototype-pollution class. Null-prototype
+* objects still satisfy Record types and JSON.stringify cleanly.
+*/
+function nullProtoRecord() {
+	return Object.create(null);
+}
+/**
+* ECMA-262's maximum Date value (±8.64e15 ms). A presence stamp past
+* it becomes an Invalid Date whose toISOString throws — one hostile
+* stamp would poison every subscriber's snapshot frame — so both
+* seams bound `at` to the representable range.
+*/
+const MAX_DATE_MS = 864e13;
+/**
+* Participant ids that collide with Object.prototype plumbing.
+* Null-prototype construction already defuses them, but they are
+* rejected at both seams (`parsePushBody`, `setPresence`) so a hostile
+* id never propagates into userland maps either.
+*/
+const RESERVED_PARTICIPANT_IDS = /* @__PURE__ */ new Set([
+	"__proto__",
+	"constructor",
+	"prototype"
+]);
+const serverInternals = /* @__PURE__ */ new WeakMap();
+/** Scheduler configuration captured only for servers made by `createServer`. */
+const serverSchedulerBindings = /* @__PURE__ */ new WeakMap();
+const objectLike = (value) => typeof value === "object" && value !== null || typeof value === "function";
+const TOOL_SCOPE_STORAGE = Symbol.for("experimental-a2.ai.tool-scope");
+function ambientToolScopeStorage() {
+	const value = Reflect.get(globalThis, TOOL_SCOPE_STORAGE);
+	if (!objectLike(value) || typeof Reflect.get(value, "getStore") !== "function" || typeof Reflect.get(value, "run") !== "function") return;
+	return value;
+}
+function installAmbientToolScopeStorage(create) {
+	const existing = ambientToolScopeStorage();
+	if (existing !== void 0) return existing;
+	const storage = create();
+	Reflect.set(globalThis, TOOL_SCOPE_STORAGE, storage);
+	return storage;
+}
+const SCHEDULER_SEND_FAILURE = Symbol.for("experimental-a2.scheduler.send-failure");
+const schedulerSendFailureMarker = (value) => {
+	if (!objectLike(value)) return void 0;
+	const marker = Reflect.get(value, SCHEDULER_SEND_FAILURE);
+	if (!objectLike(marker) || Reflect.get(marker, "version") !== 1 || !Array.isArray(Reflect.get(marker, "pending")) || !Array.isArray(Reflect.get(marker, "active"))) return;
+	return marker;
+};
+const schedulerFailureObject = (error) => {
+	if (objectLike(error) && (schedulerSendFailureMarker(error) !== void 0 || Object.isExtensible(error))) return error;
+	return new Error(String(error), { cause: error });
+};
+const schedulerSendFailureState = (error) => {
+	const existing = schedulerSendFailureMarker(error);
+	if (existing !== void 0) return existing;
+	const marker = {
+		version: 1,
+		pending: [],
+		active: []
+	};
+	Object.defineProperty(error, SCHEDULER_SEND_FAILURE, {
+		value: marker,
+		enumerable: false,
+		configurable: true,
+		writable: false
+	});
+	return marker;
+};
+const clearSchedulerSendFailureState = (error, marker) => {
+	if (marker.pending.length === 0 && marker.active.length === 0) Reflect.deleteProperty(error, SCHEDULER_SEND_FAILURE);
+};
+/**
+* Classify an adapter error before throwing it. Unclassified adapter failures
+* are retryable because the caller cannot know whether a remote send landed.
+*/
+function classifySchedulerSendFailure(error, disposition) {
+	const classified = schedulerFailureObject(error);
+	schedulerSendFailureState(classified).pending.push(disposition);
+	return classified;
+}
+/** Consume a pending adapter classification and count this rejected send. */
+function markSchedulerSendFailure(error) {
+	const marked = schedulerFailureObject(error);
+	const marker = schedulerSendFailureState(marked);
+	marker.active.push(marker.pending.pop() ?? "retryable");
+	return marked;
+}
+function consumeSchedulerSendFailure(error) {
+	if (!objectLike(error)) return void 0;
+	const marker = schedulerSendFailureMarker(error);
+	const disposition = marker?.active.pop();
+	if (marker !== void 0) clearSchedulerSendFailureState(error, marker);
+	return disposition;
+}
+const isDrainableServer = (value) => {
+	if (value === null || typeof value !== "object") return false;
+	const contract = Reflect.get(value, "contract");
+	return contract !== null && typeof contract === "object" && typeof Reflect.get(contract, "name") === "string" && typeof Reflect.get(value, "drain") === "function";
+};
+/**
+* Validate the server list captured by a scheduler route at construction time.
+* Built-in adapters keep their low-level target seam structural for custom
+* integrations. The application-facing `schedulerHandler` uses strict mode
+* so only servers made by this A2 copy reach a configured adapter.
+*/
+function assertSchedulerTargets(servers, options) {
+	const contracts = /* @__PURE__ */ new Set();
+	for (const target of servers) {
+		if (!isDrainableServer(target)) throw new TypeError("a2 scheduler: expected a server from createServer()");
+		const name = target.contract.name;
+		if (contracts.has(name)) throw new TypeError(`a2 scheduler: duplicate server contract '${name}' in one handler`);
+		contracts.add(name);
+		if (!serverSchedulerBindings.get(target)) {
+			if (!options.allowStructural) throw new TypeError(`a2 scheduler: server for contract '${name}' was not created by createServer()`);
+			continue;
+		}
+	}
+}
+/** Require every real server to share one exact configured scheduler. */
+function assertServerSchedulerBindings(scheduler, servers) {
+	for (const server of servers) {
+		const binding = serverSchedulerBindings.get(server);
+		if (!binding?.scheduler) throw new TypeError(`a2 scheduler: server for contract '${server.contract.name}' has no scheduler configured`);
+		if (binding.scheduler !== scheduler) throw new TypeError(`a2 scheduler: server for contract '${server.contract.name}' is configured with a different scheduler instance`);
+	}
+}
+/** Resolve the scheduler privately bound to a real A2 server. */
+function schedulerForServer(server) {
+	if (!isDrainableServer(server)) throw new TypeError("a2 scheduler: expected a server from createServer()");
+	const binding = serverSchedulerBindings.get(server);
+	if (!binding) throw new TypeError(`a2 scheduler: server for contract '${server.contract.name}' was not created by createServer()`);
+	if (!binding.scheduler) throw new TypeError(`a2 scheduler: server for contract '${server.contract.name}' has no scheduler configured`);
+	return binding.scheduler;
+}
+/**
+* Drain timing knobs. Mutable only as a white-box test seam. Claim
+* heartbeats run on real timers, so tests shrink these to keep suites
+* fast. Production always uses the defaults.
+*/
+const DRAIN_TIMINGS = {
+	claimTtlMs: 5e3,
+	claimHeartbeatMs: 2e3,
+	renewRetryMs: 400,
+	watchdogGraceMs: 1e3,
+	schedulerArmTimeoutMs: 2e3
+};
+/**
+* Stream liveness knobs — the server-side SSE heartbeat and the
+* client-side stall watchdog. Paired by design: the client declares a
+* connection dead after roughly two missed heartbeats. Mutable only as
+* a white-box test seam; production always uses the defaults.
+*/
+/**
+* Poll cadence for the poll-based store streams (sqlite, postgres) —
+* owned, not configurable: adaptive polling removed the operator's
+* reason to tune it (the floor keeps active streams smooth; the
+* ceiling bounds idle cost). Mutable only as a white-box test seam so
+* suites don't wait out real idle gaps.
+*/
+const POLL_TIMINGS = {
+	activeFloorMs: 25,
+	idleCeilingMs: 250
+};
+/**
+* Safety-read cadence for the notify-driven redis live stream. A
+* parked feed re-reads the store at this interval even without a
+* pub/sub wake-up, so a lost notification (subscriber reconnect gap,
+* dropped PUBLISH) costs latency, never an event. Mutable only as a
+* white-box test seam.
+*/
+const NOTIFY_TIMINGS = { safetyReadMs: 1e4 };
+const STREAM_TIMINGS = {
+	sseHeartbeatMs: 15e3,
+	sseDeadlineGraceMs: 1e3,
+	stallTimeoutMs: 35e3,
+	reconnectBaseMs: 500,
+	reconnectMaxMs: 5e3
+};
+/**
+* WebSocket down-pump backpressure — `sessionsSocket` parks its pull
+* loop while the socket reports more buffered bytes than the
+* high-water mark and re-checks on the poll cadence, so a slow reader
+* applies backpressure to the store subscription instead of buffering
+* without bound in the socket. Acks and heartbeats stay exempt: they
+* are small and correctness-relevant. Mutable only as a white-box test
+* seam.
+*/
+const SOCKET_TIMINGS = {
+	highWaterMarkBytes: 1048576,
+	resumePollMs: 25,
+	maxInFlightMessages: 32,
+	disconnectWaterMarkBytes: 8388608
+};
+/**
+* Client presence send cadence — a leading send immediately, then at
+* most one merged send per interval (~15Hz). Owned, not configurable
+* (decision #36's rule): coupling the cadence to the POST ack tied
+* remote cursor smoothness to RTT, and the ack serves no correctness
+* purpose on a fire-and-forget LWW plane. Mutable only as a white-box
+* test seam.
+*/
+const PRESENCE_TIMINGS = { sendIntervalMs: 66 };
+//#endregion
+export { schedulerForServer as _, PRESENCE_TIMINGS as a, STREAM_TIMINGS as c, assertServerSchedulerBindings as d, classifySchedulerSendFailure as f, nullProtoRecord as g, markSchedulerSendFailure as h, POLL_TIMINGS as i, ambientToolScopeStorage as l, installAmbientToolScopeStorage as m, MAX_DATE_MS as n, RESERVED_PARTICIPANT_IDS as o, consumeSchedulerSendFailure as p, NOTIFY_TIMINGS as r, SOCKET_TIMINGS as s, DRAIN_TIMINGS as t, assertSchedulerTargets as u, serverInternals as v, serverSchedulerBindings as y };
+
+//# sourceMappingURL=internal-DstsI6Re.js.map

package/dist/internal-DstsI6Re.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"internal-DstsI6Re.js","names":[],"sources":["../src/internal.ts"],"sourcesContent":["/**\n * Private seams shared by a2 entry points and a2's own tests. Not exported\n * from the package. Nothing here is public API.\n */\n\nimport type { ScheduledEvent } from './scheduler-task.ts'\nimport type { A2Scheduler, DrainableServer } from './server.ts'\n\nexport type DrainOutcome = 'busy' | 'stalled' | 'settled'\n\n/**\n * A null-prototype record for maps keyed by caller-controlled strings\n * (participant ids, presence field names). On a normal object,\n * assigning to '__proto__' rewrites the prototype instead of creating\n * an own property — the prototype-pollution class. Null-prototype\n * objects still satisfy Record types and JSON.stringify cleanly.\n */\nexport function nullProtoRecord<T extends object>(): T {\n  return Object.create(null) as T\n}\n\n/**\n * ECMA-262's maximum Date value (±8.64e15 ms). A presence stamp past\n * it becomes an Invalid Date whose toISOString throws — one hostile\n * stamp would poison every subscriber's snapshot frame — so both\n * seams bound `at` to the representable range.\n */\nexport const MAX_DATE_MS = 8_640_000_000_000_000\n\n/**\n * Participant ids that collide with Object.prototype plumbing.\n * Null-prototype construction already defuses them, but they are\n * rejected at both seams (`parsePushBody`, `setPresence`) so a hostile\n * id never propagates into userland maps either.\n */\nexport const RESERVED_PARTICIPANT_IDS: ReadonlySet<string> = new Set([\n  '__proto__',\n  'constructor',\n  'prototype',\n])\n\nexport type DrainResult = {\n  settled: boolean\n  outcome: DrainOutcome\n  /** Existing successor arm a scheduler callback may join before acking. */\n  schedulerArm?: Promise<void>\n}\n\nexport type ServerInternals = {\n  /**\n   * Await every in-flight background drain this machine has scheduled,\n   * including ones scheduled while waiting. Lets tests flush the\n   * fire-and-forget inline path deterministically — no sleeps.\n   */\n  settle(): Promise<void>\n  /** The public `server.drain()` result deliberately remains `{ settled }`. */\n  schedulerDrain(\n    sessionId: string,\n    opts?: { watchdogDueAt?: number },\n  ): Promise<DrainResult>\n  /** Deliver a scheduler-owned delayed append through the normal root path. */\n  schedulerAppend(\n    sessionId: string,\n    events: readonly ScheduledEvent[],\n  ): Promise<void>\n}\n\nexport const serverInternals: WeakMap<object, ServerInternals> = new WeakMap()\n\ntype ServerSchedulerBinding = {\n  scheduler: A2Scheduler | undefined\n}\n\n/** Scheduler configuration captured only for servers made by `createServer`. */\nexport const serverSchedulerBindings: WeakMap<object, ServerSchedulerBinding> =\n  new WeakMap()\n\nconst objectLike = (value: unknown): value is object =>\n  (typeof value === 'object' && value !== null) || typeof value === 'function'\n\n/** The ambient value delivered to `handlerContext` during a tool execution. */\nexport type AmbientToolScope = {\n  /** Executing server identity; a test scope from `runWithHandlerContext` has none. */\n  contract?: { readonly name: string }\n  context: unknown\n}\n\n/**\n * Structural AsyncLocalStorage surface for the ambient tool scope. The\n * instance is created by the server-only AI entry point (the only place\n * `node:async_hooks` may be imported) and shared through a global\n * symbol slot, so `handlerContext` in the isomorphic AI entry point and\n * independently bundled A2 copies all read the same scope.\n */\nexport type AmbientToolScopeStorage = {\n  getStore(): AmbientToolScope | undefined\n  run<R>(store: AmbientToolScope, callback: () => R): R\n}\n\nconst TOOL_SCOPE_STORAGE = Symbol.for('experimental-a2.ai.tool-scope')\n\nexport function ambientToolScopeStorage(): AmbientToolScopeStorage | undefined {\n  const value = Reflect.get(globalThis, TOOL_SCOPE_STORAGE)\n  if (\n    !objectLike(value) ||\n    typeof Reflect.get(value, 'getStore') !== 'function' ||\n    typeof Reflect.get(value, 'run') !== 'function'\n  ) {\n    return undefined\n  }\n  return value as AmbientToolScopeStorage\n}\n\nexport function installAmbientToolScopeStorage(\n  create: () => AmbientToolScopeStorage,\n): AmbientToolScopeStorage {\n  const existing = ambientToolScopeStorage()\n  if (existing !== undefined) return existing\n  const storage = create()\n  Reflect.set(globalThis, TOOL_SCOPE_STORAGE, storage)\n  return storage\n}\n\nexport type SchedulerSendFailureDisposition = 'retryable' | 'terminal'\n\ntype SchedulerSendFailureMarker = {\n  readonly version: 1\n  readonly pending: SchedulerSendFailureDisposition[]\n  readonly active: SchedulerSendFailureDisposition[]\n}\n\nconst SCHEDULER_SEND_FAILURE = Symbol.for(\n  'experimental-a2.scheduler.send-failure',\n)\n\nconst schedulerSendFailureMarker = (\n  value: unknown,\n): SchedulerSendFailureMarker | undefined => {\n  if (!objectLike(value)) return undefined\n  const marker = Reflect.get(value, SCHEDULER_SEND_FAILURE)\n  if (\n    !objectLike(marker) ||\n    Reflect.get(marker, 'version') !== 1 ||\n    !Array.isArray(Reflect.get(marker, 'pending')) ||\n    !Array.isArray(Reflect.get(marker, 'active'))\n  ) {\n    return undefined\n  }\n  return marker as SchedulerSendFailureMarker\n}\n\nconst schedulerFailureObject = (error: unknown): object => {\n  if (\n    objectLike(error) &&\n    (schedulerSendFailureMarker(error) !== undefined ||\n      Object.isExtensible(error))\n  ) {\n    return error\n  }\n  return new Error(String(error), { cause: error })\n}\n\nconst schedulerSendFailureState = (\n  error: object,\n): SchedulerSendFailureMarker => {\n  const existing = schedulerSendFailureMarker(error)\n  if (existing !== undefined) return existing\n  const marker: SchedulerSendFailureMarker = {\n    version: 1,\n    pending: [],\n    active: [],\n  }\n  Object.defineProperty(error, SCHEDULER_SEND_FAILURE, {\n    value: marker,\n    enumerable: false,\n    configurable: true,\n    writable: false,\n  })\n  return marker\n}\n\nconst clearSchedulerSendFailureState = (\n  error: object,\n  marker: SchedulerSendFailureMarker,\n): void => {\n  if (marker.pending.length === 0 && marker.active.length === 0) {\n    Reflect.deleteProperty(error, SCHEDULER_SEND_FAILURE)\n  }\n}\n\n/**\n * Classify an adapter error before throwing it. Unclassified adapter failures\n * are retryable because the caller cannot know whether a remote send landed.\n */\nexport function classifySchedulerSendFailure(\n  error: unknown,\n  disposition: SchedulerSendFailureDisposition,\n): unknown {\n  const classified = schedulerFailureObject(error)\n  schedulerSendFailureState(classified).pending.push(disposition)\n  return classified\n}\n\n/** Consume a pending adapter classification and count this rejected send. */\nexport function markSchedulerSendFailure(error: unknown): unknown {\n  const marked = schedulerFailureObject(error)\n  const marker = schedulerSendFailureState(marked)\n  marker.active.push(marker.pending.pop() ?? 'retryable')\n  return marked\n}\n\nexport function consumeSchedulerSendFailure(\n  error: unknown,\n): SchedulerSendFailureDisposition | undefined {\n  if (!objectLike(error)) return undefined\n  const marker = schedulerSendFailureMarker(error)\n  const disposition = marker?.active.pop()\n  if (marker !== undefined) clearSchedulerSendFailureState(error, marker)\n  return disposition\n}\n\nconst isDrainableServer = (value: unknown): value is DrainableServer => {\n  if (value === null || typeof value !== 'object') return false\n  const contract = Reflect.get(value, 'contract')\n  return (\n    contract !== null &&\n    typeof contract === 'object' &&\n    typeof Reflect.get(contract, 'name') === 'string' &&\n    typeof Reflect.get(value, 'drain') === 'function'\n  )\n}\n\n/**\n * Validate the server list captured by a scheduler route at construction time.\n * Built-in adapters keep their low-level target seam structural for custom\n * integrations. The application-facing `schedulerHandler` uses strict mode\n * so only servers made by this A2 copy reach a configured adapter.\n */\nexport function assertSchedulerTargets(\n  servers: readonly unknown[],\n  options: { allowStructural: boolean },\n): asserts servers is readonly DrainableServer[] {\n  const contracts = new Set<string>()\n  for (const target of servers) {\n    if (!isDrainableServer(target)) {\n      throw new TypeError('a2 scheduler: expected a server from createServer()')\n    }\n    const name = target.contract.name\n    if (contracts.has(name)) {\n      throw new TypeError(\n        `a2 scheduler: duplicate server contract '${name}' in one handler`,\n      )\n    }\n    contracts.add(name)\n\n    const binding = serverSchedulerBindings.get(target)\n    if (!binding) {\n      if (!options.allowStructural) {\n        throw new TypeError(\n          `a2 scheduler: server for contract '${name}' was not created by createServer()`,\n        )\n      }\n      continue\n    }\n  }\n}\n\n/** Require every real server to share one exact configured scheduler. */\nexport function assertServerSchedulerBindings(\n  scheduler: A2Scheduler,\n  servers: readonly DrainableServer[],\n): void {\n  for (const server of servers) {\n    const binding = serverSchedulerBindings.get(server)\n    if (!binding?.scheduler) {\n      throw new TypeError(\n        `a2 scheduler: server for contract '${server.contract.name}' has no scheduler configured`,\n      )\n    }\n    if (binding.scheduler !== scheduler) {\n      throw new TypeError(\n        `a2 scheduler: server for contract '${server.contract.name}' is configured with a different scheduler instance`,\n      )\n    }\n  }\n}\n\n/** Resolve the scheduler privately bound to a real A2 server. */\nexport function schedulerForServer(server: unknown): A2Scheduler {\n  if (!isDrainableServer(server)) {\n    throw new TypeError('a2 scheduler: expected a server from createServer()')\n  }\n  const binding = serverSchedulerBindings.get(server)\n  if (!binding) {\n    throw new TypeError(\n      `a2 scheduler: server for contract '${server.contract.name}' was not created by createServer()`,\n    )\n  }\n  if (!binding.scheduler) {\n    throw new TypeError(\n      `a2 scheduler: server for contract '${server.contract.name}' has no scheduler configured`,\n    )\n  }\n  return binding.scheduler\n}\n\n/**\n * Drain timing knobs. Mutable only as a white-box test seam. Claim\n * heartbeats run on real timers, so tests shrink these to keep suites\n * fast. Production always uses the defaults.\n */\nexport const DRAIN_TIMINGS: {\n  /** How long a claim lives without renewal. */\n  claimTtlMs: number\n  /** Heartbeat cadence while a handler is running. */\n  claimHeartbeatMs: number\n  /** Base delay before retrying a failed renewal while the lease lives. */\n  renewRetryMs: number\n  /** Delay between a claim's expiry and its scheduler watchdog. */\n  watchdogGraceMs: number\n  /** Maximum time a top-level append waits for its initial scheduler arm. */\n  schedulerArmTimeoutMs: number\n} = {\n  claimTtlMs: 5_000,\n  claimHeartbeatMs: 2_000,\n  renewRetryMs: 400,\n  watchdogGraceMs: 1_000,\n  schedulerArmTimeoutMs: 2_000,\n}\n\n/**\n * Stream liveness knobs — the server-side SSE heartbeat and the\n * client-side stall watchdog. Paired by design: the client declares a\n * connection dead after roughly two missed heartbeats. Mutable only as\n * a white-box test seam; production always uses the defaults.\n */\n/**\n * Poll cadence for the poll-based store streams (sqlite, postgres) —\n * owned, not configurable: adaptive polling removed the operator's\n * reason to tune it (the floor keeps active streams smooth; the\n * ceiling bounds idle cost). Mutable only as a white-box test seam so\n * suites don't wait out real idle gaps.\n */\nexport const POLL_TIMINGS: {\n  /** Gap between polls while a session is producing events. */\n  activeFloorMs: number\n  /** The idle ceiling — the longest gap between polls. */\n  idleCeilingMs: number\n} = {\n  activeFloorMs: 25,\n  idleCeilingMs: 250,\n}\n\n/**\n * Safety-read cadence for the notify-driven redis live stream. A\n * parked feed re-reads the store at this interval even without a\n * pub/sub wake-up, so a lost notification (subscriber reconnect gap,\n * dropped PUBLISH) costs latency, never an event. Mutable only as a\n * white-box test seam.\n */\nexport const NOTIFY_TIMINGS: {\n  safetyReadMs: number\n} = {\n  safetyReadMs: 10_000,\n}\n\nexport const STREAM_TIMINGS: {\n  /** Cadence of `: ping` comment frames from `sseResponse`. */\n  sseHeartbeatMs: number\n  /** How far ahead of an invocation deadline an SSE response closes. */\n  sseDeadlineGraceMs: number\n  /** Client: silence longer than this means the connection is dead. */\n  stallTimeoutMs: number\n  /** Client reconnect backoff: first retry delay, doubling per attempt. */\n  reconnectBaseMs: number\n  /** Client reconnect backoff ceiling. */\n  reconnectMaxMs: number\n} = {\n  sseHeartbeatMs: 15_000,\n  sseDeadlineGraceMs: 1_000,\n  stallTimeoutMs: 35_000,\n  reconnectBaseMs: 500,\n  reconnectMaxMs: 5_000,\n}\n\n/**\n * WebSocket down-pump backpressure — `sessionsSocket` parks its pull\n * loop while the socket reports more buffered bytes than the\n * high-water mark and re-checks on the poll cadence, so a slow reader\n * applies backpressure to the store subscription instead of buffering\n * without bound in the socket. Acks and heartbeats stay exempt: they\n * are small and correctness-relevant. Mutable only as a white-box test\n * seam.\n */\nexport const SOCKET_TIMINGS: {\n  highWaterMarkBytes: number\n  resumePollMs: number\n  /** Up-lane bound: concurrent push/presence handlers per socket. POST\n   * gets per-request platform limits for free; the socket must bring\n   * its own. Over the cap, pushes are answered with a retryable error\n   * ack and presence frames are shed (that plane repaints). */\n  maxInFlightMessages: number\n  /** Hard ceiling on `bufferedAmount`: past it the peer is a\n   * non-reader (acks and pings are park-exempt, so only a peer that\n   * never reads can reach it) and the socket closes 1008. */\n  disconnectWaterMarkBytes: number\n} = {\n  highWaterMarkBytes: 1_048_576,\n  resumePollMs: 25,\n  maxInFlightMessages: 32,\n  disconnectWaterMarkBytes: 8_388_608,\n}\n\n/**\n * Client presence send cadence — a leading send immediately, then at\n * most one merged send per interval (~15Hz). Owned, not configurable\n * (decision #36's rule): coupling the cadence to the POST ack tied\n * remote cursor smoothness to RTT, and the ack serves no correctness\n * purpose on a fire-and-forget LWW plane. Mutable only as a white-box\n * test seam.\n */\nexport const PRESENCE_TIMINGS: {\n  sendIntervalMs: number\n} = {\n  sendIntervalMs: 66,\n}\n"],"mappings":"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"}

package/dist/otel.d.ts

@@ -1,4 +1,4 @@
-import { i as A2Telemetry } from "./telemetry-Cso0qyHQ.js";
+import { i as A2Telemetry } from "./telemetry-BjYHTfh2.js";
 import { Tracer } from "@opentelemetry/api";
 //#region src/otel.d.ts
 type OtelOptions = {
@@ -9,4 +9,5 @@ type OtelOptions = {
 };
 declare function otel(options?: OtelOptions): A2Telemetry;
 //#endregion
-export { OtelOptions, otel };
+export { OtelOptions, otel };
+//# sourceMappingURL=otel.d.ts.map

package/dist/otel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"otel.d.ts","names":[],"sources":["../src/otel.ts"],"mappings":";;;KAiBY;;EAEV,SAAS;;EAET;;iBAac,KAAK,UAAS,cAAmB"}

package/dist/otel.js

@@ -39,3 +39,5 @@ function otel(options = {}) {
 }
 //#endregion
 export { otel };
+
+//# sourceMappingURL=otel.js.map

package/dist/otel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"otel.js","names":[],"sources":["../src/otel.ts"],"sourcesContent":["/**\n * experimental-a2/otel — OpenTelemetry adapter for the A2Telemetry interface.\n *\n * Peer-depends on `@opentelemetry/api` (optional). Spans nest through\n * the active context, so with a context manager registered (any real\n * OTel setup, e.g. `@vercel/otel`) the happy path lands in one trace:\n * request → a2.append → a2.drain → a2.event → the handler's own spans.\n */\n\nimport {\n  SpanStatusCode,\n  trace,\n  type Span,\n  type Tracer,\n} from '@opentelemetry/api'\nimport type { A2Telemetry } from './telemetry.ts'\n\nexport type OtelOptions = {\n  /** Bring your own tracer; defaults to `trace.getTracer(tracerName)`. */\n  tracer?: Tracer\n  /** Tracer name for the global provider. Default `'a2'`. */\n  tracerName?: string\n}\n\nconst fail = (span: Span, error: unknown): void => {\n  span.recordException(\n    error instanceof Error ? error : new Error(String(error)),\n  )\n  span.setStatus({\n    code: SpanStatusCode.ERROR,\n    message: error instanceof Error ? error.message : String(error),\n  })\n}\n\nexport function otel(options: OtelOptions = {}): A2Telemetry {\n  const tracer = options.tracer ?? trace.getTracer(options.tracerName ?? 'a2')\n\n  return {\n    span(name, attributes, fn) {\n      return tracer.startActiveSpan(name, { attributes }, async (span) => {\n        try {\n          return await fn({\n            setAttribute: (key, value) => {\n              span.setAttribute(key, value)\n            },\n            recordError: (error) => {\n              fail(span, error)\n            },\n          })\n        } catch (error) {\n          fail(span, error)\n          throw error\n        } finally {\n          span.end()\n        }\n      })\n    },\n  }\n}\n"],"mappings":";;;;;;;;;;AAwBA,MAAM,QAAQ,MAAY,UAAyB;CACjD,KAAK,gBACH,iBAAiB,QAAQ,QAAQ,IAAI,MAAM,OAAO,KAAK,CAAC,CAC1D;CACA,KAAK,UAAU;EACb,MAAM,eAAe;EACrB,SAAS,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK;CAChE,CAAC;AACH;AAEA,SAAgB,KAAK,UAAuB,CAAC,GAAgB;CAC3D,MAAM,SAAS,QAAQ,UAAU,MAAM,UAAU,QAAQ,cAAc,IAAI;CAE3E,OAAO,EACL,KAAK,MAAM,YAAY,IAAI;EACzB,OAAO,OAAO,gBAAgB,MAAM,EAAE,WAAW,GAAG,OAAO,SAAS;GAClE,IAAI;IACF,OAAO,MAAM,GAAG;KACd,eAAe,KAAK,UAAU;MAC5B,KAAK,aAAa,KAAK,KAAK;KAC9B;KACA,cAAc,UAAU;MACtB,KAAK,MAAM,KAAK;KAClB;IACF,CAAC;GACH,SAAS,OAAO;IACd,KAAK,MAAM,KAAK;IAChB,MAAM;GACR,UAAU;IACR,KAAK,IAAI;GACX;EACF,CAAC;CACH,EACF;AACF"}

package/dist/platform-B4TnJtWu.js

@@ -0,0 +1,34 @@
+//#region src/platform.ts
+const SYMBOL_FOR_REQ_CONTEXT = Symbol.for("@vercel/request-context");
+function requestContext() {
+	try {
+		return Reflect.get(globalThis, SYMBOL_FOR_REQ_CONTEXT)?.get?.() ?? {};
+	} catch {
+		return {};
+	}
+}
+/** The current invocation's Vercel deployment identity, when available. */
+function platformVercelOidcToken() {
+	try {
+		const token = requestContext().headers?.["x-vercel-oidc-token"];
+		return typeof token === "string" && token.length > 0 ? token : null;
+	} catch {
+		return null;
+	}
+}
+function platformWaitUntil(promise) {
+	try {
+		requestContext().waitUntil?.(promise);
+	} catch {}
+}
+/** The invocation's termination time in epoch ms, or null if unknowable. */
+function invocationDeadlineMs() {
+	const deadline = requestContext().deadline;
+	if (deadline === void 0 || deadline === null) return null;
+	const ms = new Date(deadline).getTime();
+	return Number.isNaN(ms) ? null : ms;
+}
+//#endregion
+export { platformVercelOidcToken as n, platformWaitUntil as r, invocationDeadlineMs as t };
+
+//# sourceMappingURL=platform-B4TnJtWu.js.map

package/dist/platform-B4TnJtWu.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"platform-B4TnJtWu.js","names":[],"sources":["../src/platform.ts"],"sourcesContent":["/**\n * Platform seams, read from the ambient request context — the same\n * channel `@vercel/functions` uses (`Symbol.for('@vercel/request-context')`)\n * — with no dependency on that package. Where no context exists (local\n * dev, long-lived servers, other clouds) everything degrades cleanly:\n * `waitUntil` becomes a no-op (background work is tracked in-process\n * anyway) and the deadline is unknown (claim watchdogs use their ordinary\n * TTL window).\n *\n * Tests exercise these paths by installing a real context object on the\n * symbol — simulating the platform contract, not mocking a2.\n */\n\ntype RequestContext = {\n  headers?: Readonly<Record<string, string>>\n  waitUntil?: (promise: Promise<unknown>) => void\n  /**\n   * When the platform will terminate this invocation (epoch ms, ISO\n   * string, or Date) — on Vercel this includes `waitUntil` work.\n   */\n  deadline?: number | string | Date\n}\n\nconst SYMBOL_FOR_REQ_CONTEXT = Symbol.for('@vercel/request-context')\n\nfunction requestContext(): RequestContext {\n  try {\n    const holder = Reflect.get(globalThis, SYMBOL_FOR_REQ_CONTEXT) as\n      { get?: () => RequestContext | undefined } | undefined\n    return holder?.get?.() ?? {}\n  } catch {\n    return {}\n  }\n}\n\n/** The current invocation's Vercel deployment identity, when available. */\nexport function platformVercelOidcToken(): string | null {\n  try {\n    const token = requestContext().headers?.['x-vercel-oidc-token']\n    return typeof token === 'string' && token.length > 0 ? token : null\n  } catch {\n    return null\n  }\n}\n\nexport function platformWaitUntil(promise: Promise<unknown>): void {\n  try {\n    requestContext().waitUntil?.(promise)\n  } catch {\n    // Best-effort — the promise is tracked in-process either way.\n  }\n}\n\n/** The invocation's termination time in epoch ms, or null if unknowable. */\nexport function invocationDeadlineMs(): number | null {\n  const deadline = requestContext().deadline\n  if (deadline === undefined || deadline === null) return null\n  const ms = new Date(deadline as number | string | Date).getTime()\n  return Number.isNaN(ms) ? null : ms\n}\n"],"mappings":";AAuBA,MAAM,yBAAyB,OAAO,IAAI,yBAAyB;AAEnE,SAAS,iBAAiC;CACxC,IAAI;EAGF,OAFe,QAAQ,IAAI,YAAY,sBAE3B,CAAC,EAAE,MAAM,KAAK,CAAC;CAC7B,QAAQ;EACN,OAAO,CAAC;CACV;AACF;;AAGA,SAAgB,0BAAyC;CACvD,IAAI;EACF,MAAM,QAAQ,eAAe,CAAC,CAAC,UAAU;EACzC,OAAO,OAAO,UAAU,YAAY,MAAM,SAAS,IAAI,QAAQ;CACjE,QAAQ;EACN,OAAO;CACT;AACF;AAEA,SAAgB,kBAAkB,SAAiC;CACjE,IAAI;EACF,eAAe,CAAC,CAAC,YAAY,OAAO;CACtC,QAAQ,CAER;AACF;;AAGA,SAAgB,uBAAsC;CACpD,MAAM,WAAW,eAAe,CAAC,CAAC;CAClC,IAAI,aAAa,KAAA,KAAa,aAAa,MAAM,OAAO;CACxD,MAAM,KAAK,IAAI,KAAK,QAAkC,CAAC,CAAC,QAAQ;CAChE,OAAO,OAAO,MAAM,EAAE,IAAI,OAAO;AACnC"}

package/dist/react.d.ts

@@ -1,5 +1,5 @@
-import { a as EventDefs, c as Reducer, r as ContractEvent, t as AppendInput } from "./contract-C_3dIIEU.js";
-import { A2Client, Connection, PushResult } from "./client.js";
+import { a as EventDefs, c as PresencePatch, d as WithPresence, o as PresenceDefs, p as Reducer, r as ContractEvent, s as PresenceMap, t as AppendInput } from "./contract-jIfaR085.js";
+import { a as Connection, c as HistoryState, l as LoadHistoryOptions, t as A2Client, u as PushResult } from "./client-D7mvIXrF.js";
 import { ReactElement, ReactNode } from "react";
 //#region src/react.d.ts
 type SessionProviderProps<D extends EventDefs, S> = {
@@ -13,13 +13,36 @@ type SessionProviderProps<D extends EventDefs, S> = {
   initialIndex: number;
   /** Server-rendered event history through `initialIndex`. */
   initialEvents?: ContractEvent<D>[];
+  /**
+   * This client's presence identity — required to call `setPresence`.
+   * Caller-supplied (a user id, a tab nonce, a guest name): A2 does
+   * not invent an identity story.
+   */
+  participant?: string;
   children?: ReactNode;
 };
 type BoundSessionProviderProps<D extends EventDefs, S> = Omit<SessionProviderProps<D, S>, "api">;
-type UseSessionResult<D extends EventDefs, S> = {
+/**
+ * The presence members of the hook result — intersected in via
+ * `WithPresence`, so they exist exactly when the contract declares
+ * presence fields (the reducer is the client's typed handle on it).
+ */
+type UseSessionPresence<P extends PresenceDefs> = {
+  /** The replicated presence map, this client included (local echo). */
+  presence: PresenceMap<P>;
+  /**
+   * Fire-and-forget: validated locally, echoed into the map
+   * immediately, coalesced on the wire to a fixed cadence (a leading
+   * send immediately, then at most one merged send per interval;
+   * later values win per field), stamped with the frontier at send
+   * time as `seen`. Requires the provider's `participant`.
+   */
+  setPresence: (values: PresencePatch<P>["values"]) => void;
+};
+type UseSessionResult<D extends EventDefs, S, P extends PresenceDefs = Record<never, never>> = WithPresence<P, UseSessionPresence<P>> & {
   /** The live view, folded through the shared reducer. */
   state: S;
-  /** The raw observed feed `state` is folded from. */
+  /** The raw event feed — observed, seeded, or backscrolled. */
   events: ContractEvent<D>[];
   /** The stream frontier — `lastSeenIndex` for cancellation. */
   index: number;
@@ -35,20 +58,29 @@ type UseSessionResult<D extends EventDefs, S> = {
    * back. Rejects with the server's A2Error codes.
    */
   push: (...events: AppendInput<D>[]) => PushResult<D>;
+  /**
+   * Backscroll: fetch a bounded slice of older events into `events`.
+   * Defaults page backward 50 at a time from the oldest loaded event.
+   * Display data only — `state` and the optimistic overlay never move.
+   */
+  loadHistory: (options?: LoadHistoryOptions) => Promise<ContractEvent<D>[]>;
+  /** Backscroll progress: `complete` means the feed reaches index 1. */
+  history: HistoryState;
 };
-type A2React<D extends EventDefs, S> = {
+type A2React<D extends EventDefs, S, P extends PresenceDefs = Record<never, never>> = {
   SessionProvider: (props: SessionProviderProps<D, S>) => ReactElement;
-  useSession: () => UseSessionResult<D, S>;
+  useSession: () => UseSessionResult<D, S, P>;
 };
-type BoundA2React<D extends EventDefs, S> = {
+type BoundA2React<D extends EventDefs, S, P extends PresenceDefs = Record<never, never>> = {
   SessionProvider: (props: BoundSessionProviderProps<D, S>) => ReactElement;
-  useSession: () => UseSessionResult<D, S>;
+  useSession: () => UseSessionResult<D, S, P>;
 };
-declare function createReact<D extends EventDefs, S>(options: {
-  client: A2Client<D, S>;
-}): BoundA2React<D, S>;
-declare function createReact<D extends EventDefs, S>(options: {
-  reducer: Reducer<D, S>;
-}): A2React<D, S>;
+declare function createReact<D extends EventDefs, S, P extends PresenceDefs = Record<never, never>>(options: {
+  client: A2Client<D, S, P>;
+}): BoundA2React<D, S, P>;
+declare function createReact<D extends EventDefs, S, P extends PresenceDefs = Record<never, never>>(options: {
+  reducer: Reducer<D, S, P>;
+}): A2React<D, S, P>;
 //#endregion
-export { A2React, BoundA2React, BoundSessionProviderProps, SessionProviderProps, UseSessionResult, createReact };
+export { A2React, BoundA2React, BoundSessionProviderProps, SessionProviderProps, UseSessionPresence, UseSessionResult, createReact };
+//# sourceMappingURL=react.d.ts.map