experimental-a2 0.16.1 → 0.18.0

package/dist/wire-rSUglYo8.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wire-rSUglYo8.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

@@ -1,13 +1,12 @@
 ---
 title: Quickstart
-description: Define one lifecycle, implement its reactions, and make your first durable append in about five minutes.
+description: Define a contract, react to its events, and make your first durable append in five minutes.
 ---
 
 ## What you'll build
 
-The smallest useful lifecycle: an order that notifies a shop when it arrives.
-One contract, one session, one handler, two routes, and at the end a log you
-can read back.
+An order that notifies a shop when it arrives: one contract, one handler, two
+routes, and a log you can read back.
 
 ## 1. Install
 
@@ -17,10 +16,7 @@ npm i experimental-a2 zod
 
 ## 2. Define a contract
 
-A contract is a name plus the events it understands: each key an event
-name, each value a schema. Zod here, though any
-[Standard Schema](https://standardschema.dev) validator works, and
-that's the contract's complete declaration.
+A contract is a name plus the events it understands, each with a schema:
 
 ```ts server/orders.ts
 import { z } from 'zod'
@@ -35,21 +31,10 @@ export const orders = a2.contract({
 })
 ```
 
-The contract is a plain, importable, isomorphic value. The server
-implements it below, the reducer derives from it in step 6, and when a
-browser enters the picture it types the client too.
-
-There's no database setup in development: A2 stores events in SQLite at
-`.a2/dev.db`, so state survives restarts. Tests get an in-memory store.
-Production wants an explicit backend; see
-[Going to production](/guides/production).
-
 ## 3. Implement it
 
-Handlers run where the contract is served. `createServer` binds the
-vocabulary to storage and reactions; each handler gets the triggering
-event and can append what happens next. Same file, below the contract
-(they can split later, when a browser needs the contract alone):
+`createServer` binds the contract to storage and handlers. Same file, below
+the contract:
 
 ```ts server/orders.ts
 import { createServer } from 'experimental-a2/server'
@@ -66,24 +51,19 @@ export const ordersServer = createServer({
 })
 ```
 
-All handlers are declared at construction: one table of reactions, so a
-handler can never be silently missing because the module that registered
-it wasn't imported.
-
-Two things worth noticing:
+- Handlers can run more than once (at-least-once delivery), so make external
+  calls safe to repeat. `event.id` is stable across re-runs: use it as the
+  idempotency key.
+- The returned event commits atomically with handler success. If the handler
+  throws or the process dies first, `shop.notified` doesn't appear. Return one
+  event or an array.
 
-- The side effect takes an idempotency key. Handlers can run more than
-  once (that's what at-least-once delivery means), so external calls
-  should be safe to repeat. `event.id` is stable across re-runs. Use it.
-- The returned event is committed atomically with successful handler
-  completion. If the handler throws or the process dies first,
-  `shop.notified` does not appear. A handler can return one event or an array.
+Development needs no database setup: events go to SQLite at `.a2/dev.db` and
+survive restarts. Tests get an in-memory store. Production needs an explicit
+store; see [Production](/server/production).
 
 ## 4. Append the first event
 
-`append` is the entire public surface for moving a session forward. Call it
-from a route:
-
 ```ts app/api/orders/route.ts
 import { ordersServer } from '@/server/orders'
 
@@ -99,11 +79,8 @@ export async function POST(req: Request) {
 }
 ```
 
-A session is one instance of the contract. `ordersServer.session('order-42')`
-is order 42's lifecycle: the unit A2 recovers, folds, and streams.
-Creating the handle does no I/O, and the id is yours to choose.
-
-Try it:
+`session(orderId)` is one [session](/contract/sessions), one instance of the
+contract. The id is yours, and creating the handle does no I/O.
 
 ```bash
 curl -X POST localhost:3000/api/orders \
@@ -111,18 +88,15 @@ curl -X POST localhost:3000/api/orders \
   -d '{ "orderId": "order-42", "shopId": "shop-7", "items": ["flat white"] }'
 ```
 
-The payload is validated against the schema before anything is written;
-send garbage and you get `INVALID_PAYLOAD` back, with the issues.
+The payload is validated before anything is written; a bad one fails with
+`INVALID_PAYLOAD` and the issues.
 
-When the append returns, the event is durably in the log and A2 has started the
+When `append` returns, the event is durably in the log and A2 has started the
 `created` handler inline. In production, a queue-backed scheduler wakes pending
-work after a failure or process death. See [Durability](/concepts/durability)
-for the exact contract.
+work after a failure or process death. See [Guarantees](/server/guarantees).
 
 ## 5. Read the log back
 
-Add a route that returns the session's history:
-
 ```ts app/api/orders/[orderId]/route.ts
 import { ordersServer } from '@/server/orders'
 
@@ -147,41 +121,35 @@ curl localhost:3000/api/orders/order-42
 ]
 ```
 
-(Trimmed for brevity; each event also carries `id`, `sessionId`, and
-`createdAt`.)
-
-That second event is the payoff. You appended one event; the handler
-returned the next; the log shows the whole story, in order. This is what
-debugging looks like in A2: you read.
+Each event also carries `id`, `sessionId`, and `createdAt` (trimmed here). You
+appended one event and the handler returned the second. Debugging in A2 is
+reading the log.
 
 ## 6. Fold state out of the log
 
-Raw session history is truth, but UIs usually want a view. Define a reducer
-once:
+UIs usually want a view, not raw history. 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' } })
-  .fold((state, event) => {
-    switch (event.type) {
-      case 'created':
-        return { ...state, status: 'created' }
-      case 'shop.notified':
-        return { ...state, status: 'notified' }
-      default:
-        return state
-    }
-  })
+export const ordersReducer = reducer({
+  contract: orders,
+  name: 'order-status',
+  initialState: { status: 'new' },
+}).fold((state, event) => {
+  switch (event.type) {
+    case 'created':
+      return { ...state, status: 'created' }
+    case 'shop.notified':
+      return { ...state, status: 'notified' }
+    default:
+      return state
+  }
+})
 ```
 
-A reducer is *derived from* the contract, in two steps by design: the
-first call fixes the state and event types, so `.fold()` receives fully
-concrete ones. No type arguments, no annotations, and literal unions in
-your state survive the fold.
-
-And fold anywhere you need the current picture:
+Then fold wherever you need the current picture:
 
 ```ts
 // anywhere on the server:
@@ -192,22 +160,20 @@ const { state } = await ordersServer.session('order-42').state(ordersReducer)
 // state → { status: 'notified' }
 ```
 
-The session's state is not a second record to update. It is a fold over the
-log. More in [Reading state](/concepts/state).
+State isn't a second record to update. It's a fold over the log; see
+[State](/contract/state).
 
 ## That's it
 
-You have a durable lifecycle, implemented: a validated write path, a handler,
-a log you can read, and a view folded from it.
-Everything else in these docs is the same two moves, append an event and
-react to it, applied to timers, cancellation, live UIs, and production
-infrastructure.
+You have a validated write path, a handler, a log you can read, and a view
+folded from it. The rest of these docs apply the same two moves, append an
+event and react to it, to timers, cancellation, live UIs, and production.
 
 <CardGroup cols={2}>
-  <Card title="Handlers" href="/concepts/handlers" icon="file">
-    The context object, chaining, ordering, and re-runs.
+  <Card title="Handlers" href="/server/handlers" icon="file">
+    Context, chaining, and re-runs.
   </Card>
-  <Card title="Going to production" href="/guides/production" icon="rocket">
-    Postgres, a queue-backed scheduler, and dead-letter resolution.
+  <Card title="Production" href="/server/production" icon="rocket">
+    A store, a scheduler, dead letters.
   </Card>
 </CardGroup>

package/docs/{guides/07-examples.mdx → 02-examples.mdx}

@@ -1,19 +1,10 @@
 ---
 title: Complete examples
-description: Read or copy the complete Next.js playground that ships inside the experimental-a2 package.
+description: Every experimental-a2 install includes a complete Next.js playground to copy, run, and read.
 ---
 
 ## Shipped with the package
 
-Every `experimental-a2` installation includes a complete Next.js playground at
-`node_modules/experimental-a2/examples/playground`.
-
-The playground is not a collection of isolated snippets. Each feature owns its
-contract, reducer, server, route handlers, client session, and scheduler when it
-needs one. It uses only public package entry points.
-
-Copy it into a new directory to run or modify it:
-
 ```sh
 cp -R node_modules/experimental-a2/examples/playground ./a2-playground
 cd a2-playground
@@ -21,12 +12,13 @@ pnpm install
 pnpm dev
 ```
 
-The copied `package.json` is standalone. Its A2 dependency is pinned to the
-version that supplied the example.
+The playground lives at `node_modules/experimental-a2/examples/playground`.
+Each feature owns its contract, reducer, server, route handlers, client
+session, and scheduler when it needs one, using only public entry points.
 
-The snapshot also includes an `AGENTS.md` file. Coding agents that support
-repository instructions discover the example's structure as soon as they work
-inside the copied directory.
+The copy is standalone: its `package.json` pins A2 to the version that
+shipped it, and its `AGENTS.md` describes the structure to coding agents that
+work inside the directory.
 
 ## Find the right example
 
@@ -49,8 +41,6 @@ When A2 is installed locally, read these package directories in this order:
 3. `node_modules/experimental-a2/src` only when implementation details are
    relevant.
 
-Do not infer application patterns from `dist`. The playground is the reference
-for how the public pieces fit together in a real Next.js application.
-
-The npm snapshot is generated from `apps/playground` in the A2 repository when
-the package is published, so the runnable app remains the canonical source.
+Don't infer application patterns from `dist`. The playground, generated from
+`apps/playground` in the A2 repository at publish time, is the reference for
+how the public pieces fit together.

package/docs/actors/01-introduction.mdx

@@ -1,28 +1,22 @@
 ---
 title: Introduction
-description: "A durable object built on the log: one named instance, typed state, and handlers that process one message at a time."
+description: "Typed state behind a mailbox. Each instance processes one message at a time, and each handler ends in one atomic commit."
 ---
 
 ## The model
 
-An actor is state behind a mailbox. You address an instance by id, send
-it typed events, and its handlers process them one at a time: read
-state, decide, mutate, return. Each handler ends in one atomic commit.
-Between messages the instance is rows in your store, not a process:
-nothing to keep alive, no locks to take, no lost updates to debug.
+An actor is state behind a mailbox: you send an instance typed events,
+and its handlers process them one at a time. Between messages an
+instance is rows in your store, not a process. Every instance is an
+ordinary A2 session, so durability, retries, history, and devtools hold
+for actors too.
 
-Every instance is an ordinary A2 session underneath, so everything the
-log gives a session (durability, retries, history, devtools) holds for
-actors too. The module is three entry points: `experimental-a2/actor`
-on the server, `experimental-a2/actor/client` anywhere, and
+Entry points: `experimental-a2/actor` on the server,
+`experimental-a2/actor/client` anywhere, and
 `experimental-a2/actor/react` for the hook.
 
 ## Define one
 
-A protocol declares the state shape and the events with their inputs.
-Types, not schemas: handlers are trusted server code, and the compiler
-holds them to the protocol. Pass it explicitly.
-
 ```ts vault.ts
 import { NonRetriableError } from 'experimental-a2'
 import { actor } from 'experimental-a2/actor'
@@ -52,28 +46,22 @@ export const vault = actor<Vault>({
 })
 ```
 
-The `handlers` record must cover every declared event: a missing
-handler, an extra one, or a wrong input shape fails to compile. Inputs
-arrive typed; `ctx.state` is a mutable draft of the instance's state,
-committed atomically when the handler returns. `name` is identity (it
-prefixes storage keys), and `state` seeds new instances.
+Pass the protocol explicitly as the type argument. It declares types,
+not schemas: handlers are trusted server code, and a missing handler,
+an extra one, or a wrong input shape fails to compile. `ctx.state` is a
+mutable draft, committed atomically when the handler returns. `name` is
+identity (it prefixes storage keys), and `state` seeds new instances.
 
-Types are compile-time claims. When an event can arrive from the wire,
-guard its input in the handler's first lines and throw
-`NonRetriableError` on bad shapes (bring a schema library and `.parse`
-if you prefer; it is userland either way).
+When an event can arrive from the wire, guard its input in the
+handler's first lines and throw `NonRetriableError` on bad shapes.
 
-`actor` also accepts the `store`, `scheduler`, and `telemetry` options
-`createServer` takes. Without a store it uses the same development
-default; see [Going to production](/guides/production). A protocol can
-declare one more vocabulary, `presence`, for live audience state; see
-[Presence](/actors/routes#presence).
+`actor` also accepts `createServer`'s `store`, `scheduler`, and
+`telemetry` options, with the same development default store; see
+[Production](/server/production). A protocol can also declare
+[`presence`](/actors/routes#presence).
 
 ## Call it
 
-`call` sends the event and awaits its answer: the state after the
-handler ran, and the log index of that commit.
-
 ```ts
 // anywhere on the server:
 import { vault } from '@/vault'
@@ -84,18 +72,14 @@ const { state, index } = await savings.call.deposit({ amount: 100 })
 // state reflects this deposit, and every message before it
 ```
 
-`vault.actor(id)` is a handle, not a resource; nothing exists until the
-first message. Concurrent calls from any number of serverless
+`call` awaits the answer: the state after the handler ran and the log
+index of that commit. `vault.actor(id)` is a handle; nothing exists
+until the first message. Concurrent calls from any number of
 invocations serialize on the instance's lane, and each answer reflects
-its own message. That serialization is the feature:
-[Concurrency](/actors/concurrency) is the full story.
+its own message; see [Concurrency](/actors/concurrency).
 
 ### Refusals
 
-A handler says no by throwing `NonRetriableError`. That refusal is an
-answer, not a failure: nothing commits, nothing retries, and the caller
-gets the message.
-
 ```ts
 // anywhere on the server:
 import { ActorRefusedError } from 'experimental-a2/actor'
@@ -110,24 +94,23 @@ try {
 }
 ```
 
-Three kinds of failure, three behaviors:
+Throwing `NonRetriableError` refuses the message. A refusal is an
+answer, and it is all or nothing: no state change, no buffered sends,
+no retry. The message settles, and the caller receives
+`ActorRefusedError`.
 
-- **`NonRetriableError`** is a refusal, and a refusal is all or
-  nothing: no state change, no buffered sends. The message is settled,
-  and the caller receives `ActorRefusedError`.
-- **Any other throw** is an infrastructure failure. A2 retries the
-  message with the usual budget and backoff; the instance's lane waits,
-  which is deliberate (correctness over liveness). See
+- **Any other throw** retries the message with the usual budget and
+  backoff while the instance's lane waits; see
   [Errors](/reference/errors).
 - **A crash** re-runs the handler from the pre-message state. `ctx.id`
   is the message id, stable across re-runs: use it as the idempotency
   key for external I/O.
+- **A clear** by `handle.session.clear()` before the answer rejects the
+  call with an `A2Error` whose code is `SESSION_CLEARED`. The handler
+  may already have run. Over HTTP it's a `410`.
 
 ## Send, don't wait
 
-`send` validates, appends the event durably, and returns without
-waiting for the handler.
-
 ```ts
 // anywhere on the server:
 import { vault } from '@/vault'
@@ -136,9 +119,9 @@ const { id } = await vault.actor('savings').send.deposit({ amount: 25 })
 // durably queued; the handler runs on the instance's lane
 ```
 
-Same mailbox, same ordering; the only difference is that nobody waits
-for the answer. Pass `{ id }` in the options to make a retried send
-idempotent.
+`send` validates and appends the event durably without waiting for the
+handler: same mailbox, same ordering. Pass `{ id }` in the options to
+make a retried send idempotent.
 
 ## Read without queueing
 
@@ -149,41 +132,24 @@ import { vault } from '@/vault'
 const { state } = await vault.actor('savings').state()
 ```
 
-A snapshot read. It never queues behind pending messages, and a new
+A snapshot read: it never queues behind pending messages, and a new
 instance reads as its seed state.
 
 ## State is remembered, not recomputed
 
-Every commit appends a state event to the instance's log, and reads
-fold those by last write wins. History is never reinterpreted: you can
-rewrite a handler freely without changing what any past commit means.
-(This is the opposite trade from [reducers](/concepts/state), which
-recompute views from events; actor state is the recorded decision
-itself.)
+Every commit appends a state event, and reads fold them by last write
+wins. Unlike [reducers](/contract/state), nothing is recomputed, so
+rewriting a handler never changes what a past commit means. State must
+be plain JSON: a `Date`, a `Map`, or `NaN` fails the commit loudly.
 
-Because state lives in the log, it holds to the same floor as any
-payload: plain JSON trees. A `Date`, a `Map`, or `NaN` fails the commit
-loudly instead of being silently coerced.
-
-Two consequences worth designing for:
-
-- **Old instances meet new code.** After a deploy, state written by the
-  previous version flows into the new handlers. Default new fields
-  defensively (`ctx.state.pending ??= {}` as a first line) instead of
-  assuming the latest shape.
-- **The seed applies to new instances only.** Changing `state` in the
-  definition does not migrate existing instances; they keep their
-  remembered state.
+- **Old instances meet new code.** After a deploy, default new fields
+  defensively (`ctx.state.pending ??= {}` as a first line).
+- **The seed applies to new instances only.** Changing `state` does not
+  migrate existing instances.
 
 ## The log is still there
 
-An actor is a layer over an ordinary A2 session, not a wall around
-one. `handle.session` is that session (history, streams, scheduling),
-the definition
-exposes its assembled `contract`, `server`, and `reducer`, and the full
-mailbox is visible in devtools. Event names starting with `a2.` are
-reserved for the actor's own bookkeeping.
-
-Next: [Concurrency](/actors/concurrency) for the execution
-model, [Deadlines and timers](/actors/timers) for scheduled events, and
-[Routes, clients, and React](/actors/routes) for the wire.
+`handle.session` is the instance's underlying session (history,
+streams, scheduling). The definition exposes its assembled `contract`,
+`server`, and `reducer`, and devtools show the full mailbox. Event
+names starting with `a2.` are reserved for the actor's own bookkeeping.