experimental-a2 0.0.0

package/docs/reference/01-api.mdx

@@ -0,0 +1,637 @@
+---
+title: API
+description: "The whole surface, small enough to read in one sitting: contract, server, session, reducer, and the React and HTTP helpers."
+---
+
+## `experimental-a2`
+
+### `a2.contract(options)`
+
+```ts
+a2.contract(options: {
+  name: string
+  events: Record<string, StandardSchemaV1>
+}): Contract
+```
+
+Defines one kind of lifecycle: a name plus the events it understands. The name
+must be unique per app; it identifies the contract in storage and queue
+messages. The result is a plain, importable, **isomorphic** value: the server
+implements it, reducers derive from it, the browser types its pushes off it.
+See [Contracts and sessions](/concepts/contracts).
+
+Schemas are [Standard Schema](https://standardschema.dev): Zod, Valibot,
+ArkType, anything that implements it. Validators must be synchronous
+(async ones are rejected here, at definition time), and the validated
+output is what's stored.
+
+### `contract.reducer(options)`
+
+```ts
+contract.reducer(options: {
+  name: string                // identity; keys cached snapshots
+  initialState: S             // the seed (schema input, when stateSchema is set)
+  stateSchema?: StandardSchemaV1 // declares S, checks initialState, guards cached folds
+}): { fold(fn: (state: S, event: Event) => S): Reducer<S> }
+```
+
+Derives a view from the contract. Two steps by design: the first call
+fixes the state and event types, so `.fold()` receives fully concrete
+ones. Literal unions in your state survive, with zero annotations.
+
+The name is the reducer's identity; it keys cached snapshots, so rename it
+when the fold's logic changes. Two reducers never fight over a cache
+entry, and a rename (or a `stateSchema` mismatch, when present)
+invalidates, and the next read refolds from raw events. See
+[Reading state](/concepts/state).
+
+### `A2Error`
+
+Everything A2 throws. One class, discriminated by `code`. See
+[Errors](/reference/errors).
+
+## `experimental-a2/server`
+
+### `createServer(options)`
+
+```ts
+createServer(options: {
+  contract: Contract // the vocabulary this server implements
+  log?: A2Log        // default: sqlite in dev, memory in tests, required in prod
+  recovery?: A2Recovery
+  telemetry?: A2Telemetry // optional instrumentation; see experimental-a2/otel
+  handlers?: {
+    [type]:
+      | (ctx: Context) => Promise<void>
+      | { abortOn: AbortSpec; handler: (ctx: Context) => Promise<void> }
+  }
+}): A2Server
+```
+
+Implements a contract: binds the vocabulary to storage and reactions.
+Handlers are one table, complete at construction, so a handler can never
+be silently missing because the module that registered it wasn't
+imported. Compose across files by spreading objects into `handlers`
+(note: a duplicate key under spread silently last-wins).
+
+Server-only by construction: `experimental-a2/server` is the only entry point that
+can reach a log backend, and its exports map resolves to a loud error
+under the browser condition.
+
+`abortOn` names the events that fire `ctx.signal` while a handler runs.
+an array matches by type; an object takes per-type predicates for
+targeted cancellation:
+
+```ts
+generate: {
+  abortOn: { cancelled: (event, trigger) => event.payload.of === trigger.id },
+  handler: async (ctx) => { /* ... */ },
+}
+```
+
+The context every handler receives:
+
+| Property           | Type                                       |
+| ------------------ | ------------------------------------------ |
+| `ctx.event`        | `Event`: the triggering event              |
+| `ctx.attempt`      | durable 1-based dispatch claim ordinal     |
+| `ctx.append(...e)` | append to this session, typed, atomic      |
+| `ctx.history()`    | `Promise<Event[]>`: raw log, oldest first  |
+| `ctx.signal`       | `AbortSignal`: active only with `abortOn`  |
+
+`ctx.attempt` starts at `1` and increments on every durable claim. It may skip
+when a process dies before handler entry.
+
+### `server.session(id)`
+
+```ts
+server.session(id: string): Session
+```
+
+A handle on one instance of the contract. The session is the unit of ordering,
+recovery, state, and live sync. Creating the handle does no I/O; nothing loads
+until you append, read, or stream.
+
+### `server.drain(sessionId)`
+
+```ts
+server.drain(sessionId: string): Promise<{ settled: boolean }>
+```
+
+Processes the session's pending events in order. `settled` means every
+event is processed or dead-lettered. You'll rarely call this yourself;
+it's the primitive recovery callbacks use. The public result stays this
+simple boolean. Recovery retries the first event without a processed marker.
+
+### `A2Log`
+
+Custom adapters implement these atomic drain methods:
+
+```ts
+// Custom server log adapter:
+type EventCause = {
+  index: number
+  attempt: number
+}
+
+type StoredEvent = Event & {
+  cause: EventCause | null
+  processedAt: Date | null
+  processedByAttempt: number | null
+  firstClaimedAt: Date | null
+  lastClaimedAt: Date | null
+  attemptCount: number
+  failureCount: number
+  lastFailedAt: Date | null
+  lastFailedAttempt: number | null
+  lastError: string | null
+  failedAt: Date | null
+}
+
+type LogClaimResult =
+  | { outcome: 'claimed'; event: StoredEvent }
+  | { outcome: 'busy' }
+  | { outcome: 'settled' }
+
+type LogHandoffResult =
+  | LogClaimResult
+  | { outcome: 'superseded' }
+
+interface A2Log {
+  claimNext(options: {
+    sessionId: string
+    holder: string
+    ttlMs: number
+    expiresAtMs?: number
+    maxIndex?: number
+  }): Promise<LogClaimResult>
+
+  completeAndClaimNext(options: {
+    sessionId: string
+    holder: string
+    completedIndex: number
+    attempt: number
+    maxIndex?: number
+  }): Promise<LogHandoffResult>
+
+  failAttempt(options: {
+    sessionId: string
+    index: number
+    attempt: number
+    error: string
+    maxFailures: number
+  }): Promise<{
+    outcome: 'failed' | 'dead_lettered' | 'superseded'
+    failureCount: number
+  }>
+}
+```
+
+| Method | Atomic effect |
+| --- | --- |
+| `claimNext` | Select the ordered head, respect optional `maxIndex`, acquire the lease, increment `attemptCount`, and update claim timestamps. |
+| `completeAndClaimNext` | Complete the current attempt once; record `processedByAttempt`; claim and timestamp the next only while the same holder owns a live lease. Stale attempts return `superseded`. |
+| `failAttempt` | Record a current caught failure, `lastFailedAt`, and `lastFailedAttempt`; dead-letter at `maxFailures`. Stale attempts return `superseded`. |
+
+`attemptCount` counts claims, including abandoned ones. `failureCount` counts
+caught failures and dead-letters at ten. See
+[Durability](/concepts/durability#one-event-many-attempts) for the recovery
+model. `cause` identifies the event and handler attempt whose `ctx.append`
+first persisted the child. A null cause means a root or a legacy event whose
+origin is unknown. Migrated rows can have `firstClaimedAt === null` with a
+nonzero `attemptCount`; the historical first claim is unknowable. Lifecycle
+timestamps are adapter clock values for their atomic log operations, not exact
+database commit times.
+Built-in adapters persist these fields inside their existing atomic operations,
+with no extra backend round trip.
+
+## Session
+
+### `session.append(...events)`
+
+```ts
+session.append(
+  ...events: Array<{ type: string; payload: unknown; id?: string }>
+): Promise<Event[]>
+```
+
+The only way to move a session forward. Payloads are validated against
+the contract's schemas before anything is written. A multi-event append
+is atomic: all-or-nothing, consecutive positions, one transaction. Pass
+`id` to make an append idempotent across retries; re-sending an
+identical batch returns the original rows. (Events parsed by
+`parsePushBody` are accepted directly, the push-route path.) See
+[Durability](/concepts/durability).
+
+### `session.history()`
+
+```ts
+session.history(): Promise<Event[]>
+```
+
+Every event in the session, oldest first. Always the raw log.
+
+### `session.state(reducer)`
+
+```ts
+session.state(reducer: Reducer<S>): Promise<{ state: S; index: number }>
+```
+
+The log folded through a reducer. `index` is the position the state
+reflects. Hand it to the client to resume a stream from exactly there. The
+snapshot and event tail are one log operation; snapshot write-back runs in
+platform `waitUntil`. This read never dispatches handlers.
+
+### `session.stream(options?)`
+
+```ts
+session.stream(options?: { startAt?: number }): AsyncIterable<Event>
+```
+
+A live feed of the session's events, starting after `startAt`.
+Server-side only; expose it over SSE with `sseResponse`. Subscribing never
+dispatches handlers.
+
+## Event
+
+```ts
+type Event = {
+  id: string
+  type: string
+  payload: unknown // typed by the contract's schema for `type`
+  index: number // position in the session's log, from 1
+  sessionId: string
+  createdAt: Date
+}
+```
+
+## `experimental-a2/react`
+
+### `createReact(options)`
+
+```ts
+createReact(options: {
+  client: A2Client          // bind a shared client: api + reducer + session identity
+}): { SessionProvider, useSession }
+
+// or, standalone (one client per provider mount):
+createReact(options: {
+  reducer: Reducer          // types everything: state, pushes, the feed
+  cache?: A2ClientCache     // optional; see local-first
+}): { SessionProvider, useSession }
+```
+
+A factory, like `createContext`: call it once in a `'use client'`
+module, export the bound pair. Server components import
+`SessionProvider` from that module as a client reference; client
+components import `useSession` from the same file. See
+[Live UI](/guides/react#the-session-module).
+
+`createReact({ reducer })` is also supported for provider-bound clients. Use a
+shared `A2Client` when code outside the provider needs to push before a route
+transition and the destination should adopt the same optimistic session.
+
+### `<SessionProvider>`
+
+| Prop            | What it is                                             |
+| --------------- | ------------------------------------------------------ |
+| `sessionId`     | which session to subscribe to                          |
+| `initialState`  | server-rendered state                                  |
+| `initialIndex`  | the fold's frontier, where the stream resumes          |
+| `initialEvents` | optional server-rendered history through that frontier |
+
+Opens the stream on mount, closes it on unmount, reconnects with
+backoff from the current frontier.
+
+### `useSession()`
+
+```ts
+const { state, push, events, index, connection } = useSession()
+```
+
+`state` folds live events through the shared reducer, `events` is the
+raw observed feed, and `index` is the stream frontier, the
+`lastSeenIndex` for [cancellation](/guides/cancellation).
+
+`push` appends optimistically: validated locally, rolled back on
+rejection, retried only for `LOG_UNAVAILABLE`. Awaiting it gives the
+server ack; the same result carries `confirmed`, a lazy promise for
+the later moment when the live stream has delivered the batch back and
+the view shows server truth:
+
+```ts
+const t0 = performance.now()
+const result = push({ type: 'created', payload })
+await result // the server ack: push→ack latency
+await result.confirmed // the stream round-trip: ack→stream latency
+const roundtripMs = performance.now() - t0
+```
+
+A rejected push rejects both promises with the same `A2Error`;
+`confirmed` is materialized only when accessed, so ignoring it costs
+nothing. It also reads as intent: `await push(...).confirmed` is
+"continue once this is server truth".
+
+`connection` is a discriminated union; impossible states are
+unrepresentable (an `error` only exists while disconnected):
+
+```ts
+type Connection =
+  | { status: 'idle' }
+  | { status: 'connecting'; reconnects: number; error: Error | null }
+  | { status: 'live'; reconnects: number }
+  | { status: 'closed' }
+```
+
+"Reconnecting…" is `status === 'connecting' && reconnects > 0`. And
+it's honest about silence: the server heartbeats the stream (`: ping`
+every 15s), and a client that hears nothing for two beats treats the
+connection as dead (aborts it and reconnects), so `live` means bytes
+are actually flowing, not "the socket hasn't errored yet". See
+[Live UI](/guides/react).
+
+## `experimental-a2/ai`
+
+### `agent(options)`
+
+```ts
+agent(options: {
+  name: string
+  events?: Record<string, StandardSchemaV1>
+  messageSchema?: StandardSchemaV1<UIMessage>
+  reducerName?: string
+}): AgentDefinition
+```
+
+Defines an isomorphic agent as ordinary A2 parts. Its `contract` contains the
+built-in AI protocol plus `events`, and its `reducer` projects `AIState`. The
+definition exposes only `contract` and `reducer`.
+
+Built-in event names cannot be replaced by `options.events`.
+
+### `inputs`
+
+Pure typed inputs for `append()` and `push()`:
+
+| Input | Events |
+| --- | --- |
+| `inputs.message(message)` | `ai.message.created`, plus `ai.generation.requested` for a user message |
+| `inputs.seed(message)` | `ai.message.created` only |
+| `inputs.approval(response)` | `ai.approval.responded` + continuation request |
+| `inputs.input(response)` | `ai.input.responded` + continuation request |
+| `inputs.requestInput(request)` | `ai.input.requested` |
+| `inputs.retry(options)` | a fresh `ai.generation.requested` for a failed response |
+| `inputs.interrupt(options)` | `ai.message.interrupted` |
+
+`inputs` deliberately has no session lifecycle methods. Push explicit
+`ai.session.created` and `ai.session.closed` events directly when an
+application uses them. Input event ids are stable for the interaction they
+describe, so a lost append acknowledgment can be resent safely.
+
+### `events` and `createEvents(options?)`
+
+The built-in Standard Schema definitions. Use `events` for the default AI SDK
+`UIMessage`; use `createEvents({ messageSchema })` to validate a more specific
+message type. Both are isomorphic.
+
+### `createReducer(options)`
+
+```ts
+createReducer({ contract, name? }): Reducer<AIState>
+```
+
+Builds the standard AI projection for a compatible contract. `AIState`
+contains session lifecycle, messages, generation status, pending approvals
+and input, tool activity, compaction, usage, and the last error.
+`activeProjection` holds the indexed chunk/tool frontier only while a
+generation is active; terminal events clear it. Extension events are ignored.
+
+### `deriveUIMessages(history)` and `reduceAIState(state, event)`
+
+`deriveUIMessages()` folds a raw A2 event history directly into AI SDK
+`UIMessage[]`. `reduceAIState()` is the event-at-a-time form used by the
+standard reducer. Both synchronously project the same chunk-only protocol.
+
+## `experimental-a2/ai/server`
+
+### `createAgentServer(options)`
+
+```ts
+createAgentServer({
+  agent: AgentDefinition,
+  model: LanguageModel | (context => LanguageModel),
+  tools?,
+  instructions?,
+  generation?,
+  generate?,
+  compaction?,
+  progress?,
+  log?, recovery?, telemetry?, handlers?,
+}): A2Server
+```
+
+Creates the standard server for an agent. A2 runs an AI SDK `ToolLoopAgent`,
+persists each `UIMessageChunk` once in a durable progress batch, projects
+messages synchronously, extracts tool and approval lifecycle events, and
+records completion, usage, interruption, and failure. `model` accepts an AI
+SDK model string or provider model. `model` and `instructions` can be values or per-generation async
+resolvers. `generation` accepts the remaining `ToolLoopAgent` settings, such
+as `temperature`, `maxOutputTokens`, `topP`, stop conditions, and provider
+options. Support for individual settings depends on the selected model and
+provider.
+
+`generate(context)` optionally replaces the default AI SDK generation. It
+receives messages, the resolved model and instructions, tools, generation
+settings, request state, and the abort signal. It returns a
+`ReadableStream<UIMessageChunk>`. A2 continues to own the durable lifecycle
+around that stream.
+
+`compaction` has `shouldCompact(context)` and `compact(context)` callbacks.
+When selected, both the request and the replacement messages enter the log.
+`progress` controls durable batching with `maxChunks` and `maxDelayMs`.
+
+This entry point is server-only and resolves to a throwing browser stub.
+
+### `createHandlers(options)`
+
+Returns the built-in A2 handler table without constructing a server. Spread
+it into `createServer({ handlers })` beside application handlers when you need
+a custom assembly. Application handlers spread later can deliberately replace
+a built-in handler.
+
+See [Durable AI agents](/guides/ai-agents) for the protocol and complete
+examples.
+
+## `experimental-a2/client`
+
+```ts
+createClient(options: {
+  reducer: Reducer
+  api: string
+  gcTime?: number // idle session lifetime; 5 minutes by default
+}): A2Client
+```
+
+The framework-agnostic session client `experimental-a2/react` is built on: the SSE
+subscription with frontier resume and reconnection, the optimistic push
+queue with ack/rollback, and the local fold. `client.session(id, {
+initialState?, initialIndex?, initialEvents? })` returns a handle with
+`getSnapshot()`/`subscribe()` (the `useSyncExternalStore` contract),
+`push()`, `connect()`, and `close()`. Snapshots carry `state`, `events`,
+`index`, and `connection` (the same fields `useSession` exposes), and
+`push` returns the same ack-then-`confirmed` result. Use it directly
+from any other framework, or none.
+
+Within one `A2Client`, repeated `session(id)` calls return the same live
+handle. `initialEvents` seeds the raw feed for SSR. A later call with a further
+server-rendered frontier advances the handle, merges its history, and does not
+drop pending optimistic events; a stale render cannot move it backward. Idle
+handles are evicted after `gcTime`. This memory layer is separate from
+`experimental-a2/cache-indexeddb`: memory preserves identity across route transitions,
+while IndexedDB preserves the replica across reloads.
+
+## `experimental-a2/http`
+
+| Helper                  | What it does                                                                   |
+| ----------------------- | ------------------------------------------------------------------------------ |
+| `parsePushBody(req)`    | validates the push envelope `{ sessionId, events }`, throws `INVALID_PAYLOAD`   |
+| `sseResponse(iterable)` | pipes a `session.stream()` iterable into an SSE `Response`, with a `: connected` prelude and a `: ping` heartbeat every 15s |
+| `errorResponse(err)`    | serializes an `A2Error` to `{ error: { code, message, details } }` + status     |
+| `deserializeError(body)` | rebuilds an `A2Error` from a wire body, or `null` if the body isn't one        |
+
+Together the last two are the `A2Error` wire format that `push` and the
+push route share. See [Errors](/reference/errors#over-the-wire).
+
+## `experimental-a2/cache-indexeddb`
+
+```ts
+indexedDb(): A2ClientCache
+```
+
+A browser-side cache for `SessionProvider`: the session's events
+(immutable; writes are idempotent by index), a folded snapshot
+(invalidated by a reducer rename), and the pending-push queue.
+`cache.clear(sessionId?)` is the logout story. Create instances in client
+code; they're live objects, not serializable props. See
+[Local-first](/guides/local-first).
+
+## `experimental-a2/otel`
+
+```ts
+otel(options?: { tracer?: Tracer; tracerName?: string }): A2Telemetry
+```
+
+OpenTelemetry instrumentation for a server (`@opentelemetry/api` is a
+peer dependency). Pass it as `telemetry`; spans nest through the active
+context, so the happy path lands in one trace: request → append → drain →
+each handler → the events those handlers append.
+
+### The span catalogue
+
+Four spans, all carrying `a2.contract` and `a2.session_id`:
+
+| Span        | Wraps                                                  |
+| ----------- | ------------------------------------------------------ |
+| `a2.append` | validation + the log write (one batch)                 |
+| `a2.drain`  | one drain pass over a session's backlog                |
+| `a2.event`  | one claimed dispatch of one event                      |
+| `a2.state`  | one `state()` read: snapshot-plus-tail load + fold      |
+
+Attributes arrive in two waves: **at start** (passed to `span()`) and
+**mid-span** (via `handle.setAttribute`; outcomes and counts aren't
+known until the work ran). A recorder must merge both; the ones you
+alert on are all mid-span.
+
+| Attribute             | Span        | When  | Values                                                |
+| --------------------- | ----------- | ----- | ----------------------------------------------------- |
+| `a2.append.source`    | `a2.append` | start | `external` \| `handler`                                |
+| `a2.append.types`     | `a2.append` | start | comma-joined event types                              |
+| `a2.append.count`     | `a2.append` | start | batch size                                            |
+| `a2.append.armed`     | `a2.append` | mid   | `false` when the recovery arm failed and this append degraded to append-driven healing |
+| `a2.drain.scope`      | `a2.drain`  | start | `full` \| `tree`                                      |
+| `a2.drain.outcome`    | `a2.drain`  | mid   | `settled` \| `busy` \| `stalled` \| `handed_off` |
+| `a2.drain.processed`  | `a2.drain`  | mid   | events processed this pass                            |
+| `a2.event.type`       | `a2.event`  | start | the event's type                                      |
+| `a2.event.index`      | `a2.event`  | start | log position                                          |
+| `a2.event.id`         | `a2.event`  | start | event id                                              |
+| `a2.event.attempt`    | `a2.event`  | start | same durable 1-based ordinal as `ctx.attempt`          |
+| `a2.event.handled`    | `a2.event`  | start | `false` when no handler is registered                 |
+| `a2.event.outcome`    | `a2.event`  | mid   | `processed` \| `failed` \| `dead_lettered` \| `superseded` |
+| `a2.event.aborted`    | `a2.event`  | mid   | `true` when `abortOn` fired during the run            |
+| `a2.event.lease_lost` | `a2.event`  | mid   | `true` when the lease was lost mid-handler            |
+| `a2.state.reducer`    | `a2.state`  | start | the reducer's name                                    |
+| `a2.state.snapshot`   | `a2.state`  | mid   | `hit` \| `miss` \| `rejected` (schema guard discarded it) |
+| `a2.state.folded`     | `a2.state`  | mid   | events folded past the snapshot                       |
+| `a2.state.index`      | `a2.state`  | mid   | the frontier the returned state reflects              |
+
+Drain outcomes: `settled` means nothing actionable is left; `busy` means
+another drainer holds the session (in-process slot or cross-process lease);
+`stalled` means blocked at a dead-lettered event; `handed_off` means leftovers
+went to a scheduled in-process drain.
+
+A failing handler marks its `a2.event` span with the exception and
+error status; `a2.event.outcome = dead_lettered` is the attribute to
+alert on. `superseded` means a stale completion or failure did not change the
+log.
+`A2Telemetry` is a one-method interface; anything with
+`span(name, attributes, fn)` works;
+`otel()` is simply the adapter A2 ships. This catalogue is a contract:
+renames and additions are breaking for dashboards, and are called out in the
+package's `CHANGELOG.md`.
+
+## `experimental-a2/devtools/server`
+
+```ts
+// anywhere on the server:
+import type { DevtoolsServer } from 'experimental-a2/devtools/server'
+
+declare function createDevtools(options: {
+  servers: readonly DevtoolsServer[]
+  authorize?: (
+    request: Request,
+  ) => boolean | Response | Promise<boolean | Response>
+}): {
+  handler(): (request: Request) => Promise<Response>
+}
+```
+
+A read-only dashboard over the servers' durable logs. The handler serves the
+complete browser application, its JSON endpoints, and live SSE invalidations.
+It discovers sessions and reads stored causal, dispatch, completion, failure,
+and snapshot metadata. The causal forest and lifecycle timeline come directly
+from stored events. The initial page response includes the selected dashboard
+data so the browser does not need a contracts, sessions, and detail request
+waterfall. It never drains or heals a session.
+
+Without `authorize`, the handler is available outside production and returns
+404 in production. Returning `false` from `authorize` also returns 404.
+Returning a `Response` passes that response through, which supports redirects
+and authentication challenges.
+
+The built-in memory, SQLite, Postgres, and Redis logs support inspection.
+Custom `A2Log` implementations can omit the optional `inspect` interface; the
+dashboard returns 501 for those logs.
+
+## Entry points
+
+| Entry point          | Ships                              | Peer dependency |
+| -------------------- | ---------------------------------- | --------------- |
+| `experimental-a2`                 | `contract`, `A2Error`: isomorphic core    | none     |
+| `experimental-a2/server`          | `createServer`: implement a contract      | none     |
+| `experimental-a2/client`          | `createClient`: framework-agnostic session client | none |
+| `experimental-a2/react`           | `createReact`                      | `react`         |
+| `experimental-a2/ai`              | agent contract, reducer, and append builders: isomorphic | `ai` |
+| `experimental-a2/ai/server`       | AI SDK runner and built-in handlers | `ai`           |
+| `experimental-a2/http`            | route-side transport helpers       | none            |
+| `experimental-a2/log-postgres`    | `postgres`: Postgres log backend   | `pg` (or inject a client) |
+| `experimental-a2/log-redis`       | `redis`: Redis Streams log backend, push-native streaming | `ioredis` (or inject a client) |
+| `experimental-a2/log-sqlite`      | SQLite log backend                 | none            |
+| `experimental-a2/log-memory`      | in-memory log backend              | none            |
+| `experimental-a2/recovery-vercel` | `vercelQueues` recovery            | `@vercel/queue` |
+| `experimental-a2/cache-indexeddb` | `indexedDb` browser cache          | none            |
+| `experimental-a2/otel`            | `otel` telemetry adapter           | `@opentelemetry/api` |
+| `experimental-a2/devtools/server` | durable read-only dashboard handler | none            |
+
+Core `experimental-a2` imports none of the backends, enforced by a browser-bundle
+test in CI, not just convention. Importing `experimental-a2/log-postgres` is what
+pulls in Postgres, never `experimental-a2` itself, and never your client bundle.