@voltro/cli 0.1.0

package/templates/agent-docs/data.md

@@ -0,0 +1,2172 @@
+# Data
+
+> How Voltro's reactive data layer works — queries, mutations, actions, streams, all over one WebSocket with typed errors and tracked dependencies.
+
+
+
+---
+
+<!-- source: en/data/overview.md -->
+## Overview
+
+_How Voltro's reactive data layer works — queries, mutations, actions, streams, all over one WebSocket with typed errors and tracked dependencies._
+
+The api side of a Voltro app is a collection of typed RPC primitives. You drop descriptor/server-executor pairs into the api tree; the framework discovers them; the typed client lights up.
+
+This section covers how data flows between server and client.
+
+A form bound to a mutation, a table bound to a query, one reactive backend — add
+a row and it appears instantly, pushed from the server (your own throwaway
+sandbox; it resets on refresh):
+
+```tsx
+<AutoForm api="app" mutation="todos.create" submitLabel="Add todo" />
+<DataTable api="app" query="todos.list" />
+```
+
+## The shape of it
+
+```text
+┌──────────────────────────────────────────────────────────────────┐
+│  Client (React)                                                  │
+│    useSubscription('app', 'notes.list', input)                   │
+│    useMutation('app', 'notes.create')                            │
+│    useAction('app', 'invites.send')                              │
+│    useAgentStream('app', 'support.run')                          │
+└──────────────────────────┬───────────────────────────────────────┘
+                           │  @effect/rpc over WebSocket
+                           ▼
+┌──────────────────────────────────────────────────────────────────┐
+│  api app                                                         │
+│    *.query.ts    + *.query.server.ts     — reactive reads         │
+│    *.mutation.ts + *.mutation.server.ts  — transactional writes   │
+│    *.action.ts   + *.action.server.ts    — external I/O / unary   │
+│    *.stream.ts   + *.stream.server.ts    — one-shot element push  │
+│    *.route.tsx                            — public raw-HTTP route  │
+│    *.workflow.tsx  + *.trigger.tsx        — durable work + events  │
+│    *.agent.tsx                            — persisted AI chat      │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+Most of it goes through one WebSocket (REST routes are the public raw-HTTP exception). Queries and streams are both streaming RPCs, but they mean different things: a query emits reactive snapshot/delta envelopes; a stream emits plain elements and then finishes.
+
+## Every primitive at a glance
+
+Voltro ships more building blocks than this one section holds — each is a typed descriptor in a file the CLI discovers. The five at the top live here; the rest have their own sections but are the same kind of thing. The complete set:
+
+| Primitive | File | What it is |
+|---|---|---|
+| **Query** | `*.query.ts` | reactive read → [Queries](/docs/data/queries) |
+| **Mutation** | `*.mutation.ts` | transactional write → [Mutations](/docs/data/mutations) |
+| **Action** | `*.action.ts` | unary external I/O → [Actions](/docs/data/actions) |
+| **Stream** | `*.stream.ts` | one-shot element push → [Streams](/docs/data/streams) |
+| **REST route** | `*.route.tsx` | public raw-HTTP endpoint → [REST routes](/docs/data/rest-routes) |
+| **Aggregate** | `*.aggregate.ts` | scheduled materialised query → [Aggregates](/docs/data/aggregates) |
+| **Subscriber** | `*.subscribe.ts` | per-table post-commit reaction → [Subscribers](/docs/data/subscribers) |
+| **Workflow** | `*.workflow.tsx` | durable multi-step work → [Workflows](/docs/workflows/overview) |
+| **Event trigger** | `*.trigger.tsx` | event → workflow fan-out → [Event triggers](/docs/workflows/event-triggers) |
+| **Schedule** | `*.cron.tsx` | cron-fired handler → [Scheduling](/docs/scheduling/overview) |
+| **Agent** | `*.agent.tsx` | persisted AI chat → [Agents](/docs/ai/agents) |
+| **Tool** | `*.tool.tsx` | model-callable function → [Tools](/docs/ai/tools) |
+| **Seed** | `*.seed.ts` | boot/data seeding → [Seeds](/docs/database/seeds) |
+| **Startup** | `*.startup.tsx` | run-once boot hook (long-lived work + teardown) → [Startup hooks](/docs/reference/startup) |
+| **Email** | `*.email.tsx` | React-Email template → [Mail](/docs/plugins/mail) |
+| **Webhook** | `*.webhook.tsx` | signed inbound / outbound → [Webhooks](/docs/plugins/webhooks) |
+
+## What's in this section
+
+**Primitives** — [Queries](/docs/data/queries) (reactive reads + dependency tracking) · [Mutations](/docs/data/mutations) (transactional writes, typed errors, auto-optimistic) · [Actions](/docs/data/actions) (unary RPC, no transaction) · [Subscriptions](/docs/data/subscriptions) (the reactive engine behind snapshots/deltas) · [Streams](/docs/data/streams) (`defineStream` element push) · [REST routes](/docs/data/rest-routes) (public raw-HTTP for third parties) · [Aggregates](/docs/data/aggregates) (scheduled materialised queries) · [Subscribers](/docs/data/subscribers) (per-table post-commit reactions).
+
+**Protocol & errors** — [Wire protocol](/docs/data/wire-protocol) (framing, multiplexing) · [Error handling](/docs/data/errors) (Schema-tagged errors, retries, client narrowing).
+
+## The contract
+
+Every query, mutation, action, and stream has two files:
+
+```text
+queries/notes.list.query.ts          # descriptor: browser-safe schema + metadata
+queries/notes.list.query.server.ts   # executor: server-only implementation
+```
+
+The descriptor defines the wire surface:
+
+```ts
+defineX({
+  name:   'feature.action',
+  input:  Schema.Struct({ /* ... */ }),
+  output: Schema.Struct({ /* mutations/actions */ }),
+  element: Schema.Struct({ /* streams */ }),
+  error:  Schema.Union(ErrorVariantA, ErrorVariantB),
+})
+```
+
+The server executor receives `(input, ctx)` and can return a plain value, `Promise`, `Effect`, query descriptor, or `Stream`, depending on the primitive. Everything is Schema-validated at the boundary. The TypeScript types flow to the client automatically through `rpcGroup.generated.ts`.
+
+> **`name` charset.** A procedure `name` is `.`-separated and becomes a JS
+> identifier in `rpcGroup.generated.ts` (`todos.list` → `todosListRpc`). It
+> must start with a letter and use only letters, digits, and `.` / `-` / `_`.
+> `-` and `_` are camelCased away, so two names differing only by separator
+> **collide**. Codegen rejects an invalid or colliding name at `voltro dev`
+> boot, naming the file. Prefer plain camelCase segments (`todos.list`).
+
+## Reactivity model
+
+Queries are live. A query descriptor declares `source: 'tableName'`; the server executor returns either a query builder/descriptor or a computed value. When a mutation writes to the table, the runtime recomputes affected subscriptions and pushes a snapshot or delta.
+
+Streams are not live subscriptions. A stream executor returns a one-shot `Stream` of elements. Use streams for transient token feeds, progress events, logs, or external event sources. If the result should survive reloads or update other tabs, persist rows and expose them through a query.
+
+## Tenant scoping
+
+Every executor receives `ctx.request.subject` — the typed identity of the caller. Tables with the `tenant()` mixin auto-scope reads and writes. See [Multi-tenancy](/docs/multi-tenancy/overview) for the full story.
+
+## When to use what
+
+| You want… | Use |
+|---|---|
+| Read data that updates live | `*.query.ts` + `*.query.server.ts` + `useSubscription` |
+| Write data atomically | `*.mutation.ts` + `*.mutation.server.ts` + `useMutation` |
+| External I/O / unary side effect | `*.action.ts` + `*.action.server.ts` + `useAction` |
+| Public HTTP endpoint for a third party (URL + JSON) | [`*.route.tsx`](/docs/data/rest-routes) (`defineRestRoute`) |
+| Transient server-to-client element stream | `*.stream.ts` + `*.stream.server.ts` + `useAgentStream` |
+| Durable persisted AI chat | `*.agent.tsx` or action + query over `agent_messages` |
+| Background job | `*.workflow.tsx` |
+| Fan a domain event out to one or more workflows | [`*.trigger.tsx`](/docs/workflows/event-triggers) + `ctx.events.emit(...)` |
+| Pre-computed query result (top-N, summary) | [`*.aggregate.ts`](/docs/data/aggregates) |
+| React to every commit on a table (server-side) | [`*.subscribe.ts`](/docs/data/subscribers) |
+| Event ingestion + analytical aggregates over events | [Analytics sink](/docs/plugins/analytics) |
+
+Pages don't have to pick only one. Most use `useSubscription` for reads and `useMutation` for writes; add actions or streams only when the workflow calls for them.
+
+
+
+---
+
+<!-- source: en/data/queries.md -->
+## Queries
+
+_`*.query.ts` + `*.query.server.ts` pairs — reactive reads consumed with useSubscription, with dependency tracking and delta updates._
+
+A **query** is a reactive read. The client subscribes to it; when the underlying data changes, Voltro pushes a fresh snapshot or delta over the WebSocket. No polling, no manual `refetch`, no mutation response gymnastics.
+
+Live — a computed-return query: the `{ open, done, total }` counts recompute the
+instant you add or toggle a todo (it declares `source: 'todos'`):
+
+```tsx
+const stats = useSubscription('app', 'todos.stats')   // computed, live — no refetch
+```
+
+## Minimal query pair
+
+Descriptor file:
+
+```ts
+// apps/api/queries/notes.list.query.ts
+import { defineQuery } from '@voltro/protocol'
+import { Schema } from 'effect'
+
+export const listNotes = defineQuery({
+  name:   'notes.list',
+  source: 'notes',
+  input:  Schema.Struct({}),
+  output: Schema.Array(Schema.Struct({
+    id:    Schema.String,
+    title: Schema.String,
+  })),
+})
+```
+
+Server executor:
+
+```ts
+// apps/api/queries/notes.list.query.server.ts
+import { database } from '../database/index'
+
+export default () =>
+  database.notes.orderBy('createdAt', 'desc').limit(100)
+```
+
+Save both files and `notes.list` becomes a streaming query in the typed client.
+
+## Consuming a query
+
+```tsx no-check
+import { useSubscription } from '@voltro/client'
+
+export default function Notes() {
+  const { data, error } = useSubscription('app', 'notes.list', {})
+  if (error) return <p>Error: {String(error)}</p>
+  if (data === undefined) return <p>Loading...</p>
+  return (
+    <ul>
+      {data.map((note) => <li key={note.id}>{note.title}</li>)}
+    </ul>
+  )
+}
+```
+
+The first argument is the api name from `app.config.ts.apis`; the second is the descriptor's `name`.
+
+## Inputs
+
+Descriptor:
+
+```ts
+// apps/api/queries/messages.list.query.ts
+import { defineQuery } from '@voltro/protocol'
+import { Schema } from 'effect'
+
+export const listMessages = defineQuery({
+  name:   'messages.list',
+  source: 'messages',
+  input:  Schema.Struct({
+    channelId: Schema.String,
+    limit:     Schema.Number,
+  }),
+  output: Schema.Array(Schema.Struct({
+    id:        Schema.String,
+    channelId: Schema.String,
+    body:      Schema.String,
+  })),
+})
+```
+
+Server executor:
+
+```ts
+// apps/api/queries/messages.list.query.server.ts
+import { eq } from '@voltro/database'
+import { database } from '../database/index'
+
+export default (input: { channelId: string; limit: number }) =>
+  database.messages
+    .where(eq('channelId', input.channelId))
+    .orderBy('createdAt', 'desc')
+    .limit(input.limit)
+```
+
+Client:
+
+```tsx
+const { data } = useSubscription('app', 'messages.list', {
+  channelId: 'c_123',
+  limit: 50,
+})
+```
+
+## Descriptor-return vs computed-return
+
+A query executor can return either:
+
+| Executor returns | Use when |
+|---|---|
+| A `database.<table>` query builder / descriptor | You are streaming rows from one table and want fine-grained predicate-aware invalidation. |
+| A computed value | You are building an aggregate, join, projection, or other derived shape. |
+
+Computed example:
+
+```ts
+// apps/api/queries/notes.summary.query.ts
+import { defineQuery } from '@voltro/protocol'
+import { Schema } from 'effect'
+
+export const notesSummary = defineQuery({
+  name:   'notes.summary',
+  source: 'notes',
+  input:  Schema.Struct({}),
+  output: Schema.Struct({
+    open: Schema.Number,
+    done: Schema.Number,
+  }),
+})
+```
+
+```ts
+// apps/api/queries/notes.summary.query.server.ts
+export default async (_input: Record<string, never>, ctx) => {
+  const notes = await ctx.store.select('notes').all()
+  return {
+    open: notes.filter((note) => !note.done).length,
+    done: notes.filter((note) => note.done).length,
+  }
+}
+```
+
+For computed queries, `source` is the reactivity trigger. When any row in the source table changes, the runtime re-runs the executor and emits the new value if it changed. If the executor reads more than one table (a join or matrix), declare `source` as an array — the executor re-runs when **any** listed table changes (e.g. `source: ['skills', 'ratings']`).
+
+## Auto-optimistic source
+
+`source` also connects query caches to mutation `target` metadata:
+
+```ts
+defineQuery({ name: 'notes.list', source: 'notes', /* ... */ })
+defineMutation({ name: 'notes.create', target: { table: 'notes', op: 'insert' }, /* ... */ })
+```
+
+With that pairing, `useMutation('app', 'notes.create')` can stage an optimistic row in active `notes.list` caches without client-side cache plumbing.
+
+## What gets sent on the wire
+
+Queries are streaming RPCs whose elements are **subscription events**: an initial `snapshot` followed by `delta`s. See [Wire protocol](/docs/data/wire-protocol#subscription-events-snapshot-delta) for the envelope shape. For plain element streams, use [Streams](/docs/data/streams).
+
+## Anti-patterns
+
+- **Putting server-only imports in `*.query.ts`.** Descriptors are imported by browser-safe codegen. Put database/SDK/filesystem imports in `*.query.server.ts`.
+- **Mutating from a query executor.** Queries are reads. Use a mutation for writes.
+- **Using a stream for durable data.** Streams are transient. Persist rows and expose them through a query when the UI should survive reloads or sync across tabs.
+
+
+
+---
+
+<!-- source: en/data/mutations.md -->
+## Mutations
+
+_`*.mutation.ts` + `*.mutation.server.ts` pairs — atomic writes with typed schemas and auto-optimistic metadata._
+
+A **mutation** is the write primitive. Every `ctx.store.insert`, `update`, and `delete` inside one mutation runs in a single transaction. If the executor throws, the transaction rolls back and subscribers never observe a partial write.
+
+Declare `target` metadata in the descriptor so the client can derive optimistic patches for queries whose `source` points at the same table.
+
+Live — submitting adds the row optimistically (it shows instantly, then the
+server delta confirms it):
+
+```tsx
+<AutoForm api="app" mutation="todos.create" submitLabel="Add todo" />
+<DataTable api="app" query="todos.list" />
+```
+
+## Mutation Pair
+
+Descriptor:
+
+```ts
+// apps/api/mutations/notes.create.mutation.ts
+import { defineMutation } from '@voltro/protocol'
+import { Schema } from 'effect'
+
+export const createNote = defineMutation({
+  name:   'notes.create',
+  target: { table: 'notes', op: 'insert' },
+  input:  Schema.Struct({
+    title: Schema.NonEmptyString,
+    body:  Schema.String,
+  }),
+  output: Schema.Struct({
+    id: Schema.String,
+  }),
+})
+```
+
+Server executor:
+
+```ts
+// apps/api/mutations/notes.create.mutation.server.ts
+import type { AppContext } from '@voltro/runtime'
+
+export default async (
+  input: { title: string; body: string },
+  ctx: AppContext,
+) => {
+  const inserted = await ctx.store.insert('notes', {
+    title:    input.title,
+    body:     input.body,
+    authorId: ctx.request.subject.id,
+    tenantId: ctx.request.subject.tenantId,
+  })
+
+  return { id: inserted['id'] as string }
+}
+```
+
+The descriptor is the wire contract. The `.mutation.server.ts` file is the server-only implementation.
+
+## What The Runtime Does
+
+1. Decode `input` with the descriptor schema.
+2. Run mutation plugin interceptors.
+3. Execute the server file inside `store.transactional(...)`.
+4. Encode `output` with the descriptor schema.
+5. Commit the transaction.
+6. Drain the batched change events so matching query subscriptions receive new snapshots or deltas.
+
+## Calling From React
+
+```tsx
+import { useMutation } from '@voltro/client'
+
+export default function NewNote() {
+  const create = useMutation<{ title: string; body: string }, { id: string }>(
+    'app',
+    'notes.create',
+  )
+
+  return (
+    <form onSubmit={async (event) => {
+      event.preventDefault()
+      const form = new FormData(event.currentTarget)
+      await create.mutate({
+        title: String(form.get('title')),
+        body:  String(form.get('body')),
+      })
+    }}>
+      <input name="title" />
+      <textarea name="body" />
+      <button disabled={create.pending}>
+        {create.pending ? 'Saving...' : 'Save'}
+      </button>
+    </form>
+  )
+}
+```
+
+`useMutation` returns `mutate`, `pending`, `error`, `data`, plus the chainable optimistic helpers.
+
+## Auto-Optimistic
+
+The default path is declarative:
+
+```ts
+defineQuery({
+  name: 'notes.list',
+  source: 'notes',
+  input: Schema.Struct({}),
+  output: Schema.Array(Note),
+})
+
+defineMutation({
+  name: 'notes.create',
+  target: { table: 'notes', op: 'insert' },
+  input,
+  output,
+})
+```
+
+Then the client can stay plain:
+
+```tsx
+const notes = useSubscription('app', 'notes.list', {})
+const create = useMutation('app', 'notes.create')
+
+await create.mutate({ title, body })
+```
+
+The client stages an optimistic patch, calls the server, then removes the patch when the server result or failure arrives. Server-pushed deltas are still the source of truth.
+
+For special shapes, override the patch:
+
+```tsx
+const create = useMutation('app', 'notes.create').withOptimistic((cache, input) => {
+  cache.forTag<ReadonlyArray<{ id: string; title: string }>>('notes.list', (rows) => [
+    { id: `temp:${Date.now()}`, title: input.title },
+    ...rows,
+  ])
+})
+```
+
+Use `.withoutOptimistic()` for effects that should not preview locally.
+
+## Typed Errors
+
+```ts
+import { Schema } from 'effect'
+
+class NoteQuotaExceeded extends Schema.TaggedError<NoteQuotaExceeded>()('NoteQuotaExceeded', {
+  limit: Schema.Number,
+}) {}
+
+export const createNote = defineMutation({
+  name: 'notes.create',
+  target: { table: 'notes', op: 'insert' },
+  input,
+  output,
+  error: NoteQuotaExceeded,
+})
+```
+
+Throw a matching error from the server file; the client can narrow on `_tag`.
+
+## When Not To Use A Mutation
+
+- **External I/O.** Use an action or workflow.
+- **Progress output.** Use a stream.
+- **Reads.** Use a query.
+- **Long-running durable work.** Use a workflow.
+
+
+
+---
+
+<!-- source: en/data/actions.md -->
+## Actions
+
+_`*.action.ts` + `*.action.server.ts` pairs — unary server calls for external I/O and non-transactional work._
+
+An **action** is a typed unary RPC that runs outside the mutation transaction wrapper. Use it for external I/O and request-scoped work: HTTP calls, emails, signed upload URLs, AI calls that return one value, or kicking off a workflow.
+
+Actions can read or write through `ctx.store`, but those writes are not grouped into one automatic transaction and they do not drive client auto-optimistic updates. If the main purpose is an atomic database write, use a [mutation](/docs/data/mutations). If the client should receive incremental elements while work is running, use a [stream](/docs/data/streams).
+
+Live — a unary action: call it, get one typed answer back. No transaction, no
+optimistic patch:
+
+```tsx
+const echo = useAction('app', 'demo.echo')
+await echo.run({ message })   // one call → one typed result
+```
+
+## Action Pair
+
+Descriptor:
+
+```ts
+// apps/api/actions/support.ping.action.ts
+import { defineAction } from '@voltro/protocol'
+import { Schema } from 'effect'
+
+export const pingExternal = defineAction({
+  name: 'support.ping',
+  input: Schema.Struct({ url: Schema.String }),
+  output: Schema.Struct({
+    status:     Schema.Number,
+    durationMs: Schema.Number,
+  }),
+})
+```
+
+Server executor:
+
+```ts
+// apps/api/actions/support.ping.action.server.ts
+import { HttpClient, HttpClientRequest } from '@effect/platform'
+import { Effect } from 'effect'
+
+export default (input: { url: string }) =>
+  Effect.gen(function* () {
+    const client = yield* HttpClient.HttpClient
+    const startedAt = Date.now()
+    const response = yield* client.execute(HttpClientRequest.get(input.url))
+
+    return {
+      status: response.status,
+      durationMs: Date.now() - startedAt,
+    }
+  })
+```
+
+The descriptor file is safe for client-side discovery. The `.action.server.ts` file contains the server-only code and can return a plain value, a `Promise`, or an `Effect`.
+
+## Calling From React
+
+```tsx
+import { useAction } from '@voltro/client'
+
+const ping = useAction<{ url: string }, { status: number; durationMs: number }>(
+  'app',
+  'support.ping',
+)
+
+const onClick = async () => {
+  const result = await ping.run({ url: 'https://example.com/health' })
+  console.log(result.status)
+}
+```
+
+`useAction` returns `run`, `pending`, `error`, and `lastResult`.
+
+## Action vs Mutation vs Stream
+
+| Need | Use |
+|---|---|
+| Atomic database write with rollback | Mutation |
+| External I/O or one-shot server call | Action |
+| Progressive server-to-client output | Stream |
+| Durable multi-step work | Workflow |
+| Client-side optimistic preview | Mutation with `target` metadata |
+
+## Database Writes
+
+Actions are not wrapped in the mutation transaction. A throw does not roll back previous writes or external side effects.
+
+```ts
+export default async (input, ctx) => {
+  await ctx.store.insert('auditLogs', {
+    message: input.message,
+    actorId: ctx.request.subject.id,
+  })
+
+  await sendExternalWebhook(input)
+  return { ok: true }
+}
+```
+
+Use this shape only when that ordering is acceptable. If several writes must commit or roll back together, move them to a mutation. If the external side effect must survive retries, model the operation as a workflow.
+
+## Typed Errors
+
+Actions use the same `error: Schema.Union(...)` descriptor field as mutations. Throwing a matching tagged error reaches the client as a typed failure from `run(...)`.
+
+See [Error handling](/docs/data/errors) for the pattern.
+
+## Anti-Patterns
+
+- **Actions used as reads.** Use a query if the client wants cached reactive data.
+- **Actions used for atomic writes.** Use a mutation so subscribers never see partial state.
+- **Actions used for progress feeds.** Use `defineStream` and `useAgentStream`.
+
+
+
+---
+
+<!-- source: en/data/subscriptions.md -->
+## Subscriptions
+
+_How reactive query subscriptions stay live over WebSocket._
+
+A **subscription** is what the browser gets when it calls `useSubscription(...)` for a `defineQuery` RPC. The app code writes a query pair; the runtime keeps that query live over WebSocket and pushes new snapshots or deltas when matching data changes.
+
+Subscriptions are not a separate file convention anymore. The file convention is [queries](/docs/data/queries): `*.query.ts` for the descriptor and `*.query.server.ts` for the executor.
+
+Live — add a todo (or open this page in a second tab) and the list updates with
+no refetch; the `<DataTable>` is a subscription under the hood:
+
+```tsx
+<AutoForm api="app" mutation="todos.create" submitLabel="Add todo" />
+<DataTable api="app" query="todos.list" />   {/* live subscription */}
+```
+
+## Lifecycle
+
+```tsx
+const { data } = useSubscription('app', 'notes.list', { archived: false })
+```
+
+1. The client opens or reuses the API WebSocket.
+2. It sends the query tag and input.
+3. The runtime runs `notes.list.query.server.ts`.
+4. The first value is delivered as a snapshot.
+5. Later mutations emit change events when their transaction commits.
+6. Matching query subscribers receive the updated value.
+
+From React, `data` just changes. There is no `refetch` call.
+
+## Query Descriptor
+
+```ts
+// apps/api/queries/notes.list.query.ts
+import { defineQuery } from '@voltro/protocol'
+import { Schema } from 'effect'
+
+export const listNotes = defineQuery({
+  name:   'notes.list',
+  source: 'notes',
+  input:  Schema.Struct({ archived: Schema.Boolean }),
+  output: Schema.Array(Schema.Struct({
+    id:    Schema.String,
+    title: Schema.String,
+  })),
+})
+```
+
+`source` declares which table re-runs computed queries and lets mutations with matching `target` metadata patch the client cache optimistically.
+
+## Query Executor
+
+```ts
+// apps/api/queries/notes.list.query.server.ts
+import { eq } from '@voltro/database'
+import { database } from '../database/schema'
+
+export default (input: { archived: boolean }) =>
+  database.notes.where(eq('archived', input.archived)).orderBy('createdAt', 'desc')
+```
+
+Descriptor-returning executors get fine-grained row matching. Computed-return executors can return arrays, objects, scalars, or `null`; they should declare `source` so the runtime knows what table should re-run them.
+
+## `skip`
+
+Use `{ skip }` when the input is not ready yet:
+
+```tsx
+const { data } = useSubscription(
+  'app',
+  'messages.list',
+  { channelId },
+  { skip: channelId === undefined },
+)
+```
+
+While skipped, no WebSocket subscription opens and `data` stays `undefined`.
+
+## Streams Are Different
+
+For non-database or transient element feeds, use [streams](/docs/data/streams), not subscriptions:
+
+```tsx
+const ticker = useAgentStream('app', 'ticker.watch')
+ticker.start({ symbol: 'BTC' })
+```
+
+Queries/subscriptions are for live state. Streams are for one-shot element flows such as tokens, progress events, and import logs.
+
+## Reconnect
+
+On reconnect, the client re-subscribes to active queries and receives a fresh snapshot. Optimistic patches are client-local and are reverted when their mutation settles.
+
+## Tenant Scoping
+
+Tables with the `tenant()` mixin are scoped by the runtime using `ctx.request.subject.tenantId`. Do not add duplicate tenant predicates in query executors unless you are deliberately narrowing further.
+
+## Inspect
+
+The devtools subscription surfaces show active subscribers, recent deltas, and cache state. Use them when a query updates too often or not at all.
+
+## See also
+
+- [Subscribers (`*.subscribe.ts`)](/docs/data/subscribers) — server-side, best-effort post-commit reactivity to a table (NOT the client hook on this page).
+- [Streams](/docs/data/streams) — transient, non-database element feeds (no snapshot/reconnect replay).
+
+
+
+---
+
+<!-- source: en/data/streams.md -->
+## Streams
+
+_`*.stream.ts` + `*.stream.server.ts` pairs — one-shot server-to-client element streams with defineStream and useAgentStream._
+
+A **stream** is a one-shot server-to-client feed. It emits plain elements, in order, and then finishes. It is not reactive, does not have snapshots or patches, and does not participate in auto-optimistic cache updates.
+
+Use streams for transient work: LLM token events, progress updates, import logs, provider events, or any server-side operation where the client should see elements as they arrive.
+
+Live — click Start and `{ n }` elements arrive one at a time (150ms apart), then
+the stream finishes (one-shot push, no snapshot/delta):
+
+```tsx
+const s = useAgentStream('app', 'progress.count')
+s.start({ to: 20 })   // s.events appends as elements arrive
+```
+
+## Minimal stream pair
+
+Descriptor:
+
+```ts
+// apps/api/streams/ticker.stream.ts
+import { defineStream } from '@voltro/protocol'
+import { Schema } from 'effect'
+
+export const ticker = defineStream({
+  name:    'ticker.watch',
+  input:   Schema.Struct({ symbol: Schema.String }),
+  element: Schema.Struct({
+    price: Schema.Number,
+    at:    Schema.Date,
+  }),
+})
+```
+
+Server executor:
+
+```ts
+// apps/api/streams/ticker.stream.server.ts
+import { Stream } from 'effect'
+
+export default (input: { symbol: string }) =>
+  Stream.fromAsyncIterable(
+    externalTickerStream(input.symbol),
+    (error) => error,
+  )
+```
+
+The executor can return `Stream`, `Effect<Stream>`, or a `Promise<Stream>`. The runtime binds it with `bindStream` and interrupts it when the client cancels or disconnects.
+
+## Client hook
+
+`useAgentStream` consumes any `defineStream` RPC, not only AI agents:
+
+```tsx
+import { useAgentStream } from '@voltro/client'
+
+const ticker = useAgentStream<{ price: number; at: Date }>('app', 'ticker.watch')
+
+return (
+  <>
+    <button onClick={() => ticker.start({ symbol: 'BTC' })}>Start</button>
+    <button onClick={ticker.cancel}>Cancel</button>
+    <ul>
+      {ticker.events.map((event, index) => (
+        <li key={index}>{event.price}</li>
+      ))}
+    </ul>
+  </>
+)
+```
+
+State shape:
+
+| Field | Meaning |
+|---|---|
+| `events` | Elements received so far, in order. |
+| `status` | `'idle'`, `'streaming'`, `'done'`, or `'error'`. |
+| `error` | Last stream failure when `status === 'error'`. |
+| `start(input?)` | Starts a new stream and clears previous events. |
+| `cancel()` | Interrupts the in-flight stream. |
+
+## Stream vs query
+
+| | Query | Stream |
+|---|---|---|
+| Files | `*.query.ts` + `*.query.server.ts` | `*.stream.ts` + `*.stream.server.ts` |
+| Descriptor field | `output` | `element` |
+| Client hook | `useSubscription` | `useAgentStream` |
+| Wire element | Subscription event envelope | Plain element |
+| Reactivity | Re-runs on matching writes | No automatic reactivity |
+| Persistence | Usually backed by database state | Transient unless you persist yourself |
+| Best for | Live data views | Token/progress/event feeds |
+
+If users should be able to reload the page and still see the result, persist rows and expose them through a query. If the stream is just live progress for the current run, keep it as a stream.
+
+## AI streams
+
+Transient agent runs are just streams whose elements are token/tool events. `useAgent` is an ergonomic wrapper over `useAgentStream`; durable chat uses a different pattern: an action writes/patches `agent_messages`, and a query streams those persisted rows.
+
+See [AI streaming](/docs/ai/streaming) and [Agents](/docs/ai/agents) for those patterns.
+
+## Anti-patterns
+
+- **Using streams as a database subscription replacement.** Queries already do this and handle reconnect snapshots.
+- **Streaming data that must be durable.** Put it in a table and subscribe to a query.
+- **Forgetting cancellation.** Long streams should release upstream resources when interrupted.
+
+## See also
+
+- [Subscriptions](/docs/data/subscriptions) — live, reactive query data with snapshot + reconnect replay (use this for durable row sets).
+- [Subscribers (`*.subscribe.ts`)](/docs/data/subscribers) — server-side post-commit reactivity to a table.
+
+
+
+---
+
+<!-- source: en/data/rest-routes.md -->
+## REST routes
+
+_defineRestRoute — public raw-HTTP endpoints (URL + JSON) for third parties that don't speak the rpc WebSocket. Schema-typed input/output, guards, deprecation/sunset, mounted on the same listener._
+
+The five primitives above ride one WebSocket — great for your own UI, wrong for a third party calling your API with a plain URL + JSON body. `defineRestRoute` (from `@voltro/protocol/rest`) is the public raw-HTTP surface: a schema-typed request/response endpoint that desugars to exactly one HTTP route on the **same** listener the rpc server + plugin routes use. It is NOT a separate runtime.
+
+```tsx
+// routes/v1/customers.list.route.tsx
+import { defineRestRoute, requireScope } from '@voltro/protocol/rest'
+import { Schema } from 'effect'
+
+export default defineRestRoute({
+  method: 'GET',
+  path:   '/v1/customers',
+  // Input shape is `{ query?, params?, body? }`. The desugar parses the
+  // query string, path params, and JSON body into this, then decodes it.
+  input:  Schema.Struct({
+    query: Schema.Struct({
+      limit:  Schema.optional(Schema.Number.pipe(Schema.between(1, 100))),
+      cursor: Schema.optional(Schema.String),
+    }),
+  }),
+  output: Schema.Struct({ data: Schema.Array(Customer), nextCursor: Schema.NullOr(Schema.String) }),
+  summary: 'List customers',                  // OpenAPI metadata — inert until a generator consumes it
+  guards:  [requireScope('customers:read')],  // → 403 when the subject lacks the scope
+  handler: async ({ query }, ctx) => {
+    const limit = query.limit ?? 20
+    // ctx = { subject, headers, store }. The auth resolver populates
+    // `subject`; `store` is the framework DataStore (cast at the call site).
+    return { data, nextCursor }
+  },
+})
+```
+
+## Registration
+
+REST routes are NOT auto-discovered by file suffix — register them explicitly via `restRoutes` in `app.config.ts` (the `*.route.tsx` filename is convention, not magic):
+
+```ts
+import listCustomers from './routes/v1/customers.list.route'
+
+export default {
+  type: 'api' as const,
+  name: 'publicApi',
+  restRoutes: [listCustomers],
+}
+```
+
+The module's `default` export is the descriptor — one descriptor per file, the same one-procedure-per-file discipline as `*.query.ts` / `*.mutation.ts`.
+
+## The request lifecycle (the desugar)
+
+Each descriptor becomes one HTTP route. Per request, in order:
+
+| Step | Outcome on failure |
+|---|---|
+| 1. Method gate | `405 Method Not Allowed` (`Allow:` header) |
+| 2. Sunset gate (past `sunset` date) | `410 Gone` + replacement pointer |
+| 3. Input decode (`{ query, params, body }` → schema) | `400 Bad Request` |
+| 4. Guards (after decode + ctx resolution) | the guard's `{ status, message }` (e.g. `403`) |
+| 5. `await handler(input, ctx)` | a thrown `{ status, message }` → that status; anything else → `500` |
+| 6. Output encode → JSON | `200 OK` |
+
+`deprecated` sets a `Deprecation: true` response header; `sunset` (an ISO date) sets a `Sunset:` header and, once past, flips the route to `410`. Both are pure metadata otherwise — the route keeps working until the sunset date.
+
+## `ctx` — what the handler gets
+
+```ts
+interface RestRouteContext {
+  readonly subject: Subject                              // resolved by the auth resolver
+  readonly headers: Readonly<Record<string, string>>     // request headers
+  readonly store: unknown                                // framework DataStore — cast at the call site
+}
+```
+
+The same `AuthMiddleware`/`ConnectionInfoMiddleware` that gate the rpc surface run here too, so a forwarded session cookie resolves the same `Subject` + tenant as the WebSocket path.
+
+## Guards
+
+A `RestGuard` runs after input decode, before the handler. Return `undefined` to proceed, or `{ status, message }` to short-circuit:
+
+```ts
+import { requireScope, type RestGuard } from '@voltro/protocol/rest'
+
+// Built-in: rejects 403 unless the subject carries the scope (admin '*' bypasses).
+guards: [requireScope('customers:read')]
+
+// Custom guard:
+const requireApiKey: RestGuard = (ctx) =>
+  ctx.subject.type === 'apiKey' ? undefined : { status: 401, message: 'API key required' }
+```
+
+## Idempotency (`Idempotency-Key`)
+
+Set `idempotency: true` in `app.config.ts` and every mutating REST request (`POST`/`PUT`/`PATCH`/`DELETE`) that carries an `Idempotency-Key` header is deduplicated:
+
+```ts
+// app.config.ts
+export default { type: 'api' as const, name: 'api', restRoutes: [chargeRoute], idempotency: true }
+// or: idempotency: { header: 'Idempotency-Key', ttlMs: 86_400_000 }
+```
+
+```bash
+# First call runs the handler + caches the response.
+curl -XPOST https://api.example.com/v1/charge -H 'Idempotency-Key: pay-abc' -d '{"amount":99}'
+#   → { "chargeId": "uuid-1", … }
+
+# A retry with the SAME key replays the cached response — the handler does NOT run again.
+curl -XPOST https://api.example.com/v1/charge -H 'Idempotency-Key: pay-abc' -d '{"amount":99}'
+#   → { "chargeId": "uuid-1", … }   (+ response header `Idempotency-Replayed: true`)
+```
+
+- **Replay** within the window returns the first response verbatim, with `Idempotency-Replayed: true`.
+- **In-flight duplicate** (the first call hasn't finished) gets `409`.
+- Keys are scoped per `(tenant, method, path)`, persisted in `_voltro_idempotency`, expiring after `ttlMs` (default 24h).
+
+This is the Stripe-style contract — the **client** opts in by sending the header. It's the standard for external API clients. Scope + guarantee:
+
+- **REST/HTTP only.** It rides the `Idempotency-Key` HTTP header. The WS rpc transport (`useMutation` from your own frontend) has no per-call header — guard double-submit there with optimistic UI + a disabled button, not server idempotency.
+- **Inbound webhooks already dedup** via [`@voltro/plugin-webhooks`](/docs/plugins/webhooks) (provider key + `_voltro_webhook_*`) — don't double-cover them.
+- **Atomic claim, non-atomic completion.** Two concurrent same-key requests resolve to exactly one execution (the `UNIQUE(scope,key)` insert is the arbiter). But the cached response isn't committed in the handler's own transaction — a crash between the handler committing and the record flipping to `completed` leaves the key in-flight (a retry `409`s until the TTL lapses, then re-runs). REST handlers aren't auto-transactional, so this is the honest ceiling.
+
+## REST route vs Action
+
+Both are unary request/response. Pick by transport + audience:
+
+| | [Action](/docs/data/actions) | REST route |
+|---|---|---|
+| Transport | rpc over WebSocket (+ `POST /rpc`) | public raw HTTP at a URL you choose |
+| Caller | your own UI via `useAction` | third parties with `fetch` / curl / SDKs |
+| Wire shape | the rpc JSON envelope | plain JSON body + status codes |
+| Typed errors | `Schema.TaggedError` on the rpc channel | HTTP status codes (`throw { status, message }`) |
+
+Use an action when your own client calls it; use a REST route when an external system needs a stable, documented URL. For signed inbound webhooks (Stripe, GitHub, …) use [`@voltro/plugin-webhooks`](/docs/plugins/webhooks) instead — it adds signature verification + idempotency on top.
+
+
+
+---
+
+<!-- source: en/data/aggregates.md -->
+## Aggregates
+
+_Pre-defined materialised queries that refresh on a schedule. The framework owns the lifecycle — discovery, refresh timer, cached rows, staleness metadata, dashboard surface._
+
+> **Not what you want?** For an on-demand `count` / `sum` / `groupBy` / window that runs when called (not on a schedule), see [Aggregations](/docs/database/aggregations) — the query-builder methods. This page is the SCHEDULED, materialised `*.aggregate.ts` convention.
+
+Use an aggregate for **a pre-defined query whose result should be computed once and served fast for many reads**. Top-N leaderboards. Most-used X over Y. Daily/weekly summary snapshots. Anything where the source query is expensive but the result is small and bounded.
+
+The framework discovers `*.aggregate.ts` files at boot, runs the build function on a schedule, holds the rows in a cache, and serves them via `useAggregate(def).read(...)`. You don't write a backing table, a refresh timer, a staleness check, or a dashboard surface — they're all part of the convention.
+
+## Why this instead of `*.cron.tsx`
+
+You could put the same logic in a cron handler: query the source, delete the cache table, insert the new rows. The aggregate convention earns its slot by owning seven things cron leaves to you:
+
+| Capability | Cron handler | `*.aggregate.ts` |
+|---|---|---|
+| Auto-create + manage backing storage | ❌ user defines table + migration | ✅ framework owns lifecycle |
+| Atomic refresh (no empty-window for readers) | ❌ DELETE-then-INSERT shows empty briefly | ✅ transactional swap |
+| `refreshedAt` metadata per aggregate | ❌ track manually | ✅ first-class |
+| Staleness-aware reads (`maxAgeMs` throw) | ❌ none | ✅ explicit |
+| Refresh overlap handling | ⚠️ generic cron | ✅ aggregate-specific |
+| `meta.lastError` for failures | ❌ user logs | ✅ surfaced |
+| Dashboard integration | ⚠️ generic cron entry | ✅ aggregate-specific (rows, last error, staleness) |
+
+## File shape
+
+```ts
+// apps/api/aggregates/topPlayers.aggregate.ts
+import { defineAggregate } from '@voltro/runtime'
+import { Schema } from 'effect'
+import { gt, gte, and } from '@voltro/database'
+import { database } from '../database/index'
+import { yearStart } from '../lib/time'
+
+export const TopPlayer = Schema.Struct({
+  playerId: Schema.String,
+  rank:     Schema.Number,
+  kd:       Schema.Number,
+})
+export type TopPlayer = Schema.Schema.Type<typeof TopPlayer>
+
+export default defineAggregate({
+  name: 'topPlayers',
+  refresh: '1h',                     // simple interval string
+
+  output: TopPlayer,                  // every row decoded against this
+
+  // Optional B-tree indexes on the DB-backed storage — honoured on the
+  // SQL stores; a no-op on the in-memory store (no secondary indexes).
+  indexes: [['rank']],
+
+  // The build function. Same `ctx.store` a mutation handler sees.
+  build: async (ctx) => {
+    const players = await ctx.store.query(
+      database.players
+        .where(and(gt('lastMatchAt', yearStart()), gte('kdRatio', 3.0)))
+        .orderBy('kdRatio', 'desc')
+        .take(100)
+        .descriptor,
+    )
+    return players.map((p, i) => ({
+      playerId: p.id as string,
+      rank:     i + 1,
+      kd:       p.kdRatio as number,
+    }))
+  },
+})
+```
+
+The default export must be the return value of `defineAggregate({...})`. The cli identifies files by checking for that branded shape — extra exports (like `TopPlayer` for the row type) are fine and conventional.
+
+## Reading from a handler
+
+```ts
+import { useAggregate } from '@voltro/runtime'
+import topPlayersDef, { type TopPlayer } from '../aggregates/topPlayers.aggregate'
+
+export default (input, _ctx) => Effect.gen(function* () {
+  const handle = yield* useAggregate(topPlayersDef)
+  const top10: ReadonlyArray<TopPlayer> = yield* handle.read({ limit: 10 })
+  return { top10 }
+})
+```
+
+The reading API is **explicit + namespace-only** — `useAggregate(def).read(...)`, not `database.topPlayers.findAll()`. This is a deliberate API choice (see [Why no virtual-table integration](#why-no-virtual-table-integration) below).
+
+### Read options
+
+```ts
+handle.read({
+  limit:    10,            // pagination
+  offset:   20,
+  orderBy:  'rank',        // any column in the output schema
+  direction: 'desc',
+  maxAgeMs: 10 * 60_000,   // throws AggregateStale if last refresh older
+})
+```
+
+There's deliberately no `filter` / `where` / `join`. If you need a different cut of the data, define another aggregate.
+
+### Metadata
+
+For dashboards, "data was last refreshed X minutes ago" UI labels, and operational health:
+
+```ts
+const meta = yield* handle.meta()
+// {
+//   refreshedAt: Date | null,           // null until first refresh
+//   rowCount: number,                    // last refresh result count
+//   durationMs: number,                  // how long the build function took
+//   lastError: string | null,            // last refresh error (null on success)
+//   nextRefreshAt: Date | null,          // when the next interval fires
+// }
+```
+
+`lastError` keeps the last failure visible without dropping the previous good rows — failing refreshes preserve last-good data. Reading `meta` after a failed refresh tells you the run failed; reading the rows still serves the last successful result.
+
+### Manual refresh
+
+```ts
+yield* handle.refresh()
+```
+
+Triggers an immediate refresh from the current handler. Use for "Run now" dashboard buttons or for cron-fed callers (your `*.cron.tsx` can drive aggregate refresh in custom windows that the aggregate's own interval policy doesn't cover).
+
+## Refresh policies
+
+Three forms — all three honoured at runtime:
+
+```ts
+refresh: '5m'                                                            // interval (string)
+
+refresh: { cron: '0 2 * * *', timezone: 'UTC' }                         // cron expression
+
+refresh: { interval: '1h', onChange: ['matches'], debounceMs: 30_000 }  // hybrid
+```
+
+- **Interval string** — fires every X. Parses `<n><unit>` where unit is `ms` / `s` / `m` / `h` / `d`. Invalid strings fail boot loudly.
+- **Cron expression** — `{ cron: '<expr>', timezone: '<iana-tz>' }`. The framework computes next-firing via the same `compileCron` / `Cron.next` the `*.cron.tsx` engine uses.
+- **Hybrid** — `{ interval, onChange: [<table>, ...], debounceMs }`. The interval is the upper bound; on every change to one of the listed tables, the framework debounces by `debounceMs` before firing. Use for "freshness on write but capped staleness".
+
+## Incremental maintenance (IVM)
+
+By default an aggregate **recomputes** — it re-runs its build query on each refresh
+(interval / cron / onChange). For a **bounded** aggregate you can opt into
+**incremental view maintenance**: each CDC delta on the source table updates the
+maintained value in place, with no full re-query.
+
+```ts
+export default defineAggregate({
+  name: 'sales.byRegion',
+  refresh: { onChange: ['orders'] },
+  output: SalesByRegion,
+  incremental: {
+    source: 'orders',
+    op: 'sum',                 // exactly one of count / sum / avg / min / max
+    column: 'amount',          // required for everything but count
+    groupBy: ['region'],       // one maintained row per group (optional)
+    toRow: (g) => ({ region: g.group['region'] as string, total: g.value }),
+  },
+})
+```
+
+**The shape must be maintainable** — `defineAggregate` throws at import (via
+`classifyShape`) otherwise:
+
+- exactly **one** op, from `count` / `sum` / `avg` / `min` / `max`;
+- a single `source` table (no joins);
+- no window functions, no `distinct`, no `having`.
+
+How it maintains, per delta on the source:
+
+- **count / sum / avg** — applied directly (insert adds, delete subtracts, update
+  adjusts); O(1) per change.
+- **min / max** — applied directly on insert/raise; a delete/lower of the current
+  extreme triggers a **bounded rescan** of that one group to find the new extreme.
+
+When a shape can't be incremental, leave `incremental` off and use a refresh
+policy — the engine recomputes. Incremental is an optimisation for hot, bounded
+aggregates, not a different result.
+
+## Boot strategy
+
+Each aggregate declares `bootRefresh` (default `'persistent'`). All three modes are wired in the aggregate runner (`attachAggregates`):
+
+| Mode | Behaviour | Use when |
+|---|---|---|
+| `'persistent'` (default) | Storage is rehydrated from the prior run's rows, so reads return the previous-good result immediately on restart; an async refresh then runs in the background and the first scheduled refresh fires at its natural time. | Most aggregates — best UX, no empty window on restart. |
+| `'async'` | Backing storage is reset at boot; the first refresh fires on the next tick, so reads return `[]` until it completes. | Test/dev fresh-start, or when stale data on restart would mislead. |
+| `'sync'` | Boot BLOCKS until the first refresh completes — slow boot, never serves stale data. | Pricing / business-critical computations. |
+
+A fresh-boot empty window only happens under `'async'`. If that would cause real bugs and you don't want `'sync'`'s slow boot, gate reads on `meta().refreshedAt` (or use `read({ maxAgeMs })` to throw `AggregateStale`).
+
+## Failure semantics
+
+A build function that throws **keeps the last-good rows in the cache**. The error message lands in `meta.lastError`. Reads continue to serve the prior result.
+
+This is intentional: a failing refresh shouldn't take down reads of the previous good aggregate. Last-good-data beats empty-on-fail.
+
+A build function that returns rows that fail `output` decode also records `lastError` (`output schema mismatch: row[N] failed output-schema decode at <path>: <issue>`). The cache stays at the last successful refresh.
+
+A second refresh starting while the first is still running is **skipped** — overlap-handling is `'skip'` by design. Long-running build functions don't pile up calls; they just slow the effective refresh rate.
+
+## Storage backends
+
+The framework picks per-store:
+
+- **Memory store** → in-process state, per-replica. Lost on restart; multi-instance fans out duplicate work. Fine for dev / single-pod deployments.
+- **SQL stores** (postgres / mysql / mariadb / mssql / sqlite / turso) → cross-dialect JSON-payload backing (`_voltro_aggregate_meta` + `_voltro_aggregate_rows` tables, auto-created on first boot). Atomic refresh via a generation counter — readers always see either the old generation or the new, never a mid-swap mix. Per-process in-memory mirror keeps reads sub-millisecond on the hot path.
+
+## Cluster coordination
+
+Aggregates inherit the framework's existing coordination story (plan 45). On `store: 'memory'` the runner uses `singleCoordinator` (one process); on real SQL stores it uses an `advisoryLockCoordinator` so multi-instance deployments fire exactly-one refresh per scheduled tick. No config needed — the runner picks based on the resolved store dialect.
+
+## Inspect surface
+
+Two endpoints under `/_voltro/inspect/`:
+
+```
+GET  /_voltro/inspect/aggregates                    — snapshot all + meta
+POST /_voltro/inspect/aggregates/<name>/refresh     — manual "Run now"
+```
+
+The cloud dashboard's Aggregates panel consumes these. Same auth resolver gates the surface as the rest of `/_voltro/inspect/*` (`VOLTRO_INSPECT_TOKEN` by default).
+
+## Refresh strategy — `'replace'` vs `'merge'`
+
+`strategy` controls how each refresh applies its rows:
+
+```ts
+defineAggregate({
+  name: 'topPlayers',
+  refresh: '1h',
+  output: TopPlayer,
+  strategy: 'replace',   // default — every refresh fully replaces the previous result
+  build: async (ctx) => { ... },
+})
+```
+
+```ts
+defineAggregate({
+  name: 'playerWins',
+  refresh: '5m',
+  output: PlayerWins,
+  strategy: 'merge',
+  mergeKey: 'playerId',  // required for 'merge' — each row's identity field
+  build: async (ctx) => {
+    // Only return players whose stats CHANGED since the last refresh.
+    // Players not returned this time KEEP their previous values.
+    return getPlayersWithRecentActivity()
+  },
+})
+```
+
+**`'replace'`** (default) — every refresh fully replaces the previous result. Rows from a prior refresh that the new build didn't return are dropped. Best for top-N leaderboards, summaries, snapshot-style aggregates.
+
+**`'merge'`** — upsert by `mergeKey`. Each row from `build()` either UPDATEs an existing entry (matched by `row[mergeKey]`) or INSERTs a new one. Prior rows whose key isn't in the new batch STAY. Best for "track per entity" patterns where each refresh only needs to recompute the changed entities (active players in the last hour, weapons used today, etc.). The `mergeKey` field MUST exist on every row your `build` returns — `defineAggregate` throws at registration if `strategy: 'merge'` is set without a `mergeKey`.
+
+Mental model: `'replace'` is "snapshot at time T"; `'merge'` is "incremental delta into a long-lived aggregate". Pick `'replace'` when an aggregate's value is the FULL recomputation; pick `'merge'` when each refresh contributes only the deltas.
+
+## Why no virtual-table integration
+
+The defining property of an aggregate is **the query is fixed in advance**. Treating it as a query-buildable virtual table (`database.topPlayers.where(...)`) opens four footguns:
+
+1. **Hidden staleness.** `database.topPlayers.where(...)` looks like a live query. Readers can't tell it's stale data.
+2. **Computation drift.** Adding `WHERE region='EU'` shifts the filter from refresh-time to read-time — the materialisation point IS the query; don't re-query it.
+3. **Misleading expectations.** Users would reflexively try `database.topPlayers.insert(...)`. Framework would either silently do nothing or error with a cryptic message.
+4. **Cross-timeline joins.** Joining an aggregate with a live table mixes two timelines (refresh-time + now). Mostly a footgun.
+
+The explicit namespace (`useAggregate(def).read(...)`) makes the materialisation explicit. Friction in the wrong direction (filtering, joining) is a feature — it pushes you to either define another aggregate or do the work in app code with clear boundaries.
+
+## Decision: aggregate vs subscriber vs cron
+
+| What you want | Use |
+|---|---|
+| In-transaction work tied to a write | mutation handler |
+| Reject the insert | `table().validate(Schema)` (schema DSL) |
+| Derive a value at write time | `column.computed(row => ...)` / `column.default(() => ...)` |
+| Best-effort post-commit per-row reactivity | [`*.subscribe.ts`](/docs/data/subscribers) |
+| Crash-safe post-commit reactivity | workflow invoked from `*.subscribe.ts` |
+| **Periodically-refreshed pre-computed query** | **`*.aggregate.ts`** (this) |
+| Event ingestion + time-bucketed aggregates over events | [Analytics sink](/docs/plugins/analytics) |
+| Real OLAP / 50M+ rows / arbitrary SQL | warehouse plugin (ClickHouse, DuckDB, Tinybird) |
+
+## Cross-plan: querying the warehouse from a build function
+
+The build function gets `ctx.analytics` alongside `ctx.store` — the configured [`AnalyticsSink`](/docs/plugins/analytics). `ctx.store` reads the main DataStore (OLTP); `ctx.analytics` reads the warehouse (OLAP: DuckDB / ClickHouse / postgres-lite). This is the first-class path for "reduce 10B warehouse events to a 100-row leaderboard materialised in the main store for fast reads":
+
+```ts
+import { defineAggregate } from '@voltro/runtime'
+import { Effect, Schema } from 'effect'
+
+export const TopPlayer = Schema.Struct({
+  playerId: Schema.String,
+  rank:     Schema.Number,
+  wins:     Schema.Number,
+})
+
+export default defineAggregate({
+  name: 'topPlayers',
+  refresh: '1h',
+  output: TopPlayer,
+  indexes: [['rank']],
+  build: (ctx) =>
+    Effect.gen(function* () {
+      // Warehouse query — reduces millions of events to the top 100.
+      const top = yield* ctx.analytics.topN({
+        event:   'match_completed',
+        groupBy: 'playerId',
+        metric:  'count',
+        n:       100,
+        range:   { from: new Date(Date.now() - 30 * 86_400_000) },
+      })
+      return top.map((entry, i) => ({ playerId: entry.key, rank: i + 1, wins: entry.value }))
+    }),
+})
+```
+
+`ctx.analytics` exposes the full sink contract — `topN`, `aggregate`, `timeseries`, and `track`. Like `ctx.store`, the build function runs as the system (no per-request subject).
+
+When no analytics sink is configured the framework provides the no-op sink: the read methods fail with `AnalyticsCapabilityNotSupported({ provider: 'noop' })`, which surfaces as a refresh error (last-good rows are preserved). Provider-specific queries beyond the four-method contract (raw SQL, HyperLogLog) live outside the sink — there is no raw-client escape hatch; query the provider with your own client instance inside the build function where you need them.
+
+
+
+---
+
+<!-- source: en/data/subscribers.md -->
+## Subscribers
+
+_Per-table post-commit reactivity via file convention. Default-exported defineSubscriber({ table, on, handler }) — fires AFTER commit, best-effort, fire-and-forget for async handlers._
+
+Use a `*.subscribe.ts` file when you want code to **run after every commit** to a specific table — refresh a search index, emit an external notification, invalidate a cache, push to a worker queue. The file convention is parallel to `*.startup.ts` / `*.cron.tsx` / `*.webhook.tsx`: drop a file matching the suffix anywhere under `apps/<api>/`, default-export a `defineSubscriber({...})`, the framework discovers + binds it at boot.
+
+Subscribers are deliberately **best-effort** + **non-durable**. For crash-safe async work, have the subscriber invoke a workflow.
+
+## File shape
+
+```ts
+// apps/api/subscribers/auditUserChanges.subscribe.ts
+import { defineSubscriber } from '@voltro/runtime'
+
+export default defineSubscriber({
+  table: 'users',
+  on:    'any',          // 'insert' | 'update' | 'delete' | 'any' | ['insert','delete']
+  handler: async (event, ctx) => {
+    ctx.log.info('user changed', {
+      op: event.op,
+      id: event.new?.id ?? event.old?.id,
+    })
+    // event.new — present on insert + update; null on delete
+    // event.old — present on update + delete; null on insert
+  },
+})
+```
+
+The default export must be a `defineSubscriber({...})` result. The file is identified by suffix (`*.subscribe.ts` / `*.subscribe.tsx`).
+
+## What fires when
+
+The framework binds to the store's `onChange` channel. Subscribers fire **after the transaction commits** — the row IS persisted when your handler runs. This means:
+
+- **You can read the just-committed row** via `event.new` (it's the committed value).
+- **You CAN'T reject the change** — by the time the handler runs, the transaction has landed. For pre-write rejection, use [`table().validate(Schema)`](/docs/database/columns#table-level-validation).
+- **No transaction boundary.** Side effects you do in the handler are not rolled back if some later operation fails.
+
+The `on` filter narrows by operation:
+
+- `'any'` (default) — every insert/update/delete fires the handler
+- `'insert'` / `'update'` / `'delete'` — single op
+- `['insert', 'delete']` — array of ops
+
+Other-table events get filtered out before your handler sees them. The matcher does this at the dispatcher level so subscribers add zero hot-path overhead to writes that don't match their table.
+
+## Semantics — best-effort, fire-and-forget
+
+Subscribers are **non-durable** by design:
+
+- **A throw doesn't fail the request.** The original mutation has already committed. The framework logs the failure (scoped to `subscribe:<filename>`) and the next event still arrives.
+- **Async handlers are NOT awaited by the dispatcher.** Fire-and-forget — a slow handler can't back-pressure the change stream. Errors propagate to the structured log via `.catch()`, but the change-emission path returns immediately.
+- **No retry, no resume.** If the process crashes mid-handler, the work is gone. Same if the network call inside the handler fails — there's no built-in retry policy.
+
+If you need any of those properties (transactional, durable, retried), invoke a workflow from inside the subscriber:
+
+```ts
+export default defineSubscriber({
+  table: 'orders',
+  on: 'insert',
+  handler: async (event, ctx) => {
+    // Best-effort kickoff. The workflow itself is crash-safe + retried.
+    await ctx.app.workflowClient.send('orders.fulfill', {
+      orderId: event.new!.id as string,
+    })
+  },
+})
+```
+
+The workflow body owns durability. The subscriber's job is just "translate row-change into workflow invocation".
+
+## Why this and not a regular subscription?
+
+A `useSubscription('app', 'todos.list')` is the right tool when the **client** wants live data — the framework pushes a delta over WebSocket and React re-renders. Subscribers are the server-side equivalent: when something **on the server** wants to react to a write — emit a notification, refresh an index, push to a queue — without round-tripping through a connected client.
+
+| What's reacting | Use |
+|---|---|
+| The browser, to show fresh data | `useSubscription` in a hook |
+| A server-side action, every commit | `*.subscribe.ts` (this) |
+| A server-side action, eventually-consistent + durable | `*.subscribe.ts` that kicks off a workflow |
+| A server-side action, in the same transaction | Do the work inside the mutation handler |
+
+## Decision tree — picking the right seam
+
+| What you want | Use |
+|---|---|
+| In-transaction work tied to a write | mutation handler |
+| Reject the insert | [`table().validate(Schema)`](/docs/database/columns#table-level-validation) |
+| Derive a value at write time | [`column.computed(row => ...)`](/docs/database/columns#computed-columns) / [`column.default(() => ...)`](/docs/database/columns#default-with-callback) |
+| **Best-effort post-commit reactivity per row** | **`*.subscribe.ts`** (this) |
+| Crash-safe post-commit reactivity | workflow invoked from `*.subscribe.ts` |
+| Periodically-refreshed pre-computed query | [`*.aggregate.ts`](/docs/data/aggregates) |
+| Event ingestion + analytical aggregates | [Analytics sink](/docs/plugins/analytics) |
+
+## Common patterns
+
+### Refresh a search index
+
+```ts
+import { meiliClient } from '../lib/meili'
+
+export default defineSubscriber({
+  table: 'posts',
+  on:    ['insert', 'update'],
+  handler: async (event) => {
+    if (!event.new) return
+    await meiliClient.index('posts').updateDocuments([event.new])
+  },
+})
+```
+
+### Mirror to an external system
+
+```ts
+export default defineSubscriber({
+  table: 'organizations',
+  on:    'insert',
+  handler: async (event, ctx) => {
+    if (!event.new) return
+    const slug = event.new.slug as string
+    // Best-effort sync; failure logs + continues
+    await fetch('https://my-crm.example/sync', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ slug, name: event.new.name }),
+    })
+  },
+})
+```
+
+### Soft-delete cleanup workflow
+
+```ts
+export default defineSubscriber({
+  table: 'documents',
+  on:    'update',
+  handler: async (event, ctx) => {
+    // Trigger a long-running cleanup ONLY when deletedAt was just set
+    if (!event.new || !event.old) return
+    if (event.old.deletedAt === null && event.new.deletedAt !== null) {
+      await ctx.app.workflowClient.send('documents.cleanupDeleted', {
+        documentId: event.new.id as string,
+      })
+    }
+  },
+})
+```
+
+The workflow does the heavy lift (scrub child rows, notify owners, archive to cold storage); the subscriber's job is just to detect the state transition.
+
+## Failure semantics in detail
+
+The framework logs subscriber failures via the structured logger — scope `subscribe:<filename>` — so you can grep + filter with `voltro logs --scope 'subscribe:*'`. Operations the handler reaches that themselves emit logs (HTTP client, store calls) keep their own scope.
+
+There's no retry. If a transient failure should be retried, do one of:
+
+1. Wrap the call in your own retry policy inside the handler (`Effect.retry`, `pRetry`, etc.).
+2. Move the work to a workflow that the subscriber just kicks off — workflows have first-class retry semantics.
+
+## By design
+
+The subscriber is a deliberately thin post-commit hook — the sharp edges below are choices, not gaps. When you outgrow them, the escape hatch is a workflow (durable, retried) or handler-side logic.
+
+- **One subscriber per file.** Multiple defaults exported don't compose; pick the most natural file boundary (one cohesive concern per file).
+- **Filter on `on` + table; per-row predicates live in the handler.** A predicate like "fire only when the user's plan changed" is a one-line guard at the top of the handler — kept there rather than in a framework pre-filter so the matching rule sits next to the code that reacts to it.
+- **No batching.** Each commit fires its subscribers individually. If a hot write path needs batched network calls, batch inside the handler (rolling window, debounce) — the framework doesn't impose a batching window you'd have to fight.
+
+## Configuration
+
+`*.subscribe.ts` files are discovered + bound automatically by `voltro dev` / `voltro start`. There's no `app.config.ts` flag — the file existing IS the registration.
+
+Subscribers fire AFTER the mutation handler commits, which happens AFTER any plugin `interceptMutation` chain returns. They're at the very tail of the write path:
+
+```
+client → AuthMiddleware → plugin interceptors → mutation handler → commit → subscriber handler
+```
+
+The subscriber sees the post-commit row, which has been auto-stamped by audit/tenant/softDelete mixins, validated against `table().validate(...)` if set, and persisted to the database.
+
+## See also
+
+- [Subscriptions](/docs/data/subscriptions) — the CLIENT-side `useSubscription` hook for live query data (different concept, similar name).
+- [Streams](/docs/data/streams) — transient element feeds; for crash-safe post-commit work, invoke a workflow from a subscriber.
+
+
+
+---
+
+<!-- source: en/data/reactions.md -->
+## Reactions
+
+_Standing reactive agents — a *.reaction.tsx watches a table and runs an agent/workflow on a change behind mandatory spend guards (dedupe / rate-limit / budget)._
+
+# Reactions (`*.reaction.tsx`)
+
+A **reaction** watches a table and, on a relevant change, runs an agent or
+workflow — behind MANDATORY spend guards. It's the data-driven sibling of a
+[subscriber](/docs/data/subscribers): where a subscriber is "run my code on a
+change," a reaction is "run an agent/workflow on a change, without footgunning a
+spend storm." Discovery + dispatch are automatic — drop a `*.reaction.tsx` file
+in and `voltro dev` binds it to the post-commit change stream.
+
+```tsx
+// reactions/flagBigOrder.reaction.tsx
+import { defineReaction } from '@voltro/runtime'
+
+export default defineReaction({
+  name:  'flagBigOrder',
+  watch: { table: 'orders', on: 'insert' },                 // table (+ optional op filter)
+  when:  (e) => Number((e.new as { total?: number })?.total ?? 0) > 1000,  // optional predicate
+  act:   { kind: 'workflow', workflow: 'orders.review' },   // run THIS workflow on the change
+  guards: {
+    // REQUIRED — a stable idempotency key so the same change acts ONCE. Without
+    // it, a reaction whose act writes the watched table self-triggers into a
+    // spend storm; defineReaction throws at boot if it's missing.
+    dedupeKey:     (e) => String((e.new as { id?: string })?.id ?? ''),
+    rateLimit:     { limit: 10, windowMs: 60_000 },         // optional per-reaction cap
+    costBudgetUsd: 5,                                        // optional per-tenant AI ceiling
+  },
+})
+```
+
+## How it fires
+
+Both `voltro dev` and `voltro serve` discover every `*.reaction.tsx`, bind it to
+the store's post-commit `onChange` channel, and on each change run the act
+through the guard chain: **op/table filter → `when` predicate → dedupe →
+rate-limit → budget**. The changed ROW is handed to the act — as the workflow's
+payload (so its payload schema should match the watched table's row), or seeded
+into the agent's prompt.
+
+## Guards (the point)
+
+- **`dedupeKey` (required)** — the same logical change acts exactly once. This is
+  what stops a reaction whose act writes the watched table from self-triggering
+  forever. `defineReaction` throws at boot if it's missing.
+- **`rateLimit` (optional)** — at most `limit` firings per `windowMs`.
+- **`costBudgetUsd` (optional)** — a per-tenant AI spend ceiling; over budget,
+  the reaction refuses (fails closed).
+
+## The two act targets
+
+- **`act: { kind: 'workflow', workflow }`** — starts the workflow on the change
+  (durable, retryable; the row is the payload). Reach for this when you need
+  durable multi-step orchestration.
+- **`act: { kind: 'agent', agent }`** — fires the agent headlessly: opens a fresh
+  thread, seeds it with the change as the prompt, and drives the synthesized
+  `<agent>.send` as the agent actor (tenant-scoped to the row). The assistant's
+  turn streams onto the durable `<agent>.messages` thread. Reach for this when a
+  standing agent should react in natural language.
+
+## Limits (v1)
+
+- Best-effort + fire-and-forget (like subscribers) — a failing act logs +
+  continues; it can't back-pressure the change stream. Durability comes from a
+  workflow act (an agent act is best-effort).
+- `dedupeKey` is in-memory per process in v1 (it stops the self-trigger storm
+  within a run); a durable cross-restart dedupe table is a follow-up.
+
+## When to use what
+
+- **Run my own code on a change** → [`*.subscribe.ts`](/docs/data/subscribers).
+- **Run an agent/workflow on a change, with spend guards** → `*.reaction.tsx` (this).
+- **Reject a write / derive a value at write time** → schema DSL
+  (`validate(Schema)` / `computed` / `default`).
+
+
+
+---
+
+<!-- source: en/data/wire-protocol.md -->
+## Wire protocol
+
+_What's on the WebSocket — @effect/rpc over JSON, the snapshot/delta subscription envelope, and the POST /rpc one-shot path._
+
+Voltro's client and api speak `@effect/rpc` over a WebSocket. Every primitive — queries, mutations, actions, agents, subscriptions — rides the one bidirectional connection, multiplexed by the rpc layer. The serialization is **JSON** (`RpcSerialization.layerJson`), not a bespoke binary format.
+
+You usually don't think about the wire — the typed client + `@voltro/protocol` handle it end-to-end. This page is for when you DO need to: debugging a mystery, proxying through a gateway, or understanding what the inspect tooling shows you.
+
+## The transport
+
+The api boots two rpc server instances on the same `HttpLayerRouter`:
+
+- **WebSocket** — `RpcServer.layerProtocolWebsocketRouter({ path })`, the primary transport. Long-lived; carries streaming queries (subscriptions), unary mutations/actions, and agent runs.
+- **HTTP one-shot** — `RpcServer.layerProtocolHttpRouter({ path: '/rpc' })`, registered at `POST /rpc`. Non-streaming; one request → one batched response.
+
+Both are provided `RpcSerialization.layerJson` and the SAME rpc group (`options.group`), so the SAME per-rpc handlers + the group-level `AuthMiddleware` / `ConnectionInfoMiddleware` run on either path. A forwarded session cookie resolves the same `Subject` + tenant whether the call arrives over WS or HTTP.
+
+Because `@effect/rpc` owns the framing, there's no app-level frame taxonomy to learn — the rpc client encodes a request, the server decodes it, runs the handler, and streams back the result. What's app-specific is the **payload schema** of each rpc (your `defineQuery` / `defineMutation` input + output) and, for streaming queries, the subscription-event envelope below.
+
+## Subscription events — snapshot / delta
+
+A streaming query (what `useSubscription` opens) emits a sequence of **subscription events**. The envelope is defined in `@voltro/protocol`'s `subscriptionEvent(output)` — a `Schema.Union` of three variants, parameterised on the query's declared `output` schema so the rpc layer enforces the row shape end-to-end:
+
+```ts
+// snapshot — always the FIRST event; the full initial query result
+{ _tag: 'snapshot', revision: number, data: <output> }
+
+// delta — every subsequent event; an id-keyed JSON-patch, NOT full data
+{
+  _tag: 'delta'
+  revision: number
+  emittedAt: number
+  patch: {
+    ops: Array<
+      | { op: 'add';     path: '/<id>'; value: <row> }
+      | { op: 'replace'; path: '/<id>'; value: <row> }
+      | { op: 'remove';  path: '/<id>' }
+    >
+    order: Array<id>   // the full id sequence of the next set, in order
+  }
+}
+
+// error — this ONE subscription's handler failed; surfaced in-band on its own
+// stream (never a defect that would stall siblings on the shared connection)
+{ _tag: 'error', error: { _tag?: string, message: string, ...fields }, revision?: number }
+```
+
+- **`revision`** — monotonically increasing; lets the client order events and detect gaps.
+- **`emittedAt`** — epoch milliseconds, present on `delta` only.
+- **`data`** (snapshot) — the full payload, typed by the query's `output` schema (a row, an array of rows, a computed value — whatever the handler returns).
+- **`patch`** (delta) — an id-keyed RFC-6902-style patch against the row set the client last held.
+- **`error`** — a JSON-safe shape of a typed error (its `_tag` + fields + `message` preserved, so the client can pattern-match `error._tag`). `useSubscription` exposes it as `.error` for THAT query key.
+
+The first event is always a `snapshot` carrying the full initial result — the client materialises it as its base. Subsequent events are `delta`s carrying **only the rows that changed**, plus the next id `order`. The server still re-runs the query on a change (the patch saves wire egress, not the re-query); it then diffs the previous row set against the new one into the patch.
+
+### Per-subscription errors — isolated, not connection-wide
+
+Many subscriptions multiplex over ONE WebSocket. If a single subscription's
+handler fails (e.g. a live single-row getter that throws for a stale/foreign
+id), the server emits an **`error` event on THAT subscription's own stream** and
+completes it — it does **not** let the failure become a defect, which would
+propagate to the shared connection and stall every *other* subscription on it
+(the classic "one not-found and the whole dashboard hangs on loading"). The
+client surfaces it as `useSubscription(...).error` for that one query key;
+siblings keep delivering their snapshots and deltas.
+
+**Author a live-subscribed getter to return, not throw.** A subscription is a
+long-lived stream, so a getter that throws on every re-evaluation is a broken
+stream. For an expected-absent row, make the query `output: Schema.NullOr(...)`
+and return `null` — that's a normal snapshot the widget renders as "empty",
+cleaner than an error banner. Reserve throwing for genuinely exceptional cases;
+even then it's now contained to the one subscription.
+
+### How the patch is keyed — by row `id`, not array index
+
+The diff keys on each row's `id`, addressing it as `path: '/<id>'`, rather than by array index. Index-based paths are brittle the moment a row moves — and reordering is the common case for the live result sets this targets (leaderboards, collaborative lists, game state). Id-keying makes a reshuffle cost just the changed rows plus the id list:
+
+- **`replace`** — a row present in both prev and next whose content changed; `value` is the full new row.
+- **`add`** — a row new in next; `value` is it.
+- **`remove`** — a row gone from next.
+- **reorder** — carried entirely by `order` (the next id sequence); a pure reorder emits **zero ops** and just a new `order`.
+
+The client keeps the last materialised row set, applies the ops to an id→row map, then materialises the result strictly in `order`. The round-trip is exact: applying the computed patch to the previous set reproduces the new set for every case — add, remove, replace, reorder, and combinations.
+
+**No-op suppression still applies.** When a change re-runs the query but the resolved row set is unchanged, no event is emitted at all — the patch path covers "a small part of a big result changed", the suppression covers "nothing changed".
+
+**Fallbacks.** A result set whose rows aren't id-keyed (a custom projection that drops `id`) can't be diffed by id, so its update ships as a full `snapshot` instead. Computed queries (a handler that returns a scalar or aggregate, not an id-keyed row set) likewise ship every update as a `snapshot` — there's no row set to patch.
+
+## HTTP one-shot rpc (`POST /rpc`)
+
+The WebSocket is the primary transport, but the api ALSO exposes `POST /rpc` for non-streaming invokes. It speaks the same JSON envelope and runs through the SAME per-rpc handlers + the same auth middleware — a forwarded session cookie resolves the same Subject + tenant as the WS path.
+
+This is what a server-side web-router loader's `ctx.query` uses: a loader runs inside the request handler with no WS connection, so it calls the backend over HTTP for SSR first-paint + `meta`. The HTTP protocol drains a streaming query handler's stream to completion and returns it, so a streaming query yields its FIRST (initial) `snapshot` in the response batch — exactly what first-paint needs. See [Loaders & meta](/docs/routing/loaders-and-meta#fetching-backend-data-with-ctx-query).
+
+For live, after-hydration data, subscribe over the WebSocket with `useSubscription` instead — `POST /rpc` is one-shot and never streams deltas.
+
+## Authentication
+
+The session cookie travels in the WebSocket upgrade headers (and in the `POST /rpc` request headers). The api's `AuthMiddleware` resolver decodes it and binds the resolved `Subject` to the connection; subsequent rpc calls on that connection inherit it.
+
+For API-key authentication, send `Authorization: Bearer <key>` in the upgrade (or request) headers — the same resolver path maps it to a `subject.type === 'apiKey'`.
+
+## Debugging
+
+Use the framework's own tooling rather than reading raw frames:
+
+- **`voltro traces`** — the per-request span waterfall, including each subscription `snapshot` / `delta` delivery with its produce→push latency. `voltro traces --errors` filters to failed hops.
+- **`voltro logs --trace <id>`** — every log line of one request across hops, in order.
+- The inspect dashboard's stream firehose (`GET /_voltro/inspect/stream`) surfaces rpc / cdc / log events live.
+
+## Anti-patterns
+
+- **Hand-crafting rpc frames.** Use `@voltro/client` — `@effect/rpc` owns the framing and the protocol can change.
+- **Long-polling fallbacks.** None — Voltro is WS-or-bust for live data. Browsers without WebSocket support don't get reactive updates (one-shot reads still work over `POST /rpc`).
+- **Proxying through a CDN without WebSocket support.** Cloudflare / Fastly / Vercel Edge all support it; configure the upgrade headers.
+
+
+
+---
+
+<!-- source: en/data/errors.md -->
+## Error handling
+
+_Schema-tagged error variants, runtime errors vs business errors, client narrowing, retry semantics._
+
+Voltro distinguishes **business errors** (typed, declared in the schema, expected) from **runtime errors** (unexpected exceptions, transport failures, framework bugs). Each surface has clear semantics.
+
+Live — `demo.greet` throws a typed `NameTooLong` for a name over 20 chars; the
+client narrows on `_tag` and reads the typed fields:
+
+```tsx
+const greet = useAction('app', 'demo.greet')
+try { await greet.run({ name }) }
+catch (e) { if (e._tag === 'NameTooLong') { /* typed: e.max, e.actual */ } }
+```
+
+## Business errors
+
+Declare your own with `Schema.TaggedError` — the class-extension form:
+
+```ts
+import { Schema } from 'effect'
+
+class InsufficientFunds extends Schema.TaggedError<InsufficientFunds>()('InsufficientFunds', {
+  required:  Schema.Number,
+  available: Schema.Number,
+}) {}
+
+class TitleTooLong extends Schema.TaggedError<TitleTooLong>()('TitleTooLong', {
+  maxLength: Schema.Number,
+}) {}
+```
+
+Wire them into a mutation / action / query via the `error` field:
+
+```ts
+export const transfer = defineMutation({
+  name:   'wallet.transfer',
+  input:  Schema.Struct({ to: Schema.String, amount: Schema.Number }),
+  output: Schema.Struct({ txId: Schema.String }),
+  error:  Schema.Union(InsufficientFunds, TitleTooLong),
+})
+
+export default async (input, ctx) => {
+  const wallet = await ctx.store.select('wallets').where('id', ctx.request.subject.id).one()
+  if (wallet.balance < input.amount) {
+    throw new InsufficientFunds({ required: input.amount, available: wallet.balance })
+  }
+  // …
+}
+```
+
+Client narrows on `_tag`:
+
+```tsx
+const transfer = useMutation('app', 'wallet.transfer')
+
+const result = await transfer.mutate({ to: 'usr-42', amount: 100 }).catch((e) => e)
+
+if (result._tag === 'InsufficientFunds') {
+  // result.required, result.available are typed
+  toast.error(`Need ${result.required}, have ${result.available}`)
+} else if (result._tag === 'TitleTooLong') {
+  toast.error(`Too long — max ${result.maxLength}`)
+} else if ('txId' in result) {
+  toast.success(`Transfer ${result.txId} complete`)
+}
+```
+
+Tagged errors:
+
+- Are wire-safe — they serialise as JSON (the rpc transport is `RpcSerialization.layerJson`) and restore on the client with the correct `_tag` + payload.
+- Narrow correctly in TypeScript via the `_tag` discriminant.
+- Carry typed payload fields.
+- Don't fire alerts / unhandled-promise-rejection signals — they're expected business outcomes.
+
+## Runtime errors
+
+Unexpected throws — `TypeError`, `RangeError`, framework bugs, third-party SDK failures — don't match the descriptor's `error` union, so they surface as **defects** rather than typed failures:
+
+- The throw is logged (via `@voltro/logger` to your configured sink).
+- The client sees a generic failure (no typed payload — runtime errors might leak sensitive context).
+- The trace records the throw + trace ID for cross-referencing; `voltro logs --trace <id>` returns the whole causal chain.
+- The trace is searchable in OpenTelemetry.
+
+To distinguish "we know about this" from "this surprised us":
+
+| Throw | Treatment |
+|---|---|
+| `throw new InsufficientFunds({ … })` (declared tagged error in `error:`) | Marshalled to the client typed, no log-volume increase |
+| `throw new Error('oops')` | Surfaces as a defect — full log + trace, generic failure to client |
+| Unexpected exception from a library | Same — caught, logged, generic failure |
+
+## Framework-shipped error variants
+
+`@voltro/protocol` exports exactly two tagged errors. The rest of your typed errors are ones you declare yourself (above) or ones a plugin / the runtime contributes.
+
+| Variant | From | When |
+|---|---|---|
+| `ScopeError` | `@voltro/protocol` | `requireScope(subject, scope)` failed — `{ required, message }`. |
+| `Unauthenticated` | `@voltro/protocol` | The resolved Subject is anonymous but a signed-in caller was required — optional `{ reason }`. |
+| `TenantScopeViolation` | `@voltro/runtime` | A tenant-scoped `EffectStore` write had no authenticated subject. |
+| `StoreOperationFailed` | `@voltro/runtime` | The underlying store operation failed (transient). |
+| `TableValidationFailed` | `@voltro/runtime` | A `table().validate(Schema)` row check rejected the write. |
+| `CacheError` | `@voltro/cache` | A cache backend op failed — `{ operation, key, cause }`. |
+| `RateLimited` | `@voltro/plugin-ratelimit` | The limiter rejected the call — `{ limit, retryAfterMs, resetAtMs }`. |
+| `TenantMismatch` | `@voltro/plugin-multitenancy` | `assertOwnTenant(input.tenantId, subject)` rejected a cross-tenant write. |
+
+Each plugin that ships an error (`RateLimited`, `EntitlementExceeded`, `StorageError`, `MailError`, …) merges it into every procedure's wire-error union, so the client decodes it typed without you adding it to each `error:`. To surface a runtime store error to the client, add it to the descriptor's `error:` union yourself (e.g. `error: Schema.Union(TenantScopeViolation, StoreOperationFailed, MyDomainError)`).
+
+All carry `_tag` + typed payloads, all narrow correctly on the client.
+
+## Loader errors
+
+Loaders run in the web app — they receive `{ params, query, headers, signal }`, NOT a server `ctx` with `.store`. A loader reaches the backend through `query(...)` (the `POST /rpc` path, server-side only). It short-circuits with the branded control-flow signals `NotFoundError` / `RedirectError`:
+
+```ts
+import { notFound } from '@voltro/web'
+
+export const loader = async ({ params, query }) => {
+  // `query` is present only server-side (SSR/ISR). Guard for client nav.
+  const note = query ? await query('notes.get', { id: params.id }) : undefined
+  if (!note) throw notFound(`note ${params.id}`)   // → scoped not-found.tsx / 404
+  return note
+}
+```
+
+A `NotFoundError` renders the scoped `not-found.tsx` subtree (it is NOT routed to the `error.tsx` boundary). A plain `throw new Error(...)` DOES hit `error.tsx`:
+
+```tsx
+export default function ErrorPage({ error, reset }: { error: Error; reset: () => void }) {
+  return <GenericError error={error} reset={reset} />
+}
+```
+
+See [Loaders & meta](/docs/routing/loaders-and-meta) for `NotFoundError` / `RedirectError` and the `ctx.query` SSR path.
+
+## Retry semantics
+
+| Surface | Auto-retry? | Notes |
+|---|---|---|
+| `useSubscription` | ✓ on disconnect | The api connection auto-reconnects with exponential backoff (`500ms × 2^(attempt-1)`, capped at 5s) and re-subscribes; the server replays the current snapshot. Reconnect attempts are not capped — it keeps trying until the connection is restored or the component unmounts. |
+| `useMutation` | ✗ | Mutations might be non-idempotent. Retry only when the operation is safe to repeat. |
+| `useAction` | ✗ | Same. |
+| `useAgentStream` / `useAgent` | ✗ | Streaming is hard to resume. Use a workflow for durable agent runs. |
+| Workflow steps | ✓ | Configurable per-workflow + per-step. |
+
+For mutations that are safe to repeat, wrap `mutate` in your own retry:
+
+```tsx
+const result = await retry(
+  () => create.mutate(input),
+  { attempts: 3, backoff: 'expo' },
+)
+```
+
+For operations that must be durable or exactly-once across disconnects, queue the work through a workflow and use database uniqueness constraints around the business key.
+
+## Validation errors
+
+Each rpc decodes its input against the declared `input` schema before the executor runs. A payload that fails the schema is rejected by `@effect/rpc` as a decode failure — the executor never runs. To surface field-level messages to a form UI, declare your own validation error and decode the input yourself in the handler:
+
+```ts
+import { Schema } from 'effect'
+
+class ValidationFailed extends Schema.TaggedError<ValidationFailed>()('ValidationFailed', {
+  errors: Schema.Array(Schema.Struct({ path: Schema.String, message: Schema.String })),
+}) {}
+```
+
+You can attach custom messages to the field constraints with `Schema.message`:
+
+```ts
+Schema.String.pipe(
+  Schema.minLength(1, { message: () => 'Title is required' }),
+  Schema.maxLength(200, { message: () => 'Title is too long (max 200 chars)' }),
+)
+```
+
+Schema-level row validation on a table (`table().validate(Schema)`) throws the runtime's `TableValidationFailed` — declare it in the mutation's `error:` to surface it typed.
+
+## Network errors
+
+A WebSocket disconnect interrupts in-flight unary calls — the awaited `mutate` / `run` rejects. The framework reconnects query subscriptions automatically; for mutations and actions, you decide whether retrying is safe:
+
+```tsx
+try {
+  await create.mutate(input)
+} catch (e) {
+  // Connection dropped mid-call. Wait for the api to reconnect, then retry
+  // ONLY if the operation is idempotent.
+  await waitForReconnect()
+  await create.mutate(input)
+}
+```
+
+## Anti-patterns
+
+- **Swallowing every error and showing "Something went wrong".** You're hiding genuine bugs. Let the dashboard's error pane + `voltro traces --errors` surface them; only catch the specific tagged variants you've declared.
+- **Throwing strings.** `throw 'oh no'` → surfaces as a defect, no useful payload. Use `Error` subclasses or `Schema.TaggedError` variants.
+- **`if (error instanceof InsufficientFunds)` on the client.** The wire-deserialised value isn't structurally identical to the server's class. Always check `_tag`.
+- **The curried `Schema.TaggedError('Name')({...})` form.** That doesn't type-check — use the class-extension form `class X extends Schema.TaggedError<X>()('X', {...})`.
+
+
+
+---
+
+<!-- source: en/data/cms.md -->
+## CMS
+
+_Headless CMS on the data layer — content types declared in code, derived draft/published tables, the ctx.cms read surface, and the saveDraft → publish write pipeline with save-time validation + derivation._
+
+`@voltro/cms` is a headless CMS built on the framework's own data layer. You
+declare a content type once, in code; the package compiles it to two real
+database tables (`<type>_drafts` + `<type>_published`) that auto-migrate picks
+up, gives you a typed read surface, and a write pipeline that enforces the
+schema's validation/derivation rules on every save.
+
+Two entry points keep the browser/server boundary clean:
+
+- `@voltro/cms` — the server entry: table derivation (`@voltro/database`),
+  the write pipeline, signed preview tokens (`node:crypto`), the REST mount.
+- `@voltro/cms/web` — browser-safe: the field DSL, the validation/derivation
+  engine + its typed errors (effect-only), and the `<ContentForm>` renderer
+  (react-only). An editor page pre-validates with the SAME rules the server
+  applies; a mutation descriptor can declare `error: ContentValidationFailed`
+  without dragging the server graph into the bundle.
+
+## Declaring a content type
+
+By convention each content type lives in a `*.contentType.ts` file. The field
+DSL is a plain-data descriptor language — validation rules travel as data and
+are applied at save time.
+
+```ts
+import { defineContentType, Schema, derivedFrom, slugify } from '@voltro/cms'
+
+export const blogPost = defineContentType({
+  name: 'blogPost',
+  displayName: 'Blog Post',
+  pluralName: 'Blog Posts',
+  fields: {
+    title:       Schema.String.pipe(Schema.maxLength(200)),
+    slug:        Schema.String.pipe(Schema.pattern(/^[a-z0-9-]+$/), Schema.unique(), derivedFrom('title', slugify)),
+    body:        Schema.RichText({ allowImages: true, allowEmbeds: false }),
+    tags:        Schema.Array(Schema.String),
+    publishedAt: Schema.DateTime.optional(),
+    coverImage:  Schema.Media().optional(),
+    author:      Schema.Reference('author'),
+    visibility:  Schema.Literal('public', 'unlisted', 'private'),
+  },
+  list: { columns: ['title', 'updatedAt'], defaultSort: { field: 'updatedAt', dir: 'desc' } },
+})
+```
+
+- `maxLength` / `pattern` are enforced by the save-time validator (and
+  `maxLength` also caps the shipped text widget).
+- `derivedFrom(source, transform)` marks a field computed-on-save: the
+  pipeline computes it from its source and **overwrites** a caller-provided
+  value — `slugify` is the canonical transform.
+- `unique()` marks a string field unique **per tenant** — the derived tables
+  get a real composite `(tenantId, field)` DB UNIQUE constraint (the database
+  rejects a duplicate slug within a tenant, not the app). Pair it with
+  `derivedFrom('title', slugify)` for a unique slug.
+- `Schema.RichText(options?)` stores a JSON document (e.g. a TipTap doc);
+  `allowImages` / `allowEmbeds: false` reject image/embed nodes (or `<img>` /
+  `<iframe>` / `<embed>` markers in string values) at save time. The shipped
+  default widget is a plain textarea placeholder — swap in a real editor via
+  the `ContentForm` `widgets` override.
+- `Schema.Media()` stores a storage object key as text (e.g. one issued by
+  `@voltro/plugin-storage`); resolve it to a URL after a read with
+  `resolveMedia` (below).
+- `list` describes the consuming editor's list view; every referenced name is
+  validated at definition time.
+- Reserved field names (`defineContentType` throws): `id`, `status`,
+  `tenantId`, `createdAt`, `updatedAt`, `createdBy`, `updatedBy`.
+
+`contentTypeToEntities(blogPost)` returns the `{ draft, published }` tables —
+register them in your `database/index.ts` so auto-migrate creates them. Both
+carry the lifecycle `status` column (`draft` / `published` / `archived`), the
+`tenant()` mixin (tenant-scoped reads/writes through the request store), and
+are `.reactive()` so a publish wakes live subscriptions.
+
+## Reading — `ctx.cms`
+
+`cmsContext(store, types)` builds the read surface over a request-scoped
+store; attach it to your `AppContext` and read it with `useCms(ctx)`. Reads
+target `<type>_published` and exclude `archived` rows.
+
+```ts
+import { cmsContext, useCms } from '@voltro/cms'
+
+const posts = await useCms(ctx)
+  .contentType('blogPost')
+  .where('publishedAt', '<=', new Date())
+  .orderBy('publishedAt', 'desc')
+  .limit(20)
+  .all()
+```
+
+`createCmsClient({ store, types })` is the same surface without a request
+handle (build-time / static-site generation). Signed preview tokens
+(`previewToken` / `verifyPreviewToken` / `cms.preview`) let an app read the
+draft row instead — see the package README for the token contract and the
+API-key-gated REST mount (`handleCmsRest`).
+
+## Writing — the pipeline
+
+The lifecycle ops take the caller's store first. Hand them `ctx.store` and
+every write rides the runtime's auto-scope spine: tenant + audit columns are
+stamped, reads are tenant-scoped, ids come from the table's id scheme.
+
+```ts
+import { saveDraft, publish, unpublish, archive } from '@voltro/cms'
+
+// derive → validate → write into blogPost_drafts (status: 'draft')
+const draft = await saveDraft(ctx.store, blogPost, input)
+
+// copy the draft into blogPost_published (same id), atomic per row
+const row = await publish(ctx.store, blogPost, draft.id as string)
+
+await unpublish(ctx.store, blogPost, draft.id as string) // remove the published copy, keep the draft
+await archive(ctx.store, blogPost, draft.id as string)   // status 'archived' — reads exclude it
+```
+
+`saveDraft` applies the `derivedFrom` derivations first, then validates the
+derived row — a rule on a derived field checks the value actually written.
+Violations throw `ContentValidationFailed` carrying **every** per-field
+violation (`{ field, rule, message }`), so an editor can annotate the whole
+form in one pass. Re-saving with `row.id` updates the caller's own draft;
+`publish` copies into the published table (insert on first publish, update
+after) and marks the draft in-sync.
+
+Tenant isolation is structural: a foreign id reads as absent through the
+scoped store (`ContentNotFound`), a caller-pinned `id` that exists only in
+another tenant is refused (`ContentIdConflict`), and a caller-provided
+`tenantId` never reaches a write — the pipeline owns the lifecycle columns.
+
+Handlers written in `Effect.gen` use the Effect-native siblings — the same
+typed error instances on the error channel:
+
+```ts
+import { Effect } from 'effect'
+import { saveDraftEffect, publishEffect } from '@voltro/cms'
+
+const program = Effect.gen(function* () {
+  const draft = yield* saveDraftEffect(ctx.store, blogPost, input)
+  return yield* publishEffect(ctx.store, blogPost, draft.id as string)
+}).pipe(
+  Effect.catchTag('ContentValidationFailed', (e) => Effect.succeed({ invalid: e.violations })),
+)
+```
+
+## The engine, standalone
+
+The validation/derivation engine is pure and exported on its own (also on
+`/web`) for custom write paths and client-side form validation:
+
+```ts
+import { validateContent, contentViolations, applyDerivations } from '@voltro/cms/web'
+
+const derived = applyDerivations(blogPost, formValue) // derivedFrom fields computed
+const violations = contentViolations(blogPost, derived) // pure — never throws
+validateContent(blogPost, derived) // throws ContentValidationFailed on any violation
+```
+
+## Scheduled publishing
+
+A draft can be marked to go live at a future time, then flipped live by a
+periodic sweep. `schedulePublish` stamps the draft's `publishAt` (a draft-only
+nullable column) without publishing now; `publishDue` publishes every draft
+whose time has passed.
+
+```ts
+import { schedulePublish, publishDue } from '@voltro/cms'
+
+// Mark a draft to publish later (does NOT publish now):
+await schedulePublish(ctx.store, blogPost, draftId, new Date('2026-01-01T09:00:00Z'))
+
+// Flip every due draft live (idempotent; returns the published ids):
+const publishedIds = await publishDue(ctx.store, blogPost, new Date())
+```
+
+`schedulePublish` keys off a tenant-scoped read (a foreign/missing id throws
+`ContentNotFound`) and leaves `status: 'draft'` until the row goes live.
+`publishDue` selects `publishAt <= now AND status = 'draft'`, runs the ordinary
+`publish` per row, and clears `publishAt` — idempotent, so a row is never
+double-published. It sweeps whatever store it is handed: a request store covers
+one tenant; a background/root store covers every tenant.
+
+`@voltro/cms` does not ship the scheduler — you drive `publishDue` from a
+`*.cron.tsx` schedule:
+
+```tsx no-check
+// apps/api/schedules/content-scheduler.cron.tsx
+import { defineSchedule } from '@voltro/runtime'
+import { publishDue } from '@voltro/cms'
+import { blogPost } from '../blogPost.contentType'
+
+export default defineSchedule({
+  name: 'contentScheduler',
+  cron: '* * * * *',
+  timezone: 'UTC',
+  // app.store has no request subject, so the sweep flips due drafts live
+  // across ALL tenants.
+  handler: async ({ app }) => {
+    await publishDue(app.store, blogPost, new Date())
+  },
+})
+```
+
+## Media resolution
+
+A `Schema.Media()` field stores a storage object **key**. Turning it into a
+served URL needs the storage service (its `getUrl` / `mintUrl` are
+Effect-returning and `mintUrl` needs the request `Subject`), so that context
+lives in your app — not the core package. Rather than couple `@voltro/cms` to a
+storage plugin, resolution is a typed hook: you supply a `MediaResolver`, and
+`resolveMedia` swaps every media key on a row (including media nested in
+`Array` / `Struct` fields) for the resolved URL.
+
+```ts
+import { resolveMedia, resolveMediaAll, type MediaResolver } from '@voltro/cms'
+import { Effect } from 'effect'
+
+const resolver: MediaResolver = (key) =>
+  Effect.runPromise(storage.mintUrl(key, ctx.subject)).catch(() => null)
+
+const post = await useCms(ctx).contentType('blogPost').where('slug', '=', 'hello').one()
+const withUrls = post ? await resolveMedia(blogPost, post, resolver) : null
+```
+
+`resolveMedia` returns a new row (the input is not mutated); a key the resolver
+returns `null` for is left as its stored key. `resolveMediaAll` maps a whole
+list; `mediaFields(type)` lists the top-level media field names.
+
+## Versioning content
+
+`@voltro/cms` ships no parallel revision system — the derived tables are
+ordinary database tables, so `@voltro/plugin-versioning` gives full row history
++ time-travel with no new machinery. List the derived table names in the
+plugin's `tables` option, then read a timeline or restore a snapshot:
+
+```ts no-check
+import { versioningPlugin, rowHistory, restoreAsOf } from '@voltro/plugin-versioning'
+
+// Register in your app's plugin list:
+versioningPlugin({ tables: ['blogPost_published', 'blogPost_drafts'] })
+
+const timeline = await rowHistory(ctx.store, 'blogPost_published', postId, tenantId)
+await restoreAsOf(ctx.store, 'blogPost_published', postId, tenantId, someEarlierDate)
+```
+
+## The editor form
+
+`<ContentForm>` (from `/web`) renders one labelled widget per field, driven by
+each field's editor hint — stateless and unstyled. Override any widget (e.g. a
+TipTap-backed `richText`) via the `widgets` prop:
+
+```tsx
+import { ContentForm } from '@voltro/cms/web'
+
+<ContentForm contentType={blogPost} value={row} onChange={setRow}
+  widgets={{ richText: MyTipTapWidget }} />
+```