experimental-a2 0.16.0 → 0.17.0

package/dist/wire-DjfHOvdW.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wire-DjfHOvdW.js","names":[],"sources":["../src/wire.ts"],"sourcesContent":["/**\n * The wire format shared by server.fetch and experimental-a2/client\n * (browser side): events as JSON with ISO timestamps, and the A2Error\n * envelope. Internal module — both entry points re-export what's\n * public.\n */\n\nimport { A2Error, type A2ErrorCode, type A2ServerErrorCode } from './errors.ts'\nimport { nullProtoRecord } from './internal.ts'\nimport type { Event } from './store.ts'\nimport {\n  isSerializedEvent,\n  takeBuffered,\n  type HeldEvent,\n  type SerializedEvent,\n} from './stream-buffer.ts'\nimport type {\n  PresenceMap,\n  PresencePatch,\n  PresenceSnapshot,\n} from './contract.ts'\n\nexport type WireEvent = {\n  id: string\n  type: string\n  payload: unknown\n  index: number\n  sessionId: string\n  /** ISO 8601 — revived to a Date on the client so reducers see the\n   * same shape on both sides of the wire. */\n  createdAt: string\n}\n\nexport function eventToWire(event: Event): WireEvent {\n  return {\n    id: event.id,\n    type: event.type,\n    payload: event.payload,\n    index: event.index,\n    sessionId: event.sessionId,\n    createdAt: event.createdAt.toISOString(),\n  }\n}\n\n// Consecutive frames usually repeat a stream's session, an event type, and\n// the timestamp of events appended together; each keeps its last encoding.\nconst lastEncoding = <T>(encode: (value: T) => string) => {\n  let last: T | undefined\n  let text = ''\n  return (value: T): string => {\n    if (value !== last) {\n      text = encode(value)\n      last = value\n    }\n    return text\n  }\n}\nconst isoJson = lastEncoding((ms: number) =>\n  JSON.stringify(new Date(ms).toISOString()),\n)\nconst sessionJson = lastEncoding((id: string) => JSON.stringify(id))\nconst typeJson = lastEncoding((type: string) => JSON.stringify(type))\n\n/**\n * `JSON.stringify(eventToWire(event))` for the parsed event, built around the\n * stored payload text instead of parsing and re-serializing it.\n */\nexport function serializedEventToWireJson(event: SerializedEvent): string {\n  return `{\"id\":${JSON.stringify(event.id)},\"type\":${typeJson(event.type)},\"payload\":${event.payloadJson},\"index\":${event.index},\"sessionId\":${sessionJson(event.sessionId)},\"createdAt\":${isoJson(event.createdAtMs)}}`\n}\n\n/**\n * Wire version 2: what a client opts into with `wire=2` on the stream URL.\n * Live events travel in batches, without the `sessionId` the connection\n * already names, with `createdAt` as epoch milliseconds. Any other value,\n * or none, selects version 1.\n */\nexport type WireVersion = 1 | 2\n\nexport function wireVersion(value: string | null): WireVersion {\n  return value === '2' ? 2 : 1\n}\n\n/**\n * Events already held by a stream join one write while it is shorter than\n * this many characters, so a write can exceed it by the event that crosses it.\n */\nexport const EVENT_WRITE_CHARS: number = 64 * 1024\n\n/** Stream items that are events, as opposed to snapshot or presence frames. */\nexport function isStreamEvent(item: object): item is HeldEvent {\n  return !('kind' in item) && !('snapshot' in item) && !('participant' in item)\n}\n\n/**\n * `first` and the events `iterator` already holds, encoded, until the batch\n * reaches `EVENT_WRITE_CHARS`; `last` is the batch's final event.\n */\nexport function heldEventBatch(options: {\n  first: HeldEvent\n  iterator: object\n  encode: (event: HeldEvent) => string\n}): { events: string[]; last: HeldEvent } {\n  const { iterator, encode } = options\n  let last = options.first\n  const events = [encode(last)]\n  let chars = events[0]!.length\n  while (chars < EVENT_WRITE_CHARS) {\n    const held = takeBuffered(iterator)\n    if (!held) break\n    const json = encode(held)\n    events.push(json)\n    chars += json.length + 1\n    last = held\n  }\n  return { events, last }\n}\n\n/** A version 2 live event: `WireEvent` minus `sessionId`, ms timestamp. */\nexport type CompactWireEvent = {\n  id: string\n  type: string\n  payload: unknown\n  index: number\n  createdAt: number\n}\n\n/** One version 2 event as JSON, splicing a held row's stored payload. */\nexport function compactEventJson(event: HeldEvent): string {\n  if (!isSerializedEvent(event))\n    return JSON.stringify({\n      id: event.id,\n      type: event.type,\n      payload: event.payload,\n      index: event.index,\n      createdAt: event.createdAt.getTime(),\n    })\n  return `{\"id\":${JSON.stringify(event.id)},\"type\":${typeJson(event.type)},\"payload\":${event.payloadJson},\"index\":${event.index},\"createdAt\":${event.createdAtMs}}`\n}\n\nexport function isCompactWireEvent(value: unknown): value is CompactWireEvent {\n  if (value === null || typeof value !== 'object') return false\n  const v = value as Record<string, unknown>\n  return (\n    typeof v['id'] === 'string' &&\n    typeof v['type'] === 'string' &&\n    typeof v['index'] === 'number' &&\n    typeof v['createdAt'] === 'number' &&\n    Number.isFinite(v['createdAt'])\n  )\n}\n\nexport function eventFromCompactWire(\n  wire: CompactWireEvent,\n  sessionId: string,\n): Event {\n  return {\n    id: wire.id,\n    type: wire.type,\n    payload: wire.payload,\n    index: wire.index,\n    sessionId,\n    createdAt: new Date(wire.createdAt),\n  }\n}\n\nexport function eventFromWire(wire: WireEvent): Event {\n  return {\n    id: wire.id,\n    type: wire.type,\n    payload: wire.payload,\n    index: wire.index,\n    sessionId: wire.sessionId,\n    createdAt: new Date(wire.createdAt),\n  }\n}\n\nexport function isWireEvent(value: unknown): value is WireEvent {\n  if (value === null || typeof value !== 'object') return false\n  const v = value as Record<string, unknown>\n  return (\n    typeof v['id'] === 'string' &&\n    typeof v['type'] === 'string' &&\n    typeof v['index'] === 'number' &&\n    typeof v['sessionId'] === 'string' &&\n    typeof v['createdAt'] === 'string'\n  )\n}\n\n// ── the presence wire pair ───────────────────────────────────────────\n\n/** The `event: presence` SSE frame body: one patch as JSON. */\nexport type WirePresencePatch = {\n  participant: string\n  values: Record<string, unknown>\n  seen: number\n  /** ISO 8601 — revived to a Date on the client. */\n  at: string\n}\n\n/**\n * The `event: presence-snapshot` SSE frame body: the in-memory\n * `PresenceSnapshot` shape verbatim, with each per-field `at`\n * serialized to ISO 8601.\n */\nexport type WirePresenceSnapshot = {\n  snapshot: {\n    [participant: string]: {\n      [field: string]: { value: unknown; seen: number; at: string }\n    }\n  }\n}\n\nexport function presencePatchToWire(patch: PresencePatch): WirePresencePatch {\n  return {\n    participant: patch.participant,\n    values: patch.values,\n    seen: patch.seen,\n    at: patch.at.toISOString(),\n  }\n}\n\nexport function presencePatchFromWire(wire: WirePresencePatch): PresencePatch {\n  return {\n    participant: wire.participant,\n    values: wire.values,\n    seen: wire.seen,\n    at: new Date(wire.at),\n  }\n}\n\n// Participant and field keys come off the wire, so every object keyed\n// by them is built null-prototype — see `nullProtoRecord`.\nexport function presenceSnapshotToWire(\n  snapshot: PresenceSnapshot,\n): WirePresenceSnapshot {\n  const wire: WirePresenceSnapshot['snapshot'] = nullProtoRecord()\n  for (const [participant, fields] of Object.entries(snapshot.snapshot)) {\n    const wireFields: WirePresenceSnapshot['snapshot'][string] =\n      nullProtoRecord()\n    for (const [field, entry] of Object.entries(fields)) {\n      if (entry === undefined) continue\n      wireFields[field] = {\n        value: entry.value,\n        seen: entry.seen,\n        at: entry.at.toISOString(),\n      }\n    }\n    wire[participant] = wireFields\n  }\n  return { snapshot: wire }\n}\n\nexport function presenceSnapshotFromWire(\n  wire: WirePresenceSnapshot,\n): PresenceSnapshot {\n  const map: PresenceMap = nullProtoRecord()\n  for (const [participant, fields] of Object.entries(wire.snapshot)) {\n    const revived: PresenceMap[string] = nullProtoRecord()\n    for (const [field, entry] of Object.entries(fields)) {\n      revived[field] = {\n        value: entry.value,\n        seen: entry.seen,\n        at: new Date(entry.at),\n      }\n    }\n    map[participant] = revived\n  }\n  return { snapshot: map }\n}\n\nexport function isWirePresencePatch(\n  value: unknown,\n): value is WirePresencePatch {\n  if (value === null || typeof value !== 'object') return false\n  const v = value as Record<string, unknown>\n  return (\n    typeof v['participant'] === 'string' &&\n    v['values'] !== null &&\n    typeof v['values'] === 'object' &&\n    !Array.isArray(v['values']) &&\n    typeof v['seen'] === 'number' &&\n    typeof v['at'] === 'string'\n  )\n}\n\nexport function isWirePresenceSnapshot(\n  value: unknown,\n): value is WirePresenceSnapshot {\n  if (value === null || typeof value !== 'object') return false\n  const v = value as Record<string, unknown>\n  return (\n    v['snapshot'] !== null &&\n    typeof v['snapshot'] === 'object' &&\n    !Array.isArray(v['snapshot'])\n  )\n}\n\n// ── the A2Error envelope ─────────────────────────────────────────────\n\nexport type WireError = {\n  error: { code: A2ServerErrorCode; message: string; details?: unknown }\n}\n\nconst ERROR_STATUS: Record<A2ServerErrorCode, number> = {\n  INVALID_PAYLOAD: 400,\n  FORBIDDEN: 403,\n  UNKNOWN_EVENT_TYPE: 400,\n  PARTIAL_DUPLICATE_BATCH: 400,\n  SUPERSEDED_ATTEMPT: 409,\n  SESSION_CLEARED: 409,\n  CLAIM_EXPIRED: 409,\n  STORE_UNAVAILABLE: 503,\n  STORE_NOT_CONFIGURED: 500,\n  UNKNOWN_PRESENCE_FIELD: 400,\n  PRESENCE_NOT_SUPPORTED: 500,\n}\n\nexport function errorStatus(code: A2ErrorCode): number {\n  return ERROR_STATUS[isServerErrorCode(code) ? code : 'STORE_UNAVAILABLE']\n}\n\nexport function errorToWire(error: A2Error): WireError {\n  const failure = asA2Error(error)\n  const body: WireError = {\n    error: {\n      code: failure.code as A2ServerErrorCode,\n      message: failure.message,\n    },\n  }\n  if (failure.details !== undefined) body.error.details = failure.details\n  return body\n}\n\n/** Wrap an arbitrary thrown value for the wire: known server codes pass through,\n * anything else becomes STORE_UNAVAILABLE — from the client's\n * perspective an unknown server failure is retryable-once, not a\n * protocol contract. */\nexport function asA2Error(error: unknown): A2Error {\n  return error instanceof A2Error && isServerErrorCode(error.code)\n    ? error\n    : new A2Error('STORE_UNAVAILABLE', 'internal error', { cause: error })\n}\n\n/** Rebuild an A2Error from a wire body; null if the body isn't one. */\nexport function errorFromWire(body: unknown): A2Error | null {\n  if (body === null || typeof body !== 'object') return null\n  const err = (body as { error?: unknown }).error\n  if (err === null || typeof err !== 'object') return null\n  const { code, message, details } = err as Record<string, unknown>\n  if (typeof code !== 'string' || !isServerErrorCode(code)) return null\n  return new A2Error(code, String(message ?? code), {\n    details,\n  })\n}\n\nconst isServerErrorCode = (code: string): code is A2ServerErrorCode =>\n  Object.hasOwn(ERROR_STATUS, code)\n\n// ── the ws frame layer ───────────────────────────────────────────────\n// The SSE lanes reframed for a socket (specs/a2-api.md §13): every\n// message is one JSON text frame, and a frame is its wire payload plus\n// a `kind` discriminant (plus `req` where a reply must correlate).\n// Unknown kinds are skipped by both sides — the same\n// forward-compatibility rule as named SSE frames.\n//\n// The multiplexed superset rides the same frames: `subscribe` /\n// `unsubscribe` up-frames open and close per-session lanes on one\n// socket, `sessionId` tags route everything else. Single-session\n// frames (no tags) keep parsing unchanged — a route opts into\n// multiplexing by choosing the multi-session server handler, never by\n// breaking the old protocol.\n\n/**\n * Server → client, parsed: a live-stream item, a push ack, a\n * subscription lifecycle notice, or the heartbeat. `parseSocketFrame`\n * yields these; frames of unknown kind (or ones failing their shape\n * guard) come back `null`. `sessionId` is present on frames from a\n * multiplexed socket and absent on a single-session one.\n */\nexport type StateSnapshotFrame = {\n  kind: 'snapshot'\n  sessionId: string\n  name: string\n  index: number\n  state: unknown\n  stateUndefined?: true\n  /** The session's latest clear marker, when it has been cleared. */\n  clearIndex?: number\n}\n\nexport function stateSnapshotToWire(\n  frame: StateSnapshotFrame,\n): StateSnapshotFrame {\n  return frame.state === undefined\n    ? { ...frame, state: null, stateUndefined: true }\n    : frame\n}\n\nexport function isStateSnapshotFrame(\n  value: unknown,\n): value is StateSnapshotFrame {\n  if (value === null || typeof value !== 'object') return false\n  const frame = value as Record<string, unknown>\n  return (\n    frame['kind'] === 'snapshot' &&\n    typeof frame['sessionId'] === 'string' &&\n    typeof frame['name'] === 'string' &&\n    frame['name'].length > 0 &&\n    typeof frame['index'] === 'number' &&\n    Number.isSafeInteger(frame['index']) &&\n    frame['index'] >= 0 &&\n    Object.hasOwn(frame, 'state') &&\n    (!Object.hasOwn(frame, 'stateUndefined') ||\n      (frame['stateUndefined'] === true && frame['state'] === null)) &&\n    (!Object.hasOwn(frame, 'clearIndex') ||\n      (typeof frame['clearIndex'] === 'number' &&\n        Number.isSafeInteger(frame['clearIndex']) &&\n        frame['clearIndex'] > 0 &&\n        frame['clearIndex'] <= frame['index']))\n  )\n}\n\nexport type SubscriptionStart =\n  | { index: number; bootstrap?: never; reducer?: string }\n  | { bootstrap: true; reducer: string; index?: never }\n\nexport type SocketDownFrame =\n  | StateSnapshotFrame\n  | { kind: 'event'; event: WireEvent }\n  | { kind: 'events'; events: CompactWireEvent[]; sessionId?: string }\n  | { kind: 'presence'; patch: WirePresencePatch; sessionId?: string }\n  | {\n      kind: 'presence-snapshot'\n      snapshot: WirePresenceSnapshot\n      sessionId?: string\n    }\n  | { kind: 'ack'; req: number; events: WireEvent[]; sessionId?: string }\n  | { kind: 'ack'; req: number; error: A2Error; sessionId?: string }\n  | { kind: 'subscribed'; sessionId: string; attempt?: number }\n  | {\n      kind: 'unsubscribed'\n      sessionId: string\n      attempt?: number\n      reason?: string\n      error?: A2Error\n    }\n  | { kind: 'ping' }\n\n/**\n * Client → server: the push envelope's two planes. `sessionId` is\n * implied by the socket on a single-session connection and required by\n * the multiplexed handler. Plain JSON on the wire; the server parses\n * and validates them through the same seams as `parsePushBody`.\n */\nexport type SocketPushFrame = {\n  kind: 'push'\n  /** Client-local ack correlator — opaque to the server. */\n  req: number\n  events: Array<{ type: string; payload: unknown; id?: string }>\n  sessionId?: string\n}\n\nexport type SocketPresenceFrame = {\n  kind: 'presence'\n  participant: string\n  values: Record<string, unknown>\n  seen?: number\n  at?: number\n  sessionId?: string\n}\n\n/** One session lane in a subscribe frame. The server echoes `attempt`\n * on that lane's `subscribed`/`unsubscribed` answers, so a client that\n * re-subscribed before an answer arrived can tell the answers apart. */\nexport type SocketSubscribeEntry = {\n  id: string\n  attempt?: number\n} & SubscriptionStart\n\n/** Open per-session lanes on a multiplexed socket. `index` is each\n * session's exclusive resume frontier — `stream({ startAfter })`. */\nexport type SocketSubscribeFrame = {\n  kind: 'subscribe'\n  sessions: SocketSubscribeEntry[]\n}\n\nexport type SocketUnsubscribeFrame = {\n  kind: 'unsubscribe'\n  sessions: string[]\n}\n\nexport type SocketUpFrame =\n  | SocketPushFrame\n  | SocketPresenceFrame\n  | SocketSubscribeFrame\n  | SocketUnsubscribeFrame\n\nexport const SOCKET_PING_FRAME: string = JSON.stringify({ kind: 'ping' })\n\n/** One stream item as a socket frame — `sseResponse`'s framing over\n * the same codecs, with `kind` instead of an SSE event name. On a\n * multiplexed socket presence frames carry the `sessionId` tag; events\n * already carry theirs in the wire event. */\nexport function socketFrameFor(\n  item: Event | PresencePatch | PresenceSnapshot | StateSnapshotFrame,\n  sessionId?: string,\n): string {\n  const tag = sessionId === undefined ? {} : { sessionId }\n  if ('kind' in item) return JSON.stringify(stateSnapshotToWire(item))\n  if ('snapshot' in item) {\n    return JSON.stringify({\n      kind: 'presence-snapshot',\n      ...presenceSnapshotToWire(item),\n      ...tag,\n    })\n  }\n  if ('participant' in item) {\n    return JSON.stringify({\n      kind: 'presence',\n      ...presencePatchToWire(item),\n      ...tag,\n    })\n  }\n  return JSON.stringify({ kind: 'event', ...eventToWire(item) })\n}\n\n/** A version 2 batch frame from compact event JSON; a multiplexed\n * socket names the batch's session once. */\nexport function socketEventsFor(events: string[], sessionId?: string): string {\n  const tag =\n    sessionId === undefined ? '' : `\"sessionId\":${JSON.stringify(sessionId)},`\n  return `{\"kind\":\"events\",${tag}\"events\":[${events.join(',')}]}`\n}\n\nexport function socketAckFor(\n  req: number,\n  events: Event[],\n  sessionId?: string,\n): string {\n  return JSON.stringify({\n    kind: 'ack',\n    req,\n    events: events.map(eventToWire),\n    ...(sessionId === undefined ? {} : { sessionId }),\n  })\n}\n\nexport function socketErrorAckFor(\n  req: number,\n  error: A2Error,\n  sessionId?: string,\n): string {\n  return JSON.stringify({\n    kind: 'ack',\n    req,\n    ...errorToWire(error),\n    ...(sessionId === undefined ? {} : { sessionId }),\n  })\n}\n\nexport function socketSubscribedFor(options: {\n  sessionId: string\n  attempt?: number | undefined\n}): string {\n  const { sessionId, attempt } = options\n  return JSON.stringify({\n    kind: 'subscribed',\n    sessionId,\n    ...(attempt === undefined ? {} : { attempt }),\n  })\n}\n\n/** The subscription-over notice: with a `reason` the server rejected\n * or lost the session's stream, without one it ended cleanly. */\nexport function socketUnsubscribedFor(options: {\n  sessionId: string\n  attempt?: number | undefined\n  reason?: string\n  error?: A2Error\n}): string {\n  const { sessionId, attempt, reason, error } = options\n  return JSON.stringify({\n    kind: 'unsubscribed',\n    sessionId,\n    ...(attempt === undefined ? {} : { attempt }),\n    ...(reason === undefined ? {} : { reason }),\n    ...(error === undefined ? {} : errorToWire(error)),\n  })\n}\n\nconst isAttempt = (value: unknown): value is number =>\n  typeof value === 'number' && Number.isSafeInteger(value) && value >= 0\n\nexport function parseSocketFrame(data: string): SocketDownFrame | null {\n  let parsed: unknown\n  try {\n    parsed = JSON.parse(data)\n  } catch {\n    return null\n  }\n  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {\n    return null\n  }\n  const frame = parsed as Record<string, unknown>\n  switch (frame['kind']) {\n    case 'snapshot':\n      if (!isStateSnapshotFrame(parsed))\n        throw new A2Error('INVALID_PAYLOAD', 'invalid bootstrap snapshot')\n      return parsed\n    case 'ping':\n      return { kind: 'ping' }\n    case 'event': {\n      if (!isWireEvent(parsed)) return null\n      const { id, type, payload, index, sessionId, createdAt } = parsed\n      return {\n        kind: 'event',\n        event: { id, type, payload, index, sessionId, createdAt },\n      }\n    }\n    case 'events': {\n      // Dropping a batch would leave a gap the frontier then skips past.\n      const events = frame['events']\n      if (!Array.isArray(events) || !events.every(isCompactWireEvent))\n        throw new A2Error('INVALID_PAYLOAD', 'invalid event batch')\n      return { kind: 'events', events, ...sessionTag(frame) }\n    }\n    case 'presence': {\n      if (!isWirePresencePatch(parsed)) return null\n      const { participant, values, seen, at } = parsed\n      return {\n        kind: 'presence',\n        patch: { participant, values, seen, at },\n        ...sessionTag(frame),\n      }\n    }\n    case 'presence-snapshot': {\n      if (!isWirePresenceSnapshot(parsed)) return null\n      return {\n        kind: 'presence-snapshot',\n        snapshot: { snapshot: parsed.snapshot },\n        ...sessionTag(frame),\n      }\n    }\n    case 'subscribed': {\n      const { sessionId, attempt } = frame\n      if (typeof sessionId !== 'string') return null\n      if (attempt !== undefined && !isAttempt(attempt)) return null\n      return {\n        kind: 'subscribed',\n        sessionId,\n        ...(attempt === undefined ? {} : { attempt }),\n      }\n    }\n    case 'unsubscribed': {\n      const { sessionId, attempt } = frame\n      if (typeof sessionId !== 'string') return null\n      if (attempt !== undefined && !isAttempt(attempt)) return null\n      const reason = frame['reason']\n      const error =\n        errorFromWire(parsed) ??\n        ('error' in frame\n          ? new A2Error(\n              'STORE_UNAVAILABLE',\n              'unintelligible subscription error',\n            )\n          : null)\n      return {\n        kind: 'unsubscribed',\n        sessionId,\n        ...(attempt === undefined ? {} : { attempt }),\n        ...(typeof reason === 'string' ? { reason } : {}),\n        ...(error === null ? {} : { error }),\n      }\n    }\n    case 'ack': {\n      const req = frame['req']\n      if (typeof req !== 'number') return null\n      const tag = sessionTag(frame)\n      const events = frame['events']\n      if (Array.isArray(events) && events.every(isWireEvent)) {\n        return { kind: 'ack', req, events, ...tag }\n      }\n      const error = errorFromWire(parsed)\n      if (error) return { kind: 'ack', req, error, ...tag }\n      // A correlatable ack must never be dropped: its waiter would hang\n      // forever behind a healthy socket (pings keep the watchdog fed).\n      // An outcome this client cannot interpret — an error code from a\n      // newer server, an event shape that fails a guard — degrades to\n      // a lost ack: retryable, and the client-generated ids make the\n      // retry idempotent even if the append actually committed.\n      return {\n        kind: 'ack',\n        req,\n        error: new A2Error('STORE_UNAVAILABLE', 'unintelligible ack'),\n        ...tag,\n      }\n    }\n    default:\n      return null\n  }\n}\n\nconst sessionTag = (frame: Record<string, unknown>): { sessionId?: string } => {\n  const sessionId = frame['sessionId']\n  return typeof sessionId === 'string' ? { sessionId } : {}\n}\n"],"mappings":"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"}

package/docs/01-quickstart.mdx

@@ -160,10 +160,10 @@ Raw session history is truth, but UIs usually want a view. Define a reducer
 once:
 
 ```ts reducer.ts
+import { reducer } from 'experimental-a2'
 import { orders } from '@/server/orders'
 
-export const ordersReducer = orders
-  .reducer({ name: 'order-status', initialState: { status: 'new' } })
+export const ordersReducer = reducer({ contract: orders, name: 'order-status', initialState: { status: 'new' }  })
   .fold((state, event) => {
     switch (event.type) {
       case 'created':

package/docs/actors/01-introduction.mdx

@@ -123,6 +123,10 @@ Three kinds of failure, three behaviors:
   is the message id, stable across re-runs: use it as the idempotency
   key for external I/O.
 
+A call cleared by `handle.session.clear()` before it receives its answer
+rejects with an `A2Error` whose code is `SESSION_CLEARED`. The handler may
+already have run. Over HTTP it's a `410`; see [Routes](/actors/routes).
+
 ## Send, don't wait
 
 `send` validates, appends the event durably, and returns without

package/docs/actors/04-routes.mdx

@@ -88,6 +88,19 @@ stream. It passes through `authorize` as `{ type: 'state', id }` and uses
 the same `view` projection as streams and call answers. Snapshot and call
 responses use `Cache-Control: private, no-store`.
 
+After `handle.session.clear()`, snapshots, call answers, and the state
+commits in the stream include `clearIndex`. Keep it when you pass a snapshot to `useActor`'s `initial`
+prop; the hook also picks it up from calls and refreshes. The stream sends the
+actor's initial state through `view` as a reset, and the hook drops older
+history. A delayed reset never replaces a newer snapshot.
+
+A call cleared before it receives its answer gets `410` with
+`{ code: 'SESSION_CLEARED', error }`. The handler may already have run, so
+treat its external effects as unknown, as after a timeout. The actor client
+raises it as an `ActorRequestError` with status `410` and the A2 error as
+its `cause`. Refusals keep `409`. A later message that reuses the id can't
+answer the cleared call.
+
 ## Authorize
 
 `authorize` is per-operation policy, checked before any read, write, or
@@ -258,7 +271,7 @@ What the hook gives you:
 - **`refresh()`**: reads a fresh snapshot and adopts it before resolving.
   Use it after a refusal or when returning to a suspended browser tab.
 - **`connection`**: the same discriminated union as
-  [`useSession`](/guides/react#the-client-component), heartbeat
+  [`useSession`](/guides/react#events-and-history), heartbeat
   watchdog included.
 
 Live, not optimistic. Handlers are server code deciding against

package/docs/concepts/01-contracts.mdx

@@ -132,6 +132,101 @@ progress. Collections, joins, search, and constraints across many records
 usually belong in an application database. See
 [A2 and your database](/guides/application-data).
 
+## Clearing a session
+
+`session.clear()` ends a session's current lifetime. Its history is gone,
+every reducer is back at its initial state, and the session id keeps working.
+
+```ts server/clear-order.ts
+import { ordersServer } from './orders'
+
+export async function clearOrder({ orderId, lastIndex }: {
+  orderId: string
+  lastIndex: number
+}) {
+  // here's where you'd do auth, or any other checks
+  return ordersServer.session(orderId).clear({ ifLastIndex: lastIndex })
+}
+```
+
+A clear appends one reserved marker, so indexes never restart. Clearing a
+session whose last event is `42` returns `{ cleared: true, index: 43 }`, and
+the next event is `44`.
+
+Pass `ifLastIndex` when newer events must survive. The store checks it in the
+same atomic step that appends the marker. If another event landed first, the
+clear skips and returns `{ cleared: false, index }` with the current head. You
+need no state read when you already know an event's index. A conditional clear
+is safe to retry.
+
+Work from the old lifetime stops counting. Its pending events are never
+dispatched, and a handler still running for one of them can't append, return
+events, or read the new lifetime's state. Clearing can't stop code that is
+already running or undo its side effects.
+
+Pushes and appends that land after the marker start the new lifetime, like
+any other event. Connected clients reset when the marker reaches them. Once a
+session has been cleared, `session.state()` also returns `clearIndex`. Pass the
+whole result as a client's `initial` snapshot so a cached client drops its old
+history too; the automatic snapshot on subscribe carries it already.
+
+After the marker, `clear()` deletes the old events and cached state in small
+batches and resolves when they're gone. Appends and reads keep running between
+batches, and the cost grows with the size of the old history. If it fails
+partway, the session is still cleared and the leftovers are invisible: retry
+the call, or clear again later, to finish deleting. For a very large session,
+a [scheduled clear](#scheduling-a-clear) is sturdier, because the provider
+retries it and each retry resumes the deletion. Presence is separate and keeps its own expiry.
+
+Clearing is a server operation. `server.fetch` has no clear endpoint, so
+authorize your own route before calling it.
+
+### Scheduling a clear
+
+With a [scheduler](/guides/production) configured, a handler can schedule a
+clear for later. This one clears an idle cart a day after its last activity:
+
+```ts server/carts.ts
+import * as a2 from 'experimental-a2'
+import { createServer } from 'experimental-a2/server'
+import { vercelQueues } from 'experimental-a2/scheduler-vercel'
+import { z } from 'zod'
+
+export const carts = a2.contract({
+  name: 'carts',
+  events: {
+    'item.added': z.object({ sku: z.string() }),
+  },
+})
+
+export const cartsServer = createServer({
+  contract: carts,
+  scheduler: vercelQueues(),
+  handlers: {
+    'item.added': async ({ event, session }) => {
+      await session.schedule.clear('idle', {
+        delay: '1d',
+        ifLastIndex: event.index,
+      })
+    },
+  },
+})
+```
+
+The delay counts from the event's stored time. Any later event moves the head
+past `event.index`, so this delivery skips; that event's own handler schedules
+the next check. Only events with a handler can extend the policy this way.
+
+The handler's own writes move the head too. This handler appends and returns
+nothing, so `event.index` stays the head. A handler that appends should pass
+the index its last append returned.
+
+Delivery runs the same conditional clear and finishes the deletion before it
+acknowledges, so provider retries complete an interrupted delete. No cleanup
+event is appended. The clear happens when the task is delivered, not at an
+exact deadline, and provider limits apply: Vercel Queues accepts delays up to
+six days.
+
 ## One more option: a scheduler
 
 Servers accept a `scheduler` option. When a top-level append leaves or finds

package/docs/concepts/04-state.mdx

@@ -35,18 +35,18 @@ export const orders = a2.contract({
 ```
 
 ```ts reducer.ts
+import { reducer } from 'experimental-a2'
 import { z } from 'zod'
 import { orders } from './contracts'
 
-export const ordersReducer = orders
-  .reducer({
+export const ordersReducer = reducer({ contract: orders,
     name: 'order-status',
     initialState: { status: 'new' },
     stateSchema: z.object({
       status: z.enum(['new', 'created', 'notified', 'expired']),
       shopId: z.string().optional(),
     }),
-  })
+   })
   .fold((state, event) => {
     switch (event.type) {
       case 'created':

package/docs/guides/01-timers.mdx

@@ -102,7 +102,9 @@ of one event converge.
 Keep the same name, timing, and events on every retry. A2 derives stable ids for
 events whose `id` you omit. Provider deduplication folds repeated sends while
 its deduplication window is open. After that window, duplicate deliveries
-still append once because they carry the same event ids. A changed input under
+still append once because they carry the same event ids, within one session
+lifetime. A [clear](/concepts/contracts#clearing-a-session) frees those ids, so
+a root task redelivered after one appends again. A changed input under
 the same identity conflicts when it produces a different validated event at
 delivery.
 
@@ -133,10 +135,9 @@ That means scheduled events:
 
 If the deployment receiving a timer removes or changes its event schema,
 delivery can fail validation and remain visible as a retrying scheduler error.
-Vercel Queues pins timers to their publishing deployment by default. This
-cross-deployment compatibility concern applies when
-`scheduledAppends: 'deploymentless'` is selected and to adapters that target a
-stable URL, such as QStash.
+The Vercel adapter pins timers to their publishing deployment by default.
+Cross-deployment compatibility matters when `deploymentId: null` is selected
+or an adapter targets a stable URL, such as QStash.
 
 ## Stale timers
 
@@ -168,18 +169,25 @@ because its `notBefore` timestamp uses whole Unix seconds.
 
 ## Deploy safely
 
-Vercel Queues pins scheduled appends and recovery watchdogs to their publishing
-deployment by default. `scheduledAppends: 'deploymentless'` removes affinity
-only for timers. Select it only when every eligible consumer for the topic can
-decode pending tasks and validate their events. Recovery remains pinned.
+The Vercel adapter's `deploymentId` setting applies to scheduled appends,
+scheduled clears, and recovery watchdogs alike. The default uses the publishing
+deployment. Promoting a new deployment does not move pinned tasks: older
+deployments keep receiving their own work until it is acknowledged or expires.
 
-New scheduler routes accept older recovery messages, which supports adapter
-upgrades for schedulers that deliberately cross deployments.
+Use `deploymentId: null` for deploymentless delivery of every task, including
+recovery. Every eligible consumer must use the same setting and remain
+compatible with pending tasks and session work. Deploymentless delivery does
+not select the latest production deployment.
+
+Changing the setting does not move already queued tasks. Keep consumers for
+their original deployment scope until those tasks finish. The former
+`scheduledAppends: 'deploymentless'` option affected only timers; its replacement,
+`deploymentId: null`, also makes recovery deploymentless.
 
 :::warning
-When using deploymentless Vercel timers or a stable callback URL, do not roll
-back to an A2 version without timer delivery while timer tasks are still
-outstanding. An older route can acknowledge one as a recovery message without
+When using deploymentless Vercel delivery or a stable callback URL, do not roll
+back to an A2 version without timer delivery while timer tasks are still outstanding.
+An older route can acknowledge one as a recovery message without
 appending its events. Roll forward, or first wait for the tasks to deliver or
 remove them through the provider.
 :::

package/docs/guides/02-cancellation.mdx

@@ -150,7 +150,7 @@ saw are removed retroactively, so the optimistic view and the
 authoritative refold agree on the same result. No wall clocks, no skew.
 
 And because the client pushes `cancelled`
-[optimistically](/guides/react#the-client-component), its own fold cuts
+[optimistically](/guides/react#events-and-history), its own fold cuts
 instantly. Stragglers still arriving over the stream hit `state.cancelled`
 and vanish from the view.