@voltro/workflow 0.80.0 → 0.81.0

package/CHANGELOG.md

@@ -39,6 +39,96 @@ _Changes staged for the next release accumulate here (rolled up from
 
 ---
 
+## [0.81.0] — 2026-09-25
+
+### ⚠ BREAKING
+
+- **The compose baseline gives each api app its own database** — `@voltro/cli`
+
+  `voltro baseline sync` now gives every api app in a `project.json` its own database, login and migrate service. The primary api (the app named `api`, else the first api app) keeps the project's database; every other api app connects to `<project>_<app>` with `<PROJECT>_<APP>_DB_PASSWORD`, and each api app gets `VOLTRO_API_<APP>_URL` for its sibling api apps by service name. Migration: sync, move each secondary app's own tables into its new database, and set the new password variables in production.
+
+  **`voltro update` carries you across this** — codemod `0.81.0/03_compose-baseline-one-database-per-api-app`. If you pin versions by hand and never run it, print the notes without changing anything: `voltro update --codemods-only --from <your current version> --dry-run` (this one ships in 0.81.0).
+- **A crashed process blocks its idempotency key for 30 seconds, not a day** — `@voltro/protocol`, `@voltro/runtime`, `@voltro/client`, `@voltro/voltro`
+
+  A process that died inside an idempotent mutation left its key `in_flight` for the whole replay window — 24 hours by default — so every retry with that key was refused with `MutationInFlight` (REST: `409`), including the retry of a workflow step whose callee had simply restarted. A running claim now holds on a 30-second lease that the server renews while the handler runs, over the socket and on REST alike; a dead process stops renewing, and the next send with the key takes over and runs the mutation once — the dead call's transaction never committed. A completed response still replays for the whole window. A takeover is conditional on the claim still being stale, so a claim renewed a moment earlier is never taken from a live handler. `ctx.apis` calls treat `MutationInFlight` as no answer yet: the same key is re-sent when the callee says, until it answers or the call's deadline passes (then `ApiUnavailable`). BREAKING only for an app that implements `IdempotencyStore` itself: `claim` takes the lease, and `renew(scope, key, now)` is required.
+
+  **`voltro update` carries you across this** — codemod `0.81.0/05_idempotency-store-renews-its-lease`. If you pin versions by hand and never run it, print the notes without changing anything: `voltro update --codemods-only --from <your current version> --dry-run` (this one ships in 0.81.0).
+- **Each api app owns its database schema; a second app on it refuses to boot** — `@voltro/database`, `@voltro/cli`
+
+  The first boot that migrates a database records which app owns it (`_voltro_schema_owner`). A different app booting against the same database and schema now refuses — naming both apps — before it plans anything, under `voltro dev`, `voltro serve` and `VOLTRO_AUTO_MIGRATE=0` alike; `voltro db apply` refuses the same way and claims an unclaimed database — as its first write, after every other check has passed, so an apply refused for drift or a blocked operation leaves the database as it found it. `voltro data` export and import treat the owner row as the deployment's own: it never travels to another database. Two apps on one schema each diffed it against their own declarations and planned to drop the other's tables. Migration: give every api app its own database (`DB_URL`) or schema (`DB_SCHEMA`) and reach the other app's data through `apis:` and `service:` procedures; `voltro doctor` lists api apps of a project that resolve the same target. `voltro db claim --yes` hands a schema to a RENAMED app.
+
+  **`voltro update` carries you across this** — codemod `0.81.0/01_one-database-per-app`. If you pin versions by hand and never run it, print the notes without changing anything: `voltro update --codemods-only --from <your current version> --dry-run` (this one ships in 0.81.0).
+- **ReactionDefinition is the union of the table form and the query form** — `@voltro/runtime`, `@voltro/voltro`
+
+  With reactions that watch a live query's rows, `ReactionDefinition` is now `EdgeReactionDefinition | LevelReactionDefinition`. Code holding a value of that type and reading a member only the table form has — `watch.table`, `watch.on`, `guards.dedupeKey`, `when(event)` — no longer compiles: type it `EdgeReactionDefinition`, or narrow with `isLevelReaction(def)` first. `defineReaction({ … })` is unchanged: an object literal resolves to its own form, and a value typed as the union is still accepted and validated by its `watch`.
+
+  **`voltro update` carries you across this** — codemod `0.81.0/04_reaction-definition-is-a-union`. If you pin versions by hand and never run it, print the notes without changing anything: `voltro update --codemods-only --from <your current version> --dry-run` (this one ships in 0.81.0).
+- **Store calls on a table the app does not declare now fail** — `@voltro/runtime`, `@voltro/cli`
+
+  Every store verb — in handlers, startups, schedules and workflows — now fails with `UndeclaredTableAccess` on a table that is neither declared by the app (its `table()`s, a plugin's `extendSchema.tables`) nor framework-owned (`_voltro_*`), in every environment. A string table name used to reach another app's table past its guards, audit and tenant rules. `store.raw(sql)` is unchanged. Migration: call the owning app through `apis:` and a `service:` procedure, or declare the table if it is this app's own.
+
+  **`voltro update` carries you across this** — codemod `0.81.0/02_store-refuses-undeclared-tables`. If you pin versions by hand and never run it, print the notes without changing anything: `voltro update --codemods-only --from <your current version> --dry-run` (this one ships in 0.81.0).
+
+### Added
+
+- **A plugin can bring app-shaped building blocks with `sources`** — `@voltro/protocol`, `@voltro/cli`
+
+  `definePlugin({ sources: fileURLToPath(new URL('./app', import.meta.url)) })` points at a directory of the same file conventions an app uses — queries and mutations with their executors, `schema.ts` tables, `*.workflow.tsx`, `*.cron.tsx`, subscribers, reactions — and every app that installs the plugin discovers them exactly as it discovers its own: the same codegen, browser-safety guard, access gate, migrations, and both boot paths. A reusable building block (a ledger, an audit trail, an approval flow) is shared between apps of a project without copying it; each installing app gets its own copy of the block's tables in its own database. `voltro build` keys the block's modules by plugin and path, so the serve bundle finds them wherever the block lives after a deploy.
+- **A reaction can watch the rows of a live query, including another app's** — `@voltro/runtime`, `@voltro/cli`
+
+  `defineReaction({ watch: { query: 'deployments.pending', api: 'cloud' }, key: (row) => row.id, act: { kind: 'workflow', workflow: 'deploy.run' } })` reacts to every ROW of a live query's current result — the set of open work — instead of to each change of a table. Every delivery is the whole set, so a row that appeared while the reacting process was down, restarting or deploying is acted on when it comes back; nothing is lost. The workflow's `idempotencyKey` makes each row's act exactly-once across every replica, so no claim table is involved and a start that failed is tried again on the next delivery or on `resync` (default 5 minutes). `resync` and `stuckAfter` take milliseconds or a duration from `'30s'` to `'8 days'`. With `api:` the query is another app's `service:` query, subscribed over `ctx.apis` — push without the watched app knowing its watcher; without it, one of this app's own queries, read through the same guards and row filter as its REST projection. A row still in the set long after its workflow started is reported as `stuck` and never restarted. `voltro_reaction_pending`, `voltro_reaction_oldest_seconds` and `voltro_reaction_connected` expose the queue per reaction. The table form (`watch: { table }`) is unchanged; `runReaction` now takes the table form's type, `EdgeReactionDefinition`.
+- **Apps of one project call each other through typed service procedures** — `@voltro/voltro`, `@voltro/protocol`, `@voltro/runtime`, `@voltro/client`, `@voltro/cli`, `@voltro/testing`, `@voltro/workflow`
+
+  An api app can now call another app of the same project, typed, over the socket, without touching its tables. The called app declares `service: { callers: ['worker'] }` on a query, mutation or action and lists the caller under `serviceCallers: { worker: {} }`; codegen emits those procedures into `serviceGroup.generated.ts` and never into the browser's `rpcGroup.generated.ts`. The calling app binds it under `apis: { cloud: { package: '@acme/api' } }` and calls `ctx.apis.cloud.deployments.activate(input)` (Promise) or `.effect(input)` (Effect), with every input, output and typed error inferred from the callee's declarations. A service authenticates with a per-edge credential (`VOLTRO_API_<BINDING>_TOKEN` on the caller, `VOLTRO_SERVICE_CALLER_<CALLER>_TOKEN` on the callee, `_NEXT` for rotation); `voltro dev` derives and mints it into both apps' `.env.local`, production supplies it (`voltro secret generate service`) and a missing one fails boot. A caller name is letters, digits and dashes, at most 56 characters, so its `service:<name>` identity fits an `id()` column. The called app plants an `actors` row for each accepted caller at boot (`service:<name>`, `kind: 'serviceAccount'`), so `audit()`-stamped writes name the calling app instead of failing on the foreign key. A service subject holds no scopes: it reaches exactly the procedures that name it, is refused everywhere else — framework built-ins included — and no user, API key or `admin:full` session reaches a service procedure. A write made inside a workflow step carries an idempotency key derived from the step, so a step retried after a lost reply replays instead of writing twice; an app with `serviceCallers` deduplicates mutations by default. A call without an answer fails with `ApiUnavailable` within a deadline (10 s by default); calls are measured as `voltro_api_call_duration_seconds` and `voltro_api_call_errors_total`. `voltro doctor` reports a caller listed without a procedure, a procedure naming an unlisted caller and a binding the callee does not accept. `@voltro/testing` adds `makeServiceApiMock`, which decodes every input and output through the callee's real schemas.
+
+  `apiSurface: compatible` — the replaced golden lines in `@voltro/protocol` (and the `@voltro/voltro` aggregate re-exporting it) are `AnyCheckSpec` and `DeclaredAccess` gaining the member `ServiceAccessSpec`. Every existing member is unchanged and an app keeps writing the guards it wrote; the framework is the only producer of the new member, which it normalises from `service:`. Only a switch exhaustive over guard specs needs an arm.
+- **startTestApps boots several apps of one project, each service edge wired** — `@voltro/testing`
+
+  `startTestApps({ apps, edges })` from `@voltro/testing` boots the apps of one project as real `voltro` processes (`dev` by default, `serve` with `mode: 'serve'`), each on a free port — every callee before its callers, because a caller imports the contract its callee's codegen writes — and resolves once every app answers `/internal/readiness`; a cycle of edges is refused before anything starts. Every listed edge gets a freshly minted credential written to both ends, under the variables the apps read (`VOLTRO_API_<BINDING>_TOKEN` / `_URL` on the caller, `VOLTRO_SERVICE_CALLER_<CALLER>_TOKEN` on the callee); `apps.token(caller, callee)` returns it so a test can call the callee as the caller. An app that exits or is not ready in time stops the others and the call rejects with its log. Processes rather than one process, because apps with their own tables cannot share one process's table registry.
+- **makeTestApp requests carry the caller's address** — `@voltro/testing`
+
+  A route that reads `ctx.remoteAddr` (a per-client rate limit, an audit field) could not be tested per client: every `makeTestApp` request arrived without an address. A request's options now take `remoteAddr`, the address the connection comes from, defaulting to `127.0.0.1`. The route sees it as `ctx.remoteAddr`, resolved by the function the server's listener uses, and a `publicApi` procedure's plugin interceptors see the same address, as on the server. `makeTestApp({ security: { trustedProxies, clientAddressHeader } })` takes the api's own settings, so a forwarding header is believed in a test exactly when it would be in production.
+
+  `markRestInvocation` takes the request's address as an optional third argument, and `restInvocationOf` returns it beside the spec; both only gain an optional member, so existing calls and reads are unchanged.
+
+### Fixed
+
+- **Codegen removes an rpc group the app no longer has procedures for** — `@voltro/cli`
+
+  An app whose last client-reachable procedure went away — deleted, or marked `internal: true` — kept its `rpcGroup.generated.ts`: codegen reported "no rpc primitives found — nothing to write" and left the old file, a typed contract for procedures the server no longer served. The next `voltro dev` or `voltro codegen` now removes it, as it already removed an empty `serviceGroup.generated.ts` and `apis.generated.ts`. A hand-written file of that name is left alone.
+- **The auto-launched dashboard binds `VOLTRO_DASHBOARD_PORT`** — `@voltro/cli`
+
+  `VOLTRO_DASHBOARD_PORT` was read by `voltro dashboard` only. The dashboard that `voltro dev` and `voltro start` launch on their own — api and web app alike — always came up on `:5179`, and the launcher wrote `5179` into the child's `VOLTRO_DASHBOARD_PORT`, overriding the value the developer had set. The launcher and `voltro dashboard` now resolve the port through one reader: the variable, else `5179`. A value that is not a port (`1..65535`) is refused with a warning naming it instead of silently becoming `5179`.
+- **The db pool boot line counts a connection outside the pool once** — `@voltro/cli`
+
+  With change data capture on, the line read `max=5 … + 1 = 6` and then, separately, `PLUS 1 outside the pool (CDC LISTEN consumer)`, which reads as 7 when the process holds 6. The outside connection is now named once, inside the sum it belongs to: `max=5 per replica (DB_MAX_CONNECTIONS) + 1 outside the pool (CDC LISTEN consumer) = 6 per process`.
+- **A declared `utf8mb4` store reaches the workflow engine's tables** — `@voltro/database`, `@voltro/workflow`, `@voltro/cli`
+
+  `store: { charset: 'utf8mb4' }` converted every table the app declares and left the tables the framework creates without declaring them in the database default: the durable workflow engine's `cluster_*` storage, which holds every workflow call's input and result as JSON text, and the deploy runner's `_voltro_deploys` / `_voltro_migration_ops`. On a `utf8mb3` database a workflow whose input carried an emoji was refused there. Every table the framework creates is now created in the declared charset: the runner's ledgers directly, and the workflow engine's tables by the process that creates them on its first boot, while they are still empty. A workflow table a booting process finds is never rewritten at boot; tables from before the declaration are converted by `voltro db apply` (also when the plan has nothing to do, and with `--plan`) once the deploy has closed and by the `voltro dev` auto-migrate, keeping type, nullability and column CHECKs, and `voltro db plan` lists them beside the plan (under `--json` too, on the log, never in the plan file). The database's own default is left alone. The step only ever widens, and a deploy that fails and is undone never runs it.
+- **The MySQL/MariaDB pool keeps its connections instead of reconnecting** — `@voltro/sql-mysql`
+
+  The driver pool was created with `maxIdle: 0`, so every connection released to it was closed within a second. A process reconnected after each second of quiet: a TCP handshake per burst, plus a TLS one where configured. Measured on MySQL and MariaDB: a query after two quiet seconds ran on a new connection. The pool now keeps the connections it opened, up to the limit.
+- **Workflows started by a reaction or an incoming webhook start again** — `@voltro/cli`
+
+  A workflow started by a `*.reaction.ts` act or an incoming `*.webhook.tsx` was refused with `Workflow placement requires explicit caller identity`, under `voltro dev` and `voltro serve`: neither path named a caller, and placement refuses a start without one. Both now start as the framework itself, placed in the changed row's tenant when it has one.
+- **The first boot on an empty database no longer warns about replica observations** — `@voltro/cli`
+
+  `voltro dev` started publishing this replica's observations before its auto-migrate, so the first write on an empty database hit a table that did not exist yet and printed `could not record this replica's observation — fleet views will report this replica as stale` on the first boot of every new project. The publisher now writes its first observation once the schema is applied — at once on `voltro serve`, whose fingerprint check runs before it — and never when the boot stops earlier.
+- **A 405 on a shared REST path names every method the path serves** — `@voltro/protocol`
+
+  A `DELETE` to a path served by `GET` and `POST` answered `405` with `Allow: POST`: each route refused with its own method, and the last refusal won. `Allow` and the error body's `allow` now list every method declared on the path, `GET, POST`, as the REST documentation already promised.
+- **A large REST surface no longer holds the boot for seconds registering routes** — `@voltro/runtime`, `@voltro/protocol`
+
+  Every REST route used to be mounted for all 34 HTTP methods the router knows, at its path and at its sub-path, and each insert compares itself against every entry already held. A public REST surface of about 1000 procedures therefore held about 34 000 router entries, and building them kept the thread busy for over a second after the port was bound — long enough for a liveness probe to time out. A path is now mounted for exactly the methods its routes declare: the same 1000 procedures hold 4 000 entries. Behaviour is unchanged. A method the path does not declare still reaches its routes and gets the precise `405` with `Allow`, a path nobody declared is still a `404`, and `HEAD` still answers from `GET`. For this, a REST route now declares its real `method` instead of `'*'` and sets the new `PluginHttpRoute.answersOtherMethods: true`. A plugin route that declares one method without that flag never sees another method, as before. A server of your own that mounts `restRoutesToHttpRoutes` output by method must hand the other methods to routes with `answersOtherMethods`, or they become `404` instead of `405`.
+- **The testing guide's tsconfig example no longer sets baseUrl** — `@voltro/cli`
+
+  The `paths` alias example in the testing guide set `"baseUrl": "."`, an option TypeScript 7 removed. It now maps `paths` alone, which resolves against the tsconfig's own directory. `voltro test` still reads a `baseUrl` an older config sets.
+- **voltro update lists a note's code and config lines before prose** — `@voltro/cli`
+
+  A manual note lists the lines it found in code and config first, under `── found in code or config (N lines)`. Lines in Markdown and text files follow in their own `── mentioned in prose (N lines)` block, and a note that matched only prose says `nothing in code or config matched`. Past the lines shown, the rest are named by file with a count instead of a bare `… and N more`. Before, the lines were sorted by path, and 40 lines of documentation hid a Helm env entry, the one line to change. The guide `voltro agents-md` copies into `agent-docs/` is no longer searched. It names every change of a release, so refreshing it made notes report "found" for changes the project never used.
+
+---
+
 ## [0.80.0] — 2026-09-24
 
 ### ⚠ BREAKING

package/dist/{cluster-DJittOqj.js → cluster-D7VuRhM0.js}

@@ -1,17 +1,17 @@
 import { a as e, l as t, n, o as r, t as i, u as a } from "./clusterDiagnostics-Cwt-WFec.js";
 import { Context as o, Duration as s, Effect as c, Layer as l, Option as u, Runtime as d, Schema as f } from "effect";
 import { SqlClient as p } from "@effect/sql";
-import { ClusterCron as m, ClusterSchema as h, ClusterWorkflowEngine as g, EntityAddress as _, EntityId as v, EntityType as ee, MessageStorage as y, RunnerAddress as b, ShardId as te, Sharding as x, ShardingConfig as ne, SingleRunner as re, SqlMessageStorage as ie, SqlRunnerStorage as ae } from "@effect/cluster";
-import { fnv1a64 as S, resolveMigrationLockSchema as C, sqlPoolCapacity as oe } from "@voltro/database/sql";
-import { createLogger as se } from "@voltro/logger";
+import { ClusterCron as m, ClusterSchema as h, ClusterWorkflowEngine as g, EntityAddress as _, EntityId as ee, EntityType as te, MessageStorage as ne, RunnerAddress as v, ShardId as re, Sharding as y, ShardingConfig as ie, SingleRunner as ae, SqlMessageStorage as oe, SqlRunnerStorage as se } from "@effect/cluster";
+import { applyUndeclaredCharsetWork as b, fnv1a64 as x, readUndeclaredCharsetColumns as ce, resolveMigrationLockSchema as S, sqlPoolCapacity as le, undeclaredCharsetWork as ue } from "@voltro/database/sql";
+import { createLogger as de } from "@voltro/logger";
 //#region src/workflowJournalReset.ts
-var w = f.parseJson(f.Struct({
+var C = f.parseJson(f.Struct({
 	_tag: f.Literal("Success"),
 	value: f.Struct({ _tag: f.Literal("Suspended") })
-})), ce = f.parseJson(f.Record({
+})), fe = f.parseJson(f.Record({
 	key: f.String,
 	value: f.String
-})), le = (e) => c.gen(function* () {
+})), pe = (e) => c.gen(function* () {
 	if (!/^[1-9]\d*$/.test(e.requestId) || e.workflowName.length === 0 || e.executionId.length === 0) return yield* c.die(/* @__PURE__ */ Error("Suspension observation requires an exact engine delivery owner"));
 	let [t] = yield* (yield* p.SqlClient).withoutTransforms()`
       SELECT m.entity_type, m.entity_id, m.tag, m.headers, r.id AS reply_id, r.payload
@@ -20,13 +20,13 @@ var w = f.parseJson(f.Struct({
       WHERE m.id = ${e.requestId} AND m.kind = 0`;
 	if (t === void 0) return;
 	if (t.entity_type !== `Workflow/${e.workflowName}` || t.entity_id !== e.executionId || t.tag !== "run") return yield* c.die(/* @__PURE__ */ Error("Suspension observation belongs to another execution or procedure"));
-	if (((yield* c.sync(() => f.decodeUnknownSync(ce)(t.headers)))["voltro-workflow-restart"] ?? null) !== e.restartToken || t.reply_id === null || f.decodeUnknownOption(w)(t.payload)._tag === "None") return;
+	if (((yield* c.sync(() => f.decodeUnknownSync(fe)(t.headers)))["voltro-workflow-restart"] ?? null) !== e.restartToken || t.reply_id === null || f.decodeUnknownOption(C)(t.payload)._tag === "None") return;
 	let n = String(t.reply_id);
 	return /^[1-9]\d*$/.test(n) ? {
 		...e,
 		replyId: n
 	} : yield* c.die(/* @__PURE__ */ Error("Suspension reply has an invalid identity"));
-}).pipe(c.provideService(p.SafeIntegers, !0)), ue = (t, n) => c.gen(function* () {
+}).pipe(c.provideService(p.SafeIntegers, !0)), me = (t, n) => c.gen(function* () {
 	let { restart: r, suspension: i } = n, a = /* @__PURE__ */ new Map();
 	for (let e of t) {
 		if (!/^[1-9]\d*$/.test(e.requestId) || !/^[1-9]\d*$/.test(e.replyId)) return yield* c.die(/* @__PURE__ */ Error("Journal reset requires positive decimal request and reply identities"));
@@ -101,7 +101,7 @@ var w = f.parseJson(f.Struct({
 			};
 			let r = yield* s`SELECT payload FROM ${u}
           WHERE id = ${n} AND request_id = ${e} AND kind = 0`;
-			if (r.length !== 1 || i !== void 0 && f.decodeUnknownOption(w)(r[0]?.payload)._tag === "None") return {
+			if (r.length !== 1 || i !== void 0 && f.decodeUnknownOption(C)(r[0]?.payload)._tag === "None") return {
 				kind: "changed",
 				requestId: e
 			};
@@ -118,60 +118,60 @@ var w = f.parseJson(f.Struct({
 			count: o.length
 		};
 	}).pipe(s.withTransaction, c.provideService(p.SafeIntegers, !0));
-}), de = (e) => ue([e], { suspension: e }), fe = (e) => c.gen(function* () {
-	let n = yield* c.runtime(), r = yield* c.promise(() => e.transaction((t) => a(t, e.requestId, (e) => d.runPromise(n)(le(e)))));
+}), he = (e) => me([e], { suspension: e }), ge = (e) => c.gen(function* () {
+	let n = yield* c.runtime(), r = yield* c.promise(() => e.transaction((t) => a(t, e.requestId, (e) => d.runPromise(n)(pe(e)))));
 	if (r.kind !== "bound") return r;
 	let i = yield* c.promise(() => e.transaction((n) => t(n, e.requestId)));
 	if (i.kind !== "dispatch") return i;
 	let { request: o } = i;
 	if (o.operation !== "resume" || o.resumeJournal === null) return yield* c.die(/* @__PURE__ */ Error("Resume dispatch requires its committed suspension binding"));
-	let s = yield* de({
+	let s = yield* he({
 		workflowName: o.workflowName,
 		executionId: o.executionId,
 		...o.resumeJournal
 	});
-	return yield* (yield* x.Sharding).pollStorage, {
+	return yield* (yield* y.Sharding).pollStorage, {
 		kind: "attempted",
 		request: o,
 		journal: s
 	};
-}), T = class extends o.Tag("@voltro/workflow/WorkflowResumeDispatcher")() {}, pe = c.gen(function* () {
-	let e = yield* p.SqlClient, t = yield* x.Sharding;
-	return T.of({ dispatch: (n) => fe(n).pipe(c.provideService(p.SqlClient, e), c.provideService(x.Sharding, t)) });
-}), E = 6322741009312601n, D = () => {
-	let e = C();
-	return e === void 0 ? E : S(`voltro_cluster_migration_lock:${e}`) & 9223372036854775807n;
-}, O = () => {
-	let e = `voltro_cluster_migration_${E.toString(36)}`, t = C();
+}), w = class extends o.Tag("@voltro/workflow/WorkflowResumeDispatcher")() {}, _e = c.gen(function* () {
+	let e = yield* p.SqlClient, t = yield* y.Sharding;
+	return w.of({ dispatch: (n) => ge(n).pipe(c.provideService(p.SqlClient, e), c.provideService(y.Sharding, t)) });
+}), T = 6322741009312601n, E = () => {
+	let e = S();
+	return e === void 0 ? T : x(`voltro_cluster_migration_lock:${e}`) & 9223372036854775807n;
+}, D = () => {
+	let e = `voltro_cluster_migration_${T.toString(36)}`, t = S();
 	if (t === void 0) return e;
 	let n = `${e}_${t}`;
-	return /^[A-Za-z0-9_]+$/.test(t) && n.length <= 64 ? n : `${e}_h${S(`voltro_cluster_migration_lock:${t}`).toString(16)}`;
-}, k = () => {
+	return /^[A-Za-z0-9_]+$/.test(t) && n.length <= 64 ? n : `${e}_h${x(`voltro_cluster_migration_lock:${t}`).toString(16)}`;
+}, O = () => {
 	let e = Number(process.env.VOLTRO_CLUSTER_MIGRATION_LOCK_TIMEOUT_MS);
 	return Number.isFinite(e) && e > 0 ? e : 6e4;
-}, A = 250, j = (e) => e[0]?.[0], M = (e, t) => e.onDialectOrElse({
+}, k = 250, A = (e) => e[0]?.[0], j = (e, t) => e.onDialectOrElse({
 	sqlite: () => c.void,
-	mysql: () => t.executeValues(`SELECT GET_LOCK('${O()}', ${Math.ceil(k() / 1e3)})`, []).pipe(c.flatMap((e) => j(e) === 1 || j(e) === "1" ? c.void : c.die(/* @__PURE__ */ Error(`could not acquire cluster migration lock '${O()}' (GET_LOCK timed out)`)))),
-	mssql: () => t.executeValues(`DECLARE @res int; EXEC @res = sp_getapplock @Resource = '${O()}', @LockMode = 'Exclusive', @LockOwner = 'Session', @LockTimeout = ${k()}; SELECT @res`, []).pipe(c.flatMap((e) => Number(j(e) ?? -999) >= 0 ? c.void : c.die(/* @__PURE__ */ Error(`could not acquire cluster migration lock '${O()}' (sp_getapplock ${String(j(e))})`)))),
+	mysql: () => t.executeValues(`SELECT GET_LOCK('${D()}', ${Math.ceil(O() / 1e3)})`, []).pipe(c.flatMap((e) => A(e) === 1 || A(e) === "1" ? c.void : c.die(/* @__PURE__ */ Error(`could not acquire cluster migration lock '${D()}' (GET_LOCK timed out)`)))),
+	mssql: () => t.executeValues(`DECLARE @res int; EXEC @res = sp_getapplock @Resource = '${D()}', @LockMode = 'Exclusive', @LockOwner = 'Session', @LockTimeout = ${O()}; SELECT @res`, []).pipe(c.flatMap((e) => Number(A(e) ?? -999) >= 0 ? c.void : c.die(/* @__PURE__ */ Error(`could not acquire cluster migration lock '${D()}' (sp_getapplock ${String(A(e))})`)))),
 	orElse: () => {
-		let e = D().toString(), n = Date.now(), r = t.executeValues(`SELECT pg_try_advisory_lock(${e}::bigint)`, []).pipe(c.flatMap((e) => {
-			let t = j(e);
-			return t === !0 || t === "t" || t === 1 ? c.void : Date.now() - n >= k() ? c.die(/* @__PURE__ */ Error(`could not acquire the cluster migration advisory lock within ${Math.round(k() / 1e3)}s. Another runner is migrating the cluster schema, or a prior boot wedged while holding it. (Raise VOLTRO_CLUSTER_MIGRATION_LOCK_TIMEOUT_MS, or inspect pg_locks for the holder.)`)) : c.sleep(`${A} millis`).pipe(c.zipRight(r));
+		let e = E().toString(), n = Date.now(), r = t.executeValues(`SELECT pg_try_advisory_lock(${e}::bigint)`, []).pipe(c.flatMap((e) => {
+			let t = A(e);
+			return t === !0 || t === "t" || t === 1 ? c.void : Date.now() - n >= O() ? c.die(/* @__PURE__ */ Error(`could not acquire the cluster migration advisory lock within ${Math.round(O() / 1e3)}s. Another runner is migrating the cluster schema, or a prior boot wedged while holding it. (Raise VOLTRO_CLUSTER_MIGRATION_LOCK_TIMEOUT_MS, or inspect pg_locks for the holder.)`)) : c.sleep(`${k} millis`).pipe(c.zipRight(r));
 		}));
 		return r;
 	}
-}), N = (e, t) => e.onDialectOrElse({
+}), M = (e, t) => e.onDialectOrElse({
 	sqlite: () => c.void,
-	mysql: () => c.asVoid(t.executeValues(`SELECT RELEASE_LOCK('${O()}')`, [])),
-	mssql: () => c.asVoid(t.executeValues(`EXEC sp_releaseapplock @Resource = '${O()}', @LockOwner = 'Session'`, [])),
-	orElse: () => c.asVoid(t.executeValues(`SELECT pg_advisory_unlock(${D().toString()}::bigint)`, []))
-}), P = (e, t) => e.onDialectOrElse({
+	mysql: () => c.asVoid(t.executeValues(`SELECT RELEASE_LOCK('${D()}')`, [])),
+	mssql: () => c.asVoid(t.executeValues(`EXEC sp_releaseapplock @Resource = '${D()}', @LockOwner = 'Session'`, [])),
+	orElse: () => c.asVoid(t.executeValues(`SELECT pg_advisory_unlock(${E().toString()}::bigint)`, []))
+}), N = (e, t) => e.onDialectOrElse({
 	sqlite: () => !0,
 	orElse: () => !1
 }) ? t : c.scoped(c.gen(function* () {
 	let n = yield* e.reserve;
-	return yield* c.acquireRelease(M(e, n), () => N(e, n).pipe(c.orDie)), yield* t;
-})), F = (e) => e === "sql" ? ["cluster_messages", "cluster_runners"] : ["cluster_messages"], I = (e, t) => e.onDialectOrElse({
+	return yield* c.acquireRelease(j(e, n), () => M(e, n).pipe(c.orDie)), yield* t;
+})), P = (e) => e === "sql" ? ["cluster_messages", "cluster_runners"] : ["cluster_messages"], F = (e, t) => e.onDialectOrElse({
 	pg: () => e`SELECT (to_regclass(${t}) IS NOT NULL) AS present`,
 	mysql: () => e`SELECT (COUNT(*) > 0) AS present FROM information_schema.tables WHERE table_schema = DATABASE() AND table_name = ${t}`,
 	mssql: () => e`SELECT CASE WHEN OBJECT_ID(${t}, 'U') IS NULL THEN 0 ELSE 1 END AS present`,
@@ -179,9 +179,17 @@ var w = f.parseJson(f.Struct({
 }).pipe(c.map((e) => {
 	let t = e[0]?.present;
 	return t === !0 || t === 1 || t === "1" || t === "t" || typeof t == "bigint" && t === 1n;
-}), c.catchAll(() => c.succeed(!1))), L = (e, t) => c.forEach(F(t), (t) => I(e, t), { concurrency: 1 }).pipe(c.map((e) => e.every(Boolean))), R = (e, t) => c.scoped(c.asVoid(l.build(t.pipe(l.provide(ne.layerDefaults), l.provide(l.succeed(p.SqlClient, e)))))), z = (e, t) => R(e, ie.layer).pipe(c.zipRight(t === "sql" ? R(e, ae.layer) : c.void)), B = (e) => e === "sql" ? 3 : 2, me = (e) => l.effect(p.SqlClient, c.gen(function* () {
-	let t = yield* p.SqlClient, n = B(e.runnerStorage), r = oe(t);
-	return r !== void 0 && r < n ? yield* c.dieMessage(`the workflow runtime needs ${n} database connections at once and the pool has ${r}: ` + (e.runnerStorage === "sql" ? "on a first boot it holds its migration lock and its runner lock while the migration runs on a third, and once running it keeps the runner lock and needs one more to work. " : "on a first boot it holds its migration lock while the migration runs on a second. ") + `Set DB_MAX_CONNECTIONS (or PG_MAX_CONNECTIONS) to at least ${n}` + (e.runnerStorage === "sql" ? ", or VOLTRO_WORKFLOW_RUNNER_STORAGE=memory for a single-process runtime that needs 2 (no cross-pod shard handoff)." : ".")) : ((yield* L(t, e.runnerStorage)) || (yield* P(t, z(t, e.runnerStorage))), t);
+}), c.catchAll(() => c.succeed(!1))), I = (e, t) => c.forEach(P(t), (t) => F(e, t), { concurrency: 1 }).pipe(c.map((e) => e.every(Boolean))), L = (e, t) => c.scoped(c.asVoid(l.build(t.pipe(l.provide(ie.layerDefaults), l.provide(l.succeed(p.SqlClient, e)))))), R = (e, t) => L(e, oe.layer).pipe(c.zipRight(t === "sql" ? L(e, se.layer) : c.void)), z = (e) => c.map(e.unsafe("SELECT table_name AS t FROM information_schema.tables WHERE table_schema = DATABASE() AND table_name LIKE 'cluster\\_%'"), (e) => new Set(e.map((e) => String(e.t ?? e.T)))), ve = (e, t, n) => n === void 0 || !e.onDialectOrElse({
+	mysql: () => !0,
+	orElse: () => !1
+}) ? R(e, t) : c.gen(function* () {
+	let r = yield* z(e);
+	yield* R(e, t);
+	let i = new Set([...yield* z(e)].filter((e) => !r.has(e)));
+	i.size !== 0 && (yield* b(e, ue(yield* ce(e), /* @__PURE__ */ new Set(), n, i)));
+}), ye = (e) => e === "sql" ? 3 : 2, B = (e) => l.effect(p.SqlClient, c.gen(function* () {
+	let t = yield* p.SqlClient, n = ye(e.runnerStorage), r = le(t);
+	return r !== void 0 && r < n ? yield* c.dieMessage(`the workflow runtime needs ${n} database connections at once and the pool has ${r}: ` + (e.runnerStorage === "sql" ? "on a first boot it holds its migration lock and its runner lock while the migration runs on a third, and once running it keeps the runner lock and needs one more to work. " : "on a first boot it holds its migration lock while the migration runs on a second. ") + `Set DB_MAX_CONNECTIONS (or PG_MAX_CONNECTIONS) to at least ${n}` + (e.runnerStorage === "sql" ? ", or VOLTRO_WORKFLOW_RUNNER_STORAGE=memory for a single-process runtime that needs 2 (no cross-pod shard handoff)." : ".")) : ((yield* I(t, e.runnerStorage)) || (yield* N(t, ve(t, e.runnerStorage, e.charset))), t);
 })), V = (e) => {
 	if (e instanceof Date) return Number.isNaN(e.getTime()) ? null : e;
 	if (typeof e == "string" || typeof e == "number") {
@@ -189,7 +197,7 @@ var w = f.parseJson(f.Struct({
 		return Number.isNaN(n.getTime()) ? null : n;
 	}
 	return null;
-}, H = (e) => e === !0 || e === 1 || e === "1" || e instanceof Uint8Array && e[0] === 1, he = (e, t) => {
+}, H = (e) => e === !0 || e === 1 || e === "1" || e instanceof Uint8Array && e[0] === 1, be = (e, t) => {
 	let n = e.lastIndexOf(":");
 	if (n < 0) return;
 	let r = e.slice(0, n), i = Number(e.slice(n + 1)), a = t.indexOf(r);
@@ -257,7 +265,7 @@ var w = f.parseJson(f.Struct({
 	}))), g = (r) => {
 		let i = /* @__PURE__ */ new Map();
 		for (let e of r) {
-			let t = he(e, n);
+			let t = be(e, n);
 			t !== void 0 && i.set(t, e);
 		}
 		return i.size === 0 ? c.succeed([]) : c.gen(function* () {
@@ -315,14 +323,14 @@ var w = f.parseJson(f.Struct({
 			}).pipe(t.withTransaction, c.catchAll(() => c.succeed(0)));
 		}
 	};
-}), W = se({ scope: "voltro:workflow" }), ge = 34e3, G = (e) => {
+}), W = de({ scope: "voltro:workflow" }), xe = 34e3, G = (e) => {
 	let t = e.runnerListenHost ?? process.env.POD_IP ?? process.env.VOLTRO_WORKFLOW_RUNNER_HOST ?? "localhost";
 	return {
 		host: t,
 		port: e.runnerListenPort ?? 34e3,
 		localhostRisk: e.runnerStorage === "sql" && (t === "localhost" || t === "127.0.0.1")
 	};
-}, _e = (e) => {
+}, Se = (e) => {
 	let t = e.sqliteFamily ? "memory" : "sql", n = e.override ?? process.env.VOLTRO_WORKFLOW_RUNNER_STORAGE;
 	if (n === void 0 || n.trim() === "") return t;
 	let r = n.trim().toLowerCase();
@@ -341,12 +349,12 @@ var w = f.parseJson(f.Struct({
 	return t === 1 || t === "1" || t === !0 || t === "ON" || t === "on";
 }), J = (e) => c.gen(function* () {
 	return e.runnerStorage === "memory" ? !1 : e.mode === "row" ? !0 : e.mode === "advisory" || e.dialectId !== "mysql" && e.dialectId !== "mariadb" ? !1 : yield* q;
-}), ve = (e) => ({
+}), Ce = (e) => ({
 	coordination: e.disableAdvisory ? "row-based" : "advisory",
 	dialect: e.dialectId ?? "unknown",
 	mode: e.mode,
 	...e.disableAdvisory && e.mode === "auto" ? { reason: "wsrep/Galera cluster detected" } : {}
-}), ye = () => {
+}), we = () => {
 	let e = (e) => {
 		if (e === void 0) return;
 		let t = Number(e);
@@ -357,72 +365,75 @@ var w = f.parseJson(f.Struct({
 		...n === void 0 ? {} : { failoverHeartbeatSeconds: n },
 		...r === void 0 ? {} : { messagePollSeconds: r }
 	};
-}, be = c.flatMap(x.Sharding, (e) => e.pollStorage), Y = /* @__PURE__ */ new Set(), xe = (e) => {
+}, Te = c.flatMap(y.Sharding, (e) => e.pollStorage), Y = /* @__PURE__ */ new Set(), Ee = (e) => {
 	let t = G({
 		runnerStorage: e.runnerStorage,
 		runnerListenHost: e.runnerListenHost,
 		runnerListenPort: e.runnerListenPort
 	}), i = t.host, a = t.port;
 	t.localhostRisk && !Y.has(i) && (Y.add(i), W.warn("runner host is not routable from other pods with SQL cluster storage — a workflow cannot resume on another pod after a reschedule. Inject POD_IP via the K8s downward API (fieldRef: status.podIP) or set runnerListenHost / VOLTRO_WORKFLOW_RUNNER_HOST.", { runnerHost: i }));
-	let d = me({ runnerStorage: e.runnerStorage }).pipe(l.provide(e.sqlClientLayer)), f = e.shardLockMode ?? K(), p = l.unwrapEffect(J({
+	let d = B({
+		runnerStorage: e.runnerStorage,
+		charset: e.charset
+	}).pipe(l.provide(e.sqlClientLayer)), f = e.shardLockMode ?? K(), p = l.unwrapEffect(J({
 		dialectId: e.dialectId,
 		runnerStorage: e.runnerStorage,
 		mode: f
 	}).pipe(c.map((t) => {
-		e.runnerStorage === "sql" && W.info("shard-lock coordination", ve({
+		e.runnerStorage === "sql" && W.info("shard-lock coordination", Ce({
 			disableAdvisory: t,
 			dialectId: e.dialectId,
 			mode: f
 		}));
-		let r = l.effect(n, c.flatMap(x.Sharding, (n) => U({
-			ownAddress: b.make(i, a).toString(),
+		let r = l.effect(n, c.flatMap(y.Sharding, (n) => U({
+			ownAddress: v.make(i, a).toString(),
 			shardLockMode: e.runnerStorage === "sql" ? t ? "row" : "advisory" : "none",
 			runnerStorage: e.runnerStorage,
 			dialectId: e.dialectId,
-			hasShard: (e) => n.hasShardId(te.ShardId.fromString(e))
-		}))), o = re.layer({
+			hasShard: (e) => n.hasShardId(re.ShardId.fromString(e))
+		}))), o = ae.layer({
 			runnerStorage: e.runnerStorage,
 			shardingConfig: {
-				runnerAddress: u.some(b.make(i, a)),
-				runnerListenAddress: u.some(b.make(i, a)),
+				runnerAddress: u.some(v.make(i, a)),
+				runnerListenAddress: u.some(v.make(i, a)),
 				...t ? { shardLockDisableAdvisory: !0 } : {},
 				...e.failoverLeaseSeconds === void 0 ? {} : { shardLockExpiration: s.seconds(e.failoverLeaseSeconds) },
 				...e.failoverHeartbeatSeconds === void 0 ? {} : { shardLockRefreshInterval: s.seconds(e.failoverHeartbeatSeconds) },
 				...e.messagePollSeconds === void 0 ? {} : { entityMessagePollInterval: s.seconds(e.messagePollSeconds) }
 			}
 		});
-		return l.merge(r, l.effect(T, pe)).pipe(l.provideMerge(o));
-	}))).pipe(l.provide(d)), m = e.extraShardingLayers ?? [], h = m.length === 0 ? g.layer : l.mergeAll(g.layer, ...m), _ = p.pipe(l.map((e) => o.add(e, x.Sharding, r(o.get(e, x.Sharding)))));
+		return l.merge(r, l.effect(w, _e)).pipe(l.provideMerge(o));
+	}))).pipe(l.provide(d)), m = e.extraShardingLayers ?? [], h = m.length === 0 ? g.layer : l.mergeAll(g.layer, ...m), _ = p.pipe(l.map((e) => o.add(e, y.Sharding, r(o.get(e, y.Sharding)))));
 	return h.pipe(l.provideMerge(_));
-}, Se = (e) => m.make({
+}, X = (e) => m.make({
 	name: e.name,
 	cron: e.cron,
 	execute: c.promise(() => e.execute()),
 	skipIfOlderThan: e.skipIfOlderThan ?? s.days(1)
-}), X = (e, t) => `${e}/${t}`, Ce = (e, t, n) => {
-	let r = v.make(t), i = o.get(e.annotations, h.ShardGroup)(r);
+}), Z = (e, t) => `${e}/${t}`, De = (e, t, n) => {
+	let r = ee.make(t), i = o.get(e.annotations, h.ShardGroup)(r);
 	return new _.EntityAddress({
-		entityType: ee.EntityType.make(`Workflow/${e.name}`),
+		entityType: te.EntityType.make(`Workflow/${e.name}`),
 		entityId: r,
 		shardId: n.getShardId(r, i)
 	});
-}, Z = f.decodeUnknownOption(f.Exit({
+}, Q = f.decodeUnknownOption(f.Exit({
 	success: f.Unknown,
 	failure: f.Unknown,
 	defect: f.Unknown
-})), we = (e) => {
-	let t = (e) => e && typeof e == "object" && "_tag" in e && typeof e._tag == "string" ? e._tag : void 0, n = Z(e);
+})), Oe = (e) => {
+	let t = (e) => e && typeof e == "object" && "_tag" in e && typeof e._tag == "string" ? e._tag : void 0, n = Q(e);
 	if (u.isNone(n)) return "unrecognized-reply";
 	if (n.value._tag === "Failure") return "failed";
 	let r = n.value.value, i = t(r);
 	if (i === "Suspended") return "suspended";
 	if (i === "Complete") {
-		let e = r.exit, t = Z(e);
+		let e = r.exit, t = Q(e);
 		return u.isNone(t) ? "unrecognized-reply" : t.value._tag === "Success" ? "succeeded" : "failed";
 	}
 	return "unrecognized-reply";
-}, Q = (e) => $(e.workflow, e.executionId, e.failedActivities), Te = (e) => $(e.workflow, e.executionId, e.resetActivities), $ = (e, t, n) => c.gen(function* () {
-	let r = yield* x.Sharding, i = yield* y.MessageStorage, a = Ce(e, t, r), o = yield* i.requestIdForPrimaryKey({
+}, ke = (e) => $(e.workflow, e.executionId, e.failedActivities), Ae = (e) => $(e.workflow, e.executionId, e.resetActivities), $ = (e, t, n) => c.gen(function* () {
+	let r = yield* y.Sharding, i = yield* ne.MessageStorage, a = De(e, t, r), o = yield* i.requestIdForPrimaryKey({
 		address: a,
 		tag: "run",
 		id: ""
@@ -440,7 +451,7 @@ var w = f.parseJson(f.Struct({
 		activitiesReset: 0,
 		reason: "no-reply"
 	};
-	let l = we(s.exit);
+	let l = Oe(s.exit);
 	if (l !== "failed") return {
 		redriven: !1,
 		runReplyCleared: !1,
@@ -452,7 +463,7 @@ var w = f.parseJson(f.Struct({
 		let t = yield* i.requestIdForPrimaryKey({
 			address: a,
 			tag: "activity",
-			id: X(e.name, e.attempt)
+			id: Z(e.name, e.attempt)
 		}).pipe(c.orDie);
 		if (u.isNone(t)) return {
 			redriven: !1,
@@ -486,4 +497,4 @@ var w = f.parseJson(f.Struct({
 	};
 });
 //#endregion
-export { ge as a, be as c, _e as d, J as f, T as h, Se as i, ye as l, U as m, Q as n, q as o, xe as p, Te as r, K as s, X as t, G as u };
+export { xe as a, Te as c, Se as d, J as f, w as g, B as h, X as i, we as l, U as m, ke as n, q as o, Ee as p, Ae as r, K as s, Z as t, G as u };

package/dist/cluster.d.ts

@@ -6,6 +6,7 @@ import { Duration } from 'effect';
 import { Effect } from 'effect';
 import { Layer } from 'effect';
 import { MessageStorage } from '@effect/cluster';
+import { MysqlCharset } from '@voltro/database/sql';
 import { Sharding } from '@effect/cluster';
 import { SqlClient } from '@effect/sql';
 import { SqlError } from '@effect/sql';
@@ -349,6 +350,21 @@ declare interface ClusterMessageState {
     readonly lastRead: Date | null;
 }
 
+/**
+ * A pass-through `SqlClient` layer that runs the cluster first-boot migration
+ * (serialized behind the reserved-connection migration lock) as a build
+ * side-effect, then re-exposes the SAME `SqlClient`. Provided in place of the raw
+ * dialect SqlClient layer so the cluster engine consumes THIS one — forcing the
+ * migration to complete before `SingleRunner` builds and hits its own (now no-op)
+ * DDL. Skipped entirely on the warm path, so a running cluster and single-runner
+ * restarts cost nothing.
+ */
+export declare const clusterMigrationGateLayer: (opts: {
+    readonly runnerStorage: RunnerStorage;
+    /** The declared store charset (mysql family) — the tables this gate creates are created in it. */
+    readonly charset?: MysqlCharset | undefined;
+}) => Layer.Layer<SqlClient.SqlClient, SqlError.SqlError, SqlClient.SqlClient>;
+
 declare interface ClusterRunner {
     readonly address: string;
     readonly lastHeartbeat: Date | null;
@@ -978,6 +994,13 @@ export declare interface WorkflowEngineLayerOptions {
     readonly shardLockMode?: ShardLockMode;
     readonly runnerListenHost?: string;
     readonly runnerListenPort?: number;
+    /**
+     * The declared store charset (`store: { dialect, charset }`, mysql family).
+     * The engine's tables are created by the library with no character set named;
+     * the migration gate converts the ones it creates to this, so a workflow input
+     * with a 4-byte character is not refused on a `utf8mb3` server.
+     */
+    readonly charset?: MysqlCharset | undefined;
     /**
      * FAILOVER TUNING — the two knobs that govern how fast a SURVIVING replica
      * takes over a CRASHED replica's in-flight workflows. Reclaim is a

package/dist/cluster.js

@@ -1,2 +1,2 @@
-import { a as e, c as t, d as n, f as r, h as i, i as a, l as o, m as s, n as c, o as l, p as u, r as d, s as f, t as p, u as m } from "./cluster-DJittOqj.js";
-export { e as DEFAULT_RUNNER_LISTEN_PORT, i as WorkflowResumeDispatcher, p as activityPrimaryKey, l as detectWsrepCluster, a as makeClusterCronLayer, s as makeClusterDiagnostics, f as parseShardLockMode, t as pollWorkflowStorage, c as redriveFailedRun, o as resolveFailoverTuning, m as resolveRunnerIdentity, n as resolveRunnerStorage, r as resolveShardLockDisableAdvisory, d as resumeRunFromStep, u as workflowEngineLayer };
+import { a as e, c as t, d as n, f as r, g as i, h as a, i as o, l as s, m as c, n as l, o as u, p as d, r as f, s as p, t as m, u as h } from "./cluster-D7VuRhM0.js";
+export { e as DEFAULT_RUNNER_LISTEN_PORT, i as WorkflowResumeDispatcher, m as activityPrimaryKey, a as clusterMigrationGateLayer, u as detectWsrepCluster, o as makeClusterCronLayer, c as makeClusterDiagnostics, p as parseShardLockMode, t as pollWorkflowStorage, l as redriveFailedRun, s as resolveFailoverTuning, h as resolveRunnerIdentity, n as resolveRunnerStorage, r as resolveShardLockDisableAdvisory, f as resumeRunFromStep, d as workflowEngineLayer };

package/dist/clusterTestSuite.d.ts

@@ -1,5 +1,6 @@
 import { ConfigError } from 'effect';
 import { Layer } from 'effect';
+import { MysqlCharset } from '@voltro/database/sql';
 import { Sharding } from '@effect/cluster';
 import { SqlClient } from '@effect/sql';
 import { SqlError } from '@effect/sql';
@@ -145,6 +146,13 @@ declare interface WorkflowEngineLayerOptions {
     readonly shardLockMode?: ShardLockMode;
     readonly runnerListenHost?: string;
     readonly runnerListenPort?: number;
+    /**
+     * The declared store charset (`store: { dialect, charset }`, mysql family).
+     * The engine's tables are created by the library with no character set named;
+     * the migration gate converts the ones it creates to this, so a workflow input
+     * with a 4-byte character is not refused on a `utf8mb3` server.
+     */
+    readonly charset?: MysqlCharset | undefined;
     /**
      * FAILOVER TUNING — the two knobs that govern how fast a SURVIVING replica
      * takes over a CRASHED replica's in-flight workflows. Reclaim is a

package/dist/clusterTestSuite.js

@@ -1,6 +1,6 @@
-import { F as e, L as t, S as n, g as r, v as i } from "./primitives-bv2JHUfk.js";
-import { r as a } from "./src-C8oxXvy6.js";
-import { i as o, p as s } from "./cluster-DJittOqj.js";
+import { F as e, R as t, S as n, g as r, v as i } from "./primitives-BJBn8tiH.js";
+import { r as a } from "./src-D_GRCNhv.js";
+import { i as o, p as s } from "./cluster-D7VuRhM0.js";
 import { Cron as c, Deferred as l, Effect as u, Fiber as d, Layer as f, Schema as p } from "effect";
 import { SqlClient as m } from "@effect/sql";
 import { beforeAll as h, describe as g, expect as _, test as v } from "vitest";

package/dist/index.d.ts

@@ -1368,6 +1368,28 @@ export declare const CurrentWorkflowReplayShape: FiberRef.FiberRef<ReplayShapeTr
  *  `Effect.locally(CurrentWorkflowRunId, runId)`. */
 export declare const CurrentWorkflowRunId: FiberRef.FiberRef<string | undefined>;
 
+/**
+ * FiberRef carrying the name of the `step()` whose body is running — set by
+ * `step()` around its execute, `undefined` everywhere else.
+ *
+ * It exists so work a step does OUTSIDE the process can be deduplicated
+ * without the author spelling a key: a call to another app of the project made
+ * inside a step is re-sent when the step is retried after its reply was lost,
+ * and `(executionId, step, call)` is the identity that makes the second send a
+ * replay. Read through `currentWorkflowStep`, never directly.
+ */
+export declare const CurrentWorkflowStep: FiberRef.FiberRef<string | undefined>;
+
+/**
+ * The step this fiber is running inside, with its durable execution — or
+ * `undefined` outside a recorded step. Stable across replays and retries of the
+ * same step, and different for every other step and every other run.
+ */
+export declare const currentWorkflowStep: Effect.Effect<{
+    readonly executionId: string;
+    readonly step: string;
+} | undefined>;
+
 /**
  * Stop retrying an intent whose exact payload can never start.
  *