@voltro/cli 0.25.0 → 0.26.0

package/dist/serveEntry.js

@@ -1,5 +1,5 @@
-import { Z as e } from "./inspectMetrics-EQwH7BI4.js";
+import { Z as e } from "./inspectMetrics-BU90mvJN.js";
 import { c as t } from "./seedRunner-D6eu-u5U.js";
 import { r as n } from "./appModuleLoader-C9r9mxZt.js";
-import { t as r } from "./serveCommand-5ZFiNO1R.js";
+import { t as r } from "./serveCommand-XBXuwJty.js";
 export { e as loadDotEnv, n as registerAppModules, t as registerDriver, r as runServe };

package/dist/{start-C-ZWSDpg.js → start-BGXIf6zT.js}

@@ -1,5 +1,5 @@
-import { $ as e, D as t, F as n, G as r, H as i, J as a, K as o, M as s, T as c, U as l, W as u, Y as d, _ as ee, a as te, b as f, c as p, dt as m, et as h, f as g, ft as _, g as ne, h as v, i as re, lt as y, m as b, mt as x, nt as ie, o as S, ot as C, p as w, pt as ae, r as T, rt as E, s as D, t as O, tt as k, v as A, w as j, x as M, y as oe, z as se } from "./inspectMetrics-EQwH7BI4.js";
-import { D as ce, E as le, T as ue, a as de, p as N, w as P } from "./inspect-DuLUrZp9.js";
+import { $ as e, D as t, F as n, G as r, H as i, J as a, K as o, M as s, T as c, U as l, W as u, Y as d, _ as ee, a as te, b as f, c as p, dt as m, et as h, f as g, ft as _, g as ne, h as v, i as re, lt as y, m as b, mt as x, nt as ie, o as S, ot as C, p as w, pt as ae, r as T, rt as E, s as D, t as O, tt as k, v as A, w as j, x as M, y as oe, z as se } from "./inspectMetrics-BU90mvJN.js";
+import { D as ce, E as le, T as ue, a as de, p as N, w as P } from "./inspect-CUCCzw2I.js";
 import { t as fe } from "./bootTiming-BdyP9nYw.js";
 import { dirname as F, extname as I, join as L, resolve as R } from "node:path";
 import { fileURLToPath as z, pathToFileURL as B } from "node:url";

package/dist/startEntry.js

@@ -1,3 +1,3 @@
-import { Z as e } from "./inspectMetrics-EQwH7BI4.js";
-import { t } from "./start-C-ZWSDpg.js";
+import { Z as e } from "./inspectMetrics-BU90mvJN.js";
+import { t } from "./start-BGXIf6zT.js";
 export { e as loadDotEnv, t as runStartCommand };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltro/cli",
-  "version": "0.25.0",
+  "version": "0.26.0",
   "description": "The `voltro` CLI — dev server, codegen, migrations, project scaffolding, agent-docs seeding, and production serve.",
   "keywords": [
     "voltro",
@@ -62,22 +62,22 @@
     "@effect/platform-node": "^0.108.0",
     "@effect/sql": "^0.52.0",
     "@effect/workflow": "^0.19.0",
-    "@voltro/ai": "0.25.0",
-    "@voltro/cache": "0.25.0",
-    "@voltro/data-transfer": "0.25.0",
-    "@voltro/database": "0.25.0",
-    "@voltro/env": "0.25.0",
-    "@voltro/kv": "0.25.0",
-    "@voltro/logger": "0.25.0",
-    "@voltro/plugin-auth": "0.25.0",
-    "@voltro/plugin-broadcast": "0.25.0",
-    "@voltro/plugin-mail": "0.25.0",
-    "@voltro/plugin-storage": "0.25.0",
-    "@voltro/plugin-webhooks": "0.25.0",
-    "@voltro/protocol": "0.25.0",
-    "@voltro/runtime": "0.25.0",
-    "@voltro/serverless": "0.25.0",
-    "@voltro/workflow": "0.25.0",
+    "@voltro/ai": "0.26.0",
+    "@voltro/cache": "0.26.0",
+    "@voltro/data-transfer": "0.26.0",
+    "@voltro/database": "0.26.0",
+    "@voltro/env": "0.26.0",
+    "@voltro/kv": "0.26.0",
+    "@voltro/logger": "0.26.0",
+    "@voltro/plugin-auth": "0.26.0",
+    "@voltro/plugin-broadcast": "0.26.0",
+    "@voltro/plugin-mail": "0.26.0",
+    "@voltro/plugin-storage": "0.26.0",
+    "@voltro/plugin-webhooks": "0.26.0",
+    "@voltro/protocol": "0.26.0",
+    "@voltro/runtime": "0.26.0",
+    "@voltro/serverless": "0.26.0",
+    "@voltro/workflow": "0.26.0",
     "chokidar": "^5.0.0",
     "ioredis": "^5.11.1",
     "tinyglobby": "^0.2.17",

package/templates/agent-docs/data.md

@@ -1469,6 +1469,38 @@ Tables with the `tenant()` mixin are scoped by the runtime using `ctx.request.su
 
 The devtools subscription surfaces show active subscribers, recent deltas, and cache state. Use them when a query updates too often or not at all.
 
+## Cost — how large may a live query be?
+
+Every change re-runs the query and diffs the WHOLE result against the previous
+one, so the cost is linear in the RESULT SIZE, not in the size of the change.
+Measured on `diffRows`:
+
+| result rows | one column changed | every row replaced |
+| --- | --- | --- |
+| 50 | 45 µs | — |
+| 500 | 480 µs | — |
+| 2 000 | 1.23 ms | 1.29 ms |
+| 5 000 | 3.1 ms | — |
+
+Two things follow, and the second is the one that surprises people:
+
+- **The curve is linear, not quadratic.** Per-row cost is flat across a 100×
+  growth (910 ns → 625 ns), so a large result gets slower in proportion and
+  never falls off a cliff.
+- **A one-column edit costs the same as replacing everything.** 2 000 rows with
+  a single change is 1.23 ms; the same 2 000 rows entirely replaced is 1.29 ms —
+  5 % more. The cost is the WALK, not the delta. Making your mutation smaller
+  does not make the subscription cheaper.
+
+So the number to design against is the RESULT SIZE. A few hundred rows is free.
+A 5 000-row live query costs 3.1 ms of CPU per change, per replica — fine for a
+dashboard that changes a few times a minute, wrong for one fed by a high-rate
+writer. Page the query, or narrow it with a predicate, rather than reaching for
+a bigger machine.
+
+These numbers are asserted by `rowPatch.perf.test.ts`, so they are current
+rather than a note somebody wrote down once.
+
 ## See also
 
 - [Subscribers (`*.subscribe.ts`)](/docs/data/subscribers) — server-side, best-effort post-commit reactivity to a table (NOT the client hook on this page).
@@ -1693,7 +1725,8 @@ Everything you would otherwise hand-roll is gone, and each of these was a real b
 
 - **At-most-once, best-effort, live.** No persistence, no retry, no redelivery. For guarantees use the [outbox](/docs/data/outbox); this is the other axis.
 - **Ordered per publishing instance per key.** *Not* globally per key — two instances publishing the same key have no shared counter, and we do not promise an order we cannot keep.
-- **Guards are re-checked when the subject changes**, not per delivery. Revoke a role and the stream ends.
+- **Guards are re-checked on EVERY delivery**, exactly as a live query's are. A resource-scoped guard (`{ scope: 'arena:read', from: 'arenaId' }`) runs its resolver each time, so un-sharing a resource or ending a membership stops the stream at the next delivery — the client is told, not silently skipped. What this does *not* catch is a ROLE revoked on the subject itself: those scopes were captured when the subscription opened. That half is covered by the credential bound below.
+- **A subscription cannot outlive the credential that authorized it.** When the session carries an expiry, the stream ends at it — and `useEvent` reconnects immediately, which is a NEW request, so the subject is resolved afresh and the guards run again for real. Still entitled: it continues and your app sees nothing. No longer entitled: the reconnect is refused, loudly. You write no reconnect handling for this; it is the existing retry doing its job. Note the limit precisely — this bounds EXPIRY, not revocation.
 - **Payloads are capped at 7,500 bytes** of encoded envelope, on **every** dialect. An event says something happened, so carry a photo *reference*, not a photo.
 
 ### `missed` is a number, not a feeling
@@ -1742,7 +1775,7 @@ export const orderPaid = defineEvent({
 
 One `publish` now reaches connected clients, every matching workflow trigger, and every subscribed HTTP target. Without this an app that does both declares the thing twice, in two shapes, and the two drift.
 
-The `webhook:` block is namespaced because its settings mean nothing to the other audiences — a top-level `retry` would read as if it applied to client delivery, which is at-most-once by design and has no retry at all. Requires [`@voltro/plugin-webhooks`](/docs/plugins/webhooks); absent, it costs nothing.
+The `webhook:` block is namespaced because its settings mean nothing to the other audiences — a top-level `rateLimit` would read as if it throttled client delivery, which it does not — it is a ceiling on webhook deliveries only. Requires [`@voltro/plugin-webhooks`](/docs/plugins/webhooks); absent, it costs nothing.
 
 ## Across instances
 

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

package/templates/agent-docs/deployment.md

@@ -1150,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
@@ -1163,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

@@ -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/whats-new.md

@@ -266,6 +266,13 @@ BREAKING entries name a codemod; run `voltro update` to apply it.
 
 ### Fixed
 
+- **@voltro/runtime** — **A change watched by N identical live subscribers cost N reads and N diffs. It now costs one of each.** Fifty screens open on the same list re-ran the same query fifty times per change and recomputed the same delta fifty times — in memory that is wasted CPU; against SQL it is fifty round trips.
+
+  `diffRows` costs the WALK, not the delta: ~31µs at 50 rows, ~289µs at 500, ~3.1ms at 5000, and one changed row costs what zero does. So on a large list the diff share is worth as much as the read share.
+
+  Both are keyed by the resolved read descriptor; the diff share additionally keys on the previous rows' OBJECT IDENTITY. That second half is a safety property rather than an optimisation: a patch computed against another subscriber's base silently corrupts its rows, and it is the one failure on this path that neither a test nor a log would catch. Reference identity cannot be wrong about it — two subscribers share only when they hold the literally same array, which is exactly when the read share already served them together. A late joiner holds a different object and gets its own diff.
+
+  Recorded because the route was not straight, and the wrong turns are the instructive part. The read memo was removed mid-release as dead code on a measurement that was broken: `handleChange` is dispatched with `void`, so the counter was sampled before the reads had landed, and the "1.00 reads" that condemned it was an artefact of the sampling. The diff share was separately shipped once with a test that could not prove it — counting deliveries, which happen either way, stays green with the share disabled — and was removed for that reason before being rebuilt. The proof needs no mocks: a shared diff is the SAME OBJECT in every delivery, so counting distinct patch identities is exact, and disabling reuse turns one shared patch into fifty.
 - **@voltro/cli** — **The domain-event audit tables are bounded now.** `ctx.events.emit(...)` writes one row to `_voltro_workflow_events` plus **one per matching trigger** to `_voltro_workflow_event_deliveries`, and nothing in the framework ever deleted from either. Both are registered with the boot retention GC on a 30-day default, env-tunable via `VOLTRO_WORKFLOW_EVENTS_TTL_HOURS` and `VOLTRO_WORKFLOW_EVENT_DELIVERIES_TTL_HOURS`.
 
   Same family as `_voltro_schedule_claims`, whose sweep landed one release ago after a consumer measured 35,128 rows in 14 days. The comment there already named the pattern — *"the one table of this family with no sweep"* — and two more members of the family were sitting next to it. The delivery log is the faster half: three triggers on one event write four rows per emit.
@@ -359,6 +366,13 @@ BREAKING entries name a codemod; run `voltro update` to apply it.
   It needs no cluster coordination, and that is a consequence of the design rather than a shortcut: the table version had shared rows, so one replica had to evict them or they would fight. Owner-partitioned presence has no shared state, so every replica sweeps its own and there is nothing to coordinate.
 
   Removals are ANNOUNCED — a local removal nobody broadcasts is a member every other replica keeps showing. The sweep runs at a third of the timeout, so a vanished member is gone within roughly 1.3× the window rather than up to 2×.
+- **@voltro/cli** — **`voltro build` could delete output it had just written.** The post-build orphan prune compared each file's mtime against `Date.now()` taken at build start — two different clocks. Linux stamps inode times from a COARSE clock (`ktime_get_coarse_real_ts64`) that advances once per timer tick, so a file written microseconds AFTER the cutoff can carry an mtime a tick BEFORE it, and the strict comparison then removed it.
+
+  The consequence is the exact failure the prune was designed to avoid: a bundle that is missing pieces mid-run. The wipe-before-build version had the same effect for a different reason, and this reintroduced it in a narrower window.
+
+  The comparison now carries a one-second tolerance. The two directions are not symmetric — too small deletes a fresh artefact, too large lets an orphan survive until the next prune — so the margin sits on the side of keeping. Real orphans are minutes or builds old.
+
+  Found by the release gate on Linux, where the suite's own concurrency case failed while asserting a precondition that held: the file it checked was fine, a different one was pruned. It had never failed on macOS, whose timestamp granularity differs. The suite now pins the tolerance directly — a file stamped just before the cutoff must survive, and one past the tolerance must still go, so the margin cannot quietly widen into a no-op.
 - **@voltro/cli** — **A `source:` that names no table is now reported at boot.** It was silent, and the silence is the defect: `source` is matched BY NAME against change events, so one naming a table that does not exist matches nothing — the query returns its first result and never updates again. Not a broken subscription, a permanently silent one, which from the outside is indistinguishable from "nothing has changed".
 
   ```text
@@ -407,8 +421,10 @@ BREAKING entries name a codemod; run `voltro update` to apply it.
   An `armed` step now sits between `step1` and the nap, and the teardown waits for it. `activityExecute` returns only once a step's result is durably recorded — that is what lets replay skip it, and what the idempotency-key scenario in the same suite already depends on — so `armed` starting IS the journal write having landed. No duration is left in that path.
 
   Distinct from the ceiling raises around it, which address a resumed run needing longer than the timeout under load. This one is not a timeout: no amount of waiting turns a re-executed step back into a skipped one.
-- **@voltro/runtime** — A note in `Dispatcher` recording a removed optimisation and where the cost actually is. Comment only — no behaviour, no API.
+- **@voltro/cli** — The dev-SSR streaming tests defined "the shell" as *every chunk that arrived before 0.6 × the deferral delay* — an assertion about the machine wearing the shape of an assertion about the renderer. Under a loaded CI runner the shell lands after that deadline, the derived `shell` string comes out EMPTY, and the failure reads `Expected SHELL_LAYOUT_EAGER_OK`, as though the renderer had dropped a field. Green on every developer machine.
+
+  The shell is now everything BEFORE the chunk carrying the deferred value, and the claim the first-byte deadline was reaching for is stated as what it actually is: the eager field's chunk index is strictly lower than the deferred value's. No duration remains in that path. The one clock that stays is the lower bound on WHEN the deferred value arrived — a slower machine only makes that more true.
 
-  A per-dispatch read memo had been added on the theory that N subscribers cost N identical queries. They do not: `SubscriptionRegistry` keys by `fingerprintFor(table, predicate, indexHint)`, so identical subscriptions already collapse to one entry and one read. The memo was dead code, and what exposed it was that removing it left its own test green.
+  It still fails a buffered implementation, which is the point of the suite: one chunk means the deferred index is 0, the shell is empty, and the eager-field assertion fails.
 
-  The measured linear cost (254µs / 1.1ms / 2.5ms per change at 1 / 10 / 50 subscribers) is therefore the per-subscriber work AFTER the read — the deep-equal diff, the patch, the emit — which is where the next attempt should look.
+  **Found because a red suite had been reporting green.** CI's test step ends in `| tee`, and GitHub's default `run` shell is `bash -e` — *without* `pipefail` — so the step's exit status was tee's. `@voltro/cli#test` failed, turbo exited 1, and the step reported SUCCESS; the comment above it asserted pipefail was on. It surfaced only because the failing package died before printing its summary, which tripped the undeclared-skip check further down. One line later and the gate would have gone green on a failing test. The workflow now sets `defaults.run.shell: bash` so no future piped step can reintroduce it.

package/templates/agent-docs/workflows.md

@@ -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_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
 ```

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.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",
+    "@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.25.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.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",
+    "@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.25.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.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/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.25.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.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",
+    "@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.25.0",
+    "@voltro/testing": "0.26.0",
     "typescript": "^6.0.3",
     "vitest": "^4.1.10"
   }