@voltro/cli 0.33.0 → 0.35.0

package/templates/agent-docs/workflows.md

@@ -350,7 +350,9 @@ export const ImportCustomers = workflow({
 })
 ```
 
-`payload` is the start input. `success` is the resolved output. `error` is the typed failure channel. `idempotencyKey` deduplicates concurrent or repeated starts with the same logical input. `messages` is optional codegen metadata; it emits `WorkflowSignals`, `WorkflowUpdates`, `WorkflowQueries`, and `WorkflowMessages` type maps, while runtime validation still happens at `awaitSignal(...)` / `awaitUpdate(...)`.
+`payload` is the start input. `success` is the resolved output. `error` is the typed failure channel. `idempotencyKey` deduplicates concurrent or repeated starts with the same logical input. `messages` is optional codegen metadata; it emits `WorkflowSignals`, `WorkflowUpdates`, and `WorkflowMessages` type maps, while runtime validation still happens at `awaitSignal(...)` / `awaitUpdate(...)`.
+
+There are exactly two message channels: `signals` (fire-and-forget) and `updates` (synchronous, with a result). A `queries` channel was declarable until 0.34.0 and never had a send path — nothing could invoke one — so it is gone. To read a run's state, write an ordinary `*.query.ts` over `_voltro_workflow_runs` / `_voltro_workflow_run_steps`; to ask a running workflow something and get an answer, use `updates`.
 
 ## Step boundaries
 
@@ -491,9 +493,49 @@ Parent-close policies:
 
 The dashboard shows child runs, their parent execution id, and the selected policy. `ctx.workflows.wait(child)` accepts the run handle directly when the parent needs the child's success/failure snapshot.
 
+## Running on a cron — `workflow({ schedule })`
+
+A workflow whose only trigger is a clock can declare the cron on itself, instead of a separate `*.cron.tsx` file with a `workflow:` target:
+
+```tsx
+export default workflow({
+  name: 'reports.nightly',
+  payload: Schema.Struct({ day: Schema.String }),
+  idempotencyKey: (p) => `nightly:${p.day}`,
+  schedule: {
+    cron: '0 3 * * *',
+    timezone: 'Europe/Berlin',
+    payload: ({ scheduledAt }) => ({ day: scheduledAt.toISOString().slice(0, 10) }),
+    onOverlap: 'skip',
+  },
+})
+```
+
+This is sugar, not a second scheduler: at boot it lowers into a real schedule named `workflow:<name>` on the same coordinated cron engine every `defineSchedule` uses — same exactly-once claims, same run rows, same Schedules panel, same `voltro schedule run` / `backfill` verbs.
+
+What the declaration adds is overlap vocabulary **about the workflow run** (Temporal Schedules' names):
+
+- `onOverlap: 'skip'` *(default)* — a firing stands down while the previous firing's **run** is still going.
+- `'buffer'` — firings serialize behind the running one; none is lost.
+- `'cancelOther'` — the new firing cancels the still-running previous run (only runs this schedule started — a manually-started run of the same workflow is never touched), then starts fresh.
+
+The synthesized firing **awaits the run to completion** — that is what makes `skip`/`buffer` bind on the run's duration rather than on the milliseconds it takes to enqueue one, and it is why the firing watchdog (`schedule.maxRuntime`) defaults to **24 hours** here instead of a plain schedule's 30 minutes. Set it above your slowest expected run. A failed run fails the firing, so a nightly job that dies every night is red in the schedule ledger, not a wall of green.
+
+`payload` is a value or a function of the firing — a function receives `{ scheduledAt }`, so a backfilled firing computes against **its** slot, not "now". `backfill:` and everything else about missed firings work exactly as on a plain schedule — see [Overlap & backfill](/docs/scheduling/overlap-and-backfill).
+
+If the workflow also declares a deferring control (debounce, concurrency, …), a scheduled start passes the same admission gate as any other start — a deferred firing has nothing to await and hands the run to the admission queue.
+
 ## Tenant and subject
 
-Workflow starts persist the starter subject, trace id, source, parent execution id, and parent-close policy in `_voltro_workflow_start_contexts`. Whichever runner first executes the workflow loads that context before building the executor `AppContext`.
+Workflow starts persist the starter's trace id, source, parent execution id, parent-close policy — and their **identity**, never their authority — in `_voltro_workflow_start_contexts`. Whichever runner first executes the workflow loads that context before building the executor `AppContext`.
+
+**The guarantee: identity is persisted, authority is re-resolved at resume.**
+
+- **Identity** (type, id, `tenantId`, `metadata`) is written and read through the same stripping function the session cookie mints through. It has to survive: the tenant scope reads `tenantId`, the run row is attributed to `id`, and a plugin service resolving a per-user credential reads `metadata`. A workflow started by tenant A still acts on tenant A's rows in three days' time.
+- **Authority** comes from your [`auth.resolveScopes`](/docs/authentication/strategies) on every execution attempt, with `ctx.origin === 'workflow'`. Wire no resolver and a resumed run has no scopes — fail-closed, and the same default a cookie-authenticated request has.
+- **A run with no recorded caller** — a bootstrap, or one whose row aged out — runs as `SYSTEM_SUBJECT` and is not put through your resolver.
+
+The column used to hold the whole `Subject`, scopes included. A role removed on Monday was still asserted by Thursday's resume, out of a row nothing re-validated, on a path with no request, no cookie and no expiry. Rows written by an older build are stripped on **read**, so a resumed run cannot re-assert authority that was persisted before this changed.
 
 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.
 
@@ -888,6 +930,24 @@ if (!decision.approved) {
 
 Signals are matched by name inside one workflow run. The payload is decoded with the supplied schema.
 
+### Long waits: `awaitSignalSuspending`
+
+`awaitSignal` **polls from inside a live activity** — the run keeps its worker fiber for the whole wait. Right for an approval that lands in seconds; wrong for a wait measured in hours or days, where a thousand parked runs pin a thousand fibers. For those, use the drop-in suspending variant:
+
+```tsx
+import { awaitSignalSuspending } from '@voltro/workflow'
+
+const decision = yield* awaitSignalSuspending(ctx, {
+  name: 'approval',
+  schema: Schema.Struct({ approved: Schema.Boolean }),
+  timeoutMs: 3 * 24 * 60 * 60_000,   // three days — a real human-in-the-loop wait
+})
+```
+
+Same call shape, same senders (`ctx.workflows.signal`, the dashboard button, the HTTP endpoint resume **both** variants), but the run returns `Suspended` while parked — the worker slot is freed and the wake lives in the engine's durable store, exactly like a long `sleep`. The timeout is durable too.
+
+**Rule of thumb: seconds → `awaitSignal`; anything a human might sleep on → `awaitSignalSuspending`.** The framework nudges you: an `awaitSignal` declaring a timeout above five minutes logs a one-time hint (once per workflow, never per poll) naming the suspending variant. Tune or effectively silence the threshold with `workflows: { suspendSignalHintMs }` in `app.config.ts`, or `VOLTRO_WORKFLOW_SUSPEND_HINT_MS` at runtime. It is a hint only — the framework never swaps the variant under a run, because the two journal differently and a silent swap mid-history is a replay trap dressed as a favour.
+
 ## Sending signals
 
 From the dashboard, open a running workflow and use "Send signal".
@@ -1388,6 +1448,8 @@ priority: (p) => (p.urgent ? 100 : 0)
 
 Higher runs first out of the pending queue. Ties break by arrival, so an all-default deployment is FIFO rather than dialect-dependent.
 
+> **Scope — read before porting BullMQ priority lanes.** `priority` orders **the admission queue only**: the pending rows a deferring control (debounce, batch, throttle, concurrency), a pause, or a delayed `{ at }` start has parked. A start that is admitted immediately never competes with anything — it goes straight to the engine, whatever any other start's priority says. There are no cross-workflow priority lanes, no preemption of running work, and no ordering between two starts that both found a free slot. If urgent starts must overtake normal ones, put both classes behind the same `concurrency` limit (or a shared `pool`), so every start passes through the queue that `priority` orders.
+
 ## timeouts
 
 ```ts
@@ -1509,6 +1571,28 @@ The result is per-run, not a count: `succeeded`, `failed` (with the reason for e
 
 Eligibility is fixed by the verb: a cancel acts on `running` and `suspended` runs; `replay --mode redrive` on `failed` only (redrive resumes from the step that died, which only exists for a failure); `replay --mode retry` on `failed` and `cancelled`. `--mode` has no default because the two cost very different amounts.
 
+## Delayed one-off starts — `start(..., { at })`
+
+Run this once, later — without a schedule and without a `sleep` at the top of the body:
+
+```ts
+await ctx.workflows.start('orders.remind', { orderId }, {
+  at: new Date(Date.now() + 24 * 60 * 60_000),   // tomorrow, this time
+})
+```
+
+The start is parked as a **durable row** in the same pending queue the controls above use (`mode: 'delayed'`), and the coordinated drainer fires it when `at` arrives — it survives restarts and fires on whichever replica drains, never from an in-process timer. The handle comes back `status: 'queued'` with `deferral: { mode: 'delayed', dueAt }`.
+
+Semantics worth knowing:
+
+- **`at` is an absolute instant, deliberately** — not a `delay` duration. A delay is measured "from when?" (enqueue? admission? retry?) and every queueing system answers differently; an instant has no such ambiguity and composes with the schedule/backfill surfaces, which are also instant-based. A relative delay is one line: `at: new Date(Date.now() + ms)`.
+- **At `at`, the start becomes an ordinary ARRIVAL.** Declared controls judge it as of that moment — a debounce collapses it into whatever window is open then, a rate cap can drop it (recorded, as always). `{ at }` delays the arrival; it never outranks a control.
+- An `at` in the past starts immediately — "no earlier than" is already satisfied.
+- `{ at, wait: true }` is refused: there is no result to block on for a start that exists only as a future row.
+- Each `{ at }` start is its own row. Two delayed starts never collapse into one — unlike debounce, nothing about `{ at }` says the second supersedes the first. Want collapsing? That is `debounce`, and they compose.
+
+Prefer this over `sleep` as the first step of the body when the wait precedes the work: a parked row costs one row, a sleeping run costs a durable execution the whole time.
+
 ## What a deferred start returns
 
 `start()` no longer always returns a running handle:
@@ -1565,6 +1649,18 @@ A workflow that declares one pays only for that one: an undeclared control costs
 
 The drainer runs on **one replica per tick** through the same claim arbiter the cron scheduler uses. N replicas draining at once would each see a free slot and each take it.
 
+### Measured admission throughput
+
+Measured, not estimated — `node packages/cli/scripts/admission-throughput.mjs` in the framework repo drives the real gate, facade and drainer against the in-memory reference store (slope across N=500/1000/2000 starts, median of 3 sequential repeats; Apple-silicon dev machine, 2026-08):
+
+- **no controls (passthrough): ~1 µs/start (~800,000 starts/s)** — the do-nothing path really does nothing.
+- **through a concurrency gate: ~110 µs/start (~9,000 starts/s)** — dominated by the reference store's *unindexed* admission-state scan, which grows with the ledger; a real dialect serves that read from an index, but also adds its round-trips. Read this as the machinery's worst-case CPU floor, not a database benchmark.
+- **durable park → drain → start: ~4 µs/row (~240,000 rows/s)** of pure machinery per queued row.
+
+The deployed ceiling is `min(these numbers, what your database serves for the admission reads/writes)` — on any SQL dialect the database is the bound long before the gate is. That is also why there is no key-group batching in the admission path: at ~9k gated starts/s worst-case CPU, batching would add a flush boundary to a path whose bound is elsewhere.
+
+Per **step**, the recorder adds exactly **2 fire-and-forget store writes** (insert at step start, update at settle), off the step's critical path — plus the cluster engine's own journal write, which is the durability you asked for. Hot high-step workflows can turn the introspection copy off: `workflows: { recording: 'coarse' }` — see [Debugging](/docs/workflows/debugging).
+
 
 
 ---
@@ -1572,7 +1668,7 @@ The drainer runs on **one replica per tick** through the same claim arbiter the
 <!-- source: en/workflows/versioning.md -->
 ## Versioning
 
-_Workflow definition versions, compatibility metadata, and patch markers for long-running runs._
+_Workflow definition versions, compatibility metadata, in-body patch markers, and the replay nondeterminism tripwire._
 
 Long-running workflows can outlive a deploy. Voltro does not run old JavaScript forever; a resumed run executes the current code. Make that explicit by versioning the workflow definition.
 
@@ -1595,27 +1691,71 @@ Voltro stores `workflowVersion` and `workflowPatches` on every `_voltro_workflow
 
 ## Compatibility
 
-`compatibleWith` is operator metadata. Use it to document which run versions the current code can still resume safely. If a change cannot resume old payloads or step layout, bump `version` and leave the old version out of `compatibleWith`.
+`compatibleWith` documents which run versions the current code can still resume. It is enforced: a resuming run whose stored `workflowVersion` is not listed is **terminally failed** with `WorkflowVersionIncompatible`.
 
-## Patch Markers
+That makes it a blunt instrument, and the bluntness is the point to understand before you reach for it. Bump `version` and leave the old one out, and every in-flight run on the old version dies. Do not bump, and those runs replay against the changed body with no protection at all. Neither is what you usually want — which is what `patches` is for.
 
-`patches` are named change markers. Keep them short and stable:
+## Patch markers
+
+A patch marker lets the **body itself** branch, so runs that started before a change finish on the old path while new runs take the new one. This is the middle option between "kill the in-flight runs" and "hope the replay works out".
 
 ```ts
-patches: [
-  'split-validate-and-write',
-  'rename-export-step',
-]
+import { patch, step, workflow } from '@voltro/workflow'
+
+export const Charge = workflow({
+  name: 'billing.charge',
+  payload: { orderId: Schema.String },
+  idempotencyKey: ({ orderId }) => `billing.charge:${orderId}`,
+  patches: ['split-tax-calculation'],
+})
+
+export default () => (payload) =>
+  Effect.gen(function* () {
+    if (yield* patch('split-tax-calculation')) {
+      const net = yield* step({ name: 'net-total', execute: computeNet(payload) })
+      const tax = yield* step({ name: 'tax', execute: computeTax(payload) })
+      return net + tax
+    }
+    return yield* step({ name: 'total', execute: computeTotal(payload) })
+  })
 ```
 
-Patch markers are recorded with the run. They make deploy review and dashboard triage concrete: you can answer which branching changes were active when the run started.
+The answer is pinned to the **run**, not to the deployed code. `patches` is stamped onto `_voltro_workflow_runs.workflowPatches` when the run starts and read back from that row on every resume, so:
+
+- a run started **before** you added the marker answers `false` for the rest of its life, however many times it replays;
+- a run started **after** answers `true`, and keeps answering `true` even if you later change the declaration.
+
+That is what makes the branch deterministic across a redeploy. Outside a recorded workflow body — a unit test, a bare `step()` call — `patch()` is `false`, which is the pre-patch path.
+
+### Retiring a patch
+
+Once no run predating the marker can still be in flight, delete the old branch and remove the entry from `patches`. Runs that stamped it keep the marker on their row for the audit trail; `patch()` simply stops being called.
+
+## The replay nondeterminism tripwire
+
+Journal entries are keyed by step **name**, with no shape check. Edit a workflow body while runs are in flight and the engine replays the cached result for every name that still matches and freshly executes every name that does not. Nothing errors. A renamed step re-runs a side effect the run already performed; a removed step silently skips work the journal says was done.
+
+Voltro watches for that. A run re-entering its body compares the steps it **reaches** against the steps it recorded on earlier attempts, and writes a `nondeterminism-suspected` event when they disagree:
+
+| Finding | Means |
+|---|---|
+| `unreached-step` | A step this run ran on an earlier attempt that the current code never reaches — renamed, removed, or moved behind a branch. Its journaled result is orphaned. |
+| `extra-step-occurrence` | A recorded step reached more times than it was ever recorded — typically a loop bound that changed under a live run. |
+
+The comparison is set membership plus a per-name count, never a total order: concurrent steps interleave differently on every attempt, so an order check would report correct code as broken.
+
+**It is an event, never a failure.** The run keeps going and reaches its normal outcome. The checks sit on a best-effort recorder, so a lost step-row write is enough to make one fire — a false positive that killed a run would be worse than the divergence it suspects. Treat the event as "open this run and look", not as an outage.
+
+The tripwire covers every path that replays an existing journal, including `voltro workflows redrive`. It is off on a first body entry (there is nothing to compare) and on a run with more than `VOLTRO_WORKFLOW_REPLAY_SHAPE_LIMIT` recorded steps (default 2000), where a truncated history would manufacture its own false positives.
 
 ## Rules
 
-- Bump `version` for payload shape changes, step-order changes that affect replay, or changed external side-effect semantics.
+- Bump `version` only when old runs genuinely cannot continue — it kills them.
+- Reach for `patches` first for a body change that in-flight runs should not see.
 - Keep old payload decoders inside the workflow body only while their version remains compatible.
 - Prefer additive payload changes with defaults over breaking changes.
 - Use the dashboard version chip during deploys to find runs that started on an older contract.
+- Treat a `nondeterminism-suspected` event as a deploy that needed a patch marker and did not get one.
 
 
 
@@ -1633,14 +1773,29 @@ Voltro records workflow runs, step attempts, and lifecycle events into framework
 | Table | Contents |
 |---|---|
 | `_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_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, plus the crash-loop bookkeeping `runnerEnteredAt` + `reclaimCount`. |
 | `_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-redriven`, `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`, `nondeterminism-suspected`, `run-crashlooped`, `run-stalled`. |
 | `_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`.
 
+### Turning the step rows off — `workflows.recording: 'coarse'`
+
+Every `step()` costs two fire-and-forget writes to `_voltro_workflow_run_steps` (insert at start, update at settle) — measured, and off the step's critical path, but on a hot workflow with many steps they dominate the table's growth. `'coarse'` skips **both**:
+
+```ts
+// app.config.ts
+export default {
+  workflows: { recording: 'coarse' },   // default: 'full'
+}
+```
+
+Runtime override without a rebuild: `VOLTRO_WORKFLOW_RECORDING=coarse` (env wins over config; anything unrecognised falls back to `'full'`).
+
+What `'coarse'` does **not** touch, deliberately: run rows, run events (signals, timers, cancels, stall reports — everything the dead-letter view and the sweeps read), and the cluster engine's own durable journal — replay and redrive are unaffected. The cost is exactly the dashboard's step timeline: empty for runs recorded under `'coarse'`. Flip it back when you need to see inside a run.
+
 ## 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.
@@ -1651,6 +1806,68 @@ Triage a dead-letter run one of three ways:
 - **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.
 
+## Stuck runs and crash loops
+
+Three failure modes are detected rather than left for whoever opens the dashboard.
+
+**A run that stops moving.** A staleness sweep reports live runs (`running` or `suspended`) that have made no progress for longer than the threshold — default 30 minutes — writing a `run-stalled` event carrying `idleMs`, the reason (`awaiting-signal`, `suspended`, `no-progress`) and the last progress instant. It changes no run state; it is a signal, not an intervention. The classic catch is a run parked on a signal nobody ever sends.
+
+Two things it deliberately stays quiet about, because otherwise the signal is worthless:
+
+- A run inside a durable `sleep` / `sleepUntil` whose wake instant is still in the future. That run is waiting by design, and a seven-day timer is not a stall.
+- A run already reported since its last progress. A stall is reported once and again only after the run moves and stalls afresh.
+
+Configure it in `app.config.ts` — every field optional:
+
+```ts
+export default defineApiApp({
+  workflows: {
+    staleness: {
+      // Set this above your slowest single STEP, not above your longest RUN:
+      // a run waiting on a durable timer is already excluded. Default 30 min.
+      stallAfterMs: 30 * 60_000,
+      runPage: 200,                       // live runs examined per tick, oldest first
+      onStalled: async (run) => {
+        await page(`${run.tag} ${run.runId} idle ${run.idleMs}ms (${run.reason})`)
+      },
+    },
+  },
+  // How often the sweep looks. `VOLTRO_STALENESS_SWEEP_MS` overrides it.
+  scheduling: { stalenessSweepMs: 5 * 60_000 },
+})
+```
+
+`onStalled` must not throw — a rejection is collected and reported, so one bad
+pager integration cannot stop detection for every other workflow.
+
+The sweep runs on a **coordinated** schedule, so one firing per interval
+fleet-wide rather than one per replica. Unlike every other framework background
+task it **never stops ticking when idle**: those disarm because an arrival wakes
+them, and a run going stale writes nothing there is to wake on. That makes the
+cadence an unconditional cost, which is why it defaults to five minutes rather
+than one second — on a thirty-minute threshold that is 12 coordination rows an
+hour instead of 3 600.
+
+`voltro doctor` runs the same detection **once**, for the moment you are standing
+in front of a deployment asking whether anything is wedged:
+
+```
+✗  stuck runs: 2 run(s) have made no progress
+   invoices.settle  wr_01J…  idle 4h  awaiting-signal
+   report.nightly   wr_01J…  idle 2h  no-progress
+   Nothing was changed — this is a SUSPICION, not a verdict. `awaiting-signal`
+   usually means the sender never came.
+```
+
+It is the one doctor rule that reads your DATABASE rather than your source, so
+run it where the app's DB env vars are set; anywhere else it prints a named skip
+rather than a clean tick. It records nothing and calls no `onStalled`, so running
+it neither pages anyone nor suppresses the background sweep's next real report.
+
+**A run that keeps killing its runner.** A step that crashes the process — OOM, a native crash — cannot be caught as an error: the shard lease expires, a surviving replica claims it, and executes the same payload. Without a ceiling that rotates around the fleet forever. Voltro counts consecutive runner deaths on the run row (`runnerEnteredAt` is set on every body entry and cleared on every clean exit; `reclaimCount` counts entries that found the previous marker still set). At `VOLTRO_WORKFLOW_MAX_RECLAIMS` (default 3) the run is parked as `suspended` with `errorTag: 'WorkflowCrashLooped'` and a `run-crashlooped` event, and the body is not entered again. The counter is consecutive — any clean re-entry resets it — so a long-lived healthy run is never parked for a crash it had months ago, and an operator resume gives it a fresh budget.
+
+**A run replaying against edited code.** See [Versioning](/docs/workflows/versioning) for the `nondeterminism-suspected` event.
+
 ## 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:

package/templates/apps/api-ai/actions/summarize.action.ts

@@ -25,6 +25,17 @@ export type SummaryResult = Schema.Schema.Type<typeof SummaryResult>
 
 export const summarize = defineAction({
   name:  'support.summarize',
+  // Summarises the `text` the caller passed in this same call — it reads no
+  // table, no other caller's data, and never returns the provider key. No
+  // identity ships with this template (no auth strategy, no rbac), so a scope
+  // guard here would deny every caller.
+  //
+  // What this does NOT say is "harmless": it spends provider tokens per call,
+  // so before it faces the internet put `@voltro/plugin-ratelimit` in front of
+  // it and swap this line for a `guards:` once your app has a caller to name.
+  openAccess:
+    'summarises caller-supplied text; reads no table and no other caller\'s data. '
+    + 'Metered by the AI provider, so rate-limit and guard it before it is public.',
   input: Schema.Struct({
     // The raw text to summarise (a support thread, a doc, a transcript).
     text: Schema.String,

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

@@ -12,17 +12,18 @@
   "dependencies": {
     "@effect/platform": "^0.97.0",
     "@effect/rpc": "^0.76.0",
-    "@voltro/ai": "0.33.0",
-    "@voltro/cli": "0.33.0",
-    "@voltro/database": "0.33.0",
-    "@voltro/env": "0.33.0",
-    "@voltro/protocol": "0.33.0",
-    "@voltro/runtime": "0.33.0",
+    "@voltro/ai": "0.35.0",
+    "@voltro/cli": "0.35.0",
+    "@voltro/database": "0.35.0",
+    "@voltro/env": "0.35.0",
+    "@voltro/protocol": "0.35.0",
+    "@voltro/runtime": "0.35.0",
     "effect": "^3.22.0"
   },
   "devDependencies": {
-    "@voltro/testing": "0.33.0",
+    "@voltro/testing": "0.35.0",
     "typescript": "^6.0.3",
+    "@vitest/coverage-v8": "^4.1.10",
     "vitest": "^4.1.10"
   }
 }

package/templates/apps/api-auth/actions/me.action.ts

@@ -8,6 +8,19 @@ import { Schema } from 'effect'
 
 export const me = defineAction({
   name:  'session.me',
+  // Open ON PURPOSE, and it is the one procedure in an authenticated app that
+  // has to be: it answers "who am I", and the caller who most needs an answer
+  // is the one who is nobody yet. A guard here would return `ScopeError` to an
+  // anonymous browser instead of `{ type: 'anonymous' }`, and the sign-in
+  // redirect has nothing to branch on.
+  //
+  // Safe because the answer is a projection of the caller's OWN request: the
+  // Subject `voltroPasswordStrategy` resolved from the cookie they sent. It
+  // reads no table and can say nothing about anybody else.
+  openAccess:
+    'echoes the caller\'s own resolved Subject (type/id/tenantId) — reads no table and '
+    + 'reveals nothing the caller did not present. Anonymous callers must reach it, or '
+    + 'nothing can tell them to sign in.',
   input: Schema.Struct({}),
   output: Schema.Struct({
     // 'anonymous' | 'user' | 'apiKey' | 'serviceAccount'

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

@@ -13,18 +13,19 @@
   "dependencies": {
     "@effect/platform": "^0.97.0",
     "@effect/rpc": "^0.76.0",
-    "@voltro/cli": "0.33.0",
-    "@voltro/database": "0.33.0",
-    "@voltro/env": "0.33.0",
-    "@voltro/plugin-auth": "0.33.0",
-    "@voltro/protocol": "0.33.0",
-    "@voltro/runtime": "0.33.0",
-    "@voltro/sql-postgres": "0.33.0",
+    "@voltro/cli": "0.35.0",
+    "@voltro/database": "0.35.0",
+    "@voltro/env": "0.35.0",
+    "@voltro/plugin-auth": "0.35.0",
+    "@voltro/protocol": "0.35.0",
+    "@voltro/runtime": "0.35.0",
+    "@voltro/sql-postgres": "0.35.0",
     "effect": "^3.22.0"
   },
   "devDependencies": {
-    "@voltro/testing": "0.33.0",
+    "@voltro/testing": "0.35.0",
     "typescript": "^6.0.3",
+    "@vitest/coverage-v8": "^4.1.10",
     "vitest": "^4.1.10"
   }
 }

package/templates/apps/api-backend/mutations/notes.create.mutation.ts

@@ -9,6 +9,15 @@ import { Schema } from 'effect'
 
 export const createNote = defineMutation({
   name: 'notes.create',
+  // Open, deliberately — see `queries/notes.query.ts` for the long form. In
+  // short: `assertOwnTenant` still rejects a `tenantId` that does not match the
+  // resolved subject, but with no auth strategy configured that subject is
+  // anonymous and holds no scopes, so any `guards: [{ scope }]` would deny
+  // every caller instead of some of them.
+  openAccess:
+    'inserts a note carrying only what the caller sent, into the caller\'s own tenant '
+    + '(`assertOwnTenant` rejects a mismatch). No auth strategy ships in this template, so '
+    + 'there is no identity a scope guard could name.',
   target: {
     table: 'notes',
     op: 'insert',

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

@@ -3,27 +3,31 @@
   "version": "0.0.0",
   "private": true,
   "type": "module",
+  "exports": {
+    "./rpcGroup": "./rpcGroup.generated.ts"
+  },
   "scripts": {
     "dev": "voltro dev .",
     "lint": "voltro doctor .",
     "migrate": "voltro migrate",
     "test": "voltro test",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "voltro codegen . && tsc --noEmit"
   },
   "dependencies": {
     "@effect/platform": "^0.97.0",
     "@effect/rpc": "^0.76.0",
-    "@voltro/cli": "0.33.0",
-    "@voltro/database": "0.33.0",
-    "@voltro/env": "0.33.0",
-    "@voltro/plugin-multitenancy": "0.33.0",
-    "@voltro/protocol": "0.33.0",
-    "@voltro/runtime": "0.33.0",
+    "@voltro/cli": "0.35.0",
+    "@voltro/database": "0.35.0",
+    "@voltro/env": "0.35.0",
+    "@voltro/plugin-multitenancy": "0.35.0",
+    "@voltro/protocol": "0.35.0",
+    "@voltro/runtime": "0.35.0",
     "effect": "^3.22.0"
   },
   "devDependencies": {
-    "@voltro/testing": "0.33.0",
+    "@voltro/testing": "0.35.0",
     "typescript": "^6.0.3",
+    "@vitest/coverage-v8": "^4.1.10",
     "vitest": "^4.1.10"
   }
 }

package/templates/apps/api-backend/queries/notes.query.ts

@@ -8,13 +8,35 @@ import { Schema } from 'effect'
 
 export const listNotes = defineQuery({
   name: 'notes.list',
+  // Every wire-exposed procedure must declare an access decision — `guards:` or
+  // `openAccess:` — or the app refuses to boot (`security.defaultDeny`). This
+  // one is open, and the reason says what that buys and what it does not:
+  //
+  // `tenant()` confines the result to the tenantId on the request and re-checks
+  // it on every delivery, so one tenant's rows never reach another's
+  // subscription. But this template configures NO auth strategy, so that
+  // tenantId comes from the caller's own `x-tenant` header — it shapes the
+  // result, it does not authorize the caller. A `guards: [{ scope }]` here
+  // would be unsatisfiable: with no auth strategy and no rbac, every caller
+  // resolves to an anonymous Subject that holds no scopes, so the guard would
+  // deny 100% of traffic. That is not strict security, it is an outage.
+  //
+  // So: add an auth strategy (see the `api-auth` template) FIRST, then swap
+  // this line for a `guards:` in the same change — at that point `tenant()`
+  // becomes real isolation because the tenant comes from a verified session.
+  openAccess:
+    'lists notes for the request\'s tenant only (`tenant()` scopes every delivery). No auth '
+    + 'strategy ships in this template, so that tenant comes from the caller\'s own `x-tenant` '
+    + 'header — result shaping, not access control. Add a strategy, then a `guards:`.',
   input: Schema.Struct({}),
-  output: Schema.Struct({
-    id: Schema.String,
-    title: Schema.String,
-    body: Schema.String,
-    done: Schema.Boolean,
-    tenantId: Schema.String,
-    createdAt: Schema.Date,
-  }),
+  output: Schema.Array(
+    Schema.Struct({
+      id: Schema.String,
+      title: Schema.String,
+      body: Schema.String,
+      done: Schema.Boolean,
+      tenantId: Schema.String,
+      createdAt: Schema.Date,
+    }),
+  ),
 })

package/templates/apps/api-backend-deactivation/actions/users.get.action.ts

@@ -8,6 +8,20 @@ import { Schema } from 'effect'
 
 export const getUser = defineAction({
   name: 'users.get',
+  // Reads one `users` row by id and returns its email — so read the reason
+  // literally, not as a shrug. `users` carries `deactivation()` and NOT
+  // `tenant()`, so nothing scopes this read to a caller. It is open because the
+  // whole table is this demo's own output: the template ships no seed and
+  // `users.create` below is the only writer, both on the same unauthenticated
+  // surface. There is no third party's address in here to leak.
+  //
+  // The moment you point this at real accounts that stops being true. Wire an
+  // auth strategy (see `api-auth`) and replace this line with
+  // `guards: [{ scope: 'users:read' }]` in the same change.
+  openAccess:
+    'reads one row of this demo\'s own `users` table by id; the table has no seed and no '
+    + 'writer but `users.create` on this same open surface, so it holds no third party\'s data. '
+    + 'Guard it before real accounts land here.',
   input: Schema.Struct({ id: Schema.String }),
   output: Schema.NullOr(Schema.Struct({
     id: Schema.String,

package/templates/apps/api-backend-deactivation/mutations/users.create.mutation.ts

@@ -4,6 +4,14 @@ import { Schema } from 'effect'
 export const createUser = defineMutation({
   name: 'users.create',
   target: { table: 'users', op: 'insert' },
+  // Writes exactly the email + name the caller passed, into this template's own
+  // `users` demo table, and echoes them back. It reads nothing and can reach no
+  // existing row (`email` is `.unique()`, so a duplicate fails rather than
+  // overwriting). No identity ships with this template, so a scope guard would
+  // deny every caller.
+  openAccess:
+    'inserts only the fields the caller supplied into the demo `users` table and echoes them '
+    + 'back; reads nothing and cannot modify an existing row (`email` is unique).',
   input: Schema.Struct({
     email: Schema.NonEmptyString,
     name: Schema.String,

package/templates/apps/api-backend-deactivation/mutations/users.deactivate.mutation.ts

@@ -9,6 +9,16 @@ import { Schema } from 'effect'
 export const deactivateUser = defineMutation({
   name: 'users.deactivate',
   target: { table: 'users', op: 'update' },
+  // Stamps `deactivatedAt` on a caller-named row. Open only because the table
+  // is this demo's own output (no seed, one writer, no tenant scope) — the
+  // decision itself is "anyone may lock anyone out", which is precisely the
+  // shape you must NOT ship. This is the first procedure in this template to
+  // grow a `guards: [{ scope: 'users:admin' }]` once an auth strategy gives you
+  // a caller to name.
+  openAccess:
+    'flips `deactivatedAt` on a caller-named row of the demo `users` table — reversible, and '
+    + 'the table holds only rows this same open surface created. An account-locking action: '
+    + 'guard it in the same change that adds authentication.',
   input: Schema.Struct({ id: Schema.String }),
   output: Schema.Struct({
     id: Schema.String,

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

@@ -13,17 +13,18 @@
   "dependencies": {
     "@effect/platform": "^0.97.0",
     "@effect/rpc": "^0.76.0",
-    "@voltro/cli": "0.33.0",
-    "@voltro/database": "0.33.0",
-    "@voltro/env": "0.33.0",
-    "@voltro/plugin-deactivation": "0.33.0",
-    "@voltro/protocol": "0.33.0",
-    "@voltro/runtime": "0.33.0",
+    "@voltro/cli": "0.35.0",
+    "@voltro/database": "0.35.0",
+    "@voltro/env": "0.35.0",
+    "@voltro/plugin-deactivation": "0.35.0",
+    "@voltro/protocol": "0.35.0",
+    "@voltro/runtime": "0.35.0",
     "effect": "^3.22.0"
   },
   "devDependencies": {
-    "@voltro/testing": "0.33.0",
+    "@voltro/testing": "0.35.0",
     "typescript": "^6.0.3",
+    "@vitest/coverage-v8": "^4.1.10",
     "vitest": "^4.1.10"
   }
 }