@voltro/cli 0.22.1 → 0.24.0

package/templates/agent-docs/data.md

@@ -816,6 +816,26 @@ try {
 
 The same applies to `run` on [actions](/docs/data/actions).
 
+## Idempotency — a retried mutation runs exactly once
+
+The reactive client resends an in-flight mutation after a network blip. Without a guard, "create order" or "charge card" would run twice. `useMutation` (and `useAction`) mint a fresh **idempotency key** per call and attach it to the rpc frame; when idempotency is enabled the server dedupes a repeat of that key — the handler runs once and the retry replays the first result.
+
+Enable it once (this also covers the REST `Idempotency-Key` header — one switch, both surfaces):
+
+```ts
+// app.config.ts
+export default {
+  idempotency: true, // or { ttlMs: 600_000 } — the dedup window (default 24h)
+}
+```
+
+For a HIGHER-level guarantee — dedupe a double-click or an offline resend of the *same logical action* — pass a STABLE key derived from the action's identity, instead of the per-call one:
+
+```ts
+await placeOrder.mutate(cart, { idempotencyKey: `order:${cart.id}` })
+```
+
+The key is scoped to `(tenant, subject, mutation)`, so one user's key can never replay another's. The replayed result is byte-for-byte the first one — a `Date` in the output comes back a `Date`, not a string — because it round-trips through the mutation's output schema. Off by default: with no `idempotency` config, every call runs.
 
 ## Auto-Optimistic
 
@@ -953,7 +973,11 @@ try {
 
 **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
 ```
+
 `errorTag` lives in `@voltro/protocol` rather than in the client for a reason
 worth knowing before you decide where your own error handling goes: **`_tag` is a
 wire concept, and protocol owns the wire.** So a shared error handler in a package
@@ -961,10 +985,6 @@ that has no business depending on `@voltro/client` — a UI kit, an i18n layer
 can read a tag without taking that dependency. `instanceof` is the thing that
 does NOT survive the wire: what arrives in the browser was decoded from JSON and
 never constructed, so match on the tag, not on the class.
-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):
 
@@ -1009,6 +1029,24 @@ nobody wrote a client call for it, it is on the wire — the same reasoning as
 whatever authority its caller has. This removes the wire surface, not the need to
 check who is asking; `voltro doctor`'s authz scan still covers it.
 
+**It cannot be combined with `publicApi` or `exposeAsTool`.** Those add a REST
+route and an agent tool respectively — opt-ins to a *different* surface — so a
+procedure carrying both would be unreachable from your own client and reachable
+from the internet. That combination throws where it is declared:
+
+```text
+auditLog.createFromAction: `internal: true` cannot be combined with `publicApi`.
+```
+
+Neither silent resolution would be right: dropping the REST route breaks a live
+endpoint invisibly, and keeping it defeats the flag. Drop `internal: true` if the
+wider surface is intended, or remove the annotation if it is not.
+
+The flag also removes the procedure from `voltro dev`'s inspect invoker, so the
+devtools "invoke" panel will not list it. That is deliberate — an internal
+procedure is the one most likely to carry no guard, since "only server code calls
+this" is the reason people write them.
+
 ## When Not To Use A Mutation
 
 - **External I/O.** Use an action or workflow.
@@ -2105,171 +2143,6 @@ When no analytics sink is configured the framework provides the no-op sink: the
 
 
 
----
-
-<!-- source: en/data/client-state.md -->
-## Client state (defineStore)
-
-_defineStore — client state that is not server state. Selector-only reads, key scoping instead of providers, and SSR seeding that rides the payload the router already writes._
-
-Server state already has a home: a subscription **is** live server state, and it stays live. What has no home is the rest — which rows are selected, which wizard step you are on, the draft you have not submitted.
-
-Without a primitive for that you reach for zustand or jotai, which is a *parallel runtime* — the one thing the framework asks you not to bring. So it ships one.
-
-```ts
-// wizard.store.ts
-import { defineStore } from '@voltro/client'
-
-export const wizard = defineStore('wizard', () => ({ step: 0, draft: '' }))
-```
-
-```tsx
-const step = wizard.use((s) => s.step)                    // the global instance
-const step = wizard.use((s) => s.step, { key: orderId })  // one instance per order
-
-wizard.set({ step: 2 })
-wizard.set((s) => ({ ...s, step: s.step + 1 }))
-```
-
-## Reads go through a selector — there is no `useStore()`
-
-A component that holds the whole state re-renders on every change to any field, so an API that hands it over would be used and would be wrong. Reading a slice re-renders only when **that slice** changes:
-
-```tsx
-const coupon = wizard.use((s) => s.coupon)   // set({ note }) does not re-render this
-const count  = cart.use((s) => s.items.length) // ['a'] → ['b'] does not re-render this
-```
-
-### Computed values need `equals: shallow`
-
-A selector that *builds* something — an object literal, a mapped or filtered array — returns a fresh reference every call, so the default identity check reports "changed" forever and the component re-renders on **every** store change:
-
-```tsx
-import { shallow } from '@voltro/client'
-
-const visible = cart.use((s) => s.items.filter((i) => i.visible), { equals: shallow })
-const pair    = cart.use((s) => ({ a: s.a, b: s.b }), { equals: shallow })
-```
-
-You do not have to remember: in dev the framework detects the case and warns once, naming the fix. The selector is also memoised — it does not re-run while the state object is unchanged, so an expensive filter costs nothing on unrelated updates.
-
-## Scoping is by key, not by a Provider
-
-A Provider re-renders every consumer when its value identity changes, whether or not that consumer read the field that moved — that *is* what makes context painful at scale. So an instance is addressed by a key you already have:
-
-```tsx
-wizard.use((s) => s.step, { key: orderId })
-```
-
-which is the same model as everywhere else in the framework: `useSubscription('orders.list', { orgId })` is keyed by input, not by position in the tree. One read form, an optional key, no provider to forget.
-
-`wizard.release(orderId)` drops an instance; `wizard.keys()` lists the live ones.
-
-## SSR seeding adds no new channel
-
-Call `seedStore` anywhere on the server during a render and the value reaches the client's first render:
-
-```ts
-export const loader = async ({ params }) => {
-  seedStore(wizard, { step: 2 }, { key: params.orderId })
-  return { /* … */ }
-}
-```
-
-There is no `dehydrate()` to remember and no `hydrate()` to forget — the seed rides the hydration payload the router already writes, and `mount()` applies it before the tree exists. A step you can forget is a step somebody will.
-
-On the client `seedStore` **throws**. A silent no-op would leave the store empty in the browser and full on the server, and that surfaces as a hydration mismatch that reads like a React bug.
-
-**The key is part of the address.** Seed with `{ key: orderId }` and read with `{ key: orderId }`. A component reading the global instance while a loader seeded a key gets the initial value — correct, and easy to trip over once.
-
-## Surviving a reload
-
-`persist` writes the state to `localStorage` (or `sessionStorage`) on every change and reads it back when the store is defined:
-
-```tsx
-export const filters = defineStore(
-  'inbox:filters',
-  () => ({ status: 'open', sort: 'newest', draft: '' }),
-  {
-    persist: {
-      key: 'inbox:filters',
-      storage: 'local',              // 'session' lasts the tab
-      pick: (s) => ({ status: s.status, sort: s.sort }),
-      migrate: (stored) => (isFilters(stored) ? stored : undefined),
-    },
-  },
-)
-```
-
-Three details are the whole reason this is in the framework rather than in your codebase, because a hand-rolled version gets all three wrong:
-
-**The stored value is merged over `initial()`, not substituted for it.** Ship a new field and every returning user has state without it — `undefined` where the type promises a string. Merging means an old payload gains the new defaults.
-
-**`migrate` returning `undefined` discards the value.** A stale draft is an annoyance; a half-migrated one is a bug report nobody can reproduce. Discarding is the right answer far more often than guessing, so it is the easy one to write.
-
-**Every storage touch is guarded and wrapped.** The module is imported by the server render too, and Safari in private mode throws on *reading* `localStorage`, not just on writing. A store that throws at import time takes the page with it.
-
-**A persisted store on a server-rendered page hydrates against the *server* value.** The server has no `localStorage`, so it renders `initial()`; the stored value lands in the commit right after hydration. Without that, every returning user would get a hydration mismatch — a flash and a console error that reads like a React bug. `get()` is not deferred, only the render: an action reading the draft before the first paint reads the draft.
-
-`pick` narrows what gets written — persist the filters, not the open/closed state of every panel. And only the **global** instance persists: a keyed instance is per entity, and writing every key into one bucket grows without bound. Persist a map yourself if you mean to.
-
-## Actions that write more than once
-
-An action rarely touches one field. Applying a coupon writes the coupon *and* the recomputed total; that is one thing the user did, and `batch` says so:
-
-```ts
-checkout.batch('applyCoupon', () => {
-  checkout.set({ coupon })
-  checkout.set({ total: recompute(coupon) })
-})
-```
-
-One notification, one entry in the devtools feed named `applyCoupon`, and **one undo step**. Without it the same action is three of each — Ctrl-Z walks back through a third of a change at a time, and the feed shows three anonymous writes instead of the thing that happened. React batches the re-*renders* on its own; it cannot batch the meaning.
-
-**If the callback throws, every write it made is rolled back.** Nothing was announced yet, so an action that fails halfway cannot leave the half-applied state that is the usual reason people reach for a transaction. A nested `batch` joins its parent rather than opening a second one.
-
-### Async work goes around the batch, not inside it
-
-```ts
-const quote = await fetchQuote(coupon)          // await FIRST
-checkout.batch('applyCoupon', () => {           // then batch the writes
-  checkout.set({ coupon, total: quote.total })
-})
-```
-
-Passing an `async` function to `batch` is an **error**, not a warning. Everything after the first `await` would run outside the batch — writes escaping one at a time, a rollback covering only the synchronous head, and a devtools entry that lies about what the action did. Holding a batch open across time is not available: it would have to block every other write for the duration.
-
-## Undo and redo
-
-Every write passes through one seam, so the previous state is already recorded — undo is a lookup rather than a feature the store had to be designed around:
-
-```tsx
-draft.undo(orderId)      // back one write
-draft.redo(orderId)      // forward again
-draft.canUndo(orderId)   // for disabling the button
-draft.canRedo(orderId)
-```
-
-It is a cursor over an intact history, not a stack that consumes entries. So repeated calls walk back through the steps rather than toggling between the last two, and a **new write after an undo drops the redo tail** — the behaviour every editor has.
-
-An undo never becomes undoable itself, and each keyed instance has its own history.
-
-## Devtools: inspect, and travel
-
-The `voltro dev` overlay has a **Stores** tab. It lists every defined store with its live state — global and per key — and a feed of every write: which store, which key, the label if you passed one, and the fields that actually changed.
-
-`◀ Back` and `Forward ▶` step through that feed, restoring the state as it was before or after each write. The state a component reads moves with it, so you can walk back to the moment before a bug and watch it happen again.
-
-No extension, no connector, no version to match. Every write already passes through one seam, so the panel is just another subscriber — it sees writes made by code that never heard of devtools, on any machine, including a colleague's.
-
-## What a store must never hold
-
-Server data. Copying a subscription's rows into a store gives you a second copy that does not live; the page then renders the stale one, and the bug presents as *"reactivity is broken"*. `voltro doctor` reports a `*.store.ts` that reads a subscription.
-
-Read server state where you render it, and keep the store for what is genuinely client-side.
-
-
-
 ---
 
 <!-- source: en/data/crud.md -->
@@ -2717,6 +2590,171 @@ into the agent's prompt.
 
 
 
+---
+
+<!-- source: en/data/client-state.md -->
+## Client state (defineStore)
+
+_defineStore — client state that is not server state. Selector-only reads, key scoping instead of providers, and SSR seeding that rides the payload the router already writes._
+
+Server state already has a home: a subscription **is** live server state, and it stays live. What has no home is the rest — which rows are selected, which wizard step you are on, the draft you have not submitted.
+
+Without a primitive for that you reach for zustand or jotai, which is a *parallel runtime* — the one thing the framework asks you not to bring. So it ships one.
+
+```ts
+// wizard.store.ts
+import { defineStore } from '@voltro/client'
+
+export const wizard = defineStore('wizard', () => ({ step: 0, draft: '' }))
+```
+
+```tsx
+const step = wizard.use((s) => s.step)                    // the global instance
+const step = wizard.use((s) => s.step, { key: orderId })  // one instance per order
+
+wizard.set({ step: 2 })
+wizard.set((s) => ({ ...s, step: s.step + 1 }))
+```
+
+## Reads go through a selector — there is no `useStore()`
+
+A component that holds the whole state re-renders on every change to any field, so an API that hands it over would be used and would be wrong. Reading a slice re-renders only when **that slice** changes:
+
+```tsx
+const coupon = wizard.use((s) => s.coupon)   // set({ note }) does not re-render this
+const count  = cart.use((s) => s.items.length) // ['a'] → ['b'] does not re-render this
+```
+
+### Computed values need `equals: shallow`
+
+A selector that *builds* something — an object literal, a mapped or filtered array — returns a fresh reference every call, so the default identity check reports "changed" forever and the component re-renders on **every** store change:
+
+```tsx
+import { shallow } from '@voltro/client'
+
+const visible = cart.use((s) => s.items.filter((i) => i.visible), { equals: shallow })
+const pair    = cart.use((s) => ({ a: s.a, b: s.b }), { equals: shallow })
+```
+
+You do not have to remember: in dev the framework detects the case and warns once, naming the fix. The selector is also memoised — it does not re-run while the state object is unchanged, so an expensive filter costs nothing on unrelated updates.
+
+## Scoping is by key, not by a Provider
+
+A Provider re-renders every consumer when its value identity changes, whether or not that consumer read the field that moved — that *is* what makes context painful at scale. So an instance is addressed by a key you already have:
+
+```tsx
+wizard.use((s) => s.step, { key: orderId })
+```
+
+which is the same model as everywhere else in the framework: `useSubscription('orders.list', { orgId })` is keyed by input, not by position in the tree. One read form, an optional key, no provider to forget.
+
+`wizard.release(orderId)` drops an instance; `wizard.keys()` lists the live ones.
+
+## SSR seeding adds no new channel
+
+Call `seedStore` anywhere on the server during a render and the value reaches the client's first render:
+
+```ts
+export const loader = async ({ params }) => {
+  seedStore(wizard, { step: 2 }, { key: params.orderId })
+  return { /* … */ }
+}
+```
+
+There is no `dehydrate()` to remember and no `hydrate()` to forget — the seed rides the hydration payload the router already writes, and `mount()` applies it before the tree exists. A step you can forget is a step somebody will.
+
+On the client `seedStore` **throws**. A silent no-op would leave the store empty in the browser and full on the server, and that surfaces as a hydration mismatch that reads like a React bug.
+
+**The key is part of the address.** Seed with `{ key: orderId }` and read with `{ key: orderId }`. A component reading the global instance while a loader seeded a key gets the initial value — correct, and easy to trip over once.
+
+## Surviving a reload
+
+`persist` writes the state to `localStorage` (or `sessionStorage`) on every change and reads it back when the store is defined:
+
+```tsx
+export const filters = defineStore(
+  'inbox:filters',
+  () => ({ status: 'open', sort: 'newest', draft: '' }),
+  {
+    persist: {
+      key: 'inbox:filters',
+      storage: 'local',              // 'session' lasts the tab
+      pick: (s) => ({ status: s.status, sort: s.sort }),
+      migrate: (stored) => (isFilters(stored) ? stored : undefined),
+    },
+  },
+)
+```
+
+Three details are the whole reason this is in the framework rather than in your codebase, because a hand-rolled version gets all three wrong:
+
+**The stored value is merged over `initial()`, not substituted for it.** Ship a new field and every returning user has state without it — `undefined` where the type promises a string. Merging means an old payload gains the new defaults.
+
+**`migrate` returning `undefined` discards the value.** A stale draft is an annoyance; a half-migrated one is a bug report nobody can reproduce. Discarding is the right answer far more often than guessing, so it is the easy one to write.
+
+**Every storage touch is guarded and wrapped.** The module is imported by the server render too, and Safari in private mode throws on *reading* `localStorage`, not just on writing. A store that throws at import time takes the page with it.
+
+**A persisted store on a server-rendered page hydrates against the *server* value.** The server has no `localStorage`, so it renders `initial()`; the stored value lands in the commit right after hydration. Without that, every returning user would get a hydration mismatch — a flash and a console error that reads like a React bug. `get()` is not deferred, only the render: an action reading the draft before the first paint reads the draft.
+
+`pick` narrows what gets written — persist the filters, not the open/closed state of every panel. And only the **global** instance persists: a keyed instance is per entity, and writing every key into one bucket grows without bound. Persist a map yourself if you mean to.
+
+## Actions that write more than once
+
+An action rarely touches one field. Applying a coupon writes the coupon *and* the recomputed total; that is one thing the user did, and `batch` says so:
+
+```ts
+checkout.batch('applyCoupon', () => {
+  checkout.set({ coupon })
+  checkout.set({ total: recompute(coupon) })
+})
+```
+
+One notification, one entry in the devtools feed named `applyCoupon`, and **one undo step**. Without it the same action is three of each — Ctrl-Z walks back through a third of a change at a time, and the feed shows three anonymous writes instead of the thing that happened. React batches the re-*renders* on its own; it cannot batch the meaning.
+
+**If the callback throws, every write it made is rolled back.** Nothing was announced yet, so an action that fails halfway cannot leave the half-applied state that is the usual reason people reach for a transaction. A nested `batch` joins its parent rather than opening a second one.
+
+### Async work goes around the batch, not inside it
+
+```ts
+const quote = await fetchQuote(coupon)          // await FIRST
+checkout.batch('applyCoupon', () => {           // then batch the writes
+  checkout.set({ coupon, total: quote.total })
+})
+```
+
+Passing an `async` function to `batch` is an **error**, not a warning. Everything after the first `await` would run outside the batch — writes escaping one at a time, a rollback covering only the synchronous head, and a devtools entry that lies about what the action did. Holding a batch open across time is not available: it would have to block every other write for the duration.
+
+## Undo and redo
+
+Every write passes through one seam, so the previous state is already recorded — undo is a lookup rather than a feature the store had to be designed around:
+
+```tsx
+draft.undo(orderId)      // back one write
+draft.redo(orderId)      // forward again
+draft.canUndo(orderId)   // for disabling the button
+draft.canRedo(orderId)
+```
+
+It is a cursor over an intact history, not a stack that consumes entries. So repeated calls walk back through the steps rather than toggling between the last two, and a **new write after an undo drops the redo tail** — the behaviour every editor has.
+
+An undo never becomes undoable itself, and each keyed instance has its own history.
+
+## Devtools: inspect, and travel
+
+The `voltro dev` overlay has a **Stores** tab. It lists every defined store with its live state — global and per key — and a feed of every write: which store, which key, the label if you passed one, and the fields that actually changed.
+
+`◀ Back` and `Forward ▶` step through that feed, restoring the state as it was before or after each write. The state a component reads moves with it, so you can walk back to the moment before a bug and watch it happen again.
+
+No extension, no connector, no version to match. Every write already passes through one seam, so the panel is just another subscriber — it sees writes made by code that never heard of devtools, on any machine, including a colleague's.
+
+## What a store must never hold
+
+Server data. Copying a subscription's rows into a store gives you a second copy that does not live; the page then renders the stale one, and the bug presents as *"reactivity is broken"*. `voltro doctor` reports a `*.store.ts` that reads a subscription.
+
+Read server state where you render it, and keep the store for what is genuinely client-side.
+
+
+
 ---
 
 <!-- source: en/data/outbox.md -->
@@ -3522,7 +3560,7 @@ plugin's `tables` option, then read a timeline or restore a snapshot:
 import { versioningPlugin, rowHistory, restoreAsOf } from '@voltro/plugin-versioning'
 
 // Register in your app's plugin list:
-versioningPlugin({ tables: ['blogPost_published', 'blogPost_drafts'] })
+versioningPlugin({})
 
 const timeline = await rowHistory(ctx.store, 'blogPost_published', postId, tenantId)
 await restoreAsOf(ctx.store, 'blogPost_published', postId, tenantId, someEarlierDate)

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

@@ -1556,6 +1556,37 @@ no-ops out.
 
 The cloud dashboard surfaces per-env state with a multi-env tab in the [cloud UI](./cloud-ui.md).
 
+## File-based migrations in this pipeline
+
+`voltro db apply` runs pending `migrations/*.ts` **first**, then diffs — the same order the boot path uses.
+
+`voltro db apply --plan plan.json` does **not** run them. It **refuses** when any are pending:
+
+```txt
+db apply --plan: refusing — 2 pending file-based migration(s).
+  20260714_090000_split_full_name
+  20260721_143000_backfill_slug
+
+  These perform the changes a state diff cannot infer, so they change the shape
+  this plan was computed against. Apply them and regenerate the plan:
+
+    voltro db files .
+    voltro db plan --json > plan.json
+    voltro db apply --plan plan.json
+```
+
+That is not caution for its own sake. A saved plan was computed and reviewed against an earlier state; a file migration performs exactly the kind of change (a table split, a cross-table data move) that makes the plan stale. Running the migrations first would trip the fingerprint guard immediately afterwards and leave a half-applied deploy; running them after would apply a plan reviewed against a state that no longer exists.
+
+**So a pipeline that uses the saved-plan form needs `voltro db files` as its own step**, before the plan is generated:
+
+```bash
+voltro db files .                          # authored data steps
+voltro db plan --json > plan.json          # diff, now against the corrected shape
+voltro db apply --plan plan.json           # reviewed, fingerprint-guarded
+```
+
+If you use plain `voltro db apply` instead, the first step is already included.
+
 
 
 ---
@@ -3201,6 +3232,35 @@ Fix:
   resolves the root from the first non-flag argument, defaulting to
   the current working directory
 
+## "N reactive table(s) have NO change trigger in the database" (postgres)
+
+```text
+auto-migrate: 500 reactive table(s) have NO change trigger in the database —
+ab_test_results, ab_test_variants, ab_tests, … (+492). Writes to them will not
+reach another instance's subscribers; a single instance is unaffected, which is
+why this stays invisible until you scale out. Run `voltro db apply` to install them.
+```
+
+On postgres, reactivity is carried by DDL: a per-table `framework_changes_<table>` trigger that `NOTIFY`s the CDC channel. The declared schema and the database can disagree about which tables have one.
+
+**Run `voltro db apply`.** It converges the triggers as its own step, and it does so **even when the schema diff is empty** — the usual case here, because a missing trigger is not a shape difference and `db plan` will correctly report `0 operations`:
+
+```text
+$ voltro db apply
+schema diff: 0 operations, 0 blocked
+  (schema is up to date)
+db apply: installing change triggers on 500 table(s)
+db apply: change triggers converged (1501 statement(s))
+```
+
+`db apply --plan` converges them too, so the pre-deploy Job pattern needs no extra step.
+
+**Why a table ends up without one.** The trigger DDL is emitted by the full-schema path — a fresh database — so any table that arrived while your app was already running, or during a release that installed none, has no trigger. A restored dump can do it too (triggers travel with a full dump, but not with a schema-only or `--no-triggers` one), as can a hand-run `DROP TRIGGER` during an incident.
+
+**Why it stays invisible.** A single instance's own writes reach its own subscribers through the in-process path. The trigger is what carries a write to the *other* instances, so the symptom only appears when you scale out — subscriptions that quietly stop updating, with nothing in the logs.
+
+The mirror case is reported the same way: a `.nonReactive()` table that still carries a trigger keeps paying `REPLICA IDENTITY FULL` and a `NOTIFY` on every write for a subscription nobody receives. `db apply` removes both.
+
 ## When the fix hint doesn't match reality
 
 The fix hints come from the planner's classification logic — they should always be actionable. If you see one that doesn't make sense given your code:
@@ -3219,3 +3279,66 @@ Hint mismatches are bugs in the planner's classification — they're rare but al
 - [Drift](./drift.md) — when the live DB diverged
 - [Multi-dialect strategy](./multi-dialect.md) — why MySQL + forward-roll
 - [Prod pipeline](./prod-pipeline.md) — the deploy-step apply pattern
+
+
+
+---
+
+<!-- source: en/database/migrations/adopt.md -->
+## Adopting a table into a plugin's
+
+_voltro db adopt — move an app's grown table into a plugin-owned one, with a snapshot, a count verify and the drop last._
+
+An app that did not start on a green field already has a table for half the plugins it installs. `voltro db adopt` is the way **into** the plugin's table, so using the plugin does not mean running a second source of truth beside it.
+
+```bash
+voltro db adopt --from ai_flows --into _voltro_ai_flows --map ./ai-flows.map.ts
+voltro db adopt --from ai_flows --into _voltro_ai_flows --map ./ai-flows.map.ts --apply
+```
+
+**Dry run unless you pass `--apply`.** The interesting failure here is irreversible and the interesting output is the refusal, so nothing is written until you say so. A refused plan prints no steps at all, rather than a preview of something that will not happen.
+
+## The map file is yours
+
+```ts
+// ai-flows.map.ts
+export default {
+  map: {
+    name:         'name',
+    mode:         { expr: `CASE WHEN "allowDeviation" THEN 'agentic' ELSE 'deterministic' END` },
+    costMicroUsd: { expr: '"totalCostCents" * 10000' },
+  },
+  leaveUnset: ['id'],
+}
+```
+
+Read `target: source` — fill the plugin's column FROM this expression of mine, which is the direction the SQL runs. A string is a source column; `{ expr }` is raw SQL against the source row, for the unit conversions and merged fields no tool can infer. Those are domain knowledge, and a tool inventing them silently corrupts data.
+
+`leaveUnset` is how "the target's own default fills this" stops looking like "I forgot it".
+
+## What it refuses
+
+- **a NOT NULL target column nobody maps to** — the alternative is a silent zero that reads as real data forever after;
+- **a target table that already holds rows** — adopt MOVES rows into a table, it does not merge into one somebody else already wrote;
+- **a typo on either side of the map.**
+
+A source column nobody carries across is reported but not fatal: dropping a dead column is deliberate often enough, and "I forgot this" and "I decided" look identical in a map file.
+
+## The order, and why the drop is last
+
+1. **snapshot** — `<table>__adopt_snapshot`, a real table in the same database, so restoring is a statement rather than an operational procedure at 2am. It keeps the columns the adopt left behind.
+2. **copy**
+3. **verify by count** — this catches the one failure that is otherwise invisible: a `WHERE` inside a raw expression silently dropping rows.
+4. **drop the source** — last, and only if the counts match.
+
+On a mismatch **both tables stay** and the command says so. The snapshot is never removed after a failed verify — it exists for exactly the run that goes wrong. `--keep-source` copies and verifies without dropping at all.
+
+## Ids, if the typeid prefixes differ
+
+The dry run says so before anything runs, because discovering it after the copy is discovering it too late: every row gets a new id, so every reference to the old table has to be rewritten — **including ids embedded in JSON columns**.
+
+Rewriting them is **not** automatic. Those ids live in your columns and inside your JSON, and only you know where. The translation table is what the command owes you; the rewrite is what you owe yourself. Doing it automatically is the one place here where being wrong would be silent.
+
+## After the move
+
+Your rows are now in a table whose shape the framework evolves — and nothing special happens to them. They migrate exactly like every other row, through the same declarative differ. A narrowing can fail on your data, loudly, the same way it would on anybody's.

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

@@ -225,6 +225,18 @@ DB_URL=file:./db.sqlite     # or `:memory:` for ephemeral
 
 The `app.config.ts` `store:` field stays as the dev-friendly shortcut (`store: 'postgres'`, `store: 'memory'`) — env always wins.
 
+### Query timeout — bound a runaway query
+
+```sh
+DB_STATEMENT_TIMEOUT_MS=30000   # cancel any single query after 30s
+```
+
+A missing index or an accidental cartesian join can run for minutes, and while it does it **pins a pooled connection**. Enough of them under load and the pool is exhausted — every other request now waits on a connection that will never free, and the whole app stalls. `DB_STATEMENT_TIMEOUT_MS` puts a ceiling on it: a query that outlasts the deadline is cancelled, its connection returns to the pool, and the caller gets a normal error instead of a hang.
+
+It applies to the **runtime query path only**. Migrations (`voltro db apply`) run legitimately long statements — backfills, index builds — and are **never** cancelled by it. (Caveat: `voltro dev`'s boot auto-migrate shares the app connection, so a very slow dev migration under a low timeout would trip it — raise the value, or run `voltro db apply` first.)
+
+**Wired for postgres today** (the default dialect), where it maps to the server-side `statement_timeout` — a real, server-enforced cancel (SQLSTATE `57014`), not a client-side disconnect that leaves the query running. Other dialects accept the variable but currently ignore it, and the reasons are honest rather than incidental: `@effect/sql-mssql` exposes only a connection-establishment timeout, not a per-request one; MySQL/MariaDB's `max_execution_time` bounds `SELECT`s only (writes stay unbounded), which would be a misleading half-guarantee; and SQLite is in-process with a single connection, so there is no pool to protect. Unset (or any non-postgres dialect) = no timeout.
+
 ## Local development — bring up all five
 
 The framework ships a docker-compose at `voltro/test/docker-compose.yml` that brings up postgres + mysql + mariadb + mssql on distinct ports so per-dialect tests can run side-by-side and the dev fixture never clashes with your starter postgres on `:5432`: