@voltro/cli 0.50.1 → 0.52.0

package/dist/webDev-CZbTsDcH.js

@@ -0,0 +1,2 @@
+import { b as e, v as t } from "./webDev-BgWL9gKV.js";
+export { t as tryRunWebServe, e as walkPagesTree };

package/dist/{webhooksCommand-DjE6u0r4.js → webhooksCommand-CoIO3jbj.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-Dz9GqA6P.js"), { outgoingFromEvents: r } = await import("./webhookDiscovery-il9ti-HE.js");
+	let { walk: t, loadDiscovered: n } = await import("./dev--A3nsxA3.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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltro/cli",
-  "version": "0.50.1",
+  "version": "0.52.0",
   "description": "The `voltro` CLI — dev server, codegen, migrations, project scaffolding, agent-docs seeding, and production serve.",
   "keywords": [
     "voltro",
@@ -700,6 +700,36 @@
         "title": "A COMPUTED `source:` can keep its typed names — do not widen the whole registry",
         "kind": "manual"
       },
+      {
+        "version": "0.51.0",
+        "id": "0.51.0/02_restore-refuses-without-marker",
+        "title": "`voltro data restore` refuses when it cannot write the in-progress marker",
+        "kind": "manual"
+      },
+      {
+        "version": "0.51.0",
+        "id": "0.51.0/03_restore-assets-returns-counts",
+        "title": "`restoreAssetsFromCas` returns `{ count, objects }`, not a number",
+        "kind": "manual"
+      },
+      {
+        "version": "0.51.0",
+        "id": "0.51.0/04_i18n-timezone-prop",
+        "title": "`<I18nProvider>`: `timeZone` is its own prop, not an `intlConfig` member",
+        "kind": "transform"
+      },
+      {
+        "version": "0.52.0",
+        "id": "0.52.0/01_plugin-versioning-to-row-history",
+        "title": "@voltro/plugin-versioning → @voltro/plugin-row-history (the name now says what it does)",
+        "kind": "transform"
+      },
+      {
+        "version": "0.52.0",
+        "id": "0.52.0/02_http-interceptor-fail-closed",
+        "title": "A throwing `onHttpRequest` interceptor now refuses the request (500) instead of being ignored",
+        "kind": "manual"
+      },
       {
         "version": "0.6.0",
         "id": "0.6.0/01_no-dev-session-secret",
@@ -775,22 +805,23 @@
     "@effect/platform-node": "^0.108.0",
     "@effect/sql": "^0.52.0",
     "@effect/workflow": "^0.19.0",
-    "@voltro/ai": "0.50.1",
-    "@voltro/cache": "0.50.1",
-    "@voltro/data-transfer": "0.50.1",
-    "@voltro/database": "0.50.1",
-    "@voltro/env": "0.50.1",
-    "@voltro/kv": "0.50.1",
-    "@voltro/logger": "0.50.1",
-    "@voltro/plugin-auth": "0.50.1",
-    "@voltro/plugin-broadcast": "0.50.1",
-    "@voltro/plugin-mail": "0.50.1",
-    "@voltro/plugin-storage": "0.50.1",
-    "@voltro/plugin-webhooks": "0.50.1",
-    "@voltro/protocol": "0.50.1",
-    "@voltro/runtime": "0.50.1",
-    "@voltro/serverless": "0.50.1",
-    "@voltro/workflow": "0.50.1",
+    "@voltro/ai": "0.52.0",
+    "@voltro/cache": "0.52.0",
+    "@voltro/client": "0.52.0",
+    "@voltro/data-transfer": "0.52.0",
+    "@voltro/database": "0.52.0",
+    "@voltro/env": "0.52.0",
+    "@voltro/kv": "0.52.0",
+    "@voltro/logger": "0.52.0",
+    "@voltro/plugin-auth": "0.52.0",
+    "@voltro/plugin-broadcast": "0.52.0",
+    "@voltro/plugin-mail": "0.52.0",
+    "@voltro/plugin-storage": "0.52.0",
+    "@voltro/plugin-webhooks": "0.52.0",
+    "@voltro/protocol": "0.52.0",
+    "@voltro/runtime": "0.52.0",
+    "@voltro/serverless": "0.52.0",
+    "@voltro/workflow": "0.52.0",
     "chokidar": "^5.0.0",
     "ioredis": "^5.11.1",
     "tinyglobby": "^0.2.17",

package/templates/AGENTS.core.md

@@ -404,11 +404,21 @@ Do NOT write `x.page.tsx`, `index.page.tsx` or `[id].page.tsx` — those were th
 **Every suffix above is a CONTRACT, not a label.** Something else depends on each
 promise, and `voltro doctor` enforces all of them:
 
-- `*.component.ui.tsx` may read (`useT`, `useCan`, `usePermissions`) but must
-  never import a write hook (`useMutation`, `useAction`, `useUpload`, …). That is
-  what lets a caller render it ten thousand times in a list, reuse it across
-  features, and prerender it without reading its source. Lift the write into the
-  owning `*.component.tsx` and pass a handler down.
+- `*.component.ui.tsx` may read (`useT`, `useTFn`, `useCan`, `usePermissions`,
+  the `@voltro/i18n` formatters) but must never import a write hook
+  (`useMutation`, `useAction`, `useUpload`, …). That is what lets a caller render
+  it ten thousand times in a list, reuse it across features, and prerender it
+  without reading its source. Lift the write into the owning `*.component.tsx`
+  and pass a handler down.
+
+  **Reading is a recommendation, not a grudging allowance — call the hook, do
+  not take a prop.** Threading `t` / `formatDate` / `useCan` through props is
+  prop-drilling: it grows the prop surface with every formatter, has to be
+  restated in every intermediate signature and every test, and does NOT make the
+  component more reusable — it makes every call site worse. The one argument for
+  the prop, "it renders without a provider", is already paid for the moment any
+  test mounts one. Pick one way per component head: a `t` prop beside a
+  formatter hook is the worst of both.
 - `*.internal.ts` is the promise that refactoring inside that directory breaks
   nobody. An import from another subtree revokes it.
 - `*.types.ts` having no runtime export is what makes importing it free and makes
@@ -686,6 +696,17 @@ primitive → just save; the supervised dev loop respawns and regenerates.
 - **Don't roll your own session token / ICU/i18n / job runner** — use
   `signSession`/`verifySession`, `@voltro/i18n`, `@effect/workflow`.
 - **Don't add `bullmq`/`temporal`/`react-query`/SWR** — see Mental model.
+- **Don't build a GraphQL layer over the stores.** It would bypass the
+  reactivity path (source-based invalidation, per-delivery guards) — a second,
+  dead read path. External consumers → REST + OpenAPI (`defineRestRoute` +
+  `@voltro/plugin-openapi`); internal clients → RPC + live subscriptions.
+- **Don't write `'use server'` / `'use client'` — there is no RSC.** Islands +
+  loaders + streaming SSR are the model; those directives mark a boundary this
+  framework does not have.
+- **Don't split the app into microservices with service-to-service RPC.** One
+  monolith process, scaled by running more replicas (`@effect/cluster` shards
+  durable workflows across instances), is the architecture. An external system
+  boundary is REST + OpenAPI; a reliable outbound effect is `ctx.outbox`.
 
 ## Plugins
 

package/templates/AGENTS.md

@@ -404,11 +404,21 @@ Do NOT write `x.page.tsx`, `index.page.tsx` or `[id].page.tsx` — those were th
 **Every suffix above is a CONTRACT, not a label.** Something else depends on each
 promise, and `voltro doctor` enforces all of them:
 
-- `*.component.ui.tsx` may read (`useT`, `useCan`, `usePermissions`) but must
-  never import a write hook (`useMutation`, `useAction`, `useUpload`, …). That is
-  what lets a caller render it ten thousand times in a list, reuse it across
-  features, and prerender it without reading its source. Lift the write into the
-  owning `*.component.tsx` and pass a handler down.
+- `*.component.ui.tsx` may read (`useT`, `useTFn`, `useCan`, `usePermissions`,
+  the `@voltro/i18n` formatters) but must never import a write hook
+  (`useMutation`, `useAction`, `useUpload`, …). That is what lets a caller render
+  it ten thousand times in a list, reuse it across features, and prerender it
+  without reading its source. Lift the write into the owning `*.component.tsx`
+  and pass a handler down.
+
+  **Reading is a recommendation, not a grudging allowance — call the hook, do
+  not take a prop.** Threading `t` / `formatDate` / `useCan` through props is
+  prop-drilling: it grows the prop surface with every formatter, has to be
+  restated in every intermediate signature and every test, and does NOT make the
+  component more reusable — it makes every call site worse. The one argument for
+  the prop, "it renders without a provider", is already paid for the moment any
+  test mounts one. Pick one way per component head: a `t` prop beside a
+  formatter hook is the worst of both.
 - `*.internal.ts` is the promise that refactoring inside that directory breaks
   nobody. An import from another subtree revokes it.
 - `*.types.ts` having no runtime export is what makes importing it free and makes
@@ -686,6 +696,17 @@ primitive → just save; the supervised dev loop respawns and regenerates.
 - **Don't roll your own session token / ICU/i18n / job runner** — use
   `signSession`/`verifySession`, `@voltro/i18n`, `@effect/workflow`.
 - **Don't add `bullmq`/`temporal`/`react-query`/SWR** — see Mental model.
+- **Don't build a GraphQL layer over the stores.** It would bypass the
+  reactivity path (source-based invalidation, per-delivery guards) — a second,
+  dead read path. External consumers → REST + OpenAPI (`defineRestRoute` +
+  `@voltro/plugin-openapi`); internal clients → RPC + live subscriptions.
+- **Don't write `'use server'` / `'use client'` — there is no RSC.** Islands +
+  loaders + streaming SSR are the model; those directives mark a boundary this
+  framework does not have.
+- **Don't split the app into microservices with service-to-service RPC.** One
+  monolith process, scaled by running more replicas (`@effect/cluster` shards
+  durable workflows across instances), is the architecture. An external system
+  boundary is REST + OpenAPI; a reliable outbound effect is `ctx.outbox`.
 
 ## Plugins
 
@@ -707,7 +728,7 @@ each plugin's own README.
 
 | Topic | Open | Summary |
 |---|---|---|
-| **What's new in 0.50.1** | `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.52.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. |
@@ -765,7 +786,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 / Kafka / Snowflake / BigQuery) 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, 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. |
 | 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. |
 | deactivation | `node_modules/@voltro/cli/templates/agent-docs/plugins/deactivation.md` (or `node_modules/@voltro/plugin-deactivation/README.md`) | A schema mixin that marks a subject as deactivated (can't log in) while keeping its data fully visible — the deliberate opposite of soft-delete. |
@@ -785,14 +806,14 @@ each plugin's own README.
 | prometheus | `node_modules/@voltro/cli/templates/agent-docs/plugins/prometheus.md` (or `node_modules/@voltro/plugin-prometheus/README.md`) | Prometheus exporter — scrapes the unified Metrics-API at GET /metrics in text exposition format. |
 | ratelimit | `node_modules/@voltro/cli/templates/agent-docs/plugins/ratelimit.md` (or `node_modules/@voltro/plugin-ratelimit/README.md`) | Per-endpoint, per-subject and per-tenant request limits via the rpc interceptors. Sliding-window / fixed-window / token-bucket, memory / postgres / redis stores. |
 | rbac | `node_modules/@voltro/cli/templates/agent-docs/plugins/rbac.md` (or `node_modules/@voltro/plugin-rbac/README.md`) | Roles + permissions + the permission() handler guard. Roles compile to scopes. |
+| row-history | `node_modules/@voltro/cli/templates/agent-docs/plugins/row-history.md` (or `node_modules/@voltro/plugin-row-history/README.md`) | Full row history + time-travel. audit() records who/when; row-history records what-changed-to-what — a value snapshot of every row on every write, with as-of queries. |
 | scim | `node_modules/@voltro/cli/templates/agent-docs/plugins/scim.md` (or `node_modules/@voltro/plugin-scim/README.md`) | SCIM 2.0 provisioning — Users + Groups REST endpoints so an enterprise IdP (Okta, Entra, OneLogin) can create / update / deactivate users in your app. |
 | search | `node_modules/@voltro/cli/templates/agent-docs/plugins/search.md` (or `node_modules/@voltro/plugin-search/README.md`) | Keep an external search index (Typesense / Meilisearch / Algolia) in sync with your tables via the ChangeEvent tap, query it tenant-scoped through a typed action + hook. |
 | sentry | `node_modules/@voltro/cli/templates/agent-docs/plugins/sentry.md` (or `node_modules/@voltro/plugin-sentry/README.md`) | Deep Sentry integration — errors correlated to the distributed trace, breadcrumbs from the log sink, and opt-in performance traces. |
 | soft-delete | `node_modules/@voltro/cli/templates/agent-docs/plugins/soft-delete.md` (or `node_modules/@voltro/plugin-soft-delete/README.md`) | The softDelete() schema mixin — deletedAt / deletedBy columns, delete() redirected to an UPDATE, default reads filtered, hardDelete() bypass. |
 | sso-saml | `node_modules/@voltro/cli/templates/agent-docs/plugins/sso-saml.md` (or `node_modules/@voltro/plugin-sso-saml/README.md`) | Enterprise SAML 2.0 SSO — SP-initiated login, ACS assertion consumer, SP metadata. Signature verification via @node-saml/node-saml; framework session minting built in. |
-| storage | `node_modules/@voltro/cli/templates/agent-docs/plugins/storage.md` (or `node_modules/@voltro/plugin-storage/README.md`) | File storage behind one StorageService — public objects served direct from the bucket/CDN, private objects gated by an access policy + per-object grants. S3 / R2 / GCS / MinIO / filesystem / memory providers, presigned URLs, a dashboard browser. |
+| storage | `node_modules/@voltro/cli/templates/agent-docs/plugins/storage.md` (or `node_modules/@voltro/plugin-storage/README.md`) | File storage behind one StorageService — public objects served direct from the bucket/CDN, private objects gated by an access policy + per-object grants. S3 / MinIO (R2 and GCS via their S3 interop) / Azure / database / filesystem / memory providers, presigned URLs, a dashboard browser. |
 | tinybird | `node_modules/@voltro/cli/templates/agent-docs/plugins/tinybird.md` (or `node_modules/@voltro/plugin-tinybird/README.md`) | Hosted-ClickHouse AnalyticsSink over Tinybird's Events API + Pipes — pay-as-you-go OLAP without operating a cluster. |
-| versioning | `node_modules/@voltro/cli/templates/agent-docs/plugins/versioning.md` (or `node_modules/@voltro/plugin-versioning/README.md`) | Full row history + time-travel. audit() records who/when; versioning records what-changed-to-what — a value snapshot of every row on every write, with as-of queries. |
 | webhooks | `node_modules/@voltro/cli/templates/agent-docs/plugins/webhooks.md` (or `node_modules/@voltro/plugin-webhooks/README.md`) | First-class outgoing + incoming webhooks — declared events with a webhook: block, defineIncomingWebhook in *.webhook.tsx files, runtime subscriptions, durable delivery via @effect/workflow, HMAC signing, provider presets, and idempotency. |
 
 

package/templates/agent-docs/_index.md

@@ -9,7 +9,7 @@ each plugin's own README.
 
 | Topic | Open | Summary |
 |---|---|---|
-| **What's new in 0.50.1** | `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.52.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 / Kafka / Snowflake / BigQuery) 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, 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. |
 | 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. |
 | deactivation | `node_modules/@voltro/cli/templates/agent-docs/plugins/deactivation.md` (or `node_modules/@voltro/plugin-deactivation/README.md`) | A schema mixin that marks a subject as deactivated (can't log in) while keeping its data fully visible — the deliberate opposite of soft-delete. |
@@ -87,12 +87,12 @@ each plugin's own README.
 | prometheus | `node_modules/@voltro/cli/templates/agent-docs/plugins/prometheus.md` (or `node_modules/@voltro/plugin-prometheus/README.md`) | Prometheus exporter — scrapes the unified Metrics-API at GET /metrics in text exposition format. |
 | ratelimit | `node_modules/@voltro/cli/templates/agent-docs/plugins/ratelimit.md` (or `node_modules/@voltro/plugin-ratelimit/README.md`) | Per-endpoint, per-subject and per-tenant request limits via the rpc interceptors. Sliding-window / fixed-window / token-bucket, memory / postgres / redis stores. |
 | rbac | `node_modules/@voltro/cli/templates/agent-docs/plugins/rbac.md` (or `node_modules/@voltro/plugin-rbac/README.md`) | Roles + permissions + the permission() handler guard. Roles compile to scopes. |
+| row-history | `node_modules/@voltro/cli/templates/agent-docs/plugins/row-history.md` (or `node_modules/@voltro/plugin-row-history/README.md`) | Full row history + time-travel. audit() records who/when; row-history records what-changed-to-what — a value snapshot of every row on every write, with as-of queries. |
 | scim | `node_modules/@voltro/cli/templates/agent-docs/plugins/scim.md` (or `node_modules/@voltro/plugin-scim/README.md`) | SCIM 2.0 provisioning — Users + Groups REST endpoints so an enterprise IdP (Okta, Entra, OneLogin) can create / update / deactivate users in your app. |
 | search | `node_modules/@voltro/cli/templates/agent-docs/plugins/search.md` (or `node_modules/@voltro/plugin-search/README.md`) | Keep an external search index (Typesense / Meilisearch / Algolia) in sync with your tables via the ChangeEvent tap, query it tenant-scoped through a typed action + hook. |
 | sentry | `node_modules/@voltro/cli/templates/agent-docs/plugins/sentry.md` (or `node_modules/@voltro/plugin-sentry/README.md`) | Deep Sentry integration — errors correlated to the distributed trace, breadcrumbs from the log sink, and opt-in performance traces. |
 | soft-delete | `node_modules/@voltro/cli/templates/agent-docs/plugins/soft-delete.md` (or `node_modules/@voltro/plugin-soft-delete/README.md`) | The softDelete() schema mixin — deletedAt / deletedBy columns, delete() redirected to an UPDATE, default reads filtered, hardDelete() bypass. |
 | sso-saml | `node_modules/@voltro/cli/templates/agent-docs/plugins/sso-saml.md` (or `node_modules/@voltro/plugin-sso-saml/README.md`) | Enterprise SAML 2.0 SSO — SP-initiated login, ACS assertion consumer, SP metadata. Signature verification via @node-saml/node-saml; framework session minting built in. |
-| storage | `node_modules/@voltro/cli/templates/agent-docs/plugins/storage.md` (or `node_modules/@voltro/plugin-storage/README.md`) | File storage behind one StorageService — public objects served direct from the bucket/CDN, private objects gated by an access policy + per-object grants. S3 / R2 / GCS / MinIO / filesystem / memory providers, presigned URLs, a dashboard browser. |
+| storage | `node_modules/@voltro/cli/templates/agent-docs/plugins/storage.md` (or `node_modules/@voltro/plugin-storage/README.md`) | File storage behind one StorageService — public objects served direct from the bucket/CDN, private objects gated by an access policy + per-object grants. S3 / MinIO (R2 and GCS via their S3 interop) / Azure / database / filesystem / memory providers, presigned URLs, a dashboard browser. |
 | tinybird | `node_modules/@voltro/cli/templates/agent-docs/plugins/tinybird.md` (or `node_modules/@voltro/plugin-tinybird/README.md`) | Hosted-ClickHouse AnalyticsSink over Tinybird's Events API + Pipes — pay-as-you-go OLAP without operating a cluster. |
-| versioning | `node_modules/@voltro/cli/templates/agent-docs/plugins/versioning.md` (or `node_modules/@voltro/plugin-versioning/README.md`) | Full row history + time-travel. audit() records who/when; versioning records what-changed-to-what — a value snapshot of every row on every write, with as-of queries. |
 | webhooks | `node_modules/@voltro/cli/templates/agent-docs/plugins/webhooks.md` (or `node_modules/@voltro/plugin-webhooks/README.md`) | First-class outgoing + incoming webhooks — declared events with a webhook: block, defineIncomingWebhook in *.webhook.tsx files, runtime subscriptions, durable delivery via @effect/workflow, HMAC signing, provider presets, and idempotency. |

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 / Kafka / Snowflake / BigQuery) 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, 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"
@@ -617,6 +617,14 @@
       "doc": "plugins/rbac.md",
       "module": "agent-docs/plugins/rbac.md"
     },
+    {
+      "slug": "row-history",
+      "title": "Row history",
+      "description": "Full row history + time-travel. audit() records who/when; row-history records what-changed-to-what — a value snapshot of every row on every write, with as-of queries.",
+      "pkg": "@voltro/plugin-row-history",
+      "doc": "plugins/row-history.md",
+      "module": "agent-docs/plugins/row-history.md"
+    },
     {
       "slug": "scim",
       "title": "SCIM",
@@ -660,7 +668,7 @@
     {
       "slug": "storage",
       "title": "Storage",
-      "description": "File storage behind one StorageService — public objects served direct from the bucket/CDN, private objects gated by an access policy + per-object grants. S3 / R2 / GCS / MinIO / filesystem / memory providers, presigned URLs, a dashboard browser.",
+      "description": "File storage behind one StorageService — public objects served direct from the bucket/CDN, private objects gated by an access policy + per-object grants. S3 / MinIO (R2 and GCS via their S3 interop) / Azure / database / filesystem / memory providers, presigned URLs, a dashboard browser.",
       "pkg": "@voltro/plugin-storage",
       "doc": "plugins/storage.md",
       "module": "agent-docs/plugins/storage.md"
@@ -673,14 +681,6 @@
       "doc": "plugins/tinybird.md",
       "module": "agent-docs/plugins/tinybird.md"
     },
-    {
-      "slug": "versioning",
-      "title": "Row versioning",
-      "description": "Full row history + time-travel. audit() records who/when; versioning records what-changed-to-what — a value snapshot of every row on every write, with as-of queries.",
-      "pkg": "@voltro/plugin-versioning",
-      "doc": "plugins/versioning.md",
-      "module": "agent-docs/plugins/versioning.md"
-    },
     {
       "slug": "webhooks",
       "title": "Webhooks",
@@ -710,9 +710,9 @@
     "api-ratelimit": "agent-docs/templates/apibackends.md",
     "api-rbac": "agent-docs/templates/apibackends.md",
     "api-rest": "agent-docs/templates/apibackends.md",
+    "api-row-history": "agent-docs/templates/apibackends.md",
     "api-saas": "agent-docs/templates/apibackends.md",
     "api-search": "agent-docs/templates/apibackends.md",
-    "api-versioning": "agent-docs/templates/apibackends.md",
     "api-webhooks": "agent-docs/templates/apibackends.md",
     "app": "agent-docs/templates/appshells.md",
     "blank": "agent-docs/templates/appshells.md",

package/templates/agent-docs/cli.md

@@ -142,6 +142,12 @@ config value always winning:
 | `VOLTRO_CSP_HTML` | CSP for HTML responses (under `strict` it defaults to the same policy as `VOLTRO_CSP`). `off` drops just this one. |
 | `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. |
+
+Response compression for the buffered non-rpc surfaces (and `voltro start`'s
+HTML) is configured in the same `http:` block — `http.compression.{enabled,minBytes}`
+(default on, 1 KiB threshold; `POST /rpc` is never compressed). Details + the
+BREACH reasoning: [Security → compression](/docs/security/overview#response-compression--and-where-breach-sits).
 
 Generate any of the secret vars above with `voltro secret generate <purpose>` (see [`secret`](#command-quick-reference)) — it picks the right length and format. A lower environment's secrets must always differ from production's.
 
@@ -317,36 +323,48 @@ fails to update.
 
 ```
 observed: 12/34 procedures exercised (35%)
+  1 declared/observed mismatch among the 12 that ran
   mutation(orders.place) (api/orders/place.mutation.ts)
     writes 'inventory' (update) but declares no target for it
     subscriptions on that table are not invalidated by this mutation
     fix: add { table: 'inventory', op: 'update' } to this procedure's targets
-  22 unexercised — no recording, so nothing is claimed about them
+  20 never ran — no observation exists, so nothing is claimed about them
+  2 ran with no table access recorded — indistinguishable from touching nothing, so nothing is claimed about them either
 ```
 
-Three things about that output are deliberate:
+Four things about that output are deliberate:
 
 - **Coverage comes first.** Three findings at 8% coverage and three at 95% are
   different claims. Hiding the denominator is how a check starts overstating
   what it knows.
-- **`unexercised` is a third state, not a finding.** A procedure no test and no
-  dev session ever ran has *no observation* — which is not the same as "touches
-  nothing". It is counted and never reported as a problem.
+- **Every result line carries the count it is a result about.** `1 mismatch
+  among the 12 that ran` — never a bare verdict. A sentence that still reads as
+  a conclusion once it is cut out of this block will eventually be cut out of
+  it, and quoted as a clean bill of health for a surface nobody measured.
+- **The counts partition the declared set — they add up to the total, always.**
+  There are two ways to say nothing about a procedure, and both get a line:
+  it never ran, or it ran and no table access was recorded for it. A procedure
+  that appeared in no line at all would be indistinguishable from a defect in
+  `check` itself, so the two kinds of blindness are named separately and never
+  folded into the findings.
 - **Observed diagnostics never fail the build.** An observation is evidence
   about the runs that happened, not a proof about the ones that didn't, and
   `check`'s exit code gates CI. They are always warnings.
 
-A fourth thing is not visible in that output and matters more than any of the
-three: **the recorder only knows what ran.** A boot is not a run. An idle dev
+A fifth thing is not visible in that output and matters more than any of the
+four: **the recorder only knows what ran.** A boot is not a run. An idle dev
 instance that started, served nothing and stopped produces
 
 ```
-observed: 0/2755 procedures exercised (0%)
-  2753 unexercised — no recording, so nothing is claimed about them
+observed: 0/34 procedures exercised (0%)
+  nothing was compared — a declaration is only checked against a procedure that RAN
+  34 never ran — no observation exists, so nothing is claimed about them
 ```
 
-which is the honest answer and also a useless one — the section says nothing
-about 99.9% of the surface. If you want this as a CI gate, the recording pass has
+Note what that is NOT: it is not "no mismatches found". At zero coverage there
+is no result to report, so the section reports the absence of the comparison
+instead. The honest answer is also a useless one — it says nothing about any of
+the surface. If you want this as a CI gate, the recording pass has
 to be a run that actually *calls* the procedures. `voltro e2e` is one: it spawns
 `voltro dev` for the api, which turns recording on, and then drives the specs. A
 harness of your own that boots the app in its own process needs
@@ -365,6 +383,29 @@ handlers: a static pass over code that reaches the store through shared helpers,
 behind conditionals, has a long tail of both false positives and false negatives
 — and a check that is *sometimes* wrong is one people stop reading.
 
+#### Declared vs LIVE — against a running server
+
+When `check` runs against a live api (a local `voltro dev`, or a deployed one
+via `--url`), it also diffs the tags your source declares — plugin routes
+included — against the server's actual rpc registry:
+
+```
+declared vs live: 2 of 214 source-declared tags are NOT registered on the server
+  ⚠ presence.heartbeat — a generated client calls this and gets "Unknown request tag"
+  ⚠ presence.list — a generated client calls this and gets "Unknown request tag"
+  fix: if the server runs older code, redeploy; if it is current, plugin route registration was dropped — check the boot line "plugin routes registered"
+```
+
+Only the source→live direction is a finding — a tag the server carries that your
+source does not declare is normal runtime synthesis (agents, undo, approvals).
+This exists because exactly that gap has shipped once: every
+plugin-contributed procedure dead under `voltro serve`, with nothing anywhere
+saying so — the only evidence was a `Defect` frame in the browser console of
+whoever happened to look. (That registration defect is fixed; the diff is the
+runtime backstop for the next one, e.g. a stale deploy.) The server now also
+logs every `Defect` frame it sends (`rpc defect sent to client`), so an unknown
+tag is an operator-visible event rather than a client-only one.
+
 The HTTP surface is reachable directly too — e.g. `curl -s localhost:4000/_voltro/inspect/rpc | jq` (there is no `/_voltro/inspect/queries` endpoint; it's `rpc` for procedures, `routes` for the web page tree, `subscriptions` for active subscribers).
 
 ## Where to read next
@@ -1364,7 +1405,7 @@ Point the Kubernetes liveness probe at `/internal/liveness` and the readiness pr
 For WebSocket connections to land on the same backend (required for in-process subscription state):
 
 - Reverse proxy: `lb_policy ip_hash` (Caddy) / `ip_hash` (nginx).
-- Or use `@voltro/plugin-cluster` to share subscription state across instances → any-load-balancer-works.
+- Cross-instance subscription invalidation is built in on Postgres (LISTEN/NOTIFY) and MySQL/MariaDB (binlog CDC); on any other dialect add [`@voltro/plugin-broadcast`](/docs/plugins/broadcast) (Redis/NATS). With that in place a reconnect may land on any replica and still sees every change — sticky sessions then only keep one live connection pinned, they are not a correctness requirement.
 
 ## `voltro build api --target <swift|kotlin>` — native SDK generation
 
@@ -1796,6 +1837,47 @@ matching rule lives inside the CLI, so you cannot re-derive the list with your
 own grep. `--json` prints the complete scan, nothing elided, with no preflight
 output mixed in:
 
+### Unimported `@voltro/*` dependencies
+
+A declared framework dependency nobody imports still gets installed, walked on
+every `voltro update`, and read as evidence the package is in use — its
+breaking-change notes included. The usual origin is a migration: the app moves
+off a framework package to a third-party one, and the `package.json` entry
+stays. `voltro doctor` checks every `@voltro/*` in `dependencies` and
+`devDependencies` for an import site:
+
+```
+unimported deps · 8 @voltro/* package(s) declared, 214 file(s) scanned
+  ⚠ @voltro/i18n — declared in dependencies, imported nowhere
+      a dependency nobody imports still gets installed, updated, and read as
+      evidence the package is in use — its breaking-change notes included.
+      Remove it, or if it IS imported through an assembled specifier the scan
+      cannot see, keep it and ignore this line — the rule is advisory.
+  · (2 loaded by the framework itself: @voltro/cli, @voltro/sql-postgres)
+```
+
+Scoped to `@voltro/*` deliberately: for third-party packages the same question
+has a long tail of legitimate no-import shapes, and a rule that is sometimes
+wrong is one people stop reading. Three states are distinguished, and each is
+printed:
+
+- **Exempt, by name** — packages the framework loads on your declaration
+  (`@voltro/cli` is the binary; `@voltro/devtools` is mounted by `voltro dev`;
+  the `@voltro/sql-*` dialect drivers are loaded from your config). An
+  exemption you cannot see is a finding you cannot question.
+- **Not measurable yet** — `@voltro/client` / `@voltro/web` are normally
+  imported by *generated* code. On a tree where codegen has never run, their
+  absence is a missing measurement, not a dead dependency; the section says so
+  and tells you to run `voltro dev` once.
+- **Unimported** — advisory, never fatal. A mention in a comment or an error
+  string does not count as an import (a commented-out import is exactly the
+  residue this looks for), and an import assembled at runtime from string
+  pieces is invisible to the scan — the finding text says both.
+
+The full report is in `voltro doctor --json` under `unimportedDeps`
+(`null` when there is no `package.json` to read — "could not check" and
+"checked, clean" never print the same).
+
 ### Duplicate package instances
 
 `voltro doctor` also reports any identity-sensitive package resolved at more than
@@ -2850,7 +2932,7 @@ Not every run can take it, and a run that cannot **says why** rather than quietl
 taking the slower path:
 
 - a store the framework cannot send DDL to (the in-memory store).
-- a **write recorder** on any table in the set — `versioningPlugin({ timing:
+- a **write recorder** on any table in the set — `rowHistoryPlugin({ timing:
   'in-transaction' })` and friends. A recorder is keyed by table name, so a
   staged write would find none and the recorder would silently not run. Its
   promise is "if the change committed, the entry is there", so the run keeps the
@@ -2906,7 +2988,7 @@ ITSELF is not a cycle: one statement carries the whole table.
 
 ### A `replace` does not write per-row history
 
-Write recorders — `versioningPlugin({ timing: 'in-transaction' })` and anything
+Write recorders — `rowHistoryPlugin({ timing: 'in-transaction' })` and anything
 else registered through the same seam — are **suspended for a `replace`**. A
 replace sets a state; it does not change rows, so a per-row history entry would
 describe something that did not happen. On a large bundle that is not a detail:
@@ -3412,8 +3494,22 @@ Aborting on the first one made `--assets` unusable for exactly the deployment th
 
 Only a genuine *not found* is treated this way. A 403 from a rotated credential or a 5xx from a backend outage still fails the capture — calling those "the object is gone" would turn a recoverable outage into a backup that quietly contains nothing.
 
+**Three numbers, because they answer three questions.** `_voltro_storage_refs` holds one row per *reference*, several of which legitimately name one *key*, and the content-addressed store keeps one body per distinct *object*:
+
+```
+57 reference(s) → 16 key(s) → 16 object(s), 65476 byte(s) under assets/
+```
+
+The stamp carries all three (`references`, `count`, `objects`, with `totalBytes` and `objectBytes` beside them). It used to carry only the reference count under the name `count`, so a stamp read `57` over a directory holding 16 files — and anyone answering *"are all the blobs there?"* after a restore compared the two and found a 3.5× gap that was not one. A key named by several references is also fetched once now, rather than downloaded and hashed once per row.
+
 Resume is per blob key, so re-running a `--assets` capture that was interrupted transfers only what is missing. The **dump itself has no resume** — a vendor artifact is one opaque file with no offset to restart from. If you need a resumable, chunkable, observable transfer, that is the logical path (`export` / `import`), and it is why the logical path exists.
 
+### The stamp's skew warning compares the backup against the TARGET
+
+`restore` reads `voltro-backup-stamp.json` before touching anything and warns when the backup's schema fingerprint differs from the target's. That warning used to say the difference was against "what this code declares", and it was not — the value it compares against is the target database's *live* schema, read by introspection at restore time. Bringing a target to the backup's shape makes the warning disappear while the declared fingerprint is a third value entirely, which is how the mislabel was caught. The comparison was always the useful one; only the sentence was wrong, and it sent readers looking for a code change where a database differed.
+
+The same distinction shows up in `voltro db plan`, which prints `live … · declared …` rather than `from → to` for the same reason: **a hash of a live database never equals the hash of the declaration it came from.** Introspection cannot recover everything a declaration carries — generated expressions, `maxLength`, sensitivity markers — so the two are not comparable and are not meant to match. The plan's operation list is what says whether they agree; `0 operations` under two different fingerprints means they do.
+
 ### A restore that is interrupted refuses the next boot
 
 `restore` writes one row into `_voltro_replace_in_progress` **before** the first destructive statement and removes it **after** the last write — the blobs included. Its presence at boot is a refusal naming the artifact that was going in.
@@ -3427,6 +3523,17 @@ Two changes, covering different dumps:
 - **A backup taken by `voltro data backup` excludes the marker table** (`--exclude-table` / `--ignore-table`). It can no longer carry the thing that erases the guard on the way back in.
 - **`restore` writes the marker back after the tool exits**, on the failing path as well as the succeeding one. That covers dumps taken before this version and dumps made by hand. If it was removed and rewritten you get a warning saying so; if it could not be rewritten you get an error, because the guard is then off for that run and nothing will stop the next boot.
 
+**A restore that cannot write the marker at all is refused.** Two things can prevent it — the bookkeeping store will not open (wrong credentials, an unreachable database, a missing env var, no `app.config.ts` from here), or the table is not there yet — and both mean the same thing to you: this restore would run with no guard. The refusal names which one it was:
+
+```
+✗ refusing to restore: the in-progress marker cannot be written.
+    reason: bookkeeping is unavailable: connect ECONNREFUSED 127.0.0.1:5432
+```
+
+This used to be a silent hole rather than a refusal, and worse than silent. The failure to open the store was caught and discarded, and the discarded value guarded *every* branch below it — including the refusal that would have reported the guard missing. So a restore ran on and, over a database with zero marker rows, printed *"the next boot will REFUSE, by design"*. The next boot did not refuse, and `voltro data clear-replace-marker` had nothing to clear. A restore is the operation you run against a target that is already unwell, so the precaution was falling away exactly when it was needed.
+
+**`--no-marker`** restores without the guard, deliberately. It warns every time and names the reason the marker was unavailable. It exists because the accidental way did: if going unguarded is ever right, it should be something you typed.
+
 | dialect | shape | effect |
 |---|---|---|
 | postgres, mysql, mariadb | the dump names the whole database, so the restore drops the marker table too | our backups exclude it; for any other dump the marker is written back after the tool exits |
@@ -3435,6 +3542,10 @@ Two changes, covering different dumps:
 
 Clear a marker deliberately with `voltro data clear-replace-marker --yes` once you have decided the current state is correct.
 
+**`_voltro_data_transfers` is excluded for the same reason, one table over.** The restore opens its own run row there *before* the tool starts; a dump that carried the table dropped it mid-flight, and the update recording the outcome then wrote into a table that no longer held the row. The visible result was that a failed native restore did not appear in `voltro data transfers` at all — only the `backup` row the dump had brought over from the *source* database. The command that answers "did the restore finish" could not see the run asking.
+
+Exactly those two tables are excluded, and the line is deliberate: a native restore into the same deployment *should* bring the migration ledger, the stored plans, the CDC offsets and the schedule claims — they describe the data being restored. These two describe the *restore*, and a record of an operation must not be overwritten by the operation it records.
+
 ### Both directions are in the history
 
 `backup` and `restore` write a row to the same `_voltro_data_transfers` record `import` and `export` use, so `voltro data transfers` answers "did last night's backup finish" from the instance that ran it: