@voltro/cli 0.4.0 → 0.5.0

package/dist/serveEntry.js

@@ -1,4 +1,4 @@
-import { jt as e, rt as t } from "./dev-CQxbrpDz.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-BZzUJIyo.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.4.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.4.0",
-    "@voltro/cache": "0.4.0",
-    "@voltro/data-transfer": "0.4.0",
-    "@voltro/database": "0.4.0",
-    "@voltro/env": "0.4.0",
-    "@voltro/kv": "0.4.0",
-    "@voltro/logger": "0.4.0",
-    "@voltro/plugin-auth": "0.4.0",
-    "@voltro/plugin-broadcast": "0.4.0",
-    "@voltro/plugin-mail": "0.4.0",
-    "@voltro/plugin-storage": "0.4.0",
-    "@voltro/plugin-webhooks": "0.4.0",
-    "@voltro/protocol": "0.4.0",
-    "@voltro/runtime": "0.4.0",
-    "@voltro/serverless": "0.4.0",
-    "@voltro/workflow": "0.4.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,90 @@ 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

package/templates/AGENTS.md

@@ -61,6 +61,90 @@ 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

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",

package/templates/agent-docs/ai.md

@@ -1717,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.
@@ -1729,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 }) =>
@@ -1739,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

@@ -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`

package/templates/agent-docs/cli.md

@@ -30,6 +30,7 @@ The dispatcher routes `voltro <command> [args]` to the matching subcommand and p
 | Ops / infra | `cache` (`status` / `flush` / `invalidate`), `add` (`redis`), `baseline` (`list` / `status` / `set`), `schedule-manifest`, [`storage`](/docs/plugins/storage) (`doctor` / `cors`) |
 | AI / data | `embeddings backfill <table> --text <field> --vector <field>` — (re)embed rows the `vectorEmbedding()` mixin missed (pre-existing rows / a model change); `--dry-run` to preview |
 | [Inspect & debug](/docs/cli/inspect) | `inspect`, `logs`, `traces`, `workflows`, `cluster`, `check` |
+| [Health & surface](/docs/cli/build-and-start) | [`doctor`](/docs/cli/build-and-start) — serve preflight + the hand-roll detector (names the shipped primitive at the spot you're rebuilding it); [`capabilities`](/docs/cli/build-and-start) (`--json`) — the export surface read from your installed `@voltro/*`, so it can be verified instead of recalled |
 | Harness | `test`, `e2e` |
 | Cloud | `cloud` (`login` / `whoami` / `projects` / `env` / `import`) |
 | Secrets | `secret` (`generate [purpose]` — the right var+format per secret; `generate` alone → a generic secret; `list`) |
@@ -739,6 +740,81 @@ Docker step) and prints the exact remedy: add a `voltro build .` step before
 `voltro serve .`. Drop it into your image build right after `voltro build` to
 guarantee the artefact is present before the image ships.
 
+### The hand-roll detector
+
+`voltro doctor` also scans your source for shapes the framework already has a
+primitive for, and names the primitive at the spot the hand-roll lives. This is
+**advisory and never blocking** — it prints, it does not fail your build.
+
+```bash
+voltro doctor .
+```
+
+```text
+•  Shipped primitives you may be hand-rolling:
+   [server]
+   hand-written not-found branch on rows[0] — 12 file(s): queries/team.get.ts, …
+     → .one() — fails with the typed NoRowFound on zero rows AND on more than one
+   [client]
+   per-field useState + a submit flag (hand-rolled form) — 4 file(s): src/create-dialog.tsx, …
+     → useFormBinding — fields + validation from the mutation input Schema
+```
+
+It covers both halves of the stack:
+
+| Scope | It notices | Reach for |
+|---|---|---|
+| server | `if (!rows[0]) throw …` | `.one()` / `.first()` |
+| server | 3+ sequential `store.query` in one handler | `relations()` + `.with()` |
+| server | `Effect.promise(() => ctx.store.…)` | `yield* EffectStore` |
+| server | `requireScope(...)` at the top of an executor | `guards:` on the descriptor |
+| server | a `token` / `secret` / `password` column with no encryption | `.encrypted()` |
+| server | a notify / webhook helper called at a mutation's tail | `defineSubscriber` / `defineReaction` |
+| server | `hasMore` + `limit + 1` | `paginateById` |
+| client | per-field `useState` + a submit flag | `useFormBinding` |
+| client | a table with local sort/filter state | `useDataTable` |
+| client | `FileReader` / `readAsDataURL` | `useUpload` |
+| client | `setTimeout` debounce in a `useEffect` | `useDebounced` |
+| client | `useMemo` fanning in several subscriptions | `useDerived` |
+| client | a local Next.js compat shim | the native `@voltro/web` exports |
+| client | a hand-rolled presence heartbeat | `@voltro/plugin-presence` |
+
+The rules are deliberately conservative — a detector that cries wolf trains you
+to ignore it. A column that already carries `.encrypted()`, or a handler that
+already uses `.one()`, stays silent.
+
+## `voltro capabilities` — what the framework actually exports
+
+Asked "what does this framework export", a language model will produce a
+confident answer whether or not it knows. This command replaces that guess with
+a reading of the `.d.ts` files in your own `node_modules`:
+
+```bash
+voltro capabilities              # human summary, grouped by package
+voltro capabilities --json       # the full machine-readable surface
+```
+
+```text
+voltro capabilities — 2517 exported symbols across 36 packages
+  @voltro/runtime@0.4.0 — 9 primitives, 41 values, 118 types
+    defineAggregate, defineReaction, defineSubscriber, defineResourcePolicy, …
+  @voltro/client@0.4.0 — 47 hooks, 12 components, 60 types
+    useSubscription, useMutation, useFormBinding, useDataTable, useUpload, …
+
+  * 8 primitive(s)/hook(s) appear nowhere in this project's agent guide:
+      @voltro/plugin-mail: defineEmail
+      …
+```
+
+Every symbol reported was read out of an installed package a moment ago, so an
+agent can **verify** the surface instead of recalling it. The `--json` form is
+stable and locale-independent — the same tree produces byte-identical output on
+every machine, so you can diff it across upgrades.
+
+Symbols marked `*` ship but appear nowhere in this project's seeded `AGENTS.md`
+/ `CLAUDE.md`. Refresh the guide with `voltro agents-md --force`, or read that
+package's README.
+
 ## Anti-patterns
 
 - **Running `voltro start` against a directory without `dist/`.** It exits 1 with a clear `no built dist found — run voltro build first` (checked against `.framework/dist/index.html` before any heavy work). Run `voltro build` first.

package/templates/agent-docs/data.md

@@ -408,12 +408,14 @@ export default async (
     tenantId: ctx.request.subject.tenantId,
   })
 
-  return { id: inserted['id'] as string }
+  return { id: String(inserted['id']) }
 }
 ```
 
 The descriptor is the wire contract. The `.mutation.server.ts` file is the server-only implementation.
 
+`insert` returns the post-image as an untyped `Row` (`Readonly<Record<string, unknown>>`), so narrow the field you need (`String(...)`) instead of asserting it with `as string` — an assertion silences the compiler without checking anything. To read a row back, use the fluent terminals: `ctx.store.select('notes').where('id', id).one()` fails with the typed `NoRowFound` when the row is missing (or when more than one matches), so you never need a hand-written not-found branch; `.first()` / `.maybeOne()` return `null` instead.
+
 ## What The Runtime Does
 
 1. Decode `input` with the descriptor schema.
@@ -1210,9 +1212,9 @@ export default defineAggregate({
         .descriptor,
     )
     return players.map((p, i) => ({
-      playerId: p.id as string,
+      playerId: p.id,
       rank:     i + 1,
-      kd:       p.kdRatio as number,
+      kd:       p.kdRatio,
     }))
   },
 })
@@ -1772,6 +1774,148 @@ into the agent's prompt.
 
 
 
+---
+
+<!-- source: en/data/outbox.md -->
+## Transactional outbox
+
+_ctx.outbox.enqueue — a reliable external side effect from a mutation, committed in the same transaction as the write that caused it._
+
+A mutation must not do external I/O. It runs in a transaction, and an HTTP call
+cannot be rolled back — if the request succeeds and the transaction then fails,
+you have charged a card for an order that does not exist.
+
+So "write this row **and** sync it to Jira" has no correct one-step form. The
+usual workaround is to build one: a deliveries table written inside the
+transaction, a cron that drains it, and a worker with backoff and a dead-letter.
+That is a real subsystem, and every integration app rebuilds it.
+
+`ctx.outbox` is that subsystem, as a one-liner.
+
+```ts
+// apps/api/mutations/ticket.create.server.ts
+export default async (input: { title: string }, ctx: AppContext) => {
+  const ticket = await ctx.store.insert('tickets', { title: input.title })
+
+  await ctx.outbox.enqueue('jira.sync', { ticketId: ticket.id }, {
+    idempotencyKey: `jira.sync:${ticket.id}`,
+  })
+
+  return { id: ticket.id }
+}
+```
+
+## Why this is correct, not just convenient
+
+`enqueue` writes through `ctx.store` — and inside a mutation, `ctx.store` **is
+the transactional view**. The outbox row commits in the same transaction as the
+domain write, or neither does.
+
+That is the whole guarantee. There is no window in which the ticket exists and
+the intent to sync it was lost, because losing the intent means the ticket was
+rolled back too.
+
+This is what separates it from reacting to a change *after* commit. A
+post-commit tap — including `@voltro/plugin-cdc-out`, which says so plainly —
+is at-least-once **from enqueue**: a crash between the commit and the tap loses
+the event. Here, enqueue cannot be lost.
+
+Delivery *after* commit is still at-least-once. That is the strongest guarantee
+available without a distributed transaction into the target system, so:
+
+**Handlers must be idempotent.** A process that dies between "the remote
+accepted it" and "we recorded that" will retry.
+
+## Declaring the handler
+
+One `*.outbox.ts` file per effect:
+
+```ts
+// apps/api/outbox/jira.sync.outbox.ts
+import { defineOutboxHandler } from '@voltro/runtime'
+
+export default defineOutboxHandler({
+  effect: 'jira.sync',
+  maxAttempts: 5,
+  handler: async ({ payload, attempt, subjectId, traceId }) => {
+    await jira.syncIssue(payload['ticketId'] as string)
+  },
+})
+```
+
+The handler runs **after** the enqueuing transaction committed, outside it, and
+may do external I/O — that is the point. It receives the payload, the attempt
+number, and the subject / tenant / trace of whoever enqueued it.
+
+Two handlers claiming the same `effect` is refused at boot with both filenames,
+rather than letting whichever loaded last silently win.
+
+## Retries, backoff, dead-letter
+
+| | |
+|---|---|
+| Retry schedule | exponential — 1s, 2s, 4s … capped at 5 minutes |
+| Default attempts | 8 (`maxAttempts` on the handler, or per-enqueue) |
+| Exhausted | row moves to `dead`, logged at ERROR, stays in the table |
+| Unknown effect | left **pending**, never discarded |
+
+That last row matters. The usual cause of an unknown effect is a deploy where
+the enqueuing code shipped ahead of its handler. Dead-lettering those would turn
+a rollout ordering detail into permanent loss of a side effect the app believes
+happened, so they wait instead.
+
+A dead-lettered row is not deleted — it is queryable in `_voltro_outbox` with
+its `lastError`, because a dead letter is a side effect your app thinks occurred
+and which never will.
+
+## Delivery, and why there is both a nudge and a poll
+
+When the transaction commits, the worker is nudged and the effect usually goes
+out in milliseconds. A poll also runs every 5 seconds.
+
+The nudge is an optimisation. The **poll is the contract**: it picks up rows
+whose nudge was lost because the process died between commit and delivery, rows
+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.
+
+## Options
+
+```ts
+await ctx.outbox.enqueue('mail.welcome', { userId }, {
+  idempotencyKey: `welcome:${userId}`,  // drop if an undelivered row has this key
+  maxAttempts: 3,                        // override the handler's default
+  delayMs: 60_000,                       // don't attempt before then
+})
+```
+
+`idempotencyKey` dedupes against rows that have not yet succeeded, so a retried
+mutation does not produce a second side effect. A **delivered** key is
+deliberately not a blocker — reusing a key later means "do it again", and
+treating it as permanently consumed would silently swallow a legitimate request.
+
+`enqueue` returns the outbox row id, which is also the delivery id: persist it
+alongside your row and a client can watch the effect's progress.
+
+## When NOT to use it
+
+- **Work that must be observable step-by-step, or that suspends** → a
+  [workflow](/docs/workflows/overview). The outbox delivers one effect; it is
+  not a durable multi-step process.
+- **Reacting to any change on a table, not to one mutation's intent** →
+  [`defineSubscriber`](/docs/data/subscribers) or
+  [`defineReaction`](/docs/data/reactions).
+- **Mirroring a table outward continuously** → `@voltro/plugin-cdc-out`, which
+  is built for reverse-ETL with per-pipe ordering.
+
+## See also
+
+- [Mutations](/docs/data/mutations) — the transaction boundary this rides
+- [Subscribers](/docs/data/subscribers) — post-commit reactions to table changes
+- [Workflows](/docs/workflows/overview) — durable multi-step work
+
+
+
 ---
 
 <!-- source: en/data/wire-protocol.md -->

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

@@ -803,10 +803,31 @@ eager-load with `.with({...})` to get the per-field pre-filter.
   inject a default depth limit.
 - **No reactivity**: see above.
 
+## When NOT to use
+
+- **Single-level parent / child** — use a regular
+  [self-join](/docs/database/self-joins). A recursive CTE is overkill
+  at depth 1.
+- **Performance-critical hot path with a large result set** —
+  recursive queries can explode on wide trees. Profile with
+  `EXPLAIN ANALYZE` against realistic data. If the iteration count
+  runs into the thousands, consider materializing the computed
+  hierarchy into a separate table instead.
+- **Arbitrary graph algorithms** (shortest path, connected
+  components) — a recursive CTE can be bent into these but it gets
+  ugly fast. A graph database (Neo4j, the AGE extension) is the
+  better fit.
+
 ## See also
 
 - [Plain CTEs](/docs/database/query-builder#ctes) — `withCte()` for
   non-recursive named sub-queries
+- [Self-joins](/docs/database/self-joins) — for single-level
+  parent/child queries
+- [Sub-queries](/docs/database/sub-queries) — for non-recursive
+  "rows where a column matches another query" patterns
+- [Set operations](/docs/database/set-operations) — `union` /
+  `unionAll`, the mechanism a recursive CTE is built on
 - [Joins](/docs/database/joins) — relation-based traversal when the
   graph depth is fixed (e.g. parent + immediate children)
 - [Aggregations](/docs/database/query-builder#aggregations) —