@loadmap/cli 0.1.1 → 0.3.0

package/dist/{src-B81_QU8o.js → src-CCAswkjM.js}

@@ -12,6 +12,10 @@ function measured(value, unit, o) {
 function estimated(value, unit, o) {
 	return capacity(value, unit, "estimated", o);
 }
+/** A limit someone set, such as a rate limiter's: exact, so it takes no ±. */
+function configured(value, unit, source) {
+	return capacity(value, unit, "configured", source);
+}
 function capacity(value, unit, provenance, o) {
 	const { source, within } = typeof o === "string" ? {
 		source: o,
@@ -34,7 +38,7 @@ function boundOf(c, bound) {
 }
 // ../core/src/format.ts
 /** A number for a reader: 1,234 / 12.3 / 0.4. */
-function fmt(n) {
+function fmt$1(n) {
 	if (!Number.isFinite(n)) return n > 0 ? "∞" : "—";
 	if (Math.abs(n) >= 1e3) return Math.round(n).toLocaleString("en-US");
 	return (Math.round(n * 10) / 10).toString();
@@ -51,7 +55,7 @@ function compact(n) {
 /** A load multiple, rounded down so it never promises more than the model: 2.6× / 53×. */
 function multiple(u, searchMax = 2e3) {
 	if (u == null) return "—";
-	if (!Number.isFinite(u)) return `beyond ${fmt(searchMax)}×`;
+	if (!Number.isFinite(u)) return `beyond ${fmt$1(searchMax)}×`;
 	return u >= 10 ? `${Math.floor(u)}×` : `${Math.floor(u * 10) / 10}×`;
 }
 /**
@@ -210,6 +214,19 @@ function workers(component, o) {
 		fill: o.fill ?? "round-robin"
 	};
 }
+function cache(o) {
+	return {
+		kind: "cache",
+		...o
+	};
+}
+function limit(component, o = {}) {
+	return {
+		kind: "limit",
+		component,
+		...o
+	};
+}
 function store(component, o = {}) {
 	return {
 		kind: "store",
@@ -229,11 +246,17 @@ function fanout(o) {
 		...o
 	};
 }
+/** The share a stage turns away when its component is past `full`: what is above it. */
+function rejectShare(util, full) {
+	return util != null && util > full ? 1 - full / util : 0;
+}
 function dyn(v, ctx) {
 	return typeof v === "function" ? v(ctx) : v;
 }
-function resolveStage(id, s, ctx, flowIds) {
+function resolveStage(id, s, ctx, flowIds, full) {
 	const label = s.label ?? id;
+	const util = (c) => c ? ctx.util[c] : null;
+	const rejects = rejectShare(util(s.kind === "sink" ? void 0 : s.component), full);
 	switch (s.kind) {
 		case "queue": return {
 			id,
@@ -242,15 +265,32 @@ function resolveStage(id, s, ctx, flowIds) {
 			component: s.component,
 			partitions: dyn(s.partitions, ctx)
 		};
-		case "workers": return {
-			id,
-			label,
-			kind: "workers",
-			component: s.component,
-			pods: dyn(s.pods, ctx),
-			perPod: dyn(s.perPod, ctx),
-			fill: s.fill
-		};
+		case "workers": {
+			const perPod = dyn(s.perPod, ctx);
+			const base = {
+				id,
+				label,
+				kind: "workers",
+				component: s.component,
+				perPod,
+				fill: s.fill
+			};
+			if (!s.autoscale) {
+				const pods = dyn(s.pods ?? 0, ctx);
+				return {
+					...base,
+					pods,
+					running: pods
+				};
+			}
+			const a = autoscaleOf(id, s.autoscale, ctx);
+			return {
+				...base,
+				pods: a.max,
+				running: running(a, util(s.component)),
+				autoscale: a
+			};
+		}
 		case "fanout": {
 			const to = dyn(s.to, ctx);
 			const perFlow = {};
@@ -260,26 +300,72 @@ function resolveStage(id, s, ctx, flowIds) {
 				label,
 				kind: "fanout",
 				component: s.component,
-				to: perFlow
+				to: perFlow,
+				rejects,
+				shed: rejects
 			};
 		}
+		case "cache": return {
+			id,
+			label,
+			kind: "cache",
+			component: s.component,
+			hit: hitOf(id, s, ctx),
+			rejects,
+			shed: rejects
+		};
 		case "sink": return {
 			id,
 			label,
 			kind: "sink"
 		};
+		case "store": return {
+			id,
+			label,
+			kind: "store",
+			component: s.component
+		};
 		default: return {
 			id,
 			label,
 			kind: s.kind,
-			component: s.component
+			component: s.component,
+			rejects,
+			shed: rejects
 		};
 	}
 }
+/** A cache's hit share, checked: a share outside 0 to 1 is a mistake, not a rate. */
+function hitOf(id, s, ctx) {
+	const hit = dyn(s.hit, ctx);
+	if (!(hit >= 0 && hit <= 1)) throw new Error(`loadmap: cache "${id}" needs a hit share from 0 to 1, not ${hit}`);
+	return hit;
+}
+function autoscaleOf(id, a, ctx) {
+	const min = dyn(a.min, ctx);
+	const max = dyn(a.max, ctx);
+	const target = dyn(a.target, ctx);
+	if (!(Number.isInteger(min) && Number.isInteger(max) && min >= 1 && max >= min)) throw new Error(`loadmap: workers "${id}" autoscale needs whole numbers with 1 ≤ min ≤ max, not ${min} and ${max}`);
+	if (!(target > 0 && target <= 1)) throw new Error(`loadmap: workers "${id}" autoscale needs a target above 0 and at most 1, not ${target}`);
+	return {
+		min,
+		max,
+		target
+	};
+}
+/**
+* The pods an autoscaler runs: enough to hold each near its target. `util` is against the pool at max pods, so
+* util × max is the work in pods' worth of capacity.
+*/
+function running(a, util) {
+	const need = Math.ceil((util ?? 0) * a.max / a.target - 1e-9);
+	return Math.min(a.max, Math.max(a.min, need));
+}
 // ../core/src/model.ts
 const RESERVED$1 = [
 	"load",
 	"flows",
+	"at",
 	"demand",
 	"util",
 	"derived"
@@ -299,6 +385,11 @@ function defineModel(def) {
 			if (st.kind === "fanout" && i < route.length - 1) throw new Error(`loadmap: fan-out "${s}" must be the last stage of the route of "${f}"`);
 		});
 	}
+	for (const c of componentIds) if (!def.components[c].demand && !stageIds.some((s) => def.stages[s].component === c)) throw new Error(`loadmap: component "${c}" needs a demand: no stage uses it`);
+	for (const s of stageIds) {
+		const st = def.stages[s];
+		if (st.kind === "workers" && st.pods == null === (st.autoscale == null)) throw new Error(`loadmap: workers "${s}" needs pods or autoscale, one of them`);
+	}
 	const thresholds = {
 		target: def.thresholds?.target ?? .5,
 		full: def.thresholds?.full ?? 1
@@ -397,8 +488,17 @@ function defineModel(def) {
 		const stated = context(def, values);
 		const uncertain = componentIds.filter((c) => (stated.capacity(c).within ?? 0) > 0);
 		const components = {};
+		const seen = /* @__PURE__ */ new Map();
+		const utilOf = (bound, load) => {
+			const k = `${bound}|${load}`;
+			const hit = seen.get(k);
+			if (hit) return hit;
+			const u = utilAt(values, bound)(load);
+			seen.set(k, u);
+			return u;
+		};
 		for (const c of componentIds) {
-			const at = (bound) => (load) => utilAt(values, bound)(load)[c];
+			const at = (bound) => (load) => utilOf(bound, load)[c];
 			const both = (th) => {
 				const x = crossing(at(), th, searchMax);
 				if (x == null) return {
@@ -485,7 +585,7 @@ function defineModel(def) {
 			...defaults(),
 			...partial
 		};
-		const { ctx, capacity, over, describe } = context(def, values);
+		const { ctx, capacity, over, describe, overload: overloadOf, retries, shed } = context(def, values);
 		const crossings = crossingsFor(values);
 		const components = {};
 		for (const c of componentIds) {
@@ -525,15 +625,24 @@ function defineModel(def) {
 		const flows = {};
 		for (const f of flowIds) flows[f] = ctx.flows[f];
 		const stages = {};
-		for (const s of stageIds) stages[s] = resolveStage(s, def.stages[s], ctx, flowIds);
+		for (const s of stageIds) {
+			const st = resolveStage(s, def.stages[s], ctx, flowIds, thresholds.full);
+			stages[s] = st.kind === "pass" || st.kind === "limit" || st.kind === "cache" ? {
+				...st,
+				shed: shed(s)
+			} : st;
+		}
 		for (const st of Object.values(stages)) if (st.kind === "fanout") for (const b of Object.values(st.to).flat()) {
 			const to = stages[b.stage];
 			if (!to || to.kind === "queue" || to.kind === "workers" || to.kind === "fanout") throw new Error(`loadmap: fan-out "${st.id}" branches to "${b.stage}", which is not a sink, store or pass stage`);
 		}
 		const overload = {};
-		for (const f of flowIds) {
-			const o = def.flows[f].overload;
-			overload[f] = (typeof o === "function" ? o(ctx) : o) ?? {};
+		for (const f of flowIds) overload[f] = overloadOf(f);
+		const at = {};
+		for (const s of stageIds) {
+			const row = {};
+			for (const f of flowIds) row[f] = ctx.at[s][f];
+			at[s] = row;
 		}
 		const assumptions = [];
 		for (const c of componentIds) {
@@ -567,7 +676,9 @@ function defineModel(def) {
 			assumptions,
 			stages,
 			routes: def.routes,
+			at,
 			overload,
+			retry: retries(),
 			ctx
 		};
 	};
@@ -604,9 +715,10 @@ function defineModel(def) {
 }
 /**
 * The model's numbers for one set of values. Every number is computed on first use and kept, so a model function
-* may read any other; a value that needs itself throws, naming the loop.
+* may read any other; a value that needs itself throws, naming the loop. Retries are the one loop that is solved:
+* a retrying flow's attempts settle where the share its route turns away gives back the same attempts.
 */
-function context(def, values, bound, pinned) {
+function context(def, values, bound, pinned, fixed) {
 	const cache = /* @__PURE__ */ new Map();
 	const stack = [];
 	const memo = (key, f) => {
@@ -630,15 +742,205 @@ function context(def, values, bound, pinned) {
 		return Object.freeze(t);
 	};
 	const ctx = { ...values };
+	const full = def.thresholds?.full ?? 1;
 	const flowIds = Object.keys(def.flows);
 	const componentIds = Object.keys(def.components);
+	const stages = def.stages;
+	const stageIds = Object.keys(stages);
+	const routes = def.routes;
 	const capacity = (c) => memo(`capacity of ${c}`, () => {
 		const cap = def.components[c].capacity;
 		return typeof cap === "function" ? cap(ctx) : cap;
 	});
 	const enabled = (c) => memo(`${c} enabled`, () => def.components[c].when?.(ctx) ?? true);
-	ctx.flows = table(flowIds, (f) => memo(`flow ${f}`, () => def.flows[f].rate(ctx)));
-	ctx.demand = table(componentIds, (c) => memo(`demand of ${c}`, () => def.components[c].demand(ctx)));
+	const overload = (f) => memo(`overload of ${f}`, () => {
+		const o = def.flows[f].overload;
+		return (typeof o === "function" ? o(ctx) : o) ?? {};
+	});
+	const retryOf = (f) => {
+		const rule = def.flows[f].retry;
+		const r = typeof rule === "function" ? rule(values) : rule;
+		if (!r) return void 0;
+		if (!(Number.isInteger(r.times) && r.times >= 0)) throw new Error(`loadmap: flow "${f}" retries a whole number of times, not ${r.times}`);
+		if (r.budget != null && !(r.budget >= 0 && Number.isFinite(r.budget))) throw new Error(`loadmap: flow "${f}" needs a retry budget of 0 or more, not ${r.budget}`);
+		return r.times > 0 && r.budget !== 0 ? r : void 0;
+	};
+	const rate = (f) => memo(`rate of ${f}`, () => def.flows[f].rate(ctx));
+	ctx.flows = table(flowIds, (f) => memo(`flow ${f}`, () => {
+		if (fixed && Object.hasOwn(fixed, f)) return fixed[f];
+		return retryOf(f) ? retries()[f].attempts : def.flows[f].rate(ctx);
+	}));
+	/** The share a stage turns away: past its component's `full`, what is above it. */
+	const rejects = (s) => memo(`rejects at ${s}`, () => {
+		const st = stages[s];
+		if (!(st.kind === "pass" || st.kind === "limit" || st.kind === "cache" || st.kind === "fanout") || !st.component) return 0;
+		return rejectShare(ctx.util[st.component], full);
+	});
+	const hit = (s) => memo(`hit at ${s}`, () => hitOf(s, stages[s], ctx));
+	/** The share of a flow's units that go on past a stage: cache hits stay, and what a limiter turns away. */
+	const onward = (s) => {
+		const st = stages[s];
+		return st.kind === "cache" ? 1 - hit(s) : st.kind === "limit" ? 1 - rejects(s) : 1;
+	};
+	/** Copies per unit of a flow that a fan-out at t sends to s: 0 unless t is a fan-out with a branch there. */
+	const copies = (t, f, s) => {
+		const st = stages[t];
+		if (st.kind !== "fanout") return 0;
+		const to = memo(`branches of ${t}`, () => dyn(st.to, ctx));
+		let n = 0;
+		for (const b of Array.isArray(to) ? to : to[f] ?? []) if (b.stage === s) n += b.share;
+		return n;
+	};
+	const arriving = (s, f) => memo(`${f} at ${s}`, () => {
+		const route = routes[f] ?? [];
+		const last = route.findLastIndex((t) => t === s || copies(t, f, s) > 0);
+		let total = 0;
+		let r = ctx.flows[f];
+		for (const [i, t] of route.entries()) {
+			if (t === s) total += r;
+			total += r * copies(t, f, s);
+			if (i >= last) break;
+			r *= onward(t);
+		}
+		return total;
+	});
+	const inner = /* @__PURE__ */ new Map();
+	ctx.at = table(stageIds, (s) => {
+		const known = inner.get(s);
+		if (known) return known;
+		const t = table(flowIds, (f) => arriving(s, f));
+		inner.set(s, t);
+		return t;
+	});
+	/**
+	* The share of a flow's attempts turned away somewhere on its route; a cache hit is an answer, not a failure. A
+	* stage's rejections are counted against what is offered to it, so behind another stage that turns work away it
+	* passes at most what it can take (offered × (1 − rejects)), not a share of a share: the bottleneck decides.
+	*/
+	const failure = (f) => memo(`failures of ${f}`, () => {
+		let offered = 1;
+		let actual = 1;
+		let answered = 0;
+		for (const s of routes[f] ?? []) {
+			const r = stages[s].kind === "fanout" ? 0 : rejects(s);
+			if (r > 0) actual = Math.min(actual, offered * (1 - r));
+			if (stages[s].kind === "cache") {
+				answered += actual * hit(s);
+				actual *= 1 - hit(s);
+			}
+			offered *= onward(s);
+		}
+		return Math.max(0, 1 - answered - actual);
+	});
+	/**
+	* What actually reaches a stage, per second: like `at`, less what stages before it turned away. A stage takes up to
+	* what is offered to it × (1 − rejects), so behind another stage that turns work away the bottleneck decides.
+	*/
+	const actual = (s, f) => memo(`${f} reaching ${s}`, () => {
+		const route = routes[f] ?? [];
+		const last = route.findLastIndex((t) => t === s || copies(t, f, s) > 0);
+		let total = 0;
+		let r = ctx.flows[f];
+		for (const [i, t] of route.entries()) {
+			if (t === s) total += r;
+			total += r * copies(t, f, s) * (1 - rejects(t));
+			if (i >= last) break;
+			const cut = rejects(t);
+			if (cut > 0) r = Math.min(r, arriving(t, f) * (1 - cut));
+			if (stages[t].kind === "cache") r *= 1 - hit(t);
+		}
+		return total;
+	});
+	/** The share of what actually reaches a stage that it turns away: the one number the sim and the meters show. */
+	const shed = (s) => memo(`shed at ${s}`, () => {
+		const r = rejects(s);
+		if (!r) return 0;
+		let offered = 0;
+		let reaching = 0;
+		for (const f of flowIds) {
+			offered += arriving(s, f);
+			reaching += actual(s, f);
+		}
+		return reaching > 0 ? Math.max(0, 1 - offered * (1 - r) / reaching) : 0;
+	});
+	const retries = () => memo("retries", () => {
+		const ids = flowIds.filter((f) => retryOf(f));
+		const lam = {};
+		for (const f of ids) lam[f] = rate(f);
+		const most = (f) => {
+			const r = retryOf(f);
+			return Math.min(r.times, r.budget ?? Number.POSITIVE_INFINITY);
+		};
+		const attempts = (e) => {
+			const a = {};
+			for (const f of ids) a[f] = lam[f] * (1 + e[f]);
+			return a;
+		};
+		const wanted = (e) => {
+			const sub = context(def, values, bound, pinned, attempts(e));
+			const w = {};
+			const p = {};
+			for (const f of ids) {
+				p[f] = sub.failure(f);
+				w[f] = Math.min(excess(p[f], retryOf(f).times), most(f));
+			}
+			return {
+				w,
+				p
+			};
+		};
+		let e = Object.fromEntries(ids.map((f) => [f, 0]));
+		for (let step = 0; step < 100; step++) {
+			const { w, p: failed } = wanted(e);
+			const d = {};
+			for (const f of ids) d[f] = Math.max(0, w[f] - e[f]);
+			const live = ids.filter((f) => lam[f] > 0 && d[f] > (step ? 1e-10 * (1 + e[f]) : 0));
+			if (!live.length) {
+				const a = attempts(e);
+				const out = {};
+				for (const f of ids) {
+					const l = lam[f];
+					const p = failed[f];
+					const times = retryOf(f).times;
+					const retried = p > 0 && excess(p, times) > e[f] * (1 + 1e-12) ? root((y) => excess(y, times), e[f], p) / p : 1;
+					out[f] = {
+						times,
+						rate: l,
+						attempts: a[f],
+						rejected: p,
+						retried,
+						failed: l > 0 ? 1 - (1 - p) * (1 + e[f]) : 0
+					};
+				}
+				return out;
+			}
+			const along = (t) => {
+				const y = { ...e };
+				for (const f of live) y[f] = e[f] + t * d[f];
+				return y;
+			};
+			const holds = (t) => {
+				const y = along(t);
+				const wy = wanted(y).w;
+				return Math.min(...live.map((f) => (wy[f] - y[f]) / d[f]));
+			};
+			const far = Math.min(...live.map((f) => (most(f) - e[f]) / d[f]));
+			if (far <= 1) e = along(far);
+			else {
+				const h1 = holds(1);
+				e = along(h1 > 0 ? settle(holds, 1, far, h1) : 1);
+			}
+		}
+		throw new Error(`loadmap: the retries of ${joinAnd(ids.map((f) => `"${f}"`))} do not settle`);
+	});
+	const usedBy = (c) => stageIds.filter((s) => stages[s].component === c);
+	ctx.demand = table(componentIds, (c) => memo(`demand of ${c}`, () => {
+		const d = def.components[c].demand;
+		if (d) return d(ctx);
+		let total = 0;
+		for (const s of usedBy(c)) for (const f of flowIds) total += arriving(s, f);
+		return total;
+	}));
 	ctx.util = table(componentIds, (c) => memo(`utilization of ${c}`, () => {
 		if (!enabled(c)) return null;
 		const cap = boundOf(capacity(c), c === pinned ? void 0 : bound);
@@ -650,10 +952,55 @@ function context(def, values, bound, pinned) {
 	return {
 		ctx: Object.freeze(ctx),
 		capacity,
+		overload,
+		failure,
+		shed,
+		retries: () => flowIds.some((f) => retryOf(f)) ? retries() : {},
 		over: (c) => text(def.components[c].over) ?? "",
 		describe: (c) => text(def.components[c].describe)
 	};
 }
+/** y + y² + … + yⁿ: the retries per unit when each attempt fails with share y and n retries may follow. */
+function excess(y, n) {
+	return y >= 1 ? n : y * (1 - y ** n) / (1 - y);
+}
+/**
+* Where h, above 0 at lo and at most 0 at hi, reaches 0: regula falsi with the Illinois step, a few evaluations where
+* bisection takes forty, and still bracketed when h has a kink (the knee where rejections start).
+*/
+function settle(h, lo, hi, hl = h(lo)) {
+	let hh = h(hi);
+	if (hh >= 0) return hi;
+	let side = 0;
+	let x = lo;
+	for (let k = 0; k < 100 && hi - lo > 1e-13 * hi; k++) {
+		x = (lo * hh - hi * hl) / (hh - hl);
+		const hx = h(x);
+		if (hx === 0) break;
+		if (hx > 0) {
+			lo = x;
+			hl = hx;
+			if (side === 1) hh /= 2;
+			side = 1;
+		} else {
+			hi = x;
+			hh = hx;
+			if (side === -1) hl /= 2;
+			side = -1;
+		}
+	}
+	return x;
+}
+/** The y in [0, hi] where a rising f(y) reaches `goal`. */
+function root(f, goal, hi) {
+	let lo = 0;
+	for (let k = 0; k < 200 && hi - lo > 1e-15; k++) {
+		const mid = (lo + hi) / 2;
+		if (f(mid) < goal) lo = mid;
+		else hi = mid;
+	}
+	return (lo + hi) / 2;
+}
 /**
 * The lowest load multiple at which `util(load)` reaches `th`. A coarse geometric scan finds the first bracket, so a
 * utilization that does not rise steadily with the load is not mis-bisected; bisection then narrows it.
@@ -688,13 +1035,13 @@ function reach(r, searchMax, when = () => null) {
 	if (!r) return multiple(null);
 	return `${multiples(r, searchMax)}${months(when(r.low), when(r.high))}`;
 }
-/** " (capacity estimated ±30 %)"; nothing for a measured capacity without a ±. */
+/** " (capacity estimated ±30 %)"; nothing for a measured capacity without a ± or a configured one. */
 function sureness(c) {
-	if (!c || c.provenance === "measured" && !c.within) return "";
+	if (!c || c.provenance !== "estimated" && !c.within) return "";
 	return ` (capacity ${c.provenance}${c.within ? ` ±${pct(c.within)}` : ""})`;
 }
 function verdict(load, live, first, range, th, searchMax, when) {
-	const at = `At ${fmt(load)}×`;
+	const at = `At ${fmt$1(load)}×`;
 	const target = `${pct(th.target)} target`;
 	if (!first) return {
 		tier: "ok",
@@ -810,7 +1157,7 @@ function check$1(model, expectations = model.expectations) {
 			});
 		}
 		const failed = claims.filter((x) => !x.ok);
-		const message = failed.length ? failed.map((x) => `expected at least ${fmt(x.min)}×, but ${x.text}`).join("; ") : claims.map((x) => x.text).join("; ");
+		const message = failed.length ? failed.map((x) => `expected at least ${fmt$1(x.min)}×, but ${x.text}`).join("; ") : claims.map((x) => x.text).join("; ");
 		return {
 			expectation: e,
 			ok: !failed.length,
@@ -1014,6 +1361,26 @@ function distance(a, b) {
 function own(o, k) {
 	return Object.hasOwn(o, k) ? o[k] : void 0;
 }
+/**
+* Which argument of a statement fills which slot: by kind, in order, optional slots skipped. `bad` are the ones that
+* fit no slot, `missing` the first required slot left empty.
+*/
+function matchArgs(slots, args) {
+	const open = [...slots];
+	const filled = /* @__PURE__ */ new Map();
+	const bad = [];
+	for (const a of args) {
+		const kind = a.t === "id" ? "id" : a.t === "str" || a.t === "tpl" ? "text" : a.t === "num" ? "number" : null;
+		const i = open.findIndex((s) => s.kind === kind);
+		if (kind == null || i < 0 || open.slice(0, i).some((s) => !s.optional)) bad.push(a);
+		else filled.set(open.splice(0, i + 1).at(-1), a);
+	}
+	return {
+		filled,
+		bad,
+		missing: open.find((s) => !s.optional)
+	};
+}
 const STAGE_LABEL = [{
 	name: "id",
 	kind: "id",
@@ -1046,14 +1413,16 @@ const COMPONENT_PROPS = {
 		doc: "\"are past capacity\" instead of \"is\"."
 	},
 	demand: {
+		inspector: "main",
 		value: "number",
 		scope: "ctx",
-		doc: "What the component must handle, in its capacity's unit."
+		doc: "What the component must handle, in its capacity's unit. Without one: the units per second reaching its stages."
 	},
 	capacity: {
+		inspector: "main",
 		value: "capacity",
 		scope: "ctx",
-		doc: "What it can handle: measured(value, unit, source) or estimated(value, unit, source); `value ± 30%` says how sure it is."
+		doc: "What it can handle: measured(value, unit, source) or estimated(value, unit, source), `value ± 30%` saying how sure it is; configured(value, unit, source) for a limit someone set."
 	},
 	when: {
 		value: "boolean",
@@ -1114,6 +1483,7 @@ const SCHEMA = {
 		args: [],
 		props: {
 			title: {
+				inspector: "main",
 				value: "string",
 				scope: "const",
 				doc: "The heading above the diagram."
@@ -1172,6 +1542,7 @@ const SCHEMA = {
 		children: []
 	},
 	load: {
+		inspector: "model",
 		doc: "The load, as a multiple of today. It drives the limits.",
 		example: "load \"Users, × today\" { max: 100; default: 10 }",
 		args: [{
@@ -1186,6 +1557,7 @@ const SCHEMA = {
 				doc: "The lowest multiple. Default 1."
 			},
 			max: {
+				inspector: "main",
 				value: "number",
 				scope: "const",
 				doc: "The highest multiple on the slider.",
@@ -1197,6 +1569,7 @@ const SCHEMA = {
 				doc: "The slider step. Default 1."
 			},
 			default: {
+				inspector: "main",
 				value: "number",
 				scope: "const",
 				doc: "Where the slider starts. Default the minimum."
@@ -1205,6 +1578,7 @@ const SCHEMA = {
 		children: []
 	},
 	param: {
+		inspector: "model",
 		doc: "A control: options make a select, min and max a slider, a true or false default a switch.",
 		example: "param pods \"Worker pods\" { options: [2, 3, 4, 6]; default: 3 }",
 		args: [{
@@ -1217,26 +1591,31 @@ const SCHEMA = {
 		}],
 		props: {
 			options: {
+				inspector: "main",
 				value: "options",
 				scope: "const",
 				doc: "The choices of a select: [2, 3, 4] or [\"a\", \"b\"]."
 			},
 			min: {
+				inspector: "main",
 				value: "number",
 				scope: "const",
 				doc: "The lowest value of a slider."
 			},
 			max: {
+				inspector: "main",
 				value: "number",
 				scope: "const",
 				doc: "The highest value of a slider."
 			},
 			step: {
+				inspector: "main",
 				value: "number",
 				scope: "const",
 				doc: "The step of a slider. Default 1."
 			},
 			default: {
+				inspector: "main",
 				value: "value",
 				scope: "const",
 				doc: "The starting value.",
@@ -1302,11 +1681,13 @@ const SCHEMA = {
 		}
 	},
 	growth: {
+		inspector: "model",
 		doc: "How fast the load grows, compounded from asOf, where it is 1×: load multiples become dates.",
 		example: "growth { rate: 0.06; per: month; asOf: \"2026-11-01\" }",
 		args: [],
 		props: {
 			rate: {
+				inspector: "main",
 				value: "number",
 				scope: "const",
 				required: true,
@@ -1395,6 +1776,7 @@ const SCHEMA = {
 		}
 	},
 	let: {
+		inspector: "model",
 		doc: "A named formula other formulas can use by its name.",
 		example: "let perPosition = watchOnly ? 0.3 : 1.2",
 		args: [{
@@ -1406,6 +1788,7 @@ const SCHEMA = {
 		children: []
 	},
 	fit: {
+		inspector: "model",
 		doc: "cost = a + b × x, fitted from measured points. Call it like a function: workerCores(rate).",
 		example: "fit workerCores \"Worker CPU per request\" { source: \"load test\"; points rate cores { 200 0.26 } }",
 		args: [{
@@ -1446,6 +1829,7 @@ const SCHEMA = {
 		rows: true
 	},
 	flow: {
+		inspector: "model",
 		doc: "Something that moves through the system, with its rate and its route.",
 		example: "flow orders \"orders\" { unit: \"order\"; rate: 40 * load; route: gateway -> topic -> workers }",
 		args: [{
@@ -1463,6 +1847,7 @@ const SCHEMA = {
 				doc: "One unit of the flow, singular: \"order\"."
 			},
 			rate: {
+				inspector: "main",
 				value: "number",
 				scope: "ctx",
 				doc: "Units per second.",
@@ -1492,7 +1877,11 @@ const SCHEMA = {
 				doc: "A theme colour (accent, alt, ok, warn, drop, muted) or a CSS colour in quotes."
 			}
 		},
-		children: ["drop", "merge"]
+		children: [
+			"drop",
+			"merge",
+			"retry"
+		]
 	},
 	drop: {
 		doc: "Units older than olderThan simulated seconds are dropped before they are handled.",
@@ -1534,6 +1923,32 @@ const SCHEMA = {
 		},
 		children: []
 	},
+	retry: {
+		doc: "A unit turned away on the route (by a pass, limit or cache stage past capacity) is sent again, up to times more times. The attempts settle where the retries they cause are the ones assumed.",
+		example: "retry { times: 3; budget: 0.1 }",
+		args: [],
+		props: {
+			times: {
+				inspector: "main",
+				value: "number",
+				scope: "values",
+				doc: "Retries after the first attempt: a whole number. Reads only the parameters.",
+				required: true
+			},
+			budget: {
+				inspector: "main",
+				value: "number",
+				scope: "values",
+				doc: "At most this share of the flow is added as retries: 0.1 adds at most 10 %. Without one, every retry is sent."
+			},
+			when: {
+				value: "boolean",
+				scope: "values",
+				doc: "The rule applies only while this is true; it reads only parameters."
+			}
+		},
+		children: []
+	},
 	component: {
 		doc: "Something that can run out: its demand against its capacity. On a box, write these lines on the box.",
 		example: "component cache \"Cache\" { demand: flows.reads; capacity: estimated(9000, \"req/s\") }",
@@ -1568,6 +1983,8 @@ const SCHEMA = {
 			"store",
 			"sink",
 			"fanout",
+			"cache",
+			"limit",
 			"component"
 		]
 	},
@@ -1578,6 +1995,7 @@ const SCHEMA = {
 		props: {
 			sub: SUB,
 			members: {
+				inspector: "main",
 				value: "number",
 				scope: "ctx",
 				doc: "How many members.",
@@ -1614,6 +2032,29 @@ const SCHEMA = {
 		props: { component: STAGE_COMPONENT },
 		children: []
 	},
+	cache: {
+		doc: "A share of the units (hit) is answered here and goes no further; the rest carry on to the next stage. Past capacity the share above 100 % is rejected.",
+		example: "cache { hit: 0.8 }",
+		args: STAGE_LABEL,
+		props: {
+			hit: {
+				inspector: "main",
+				value: "number",
+				scope: "ctx",
+				doc: "The share answered here, 0 to 1.",
+				required: true
+			},
+			component: STAGE_COMPONENT
+		},
+		children: []
+	},
+	limit: {
+		doc: "A rate limiter: its component's capacity is the limit. Above it the share over is turned away, and the stages after it see only what got through.",
+		example: "limit",
+		args: STAGE_LABEL,
+		props: { component: STAGE_COMPONENT },
+		children: []
+	},
 	store: {
 		doc: "Where a flow ends: written to its component.",
 		example: "store",
@@ -1656,12 +2097,13 @@ const SCHEMA = {
 		args: STAGE_LABEL,
 		props: {
 			pods: {
+				inspector: "main",
 				value: "number",
 				scope: "ctx",
-				doc: "How many pods.",
-				required: true
+				doc: "How many pods; an autoscaled pool has autoscale instead."
 			},
 			perPod: {
+				inspector: "main",
 				value: "number",
 				scope: "ctx",
 				doc: "Workers per pod.",
@@ -1675,6 +2117,35 @@ const SCHEMA = {
 			},
 			component: STAGE_COMPONENT
 		},
+		children: ["autoscale"]
+	},
+	autoscale: {
+		doc: "Pods are added and removed to hold each running pod near target, between min and max. The component's capacity is the pool at max pods: it runs out when the pool cannot grow further.",
+		example: "autoscale { min: 2; max: 10; target: 0.7 }",
+		args: [],
+		props: {
+			min: {
+				inspector: "main",
+				value: "number",
+				scope: "ctx",
+				doc: "The fewest pods, at least 1.",
+				required: true
+			},
+			max: {
+				inspector: "main",
+				value: "number",
+				scope: "ctx",
+				doc: "The most pods.",
+				required: true
+			},
+			target: {
+				inspector: "main",
+				value: "number",
+				scope: "ctx",
+				doc: "The utilization each running pod is held at, above 0 and at most 1: 0.7 scales out above 70 %.",
+				required: true
+			}
+		},
 		children: []
 	},
 	fanout: {
@@ -1686,6 +2157,7 @@ const SCHEMA = {
 		edges: "branches"
 	},
 	thresholds: {
+		inspector: "model",
 		doc: "The utilization of the target and of \"runs out\".",
 		example: "thresholds { target: 0.5; full: 1 }",
 		args: [],
@@ -1728,7 +2200,9 @@ const STAGES = [
 	"sink",
 	"queue",
 	"workers",
-	"fanout"
+	"fanout",
+	"cache",
+	"limit"
 ];
 // ../dsl/src/expr.ts
 /** A formula failed while the model ran: where, and why. */
@@ -1800,7 +2274,7 @@ const BUILTINS = {
 	fmt: {
 		args: ["number"],
 		result: "string",
-		fn: fmt
+		fn: fmt$1
 	},
 	compact: {
 		args: ["number"],
@@ -1836,11 +2310,22 @@ const BUILTINS = {
 		min: 2,
 		result: "capacity",
 		fn: estimated
+	},
+	configured: {
+		args: [
+			"number",
+			"string",
+			"string"
+		],
+		min: 2,
+		result: "capacity",
+		fn: configured
 	}
 };
-/** The tables a formula may read with a ".": flows.orders, demand.db, util.db, derived.x. */
+/** The tables a formula may read with a ".": flows.orders, at.db.orders, demand.db, util.db, derived.x. */
 const TABLES = [
 	"flows",
+	"at",
 	"demand",
 	"util",
 	"derived"
@@ -2005,14 +2490,15 @@ var Compiler$1 = class {
 		return bad;
 	}
 	example(table) {
-		return [...table === "flows" ? this.names.flows : table === "derived" ? this.names.lets.keys() : this.names.components][0] ?? "x";
+		return [...table === "flows" ? this.names.flows : table === "at" ? this.names.stages : table === "derived" ? this.names.lets.keys() : this.names.components][0] ?? "x";
 	}
 	member(e) {
 		const table = e.object.name;
 		const key = e.prop.name;
+		if (table === "at") return this.at(e);
 		const pool = table === "flows" ? this.names.flows : table === "demand" || table === "util" ? this.names.components : table === "derived" ? this.names.lets.keys() : void 0;
 		if (!pool) {
-			this.report.error(e.object, `"${table}" has no entries: only flows., demand., util. and derived. do`);
+			this.report.error(e.object, `"${table}" has no entries: only flows., at., demand., util. and derived. do`);
 			return bad;
 		}
 		if (!(table === "derived" ? this.names.lets.has(key) : pool.has(key))) {
@@ -2027,6 +2513,26 @@ var Compiler$1 = class {
 			run: (c) => c[table][key]
 		};
 	}
+	/** at.db: every flow reaching the stage, per second; at.db.orders: one flow. */
+	at(e) {
+		const stage = e.prop.name;
+		if (!this.names.stages.has(stage)) {
+			this.report.error(e.prop, `unknown stage "${stage}"`, didYouMean(stage, this.names.stages));
+			return bad;
+		}
+		const flow = e.flow?.name;
+		if (flow != null && !this.names.flows.has(flow)) {
+			this.report.error(e.flow, `unknown flow "${flow}"`, didYouMean(flow, this.names.flows));
+			return bad;
+		}
+		if (!this.canRead(e, flow == null ? `at.${stage}` : `at.${stage}.${flow}`)) return bad;
+		const flows = [...this.names.flows];
+		return {
+			type: "number",
+			constant: false,
+			run: flow == null ? (c) => flows.reduce((a, f) => a + c.at[stage][f], 0) : (c) => c.at[stage][flow]
+		};
+	}
 	call(e) {
 		const name = e.callee.name;
 		const pm = e.args[0]?.t === "pm" ? e.args[0] : null;
@@ -2180,8 +2686,11 @@ const PUNCT = [
 /**
 * Splits `source[from, to)` into tokens. Newlines end statements, except inside parentheses and brackets, so a long
 * formula can wrap there. `#` starts a comment to the end of the line.
+*
+* With `trivia` (for the formatter, never the parser) every newline is a token, blank lines and wrapped formulas
+* included, and so is every comment.
 */
-function lex(source, report, from = 0, to = source.length) {
+function lex(source, report, from = 0, to = source.length, trivia = false) {
 	const out = [];
 	let depth = 0;
 	let i = from;
@@ -2189,7 +2698,7 @@ function lex(source, report, from = 0, to = source.length) {
 	while (i < to) {
 		const c = source[i];
 		if (c === "\n") {
-			if (depth === 0 && out.at(-1)?.kind !== "newline") push({
+			if (trivia || depth === 0 && out.at(-1)?.kind !== "newline") push({
 				kind: "newline",
 				text: "\n",
 				from: i,
@@ -2197,8 +2706,16 @@ function lex(source, report, from = 0, to = source.length) {
 			});
 			i++;
 		} else if (c === " " || c === "	" || c === "\r") i++;
-		else if (c === "#") while (i < to && source[i] !== "\n") i++;
-		else if (isIdStart(c)) {
+		else if (c === "#") {
+			const s = i;
+			while (i < to && source[i] !== "\n") i++;
+			if (trivia) push({
+				kind: "comment",
+				text: source.slice(s, i).trimEnd(),
+				from: s,
+				to: i
+			});
+		} else if (isIdStart(c)) {
 			const s = i;
 			while (i < to && isIdPart(source[i])) i++;
 			push({
@@ -2401,7 +2918,7 @@ const PREC = {
 /** Thrown after a syntax error has been reported, to skip to the next statement. */
 var Bail$1 = class {};
 /** Parses a definition into statements. Never throws: errors go to the reporter, and parsing goes on at the next line. */
-function parse$1(source, report = new Reporter(source)) {
+function parse$2(source, report = new Reporter(source)) {
 	if (source.length > 2e5) {
 		report.error({
 			from: 0,
@@ -2771,6 +3288,19 @@ var Parser = class {
 					this.next();
 					const prop = this.ident("a name after \".\"");
 					if (!this.is("(")) {
+						if (callee.name === "at" && this.is(".")) {
+							this.next();
+							const flow = this.ident("a flow after \"at.<stage>.\"");
+							if (this.is(".")) this.fail(this.peek(), "at takes two names: at.db.orders");
+							return {
+								t: "member",
+								object: callee,
+								prop,
+								flow,
+								from: t.from,
+								to: flow.to
+							};
+						}
 						if (this.is(".")) this.fail(this.peek(), "only one \".\" is allowed: flows.orders, util.db");
 						return {
 							t: "member",
@@ -2872,7 +3402,7 @@ function compile(source, o = {}) {
 	let definition;
 	let expectations = [];
 	try {
-		doc = parse$1(source, report).doc;
+		doc = parse$2(source, report).doc;
 		definition = c.run(doc);
 		if (definition) expectations = check$1(definition.model).map((result, i) => {
 			const at = c.expectSpans[i];
@@ -2989,6 +3519,7 @@ var Compiler = class {
 			params: paramTypes,
 			lets: this.lets,
 			flows: new Set(flowNames.keys()),
+			stages: new Set(stageNames.keys()),
 			components: new Set(componentNames.keys()),
 			fits: this.fits,
 			functions: this.functions
@@ -3074,6 +3605,8 @@ var Compiler = class {
 			if (priority != null) def.priority = priority;
 			const overload = this.overload(b);
 			if (overload) def.overload = overload;
+			const retry = this.retry(b);
+			if (retry) def.retry = retry;
 			flowDefs[id.name] = def;
 			const route = this.prop(b, "route");
 			const stages = [];
@@ -3109,6 +3642,8 @@ var Compiler = class {
 			if (def) stageDefs[s.id] = def;
 		}
 		for (const [id, s] of stageOf) if (!reached.has(id) && s.block.keyword !== "fanout") this.report.warning(s.block.args.id ?? s.block.at, `no flow passes the stage "${id}"`);
+		const used = new Set(Object.values(stageDefs).map((d) => d.component));
+		for (const [id, c] of Object.entries(componentDefs)) if (!c.demand && !used.has(id)) this.report.error(componentNames.get(id), `the component "${id}" needs "demand: …": no stage uses it`, COMPONENT_PROPS.demand.doc);
 		const calibration = {};
 		for (const f of fits) {
 			const fit = f.args.id && this.fits.get(f.args.id.name);
@@ -3272,16 +3807,9 @@ var Compiler = class {
 		return b;
 	}
 	args(b, d) {
-		const slots = [...b.spec.args];
-		for (const a of d.args) {
-			const kind = a.t === "id" ? "id" : a.t === "str" || a.t === "tpl" ? "text" : a.t === "num" ? "number" : null;
-			const i = slots.findIndex((s) => s.kind === kind);
-			if (kind == null || i < 0 || slots.slice(0, i).some((s) => !s.optional)) {
-				this.report.error(a, `unexpected ${this.slice(a)} after "${b.keyword}"`, usage(b.keyword));
-				continue;
-			}
-			const slot = slots[i];
-			slots.splice(0, i + 1);
+		const { filled, bad, missing } = matchArgs(b.spec.args, d.args);
+		for (const a of bad) this.report.error(a, `unexpected ${this.slice(a)} after "${b.keyword}"`, usage(b.keyword));
+		for (const [slot, a] of filled) {
 			if (a.t === "tpl" && !slot.dynamic && !a.parts.length) {
 				b.args[slot.name] = {
 					t: "str",
@@ -3299,7 +3827,6 @@ var Compiler = class {
 			};
 			else b.args[slot.name] = a;
 		}
-		const missing = slots.find((s) => !s.optional);
 		if (missing) this.report.error(b.at, `"${b.keyword}" needs its ${missing.name}`, usage(b.keyword));
 		if (b.spec.init && !d.init) this.report.error(b.at, `"${b.keyword}" needs "= formula"`, usage(b.keyword));
 		if (!b.spec.init && d.init) this.report.error(d.init, `"${b.keyword}" takes no "="`);
@@ -3706,13 +4233,16 @@ var Compiler = class {
 		if (!rules.length) return void 0;
 		const seen = /* @__PURE__ */ new Set();
 		const parts = [];
+		const props = {
+			drop: ["olderThan", "reason"],
+			merge: ["share", "reason"]
+		};
 		for (const r of rules) {
 			const key = r.keyword;
 			if (seen.has(key)) this.report.error(r.at, `"${key}" is set twice in this flow`);
 			seen.add(key);
 			const fields = [];
-			const first = key === "drop" ? "olderThan" : "share";
-			for (const k of [first, "reason"]) {
+			for (const k of props[key]) {
 				const v = this.dynProp(r, k, k === "reason" ? "string" : "number");
 				if (v !== void 0) fields.push([k, v]);
 			}
@@ -3736,6 +4266,24 @@ var Compiler = class {
 		};
 		return fixed ? at(void 0) : at;
 	}
+	/** A flow's retry rule: it reads only the load and the parameters, since retries change every other number. */
+	retry(b) {
+		const r = b.children.filter((c) => c.keyword === "retry");
+		if (!r.length) return void 0;
+		if (r.length > 1) this.report.error(r[1].at, "\"retry\" is set twice in this flow");
+		const rule = r[0];
+		const times = this.dynProp(rule, "times", "number");
+		const budget = this.dynProp(rule, "budget", "number");
+		const w = this.prop(rule, "when");
+		const when = w && placed(w.value, this.formula(w.value, "values").run);
+		const at = (v) => {
+			if (when && !when(v)) return void 0;
+			const out = { times: (typeof times === "function" ? times(v) : times) ?? 0 };
+			if (budget !== void 0) out.budget = typeof budget === "function" ? budget(v) : budget;
+			return out;
+		};
+		return !when && typeof times !== "function" && typeof budget !== "function" ? at(void 0) : at;
+	}
 	component(b, box) {
 		const o = {};
 		const name = this.constProp(b, "name") ?? this.text(b.args.label) ?? this.text(box?.args.label);
@@ -3758,16 +4306,12 @@ var Compiler = class {
 			const prop = this.prop(b, k);
 			if (!prop) continue;
 			const check = k === "capacity" ? (v) => {
-				if (!isCapacity(v)) throw new Error("a capacity comes from measured(…) or estimated(…)");
+				if (!isCapacity(v)) throw new Error("a capacity comes from measured(…), estimated(…) or configured(…)");
 			} : void 0;
 			o[k] = this.dyn(prop.value, want, "ctx", check);
 		}
 		const at = box ? box.args.id ?? box.at : b.at;
-		for (const k of [
-			"demand",
-			"capacity",
-			"over"
-		]) if (!(k in o)) this.report.error(at, `the component needs "${k}: …"`, COMPONENT_PROPS[k].doc);
+		for (const k of ["capacity", "over"]) if (!(k in o)) this.report.error(at, `the component needs "${k}: …"`, COMPONENT_PROPS[k].doc);
 		return o;
 	}
 	stage(b, box, components, resolve, flows, reached) {
@@ -3785,18 +4329,46 @@ var Compiler = class {
 		};
 		switch (b.keyword) {
 			case "pass": return component ? pass(component, base) : needs();
+			case "limit": return component ? limit(component, base) : needs();
+			case "cache": {
+				const hit = this.dynProp(b, "hit", "number");
+				return cache({
+					...base,
+					hit: hit ?? 0,
+					...component ? { component } : {}
+				});
+			}
 			case "store": return component ? store(component, base) : needs();
 			case "sink": return sink(base);
 			case "workers": {
 				if (!component) return needs();
-				const pods = this.dynProp(b, "pods", "number", this.count("pods"));
 				const perPod = this.dynProp(b, "perPod", "number", this.count("perPod"));
 				const fill = this.constProp(b, "fill");
-				return workers(component, {
+				const rest = {
 					...base,
-					pods: pods ?? 0,
 					perPod: perPod ?? 0,
 					...fill ? { fill } : {}
+				};
+				const scale = b.children.find((c) => c.keyword === "autoscale");
+				if (scale) {
+					if (this.prop(b, "pods")) this.report.error(this.prop(b, "pods").key, "an autoscaled pool has no fixed pods", "leave out pods");
+					const min = this.dynProp(scale, "min", "number") ?? 1;
+					const max = this.dynProp(scale, "max", "number", this.count("pods")) ?? 1;
+					const target = this.dynProp(scale, "target", "number") ?? 1;
+					return workers(component, {
+						...rest,
+						autoscale: {
+							min,
+							max,
+							target
+						}
+					});
+				}
+				const pods = this.dynProp(b, "pods", "number", this.count("pods"));
+				if (!this.prop(b, "pods")) this.report.error(b.at, "a workers stage needs pods, or autoscale", "pods: 3, or autoscale { min: 2; max: 10; target: 0.7 }");
+				return workers(component, {
+					...rest,
+					pods: pods ?? 0
 				});
 			}
 			case "queue": {
@@ -3946,6 +4518,200 @@ function where(keyword) {
 	const parents = Object.entries(SCHEMA).filter(([, s]) => s.children.includes(keyword)).map(([k]) => k === "" ? "the top level" : k);
 	return parents.length ? `it goes in ${parents.join(" or ")}` : void 0;
 }
+// ../dsl/src/ast.ts
+/** The formulas directly inside a formula, in order; a template's parts only when asked (they are its own text). */
+function childrenOf(e, templates = false) {
+	switch (e.t) {
+		case "unary": return [e.arg];
+		case "pm": return [e.value, e.within];
+		case "cond": return [
+			e.test,
+			e.then,
+			e.else
+		];
+		case "bin": return [e.left, e.right];
+		case "call": return e.args;
+		case "array": return e.items;
+		case "tpl": return templates ? e.parts : [];
+		default: return [];
+	}
+}
+/**
+* Lays a definition out the one way: two spaces a block, a statement a line, at most one blank line, one space
+* around operators. It works on the tokens, so numbers, texts, templates and parentheses stay exactly as written and
+* a formula never changes. A block written on one line stays on one line while it fits. A text with a syntax error is
+* left alone.
+*/
+function format(source) {
+	const { doc, report } = parse$2(source);
+	if (report.failed) return {
+		ok: false,
+		text: source,
+		diagnostics: report.list
+	};
+	const toks = lex(source, new Reporter(source), 0, source.length, true).filter((t) => t.kind !== "eof");
+	const marks = marksOf(doc.body, toks);
+	const lines = new Reporter(source);
+	const match = /* @__PURE__ */ new Map();
+	const open = [];
+	for (let i = 0; i < toks.length; i++) if (isPunct(toks[i], "{")) open.push(i);
+	else if (isPunct(toks[i], "}")) match.set(open.pop(), i);
+	const empty = /* @__PURE__ */ new Set();
+	const written = /* @__PURE__ */ new Set();
+	for (const [i, j] of match) if (toks.slice(i + 1, j).every((t) => t.kind === "newline")) empty.add(i);
+	else if (lines.position(toks[i].from).line !== lines.position(toks[j].from).line) written.add(i);
+	const index = new Map(toks.map((t, i) => [t, i]));
+	const split = /* @__PURE__ */ new Set();
+	const oneLine = (t) => {
+		const i = index.get(t);
+		return isPunct(t, "{") && !empty.has(i) && !written.has(i) && !split.has(i);
+	};
+	for (;;) {
+		const out = layout(toks, match, (i) => split.has(i) || written.has(i), empty);
+		const text = out.map((l) => l.toks.length ? "  ".repeat(l.depth) + join$1(l.toks, marks) : "");
+		const long = out.find((l, n) => [...text[n]].length > 120 && l.toks.some(oneLine));
+		if (!long) return {
+			ok: true,
+			text: text.length ? `${text.join("\n")}\n` : "",
+			diagnostics: []
+		};
+		split.add(index.get(long.toks.find(oneLine)));
+	}
+}
+/** The tokens in lines with their depth. `multi` tells a block laid out a statement a line. */
+function layout(toks, match, multi, empty) {
+	const out = [];
+	let cur = [];
+	let depth = 0;
+	let lineDepth = 0;
+	let newlines = 0;
+	let start = true;
+	const blocks = [true];
+	const end = () => {
+		if (cur.length) out.push({
+			depth: lineDepth,
+			toks: cur
+		});
+		cur = [];
+	};
+	const add = (t) => {
+		if (!cur.length) {
+			if (newlines > 1 && !start && !isPunct(t, "}")) out.push({
+				depth: 0,
+				toks: []
+			});
+			lineDepth = depth - (isPunct(t, "}") || isPunct(t, ")") || isPunct(t, "]") ? 1 : 0);
+		}
+		newlines = 0;
+		start = false;
+		cur.push(t);
+	};
+	for (let i = 0; i < toks.length; i++) {
+		const t = toks[i];
+		if (t.kind === "newline") {
+			end();
+			newlines++;
+		} else if (isPunct(t, ";")) {
+			if (blocks.at(-1)) {
+				if (toks[i + 1]?.kind !== "comment") end();
+			} else {
+				const next = toks[i + 1];
+				const last = cur.at(-1);
+				if (!(!next || next.kind === "newline" || next.kind === "comment" || isPunct(next, "}") || !last || isPunct(last, "{") || isPunct(last, ";"))) add(t);
+			}
+		} else if (isPunct(t, "{")) {
+			if (empty.has(i)) {
+				add(t);
+				i = match.get(i);
+				add(toks[i]);
+				continue;
+			}
+			const m = multi(i);
+			add(t);
+			depth++;
+			blocks.push(m);
+			if (m) {
+				if (toks[i + 1]?.kind === "comment") add(toks[++i]);
+				end();
+				start = true;
+			}
+		} else if (isPunct(t, "}")) {
+			if (blocks.pop()) end();
+			add(t);
+			depth--;
+		} else if (isPunct(t, "(") || isPunct(t, "[")) {
+			add(t);
+			depth++;
+		} else if (isPunct(t, ")") || isPunct(t, "]")) {
+			add(t);
+			depth--;
+		} else add(t);
+	}
+	end();
+	return out;
+}
+function marksOf(body, toks) {
+	const m = {
+		unary: /* @__PURE__ */ new Set(),
+		percent: /* @__PURE__ */ new Set(),
+		ternary: /* @__PURE__ */ new Set()
+	};
+	const after = (at) => {
+		let lo = 0;
+		let hi = toks.length;
+		while (lo < hi) {
+			const mid = lo + hi >> 1;
+			if (toks[mid].from < at) lo = mid + 1;
+			else hi = mid;
+		}
+		return lo;
+	};
+	const find = (from, text) => {
+		for (let i = after(from); i < toks.length; i++) if (isPunct(toks[i], text)) return toks[i].from;
+		return -1;
+	};
+	const expr = (e) => {
+		if (!e) return;
+		if (e.t === "unary") {
+			let at = -1;
+			for (let i = after(e.from); i < toks.length && toks[i].from < e.arg.from; i++) if (isPunct(toks[i], e.op)) at = toks[i].from;
+			m.unary.add(at);
+		} else if (e.t === "pm" && e.percent) m.percent.add(find(e.within.to, "%"));
+		else if (e.t === "cond") m.ternary.add(find(e.then.to, ":"));
+		for (const k of childrenOf(e)) expr(k);
+	};
+	const stmt = (s) => {
+		if (s.kind === "row") s.values.forEach(expr);
+		else if (s.kind === "prop") expr(s.value);
+		else {
+			if (s.kind === "decl") {
+				s.args.forEach(expr);
+				expr(s.init);
+			} else expr(s.value);
+			s.body?.forEach(stmt);
+		}
+	};
+	body.forEach(stmt);
+	return m;
+}
+function join$1(toks, m) {
+	let s = toks[0].text;
+	for (let i = 1; i < toks.length; i++) s += gap(toks[i - 1], toks[i], m) + toks[i].text;
+	return s;
+}
+function gap(a, b, m) {
+	const A = a.kind === "punct" ? a.text : "";
+	const B = b.kind === "punct" ? b.text : "";
+	if (A === "{" && B === "}") return "";
+	if (A === "(" || A === "[" || A === ".") return "";
+	if ((A === "-" || A === "+" || A === "!") && m.unary.has(a.from)) return "";
+	if (B === ")" || B === "]" || B === "," || B === ";" || B === ".") return "";
+	if (B === "%" && m.percent.has(b.from)) return "";
+	if (B === ":" && !m.ternary.has(b.from)) return "";
+	if (B === "(" && a.kind === "ident") return "";
+	return " ";
+}
+const isPunct = (t, text) => t.kind === "punct" && t.text === text;
 // src/check.ts
 /**
 * `loadmap check`: compiles each definition and tests its expect lines. Resolves to the exit code: 1 when a
@@ -3955,7 +4721,7 @@ async function check(argv, o = {}) {
 	const log = o.log ?? console.log;
 	let parsed;
 	try {
-		parsed = parse(argv, o.env ?? process.env);
+		parsed = parse$1(argv, o.env ?? process.env);
 	} catch (err) {
 		log(err.message);
 		return 2;
@@ -3984,7 +4750,7 @@ async function check(argv, o = {}) {
 	}
 	return failed ? 1 : 0;
 }
-function parse(argv, env) {
+function parse$1(argv, env) {
 	const { values, positionals } = parseArgs({
 		args: argv,
 		allowPositionals: true,
@@ -4019,8 +4785,90 @@ function github(d, file, source) {
 }
 const data = (s) => s.replaceAll("%", "%25").replaceAll("\r", "%0D").replaceAll("\n", "%0A");
 const prop = (s) => data(s).replaceAll(":", "%3A").replaceAll(",", "%2C");
+// src/fmt.ts
+/**
+* `loadmap fmt`: lays each definition out the one way (`format()` of @loadmap/dsl), in place. With `--check` it only
+* names the files that are not laid out so. `-` reads standard input and writes standard output. Resolves to 1 when a
+* file has a syntax error, cannot be read, or (with --check) needs formatting; 2 for a usage mistake.
+*/
+async function fmt(argv, o = {}) {
+	const log = o.log ?? console.log;
+	let parsed;
+	try {
+		parsed = parse(argv);
+	} catch (err) {
+		log(err.message);
+		return 2;
+	}
+	if (parsed.stdin) {
+		const source = await (o.read ?? readStdin)();
+		const r = format(source);
+		if (!r.ok) for (const d of r.diagnostics) log(formatDiagnostic(d, source, "<stdin>"));
+		else (o.write ?? ((s) => process.stdout.write(s)))(r.text);
+		return r.ok ? 0 : 1;
+	}
+	let failed = false;
+	let changed = 0;
+	let skipped = 0;
+	for (const file of parsed.files) {
+		let source;
+		try {
+			source = await readFile(file, "utf8");
+		} catch (err) {
+			log(`${file}: cannot read it (${err.code ?? err.message})`);
+			failed = true;
+			skipped++;
+			continue;
+		}
+		const r = format(source);
+		if (!r.ok) {
+			for (const d of r.diagnostics) log(formatDiagnostic(d, source, file));
+			log(`${file}: left as it is, it has a syntax error`);
+			failed = true;
+			skipped++;
+		} else if (r.text !== source) {
+			changed++;
+			if (parsed.check) {
+				log(`${file}: not laid out by loadmap fmt`);
+				failed = true;
+			} else {
+				await writeFile(file, r.text);
+				log(`${file}: formatted`);
+			}
+		}
+	}
+	const n = parsed.files.length;
+	const files = (k) => `${k} ${k === 1 ? "file" : "files"}`;
+	const left = skipped ? `; ${skipped} left out (unreadable or a syntax error)` : "";
+	let summary = `${changed} of ${files(n)} formatted`;
+	if (parsed.check && changed) summary = `${changed} of ${files(n)} need loadmap fmt`;
+	else if (parsed.check) summary = skipped ? `${n - skipped} of ${files(n)} laid out already` : `${files(n)} laid out already`;
+	log(summary + left);
+	return failed ? 1 : 0;
+}
+function parse(argv) {
+	const { values, positionals } = parseArgs({
+		args: argv,
+		allowPositionals: true,
+		options: { check: { type: "boolean" } }
+	});
+	if (!positionals.length) throw new Error("loadmap fmt needs one or more .loadmap files, or - for standard input");
+	const stdin = positionals.includes("-");
+	if (stdin && (positionals.length > 1 || values.check)) throw new Error("loadmap fmt - reads standard input alone, without files or --check");
+	return {
+		files: positionals,
+		check: !!values.check,
+		stdin
+	};
+}
+async function readStdin() {
+	const chunks = [];
+	for await (const c of process.stdin) chunks.push(c);
+	return Buffer.concat(chunks).toString("utf8");
+}
 // src/index.ts
 const USAGE = `loadmap check <file.loadmap>… [--format text|github]
+loadmap fmt <file.loadmap>… [--check] | loadmap fmt -
 loadmap record <url | file.loadmap> --out <file.gif|.webm|.mp4|.png|.svg> [options]
 
 check compiles each definition and tests its expect lines on the pessimistic edge (every capacity at its low
@@ -4028,6 +4876,12 @@ bound). It exits 1 when a definition has an error or an expectation fails, 0 whe
 
   --format <f>          text, or github to add annotations on the lines (the default under GitHub Actions)
 
+fmt lays each definition out the one way, in place: two spaces a block, a statement a line, one space around
+operators; numbers, texts and formulas stay as written. A file with a syntax error is left alone (exit 1).
+
+  --check               change nothing; exit 1 when a file is not laid out so (for CI)
+  -                     read standard input, write standard output
+
 record opens the page in headless Chromium, finds the loadmap it exposes (expose() from @loadmap/export) and
 records it on a fixed clock, so the same options give the same file. A .loadmap file is drawn by the viewer that
 comes with the command.
@@ -4051,6 +4905,7 @@ comes with the command.
 async function main(argv, log = console.log) {
 	const [command, ...rest] = argv;
 	if (command === "check") return check(rest, { log });
+	if (command === "fmt") return fmt(rest, { log });
 	if (command !== "record") {
 		log(USAGE);
 		return command === "--help" || command === "-h" ? 0 : 2;
@@ -4254,4 +5109,4 @@ async function recordPage(a, format) {
 		await browser.close();
 	}
 }
-export { check as a, record as i, main as n, github as o, parseRecord as r, USAGE as t };
+export { fmt as a, record as i, main as n, check as o, parseRecord as r, github as s, USAGE as t };