@voltro/cli 0.11.0 → 0.11.2

package/dist/startEntry.js

@@ -1,3 +1,3 @@
-import { N as e } from "./inspectMetrics-BeMjgt8x.js";
-import { t } from "./start-C_M4fGS2.js";
+import { bt as e } from "./inspectMetrics-BuBwg1yW.js";
+import { t } from "./start-ChN6PO-c.js";
 export { e as loadDotEnv, t as runStartCommand };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltro/cli",
-  "version": "0.11.0",
+  "version": "0.11.2",
   "description": "The `voltro` CLI — dev server, codegen, migrations, project scaffolding, agent-docs seeding, and production serve.",
   "keywords": [
     "voltro",
@@ -45,6 +45,11 @@
       "types": "./dist/serveEntry.d.ts",
       "import": "./dist/serveEntry.js",
       "default": "./dist/serveEntry.js"
+    },
+    "./startEntry": {
+      "types": "./dist/startEntry.d.ts",
+      "import": "./dist/startEntry.js",
+      "default": "./dist/startEntry.js"
     }
   },
   "main": "./dist/index.js",
@@ -57,22 +62,22 @@
     "@effect/platform-node": "^0.107.0",
     "@effect/sql": "^0.51.1",
     "@effect/workflow": "^0.18.2",
-    "@voltro/ai": "0.11.0",
-    "@voltro/cache": "0.11.0",
-    "@voltro/data-transfer": "0.11.0",
-    "@voltro/database": "0.11.0",
-    "@voltro/env": "0.11.0",
-    "@voltro/kv": "0.11.0",
-    "@voltro/logger": "0.11.0",
-    "@voltro/plugin-auth": "0.11.0",
-    "@voltro/plugin-broadcast": "0.11.0",
-    "@voltro/plugin-mail": "0.11.0",
-    "@voltro/plugin-storage": "0.11.0",
-    "@voltro/plugin-webhooks": "0.11.0",
-    "@voltro/protocol": "0.11.0",
-    "@voltro/runtime": "0.11.0",
-    "@voltro/serverless": "0.11.0",
-    "@voltro/workflow": "0.11.0",
+    "@voltro/ai": "0.11.2",
+    "@voltro/cache": "0.11.2",
+    "@voltro/data-transfer": "0.11.2",
+    "@voltro/database": "0.11.2",
+    "@voltro/env": "0.11.2",
+    "@voltro/kv": "0.11.2",
+    "@voltro/logger": "0.11.2",
+    "@voltro/plugin-auth": "0.11.2",
+    "@voltro/plugin-broadcast": "0.11.2",
+    "@voltro/plugin-mail": "0.11.2",
+    "@voltro/plugin-storage": "0.11.2",
+    "@voltro/plugin-webhooks": "0.11.2",
+    "@voltro/protocol": "0.11.2",
+    "@voltro/runtime": "0.11.2",
+    "@voltro/serverless": "0.11.2",
+    "@voltro/workflow": "0.11.2",
     "chokidar": "^5.0.0",
     "ioredis": "^5.11.1",
     "tinyglobby": "^0.2.17",
@@ -80,6 +85,7 @@
   },
   "optionalDependencies": {
     "@tailwindcss/vite": "^4.3.2",
+    "@vercel/nft": "^1.10.2",
     "@vitejs/plugin-react": "^6.0.3",
     "esbuild": "^0.28.0",
     "tsx": "^4.23.0",

package/templates/agent-docs/data.md

@@ -293,6 +293,28 @@ export default async (_input: Record<string, never>, ctx) => {
 
 For computed queries, `source` is the reactivity trigger. When any row in the source table changes, the runtime re-runs the executor and emits the new value if it changed. If the executor reads more than one table (a join or matrix), declare `source` as an array — the executor re-runs when **any** listed table changes (e.g. `source: ['skills', 'ratings']`).
 
+### Type the computed return against `output` — `defineExecutor`
+
+A computed executor's return is encoded through the descriptor's `output` schema — but the bare default export's return is **not** type-checked against it. So a handler that builds `{ publishedAt: row.publishedAt.getTime() }` where `output` is `timestampMs` (Type `Date`) compiles green and throws `Expected DateFromSelf, actual 1784…` at *encode* time, which **Dies the subscription**. For a nullable date it's a time-bomb: fine while the value is null, exploding the instant it becomes non-null (a publish, say).
+
+Wrap the handler in `defineExecutor(descriptor, fn)` — it pins the return to `Schema.Type<output>`, turning that into a compile error at the handler:
+
+```ts
+// apps/api/queries/notes.summary.query.server.ts
+import { defineExecutor } from '@voltro/runtime'
+import { notesSummary } from './notes.summary.query'
+
+export default defineExecutor(notesSummary, async (_input, ctx) => {
+  const notes = await ctx.store.select('notes').all()
+  return {
+    open: notes.filter((note) => !note.done).length,
+    done: notes.filter((note) => note.done).length,
+  }
+})
+```
+
+It's a runtime identity (returns the handler unchanged) — the whole value is the compile check. The Effect error and requirement channels stay inferred; only the success value is constrained. A **descriptor-return** (reactive) executor is allowed through unchecked: the store produces the rows, so a value-level return type can't express the row-vs-`output` check. `defineExecutor` works the same for `defineMutation` / `defineAction` handlers.
+
 ## Auto-optimistic source
 
 `source` also connects query caches to mutation `target` metadata:
@@ -625,6 +647,48 @@ The descriptor is the wire contract. The `.mutation.server.ts` file is the serve
 5. Commit the transaction.
 6. Drain the batched change events so matching query subscriptions receive new snapshots or deltas.
 
+## Missing required columns fail LOUD, at the call
+
+`ctx.store.insert` / `upsert` / `insertIgnore` check the payload against the
+table before the statement runs. A column that is NOT NULL, has no default, and
+isn't auto-stamped — a business FK like `teamId`, a plain `timestamp()` like
+`lastRefreshedAt` — must be present, or the write raises a typed
+`TableValidationFailed` naming it:
+
+```txt
+TableValidationFailed: missing required column 'lastRefreshedAt'
+  — NOT NULL with no default and not auto-stamped
+```
+
+Without this the omission slips past `tsc` and boot and surfaces only as a raw
+dialect `SqlError: Failed to execute statement` — and only on the INSERT path, so
+it stays dormant until the first row with no existing cache entry. An
+`upsert` / `insertIgnore` whose payload omits one of its own `conflictColumns` is
+named the same way (an absent conflict key can't match its target). The check
+runs after stamping, so auto-id, `tenantId`, and audit columns never trip it, and
+it skips nullable and defaulted columns — the ones you may legitimately omit.
+
+### Catch it at COMPILE time — `insertRow` / `upsertRow`
+
+The runtime guard above is the backstop. To catch a missing column at compile
+time, use `insertRow` / `upsertRow` — they take the **table object** (not a
+string name), so the payload is typed against the table's required columns:
+
+```ts
+import { insertRow } from '@voltro/database'
+
+// ✗ compile error — lastRefreshedAt is NOT NULL with no default
+await insertRow(ctx.store, roadmapEpicStats, { teamId })
+// ✓
+await insertRow(ctx.store, roadmapEpicStats, { teamId, lastRefreshedAt: new Date() })
+```
+
+`InferInsertRow<T>` makes a column optional exactly when you may omit it — it's
+nullable, has a `.default()`, or is a framework-filled `id` / `tenantId` / audit
+column — and required otherwise. `upsertRow`'s `conflictColumns` are constrained
+to the table's own columns, so a typo is a compile error too. The string-keyed
+`ctx.store.insert` / `upsert` still work unchanged; the typed seam is opt-in.
+
 ## Partial updates: `ctx.store.applyDefined`
 
 A partial-update mutation should set only the fields the caller actually sent — not overwrite an omitted field with `undefined`. Instead of hand-writing `if (input.x !== undefined) patch.x = input.x` per field, use `ctx.store.applyDefined(input, keys)`:
@@ -1046,11 +1110,18 @@ cancellation email. Declare the overlap instead of relying on luck:
 sequence()
   .step('draft', () => createDraft.run(input), { undo: (d) => discardDraft.run({ id: d.id }) })
   .step('jira',  (c) => createTicket.run({ draftId: c.draft.id }), {
-    undo:   (t) => deleteJiraDraftTicket.run({ key: t.key }),
+    undo:   (t, ctx) => deleteJiraDraftTicket.run({ key: t.key, draftId: ctx.draft.id }),
     covers: ['draft'],
   })
 ```
 
+An `undo` receives `(result, ctx)` — its own result *and* the context up to that
+step, the same context `covers` and `when` see. An inverse that needs an id from
+an earlier step (here `deleteJiraDraftTicket` wants both the jira key and the
+`draftId`) reads it from `ctx` rather than the step re-returning it just so the
+undo can reach it. A later step's result is not in `ctx`: it is rolled back
+before this one, so reading it would be reading something already reversed.
+
 If the covering undo *fails*, the covered steps are neither run nor claimed —
 whether the cascade got that far is unknown, and both guesses are wrong. They
 come back in `compensationUncertain` so you can reconcile.

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

@@ -208,6 +208,13 @@ const rows = await ctx.store.query(database.people.descriptor)
 rows[0]?.fullName    // → 'Mario Lima'
 ```
 
+**A generated column is never caller-supplied.** It's omitted from the typed insert
+payload — `insertRow(store, people, { firstName, lastName })` compiles with no
+`fullName`, and its type is optional even when the column is NOT nullable and has no
+default (the DB owns the value). If a loose `store.insert` passes one anyway, the
+framework strips it before the INSERT — MariaDB and Postgres both reject an explicit
+value for a generated column, so this keeps that error from reaching the dialect.
+
 ## STORED vs VIRTUAL
 
 `{ stored: true }` (the rare-but-useful case):

package/templates/agent-docs/deployment.md

@@ -234,6 +234,32 @@ your-product.com {
 
 The path is **relative** in the bundle, so the host resolves at runtime — **one built image works across every environment**; only the path is fixed. Keep the socket **same-origin** with the web app: the session cookie rides the WS upgrade, and a cross-origin socket wouldn't carry it (every subscription would run anonymous). For an api on a genuinely separate origin, use the api spec's absolute `url` on the web side plus a token-based `headers` resolver instead of a cookie. (One custom `wsPath` per origin — the framework fails the build if two same-origin apis would collide on it.)
 
+### Split web/api deployment — the SSR api origin — `serverUrl`
+
+When `web` and `api` deploy as **separate services** (e.g. different k8s namespaces, one ingress routing `/api*` → api), the **browser** reaches the api by its relative `wsPath` against the page origin — but a `renderMode:'ssr'` page's `ctx.query` runs in the **web pod**, which has no page origin and must reach the api by **internal DNS**. These are genuinely different endpoints, so `url` (which is *also* the browser's ws origin) can't express the internal one without shipping an unreachable host to the browser.
+
+Set the server-only `serverUrl` (or the env override) to the api's internal origin:
+
+```ts
+// web/app.config.ts
+apis: {
+  app: {
+    package: '@app/api',
+    transport: { wsPath: '/api/sync' },        // browser → relative, same-origin
+    serverUrl: process.env.VOLTRO_API_ORIGIN,  // web pod → internal DNS (SSR only)
+  },
+},
+```
+
+```bash
+# or set it purely from ops, no app.config edit — per-api, name upper-cased:
+VOLTRO_API_ORIGIN_APP=http://api.my-namespace.svc.cluster.local
+# or a single shared origin for every api:
+VOLTRO_API_ORIGIN=http://api.my-namespace.svc.cluster.local
+```
+
+`serverUrl` / `VOLTRO_API_ORIGIN*` is used **only** for the SSR `POST /rpc` and is **never** emitted into the browser bundle. Resolution order: env > `serverUrl` > (under `voltro dev` only) the dev proxy target > an external api's absolute `url`. Under `voltro start`, a package api with **none** of these set makes the SSR query **fail loud** — naming the api and the config to set — instead of dialing the dev `localhost` port and surfacing a cryptic `ECONNREFUSED` in a 500.
+
 ### `allowedHosts` — fronting the web app on a real domain
 
 Vite 8's DNS-rebind guard returns HTTP **403** for any request whose `Host`
@@ -275,6 +301,7 @@ cause.
 | `AI_PROVIDER` | when using `@voltro/ai` | `anthropic` / `openai` / `mock` |
 | `AI_API_KEY` | with `AI_PROVIDER` | Provider's API key |
 | `SSR_CACHE` | optional | `memory` (default) or `postgres` (needs `PG_*` set too) for the ISR cache |
+| `VOLTRO_API_ORIGIN` / `VOLTRO_API_ORIGIN_<NAME>` | split web/api deploy with SSR pages | The api's internal origin the WEB pod uses for SSR `ctx.query` (`http://api.<ns>.svc.cluster.local`). Per-api `_<NAME>` (name upper-cased) wins over the shared one and over `serverUrl`. Never sent to the browser |
 | `PORT` | optional | App's listen port (overrides `app.config.ts.port`) |
 | `VOLTRO_INSPECT` | optional | `off` to disable `_voltro/inspect/*` in prod |
 | `VOLTRO_INSPECT_TOKEN` | recommended | Bearer token guard on inspect endpoints |
@@ -402,6 +429,24 @@ The phases, in boot order:
 
 Read this from the container's own logs at its real CPU allotment, not a beefy dev machine: a `modules` phase that dwarfs everything else means the cold start is dominated by evaluating the dependency graph (raise the container's CPU, or keep one instance warm); a fat `store` phase points at the database connection instead. `VOLTRO_BOOT_TIMING` adds a handful of `performance.now()` calls and one log line — it is safe to leave on in production.
 
+A **web app** (`voltro start`) reports its own phases under the same flag, on its ready line:
+
+```text
+boot phases (ready in 640ms)  { bootMs: 640, phases: { modules: 590, config: 6, scan: 12, provider: 22, routes: 4, cdc: 0, ready: 6 } }
+```
+
+| Phase | What it covers |
+| --- | --- |
+| `modules` | node init + module-graph load/compile — the dominant cold-start phase, same as the api. Note the web start path has **no serve-bundle equivalent** yet, so `voltro build` does not collapse this phase for a web app the way it does for `voltro serve`; it is the framework graph evaluated unbundled on every cold process |
+| `config` | `app.config.ts` + the typed-env gate |
+| `scan` | reading the built shell, resolving the api origin, the ISR cache backend, and walking `src/pages` |
+| `provider` | importing the precompiled SSR bundle (`dist/server/ssrEntry.js`). Stays small because page modules load lazily — a fat `provider` phase means the SSR bundle regressed to eager imports |
+| `routes` | building per-route metadata. Cheap from the build-time `pageMeta` manifest; fat only when it fell back to importing every page module |
+| `cdc` | postgres `LISTEN` wiring for ISR cache invalidation (zero without it) |
+| `ready` | the HTTP listener flip |
+
+**What boot timing cannot see:** `performance.now()` starts at *process* start, so everything before node runs — the container's scale-from-zero scheduling and image pull — is invisible to it. If a request that took many seconds end-to-end shows a `ready in` well under a second, the tail is infrastructure (image size, cold scheduling), not framework boot — split it with your platform's own request/container timestamps, not with more marks.
+
 ## Precompiled boot
 
 `voltro build` precompiles the whole serve path — the framework, Effect, and your app — into a single **serve bundle**, and `voltro serve` boots from it directly. Instead of resolving and compiling the full module graph on every cold process, the boot loads one prebuilt file with your app modules as lazy chunks. This collapses the `modules` phase — `serve: ready` drops from ~1000 ms to ~180 ms; the win is larger on a scale-to-zero container with a cold filesystem, where per-module resolution costs the most. It applies whether your app uses a SQL driver or the memory store: your declared driver (e.g. `@voltro/sql-postgres`) is inlined into the bundle, and only its native binding (`pg`) stays external.
@@ -415,6 +460,12 @@ Building an API app produces the bundle, and `voltro serve` boots from it. In **
 
 Because production never transpiles, the serve image needs none of the build toolchain. The framework declares `tsx`, `esbuild`, `vite`, and Tailwind as **optional** dependencies of `@voltro/cli`, and the production Dockerfiles isolate the app with `pnpm --prod --no-optional deploy` — which drops that whole tree (and its native binaries) from the image. A serve image ships only what it runs at runtime: your app, the framework, and the one SQL driver you declared.
 
+And it shrinks further, the same way a web image does. The serve bundle is directly executable, so the production API container runs it with `node .framework/dist-api/serveBundle/serveEntry.js` — not `pnpm voltro serve` — with no pnpm process and no `@voltro/cli` bin to resolve at boot. That lets `voltro prune-runtime` drop `@voltro/cli` and the whole inlined framework tree from the runtime image too; what stays is the native SQL driver your app actually declared (traced + kept automatically) — a memory-store api's `node_modules` fell from ~146 MB to ~11 MB in a fixture. The serve entry chdir's to the app root before its app-module registry keys are computed, so the pruned, relocated tree still resolves every module.
+
+**Web apps get the same treatment.** `voltro build` also precompiles the `voltro start` runtime into a **start bundle** (`.framework/dist-web/startBundle/startEntry.js`, framework inlined) — so a cold web boot loads one artefact instead of resolving the whole framework graph. This collapses the web `modules` phase the same way the serve bundle does (~17× on a small app in practice), which matters most exactly where it hurts: a scale-from-zero container on a fraction of a vCPU. In production the container runs that bundle **directly** — `node .framework/dist-web/startBundle/startEntry.js`, not `pnpm voltro start` — so there is no pnpm process and no `@voltro/cli` bin to resolve at boot; the bundle is a self-contained, relocation-safe entrypoint (its main-guard chdir's to the app root so cwd-based resolution holds anywhere). In development `voltro start` imports the same bundle; if it ever fails to build or load, that path falls back to the ordinary per-module boot — slower, never broken.
+
+**And the image itself shrinks — to almost nothing.** Because the SSR bundle, the start bundle, and the precompiled config all inline + tree-shake the framework, *and the production entrypoint is the bundle itself rather than the CLI*, a booted web app needs from `node_modules` only the runtime-external **native** leaves it actually reaches (a SQL driver an ISR or config path touches) — everything else is already compiled into the bundles. `voltro prune-runtime` traces the real reachable set from that entrypoint (`@vercel/nft`, the same tool behind Next.js `output: standalone`) and drops the rest — including `@voltro/cli` and the whole inlined effect/React tree, which nothing at runtime imports any more. It's automatic — a native driver you use is traced and kept, one you don't is dropped, no per-app allow-list — and for a static/SSR marketing site with no native runtime dependency, `node_modules` collapses to **zero** (measured on a fixture: 151 MB → ~0 B): the image is just the node base plus `.framework`. A build-time **boot smoke** then starts the *pruned* tree with the real `node …/startEntry.js` entrypoint and fails the build unless it reaches `start: ready`, so a slimmed image that can't boot never ships. A smaller image is a faster cold pull on a fresh node — the other half of the scale-from-zero latency the boot bundle can't touch.
+
 ## Tiers (Voltro Cloud — coming soon)
 
 Managed cloud hosting is not yet available; the Pro / Enterprise rows below are the planned managed tiers. Today you self-host and run `voltro dormancy` yourself.

package/templates/agent-docs/internationalization.md

@@ -115,6 +115,18 @@ export default defineLocale<typeof en>()({
 
 **Don't roll your own ICU MessageFormat.** Pluralization, gender, and ordinals across 50+ languages is a solved problem; reimplementing it produces bugs that only surface in specific locales (Turkish dotted-i, Arabic plurals, Finnish cases).
 
+**Check placeholder parity, not just key parity.** `defineLocale` enforces that every locale has the same KEYS, but not that each message has the same `{var}` set — a translation that drops or renames a `{var}` compiles and boots, then throws `The intl string context variable "date" was not provided` only in that locale, only when the message renders. `assertCatalogParity` catches it up front:
+
+```ts
+import { assertCatalogParity } from '@voltro/i18n'
+import en from './locales/en'
+import de from './locales/de'
+
+assertCatalogParity({ en, de }) // throws, listing every {var} drift
+```
+
+Call it in a test (or at boot with `{ onMismatch: 'warn' }`). Plural argument names are compared; a plural's inner `{# item}` branches are not mistaken for placeholders.
+
 ## Reading translations in components
 
 ```tsx
@@ -144,6 +156,65 @@ const locale = useLocale()
 - **`useLocale()`** — the active locale code, as React state inside the provider.
 - **`useMessages()`** — the active locale's RAW catalog (`useMessages()['some.id']`): the unformatted ICU template, not the formatted output. For when you need the raw string — e.g. to feed your own formatter, or a lookup that must not run ICU.
 
+## Compile-time keys AND params — `createTypedMessages`
+
+`defineLocale` catches a missing KEY at compile time, but the bare `useT` / `useTFn` don't type the KEY or the PARAMS at the *call site* — so `useT('home.greeting')` (a message that needs `{name}`) compiles and then throws at render (`The intl string context variable "name" was not provided`). `createTypedMessages<typeof en>()` binds the catalog's literal message types to `useT` / `useTFn` / `<T>` so both are compile errors:
+
+```tsx
+// src/i18n.ts — call once with your base catalog, re-export the result
+import { createTypedMessages } from '@voltro/i18n'
+import type en from './locales/en'
+
+export const { useT, useTFn, T } = createTypedMessages<typeof en>()
+```
+
+```tsx
+// now, everywhere you import from './i18n' instead of '@voltro/i18n':
+useT('home.greeting')              // ✗ compile error — expected { name: … }
+useT('home.greeting', { name })    // ✓
+useT('header.search')              // ✓ no placeholders → no values arg
+useT('does.not.exist')             // ✗ compile error — not a catalog key
+```
+
+It's almost pure type refinement — the runtime is the same `useT` / `useTFn` / `<T>` (plus a `.dynamic` escape, below), only the signatures narrow to your catalog. Requires the base catalog to be `as const` (so its message strings survive as literal types).
+
+**Scope.** Simple `{name}` and single-argument `{count, number}` placeholders are extracted and required. For a *nested* inline ICU message (`{count, plural, one {…} other {…}}` / `select`), the **top-level arg** (`count`) is required and a branch's inner text is NOT mistaken for a var — so `t('duration', { count })` typechecks and renders. A REAL var nested inside a branch (`other {# — {discipline}}`) is not collected, so it reads as *not required* rather than wrongly required; pass it via the loose values bag. Pluralising in JS over simple `{count}` messages (`items.map((i) => t('cart.one', { count: i.n }))`) stays fully typed. `<T>` gets a typed key with loose values, because its rich-text `<tag>` renderers can't be modelled by placeholder extraction.
+
+### Runtime-computed keys — `t.dynamic`
+
+For a key you build at runtime, do NOT cast it to the catalog key union — that union spans placeholder-bearing keys, so the call then demands a spurious 2nd ICU arg. Use `t.dynamic`, a plain-string escape with no forced args, on both `useT` and the `useTFn()` result:
+
+```tsx
+const t = useTFn()
+t.dynamic(`status.${row.state}`)                 // ✓ plain string, no forced arg
+t.dynamic(`greeting.${kind}`, { name })          // values still allowed, but loose
+```
+
+### Passing `t` across a package boundary — `LooseTFunction`
+
+Type a `t` pass-through param as `TypedTFunction<C>` to keep it strict — the strict type propagates down through helper signatures. At a boundary that *can't* import your catalog (a shared UI package), type the param `LooseTFunction` (`(id: string, values?) => string`) instead of `(...args: any[]) => string`, and pass `t.dynamic` — which IS a `LooseTFunction`. A strict `TypedTFunction` is deliberately NOT assignable to the loose one (a narrowed key param can't satisfy a wider one, and silently allowing it would erase the checking).
+
+```tsx
+// a shared package that can't see the app catalog
+import type { LooseTFunction } from '@voltro/i18n'
+export const formatError = (t: LooseTFunction, e: AppError): string => t(e.messageKey)
+
+// in the app, at the boundary:
+formatError(t.dynamic, err)
+```
+
+A convenient app-wide barrel captures the bound types once:
+
+```tsx
+// src/i18n.ts
+import { createTypedMessages, type TypedTFunction } from '@voltro/i18n'
+import type en from './locales/en'
+
+export const { useT, useTFn, T } = createTypedMessages<typeof en>()
+export type AppTFunction = TypedTFunction<typeof en>        // for helper / prop params
+export type AppMessageKey = Parameters<AppTFunction>[0]     // the catalog's key union
+```
+
 ## Reading a message outside React — `meta({ locale })`
 
 `useT` is a hook — it only runs inside a component, against the *active* locale. A page's `meta({ locale })` runs OUTSIDE React (at build / SSR meta-resolution time) and is handed an arbitrary locale string. Use **`pickCatalog`** to resolve a message there:

package/templates/agent-docs/multi-tenancy.md

@@ -337,6 +337,39 @@ tenant. Use this for per-tenant marketing pages, public listings filtered
 by tenant slug, status pages. Never expose any table that should require
 auth this way — the header is client-controlled and unauthenticated.
 
+## The empty-tenant sentinel — why a scoped read silently returns empty
+
+A subject that authenticated but has **no resolved org** carries the
+empty-string tenant `''`, not `null`. This is deliberate: `null` means a
+`system` subject and reads *unscoped*, so an org-less user must NOT be
+treated as one — that would stream every tenant's rows. Instead the
+auto-merged filter becomes `eq('tenantId', '')`, which matches no real
+row, so the read **fails closed**: it returns empty rather than leaking.
+
+The cost is a debugging trap — an empty result with no error looks
+identical to "no such row". So `voltro dev` warns once per tenant-scoped
+table when it happens:
+
+```txt
+[warn] tenant-scoped read with an EMPTY tenant — every row is filtered out
+  table: weeklyUpdates
+  cause: the subject authenticated but has no resolved org (tenantId=''),
+         so the auto-merged eq('tenantId', '') matches no real row —
+         this is NOT 'no such row'
+  fix:   resolve the subject to an active org before the read, or mark the
+         query .unscoped() if it is deliberately cross-tenant
+```
+
+If you see empty reads in development, this line tells you whether the
+cause is the data or an unresolved org. `voltro serve` does not emit it —
+it is a development diagnostic, not a production log.
+
+`voltro dev` also warns ONCE, earlier, the first time an authenticated
+subject resolves with no active org at all — "authenticated, but no active
+org → all tenant-scoped reads will be empty" — catching the whole class at
+the door before any specific read. Resolve the user to an active org during
+auth, or route org-less users to an onboarding flow.
+
 ## Subdomain-based tenant resolution
 
 For `tenant1.your-product.com` / `tenant2.your-product.com`, write a

package/templates/agent-docs/testing.md

@@ -320,6 +320,32 @@ Retries are always on and carry no backoff here. Production's jitter exists to d
 - **Transport concerns** — connection info, rate limiting, the tenant header. Those are properties of the HTTP hop, not of the procedure; faking them here would only assert against the fake.
 - **Undo capture and the metrics sample** — optional injections the serve entrypoint makes. Their absence changes nothing a handler can observe.
 
+## Completing a fixture row — `fixtureRow`
+
+`ctx.store` is the real mixin-wrapped store, so `store.insert` runs the same required-column validation production does: a payload that omits a NOT-NULL, no-default, non-auto-stamped column throws `TableValidationFailed` naming the column. That is deliberate — the test store is not laxer than Postgres, so a fixture can't pass on a row the database would reject. But it means a lean fixture (`insert('journal_entries', { id })`, an omitted required FK) now fails.
+
+`fixtureRow(table, overrides)` completes the row for you. It fills every column the validator would flag with a schema-typed placeholder, then merges your overrides on top — so you write only the columns the test cares about and the rest are made valid:
+
+```ts
+import { fixtureRow, makeTestContext } from '@voltro/testing'
+import { journalEntries } from '../schema/journal'
+
+const ctx = makeTestContext({ subject, store: mockStore({ journal_entries: [] }) })
+
+await ctx.store.insert('journal_entries', fixtureRow(journalEntries, {
+  amount: '100.00',          // the columns THIS test asserts on
+}))                          // entryNumber (unique), postedAt, … auto-filled
+```
+
+What it fills and what it leaves alone:
+
+- **Fills** each required column with a value of the right shape — a `oneOf` column takes its first allowed value, a `unique` column gets a distinct value per call (so two fixtures don't collide on the key), `timestamp` / `date` get a fixed epoch, `decimal` / `bigint` a numeric string.
+- **Leaves out** exactly what a caller may legitimately omit: nullable columns, defaulted columns, and the framework auto-stamped set (`id`, `tenantId`, `createdAt`, `updatedAt`, `createdBy`, `updatedBy`, `deletedAt`, `deletedBy`) — the store stamps those from the subject and the table scheme.
+- **Refuses to guess** a structured type (`json`, `bytes`, `vector`, `array`, `interval`, `raw`): it throws naming the column and telling you to pass it explicitly, rather than inventing a value that fails the codec obscurely.
+- **Your override always wins** — including an explicit `null`. Don't assert on a synthesized placeholder; override anything the test inspects.
+
+There is no flag to turn the validation off — a test store that accepts rows production rejects is a fake testing itself. `fixtureRow` is a runtime filler for the loose `store.insert(name, row)` path. For **compile-time** payload typing (a missing required column caught as a type error at the call), use [`insertRow` / `upsertRow`](/docs/data/mutations) from `@voltro/database`, which check against `InferInsertRow<T>`.
+
 ## Subject + tenant re-scoping
 
 `withSubject` and `withTenant` re-scope to a different principal for one block, sharing the **same** underlying data — so cross-subject reads exercise real tenant scoping, not a closure stub. This is how you prove isolation: write as one tenant, then assert another tenant can't see the row.

package/templates/apps/api-ai/package.json

@@ -11,16 +11,16 @@
   "dependencies": {
     "@effect/platform": "^0.96.1",
     "@effect/rpc": "^0.75.1",
-    "@voltro/ai": "0.11.0",
-    "@voltro/cli": "0.11.0",
-    "@voltro/database": "0.11.0",
-    "@voltro/env": "0.11.0",
-    "@voltro/protocol": "0.11.0",
-    "@voltro/runtime": "0.11.0",
+    "@voltro/ai": "0.11.2",
+    "@voltro/cli": "0.11.2",
+    "@voltro/database": "0.11.2",
+    "@voltro/env": "0.11.2",
+    "@voltro/protocol": "0.11.2",
+    "@voltro/runtime": "0.11.2",
     "effect": "^3.21.2"
   },
   "devDependencies": {
-    "@voltro/testing": "0.11.0",
+    "@voltro/testing": "0.11.2",
     "typescript": "^5.7.0",
     "vitest": "^3.0.0"
   }

package/templates/apps/api-auth/package.json

@@ -12,17 +12,17 @@
   "dependencies": {
     "@effect/platform": "^0.96.1",
     "@effect/rpc": "^0.75.1",
-    "@voltro/cli": "0.11.0",
-    "@voltro/database": "0.11.0",
-    "@voltro/env": "0.11.0",
-    "@voltro/plugin-auth": "0.11.0",
-    "@voltro/protocol": "0.11.0",
-    "@voltro/runtime": "0.11.0",
-    "@voltro/sql-postgres": "0.11.0",
+    "@voltro/cli": "0.11.2",
+    "@voltro/database": "0.11.2",
+    "@voltro/env": "0.11.2",
+    "@voltro/plugin-auth": "0.11.2",
+    "@voltro/protocol": "0.11.2",
+    "@voltro/runtime": "0.11.2",
+    "@voltro/sql-postgres": "0.11.2",
     "effect": "^3.21.2"
   },
   "devDependencies": {
-    "@voltro/testing": "0.11.0",
+    "@voltro/testing": "0.11.2",
     "typescript": "^5.7.0",
     "vitest": "^3.0.0"
   }

package/templates/apps/api-backend/package.json

@@ -12,16 +12,16 @@
   "dependencies": {
     "@effect/platform": "^0.96.1",
     "@effect/rpc": "^0.75.1",
-    "@voltro/cli": "0.11.0",
-    "@voltro/database": "0.11.0",
-    "@voltro/env": "0.11.0",
-    "@voltro/plugin-multitenancy": "0.11.0",
-    "@voltro/protocol": "0.11.0",
-    "@voltro/runtime": "0.11.0",
+    "@voltro/cli": "0.11.2",
+    "@voltro/database": "0.11.2",
+    "@voltro/env": "0.11.2",
+    "@voltro/plugin-multitenancy": "0.11.2",
+    "@voltro/protocol": "0.11.2",
+    "@voltro/runtime": "0.11.2",
     "effect": "^3.21.2"
   },
   "devDependencies": {
-    "@voltro/testing": "0.11.0",
+    "@voltro/testing": "0.11.2",
     "typescript": "^5.7.0",
     "vitest": "^3.0.0"
   }

package/templates/apps/api-backend-deactivation/package.json

@@ -12,16 +12,16 @@
   "dependencies": {
     "@effect/platform": "^0.96.1",
     "@effect/rpc": "^0.75.1",
-    "@voltro/cli": "0.11.0",
-    "@voltro/database": "0.11.0",
-    "@voltro/env": "0.11.0",
-    "@voltro/plugin-deactivation": "0.11.0",
-    "@voltro/protocol": "0.11.0",
-    "@voltro/runtime": "0.11.0",
+    "@voltro/cli": "0.11.2",
+    "@voltro/database": "0.11.2",
+    "@voltro/env": "0.11.2",
+    "@voltro/plugin-deactivation": "0.11.2",
+    "@voltro/protocol": "0.11.2",
+    "@voltro/runtime": "0.11.2",
     "effect": "^3.21.2"
   },
   "devDependencies": {
-    "@voltro/testing": "0.11.0",
+    "@voltro/testing": "0.11.2",
     "typescript": "^5.7.0",
     "vitest": "^3.0.0"
   }

package/templates/apps/api-backend-mail/package.json

@@ -12,18 +12,18 @@
   "dependencies": {
     "@react-email/components": "^1.0.12",
     "@react-email/render": "^1.4.0",
-    "@voltro/cli": "0.11.0",
-    "@voltro/database": "0.11.0",
-    "@voltro/env": "0.11.0",
-    "@voltro/plugin-mail": "0.11.0",
-    "@voltro/plugin-multitenancy": "0.11.0",
-    "@voltro/protocol": "0.11.0",
-    "@voltro/runtime": "0.11.0",
+    "@voltro/cli": "0.11.2",
+    "@voltro/database": "0.11.2",
+    "@voltro/env": "0.11.2",
+    "@voltro/plugin-mail": "0.11.2",
+    "@voltro/plugin-multitenancy": "0.11.2",
+    "@voltro/protocol": "0.11.2",
+    "@voltro/runtime": "0.11.2",
     "effect": "^3.21.2",
     "react": "^19.0.0"
   },
   "devDependencies": {
-    "@voltro/testing": "0.11.0",
+    "@voltro/testing": "0.11.2",
     "typescript": "^5.7.0",
     "vitest": "^3.0.0"
   }

package/templates/apps/api-backend-mariadb/package.json

@@ -12,18 +12,18 @@
   "dependencies": {
     "@effect/platform": "^0.96.1",
     "@effect/rpc": "^0.75.1",
-    "@voltro/cli": "0.11.0",
-    "@voltro/database": "0.11.0",
-    "@voltro/env": "0.11.0",
-    "@voltro/plugin-multitenancy": "0.11.0",
-    "@voltro/plugin-storage": "0.11.0",
-    "@voltro/protocol": "0.11.0",
-    "@voltro/runtime": "0.11.0",
-    "@voltro/sql-mysql": "0.11.0",
+    "@voltro/cli": "0.11.2",
+    "@voltro/database": "0.11.2",
+    "@voltro/env": "0.11.2",
+    "@voltro/plugin-multitenancy": "0.11.2",
+    "@voltro/plugin-storage": "0.11.2",
+    "@voltro/protocol": "0.11.2",
+    "@voltro/runtime": "0.11.2",
+    "@voltro/sql-mysql": "0.11.2",
     "effect": "^3.21.2"
   },
   "devDependencies": {
-    "@voltro/testing": "0.11.0",
+    "@voltro/testing": "0.11.2",
     "typescript": "^5.7.0",
     "vitest": "^3.0.0"
   }

package/templates/apps/api-backend-storage/package.json

@@ -10,17 +10,17 @@
     "test": "voltro test"
   },
   "dependencies": {
-    "@voltro/cli": "0.11.0",
-    "@voltro/database": "0.11.0",
-    "@voltro/env": "0.11.0",
-    "@voltro/plugin-multitenancy": "0.11.0",
-    "@voltro/plugin-storage": "0.11.0",
-    "@voltro/protocol": "0.11.0",
-    "@voltro/runtime": "0.11.0",
+    "@voltro/cli": "0.11.2",
+    "@voltro/database": "0.11.2",
+    "@voltro/env": "0.11.2",
+    "@voltro/plugin-multitenancy": "0.11.2",
+    "@voltro/plugin-storage": "0.11.2",
+    "@voltro/protocol": "0.11.2",
+    "@voltro/runtime": "0.11.2",
     "effect": "^3.21.2"
   },
   "devDependencies": {
-    "@voltro/testing": "0.11.0",
+    "@voltro/testing": "0.11.2",
     "typescript": "^5.7.0",
     "vitest": "^3.0.0"
   }