experimental-a2 0.16.1 → 0.18.0

package/docs/actors/02-concurrency.mdx

@@ -1,50 +1,35 @@
 ---
 title: Concurrency
-description: "Each instance processes one message at a time. Slow work goes in concurrent handlers: they run in parallel and report back by sending events."
+description: "Each instance processes one message at a time. Slow work goes in concurrent handlers, which run in parallel and report back by sending events."
 ---
 
 ## One message at a time
 
-Every message an instance receives runs on its
-[lane](/concepts/handlers#lanes): a serial queue, one handler at a
-time, in arrival order. This is what makes handlers easy to trust. A
-handler always sees the state every previous message produced, its
-checks cannot be raced by another message, and its changes commit
-before the next message runs.
+Every message runs on the instance's [lane](/server/handlers#lanes):
+one handler at a time, in arrival order. A handler sees the state every
+previous message produced, no other message can race its checks, and
+its changes commit before the next message runs.
 
-The lane is per instance. A thousand vaults process in parallel; each
-vault processes in order. If a single instance receives more traffic
-than one queue can absorb, split the identity and give the work more
-instances (per user, per order, per document) instead of trying to
-make one instance concurrent.
-
-## The problem with slow work
-
-A serial handler holds the lane while it runs. If `withdraw` awaits a
-two-second bank API, every deposit waits behind it. The instance stays
-correct, but it stops responding.
-
-The fix is not to weaken the lane. It is to split the work: serial
-handlers make the decisions, concurrent handlers do the slow parts,
-and the results come back as events.
+Lanes are per instance: a thousand vaults process in parallel, each in
+order. If one instance gets more traffic than one queue can absorb,
+split the identity (per user, per order, per document) instead of
+making one instance concurrent.
 
 ## Concurrent handlers
 
-Wrap a handler in `concurrent(...)` and it leaves the lane: it runs in
-parallel with serial handlers and with other concurrent handlers. Two
-things change inside it:
+A serial handler holds the lane while it runs: if `withdraw` awaits a
+two-second bank API, every deposit waits behind it. Keep decisions
+serial and move the slow part into a handler wrapped in
+`concurrent(...)`. It leaves the lane and runs in parallel with serial
+handlers and other concurrent ones. Inside it:
 
-- There is no `ctx.state` draft to mutate. Reading state becomes a
-  function call, `ctx.state()`, and the snapshot it returns can go
-  stale while the handler keeps running.
-- State changes happen by sending events. Their serial handlers run on
-  the lane and decide against current state.
+- `ctx.state()` returns a snapshot, which can go stale while the
+  handler runs. There is no draft to mutate.
+- State changes happen by sending events, whose serial handlers decide
+  against current state.
 
 ## Reserve, transfer, settle
 
-A withdrawal that talks to a slow bank, without ever blocking the
-vault: reserve the money, run the transfer, then settle or refund.
-
 ```ts vault.ts
 import { NonRetriableError } from 'experimental-a2'
 import { actor, concurrent } from 'experimental-a2/actor'
@@ -109,46 +94,34 @@ export const vault = actor<Vault>({
 })
 ```
 
-Step by step:
-
-1. **`withdraw` reserves.** It runs on the lane, so the balance check
-   cannot be raced by another withdrawal. The balance drops, `pending`
-   records the reserved amount, and the `transfer` event commits
-   atomically with both. The withdrawal cannot half-start.
-2. **`transfer` does the slow part.** It runs off the lane, so
-   deposits keep flowing meanwhile. It finishes by sending an event:
-   `settle` on success, `refund` when the bank says no. It never
-   changes state itself, and it reports failure by sending, not by
-   throwing.
-3. **`settle` and `refund` finish the job.** Both check `pending[ref]`
-   first and return when the entry is gone, so a duplicate or late
-   message does nothing. The refund amount comes from state, not from
-   recomputing it.
-
-A crash at any step re-runs that one message from the state it started
-with. Wherever the process dies, the vault lands in a named state:
-reserved, settled, or refunded. Money is never half-transferred.
+1. **`withdraw` reserves** on the lane, so no other withdrawal can race
+   the balance check. The balance drop, the `pending` entry, and the
+   `transfer` event commit atomically: the withdrawal cannot
+   half-start.
+2. **`transfer` does the slow part** off the lane, so deposits keep
+   flowing. It never changes state, and it reports failure by sending
+   `refund`, not by throwing.
+3. **`settle` and `refund` finish.** Both return when `pending[ref]` is
+   gone, so a duplicate or late message does nothing. The refund amount
+   comes from state.
+
+A crash re-runs only that message from the state it started with, so
+the vault always lands reserved, settled, or refunded.
 
 ## Buffered sends
 
-`ctx.send` does not append immediately. Everything a handler sends is
-buffered and commits when the handler completes: for a serial handler,
-in the same commit as its state change; for a concurrent handler, when
-it finishes. A refusal discards the buffer along with the state
-changes, so a refused message leaves no trace. Re-runs produce the
-same message ids, so a retried handler does not append its sends
-twice.
+`ctx.send` buffers. A serial handler's sends commit with its state
+change; a concurrent handler's commit when it finishes. A refusal
+discards the buffer with the state changes, so a refused message leaves
+no trace. Re-runs produce the same message ids, so a retried handler
+never appends its sends twice. `ctx.schedule` is
+[not buffered](/actors/timers#scheduling-is-immediate).
 
 ## When handlers fail
 
-- A **serial** handler that throws `NonRetriableError` refuses the
-  message: nothing commits, and the caller gets the answer (see
-  [Introduction](/actors/introduction#refusals)).
-- A **serial** handler that throws anything else is retried on the
-  lane, and the instance waits. This is deliberate: state never
-  advances past a failure.
-- A **concurrent** handler that throws is retried off the lane;
-  nothing else waits for it.
-- `call` works on serial events only. A concurrent handler produces no
-  answer to wait for, so calling one is rejected: `send` those events
-  instead.
+A concurrent handler that throws retries off the lane, and nothing
+waits for it. Serial handlers fail as described in
+[Refusals](/actors/introduction#refusals).
+
+`call` works on serial events only. A concurrent handler produces no
+answer, so calling one is rejected: `send` those events instead.

package/docs/actors/03-timers.mdx

@@ -5,11 +5,6 @@ description: "Schedule a typed event back to the same instance. Deadlines surviv
 
 ## A deadline is a message, delivered later
 
-`ctx.schedule` mirrors `ctx.send`, one method per declared event, with
-a timing argument: exactly one of `{ delay: '1h' }` or `{ at: date }`.
-It hands the event to the configured scheduler, and delivery lands on
-the instance's lane like any other message.
-
 ```ts escrow.ts
 import { actor } from 'experimental-a2/actor'
 import { vercelQueues } from 'experimental-a2/scheduler-vercel'
@@ -46,38 +41,29 @@ export const escrow = actor<Escrow>({
 })
 ```
 
-Held funds now have two futures, and both are handled: someone accepts
-the offer, or the hour passes and the funds release themselves. The
-deadline is durable: it outlives the invocation that armed it and any
-deploys in between.
+`ctx.schedule` mirrors `ctx.send`, one method per declared event, with
+a timing argument: exactly one of `{ delay: '1h' }` or `{ at: date }`.
+It requires the `scheduler` option. The deadline outlives the
+invocation that armed it and any deploys in between, and delivery lands
+on the instance's lane like any other message.
 
-Scheduling requires the `scheduler` option. Adapters, delay limits, and
-delivery semantics are the session timers underneath; see
-[Timers and delays](/guides/timers).
+Adapters, delay limits, and delivery semantics are the
+[session timers](/server/timers) underneath.
 
 ## Stale timers are no-ops
 
-When `accept` wins the race, the release timer still fires an hour
-later. It meets the same first-line guard the finalizer pattern already
-uses (`held[offerId] === undefined`) and does nothing. When the timer
-wins, a late `accept` meets that guard instead.
-
-There is no cancellation API, and the log records that the timer fired.
-Guarded delivery is the pattern: let the event land, read the state,
-return when it no longer applies. The guard that makes finalizers
-idempotent is the same guard that makes deadlines safe.
+When `accept` wins, the release timer still fires an hour later, meets
+the `held[offerId] === undefined` guard, and does nothing. When the
+timer wins, a late `accept` meets the same guard. There is no
+cancellation API, and the log records that the timer fired: let the
+event land and return when it no longer applies.
 
 ## Identity and retries
 
 A timer's name defaults to the target event's name, scoped to the
-triggering message. A re-run of a crashed handler therefore addresses
-the same timer rather than arming a second one, and provider
-deduplication plus stable event ids fold duplicate deliveries into one
-append. Relative delays anchor to the triggering message's durable
-`createdAt`, so re-runs resolve the same due time.
-
-One handler run gets one timer per target event. To arm several toward
-the same event, name them apart:
+triggering message, so a re-run of a crashed handler addresses the same
+timer instead of arming a second. One handler run gets one timer per
+target event; to arm several toward the same event, name them apart:
 
 ```ts
 // inside a handler:
@@ -87,24 +73,22 @@ await ctx.schedule.release(
 )
 ```
 
+Duplicate deliveries fold into one append, and relative delays anchor
+to the triggering message's `createdAt`; see
+[Identity and retries](/server/timers#identity-and-retries).
+
 ## Scheduling is immediate
 
 :::warning
-Unlike `ctx.send`, `ctx.schedule` is not buffered. A timer lives at the
-provider, not in the log, so it cannot ride the handler's atomic
-commit: the call awaits provider acceptance right where it happens. A
-handler that schedules and then refuses has still armed the timer.
-Guarded delivery makes that safe (the stale timer fires into a no-op),
-but order handlers accordingly: guards and refusals first, `ctx.schedule`
-last.
+Unlike `ctx.send`, `ctx.schedule` is not buffered: a timer lives at
+the provider, not in the log, so the call awaits provider acceptance
+right where it happens. A handler that schedules and then refuses has
+still armed the timer. Guarded delivery makes that safe, but order
+handlers accordingly: guards and refusals first, `ctx.schedule` last.
 :::
 
 ## From outside a handler
 
-The typed surface lives on handler contexts. To schedule from ordinary
-server code, use the instance's underlying session, which takes an
-explicit name, timing, and event:
-
 ```ts
 // anywhere on the server:
 import { escrow } from '@/escrow'
@@ -116,5 +100,7 @@ await escrow.actor('offer-42').session.schedule(
 )
 ```
 
-Root scheduling semantics apply (`{ at }` for retry-stable targets);
-see [Timers and delays](/guides/timers#schedule-from-ordinary-server-code).
+Outside handler contexts, schedule through the instance's session with
+an explicit name, timing, and event. Root scheduling semantics apply
+(`{ at }` for retry-stable targets); see
+[Schedule from ordinary server code](/server/timers#schedule-from-ordinary-server-code).

package/docs/actors/04-routes.mdx

@@ -1,13 +1,10 @@
 ---
 title: Routes, clients, and React
-description: "One route serves an instance: GET streams live state, POST answers calls. Authorize per operation, project per mount, and mount it in React with one hook."
+description: "One route serves an instance: GET streams live state, POST answers calls. Authorize per operation, project per mount, and call it from any client or one React hook."
 ---
 
 ## The actor for this page
 
-A vault with one internal field, so the projection section below has
-something to hide:
-
 ```ts vault.ts
 import { NonRetriableError } from 'experimental-a2'
 import { actor } from 'experimental-a2/actor'
@@ -47,9 +44,6 @@ export const vault = actor<Vault>({
 
 ## The route
 
-`handle.fetch` serves one instance over HTTP. Your route authenticates
-and picks the instance; the library serves the rest.
-
 ```ts app/vault/[vaultId]/route.ts
 import { vault } from '@/vault'
 
@@ -66,33 +60,43 @@ export const GET = respond
 export const POST = respond
 ```
 
-`GET` is the live stream: a server-sent events response of the
-instance's state commits, resumed after the `index` query parameter,
-with heartbeats. The stream carries state and nothing else: subscribers
-see what the actor is, never other callers' inputs, and a refusal
-answers only its caller. The full mailbox stays server-side.
+`handle.fetch` serves one instance; your route authenticates and picks
+which:
 
-`POST` is the call lane. The body names a declared event:
+- **`GET`** streams state commits as server-sent events, resumed after
+  the `index` query parameter, with heartbeats. It carries state and
+  nothing else: subscribers never see other callers' inputs, and a
+  refusal answers only its caller.
+- **`GET ?snapshot=1`** returns the current `{ state, index }`.
+- **`POST`** makes a call and responds with its answer.
+
+A `POST` body names a declared event:
 
 ```json
 { "event": "deposit", "input": { "amount": 100 }, "messageId": "m-1" }
 ```
 
-The response is the answer: `{ state, index }` on success, `409` with
-the refusal's message when the handler says no, `400` for an undeclared
-event. `messageId` is optional; send one to make retrying the request
-idempotent.
+It answers `{ state, index }`, `409` with the refusal's message, or
+`400` for an undeclared event. The optional `messageId` makes retrying
+the request idempotent. Snapshot and call responses use
+`Cache-Control: private, no-store`.
 
-`GET ?snapshot=1` reads the current `{ state, index }` without opening a
-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 a clear
 
-## Authorize
+After `handle.session.clear()`, snapshots, call answers, and stream
+commits include `clearIndex`; keep it in any snapshot you pass to
+`useActor`'s `initial`. The stream then 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.
 
-`authorize` is per-operation policy, checked before any read, write, or
-subscription. Authentication (who is asking) stays in your route;
-`authorize` decides whether this operation is allowed.
+A call cleared before its answer gets `410` with
+`{ code: 'SESSION_CLEARED', error }`, which the actor client raises as
+an `ActorRequestError` with status `410` and the A2 error as its
+`cause`. The handler may already have run, so treat its effects as
+unknown, as after a timeout. A later message reusing the id can't
+answer the cleared call.
+
+## Authorize
 
 ```ts
 // app/vault/[vaultId]/route.ts, now with per-operation policy:
@@ -110,19 +114,17 @@ export async function POST(
 }
 ```
 
-The operation is a discriminated union: `{ type: 'state', id }` for
-snapshot reads, `{ type: 'stream', id, startAfter }` for subscriptions,
-`{ type: 'call', id, event, input,
-messageId? }` for calls. Returning `false` answers `403`.
+Authentication stays in your route; `authorize` decides whether each
+operation is allowed, before any read, write, or subscription.
+Returning `false` answers `403`. The operation is one of:
 
-## Views: what each mount shows
+- `{ type: 'state', id }` for snapshot reads
+- `{ type: 'stream', id, startAfter }` for subscriptions
+- `{ type: 'call', id, event, input, messageId? }` for calls
+- `{ type: 'presence', id, participant, values }` for
+  [presence](#presence) announcements
 
-State can be mixed-audience: internal bookkeeping next to public
-fields. The definition stays audience-blind; audiences are a route
-concern, like auth. A `view` is a request-time projection applied to
-everything that mount serves: snapshots, every state frame on the stream,
-and every call answer (they must agree, or the call lane would leak
-what the stream hides).
+## Views: what each mount shows
 
 ```ts
 // app/vault/[vaultId]/public/route.ts, a projected mount of the same actor:
@@ -139,21 +141,23 @@ export async function GET(
 }
 ```
 
-Different routes project the same actor differently: an admin mount
-with no view sees everything, the public mount above hides `audit`.
-Per-viewer views need no extra machinery, because the route already
-holds the identity; a closure does it
-(`view: (state) => ({ ...visible, mine: state.perUser[user.id] })`).
-View output holds to the same plain-JSON floor as state itself.
+A `view` projects everything its mount serves: snapshots, stream
+frames, and call answers alike, so calls never leak what the stream
+hides. Audiences are a route concern, like auth: an admin mount with no
+view sees everything, and the mount above hides `audit`. For a
+per-viewer view, close over your route's identity:
+`view: (state) => ({ ...visible, mine: state.perUser[user.id] })`. View
+output must be plain JSON, like state.
 
-Views are for internal-but-not-secret fields. Secrets do not belong in
-state at all: state commits are log rows, and the log is forever. Keep
-secrets outside, pass references, resolve them inside handlers.
+Clients of a projected mount pass its shape as the second type argument
+(`createActorClient<typeof vault, PublicVault>` or
+`useActor<typeof vault, PublicVault>`).
 
-## Any client
+Views hide internal fields, not secrets. State commits are log rows,
+and the log is forever: keep secrets outside, pass references, and
+resolve them inside handlers.
 
-`createActorClient` is the typed call surface over that route's `POST`
-lane. It works anywhere: browsers, other frameworks, other servers.
+## Any client
 
 ```ts
 // in the browser, or any client at all:
@@ -175,26 +179,20 @@ try {
 }
 ```
 
-The import of `vault` is type-only, so it is erased at build time: the
-server module never enters a client bundle. On a view-projected mount,
-pass the projected shape as the second type argument
-(`createActorClient<typeof vault, PublicVault>`) so answers carry it.
-
-`client.state()` reads a fresh snapshot. The optional `onSnapshot`
-callback receives successful state reads and call answers before their
-promises resolve. It receives each answer, including older results from
-idempotent retries; consumers compare indexes before replacing live state.
+`createActorClient` is the typed call surface over the route's `POST`,
+for browsers, other frameworks, and other servers. The `vault` import
+is type-only, so the server module never enters a client bundle. `client.state()` reads a fresh snapshot. The optional
+`onSnapshot` callback receives successful reads and call answers before
+their promises resolve, including older results from idempotent
+retries, so compare indexes before replacing live state.
 
-`ActorRequestError` carries an HTTP `status` when available. Network
-failures, timeouts, and server errors do not establish whether a call
-committed. Retry with the same explicit `id` and input to recover its
-original answer. A client does not retry calls automatically.
+`ActorRequestError` carries an HTTP `status` when available. A network
+failure, timeout, or server error doesn't establish whether a call
+committed: retry with the same explicit `id` and input to recover its
+original answer. The client never retries calls automatically.
 
 ## React
 
-One hook. The server component hands down the first fold, the hook
-keeps it live and exposes the same typed calls.
-
 ```tsx app/vault/[vaultId]/page.tsx
 import { vault } from '@/vault'
 import { VaultClient } from './vault-client'
@@ -243,56 +241,34 @@ export function VaultClient({
 }
 ```
 
-What the hook gives you:
-
-- **`state`**: the live view. Call answers and stream commits update it;
-  the fold is library code, so no reducers, schemas, or contracts
-  appear in browser code.
-- **`call`**: the same typed surface as `createActorClient`, because it
-  is one; `useActor` is a thin React wrapper over the client primitive
-  and the stream.
-- **`index`**: the latest adopted state index, and **`events`**: the
-  state-commit feed observed through the stream, starting after the initial
-  snapshot. Call answers and refreshes can advance state before the feed
-  catches up; delayed commits still enter the feed once.
-- **`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
-  watchdog included.
-
-Live, not optimistic. Handlers are server code deciding against
-serialized fresh state, so there is nothing correct for the browser to
-apply early; a local guess would be wrong exactly when the actor
-matters. If a control needs pending UI, `await call.deposit(...)` is a
-promise like any other.
-
-Successful calls update the shared client state before their promises
-resolve. Snapshots only advance state: an older call answer or delayed
-stream frame never replaces a newer state. React renders that update on
-its normal schedule. A call still returns its own answer, even if a newer
-state has already arrived. Refusals do not change state or trigger an
-automatic refresh.
-
-The stream tracks its own position for deduplication and reconnects.
-Adopting a newer snapshot does not skip stream events: delayed commits
-enter `events` without replacing newer state. Events from before the
-initial snapshot are not loaded into this feed.
-
-On a view-projected mount, pass the projected shape as the second type
-argument (`useActor<typeof vault, PublicVault>`); `initial`, `state`,
-and the call answers all carry it.
+The server component hands down the first snapshot; `useActor` keeps it
+live and returns:
+
+- **`state`**: the live view (no reducers, schemas, or contracts in
+  browser code).
+- **`call`**: the same typed calls as `createActorClient`, which the
+  hook wraps.
+- **`index`**: the latest adopted state index.
+- **`events`**: the state commits the stream observed after the initial
+  snapshot. A delayed commit still enters once, even when a call answer
+  or refresh already advanced `state`.
+- **`refresh()`**: reads and adopts a fresh snapshot before resolving.
+  Use it after a refusal or when a suspended tab returns.
+- **`connection`**: the same union as
+  [`useSession`](/client/react#events-and-history), heartbeat watchdog
+  included.
+
+State is live, not optimistic: handlers decide on the server against
+fresh state. For pending UI, await the call.
+
+A successful call updates `state` before its promise resolves (React
+renders on its normal schedule) and returns its own answer, even if
+newer state already arrived. State only advances: an older answer or
+delayed stream frame never replaces newer state. Refusals don't change
+state or trigger a refresh.
 
 ## Presence
 
-Who is here, live: cursors, names, viewer counts. Presence is
-ephemeral audience state. It replicates to the instance's subscribers
-and expires; it never enters the log, and handlers cannot see it (an
-actor decides from its log, never from who is watching).
-
-Declare the vocabulary in the protocol as types, and arm the wire with
-`presence: true`:
-
 ```ts board.ts
 import { actor } from 'experimental-a2/actor'
 
@@ -314,10 +290,12 @@ export const board = actor<Board>({
 })
 ```
 
-The route does not change: the same `GET` stream interleaves presence
-updates between state commits, and the same `POST` lane accepts
-presence announcements. In React, pass a `participant` identity and
-use the map:
+Declare [presence](/client/presence) fields as types in the protocol
+and arm the wire with `presence: true`. Presence replicates to the
+instance's subscribers and expires; it never enters the log, and
+handlers can't see it. The route doesn't change: `GET` interleaves
+presence with state commits, and `POST` accepts announcements. In
+React, pass a `participant` identity and read the map:
 
 ```tsx app/board/[boardId]/board-client.tsx
 'use client'
@@ -353,32 +331,27 @@ export function BoardClient({
 }
 ```
 
-`setPresence` is fire-and-forget: throttled on the way out, resent
-after a reconnect, `null` clears a field. The map holds each
-participant's latest fields with their stamps; how long a value stays
-painted is render logic, decided against `at`.
+`setPresence` is fire-and-forget: throttled, resent after a reconnect,
+and `null` clears a field. The map holds each participant's latest
+fields with their stamps; decide how long to paint a value from `at`.
 
-Three guards stand where presence enters, and none of them is a
-schema:
+Three guards, none of them a schema:
 
 - **Types**: the protocol types `setPresence` and the map, so honest
-  clients cannot send the wrong shape.
-- **The floor**: the library rejects values that are not plain JSON
-  trees, values over 8 KB, and object-plumbing field names.
-- **`authorize`**: every announcement arrives as
-  `{ type: 'presence', id, participant, values }` before it is
-  accepted. Clamp, verify the participant matches the authenticated
-  user, or rate-limit here.
+  clients can't send the wrong shape.
+- **The floor**: A2 rejects values that aren't plain JSON trees, values
+  over 8 KB, and object-plumbing field names.
+- **[`authorize`](#authorize)**: every announcement arrives as a
+  `presence` operation before it is accepted. Clamp, verify the
+  participant matches the authenticated user, or rate-limit here.
 
-What no guard does is make peer values trustworthy. Presence is
-authored by whoever holds a connection: render it like user input.
+No guard makes peer values trustworthy: presence is authored by whoever
+holds a connection, so render it like user input.
 
 ## The session wire underneath
 
-`handle.fetch` serves the actor's two lanes and nothing else. When you
-want the raw session protocol instead (the full event feed, pushes,
-presence, the `ws` transport), the definition exposes the underlying
-server: mount `def.server.fetch` and use the core
-[client](/guides/react) against it. That wire shows the whole mailbox
-to its subscribers, inputs included, so reserve it for trusted
-audiences.
+For the raw session protocol (the full event feed, pushes, presence,
+the `ws` transport), mount `def.server.fetch` as a
+[session route](/server/routes) and use the core
+[client](/client/react). That wire shows the whole mailbox, inputs
+included, so reserve it for trusted audiences.

package/docs/actors/meta.ts

@@ -1 +1 @@
-export default { order: 4 }
+export default { order: 6 }