@voltro/cli 0.51.0 → 0.53.0

package/templates/agent-docs/data.md

@@ -1103,6 +1103,40 @@ target: {
 
 `path`, `by`, `match`, and `shapeItem` are browser-safe descriptor data (a dot-path string + pure functions) — the same discipline as `identify`/`shape`.
 
+## Declared relations — a junction saved in the same mutation
+
+A form with a multi-reference field (assigned stores, tags, members) writes a
+JUNCTION table beside the row. Declare that on the write target and the
+framework reconciles the links INSIDE the mutation's transaction — no
+hand-written junction code in the executor, and a failure rolls the whole
+write back:
+
+```ts
+export const employeesUpdate = defineMutation({
+  name: 'employees.update',
+  input: EmployeesUpdateInput,   // carries assignedStores: string[]
+  output: Employee,
+  target: {
+    table: 'employees',
+    op: 'update',
+    relations: { assignedStores: 'employee_assigned_stores' },
+  },
+})
+```
+
+After the executor succeeds, `input.assignedStores` is reconciled against the
+junction via the diff-based link writer (`store.relationLinks`): missing rows
+inserted, surplus rows deleted, unchanged rows untouched — so reactive
+subscriptions on the junction see one change per changed row. The anchor
+column is derived from the junction's `reference()` targets; a self-junction
+(both columns referencing one table) is refused by name, never guessed.
+
+The semantics worth knowing: an ABSENT input field leaves the links
+untouched — absent is not empty; an empty array is the explicit "clear them
+all". The row id comes from the executor's `output.id`, falling back to
+`input.id`. The link writes go through `ctx.store`, so undo capture and
+cross-table rules see them like any other write.
+
 ## Typed Errors
 
 ```ts
@@ -2026,8 +2060,14 @@ Queries/subscriptions are for live state. Streams are for one-shot element flows
 ## Reconnect
 
 A dropped WebSocket rebuilds the whole client stack — new socket, new RPC
-client, new subscription cache — and re-subscribes every active query, each of
-which answers with a fresh snapshot.
+client, new subscription cache — and re-subscribes every active query. Inside
+the resume window (`reactive.resume.windowMs`, default 60 s) the server replays
+**only the deltas the client missed** — the re-subscribe presents the last
+materialised revision and the stream continues on the same revision line, so a
+short offline gap costs a handful of patches instead of every row. Outside the
+window, for computed queries, for row-filtered apps, or whenever anything is in
+doubt, the query answers with a fresh snapshot — the delta-resume wire contract
+lives in [the wire protocol](/docs/data/wire-protocol#reconnect--delta-resume).
 
 **What is on screen while that happens is your last-known-good data, not a
 skeleton.** The replacement cache is seeded from the one it retires, so `data`
@@ -2054,6 +2094,15 @@ Three things are deliberately NOT carried across:
 - **Entries nothing re-subscribes to.** A screen that unmounted during the
   reconnect does not pin its rows; the seed evicts on the normal inactive TTL.
 
+### The local-first mirror partitions by subject — the carve-out
+
+An app using `@voltro/local-first`'s query mirror keeps rows on the DEVICE
+across reloads. The blank-on-auth rule extends there structurally: every
+mirrored key carries the subject AND tenant, so the next subject's binding
+simply never finds the predecessor's rows, and a logout or membership
+revocation calls `purge()` on the departing partition. Nothing about the
+in-memory blanking above changes.
+
 ### An auth change still blanks — on purpose
 
 When the rebuild happens because the connection's *subject* changed — a cookie
@@ -2158,32 +2207,40 @@ once. Order BETWEEN subscribers was never guaranteed.
 There is a number, it is not a constant, and which number you get depends on a
 property of your **queries** rather than of your scale. Re-derive it on your own
 hardware with `node packages/runtime/scripts/fanout-ceiling.mjs`; the figures
-below are the spread across three runs on a busy developer machine at 10 matched
-writes per second, against a budget of 100 ms of event-loop time per second (10%
-of one core).
+below are the spread across three runs on a busy developer machine (12-core,
+macOS) at 10 matched writes per second, against a budget of 100 ms of
+event-loop time per second (10% of one core).
 
 | Subscriber population | Marginal CPU per subscriber | Subscribers per node |
 | --- | --- | --- |
-| **Shared** — N clients on the SAME query (a leaderboard, a shared board) | 0.5–0.9 µs | ≈ 11 000–20 000 |
-| **Distinct** — N clients each on their OWN query (`where userId = me`) | 22–29 µs | ≈ 350–450 |
-
-Ranges rather than single numbers, deliberately: that is the spread three runs
-produced, and a ceiling quoted to three significant figures from one run is a
-number somebody will hold you to.
-
-The shared case is cheap because the memoisation above applies: one read, one
-diff, N emits. The distinct case gets no sharing at all — the read, the diff and
-the emit are all per subscriber — and a per-user dashboard is exactly that shape.
-**Plan against the distinct number**, and note that it scales inversely with your
-write rate: at 1 matched write per second it is ten times higher.
-
-Two things that are easy to assume and are not true:
-
-- **A more selective `where` buys no headroom.** Measured: 200 of 200
-  subscribers whose predicate matched *nothing* were still woken by one write on
-  their table. Every subscription is a dependent of its own table, so a change
-  wakes all of them and each re-queries. The ceiling counts subscribers **on the
-  table**, not subscribers whose predicate matches.
+| **Shared** — N clients on the SAME query (a leaderboard, a shared board), every write matches all of them | 0.37–0.41 µs | ≈ 25 000–27 000 |
+| **Distinct** — N clients each on their OWN query (`where userId = me`), a write matches ONE | flat — per-write cost does not grow with resident subscribers | not set by subscriber count |
+
+The shared case fans out by design — one read and one diff (the memoisation
+above), then N emits — and it is the shape that sets the ceiling. The distinct
+case changed shape entirely with **matcher authority**: a subscription whose
+query is a plain predicate read is woken by the predicate index alone, so a
+write to *somebody else's* row is a non-event, not a wake. Per write it costs a
+bucket lookup plus one delivery, regardless of how many thousands of distinct
+subscribers are resident. Measured: **0 of 200** subscribers whose predicate
+matched nothing were woken by a write on their table — **a selective `where`
+buys real headroom** now.
+
+What still wakes conservatively (any change on the table), and deliberately —
+this list is exhaustive:
+
+- queries with an **eager `.with()` spec**, a setOp (`union`/…) or a CTE — the
+  handler reads rows the root predicate does not describe;
+- **`dependsOn`** raw reads (the dispatcher can only re-run the descriptor,
+  never the handler);
+- **computed** queries and **`reactivityChannel`** queries (their own
+  recompute paths, unchanged);
+- **oversized change events** (`tombstone` / `unrecovered` — row images the
+  matcher cannot see wake the whole table for that one event; `rehydrated`
+  events are judged normally).
+
+One thing that is easy to assume and is not true:
+
 - **It is not 512.** That constant bounds `onChange` LISTENERS — one per declared
   subscription file, reaction or aggregate, bound once at boot. Every client
   subscription in a process shares the dispatcher's single listener, so ten
@@ -2195,6 +2252,46 @@ mysql/mariadb (binlog), so a second node needs no extra wiring — the cost bein
 budgeted here is the matcher and re-query CPU each node spends on ITS OWN
 clients.
 
+### Deltas are per-query — two queries can briefly diverge
+
+Every subscription has its own revision line and its own delivery moment. After
+one write that affects two queries you hold open, the deltas arrive as two
+independent pushes — usually microseconds apart, but there is no cross-query
+transaction on the wire, and a render between the two pushes can see query A
+after the write and query B before it. Within ONE query you never see a partial
+write (a delta is computed from a committed row set); across queries, design for
+eventual agreement rather than instantaneous consistency — derive values that
+must agree atomically inside one query instead of joining two on the client.
+
+## Raw WebSocket gateways — `defineWebSocket`
+
+Everything above rides the framework's subscription protocol, and that stays the answer for app realtime — live queries, optimistic patches, reconnect. A **gateway** exists for the other case: a FOREIGN protocol that needs a socket the framework does not speak — a Yjs provider, a legacy device fleet, an MQTT-over-WS bridge. It mounts its own upgrade path beside the rpc socket, in a `*.ws.ts` file discovered on **both** boot paths:
+
+```ts
+// gateways/yjs.ws.ts
+import { defineWebSocket } from '@voltro/protocol'
+
+export default defineWebSocket({
+  path: '/gateways/yjs',
+  auth: 'subject',   // REQUIRED, no default: 'subject' | 'public'
+  onConnection: ({ send, close, onMessage, subject, headers, path }) => {
+    const doc = attachDoc(subject!.id)
+    onMessage((data) => doc.applyUpdate(data))     // binary-safe frames
+    const stop = doc.onUpdate((update) => send(update))
+    return () => { stop(); doc.release() }          // teardown
+  },
+})
+```
+
+The contract, in the order it protects you:
+
+- **`auth` is mandatory and has no default.** `'subject'` runs the SAME auth chain as rpc/SSR *before* the upgrade — an unauthenticated caller gets `401` while the request is still plain http, and the connection is bound to the credential's expiry: when it lapses, the socket closes with application code `4001`, so a foreign client can re-auth and reconnect. `'public'` is a deliberate, written-down decision (a device fleet with protocol-level auth of its own).
+- **Every gateway path is origin-checked at upgrade** — cross-origin means `403`, which closes cross-site WebSocket hijacking for your protocol exactly as for the framework's socket.
+- **`onConnection({ send, close, onMessage, subject, headers, path })`** may return a teardown function — it runs on client disconnect, on credential expiry, and on server shutdown, so whatever the handler opened cannot outlive the socket.
+- A plain GET on a gateway path answers `426 Upgrade Required`; two gateways declaring one path refuse the boot.
+
+**The boundary to keep:** if your own UI needs live data, that is a query + `useSubscription`, never a gateway. A gateway hands you raw frames and none of the subscription protocol's guarantees — reach for it only when the CLIENT dictates the protocol.
+
 ## See also
 
 - [Subscribers (`*.subscribe.ts`)](/docs/data/subscribers) — server-side, best-effort post-commit reactivity to a table (NOT the client hook on this page).
@@ -2940,6 +3037,44 @@ const requireApiKey: RestGuard = (ctx) =>
   ctx.subject.type === 'apiKey' ? undefined : { status: 401, message: 'API key required' }
 ```
 
+## Methods — PATCH, HEAD and OPTIONS are first-class
+
+`method:` accepts `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `HEAD` and `OPTIONS`, on REST routes and plugin HTTP routes alike. Two details:
+
+- **HEAD is admitted wherever GET is** (RFC 9110): a `HEAD` request runs the GET route's whole pipeline — method gate, guards, handler — and the transport drops the body. You never declare a second route for it.
+- **A wrong method is still a precise `405`**, with an `Allow:` header naming exactly the methods mounted on that path — including when several routes share one path.
+
+## Body limits — `maxBodyBytes`
+
+Every HTTP body read is capped at 8 MiB by default — `POST /rpc` (as it always was), plugin routes, REST routes and incoming webhooks. The app-wide cap is `http.maxBodyBytes` in `app.config.ts` (env override `VOLTRO_MAX_BODY_BYTES`); a route that legitimately takes more declares its own:
+
+```ts
+export default defineRestRoute({
+  method: 'POST',
+  path:   '/v1/import',
+  maxBodyBytes: 64 * 1024 * 1024,   // this route only — the app cap stays 8 MiB
+  // …
+})
+```
+
+The same per-route override exists on an incoming webhook's handler (`maxBodyBytes`) — fat provider payloads are the normal case there, not the exception. Two details:
+
+- **Routes that share one PATH share one body read.** The body is read once for the whole group, so the widest `maxBodyBytes` override in the group applies to the group.
+- An oversized body answers `413` whether it announces itself (`Content-Length`) or arrives chunked — the counter cuts it at the cap and never buffers past it.
+
+## Conditional GET — `etag: true`
+
+```ts
+export default defineRestRoute({
+  method: 'GET',
+  path:   '/v1/customers',
+  etag:   true,   // GET only — ignored elsewhere
+  // …
+})
+```
+
+The route stamps a **weak, content-derived** `ETag` (`W/"<sha-1 of the encoded output>"`) on every `200`, and answers a matching `If-None-Match` with `304 Not Modified` — the tag, no body. Weak on purpose: the transport may vary the BYTES per content-encoding, but the representation is the same. (`voltro start` does the equivalent for the web app's HTML on its own — `If-None-Match` answers `304` for buffered `200`s, with weak `W/"md5"` tags over the *uncompressed* body; `no-store` responses excepted.)
+
 ## Idempotency (`Idempotency-Key`)
 
 Set `idempotency: true` in `app.config.ts` and every mutating REST request (`POST`/`PUT`/`PATCH`/`DELETE`) that carries an `Idempotency-Key` header is deduplicated:
@@ -2970,6 +3105,56 @@ This is the Stripe-style contract — the **client** opts in by sending the head
 - **Inbound webhooks already dedup** via [`@voltro/plugin-webhooks`](/docs/plugins/webhooks) (provider key + `_voltro_webhook_*`) — don't double-cover them.
 - **Atomic claim, non-atomic completion.** Two concurrent same-key requests resolve to exactly one execution (the `UNIQUE(scope,key)` insert is the arbiter). But the cached response isn't committed in the handler's own transaction — a crash between the handler committing and the record flipping to `completed` leaves the key in-flight (a retry `409`s until the TTL lapses, then re-runs). REST handlers aren't auto-transactional, so this is the honest ceiling.
 
+## API versions — opt-in `version:` + the sunset flow
+
+A route that will evolve declares its version instead of baking it into the
+path; `version: 'v2'` mounts under `/v2/…`:
+
+```ts
+// v2 — the current shape
+export const listCustomers = defineRestRoute({
+  method: 'GET',
+  path: '/customers',
+  version: 'v2',
+  output: Schema.Struct({ data: Schema.Array(Customer), nextCursor: Schema.NullOr(Schema.String) }),
+  handler: async (_i, ctx) => ({ data: await ctx.store.query(customers), nextCursor: null }),
+})
+
+// v1 — still mounted, deprecated, and gone on a date
+export const listCustomersV1 = defineRestRoute({
+  method: 'GET',
+  path: '/customers',
+  version: 'v1',
+  deprecated: 'GET /v2/customers',   // Deprecation header + replacement pointer
+  sunset: '2027-03-01',              // Sunset header; 410 Gone from this date
+  output: Schema.Struct({ customers: Schema.Array(Customer) }),
+  handler: async (_i, ctx) => ({ customers: await ctx.store.query(customers) }),
+})
+```
+
+Two versions are **two descriptors** — the old one is ordinary code (visible,
+testable, deletable), not an entry in a transformation DSL. While it lives,
+responses carry `Deprecation: true` + `Sunset:`; past the date it answers
+`410 Gone` with `{ version: 'v1', replacement: 'GET /v2/customers' }`. Then
+you delete it. `version` is opt-in: a route without it keeps its literal path
+(no auto-prefix), and declaring `version:` on a path that already starts with
+`/vN/` is refused at definition — both spellings at once is never intended.
+`publicApi` projections version the same way (`spec.version`, default `v1`),
+and the OpenAPI doc groups each version's operations under a version tag with
+`x-voltro-api-version` — one document, the `/vN/` paths already separate them.
+
+**URI versioning only, on purpose.** Header- and media-type-versioning (the
+NestJS options) are not supported: the OpenAPI document, cache keys and plain
+`curl` are all path-shaped, and a version a URL cannot express is a version a
+cached response cannot vary on. If an edge must accept `Accept-Version:`
+headers, rewrite them to the path prefix at the proxy.
+
+**And the rpc socket is deliberately outside this.** The generated client is
+versioned with the server it was generated from — there is no `/v2` for
+`useMutation`. Honest edge: a browser tab that stayed open across your deploy
+runs the PREVIOUS client until reload; that skew window exists, it is small,
+and URL versioning would not remove it.
+
 ## Projecting an existing procedure — `publicApi`
 
 You often want to *offer* an API you don't consume from your own frontend. When the procedure already exists as a query / mutation / action, you don't need to rewrite it as a REST route — annotate it with `publicApi` and the framework mounts ONE HTTP route that runs the **same** handler, under the same guards:
@@ -3026,6 +3211,45 @@ Same guarantees as the WebSocket path, because it is the same code: the declarat
 
 For a hand-written `defineRestRoute`, the same machinery is available directly — return `sse((emit) => unsubscribe)` from the handler and frame events with `sseFrame(event, data)` (both from `@voltro/protocol/rest`).
 
+## Binary downloads — `bytes()`
+
+A handler that serves a file, an export or any non-JSON body returns `bytes(stream, options)` — imported beside `defineRestRoute` / `sse`:
+
+```ts
+import { defineRestRoute, bytes, requireScope } from '@voltro/protocol/rest'
+
+export default defineRestRoute({
+  method: 'GET',
+  path:   '/v1/exports/:id',
+  guards: [requireScope('exports:read')],
+  handler: async ({ params }, ctx) => {
+    const file = await locateExport(params.id)
+    // Lazy thunk form — the source is opened only when the response streams.
+    return bytes(() => openExportStream(file), {
+      contentType: 'application/zip',
+      contentLength: file.size,
+      contentDisposition: `attachment; filename="${file.name}"`,
+    })
+  },
+})
+```
+
+- The first argument is a web `ReadableStream<Uint8Array>` — or the **lazy thunk form** `() => ReadableStream`, which defers opening the source until the response actually streams.
+- The server **pipes without buffering** — a body larger than the heap is fine (the guarantee is exercised with a 256-MiB stream), and byte streams are **never compressed**.
+- Everything before the handler still runs — method gate, sunset, input decode, guards — so a streaming route is exactly as gated as a buffered one.
+- On a plugin HTTP route the same shape is `PluginHttpRouteResult.byteStream`.
+
+### Idempotency × streams — decided
+
+`streaming: true` on a method the idempotency binding claims (`POST`/`PUT`/`PATCH`/`DELETE`) is a **mount error**: a stream cannot cache a replayable body, so the idempotency claim could never complete — every retry would `409` until the TTL lapsed. The refusal names the two ways out: serve the stream on `GET`, or keep the idempotency binding away from the app's streaming routes. A handler that returns a stream *without* declaring `streaming: true` is caught at runtime instead — the claim is **released** so a retry re-processes.
+
+## No multipart parser — a declared boundary
+
+There is **no multipart parser** on REST or webhook routes — `multipart/form-data` against `/form/*` answers `415`, and a REST handler never sees parsed file parts. That boundary is deliberate, and this list of alternatives is complete:
+
+- **File uploads** ride [`@voltro/plugin-storage`](/docs/plugins/storage)'s upload routes — a binary PUT plus a resumable, chunked upload with signed tickets. That is the sanctioned file path, not a workaround.
+- **A provider that delivers webhooks as multipart** (the Mailgun-inbound class) needs, today, either a small parser proxy in front of the endpoint or the provider's JSON delivery mode where it offers one.
+
 ## REST route vs Action
 
 Both are unary request/response. Pick by transport + audience:
@@ -4464,7 +4688,7 @@ rather than letting whichever loaded last silently win.
 ## Retries, backoff, dead-letter
 
 | | |
-|---|---|
+| --- | --- |
 | Retry schedule | exponential — 1s, 2s, 4s … capped at 5 minutes |
 | Default attempts | 8 (`maxAttempts` on the handler, or per-enqueue) |
 | Exhausted | row moves to `dead`, logged at ERROR, stays in the table |
@@ -4530,7 +4754,7 @@ delivery-history screen renders. So every attempt appends a row to
 `_voltro_outbox_attempts`:
 
 | column | |
-|---|---|
+| --- | --- |
 | `outboxId` | the entry this attempt belongs to |
 | `effect` | denormalised — the history stays readable after the entry is purged |
 | `attempt` | 1-indexed, monotonic across the entry's whole life |
@@ -4626,6 +4850,20 @@ bound.
 - **Mirroring a table outward continuously** → `@voltro/plugin-cdc-out`, which
   is built for reverse-ETL with per-pipe ordering.
 
+## There is no generic job queue — take X for Y
+
+Voltro deliberately ships no `defineJob` primitive (priorities, worker pools, a
+BullMQ equivalent). The outbox, [workflows](/docs/workflows/overview) and
+[schedules](/docs/scheduling/overview) cover the cases between them, and a third
+durability primitive would drift from both. What to reach for instead:
+
+| you want… | take |
+| --- | --- |
+| a concurrency-limited worker pool | workflows + [declarative flow control](/docs/workflows/declarative-flow-control) — `concurrency` / `throttle` bound how many runs execute at once |
+| true priority scheduling (high-priority work overtakes queued low-priority work) | does not exist as a primitive — a workflow draining **your own queue table** in your priority order is the honest build |
+| a delayed / scheduled message | `delayMs` on `enqueue` (above) for a one-off delayed effect; a [schedule](/docs/scheduling/overview) for recurring time-based work; workflow [`sleep`](/docs/workflows/sleep) for a pause inside a durable process |
+| exactly-once delivery | does not exist — delivery is at-least-once everywhere, which is the strongest guarantee available without a distributed transaction into the target; **idempotent handlers are mandatory** (see above) |
+
 ## See also
 
 - [Mutations](/docs/data/mutations) — the transaction boundary this rides
@@ -4684,7 +4922,7 @@ A streaming query (what `useSubscription` opens) emits a sequence of **subscript
 { _tag: 'error', error: { _tag?: string, message: string, ...fields }, revision?: number }
 ```
 
-- **`revision`** — monotonically increasing; lets the client order events and detect gaps.
+- **`revision`** — monotonically increasing; lets the client order events. **Revisions may JUMP forward** — under socket backpressure the server coalesces updates a slow consumer hasn't read yet into one event whose patch is computed against the row set of the last event it actually handed over, so patch continuity holds across the jump. A jump is therefore normal, never a gap; only a *regressing* or repeating revision would be a protocol violation.
 - **`emittedAt`** — epoch milliseconds, present on `delta` only.
 - **`data`** (snapshot) — the full payload, typed by the query's `output` schema (a row, an array of rows, a computed value — whatever the handler returns).
 - **`patch`** (delta) — an id-keyed RFC-6902-style patch against the row set the client last held.
@@ -4703,6 +4941,70 @@ propagate to the shared connection and stall every *other* subscription on it
 client surfaces it as `useSubscription(...).error` for that one query key;
 siblings keep delivering their snapshots and deltas.
 
+### Slow consumers — coalescing and `SubscriptionOverrun`
+
+A consumer that stops reading (a backgrounded tab, a saturated link) does not
+grow the server without bound. While its socket is blocked, updates
+**coalesce**: the server keeps only the newest state per subscription and, when
+the socket accepts again, sends ONE event — a patch against the last state the
+consumer was actually handed (`revision` jumps accordingly, see above). Memory
+per blocked subscription is bounded by construction: one pending state,
+regardless of how far behind the consumer is.
+
+A consumer that stays more than `reactive.socket.maxBufferedBytes` (default
+1 MiB, env `VOLTRO_REACTIVE_MAX_BUFFERED_BYTES`) behind for
+`reactive.socket.overrunAfterMs` (default 10 s) is closed **loudly**: it
+receives an `error` event with `error._tag: 'SubscriptionOverrun'` (carrying
+`bufferedBytes` + `maxBufferedBytes`) and the stream ends — never a silent
+drop. The client re-subscribes and starts from a fresh snapshot.
+
+Oversized events are telemetry, not a cap: an event over
+`reactive.socket.oversizedEventBytes` (default 256 KiB) is delivered normally
+and counted (`voltro_subscription_oversized_total`) with a WARN naming the
+query — alongside `voltro_subscription_buffered_bytes`,
+`voltro_subscription_coalesced_total` and `voltro_subscription_overrun_total`
+in the Prometheus exporter and the inspect Metrics panel.
+
+### Reconnect — delta-resume
+
+A client that reconnects inside the **resume window** does not have to pay for
+a full snapshot: it sends the last `revision` it materialised in the per-call
+`voltro-resume-from` request header (the same header surface the idempotency
+key rides), and the server — which kept the subscription alive server-side for
+the window after the disconnect — **replays only the deltas that were missed**
+and re-attaches the stream on the SAME revision line.
+
+The signal is the first event's tag, not a schema field:
+
+- **first event `delta`** — the resume was honoured; apply the patch onto the
+  rows you already hold and continue.
+- **first event `snapshot`** — the resume was declined; reset to the snapshot.
+  This is the answer whenever anything is in doubt, because a wrong snapshot
+  costs bytes while a wrong replay would leak rows.
+
+`@voltro/client` does both automatically — the reconnect-seeded cache keeps its
+rows and revision, presents the header, and treats a snapshot-first stream as
+the reset it already knows how to do. Replayed deltas may **coalesce** exactly
+as slow-consumer updates do (revisions jump; patch continuity holds).
+
+A resume is declined — always with a fresh snapshot — when:
+
+- the window expired (`reactive.resume.windowMs`, default 60 s, env
+  `VOLTRO_REACTIVE_RESUME_WINDOW_MS`), or more deltas were missed than the ring
+  retains (`reactive.resume.maxDeltas`, default 256, env
+  `VOLTRO_REACTIVE_RESUME_MAX_DELTAS`);
+- the query's `guards:` were revoked while the client was away — the
+  per-delivery re-check keeps running on the detached subscription, and a
+  revocation drops the retained history outright;
+- the resuming caller is a different subject or tenant (a login, logout or
+  tenant switch between disconnect and resume) — the retained history is keyed
+  by subject AND tenant, so a changed identity simply never finds it;
+- the app registers a row filter (`setRowFilter`), or the query is a
+  **computed** query — both are excluded from resume by design: a row-filtered
+  subscription's visible row set exists only per delivery, and a computed query
+  re-runs a handler with no delta chain to replay. They reconnect with a fresh
+  snapshot, exactly as before.
+
 **Author a live-subscribed getter to return, not throw.** A subscription is a
 long-lived stream, so a getter that throws on every re-evaluation is a broken
 stream. For an expected-absent row, make the query `output: Schema.NullOr(...)`
@@ -5035,6 +5337,203 @@ try {
 
 
 
+---
+
+<!-- source: en/data/content-collections.md -->
+## Content collections
+
+_File-based, schema-typed markdown content — defineCollection over content/<name>/**/*.md, an isomorphic getCollection/getEntry, locale trees with fallback, headings for TOCs, data collections, references, and RSS feeds — without installing a markdown dependency._
+
+A content collection turns a folder of markdown files into typed, rendered
+content: you declare the frontmatter schema in code, and `getCollection()` /
+`getEntry()` hand you decoded data plus server-rendered HTML with
+syntax-highlighted code fences. The markdown engine lives in the framework —
+**do not install your own `marked` / `remark` / `shiki`**; a second pipeline
+drifts from the one your artifacts, feeds and templates already use.
+
+## A blog in 20 lines
+
+One collection file, one markdown file, one page:
+
+```ts
+// src/collections/posts.collection.ts
+import { Schema } from 'effect'
+import { defineCollection } from '@voltro/content'
+
+export const posts = defineCollection({
+  name: 'posts',
+  directory: 'content/posts',
+  schema: Schema.Struct({ title: Schema.String, date: Schema.String }),
+})
+export type Post = Schema.Schema.Type<typeof posts.schema>
+```
+
+```ts
+// src/pages/blog/[slug]/page.tsx
+import { getCollection, getEntry, type ContentEntry } from '@voltro/content'
+import { useLoaderData } from '@voltro/web'
+import { posts, type Post } from '../../../collections/posts.collection'
+
+export const renderMode = 'static' as const
+export const getStaticPaths = async () =>
+  (await getCollection(posts.name)).map((e) => ({ params: { slug: e.slug } }))
+export const loader = async ({ params }: { params: { slug: string } }) =>
+  await getEntry<Post>(posts.name, params.slug)
+
+export default function Post() {
+  const post = useLoaderData<ContentEntry<Post> | null>()
+  if (!post) return <main>Not found</main>
+  return <article dangerouslySetInnerHTML={{ __html: post.html ?? '' }} />
+}
+```
+
+Drop `content/posts/hello.md` with `title:` + `date:` frontmatter and the
+build pre-renders `/blog/hello` — highlighted code fences included.
+
+## How it stays out of your bundle
+
+The loader is **isomorphic**. At build/SSR time it reads the filesystem and
+renders markdown (shiki runs on the server only). The build also emits JSON
+artifacts under `dist/assets/content/<name>[.<locale>]/…` — an index (slugs +
+frontmatter, no bodies) and one file per entry (rendered HTML + headings). On
+an SPA navigation, the CLIENT branch of `getCollection`/`getEntry` fetches
+those artifacts. The result: no markdown engine, no highlighter, and no
+content bodies in your JavaScript bundle. `voltro dev` serves the same
+artifact shapes on demand and invalidates them when a `content/**` file
+changes.
+
+## Frontmatter is a schema, and violations fail the build
+
+The `schema` is an `effect/Schema` struct decoded per file. A missing or
+mistyped field is a **build error naming the file** — not a page that renders
+`undefined`. Numbers in frontmatter arrive as strings; use
+`Schema.Union(Schema.NumberFromString, Schema.Number)` for numeric fields.
+`getCollection<A>` returns entries whose `data` is the schema's inferred
+type — no casts.
+
+## Slugs come from the path
+
+`content/posts/hello.md` → `hello`; nested folders stay in the slug
+(`database/joins.md` → `database/joins`). Two files resolving to one slug
+(a rename that left both) is a build error.
+
+## Locale trees + fallback
+
+A collection with `i18n` treats the first path segment as the locale:
+
+```ts
+export const docs = defineCollection({
+  name: 'docs',
+  directory: 'content/docs',
+  schema: Schema.Struct({ title: Schema.String }),
+  i18n: { locales: ['en', 'de'], defaultLocale: 'en', missing: 'fallback' },
+})
+```
+
+`getCollection('docs', { locale: 'de' })` reads the `de/` tree. A slug missing
+in the requested locale is served from the default tree with
+`fallback: true` on the entry (render an "untranslated" banner off it) — or
+omitted entirely with `missing: 'missing'`. Incomplete translations are the
+normal case; decide the policy per collection instead of improvising per page.
+
+## Headings as data
+
+Every rendered entry carries `headings: [{ depth, slug, text }]` — the TOC
+input. The slugs are the SAME ids stamped on the rendered `<h2 id="…">`
+elements, so sidebar anchors never drift from the body. For a TOC without a
+render pass, `extractHeadings(markdown)` (from `@voltro/content/markdown`)
+computes the same data synchronously.
+
+## Data collections
+
+`kind: 'data'` reads `.json` files instead of markdown — the `authors.json`
+case. Each file decodes whole against the schema; there is no render path:
+
+```ts
+export const authors = defineCollection({
+  name: 'authors',
+  directory: 'content/authors',
+  kind: 'data',
+  schema: Schema.Struct({ name: Schema.String, url: Schema.String }),
+})
+```
+
+## References between collections
+
+`reference('<collection>')` declares a frontmatter field that names an entry
+of another collection by slug:
+
+```ts
+schema: Schema.Struct({
+  title: Schema.String,
+  author: reference('authors'),
+})
+```
+
+The build validates every reference — a dangling one (`author: nobody`) fails
+the build naming the collection, entry, field and target. Resolve it with
+`getEntry('authors', entry.data.author)`.
+
+## RSS feeds from a collection
+
+Declare feeds in `app.config.ts`; the build writes them next to
+`sitemap.xml`, and `voltro dev` serves the same XML live:
+
+```ts
+export default {
+  // …
+  seo: { siteUrl: 'https://example.com' },
+  feeds: [{
+    path: '/rss.xml',
+    collection: 'posts',
+    title: 'My blog',
+    item: (e) => e.data.draft === 'true' ? null : ({
+      title: e.data.title, link: `/blog/${e.slug}`, date: e.data.date,
+    }),
+  }],
+}
+```
+
+Returning `null` from `item` excludes an entry — that is the **draft filter**:
+keep a `draft: true` field in your schema and filter it in `item` and in your
+page loaders (the changelog template's `visibleReleases` helper is the worked
+example, including future-dated staging).
+
+## No MDX — islands carry the interactivity
+
+Collection bodies are **markdown, not MDX**: JSX, `import`s and
+`{expressions}` in a body are not executed. When a content page needs a live
+widget, the surrounding PAGE provides it via the islands mechanism — the
+content stays inert HTML and the widget hydrates alone:
+
+```tsx
+// src/pages/blog/[slug]/page.tsx
+export const interactive = 'islands' as const
+
+export default function Post() {
+  const post = useLoaderData<ContentEntry<Post>>()
+  return (
+    <main>
+      <ReadingProgress />  {/* an island() component — the ONLY hydrated JS */}
+      <article dangerouslySetInnerHTML={{ __html: post.html ?? '' }} />
+    </main>
+  )
+}
+```
+
+## Limits + neighbors
+
+- **Images referenced from markdown bodies** are copied as-is (no transform):
+  the [image pipeline](/docs/routing/assets) covers `?image` imports from
+  code. Put content images under `public/` and reference them absolutely.
+- **Files are DEVELOPER content** — versioned with the code, deployed by the
+  build. Editorial content with drafts, roles and a save/publish pipeline is
+  [`@voltro/cms`](/docs/data/cms). Astro's remote "Content Layer loaders"
+  map to `@voltro/cms` here: remote/editorial sources go through the CMS,
+  not through file collections.
+
+
+
 ---
 
 <!-- source: en/data/cms.md -->
@@ -5183,6 +5682,38 @@ const program = Effect.gen(function* () {
 )
 ```
 
+### ISR revalidation on publish
+
+A content type can declare which ISR routes fall when its content is
+published or unpublished — `publish()`/`unpublish()` fire
+[`revalidatePath` / `revalidateTag`](/docs/routing/render-modes#on-demand-revalidation)
+for each entry after the write commits, reaching every `voltro start`
+replica:
+
+```ts
+import { defineContentType, Schema } from '@voltro/cms'
+
+const blogPost = defineContentType({
+  name: 'blogPost',
+  displayName: 'Blog post',
+  pluralName: 'Blog posts',
+  fields: {
+    title: Schema.String.pipe(Schema.maxLength(200)),
+    body:  Schema.RichText({ allowImages: true, allowEmbeds: false }),
+  },
+  revalidate: {
+    paths: ['/blog/[slug]', '/blog'],
+    tags: ['blog'],
+  },
+})
+```
+
+You don't need this on postgres for the plain publish case: a route declaring
+`cacheInvalidatesOn: ['blogPost_published']` is already dropped by CDC when
+the published table changes. Declare `revalidate` for what CDC can't see —
+non-postgres dialects, routes whose loaders read the content indirectly, or
+tag fanout across several routes.
+
 ## The engine, standalone
 
 The validation/derivation engine is pure and exported on its own (also on
@@ -5269,15 +5800,16 @@ list; `mediaFields(type)` lists the top-level media field names.
 ## Versioning content
 
 `@voltro/cms` ships no parallel revision system — the derived tables are
-ordinary database tables, so `@voltro/plugin-versioning` gives full row history
-+ time-travel with no new machinery. List the derived table names in the
-plugin's `tables` option, then read a timeline or restore a snapshot:
+ordinary database tables, so `@voltro/plugin-row-history` gives full row history
+plus time-travel with no new machinery. The plugin records every table by default —
+narrow it with `include:` (pass the derived table handles) or `exclude:` if you
+only want content history — then read a timeline or restore a snapshot:
 
 ```ts no-check
-import { versioningPlugin, rowHistory, restoreAsOf } from '@voltro/plugin-versioning'
+import { rowHistoryPlugin, rowHistory, restoreAsOf } from '@voltro/plugin-row-history'
 
 // Register in your app's plugin list:
-versioningPlugin({})
+rowHistoryPlugin({})
 
 const timeline = await rowHistory(ctx.store, 'blogPost_published', postId, tenantId)
 await restoreAsOf(ctx.store, 'blogPost_published', postId, tenantId, someEarlierDate)
@@ -5542,3 +6074,118 @@ app's public origin comes from `VOLTRO_PUBLIC_URL`.
   a secret, not a connection.
 - **`redirectTo` is a same-origin path only.** An absolute URL is rejected —
   otherwise every app declaring a connection would ship an open redirector.
+
+
+
+---
+
+<!-- source: en/data/grpc.md -->
+## gRPC surface
+
+_Serve opt-in procedures to generated gRPC clients — proto emitted from your effect/Schema with checked-in field-number stability, unary for mutations/actions, server-streaming for live queries, guards + interceptors + typed errors identical to the socket._
+
+The gRPC surface serves a NAMED list of your procedures to external gRPC
+clients — the polyglot-microservice door. The `.proto` is generated from the
+same `effect/Schema` your procedures already declare, so there is no second
+contract to maintain; the wire semantics are the framework's own: guards,
+plugin interceptors and typed errors behave **identically** to the rpc
+socket, because a gRPC call runs the *same bound runner* every other surface
+uses (the e2e proves interceptor order side by side).
+
+```ts
+// app.config.ts
+export default {
+  type: 'api' as const,
+  name: 'api',
+  grpc: {
+    port: 50051,
+    procedures: ['orders.get', 'orders.list', 'orders.create'],
+    // tls: { certPath, keyPath, caPath? } — plaintext without it (dev / mesh).
+  },
+}
+```
+
+NOTHING is exposed by default — every tag is named. Booting writes
+`.framework/grpc.proto` (hand it to any proto codegen) and mounts
+`grpc.health.v1` health checking plus server reflection (`grpcurl … list`
+works out of the box). The gRPC packages ship as script-free optional
+dependencies of `@voltro/cli`; a configured `grpc:` block with them missing
+refuses the boot by name.
+
+## Field numbers are managed — `grpc.manifest.json`
+
+Field numbers are the proto wire identity, so they may never depend on
+property order. They come from a checked-in manifest in your app root:
+
+- a **new** field gets the next never-used number — an **inserted** field
+  never renumbers its neighbours;
+- a **deleted** field's number becomes `reserved` (emitted into the proto,
+  so `protoc` refuses a colliding hand-edit too);
+- **reusing** a reserved number is a codegen error, never a warning — an old
+  client would silently read the wrong field.
+
+Commit the manifest with the schema change that moved it: the diff review IS
+the wire-contract review.
+
+## The mapping table
+
+| Schema | proto3 |
+|---|---|
+| `Schema.String` / `Number` / `Boolean` | `string` / `double` / `bool` |
+| integer schemas | `int64` |
+| `Schema.Array(T)` | `repeated T` |
+| nested `Schema.Struct` | nested message |
+| `Schema.Record({ key: String, value: T })` | `map<string, T>` |
+| `Schema.optional(T)` **and** `Schema.NullOr(T)` | `optional T` — absent and `null` are ONE wire state (proto3 presence) |
+| string-literal unions | `string` (validated server-side on decode) |
+| unions of shapes, tuples, recursion, free-form objects | a LOUD per-procedure codegen error naming the schema path |
+
+Requests are decoded against the descriptor's input schema before the
+executor runs — proto3 suppresses default values on the wire, and without
+that decode an empty string would arrive as an absent field and fail
+somewhere much later.
+
+## Status codes — complete against the wire error union
+
+| outcome | gRPC status | trailers |
+|---|---|---|
+| no credential on a guarded call | `UNAUTHENTICATED` | |
+| presented-and-rejected credential | `UNAUTHENTICATED` | |
+| authenticated, missing scope (`ScopeError`) | `PERMISSION_DENIED` | `voltro-error: scope` |
+| input fails the schema | `INVALID_ARGUMENT` | `voltro-error: input` |
+| `BusinessRuleViolation` | `FAILED_PRECONDITION` | `voltro-error: rule` |
+| `requiresApproval` pending — a FLOW OUTCOME, not a failure | `FAILED_PRECONDITION` | `voltro-pending: approval` + `voltro-approval-id` |
+| your declared typed error | `FAILED_PRECONDITION` | `voltro-error: <tag>` |
+| deadline exceeded | `DEADLINE_EXCEEDED` | |
+| anything else | `INTERNAL` | |
+
+**Deadlines interrupt the work.** A client deadline (`grpc-timeout`) aborts
+the executor's fiber through the request signal — the server stops doing the
+work, it does not merely suppress the response (the e2e pins this with a
+sleeping action whose post-sleep write never lands).
+
+## Streaming queries
+
+A `query` becomes a **server-streaming** rpc: each frame is the CURRENT full
+snapshot, re-pushed live when the query's `source:` changes — subscribe,
+mutate from anywhere, and the open stream receives the new frame with no
+re-request. The per-delivery guard re-check applies (a revoked scope ends
+the stream with the mapped status), and slow consumers are handled through
+grpc-js write backpressure — frames coalesce to the latest snapshot rather
+than buffering unboundedly.
+
+## Declared limits (v1)
+
+- **No client- or bidi-streaming**, and `*.stream.ts` procedures are NOT
+  exposable — the fourth kind is a one-shot element stream with its own
+  semantics; put it behind a query or keep it on the socket.
+- **No gRPC-Web** — a browser talks the framework's own subscription
+  protocol (that is the better browser transport in every dimension we care
+  about); gRPC is for backends.
+- **No Connect protocol** — connectrpc is NOT gRPC-Web; a connect consumer's
+  alternative today is the [REST/OpenAPI projection](/docs/data/rest-routes).
+- App realtime stays on the framework's subscription protocol, and gateways
+  exist for the other case: a FOREIGN protocol that needs a socket the
+  framework does not speak — the same boundary
+  [data/subscriptions](/docs/data/subscriptions) draws for raw WebSocket
+  gateways, one sentence, two doors.