experimental-a2 0.3.0 → 0.5.0

package/docs/guides/01-timers.mdx

@@ -1,80 +1,185 @@
 ---
 title: Timers and delays
-description: A delayed action is an event delivered later by anything that can make an HTTP call.
+description: Schedule a typed session event for later with the same adapter that handles recovery.
 ---
 
-## Schedule delayed events
+## Schedule from a handler
 
-If something should happen in five days, schedule an HTTP call that appends
-the event then. The scheduler stores the session id and event until delivery.
-
-## Schedule an event
-
-Use any scheduler that can deliver an HTTP call later: QStash, a cron, your
-payment provider's webhook. It hits a route; the route appends.
+Configure one scheduler for the server, then call
+`session.schedule(name, timing, ...events)`. This schedules an `expired` event
+for five days after the durable `created` event:
 
 ```ts server/orders.ts
 import { createServer } from 'experimental-a2/server'
+import { vercelQueues } from 'experimental-a2/scheduler-vercel'
 import { orders } from '@/contracts'
 
+export const scheduler = vercelQueues()
+
 export const ordersServer = createServer({
   contract: orders,
+  scheduler,
   handlers: {
     created: async ({ session }) => {
-      // schedule with anything that can deliver an HTTP call later:
-      // QStash, cron, a provider webhook:
-      //
-      // await scheduleHttpCall({
-      //   delay: '5d',
-      //   url: '/api/append',
-      //   body: { sessionId: session.id, type: 'expired', payload: {} },
-      // })
+      await session.schedule(
+        'expire-order',
+        { delay: '5d' },
+        { type: 'expired', payload: {} },
+      )
+    },
+    expired: async ({ session }) => {
+      const events = await session.history()
+      if (events.some((event) => event.type === 'shop.started')) return
+      // your expiry side effect goes here
     },
   },
 })
 ```
 
-```ts app/api/append/route.ts
+The same scheduler route handles recovery watchdogs and scheduled events. Mount
+it once as shown in
+[Going to production](/guides/production#2-add-a-scheduler-for-handlers-and-timers).
+
+`timing` is exactly one of these shapes:
+
+```ts
+// anywhere on the server:
+type ScheduleTiming =
+  | { delay: `${number}${'ms' | 's' | 'm' | 'h' | 'd'}`; at?: never }
+  | { at: Date; delay?: never }
+```
+
+The template type checks the unit suffix. At runtime, the number must be an
+unsigned base-10 decimal without leading zeros, finite, and greater than zero.
+A2 rejects `0s`, signs, exponent notation, malformed strings, and invalid
+dates.
+
+The requested target is the earliest useful delivery time, not an exact
+execution deadline. Adapters encode provider timing in whole-second slots. A
+target that is already due publishes immediately.
+
+The call awaits provider acceptance and returns `void`. No event enters the
+store until the scheduler delivers the task.
+
+## Schedule from ordinary server code
+
+Root sessions expose the same method. Use `{ at }` when a caller may retry and
+the target time must stay fixed:
+
+```ts app/api/trials/route.ts
+import { z } from 'zod'
 import { ordersServer } from '@/server/orders'
 
-export async function POST(req: Request) {
-  const { sessionId, type, payload } = await req.json()
-  await ordersServer.session(sessionId).append({ type, payload })
-  return Response.json({ ok: true })
+const scheduleTrial = z.object({
+  orderId: z.string(),
+  expiresAt: z.iso.datetime().transform((value) => new Date(value)),
+})
+
+export async function POST(request: Request) {
+  const body = scheduleTrial.parse(await request.json())
+  await ordersServer.session(body.orderId).schedule(
+    'expire-order',
+    { at: body.expiresAt },
+    { type: 'expired', payload: {} },
+  )
+  return Response.json({ scheduled: true }, { status: 202 })
 }
 ```
 
-:::warning
-Auth this route like any other. Anything that can call it can move your
-sessions forward.
-:::
+A root `{ delay: '30s' }` starts from the wall clock captured by that call. A
+retry 10 seconds later calculates a delivery 10 seconds later too. An absolute
+`{ at }` preserves the original target. Inside a handler, relative delays are
+already retry-stable: A2 anchors them to the triggering event's durable
+`createdAt`, not the retry's clock.
+
+## Identity and retries
+
+`name` identifies one logical schedule. On a root session its scope is the
+contract and session. In a handler it also includes the triggering event id, so
+different events can both use a local name such as `expire-order` while retries
+of one event converge.
+
+Keep the same name, timing, and events on every retry. A2 derives stable ids for
+events whose `id` you omit. Provider deduplication folds repeated sends while
+its deduplication window is open. After that window, duplicate deliveries
+still append once because they carry the same event ids. A changed input under
+the same identity conflicts when it produces a different validated event at
+delivery.
+
+A2 does not store a timer-intent registry, so it cannot compare every retry
+with the first call before sending. The stable provider task and event ids are
+the durable convergence mechanism.
+
+## What arrives later
+
+Scheduled payloads travel inside the provider message. Before validation, A2
+snapshots each payload into the same plain JSON tree the provider will deliver.
+Encode a `Date` as an ISO string and a custom class as explicit JSON data. A2
+rejects `undefined`, functions, symbols, bigint values, cycles, accessors, and
+non-plain prototypes. Shared object references become independent JSON values;
+reference identity is not part of a scheduled payload. The task carries that
+snapshotted schema input. At delivery, A2 validates it through
+an ordinary top-level append with fixed ids. A schema transform produces the
+stored payload from that original input, rather than receiving its earlier
+validation output as new input.
+
+That means scheduled events:
+
+- enter the log only when delivered;
+- have `cause: null`, like an ordinary server append;
+- run handlers and lanes normally;
+- update reducers, streams, and live clients normally; and
+- tolerate at-least-once delivery through their stable ids.
+
+If the deployment receiving a timer removes or changes its event schema,
+delivery can fail validation and remain visible as a retrying scheduler error.
+Vercel Queues pins timers to their publishing deployment by default. This
+cross-deployment compatibility concern applies when
+`scheduledAppends: 'deploymentless'` is selected and to adapters that target a
+stable URL, such as QStash.
 
 ## Stale timers
 
-The order shipped on day two. The expiry still fires on day five. Now what?
+The order shipped on day two. Its expiry event still arrives on day five. The
+recommended pattern is the guard in the first example: let the event land, read
+the session, and return when it no longer applies. The log still records the
+fact that the timer fired.
 
-You could hunt down the scheduled call and cancel it. The simpler default,
-and the recommended one, is to let the timer fire and have the handler
-check whether it still applies. Guard on read:
+A2 has no cancellation, reschedule, cron, or timer-listing API. `name` is an
+idempotency key, not a handle. Model repeated schedules as session events and
+have a handler schedule the next occurrence explicitly.
 
-```ts
-// server/orders.ts, the expiry handler, guarding on read:
-import { createServer } from 'experimental-a2/server'
-import { orders } from '@/contracts'
+## Provider limits
 
-export const ordersServer = createServer({
-  contract: orders,
-  handlers: {
-    expired: async ({ session }) => {
-      const events = await session.history()
-      if (events.some((e) => e.type === 'shop.started')) return // stale, ignore
-      // ...actually expire the order
-    },
-  },
-})
-```
+One scheduled task must fit the active provider's maximum delay:
+
+| Adapter | Maximum one-shot delay |
+| --- | --- |
+| Vercel Queues | 6 days |
+| QStash free | 7 days |
+| QStash usage-based | 1 year |
+| QStash fixed | no fixed maximum |
 
-This works because history is truth. The timer doesn't need to know what
-happened after it was scheduled; the handler can just look. The stale
-`expired` event still lands in the log, and that's fine: it's a fact ("the
-timer fired"), and the handler decided it was moot.
+These are provider limits. A2 does not silently split a longer delay into
+several tasks. Vercel Queues retains the message for seven days; A2 reserves
+the final day for delivery and retries instead of making the delay equal the
+message's lifetime. Leave at least one second of margin at a QStash maximum
+because its `notBefore` timestamp uses whole Unix seconds.
+
+## Deploy safely
+
+Vercel Queues pins scheduled appends and recovery watchdogs to their publishing
+deployment by default. `scheduledAppends: 'deploymentless'` removes affinity
+only for timers. Select it only when every eligible consumer for the topic can
+decode pending tasks and validate their events. Recovery remains pinned.
+
+New scheduler routes accept older recovery messages, which supports adapter
+upgrades for schedulers that deliberately cross deployments.
+
+:::warning
+When using deploymentless Vercel timers or a stable callback URL, do not roll
+back to an A2 version without timer delivery while timer tasks are still
+outstanding. An older route can acknowledge one as a recovery message without
+appending its events. Roll forward, or first wait for the tasks to deliver or
+remove them through the provider.
+:::

package/docs/guides/02-cancellation.mdx

@@ -41,10 +41,36 @@ export const chatServer = createServer({
 
 While the handler runs, A2 watches the session's log. The moment a
 `cancelled` event lands (or one already landed before the handler
-started), `ctx.signal` fires. Handlers without `abortOn` pay nothing.
-
-One rule: an aborted handler should catch and return normally. Throwing
-means "retry me", exactly the wrong response to someone pressing stop.
+started), `ctx.signal` fires. Handlers without `abortOn` pay nothing
+for the watch: no subscription is held for them.
+
+Every handler's signal, with or without `abortOn`, also guards the run's
+durable claim. While a handler runs, A2 renews its claim on a heartbeat,
+and a failed renewal retries promptly while the lease can still be saved.
+A short stall is free: blocking the event loop for less than the lease's
+slack costs nothing, because an overdue beat fires the moment the loop
+wakes. If no renewal lands before the lease lapses, the signal fires with
+an `A2Error` reason of code `CLAIM_EXPIRED`. That decision is local (no
+store round trip), so it works even while the store is unreachable, and
+it means: assume a recovery run is taking over, stop external work now.
+If a successor has provably claimed the event, the reason is
+`SUPERSEDED_ATTEMPT` instead; by then a lapsed run's signal has usually
+already fired. A superseded run can no longer write to the log or
+complete; wiring `ctx.signal` into your external calls is what stops it
+from racing its successor outside A2.
+
+The right response depends on the reason, and the default wiring gets
+every case correct: pass `ctx.signal` to your I/O and let the abort
+propagate. A propagated lease abort (`CLAIM_EXPIRED` or
+`SUPERSEDED_ATTEMPT`, which is exactly what `fetch(url, { signal })`
+rejects with) makes A2 surrender the attempt: no completion recorded,
+no failure budget spent, and the event recovers normally. A user
+cancellation (`abortOn`) is the one case to catch and return normally,
+because the stop is the outcome and the completion should count.
+Return normally after a lease abort only when the work is actually
+done: a lapsed run that finished, with no successor claimed yet, still
+completes and its completion counts. Any other throw is a real failure
+and spends the retry budget.
 
 When one session multiplexes work (several generations over its
 lifetime), match by *instance*, not just type, with a predicate:

package/docs/guides/03-react.mdx

@@ -10,9 +10,9 @@ paint, a stream keeps it fresh, and writes apply instantly. One reducer
 produces every one of those views; server and client fold the same log
 with the same function, so they can't disagree.
 
-That's the trick, really. The client doesn't sync state. It syncs events,
-and folds them locally. State sync is a hard problem. An append-only log
-with positions is not.
+That's the trick, really. The client receives one state snapshot and its log
+position, then syncs later events and folds them locally. It does not keep
+synchronizing state. An append-only log with positions is simpler.
 
 This is session sync. The client follows one known session id; it does not
 subscribe to database tables or queries across many sessions. Keep those
@@ -23,52 +23,57 @@ reducer, and the provider + hook it returns.
 
 ## The API route
 
-One file exposes a session over HTTP: `GET` streams events, `POST` appends.
-These are ordinary route handlers; put whatever checks you like in front.
+One call exposes a session over HTTP: `GET` streams events (and serves
+history slices), `POST` appends. `handle` parses each request into an
+intent, runs your hooks, then acts.
 
 ```ts app/api/order-events/route.ts
-import { A2Error } from 'experimental-a2'
+import { handle } from 'experimental-a2/http'
 import { ordersServer } from '@/server/orders'
-import { errorResponse, parsePushBody, sseResponse } from 'experimental-a2/http'
 
-export async function GET(req: Request) {
-  const { searchParams } = new URL(req.url)
-  const sessionId = searchParams.get('sessionId')
-  if (!sessionId) {
-    return errorResponse(new A2Error('INVALID_PAYLOAD', 'missing sessionId'))
-  }
-  const startAt = Number(searchParams.get('index')) || 0
-
-  // here's where you'd do auth, or any other checks
-
-  return sseResponse(ordersServer.session(sessionId).stream({ startAt }))
-}
-
-export async function POST(req: Request) {
-  try {
-    const { sessionId, events } = await parsePushBody(req)
-
-    // here's where you'd do auth, or any other checks
-
-    const result = await ordersServer.session(sessionId).append(...events)
-    return Response.json(result)
-  } catch (err) {
-    return errorResponse(err)
-  }
-}
+export const { GET, POST } = handle(ordersServer, {
+  before({ request, intent }) {
+    // here's where you'd do auth, or any other checks. Every lane
+    // arrives parsed: intent.type is 'stream', 'history', 'push', or
+    // 'ws-upgrade'. Return a Response to refuse, e.g.:
+    // if (!canRead(request, intent)) return new Response(null, { status: 403 })
+  },
+})
 ```
 
-`GET` is the read path. `stream({ startAt })` is a live `AsyncIterable` of
-one session's events starting after a given position, and `sseResponse`
-pipes it into a server-sent events response. Clients pass `index` to resume
-exactly where they left off, after a first paint or a dropped
-connection.
+`GET` is the read path. A plain `GET` is the live stream: a server-sent
+events response of one session's events, resumed after the `index` query
+parameter, so clients pick up exactly where they left off after a first
+paint or a dropped connection. A `GET` carrying `gte`/`lte` query
+parameters is a history slice instead: the bounded log range as JSON,
+the cold read [`loadHistory`](#the-client-component) rides.
+
+`POST` is the write path. The push envelope is validated (garbage
+answers `INVALID_PAYLOAD` before your hooks run), then `append` does the
+rest. The response is the appended events: an ack, not a stream. Thrown
+[`A2Error`s](/reference/errors#over-the-wire) serialize onto the wire so
+the client can branch on the same codes.
+
+Parsing is protocol, hooks are policy. `before` sees every parsed
+intent and short-circuits by returning a Response. `after` runs when the
+library produced an HTTP response and can decorate or replace it. That
+is where caching policy lives, if you want any: `outcome.covered` on a
+history read means the closed range came back fully covered, an
+immutable slice of an append-only log.
+
+```ts
+// app/api/order-events/route.ts, now with response decoration:
+import { handle } from 'experimental-a2/http'
+import { ordersServer } from '@/server/orders'
 
-`POST` is the write path. `parsePushBody` validates the envelope (and
-throws `INVALID_PAYLOAD` on garbage), then `append` does the rest. The
-response is the appended events: an ack, not a stream. `errorResponse`
-serializes any thrown [`A2Error`](/reference/errors#over-the-wire) so the
-client can branch on the same codes.
+export const { GET, POST } = handle(ordersServer, {
+  after({ outcome, response }) {
+    if (outcome.type === 'history' && outcome.covered) {
+      response.headers.set('cache-control', 'private, max-age=31536000')
+    }
+  },
+})
+```
 
 ## The session module
 
@@ -114,16 +119,12 @@ export default async function OrderPage({
   const { orderId } = await params
   const session = ordersServer.session(orderId)
   const { state, index } = await session.state(ordersReducer)
-  const initialEvents = (await session.history()).filter(
-    (event) => event.index <= index,
-  )
 
   return (
     <SessionProvider
       sessionId={orderId}
       initialState={state}
       initialIndex={index}
-      initialEvents={initialEvents}
     >
       <OrderClient />
     </SessionProvider>
@@ -131,12 +132,10 @@ export default async function OrderPage({
 }
 ```
 
-Three props do the heavy lifting. `initialState` is the fold; `initialIndex`
-is its frontier, the log position the fold reflects; `initialEvents` makes
-the raw feed available in the server render too. Reading state before history
-and filtering at the state frontier gives both values one consistent boundary.
-The client opens its stream at exactly that position. Nothing missed, nothing
-folded twice.
+Two props do the heavy lifting. `initialState` is the fold. `initialIndex` is
+its frontier, the log position the fold reflects. The client opens its stream
+after that position. The stream catches up any events appended after the server
+fold, then stays live. No history read is needed to hydrate state.
 (No `reducer` or `api` prop: the provider got both from the shared client.)
 
 ## The client component
@@ -146,7 +145,7 @@ folded twice.
 import { useSession } from './session'
 
 export function OrderClient() {
-  const { state, push, events, index } = useSession()
+  const { state, push } = useSession()
 
   return (
     <button onClick={() => push({ type: 'shop.started', payload: {} })}>
@@ -172,9 +171,29 @@ What the hook gives you:
   live stream delivers the batch back and the view shows server truth.
   `await push(...).confirmed` is "continue once this is real"; two
   `performance.now()` calls around the two awaits are a complete
-  push→ack→stream latency meter.
-- **`events`**: the raw feed `state` is folded from, for UI that wants
-  the log itself: an activity feed, a debug panel.
+  push→ack→stream latency meter. Overlapping calls on the same
+  session still apply immediately, then enter the transport in call
+  order. Controls do not need to wait or disable themselves to preserve
+  that order.
+- **`events`**: the raw events this client has observed or was explicitly
+  seeded with. With only the server snapshot, it begins after `initialIndex`.
+  Use it for UI that wants the log itself: an activity feed, a debug panel.
+  Earlier events are not needed to hydrate `state`.
+- **`loadHistory`**: backscroll. `loadHistory({ before?, limit? })`
+  fetches a bounded slice of the log from below the frontier (the same
+  route, `gte`/`lte` query parameters) and merges it into `events`:
+  deduped, ordered, shared across every handle of the session. By
+  default each call walks backward 50 events at a time from the oldest
+  one loaded. 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;
+  backscrolled events are display data. Calls serialize per session, so
+  a double-tap never fetches the same range twice. The `ws` api has no
+  history lane; `loadHistory` throws a `TypeError` there.
+- **`history`**: backscroll progress, `{ loading, complete,
+  oldestLoaded }`. `complete` means the feed reaches index 1 (or the
+  log is empty): nothing older is left, hide the "load older" button.
 - **`index`**: the stream frontier, the last server-confirmed log
   position. This is the `lastSeenIndex` that makes
   [cancellation](/guides/cancellation) exact.
@@ -204,7 +223,7 @@ is the L2: it survives reloads; the memory runtime does not.
 One detail worth knowing: every push carries a client-generated event id.
 That id is how the ack finds its optimistic entry, and it makes retrying
 a failed `POST` idempotent for free (`push` auto-retries only
-`LOG_UNAVAILABLE`).
+`STORE_UNAVAILABLE`).
 
 Optimistic pushes are also what make [cancellation](/guides/cancellation)
 feel instant: the `cancelled` event folds locally before the server ever

package/docs/guides/04-local-first.mdx

@@ -39,7 +39,7 @@ Local-first is usually hard because it means syncing state, and state
 needs merging. A2 caches an append-only log with server-assigned positions
 instead. A cached event can never be *wrong*; this browser can only be
 *behind*. Catching up is fetching events after an index, which is what
-`stream({ startAt })` does anyway. There's no merge function because
+`stream({ startAfter })` does anyway. There's no merge function because
 there's nothing to merge.
 
 ## What gets stored