@voltro/cli 0.23.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-Cl8sicD5.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.23.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.23.0",
-    "@voltro/cache": "0.23.0",
-    "@voltro/data-transfer": "0.23.0",
-    "@voltro/database": "0.23.0",
-    "@voltro/env": "0.23.0",
-    "@voltro/kv": "0.23.0",
-    "@voltro/logger": "0.23.0",
-    "@voltro/plugin-auth": "0.23.0",
-    "@voltro/plugin-broadcast": "0.23.0",
-    "@voltro/plugin-mail": "0.23.0",
-    "@voltro/plugin-storage": "0.23.0",
-    "@voltro/plugin-webhooks": "0.23.0",
-    "@voltro/protocol": "0.23.0",
-    "@voltro/runtime": "0.23.0",
-    "@voltro/serverless": "0.23.0",
-    "@voltro/workflow": "0.23.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/authentication.md

@@ -166,6 +166,27 @@ import { handleSignIn } from '@voltro/plugin-auth'
 
 Use `handleSignIn` instead of rolling your own — the timing-oracle gap is the kind of subtle bug that hides for years. Note it returns a `401 HandlerResult`, it does not throw a domain error.
 
+## Brute-force lockout
+
+`plugin-auth` locks an account after repeated failed credential attempts, so password-spraying and credential-stuffing don't get unlimited guesses. After **5 failed attempts** (a wrong password — or, for MFA users, a wrong second-factor code) within **15 minutes**, sign-in for that email is refused with a `429 account_locked` (carrying a `retryAfterSeconds`) for **15 minutes**. A completed login clears the counter.
+
+The counter is keyed by **email**, not user id, and it tracks unknown addresses too: a locked account and an unknown-but-hammered address respond identically, so the lock can't be turned into an existence oracle — the same reasoning as the timing-oracle defence above.
+
+It is **on by default** — a security default you get for free. Tune or disable it per app:
+
+```ts
+authRoutesPlugin({
+  store,
+  lockout: {
+    maxAttempts: 5,      // failed attempts before locking (default 5)
+    windowSeconds: 900,  // counting window (default 15 min)
+    lockSeconds: 900,    // lock duration (default 15 min)
+  },
+})
+```
+
+The counter lives in the `loginAttempts` table (contributed via `authTables`), so it appears automatically on your next `voltro db apply` / `voltro dev` boot. For lockout that holds across multiple nodes, back the store with Postgres (`postgresUserStore`) — the in-memory store is single-node.
+
 ## Rehashing on parameter bump
 
 When the framework updates the default cost parameters, existing hashes stay valid — `verifyPassword` reads `N`/`r`/`p` from the stored hash string itself (they're encoded inline as `scrypt$<N>$<r>$<p>$…`). Rehash-on-verify ships: `needsRehash(stored)` reports whether a hash is below the current cost, and `verifyPasswordWithRehash(plaintext, stored)` returns `{ valid, rehash? }` — when the password matches an under-cost hash, `rehash` is a freshly-minted replacement. `handleSignIn` wires this through `UserStore.updatePassword`, so a user's stored hash silently strengthens on their next login, no forced reset and no backfill.

package/templates/agent-docs/cli.md

@@ -2174,6 +2174,38 @@ voltro data restore ./backups/2026-07-01    # pg_restore / mysql / …
 
 These shell out to the vendor tools resolved from your `DB_DIALECT` + connection env. They produce a dialect-native artifact (`db.dump`, `db.sql`, `db.sqlite`, `db.bacpac`) that is lossless and point-in-time consistent for **same-dialect** restore — the right tool for disaster recovery. Secrets are passed via the tools' environment variables (`PGPASSWORD`, `MYSQL_PWD`), never on the command line, where the tool supports it. The named tool must be installed and on `PATH`.
 
+### The provenance stamp — a restore that refuses the wrong DB
+
+A native dump is opaque: it doesn't say which dialect made it, which schema shape it carries, or when. `backup` writes a sidecar `voltro-backup-stamp.json` next to the artifact recording exactly that — `dialect`, the live schema `fingerprint`, the `@voltro/cli` version, and the timestamp.
+
+`restore` reads the stamp **before touching the DB** and acts on two failures that are otherwise silent until they corrupt:
+
+- **Cross-dialect restore → refused.** Restoring a postgres dump while `DB_DIALECT=mysql` is never valid; it stops with an error instead of half-loading. Override with `--force` only if you genuinely know better.
+- **Schema/code skew → warned.** If the backup's schema fingerprint differs from what the running code declares, restore prints a warning to run `voltro db apply` afterwards — the dump's shape predates (or postdates) this deploy's code. (Production boot already refuses on a fingerprint mismatch; the stamp surfaces it at restore time, before the boot.)
+
+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.
+
+> **Test your backups.** A backup you've never restored is a hypothesis. Restore your latest artifact into a throwaway database and boot the app against it on a schedule — the stamp's dialect/fingerprint checks turn a silently-broken backup into a loud one, but only an actual restore proves the bytes are good.
+
 ## Masking (prod → dev/stage safely)
 
 Cloning prod into a lower environment must not carry real user data. `voltro data export`