@voltro/cli 0.33.0 → 0.34.0

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

@@ -41,6 +41,29 @@ Verify in the boot log:
 That's it. Reads now flow to the replica unless RYW pins them back.
 Writes always go to primary.
 
+## Replica pools take the primary's connection settings
+
+A replica is a **connection pool in the same process**, and it is configured by
+the same environment variables the primary reads — `DB_MAX_CONNECTIONS`,
+`PG_SSL`, `DB_SCHEMA`, `DB_STATEMENT_TIMEOUT_MS`, `DB_ACQUIRE_TIMEOUT_MS`. The
+replica URL decides only WHICH server it talks to.
+
+That matters for two reasons an operator has to plan for:
+
+- **Connection budget.** `DB_REPLICA_URLS` with two entries means this process
+  opens **three** pools of `DB_MAX_CONNECTIONS` each, not one. The boot line
+  says so:
+
+  ```
+  db pool: max=10 per replica (DB_MAX_CONNECTIONS) → max × 3 = 30 per pod × 4 replicas = up to 120 connections.
+    This process opens 3 pools of that size — 1 primary + 2 read replica(s) (DB_REPLICA_URLS), each with its own DB_MAX_CONNECTIONS.
+  ```
+
+- **TLS.** `PG_SSL=require` now applies to replica connections as well. A
+  `?sslmode=require` in the replica URL still works and still wins over the
+  driver default, but an explicit `PG_SSL` outranks it — so the TLS decision is
+  made once, for every connection the process opens.
+
 ## Read-your-writes (RYW)
 
 After a mutation commits, the subject who wrote is **pinned to
@@ -319,6 +342,43 @@ will NOT reach clients on other replicas. Add @voltro/plugin-broadcast (Redis /
 
 When BOTH a native path and the broadcast plugin are wired (e.g. postgres + broadcast), both stay active — the own-origin skip dedups, so there's no double-emit. The native path is the primary; the bus is harmless redundancy.
 
+## sqlite and the memory store behind replicas
+
+Neither dialect has a cross-instance path, and neither can get one: a local
+database file and an in-process store are, by construction, **this process's**.
+Putting several replicas in front of one is not a reactivity gap — the replicas
+do not share a database at all, so each one is also reading its own data.
+
+On a laptop that is the correct, normal configuration, which is why the framework
+said nothing about it for a long time. It now warns when it can see evidence of
+an **orchestrator**:
+
+```
+[voltro:serve] this app runs on 'sqlite' — a local database file — but POD_IP is set
+(Kubernetes), which means several replicas. Neither dialect has ANY cross-instance
+change capture: a client connected to replica A never sees a write made on replica B,
+for every table, and each replica is also reading its OWN data…
+```
+
+The evidence is one of `REPLICA_COUNT > 1`, `KUBERNETES_SERVICE_HOST`, `POD_IP`,
+`POD_NAME`, `FLY_ALLOC_ID`, `FLY_MACHINE_ID`, `ECS_CONTAINER_METADATA_URI[_V4]`,
+`K_REVISION`, `CONTAINER_APP_REPLICA_NAME` or `RENDER_INSTANCE_ID`. `HOSTNAME`,
+`NODE_ENV` and `PORT` are deliberately **not** evidence — every single-instance
+container sets those too, and a warning that fires on a laptop gets filtered out
+before it reaches the deployment where it is true.
+
+Two ways to silence it, and they are not equivalent:
+
+- `REPLICA_COUNT=1` — you are telling the framework there is exactly one process.
+  This is the honest one, and it is the only positive evidence *against* that
+  exists, so it outranks every platform signal.
+- Declaring `@voltro/plugin-broadcast` with a real provider — not because a bus
+  fixes it (the replicas still have separate databases), but because declaring
+  one means you have already thought about the question.
+
+The real fix is postgres or mysql/mariadb: a shared database with a native
+cross-instance change path.
+
 ## Where it lives in the codebase
 
 - `voltro/packages/plugin-broadcast` — the plugin, the `BroadcastProvider` contract, the redis / nats / memory providers, `attachBroadcastBus`.

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

@@ -373,6 +373,7 @@ import { TableValidationFailed } from '@voltro/runtime'
 
 export const createUser = defineMutation({
   name:   'users.create',
+  guards: [{ scope: 'users:write' }],
   input:  Schema.Struct({ email: Schema.String }),
   output: Schema.Struct({ id: Schema.String }),
   target: { table: 'users', op: 'insert' },

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

@@ -74,21 +74,68 @@ table. If you want one tenant's rows, say so in your own predicate.
 |---|---|---|
 | `boot` | On every `voltro dev` boot, **only if the fingerprint changed** | — |
 | `manual` | Only via `voltro db seed --id <name>` or the dashboard | — |
-| `onTenantCreate` | **Not wired yet** — declared and validated, never triggered | — |
-| `onSchemaChange` | **Not wired yet** — declared and validated, never triggered | `watchedTables` |
-| `cron` | **Not wired yet** — declared and validated, never triggered | `cron` |
-
-Only `boot` and `manual` actually execute today. The other three lifecycles
-validate at definition time (a `cron` seed without a `cron` field throws, an
-`onSchemaChange` seed without `watchedTables` throws) and are registered so the
-dashboard can list them — but nothing fires them. A seed declared with one of
-them will never run, silently.
-
-Until they are wired, express the same intent with a primitive that does run: a
-`*.cron.tsx` schedule whose handler does the seeding, or an explicit `voltro db
-seed --id <name>` from your migration/provisioning step. This table said
-otherwise until 0.10.0, which is exactly the kind of promise that costs someone
-a debugging afternoon — it is corrected here rather than quietly dropped.
+| `onTenantCreate` | Every time a tenant namespace is provisioned, **into that namespace** | a store with namespace isolation |
+| `onSchemaChange` | After a schema apply that touched a watched table (`voltro dev`'s boot auto-migrate, `voltro db apply`, `voltro migrate`) | `watchedTables` |
+| `cron` | On the cron expression, through the coordinated scheduler — one firing fleet-wide | `cron` |
+
+### `onTenantCreate`
+
+Fires from `provisionTenantNamespace`, after the namespace DDL lands and before
+provisioning resolves — so a caller that awaits it gets a tenant whose tables
+**and** reference data exist, or an error. Three properties worth knowing:
+
+- **Steps run scoped to the new namespace**, never the shared tables. A store
+  without namespace isolation (sqlite, a single-schema deployment) makes the run
+  **refuse** rather than fall back — the fallback would write one tenant's
+  fixture into every tenant's data. On a single-namespace deployment, declare
+  the seed `lifecycle: 'boot'` instead.
+- **No fingerprint skip.** A new namespace has none of the data, whatever
+  another tenant's run recorded. The ledger row is keyed `<seedId>@<namespace>`,
+  so N tenants produce N rows in `_voltro_seeds`.
+- **A failure fails provisioning.** Unlike a boot seed, which logs and lets the
+  server come up, a failed tenant-create seed rejects the provisioning call — a
+  tenant whose namespace exists and whose data does not, reported as success, is
+  worse than a loud error. Re-run provisioning (it is idempotent) or
+  `voltro db seed --id <name>` once the cause is fixed.
+
+### `onSchemaChange`
+
+Fires from the migration applier, so it covers every path that applies a schema:
+`voltro dev`'s boot auto-migrate, `voltro db apply` (bare and `--plan`) and
+`voltro migrate`. Every seed whose `watchedTables` intersect the tables the apply
+actually changed runs once, after the apply.
+
+Three properties worth knowing:
+
+- **Strictly post-apply.** It runs after the audit row is written, so on a
+  transactional dialect the DDL has already committed and the seed talks to its
+  own `DataStore` rather than the migration's connection.
+- **It cannot fail the migration.** The schema landed; a fixture that throws is
+  logged and recorded in `_voltro_seeds`. A successful apply is never reported as
+  failed because reference data did not load.
+- **`voltro serve` does not run it** — for the same reason it does not run boot
+  seeds. Serve never applies a schema, so there is no schema change for it to
+  react to; the pre-deploy `voltro db apply` is where it happens.
+
+> This seam was **declared and never called** until 0.34.0: the hook installed,
+> the seeds were discovered, listed and ledgered, and nothing ran. If you
+> declared an `onSchemaChange` seed before that release, expect it to fire on
+> your next apply.
+
+### `cron`
+
+`cron` seeds are projected into real schedules — the same coordinated scheduler
+`*.cron.tsx` uses, so one firing happens fleet-wide instead of one per replica.
+Both `voltro dev` and `voltro serve` register them at boot and log the schedule
+names they created.
+
+The schedule is named `seed:<id>`, which is also the name its runs appear under
+in `_voltro_schedule_runs` and in the dashboard — distinct from a `*.cron.tsx`
+namespace, so a schedule and a seed may share an id without colliding.
+
+A cron firing runs the seed **unconditionally**. The fingerprint skip that makes
+a `boot` seed cheap does not apply here: the trigger is the clock, not a change
+in the source.
 
 ```ts
 defineSeed({
@@ -96,11 +143,24 @@ defineSeed({
   name: 'Rebuild search index nightly',
   lifecycle: 'cron',
   cron: '0 3 * * *',              // required for lifecycle: 'cron'
+  timezone: 'Europe/Berlin',      // optional; defaults to an explicit 'UTC'
   steps: ({ step }) => [ /* … */ ],
 })
 ```
 
-`defineSeed` validates at definition time: `cron` lifecycle without a `cron` field throws, `onSchemaChange` without `watchedTables` throws, and a seed with zero steps throws.
+`timezone` is defaulted rather than required (unlike `defineSchedule`'s, where
+it is mandatory) — reference data rarely cares about a local wall clock. The
+default is an explicit `'UTC'`, never the container's clock.
+
+`defineSeed` validates at definition time: `cron` lifecycle without a `cron` field throws, `onSchemaChange` without `watchedTables` throws, and a seed with zero steps throws. The cron EXPRESSION is validated at boot, so a typo fails the boot naming the seed rather than never firing.
+
+> **An app with any `*.seed.ts` gets the two schedule ledger tables**
+> (`_voltro_schedule_runs`, `_voltro_schedule_claims`), even without a cron seed.
+> Whether a seed is a cron seed is a field INSIDE the file, and `voltro migrate`
+> never imports your modules — so the table set is decided from the FILENAME, and
+> it has to be decided identically by `voltro dev`, `voltro serve`, `voltro db
+> apply` and `voltro migrate` or the schema fingerprint diverges. Two empty ledger
+> tables is the price of that agreement.
 
 ## Steps
 
@@ -138,6 +198,7 @@ voltro db seed --store memory     # explicit opt-in: in-memory smoke run
 
 - **Reference data** (must exist in every environment): `lifecycle: 'boot'`, idempotent via `upsertByUnique`. Safe in production.
 - **Demo data** (populate a fresh dashboard): `lifecycle: 'boot'` in dev, or `lifecycle: 'manual'` so it's operator-triggered and never auto-runs in prod.
+- **Per-tenant starter data** (a new tenant's default categories, roles, settings): `lifecycle: 'onTenantCreate'`, which runs scoped to the tenant's own namespace as it is provisioned.
 
 See [migrations](/docs/database/migrations) for schema changes — seeds populate data, migrations shape the tables.
 
@@ -237,6 +298,49 @@ It applies to the **runtime query path only**. Migrations (`voltro db apply`) ru
 
 **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.
 
+### Acquire timeout — bound the wait for a free connection
+
+`DB_STATEMENT_TIMEOUT_MS` above bounds a query the **server** is running. Nothing bounded a query the client had not sent yet: a request arriving when every pooled connection is busy waited — with no error, no retry and no log line — until something else finished. Those are the two halves of "a request is stuck", and only one of them was covered.
+
+Every dialect that can bound an acquire now does, **by default**:
+
+| Dialect | Default | What is bounded |
+|---|---|---|
+| postgres | 10 s | the whole acquire — waiting in the pool's queue *and* connecting |
+| mysql / mariadb | 10 s connect · 100 queued waiters | connecting; the wait is bounded by queue **length**, see below |
+| mssql | 10 s | connecting (and the boot probe) |
+| sqlite / turso | — | one in-process connection, no pool to exhaust |
+
+An exhausted pool now fails with an error that **names the pool** — `Failed to acquire connection` — at the moment the pool is the cause, instead of surfacing as unexplained latency somewhere with no connection information in it.
+
+Move it with `DB_ACQUIRE_TIMEOUT_MS`, in milliseconds. `0` restores the driver's unbounded wait; a negative or non-numeric value falls back to the 10 s default rather than to no bound at all:
+
+```sh
+DB_ACQUIRE_TIMEOUT_MS=3000     # 0 = the driver's unbounded wait
+DB_ACQUIRE_QUEUE_LIMIT=2000    # mysql / mariadb only, OPT-IN — read the hazard below
+```
+
+Both are read on every command that opens a pool — `voltro dev`, `voltro serve`, `voltro migrate` and every `voltro db …` subcommand alike — so the variable means one thing across your deployment. (`DB_STATEMENT_TIMEOUT_MS` above is deliberately runtime-only: a migration runs legitimately long *statements*. An acquire bound fires when no connection is free at all, which a migration has no more reason to wait forever for than a request does.)
+
+That "every command" is literal, and it is worth stating because it has not always been true. Every pool the CLI opens gets its configuration from **one** resolver, so a knob cannot be honoured by one command and ignored by the next. The only two things the command changes are the two named here: `DB_STATEMENT_TIMEOUT_MS` (runtime only) and `DB_DIRECT_URL` / `DB_MIGRATE_URL` (migration only). Everything else — pool size, `DB_SCHEMA`, TLS (`PG_SSL`), the acquire bounds — resolves identically everywhere, including in the two places that open a bare postgres client rather than a pool (the web process's ISR cache and its CDC listener).
+
+The same value is `ConnectionConfig.acquireTimeoutMs` when you build a layer yourself:
+
+```typescript
+import { postgresDialect } from '@voltro/sql-postgres'
+
+const layer = postgresDialect.makeSqlLayer({
+  url: process.env.DB_URL!,
+  acquireTimeoutMs: 3_000,   // 0 = the driver's unbounded wait
+})
+```
+
+**mysql/mariadb cannot express a time bound on the waiting half, and the length bound that exists is opt-in.** `mysql2`'s pool queues the waiting caller with no timer at all, so there is nothing to set. The one bound the driver has is a LENGTH — `ConnectionConfig.acquireQueueLimit` / `DB_ACQUIRE_QUEUE_LIMIT`, mysql2's `queueLimit`. **The framework does not set it for you**, and the reason is worth understanding before you do:
+
+A time bound self-throttles. The acquire fails only once the wait has elapsed, so nothing can retry it faster than the timeout. A length bound is free: past the limit mysql2 rejects the acquire *synchronously*, so any caller that retries a failed acquire without a delay retries in the same tick — forever. The event loop is never reached again, which means no timer fires and the queue whose depth caused the rejection can never drain. The symptom is a process pinned at 100% CPU with no error, no log line, and an idle database.
+
+That caller is not hypothetical: the workflow cluster releases shards one statement per shard (300 by default) and retries a failed release immediately. So set `DB_ACQUIRE_QUEUE_LIMIT` only if you know nothing in your process retries an acquire without backoff, and set it well above the peak concurrency of anything that might. Unset — the default — you get mysql2's unbounded queue: callers wait rather than fail. mssql's pool exposes neither knob, so only establishment is bounded there — stated rather than papered over, for the same reason `DB_STATEMENT_TIMEOUT_MS` is left unwired on the dialects that cannot enforce it honestly.
+
 ## 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`:
@@ -378,6 +482,8 @@ The framework wraps `pg` (`node-postgres`) via Effect's typed connection layer.
 | `PG_MAX_CONNECTIONS`  | `10`    | pool ceiling. Tune up for high concurrency; CPU-bound workloads rarely benefit past ~2× cores. |
 | `PG_SSL`              | unset   | `'require'` (TLS without certificate verification — what production deployments behind RDS / Cloud SQL / Supabase want) / `'disable'` (force plaintext). Any other value — including libpq's `'prefer'`, which node-postgres cannot express (the driver has no TLS-then-plaintext fallback) — fails at boot instead of silently downgrading to plaintext. A `?sslmode=require\|disable` query on `DB_URL` works too; an explicit `PG_SSL` wins when both are set. |
 
+`PG_SSL` is read by **every** command that opens a connection — `voltro dev`, `voltro serve`, `voltro start`, `voltro migrate` and every `voltro db …` subcommand — so TLS is not something one command negotiates and the next one skips.
+
 ## CDC — LISTEN/NOTIFY
 
 Every table gets an AFTER trigger that emits a `framework_changes` notification on each insert / update / delete. The dispatcher LISTENs on that channel once per process and fans out to subscribers in-memory.
@@ -409,10 +515,63 @@ Trade-offs of the LISTEN/NOTIFY path:
 - ✅ Sub-frame latency (60fps UIs feel real-time).
 - ✅ Zero polling load even on idle tables.
 - ❌ Requires a long-lived connection per process. Connection-pooled deploys must use a sidecar listener or pgbouncer in session mode.
-- ❌ NOTIFY payloads are capped at 8KB. The trigger sends the full row images (`row_to_json(OLD)`/`row_to_json(NEW)`) so subscribers get the pre/post values directly; when a wide row would exceed the cap the trigger drops the body and sends an ID-only notification (the subscriber re-queries), so a very wide reactive row degrades gracefully rather than failing.
+- ❌ NOTIFY payloads are capped at 8000 bytes. The trigger sends the full row images (`row_to_json(OLD)`/`row_to_json(NEW)`) so subscribers get the pre/post values directly; a wide row that would exceed the cap falls back to a key-only notification. See the delivery guarantee below — the fallback is not free, and it is not the same for a subscription as it is for a tap.
 
 Set `CDC=0` to disable + force the inline-emit path (single-process only, no cross-process fan-out). Useful for tests + single-binary deploys.
 
+### Oversized rows — what is guaranteed
+
+A row whose JSON image exceeds ~8000 bytes (a document, a large `json()` column,
+an embedded array) cannot travel in a NOTIFY payload. The trigger keeps the
+change and the **primary key**, drops the images, and the CDC consumer re-reads
+the row from the database before the event reaches anything. What each consumer
+gets:
+
+| Change | What is delivered | `event.oversized` |
+|---|---|---|
+| insert / update | the row **re-read from the database** | `'rehydrated'` |
+| delete | the **primary key only** — a tombstone | `'tombstone'` |
+| key missing, re-read failed, or the row is already gone | both images null | `'unrecovered'` |
+
+Read the marker before you treat an image as a snapshot. Three limits are real
+and cannot be engineered away:
+
+- **A re-read returns the row as it is NOW.** If a second write lands between
+  the change and the re-read, this event carries the newer state — and the
+  second change delivers it again. The stream is convergent, not
+  point-in-time. Postgres keeps no copy of an image the transport dropped.
+- **`old` is null on an oversized update, and pk-only on an oversized delete.**
+  There is nowhere to read a pre-image from. A tombstone is enough to REMOVE the
+  row from a search index, an analytics mirror or a CDC stream; it is not a
+  record of what the row contained, and `@voltro/plugin-versioning` writes
+  `data: null` for one rather than a fabricated empty snapshot.
+- **`'unrecovered'` means the content is gone.** No retry can bring it back —
+  it was never delivered. Subscriptions are unaffected (they re-query); taps
+  miss that row until the next write to it or a re-seed.
+
+Every fallback is counted as `voltro_cdc_oversized_total{outcome=…}` (scrapeable
+via `@voltro/plugin-prometheus` at `/metrics`, or `GET
+/_voltro/inspect/metrics`), the first one per table is logged at `warn`, and
+every `unrecovered` one is logged at `error`. **Alert on
+`outcome="unrecovered"`** — a non-zero rate means the deployment is losing
+changes for its taps.
+
+Tunables (options on the postgres store, or environment):
+
+| Env | Default | Meaning |
+|---|---|---|
+| `VOLTRO_CDC_REHYDRATE_TIMEOUT_MS` | `5000` | total budget for recovering one oversized change. The LISTEN consumer is serial, so this also bounds how long one oversized row can hold up the change stream. |
+| `VOLTRO_CDC_REHYDRATE_RETRIES`    | `2`    | re-reads after the first attempt, inside that budget. |
+
+The re-read is issued against the schema the write landed in, so it is correct
+under namespace (schema-per-tenant) isolation.
+
+**This lives in the database, so it has to be applied.** The trigger function is
+DDL: a database created before this shipped still carries the old body, which
+drops the key and makes every oversized change `'unrecovered'`. `voltro db
+apply` replaces it (`voltro dev` reports it at boot as trigger drift, and the
+`error` log line names the same remedy).
+
 ## Workflow cluster
 
 `@effect/cluster`'s `SqlRunnerStorage` uses `pg_advisory_lock(key)` to claim shard ownership. The framework wires this transparently — set `DB_DIALECT=postgres` + provide a SqlClient layer and `workflowEngineLayer({ runnerStorage: 'sql' })` does the rest.
@@ -504,9 +663,25 @@ DB_HOST=…  DB_PORT=…  DB_USER=…  DB_PASSWORD=…  DB_DATABASE=…
 # at migration time.
 ```
 
+## TLS — honoured, or refused
+
+Ask for TLS in the connection URL:
+
+```sh
+DB_URL=mysql://app:app@db.internal:3306/app?sslmode=require   # TLS, certificate not verified
+DB_URL=mysql://app:app@db.internal:3306/app?ssl=true          # the provider-style alias — same thing
+DB_URL=mysql://app:app@db.internal:3306/app?sslmode=disable   # explicit plaintext
+```
+
+`require` maps to mysql2's `{ rejectUnauthorized: false }` — the connection is **encrypted, the server certificate is not authenticated**. That is the mode managed providers expect, and it is the same meaning `?sslmode=require` has on the postgres dialect.
+
+**Anything else fails at boot**, on purpose: `prefer`, `allow`, `verify-ca`, `verify-full`, a CA-profile name, `?ssl=yes`. mysql2 either sends an SSLRequest or it does not, so `prefer` is not expressible; and a verification mode cannot round-trip through the cross-dialect boolean `ssl` field, so honouring the word would mean quietly giving you something weaker than it names. A boot failure is the correct answer to a TLS request that cannot be satisfied.
+
+> **This changed.** Before this release the mysql/mariadb dialect had **no TLS path at all** — `?ssl=true` was parsed off the URL and discarded, and the connection went out in plaintext with no warning. If your URL carries `?ssl=` or `?sslmode=`, that request is now real: verify your server accepts TLS before deploying.
+
 ## Driver: `@effect/sql-mysql2`
 
-Wraps the `mysql2` driver (Node.js mysql client). The framework's `MysqlStore` opens a connection pool sized via `DB_MAX_CONNECTIONS` (default 10).
+Wraps the `mysql2` driver (Node.js mysql client). The framework's `MysqlStore` opens a connection pool sized via `DB_MAX_CONNECTIONS` (default 10), with a 10 s bound on **establishing** a connection. Waiting for a busy one is **not** bounded: mysql2 has no timer for that phase, and the length ceiling it does offer (`ConnectionConfig.acquireQueueLimit`) is opt-in because mysql2 rejects past the limit synchronously — which turns any zero-delay acquire retry into an event-loop-starving spin. See the [acquire-timeout table](../dialects) for the full reasoning before you set it.
 
 The driver returns BOOLEAN as `0|1` (TINYINT(1) is MySQL's underlying type). The framework's `decodeRowsFromSchema` post-processor converts back to `true|false` for any column the schema registry declares as `boolean()`. Without this, every reactive subscription opening on a BOOLEAN column would see `1` instead of `true` and fail framework Schema validators.
 
@@ -709,6 +884,8 @@ makeMysqlStore({ sqlLayer, variant: 'mariadb', changeStrategy: 'cdc', cdcConfig
 
 The variant flows through to per-operation getters (`supportsInsertReturning`, `supportsDeleteReturning`, `supportsUpdateReturning`) and to the JSON-agg compiler's dialect branch.
 
+TLS and the pool bounds are shared with MySQL, driver-for-driver: `?sslmode=require` / `?ssl=true` encrypts (certificate not verified), an unsupported mode fails at boot rather than falling back to plaintext, and the acquire wait is bounded by queue length because mysql2 has no time-based bound for it. See [MySQL → TLS](./mysql) and the [acquire-timeout table](../dialects).
+
 ## `UPDATE … RETURNING` does NOT exist — anywhere
 
 Despite MariaDB's broad RETURNING support — `INSERT … RETURNING *` since 10.5, `DELETE … RETURNING *` since 10.0 — there is **no UPDATE … RETURNING in any MariaDB version**. The framework's first attempt at supportsReturning treated the whole RETURNING family as one flag and emitted `UPDATE … RETURNING *` on mariadb, which fails with a parse error.
@@ -914,9 +1091,21 @@ DB_URL=mssql://sa:<password>@localhost:11433/voltro_test
 
 The framework's docker-compose at `voltro/test/docker-compose.yml` brings up MSSQL on `:11433` with an `mssql-init` sidecar that runs `CREATE DATABASE voltro_test` once the server is healthy. mssql doesn't have a `docker-entrypoint-initdb.d` equivalent, so the framework synthesizes one.
 
+## TLS — honoured, or refused
+
+```sh
+DB_URL=mssql://sa:<password>@sql.internal:1433/app?sslmode=require   # encrypt, don't verify the certificate
+DB_URL=mssql://sa:<password>@sql.internal:1433/app?encrypt=1         # tedious' own spelling — same thing
+DB_URL=mssql://sa:<password>@sql.internal:1433/app?sslmode=disable   # explicit plaintext
+```
+
+`require` maps to tedious `encrypt: true` + `trustServerCertificate: true` — encrypted, server certificate not authenticated, which is what lets a Developer-edition instance's self-signed certificate work. Unsupported modes (`prefer`, `verify-ca`, `verify-full`, `?encrypt=yes`) **fail at boot** rather than connecting with something weaker than they name.
+
+> **This changed.** `@effect/sql-mssql` defaults `encrypt` to **false** (it overrides tedious' own `true`), and the framework never read the `ssl` config or the URL query — so every mssql session was plaintext, while a hard-coded `trustServerCertificate: true` made the configuration look TLS-aware. Unset still means plaintext (unchanged); a TLS request in the URL is now real.
+
 ## Driver: `@effect/sql-mssql`
 
-Wraps `tedious` (the Node.js TDS driver). The framework's `MssqlStore` opens a connection pool sized via `DB_MAX_CONNECTIONS` (default 10).
+Wraps `tedious` (the Node.js TDS driver). The framework's `MssqlStore` opens a connection pool sized via `DB_MAX_CONNECTIONS` (default 10), with a 10 s bound on establishing a connection (`ConnectionConfig.acquireTimeoutMs`). Waiting for a BUSY pooled connection is not bounded here — the client's pool exposes no such knob; see the [acquire-timeout table](../dialects) for what each dialect can enforce.
 
 Tedious returns BIT as proper boolean (✓) and NVARCHAR as string. JSON columns are NVARCHAR(MAX) under the hood — driver returns the raw string. The framework's `decodeRowsFromSchema` JSON.parses any column declared as `json()` in the schema registry; without this, every reactive subscription reading a JSON column would see strings and fail framework Schema validators.
 

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

@@ -47,6 +47,43 @@ await ctx.store.transactional(async (tx) => {
 
 `transactional()` **must not be nested** — a nested invocation throws to surface a design mistake. Use a single top-level `transactional()` per unit of work.
 
+## Typed errors survive a transaction
+
+A `Data.TaggedError` thrown inside a transaction reaches the caller — and the browser client — **as itself**: `_tag`, payload and prototype intact, so a mutation's declared `error:` union still matches.
+
+```ts
+import { Data } from 'effect'
+
+class NoteNotFound extends Data.TaggedError('NoteNotFound')<{ noteId: string }> {}
+
+// apps/api/mutations/notes.rename.mutation.ts — auto-transactional
+export default async (input, ctx) => {
+  const note = await ctx.store.query({ table: 'notes', /* … */ })
+  if (!note) throw new NoteNotFound({ noteId: input.id })   // arrives typed on the client
+  // …
+}
+```
+
+On the client:
+
+```ts
+const res = await client.notes.rename({ id, title })
+if (res.error?._tag === 'NoteNotFound') { /* this branch fires */ }
+```
+
+This holds on **every** dialect and on **both** tenancy topologies — shared-schema and namespace isolation — because all four dialect stores and both postgres entry points run through one shared transaction bracket. Never match on `error.message` to identify a transaction failure; the `_tag` is the contract.
+
+## Automatic retry on transient conflicts
+
+A transaction that fails with a transient contention error is retried automatically: exponential backoff from 10 ms, up to 3 retries (4 attempts total). What counts as transient is per-dialect — postgres `serialization_failure` (40001) and `deadlock_detected` (40P01), mysql/mariadb deadlock and lock-wait timeout, mssql deadlock victim (1205), sqlite `SQLITE_BUSY`/`SQLITE_LOCKED`, and Turso's MVCC write-write conflict.
+
+Two properties worth knowing:
+
+- **A conflict raised by the COMMIT itself is retried too.** Under `SERIALIZABLE`, the engine can only detect some conflicts at commit time — those are caught and replayed like any other.
+- **Each attempt gets a fresh transaction and a fresh event buffer.** A retried attempt's queued ChangeEvents are discarded with it, so subscribers see exactly one event set: the winning attempt's.
+
+Because the body can run more than once, keep `transactional()` bodies **idempotent** — no counters incremented in JS, no external calls (see the anti-patterns below).
+
 ## Optimistic concurrency
 
 The fluent update builder carries an `.expectVersion(n)` guard: the update only matches rows whose `version` equals `n`, and throws `OptimisticLockError` when none match (the row was concurrently changed). Add a `version` column to the table to use it.
@@ -134,6 +171,37 @@ array is a no-op that returns `[]`.
 see each new row's delta — identical to N single inserts. Inside a
 `transactional()` the per-row events queue until commit and drop on a throw.
 
+### Large arrays are chunked for you — and stay all-or-nothing
+
+Every engine caps what ONE statement may carry, and the caps are far apart:
+
+| Dialect | Bind parameters per statement | Rows per `VALUES` |
+| --- | --- | --- |
+| postgres | 65 535 | — |
+| mysql / mariadb | 65 535 | — |
+| **mssql** | **2 098** | **1 000** |
+| sqlite / turso | 32 766 | — |
+
+`INSERT … VALUES` binds one parameter per **column per row**, so the row limit
+is `floor(cap / columns)` — a 12-column table caps at 5 461 rows on postgres and
+at **174** on mssql. Past that the driver refuses with its own error about a
+limit you never chose.
+
+`insertMany` splits the array for you at that boundary. Two properties are
+guaranteed:
+
+- **A fitting array is still ONE statement.** Nothing changes for the normal
+  case — no extra round-trips, no behaviour difference.
+- **A chunked insert is still all-or-nothing.** When the call is not already
+  inside a `transactional()`, the chunks run in one transaction the framework
+  opens, so a failure in the last chunk rolls back the earlier ones. Without
+  that, chunking would quietly add partial-success-on-failure to a call that
+  never had it.
+
+There is nothing to configure. If a SINGLE row is wider than the cap (a
+3 000-column table on mssql) the engine's own error is what you get — a row
+cannot be split.
+
 ## `upsert` — insert or update on conflict
 
 The 90% case: "make this row exist with these values; if it already

package/templates/agent-docs/deployment.md

@@ -300,9 +300,9 @@ cause.
 | `VOLTRO_STORAGE_SECRET` | optional (`@voltro/plugin-storage`) | Signs private-file grant tokens; falls back to the session secret if unset |
 | `AI_PROVIDER` | when using `@voltro/ai` | `anthropic` / `openai` / `mock` |
 | `AI_API_KEY` | with `AI_PROVIDER` | Provider's API key |
-| `SSR_CACHE` | optional | `memory` (default) or `postgres` (needs `PG_*` set too) for the ISR cache |
+| `SSR_CACHE` | optional | `memory` (default) or `postgres` for the ISR cache. `postgres` needs a database in the WEB process's env (`DB_URL` / `DB_HOST` / `PG_HOST`) — without one it aborts the boot in production rather than falling back to memory |
 | `VOLTRO_API_ORIGIN` / `VOLTRO_API_ORIGIN_<NAME>` | split web/api deploy with SSR pages | The api's internal origin the WEB pod uses for SSR `ctx.query` (`http://api.<ns>.svc.cluster.local`). Per-api `_<NAME>` (name upper-cased) wins over the shared one and over `serverUrl`. Never sent to the browser |
-| `PORT` | optional | App's listen port (overrides `app.config.ts.port`) |
+| `PORT` | optional | App's listen port. Outranks `--port` and `app.config.ts` `port:` — a platform that assigns a port sets this one, so it has to win. Unset, the app binds its declared `port:`, then 4000 (api) / 5173 (web). |
 | `VOLTRO_INSPECT` | optional | `off` to disable `_voltro/inspect/*` in prod |
 | `VOLTRO_INSPECT_TOKEN` | recommended | Bearer token guard on inspect endpoints |
 | `VOLTRO_DASHBOARD_APPS` | dashboard only | JSON `[{name?,url,token?}]` — target apps + inspect tokens the deployed DevTools dashboard shows (served at runtime from `/api/dashboard/config`) |
@@ -833,6 +833,8 @@ VOLTRO_SESSION_SECRET_PREVIOUS=<old>   # still verifies live cookies
 
 Keep `_PREVIOUS` in place for one session-TTL window, then drop it. Existing cookies verify against `previous` until they naturally expire — no live session is invalidated.
 
+> **If you embed the framework's middleware yourself** rather than booting through `voltro serve`, there is no boot gate to catch a missing secret. In that case a presented `voltro:session` cookie that cannot be verified now logs, once per process and at error level, that no credential-expiry bound is being imposed — so realtime subscriptions on that connection will not be cut off when the session expires. It is a diagnostic, not a refusal: a stale `voltro:session` cookie from another app on the same host is a normal thing for a browser to carry, and failing the request would turn that into a denial of service.
+
 ## 2. Kubernetes health probes
 
 `voltro serve` exposes two unauthenticated endpoints, both handled **before** any rate-limit interceptor:
@@ -1002,12 +1004,21 @@ indexed query instead of scanning every table). Force a full re-introspect with
 
 ## 4. Request limits & DoS
 
-`POST /rpc` (the buffered JSON endpoint the SSR loaders use) rejects an over-`Content-Length` body with **413** *before* buffering it into memory:
+`POST /rpc` (the buffered JSON endpoint the SSR loaders use) is capped, and the cap is enforced **as bytes arrive**:
 
 ```sh
 VOLTRO_MAX_RPC_BODY_BYTES=8388608   # default 8 MiB
 ```
 
+A declared `Content-Length` over the cap is refused up front, so an honest client
+gets its **413** without uploading anything — a courtesy, not the enforcement,
+since a `Transfer-Encoding: chunked` body declares no length at all. The byte
+counter is the enforcement: it stops accumulating the moment the running total
+crosses the limit, drains the rest of the upload rather than dropping the
+connection, and answers **413**. Both shapes therefore end in the same status
+code, and the refusal is logged under the `voltro:security` scope with the cap
+and the byte count at which the server stopped reading.
+
 Scope: this guards the `/rpc` JSON path only. File uploads ride separate storage routes with their own `limits.maxBytes`, and WebSocket frames are capped by the `ws` library default (100 MiB).
 
 **Put per-IP rate limiting and the primary body-size cap at the ingress** — that is the correct layer: it holds per-IP state and works across replicas, which an in-process limit can't.
@@ -1020,6 +1031,51 @@ nginx.ingress.kubernetes.io/limit-rps: "20"
 
 For **app-level** throttling (per-subject / per-tenant, e.g. an expensive action), use `@voltro/plugin-ratelimit` and the plugin `onHttpRequest` interceptor seam. It complements the ingress cap — it does not replace it.
 
+**There is no rate limit in the box.** The body cap above is the only request guard the runtime applies by default; `@voltro/plugin-ratelimit` is opt-in, so an app that has not installed and configured it has no per-IP, per-API-key or per-tenant cap on `/rpc` at all. The one on-by-default throttle anywhere in the framework is `plugin-auth`'s [brute-force lockout](/docs/authentication/passwords#brute-force-lockout), which covers sign-in credential attempts and nothing else. Treat the ingress limit as required, not as belt-and-braces.
+
+### Per-IP limits need a trusted proxy
+
+The address the runtime rate-limits, geo-blocks and audits by is
+`socket.remoteAddress` — **not** `x-forwarded-for`, which any client can write.
+Behind an ingress that means every request counts against the proxy's address —
+and every `sessions.ipAddress` row records the proxy — until you declare the hop:
+
+```ts
+// app.config.ts
+export default {
+  security: {
+    trustedProxies: ['private'],   // or: ['loopback'] · ['10.0.0.0/8'] · ['2'] · ['*']
+  },
+}
+```
+
+The same setting decides whether `x-forwarded-proto` is believed, which is what
+lets the runtime emit HSTS behind a TLS-terminating load balancer. Override it
+on a running deployment with `VOLTRO_TRUSTED_PROXIES=private` (comma-separated).
+
+### Cross-site protection and its allowlist
+
+Every state-changing request — `POST /rpc`, the `/ws` upgrade, every REST route
+projected from a `publicApi:` mutation, everything in `apiConfig.restRoutes`,
+and `POST /v1/api-keys` — refuses a browser request whose `Origin` is neither
+the `Host` it was sent to nor an allowlisted origin. **A split web/api
+deployment must declare its web origin** or the browser gets a 403 on every
+mutation, REST write and socket:
+
+```ts
+// app.config.ts
+export default {
+  security: {
+    allowedOrigins: ['https://app.example.com'],
+  },
+}
+```
+
+The environment override is `VOLTRO_ALLOWED_ORIGINS` (comma-separated).
+Server-to-server callers (SSR loaders, mobile SDKs, other services) send no
+`Origin` and are unaffected. Full detail in
+[Security](/docs/security/overview#cross-site-requests-are-refused).
+
 ## 5. Multi-tenant isolation
 
 Tables carrying the `tenant()` mixin are auto-scoped to the request's tenant — nothing more to do there. The gap is the **anonymous** request that matches no auth strategy: by default it resolves to a tenant-less anonymous Subject that can read any non-`tenant()` table across the DB.
@@ -1079,6 +1135,12 @@ sink, stops accepting new connections while **finishing already-accepted
 requests**, and closes the SQL connection pool **last** (waiting for in-flight
 transactions). Verified under concurrent load — accepted requests complete.
 
+The **transactional-outbox worker** is part of that sequence: its poll timer and
+its change subscription are released, and a delivery already in flight is
+awaited, before the pool closes. An outbox row that was still pending is not
+lost — it is durable, and the next process's first pass picks it up, which is
+one of the three reasons that poll exists.
+
 **But the app cannot drain a rolling update by itself.** The runtime
 (`NodeRuntime`) owns the `SIGTERM` signal and closes the HTTP listener promptly —
 so a request that *arrives* during shutdown is refused. Failing readiness from
@@ -1315,6 +1377,10 @@ Lower the lease for **faster failover**, at the cost of **false-positive reclaim
 - [ ] Serving pods run `voltro serve` (not `voltro dev`), with `VOLTRO_AUTO_MIGRATE=0`
 - [ ] Schema applied by a pre-deploy Job / initContainer (`voltro db apply`), not in the serving pod
 - [ ] `VOLTRO_MAX_RPC_BODY_BYTES` sane; ingress caps body size + per-IP rate
+- [ ] `VOLTRO_TRUSTED_PROXIES` set if you run behind an ingress AND rate-limit per IP
+- [ ] `VOLTRO_ALLOWED_ORIGINS` set if the web app is on a different origin than the api
+- [ ] Security headers reviewed (`VOLTRO_SECURITY_HEADERS`, `VOLTRO_CSP`); HSTS reaching the browser over https
+- [ ] Every `*.webhook.tsx` declares its verification, and each signature-verified one has its `VOLTRO_WEBHOOK_SECRET_<ID>`
 - [ ] `auth.anonymousTenantRequired: true` (unless the app serves anonymous public data)
 - [ ] `OTEL_EXPORTER_OTLP_ENDPOINT` + `OTEL_SERVICE_NAME` pointed at your collector
 - [ ] `VOLTRO_LOG_FORMAT=json`; `sentryPlugin()` + `SENTRY_DSN` for errors