experimental-a2 0.10.0 → 0.11.0

package/docs/reference/01-api.mdx

@@ -59,7 +59,8 @@ invalidates, and the next read refolds from raw events. See
 
 ### `A2Error`
 
-Everything A2 throws. One class, discriminated by `code`. See
+The shared base for A2 failures, discriminated by `code`. The session
+client exposes its `A2ClientError` subclass. See
 [Errors](/reference/errors).
 
 ## `experimental-a2/server`
@@ -793,25 +794,27 @@ transition and the destination should adopt the same optimistic session.
 | --------------- | ------------------------------------------------------ |
 | `sessionId`     | which session to subscribe to                          |
 | `initialState`  | server-rendered state                                  |
-| `initialIndex`  | the fold's frontier, where the stream resumes          |
+| `initialIndex`  | the fold's frontier, where a new session starts streaming |
 | `initialEvents` | optional earlier raw events for a history UI           |
 | `participant`   | overrides the client's `participant`; one of the two is required to call `setPresence` |
 
 Opens the stream on mount, closes it on unmount, reconnects with
-backoff from the current frontier. `participant` binds at the session's
+backoff from its last streamed event. `participant` binds at the session's
 first resolution; a changed provider prop is ignored for the session's
 runtime lifetime.
 
 `initialState` and `initialIndex` are the complete server-to-client handoff.
-The stream resumes after `initialIndex`, including events appended between the
-server render and the connection. `initialEvents` only preloads the raw
+For a new session, the stream starts after `initialIndex`, including events
+appended between the server render and the connection. `initialEvents` only preloads the raw
 `events` feed for a UI that needs entries from before that frontier. It does
-not affect state hydration or stream resumption.
+not affect state hydration or stream resumption. Later snapshots advance
+state while preserving the stream's resume position, so delayed events
+still enter the feed without folding into state again.
 
 ### `useSession()`
 
 ```ts
-const { state, push, events, index, loadHistory, history, connection,
+const { state, push, reconnect, events, index, loadHistory, history, connection,
   presence, setPresence } = useSession()
 ```
 
@@ -819,7 +822,7 @@ const { state, push, events, index, loadHistory, history, connection,
 shared reducer. `events` is the raw event feed: observed, explicitly
 seeded, or backscrolled. Unless `initialEvents` seeds earlier entries or
 `loadHistory` fetches them, it begins after `initialIndex`. `index` is
-the stream frontier, the `lastSeenIndex` for
+the latest server-confirmed state index, the `lastSeenIndex` for
 [cancellation](/guides/cancellation).
 
 `loadHistory({ before?, limit? })` backscrolls: it fetches a bounded
@@ -828,10 +831,9 @@ query parameters) and merges it into `events`, deduped, ordered, and
 shared across every handle of the session. It resolves with the events
 in the requested range. Defaults walk backward 50 at a time from the
 oldest loaded event; `before` is an exclusive upper bound. After a
-hydrate jump (returning to a session whose frontier advanced while
-away), default paging still continues from the oldest loaded event;
-pass an explicit `before` to fill the gap between the old feed and the
-new frontier. It never touches `state` or the optimistic overlay. Calls
+newer snapshot hydrates the session, default paging still continues from
+the oldest loaded event. Pass an explicit `before` to read another range.
+It never touches `state` or the optimistic overlay. Calls
 serialize per session and already-loaded ranges are not refetched.
 `history` is the progress: `{ loading, complete, oldestLoaded }`, where
 `complete` means the feed reaches index 1 (or the log is empty). The `ws` api has no history lane; there `loadHistory`
@@ -856,7 +858,7 @@ contract; it still never folds presence). `setPresence` requires a
 [Presence](/guides/presence).
 
 `push` appends optimistically: validated locally, rolled back on
-rejection, retried only for `STORE_UNAVAILABLE`. Awaiting it gives the
+rejection, retried for `STORE_UNAVAILABLE` and transport failures. Awaiting it gives the
 server ack; the same result carries `confirmed`, a lazy promise for
 the later moment when the live stream has delivered the batch back and
 the view shows server truth:
@@ -875,18 +877,31 @@ only for the previous call's ack or final rejection, not for `confirmed`.
 Other session IDs and clients remain concurrent; they converge on the log's
 durable order.
 
-A rejected push rejects both promises with the same `A2Error`;
+A rejected push rejects both promises with the same `A2ClientError`;
 `confirmed` is materialized only when accessed, so ignoring it costs
 nothing. It also reads as intent: `await push(...).confirmed` is
 "continue once this is server truth".
 
+`session.reconnect(): void` immediately restarts a leased subscription,
+including one paused by the reconnection policy,
+from its current cursor. It preserves state, pending writes, and leases, and
+does nothing without an active lease. The React `useSession()` result exposes
+the same `reconnect` function. Use it after a custom REST mutation; it requests
+a restart rather than returning a promise for catch-up completion. A
+multiplexed WebSocket keeps its physical socket and other session lanes;
+a single-session WebSocket replaces its socket.
+
 `connection` is a discriminated union; impossible states are
 unrepresentable (an `error` only exists while disconnected):
 
 ```ts
+// in a client module:
+import type { A2ClientError } from 'experimental-a2/client'
+
 type Connection =
   | { status: 'idle' }
-  | { status: 'connecting'; reconnects: number; error: Error | null }
+  | { status: 'connecting'; reconnects: number; error: A2ClientError | null }
+  | { status: 'paused'; reconnects: number; error: A2ClientError | null }
   | { status: 'live'; reconnects: number }
   | { status: 'closed' }
 ```
@@ -1206,6 +1221,11 @@ createClient(options: {
   api: ClientApi
   gcTime?: number // idle session lifetime; 5 minutes by default
   participant?: string // default presence identity for every session
+  reconnect?: (failure: {
+    sessionId: string
+    error: A2ClientError | null
+    attempt: number
+  }) => number | false
 }): A2Client
 
 type ClientApi =
@@ -1217,6 +1237,30 @@ type ClientApi =
 type SessionUrl = string | ((sessionId: string) => string)
 ```
 
+`reconnect` runs after a failed connection or a stream ending, including a
+clean end with `error: null`. Return the delay in milliseconds before the next
+attempt, or `false` to pause automatic reconnection. Delays must be finite,
+non-negative, and at most 2,147,483,647 ms. The callback is synchronous; a
+throw or invalid result pauses the connection with an `A2ClientError`.
+
+`attempt` starts at 1 for the first retry. It counts consecutive attempts
+per session and resets when the stream becomes live or `session.reconnect()`
+explicitly restarts it. It is separate from the lifetime `reconnects` count.
+Without a callback, A2 retries indefinitely with delays starting at 500 ms,
+doubling up to five seconds. The callback does not run for an explicit
+restart, an idle-stream refresh, or a caller closing the stream.
+
+While paused, `connection.status` is `paused` and its last error remains
+available. State, hydration, optimistic writes, and connection leases remain
+intact. Another consumer taking a lease does not resume a paused stream.
+Call `session.reconnect()` to resume immediately with a fresh attempt count.
+Releasing the last lease still closes the stream. A later first lease starts
+a new connection. Push retries are independent of this policy; a push does
+not resume a paused stream. An acknowledged push's `confirmed` promise waits
+until streamed events or a newer hydrated snapshot cover the acknowledged
+state index. Resumption preserves the stream's own position, even when
+hydration has advanced state while paused.
+
 A `SessionUrl` function runs for each HTTP request or WebSocket connection.
 Use it for session-specific paths. A2 still adds its `sessionId` and read-bound
 query parameters. The function does not authorize that ID. Bind any path scope
@@ -1229,7 +1273,7 @@ subscription with frontier resume and reconnection, the optimistic push
 queue with ack/rollback, and the local fold. `client.session(id, {
 initialState?, initialIndex?, initialEvents?, participant? })` returns a
 handle with `getSnapshot()`/`subscribe()` (the `useSyncExternalStore`
-contract), `push()`, `loadHistory()`, `connect()`, and `close()`.
+contract), `push()`, `loadHistory()`, `connect()`, `reconnect()`, and `close()`.
 `connect()` takes a lease on the live stream and returns its release:
 leases refcount per handle (the first connects, releasing the last
 closes, releasing twice is a no-op), so independent consumers of one

package/docs/reference/02-errors.mdx

@@ -1,13 +1,13 @@
 ---
 title: Errors
-description: One error class, stable codes, and clear rules about what append will never throw for.
+description: Stable server and client error codes, transport details, and append guarantees.
 ---
 
 ## `A2Error`
 
-Everything A2 throws is an `A2Error`, a single class discriminated by
-`code`, not a subclass hierarchy. One class serializes cleanly across the
-push-route boundary and keeps `instanceof` working after bundling.
+A2 failures carry an `A2Error` with a stable `code`. The session client exposes
+`A2ClientError`, which extends `A2Error`, for both server failures and failures
+observed locally. Existing `instanceof A2Error` checks also match client errors.
 
 ```ts
 // e.g. in a route handler:
@@ -45,9 +45,39 @@ export async function POST(req: Request) {
 | `STORE_UNAVAILABLE`       | the store backend failed; nothing was written, original error as `cause` | **yes**   |
 | `STORE_NOT_CONFIGURED`    | production boot with no `store` configured (during `next build` page collection, deferred to first use) | no |
 
-Retryability is derivable from the code. `STORE_UNAVAILABLE` is the only one
-worth retrying; the rest are deterministic caller bugs, and retrying them
-is wasted work.
+Of these server codes, only `STORE_UNAVAILABLE` is automatically retried by
+client pushes. Reconnection has its own caller-configurable policy.
+
+## `A2ClientError`
+
+Import `A2ClientError` from `experimental-a2/client`. Connection failures,
+push failures, history read failures, and local A2 validation failures use
+this class. Server failures keep their `code`, `message`, and `details`.
+Unexpected thrown values are retained as `cause`. Invalid API arguments can
+still throw native `TypeError` or `RangeError` exceptions.
+
+| Client code | Meaning |
+| --- | --- |
+| `TIMEOUT` | A2 detected a stream stall or an unconfirmed subscription. `phase` is `stream` or `subscribe`; `timeoutMs` is the expired deadline. |
+| `HTTP_ERROR` | An unsuccessful HTTP response without a recognized A2 error body. `status` carries the HTTP status. |
+| `CONNECTION_FAILED` | The transport could not establish or retain a connection. WebSocket close events preserve `closeCode` and `closeReason` when available. |
+| `UNKNOWN` | An unexpected client failure. The original value is available as `cause`. |
+
+HTTP failures retain `status` even when they carry a recognized server code.
+A browser WebSocket handshake rejection has no readable HTTP status or body;
+it remains `CONNECTION_FAILED`. A2 does not infer an authorization failure or
+a timeout from an opaque socket error.
+
+The stream watchdog detects 35 seconds of silence after connection. A
+multiplexed subscription also has 35 seconds to receive confirmation. There
+is no A2-owned initial connection deadline for HTTP or single-session
+WebSockets. Clean stream termination has no error: the reconnection callback
+and connection snapshot carry `null`.
+
+Pushes retain their three-attempt budget for `STORE_UNAVAILABLE` and client
+transport failures. The reconnection callback controls only the live stream.
+Pausing that stream preserves the writer; it does not guarantee that a push
+can succeed while its WebSocket is unavailable.
 
 On `PARTIAL_DUPLICATE_BATCH`: retrying an *identical* batch is not an
 error. It's an idempotent success, and you get the previously appended
@@ -60,7 +90,7 @@ nothing is written.
 
 ## NonRetriableError
 
-The second exported error class. Throw it (or a subclass, matched by
+Throw it (or a subclass, matched by
 `instanceof`) from a handler when the failure is deterministic: the
 event dead-letters immediately instead of consuming the ten-failure
 retry budget, because a guard that refuses this attempt will refuse
@@ -110,6 +140,10 @@ with a mapped status: `INVALID_PAYLOAD`, `UNKNOWN_EVENT_TYPE`, and
 `PARTIAL_DUPLICATE_BATCH` are 400; `FORBIDDEN` is 403;
 `SUPERSEDED_ATTEMPT` is 409; `STORE_UNAVAILABLE` is 503.
 
-The client's `push` deserializes the body back into an `A2Error`, so client
-and server code branch on identical codes. `push` auto-retries only
-`STORE_UNAVAILABLE`. `server.fetch` owns the HTTP serialization.
+The session client deserializes the body into an `A2ClientError`, so client
+and server code branch on identical server codes. `server.fetch` owns HTTP
+serialization. Multiplexed WebSocket subscription failures carry the same
+error envelope in their `unsubscribed` frame, alongside the legacy `reason`
+string. Older reason-only frames remain readable as `CONNECTION_FAILED`.
+Unknown server exceptions become `STORE_UNAVAILABLE`; their private causes
+are not sent to clients.

package/examples/playground/package.json

@@ -22,7 +22,7 @@
     "@vercel/sandbox": "^3.0.0",
     "ai": "^7.0.58",
     "codemirror": "^6.0.2",
-    "experimental-a2": "0.10.0",
+    "experimental-a2": "0.11.0",
     "ioredis": "^5.9.0",
     "next": "^16.3.0",
     "pg": "^8.16.0",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "experimental-a2",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Durable sync and reactions for things with a lifecycle: one event log, derived state, and live client per session.",
   "license": "MIT",
   "type": "module",

package/src/actor-client.ts

@@ -22,6 +22,16 @@ import type { ActorCallOptions, ActorCallResult } from './actor.ts'
 
 export { ActorRefusedError }
 
+export class ActorRequestError extends Error {
+  readonly status: number | undefined
+
+  constructor(message: string, options?: { status?: number; cause?: unknown }) {
+    super(message, { cause: options?.cause })
+    this.name = 'ActorRequestError'
+    this.status = options?.status
+  }
+}
+
 /** The loose shape of an `actor()` definition — carried type-only. */
 export type AnyActorDefinition = {
   actor(id: string): {
@@ -58,13 +68,15 @@ export type ActorClient<
 > = {
   /** Typed calls over POST — the response is the answer. */
   readonly call: ActorClientCall<D, View>
+  readonly state: () => Promise<ActorCallResult<View>>
 }
 
-export type CreateActorClientOptions = {
+export type CreateActorClientOptions<View = unknown> = {
   /** The route whose handler delegates to `handle.fetch` for this instance. */
   api: string
   /** Injectable transport (tests, custom auth headers). */
   fetch?: typeof globalThis.fetch
+  onSnapshot?: (snapshot: ActorCallResult<View>) => void
 }
 
 const CALL_TIMEOUT_MS = 30_000
@@ -76,7 +88,7 @@ const callOverWire = async (
   input: unknown,
   options?: ActorCallOptions,
 ): Promise<ActorCallResult<unknown>> => {
-  const response = await fetchImpl(api, {
+  const response = await requestOverWire(fetchImpl, api, {
     method: 'POST',
     headers: { 'content-type': 'application/json' },
     body: JSON.stringify({
@@ -86,10 +98,7 @@ const callOverWire = async (
     }),
     signal: AbortSignal.timeout(options?.timeoutMs ?? CALL_TIMEOUT_MS),
   })
-  const body = (await response.json().catch(() => ({}))) as Record<
-    string,
-    unknown
-  >
+  const body = await responseBody(response)
   if (response.status === 409 && typeof body['error'] === 'string') {
     throw new ActorRefusedError(
       typeof body['event'] === 'string' ? body['event'] : event,
@@ -102,7 +111,53 @@ const callOverWire = async (
       typeof body['error'] === 'string'
         ? body['error']
         : `actor call failed (${response.status})`
-    throw new Error(message)
+    throw new ActorRequestError(message, { status: response.status })
+  }
+  return snapshotBody(body, response.status)
+}
+
+const requestOverWire = async (
+  fetchImpl: typeof globalThis.fetch,
+  api: string,
+  init: RequestInit,
+): Promise<Response> => {
+  try {
+    return await fetchImpl(api, init)
+  } catch (cause) {
+    throw new ActorRequestError('actor request did not receive a response', {
+      cause,
+    })
+  }
+}
+
+const responseBody = async (
+  response: Response,
+): Promise<Record<string, unknown>> => {
+  try {
+    const body: unknown = await response.json()
+    if (!body || typeof body !== 'object' || Array.isArray(body))
+      throw new Error('invalid response')
+    return body as Record<string, unknown>
+  } catch (cause) {
+    throw new ActorRequestError('actor request returned an invalid response', {
+      status: response.status,
+      cause,
+    })
+  }
+}
+
+const snapshotBody = (
+  body: Record<string, unknown>,
+  status: number,
+): ActorCallResult<unknown> => {
+  if (
+    !('state' in body) ||
+    !Number.isSafeInteger(body['index']) ||
+    (body['index'] as number) < 0
+  ) {
+    throw new ActorRequestError('actor request returned an invalid snapshot', {
+      status,
+    })
   }
   return body as ActorCallResult<unknown>
 }
@@ -116,17 +171,62 @@ const callOverWire = async (
 export function createActorClient<
   D extends AnyActorDefinition,
   View = ActorStateOf<D>,
->(options: CreateActorClientOptions): ActorClient<D, View> {
+>(options: CreateActorClientOptions<View>): ActorClient<D, View> {
   const fetchImpl = options.fetch ?? globalThis.fetch.bind(globalThis)
+  const adopt = (snapshot: ActorCallResult<unknown>): ActorCallResult<View> => {
+    const result = snapshot as ActorCallResult<View>
+    options.onSnapshot?.(result)
+    return result
+  }
+  const state = async (): Promise<ActorCallResult<View>> => {
+    const api = options.api.split('#')[0]!
+    const separator = api.includes('?') ? '&' : '?'
+    const response = await requestOverWire(
+      fetchImpl,
+      `${api}${separator}snapshot=1`,
+      {
+        cache: 'no-store',
+        signal: AbortSignal.timeout(CALL_TIMEOUT_MS),
+      },
+    )
+    const body = await responseBody(response)
+    if (!response.ok) {
+      throw new ActorRequestError(
+        typeof body['error'] === 'string'
+          ? body['error']
+          : `actor state read failed (${response.status})`,
+        { status: response.status },
+      )
+    }
+    return adopt(snapshotBody(body, response.status))
+  }
+  const methods = new Map<
+    string,
+    (
+      input?: unknown,
+      callOptions?: ActorCallOptions,
+    ) => Promise<ActorCallResult<View>>
+  >()
   const call = new Proxy(
     {},
     {
-      get: (_target, event) =>
-        typeof event === 'string'
-          ? (input?: unknown, callOptions?: ActorCallOptions) =>
-              callOverWire(fetchImpl, options.api, event, input, callOptions)
-          : undefined,
+      get: (_target, event) => {
+        if (typeof event !== 'string') return undefined
+        let method = methods.get(event)
+        if (!method) {
+          method = (input, callOptions) =>
+            callOverWire(
+              fetchImpl,
+              options.api,
+              event,
+              input,
+              callOptions,
+            ).then(adopt)
+          methods.set(event, method)
+        }
+        return method
+      },
     },
   ) as ActorClientCall<D, View>
-  return { call }
+  return { call, state }
 }

package/src/actor-react.ts

@@ -41,6 +41,7 @@ import type { A2Client, Connection } from './client.ts'
 import type { ContractEvent, EventDefs, PresenceDefs } from './contract.ts'
 import type { Reducer } from './reducer.ts'
 import { useSession } from './react.ts'
+import { useMemo } from 'react'
 
 /** The server-to-client handoff: `await def.actor(id).state()`. */
 export type ActorSnapshot<S> = { state: S; index: number }
@@ -66,13 +67,14 @@ type PresenceOf<D extends AnyActorDefinition> = D extends {
   : never
 
 export type UseActorResult<D extends AnyActorDefinition, View> = {
-  /** The actor's state, live: every commit streams in and replaces it. */
+  /** The live view, advanced by call answers, refreshes, and stream commits. */
   state: View
-  /** The stream frontier. */
+  /** The latest adopted state index. */
   index: number
   connection: Connection
   /** Typed calls over POST — the response is the answer. */
   call: ActorClientCall<D, View>
+  refresh: () => Promise<ActorSnapshot<View>>
   /** The state-commit feed this browser has observed. */
   events: ContractEvent<EventDefs>[]
   /**
@@ -128,12 +130,25 @@ export function useActor<D extends AnyActorDefinition, View = ActorStateOf<D>>(
       ? {}
       : { participant: options.participant }),
   })
-  const { call } = createActorClient<D, View>({ api })
+  const { call, state: refresh } = useMemo(
+    () =>
+      createActorClient<D, View>({
+        api,
+        onSnapshot: ({ state, index }) => {
+          client.session(options.id, {
+            initialState: state,
+            initialIndex: index,
+          })
+        },
+      }),
+    [api, client, options.id],
+  )
   return {
     state: session.state as View,
     index: session.index,
     connection: session.connection,
     call,
+    refresh,
     events: session.events,
     presence: session.presence as ActorPresenceMap<PresenceOf<D>>,
     setPresence: session.setPresence as (

package/src/actor.ts

@@ -169,9 +169,10 @@ export type ActorOptions<D extends ActorProtocol> = {
 /**
  * One HTTP operation `handle.fetch` is about to serve — the actor
  * mirror of core's `A2Operation`. `authorize` sees it before any
- * write or subscription; returning `false` answers 403.
+ * read, write, or subscription; returning `false` answers 403.
  */
 export type ActorOperation =
+  | { readonly type: 'state'; readonly id: string }
   | {
       readonly type: 'stream'
       readonly id: string
@@ -736,6 +737,19 @@ export function actor<D extends ActorProtocol>(
 
       if (request.method === 'GET') {
         const url = new URL(request.url)
+        if (url.searchParams.has('snapshot')) {
+          if (!(await authorized({ type: 'state', id }))) return forbidden()
+          const result = await readState()
+          return Response.json(
+            {
+              state: fetchOptions?.view
+                ? applyView(fetchOptions.view, result.state)
+                : result.state,
+              index: result.index,
+            },
+            { headers: { 'cache-control': 'private, no-store' } },
+          )
+        }
         const raw = Number(url.searchParams.get('index'))
         const startAfter = Number.isSafeInteger(raw) && raw >= 0 ? raw : 0
         if (!(await authorized({ type: 'stream', id, startAfter }))) {
@@ -851,6 +865,7 @@ export function actor<D extends ActorProtocol>(
                 index: result.index,
               }
             : result,
+          { headers: { 'cache-control': 'private, no-store' } },
         )
       } catch (error) {
         if (error instanceof ActorRefusedError) {

package/src/client-errors.ts

@@ -0,0 +1,51 @@
+import { A2Error, type A2ErrorCode } from './errors.ts'
+
+export type A2ClientErrorOptions = {
+  details?: unknown
+  cause?: unknown
+  status?: number
+  closeCode?: number
+  closeReason?: string
+  phase?: 'stream' | 'subscribe'
+  timeoutMs?: number
+}
+
+export class A2ClientError extends A2Error {
+  readonly status: number | undefined
+  readonly closeCode: number | undefined
+  readonly closeReason: string | undefined
+  readonly phase: 'stream' | 'subscribe' | undefined
+  readonly timeoutMs: number | undefined
+
+  constructor(
+    code: A2ErrorCode,
+    message: string,
+    options?: A2ClientErrorOptions,
+  ) {
+    super(code, message, options)
+    this.name = 'A2ClientError'
+    this.status = options?.status
+    this.closeCode = options?.closeCode
+    this.closeReason = options?.closeReason
+    this.phase = options?.phase
+    this.timeoutMs = options?.timeoutMs
+  }
+}
+
+export function asClientError(
+  error: unknown,
+  options?: { code?: A2ErrorCode },
+): A2ClientError {
+  if (error instanceof A2ClientError) return error
+  if (error instanceof A2Error) {
+    return new A2ClientError(error.code, error.message, {
+      details: error.details,
+      cause: error,
+    })
+  }
+  return new A2ClientError(
+    options?.code ?? 'UNKNOWN',
+    error instanceof Error ? error.message : 'client operation failed',
+    { cause: error },
+  )
+}