experimental-a2 0.17.0 → 0.18.1

package/docs/guides/08-application-data.mdx

@@ -1,113 +0,0 @@
----
-title: A2 and your database
-description: Use A2 for things with a lifecycle. Keep collections, relationships, and queries in your application database.
----
-
-## Start with ownership
-
-A2 does not replace your application database. It synchronizes one known
-session at a time: its events, its derived state, and optimistic writes from
-the browser. It does not synchronize tables or database queries.
-
-Use your database for the records and relationships that the rest of the
-application queries.
-
-Decide which system owns each fact:
-
-- If A2 owns it, append an event and derive the session's state with a reducer.
-- If your database owns it, write it with the database's normal transaction.
-
-Do not make both paths authoritative for the same fact.
-
-## What belongs in A2
-
-A2 fits something with a lifecycle: an order moving through fulfillment, an
-agent producing a response, an approval waiting for a decision, or an import
-that can fail and resume.
-
-A **contract** names the events in one kind of lifecycle. A **session** is one
-instance of it:
-
-```text
-orders / order-42
-orders / order-43
-agents / run-abc
-```
-
-The session is the boundary A2 logs, recovers, folds, and streams. Put events
-in the same session when they form one history or view. Handler execution is
-concurrent unless events share a lane.
-
-A contract is not a table. A session is not a table either. One contract
-usually serves many sessions, and one session may describe changes that touch
-several records elsewhere in an application.
-
-## What belongs in the database
-
-Use your application database for collections and relationships: accounts,
-projects, issue lists, labels, permissions, search, joins, pagination, and
-reporting. Use its transactions for constraints that must hold across several
-rows before a request returns.
-
-The Postgres adapter in `experimental-a2/store-postgres` stores A2's own event logs. It does not
-watch your application tables, turn their changes into events, or combine an
-A2 append with your SQL transaction. The A2 log and your tables may share one
-Postgres database, but they remain separate data models and transaction
-boundaries.
-
-## An issue tracker
-
-An issue tracker is mostly a collection and query product. Postgres should
-usually own its core data:
-
-| 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 A2 session can store the investigation's messages, progress, tool calls,
-approval, and result. It refers to the issue id, but it does not become a
-second owner of the issue.
-
-An individual issue also has a lifecycle, so A2 can own it when the issue's
-ordered history and live state are the center of the product. That choice has
-a cost: boards and search span many sessions and need another query model. If
-those collection views are the center of the product, let the database lead.
-
-Do not put an entire workspace in one session just to make cross-issue queries
-possible. Every event joins the same growing log and every client follows it.
-
-## 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`. The event is
-durable before the handler runs, and the SQL write may happen later or be
-retried.
-
-That is a good fit for a reaction to a lifecycle event. It is not one atomic
-write across A2 and your tables. If a relational change must commit before the
-request succeeds, make that change through the database's write path.
-
-## Cross-session indexes
-
-Sometimes an A2-owned lifecycle needs a small database index, such as a list of
-active imports. A handler can maintain that index. Treat it as an advanced
-integration:
-
-- it is eventually consistent with the session logs;
-- writes must be idempotent;
-- A2 assigns log order within one session, not across sessions;
-- A2 does not expose one API that scans and replays every session to rebuild
-  the index.
-
-Back up and migrate that index like application data. If search, joins, and
-cross-session reporting are central rather than incidental, the database
-should probably own that domain.
-
-## The short version
-
-Use A2 when people open something by id and watch it progress. Use your
-database when people list, filter, join, and edit many records. In an
-application that needs both, split ownership along that line.

package/docs/guides/09-presence.mdx

@@ -1,262 +0,0 @@
----
-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() }),
-  },
-  reducer: { name: 'scene', initialState: {}, fold: (state) => state },
-  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 `server.fetch` route as [Live UI](/guides/react). Presence is
-inferred from the contract. A contract with presence fields streams
-presence patches with events, starting with a snapshot of the current
-map. Its push body also accepts an optional `presence` sibling to
-`events`, forwarded to `setPresence`.
-
-```ts app/api/canvas-events/route.ts
-import { canvasServer } from '@/server/canvas'
-
-export const GET = canvasServer.fetch
-export const POST = canvasServer.fetch
-```
-
-Wrap `server.fetch` when the route needs authentication. Pass
-`authorize` to check the typed A2 operation before field validation or
-I/O. A push operation carries the complete presence patch, including
-its caller-supplied participant id. The same hook runs for HTTP and
-WebSocket presence.
-
-`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. A
-presence-only push acks `[]`.
-
-## The browser
-
-Presence needs a `participant` id (yours to mint: a user id, a tab
-nonce, the playground's guest name). State it once on
-`createClient({ participant })` when the app knows it at module scope,
-or pass it to the provider, whose `participant` prop overrides the
-client's. The hook grows two members. The
-session module is the usual pair from
-[Live UI](/guides/react#bind-react-once), 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'
-
-export const canvasClient = createClient({
-  contract: canvas,
-  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.
-
-## 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 patches |
-| `store-redis-http` | push over HTTP subscriptions; adaptive polling when unsupported |
-| `store-memory` | in-process, immediate |
-| `store-postgres` | native notifications with `listenConnectionString`; adaptive polling by default |
-| `store-sqlite` | degraded: bounded TTL'd rows, read on the live feed's poll cadence |
-
-Degraded means later, not lost while watched: presence-only traffic
-uses an adaptive re-read cadence, starting at 25ms and backing off to two
-seconds while unchanged. New presence patches or durable events restore the
-fast cadence. An idle remote viewer may wait up to two seconds plus query
-latency for the first change. Redis Pub/Sub does not proactively broadcast
-TTL expiry. Silent departures keep their last values in connected clients'
-maps until a snapshot reconciles them, so use the render-time expiry above.
-Native Postgres subscriptions reconcile missing or expired fields on their
-ten-second safety reads. 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

@@ -1,221 +0,0 @@
----
-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, and presence throttling. `api` picks the wire underneath
-it:
-
-```ts
-// in a 'use client' session module:
-api: '/api/order-events'
-api: (sessionId) => `/api/orders/${encodeURIComponent(sessionId)}/events`
-api: { type: 'http', push: '/api/order-push', stream: '/api/order-stream' }
-api: { type: 'ws', url: '/api/order-events' }
-```
-
-- **One route** is the default and the recommendation. Pass a fixed URL or a
-  session URL function. It serves GET (SSE stream and history) and POST (push).
-- **`http` split** serves the two verbs from separate routes. Use it
-  when platform duration limits differ per verb.
-- **`ws`** rides streams, pushes, and presence over WebSocket. It opens
-  one socket per session. Set `multiplex: true` on the client and
-  `multiplexWebSocket: true` on the route to share one socket across the
-  client's sessions.
-
-A split socket is unrepresentable on purpose. The socket is one
-connection in both directions.
-
-Every session-scoped URL may instead be a `(sessionId) => string` function.
-A2 resolves it for each request or reconnect, then adds its standard query
-parameters. This supports paths scoped to a session. Encode the ID when placing
-it in a path segment. The function chooses a route, not authority: if a path or
-connection token is scoped to one session, `authorize` must compare that scope
-to `operation.sessionId`. Bind URL tokens to the same session and keep them
-short-lived because URLs can appear in infrastructure logs. Multiplexed
-WebSockets take one plain URL because the connection carries more than one
-session.
-
-One wire is missing from `ws` by design: the history lane.
-[`loadHistory`](/guides/react#events-and-history) is a bounded cold
-read and rides plain HTTP. On a `ws` API it throws a `TypeError`.
-
-## The HTTP route
-
-`server.fetch` is bound, so an unprotected route is two exports:
-
-```ts app/api/public-order-events/route.ts
-import { ordersServer } from '@/server/orders'
-
-export const GET = ordersServer.fetch
-export const POST = ordersServer.fetch
-```
-
-A plain GET streams one session over SSE. A GET with `gte` and `lte`
-returns a history slice. POST parses the push envelope and appends its
-events. If the contract declares presence, the same route streams and
-accepts presence automatically.
-
-Wrap the call when the route needs authentication or authorization:
-
-```ts app/api/protected-order-events/route.ts
-import { ordersServer } from '@/server/orders'
-
-async function fetchOrders(request: Request): Promise<Response> {
-  // your authentication:
-  const user = { id: 'user-1' }
-  if (!user) return new Response(null, { status: 401 })
-
-  return ordersServer.fetch(request, {
-    authorize(operation) {
-      // your per-session and per-operation authorization:
-      // return canAccess(user, operation)
-      return true
-    },
-  })
-}
-
-export const GET = fetchOrders
-export const POST = fetchOrders
-```
-
-`authorize` runs after A2 parses the operation and before schema
-validation or durable I/O. It receives `stream`, `history`, and `push`
-operations. Push operations include parsed event names and payloads,
-plus the complete presence patch when present. Return `false` to deny.
-A2 answers `FORBIDDEN` with status 403. If the hook throws, A2 treats
-that as an infrastructure failure and answers `STORE_UNAVAILABLE`.
-
-The hook is per `fetch` call. Authentication stays in the route, where
-request headers, cookies, and framework context are available. The
-captured user can then authorize strongly typed A2 operations without
-repeating request parsing.
-
-## The WebSocket route
-
-Pass the platform's upgrade capability on GET. POST can stay a direct
-export for HTTP clients:
-
-```ts app/api/socket-order-events/route.ts
-import { experimental_upgradeWebSocket } from '@vercel/functions'
-import { ordersServer } from '@/server/orders'
-
-export const POST = ordersServer.fetch
-
-export function GET(request: Request): Promise<Response> {
-  return ordersServer.fetch(request, {
-    upgradeWebSocket: (attach) =>
-      experimental_upgradeWebSocket(attach, {
-        maxPayload: 4 * 1024 * 1024,
-      }),
-  })
-}
-```
-
-The socket is bound to the `sessionId` in its upgrade URL. The route
-authorizes that session before upgrading, and frames cannot select a
-different session afterward. Each connected session has its own socket.
-
-Authenticate the physical upgrade before calling `server.fetch`. For browser
-sockets authenticated by cookies, validate the request's `Origin` too. A
-WebSocket handshake does not use a CORS preflight.
-Then pass `authorize` to check the session stream and every push or
-presence frame. There is no separate upgrade operation: request policy
-belongs to the route, while A2 operation policy belongs to `authorize`.
-
-To multiplex, opt in on both sides:
-
-```ts app/api/multiplexed-order-events/route.ts
-import { experimental_upgradeWebSocket } from '@vercel/functions'
-import { ordersServer } from '@/server/orders'
-
-export function GET(request: Request): Promise<Response> {
-  return ordersServer.fetch(request, {
-    multiplexWebSocket: true,
-    upgradeWebSocket: (attach) =>
-      experimental_upgradeWebSocket(attach, {
-        maxPayload: 4 * 1024 * 1024,
-      }),
-  })
-}
-```
-
-```ts app/orders/multiplexed-session.ts
-'use client'
-import { createClient } from 'experimental-a2/client'
-import { orders } from '@/contracts'
-
-export const ordersClient = createClient({
-  contract: orders,
-  api: {
-    type: 'ws',
-    url: '/api/multiplexed-order-events',
-    multiplex: true,
-  },
-})
-```
-
-Only enable multiplexing when the request's authentication context may
-open more than one session and `authorize` checks each supplied session
-ID. Subscribe frames open the lanes after the physical upgrade.
-
-On a multiplexed socket, a denied subscribe receives an `unsubscribed`
-notice with a structured `FORBIDDEN` error and leaves other sessions
-connected. A failed stream or thrown authorization check carries
-`STORE_UNAVAILABLE`. The client exposes these as `A2ClientError` instances
-to its reconnection policy. On either socket shape, a
-denied event push receives a non-retryable `FORBIDDEN` ack. Denied
-presence is silently dropped because presence is fire-and-forget and
-repaints on the next update.
-
-A2 reads the platform's ambient invocation deadline and closes the
-socket cleanly before it. `waitUntil` and deadline discovery remain
-platform capabilities used internally, not options on `server.fetch`.
-
-## The client
-
-```ts app/orders/[orderId]/session.ts
-'use client'
-import { createClient } from 'experimental-a2/client'
-import { createReact } from 'experimental-a2/react'
-import { orders } from '@/contracts'
-
-export const ordersClient = createClient({
-  contract: orders,
-  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`, and presence coalesces on the same cadence.
-The connection status, stall watchdog, and reconnection behavior are
-shared above the wire seam.
-
-## Lifecycle
-
-When a socket closes, the client follows its reconnection policy at the current
-frontier, receives a fresh presence snapshot, and re-sends its own latest
-presence values. A multiplexed socket re-subscribes every active session
-at its own frontier. Event pushes keep their client-generated ids, so
-retry remains idempotent.
-
-Configure `createClient({ reconnect })` to choose a delay or pause by
-returning `false`. A paused session keeps its state and leases; call
-`session.reconnect()` to resume it. The default policy reconnects with
-backoff indefinitely. A clean close also runs the policy, with `error: null`.
-
-Pre-upgrade authorization remains in the HTTP route. Browser WebSockets do
-not expose a rejected upgrade's HTTP status or body, so those failures remain
-opaque `CONNECTION_FAILED` errors. Structured subscription errors are
-available after a multiplexed socket has opened.
-
-SSE and WebSocket are transport choices, not different consistency
-models. Both resume from the durable event frontier and treat presence
-as ephemeral repaintable state.