@voltro/cli 0.53.0 → 0.54.0

package/dist/{webDev-C7jWJ5dX.js → webDev-DlvZO30c.js}

@@ -1,2 +1,2 @@
-import { p as e, x as t, y as n } from "./webDev-oczpugbx.js";
+import { p as e, x as t, y as n } from "./webDev-DSI9SOhs.js";
 export { e as loadConfig, n as tryRunWebServe, t as walkPagesTree };

package/dist/{webhooksCommand-4SVPDjKg.js → webhooksCommand-BvzXNHji.js}

@@ -222,7 +222,7 @@ createVerifier({ secret: [process.env.WEBHOOK_SECRET, process.env.WEBHOOK_SECRET
 		...t === void 0 ? {} : { payload: t }
 	};
 }, S = u({ scope: "voltro:webhooks" }), C = ["--out", "--name"], w = async (e) => {
-	let { walk: t, loadDiscovered: n } = await import("./dev-GjJWAYo2.js"), { outgoingFromEvents: r } = await import("./webhookDiscovery-il9ti-HE.js");
+	let { walk: t, loadDiscovered: n } = await import("./dev-cKUiZZsB.js"), { outgoingFromEvents: r } = await import("./webhookDiscovery-il9ti-HE.js");
 	return r((await n(await t(e))).events.map((e) => ({
 		file: e.file,
 		descriptor: e.descriptor

package/dist/workspaceDeps-RKEkX92S.js

@@ -0,0 +1,45 @@
+import { dirname as e, join as t } from "node:path";
+import { promises as n } from "node:fs";
+//#region src/workspaceDeps.ts
+var r = async (r, i) => {
+	let a = r;
+	for (;;) {
+		let r = t(a, "node_modules", i);
+		try {
+			if ((await n.stat(r)).isDirectory()) {
+				let e = await n.realpath(r);
+				return e.includes("/node_modules/") ? null : e;
+			}
+		} catch {}
+		let o = e(a);
+		if (o === a) return null;
+		a = o;
+	}
+}, i = async (e) => {
+	let i;
+	try {
+		let r = await n.readFile(t(e, "package.json"), "utf8"), a = JSON.parse(r);
+		i = Object.keys({
+			...a.dependencies,
+			...a.devDependencies
+		});
+	} catch {
+		return [];
+	}
+	return (await Promise.all(i.map(async (i) => {
+		let a = await r(e, i);
+		if (a === null) return null;
+		let o = t(a, "src");
+		try {
+			if (!(await n.stat(o)).isDirectory()) return null;
+		} catch {
+			return null;
+		}
+		return {
+			pkg: i,
+			dir: o
+		};
+	}))).filter((e) => e !== null);
+};
+//#endregion
+export { i as n, r as t };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltro/cli",
-  "version": "0.53.0",
+  "version": "0.54.0",
   "description": "The `voltro` CLI — dev server, codegen, migrations, project scaffolding, agent-docs seeding, and production serve.",
   "keywords": [
     "voltro",
@@ -836,24 +836,24 @@
     "@effect/platform-node": "^0.108.0",
     "@effect/sql": "^0.52.0",
     "@effect/workflow": "^0.19.0",
-    "@voltro/ai": "0.53.0",
-    "@voltro/cache": "0.53.0",
-    "@voltro/client": "0.53.0",
-    "@voltro/content": "0.53.0",
-    "@voltro/data-transfer": "0.53.0",
-    "@voltro/database": "0.53.0",
-    "@voltro/env": "0.53.0",
-    "@voltro/kv": "0.53.0",
-    "@voltro/logger": "0.53.0",
-    "@voltro/plugin-auth": "0.53.0",
-    "@voltro/plugin-broadcast": "0.53.0",
-    "@voltro/plugin-mail": "0.53.0",
-    "@voltro/plugin-storage": "0.53.0",
-    "@voltro/plugin-webhooks": "0.53.0",
-    "@voltro/protocol": "0.53.0",
-    "@voltro/runtime": "0.53.0",
-    "@voltro/serverless": "0.53.0",
-    "@voltro/workflow": "0.53.0",
+    "@voltro/ai": "0.54.0",
+    "@voltro/cache": "0.54.0",
+    "@voltro/client": "0.54.0",
+    "@voltro/content": "0.54.0",
+    "@voltro/data-transfer": "0.54.0",
+    "@voltro/database": "0.54.0",
+    "@voltro/env": "0.54.0",
+    "@voltro/kv": "0.54.0",
+    "@voltro/logger": "0.54.0",
+    "@voltro/plugin-auth": "0.54.0",
+    "@voltro/plugin-broadcast": "0.54.0",
+    "@voltro/plugin-mail": "0.54.0",
+    "@voltro/plugin-storage": "0.54.0",
+    "@voltro/plugin-webhooks": "0.54.0",
+    "@voltro/protocol": "0.54.0",
+    "@voltro/runtime": "0.54.0",
+    "@voltro/serverless": "0.54.0",
+    "@voltro/workflow": "0.54.0",
     "chokidar": "^5.0.0",
     "ioredis": "^5.11.1",
     "tinyglobby": "^0.2.17",

package/templates/AGENTS.core.md

@@ -368,6 +368,8 @@ public REST routes, declared via `restRoutes` in `app.config.ts`).
 | `*.agent.tsx` + `*.agent.server.tsx` | server-side LLM chat |
 | `*.tool.tsx` | tool an agent can call |
 | `*.entity.ts` / `*.schema.ts` / `schema.ts` | one table per file |
+| `*.collection.ts` | content collection (`defineCollection`) — schema-typed markdown/JSON |
+| `content/<name>/**` | that collection's files (markdown + frontmatter, or `.json`) |
 | `page.tsx` (under `src/pages/`) | the route its DIRECTORY serves + `page.test.tsx` |
 | `*.component.tsx` | exactly ONE component (+ types) |
 | `*.component.ui.tsx` | presentational: one component, READS only — never writes |

package/templates/AGENTS.md

@@ -368,6 +368,8 @@ public REST routes, declared via `restRoutes` in `app.config.ts`).
 | `*.agent.tsx` + `*.agent.server.tsx` | server-side LLM chat |
 | `*.tool.tsx` | tool an agent can call |
 | `*.entity.ts` / `*.schema.ts` / `schema.ts` | one table per file |
+| `*.collection.ts` | content collection (`defineCollection`) — schema-typed markdown/JSON |
+| `content/<name>/**` | that collection's files (markdown + frontmatter, or `.json`) |
 | `page.tsx` (under `src/pages/`) | the route its DIRECTORY serves + `page.test.tsx` |
 | `*.component.tsx` | exactly ONE component (+ types) |
 | `*.component.ui.tsx` | presentational: one component, READS only — never writes |
@@ -728,7 +730,7 @@ each plugin's own README.
 
 | Topic | Open | Summary |
 |---|---|---|
-| **What's new in 0.53.0** | `node_modules/@voltro/cli/templates/agent-docs/whats-new.md` | Everything that changed in this version. Read it before hand-rolling something the framework may now ship. |
+| **What's new in 0.54.0** | `node_modules/@voltro/cli/templates/agent-docs/whats-new.md` | Everything that changed in this version. Read it before hand-rolling something the framework may now ship. |
 | AI | `node_modules/@voltro/cli/templates/agent-docs/ai.md` | How Voltro treats AI — agents, tools, streaming, RAG — all primitives over the same WebSocket as the rest of the framework. |
 | Authentication | `node_modules/@voltro/cli/templates/agent-docs/authentication.md` | How @voltro/plugin-auth wires password + session-cookie auth across api + web, plus the pluggable identity-strategy protocol. |
 | Caching | `node_modules/@voltro/cli/templates/agent-docs/caching.md` | Voltro's caching layer (@voltro/cache) — an always-on memory default, swappable Redis-compatible backends, a low-level wrap primitive, and automatic query-result invalidation. |
@@ -786,7 +788,7 @@ each plugin's own README.
 | auth-workos | `node_modules/@voltro/cli/templates/agent-docs/plugins/auth-workos.md` (or `node_modules/@voltro/plugin-auth-workos/README.md`) | WorkOS AuthStrategy — verifies WorkOS AuthKit / SSO JWTs via JWKS (no API key) and maps org_id → tenantId. |
 | billing | `node_modules/@voltro/cli/templates/agent-docs/plugins/billing.md` (or `node_modules/@voltro/plugin-billing/README.md`) | Subscriptions, plans, entitlements, and usage metering over a pluggable provider (Stripe + mock). Money is integer minor units. |
 | broadcast | `node_modules/@voltro/cli/templates/agent-docs/plugins/broadcast.md` (or `node_modules/@voltro/plugin-broadcast/README.md`) | Cross-replica reactivity over a pub/sub bus (Redis / NATS) for non-postgres dialects — closes the single-instance gap so a write on one pod surfaces on another. |
-| cdc-out | `node_modules/@voltro/cli/templates/agent-docs/plugins/cdc-out.md` (or `node_modules/@voltro/plugin-cdc-out/README.md`) | Declaratively mirror table changes outward to external sinks (webhook, plus a CdcSink interface for custom sinks) through a durable outbox — ordered per pipe, at-least-once from enqueue, retried with backoff, dead-lettered. |
+| cdc-out | `node_modules/@voltro/cli/templates/agent-docs/plugins/cdc-out.md` (or `node_modules/@voltro/plugin-cdc-out/README.md`) | Declaratively mirror table changes outward to external sinks (webhook, Kafka, plus a CdcSink interface for custom sinks) through a durable outbox — ordered per pipe, at-least-once from enqueue, retried with backoff, dead-lettered. |
 | clickhouse | `node_modules/@voltro/cli/templates/agent-docs/plugins/clickhouse.md` (or `node_modules/@voltro/plugin-clickhouse/README.md`) | Production-grade OLAP AnalyticsSink over ClickHouse — self-hosted or ClickHouse Cloud — for billions of events with millisecond aggregates. |
 | comments | `node_modules/@voltro/cli/templates/agent-docs/plugins/comments.md` (or `node_modules/@voltro/plugin-comments/README.md`) | Comment threads on any app entity — replies, resolve/reopen, @-mentions with notifications, reactions, unread counters — live over the reactive engine, with an ejectable thread UI. |
 | datadog | `node_modules/@voltro/cli/templates/agent-docs/plugins/datadog.md` (or `node_modules/@voltro/plugin-datadog/README.md`) | Agentless Datadog metrics exporter — pushes the unified Metrics-API to Datadog's /api/v2/series HTTP intake. |

package/templates/agent-docs/_index.md

@@ -9,7 +9,7 @@ each plugin's own README.
 
 | Topic | Open | Summary |
 |---|---|---|
-| **What's new in 0.53.0** | `node_modules/@voltro/cli/templates/agent-docs/whats-new.md` | Everything that changed in this version. Read it before hand-rolling something the framework may now ship. |
+| **What's new in 0.54.0** | `node_modules/@voltro/cli/templates/agent-docs/whats-new.md` | Everything that changed in this version. Read it before hand-rolling something the framework may now ship. |
 | AI | `node_modules/@voltro/cli/templates/agent-docs/ai.md` | How Voltro treats AI — agents, tools, streaming, RAG — all primitives over the same WebSocket as the rest of the framework. |
 | Authentication | `node_modules/@voltro/cli/templates/agent-docs/authentication.md` | How @voltro/plugin-auth wires password + session-cookie auth across api + web, plus the pluggable identity-strategy protocol. |
 | Caching | `node_modules/@voltro/cli/templates/agent-docs/caching.md` | Voltro's caching layer (@voltro/cache) — an always-on memory default, swappable Redis-compatible backends, a low-level wrap primitive, and automatic query-result invalidation. |
@@ -67,7 +67,7 @@ each plugin's own README.
 | auth-workos | `node_modules/@voltro/cli/templates/agent-docs/plugins/auth-workos.md` (or `node_modules/@voltro/plugin-auth-workos/README.md`) | WorkOS AuthStrategy — verifies WorkOS AuthKit / SSO JWTs via JWKS (no API key) and maps org_id → tenantId. |
 | billing | `node_modules/@voltro/cli/templates/agent-docs/plugins/billing.md` (or `node_modules/@voltro/plugin-billing/README.md`) | Subscriptions, plans, entitlements, and usage metering over a pluggable provider (Stripe + mock). Money is integer minor units. |
 | broadcast | `node_modules/@voltro/cli/templates/agent-docs/plugins/broadcast.md` (or `node_modules/@voltro/plugin-broadcast/README.md`) | Cross-replica reactivity over a pub/sub bus (Redis / NATS) for non-postgres dialects — closes the single-instance gap so a write on one pod surfaces on another. |
-| cdc-out | `node_modules/@voltro/cli/templates/agent-docs/plugins/cdc-out.md` (or `node_modules/@voltro/plugin-cdc-out/README.md`) | Declaratively mirror table changes outward to external sinks (webhook, plus a CdcSink interface for custom sinks) through a durable outbox — ordered per pipe, at-least-once from enqueue, retried with backoff, dead-lettered. |
+| cdc-out | `node_modules/@voltro/cli/templates/agent-docs/plugins/cdc-out.md` (or `node_modules/@voltro/plugin-cdc-out/README.md`) | Declaratively mirror table changes outward to external sinks (webhook, Kafka, plus a CdcSink interface for custom sinks) through a durable outbox — ordered per pipe, at-least-once from enqueue, retried with backoff, dead-lettered. |
 | clickhouse | `node_modules/@voltro/cli/templates/agent-docs/plugins/clickhouse.md` (or `node_modules/@voltro/plugin-clickhouse/README.md`) | Production-grade OLAP AnalyticsSink over ClickHouse — self-hosted or ClickHouse Cloud — for billions of events with millisecond aggregates. |
 | comments | `node_modules/@voltro/cli/templates/agent-docs/plugins/comments.md` (or `node_modules/@voltro/plugin-comments/README.md`) | Comment threads on any app entity — replies, resolve/reopen, @-mentions with notifications, reactions, unread counters — live over the reactive engine, with an ejectable thread UI. |
 | datadog | `node_modules/@voltro/cli/templates/agent-docs/plugins/datadog.md` (or `node_modules/@voltro/plugin-datadog/README.md`) | Agentless Datadog metrics exporter — pushes the unified Metrics-API to Datadog's /api/v2/series HTTP intake. |

package/templates/agent-docs/_manifest.json

@@ -460,7 +460,7 @@
     {
       "slug": "cdc-out",
       "title": "CDC-out (reverse-ETL)",
-      "description": "Declaratively mirror table changes outward to external sinks (webhook, plus a CdcSink interface for custom sinks) through a durable outbox — ordered per pipe, at-least-once from enqueue, retried with backoff, dead-lettered.",
+      "description": "Declaratively mirror table changes outward to external sinks (webhook, Kafka, plus a CdcSink interface for custom sinks) through a durable outbox — ordered per pipe, at-least-once from enqueue, retried with backoff, dead-lettered.",
       "pkg": "@voltro/plugin-cdc-out",
       "doc": "plugins/cdc-out.md",
       "module": "agent-docs/plugins/cdc-out.md"

package/templates/agent-docs/ai.md

@@ -116,7 +116,7 @@ Env vars `providerFromEnv()` reads:
 | `AI_PROVIDER` | `mock` | `mock` \| `anthropic` \| `openai` \| `gateway`. |
 | `AI_MODEL` | per provider (see below) | Override the model. Defaults: `claude-opus-4-8` (anthropic), `gpt-5.5` (openai), `mock` (mock). **REQUIRED for `gateway`** — a `creator/model` id; boot throws if unset. |
 
-Provider API keys are read by the underlying `@ai-sdk/*` packages from their standard env vars — `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `AI_GATEWAY_API_KEY`. The framework doesn't read a separate `AI_API_KEY`. (To give a SINGLE agent its own key from code instead of env, see [Per-config key + base URL](#per-config-key--base-url) below.)
+Provider API keys are read by the underlying `@ai-sdk/*` packages from their standard env vars — `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `AI_GATEWAY_API_KEY`. The framework doesn't read a separate `AI_API_KEY`. (To give a SINGLE agent its own key from code instead of env, see [Per-config key + base URL](#per-config-key-base-url) below.)
 
 ## Anthropic
 
@@ -141,7 +141,7 @@ AI_MODEL=gpt-5.5
 OPENAI_API_KEY=sk-…
 ```
 
-Backed by `@ai-sdk/openai`. `AI_MODEL` is a plain OpenAI model id (`gpt-5.5`, `gpt-4o-mini`, …). For a self-hosted / Azure-style / proxy endpoint, set `baseURL` on a `ProviderConfig` (see [Per-config key + base URL](#per-config-key--base-url)) rather than an env var.
+Backed by `@ai-sdk/openai`. `AI_MODEL` is a plain OpenAI model id (`gpt-5.5`, `gpt-4o-mini`, …). For a self-hosted / Azure-style / proxy endpoint, set `baseURL` on a `ProviderConfig` (see [Per-config key + base URL](#per-config-key-base-url)) rather than an env var.
 
 ## Vercel AI Gateway
 
@@ -239,7 +239,7 @@ export default (input: { prompt: string }) =>
   })
 ```
 
-`GenerateTextOptions` is `{ prompt, system?, provider?, fallbacks?, maxTokens? }`. There is no `messages`/`effort` shape — the prompt is a single string the SDK wraps as the user turn; `system` steers it. `fallbacks` is a [provider fallback chain](#fallback-chain--survive-a-provider-outage).
+`GenerateTextOptions` is `{ prompt, system?, provider?, fallbacks?, maxTokens? }`. There is no `messages`/`effort` shape — the prompt is a single string the SDK wraps as the user turn; `system` steers it. `fallbacks` is a [provider fallback chain](#fallback-chain-survive-a-provider-outage).
 
 Structured output:
 
@@ -276,7 +276,7 @@ type ProviderConfig =
   | { name: 'gateway';   model: `${string}/${string}`; apiKey?: string; baseURL?: string }  // creator/model
 ```
 
-The mock-only `mockText` / `script` can't appear on a real provider (the type rejects it), the gateway's `model` is a `creator/model`-typed string (a bare `'gpt-5.5'` is a compile error, not a boot crash), and the per-provider model-id types (`AnthropicModel` / `OpenAIModel`) are **open unions** — known ids autocomplete, but any string the provider ships tomorrow still type-checks. Use `provider` for per-request model selection (e.g. a cheaper model on a fallback path), or to pin a specific key/endpoint (see [Per-config key + base URL](#per-config-key--base-url)).
+The mock-only `mockText` / `script` can't appear on a real provider (the type rejects it), the gateway's `model` is a `creator/model`-typed string (a bare `'gpt-5.5'` is a compile error, not a boot crash), and the per-provider model-id types (`AnthropicModel` / `OpenAIModel`) are **open unions** — known ids autocomplete, but any string the provider ships tomorrow still type-checks. Use `provider` for per-request model selection (e.g. a cheaper model on a fallback path), or to pin a specific key/endpoint (see [Per-config key + base URL](#per-config-key-base-url)).
 
 For runtime provider switching across a whole layer, bind an `AiServiceImpl` to the `AiService` Context tag at boot and read it with `yield* AiService` — `defaultAiService` (backed by `providerFromEnv`) is the default.
 

package/templates/agent-docs/authentication.md

@@ -2602,6 +2602,78 @@ A membership that ends mid-subscription therefore stops serving rows — the
 caller's open ticket list drops the rows they can no longer see, without a
 refresh and without the subscription having to be torn down.
 
+**On every transport, and that list is complete: the WebSocket, an [SSE
+stream](/docs/data/rest-routes#live-updates-over-http-stream-sse), and a
+[gRPC](/docs/data/grpc) server-streaming rpc.** All three open their
+subscription through the same code and resolve the filter per delivery, so
+"stays open for hours" never becomes a way to hold a stale predicate. The same
+delivery also re-checks the query's `guards:`; a filter resolution that FAILS
+revokes the subscription on all three rather than falling back to an unfiltered
+or empty read.
+
+## Declare which tables it narrows — `tables:`
+
+Optional, one line, and it buys back a feature the filter otherwise switches
+off for the whole app:
+
+```ts
+setRowFilter({
+  load,
+  predicate,
+  tables: ['bookmarks', 'recentSearches', 'todoSchedules', 'todoTags'],
+})
+```
+
+**What it buys.** [Delta-resume](/docs/data/wire-protocol#reconnect-delta-resume)
+is excluded for a subscription whose row set is re-resolved per delivery —
+replaying deltas could serve rows the subject has since lost. Without a
+declaration the framework cannot tell which tables your predicate may reach, so
+it excludes them all: one registration disables cheap reconnects for every
+subscription in the process. A deployment measured a filter over 4 tables
+costing it on all 173 of their query descriptors, 55 of whose source tables the
+filter never touches. With the declaration, only subscriptions on the listed
+tables are excluded.
+
+**Why a declaration and not a probe.** Resolving the scope at subscribe time
+and treating "returns `undefined` for this table" as safe is cheaper and
+unsound: your predicate is a function of freshly loaded context, so a table it
+does not narrow now may be narrowed on the next delivery — which is the entire
+reason the filter is re-resolved per delivery. A static list is a promise about
+every future resolution.
+
+**It is verified, not trusted.** Returning a predicate for a table outside the
+list raises `RowFilterDeclarationViolated` at the read that did it — the
+request fails and a subscription is revoked. A declaration nobody checks is a
+comment, and this one is load-bearing: the resume grant is issued on its
+strength. Omit `tables:` entirely and nothing is verified and nothing resumes —
+the conservative default.
+
+## Eager loads are refused, not silently unfiltered
+
+A relation pulled in with `.with(...)` is resolved **below** the seam that
+applies the filter: the stores expand the eager tree themselves (the memory
+store recurses through its own raw read; the SQL stores fold the relation into
+one join). So a filtered table reached through a relation would come back
+unfiltered.
+
+Rather than serve those rows, the read **refuses**, naming the table and both
+ways out:
+
+```
+row filter: 'readers' is reached through an eager load on 'notes', and an eager
+relation is resolved BELOW the row filter — its rows would come back
+unfiltered. Refusing the read rather than serving it.
+  → read 'readers' as its own query (it is filtered there), or
+  → drop 'readers' from this .with(...) if the relation does not need
+    row-level narrowing.
+```
+
+Only relations reaching a table your filter actually narrows are affected —
+every other eager load is untouched. Applying the filter inside eager
+compilation is the real fix and it is a per-dialect change; until then this is
+a refusal rather than a leak, for the same reason the module refuses to
+fail open.
+
 ## Row filters vs. guards
 
 They answer different questions, and a complete policy usually wants both:

package/templates/agent-docs/cli.md

@@ -32,6 +32,7 @@ The dispatcher routes `voltro <command> [args]` to the matching subcommand and p
 | Integrate | [`webhooks`](/docs/plugins/webhooks#voltro-webhooks-consumer-the-package-your-subscribers-install) (`consumer` / `events`) — generate the ZERO-dependency Standard-Webhooks verification package your subscribers install, from your own declared events (`--out` / `--name`); list the events a subscriber can register for (`--json`) |
 | [Inspect & debug](/docs/cli/inspect) | `inspect`, `logs`, `traces`, `workflows`, `cluster`, `check` |
 | [Health & surface](/docs/cli/build-and-start) | [`doctor`](/docs/cli/build-and-start) — serve preflight + the hand-roll detector (names the shipped primitive at the spot you're rebuilding it); [`capabilities`](/docs/cli/build-and-start) (`--json`) — the export surface read from your installed `@voltro/*`, so it can be verified instead of recalled; `info` (`--json`) — CLI / node / package-manager / dialect + every installed `@voltro/*` version, flagging lockstep skew (exits 1 on skew) |
+| Mobile | `mobile` (`codegen` / `links`) — the Expo app's build-time steps: the typed rpc client + deep-link table, and the `apple-app-site-association` / `assetlinks.json` a universal link needs. `voltro codegen` inside a mobile app runs the same generators. |
 | Harness | `test`, `e2e` |
 | Cloud | `cloud` (`login` / `whoami` / `projects` / `env` / `import`); `login` is a top-level alias of `cloud login` |
 | Secrets | `secret` (`generate [purpose]` — the right var+format per secret; `generate` alone → a generic secret; `list`) |
@@ -143,6 +144,8 @@ config value always winning:
 | `VOLTRO_HSTS` | `Strict-Transport-Security` value. `off` drops just this one. |
 | `VOLTRO_MAX_RPC_BODY_BYTES` | Cap on the buffered `POST /rpc` JSON body (default 8 MiB) — an oversized body is refused `413` and never buffered past the cap. File uploads ride plugin routes with their own limits. |
 | `VOLTRO_MAX_BODY_BYTES` | Cap on every OTHER body read — plugin HTTP routes, REST routes, incoming webhooks (default 8 MiB, matching the rpc cap). The config-file spelling is `http.maxBodyBytes` in `app.config.ts`; per-route overrides (`defineRestRoute({ maxBodyBytes })`, a webhook handler's `maxBodyBytes`) win over both. Oversize is `413` for `Content-Length` and chunked alike. |
+| `VOLTRO_CRDT_COMPACT_MAX_BYTES` | Size above which a merged `crdtText()` / `crdtDoc()` blob is soft-compacted (default 512 KiB, `0` disables). The config-file spelling is `crdt.compactMaxBytes` in `app.config.ts`; this variable wins over it. See [local-first](/docs/local-first/overview#rich-text-crdtdoc-usecrdtdoc-usecrdteditor). |
+| `VOLTRO_GRPC_DRAIN_MS` | How long the [gRPC surface](/docs/data/grpc) lets open calls finish on shutdown before force-closing them (default 5000, `0` forces immediately). The config-file spelling is `grpc.drainMs`; this variable wins over it. Keep it below your orchestrator's termination grace. |
 
 Response compression for the buffered non-rpc surfaces (and `voltro start`'s
 HTML) is configured in the same `http:` block — `http.compression.{enabled,minBytes}`
@@ -2031,7 +2034,7 @@ package's README.
 
 _voltro migrate — apply the declared schema through the declarative differ (an alias of voltro db apply)._
 
-`voltro migrate` applies your declared schema (`*.entity.ts` / `*.schema.ts` / `schema.ts`) to the configured database. It is an **alias of [`voltro db apply`](#the-declarative-workflow)**: it diffs the declared schema against the live database and emits the ALTERs, so a changed column or a new index actually lands.
+`voltro migrate` applies your declared schema (`*.entity.ts` / `*.schema.ts` / `schema.ts`) to the configured database. It is an **alias of [`voltro db apply`](#the-declarative-diff-workflow-voltro-db)**: it diffs the declared schema against the live database and emits the ALTERs, so a changed column or a new index actually lands.
 
 > Before 0.11.4 this command was a create-only apply (`CREATE TABLE IF NOT EXISTS`, no diffing), which meant a column or type change reported success having applied **nothing**. If you need that bootstrap-only behaviour for a brand-new database, it is now `voltro migrate --create-only`.
 

package/templates/agent-docs/data.md

@@ -1717,7 +1717,7 @@ created by every migration and diffed on every boot.
 
 The other tempting option is to point `source:` at a name that resolves to
 nothing. That is worse than the empty table: the [stale-`source` boot
-warning](#fan-out--how-many-subscribers-may-one-change-wake) is the only signal
+warning](#fan-out-how-many-subscribers-may-one-change-wake) is the only signal
 for a subscription that has gone permanently quiet, and an exemption for a name
 you invented disables it for the one case it was built for.
 
@@ -1847,7 +1847,7 @@ Two consequences worth knowing:
 - **Not free per subscriber.** A publish wakes every subscriber of that channel
   and re-runs each one's executor; the channel is one routing key, so
   subscribers looking at different slices of the state are woken too. Publish on
-  a real change, not on a timer — see [Fan-out](#fan-out--how-many-subscribers-may-one-change-wake).
+  a real change, not on a timer — see [Fan-out](#fan-out-how-many-subscribers-may-one-change-wake).
 
 ## Query Executor
 
@@ -2067,7 +2067,7 @@ materialised revision and the stream continues on the same revision line, so a
 short offline gap costs a handful of patches instead of every row. Outside the
 window, for computed queries, for row-filtered apps, or whenever anything is in
 doubt, the query answers with a fresh snapshot — the delta-resume wire contract
-lives in [the wire protocol](/docs/data/wire-protocol#reconnect--delta-resume).
+lives in [the wire protocol](/docs/data/wire-protocol#reconnect-delta-resume).
 
 **What is on screen while that happens is your last-known-good data, not a
 skeleton.** The replacement cache is seeded from the one it retires, so `data`
@@ -2172,6 +2172,15 @@ subscriber on every delivery, on purpose — a role revoked or a share withdrawn
 to end the stream on the very NEXT delivery, not whenever a cache happens to
 expire — and each of them can be a database round-trip.
 
+**On every transport.** A live query can leave the server three ways — the
+WebSocket the browser client uses, an [SSE
+stream](/docs/data/rest-routes#live-updates-over-http-stream-sse), and a
+[gRPC](/docs/data/grpc) server-streaming rpc — and all three resolve per
+delivery through the same code: guards re-checked before each frame, row
+visibility re-derived from the unfiltered base descriptor for each frame, and a
+revoked scope ending the stream. The transport decides how the frame is
+framed, never what the subject may see.
+
 So deliveries run **concurrently, up to a bound**. The default is 8 in flight.
 Measured with 50 subscribers behind a 5 ms guard: 517 ms to serve all of them
 serially, 72 ms at 8 lanes.
@@ -3205,7 +3214,9 @@ es.addEventListener('delta',    (e) => applyDelta(JSON.parse(e.data)))
 
 Each event's `_tag` becomes the SSE `event:` name, so a client listens per kind instead of switching on a payload field. The framing handles the details that bite otherwise: embedded newlines are split across `data:` lines (a raw `\n` would truncate the event), a `retry:` hint is sent, and a keep-alive comment goes out every 15s so proxies don't drop an idle stream.
 
-Same guarantees as the WebSocket path, because it is the same code: the declarative `guards:`, the row filter and tenant scoping all run before anything is emitted, and the client's disconnect tears the subscription down (including a disconnect *during* setup). A guard denial arrives as one `error` event rather than an HTTP status — by then the response headers are already sent.
+Same guarantees as the WebSocket path, because it is the same code: the declarative `guards:`, the [row filter](/docs/authentication/row-level-security) and tenant scoping all run before anything is emitted, and the client's disconnect tears the subscription down (including a disconnect *during* setup). A guard denial arrives as one `error` event rather than an HTTP status — by then the response headers are already sent.
+
+And they run before **every** event, not only before the first one: the guards are re-checked and the subject's row visibility is re-resolved from the unfiltered base descriptor per delivery, so a scope revoked while the `EventSource` is open ends the stream on the next event, and a membership that ends stops carrying those rows in the next `delta`. An open SSE stream is not a cheaper read path than a fresh `GET`.
 
 `stream: 'sse'` on a mutation or action is ignored: there is nothing to subscribe to.
 
@@ -4999,10 +5010,22 @@ A resume is declined — always with a fresh snapshot — when:
 - the resuming caller is a different subject or tenant (a login, logout or
   tenant switch between disconnect and resume) — the retained history is keyed
   by subject AND tenant, so a changed identity simply never finds it;
-- the app registers a row filter (`setRowFilter`), or the query is a
-  **computed** query — both are excluded from resume by design: a row-filtered
-  subscription's visible row set exists only per delivery, and a computed query
-  re-runs a handler with no delta chain to replay. They reconnect with a fresh
+- the query is a **computed** query — it re-runs a handler, so there is no
+  delta chain to replay;
+- a registered row filter (`setRowFilter`) can narrow THIS subscription's
+  source table, or the query declares an eager `.with(...)`. A row-filtered
+  subscription's visible row set exists only per delivery, so replaying it
+  could serve rows the subject has since lost.
+
+  **This is per table, not per app.** A filter that declares
+  `tables: [...]` (see [row-level security](/docs/authentication/row-level-security))
+  keeps delta-resume on every subscription whose source is not in that set —
+  the common case, since most filters narrow a handful of tables. Without the
+  declaration the framework cannot know which tables the predicate may reach
+  and excludes them all, which is what a deployment measured as one filter over
+  4 tables costing the feature on all 173 of their queries. Eager loads are
+  excluded wholesale because a relation resolves below the seam that narrows.
+  They reconnect with a fresh
   snapshot, exactly as before.
 
 **Author a live-subscribed getter to return, not throw.** A subscription is a
@@ -6101,6 +6124,8 @@ export default {
     port: 50051,
     procedures: ['orders.get', 'orders.list', 'orders.create'],
     // tls: { certPath, keyPath, caPath? } — plaintext without it (dev / mesh).
+    // drainMs: 5000,        // shutdown drain budget — see below
+    // maxMessageBytes, maxMetadataBytes — grpc-js frame limits
   },
 }
 ```
@@ -6112,6 +6137,21 @@ works out of the box). The gRPC packages ship as script-free optional
 dependencies of `@voltro/cli`; a configured `grpc:` block with them missing
 refuses the boot by name.
 
+## Shutdown drains, then forces — `drainMs`
+
+On SIGTERM the surface flips its health status to `NOT_SERVING` (so a load
+balancer stops sending it work) and gives open calls **`drainMs`** to finish
+before force-closing them. Default `5000`; `0` forces immediately; the env
+override is `VOLTRO_GRPC_DRAIN_MS`.
+
+Pick it from two numbers only you have. Keep it **below** your orchestrator's
+termination grace (`terminationGracePeriodSeconds`, `docker stop -t`) — past
+that point SIGKILL arrives and the drain never completes, so a larger budget
+buys nothing. Keep it **above** your longest legitimately in-flight unary
+call, or every rolling deploy force-closes work that would have finished. When
+the budget is exceeded the surface says so in a warning naming the budget,
+rather than leaking the port into the next boot.
+
 ## Field numbers are managed — `grpc.manifest.json`
 
 Field numbers are the proto wire identity, so they may never depend on
@@ -6169,10 +6209,19 @@ sleeping action whose post-sleep write never lands).
 A `query` becomes a **server-streaming** rpc: each frame is the CURRENT full
 snapshot, re-pushed live when the query's `source:` changes — subscribe,
 mutate from anywhere, and the open stream receives the new frame with no
-re-request. The per-delivery guard re-check applies (a revoked scope ends
-the stream with the mapped status), and slow consumers are handled through
-grpc-js write backpressure — frames coalesce to the latest snapshot rather
-than buffering unboundedly.
+re-request.
+
+**Authorization is re-derived per FRAME, not frozen at open.** Before every
+delivery the framework re-runs the query's `guards:` and re-resolves the
+subject's [row-level visibility](/docs/authentication/row-level-security)
+from the unfiltered base descriptor. A revoked scope ends the stream with the
+mapped status; a membership that ends mid-stream stops carrying those rows in
+the next frame, with the stream itself untouched. This is the same code the
+WebSocket and SSE transports run — an open gRPC stream is not a cheaper read
+path than a fresh call.
+
+Slow consumers are handled through grpc-js write backpressure — frames
+coalesce to the latest snapshot rather than buffering unboundedly.
 
 ## Declared limits (v1)
 

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

@@ -627,7 +627,7 @@ await ctx.store.update('notes', id, {
 
 Two layers of validation apply:
 
-1. **JSON validity** — that the stored bytes are well-formed JSON — is enforced automatically by the database on every dialect (see [Storage + validation per dialect](#storage--validation-per-dialect)). You don't declare anything.
+1. **JSON validity** — that the stored bytes are well-formed JSON — is enforced automatically by the database on every dialect (see [Storage + validation per dialect](#storage-validation-per-dialect)). You don't declare anything.
 2. **JSON *shape*** — that the value matches your expected structure — is up to you: enforce it at the table level with `table().validate(Schema)`:
 
 ```ts

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

@@ -700,7 +700,7 @@ A handler that a `voltro dev` session or a test actually ran is reported with wh
 
 ### What the codemod does per kind
 
-- **`rename-column`** gets a real `transform`: it renames the field in the `*.entity.ts` AND chains **`.renamedFrom('old')`** (so the differ plans a catalog RENAME, not the lossy drop+create described [above](#renamedfromoldname)), then annotates the handler sites the blast radius found.
+- **`rename-column`** gets a real `transform`: it renames the field in the `*.entity.ts` AND chains **`.renamedFrom('old')`** (so the differ plans a catalog RENAME, not the lossy drop+create described [above](#renamedfrom-oldname)), then annotates the handler sites the blast radius found.
 - **`retype-column` / `split-column` / `drop-column` / `rename-table`** are reshaping changes with no single mechanical rewrite, so they get a **`manual`** codemod: a generated, numbered checklist of the edits + the annotation to add, printed for you to apply.
 
 `voltro evolve` produces the plan; it does not apply the schema change. **`voltro check` is the gate on the result**, and `voltro db apply` lands it — after `--write`, review the annotated handlers, then run those two.

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

@@ -391,7 +391,7 @@ What the framework hides for you vs what's worth knowing. Per-dialect pages dril
 | `RETURNING *` on DELETE                   | yes             | no              | yes (10.0+)     | OUTPUT DELETED.* | yes | yes |
 | Parameterized `LIMIT ?`                   | yes             | no — integer-literal inlined | yes | no — integer-literal inlined | yes | yes |
 | `LIMIT N OFFSET N` syntax                 | yes             | yes             | yes             | no — `OFFSET … ROWS FETCH NEXT … ROWS ONLY` | yes | yes |
-| DEFAULT on TEXT columns                   | yes             | **NO** — auto-uses VARCHAR(255) | yes | yes (NVARCHAR(MAX)) | yes | yes |
+| DEFAULT on TEXT columns                   | yes             | **NO** — framework emits VARCHAR(255) | yes — framework still emits VARCHAR(255) (engine parity) | yes — framework emits NVARCHAR(450) (indexable) | yes | yes |
 | Native JSON column type                   | JSONB           | JSON            | JSON            | NVARCHAR(MAX)    | TEXT                | TEXT               |
 | JSON columns returned as objects          | yes             | yes             | yes             | **no — strings** — framework auto-parses | **no — strings** — framework auto-parses | **no — strings** — framework auto-parses |
 | Booleans                                  | proper booleans | 0/1 (TINYINT)   | 0/1             | BIT (proper bool) | 0/1 (INTEGER)     | 0/1 (INTEGER)      |
@@ -796,11 +796,48 @@ The framework's DDL emitter detects the case and switches to `VARCHAR(255)`:
 ```typescript
 text().default('json')                     // → VARCHAR(255) DEFAULT 'json'
 text().oneOf(['a', 'b', 'c']).default('a') // → VARCHAR(255) DEFAULT 'a' CHECK (col IN ('a','b','c'))
-text().nullable()                          // → TEXT (unchanged — no default to trip up)
+text().nullable()                          // → LONGTEXT (unchanged — no default to trip up)
 ```
 
 VARCHAR(255) is the framework's heuristic — enough for typical enum-like values, short status strings, format identifiers. If you need longer defaulted text, declare the column as `text().nullable()` + handle the missing-default case in application code, OR drop down to `unsafe()`.
 
+### Adding a default to an existing column
+
+The rule holds for a migration too, not only for `CREATE TABLE`. Adding
+`.default(…)` to a `text()` column that already exists **reshapes** the column
+rather than setting a default on it:
+
+```sql
+ALTER TABLE tickets MODIFY COLUMN `status` VARCHAR(255) NOT NULL DEFAULT 'active'
+```
+
+That is deliberate, and it is what makes the change appliable at all: a plain
+`ALTER TABLE … ALTER COLUMN status SET DEFAULT 'active'` is answered by MySQL
+with `BLOB, TEXT, GEOMETRY or JSON column 'status' can't have a default value`,
+so the migration would stop half-applied. Reshaping means the column has the same
+type whether the default was declared before or after the table existed.
+
+Two consequences worth knowing before you run it:
+
+- **It is a narrowing.** If a row already holds more than 255 characters, the
+  ALTER fails (`Data too long for column 'status'`) and the migration stops
+  before it. Check first, and pick the width yourself with
+  `text().maxLength(n).default(…)` if 255 is too small:
+
+  ```sql
+  SELECT COUNT(*) FROM tickets WHERE CHAR_LENGTH(status) > 255
+  ```
+
+- **Removing a default does not reshape back.** `DROP DEFAULT` is legal on any
+  mysql type, and widening a `VARCHAR(255)` back to `LONGTEXT` would fail for an
+  indexed column — so the column keeps its bounded type. Declare
+  `text().maxLength(255)` if you want that to be visible in the schema.
+
+SQL Server does the same thing for its own reason (an `NVARCHAR(MAX)` column
+cannot be indexed, so a defaulted text column is `NVARCHAR(450)`). On postgres a
+`TEXT` column takes a `DEFAULT` directly, and SQLite rebuilds the table to the
+declared shape — neither reshapes anything.
+
 ## JSON columns
 
 `json()` columns emit `JSON` (mysql's native binary JSON type since 5.7+). The driver auto-parses on read; same shape as postgres. No coercion overhead.
@@ -1187,6 +1224,31 @@ When the caller didn't supply an `orderBy` but did set `skip` (uncommon but lega
 
 The compiler inlines integer literals for TOP/OFFSET/FETCH NEXT values rather than parameter binding. Same rationale as MySQL — tedious has bind-as-INT issues with large or unexpected-typed numeric params.
 
+## Text columns with a DEFAULT — NVARCHAR(450)
+
+A plain `text()` column is `NVARCHAR(MAX)`, which SQL Server cannot index. A text
+column that carries a literal default or a closed value set is therefore emitted
+bounded, at `NVARCHAR(450)` — under the 900-byte single-column key limit, so it
+stays indexable:
+
+```typescript
+text().default('open')                 // → NVARCHAR(450) + a DEFAULT constraint
+text().oneOf(['open', 'closed'])       // → NVARCHAR(450) + a CHECK constraint
+text().nullable()                      // → NVARCHAR(MAX)
+```
+
+This holds for migrations as well as for `CREATE TABLE`: adding `.default(…)` to
+an existing text column retypes it to `NVARCHAR(450)` and then adds the default
+constraint, so the column has the same type whether the default was declared
+before or after the table existed. It is a narrowing — if a row already holds
+more than 450 characters, the `ALTER COLUMN` fails ("String or binary data would
+be truncated") and the migration stops there. Check first, and use
+`text().maxLength(n).default(…)` to choose a different width:
+
+```sql
+SELECT COUNT(*) FROM tickets WHERE LEN(status) > 450
+```
+
 ## JSON columns — NVARCHAR(MAX) + auto-parse
 
 `json()` columns emit `NVARCHAR(MAX)` in DDL — mssql has no native JSON type pre-2025. Validation goes through `ISJSON(col) = 1` CHECK constraints; serialization is application-side.

package/templates/agent-docs/internationalization.md

@@ -78,6 +78,8 @@ Server-side, the active locale is determined by, in priority order:
 2. **`Accept-Language` header** — the browser/OS preference, q-weighted and sorted per RFC 4647.
 3. **`defaultLocale`** — last-resort fallback.
 
+**One resolver decides, and everything the server renders for that request reads its answer** — the page render and its `<I18nProvider>`, the `<html lang>` attribute, the ISR cache key (so a language switch cannot re-serve the previous locale's cached HTML), and the validation errors an [`<AutoForm>` renders on the no-JavaScript form-POST path](/docs/ui/forms-and-tables#forms-without-javascript). That last one is worth naming because a server has no `<html lang>` to read yet at the time it validates; deriving the locale a second way there would answer `en` for every request.
+
 The resolved locale is **guaranteed** to be one of the codes in `locales`. Any unsupported value (a cookie pointing at a code you no longer ship, a browser asking for `xx-YY`) falls through to the next signal. RFC 4647 lookup strips subtags one segment at a time — `de-CH-1996` → `de-CH` → `de` — so a `de` catalog serves a `de-CH` browser.
 
 The client **adopts what the server resolved**, reading it from the `<html lang>` attribute the server render sets, then falling back to the cookie and the default. `Accept-Language` is never read in the browser: `navigator.languages` can diverge from what the server saw.