@voltro/cli 0.28.0 → 0.30.0

package/templates/agent-docs/cli.md

@@ -19,18 +19,18 @@ The dispatcher routes `voltro <command> [args]` to the matching subcommand and p
 
 | Group | Commands |
 |---|---|
-| [Scaffolding](/docs/cli/scaffolding) | `create-project`, `add-app`, `list-templates` |
+| [Scaffolding](/docs/cli/scaffolding) | `create-project`, `add-app`, `list-templates`, `new` (scaffold one primitive — `query` / `mutation` / `action` / `workflow` / `page`) |
 | Packages | `package` (`create` / `publishable` / `private` / `status`), `create-package` |
-| [Dev](/docs/cli/dev) | `dev`, `codegen`, `agents-md`, [`env`](/docs/cli/env) (`check` / `sync` / `types` / `turbo`), [`generate`](/docs/cli/scaffolding) (AI app-builder), `dashboard` (serve the DevTools dashboard standalone; `--port`, `VOLTRO_DASHBOARD_APPS`) |
+| [Dev](/docs/cli/dev) | `dev`, `codegen`, `typecheck` (`tsc --noEmit` with the app's own TypeScript), `agents-md`, [`env`](/docs/cli/env) (`check` / `sync` / `types` / `turbo`), [`generate`](/docs/cli/scaffolding) (AI app-builder), `dashboard` (serve the DevTools dashboard standalone; `--port`, `VOLTRO_DASHBOARD_APPS`) |
 | [Build & run](/docs/cli/build-and-start) | `build`, `start`, `serve` |
 | Deploy | `deploy` (`plan` — auto-detect the target tier per app + function), [`serverless`](/docs/deployment/serverless-functions) (`list` / `dev` / `serve` / `build` / `deploy`), [`static`](/docs/deployment/static-sites) (`hosts` / `deploy`), `dormancy` (single-node scale-to-zero: fronts the app, stops it when idle, wakes on the next request; `--idle-grace-ms` / `--tick-ms`) |
-| [Database](/docs/cli/migrate) | `migrate`, `db` (`plan` / `apply` / `plans` / `drift` / `squash` / `restore-snapshot` / `migrate` / `rollback` / `status` / `seed`) |
+| [Database](/docs/cli/migrate) | `migrate`, `db` (`plan` / `apply` / `plans` / `drift` / `squash` / `restore-snapshot` / `migrate` / `rollback` / `status` / `seed`), [`evolve`](/docs/database/migrations/rename-and-drop) (schema-evolution copilot — propose a codemod + branch-verified backfill for a rename / retype / split / drop of an existing column or table) |
 | [Update](/docs/cli/update) | `update` (`--to` / `--dry-run` / `--force` / `--exact`) — bump every `@voltro/*`, install, run the codemods that adapt your source to the new version |
 | [Data transfer](/docs/cli/data) | `data` (`export` / `import` / `unpack` / `inspect` / `backup` / `restore`) — directory + single-file `.vbundle` bundles, streaming assets, masking, at-rest encryption |
 | Ops / infra | `cache` (`status` / `flush` / `invalidate`), `add` (`redis`), `baseline` (`list` / `status` / `set`), `schedule-manifest`, [`storage`](/docs/plugins/storage) (`doctor` / `cors`) |
-| AI / data | `embeddings backfill <table> --text <field> --vector <field>` — (re)embed rows the `vectorEmbedding()` mixin missed (pre-existing rows / a model change); `--dry-run` to preview |
+| AI / data | `embeddings backfill <table> --text <field> --vector <field>` — (re)embed rows the `vectorEmbedding()` mixin missed (pre-existing rows / a model change); `--dry-run` to preview; [`eval`](/docs/ai/agents#evaluating-recorded-runs-voltro-eval) — replay recorded agent runs against golden cases + judge, exit 1 on regression (a deploy gate; `--json` / `--branch` / `--threshold`) |
 | [Inspect & debug](/docs/cli/inspect) | `inspect`, `logs`, `traces`, `workflows`, `cluster`, `check` |
-| [Health & surface](/docs/cli/build-and-start) | [`doctor`](/docs/cli/build-and-start) — serve preflight + the hand-roll detector (names the shipped primitive at the spot you're rebuilding it); [`capabilities`](/docs/cli/build-and-start) (`--json`) — the export surface read from your installed `@voltro/*`, so it can be verified instead of recalled |
+| [Health & surface](/docs/cli/build-and-start) | [`doctor`](/docs/cli/build-and-start) — serve preflight + the hand-roll detector (names the shipped primitive at the spot you're rebuilding it); [`capabilities`](/docs/cli/build-and-start) (`--json`) — the export surface read from your installed `@voltro/*`, so it can be verified instead of recalled; `info` (`--json`) — CLI / node / package-manager / dialect + every installed `@voltro/*` version, flagging lockstep skew (exits 1 on skew) |
 | Harness | `test`, `e2e` |
 | Cloud | `cloud` (`login` / `whoami` / `projects` / `env` / `import`) |
 | Secrets | `secret` (`generate [purpose]` — the right var+format per secret; `generate` alone → a generic secret; `list`) |
@@ -69,7 +69,8 @@ The CLI reads:
 | `VOLTRO_LOG_FORMAT` | `pretty` / `json`. Force the logger's output format. |
 | `VOLTRO_LOG_LEVEL` | `trace` / `debug` / `info` / `warn` / `error` / `fatal`. |
 | `VOLTRO_INSPECT` | `off` to disable the `/_voltro/inspect/*` HTTP endpoints. |
-| `VOLTRO_INSPECT_TOKEN` | Bearer token for guarded inspect endpoints. |
+| `VOLTRO_INSPECT_TOKEN` | Bearer for the inspect surface. **Fail-closed:** unset → every request is `401`. `voltro dev` mints one per project; `voltro serve` / `voltro start` mint nothing, so a public deploy is closed by default (set it explicitly to open the surface). |
+| `VOLTRO_INSPECT_ALLOWED_HOSTS` | Extra `Host` names allowed to reach the **dev** inspect surface, past its DNS-rebinding guard (comma/space-separated). Loopback names + IP literals are always allowed; any other domain name is refused unless listed here — the api counterpart of vite's `allowedHosts`. |
 | `DB_URL` | Database connection string (falls back to `DB_PRIMARY_URL`; or the discrete `DB_*` / `PG_*` fields). |
 | `VOLTRO_SESSION_SECRET` | Session-cookie signing secret (`@voltro/plugin-auth`). Rotate with zero downtime: move the old value to `VOLTRO_SESSION_SECRET_PREVIOUS` for one session lifetime — cookies signed with either secret keep verifying, and previous-key cookies are re-issued under the new one. |
 | `VOLTRO_DATA_TRANSFER_SECRET` | Gates the prod data-transfer endpoints (`POST /_voltro/admin/{export,import}`); ≥16 chars or the routes don't mount. |
@@ -116,6 +117,47 @@ voltro build                   # vite build + SSG pre-render
 voltro start                   # production server
 ```
 
+### "Scaffold a new primitive the right way"
+
+`voltro new <kind> <name>` writes the correct file convention(s) so you don't
+learn the descriptor/executor split or the browser-safe boundary from a boot-time
+error. It refuses to overwrite an existing file unless you pass `--force`.
+
+```bash
+voltro new query notes.list          # notes.list.query.ts + notes.list.query.server.ts
+voltro new mutation notes.create     # descriptor + .server executor pair
+voltro new action notes.touch        # descriptor + .server executor pair
+voltro new workflow orders.fulfill   # .workflow.tsx descriptor + .workflow.server.tsx executor
+voltro new page about                # src-pages page.tsx under the name path
+voltro new query billing.summary --dir queries   # write into a subdirectory
+```
+
+The descriptor half imports only `@voltro/protocol` (or `@voltro/workflow/define`)
++ `effect` — browser-safe by construction; the server graph lives in the paired
+`.server` file. Fill in the `TODO`s, then `voltro dev` discovers it.
+
+### "Type-check before I commit"
+
+```bash
+voltro typecheck                     # tsc --noEmit against ./tsconfig.json
+voltro typecheck apps/api            # a specific app
+voltro typecheck --project tsconfig.build.json
+```
+
+It runs the **app's own** TypeScript (a `tsc --noEmit`), so "green" means tests
+AND types. Any flag it doesn't own passes straight through to `tsc`.
+
+### "What versions am I actually running?"
+
+```bash
+voltro info                          # CLI, node, package manager, dialect + @voltro/* versions
+voltro info --json                   # machine-readable; exits 1 on version skew
+```
+
+`@voltro/*` ship in lockstep, so a mismatch (e.g. `@voltro/database` a minor
+behind `@voltro/runtime`) means an untested graph. `voltro info` flags it and
+`voltro update` realigns everything.
+
 ### "Something's wrong — inspect what's running"
 
 ```bash
@@ -1025,6 +1067,37 @@ For WebSocket connections to land on the same backend (required for in-process s
 - Reverse proxy: `lb_policy ip_hash` (Caddy) / `ip_hash` (nginx).
 - Or use `@voltro/plugin-cluster` to share subscription state across instances → any-load-balancer-works.
 
+## `voltro build api --target <swift|kotlin>` — native SDK generation
+
+Generate a fully native mobile client from the same API bindings the TypeScript client is generated from. No hand-written models, no drift: the SDK is derived from your app's **capability manifest** — the exact procedure descriptors + JSON Schemas the framework already assembles from source — so every type stays in lockstep with the server.
+
+```bash
+voltro build api --target swift    apps/acme/api    # → apps/acme/api/sdk/swift  (Swift Package)
+voltro build api --target kotlin   apps/acme/api    # → apps/acme/api/sdk/kotlin (Kotlin Multiplatform)
+voltro build api --target swift --out ./ios/Sdk --name AcmeClient .
+```
+
+Flags:
+
+- `--target swift | kotlin` — the language to emit. Required.
+- `--out <dir>` — output directory. Default: `<appDir>/sdk/<target>`.
+- `--name <PackageName>` — the Swift package / Kotlin module name (PascalCase). Default `VoltroClient`.
+- `--kotlin-package <dotted>` — Kotlin source package. Default `com.voltro.client`.
+
+What each package contains:
+
+| Piece | Swift | Kotlin |
+|---|---|---|
+| Type-safe models | `Codable` structs + `String` enums | `@Serializable` data classes + enum classes |
+| One-shot client (query / mutation / action) | `async throws` methods over `URLSession` | `suspend` methods over Ktor |
+| Subscription client (streams) | `AsyncThrowingStream` over `URLSessionWebSocketTask` | `Flow` over Ktor WebSockets |
+| Auth + tenant context | `AuthContext` (bearer + `x-tenant` headers) | `AuthContext` |
+| Push registration | `PushRegistration` stub | `PushRegistration` stub |
+
+Type mapping is faithful: `string → String`, `integer → Int`, `number → Double/Double`, `boolean → Bool/Boolean`, arrays → `[T]` / `List<T>`, nested objects → their own named type, string-literal unions → an enum, and an **optional field** (one absent from the schema's `required` set, or a `NullOr`) becomes a Swift `Optional` / Kotlin nullable with a `= nil` / `= null` default.
+
+**Scope — this is the SDK code generator, not a native runtime.** Deliberately out of scope (they need a native runtime or managed infra, not generated client code): native module bindings (camera, biometrics), the APNs/FCM push **sender** (per-tenant Apple/Firebase credentials, provisioned server-side), and the managed OTA / EAS build pipeline. The generated source is verified at the generator level (golden-string tests over the emitted Swift + Kotlin). Compiling it with `swiftc` / Gradle is the remaining step in your own mobile CI — the framework harness has no Swift/Kotlin toolchain.
+
 ## `voltro doctor` — preflight a production serve
 
 Production `voltro serve` for an **API** app boots ONLY from the precompiled serve
@@ -1210,6 +1283,51 @@ since a rename or a deletion is decidable whatever the payload looks like.
 The required keys come from the live `payloadSchema`, the same source the runtime
 validation reads, so the two cannot disagree about what a payload needs.
 
+### The junction-FK check
+
+A link / junction table (`projectMembers`, `todoTagAssignments`) exists to connect two aggregates, so its columns are almost all foreign keys. Declared with `reference(() => projects)` the framework knows the edge — it enforces integrity, auto-indexes the FK, and can walk the reference graph. Declared as a bare `text()` id column the *same* edge is invisible: no FK, no auto-index, and nothing that walks references can follow it. Nothing type-checks the difference.
+
+`voltro doctor` flags a junction table with an id-shaped column that is a plain scalar and not a `reference()`:
+
+```
+junction FKs: 2 junction tables with an id column that is a plain text() and not a reference()
+  'todoListMembers': 'todoListId', 'userId' (part of a composite primary key)
+  'todoTagAssignments': 'todoId', 'tagId' (this table is nothing but link columns)
+  Declare each as reference(() => <table>): the FK is enforced, the column is auto-indexed,
+  and the relationship becomes walkable (a plain text() id column is an invisible edge).
+```
+
+It will **not** fire on any `*Id` text column — a `tenantId`, a `traceId`, an external-system reference are all legitimate plain-scalar shapes. It fires only when the table's OWN structure independently says "link table", and it names which signal tripped it so the finding is auditable rather than a bare accusation:
+
+| Signal | What it means |
+|---|---|
+| `part of a composite primary key` | the suspect column is a member of an explicit `primaryKey([...])` — the PK structure alone proves the row is a link |
+| `sits beside a wired reference() on this table` | a real `reference()` on a same-shaped sibling column, while this one is a bare scalar |
+| `this table is nothing but link columns` | the whole table is id-shaped columns + bookkeeping (a pure link table) |
+
+The audit reads the tables' **real declared `ColumnType`s** — the same materialised column definitions the migrator emits DDL from — never source text. So a `reference` is told apart from a plain scalar by its declared type, not a name regex, and a column name that only appears in a comment cannot trip it.
+
+### Event delivery + scale
+
+Two events with identical route / subscriber / buffer numbers can mean **opposite** things about a missing message — `each` counts a drop as a loss and tells the subscriber, `latest` supersedes the pending value and says nothing — and that mode is invisible once the app is running. So `voltro doctor` lists every declared event's delivery mode:
+
+```
+event delivery: 4 declared events — the mode decides what a MISSING message means
+  'games.started': each
+  'player.moved': latest
+  each   — every delivery matters; a slow subscriber loses the oldest and is TOLD how many (the default).
+  latest — a newer delivery supersedes a pending one; a slow subscriber gets the current value, told nothing.
+```
+
+It also **warns** on two shapes that will not scale the way the declaration reads — advisory, never blocking:
+
+| Warning | Why |
+|---|---|
+| **routing key has 3+ fields** | every key field is a routing address, and the count of distinct routes is the *product* of the fields' value spaces. Check each is an ADDRESS the delivery is decided by (`arenaId`), not a discriminator the handler reads (`gameType`) — the latter belongs in the payload, not the key. |
+| **`webhook:` on a per-frame event** | a webhook block on a name like `player.moved` / `cursor.moved` / `*.frameRendered` becomes N HTTP deliveries per second *per subscribed target*. The webhook rate limit **defers** the excess as pending rows rather than failing, so the symptom is a growing table. Publish a coarser event (a summary / state change) for the outside world. |
+
+The field count comes from the same schema-property reader the runtime validation uses, so it cannot disagree with the key the event actually routes on. Both findings appear in `voltro doctor --json` under `eventDelivery`.
+
 ### The hand-roll detector
 
 `voltro doctor` also scans your source for shapes the framework already has a
@@ -1735,16 +1853,35 @@ voltro workflows resume <runId>
 voltro workflows signal <runId> --name approval        # inject a named signal
 voltro workflows update <runId> --name …
 voltro workflows children <parentExecutionId>
+voltro workflows flow                          # the admission queue + ledger
+voltro workflows pause|unpause <workflowName>  # stop/restart admission fleet-wide
+voltro workflows cancel-many --reason "…"      # DRY RUN until --commit
+voltro workflows replay-many --mode redrive    # DRY RUN until --commit
+voltro workflows inferences                    # offloaded model calls in flight
 ```
 
+`inferences` shows what nothing else can: a run parked on an offloaded model call reads `suspended` in the run list with no step row yet, so during a slow provider — the moment you would look — the run list has nothing to say.
+
 Underneath, workflow state lives in the `_voltro_workflow_runs` + `_voltro_workflow_run_steps` tables and is surfaced live by the dashboard's Workflows panel. The same data is reachable over HTTP:
 
 ```bash
 curl -s localhost:$PORT/_voltro/inspect/workflows/runs | jq            # recent runs
 curl -s "localhost:$PORT/_voltro/inspect/workflows/runs/<runId>/steps" | jq   # step-by-step
 curl -s "localhost:$PORT/_voltro/inspect/workflows/runs/<runId>/events" | jq  # the run's event log
+curl -s "localhost:$PORT/_voltro/inspect/workflows/stats?hours=24" | jq       # bucketed run activity (the dashboard chart)
 ```
 
+The runs endpoint filters **server-side**, so a triage query over a large run history costs one narrow page instead of the whole table:
+
+```bash
+# multi-status + tag search + source + id-prefix + time range — all composable
+curl -s "localhost:$PORT/_voltro/inspect/workflows/runs?statuses=failed,cancelled&q=orders&source=workflow-rpc&idPrefix=wfrun_&from=2026-08-01T00:00:00Z&to=2026-08-08T00:00:00Z" | jq
+```
+
+`statuses` is a comma list; `q` is a case-insensitive tag substring; `idPrefix` matches the run id **or** the execution id (you never have to know which kind your log line carried); `from`/`to` bound `startedAt`. The dashboard's filter bar sends exactly these params.
+
+`/workflows/stats` returns ~48 buckets over a trailing window (`hours`, default 24, max 168; optional `tag`), each with `started` / `succeeded` / `failed` / `cancelled` counts, plus per-workflow totals. When the window held more runs than the scan cap, the response says `truncated: true` — the chart renders that as a warning, because a silently-truncated chart shows throughput dropping at exactly the moment it spiked.
+
 Each run row carries ID, name, status (running / succeeded / failed / dead), step count, last completed step, and duration. The per-run action endpoint matches `…/workflows/runs/<runId>/<action>` for `cancel` / `retry` / `suspend` / `resume` / `signal` — the `voltro workflows` subcommands and the dashboard's run-detail buttons both POST to these:
 
 ```bash

package/templates/agent-docs/configuration.md

@@ -265,6 +265,38 @@ const sync = resolveSecretSync('SESSION_SECRET')        // env-only fast path (s
 
 The field-encryption key (for `.encrypted()` columns — see [plugin-governance](/docs/plugins/governance)) resolves through this same backend. `governancePlugin({ fieldEncryption: true })` reads the secret `VOLTRO_FIELD_ENCRYPTION_KEY` (override with `fieldEncryption: { secretKey }`); point `secrets` at your vault and the key never touches an env file.
 
+## Live rotation — swap a secret without a restart
+
+The boot env gate resolves every secret once, at start-up. Rotating a leaked key normally means a redeploy. `@voltro/env/server` lets a running process cut over to a re-resolved value **and keep accepting the old one for a grace window** — so requests signed with the previous key still verify while callers catch up.
+
+```ts
+import { rotateSecretLive, getSecretWithOverlap } from '@voltro/env/server'
+
+// Re-resolve WEBHOOK_SIGNING_SECRET through the active backend and cut over,
+// holding the OLD value valid for a 5-minute overlap (the default).
+await rotateSecretLive('WEBHOOK_SIGNING_SECRET', { graceMs: 5 * 60_000 })
+
+// A verifier accepts BOTH during the overlap — try current first, fall back:
+const { current, previous } = getSecretWithOverlap('WEBHOOK_SIGNING_SECRET')
+```
+
+`getSecretWithOverlap(key)` returns `{ current, previous }` — the same current/previous pattern session verification uses for `VOLTRO_SESSION_SECRET` + `_PREVIOUS`. `previous` is present only while a rotation's grace window is open, then `undefined` (revoked lazily, on read — no timer). For a value you already have in hand (e.g. fetched from your own KMS), the lower-level `refreshEnvValue` installs it directly:
+
+```ts
+import { refreshEnvValue } from '@voltro/env'
+
+refreshEnvValue('WEBHOOK_SIGNING_SECRET', nextValue, {
+  previous: oldValue,      // held valid for the grace window
+  graceMs:  5 * 60_000,
+})
+```
+
+`refreshEnvValue` throws if called **before** the boot env gate ran — a live rotation is a post-boot operation that replaces a value the gate already resolved, not a way to set one that was missing.
+
+### What live rotation actually reaches — the honest bound
+
+This updates what code that reads a secret **per use** sees: outbound API keys resolved on each call, webhook-signing verification, `.encrypted()` field encryption. It does **not** reconnect a live resource built once, at boot, from the old credential — a database connection pool created with the previous password keeps that connection. Rotating a DB password stays a reconnect concern (drain + rebuild the pool, or redeploy); rotating a signing or outbound key is what this is for.
+
 ## Testing
 
 `setSecretsBackend(backend)` installs a backend for a test; `resetSecretsBackend()` restores the env default. `resolveSecretsBackend(config)` is the pure resolver the boot path uses to turn the `secrets` config value into a backend.

package/templates/agent-docs/data.md

@@ -1024,6 +1024,67 @@ const message = matchError(err, {
 }, () => 'Something went wrong')
 ```
 
+## Cross-table business rules — `.rule()`
+
+A [typed error](#typed-errors) is declared on ONE mutation. A **rule** is declared on a TABLE: an invariant the runtime enforces on EVERY mutation that writes that table, no matter which one did the write. Declare it in the schema with `.rule(name, predicate)`:
+
+```ts
+import { table, id, integer, eq } from '@voltro/database'
+import { database } from '../database/schema'
+
+export const invoices = table('invoices', {
+  id:    id(),
+  total: integer(),
+}).rule(
+  'totalMatchesLineItems',
+  async (row, { store }) => {
+    const items = await store.query(
+      database.lineItems.where(eq('invoiceId', row.id)).descriptor,
+    )
+    const sum = items.reduce((acc, l) => acc + Number(l.amount), 0)
+    return sum === row.total || { params: { computed: sum, declared: row.total } }
+  },
+)
+```
+
+The predicate receives the **post-write row** and a `context` whose `store` is the SAME transactional store the mutation wrote through — so a cross-table read shares the write's MVCC snapshot and cannot race it. It runs INSIDE the mutation transaction, after the write and before commit, and it is dialect-neutral (the same predicate is correct on all four dialects — no per-dialect code). Return `true` (or nothing) when the invariant holds; return `false` or a `RuleViolationDetail` (`{ params?, field?, message? }`) to signal a violation for THIS row.
+
+Unlike [`.check()`](/docs/database/columns#db-level-checks) — a single-row SQL `CHECK` the DATABASE enforces as DDL — a rule is a PREDICATE the runtime evaluates, so it can read OTHER tables. Use `.check()` when the database itself must guarantee a single-row constraint; reach for `.rule()` for a cross-table invariant (an invoice total matching its line items, a booking not exceeding a resource's capacity).
+
+### The violation is a typed error — automatically
+
+A violated `error`-severity rule rolls the whole mutation back and fails with the typed, wire-preserved **`BusinessRuleViolation`**. You do **not** declare it on the mutation's `error:` — the runtime auto-merges it into every mutation's error union at the wire boundary, exactly like `ScopeError`. A rule declared on a SCHEMA table can fail ANY mutation that writes that table, so no single descriptor could know to declare it; the auto-merge is what keeps the violation a typed error the client decodes by `_tag` rather than an untyped defect.
+
+Match it on the client the same way as any [typed error](#matching-typed-errors-on-the-client):
+
+```ts
+import { errorTag } from '@voltro/protocol'
+
+try {
+  await createInvoice(input)
+} catch (err) {
+  if (errorTag(err) === 'BusinessRuleViolation') {
+    // err.rule — the rule name; err.params — the offending values; err.field — the pointer
+  }
+}
+```
+
+`BusinessRuleViolation` carries `rule` (the declared name), optional `params` (i18n params for the offending values), an optional `field` pointer, and `severity` (always `'error'` on the wire — a warning-severity rule never reaches the client as an error).
+
+### `severity: 'warning'` — log without blocking
+
+```ts
+export const invoices = table('invoices', { id: id(), total: integer() }).rule(
+  'totalMatchesLineItems',
+  async (row, { store }) => true,
+  { severity: 'warning' },
+)
+```
+
+A `warning`-severity rule LOGS and audits the violation but lets the write commit — useful while backfilling data that does not yet satisfy a newly-added invariant. The default is `'error'` (roll back).
+
+Rules run on `voltro dev` and `voltro serve` through the same mutation runner, so the two boot paths cannot disagree about whether a rule fires. Inserts and updates on your own tables are re-validated; a delete is not (there is no post-write row to check).
+
 ## `internal: true` — off the wire entirely
 
 Every discovered `*.mutation.ts` / `*.query.ts` / `*.action.ts` / `*.stream.ts` is
@@ -1472,6 +1533,88 @@ A subscription that was live and is then skipped goes idle — it does **not**
 keep serving the snapshot it still holds. Otherwise `skip: !open` would show
 last time's data the moment a dialog reopens.
 
+## SSR preload — first paint with data
+
+By default a `useSubscription` on an SSR page flashes its empty/loading state on
+mount, THEN opens the WebSocket and fetches the first snapshot — even though the
+server could have fetched that value during the render. **`usePreloadedSubscription`**
+closes that gap: it reads its first value from the SSR hydration payload, renders
+real data on the first paint, then upgrades to the live stream the instant its
+first snapshot lands.
+
+Two things wire it up: the hook, and a `preload` export on the page.
+
+```tsx
+import { usePreloadedSubscription } from '@voltro/client'
+
+export const preload = ['notes.list']
+
+export default function NotesPage() {
+  const { data } = usePreloadedSubscription<Note[]>('app', 'notes.list')
+  // `data` is present on the first paint — no loading flash
+  return <NotesTable notes={data} />
+}
+```
+
+`export const preload` lists the subscriptions the page's tree needs at first
+paint. During the SSR render (`voltro dev` and `voltro start`) the framework runs
+each one server-side — the SAME `ctx.query(tag, input)` a loader receives — and
+seeds the result into the hydration payload. The client's
+`usePreloadedSubscription` finds the seed by the SAME cache key `useSubscription`
+uses, so the server markup and the client hydration render read an identical
+value — there is no hydration mismatch. The live subscription still opens and
+takes over; the seed is only the first value, never the source of truth.
+
+### `preload` entries
+
+An entry is either a bare tag or a tag plus an `input` derived from the route
+params:
+
+```tsx
+export const preload = [
+  'teams.list',                                                    // no input
+  { tag: 'project.detail', input: (params) => ({ id: params.id }) },
+]
+```
+
+The `input` you derive here MUST match the `input` you pass the hook — both
+address the same cache entry:
+
+```tsx
+export default function ProjectPage({ params }: { params: { id: string } }) {
+  const { data } = usePreloadedSubscription('app', 'project.detail', { id: params.id })
+  return <ProjectView project={data} />
+}
+```
+
+### Falls back to `useSubscription`
+
+When no seed exists for the key — a client-side SPA navigation the server never
+rendered, or the static prerender (which has no live api origin) —
+`usePreloadedSubscription` behaves EXACTLY like `useSubscription`: it loads until
+the stream answers. So it is always safe to reach for; the preload is a
+first-paint optimization, never a correctness dependency. A failed preload is
+likewise non-fatal — the live subscription still delivers the value on the
+client, the only loss is the first-paint seed.
+
+### Seeding by hand
+
+`export const preload` is sugar over an explicit seed. When a loader ALREADY has
+the value — you fetched it for the `<title>`, a breadcrumb, or the row name — seed
+it directly with `seedPreloadedSubscription` (server-side only) instead of
+fetching it a second time:
+
+```ts
+import { seedPreloadedSubscription } from '@voltro/client'
+
+// inside a loader / layout loader, server-side
+const notes = await ctx.query('notes.list', {})
+seedPreloadedSubscription('app', 'notes.list', {}, notes)
+```
+
+Calling it outside a server render throws — on the client the live subscription
+already provides the value, so a client-side seed would be meaningless.
+
 ## Streams Are Different
 
 For non-database or transient element feeds, use [streams](/docs/data/streams), not subscriptions:
@@ -2697,6 +2840,145 @@ export default defineAggregate({
 
 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.
 
+## Standing IVM siblings — expectations, cost budgets, experiments
+
+Three more primitives are built on the same engine as `defineAggregate({ incremental })` — they reduce a table to a value maintained incrementally from `store.onChange` CDC deltas (O(1) per write, no re-query). Unlike an aggregate you never `read()` a materialised table; you **observe a live signal** through a framework registry and a `useX(def)` handler-sugar. Each is discovered by its own file convention and wired into both `voltro dev` and `voltro serve`.
+
+| Primitive | File | Reduces a table to | Observe with |
+|---|---|---|---|
+| `defineExpectation` | `*.expectation.ts` | a `holding`/`violated` data-quality signal | `useExpectation` / `ExpectationRegistry` |
+| `defineCostBudget` | `*.budget.ts` | per-tenant compute-cost attribution + `ok`/`warn`/`exceeded` budgets | `useCostBudget` / `CostRegistry` |
+| `defineExperiment` | `*.experiment.ts` | per-variant metric + lift (live A/B / holdout) | `useExperiment` / `ExperimentRegistry` |
+
+They are **soft, observability-grade signals** — none of them ever blocks a write. Rejecting a write is a business rule's job (`table().validate(Schema)`); running an agent/workflow on a change is [`*.reaction.tsx`](/docs/data/reactions). These three only *watch* and *report*.
+
+### Data-quality expectations (`*.expectation.ts`)
+
+A `defineExpectation` is a standing data-quality contract over a table. Where dbt tests / Great Expectations run in BATCH and catch bad data hours later, an expectation re-evaluates on every write and tips `holding`↔`violated` the instant an invariant breaks — tracing the violation to the write that caused it (the CDC event's `traceId` / `subjectId` / `procedure`).
+
+```ts
+// apps/api/expectations/orderFreshness.expectation.ts
+import { defineExpectation } from '@voltro/runtime'
+
+export default defineExpectation({
+  name: 'orders-fresh',
+  on: { table: 'orders' },      // its CDC deltas drive re-evaluation
+  invariant: { kind: 'freshness', column: 'createdAt', maxAgeMs: 10 * 60_000 },
+  severity: 'critical',         // 'info' | 'warn' (default) | 'critical' — alerting priority only
+})
+```
+
+The default export must be the return value of `defineExpectation({...})` — the cli discovers `*.expectation.ts` files by that branded shape.
+
+Four invariant kinds, each reducing the table to one incrementally-maintained metric:
+
+```ts
+{ kind: 'freshness',   column: 'createdAt', maxAgeMs: 600_000 }              // newest row no older than X (re-checked on a clock tick too)
+{ kind: 'nullRate',    column: 'email', maxRate: 0.01 }                      // ≤ 1% of rows null in `column`
+{ kind: 'rowCount',    min: 1, max: 100_000 }                               // COUNT(*) within [min, max]
+{ kind: 'valueBounds', column: 'price', min: 0, max: 1000, maxViolationRate: 0.05 } // ≤ 5% of rows out of [min, max]
+```
+
+An optional `on.where` predicate narrows the population the invariant is asserted over — it runs server-side per row and never leaves the server, so it can be any predicate:
+
+```ts
+on: { table: 'orders', where: (row) => (row['status'] as string) === 'paid' }
+```
+
+Observe one expectation from a handler with `useExpectation`, or read the whole surface off `ExpectationRegistry`:
+
+```ts
+import { Effect } from 'effect'
+import { useExpectation } from '@voltro/runtime'
+import ordersFresh from '../expectations/orderFreshness.expectation'
+
+export default (input, _ctx) =>
+  Effect.gen(function* () {
+    const state = yield* useExpectation(ordersFresh)
+    // state: { status: 'holding' | 'violated' | 'unknown', metric, threshold,
+    //          since, lastEvaluatedAt, lastCause, ... } | null (null = not registered)
+    return { degraded: state?.status === 'violated' }
+  })
+```
+
+`ExpectationRegistry` exposes `snapshot()` (every expectation's state — the inspect feed), `get(name)`, `violations()` (the alerting view), and `subscribe(listener)` for `violated`/`recovered` transitions. A transition carries the causing write's provenance; a `freshness` SLA aging out with no write reports `cause: null` — the honest "no write caused this; the ABSENCE of writes did".
+
+### Cost budgets (`*.budget.ts`)
+
+A `defineCostBudget` is a reactive-FinOps primitive: per-tenant / per-subscription compute-cost attribution plus a budget every tenant is held to independently. It is to reactive compute what AI's `requireAiBudget` is to USD spend — a standing per-tenant ceiling that crosses `ok`→`warn`→`exceeded` and recovers on a window rollover.
+
+```ts
+// apps/api/budgets/tenantCompute.budget.ts
+import { defineCostBudget } from '@voltro/runtime'
+
+export default defineCostBudget({
+  name: 'tenant-compute',
+  limit: 100_000,       // the per-tenant ceiling, in the budget's unit
+  unit: 'recompute',    // which cost unit to meter; omit ⇒ the tenant's TOTAL across every unit
+  warnAt: 0.8,          // fraction of `limit` at which it goes 'warn' (default 0.8; set 1 to disable)
+  window: '24h',        // tumbling window — the counter resets each boundary; omit ⇒ cumulative since boot
+  severity: 'warn',     // 'info' | 'warn' (default) | 'critical'
+})
+```
+
+Observe one budget for one tenant with `useCostBudget(def, tenantId)`:
+
+```ts
+import { Effect } from 'effect'
+import { useCostBudget } from '@voltro/runtime'
+import tenantCompute from '../budgets/tenantCompute.budget'
+
+export default (input, ctx) =>
+  Effect.gen(function* () {
+    const state = yield* useCostBudget(tenantCompute, ctx.tenantId)
+    // state: { status: 'ok' | 'warn' | 'exceeded', spent, limit, warnThreshold, ... } | null
+    return { overBudget: state?.status === 'exceeded' }
+  })
+```
+
+`CostRegistry` exposes `attribution()` (per-tenant chargeback/showback rows — `total` + `byUnit` + `bySubscription`), `tenant(tenantId)`, `budgets()`, `budget(name, tenantId)`, `breaches()` (the alerting view), and `subscribe(listener)` for threshold crossings.
+
+> **Reactive recomputes now feed attribution automatically.** Declaring any `*.budget.ts` wires the dispatcher's `recordCost` tap in both boot paths: every time a source-row change re-runs an affected subscription and pushes it a delta, one `{ unit: 'recompute', amount: 1 }` cost event is attributed to that subscription's tenant (and traceId). So a tenant's `total`/`spent` populates from real reactive work — a `unit: 'recompute'` budget crosses `ok`→`warn`→`exceeded` as deliveries accrue, and recovers on a window rollover. The emission is **per delivered recompute** — one event per subscription the change fanned out to, on both the row-set and computed-query delivery paths. An app that declares NO cost budget wires no tap and allocates nothing on the reactive hot path.
+
+### Online experiments (`*.experiment.ts`)
+
+A `defineExperiment` is a live A/B / holdout experiment expressed as IVM aggregates. Assignment is a deterministic salted hash (subject → variant, no stored assignment table, reproducible on the client); the success metric is maintained PER VARIANT from the watched table's CDC — so lift vs a baseline is real-time, with no batch pipeline. It differs from `plugin-flags` (which GATES a code path) — an experiment MEASURES the outcome.
+
+```ts
+// apps/api/experiments/checkoutColor.experiment.ts
+import { defineExperiment } from '@voltro/runtime'
+
+export default defineExperiment({
+  name: 'checkout-button-color',
+  on: { table: 'orders' },                      // its CDC deltas drive the live recompute
+  subject: 'userId',                            // stable per-subject bucketing (a column name, or a (row) => key fn)
+  variants: [{ name: 'control' }, { name: 'green', weight: 1 }],   // ≥ 2 arms; `weight` skews the split (default 1)
+  holdout: 0.1,                                 // 10% held out entirely, for a clean untouched baseline
+  metric: { kind: 'conversionRate', column: 'completed' },         // per-variant success metric
+  baseline: 'control',                          // which variant lift is measured against (default: the first)
+})
+```
+
+Metric kinds: `{ kind: 'count' }`, `{ kind: 'sum', column }`, `{ kind: 'avg', column }`, and `{ kind: 'conversionRate', column, equals? }` (converted iff `row[column]` is truthy, or `=== equals` when given). `avg` / `conversionRate` are per-subject rates that a lift reads honestly; `count` / `sum` reflect exposure too, so their cross-variant comparison only means "more/less total".
+
+Observe the live result with `useExperiment`, or off `ExperimentRegistry`:
+
+```ts
+import { Effect } from 'effect'
+import { useExperiment } from '@voltro/runtime'
+import checkoutColor from '../experiments/checkoutColor.experiment'
+
+export default (input, _ctx) =>
+  Effect.gen(function* () {
+    const result = yield* useExperiment(checkoutColor)
+    // result: { totalExposure, baseline, variants: [{ variant, isBaseline, isHoldout,
+    //           exposure, metric, lift, diff }, ...], lastUpdatedAt, ... } | null
+    return { arms: result?.variants ?? [] }
+  })
+```
+
+Each variant row carries its `exposure` (sample size), the maintained `metric`, and — for non-baseline arms — `lift` (`(metric − baseMetric) / baseMetric`) and `diff` (absolute). `ExperimentRegistry` exposes `snapshot()`, `get(name)`, and `subscribe(listener)` for the live recompute stream that a results view redraws from. The same-subject-same-variant assignment is a pure function (`assignVariant(def, subject)`) a client can reproduce.
+
 
 
 ---

package/templates/agent-docs/database/migrations.md

@@ -658,6 +658,53 @@ export const users = table('users', {
 
 The cleanup is a separate PR after the migration has rolled out. Don't mix the rollout PR with the cleanup PR — the markers ARE the migration's audit trail until it's applied everywhere.
 
+## `voltro evolve` — the schema-evolution copilot
+
+Adding the `.renamedFrom()` marker by hand is easy for one column. The hard part of changing an EXISTING schema is the *rest*: which handlers read or write that column, whether a rename is safe or needs a backfill, and getting the annotation onto the entity AND every call site without missing one. `voltro evolve` does that reconnaissance and proposes a reviewable plan.
+
+Given a change, it reads the **observed graph** (`app.graph.observed.generated.json`, recorded by `voltro dev` — see [`voltro check`](/docs/cli/inspect)) plus the declared manifest, enumerates the real blast radius, and prints three things: a proposed **codemod**, a branch-verified **backfill** plan, and a `voltro check` **verify** step.
+
+```bash
+voltro evolve rename-column notes.title --to heading            # dry-run: plan + codemod preview
+voltro evolve rename-column notes.title --to heading --write    # apply the codemod
+voltro evolve retype-column orders.total --to numeric           # reshape → manual codemod + steps
+voltro evolve split-column users.name --into firstName,lastName
+voltro evolve rename-table note --to notes
+voltro evolve drop-column notes.legacy
+voltro evolve rename-column notes.title --to heading --json     # for CI / an agent loop
+```
+
+It is **dry-run by default** (mirrors `voltro generate`); `--write` applies the codemod through the same `runCodemods` toolkit as `voltro update`. `--json` emits the whole plan for CI or an agent.
+
+### The blast radius is observed, not guessed
+
+```text
+change: rename-column notes.title → heading
+
+blast radius (observed + declared):
+  query(notes.list) — observed read
+  mutation(notes.update) — observed update
+  ⚠ 1 declared but NEVER exercised — column use UNKNOWN: notes.archive
+
+codemod:
+  entity: rename 'notes.title' → 'heading' and add .renamedFrom('title') (catalog rename — data preserved)
+  annotate 2 handler site(s) that reference the old field
+
+backfill (dry-runs on branch notes-pr-0):
+  [safe] catalog RENAME — no data movement
+
+verify: voltro check
+```
+
+A handler that a `voltro dev` session or a test actually ran is reported with what it did (`observed read` / `observed update`). A handler that is *declared* to touch the table but was **never exercised** is flagged `UNKNOWN` and listed separately — it is never folded into "safe", because no run proves what it does with the column. That honesty is the point: the tool tells you exactly where it cannot vouch for the change.
+
+### What the codemod does per kind
+
+- **`rename-column`** gets a real `transform`: it renames the field in the `*.entity.ts` AND chains **`.renamedFrom('old')`** (so the differ plans a catalog RENAME, not the lossy drop+create described [above](#renamedfromoldname)), then annotates the handler sites the blast radius found.
+- **`retype-column` / `split-column` / `drop-column` / `rename-table`** are reshaping changes with no single mechanical rewrite, so they get a **`manual`** codemod: a generated, numbered checklist of the edits + the annotation to add, printed for you to apply.
+
+`voltro evolve` produces the plan; it does not apply the schema change. **`voltro check` is the gate on the result**, and `voltro db apply` lands it — after `--write`, review the annotated handlers, then run those two.
+
 
 
 ---