@voltro/cli 0.3.0 → 0.5.0

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`) |
@@ -722,6 +723,98 @@ For WebSocket connections to land on the same backend (required for in-process s
 - Reverse proxy: `lb_policy ip_hash` (Caddy) / `ip_hash` (nginx).
 - Or use `@voltro/plugin-cluster` to share subscription state across instances → any-load-balancer-works.
 
+## `voltro doctor` — preflight a production serve
+
+Production `voltro serve` for an **API** app boots ONLY from the precompiled serve
+bundle and is **fatal if it's missing** — a hand-rolled Dockerfile that runs
+`voltro serve` without a prior `voltro build` breaks at deploy. `voltro doctor`
+(or `voltro serve --preflight`) catches that at BUILD time instead of cold-start:
+
+```bash
+voltro doctor .                 # check the serve bundle exists; print the fix if not
+voltro serve --preflight .      # same check, then exit — never boots
+```
+
+It exits **1** when the serve bundle is missing on an API app (so it fails a CI /
+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.
@@ -1672,8 +1765,30 @@ voltro update --to 0.4.0      # pin an explicit target version
 voltro update --dry-run       # preview the bump + which codemods would run — writes nothing
 voltro update --force         # allow a dirty working tree (not recommended)
 voltro update --exact         # pin exact versions (drop the ^ / ~ range prefix)
+
+# Recover the codemods after a MANUAL version bump (no bump, no install):
+voltro update --codemods-only --from 0.3.0            # re-run codemods 0.3.0 → installed
+voltro update --codemods-only --from 0.3.0 --to 0.4.0 # explicit delta
+```
+
+## Already bumped by hand? Recover the codemods
+
+If you bump `@voltro/*` versions in `package.json` yourself and install first, a
+plain `voltro update` sees the installed version already equals the target and
+reports **"already on X — nothing to do"** — skipping the codemods AND the
+printed manual steps for the delta you actually crossed. To re-apply them without
+touching `package.json` again:
+
+```bash
+voltro update --codemods-only --from <version-you-came-from>
 ```
 
+`--codemods-only` (alias `--run-codemods`) runs the codemods + manual notes for
+`[from, to]` against the already-installed tree — no version bump, no install.
+`--to` defaults to the installed version; pass it to pin an explicit delta.
+`--from` also works on a normal `voltro update` to override the auto-detected
+source version.
+
 ## The clean-tree guard
 
 Codemods **rewrite your source**, so you need a clean diff to review afterwards. `voltro update` refuses to run on a dirty git working tree — commit or stash first. Use `--dry-run` to preview without touching anything, or `--force` to override the guard (you accept a mixed diff).

package/templates/agent-docs/data.md

@@ -315,6 +315,40 @@ Queries are streaming RPCs whose elements are **subscription events**: an initia
 - **Using a stream for durable data.** Streams are transient. Persist rows and expose them through a query when the UI should survive reloads or sync across tabs.
 
 
+## Loading vs empty — don't conflate them
+
+`useSubscription` returns `loading` and `isEmpty` alongside `data`. They are
+**different** states, and branching on `data === undefined` alone is what causes
+a flash of empty-state before the first snapshot:
+
+| State | Meaning | Render |
+|---|---|---|
+| `loading` | no snapshot has arrived yet | skeleton |
+| `isEmpty` | snapshot arrived, zero rows (or a null value) | empty state |
+| neither | rows present | the list |
+
+```tsx
+const { data, loading, isEmpty } = useSubscription<Note[]>('app', 'notes.list', {})
+if (loading) return <TableSkeleton/>
+if (isEmpty) return <EmptyNotes/>
+return <NotesTable notes={data!}/>
+```
+
+`fallback` fills `data` while loading so a page can render its real (empty) shell
+immediately — it never lies about `loading`:
+
+```ts
+const { data, loading } = useSubscription('app', 'notes.list', {}, { fallback: [] })
+// data is [] before the first snapshot; loading is still true
+```
+
+**Errors.** `error` carries a **cold-start** stream failure (nothing ever
+arrived) — check it to avoid an infinite skeleton. A failure AFTER data arrived
+deliberately does NOT replace good data with an error banner (a transient
+websocket hiccup would blank a working screen); those reach the api's error bus
+instead — subscribe with `useOnRpcError` for connection-level UX.
+
+
 
 ---
 
@@ -374,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.
@@ -432,6 +468,35 @@ export default function NewNote() {
 
 `useMutation` returns `mutate`, `pending`, `error`, `data`, plus the chainable optimistic helpers.
 
+### Handling the result — `onSuccess` / `onError` / `notify`
+
+Pass a result handler to `mutate` instead of wrapping every call in
+`try/catch/finally` + toasts. `pending` already replaces the `finally`:
+
+```ts
+const create = useMutation('app', 'teams.create')
+
+await create.mutate(input, {
+  onSuccess: (team) => setOpen(false),
+  notify: { success: t('teams.created'), error: (e) => messageFor(e) },
+})
+```
+
+**The load-bearing rule:** supplying an error handler (`onError` **or**
+`notify.error`) marks the failure **handled** — `mutate` then resolves with
+`undefined` instead of rejecting, which is what removes the `try/catch`. With no
+error handler it rejects exactly as before, so an unhandled failure stays loud.
+You opt in per call.
+
+`notify` routes to an app-wide sink you register once — the framework is not
+bound to any toast library:
+
+```ts
+import { setMutationNotifier } from '@voltro/client'
+setMutationNotifier({ success: (m) => toast.success(m), error: (m) => toast.error(m) })
+```
+
+
 ## Auto-Optimistic
 
 The default path is declarative:
@@ -492,6 +557,30 @@ target: {
 - `op: 'delete'` filters the item out by its key.
 - `by` overrides the item-key field (default `'id'`).
 
+**Shape the item with `shapeItem` (not `shape`).** For a nested target, build/patch the item with `shapeItem` — it is typed to the **item** of the nested array, not the mutation's output, so `current` needs no cast:
+
+```ts
+target: {
+  table: 'projectRoadmaps', op: 'update', path: 'snapshot.projects',
+  identify: (input) => input.projectId,
+  shapeItem: (input, current) => ({ ...current, startDate: input.startDate }),  // `current` IS the item
+}
+```
+
+(The flat `shape` stays bound to the output row — a single field can't be both, so the nested shaper is its own.)
+
+**Bulk (multi-item) patches.** `identify` may return an **array** of ids to patch or delete **many** items in one mutation — exactly the group-drag / batch-edit where per-item parallel writes used to race:
+
+```ts
+target: {
+  table: 'projectRoadmaps', op: 'update', path: 'snapshot.projects',
+  identify: (input) => input.projectIds,                    // ← ARRAY: patch them all
+  shapeItem: (input, current) => ({ ...current, shiftedBy: input.delta }),  // each keeps its own key
+}
+```
+
+(This works for flat top-level targets too — `identify` returning an array patches/deletes every matching row.)
+
 Add `match` to patch **only** the entries whose current value satisfies a predicate — the guard that stops a patch bleeding across sibling subscriptions sharing a source table:
 
 ```ts
@@ -502,7 +591,7 @@ target: {
 }
 ```
 
-`path`, `by`, and `match` are browser-safe descriptor data (a dot-path string + a pure predicate) — the same discipline as `identify`/`shape`.
+`path`, `by`, `match`, and `shapeItem` are browser-safe descriptor data (a dot-path string + pure functions) — the same discipline as `identify`/`shape`.
 
 ## Typed Errors
 
@@ -524,6 +613,42 @@ export const createNote = defineMutation({
 
 Throw a matching error from the server file; the client can narrow on `_tag`.
 
+### Matching typed errors on the client
+
+Tagged errors **round-trip structurally** over the wire — the caught value carries `_tag` plus every declared field as real properties (and `instanceof` works, same Schema class both ends). You do **not** need to parse the error message string.
+
+Inside Effect, use `Effect.catchTag('NoteQuotaExceeded', …)`. In a React `try/catch` (outside Effect, where `catchTag` isn't available and the decoded value may be a plain object, not a class instance), match with **`errorTag(err)`** — the dependency-free tag reader `@voltro/client` ships:
+
+```ts
+import { errorTag } from '@voltro/client'
+
+try {
+  await createNote(input)
+} catch (err) {
+  if (errorTag(err) === 'NoteQuotaExceeded') {
+    // err.limit is the declared field — read it directly, no regex
+  }
+}
+```
+
+**Trace id for debugging.** An error caught from `useMutation` / `useAction` carries a **non-enumerable `__voltroTraceId`** — the bridge to the server logs for that exact call:
+
+```ts
+const traceId = (err as { __voltroTraceId?: string }).__voltroTraceId
+// → `voltro logs --trace <traceId>` to see the server-side span
+```
+
+**Exhaustive matching with the generated `matchError`.** Codegen emits a per-app `matchError` (plus `AppError` / `AppErrorTag`) into `rpcGroup.generated.ts`, derived by reference from every descriptor's `error:` schema + your plugins' cross-cutting errors — so there's no hand-maintained tag list to drift out of date (a dead/renamed tag is a compile error):
+
+```ts
+import { matchError } from './rpcGroup.generated'
+
+const message = matchError(err, {
+  NoteQuotaExceeded: (e) => `Limit ${e.limit} reached`,   // e is typed
+  ScopeError: (e) => `Missing ${e.required}`,
+}, () => 'Something went wrong')
+```
+
 ## When Not To Use A Mutation
 
 - **External I/O.** Use an action or workflow.
@@ -1087,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,
     }))
   },
 })
@@ -1116,6 +1241,7 @@ The reading API is **explicit + namespace-only** — `useAggregate(def).read(...
 
 ```ts
 handle.read({
+  where:    { teamId: 't1' }, // filter the materialised rows (see below)
   limit:    10,            // pagination
   offset:   20,
   orderBy:  'rank',        // any column in the output schema
@@ -1124,7 +1250,34 @@ handle.read({
 })
 ```
 
-There's deliberately no `filter` / `where` / `join`. If you need a different cut of the data, define another aggregate.
+### Parameterised reads — `where`
+
+Without a filter an aggregate can only ever be "the one global roll-up". Every tenant-, team- or period-scoped roll-up — which is most of the real ones — then has to read the *whole* aggregate and filter client-side: every row crosses the wire so the caller can throw most of them away. `where` moves that cut to the read.
+
+```ts
+// one team's rows, for one year
+const rows = yield* handle.read({ where: { teamId: 'team_7', year: 2026 } })
+
+// an array is an IN set — status is 'open' OR 'blocked'
+const active = yield* handle.read({ where: { status: ['open', 'blocked'] } })
+
+// composes with the other read options
+const top = yield* handle.read({
+  where:   { teamId: 'team_7', status: ['open', 'blocked'] },
+  orderBy: 'rank',
+  limit:   10,
+})
+```
+
+The semantics, exactly:
+
+- **Entries are ANDed** — a row matches only when it satisfies *every* entry.
+- **A scalar value means strict equality** (`===`) against that field on the row.
+- **An array value means IN** — the row's value must be one of the array's entries.
+- An omitted `where`, or an empty `{}`, filters nothing.
+- Filtering happens **before** `orderBy` and `limit` / `offset`, so pagination paginates the filtered set.
+
+`where` is deliberately **data, not a predicate function**. It is applied over the rows the aggregate has already materialised — the refresh still computes the full roll-up, and `where` cuts the result before it crosses the wire. Keeping it a serializable record of field → value (rather than a callback) is what leaves the door open to pushing the same filter down to the store later. A cut you can't express as equality / IN belongs in another aggregate rather than in the read.
 
 ### Metadata
 
@@ -1291,11 +1444,11 @@ Mental model: `'replace'` is "snapshot at time T"; `'merge'` is "incremental del
 The defining property of an aggregate is **the query is fixed in advance**. Treating it as a query-buildable virtual table (`database.topPlayers.where(...)`) opens four footguns:
 
 1. **Hidden staleness.** `database.topPlayers.where(...)` looks like a live query. Readers can't tell it's stale data.
-2. **Computation drift.** Adding `WHERE region='EU'` shifts the filter from refresh-time to read-time — the materialisation point IS the query; don't re-query it.
+2. **Computation drift.** A full query builder shifts arbitrary computation from refresh-time to read-time — the materialisation point IS the query; don't re-query it. `read({ where })` is the bounded exception: an equality / IN cut of rows that are *already* materialised, not a new query.
 3. **Misleading expectations.** Users would reflexively try `database.topPlayers.insert(...)`. Framework would either silently do nothing or error with a cryptic message.
 4. **Cross-timeline joins.** Joining an aggregate with a live table mixes two timelines (refresh-time + now). Mostly a footgun.
 
-The explicit namespace (`useAggregate(def).read(...)`) makes the materialisation explicit. Friction in the wrong direction (filtering, joining) is a feature — it pushes you to either define another aggregate or do the work in app code with clear boundaries.
+The explicit namespace (`useAggregate(def).read(...)`) makes the materialisation explicit. `where` covers the one cut that genuinely belongs at read time — scoping a roll-up to a tenant, a team, a period. Everything past it (joins, aggregating over the aggregate, arbitrary predicates) keeps its friction on purpose: it pushes you to either define another aggregate or do the work in app code with clear boundaries.
 
 ## Decision: aggregate vs subscriber vs cron
 
@@ -1621,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

@@ -242,9 +242,11 @@ Cross-dialect:
 | Dialect             | Support                                                        |
 |---------------------|----------------------------------------------------------------|
 | postgres / sqlite / mssql | native partial `CREATE UNIQUE INDEX … WHERE`             |
-| mysql / mariadb     | FAILS LOUDLY at migrate — no partial-index support; a full unique index would forbid re-creating a soft-deleted key. Use a generated STORED column + `.unique([...])` there. |
+| mysql / mariadb     | lowered automatically to a generated STORED column per key column (NULL when soft-deleted) + a UNIQUE over them — NULL-distinct gives the same resurrection-safe semantics. Nothing to hand-write. |
 
-The predicate is emitted verbatim (ANSI double-quoted identifiers, valid on the three supported dialects).
+**mysql / mariadb — how the emulation works.** Those engines have no partial index, so `.uniqueActive(['projectId', 'year'])` lowers to one `CASE WHEN <predicate> THEN CAST(<col> AS CHAR(255)) ELSE NULL END` STORED column per key column plus a `UNIQUE` over them. A soft-deleted row's generated columns are all NULL, and mysql/mariadb treat NULLs as DISTINCT in a unique index, so it never collides — re-creating the key just works, exactly like the partial index elsewhere. This round-trips through the declarative differ (the generated columns are part of the declared snapshot on those dialects, so `voltro dev` never re-plans them). You write the same `.uniqueActive([...])` on every dialect.
+
+The predicate is emitted verbatim (ANSI double-quoted identifiers; on mysql/mariadb they are re-quoted with backticks inside the generated column).
 
 ## When NOT to index
 
@@ -801,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) —

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

@@ -100,6 +100,8 @@ ctx.store.select('notes').where(not(eq('archived', true)))
 
 `and(...)` is rarely needed because chained `.where()` calls are already AND'd; useful inside `or(...)` to nest.
 
+`eq(col, val)` (and the other predicate helpers) is **callable without a row-type generic** — it defaults to a loose row shape — so in generic handler code you write `eq('teamId', id)` directly. There's no need for a `const ef = (c, v) => eq<Row, string>(c, v)` wrapper.
+
 ### JSON path filters
 
 For `json<T>()` columns:
@@ -128,19 +130,29 @@ Each call adds ONE column + direction; chain for multi-column ordering:
 .limit(20).offset(40)
 ```
 
-For cursor pagination that avoids OFFSET's O(n) scan, use the standalone `paginateById` helper over `ctx.store.query(...)`:
+For cursor pagination that avoids OFFSET's O(n) scan, use `paginateBy` over `ctx.store.query(...)`:
 
 ```ts
-import { paginateById } from '@voltro/database'
+import { paginateBy } from '@voltro/database'
 
 const rows = await ctx.store.query(
-  paginateById(database.notes.orderBy('createdAt', 'desc').descriptor, req.cursor, 20),
+  paginateBy(database.notes.descriptor, 'createdAt', req.cursor, 20, 'desc'),
 )
-const nextCursor = rows.at(-1)?.id ?? null
+const nextCursor = rows.at(-1)?.createdAt ?? null
 return { rows, nextCursor }
 ```
 
-`paginateById(descriptor, cursor, limit)` adds a `WHERE id > cursor ORDER BY id LIMIT n` clause and preserves any existing predicate. Works for any sortable id scheme (TypeID, ULID, Snowflake, Numeric).
+`paginateBy(descriptor, column, cursor, limit, direction?)` adds the keyset predicate, sets the ORDER BY, and preserves any existing `where`.
+
+The `direction` argument controls **both** the comparison and the sort — a `desc` feed pages with `<`, not `>`. That pairing is the classic keyset bug: an ascending comparison under a descending sort returns the same first page forever.
+
+The cursor column must be unique, or monotonic enough that ties don't straddle a page boundary. For a timestamp with collisions, order by a tie-breaker and paginate on that:
+
+```ts
+paginateBy(database.notes.orderBy('createdAt', 'desc').descriptor, 'id', req.cursor, 20)
+```
+
+`paginateById(descriptor, cursor, limit)` is the `id`-column shorthand — literally `paginateBy(descriptor, 'id', cursor, limit)`. It works for any sortable id scheme (TypeID, ULID, Snowflake, Numeric). Note it sets the order to `id asc`, so passing a descriptor that already carries `.orderBy('createdAt', 'desc')` does **not** page by `createdAt` — use `paginateBy` when the sort column is the thing you want to page on.
 
 ## Aggregates
 

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

@@ -716,8 +716,11 @@ const row = await ctx.store.insert('todos', { title, done: false })
 // Test — deterministic id.
 await ctx.store.insert('todos', { id: 'todo_pinned_for_test', title, done: false })
 
-// Signup self-stamping — pass createdBy: userId in the same insert.
-await ctx.store.insert('users', { id: userId, createdBy: userId, email })
+// Signup self-stamping — the actor IS the row. Generate the id up front
+// so createdBy can point at the row being created, in the same insert.
+import { typeid } from 'typeid-js'
+const userId = typeid('user').toString()
+await ctx.store.insert('users', { id: userId, email, createdBy: userId })
 ```
 
 ## Branded TypeScript types