@voltro/runtime 0.85.0 → 0.87.0

package/dist/connectionVault.js

@@ -0,0 +1,410 @@
+import { decryptField as e, encryptField as t, getFieldCipher as n } from "./fieldCipher.js";
+import { and as r, eq as i, fieldBinding as a, generateId as o, id as s, json as c, lte as l, table as u, text as d, timestamp as f } from "@voltro/database";
+import { ConnectionHandshakeFailed as p } from "@voltro/protocol";
+import { createLogger as m } from "@voltro/logger";
+//#region src/connectionVault.ts
+var h = m({ scope: "voltro:connections" }), g = "_voltro_connections", _ = {
+	kind: "typeid",
+	prefix: "conn"
+}, v = u(g, {
+	id: s({ prefix: "conn" }),
+	connectionId: d(),
+	subjectId: d(),
+	tenantId: d().nullable(),
+	kind: d().oneOf(["oauth2", "pat"]),
+	status: d().oneOf([
+		"connected",
+		"expired",
+		"revoked",
+		"error"
+	]),
+	accessToken: d(),
+	refreshToken: d().nullable(),
+	expiresAt: f().nullable(),
+	scopes: d().nullable(),
+	accountId: d().nullable(),
+	accountLabel: d().nullable(),
+	lastError: d().nullable(),
+	refreshLockedUntil: f(),
+	metadata: c().nullable(),
+	connectedAt: f(),
+	updatedAt: f()
+}).unique("byConnectionSubject", ["connectionId", "subjectId"]).index(["subjectId"]), y = "_voltro_connection_grants", ee = {
+	kind: "typeid",
+	prefix: "cgrant"
+}, b = u(y, {
+	id: s({ prefix: "cgrant" }),
+	state: d().unique(),
+	connectionId: d(),
+	subjectId: d(),
+	tenantId: d().nullable(),
+	codeVerifier: d().nullable(),
+	redirectTo: d(),
+	createdAt: f(),
+	expiresAt: f()
+}).index(["expiresAt"]), x = (e) => typeof e == "function" ? e() : e, te = /^[a-z][a-z0-9-]*$/, ne = (e) => {
+	if (!te.test(e.id)) throw Error(`defineConnection: id "${e.id}" must be lowercase kebab-case (it becomes a URL path segment).`);
+	if (e.kind === "oauth2") {
+		for (let t of ["authorizeUrl", "tokenUrl"]) if (typeof e[t] != "string" || e[t].length === 0) throw Error(`defineConnection("${e.id}"): \`${t}\` is required for kind 'oauth2'.`);
+		for (let t of ["clientId", "clientSecret"]) {
+			let n = e[t];
+			if (typeof n != "function" && (typeof n != "string" || n.length === 0)) throw Error(`defineConnection("${e.id}"): \`${t}\` is required for kind 'oauth2' — a string, or a thunk (\`() => serverEnv.X\`) read when the connection is used.`);
+		}
+	}
+	return e;
+}, S = (e) => e.label ?? e.id, C = (e) => {
+	if (e.length !== 0 && n() === void 0) throw Error(`connections: ${e.length} connection(s) declared (${e.map((e) => e.id).join(", ")}) but no field cipher is registered. Connection tokens are stored encrypted and there is no plaintext fallback. Set VOLTRO_FIELD_ENCRYPTION_KEY (\`voltro secret generate field-encryption\`; \`voltro dev\` mints one), or call setFieldCipher at boot.`);
+}, w = (e) => {
+	let t = /* @__PURE__ */ new Map();
+	for (let n of e) {
+		if (t.has(n.id)) throw Error(`connections: duplicate connection id "${n.id}" — each *.connection.ts must declare a distinct id.`);
+		t.set(n.id, n);
+	}
+	return {
+		get: (e) => t.get(e),
+		list: () => [...t.values()]
+	};
+}, T = (e) => {
+	if (e == null) return null;
+	let t = e instanceof Date ? e : new Date(String(e));
+	return Number.isNaN(t.getTime()) ? null : t;
+}, E = (e) => T(e)?.toISOString() ?? null, D = (e) => String(e ?? "").match(/[^ ]+/g) ?? [], O = (e, t) => t === void 0 ? {
+	connectionId: e.id,
+	kind: e.kind,
+	label: S(e),
+	status: "disconnected",
+	accountId: null,
+	accountLabel: null,
+	scopes: [],
+	expiresAt: null,
+	lastError: null,
+	connectedAt: null
+} : {
+	connectionId: e.id,
+	kind: e.kind,
+	label: S(e),
+	status: String(t.status ?? "connected"),
+	accountId: t.accountId ?? null,
+	accountLabel: t.accountLabel ?? null,
+	scopes: D(t.scopes),
+	expiresAt: E(t.expiresAt),
+	lastError: t.lastError ?? null,
+	connectedAt: E(t.connectedAt)
+}, k = async (e, t, n) => (await e.query({
+	table: g,
+	predicate: r(i("connectionId", t), i("subjectId", n)),
+	order: [],
+	take: 1,
+	skip: void 0,
+	projection: void 0
+}))[0], A = async (e) => {
+	let n = (e.now ?? (() => /* @__PURE__ */ new Date()))(), s = e.tokens.expiresAt === void 0 ? null : new Date(e.tokens.expiresAt), c = await e.store.query({
+		table: g,
+		predicate: r(i("connectionId", e.definition.id), i("subjectId", e.subjectId)),
+		order: [],
+		take: 1,
+		skip: void 0,
+		projection: ["id"]
+	}), l = typeof c[0]?.id == "string" ? c[0].id : o(_, g), u = {
+		id: l,
+		connectionId: e.definition.id,
+		subjectId: e.subjectId,
+		tenantId: e.tenantId,
+		kind: e.definition.kind,
+		status: "connected",
+		accessToken: t(e.tokens.accessToken, a(g, "accessToken", l)),
+		refreshToken: e.tokens.refreshToken === void 0 ? null : t(e.tokens.refreshToken, a(g, "refreshToken", l)),
+		expiresAt: s,
+		scopes: e.tokens.scopes.length > 0 ? e.tokens.scopes.join(" ") : null,
+		accountId: e.account?.accountId ?? null,
+		accountLabel: e.account?.accountLabel ?? null,
+		lastError: null,
+		refreshLockedUntil: /* @__PURE__ */ new Date(0),
+		metadata: e.account?.metadata ?? null,
+		connectedAt: n,
+		updatedAt: n
+	};
+	return re(e.store, u);
+}, re = (e, t) => e.upsert(g, t, {
+	conflictColumns: ["connectionId", "subjectId"],
+	update: [
+		"kind",
+		"status",
+		"accessToken",
+		"refreshToken",
+		"expiresAt",
+		"scopes",
+		"accountId",
+		"accountLabel",
+		"lastError",
+		"refreshLockedUntil",
+		"metadata",
+		"updatedAt"
+	]
+}), j = async (e, t, n) => {
+	let r = await k(e, t, n);
+	return r !== void 0 && e.delete(g, r.id);
+}, M = async (e, t, n) => {
+	let r = await e.query({
+		table: g,
+		predicate: i("subjectId", n),
+		order: [],
+		take: void 0,
+		skip: void 0,
+		projection: void 0
+	}), a = new Map(r.map((e) => [String(e.connectionId), e]));
+	return t.list().map((e) => O(e, a.get(e.id)));
+}, N = (e, t) => globalThis.fetch(e, t), P = async (e, t, n) => {
+	let r = e.fetchImpl ?? N, i, a;
+	try {
+		let n = await r(e.tokenUrl, {
+			method: "POST",
+			headers: {
+				"content-type": "application/x-www-form-urlencoded",
+				accept: "application/json"
+			},
+			body: new URLSearchParams(t).toString()
+		});
+		i = n.status, a = await n.text();
+	} catch (t) {
+		throw new p({
+			connectionId: e.id,
+			reason: `token endpoint unreachable: ${String(t)}`,
+			transient: !0
+		});
+	}
+	let o;
+	try {
+		o = JSON.parse(a);
+	} catch {
+		o = {};
+	}
+	if (i < 200 || i >= 300) throw new p({
+		connectionId: e.id,
+		reason: `token endpoint ${i}: ${o.error ?? ""} ${o.error_description ?? a.slice(0, 200)}`.trim(),
+		transient: i >= 500
+	});
+	if (typeof o.access_token != "string" || o.access_token.length === 0) throw new p({
+		connectionId: e.id,
+		reason: "token response carried no access_token",
+		transient: !1
+	});
+	return {
+		accessToken: o.access_token,
+		...typeof o.refresh_token == "string" ? { refreshToken: o.refresh_token } : {},
+		...Number.isFinite(o.expires_in) ? { expiresAt: n() + o.expires_in * 1e3 } : {},
+		scopes: (o.scope ?? e.scopes?.join(" ") ?? "").match(/[^ ]+/g) ?? []
+	};
+}, F = (e, t, n = Date.now) => P(e, {
+	grant_type: "authorization_code",
+	client_id: x(e.clientId),
+	client_secret: x(e.clientSecret),
+	code: t.code,
+	redirect_uri: t.redirectUri,
+	...t.codeVerifier ? { code_verifier: t.codeVerifier } : {}
+}, n), I = (e, t, n = Date.now) => P(e, {
+	grant_type: "refresh_token",
+	client_id: x(e.clientId),
+	client_secret: x(e.clientSecret),
+	refresh_token: t
+}, n), L = 6e4, R = 3e4, z = class extends Error {
+	connectionId;
+	subjectId;
+	_tag = "ConnectionNotConnected";
+	constructor(e, t) {
+		super(`connection "${e}" is not connected for this subject`), this.connectionId = e, this.subjectId = t, this.name = "ConnectionNotConnected";
+	}
+}, B = (e) => new Promise((t) => {
+	setTimeout(t, e);
+}), V = /* @__PURE__ */ new Map(), H = (e, t) => `${e}\u0000${t}`, U = () => {
+	V.clear();
+}, W = (t, n) => ({
+	connectionId: t.id,
+	kind: t.kind,
+	accessToken: e(String(n.accessToken), a(g, "accessToken", n.id)),
+	expiresAt: T(n.expiresAt),
+	scopes: D(n.scopes),
+	accountId: n.accountId ?? null,
+	accountLabel: n.accountLabel ?? null
+}), G = (e, t, n) => {
+	let r = T(e.expiresAt);
+	return r !== null && r.getTime() - n < t;
+}, K = async (e) => {
+	let t = e.now ?? Date.now, { store: n, definition: r, subjectId: i } = e, a = await k(n, r.id, i);
+	if (a === void 0) throw new z(r.id, i);
+	if (r.kind === "pat" || !G(a, r.refreshSkewMs ?? 6e4, t())) return W(r, a);
+	let o = H(r.id, i), s = V.get(o);
+	if (s !== void 0) return s;
+	let c = q({
+		...e,
+		now: t,
+		row: a
+	}).finally(() => {
+		V.delete(o);
+	});
+	return V.set(o, c), c;
+}, q = async (n) => {
+	let { store: o, subjectId: s, now: c } = n, u = n.definition, d = n.sleep ?? B, f = u.refreshSkewMs ?? 6e4, m = n.row.id;
+	if (await o.updateMany("_voltro_connections", { refreshLockedUntil: new Date(c() + 3e4) }, { where: r(i("id", m), l("refreshLockedUntil", new Date(c()))) }) === 0) {
+		for (let e = 0; e < 10; e++) {
+			await d(200);
+			let e = await k(o, u.id, s);
+			if (e === void 0) throw new z(u.id, s);
+			if (!G(e, f, c())) return W(u, e);
+		}
+		throw new p({
+			connectionId: u.id,
+			reason: "another replica held the refresh lease and did not publish a fresh token in time",
+			transient: !0
+		});
+	}
+	let _ = n.row.refreshToken;
+	if (_ == null) throw await o.update(g, m, {
+		status: "expired",
+		lastError: "access token expired and no refresh token is on file — reconnect required",
+		refreshLockedUntil: /* @__PURE__ */ new Date(0),
+		updatedAt: new Date(c())
+	}), new p({
+		connectionId: u.id,
+		reason: "access token expired and no refresh token is on file — reconnect required",
+		transient: !1
+	});
+	let v;
+	try {
+		v = await I(u, e(String(_), a(g, "refreshToken", m)), c);
+	} catch (e) {
+		let n = e instanceof p ? e : new p({
+			connectionId: u.id,
+			reason: String(e),
+			transient: !0
+		});
+		throw await o.update(g, m, {
+			status: n.transient ? "error" : "revoked",
+			lastError: n.reason,
+			refreshLockedUntil: /* @__PURE__ */ new Date(0),
+			updatedAt: new Date(c()),
+			...n.transient ? {} : {
+				accessToken: t("", a(g, "accessToken", m)),
+				refreshToken: null,
+				expiresAt: null
+			}
+		}), h.warn("connection refresh failed", {
+			connectionId: u.id,
+			transient: n.transient,
+			reason: n.reason
+		}), n;
+	}
+	let y = {
+		status: "connected",
+		accessToken: t(v.accessToken, a(g, "accessToken", m)),
+		...v.refreshToken === void 0 ? {} : { refreshToken: t(v.refreshToken, a(g, "refreshToken", m)) },
+		expiresAt: v.expiresAt === void 0 ? null : new Date(v.expiresAt),
+		...v.scopes.length > 0 ? { scopes: v.scopes.join(" ") } : {},
+		lastError: null,
+		refreshLockedUntil: /* @__PURE__ */ new Date(0),
+		updatedAt: new Date(c())
+	};
+	return W(u, await o.update(g, m, y) ?? {
+		...n.row,
+		...y
+	});
+}, J = (e = 32) => {
+	let t = new Uint8Array(e);
+	return globalThis.crypto.getRandomValues(t), Array.from(t, (e) => e.toString(16).padStart(2, "0")).join("");
+}, Y = (e) => {
+	let t = "";
+	for (let n of e) t += String.fromCharCode(n);
+	return btoa(t).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}, ie = async (e) => {
+	let t = await globalThis.crypto.subtle.digest("SHA-256", new TextEncoder().encode(e));
+	return Y(new Uint8Array(t));
+}, X = 6e5, Z = (e) => `/_voltro/connections/${e}/callback`, Q = (e) => e === void 0 || e.length === 0 || !e.startsWith("/") || e.startsWith("//") || e.startsWith("/\\") ? "/" : e, $ = (e, t) => e.redirectUri ?? `${t.replace(/\/+$/, "")}${Z(e.id)}`, ae = async (e) => {
+	let n = (e.now ?? (() => /* @__PURE__ */ new Date()))(), { definition: r } = e, i = J(), s = r.pkce === !1 ? null : J(48), c = $(r, e.publicUrl), l = o(ee, y);
+	await e.store.insert(y, {
+		id: l,
+		state: i,
+		connectionId: r.id,
+		subjectId: e.subjectId,
+		tenantId: e.tenantId,
+		codeVerifier: s === null ? null : t(s, a(y, "codeVerifier", l)),
+		redirectTo: Q(e.redirectTo),
+		createdAt: n,
+		expiresAt: new Date(n.getTime() + X)
+	});
+	let u = new URLSearchParams({
+		response_type: "code",
+		client_id: x(r.clientId),
+		redirect_uri: c,
+		state: i,
+		...r.scopes && r.scopes.length > 0 ? { scope: r.scopes.join(" ") } : {},
+		...r.authorizeParams ?? {}
+	});
+	s !== null && (u.set("code_challenge", await ie(s)), u.set("code_challenge_method", "S256"));
+	let d = r.authorizeUrl.includes("?") ? "&" : "?";
+	return {
+		authorizeUrl: `${r.authorizeUrl}${d}${u.toString()}`,
+		state: i
+	};
+}, oe = async (t) => {
+	let n = (t.now ?? (() => /* @__PURE__ */ new Date()))(), r = (await t.store.query({
+		table: y,
+		predicate: i("state", t.state),
+		order: [],
+		take: 1,
+		skip: void 0,
+		projection: void 0
+	}))[0];
+	if (r === void 0) throw new p({
+		connectionId: "unknown",
+		reason: "unknown or already-used handshake state",
+		transient: !1
+	});
+	await t.store.delete(y, r.id);
+	let o = String(r.connectionId), s = T(r.expiresAt);
+	if (s !== null && s.getTime() < n.getTime()) throw new p({
+		connectionId: o,
+		reason: "handshake expired — start again",
+		transient: !1
+	});
+	let c = t.registry.get(o);
+	if (c === void 0 || c.kind !== "oauth2") throw new p({
+		connectionId: o,
+		reason: "no oauth2 connection is declared under that id",
+		transient: !1
+	});
+	let l = r.codeVerifier === null || r.codeVerifier === void 0 ? null : e(String(r.codeVerifier), a(y, "codeVerifier", r.id)), u = await F(c, {
+		code: t.code,
+		redirectUri: $(c, t.publicUrl),
+		codeVerifier: l
+	}, () => n.getTime()), d = c.identify === void 0 ? void 0 : await c.identify(u).catch((e) => {
+		h.warn("connection identify failed; storing without account details", {
+			connectionId: o,
+			reason: String(e)
+		});
+	});
+	return await A({
+		store: t.store,
+		definition: c,
+		subjectId: String(r.subjectId),
+		tenantId: r.tenantId ?? null,
+		tokens: u,
+		...d === void 0 ? {} : { account: d },
+		now: () => n
+	}), {
+		connectionId: o,
+		redirectTo: Q(String(r.redirectTo ?? "/"))
+	};
+}, se = async (e, t = /* @__PURE__ */ new Date()) => {
+	let n = await e.query({
+		table: y,
+		predicate: l("expiresAt", t),
+		order: [],
+		take: void 0,
+		skip: void 0,
+		projection: ["id"]
+	}), r = 0;
+	for (let t of n) await e.delete("_voltro_connection_grants", t.id) && r++;
+	return r;
+};
+//#endregion
+export { g as CONNECTIONS_TABLE, y as CONNECTION_GRANTS_TABLE, z as ConnectionNotConnected, L as DEFAULT_REFRESH_SKEW_MS, X as GRANT_TTL_MS, R as REFRESH_LEASE_MS, b as _voltroConnectionGrantsTable, v as _voltroConnectionsTable, C as assertConnectionCipherConfigured, ae as beginOAuthConnect, U as clearConnectionRefreshFlights, oe as completeOAuthConnect, Z as connectionCallbackPath, S as connectionLabel, ne as defineConnection, F as exchangeAuthorizationCode, j as forgetCredential, M as listConnectionStates, w as makeConnectionRegistry, x as oauthCredentialValue, O as projectConnectionState, I as refreshAccessToken, K as resolveConnection, $ as resolveRedirectUri, Q as sanitizeRedirectTo, A as storeCredential, se as sweepExpiredGrants };

package/dist/connectionsFacade.js

@@ -0,0 +1,56 @@
+import { noteCacheVolatile as e } from "./computedQueryCache.js";
+import { ConnectionNotConnected as t, listConnectionStates as n, resolveConnection as r } from "./connectionVault.js";
+//#region src/connectionsFacade.ts
+var i, a = (e) => {
+	i = e;
+}, o = () => i, s = (e, t) => {
+	let n = i;
+	return n === void 0 ? Promise.reject(/* @__PURE__ */ Error(`resolveConnectionForSubject("${t}"): no connection vault is registered — the app declares no \`*.connection.ts\`, or this call ran before boot completed.`)) : n(e, t);
+}, c = (e) => async (n, i) => {
+	let a = e.registry.get(i);
+	if (a === void 0) throw Error(`connection "${i}" is not declared. Declared: ${e.registry.list().map((e) => e.id).join(", ") || "(none)"}.`);
+	let o = n.id ?? null;
+	if (o === null || o === "") throw new t(i, "<anonymous>");
+	return r({
+		store: e.store,
+		definition: a,
+		subjectId: o
+	});
+}, l = (i) => {
+	let a = i.subject.id ?? null, o = async (n) => {
+		e("ctx.connections");
+		let o = i.registry.get(n);
+		if (o === void 0) throw Error(`ctx.connections.get("${n}"): no such connection is declared. Declared: ${i.registry.list().map((e) => e.id).join(", ") || "(none)"}.`);
+		if (a === null || a === "") throw new t(n, "<anonymous>");
+		return r({
+			store: i.store,
+			definition: o,
+			subjectId: a
+		});
+	};
+	return {
+		get: o,
+		tryGet: async (e) => {
+			try {
+				return await o(e);
+			} catch (e) {
+				if (e instanceof t) return null;
+				throw e;
+			}
+		},
+		list: async () => a === null || a === "" ? i.registry.list().map((e) => ({
+			connectionId: e.id,
+			kind: e.kind,
+			label: e.label ?? e.id,
+			status: "disconnected",
+			accountId: null,
+			accountLabel: null,
+			scopes: [],
+			expiresAt: null,
+			lastError: null,
+			connectedAt: null
+		})) : n(i.store, i.registry, a)
+	};
+};
+//#endregion
+export { o as getConnectionResolver, c as makeConnectionResolver, l as makeConnectionsFacade, s as resolveConnectionForSubject, a as setConnectionResolver };

package/dist/coordinatedSchedule.js

@@ -0,0 +1,145 @@
+import { cronForInterval as e, externalizationRefusal as t, registerExternalizedTask as n } from "./externalizedTasks.js";
+//#region src/coordinatedSchedule.ts
+var r = (e) => {
+	if (e === void 0) return null;
+	let t = e.nextDueInMs;
+	return {
+		idle: e.idle === !0,
+		...t === null ? { nextDueInMs: null } : typeof t == "number" && Number.isFinite(t) ? { nextDueInMs: t } : {}
+	};
+}, i = /* @__PURE__ */ new WeakMap(), a = (e) => i.get(e)?.() ?? null, o = 3e4, s = (e = process.env) => {
+	let t = e.VOLTRO_POLL_CEILING_MS;
+	if (t === void 0) return o;
+	let n = Number(t);
+	return Number.isFinite(n) && n > 0 ? n : o;
+}, c = (a, o, c, u) => {
+	let d = Math.max(o, u.maxIdleIntervalMs ?? s()), f = !1, p, m = /* @__PURE__ */ new Set(), h = (e) => {
+		let t = Promise.resolve().then(e);
+		return m.add(t), t.then(() => m.delete(t), () => m.delete(t)), t;
+	}, g, _ = !1, v = o, y = !1, b = !1, x = 0, S = null, C = {
+		ticks: 0,
+		claimWins: 0,
+		claimLosses: 0,
+		claimFailures: 0,
+		taskFailures: 0,
+		wakes: 0,
+		coalescedWakes: 0,
+		lastTickAt: null,
+		lastWakeAt: null,
+		lastDecision: "starting",
+		lastOutcome: null
+	}, w = (e) => {
+		f || (g !== void 0 && clearTimeout(g), g = void 0, S = null, e === "disarm" ? _ = !0 : (_ = !1, v = Math.max(0, Math.min(e, d)), S = Date.now() + v, g = setTimeout(() => {
+			E();
+		}, v), typeof g.unref == "function" && g.unref()));
+	}, T = async () => {
+		if (f) return;
+		if (y) {
+			b = !0;
+			return;
+		}
+		C.ticks++, C.lastTickAt = Date.now(), C.lastOutcome = null, S = null, y = !0;
+		let e = new Date(Math.floor(Date.now() / o) * o);
+		try {
+			let t = !1;
+			try {
+				t = await u.coordinator.tryClaim(a, e, o);
+			} catch (e) {
+				C.claimFailures++, C.lastDecision = "claim-failed", u.log?.warn("coordinated schedule: claim check failed — skipping this tick", {
+					task: a,
+					reason: e?.message ?? String(e)
+				}), w(o);
+				return;
+			}
+			if (!t) {
+				C.claimLosses++, C.lastDecision = "claim-lost", w(o);
+				return;
+			}
+			if (f) return;
+			let n;
+			C.claimWins++;
+			try {
+				n = await c();
+			} catch (e) {
+				C.taskFailures++, C.lastDecision = "task-failed", u.log?.warn("coordinated schedule: task threw", {
+					task: a,
+					reason: e?.message ?? String(e)
+				}), w(o);
+				return;
+			}
+			C.lastOutcome = r(n);
+			let i = l(C.lastOutcome ?? void 0, o, v, d, u.disarmWhenIdle ?? !1);
+			C.lastDecision = i === "disarm" ? "idle-disarmed" : n?.idle ? "idle-backoff" : "active", w(i);
+		} finally {
+			y = !1, b && !f && (b = !1, w(0));
+		}
+	}, E = () => f ? Promise.resolve() : h(T), D = async () => {
+		if (f) throw Error("Coordinated schedule is stopped");
+		C.ticks++, C.lastTickAt = Date.now(), C.lastOutcome = null;
+		let e = new Date(Math.floor(Date.now() / o) * o), t;
+		try {
+			t = await (u.externalClaim ?? u.coordinator).tryClaim(a, e, o);
+		} catch (e) {
+			throw C.claimFailures++, C.lastDecision = "claim-failed", e;
+		}
+		if (!t) return C.claimLosses++, C.lastDecision = "claim-lost", "deduplicated";
+		if (f) throw Error("Coordinated schedule is stopped");
+		C.claimWins++;
+		try {
+			let e = await c();
+			C.lastOutcome = r(e), C.lastDecision = "active";
+		} catch (e) {
+			throw C.taskFailures++, C.lastDecision = "task-failed", e;
+		}
+		return "ran";
+	}, O = () => f ? Promise.reject(/* @__PURE__ */ Error("Coordinated schedule is stopped")) : h(D), k = u.externalize === !0 ? t(a, o) : void 0, A = u.externalize === !0 && k === void 0;
+	k !== void 0 && u.log?.warn(`coordinated schedule: REFUSING to externalise this task — ${k}`, {
+		task: a,
+		intervalMs: o
+	});
+	let j;
+	A ? (j = (u.externalTasks?.register ?? n)({
+		name: a,
+		intervalMs: o,
+		cron: e(o),
+		run: O
+	}), u.log?.info("coordinated schedule: externalised — no in-process timer", {
+		task: a,
+		intervalMs: o
+	})) : w(o);
+	let M = {
+		name: a,
+		currentIntervalMs: () => v,
+		isArmed: () => !f && !_ && !A,
+		wake: () => {
+			if (f) return;
+			C.wakes++, C.lastWakeAt = Date.now();
+			let e = Date.now();
+			!_ && e - x < o ? C.coalescedWakes++ : (C.lastDecision = "wake", x = e, y ? b = !0 : w(0));
+		},
+		stop: () => (p === void 0 && (f = !0, g !== void 0 && clearTimeout(g), g = void 0, S = null, j?.(), p = Promise.allSettled([...m]).then(() => {})), p)
+	};
+	return i.set(M, () => ({
+		...C,
+		lastOutcome: C.lastOutcome === null ? null : { ...C.lastOutcome },
+		task: a,
+		state: f ? "stopped" : A ? "externalized" : y ? "running" : _ ? "disarmed" : "armed",
+		baseIntervalMs: o,
+		currentIntervalMs: v,
+		maxIdleIntervalMs: d,
+		nextTickAt: S,
+		disarmWhenIdle: u.disarmWhenIdle ?? !1
+	})), M;
+}, l = (e, t, n, r, i = !1) => {
+	if (e === void 0 || !e.idle) return t;
+	let a = typeof e.nextDueInMs == "number" && Number.isFinite(e.nextDueInMs) ? e.nextDueInMs : void 0;
+	if (a === void 0 && e.nextDueInMs === null && i) return "disarm";
+	let o = Math.min(Math.max(n, t) * 2, r);
+	return a === void 0 ? o : Math.max(t, i ? a : Math.min(o, a));
+}, u = (e) => (t, n, r, i) => c(t, n, r, {
+	...e,
+	...e.externalizeTask === void 0 ? {} : { externalize: e.externalizeTask(t) },
+	...i?.disarmWhenIdle === void 0 ? {} : { disarmWhenIdle: i.disarmWhenIdle }
+});
+//#endregion
+export { o as DEFAULT_MAX_IDLE_INTERVAL_MS, a as inspectCoordinatedSchedule, u as makeCoordinatedScheduler, l as nextDelay, s as readPollCeilingMs, c as scheduleCoordinated };