@voltro/cli 0.24.0 → 0.25.0

package/dist/serveEntry.js

@@ -1,5 +1,5 @@
-import { Z as e } from "./inspectMetrics-dcC7gnxu.js";
+import { Z as e } from "./inspectMetrics-EQwH7BI4.js";
 import { c as t } from "./seedRunner-D6eu-u5U.js";
 import { r as n } from "./appModuleLoader-C9r9mxZt.js";
-import { t as r } from "./serveCommand-C4gzDZzc.js";
+import { t as r } from "./serveCommand-5ZFiNO1R.js";
 export { e as loadDotEnv, n as registerAppModules, t as registerDriver, r as runServe };

package/dist/{start-C_4VUDT8.js → start-C-ZWSDpg.js}

@@ -1,5 +1,5 @@
-import { $ as e, D as t, F as n, G as r, H as i, J as a, K as o, M as s, T as c, U as l, W as u, Y as d, _ as ee, a as te, b as f, c as p, dt as m, et as h, f as g, ft as _, g as ne, h as v, i as re, lt as y, m as b, mt as x, nt as ie, o as S, ot as C, p as w, pt as ae, r as T, rt as E, s as D, t as O, tt as k, v as A, w as j, x as M, y as oe, z as se } from "./inspectMetrics-dcC7gnxu.js";
-import { D as ce, E as le, T as ue, a as de, p as N, w as P } from "./inspect-_ldwsAwH.js";
+import { $ as e, D as t, F as n, G as r, H as i, J as a, K as o, M as s, T as c, U as l, W as u, Y as d, _ as ee, a as te, b as f, c as p, dt as m, et as h, f as g, ft as _, g as ne, h as v, i as re, lt as y, m as b, mt as x, nt as ie, o as S, ot as C, p as w, pt as ae, r as T, rt as E, s as D, t as O, tt as k, v as A, w as j, x as M, y as oe, z as se } from "./inspectMetrics-EQwH7BI4.js";
+import { D as ce, E as le, T as ue, a as de, p as N, w as P } from "./inspect-DuLUrZp9.js";
 import { t as fe } from "./bootTiming-BdyP9nYw.js";
 import { dirname as F, extname as I, join as L, resolve as R } from "node:path";
 import { fileURLToPath as z, pathToFileURL as B } from "node:url";

package/dist/startEntry.js

@@ -1,3 +1,3 @@
-import { Z as e } from "./inspectMetrics-dcC7gnxu.js";
-import { t } from "./start-C_4VUDT8.js";
+import { Z as e } from "./inspectMetrics-EQwH7BI4.js";
+import { t } from "./start-C-ZWSDpg.js";
 export { e as loadDotEnv, t as runStartCommand };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltro/cli",
-  "version": "0.24.0",
+  "version": "0.25.0",
   "description": "The `voltro` CLI — dev server, codegen, migrations, project scaffolding, agent-docs seeding, and production serve.",
   "keywords": [
     "voltro",
@@ -62,22 +62,22 @@
     "@effect/platform-node": "^0.108.0",
     "@effect/sql": "^0.52.0",
     "@effect/workflow": "^0.19.0",
-    "@voltro/ai": "0.24.0",
-    "@voltro/cache": "0.24.0",
-    "@voltro/data-transfer": "0.24.0",
-    "@voltro/database": "0.24.0",
-    "@voltro/env": "0.24.0",
-    "@voltro/kv": "0.24.0",
-    "@voltro/logger": "0.24.0",
-    "@voltro/plugin-auth": "0.24.0",
-    "@voltro/plugin-broadcast": "0.24.0",
-    "@voltro/plugin-mail": "0.24.0",
-    "@voltro/plugin-storage": "0.24.0",
-    "@voltro/plugin-webhooks": "0.24.0",
-    "@voltro/protocol": "0.24.0",
-    "@voltro/runtime": "0.24.0",
-    "@voltro/serverless": "0.24.0",
-    "@voltro/workflow": "0.24.0",
+    "@voltro/ai": "0.25.0",
+    "@voltro/cache": "0.25.0",
+    "@voltro/data-transfer": "0.25.0",
+    "@voltro/database": "0.25.0",
+    "@voltro/env": "0.25.0",
+    "@voltro/kv": "0.25.0",
+    "@voltro/logger": "0.25.0",
+    "@voltro/plugin-auth": "0.25.0",
+    "@voltro/plugin-broadcast": "0.25.0",
+    "@voltro/plugin-mail": "0.25.0",
+    "@voltro/plugin-storage": "0.25.0",
+    "@voltro/plugin-webhooks": "0.25.0",
+    "@voltro/protocol": "0.25.0",
+    "@voltro/runtime": "0.25.0",
+    "@voltro/serverless": "0.25.0",
+    "@voltro/workflow": "0.25.0",
     "chokidar": "^5.0.0",
     "ioredis": "^5.11.1",
     "tinyglobby": "^0.2.17",

package/templates/AGENTS.core.md

@@ -39,18 +39,24 @@ Workflows split the same way (`*.workflow.tsx` + `*.workflow.server.tsx`).
 
 Ask in order; stop at the first "yes":
 
-1. **Needs a LIVE feed that auto-updates on writes?** → **query** (`queries/`).
-   The only streaming primitive. Declares `source: 'table'` so writes invalidate it.
-2. **A single atomic DB write (one commit boundary)?** → **mutation** (`mutations/`).
+1. **Something HAPPENED, with no row behind it?** → **event** (`*.event.ts`).
+   A game started, a door opened, a terminal confirmed. It has a time and no
+   value afterwards, where a row has a value and no time. Ephemeral, fan-out to
+   every listening client, at-most-once. **If you are about to write a table so
+   that a subscriber fires, this is what you want.**
+2. **Needs a LIVE feed that auto-updates on writes?** → **query** (`queries/`).
+   The reactive read primitive. Declares `source: 'table'` so writes invalidate it.
+3. **A single atomic DB write (one commit boundary)?** → **mutation** (`mutations/`).
    Runs in a transaction; a throw rolls back; ChangeEvents drain only on commit.
    Declares `target: { table, op }` → drives client auto-optimistic.
-3. **External I/O — HTTP, file, AI, payment, email, signed URL?** → **action**
+4. **External I/O — HTTP, file, AI, payment, email, signed URL?** → **action**
    (`actions/`). NOT transactional; no rollback of side effects.
-4. **Multi-step work that must survive a crash/deploy, retry-from-where-it-died?**
+5. **Multi-step work that must survive a crash/deploy, retry-from-where-it-died?**
    → **workflow** (`*.workflow.tsx`). Durable, suspend/resume.
 
 | Use case | Primitive |
 |---|---|
+| A game starts / a door opens / a printer finishes — many screens react | Event |
 | List todos / messages on a page | Query |
 | Toggle a todo, send a message, edit a name | Mutation |
 | Generate a thumbnail / send a welcome email / call an LLM ad-hoc | Action |
@@ -248,6 +254,7 @@ public REST routes, declared via `restRoutes` in `app.config.ts`).
 | `*.mutation.ts` + `*.mutation.server.ts` | transactional unary write |
 | `*.action.ts` + `*.action.server.ts` | non-transactional external I/O |
 | `*.stream.ts` + `*.stream.server.ts` | server→client stream (e.g. AI tokens) |
+| `*.event.ts` | ephemeral fan-out event (`defineEvent`; no `.server` half) |
 | `*.workflow.tsx` + `*.workflow.server.tsx` | durable multi-step work |
 | `*.trigger.tsx` | domain event → workflow |
 | `*.cron.tsx` | scheduled job (single file) |

package/templates/AGENTS.md

@@ -39,18 +39,24 @@ Workflows split the same way (`*.workflow.tsx` + `*.workflow.server.tsx`).
 
 Ask in order; stop at the first "yes":
 
-1. **Needs a LIVE feed that auto-updates on writes?** → **query** (`queries/`).
-   The only streaming primitive. Declares `source: 'table'` so writes invalidate it.
-2. **A single atomic DB write (one commit boundary)?** → **mutation** (`mutations/`).
+1. **Something HAPPENED, with no row behind it?** → **event** (`*.event.ts`).
+   A game started, a door opened, a terminal confirmed. It has a time and no
+   value afterwards, where a row has a value and no time. Ephemeral, fan-out to
+   every listening client, at-most-once. **If you are about to write a table so
+   that a subscriber fires, this is what you want.**
+2. **Needs a LIVE feed that auto-updates on writes?** → **query** (`queries/`).
+   The reactive read primitive. Declares `source: 'table'` so writes invalidate it.
+3. **A single atomic DB write (one commit boundary)?** → **mutation** (`mutations/`).
    Runs in a transaction; a throw rolls back; ChangeEvents drain only on commit.
    Declares `target: { table, op }` → drives client auto-optimistic.
-3. **External I/O — HTTP, file, AI, payment, email, signed URL?** → **action**
+4. **External I/O — HTTP, file, AI, payment, email, signed URL?** → **action**
    (`actions/`). NOT transactional; no rollback of side effects.
-4. **Multi-step work that must survive a crash/deploy, retry-from-where-it-died?**
+5. **Multi-step work that must survive a crash/deploy, retry-from-where-it-died?**
    → **workflow** (`*.workflow.tsx`). Durable, suspend/resume.
 
 | Use case | Primitive |
 |---|---|
+| A game starts / a door opens / a printer finishes — many screens react | Event |
 | List todos / messages on a page | Query |
 | Toggle a todo, send a message, edit a name | Mutation |
 | Generate a thumbnail / send a welcome email / call an LLM ad-hoc | Action |
@@ -248,6 +254,7 @@ public REST routes, declared via `restRoutes` in `app.config.ts`).
 | `*.mutation.ts` + `*.mutation.server.ts` | transactional unary write |
 | `*.action.ts` + `*.action.server.ts` | non-transactional external I/O |
 | `*.stream.ts` + `*.stream.server.ts` | server→client stream (e.g. AI tokens) |
+| `*.event.ts` | ephemeral fan-out event (`defineEvent`; no `.server` half) |
 | `*.workflow.tsx` + `*.workflow.server.tsx` | durable multi-step work |
 | `*.trigger.tsx` | domain event → workflow |
 | `*.cron.tsx` | scheduled job (single file) |
@@ -595,7 +602,7 @@ each plugin's own README.
 
 | Topic | Open | Summary |
 |---|---|---|
-| **What's new in 0.23.0** | `node_modules/@voltro/cli/templates/agent-docs/whats-new.md` | Everything that changed in this version. Read it before hand-rolling something the framework may now ship. |
+| **What's new in 0.25.0** | `node_modules/@voltro/cli/templates/agent-docs/whats-new.md` | Everything that changed in this version. Read it before hand-rolling something the framework may now ship. |
 | AI | `node_modules/@voltro/cli/templates/agent-docs/ai.md` | How Voltro treats AI — agents, tools, streaming, RAG — all primitives over the same WebSocket as the rest of the framework. |
 | Authentication | `node_modules/@voltro/cli/templates/agent-docs/authentication.md` | How @voltro/plugin-auth wires password + session-cookie auth across api + web, plus the pluggable identity-strategy protocol. |
 | Caching | `node_modules/@voltro/cli/templates/agent-docs/caching.md` | Voltro's caching layer (@voltro/cache) — an always-on memory default, swappable Redis-compatible backends, a low-level wrap primitive, and automatic query-result invalidation. |
@@ -677,7 +684,7 @@ each plugin's own README.
 | storage | `node_modules/@voltro/plugin-storage/README.md` | File storage behind one StorageService — public objects served direct from the bucket/CDN, private objects gated by an access policy + per-object grants. S3 / R2 / GCS / MinIO / filesystem / memory providers, presigned URLs, a dashboard browser. |
 | tinybird | `node_modules/@voltro/plugin-tinybird/README.md` | Hosted-ClickHouse AnalyticsSink over Tinybird's Events API + Pipes — pay-as-you-go OLAP without operating a cluster. |
 | versioning | `node_modules/@voltro/plugin-versioning/README.md` | Full row history + time-travel. audit() records who/when; versioning records what-changed-to-what — a value snapshot of every row on every write, with as-of queries. |
-| webhooks | `node_modules/@voltro/plugin-webhooks/README.md` | First-class outgoing + incoming webhooks — defineOutgoingEvent / defineIncomingWebhook in *.webhook.tsx files, runtime subscriptions, durable delivery via @effect/workflow, HMAC signing, provider presets, and idempotency. |
+| webhooks | `node_modules/@voltro/plugin-webhooks/README.md` | First-class outgoing + incoming webhooks — declared events with a webhook: block, defineIncomingWebhook in *.webhook.tsx files, runtime subscriptions, durable delivery via @effect/workflow, HMAC signing, provider presets, and idempotency. |
 
 
 ---

package/templates/agent-docs/_index.md

@@ -9,7 +9,7 @@ each plugin's own README.
 
 | Topic | Open | Summary |
 |---|---|---|
-| **What's new in 0.23.0** | `node_modules/@voltro/cli/templates/agent-docs/whats-new.md` | Everything that changed in this version. Read it before hand-rolling something the framework may now ship. |
+| **What's new in 0.25.0** | `node_modules/@voltro/cli/templates/agent-docs/whats-new.md` | Everything that changed in this version. Read it before hand-rolling something the framework may now ship. |
 | AI | `node_modules/@voltro/cli/templates/agent-docs/ai.md` | How Voltro treats AI — agents, tools, streaming, RAG — all primitives over the same WebSocket as the rest of the framework. |
 | Authentication | `node_modules/@voltro/cli/templates/agent-docs/authentication.md` | How @voltro/plugin-auth wires password + session-cookie auth across api + web, plus the pluggable identity-strategy protocol. |
 | Caching | `node_modules/@voltro/cli/templates/agent-docs/caching.md` | Voltro's caching layer (@voltro/cache) — an always-on memory default, swappable Redis-compatible backends, a low-level wrap primitive, and automatic query-result invalidation. |
@@ -91,4 +91,4 @@ each plugin's own README.
 | storage | `node_modules/@voltro/plugin-storage/README.md` | File storage behind one StorageService — public objects served direct from the bucket/CDN, private objects gated by an access policy + per-object grants. S3 / R2 / GCS / MinIO / filesystem / memory providers, presigned URLs, a dashboard browser. |
 | tinybird | `node_modules/@voltro/plugin-tinybird/README.md` | Hosted-ClickHouse AnalyticsSink over Tinybird's Events API + Pipes — pay-as-you-go OLAP without operating a cluster. |
 | versioning | `node_modules/@voltro/plugin-versioning/README.md` | Full row history + time-travel. audit() records who/when; versioning records what-changed-to-what — a value snapshot of every row on every write, with as-of queries. |
-| webhooks | `node_modules/@voltro/plugin-webhooks/README.md` | First-class outgoing + incoming webhooks — defineOutgoingEvent / defineIncomingWebhook in *.webhook.tsx files, runtime subscriptions, durable delivery via @effect/workflow, HMAC signing, provider presets, and idempotency. |
+| webhooks | `node_modules/@voltro/plugin-webhooks/README.md` | First-class outgoing + incoming webhooks — declared events with a webhook: block, defineIncomingWebhook in *.webhook.tsx files, runtime subscriptions, durable delivery via @effect/workflow, HMAC signing, provider presets, and idempotency. |

package/templates/agent-docs/_manifest.json

@@ -53,7 +53,7 @@
       "group": null,
       "description": "How Voltro's reactive data layer works — queries, mutations, actions, streams, all over one WebSocket with typed errors and tracked dependencies.",
       "path": "agent-docs/data.md",
-      "files": 17
+      "files": 18
     },
     {
       "id": "database/advancedqueries",
@@ -134,7 +134,7 @@
       "group": "database.schema",
       "description": "Five generation schemes — TypeID (default), ULID, numeric, Snowflake, custom. Decision matrix, auto-injection lifecycle, cursor pagination, branded TypeScript types.",
       "path": "agent-docs/database/schema.md",
-      "files": 8
+      "files": 9
     },
     {
       "id": "database/seedsdialects",
@@ -608,7 +608,7 @@
     {
       "slug": "webhooks",
       "title": "Webhooks",
-      "description": "First-class outgoing + incoming webhooks — defineOutgoingEvent / defineIncomingWebhook in *.webhook.tsx files, runtime subscriptions, durable delivery via @effect/workflow, HMAC signing, provider presets, and idempotency.",
+      "description": "First-class outgoing + incoming webhooks — declared events with a webhook: block, defineIncomingWebhook in *.webhook.tsx files, runtime subscriptions, durable delivery via @effect/workflow, HMAC signing, provider presets, and idempotency.",
       "pkg": "@voltro/plugin-webhooks",
       "doc": "plugins/webhooks.md"
     }

package/templates/agent-docs/cli.md

@@ -2185,6 +2185,21 @@ A native dump is opaque: it doesn't say which dialect made it, which schema shap
 
 A backup with no stamp (older, or hand-made) restores with a caution rather than a hard stop.
 
+### The restore drill — prove the backup, don't assume it
+
+```bash
+voltro data restore ./backups/2026-07-01 --drill --drill-url postgres://…/scratch
+# or set DRILL_DB_URL and just: voltro data restore ./backups/2026-07-01 --drill
+```
+
+`--drill` restores the artifact into a **throwaway** database (from `--drill-url` / `DRILL_DB_URL`) and verifies it — **without ever touching the live DB**. It refuses a drill target that resolves to your live connection (a drill that `--clean`s production is the disaster it exists to rehearse against). After the restore it introspects the throwaway DB and compares its schema fingerprint to the backup's stamp:
+
+- **zero tables restored** → FAIL (the dump is empty or unreadable — this backup would not recover you),
+- **fingerprint disagrees with the stamp** → FAIL (the restore didn't reproduce what was backed up),
+- **tables + matching fingerprint** → PASS.
+
+It exits non-zero on any FAIL, so a scheduled CI job turns a silently-broken backup into a red build. Run it against your latest artifact on a cron — a backup you've never restored is a hypothesis, and this is how you keep it a fact. (The verify is schema-level; a full app boot against the restored DB is a heavier check you can layer on top.)
+
 ### Point-in-time recovery (PITR) is your database's job, not the framework's
 
 `backup` is a point-in-time **snapshot**. "Restore to 14:32, just before the bad deploy" (PITR) needs continuous WAL/binlog archiving, which lives at the database/provider layer — pg's `archive_command` + a base backup (pgBackRest / WAL-G), a managed provider's continuous backup (RDS, Cloud SQL, Neon, PlanetScale). The framework deliberately does **not** reimplement it: layer PITR under these native snapshots at the infra layer. A weekly `voltro data backup` + provider PITR together give you both a portable artifact and a fine-grained restore point.

package/templates/agent-docs/data.md

@@ -60,6 +60,7 @@ Voltro ships more building blocks than this one section holds — each is a type
 | **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) |
+| **Event** | `*.event.ts` | ephemeral fan-out to many clients → [Events](/docs/data/events) |
 | **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) |
@@ -75,7 +76,7 @@ Voltro ships more building blocks than this one section holds — each is a type
 
 ## 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).
+**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) · [Events](/docs/data/events) (`defineEvent` — things that HAPPEN, with no row behind them) · [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).
 
@@ -130,7 +131,7 @@ Every executor receives `ctx.request.subject` — the typed identity of the call
 | 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(...)` |
+| Fan a domain event out to one or more workflows | [`*.trigger.tsx`](/docs/workflows/event-triggers) + `ctx.events.publish(...)` |
 | 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) |
@@ -1593,6 +1594,309 @@ See [AI streaming](/docs/ai/streaming) and [Agents](/docs/ai/agents) for those p
 
 
 
+---
+
+<!-- source: en/data/events.md -->
+## Events
+
+_`*.event.ts` — ephemeral fan-out to connected clients with defineEvent, ctx.events.publish and useEvent. At-most-once, live, and it tells you when it lost something._
+
+An **event** is a thing that *happened*. It has a time and no value afterwards — where a table row has a value and no time.
+
+That distinction decides which primitive you want, and it is the only decision here that is hard to reverse later:
+
+| You are modelling | Use | Because |
+| --- | --- | --- |
+| **what happened** — a game started, a door opened, a terminal confirmed a payment | **Events** (this page) | nothing to store; a late arrival wants what happens *next*, not the history |
+| **what is** — the current roster, an order's status, a document | [Queries](/docs/data/queries) + [Subscriptions](/docs/data/subscriptions) | a late arrival wants the current value immediately |
+| **what must happen, even if we crash** — charge a card, send an invoice | [Outbox](/docs/data/outbox) | needs persistence, retries and a delivery guarantee |
+
+If you find yourself writing a table so that a subscriber fires, you want an event.
+
+## Declare it
+
+```ts
+// events/gameLifecycle.event.ts
+import { defineEvent } from '@voltro/protocol'
+import { Schema } from 'effect'
+
+export const gameStarted = defineEvent({
+  name: 'games.started',
+  key: Schema.Struct({ arenaId: Schema.String }),
+  payload: Schema.Struct({
+    gameId: Schema.String,
+    gameType: Schema.Literal('evo5', 'evo6'),
+    startedAt: Schema.Number,
+  }),
+  guards: [{ scope: 'display:read' }],
+})
+```
+
+A `*.event.ts` file is **browser-safe** and may hold several declarations — a lifecycle's stages are one concept. Client and server import the *same* value, which is what makes the key and payload types identical at both ends.
+
+**`key` is the address, and only the address.** A subscriber receives events published under a key it asked for, so the server never sends the others at all. Put in it what *routes* (`arenaId`) and nothing else — a discriminator your handler reads (`gameType`) is payload. Every key field fragments the subscriber set.
+
+**`guards` decide who may listen**, in the same vocabulary a query uses, and they are checked *before* the subscription is registered — a refused client never holds one. The routing key is the guard input, so a resource-scoped guard (`{ scope: 'arena:read', from: 'arenaId' }`) sees which arena was asked for. A refusal reaches the client as the `ScopeError` the rpc declares.
+
+**The tenant is not part of the key and must never be added.** It comes from the subject on both sides, so a cross-tenant delivery is impossible by construction rather than by remembering to filter.
+
+The name shares the rpc tag space. Two declarations answering to one name fail the **boot**, not the first delivery.
+
+## Publish it
+
+Only the server publishes. A client-originated event is an [action](/docs/data/actions) that publishes — which means every publish has already passed a guard-checked, typed handler, and there is no "who may write to this channel" question to answer.
+
+```ts
+// actions/reportGameEvent.action.server.ts
+export default (input, ctx) => Effect.gen(function* () {
+  yield* ctx.events.publish(gameStarted, { arenaId: input.arenaId }, {
+    gameId: input.gameId,
+    gameType: 'evo5',
+    startedAt: Date.now(),
+  })
+})
+```
+
+`publish` works from anywhere with a `ctx`: an action, a mutation, a workflow, a subscriber, a cron, a startup hook.
+
+**Inside a mutation it fires on COMMIT, and not at all on rollback.** That is not a nicety: a display reacting to a game start the database rolled back happens on every constraint violation, every deadlock retry, every guard that fails *after* the publish line. Outside a transaction it fires immediately.
+
+Three typed errors reach the **producer**, so a mismatch is one failing call rather than every consumer's handler breaking on a field that is not there: `EventPayloadInvalid`, `EventKeyInvalid`, `EventPayloadTooLarge`.
+
+<Callout>
+**Both handler styles publish.** `ctx.events.publish` returns an Effect, so the
+`Effect.gen` form above is the idiomatic one — but `await ctx.events.publish(…)`
+in a plain `async (input, ctx) => { … }` handler works too and resolves with the
+same result. It used to hand back an unrun Effect: nothing published, nothing
+errored, and the handler returned success.
+</Callout>
+
+## Consume it
+
+```tsx
+const { missed, status } = useEvent(gameStarted, arenaId ? { arenaId } : null, (payload) => {
+  scene.switchTo('running', payload.gameId)
+})
+```
+
+`payload` is typed from the descriptor — a wrong field name is a `tsc` error at this call site.
+
+Everything you would otherwise hand-roll is gone, and each of these was a real bug in apps that built this on a reactive list:
+
+- **No history on mount.** A fresh subscriber gets what happens *from now on*. No `seen` set, no `initialized` flag, no window.
+- **Exactly once, even under React `StrictMode`** — where every effect runs twice and a naive subscription fires each handler twice, in development only.
+- **A changing handler does not resubscribe.** Every call site passes an inline arrow; putting it in a dependency array rebuilds the subscription on every render and loses whatever arrives in the gap.
+- **A key change is a clean switch** — the old subscription ends before the new one starts.
+- **`key: null` means "not yet"**: no subscription, `status: 'idle'`. You never need a placeholder key.
+
+## What it guarantees — read this before you build on it
+
+- **At-most-once, best-effort, live.** No persistence, no retry, no redelivery. For guarantees use the [outbox](/docs/data/outbox); this is the other axis.
+- **Ordered per publishing instance per key.** *Not* globally per key — two instances publishing the same key have no shared counter, and we do not promise an order we cannot keep.
+- **Guards are re-checked when the subject changes**, not per delivery. Revoke a role and the stream ends.
+- **Payloads are capped at 7,500 bytes** of encoded envelope, on **every** dialect. An event says something happened, so carry a photo *reference*, not a photo.
+
+### `missed` is a number, not a feeling
+
+When deliveries are lost, you are told **how many** and **why**:
+
+```tsx
+useEvent(gameStarted, key, handler, {
+  onMissed: ({ count, reason }) => resyncFromServer(count),   // reason: 'buffer' | 'resume'
+})
+```
+
+Every delivery carries a serial, and the server keeps the highest it has seen — so a loss is arithmetic (what you were owed, minus what could be replayed), never an estimate. `buffer` means your client fell behind and the oldest were dropped; `resume` means a reconnect asked for messages older than the server still holds.
+
+This matters more than it sounds. Silence is the one outcome nothing can be built on: a display cannot tell "no game started" from "I missed the start signal".
+
+### Reconnects resume; mounts do not
+
+These read as one contradiction — *never replay history* against *never lose a message* — and they are two different questions:
+
+- **A first attach** starts empty. Set `rewind: true` on the descriptor if you want the recent buffer instead.
+- **A reconnect** continues from the last serial that subscription saw. `useEvent` does this for you, including after a deploy or a proxy timeout.
+
+The buffer is deliberately small — tens of messages, minutes. Anything larger is a durable queue, and the framework already has one.
+
+## Triggering a workflow from an event
+
+```ts
+triggerWorkflow({ on: gameStarted, workflow: 'postGameReport' })
+```
+
+`on:` takes the descriptor and reads its name, so renaming the event moves this call site with it. The older string form (`event: 'games.started'`) still works and is going away: with a string, a rename leaves the trigger matching nothing and the workflow simply never runs again — nothing errors, which is the same silence this whole primitive exists to remove.
+
+## Reaching HTTP receivers too
+
+An event can also be delivered to subscribed webhook targets — the third audience of the same declaration:
+
+```ts
+export const orderPaid = defineEvent({
+  name: 'orders.paid',
+  key: Schema.Struct({ orderId: Schema.String }),
+  payload: Schema.Struct({ total: Schema.Number }),
+  webhook: { description: 'An order was paid', version: 2 },
+})
+```
+
+One `publish` now reaches connected clients, every matching workflow trigger, and every subscribed HTTP target. Without this an app that does both declares the thing twice, in two shapes, and the two drift.
+
+The `webhook:` block is namespaced because its settings mean nothing to the other audiences — a top-level `retry` would read as if it applied to client delivery, which is at-most-once by design and has no retry at all. Requires [`@voltro/plugin-webhooks`](/docs/plugins/webhooks); absent, it costs nothing.
+
+## Across instances
+
+Local delivery always works. For fan-out across replicas the event rides postgres `LISTEN/NOTIFY` or [`@voltro/plugin-broadcast`](/docs/plugins/broadcast) (Redis / NATS), exactly like change events — and a broker outage degrades cross-replica delivery without touching local subscribers.
+
+**Each declared event gets its own channel** (`<namespace>:events:<name>`, where
+the namespace defaults to your app's name — see
+[broadcast](/docs/plugins/broadcast)), and a
+replica subscribes to it only while it actually has a local subscriber. This
+matters as soon as one event is much busier than the others: on a single shared
+channel every replica receives, decodes and tracks every event of every peer,
+including the ones it serves no clients for. With five replicas and a high-rate
+event whose subscribers all sit on one of them, four were doing that work and
+discarding the result.
+
+Nothing to configure — it follows from the declaration. The one operational
+consequence: during a **rolling deploy** replicas on different framework versions
+use different channel names, so cross-replica delivery is degraded for the length
+of the rollout. Local delivery on each replica is unaffected throughout.
+
+## Throughput — the numbers, and where this is the wrong primitive
+
+Measured on one core, publish path only:
+
+| | |
+| --- | --- |
+| `bus.publish`, 1–100 subscribers | ~1.5µs (**~670,000/s**) |
+| `bus.publish`, 1000 subscribers | ~3.1µs (~325,000/s) |
+| `ctx.events.publish` (validation + size gate + bus) | ~4.1µs (**~240,000/s**) |
+
+**Across replicas**, measured over a real Redis with two processes — 200 of 200
+delivered, no loss:
+
+| p50 | p95 | p99 | max |
+| --- | --- | --- | --- |
+| 1.67 ms | 2.91 ms | 6.58 ms | 9.95 ms |
+
+That is the broker round trip plus both bus hops. It is the number that matters
+for a display in another pod, and it is the one to compare against a hosted
+realtime service — where the same hop is a network round trip to someone else's
+region.
+
+**Fan-out is nearly free.** One subscriber and a hundred cost the same — the
+per-publish work dominates, not the delivery loop. What you pay per subscriber is
+the wire encode on its own subscription, not anything in the bus.
+
+For a game lifecycle — eight stage events per game, one publish each — that is
+several orders of magnitude of headroom. Even 100 players at 60Hz (6,000
+events/s) sits at ~2.5% of one core.
+
+### Where it stops being the right tool
+
+Not at a throughput number, but at a **semantic** one: this primitive guarantees
+at-most-once delivery of *every* message, with gap accounting. For a 60Hz stream
+of positions or cursors, that guarantee costs something and buys nothing —
+**nobody needs frame 1 once frame 2 has arrived.** You want last-value-wins state,
+not a delivery log.
+
+### `delivery: 'latest'` — when only the current value matters
+
+Declare it, and the framework stops treating a superseded value as a loss:
+
+```ts
+export default defineEvent({
+  name: 'player.moved',
+  key: Schema.Struct({ arenaId: Schema.String }),
+  payload: Schema.Struct({ playerId: Schema.String, x: Schema.Number, y: Schema.Number }),
+  access: 'authenticated',
+  delivery: 'latest',
+})
+```
+
+| | `each` (default) | `latest` |
+| --- | --- | --- |
+| A slow subscriber | keeps the newest, is told how many it lost | receives the current value |
+| Gap reporting | `missed` is computed and delivered | none — nothing was lost |
+| Server retention | up to 64 messages / 5 minutes | one value |
+| Reconnect | replays what is retained, reports the shortfall | hands over the current value |
+
+The distinction is **semantic, not performance**. `latest` is not "the fast mode":
+it changes what a missing message *means*. Choosing it for a stream where each
+delivery matters drops the ones in between; choosing `each` for a per-frame
+stream makes a slow client work through a backlog to reach a state it could have
+had immediately, and report a "loss" that was never one.
+
+The test: **would a consumer be wrong to miss one?**
+
+<Callout type="warn">
+`delivery: 'latest'` cannot be combined with `webhook`, and the declaration is
+refused. `latest` says a superseded delivery did not matter — but a webhook
+delivery is a durable side effect at a third party, and one already sent cannot
+be superseded. A 60Hz event with an HTTP audience is also 60 deliveries per
+second *per subscribed target*, and the webhook rate limit **defers** the excess
+as pending rows rather than dropping it, so the symptom is a growing table rather
+than an error anyone would look at. Publish the high-rate event for clients and a
+separate, coarser one for the outside world.
+</Callout>
+
+### Still worth avoiding
+
+- **Payloads over a few hundred bytes at high rate.** The size gate stops you at
+  7,500 bytes, and long before that the wire encode per subscriber becomes the
+  cost. Send a reference.
+- **Per-frame data as an event at all.** Even under `latest`, 60Hz of positions
+  is 60 encodes per second per subscriber. Coalescing on the client and
+  publishing at 10–20Hz is usually indistinguishable to a human and an order of
+  magnitude cheaper.
+
+The honest rule: **use an event when a consumer would be wrong to miss one.** If
+missing one is fine because the next one supersedes it, either declare
+`delivery: 'latest'` or model it as state — a table, or a value the client
+replaces.
+
+## Testing
+
+```ts
+import { testEventBus } from '@voltro/testing'
+
+const events = testEventBus()
+const display = events.subscribe(gameStarted, { arenaId: 'a1' })
+await events.publish(gameStarted, { arenaId: 'a1' }, { gameId: 'g1', gameType: 'evo5', startedAt: 0 })
+expect(display.received).toEqual([{ gameId: 'g1', gameType: 'evo5', startedAt: 0 }])
+
+// Force a loss deterministically instead of racing a queue:
+events.skipSerials(gameStarted, { arenaId: 'a1' }, 5)
+```
+
+It drives the real bus and the real publish path — validation, the size gate and serials all behave as they do in production — so a test cannot pass on a payload the server would reject.
+
+## Evolving a payload
+
+Clients decode against **their own** copy of the schema. Adding a field is safe. **Removing a required field breaks clients still running the old bundle**, loudly, at decode time — which is better than a silent `undefined` in a handler, and worth knowing if you ship to devices that do not reload for months. Treat those deployments as additive-only.
+
+## Anti-pattern: events as rows
+
+If you have this, replace it:
+
+```tsx
+// ✗ an events TABLE, reconstructed into "new" on the client
+const { data } = useSubscription('app', 'realtime.list', { limit: 500 })
+const seen = useRef(new Set()); const initialized = useRef(false)
+useEffect(() => { /* mark everything seen on the first pass, then diff */ }, [data])
+```
+
+Three bugs in nine lines, and every consumer has to get all three right: the `seen` set, the `initialized` flag (without it, loading the page replays 500 old events into a live system), and `limit` (a silent ceiling — nothing tells you when more than 500 arrive between renders). The table also grows forever and holds rows nobody reads twice.
+
+Migrating is mechanical: declare the event, replace the insert with `ctx.events.publish`, replace the hook with `useEvent`, and drop the table.
+
+## See also
+
+[Subscriptions](/docs/data/subscriptions) · [Outbox](/docs/data/outbox) · [Subscribers](/docs/data/subscribers) · [Streams](/docs/data/streams)
+
+
+
 ---
 
 <!-- source: en/data/rest-routes.md -->

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

@@ -1556,6 +1556,46 @@ no-ops out.
 
 The cloud dashboard surfaces per-env state with a multi-env tab in the [cloud UI](./cloud-ui.md).
 
+## Rehearsing a migration against real data
+
+The strongest check on this pipeline is not that each command exits 0 — it is that **no row moved that you did not ask to move**. A consumer running a MariaDB cutover built this loop and it caught three defects the framework's own suite did not; the method is theirs, written up here because the next person should not have to invent it.
+
+1. **Restore a backup into a throwaway database.**
+
+   ```sh
+   voltro data backup ./rehearsal .
+   DB_URL=$SCRATCH_URL voltro data restore ./rehearsal
+   ```
+
+   Use `data backup` / `data restore` — the NATIVE path — not the logical `data export`. The logical exporter re-shapes rows through the **current** declared schema, and the state a rehearsal exists to migrate *from* is precisely the one that does not match it.
+
+2. **Take an exact census, before.**
+
+   ```sql
+   SELECT table_name, COUNT(*) FROM ... -- one COUNT(*) per table
+   ```
+
+   It must be `COUNT(*)`. `information_schema.TABLE_ROWS` is an **estimate** on InnoDB — routinely off by thousands, and it is what a fast version of this check would reach for. The slowness is the point.
+
+3. **Run the exact production command sequence** — the same one your deploy Job runs, in the same order:
+
+   ```sh
+   voltro db files .
+   voltro db plan --json > plan.json
+   voltro db apply --plan plan.json
+   ```
+
+4. **Take the census again, and require the difference to be explainable.**
+
+   A healthy run moves one row: the `_voltro_migration_plans` ledger entry. Anything else is a question, not a result.
+
+**Two things the census must get right**, both learned by using it:
+
+- **A soft drop is not a loss.** With `VOLTRO_SOFT_DROP=1` a dropped table reappears as `<name>__dropped_<YYYYMMDDHHMMSS>` with its rows intact. Reporting that as a vanished table trains people to ignore the check; reporting it as clean hides a real drop. Give it its own category.
+- **A new table is not a discrepancy.** A migration that adds one produces a table with no "before" count. Say so explicitly rather than letting a zero read as data loss.
+
+To rehearse a schema several months old — the realistic case — craft the backup deliberately: a table a later migration added, a column a later one narrowed, a column the schema no longer declares. The planner is state-based, so it diffs live against declared and never replays a history; a six-month-old dump costs exactly one diff.
+
 ## File-based migrations in this pipeline
 
 `voltro db apply` runs pending `migrations/*.ts` **first**, then diffs — the same order the boot path uses.