@voltro/workflow 0.84.0 → 0.86.0

package/dist/admissionSubmission.js

@@ -0,0 +1,297 @@
+import { sealErrorText as e } from "./journalEncryption.js";
+import { withAdmissionTransaction as t } from "./admissionTransaction.js";
+import { resolveAdmissionKeys as n } from "./admission.js";
+import { readWorkflowFailureRecord as r, recordWorkflowFailureInTransaction as i } from "./failureReportStore.js";
+import { handoffWorkflowFailureInTransaction as a, isFailureDeliverySubmission as o } from "./failureHandoff.js";
+import { readResidentExecutionEvidence as s } from "./residentExecutionEvidence.js";
+import { ADMISSIONS_TABLE as c, evaluateAdmission as l, recordAdmission as u, retryBackoffMs as d } from "./admissionStore.js";
+import { Schema as f } from "effect";
+import { and as p, eq as m, gt as h, isNull as g } from "@voltro/database";
+import { createHash as _, randomUUID as v } from "node:crypto";
+import { isDeepStrictEqual as y } from "node:util";
+//#region src/admissionSubmission.ts
+var b = "_voltro_workflow_submissions", x = "wfsub", S = () => `${x}_${v()}`, C = f.Struct({
+	id: f.String,
+	workflowName: f.String,
+	tenantId: f.NullOr(f.String),
+	ledgerId: f.String,
+	preparedExecutionId: f.NullOr(f.String),
+	executionId: f.NullOr(f.String),
+	runId: f.NullOr(f.String),
+	receiptsBound: f.Boolean,
+	dispatchAttempts: f.Number.check(f.isInt(), f.isGreaterThanOrEqualTo(0)),
+	failureId: f.NullOr(f.String),
+	retry: f.Struct({
+		attempts: f.Int,
+		after: f.Number,
+		lastError: f.NullOr(f.String),
+		stoppedAt: f.NullOr(f.Number),
+		recovery: f.optional(f.Struct({
+			attempts: f.Int,
+			stoppedAt: f.Number,
+			retriedAt: f.Number
+		}))
+	}),
+	payload: f.Unknown,
+	callerContext: f.Unknown,
+	intentIds: f.Array(f.String),
+	eviction: f.NullOr(f.Struct({
+		executionId: f.String,
+		runId: f.String
+	}))
+}), w = f.decodeUnknownSync(C);
+async function* T(e, t, n) {
+	let r;
+	for (;;) {
+		let i = p(m("preparedExecutionId", t), h("dispatchAttempts", 0)), a = await e.query({
+			table: b,
+			predicate: r === void 0 ? i : p(i, h("id", r)),
+			order: [{
+				column: "id",
+				direction: "asc"
+			}],
+			take: 100,
+			skip: void 0,
+			projection: void 0
+		});
+		if (a.length === 0) return;
+		for (let e of a) {
+			let i = w(e);
+			if (i.workflowName !== n || !i.receiptsBound || i.failureId !== null || i.executionId !== null && i.executionId !== t) throw Error("Workflow completion has an inconsistent resident submission owner");
+			yield i, r = i.id;
+		}
+	}
+}
+var E = async (e, t, n) => (await D(e, t, n)).map((e) => w(e)), D = async (e, t, n) => {
+	if (!Number.isSafeInteger(t) || t < 1) throw Error("Submission recovery requires a positive page size");
+	return e.query({
+		table: b,
+		predicate: n === void 0 ? p(m("receiptsBound", !0), g("executionId"), g("failureId")) : p(m("receiptsBound", !0), g("executionId"), g("failureId"), h("id", n)),
+		order: [{
+			column: "id",
+			direction: "asc"
+		}],
+		take: t,
+		skip: void 0,
+		projection: void 0
+	});
+}, O = async (e, t) => {
+	let n = await e.query({
+		table: b,
+		predicate: m("id", t),
+		order: [],
+		take: 1,
+		skip: void 0,
+		projection: void 0
+	});
+	return n[0] === void 0 ? void 0 : f.decodeUnknownSync(C)(n[0]);
+}, k = async (e, n) => t(e, (e) => A(e, n)), A = async (e, t) => {
+	if (t.id.length === 0) throw Error("Admission submission requires a stable non-empty identity");
+	let r = await e.query({
+		table: b,
+		predicate: m("id", t.id),
+		order: [],
+		take: 1,
+		skip: void 0,
+		projection: void 0
+	});
+	if (r[0] !== void 0) {
+		let e = f.decodeUnknownSync(C)(r[0]);
+		if (e.workflowName !== t.control.workflowName || e.tenantId !== t.tenantId) throw Error("Admission submission identity belongs to a different workflow or tenant");
+		let n = JSON.parse(JSON.stringify(e.payload) ?? "null"), i = JSON.parse(JSON.stringify(t.encodedPayload) ?? "null");
+		if (!y(n, i)) throw Error("Admission submission identity is already bound to a different payload");
+		return {
+			kind: "reserved",
+			submission: e,
+			reused: !0
+		};
+	}
+	let i = n(t.control, t.keyPayload), a = await l({
+		store: e,
+		control: t.control,
+		keys: i,
+		paused: t.paused,
+		now: t.now,
+		reconsidering: !0
+	});
+	if (a.kind !== "admit") return {
+		kind: "not-admitted",
+		decision: a
+	};
+	let o = await u({
+		store: e,
+		control: t.control,
+		keys: i,
+		outcome: "admitted",
+		mode: t.mode,
+		reason: a.reason,
+		collapsed: t.collapsed,
+		waitedMs: t.now - t.firstSeenAt,
+		executionId: null,
+		runId: null,
+		tenantId: t.tenantId,
+		now: t.now
+	});
+	if (o === void 0) throw Error("Admission reservation has no ledger identity");
+	return {
+		kind: "reserved",
+		submission: await j(e, {
+			id: t.id,
+			workflowName: t.control.workflowName,
+			tenantId: t.tenantId,
+			ledgerId: o,
+			payload: t.encodedPayload,
+			callerContext: t.callerContext,
+			intentIds: t.intentIds,
+			eviction: a.evict ?? null
+		}),
+		reused: !1
+	};
+}, j = async (e, t) => {
+	if (t.id.length === 0 || t.ledgerId.length === 0) throw Error("Submission requires its reserved admission identity");
+	let n = {
+		...t,
+		callerContext: t.callerContext ?? null,
+		intentIds: [...t.intentIds],
+		preparedExecutionId: null,
+		executionId: null,
+		runId: null,
+		receiptsBound: !1,
+		dispatchAttempts: 0,
+		failureId: null,
+		retry: {
+			attempts: 0,
+			after: 0,
+			lastError: null,
+			stoppedAt: null
+		}
+	};
+	return await e.insert(b, n), n;
+}, M = async (e, n, r) => t(e, (e) => N(e, n, r)), N = async (e, t, n) => {
+	if (n.executionId.length === 0) throw Error("Engine acknowledgement requires an execution identity");
+	let r = await e.query({
+		table: b,
+		predicate: m("id", t),
+		order: [],
+		take: 1,
+		skip: void 0,
+		projection: void 0
+	});
+	if (r[0] === void 0) throw Error("Cannot acknowledge an unknown admission submission");
+	let i = f.decodeUnknownSync(C)(r[0]);
+	if (i.failureId !== null) throw Error("Cannot acknowledge a permanently rejected admission submission");
+	if (i.preparedExecutionId !== null && i.preparedExecutionId !== n.executionId) throw Error("Engine acknowledgement contradicts the prepared execution identity");
+	if (i.executionId !== null && i.executionId !== n.executionId || i.runId !== null && n.runId !== null && i.runId !== n.runId) throw Error("Admission submission already belongs to a different execution or run");
+	let a = await s(e, i.workflowName, n.executionId), o = i.runId ?? n.runId;
+	if (a !== void 0 && o !== null && a.runId !== o) throw Error("Admission acknowledgement belongs to a different resident run");
+	let c = {
+		executionId: n.executionId,
+		runId: o ?? a?.runId ?? null
+	}, l = a?.completedAt ?? void 0;
+	if (await e.update("_voltro_workflow_admissions", i.ledgerId, {
+		...c,
+		...l === void 0 ? {} : { releasedAt: l }
+	}) === null) throw Error("Admission submission has no lease to acknowledge");
+	if (await e.update("_voltro_workflow_submissions", t, c) === null) throw Error("Admission submission disappeared during acknowledgement");
+	return {
+		...i,
+		...c
+	};
+}, P = async (e, t, n) => {
+	if (n.length === 0) throw Error("Prepared submission requires a non-empty execution identity");
+	let r = await O(e, t);
+	if (r === void 0) throw Error("Cannot prepare an unknown admission submission");
+	if (!r.receiptsBound || r.failureId !== null) throw Error("Cannot prepare an incomplete or terminal admission submission");
+	if (r.preparedExecutionId !== null) {
+		if (r.executionId !== null && r.executionId !== r.preparedExecutionId) throw Error("Submission acceptance contradicts its prepared identity");
+		return r;
+	}
+	if (r.executionId !== null) throw Error("Cannot prepare an accepted submission without its prepared identity");
+	if (r.dispatchAttempts !== 0) throw Error("Cannot choose an execution identity after an unbound dispatch");
+	if (r.retry.stoppedAt !== null) throw Error("Cannot prepare a stopped admission submission");
+	if (await e.update("_voltro_workflow_submissions", t, { preparedExecutionId: n }) === null) throw Error("Admission submission disappeared while preparing execution");
+	return {
+		...r,
+		preparedExecutionId: n
+	};
+}, F = async (t, n, r, i, a = !1, o = 0) => {
+	if (a !== !1 && (!Number.isSafeInteger(a) || a < 1)) throw Error("Submission retry limit must be a positive integer or false");
+	if (!Number.isSafeInteger(o) || o < 0) throw Error("Submission failure requires a valid observed recovery epoch");
+	let s = await O(t, n);
+	if (s === void 0) throw Error("Cannot record failure for an unknown submission");
+	if (s.executionId !== null || s.failureId !== null || s.retry.stoppedAt !== null || (s.retry.recovery?.attempts ?? 0) !== o) return s;
+	let c = s.retry.attempts + 1, l = c - (s.retry.recovery?.attempts ?? 0), u = {
+		...s.retry,
+		attempts: c,
+		lastError: e(s.workflowName, r),
+		after: i + d(l),
+		stoppedAt: a !== !1 && l >= a ? i : null
+	};
+	if (await t.update("_voltro_workflow_submissions", n, { retry: u }) === null) throw Error("Admission submission disappeared while recording failure");
+	return {
+		...s,
+		retry: u
+	};
+}, I = async (e, t, n) => {
+	if (!Number.isFinite(n)) throw Error("Submission dispatch requires a finite timestamp");
+	let r = await O(e, t);
+	if (r === void 0) throw Error("Cannot dispatch an unknown admission submission");
+	if (!r.receiptsBound || r.executionId !== null || r.failureId !== null || r.retry.stoppedAt !== null || r.retry.after > n) return null;
+	let i = r.dispatchAttempts + 1;
+	if (!Number.isSafeInteger(i)) throw Error("Submission dispatch counter exhausted");
+	if (r.dispatchAttempts === 0) {
+		let [t] = await e.query({
+			table: c,
+			predicate: m("id", r.ledgerId),
+			lock: "update",
+			order: [],
+			take: 1,
+			skip: void 0,
+			projection: void 0
+		});
+		if (t === void 0 || t.workflowName !== r.workflowName || t.tenantId !== r.tenantId || t.outcome !== "admitted" || t.executionId !== null || t.runId !== null || t.releasedAt !== null) throw Error("First submission dispatch requires its matching unbound and unreleased admission lease");
+		let i = t.admittedAt instanceof Date ? t.admittedAt.getTime() : NaN, a = t.expiresAt instanceof Date ? t.expiresAt.getTime() : NaN, o = a - i, s = new Date(n + o);
+		if (!Number.isFinite(i) || !Number.isFinite(a) || o <= 0 || !Number.isFinite(s.getTime())) throw Error("First submission dispatch requires a valid finite original admission lease interval");
+		if (await e.update("_voltro_workflow_admissions", r.ledgerId, { expiresAt: s }) === null) throw Error("Admission submission lost its lease before first dispatch");
+	}
+	if (await e.update("_voltro_workflow_submissions", t, { dispatchAttempts: i }) === null) throw Error("Admission submission disappeared before dispatch");
+	return {
+		...r,
+		dispatchAttempts: i
+	};
+}, L = async (e, t, n, s, c = 0) => {
+	if (!Number.isSafeInteger(n) || n < 0) throw Error("Invalid submission dispatch attempt");
+	if (!Number.isSafeInteger(c) || c < 0) throw Error("Submission rejection requires a valid observed recovery epoch");
+	let l = await O(e, t);
+	if (l === void 0) throw Error("Cannot reject an unknown admission submission");
+	if (l.failureId !== null) {
+		let n = await r(e, l.failureId);
+		if (n === void 0 || n.sourceKind !== "submission" || n.sourceId !== t || n.workflowName !== l.workflowName || n.tenantId !== l.tenantId) throw Error("Rejected submission has no matching durable failure report");
+		return await a(e, n.id, s.now), n;
+	}
+	if ((l.retry.recovery?.attempts ?? 0) !== c || !l.receiptsBound || l.executionId !== null || l.dispatchAttempts !== n || n > 1) return;
+	let u = `wffr_${_("sha256").update(JSON.stringify(["submission", t])).digest("hex").slice(0, 40)}`, d = await i(e, {
+		id: u,
+		sourceKind: "submission",
+		sourceId: t,
+		workflowName: l.workflowName,
+		tenantId: l.tenantId,
+		handler: await o(e, t) ? null : s.handler,
+		callerContext: l.callerContext,
+		report: {
+			workflow: l.workflowName,
+			payload: l.payload,
+			errorTag: "WorkflowPayloadError",
+			errorMessage: s.errorMessage,
+			reason: "permanent input rejection before engine acceptance",
+			failedAt: s.now,
+			runId: null,
+			executionId: null
+		}
+	});
+	if (await e.update("_voltro_workflow_admissions", l.ledgerId, { releasedAt: new Date(s.now) }) === null) throw Error("Rejected admission submission has no lease");
+	if (await e.update("_voltro_workflow_submissions", t, { failureId: u }) === null) throw Error("Admission submission disappeared during rejection");
+	return await a(e, d.id, s.now), d;
+};
+//#endregion
+export { x as ADMISSION_SUBMISSION_ID_PREFIX, b as SUBMISSIONS_TABLE, M as acknowledgeAdmissionSubmission, N as acknowledgeAdmissionSubmissionInTransaction, I as beginAdmissionSubmissionDispatchInTransaction, w as decodeAdmissionSubmission, T as dispatchedExecutionSubmissions, S as newAdmissionSubmissionId, F as noteAdmissionSubmissionFailure, E as pendingAdmissionSubmissions, j as persistReservedSubmission, P as prepareAdmissionSubmissionExecutionInTransaction, O as readAdmissionSubmission, D as readPendingAdmissionSubmissionRows, L as rejectAdmissionSubmissionInTransaction, k as reserveAdmissionSubmission, A as reserveAdmissionSubmissionInTransaction };

package/dist/admissionTables.js

@@ -0,0 +1,137 @@
+import { boolean as e, id as t, integer as n, json as r, real as i, table as a, text as o, timestamp as s } from "@voltro/database";
+//#region src/admissionTables.ts
+var c = a("_voltro_workflow_admission_locks", {
+	id: t({ prefix: "wfalk" }),
+	nonce: o()
+}).nonReactive(), l = a("_voltro_workflow_parent_closures", {
+	id: t({ prefix: "wfpc" }),
+	runId: o(),
+	workflowName: o(),
+	executionId: o(),
+	generation: o(),
+	parentStatus: o().oneOf([
+		"succeeded",
+		"failed",
+		"cancelled"
+	]),
+	closedAt: s(),
+	afterChildId: o().nullable(),
+	scanHasOpenChildren: e().default(!1),
+	completedAt: s().nullable()
+}).index(["executionId"]).index(["completedAt", "id"]).nonReactive(), u = a("_voltro_workflow_control_requests", {
+	id: t({ prefix: "wfctl" }),
+	runId: o(),
+	workflowName: o(),
+	executionId: o(),
+	generation: o(),
+	operation: o().oneOf([
+		"cancel",
+		"terminate",
+		"resume"
+	]),
+	requestedAt: s(),
+	owner: r().nullable(),
+	cause: r().nullable(),
+	parentClosureId: o().nullable(),
+	resumeJournal: r().nullable(),
+	dispatchAttempts: n().default(0),
+	result: r().nullable()
+}).index(["runId"]).index(["parentClosureId", "id"]).nonReactive(), d = a("_voltro_workflow_failure_reports", {
+	id: t({ prefix: "wffr" }),
+	workflowName: o(),
+	tenantId: o().nullable(),
+	sourceId: o(),
+	sourceKind: o().oneOf([
+		"submission",
+		"intent",
+		"run"
+	]),
+	handler: o().nullable(),
+	callerContext: r().nullable(),
+	report: r(),
+	handoffReceiptId: o().nullable(),
+	handoffAttempt: n().default(0),
+	acceptedExecutionId: o().nullable()
+}).index(["sourceKind", "sourceId"]).nonReactive(), f = a("_voltro_workflow_submissions", {
+	id: t({ prefix: "wfsub" }),
+	workflowName: o(),
+	tenantId: o().nullable(),
+	ledgerId: o(),
+	executionId: o().nullable(),
+	runId: o().nullable(),
+	receiptsBound: e().default(!1),
+	preparedExecutionId: o().nullable(),
+	dispatchAttempts: n().default(0),
+	failureId: o().nullable(),
+	retry: r(),
+	payload: r(),
+	callerContext: r().nullable(),
+	intentIds: r(),
+	eviction: r().nullable()
+}).nonReactive(), p = a("_voltro_workflow_start_receipts", {
+	id: t({ prefix: "wfrc" }),
+	workflowName: o(),
+	tenantId: o().nullable(),
+	pendingId: o().maxLength(64),
+	submissionId: o().maxLength(64).nullable(),
+	terminal: r().nullable(),
+	requestFingerprint: o().maxLength(64).nullable()
+}).index(["pendingId"]).nonReactive(), m = a("_voltro_workflow_pending", {
+	id: t({ prefix: "wfp" }),
+	tenantId: o().nullable(),
+	workflowName: o(),
+	controlKey: o(),
+	mode: o().oneOf([
+		"debounce",
+		"batch",
+		"throttle",
+		"concurrency",
+		"paused",
+		"delayed"
+	]),
+	payload: r(),
+	callerContext: r().nullable(),
+	queuedAppVersion: o().nullable(),
+	queuedSchemaFingerprint: o().nullable(),
+	priority: n().default(0),
+	dueAt: s(),
+	deadlineAt: s().nullable(),
+	collapsed: n().default(1),
+	firstSeenAt: s().default("now"),
+	updatedAt: s().default("now"),
+	attempts: n().default(0),
+	lastError: o().nullable(),
+	deadLetteredAt: s().nullable()
+}).index(["workflowName", "controlKey"]).index(["dueAt"]).index(["workflowName", "mode"]).index(["tenantId"]), h = a("_voltro_workflow_admissions", {
+	id: t({ prefix: "wfadm" }),
+	tenantId: o().nullable(),
+	workflowName: o(),
+	outcome: o().oneOf([
+		"admitted",
+		"dropped",
+		"skipped",
+		"evicted",
+		"expired",
+		"discarded"
+	]),
+	mode: o().nullable(),
+	reason: o().nullable(),
+	collapsed: n().default(1),
+	waitedMs: i().nullable().narrowedFrom("integer"),
+	executionId: o().nullable(),
+	runId: o().nullable(),
+	singletonKey: o().nullable(),
+	concurrencyKey: o().nullable(),
+	concurrencyReservation: r().nullable(),
+	rateKey: o().nullable(),
+	admittedAt: s().default("now"),
+	expiresAt: s().nullable(),
+	releasedAt: s().nullable()
+}).index(["workflowName", "admittedAt"]).index(["concurrencyKey", "releasedAt"]).index(["singletonKey", "releasedAt"]).index(["rateKey", "admittedAt"]).index(["executionId"]).index(["tenantId"]), g = a("_voltro_workflow_pauses", {
+	id: t({ prefix: "wfpause" }),
+	pausedAt: s().default("now"),
+	pausedBy: o().nullable(),
+	reason: o().nullable()
+});
+//#endregion
+export { c as _voltroWorkflowAdmissionLocksTable, h as _voltroWorkflowAdmissionsTable, u as _voltroWorkflowControlRequestsTable, d as _voltroWorkflowFailureReportsTable, l as _voltroWorkflowParentClosuresTable, g as _voltroWorkflowPausesTable, m as _voltroWorkflowPendingTable, p as _voltroWorkflowStartReceiptsTable, f as _voltroWorkflowSubmissionsTable };

package/dist/admissionTransaction.js

@@ -0,0 +1,21 @@
+import { eq as e } from "@voltro/database";
+import { randomUUID as t } from "node:crypto";
+//#region src/admissionTransaction.ts
+var n = "_voltro_workflow_admission_locks", r = "deployment", i = async (i, a) => (await i.insertIgnoreWithOutcome(n, {
+	id: r,
+	nonce: t()
+}, { conflictColumns: ["id"] }), i.transactional(async (n) => {
+	if ((await n.query({
+		table: "_voltro_workflow_admission_locks",
+		predicate: e("id", r),
+		lock: "update",
+		order: [],
+		take: 1,
+		skip: void 0,
+		projection: void 0
+	})).length !== 1) throw Error("Admission coordinator row is missing; refusing an unlocked decision");
+	if (await n.update("_voltro_workflow_admission_locks", r, { nonce: t() }) === null) throw Error("Admission coordinator row disappeared; refusing an unlocked decision");
+	return a(n);
+}));
+//#endregion
+export { n as ADMISSION_LOCKS_TABLE, i as withAdmissionTransaction };

package/dist/awaitEvent.js

@@ -0,0 +1,82 @@
+import { encryptionAwareActivity as e } from "./journalEncryption.js";
+import { CurrentWorkflowRunId as t, WorkflowRunRecorder as n } from "./recorder.js";
+import { Effect as r, Schema as i } from "effect";
+import { and as a, eq as o, gte as s } from "@voltro/database";
+//#region src/awaitEvent.ts
+var c = async (e, t) => {
+	if (e !== void 0) try {
+		await e.recordEvent(t);
+	} catch {}
+}, l = (l, d) => {
+	let f = r.gen(function* () {
+		let e = d.pollIntervalMs ?? 200, f = d.maxPollIntervalMs ?? 5e3, p = d.timeoutMs ?? 864e5, m = d.take ?? 500, h = yield* t, g = yield* r.serviceOption(n), _ = g._tag === "Some" ? g.value : void 0;
+		if (h === void 0) return yield* r.die(/* @__PURE__ */ Error("awaitEvent: no active workflow run id in scope"));
+		let v = h, y = yield* d.since === "run-start" ? u(l, v) : r.succeed(/* @__PURE__ */ new Date());
+		yield* r.promise(() => c(_, {
+			runId: v,
+			eventType: "event-awaited",
+			payload: {
+				event: d.event,
+				since: d.since ?? "wait-start",
+				cutoff: y.toISOString()
+			}
+		}));
+		let b = Date.now(), x = e, S = 0;
+		for (;;) {
+			let e = Date.now() - b;
+			if (e > p) return yield* r.die(/* @__PURE__ */ Error(`awaitEvent('${d.event}') timed out after ${e}ms having examined ${S} candidate event(s). ${S === 0 ? "NONE were published under that name in the window — check the spelling against ctx.events.publish, and consider since: 'run-start' if the event may have arrived before this step began." : "The predicate rejected all of them — log one payload and compare it with what `match` expects."}`));
+			let t = {
+				table: "_voltro_workflow_events",
+				predicate: a(o("name", d.event), s("occurredAt", y)),
+				order: [{
+					column: "occurredAt",
+					direction: "asc"
+				}],
+				take: m,
+				skip: void 0,
+				projection: void 0
+			}, n = yield* r.tryPromise({
+				try: () => l.store.query(t),
+				catch: (e) => e
+			});
+			S = n.length;
+			for (let e of n) {
+				let t = yield* i.decodeUnknownEffect(d.schema)(e.payload);
+				if (d.match(t)) return yield* r.promise(() => c(_, {
+					runId: v,
+					eventType: "event-received",
+					payload: {
+						event: d.event,
+						eventId: e.id
+					}
+				})), t;
+			}
+			yield* r.sleep(`${x} millis`), x = Math.min(x * 2, f);
+		}
+	});
+	return e({
+		name: `awaitEvent:${d.event}`,
+		success: d.schema,
+		execute: f
+	});
+}, u = (e, t) => r.gen(function* () {
+	let n = (yield* r.tryPromise({
+		try: () => e.store.query({
+			table: "_voltro_workflow_runs",
+			predicate: o("id", t),
+			order: [],
+			take: 1,
+			skip: void 0,
+			projection: void 0
+		}),
+		catch: (e) => e
+	}))[0]?.startedAt;
+	if (n instanceof Date) return n;
+	if (typeof n == "string" || typeof n == "number") {
+		let e = new Date(n);
+		if (!Number.isNaN(e.getTime())) return e;
+	}
+	return /* @__PURE__ */ new Date(0);
+});
+//#endregion
+export { l as awaitEvent };

package/dist/budgetHold.js

@@ -0,0 +1,136 @@
+import { awaitSignalSuspending as e, completeSuspendingSignal as t } from "./signalsSuspending.js";
+import { Cause as n, Effect as r, Schema as i } from "effect";
+import { and as a, eq as o, generateId as s, id as c, isNull as l, registerRetention as u, retentionTtlMsFromEnv as d, table as f, text as p, timestamp as m } from "@voltro/database";
+//#region src/budgetHold.ts
+var h = "_voltro_budget_holds", g = "budget-hold", _ = (e) => `${g}:${e}`, v = (e) => `${e.executionId}/${e.stepName}/${e.budget}#${e.generation}`, y = async (e, t) => (await e.query({
+	table: h,
+	predicate: a(o("executionId", t.executionId), o("stepName", t.stepName), o("budget", t.budget)),
+	order: []
+})).length, b = f(h, {
+	id: c({ prefix: "bhd" }),
+	holdKey: p().maxLength(191).unique(),
+	budget: p(),
+	tenantId: p().nullable(),
+	executionId: p(),
+	workflowName: p(),
+	signalName: p(),
+	stepName: p(),
+	spentMicroUsd: p().nullable(),
+	limitMicroUsd: p().nullable(),
+	heldAt: m().default("now"),
+	releasedAt: m().nullable(),
+	outcome: p().nullable()
+}).index(["budget", "releasedAt"]), x = () => {
+	u({
+		source: "framework",
+		table: h,
+		timeColumn: "releasedAt",
+		ttlMs: d(process.env.VOLTRO_BUDGET_HOLDS_TTL_HOURS, 720)
+	});
+}, S = class extends Error {
+	budget;
+	holdKey;
+	constructor(e, t, n) {
+		super(`budget '${e}': the run was suspended waiting for headroom and gave up after ${n}ms (hold ${t}). Nothing was spent. Raise the budget, reset its window, or lift the hold, then re-drive the run.`), this.name = "BudgetHoldExpired", this.budget = e, this.holdKey = t;
+	}
+}, C = 6048e5, w = 9e5, T = (t) => r.gen(function* () {
+	x();
+	let c = t.timeoutMs ?? 6048e5, u = t.recheckEveryMs ?? 9e5, d = {
+		executionId: t.executionId,
+		stepName: t.stepName,
+		budget: t.budget
+	};
+	for (let f = 0;; f++) {
+		let p = yield* r.promise(() => D(t.store, d)), m = p.length === 0 ? Date.now() : E(p[0]?.heldAt), g = Number.isFinite(c) ? c - (Date.now() - m) : Infinity, y = v({
+			...d,
+			generation: f
+		});
+		if (g <= 0) return yield* r.promise(() => O(t.store, d, "expired")), yield* r.fail(new S(t.budget, y, c));
+		let b = _(y);
+		yield* r.promise(() => t.store.insertIgnore(h, {
+			id: s({
+				kind: "typeid",
+				prefix: "bhd"
+			}, h),
+			holdKey: y,
+			budget: t.budget,
+			tenantId: t.tenantId,
+			executionId: t.executionId,
+			workflowName: t.workflowName,
+			signalName: b,
+			stepName: t.stepName,
+			spentMicroUsd: t.spentMicroUsd === void 0 ? null : String(Math.round(t.spentMicroUsd)),
+			limitMicroUsd: t.limitMicroUsd === void 0 ? null : String(Math.round(t.limitMicroUsd)),
+			heldAt: /* @__PURE__ */ new Date(),
+			releasedAt: null,
+			outcome: null
+		}, { conflictColumns: ["holdKey"] }));
+		let x = Math.min(u, g);
+		if (yield* e({ store: t.store }, {
+			name: b,
+			schema: i.Unknown,
+			timeoutMs: x
+		}).pipe(r.catchCause((e) => n.hasInterruptsOnly(e) ? r.failCause(e) : r.void)), yield* r.promise(() => t.store.updateMany(h, {
+			releasedAt: /* @__PURE__ */ new Date(),
+			outcome: "recheck"
+		}, { where: a(o("holdKey", y), l("releasedAt")) })), yield* t.hasHeadroom) return;
+	}
+}), E = (e) => e instanceof Date ? e.getTime() : typeof e == "string" ? Date.parse(e) : Date.now(), D = async (e, t) => [...await e.query({
+	table: h,
+	predicate: a(o("executionId", t.executionId), o("stepName", t.stepName), o("budget", t.budget)),
+	order: []
+})].sort((e, t) => String(e.id).localeCompare(String(t.id))), O = async (e, t, n) => {
+	await e.updateMany(h, {
+		releasedAt: /* @__PURE__ */ new Date(),
+		outcome: n
+	}, { where: a(o("executionId", t.executionId), o("stepName", t.stepName), o("budget", t.budget), l("releasedAt")) });
+}, k = (e) => r.gen(function* () {
+	let n = e.tenantId === void 0 ? a(o("budget", e.budget), l("releasedAt")) : a(o("budget", e.budget), o("tenantId", e.tenantId), l("releasedAt")), i = yield* r.promise(() => e.store.query({
+		table: h,
+		predicate: n,
+		order: []
+	})), s = 0;
+	for (let n of i) (yield* r.promise(() => e.store.updateMany("_voltro_budget_holds", {
+		releasedAt: /* @__PURE__ */ new Date(),
+		outcome: e.outcome ?? "released"
+	}, { where: a(o("id", String(n.id)), l("releasedAt")) }))) === 1 && (yield* t({
+		target: {
+			executionId: String(n.executionId),
+			workflowName: String(n.workflowName)
+		},
+		signalName: String(n.signalName),
+		payload: {
+			released: !0,
+			budget: e.budget
+		}
+	}).pipe(r.catch(() => r.succeed({ completed: !1 }))), s += 1);
+	return { released: s };
+}), A = async (e, t) => {
+	let n = t?.budget === void 0 ? l("releasedAt") : a(o("budget", t.budget), l("releasedAt"));
+	return (await e.query({
+		table: h,
+		predicate: n,
+		order: []
+	})).map((e) => ({
+		id: String(e.id),
+		holdKey: String(e.holdKey),
+		budget: String(e.budget),
+		tenantId: e.tenantId ?? null,
+		executionId: String(e.executionId),
+		workflowName: String(e.workflowName),
+		stepName: String(e.stepName),
+		heldAt: e.heldAt instanceof Date ? e.heldAt.toISOString() : String(e.heldAt ?? "")
+	}));
+}, j = async (e) => {
+	let t = await A(e), n = /* @__PURE__ */ new Map();
+	for (let e of t) {
+		let t = `${e.budget}\u0000${e.tenantId ?? ""}`;
+		n.has(t) || n.set(t, {
+			budget: e.budget,
+			tenantId: e.tenantId
+		});
+	}
+	return [...n.values()];
+};
+//#endregion
+export { h as BUDGET_HOLDS_TABLE, S as BudgetHoldExpired, C as DEFAULT_BUDGET_HOLD_TIMEOUT_MS, w as DEFAULT_BUDGET_RECHECK_MS, b as _voltroBudgetHoldsTable, y as budgetHoldGeneration, v as budgetHoldKey, _ as budgetHoldSignalName, j as heldBudgets, A as pendingBudgetHolds, k as releaseBudgetHolds, T as suspendForBudget };