@voltro/cli 0.24.0 → 0.26.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.
@@ -525,34 +525,55 @@ Workflow durability and retry are related, but not identical. The engine checkpo
 
 ## Per-step retries
 
-Use `stepModule.retry(...)` when you want retry attempts to appear as separate step attempts in the dashboard:
+Declare a `retry:` policy on `step({...})` and the framework **enforces** it — it compiles the policy to an Effect `Schedule` and retries `execute` for you. No hand-written retry needed:
 
 ```tsx
-import { workflow, step, stepModule } from '@voltro/workflow'
-import { Effect, Schedule, Schema } from 'effect'
+import { workflow, step } from '@voltro/workflow'
+import { Schema } from 'effect'
 
 class ProviderDown extends Schema.TaggedError<ProviderDown>()('ProviderDown', {
   message: Schema.String,
 }) {}
 
-const summary = yield* stepModule.retry(
-  step({
-    name: 'summarise-with-llm',
-    input: { noteId },
-    success: Schema.String,
-    error: ProviderDown,
-    retry: {
-      strategy: 'exponential',
-      maxAttempts: 5,
-      baseDelay: '500 millis',
-    },
-    execute: callLlm(note.body),
-  }),
-  Schedule.exponential('500 millis').pipe(Schedule.recurs(4)),
-)
+const summary = yield* step({
+  name: 'summarise-with-llm',
+  input: { noteId },
+  success: Schema.String,
+  error: ProviderDown,
+  retry: {
+    maxAttempts: 5,
+    strategy: 'exponential',
+    baseDelay: '500 millis',
+  },
+  execute: callLlm(note.body),
+})
 ```
 
-The `retry` field on `step({...})` is metadata for inspection. The actual retry behaviour comes from `stepModule.retry(...)`, `Effect.retry(...)`, or another Effect retry combinator.
+Retries run inside the one step and are transparent to the durable engine — completed steps still checkpoint; the step's final outcome is recorded. `retry: { maxAttempts: 5 }` is already a good policy (exponential backoff, jittered).
+
+### The conditions you actually want
+
+The useful retry question is rarely "how many times" — it's *which* failures, for *how long*, and *how spread out*. The policy covers all of it:
+
+```tsx
+retry: {
+  maxAttempts: 5,                          // total attempts including the first (default 3)
+  strategy: 'exponential',                 // 'exponential' | 'fixed' | 'linear'
+  baseDelay: '500 millis',
+  maxDelay: '30 seconds',                  // ceiling so exponential growth can't run away
+  factor: 2,                               // exponential growth factor
+  jitter: true,                            // full jitter (default true) — anti-thundering-herd
+  maxElapsed: '5 minutes',                 // a total time BUDGET — stop retrying after this
+  retryableErrors: ['ProviderDown'],       // retry ONLY these typed errors; others fail fast
+  respectRetryAfter: true,                 // honor a 429: retryAfter REPLACES this attempt's backoff
+}
+```
+
+- **`retryableErrors`** (or a `retryable: (error) => boolean` predicate) is the important one: retry the *transient* failures, fail *fast* on the permanent ones. A `ValidationError` should never be retried; a `ProviderDown` should.
+- **`maxElapsed`** is a deadline across all attempts, not another count — the right bound when "keep trying for up to 5 minutes" matters more than "try 8 times".
+- **`respectRetryAfter`** uses exactly the delay a provider asked for (a `retryAfterMillis` number, or `retryAfter` in seconds, on the thrown error) as the next delay, replacing the computed backoff for that attempt; falls back to backoff when there is no hint.
+
+Retries here run *inside* the one step attempt, so the step is recorded as a SINGLE row in `_voltro_workflow_run_steps` with its final outcome — the individual in-step retries are not separate rows. `respectRetryAfter` uses the provider's delay AS the next delay (replacing the computed backoff for that attempt), falling back to backoff when the error carries no hint. For per-attempt rows in the dashboard, or a bespoke `Schedule`, use `stepModule.retry(step({...}), schedule)` instead. Do NOT set `retry:` on a step you ALSO wrap in `stepModule.retry` / `Effect.retry`: it would retry twice.
 
 ## What to retry
 
@@ -604,6 +625,64 @@ For ad-hoc ops, the same operation is available manually — the CLI (`voltro wo
 voltro workflows retry wfrun_01H...
 ```
 
+`retry` starts a **fresh execution** — a new execution id, an empty journal, every step runs again. That is the right tool for a short, idempotent job, or when the input itself was wrong (`payloadOverride`). For a long multi-step pipeline where re-doing steps 1…N‑1 is expensive or unsafe, you want the opposite: resume from where it failed.
+
+## Resume from where it failed — `suspendOnFailure`
+
+Declare `suspendOnFailure: true` on a workflow and a failure no longer becomes a terminal `failed` run — it **suspends** with the durable journal intact:
+
+```ts
+export default workflow({
+  name: 'billing.close-month',
+  payload: { orgId: Schema.String },
+  success: Schema.Void,
+  error: Schema.Unknown,
+  idempotencyKey: ({ orgId }) => `billing.close-month:${orgId}`,
+  suspendOnFailure: true,          // a failure suspends (recoverable), not fails (terminal)
+  execute: ({ orgId }) => Effect.gen(function* () {
+    yield* step('snapshot-ledger', /* … */)   // completed steps are journaled
+    yield* step('call-tax-provider', /* … */)  // ← a transient 503 here …
+    yield* step('finalise-invoices', /* … */)
+  }),
+})
+```
+
+When `call-tax-provider` fails, the run goes to `suspended` (not `failed`), carrying the failure reason. Fix the cause, then **resume** — the engine replays `snapshot-ledger` from the journal (it does **not** re-run) and continues from the failed step:
+
+```sh
+voltro workflows resume wfrun_01H...      # re-drives from the failure point
+```
+
+```ts
+await ctx.workflows.resume(run.id)         // the same, from a handler
+```
+
+Because a suspended-on-failure run is **recoverable, not dead**, it shows up under `--status suspended`, NOT in the [dead-letter view](/docs/workflows/debugging) (`voltro workflows list --dead-letter`, which is failed-and-unhandled). Choose per workflow: `suspendOnFailure: true` for a long pipeline where prior work must not be redone; the default (`retry` from scratch) for short idempotent jobs.
+
+## Re-drive a failed run — `redrive`
+
+`suspendOnFailure` is a decision you make **before** the run. What if a run already **failed** — it's sitting in the dead-letter view — and you still want to continue it from where it died, not re-run it from scratch? That is `redrive`:
+
+```sh
+voltro workflows redrive wf_01H...   # re-drive a FAILED run from the step it died on
+```
+
+```ts
+await ctx.workflows.redrive(run.id)  // the same, from a handler; addressed by run id
+```
+
+`redrive` re-drives the run from its durable journal: every **completed** step replays from the journal (it does **not** re-run), and only the **failed** step(s) re-execute. It is the after-the-fact counterpart to `suspendOnFailure` + `resume` — same "continue from the failure point" outcome, but for a run that already went terminal without being marked suspend-on-failure. Fix the downstream cause first, then redrive.
+
+The three recovery tools, and when each applies:
+
+| Tool | Use when | Journal |
+|---|---|---|
+| `retry` | The input was wrong, or the job is short + idempotent | Fresh execution, empty journal — every step runs again |
+| `resume` | The run is `suspended` (you set `suspendOnFailure: true`, or it awaits a signal) | Continues from the failure/suspend point — completed steps replay |
+| `redrive` | The run is `failed` (dead-letter) and re-running earlier steps is expensive/unsafe | Continues from the failure point — completed steps replay, failed steps re-run |
+
+`redrive` refuses a run that isn't a not-yet-discarded failure (use `resume` for a suspended run, `retry` for a fresh execution), and it needs a durable journal — on the memory store there is nothing to re-drive, so it declines cleanly (`redriven: false` with a reason) rather than pretending. It works under `voltro serve` as well as `voltro dev`, because dead-letter recovery happens in production. A re-drive records a `run-redriven` event on the run's timeline.
+
 ## Compensation
 
 For saga-style workflows, model compensation explicitly with `Effect.catchAll` around the step that can fail after an earlier side effect:
@@ -664,7 +743,7 @@ The dashboard and `voltro workflows show <runId>` read these same tables through
 
 - **Catching errors and returning success.** Operators lose the failed run.
 - **Retrying non-idempotent side effects.** Double charges and duplicate emails are workflow bugs, not retry bugs.
-- **Putting retry metadata on a step without `Effect.retry` or `stepModule.retry`.** Metadata only explains intent; it does not execute a policy.
+- **Declaring `retry:` on a step you ALSO wrap in `Effect.retry` / `stepModule.retry`.** `retry:` is enforced now — the step would retry twice. Keep one.
 - **Expecting a DLQ table.** The current triage surface is failed runs plus retry controls.
 
 
@@ -1181,12 +1260,22 @@ Voltro records workflow runs, step attempts, and lifecycle events into framework
 | `_voltro_workflow_start_contexts` | One row per started execution id: starter subject, trace id, source, parent execution id, parent-close policy, and creation time. Used for cross-runner context handoff. |
 | `_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_run_events` | Lifecycle events: `run-started`, `run-succeeded`, `run-failed`, `run-suspended`, `run-resumed`, `run-redriven`, `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.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`.
 
+## Dead-letter: triaging failed runs
+
+The framework does not retry a workflow on its own (see [Retries](/docs/workflows/retries) — you compose retries inside `execute:` with `Effect.retry`). So a run that reaches `failed` is **terminal**: it is the dead-letter. `voltro workflows list --dead-letter` (or the Prometheus series `voltro_workflow_runs_total{status="failed"}` and the stale `voltro_workflow_last_success_timestamp_seconds` gauge — see [Prometheus](/docs/plugins/prometheus)) is your queue of unhandled failures.
+
+Triage a dead-letter run one of three ways:
+
+- **Retry** it — `voltro workflows retry <id>` starts a fresh execution against the original (or an overridden) payload once you've fixed the cause. Every step runs again from scratch.
+- **Re-drive** it — `voltro workflows redrive <id>` re-drives the run from its durable journal: completed steps replay, only the failed step(s) re-execute. Use this instead of `retry` for a long pipeline where redoing steps 1…N‑1 is expensive or unsafe. It is the after-the-fact counterpart to [`suspendOnFailure` + `resume`](/docs/workflows/retries) and works under `voltro serve` too. Refuses a non-failed / already-discarded run; declines cleanly when there is no durable journal (the memory store). Records a `run-redriven` event.
+- **Discard** it — `voltro workflows discard <id>` acknowledges the failure so it drops off the `--dead-letter` view. It is an **ack, not a re-classification**: the run stays `status: 'failed'` (the outcome + audit trail survive) and gains a `discardedAt` timestamp. `--status failed` still lists it, marked `discarded`; only `--dead-letter` hides it. Discarding a non-failed run is refused, and discarding is idempotent.
+
 ## Dashboard
 
 When `voltro dev` is running, the Workflows panel lists recent runs, their status, start source, timing, payload, output/error, step attempts, and events. The run detail view is the fastest way to answer:
@@ -1199,7 +1288,7 @@ When `voltro dev` is running, the Workflows panel lists recent runs, their statu
 - What output or typed error did it produce?
 - Did a timer or signal fire?
 
-The panel also exposes run controls for users with the right capability: cancel, retry, suspend, resume, send signal, and send a tracked update.
+The panel also exposes run controls for users with the right capability: cancel, retry, suspend, resume, redrive (re-drive a failed run from its journal), discard (acknowledge a failed run), send signal, and send a tracked update.
 
 Run filters can be saved as named views. The selected view and ad-hoc
 filters are mirrored into the URL query string, so a teammate can open the
@@ -1213,12 +1302,15 @@ queued/running/waiting work by workflow lane and start source.
 ```sh
 voltro workflows list --status running --tail 50
 voltro workflows list --tag notes.summarise --format json
+voltro workflows list --dead-letter                  # failed runs not yet discarded
 voltro workflows start notes.summarise --payload '{"noteId":"note_123"}'
 voltro workflows show wfrun_01H...
 voltro workflows retry wfrun_01H...
 voltro workflows cancel wfrun_01H...
 voltro workflows suspend wfrun_01H...
 voltro workflows resume wfrun_01H...
+voltro workflows redrive wfrun_01H...                # re-drive a failed run from where it died
+voltro workflows discard wfrun_01H...                # acknowledge a failed run
 voltro workflows signal wfrun_01H... --name approval --payload '{"approved":true}'
 voltro workflows update wfrun_01H... --name approve --payload '{"decision":true}'
 voltro workflows children exec_01H...
@@ -1241,6 +1333,8 @@ POST /_voltro/inspect/workflows/runs/:id/cancel
 POST /_voltro/inspect/workflows/runs/:id/retry
 POST /_voltro/inspect/workflows/runs/:id/suspend
 POST /_voltro/inspect/workflows/runs/:id/resume
+POST /_voltro/inspect/workflows/runs/:id/redrive
+POST /_voltro/inspect/workflows/runs/:id/discard
 POST /_voltro/inspect/workflows/runs/:id/signal
 POST /_voltro/inspect/workflows/runs/:id/update
 ```
@@ -1383,16 +1477,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,
@@ -1407,23 +1508,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:
 
@@ -1439,11 +1538,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

@@ -12,16 +12,16 @@
   "dependencies": {
     "@effect/platform": "^0.97.0",
     "@effect/rpc": "^0.76.0",
-    "@voltro/ai": "0.24.0",
-    "@voltro/cli": "0.24.0",
-    "@voltro/database": "0.24.0",
-    "@voltro/env": "0.24.0",
-    "@voltro/protocol": "0.24.0",
-    "@voltro/runtime": "0.24.0",
+    "@voltro/ai": "0.26.0",
+    "@voltro/cli": "0.26.0",
+    "@voltro/database": "0.26.0",
+    "@voltro/env": "0.26.0",
+    "@voltro/protocol": "0.26.0",
+    "@voltro/runtime": "0.26.0",
     "effect": "^3.22.0"
   },
   "devDependencies": {
-    "@voltro/testing": "0.24.0",
+    "@voltro/testing": "0.26.0",
     "typescript": "^6.0.3",
     "vitest": "^4.1.10"
   }

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

@@ -13,17 +13,17 @@
   "dependencies": {
     "@effect/platform": "^0.97.0",
     "@effect/rpc": "^0.76.0",
-    "@voltro/cli": "0.24.0",
-    "@voltro/database": "0.24.0",
-    "@voltro/env": "0.24.0",
-    "@voltro/plugin-auth": "0.24.0",
-    "@voltro/protocol": "0.24.0",
-    "@voltro/runtime": "0.24.0",
-    "@voltro/sql-postgres": "0.24.0",
+    "@voltro/cli": "0.26.0",
+    "@voltro/database": "0.26.0",
+    "@voltro/env": "0.26.0",
+    "@voltro/plugin-auth": "0.26.0",
+    "@voltro/protocol": "0.26.0",
+    "@voltro/runtime": "0.26.0",
+    "@voltro/sql-postgres": "0.26.0",
     "effect": "^3.22.0"
   },
   "devDependencies": {
-    "@voltro/testing": "0.24.0",
+    "@voltro/testing": "0.26.0",
     "typescript": "^6.0.3",
     "vitest": "^4.1.10"
   }

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

@@ -13,16 +13,16 @@
   "dependencies": {
     "@effect/platform": "^0.97.0",
     "@effect/rpc": "^0.76.0",
-    "@voltro/cli": "0.24.0",
-    "@voltro/database": "0.24.0",
-    "@voltro/env": "0.24.0",
-    "@voltro/plugin-multitenancy": "0.24.0",
-    "@voltro/protocol": "0.24.0",
-    "@voltro/runtime": "0.24.0",
+    "@voltro/cli": "0.26.0",
+    "@voltro/database": "0.26.0",
+    "@voltro/env": "0.26.0",
+    "@voltro/plugin-multitenancy": "0.26.0",
+    "@voltro/protocol": "0.26.0",
+    "@voltro/runtime": "0.26.0",
     "effect": "^3.22.0"
   },
   "devDependencies": {
-    "@voltro/testing": "0.24.0",
+    "@voltro/testing": "0.26.0",
     "typescript": "^6.0.3",
     "vitest": "^4.1.10"
   }

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

@@ -13,16 +13,16 @@
   "dependencies": {
     "@effect/platform": "^0.97.0",
     "@effect/rpc": "^0.76.0",
-    "@voltro/cli": "0.24.0",
-    "@voltro/database": "0.24.0",
-    "@voltro/env": "0.24.0",
-    "@voltro/plugin-deactivation": "0.24.0",
-    "@voltro/protocol": "0.24.0",
-    "@voltro/runtime": "0.24.0",
+    "@voltro/cli": "0.26.0",
+    "@voltro/database": "0.26.0",
+    "@voltro/env": "0.26.0",
+    "@voltro/plugin-deactivation": "0.26.0",
+    "@voltro/protocol": "0.26.0",
+    "@voltro/runtime": "0.26.0",
     "effect": "^3.22.0"
   },
   "devDependencies": {
-    "@voltro/testing": "0.24.0",
+    "@voltro/testing": "0.26.0",
     "typescript": "^6.0.3",
     "vitest": "^4.1.10"
   }

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

@@ -13,18 +13,18 @@
   "dependencies": {
     "@react-email/components": "^1.0.12",
     "@react-email/render": "^1.4.0",
-    "@voltro/cli": "0.24.0",
-    "@voltro/database": "0.24.0",
-    "@voltro/env": "0.24.0",
-    "@voltro/plugin-mail": "0.24.0",
-    "@voltro/plugin-multitenancy": "0.24.0",
-    "@voltro/protocol": "0.24.0",
-    "@voltro/runtime": "0.24.0",
+    "@voltro/cli": "0.26.0",
+    "@voltro/database": "0.26.0",
+    "@voltro/env": "0.26.0",
+    "@voltro/plugin-mail": "0.26.0",
+    "@voltro/plugin-multitenancy": "0.26.0",
+    "@voltro/protocol": "0.26.0",
+    "@voltro/runtime": "0.26.0",
     "effect": "^3.22.0",
     "react": "^19.0.0"
   },
   "devDependencies": {
-    "@voltro/testing": "0.24.0",
+    "@voltro/testing": "0.26.0",
     "typescript": "^6.0.3",
     "vitest": "^4.1.10"
   }

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

@@ -13,18 +13,18 @@
   "dependencies": {
     "@effect/platform": "^0.97.0",
     "@effect/rpc": "^0.76.0",
-    "@voltro/cli": "0.24.0",
-    "@voltro/database": "0.24.0",
-    "@voltro/env": "0.24.0",
-    "@voltro/plugin-multitenancy": "0.24.0",
-    "@voltro/plugin-storage": "0.24.0",
-    "@voltro/protocol": "0.24.0",
-    "@voltro/runtime": "0.24.0",
-    "@voltro/sql-mysql": "0.24.0",
+    "@voltro/cli": "0.26.0",
+    "@voltro/database": "0.26.0",
+    "@voltro/env": "0.26.0",
+    "@voltro/plugin-multitenancy": "0.26.0",
+    "@voltro/plugin-storage": "0.26.0",
+    "@voltro/protocol": "0.26.0",
+    "@voltro/runtime": "0.26.0",
+    "@voltro/sql-mysql": "0.26.0",
     "effect": "^3.22.0"
   },
   "devDependencies": {
-    "@voltro/testing": "0.24.0",
+    "@voltro/testing": "0.26.0",
     "typescript": "^6.0.3",
     "vitest": "^4.1.10"
   }

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

@@ -11,17 +11,17 @@
     "test": "voltro test"
   },
   "dependencies": {
-    "@voltro/cli": "0.24.0",
-    "@voltro/database": "0.24.0",
-    "@voltro/env": "0.24.0",
-    "@voltro/plugin-multitenancy": "0.24.0",
-    "@voltro/plugin-storage": "0.24.0",
-    "@voltro/protocol": "0.24.0",
-    "@voltro/runtime": "0.24.0",
+    "@voltro/cli": "0.26.0",
+    "@voltro/database": "0.26.0",
+    "@voltro/env": "0.26.0",
+    "@voltro/plugin-multitenancy": "0.26.0",
+    "@voltro/plugin-storage": "0.26.0",
+    "@voltro/protocol": "0.26.0",
+    "@voltro/runtime": "0.26.0",
     "effect": "^3.22.0"
   },
   "devDependencies": {
-    "@voltro/testing": "0.24.0",
+    "@voltro/testing": "0.26.0",
     "typescript": "^6.0.3",
     "vitest": "^4.1.10"
   }

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

@@ -12,17 +12,17 @@
   "dependencies": {
     "@effect/platform": "^0.97.0",
     "@effect/rpc": "^0.76.0",
-    "@voltro/cli": "0.24.0",
-    "@voltro/database": "0.24.0",
-    "@voltro/env": "0.24.0",
-    "@voltro/plugin-governance": "0.24.0",
-    "@voltro/plugin-multitenancy": "0.24.0",
-    "@voltro/protocol": "0.24.0",
-    "@voltro/runtime": "0.24.0",
+    "@voltro/cli": "0.26.0",
+    "@voltro/database": "0.26.0",
+    "@voltro/env": "0.26.0",
+    "@voltro/plugin-governance": "0.26.0",
+    "@voltro/plugin-multitenancy": "0.26.0",
+    "@voltro/protocol": "0.26.0",
+    "@voltro/runtime": "0.26.0",
     "effect": "^3.22.0"
   },
   "devDependencies": {
-    "@voltro/testing": "0.24.0",
+    "@voltro/testing": "0.26.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,
+  }),
+})