@voltro/cli 0.18.0 → 0.19.0

package/dist/serveEntry.js

@@ -1,5 +1,5 @@
 import { Q as e } from "./inspectMetrics-D1DmLeJs.js";
 import { c as t } from "./seedRunner-D6eu-u5U.js";
 import { r as n } from "./appModuleLoader-C9r9mxZt.js";
-import { t as r } from "./serveCommand-CxcxHc9Y.js";
+import { t as r } from "./serveCommand-vPF5ucXC.js";
 export { e as loadDotEnv, n as registerAppModules, t as registerDriver, r as runServe };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltro/cli",
-  "version": "0.18.0",
+  "version": "0.19.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.107.0",
     "@effect/sql": "^0.51.1",
     "@effect/workflow": "^0.18.2",
-    "@voltro/ai": "0.18.0",
-    "@voltro/cache": "0.18.0",
-    "@voltro/data-transfer": "0.18.0",
-    "@voltro/database": "0.18.0",
-    "@voltro/env": "0.18.0",
-    "@voltro/kv": "0.18.0",
-    "@voltro/logger": "0.18.0",
-    "@voltro/plugin-auth": "0.18.0",
-    "@voltro/plugin-broadcast": "0.18.0",
-    "@voltro/plugin-mail": "0.18.0",
-    "@voltro/plugin-storage": "0.18.0",
-    "@voltro/plugin-webhooks": "0.18.0",
-    "@voltro/protocol": "0.18.0",
-    "@voltro/runtime": "0.18.0",
-    "@voltro/serverless": "0.18.0",
-    "@voltro/workflow": "0.18.0",
+    "@voltro/ai": "0.19.0",
+    "@voltro/cache": "0.19.0",
+    "@voltro/data-transfer": "0.19.0",
+    "@voltro/database": "0.19.0",
+    "@voltro/env": "0.19.0",
+    "@voltro/kv": "0.19.0",
+    "@voltro/logger": "0.19.0",
+    "@voltro/plugin-auth": "0.19.0",
+    "@voltro/plugin-broadcast": "0.19.0",
+    "@voltro/plugin-mail": "0.19.0",
+    "@voltro/plugin-storage": "0.19.0",
+    "@voltro/plugin-webhooks": "0.19.0",
+    "@voltro/protocol": "0.19.0",
+    "@voltro/runtime": "0.19.0",
+    "@voltro/serverless": "0.19.0",
+    "@voltro/workflow": "0.19.0",
     "chokidar": "^5.0.0",
     "ioredis": "^5.11.1",
     "tinyglobby": "^0.2.17",

package/templates/AGENTS.core.md

@@ -103,30 +103,41 @@ line below replaces something real apps write by hand hundreds of times.
    in-handler for checks that need LOADED data. A hand-written `requireScope(...)`
    at the top of every executor — or a hand-kept map from rpc tag to policy rule,
    which is fail-open by omission — is what `guards:` exists to delete.
-6. **Storing a token, secret, or credential in a column?** → **`.encrypted()`**
+6. **Which ROWS may the caller see** (not: may they make the call)? →
+   **`setRowFilter`** — a predicate derived from the Subject, AND-merged into
+   EVERY read of that table, including every subscription delivery. `guards:`
+   and this answer different questions and the pair is easy to conflate:
+   - `guards:` → *may I call this procedure?* → a typed `ScopeError`.
+   - `setRowFilter` → *which rows may I see?* → the rows are simply absent.
+   A `WHERE ownerId = me` in the list handler covers the query and **NOT** the
+   stream, which is the failure this deletes. Register it from a
+   `*.startup.tsx`; its `load` must read through an UNFILTERED store (the boot
+   store / the `database` handle) — reading through the filtered one applies the
+   filter to itself and blows the stack. Depth → **`authentication`**.
+7. **Storing a token, secret, or credential in a column?** → **`.encrypted()`**
    on the column. Boot fails loudly if no cipher is configured, so an
    `.encrypted()` column can never silently persist plaintext.
-7. **Writing an Effect-form handler?** → `const store = yield* EffectStore` —
+8. **Writing an Effect-form handler?** → `const store = yield* EffectStore` —
    its failures land on the typed error channel. `Effect.promise(() =>
    ctx.store.query(…))` throws that channel away and turns a store failure into
    a defect.
-8. **Cursor pagination?** → **`paginateBy(descriptor, column, cursor, limit,
+9. **Cursor pagination?** → **`paginateBy(descriptor, column, cursor, limit,
    direction?)`** (or **`paginateById`**, its `id`-column shorthand). Not a
    hand-rolled limit+1 / slice / `hasMore` triple. `direction` flips the
    COMPARISON as well as the sort — a `desc` feed pages with `<`.
-9. **Assembling data whose SHAPE depends on the data** (a tree walk where each
+10. **Assembling data whose SHAPE depends on the data** (a tree walk where each
    level's ids come from the level above)? → **`ctx.load` / `ctx.loadMany`** —
    same-tick reads of one table coalesce into one `WHERE id IN (...)`, so the
    walk costs one query per LEVEL. Use `relations()` + `.with()` whenever the
    shape IS static; this is the fallback, not the default.
-10. **A mutation must cause an EXTERNAL side effect** (webhook, Jira sync,
+11. **A mutation must cause an EXTERNAL side effect** (webhook, Jira sync,
    payment)? → **`ctx.outbox.enqueue(effect, payload)`** + a
    **`defineOutboxHandler`** in a `*.outbox.ts`. The enqueue writes through the
    mutation's TRANSACTION, so the intent commits with the write or not at all;
    delivery happens after commit, with backoff and a dead-letter. Do NOT call
    the remote from the mutation (not transactional), and do not hand-build a
    deliveries table + drain cron — that IS this primitive.
-11. **Calling a third party ON BEHALF OF A USER** (their Jira token, their Slack
+12. **Calling a third party ON BEHALF OF A USER** (their Jira token, their Slack
    grant)? → **`defineConnection({ id, kind: 'oauth2' | 'pat' })`** in a
    `*.connection.ts`, then **`ctx.connections.get(id)`**. One declaration yields
    the encrypted per-user token store, the OAuth authorize/callback pair,
@@ -140,6 +151,7 @@ line below replaces something real apps write by hand hundreds of times.
 | `const rows = …; if (!rows[0]) throw new NotFound()` | `.one()` |
 | 3+ sequential `store.query` to assemble related data | `relations()` + `.with()` |
 | a notify/webhook helper called at the end of a mutation | `defineSubscriber` / `defineReaction` |
+| `WHERE ownerId = me` in every list handler | `setRowFilter` (covers the SUBSCRIPTION too) |
 | a counter recomputed by scanning rows on every read | `defineAggregate` (+ `incremental:`) |
 | `requireScope(...)` as the first line of every executor | `guards:` on the descriptor |
 | a token/secret column written as plain text | `.encrypted()` |
@@ -456,7 +468,7 @@ separate markers, and using one to answer another's question is the mistake:
 
 | Marker | Answers | Enforced by |
 |---|---|---|
-| `.serverOnly()` | may this value leave the server AT ALL? | **the boot audit — it FAILS the boot**, it does not warn |
+| `.serverOnly()` | may this value leave the server AT ALL? | **`voltro serve` fails to boot; `voltro doctor` exits non-zero.** `voltro dev` only warns |
 | `.sensitive('class')` / `.safe()` | may it appear in a `voltro data export`? | the export's masking profile, **fail-closed** |
 | `.encrypted()` | is it encrypted AT REST? | the store's codec |
 
@@ -470,8 +482,12 @@ export const users = table('users', {
 ```
 
 - **`.serverOnly()` is the one that decides "leak / no leak".** A wire-reachable
-  query that declares such a column in its OUTPUT does not start: the boot audit
-  refuses. That is a feature — the failure happens at boot, not in a bundle.
+  query that declares such a column in its OUTPUT does not reach production:
+  `voltro serve` refuses to boot and `voltro doctor` exits non-zero, so the
+  failure happens at deploy time rather than in a bundle. `voltro dev` only
+  WARNS — mid-edit a refused boot is worse than the bug — so do not read a green
+  dev boot as a clean audit. `VOLTRO_SERVER_ONLY=strict` makes dev fail too;
+  put `voltro doctor` in CI if you want one gate that covers both.
 - **`.encrypted()` is NOT an exposure marker.** It says the bytes at rest are
   encrypted; the runtime decrypts them for a handler, so an encrypted column
   flows to the client exactly like any other unless it is ALSO `.serverOnly()`.

package/templates/AGENTS.md

@@ -103,30 +103,41 @@ line below replaces something real apps write by hand hundreds of times.
    in-handler for checks that need LOADED data. A hand-written `requireScope(...)`
    at the top of every executor — or a hand-kept map from rpc tag to policy rule,
    which is fail-open by omission — is what `guards:` exists to delete.
-6. **Storing a token, secret, or credential in a column?** → **`.encrypted()`**
+6. **Which ROWS may the caller see** (not: may they make the call)? →
+   **`setRowFilter`** — a predicate derived from the Subject, AND-merged into
+   EVERY read of that table, including every subscription delivery. `guards:`
+   and this answer different questions and the pair is easy to conflate:
+   - `guards:` → *may I call this procedure?* → a typed `ScopeError`.
+   - `setRowFilter` → *which rows may I see?* → the rows are simply absent.
+   A `WHERE ownerId = me` in the list handler covers the query and **NOT** the
+   stream, which is the failure this deletes. Register it from a
+   `*.startup.tsx`; its `load` must read through an UNFILTERED store (the boot
+   store / the `database` handle) — reading through the filtered one applies the
+   filter to itself and blows the stack. Depth → **`authentication`**.
+7. **Storing a token, secret, or credential in a column?** → **`.encrypted()`**
    on the column. Boot fails loudly if no cipher is configured, so an
    `.encrypted()` column can never silently persist plaintext.
-7. **Writing an Effect-form handler?** → `const store = yield* EffectStore` —
+8. **Writing an Effect-form handler?** → `const store = yield* EffectStore` —
    its failures land on the typed error channel. `Effect.promise(() =>
    ctx.store.query(…))` throws that channel away and turns a store failure into
    a defect.
-8. **Cursor pagination?** → **`paginateBy(descriptor, column, cursor, limit,
+9. **Cursor pagination?** → **`paginateBy(descriptor, column, cursor, limit,
    direction?)`** (or **`paginateById`**, its `id`-column shorthand). Not a
    hand-rolled limit+1 / slice / `hasMore` triple. `direction` flips the
    COMPARISON as well as the sort — a `desc` feed pages with `<`.
-9. **Assembling data whose SHAPE depends on the data** (a tree walk where each
+10. **Assembling data whose SHAPE depends on the data** (a tree walk where each
    level's ids come from the level above)? → **`ctx.load` / `ctx.loadMany`** —
    same-tick reads of one table coalesce into one `WHERE id IN (...)`, so the
    walk costs one query per LEVEL. Use `relations()` + `.with()` whenever the
    shape IS static; this is the fallback, not the default.
-10. **A mutation must cause an EXTERNAL side effect** (webhook, Jira sync,
+11. **A mutation must cause an EXTERNAL side effect** (webhook, Jira sync,
    payment)? → **`ctx.outbox.enqueue(effect, payload)`** + a
    **`defineOutboxHandler`** in a `*.outbox.ts`. The enqueue writes through the
    mutation's TRANSACTION, so the intent commits with the write or not at all;
    delivery happens after commit, with backoff and a dead-letter. Do NOT call
    the remote from the mutation (not transactional), and do not hand-build a
    deliveries table + drain cron — that IS this primitive.
-11. **Calling a third party ON BEHALF OF A USER** (their Jira token, their Slack
+12. **Calling a third party ON BEHALF OF A USER** (their Jira token, their Slack
    grant)? → **`defineConnection({ id, kind: 'oauth2' | 'pat' })`** in a
    `*.connection.ts`, then **`ctx.connections.get(id)`**. One declaration yields
    the encrypted per-user token store, the OAuth authorize/callback pair,
@@ -140,6 +151,7 @@ line below replaces something real apps write by hand hundreds of times.
 | `const rows = …; if (!rows[0]) throw new NotFound()` | `.one()` |
 | 3+ sequential `store.query` to assemble related data | `relations()` + `.with()` |
 | a notify/webhook helper called at the end of a mutation | `defineSubscriber` / `defineReaction` |
+| `WHERE ownerId = me` in every list handler | `setRowFilter` (covers the SUBSCRIPTION too) |
 | a counter recomputed by scanning rows on every read | `defineAggregate` (+ `incremental:`) |
 | `requireScope(...)` as the first line of every executor | `guards:` on the descriptor |
 | a token/secret column written as plain text | `.encrypted()` |
@@ -456,7 +468,7 @@ separate markers, and using one to answer another's question is the mistake:
 
 | Marker | Answers | Enforced by |
 |---|---|---|
-| `.serverOnly()` | may this value leave the server AT ALL? | **the boot audit — it FAILS the boot**, it does not warn |
+| `.serverOnly()` | may this value leave the server AT ALL? | **`voltro serve` fails to boot; `voltro doctor` exits non-zero.** `voltro dev` only warns |
 | `.sensitive('class')` / `.safe()` | may it appear in a `voltro data export`? | the export's masking profile, **fail-closed** |
 | `.encrypted()` | is it encrypted AT REST? | the store's codec |
 
@@ -470,8 +482,12 @@ export const users = table('users', {
 ```
 
 - **`.serverOnly()` is the one that decides "leak / no leak".** A wire-reachable
-  query that declares such a column in its OUTPUT does not start: the boot audit
-  refuses. That is a feature — the failure happens at boot, not in a bundle.
+  query that declares such a column in its OUTPUT does not reach production:
+  `voltro serve` refuses to boot and `voltro doctor` exits non-zero, so the
+  failure happens at deploy time rather than in a bundle. `voltro dev` only
+  WARNS — mid-edit a refused boot is worse than the bug — so do not read a green
+  dev boot as a clean audit. `VOLTRO_SERVER_ONLY=strict` makes dev fail too;
+  put `voltro doctor` in CI if you want one gate that covers both.
 - **`.encrypted()` is NOT an exposure marker.** It says the bytes at rest are
   encrypted; the runtime decrypts them for a handler, so an encrypted column
   flows to the client exactly like any other unless it is ALSO `.serverOnly()`.
@@ -579,7 +595,7 @@ each plugin's own README.
 
 | Topic | Open | Summary |
 |---|---|---|
-| **What's new in 0.18.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.19.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.18.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.19.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/authentication.md

@@ -590,6 +590,15 @@ column read raw hands back the string `enc:v1:…`, which compares, concatenates
 renders and logs perfectly well, and simply never matches the token you compare
 it to.
 
+**The soft-delete row is the one to read twice if you are porting raw SQL onto
+this store.** A read here behaves the way your SQL did and returns tombstones —
+the store does *not* start appending `deletedAt IS NULL` behind you. So a lookup
+that must see a soft-deleted row (a login that revives a returning user, say)
+needs no opt-out and no `.withDeleted()`; that opt-out belongs to `ctx.store`,
+which *does* apply the filter. Assuming the filter is present is the more
+expensive mistake of the two: it turns a working login into a "not found →
+insert → unique violation on email", and nothing about the code says so.
+
 This is also what changes when you move a read **off** hand-written SQL and onto
 the store. Raw SQL sees ciphertext and you decrypt it yourself — `decryptField`
 from `@voltro/runtime` is the escape hatch for exactly that. Through either

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

@@ -248,9 +248,32 @@ Enforcement: the [`crud.*` read helpers](/docs/data/crud) strip `.serverOnly()`
 columns from every returned row **automatically** — you declare the exposure
 policy once at the schema and can't forget it on a handler. For a hand-written
 query, omit the column from the `output` schema (and don't put it in the returned
-object) — and `voltro dev` **warns at boot**, naming the query and column, if a
-wire-reachable query's output declares a `.serverOnly()` column of its `source`
-table, so a secret can't ship on the wire by omission-mistake.
+object).
+
+A hand-written output is the case `crud.*` cannot cover, so an audit checks it:
+a wire-reachable query whose `source` table carries a `.serverOnly()` column that
+its `output` **declares**. What that costs is different per command, on purpose:
+
+| Command | On a leak |
+|---|---|
+| `voltro serve` | **the boot fails** |
+| `voltro doctor` | **exits non-zero** — put it in CI |
+| `voltro dev` | warns, naming the query and column |
+
+Dev only warns because a refused boot between two keystrokes is worse than the
+bug; production is the opposite, so that is where the gate is. **Do not read a
+green `voltro dev` boot as a clean audit** — the warning sits in the boot log
+among everything else. `voltro doctor` is the check to automate.
+
+`VOLTRO_SERVER_ONLY` moves the line in both directions: `strict` makes `voltro
+dev` fail too, `warn` downgrades `voltro serve` to a warning, `off` silences it
+entirely. The downgrades are documented rather than hidden because the
+alternative to a stated escape hatch is deleting the marker — and a check whose
+only way out is to disable it gets disabled.
+
+(`voltro check` does **not** run this audit. It has a live-api mode that has no
+access to your table definitions, and a rule that fires in one of its two modes
+would be worse than one that fires in neither.)
 
 Distinct from `.encrypted()` on purpose: encryption at rest says nothing about
 who may receive the plaintext — a private note you decrypt *for its owner* is a

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

@@ -114,6 +114,8 @@ ctx.store.select('notes')
 
 There is no `'like'`. It used to be here, and it was a lie: it mapped to `contains`, so `.where('path', 'like', '/api/%')` matched only rows literally containing the characters `/api/%` and the wildcard you wrote did nothing. An operator named after SQL's must honour your wildcards or not exist.
 
+> **Writing an in-memory store for tests? Do not reimplement these.** `evaluatePredicate` is exported from `@voltro/database` and is the same function the memory store runs, so a test double built on it agrees with a real database by construction. Hand-rolling the switch is where a stub quietly diverges — a `case 'contains'` written as `String(a).includes(b)` is case-SENSITIVE where the real one folds case, and coerces a number where the real one returns `false`. That stub passes queries a live dialect fails, which is the worst direction for a test double to be wrong in.
+
 These are the only operators the ergonomic `.where(col, op, value)` form accepts. For `IS NULL` / `NOT IN` / `IS NOT NULL`, pass a predicate built with the `@voltro/database` helpers:
 
 ```ts