@mark1russell7/service 0.5.0 → 0.5.2

package/build/index.js

@@ -3,6 +3,7 @@ import { detectionTime, heartbeat } from "./heartbeat.js";
 import { a as recoverSpan, i as heartbeatDetection, n as asWindow, r as failSpan, t as asDebounce } from "./timing-DGRi3XCI.js";
 import { n as operationProblems, t as mayReissue } from "./operation-DL5RxFds.js";
 import { backoffBand, backoffDelay, backoffProblems } from "./backoff.js";
+import { n as countOf, r as millisecondsOf, t as boundedMillisecondsOf } from "./knobs-BxG-c7Zb.js";
 import { convertExact, convertible, quantity, rationals, valueIn } from "@mark1russell7/quantity";
 import { replay } from "@mark1russell7/algebra/replay";
 //#region src/description.ts
@@ -498,11 +499,37 @@ const EXIT_SIGNALS = [
 	"SIGQUIT"
 ];
 /** These are the process triggers that a declaration can opt in to. */
-const PROCESS_TRIGGERS = ["stdin-close", "ipc-close"];
+const PROCESS_TRIGGERS = [
+	"stdin-close",
+	"ipc-close",
+	"ipc-message"
+];
 /** This function tells if a number is an exit code of a process: a whole number from 0 to 255. */
 const isExitCode = (code) => Number.isInteger(code) && code >= 0 && code <= 255;
 /** This function tells if a trigger is an exit signal. A repeat signal obeys `onRepeatSignal`. */
 const isExitSignal = (trigger) => EXIT_SIGNALS.includes(trigger);
+/** This function tells if a value is a message shape: a value of JSON, with no function and no undefined. */
+const isMessageShape = (value) => {
+	if (value === null || typeof value === "string" || typeof value === "boolean") return true;
+	if (typeof value === "number") return Number.isFinite(value);
+	if (Array.isArray(value)) return value.every(isMessageShape);
+	if (typeof value !== "object") return false;
+	const prototype = Object.getPrototypeOf(value);
+	return (prototype === Object.prototype || prototype === null) && Object.values(value).every(isMessageShape);
+};
+/** This function tells if a message of the IPC channel matches a shape. */
+const matchesMessage = (shape, message) => {
+	if (shape === null || typeof shape !== "object") return Object.is(shape, message);
+	if (Array.isArray(shape)) {
+		const items = shape;
+		return Array.isArray(message) && message.length === items.length && items.every((item, at) => matchesMessage(item, message[at]));
+	}
+	if (message === null || typeof message !== "object" || Array.isArray(message)) return false;
+	const fields = message;
+	return Object.entries(shape).every(([field, value]) => Object.hasOwn(fields, field) && matchesMessage(value, fields[field]));
+};
+/** This time is the interval of the timer of a hold, the most that a timer of Node accepts. */
+const HOLD_INTERVAL = 2147483647;
 /** This function adds a handler to some events of an emitter. The handler operates one time at most. */
 const once = (emitter, events, handler) => {
 	let called = false;
@@ -556,6 +583,13 @@ const processPortOf = (find) => {
 				return once(input, ["end", "close"], handler);
 			}
 			if (trigger === "ipc-close") return once(host, ["disconnect"], handler);
+			if (trigger === "ipc-message") {
+				const receive = (message) => handler(message);
+				host.on("message", receive);
+				return () => {
+					host.off("message", receive);
+				};
+			}
 			host.on(trigger, handler);
 			return () => {
 				host.off(trigger, handler);
@@ -565,6 +599,16 @@ const processPortOf = (find) => {
 			const host = hostProcess();
 			await Promise.all([written(host.stdout), written(host.stderr)]);
 		},
+		hold() {
+			hostProcess();
+			const timer = setInterval(() => {}, HOLD_INTERVAL);
+			let held = true;
+			return () => {
+				if (!held) return;
+				held = false;
+				clearInterval(timer);
+			};
+		},
 		exit(code) {
 			hostProcess().exit(code);
 		}
@@ -572,6 +616,33 @@ const processPortOf = (find) => {
 };
 /** This port is the process of Node. */
 const nodeProcess = processPortOf(() => globalThis.process);
+/**
+* This function gives a process port for a lifecycle in a process that another part owns. That
+* part is a script, a test of an application, or a library entry. The port adds no handler of a signal or of
+* a trigger, it does not hold the process, and its `exit` only records the code. The caller stops
+* the lifecycle with `life.shutdown()`. A process with a service of its own gives its parts to
+* that service, and does not use this port.
+*/
+const embeddedProcess = () => {
+	let code = null;
+	let resolve = () => {};
+	return {
+		on() {
+			return () => {};
+		},
+		exit(requested) {
+			if (code !== null) return;
+			code = requested;
+			resolve(requested);
+		},
+		get exitCode() {
+			return code;
+		},
+		exited: new Promise((done) => {
+			resolve = done;
+		})
+	};
+};
 //#endregion
 //#region src/routes.ts
 const NAME = /^[A-Za-z_][A-Za-z0-9_]*/;
@@ -648,7 +719,7 @@ const compilePattern = (pattern) => {
 };
 //#endregion
 //#region src/requests.ts
-const isAsyncIterable = (value) => value !== null && (typeof value === "object" || typeof value === "function") && typeof value[Symbol.asyncIterator] === "function";
+const isAsyncIterable$1 = (value) => value !== null && (typeof value === "object" || typeof value === "function") && typeof value[Symbol.asyncIterator] === "function";
 const isPromiseLike = (value) => value !== null && (typeof value === "object" || typeof value === "function") && typeof value.then === "function";
 /** This function gives a stream of events from a function that gives the next event. */
 const streamOf = (next, stop) => {
@@ -793,7 +864,7 @@ const tracker = (controllers, clock, refuses, choices = /* @__PURE__ */ new Map(
 		/** This function takes the result of the work: a stream, or one value. */
 		const take = (result) => {
 			if (end !== null) return;
-			if (isAsyncIterable(result)) {
+			if (isAsyncIterable$1(result)) {
 				source = result[Symbol.asyncIterator]();
 				if (abort.signal.aborted) closeSource();
 			} else {
@@ -804,7 +875,7 @@ const tracker = (controllers, clock, refuses, choices = /* @__PURE__ */ new Map(
 		let ready;
 		try {
 			const result = work(abort.signal);
-			if (isAsyncIterable(result) || !isPromiseLike(result)) {
+			if (isAsyncIterable$1(result) || !isPromiseLike(result)) {
 				take(result);
 				ready = Promise.resolve();
 			} else ready = Promise.resolve(result).then(take, failed);
@@ -1039,7 +1110,8 @@ const lifecycle = (description, runtime, components, options = {}, bind = () =>
 		startupEnded = resolve;
 	});
 	let offs = [];
-	/** This function ends the process with a code, one time, and removes each handler of a trigger. */
+	let release = () => {};
+	/** This function ends the process with a code, one time, and removes each handler of a trigger and the hold. */
 	const end = (code, on) => {
 		state = "exited";
 		exitCode = code;
@@ -1047,22 +1119,34 @@ const lifecycle = (description, runtime, components, options = {}, bind = () =>
 		offs = [];
 		moveExit("exited", on, `exit ${code}`);
 		finish(code);
+		release();
 		port.exit(code);
 	};
-	/** This function receives a trigger of the process: the first one starts the shutdown. */
-	const triggered = (trigger) => {
+	/**
+	* This function receives a trigger of the process: the first one starts the shutdown. The cause
+	* names the trigger, and a message that stands for a signal tells it.
+	*/
+	const triggered = (trigger, cause = trigger) => {
 		if (exitState === "exited") return;
 		if (shutdownStarted || exitState === "stopping") {
 			if (isExitSignal(trigger) && repeatPolicy === "exit") {
-				fail(`${trigger} came again while the shutdown ran, and the declaration exits at once`);
+				fail(`${cause} came again while the shutdown ran, and the declaration exits at once`);
 				end(1, "exit.repeat");
 				return;
 			}
-			record("exit", exitState, exitState, "exit.repeat", trigger);
+			record("exit", exitState, exitState, "exit.repeat", cause);
 			return;
 		}
 		const code = exitCodes[trigger];
-		shutdown(trigger, code === void 0 ? {} : { code });
+		shutdown(cause, code === void 0 ? {} : { code });
+	};
+	const messages = description.shutdown.messages ?? [];
+	/** This function receives a message of the IPC channel. The first declared shape that it matches gives its trigger. */
+	const received = (message) => {
+		const found = messages.find((each) => matchesMessage(each.match, message));
+		if (found === void 0) return;
+		if (found.as === void 0) triggered("ipc-message");
+		else triggered(found.as, `${found.as} (a message of the IPC channel)`);
 	};
 	/** This function does the work of one phase, until its cap. It gives true when the work ended in time. */
 	const runPhase = async (phase, hold, work) => {
@@ -1208,7 +1292,8 @@ const lifecycle = (description, runtime, components, options = {}, bind = () =>
 		keepAlive: () => state === "running" && runtime.verdict().ready
 	};
 	bind(life);
-	offs = [...EXIT_SIGNALS, ...description.shutdown.triggers ?? []].map((trigger) => port.on(trigger, () => triggered(trigger)));
+	release = port.hold?.() ?? (() => {});
+	offs = [...EXIT_SIGNALS, ...description.shutdown.triggers ?? []].map((trigger) => port.on(trigger, trigger === "ipc-message" ? received : () => triggered(trigger)));
 	(async () => {
 		const started = (what) => record("gate", "starting", "starting", "component.started", what);
 		try {
@@ -1301,8 +1386,8 @@ const watchdog = (clock, spec, trace) => {
 };
 //#endregion
 //#region src/builder.ts
-const isTime = (amount) => convertible(amount.unit, "s");
-const above = (amount) => amount.value === "infinite" || isTime(amount) && valueIn(amount, "s") > 0;
+const isTime$1 = (amount) => convertible(amount.unit, "s");
+const above = (amount) => amount.value === "infinite" || isTime$1(amount) && valueIn(amount, "s") > 0;
 const whole = (count) => Number.isInteger(count) && count >= 1;
 /** This function gives the problems of a timing: a zero interval or count fails decoding. */
 const timingProblems = (policy, timing) => {
@@ -1313,15 +1398,20 @@ const timingProblems = (policy, timing) => {
 		if (!whole(timing.recoverAfter)) problems.push(`the ${policy} debounce recovers after ${timing.recoverAfter} polls, not a whole number above zero`);
 		return problems;
 	}
-	const negative = (amount) => amount !== void 0 && (!isTime(amount) || valueIn(amount, "s") < 0);
+	const negative = (amount) => amount !== void 0 && (!isTime$1(amount) || valueIn(amount, "s") < 0);
 	return negative(timing.failAfter) || negative(timing.recoverAfter) ? [`the ${policy} window is not a time of zero or more`] : [];
 };
 /** This function gives the problems of the rules of the shutdown: an unknown name, or an exit code that a process cannot give. */
-const shutdownProblems = (floor, repeat, triggers, exitCodes) => {
+const shutdownProblems = (floor, repeat, triggers, exitCodes, messages) => {
 	const problems = [];
 	if (floor !== void 0 && floor !== "half" && floor !== "none") problems.push(`the cooperative floor ${String(floor)} is not "half" or "none"`);
 	if (repeat !== void 0 && repeat !== "ignore" && repeat !== "exit") problems.push(`the policy of a repeat signal ${String(repeat)} is not "ignore" or "exit"`);
 	for (const trigger of triggers) if (!PROCESS_TRIGGERS.includes(trigger)) problems.push(`the trigger ${String(trigger)} is not a process trigger (${PROCESS_TRIGGERS.join(", ")})`);
+	if (triggers.includes("ipc-message") && messages.length === 0) problems.push(`the trigger ipc-message has no message to match: declare it with svc.trigger("ipc-message", { match })`);
+	for (const message of messages) {
+		if (!isMessageShape(message.match)) problems.push(`the match of a message trigger is not a value of JSON: ${String(message.match)}`);
+		if (message.as !== void 0 && !isExitSignal(message.as)) problems.push(`a message trigger stands for ${String(message.as)}, not an exit signal (${EXIT_SIGNALS.join(", ")})`);
+	}
 	for (const [trigger, code] of Object.entries(exitCodes)) {
 		if (!(EXIT_SIGNALS.includes(trigger) || triggers.includes(trigger))) problems.push(`the exit code of ${trigger} names no exit signal and no declared trigger`);
 		if (code === void 0 || !isExitCode(code)) problems.push(`the exit code of ${trigger} is ${String(code)}, not a whole number from 0 to 255`);
@@ -1346,6 +1436,7 @@ const service = (name) => {
 	let floor;
 	let repeat;
 	const triggers = [];
+	const messages = [];
 	const exitCodes = {};
 	let started = false;
 	let partial = false;
@@ -1567,7 +1658,13 @@ const service = (name) => {
 		},
 		trigger(...given) {
 			composing("a trigger");
-			for (const each of given) if (!triggers.includes(each)) triggers.push(each);
+			const [first, message] = given;
+			if (first === "ipc-message" && typeof message === "object" && message !== null) {
+				if (!triggers.includes("ipc-message")) triggers.push("ipc-message");
+				messages.push({ ...message });
+				return builder;
+			}
+			for (const each of given) if (typeof each === "string" && !triggers.includes(each)) triggers.push(each);
 			return builder;
 		},
 		exitCode(trigger, code) {
@@ -1586,6 +1683,7 @@ const service = (name) => {
 			if (given.cooperativeFloor !== void 0) builder.cooperativeFloor(given.cooperativeFloor);
 			if (given.onRepeatSignal !== void 0) builder.onRepeatSignal(given.onRepeatSignal);
 			if (given.triggers !== void 0) builder.trigger(...given.triggers);
+			for (const message of given.messages ?? []) builder.trigger("ipc-message", message);
 			for (const [trigger, code] of Object.entries(given.exitCodes ?? {})) if (code !== void 0) builder.exitCode(trigger, code);
 			return builder;
 		},
@@ -1607,11 +1705,11 @@ const service = (name) => {
 			for (const gate of ["readiness", "liveness"]) problems.push(...timingProblems(gate, policies[gate]));
 			for (const check of checks) {
 				if (check.dependency !== null && !known.has(check.dependency)) problems.push(`check ${check.name} exercises ${check.dependency}, which is not a dependency`);
-				if (!isTime(check.poll.interval) || !isTime(check.poll.timeout)) problems.push(`check ${check.name} polls in a unit that is not a time`);
+				if (!isTime$1(check.poll.interval) || !isTime$1(check.poll.timeout)) problems.push(`check ${check.name} polls in a unit that is not a time`);
 				else if (!above(check.poll.interval) || !above(check.poll.timeout)) problems.push(`check ${check.name} polls with an interval or a timeout that is not above zero`);
 				if (!(check.poll.jitter >= 0 && check.poll.jitter < 1)) problems.push(`check ${check.name} has a jitter of ${check.poll.jitter}, not a fraction below 1`);
 				const timing = check.gates === null ? null : policies[check.gates];
-				if (timing?.type === "debounce" && isTime(check.poll.interval) && above(timing.interval) && valueIn(check.poll.interval, "s") !== valueIn(timing.interval, "s")) problems.push(`check ${check.name} polls every ${valueIn(check.poll.interval, "s")} s, but the ${check.gates} debounce counts polls every ${valueIn(timing.interval, "s")} s`);
+				if (timing?.type === "debounce" && isTime$1(check.poll.interval) && above(timing.interval) && valueIn(check.poll.interval, "s") !== valueIn(timing.interval, "s")) problems.push(`check ${check.name} polls every ${valueIn(check.poll.interval, "s")} s, but the ${check.gates} debounce counts polls every ${valueIn(timing.interval, "s")} s`);
 			}
 			for (const controller of controllers) {
 				for (const needed of controller.requires) if (!known.has(needed)) problems.push(`controller ${controller.name} requires ${needed}, which is not a dependency`);
@@ -1619,8 +1717,8 @@ const service = (name) => {
 				for (const declared of controller.patterns) problems.push(...routePatternProblems(`controller ${controller.name}`, declared));
 			}
 			for (const dependency of dependencies) for (const [name, operation] of Object.entries(dependency.operations)) problems.push(...operationProblems(`dependency ${dependency.name}`, name, operation));
-			for (const phase of phases) if (!isTime(phase.cap)) problems.push(`phase ${phase.name}'s cap is not a time`);
-			problems.push(...shutdownProblems(floor, repeat, triggers, exitCodes));
+			for (const phase of phases) if (!isTime$1(phase.cap)) problems.push(`phase ${phase.name}'s cap is not a time`);
+			problems.push(...shutdownProblems(floor, repeat, triggers, exitCodes, messages));
 			const ranked = phases.map((phase) => phase.name).filter((each) => stageRank(each) >= 0);
 			for (let at = 1; at < ranked.length; at += 1) if (stageRank(ranked[at]) < stageRank(ranked[at - 1])) problems.push(`the phase "${ranked[at]}" comes after "${ranked[at - 1]}", but the stages go ${STAGES.join(", ")}`);
 			if (problems.length > 0) throw new Error(`${name}: ${problems.join("; ")}`);
@@ -1663,6 +1761,7 @@ const service = (name) => {
 					...floor === void 0 ? {} : { cooperativeFloor: floor },
 					onRepeatSignal: repeat,
 					...triggers.length === 0 ? {} : { triggers: [...triggers] },
+					...messages.length === 0 ? {} : { messages: messages.map((each) => ({ ...each })) },
 					...Object.keys(exitCodes).length === 0 ? {} : { exitCodes: { ...exitCodes } }
 				}
 			};
@@ -1807,6 +1906,7 @@ const SERVICE_RULES = [
 	"O17",
 	"O18",
 	"O19",
+	"O20",
 	"O21",
 	"O22",
 	"O23",
@@ -1816,6 +1916,14 @@ const SERVICE_RULES = [
 const secondsOf = (amount) => rationals.toNumber(convertExact(rationals.fromNumber(amount.value), amount.unit, "s"));
 /** This function gives an amount, or no bound, as the law binds it. */
 const boundOf = (amount) => amount.value === "infinite" ? "inf" : secondsOf(amount);
+/** This function tells if a unit is a time. A unit that the package does not know is not a time. */
+const isTime = (unit) => {
+	try {
+		return convertible(unit, "s");
+	} catch {
+		return false;
+	}
+};
 /** This function gives the largest of some numbers of seconds, or undefined when there are none. */
 const most = (values) => values.length === 0 ? void 0 : Math.max(...values);
 /** This function gives what the declaration tells about the service, as symbols of the law, and the source of each. */
@@ -1857,7 +1965,30 @@ const dependencyBindings = (dependency, scenario) => {
 	for (const [symbol, amount] of Object.entries(scenario.dependencies?.[dependency.name] ?? {})) bind[symbol.includes("@") ? symbol : `${symbol}@dependency`] = boundOf(amount);
 	return bind;
 };
+/**
+* These are the hops of the law at which the knobs of a transport bind, by its kind. A worker does
+* its units as a consumer does, thus both bind at `consumer` (O20). A server binds at no hop yet.
+*/
+const TRANSPORT_HOPS = {
+	server: null,
+	consumer: "consumer",
+	worker: "consumer"
+};
+/**
+* This function gives the time knobs of a transport at the hop of its kind, and the values of the
+* scenario for its source. A knob with a hop in its name binds at that hop. A count binds no symbol.
+*/
+const transportBindings = (transport, hop, scenario) => {
+	const bind = {};
+	for (const [knob, amount] of Object.entries(transport.knobs)) {
+		if (!isTime(amount.unit)) continue;
+		bind[knob.includes("@") ? knob : `${knob}@${hop}`] = boundOf(amount);
+	}
+	for (const [symbol, amount] of Object.entries(scenario.transports?.[transport.name] ?? {})) bind[symbol] = boundOf(amount);
+	return bind;
+};
 const SCOPED = /@(client|dependency|server)$/;
+const TRANSPORT_SCOPED = /@consumer$/;
 /** This identifier is the rule of the findings about a field that the declaration does not give. */
 const DECLARATION_RULE = "declaration";
 /**
@@ -1875,9 +2006,9 @@ const declarationFindings = (svc) => svc.shutdown.onRepeatSignal === void 0 ? [{
 	unbound: ["shutdown.onRepeatSignal"]
 }] : [];
 /**
-* This function applies each service rule to a declaration and a scenario: one time for the
-* service, and one time for each client. It also gives a finding for each necessary field that the
-* description does not give (`DECLARATION_RULE`).
+* This function applies each service rule to a declaration and a scenario. A rule applies one time
+* for the service, for each client, or for each consumer and worker. The function also gives a
+* finding for each necessary field that the description does not give (`DECLARATION_RULE`).
 */
 const lint = (svc, scenario, rules) => {
 	const service = serviceBindings(svc, scenario).bind;
@@ -1885,7 +2016,13 @@ const lint = (svc, scenario, rules) => {
 	for (const rule of rules) {
 		if (!SERVICE_RULES.includes(rule.id)) continue;
 		const symbols = symbolsOf(rule);
-		const scopes = symbols.some((symbol) => SCOPED.test(symbol)) ? svc.dependencies.map((dependency) => [dependency.name, {
+		const scopes = symbols.some((symbol) => TRANSPORT_SCOPED.test(symbol)) ? svc.transports.flatMap((transport) => {
+			const hop = TRANSPORT_HOPS[transport.kind];
+			return hop === null ? [] : [[transport.name, {
+				...service,
+				...transportBindings(transport, hop, scenario)
+			}]];
+		}) : symbols.some((symbol) => SCOPED.test(symbol)) ? svc.dependencies.map((dependency) => [dependency.name, {
 			...service,
 			...dependencyBindings(dependency, scenario)
 		}]) : [[svc.name, service]];
@@ -2022,6 +2159,650 @@ const kubernetes = (pod) => {
 	};
 };
 //#endregion
+//#region src/units.ts
+/** This function gives the cause of an abort as text. */
+const causeOf = (signal) => signal.reason instanceof Error ? signal.reason.message : String(signal.reason ?? "the unit got an abort");
+/**
+* This function does one unit of work, and gives its end. With a request, the unit goes through
+* `life.request`, thus the service counts it, drains it and can cut it. A throw after the abort of
+* the transport is a cut, not a failure (S6 A10). A throw after the bound is a failure.
+*/
+const runUnit = async (run) => {
+	const { clock, bound, abort, life, request, unit, work } = run;
+	const timeout = new AbortController();
+	const cancel = Number.isFinite(bound) ? clock.after(bound, () => timeout.abort(/* @__PURE__ */ new Error(`the unit did not end in its unit_processing_time of ${bound} ms`))) : () => {};
+	const call = async (tracker) => work(AbortSignal.any(tracker === void 0 ? [abort.signal, timeout.signal] : [
+		abort.signal,
+		timeout.signal,
+		tracker
+	]));
+	const thrown = (error) => {
+		if (abort.signal.aborted) return {
+			kind: "cut",
+			cause: causeOf(abort.signal),
+			retryable: false
+		};
+		if (timeout.signal.aborted) return {
+			kind: "failed",
+			error: timeout.signal.reason
+		};
+		return {
+			kind: "failed",
+			error
+		};
+	};
+	try {
+		if (request === void 0) try {
+			return {
+				kind: "done",
+				value: await call()
+			};
+		} catch (error) {
+			return thrown(error);
+		}
+		let collected;
+		try {
+			const route = typeof request.route === "string" ? request.route : request.route(unit);
+			const detail = request.detail?.(unit);
+			collected = life.request(request.controller, route, (signal) => call(signal).then((value) => ({ value })), detail === void 0 ? {} : { detail }).collect();
+		} catch (error) {
+			return {
+				kind: "failed",
+				error
+			};
+		}
+		const { items, end } = await collected;
+		if (end.kind === "done") return {
+			kind: "done",
+			value: items[0]?.value
+		};
+		if (end.kind === "failed") return thrown(end.error);
+		if (end.kind === "refused") return {
+			kind: "refused",
+			cause: end.cause
+		};
+		return {
+			kind: "cut",
+			cause: end.cause,
+			retryable: end.retryable
+		};
+	} finally {
+		cancel();
+	}
+};
+/** This function makes a flight set on a clock. */
+const flights = (clock) => {
+	const units = /* @__PURE__ */ new Set();
+	const idle = /* @__PURE__ */ new Set();
+	const lower = /* @__PURE__ */ new Set();
+	let aborted = null;
+	const settle = () => {
+		for (const done of [...lower]) done();
+		lower.clear();
+		if (units.size === 0) for (const done of [...idle]) done();
+	};
+	const abort = (reason) => {
+		aborted ??= { reason };
+		for (const unit of [...units]) if (!unit.signal.aborted) unit.abort(aborted.reason);
+	};
+	return {
+		get size() {
+			return units.size;
+		},
+		add(unit) {
+			units.add(unit);
+			if (aborted !== null && !unit.signal.aborted) unit.abort(aborted.reason);
+			return () => {
+				if (units.delete(unit)) settle();
+			};
+		},
+		abort,
+		clear() {
+			units.clear();
+			settle();
+		},
+		drain(deadline, signal) {
+			const cooperative = () => abort(signal.reason);
+			if (signal.aborted) cooperative();
+			else signal.addEventListener("abort", cooperative, { once: true });
+			if (units.size === 0 || deadline <= clock.now()) {
+				signal.removeEventListener("abort", cooperative);
+				return Promise.resolve();
+			}
+			return new Promise((resolve) => {
+				let cancel = () => {};
+				const done = () => {
+					idle.delete(done);
+					cancel();
+					signal.removeEventListener("abort", cooperative);
+					resolve();
+				};
+				idle.add(done);
+				cancel = clock.after(Math.max(0, deadline - clock.now()), done);
+			});
+		},
+		less() {
+			return new Promise((resolve) => lower.add(resolve));
+		},
+		release() {
+			for (const done of [...lower]) done();
+			lower.clear();
+		}
+	};
+};
+/** This function makes a sleeper on a clock. */
+const sleeper = (clock) => {
+	let wakes = 0;
+	let stopped = false;
+	const sleeps = /* @__PURE__ */ new Set();
+	const backoffs = /* @__PURE__ */ new Set();
+	const wait = (ms, into) => stopped ? Promise.resolve() : new Promise((resolve) => {
+		let cancel = () => {};
+		const done = () => {
+			if (!into.delete(done)) return;
+			cancel();
+			resolve();
+		};
+		into.add(done);
+		if (Number.isFinite(ms)) cancel = clock.after(ms, done);
+	});
+	return {
+		get wakes() {
+			return wakes;
+		},
+		sleep(ms, since) {
+			if (since !== wakes) return Promise.resolve();
+			return wait(ms, sleeps);
+		},
+		backoff(ms) {
+			return wait(ms, backoffs);
+		},
+		wake() {
+			wakes += 1;
+			const ended = sleeps.size;
+			for (const done of [...sleeps]) done();
+			return ended;
+		},
+		stop() {
+			stopped = true;
+			for (const done of [...sleeps, ...backoffs]) done();
+		}
+	};
+};
+/** This function waits for a work until a bound on the clock, in milliseconds. */
+const settleWithin = (clock, ms, work) => new Promise((resolve) => {
+	const cancel = Number.isFinite(ms) ? clock.after(ms, () => resolve({ kind: "bound" })) : () => {};
+	work.then(() => {
+		cancel();
+		resolve({ kind: "done" });
+	}, (error) => {
+		cancel();
+		resolve({
+			kind: "failed",
+			error
+		});
+	});
+});
+/**
+* This function gives the backoff of the knobs of a loop. The first delay is `retry_base`, and each
+* delay is two times longer, up to `retry_cap`. Each delay has a jitter up to the base, as in the Redis client.
+*/
+const retryOf = (knobs, owner) => {
+	const base = boundedMillisecondsOf(knobs, "retry_base", owner);
+	const backoff = {
+		base,
+		factor: 2,
+		cap: boundedMillisecondsOf(knobs, "retry_cap", owner),
+		jitter: {
+			kind: "add",
+			amount: base
+		}
+	};
+	const problems = backoffProblems(backoff);
+	if (problems.length > 0) throw new Error(`${owner}: the retry_base and retry_cap give no backoff: ${problems.join(", ")}`);
+	return backoff;
+};
+/**
+* This function gives the problems of the bounds of a loop in a declaration. The close bound fits
+* in the cap of `close transports`. The bound of a unit fits in the cap of `drain`, or the drain can cut a unit (S6 A10).
+*/
+const boundProblems = (owner, closeBound, unitBound, description) => {
+	const capOf = (name) => {
+		const phase = description.shutdown.phases.find((each) => each.name === name);
+		return phase === void 0 ? void 0 : valueIn(phase.cap, "ms");
+	};
+	const found = [];
+	const close = capOf("close transports");
+	if (close === void 0) found.push(`${owner} needs the phase "close transports" to close`);
+	else if (closeBound >= close) found.push(`the close_bound of ${owner}, ${closeBound} ms, does not fit in the cap of "close transports", ${close} ms`);
+	const drain = capOf("drain");
+	if (drain === void 0) found.push(`${owner} needs the phase "drain" to end its units`);
+	else if (!Number.isFinite(unitBound)) found.push(`the unit_processing_time of ${owner} has no bound, thus the drain can cut a unit at its cap of ${drain} ms`);
+	else if (unitBound >= drain) found.push(`the unit_processing_time of ${owner}, ${unitBound} ms, does not fit in the cap of "drain", ${drain} ms`);
+	return found;
+};
+//#endregion
+//#region src/worker.ts
+const OWNER$1 = "workerLoop";
+/**
+* This function makes a worker loop as a transport (S6 A10). It has a setup, an iteration and a
+* teardown, and each lane does its iterations one at a time.
+* - The start does the setup. A failed setup gets its teardown, and the start throws.
+* - The first iteration of each lane comes after the startup ends. Each sleep and each backoff is on the clock.
+* - `stopIntake` starts no new iteration, and it ends each sleep and each backoff.
+* - `drain` waits for each iteration in flight until the deadline, and gives it the cooperative
+*   abort. A throw after that abort is not a failure.
+* - `close` aborts each iteration, waits for its end, and does the teardown, all in `close_bound`.
+*/
+const workerLoop = (knobs, options) => {
+	const sleep = millisecondsOf(knobs, "worker_sleep", OWNER$1);
+	const bound = millisecondsOf(knobs, "unit_processing_time", OWNER$1);
+	const backoff = retryOf(knobs, OWNER$1);
+	const closeBound = boundedMillisecondsOf(knobs, "close_bound", OWNER$1);
+	const lanes = countOf(knobs, "concurrency", OWNER$1);
+	if (!Number.isFinite(lanes)) throw new Error(`${OWNER$1} needs a concurrency with a bound: each lane is a loop`);
+	const clock = options.clock ?? realClock;
+	const random = options.random ?? Math.random;
+	const running = flights(clock);
+	const rests = sleeper(clock);
+	const intake = new AbortController();
+	const pending = /* @__PURE__ */ new Set();
+	let started = false;
+	let setup = null;
+	let state;
+	let tornDown = null;
+	let closing = null;
+	const report = (error, failures) => {
+		try {
+			options.onError?.(error, failures);
+		} catch {}
+	};
+	/** This function does the teardown one time, after the setup ends, and only when the setup started. */
+	const teardown = () => {
+		if (tornDown !== null) return tornDown;
+		const release = options.teardown;
+		const made = setup;
+		tornDown = made === null || release === void 0 ? Promise.resolve() : made.then((given) => release(given), () => release(void 0));
+		return tornDown;
+	};
+	const keep = (work) => {
+		pending.add(work);
+		const forget = () => {
+			pending.delete(work);
+		};
+		work.then(forget, forget);
+		return work;
+	};
+	/** This function is one lane: an iteration, then its sleep or its backoff, until the intake stops. */
+	const lane = async (index, life) => {
+		let failures = 0;
+		let since = rests.wakes;
+		await rests.sleep(0, since);
+		for (;;) {
+			if (intake.signal.aborted) return;
+			since = rests.wakes;
+			const abort = new AbortController();
+			const remove = running.add(abort);
+			const count = failures;
+			const end = await runUnit({
+				clock,
+				bound,
+				abort,
+				life,
+				request: options.request,
+				unit: index,
+				work: (signal) => keep((async () => options.iteration({
+					signal,
+					intake: intake.signal,
+					state,
+					lane: index,
+					failures: count,
+					life
+				}))())
+			});
+			remove();
+			if (end.kind === "cut") return;
+			if (end.kind === "done") {
+				failures = 0;
+				await rests.sleep(end.value === "more" ? 0 : sleep, end.value === "more" ? rests.wakes : since);
+				continue;
+			}
+			failures += 1;
+			report(end.kind === "failed" ? end.error : /* @__PURE__ */ new Error(`the service refused the iteration: ${end.cause}`), failures);
+			await rests.backoff(backoffDelay(backoff, failures, random));
+		}
+	};
+	return {
+		knobs: { ...knobs },
+		async start(signal, life) {
+			if (closing !== null) throw new Error(`${OWNER$1}: a closed loop does not start again`);
+			if (started) throw new Error(`${OWNER$1}: the loop started already`);
+			started = true;
+			const make = options.setup;
+			setup = make === void 0 ? Promise.resolve(void 0) : new Promise((resolve) => resolve(make(signal)));
+			try {
+				await setup.then((given) => {
+					state = given;
+				});
+			} catch (error) {
+				await settleWithin(clock, closeBound, teardown());
+				throw error;
+			}
+			life.started.then(() => {
+				if (intake.signal.aborted || life.state !== "running") return;
+				for (let index = 0; index < lanes; index += 1) lane(index, life).catch((error) => report(error, 0));
+			});
+		},
+		stopIntake() {
+			if (intake.signal.aborted) return;
+			intake.abort(/* @__PURE__ */ new Error(`${OWNER$1} stopped its intake`));
+			rests.stop();
+		},
+		drain(deadline, signal) {
+			return running.drain(deadline, signal);
+		},
+		inFlight: () => running.size,
+		wake() {
+			if (intake.signal.aborted) return false;
+			rests.wake();
+			return true;
+		},
+		close() {
+			if (closing !== null) return closing;
+			if (!intake.signal.aborted) intake.abort(/* @__PURE__ */ new Error(`${OWNER$1} closed`));
+			rests.stop();
+			running.abort(/* @__PURE__ */ new Error(`${OWNER$1} closed`));
+			running.clear();
+			closing = (async () => {
+				const began = clock.now();
+				const ended = await settleWithin(clock, closeBound, Promise.allSettled([...pending]));
+				const down = await settleWithin(clock, Math.max(0, closeBound - (clock.now() - began)), teardown());
+				if (ended.kind === "bound") throw new Error(`${OWNER$1}: an iteration did not end in the close_bound of ${closeBound} ms after its abort`);
+				if (down.kind === "failed") throw down.error;
+				if (down.kind === "bound") throw new Error(`${OWNER$1}: the teardown did not end in the close_bound of ${closeBound} ms`);
+			})();
+			return closing;
+		},
+		problems(description) {
+			return boundProblems(OWNER$1, closeBound, bound, description);
+		}
+	};
+};
+//#endregion
+//#region src/queue.ts
+/**
+* This function gives the redelivery policy of S6 A11. A poison message gets `ack`. Each other job
+* goes back on the queue after its first failure, one time. After a later failure, `then` gives the
+* action: the declared policy of the queue.
+*/
+const redeliverOnce = (then, poison) => (failure) => {
+	if (poison?.(failure.error, failure.job) === true) return "ack";
+	if (failure.delivery <= 1) return "requeue";
+	return typeof then === "function" ? then(failure) : then;
+};
+const OWNER = "queueDrain";
+const ACTIONS = [
+	"requeue",
+	"reject",
+	"ack"
+];
+const STOPPED = Symbol("the intake stopped");
+const isAsyncIterable = (value) => value !== null && (typeof value === "object" || typeof value === "function") && typeof value[Symbol.asyncIterator] === "function";
+/**
+* This function makes a queue drain as a transport (S6 A11). One taker takes the jobs from the
+* source while a slot is free, and each job operates in its slot.
+* - A success gets `ack`. A failure gets the action of the redelivery policy.
+* - `stopIntake` takes no new job, and a job that the drain took and did not start goes back (`requeue`, `unstarted`).
+* - `drain` waits for each job in flight until the deadline, and gives it the cooperative abort.
+* - `close` aborts each job, waits for its end, and closes the source, all in `close_bound`. A job
+*   that does not end in the bound gets `reject`.
+*/
+const queueDrain = (knobs, options) => {
+	const poll = millisecondsOf(knobs, "queue_poll_interval", OWNER);
+	const bound = millisecondsOf(knobs, "unit_processing_time", OWNER);
+	const backoff = retryOf(knobs, OWNER);
+	const closeBound = boundedMillisecondsOf(knobs, "close_bound", OWNER);
+	const concurrency = countOf(knobs, "concurrency", OWNER);
+	const { settle } = options;
+	const clock = options.clock ?? realClock;
+	const random = options.random ?? Math.random;
+	const running = flights(clock);
+	const rests = sleeper(clock);
+	const intake = new AbortController();
+	const stopped = new Promise((resolve) => intake.signal.addEventListener("abort", () => resolve(STOPPED), { once: true }));
+	const pending = /* @__PURE__ */ new Set();
+	const active = /* @__PURE__ */ new Set();
+	let refusals = 0;
+	let pausedUntil = Number.NEGATIVE_INFINITY;
+	let cancelSource = () => {};
+	let started = false;
+	let closing = null;
+	const report = (error, job) => {
+		try {
+			options.onError?.(error, job);
+		} catch {}
+	};
+	const keep = (work) => {
+		pending.add(work);
+		const forget = () => {
+			pending.delete(work);
+		};
+		work.then(forget, forget);
+	};
+	/** This function tells the queue the end of a job, one time. A throw of the queue is a failure. */
+	const once = async (unit, tell) => {
+		if (unit.settled) return;
+		unit.settled = true;
+		try {
+			await tell();
+		} catch (error) {
+			report(error, unit.job);
+		}
+	};
+	const handBack = (job) => keep((async () => {
+		try {
+			await settle.requeue(job, "unstarted");
+		} catch (error) {
+			report(error, job);
+		}
+	})());
+	/** This function gives the action of the policy for a failed job. A policy that throws, or that gives no action, rejects the job. */
+	const actionOf = (job, error, delivery) => {
+		try {
+			const action = options.redelivery({
+				job,
+				error,
+				delivery
+			});
+			if (ACTIONS.includes(action)) return action;
+			report(/* @__PURE__ */ new Error(`the redelivery policy gave ${String(action)}, not requeue, reject or ack`), job);
+		} catch (thrown) {
+			report(thrown, job);
+		}
+		return "reject";
+	};
+	const settleEnd = (unit, end, delivery) => {
+		const { job } = unit;
+		if (end.kind === "done") return once(unit, () => settle.ack(job));
+		if (end.kind === "refused") {
+			report(/* @__PURE__ */ new Error(`the service refused the job: ${end.cause}`), job);
+			return once(unit, () => settle.requeue(job, "unstarted"));
+		}
+		if (end.kind === "cut") {
+			if (end.retryable) return once(unit, () => settle.requeue(job, "cut"));
+			const cut = new Error(end.cause);
+			return once(unit, () => settle.reject(job, cut));
+		}
+		const { error } = end;
+		report(error, job);
+		const action = actionOf(job, error, delivery);
+		if (action === "requeue") return once(unit, () => settle.requeue(job, "failed"));
+		return once(unit, () => action === "ack" ? settle.ack(job) : settle.reject(job, error));
+	};
+	/** This function starts one job in a slot. The slot stays in flight until the queue has the end of the job. */
+	const runJob = (job, life) => {
+		const unit = {
+			job,
+			settled: false
+		};
+		active.add(unit);
+		const abort = new AbortController();
+		const remove = running.add(abort);
+		let delivery;
+		try {
+			delivery = settle.delivery(job);
+		} catch (error) {
+			report(error, job);
+			delivery = Number.POSITIVE_INFINITY;
+		}
+		keep((async () => {
+			const end = await runUnit({
+				clock,
+				bound,
+				abort,
+				life,
+				request: options.request,
+				unit: job,
+				work: (signal) => options.handle(job, {
+					signal,
+					intake: intake.signal,
+					delivery,
+					life
+				})
+			});
+			if (end.kind === "refused") {
+				refusals += 1;
+				pausedUntil = clock.now() + backoffDelay(backoff, refusals, random);
+			} else refusals = 0;
+			await settleEnd(unit, end, delivery);
+		})().finally(() => {
+			active.delete(unit);
+			remove();
+		}));
+	};
+	/** This function gives the take of the source. */
+	const takeOf = () => {
+		const source = options.source;
+		if (isAsyncIterable(source)) {
+			const iterator = source[Symbol.asyncIterator]();
+			cancelSource = () => {
+				try {
+					Promise.resolve(iterator.return?.()).catch(() => {});
+				} catch {}
+			};
+			return async () => {
+				const step = await iterator.next();
+				return step.done === true ? { kind: "end" } : {
+					kind: "job",
+					job: step.value
+				};
+			};
+		}
+		const pull = source;
+		return () => new Promise((resolve) => resolve(pull(intake.signal))).then((job) => job === null || job === void 0 ? { kind: "none" } : {
+			kind: "job",
+			job
+		});
+	};
+	/** This function is the taker: it takes a job while a slot is free, until the intake stops or the source ends. */
+	const taker = async (life) => {
+		const take = takeOf();
+		let failures = 0;
+		for (;;) {
+			if (intake.signal.aborted) return;
+			if (running.size >= concurrency) {
+				await running.less();
+				continue;
+			}
+			const pause = pausedUntil - clock.now();
+			if (pause > 0) {
+				await rests.backoff(pause);
+				continue;
+			}
+			const since = rests.wakes;
+			const taking = take().catch((error) => ({
+				kind: "error",
+				error
+			}));
+			const first = await Promise.race([taking, stopped]);
+			if (first === STOPPED || intake.signal.aborted) {
+				if (first === STOPPED) taking.then((late) => {
+					if (late.kind === "job") handBack(late.job);
+				});
+				else if (first.kind === "job") handBack(first.job);
+				return;
+			}
+			if (first.kind === "error") {
+				failures += 1;
+				report(first.error, void 0);
+				await rests.backoff(backoffDelay(backoff, failures, random));
+				continue;
+			}
+			failures = 0;
+			if (first.kind === "end") {
+				report(/* @__PURE__ */ new Error(`the source of ${OWNER} ended while its intake was open: it takes no more jobs`), void 0);
+				return;
+			}
+			if (first.kind === "none") {
+				await rests.sleep(poll, since);
+				continue;
+			}
+			runJob(first.job, life);
+		}
+	};
+	const stopTaking = (cause) => {
+		if (intake.signal.aborted) return;
+		intake.abort(new Error(cause));
+		rests.stop();
+		running.release();
+		cancelSource();
+	};
+	return {
+		knobs: { ...knobs },
+		start(_signal, life) {
+			if (closing !== null) throw new Error(`${OWNER}: a closed drain does not start again`);
+			if (started) throw new Error(`${OWNER}: the drain started already`);
+			started = true;
+			life.started.then(() => {
+				if (intake.signal.aborted || life.state !== "running") return;
+				taker(life).catch((error) => report(error, void 0));
+			});
+		},
+		stopIntake() {
+			stopTaking(`${OWNER} stopped its intake`);
+		},
+		drain(deadline, signal) {
+			return running.drain(deadline, signal);
+		},
+		inFlight: () => running.size,
+		wake() {
+			if (intake.signal.aborted) return false;
+			rests.wake();
+			return true;
+		},
+		close() {
+			if (closing !== null) return closing;
+			stopTaking(`${OWNER} closed`);
+			running.abort(/* @__PURE__ */ new Error(`${OWNER} closed`));
+			running.clear();
+			closing = (async () => {
+				const began = clock.now();
+				const ended = await settleWithin(clock, closeBound, Promise.allSettled([...pending]));
+				if (ended.kind === "bound") for (const unit of [...active]) once(unit, () => settle.reject(unit.job, /* @__PURE__ */ new Error(`${OWNER} closed with the job in flight`)));
+				const shut = options.close;
+				const down = await settleWithin(clock, Math.max(0, closeBound - (clock.now() - began)), shut === void 0 ? Promise.resolve() : (async () => shut())());
+				if (ended.kind === "bound") throw new Error(`${OWNER}: a job did not end in the close_bound of ${closeBound} ms after its abort`);
+				if (down.kind === "failed") throw down.error;
+				if (down.kind === "bound") throw new Error(`${OWNER}: the close of the source did not end in the close_bound of ${closeBound} ms`);
+			})();
+			return closing;
+		},
+		problems(description) {
+			return boundProblems(OWNER, closeBound, bound, description);
+		}
+	};
+};
+//#endregion
 //#region src/machines.ts
 /**
 * The machines of the runtime as `mark1russell7.machine/1` documents. The documents are the
@@ -2471,6 +3252,6 @@ const MACHINES = {
 	watchdog: WATCHDOG_MACHINE
 };
 //#endregion
-export { DECLARATION_RULE, EXIT_MACHINE, EXIT_SIGNALS, FORMAT, GATE_MACHINE, LATCH_MACHINE, MACHINES, POLLER_MACHINE, PROCESS_TRIGGERS, SERVICE_RULES, STAGES, WATCHDOG_MACHINE, WINDOW_MACHINE, asDebounce, asWindow, backoffBand, backoffDelay, backoffProblems, capKnob, cooperativeAbortAt, daemon, detectionTime, drainMachine, ephemeral, evaluate, failSpan, heartbeat, heartbeatDetection, inequalities, isExitCode, isExitSignal, kubernetes, lint, localDev, mayReissue, nodeProcess, platformClock, processPortOf, realClock, recoverSpan, replay, service, serviceBindings, stageRank, symbolsOf, verdictOf, watchdog };
+export { DECLARATION_RULE, EXIT_MACHINE, EXIT_SIGNALS, FORMAT, GATE_MACHINE, LATCH_MACHINE, MACHINES, POLLER_MACHINE, PROCESS_TRIGGERS, SERVICE_RULES, STAGES, WATCHDOG_MACHINE, WINDOW_MACHINE, asDebounce, asWindow, backoffBand, backoffDelay, backoffProblems, capKnob, cooperativeAbortAt, daemon, detectionTime, drainMachine, embeddedProcess, ephemeral, evaluate, failSpan, heartbeat, heartbeatDetection, inequalities, isExitCode, isExitSignal, isMessageShape, kubernetes, lint, localDev, matchesMessage, mayReissue, nodeProcess, platformClock, processPortOf, queueDrain, realClock, recoverSpan, redeliverOnce, replay, service, serviceBindings, stageRank, symbolsOf, verdictOf, watchdog, workerLoop };
 
 //# sourceMappingURL=index.js.map