@voltro/cli 0.53.0 → 0.55.0

package/dist/{webhooksCommand-4SVPDjKg.js → webhooksCommand-B1LVcyO3.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-DfVZaoys.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.55.0",
   "description": "The `voltro` CLI — dev server, codegen, migrations, project scaffolding, agent-docs seeding, and production serve.",
   "keywords": [
     "voltro",
@@ -754,6 +754,18 @@
         "title": "WidgetKind gained 'array' and 'reference' — total widget registries need two new entries",
         "kind": "manual"
       },
+      {
+        "version": "0.55.0",
+        "id": "0.55.0/01_target-relations-declare-columns",
+        "title": "A target's `relations:` names the junction's two columns now, not just the table",
+        "kind": "manual"
+      },
+      {
+        "version": "0.55.0",
+        "id": "0.55.0/02_widget-kind-gained-rich-text",
+        "title": "WidgetKind gained 'rich-text' — total widget registries need one new entry",
+        "kind": "manual"
+      },
       {
         "version": "0.6.0",
         "id": "0.6.0/01_no-dev-session-secret",
@@ -836,24 +848,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.55.0",
+    "@voltro/cache": "0.55.0",
+    "@voltro/client": "0.55.0",
+    "@voltro/content": "0.55.0",
+    "@voltro/data-transfer": "0.55.0",
+    "@voltro/database": "0.55.0",
+    "@voltro/env": "0.55.0",
+    "@voltro/kv": "0.55.0",
+    "@voltro/logger": "0.55.0",
+    "@voltro/plugin-auth": "0.55.0",
+    "@voltro/plugin-broadcast": "0.55.0",
+    "@voltro/plugin-mail": "0.55.0",
+    "@voltro/plugin-storage": "0.55.0",
+    "@voltro/plugin-webhooks": "0.55.0",
+    "@voltro/protocol": "0.55.0",
+    "@voltro/runtime": "0.55.0",
+    "@voltro/serverless": "0.55.0",
+    "@voltro/workflow": "0.55.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.55.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.55.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,121 @@ 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
+const OWNED = new Set(['documents', 'comments'])
+
+setRowFilter({
+  load,
+  predicate: (ctx, table) => (OWNED.has(table) ? eq('ownerId', ctx.userId) : undefined),
+  // Derived from the same set the predicate reads. Two hand-kept lists is the
+  // shape in which a table lands in exactly one of them.
+  tables: [...OWNED],
+})
+```
+
+**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, including every one reading a table your predicate
+never returns anything for. With the declaration, only subscriptions on the
+listed tables are excluded.
+
+**What it does not buy, and this bounds the whole feature.** A subscription only
+has a delta chain when its executor returns a **descriptor**. One that returns a
+mapped value or a page envelope —
+
+```ts
+export default async ({ database }) => {
+  const rows = await database.notifications.where(...)
+  return { notifications: rows.map(toDto), hasMore: rows.length === 20 }
+}
+```
+
+— re-runs an opaque handler and emits snapshots, with or without a filter. So
+the count `tables:` gives back is the count of descriptor-returning
+subscriptions, not the number of queries in your app. Declare it anyway (it
+costs nothing, and it applies the moment such a query returns the builder), but
+measure before expecting a change.
+
+**How to see which of yours are which.** The two shapes are indistinguishable
+from the outside — a subscription that resumed and one that was never eligible
+both reconnect with rows on the screen. So the runtime records its own verdict
+at the moment it decides, per query label:
+
+```sh
+curl -s localhost:4000/_voltro/inspect/subscriptions | jq .resume
+```
+
+```json
+[
+  { "label": "documents.list", "resumable": 12, "excluded": {} },
+  { "label": "notifications.list", "resumable": 0, "excluded": { "computed": 8 } },
+  { "label": "comments.list", "resumable": 0, "excluded": { "row-filter": 3 } }
+]
+```
+
+A label appears once something has subscribed to it, so click through the app
+first. `computed` means no declaration can ever help that query; `row-filter`
+means the filter narrows its source and the exclusion is the point;
+`eager-load` means dropping the `.with(...)` would flip it. `voltro dev` also
+logs each verdict once per label under the `voltro:resume` scope.
+
+**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`.
 
@@ -2966,17 +2969,67 @@ the swap could not run: 2 row(s) in the bundle reference a row the bundle does n
   The target is UNCHANGED — the swap runs in one transaction and none of it committed.
 ```
 
-Staging tables from a run that died mid-load are collected by the next
-`replace` over the same tables. One over a DIFFERENT set leaves them, and
-nothing else removes them:
+### Staging tables a dead run left behind
+
+A staged run RECORDS the scratch tables it creates, in the same
+`_voltro_replace_in_progress` table an interrupted destructive `replace` writes
+to — with one difference that matters: **a staging record never refuses a boot.**
+Nothing was destroyed, so there is nothing to refuse over. The boot reports
+instead:
+
+```
+staged data-import leftovers:
+  - 3 staging table(s) from a `replace` over api, last active 74 minute(s) ago — DROPPED: the run
+    is not resumable and has been silent long enough that nothing is loading into them.
+  The target of a staged `replace` is untouched until one short swap at the end, so none of this is
+  a reason to refuse the boot — it is a reason to know the disk is holding a copy of a bundle.
+```
+
+The run refreshes a heartbeat on that record every couple of seconds while rows
+land, which is what lets a boot tell the three cases apart:
+
+| what the record says | what the boot does |
+|---|---|
+| silent past the threshold, started without `--no-atomic` | **drops** the tables it names |
+| still beating | leaves them — an import is loading into them right now, here or on another replica |
+| started `--no-atomic` | leaves them — its staging IS the resume point |
+
+The threshold is `30` minutes by default. It is deliberately generous: the cost
+of collecting too early is that an in-flight import's swap fails with a missing
+table and you re-run it — the target is untouched either way — but the cost is
+still a re-run.
+
+Declare a different one for a deployment whose imports routinely pause longer
+than that, waiting on an upstream export or a maintenance window:
+
+```ts
+// app.config.ts
+export default {
+  dataTransfer: {
+    stagingStaleMinutes: 90,
+  },
+}
+```
+
+`VOLTRO_STAGING_STALE_MINUTES` overrides the declaration in turn — an operator
+acting on a running deployment outranks what the project declared. Note that the
+threshold decides only what a boot DROPS: leftover staging tables are named in
+the boot log either way.
+
+What the boot does NOT collect, you can:
 
 ```bash
 voltro data clear-staging --yes
 ```
 
-Deliberately a command and not a boot sweep: a booting process cannot tell a
-leftover from a staging table another replica is loading into right now, and
-deleting the second would destroy an import in flight.
+It now labels each table with what its own run says, so a resume point is
+distinguishable from a leftover before you drop it:
+
+```
+2 staging table(s) from an earlier `--mode replace`:
+    _voltro_staging_tasks — RESUMABLE: a `--no-atomic` re-run continues from it, last active 4 min ago
+    _voltro_staging_notes — no run claims it (an orphan, or from before the marker)
+```
 
 A **cycle** in the bundle's foreign keys is detected before the load, not after
 it. The swap inserts parents first, so two tables referencing each other cannot
@@ -3559,7 +3612,14 @@ A native run reports **blobs**, not rows: the vendor tool reports no row count w
 
 ### The provenance stamp — a restore that refuses the wrong DB
 
-A native dump is opaque: it doesn't say which dialect made it, which schema shape it carries, or when. `backup` writes a sidecar `voltro-backup-stamp.json` next to the artifact recording exactly that — `dialect`, the live schema `fingerprint`, the `@voltro/cli` version, and the timestamp.
+A native dump is opaque: it doesn't say which dialect made it, which schema shape it carries, or when. `backup` writes a sidecar `voltro-backup-stamp.json` next to the artifact recording exactly that — `dialect`, the `@voltro/cli` version, the timestamp, and **two** schema fingerprints.
+
+Two, because they are different facts and only one of them is a claim about the artifact:
+
+- **`schemaFingerprint`** — the source database's whole live schema at backup time. This is what the skew warning below compares against a target.
+- **`dumpFingerprint`** — the schema the **artifact carries**: that same snapshot minus the tables the dump excludes. On postgres and the mysql family those are `_voltro_replace_in_progress` and `_voltro_data_transfers` (see above); on sqlite, turso and mssql nothing is excluded and the two values are equal.
+
+The distinction is not bookkeeping. `voltro data backup` opens its own run row in `_voltro_data_transfers` *before* it dumps, so on any database the framework has run against, the artifact is two tables short of the live schema it was taken from. Anything comparing a restored schema against a stamped one has to compare against `dumpFingerprint` — the drill did not, and failed every healthy backup with *"the artifact is inconsistent."*
 
 `restore` reads the stamp **before touching the DB** and acts on two failures that are otherwise silent until they corrupt:
 
@@ -3575,13 +3635,39 @@ voltro data restore ./backups/2026-07-01 --drill --drill-url postgres://…/scra
 # or set DRILL_DB_URL and just: voltro data restore ./backups/2026-07-01 --drill
 ```
 
-`--drill` restores the artifact into a **throwaway** database (from `--drill-url` / `DRILL_DB_URL`) and verifies it — **without ever touching the live DB**. It refuses a drill target that resolves to your live connection (a drill that `--clean`s production is the disaster it exists to rehearse against). After the restore it introspects the throwaway DB and compares its schema fingerprint to the backup's stamp:
+`--drill` restores the artifact into a **throwaway** database (from `--drill-url` / `DRILL_DB_URL`) and verifies it — **without ever touching the live DB**. It refuses a drill target that resolves to your live connection (a drill that `--clean`s production is the disaster it exists to rehearse against). After the restore it introspects the throwaway DB and probes its migration ledger:
 
 - **zero tables restored** → FAIL (the dump is empty or unreadable — this backup would not recover you),
-- **fingerprint disagrees with the stamp** → FAIL (the restore didn't reproduce what was backed up),
-- **tables + matching fingerprint** → PASS.
+- **schema fingerprint disagrees with the stamp's `dumpFingerprint`** → FAIL (the restore didn't reproduce what was backed up),
+- **`_voltro_migration_plans` restored EMPTY** → FAIL (see below),
+- **tables + matching fingerprint + a populated or absent ledger** → PASS.
+
+A stamp too old to carry a `dumpFingerprint` gives a **PASS (partial)** that says the shape could not be cross-checked. It does not fall back to `schemaFingerprint`: that is the comparison that fails a healthy backup, and a check that is red on every real input gets switched off — taking its genuine failures with it.
+
+It exits non-zero on any FAIL, so a scheduled CI job turns a silently-broken backup into a red build. Run it against your latest artifact on a cron — a backup you've never restored is a hypothesis, and this is how you keep it a fact.
+
+#### The ledger check — the one thing a schema comparison cannot see
+
+A fingerprint answers *"is the shape right?"*. A drill's real question is *"would my app come up against this?"*, and the gap between them is **content** — a framework table that restored with the right columns and the wrong rows.
+
+`voltro serve`'s boot gate reads the newest row of `_voltro_migration_plans` and refuses with `prod-mismatch` when there is none. So a ledger table that restores with exactly the right columns and **zero rows** is a database no source tree can boot, and its schema fingerprint is identical to a healthy one's. The drill fails that, and names it:
+
+```
+FAIL — restored 30 table(s) with the right shape, but `_voltro_migration_plans`
+       came back EMPTY.
+       `voltro serve` reads the newest row of that table as its boot gate and
+       refuses with `prod-mismatch` when there is none.
+```
+
+A restored database with **no ledger table at all** is not a voltro-managed schema (a hand-made dump, someone else's database) — the drill says so and claims nothing about booting it, rather than failing it.
+
+What the drill deliberately does **not** judge is a ledger whose fingerprint differs from what your code declares. It has no way to know which commit you will deploy next to this database, and `voltro db apply` clears that state anyway; failing a backup for it would make the drill red for a reason that is not about the backup.
+
+#### Why there is no full app boot
+
+Booting a real app against the restored database sounds like the stronger check, and it would be a weaker one. There is no app in the drill's path — it would have to boot a **fixture**, and a fixture booting says nothing about whether *your* app boots. It moves the drill from *"proves your backup"* to *"proves our fixture"* while reading as the bigger claim.
 
-It exits non-zero on any FAIL, so a scheduled CI job turns a silently-broken backup into a red build. Run it against your latest artifact on a cron — a backup you've never restored is a hypothesis, and this is how you keep it a fact. (The verify is schema-level; a full app boot against the restored DB is a heavier check you can layer on top.)
+The part worth having does not need a process: the boot gate is a comparison, not a startup sequence, so the one boot-fatal condition that holds regardless of which code you deploy is reachable with a `SELECT`. That is the ledger check above.
 
 ### Point-in-time recovery (PITR) is your database's job, not the framework's