experimental-a2 0.2.0 → 0.4.0

package/docs/guides/09-presence.mdx

@@ -0,0 +1,284 @@
+---
+title: Presence
+description: "Ephemeral participant state on a durable session: cursors, typing, live progress. Presence repaints; the log replays."
+---
+
+## Two planes, one session
+
+Everything in the log is a fact: stored forever, folded by reducers,
+replayed on demand. Presence is not a fact. "Her cursor is at (312, 88)"
+has a useful lifetime of about two seconds, no replay value, and no
+durability requirement; a lost update is repainted by the next one.
+
+The test that separates the planes:
+
+> Will anyone, human or reducer, care about this datum after the moment
+> passes? Yes: event, in the log. No: presence.
+
+Messages, document updates, cancellations: events. Cursors, selections,
+typing, "who's online", a handler's live progress: presence.
+
+A2 gives presence its own plane on the session you already have. Same
+contract, same route, same auth, same stream. Each participant owns a
+small ephemeral state; A2 replicates the latest value of each field to
+everyone subscribed and stores none of it in the log. Reducers never see
+it, `history()` never returns it, and the browser cache never persists
+it. One invariant covers the whole design:
+
+> **Presence repaints; the log replays.** Anything that decides (a fold,
+> a retry, an abort match) reads the log. Presence only hurries pixels.
+
+## Declare it in the contract
+
+`presence` is a second vocabulary next to `events`: each key is a field
+of one participant's ephemeral state, each value a schema for it.
+
+```ts contracts.ts
+import { z } from 'zod'
+import * as a2 from 'experimental-a2'
+
+export const canvas = a2.contract({
+  name: 'canvas',
+  events: {
+    'shape.created': z.object({
+      id: z.string(),
+      kind: z.enum(['rect', 'ellipse']),
+      x: z.number(),
+      y: z.number(),
+    }),
+    'shape.moved': z.object({ id: z.string(), x: z.number(), y: z.number() }),
+  },
+  presence: {
+    cursor: z.object({ x: z.number(), y: z.number() }),
+    dragging: z.object({ shapeId: z.string(), x: z.number(), y: z.number() }),
+  },
+})
+```
+
+The field is the unit of replication: last writer wins per participant
+per field. Setting `cursor` does not touch `dragging`. Fields are absent
+until a participant sets them, and clear when set to `null` or when
+their backend TTL lapses (a closed tab disappears by silence, no
+explicit leave required).
+
+## The route
+
+The same two handlers as [Live UI](/guides/react), with one option and
+one branch. `stream({ presence: true })` interleaves presence patches
+with events on the SSE response, starting with a snapshot of the current
+map. The push body grows an optional `presence` sibling to `events`.
+
+```ts app/api/canvas-events/route.ts
+import { A2Error } from 'experimental-a2'
+import { errorResponse, parsePushBody, sseResponse } from 'experimental-a2/http'
+import { canvasServer } from '@/server/canvas'
+
+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 startAfter = Number(searchParams.get('index')) || 0
+
+  // here's where you'd do auth, or any other checks
+
+  return sseResponse(
+    canvasServer.session(sessionId).stream({ startAfter, presence: true }),
+  )
+}
+
+export async function POST(req: Request) {
+  try {
+    const { sessionId, events, presence } = await parsePushBody(req)
+    const session = canvasServer.session(sessionId)
+
+    // here's where you'd do auth, or any other checks; the participant
+    // id is caller-supplied, so authorize it like you authorize events.
+    // createServer's validatePush is the same seam: on the presence
+    // plane it receives { sessionId, events: [], presence }, the whole
+    // patch, participant included
+
+    if (presence) await session.setPresence(presence)
+    if (events.length === 0) return Response.json([])
+    return Response.json(await session.append(...events))
+  } catch (err) {
+    return errorResponse(err)
+  }
+}
+```
+
+`setPresence` validates each field against the contract, then
+broadcasts. No append transaction, no dispatch, no scheduler arm, no log
+row. A bad field throws `INVALID_PAYLOAD`; an unknown field throws
+`UNKNOWN_PRESENCE_FIELD`; nothing is broadcast on either.
+
+## The browser
+
+The provider takes a `participant` id (yours to mint: a user id, a tab
+nonce, the playground's guest name). The hook grows two members. The
+session module is the usual pair from
+[Live UI](/guides/react#the-session-module), bound to a reducer that
+carries the canvas contract:
+
+```ts app/canvas/[canvasId]/session.ts
+'use client'
+import { createClient } from 'experimental-a2/client'
+import { createReact } from 'experimental-a2/react'
+import { canvas } from '@/contracts'
+
+// a minimal scene fold; the real one lives with your reducers
+const sceneReducer = canvas
+  .reducer({ name: 'scene', initialState: {} })
+  .fold((state) => state)
+
+export const canvasClient = createClient({
+  reducer: sceneReducer,
+  api: '/api/canvas-events',
+})
+export const { SessionProvider, useSession } = createReact({
+  client: canvasClient,
+})
+```
+
+```tsx app/canvas/[canvasId]/canvas-client.tsx
+'use client'
+import { useSession } from './session'
+
+export function CanvasClient() {
+  const { presence, setPresence } = useSession()
+
+  return (
+    <div
+      onPointerMove={(e) => setPresence({ cursor: { x: e.clientX, y: e.clientY } })}
+    >
+      {Object.entries(presence).map(([participant, fields]) =>
+        // render-time expiry: a cursor silent for a few seconds is gone
+        fields.cursor && Date.now() - fields.cursor.at.getTime() < 5_000 ? (
+          <Cursor key={participant} {...fields.cursor.value} />
+        ) : null,
+      )}
+    </div>
+  )
+}
+
+// your cursor sprite:
+// function Cursor({ x, y }: { x: number; y: number }) { ... }
+const Cursor = (props: { x: number; y: number }) => null
+```
+
+- **`setPresence(values)`** is fire-and-forget: validated locally,
+  merged into the local map immediately, coalesced on the wire to a
+  fixed cadence. The first set sends immediately; within the interval,
+  later values merge field by field (latest wins, `null` included) and
+  one trailing send carries the merged batch, so a 60Hz pointer becomes
+  about fifteen sends per second and losing one is repainted by the
+  next. Sends may overlap in flight; that is safe because merges are
+  last-writer-wins by `at` per field. No ack, no `confirmed`, no retry,
+  no optimistic rollback: there is nothing to roll back, because
+  nothing was ever true.
+- **`presence`** is the replicated map,
+  `Record<participantId, { [field]: { value, seen, at } }>`, including
+  your own participant. `at` is the sender's stamp for when the value
+  was set, and the last-writer-wins comparator; the client stamps its
+  sends monotonically, so overlapping sends can never invert. How long
+  a cursor stays painted is view logic, decided at render time. Wall
+  clocks never enter folds, and presence is not folded state.
+
+Set a field to `null` to clear it (pointer leaves the canvas, blur,
+unmount). Everything else expires by TTL when a tab goes silent: 60
+seconds by default, set `createServer({ presence: { ttlMs } })` to
+change it. Expiry counts on the backend's clock, not the sender's
+stamp.
+
+Both members are typed from the contract's `presence` map, through the
+reducer, with no type arguments: field names, payloads, and `null`
+clears all autocomplete. On a contract without `presence` the members
+do not exist, so reaching for them is a compile error, not a silent
+no-op. One symptom worth knowing: if the map holds only your own
+echo while others are active, the GET route forgot `presence: true`.
+
+## Reconciling the planes: `seen`
+
+Every presence value carries `seen`, the sender's stream frontier at the
+moment it was set. The client stamps it automatically. This is what lets
+the two planes agree on an order without wall clocks.
+
+The classic race: a participant drags a shape (presence), drops it
+(event), and a stale `dragging` patch arrives after the durable
+`shape.moved`. Without a shared coordinate system the shape flickers
+backwards. With `seen`, superseding is one render-time rule:
+
+```ts
+// in render code: a ghost is dead once the log has moved past it.
+// show fields.dragging only if
+//   fields.dragging.seen >= state.shapes[fields.dragging.value.shapeId].movedAt
+// where movedAt is the index your reducer recorded for the last shape.moved
+```
+
+The durable event at index 214 beats any presence stamped 213 or lower,
+deterministically. A2 carries the stamp and exposes the frontiers; the
+comparison is yours, in view code, next to the pixels it protects.
+
+## Handlers broadcast too
+
+`ctx.session.setPresence` is the same session operation. A handler
+grinding through work can publish live progress without writing
+non-facts to the log:
+
+```ts server/canvas.ts
+import { createServer } from 'experimental-a2/server'
+import { canvas } from '@/contracts'
+
+export const canvasServer = createServer({
+  contract: canvas,
+  handlers: {
+    'shape.created': async (ctx) => {
+      // long work; broadcast progress as it goes:
+      // await ctx.session.setPresence({
+      //   participant: 'system:thumbnails',
+      //   values: { progress: { step: 2, of: 5 } },
+      // })
+    },
+  },
+})
+```
+
+The participant id is the handler's choice; a `system:` prefix keeps
+robots and humans apart in the map. Append the durable outcome as an
+event when the work completes; the progress was never a fact, the result
+is.
+
+## What presence never does
+
+- Never appears in `history()`, `state()`, or a reducer's input type.
+  The separation is structural: presence fields are not events, so a
+  fold cannot reach them even by accident.
+- Never arms the scheduler, takes a claim, or retries. A crashed presence
+  update is a non-event, literally.
+- Never enters the IndexedDB cache. Cache the log, never the moment.
+- Never blocks an append. The planes share a route, not a transaction.
+
+## Backends
+
+Presence needs a broadcast primitive, and backends differ. Declaring
+`presence` in a contract requires a store with the presence capability;
+`createServer` throws `PRESENCE_NOT_SUPPORTED` at construction
+otherwise. All built-in stores have it, at two tiers:
+
+| Backend | Delivery |
+| --- | --- |
+| `store-redis` | push: TTL'd hash plus pub/sub patch, single-digit ms to parked subscribers |
+| `store-memory` | in-process, immediate |
+| `store-postgres`, `store-sqlite`, `store-redis-http` | degraded: bounded TTL'd rows, read on the live feed's poll cadence |
+
+Degraded means later, not lost while watched: presence-only traffic
+surfaces on a fixed 250ms re-read tick plus event wakes; the 25ms
+adaptive floor engages only while events flow. The push tier never
+broadcasts TTL expiry: a participant that departs silently keeps their
+last values in connected clients' maps until those clients reconnect,
+which is why the render-time expiry above is the guard. Cursors want
+the push tier; typing indicators and progress read fine on either. The presence rows are
+bounded per session and participant, so this is not log growth in
+disguise, but on metered backends every patch is still a network
+operation. Presence makes ephemeral state correct, not free.

package/docs/guides/10-transports.mdx

@@ -0,0 +1,131 @@
+---
+title: Transports
+description: "One client, three wires: a single HTTP route, split routes for per-route timeouts, or one WebSocket for both directions."
+---
+
+## One wire seam, same client
+
+Everything the client does is transport-agnostic: optimistic pushes
+with ack and `confirmed`, frontier-resumed live reads, reconnection
+with backoff, the presence throttle and re-send. `api` picks the wire
+underneath it:
+
+```ts
+// in a 'use client' session module:
+api: '/api/order-events'
+api: { type: 'http', push: '/api/order-push', stream: '/api/order-stream' }
+api: { type: 'ws', url: '/api/order-events' }
+```
+
+- **The string** is the default and the recommendation: one route
+  serving GET (SSE stream) and POST (push), one file, one auth surface.
+  Everything else in these docs uses it.
+- **`http` split** serves the two verbs from two routes. Use it when
+  platform duration limits differ per verb: the stream is a long-lived
+  read that wants a high `maxDuration`, the push is a short write that
+  doesn't.
+- **`ws`** rides everything over one WebSocket: the stream comes down
+  it, pushes and presence go up it. Use it when latency or per-message
+  cost matters; at a presence cadence of fifteen sends a second, each
+  send is a socket frame instead of a route invocation.
+
+A split socket is unrepresentable on purpose. The socket is one
+connection in both directions; there is nothing left to split.
+
+## The WebSocket route
+
+The same route can serve both transports by branching on the upgrade
+header. Auth runs before the upgrade, while the request is still a
+request.
+
+```ts app/api/order-events/route.ts
+import { experimental_upgradeWebSocket } from '@vercel/functions'
+import { A2Error } from 'experimental-a2'
+import { errorResponse, sessionSocket, sseResponse } from 'experimental-a2/http'
+import { ordersServer } from '@/server/orders'
+
+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 startAfter = Number(searchParams.get('index')) || 0
+
+  // here's where you'd do auth, or any other checks
+
+  if (req.headers.get('upgrade')?.toLowerCase() === 'websocket') {
+    return experimental_upgradeWebSocket(
+      (ws) => sessionSocket(ordersServer.session(sessionId), ws, { startAfter }),
+      // ws defaults to 100 MiB per frame; POST bodies cap at about
+      // 4.5 MB on the platform. Keep the two ingress paths at parity.
+      { maxPayload: 4 * 1024 * 1024 },
+    )
+  }
+  return sseResponse(ordersServer.session(sessionId).stream({ startAfter }))
+}
+```
+
+`sessionSocket` speaks the whole protocol against any `ws`-shaped
+socket: it pumps the session's stream down as JSON frames, accepts push
+and presence frames up, validates them exactly as `parsePushBody` does
+(same provenance brand, same `validatePush` calls, once per plane), and
+answers each push with its ack. POST keeps working unchanged next to
+it; a `ws` client never calls it, an `http` client never upgrades. The
+transports are additive.
+
+Contracts that declare presence pass `{ presence: true }` in the
+options, the same opt-in as `stream()`.
+
+## The client
+
+```ts app/orders/[orderId]/session.ts
+'use client'
+import { createClient } from 'experimental-a2/client'
+import { createReact } from 'experimental-a2/react'
+import { ordersReducer } from '@/reducer'
+
+export const ordersClient = createClient({
+  reducer: ordersReducer,
+  api: { type: 'ws', url: '/api/order-events' },
+})
+export const { SessionProvider, useSession } = createReact({
+  client: ordersClient,
+})
+```
+
+Nothing else changes. `useSession` is identical, `push` returns the
+same ack and `confirmed`, presence coalesces on the same cadence. The
+connection status, the stall watchdog (two missed heartbeats), and
+reconnection with backoff all behave as they do over SSE, because they
+are the same machinery above the wire seam.
+
+## Lifecycle
+
+A socket closes when the platform ends the function invocation, or
+when the server closes it deliberately ahead of a known deadline. The
+client treats every close the same way it treats a dropped SSE stream:
+reconnect with backoff, resume from the current frontier, receive a
+fresh presence snapshot, re-send its own presence fields set since the
+disconnect. A push whose socket died before the ack rejects as
+retryable: nothing was acknowledged, and if the append had already
+committed, the client-generated event ids make the retry an idempotent
+replay (you get the original events back). Push retries wait for the
+restored socket rather than a fixed clock, capped by the reconnect
+backoff, so a push caught in a routine blip resolves the way it would
+have over HTTP, where pushes never depended on the stream.
+
+On Vercel, WebSocket connections pin to one function instance and new
+connections may land anywhere. A2 never relies on instance affinity:
+the log is the shared state, so two clients on two instances converge
+through it, exactly as they do over HTTP.
+
+## Choosing
+
+SSE plus POST is the right default: simplest route, ordinary HTTP
+semantics, and one auth surface. Reach for `ws` when the send rate
+makes per-request overhead visible (live cursors, drag ghosts) or when
+round-trip latency is the product. Reach for the `http` split only when
+per-route duration configuration forces it. The protocol underneath is
+the same in every case: the log replays, presence repaints, and the
+wire is an implementation detail.

package/docs/index.mdx

@@ -1,6 +1,6 @@
 ---
 title: Introduction
-description: A2 is durable sync and reactions for things with a lifecycle. Append events, run handlers, and keep one live view from server to browser.
+description: A2 is durable sync and reactions for things with a lifecycle. Append or schedule events, run handlers, and keep one live view from server to browser.
 ---
 
 ```bash
@@ -14,8 +14,8 @@ Handlers react to them, and usually return the next one. The browser follows
 the same log and folds the same state as the server. That's the whole model;
 the rest of this page is it happening.
 
-There is no declared state machine. Events record facts, reducers compute the
-current view, and handlers perform the reactions.
+Events record facts, reducers compute the current view, and handlers perform
+the reactions.
 
 ## Define a contract
 
@@ -39,8 +39,7 @@ export const orders = a2.contract({
 
 ## React to events
 
-Handlers are plain async functions: no determinism rules, no replay, no
-wrappers around side effects. Each one reacts to a fact and usually
+Handlers are plain async functions. Each one reacts to a fact and usually
 returns the next one.
 
 ```ts server/orders.ts
@@ -87,9 +86,11 @@ export async function POST(req: Request) {
 }
 ```
 
-That append is durable. The event hits the log before anything else happens,
-then A2 starts its handler inline. In production, queue-backed recovery wakes
-pending work after a crash or timeout.
+A2 commits the event before its handler can start. The handler may begin before
+`append` returns; the return confirms durability, not handler completion.
+A queue-backed scheduler wakes pending work after a crash or timeout. The same
+scheduler lets a session append a typed event later with
+`session.schedule(name, { delay: '30s' }, event)`.
 
 ## State is a fold
 
@@ -168,8 +169,8 @@ twenty lines; [Live UI](/guides/react) wires it end to end.
 
 - **Handlers are plain async functions.** They run concurrently by default.
   Use a lane for selective FIFO execution.
-- **Handlers are optional per event type.** A log-only event settles during
-  append and creates no reaction or recovery work.
+- **Handlers are optional per event type.** A history-only event settles during
+  append and creates no reaction or scheduler work.
 - **History is real.** [`history()`](/concepts/state) returns what
   actually happened, in order. Debugging is reading, not reconstructing.
 - **Nothing inside a session is sacred except its log.** Snapshots, claims, queue
@@ -178,38 +179,12 @@ twenty lines; [Live UI](/guides/react) wires it end to end.
 
 ## FAQ
 
-<details>
-<summary>Why not a workflow engine?</summary>
-
-Workflow engines replay your code from the top on every wake-up. So the
-code has to be deterministic, so every side effect gets wrapped in a step
-function, and `sleep()` becomes something magical instead of something
-you'd never call in a serverless function.
-
-A2's answer is older and simpler: write everything down. Every meaningful
-thing that happens is an event in a log. Handlers are stateless functions
-that react to one event at a time. State isn't stored. It's computed, by
-folding over the log whenever you need it. There's no orchestrator to
-operate.
-
-</details>
-
-<details>
-<summary>Isn't this just event sourcing?</summary>
-
-It's the useful core of it. A log of facts, state as a fold: the idea is
-decades old, and it's a good one. A2 cuts the ceremony that made it a big
-commitment. No command bus, no projection cluster, no upcasting
-framework. A contract, a log, handlers, reducers.
-
-</details>
-
 <details>
 <summary>Can I use A2 without handlers?</summary>
 
 Yes. Omit `handlers` and use `append`, `history`, reducers, and live streams as
 a durable event log. Events settle in their append transaction, with no drain,
-claim, or queue message. A contract can also mix handled and log-only event
+claim, or queue message. A contract can also mix handled and history-only event
 types. A2 decides per event type.
 
 See [Events without handlers](/concepts/handlers#events-without-handlers).
@@ -217,12 +192,12 @@ See [Events without handlers](/concepts/handlers#events-without-handlers).
 </details>
 
 <details>
-<summary>How do I wait five days?</summary>
+<summary>How do I schedule an event for later?</summary>
 
-You don't sleep. You schedule an event. Anything that can deliver an
-HTTP call later (QStash, a cron, a payment provider's webhook) hits a
-route that appends. The scheduled thing is data, a session id plus an
-event, not a suspended function. See [Timers](/guides/timers).
+Configure Vercel Queues or QStash, then call
+`session.schedule(name, { delay: '30s' }, event)` or use `{ at: Date }`. The
+same scheduler route handles recovery and the delayed append. Names and omitted
+event ids stay stable across retries. See [Timers](/guides/timers).
 
 </details>
 
@@ -248,10 +223,11 @@ recovery story behind them.
 <details>
 <summary>What does production need?</summary>
 
-A durable log backend, such as Postgres or Redis. Add queue-backed recovery
-when the contract has handlers. A log-only contract needs no reaction
-infrastructure. Development needs neither: SQLite appears under `.a2/` and
-state survives restarts. See [Going to production](/guides/production).
+A durable store backend, such as Postgres or Redis. Add a queue-backed scheduler
+when the contract has handlers or calls `session.schedule`. A history-only
+contract with no timers needs no reaction infrastructure. Development needs
+neither: SQLite appears under `.a2/` and state survives restarts. See
+[Going to production](/guides/production).
 
 </details>