@voltro/workflow 0.34.0 → 0.35.0

package/dist/{primitives-oLKOTbvJ.js → primitives-CyQZeT1t.js}

@@ -1,44 +1,44 @@
 import { Activity as e, Activity as t, DurableClock as n, DurableClock as r, DurableQueue as i, DurableQueue as a, DurableRateLimiter as o, DurableRateLimiter as s, Workflow as c, Workflow as l } from "@effect/workflow";
-import { Cause as u, Context as d, Duration as f, Effect as p, Exit as m, FiberRef as h, Option as ee, Schedule as g, Schema as _ } from "effect";
+import { Cause as u, Context as d, Cron as f, Duration as p, Effect as m, Either as h, Exit as ee, FiberRef as g, Option as te, Schedule as _, Schema as ne } from "effect";
 //#region src/flowControl.ts
-var v = (e) => e !== void 0 && (e.debounce !== void 0 || e.singleton !== void 0 || e.concurrency !== void 0 || e.throttle !== void 0 || e.rateLimit !== void 0 || e.batch !== void 0 || e.timeouts?.startMs !== void 0 || e.timeouts?.finishMs !== void 0), y = (e) => e?.cancelOn !== void 0 && e.cancelOn.length > 0, b = [
+var re = (e) => e !== void 0 && (e.debounce !== void 0 || e.singleton !== void 0 || e.concurrency !== void 0 || e.throttle !== void 0 || e.rateLimit !== void 0 || e.batch !== void 0 || e.timeouts?.startMs !== void 0 || e.timeouts?.finishMs !== void 0), v = (e) => e?.cancelOn !== void 0 && e.cancelOn.length > 0, y = [
 	"debounce",
 	"batch",
 	"throttle",
 	"concurrency"
-], x = (e) => {
+], b = (e) => {
 	if (e === void 0) return [];
 	let t = [];
 	return e.debounce !== void 0 && t.push("debounce"), e.batch !== void 0 && t.push("batch"), e.throttle !== void 0 && t.push("throttle"), e.concurrency !== void 0 && t.push("concurrency"), t;
-}, S = (e, t, n) => {
+}, x = (e, t, n) => {
 	let r;
 	try {
-		r = f.toMillis(f.decode(e));
+		r = p.toMillis(p.decode(e));
 	} catch {
 		throw Error(`workflow '${n}': ${t} is not a duration Effect can read (got ${JSON.stringify(e)}). Use a spelled-out unit ('15 minutes', '1 hour', '30 seconds'), a number of milliseconds, or a Duration — the abbreviated forms ('15m', '1h') are NOT accepted.`);
 	}
 	if (!Number.isFinite(r) || r <= 0) throw Error(`workflow '${n}': ${t} must be a positive finite duration, got ${String(e)}`);
 	return r;
-}, C = (e, t, n) => {
+}, S = (e, t, n) => {
 	if (!Number.isInteger(e) || e <= 0) throw Error(`workflow '${n}': ${t} must be a positive integer, got ${String(e)}`);
 	return e;
-}, w = (e, t, n) => {
+}, C = (e, t, n) => {
 	if (typeof e != "function") throw Error(`workflow '${n}': ${t} must be a function of the payload`);
 	return e;
-}, T = (e) => {
+}, w = (e) => {
 	let t = e?.ast?.propertySignatures;
 	if (!Array.isArray(t)) return !1;
 	let n = t.find((e) => e.name === "items");
 	return n !== void 0 && n.type?._tag === "TupleType";
-}, E = (e) => {
+}, T = (e) => {
 	let { workflowName: t, control: n } = e;
 	if (n === void 0) return;
 	let r = { workflowName: t };
 	if (n.debounce !== void 0) {
-		let e = n.debounce, i = S(e.period, "debounce.period", t), a = e.timeout === void 0 ? void 0 : S(e.timeout, "debounce.timeout", t);
+		let e = n.debounce, i = x(e.period, "debounce.period", t), a = e.timeout === void 0 ? void 0 : x(e.timeout, "debounce.timeout", t);
 		if (a !== void 0 && a < i) throw Error(`workflow '${t}': debounce.timeout (${a}ms) is shorter than debounce.period (${i}ms), so the burst can never be collapsed — the run would be admitted before the quiet period could ever elapse. Raise the timeout or lower the period.`);
 		r.debounce = {
-			key: w(e.key, "debounce.key", t),
+			key: C(e.key, "debounce.key", t),
 			periodMs: i,
 			...a === void 0 ? {} : { timeoutMs: a }
 		};
@@ -47,7 +47,7 @@ var v = (e) => e !== void 0 && (e.debounce !== void 0 || e.singleton !== void 0
 		let e = n.singleton;
 		if (e.mode !== "skip" && e.mode !== "cancel") throw Error(`workflow '${t}': singleton.mode must be 'skip' or 'cancel'. There is no default — 'skip' discards the incoming request and 'cancel' discards the running one, and choosing for you would silently throw away work either way.`);
 		r.singleton = {
-			key: w(e.key, "singleton.key", t),
+			key: C(e.key, "singleton.key", t),
 			mode: e.mode
 		};
 	}
@@ -55,34 +55,34 @@ var v = (e) => e !== void 0 && (e.debounce !== void 0 || e.singleton !== void 0
 		let e = n.concurrency;
 		if (e.pool !== void 0 && (typeof e.pool != "string" || e.pool.trim() === "")) throw Error(`workflow '${t}': concurrency.pool must be a non-empty name — it is the identity other workflows declare to share this budget, and an empty one would silently merge every empty-named pool in the deployment into one.`);
 		r.concurrency = {
-			limit: C(e.limit, "concurrency.limit", t),
-			...e.key === void 0 ? {} : { key: w(e.key, "concurrency.key", t) },
+			limit: S(e.limit, "concurrency.limit", t),
+			...e.key === void 0 ? {} : { key: C(e.key, "concurrency.key", t) },
 			...e.pool === void 0 ? {} : { pool: e.pool.trim() }
 		};
 	}
 	if (n.throttle !== void 0) {
 		let e = n.throttle;
 		r.throttle = {
-			limit: C(e.limit, "throttle.limit", t),
-			periodMs: S(e.period, "throttle.period", t),
-			...e.key === void 0 ? {} : { key: w(e.key, "throttle.key", t) }
+			limit: S(e.limit, "throttle.limit", t),
+			periodMs: x(e.period, "throttle.period", t),
+			...e.key === void 0 ? {} : { key: C(e.key, "throttle.key", t) }
 		};
 	}
 	if (n.rateLimit !== void 0) {
 		let e = n.rateLimit;
 		r.rateLimit = {
-			limit: C(e.limit, "rateLimit.limit", t),
-			periodMs: S(e.period, "rateLimit.period", t),
-			...e.key === void 0 ? {} : { key: w(e.key, "rateLimit.key", t) }
+			limit: S(e.limit, "rateLimit.limit", t),
+			periodMs: x(e.period, "rateLimit.period", t),
+			...e.key === void 0 ? {} : { key: C(e.key, "rateLimit.key", t) }
 		};
 	}
 	if (n.batch !== void 0) {
 		let i = n.batch;
-		if (e.payloadSchema !== void 0 && !T(e.payloadSchema)) throw Error(`workflow '${t}': batch is declared, so the workflow's own \`payload\` must be the BATCH shape — \`Schema.Struct({ items: Schema.Array(Item) })\` — while callers start it with a SINGLE item. Declare the item's schema as \`batch.item\`. Checked here rather than at admission because a decode failure on the batching replica is a failure nobody is watching.`);
+		if (e.payloadSchema !== void 0 && !w(e.payloadSchema)) throw Error(`workflow '${t}': batch is declared, so the workflow's own \`payload\` must be the BATCH shape — \`Schema.Struct({ items: Schema.Array(Item) })\` — while callers start it with a SINGLE item. Declare the item's schema as \`batch.item\`. Checked here rather than at admission because a decode failure on the batching replica is a failure nobody is watching.`);
 		r.batch = {
-			...i.key === void 0 ? {} : { key: w(i.key, "batch.key", t) },
-			maxSize: C(i.maxSize, "batch.maxSize", t),
-			timeoutMs: S(i.timeout, "batch.timeout", t),
+			...i.key === void 0 ? {} : { key: C(i.key, "batch.key", t) },
+			maxSize: S(i.maxSize, "batch.maxSize", t),
+			timeoutMs: x(i.timeout, "batch.timeout", t),
 			...i.item === void 0 ? {} : { item: i.item }
 		};
 	}
@@ -91,7 +91,7 @@ var v = (e) => e !== void 0 && (e.debounce !== void 0 || e.singleton !== void 0
 		r.priority = n.priority;
 	}
 	if (n.timeouts !== void 0) {
-		let e = n.timeouts, i = e.start === void 0 ? void 0 : S(e.start, "timeouts.start", t), a = e.finish === void 0 ? void 0 : S(e.finish, "timeouts.finish", t);
+		let e = n.timeouts, i = e.start === void 0 ? void 0 : x(e.start, "timeouts.start", t), a = e.finish === void 0 ? void 0 : x(e.finish, "timeouts.finish", t);
 		(i !== void 0 || a !== void 0) && (r.timeouts = {
 			...i === void 0 ? {} : { startMs: i },
 			...a === void 0 ? {} : { finishMs: a }
@@ -111,7 +111,7 @@ var v = (e) => e !== void 0 && (e.debounce !== void 0 || e.singleton !== void 0
 			if (typeof e?.event != "string" || e.event.length === 0) throw Error(`workflow '${t}': ${r}.event must be a non-empty event name, exactly as ctx.events.publish writes it.`);
 			if (e.schema === void 0 || typeof e.schema.ast != "object") throw Error(`workflow '${t}': ${r}.schema must be a Schema for the event payload. It is decoded before \`match\` runs, so the predicate reads the domain type rather than raw JSON.`);
 			if (typeof e.match != "function") throw Error(`workflow '${t}': ${r}.match is required. Omitting it would mean "cancel every live run of this workflow whenever '${e.event}' is published" — write \`match: () => true\` if that is what you mean, so it is visible in review.`);
-			let i = e.within === void 0 ? void 0 : S(e.within, `${r}.within`, t);
+			let i = e.within === void 0 ? void 0 : x(e.within, `${r}.within`, t);
 			return {
 				event: e.event,
 				schema: e.schema,
@@ -122,9 +122,9 @@ var v = (e) => e !== void 0 && (e.debounce !== void 0 || e.singleton !== void 0
 		});
 		e.length > 0 && (r.cancelOn = e);
 	}
-	if (r.timeouts?.startMs !== void 0 && x(r).length === 0) throw Error(`workflow '${t}': timeouts.start bounds how long a run may sit in the ADMISSION queue, but this workflow declares no control that can defer one (debounce, batch, throttle, concurrency). It would never fire. Use timeouts.finish to bound the run itself.`);
+	if (r.timeouts?.startMs !== void 0 && b(r).length === 0) throw Error(`workflow '${t}': timeouts.start bounds how long a run may sit in the ADMISSION queue, but this workflow declares no control that can defer one (debounce, batch, throttle, concurrency). It would never fire. Use timeouts.finish to bound the run itself.`);
 	return r;
-}, D = (e) => {
+}, E = (e) => {
 	let t = /* @__PURE__ */ new Map();
 	for (let n of e) {
 		let e = n?.concurrency;
@@ -137,7 +137,46 @@ var v = (e) => e !== void 0 && (e.debounce !== void 0 || e.singleton !== void 0
 		else if (r.limit !== e.limit) throw Error(`concurrency pool '${e.pool}': '${n.workflowName}' declares limit ${e.limit}, but ${r.workflows.map((e) => `'${e}'`).join(", ")} declare${r.workflows.length === 1 ? "s" : ""} limit ${r.limit}. A pool is ONE budget — every member must declare the same number, or the enforced limit would depend on which workflow's start arrived first. Align the limits, or give the workflows different pool names if they were never meant to share.`);
 		else r.workflows.push(n.workflowName);
 	}
-}, O = class extends d.Tag("@voltro/WorkflowRunRecorder")() {}, k = h.unsafeMake(void 0), A = h.unsafeMake(void 0), j = h.unsafeMake(void 0), M = h.unsafeMake([]), N = () => h.get(k), P = () => h.get(A), F = class extends d.Tag("@voltro/WorkflowStepInterceptor")() {}, I = (e) => {
+}, D = class extends d.Tag("@voltro/WorkflowRunRecorder")() {}, O = g.unsafeMake(void 0), k = g.unsafeMake(void 0), A = g.unsafeMake(void 0), j = g.unsafeMake([]), M = () => g.get(O), N = () => g.get(k), P = class extends d.Tag("@voltro/WorkflowStepInterceptor")() {}, F = 1440 * 6e4, ie = /* @__PURE__ */ new Set([
+	"skip",
+	"buffer",
+	"cancelOther"
+]), ae = /* @__PURE__ */ new Set([
+	"skip",
+	"latest",
+	"all"
+]), I = (e, t) => {
+	if (t === void 0) return;
+	if (typeof t.timezone != "string" || t.timezone.trim() === "") throw Error(`workflow '${e}': schedule.timezone is required (e.g. "UTC", "Europe/Berlin") — never server-local, which differs between your machine and the container.`);
+	let n = f.parse(t.cron, t.timezone);
+	if (h.isLeft(n)) throw Error(`workflow '${e}': schedule.cron "${t.cron}" (tz="${t.timezone}") is not a valid cron expression — ${String(n.left)}`);
+	let r = t.onOverlap ?? "skip";
+	if (!ie.has(r)) throw Error(`workflow '${e}': schedule.onOverlap must be 'skip' | 'buffer' | 'cancelOther', got ${JSON.stringify(r)}`);
+	let i = t.backfill ?? "skip";
+	if (!ae.has(i)) throw Error(`workflow '${e}': schedule.backfill must be 'skip' | 'latest' | 'all', got ${JSON.stringify(i)}`);
+	let a = F;
+	return t.maxRuntime !== void 0 && (a = L(t.maxRuntime, e)), {
+		cron: t.cron,
+		timezone: t.timezone,
+		...t.payload === void 0 ? {} : { payload: t.payload },
+		onOverlap: r,
+		backfill: i,
+		maxRuntimeMs: a
+	};
+}, L = (e, t) => {
+	let n;
+	try {
+		n = p.toMillis(p.decode(e));
+	} catch {
+		throw Error(`workflow '${t}': schedule.maxRuntime is not a duration Effect can read (got ${JSON.stringify(e)}). Use '2 hours', a number of milliseconds, or a Duration.`);
+	}
+	if (!Number.isFinite(n) || n <= 0) throw Error(`workflow '${t}': schedule.maxRuntime must be a positive finite duration`);
+	return n;
+}, R = "__voltroWorkflowSchedule", z = (e) => {
+	if (typeof e != "object" || !e) return;
+	let t = e[R];
+	return t === void 0 ? void 0 : t;
+}, B = (e) => {
 	let t = /* @__PURE__ */ new Map();
 	for (let n of e) t.set(n.stepName, (t.get(n.stepName) ?? 0) + 1);
 	let n = /* @__PURE__ */ new Map(), r = /* @__PURE__ */ new Set(), i = (e) => r.has(e) ? !1 : (r.add(e), !0);
@@ -166,79 +205,79 @@ var v = (e) => e !== void 0 && (e.debounce !== void 0 || e.singleton !== void 0
 			return e;
 		}
 	};
-}, L = h.unsafeMake(void 0), R = (e) => ({
+}, V = g.unsafeMake(void 0), H = (e) => ({
 	kind: e.kind,
 	stepName: e.stepName,
 	recorded: e.recorded,
 	reached: e.reached,
 	detail: e.detail
-}), z = (e) => p.gen(function* () {
+}), U = (e) => m.gen(function* () {
 	if (e.length === 0) return;
-	let t = yield* h.get(k), n = yield* p.serviceOption(O);
+	let t = yield* g.get(O), n = yield* m.serviceOption(D);
 	if (t === void 0 || n._tag !== "Some") return;
 	let r = n.value;
-	for (let n of e) yield* p.promise(() => r.recordEvent({
+	for (let n of e) yield* m.promise(() => r.recordEvent({
 		runId: t,
 		eventType: "nondeterminism-suspected",
-		payload: R(n)
+		payload: H(n)
 	}).then(() => void 0).catch(() => void 0));
-}), B = (e) => {
+}), W = (e) => {
 	if (typeof e != "object" || !e) return;
 	let t = e.retryAfterMillis;
-	if (typeof t == "number" && Number.isFinite(t) && t >= 0) return f.millis(t);
+	if (typeof t == "number" && Number.isFinite(t) && t >= 0) return p.millis(t);
 	let n = e.retryAfter;
-	if (typeof n == "number" && Number.isFinite(n) && n >= 0) return f.seconds(n);
-}, V = (e) => f.decode(e), H = (e) => typeof e == "object" && e && "_tag" in e ? String(e._tag) : void 0, U = (e) => e !== void 0 && (e.maxAttempts ?? 3) > 1, W = (e) => {
+	if (typeof n == "number" && Number.isFinite(n) && n >= 0) return p.seconds(n);
+}, G = (e) => p.decode(e), K = (e) => typeof e == "object" && e && "_tag" in e ? String(e._tag) : void 0, q = (e) => e !== void 0 && (e.maxAttempts ?? 3) > 1, J = (e) => {
 	if (e.retryable) return e.retryable;
 	if (e.retryableErrors && e.retryableErrors.length > 0) {
 		let t = new Set(e.retryableErrors);
 		return (e) => {
-			let n = H(e);
+			let n = K(e);
 			return n !== void 0 && t.has(n);
 		};
 	}
 	return () => !0;
-}, G = (e) => {
-	let t = e.baseDelay ?? "200 millis", n = e.strategy ?? "exponential", r = e.maxAttempts ?? 3, i = n === "linear" ? g.linear(V(e.step ?? t)) : n === "fixed" ? g.spaced(V(t)) : g.exponential(V(t), e.factor ?? 2);
+}, oe = (e) => {
+	let t = e.baseDelay ?? "200 millis", n = e.strategy ?? "exponential", r = e.maxAttempts ?? 3, i = n === "linear" ? _.linear(G(e.step ?? t)) : n === "fixed" ? _.spaced(G(t)) : _.exponential(G(t), e.factor ?? 2);
 	if (e.maxDelay !== void 0) {
-		let t = V(e.maxDelay);
-		i = g.modifyDelay(i, (e, n) => f.min(n, t));
+		let t = G(e.maxDelay);
+		i = _.modifyDelay(i, (e, n) => p.min(n, t));
 	}
-	(e.jitter ?? !0) === !0 && (i = g.jittered(i));
-	let a = g.intersect(i, g.recurs(Math.max(0, r - 1)));
-	return e.maxElapsed !== void 0 && (a = g.upTo(V(e.maxElapsed))(a)), a;
-}, K = (e, t) => {
-	let n = f.toMillis(V(e.baseDelay ?? "200 millis")), r = e.strategy ?? "exponential", i = r === "fixed" ? n : r === "linear" ? n + f.toMillis(V(e.step ?? e.baseDelay ?? "200 millis")) * (t - 1) : n * (e.factor ?? 2) ** (t - 1);
-	return e.maxDelay !== void 0 && (i = Math.min(i, f.toMillis(V(e.maxDelay)))), (e.jitter ?? !0) === !0 && (i *= Math.random()), i;
-}, q = (e, t, n, r) => p.gen(function* () {
-	let i = t.maxAttempts ?? 3, a = t.maxElapsed === void 0 ? Infinity : f.toMillis(V(t.maxElapsed)), o = yield* p.sync(() => Date.now()), s = 0;
+	(e.jitter ?? !0) === !0 && (i = _.jittered(i));
+	let a = _.intersect(i, _.recurs(Math.max(0, r - 1)));
+	return e.maxElapsed !== void 0 && (a = _.upTo(G(e.maxElapsed))(a)), a;
+}, se = (e, t) => {
+	let n = p.toMillis(G(e.baseDelay ?? "200 millis")), r = e.strategy ?? "exponential", i = r === "fixed" ? n : r === "linear" ? n + p.toMillis(G(e.step ?? e.baseDelay ?? "200 millis")) * (t - 1) : n * (e.factor ?? 2) ** (t - 1);
+	return e.maxDelay !== void 0 && (i = Math.min(i, p.toMillis(G(e.maxDelay)))), (e.jitter ?? !0) === !0 && (i *= Math.random()), i;
+}, ce = (e, t, n, r) => m.gen(function* () {
+	let i = t.maxAttempts ?? 3, a = t.maxElapsed === void 0 ? Infinity : p.toMillis(G(t.maxElapsed)), o = yield* m.sync(() => Date.now()), s = 0;
 	for (;;) {
-		let c = yield* p.exit(e);
-		if (m.isSuccess(c)) return c.value;
-		let l = c.cause, d = u.failureOption(l), h = ee.isSome(d) ? d.value : u.squash(l);
+		let c = yield* m.exit(e);
+		if (ee.isSuccess(c)) return c.value;
+		let l = c.cause, d = u.failureOption(l), f = te.isSome(d) ? d.value : u.squash(l);
 		s += 1;
-		let g = (yield* p.sync(() => Date.now())) - o;
-		if (s >= i || !n(h) || g >= a) return yield* p.failCause(l);
-		r?.(h);
-		let _ = B(h), v = _ === void 0 ? K(t, s) : f.toMillis(_);
-		yield* p.sleep(f.millis(v));
+		let h = (yield* m.sync(() => Date.now())) - o;
+		if (s >= i || !n(f) || h >= a) return yield* m.failCause(l);
+		r?.(f);
+		let g = W(f), _ = g === void 0 ? se(t, s) : p.toMillis(g);
+		yield* m.sleep(p.millis(_));
 	}
-}), J = (e, t, n) => {
-	if (!U(t)) return e;
-	let r = W(t);
-	if (t.respectRetryAfter === !0) return q(e, t, r, n);
-	let i = G(t), a = n ? p.tapError(e, (e) => p.sync(() => {
+}), le = (e, t, n) => {
+	if (!q(t)) return e;
+	let r = J(t);
+	if (t.respectRetryAfter === !0) return ce(e, t, r, n);
+	let i = oe(t), a = n ? m.tapError(e, (e) => m.sync(() => {
 		r(e) && n(e);
 	})) : e;
-	return p.retry(a, {
+	return m.retry(a, {
 		schedule: i,
 		while: r
 	});
-}, Y = Symbol.for("voltro.workflow.workerLayer"), X = Symbol.for("voltro.workflow.version"), Z = "__voltroWorkflowMessages", Q = "__voltroWorkflowFlowControl", te = (e) => typeof e == "object" && !!e && e[Y] === !0, ne = (e) => typeof e == "object" && e && e[X] !== void 0 ? e[X] : {
+}, Y = Symbol.for("voltro.workflow.workerLayer"), X = Symbol.for("voltro.workflow.version"), Z = "__voltroWorkflowMessages", Q = "__voltroWorkflowFlowControl", ue = (e) => typeof e == "object" && !!e && e[Y] === !0, de = (e) => typeof e == "object" && e && e[X] !== void 0 ? e[X] : {
 	version: "1",
 	compatibleWith: ["1"],
 	patches: []
-}, re = ((e) => {
+}, fe = ((e) => {
 	let t = c.make(e), n = e.suspendOnFailure === !0 ? t.annotate(c.SuspendOnFailure, !0) : t, r = String(e.version ?? "1"), i = {
 		version: r,
 		compatibleWith: (e.compatibleWith ?? [r]).map(String),
@@ -254,30 +293,35 @@ var v = (e) => e !== void 0 && (e.debounce !== void 0 || e.singleton !== void 0
 		value: a,
 		enumerable: !1
 	});
-	let o = E({
+	let o = T({
 		workflowName: e.name,
 		payloadSchema: e.payload,
 		control: e
 	});
-	return o !== void 0 && Object.defineProperty(n, Q, {
+	o !== void 0 && Object.defineProperty(n, Q, {
 		value: o,
 		enumerable: !1
+	});
+	let s = I(e.name, e.schedule);
+	return s !== void 0 && Object.defineProperty(n, R, {
+		value: s,
+		enumerable: !1
 	}), n;
-}), ie = (e) => {
+}), pe = (e) => {
 	if (typeof e != "object" || !e) return;
 	let t = e[Q];
 	return t === void 0 ? void 0 : t;
-}, ae = i.make, oe = i.process, se = ((...e) => {
+}, me = i.make, he = i.process, ge = ((...e) => {
 	let t = i.worker(...e);
 	return Object.defineProperty(t, Y, {
 		value: !0,
 		enumerable: !1
 	}), t;
-}), ce = o.rateLimit, $ = (e) => p.gen(function* () {
-	let t = yield* k, r = yield* p.serviceOption(O), i = f.toMillis(f.decode(e.duration));
+}), _e = o.rateLimit, $ = (e) => m.gen(function* () {
+	let t = yield* O, r = yield* m.serviceOption(D), i = p.toMillis(p.decode(e.duration));
 	if (t !== void 0 && r._tag === "Some") {
-		let a = r.value, o = new Date(Date.now() + i).toISOString(), s = yield* j;
-		yield* p.promise(() => a.recordEvent({
+		let a = r.value, o = new Date(Date.now() + i).toISOString(), s = yield* A;
+		yield* m.promise(() => a.recordEvent({
 			runId: t,
 			eventType: "timer-set",
 			payload: {
@@ -288,7 +332,7 @@ var v = (e) => e !== void 0 && (e.debounce !== void 0 || e.singleton !== void 0
 			}
 		}).catch(() => {}));
 		let c = Date.now();
-		yield* n.sleep(e), yield* p.promise(() => a.recordEvent({
+		yield* n.sleep(e), yield* m.promise(() => a.recordEvent({
 			runId: t,
 			eventType: "timer-fired",
 			payload: {
@@ -300,18 +344,18 @@ var v = (e) => e !== void 0 && (e.debounce !== void 0 || e.singleton !== void 0
 		return;
 	}
 	yield* n.sleep(e);
-}), le = (t) => p.gen(function* () {
+}), ve = (t) => m.gen(function* () {
 	let n = (yield* e.make({
 		name: `sleepUntil:${t.name}`,
-		success: _.Number,
-		execute: p.sync(() => t.until instanceof Date ? t.until.getTime() : t.until)
+		success: ne.Number,
+		execute: m.sync(() => t.until instanceof Date ? t.until.getTime() : t.until)
 	})) - Date.now();
 	n <= 0 || (yield* $({
 		name: t.name,
 		duration: `${n} millis`
 	}));
-}), ue = (t, n, r, i) => p.gen(function* () {
-	let a = yield* k, o = yield* e.CurrentAttempt, s = yield* p.serviceOption(O), c = yield* p.serviceOption(F), l = c._tag === "Some" ? c.value.interceptor(n, {
+}), ye = (t, n, r, i) => m.gen(function* () {
+	let a = yield* O, o = yield* e.CurrentAttempt, s = yield* m.serviceOption(D), c = yield* m.serviceOption(P), l = c._tag === "Some" ? c.value.interceptor(n, {
 		runId: a ?? "unrecorded",
 		stepName: t,
 		attempt: o
@@ -320,7 +364,7 @@ var v = (e) => e !== void 0 && (e.debounce !== void 0 || e.singleton !== void 0
 		f = s.value;
 		let e = i === void 0 ? void 0 : (({ retryable: e, ...t }) => t)(i);
 		try {
-			d = yield* p.promise(() => f.startStep({
+			d = yield* m.promise(() => f.startStep({
 				runId: a,
 				stepName: t,
 				attempt: o,
@@ -331,16 +375,16 @@ var v = (e) => e !== void 0 && (e.debounce !== void 0 || e.singleton !== void 0
 			d = void 0;
 		}
 	}
-	let m = Date.now();
-	return yield* J(l, i).pipe(p.tap((e) => d && f ? p.promise(async () => {
+	let p = Date.now();
+	return yield* le(l, i).pipe(m.tap((e) => d && f ? m.promise(async () => {
 		try {
 			await f.endStepSuccess({
 				stepRecordId: d,
 				output: e,
-				durationMs: Date.now() - m
+				durationMs: Date.now() - p
 			});
 		} catch {}
-	}) : p.void), p.tapErrorCause((e) => d && f && !u.isInterruptedOnly(e) ? p.promise(async () => {
+	}) : m.void), m.tapErrorCause((e) => d && f && !u.isInterruptedOnly(e) ? m.promise(async () => {
 		try {
 			let t = u.failureOption(e), n = Array.from(u.failures(e)), r = Array.from(u.defects(e)), i = t._tag === "Some" ? t.value : r[0] ?? u.squash(e), a = i?.message ?? String(i), o = i && typeof i == "object" && "_tag" in i ? String(i._tag) : null;
 			await f.endStepFailure({
@@ -352,27 +396,27 @@ var v = (e) => e !== void 0 && (e.debounce !== void 0 || e.singleton !== void 0
 					failures: n,
 					defects: r
 				},
-				durationMs: Date.now() - m
+				durationMs: Date.now() - p
 			});
 		} catch {}
-	}) : p.void));
-}), de = (e) => p.gen(function* () {
-	let t = yield* h.get(L);
+	}) : m.void));
+}), be = (e) => m.gen(function* () {
+	let t = yield* g.get(V);
 	if (t === void 0) return;
 	let n = t.reach(e);
-	n !== void 0 && (yield* z([n]));
-}), fe = (e, t) => {
+	n !== void 0 && (yield* U([n]));
+}), xe = (e, t) => {
 	let n = e;
 	return {
 		...e,
-		commit: () => p.zipRight(de(t), n)
+		commit: () => m.zipRight(be(t), n)
 	};
-}, pe = (t) => {
+}, Se = (t) => {
 	let { input: n, retry: r, ...i } = t;
-	return fe(e.make({
+	return xe(e.make({
 		...i,
-		execute: ue(i.name, i.execute, n, r)
+		execute: ye(i.name, i.execute, n, r)
 	}), i.name);
-}, me = (e) => p.map(h.get(M), (t) => t.includes(e)), he = c.withCompensation, ge = e.idempotencyKey;
+}, Ce = (e) => m.map(g.get(j), (t) => t.includes(e)), we = c.withCompensation, Te = e.idempotencyKey;
 //#endregion
-export { k as A, v as B, l as C, z as D, R as E, N as F, b as I, D as L, O as M, F as N, A as O, P, x as R, re as S, I as T, E as V, le as _, r as a, t as b, s as c, te as d, me as f, $ as g, ce as h, Y as i, j, M as k, ie as l, se as m, Z as n, ae as o, oe as p, X as r, a as s, Q as t, ne as u, pe as v, L as w, he as x, ge as y, y as z };
+export { z as A, y as B, l as C, U as D, H as E, A as F, T as G, b as H, D as I, P as L, k as M, j as N, F as O, O as P, N as R, fe as S, B as T, v as U, E as V, re as W, ve as _, r as a, t as b, s as c, ue as d, Ce as f, $ as g, _e as h, Y as i, I as j, R as k, pe as l, ge as m, Z as n, me as o, he as p, X as r, a as s, Q as t, de as u, Se as v, V as w, we as x, Te as y, M as z };

package/dist/primitives.d.ts

@@ -41,6 +41,9 @@ declare type DecodedPayload<P> = P extends Schema.Struct.Fields ? Schema.Struct.
     readonly Type: infer T;
 } ? T : never;
 
+/** 24 h — see {@link WorkflowScheduleDeclaration.maxRuntime}. */
+export declare const DEFAULT_WORKFLOW_SCHEDULE_MAX_RUNTIME_MS: number;
+
 /**
  * Controls that can DEFER a start rather than answer it immediately.
  *
@@ -77,6 +80,9 @@ export declare type FlowDuration = Duration.DurationInput;
  *  the path it took before this feature existed. */
 export declare const getWorkflowFlowControl: (value: unknown) => ResolvedFlowControl | undefined;
 
+/** The resolved schedule attached to a workflow definition, or undefined. */
+export declare const getWorkflowSchedule: (value: unknown) => ResolvedWorkflowSchedule | undefined;
+
 export declare const getWorkflowVersionMetadata: (value: unknown) => WorkflowVersionMetadata;
 
 /** `true` when this workflow declares at least one `cancelOn` entry — i.e. when
@@ -303,6 +309,18 @@ export declare interface ResolvedFlowControl {
     readonly cancelOn?: ReadonlyArray<ResolvedCancelOn>;
 }
 
+/** The declaration with defaults filled in — what the CLI lowering reads. */
+export declare interface ResolvedWorkflowSchedule {
+    readonly cron: string;
+    readonly timezone: string;
+    readonly payload?: unknown | ((fire: {
+        readonly scheduledAt: Date;
+    }) => unknown | Promise<unknown>);
+    readonly onOverlap: WorkflowScheduleOverlap;
+    readonly backfill: 'skip' | 'latest' | 'all';
+    readonly maxRuntimeMs: number;
+}
+
 /**
  * Durable sleep — wake time journaled in the cluster. Wrapper around
  * `DurableClock.sleep` that emits `timer-set` / `timer-fired` events
@@ -462,6 +480,14 @@ export declare interface ValidateFlowControlInput {
     readonly control: (WorkflowFlowControl<never> & WorkflowCancelOnDeclared) | undefined;
 }
 
+/**
+ * Validate at DEFINITION time — module load, i.e. boot — with a message naming
+ * the workflow and the field. Same posture as `validateFlowControl` and
+ * `defineSchedule`: a cron typo that surfaces as "never fired" three days in
+ * is the failure class this repo keeps paying for.
+ */
+export declare const validateWorkflowSchedule: (workflowName: string, declaration: WorkflowScheduleDeclaration<never> | undefined) => ResolvedWorkflowSchedule | undefined;
+
 /**
  * Add compensating (rollback) logic to a top-level effect in a workflow
  * body. The finalizer runs if the WHOLE workflow later fails — use it for
@@ -848,6 +874,12 @@ declare type WorkflowFn = <const Name extends string, Payload extends WorkflowPa
      *  type comes from its OWN `schema` — see {@link WorkflowCancelOnList} for
      *  why that needs a tuple type parameter rather than a plain array. */
     readonly cancelOn?: WorkflowCancelOnList<Cancels, DecodedPayload<Payload>>;
+    /** Run this workflow on a cron — the workflow-side spelling of a
+     *  `defineSchedule({ workflow })` target, with Temporal's overlap
+     *  vocabulary (`skip` / `buffer` / `cancelOther`). Lowered by the CLI into
+     *  a real schedule named `workflow:<name>`; see
+     *  {@link WorkflowScheduleDeclaration}. */
+    readonly schedule?: WorkflowScheduleDeclaration<DecodedPayload<Payload>>;
 } & Omit<WorkflowBaseOptions, 'name' | 'payload' | 'idempotencyKey' | 'success' | 'error'> & WorkflowVersionOptions & {
     readonly messages?: Messages;
 } & WorkflowFlowControl<DecodedPayload<Payload>>) => workflowModule.Workflow<Name, PayloadSchemaOf<Payload>, Success, Error> & WorkflowMessagesCarrier<NormaliseWorkflowMessages<Messages>>;
@@ -907,6 +939,68 @@ export declare interface WorkflowRateLimit<Payload> {
     readonly key?: (payload: Payload) => string;
 }
 
+export declare interface WorkflowScheduleDeclaration<Payload> {
+    /** Standard cron expression — 5-field or 6-field (leading seconds). */
+    readonly cron: string;
+    /** IANA timezone the expression is interpreted in. REQUIRED, like
+     *  `defineSchedule` — server-local time in a container is a bug factory. */
+    readonly timezone: string;
+    /**
+     * The payload each firing starts the workflow with. A value, or a function
+     * of the firing (`({ scheduledAt }) => …`) for payloads that carry the slot
+     * — a backfilled firing then computes against ITS instant, not "now".
+     * Omitted ⇒ `{}`, which only typechecks for workflows whose payload has no
+     * required fields; a mismatch fails the start with `WorkflowPayloadError`
+     * naming the missing fields, same as any other start.
+     */
+    readonly payload?: Payload | ((fire: {
+        readonly scheduledAt: Date;
+    }) => Payload | Promise<Payload>);
+    /** Default `'skip'` — Temporal's default too, and the only answer that is
+     *  safe for every job shape. */
+    readonly onOverlap?: WorkflowScheduleOverlap;
+    /** Boot catch-up policy for firings missed during downtime — the scheduler's
+     *  own vocabulary, unchanged. Default `'skip'`. For a RANGE older than boot
+     *  backfill reaches, use `voltro schedule backfill`. */
+    readonly backfill?: 'skip' | 'latest' | 'all';
+    /**
+     * Watchdog on ONE firing — which, for a workflow schedule, INCLUDES the
+     * awaited run (that await is what makes `onOverlap` bind on the run's
+     * duration). Default 24 hours rather than `defineSchedule`'s 30 minutes,
+     * because a durable run legitimately outlives a handler; set it above your
+     * slowest expected run. Past it the FIRING records `failed`/timeout and
+     * releases the overlap guard — the workflow run itself is NOT cancelled
+     * (declare flow-control `timeouts.finish` to bound the run).
+     */
+    readonly maxRuntime?: FlowDuration;
+}
+
+/**
+ * What happens when a firing arrives while the RUN from the previous firing is
+ * still going — Temporal Schedules' overlap vocabulary, applied to the
+ * workflow run (not merely to the handler invocation):
+ *
+ *   `'skip'`        — the new firing stands down; recorded as `skipped`.
+ *   `'buffer'`      — the new firing waits and runs after the previous one
+ *                     finishes; firings serialize, none is lost.
+ *   `'cancelOther'` — the new firing CANCELS the still-running previous run
+ *                     and starts fresh — for "recompute the latest state"
+ *                     jobs where the old run's partial work is worthless.
+ *
+ * The first two lower into the scheduler's own `onOverlap: 'skip' | 'queue'`;
+ * what makes them bind on the RUN's duration is that the synthesised handler
+ * AWAITS the workflow run to completion, so the schedule-run row is `running`
+ * for exactly as long as the workflow is.
+ */
+export declare type WorkflowScheduleOverlap = 'skip' | 'buffer' | 'cancelOther';
+
+/** Attached via `defineProperty` like the flow-control carrier — the value's
+ *  TYPE does not know about it, and the web bundle never reads it. A STRING
+ *  property rather than a symbol for the same reason as
+ *  `WorkflowFlowControlProperty`: the CLI's discovery reads it off a module
+ *  that crossed a bundler boundary, and symbols do not survive every one. */
+export declare const WorkflowScheduleProperty = "__voltroWorkflowSchedule";
+
 /**
  * At most one run per key. The newcomer either stands down or evicts.
  *

package/dist/primitives.js

@@ -1,2 +1,2 @@
-import { B as e, C as t, D as n, E as r, I as i, L as a, R as o, S as s, T as c, V as l, _ as u, a as d, b as f, c as p, d as m, f as h, g, h as _, i as v, l as y, m as b, n as x, o as S, p as C, r as w, s as T, t as E, u as D, v as O, w as k, x as A, y as j, z as M } from "./primitives-oLKOTbvJ.js";
-export { k as CurrentWorkflowReplayShape, i as DEFERRING_CONTROLS, E as WorkflowFlowControlProperty, x as WorkflowMessagesProperty, w as WorkflowVersionTypeId, v as WorkflowWorkerLayerTypeId, a as assertConsistentPools, o as deferringControlsOf, d as durableClock, S as durableQueue, T as durableQueueModule, p as durableRateLimiterModule, y as getWorkflowFlowControl, D as getWorkflowVersionMetadata, M as hasCancelOn, e as hasFlowControl, m as isWorkflowWorkerLayer, c as makeReplayShapeTracker, r as nondeterminismEventPayload, h as patch, C as processQueue, b as queueWorker, _ as rateLimit, n as reportNondeterminism, g as sleep, u as sleepUntil, O as step, j as stepIdempotencyKey, f as stepModule, l as validateFlowControl, A as withCompensation, s as workflow, t as workflowModule };
+import { A as e, B as t, C as n, D as r, E as i, G as a, H as o, O as s, S as c, T as l, U as u, V as d, W as f, _ as p, a as m, b as h, c as g, d as _, f as v, g as y, h as b, i as x, j as S, k as C, l as w, m as T, n as E, o as D, p as O, r as k, s as A, t as j, u as M, v as N, w as P, x as F, y as I } from "./primitives-CyQZeT1t.js";
+export { P as CurrentWorkflowReplayShape, s as DEFAULT_WORKFLOW_SCHEDULE_MAX_RUNTIME_MS, t as DEFERRING_CONTROLS, j as WorkflowFlowControlProperty, E as WorkflowMessagesProperty, C as WorkflowScheduleProperty, k as WorkflowVersionTypeId, x as WorkflowWorkerLayerTypeId, d as assertConsistentPools, o as deferringControlsOf, m as durableClock, D as durableQueue, A as durableQueueModule, g as durableRateLimiterModule, w as getWorkflowFlowControl, e as getWorkflowSchedule, M as getWorkflowVersionMetadata, u as hasCancelOn, f as hasFlowControl, _ as isWorkflowWorkerLayer, l as makeReplayShapeTracker, i as nondeterminismEventPayload, v as patch, O as processQueue, T as queueWorker, b as rateLimit, r as reportNondeterminism, y as sleep, p as sleepUntil, N as step, I as stepIdempotencyKey, h as stepModule, a as validateFlowControl, S as validateWorkflowSchedule, F as withCompensation, c as workflow, n as workflowModule };