experimental-a2 0.16.0 → 0.17.0

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

@@ -1,88 +1,47 @@
 ---
-title: Local-first
-description: "Cache one A2 session in the browser: instant revisits, stream resumption, and offline writes."
+title: Client lifetime
+description: "Share an in-memory session, control idle eviction, and resume its event stream."
 ---
 
-## One option
+## Reuse a client
 
-```tsx app/orders/[orderId]/session.ts
+Keep the client in a module so components share session identity, state,
+raw events, pending writes, and connection ownership:
+
+```ts app/session-client.ts
 'use client'
-import { createReact } from 'experimental-a2/react'
-import { indexedDb } from 'experimental-a2/cache-indexeddb'
-import { ordersReducer } from '@/reducer'
+import { createClient } from 'experimental-a2/client'
+import { orders } from '@/contracts'
 
-export const { SessionProvider, useSession } = createReact({
-  reducer: ordersReducer,
-  cache: indexedDb(),
+export const ordersClient = createClient({
+  contract: orders,
+  api: '/api/order-events',
+  gcTime: 5 * 60 * 1_000,
 })
 ```
 
-This is the [session module](/guides/react#the-session-module) from Live
-UI with one addition. The cache is created here, in client code, where
-live objects belong; server components keep importing `SessionProvider`
-exactly as before; nothing crosses the server boundary.
-
-With `cache` set:
-
-- **Revisits paint instantly.** State folds from the local copy before the
-  network says a word. Works offline too.
-- **The stream resumes from the cached frontier.** Reconnects fetch only
-  what this browser hasn't seen, no matter how long it's been.
-- **Pushes queue while offline**, and replay, in order, when the
-  connection returns.
-
-Without it, nothing changes; the provider behaves exactly as before.
-
-## Why this is safe
-
-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({ startAfter })` does anyway. There's no merge function because
-there's nothing to merge.
-
-## What gets stored
+`gcTime` is the idle eviction delay, five minutes by default. Active
+connections, listeners, and pending work keep the runtime alive. Another
+client instance has a separate cache even when it uses the same URL.
 
-Three things, in IndexedDB:
+## Startup and reconnect
 
-| Stored                                        | Invalidated by                                          |
-| --------------------------------------------- | ------------------------------------------------------- |
-| the session's events                          | nothing; they're immutable                              |
-| a folded snapshot, keyed by reducer name | a reducer rename (or a `stateSchema` mismatch, when the reducer declares one): discarded, refolded from cached events |
-| pending pushes                                | the server's ack                                        |
+A new unseeded session receives a snapshot on its event subscription.
+A supplied state/index pair skips that read. A cached session keeps its
+state and resumes after its delivered event position. See
+[Live UI](/guides/react).
 
-Note the middle row: the reducer's `name` does the same job here that it
-does for [server snapshots](/concepts/state#snapshots-are-a-cache). One
-string, both sides of the wire.
+State snapshots bound replay work, not the size of the reducer state or
+raw event collection. Choose reducer contents that fit the application.
 
-Deleting the cache is always safe. It's a replica of what this browser
-already saw; the log on the server stays the only authority.
+## Persistence
 
-## Offline writes
-
-`push` while offline persists the events, client ids and all, and
-applies them optimistically, same as always. On reconnect they replay in
-order. The replay is idempotent by construction: an identical batch is an
-idempotent success, so a flaky reconnect, or a second tab replaying the
-same queue, causes no duplicates. Rejections refold without the event,
-exactly like an online push the server refused.
-
-What this is *not*: local execution. Handlers run on the server, when the
-events arrive. An offline push is a queued intent, not a completed
-action. Design the UI accordingly ("sending…" is honest; "sent" is not).
-
-## Logout
-
-Cached events outlive the session cookie. If your app authenticates,
-clear the cache when the user leaves:
-
-```ts
-// in the browser, wherever your logout flow runs:
-await cache.clear() // everything, or cache.clear(sessionId) for one session
-```
+This cache is in memory. Reloading the page discards it. A2 does not ship
+an IndexedDB adapter or a persistent offline write queue. The
+`experimental-a2/cache-indexeddb` entry point currently has no implementation.
 
-That's the one obligation `cache` puts on you. The cache never *grants*
-access (your routes still authorize every read and write) but it
-*retains* what was legitimately seen, and retained data belongs to the
-person who saw it.
+Pushes have bounded retries and optimistic rollback when they fail.
+Application-owned persistence can restore a state/index pair through the
+normal hydration options. Only restore data belonging to the same session
+and reducer version, and keep authentication and retained-data policy in
+the application.

package/docs/guides/05-production.mdx

@@ -77,11 +77,13 @@ from another client can take up to the idle interval plus query latency to
 arrive after a quiet period.
 
 Prefer Redis? `redis({ url })` from `experimental-a2/store-redis` stores each
-session as a Redis Stream and streams push-natively: writes to watched
-sessions publish a disposable wake-up (sessions nobody watches cost no extra
-command), one shared subscriber connection per process serves every connected
-viewer, and a safety re-read covers a lost wake-up within ten seconds.
-Connections scale with your processes, not with your audience.
+session as a Redis Stream and streams push-natively: every write publishes a
+disposable wake-up, one shared subscriber connection per process serves every
+connected viewer, and a safety re-read covers a lost wake-up within ten
+seconds. Connections scale with your processes, not with your audience. On
+providers that bill per command, such as Upstash, each command a script runs
+counts: appending an event with a handler and running it takes 24 commands,
+and an idle live stream takes 6 a minute.
 `ioredis` is an optional peer dependency; pass `url`, or inject a client.
 Works on single instances and non-cluster providers such as Upstash, where
 durability is on by default. When only a REST API is available,
@@ -89,8 +91,12 @@ durability is on by default. When only a REST API is available,
 same storage over `fetch`. Live events and presence use Upstash’s HTTP
 `SUBSCRIBE` endpoint (SSE), with the same URL and token. Each active channel
 holds one outbound HTTP subscription per store instance, shared by its local
-viewers and closed when the last viewer leaves. Writes to watched sessions
-publish wake-ups inside the same Redis script as the append. Presence writes
+viewers and closed when the last viewer leaves. Writes publish wake-ups inside
+the same Redis script as the append, and each wake-up carries the new events so
+live streams deliver them without another read. Live streams trust those
+messages, so a Redis identity that can publish to the `:notify` channels can add
+or hide live events: grant publish access only to identities that can also
+write the store. Presence writes
 also publish their applied fields inside the script. A rejected notification
 does not fail the applied write. Idle event streams
 read once every ten seconds to recover missed notifications. Subscriptions reconnect automatically and catch up from
@@ -172,29 +178,30 @@ route's protection boundary: Vercel makes the function private, and only queue
 infrastructure can invoke it. Do not expose the callback as an ordinary public
 route or add a second authentication scheme around it.
 
-The adapter pins recovery watchdogs and scheduled appends to the deployment
-that published them. This is the safe default. A recovery task always returns
-to code that understands the session work it armed.
+The adapter uses one queue client for recovery watchdogs, scheduled appends,
+and scheduled clears. Its `deploymentId` setting applies to sends, payload
+fetches, acknowledgements, and visibility changes. Omit it to use the publishing
+deployment, pass a deployment ID to target that deployment, or pass `null` for
+deploymentless delivery. Publishing and consuming clients must use the same
+deployment scope.
 
-You can remove deployment affinity from scheduled appends only:
+Promoting a new deployment does not move pinned tasks. Older deployments keep
+receiving their own work until it is acknowledged or expires. Upgrading does
+not repair an older deployment's callback handler.
 
-```ts
-// server/orders.ts, when every consumer is compatible with pending timers:
-import { vercelQueues } from 'experimental-a2/scheduler-vercel'
-
-export const scheduler = vercelQueues({
-  scheduledAppends: 'deploymentless',
-})
-```
+With `deploymentId: null`, Vercel chooses an eligible deploymentless consumer;
+this does not select the latest production deployment. Every eligible consumer
+must use `deploymentId: null` and remain compatible with pending tasks and
+session work.
 
-`deploymentless` does not mean "latest production." It lets Vercel Queues
-choose an eligible deploymentless consumer for the topic. Keep task envelopes
-and event schemas compatible across every such consumer. Recovery watchdogs
-remain deployment-scoped in both modes. Scheduler task envelopes are
-versioned.
+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.
 
 Vercel Queues defaults to 24-hour message retention. The adapter sets retention
-to 7 days and accepts scheduled appends through 6 days, reserving the final day
+to 7 days and accepts scheduled appends and clears through 6 days, reserving
+the final day
 for delivery and retries. Recovery watchdogs are measured in seconds.
 
 ### QStash
@@ -446,8 +453,11 @@ identity, stale-timer guards, and the full provider limits.
 :::warning
 Do not roll back to an A2 version without timer delivery while scheduled tasks
 are outstanding. New routes accept old recovery messages, but an old route can
-acknowledge a new append task without writing its events. Roll forward, or wait
-for those tasks to deliver or remove them through the provider first.
+acknowledge a new append task without writing its events. The same applies to
+scheduled clears and a version without them: an old Vercel Queues route keeps
+failing a clear task until retention ends, and an old QStash route rejects it
+as non-retryable, so QStash moves it to its dead-letter queue. Roll forward, or
+wait for those tasks to deliver or remove them through the provider first.
 :::
 
 ## 3. When an event dead-letters
@@ -494,6 +504,9 @@ alert on when an event [needs manual
 resolution](#3-when-an-event-dead-letters). See the
 [API reference](/reference/api#a2otel) for the span catalogue.
 
+Agent servers use the same telemetry for `a2.ai.*` spans. Core and AI operations
+can nest and overlap, so their durations do not add up to separate layer totals.
+
 ## Running without a scheduler
 
 If none of a contract's event types have handlers and the app never calls