@voltro/cli 0.33.0 → 0.34.0

package/templates/agent-docs/data.md

@@ -168,6 +168,7 @@ import { Schema } from 'effect'
 export const listNotes = defineQuery({
   name:   'notes.list',
   source: 'notes',
+  guards: [{ scope: 'notes:read' }],
   input:  Schema.Struct({}),
   output: Schema.Array(Schema.Struct({
     id:    Schema.String,
@@ -188,6 +189,13 @@ export default () =>
 
 Save both files and `notes.list` becomes a streaming query in the typed client.
 
+> **`guards:` is not decoration here — it is what makes the file boot.** Every
+> wire-exposed procedure must declare exactly one of `guards:`,
+> `openAccess: '<reason>'` or `internal: true`; a descriptor that declares none
+> is refused at boot, naming the file. Which one is right is a real decision,
+> and both of the other two appear on this page below. Full rules:
+> [Authorization](/docs/authentication/authorization#every-procedure-decides-guards-or-openaccess).
+
 ## Consuming a query
 
 ```tsx no-check
@@ -219,6 +227,7 @@ import { Schema } from 'effect'
 export const listMessages = defineQuery({
   name:   'messages.list',
   source: 'messages',
+  guards: [{ scope: 'messages:read' }],
   input:  Schema.Struct({
     channelId: Schema.String,
     limit:     Schema.Number,
@@ -273,6 +282,7 @@ import { Schema } from 'effect'
 export const notesSummary = defineQuery({
   name:   'notes.summary',
   source: 'notes',
+  guards: [{ scope: 'notes:read' }],
   input:  Schema.Struct({}),
   output: Schema.Struct({
     open: Schema.Number,
@@ -323,8 +333,11 @@ It's a runtime identity (returns the handler unchanged) — the whole value is t
 `source` also connects query caches to mutation `target` metadata:
 
 ```ts
-defineQuery({ name: 'notes.list', source: 'notes', /* ... */ })
-defineMutation({ name: 'notes.create', target: { table: 'notes', op: 'insert' }, /* ... */ })
+defineQuery({ name: 'notes.list', source: 'notes', guards: [{ scope: 'notes:read' }], /* ... */ })
+defineMutation({
+  name: 'notes.create', target: { table: 'notes', op: 'insert' },
+  guards: [{ scope: 'notes:write' }], /* ... */
+})
 ```
 
 With that pairing, `useMutation('app', 'notes.create')` can stage an optimistic row in active `notes.list` caches without client-side cache plumbing.
@@ -340,7 +353,11 @@ export const teamBoard = defineQuery({
   name: 'boards.forTeam',
   input: Schema.Struct({ teamId: Schema.String }),
   output: BoardRows,
-  // `boards` alone is wrong here — `requireTeamAccess` reads `teamMembers`.
+  // The guard resolves the caller's membership of THIS team — a read of
+  // `teamMembers` that happens before the executor runs.
+  guards: [{ action: 'view', resourceType: 'team', resource: (input) => input.teamId }],
+  // `boards` alone is wrong here — that membership read is part of what the
+  // result depends on.
   source: ['boards', 'teamMembers'],
 })
 ```
@@ -390,6 +407,7 @@ import { Schema } from 'effect'
 export const listProjects = defineQuery({
   name:   'projects.list',
   source: 'projects',
+  guards: [{ scope: 'projects:read' }],
   input:  Schema.Struct({}),
   output: Schema.Array(
     Schema.Struct({
@@ -542,9 +560,12 @@ Queries are streaming RPCs whose elements are **subscription events**: an initia
 defineQuery({ name: 'q', guards: [], … })              // ✗ enforces nothing
 defineQuery({ name: 'q', source: '', … })              // ✗ reactive, subscribed to nothing
 defineQuery({ name: 'q', internal: true, overridesPlugin: true, … })  // ✗ removes, replaces nothing
+defineQuery({ name: 'q', openAccess: '', … })          // ✗ a marker with no reason
+defineQuery({ name: 'q', guards: [{ scope: 'x' }], openAccess: 'open', … })  // ✗ two decisions
+defineQuery({ name: 'q', internal: true, openAccess: 'open', … })  // ✗ no wire to decide about
 ```
 
-The same three shapes `defineEvent` refuses, for the same reasons — a rule that
+The first three are the shapes `defineEvent` refuses too, for the same reasons — a rule that
 holds for one primitive and not another is worse than no rule, because the
 answer then depends on which file you happened to open.
 
@@ -561,6 +582,22 @@ something unreachable in its place: callers get a 404 for something that used to
 work, with no diff that says so. Joins the existing refusals of `internal` with
 `publicApi` or `exposeAsTool`.
 
+**`openAccess` without a reason** is a marker that says nothing. The reason is
+what a reviewer reads to decide whether this really should be callable without a
+check — `openAccess: 'public pricing, no caller data'`.
+
+**`openAccess` + `guards`** is two different access decisions at once: the
+procedure is protected AND open. Keep the guards if a caller must hold a scope;
+drop them if anyone may call it.
+
+**`openAccess` + `internal: true`** decides about a surface that does not exist —
+`internal` takes the procedure off the wire. Drop one of the two.
+
+> Every wire-exposed procedure must carry ONE of `guards:` / `openAccess:` /
+> `internal: true`, or the boot refuses it. See
+> [Authorization](/docs/authentication/authorization) for the gate and the
+> `security.defaultDeny` field that governs it.
+
 
 ## Loading vs empty — don't conflate them
 
@@ -658,6 +695,7 @@ import { Schema } from 'effect'
 export const createNote = defineMutation({
   name:   'notes.create',
   target: { table: 'notes', op: 'insert' },
+  guards: [{ scope: 'notes:write' }],
   input:  Schema.Struct({
     title: Schema.NonEmptyString,
     body:  Schema.String,
@@ -668,6 +706,13 @@ export const createNote = defineMutation({
 })
 ```
 
+> **`guards:` is what makes this file boot.** A wire-exposed mutation must
+> declare exactly one of `guards:`, `openAccess: '<reason>'` or `internal: true`
+> — a descriptor with none of them is refused at boot, naming the file. A write
+> is also where a rubber-stamp guard costs the most, so name the scope the write
+> actually needs rather than one every caller already holds. Full rules:
+> [Authorization](/docs/authentication/authorization#every-procedure-decides-guards-or-openaccess).
+
 Server executor:
 
 ```ts
@@ -872,6 +917,7 @@ The default path is declarative:
 defineQuery({
   name: 'notes.list',
   source: 'notes',
+  guards: [{ scope: 'notes:read' }],
   input: Schema.Struct({}),
   output: Schema.Array(Note),
 })
@@ -879,6 +925,7 @@ defineQuery({
 defineMutation({
   name: 'notes.create',
   target: { table: 'notes', op: 'insert' },
+  guards: [{ scope: 'notes:write' }],
   input,
   output,
 })
@@ -972,6 +1019,7 @@ class NoteQuotaExceeded extends Schema.TaggedError<NoteQuotaExceeded>()('NoteQuo
 export const createNote = defineMutation({
   name: 'notes.create',
   target: { table: 'notes', op: 'insert' },
+  guards: [{ scope: 'notes:write' }],
   input,
   output,
   error: NoteQuotaExceeded,
@@ -1087,10 +1135,16 @@ Rules run on `voltro dev` and `voltro serve` through the same mutation runner, s
 
 ## `internal: true` — off the wire entirely
 
-Every discovered `*.mutation.ts` / `*.query.ts` / `*.action.ts` / `*.stream.ts` is
-callable over the WebSocket by any authenticated browser session. `publicApi` and
-`exposeAsTool` opt IN to wider surfaces; `internal: true` opts OUT of the default
-one:
+Every discovered `*.mutation.ts` / `*.query.ts` / `*.action.ts` / `*.stream.ts`
+gets a route on the WebSocket — which is why each one has to declare **who may
+call it**, and why an app carrying an undecided procedure does not boot at all.
+`internal: true` is the third answer to that question, beside `guards:` and
+`openAccess:`: there is no wire surface to make a decision about, because the
+procedure never gets a route. (`publicApi` and `exposeAsTool` go the other way
+and opt IN to *wider* surfaces — which is why neither combines with `internal`.)
+
+Reach for it when the caller is other **server** code — a workflow step, a
+schedule, another executor — and never a browser:
 
 ```ts
 export const createFromAction = defineMutation({
@@ -1113,6 +1167,13 @@ anyone logged in. If the only thing keeping a procedure off the wire is that
 nobody wrote a client call for it, it is on the wire — the same reasoning as
 `.serverOnly()` on a column, one level up.
 
+That app is why the boot gate exists: all 18 declared no access decision, so
+today it does not start until each of them says `guards:`, `openAccess:` or
+`internal: true`. The gate turns "reachable and nobody looked" into a refusal
+naming every file — but it only forces the question, it cannot answer it, and
+`internal: true` is the right answer only when no browser is meant to call the
+procedure at all.
+
 **It is not a substitute for a guard.** An internal procedure still runs with
 whatever authority its caller has. This removes the wire surface, not the need to
 check who is asking; `voltro doctor`'s authz scan still covers it.
@@ -1172,6 +1233,7 @@ a mutation do:
 ```ts
 export const syncIssue = defineAction({
   name: 'jira.syncIssue',
+  guards: [{ scope: 'jira:sync' }],
   input: Schema.Struct({ key: Schema.String }),
   output: Schema.Struct({ ok: Schema.Boolean }),
   source: 'jiraIssueCache',
@@ -1195,6 +1257,7 @@ import { Schema } from 'effect'
 
 export const pingExternal = defineAction({
   name: 'support.ping',
+  guards: [{ scope: 'support:diagnostics' }],
   input: Schema.Struct({ url: Schema.String }),
   output: Schema.Struct({
     status:     Schema.Number,
@@ -1203,6 +1266,15 @@ export const pingExternal = defineAction({
 })
 ```
 
+> **`guards:` is what makes this file boot** — a wire-exposed action must declare
+> exactly one of `guards:`, `openAccess: '<reason>'` or `internal: true`, or the
+> boot refuses it, naming the file. This one earns a real scope rather than
+> `openAccess`: it fetches a **caller-supplied URL** from your server. The
+> [SSRF guard](/docs/security/overview#outbound-http-is-ssrf-guarded-by-default)
+> keeps that off your internal network, but "anyone on the internet may make this
+> server issue requests" is still not a claim to make by accident. Full rules:
+> [Authorization](/docs/authentication/authorization#every-procedure-decides-guards-or-openaccess).
+
 Server executor:
 
 ```ts
@@ -1461,6 +1533,7 @@ import { Schema } from 'effect'
 export const listNotes = defineQuery({
   name:   'notes.list',
   source: 'notes',
+  guards: [{ scope: 'notes:read' }],   // re-checked on every delivery, not just at open
   input:  Schema.Struct({ archived: Schema.Boolean }),
   output: Schema.Array(Schema.Struct({
     id:    Schema.String,
@@ -1471,6 +1544,84 @@ export const listNotes = defineQuery({
 
 `source` declares which table re-runs computed queries and lets mutations with matching `target` metadata patch the client cache optimistically.
 
+## Reactivity channels
+
+`source:` usually names a table. It does not have to, and when the state a query
+reads is **not in the database**, naming one is the wrong answer.
+
+```ts
+import { defineQuery, reactivityChannel } from '@voltro/protocol'
+import { Schema } from 'effect'
+
+// Declared once, in a browser-safe module both sides import.
+export const jobQueue = reactivityChannel('job-queue')
+
+export const queueDepth = defineQuery({
+  name:   'jobs.depth',
+  source: jobQueue,                     // ← a channel, not a table
+  input:  Schema.Struct({}),
+  output: Schema.Struct({ pending: Schema.Number }),
+})
+```
+
+Then push it from wherever the state actually changes:
+
+```ts
+import { publishReactivity } from '@voltro/protocol'
+
+publishReactivity(ctx.store, jobQueue)   // every subscriber re-runs its executor
+```
+
+Everything else is unchanged: the executor returns a plain value, the framework
+re-runs it and pushes the result over the same subscription transport a
+table-backed reactive query uses. There is no second client concept and no
+second push mechanism — `useSubscription` does not know the difference.
+
+### Why not just declare a table
+
+Because the alternatives are worse, and the framework shipped one of them for a
+release. Presence held its roster in memory and still declared a
+`_voltro_presence` table it never wrote a row to, purely to own a name the
+reactivity layer would route on — an empty table in every user's database,
+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
+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.
+
+### Pass the channel, not its key
+
+A channel's routing key is `channel:<name>`, and you can read it off
+`jobQueue.key`. **Do not write that string into `source:`.** Passing the object
+creates an import edge from the query to the declaration, which removes the
+entire class of stale-source bugs for channels: a table `source:` is a string,
+so a rename leaves the old one behind and `tsc` cannot see it, while a channel
+that is not imported does not exist to be named. The boot audit reports a
+`channel:` key nothing declared, for the two ways round it.
+
+Names are lowercase kebab segments separated by dots — `presence`, `job-queue`,
+`billing.usage`. A `:` is refused (it is the namespace separator) and so is an
+uppercase letter (a key that differs only by case reads as one channel and
+routes as two). Declaring the same name twice returns the same channel.
+
+### What a channel is not
+
+- **Not an event.** [`defineEvent`](/docs/data/subscriptions#streams-are-different)
+  carries a PAYLOAD to subscribers with replay, ordering and gap detection. A
+  channel carries nothing — it says "re-read", and the subscriber's own executor
+  decides what that means. Reach for an event when the message matters; a channel
+  when the state does.
+- **Not cross-replica.** `publishReactivity` wakes subscribers on the node that
+  called it. Fanning a change out to other replicas is
+  [`@voltro/plugin-broadcast`](/docs/plugins/broadcast)'s job, exactly as it is
+  for table changes on a dialect without CDC.
+- **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).
+
 ## Query Executor
 
 ```ts
@@ -1628,7 +1779,50 @@ Queries/subscriptions are for live state. Streams are for one-shot element flows
 
 ## Reconnect
 
-On reconnect, the client re-subscribes to active queries and receives a fresh snapshot. Optimistic patches are client-local and are reverted when their mutation settles.
+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.
+
+**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`
+keeps its previous value and `loading` stays `false` across the gap; the first
+snapshot on the new stream replaces the stale rows. There is nothing to opt
+into:
+
+```tsx
+const { data, loading } = useSubscription('app', 'notes.list', {})
+if (loading) return <Skeleton/>   // does NOT fire on a reconnect
+return <NoteList notes={data}/>
+```
+
+Use [`useConnectionStatus`](/docs/ui/client-utilities/use-connection-status) if
+you want to tell the user the rows may be a few seconds old — the data itself
+never disappears from under them.
+
+Three things are deliberately NOT carried across:
+
+- **Optimistic patches.** They are client-local and belong to mutations that
+  died with the old connection, so nothing could ever retract them. They are
+  reverted when their mutation settles.
+- **A cold-start error.** The new connection re-establishes the truth.
+- **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.
+
+### An auth change still blanks — on purpose
+
+When the rebuild happens because the connection's *subject* changed — a cookie
+login, a logout, a tenant switch, i.e. `useReconnect()` — **nothing** is carried
+over and the screen does go back to its loading state.
+
+That is not a gap in the feature, it is the point of the gate. The next subject
+may be entitled to strictly less than the previous one, so painting the previous
+subject's rows into their session, even for the moment before the first snapshot
+lands, would be a data exposure. The same rule applies to
+[`useRefreshSubscriptions`](/docs/ui/client-utilities/use-refresh-subscriptions),
+which clears each entry's data on the same-socket re-auth path.
+
+The short version: **a dropped connection keeps your screen, a change of
+identity clears it.**
 
 ## Tenant Scoping
 
@@ -1670,6 +1864,82 @@ a bigger machine.
 These numbers are asserted by `rowPatch.perf.test.ts`, so they are current
 rather than a note somebody wrote down once.
 
+## Fan-out — how many subscribers may one change wake?
+
+A change wakes every subscription that reads the changed table, and the framework
+already collapses the work they share: one READ per distinct query, one DIFF per
+distinct `(query, base)`, one no-op comparison per distinct `(query, base)`. Fifty
+screens on one query cost one of each, not fifty.
+
+What does NOT collapse is what is genuinely per subscriber: re-running the query's
+`guards:` and re-resolving row-level visibility. Those are re-run for every
+subscriber on every delivery, on purpose — a role revoked or a share withdrawn has
+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.
+
+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.
+
+Set it with `VOLTRO_REACTIVE_DELIVERY_CONCURRENCY`:
+
+```bash
+VOLTRO_REACTIVE_DELIVERY_CONCURRENCY=16 voltro serve
+```
+
+Raise it when your guards or row filters hit the database and you have pool
+headroom; set it to `1` for strictly one-at-a-time delivery. A value that is not
+a positive integer is ignored rather than honoured — a concurrency of `0` is a
+fan-out that delivers to nobody, and that is reachable through a typo in a values
+file. Unbounded is deliberately not an option: one round-trip per subscriber at
+the same instant starves the connection pool the request path shares, which is
+slower than serial.
+
+Per-subscriber ordering is unaffected: a change touches each subscription exactly
+once. Order BETWEEN subscribers was never guaranteed.
+
+### How many subscribers fit on one node?
+
+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).
+
+| 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.
+- **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
+  thousand of them move that count by zero.
+
+Past the ceiling the lever is horizontal: more nodes, each carrying fewer
+subscribers. Change fan-out is already fleet-wide on postgres (LISTEN/NOTIFY) and
+mysql/mariadb (binlog), so a second node needs no extra wiring — the cost being
+budgeted here is the matcher and re-query CPU each node spends on ITS OWN
+clients.
+
 ## 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).
@@ -1707,6 +1977,8 @@ import { Schema } from 'effect'
 
 export const ticker = defineStream({
   name:    'ticker.watch',
+  openAccess: 'public market prices from an upstream feed — reads no table and '
+    + 'nothing derived from the caller',
   input:   Schema.Struct({ symbol: Schema.String }),
   element: Schema.Struct({
     price: Schema.Number,
@@ -1715,6 +1987,15 @@ export const ticker = defineStream({
 })
 ```
 
+> **The access decision is what makes this file boot.** A wire-exposed stream
+> must declare exactly one of `guards:`, `openAccess: '<reason>'` or
+> `internal: true`, or the boot refuses it, naming the file. This one is
+> genuinely open, so it says so — and the reason is the point: `openAccess`
+> takes a sentence, not a boolean, because a reviewer has to be able to check
+> the claim. A stream carrying *your* rows (an import log, an export feed) wants
+> `guards:` instead. Full rules:
+> [Authorization](/docs/authentication/authorization#every-procedure-decides-guards-or-openaccess).
+
 Server executor:
 
 ```ts
@@ -2438,6 +2719,7 @@ export default defineQuery({
 - **Relations** need nothing extra: eager loading is resolved server-side by the executor, so `include` works identically over HTTP.
 - **Authorization is the same code** as the WebSocket path — the declarative `guards:`, the row filter, and tenant scoping all run before the handler. A procedure that denies on the socket denies here.
 - Also available per endpoint: `scopes` (extra API-key scopes), `rateLimit`, `idempotent`.
+- **`idempotency:` covers these routes too**, on the same terms as a hand-written `restRoutes` entry above: one binding, one `Idempotency-Key` header, one `_voltro_idempotency` table, and identical behaviour under `voltro dev` and `voltro serve`. Projected routes and hand-written ones go through the same single projection, so it is not possible for one to deduplicate and the other not to.
 
 This pairs with [`crud.list`](/docs/data/crud): `filter` / `paginate` / `sort` / `include` on the executor plus `publicApi: {}` on the descriptor is a complete, filtered, paginated REST list endpoint in one declaration.
 
@@ -3004,6 +3286,8 @@ import { Schema } from 'effect'
 
 export default defineQuery({
   name: 'accounts.list',
+  // the authorization lives here, not in the helper — crud.* adds no guard
+  guards: [{ scope: 'accounts:read' }],
   input: Schema.Struct({}),
   // note: the wire output OMITS apiSecret, so it never reaches the client
   output: Schema.Array(Schema.Struct({ id: Schema.String, name: Schema.String })),
@@ -3014,6 +3298,8 @@ export default defineQuery({
 
 - **Tenant scope.** `crud.list` and `crud.getById` read through `ctx.store`, which auto-scopes a `tenant()` table. They never call `.unscoped()`, so a cross-tenant read is impossible through them — `payslips.list` cannot return another tenant's rows.
 - **Redaction.** A column a generated read must never ship — a credential, a token hash, a salary — is stripped from every returned row (reads and the row a `create` / `update` echoes). Two sources: a column marked [`.serverOnly()`](/docs/database/sensitivity) is stripped **automatically** (declare the exposure policy once at the schema and every crud read respects it — the single-source form), plus the per-call `redact: [...]` option for anything not worth a schema marker. Declare the same omission in the descriptor's `output` schema so the column never reaches the client at all; the helper is the runtime guarantee that it doesn't, whatever the schema says.
+- **No mass assignment of a `.serverOnly()` column.** The same marker is enforced on the **input** side: `crud.create` and `crud.update` **refuse** a payload that sets one, with `ServerOnlyColumnWrite` naming the offending columns, and nothing is written. `.serverOnly()` means *never crosses the wire*, so accepting it inbound is the same violation as leaking it, mirrored — a client could SET a column it is not allowed to READ. It is a refusal rather than a silent strip because a stripped field makes an attack look like a no-op and leaves an honest caller debugging a value that quietly did not land. A key present with the value `undefined` does not count as sent, so optional schema fields are unaffected. When the *server* legitimately needs to write one, do it from the handler with `ctx.store.insert` / `ctx.store.update` — those are unchanged; the refusal is on the generated path, which is the one fed straight from client input.
+- **Keyed writes stay inside the caller's tenant.** `crud.update` and `crud.remove` address the row by `input.id`, which is client-supplied. On a [`tenant()`](/docs/multi-tenancy/mixin) table the store resolves that id inside `subject.tenantId`, so another tenant's id fails with `TenantRowNotFound` instead of writing. The error is the same whether the row is missing or foreign, on purpose — the pair would otherwise be a cross-tenant existence oracle.
 - **`getById` returns `null`, never throws.** A reactive getter that throws takes its shared-WebSocket siblings down with it. `crud.getById` resolves `null` for an absent row.
 
 ## The helpers
@@ -3022,8 +3308,8 @@ export default defineQuery({
 |---|---|
 | `crud.list(table, { redact? })` | tenant-scoped list of every row, redacted |
 | `crud.getById(table, { redact? })` | one row by `input.id`, or `null` — redacted |
-| `crud.create(table, { redact? })` | insert `input`; id/tenant/audit auto-stamped; echoes the redacted row |
-| `crud.update(table, { redact? })` | patch `{ id, ...patch }`; returns the updated row or `null` |
+| `crud.create(table, { redact? })` | insert `input`; id/tenant/audit auto-stamped; echoes the redacted row; refuses a `.serverOnly()` field in the input |
+| `crud.update(table, { redact? })` | patch `{ id, ...patch }`; returns the updated row or `null`; tenant-resolved by id; refuses a `.serverOnly()` field in the patch |
 | `crud.remove(table)` | delete `input.id`; returns `{ deleted }` |
 | `crud.count(table, { filter? })` | `COUNT(*)` of the filtered, tenant-scoped set — the total for page-based UIs |
 
@@ -3428,6 +3714,223 @@ into the agent's prompt.
 
 
 
+---
+
+<!-- source: en/data/approvals.md -->
+## Approvals
+
+_requiresApproval — a mutation or action that needs a second human before it takes effect, with the pending intent in a durable row and self-approval refused._
+
+A mutation can declare that **one person is not enough**:
+
+```ts
+// apps/api/mutations/invoices.refund.mutation.ts
+import { defineMutation } from '@voltro/protocol'
+import { Schema } from 'effect'
+
+export const refundInvoice = defineMutation({
+  name: 'invoices.refund',
+  input:  Schema.Struct({ invoiceId: Schema.String, amountCents: Schema.Number }),
+  output: Schema.Struct({ ok: Schema.Boolean }),
+  // The requester still has to be allowed to ASK.
+  guards: [{ scope: 'invoices:refund' }],
+  requiresApproval: {
+    approvers: [{ scope: 'invoices:approve' }],
+    expiresIn: '4h',
+    reason: 'refunds move money out of the account',
+  },
+})
+```
+
+That is the whole declaration. The framework does the rest: the first call is
+recorded and refused, a second human decides, and the identical call then
+succeeds exactly once.
+
+Human-in-the-loop already existed *inside* a durable workflow
+([`awaitSignal`](/docs/workflows/definition), AI-Flows' human step). This is the
+same idea for an **ordinary rpc call** — no workflow around it, no status column
+to hand-roll, and the "who may approve" rule expressed in the same `guards:`
+vocabulary as everything else.
+
+## What the caller sees
+
+The first call does **not** run. It fails with a typed `ApprovalRequired`:
+
+```ts
+import { errorTag } from '@voltro/protocol'
+
+const result = await refund({ invoiceId, amountCents })
+// throws:
+// {
+//   _tag: 'ApprovalRequired',
+//   approvalId: 'apv_01j…',
+//   procedure: 'invoices.refund',
+//   expiresAt: '2026-08-12T14:00:00.000Z',
+//   requiredScopes: ['invoices:approve'],
+//   reason: 'refunds move money out of the account',
+//   created: true,   // false when an earlier identical call already asked
+// }
+```
+
+It is a typed failure rather than a success with a status field on purpose: a
+mutation that returned its normal output shape when nothing happened is the
+easiest thing in the world for a client to mis-handle, and every client already
+branches on `_tag`.
+
+For a mutation the **transaction never opens**. For an action the executor's
+external I/O never happens — which is the only point at which nothing has
+happened yet, since there is no rollback for an outbound HTTP call.
+
+## The two built-in procedures
+
+`__voltro.approvals.pending` is a reactive query over the approvals table, so
+both sides of the exchange are live with no polling:
+
+```tsx
+import { useSubscription, useMutation } from '@voltro/client'
+import type { PendingApproval } from '@voltro/protocol'
+
+export const ApprovalQueue = () => {
+  const { data } = useSubscription<ReadonlyArray<PendingApproval>>(
+    'app', '__voltro.approvals.pending', {},
+  )
+  const decide = useMutation('app', '__voltro.approvals.decide')
+
+  return (
+    <ul>
+      {(data ?? []).map((a) => (
+        <li key={a.id}>
+          {a.procedure} — {a.relation === 'to-decide' ? 'awaiting you' : `you asked · ${a.status}`}
+          {a.relation === 'to-decide' && (
+            <button onClick={() => decide.mutate({ approvalId: a.id, decision: 'approve' })}>
+              Approve
+            </button>
+          )}
+        </li>
+      ))}
+    </ul>
+  )
+}
+```
+
+Each row carries a `relation`: `'to-decide'` (you may act on it) or
+`'requested'` (you asked for it). The requester watches their own row flip
+`pending → approved` and re-fires the mutation; the approver's queue appears
+without a refresh.
+
+The feed is **scoped in the handler, not by a descriptor guard** — a row appears
+only if you requested it or satisfy its recorded approver scopes, so an
+anonymous caller sees an empty list. There is no scope that means "may see my own
+approval work", and inventing one would be a guard that reads as protection and
+enforces nothing.
+
+## Where the pending intent lives, and why its identity matters
+
+Between the request and the decision the intent is a row in `_voltro_approvals`
+— durable, so it survives a restart, a rolling deploy and a replica switch.
+
+Its identity is **content-addressed**: a digest over the procedure, the
+requester, the tenant, the canonicalised input, and an optional caller `nonce`.
+Both directions of getting that wrong are real bugs:
+
+- too **coarse** (keying on the procedure, say) and two different pending
+  intents share one row, so approving one executes the other's payload;
+- too **fine** (a fresh id per attempt) and every page refresh, client re-send or
+  transaction replay mints a second approval, asking the human twice for one
+  decision.
+
+Content-addressing is the only spelling that is stable across a retry and
+distinct across intents. A `UNIQUE` on that key enforces **at most one live
+intent per content**. Two deliberately identical requests — the same user really
+does want to refund the same invoice twice — are expressible by passing a
+different `nonce`, which is a decision you state rather than one the framework
+guesses.
+
+An approval is **consumed** when it admits a call. A replay after that is a new
+request, not a free second execution.
+
+## The refusals
+
+These are the point of the feature, so they are worth reading as a list.
+
+**Self-approval is refused, unconditionally.** There is no opt-out flag. The
+whole content of "a second human" is that it is a second one, and a framework
+that shipped `allowSelfApproval: true` would be shipping a control every team
+turns off under deadline pressure — with the audit row still reading "approved".
+
+The check runs **before** the authority check, deliberately: a requester who
+happens to hold the approver scope is told they cannot approve their own request,
+which is the accurate reason, instead of being quietly let through.
+
+**An unauthorised approver** gets `ApprovalForbidden`, naming the scope they
+lack. The check uses the same guard evaluator the dispatch spine runs, against
+the scopes recorded **on the row** — including a resource-scoped guard's resolved
+resource id, so `approvers: [{ scope: 'invoices:approve', resource: (i) => i.invoiceId }]`
+stays scoped to that invoice at decision time rather than widening into a global
+scope check.
+
+**An anonymous decider** is refused. Every anonymous caller compares equal to
+every other, so the identity the control rests on does not exist. For the same
+reason, `requiresApproval` combined with `openAccess:` is refused at declaration.
+
+**Expiry fails closed.** Past `expiresAt` the intent can be neither approved nor
+executed — including an intent that was approved and then aged out before the
+requester came back. The requester re-submits and a fresh decision is asked for.
+
+**One intent, one verdict.** A second decision on the same intent gets
+`ApprovalNotPending`.
+
+A rejection is reported to the requester once, as `ApprovalRejected`, on their
+next attempt. A further attempt after that opens a genuinely new decision — a
+rejection is a verdict on one request, not a permanent ban on the operation.
+
+## Declaration-time refusals
+
+Two shapes read like a control and enforce nothing, so they throw where you can
+still see both fields:
+
+```ts
+// ✗ nobody can approve this — every call would park forever
+requiresApproval: { approvers: [] }
+
+// ✗ an unauthenticated requester has no identity, so the self-approval
+//   refusal cannot compare anything and the control degrades to nothing
+openAccess: 'public', requiresApproval: { approvers: [{ scope: 'x' }] }
+```
+
+## Expiry as a tunable
+
+Precedence: the descriptor's own `expiresIn`, then the app default, then the
+environment, then 24 hours.
+
+```ts
+// app.config.ts
+export default {
+  approvals: { expiresIn: '4h' },
+}
+```
+
+`VOLTRO_APPROVAL_EXPIRY_HOURS` overrides the built-in default. There is
+deliberately no "never expires": an approval queue with no floor is a list of
+decisions nobody made.
+
+## Agent tools
+
+`exposeAsTool: { confirm: true }` used to be a report — the inventory showed it
+and nothing enforced it. It is now backed by this primitive: a confirm tool is
+mountable only if its descriptor also declares `requiresApproval`, and then the
+agent's call parks in your approval queue and returns `ApprovalRequired` to the
+model. See [Agent tools](/docs/ai/tools).
+
+## The table
+
+`_voltro_approvals` is created for every app (it is one small table, and the
+alternative would be a surprise `CREATE TABLE` on the production boot after
+somebody adds `requiresApproval:` to a mutation). It is bounded by the retention
+sweep — 30 days by default, `VOLTRO_APPROVALS_TTL_HOURS` to change it.
+
+
+
 ---
 
 <!-- source: en/data/client-state.md -->
@@ -3698,6 +4201,20 @@ enqueued by another replica, and rows waiting out a backoff. Without it the
 guarantee degrades to "delivered unless something went wrong" — which is the
 exact case a durable outbox exists for.
 
+**The 5 seconds is a floor, not a rate.** Those three reasons are taken one at a
+time, and only the last needs a clock:
+
+| the poll exists for… | what brings the loop back |
+| --- | --- |
+| a nudge lost to a dead process | the first pass at boot, which is not deferred behind a tick |
+| a row another replica enqueued | a change event on `_voltro_outbox` |
+| a row waiting out a backoff | the runner arms for that row's own `nextAttemptAt` |
+
+So on an empty queue the timer **stops entirely** and the loop waits to be woken.
+Where no change channel is available it keeps the fixed 5-second tick instead —
+the poll is then the only thing that can notice another replica's row, and a
+durable outbox that stops looking is worse than one that polls.
+
 ## Options
 
 ```ts
@@ -3989,6 +4506,7 @@ Wire them into a mutation / action / query via the `error` field:
 ```ts
 export const transfer = defineMutation({
   name:   'wallet.transfer',
+  guards: [{ scope: 'wallet:transfer' }],
   input:  Schema.Struct({ to: Schema.String, amount: Schema.Number }),
   output: Schema.Struct({ txId: Schema.String }),
   error:  Schema.Union(InsufficientFunds, TitleTooLong),
@@ -4020,6 +4538,25 @@ if (result._tag === 'InsufficientFunds') {
 }
 ```
 
+### What a rejected write actually rejects with
+
+**The value is the typed error itself** — the same value `useSubscription` reports on the read side. Not a wrapper around it, and not an Effect `FiberFailure` (whose `_tag` would be `undefined`, so every branch above would silently fall through to the generic one).
+
+That guarantee covers every write hook, not just `mutate`:
+
+| Hook | Rejecting call |
+|---|---|
+| `useMutation` | `mutate(input)` |
+| `useAction` | `run(input)` |
+| `useWorkflow` | `start` · `cancel` · `resume` · `signal` · `update` |
+| `useWorkflowSignal` / `useWorkflowUpdate` | `signal` · `update` |
+| `useUpload` | `upload` · `uploadMany` |
+
+Two consequences worth knowing:
+
+- A **defect** (an undeclared `throw` server-side, a transport drop) rejects too, but with a plain `Error` — so an `_tag` check on it is `undefined` and falls to your generic branch, which is the intended split. Check `_tag` for the outcomes you declared; treat everything else as unexpected.
+- Passing `onError` (or `notify.error`) instead **resolves** with `undefined` and hands that same typed value to your handler. See [Mutations](/docs/data/mutations).
+
 Tagged errors:
 
 - Are wire-safe — they serialise as JSON (the rpc transport is `RpcSerialization.layerJson`) and restore on the client with the correct `_tag` + payload.
@@ -4053,6 +4590,8 @@ To distinguish "we know about this" from "this surprised us":
 | `ScopeError` | `@voltro/protocol` | `requireScope(subject, scope)` failed — `{ required, message }`. |
 | `Unauthenticated` | `@voltro/protocol` | The resolved Subject is anonymous but a signed-in caller was required — optional `{ reason }`. |
 | `TenantScopeViolation` | `@voltro/runtime` | A tenant-scoped `EffectStore` write had no authenticated subject. |
+| `TenantRowNotFound` | `@voltro/runtime` | A keyed-by-id write (`store.update(t, id, …)`, `delete`, `hardDelete`, `patchJson`) on a `tenant()` table found no such row **in the caller's tenant**. Raised identically whether the row is missing or belongs to another tenant — the distinction would be a cross-tenant existence oracle. |
+| `ServerOnlyColumnWrite` | `@voltro/runtime` | A `crud.create` / `crud.update` input tried to set a [`.serverOnly()`](/docs/database/sensitivity) column — `{ table, columns }`. |
 | `StoreOperationFailed` | `@voltro/runtime` | The underlying store operation failed (transient). |
 | `TableValidationFailed` | `@voltro/runtime` | A `table().validate(Schema)` row check rejected the write. |
 | `CacheError` | `@voltro/cache` | A cache backend op failed — `{ operation, key, cause }`. |