@mark1russell7/service 0.1.0 → 0.2.0

package/build/index.js

@@ -1,109 +1,969 @@
-import { compare, convertExact, convertible, quantity, rationals } from "@mark1russell7/quantity";
-//#region src/timing.ts
-const seconds = (amount) => convertExact(rationals.fromNumber(amount.value), amount.unit, "s");
-const out = (value) => quantity(rationals.toNumber(value), "s");
-const fraction = (jitter) => {
-	if (!(jitter >= 0 && jitter < 1)) throw new RangeError(`jitter is a fraction below 1, not ${jitter}`);
-	return rationals.fromNumber(jitter);
-};
-const count = (polls, what) => {
-	if (!Number.isInteger(polls) || polls < 1) throw new RangeError(`${what} is a whole number of polls, not ${polls}`);
-	return rationals.rational(BigInt(polls));
+import { i as recoverSpan, n as asWindow, r as failSpan, t as asDebounce } from "./timing-DxZ4nkQg.js";
+import { n as mayReissue, r as operationProblems, t as realClock } from "./clock-DlJFFZlX.js";
+import { convertExact, convertible, quantity, rationals, valueIn } from "@mark1russell7/quantity";
+import { arr, fromStates } from "@mark1russell7/algebra";
+//#region src/description.ts
+/**
+* This is the format of a service as data: what `describe()` exports, and nothing starts. The
+* timer algebra and the ordering law read it. Each timer has a unit. Each knob comes from the
+* declaration, because the runtime has no defaults. A bound that nobody gives is "no bound", not
+* zero.
+*/
+const FORMAT = "mark1russell7.service/1";
+//#endregion
+//#region src/latch.ts
+const ms = (amount) => valueIn(amount, "ms");
+/**
+* This function makes a latch. `tripped` is its state at the start: a readiness latch starts
+* tripped, and a liveness latch starts released. The latch starts `changed` each time it trips or
+* releases, and it gives each transition to `trace`. A debounce has the states `released` and
+* `tripped`. A window also has the states `failing` and `recovering`, while one of its timers runs.
+*/
+const latch = (timing, clock, tripped, changed, trace) => {
+	let state = tripped;
+	let since = clock.now();
+	let streak = 0;
+	let fails = 0;
+	let passes = 0;
+	let failingSince = null;
+	let passingSince = null;
+	let failTimer = null;
+	let passTimer = null;
+	/** This function gives the name of the state, as the machine documents name it. */
+	const named = () => state ? passingSince === null ? "tripped" : "recovering" : failingSince === null ? "released" : "failing";
+	/** This function does one step of the machine, and gives its transition to the trace. */
+	const step = (on, change) => {
+		const from = named();
+		change();
+		trace?.(from, named(), on);
+	};
+	const set = (next) => {
+		if (next === state) return;
+		state = next;
+		since = clock.now();
+		changed();
+	};
+	const stopFail = () => {
+		failTimer?.();
+		failTimer = null;
+		failingSince = null;
+	};
+	const stopPass = () => {
+		passTimer?.();
+		passTimer = null;
+		passingSince = null;
+	};
+	const debounce = (result) => {
+		if (timing.type !== "debounce") return;
+		if (result.outcome === "ok") {
+			passes += 1;
+			fails = 0;
+			if (state && passes >= timing.recoverAfter) set(false);
+		} else {
+			fails += 1;
+			passes = 0;
+			if (!state && fails >= timing.failAfter) set(true);
+		}
+	};
+	const windowed = (result) => {
+		if (timing.type !== "window") return;
+		if (result.outcome === "ok") {
+			stopFail();
+			if (!state) return;
+			if (timing.recoverAfter === void 0) {
+				set(false);
+				return;
+			}
+			if (passingSince !== null) return;
+			const wait = ms(timing.recoverAfter);
+			if (wait <= 0) {
+				stopPass();
+				set(false);
+				return;
+			}
+			passingSince = result.at;
+			passTimer = clock.after(wait, () => step("window.recovered", () => {
+				passTimer = null;
+				passingSince = null;
+				set(false);
+			}));
+			return;
+		}
+		stopPass();
+		if (state || failingSince !== null) return;
+		const wait = ms(timing.failAfter);
+		if (wait <= 0) {
+			stopFail();
+			set(true);
+			return;
+		}
+		failingSince = result.at;
+		failTimer = clock.after(wait, () => step("window.failed", () => {
+			failTimer = null;
+			failingSince = null;
+			set(true);
+		}));
+	};
+	return {
+		get tripped() {
+			return state;
+		},
+		get since() {
+			return since;
+		},
+		get streak() {
+			return streak;
+		},
+		record(result) {
+			if (result.outcome === "indeterminate") return;
+			const pass = result.outcome === "ok";
+			step(pass ? "poll.ok" : "poll.fail", () => {
+				streak = pass ? Math.max(0, streak) + 1 : Math.min(0, streak) - 1;
+				debounce(result);
+				windowed(result);
+			});
+		},
+		stop() {
+			stopFail();
+			stopPass();
+		}
+	};
 };
-/** N polls with jitter take from N − 1 short intervals to N long intervals. */
-const debounced = (polls, interval, jitter) => [rationals.mul(rationals.sub(polls, rationals.ONE), rationals.mul(interval, rationals.sub(rationals.ONE, jitter))), rationals.mul(polls, rationals.mul(interval, rationals.add(rationals.ONE, jitter)))];
+//#endregion
+//#region src/poller.ts
+const message$1 = (error) => error instanceof Error ? error.message : String(error);
 /**
-* This function gives the time that a policy takes to fail after its signal becomes bad. A
-* debounce of N polls takes approximately N intervals, with the jitter. A window takes its
-* duration, plus one interval at most for the poll that starts its sequence. A step that fails by
-* a timeout adds the timeout of the poll. At 3 polls of 5 s ± 20 %, the latch fails in 8–18 s on
-* an error, and in 12–22 s on a 4 s timeout.
+* This function makes a poller. The loop is on a fixed delay from the start of each poll. Thus the
+* next poll starts one interval after the current poll starts, with the jitter (±20 % is 0.2).
+* The timing algebra of the declaration uses this model.
+*
+* Each poll makes a new measurement. While a use of the check is pending, the poller does not
+* start the check again. Such a poll fails at once with the same cause, and the sequence of
+* failures continues.
 */
-const failSpan = (timing, poll, by = "error") => {
-	const jitter = fraction(poll.jitter);
-	const late = by === "timeout" ? seconds(poll.timeout) : rationals.ZERO;
-	if (timing.type === "debounce") {
-		const [min, max] = debounced(count(timing.failAfter, "failAfter"), seconds(timing.interval), jitter);
-		return {
-			min: out(rationals.add(min, late)),
-			max: out(rationals.add(max, late))
-		};
-	}
-	const duration = seconds(timing.failAfter);
-	const interval = rationals.mul(seconds(poll.interval), rationals.add(rationals.ONE, jitter));
+const poller = (options) => {
+	const { clock, poll, run } = options;
+	const interval = valueIn(poll.interval, "ms");
+	const timeout = valueIn(poll.timeout, "ms");
+	let last = null;
+	let next = null;
+	let stopped = false;
+	let looping = false;
+	let pending = null;
+	const active = /* @__PURE__ */ new Set();
+	/** This function gives the name of the state, as the machine document of the poller names it. */
+	const named = () => stopped ? "stopped" : pending !== null ? pending.late ? "hung" : "calling" : looping ? "waiting" : "idle";
+	const step = (on, change) => {
+		const from = named();
+		change();
+		options.trace?.(from, named(), on);
+	};
+	const result = (outcome, started, fields = {}) => ({
+		outcome,
+		at: clock.now(),
+		took: clock.now() - started,
+		cause: fields.cause ?? null,
+		timedOut: fields.timedOut ?? false,
+		thrown: fields.thrown ?? false,
+		forced: fields.forced ?? false
+	});
+	const once = () => {
+		const started = clock.now();
+		if (options.forced()) return Promise.resolve(result("error", started, {
+			cause: "the force-fail list names it",
+			forced: true
+		}));
+		if (pending !== null) {
+			const cause = `its call of ${Math.round(started - pending.since)} ms ago is still pending`;
+			return Promise.resolve(result("error", started, { cause }));
+		}
+		const controller = new AbortController();
+		return new Promise((resolve) => {
+			let done = false;
+			const finish = (value) => {
+				if (done) return;
+				done = true;
+				active.delete(abandon);
+				cancel();
+				resolve(value);
+			};
+			const abandon = () => {
+				controller.abort();
+				finish(result("error", started, { cause: "the runtime stopped" }));
+			};
+			active.add(abandon);
+			const call = {
+				since: started,
+				late: false
+			};
+			pending = call;
+			const cancel = clock.after(timeout, () => {
+				controller.abort();
+				step("timeout", () => {
+					if (pending === call) call.late = true;
+				});
+				finish(result("error", started, {
+					cause: `no answer in ${timeout} ms`,
+					timedOut: true
+				}));
+			});
+			const settled = () => {
+				if (pending !== call) return;
+				step(call.late ? "late-answer" : "answer", () => {
+					pending = null;
+				});
+			};
+			let answer;
+			try {
+				answer = Promise.resolve(run(controller.signal));
+			} catch (error) {
+				answer = Promise.reject(error);
+			}
+			answer.then((value) => {
+				settled();
+				const outcome = value ?? "ok";
+				finish(result(outcome, started, outcome === "ok" ? {} : { cause: `the check gave ${outcome}` }));
+			}, (error) => {
+				settled();
+				finish(result("error", started, {
+					cause: message$1(error),
+					thrown: true
+				}));
+			});
+		});
+	};
+	const handle = (value) => {
+		last = value;
+		if (!stopped) options.record(value);
+		return value;
+	};
+	const jittered = () => interval * (1 + poll.jitter * (2 * options.random() - 1));
+	const tick = () => {
+		next = null;
+		if (stopped) return;
+		let polled;
+		step("tick", () => {
+			next = clock.after(jittered(), tick);
+			polled = once();
+		});
+		polled.then(handle);
+	};
 	return {
-		min: out(rationals.add(duration, late)),
-		max: out(rationals.add(rationals.add(duration, interval), late))
+		get last() {
+			return last;
+		},
+		pollNow: () => {
+			let polled;
+			step("sweep", () => {
+				polled = once();
+			});
+			return polled.then(handle);
+		},
+		start(delay) {
+			if (stopped || next !== null) return;
+			step("start", () => {
+				looping = true;
+				next = clock.after(Math.max(0, delay), tick);
+			});
+		},
+		jittered,
+		stop() {
+			if (stopped) return;
+			step("stop", () => {
+				stopped = true;
+				next?.();
+				next = null;
+			});
+			for (const abandon of [...active]) abandon();
+		}
 	};
 };
-/** This function gives the time that a policy takes to recover after its signal becomes good. */
-const recoverSpan = (timing, poll) => {
-	const jitter = fraction(poll.jitter);
-	if (timing.type === "debounce") {
-		const [min, max] = debounced(count(timing.recoverAfter, "recoverAfter"), seconds(timing.interval), jitter);
-		return {
-			min: out(min),
-			max: out(max)
+//#endregion
+//#region src/health.ts
+/**
+* This function makes the runtime of a declaration. The service has no defaults of its own: each
+* timing, poll and coupling comes from the description.
+*/
+const healthRuntime = (description, runs, options = {}) => {
+	const clock = options.clock ?? realClock;
+	const random = options.random ?? Math.random;
+	const forced = new Set(options.forceFail ?? []);
+	const startedAt = clock.now();
+	const budget = valueIn(description.policies.startup, "ms");
+	const entries = /* @__PURE__ */ new Map();
+	const dependencies = new Set(description.dependencies.map((dependency) => dependency.name));
+	const lateDependencies = /* @__PURE__ */ new Set();
+	const listeners = /* @__PURE__ */ new Set();
+	let started = false;
+	let draining = false;
+	let stopped = false;
+	let gate = "closed";
+	const tracer = (machine, instance) => (from, to, on) => options.record?.({
+		at: clock.now(),
+		machine,
+		instance,
+		from,
+		to,
+		on
+	});
+	const gateTrace = tracer("gate", description.name);
+	const moveGate = (to, on, detail) => {
+		const from = gate;
+		gate = to;
+		options.record?.({
+			at: clock.now(),
+			machine: "gate",
+			instance: description.name,
+			from,
+			to,
+			on,
+			...detail === void 0 ? {} : { detail }
+		});
+	};
+	let budgetTimer = clock.after(budget, () => {
+		budgetTimer = null;
+		if (gate !== "open" && gate !== "failed") gateTrace(gate, gate, "startup.over-budget");
+	});
+	const changed = () => {
+		if (listeners.size === 0) return;
+		const now = verdict();
+		for (const listener of listeners) listener(now);
+	};
+	const add = (check, given, late) => {
+		const run = options.wrapCheck?.(check, given) ?? given;
+		const timing = check.gates === null ? null : description.policies[check.gates];
+		const made = timing === null ? null : latch(timing, clock, check.gates === "readiness", changed, tracer(timing.type === "window" ? "window" : "latch", check.name));
+		const entry = {
+			check,
+			latch: made,
+			poller: poller({
+				name: check.name,
+				poll: check.poll,
+				run,
+				clock,
+				random,
+				forced: () => forced.has(check.name) || check.dependency !== null && forced.has(check.dependency),
+				record: (result) => {
+					made?.record(result);
+					if (result.outcome === "ok" && check.dependency !== null) {
+						if (lateDependencies.delete(check.dependency)) changed();
+					}
+				},
+				trace: tracer("poller", check.name)
+			})
 		};
+		entries.set(check.name, entry);
+		if (late && !stopped) {
+			entry.poller.pollNow();
+			entry.poller.start(entry.poller.jittered());
+		}
+	};
+	for (const check of description.checks) {
+		const run = runs.get(check.name);
+		if (run === void 0) throw new Error(`check ${check.name} has no function: the runtime has no defaults`);
+		add(check, run, false);
 	}
-	const duration = timing.recoverAfter === void 0 ? rationals.ZERO : seconds(timing.recoverAfter);
-	const interval = rationals.mul(seconds(poll.interval), rationals.add(rationals.ONE, jitter));
+	const latchesOf = (gateOf, keep = () => true) => [...entries.values()].flatMap((entry) => entry.check.gates === gateOf && entry.latch !== null && keep(entry.check) ? [entry.latch] : []);
+	const released = (latches) => latches.every((each) => !each.tripped);
+	/** This function tells if a policy fails through a declared coupling from another policy. */
+	const coupledOff = (to, base) => description.couplings.some((coupling) => coupling.to === to && !base[coupling.from]);
+	const verdict = () => {
+		const base = {
+			readiness: released(latchesOf("readiness")) && lateDependencies.size === 0,
+			liveness: released(latchesOf("liveness"))
+		};
+		const alive = base.liveness && !coupledOff("liveness", base);
+		const open = started && !draining && !coupledOff("readiness", base);
+		const ready = open && base.readiness;
+		const dependencyReady = (name) => !lateDependencies.has(name) && released(latchesOf("readiness", (check) => check.dependency === name));
+		const own = released(latchesOf("readiness", (check) => check.dependency === null));
+		const dependenciesOut = {};
+		for (const name of dependencies) dependenciesOut[name] = dependencyReady(name);
+		const controllers = {};
+		for (const controller of description.controllers) controllers[controller.name] = open && own && controller.requires.every(dependencyReady);
+		const checks = {};
+		for (const [name, entry] of entries) checks[name] = {
+			gates: entry.check.gates,
+			dependency: entry.check.dependency,
+			tripped: entry.latch?.tripped ?? null,
+			streak: entry.latch?.streak ?? 0,
+			since: entry.latch?.since ?? null,
+			last: entry.poller.last
+		};
+		const elapsed = clock.now() - startedAt;
+		return {
+			started,
+			draining,
+			ready,
+			alive,
+			controllers,
+			dependencies: dependenciesOut,
+			checks,
+			startup: {
+				budget,
+				elapsed,
+				overBudget: !started && elapsed > budget
+			}
+		};
+	};
+	const answer = (kind, pass, controller) => ({
+		status: pass || kind === "report" ? 200 : 503,
+		contentType: "application/health+json",
+		body: {
+			status: pass ? "pass" : "fail",
+			service: description.name,
+			probe: kind,
+			...controller === void 0 ? {} : { controller },
+			...kind === "report" ? { verdict: verdict() } : {}
+		}
+	});
 	return {
-		min: out(duration),
-		max: out(rationals.add(duration, interval))
+		verdict,
+		probe(kind, controller) {
+			const now = verdict();
+			if (kind === "startup") return answer(kind, now.started);
+			if (kind === "liveness") return answer(kind, now.alive);
+			if (kind === "report") return answer(kind, now.ready && now.alive);
+			if (controller === void 0) return answer(kind, now.ready);
+			const known = now.controllers[controller];
+			if (known === void 0) throw new Error(`${description.name} has no controller ${controller}`);
+			return answer(kind, known, controller);
+		},
+		subscribe(listener) {
+			listeners.add(listener);
+			return () => listeners.delete(listener);
+		},
+		forceFail(name, on) {
+			if (on) forced.add(name);
+			else forced.delete(name);
+		},
+		drain() {
+			if (draining) return;
+			draining = true;
+			changed();
+		},
+		stop() {
+			stopped = true;
+			budgetTimer?.();
+			budgetTimer = null;
+			for (const entry of entries.values()) {
+				entry.poller.stop();
+				entry.latch?.stop();
+			}
+		},
+		beginStartup() {
+			if (gate === "closed") moveGate("starting", "startup.begin");
+		},
+		failStartup(cause) {
+			if (gate === "open" || gate === "failed") return;
+			moveGate("failed", "startup.fail", cause);
+			budgetTimer?.();
+			budgetTimer = null;
+		},
+		async warmUp() {
+			if (started || stopped || gate === "failed" || gate === "sweeping") return;
+			moveGate("sweeping", "mark-ready");
+			const sweep = clock.now();
+			await Promise.all([...entries.values()].map((entry) => entry.poller.pollNow()));
+			if (stopped || gate !== "sweeping") return;
+			for (const entry of entries.values()) entry.poller.start(entry.poller.jittered() - (clock.now() - sweep));
+			started = true;
+			budgetTimer?.();
+			budgetTimer = null;
+			moveGate("open", "sweep.done");
+			changed();
+		},
+		addCheck(check, run) {
+			if (entries.has(check.name)) throw new Error(`${description.name} already has a check named ${check.name}`);
+			add(check, run, true);
+			changed();
+		},
+		addDependency(name) {
+			if (dependencies.has(name)) return;
+			dependencies.add(name);
+			lateDependencies.add(name);
+			changed();
+		}
 	};
 };
-/** This function gives the window that a debounce approximates: N polls of an interval fail after N intervals. */
-const asWindow = (timing) => timing.type === "window" ? timing : {
-	type: "window",
-	failAfter: out(rationals.mul(count(timing.failAfter, "failAfter"), seconds(timing.interval))),
-	recoverAfter: out(rationals.mul(count(timing.recoverAfter, "recoverAfter"), seconds(timing.interval)))
+//#endregion
+//#region src/process.ts
+/** These are the signals that the runtime handles. */
+const EXIT_SIGNALS = [
+	"SIGINT",
+	"SIGTERM",
+	"SIGQUIT"
+];
+/** This port is the process of Node. */
+const nodeProcess = {
+	on(signal, handler) {
+		const host = globalThis.process;
+		if (host === void 0) throw new Error("no process: give the runtime a process port");
+		host.on(signal, handler);
+		return () => {
+			host.off(signal, handler);
+		};
+	},
+	exit(code) {
+		const host = globalThis.process;
+		if (host === void 0) throw new Error("no process: give the runtime a process port");
+		host.exit(code);
+	}
 };
-/** This function gives the debounce that approximates a window on a poll: the polls that fit, rounded up. */
-const asDebounce = (timing, poll) => {
-	if (timing.type === "debounce") return timing;
-	const interval = seconds(poll.interval);
-	const polls = (duration) => duration === void 0 ? 1 : Math.max(1, Number(rationals.ceil(rationals.div(duration, interval)).n));
+//#endregion
+//#region src/requests.ts
+/**
+* This function makes a tracker. `refuses` gives the reason that the service refuses a new request
+* for a controller at this time, or null when it admits it.
+*/
+const tracker = (controllers, clock, refuses) => {
+	const byName = new Map(controllers.map((controller) => [controller.name, controller]));
+	const flights = /* @__PURE__ */ new Set();
+	const idle = /* @__PURE__ */ new Set();
+	let intake = true;
+	const settle = (flight) => {
+		flights.delete(flight);
+		if (flights.size === 0) for (const done of [...idle]) done();
+	};
+	/** This function answers a request that the shutdown stopped, by the idempotency of its route. */
+	const cut = (flight, cause) => {
+		const operation = byName.get(flight.controller).routes[flight.route];
+		const since = quantity(Math.max(0, clock.now() - flight.started) / 1e3, "s");
+		const retryable = mayReissue(operation, since);
+		return {
+			kind: "cut",
+			status: retryable ? 503 : 500,
+			retryable,
+			cause
+		};
+	};
 	return {
-		type: "debounce",
-		interval: poll.interval,
-		failAfter: polls(seconds(timing.failAfter)),
-		recoverAfter: polls(timing.recoverAfter === void 0 ? void 0 : seconds(timing.recoverAfter))
+		request(controller, route, work) {
+			const held = byName.get(controller);
+			if (held === void 0) throw new Error(`there is no controller ${controller}`);
+			if (held.routes[route] === void 0) throw new Error(`controller ${controller} does not declare the route ${route}`);
+			const refusal = intake ? refuses(controller) : "the service stopped its intake";
+			if (refusal !== null) return Promise.resolve({
+				kind: "refused",
+				status: 503,
+				retryable: true,
+				cause: refusal
+			});
+			return new Promise((resolve) => {
+				let answered = false;
+				const flight = {
+					controller,
+					route,
+					started: clock.now(),
+					abort: new AbortController(),
+					answer: (outcome) => {
+						if (answered) return;
+						answered = true;
+						settle(flight);
+						resolve(outcome);
+					}
+				};
+				flights.add(flight);
+				let promise;
+				try {
+					promise = Promise.resolve(work(flight.abort.signal));
+				} catch (error) {
+					promise = Promise.reject(error);
+				}
+				promise.then((value) => {
+					if (answered) return;
+					answered = true;
+					settle(flight);
+					resolve({
+						kind: "done",
+						value
+					});
+				}, (error) => {
+					if (answered) return;
+					const outcome = flight.abort.signal.aborted ? cut(flight, "the shutdown aborted it, and it failed") : {
+						kind: "failed",
+						error
+					};
+					answered = true;
+					settle(flight);
+					resolve(outcome);
+				});
+			});
+		},
+		inFlight(controller) {
+			let count = 0;
+			for (const flight of flights) if (controller === void 0 || flight.controller === controller) count += 1;
+			return count;
+		},
+		stopIntake() {
+			intake = false;
+		},
+		cooperativeAbort() {
+			for (const flight of flights) flight.abort.abort(/* @__PURE__ */ new Error("the cooperative abort of the drain"));
+		},
+		drain(deadline) {
+			if (flights.size === 0) return Promise.resolve();
+			return new Promise((resolve) => {
+				let finished = false;
+				const done = () => {
+					if (finished) return;
+					finished = true;
+					idle.delete(done);
+					cancel();
+					resolve();
+				};
+				idle.add(done);
+				const cancel = clock.after(Math.max(0, deadline - clock.now()), () => {
+					for (const flight of [...flights]) {
+						flight.abort.abort(/* @__PURE__ */ new Error("the drain reached its deadline"));
+						flight.answer(cut(flight, "the drain reached its deadline"));
+					}
+					done();
+				});
+			});
+		}
 	};
 };
 //#endregion
-//#region src/description.ts
+//#region src/lifecycle.ts
 /**
-* This is the format of a service as data: what `describe()` exports, and nothing starts. The
-* timer algebra and the ordering law read it. Each timer has a unit. Each knob comes from the
-* declaration, because the runtime has no defaults. A bound that nobody gives is "no bound", not
-* zero.
+* These are the stages of the shutdown, in their sequence. A declared phase with one of these
+* names gets the work of the runtime for its stage. A phase with another name gets only the work of
+* its owners.
+* - `fail readiness`: readiness fails at the start of the shutdown. This phase then holds for its
+*   cap, while the endpoints of the platform remove the service.
+* - `stop intake`: each transport stops its intake, and new requests get a retryable 503.
+* - `drain`: the transports and the requests in flight end, until the cap. The cooperative abort
+*   comes before the end of the cap, by the cooperative window.
+* - `close transports`: each transport closes.
+* - `stop the poller`: each check and watchdog stops. Then the signal of the service aborts.
+* - `tear down dependencies`: each dependency closes, in the reverse sequence of its connection.
+* - `close the health server`: the probes stop last.
 */
-const FORMAT = "mark1russell7.service/1";
-//#endregion
-//#region src/operation.ts
+const STAGES = [
+	"fail readiness",
+	"stop intake",
+	"drain",
+	"close transports",
+	"stop the poller",
+	"tear down dependencies",
+	"close the health server"
+];
+/** This function gives the place of a stage in the sequence, or -1 for a phase of another name. */
+const stageRank = (name) => STAGES.indexOf(name);
+/** The signal of the service aborts after the poller stops, and before the dependencies close. */
+const ABORT_AFTER = stageRank("stop the poller");
 /**
-* This function tells if an operation can go again `since` its first issue. An idempotent
-* operation can always go again, and other operations cannot. A keyed operation can go again
-* while the server keeps its key.
+* This function gives the time of the cooperative abort, in milliseconds after the drain starts. It
+* is the cap less the cooperative window, and not less than half the cap. A window without a bound
+* gives half the cap.
 */
-const mayReissue = (operation, since) => {
-	const { idempotent } = operation;
-	if (typeof idempotent === "boolean") return idempotent;
-	return compare(since, idempotent.window) < 0;
+const cooperativeAbortAt = (cap, window) => {
+	const before = window.value === "infinite" ? Number.POSITIVE_INFINITY : valueIn(window, "ms");
+	return Math.max(cap - before, cap / 2);
 };
-/** This function gives the problems in the declaration of an operation that `describe()` refuses. */
-const operationProblems = (owner, name, operation) => {
-	const { idempotent } = operation;
-	if (typeof idempotent === "boolean") return [];
+const message = (error) => error instanceof Error ? error.message : String(error);
+/**
+* This function gives the problems of a declaration that the lifecycle cannot start: a stage with
+* work and no declared phase. The runtime has no defaults, thus a transport without a drain phase
+* has no time to drain.
+*/
+const lifecycleProblems = (description, components) => {
+	const declared = new Set(description.shutdown.phases.map((phase) => phase.name));
+	const needs = (stage, why) => declared.has(stage) ? [] : [`${description.name} has ${why}, thus it declares the phase "${stage}"`];
 	const problems = [];
-	if (idempotent.key.trim().length === 0) problems.push(`${owner}'s ${name} names no key`);
-	if (!convertible(idempotent.window.unit, "s")) problems.push(`${owner}'s ${name} holds its key for a span that is not a time`);
+	for (const transport of description.transports) if (!components.transports.has(transport.name)) problems.push(`transport ${transport.name} has no implementation: the runtime has no defaults`);
+	if (components.transports.size > 0 || description.controllers.length > 0) {
+		problems.push(...needs("stop intake", "transports or controllers"));
+		problems.push(...needs("drain", "transports or controllers"));
+	}
+	if (components.transports.size > 0) problems.push(...needs("close transports", "transports"));
+	if (description.checks.length > 0) problems.push(...needs("stop the poller", "checks"));
+	if (components.dependencies.size > 0) problems.push(...needs("tear down dependencies", "dependency handles"));
+	if (components.healthServer !== null) problems.push(...needs("close the health server", "a health server"));
 	return problems;
 };
+/**
+* This function starts the lifecycle of a service. The startup has a sequence: the health server
+* first, then each dependency, then each transport, and the startup gate last. A signal during the
+* startup gets its shutdown after the startup ends. The shutdown does the declared phases in their
+* sequence, each one capped. Only the lifecycle ends the process: 0 after a clean shutdown, and 1
+* after an error.
+*/
+const lifecycle = (description, runtime, components, options = {}) => {
+	const clock = options.clock ?? realClock;
+	const port = options.process ?? nodeProcess;
+	const record = (machine, from, to, on, detail) => options.record?.({
+		at: clock.now(),
+		machine,
+		instance: description.name,
+		from,
+		to,
+		on,
+		...detail === void 0 ? {} : { detail }
+	});
+	const service = new AbortController();
+	const errors = [];
+	let state = "starting";
+	let exitCode = null;
+	let intakeStopped = false;
+	let shutdownStarted = false;
+	let failedStartup = false;
+	let exitState = "running";
+	const moveExit = (to, on, detail) => {
+		record("exit", exitState, to, on, detail);
+		exitState = to;
+	};
+	const fail = (cause) => {
+		errors.push(cause);
+		record("exit", exitState, exitState, "error", cause);
+	};
+	const requests = tracker(description.controllers, clock, (controller) => {
+		if (state === "starting") return "the service has not started";
+		if (state === "exited") return "the service has exited";
+		if (state === "draining") return null;
+		return runtime.verdict().controllers[controller] === true ? null : `controller ${controller} is not ready`;
+	});
+	let finish = () => {};
+	const done = new Promise((resolve) => {
+		finish = resolve;
+	});
+	let healthListening = false;
+	const connected = [];
+	const startedTransports = [];
+	const offs = EXIT_SIGNALS.map((signal) => port.on(signal, () => {
+		shutdown(signal);
+	}));
+	const startup = (async () => {
+		runtime.beginStartup();
+		const started = (what) => record("gate", "starting", "starting", "component.started", what);
+		try {
+			if (components.healthServer !== null) {
+				await components.healthServer.listen(runtime);
+				healthListening = true;
+				started("the health server");
+			}
+			for (const dependency of description.dependencies) {
+				const handle = components.dependencies.get(dependency.name);
+				if (handle === void 0) continue;
+				await handle.connect(service.signal);
+				connected.push([dependency.name, handle]);
+				started(`dependency ${dependency.name}`);
+			}
+			for (const transport of description.transports) {
+				const impl = components.transports.get(transport.name);
+				await impl.start(service.signal);
+				startedTransports.push([transport.name, impl]);
+				started(`${transport.kind} ${transport.name}`);
+			}
+			await runtime.warmUp();
+			if (state === "starting") state = "running";
+		} catch (error) {
+			const cause = `the startup failed: ${message(error)}`;
+			failedStartup = true;
+			runtime.failStartup(cause);
+			fail(cause);
+			if (exitState === "running") moveExit("stopping", "startup.fail", cause);
+			else record("exit", exitState, exitState, "startup.fail", cause);
+		}
+	})();
+	startup.then(() => {
+		if (failedStartup && !shutdownStarted) shutdown("the startup failed");
+	});
+	/** 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) => {
+		const cap = valueIn(phase.cap, "ms");
+		const deadline = clock.now() + cap;
+		const capped = new AbortController();
+		const context = {
+			deadline,
+			signal: capped.signal,
+			clock
+		};
+		let pending = work.length;
+		const all = Promise.all(work.map(async (each) => {
+			try {
+				await each(context);
+			} catch (error) {
+				fail(`the phase ${phase.name} failed: ${message(error)}`);
+			} finally {
+				pending -= 1;
+			}
+		}));
+		let cancelCap = () => {};
+		const end = new Promise((resolve) => {
+			cancelCap = clock.after(cap, () => resolve("cap"));
+		});
+		if (await Promise.race([all.then(() => "work"), end]) === "work" && hold) await end;
+		cancelCap();
+		capped.abort(/* @__PURE__ */ new Error(`the phase ${phase.name} reached its cap`));
+		return pending === 0;
+	};
+	async function shutdown(cause = "the service asked for it") {
+		if (shutdownStarted || exitState === "exited") {
+			if (exitState === "stopping") record("exit", exitState, exitState, "exit.repeat", cause);
+			return done;
+		}
+		shutdownStarted = true;
+		if (exitState === "running") moveExit("stopping", "exit.request", cause);
+		await startup;
+		state = "draining";
+		runtime.drain();
+		let drainState = "running";
+		const moveDrain = (to, on, detail) => {
+			record("drain", drainState, to, on, detail);
+			drainState = to;
+		};
+		const abortService = () => {
+			if (service.signal.aborted) return;
+			service.abort(/* @__PURE__ */ new Error("the service stopped"));
+			record("drain", drainState, drainState, "signal.abort");
+		};
+		const phases = description.shutdown.phases;
+		let on = "exit.request";
+		for (const phase of phases) {
+			const rank = stageRank(phase.name);
+			moveDrain(phase.name, on);
+			if (rank > ABORT_AFTER) abortService();
+			const work = [];
+			if (phase.name === "stop intake") {
+				work.push(() => {
+					intakeStopped = true;
+					requests.stopIntake();
+				});
+				for (const [, impl] of startedTransports) work.push(() => impl.stopIntake());
+			}
+			let cancelAbort = () => {};
+			if (phase.name === "drain") {
+				const cap = valueIn(phase.cap, "ms");
+				const cooperative = new AbortController();
+				const fireAt = cooperativeAbortAt(cap, description.shutdown.cooperativeWindow);
+				cancelAbort = clock.after(fireAt, () => {
+					cooperative.abort(/* @__PURE__ */ new Error("the cooperative abort of the drain"));
+					requests.cooperativeAbort();
+					record("drain", drainState, drainState, "drain.cooperative-abort");
+				});
+				work.push(({ deadline }) => requests.drain(deadline));
+				for (const [, impl] of startedTransports) work.push(({ deadline }) => impl.drain(deadline, cooperative.signal));
+			}
+			if (phase.name === "close transports") for (const [, impl] of startedTransports) work.push(() => impl.close());
+			if (phase.name === "stop the poller") work.push(() => {
+				runtime.stop();
+				components.stopPollers();
+			});
+			if (phase.name === "tear down dependencies") work.push(async () => {
+				for (const [, handle] of [...connected].reverse()) await handle.close();
+			});
+			if (phase.name === "close the health server" && healthListening && components.healthServer !== null) {
+				const server = components.healthServer;
+				work.push(() => server.close());
+			}
+			for (const owned of components.phaseWork.get(phase.name) ?? []) work.push(owned);
+			const inTime = await runPhase(phase, phase.name === "fail readiness", work);
+			cancelAbort();
+			if (!inTime) fail(`the phase ${phase.name} did not end in its cap of ${valueIn(phase.cap, "s")} s`);
+			on = inTime ? "phase.done" : "phase.cap";
+		}
+		moveDrain("done", on);
+		abortService();
+		runtime.stop();
+		components.stopPollers();
+		if (!intakeStopped) requests.stopIntake();
+		for (const off of offs) off();
+		state = "exited";
+		exitCode = errors.length > 0 ? 1 : 0;
+		moveExit("exited", "shutdown.done", `exit ${exitCode}`);
+		finish(exitCode);
+		port.exit(exitCode);
+		return exitCode;
+	}
+	return {
+		health: runtime,
+		get state() {
+			return state;
+		},
+		get exitCode() {
+			return exitCode;
+		},
+		get errors() {
+			return [...errors];
+		},
+		started: startup,
+		done,
+		signal: service.signal,
+		shutdown,
+		request: (controller, route, work) => requests.request(controller, route, work),
+		inFlight: (controller) => requests.inFlight(controller),
+		keepAlive: () => state === "running" && runtime.verdict().ready
+	};
+};
+//#endregion
+//#region src/watchdog.ts
+/** This function starts a watchdog on a clock. */
+const watchdog = (clock, spec, trace) => {
+	const tick = valueIn(spec.tick, "ms");
+	const threshold = valueIn(spec.threshold, "ms");
+	if (!(tick > 0)) throw new RangeError(`watchdog ${spec.name} ticks every ${tick} ms, not above zero`);
+	let blocked = false;
+	let stopped = false;
+	let worst = 0;
+	let sincePoll = 0;
+	let next = null;
+	const named = () => stopped ? "stopped" : blocked ? "blocked" : "watching";
+	const arm = () => {
+		const due = clock.now() + tick;
+		next = clock.after(tick, () => {
+			next = null;
+			if (stopped) return;
+			const late = Math.max(0, clock.now() - due);
+			worst = Math.max(worst, late);
+			sincePoll = Math.max(sincePoll, late);
+			const from = named();
+			blocked = late > threshold;
+			trace?.(from, named(), "tick");
+			arm();
+		});
+	};
+	arm();
+	return {
+		check: () => {
+			const failed = blocked || sincePoll > threshold;
+			sincePoll = 0;
+			return failed ? "error" : "ok";
+		},
+		get worst() {
+			return worst;
+		},
+		get blocked() {
+			return blocked;
+		},
+		stop() {
+			if (stopped) return;
+			const from = named();
+			stopped = true;
+			next?.();
+			next = null;
+			trace?.(from, "stopped", "stop");
+		}
+	};
+};
 //#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 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) => {
+	if (timing.type === "debounce") {
+		const problems = [];
+		if (!above(timing.interval)) problems.push(`the ${policy} debounce polls at an interval that is not above zero`);
+		if (!whole(timing.failAfter)) problems.push(`the ${policy} debounce fails after ${timing.failAfter} polls, not a whole number above zero`);
+		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);
+	return negative(timing.failAfter) || negative(timing.recoverAfter) ? [`the ${policy} window is not a time of zero or more`] : [];
+};
 /** This function starts the composition of a service. */
 const service = (name) => {
 	if (name.trim().length === 0) throw new Error("a service needs a name");
@@ -111,6 +971,7 @@ const service = (name) => {
 	const dependencies = [];
 	const controllers = [];
 	const checks = [];
+	const runs = /* @__PURE__ */ new Map();
 	const couplings = [];
 	const phases = [];
 	let readiness;
@@ -119,6 +980,14 @@ const service = (name) => {
 	let cooperative;
 	let started = false;
 	let partial = false;
+	let runtime;
+	let live;
+	let running;
+	const transportImpls = /* @__PURE__ */ new Map();
+	const handles = /* @__PURE__ */ new Map();
+	const phaseWork = /* @__PURE__ */ new Map();
+	const watchdogs = [];
+	let probes = null;
 	/** This function stops a change to the shape of the service after the start. */
 	const composing = (what) => {
 		if (started) throw new Error(`${name} has started: ${what} is declared before svc.start()`);
@@ -126,7 +995,7 @@ const service = (name) => {
 	const once = (list, entry, what) => {
 		if (list.some((held) => held.name === entry)) throw new Error(`${name} already has a ${what} named ${entry}`);
 	};
-	const transport = (kind) => (entry, knobs) => {
+	const transport = (kind) => (entry, knobs, impl) => {
 		composing(`a ${kind}`);
 		once(transports, entry, "transport");
 		transports.push({
@@ -134,19 +1003,67 @@ const service = (name) => {
 			kind,
 			knobs: { ...knobs }
 		});
+		if (impl !== void 0) transportImpls.set(entry, impl);
 		return builder;
 	};
+	/** This function makes the runtime of the declaration: its checks, and a watchdog for each spec. */
+	const makeRuntime = (options) => {
+		const description = builder.describe();
+		const clock = options.clock ?? realClock;
+		const dogs = [];
+		const all = new Map(runs);
+		for (const spec of watchdogs) {
+			const dog = watchdog(clock, spec, (from, to, on) => options.record?.({
+				at: clock.now(),
+				machine: "watchdog",
+				instance: spec.name,
+				from,
+				to,
+				on
+			}));
+			dogs.push(dog);
+			all.set(spec.name, () => dog.check());
+		}
+		const stopPollers = () => {
+			for (const dog of dogs) dog.stop();
+		};
+		let made;
+		try {
+			made = healthRuntime(description, all, options);
+		} catch (error) {
+			stopPollers();
+			throw error;
+		}
+		return {
+			runtime: {
+				...made,
+				stop: () => {
+					made.stop();
+					stopPollers();
+				}
+			},
+			description,
+			stopPollers
+		};
+	};
 	const builder = {
 		name,
-		dependency(entry, spec) {
+		get health() {
+			return live ?? null;
+		},
+		dependency(entry, spec, handle) {
 			once(dependencies, entry, "dependency");
+			if (handle !== void 0 && !started) handles.set(entry, handle);
 			dependencies.push({
 				name: entry,
 				...spec,
 				knobs: { ...spec.knobs },
 				operations: { ...spec.operations }
 			});
-			if (started) partial = true;
+			if (started) {
+				partial = true;
+				live?.addDependency(entry);
+			}
 			return builder;
 		},
 		server: transport("server"),
@@ -176,10 +1093,43 @@ const service = (name) => {
 			};
 			return handle;
 		},
-		check(check) {
+		check(check, run) {
 			once(checks, check.name, "check");
+			if (started && run === void 0) throw new Error(`check ${check.name} joins after the start, thus it needs its function`);
 			checks.push({ ...check });
-			if (started) partial = true;
+			if (run !== void 0) runs.set(check.name, run);
+			if (started) {
+				partial = true;
+				live?.addCheck({
+					...check,
+					poll: { ...check.poll }
+				}, run);
+			}
+			return builder;
+		},
+		healthServer(server) {
+			composing("the health server");
+			if (probes !== null) throw new Error(`${name} already has a health server`);
+			probes = server;
+			return builder;
+		},
+		onPhase(phase, work) {
+			composing(`work for the phase ${phase}`);
+			phaseWork.set(phase, [...phaseWork.get(phase) ?? [], work]);
+			return builder;
+		},
+		watchdog(spec) {
+			composing(`the watchdog ${spec.name}`);
+			once(checks, spec.name, "check");
+			checks.push({
+				name: spec.name,
+				dependency: null,
+				step: "local-state",
+				ownConnection: true,
+				gates: spec.gates,
+				poll: { ...spec.poll }
+			});
+			watchdogs.push(spec);
 			return builder;
 		},
 		readiness(timing) {
@@ -226,9 +1176,18 @@ const service = (name) => {
 			if (missing.length > 0) throw new Error(`${name} does not declare ${missing.join("; ")}: the runtime has no defaults`);
 			const known = new Set(dependencies.map((entry) => entry.name));
 			const problems = [];
+			const policies = {
+				readiness,
+				liveness
+			};
+			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`);
+				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`);
 			}
 			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`);
@@ -236,6 +1195,8 @@ const service = (name) => {
 			}
 			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`);
+			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("; ")}`);
 			const controllersOut = controllers.map((entry) => ({
 				name: entry.name,
@@ -272,10 +1233,47 @@ const service = (name) => {
 				}
 			};
 		},
-		start() {
-			builder.describe();
+		start(options = {}) {
+			if (runtime !== void 0) return runtime;
+			if (running !== void 0) return Promise.reject(/* @__PURE__ */ new Error(`${name} runs its lifecycle: use its health`));
+			let made;
+			try {
+				made = makeRuntime(options).runtime;
+			} catch (error) {
+				return Promise.reject(error);
+			}
 			started = true;
-			return Promise.resolve();
+			live = made;
+			runtime = made.warmUp().then(() => made);
+			return runtime;
+		},
+		run(options = {}) {
+			if (running !== void 0) return running;
+			if (runtime !== void 0) return Promise.reject(/* @__PURE__ */ new Error(`${name} started its health only: run() starts the whole lifecycle`));
+			let life;
+			try {
+				const description = builder.describe();
+				const components = {
+					transports: transportImpls,
+					dependencies: handles,
+					healthServer: probes,
+					phaseWork,
+					stopPollers: () => {}
+				};
+				const problems = lifecycleProblems(description, components);
+				if (problems.length > 0) throw new Error(`${name}: ${problems.join("; ")}`);
+				const made = makeRuntime(options);
+				started = true;
+				live = made.runtime;
+				life = lifecycle(made.description, made.runtime, {
+					...components,
+					stopPollers: made.stopPollers
+				}, options);
+			} catch (error) {
+				return Promise.reject(error);
+			}
+			running = life.started.then(() => life);
+			return running;
 		}
 	};
 	return builder;
@@ -448,6 +1446,456 @@ const lint = (svc, scenario, rules) => {
 	return findings;
 };
 //#endregion
-export { FORMAT, SERVICE_RULES, asDebounce, asWindow, evaluate, failSpan, inequalities, lint, mayReissue, recoverSpan, service, serviceBindings, symbolsOf, verdictOf };
+//#region src/machines.ts
+/**
+* The machines of the runtime as `mark1russell7.machine/1` documents. The documents are the
+* specification, and TypeScript implements them. A test records the transitions of the runtime
+* and replays them against each document, thus the code and the documents cannot disagree.
+*/
+const SOURCE = [{
+	ref: "packages/service/src (the runtime implements this document)",
+	rung: "implemented"
+}];
+const base = (id, title) => ({
+	format: "mark1russell7.machine/1",
+	id: `service.machine.${id}`,
+	title,
+	layer: "self",
+	version: "0.2.0",
+	sources: SOURCE
+});
+const t = (id, from, on, to, extra = {}) => ({
+	id,
+	from,
+	on,
+	to,
+	...extra
+});
+/**
+* The startup gate opens one time. The lifecycle moves it from `closed` to `starting` while its
+* components start. Then one warm-up sweep of each check opens it. A component that does not start
+* fails it for good.
+*/
+const GATE_MACHINE = {
+	...base("gate", "The startup gate"),
+	states: {
+		closed: { initial: true },
+		starting: { note: "the health server, then the dependencies, then the transports" },
+		sweeping: { note: "one bounded warm-up sweep of each check" },
+		open: { final: true },
+		failed: { final: true }
+	},
+	events: {
+		"startup.begin": { kind: "local" },
+		"component.started": { kind: "local" },
+		"mark-ready": { kind: "local" },
+		"sweep.done": { kind: "local" },
+		"startup.fail": { kind: "local" },
+		"startup.over-budget": { kind: "timer" }
+	},
+	knobs: { startup: {
+		key: "policies.startup",
+		scope: "service",
+		unit: "s",
+		default: null
+	} },
+	timers: { startup_budget: {
+		duration: {
+			knob: "startup",
+			unit: "s"
+		},
+		arms: ["enter:closed"],
+		cancels: ["sweep.done", "startup.fail"],
+		fires: "startup.over-budget",
+		note: "the gate says that it is over its budget, and the startup probe of the platform acts on it"
+	} },
+	transitions: [
+		t("begin", "closed", "startup.begin", "starting"),
+		t("component", "starting", "component.started", "starting"),
+		t("mark-ready", ["closed", "starting"], "mark-ready", "sweeping"),
+		t("open", "sweeping", "sweep.done", "open"),
+		t("fail", [
+			"closed",
+			"starting",
+			"sweeping"
+		], "startup.fail", "failed"),
+		t("over-budget-closed", "closed", "startup.over-budget", "closed", { timer: "startup_budget" }),
+		t("over-budget-starting", "starting", "startup.over-budget", "starting", { timer: "startup_budget" }),
+		t("over-budget-sweeping", "sweeping", "startup.over-budget", "sweeping", { timer: "startup_budget" })
+	]
+};
+/** A debounce latch counts the polls of its check in sequence. A readiness latch starts tripped. */
+const LATCH_MACHINE = {
+	...base("latch", "The latch of a policy, as a debounce"),
+	states: {
+		tripped: {
+			initial: true,
+			note: "a readiness latch starts here; a liveness latch starts released"
+		},
+		released: {}
+	},
+	events: {
+		"poll.ok": { kind: "local" },
+		"poll.fail": { kind: "local" }
+	},
+	knobs: {
+		fail_after: {
+			key: "policies.<gate>.failAfter",
+			scope: "check",
+			unit: "count",
+			default: null
+		},
+		recover_after: {
+			key: "policies.<gate>.recoverAfter",
+			scope: "check",
+			unit: "count",
+			default: null
+		}
+	},
+	timers: {},
+	transitions: [
+		t("pass", "released", "poll.ok", "released"),
+		t("fail-count", "released", "poll.fail", "released", { guard: "failures in sequence < fail_after" }),
+		t("trip", "released", "poll.fail", "tripped", { guard: "failures in sequence >= fail_after" }),
+		t("fail", "tripped", "poll.fail", "tripped"),
+		t("pass-count", "tripped", "poll.ok", "tripped", { guard: "passes in sequence < recover_after" }),
+		t("release", "tripped", "poll.ok", "released", { guard: "passes in sequence >= recover_after" })
+	]
+};
+/**
+* A window latch measures time on the monotonic clock from the first failure of a sequence, and
+* from the first pass after a trip.
+*/
+const WINDOW_MACHINE = {
+	...base("window", "The latch of a policy, as a window"),
+	states: {
+		released: {
+			initial: true,
+			note: "a liveness latch starts here; a readiness latch starts tripped"
+		},
+		failing: { note: "the fail window runs" },
+		tripped: {},
+		recovering: { note: "the recover window runs" }
+	},
+	events: {
+		"poll.ok": { kind: "local" },
+		"poll.fail": { kind: "local" },
+		"window.failed": { kind: "timer" },
+		"window.recovered": { kind: "timer" }
+	},
+	knobs: {
+		fail_after: {
+			key: "policies.<gate>.failAfter",
+			scope: "check",
+			unit: "s",
+			default: null
+		},
+		recover_after: {
+			key: "policies.<gate>.recoverAfter",
+			scope: "check",
+			unit: "s",
+			default: null
+		}
+	},
+	timers: {
+		fail_window: {
+			duration: {
+				knob: "fail_after",
+				unit: "s"
+			},
+			arms: ["enter:failing"],
+			cancels: ["poll.ok"],
+			fires: "window.failed"
+		},
+		recover_window: {
+			duration: {
+				knob: "recover_after",
+				unit: "s"
+			},
+			arms: ["enter:recovering"],
+			cancels: ["poll.fail"],
+			fires: "window.recovered"
+		}
+	},
+	transitions: [
+		t("pass", "released", "poll.ok", "released"),
+		t("start-failing", "released", "poll.fail", "failing", { guard: "fail_after > 0" }),
+		t("trip-at-once", "released", "poll.fail", "tripped", { guard: "fail_after = 0" }),
+		t("still-failing", "failing", "poll.fail", "failing"),
+		t("stop-failing", "failing", "poll.ok", "released"),
+		t("trip", "failing", "window.failed", "tripped", { timer: "fail_window" }),
+		t("fail", "tripped", "poll.fail", "tripped"),
+		t("release-at-once", "tripped", "poll.ok", "released", { guard: "recover_after is absent or 0" }),
+		t("start-recovering", "tripped", "poll.ok", "recovering", { guard: "recover_after > 0" }),
+		t("still-recovering", "recovering", "poll.ok", "recovering"),
+		t("stop-recovering", "recovering", "poll.fail", "tripped"),
+		t("release", "recovering", "window.recovered", "released", { timer: "recover_window" })
+	]
+};
+/**
+* A poller starts one check on a jittered loop with a fixed delay. A call that outlives its timeout
+* stays pending (`hung`), and the poller does not start the check again until the call settles.
+*/
+const POLLER_MACHINE = {
+	...base("poller", "The poller of a check"),
+	states: {
+		idle: {
+			initial: true,
+			note: "before the loop starts"
+		},
+		waiting: { note: "the loop timer runs, and no call is pending" },
+		calling: { note: "a call runs, in its timeout" },
+		hung: { note: "a call outlived its timeout, and it is still pending" },
+		stopped: { final: true }
+	},
+	events: {
+		start: { kind: "local" },
+		sweep: { kind: "local" },
+		tick: { kind: "timer" },
+		answer: { kind: "local" },
+		timeout: { kind: "timer" },
+		"late-answer": { kind: "local" },
+		stop: { kind: "local" }
+	},
+	knobs: {
+		interval: {
+			key: "checks.<name>.poll.interval",
+			scope: "check",
+			unit: "s",
+			default: null
+		},
+		timeout: {
+			key: "checks.<name>.poll.timeout",
+			scope: "check",
+			unit: "s",
+			default: null
+		}
+	},
+	timers: {
+		loop: {
+			duration: {
+				knob: "interval",
+				unit: "s"
+			},
+			arms: ["start", "tick"],
+			cancels: ["stop"],
+			fires: "tick",
+			note: "the interval, with its jitter: a fixed delay from the start of each poll"
+		},
+		poll_timeout: {
+			duration: {
+				knob: "timeout",
+				unit: "s"
+			},
+			arms: ["enter:calling"],
+			cancels: ["answer", "stop"],
+			fires: "timeout"
+		}
+	},
+	transitions: [
+		t("sweep", "idle", "sweep", "calling"),
+		t("start", "idle", "start", "waiting"),
+		t("start-while-calling", "calling", "start", "calling", { note: "a late check polls at once, then starts its loop" }),
+		t("start-while-hung", "hung", "start", "hung"),
+		t("tick", "waiting", "tick", "calling", { guard: "the force-fail list does not name the check" }),
+		t("tick-forced", "waiting", "tick", "waiting", { guard: "the force-fail list names the check" }),
+		t("tick-pending", "calling", "tick", "calling", { note: "the poll fails at once: its call is pending" }),
+		t("tick-hung", "hung", "tick", "hung", { note: "the poll fails at once: its call is pending" }),
+		t("answer-loop", "calling", "answer", "waiting", { guard: "the loop runs" }),
+		t("answer-sweep", "calling", "answer", "idle", { guard: "the loop has not started" }),
+		t("timeout", "calling", "timeout", "hung", { timer: "poll_timeout" }),
+		t("late-answer-loop", "hung", "late-answer", "waiting", { guard: "the loop runs" }),
+		t("late-answer-sweep", "hung", "late-answer", "idle", { guard: "the loop has not started" }),
+		t("stop", [
+			"idle",
+			"waiting",
+			"calling",
+			"hung"
+		], "stop", "stopped"),
+		t("settle-after-stop", "stopped", [
+			"answer",
+			"late-answer",
+			"timeout"
+		], "stopped")
+	]
+};
+/**
+* The exit manager is the only part that ends the process. The first exit request starts the
+* shutdown, and a later one has no effect. An error makes the exit code 1.
+*/
+const EXIT_MACHINE = {
+	...base("exit", "The exit manager"),
+	states: {
+		running: { initial: true },
+		stopping: {},
+		exited: { final: true }
+	},
+	events: {
+		"exit.request": {
+			kind: "app",
+			note: "SIGINT, SIGTERM, SIGQUIT or shutdown()"
+		},
+		"exit.repeat": { kind: "app" },
+		"startup.fail": { kind: "local" },
+		error: { kind: "local" },
+		"shutdown.done": { kind: "local" }
+	},
+	knobs: {},
+	timers: {},
+	transitions: [
+		t("request", "running", "exit.request", "stopping"),
+		t("startup-fail", "running", "startup.fail", "stopping"),
+		t("error-running", "running", "error", "running"),
+		t("repeat", "stopping", "exit.repeat", "stopping"),
+		t("startup-fail-stopping", "stopping", "startup.fail", "stopping"),
+		t("error", "stopping", "error", "stopping"),
+		t("exit", "stopping", "shutdown.done", "exited", { note: "the exit code is 1 after an error, else 0" })
+	]
+};
+/** A watchdog measures how late its own tick comes, and a late tick shows a blocked event loop. */
+const WATCHDOG_MACHINE = {
+	...base("watchdog", "The watchdog of the event loop"),
+	states: {
+		watching: { initial: true },
+		blocked: {},
+		stopped: { final: true }
+	},
+	events: {
+		tick: { kind: "timer" },
+		stop: { kind: "local" }
+	},
+	knobs: {
+		tick: {
+			key: "watchdog.tick",
+			scope: "process",
+			unit: "s",
+			default: null
+		},
+		threshold: {
+			key: "watchdog.threshold",
+			scope: "process",
+			unit: "s",
+			default: null
+		}
+	},
+	timers: { tick: {
+		duration: {
+			knob: "tick",
+			unit: "s"
+		},
+		arms: ["enter:watching", "tick"],
+		cancels: ["stop"],
+		fires: "tick"
+	} },
+	transitions: [
+		t("on-time", "watching", "tick", "watching", { guard: "lateness <= threshold" }),
+		t("block", "watching", "tick", "blocked", { guard: "lateness > threshold" }),
+		t("still-blocked", "blocked", "tick", "blocked", { guard: "lateness > threshold" }),
+		t("unblock", "blocked", "tick", "watching", { guard: "lateness <= threshold" }),
+		t("stop", ["watching", "blocked"], "stop", "stopped")
+	]
+};
+/** This function gives the name of a knob for the cap of a phase: `drain` gives `drain_cap`. */
+const capKnob = (phase) => `${phase.replace(/[^A-Za-z0-9]+/g, "_")}_cap`;
+/**
+* This function gives the drain of a declaration as a machine. It has one state for each declared
+* phase, in its sequence, and each state has a timer at its cap. The drain also has the cooperative abort: the
+* cap of the drain less the cooperative window, and half that cap at the least.
+*/
+const drainMachine = (description) => {
+	const phases = description.shutdown.phases;
+	const states = { running: { initial: true } };
+	for (const phase of phases) states[phase.name] = {};
+	states["done"] = { final: true };
+	const knobs = Object.fromEntries([...phases.map((phase) => [capKnob(phase.name), {
+		key: `shutdown.phases.${phase.name}.cap`,
+		scope: "service",
+		unit: "s",
+		default: null
+	}]), ["cooperative_window", {
+		key: "shutdown.cooperativeWindow",
+		scope: "service",
+		unit: "s",
+		default: null
+	}]]);
+	const timers = {};
+	for (const phase of phases) timers[`${capKnob(phase.name)}_timer`] = {
+		duration: {
+			knob: capKnob(phase.name),
+			unit: "s"
+		},
+		arms: [`enter:${phase.name}`],
+		cancels: ["phase.done"],
+		fires: "phase.cap"
+	};
+	if (phases.some((phase) => phase.name === "drain")) timers["cooperative_abort"] = {
+		duration: {
+			expr: "max(drain_cap - cooperative_window, drain_cap / 2)",
+			unit: "s"
+		},
+		arms: ["enter:drain"],
+		cancels: ["phase.done", "phase.cap"],
+		fires: "drain.cooperative-abort"
+	};
+	const transitions = [];
+	const order = [
+		"running",
+		...phases.map((phase) => phase.name),
+		"done"
+	];
+	for (let at = 0; at + 1 < order.length; at += 1) {
+		const from = order[at];
+		const to = order[at + 1];
+		transitions.push(at === 0 ? t(`begin`, from, "exit.request", to) : t(`after-${from}`, from, ["phase.done", "phase.cap"], to, {
+			timer: `${capKnob(from)}_timer`,
+			note: "phase.cap: the work of the phase did not end in its cap, and the exit code is 1"
+		}));
+	}
+	if (phases.some((phase) => phase.name === "drain")) transitions.push(t("cooperative-abort", "drain", "drain.cooperative-abort", "drain", { timer: "cooperative_abort" }));
+	for (const state of [...phases.map((phase) => phase.name), "done"]) transitions.push(t(`signal-abort-${state}`, state, "signal.abort", state));
+	return {
+		...base("drain", `The drain of ${description.name}`),
+		states,
+		events: {
+			"exit.request": { kind: "app" },
+			"phase.done": { kind: "local" },
+			"phase.cap": { kind: "timer" },
+			"drain.cooperative-abort": { kind: "timer" },
+			"signal.abort": { kind: "local" }
+		},
+		knobs,
+		timers,
+		transitions
+	};
+};
+/** These are the static machines of the runtime, by the name that their events carry. */
+const MACHINES = {
+	gate: GATE_MACHINE,
+	latch: LATCH_MACHINE,
+	window: WINDOW_MACHINE,
+	poller: POLLER_MACHINE,
+	exit: EXIT_MACHINE,
+	watchdog: WATCHDOG_MACHINE
+};
+/**
+* This function replays the transitions of one machine of the runtime against its document. Each
+* instance starts in the state that its first transition leaves. Each transition must leave the
+* state where the replay is. The document must have a transition from that state, on that event,
+* to that state. The function gives each disagreement.
+*/
+const replay = (doc, events) => {
+	const problems = [];
+	const at = /* @__PURE__ */ new Map();
+	for (const event of events) {
+		const where = at.get(event.instance) ?? event.from;
+		if (doc.states[where] === void 0) problems.push(`${event.instance}: the state ${where} is not in ${doc.id}`);
+		if (event.from !== where) problems.push(`${event.instance}: the runtime left ${event.from} on ${event.on}, but the replay is in ${where}`);
+		if (!doc.transitions.some((each) => fromStates(doc, each.from).includes(event.from) && arr(each.on).includes(event.on) && each.to === event.to)) problems.push(`${event.instance}: ${doc.id} has no transition from ${event.from} on ${event.on} to ${event.to}`);
+		at.set(event.instance, event.to);
+	}
+	return problems;
+};
+//#endregion
+export { EXIT_MACHINE, EXIT_SIGNALS, FORMAT, GATE_MACHINE, LATCH_MACHINE, MACHINES, POLLER_MACHINE, SERVICE_RULES, STAGES, WATCHDOG_MACHINE, WINDOW_MACHINE, asDebounce, asWindow, capKnob, cooperativeAbortAt, drainMachine, evaluate, failSpan, inequalities, lint, mayReissue, nodeProcess, realClock, recoverSpan, replay, service, serviceBindings, stageRank, symbolsOf, verdictOf, watchdog };
 
 //# sourceMappingURL=index.js.map