experimental-a2 0.17.0 → 0.18.0

package/docs/concepts/04-state.mdx

@@ -1,209 +0,0 @@
----
-title: Reading state
-description: "A session's state is a fold over its log: raw history when you want facts, a reducer when you want the current view."
----
-
-## History
-
-```ts
-// anywhere on the server:
-const events = await ordersServer.session(orderId).history()
-```
-
-Everything that happened in this session, oldest first. Always the raw log,
-never a summary, never a snapshot. This is the session's audit trail and
-debugging story, and it is also fine to use inside handlers for questions like
-"did the shop already start?" Pass inclusive `gte` or `lte` indexes to read a
-bounded slice.
-
-## Reducers
-
-For a computed view, derive a reducer from the contract and fold:
-
-```ts contracts.ts
-import { z } from 'zod'
-import * as a2 from 'experimental-a2'
-
-export const orders = a2.contract({
-  name: 'orders',
-  events: {
-    created: z.object({ shopId: z.string(), items: z.array(z.string()) }),
-    'shop.notified': z.object({}),
-    expired: z.object({}),
-  },
-})
-```
-
-```ts reducer.ts
-import { reducer } from 'experimental-a2'
-import { z } from 'zod'
-import { orders } from './contracts'
-
-export const ordersReducer = reducer({ contract: orders,
-    name: 'order-status',
-    initialState: { status: 'new' },
-    stateSchema: z.object({
-      status: z.enum(['new', 'created', 'notified', 'expired']),
-      shopId: z.string().optional(),
-    }),
-   })
-  .fold((state, event) => {
-    switch (event.type) {
-      case 'created':
-        return { status: 'created', shopId: event.payload.shopId }
-      case 'shop.notified':
-        return { ...state, status: 'notified' }
-      case 'expired':
-        return { ...state, status: 'expired' }
-      default:
-        return state
-    }
-  })
-```
-
-```ts
-// anywhere on the server, e.g. a server component before first paint:
-const { state, index } = await ordersServer
-  .session(orderId)
-  .state(ordersReducer)
-```
-
-Handlers receive the same session interface for their triggering session:
-
-```ts server.ts
-import { createServer } from 'experimental-a2/server'
-import { orders } from './contracts'
-import { ordersReducer } from './reducer'
-
-export const ordersServer = createServer({
-  contract: orders,
-  handlers: {
-    created: async ({ session }) => {
-      const { state, index } = await session.state(ordersReducer)
-      void state
-      void index
-    },
-  },
-})
-```
-
-A reducer is a name (its identity, more on that below), `initialState`, an
-optional `stateSchema`, and the pure `fold`, `(state, event) => state`. It is
-derived from the contract, so the events type themselves; the two-step shape
-fixes the state and event types before `.fold()` receives them. No type
-arguments or annotations are needed, and literal unions survive the fold.
-`state()` returns the result with `index`, the last log position included. The
-fold includes every event through that index and none after it. The browser
-resumes its live stream from that boundary. See [Live UI](/guides/react).
-
-A root session reads the latest committed frontier by default. A handler's
-session is causally scoped, so the same call stops at its triggering event:
-
-```ts causal-server.ts
-import { createServer } from 'experimental-a2/server'
-import { orders } from './contracts'
-import { ordersReducer } from './reducer'
-
-export const causalOrdersServer = createServer({
-  contract: orders,
-  handlers: {
-    created: async ({ event, session }) => {
-      const atTrigger = await session.state(ordersReducer)
-      // atTrigger.index === event.index
-
-      const current = await session.state(ordersReducer, {
-        through: 'latest',
-      })
-      void current
-    },
-  },
-})
-```
-
-The trigger boundary is stable across concurrent appends and retries. Use the
-explicit latest read for joins or other logic that intentionally observes later
-events. A numeric `{ through: index }` reads any inclusive log boundary;
-`through: 0` returns `initialState`.
-
-A bounded handler read also keeps that exact folded checkpoint available while
-the triggering event is unfinished. This is automatic. When concurrent work
-advances the reducer's latest snapshot, A2 retains the older checkpoint until
-every handler event using it completes or dead-letters. There is no TTL, history
-limit, or retention setting to tune.
-
-Root reads and handler reads with `{ through: 'latest' }` do not retain
-historical checkpoints. A root numeric read can use an older checkpoint that an
-active handler already retained, but querying an old boundary does not keep it
-around or write a stale snapshot behind the current head. If no suitable
-checkpoint exists, A2 folds the bounded log.
-
-The snapshot and its remaining event tail come back in one consistent store
-operation. A missing snapshot or one rejected by `stateSchema` rebuilds from the
-log. An operational storage-read failure propagates with its backend diagnostics;
-it does not trigger a full-log read. Existing A2 errors pass through, and other
-errors become `STORE_UNAVAILABLE` with the original error as their cause.
-`state()` is observational: it never runs handlers or waits for pending work.
-Its index marks committed history, not handler completion.
-
-A latest read and a following `ctx.session.append(name, ...events)` are separate
-operations. Concurrent appends and retries can move the frontier between them.
-For joins, read with `{ through: 'latest' }`, use a monotone readiness check
-(once ready, always ready), and give the output event a stable explicit `id`.
-Repeated attempts then converge on the same append.
-
-`stateSchema` declares the state's shape once. Without it, the state type
-is inferred from `initialState`, fine while every fold arm returns the
-same shape. With it, the schema is the type (and the seed may lean on its
-defaults), `initialState` is validated at definition, and anywhere A2
-rehydrates folded state instead of refolding raw events, [server
-snapshots](#snapshots-are-a-cache), the [browser
-cache](/guides/local-first): a cached fold that fails the schema is
-discarded and refolded, catching shape drift a stale `name` can't.
-
-Note what these modules import: schemas and `experimental-a2`. Never `experimental-a2/server`,
-never a store backend. Contract and reducer are isomorphic by
-construction; the browser runs the same reducer. More on the split in
-[Live UI](/guides/react#keep-the-backend-out-of-the-bundle). (In a
-server-only app you can keep the contract next to `createServer`
-instead of in its own file.)
-
-## Snapshots are a cache
-
-Folding a long session on every read would get slow, so the store backend
-caches folded state as a snapshot. You never interact with it, except for
-one string.
-
-Each session and reducer has one latest snapshot. Older snapshots exist only
-while unfinished handler events need their exact state boundary. Handler
-completion and dead-lettering release those references in the same store
-operation and remove any historical snapshot with no remaining reader. Several
-handlers can share one checkpoint; it stays until the last reference leaves.
-
-Snapshots are keyed by the reducer's `name`, which makes the name do two
-jobs. It's the identity: two different reducers over the same session
-never fight over a cache entry, because they have different names. And
-it's the invalidation knob. Changed the fold's logic? Change the name (a
-`-v2` suffix works). Snapshots stored under the old name are simply
-ignored; the next read refolds from raw events and caches under the new
-name. That's the entire cache invalidation story: one string.
-
-Snapshot write-back runs in platform `waitUntil` after the state is ready. One
-same-tick group of reads for a reducer and session reads the widest required log
-range once, folds it once, and writes the needed prefixes together. A failed cache
-write does not fail the completed state read. A2 reports it through the
-`a2.snapshot` telemetry span, or `console.error` by default, with session, reducer,
-checkpoint index, and batch count. It does not attach snapshot contents. The next
-read folds the missing tail again.
-
-Deleting every snapshot is always safe. The log rebuilds them.
-
-## Events don't change meaning
-
-The log is append-only, and events are immutable in meaning: `created`
-means forever what it meant when it was written. When a payload needs a new
-shape, add a new event type (`created.v2`) rather than redefining the old
-one.
-
-This is why reducers accumulate switch cases over time, and why they never
-migrate anything: old sessions keep their old events, new sessions write
-new ones, and the same fold handles both.

package/docs/guides/01-timers.mdx

@@ -1,193 +0,0 @@
----
-title: Timers and delays
-description: Schedule a typed session event for later with the same adapter that handles recovery.
----
-
-## Schedule from a handler
-
-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 }) => {
-      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
-    },
-  },
-})
-```
-
-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'
-
-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 })
-}
-```
-
-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, within one session
-lifetime. A [clear](/concepts/contracts#clearing-a-session) frees those ids, so
-a root task redelivered after one appends again. A changed input under
-the same identity conflicts when it produces a different validated event at
-delivery.
-
-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.
-The Vercel adapter pins timers to their publishing deployment by default.
-Cross-deployment compatibility matters when `deploymentId: null` is selected
-or an adapter targets a stable URL, such as QStash.
-
-## Stale timers
-
-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.
-
-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.
-
-## Provider limits
-
-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 |
-
-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
-
-The Vercel adapter's `deploymentId` setting applies to scheduled appends,
-scheduled clears, and recovery watchdogs alike. The default uses the publishing
-deployment. Promoting a new deployment does not move pinned tasks: older
-deployments keep receiving their own work until it is acknowledged or expires.
-
-Use `deploymentId: null` for deploymentless delivery of every task, including
-recovery. Every eligible consumer must use the same setting and remain
-compatible with pending tasks and session work. Deploymentless delivery does
-not select the latest production deployment.
-
-Changing the setting does not move already queued tasks. Keep consumers for
-their original deployment scope until those tasks finish. The former
-`scheduledAppends: 'deploymentless'` option affected only timers; its replacement,
-`deploymentId: null`, also makes recovery deploymentless.
-
-:::warning
-When using deploymentless Vercel delivery or a stable callback URL, do not roll
-back to an A2 version without timer delivery while timer tasks are still outstanding.
-An older route can acknowledge one as a recovery message without
-appending its events. Roll forward, or first wait for the tasks to deliver or
-remove them through the provider.
-:::

package/docs/guides/02-cancellation.mdx

@@ -1,161 +0,0 @@
----
-title: Cancellation
-description: There is no abort() API. Cancelling is appending, and the running handler finds out through a signal.
----
-
-## Cancelling is appending
-
-A user presses stop on a streaming AI response. In A2 that's not a special
-operation with its own machinery. It's an event:
-
-```ts
-// in the browser: push from useSession (see Live UI)
-push({ type: 'cancelled', payload: { lastSeenIndex: index } })
-```
-
-Same route, same auth, same log as every other event. Two things then
-happen, at two different speeds.
-
-## The running handler stops
-
-A handler doing abortable work opts in by naming the events that should
-interrupt it:
-
-```ts server/chat.ts
-import { createServer } from 'experimental-a2/server'
-import { chat } from '@/contracts'
-
-export const chatServer = createServer({
-  contract: chat,
-  handlers: {
-    generate: {
-      abortOn: ['cancelled'],
-      handler: async (ctx) => {
-        // your abortable work; hand it ctx.signal:
-        // await streamText({ signal: ctx.signal, ... })
-      },
-    },
-  },
-})
-```
-
-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
-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:
-
-```ts
-// server/chat.ts, the generate entry, targeted by instance:
-generate: {
-  abortOn: {
-    // only the cancel that names this run fires the signal
-    cancelled: (event, trigger) => event.payload.of === trigger.id,
-  },
-  handler: async (ctx) => {
-    // ...
-  },
-}
-```
-
-The pushing side already knows the id it's cancelling; it's in the
-`events` feed the hook exposes.
-
-Handlers are concurrent by default. A `cancelled` handler may therefore run
-while the interrupted handler is still unwinding. The signal is the
-preemption channel; the event is the durable record.
-
-When cleanup must wait for the interrupted handler, put both event types in
-one lane. The event fires the signal as soon as it is appended, but its own
-handler waits for earlier work in that lane:
-
-```ts server/chat-with-cleanup.ts
-import { createServer } from 'experimental-a2/server'
-import { chat } from '@/contracts'
-
-export const chatServer = createServer({
-  contract: chat,
-  handlers: {
-    generate: {
-      lane: 'generation',
-      abortOn: ['cancelled'],
-      handler: async (ctx) => {
-        // your abortable work; hand it ctx.signal:
-        // await streamText({ signal: ctx.signal, ... })
-      },
-    },
-    cancelled: {
-      lane: 'generation',
-      handler: async () => {
-        // your cleanup, after generate has returned
-      },
-    },
-  },
-})
-```
-
-## The view cuts
-
-Chunks in flight during the cancel round-trip still land in the log after
-`cancelled`. That's correct. They're true history; the model really did
-generate them. Keeping them out of what the user sees is the reducer's job:
-
-```ts reducer.ts
-case 'chunk':
-  return state.cancelled
-    ? state
-    : { ...state, chunks: [...state.chunks, { index: event.index, delta: event.payload.delta }] }
-case 'cancelled':
-  return {
-    ...state,
-    cancelled: true,
-    chunks: state.chunks.filter((c) => c.index <= event.payload.lastSeenIndex),
-  }
-```
-
-`lastSeenIndex` is the client's stream frontier, a number it already
-tracks to resume subscriptions. Cutting on it makes the trim exact and
-clock-free: chunks the log ordered before `cancelled` but the user never
-saw are removed retroactively, so the optimistic view and the
-authoritative refold agree on the same result. No wall clocks, no skew.
-
-And because the client pushes `cancelled`
-[optimistically](/guides/react#events-and-history), its own fold cuts
-instantly. Stragglers still arriving over the stream hit `state.cancelled`
-and vanish from the view.
-
-:::tip
-Keep chunks at per-chunk granularity in state until the session reaches a
-terminal event, then compact them into one string. That's reducer design,
-fully yours.
-:::