@voltro/cli 0.1.4 → 0.1.6

package/dist/dev-BjylpfGQ.js

@@ -0,0 +1,2 @@
+import { o as e } from "./dev-BhBMpHkm.js";
+export { e as loadApiConfig };

package/dist/index.js

@@ -1,4 +1,4 @@
-import { i as e, n as t, r as n, t as r } from "./commands-dErOyJ0j.js";
+import { i as e, n as t, r as n, t as r } from "./commands-CN-DLT1Q.js";
 //#region src/index.ts
 var i = "framework";
 //#endregion

package/dist/startup.js

@@ -1,2 +1,2 @@
-import { n as e, t } from "./startupRunner-CRhuUl91.js";
+import { n as e, t } from "./startupRunner-DAexyPkM.js";
 export { t as loadStartupFiles, e as runStartups };

package/dist/{startupRunner-CRhuUl91.js → startupRunner-DAexyPkM.js}

@@ -1,30 +1,32 @@
 import { basename as e } from "node:path";
 import { pathToFileURL as t } from "node:url";
 import { publishServerError as n } from "@voltro/protocol";
-//#region src/startupRunner.ts
-var r = (e) => e.replace(/\.startup\.tsx?$/, ""), i = async (n, i) => {
-	let a = [];
-	for (let o of n) {
-		let n;
+//#region src/appModuleLoader.ts
+var r = /* @__PURE__ */ new Map(), i = (e) => {
+	for (let [t, n] of Object.entries(e)) r.set(t, n);
+}, a = async (e) => r.get(e) || await import(t(e).href), o = (e) => e.replace(/\.startup\.tsx?$/, ""), s = async (t, n) => {
+	let r = [];
+	for (let i of t) {
+		let t;
 		try {
-			n = await import(t(o).href);
+			t = await a(i);
 		} catch (e) {
-			i.warn("startup: failed to import", { file: o }, e);
+			n.warn("startup: failed to import", { file: i }, e);
 			continue;
 		}
-		let s = n.default;
+		let s = t.default;
 		if (typeof s != "function") {
-			i.warn("startup: no default-export function", { file: o });
+			n.warn("startup: no default-export function", { file: i });
 			continue;
 		}
-		a.push({
-			file: o,
-			id: r(e(o)),
+		r.push({
+			file: i,
+			id: o(e(i)),
 			fn: s
 		});
 	}
-	return a;
-}, a = async (e, t, r) => {
+	return r;
+}, c = async (e, t, r) => {
 	let i = [];
 	for (let a of e) {
 		let e = r.child(`startup:${a.id}`), o = {
@@ -68,4 +70,4 @@ var r = (e) => e.replace(/\.startup\.tsx?$/, ""), i = async (n, i) => {
 	} };
 };
 //#endregion
-export { a as n, i as t };
+export { i, c as n, a as r, s as t };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltro/cli",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "The `voltro` CLI — dev server, codegen, migrations, project scaffolding, agent-docs seeding, and production serve.",
   "keywords": [
     "voltro",
@@ -49,27 +49,27 @@
     "@effect/workflow": "^0.18.2",
     "@tailwindcss/vite": "^4.3.2",
     "@vitejs/plugin-react": "^6.0.3",
-    "@voltro/ai": "0.1.4",
-    "@voltro/cache": "0.1.4",
-    "@voltro/data-transfer": "0.1.4",
-    "@voltro/database": "0.1.4",
-    "@voltro/env": "0.1.4",
-    "@voltro/kv": "0.1.4",
-    "@voltro/logger": "0.1.4",
-    "@voltro/plugin-auth": "0.1.4",
-    "@voltro/plugin-broadcast": "0.1.4",
-    "@voltro/plugin-mail": "0.1.4",
-    "@voltro/plugin-storage": "0.1.4",
-    "@voltro/plugin-webhooks": "0.1.4",
-    "@voltro/protocol": "0.1.4",
-    "@voltro/runtime": "0.1.4",
-    "@voltro/serverless": "0.1.4",
-    "@voltro/sql-mssql": "0.1.4",
-    "@voltro/sql-mysql": "0.1.4",
-    "@voltro/sql-postgres": "0.1.4",
-    "@voltro/sql-sqlite": "0.1.4",
-    "@voltro/sql-turso": "0.1.4",
-    "@voltro/workflow": "0.1.4",
+    "@voltro/ai": "0.1.6",
+    "@voltro/cache": "0.1.6",
+    "@voltro/data-transfer": "0.1.6",
+    "@voltro/database": "0.1.6",
+    "@voltro/env": "0.1.6",
+    "@voltro/kv": "0.1.6",
+    "@voltro/logger": "0.1.6",
+    "@voltro/plugin-auth": "0.1.6",
+    "@voltro/plugin-broadcast": "0.1.6",
+    "@voltro/plugin-mail": "0.1.6",
+    "@voltro/plugin-storage": "0.1.6",
+    "@voltro/plugin-webhooks": "0.1.6",
+    "@voltro/protocol": "0.1.6",
+    "@voltro/runtime": "0.1.6",
+    "@voltro/serverless": "0.1.6",
+    "@voltro/sql-mssql": "0.1.6",
+    "@voltro/sql-mysql": "0.1.6",
+    "@voltro/sql-postgres": "0.1.6",
+    "@voltro/sql-sqlite": "0.1.6",
+    "@voltro/sql-turso": "0.1.6",
+    "@voltro/workflow": "0.1.6",
     "chokidar": "^5.0.0",
     "esbuild": "^0.28.0",
     "ioredis": "^5.11.1",

package/templates/agent-docs/ai.md

@@ -18,27 +18,27 @@ The implementation is the [Vercel AI SDK](https://sdk.vercel.ai) wrapped behind
 ## The model
 
 ```text
-                 ┌─────────────────────────────────────────┐
-                 │  Vercel AI SDK                          │
-                 │   anthropic / openai / gateway / mock    │
-                 └────────────────┬────────────────────────┘
-                                  │
-                                  ▼
-┌─────────────────────────────────────────────────────────────────┐
-│  @voltro/ai                                                      │
-│    generateText(...) / generateObject(...)                       │
-│    streamText(...)                                                │
-│    embed(...) / embedMany(...)                                    │
-└────┬─────────────────────────┬──────────────────────────────────┘
-     │                         │
-     ▼                         ▼
-┌──────────────────────────────┐   ┌──────────────────────────────────┐
-│  *.agent.tsx (descriptor)    │   │  *.tool.tsx                      │
-│   defineAgent({ name, input })│   │   defineTool({ name, input,      │
-│  *.agent.server.tsx (executor)│   │     output })                    │
-│   defineAgentExecutor(desc, { │   │   typed + wired on the executor  │
-│     system, tools, model })   │   │                                  │
-└──────────────────────────────┘   └──────────────────────────────────┘
+               ┌───────────────────────────────────────┐
+               │  Vercel AI SDK                        │
+               │   anthropic / openai / gateway / mock │
+               └───────────────────┬───────────────────┘
+                                   │
+                                   ▼
+┌──────────────────────────────────────────────────────────────────────┐
+│  @voltro/ai                                                          │
+│    generateText(...) / generateObject(...)                           │
+│    streamText(...)                                                   │
+│    embed(...) / embedMany(...)                                       │
+└────────────────┬────────────────────────────────────┬────────────────┘
+                 │                                    │
+                 ▼                                    ▼
+┌────────────────────────────────┐   ┌─────────────────────────────────┐
+│  *.agent.tsx (descriptor)      │   │  *.tool.tsx                     │
+│   defineAgent({ name, input }) │   │   defineTool({ name, input,     │
+│  *.agent.server.tsx (executor) │   │     output })                   │
+│   defineAgentExecutor(desc, {  │   │   typed + wired on the executor │
+│     system, tools, model })    │   │                                 │
+└────────────────────────────────┘   └─────────────────────────────────┘
 ```
 
 ## What's in this section

package/templates/agent-docs/authentication.md

@@ -20,18 +20,18 @@ Voltro's auth story ships as a plugin: `@voltro/plugin-auth`. It's server-side p
 ## The pieces
 
 ```text
-┌───────────────────────────────────────────────────────────────┐
-│  Browser                                                      │
-│    POST /auth/signin   ────────┐                              │
-│    Cookie: voltro:session=...  │                              │
+┌────────────────────────────────────────────────────────────────┐
+│  Browser                                                       │
+│    POST /auth/signin   ────────┐                               │
+│    Cookie: voltro:session=...  │                               │
 └───────────────────────────────┬─┘                              │
-                                │  Set-Cookie (HttpOnly, Secure)│
+                                │  Set-Cookie (HttpOnly, Secure) │
                                 ▼                                │
-┌───────────────────────────────────────────────────────────────┐
-│  api app                                                      │
+┌────────────────────────────────────────────────────────────────┐
+│  api app                                                       │
 │    handleSignIn → verifyPassword → issueSession                │
-│    readSession  → HMAC verify    → Subject                    │
-└───────────────────────────────────────────────────────────────┘
+│    readSession  → HMAC verify    → Subject                     │
+└────────────────────────────────────────────────────────────────┘
                                 ▲
                                 │  ctx.subject (typed)
                                 │

package/templates/agent-docs/cli.md

@@ -610,7 +610,7 @@ What it does for a web app:
 3. **Pre-builds the SSR bundle** — every page module compiled to `dist/server/ssrEntry.js` so `voltro start` doesn't need a Vite middleware loader at runtime.
 4. **Copies `public/`** into `dist/`.
 
-For api apps, `voltro build` bundles the discovery-walked sources + dependencies into a single Node ESM entry at `dist/api.js`. Production servers run it via `node dist/api.js`.
+For api apps, `voltro build` precompiles the whole handler closure — every procedure, workflow, subscriber, reaction, aggregate, agent, webhook, cron, startup, `app.config`, and their shared `database`/`lib` deps — into a single esbuild bundle at `.framework/dist-api/apiEntry.js` (the framework + npm deps stay external). `voltro serve` loads that bundle automatically at boot and resolves every handler from it, so production never transpiles TypeScript at runtime. Without a build, `voltro serve` still loads each source module on demand (via the `tsx` loader) exactly as `voltro dev` does — the build is an optimisation, not a requirement.
 
 `voltro build` takes a single optional app directory and parses no flags — the SSR bundle is always attempted, and the SSG pre-render always runs for `static`-mode pages.
 

package/templates/agent-docs/data.md

@@ -36,16 +36,16 @@ sandbox; it resets on refresh):
 └──────────────────────────┬───────────────────────────────────────┘
                            │  @effect/rpc over WebSocket
                            ▼
-┌──────────────────────────────────────────────────────────────────┐
-│  api app                                                         │
-│    *.query.ts    + *.query.server.ts     — reactive reads         │
-│    *.mutation.ts + *.mutation.server.ts  — transactional writes   │
-│    *.action.ts   + *.action.server.ts    — external I/O / unary   │
-│    *.stream.ts   + *.stream.server.ts    — one-shot element push  │
+┌────────────────────────────────────────────────────────────────────┐
+│  api app                                                           │
+│    *.query.ts    + *.query.server.ts     — reactive reads          │
+│    *.mutation.ts + *.mutation.server.ts  — transactional writes    │
+│    *.action.ts   + *.action.server.ts    — external I/O / unary    │
+│    *.stream.ts   + *.stream.server.ts    — one-shot element push   │
 │    *.route.tsx                            — public raw-HTTP route  │
 │    *.workflow.tsx  + *.trigger.tsx        — durable work + events  │
 │    *.agent.tsx                            — persisted AI chat      │
-└──────────────────────────────────────────────────────────────────┘
+└────────────────────────────────────────────────────────────────────┘
 ```
 
 Most of it goes through one WebSocket (REST routes are the public raw-HTTP exception). Queries and streams are both streaming RPCs, but they mean different things: a query emits reactive snapshot/delta envelopes; a stream emits plain elements and then finishes.

package/templates/agent-docs/database/migrations.md

@@ -1175,38 +1175,38 @@ What prod boot DOES is compare the declared-schema fingerprint against the lates
 └────────────────┬────────────────┘
                  │
                  ▼
-┌─────────────────────────────────┐
-│ 2. CI runs `voltro db plan`     │
+┌──────────────────────────────────┐
+│ 2. CI runs `voltro db plan`      │
 │    against a staging-style       │
 │    snapshot. The printed plan    │
 │    (classes + fingerprints) goes │
 │    into the PR for review        │
-└────────────────┬────────────────┘
+└────────────────┬─────────────────┘
                  │
                  ▼
-┌─────────────────────────────────┐
-│ 3. Reviewer reads the plan      │
+┌──────────────────────────────────┐
+│ 3. Reviewer reads the plan       │
 │    classification, fingerprints  │
 │    + DSL annotations             │
 │    Approves PR                   │
-└────────────────┬────────────────┘
+└────────────────┬─────────────────┘
                  │
                  ▼
-┌─────────────────────────────────┐
-│ 4. Merge to main                │
+┌──────────────────────────────────┐
+│ 4. Merge to main                 │
 │    CI/CD deploys new image       │
 │    BEFORE traffic switch a       │
 │    one-shot job runs             │
 │    `voltro db apply` against     │
 │    the prod DB (re-diffs live)   │
-└────────────────┬────────────────┘
+└────────────────┬─────────────────┘
                  │
                  ▼
-┌─────────────────────────────────┐
-│ 5. Traffic switches             │
-│    Prod boot: fingerprint match  │
+┌───────────────────────────────────┐
+│ 5. Traffic switches               │
+│    Prod boot: fingerprint match   │
 │    → serves                       │
-└─────────────────────────────────┘
+└───────────────────────────────────┘
 ```
 
 There's a slot for the apply step in every common deploy tool (k8s init container, ECS task pre-deploy hook, Heroku release phase, Cloud Run job-on-deploy, Fly.io `release_command`). The shape is identical: run a one-shot container/process that holds the migration credentials + executes `voltro db apply`. It re-diffs the live DB against the deployed code's declared schema and applies the resulting plan — there is no pre-serialised plan file to pass; the apply re-computes the diff at run time. The serving process never gets the migration-grade credentials.

package/templates/agent-docs/database/querying.md

@@ -1499,14 +1499,14 @@ At runtime, every `ChangeEvent` consults this map BEFORE triggering a re-query.
 Stage 1 — the dependency graph tracks per-table dependency. When `posts` changes, the dispatcher finds every subscription whose dependent-table set includes `posts` and triggers a re-query. After the re-query, a shallow row-set compare (JSON.stringify per row) suppresses the delta if the result is shape-identical to the last delivered snapshot.
 
 ```text
-┌──────────────────────────────────────────────────────────────────┐
-│ Subscription: users.with({ posts: { with: { author: true } } })  │
-│                                                                   │
+┌───────────────────────────────────────────────────────────────────────┐
+│ Subscription: users.with({ posts: { with: { author: true } } })       │
+│                                                                       │
 │   change(users)     → re-query  → diff vs lastDelivered → maybe delta │
 │   change(posts)     → re-query  → diff vs lastDelivered → maybe delta │
-│                                                                   │
-│   change(orgs)      → no-op (not in dependency graph)             │
-└──────────────────────────────────────────────────────────────────┘
+│                                                                       │
+│   change(orgs)      → no-op (not in dependency graph)                 │
+└───────────────────────────────────────────────────────────────────────┘
 ```
 
 This is CORRECT but expensive: every write to a dependent table costs a SQL round-trip, even when the write touched a column the subscription doesn't care about.

package/templates/agent-docs/deployment.md

@@ -374,6 +374,34 @@ The app is only stopped when, continuously for the grace window:
 
 A long-sleeping workflow (`sleep('3 days')`) is exactly the case dormancy is built for: the app stops, and the orchestrator brings a fresh process up when the sleep is due — the workflow resumes from its journal.
 
+## Diagnosing cold-start latency
+
+The flip side of scale-to-zero is a cold start on the first hit after an idle period. Every `voltro serve` boot logs how long it took to become ready:
+
+```text
+serve: ready in 1910ms
+```
+
+To see WHERE those milliseconds go, set `VOLTRO_BOOT_TIMING=1` — the same line gains a per-phase breakdown:
+
+```text
+serve: ready in 1910ms  { bootMs: 1910, phases: { modules: 1872, config: 0, discover: 18, store: 9, plugins: 1, workflow: 1, ready: 9 } }
+```
+
+The phases, in boot order:
+
+| Phase | What it covers |
+| --- | --- |
+| `modules` | node init + loading and compiling the JS module graph (the framework + your app). On a scale-to-zero container this is almost always the dominant phase — it is the cost of evaluating the dependency graph on a cold process, and it scales inversely with your CPU allotment. No app-level change shrinks it — **precompiling the app (`voltro build`) removes only the transpile of your own source files, not the framework graph load.** |
+| `config` | loading `app.config.ts` + the typed-env gate |
+| `discover` | walking the app + loading discovered primitives (plus the precompiled bundle, when `voltro build` produced one) |
+| `store` | opening the data store + cache/kv facades — a real SQL dialect includes the connection handshake here |
+| `plugins` | plugin bind + lifecycle activation |
+| `workflow` | the durable-workflow engine |
+| `ready` | serveApi's own setup — handler layers, subscribers, reactions, aggregates, the HTTP listener |
+
+Read this from the container's own logs at its real CPU allotment, not a beefy dev machine: a `modules` phase that dwarfs everything else means the cold start is dominated by evaluating the dependency graph (raise the container's CPU, or keep one instance warm); a fat `store` phase points at the database connection instead. `VOLTRO_BOOT_TIMING` adds a handful of `performance.now()` calls and one log line — it is safe to leave on in production.
+
 ## Tiers (Voltro Cloud — coming soon)
 
 Managed cloud hosting is not yet available; the Pro / Enterprise rows below are the planned managed tiers. Today you self-host and run `voltro dormancy` yourself.

package/templates/agent-docs/internationalization.md

@@ -13,7 +13,7 @@ _Voltro's i18n layer (@voltro/i18n) — an opinionated wrap over react-intl, aut
 
 Voltro ships internationalization in **`@voltro/i18n`** — an opinionated, thin wrap over [`react-intl`](https://formatjs.io/docs/react-intl/) plus framework auto-wiring. A web app gets a working `<I18nProvider>` from a single field in `app.config.ts`. You never write the provider, and you never import `@voltro/i18n` in your layout.
 
-The public surface is intentionally small — `<I18nProvider>`, `<T>`, `useT`, `useTFn`, `useLocale`, `defineCatalog`, `defineLocale`. Power users who need an API the wrap doesn't expose (custom formatters, rich-text with React-element values, `IntlProvider`'s `timeZone` / `formats` props) `import { … } from 'react-intl'` directly. The wrap is **opt-in, not lock-in** — the library is in your `node_modules`, the wrap is optional.
+The public surface is intentionally small — `<I18nProvider>`, `<T>`, `useT`, `useTFn`, `useLocale`, `useMessages`, `defineCatalog`, `defineLocale`, `pickCatalog`. Power users who need an API the wrap doesn't expose (custom formatters, rich-text with React-element values, `IntlProvider`'s `timeZone` / `formats` props) `import { … } from 'react-intl'` directly. The wrap is **opt-in, not lock-in** — the library is in your `node_modules`, the wrap is optional.
 
 ## When to enable
 
@@ -142,6 +142,31 @@ const locale = useLocale()
 - **`useT(id, values?)`** — imperative form returning a plain string, for non-JSX call sites: `placeholder`, `aria-label`, `document.title`, toasts, error messages.
 - **`useTFn()`** — returns a `(id, values?) => string` translator the component captures once. Use when one component needs `t` inside helper functions or `.map()` callbacks — `react-intl` runs once, the closure replays.
 - **`useLocale()`** — the active locale code, as React state inside the provider.
+- **`useMessages()`** — the active locale's RAW catalog (`useMessages()['some.id']`): the unformatted ICU template, not the formatted output. For when you need the raw string — e.g. to feed your own formatter, or a lookup that must not run ICU.
+
+## Reading a message outside React — `meta({ locale })`
+
+`useT` is a hook — it only runs inside a component, against the *active* locale. A page's `meta({ locale })` runs OUTSIDE React (at build / SSR meta-resolution time) and is handed an arbitrary locale string. Use **`pickCatalog`** to resolve a message there:
+
+```ts
+// src/locales/index.ts
+import { pickCatalog } from '@voltro/i18n'
+import en from './en'
+import de from './de'
+
+export const getCatalog = (locale?: string) => pickCatalog({ en, de }, locale, 'en')
+```
+
+```tsx
+// any page — meta gets the active locale (from the URL prefix, or the voltro:lang cookie)
+import { getCatalog } from '../locales'
+
+export const meta = ({ locale }: { readonly locale: string }): PageMeta => ({
+  title: getCatalog(locale)['meta.home.title'],
+})
+```
+
+`pickCatalog(catalogs, locale, defaultLocale)` returns the concrete catalog type, so a known-key lookup is `string` (not `string | undefined`) — exactly what `PageMeta.title` needs. An unknown or `undefined` locale falls back to `defaultLocale`.
 
 ## The react-intl escape hatch
 

package/templates/agent-docs/workflows.md

@@ -819,6 +819,8 @@ You do not call the cluster layer yourself — the CLI does. The boot log tells
 [voltro:dev] workflow engine: cluster-sql, dialect=mariadb
 ```
 
+Two settings tune this for demanding topologies: **`VOLTRO_WORKFLOW_SHARD_LOCK`** keeps cross-pod handoff correct on a Galera / Percona XtraDB cluster (see [Galera and multi-primary clusters](#galera-and-multi-primary-clusters)), and **`VOLTRO_WORKFLOW_RUNNER_STORAGE`** opts out of SQL runner storage when you don't need handoff (see [Single-process runner storage](#single-process-runner-storage)).
+
 ### The deployment contract
 
 A real multi-instance deployment has to give each pod a routable identity. This is the entire operational surface of clustering, and it is what the framework's Helm baseline injects:
@@ -848,6 +850,38 @@ env:
 
 That is the whole contract: stable per-pod identity (`POD_NAME` → `server_id`), routable runner host (`POD_IP`), a pinned runner port, the shared `DB_URL`, and CDC on. No application code changes between one instance and four.
 
+### Galera and multi-primary clusters
+
+Multi-primary MariaDB (Galera) and Percona XtraDB are first-class **and keep full cross-pod handoff** — no proxy, no single-writer endpoint, no loss of durability. This is handled automatically; the paragraphs below are the *why* for operators who need it.
+
+By default `@effect/cluster` coordinates which runner owns which shard with **session advisory locks** (`GET_LOCK` on MySQL/MariaDB, `pg_advisory_lock` on Postgres). Advisory locks are **node-local** — a lock held on one Galera node is invisible on the others, and Galera never replicates them. So on a Galera cluster whose app pods reach the database through a load-balancing Service (connections spread across nodes), advisory-lock coordination can't see itself: pods split-brain shard ownership, and the runner-storage bootstrap can wedge before it creates `cluster_runners` (the pod stays **un-Ready** while a shard-lock refresher errors against a `cluster_runners` table it thinks is missing).
+
+Voltro resolves this with the **`VOLTRO_WORKFLOW_SHARD_LOCK`** setting (`auto` | `row` | `advisory`, default `auto`):
+
+- **`auto`** — probe the live connection (`@@wsrep_on`) and switch to the row-lease path on a Galera / PXC cluster, keep advisory locks everywhere else. No operator config needed.
+- **`row`** — force the row-lease path. `SqlRunnerStorage` coordinates shard ownership with a **certified conditional upsert** on the `cluster_locks` table (`INSERT … ON DUPLICATE KEY UPDATE … WHERE acquired_at < <expiry>`) instead of `GET_LOCK`. Galera certifies that write across *all* nodes — the same reason the cron `advisoryLock` tier uses a claims row, not a session lock — so shard ownership is coordinated correctly no matter which node a connection lands on. Cross-pod handoff works: a dead pod's lease ages out and a surviving pod takes over the shard.
+- **`advisory`** — force the classic `GET_LOCK` path (single-primary only).
+
+The boot log reports the resolved mode, and `voltro cluster status` shows it per instance (`shard-lock=row`):
+
+```text
+[voltro:serve] shard-lock coordination: row-based (dialect=mariadb, mode=auto, wsrep/Galera cluster detected)
+```
+
+**Two honest caveats.** Row-lease failover is **expiry-based, not instant** — a dead pod's shards are reclaimed after the lease timeout (seconds), where advisory locks release the instant a connection drops. That's why `auto` keeps the faster advisory path on a single-primary server and only pays the timeout on Galera. And MySQL **Group Replication** (and other non-wsrep multi-primary topologies) aren't auto-detected — set `VOLTRO_WORKFLOW_SHARD_LOCK=row` explicitly there.
+
+### Single-process runner storage
+
+If a deployment genuinely does **not** need cross-pod handoff — dev, a single-region single-replica service, or one where each pod owning its own workflows is acceptable — set **`VOLTRO_WORKFLOW_RUNNER_STORAGE=memory`** to skip the SQL runner storage entirely:
+
+```text
+VOLTRO_WORKFLOW_RUNNER_STORAGE=memory
+```
+
+This is the engine `sqlite` uses. It **skips `SqlRunnerStorage`** (no `cluster_runners` / `cluster_locks`, no advisory locks) while **durability is unaffected** — run/message/reply state still persists via `SqlMessageStorage`. The tradeoff is the point: **no cross-pod handoff** — a workflow started on a now-dead pod will not resume on a surviving one. Prefer the row-lease coordination above for multi-replica deployments that need handoff; reach for `memory` only when they don't.
+
+`VOLTRO_WORKFLOW_RUNNER_STORAGE=sql` is rejected on `sqlite` / `turso` (no advisory-lock branch there), and an unrecognized `VOLTRO_WORKFLOW_SHARD_LOCK` value fails boot loudly — a misconfiguration never silently selects a broken engine.
+
 ## Durable workflows resume on any instance
 
 Workflow durability lives in `@effect/cluster`'s engine, not in any Voltro table. Each workflow's journal (steps, idempotency keys, signals) is persisted to the cluster's storage on the shared database. When a pod dies mid-step:

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

@@ -11,16 +11,16 @@
   "dependencies": {
     "@effect/platform": "^0.96.1",
     "@effect/rpc": "^0.75.1",
-    "@voltro/ai": "0.1.4",
-    "@voltro/cli": "0.1.4",
-    "@voltro/database": "0.1.4",
-    "@voltro/env": "0.1.4",
-    "@voltro/protocol": "0.1.4",
-    "@voltro/runtime": "0.1.4",
+    "@voltro/ai": "0.1.6",
+    "@voltro/cli": "0.1.6",
+    "@voltro/database": "0.1.6",
+    "@voltro/env": "0.1.6",
+    "@voltro/protocol": "0.1.6",
+    "@voltro/runtime": "0.1.6",
     "effect": "^3.21.2"
   },
   "devDependencies": {
-    "@voltro/testing": "0.1.4",
+    "@voltro/testing": "0.1.6",
     "typescript": "^5.7.0",
     "vitest": "^3.0.0"
   }

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

@@ -12,16 +12,16 @@
   "dependencies": {
     "@effect/platform": "^0.96.1",
     "@effect/rpc": "^0.75.1",
-    "@voltro/cli": "0.1.4",
-    "@voltro/database": "0.1.4",
-    "@voltro/env": "0.1.4",
-    "@voltro/plugin-auth": "0.1.4",
-    "@voltro/protocol": "0.1.4",
-    "@voltro/runtime": "0.1.4",
+    "@voltro/cli": "0.1.6",
+    "@voltro/database": "0.1.6",
+    "@voltro/env": "0.1.6",
+    "@voltro/plugin-auth": "0.1.6",
+    "@voltro/protocol": "0.1.6",
+    "@voltro/runtime": "0.1.6",
     "effect": "^3.21.2"
   },
   "devDependencies": {
-    "@voltro/testing": "0.1.4",
+    "@voltro/testing": "0.1.6",
     "typescript": "^5.7.0",
     "vitest": "^3.0.0"
   }

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

@@ -12,16 +12,16 @@
   "dependencies": {
     "@effect/platform": "^0.96.1",
     "@effect/rpc": "^0.75.1",
-    "@voltro/cli": "0.1.4",
-    "@voltro/database": "0.1.4",
-    "@voltro/env": "0.1.4",
-    "@voltro/plugin-multitenancy": "0.1.4",
-    "@voltro/protocol": "0.1.4",
-    "@voltro/runtime": "0.1.4",
+    "@voltro/cli": "0.1.6",
+    "@voltro/database": "0.1.6",
+    "@voltro/env": "0.1.6",
+    "@voltro/plugin-multitenancy": "0.1.6",
+    "@voltro/protocol": "0.1.6",
+    "@voltro/runtime": "0.1.6",
     "effect": "^3.21.2"
   },
   "devDependencies": {
-    "@voltro/testing": "0.1.4",
+    "@voltro/testing": "0.1.6",
     "typescript": "^5.7.0",
     "vitest": "^3.0.0"
   }

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

@@ -12,16 +12,16 @@
   "dependencies": {
     "@effect/platform": "^0.96.1",
     "@effect/rpc": "^0.75.1",
-    "@voltro/cli": "0.1.4",
-    "@voltro/database": "0.1.4",
-    "@voltro/env": "0.1.4",
-    "@voltro/plugin-deactivation": "0.1.4",
-    "@voltro/protocol": "0.1.4",
-    "@voltro/runtime": "0.1.4",
+    "@voltro/cli": "0.1.6",
+    "@voltro/database": "0.1.6",
+    "@voltro/env": "0.1.6",
+    "@voltro/plugin-deactivation": "0.1.6",
+    "@voltro/protocol": "0.1.6",
+    "@voltro/runtime": "0.1.6",
     "effect": "^3.21.2"
   },
   "devDependencies": {
-    "@voltro/testing": "0.1.4",
+    "@voltro/testing": "0.1.6",
     "typescript": "^5.7.0",
     "vitest": "^3.0.0"
   }

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

@@ -12,18 +12,18 @@
   "dependencies": {
     "@react-email/components": "^1.0.12",
     "@react-email/render": "^1.4.0",
-    "@voltro/cli": "0.1.4",
-    "@voltro/database": "0.1.4",
-    "@voltro/env": "0.1.4",
-    "@voltro/plugin-mail": "0.1.4",
-    "@voltro/plugin-multitenancy": "0.1.4",
-    "@voltro/protocol": "0.1.4",
-    "@voltro/runtime": "0.1.4",
+    "@voltro/cli": "0.1.6",
+    "@voltro/database": "0.1.6",
+    "@voltro/env": "0.1.6",
+    "@voltro/plugin-mail": "0.1.6",
+    "@voltro/plugin-multitenancy": "0.1.6",
+    "@voltro/protocol": "0.1.6",
+    "@voltro/runtime": "0.1.6",
     "effect": "^3.21.2",
     "react": "^19.0.0"
   },
   "devDependencies": {
-    "@voltro/testing": "0.1.4",
+    "@voltro/testing": "0.1.6",
     "typescript": "^5.7.0",
     "vitest": "^3.0.0"
   }

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

@@ -12,18 +12,18 @@
   "dependencies": {
     "@effect/platform": "^0.96.1",
     "@effect/rpc": "^0.75.1",
-    "@voltro/cli": "0.1.4",
-    "@voltro/database": "0.1.4",
-    "@voltro/env": "0.1.4",
-    "@voltro/plugin-multitenancy": "0.1.4",
-    "@voltro/plugin-storage": "0.1.4",
-    "@voltro/protocol": "0.1.4",
-    "@voltro/runtime": "0.1.4",
-    "@voltro/sql-mysql": "0.1.4",
+    "@voltro/cli": "0.1.6",
+    "@voltro/database": "0.1.6",
+    "@voltro/env": "0.1.6",
+    "@voltro/plugin-multitenancy": "0.1.6",
+    "@voltro/plugin-storage": "0.1.6",
+    "@voltro/protocol": "0.1.6",
+    "@voltro/runtime": "0.1.6",
+    "@voltro/sql-mysql": "0.1.6",
     "effect": "^3.21.2"
   },
   "devDependencies": {
-    "@voltro/testing": "0.1.4",
+    "@voltro/testing": "0.1.6",
     "typescript": "^5.7.0",
     "vitest": "^3.0.0"
   }