@voltro/cli 0.27.0 → 0.29.0

package/templates/agent-docs/data.md

@@ -1024,6 +1024,67 @@ const message = matchError(err, {
 }, () => 'Something went wrong')
 ```
 
+## Cross-table business rules — `.rule()`
+
+A [typed error](#typed-errors) is declared on ONE mutation. A **rule** is declared on a TABLE: an invariant the runtime enforces on EVERY mutation that writes that table, no matter which one did the write. Declare it in the schema with `.rule(name, predicate)`:
+
+```ts
+import { table, id, integer, eq } from '@voltro/database'
+import { database } from '../database/schema'
+
+export const invoices = table('invoices', {
+  id:    id(),
+  total: integer(),
+}).rule(
+  'totalMatchesLineItems',
+  async (row, { store }) => {
+    const items = await store.query(
+      database.lineItems.where(eq('invoiceId', row.id)).descriptor,
+    )
+    const sum = items.reduce((acc, l) => acc + Number(l.amount), 0)
+    return sum === row.total || { params: { computed: sum, declared: row.total } }
+  },
+)
+```
+
+The predicate receives the **post-write row** and a `context` whose `store` is the SAME transactional store the mutation wrote through — so a cross-table read shares the write's MVCC snapshot and cannot race it. It runs INSIDE the mutation transaction, after the write and before commit, and it is dialect-neutral (the same predicate is correct on all four dialects — no per-dialect code). Return `true` (or nothing) when the invariant holds; return `false` or a `RuleViolationDetail` (`{ params?, field?, message? }`) to signal a violation for THIS row.
+
+Unlike [`.check()`](/docs/database/columns#db-level-checks) — a single-row SQL `CHECK` the DATABASE enforces as DDL — a rule is a PREDICATE the runtime evaluates, so it can read OTHER tables. Use `.check()` when the database itself must guarantee a single-row constraint; reach for `.rule()` for a cross-table invariant (an invoice total matching its line items, a booking not exceeding a resource's capacity).
+
+### The violation is a typed error — automatically
+
+A violated `error`-severity rule rolls the whole mutation back and fails with the typed, wire-preserved **`BusinessRuleViolation`**. You do **not** declare it on the mutation's `error:` — the runtime auto-merges it into every mutation's error union at the wire boundary, exactly like `ScopeError`. A rule declared on a SCHEMA table can fail ANY mutation that writes that table, so no single descriptor could know to declare it; the auto-merge is what keeps the violation a typed error the client decodes by `_tag` rather than an untyped defect.
+
+Match it on the client the same way as any [typed error](#matching-typed-errors-on-the-client):
+
+```ts
+import { errorTag } from '@voltro/protocol'
+
+try {
+  await createInvoice(input)
+} catch (err) {
+  if (errorTag(err) === 'BusinessRuleViolation') {
+    // err.rule — the rule name; err.params — the offending values; err.field — the pointer
+  }
+}
+```
+
+`BusinessRuleViolation` carries `rule` (the declared name), optional `params` (i18n params for the offending values), an optional `field` pointer, and `severity` (always `'error'` on the wire — a warning-severity rule never reaches the client as an error).
+
+### `severity: 'warning'` — log without blocking
+
+```ts
+export const invoices = table('invoices', { id: id(), total: integer() }).rule(
+  'totalMatchesLineItems',
+  async (row, { store }) => true,
+  { severity: 'warning' },
+)
+```
+
+A `warning`-severity rule LOGS and audits the violation but lets the write commit — useful while backfilling data that does not yet satisfy a newly-added invariant. The default is `'error'` (roll back).
+
+Rules run on `voltro dev` and `voltro serve` through the same mutation runner, so the two boot paths cannot disagree about whether a rule fires. Inserts and updates on your own tables are re-validated; a delete is not (there is no post-write row to check).
+
 ## `internal: true` — off the wire entirely
 
 Every discovered `*.mutation.ts` / `*.query.ts` / `*.action.ts` / `*.stream.ts` is
@@ -1472,6 +1533,88 @@ A subscription that was live and is then skipped goes idle — it does **not**
 keep serving the snapshot it still holds. Otherwise `skip: !open` would show
 last time's data the moment a dialog reopens.
 
+## SSR preload — first paint with data
+
+By default a `useSubscription` on an SSR page flashes its empty/loading state on
+mount, THEN opens the WebSocket and fetches the first snapshot — even though the
+server could have fetched that value during the render. **`usePreloadedSubscription`**
+closes that gap: it reads its first value from the SSR hydration payload, renders
+real data on the first paint, then upgrades to the live stream the instant its
+first snapshot lands.
+
+Two things wire it up: the hook, and a `preload` export on the page.
+
+```tsx
+import { usePreloadedSubscription } from '@voltro/client'
+
+export const preload = ['notes.list']
+
+export default function NotesPage() {
+  const { data } = usePreloadedSubscription<Note[]>('app', 'notes.list')
+  // `data` is present on the first paint — no loading flash
+  return <NotesTable notes={data} />
+}
+```
+
+`export const preload` lists the subscriptions the page's tree needs at first
+paint. During the SSR render (`voltro dev` and `voltro start`) the framework runs
+each one server-side — the SAME `ctx.query(tag, input)` a loader receives — and
+seeds the result into the hydration payload. The client's
+`usePreloadedSubscription` finds the seed by the SAME cache key `useSubscription`
+uses, so the server markup and the client hydration render read an identical
+value — there is no hydration mismatch. The live subscription still opens and
+takes over; the seed is only the first value, never the source of truth.
+
+### `preload` entries
+
+An entry is either a bare tag or a tag plus an `input` derived from the route
+params:
+
+```tsx
+export const preload = [
+  'teams.list',                                                    // no input
+  { tag: 'project.detail', input: (params) => ({ id: params.id }) },
+]
+```
+
+The `input` you derive here MUST match the `input` you pass the hook — both
+address the same cache entry:
+
+```tsx
+export default function ProjectPage({ params }: { params: { id: string } }) {
+  const { data } = usePreloadedSubscription('app', 'project.detail', { id: params.id })
+  return <ProjectView project={data} />
+}
+```
+
+### Falls back to `useSubscription`
+
+When no seed exists for the key — a client-side SPA navigation the server never
+rendered, or the static prerender (which has no live api origin) —
+`usePreloadedSubscription` behaves EXACTLY like `useSubscription`: it loads until
+the stream answers. So it is always safe to reach for; the preload is a
+first-paint optimization, never a correctness dependency. A failed preload is
+likewise non-fatal — the live subscription still delivers the value on the
+client, the only loss is the first-paint seed.
+
+### Seeding by hand
+
+`export const preload` is sugar over an explicit seed. When a loader ALREADY has
+the value — you fetched it for the `<title>`, a breadcrumb, or the row name — seed
+it directly with `seedPreloadedSubscription` (server-side only) instead of
+fetching it a second time:
+
+```ts
+import { seedPreloadedSubscription } from '@voltro/client'
+
+// inside a loader / layout loader, server-side
+const notes = await ctx.query('notes.list', {})
+seedPreloadedSubscription('app', 'notes.list', {}, notes)
+```
+
+Calling it outside a server render throws — on the client the live subscription
+already provides the value, so a client-side seed would be meaningless.
+
 ## Streams Are Different
 
 For non-database or transient element feeds, use [streams](/docs/data/streams), not subscriptions:
@@ -2697,6 +2840,145 @@ export default defineAggregate({
 
 When no analytics sink is configured the framework provides the no-op sink: the read methods fail with `AnalyticsCapabilityNotSupported({ provider: 'noop' })`, which surfaces as a refresh error (last-good rows are preserved). Provider-specific queries beyond the four-method contract (raw SQL, HyperLogLog) live outside the sink — there is no raw-client escape hatch; query the provider with your own client instance inside the build function where you need them.
 
+## Standing IVM siblings — expectations, cost budgets, experiments
+
+Three more primitives are built on the same engine as `defineAggregate({ incremental })` — they reduce a table to a value maintained incrementally from `store.onChange` CDC deltas (O(1) per write, no re-query). Unlike an aggregate you never `read()` a materialised table; you **observe a live signal** through a framework registry and a `useX(def)` handler-sugar. Each is discovered by its own file convention and wired into both `voltro dev` and `voltro serve`.
+
+| Primitive | File | Reduces a table to | Observe with |
+|---|---|---|---|
+| `defineExpectation` | `*.expectation.ts` | a `holding`/`violated` data-quality signal | `useExpectation` / `ExpectationRegistry` |
+| `defineCostBudget` | `*.budget.ts` | per-tenant compute-cost attribution + `ok`/`warn`/`exceeded` budgets | `useCostBudget` / `CostRegistry` |
+| `defineExperiment` | `*.experiment.ts` | per-variant metric + lift (live A/B / holdout) | `useExperiment` / `ExperimentRegistry` |
+
+They are **soft, observability-grade signals** — none of them ever blocks a write. Rejecting a write is a business rule's job (`table().validate(Schema)`); running an agent/workflow on a change is [`*.reaction.tsx`](/docs/data/reactions). These three only *watch* and *report*.
+
+### Data-quality expectations (`*.expectation.ts`)
+
+A `defineExpectation` is a standing data-quality contract over a table. Where dbt tests / Great Expectations run in BATCH and catch bad data hours later, an expectation re-evaluates on every write and tips `holding`↔`violated` the instant an invariant breaks — tracing the violation to the write that caused it (the CDC event's `traceId` / `subjectId` / `procedure`).
+
+```ts
+// apps/api/expectations/orderFreshness.expectation.ts
+import { defineExpectation } from '@voltro/runtime'
+
+export default defineExpectation({
+  name: 'orders-fresh',
+  on: { table: 'orders' },      // its CDC deltas drive re-evaluation
+  invariant: { kind: 'freshness', column: 'createdAt', maxAgeMs: 10 * 60_000 },
+  severity: 'critical',         // 'info' | 'warn' (default) | 'critical' — alerting priority only
+})
+```
+
+The default export must be the return value of `defineExpectation({...})` — the cli discovers `*.expectation.ts` files by that branded shape.
+
+Four invariant kinds, each reducing the table to one incrementally-maintained metric:
+
+```ts
+{ kind: 'freshness',   column: 'createdAt', maxAgeMs: 600_000 }              // newest row no older than X (re-checked on a clock tick too)
+{ kind: 'nullRate',    column: 'email', maxRate: 0.01 }                      // ≤ 1% of rows null in `column`
+{ kind: 'rowCount',    min: 1, max: 100_000 }                               // COUNT(*) within [min, max]
+{ kind: 'valueBounds', column: 'price', min: 0, max: 1000, maxViolationRate: 0.05 } // ≤ 5% of rows out of [min, max]
+```
+
+An optional `on.where` predicate narrows the population the invariant is asserted over — it runs server-side per row and never leaves the server, so it can be any predicate:
+
+```ts
+on: { table: 'orders', where: (row) => (row['status'] as string) === 'paid' }
+```
+
+Observe one expectation from a handler with `useExpectation`, or read the whole surface off `ExpectationRegistry`:
+
+```ts
+import { Effect } from 'effect'
+import { useExpectation } from '@voltro/runtime'
+import ordersFresh from '../expectations/orderFreshness.expectation'
+
+export default (input, _ctx) =>
+  Effect.gen(function* () {
+    const state = yield* useExpectation(ordersFresh)
+    // state: { status: 'holding' | 'violated' | 'unknown', metric, threshold,
+    //          since, lastEvaluatedAt, lastCause, ... } | null (null = not registered)
+    return { degraded: state?.status === 'violated' }
+  })
+```
+
+`ExpectationRegistry` exposes `snapshot()` (every expectation's state — the inspect feed), `get(name)`, `violations()` (the alerting view), and `subscribe(listener)` for `violated`/`recovered` transitions. A transition carries the causing write's provenance; a `freshness` SLA aging out with no write reports `cause: null` — the honest "no write caused this; the ABSENCE of writes did".
+
+### Cost budgets (`*.budget.ts`)
+
+A `defineCostBudget` is a reactive-FinOps primitive: per-tenant / per-subscription compute-cost attribution plus a budget every tenant is held to independently. It is to reactive compute what AI's `requireAiBudget` is to USD spend — a standing per-tenant ceiling that crosses `ok`→`warn`→`exceeded` and recovers on a window rollover.
+
+```ts
+// apps/api/budgets/tenantCompute.budget.ts
+import { defineCostBudget } from '@voltro/runtime'
+
+export default defineCostBudget({
+  name: 'tenant-compute',
+  limit: 100_000,       // the per-tenant ceiling, in the budget's unit
+  unit: 'recompute',    // which cost unit to meter; omit ⇒ the tenant's TOTAL across every unit
+  warnAt: 0.8,          // fraction of `limit` at which it goes 'warn' (default 0.8; set 1 to disable)
+  window: '24h',        // tumbling window — the counter resets each boundary; omit ⇒ cumulative since boot
+  severity: 'warn',     // 'info' | 'warn' (default) | 'critical'
+})
+```
+
+Observe one budget for one tenant with `useCostBudget(def, tenantId)`:
+
+```ts
+import { Effect } from 'effect'
+import { useCostBudget } from '@voltro/runtime'
+import tenantCompute from '../budgets/tenantCompute.budget'
+
+export default (input, ctx) =>
+  Effect.gen(function* () {
+    const state = yield* useCostBudget(tenantCompute, ctx.tenantId)
+    // state: { status: 'ok' | 'warn' | 'exceeded', spent, limit, warnThreshold, ... } | null
+    return { overBudget: state?.status === 'exceeded' }
+  })
+```
+
+`CostRegistry` exposes `attribution()` (per-tenant chargeback/showback rows — `total` + `byUnit` + `bySubscription`), `tenant(tenantId)`, `budgets()`, `budget(name, tenantId)`, `breaches()` (the alerting view), and `subscribe(listener)` for threshold crossings.
+
+> **Reactive recomputes now feed attribution automatically.** Declaring any `*.budget.ts` wires the dispatcher's `recordCost` tap in both boot paths: every time a source-row change re-runs an affected subscription and pushes it a delta, one `{ unit: 'recompute', amount: 1 }` cost event is attributed to that subscription's tenant (and traceId). So a tenant's `total`/`spent` populates from real reactive work — a `unit: 'recompute'` budget crosses `ok`→`warn`→`exceeded` as deliveries accrue, and recovers on a window rollover. The emission is **per delivered recompute** — one event per subscription the change fanned out to, on both the row-set and computed-query delivery paths. An app that declares NO cost budget wires no tap and allocates nothing on the reactive hot path.
+
+### Online experiments (`*.experiment.ts`)
+
+A `defineExperiment` is a live A/B / holdout experiment expressed as IVM aggregates. Assignment is a deterministic salted hash (subject → variant, no stored assignment table, reproducible on the client); the success metric is maintained PER VARIANT from the watched table's CDC — so lift vs a baseline is real-time, with no batch pipeline. It differs from `plugin-flags` (which GATES a code path) — an experiment MEASURES the outcome.
+
+```ts
+// apps/api/experiments/checkoutColor.experiment.ts
+import { defineExperiment } from '@voltro/runtime'
+
+export default defineExperiment({
+  name: 'checkout-button-color',
+  on: { table: 'orders' },                      // its CDC deltas drive the live recompute
+  subject: 'userId',                            // stable per-subject bucketing (a column name, or a (row) => key fn)
+  variants: [{ name: 'control' }, { name: 'green', weight: 1 }],   // ≥ 2 arms; `weight` skews the split (default 1)
+  holdout: 0.1,                                 // 10% held out entirely, for a clean untouched baseline
+  metric: { kind: 'conversionRate', column: 'completed' },         // per-variant success metric
+  baseline: 'control',                          // which variant lift is measured against (default: the first)
+})
+```
+
+Metric kinds: `{ kind: 'count' }`, `{ kind: 'sum', column }`, `{ kind: 'avg', column }`, and `{ kind: 'conversionRate', column, equals? }` (converted iff `row[column]` is truthy, or `=== equals` when given). `avg` / `conversionRate` are per-subject rates that a lift reads honestly; `count` / `sum` reflect exposure too, so their cross-variant comparison only means "more/less total".
+
+Observe the live result with `useExperiment`, or off `ExperimentRegistry`:
+
+```ts
+import { Effect } from 'effect'
+import { useExperiment } from '@voltro/runtime'
+import checkoutColor from '../experiments/checkoutColor.experiment'
+
+export default (input, _ctx) =>
+  Effect.gen(function* () {
+    const result = yield* useExperiment(checkoutColor)
+    // result: { totalExposure, baseline, variants: [{ variant, isBaseline, isHoldout,
+    //           exposure, metric, lift, diff }, ...], lastUpdatedAt, ... } | null
+    return { arms: result?.variants ?? [] }
+  })
+```
+
+Each variant row carries its `exposure` (sample size), the maintained `metric`, and — for non-baseline arms — `lift` (`(metric − baseMetric) / baseMetric`) and `diff` (absolute). `ExperimentRegistry` exposes `snapshot()`, `get(name)`, and `subscribe(listener)` for the live recompute stream that a results view redraws from. The same-subject-same-variant assignment is a pure function (`assignVariant(def, subject)`) a client can reproduce.
+
 
 
 ---

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

@@ -658,6 +658,53 @@ export const users = table('users', {
 
 The cleanup is a separate PR after the migration has rolled out. Don't mix the rollout PR with the cleanup PR — the markers ARE the migration's audit trail until it's applied everywhere.
 
+## `voltro evolve` — the schema-evolution copilot
+
+Adding the `.renamedFrom()` marker by hand is easy for one column. The hard part of changing an EXISTING schema is the *rest*: which handlers read or write that column, whether a rename is safe or needs a backfill, and getting the annotation onto the entity AND every call site without missing one. `voltro evolve` does that reconnaissance and proposes a reviewable plan.
+
+Given a change, it reads the **observed graph** (`app.graph.observed.generated.json`, recorded by `voltro dev` — see [`voltro check`](/docs/cli/inspect)) plus the declared manifest, enumerates the real blast radius, and prints three things: a proposed **codemod**, a branch-verified **backfill** plan, and a `voltro check` **verify** step.
+
+```bash
+voltro evolve rename-column notes.title --to heading            # dry-run: plan + codemod preview
+voltro evolve rename-column notes.title --to heading --write    # apply the codemod
+voltro evolve retype-column orders.total --to numeric           # reshape → manual codemod + steps
+voltro evolve split-column users.name --into firstName,lastName
+voltro evolve rename-table note --to notes
+voltro evolve drop-column notes.legacy
+voltro evolve rename-column notes.title --to heading --json     # for CI / an agent loop
+```
+
+It is **dry-run by default** (mirrors `voltro generate`); `--write` applies the codemod through the same `runCodemods` toolkit as `voltro update`. `--json` emits the whole plan for CI or an agent.
+
+### The blast radius is observed, not guessed
+
+```text
+change: rename-column notes.title → heading
+
+blast radius (observed + declared):
+  query(notes.list) — observed read
+  mutation(notes.update) — observed update
+  ⚠ 1 declared but NEVER exercised — column use UNKNOWN: notes.archive
+
+codemod:
+  entity: rename 'notes.title' → 'heading' and add .renamedFrom('title') (catalog rename — data preserved)
+  annotate 2 handler site(s) that reference the old field
+
+backfill (dry-runs on branch notes-pr-0):
+  [safe] catalog RENAME — no data movement
+
+verify: voltro check
+```
+
+A handler that a `voltro dev` session or a test actually ran is reported with what it did (`observed read` / `observed update`). A handler that is *declared* to touch the table but was **never exercised** is flagged `UNKNOWN` and listed separately — it is never folded into "safe", because no run proves what it does with the column. That honesty is the point: the tool tells you exactly where it cannot vouch for the change.
+
+### What the codemod does per kind
+
+- **`rename-column`** gets a real `transform`: it renames the field in the `*.entity.ts` AND chains **`.renamedFrom('old')`** (so the differ plans a catalog RENAME, not the lossy drop+create described [above](#renamedfromoldname)), then annotates the handler sites the blast radius found.
+- **`retype-column` / `split-column` / `drop-column` / `rename-table`** are reshaping changes with no single mechanical rewrite, so they get a **`manual`** codemod: a generated, numbered checklist of the edits + the annotation to add, printed for you to apply.
+
+`voltro evolve` produces the plan; it does not apply the schema change. **`voltro check` is the gate on the result**, and `voltro db apply` lands it — after `--write`, review the annotated handlers, then run those two.
+
 
 
 ---

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

@@ -296,6 +296,63 @@ who may receive the plaintext — a private note you decrypt *for its owner* is
 valid case, so treating "encrypted" as "never to a client" would be wrong. State
 the exposure policy explicitly.
 
+## `.readableBy(...scopes)` — visible only to scoped subjects
+
+The **graded middle of the same wire-exposure axis** as `.serverOnly()` — not a
+fourth axis. A plain column is visible to everyone who can read the row;
+`.serverOnly()` hides it from every client; `.readableBy(...)` sits between them —
+the column reaches a subject only if it holds the scope:
+
+```ts
+import { id, integer, text, table } from '@voltro/database'
+
+export const invoices = table('invoices', {
+  id:          id(),
+  number:      text(),                                        // visible to everyone
+  amountCents: integer().readableBy('billing:read'),          // only billing-scoped subjects
+  taxNote:     text().readableBy('billing:read', 'admin:pii'), // ANY of the two scopes
+})
+```
+
+**What it does:** a column marked `.readableBy(...scopes)` is stripped from the
+wire OUTPUT for any subject holding NONE of the listed scopes, and present for
+one holding **at least one** of them. Like `.serverOnly()` it changes nothing at
+rest and nothing in the DDL — it is a wire concern only, so a server-internal
+read (`ctx.store.query`) still sees the value; the strip applies only on the way
+out to a client.
+
+**Scope semantics:**
+
+- **≥ 1 scope, OR-matched.** A subject sees the column iff it holds at least one
+  of the listed scopes — `.readableBy('a', 'b')` means "a OR b", not both.
+- **Effective scopes.** The check is the framework's `hasEffectiveScope` — the
+  subject's RAW scopes **∪** its rbac role-derived scopes — so a role that grants
+  `billing:read` unlocks the column even when the scope is not listed directly on
+  the subject.
+- **`admin:full` bypasses it.** A subject holding `admin:full` sees every
+  `.readableBy(...)` column, exactly as it satisfies every guard.
+- **At least one scope is required.** `.readableBy()` with no scope would mean
+  "readable by nobody" — that is `.serverOnly()` — so both the empty call and a
+  blank scope string are rejected at declaration.
+
+**`.serverOnly()` wins when both are present.** `.serverOnly()` is the all-hidden
+end of the axis, so a column carrying both is hidden from EVERYONE — `admin:full`
+included. `.readableBy()` only ever *narrows* an otherwise-visible column; it can
+never re-expose a `.serverOnly()` one:
+
+```ts
+amountCents: integer().readableBy('billing:read'),          // scoped subjects see it; admin:full does too
+secretKey:   text().serverOnly().readableBy('billing:read'), // serverOnly wins → hidden from EVERYONE
+```
+
+Enforcement shares the SAME chokepoint as `.serverOnly()` — the Dispatcher's read
+boundary — but resolves **per subject**: it applies to a query's initial snapshot
+AND every reactive subscription delta, and to the one-shot
+[`publicApi`](/docs/data/rest-routes) REST GET, in both boot paths (`voltro dev`,
+`voltro serve`). A table that declares no `.readableBy(...)` column pays nothing —
+the strip collapses to the subject-independent `.serverOnly()` set and the
+dispatcher's read/diff memo is still shared across all subscribers of a change.
+
 ## Worked example
 
 ```ts

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

@@ -280,7 +280,9 @@ Two layers enforce row invariants, and they're complementary:
 
 - **`table().validate(Schema)` (below)** — app-level `effect/Schema` validation, run before the INSERT/UPDATE. Use it for the rich stuff a portable `CHECK` can't express: regex / email / structured strings, length ranges, numeric bounds, cross-field rules with custom typed errors. It's the single validation surface — don't reach for a pile of `.min()` / `.max()` / `.pattern()` column modifiers (there aren't any, by design).
 
-Rule of thumb: **`.check()` when the DATABASE must guarantee it; `validate(Schema)` for everything else.** There is no `.comment()` / `.index()` column modifier — indexes are table-level.
+- **`table().rule(name, predicate)` (cross-table)** — neither of the above can read ANOTHER table. A [business rule](/docs/data/mutations#cross-table-business-rules-rule) is a predicate the runtime evaluates inside the mutation transaction, so it can compare the written row against rows in other tables (an invoice total vs. its line items) and rolls the mutation back with a typed `BusinessRuleViolation` on failure.
+
+Rule of thumb: **`.check()` when the DATABASE must guarantee a single-row constraint; `table().rule()` for a cross-table invariant; `validate(Schema)` for everything else.** There is no `.comment()` / `.index()` column modifier — indexes are table-level.
 
 ## Default with callback
 

package/templates/agent-docs/deployment.md

@@ -1150,6 +1150,59 @@ KV_BACKEND=redis
 
 Schedules and aggregates auto-coordinate via an advisory lock on SQL stores — no extra config to keep them from double-firing across replicas.
 
+### The prerequisites you learn at the SECOND pod
+
+Every item below is invisible on one replica and breaks on two. They are
+collected here because an operator reported each of them separately, each found
+the same way: the first pod proved the configuration worked.
+
+**The connection pool multiplies, the database limit does not.**
+
+```sh
+DB_MAX_CONNECTIONS=10       # per replica — the fleet opens up to this × replicaCount
+```
+
+The framework opens ONE pool per process. At 4 replicas a pool of 10 is 40
+connections against a database that still allows whatever it allowed before you
+scaled. An operator's second pod died on `Connection timed out` for exactly
+this. `voltro serve` now prints the number and the arithmetic at boot:
+
+```
+db pool: max=10 per replica (DB_MAX_CONNECTIONS) × 4 replicas = up to 40 connections.
+```
+
+Set `REPLICA_COUNT` from your deployment (Helm: `{{ .Values.replicaCount }}`) and
+the line does the multiplication for you; without it the line still names the
+formula. `voltro dev` deliberately does not print it — one process, no replicas.
+
+**`POD_IP` is each replica's identity, not only a workflow setting.**
+
+```yaml
+env:
+  - name: POD_IP
+    valueFrom:
+      fieldRef:
+        fieldPath: status.podIP
+```
+
+Without it every replica registers under the same host, so they are one runner
+as far as the cluster is concerned. The boot warning for it fires only on SQL
+cluster storage, so a deployment that has not adopted durable workflows yet gets
+no signal at all — inject it as a matter of course.
+
+**Derive the broadcast namespace from something that cannot be forgotten.**
+
+```yaml
+- name: VOLTRO_BROADCAST_NAMESPACE
+  value: {{ .Release.Namespace }}
+```
+
+Staging and production of the same app share a name, code and fingerprint, so
+the auto-derived namespace does NOT separate them — only this variable does. An
+operator's own guidance, and better than ours was: a value taken from the
+release namespace cannot be left out of one environment's config file, because
+there is no file to forget.
+
 ### Workflow failover across replicas
 
 On a **SQL store** (postgres / mysql / mariadb / mssql), durable workflows survive a replica crash: completed `step({...})` activities are checkpointed in the cluster journal, so when a replica dies mid-run, a **surviving replica takes over the run and continues it from the last completed step** — it replays the completed steps rather than re-running them. (On sqlite the engine is single-process — durable within one replica, no cross-replica failover.) Two requirements:
@@ -1181,6 +1234,9 @@ Lower the lease for **faster failover**, at the cost of **false-positive reclaim
 - [ ] `VOLTRO_LOG_FORMAT=json`; `sentryPlugin()` + `SENTRY_DSN` for errors
 - [ ] `terminationGracePeriodSeconds` generous for graceful drain; `VOLTRO_SHUTDOWN_GRACE_MS` set just under it (minus the preStop sleep)
 - [ ] `CACHE_BACKEND` / `KV_BACKEND` + a cross-replica change bus when running >1 replica
+- [ ] `DB_MAX_CONNECTIONS` set so `pool × replicaCount` fits your database's limit — read the `db pool:` boot line before raising `replicaCount`
+- [ ] `POD_IP` injected via the downward API on EVERY multi-replica deployment, not only for durable workflows
+- [ ] `VOLTRO_BROADCAST_NAMESPACE` derived from the release namespace — staging and production do not separate themselves
 - [ ] For durable workflows on >1 replica: SQL store + `POD_IP` injected; tune `VOLTRO_WORKFLOW_FAILOVER_LEASE` if a 35s takeover is too slow; step side effects idempotent