@voltro/cli 0.33.0 → 0.35.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