@voltro/cli 0.24.0 → 0.25.0

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

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