@voltro/cli 0.50.1 → 0.52.0

package/templates/agent-docs/introduction.md

@@ -132,6 +132,22 @@ Voltro is deliberately opinionated about boring things (HTTP, state, transport,
 - **Magic.** Every file convention is documented; every generated file lives in `.framework/` and you can read it.
 - **Codegen you have to remember to run.** Schema flows from your tables to your React components automatically via Vite's module graph.
 
+## Deliberate noes
+
+Two questions come up in every framework comparison. Both are decided — deliberately no — and here is why, so nobody has to re-litigate them.
+
+### Why is there no GraphQL API?
+
+1. **GraphQL's three core promises are solved differently here.** Type-safe selective reads ⇒ typed queries + schema inference. One endpoint for every client ⇒ the RPC socket with a generated client. Third-party consumers ⇒ [REST routes](/docs/data/rest-routes) + [OpenAPI 3.1](/docs/plugins/openapi) (`@voltro/plugin-openapi`).
+2. **A GraphQL gateway would have no access to the reactivity path** — source-based invalidation, per-delivery guards. It would be a second, dead read path whose results are never live: exactly the kind of duplicate path this framework refuses to keep.
+3. **Resolver N+1, persisted-query complexity, and a second permission model** (field-level vs. our guards/RLS) buy nothing the existing surface cannot do.
+
+Don't build a GraphQL layer over the stores. External consumers get REST + OpenAPI; internal clients get RPC + live subscriptions.
+
+### Why not React Server Components?
+
+RSC is a second rendering **and** data model — Flight serialization, `'use client'` boundaries, deep bundler integration — that would compete with the reactive subscription model instead of composing with it. The problems it solves are covered by what exists today: [islands](/docs/routing/islands) for shipping less JS, loaders for server data at render time, and streaming SSR with `defer()` for progressive delivery. Don't write `'use server'` / `'use client'` directives in a Voltro app; they mark a boundary this framework does not have.
+
 ## Where to read next
 
 - [Getting started](/docs/intro/getting-started) — scaffold + boot in under a minute
@@ -435,6 +451,7 @@ Voltro replaces router and registry config with **filesystem conventions**. Drop
 | `*.agent.server.tsx` | Server agent **executor**: `defineAgentExecutor(descriptor, { system, tools, model, maxSteps })`. | Agent runtime. |
 | `*.tool.tsx` | A tool an agent can call. Schema + handler. | Agent runtime. |
 | `*.webhook.tsx` | Outgoing webhook spec (target, retry, schema). | Webhook delivery worker. |
+| `*.ws.ts` | Raw WebSocket gateway — `defineWebSocket({ path, auth, onConnection })` as the default export, for FOREIGN protocols beside the rpc socket. | Upgrade listener on the api server, both boot paths. |
 | `*.entity.ts` | Database table — one table per file: `table()` + columns + mixins. Re-exported from a `database/index.ts` barrel. | Migrations + the runtime data store. |
 | `*.config.ts` | App-level config (`app.config.ts`, `tsconfig.json`, etc.). | The CLI. |
 
@@ -470,6 +487,25 @@ Without the marker the leak is still caught — by the rpcGroup guard — but on
 
 An unmarked file makes no claim, and that is fine: `*.client.ts` is for the shared files where the mistake is expensive, not a label to sprinkle on everything.
 
+### Raw WebSocket gateways: `*.ws.ts`
+
+A `*.ws.ts` file's default export mounts a raw WebSocket upgrade path beside the rpc socket — for a protocol the framework does not speak (a Yjs provider, a legacy device fleet). Discovered on **both** boot paths, `voltro dev` and `voltro serve`:
+
+```ts
+// gateways/collab.ws.ts
+import { defineWebSocket } from '@voltro/protocol'
+
+export default defineWebSocket({
+  path: '/gateways/collab',
+  auth: 'subject',   // REQUIRED, no default — or 'public', a decision you write down
+  onConnection: ({ send, onMessage, subject }) => {
+    onMessage((data) => send(data))   // your protocol, your frames
+    return () => { /* teardown — runs on disconnect, credential expiry, shutdown */ }
+  },
+})
+```
+
+`auth: 'subject'` authenticates through the same chain as rpc/SSR **before** the upgrade (401 while it is still http) and binds the connection to the credential's expiry (close code `4001`); every gateway path is origin-checked at upgrade. Two gateways on one path refuse the boot; a plain GET on a gateway path answers `426`. App realtime stays [subscriptions](/docs/data/subscriptions) — full detail under [Raw WebSocket gateways](/docs/data/subscriptions#raw-websocket-gateways--definewebsocket).
 
 ## The web side (`apps/*/web/`)
 
@@ -494,6 +530,16 @@ export const interactive = 'islands' as const      // 'none' | 'islands' | 'full
 - `renderMode` controls when the HTML is produced (build vs. request).
 - `interactive` controls how much JS ships (`'none'` strips it all, `'full'` hydrates the page, `'islands'` hydrates only `.island.tsx` files).
 
+A page can also declare its query-string contract as a page export:
+
+```tsx
+export const searchParams = Schema.Struct({
+  page: Schema.optionalWith(Schema.NumberFromString, { default: () => 1 }),
+})
+```
+
+- `searchParams` (an `effect/Schema` struct — every field optional or with a default) types the page's query string: `useSearchParams(searchParams)` returns the decoded shape, and links built with `withQuery` type-check against it. Details: [Pages → Query strings](/docs/routing/pages#query-strings).
+
 ## Discovery in practice
 
 ```text

package/templates/agent-docs/local-first-mobile.md

@@ -26,10 +26,13 @@ imports it directly. The React wrappers live behind `@voltro/local-first/react`
 > transport, [`useCrdtText`](#a-collaborative-text-field-usecrdttext) — the React
 > binding for a collaborative text field — [presence/awareness](#presence--awareness)
 > via `usePresence`, [durable IndexedDB persistence](#durable-persistence), and the
-> [`localFirst` table mixin](#the-localfirst-table-mixin). What remains is a thin
-> [runtime binding](#whats-shipped-vs-a-runtime-seam) to provisioned infra
-> (a broker at scale) plus the two app-specific tags `useCrdtText` is pointed at —
-> not un-built framework code.
+> [`localFirst` table mixin](#the-localfirst-table-mixin). What remains falls in
+> two tiers: a thin [runtime binding](#whats-shipped-vs-a-runtime-seam) to
+> provisioned infra (a broker at scale) plus the two app-specific tags
+> `useCrdtText` is pointed at — and the sync **engine** (a locally queryable
+> database, automatic mirroring of `localFirst()` tables, partial replication),
+> which is planned and not yet built. Today `localFirst()` is a declaration the
+> tooling discovers, not an auto-synced local database.
 
 ## CRDT text: `crdtText` + `mergeCrdtStates`
 
@@ -204,6 +207,26 @@ import { Schema } from 'effect'
 body: Schema.NullOr(Schema.Uint8ArrayFromBase64)
 ```
 
+### Known cost limits of `crdtText()` today
+
+Two amplification effects are worth knowing before you put a `crdtText()` column
+on a hot editing path — both are per-keystroke costs, and both are real today:
+
+- **Wire amplification downstream.** A subscription delta carries the row's
+  columns, and for a CRDT column that is the merged **full state** (base64) —
+  every keystroke ships the whole document to every subscriber of the query,
+  not the one-edit update. Keep the streamed query's projection narrow (don't
+  project `body` into a list view), or subscribe to the document row alone.
+- **Undo/row-history capture.** Server-side capture (the undo log — default-on
+  outside production — and `plugin-row-history`'s row history, where enabled)
+  snapshots the row per mutation, so per-keystroke mutations write a
+  full-state blob per keystroke into those tables. Point them away from
+  CRDT-heavy tables, or batch edits before pushing.
+
+Both limits are on the framework's roadmap (incremental delivery and
+CRDT-aware capture); until then they are costs to design around, not bugs to
+report.
+
 ## Presence & awareness
 
 `usePresence(roomId, self, { channel })` publishes this peer's ephemeral state
@@ -348,9 +371,13 @@ constructs the `ApiHandle` (runtime + subscription cache + rpc client) over a
 WebSocket **you** inject, so RN passes its own `globalThis.WebSocket` and gets
 the same client stack the web app uses, without pulling in `@voltro/web`.
 
-Still open before the loop is proven end-to-end on a device: codegen emitting the
-api's rpc group for a mobile app, an RN persistence adapter, a NetInfo connection
-signal, and a reconnect supervisor. `@voltro/react-native` ships the
+Still open before the loop is proven end-to-end on a device: the device boot
+itself — everything here is unit-tested without a simulator, so booting a real
+Metro runtime is the remaining verification — plus `*.deepLink.ts` codegen
+discovery (until it lands, register links via `matchFirstDeepLink(links, url)`),
+push **sender** adapters (APNs / FCM need per-tenant credentials), and
+native-module bindings (camera, biometrics, secure token storage need a native
+runtime). `@voltro/react-native` ships the
 mobile-specific plumbing around that, limited to the parts that need **no
 per-tenant credentials and no native runtime**: device registration,
 background-sync scheduling, offline-first defaults, a connection-status surface,

package/templates/agent-docs/plugins/ai-flows.md

@@ -356,7 +356,7 @@ import { Effect } from 'effect'
 export default defineSchedule({ cron: '*/15 * * * *', timezone: 'Europe/Berlin', handler: (s) => Effect.promise(() => runCadenceTick(s.app)) })
 ```
 
-Adopt `@voltro/plugin-versioning` on `_voltro_ai_flows` for automatic edit history.
+Adopt `@voltro/plugin-row-history` on `_voltro_ai_flows` for automatic edit history.
 
 ## Deployment notes
 

package/templates/agent-docs/plugins/audit.md

@@ -86,7 +86,7 @@ auditPlugin({ sink: 'datastore', record: 'errors' })
 ```
 
 - `'all'` (default) — every invocation.
-- `'errors'` — refusals only: a denied guard, a revoked key, a rejected validation. This is the forensic core, and it pairs with [`@voltro/plugin-versioning`](/docs/plugins/versioning), which records the successful *writes* — so the two together still cover everything while this table stays small enough that retention is a footnote.
+- `'errors'` — refusals only: a denied guard, a revoked key, a rejected validation. This is the forensic core, and it pairs with [`@voltro/plugin-row-history`](/docs/plugins/row-history), which records the successful *writes* — so the two together still cover everything while this table stays small enough that retention is a footnote.
 - a predicate — `(event) => boolean`, for anything else.
 
 `'all'` is the default even though `'errors'` is often the right choice, because defaulting to errors would silently stop recording successes for every app that upgrades — and "what did this compromised account touch" is answered by successes. Shrinking the trail is a decision you make with your eyes open.
@@ -166,7 +166,7 @@ The trail is only useful if you can enter it by the questions an incident asks.
 
 ```ts
 import { auditByTrace, auditBySubject } from '@voltro/plugin-audit'
-import { historyByTrace } from '@voltro/plugin-versioning'
+import { historyByTrace } from '@voltro/plugin-row-history'
 
 // What happened during ONE call — and what it changed.
 const calls   = await auditByTrace(ctx.store, traceId)
@@ -176,7 +176,7 @@ const changed = await historyByTrace(ctx.store, traceId, ctx.request.subject.ten
 const denied = await auditBySubject(ctx.store, actorId, { status: 'error', limit: 50 })
 ```
 
-`traceId` is the join key. [`plugin-versioning`](/docs/plugins/versioning) records *what changed*; this records *who called and whether they were refused*. Neither is complete alone, and before the join key existed they could not be read together at all.
+`traceId` is the join key. [`plugin-row-history`](/docs/plugins/row-history) records *what changed*; this records *who called and whether they were refused*. Neither is complete alone, and before the join key existed they could not be read together at all.
 
 `auditBySubject` takes `status` as a real argument rather than leaving you to filter in JS: the index is `(subjectId, status, at)`, so a filter applied after fetching would not use it.
 
@@ -300,7 +300,7 @@ philosophies.
 
 That matters because the right to be forgotten is one this framework grants:
 `@voltro/plugin-governance`'s `governance.erase` (`delete | anonymize`) exists
-for it. Without a snapshot, installing audit + versioning + governance together
+for it. Without a snapshot, installing audit + row-history + governance together
 makes the first two unreadable for exactly the subjects an investigation is
 about. **Anonymisation is the worse half**: the join succeeds and returns
 "Anonymised" for every entry that actor ever produced, retroactively rewriting
@@ -392,7 +392,7 @@ auditPlugin({
     typeof ctx.input?.teamId === 'string' ? { teamId: ctx.input.teamId } : undefined,
 })
 
-versioningPlugin({
+rowHistoryPlugin({
   // From the ROW here — that is what this plugin has.
   resolveScope: (row) => ({ teamId: row.teamId }),
 })

package/templates/agent-docs/plugins/cdc-out.md

@@ -1,6 +1,6 @@
 # CDC-out (reverse-ETL)
 
-> 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.
+> 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.
 
 
 
@@ -9,7 +9,7 @@
 <!-- source: en/plugins/cdc-out.md -->
 ## CDC-out (reverse-ETL)
 
-_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._
+_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 — declarative reverse-ETL
 

package/templates/agent-docs/plugins/{versioning.md → row-history.md}

@@ -1,27 +1,27 @@
-# Row versioning
+# Row history
 
-> 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.
+> 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.
 
 
 
 ---
 
-<!-- source: en/plugins/versioning.md -->
-## Row versioning
+<!-- source: en/plugins/row-history.md -->
+## Row history
 
-_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._
+_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._
 
-`@voltro/plugin-versioning` keeps a complete value history of selected tables. Where [`audit()`](/docs/plugins/audit) records *who* changed a row and *when*, versioning records *what* — a full snapshot of the row on every insert / update / delete — and lets you read any row **as of** a past instant. It rides the framework's post-commit ChangeEvent tap, so it captures every write that goes through the store with no per-handler wiring.
+`@voltro/plugin-row-history` keeps a complete value history of selected tables. Where [`audit()`](/docs/plugins/audit) records *who* changed a row and *when*, row-history records *what* — a full snapshot of the row on every insert / update / delete — and lets you read any row **as of** a past instant. It rides the framework's post-commit ChangeEvent tap, so it captures every write that goes through the store with no per-handler wiring.
 
 ## Wiring
 
 ```ts
 // app.config.ts
-import { versioningPlugin } from '@voltro/plugin-versioning'
+import { rowHistoryPlugin } from '@voltro/plugin-row-history'
 
 export default {
   type: 'api' as const, name: 'api',
-  plugins: [versioningPlugin({})],
+  plugins: [rowHistoryPlugin({})],
 }
 ```
 
@@ -30,14 +30,14 @@ Every committed change to a listed table appends a row to `_voltro_row_history`
 The history row's own `id` is **derived** from `(tableName, rowId, version)` and has a fixed width — it is a surrogate, and every part of it is already a column beside it, so do not parse or construct it. That width is the point: an `id()` column is `VARCHAR(64)` on mysql/mariadb and `NVARCHAR(64)` on mssql, so a key built by concatenating those parts grew with your **table name** and stopped fitting past 22 characters — which failed every write to that table, not merely an import.
 
 
-### What gets versioned — opt OUT, not in
+### What gets recorded — opt OUT, not in
 
-`versioningPlugin({})` covers **every table your app declares**. There is no list to write and none to maintain.
+`rowHistoryPlugin({})` covers **every table your app declares**. There is no list to write and none to maintain.
 
 ```ts
-versioningPlugin({})                              // every app table
-versioningPlugin({ exclude: [domainEvents] })     // opt one out
-versioningPlugin({ include: [aiFlowsTable] })     // add a PLUGIN's table
+rowHistoryPlugin({})                              // every app table
+rowHistoryPlugin({ exclude: [domainEvents] })     // opt one out
+rowHistoryPlugin({ include: [aiFlowsTable] })     // add a PLUGIN's table
 ```
 
 Both take table **values**, not names — a misspelling is a compile error at the call site, exactly as with `reference(() => table)`.
@@ -51,18 +51,18 @@ A table named in both `include` and `exclude` throws at construction — only yo
 **Check the boot line once after upgrading.** It prints the RESOLVED count, not the configured one:
 
 ```txt
-versioning active · tables: 41 · historyTable: _voltro_row_history · retentionDays: 365
+row-history active · tables: 41 · historyTable: _voltro_row_history · retentionDays: 365
 ```
 
 If 41 surprises you, `exclude` is the knob. The retention sweep (`VOLTRO_ROW_HISTORY_TTL_HOURS`) still bounds age.
 
 ## What this is NOT — the grain
 
-Versioning records **row changes, not domain events**. One entry per row per write, named by *table*. If your product has a user-facing audit feature whose entries are named after an aggregate root — one `Team` event for a call that writes `teams` + `roles` + `userTeams` + `userTeamRoles` — this is the layer **underneath** that, not a replacement for it.
+Row history records **row changes, not domain events**. One entry per row per write, named by *table*. If your product has a user-facing audit feature whose entries are named after an aggregate root — one `Team` event for a call that writes `teams` + `roles` + `userTeams` + `userTeamRoles` — this is the layer **underneath** that, not a replacement for it.
 
 The distinction is worth reading before you plan a migration onto it. A migration off hundreds of hand-written audit calls onto this tap runs into the same wall a few hours in: the grain is different. A table-keyed tap does not produce an aggregate-keyed trail with better coverage, it produces a *different artifact*. The two compose:
 
-- **versioning** answers "what did row R look like before, and after" — for every write, whether or not anyone remembered to record it;
+- **row history** answers "what did row R look like before, and after" — for every write, whether or not anyone remembered to record it;
 - an **aggregate trail** (the [audit sink](/docs/plugins/audit), one row per mutation invocation) answers "what business operation happened, to which entity, and did it succeed";
 - `traceId` joins them, so one request reads as one story.
 
@@ -95,10 +95,10 @@ migration — with the same meaning as an absent `traceId`.
 
 ## The correlation bridge — joining *what changed* to *who called*
 
-`ChangeEvent` carries the calling `traceId` and `subjectId`, so a history row can be joined to the [audit sink](/docs/plugins/audit) row for the **same call**. Before this, both trails existed and shipped and nothing connected them: versioning knew what changed, the audit sink knew who called and whether they were refused, and no key spanned the two.
+`ChangeEvent` carries the calling `traceId` and `subjectId`, so a history row can be joined to the [audit sink](/docs/plugins/audit) row for the **same call**. Before this, both trails existed and shipped and nothing connected them: row-history knew what changed, the audit sink knew who called and whether they were refused, and no key spanned the two.
 
 ```ts
-import { historyByTrace, historyBySubject } from '@voltro/plugin-versioning'
+import { historyByTrace, historyBySubject } from '@voltro/plugin-row-history'
 
 // What did this call change? (`byTrace`)
 const touched = await historyByTrace(ctx.store, traceId, ctx.request.subject.tenantId)
@@ -118,7 +118,7 @@ Both questions were previously unanswerable at any speed — `byRow` is the only
 ## `timing` — when the history row is written
 
 ```ts
-versioningPlugin({ timing: 'in-transaction' })
+rowHistoryPlugin({ timing: 'in-transaction' })
 ```
 
 | | `'post-commit'` (default) | `'in-transaction'` |
@@ -175,7 +175,7 @@ That is the correct order, not a race to engineer around: the change is durable,
 { "id": "sess_1", "secret": "enc:v1:a56iziEV9THLhzmJ:Vk0ux+0bECleTLBJkCa0Rg==:3AtMwP" }
 ```
 
-So versioning a table with encrypted columns **does not widen exposure** — the history is exactly as readable as the row it came from. This is worth stating because "full row snapshot" reads alarming next to `.encrypted()`, and the cautious reader excludes the table. One did, and only found out by measuring.
+So keeping history for a table with encrypted columns **does not widen exposure** — the history is exactly as readable as the row it came from. This is worth stating because "full row snapshot" reads alarming next to `.encrypted()`, and the cautious reader excludes the table. One did, and only found out by measuring.
 
 **`.serverOnly()` columns ARE withheld**, and for a sharper reason than "a second copy": `crud.*` strips those columns from every row it returns, and a snapshot would smuggle the value back past that stripping inside a `json()` blob, where no column-level rule applies. A marker meaning *never serialize this to a client* cannot survive being re-exported through a different column's contents.
 
@@ -189,7 +189,7 @@ The withheld names are listed under `data._omitted`, so a reader can tell *"this
 ## Querying the timeline
 
 ```ts
-import { rowHistory, rowAsOf } from '@voltro/plugin-versioning'
+import { rowHistory, rowAsOf } from '@voltro/plugin-row-history'
 
 // Every version of a row, oldest → newest — TENANT-SCOPED to the caller:
 const history = await rowHistory(ctx.store, 'posts', postId, ctx.request.subject.tenantId)
@@ -204,7 +204,7 @@ Pass the caller's `tenantId` — reads are **tenant-scoped**: a row's value time
 ## Restore & diff
 
 ```ts
-import { restoreAsOf, diffVersions } from '@voltro/plugin-versioning'
+import { restoreAsOf, diffVersions } from '@voltro/plugin-row-history'
 
 // Roll the LIVE row back to its state at a past instant (tenant-scoped like
 // rowAsOf — no visible state then ⇒ null, nothing written). The restore goes

package/templates/agent-docs/plugins/storage.md

@@ -1,6 +1,6 @@
 # Storage
 
-> 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.
+> 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.
 
 
 
@@ -9,7 +9,7 @@
 <!-- source: en/plugins/storage.md -->
 ## Storage
 
-_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._
+_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._
 
 `@voltro/plugin-storage` is file storage behind one `StorageService`. Wire a
 provider in `app.config.ts`; consume it in handlers and actions via

package/templates/agent-docs/plugins.md

@@ -27,7 +27,7 @@ The framework ships some plugins; you write your own; the contract is small enou
 - [plugin-billing](/docs/plugins/billing) — subscriptions, plans, entitlements + usage metering (Stripe + mock provider); seat-based billing on Stripe's own proration, retries, tax and checkout; money as integer minor units
 - [plugin-licensing](/docs/plugins/licensing) — offline-verified EdDSA license keys + cloud-issued entitlement snapshots that feed plugin-billing; plan entitlements + pricing decided server-side, never baked into a published version
 - [plugin-mail](/docs/plugins/mail) — transactional email (Resend / Postmark / SendGrid / SES / Mailgun / SMTP, templates, suppression, scheduling, batch, idempotency)
-- [plugin-storage](/docs/plugins/storage) — file storage: public (CDN-direct) + private (access policy + per-object grants), S3 / R2 / GCS / MinIO / filesystem
+- [plugin-storage](/docs/plugins/storage) — file storage: public (CDN-direct) + private (access policy + per-object grants), S3 / MinIO (R2 and GCS via their S3 interop) / Azure / database / filesystem
 - [plugin-ai-flows](/docs/plugins/ai-flows) — durable multi-step AI pipelines (deterministic + agentic) with human-in-the-loop, chaining, and cadence; code-first `defineFlow` or data-driven rows
 - [plugin-postgis](/docs/plugins/postgis) — postgres-native `geography` / `geometry` columns + spatial operators
 - [plugin-broadcast](/docs/plugins/broadcast) — cross-replica reactivity over a pub/sub bus (Redis / NATS) for non-postgres dialects
@@ -42,10 +42,10 @@ The framework ships some plugins; you write your own; the contract is small enou
 - [plugin-logship](/docs/plugins/logship) — ship structured logs to Better Stack / Axiom / Loki / any HTTP sink; batched, redacted, fail-soft
 - [plugin-moderation](/docs/plugins/moderation) — moderate user content before commit: keyword or AI provider, block / flag via interceptor + in-handler redact
 - [plugin-search](/docs/plugins/search) — keep an external index (Typesense / Meilisearch / Algolia) in sync via the ChangeEvent tap; tenant-scoped `search.query` + hook
-- [plugin-cdc-out](/docs/plugins/cdc-out) — declarative reverse-ETL: mirror table changes outward to a webhook / Kafka / Snowflake / BigQuery sink through a durable outbox; ordered per pipe, at-least-once from enqueue, dead-lettered
+- [plugin-cdc-out](/docs/plugins/cdc-out) — declarative reverse-ETL: mirror table changes outward to a webhook sink (or any custom `CdcSink`) through a durable outbox; ordered per pipe, at-least-once from enqueue, dead-lettered
 - [plugin-governance](/docs/plugins/governance) — data governance: retention TTL sweep, GDPR export + erasure, consent ledger, field encryption
 - [plugin-openapi](/docs/plugins/openapi) — OpenAPI 3.1 spec + Swagger-UI docs generated from your `defineRestRoute` descriptors and (opt-in) rpc procedures
-- [plugin-versioning](/docs/plugins/versioning) — full row history + time-travel (`rowHistory` / `rowAsOf` / `restoreAsOf` / `diffVersions`); what-changed-to-what on every write
+- [plugin-row-history](/docs/plugins/row-history) — full row history + time-travel (`rowHistory` / `rowAsOf` / `restoreAsOf` / `diffVersions`); what-changed-to-what on every write
 - [plugin-presence](/docs/plugins/presence) — ephemeral realtime presence: heartbeat roster per channel + `usePresence` / `useTyping` hooks, held in memory; cross-instance with [plugin-broadcast](/docs/plugins/broadcast)
 - [plugin-auth-social](/docs/plugins/auth-social) — first-party Sign in with Google / GitHub / Apple: mandatory PKCE + state, JWKS-verified ID tokens, a deliberate account-linking policy, sessions issued through plugin-auth
 - [plugin-scim](/docs/plugins/scim) — SCIM 2.0 provisioning (Users + Groups at `/scim/v2`) so an enterprise IdP can create/deactivate users
@@ -70,7 +70,7 @@ Status legend: ✓ shipped · ◐ partial · — planned.
 | `@voltro/plugin-licensing` | ✓ | Offline-verified EdDSA license keys + cloud-issued entitlement snapshots that feed plugin-billing; plan entitlements + pricing decided server-side, never baked into a published version. [→ details](/docs/plugins/licensing) |
 | `@voltro/plugin-ai-flows` | ✓ | Durable multi-step AI pipelines — deterministic or agentic, with human-in-the-loop, chaining and cadence; author flows in code (`defineFlow`) or as data (visual-editor rows), one engine runs both. [→ details](/docs/plugins/ai-flows) |
 | `@voltro/plugin-mail` | ✓ | Transactional email — Resend / Postmark / SendGrid / SES / Mailgun / SMTP, *.email.tsx templates, per-tenant suppression, send-time scheduling, bulk/batch send, per-send idempotency, durable via workflows |
-| `@voltro/plugin-storage` | ✓ | File storage — public (CDN-direct) + private (access policy + per-object grants), S3 / R2 / GCS / MinIO / filesystem providers, presigned URLs, `listRefs` browse/search, HTTP Range (206) serving, dashboard browser |
+| `@voltro/plugin-storage` | ✓ | File storage — public (CDN-direct) + private (access policy + per-object grants), S3 / MinIO (R2 and GCS via their S3 interop) / Azure / database / filesystem providers, presigned URLs, `listRefs` browse/search, HTTP Range (206) serving, dashboard browser |
 | `@voltro/plugin-postgis` | ✓ | Postgres-native `geography` / `geometry` columns + spatial predicates (`ST_DWithin`, `ST_Contains`, `ST_Intersects`); GiST indexes via `.expressionIndex(..., { kind: 'gist' })`. No `ST_Distance` projection yet. Postgres-only by design (fails loud elsewhere). [→ details](/docs/plugins/postgis) |
 | `@voltro/plugin-broadcast` | ✓ | Cross-replica reactivity — fans out app-mutation change events to every replica over a pub/sub bus (Redis / NATS). Closes the single-instance gap for every non-postgres dialect. [→ details](/docs/plugins/broadcast) |
 | `@voltro/plugin-webhooks` | ✓ | Incoming + outgoing webhooks — `defineIncomingWebhook` (signature verify + idempotency, Stripe/GitHub/Slack presets) and `defineEvent` (durable delivery workflow, HMAC signing, retries, filters). [→ details](/docs/plugins/webhooks) |
@@ -91,10 +91,10 @@ Status legend: ✓ shipped · ◐ partial · — planned.
 | `@voltro/plugin-logship` | ✓ | Ship structured logs to Better Stack / Axiom / Loki / any HTTP sink — rides the log-sink hook, batched + redacted + fail-soft, trace-correlated. [→ details](/docs/plugins/logship) |
 | `@voltro/plugin-moderation` | ✓ | Content moderation — keyword denylist or AI provider (fails open), block (typed `ContentRejected`) / flag via rpc interceptor + in-handler `moderate()` redact helper. [→ details](/docs/plugins/moderation) |
 | `@voltro/plugin-search` | ✓ | External search index sync — rides the ChangeEvent tap to mirror tables into Typesense / Meilisearch / Algolia (memory default), tenant-scoped `search.query` action (facets · highlighting · fuzziness · range/negation filters · engine-param passthrough) + `useSearch` hook + `backfillIndex` + durable cross-replica sync stats. [→ details](/docs/plugins/search) |
-| `@voltro/plugin-cdc-out` | ◐ | Declarative reverse-ETL — 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. Engine + memory/webhook sinks shipped; warehouse connectors implement the `CdcSink` interface. |
+| `@voltro/plugin-cdc-out` | ◐ | Declarative reverse-ETL — 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. Engine + memory/webhook sinks shipped; anything else implements the `CdcSink` interface. |
 | `@voltro/plugin-governance` | ✓ | Data governance — retention TTL sweep (delete / anonymise), GDPR subject export + erasure (admin-gated routes + `GovernanceService`), consent ledger, field encryption. [→ details](/docs/plugins/governance) |
 | `@voltro/plugin-openapi` | ✓ | OpenAPI 3.1 spec (`GET /openapi.json`) + Swagger-UI (`GET /docs`) generated from `defineRestRoute` descriptors AND (opt-in) rpc procedures (queries/mutations/actions/streams → `POST /rpc/<name>`) — input/output/error Schemas via `JSONSchema.make`. [→ details](/docs/plugins/openapi) |
-| `@voltro/plugin-versioning` | ✓ | Full row history + time-travel — value snapshot of every insert/update/delete on listed tables into `_voltro_row_history` (rides the ChangeEvent tap); `rowHistory` / `rowAsOf` queries + `restoreAsOf` / `diffVersions`; TTL + per-row cap retention. [→ details](/docs/plugins/versioning) |
+| `@voltro/plugin-row-history` | ✓ | Full row history + time-travel — value snapshot of every insert/update/delete (every table by default; narrow with include/exclude) into `_voltro_row_history` (rides the ChangeEvent tap); `rowHistory` / `rowAsOf` queries + `restoreAsOf` / `diffVersions`; TTL + per-row cap retention. [→ details](/docs/plugins/row-history) |
 | `@voltro/plugin-presence` | ✓ | Ephemeral realtime presence — heartbeat roster per channel (`presence.heartbeat`/`list`/`leave` + `usePresence`), a `useTyping` typing indicator. Held **in memory**, owner-partitioned — no table is written; cross-instance requires [`@voltro/plugin-broadcast`](/docs/plugins/broadcast), and without a broker each replica sees only its own clients. [→ details](/docs/plugins/presence) |
 | `@voltro/plugin-scim` | ✓ | SCIM 2.0 provisioning — Users + Groups REST at `/scim/v2` (bearer-gated) incl. group-membership PATCH/PUT + the RFC 7644 discovery trio (ServiceProviderConfig/Schemas/ResourceTypes), `userName`/`externalId`/`displayName eq` filters, pagination, unique `userName`, `active:false` deactivation; `_voltro_scim_users`/`_voltro_scim_groups`. [→ details](/docs/plugins/scim) |
 | `@voltro/plugin-sso-saml` | ✓ | Enterprise SAML 2.0 SSO — SP-initiated login + Single Logout (both directions) + ACS + SP metadata under `/saml`; IdP-metadata-URL auto cert rotation, encrypted assertions, clock-skew, SP request signing. Signature verify via `@node-saml/node-saml` (optional+lazy), mints a framework session. [→ details](/docs/plugins/sso-saml) |
@@ -746,7 +746,7 @@ A package can ship BOTH a schema mixin AND a runtime plugin (`@voltro/plugin-aud
 
 ## More extension surfaces
 
-The plugin contract carries eight additional surfaces beyond the
+The plugin contract carries the additional surfaces below, beyond the
 interceptors + lifecycle + manifest fields covered above:
 
 ### `inspectEndpoints: PluginInspectEndpoint[]` — plugin-mounted HTTP endpoints
@@ -874,6 +874,17 @@ plugin-provided template is scaffolded exactly like a built-in one —
 `scaffoldFromTemplate` copies the declared tree and substitutes the
 `{{…}}` tokens in both file content AND file/directory names.
 
+### `httpRoutes: PluginHttpRoute[]` — raw HTTP endpoints on the framework listener
+
+A plugin can mount plain HTTP routes beside the rpc surface (`@voltro/plugin-storage`'s upload/download routes, an IdP callback). The request/response shape is transport-honest, and four properties are worth pinning:
+
+- **The full method union is first-class.** `method` is `'*' | 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'HEAD' | 'OPTIONS'`. **HEAD is admitted wherever GET is** (RFC 9110) — the GET handler runs and the transport drops the body; you never mount a second route for it. A wrong method stays a precise `405` with an `Allow:` header, including when several routes share one path.
+- **The body read is capped** — 8 MiB by default, the same cap as every other surface (`http.maxBodyBytes` in `app.config.ts`, env `VOLTRO_MAX_BODY_BYTES`), and the read is binary-clean. A route that takes more declares its own `maxBodyBytes`; routes **sharing a path share one body read**, so the widest override in the group applies to the group. Oversize answers `413` for both `Content-Length` and chunked requests.
+- **Binary streaming responses** return `byteStream` on the `PluginHttpRouteResult` — a `ReadableStream<Uint8Array>` (or lazy thunk) with optional `contentLength` / `contentDisposition`, piped without buffering and never compressed. It is the plugin-route spelling of the REST surface's [`bytes()`](/docs/data/rest-routes#binary-downloads--bytes).
+- **Buffered responses are compression-negotiated** (brotli/gzip, compressible types only) by the listener — nothing to declare; see [Security → compression](/docs/security/overview).
+
+A state-changing plugin route is origin-checked unless it declares `originGuard: 'exempt'`, and `req.remoteAddr` is the trusted-proxy-resolved client address — both covered with examples in [Security](/docs/security/overview#routes-that-a-third-party-legitimately-posts-to).
+
 ### `onHttpRequest: HttpRequestInterceptor` — pre-auth HTTP-pipeline hook
 
 Fires at the **very top** of every HTTP request — BEFORE auth resolution,
@@ -937,6 +948,17 @@ is deliberate: `GET /internal/liveness` and `GET /internal/readiness` are
 answered before the interceptor, so a rate-limit or geo-block plugin cannot 503
 a Kubernetes probe and take the replica out of rotation.
 
+**The chain is FAIL-CLOSED.** An interceptor that throws is a `500` plus a log
+line — the request does NOT continue. It used to: the failure was swallowed and
+the request flowed on, which meant a crashed security gate was an open one.
+That polarity puts a decision on every interceptor author: if your hook is a
+GATE (geo-block, bot detection), let a failure propagate — refusing is the
+correct degraded behaviour. If it is protection with a DEPENDENCY (a rate-limit
+counter in Redis), catch your own failure inside the hook and **degrade
+loudly** — `@voltro/plugin-ratelimit`'s `httpShield` does exactly that: a Redis
+outage means unlimited-with-a-warning, never a self-inflicted API outage.
+What no interceptor gets to do anymore is fail silently and stay in the chain.
+
 ### `extendSchema: { tables, migrations }` — contribute schema + migrations
 
 A plugin contributes BOTH declarative table descriptors AND custom SQL

package/templates/agent-docs/reference.md

@@ -581,6 +581,7 @@ Returns a function `(to: string, options?) => void`.
 |---|---|
 | `replace: true` | Replace the history entry (no back-button entry). |
 | `scroll: false` | Don't scroll to top after navigation. |
+| `transition: true / false` | Run (or suppress) this navigation's swap through `document.startViewTransition`, overriding the app-wide `router.viewTransitions` default. `<Link transition>` is the declarative mirror. See [View transitions](/docs/routing/navigation#view-transitions). |
 
 `navigate` takes a path string only — there is no numeric history overload. For back / forward, reach for the browser API:
 
@@ -607,12 +608,22 @@ Pass `true`/`false` or a predicate `({ to, opts }) => boolean` (to allow some de
 
 ## `useSearchParams()` + `useSetSearchParams()`
 
-Read the query string as a `URLSearchParams` (SSR-aware — the request URL on the server, `window.location.search` on the client):
+Read the query string. Two overloads, both SSR-aware (the request URL on the server, `window.location.search` on the client):
+
+- `useSearchParams()` — the raw `URLSearchParams`, for routes without a schema.
+- `useSearchParams(searchParams)` — pass the page's own `searchParams` schema export to get the decoded, typed shape. Defaults applied; an invalid query falls back to the defaults instead of crashing.
 
 ```tsx
+import { Schema } from 'effect'
 import { useSearchParams } from '@voltro/web'
 
-const tab = useSearchParams().get('tab') ?? 'overview'
+export const searchParams = Schema.Struct({
+  tab:  Schema.optionalWith(Schema.String, { default: () => 'overview' }),
+  page: Schema.optionalWith(Schema.NumberFromString, { default: () => 1 }),
+})
+
+const { tab, page } = useSearchParams(searchParams)   // tab: string · page: number
+const raw = useSearchParams()                         // URLSearchParams (schema-less routes)
 ```
 
 Write it with `useSetSearchParams()` — the setter updates the query via `navigate`, so readers re-render immediately:
@@ -628,6 +639,28 @@ setParams({ page: '2' }, { push: true })             // distinct history entry
 
 Writes default to a history replace; pass `{ push: true }` for a Back entry or `{ scroll: false }` to keep scroll. See [Navigation](/docs/routing/navigation#reading--writing-search-params).
 
+`useSetSearchParams(searchParams)` — pass the schema to get the **typed** setter. Object form replaces the query (a left-out field decodes to its default on the next read); the updater form receives the current **decoded** params, so a merge is an explicit spread:
+
+```tsx
+const setTyped = useSetSearchParams(searchParams)
+setTyped({ page: 2 })                          // replaces → ?page=2
+setTyped((p) => ({ ...p, page: p.page + 1 }))  // keeps every other param — typed merge
+```
+
+## Typed `withQuery()`
+
+Not a hook, but the link-side half of the same contract: for a route whose page exports a `searchParams` schema, the generated `routes` builder brands the URL with the schema's shape (through a type-only import — no page code enters the routes module), and `withQuery` type-checks the params against it — a misspelt key or a wrong value type is a compile error:
+
+```tsx
+import { withQuery } from '@voltro/web'
+import { routes } from './.framework/routes'
+
+withQuery(routes['/notes'](), { page: 2 })     // OK — typed against the schema
+// withQuery(routes['/notes'](), { pgae: 2 })  // compile error (unknown key)
+```
+
+The encode is canonical: strings pass through, numbers/booleans via `String()`, arrays as repeated keys, `undefined` omitted; a `Date` (or any object) is refused loudly — declare the field as a string/number transform in the schema instead. See [Navigation → typed `withQuery`](/docs/routing/navigation#typed-withquery).
+
 ## `usePrefetch()`
 
 Trigger loader-data prefetch on hover / focus. Wired automatically by `<Link prefetch />`; export only useful for custom triggers.
@@ -821,6 +854,10 @@ export default function SearchPage() {
 that must react to router-pushed query changes without a reload re-render through the router
 (`useNavigate`/`useLocation`); the hook then re-resolves on that render.
 
+Prefer the typed form where the page declares a `searchParams` schema export —
+`useSearchParams(searchParams)` returns the decoded shape instead of a raw
+`URLSearchParams`. See [Routing hooks](/docs/reference/hooks-routing#usesearchparams--usesetsearchparams).
+
 ## Reading cookies
 
 ```ts