experimental-a2 0.20.0 → 0.22.0

package/docs/server/05-sql-projections.mdx

@@ -0,0 +1,391 @@
+---
+title: SQL projections
+description: Keep tables in your own database from A2's logs with a consumer, so lists, filters, and joins are SQL queries.
+---
+
+## The tables
+
+```ts db/schema.ts
+import { bigint, pgTable, primaryKey, text } from 'drizzle-orm/pg-core'
+
+/** The order list: one row per order. */
+export const orderList = pgTable('order_list', {
+  orderId: text('order_id').primaryKey(),
+  shopId: text('shop_id').notNull(),
+  status: text('status').notNull(),
+})
+
+/** The last event each consumer applied from each session's log. */
+export const positions = pgTable(
+  'positions',
+  {
+    consumer: text('consumer').notNull(),
+    sessionId: text('session_id').notNull(),
+    logIndex: bigint('log_index', { mode: 'number' }).notNull(),
+  },
+  (table) => [primaryKey({ columns: [table.consumer, table.sessionId] })],
+)
+```
+
+```ts db/client.ts
+import { drizzle } from 'drizzle-orm/node-postgres'
+import * as schema from '@/db/schema'
+
+export const db = drizzle({
+  connection: { connectionString: process.env.DATABASE_URL },
+  schema,
+})
+```
+
+A2 keeps each session's log. When people list, filter, and join across
+sessions, read tables in your database instead, kept from the logs by a
+[consumer](/server/consumers): a projection. This page keeps an order list
+with Drizzle on Postgres, as an example. The pattern is the same with any SQL
+database and client.
+
+The order list has a row per order. `positions` has a row per consumer and
+session: the index of the last event that consumer applied to your tables.
+Your migrations create both, like any table. A2's own tables can live in the
+same database; see [Postgres](/stores/postgres#with-drizzle).
+
+## Why a position row
+
+A2 keeps each consumer's cursor, its place in a session's log, in A2's store,
+and moves it after `run` returns. It fences its own writes by attempt: an
+append, a returned batch, or a cursor move from an attempt that lost its claim
+is refused. Your SQL commits in your own transaction, which A2 can't fence or
+make atomic with its cursor. Two things follow:
+
+- **A crash between your commit and the cursor move retries the event.** Your
+  rows are in, the cursor isn't, and A2 runs the event again.
+- **An attempt that lost its claim can still commit.** Its claim lapsed while
+  it ran, a newer attempt applied the event and the ones after it, and then
+  the old attempt commits an older event over newer rows.
+
+The position row fences both. It commits in the same transaction as your rows,
+and a transaction writes only when it moves the position forward, so each
+event lands in your tables once, in log order.
+
+## Claim the event first
+
+```ts server/order-list.ts
+import { eq, lt } from 'drizzle-orm'
+import { consumer } from 'experimental-a2/server'
+import { orders } from '@/contracts'
+import { db } from '@/db/client'
+import { orderList, positions } from '@/db/schema'
+
+const name = 'order-list-v1'
+
+export const orderListTable = consumer({
+  contract: orders,
+  name,
+  lane: 'order-list',
+  backfill: true,
+}).run(async ({ event }) => {
+  await db.transaction(async (tx) => {
+    const claimed = await tx
+      .insert(positions)
+      .values({ consumer: name, sessionId: event.sessionId, logIndex: event.index })
+      .onConflictDoUpdate({
+        target: [positions.consumer, positions.sessionId],
+        set: { logIndex: event.index },
+        setWhere: lt(positions.logIndex, event.index),
+      })
+      .returning({ logIndex: positions.logIndex })
+    // this event, or a later one, is already in:
+    if (claimed.length === 0) return
+
+    if (event.type === 'created') {
+      await tx.insert(orderList).values({
+        orderId: event.sessionId,
+        shopId: event.payload.shopId,
+        status: 'created',
+      })
+    } else {
+      await tx
+        .update(orderList)
+        .set({ status: event.type })
+        .where(eq(orderList.orderId, event.sessionId))
+    }
+  })
+})
+```
+
+The transaction's first statement claims the event. It inserts the session's
+position, or moves it to this event's index if it's behind, and returns the
+row when it did. No row back means this event, or a later one, is already in
+your tables: return, and the transaction changes nothing. Otherwise write your
+rows. They commit with the position, or none of it does.
+
+In plain SQL, it's the same statement on Postgres and SQLite:
+
+```sql
+insert into positions (consumer, session_id, log_index)
+values ($1, $2, $3)
+on conflict (consumer, session_id) do update
+  set log_index = excluded.log_index
+  where positions.log_index < excluded.log_index
+returning 1
+```
+
+It comes first so a duplicate waits before it does any work. On Postgres, at
+the default read committed level, two transactions that claim the same event
+can't both get the row back: the second one's insert waits for the first to
+commit, then checks the condition again against the committed position, finds
+it caught up, and returns nothing. If the first rolls back, the second claims
+the event. Reading the position first with `select ... for update` doesn't
+cover a session's first event: there's no row to lock yet, so both
+transactions read nothing and both apply it.
+
+## The consumer
+
+```ts server/orders.ts
+import { createServer } from 'experimental-a2/server'
+import { postgres } from 'experimental-a2/store-postgres'
+import { orders } from '@/contracts'
+import { orderListTable } from '@/server/order-list'
+
+export const ordersServer = createServer({
+  contract: orders,
+  store: postgres({ connectionString: process.env.DATABASE_URL }),
+  consumers: [orderListTable],
+})
+```
+
+- **A string lane runs a session's events in order.** One at a time, in log
+  order, one transaction each. Sessions run independently.
+- **`backfill` fills it from history.** It reads each session's log from its
+  first event, not only events appended after it exists. A session starts on
+  its next append, or when you [consume](#read-your-writes) it. Nothing
+  enumerates sessions, so to fill the table for orders that never change
+  again, consume each one.
+- **A rebuild is a new name.** See [Rebuild it](#rebuild-it).
+
+## Read it
+
+```ts server/order-list.ts
+export function shopOrders(shopId: string) {
+  return db.select().from(orderList).where(eq(orderList.shopId, shopId))
+}
+```
+
+Lists, filters, and joins are queries against your tables.
+
+## Read your writes
+
+```ts server/place-order.ts
+import { orderListTable, shopOrders } from '@/server/order-list'
+import { ordersServer } from '@/server/orders'
+
+export async function placeOrder(orderId: string, shopId: string) {
+  const order = ordersServer.session(orderId)
+  const [created] = await order.append({
+    type: 'created',
+    payload: { shopId, items: [] },
+  })
+  await order.consume(orderListTable, { through: created.index })
+  // the new order is in the list:
+  return shopOrders(shopId)
+}
+```
+
+Your tables lag the log a little. Before a read that has to include a write
+you just made, [consume](/server/consumers#run-a-consumer-now-with-consume)
+the projection through the index the append returned. It returns once your
+tables have that event.
+
+A consumer that reads your tables waits the same way:
+
+```ts server/receipts.ts
+import { consumer } from 'experimental-a2/server'
+import { orders } from '@/contracts'
+import { orderListTable } from '@/server/order-list'
+
+export const receipts = consumer({
+  contract: orders,
+  name: 'receipts',
+  types: ['shop.notified'],
+}).run(async ({ event, session }) => {
+  await session.consume(orderListTable, { through: event.index })
+  // the order list has this event; read it:
+  // const [order] = await db.select().from(orderList).where(eq(orderList.orderId, event.sessionId))
+})
+```
+
+Pass `event.index - 1` instead when the consumer applies the triggering event
+itself and needs your tables only up to it. A consumer can't consume itself.
+
+`consume` takes the session's lock in A2's store on every call, even when your
+tables are caught up, and while another invocation holds the next event, it
+polls until that one finishes. On a hot path, read your position row first,
+and consume only when it's behind the index you need:
+
+```ts server/read-through.ts
+import { and, eq } from 'drizzle-orm'
+import { db } from '@/db/client'
+import { positions } from '@/db/schema'
+import { orderListTable } from '@/server/order-list'
+import { ordersServer } from '@/server/orders'
+
+export async function readThrough(orderId: string, index: number) {
+  const [position] = await db
+    .select({ logIndex: positions.logIndex })
+    .from(positions)
+    .where(
+      and(
+        eq(positions.consumer, orderListTable.name),
+        eq(positions.sessionId, orderId),
+      ),
+    )
+  if ((position?.logIndex ?? 0) < index) {
+    await ordersServer.session(orderId).consume(orderListTable, { through: index })
+  }
+}
+```
+
+## Live views from the table
+
+```ts server/order-view.ts
+import { and, eq } from 'drizzle-orm'
+import { db } from '@/db/client'
+import { orderList, positions } from '@/db/schema'
+import { orderListTable } from '@/server/order-list'
+
+/** One order's row, and the log index it reflects. */
+export function orderView(orderId: string) {
+  return db.transaction(
+    async (tx) => {
+      const [position] = await tx
+        .select({ logIndex: positions.logIndex })
+        .from(positions)
+        .where(
+          and(
+            eq(positions.consumer, orderListTable.name),
+            eq(positions.sessionId, orderId),
+          ),
+        )
+      const [order] = await tx
+        .select()
+        .from(orderList)
+        .where(eq(orderList.orderId, orderId))
+      return { order, through: position?.logIndex ?? 0 }
+    },
+    { isolationLevel: 'repeatable read' },
+  )
+}
+```
+
+A view of one session can load its rows from your tables and stay live with
+the session's [stream](/client/react). Read the rows and the position in one
+snapshot, a repeatable read transaction on Postgres, and return them together.
+The client follows the stream and applies only the events after `through`, so
+it neither misses an event nor applies one twice.
+
+## SQLite
+
+```ts server/order-list-sqlite.ts
+import { DatabaseSync } from 'node:sqlite'
+import { consumer } from 'experimental-a2/server'
+import { orders } from '@/contracts'
+
+// your migrations create order_list and positions in this file:
+const db = new DatabaseSync('.a2/app.db')
+const name = 'order-list-v1'
+
+const claim = db.prepare(`
+  insert into positions (consumer, session_id, log_index)
+  values (?, ?, ?)
+  on conflict (consumer, session_id) do update
+    set log_index = excluded.log_index
+    where positions.log_index < excluded.log_index
+  returning 1
+`)
+const insertOrder = db.prepare(
+  'insert into order_list (order_id, shop_id, status) values (?, ?, ?)',
+)
+const setStatus = db.prepare(
+  'update order_list set status = ? where order_id = ?',
+)
+
+export const orderListTable = consumer({
+  contract: orders,
+  name,
+  lane: 'order-list',
+  backfill: true,
+}).run(async ({ event }) => {
+  // synchronous from begin to commit, with nothing awaited in between:
+  db.exec('begin immediate')
+  try {
+    if (claim.get(name, event.sessionId, event.index) !== undefined) {
+      if (event.type === 'created') {
+        insertOrder.run(event.sessionId, event.payload.shopId, 'created')
+      } else {
+        setStatus.run(event.type, event.sessionId)
+      }
+    }
+    db.exec('commit')
+  } catch (error) {
+    db.exec('rollback')
+    throw error
+  }
+})
+```
+
+The claim is the same statement. Run the transaction synchronously, from
+`begin immediate` to `commit`, with nothing awaited in between:
+`node:sqlite`'s `DatabaseSync` runs each statement on the calling thread, so
+nothing else runs in the middle, and two of your own transactions never
+interleave on one handle.
+
+It's required when your tables share a file with A2's
+[SQLite store](/stores/sqlite). A2 writes on the same thread, through its own
+handle, and SQLite lets one writer hold a file at a time. If your transaction
+awaited while it held the file, an A2 write to it would block the thread on
+A2's five-second busy timeout, and your transaction couldn't reach `commit`
+until that write gave up.
+
+## Throughput and lag
+
+A string lane runs a session's events one at a time, one transaction each, so
+a projection keeps up with a session as long as its transactions outpace that
+session's appends. In the playground's a2slack drills, with Redis and Postgres
+on the same machine, the feed projection, which keeps a whole workspace in one
+session, ran an event in about 0.4 ms and rebuilt at about 1,800 events a
+second. Posting 10,000 messages in under a second put it up to about six
+seconds behind. A remote database adds at least a round trip to every event.
+
+Watch it with each `a2.event` span's `a2.event.lag`, how many events the
+session had appended after the one it claimed, and `a2.event.age_ms`, how old
+that event was when its run started, grouped by `a2.event.consumer`. See
+[Telemetry](/reference/telemetry#the-span-catalogue). When a session's appends
+keep outrunning its projection, keep each transaction to the claim and your
+writes, and do slower work, like calling an API, in a consumer of its own.
+
+## Rebuild it
+
+To change what a projection writes, or to fill it again, give its consumer a
+new name, such as `order-list-v2`. A new name is a new consumer: it has no
+cursors in A2 and no rows in `positions`, and `backfill` fills it from each
+session's first event, as each session next runs.
+
+Point it at new tables, created by the migration that ships it, and switch
+your reads to them once it has caught up. A deployment still running
+`order-list-v1` keeps writing to the old ones until it's gone. To reuse the
+old tables instead, truncate them, along with the old name's rows in
+`positions`, in a migration that runs once no deployment runs the old name:
+an earlier deployment that still does keeps writing to tables you emptied.
+
+## Point in time
+
+The order list holds each order as of its latest event. To read one as of an
+earlier index, such as next to an old event, keep a versions table too: a row
+per event, keyed by session and log index, written in the same transaction as
+the rest. The row as of index N is the newest at or below it:
+
+```sql
+select status from order_versions
+where order_id = $1 and log_index <= $2
+order by log_index desc
+limit 1
+```

package/docs/server/06-guarantees.mdx

@@ -1,61 +1,68 @@
 ---
 title: Guarantees
-description: Appends are effectively-once, handlers are at-least-once, and retries keep event identity across crashes.
+description: Appends are effectively-once, consumers are at-least-once, and retries keep event identity across crashes.
 ---
 
 ## In short
 
-- **Appends are effectively-once.** Event ids deduplicate writes. A batch commits
-  before its handlers start; they may start before `append` resolves.
-- **Handlers are at-least-once.** They may run again after a crash, so
-  [side effects use idempotency keys](/server/handlers#handlers-can-run-twice).
+- **Appends are effectively-once.** Event ids deduplicate writes within a
+  session. A batch commits before its consumers start; they may start before
+  `append` resolves.
+- **Consumers are at-least-once.** They may run again after a crash, so
+  [side effects use idempotency keys](/server/consumers#consumers-can-run-twice).
 - **The log stays ordered.** Every session has one immutable append order.
-- **Handlers are concurrent by default.** Log order does not serialize them.
-  Only events in the same lane run one at a time in log order.
+- **Consumers are concurrent by default.** Log order does not serialize them.
+  Only events in the same lane of one consumer run one at a time in log order.
+- **Every consumer keeps its own place.** One consumer's failures, retries, and
+  dead letters never hold up another.
 
 ## One event, many attempts
 
-An event is pending until A2 marks it processed. Every wakeup (an append, a
-scheduler watchdog, or `server.drain()`) claims the session's eligible events,
-and the log decides what remains. Reads never dispatch handlers.
+A consumer keeps a durable cursor in every session: where it has gotten to,
+and the event it runs next, its head. An event is pending for a consumer until
+that consumer's cursor moves past it. Every wakeup (an append, a scheduler
+watchdog, or `server.drain()`) claims the session's eligible heads, and the
+cursors decide what remains. Reads never dispatch consumers.
 
 Each claim expires. If its holder dies, the claim lapses and the next wakeup
-claims the event again with a larger `ctx.attempt`. The retry gets the same
+claims the head again with a larger `ctx.attempt`. The retry gets the same
 event id, index, type, and payload. A kill after the claim can use up an
-attempt before your code runs, and that attempt counts toward the event's
-[failure budget](#when-a-handler-keeps-failing). An older attempt can never
+attempt before your code runs, and that attempt counts toward the head's
+[failure budget](#when-a-consumer-keeps-failing). An older attempt can never
 overwrite a newer one's completion or failure.
 
 :::note[Recovery is not an event]
 A2 does not append `recovered` or `continued`. Recovery retries the same event.
-Your log contains only application facts.
+Your log contains only application facts; cursors live beside it.
 :::
 
 ## Immediate and dependent events
 
-[`ctx.session.append(name, ...events)`](/server/handlers#append-what-should-happen-now)
+[`ctx.session.append(name, ...events)`](/server/consumers#append-what-should-happen-now)
 commits immediately: its events stay in the log if the parent later crashes,
 and run concurrently with it unless both share a lane.
-[Returned events](/server/handlers#return-what-happens-after-success) commit
-with the parent's completion, in one transaction.
+[Returned events](/server/consumers#return-what-happens-after-success) commit
+with the cursor's advance past the parent, in one transaction.
 
-If the handler throws or dies before that transaction, neither the completion
+If `run` throws or dies before that transaction, neither the completion
 nor the returned events exist, and the retry produces the same deterministic
 ids. If the transaction commits but its acknowledgement is lost, the retry gets
 the committed rows back. A partial or changed batch is rejected.
 
 The transaction covers only A2's log. An HTTP call, database write, or other
 external effect can't join it, so a crash after the effect but before
-completion repeats it. Use `event.id` as an idempotency key or add fencing in
-the external system.
+completion repeats it. Use `event.id` as an idempotency key, with the session
+when ids can repeat across sessions (see
+[Consumers can run twice](/server/consumers#consumers-can-run-twice)), or add
+fencing in the external system.
 
 ## Lanes
 
-[Lanes](/server/handlers#lanes) are session-scoped serial groups. Only the
-lowest-index unfinished event in a lane is eligible, so a failure blocks later
-events in that lane, not the whole session. Unlaned events and different lanes
-run concurrently. A2 stores the lane at append, so a changed lane resolver
-affects only new events.
+[Lanes](/server/consumers#lanes) are serial groups of one consumer in one
+session. Only the lowest-index unfinished event in a lane is eligible, so a
+failure blocks later events in that lane, not the whole session and not other
+consumers. Unlaned events and different lanes run concurrently. A2 stores each
+consumer's lane at append, so a changed lane resolver affects only new events.
 
 A lane controls A2 dispatch, not the outside world. A2 claims every eligible
 event, with no global concurrency limit or priority queue. Put capacity limits
@@ -64,55 +71,57 @@ runtime.
 
 ## Append and scheduling
 
-A top-level append commits before any wakeup. A2 then starts the handlers
-inline and, with a scheduler, arms a watchdog in parallel. Handlers never wait
-for the queue, and a handler may start before `append` returns. `append` waits
-up to two seconds for the watchdog send, never for handlers. A failed arm
-records `a2.append.armed = false` on the trace. Handler appends and returned
-events join the running drain and add no arm.
+A top-level append commits before any wakeup. A2 then starts the consumers
+inline and, with a scheduler, arms a watchdog in parallel. Consumers never wait
+for the queue, and one may start before `append` returns. `append` waits up to
+two seconds for the watchdog send, never for consumers. A failed arm records
+`a2.append.armed = false` on the trace. Consumer appends and returned events
+join the running drain and add no arm.
 
 [`append.dispatch`](/schedulers/overview#dispatch-in-a-fresh-invocation) skips
 the inline drain and hands the work to the scheduler instead.
 
-An event type without a handler settles in the append transaction. It starts
-no drain or arm unless older handled work in the session is still pending.
+An event no consumer takes starts no work. It starts no drain or arm unless
+older work in the session is still pending. A dead letter is not pending: it
+waits for a redrive, which wakes the session itself.
 
 ## Causal trees are durable
 
-Every event a handler appends or returns stores a `cause`: the triggering
-event's index and dispatch attempt. Top-level appends store `null`. Children
-of one handler are siblings, nested handlers add levels, and a retried child
-keeps its original cause.
+Every event a consumer appends or returns stores a `cause`: the consumer, its
+lane, the triggering event's index, and the attempt. Top-level appends store
+`null`. Children of one run are siblings, nested runs add levels, and a
+retried child keeps its original cause.
 
 ## A chain that crosses the function timeout
 
-A function killed mid-handler restarts that handler from its entry point in a
-fresh invocation: same event, new attempt. Events already processed stay
-processed, so a chain of handlers can outlast one invocation, but each handler
+A function killed mid-run restarts that consumer's `run` from its entry point
+in a fresh invocation: same event, new attempt. Events a cursor already moved
+past stay done, so a chain of events can outlast one invocation, but each run
 must fit in a fresh one: an attempt that runs out of time is a failed attempt,
-and a handler that never fits dead-letters after ten. Split longer work into
+and a run that never fits dead-letters after ten. Split longer work into
 smaller events or increase the function duration. On Vercel, A2 caps the claim window
 at the function deadline when the platform exposes it, so a retry starts
 promptly after a timeout. Once the deadline passes, A2 claims nothing more in
 that invocation, so a timeout costs the event one attempt.
 
-## When a handler keeps failing
+## When a consumer keeps failing
 
-A caught failure counts against that event, releases its claim, and leaves
-other eligible events running. A2 holds it back for a delay that starts at
+A caught failure counts against that consumer's head, releases its claim, and
+leaves other eligible heads running. A2 holds it back for a delay that starts at
 one second and doubles with each failed attempt up to 30 seconds, then retries
 it on the session's next wake. With a scheduler, that's a few seconds at first,
 then the delay itself. An attempt that ends before it finishes, because its
 process timed out, crashed, or lost its claim, counts too, once the next
-attempt takes its claim over. Ten failed attempts dead-letter the event: later
-events in its lane stay blocked, while unlaned events and other lanes continue.
+attempt takes its claim over. Ten failed attempts dead-letter the event for
+that consumer: later events in its lane stay blocked, while unlaned events,
+other lanes, and other consumers continue.
 A crash costs every event it interrupts one attempt, so a session whose work
 keeps outrunning its function dead-letters: bound its fan-out, or put work that
 waits on the same resource in one lane. A `NonRetriableError`, or a returned
 batch the store refuses because it reuses an event id, dead-letters the event
 on that first attempt instead: a retry would fail the same way. The event
 waits until you
-[retry or skip it](/server/handlers#resolve-a-dead-letter) with
+[retry or skip it](/server/consumers#resolve-a-dead-letter) with
 `session.redrive()`.
 
 ## Limits
@@ -123,13 +132,14 @@ waits until you
 | No scheduler configured | A later top-level append or explicit `drain()` wakes the session. Reads never do. |
 | Scheduler invocation dies after claiming but before arming | Its unacknowledged queue delivery is the slower fallback. |
 | Store backend unavailable | Safe progress stops until it returns. |
-| External effect succeeds before A2 completion | The handler may repeat it. Use idempotency or external fencing. |
+| External effect succeeds before A2 completion | The consumer may repeat it. Use idempotency or external fencing. |
 
 ## What append never throws for
 
-A failing handler never makes `append` throw. Handler failures are retried and,
-if persistent, [dead-letter the event](#when-a-handler-keeps-failing).
+A failing consumer never makes `append` throw. Its failures are retried and,
+if persistent, [dead-letter the event](#when-a-consumer-keeps-failing) for
+that consumer.
 
-Append success means the event is durable, not that its handlers finished. An
+Append success means the event is durable, not that its consumers finished. An
 identical batch retry returns rows with the same ids. A mixed batch throws
 [`PARTIAL_DUPLICATE_BATCH`](/reference/errors).

package/docs/stores/01-overview.mdx

@@ -11,9 +11,9 @@ import { orders } from '@/contracts'
 export const ordersServer = createServer({
   contract: orders,
   store: redis({ url: process.env.REDIS_URL }),
-  handlers: {
+  consumers: [
     /* ... */
-  },
+  ],
 })
 ```
 
@@ -34,4 +34,4 @@ A store holds A2's session histories. It doesn't connect A2 to your
 application tables; see
 [Sessions and your database](/contract/sessions#sessions-and-your-database).
 
-Servers with handlers or timers also need a [scheduler](/schedulers/overview).
+Servers with consumers or timers also need a [scheduler](/schedulers/overview).

package/docs/stores/02-redis.mdx

@@ -11,9 +11,9 @@ import { orders } from '@/contracts'
 export const ordersServer = createServer({
   contract: orders,
   store: redis({ url: process.env.REDIS_URL }),
-  handlers: {
+  consumers: [
     /* ... */
-  },
+  ],
 })
 ```
 
@@ -21,9 +21,9 @@ export const ordersServer = createServer({
 npm i ioredis
 ```
 
-Works on a single Redis instance and on non-cluster providers such as Upstash,
-which is durable by default (use its TCP `rediss://` URL). There's nothing to
-set up: A2 creates its keys as it writes.
+Works on a single Redis or Valkey instance and on non-cluster providers such as
+Upstash, which is durable by default (use its TCP `rediss://` URL). There's
+nothing to set up: A2 creates its keys as it writes.
 
 ## Options
 
@@ -31,19 +31,33 @@ set up: A2 creates its keys as it writes.
 | --- | --- |
 | `url` | creates an `ioredis` client |
 | `client` | your own `ioredis` client instead |
-| `keyPrefix` | isolates several apps on one Redis. Default `'a2'` |
+| `keyPrefix` | isolates several apps on one Redis. Default `'a2'`; no braces |
 | `clock`, `ids` | test seams for timestamps and generated event ids |
 
+## Upgrade
+
+The store records its key layout in `<keyPrefix>:schema`, and refuses a prefix
+marked with another one with `STORE_NOT_CONFIGURED`. A release that changes
+the layout says what to do on its [upgrade page](/upgrades/overview). This
+release names every key differently from earlier ones, so give the store a
+fresh `keyPrefix`.
+
 ## How it works
 
-- Each session is a Redis Stream.
-- Every write publishes a wake-up, so live streams are push-driven, and
-  connections scale with your processes, not with your viewers.
+- Each session is a Redis Stream, and every key of a session shares one hash
+  tag.
+- Every write is one atomic script over its session's keys. On Upstash, which
+  runs a script under a database-wide lock by default, A2 marks each script to
+  lock only its session's keys. Redis and Valkey run one command at a time, so
+  A2 keeps scripts short instead.
+- Every write publishes a wake-up after its script, so live streams are
+  push-driven, and connections scale with your processes, not with your
+  viewers.
 - A wake-up is disposable: a safety re-read recovers a lost one within ten
   seconds.
 
 ## Cost per command
 
 On providers that bill per command, such as Upstash, appending an event with a
-handler and running it takes 24 commands, and an idle live stream takes 6 a
+consumer and running it takes 19 commands, and an idle live stream takes 6 a
 minute.