@voltro/cli 0.52.0 → 0.54.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
@@ -1683,7 +1717,7 @@ created by every migration and diffed on every boot.
 
 The other tempting option is to point `source:` at a name that resolves to
 nothing. That is worse than the empty table: the [stale-`source` boot
-warning](#fan-out--how-many-subscribers-may-one-change-wake) is the only signal
+warning](#fan-out-how-many-subscribers-may-one-change-wake) is the only signal
 for a subscription that has gone permanently quiet, and an exemption for a name
 you invented disables it for the one case it was built for.
 
@@ -1813,7 +1847,7 @@ Two consequences worth knowing:
 - **Not free per subscriber.** A publish wakes every subscriber of that channel
   and re-runs each one's executor; the channel is one routing key, so
   subscribers looking at different slices of the state are woken too. Publish on
-  a real change, not on a timer — see [Fan-out](#fan-out--how-many-subscribers-may-one-change-wake).
+  a real change, not on a timer — see [Fan-out](#fan-out-how-many-subscribers-may-one-change-wake).
 
 ## Query Executor
 
@@ -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
@@ -2123,6 +2172,15 @@ subscriber on every delivery, on purpose — a role revoked or a share withdrawn
 to end the stream on the very NEXT delivery, not whenever a cache happens to
 expire — and each of them can be a database round-trip.
 
+**On every transport.** A live query can leave the server three ways — the
+WebSocket the browser client uses, an [SSE
+stream](/docs/data/rest-routes#live-updates-over-http-stream-sse), and a
+[gRPC](/docs/data/grpc) server-streaming rpc — and all three resolve per
+delivery through the same code: guards re-checked before each frame, row
+visibility re-derived from the unfiltered base descriptor for each frame, and a
+revoked scope ending the stream. The transport decides how the frame is
+framed, never what the subject may see.
+
 So deliveries run **concurrently, up to a bound**. The default is 8 in flight.
 Measured with 50 subscribers behind a 5 ms guard: 517 ms to serve all of them
 serially, 72 ms at 8 lanes.
@@ -2158,32 +2216,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 +2261,17 @@ 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:
@@ -3137,7 +3214,9 @@ es.addEventListener('delta',    (e) => applyDelta(JSON.parse(e.data)))
 
 Each event's `_tag` becomes the SSE `event:` name, so a client listens per kind instead of switching on a payload field. The framing handles the details that bite otherwise: embedded newlines are split across `data:` lines (a raw `\n` would truncate the event), a `retry:` hint is sent, and a keep-alive comment goes out every 15s so proxies don't drop an idle stream.
 
-Same guarantees as the WebSocket path, because it is the same code: the declarative `guards:`, the row filter and tenant scoping all run before anything is emitted, and the client's disconnect tears the subscription down (including a disconnect *during* setup). A guard denial arrives as one `error` event rather than an HTTP status — by then the response headers are already sent.
+Same guarantees as the WebSocket path, because it is the same code: the declarative `guards:`, the [row filter](/docs/authentication/row-level-security) and tenant scoping all run before anything is emitted, and the client's disconnect tears the subscription down (including a disconnect *during* setup). A guard denial arrives as one `error` event rather than an HTTP status — by then the response headers are already sent.
+
+And they run before **every** event, not only before the first one: the guards are re-checked and the subject's row visibility is re-resolved from the unfiltered base descriptor per delivery, so a scope revoked while the `EventSource` is open ends the stream on the next event, and a membership that ends stops carrying those rows in the next `delta`. An open SSE stream is not a cheaper read path than a fresh `GET`.
 
 `stream: 'sse'` on a mutation or action is ignored: there is nothing to subscribe to.
 
@@ -4854,7 +4933,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.
@@ -4873,6 +4952,82 @@ 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 query is a **computed** query — it re-runs a handler, so there is no
+  delta chain to replay;
+- a registered row filter (`setRowFilter`) can narrow THIS subscription's
+  source table, or the query declares an eager `.with(...)`. A row-filtered
+  subscription's visible row set exists only per delivery, so replaying it
+  could serve rows the subject has since lost.
+
+  **This is per table, not per app.** A filter that declares
+  `tables: [...]` (see [row-level security](/docs/authentication/row-level-security))
+  keeps delta-resume on every subscription whose source is not in that set —
+  the common case, since most filters narrow a handful of tables. Without the
+  declaration the framework cannot know which tables the predicate may reach
+  and excludes them all, which is what a deployment measured as one filter over
+  4 tables costing the feature on all 173 of their queries. Eager loads are
+  excluded wholesale because a relation resolves below the seam that narrows.
+  They reconnect with a fresh
+  snapshot, exactly as before.
+
 **Author a live-subscribed getter to return, not throw.** A subscription is a
 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(...)`
@@ -5205,6 +5360,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 -->
@@ -5745,3 +6097,144 @@ 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).
+    // drainMs: 5000,        // shutdown drain budget — see below
+    // maxMessageBytes, maxMetadataBytes — grpc-js frame limits
+  },
+}
+```
+
+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.
+
+## Shutdown drains, then forces — `drainMs`
+
+On SIGTERM the surface flips its health status to `NOT_SERVING` (so a load
+balancer stops sending it work) and gives open calls **`drainMs`** to finish
+before force-closing them. Default `5000`; `0` forces immediately; the env
+override is `VOLTRO_GRPC_DRAIN_MS`.
+
+Pick it from two numbers only you have. Keep it **below** your orchestrator's
+termination grace (`terminationGracePeriodSeconds`, `docker stop -t`) — past
+that point SIGKILL arrives and the drain never completes, so a larger budget
+buys nothing. Keep it **above** your longest legitimately in-flight unary
+call, or every rolling deploy force-closes work that would have finished. When
+the budget is exceeded the surface says so in a warning naming the budget,
+rather than leaking the port into the next boot.
+
+## Field numbers are managed — `grpc.manifest.json`
+
+Field numbers are the proto wire identity, so they may never depend on
+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.
+
+**Authorization is re-derived per FRAME, not frozen at open.** Before every
+delivery the framework re-runs the query's `guards:` and re-resolves the
+subject's [row-level visibility](/docs/authentication/row-level-security)
+from the unfiltered base descriptor. A revoked scope ends the stream with the
+mapped status; a membership that ends mid-stream stops carrying those rows in
+the next frame, with the stream itself untouched. This is the same code the
+WebSocket and SSE transports run — an open gRPC stream is not a cheaper read
+path than a fresh call.
+
+Slow consumers are handled through grpc-js write backpressure — frames
+coalesce to the latest snapshot rather than buffering unboundedly.
+
+## Declared limits (v1)
+
+- **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.