experimental-a2 0.17.0 → 0.18.1

package/docs/contract/02-state.mdx

@@ -0,0 +1,142 @@
+---
+title: State
+description: "State is a fold over the log: raw history for facts, a reducer for the current view."
+---
+
+## History
+
+```ts
+// anywhere on the server:
+const events = await ordersServer.session(orderId).history()
+```
+
+Every event in the session, oldest first: always the raw log, never a summary
+or snapshot. Use it for audits, debugging, and handler questions like "did the
+shop already start?" Pass inclusive `gte` or `lte` indexes to read a slice.
+
+## Reducers
+
+Derive a reducer from the [`orders` contract](/contract/events) and fold:
+
+```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)
+```
+
+A reducer is a `name` (its [cache identity](#snapshots-are-a-cache)), an
+`initialState`, an optional `stateSchema`, and a pure `fold`,
+`(state, event) => state`. The two-step shape fixes the state and event types
+before `.fold()`, so you write no type arguments and literal unions survive.
+
+`state()` returns `state` and `index`: the fold includes every event through
+that index and none after. The browser resumes its live stream from there; see
+[React](/client/react).
+
+Without `stateSchema`, the state type is inferred from `initialState`, fine
+while every fold arm returns the same shape. With it, the schema is the type
+(the seed may lean on its defaults), `initialState` is validated at
+definition, and a cached fold that fails the schema, in a server snapshot or
+the [browser cache](/client/react), is discarded and refolded. That catches
+shape drift a stale `name` can't.
+
+Contract and reducer modules import only schemas and `experimental-a2`, so the
+browser runs the same reducer; see [React](/client/react#publish-the-state). A
+server-only app can keep the contract next to `createServer` instead.
+
+## Read boundaries
+
+A root session reads the latest committed frontier. A handler's session stops
+at its triggering event by default, stable across concurrent appends and
+retries:
+
+```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 ({ event, session }) => {
+      const atTrigger = await session.state(ordersReducer)
+      // atTrigger.index === event.index
+
+      const latest = await session.state(ordersReducer, { through: 'latest' })
+      // latest also folds events appended after this one
+    },
+  },
+})
+```
+
+Use `{ through: 'latest' }` for joins or other logic that intentionally
+observes later events. A numeric `{ through: index }` reads any inclusive log
+boundary; `through: 0` returns `initialState`. `state()` is observational: it
+never runs handlers or waits for pending work, and its index marks committed
+history, not handler completion.
+
+A latest read and a following `ctx.session.append(name, ...events)` are
+separate operations, and 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.
+
+## Snapshots are a cache
+
+The store backend caches folded state as snapshots keyed by the reducer's
+`name`, so two reducers over one session never share an entry. Changed the
+fold's logic? Change the name (a `-v2` suffix works). The next read ignores
+the old snapshots, refolds from raw events, and caches under the new name.
+
+A missing snapshot, or one `stateSchema` rejects, rebuilds from the log. A
+storage read failure propagates with its backend diagnostics instead: existing
+A2 errors pass through, and others become `STORE_UNAVAILABLE` with the
+original error as their cause.
+
+Snapshot write-back runs in platform `waitUntil` after the state is ready. A
+failed write doesn't fail the read: A2 reports it through the `a2.snapshot`
+telemetry span (or `console.error` by default) without snapshot contents, and
+the next read folds the missing tail again.
+
+Each session and reducer has one latest snapshot. Older ones exist only while
+handler events that read at their boundary are unfinished (not yet completed
+or dead-lettered). This is automatic: there is no TTL, history limit, or
+retention setting.
+
+Deleting every snapshot is always safe. The log rebuilds them.
+
+## Events don't change meaning
+
+The log is append-only, and `created` means forever what it meant when it was
+written. When a payload needs a new shape, add a new event type (`created.v2`)
+instead of redefining the old one.
+
+Reducers accumulate cases over time and never migrate anything: old sessions
+keep their old events, new sessions write new ones, and the same fold handles
+both.

package/docs/contract/03-sessions.mdx

@@ -0,0 +1,175 @@
+---
+title: Sessions
+description: "A session is one instance of a contract, with its own ordered log, state, and live stream. Collections and queries stay in your database."
+---
+
+```ts
+// anywhere on the server: a route, a handler, a script
+const order = ordersServer.session('order-42')
+```
+
+A session is one instance of the contract (one order, one chat, one import)
+with its own ordered log, state, recovery, and live stream. The id is yours.
+Creating the handle does no I/O; nothing loads until you append, read, or
+stream.
+
+## Pick the boundary
+
+Put events in one session when they form one history, fold, recovery unit, or
+live view. Split what should be read and recovered independently.
+
+A session is not a table or a general query boundary: one `orders` contract can
+serve millions of order sessions through the same server and handlers.
+Collections, joins, search, and constraints across many records belong in
+[your database](#sessions-and-your-database).
+
+## Clearing a session
+
+```ts server/clear-order.ts
+import { ordersServer } from './orders'
+
+export async function clearOrder({ orderId, lastIndex }: {
+  orderId: string
+  lastIndex: number
+}) {
+  // here's where you'd do auth, or any other checks
+  return ordersServer.session(orderId).clear({ ifLastIndex: lastIndex })
+}
+```
+
+`session.clear()` ends a session's current lifetime: its history is gone, every
+reducer is back at its initial state, and the id keeps working for the next
+lifetime. It appends a reserved marker, so indexes never restart: clearing a
+session whose last event is `42` returns `{ cleared: true, index: 43 }`, and the
+next event is `44`.
+
+Pass `ifLastIndex` when newer events must survive. The store checks it in the
+same atomic step that appends the marker; if another event landed first, the
+clear skips and returns `{ cleared: false, index }` with the current head. A
+conditional clear is safe to retry.
+
+The old lifetime's pending events are never dispatched, and a handler still
+running for one can't append, return events, or read the new lifetime's state.
+Clearing can't stop code that is already running or undo its side effects.
+
+Connected clients reset when the marker reaches them. After a clear,
+`session.state()` also returns `clearIndex`: pass the whole result as a client's
+`initial` so a cached client drops its old history too (the automatic snapshot
+on subscribe already carries it).
+
+`clear()` resolves once the old events and cached state are deleted; appends
+and reads keep running meanwhile, and the cost grows with the old history. If
+deletion fails partway, the session is still cleared and the leftovers are
+invisible: retry, or clear again later, to finish. For a very large session,
+prefer a [scheduled clear](#scheduling-a-clear), because the provider retries
+it and each retry resumes the deletion. Presence isn't cleared; it keeps its
+own expiry.
+
+`server.fetch` has no clear endpoint. Clearing is a server operation, so
+authorize your own route before calling it.
+
+### Scheduling a clear
+
+With a [scheduler](/server/production) configured, a handler can schedule a
+clear. This one clears an idle cart a day after its last activity:
+
+```ts server/carts.ts
+import * as a2 from 'experimental-a2'
+import { createServer } from 'experimental-a2/server'
+import { vercelQueues } from 'experimental-a2/scheduler-vercel'
+import { z } from 'zod'
+
+export const carts = a2.contract({
+  name: 'carts',
+  events: {
+    'item.added': z.object({ sku: z.string() }),
+  },
+})
+
+export const cartsServer = createServer({
+  contract: carts,
+  scheduler: vercelQueues(),
+  handlers: {
+    'item.added': async ({ event, session }) => {
+      await session.schedule.clear('idle', {
+        delay: '1d',
+        ifLastIndex: event.index,
+      })
+    },
+  },
+})
+```
+
+The delay counts from the event's stored time. A later event moves the head
+past `event.index`, so this delivery skips and that event's handler schedules
+the next check; only events with a handler extend the policy. A handler's own
+writes move the head too, so one that appends should pass the index its last
+append returned.
+
+Delivery runs the same conditional clear and finishes the deletion before it
+acknowledges, so provider retries complete an interrupted delete. No event is
+appended. The clear happens at delivery, not at an exact deadline, within
+provider limits: Vercel Queues accepts delays up to six days.
+
+## Sessions and your database
+
+A2 does not replace your application database. It syncs one known session at a
+time (its events, derived state, and optimistic browser writes), not tables or
+queries. Give each fact one owner:
+
+- If A2 owns it, append an event and derive state with a reducer.
+- If your database owns it, write it with the database's normal transaction.
+
+Never make both paths authoritative for the same fact.
+
+Use A2 when people open something by id and watch it progress: an order in
+fulfillment, an agent producing a response, an approval waiting for a decision,
+an import that can fail and resume. Use your database when people list,
+filter, join, and edit many records, and for constraints that must hold across
+rows before a request returns.
+
+`experimental-a2/store-postgres` stores A2's own event logs. It does not watch
+your tables, turn their changes into events, or combine an A2 append with your
+SQL transaction. Both can share one Postgres database as separate data models
+and transaction boundaries.
+
+### An issue tracker
+
+Postgres usually owns an issue tracker's core data; A2 sessions own the runs
+attached to it:
+
+| Part | Owner |
+| --- | --- |
+| issues, projects, labels, comments | Postgres |
+| permissions, board filters, search | Postgres |
+| an AI investigation attached to an issue | one A2 session |
+| an import or automation run | one A2 session |
+
+The investigation's session refers to the issue id without becoming a second
+owner of the issue. A2 can own individual issues when their history and live
+state are the center of the product, but boards and search then span many
+sessions and need another query model. Don't put a whole workspace in one
+session for cross-issue queries: every event joins one growing log that every
+client follows.
+
+### Database writes from handlers
+
+Handlers may call your database like any other side effect. They are
+at-least-once, so make the write idempotent with `event.id`; it runs after the
+event is durable and may be retried. That is not one atomic write across A2
+and your tables: if a relational change must commit before the request
+succeeds, make it through the database's write path.
+
+### Cross-session indexes
+
+A handler can maintain a small database index over A2-owned sessions, such as a
+list of active imports. Treat it as an advanced integration:
+
+- it is eventually consistent with the session logs;
+- writes must be idempotent;
+- A2 orders events within one session, not across sessions;
+- no A2 API scans and replays every session to rebuild it.
+
+Back up and migrate it like application data. If search, joins, and
+cross-session reporting are central, the database should probably own that
+domain.