@voltro/cli 0.23.0 → 0.25.0

package/templates/agent-docs/workflows.md

@@ -42,7 +42,7 @@ const { runId } = await run.run({})
 | External side effects that need retry/resume semantics | Workflow |
 | Human approval or webhook callback in the middle of work | Workflow + `awaitSignal` |
 | External command that must validate and return a result | Workflow + `awaitUpdate` |
-| Domain event that should fan out to durable work | `triggerWorkflow(...)` + `ctx.events.emit(...)` |
+| Domain event that should fan out to durable work | `triggerWorkflow(...)` + `ctx.events.publish(...)` |
 | One-off durable delay inside an operation | Workflow + `sleep` |
 | Recurring job such as "daily at 3am" | [Schedule](/docs/scheduling/overview) (`*.cron.tsx`) |
 | Atomic database write | Mutation |
@@ -225,7 +225,7 @@ export default triggerWorkflow<{ userId: string; plan: string }, { userId: strin
 Then emit the event from a mutation, action, incoming webhook, schedule, or workflow:
 
 ```ts
-await ctx.events.emit('user.signup', { userId, plan })
+yield* ctx.events.publish(userSignedUp, { userId }, { plan })
 ```
 
 Voltro records the event in `_voltro_workflow_events`, records each trigger delivery in `_voltro_workflow_event_deliveries`, and starts matching workflows with `source: event:<name>`. Emits inside mutations are post-commit safe: if the mutation rolls back, the workflow fan-out is not launched.
@@ -235,7 +235,7 @@ Use `event: '*'` for audit-style wildcard triggers that should see every emitted
 ## Runtime boundaries
 
 - The workflow executor receives an `AppContext` built for the run. Starts from RPC handlers, mutations, actions, schedules, verified incoming handlers, and inspect tooling record a `source` such as `workflow-rpc`, `app-context`, `schedule:<name>`, `incoming:<id>`, or `inspect`. Request starts also carry the starter trace; authenticated request starts carry the resolved subject into the run record and executor context.
-- `ctx.events.emit(...)` is available when the app declares workflow event triggers. Triggered workflow starts carry the starter subject/trace and a `source` of `event:<name>`.
+- `ctx.events.publish(...)` is available when the app declares workflow event triggers. Triggered workflow starts carry the starter subject/trace and a `source` of `event:<name>`.
 - Put tenant/user ids that the workflow must enforce into the payload. That keeps business authorization deterministic across retries, resumes, and future cross-replica handoff.
 - Child workflows should be started with `ctx.workflows.child(...)`. Parent lineage and parent-close policy are persisted before the child start, so they survive cross-runner execution.
 - External incoming handlers created with `defineIncomingWebhook(...)` receive `context.workflows`, so a verified webhook can start, signal, or update a workflow after signature and idempotency checks.
@@ -474,6 +474,36 @@ Workflow starts persist the starter subject, trace id, source, parent execution
 
 Still include tenant/user ids that the business process must enforce in `payload`, validate them in the first step, and scope store reads/writes deliberately. Payload data is replay-safe and makes authorization decisions auditable across retries and deploys.
 
+## Calling an HTTP API from a step
+
+The framework's `HttpClient` is available inside a workflow executor — the same one handlers `yield*`, with the same SSRF allowlist and the same automatic `traceparent` propagation. `yield*` it in a step:
+
+```ts
+import { HttpClient, HttpClientRequest } from '@effect/platform'
+
+export const executor = defineWorkflowExecutor(syncInvoice, (payload) =>
+  Effect.gen(function* () {
+    const remote = yield* step({ name: 'fetch-invoice' }, () =>
+      Effect.gen(function* () {
+        const client = yield* HttpClient.HttpClient
+        const res = yield* client.execute(
+          HttpClientRequest.get(`https://billing.example.com/invoices/${payload.invoiceId}`),
+        )
+        return yield* res.json
+      }),
+    )
+    yield* step({ name: 'persist' }, () => database.invoices.update(payload.invoiceId, remote))
+  }),
+)
+```
+
+Two things follow from where it sits:
+
+- **Wrap the call in a `step`.** The result is then checkpointed, so a retry or a resume after a deploy replays the recorded response instead of calling the remote again. A bare `yield*` outside a step re-issues the request on every replay — which for a payment capture or an email send is the difference between once and several times.
+- **It is the SSRF-guarded client.** Requests to internal targets are refused by the same policy handlers get; a workflow is not a way around it. Configure the allowlist once in `app.config.ts` under `http` — dev and serve read the same key, so the policy cannot differ between them.
+
+Reaching for `fetch` instead loses both: no allowlist, no trace propagation, and nothing tying the call to the step that made it.
+
 ## Anti-patterns
 
 - **Using `input` in `workflow({...})`.** The current API is `payload`.
@@ -1152,7 +1182,7 @@ Voltro records workflow runs, step attempts, and lifecycle events into framework
 | `_voltro_workflow_runs` | One row per run: `id`, `tag`, `executionId`, `status`, `payload`, `workflowVersion`, `workflowPatches`, `output`, error fields, subject, start source, timing, trace id, parent execution id, parent-close policy. |
 | `_voltro_workflow_run_steps` | One row per step attempt: step name, attempt number, recorded input, retry metadata, output or error, duration. |
 | `_voltro_workflow_run_events` | Lifecycle events: `run-started`, `run-succeeded`, `run-failed`, `run-suspended`, `run-resumed`, `run-cancelled`, `timer-set`, `timer-fired`, `signal-awaited`, `signal-sent`, `signal-received`, `update-requested`, `update-received`, `update-completed`, `update-failed`. |
-| `_voltro_workflow_events` | Domain events emitted through `ctx.events.emit(...)`: event id, name, payload, source, subject, trace id, occurred time. |
+| `_voltro_workflow_events` | Domain events emitted through `ctx.events.publish(...)`: event id, name, payload, source, subject, trace id, occurred time. |
 | `_voltro_workflow_event_deliveries` | One row per workflow trigger delivery: event id, trigger id, workflow name, execution id, idempotency key, status, error. |
 
 Run status is `running`, `succeeded`, `failed`, `cancelled`, or `suspended`.
@@ -1353,16 +1383,23 @@ Validation runs on the **decoded** value, so a `Schema.Date` payload accepts a
 <!-- source: en/workflows/event-triggers.md -->
 ## Event triggers
 
-_defineEventTrigger — bind a domain event name to a workflow. ctx.events.emit(name, data) fans the event out to every matching trigger with filter, payload-mapping, and idempotency._
+_defineEventTrigger — bind a domain event name to a workflow. ctx.events.publish(descriptor, key, payload) fans the event out to every matching trigger with filter, payload-mapping, and idempotency._
 
-A workflow is usually kicked off directly (`ctx.workflows.start(...)`). An **event trigger** decouples that: a `*.trigger.tsx` file binds a domain **event name** to a **workflow name**, and any handler that calls `ctx.events.emit('event.name', data)` fans the event out to every trigger listening for it. The emitter never names the workflow — "something happened" is separated from "run this workflow", so you add reactions without touching the code that emits.
+A workflow is usually kicked off directly (`ctx.workflows.start(...)`). An **event trigger** decouples that: a `*.trigger.tsx` file binds a **declared event** to a **workflow name**, and any handler that publishes that event fans it out to every trigger listening for it. The emitter never names the workflow — "something happened" is separated from "run this workflow", so you add reactions without touching the code that emits.
 
 ```tsx
+// events/orders.event.ts — the declaration both sides share
+export const orderPaid = defineEvent({
+  name: 'order.paid',
+  key: Schema.Struct({ orderId: Schema.String }),
+  payload: Schema.Struct({ total: Schema.Number, tenantId: Schema.String }),
+})
+
 // triggers/orderPaid.trigger.tsx
 import { defineEventTrigger } from '@voltro/runtime'
 
 export default defineEventTrigger({
-  event:    'order.paid',                    // the event name to listen for
+  on:       orderPaid,                       // the declared event to listen for
   workflow: 'fulfilment.run',                // the workflow to start
   // Optional: skip when the predicate returns false.
   filter:  (e) => e.data.total > 0,
@@ -1377,23 +1414,21 @@ Discovery walks every `*.trigger.tsx`; the `default` export must be a `defineEve
 
 ## Emitting an event
 
-From any handler, emit through `ctx.events`:
+From any handler with a `ctx`, publish the declared event:
 
 ```ts
-const execute = async (input: { orderId: string }, ctx: AppContext) => {
+const execute = (input: { orderId: string }, ctx: AppContext) => Effect.gen(function* () {
   // ... mark the order paid ...
-  const result = await ctx.events.emit('order.paid', {
-    orderId:  input.orderId,
-    tenantId: ctx.request.subject.tenantId,
+  yield* ctx.events.publish(orderPaid, { orderId: input.orderId }, {
     total:    order.total,
+    tenantId: ctx.request.subject.tenantId,
   })
-  // result.eventId — the persisted event id
-  // result.triggered — one entry per matched trigger:
-  //   { triggerId, workflowName, status: 'started' | 'skipped' | 'failed', run?, reason? }
-}
+})
 ```
 
-`emit(name, data, options?)` accepts `{ id?, source? }` (override the event id / source label). It returns `{ eventId, triggered }` as soon as the workflows are kicked off — the workflows themselves run durably in the background, exactly like `ctx.workflows.start`.
+`publish` reaches BOTH audiences from one call: the durable one (this page — the event log plus every matching trigger) and the ephemeral one ([connected clients](/docs/data/events)). Inside a mutation both fire on COMMIT and neither on rollback, so a client and a triggered workflow cannot disagree about whether the thing happened.
+
+`on:` reads the event NAME off the descriptor, so renaming the event moves the trigger with it. The older string form (`event: 'order.paid'`) was removed in 0.25.0 — with a string, a rename left the trigger matching nothing and the workflow simply never ran again, without an error.
 
 The event envelope every `filter` / `payload` / `idempotencyKey` receives is:
 
@@ -1409,11 +1444,30 @@ The event envelope every `filter` / `payload` / `idempotencyKey` receives is:
 - **Idempotency.** Before starting, the runtime checks for an existing delivery with the same `idempotencyKey` (default `<eventId>:<triggerId>`) — a duplicate is recorded as `status: 'skipped', reason: 'duplicate'` and the workflow is not started twice.
 - **Every emit is audited.** The event itself lands in `_voltro_workflow_events`; one row per trigger lands in `_voltro_workflow_event_deliveries` with `status` (`starting → started`, or `skipped` / `failed`), the started `executionId`, and any error message. Both tables are reactive — the dashboard's Workflows view surfaces deliveries live.
 
+## Retention — and why the delivery TTL is not just housekeeping
+
+Both audit tables are append-only, so both are swept on a **30-day** default by the
+boot retention GC (postgres): `VOLTRO_WORKFLOW_EVENTS_TTL_HOURS` and
+`VOLTRO_WORKFLOW_EVENT_DELIVERIES_TTL_HOURS`. The delivery log grows faster — one
+row per *trigger*, so three triggers on one event write four rows per emit.
+
+**The delivery TTL is the deduplication window.** The idempotency check above looks
+for an existing delivery row, so once a row is swept its key is no longer
+deduplicated. With the default key (`<eventId>:<triggerId>`, and `eventId` is fresh
+per emit) a duplicate cannot occur and this costs nothing. It matters only when you
+supply your own `idempotencyKey`: if your app can re-emit the *same* stable key
+(`fulfil:order-123`) more than 30 days apart and must still be deduplicated, raise
+`VOLTRO_WORKFLOW_EVENT_DELIVERIES_TTL_HOURS` past that horizon.
+
+Unlike `_voltro_outbox`, the delivery log is **not** status-filtered — a stale
+`starting` row has no requeue path and no reader, so keeping it would leave the
+table unbounded for exactly the rows a crash produces.
+
 ## When to use it
 
 Reach for an event trigger when ONE thing happening should fan out to several independent reactions, or when you want the emitter to stay ignorant of the consumers:
 
-- `order.paid` → start fulfilment AND a receipt-email workflow AND an analytics rollup — three triggers, one `emit`.
-- A mutation emits `user.signedUp`; an onboarding workflow trigger starts the drip sequence. The signup mutation never imports the onboarding workflow.
+- `order.paid` → start fulfilment AND a receipt-email workflow AND an analytics rollup — three triggers, one `publish`.
+- A mutation publishes `user.signedUp`; an onboarding workflow trigger starts the drip sequence. The signup mutation never imports the onboarding workflow.
 
-If the handler already knows exactly which workflow to run and there's only one, call [`ctx.workflows.start(...)`](/docs/workflows/definition) directly — the trigger indirection only pays off when you're decoupling emit from react, or fanning one event out to many.
+If the handler already knows exactly which workflow to run and there's only one, call [`ctx.workflows.start(...)`](/docs/workflows/definition) directly — the trigger indirection only pays off when you're decoupling publish from react, or fanning one event out to many.

package/templates/apps/api-ai/package.json

@@ -5,22 +5,23 @@
   "type": "module",
   "scripts": {
     "dev": "voltro dev .",
+    "lint": "voltro doctor .",
     "test": "voltro test",
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
     "@effect/platform": "^0.97.0",
     "@effect/rpc": "^0.76.0",
-    "@voltro/ai": "0.23.0",
-    "@voltro/cli": "0.23.0",
-    "@voltro/database": "0.23.0",
-    "@voltro/env": "0.23.0",
-    "@voltro/protocol": "0.23.0",
-    "@voltro/runtime": "0.23.0",
+    "@voltro/ai": "0.25.0",
+    "@voltro/cli": "0.25.0",
+    "@voltro/database": "0.25.0",
+    "@voltro/env": "0.25.0",
+    "@voltro/protocol": "0.25.0",
+    "@voltro/runtime": "0.25.0",
     "effect": "^3.22.0"
   },
   "devDependencies": {
-    "@voltro/testing": "0.23.0",
+    "@voltro/testing": "0.25.0",
     "typescript": "^6.0.3",
     "vitest": "^4.1.10"
   }

package/templates/apps/api-auth/package.json

@@ -5,6 +5,7 @@
   "type": "module",
   "scripts": {
     "dev": "voltro dev .",
+    "lint": "voltro doctor .",
     "migrate": "voltro migrate",
     "test": "voltro test",
     "typecheck": "tsc --noEmit"
@@ -12,17 +13,17 @@
   "dependencies": {
     "@effect/platform": "^0.97.0",
     "@effect/rpc": "^0.76.0",
-    "@voltro/cli": "0.23.0",
-    "@voltro/database": "0.23.0",
-    "@voltro/env": "0.23.0",
-    "@voltro/plugin-auth": "0.23.0",
-    "@voltro/protocol": "0.23.0",
-    "@voltro/runtime": "0.23.0",
-    "@voltro/sql-postgres": "0.23.0",
+    "@voltro/cli": "0.25.0",
+    "@voltro/database": "0.25.0",
+    "@voltro/env": "0.25.0",
+    "@voltro/plugin-auth": "0.25.0",
+    "@voltro/protocol": "0.25.0",
+    "@voltro/runtime": "0.25.0",
+    "@voltro/sql-postgres": "0.25.0",
     "effect": "^3.22.0"
   },
   "devDependencies": {
-    "@voltro/testing": "0.23.0",
+    "@voltro/testing": "0.25.0",
     "typescript": "^6.0.3",
     "vitest": "^4.1.10"
   }

package/templates/apps/api-backend/package.json

@@ -5,6 +5,7 @@
   "type": "module",
   "scripts": {
     "dev": "voltro dev .",
+    "lint": "voltro doctor .",
     "migrate": "voltro migrate",
     "test": "voltro test",
     "typecheck": "tsc --noEmit"
@@ -12,16 +13,16 @@
   "dependencies": {
     "@effect/platform": "^0.97.0",
     "@effect/rpc": "^0.76.0",
-    "@voltro/cli": "0.23.0",
-    "@voltro/database": "0.23.0",
-    "@voltro/env": "0.23.0",
-    "@voltro/plugin-multitenancy": "0.23.0",
-    "@voltro/protocol": "0.23.0",
-    "@voltro/runtime": "0.23.0",
+    "@voltro/cli": "0.25.0",
+    "@voltro/database": "0.25.0",
+    "@voltro/env": "0.25.0",
+    "@voltro/plugin-multitenancy": "0.25.0",
+    "@voltro/protocol": "0.25.0",
+    "@voltro/runtime": "0.25.0",
     "effect": "^3.22.0"
   },
   "devDependencies": {
-    "@voltro/testing": "0.23.0",
+    "@voltro/testing": "0.25.0",
     "typescript": "^6.0.3",
     "vitest": "^4.1.10"
   }

package/templates/apps/api-backend-deactivation/package.json

@@ -5,6 +5,7 @@
   "type": "module",
   "scripts": {
     "dev": "voltro dev .",
+    "lint": "voltro doctor .",
     "migrate": "voltro migrate",
     "test": "voltro test",
     "typecheck": "tsc --noEmit"
@@ -12,16 +13,16 @@
   "dependencies": {
     "@effect/platform": "^0.97.0",
     "@effect/rpc": "^0.76.0",
-    "@voltro/cli": "0.23.0",
-    "@voltro/database": "0.23.0",
-    "@voltro/env": "0.23.0",
-    "@voltro/plugin-deactivation": "0.23.0",
-    "@voltro/protocol": "0.23.0",
-    "@voltro/runtime": "0.23.0",
+    "@voltro/cli": "0.25.0",
+    "@voltro/database": "0.25.0",
+    "@voltro/env": "0.25.0",
+    "@voltro/plugin-deactivation": "0.25.0",
+    "@voltro/protocol": "0.25.0",
+    "@voltro/runtime": "0.25.0",
     "effect": "^3.22.0"
   },
   "devDependencies": {
-    "@voltro/testing": "0.23.0",
+    "@voltro/testing": "0.25.0",
     "typescript": "^6.0.3",
     "vitest": "^4.1.10"
   }

package/templates/apps/api-backend-mail/package.json

@@ -5,6 +5,7 @@
   "type": "module",
   "scripts": {
     "dev": "voltro dev .",
+    "lint": "voltro doctor .",
     "migrate": "voltro migrate",
     "typecheck": "tsc --noEmit",
     "test": "voltro test"
@@ -12,18 +13,18 @@
   "dependencies": {
     "@react-email/components": "^1.0.12",
     "@react-email/render": "^1.4.0",
-    "@voltro/cli": "0.23.0",
-    "@voltro/database": "0.23.0",
-    "@voltro/env": "0.23.0",
-    "@voltro/plugin-mail": "0.23.0",
-    "@voltro/plugin-multitenancy": "0.23.0",
-    "@voltro/protocol": "0.23.0",
-    "@voltro/runtime": "0.23.0",
+    "@voltro/cli": "0.25.0",
+    "@voltro/database": "0.25.0",
+    "@voltro/env": "0.25.0",
+    "@voltro/plugin-mail": "0.25.0",
+    "@voltro/plugin-multitenancy": "0.25.0",
+    "@voltro/protocol": "0.25.0",
+    "@voltro/runtime": "0.25.0",
     "effect": "^3.22.0",
     "react": "^19.0.0"
   },
   "devDependencies": {
-    "@voltro/testing": "0.23.0",
+    "@voltro/testing": "0.25.0",
     "typescript": "^6.0.3",
     "vitest": "^4.1.10"
   }

package/templates/apps/api-backend-mariadb/package.json

@@ -5,6 +5,7 @@
   "type": "module",
   "scripts": {
     "dev": "voltro dev .",
+    "lint": "voltro doctor .",
     "migrate": "voltro migrate",
     "test": "voltro test",
     "typecheck": "tsc --noEmit"
@@ -12,18 +13,18 @@
   "dependencies": {
     "@effect/platform": "^0.97.0",
     "@effect/rpc": "^0.76.0",
-    "@voltro/cli": "0.23.0",
-    "@voltro/database": "0.23.0",
-    "@voltro/env": "0.23.0",
-    "@voltro/plugin-multitenancy": "0.23.0",
-    "@voltro/plugin-storage": "0.23.0",
-    "@voltro/protocol": "0.23.0",
-    "@voltro/runtime": "0.23.0",
-    "@voltro/sql-mysql": "0.23.0",
+    "@voltro/cli": "0.25.0",
+    "@voltro/database": "0.25.0",
+    "@voltro/env": "0.25.0",
+    "@voltro/plugin-multitenancy": "0.25.0",
+    "@voltro/plugin-storage": "0.25.0",
+    "@voltro/protocol": "0.25.0",
+    "@voltro/runtime": "0.25.0",
+    "@voltro/sql-mysql": "0.25.0",
     "effect": "^3.22.0"
   },
   "devDependencies": {
-    "@voltro/testing": "0.23.0",
+    "@voltro/testing": "0.25.0",
     "typescript": "^6.0.3",
     "vitest": "^4.1.10"
   }

package/templates/apps/api-backend-storage/package.json

@@ -5,22 +5,23 @@
   "type": "module",
   "scripts": {
     "dev": "voltro dev .",
+    "lint": "voltro doctor .",
     "migrate": "voltro migrate",
     "typecheck": "tsc --noEmit",
     "test": "voltro test"
   },
   "dependencies": {
-    "@voltro/cli": "0.23.0",
-    "@voltro/database": "0.23.0",
-    "@voltro/env": "0.23.0",
-    "@voltro/plugin-multitenancy": "0.23.0",
-    "@voltro/plugin-storage": "0.23.0",
-    "@voltro/protocol": "0.23.0",
-    "@voltro/runtime": "0.23.0",
+    "@voltro/cli": "0.25.0",
+    "@voltro/database": "0.25.0",
+    "@voltro/env": "0.25.0",
+    "@voltro/plugin-multitenancy": "0.25.0",
+    "@voltro/plugin-storage": "0.25.0",
+    "@voltro/protocol": "0.25.0",
+    "@voltro/runtime": "0.25.0",
     "effect": "^3.22.0"
   },
   "devDependencies": {
-    "@voltro/testing": "0.23.0",
+    "@voltro/testing": "0.25.0",
     "typescript": "^6.0.3",
     "vitest": "^4.1.10"
   }

package/templates/apps/api-data-advanced/package.json

@@ -5,23 +5,24 @@
   "type": "module",
   "scripts": {
     "dev": "voltro dev .",
+    "lint": "voltro doctor .",
     "test": "voltro test",
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
     "@effect/platform": "^0.97.0",
     "@effect/rpc": "^0.76.0",
-    "@voltro/cli": "0.23.0",
-    "@voltro/database": "0.23.0",
-    "@voltro/env": "0.23.0",
-    "@voltro/plugin-governance": "0.23.0",
-    "@voltro/plugin-multitenancy": "0.23.0",
-    "@voltro/protocol": "0.23.0",
-    "@voltro/runtime": "0.23.0",
+    "@voltro/cli": "0.25.0",
+    "@voltro/database": "0.25.0",
+    "@voltro/env": "0.25.0",
+    "@voltro/plugin-governance": "0.25.0",
+    "@voltro/plugin-multitenancy": "0.25.0",
+    "@voltro/protocol": "0.25.0",
+    "@voltro/runtime": "0.25.0",
     "effect": "^3.22.0"
   },
   "devDependencies": {
-    "@voltro/testing": "0.23.0",
+    "@voltro/testing": "0.25.0",
     "typescript": "^6.0.3",
     "vitest": "^4.1.10"
   }

package/templates/apps/api-durable/README.md

@@ -28,7 +28,8 @@ state + multi-instance cluster workflow runners.
 |---|---|---|
 | `app.config.ts`                                | app config        | `store: 'memory'`, zero-infra boot. |
 | `database/schema.ts`                           | schema            | core `actors`/`tenants` + an `orders` table (`tenant()` + `.reactive()`). |
-| `mutations/orders.place.mutation.*`            | mutation          | insert an order, then **emit `order.placed`** post-commit via `ctx.events.emit`. Tenant write-guard. |
+| `mutations/orders.place.mutation.*`            | mutation          | insert an order and **publish `order.placed`** on commit via `ctx.events.publish`. Tenant write-guard. |
+| `events/orders.event.ts`                       | event             | the declared `order.placed` — one value shared by the publisher, the trigger and any client. |
 | `triggers/order.placed.trigger.tsx`            | event trigger     | maps event `order.placed` → **start** the `orders.fulfill` workflow. |
 | `workflows/order.fulfill.workflow.*`           | durable workflow  | `step('reserve-stock')` (with **`withCompensation`** saga rollback) → `sleep` → **`awaitSignal('approval')`** human gate → `step('ship')` / mark rejected. |
 | `mutations/orders.approve.mutation.*`          | mutation          | inject the `approval` signal into the parked run via `ctx.workflows.signal(...)`. |

package/templates/apps/api-durable/events/orders.event.ts

@@ -0,0 +1,18 @@
+// The declared domain event. Browser-safe: the SAME value is imported by the
+// mutation that publishes it, the trigger that reacts to it, and any client that
+// wants to watch it live — which is what makes the payload type identical
+// everywhere and a rename impossible to half-apply.
+
+import { defineEvent } from '@voltro/protocol'
+import { Schema } from 'effect'
+
+export const orderPlaced = defineEvent({
+  name: 'order.placed',
+  // The ROUTING key: which subscribers receive this. Only what decides
+  // delivery belongs here — the tenant comes from the subject, never the key.
+  key: Schema.Struct({ orderId: Schema.String }),
+  payload: Schema.Struct({
+    orderId:  Schema.String,
+    tenantId: Schema.String,
+  }),
+})

package/templates/apps/api-durable/mutations/orders.place.mutation.server.ts

@@ -1,34 +1,36 @@
 // `orders.place` — EXECUTOR (server-only, default export).
 //
-// Inserts the order in the mutation transaction, then emits a domain
-// event AFTER commit. `ctx.events.emit(...)` is post-commit safe: the
-// event is recorded + the `order.placed` trigger fans out only once the
-// row is durably written, so a rollback never starts a fulfillment
-// workflow for an order that doesn't exist.
+// Inserts the order and publishes a declared domain event in the SAME
+// transaction. `ctx.events.publish(...)` fires on COMMIT and not at all on
+// rollback, so a rolled-back order can neither start a fulfillment workflow nor
+// tell a connected client that it exists — you do not have to sequence the two
+// by hand.
 
 import { assertOwnTenant } from '@voltro/plugin-multitenancy/guard'
+import { Effect } from 'effect'
 import type { AppContext } from '@voltro/runtime'
+import { orderPlaced } from '../events/orders.event'
 
-const execute = async (
+const execute = (
   input: { tenantId: string; customerName: string; amountCents: number },
   ctx: AppContext,
-) => {
+) => Effect.gen(function* () {
   // Cross-tenant write guard — reject a caller spoofing input.tenantId.
   assertOwnTenant(input.tenantId, ctx.request.subject)
 
   // Framework auto-injects an `order_…` id + the tenant/audit columns.
-  const row = await ctx.store.insert('orders', {
+  const row = yield* Effect.promise(() => ctx.store.insert('orders', {
     status:       'placed',
     customerName: input.customerName,
     amountCents:  input.amountCents,
     tenantId:     input.tenantId,
-  })
+  }))
 
-  // Post-commit fan-out → the `order.placed` trigger starts the
-  // `orders.fulfill` workflow. `ctx.events` is only present when the
-  // runtime wired the events facade (it always is under `voltro dev`);
-  // guard so a unit-test ctx without it doesn't throw.
-  await ctx.events?.emit('order.placed', {
+  // One publish, both audiences: the `order.placed` trigger starts the
+  // `orders.fulfill` workflow, and any client watching this order sees it live.
+  // Both on the commit boundary — they cannot disagree about whether it
+  // happened.
+  yield* ctx.events!.publish(orderPlaced, { orderId: row['id'] as string }, {
     orderId:  row['id'] as string,
     tenantId: input.tenantId,
   })
@@ -40,6 +42,6 @@ const execute = async (
     amountCents:  row['amountCents'] as number,
     tenantId:     row['tenantId'] as string,
   }
-}
+})
 
 export default execute

package/templates/apps/api-durable/package.json

@@ -5,23 +5,24 @@
   "type": "module",
   "scripts": {
     "dev": "voltro dev .",
+    "lint": "voltro doctor .",
     "test": "voltro test",
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
     "@effect/platform": "^0.97.0",
     "@effect/rpc": "^0.76.0",
-    "@voltro/cli": "0.23.0",
-    "@voltro/database": "0.23.0",
-    "@voltro/env": "0.23.0",
-    "@voltro/plugin-multitenancy": "0.23.0",
-    "@voltro/protocol": "0.23.0",
-    "@voltro/runtime": "0.23.0",
-    "@voltro/workflow": "0.23.0",
+    "@voltro/cli": "0.25.0",
+    "@voltro/database": "0.25.0",
+    "@voltro/env": "0.25.0",
+    "@voltro/plugin-multitenancy": "0.25.0",
+    "@voltro/protocol": "0.25.0",
+    "@voltro/runtime": "0.25.0",
+    "@voltro/workflow": "0.25.0",
     "effect": "^3.22.0"
   },
   "devDependencies": {
-    "@voltro/testing": "0.23.0",
+    "@voltro/testing": "0.25.0",
     "typescript": "^6.0.3",
     "vitest": "^4.1.10"
   }

package/templates/apps/api-durable/triggers/order.placed.trigger.tsx

@@ -1,9 +1,10 @@
 // Event → workflow trigger. Auto-discovered (`*.trigger.tsx`); no
 // app.config wiring needed.
 //
-// When any handler emits `order.placed` (the `orders.place` mutation
-// does, post-commit), this trigger starts the `orders.fulfill`
-// workflow. The event payload IS the workflow payload here (both are
+// When any handler publishes `order.placed` (the `orders.place` mutation does,
+// on commit), this trigger starts the `orders.fulfill` workflow. It binds the
+// DECLARED event rather than its name, so renaming the event moves this file
+// with it instead of silently matching nothing. The event payload IS the workflow payload here (both are
 // `{ orderId, tenantId }`), so no `payload` mapper is needed — pass one
 // when the shapes differ.
 //
@@ -11,11 +12,12 @@
 // (crash + replay), the matching key short-circuits the second start.
 
 import { defineEventTrigger } from '@voltro/runtime'
+import { orderPlaced } from '../events/orders.event'
 
 export default defineEventTrigger<
   { orderId: string; tenantId: string }
 >({
-  event:    'order.placed',
+  on:       orderPlaced,
   workflow: 'orders.fulfill',
   idempotencyKey: (event) => `order.placed:${event.data.orderId}`,
 })

package/templates/apps/api-feature-flags/package.json

@@ -5,6 +5,7 @@
   "type": "module",
   "scripts": {
     "dev": "voltro dev .",
+    "lint": "voltro doctor .",
     "migrate": "voltro migrate",
     "test": "voltro test",
     "typecheck": "tsc --noEmit"
@@ -12,18 +13,18 @@
   "dependencies": {
     "@effect/platform": "^0.97.0",
     "@effect/rpc": "^0.76.0",
-    "@voltro/cli": "0.23.0",
-    "@voltro/database": "0.23.0",
-    "@voltro/env": "0.23.0",
-    "@voltro/plugin-flags": "0.23.0",
-    "@voltro/plugin-multitenancy": "0.23.0",
-    "@voltro/protocol": "0.23.0",
-    "@voltro/runtime": "0.23.0",
-    "@voltro/sql-postgres": "0.23.0",
+    "@voltro/cli": "0.25.0",
+    "@voltro/database": "0.25.0",
+    "@voltro/env": "0.25.0",
+    "@voltro/plugin-flags": "0.25.0",
+    "@voltro/plugin-multitenancy": "0.25.0",
+    "@voltro/protocol": "0.25.0",
+    "@voltro/runtime": "0.25.0",
+    "@voltro/sql-postgres": "0.25.0",
     "effect": "^3.22.0"
   },
   "devDependencies": {
-    "@voltro/testing": "0.23.0",
+    "@voltro/testing": "0.25.0",
     "typescript": "^6.0.3",
     "vitest": "^4.1.10"
   }