@voltro/cli 0.33.0 → 0.34.0

package/templates/agent-docs/introduction.md

@@ -23,27 +23,52 @@ This guide gets you from zero to a running stack in under a minute.
 
 ## Scaffold a project
 
-`create-project` runs **inside an existing pnpm workspace** — it walks up from your current directory looking for `pnpm-workspace.yaml` and writes the project into that workspace's `apps/` directory. Run it from the root of your workspace:
+A Voltro monorepo is a pnpm workspace. `create-project` walks up from your current directory looking for `pnpm-workspace.yaml` — and **when there is none, it creates the workspace root right there** before scaffolding. So an empty directory is a perfectly good starting point:
 
 ```bash
+mkdir acme && cd acme
+
 pnpx voltro create-project acme \
   --api api-backend \
   --web frontend-landing \
   --port-range 5190-5199
 ```
 
-This creates `apps/acme/` inside the workspace with an `api/` (Voltro backend) and a `web/` (landing page) app. The project name is kebab-cased (so `Acme` becomes `acme`). The `--port-range` is recorded in `project.json` so every new app added later gets a unique port without you thinking about it.
+You get:
+
+```text
+acme/
+  pnpm-workspace.yaml     # the package globs + the install-script decisions
+  package.json            # dev / build / test / typecheck (plain `pnpm -r` scripts)
+  .gitignore              # incl. .env.local, where `voltro dev` mints your secrets
+  .git/                   # unless you were already inside a repo
+  AGENTS.md + CLAUDE.md   # the agent guide, seeded per project
+  apps/acme/
+    api/                  # Voltro backend
+    web/                  # landing page
+    project.json          # the project's port range + app map
+```
+
+The project name is kebab-cased (so `Acme` becomes `acme`). The `--port-range` is recorded in `project.json` so every new app added later gets a unique port without you thinking about it.
+
+Three things worth knowing about this first run:
+
+- **The install-script question is already answered.** pnpm refuses to finish an install that has an undecided `postinstall` (`ERR_PNPM_IGNORED_BUILDS`), and a Voltro workspace pulls three — all transitive, none of them anything you picked. `pnpm-workspace.yaml` ships the answers with a reason on each line: `esbuild: true` (vite's compiler binary), `@parcel/watcher` and `msgpackr-extract` `false` (optional native accelerators with pure-JS fallbacks, so your first install needs no C++ toolchain). Change your mind with `pnpm approve-builds`.
+- **Already have a workspace?** Nothing is overwritten. An existing `pnpm-workspace.yaml` is left alone, and only root scripts you *don't* already define are filled in. To prepare a directory without scaffolding anything yet, run `voltro init` — it creates the same workspace root and stops there.
+- **It registers the project with the cloud control plane** (self-hosted tracking) unless you pass `--no-register`. Offline, in CI, or just not interested: `--no-register` skips the network call entirely.
 
 ## Boot it
 
-Install and run from the **workspace root** — there is no top-level `acme/` directory to `cd` into; the project lives under `apps/acme/`:
+Install and run from the **workspace root** — there is no top-level `acme/api` to `cd` into; the project lives under `apps/acme/`:
 
 ```bash
 pnpm install
 pnpm dev
 ```
 
-The dev orchestrator boots every app in parallel with HMR. By default:
+The root `dev` script is `pnpm -r --parallel dev`: it runs every workspace package that has a `dev` script, at once. No task runner to install — and apps that own their own dev loop (an Expo mobile app, a serverless bundle) simply don't define `dev`, so they opt out by construction. To run one app on its own, `pnpm --filter @acme/api dev`.
+
+By default:
 
 - `api` listens on `:4000` (RPC over WebSocket on `/ws`)
 - `web` listens on the first port in your range (e.g. `5190`)
@@ -153,10 +178,10 @@ useMutation('billing', 'invoices.pay')
 Every procedure descriptor declares a globally unique `name`. That name is the **RPC tag**:
 
 ```ts
-defineQuery({ name: 'todos.list', /* ... */ })
-defineMutation({ name: 'todos.create', /* ... */ })
-defineAction({ name: 'support.ping', /* ... */ })
-defineStream({ name: 'agent.run', /* ... */ })
+defineQuery({    name: 'todos.list',   guards: [{ scope: 'todos:read' }],   /* ... */ })
+defineMutation({ name: 'todos.create', guards: [{ scope: 'todos:write' }],  /* ... */ })
+defineAction({   name: 'support.ping', guards: [{ scope: 'support:diagnostics' }], /* ... */ })
+defineStream({   name: 'agent.run',    guards: [{ scope: 'agents:run' }],   /* ... */ })
 ```
 
 Hooks use the API name plus RPC tag. There is no hand-written client SDK per endpoint.
@@ -172,6 +197,34 @@ Procedures are split into two files:
 
 This keeps the wire contract importable from the client while server code stays server-only.
 
+## Every Procedure Declares Who May Call It
+
+Dropping a descriptor into the tree **puts it on the wire**. So each one carries an access decision, and a descriptor that carries none is **refused at boot** — by `voltro dev`, by `voltro serve`, and by `voltro doctor` as a preflight. Exactly one of three:
+
+```ts
+export const invoiceList = defineQuery({
+  name: 'invoices.list',
+  guards: [{ scope: 'invoices:read' }],   // the caller must hold a scope
+  /* ... */
+})
+
+export const pricing = defineQuery({
+  name: 'pricing.current',
+  openAccess: 'public pricing page — reads no caller data',  // anyone may, and why
+  /* ... */
+})
+
+export const stampAudit = defineMutation({
+  name: 'auditLog.stamp',
+  internal: true,                          // not on the wire at all
+  /* ... */
+})
+```
+
+`openAccess` takes a **reason, not a boolean**, and that is the whole design: it is what makes *"we decided this is open"* distinguishable from *"nobody looked"*. Without it, the only way to satisfy the gate would be to invent a guard — and the guard people invent is one every caller already holds, which reads as protection and enforces nothing.
+
+The one to expect first: your **first self-written procedure file** will not boot until it has one of these three. Full rules in [Authorization](/docs/authentication/authorization#every-procedure-decides-guards-or-openaccess).
+
 ## The Main Primitives
 
 | Primitive | Use it for | Client hook | Durable? | Reactive? |
@@ -208,8 +261,11 @@ const { data: todos } = useSubscription('app', 'todos.list', {})
 When a mutation commits, the runtime emits change events. Queries whose `source` matches the changed table can update automatically.
 
 ```ts
-defineQuery({ name: 'todos.list', source: 'todos', /* ... */ })
-defineMutation({ name: 'todos.create', target: { table: 'todos', op: 'insert' }, /* ... */ })
+defineQuery({ name: 'todos.list', source: 'todos', guards: [{ scope: 'todos:read' }], /* ... */ })
+defineMutation({
+  name: 'todos.create', target: { table: 'todos', op: 'insert' },
+  guards: [{ scope: 'todos:write' }], /* ... */
+})
 ```
 
 There is no `refetch` as the normal path. The subscription lives for the lifetime of the component.
@@ -287,11 +343,14 @@ You don't need Docker for dev — Voltro ships an in-memory store. You'll want D
 The CLI runs from the registry without a global install:
 
 ```bash
+mkdir my-app && cd my-app
 pnpx voltro create-project my-app
 ```
 
 This is the smallest blast radius — `pnpx` fetches the latest CLI release into the local cache and discards it after.
 
+An empty directory is enough: `create-project` writes the pnpm workspace root (`pnpm-workspace.yaml`, a root `package.json` with `dev`/`build`/`test`/`typecheck`, a `.gitignore`, `git init`) when it can't find one above you. Inside an existing workspace it adds nothing but the project. `voltro init` does the workspace-root half on its own, for when you want the repo prepared before you pick templates.
+
 ### 2. Per-project dependency
 
 Once your project exists, the CLI is already a `dependency` of the `api` app's `package.json`, so:
@@ -300,7 +359,7 @@ Once your project exists, the CLI is already a `dependency` of the `api` app's `
 pnpm --filter @my-app/api exec voltro dev
 ```
 
-The api template's own `dev` script is `voltro dev .`, so `pnpm dev` in the app runs the CLI directly. If your workspace ships a turbo dev pipeline, `pnpm dev` at the repo root delegates to it. You rarely call the filtered form directly.
+The api template's own `dev` script is `voltro dev .`, so `pnpm dev` in the app runs the CLI directly. At the workspace root, `pnpm dev` is `pnpm -r --parallel dev` — every app at once. You rarely call the filtered form directly.
 
 ### 3. Global install
 
@@ -318,7 +377,7 @@ voltro version
 voltro list-templates
 ```
 
-The second command prints the app templates the CLI can scaffold. You'll see the `api-backend*` templates (`api-backend`, `api-backend-mail`, `api-backend-mariadb`, `api-backend-storage`) and the `frontend-*` templates (`frontend-blank`, `frontend-docs`, `frontend-landing`) — that's everything in place.
+The second command prints the app templates the CLI can scaffold — **dozens** of them, across four kinds: `api-*` backends, `frontend-*` web apps, an `edge-functions` serverless bundle, and `mobile-app` (Expo). The output is generated from the templates the installed CLI actually ships, so it is the authority on what your version can scaffold; do not go by a list in a doc. For what each one demonstrates and when to pick it, see the [app-template reference](/docs/reference/templates).
 
 ## Editor setup
 
@@ -363,13 +422,13 @@ Voltro replaces router and registry config with **filesystem conventions**. Drop
 
 | Suffix | What it is | Wired into |
 |---|---|---|
-| `*.query.ts` | Browser-safe reactive query descriptor: `defineQuery({ name, source, input, output })`. | Typed RPC group + client metadata. |
+| `*.query.ts` | Browser-safe reactive query descriptor: `defineQuery({ name, source, input, output, guards })`. | Typed RPC group + client metadata. |
 | `*.query.server.ts` | Server executor for the matching query descriptor. | Reactive subscription runtime. |
-| `*.mutation.ts` | Browser-safe mutation descriptor: `defineMutation({ name, target, input, output, error })`. | Typed RPC group + auto-optimistic metadata. |
+| `*.mutation.ts` | Browser-safe mutation descriptor: `defineMutation({ name, target, input, output, error, guards })`. | Typed RPC group + auto-optimistic metadata. |
 | `*.mutation.server.ts` | Server executor for the matching mutation descriptor. | Transactional mutation runner. |
-| `*.action.ts` | Browser-safe action descriptor: `defineAction({ name, input, output, error })`. | Typed RPC group. |
+| `*.action.ts` | Browser-safe action descriptor: `defineAction({ name, input, output, error, guards })`. | Typed RPC group. |
 | `*.action.server.ts` | Server executor for the matching action descriptor. | Non-transactional action runner. |
-| `*.stream.ts` | Browser-safe one-shot stream descriptor: `defineStream({ name, input, element, error })`. | Typed streaming RPC group. |
+| `*.stream.ts` | Browser-safe one-shot stream descriptor: `defineStream({ name, input, element, error, guards })`. | Typed streaming RPC group. |
 | `*.stream.server.ts` | Server executor returning an Effect `Stream`. | Plain server-to-client element streams. |
 | `*.workflow.tsx` | A durable Effect workflow. Survives restarts. | `@effect/workflow` runtime. |
 | `*.agent.tsx` | Browser-safe AI agent **descriptor**: `defineAgent({ name, input })`. Codegen-typed routes. | Agent runtime + client types. |
@@ -381,6 +440,18 @@ Voltro replaces router and registry config with **filesystem conventions**. Drop
 
 Procedure descriptors are intentionally separate from server executors. Descriptor files are safe for browser imports and codegen; `.server.ts` files can import the database, file system, SDK clients, secrets, and other server-only modules. Each descriptor has exactly one matching `.server.ts` file with the same primitive suffix. Workflows follow the same split: a browser-safe `*.workflow.tsx` descriptor (importing `workflow` from `@voltro/workflow/define`) paired with a `*.workflow.server.tsx` executor.
 
+### The access decision is not optional
+
+`guards` appears in all four procedure signatures above because dropping a file into the tree **puts it on the wire**, and a wire-exposed procedure has to say who may call it. Exactly one of three:
+
+```ts
+guards: [{ scope: 'notes:read' }]                    // the caller must hold a scope
+openAccess: 'public pricing page — reads no caller data'  // anyone may call it, and why
+internal: true                                        // not on the wire at all
+```
+
+A descriptor that declares none of them is **refused at boot** — by `voltro dev`, by `voltro serve`, and by `voltro doctor` as a preflight. This is the one field a newly-created procedure file is most likely to be missing, and the failure is a boot refusal naming the file rather than a subtle runtime surprise. Full rules, including `openAccess`'s required reason and the per-app `security.defaultDeny` switch: [Authorization](/docs/authentication/authorization#every-procedure-decides-guards-or-openaccess).
+
 The browser-safe rule is **transitive**, and that is where it usually breaks. The codegen pulls every descriptor (and every workflow descriptor) value-level into `rpcGroup.generated.ts`, which the web client loads — so a descriptor plus *everything it imports* must stay free of server-only code (`node:*`, the `database` handle, `@voltro/ai`, cluster, plugins, `@voltro/protocol/session`). The classic mistake is not a literal `import 'node:crypto'` but a descriptor importing a shared typed-error or helper from a `lib/` file that *also* imports the database — which drags the whole schema graph into the browser bundle. Keep typed errors, Schemas, and pure helpers in files with zero server imports; put DB-backed guards in `.server.ts`. A leak shows up as the web app fetching hundreds of modules / tens of MB on first load, or crashing with `Module "node:crypto" has been externalized for browser compatibility`.
 
 ### Declaring a shared file browser-safe: `*.client.ts`

package/templates/agent-docs/local-first-mobile.md

@@ -23,11 +23,13 @@ imports it directly. The React wrappers live behind `@voltro/local-first/react`
 > [`crdtText()` database column](#the-crdttext-database-column) (with its
 > authoritative server-side merge on the write path), the
 > [`SyncClient`](#the-syncclient-bi-directional-wire) that drives the queue over a
-> transport, [presence/awareness](#presence--awareness) via `usePresence`,
-> [durable IndexedDB persistence](#durable-persistence), and the
+> transport, [`useCrdtText`](#a-collaborative-text-field-usecrdttext) — the React
+> binding for a collaborative text field — [presence/awareness](#presence--awareness)
+> via `usePresence`, [durable IndexedDB persistence](#durable-persistence), and the
 > [`localFirst` table mixin](#the-localfirst-table-mixin). What remains is a thin
 > [runtime binding](#whats-shipped-vs-a-runtime-seam) to provisioned infra
-> (a broker at scale, a running app's transport) — not un-built framework code.
+> (a broker at scale) plus the two app-specific tags `useCrdtText` is pointed at —
+> not un-built framework code.
 
 ## CRDT text: `crdtText` + `mergeCrdtStates`
 
@@ -139,6 +141,69 @@ Everything below the two transport functions — the drain loop, retry/attempt
 counting, optimistic local merge, durable persistence — is in the client and
 tested against an in-memory dispatcher that mirrors the server's merge.
 
+## A collaborative text field: `useCrdtText`
+
+`useCrdtText` is the React binding over that wire — one `crdtText()` cell, bound
+to the mutation that writes it and the reactive query that streams it:
+
+```tsx
+import { useMutation, useSubscription } from '@voltro/client'
+import { useCrdtText } from '@voltro/local-first/react'
+
+function BodyEditor({ id }: { id: string }) {
+  const row = useSubscription<{ body: Uint8Array | null }>('app', 'documents.byId', { id })
+  const save = useMutation<{ id: string; body: Uint8Array }>('app', 'documents.setBody')
+
+  const body = useCrdtText({
+    cell: { table: 'documents', id, column: 'body' },
+    remote: row.data?.body ?? null,             // what the server currently holds
+    push: (w) => save.mutate({ id: w.id, body: w.update }),  // deliver a local edit
+  })
+
+  return (
+    <>
+      <textarea value={body.text} onChange={(e) => body.setText(e.target.value)} />
+      {body.synced ? null : <em>saving… ({body.outstanding})</em>}
+    </>
+  )
+}
+```
+
+The hook owns one `SyncClient` per `(table, id, column)` cell — created and
+closed with the component — re-renders on a local edit, an ack or incoming
+merged state, and folds the streamed row back in. It returns `text`,
+`insert(index, text)`, `delete(index, length)`, `setText(next)`, the encoded
+`state`, `outstanding` / `synced`, and `setOnline`.
+
+<Callout type="warn">
+**`setText` is a span diff, and that is the whole point.** A `<textarea>` hands
+you the entire new string, so the obvious binding is "clear the document,
+insert the new text" — a delete-all/insert-all, which is exactly the
+last-write-wins behaviour a CRDT is chosen to prevent: two people typing in
+different paragraphs each erase the other's, and the text looks right on
+whichever peer typed last. `useCrdtText` diffs the common prefix and suffix and
+emits ONE delete plus ONE insert, so an edit outside the changed span survives.
+The diff is exported as `crdtTextEdit(before, after)` if you drive the document
+yourself.
+</Callout>
+
+Two things stay yours to name, because nothing can derive them: **which
+mutation** writes the column and **which query** streams the row. Voltro
+generates no per-table CRUD surface, so the hook takes those two as `push` and
+`remote` — the same shape as `usePresence`'s injected channel. Everything under
+them (client lifecycle, optimistic merge, offline queue, bounded retry, durable
+persistence, the edit encoding) is framework code.
+
+The descriptors on the other end declare the column as bytes-over-base64 —
+`Uint8Array` in the handler, a base64 string on the wire:
+
+```ts
+import { Schema } from 'effect'
+
+// documents.byId output (and documents.setBody input)
+body: Schema.NullOr(Schema.Uint8ArrayFromBase64)
+```
+
 ## Presence & awareness
 
 `usePresence(roomId, self, { channel })` publishes this peer's ephemeral state
@@ -168,6 +233,16 @@ Redis/NATS at scale (both already shipped). `createInMemoryPresenceChannel()` is
 the local/test transport. Join/leave, announce-back discovery, cursor
 propagation, and TTL expiry live in the pure `createPresenceRoom` the hook wraps.
 
+> **Two different hooks share the name `usePresence`, and they are not
+> interchangeable.** THIS one (`@voltro/local-first/react`) is peer-to-peer
+> awareness over a pub/sub channel — `usePresence(roomId, self, { channel })` →
+> `{ presence, others, setPresence }` — for high-frequency cursor/selection
+> state that must never touch the database.
+> [`@voltro/plugin-presence`](/docs/plugins/presence)'s is a server-backed
+> roster — `usePresence(channel, options)` → the list of members whose heartbeat
+> is fresh, plus a `useTyping` indicator, through the app's own rpc. Reach for
+> the plugin for "who is here"; reach for this one for "where is their cursor".
+
 ## The offline sync queue
 
 `useSyncQueue()` is a reactive view over a **pure, tested reducer**: writes made
@@ -252,7 +327,7 @@ code already speaks:
 
 | Runtime seam | What it binds | Why it's a binding, not code |
 | --- | --- | --- |
-| **Sync transport → a running app** | The `SyncClient`'s `push`/`onRemoteState` to one app's `useMutation` + `useSubscription`. | The two functions are app-specific glue; the drain loop, merge, retry, and persistence all ship and are tested. |
+| **Two app-specific tags** | Which mutation writes the `crdtText()` column, and which reactive query streams the row, in [`useCrdtText`](#a-collaborative-text-field-usecrdttext). | Voltro generates no per-table CRUD surface, so there is nothing to derive them from. The client lifecycle, optimistic merge, offline queue, retry, persistence and edit encoding all ship. |
 | **Presence channel → a broker at scale** | The `PresenceChannel` to a provisioned Redis/NATS broker. | It's a network hop over an already-shipped broker; the awareness logic ships and is tested over the in-memory channel. |
 | **wa-sqlite / Turso adapter** *(optional)* | A SQL durable adapter for cross-tab queries, behind `PersistenceAdapter`. | IndexedDB is the durable default today; a SQL backing is a sibling factory, nothing above it changes. |
 

package/templates/agent-docs/multi-tenancy.md

@@ -11,7 +11,7 @@
 
 _Multi-tenancy as a runtime primitive — the tenant() mixin, ctx.subject.tenantId, automatic read scoping, explicit write gates._
 
-Multi-tenancy is one of those features every B2B SaaS re-derives badly. Voltro treats it as a runtime primitive: drop the `tenant()` mixin on a table, and the framework guarantees cross-tenant data leakage is structurally impossible for **reads**. Writes get a typed `TenantMismatch` error if you forget the explicit check.
+Multi-tenancy is one of those features every B2B SaaS re-derives badly. Voltro treats it as a runtime primitive: drop the `tenant()` mixin on a table, and the framework makes cross-tenant access structurally impossible for **reads and writes alike** — including a write keyed by a row id that came straight from request input.
 
 ## The model
 
@@ -19,18 +19,27 @@ Multi-tenancy is one of those features every B2B SaaS re-derives badly. Voltro t
        Subject (tenantId: 'acme')
               │
               ▼
-   ┌─────────────────────────┐
-   │  Queries (read)          │  ← runtime AND-merges
-   │   ctx.store.select(...) │     WHERE tenantId = subject.tenantId
-   └─────────────────────────┘
-   ┌─────────────────────────┐
-   │  Mutations (write)      │  ← you call
-   │   ctx.store.insert(...) │     assertOwnTenant(input.tenantId, subject)
-   └─────────────────────────┘
+   ┌──────────────────────────────┐
+   │  Reads                        │  ← AND-merged
+   │   select / query / subscribe  │     WHERE tenantId = subject.tenantId
+   └──────────────────────────────┘
+   ┌──────────────────────────────┐
+   │  Inserts                      │  ← auto-stamped from the subject,
+   │   store.insert(...)           │     refused when there is no tenant
+   └──────────────────────────────┘
+   ┌──────────────────────────────┐
+   │  Set-based writes             │  ← AND-merged onto your WHERE
+   │   updateMany / deleteMany     │     (same predicate as reads)
+   │   update(t).where(...)        │
+   └──────────────────────────────┘
+   ┌──────────────────────────────┐
+   │  Keyed-by-id writes           │  ← the row is RESOLVED inside your
+   │   store.update(t, id, patch)  │     tenant first; TenantRowNotFound
+   │   store.delete(t, id)         │     when it isn't there
+   └──────────────────────────────┘
 ```
 
-Reads are auto-scoped because the subject + table mixin contain enough information.
-Writes are NOT auto-scoped because the input gets to *propose* a tenant — your code decides whether to honour it (typical: never) or assert against the subject (typical: always).
+Every path is enforced by the framework, not by remembering a helper. The keyed row was the last one that wasn't: `update(table, id, patch)` addressed the row by primary key alone, so a mutation that took an id from request input could write into another tenant with no error and nothing in the code to review.
 
 ## What's in this section
 
@@ -54,7 +63,11 @@ export const notes = table('notes', {
 Query (auto-scoped):
 
 ```tsx
-export const listNotes = defineQuery({ name: 'notes.list', input: Schema.Struct({}) })
+export const listNotes = defineQuery({
+  name: 'notes.list',
+  guards: [{ scope: 'notes:read' }],   // WHO may open it; tenant() decides WHICH rows
+  input: Schema.Struct({}),
+})
 export default async (_input, ctx) => ctx.store.select('notes').all()
 // SQL: SELECT * FROM notes WHERE tenantId = $1   (with subject.tenantId)
 ```
@@ -66,6 +79,7 @@ import { assertOwnTenant, TenantMismatch } from '@voltro/plugin-multitenancy'
 
 export const createNote = defineMutation({
   name:  'notes.create',
+  guards: [{ scope: 'notes:write' }],
   input: Schema.Struct({ tenantId: Schema.String, title: Schema.String }),
   error: TenantMismatch,
 })
@@ -77,13 +91,40 @@ export default async (input, ctx) => {
 
 If a client posts `{ tenantId: 'their-tenant', title: 'hack' }` while their cookie's subject says `tenantId: 'acme'`, the mutation throws `TenantMismatch`. The audit log records it; the client sees a typed error variant.
 
-## Why the asymmetry
+**`guards:` and `tenant()` answer different questions, and both descriptors above need the first one.** `tenant()` decides **which rows** a call may touch; `guards:` decides **who may make the call at all** — and a wire-exposed procedure that declares neither `guards:`, `openAccess: '<reason>'` nor `internal: true` is refused at boot. Tenant scoping is not a substitute: it confines an *anonymous* caller to whatever tenant the request resolved to, which shapes the result rather than authorizing anybody. Get both, and a revoked membership also stops an open subscription mid-session, because guards are re-checked on every delivery. Full rules: [Authorization](/docs/authentication/authorization#every-procedure-decides-guards-or-openaccess).
+
+## What a keyed write does now
+
+A keyed write resolves its target row inside `subject.tenantId` before it writes. When there is no such row, it fails with `TenantRowNotFound` from `@voltro/runtime` — it does **not** return `null` / `false`:
+
+```ts
+// notes.rename.mutation.server.ts — `input.id` comes from the client
+export default async (input, ctx) => {
+  // Another tenant's note id → TenantRowNotFound. Nothing to remember.
+  return ctx.store.update('notes', input.id, { title: input.title })
+}
+```
+
+```ts
+import { TenantRowNotFound } from '@voltro/runtime'
+// declare it to surface the refusal typed at the client
+export default defineMutation({
+  name: 'notes.rename',
+  guards: [{ scope: 'notes:write' }],
+  input: RenameInput,
+  error: TenantRowNotFound,
+})
+```
+
+**The error is deliberately ambiguous, and that is the design.** It is raised identically whether the row does not exist at all or belongs to another tenant, and it carries nothing that separates the two. Reporting "forbidden" for a foreign row and "not found" for a missing one would turn every keyed write into a cross-tenant *existence oracle*: a caller walks ids and learns which are real in someone else's tenant. Failing loudly and identically gives your handler a signal to act on and gives an attacker one bit they already had — the id they themselves sent is not theirs.
+
+The alternative — silently affecting zero rows — is worse than either. It reads to the handler as "the row is gone" rather than "you may not touch it", so a genuine isolation breach shows up as a confusing empty branch and never as a security signal.
 
-Reads always have a single answer: "what does this subject see?" → AND the tenant. Auto-scopable.
+## What is NOT auto-decided: which tenant an insert claims
 
-Writes have an open question: "which tenant should this go in?" The input gets to claim — sometimes legitimately (impersonation by an admin, switching active tenant). Your code decides whether to honour the claim. The framework can't auto-enforce because legitimate exceptions exist.
+The open question is only ever on the way IN. An insert that omits `tenantId` is stamped from the subject; an insert that *sets* one is not silently substituted, because a legitimate cross-tenant write exists (admin tooling, impersonation). That is where `assertOwnTenant` earns its place — it rejects a *claimed* `input.tenantId` that isn't the subject's, at the top of the executor and with a typed `TenantMismatch`. It is an ergonomic early check, no longer the thing standing between you and a cross-tenant write.
 
-Defaulting to "auto-reject mismatching writes" would still work for 99% of mutations + would make the 1% impossible. We picked "assert explicitly" instead — slightly more code, full flexibility.
+A genuine cross-tenant write runs as the system subject via `runAsSystem` (see [Edge cases](/docs/multi-tenancy/edge-cases)) — a subject with `tenantId: null`, for which every merge above is skipped by construction.
 
 ## Tenant scoping covers more than just the database
 
@@ -129,9 +170,25 @@ Namespace isolation is **one** mechanism — a per-request namespace `tenant_<sa
 
 Database-per-tenant falls out of the same seam for free — only the namespace id differs; the mapping to a physical container is a per-dialect detail. Isolation is **physical**: it no longer depends on a predicate being present, so a query that forgets the tenant filter — or a table that never carried the `tenant()` mixin at all — still cannot read another tenant's rows.
 
-### Postgres fast-path — `SET LOCAL search_path`
+### Postgres — reads are one statement, writes take a `SET LOCAL search_path` transaction
+
+On postgres a namespaced **read** compiles the namespace straight into the identifier — `"tenant_<id>"."todos"` — and runs as a single statement outside any transaction. That is the same mechanism the other dialects have always used, and it is one round trip.
+
+A namespaced **write** (and `raw()`) still runs inside a transaction whose first statement is `SET LOCAL search_path TO "tenant_<id>"`. Because it's `SET LOCAL` (transaction-scoped), the setting **resets at commit** — mandatory on a pooled connection, where a bare `SET search_path` would persist and leak into the next request that checks out the same connection. A write wants its transaction anyway; `raw()` executes SQL text you wrote, which the framework cannot qualify on your behalf.
 
-On postgres each request runs inside a transaction whose first statement is `SET LOCAL search_path TO "tenant_<id>"`. Because it's `SET LOCAL` (transaction-scoped), the setting **resets at commit** — mandatory on a pooled connection, where a bare `SET search_path` would persist and leak into the next request that checks out the same connection. The other dialects qualify identifiers directly (`tenant_<id>.todos`).
+Reads used to take the transaction too, which made every tenant read `BEGIN` + `SET LOCAL` + `SELECT` + `COMMIT` — four round trips holding one pooled connection for all four. Measured against a local postgres, that cost **2.2×** a shared-schema read, and the same factor applied to how long the connection was held, so effective pool capacity under tenant isolation was materially lower than the pool size suggested. Qualifying the identifier also removes the leak surface rather than managing it: nothing is set on the connection, so there is nothing to reset.
+
+One consequence worth knowing: an **eager** (`with:`) read under namespace isolation uses the portable multi-query walker rather than the single-roundtrip JSON aggregate, because the JSON-aggregate compiler does not qualify relation tables. That has always been true on mysql / mssql / sqlite; postgres now matches them. It shows up as `voltro_db_eager_fallback_total{reason="not-compilable"}` — see [Database metrics](/docs/observability/overview).
+
+### Same transaction guarantees as the shared schema
+
+Writes and explicit `transactional()` blocks run inside a transaction, and it is worth stating explicitly what that transaction gives you — it is **exactly** what a shared-schema transaction gives you, with no exceptions:
+
+- a typed error thrown inside it arrives typed (`_tag`, payload, prototype intact), so a mutation's declared `error:` union matches;
+- a transient conflict (serialization failure / deadlock, including one raised at COMMIT) is retried with backoff;
+- the caller's write attribution (`traceId` / `subjectId` / `procedure`) is carried onto every ChangeEvent the transaction produces.
+
+There is one transaction bracket behind both topologies, so there is no "namespace mode is a bit different" caveat to remember. See [Transactions](/docs/database/transactions).
 
 ### Fail closed on a missing tenant
 
@@ -174,6 +231,7 @@ export const notes = table('notes', {
 2. **An auto-index** on `tenantId` (`indexes: [{ fields: ['tenantId'] }]`). The name is auto-generated as `<tableName>_tenantId_idx`.
 3. **Read scoping** — the runtime AND-merges `WHERE tenantId = ctx.subject.tenantId` into every subscription against this table.
 4. **Insert auto-fill** — when an insert's row payload omits `tenantId`, the runtime stamps it from the request subject.
+5. **Write scoping** — `updateMany` / `deleteMany` and the fluent `update(t).where(...)` / `delete(t).where(...)` builders get the same predicate AND-merged onto their `WHERE`, and a **keyed-by-id** write (`update(t, id, patch)`, `delete(t, id)`, `hardDelete`, `patchJson`) resolves its target row inside the caller's tenant before writing — see [What it does NOT do](#what-it-does-not-do).
 
 The mixin's stable id is `voltro/tenant`. The execution lives in the runtime's `wrapStoreWithMixinBehaviour` (write side) and the CLI's `applyTenantScope` (read side) — both key off that id. The mixin source is `voltro/packages/plugin-multitenancy/src/mixin.ts`.
 
@@ -214,9 +272,26 @@ If you DON'T pass `tenantId`, the runtime auto-fills it from `ctx.subject.tenant
 
 When you DO pass an explicit `tenantId` (an admin writing into another tenant), the framework does NOT silently substitute the subject's value — silent substitution is a footgun. Guard the write with `assertOwnTenant` (see below); a genuine cross-tenant write runs as the `system` subject via `runAsSystem` (see [Edge cases](/docs/multi-tenancy/edge-cases)).
 
+## Keyed writes resolve inside your tenant
+
+`ctx.store.update(table, id, patch)`, `delete(table, id)`, `hardDelete(table, id)` and `patchJson(table, id, ...)` address a row by primary key. On a `tenant()` table the runtime resolves that key **inside `subject.tenantId`** before writing, so an id that came straight from request input cannot reach another tenant's row:
+
+```ts
+export default async (input, ctx) => {
+  // input.id is client-supplied. Another tenant's id → TenantRowNotFound.
+  return ctx.store.update('notes', input.id, { title: input.title })
+}
+```
+
+When the row is not in your tenant the call **fails** with `TenantRowNotFound` (`@voltro/runtime`) rather than returning `null` / `false`. Declare it in the descriptor's `error:` to surface it typed at the client.
+
+The error is raised **identically** whether the row is missing or belongs to another tenant, and carries nothing that separates them — reporting the two differently would let a caller probe for row ids in other tenants. Do not try to recover the distinction; there is nothing on the wire to recover it from, on purpose.
+
+Not affected: subjects with no tenant at all — a schedule firing, a resumed workflow, a `*.subscribe.ts` handler — still span tenants by design, and so does a write through the raw store.
+
 ## What it does NOT do
 
-- **Auto-guard writes.** Read scoping is automatic; mutations receive user-supplied input including `tenantId`. A client authenticated as tenant A can post `tenantId: 'B'` and the row lands in B without a guard. Call `assertOwnTenant` at the top of the executor:
+- **Decide which tenant an insert claims.** An insert that omits `tenantId` is stamped from the subject, but one that *sets* it is not silently substituted — a legitimate cross-tenant write exists. `assertOwnTenant` is the early, typed check for a handler that means to USE a claimed `input.tenantId`:
 
   ```ts
   import { assertOwnTenant, TenantMismatch } from '@voltro/plugin-multitenancy'
@@ -227,7 +302,7 @@ When you DO pass an explicit `tenantId` (an admin writing into another tenant),
   }
   ```
 
-  Declare `error: TenantMismatch` on the mutation descriptor so the rpc layer surfaces the rejection typed.
+  Declare `error: TenantMismatch` on the mutation descriptor so the rpc layer surfaces the rejection typed. It checks a *claimed* `tenantId` — a mutation whose input carries none never reaches it, which is why it is no longer what stands between you and a cross-tenant write.
 
 - **Apply to raw SQL.** A hand-written `@effect/sql` query bypasses the mixin. Write the filter yourself.
 

package/templates/agent-docs/observability.md

@@ -71,7 +71,7 @@ Even with no exporter, `voltro dev` installs a **buffer-only** tracer — that's
 
 ## Metrics export
 
-Separate from tracing, the framework records **metrics** into Effect's global `MetricRegistry` — one source of truth (`voltro_rpc_*`, `voltro_http_*`, `voltro_plugin_hook_*`, `voltro_subscription_*` + `voltro_subscriptions_active`, plus `effect_fiber_*` and any custom metric). Three ways to get them out:
+Separate from tracing, the framework records **metrics** into Effect's global `MetricRegistry` — one source of truth (`voltro_rpc_*`, `voltro_http_*`, `voltro_plugin_hook_*`, `voltro_subscription_*` + `voltro_subscriptions_active`, `voltro_db_*`, plus `effect_fiber_*` and any custom metric). Three ways to get them out:
 
 ```bash
 # OTLP metrics — the SAME OTEL endpoint that enables trace export also enables
@@ -94,6 +94,55 @@ Two pull/push consumers read the SAME registry, so they can't disagree:
 - **[`@voltro/plugin-datadog`](/docs/plugins/datadog)** — agentless push to Datadog's `/api/v2/series` (for setups without an Agent / OTLP collector). With an Agent, prefer pointing `OTEL_EXPORTER_OTLP_ENDPOINT` at it instead.
 - The dashboard **Metrics** panel reads the same snapshot via `GET /_voltro/inspect/metrics`.
 
+## Database metrics (`voltro_db_*`)
+
+Every dialect store emits the same five series, so a dashboard built against one
+database keeps working after a migration to another. The labels are `dialect`
+(`postgres` · `mysql` · `mariadb` · `mssql` · `sqlite` · `turso`) and `op`
+(`select` · `insert` · `update` · `delete` · `upsert` · `raw` · `transaction`
+· `ddl`).
+
+| Series | Type | What it answers |
+| --- | --- | --- |
+| `voltro_db_queries_total` | counter | Query rate, split by operation kind. |
+| `voltro_db_query_duration_seconds` | histogram | p50/p95/p99 per operation — `histogram_quantile` over the buckets. |
+| `voltro_db_errors_total` | counter | Statement failure rate. |
+| `voltro_db_operations_in_flight` | gauge | Concurrency the framework is holding right now. |
+| `voltro_db_eager_fallback_total` | counter | Eager loads that dropped off the single-roundtrip fast path. |
+
+**No table name is ever a label.** Table names grow with your schema, and a
+label that grows with the schema is how a scrape target falls over. The table
+appears in the log line instead.
+
+**`voltro_db_operations_in_flight` is not the driver's pool queue.** It counts
+operations the framework currently has in flight, which is an upper bound on the
+connections it holds — the same number on every dialect. Your driver's own
+`waiting` count is not exposed. In practice you alert on this gauge sitting near
+your pool size *together with* the duration histogram's tail growing: a starved
+pool shows up as acquire time inside the query timing.
+
+### `voltro_db_eager_fallback_total` — the one to alert on
+
+An `eager:` query normally compiles to **one** round trip (a JSON aggregate).
+When it can't, the framework silently uses the portable multi-query walker
+instead — correct, and one round trip per relation level, on every call. That is
+a permanent per-query cliff with no error attached to it, which is why it is
+counted. The `reason` label separates the two very different cases:
+
+- `not-compilable` — the query shape can never take the fast path (an
+  unregistered relation, an ambiguous inferred foreign key, or an eager read
+  under physical tenant isolation). Steady state. Worth knowing about, not worth
+  paging on.
+- `execute-failed` — the fast path compiled, **ran, and threw**, so the query
+  paid for both paths. This is the one to alert on. It usually means a database
+  or driver upgrade changed something under the JSON-aggregate query.
+
+Both also log: a `warn` the first time a given table and reason are seen, then
+again at most every 5 minutes while it persists (`VOLTRO_DB_EAGER_FALLBACK_WARN_INTERVAL_MS`,
+`0` = once only). The counter is never rate-limited — the log line answers "is
+this happening now", the counter answers "has this been happening since the
+deploy three weeks ago".
+
 ## Routing traces to a vendor
 
 The env-driven OTLP path above ships traces to any OTLP/HTTP collector. For **deep, opt-in vendor integration** — install one plugin, get traces + errors + logs all correlated by the same `traceId`, zero `OTEL_*` env — a plugin can contribute to the framework's tracer directly via `contributeObservability`:
@@ -122,7 +171,11 @@ Inside a mutation / action / workflow executor, just use Effect:
 ```typescript
 import { Effect } from 'effect'
 
-export const myAction = defineAction({ ... })
+export const myAction = defineAction({
+  name: 'reports.rebuild',
+  guards: [{ scope: 'reports:write' }],
+  /* input, output */
+})
 
 export default (input, ctx) =>
   Effect.gen(function* () {
@@ -172,7 +225,9 @@ client.mutation.placeOrder        traceId=4bf92f35…
 The in-memory ring always keeps EVERY span for live debugging. SEPARATELY, on postgres, the framework can durably mirror a SUBSET of spans into `_voltro_traces` so the in-app Traces dashboard survives restarts. This is a **dev convenience** — at real volume durable tracing belongs in an **OTLP backend (Tempo / Honeycomb / Datadog), not your OLTP postgres** (set `OTEL_EXPORTER_OTLP_ENDPOINT`). A row-per-span firehose into postgres is what turned this table into ~85% of a production DB. So persistence is **environment-aware + fully configurable**:
 
 - **Default OFF in production, `interesting` in dev.** `voltro dev` (not `NODE_ENV=production`) persists only "interesting" spans. `voltro serve` / `voltro start` default `NODE_ENV=production` when it's unset, so they persist NOTHING and **`_voltro_traces` is not even created** — use OTLP in prod. An explicit `NODE_ENV` is never overridden.
-- **`VOLTRO_TRACING_PERSIST`** = `off` | `errors` | `interesting` | `all` (overrides the env default everywhere). `interesting` = error + slow + per-trace root spans, MINUS the high-volume subscription delivery (snapshot/delta) spans. `errors` = error spans only. `all` = every non-delivery span. `off` = no persistence and no table.
+- **`VOLTRO_TRACING_PERSIST`** = `off` | `errors` | `interesting` | `all` (overrides the env default everywhere). `interesting` = error + slow + per-trace root spans, MINUS the high-volume subscription delivery (snapshot/delta) spans, MINUS the framework's own background-task reads. `errors` = error spans only. `all` = every non-delivery span. `off` = no persistence and no table.
+
+  **Why background tasks are excluded from "slow".** The framework polls four of its own tables on a timer (`_voltro_schedule_claims`, `_voltro_workflow_pending`, `_voltro_workflow_pauses`, `_voltro_ai_inferences`). Those reads are slow exactly when the database is under pressure — which is when persisting them costs the most. A consumer measured the loop closing on itself: `_voltro_traces` at 476 571 rows / 335 MB, writing ~11 INSERTs/s onto the same 15-slot pooler the app read through, 99 % of it framework poller spans. Pool pressure makes the spans slow, slow spans are "interesting", persisting them costs pool. They are still kept when they ERROR, and `all` mode still keeps everything. A request-path framework table like `_voltro_api_keys` is NOT excluded — a slow lookup there is a real user waiting.
 - **`VOLTRO_TRACING_SLOW_MS`** (default `500`) — the "slow" threshold used by `interesting`.
 - **`VOLTRO_TRACING_PERSIST_DELIVERY`** (default off) — also persist the subscription delivery spans (the firehose; rarely wanted).
 - **`VOLTRO_TRACING_SAMPLE`** (`0`–`1`, default `1`) — per-*trace* sampling (a kept trace keeps all its eligible spans; errors are never sampled out). `=0` with no explicit mode means off.