@voltro/cli 0.33.0 → 0.34.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
 
@@ -493,7 +495,15 @@ The dashboard shows child runs, their parent execution id, and the selected poli
 
 ## 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.
 
@@ -1572,7 +1582,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 +1605,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`.
+
+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.
 
-## Patch Markers
+## Patch markers
 
-`patches` are named change markers. Keep them short and stable:
+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,9 +1687,9 @@ 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. |
 
@@ -1651,6 +1705,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.34.0",
+    "@voltro/cli": "0.34.0",
+    "@voltro/database": "0.34.0",
+    "@voltro/env": "0.34.0",
+    "@voltro/protocol": "0.34.0",
+    "@voltro/runtime": "0.34.0",
     "effect": "^3.22.0"
   },
   "devDependencies": {
-    "@voltro/testing": "0.33.0",
+    "@voltro/testing": "0.34.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.34.0",
+    "@voltro/database": "0.34.0",
+    "@voltro/env": "0.34.0",
+    "@voltro/plugin-auth": "0.34.0",
+    "@voltro/protocol": "0.34.0",
+    "@voltro/runtime": "0.34.0",
+    "@voltro/sql-postgres": "0.34.0",
     "effect": "^3.22.0"
   },
   "devDependencies": {
-    "@voltro/testing": "0.33.0",
+    "@voltro/testing": "0.34.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.34.0",
+    "@voltro/database": "0.34.0",
+    "@voltro/env": "0.34.0",
+    "@voltro/plugin-multitenancy": "0.34.0",
+    "@voltro/protocol": "0.34.0",
+    "@voltro/runtime": "0.34.0",
     "effect": "^3.22.0"
   },
   "devDependencies": {
-    "@voltro/testing": "0.33.0",
+    "@voltro/testing": "0.34.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.34.0",
+    "@voltro/database": "0.34.0",
+    "@voltro/env": "0.34.0",
+    "@voltro/plugin-deactivation": "0.34.0",
+    "@voltro/protocol": "0.34.0",
+    "@voltro/runtime": "0.34.0",
     "effect": "^3.22.0"
   },
   "devDependencies": {
-    "@voltro/testing": "0.33.0",
+    "@voltro/testing": "0.34.0",
     "typescript": "^6.0.3",
+    "@vitest/coverage-v8": "^4.1.10",
     "vitest": "^4.1.10"
   }
 }

package/templates/apps/api-backend-mail/actions/sendWelcome.action.ts

@@ -10,6 +10,23 @@ import { defineAction } from '@voltro/protocol'
 
 export const sendWelcome = defineAction({
   name: 'mail.sendWelcome',
+  // Read this one carefully before copying it. Sending THIS APP'S branded mail
+  // to a caller-supplied address is one of the few things a tenant boundary
+  // does not bound — the recipient is an arbitrary third party, not a row.
+  //
+  // It is open here for exactly two reasons, both checkable in this repo:
+  // `provider: 'console'` in app.config.ts means nothing leaves the process
+  // (the send is logged and captured in the dev outbox), and no auth strategy
+  // ships in this template, so a `guards: [{ scope: 'mail:send' }]` would deny
+  // every caller rather than the wrong ones.
+  //
+  // The moment you swap in `resend` / `postmark` / `sendgrid` / `smtp`, this
+  // becomes an open relay for your own domain's reputation. Add an auth
+  // strategy and that `mail:send` guard in the SAME change.
+  openAccess:
+    'sends the `welcome` template to a caller-supplied address via the `console` provider — '
+    + 'nothing leaves the process, it is logged and captured in the dev outbox. Switching to a '
+    + 'real provider makes this an open relay: add an auth strategy and a `mail:send` guard first.',
   input: Schema.Struct({
     email: Schema.String,
     name: Schema.String,

package/templates/apps/api-backend-mail/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-mail/package.json

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

package/templates/apps/api-backend-mail/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-mariadb/.env.example

@@ -1,5 +1,19 @@
 # {{capProjectName}} — MariaDB backend env. Copy to `.env` and adjust.
 
+# ── Environment ────────────────────────────────────────────────────────
+#
+# DECLARE IT. Every `voltro db …` / `voltro migrate` invocation resolves an
+# UNSET `NODE_ENV` to `production` — the same way `voltro serve` and `voltro
+# start` do — so a bare `pnpm migrate` with no NODE_ENV refuses rather than
+# applying an un-reviewed diff to what might be a production database. It also
+# decides which `_voltro_*` bookkeeping tables the command declares, and a
+# migration command that resolves it differently from the serving process
+# declares a DIFFERENT schema.
+#
+# `voltro dev` declares `development` for itself and needs nothing from here;
+# this line is what makes the explicit schema commands work locally.
+NODE_ENV=development
+
 # ── Database (MariaDB + binlog CDC) ────────────────────────────────────
 DB_DIALECT=mariadb
 DB_URL=mysql://app:app@localhost:3307/{{projectNameSnake}}