@voltro/cli 0.3.0 → 0.5.0

package/dist/serveEntry.js

@@ -1,4 +1,4 @@
-import { At as e, nt as t } from "./dev-x_VqbV_8.js";
+import { Nt as e, at as t } from "./dev-B71ICpXJ.js";
 import { a as n } from "./startupRunner-DhlX9nqd.js";
-import { t as r } from "./serveCommand-Dttqe5Ms.js";
+import { t as r } from "./serveCommand-C0WFA396.js";
 export { e as loadDotEnv, n as registerAppModules, t as registerDriver, r as runServe };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltro/cli",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "The `voltro` CLI — dev server, codegen, migrations, project scaffolding, agent-docs seeding, and production serve.",
   "keywords": [
     "voltro",
@@ -52,22 +52,22 @@
     "@effect/platform-node": "^0.107.0",
     "@effect/sql": "^0.51.1",
     "@effect/workflow": "^0.18.2",
-    "@voltro/ai": "0.3.0",
-    "@voltro/cache": "0.3.0",
-    "@voltro/data-transfer": "0.3.0",
-    "@voltro/database": "0.3.0",
-    "@voltro/env": "0.3.0",
-    "@voltro/kv": "0.3.0",
-    "@voltro/logger": "0.3.0",
-    "@voltro/plugin-auth": "0.3.0",
-    "@voltro/plugin-broadcast": "0.3.0",
-    "@voltro/plugin-mail": "0.3.0",
-    "@voltro/plugin-storage": "0.3.0",
-    "@voltro/plugin-webhooks": "0.3.0",
-    "@voltro/protocol": "0.3.0",
-    "@voltro/runtime": "0.3.0",
-    "@voltro/serverless": "0.3.0",
-    "@voltro/workflow": "0.3.0",
+    "@voltro/ai": "0.5.0",
+    "@voltro/cache": "0.5.0",
+    "@voltro/data-transfer": "0.5.0",
+    "@voltro/database": "0.5.0",
+    "@voltro/env": "0.5.0",
+    "@voltro/kv": "0.5.0",
+    "@voltro/logger": "0.5.0",
+    "@voltro/plugin-auth": "0.5.0",
+    "@voltro/plugin-broadcast": "0.5.0",
+    "@voltro/plugin-mail": "0.5.0",
+    "@voltro/plugin-storage": "0.5.0",
+    "@voltro/plugin-webhooks": "0.5.0",
+    "@voltro/protocol": "0.5.0",
+    "@voltro/runtime": "0.5.0",
+    "@voltro/serverless": "0.5.0",
+    "@voltro/workflow": "0.5.0",
     "chokidar": "^5.0.0",
     "ioredis": "^5.11.1",
     "ts-morph": "^28.0.0"

package/templates/AGENTS.core.md

@@ -61,6 +61,137 @@ Ask in order; stop at the first "yes":
 Deep dive: **`data.md`** (queries/mutations/actions/streams/errors),
 **`workflows.md`**, **`scheduling.md`**.
 
+### Pick the SERVER primitive (inside a handler)
+
+The four above answer "which FILE do I write". This answers "what do I write
+INSIDE it" — the part where hand-rolled boilerplate actually accumulates. Every
+line below replaces something real apps write by hand hundreds of times.
+
+1. **Loading one row you expect to exist?** → **`.one()`**
+   (`ctx.store.select('t').where('id', x).one()`). It fails with the typed
+   `NoRowFound` when there is no row — AND when there is more than one, so a
+   filter that stops being unique fails loudly instead of returning an
+   arbitrary row. `NoRowFound` is declarable in the descriptor's `error:` union.
+   Nullable variant: **`.first()`** / **`.maybeOne()`**.
+   Never `const rows = await …; if (!rows[0]) throw new NotFound()`.
+2. **Need related data — 2+ reads to assemble one result?** → declare
+   **`relations()`** (`*.relations.ts`) and eager-load with **`.with({ posts: true })`**.
+   That compiles to ONE JSON-aggregate query on every SQL dialect. Sequential
+   `store.query` calls per parent row are an N+1 you are writing on purpose.
+3. **Something must happen AFTER a mutation commits** (notify, webhook, sync)?
+   → **`defineSubscriber`** (`*.subscribe.ts`, runs any handler on a table
+   change) or **`defineReaction`** (`*.reaction.tsx`, fires a named agent or
+   workflow; requires a `dedupeKey`, supports `rateLimit` / `costBudgetUsd`).
+   Both are post-commit and receive the `old`/`new` diff. Calling a
+   notify-helper at the tail of the mutation body instead makes the reactivity
+   invisible — you can only find it by reading every executor. Both are
+   best-effort, so genuinely critical delivery still belongs in a workflow.
+4. **A roll-up / counter recomputed on every read?** → **`defineAggregate`**
+   (`*.aggregate.ts`). Add `incremental:` for `count|sum|avg|min|max` group-bys
+   and it is MAINTAINED on write rather than recomputed. `read({ where })`
+   parameterises it, so one aggregate serves per-team / per-period slices.
+5. **A permission check?** → declare **`guards:`** on the descriptor — it is
+   enforced before the executor (and before a mutation's transaction opens) and
+   fails with a typed `ScopeError`. Two kinds, same array, all must pass:
+   - `{ scope: 'notes:write' }` — may the caller do this AT ALL.
+   - `{ action, resourceType, resource: (input) => input.id }` — may they do it
+     to THIS ROW (relationship/ReBAC, against a `defineResourcePolicy`). Needs a
+     registered `setTupleSource`; **everything unanswerable DENIES** (no source,
+     no policy, no id, source throws).
+   Guards are re-checked on every subscription delivery, so a revoked grant ends
+   the stream instead of continuing to push rows. Only use `ctx.access`
+   in-handler for checks that need LOADED data. A hand-written `requireScope(...)`
+   at the top of every executor — or a hand-kept map from rpc tag to policy rule,
+   which is fail-open by omission — is what `guards:` exists to delete.
+6. **Storing a token, secret, or credential in a column?** → **`.encrypted()`**
+   on the column. Boot fails loudly if no cipher is configured, so an
+   `.encrypted()` column can never silently persist plaintext.
+7. **Writing an Effect-form handler?** → `const store = yield* EffectStore` —
+   its failures land on the typed error channel. `Effect.promise(() =>
+   ctx.store.query(…))` throws that channel away and turns a store failure into
+   a defect.
+8. **Cursor pagination?** → **`paginateBy(descriptor, column, cursor, limit,
+   direction?)`** (or **`paginateById`**, its `id`-column shorthand). Not a
+   hand-rolled limit+1 / slice / `hasMore` triple. `direction` flips the
+   COMPARISON as well as the sort — a `desc` feed pages with `<`.
+9. **Assembling data whose SHAPE depends on the data** (a tree walk where each
+   level's ids come from the level above)? → **`ctx.load` / `ctx.loadMany`** —
+   same-tick reads of one table coalesce into one `WHERE id IN (...)`, so the
+   walk costs one query per LEVEL. Use `relations()` + `.with()` whenever the
+   shape IS static; this is the fallback, not the default.
+10. **A mutation must cause an EXTERNAL side effect** (webhook, Jira sync,
+   payment)? → **`ctx.outbox.enqueue(effect, payload)`** + a
+   **`defineOutboxHandler`** in a `*.outbox.ts`. The enqueue writes through the
+   mutation's TRANSACTION, so the intent commits with the write or not at all;
+   delivery happens after commit, with backoff and a dead-letter. Do NOT call
+   the remote from the mutation (not transactional), and do not hand-build a
+   deliveries table + drain cron — that IS this primitive.
+
+| You're about to write | Reach for instead |
+|---|---|
+| `const rows = …; if (!rows[0]) throw new NotFound()` | `.one()` |
+| 3+ sequential `store.query` to assemble related data | `relations()` + `.with()` |
+| a notify/webhook helper called at the end of a mutation | `defineSubscriber` / `defineReaction` |
+| a counter recomputed by scanning rows on every read | `defineAggregate` (+ `incremental:`) |
+| `requireScope(...)` as the first line of every executor | `guards:` on the descriptor |
+| a token/secret column written as plain text | `.encrypted()` |
+| `Effect.promise(() => ctx.store.query(...))` in an Effect handler | `yield* EffectStore` |
+| hand-rolled limit+1 / `hasMore` cursor paging | `paginateBy` / `paginateById` |
+| a loop issuing one `store.query` per node of a walk | `ctx.load` / `ctx.loadMany` |
+| a deliveries table + drain cron + retry worker | `ctx.outbox.enqueue` + `defineOutboxHandler` |
+| `row['name'] as string` on every field you read | nothing — `ctx.store.query(database.t….descriptor)` already returns the table's row type. A cast here means the descriptor was hand-built, or you are casting out of habit |
+
+Deep dive: **`data.md`** (`.one()`, subscribers, reactions, aggregates),
+**`database/querying.md`** (relations + `.with`), **`authentication.md`**
+(`guards:`, resource policies), **`plugins/governance.md`** (`.encrypted()`).
+
+### Pick the CLIENT primitive (decision rubric)
+
+`useSubscription` / `useMutation` / `useAction` are the transport — they are NOT
+the whole client surface. The framework ships a **headless primitive for every
+common UI job**, each derived from the descriptor Schema you already wrote. Reach
+for one BEFORE hand-rolling; ask in order:
+
+1. **A form / any typed write UI?** → **`useFormBinding`** — fields + validation
+   derived from the mutation's input Schema, and a server
+   `ValidationError({ field })` routes itself to that field. Not per-field `useState`.
+2. **A table / list with sort, filter, pagination?** → **`useDataTable`** (columns
+   from the query's output Schema, live rows). **`useQueryFilters`** builds filter
+   controls from the query's INPUT Schema; **`useQueryField`** is the query-bound picker.
+3. **A file upload?** → **`useUpload`** (progress, cancel, provider-agnostic).
+   Not `FileReader` → base64 → action.
+4. **Gating UI on permission?** → **`useCan`** / **`useCanAny`** (scopes, from
+   `@voltro/client`, fed by `<PermissionProvider scopes>`) or
+   **`useResourceCan`** / **`useResourceCans`** (per-resource ReBAC, reactive).
+   These live in the client, not behind a plugin — scopes are a framework
+   concept, so gating a button never requires installing rbac.
+5. **A value derived from one or more subscriptions?** → **`useDerived`**
+   (dependency-tracked, referentially stable). Not a hand-maintained `useMemo` dep array.
+6. **A very large list?** → **`useWindowedSubscription`** (subscribe to the visible
+   window only, not a million rows).
+7. **Debounced input?** → **`useDebounced`**; **`useAsyncValidation`** for checks
+   that need the DB (uniqueness, cross-row) — live, over a query binding.
+8. **A loading placeholder?** → **`useFormSkeleton`** / **`useTableSkeleton`** —
+   shaped like the REAL data, from the same Schema.
+9. **Offline writes · undo · dry-run · "why is this value here?"** → **`useOutbox`**,
+   **`useUndoLog`**, **`usePreview`**, **`useProvenance`**.
+10. **Global rpc-error handling?** → **`useOnRpcError`** + **`reportClientError`**.
+
+| You're about to write | Reach for instead |
+|---|---|
+| per-field `useState` + `isSubmitting` + `resetForm()` | `useFormBinding` |
+| shadcn `<Table>` + per-table sort/filter state | `useDataTable` |
+| `FileReader` → base64 → action → `storage.put` | `useUpload` |
+| `useMemo` fanning in 3+ subscriptions | `useDerived` |
+| `setTimeout` debounce inside `useEffect` | `useDebounced` |
+| `data === undefined ? <Skeleton/> : …` | `useFormSkeleton` / `useTableSkeleton` |
+| a hand-kept page-scope check | `useCan` / `useResourceCan` |
+| a hand-rolled presence roster / notification inbox / feature flag | `@voltro/plugin-presence` / `-notifications` / `-flags` |
+
+Deep dive: **`schema-driven-ui.md`** (forms, tables, pickers, filters, skeletons),
+**`reference.md`** (the complete hook list). If you are hand-writing more than ~20
+lines of generic UI plumbing, stop and check those two first.
+
 ## Project layout
 
 One OR MORE **projects** live under `apps/`. A project (`project.json`) is the

package/templates/AGENTS.md

@@ -61,6 +61,137 @@ Ask in order; stop at the first "yes":
 Deep dive: **`data.md`** (queries/mutations/actions/streams/errors),
 **`workflows.md`**, **`scheduling.md`**.
 
+### Pick the SERVER primitive (inside a handler)
+
+The four above answer "which FILE do I write". This answers "what do I write
+INSIDE it" — the part where hand-rolled boilerplate actually accumulates. Every
+line below replaces something real apps write by hand hundreds of times.
+
+1. **Loading one row you expect to exist?** → **`.one()`**
+   (`ctx.store.select('t').where('id', x).one()`). It fails with the typed
+   `NoRowFound` when there is no row — AND when there is more than one, so a
+   filter that stops being unique fails loudly instead of returning an
+   arbitrary row. `NoRowFound` is declarable in the descriptor's `error:` union.
+   Nullable variant: **`.first()`** / **`.maybeOne()`**.
+   Never `const rows = await …; if (!rows[0]) throw new NotFound()`.
+2. **Need related data — 2+ reads to assemble one result?** → declare
+   **`relations()`** (`*.relations.ts`) and eager-load with **`.with({ posts: true })`**.
+   That compiles to ONE JSON-aggregate query on every SQL dialect. Sequential
+   `store.query` calls per parent row are an N+1 you are writing on purpose.
+3. **Something must happen AFTER a mutation commits** (notify, webhook, sync)?
+   → **`defineSubscriber`** (`*.subscribe.ts`, runs any handler on a table
+   change) or **`defineReaction`** (`*.reaction.tsx`, fires a named agent or
+   workflow; requires a `dedupeKey`, supports `rateLimit` / `costBudgetUsd`).
+   Both are post-commit and receive the `old`/`new` diff. Calling a
+   notify-helper at the tail of the mutation body instead makes the reactivity
+   invisible — you can only find it by reading every executor. Both are
+   best-effort, so genuinely critical delivery still belongs in a workflow.
+4. **A roll-up / counter recomputed on every read?** → **`defineAggregate`**
+   (`*.aggregate.ts`). Add `incremental:` for `count|sum|avg|min|max` group-bys
+   and it is MAINTAINED on write rather than recomputed. `read({ where })`
+   parameterises it, so one aggregate serves per-team / per-period slices.
+5. **A permission check?** → declare **`guards:`** on the descriptor — it is
+   enforced before the executor (and before a mutation's transaction opens) and
+   fails with a typed `ScopeError`. Two kinds, same array, all must pass:
+   - `{ scope: 'notes:write' }` — may the caller do this AT ALL.
+   - `{ action, resourceType, resource: (input) => input.id }` — may they do it
+     to THIS ROW (relationship/ReBAC, against a `defineResourcePolicy`). Needs a
+     registered `setTupleSource`; **everything unanswerable DENIES** (no source,
+     no policy, no id, source throws).
+   Guards are re-checked on every subscription delivery, so a revoked grant ends
+   the stream instead of continuing to push rows. Only use `ctx.access`
+   in-handler for checks that need LOADED data. A hand-written `requireScope(...)`
+   at the top of every executor — or a hand-kept map from rpc tag to policy rule,
+   which is fail-open by omission — is what `guards:` exists to delete.
+6. **Storing a token, secret, or credential in a column?** → **`.encrypted()`**
+   on the column. Boot fails loudly if no cipher is configured, so an
+   `.encrypted()` column can never silently persist plaintext.
+7. **Writing an Effect-form handler?** → `const store = yield* EffectStore` —
+   its failures land on the typed error channel. `Effect.promise(() =>
+   ctx.store.query(…))` throws that channel away and turns a store failure into
+   a defect.
+8. **Cursor pagination?** → **`paginateBy(descriptor, column, cursor, limit,
+   direction?)`** (or **`paginateById`**, its `id`-column shorthand). Not a
+   hand-rolled limit+1 / slice / `hasMore` triple. `direction` flips the
+   COMPARISON as well as the sort — a `desc` feed pages with `<`.
+9. **Assembling data whose SHAPE depends on the data** (a tree walk where each
+   level's ids come from the level above)? → **`ctx.load` / `ctx.loadMany`** —
+   same-tick reads of one table coalesce into one `WHERE id IN (...)`, so the
+   walk costs one query per LEVEL. Use `relations()` + `.with()` whenever the
+   shape IS static; this is the fallback, not the default.
+10. **A mutation must cause an EXTERNAL side effect** (webhook, Jira sync,
+   payment)? → **`ctx.outbox.enqueue(effect, payload)`** + a
+   **`defineOutboxHandler`** in a `*.outbox.ts`. The enqueue writes through the
+   mutation's TRANSACTION, so the intent commits with the write or not at all;
+   delivery happens after commit, with backoff and a dead-letter. Do NOT call
+   the remote from the mutation (not transactional), and do not hand-build a
+   deliveries table + drain cron — that IS this primitive.
+
+| You're about to write | Reach for instead |
+|---|---|
+| `const rows = …; if (!rows[0]) throw new NotFound()` | `.one()` |
+| 3+ sequential `store.query` to assemble related data | `relations()` + `.with()` |
+| a notify/webhook helper called at the end of a mutation | `defineSubscriber` / `defineReaction` |
+| a counter recomputed by scanning rows on every read | `defineAggregate` (+ `incremental:`) |
+| `requireScope(...)` as the first line of every executor | `guards:` on the descriptor |
+| a token/secret column written as plain text | `.encrypted()` |
+| `Effect.promise(() => ctx.store.query(...))` in an Effect handler | `yield* EffectStore` |
+| hand-rolled limit+1 / `hasMore` cursor paging | `paginateBy` / `paginateById` |
+| a loop issuing one `store.query` per node of a walk | `ctx.load` / `ctx.loadMany` |
+| a deliveries table + drain cron + retry worker | `ctx.outbox.enqueue` + `defineOutboxHandler` |
+| `row['name'] as string` on every field you read | nothing — `ctx.store.query(database.t….descriptor)` already returns the table's row type. A cast here means the descriptor was hand-built, or you are casting out of habit |
+
+Deep dive: **`data.md`** (`.one()`, subscribers, reactions, aggregates),
+**`database/querying.md`** (relations + `.with`), **`authentication.md`**
+(`guards:`, resource policies), **`plugins/governance.md`** (`.encrypted()`).
+
+### Pick the CLIENT primitive (decision rubric)
+
+`useSubscription` / `useMutation` / `useAction` are the transport — they are NOT
+the whole client surface. The framework ships a **headless primitive for every
+common UI job**, each derived from the descriptor Schema you already wrote. Reach
+for one BEFORE hand-rolling; ask in order:
+
+1. **A form / any typed write UI?** → **`useFormBinding`** — fields + validation
+   derived from the mutation's input Schema, and a server
+   `ValidationError({ field })` routes itself to that field. Not per-field `useState`.
+2. **A table / list with sort, filter, pagination?** → **`useDataTable`** (columns
+   from the query's output Schema, live rows). **`useQueryFilters`** builds filter
+   controls from the query's INPUT Schema; **`useQueryField`** is the query-bound picker.
+3. **A file upload?** → **`useUpload`** (progress, cancel, provider-agnostic).
+   Not `FileReader` → base64 → action.
+4. **Gating UI on permission?** → **`useCan`** / **`useCanAny`** (scopes, from
+   `@voltro/client`, fed by `<PermissionProvider scopes>`) or
+   **`useResourceCan`** / **`useResourceCans`** (per-resource ReBAC, reactive).
+   These live in the client, not behind a plugin — scopes are a framework
+   concept, so gating a button never requires installing rbac.
+5. **A value derived from one or more subscriptions?** → **`useDerived`**
+   (dependency-tracked, referentially stable). Not a hand-maintained `useMemo` dep array.
+6. **A very large list?** → **`useWindowedSubscription`** (subscribe to the visible
+   window only, not a million rows).
+7. **Debounced input?** → **`useDebounced`**; **`useAsyncValidation`** for checks
+   that need the DB (uniqueness, cross-row) — live, over a query binding.
+8. **A loading placeholder?** → **`useFormSkeleton`** / **`useTableSkeleton`** —
+   shaped like the REAL data, from the same Schema.
+9. **Offline writes · undo · dry-run · "why is this value here?"** → **`useOutbox`**,
+   **`useUndoLog`**, **`usePreview`**, **`useProvenance`**.
+10. **Global rpc-error handling?** → **`useOnRpcError`** + **`reportClientError`**.
+
+| You're about to write | Reach for instead |
+|---|---|
+| per-field `useState` + `isSubmitting` + `resetForm()` | `useFormBinding` |
+| shadcn `<Table>` + per-table sort/filter state | `useDataTable` |
+| `FileReader` → base64 → action → `storage.put` | `useUpload` |
+| `useMemo` fanning in 3+ subscriptions | `useDerived` |
+| `setTimeout` debounce inside `useEffect` | `useDebounced` |
+| `data === undefined ? <Skeleton/> : …` | `useFormSkeleton` / `useTableSkeleton` |
+| a hand-kept page-scope check | `useCan` / `useResourceCan` |
+| a hand-rolled presence roster / notification inbox / feature flag | `@voltro/plugin-presence` / `-notifications` / `-flags` |
+
+Deep dive: **`schema-driven-ui.md`** (forms, tables, pickers, filters, skeletons),
+**`reference.md`** (the complete hook list). If you are hand-writing more than ~20
+lines of generic UI plumbing, stop and check those two first.
+
 ## Project layout
 
 One OR MORE **projects** live under `apps/`. A project (`project.json`) is the

package/templates/agent-docs/_manifest.json

@@ -53,7 +53,7 @@
       "group": null,
       "description": "How Voltro's reactive data layer works — queries, mutations, actions, streams, all over one WebSocket with typed errors and tracked dependencies.",
       "path": "agent-docs/data.md",
-      "files": 13
+      "files": 14
     },
     {
       "id": "database/advancedqueries",
@@ -170,7 +170,7 @@
       "group": null,
       "description": "Voltro's i18n layer (@voltro/i18n) — an opinionated wrap over react-intl, auto-wired from a single app.config.ts field, with cookie + Accept-Language locale resolution.",
       "path": "agent-docs/internationalization.md",
-      "files": 3
+      "files": 4
     },
     {
       "id": "introduction",
@@ -242,7 +242,7 @@
       "group": null,
       "description": "Project the typed descriptor graph into UI — forms, tables, pickers, and reactive components, all bound to a descriptor with near-zero glue.",
       "path": "agent-docs/schema-driven-ui.md",
-      "files": 13
+      "files": 23
     },
     {
       "id": "security",
@@ -305,7 +305,7 @@
       "group": null,
       "description": "Voltro's test story — the @voltro/testing package, the test pyramid (unit handlers/tools → workflow runner → e2e), and the voltro test / voltro e2e CLI commands.",
       "path": "agent-docs/testing.md",
-      "files": 4
+      "files": 5
     },
     {
       "id": "workflows",

package/templates/agent-docs/ai.md

@@ -1019,6 +1019,34 @@ It returns a `Stream<SeqEvent>` — each element is `{ seq, event }`. The descri
 
 On the client, `useResumableAgentStream('app', 'support.run')` does the rest: it unwraps each `SeqEvent` (so `.events` are the plain inner events), tracks the highest `seq`, and on a transport drop BEFORE the run's terminal event it auto-reconnects with `fromSeq` = the last seq it rendered (exponential backoff; the no-progress cap resets whenever a reconnect delivers a new event, so a long flaky stream survives any number of well-spaced drops). The server replays past the cursor, then continues — one seamless stream.
 
+The hook's own surface is small:
+
+```tsx
+import { useResumableAgentStream } from '@voltro/client'
+import type { AgentEvent } from '@voltro/ai/events'
+
+const run = useResumableAgentStream<AgentEvent>('app', 'support.run')
+
+// `input` MUST carry the resume key — `fromSeq` is injected by the hook.
+run.start({ streamId, message: prompt })
+run.cancel()
+```
+
+| Field | Meaning |
+|---|---|
+| `events` | The unwrapped inner events so far, in order and deduped by `seq`. |
+| `status` | `'idle'`, `'streaming'`, `'reconnecting'`, `'done'`, or `'error'`. |
+| `reconnects` | How many times the transport dropped and auto-reconnected this run. |
+| `error` | Set when `status === 'error'`. |
+| `start(input?)` | Begins a run, clearing previous events. |
+| `cancel()` | Stops the run and any pending reconnect. |
+
+A third options argument tunes the reconnect policy: `maxReconnects` (default
+`6`), `backoffMs` (`400`), `maxBackoffMs` (`8000`), and `isTerminal` — which
+defaults to treating an `AgentEvent`-shaped `{ _tag: 'done' | 'error' }` as the
+end of the run. Override `isTerminal` when your element type signals completion
+some other way, or the hook will keep trying to resume a finished stream.
+
 For multi-node deployments use `dataStoreResumableStreamStore(ctx.store)` — it persists to the framework's own database (`streamEventsTable` + `streamStateTable`, register them in your `database/index.ts`) and elects exactly ONE producer per `streamId` via an atomic claim, so only one node runs the model while every node's consumers tail the shared log. Sweep finished streams with `gcResumableStreams(store, { olderThan })`.
 
 For the fastest path, `redisResumableStreamStore(redis, { ttlSeconds })` backs the log with a Redis LIST (`RPUSH`/`LRANGE`) plus a `SET … NX` producer claim — TTL evicts finished/abandoned streams without a sweep. `@voltro/ai` takes no Redis dependency; you inject a tiny `ResumableRedis` client (five methods: `setNx` / `rpush` / `lrange` / `set` / `exists`) adapting ioredis / node-redis. All three backends satisfy the same `ResumableStreamStore` interface, so they swap without touching the producer/consumer code.
@@ -1689,6 +1717,7 @@ export const ask = defineAction({
 ```ts
 // copilot.ask.action.server.ts — the server executor (imports @voltro/ai)
 import { Effect } from 'effect'
+import { EffectStore } from '@voltro/runtime'
 import { runDataCopilot, generateObject, CopilotProposalSchema, type CopilotSchema } from '@voltro/ai'
 
 // The manifest the model is constrained to — only these tables/columns exist.
@@ -1701,6 +1730,7 @@ const schema: CopilotSchema = {
 
 const execute = (input: { question: string }, ctx: AppContext) =>
   Effect.gen(function* () {
+    const store = yield* EffectStore
     const v = yield* Effect.promise(() =>
       runDataCopilot(input.question, schema, {
         propose: ({ system, prompt }) =>
@@ -1711,13 +1741,15 @@ const execute = (input: { question: string }, ctx: AppContext) =>
     )
     if (!v.ok) return { ok: false as const, reason: v.rejection.reason }
     // The validated SELECT runs AS the subject → tenant + row scope apply.
-    const rows = yield* Effect.promise(() => ctx.store.query(v.descriptor as never))
-    return { ok: true as const, rows: rows as ReadonlyArray<Record<string, unknown>> }
+    const rows = yield* store.query(v.descriptor)
+    return { ok: true as const, rows }
   })
 
 export default execute
 ```
 
+`v.descriptor` is already a `QueryDescriptor`, so nothing needs casting. In an Effect-form executor read through `EffectStore` (`yield* EffectStore`) rather than lifting `ctx.store.query` with `Effect.promise` — the lift discards the typed `StoreError` channel that `store.query` gives you.
+
 ## Client: `useDataCopilot` + `<DataCopilot>`
 
 The hook is a thin binding over `useAction` — it imports **nothing** from

package/templates/agent-docs/authentication.md

@@ -403,7 +403,7 @@ if (!canTrigger) throw new Unauthorised({})
 ```ts
 import { permission } from '@voltro/plugin-rbac'
 
-yield* permission(ctx, 'admin:full')   // Effect<void, Forbidden>
+yield* permission(ctx, 'admin:full')   // Effect<void, ScopeError>
 ```
 
 See [the RBAC plugin](/docs/plugins/rbac) for the full model.
@@ -1732,6 +1732,75 @@ export const todoPolicy = defineResourcePolicy({
 })
 ```
 
+## Enforce it declaratively — `guards:`
+
+`can` / `assertCan` above are the imperative form: you load the tuples and make
+the decision inside the handler. That works, and it is what you reach for when
+the check needs data you have already loaded.
+
+For the ordinary case — "may this caller perform ACTION on the row this input
+names?" — declare it on the descriptor instead:
+
+```ts
+export const todoUpdate = defineMutation({
+  name: 'todos.update',
+  input: Schema.Struct({ id: Schema.String, title: Schema.String }),
+  output: Schema.Void,
+  guards: [{ action: 'edit', resourceType: 'todo', resource: (input) => input.id }],
+})
+```
+
+The framework resolves it BEFORE the executor runs — for a mutation, before the
+transaction opens — and fails with a typed `ScopeError` naming
+`<resourceType>:<action>`.
+
+Why the declarative form is not just shorter: an in-handler check is one an
+author can forget, and a forgotten check is a silent hole rather than an error.
+The same is true of the older pattern of hand-maintaining a map from rpc tag to
+policy rule and installing it as an interceptor — that map is **fail-open by
+omission**: add an endpoint, forget the entry, and nothing anywhere tells you.
+A guard on the descriptor cannot be forgotten for an rpc that exists, because
+it is part of the rpc.
+
+Scope guards and relationship guards live in the same array and ALL must pass:
+
+```ts
+guards: [
+  { scope: 'todos:write' },                                        // may you edit todos at all
+  { action: 'edit', resourceType: 'todo', resource: (i) => i.id }, // may you edit THIS one
+]
+```
+
+### Activate it: register a tuple source
+
+A relationship guard needs to read the caller's relations. That comes from the
+registered **tuple source**:
+
+```ts
+// app.config.ts or a *.startup.ts
+import { setTupleSource, loadResourceTuples } from '@voltro/runtime'
+
+setTupleSource((req) =>
+  loadResourceTuples(store, req.subjectId, req.resourceType, req.resourceId))
+```
+
+`voltro dev` / `voltro serve` register exactly this default for you, reading
+`_voltro_rebac_tuples`. Register your own when your relationships already live
+in your own tables — a `teamMembers` row is a relation; you should not have to
+copy it into a framework table to authorize against it.
+
+**Every unanswerable case denies.** No tuple source registered, no policy for
+that `resourceType`, an input that doesn't identify a resource, a tuple source
+that throws — each is a denial, not a pass. An authorization question nobody can
+answer is a refusal; treating it as a pass is how a policy layer ends up
+enforcing nothing while looking like it does.
+
+### Guards are re-checked on every subscription delivery
+
+A subscription is a long-lived grant. Its guards — scope and relationship alike
+— are re-evaluated before each delivery, so revoking a relation mid-session ends
+the stream with the typed error instead of continuing to push rows.
+
 ## Decide — `can` / `assertCan`
 
 `can(subject, action, resource, { policy, tuples })` is the decision; `assertCan`
@@ -1778,9 +1847,12 @@ the headline that builds on it.)
 import { useResourceCan } from '@voltro/client'
 
 const canEdit = useResourceCan('app', 'todos.can', { action: 'edit', resourceType: 'todo', resourceId: id })
-// canEdit.allowed: boolean | undefined (undefined until resolved); reactive.
+// canEdit.allowed: boolean (false until the first verdict); canEdit.pending: boolean.
 ```
 
+Full API — including the batch `useResourceCans` for per-row gating — in
+[usePermissions](/docs/ui/client-utilities/use-permissions).
+
 ## Capability map
 
 `rebacPolicyGraph()` returns every resource type, its actions, the relations each