@voltro/cli 0.11.2 → 0.11.3

package/CHANGELOG.md

@@ -39,6 +39,61 @@ _Changes staged for the next release accumulate here (rolled up from
 
 ---
 
+## [0.11.3] — 2026-07-24
+
+### Added
+
+- **@voltro/runtime** — `crud.*` secure-default CRUD handler helpers + `redactColumns` (A1 core). Each returns an executor you export as a `*.query.server.ts` / `*.mutation.server.ts` default — the descriptor (schemas + `guards`) stays hand-written and browser-safe:
+
+  ```ts
+  // accounts.list.query.server.ts
+  import { crud } from '@voltro/runtime'
+  export default crud.list('accounts', { redact: ['apiSecret'] })
+  ```
+
+  They bake in the invariants a hand-rolled CRUD generator kept getting wrong (the leak class was in the HANDLERS, not the schemas):
+
+  - **Tenant scope** — `list` / `getById` read through `ctx.store`, which auto-scopes a `tenant()` table; they never `.unscoped()`, so a cross-tenant read is impossible. - **Redaction** — `redact` columns are stripped from every returned row (a credential / secret / salary a read must never ship), on reads AND on the row a `create` / `update` echoes. `redactColumns(rows, cols)` is exported standalone for a hand-written handler that isn't plain CRUD. - **`getById` returns `null`, never throws** — a reactive getter that throws stalls its shared-WS siblings (pairs with the per-subscription error isolation).
+
+  What they deliberately DON'T do is authorize: a guard runs before the executor, so gating stays on the DESCRIPTOR (`guards: [...]`) — an executor can't gate itself. Keep write descriptors guarded.
+
+  Scope note: this is the browser-safe, codegen-free core. Deriving the descriptor SCHEMAS from a table (to drop the hand-written `Schema.Struct`) is structurally a codegen concern — a table VALUE can't be imported into a browser-loaded descriptor (it drags the store into the bundle; `rowSchema` is server-only for exactly this reason) — so full schema-derivation + a `.crud()` boot audit for the scope/gating discipline are a separate, planned pass. See `plans/framework-a1-defineCrud.md`.
+- **@voltro/runtime** — `ctx.store.links(junctionTable, anchor)` — a diff-based writer for a many-to-many JUNCTION table (A2). It reconciles the links from one anchor row against a target-id list by writing only the DIFFERENCE:
+
+  ```ts
+  await ctx.store.links('post_tags', { postId: post.id }).set(tagIds) // add missing, remove surplus
+  await ctx.store.links('post_tags', { postId: post.id }).add([tagId]) // idempotent
+  await ctx.store.links('post_tags', { postId: post.id }).remove([tagId])
+  await ctx.store.links('post_tags', { postId: post.id }).list()      // current target ids
+  ```
+
+  Why it belongs in the framework rather than every app: a drop-all-then-reinsert `setLinks` loses data when two writers overlap and makes a reactive subscription on the junction churn every row (flicker) even when nothing changed. `links().set()` touches only the rows that actually differ — the added are inserted, the removed deleted, the unchanged left in place — so a reactive consumer sees a change only for what changed, and `set()` returns `{ added, removed }`. `add`/`remove` are likewise idempotent (they read first and act only on the genuine delta).
+
+  `anchor` names the source column and its id (`{ postId: 'p1' }`); the target column is the junction's OTHER `reference()` column, auto-detected. A junction with anything but exactly two reference columns is refused with a message naming what it found — use plain `insertMany`/`deleteMany` for a non-standard junction. The writes go through the normal stamped/tenant-scoped store path, so tenant and audit columns are filled as usual. Additive: a new `links` method on `FluentStore` + the `JunctionLinks` interface.
+- **@voltro/client, @voltro/web** — `useSubscription(..., { initialSnapshot })` — the last mile of "SSR-correct first paint, then live" (A5). Pass the value an SSR loader already fetched with `ctx.query` (read it in the component with `useLoaderData()`) and the subscription shows it at the first paint with `loading: false` — it IS real server data — then swaps to the live stream the instant its first snapshot arrives:
+
+  ```tsx
+  const seed = useLoaderData<Employee>()
+  const { data } = useSubscription('app', 'employees.me', {}, { initialSnapshot: seed })
+  ```
+
+  The SSR markup and the hydration render read the same loader value, so they match (no hydration flicker), and the app no longer hand-builds a seed store to bridge loader data into the first render. This is the difference from `fallback`, whose value never came from the server and so keeps `loading: true`; use exactly one of the two. Like `fallback`, `initialSnapshot` guarantees `data` is present, so the call gets the non-union result and needs no `loading` branch. Additive: a new `initialSnapshot` field on `SubscriptionOptions` + an overload; `@voltro/web` re-exports the client surface.
+- **@voltro/cli** — `apis.<name>.authHeaders` in a web `app.config.ts` — a declarative per-reconnect auth-header resolver, so an authenticated split-origin web app no longer hand-mounts `VoltroRuntimeProvider` just to inject a rotating-token thunk (A4). The framework owns the client mount, the reconnect re-resolve, and the SSR-null case (the resolver runs browser-only — it never fires on the server):
+
+  ```ts
+  // app.config.ts
+  apis: {
+    api: {
+      package: '@app/api',
+      authHeaders: async () => ({ authorization: `Bearer ${await getToken()}` }),
+    },
+  }
+  ```
+
+  Because it's a FUNCTION, the codegen imports it from `app.config.ts` into the client bundle rather than serializing it — so a config that declares `authHeaders` must stay browser-safe (no `node:*` / server-only value imports; a pure env schema is fine, and tree-shakes out). It supersedes a static `headers` on the same api. The provider already resolved a `ResolvableHeaders` thunk fresh per connection generation; this just lets you declare it in config instead of hand-writing a `mount()` call.
+
+---
+
 ## [0.11.2] — 2026-07-24
 
 ### Added

package/dist/apiBuild-BmPdmhgi.js

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

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

@@ -1,5 +1,5 @@
-import { Mt as e } from "./inspectMetrics-BuBwg1yW.js";
-import { d as t, lt as n } from "./dev-zJGsTTNb.js";
+import { Mt as e } from "./inspectMetrics-SRtv8KDy.js";
+import { d as t, lt as n } from "./dev-CGt0PP1f.js";
 import { isAbsolute as r, join as i, relative as a, resolve as o } from "node:path";
 import { createLogger as s } from "@voltro/logger";
 import { existsSync as c, promises as l } from "node:fs";

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-C0ytPFfl.js";
+import { bt as e } from "./inspectMetrics-SRtv8KDy.js";
+import { n as t } from "./commands-BDGYrBhK.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-C0ytPFfl.js → commands-BDGYrBhK.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 { 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-SRtv8KDy.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-CGt0PP1f.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-BVIiATXr.js";
-import { t as Pe } from "./start-ChN6PO-c.js";
-import { n as Fe, r as Ie } from "./serveCommand-Dd3oLzbo.js";
+import { i as Ae, n as je, s as Me, t as Ne } from "./apiBuild-zFDv0u8y.js";
+import { t as Pe } from "./start-Crl39M38.js";
+import { n as Fe, r as Ie } from "./serveCommand-p6e5Ahgx.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";
@@ -728,10 +728,10 @@ external scheduler owns the once-only guarantee.
 }, tr = async (e) => {
 	let t = await ae(e);
 	if (!t) {
-		let { loadApiConfig: t } = await import("./dev-DH13Ysgs.js"), n = await t(e);
+		let { loadApiConfig: t } = await import("./dev-D_PGP9Kx.js"), n = await t(e);
 		if (n) {
 			B.info("building api app", { app: n.name ?? "(unnamed)" });
-			let { runApiBuild: t, runServeBundleBuild: r } = await import("./apiBuild-C_KY5oY_.js");
+			let { runApiBuild: t, runServeBundleBuild: r } = await import("./apiBuild-BmPdmhgi.js");
 			await t(e);
 			try {
 				await r(e);

package/dist/{dev-zJGsTTNb.js → dev-CGt0PP1f.js}

@@ -1,4 +1,4 @@
-import { $ as e, A as t, B as n, C as r, Dt as i, E as a, Et as o, G as s, H as c, Lt as l, O as u, Pt as d, Q as f, R as p, U as m, V as h, W as g, X as _, Y as ee, Z as te, _t as ne, at as re, ct as ie, dt as ae, et as v, ft as oe, gt as y, ht as se, it as ce, j as le, kt as ue, l as b, lt as de, mt as fe, nt as pe, ot as me, pt as he, rt as ge, st as _e, t as ve, tt as ye, ut as be, vt as xe, w as Se, xt as Ce, yt as we } from "./inspectMetrics-BuBwg1yW.js";
+import { $ as e, A as t, B as n, C as r, Dt as i, E as a, Et as o, G as s, H as c, Lt as l, O as u, Pt as d, Q as f, R as p, U as m, V as h, W as g, X as _, Y as ee, Z as te, _t as ne, at as re, ct as ie, dt as ae, et as v, ft as oe, gt as y, ht as se, it as ce, j as le, kt as ue, l as b, lt as de, mt as fe, nt as pe, ot as me, pt as he, rt as ge, st as _e, t as ve, tt as ye, ut as be, vt as xe, w as Se, xt as Ce, yt as we } from "./inspectMetrics-SRtv8KDy.js";
 import { i as x, n as Te, t as Ee } from "./startupRunner-DhlX9nqd.js";
 import { r as De } from "./devActivity-1WtIVyHc.js";
 import { t as Oe } from "./frameworkInspectState-CX2250XB.js";

package/dist/dev-D_PGP9Kx.js

@@ -0,0 +1,2 @@
+import { o as e } from "./dev-CGt0PP1f.js";
+export { e as loadApiConfig };

package/dist/index.js

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

package/dist/{inspectMetrics-BuBwg1yW.js → inspectMetrics-SRtv8KDy.js}

@@ -2754,7 +2754,8 @@ import {
 	browserWsUrl: t.url,
 	proxyTarget: void 0,
 	...t.serverUrl ? { serverOrigin: t.serverUrl } : {},
-	...t.headers ? { headers: t.headers } : {}
+	...t.headers ? { headers: t.headers } : {},
+	...t.authHeaders ? { hasAuthHeaders: !0 } : {}
 }), Di = (e, t, n) => {
 	let r = t.transport?.wsPath ?? n.wsPath;
 	return {
@@ -2764,7 +2765,8 @@ import {
 		proxyTarget: `ws://localhost:${n.port}`,
 		...r ? { wsPath: r } : {},
 		...t.serverUrl ? { serverOrigin: t.serverUrl } : {},
-		...t.headers ? { headers: t.headers } : {}
+		...t.headers ? { headers: t.headers } : {},
+		...t.authHeaders ? { hasAuthHeaders: !0 } : {}
 	};
 }, Oi = (e) => {
 	let t = /* @__PURE__ */ new Map();
@@ -2891,9 +2893,11 @@ import {
 		""
 	].join("\n"), u = r(e, "src", "pages"), { pages: d, dirs: f } = await $(u);
 	await rr(u, d);
-	let p = (e) => `${e.replace(/[^a-zA-Z0-9]/g, "_")}AppGroup`, m = (e) => `${e.replace(/[^a-zA-Z0-9]/g, "_")}AppDescriptors`, h = n.map((e) => `import { appGroup as ${p(e.name)}, appDescriptors as ${m(e.name)} } from '${e.pkg}/rpcGroup'`), g = n.map((e) => {
+	let p = (e) => `${e.replace(/[^a-zA-Z0-9]/g, "_")}AppGroup`, m = (e) => `${e.replace(/[^a-zA-Z0-9]/g, "_")}AppDescriptors`, h = n.map((e) => `import { appGroup as ${p(e.name)}, appDescriptors as ${m(e.name)} } from '${e.pkg}/rpcGroup'`);
+	n.some((e) => e.hasAuthHeaders) && (h.push("import __voltroAppConfig from '../app.config'"), h.push("const __voltroAuthHeaders = (__voltroAppConfig as { readonly apis?: Record<string, { readonly authHeaders?: () => Record<string, string> | Promise<Record<string, string>> }> }).apis"));
+	let g = n.map((e) => {
 		let t = [`group: ${p(e.name)}`];
-		return t.push(`descriptors: ${m(e.name)}`), t.push(`wsUrl: ${JSON.stringify(e.browserWsUrl)}`), e.headers && t.push(`headers: ${JSON.stringify(e.headers)}`), `    ${JSON.stringify(e.name)}: { ${t.join(", ")} },`;
+		return t.push(`descriptors: ${m(e.name)}`), t.push(`wsUrl: ${JSON.stringify(e.browserWsUrl)}`), e.hasAuthHeaders ? t.push(`headers: __voltroAuthHeaders?.[${JSON.stringify(e.name)}]?.authHeaders`) : e.headers && t.push(`headers: ${JSON.stringify(e.headers)}`), `    ${JSON.stringify(e.name)}: { ${t.join(", ")} },`;
 	}), _, v, b;
 	if (d.length > 0) {
 		let e = d.map((e) => `  ${JSON.stringify(e.pattern)}: () => import('../src/pages/${e.file}'),`), n = [];

package/dist/{serveCommand-Dd3oLzbo.js → serveCommand-p6e5Ahgx.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 { kt as e, t } from "./inspectMetrics-SRtv8KDy.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-CGt0PP1f.js";
 import { a as Se, r as Ce } from "./startupRunner-DhlX9nqd.js";
-import { n as we, s as O } from "./apiBuild-BVIiATXr.js";
+import { n as we, s as O } from "./apiBuild-zFDv0u8y.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 { bt as e } from "./inspectMetrics-SRtv8KDy.js";
+import { dt as t } from "./dev-CGt0PP1f.js";
 import { a as n } from "./startupRunner-DhlX9nqd.js";
-import { t as r } from "./serveCommand-Dd3oLzbo.js";
+import { t as r } from "./serveCommand-p6e5Ahgx.js";
 export { e as loadDotEnv, n as registerAppModules, t as registerDriver, r as runServe };

package/dist/{start-ChN6PO-c.js → start-Crl39M38.js}

@@ -1,4 +1,4 @@
-import { A as e, C as t, Ct as n, E as r, Et as i, G as a, H as o, I as s, J as c, Mt as l, N as u, O as d, R as ee, St as f, Tt as p, U as m, V as h, W as g, Z as _, _ as v, _t as te, a as y, at as b, b as x, c as ne, f as S, g as re, gt as C, h as w, i as T, j as E, k as D, kt as O, m as k, o as ie, p as ae, q as A, r as oe, s as se, t as ce, v as j, w as le, wt as M, y as N } from "./inspectMetrics-BuBwg1yW.js";
+import { A as e, C as t, Ct as n, E as r, Et as i, G as a, H as o, I as s, J as c, Mt as l, N as u, O as d, R as ee, St as f, Tt as p, U as m, V as h, W as g, Z as _, _ as v, _t as te, a as y, at as b, b as x, c as ne, f as S, g as re, gt as C, h as w, i as T, j as E, k as D, kt as O, m as k, o as ie, p as ae, q as A, r as oe, s as se, t as ce, v as j, w as le, wt as M, y as N } from "./inspectMetrics-SRtv8KDy.js";
 import { t as ue } from "./bootTiming-BdyP9nYw.js";
 import { dirname as P, extname as F, join as I, resolve as L } from "node:path";
 import { fileURLToPath as R, pathToFileURL as de } from "node:url";

package/dist/startEntry.js

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

package/package.json

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

package/templates/agent-docs/_manifest.json

@@ -53,7 +53,7 @@
       "group": null,
       "description": "How Voltro's reactive data layer works — queries, mutations, actions, streams, all over one WebSocket with typed errors and tracked dependencies.",
       "path": "agent-docs/data.md",
-      "files": 15
+      "files": 16
     },
     {
       "id": "database/advancedqueries",

package/templates/agent-docs/authentication.md

@@ -723,6 +723,28 @@ The strategy above only *verifies* — your browser still has to *send* the toke
 
   This is **required when the api is a separate origin** (the common case — `api.example.com` vs your web origin): there is no shared cookie and no upgrade header, so without `headers` every subscription connects **anonymous** (the shell renders, but user-/tenant-scoped data stays empty). A static object works for non-rotating tokens; never hardcode a secret literal — it ships to the browser.
 
+### Declaratively — `apis.<name>.authHeaders` in `app.config.ts`
+
+Rather than hand-writing a `mount()` entry just to inject the thunk, declare it on the api in `app.config.ts`. The framework owns the client mount, the SSR-null case (the resolver runs browser-only — it never fires on the server), and the re-resolve on every reconnect; you supply only the token function:
+
+```ts
+// app.config.ts
+export default {
+  type: 'web' as const,
+  apis: {
+    api: {
+      package: '@app/api',
+      // Resolved fresh on every (re)connect — a rotating token is pulled anew:
+      authHeaders: async () => ({
+        authorization: `Bearer ${(await supabase.auth.getSession()).data.session?.access_token ?? ''}`,
+      }),
+    },
+  },
+}
+```
+
+`authHeaders` is a **function**, so it is imported from `app.config.ts` into the client bundle rather than serialized — the file must stay browser-safe (no `node:*` / server-only value imports; the env schema and other pure config are fine). It supersedes a static `headers` on the same api. This is the preferred form; reach for a hand-written `mount()` only when you need to wrap the tree in your own provider as well.
+
 ## WorkOS
 
 ```ts

package/templates/agent-docs/data.md

@@ -315,6 +315,8 @@ export default defineExecutor(notesSummary, async (_input, ctx) => {
 
 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.
 
+> **Composing one executor inside another (e.g. a workflow `step`).** The value `defineExecutor` returns is typed as the `ExecutorReturn` UNION (`Output | Promise | Effect | descriptor-return`), so it has no `.pipe` — you can't feed the wrapped default export straight into another Effect. Export the handler's raw `Effect` separately (a named `export const execute = …`, or import the un-wrapped function) and compose THAT; keep the `defineExecutor`-wrapped default only as the procedure's entry point. The union return is deliberate — it's what lets one helper type every executor shape — so this is a "import the raw effect for composition" convention, not a gap to route around.
+
 ## Auto-optimistic source
 
 `source` also connects query caches to mutation `target` metadata:
@@ -1947,6 +1949,72 @@ When no analytics sink is configured the framework provides the no-op sink: the
 
 
 
+---
+
+<!-- source: en/data/crud.md -->
+## CRUD helpers
+
+_crud.* secure-default handler helpers — tenant-scoped reads, column redaction, and null-not-throw getById, so the CRUD tail of a handler is one honest line._
+
+Most of a plain list / get / create / update / delete handler is the same five lines every time — and getting those lines subtly wrong is how data leaks. The `crud.*` helpers from `@voltro/runtime` give you the **executor** with the secure defaults baked in; you still write the descriptor (schemas + `guards`), which is where the browser-safe wire contract and the authorization live.
+
+```ts
+// accounts.list.query.server.ts
+import { crud } from '@voltro/runtime'
+
+export default crud.list('accounts', { redact: ['apiSecret'] })
+```
+
+```ts
+// accounts.list.query.ts — the descriptor stays hand-written + browser-safe
+import { defineQuery } from '@voltro/protocol'
+import { Schema } from 'effect'
+
+export default defineQuery({
+  name: 'accounts.list',
+  input: Schema.Struct({}),
+  // note: the wire output OMITS apiSecret, so it never reaches the client
+  output: Schema.Array(Schema.Struct({ id: Schema.String, name: Schema.String })),
+})
+```
+
+## What the defaults bake in
+
+- **Tenant scope.** `crud.list` and `crud.getById` read through `ctx.store`, which auto-scopes a `tenant()` table. They never call `.unscoped()`, so a cross-tenant read is impossible through them — `payslips.list` cannot return another tenant's rows.
+- **Redaction.** `redact` names columns stripped from every returned row — a credential, a token hash, a salary that a generated read must never ship. It applies to reads and to the row a `create` / `update` echoes back. Declare the same omission in the descriptor's `output` schema so the column never reaches the client at all; the helper is the runtime guarantee that it doesn't, whatever the schema says.
+- **`getById` returns `null`, never throws.** A reactive getter that throws takes its shared-WebSocket siblings down with it. `crud.getById` resolves `null` for an absent row.
+
+## The helpers
+
+| Helper | Executor it returns |
+|---|---|
+| `crud.list(table, { redact? })` | tenant-scoped list of every row, redacted |
+| `crud.getById(table, { redact? })` | one row by `input.id`, or `null` — redacted |
+| `crud.create(table, { redact? })` | insert `input`; id/tenant/audit auto-stamped; echoes the redacted row |
+| `crud.update(table, { redact? })` | patch `{ id, ...patch }`; returns the updated row or `null` |
+| `crud.remove(table)` | delete `input.id`; returns `{ deleted }` |
+
+`redactColumns(rows, cols)` is exported standalone for a hand-written handler that isn't plain CRUD but still needs to redact declaratively.
+
+## What they deliberately don't do — authorization
+
+A guard runs *before* the executor, so gating lives on the **descriptor**, not the handler — an executor cannot gate itself. Keep every write descriptor guarded:
+
+```ts
+export default defineMutation({
+  name: 'accounts.create',
+  input: AccountInput,
+  output: Account,
+  guards: [requireScope('accounts:write')],   // ← the gate; crud.create does not add one
+})
+```
+
+## Scope — why the schema is still hand-written
+
+These helpers give you the secure **handler**, not schema derivation. Deriving the descriptor's `input`/`output` from the table automatically would need the table VALUE inside the descriptor file — and a descriptor is loaded value-level by the browser client, so importing a table there drags the store and driver into the browser bundle (the boundary guard aborts the boot; `rowSchema` is server-only for exactly this reason). Full schema-derivation, and a boot audit that fails when a `tenant()` table's list reads unscoped or a write goes ungated, are a separate planned pass — the handler defaults above are the part that ships browser-safe today and closes the leak class.
+
+
+
 ---
 
 <!-- source: en/data/subscribers.md -->

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

@@ -1044,6 +1044,22 @@ The framework deliberately avoids the Prisma / TypeORM "auto-generated junction"
 
 3. **Schema is explicit**. Looking at your `database/` directory tells you exactly which tables exist. No hidden auto-generated tables to chase down at migration time.
 
+## Writing links — `store.links`
+
+Reconciling the set of links from one row (a post's tags, a user's orgs) by hand — read the current rows, work out which to insert and which to delete — is fiddly and easy to get wrong. A drop-all-then-reinsert shortcut loses data when two requests overlap and makes a reactive subscription on the junction churn *every* row even when nothing changed. `ctx.store.links(junctionTable, anchor)` does the diff for you:
+
+```ts
+// anchor names the source column + id; the target column is auto-detected
+await ctx.store.links('org_memberships', { userId: user.id }).set(orgIds)  // reconcile to exactly orgIds
+await ctx.store.links('org_memberships', { userId: user.id }).add([orgId]) // idempotent — no-op if already linked
+await ctx.store.links('org_memberships', { userId: user.id }).remove([orgId])
+const orgIds = await ctx.store.links('org_memberships', { userId: user.id }).list()
+```
+
+`set(targetIds)` writes only the **difference**: the missing links are inserted, the surplus deleted, and links that are already correct are left untouched — so a reactive consumer sees a change only for what actually changed, and it returns `{ added, removed }`. `add` and `remove` read first and act only on the genuine delta, so both are idempotent.
+
+The **target column** is the junction's *other* `reference()` column — the one the anchor doesn't name. A junction with anything but exactly two reference columns is refused (write it by hand with `insertMany` / `deleteMany`). The writes go through the normal store path, so a junction that carries `tenant()` / `audit()` gets those columns stamped as usual. A junction with extra business columns (a membership `role`, a tag `order`) needs those set per row — `links` only manages the two FK columns, so insert those rows directly.
+
 ## SQL shape
 
 The framework emits an INNER JOIN through the junction:

package/templates/agent-docs/internationalization.md

@@ -178,13 +178,25 @@ 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.
+**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 {# blockers in {discipline}}`) is not collected, so it reads as *not required* rather than wrongly required; pass it via the loose values bag.
+
+To get that nested var **compiler-required**, split the plural into simple sibling keys and pick with a JS branch — each key is then a plain message where every var is top-level:
+
+```tsx
+// catalog: 'blocker.one': '{count} blocker in {discipline}', 'blocker.other': '{count} blockers in {discipline}'
+count === 1
+  ? t('blocker.one',   { count, discipline })   // ✓ both vars required
+  : t('blocker.other', { count, discipline })
+```
+
+(The [`plural()` helper](/docs/i18n/formatting) only substitutes `{count}`, so it doesn't type or fill a second var — use it for count-only messages.) `<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
+import { useTFn } from '@app/messages' // your createTypedMessages() barrel — `.dynamic` lives on these
 const t = useTFn()
 t.dynamic(`status.${row.state}`)                 // ✓ plain string, no forced arg
 t.dynamic(`greeting.${kind}`, { name })          // values still allowed, but loose

package/templates/agent-docs/routing.md

@@ -793,6 +793,23 @@ Two consequences worth designing around:
   a side effect), put it in an effect or use `useSubscription` — do not rely on
   the loader firing a second time.
 
+#### SSR first paint, then live — `initialSnapshot`
+
+When a page wants the SSR-rendered data AND a live subscription, hand the loader's value to `useSubscription` as its `initialSnapshot`. The loader fetches the data on the server with `ctx.query`; the subscription shows that value at the first paint with `loading: false` — it is real server data, not a placeholder — then swaps to the live stream the instant its first snapshot arrives:
+
+```tsx
+export const loader = async ({ query }) => query('employees.me', {})
+
+export default function Profile() {
+  const seed = useLoaderData<Employee>()
+  // First paint shows the SSR value; the WS stream takes over seamlessly.
+  const { data } = useSubscription<Employee>('app', 'employees.me', {}, { initialSnapshot: seed })
+  return <ProfileCard employee={data} />
+}
+```
+
+Because the SSR markup and the hydration render read the same loader value, they match — no hydration flicker — and you don't hand-build a seed store to bridge the two. This is distinct from `fallback`, whose value never came from the server and so keeps `loading: true`; use exactly one of the two.
+
 Client-side navigation is unchanged: moving to another route runs that route's
 loaders in the browser as usual. A `spa` page has no server render, so its
 loader runs on the client on first mount.

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.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",
+    "@voltro/ai": "0.11.3",
+    "@voltro/cli": "0.11.3",
+    "@voltro/database": "0.11.3",
+    "@voltro/env": "0.11.3",
+    "@voltro/protocol": "0.11.3",
+    "@voltro/runtime": "0.11.3",
     "effect": "^3.21.2"
   },
   "devDependencies": {
-    "@voltro/testing": "0.11.2",
+    "@voltro/testing": "0.11.3",
     "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.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",
+    "@voltro/cli": "0.11.3",
+    "@voltro/database": "0.11.3",
+    "@voltro/env": "0.11.3",
+    "@voltro/plugin-auth": "0.11.3",
+    "@voltro/protocol": "0.11.3",
+    "@voltro/runtime": "0.11.3",
+    "@voltro/sql-postgres": "0.11.3",
     "effect": "^3.21.2"
   },
   "devDependencies": {
-    "@voltro/testing": "0.11.2",
+    "@voltro/testing": "0.11.3",
     "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.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/cli": "0.11.3",
+    "@voltro/database": "0.11.3",
+    "@voltro/env": "0.11.3",
+    "@voltro/plugin-multitenancy": "0.11.3",
+    "@voltro/protocol": "0.11.3",
+    "@voltro/runtime": "0.11.3",
     "effect": "^3.21.2"
   },
   "devDependencies": {
-    "@voltro/testing": "0.11.2",
+    "@voltro/testing": "0.11.3",
     "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.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",
+    "@voltro/cli": "0.11.3",
+    "@voltro/database": "0.11.3",
+    "@voltro/env": "0.11.3",
+    "@voltro/plugin-deactivation": "0.11.3",
+    "@voltro/protocol": "0.11.3",
+    "@voltro/runtime": "0.11.3",
     "effect": "^3.21.2"
   },
   "devDependencies": {
-    "@voltro/testing": "0.11.2",
+    "@voltro/testing": "0.11.3",
     "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.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",
+    "@voltro/cli": "0.11.3",
+    "@voltro/database": "0.11.3",
+    "@voltro/env": "0.11.3",
+    "@voltro/plugin-mail": "0.11.3",
+    "@voltro/plugin-multitenancy": "0.11.3",
+    "@voltro/protocol": "0.11.3",
+    "@voltro/runtime": "0.11.3",
     "effect": "^3.21.2",
     "react": "^19.0.0"
   },
   "devDependencies": {
-    "@voltro/testing": "0.11.2",
+    "@voltro/testing": "0.11.3",
     "typescript": "^5.7.0",
     "vitest": "^3.0.0"
   }