@voltro/cli 0.11.1 → 0.11.2

package/CHANGELOG.md

@@ -39,6 +39,44 @@ _Changes staged for the next release accumulate here (rolled up from
 
 ---
 
+## [0.11.2] — 2026-07-24
+
+### Added
+
+- **@voltro/i18n** — Two escapes for adopting typed messages (`createTypedMessages`, #16) app-wide (#19):
+
+  - **`t.dynamic(runtimeKey, values?)`** — a first-class escape for a genuinely runtime-computed key, on both `useT` and the `useTFn()` result. It takes a plain string with NO forced ICU args, so it doesn't fight the strict literal-key surface. Until now the natural escape — casting a computed key to the catalog key union — made things WORSE: that union spans placeholder-bearing keys, so the call then demanded a spurious 2nd ICU arg. `t.dynamic` is the documented, discoverable alternative. - **`LooseTFunction`** — the widened `(id: string, values?) => string` signature to type a `t` pass-through across a package boundary that can't import the app catalog, instead of falling back to `(...args: any[]) => string`. A strict `TypedTFunction` is deliberately NOT assignable to it (a narrowed key param can't satisfy a wider one — that would erase the checking); pass `t.dynamic` at the boundary, which IS a `LooseTFunction`.
+
+  Additive: `TypedTFunction<C>` gains a `.dynamic` member (the callable surface is unchanged, so `Parameters<TypedTFunction<C>>[0]` and existing typed call sites still resolve). `createTypedMessages` attaches `.dynamic` in place on the two translate functions — no new per-render closure, so a captured `t`'s identity stays stable.
+- **@voltro/testing, @voltro/database** — `fixtureRow(table, overrides)` (`@voltro/testing`) completes a partial test row so it satisfies the 0.11.1 required-column insert validation — WITHOUT disabling the check. It fills every NOT-NULL, no-default, non-auto-stamped column the payload omits with a schema-typed placeholder (a `oneOf` column takes its first allowed value; a `unique` column gets a distinct value per call so two fixtures don't collide; `timestamp`/`date` get a fixed epoch), then merges your overrides on top (an explicit value always wins). It leaves out exactly what a caller may omit — nullable, defaulted, and framework auto-stamped columns (id / tenant / audit) — and refuses to guess a structured type (`json` / `bytes` / `vector` / `array` / `interval` / `raw`), throwing a message that names the column and says to pass it explicitly.
+
+  The motivating case: 0.11.1 made the in-memory/test store reject the same partial inserts real Postgres always would (correct — it surfaced a latent prod bug), which turned lean fixtures (`insert(users, { id })`, an omitted required FK) into `TableValidationFailed`. The wrong fix is a `validateInserts: false` knob — it re-hides that bug class, and a test store laxer than production is a fake testing itself. `fixtureRow` is the right one: it makes the fixture COMPLETE.
+
+  ```ts
+  await ctx.store.insert('journal_entries', fixtureRow(journalEntries, {
+    tenantId, amount: '100.00',   // the columns THIS test cares about
+  }))                             // entryNumber, postedAt, … auto-filled + unique
+  ```
+
+  It is a runtime filler for the loose `store.insert(name, row)` path (what fixtures use). For COMPILE-time payload typing, use `insertRow` / `upsertRow` from `@voltro/database`. The auto-stamped column set it skips is now exported as `AUTO_FILLED_COLUMNS` from `@voltro/database` — the same list `InferInsertRow` derives its optional columns from, single-sourced so the two can't drift.
+
+### Changed
+
+- **@voltro/cli** — `voltro build` now emits **directly-executable** boot bundles for BOTH app kinds: the web start bundle (`.framework/dist-web/startBundle/startEntry.js`) and the api serve bundle (`.framework/dist-api/serveBundle/serveEntry.js`) each carry a main-guard that boots the app when run as `node <entry>.js`, and stays inert when imported (the `voltro start` / `voltro serve` dev fast paths are unchanged). Production containers can now use `CMD ["node", "…/startEntry.js"]` (or `serveEntry.js`) instead of `pnpm voltro start` / `pnpm voltro serve` — no pnpm process, no `@voltro/cli` bin at runtime — which is what makes `voltro prune-runtime` safe to enable on both: with the self-contained bundle as the real entrypoint, the @vercel/nft trace roots there and legitimately drops `@voltro/cli` and the whole inlined framework tree (a static site's `node_modules` collapses to ~0; a memory api's 146 MB → 11 MB). `prune-runtime` now also roots the trace at the serve bundle. The serve entry chdir's to the app root BEFORE its app-module registry keys are computed from cwd, preserving relocation-safety. Existing `pnpm voltro start` / `pnpm voltro serve` entrypoints keep working. The standalone Dockerfiles gain a build-time boot smoke that fails the build unless the pruned tree reaches ready.
+
+### Fixed
+
+- **@voltro/i18n** — `createTypedMessages` (#16) no longer extracts phantom required vars from a nested plural/select message (#19). For `'{count, plural, one {# day} other {# days total duration}}'`, the type-level `ICUVars` parse was reading a branch's TEXT (`"# days total duration"`) as a bogus required arg name, so `useT('key', { count })` failed to typecheck even though it renders perfectly — and a real var nested inside a branch was dropped. `ICUArgName` now resolves to `never` for any candidate that isn't a valid ICU identifier (`^[A-Za-z0-9_]+$`), so branch text — which contains spaces / `#` / `—` — is never mistaken for a var. Only the top-level arg (`count`) is required, matching what the message actually needs.
+
+  Scope note: a REAL var nested inside a plural branch (`other {# — {discipline}}`) is still not collected, so it reads as not-required rather than wrongly-required — the safe direction. Apps that pluralise in JS over simple `{count}` messages (the Voltro idiom) were already fully typed and are unaffected.
+- **@voltro/database, @voltro/runtime** — `InferInsertRow` (and thus `insertRow` / `upsertRow`, #15) no longer requires a non-nullable DB-generated (`generatedAs`) column (#20). A stored/virtual generated column declared without `.nullable()` and without a default was typed **required**, but MariaDB/Postgres REJECT an explicit value for a generated column — so the type forced the caller to pass a value the database refuses at runtime. `.generatedAs()` now marks the column optional-for-insert exactly like a `.default()` column (the DB supplies it), so it may be omitted; the whole payload guard on every real column stays intact.
+
+  Two runtime halves complete it, so the loose `store.insert(name, row)` path agrees: the required-column validation (`missingRequiredColumns`) skips generated columns — omitting one is correct, never a missing-column error — and the store write path now STRIPS any value a caller supplied for a generated column before the INSERT reaches the dialect (tracked on the schema registry as `generatedColumns`), so a value from an untyped insert can't blow up on MariaDB. A generated column is never caller-supplied; the framework and the DB own it end to end.
+
+  The `.generatedAs()` return type narrows from `this` to `ColumnBuilder<…, true>` (the HasDefault flag) — a purely more-permissive refinement: it only makes the column omittable, so no existing code stops compiling.
+
+---
+
 ## [0.11.1] — 2026-07-23
 
 ### Added
@@ -71,6 +109,8 @@ _Changes staged for the next release accumulate here (rolled up from
 - **@voltro/database, @voltro/runtime** — `store.insert` / `upsert` / `insertIgnore` now raise a clear, typed `TableValidationFailed` naming the column when the payload omits one that is NOT NULL, has no default, and isn't auto-stamped — instead of a raw dialect `SqlError: Failed to execute statement` (`Field '…' doesn't have a default value`) surfaced only on the INSERT path (so it lay dormant until the first row with no existing cache entry). An upsert / insertIgnore whose payload is missing one of its own `conflictColumns` is likewise named at the call (an absent conflict key can't match its target). The check runs AFTER stamping, so auto-id / tenant / audit columns never trip it, and skips nullable, defaulted, and id (`idScheme`) columns — exactly the ones a caller may legitimately omit.
 
   Two pure helpers back it — `missingRequiredColumns(table, row)` and `missingConflictColumns(conflictColumns, row)` (exported from `@voltro/database`). This is the runtime half of the "handler data silently disagrees with the schema" class; a compile-time payload type needs the column DSL to track `hasDefault` at the type level, which is a separate change.
+
+  **Migration impact — behaviour-breaking for lenient test fixtures.** The in-memory/test store now rejects the same partial inserts a real Postgres always would, so it stops being laxer than production — which is the point (it surfaced at least one latent prod bug where a NOT-NULL `text().unique()` column was written without a value). But a fixture that inserted a partial row (`{ id }` parents, an omitted required FK) and passed against the old lenient memory store now throws `TableValidationFailed`. There is no code-level codemod — the fix is fixture DATA: fill the required columns. Use the new `fixtureRow(table, overrides)` helper in `@voltro/testing`, which fills every NOT-NULL-no-default column with a schema-typed placeholder and merges your overrides on top, so a fixture complies without disabling the check. There is deliberately no opt-out to turn the validation off: a test store that accepts rows production rejects is a fake testing itself.
 - **@voltro/database, @voltro/plugin-ai-flows, @voltro/plugin-audit, @voltro/plugin-deactivation, @voltro/plugin-soft-delete** — Compile-time payload typing for writes (#15) — the type-level half that the runtime `TableValidationFailed` guard flagged as a separate change. `insertRow` / `upsertRow` take the TABLE OBJECT (not a string name), so the payload is checked against `InferInsertRow<T>`: every column is required EXCEPT nullable ones, columns with a default, and the framework-filled id/tenant/audit columns. A missing NOT-NULL-no-default column — the exact `lastRefreshedAt` / `teamId` omission from the report — is now a COMPILE error at the call, not a runtime SqlError only on the INSERT path; `upsertRow`'s `conflictColumns` are constrained to the table's own columns too.
 
   import { insertRow } from '@voltro/database' await insertRow(ctx.store, roadmapEpicStats, { teamId, lastRefreshedAt: new Date() })

package/dist/{apiBuild-D_kEJTxc.js → apiBuild-BVIiATXr.js}

@@ -153,15 +153,19 @@ const drivers = ${JSON.stringify(t)}\nlet mod\nfor (const d of drivers) {\n  try
 		...c(_) ? { tsconfig: _ } : {}
 	}), y = Object.keys(v.metafile.inputs).map((e) => o(t, e)).filter((e) => e.startsWith(`${t}/`) && !e.includes("/node_modules/") && !e.includes("/.framework/") && m(e)), b = await f(t), x = /* @__PURE__ */ new Set(), S = [
 		"// GENERATED BY `voltro build` — do not edit; overwritten on next build.",
-		"import { join as __join } from 'node:path'",
+		"import { join as __join, dirname as __dirname, resolve as __resolve } from 'node:path'",
+		"import { pathToFileURL as __pathToFileURL, fileURLToPath as __fileURLToPath } from 'node:url'",
 		"import { runServe as __runServe, registerAppModules, registerDriver, loadDotEnv } from '@voltro/cli/serveEntry'",
 		...b.map((e, t) => `import * as __drv${t} from ${JSON.stringify(e)}`),
+		"const __isMain = Boolean(process.argv[1]) && import.meta.url === __pathToFileURL(process.argv[1]).href",
+		"if (__isMain) process.chdir(__resolve(__dirname(__fileURLToPath(import.meta.url)), '..', '..', '..'))",
 		"const __root = process.cwd()",
 		"registerAppModules({",
 		...y.map((e) => `  [__join(__root, ${JSON.stringify(a(t, e))})]: () => import(${JSON.stringify(e)}),`),
 		"})",
 		...b.map((e, t) => `registerDriver(${JSON.stringify(e)}, __drv${t})`),
 		"export const runServe = (args = []) => { loadDotEnv([]); return __runServe(args) }",
+		"if (__isMain) runServe(process.argv.slice(2)).then((c) => process.exit(typeof c === 'number' ? c : 0))",
 		""
 	], w = i(r, "serveEntry.ts");
 	return await l.writeFile(w, S.join("\n"), "utf8"), await n.build({

package/dist/apiBuild-C_KY5oY_.js

@@ -0,0 +1,2 @@
+import { a as e, o as t } from "./apiBuild-BVIiATXr.js";
+export { e as runApiBuild, t as runServeBundleBuild };

package/dist/bin.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { bt as e } from "./inspectMetrics-BuBwg1yW.js";
-import { n as t } from "./commands-BiQsbV50.js";
+import { n as t } from "./commands-C0ytPFfl.js";
 import { createLogger as n } from "@voltro/logger";
 //#region src/bin.ts
 var r = n({ scope: "voltro:cli" }), i = process.argv.slice(2);

package/dist/{commands-BiQsbV50.js → commands-C0ytPFfl.js}

@@ -1,9 +1,9 @@
 import { At as e, D as t, Dt as n, F as r, Ft as i, It as a, K as o, M as s, Mt as c, N as l, Nt as u, Ot as d, P as f, Pt as p, T as m, a as h, b as g, c as _, d as v, f as y, jt as ee, k as b, kt as te, n as ne, o as re, p as ie, s as ae, u as oe, v as se, w as ce, x as le, y as ue } from "./inspectMetrics-BuBwg1yW.js";
 import { B as de, K as fe, L as pe, R as me, V as he, ct as ge, i as _e, l as ve, n as ye, o as be, p as xe, rt as Se, tt as Ce, ut as we, z as Te } from "./dev-zJGsTTNb.js";
 import { a as x, c as Ee, i as De, o as Oe, s as ke } from "./devActivity-1WtIVyHc.js";
-import { i as Ae, n as je, s as Me, t as Ne } from "./apiBuild-D_kEJTxc.js";
+import { i as Ae, n as je, s as Me, t as Ne } from "./apiBuild-BVIiATXr.js";
 import { t as Pe } from "./start-ChN6PO-c.js";
-import { n as Fe, r as Ie } from "./serveCommand-BU454-ay.js";
+import { n as Fe, r as Ie } from "./serveCommand-Dd3oLzbo.js";
 import { basename as S, dirname as C, isAbsolute as Le, join as w, relative as T, resolve as E, sep as Re } from "node:path";
 import { fileURLToPath as ze, pathToFileURL as Be } from "node:url";
 import { FileSystem as Ve } from "@effect/platform";
@@ -282,8 +282,25 @@ external scheduler owns the once-only guarantee.
 	return await N.writeFile(o, [
 		"// GENERATED BY `voltro build` — do not edit; overwritten on next build.",
 		"import { runStartCommand as __run, loadDotEnv } from '@voltro/cli/startEntry'",
+		"import { pathToFileURL, fileURLToPath } from 'node:url'",
+		"import { dirname, resolve } from 'node:path'",
 		"export const runStartCommand = (args = []) => { loadDotEnv([]); return __run(args) }",
 		"export { loadDotEnv }",
+		"",
+		"// DIRECT-INVOKE ENTRY. `node startEntry.js` is the PRODUCTION container command",
+		"// — no `pnpm voltro start` wrapper, so the container never resolves the @voltro/cli",
+		"// bin and `voltro prune-runtime` can drop the CLI (and the whole inlined",
+		"// effect/@voltro/react tree) from the runtime image: the trace roots at THIS",
+		"// self-contained bundle, which is now also the real entrypoint. When this module",
+		"// is IMPORTED instead (bin/voltro.mjs's dev fast path) the guard is inert.",
+		"if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {",
+		"  // Relocation-safe: the app root is 3 dirs up from",
+		"  // .framework/dist-web/startBundle/startEntry.js — chdir there so tryRunStart",
+		"  // resolves the SSR bundle + appConfig from cwd regardless of the launch dir",
+		"  // (WORKDIR already sets it in our image; this makes it robust anywhere).",
+		"  process.chdir(resolve(dirname(fileURLToPath(import.meta.url)), '..', '..', '..'))",
+		"  runStartCommand(process.argv.slice(2)).then((c) => process.exit(typeof c === 'number' ? c : 0))",
+		"}",
 		""
 	].join("\n"), "utf8"), await t.build({
 		entryPoints: [o],
@@ -714,7 +731,7 @@ external scheduler owns the once-only guarantee.
 		let { loadApiConfig: t } = await import("./dev-DH13Ysgs.js"), n = await t(e);
 		if (n) {
 			B.info("building api app", { app: n.name ?? "(unnamed)" });
-			let { runApiBuild: t, runServeBundleBuild: r } = await import("./apiBuild-BGd-BnHq.js");
+			let { runApiBuild: t, runServeBundleBuild: r } = await import("./apiBuild-C_KY5oY_.js");
 			await t(e);
 			try {
 				await r(e);
@@ -8330,6 +8347,12 @@ image, use \`voltro serverless serve\` from the project root.
 		"dist",
 		"server",
 		"appConfig.js"
+	],
+	[
+		".framework",
+		"dist-api",
+		"serveBundle",
+		"serveEntry.js"
 	]
 ], sp = ["pg", ...Ne.filter((e) => !e.includes("*"))], cp = async (e) => {
 	let t = w(e, "node_modules");

package/dist/index.js

@@ -1,4 +1,4 @@
-import { i as e, n as t, r as n, t as r } from "./commands-BiQsbV50.js";
+import { i as e, n as t, r as n, t as r } from "./commands-C0ytPFfl.js";
 //#region src/index.ts
 var i = "framework";
 //#endregion

package/dist/{serveCommand-BU454-ay.js → serveCommand-Dd3oLzbo.js}

@@ -1,7 +1,7 @@
 import { kt as e, t } from "./inspectMetrics-BuBwg1yW.js";
 import { $ as n, A as r, C as i, D as a, E as o, F as s, G as c, H as l, I as u, J as d, M as f, N as p, O as ee, P as m, Q as h, S as g, T as te, U as ne, W as re, X as _, Y as ie, Z as ae, _ as oe, at as v, b as se, d as ce, et as y, f as b, g as le, h as ue, i as x, it as de, j as S, k as C, m as fe, n as pe, nt as me, o as w, ot as T, q as he, s as ge, st as _e, t as ve, ut as E, v as ye, w as be, x as xe, y as D } from "./dev-zJGsTTNb.js";
 import { a as Se, r as Ce } from "./startupRunner-DhlX9nqd.js";
-import { n as we, s as O } from "./apiBuild-D_kEJTxc.js";
+import { n as we, s as O } from "./apiBuild-BVIiATXr.js";
 import { t as Te } from "./bootTiming-BdyP9nYw.js";
 import { join as Ee } from "node:path";
 import { pathToFileURL as De } from "node:url";

package/dist/serveEntry.js

@@ -1,5 +1,5 @@
 import { bt as e } from "./inspectMetrics-BuBwg1yW.js";
 import { dt as t } from "./dev-zJGsTTNb.js";
 import { a as n } from "./startupRunner-DhlX9nqd.js";
-import { t as r } from "./serveCommand-BU454-ay.js";
+import { t as r } from "./serveCommand-Dd3oLzbo.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.11.1",
+  "version": "0.11.2",
   "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.11.1",
-    "@voltro/cache": "0.11.1",
-    "@voltro/data-transfer": "0.11.1",
-    "@voltro/database": "0.11.1",
-    "@voltro/env": "0.11.1",
-    "@voltro/kv": "0.11.1",
-    "@voltro/logger": "0.11.1",
-    "@voltro/plugin-auth": "0.11.1",
-    "@voltro/plugin-broadcast": "0.11.1",
-    "@voltro/plugin-mail": "0.11.1",
-    "@voltro/plugin-storage": "0.11.1",
-    "@voltro/plugin-webhooks": "0.11.1",
-    "@voltro/protocol": "0.11.1",
-    "@voltro/runtime": "0.11.1",
-    "@voltro/serverless": "0.11.1",
-    "@voltro/workflow": "0.11.1",
+    "@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",

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

@@ -460,9 +460,11 @@ 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.
 
-**Web apps get the same treatment.** `voltro build` also precompiles the `voltro start` runtime into a **start bundle** (`.framework/dist-web/startBundle/`, framework inlined), and `voltro start` boots from it automatically — 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. It is transparent — no config, no separate command, and it travels in `.framework` with everything else the deploy already copies. If the bundle ever fails to build or load, `voltro start` falls back to the ordinary per-module boot: slower, never broken.
+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.
 
-**And the image itself shrinks.** Because the SSR bundle, the start bundle, and the precompiled config all inline + tree-shake the framework, 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. The standalone web Dockerfiles trace the real reachable set (`@vercel/nft`, the same tool behind Next.js `output: standalone`) and drop the rest. 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 nothing: the image is just the base plus `.framework`. On a real marketing app the shipped app tree fell from ~210 MB to ~65 MB. 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.
+**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)
 

package/templates/agent-docs/internationalization.md

@@ -176,9 +176,44 @@ useT('header.search')              // ✓ no placeholders → no values arg
 useT('does.not.exist')             // ✗ compile error — not a catalog key
 ```
 
-It's pure type refinement — the runtime is the same `useT` / `useTFn` / `<T>`, only the signatures narrow to your catalog. Requires the base catalog to be `as const` (so its message strings survive as literal types).
+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. Messages with *nested* inline ICU (`{n, plural, one {…} other {…}}` / `select`) accept a loose values bag instead of a wrong strict one — pluralise in JS over simple `{count}` messages (`items.map((i) => t('cart.one', { count: i.n }))`) to stay fully typed. `<T>` gets a typed key with loose values, because its rich-text `<tag>` renderers can't be modelled by placeholder extraction.
+**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 })`
 

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.1",
-    "@voltro/cli": "0.11.1",
-    "@voltro/database": "0.11.1",
-    "@voltro/env": "0.11.1",
-    "@voltro/protocol": "0.11.1",
-    "@voltro/runtime": "0.11.1",
+    "@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.1",
+    "@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.1",
-    "@voltro/database": "0.11.1",
-    "@voltro/env": "0.11.1",
-    "@voltro/plugin-auth": "0.11.1",
-    "@voltro/protocol": "0.11.1",
-    "@voltro/runtime": "0.11.1",
-    "@voltro/sql-postgres": "0.11.1",
+    "@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.1",
+    "@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.1",
-    "@voltro/database": "0.11.1",
-    "@voltro/env": "0.11.1",
-    "@voltro/plugin-multitenancy": "0.11.1",
-    "@voltro/protocol": "0.11.1",
-    "@voltro/runtime": "0.11.1",
+    "@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.1",
+    "@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.1",
-    "@voltro/database": "0.11.1",
-    "@voltro/env": "0.11.1",
-    "@voltro/plugin-deactivation": "0.11.1",
-    "@voltro/protocol": "0.11.1",
-    "@voltro/runtime": "0.11.1",
+    "@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.1",
+    "@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.1",
-    "@voltro/database": "0.11.1",
-    "@voltro/env": "0.11.1",
-    "@voltro/plugin-mail": "0.11.1",
-    "@voltro/plugin-multitenancy": "0.11.1",
-    "@voltro/protocol": "0.11.1",
-    "@voltro/runtime": "0.11.1",
+    "@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.1",
+    "@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.1",
-    "@voltro/database": "0.11.1",
-    "@voltro/env": "0.11.1",
-    "@voltro/plugin-multitenancy": "0.11.1",
-    "@voltro/plugin-storage": "0.11.1",
-    "@voltro/protocol": "0.11.1",
-    "@voltro/runtime": "0.11.1",
-    "@voltro/sql-mysql": "0.11.1",
+    "@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.1",
+    "@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.1",
-    "@voltro/database": "0.11.1",
-    "@voltro/env": "0.11.1",
-    "@voltro/plugin-multitenancy": "0.11.1",
-    "@voltro/plugin-storage": "0.11.1",
-    "@voltro/protocol": "0.11.1",
-    "@voltro/runtime": "0.11.1",
+    "@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.1",
+    "@voltro/testing": "0.11.2",
     "typescript": "^5.7.0",
     "vitest": "^3.0.0"
   }

package/templates/apps/api-data-advanced/package.json

@@ -11,17 +11,17 @@
   "dependencies": {
     "@effect/platform": "^0.96.1",
     "@effect/rpc": "^0.75.1",
-    "@voltro/cli": "0.11.1",
-    "@voltro/database": "0.11.1",
-    "@voltro/env": "0.11.1",
-    "@voltro/plugin-governance": "0.11.1",
-    "@voltro/plugin-multitenancy": "0.11.1",
-    "@voltro/protocol": "0.11.1",
-    "@voltro/runtime": "0.11.1",
+    "@voltro/cli": "0.11.2",
+    "@voltro/database": "0.11.2",
+    "@voltro/env": "0.11.2",
+    "@voltro/plugin-governance": "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.1",
+    "@voltro/testing": "0.11.2",
     "typescript": "^5.7.0",
     "vitest": "^3.0.0"
   }

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

@@ -11,17 +11,17 @@
   "dependencies": {
     "@effect/platform": "^0.96.1",
     "@effect/rpc": "^0.75.1",
-    "@voltro/cli": "0.11.1",
-    "@voltro/database": "0.11.1",
-    "@voltro/env": "0.11.1",
-    "@voltro/plugin-multitenancy": "0.11.1",
-    "@voltro/protocol": "0.11.1",
-    "@voltro/runtime": "0.11.1",
-    "@voltro/workflow": "0.11.1",
+    "@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",
+    "@voltro/workflow": "0.11.2",
     "effect": "^3.21.2"
   },
   "devDependencies": {
-    "@voltro/testing": "0.11.1",
+    "@voltro/testing": "0.11.2",
     "typescript": "^5.7.0",
     "vitest": "^3.0.0"
   }