@voltro/workflow 0.86.0 → 0.88.0

package/dist/clusterLayer.js

@@ -1,49 +1,65 @@
-import { withWorkflowDelivery as e } from "./workflowDelivery.js";
-import { ClusterDiagnostics as t } from "./clusterDiagnostics.js";
-import { WorkflowResumeDispatcher as n, makeWorkflowResumeDispatcher as r } from "./workflowResumeDispatch.js";
-import { WorkflowRestartDispatcher as i, makeWorkflowRestartDispatcher as a } from "./workflowRestartDispatch.js";
-import { clusterMigrationGateLayer as o } from "./clusterMigrationGate.js";
-import { clusterRunnerLayer as s } from "./clusterRunnerLayer.js";
-import { acquireSqliteWorkflowOwnership as c } from "./sqliteWorkflowOwnership.js";
-import { makeClusterDiagnostics as l } from "./clusterDiagnosticsSql.js";
-import { RateLimiter as u } from "effect/persistence";
-import { Context as d, Duration as f, Effect as p, Layer as m, Option as h } from "effect";
-import { SqlClient as g } from "effect/sql";
-import { ClusterWorkflowEngine as _, MessageStorage as v, RunnerAddress as y, ShardId as b, Sharding as x } from "effect/cluster";
-import { createLogger as S } from "@voltro/logger";
-//#region src/clusterLayer.ts
-var C = S({ scope: "voltro:workflow" }), w = 34e3, T = (e) => {
+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";
+// 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")
 	};
-}, E = (e) => {
+}, 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;
-}, D = (e = process.env.VOLTRO_WORKFLOW_SHARD_LOCK) => {
+}, 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}'.`);
-}, O = p.gen(function* () {
-	let e = yield* (yield* g.SqlClient)`SELECT @@wsrep_on AS wsrep`.pipe(p.catch(() => p.succeed([])));
+}, 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";
-}), k = (e) => p.gen(function* () {
-	return e.runnerStorage === "memory" ? !1 : e.dialectId === "sqlite" || e.dialectId === "turso" || e.mode === "row" ? !0 : e.mode === "advisory" || e.dialectId !== "mysql" && e.dialectId !== "mariadb" ? !1 : yield* O;
-}), A = (e) => ({
+}), 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" : "wsrep/Galera cluster detected" } : {}
-}), j = () => {
+	...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);
@@ -54,57 +70,75 @@ var C = S({ scope: "voltro:workflow" }), w = 34e3, T = (e) => {
 		...n === void 0 ? {} : { failoverHeartbeatSeconds: n },
 		...r === void 0 ? {} : { messagePollSeconds: r }
 	};
-}, M = p.flatMap(x.Sharding, (e) => e.pollStorage), N = /* @__PURE__ */ new Set(), P = (e) => Object.assign(Object.create(Object.getPrototypeOf(e)), e, { requestIdForPrimaryKey: (t) => e.requestIdForPrimaryKey(t).pipe(p.provideService(g.SafeIntegers, !0)) }), F = (S) => {
-	let w = T({
-		runnerStorage: S.runnerStorage,
-		runnerListenHost: S.runnerListenHost,
-		runnerListenPort: S.runnerListenPort
-	}), E = w.host, O = w.port;
-	w.localhostRisk && !N.has(E) && (N.add(E), C.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: E }));
-	let j = S.dialectId === "sqlite" ? m.effect(g.SqlClient, p.gen(function* () {
-		let e = yield* g.SqlClient, t = (yield* e.unsafe("PRAGMA database_list")).find((e) => e.name === "main");
-		return t === void 0 ? yield* p.die(/* @__PURE__ */ Error("SQLite workflow connection has no main database")) : (t.file !== "" && (yield* c(t.file)), e);
-	}).pipe(p.orDie)).pipe(m.provide(S.sqlClientLayer)) : S.sqlClientLayer, M = o({
-		runnerStorage: S.runnerStorage,
-		charset: S.charset
-	}).pipe(m.provide(j)), F = S.shardLockMode ?? D(), I = m.unwrap(k({
-		dialectId: S.dialectId,
-		runnerStorage: S.runnerStorage,
-		mode: F
-	}).pipe(p.map((e) => {
-		S.runnerStorage === "sql" && C.info("shard-lock coordination", A({
+}, 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: S.dialectId,
-			mode: F
+			dialectId: j.dialectId,
+			mode: X
 		}));
-		let o = m.effect(t, p.flatMap(x.Sharding, (t) => l({
-			ownAddress: y.make(E, O).toString(),
-			shardLockMode: S.runnerStorage === "sql" ? e ? "row" : "advisory" : "none",
-			runnerStorage: S.runnerStorage,
-			dialectId: S.dialectId,
-			hasShard: (e) => t.hasShardId(b.fromString(e))
-		}))), c = {
-			runnerAddress: h.some(y.make(E, O)),
-			runnerListenAddress: h.some(y.make(E, O)),
+		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 } : {},
-			...S.failoverLeaseSeconds === void 0 ? {} : { shardLockExpiration: f.seconds(S.failoverLeaseSeconds) },
-			...S.failoverHeartbeatSeconds === void 0 ? {} : { shardLockRefreshInterval: f.seconds(S.failoverHeartbeatSeconds) },
-			...S.messagePollSeconds === void 0 ? {} : { entityMessagePollInterval: f.seconds(S.messagePollSeconds) }
-		}, u = f.seconds(S.failoverHeartbeatSeconds ?? 10), d = s({
-			runnerStorage: S.runnerStorage,
-			shardingConfig: c,
+			...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: u,
-				giveUpAfter: f.times(u, 3),
-				log: C
+				interval: o,
+				giveUpAfter: b.times(o, 3),
+				log: M
 			}
 		});
-		return m.mergeAll(o, m.effect(n, r), m.effect(i, a)).pipe(m.provideMerge(d));
-	}))).pipe(m.provide(M)), L = S.extraShardingLayers ?? [], R = L.length === 0 ? _.layer : m.mergeAll(_.layer, ...L), z = m.flatMap(I, (t) => {
-		let n = d.add(t, x.Sharding, e(d.get(t, x.Sharding)));
-		return m.succeedContext(S.dialectId === "sqlite" ? d.add(n, v.MessageStorage, P(d.get(n, v.MessageStorage))) : n);
-	}), B = u.layer.pipe(m.provide(u.layerStoreMemory));
-	return m.merge(R, B).pipe(m.provideMerge(z));
+		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 { w as DEFAULT_RUNNER_LISTEN_PORT, O as detectWsrepCluster, D as parseShardLockMode, M as pollWorkflowStorage, j as resolveFailoverTuning, T as resolveRunnerIdentity, E as resolveRunnerStorage, k as resolveShardLockDisableAdvisory, A as shardLockLogFields, F as workflowEngineLayer };
+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

@@ -3,7 +3,7 @@ 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
+// src/clusterMigrationGate.ts
 var p = 6322741009312601n, m = () => {
 	let e = u();
 	return e === void 0 ? p : c(`voltro_cluster_migration_lock:${e}`) & 9223372036854775807n;
@@ -57,5 +57,4 @@ var p = 6322741009312601n, m = () => {
 	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

@@ -1,21 +1,30 @@
-import { webCryptoLayer as e } from "./webCrypto.js";
-import { guardRunnerStorage as t } from "./runnerStorageGuard.js";
-import { Effect as n, Layer as r, Semaphore as i } from "effect";
-import { SqlClient as a } from "effect/sql";
-import { RunnerHealth as o, RunnerStorage as s, Runners as c, Sharding as l, ShardingConfig as u, SqlMessageStorage as d, SqlRunnerStorage as f } from "effect/cluster";
-//#region src/clusterRunnerLayer.ts
-var p = (e) => n.map(i.make(1), (t) => ({
+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";
+// src/clusterRunnerLayer.ts
+var b = (e) => s.map(u.make(1), (t) => ({
 	...e,
-	release: (r, i) => t.withPermits(1)(n.suspend(() => e.release(r, i)))
-})), m = r.unwrap(n.map(a.SqlClient, (e) => e.onDialectOrElse({
-	sqlite: () => r.effect(s.RunnerStorage, n.flatMap(s.RunnerStorage, p)).pipe(r.provide(f.layer)),
-	orElse: () => f.layer
-}))), h = (e) => r.effect(s.RunnerStorage, n.gen(function* () {
-	let n = yield* a.SqlClient, r = yield* s.RunnerStorage;
-	return yield* t(r, {
+	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: n`SELECT 1`
+		probe: t`SELECT 1`
 	});
-})).pipe(r.provide(r.orDie(m))), g = (t) => l.layer.pipe(r.provideMerge(c.layerNoop), r.provideMerge(d.layer), r.provide([t.runnerStorage === "memory" ? s.layerMemory : h(t.guard), o.layerNoop]), r.provide(u.layerFromEnv(t.shardingConfig)), r.provide(e));
-//#endregion
-export { g as clusterRunnerLayer, p as limitSqliteShardReleases };
+})).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));
+export { T as clusterRunnerLayer, b as limitSqliteShardReleases };

package/dist/clusterShardGroups.js

@@ -0,0 +1,32 @@
+// 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
+	});
+};
+export { e as captureWorkflowShardGroups };

package/dist/clusterTestSuite.d.ts

@@ -36,6 +36,31 @@ export declare interface ClusterEngineFixture {
     readonly reachable: () => Promise<boolean>;
 }
 
+/** Test-runner operations supplied by the suite caller, outside the runtime graph. */
+export declare interface ClusterSuiteTestApi {
+    readonly describe: (name: string, body: () => void) => unknown;
+    readonly test: (name: string, body: (context: {
+        readonly skip: () => void;
+    }) => Promise<void>, timeoutMs?: number) => unknown;
+    readonly beforeAll: (body: () => Promise<void>, timeoutMs?: number) => unknown;
+    readonly afterEach: (body: () => void | Promise<void>) => unknown;
+    readonly expect: (actual: unknown, message?: string) => {
+        readonly toBe: (expected: unknown) => unknown;
+        readonly toEqual: (expected: unknown) => unknown;
+        readonly toContain: (expected: unknown) => unknown;
+        readonly toBeGreaterThan: (expected: number) => unknown;
+        readonly toBeGreaterThanOrEqual: (expected: number) => unknown;
+        readonly rejects: {
+            readonly toThrow: () => Promise<unknown>;
+        };
+    };
+}
+
+declare interface JournalRoutingState {
+    readonly generation: number;
+    readonly layout: string;
+}
+
 /**
  * Clear cluster state left behind by EARLIER runs of this suite.
  *
@@ -70,9 +95,9 @@ export declare const purgeClusterState: (fixture: ClusterEngineFixture) => Promi
  * `@voltro/sql-*` (or the workflow package) calls this from a thin
  * `cluster.<dialect>.integration.test.ts` with its fixture.
  */
-export declare const runClusterEngineSuite: (fixture: ClusterEngineFixture) => void;
+export declare const runClusterEngineSuite: (fixture: ClusterEngineFixture, tests: ClusterSuiteTestApi) => void;
 
-export declare const runJournalEncryptionSuite: (fixture: ClusterEngineFixture) => void;
+export declare const runJournalEncryptionSuite: (fixture: ClusterEngineFixture, tests: ClusterSuiteTestApi) => void;
 
 /**
  * Runner-storage backend for `effect/cluster.SingleRunner`.
@@ -122,6 +147,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 +238,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 { }