@mark1russell7/service 0.0.0-stage → 0.2.0

package/build/index.js

@@ -0,0 +1,1901 @@
+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();
+		}
+	};
+};
+//#endregion
+//#region src/poller.ts
+const message$1 = (error) => error instanceof Error ? error.message : String(error);
+/**
+* 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 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 {
+		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();
+		}
+	};
+};
+//#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 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 {
+		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();
+		}
+	};
+};
+//#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);
+	}
+};
+//#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 {
+		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/lifecycle.ts
+/**
+* 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 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 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 cooperativeAbortAt = (cap, window) => {
+	const before = window.value === "infinite" ? Number.POSITIVE_INFINITY : valueIn(window, "ms");
+	return Math.max(cap - before, cap / 2);
+};
+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 = [];
+	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");
+	const transports = [];
+	const dependencies = [];
+	const controllers = [];
+	const checks = [];
+	const runs = /* @__PURE__ */ new Map();
+	const couplings = [];
+	const phases = [];
+	let readiness;
+	let liveness;
+	let startup;
+	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()`);
+	};
+	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, impl) => {
+		composing(`a ${kind}`);
+		once(transports, entry, "transport");
+		transports.push({
+			name: entry,
+			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,
+		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;
+				live?.addDependency(entry);
+			}
+			return builder;
+		},
+		server: transport("server"),
+		consumer: transport("consumer"),
+		worker: transport("worker"),
+		controller(entry) {
+			composing("a controller");
+			once(controllers, entry, "controller");
+			const held = {
+				name: entry,
+				requires: [],
+				routes: {}
+			};
+			controllers.push(held);
+			const handle = {
+				requires(...needed) {
+					composing(`what ${entry} requires`);
+					held.requires.push(...needed);
+					return handle;
+				},
+				route(served, operation) {
+					composing(`${entry}'s routes`);
+					if (held.routes[served] !== void 0) throw new Error(`${entry} already serves ${served}`);
+					held.routes[served] = { ...operation };
+					return handle;
+				}
+			};
+			return handle;
+		},
+		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 (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) {
+			composing("readiness");
+			readiness = timing;
+			return builder;
+		},
+		liveness(timing) {
+			composing("liveness");
+			liveness = timing;
+			return builder;
+		},
+		startup(budget) {
+			composing("the startup budget");
+			startup = budget;
+			return builder;
+		},
+		couple(coupling) {
+			composing("a coupling");
+			couplings.push({ ...coupling });
+			return builder;
+		},
+		phase(entry, cap) {
+			composing("a shutdown phase");
+			once(phases, entry, "shutdown phase");
+			phases.push({
+				name: entry,
+				cap
+			});
+			return builder;
+		},
+		cooperativeWindow(window) {
+			composing("the cooperative window");
+			cooperative = window;
+			return builder;
+		},
+		describe() {
+			const missing = [];
+			if (readiness === void 0) missing.push("readiness (svc.readiness)");
+			if (liveness === void 0) missing.push("liveness (svc.liveness)");
+			if (startup === void 0) missing.push("a startup budget (svc.startup)");
+			if (phases.length === 0) missing.push("its shutdown phases (svc.phase)");
+			if (cooperative === void 0) missing.push("a cooperative window, or no bound (svc.cooperativeWindow)");
+			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`);
+				for (const [route, operation] of Object.entries(controller.routes)) problems.push(...operationProblems(`controller ${controller.name}`, route, operation));
+			}
+			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,
+				requires: [...entry.requires],
+				routes: { ...entry.routes }
+			}));
+			return {
+				format: FORMAT,
+				name,
+				partial,
+				transports: transports.map((entry) => ({
+					...entry,
+					knobs: { ...entry.knobs }
+				})),
+				dependencies: dependencies.map((entry) => ({
+					...entry,
+					knobs: { ...entry.knobs },
+					operations: { ...entry.operations }
+				})),
+				controllers: controllersOut,
+				checks: checks.map((entry) => ({
+					...entry,
+					poll: { ...entry.poll }
+				})),
+				policies: {
+					readiness,
+					liveness,
+					startup
+				},
+				couplings: couplings.map((entry) => ({ ...entry })),
+				shutdown: {
+					phases: phases.map((entry) => ({ ...entry })),
+					cooperativeWindow: cooperative
+				}
+			};
+		},
+		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;
+			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;
+};
+//#endregion
+//#region src/law.ts
+const value = (bound) => bound === "inf" || bound === "off" ? Infinity : Number(bound);
+const keyOf = (term) => term.at !== void 0 ? `${term.knob}@${term.at}` : term.knob;
+/** This function gives the bound of a symbol, or undefined when the symbol has no bound. */
+const boundOf$1 = (bind, key) => {
+	const bound = bind[key];
+	return typeof bound === "number" || bound === "inf" || bound === "off" ? bound : void 0;
+};
+/** This function gives the inequalities of a rule: its expr, then the others. */
+const inequalities = (rule) => [rule.expr, ...rule.expr_more ?? []];
+/** This function gives the symbols that a rule reads, as `symbol@hop`. */
+const symbolsOf = (rule) => {
+	const out = [];
+	for (const inequality of inequalities(rule)) for (const term of [...inequality.lhs.terms, ...inequality.rhs.terms]) {
+		const key = keyOf(term);
+		if (!out.includes(key)) out.push(key);
+	}
+	return out;
+};
+/** This function gives the value of a side, Σ coef × symbol + const, or null when a symbol has no bound. */
+const sideOf = (side, bind) => {
+	let total = side.const ?? 0;
+	for (const term of side.terms) {
+		const bound = boundOf$1(bind, keyOf(term));
+		if (bound === void 0) return null;
+		total += term.coef * value(bound);
+	}
+	return total;
+};
+/** This function gives the margin of an inequality: from the binding (one for all, or one each), else from the rule, else 0. */
+const marginOf = (inequality, index, bind) => {
+	if (Array.isArray(bind.margins)) return Number(bind.margins[index] ?? 0);
+	if (typeof bind.margin === "number") return bind.margin;
+	return typeof inequality.margin === "number" ? inequality.margin : 0;
+};
+/**
+* This function evaluates each inequality on one binding. "<" holds when lhs + margin < rhs, and
+* ">" holds when lhs > rhs + margin. Only the inequalities with all their symbols bound apply.
+* The others are null.
+*/
+const evaluate = (rule, bind) => inequalities(rule).map((inequality, index) => {
+	const lhs = sideOf(inequality.lhs, bind);
+	const rhs = sideOf(inequality.rhs, bind);
+	const margin = marginOf(inequality, index, bind);
+	if (lhs === null || rhs === null) return {
+		lhs,
+		rhs,
+		margin,
+		holds: null
+	};
+	return {
+		lhs,
+		rhs,
+		margin,
+		holds: inequality.op === "<" ? lhs + margin < rhs : inequality.op === "<=" ? lhs + margin <= rhs : inequality.op === ">" ? lhs > rhs + margin : lhs >= rhs + margin
+	};
+});
+/**
+* This function gives the verdict of an evaluation. When an applicable inequality fails, the
+* verdict is "violated". When all hold only because a timer is absent, the verdict is "unbounded",
+* because nothing then limits the window. Otherwise the verdict is "holds". When no inequality
+* applies, the arithmetic cannot decide, and the verdict is "depends".
+*/
+const verdictOf = (rule, bind, evaluated) => {
+	const applicable = evaluated.flatMap((entry, index) => entry.holds === null ? [] : [index]);
+	if (applicable.length === 0) return "depends";
+	if (applicable.some((index) => evaluated[index]?.holds === false)) return "violated";
+	const all = inequalities(rule);
+	return applicable.some((index) => {
+		const inequality = all[index];
+		return [...inequality.lhs.terms, ...inequality.rhs.terms].some((term) => {
+			const bound = boundOf$1(bind, keyOf(term));
+			return bound !== void 0 && value(bound) === Infinity;
+		});
+	}) ? "unbounded" : "holds";
+};
+//#endregion
+//#region src/lint.ts
+/** These are the identifiers of the rules that each declaration gets. */
+const SERVICE_RULES = [
+	"O09",
+	"O10",
+	"O11",
+	"O12",
+	"O13",
+	"O14",
+	"O15",
+	"O16",
+	"O17",
+	"O18",
+	"O19",
+	"O21",
+	"O22",
+	"O23",
+	"O27"
+];
+/** This function gives a finite amount in seconds. */
+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 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. */
+const serviceBindings = (svc, scenario) => {
+	const bind = {};
+	const from = {};
+	const set = (symbol, bound, said) => {
+		if (bound === void 0) return;
+		bind[symbol] = bound;
+		from[symbol] = said;
+	};
+	const gating = svc.checks.filter((check) => check.gates !== null);
+	const readinessChecks = gating.filter((check) => check.gates === "readiness");
+	const livenessChecks = gating.filter((check) => check.gates === "liveness");
+	set("check_poll_interval@service", most(gating.map((check) => secondsOf(check.poll.interval))), "the slowest gating check's interval");
+	set("check_timeout@service", most(gating.map((check) => secondsOf(check.poll.timeout))), "the longest gating check's timeout");
+	set("slowest_poll@service", most(gating.map((check) => secondsOf(check.poll.timeout) + secondsOf(check.poll.interval) * (1 + check.poll.jitter))), "a check's timeout plus one jittered interval, at its slowest");
+	const windowOf = (checks, policy) => most(checks.map((check) => secondsOf(failSpan(svc.policies[policy], check.poll, "timeout").max)));
+	const readiness = windowOf(readinessChecks, "readiness");
+	const liveness = windowOf(livenessChecks, "liveness");
+	set("readiness_detection_window@service", readiness, "the readiness latch, failing by timeout");
+	if (readiness !== void 0) set("readiness_detection_window@pod", readiness + secondsOf(scenario.probes.readiness), "the readiness latch, then the kubelet's probe");
+	if (liveness !== void 0) set("liveness_detection_window@pod", liveness + secondsOf(scenario.probes.liveness), "the liveness window, then the kubelet's probe");
+	set("startup_budget@pod", secondsOf(svc.policies.startup), "the declared startup budget");
+	set("process_drain_time@process", svc.shutdown.phases.reduce((total, phase) => total + secondsOf(phase.cap), 0), `the shutdown phases' caps, summed (${svc.shutdown.phases.map((phase) => phase.name).join(", ")})`);
+	set("cooperative_window@process", boundOf(svc.shutdown.cooperativeWindow), "the declared cooperative window");
+	for (const [symbol, amount] of Object.entries(scenario.platform)) set(symbol, boundOf(amount), "the scenario");
+	return {
+		bind,
+		from
+	};
+};
+/** This function gives the client knobs of a dependency at @client, and the values of the scenario at its own hops. */
+const dependencyBindings = (dependency, scenario) => {
+	const bind = {};
+	for (const [knob, amount] of Object.entries(dependency.knobs)) bind[`${knob}@client`] = boundOf(amount);
+	for (const [symbol, amount] of Object.entries(scenario.dependencies?.[dependency.name] ?? {})) bind[symbol.includes("@") ? symbol : `${symbol}@dependency`] = boundOf(amount);
+	return bind;
+};
+const SCOPED = /@(client|dependency|server)$/;
+/** This function applies each service rule to a declaration and a scenario: one time for the service, and one time for each client. */
+const lint = (svc, scenario, rules) => {
+	const service = serviceBindings(svc, scenario).bind;
+	const findings = [];
+	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, {
+			...service,
+			...dependencyBindings(dependency, scenario)
+		}]) : [[svc.name, service]];
+		for (const [scope, bind] of scopes) {
+			const evaluated = evaluate(rule, bind);
+			findings.push({
+				rule: rule.id,
+				scope,
+				verdict: verdictOf(rule, bind, evaluated),
+				statement: rule.rule,
+				...rule.window !== void 0 ? { window: rule.window } : {},
+				evaluated,
+				unbound: symbols.filter((symbol) => bind[symbol] === void 0)
+			});
+		}
+	}
+	return findings;
+};
+//#endregion
+//#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