@voltro/cli 0.11.3 → 0.12.0

package/templates/agent-docs/data.md

@@ -691,6 +691,14 @@ column — and required otherwise. `upsertRow`'s `conflictColumns` are constrain
 to the table's own columns, so a typo is a compile error too. The string-keyed
 `ctx.store.insert` / `upsert` still work unchanged; the typed seam is opt-in.
 
+> **If you adopt it, check your tooling for the old spelling.** `insertRow`
+> replaces `store.insert('<tableName>', …)`, so anything that matches on that
+> string stops matching — a lint rule, a codemod, an architecture test. One team
+> had a test asserting every mutation writes an audit log; it matched
+> `store.insert('auditLogs'`, and migrating to `insertRow` silently blinded it.
+> Green suite, gap reintroduced. Grep for the old spelling before you migrate,
+> not after.
+
 ## Partial updates: `ctx.store.applyDefined`
 
 A partial-update mutation should set only the fields the caller actually sent — not overwrite an omitted field with `undefined`. Instead of hand-writing `if (input.x !== undefined) patch.x = input.x` per field, use `ctx.store.applyDefined(input, keys)`:
@@ -1579,6 +1587,61 @@ 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.
 
+## 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:
+
+```ts
+// queries/absenceRequests.list.query.ts
+export default defineQuery({
+  name:   'absenceRequests.list',
+  input:  Schema.Struct({ status: Schema.optional(Schema.String), limit: Schema.optional(Schema.Number) }),
+  output: Schema.Array(AbsenceRequest),
+  guards: [requireScope('absences:read')],
+  publicApi: {},   // → GET /v1/absenceRequests/list?status=open&limit=20
+})
+```
+
+- **Method** derives from the kind: query → `GET`, mutation / action → `POST` (override with `method`).
+- **Path** derives from the tag: `/<version>/<tag-as-path>` (override with `path`; set `version`).
+- **Input binding** follows the method: for `GET` the descriptor's `input` schema is bound to the **query string**, otherwise to the JSON **body**. So filter and pagination fields are plain URL params — no separate input shape.
+- **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`.
+
+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.
+
+Use `publicApi` when the procedure already exists and the derived URL is fine; use `defineRestRoute` when you need a hand-shaped URL, path params, or a response that isn't the procedure's output.
+
+### Live updates over HTTP — `stream: 'sse'`
+
+A third party that can't open your WebSocket can still follow changes: `stream: 'sse'` on a QUERY projects it as Server-Sent Events — the initial `snapshot`, then a `delta` per change, until the client disconnects.
+
+```ts
+export default defineQuery({
+  name:   'orders.live',
+  input:  Schema.Struct({ status: Schema.optional(Schema.String) }),
+  output: Schema.Array(Order),
+  guards: [requireScope('orders:read')],
+  publicApi: { stream: 'sse' },   // → GET /v1/orders/live?status=open  (text/event-stream)
+})
+```
+
+```js
+// any EventSource client — no Voltro SDK needed
+const es = new EventSource('/v1/orders/live?status=open')
+es.addEventListener('snapshot', (e) => setRows(JSON.parse(e.data).data))
+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.
+
+`stream: 'sse'` on a mutation or action is ignored: there is nothing to subscribe to.
+
+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`).
+
 ## REST route vs Action
 
 Both are unary request/response. Pick by transport + audience:
@@ -1981,7 +2044,7 @@ export default defineQuery({
 ## What the defaults bake in
 
 - **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.** `redact` names columns stripped from every returned row — a credential, a token hash, a salary that a generated read must never ship. It applies to reads and to the row a `create` / `update` echoes back. 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.
+- **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.
 - **`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
@@ -1993,9 +2056,88 @@ export default defineQuery({
 | `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.remove(table)` | delete `input.id`; returns `{ deleted }` |
+| `crud.count(table, { filter? })` | `COUNT(*)` of the filtered, tenant-scoped set — the total for page-based UIs |
 
 `redactColumns(rows, cols)` is exported standalone for a hand-written handler that isn't plain CRUD but still needs to redact declaratively.
 
+## `crud.list` read ergonomics — filter, sort, paginate, include
+
+A generated list isn't limited to "all rows". `crud.list` takes the ergonomics every real list view needs — all optional and additive on top of `redact`:
+
+```ts
+export default crud.list('absenceRequests', {
+  filter:   (input) => ({ employeeId: input.employeeId, status: input.status }), // → WHERE
+  paginate: true,                                        // ?page=3&pageSize=20  (or ?limit=20&offset=40)
+  sort:     [{ column: 'createdAt', direction: 'desc' }], // multi-column
+  include:  { employee: { with: { team: true } } },      // eager relations, nested filter/sort
+  redact:   ['internalNote'],
+})
+```
+
+- **`filter`** maps the request input to a `WHERE` — return a column→value map; an `undefined` field is ignored (an absent filter param is a no-op). Applied through the tenant-scoped `.where`.
+- **`paginate: true`** accepts BOTH paging styles, so a caller uses whichever its UI thinks in: **`page`** (1-based) + **`pageSize`** (default 100), or **`limit`** / **`offset`** (defaults 100 / 0). `page` wins when both are sent, and a `page` below 1 clamps to the first page rather than producing a negative offset. For the total a page-based UI needs ("page 3 of 12"), pair it with `crud.count` — see below.
+- **`maxPageSize`** caps how many rows ONE request may ask for (default **1000**). The page size is caller-controlled, so without a cap `?limit=1000000` is a one-request read of the whole table — and with `publicApi` that caller is anyone who can reach the URL. Values above the cap are clamped, not rejected; raise it deliberately for an export-style endpoint.
+- **`sort`** is a multi-column `orderBy`, applied in order.
+- **`include`** is the SAME spec [`.with(...)`](/docs/database/relations) takes, so nested relations and per-branch `where` / `orderBy` / `limit` (nested filtering and sort) all work. `getById` takes `include` too.
+
+
+Pass `crud.count` the **same** `filter` as the list (share the option object) so the total and the pages can't disagree about which rows they mean. It ignores paging fields on the input — it counts the whole filtered set, not the current page:
+
+```ts
+// the total, for rendering "page 3 of 12" — SAME filter as the list
+export default crud.count('absenceRequests', {
+  filter: (input) => ({ employeeId: input.employeeId, status: input.status }),
+})
+```
+
+Declare the filter / pagination fields in the descriptor's `input` schema so the client can pass them; the executor reads them off `input`.
+
+**You don't need a `toView` projection layer** — the `output` schema already shapes the wire result. `crud.list` returns full rows, and on encode Effect **strips every column the output schema doesn't declare** (a tight `Schema.Struct({ id, name })` ships only `id` + `name`, whatever else the row holds), and a `timestampMs` field normalizes a `Date` to epoch ms. So select fields by naming them in `output`, and normalize dates with the wire field schemas — no per-table view function. (Renames are expressible via a Schema transform if you need them.)
+
+### `columns` — don't even READ what you drop
+
+The output schema stops a column reaching the client; `columns` stops it being read at all. Use it when a table carries something wide that a list view never shows — a long text body, a big `json()` blob:
+
+```ts
+export default crud.list('articles', { columns: ['id', 'title', 'createdAt'] })
+// the large `body` is never SELECTed, transferred from the DB, or decoded
+```
+
+`.serverOnly()` columns are removed from the projection automatically — they're stripped from the response anyway, so reading them is pure waste.
+
+**Trap:** an eager `include` branch joins on a foreign key, so a projection that omits that FK breaks the relation. Keep the FK in `columns` when you also pass `include`.
+
+### `scope` — keep per-subject narrowing when you adopt the helper
+
+`filter` builds the WHERE from the request; `scope` builds it from the **caller**:
+
+```ts
+crud.list('timeEntries', {
+  filter: (input) => ({ status: input.status }),      // what the caller ASKED for
+  scope:  (ctx)   => ({ ownerId: ctx.request.subject.id }),  // what it MAY SEE
+})
+```
+
+A WHERE built only from `input` can express *the rows the caller asked for*, never
+*the rows the caller may see*.
+
+`scope` is merged **last**, so a request field of the same name can never widen it —
+`?ownerId=someone-else` is simply overridden. That ordering is why the two are
+separate options rather than one: only one of them is a security boundary, and kept
+apart, *"does this list declare a `scope`?"* is a question a reviewer — or a future
+boot audit — can actually ask. Folded into `filter`, it becomes *"does this filter
+happen to read ctx somewhere in its body?"*, which nothing can check. Tenant scope still applies automatically; anything
+narrower — owner, team, role — does not. So replacing a hand-written handler that
+carried such a narrowing with `crud.list` **widens the result set, silently and
+without an error**. One app lost exactly that across eight list views.
+
+Use the same filter for `crud.count`, or the total contradicts the pages —
+"showing 10 of 4000" on a page holding ten rows.
+
+The reason this is an option rather than a reason to leave: hand-writing the query
+to get the narrowing also forfeits `serverOnly` stripping and the page-size clamp.
+A narrowing requirement should not cost you the safety rails.
+
 ## What they deliberately don't do — authorization
 
 A guard runs *before* the executor, so gating lives on the **descriptor**, not the handler — an executor cannot gate itself. Keep every write descriptor guarded:

package/templates/agent-docs/database/misc.md

@@ -225,6 +225,38 @@ Precedence, exactly:
 3. **`.safe()`** on an encrypted column suppresses the implied secret and copies
    it verbatim — say this only when you have genuinely reviewed the plaintext.
 
+## `.serverOnly()` — never to a client
+
+A THIRD, independent axis. `.sensitive()` / `.safe()` are about **data export
+masking**; `.encrypted()` is about **storage at rest**; `.serverOnly()` is about
+**wire exposure** — a column marked `.serverOnly()` is read normally by server
+code but must NEVER be serialized to a client:
+
+```ts
+keyHash: text().serverOnly(),   // an auth middleware verifies it; a client never sees it
+```
+
+The three are orthogonal — a column can carry any combination:
+
+```ts
+keyHash:      text().serverOnly(),               // a hash you never ship (not secret at rest — it IS the digest)
+recoveryNote: text().encrypted(),                // encrypted at rest, but the owner may read it → not serverOnly
+apiToken:     text().encrypted().serverOnly(),    // secret at rest AND never to a client
+```
+
+Enforcement: the [`crud.*` read helpers](/docs/data/crud) strip `.serverOnly()`
+columns from every returned row **automatically** — you declare the exposure
+policy once at the schema and can't forget it on a handler. For a hand-written
+query, omit the column from the `output` schema (and don't put it in the returned
+object) — and `voltro dev` **warns at boot**, naming the query and column, if a
+wire-reachable query's output declares a `.serverOnly()` column of its `source`
+table, so a secret can't ship on the wire by omission-mistake.
+
+Distinct from `.encrypted()` on purpose: encryption at rest says nothing about
+who may receive the plaintext — a private note you decrypt *for its owner* is a
+valid case, so treating "encrypted" as "never to a client" would be wrong. State
+the exposure policy explicitly.
+
 ## Worked example
 
 ```ts

package/templates/agent-docs/database/querying.md

@@ -1058,7 +1058,20 @@ const orgIds = await ctx.store.links('org_memberships', { userId: user.id }).lis
 
 `set(targetIds)` writes only the **difference**: the missing links are inserted, the surplus deleted, and links that are already correct are left untouched — so a reactive consumer sees a change only for what actually changed, and it returns `{ added, removed }`. `add` and `remove` read first and act only on the genuine delta, so both are idempotent.
 
-The **target column** is the junction's *other* `reference()` column — the one the anchor doesn't name. A junction with anything but exactly two reference columns is refused (write it by hand with `insertMany` / `deleteMany`). The writes go through the normal store path, so a junction that carries `tenant()` / `audit()` gets those columns stamped as usual. A junction with extra business columns (a membership `role`, a tag `order`) needs those set per row — `links` only manages the two FK columns, so insert those rows directly.
+The **target column** is the junction's *other* `reference()` column — the one the anchor doesn't name. A junction with anything but exactly two reference columns is refused (write it by hand with `insertMany` / `deleteMany`). The writes go through the normal store path, so a junction that carries `tenant()` / `audit()` gets those columns stamped as usual.
+
+`set` / `add` / `remove` manage only the two FK columns. For a junction that carries **per-row payload** — a membership `role`, a `capacity` value — use `setRows`, which diffs on the (source, target) pair AND updates the payload:
+
+```ts
+await ctx.store.links('team_capacities', { teamId: team.id }).setRows([
+  { projectId: 'p1', capacity: 40 },
+  { projectId: 'p2', capacity: 20 },
+])
+// added rows inserted with payload, removed deleted, a surviving row whose payload
+// CHANGED is updated, an unchanged one is left untouched → { added, removed, updated }
+```
+
+Only rows whose payload actually differs are written, so a reactive consumer sees a change exactly where the data changed — the diff-based replacement for a drop-and-reinsert on a data-carrying junction. Payload is compared by strict per-column equality (scalars like `capacity` / `role`).
 
 ## SQL shape
 

package/templates/agent-docs/internationalization.md

@@ -178,18 +178,13 @@ useT('does.not.exist')             // ✗ compile error — not a catalog key
 
 It's almost pure type refinement — the runtime is the same `useT` / `useTFn` / `<T>` (plus a `.dynamic` escape, below), only the signatures narrow to your catalog. Requires the base catalog to be `as const` (so its message strings survive as literal types).
 
-**Scope.** Simple `{name}` and single-argument `{count, number}` placeholders are extracted and required. For a *nested* inline ICU message (`{count, plural, one {…} other {…}}` / `select`), the **top-level arg** (`count`) is required and a branch's inner text is NOT mistaken for a var — so `t('duration', { count })` typechecks and renders. A REAL var nested inside a branch (`other {# blockers in {discipline}}`) is not collected, so it reads as *not required* rather than wrongly required; pass it via the loose values bag.
-
-To get that nested var **compiler-required**, split the plural into simple sibling keys and pick with a JS branch — each key is then a plain message where every var is top-level:
+**Scope.** Simple `{name}` and single-argument `{count, number}` placeholders are extracted and required. A *nested* inline ICU message (`{count, plural, one {…} other {…}}` / `select`) is fully parsed: the **top-level arg** (`count`) AND a real var nested inside a branch are both required, while a branch's literal text is never mistaken for a var. So for `'{count, plural, one {# blocker in {discipline}} other {# blockers in {discipline}}}'`, `t('blockers', { count, discipline })` is required — omit `discipline` and it's a compile error, not a render-time throw:
 
 ```tsx
-// catalog: 'blocker.one': '{count} blocker in {discipline}', 'blocker.other': '{count} blockers in {discipline}'
-count === 1
-  ? t('blocker.one',   { count, discipline })   // ✓ both vars required
-  : t('blocker.other', { count, discipline })
+t('blockers', { count: n, discipline })   // ✓ both required — discipline lives inside the branches
 ```
 
-(The [`plural()` helper](/docs/i18n/formatting) only substitutes `{count}`, so it doesn't type or fill a second var — use it for count-only messages.) `<T>` gets a typed key with loose values, because its rich-text `<tag>` renderers can't be modelled by placeholder extraction.
+`<T>` gets a typed key with loose values, because its rich-text `<tag>` renderers can't be modelled by placeholder extraction.
 
 ### Runtime-computed keys — `t.dynamic`
 

package/templates/agent-docs/reference.md

@@ -985,6 +985,41 @@ export default (input: { prompt: string }) =>
   })
 ```
 
+### Writing a wrapper that PROVIDES a service
+
+A helper that provides a service must be generic over `R` and **subtract** the tag
+it provides, or it silently narrows what callers may pass it. The failure mode is
+confusing because it shows up at the CALL site, not in the wrapper:
+
+```ts
+import { Context, Effect } from 'effect'
+
+class Tenant extends Context.Tag('Tenant')<Tenant, { readonly id: string }>() {}
+
+// WRONG — `R` defaults to `never`, so this only accepts effects that need
+// nothing else. Pass it an effect that also needs `Db` and it stops compiling.
+const withTenantBad = <A, E>(id: string, effect: Effect.Effect<A, E>) =>
+  Effect.provideService(effect, Tenant, { id })
+
+// RIGHT — generic over `R`, and the return type SUBTRACTS the tag it provided.
+const withTenant = <A, E, R>(
+  id: string,
+  effect: Effect.Effect<A, E, R>,
+): Effect.Effect<A, E, Exclude<R, Tenant>> =>
+  Effect.provideService(effect, Tenant, { id })
+```
+
+`Exclude<R, Tenant>` is what makes the wrapper composable: the caller's remaining
+requirements pass through untouched, and only the tag you actually supplied
+disappears. Without it, the wrapper's own signature dictates the caller's entire
+requirement set.
+
+The same rule applies to any callback the framework takes from you (an AI tool
+body, a media generator, a workflow step): declare its `R` as `unknown` rather
+than letting it default to `never`, then let the framework's own bridge discharge
+it. A callback typed `Effect<A, E, never>` cannot use ANY service, which is
+rarely what you meant.
+
 ## Context By Primitive
 
 | Server file | Transaction | Typical store usage | External I/O | Returns |

package/templates/agent-docs/scheduling.md

@@ -208,7 +208,15 @@ timezone: 'Europe/Berlin'   // 09:00 Berlin — DST handled by effect's Cron
 
 ## The handler context
 
-The handler receives a `ScheduleContext` — the same `app` a mutation gets, plus firing metadata:
+The handler receives a `ScheduleContext` — the same `app` a mutation gets, plus firing metadata.
+
+> **The API is identical; the subject is not.** `ctx.app.store` here is **not
+> tenant-scoped** — a schedule runs as `system` with no tenant. Reads see every
+> tenant's rows, and a write to a `tenant()` table fails with
+> `TenantScopeViolation` unless you pass `tenantId` explicitly. See
+> [below](#a-schedule-runs-as-the-system-subject--no-tenant). This sentence is
+> here rather than only further down because "same shape as a mutation" is what
+> sets the expectation that gets violated.
 
 ```tsx
 handler: async (ctx) => {
@@ -250,6 +258,32 @@ Writes to a `tenant()` table need the same treatment: pass `tenantId`
 explicitly, or the write fails with `TenantScopeViolation` rather than landing
 somewhere arbitrary.
 
+### `ctx.app.storeForTenant(id)` — the fan-out shortcut
+
+Doing that by hand means every `.where('tenantId', …)` and every explicit
+`tenantId:` is one forgotten call away from reading or writing across tenants.
+`storeForTenant` hands you a store scoped to exactly one:
+
+```tsx
+handler: async (ctx) => {
+  for (const t of await ctx.app.store.select('tenants').all()) {
+    const scoped = ctx.app.storeForTenant(t.id)
+    await scoped.insert('digests', { body: summary })   // tenantId stamped, not passed
+  }
+}
+```
+
+Inside a REQUEST this is almost always the wrong tool — the subject already
+carries a tenant, and reaching for another one is a cross-tenant access with
+extra steps. It exists because the system subject has *no* tenant to infer.
+
+One implementation detail worth knowing, because it is counter-intuitive: the
+scoped store does **not** run as a `system` subject with a tenant attached. A
+system subject carries `tenantId: null` by construction and the tenant mixin
+special-cases it to skip scoping entirely — on a system subject, a null tenant
+means *all* tenants. So the scoped view runs as a `serviceAccount` bound to that
+one tenant, keeping the schedule's scopes.
+
 This behaves identically under `voltro dev` and `voltro serve`. It did not
 always — before 0.10.0, dev scoped schedules to `$TENANT` (default `acme`)
 while production ran them unscoped, so the same cron read one tenant in

package/templates/agent-docs/security.md

@@ -22,6 +22,54 @@ Please report suspected vulnerabilities **privately** — never in public issues
 
 You'll get an **acknowledgement within 3 business days**, an assessment once we've reproduced the issue, and a **coordinated disclosure** timeline agreed with you — with credit in the release notes if you'd like it. We don't run a paid bug-bounty program yet, but we genuinely value responsible disclosure.
 
+## Outbound HTTP is SSRF-guarded by default
+
+The `HttpClient` your handlers `yield*` refuses internal targets:
+
+- loopback, RFC-1918, CGNAT and link-local addresses — including the
+  `169.254.169.254` cloud-metadata endpoint
+- the hostnames `localhost`, `*.internal`, `*.local`
+- any non-`http(s)` scheme
+
+**Every redirect hop is revalidated, not just the URL you passed.** A public URL
+that `302`s to the metadata endpoint is the actual attack; checking only the
+initial target catches none of it.
+
+This matters because a caller-supplied URL is ordinary product surface — a
+scraper, a webhook-registration form, an importer, a "test this connection"
+button. Those reach `HttpClient` with whatever the user typed.
+
+### Allowing a target on purpose
+
+```ts
+// app.config.ts
+export default defineApiConfig({
+  http: { allowHosts: ['*.svc.cluster.local', 'billing.internal'] },
+})
+```
+
+An entry may be an exact host, a `*.suffix` wildcard (which does **not** match the
+apex — one that did would silently widen your exception), or `host:port` when only
+one port should be reachable.
+
+There is no boolean off-switch, deliberately: *"we call one internal service"* and
+*"we do not check URLs"* are different postures, and a boolean cannot tell them
+apart six months later.
+
+### In tests, allow the stub — don't mock the guard
+
+Use the same `allowHosts` to reach a local stub server (`['127.0.0.1:8787']`).
+That keeps the test on the real guarded code path with a narrow exception. Mocking
+the guard away instead means the production path is never exercised — which is
+exactly how this framework's own webhook delivery once ended up behind a
+`NODE_ENV` check.
+
+### What this does NOT cover
+
+DNS is not resolved. A public hostname that *resolves* to a private address (DNS
+rebinding) still passes. That vector needs network-layer egress control; it is
+stated here rather than silently implied.
+
 ## Supply-chain assurance
 
 Every release passes automated supply-chain gates in CI before a single package is published:

package/templates/agent-docs/templates/apibackends.md

@@ -2615,9 +2615,9 @@ done
 <!-- source: en/templates/api-rbac.md -->
 ## API · RBAC
 
-_Role-based access control with @voltro/plugin-rbac — a role→scope map, an interceptor that resolves the caller's roles to scopes, and an in-handler permission(ctx, 'notes:write') guard that fails typed ScopeError. admin:full bypasses. Config-only, zero infra; useCan() for web UI._
+_Role-based access control with @voltro/plugin-rbac — a role→scope map, an interceptor that resolves the caller's roles to scopes, declarative descriptor guards (statically checked by voltro check), resource-scoped guards, and the in-handler permission()/can() guards. admin:full bypasses. Config-only, zero infra._
 
-Roles → scopes → guards. `@voltro/plugin-rbac` compiles a role map and an rpc interceptor resolves each caller's **roles** to **scopes**, stamped on the subject. Guard handlers with `permission(ctx, 'notes:write')`, the Effect-native guard that fails typed `ScopeError`. The `admin:full` scope is a blanket bypass. Config-only, zero infra. Template id: **`api-rbac`**.
+Roles → scopes → guards. `@voltro/plugin-rbac` compiles a role map, and an rpc interceptor resolves each caller's **roles** into **scopes** published to the framework's effective-scope seam. From there both authorization forms see them. The `admin:full` scope is a blanket bypass. Config-only, zero infra. Template id: **`api-rbac`**.
 
 ## Scaffold
 
@@ -2627,40 +2627,99 @@ voltro create-project acme --api=api-rbac
 
 ## Roles as config
 
-```ts
-// app.config.ts
-import { rbacPlugin } from '@voltro/plugin-rbac'
+The role map is the app's **declared scope vocabulary**, not just a lookup table: `rbacPlugin` publishes the union of it, and [`voltro check`](/docs/cli/overview) fails on any descriptor guard requiring a scope that appears nowhere in it.
 
-const roles = {
+```ts
+// authz.ts — split out of app.config.ts so tests build the real plugin
+export const roles = {
   viewer: ['notes:read'],
   editor: ['notes:read', 'notes:write'],
-  admin:  ['admin:full'],                 // blanket bypass — passes every check
+  owner:  ['notes:read', 'notes:write', 'notes:delete', 'teams:rename'],
+  admin:  ['*'],                          // wildcard → admin:full blanket bypass
 }
+```
+
+```ts
+// app.config.ts
+import { rbacPlugin } from '@voltro/plugin-rbac'
+import { demoRolesForTenant, roles, rolesOnTeam } from './authz'
 
 rbacPlugin({
   roles,
   // PRODUCTION: the default resolver reads subject.metadata.roles (set by your
   // auth strategy), or do a DB lookup. The shipped DEMO maps tenant → role so
-  // you can try each via the x-tenant header with zero auth setup:
-  resolveRoles: (subject) =>
-    ({ acme: ['admin'], editors: ['editor'], readers: ['viewer'] })[subject.tenantId ?? ''] ?? ['viewer'],
+  // you can try each via the x-tenant header with zero auth setup.
+  resolveRoles: (subject) => demoRolesForTenant(subject.tenantId),
+  // PER-RESOURCE roles — see "Resource-scoped guards" below.
+  resolveResourceRoles: (subject, resource) => rolesOnTeam(subject.id, resource),
 })
 ```
 
-## Guard with `permission()`
+## Two guard forms — prefer the declarative one
 
 ```ts
-// notes.create.mutation.server.ts
-import { permission } from '@voltro/plugin-rbac'
+// notes.create.mutation.ts — DECLARATIVE, on the descriptor
+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 }),
+  output: Schema.Struct({ id: Schema.String, title: Schema.String }),
+})
+```
+
+The framework enforces this in the dispatch spine — before the executor, and before a mutation's transaction opens — so an unauthorized call never touches the DB. Declaring `guards:` also merges `ScopeError` into the wire error union automatically, so no `error:` field is needed and the client still decodes the denial typed. Reads take guards too, re-checked on every delivery, so a revoked role stops a live subscription.
 
+The reason to prefer it is **static checkability**: a declarative guard lands in the capability manifest, so `voltro check` catches a scope no role grants. An in-handler call is invisible to that check.
+
+```ts
+// notes.delete.mutation.server.ts — IN-HANDLER, for what needs the loaded row
 export default (input, ctx) => Effect.gen(function* () {
-  yield* permission(ctx, 'notes:write')       // fails typed ScopeError for viewer
   const store = yield* EffectStore
-  return yield* store.insert('notes', { title: input.title, body: input.body })
+  const rows = yield* Effect.promise(() =>
+    ctx.store.query(database.notes.where(eq('id', input.id)).limit(1).descriptor))
+  const note = rows[0]
+  if (note === undefined) return yield* Effect.fail(new NoteNotFound({ id: input.id }))
+
+  // Only decidable AFTER the row is loaded — no descriptor guard can express it.
+  const hard = note['archived'] === true || can(ctx, 'notes:purge')
+  if (hard) { yield* store.delete('notes', input.id); return { id: input.id, mode: 'hard' } }
+  yield* store.update('notes', input.id, { archived: true })
+  return { id: input.id, mode: 'soft' }
 })
 ```
 
-Declare `error: ScopeError` (from `@voltro/protocol`). Companions: `anyPermission(ctx, [...])` (OR), `assertPermission` (sync throw), `can(ctx, scope)` (boolean).
+Rule of thumb: put in `guards:` everything decidable from the **subject** and the **input**; reach for `permission()` / `can()` only for what needs loaded data. Companions: `anyPermission(ctx, [...])` (OR), `assertPermission` (sync throw), `can(ctx, scope)` (boolean, branches instead of refusing).
+
+## Resource-scoped guards
+
+`guards: [{ scope, resource }]` makes a grant mean "owner **of this team**" instead of "owner globally".
+
+```ts
+// teams.rename.mutation.ts
+guards: [{ scope: 'teams:rename', resource: (input: { teamId: string }) => input.teamId }],
+```
+
+The `resource` extractor pulls the id out of the decoded input; rbac's `resolveResourceRoles` returns the roles the caller holds on that id, compiled through the same role map. A **globally** held scope (or `admin:full`) satisfies the guard without the resolver ever being called — only the gap falls through. That fall-through is **fail-closed**: a resolver that throws or rejects denies, it does not degrade to the global answer.
+
+## Failure postures, deliberately different
+
+| Resolver | On throw / reject |
+| --- | --- |
+| `resolveRoles` / `resolvePermissions` | logs, degrades to the subject's **own** scopes — never grants, but an api key with valid scopes still works |
+| `resolveResourceRoles` | **denies** (fail-closed) |
+
+Both hold for a synchronous throw as well as a rejected promise.
+
+## Static check
+
+```bash
+voltro check --offline      # no running app needed — usable as a CI gate
+```
+
+A guard requiring `notes:wirte` when the roles grant `notes:write` is not merely misconfigured: that procedure is permanently, silently uncallable by everyone. `voltro check` reports it as `rbac/unknown-scope` and exits non-zero.
+
+The registry stays **dormant** when a custom `resolvePermissions` is configured — that resolver merges scopes from outside the role map by design, so publishing the map alone would flag correct code.
 
 ## Try it
 
@@ -2676,6 +2735,18 @@ curl -s localhost:4000/_voltro/inspect/invoke -H 'content-type: application/json
 # → { ok:false, error:{ _tag:"ScopeError", required:"notes:write" } }
 ```
 
+## Testing authorization
+
+The shipped `tests/authz.test.ts` drives the **real** plugin: `makeTestContext({ plugins: [rbacPlugin({ roles, … })] })` composes the actual interceptor chain, and `invoke` enforces the descriptor's guards with the same function the serve pipeline calls.
+
+```ts
+const ctx = makeTestContext({ subject, store: mockStore({ notes: [] }), plugins: [plugin()] })
+await expect(invoke(createNote, createNoteHandler, { title: 'x', body: '' }, ctx))
+  .rejects.toMatchObject({ _tag: 'ScopeError', required: 'notes:write' })
+```
+
+Do **not** hand-set `subject.scopes` to the value you expect. That tests the guard while assuming the resolution which produces it — and the resolution is the half that actually breaks (a renamed role, a throwing resolver, a scope no role grants). Those all pass a pre-stamped test and fail a real one.
+
 ## On the web side
 
 ```tsx
@@ -2686,7 +2757,7 @@ const canWrite = useCan('notes:write')
 {canWrite && <NewNoteButton />}      // hide affordances the user can't use
 ```
 
-The UI gate ships in [`@voltro/client`](/docs/ui/client-utilities/use-can), not in the plugin: scopes are a framework concept, so gating a button must not require an rbac dependency. `useCan` is a UI affordance only — the server `permission()` guard is the enforcement.
+The UI gate ships in [`@voltro/client`](/docs/ui/client-utilities/use-can), not in the plugin: scopes are a framework concept, so gating a button must not require an rbac dependency. `useCan` is a UI affordance only — the server guard is the enforcement.
 
 ## Persisted roles
 
@@ -2695,6 +2766,8 @@ Set `tables: true` to store assignments in `roles` / `userRoles` tables and reso
 ## Anti-patterns
 
 - **Returning scopes from `resolveRoles`.** It returns role SLUGS (`['editor']`); the `roles` map turns those into scopes. Returning scopes directly bypasses the map.
+- **Re-checking a descriptor guard inside its own executor.** Two copies of one rule, and the copy `voltro check` reads is the descriptor's.
+- **Reaching for `permission()` when `guards:` would do.** It works, but it opts that procedure out of the static check.
 - **Scopes ≠ entitlements.** RBAC answers "may you call this"; billing entitlements (see [`api-saas`](/docs/templates/api-saas)) answer "do you have quota left". A procedure can need both.