@voltro/cli 0.23.0 → 0.25.0

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

@@ -4,69 +4,6 @@
 
 
 
----
-
-<!-- source: en/database/migrations/adopt.md -->
-## Adopting a table into a plugin's
-
-_voltro db adopt — move an app's grown table into a plugin-owned one, with a snapshot, a count verify and the drop last._
-
-An app that did not start on a green field already has a table for half the plugins it installs. `voltro db adopt` is the way **into** the plugin's table, so using the plugin does not mean running a second source of truth beside it.
-
-```bash
-voltro db adopt --from ai_flows --into _voltro_ai_flows --map ./ai-flows.map.ts
-voltro db adopt --from ai_flows --into _voltro_ai_flows --map ./ai-flows.map.ts --apply
-```
-
-**Dry run unless you pass `--apply`.** The interesting failure here is irreversible and the interesting output is the refusal, so nothing is written until you say so. A refused plan prints no steps at all, rather than a preview of something that will not happen.
-
-## The map file is yours
-
-```ts
-// ai-flows.map.ts
-export default {
-  map: {
-    name:         'name',
-    mode:         { expr: `CASE WHEN "allowDeviation" THEN 'agentic' ELSE 'deterministic' END` },
-    costMicroUsd: { expr: '"totalCostCents" * 10000' },
-  },
-  leaveUnset: ['id'],
-}
-```
-
-Read `target: source` — fill the plugin's column FROM this expression of mine, which is the direction the SQL runs. A string is a source column; `{ expr }` is raw SQL against the source row, for the unit conversions and merged fields no tool can infer. Those are domain knowledge, and a tool inventing them silently corrupts data.
-
-`leaveUnset` is how "the target's own default fills this" stops looking like "I forgot it".
-
-## What it refuses
-
-- **a NOT NULL target column nobody maps to** — the alternative is a silent zero that reads as real data forever after;
-- **a target table that already holds rows** — adopt MOVES rows into a table, it does not merge into one somebody else already wrote;
-- **a typo on either side of the map.**
-
-A source column nobody carries across is reported but not fatal: dropping a dead column is deliberate often enough, and "I forgot this" and "I decided" look identical in a map file.
-
-## The order, and why the drop is last
-
-1. **snapshot** — `<table>__adopt_snapshot`, a real table in the same database, so restoring is a statement rather than an operational procedure at 2am. It keeps the columns the adopt left behind.
-2. **copy**
-3. **verify by count** — this catches the one failure that is otherwise invisible: a `WHERE` inside a raw expression silently dropping rows.
-4. **drop the source** — last, and only if the counts match.
-
-On a mismatch **both tables stay** and the command says so. The snapshot is never removed after a failed verify — it exists for exactly the run that goes wrong. `--keep-source` copies and verifies without dropping at all.
-
-## Ids, if the typeid prefixes differ
-
-The dry run says so before anything runs, because discovering it after the copy is discovering it too late: every row gets a new id, so every reference to the old table has to be rewritten — **including ids embedded in JSON columns**.
-
-Rewriting them is **not** automatic. Those ids live in your columns and inside your JSON, and only you know where. The translation table is what the command owes you; the rewrite is what you owe yourself. Doing it automatically is the one place here where being wrong would be silent.
-
-## After the move
-
-Your rows are now in a table whose shape the framework evolves — and nothing special happens to them. They migrate exactly like every other row, through the same declarative differ. A narrowing can fail on your data, loudly, the same way it would on anybody's.
-
-
-
 ---
 
 <!-- source: en/database/migrations/index.md -->
@@ -1619,6 +1556,46 @@ no-ops out.
 
 The cloud dashboard surfaces per-env state with a multi-env tab in the [cloud UI](./cloud-ui.md).
 
+## Rehearsing a migration against real data
+
+The strongest check on this pipeline is not that each command exits 0 — it is that **no row moved that you did not ask to move**. A consumer running a MariaDB cutover built this loop and it caught three defects the framework's own suite did not; the method is theirs, written up here because the next person should not have to invent it.
+
+1. **Restore a backup into a throwaway database.**
+
+   ```sh
+   voltro data backup ./rehearsal .
+   DB_URL=$SCRATCH_URL voltro data restore ./rehearsal
+   ```
+
+   Use `data backup` / `data restore` — the NATIVE path — not the logical `data export`. The logical exporter re-shapes rows through the **current** declared schema, and the state a rehearsal exists to migrate *from* is precisely the one that does not match it.
+
+2. **Take an exact census, before.**
+
+   ```sql
+   SELECT table_name, COUNT(*) FROM ... -- one COUNT(*) per table
+   ```
+
+   It must be `COUNT(*)`. `information_schema.TABLE_ROWS` is an **estimate** on InnoDB — routinely off by thousands, and it is what a fast version of this check would reach for. The slowness is the point.
+
+3. **Run the exact production command sequence** — the same one your deploy Job runs, in the same order:
+
+   ```sh
+   voltro db files .
+   voltro db plan --json > plan.json
+   voltro db apply --plan plan.json
+   ```
+
+4. **Take the census again, and require the difference to be explainable.**
+
+   A healthy run moves one row: the `_voltro_migration_plans` ledger entry. Anything else is a question, not a result.
+
+**Two things the census must get right**, both learned by using it:
+
+- **A soft drop is not a loss.** With `VOLTRO_SOFT_DROP=1` a dropped table reappears as `<name>__dropped_<YYYYMMDDHHMMSS>` with its rows intact. Reporting that as a vanished table trains people to ignore the check; reporting it as clean hides a real drop. Give it its own category.
+- **A new table is not a discrepancy.** A migration that adds one produces a table with no "before" count. Say so explicitly rather than letting a zero read as data loss.
+
+To rehearse a schema several months old — the realistic case — craft the backup deliberately: a table a later migration added, a column a later one narrowed, a column the schema no longer declares. The planner is state-based, so it diffs live against declared and never replays a history; a six-month-old dump costs exactly one diff.
+
 ## File-based migrations in this pipeline
 
 `voltro db apply` runs pending `migrations/*.ts` **first**, then diffs — the same order the boot path uses.
@@ -3295,6 +3272,35 @@ Fix:
   resolves the root from the first non-flag argument, defaulting to
   the current working directory
 
+## "N reactive table(s) have NO change trigger in the database" (postgres)
+
+```text
+auto-migrate: 500 reactive table(s) have NO change trigger in the database —
+ab_test_results, ab_test_variants, ab_tests, … (+492). Writes to them will not
+reach another instance's subscribers; a single instance is unaffected, which is
+why this stays invisible until you scale out. Run `voltro db apply` to install them.
+```
+
+On postgres, reactivity is carried by DDL: a per-table `framework_changes_<table>` trigger that `NOTIFY`s the CDC channel. The declared schema and the database can disagree about which tables have one.
+
+**Run `voltro db apply`.** It converges the triggers as its own step, and it does so **even when the schema diff is empty** — the usual case here, because a missing trigger is not a shape difference and `db plan` will correctly report `0 operations`:
+
+```text
+$ voltro db apply
+schema diff: 0 operations, 0 blocked
+  (schema is up to date)
+db apply: installing change triggers on 500 table(s)
+db apply: change triggers converged (1501 statement(s))
+```
+
+`db apply --plan` converges them too, so the pre-deploy Job pattern needs no extra step.
+
+**Why a table ends up without one.** The trigger DDL is emitted by the full-schema path — a fresh database — so any table that arrived while your app was already running, or during a release that installed none, has no trigger. A restored dump can do it too (triggers travel with a full dump, but not with a schema-only or `--no-triggers` one), as can a hand-run `DROP TRIGGER` during an incident.
+
+**Why it stays invisible.** A single instance's own writes reach its own subscribers through the in-process path. The trigger is what carries a write to the *other* instances, so the symptom only appears when you scale out — subscriptions that quietly stop updating, with nothing in the logs.
+
+The mirror case is reported the same way: a `.nonReactive()` table that still carries a trigger keeps paying `REPLICA IDENTITY FULL` and a `NOTIFY` on every write for a subscription nobody receives. `db apply` removes both.
+
 ## When the fix hint doesn't match reality
 
 The fix hints come from the planner's classification logic — they should always be actionable. If you see one that doesn't make sense given your code:
@@ -3313,3 +3319,66 @@ Hint mismatches are bugs in the planner's classification — they're rare but al
 - [Drift](./drift.md) — when the live DB diverged
 - [Multi-dialect strategy](./multi-dialect.md) — why MySQL + forward-roll
 - [Prod pipeline](./prod-pipeline.md) — the deploy-step apply pattern
+
+
+
+---
+
+<!-- source: en/database/migrations/adopt.md -->
+## Adopting a table into a plugin's
+
+_voltro db adopt — move an app's grown table into a plugin-owned one, with a snapshot, a count verify and the drop last._
+
+An app that did not start on a green field already has a table for half the plugins it installs. `voltro db adopt` is the way **into** the plugin's table, so using the plugin does not mean running a second source of truth beside it.
+
+```bash
+voltro db adopt --from ai_flows --into _voltro_ai_flows --map ./ai-flows.map.ts
+voltro db adopt --from ai_flows --into _voltro_ai_flows --map ./ai-flows.map.ts --apply
+```
+
+**Dry run unless you pass `--apply`.** The interesting failure here is irreversible and the interesting output is the refusal, so nothing is written until you say so. A refused plan prints no steps at all, rather than a preview of something that will not happen.
+
+## The map file is yours
+
+```ts
+// ai-flows.map.ts
+export default {
+  map: {
+    name:         'name',
+    mode:         { expr: `CASE WHEN "allowDeviation" THEN 'agentic' ELSE 'deterministic' END` },
+    costMicroUsd: { expr: '"totalCostCents" * 10000' },
+  },
+  leaveUnset: ['id'],
+}
+```
+
+Read `target: source` — fill the plugin's column FROM this expression of mine, which is the direction the SQL runs. A string is a source column; `{ expr }` is raw SQL against the source row, for the unit conversions and merged fields no tool can infer. Those are domain knowledge, and a tool inventing them silently corrupts data.
+
+`leaveUnset` is how "the target's own default fills this" stops looking like "I forgot it".
+
+## What it refuses
+
+- **a NOT NULL target column nobody maps to** — the alternative is a silent zero that reads as real data forever after;
+- **a target table that already holds rows** — adopt MOVES rows into a table, it does not merge into one somebody else already wrote;
+- **a typo on either side of the map.**
+
+A source column nobody carries across is reported but not fatal: dropping a dead column is deliberate often enough, and "I forgot this" and "I decided" look identical in a map file.
+
+## The order, and why the drop is last
+
+1. **snapshot** — `<table>__adopt_snapshot`, a real table in the same database, so restoring is a statement rather than an operational procedure at 2am. It keeps the columns the adopt left behind.
+2. **copy**
+3. **verify by count** — this catches the one failure that is otherwise invisible: a `WHERE` inside a raw expression silently dropping rows.
+4. **drop the source** — last, and only if the counts match.
+
+On a mismatch **both tables stay** and the command says so. The snapshot is never removed after a failed verify — it exists for exactly the run that goes wrong. `--keep-source` copies and verifies without dropping at all.
+
+## Ids, if the typeid prefixes differ
+
+The dry run says so before anything runs, because discovering it after the copy is discovering it too late: every row gets a new id, so every reference to the old table has to be rewritten — **including ids embedded in JSON columns**.
+
+Rewriting them is **not** automatic. Those ids live in your columns and inside your JSON, and only you know where. The translation table is what the command owes you; the rewrite is what you owe yourself. Doing it automatically is the one place here where being wrong would be silent.
+
+## After the move
+
+Your rows are now in a table whose shape the framework evolves — and nothing special happens to them. They migrate exactly like every other row, through the same declarative differ. A narrowing can fail on your data, loudly, the same way it would on anybody's.

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

@@ -629,6 +629,86 @@ A mixin can also declare `requires: [otherMixin()]` (resolved depth-first) and `
 
 
 
+---
+
+<!-- source: en/database/concurrency-and-expiry.md -->
+## Concurrency + expiry
+
+_.version() for optimistic locking and expires() for time-limited rows — what each guarantees, on which dialect._
+
+Two column-level tools for questions a schema cannot otherwise answer: **which write is newest**, and **when does this row stop counting**.
+
+## `.version()` — optimistic locking
+
+Two clients read the same row and both write it. Without a version the second silently wins, and the first user's change is gone with no trace. That is the shape of every *"my edit disappeared"* report.
+
+```ts
+export const documents = table('documents', {
+  id:      id(),
+  title:   text(),
+  version: integer().version(),
+})
+```
+
+From then on the store **increments** `version` on every update, and an update that carries an expectation fails when the row has moved on:
+
+```ts
+// The client sends the version it read.
+yield* ctx.store.update('documents', input.id, { title: input.title, version: input.version })
+// → VersionConflict { expected: 3, actual: 7 } when four writes landed in between
+```
+
+`VersionConflict` is a typed error, so it reaches the client typed and a UI can offer *reload and re-apply* instead of showing a crash. It carries **both** numbers, because "someone else changed it" is not actionable while "you had 3, it is now 7" is.
+
+**Why not `updatedAt`.** A timestamp cannot do this job. Two writes in the same millisecond are indistinguishable, and across replicas the clocks disagree — a comparison that looks correct in a test loses rows under load. An integer the database owns is totally ordered and needs no clock. (`.version()` therefore rejects a `text()` or `timestamp()` column at declaration.)
+
+**What it does not do.** It is not a history — it records *that* a row changed, not what to; use [`plugin-versioning`](/docs/plugins/versioning) for that. It is not a lock: a conflict is **reported**, never queued or merged, because merging two intents is a decision only your application can make. And it is not a retry — "re-apply my change on top of theirs" is correct for some changes and wrong for others, so you write it.
+
+**Three details worth knowing:**
+
+- The version a caller sends is an **expectation, never a write**. It is stripped from the patch, so a client cannot pin its own version and win every race.
+- An update with **no** expectation is still last-write-wins — the default does not change — but the version **still advances**. A version that moved only for careful writers would be worse than none: it would sit still while a careless write changed the row.
+- A row **deleted** underneath you is a conflict too, with `actual: null`. That is how you tell "deleted" from "changed".
+
+## `expires()` — a row with an end date
+
+```ts
+export const inviteLinks = table('inviteLinks', {
+  id:    id(),
+  email: text(),
+}).with(expires())
+
+await ctx.store.insert('inviteLinks', {
+  email,
+  expiresAt: new Date(Date.now() + 24 * 3_600_000),
+})
+```
+
+After that instant the row is **not returned by reads**. `expiresAt` is nullable and null means *never*, so adding the mixin to an existing table does not make its rows vanish.
+
+Opt out for a deliberate read — an admin view, a grace-period check:
+
+```ts
+ctx.store.select('inviteLinks').includeExpired()
+```
+
+### Read this before you rely on it
+
+**Visibility and storage are two different guarantees, and only one of them holds everywhere.**
+
+| | where | when |
+| --- | --- | --- |
+| **Invisible to reads** | every dialect | immediately, the instant it passes |
+| **Physically deleted** | postgres only | eventually, by the retention sweep |
+
+So an expired row is **invisible everywhere and still present in the database on four of five dialects**. That is the right trade — making visibility depend on the sweep would mean a row that vanished on postgres and kept serving on MariaDB — but it is a surprising one, and it matters: *do not treat an expired row as unreachable*. If the value must actually be gone, delete it, or do not store it in a row at all.
+
+## See also
+
+[Column types](/docs/database/columns) · [Mutations](/docs/data/mutations) · [Soft delete](/docs/plugins/soft-delete)
+
+
+
 ---
 
 <!-- source: en/database/ids/index.md -->

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

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

package/templates/agent-docs/deployment.md

@@ -918,6 +918,53 @@ under `NODE_ENV=production` (it refuses unless both fingerprints still match the
 reviewed plan). A Job runs **once per release** vs an `initContainer`'s once per
 replica, so it's the better fit for a multi-replica rollout.
 
+### Expand/contract — the migration that's safe while old pods still serve
+
+The pre-deploy Job applies the schema **before the new pods roll** — so during a
+rolling update, old pods (old code) run against the already-migrated schema for
+the length of the rollout. A migration that DROPS or RENAMES a column, NARROWS a
+type, or ADDS a constraint breaks those old pods mid-rollout: they 500 reading a
+column that's gone, or their writes are rejected by the new constraint. The
+migration "succeeded" and the app served errors anyway.
+
+`voltro db plan` flags these — the operations unsafe under a rolling deploy are
+listed with a `⚠`, separately from the data-safety (lossy / blocked) gate, since
+the two are orthogonal: a `dropped()` column is blessed for data loss and *still*
+breaks an old reader.
+
+```text
+⚠ 1 operation(s) UNSAFE under a rolling deploy
+  (old + new instances overlap → old code breaks against the new schema):
+    • drop-column: old instances still SELECT/INSERT "orders"."legacy_total"; …
+      → stop reading the column in code and deploy that first; drop it in a LATER deploy
+```
+
+Two ways to handle it:
+
+1. **No overlap window** — a maintenance-window or **scale-to-zero** deploy (old
+   pods gone before new ones start) has no simultaneous old code, so a single-step
+   drop/rename is fine. The advisory doesn't apply; ignore it.
+2. **Zero-downtime rollout** — split the breaking change into two releases, each
+   of which keeps *both* code versions working (**expand/contract**):
+   - **Expand** (release N): add the new shape — a nullable column, a new table,
+     a backfill, dual-write from the new code. Old code ignores it.
+   - **Cut over**: the new code reads/writes the new shape; deploy it.
+   - **Contract** (release N+1): once no pod runs the old code, drop/rename/narrow
+     the now-unused old shape. This step's `db plan` is clean.
+
+Renaming `orders.total` → `orders.amount` under zero downtime is: add `amount`
+(expand) → backfill + dual-write → cut reads over → drop `total` (contract) — three
+releases, never one, so no in-flight pod ever references a column that isn't there.
+
+**Make it a hard gate if you always rolling-deploy — `VOLTRO_ROLLING_DEPLOY=1`.**
+The `db plan` ⚠ is advisory by default, because a maintenance-window / scale-to-zero
+deploy has no overlap window and the framework can't tell which you run. If your
+pipeline is *always* a rolling update, set `VOLTRO_ROLLING_DEPLOY=1` in the migration
+Job's env: `voltro db apply` then **refuses** (exit 2) a plan containing a
+rolling-unsafe operation instead of warning, so an un-split breaking change fails the
+deploy rather than breaking pods at runtime. Override a specific apply with `--force`.
+Unset (the default) leaves today's advisory behaviour untouched.
+
 ### If you DO run `voltro dev` in a cluster (dev / staging only)
 
 `voltro dev` binds a small **boot-health surface** on its own port so a probe can
@@ -1059,6 +1106,33 @@ that route to a terminating pod before k8s finishes removing it from the Service
 endpoints. With it, that window is drained. `terminationGracePeriodSeconds` must
 be larger than the sleep plus the app's own teardown, or k8s SIGKILLs mid-drain.
 
+**Bound the app's own teardown with `VOLTRO_SHUTDOWN_GRACE_MS`.** After
+`SIGTERM`, the runtime runs its finalizers (pool close, plugin `onDeactivate`,
+analytics flush, trace persist) and then exits — but installing the signal
+handler removes node's default kill, so a finalizer that *never* completes (a
+pool drain against a database that is already gone, a wedged `onDeactivate`)
+would otherwise hang the process forever. A hard deadline caps that: teardown
+gets until the deadline, then the process exits regardless. It defaults to
+**10s**; set `VOLTRO_SHUTDOWN_GRACE_MS` (clamped to 1s–5min) to sit JUST UNDER
+your `terminationGracePeriodSeconds` minus the preStop sleep — so the app drains
+and exits *cleanly on its own* before k8s SIGKILLs it mid-drain:
+
+```yaml
+spec:
+  terminationGracePeriodSeconds: 30
+  containers:
+    - name: api
+      env:
+        # preStop sleep (5s) + app teardown (≤22s) < 30s grace, with headroom.
+        - name: VOLTRO_SHUTDOWN_GRACE_MS
+          value: "22000"
+```
+
+The close is clean on the client side too: on shutdown each live WebSocket is
+closed with a proper close frame (not an abrupt socket drop), and the web
+client's supervisor reconnects on any close — so an open dashboard re-attaches
+to a healthy replica across a rolling deploy without a page reload.
+
 ## 8. Multiple replicas
 
 Cache and KV default to **in-process** (per-replica). For a shared backend across replicas:
@@ -1087,7 +1161,7 @@ Schedules and aggregates auto-coordinate via an advisory lock on SQL stores —
 - [ ] `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
-- [ ] `terminationGracePeriodSeconds` generous for graceful drain
+- [ ] `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
 
 

package/templates/agent-docs/plugins.md

@@ -70,7 +70,7 @@ Status legend: ✓ shipped · ◐ partial · — planned.
 | `@voltro/plugin-storage` | ✓ | File storage — public (CDN-direct) + private (access policy + per-object grants), S3 / R2 / GCS / MinIO / filesystem providers, presigned URLs, `listRefs` browse/search, HTTP Range (206) serving, dashboard browser |
 | `@voltro/plugin-postgis` | ✓ | Postgres-native `geography` / `geometry` columns + spatial predicates (`ST_DWithin`, `ST_Contains`, `ST_Intersects`); GiST indexes via `.expressionIndex(..., { kind: 'gist' })`. No `ST_Distance` projection yet. Postgres-only by design (fails loud elsewhere). [→ details](/docs/plugins/postgis) |
 | `@voltro/plugin-broadcast` | ✓ | Cross-replica reactivity — fans out app-mutation change events to every replica over a pub/sub bus (Redis / NATS). Closes the single-instance gap for every non-postgres dialect. [→ details](/docs/plugins/broadcast) |
-| `@voltro/plugin-webhooks` | ✓ | Incoming + outgoing webhooks — `defineIncomingWebhook` (signature verify + idempotency, Stripe/GitHub/Slack presets) and `defineOutgoingEvent` (durable delivery workflow, HMAC signing, retries, filters). [→ details](/docs/plugins/webhooks) |
+| `@voltro/plugin-webhooks` | ✓ | Incoming + outgoing webhooks — `defineIncomingWebhook` (signature verify + idempotency, Stripe/GitHub/Slack presets) and `defineEvent` (durable delivery workflow, HMAC signing, retries, filters). [→ details](/docs/plugins/webhooks) |
 | `@voltro/plugin-auth-{workos,kinde,clerk,auth0,supabase,oidc}` | ✓ | Six IdP adapters over the shared `jwtBearerStrategy` — JWKS verify + claims→tenant mapping; WorkOS additionally ships hosted-login OAuth primitives (`workosAuthorizationUrl` / `workosAuthenticateWithCode`) for a redirect-based SSO login flow. [→ details](/docs/authentication/external-idp) |
 | `@voltro/plugin-analytics-postgres` | ✓ | First-party lite — events on the main DataStore, cross-dialect (postgres / mysql / mariadb / mssql / sqlite / turso). [→ details](/docs/plugins/analytics#voltroplugin-analytics-postgres) |
 | `@voltro/plugin-duckdb` | ✓ | Embedded DuckDB sidecar — real OLAP performance, no external service. [→ details](/docs/plugins/analytics#voltroplugin-duckdb) |

package/templates/agent-docs/reference.md

@@ -361,7 +361,7 @@ Events include lifecycle changes, timers, signals, and updates recorded by the w
 
 ## `useWorkflowDomainEvents(apiName, filters?, options?)`
 
-Subscribes to the **domain events** an app emitted through `ctx.events.emit(...)` — the business-event log behind [event triggers](/docs/workflows/event-triggers), not one run's internal timeline.
+Subscribes to the **domain events** an app emitted through `ctx.events.publish(...)` — the business-event log behind [event triggers](/docs/workflows/event-triggers), not one run's internal timeline.
 
 ```tsx
 const { events } = useWorkflowDomainEvents('app', { name: 'order.paid', limit: 50 })
@@ -1131,7 +1131,7 @@ Templates come in **three kinds**, matching the three things you deploy:
 | [`api-rest`](/docs/templates/api-rest) | Public REST API — `defineRestRoute` (query/path/body, scope guards, Idempotency-Key) + `@voltro/plugin-openapi` (OpenAPI 3.1 spec + Swagger UI at `/docs`). Zero-infra boot. |
 | [`api-saas`](/docs/templates/api-saas) | The SaaS plugin bundle — billing entitlements + notifications + analytics + presence, wired turnkey; one `projects.create` exercises three together. Zero-infra boot. |
 | [`api-observability`](/docs/templates/api-observability) | Production-readiness — Prometheus `/metrics` + a custom counter, Sentry (inert without a DSN), tracing, and a `@voltro/testing` unit test (`voltro test`). Zero-infra boot. |
-| [`api-webhooks`](/docs/templates/api-webhooks) | First-class webhooks both ways — a signature-verified incoming `*.webhook.tsx` receiver + an outgoing `defineOutgoingEvent` emitted via a durable signed delivery workflow. Zero-infra boot. |
+| [`api-webhooks`](/docs/templates/api-webhooks) | First-class webhooks both ways — a signature-verified incoming `*.webhook.tsx` receiver + an outgoing `defineEvent` emitted via a durable signed delivery workflow. Zero-infra boot. |
 
 ## Web frontends (`kind: web`)
 

package/templates/agent-docs/security.md

@@ -39,6 +39,24 @@ This matters because a caller-supplied URL is ordinary product surface — a
 scraper, a webhook-registration form, an importer, a "test this connection"
 button. Those reach `HttpClient` with whatever the user typed.
 
+### Handling a refusal
+
+A blocked request fails on the **error channel**, as an `HttpClientError.RequestError` whose `cause` is the `SsrfBlockedError`. So the handler that supplied the URL can decide what it means:
+
+```ts
+yield* enrich(userSuppliedUrl).pipe(
+  Effect.catchTag('RequestError', (e) =>
+    e.cause instanceof SsrfBlockedError
+      ? Effect.succeed(none)          // an optional enrichment: skip it
+      : Effect.fail(e)),              // a real transport failure: keep failing
+)
+```
+
+Two things worth knowing if you are upgrading from a version before this was a failure:
+
+- **It used to be a defect** (`Effect.die`), so code that handled it did so with `Effect.catchAllDefect`. That arm no longer fires. If you also have an `Effect.mapError` above it, the rejection now reaches `mapError` FIRST — and a delivery that classified an SSRF block as *terminal* in the defect arm will be reclassified as whatever `mapError` returns. A consumer hit exactly this: a permanent condition became retryable and burned the full backoff budget re-attempting a request that can never succeed. Nothing in the type system can see that, because the error channel already carried `HttpClientError`.
+- **`description` names the policy** (`SSRF policy: blocked private/reserved address …`), which is what you want in a log line; the `cause` is what you want in a branch.
+
 ### Allowing a target on purpose
 
 ```ts

package/templates/agent-docs/templates/apibackends.md

@@ -663,7 +663,7 @@ const execute = async (
 export default execute
 ```
 
-`TenantMismatch` is imported from the browser-safe `@voltro/plugin-multitenancy/guard` subpath, NOT the package root — the root re-exports the schema mixin, which would drag `@voltro/database` into the client rpcGroup bundle. `ctx.events.emit(...)` is post-commit safe: the event is recorded and fans out only once the row is durably written.
+`TenantMismatch` is imported from the browser-safe `@voltro/plugin-multitenancy/guard` subpath, NOT the package root — the root re-exports the schema mixin, which would drag `@voltro/database` into the client rpcGroup bundle. `ctx.events.publish(...)` is post-commit safe: the event is recorded and fans out only once the row is durably written.
 
 ## Event trigger — start a workflow from a domain event
 
@@ -1019,7 +1019,7 @@ Watch the run in the dashboard's **Workflows** tab (the `awaitSignal` gate also
 
 ## Anti-patterns
 
-- **Emitting the domain event before the write commits.** `orders.place` emits `order.placed` *after* `ctx.store.insert` returns — `ctx.events.emit` is post-commit safe so a rolled-back transaction never starts a workflow for an order that doesn't exist. Don't emit eagerly inside the same expression as the insert.
+- **Worrying about publishing before the write commits.** You no longer have to: inside a mutation `ctx.events.publish` fires on COMMIT and not at all on rollback, so a rolled-back transaction cannot start a workflow for an order that does not exist — and cannot tell a client it does either. Publish wherever it reads best.
 - **Doing external I/O inside a mutation.** The place mutation only inserts + emits. HTTP calls, payments, and other side effects belong in a workflow `step()` (journaled + replayed) or an action — a mutation runs in a transaction and can't roll back an HTTP side effect.
 - **Tracking the workflow run handle to send a signal.** `orders.approve` re-derives the executionId from the payload via the deterministic `idempotencyKey` instead. Storing the handle from the place mutation is unnecessary and breaks across restarts.
 - **Dropping the cross-tenant write guard.** Tables with `tenant()` get automatic SUBSCRIPTION scoping, but a mutation that writes raw rows still needs `assertOwnTenant(input.tenantId, ctx.request.subject)` — and `TenantMismatch` must be imported from `@voltro/plugin-multitenancy/guard` in the descriptor, never the package root (the root leaks `@voltro/database` into the browser bundle).
@@ -2212,7 +2212,7 @@ The package also ships `MockClock` / `MockEmail` / `mockAi` / `makeWorkflowRunne
 <!-- source: en/templates/api-webhooks.md -->
 ## API · Webhooks
 
-_First-class webhooks both ways — a signature-verified incoming *.webhook.tsx receiver (genericProvider HMAC) that rejects forged traffic before your handler runs, plus an outgoing defineOutgoingEvent a mutation emits to subscribed targets via a durable signed delivery workflow. Zero-infra boot._
+_First-class webhooks both ways — a signature-verified incoming *.webhook.tsx receiver (genericProvider HMAC) that rejects forged traffic before your handler runs, plus an outgoing defineEvent a mutation emits to subscribed targets via a durable signed delivery workflow. Zero-infra boot._
 
 Webhooks **both ways**, wired turnkey: a **signature-verified incoming receiver** that rejects forged traffic before your code runs, and an **outgoing event** a mutation emits to subscribed targets through a durable, signed, retried delivery workflow. Webhooks are **file-convention** (drop a `*.webhook.tsx`, it's auto-discovered) — not a `plugins:[]` entry. Boots **zero-infra** (`store: 'memory'`). Template id: **`api-webhooks`**.
 
@@ -2231,7 +2231,7 @@ apps/acme/api/
 ├── .env                                  # VOLTRO_WEBHOOK_SECRET_ORDERS (dev signing secret)
 ├── database/schema.ts                    # orders + webhookTables() bookkeeping
 ├── webhooks/orders.webhook.tsx           # INCOMING — signature-verified receiver
-├── events/order.completed.webhook.tsx    # OUTGOING — defineOutgoingEvent
+├── events/order.completed.webhook.tsx    # OUTGOING — defineEvent
 ├── mutations/orders.fulfill.mutation.ts  # create order + emit (+ .server.ts)
 └── queries/orders.list.query.ts          # reactive list (+ .server.ts)
 ```
@@ -2281,7 +2281,7 @@ curl -s -o /dev/null -w '%{http_code}\n' -X POST http://localhost:4000/webhooks/
 
 ```ts
 // events/order.completed.webhook.tsx
-export default defineOutgoingEvent({ id: 'order.completed', payload: Schema.Struct({ /* … */ }), version: 1 })
+export default defineEvent({ id: 'order.completed', payload: Schema.Struct({ /* … */ }), version: 1 })
 
 // mutations/orders.fulfill.mutation.server.ts — after the row commits:
 const { eventId, deliveries } = await useWebhooks(ctx).emit('order.completed', { orderId, tenantId, /* … */ })

package/templates/agent-docs/templates/overview.md

@@ -43,7 +43,7 @@ The four `api-backend*` shapes share the same minimal `notes` domain and differ
 | [`api-rest`](/docs/templates/api-rest) | **Public REST + OpenAPI** — `defineRestRoute` endpoints (query/path/body, scope guards, `Idempotency-Key`) + `@voltro/plugin-openapi` (Swagger UI at `/docs`, generated from the descriptors). Zero-infra boot. |
 | [`api-saas`](/docs/templates/api-saas) | **The SaaS plugin bundle** — billing entitlements (a quota gate), in-app + console notifications, analytics events, and live presence, wired turnkey. One `projects.create` exercises billing + analytics + notifications together. |
 | [`api-observability`](/docs/templates/api-observability) | **Metrics + errors + tests** — `@voltro/plugin-prometheus` (`GET /metrics` + a custom counter), `@voltro/plugin-sentry` (inert without a DSN), tracing, and a `@voltro/testing` unit test. Zero-infra boot. |
-| [`api-webhooks`](/docs/templates/api-webhooks) | **First-class webhooks** — a signature-verified incoming `*.webhook.tsx` receiver (rejects forged traffic before your handler) + an outgoing `defineOutgoingEvent` a mutation emits via a durable signed delivery workflow. Zero-infra boot. |
+| [`api-webhooks`](/docs/templates/api-webhooks) | **First-class webhooks** — a signature-verified incoming `*.webhook.tsx` receiver (rejects forged traffic before your handler) + an outgoing `defineEvent` a mutation emits via a durable signed delivery workflow. Zero-infra boot. |
 | [`api-search`](/docs/templates/api-search) | **Full-text search in sync** — `@voltro/plugin-search` mirrors every table write into an index via the post-commit change tap; the synthesized `search.query` rpc returns tenant-scoped hits. Memory backend (zero infra); one line to Typesense/Meilisearch/Algolia. |
 | [`api-feature-flags`](/docs/templates/api-feature-flags) | **Feature flags as code** — `@voltro/plugin-flags`: kill-switch / %-rollout / targeting, a declarative `gatedBy` map + an in-handler `requireFlag` guard (both fail typed `FlagDisabled`), `useFlag()` on the web. Memory store. |
 | [`api-ratelimit`](/docs/templates/api-ratelimit) | **Per-endpoint rate limiting** — `@voltro/plugin-ratelimit` intercepts rpc: a default + rules (sliding-window / token-bucket, by subject/tenant/…), typed `RateLimited` auto-merged into the error union. Memory store. |