@voltro/workflow 0.85.0 → 0.87.0

package/dist/clusterLayer.js

@@ -0,0 +1,145 @@
+import { JournalRoutingGuard as e } from "./journalRoutingGuard.js";
+import { withWorkflowDelivery as t } from "./workflowDelivery.js";
+import { ClusterDiagnostics as n } from "./clusterDiagnostics.js";
+import { WorkflowRuntimeReadiness as r, makeWorkflowRuntimeReadiness as i } from "./workflowRuntimeReadiness.js";
+import { journalRoutingLayout as a } from "./journalRoutingLayout.js";
+import { recordWorkflowExecutorRouting as o } from "./workflowExecutorRouting.js";
+import { JournalRoutingLayout as s, withJournalWorkflowRouting as c } from "./journalRoutingRuntime.js";
+import { captureWorkflowShardGroups as ee } from "./clusterShardGroups.js";
+import { acquireGuardedPostgresJournalRoutingAdmission as te, captureJournalRoutingState as l } from "./journalRoutingState.js";
+import { WorkflowResumeDispatcher as u, makeWorkflowResumeDispatcher as d } from "./workflowResumeDispatch.js";
+import { WorkflowRestartDispatcher as f, makeWorkflowRestartDispatcher as p } from "./workflowRestartDispatch.js";
+import { clusterMigrationGateLayer as ne } from "./clusterMigrationGate.js";
+import { clusterRunnerLayer as m } from "./clusterRunnerLayer.js";
+import { acquireSqliteWorkflowOwnership as h } from "./sqliteWorkflowOwnership.js";
+import { makeClusterDiagnostics as g } from "./clusterDiagnosticsSql.js";
+import { WorkflowEngine as _ } from "effect/workflow";
+import { RateLimiter as v } from "effect/persistence";
+import { Context as y, Duration as b, Effect as x, Layer as S, Option as C } from "effect";
+import { SqlClient as w } from "effect/sql";
+import { ClusterWorkflowEngine as T, MessageStorage as E, RunnerAddress as D, ShardId as O, Sharding as k } from "effect/cluster";
+import { sqlPoolCapacity as A } from "@voltro/database/sql";
+import { createLogger as j } from "@voltro/logger";
+//#region src/clusterLayer.ts
+var M = j({ scope: "voltro:workflow" }), N = 34e3, P = (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")
+	};
+}, F = (e) => {
+	let t = e.sqlRunnerSupported ?? !e.sqliteFamily, n = t ? "sql" : "memory", r = e.override ?? process.env.VOLTRO_WORKFLOW_RUNNER_STORAGE;
+	if (r === void 0 || r.trim() === "") return n;
+	let i = r.trim().toLowerCase();
+	if (i !== "memory" && i !== "sql") throw Error(`VOLTRO_WORKFLOW_RUNNER_STORAGE must be 'memory' or 'sql', got '${r}'.`);
+	if (i === "sql" && !t) throw Error("VOLTRO_WORKFLOW_RUNNER_STORAGE='sql' is unsupported for this database connection. Use 'memory' for a local or embedded SQLite-family connection.");
+	return i;
+}, I = (e = process.env.VOLTRO_WORKFLOW_SHARD_LOCK) => {
+	if (e === void 0 || e.trim() === "") return "auto";
+	let t = e.trim().toLowerCase();
+	if (t === "auto" || t === "row" || t === "advisory") return t;
+	throw Error(`VOLTRO_WORKFLOW_SHARD_LOCK must be 'auto', 'row', or 'advisory', got '${e}'.`);
+}, L = x.gen(function* () {
+	let e = yield* (yield* w.SqlClient)`SELECT @@wsrep_on AS wsrep`.pipe(x.catch(() => x.succeed([])));
+	if (e.length === 0) return !1;
+	let t = e[0].wsrep;
+	return t === 1 || t === "1" || t === !0 || t === "ON" || t === "on";
+}), R = (e) => x.gen(function* () {
+	if (e.runnerStorage === "memory") return !1;
+	if (e.dialectId === "sqlite" || e.dialectId === "turso" || e.mode === "row") return !0;
+	if (e.mode === "advisory") return !1;
+	if (e.dialectId === "postgres") {
+		let e = (yield* (yield* w.SqlClient)`SELECT current_schema() AS schema`.pipe(x.orDie))[0]?.schema;
+		return e ? e !== "public" : yield* x.die(/* @__PURE__ */ Error("PostgreSQL workflow coordination requires an accessible current schema"));
+	}
+	return e.dialectId !== "mysql" && e.dialectId !== "mariadb" ? !1 : yield* L;
+}), z = (e) => ({
+	coordination: e.disableAdvisory ? "row-based" : "advisory",
+	dialect: e.dialectId ?? "unknown",
+	mode: e.mode,
+	...e.disableAdvisory && e.mode === "auto" ? { reason: e.dialectId === "sqlite" || e.dialectId === "turso" ? "SQLite-family connection uses row locks" : e.dialectId === "postgres" ? "PostgreSQL non-public schema uses row leases" : "wsrep/Galera cluster detected" } : {}
+}), B = () => {
+	let e = (e) => {
+		if (e === void 0) return;
+		let t = Number(e);
+		return Number.isFinite(t) && t > 0 ? t : void 0;
+	}, t = e(process.env.VOLTRO_WORKFLOW_FAILOVER_LEASE), n = e(process.env.VOLTRO_WORKFLOW_FAILOVER_HEARTBEAT), r = e(process.env.VOLTRO_WORKFLOW_POLL_INTERVAL);
+	return {
+		...t === void 0 ? {} : { failoverLeaseSeconds: t },
+		...n === void 0 ? {} : { failoverHeartbeatSeconds: n },
+		...r === void 0 ? {} : { messagePollSeconds: r }
+	};
+}, V = x.flatMap(k.Sharding, (e) => e.pollStorage), H = /* @__PURE__ */ new Set(), U = (e) => Object.assign(Object.create(Object.getPrototypeOf(e)), e, { requestIdForPrimaryKey: (t) => e.requestIdForPrimaryKey(t).pipe(x.provideService(w.SafeIntegers, !0)) }), W = (j) => {
+	let N = j.runnerMode === void 0 ? "worker" : j.runnerMode;
+	if (N !== "worker" && N !== "client") throw Error("Invalid workflow runner mode");
+	let F = N === "client", L = j.journalRouting === void 0 ? void 0 : l(j.journalRouting);
+	if (L !== void 0 && j.dialectId !== "postgres") throw Error("Guarded journal routing currently requires PostgreSQL");
+	let B = L === void 0 ? void 0 : a(L.layout), V = ee(j.shardGroups ?? (B === void 0 ? void 0 : {
+		available: B.available,
+		assigned: F ? [] : B.available
+	}), F);
+	if (B !== void 0 && (V?.available.length !== B.available.length || B.available.some((e) => !V?.available.includes(e)))) throw Error("Shard inventory must match the admitted journal routing layout");
+	if (F && (j.runnerStorage !== "sql" || j.dialectId === "sqlite")) throw Error("Client-only workflows require shared remote SQL runner storage");
+	if (F && (j.extraShardingLayers?.length ?? 0) > 0) throw Error("Client-only workflows cannot own extra sharding layers");
+	let W = P({
+		runnerStorage: j.runnerStorage,
+		runnerListenHost: j.runnerListenHost,
+		runnerListenPort: j.runnerListenPort
+	}), G = W.host, K = W.port;
+	!F && W.localhostRisk && !H.has(G) && (H.add(G), M.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: G }));
+	let q = j.dialectId === "sqlite" ? S.effect(w.SqlClient, x.gen(function* () {
+		let e = yield* w.SqlClient, t = (yield* e.unsafe("PRAGMA database_list")).find((e) => e.name === "main");
+		return t === void 0 ? yield* x.die(/* @__PURE__ */ Error("SQLite workflow connection has no main database")) : (t.file !== "" && (yield* h(t.file)), e);
+	}).pipe(x.orDie)).pipe(S.provide(j.sqlClientLayer)) : j.sqlClientLayer, J = ne({
+		runnerStorage: j.runnerStorage,
+		charset: j.charset
+	}).pipe(S.provide(q)), Y = L === void 0 ? J : S.effect(e, x.gen(function* () {
+		let e = yield* w.SqlClient, t = A(e), n = j.runnerStorage === "sql" ? 3 : 2;
+		return t !== void 0 && t < n ? yield* x.die(/* @__PURE__ */ Error(`Guarded journal routing requires at least ${n} SQL connections for the admission lock, runner ownership and journal work`)) : yield* te(L);
+	}).pipe(x.orDie)).pipe(S.provideMerge(J)), X = j.shardLockMode ?? I(), re = S.unwrap(R({
+		dialectId: j.dialectId,
+		runnerStorage: j.runnerStorage,
+		mode: X
+	}).pipe(x.map((e) => {
+		!F && j.runnerStorage === "sql" && M.info("shard-lock coordination", z({
+			disableAdvisory: e,
+			dialectId: j.dialectId,
+			mode: X
+		}));
+		let t = S.effect(n, x.flatMap(k.Sharding, (t) => g({
+			ownAddress: D.make(G, K).toString(),
+			shardLockMode: j.runnerStorage === "sql" ? e ? "row" : "advisory" : "none",
+			runnerStorage: j.runnerStorage,
+			dialectId: j.dialectId,
+			hasShard: (e) => t.hasShardId(O.fromString(e))
+		}))), a = {
+			...V === void 0 ? {} : {
+				availableShardGroups: V.available,
+				assignedShardGroups: V.assigned
+			},
+			runnerAddress: F ? C.none() : C.some(D.make(G, K)),
+			runnerListenAddress: F ? C.none() : C.some(D.make(G, K)),
+			...e ? { shardLockDisableAdvisory: !0 } : {},
+			...j.failoverLeaseSeconds === void 0 ? {} : { shardLockExpiration: b.seconds(j.failoverLeaseSeconds) },
+			...j.failoverHeartbeatSeconds === void 0 ? {} : { shardLockRefreshInterval: b.seconds(j.failoverHeartbeatSeconds) },
+			...j.messagePollSeconds === void 0 ? {} : { entityMessagePollInterval: b.seconds(j.messagePollSeconds) }
+		}, o = b.seconds(j.failoverHeartbeatSeconds ?? 10), s = m({
+			clientOnly: F,
+			runnerStorage: j.runnerStorage,
+			shardingConfig: a,
+			guard: {
+				interval: o,
+				giveUpAfter: b.times(o, 3),
+				log: M
+			}
+		});
+		return S.mergeAll(S.effect(r, i), t, S.effect(u, d), S.effect(f, p)).pipe(S.provideMerge(s));
+	}))).pipe(S.provide(L === void 0 ? Y : S.merge(Y, S.succeed(s, L.layout)))), Z = j.extraShardingLayers ?? [], Q = F ? S.effect(_.WorkflowEngine, T.make) : T.layer, $ = L === void 0 ? Q : Q.pipe(S.flatMap((e) => S.succeed(_.WorkflowEngine, c(y.get(e, _.WorkflowEngine), L.layout)))), ie = Z.length === 0 ? $ : S.mergeAll($, ...Z), ae = S.flatMap(re, (e) => {
+		let n = y.add(e, k.Sharding, t(y.get(e, k.Sharding)));
+		return S.succeedContext(j.dialectId === "sqlite" ? y.add(n, E.MessageStorage, U(y.get(n, E.MessageStorage))) : n);
+	}), oe = v.layer.pipe(S.provide(v.layerStoreMemory));
+	return S.merge(ie, oe).pipe(S.provideMerge(ae), S.flatMap((e) => S.succeedContext(o(e, y.get(e, _.WorkflowEngine), N, L, V))));
+};
+//#endregion
+export { N as DEFAULT_RUNNER_LISTEN_PORT, L as detectWsrepCluster, I as parseShardLockMode, V as pollWorkflowStorage, B as resolveFailoverTuning, P as resolveRunnerIdentity, F as resolveRunnerStorage, R as resolveShardLockDisableAdvisory, z as shardLockLogFields, W as workflowEngineLayer };

package/dist/clusterMigrationGate.js

@@ -0,0 +1,61 @@
+import { webCryptoLayer as e } from "./webCrypto.js";
+import { Effect as t, Layer as n } from "effect";
+import { SqlClient as r } from "effect/sql";
+import { ShardingConfig as i, SqlMessageStorage as a, SqlRunnerStorage as o } from "effect/cluster";
+import { applyUndeclaredCharsetWork as s, fnv1a64 as c, readUndeclaredCharsetColumns as l, resolveMigrationLockSchema as u, sqlPoolCapacity as d, undeclaredCharsetWork as f } from "@voltro/database/sql";
+//#region src/clusterMigrationGate.ts
+var p = 6322741009312601n, m = () => {
+	let e = u();
+	return e === void 0 ? p : c(`voltro_cluster_migration_lock:${e}`) & 9223372036854775807n;
+}, h = () => {
+	let e = `voltro_cluster_migration_${p.toString(36)}`, t = u();
+	if (t === void 0) return e;
+	let n = `${e}_${t}`;
+	return /^[A-Za-z0-9_]+$/.test(t) && n.length <= 64 ? n : `${e}_h${c(`voltro_cluster_migration_lock:${t}`).toString(16)}`;
+}, g = () => {
+	let e = Number(process.env.VOLTRO_CLUSTER_MIGRATION_LOCK_TIMEOUT_MS);
+	return Number.isFinite(e) && e > 0 ? e : 6e4;
+}, _ = 250, v = (e) => e[0]?.[0], y = (e, n) => e.onDialectOrElse({
+	sqlite: () => t.void,
+	mysql: () => n.executeValues(`SELECT GET_LOCK('${h()}', ${Math.ceil(g() / 1e3)})`, []).pipe(t.flatMap((e) => v(e) === 1 || v(e) === "1" ? t.void : t.die(/* @__PURE__ */ Error(`could not acquire cluster migration lock '${h()}' (GET_LOCK timed out)`)))),
+	mssql: () => n.executeValues(`DECLARE @res int; EXEC @res = sp_getapplock @Resource = '${h()}', @LockMode = 'Exclusive', @LockOwner = 'Session', @LockTimeout = ${g()}; SELECT @res`, []).pipe(t.flatMap((e) => Number(v(e) ?? -999) >= 0 ? t.void : t.die(/* @__PURE__ */ Error(`could not acquire cluster migration lock '${h()}' (sp_getapplock ${String(v(e))})`)))),
+	orElse: () => {
+		let e = m().toString(), r = Date.now(), i = n.executeValues(`SELECT pg_try_advisory_lock(${e}::bigint)`, []).pipe(t.flatMap((e) => {
+			let n = v(e);
+			return n === !0 || n === "t" || n === 1 ? t.void : Date.now() - r >= g() ? t.die(/* @__PURE__ */ Error(`could not acquire the cluster migration advisory lock within ${Math.round(g() / 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.)`)) : t.sleep(`${_} millis`).pipe(t.andThen(i));
+		}));
+		return i;
+	}
+}), b = (e, n) => e.onDialectOrElse({
+	sqlite: () => t.void,
+	mysql: () => t.asVoid(n.executeValues(`SELECT RELEASE_LOCK('${h()}')`, [])),
+	mssql: () => t.asVoid(n.executeValues(`EXEC sp_releaseapplock @Resource = '${h()}', @LockOwner = 'Session'`, [])),
+	orElse: () => t.asVoid(n.executeValues(`SELECT pg_advisory_unlock(${m().toString()}::bigint)`, []))
+}), x = (e, n) => e.onDialectOrElse({
+	sqlite: () => !0,
+	orElse: () => !1
+}) ? n : t.scoped(t.gen(function* () {
+	let r = yield* e.reserve;
+	return yield* t.acquireRelease(y(e, r), () => b(e, r).pipe(t.orDie)), yield* n;
+})), S = (e) => e === "sql" ? ["cluster_messages", "cluster_runners"] : ["cluster_messages"], C = (e, n) => e.onDialectOrElse({
+	pg: () => e`SELECT (to_regclass(${n}) IS NOT NULL) AS present`,
+	mysql: () => e`SELECT (COUNT(*) > 0) AS present FROM information_schema.tables WHERE table_schema = DATABASE() AND table_name = ${n}`,
+	mssql: () => e`SELECT CASE WHEN OBJECT_ID(${n}, 'U') IS NULL THEN 0 ELSE 1 END AS present`,
+	orElse: () => e`SELECT (COUNT(*) > 0) AS present FROM sqlite_master WHERE type = 'table' AND name = ${n}`
+}).pipe(t.map((e) => {
+	let t = e[0]?.present;
+	return t === !0 || t === 1 || t === "1" || t === "t" || typeof t == "bigint" && t === 1n;
+}), t.catch(() => t.succeed(!1))), w = (e, n) => t.forEach(S(n), (t) => C(e, t), { concurrency: 1 }).pipe(t.map((e) => e.every(Boolean))), T = (a, o) => t.scoped(t.asVoid(n.build(o.pipe(n.provide(i.layerDefaults), n.provide(n.succeed(r.SqlClient, a)), n.provide(e))))), E = (e, n) => T(e, a.layer).pipe(t.andThen(n === "sql" ? T(e, o.layer) : t.void)), D = (e) => t.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)))), O = (e, n, r) => r === void 0 || !e.onDialectOrElse({
+	mysql: () => !0,
+	orElse: () => !1
+}) ? E(e, n) : t.gen(function* () {
+	let t = yield* D(e);
+	yield* E(e, n);
+	let i = new Set([...yield* D(e)].filter((e) => !t.has(e)));
+	i.size !== 0 && (yield* s(e, f(yield* l(e), /* @__PURE__ */ new Set(), r, i)));
+}), k = (e) => e === "sql" ? 3 : 2, A = (e) => n.effect(r.SqlClient, t.gen(function* () {
+	let n = yield* r.SqlClient, i = k(e.runnerStorage), a = d(n);
+	return a !== void 0 && a < i ? yield* t.die(/* @__PURE__ */ Error(`the workflow runtime needs ${i} database connections at once and the pool has ${a}: ` + (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 ${i}` + (e.runnerStorage === "sql" ? ", or VOLTRO_WORKFLOW_RUNNER_STORAGE=memory for a single-process runtime that needs 2 (no cross-pod shard handoff)." : "."))) : ((yield* w(n, e.runnerStorage)) || (yield* x(n, O(n, e.runnerStorage, e.charset))), n);
+}));
+//#endregion
+export { k as clusterConnectionFloor, A as clusterMigrationGateLayer, C as tableExists, x as withClusterMigrationLock };

package/dist/clusterRunnerLayer.js

@@ -0,0 +1,31 @@
+import { JournalRoutingGuard as e } from "./journalRoutingGuard.js";
+import { JournalRoutingLayout as t, withJournalEntityRouting as n } from "./journalRoutingRuntime.js";
+import { webCryptoLayer as r } from "./webCrypto.js";
+import { withJournalRoutingGuard as i } from "./journalRoutingSharding.js";
+import { guardJournalMessageStorage as a } from "./journalRoutingMessageStorage.js";
+import { guardRunnerStorage as o } from "./runnerStorageGuard.js";
+import { Effect as s, Layer as c, Option as l, Semaphore as u } from "effect";
+import { SqlClient as d } from "effect/sql";
+import { MessageStorage as f, RunnerHealth as p, RunnerStorage as m, Runners as h, Sharding as g, ShardingConfig as _, SqlMessageStorage as v, SqlRunnerStorage as y } from "effect/cluster";
+//#region src/clusterRunnerLayer.ts
+var b = (e) => s.map(u.make(1), (t) => ({
+	...e,
+	release: (n, r) => t.withPermits(1)(s.suspend(() => e.release(n, r)))
+})), x = c.unwrap(s.map(d.SqlClient, (e) => e.onDialectOrElse({
+	sqlite: () => c.effect(m.RunnerStorage, s.flatMap(m.RunnerStorage, b)).pipe(c.provide(y.layer)),
+	orElse: () => y.layer
+}))), S = (e) => c.effect(m.RunnerStorage, s.gen(function* () {
+	let t = yield* d.SqlClient, n = yield* m.RunnerStorage;
+	return yield* o(n, {
+		...e,
+		probe: t`SELECT 1`
+	});
+})).pipe(c.provide(c.orDie(x))), C = c.effect(f.MessageStorage, s.gen(function* () {
+	let t = yield* f.MessageStorage, n = yield* s.serviceOption(e);
+	return l.isSome(n) ? a(t, n.value) : t;
+})).pipe(c.provide(v.layer)), w = c.effect(g.Sharding, s.gen(function* () {
+	let r = yield* g.Sharding, a = yield* s.serviceOption(e), o = yield* s.serviceOption(t), c = l.isSome(o) ? n(r, o.value) : r;
+	return l.isSome(a) ? i(c, a.value) : c;
+})).pipe(c.provide(g.layer)), T = (e) => w.pipe(c.provideMerge(h.layerNoop), c.provideMerge(C), c.provide([e.runnerStorage === "memory" ? m.layerMemory : e.clientOnly ? c.orDie(x) : S(e.guard), p.layerNoop]), c.provide(_.layerFromEnv(e.shardingConfig)), c.provide(r));
+//#endregion
+export { T as clusterRunnerLayer, b as limitSqliteShardReleases };

package/dist/clusterShardGroups.js

@@ -0,0 +1,33 @@
+//#region src/clusterShardGroups.ts
+var e = (e, t) => {
+	if (e === void 0) return;
+	if (!e || typeof e != "object" || Array.isArray(e) || ![Object.prototype, null].includes(Object.getPrototypeOf(e))) throw Error("Workflow shard groups require a plain data object");
+	let n = /* @__PURE__ */ new Map();
+	for (let t of Reflect.ownKeys(e)) {
+		let r = Object.getOwnPropertyDescriptor(e, t);
+		if (typeof t != "string" || !["available", "assigned"].includes(t) || !r.enumerable || !("value" in r)) throw Error("Invalid workflow shard group field");
+		n.set(t, r.value);
+	}
+	let r = (e) => {
+		let t = n.get(e);
+		if (!Array.isArray(t) || t.length > 64 || Reflect.ownKeys(t).length !== t.length + 1) throw Error("Invalid workflow shard group list");
+		let r = [];
+		for (let e = 0; e < t.length; e++) {
+			let n = Object.getOwnPropertyDescriptor(t, String(e));
+			if (!n?.enumerable || !("value" in n) || typeof n.value != "string" || !/^[a-z][a-z0-9._-]{0,31}$/.test(n.value)) throw Error("Invalid workflow shard group name");
+			r.push(n.value);
+		}
+		if (new Set(r).size !== r.length) throw Error("Duplicate workflow shard group");
+		return Object.freeze(r);
+	}, i = r("available"), a = r("assigned");
+	if (i.length === 0) throw Error("Workflow shard group inventory cannot be empty");
+	if (a.some((e) => !i.includes(e))) throw Error("Assigned workflow shard group is unavailable");
+	if (t && a.length > 0) throw Error("Client-only workflows cannot own shard groups");
+	if (!t && a.length === 0) throw Error("Workflow workers require an assigned shard group");
+	return Object.freeze({
+		available: i,
+		assigned: a
+	});
+};
+//#endregion
+export { e as captureWorkflowShardGroups };

package/dist/clusterTestSuite.d.ts

@@ -36,6 +36,11 @@ export declare interface ClusterEngineFixture {
     readonly reachable: () => Promise<boolean>;
 }
 
+declare interface JournalRoutingState {
+    readonly generation: number;
+    readonly layout: string;
+}
+
 /**
  * Clear cluster state left behind by EARLIER runs of this suite.
  *
@@ -122,6 +127,15 @@ declare type ShardLockMode = 'auto' | 'row' | 'advisory';
 export declare const tcpReachable: (host: string, port: number, timeoutMs?: number) => Promise<boolean>;
 
 declare interface WorkflowEngineLayerOptions {
+    /** Client mode submits/polls durable work without registering an executor,
+     * runner heartbeat or shard owner. Requires shared SQL runner storage. */
+    readonly runnerMode?: 'worker' | 'client';
+    /** Opt into the persisted PostgreSQL routing generation and guarded journal.
+     * Requires a completed stop-all routing transition before split ownership. */
+    readonly journalRouting?: JournalRoutingState;
+    /** Explicit cluster-wide routing inventory and this runner's ownership.
+     * Omitted preserves existing routing. Does not migrate persisted addresses. */
+    readonly shardGroups?: WorkflowShardGroups;
     /**
      * The dialect's SqlClient layer (postgres / mysql / mariadb / mssql).
      * For `runnerStorage: 'memory'` it's still required so the cluster's
@@ -204,4 +218,13 @@ declare interface WorkflowEngineLayerOptions {
     readonly extraShardingLayers?: ReadonlyArray<Layer.Layer<never, never, Sharding.Sharding>>;
 }
 
+/** Explicit routing inventory shared by every runner in one cluster. Changing
+ * groups changes persistent addresses; this is not a journal migration. */
+/** Group names are at most 32 ASCII characters: group + colon + a safe integer
+ * slot fits the existing SQL journal shard_id VARCHAR(50) on every dialect. */
+declare interface WorkflowShardGroups {
+    readonly available: ReadonlyArray<string>;
+    readonly assigned: ReadonlyArray<string>;
+}
+
 export { }