@voltro/cli 0.22.1 → 0.24.0

package/dist/startEntry.js

@@ -1,3 +1,3 @@
-import { X as e } from "./inspectMetrics-9ZSuDeqD.js";
-import { t } from "./start-CsIjcOi-.js";
+import { Z as e } from "./inspectMetrics-dcC7gnxu.js";
+import { t } from "./start-C_4VUDT8.js";
 export { e as loadDotEnv, t as runStartCommand };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltro/cli",
-  "version": "0.22.1",
+  "version": "0.24.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.22.1",
-    "@voltro/cache": "0.22.1",
-    "@voltro/data-transfer": "0.22.1",
-    "@voltro/database": "0.22.1",
-    "@voltro/env": "0.22.1",
-    "@voltro/kv": "0.22.1",
-    "@voltro/logger": "0.22.1",
-    "@voltro/plugin-auth": "0.22.1",
-    "@voltro/plugin-broadcast": "0.22.1",
-    "@voltro/plugin-mail": "0.22.1",
-    "@voltro/plugin-storage": "0.22.1",
-    "@voltro/plugin-webhooks": "0.22.1",
-    "@voltro/protocol": "0.22.1",
-    "@voltro/runtime": "0.22.1",
-    "@voltro/serverless": "0.22.1",
-    "@voltro/workflow": "0.22.1",
+    "@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",
     "chokidar": "^5.0.0",
     "ioredis": "^5.11.1",
     "tinyglobby": "^0.2.17",

package/templates/AGENTS.md

@@ -595,7 +595,7 @@ each plugin's own README.
 
 | Topic | Open | Summary |
 |---|---|---|
-| **What's new in 0.22.1** | `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.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. |
 | 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. |

package/templates/agent-docs/_index.md

@@ -9,7 +9,7 @@ each plugin's own README.
 
 | Topic | Open | Summary |
 |---|---|---|
-| **What's new in 0.22.1** | `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.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. |
 | 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. |

package/templates/agent-docs/_manifest.json

@@ -89,7 +89,7 @@
       "group": "database.migrations",
       "description": "Voltro's planner-based migration system — diff your declared schema against the live DB, classify each change, refuse-to-apply anything risky without explicit intent. Dev auto-applies, prod refuses.",
       "path": "agent-docs/database/migrations.md",
-      "files": 16
+      "files": 17
     },
     {
       "id": "database/misc",

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/caching.md

@@ -286,12 +286,13 @@ The matching `.<primitive>.server.ts` is **unchanged** — caching is a descript
 
 ## `scope` is required — and it's a security decision
 
-`scope` has **no default**, because guessing wrong leaks one user's rows to another. The rubric is one question:
+`scope` has **no default**, because guessing wrong leaks one user's rows to another. The rubric is one question, with **three** answers:
 
-> **Does the resolved query depend on the caller?**
+> **Does the resolved query depend on the caller — and on what about them?**
 
-- **Yes** — tenant-filtered, `where authorId = me`, anything row-scoped → **`scope: 'subject'`**. The cache key includes the caller's subject id, so two subjects can never share an entry.
-- **No** — the same rows for everyone (reference / lookup data) → **`scope: 'global'`**. One entry shared across all callers.
+- **On the PERSON** — `where authorId = me`, anything row-scoped → **`scope: 'subject'`**. The cache key includes the caller's subject id, so two subjects can never share an entry.
+- **On their ORG only** — an org-wide figure every colleague sees identically → **`scope: 'tenant'`**. One entry per `tenantId`, never shared across orgs.
+- **On neither** — the same rows for everyone (reference / lookup data) → **`scope: 'global'`**. One entry shared across all callers.
 
 ```ts
 // reference data — identical for everyone → global
@@ -302,9 +303,24 @@ export const listCountries = defineQuery({
   output: Country,
   cache:  { ttl: '1h', scope: 'global' },
 })
+
+// an org-wide statistic — same for all 18 colleagues, never across orgs
+export const last12Months = defineQuery({
+  name:   'globalStatistics.last12Months',
+  source: ['invoices', 'employees'],
+  input:  Schema.Struct({}),
+  output: Stats,
+  cache:  { ttl: '5m', scope: 'tenant' },
+})
 ```
 
-**Never put `scope: 'global'` on a subject-filtered query.** Tenant tables are auto-scoped per subject by the runtime, so a `global` cache over one would serve tenant A's rows to tenant B. When in doubt, use `subject`.
+`'tenant'` exists because the other two were the only options and neither fit an org-wide figure: `'subject'` recomputes it per person — eighteen identical computations of the same nine-table statistic for an eighteen-person org — and `'global'` shares one entry across tenant boundaries, which for data derived from `subject.tenantId` is not a cache but a leak.
+
+A caller with no `tenantId` (an anonymous or system subject) **bypasses** a `'tenant'` cache rather than sharing a null-keyed entry.
+
+**Never put `scope: 'global'` on a subject- or tenant-filtered query.** Tenant tables are auto-scoped by the runtime, so a `global` cache over one would serve tenant A's rows to tenant B. **The boot audit checks this**: a `'global'` scope over a `tenant()`-scoped table is reported by `voltro dev` and refused under `VOLTRO_SERVER_ONLY=strict`. It stays silent for `'global'` on reference data — the case the option exists for — and for a query with no declared `source`, where it has nothing to reason about.
+
+**`scope: 'tenant'` is not a replacement for modelling.** For a rollup, an aggregate with `tenantId` as an indexed column puts the tenant boundary in the *data* rather than in a cache key, which is better. `'tenant'` is for the other case: a query that must be FRESH and is merely expensive, where an aggregate's refresh interval is the wrong instrument.
 
 ## How auto-invalidation works
 

package/templates/agent-docs/cli.md

@@ -1069,6 +1069,21 @@ source counts as a guard, so `requireTeamAccess()` is recognised without any
 configuration. Without that the scan would report every call site of your own
 guards, which is the failure mode that makes a check ignorable.
 
+It reads your **whole source tree** for those names, not just the
+convention-named files — guards live in `lib/access.ts`, not in `*.mutation.ts`.
+The line above the counts tells you what it found, and it is worth reading before
+you trust the numbers:
+
+```txt
+  guard vocabulary: 17 from your source (requireTeamAccess, assertInquiryAccess, …)
+```
+
+If it instead says `framework names only — no exported require*/assert* found in
+this app` while you know you export some, the counts below it are not meaningful:
+every call site of your own guards is being reported as unguarded. Check that
+they are `export`ed and that the name starts with `require` / `assert` followed
+by a capital.
+
 **An inline ownership check is informational.** `row.userId !== subject.id → new
 AccessDeniedError({})` is correct code — it is listed so you can see where the
 rule lives in a handler rather than on a descriptor, and it never fails the run.
@@ -2159,6 +2174,23 @@ 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.
+
+### 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`
@@ -2606,6 +2638,35 @@ voltro update --codemods-only --from 0.5.0 --to 0.6.0
 
 Every `@voltro/*` entry in `dependencies` and `devDependencies` — in every workspace member, see above — with the range style preserved (`^0.3.0` stays caret, `~0.3.0` stays tilde) unless you pass `--exact`. Non-registry specs (`workspace:*`, `catalog:`, `link:`, …) are left untouched — they're already resolved by your monorepo or catalog.
 
+### And the peer dependencies the framework requires
+
+`@effect/*` are **peer** dependencies, so your app declares them directly. When a
+release moves its peer range, bumping only `@voltro/*` leaves you installed
+against the old ones:
+
+```txt
+Aligning peer dependencies the framework requires:
+  @effect/rpc       ^0.75.1 → ^0.76.0   (apps/api/package.json)
+  @effect/platform  ^0.96.2 → ^0.97.0   (apps/api/package.json)
+```
+
+`update` reads those requirements off the freshly installed `@voltro/*` packages
+and re-installs if anything moved. Without it your package manager only *warns*,
+and the app compiles and boots on a graph the framework was never tested against
+— which is the failure mode with no symptom until there is one.
+
+It is deliberately conservative:
+
+- **Only peers you already declare.** One resolved transitively is not `update`'s
+  to add.
+- **Only when your range is genuinely lower.** Pinned ahead, or pinned exactly at
+  the floor (`0.76.0` vs `^0.76.0`), is left alone — that is a choice.
+- **Only ranges it can judge** (`^`, `~`, `>=`, exact). A union (`^1 || ^2`), a
+  bounded range, `workspace:` / `catalog:` — untouched.
+
+If two framework packages disagree about one peer, it says so and changes
+nothing: that is our bug, not yours to absorb silently.
+
 ## When the install cannot run on this host
 
 Some projects install in a container with their own store, from an offline