@voltro/cli 0.24.0 → 0.26.0

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

@@ -1556,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.

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

@@ -423,6 +423,53 @@ the framework ships richer types for specific use cases:
 - **[JSON](/docs/database/json)** — `json<T>()` for arbitrary nested
   data; native JSONB on postgres.
 
+## Pointing at a plugin-owned row — `pluginRef`
+
+```ts
+import { pluginRef } from '@voltro/database'
+import { aiFlowsTable } from '@voltro/plugin-ai-flows'
+
+export const favourites = table('favourites', {
+  id: id(),
+  flowId:     pluginRef(aiFlowsTable, { orphanPolicy: 'delete' }),
+  sharedFlow: pluginRef(aiFlowsTable, { orphanPolicy: 'null' }).nullable(),
+})
+```
+
+A plain typed id column with **no foreign key**, plus a declared orphan rule the
+framework runs on the post-commit change channel.
+
+**Reach for `reference()` first.** A real foreign key across a plugin boundary
+works and survives the plugin renaming its table, because `reference()` takes
+the table as a VALUE — see
+[plugins/overview](/docs/plugins/overview#pointing-your-table-at-a-plugins-row).
+`pluginRef` is for the case where you have deliberately chosen NOT to have a
+key: it enforces nothing at the database level.
+
+What it restores is the piece that goes missing with that choice — not the
+constraint but the RULE, which otherwise becomes a hand-written subscriber per
+app that nobody notices the absence of.
+
+| policy | on the target's delete |
+| --- | --- |
+| `'delete'` | delete the referencing row — for one that only exists to point (a favourite, a pin, a share) |
+| `'null'` | clear the column, keep the row. Requires `.nullable()` |
+| `'keep'` (default) | nothing — the explicit "I handle it myself" |
+
+Four things worth knowing before you rely on it:
+
+- **The tenant boundary fails closed.** A referencing row whose tenant differs
+  from the deleted row's — or which has none — is left alone. Deleting across a
+  tenant boundary because a scope was missing is worse than leaving an orphan.
+- **Soft deletes are opt-in** (`onSoftDelete: true`). A soft delete is a state
+  the target can undo, so cascading on it destroys rows a restore cannot bring
+  back — and plugin tables are inconsistent about carrying `deletedAt` at all.
+- **The target is a table VALUE.** A rename carries the rule with it, which is
+  the whole reason the FK was refused; a string would put the coupling back.
+- **A missing plugin refuses at boot**, naming both sides. A declared rule
+  against a table nothing registers would sit there looking enforced.
+
+
 ## Anti-patterns
 
 - **`serial`/`bigserial` integer ids.** Leaks row counts via `/users/12345`. Use `id()` (TypeID).
@@ -629,6 +676,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/deployment.md

@@ -956,6 +956,15 @@ 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
@@ -1141,6 +1150,24 @@ KV_BACKEND=redis
 
 Schedules and aggregates auto-coordinate via an advisory lock on SQL stores — no extra config to keep them from double-firing across replicas.
 
+### Workflow failover across replicas
+
+On a **SQL store** (postgres / mysql / mariadb / mssql), durable workflows survive a replica crash: completed `step({...})` activities are checkpointed in the cluster journal, so when a replica dies mid-run, a **surviving replica takes over the run and continues it from the last completed step** — it replays the completed steps rather than re-running them. (On sqlite the engine is single-process — durable within one replica, no cross-replica failover.) Two requirements:
+
+- **Inject `POD_IP`** (K8s downward API, `fieldRef: status.podIP`) or set `VOLTRO_WORKFLOW_RUNNER_HOST`. This is each replica's cluster **identity** — without a distinct value, every replica registers as the *same* runner and they stop distributing shards (and cross-pod resume degrades). The boot logs a warning if it sees `localhost` with SQL storage.
+- **Make step side effects idempotent.** Failover is *at-least-once at the step boundary*: a crash between a side effect and its journal write re-runs that step. A step's own [`retry:`](/docs/workflows/retries) does not change this — it's about the step you're inside, not the replica handoff.
+
+**Is polling the bottleneck? No — reclaim is a lease, not a poll.** A crashed replica keeps its shards until its heartbeat goes stale; only then can a survivor claim them. So takeover latency is bounded by the **lease TTL (~35s by default)**, not by any message-poll interval, and a push mechanism (LISTEN/NOTIFY) does **not** move it. Two knobs tune it:
+
+```sh
+VOLTRO_WORKFLOW_FAILOVER_LEASE=15       # seconds a dead replica's work stays locked (default 35)
+VOLTRO_WORKFLOW_FAILOVER_HEARTBEAT=5    # lease-refresh cadence (default 10; keep ≈ lease/3)
+```
+
+Lower the lease for **faster failover**, at the cost of **false-positive reclaims**: if a *healthy* replica is paused longer than the lease by a GC pause or a DB-latency spike, another replica may briefly also claim its shards. Keep the heartbeat around a third of the lease so one slow refresh doesn't trip a reclaim. For crash detection that doesn't depend on the timeout at all, pair it with a K8s **liveness probe** so a dead pod is removed promptly.
+
+(A separate concern is *new*-message pickup: a workflow triggered on the replica that owns its shard starts immediately, but one owned by ANOTHER replica is otherwise picked up on that replica's next storage poll — up to 10s. **If you run a broadcast broker (Redis/NATS — which a multi-replica deployment already does for cross-replica reactivity), this is automatic and near-instant**: a trigger pushes a "wake" over the bus and the shard owner re-polls at once, on any SQL dialect. Without a broker, tune `VOLTRO_WORKFLOW_POLL_INTERVAL=2` instead. Unrelated to the failover path above.)
+
 ## Checklist
 
 - [ ] `VOLTRO_SESSION_SECRET` set from `voltro secret generate session`, in a secrets manager
@@ -1154,6 +1181,7 @@ Schedules and aggregates auto-coordinate via an advisory lock on SQL stores —
 - [ ] `VOLTRO_LOG_FORMAT=json`; `sentryPlugin()` + `SENTRY_DSN` for errors
 - [ ] `terminationGracePeriodSeconds` generous for graceful drain; `VOLTRO_SHUTDOWN_GRACE_MS` set just under it (minus the preStop sleep)
 - [ ] `CACHE_BACKEND` / `KV_BACKEND` + a cross-replica change bus when running >1 replica
+- [ ] For durable workflows on >1 replica: SQL store + `POD_IP` injected; tune `VOLTRO_WORKFLOW_FAILOVER_LEASE` if a 35s takeover is too slow; step side effects idempotent
 
 
 

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) |
@@ -166,9 +166,31 @@ the `_voltro_` namespace in 0.22.0, a `reference(() => table)` followed the rena
 **`fk: false`-style decoupling is still available** — declare a plain `text()`
 column instead. Choose it when you deliberately want the app schema independent
 of the plugin's, and accept that nothing then enforces the link. What you should
-NOT do is reach for it by default: an unenforced id column plus a hand-written
-`defineSubscriber` that cleans up on delete is referential integrity re-implemented
-per app, and it is silently wrong the first time somebody forgets it.
+NOT do is reach for it by default.
+
+**When you DO want the decoupling, `pluginRef` gives you the rule without the
+key.** It is a plain typed id column — no constraint, no cross-schema
+dependency — plus a declared orphan policy the framework runs on the post-commit
+change channel:
+
+```ts
+import { pluginRef } from '@voltro/database'
+
+flowId:     pluginRef(aiFlowsTable, { orphanPolicy: 'delete' })
+sharedFlow: pluginRef(aiFlowsTable, { orphanPolicy: 'null' }).nullable()
+```
+
+That closes the gap named above: an unenforced id column plus a hand-written
+`defineSubscriber` that cleans up on delete is referential integrity
+re-implemented per app, and it is silently wrong the first time somebody forgets
+it. The declaration is the same one line either way — the difference is that the
+framework performs it.
+
+**Prefer `reference()` when you want a real key.** `pluginRef` is for the case
+where you have deliberately chosen not to have one; it does not make the
+database enforce anything. The tenant boundary fails closed, soft deletes are
+opt-in (`onSoftDelete`), and a `pluginRef` at a table no installed plugin
+registers refuses at boot rather than sitting there looking enforced.
 
 **`orphanPolicy` is not part of this.** It is migration metadata — how existing
 orphan rows are cleaned up *before* the FK constraint is added — and has no

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. |