@mark1russell7/coeval 0.4.1 → 0.4.3

package/build/index.js

@@ -175,9 +175,17 @@ function fromJson(value) {
 	});
 }
 /**
-* This function tells if two JSON values are equal. Equal values have the same texts, numbers and truth values,
-* the same items in the same order, and the same fields. The order of the fields does not matter. It does not use the stack for the
-* depth, thus a deep document cannot overflow it.
+* This function tells if two values are equal. Plain JSON compares by its structure. Equal values have the same
+* texts, numbers and truth values, the same items in the same order, and the same fields. The order of the fields
+* does not matter. Each leaf compares with `Object.is`, thus `-0` is not `0`, and `NaN` is `NaN`.
+*
+* Only lists and plain records (`isRecord`) compare by their items and fields. Each other object compares by
+* identity: a date, a map, a function and an instance of a class are equal only to themselves. Thus an early cutoff
+* with this function does not keep a stale host value.
+*
+* The function does not use the stack for the depth, thus a deep document cannot overflow it. A cycle of lists or
+* records does not make it loop. `sameValue` of `agree` uses the same rules, and it adds rules for closures and for
+* a rule of the caller.
 *
 * @param a - The first value.
 * @param b - The second value.
@@ -185,15 +193,23 @@ function fromJson(value) {
 */
 function docEquals(a, b) {
 	const stack = [[a, b]];
+	let seen;
 	while (stack.length > 0) {
 		const [x, y] = stack.pop();
 		if (Object.is(x, y)) continue;
-		if (typeof x !== "object" || typeof y !== "object" || x === null || y === null) return false;
-		if (Array.isArray(x) !== Array.isArray(y)) return false;
-		if (Array.isArray(x)) {
+		const list = Array.isArray(x);
+		if (list !== Array.isArray(y)) return false;
+		if (!list && (!isRecord(x) || !isRecord(y))) return false;
+		seen ??= /* @__PURE__ */ new Map();
+		const pairs = seen.get(x);
+		if (pairs?.has(y) === true) continue;
+		if (pairs === void 0) seen.set(x, /* @__PURE__ */ new Set([y]));
+		else pairs.add(y);
+		if (list) {
+			const xs = x;
 			const ys = y;
-			if (x.length !== ys.length) return false;
-			for (let index = 0; index < x.length; index += 1) stack.push([x[index], ys[index]]);
+			if (xs.length !== ys.length) return false;
+			for (let index = 0; index < xs.length; index += 1) stack.push([xs[index], ys[index]]);
 			continue;
 		}
 		const xr = x;
@@ -282,7 +298,11 @@ var Failure = class extends Error {
 * @returns `true` for a stack overflow.
 */
 function isStackOverflow(error) {
-	return error instanceof RangeError && /call stack/i.test(error.message);
+	try {
+		return error instanceof RangeError && /call stack/i.test(error.message);
+	} catch {
+		return true;
+	}
 }
 /**
 * This function changes an exception into an error value. A `Failure` gives its error value. A stack overflow
@@ -1036,6 +1056,10 @@ const NO_SLOTS = Object.freeze([]);
 function hasSlots(template) {
 	return template.t !== "data";
 }
+/** This function tells if a shape holds only data: no value of the shape can hold a part. */
+function isData(shape) {
+	return shape.shape === "none" || shape.shape === "text" || shape.shape === "number" || shape.shape === "one";
+}
 /** This function gives the reason why a value is not data of a shape, or `undefined` when it is. */
 function dataFault(spec, item) {
 	if (spec.shape === "text") return typeof item === "string" ? void 0 : "The value must be a text.";
@@ -1137,9 +1161,13 @@ function splitParts(shape, value) {
 				shape: "term",
 				...spec.of === void 0 ? {} : { of: spec.of }
 			};
-			return {
+			const items = list.map((child, index) => walk(each, child, [...path, index]));
+			return isData(each) ? {
+				t: "data",
+				value: item
+			} : {
 				t: "list",
-				items: list.map((child, index) => walk(each, child, [...path, index]))
+				items
 			};
 		}
 		if (!isRecord(item)) throw new Bad("The value must be a record.", path);
@@ -1207,6 +1235,54 @@ function splitParts(shape, value) {
 	};
 }
 /**
+* This function reads one document by the contracts of the world. It finds the kind of the type. A bare value gets
+* the type that its position declares. Then the function splits the value by the shape of the kind. The plan, the
+* reference interpreter and the static kit read each document with this function. Thus they see the same parts.
+*
+* @param world - The world of the kinds.
+* @param value - The document, or a bare value.
+* @param declaredType - The type that the position of a bare value declares.
+* @returns The document, its kind and its parts, or the reason why the value is not a document.
+*/
+function partsOf(world, value, declaredType) {
+	const envelope = isEnvelope(value) ? value : void 0;
+	if (envelope === void 0 && declaredType === void 0) return {
+		ok: false,
+		code: "#PART?",
+		reason: "The value has no envelope, and its position declares no type."
+	};
+	const doc = envelope ?? {
+		type: declaredType,
+		value
+	};
+	const found = lookupKind(world, doc.type);
+	const kind = found.ok ? found.kind : void 0;
+	const split = splitParts(kind?.parts, doc.value);
+	const typePath = found.ok ? found.path : void 0;
+	if (split.ok) return {
+		ok: true,
+		doc,
+		declared: envelope === void 0,
+		kind,
+		typePath,
+		split
+	};
+	const where = split.at.length === 0 ? "" : ` (at ${split.at.join(".")})`;
+	const reason = `${split.reason}${where} The kind is ${typeName(doc.type)}.`;
+	return {
+		ok: true,
+		doc,
+		declared: envelope === void 0,
+		kind,
+		typePath,
+		split: {
+			ok: false,
+			reason,
+			at: split.at
+		}
+	};
+}
+/**
 * This function tells if the path of a part matches a pattern of a scope rule. The key `"*"` of a pattern matches
 * each key.
 *
@@ -1543,7 +1619,7 @@ function holderNode() {
 	};
 }
 /** This function drives steps that cannot wait. */
-function drive(steps) {
+function drive$1(steps) {
 	const step = steps.next();
 	if (step.done === true) return step.value;
 	step.value.catch(() => void 0);
@@ -1586,7 +1662,10 @@ function isCompiledRunner(runner) {
 	return typeof runner === "object" && runner !== null && typeof runner.compileRun === "function";
 }
 function failing(c, meta, place, code, reason) {
-	const result = fail(code, reason, { place });
+	return failingWith(c, meta, fail(code, reason, { place }));
+}
+/** This function gives the code of a document that fails with one result at each evaluation. */
+function failingWith(c, meta, result) {
 	const plain = () => result;
 	return finish(c, meta, plain, function* () {
 		return result;
@@ -1648,15 +1727,15 @@ function finish(c, meta, code, run) {
 * This function finds the evaluator of the verb `eval` without the record of the rungs, for a compilation without a
 * trace. It gives the same evaluator as `ask`: the own entry, then the kind, then the default of the world.
 */
-function evaluatorOf(world, envelope, found) {
+function evaluatorOf(world, envelope, kind) {
 	const own = envelope?.own;
 	const ownName = own !== void 0 && Object.hasOwn(own, "eval") ? own["eval"] : void 0;
 	if (ownName !== void 0) return {
 		name: ownName,
 		unknown: false
 	};
-	if (!found.ok) return { unknown: true };
-	const verbs = found.kind.verbs;
+	if (kind === void 0) return { unknown: true };
+	const verbs = kind.verbs;
 	const name = Object.hasOwn(verbs, "eval") ? verbs["eval"] : Object.hasOwn(world.defaults, "eval") ? world.defaults["eval"] : void 0;
 	return name === void 0 ? { unknown: false } : {
 		name,
@@ -1675,23 +1754,28 @@ const NO_META = Object.freeze({
 	side: "derive"
 });
 function compileNode(c, value, place, declared, depth, address = false) {
-	const envelope = isEnvelope(value) ? value : void 0;
-	const doc = envelope ?? {
-		type: declared ?? "?",
-		value
-	};
+	const world = c.machine.world;
+	const read = partsOf(world, value, declared);
+	if (!read.ok) return failing(c, c.traced ? {
+		path: place.map(String),
+		doc: {
+			type: "?",
+			value
+		},
+		declared: true,
+		answer: NO_ANSWER,
+		side: "derive"
+	} : NO_META, place, read.code, read.reason);
+	const { doc, kind, split } = read;
+	const envelope = read.declared ? void 0 : doc;
 	const meta0 = c.traced ? {
 		path: place.map(String),
 		doc,
-		declared: envelope === void 0,
+		declared: read.declared,
 		answer: NO_ANSWER,
 		side: "derive"
 	} : NO_META;
-	if (envelope === void 0 && declared === void 0) return failing(c, meta0, place, "#PART?", "The value has no envelope, and its position declares no type.");
 	if (depth > c.maxDepth) return failing(c, meta0, place, "#DEPTH!", `The nesting is deeper than ${c.maxDepth} documents.`);
-	const world = c.machine.world;
-	const found = lookupKind(world, doc.type);
-	const kind = found.ok ? found.kind : void 0;
 	let meta = meta0;
 	let name;
 	let unknown;
@@ -1705,7 +1789,7 @@ function compileNode(c, value, place, declared, depth, address = false) {
 		name = answer.evaluator;
 		unknown = answer.error === "unknown-kind";
 	} else {
-		const quick = evaluatorOf(world, envelope, found);
+		const quick = evaluatorOf(world, envelope, kind);
 		name = quick.name;
 		unknown = quick.unknown;
 	}
@@ -1715,11 +1799,7 @@ function compileNode(c, value, place, declared, depth, address = false) {
 	const runner = name !== void 0 && Object.hasOwn(runners, name) ? runners[name] : void 0;
 	const evaluator = name !== void 0 && Object.hasOwn(c.machine.evaluators, name) ? c.machine.evaluators[name] : void 0;
 	if (name === void 0 || runner === void 0 && evaluator === void 0) return failing(c, meta, place, "#NOEVAL", `No rung gives an evaluator for ${kindText}.`);
-	const split = splitParts(kind?.parts, doc.value);
-	if (!split.ok) {
-		const at = split.at.length === 0 ? "" : ` (at ${split.at.join(".")})`;
-		return failing(c, meta, place, "#VALUE!", `${split.reason}${at} The kind is ${kindText}.`);
-	}
+	if (!split.ok) return failing(c, meta, place, "#VALUE!", split.reason);
 	const parts = split.parts.map((slot) => {
 		const item = slot.item;
 		const own = compileNode(c, item, place.concat(slot.path), slot.of, depth + 1, slot.address === true);
@@ -1741,7 +1821,7 @@ function compileNode(c, value, place, declared, depth, address = false) {
 	});
 	const input = {
 		kind: kindText,
-		typePath: found.ok ? found.path : [],
+		typePath: read.typePath ?? [],
 		doc,
 		value: split.parts.length === 0 ? doc.value : split.fill(parts),
 		data: split.data,
@@ -1752,10 +1832,22 @@ function compileNode(c, value, place, declared, depth, address = false) {
 		...address ? { address: true } : {}
 	};
 	if (runner !== void 0) {
-		const run = placedRun(isCompiledRunner(runner) ? runner.compileRun(input) : interpretRun(runner, input, split.fill), place, name);
+		let inner;
+		try {
+			inner = isCompiledRunner(runner) ? runner.compileRun(input) : interpretRun(runner, input, split.fill);
+		} catch (error) {
+			return failingWith(c, meta, placed(thrown(error, `the runner ${name}`), place));
+		}
+		const run = placedRun(inner, place, name);
 		return finish(c, meta, runnerCode(run, place, kindText), run);
 	}
-	const code = placedCode(isCompiledEvaluator(evaluator) ? evaluator.compile(input) : interpret(evaluator, input, split.fill), place, name);
+	let inner;
+	try {
+		inner = isCompiledEvaluator(evaluator) ? evaluator.compile(input) : interpret(evaluator, input, split.fill);
+	} catch (error) {
+		return failingWith(c, meta, placed(thrown(error, `the evaluator ${name}`), place));
+	}
+	const code = placedCode(inner, place, name);
 	return finish(c, meta, code, runOf(code));
 }
 /** This function gives the code of a document: the code of its evaluator, with the place of each error and of each exception. */
@@ -1797,9 +1889,12 @@ function placedRun(inner, place, name) {
 		}
 	};
 }
-/** This function gives the code of a runner in an evaluation: its steps, which cannot wait. */
+/**
+* This function gives the code of a runner in an evaluation: its steps, which cannot wait. A step that waits gives
+* `#CALC!` at the place of the runner, where the error started (RUN.WAIT).
+*/
 function runnerCode(run, place, kindText) {
-	return (ctx, rt) => rt.running ? fail("#CALC!", `${kindText} waits for effects, and its parent cannot wait. Give the parent a runner.`, { place }) : drive(run(ctx, rt));
+	return (ctx, rt) => rt.running ? fail("#CALC!", `${kindText} waits for effects, and its parent cannot wait. Give the parent a runner.`, { place }) : placed(drive$1(run(ctx, rt)), place);
 }
 /** This function gives the steps of a run of an evaluator. The code runs at the first step, and it does not wait. */
 function runOf(code) {
@@ -1891,7 +1986,7 @@ function prepare(machine, doc, options = {}) {
 	try {
 		root = compileNode(c, doc, [], options.declaredType, 0);
 	} catch (error) {
-		const result = thrown(error, "the compilation");
+		const result = placed(thrown(error, "the compilation"), []);
 		root = {
 			code: () => result,
 			run: function* () {
@@ -1952,7 +2047,7 @@ function planner(machine, options = {}) {
 		return plan;
 	};
 }
-function record(s, result) {
+function record$1(s, result) {
 	const root = s.holder?.children[0];
 	if (root === void 0) throw new Error("The evaluation made no trace.");
 	return {
@@ -1981,7 +2076,7 @@ function evaluate(machine, doc, context = makeContext(), declaredType) {
 		...declaredType === void 0 ? {} : { declaredType }
 	});
 	const s = new Session(machine, false, true, void 0, void 0, void 0);
-	return record(s, plan.root.code(rootContext(machine, context), s));
+	return record$1(s, plan.root.code(rootContext(machine, context), s));
 }
 /**
 * This function runs a document: an evaluation in which the host does each effect. A runner waits for its
@@ -2000,7 +2095,7 @@ async function run(machine, doc, context = makeContext(), options = {}) {
 		...options.declaredType === void 0 ? {} : { declaredType: options.declaredType }
 	});
 	const s = new Session(machine, true, true, options.perform, options.signal, void 0);
-	return record(s, await driveWaiting(plan.root.run(rootContext(machine, context), s), options.signal));
+	return record$1(s, await driveWaiting(plan.root.run(rootContext(machine, context), s), options.signal));
 }
 /**
 * This function finds a node of a trace by its path.
@@ -2998,40 +3093,32 @@ function walk(world, doc, visit, options = {}) {
 	}];
 	while (stack.length > 0) {
 		const item = stack.pop();
-		const envelope = isEnvelope(item.value) ? item.value : void 0;
-		if (envelope === void 0 && item.declared === void 0) {
+		const read = partsOf(world, item.value, item.declared);
+		if (!read.ok) {
 			options.problem?.({
 				place: keysOf(item.place),
 				at: keysOf(item.at),
-				code: "#PART?",
-				reason: "The value has no envelope, and its position declares no type."
+				code: read.code,
+				reason: read.reason
 			});
 			continue;
 		}
-		const doc = envelope ?? {
-			type: item.declared ?? "?",
-			value: item.value
-		};
-		const found = lookupKind(world, doc.type);
-		const kind = found.ok ? found.kind : void 0;
-		const here = new Visit(item.place, item.at, doc, envelope === void 0, item.depth, item.names, item.later, item.slot, item.parent, kind, found.ok ? found.path : void 0, item.address ? true : void 0, item.caps);
+		const { doc, kind, split } = read;
+		const here = new Visit(item.place, item.at, doc, read.declared, item.depth, item.names, item.later, item.slot, item.parent, kind, read.typePath, item.address ? true : void 0, item.caps);
 		if (visit(here) === "skip" || kind === void 0) continue;
-		const split = splitParts(kind.parts, doc.value);
-		const base = envelope === void 0 ? item.at : {
+		const base = read.declared ? item.at : {
 			up: item.at,
 			keys: ["value"]
 		};
 		if (!split.ok) {
-			const at = split.at.length === 0 ? "" : ` (at ${split.at.join(".")})`;
-			const where = keysOf({
-				up: base,
-				keys: split.at
-			});
 			options.problem?.({
 				place: keysOf(item.place),
-				at: where,
+				at: keysOf({
+					up: base,
+					keys: split.at
+				}),
 				code: "#VALUE!",
-				reason: `${split.reason}${at} The kind is ${typeName(doc.type)}.`
+				reason: split.reason
 			});
 			continue;
 		}
@@ -3163,7 +3250,8 @@ function capReason(v, kind) {
 * - `#PART?`: a value without a type.
 * - `#DEPTH!`: too much nesting.
 * - `#REF!` and `#STEP?`: a bad path.
-* - `#NAME?`: a name that nothing binds.
+* - `#NAME?`: a name that nothing binds. With the hook `known` of the machine, also a name that the language does not
+*   have, for example an operation.
 * - `#CAP!`: an effect that the capabilities of its document do not permit. A kind around the document can narrow them.
 *
 * @param machine - The world and the code of the evaluators.
@@ -3205,6 +3293,15 @@ function check(machine, doc, options = {}) {
 			reason: `No rung gives an evaluator for ${typeName(v.doc.type)}.`,
 			at: v.at
 		});
+		else if (machine.known !== void 0) {
+			const known = machine.known(v.typePath ?? [], name);
+			if (known !== true) issues.push({
+				code: "#NAME?",
+				place: v.place,
+				reason: known,
+				at: v.at
+			});
+		}
 		const caps = v.caps;
 		if (caps !== void 0 && v.kind?.effects !== void 0) {
 			const kinds = v.kind.effects === "type" ? [v.typePath ?? []] : v.kind.effects.map((kind) => kind.split("."));
@@ -3237,7 +3334,7 @@ function check(machine, doc, options = {}) {
 				reason: `A path starts with a root: ${ROOTS.join(", ")}.`,
 				at: stepAt(0)
 			});
-			return "skip";
+			return;
 		}
 		if (!roots.includes(root)) issues.push({
 			code: "#REF!",
@@ -3290,7 +3387,7 @@ var Held = class {
 		this.error = error;
 	}
 };
-const CLOSURE = Symbol.for("coeval.closure");
+const CLOSURE$2 = Symbol.for("coeval.closure");
 /**
 * This function tells if a value is a function that the construct `fn` made.
 *
@@ -3298,7 +3395,7 @@ const CLOSURE = Symbol.for("coeval.closure");
 * @returns `true` for a closure.
 */
 function isClosure(value) {
-	return typeof value === "function" && value[CLOSURE] !== void 0;
+	return typeof value === "function" && value[CLOSURE$2] !== void 0;
 }
 /** The standard extensions: the values that JSON cannot write. */
 const STD_EXT = {
@@ -3344,7 +3441,7 @@ function valuesOf(parts, ctx, rt) {
 	}
 	return values;
 }
-function partsOf(value) {
+function partsOf$1(value) {
 	return isRecord(value) ? value : {};
 }
 const LIT_SUMMARY = "A literal: its value is the result.";
@@ -3408,7 +3505,14 @@ function formulaKinds() {
 			verbs: { eval: "formula.fn" },
 			parts: {
 				shape: "record",
-				fields: { body: term },
+				fields: {
+					params: {
+						shape: "list",
+						item: { shape: "text" },
+						distinct: true
+					},
+					body: term
+				},
 				required: ["params", "body"]
 			},
 			scope: [{
@@ -3531,18 +3635,19 @@ function formulaEvaluators(profile = {}) {
 				if (missing !== void 0 && missing(reached)) return fail("#N/A", "The path reaches no value.");
 				return ok(reached);
 			};
-			const computed = parts.length > 0;
+			const held = (ctx) => {
+				if (head === void 0 || !Object.hasOwn(ctx.names, head)) return void 0;
+				const bound = ctx.names[head];
+				return bound instanceof Held ? {
+					ok: false,
+					error: bound.error
+				} : void 0;
+			};
+			if (parts.length === 0) return (ctx, rt) => held(ctx) ?? give(rt.resolve(ctx, path));
 			return (ctx, rt) => {
-				if (head !== void 0 && Object.hasOwn(ctx.names, head)) {
-					const bound = ctx.names[head];
-					if (bound instanceof Held) return {
-						ok: false,
-						error: bound.error
-					};
-				}
-				if (!computed) return give(rt.resolve(ctx, path));
 				const steps = valuesOf(parts, ctx, rt);
-				return Array.isArray(steps) ? give(rt.resolve(ctx, fill(steps))) : steps;
+				if (!Array.isArray(steps)) return steps;
+				return held(ctx) ?? give(rt.resolve(ctx, fill(steps)));
 			};
 		}),
 		"formula.step": compiled(({ doc, parts, fill }) => {
@@ -3559,7 +3664,7 @@ function formulaEvaluators(profile = {}) {
 			};
 		}),
 		"formula.record": compiled(({ value }) => {
-			const fields = partsOf(value);
+			const fields = partsOf$1(value);
 			const keys = Object.keys(fields);
 			const codes = keys.map((key) => fields[key].code);
 			if (combine !== void 0) {
@@ -3592,8 +3697,8 @@ function formulaEvaluators(profile = {}) {
 			return Array.isArray(values) ? ok(values) : values;
 		}),
 		"formula.let": compiled(({ value }) => {
-			const record = partsOf(value);
-			const bindings = Object.entries(partsOf(record["bind"]));
+			const record = partsOf$1(value);
+			const bindings = Object.entries(partsOf$1(record["bind"]));
 			const body = record["body"];
 			return (ctx, rt) => {
 				const names = { ...ctx.names };
@@ -3614,7 +3719,7 @@ function formulaEvaluators(profile = {}) {
 				return () => bad;
 			}
 			const names = params;
-			const body = partsOf(value)["body"];
+			const body = partsOf$1(value)["body"];
 			return (ctx, rt) => {
 				const closure = (...args) => {
 					const scope = { ...ctx.names };
@@ -3626,12 +3731,12 @@ function formulaEvaluators(profile = {}) {
 					if (!result.ok) throw new Failure(result.error);
 					return result.value;
 				};
-				Object.defineProperty(closure, CLOSURE, { value: { params: names } });
+				Object.defineProperty(closure, CLOSURE$2, { value: { params: names } });
 				return ok(closure);
 			};
 		}),
 		"formula.call": compiled(({ value }) => {
-			const record = partsOf(value);
+			const record = partsOf$1(value);
 			const fnPart = record["fn"];
 			const args = Array.isArray(record["args"]) ? record["args"] : [];
 			return (ctx, rt) => {
@@ -3652,7 +3757,7 @@ function formulaEvaluators(profile = {}) {
 			};
 		}),
 		"formula.if": compiled(({ value }) => {
-			const record = partsOf(value);
+			const record = partsOf$1(value);
 			const test = record["test"];
 			const then = record["then"];
 			const other = record["else"];
@@ -3771,14 +3876,52 @@ function formulaEvaluators(profile = {}) {
 	};
 }
 /**
+* This function makes the hook `known` of the formula kit for one profile (STATIC.KNOWN). The evaluator
+* `formula.op` knows an operation of `lazy` or of `ops`. A profile whose `ops` is a function answers through a call
+* of that function. A function that throws counts as an answer, because the run then gives `#CALC!`. The evaluator
+* `formula.ext` knows an extension of `ext` and each standard extension. The hook knows each name of the other
+* evaluators.
+*
+* @param profile - The operations and the extensions of the language.
+* @returns The hook: `true`, or the reason of the `#NAME?` that the evaluator gives in a run.
+*/
+function formulaKnown(profile = {}) {
+	const hasOp = (name) => {
+		if (profile.lazy !== void 0 && Object.hasOwn(profile.lazy, name)) return true;
+		const ops = profile.ops;
+		if (ops === void 0) return false;
+		if (typeof ops !== "function") return Object.hasOwn(ops, name);
+		try {
+			return ops(name) !== void 0;
+		} catch {
+			return true;
+		}
+	};
+	const hasExt = (name) => profile.ext !== void 0 && Object.hasOwn(profile.ext, name) || Object.hasOwn(STD_EXT, name);
+	return (path, evaluator) => {
+		if (evaluator !== "formula.op" && evaluator !== "formula.ext") return true;
+		const name = path.slice(1).join(".");
+		if (evaluator === "formula.op") return hasOp(name) ? true : `The language has no operation ${name}.`;
+		return hasExt(name) ? true : `The language has no extension ${name}.`;
+	};
+}
+/**
 * This function makes a machine for a formula language. The machine has the kinds and the evaluators of the
-* formula kit. It also has the kinds, the evaluators and the walkers that the language adds.
+* formula kit. It also has the kinds, the evaluators and the walkers that the language adds. Its hook `known` comes
+* from the profile (`formulaKnown`). A hook `known` of the language answers each name that the kit knows.
 *
 * @param profile - The operations and the rules of the language.
 * @param more - The parts of a machine that the language adds. Its kinds win over the kinds of the kit.
 * @returns The machine.
 */
 function formulaMachine(profile = {}, more = {}) {
+	const kit = formulaKnown(profile);
+	const replaced = (name) => more.evaluators !== void 0 && Object.hasOwn(more.evaluators, name) || more.runners !== void 0 && Object.hasOwn(more.runners, name);
+	const theirs = more.known;
+	const known = (path, evaluator) => {
+		const answer = replaced(evaluator) ? true : kit(path, evaluator);
+		return answer === true && theirs !== void 0 ? theirs(path, evaluator) : answer;
+	};
 	return {
 		...more,
 		world: {
@@ -3791,10 +3934,1072 @@ function formulaMachine(profile = {}, more = {}) {
 		evaluators: {
 			...formulaEvaluators(profile),
 			...more.evaluators
+		},
+		known
+	};
+}
+//#endregion
+//#region src/reference.ts
+function own(table, name) {
+	return table !== void 0 && Object.hasOwn(table, name) ? table[name] : void 0;
+}
+/** This function finds the code of an evaluator name. A runner wins over an evaluator of the same name. */
+function choose(env, name) {
+	const runner = own(env.machine.runners, name);
+	if (runner !== void 0) {
+		const defined = own(env.definitions.runners, name);
+		if (defined !== void 0) return { runner: defined };
+		return typeof runner === "function" ? { runner } : { gap: `The reference has no definition of the compiled runner ${name}.` };
+	}
+	const evaluator = own(env.machine.evaluators, name);
+	if (evaluator === void 0) return void 0;
+	const defined = own(env.definitions.evaluators, name);
+	if (defined !== void 0) return { evaluator: defined };
+	return typeof evaluator === "function" ? { evaluator } : { gap: `The reference has no definition of the compiled evaluator ${name}.` };
+}
+/**
+* This function reads one document by the rules, in their order. First come an envelope or a declared type
+* (EVAL.ERRORS) and the limit of the depth (PLAN.DEPTH). Then come the ladder (LADDER.*), an evaluator and the shape
+* of the parts (SHAPE.*).
+*/
+function examine(env, at) {
+	const { place, declared } = at;
+	const world = env.machine.world;
+	const read = partsOf(world, at.value, declared);
+	if (!read.ok) return fail(read.code, read.reason, { place });
+	if (at.depth > env.maxDepth) return fail("#DEPTH!", `The nesting is deeper than ${env.maxDepth} documents.`, { place });
+	const { doc, kind, split } = read;
+	const kindText = typeName(doc.type);
+	const answer = ask(world, read.declared ? {} : doc, "eval", declared === void 0 ? {} : { declaredType: declared });
+	if (answer.error === "unknown-kind") return fail("#KIND?", `The world has no kind ${kindText}.`, { place });
+	const name = answer.evaluator;
+	const chosen = name === void 0 ? void 0 : choose(env, name);
+	if (name === void 0 || chosen === void 0) return fail("#NOEVAL", `No rung gives an evaluator for ${kindText}.`, { place });
+	if (!split.ok) return fail("#VALUE!", split.reason, { place });
+	return {
+		doc,
+		kindText,
+		typePath: read.typePath ?? [],
+		kind,
+		name,
+		chosen,
+		split
+	};
+}
+/** This function gives the capabilities that the rules of a kind give one part (D14, CAP.CONTRACT, CAP.ONLY). */
+function capsOfPart(rules, path, caps) {
+	let out = caps;
+	for (const rule of rules ?? []) {
+		if (rule.in !== void 0 && !rule.in.some((pattern) => pathMatches(path, pattern))) continue;
+		if (rule.rule === "mask") return [];
+		if (rule.rule === "only") out = intersectCaps(out, rule.caps);
+	}
+	return out;
+}
+/**
+* This function gives the context of a part. A context that the evaluator gives keeps only the capabilities of the
+* parent (CAP.NARROW). Then the rules of the kind narrow it (CAP.CONTRACT).
+*/
+function contextOfPart(seen, slot, parent, given) {
+	const base = given === void 0 || given === parent ? parent : {
+		...given,
+		caps: given.caps.filter((cap) => permits(parent.caps, cap))
+	};
+	const caps = capsOfPart(seen.kind?.caps, slot.path, base.caps);
+	return caps === base.caps ? base : {
+		...base,
+		caps
+	};
+}
+function headerOf(item) {
+	return isEnvelope(item) && typeof item.name === "string" ? item.name : void 0;
+}
+function partAt(seen, at, slot, given) {
+	return {
+		value: slot.item,
+		place: at.place.concat(slot.path),
+		declared: slot.of,
+		depth: at.depth + 1,
+		address: slot.address === true,
+		ctx: contextOfPart(seen, slot, at.ctx, given)
+	};
+}
+/** This function resolves a path with the full algorithm of `resolve`, not with its short path (DEREF.QUICK). */
+function resolveFully(machine, ctx, path, options) {
+	const found = resolve(machine, ctx, path, { hops: true });
+	return options?.hops === true ? found : {
+		...found,
+		hops: []
+	};
+}
+/** This function records an effect when the capabilities permit it (RUN.CAP, CAP.HOOK). */
+function record(env, ctx, kind, payload, place) {
+	const keys = typeof kind === "string" ? kind.split(".") : kind;
+	const text = keys.join(".");
+	const machine = env.machine;
+	if (!(machine.permits === void 0 ? permits(ctx.caps, keys) : machine.permits(ctx.caps, keys, ctx))) return fail("#CAP!", `The context has no capability for the effect ${text}.`, { place });
+	env.effects.push({
+		index: env.effects.length,
+		kind: text,
+		path: keys,
+		payload,
+		node: -1,
+		at: 0,
+		place,
+		context: ctx
+	});
+}
+/** This function evaluates a document. Each error gets the place of the document where it started (K5). */
+function evaluateAt(env, at) {
+	const seen = examine(env, at);
+	if (!("doc" in seen)) return seen;
+	return evaluateSeen(env, seen, at);
+}
+function evaluateSeen(env, seen, at) {
+	const { chosen } = seen;
+	const { place } = at;
+	if ("gap" in chosen) return fail("#NOEVAL", chosen.gap, { place });
+	if ("runner" in chosen) return drive(runSeen(env, seen, at, chosen.runner), place);
+	const input = evalInput(env, seen, at);
+	try {
+		return placed(chosen.evaluator(input), place);
+	} catch (error) {
+		return placed(thrown(error, `the evaluator ${seen.name}`), place);
+	}
+}
+/** This function gives the steps of a document for a runner. Nothing happens before the first step. */
+function* stepsAt(env, at) {
+	const seen = examine(env, at);
+	if (!("doc" in seen)) return seen;
+	if ("runner" in seen.chosen) return yield* runSeen(env, seen, at, seen.chosen.runner);
+	return evaluateSeen(env, seen, at);
+}
+function* runSeen(env, seen, at, runner) {
+	try {
+		return placed(yield* runner(runInput(env, seen, at)), at.place);
+	} catch (error) {
+		return placed(thrown(error, `the runner ${seen.name}`), at.place);
+	}
+}
+/** This function drives steps that cannot wait. A step that waits gives `#CALC!` at the document (RUN.WAIT). */
+function drive(steps, place) {
+	const step = steps.next();
+	if (step.done === true) return step.value;
+	step.value.catch(() => void 0);
+	const waited = fail("#CALC!", "A part waited, and its parent cannot wait.", { place });
+	steps.return(waited);
+	return waited;
+}
+function evalInput(env, seen, at) {
+	const { split, doc } = seen;
+	const parts = split.parts.map((slot) => {
+		const name = headerOf(slot.item);
+		return {
+			key: slot.key,
+			path: slot.path,
+			...name === void 0 ? {} : { name },
+			evaluate: (given) => evaluateAt(env, partAt(seen, at, slot, given))
+		};
+	});
+	const fill = (items) => split.parts.length === 0 ? doc.value : split.fill(items);
+	return {
+		kind: seen.kindText,
+		typePath: seen.typePath,
+		doc,
+		value: fill(parts),
+		data: split.data,
+		parts,
+		context: at.ctx,
+		place: at.place,
+		...at.address ? { address: true } : {},
+		resolve: (path, options) => resolveFully(env.machine, at.ctx, path, options),
+		effect: (kind, payload) => record(env, at.ctx, kind, payload, at.place) ?? ok(payload),
+		fill
+	};
+}
+function runInput(env, seen, at) {
+	const { split, doc } = seen;
+	const parts = split.parts.map((slot) => {
+		const name = headerOf(slot.item);
+		return {
+			key: slot.key,
+			path: slot.path,
+			...name === void 0 ? {} : { name },
+			evaluate: (given) => stepsAt(env, partAt(seen, at, slot, given))
+		};
+	});
+	const fill = (items) => split.parts.length === 0 ? doc.value : split.fill(items);
+	return {
+		kind: seen.kindText,
+		typePath: seen.typePath,
+		doc,
+		value: fill(parts),
+		data: split.data,
+		parts,
+		context: at.ctx,
+		place: at.place,
+		resolve: (path, options) => resolveFully(env.machine, at.ctx, path, options),
+		effect: function* (kind, payload) {
+			return record(env, at.ctx, kind, payload, at.place) ?? ok(payload);
+		},
+		all: (list, options) => together(list, options),
+		fill
+	};
+}
+/**
+* This function evaluates parts for `all` (RUN.ALL). The parts start in their order, up to the limit, and each part
+* goes on until it ends or waits. In an evaluation, a part that waits does not end, thus it keeps its place in the
+* limit. With `failFast`, the first failure stops the parts that wait, and the later parts do not start
+* (RUN.FAIL-FAST). When no part failed and a part waits, the steps wait, and the drive gives `#CALC!`.
+*/
+function* together(list, options = {}) {
+	const limit = Math.max(1, options.concurrency ?? list.length);
+	const results = list.map(() => void 0);
+	const waiting = [];
+	let failed = false;
+	for (let index = 0; index < list.length && !failed && waiting.length < limit; index += 1) {
+		let result;
+		try {
+			const steps = list[index].evaluate();
+			const step = steps.next();
+			if (step.done === true) result = step.value;
+			else waiting.push({
+				steps,
+				promise: step.value
+			});
+		} catch (error) {
+			result = thrown(error, "a part");
 		}
+		results[index] = result;
+		if (result !== void 0 && options.failFast === true && !result.ok) failed = true;
+	}
+	if (failed) {
+		const stopped = fail("#ABORT", "The part stopped: a part before it failed, and the parts run with failFast.");
+		for (const item of waiting) try {
+			item.steps.return(stopped);
+		} catch {}
+		return results.map((result) => result ?? stopped);
+	}
+	if (waiting.length > 0) yield Promise.race(waiting.map((item) => item.promise));
+	return results;
+}
+/**
+* This function evaluates a document by the rules, without a compilation. It is the reference of the plans: a plan,
+* a traced plan and the second tier of a language must give its results. It covers evaluations, not runs: an effect
+* gives its payload, and a part that waits gives `#CALC!`.
+*
+* @param machine - The world and the code of the evaluators.
+* @param doc - The document.
+* @param context - The names and the capabilities at the root.
+* @param options - The type of a bare root value, the definitions of compiled code, and a list for the effects.
+* @returns The result.
+*/
+function reference(machine, doc, context = makeContext(), options = {}) {
+	const env = {
+		machine,
+		definitions: options.definitions ?? {},
+		effects: options.effects ?? [],
+		maxDepth: machine.maxDepth ?? 1e3
 	};
+	const ctx = context.world === null ? {
+		...context,
+		world: worldThing(machine.world)
+	} : context;
+	try {
+		return evaluateAt(env, {
+			value: doc,
+			place: [],
+			declared: options.declaredType,
+			depth: 0,
+			address: false,
+			ctx
+		});
+	} catch (error) {
+		return placed(thrown(error, "the reference"), []);
+	}
+}
+const CLOSURE$1 = Symbol.for("coeval.closure");
+/** This function sets an own field, also the field `__proto__` (SHAPE.PROTO). */
+function setField(target, key, value) {
+	Object.defineProperty(target, key, {
+		value,
+		enumerable: true,
+		writable: true,
+		configurable: true
+	});
+}
+function partNamed(parts, key) {
+	return parts.find((part) => part.path.length === 1 && part.path[0] === key);
+}
+function partsUnder(parts, key) {
+	return parts.filter((part) => part.path.length === 2 && part.path[0] === key);
+}
+/**
+* This function gives the definitions of the formula kit for one profile. Each construct is a function evaluator in
+* the most direct style. It shares no code with the compilers of `formulaEvaluators`, thus the two readings of the
+* rules can disagree, and a test finds it.
+*
+* @param profile - The operations and the rules of the language.
+* @returns The definitions, by evaluator name.
+*/
+function formulaDefinitions(profile = {}) {
+	const truthy = profile.truthy ?? ((value) => typeof value === "boolean" ? value : void 0);
+	const opOf = (name) => typeof profile.ops === "function" ? profile.ops(name) : own(profile.ops, name);
+	const noTruth = (what) => fail("#VALUE!", `The ${what} must give a truth value.`);
+	/** FORMULA.LIST, FORMULA.OPS and FORMULA.COMBINE: the values of parts in order, or the error. */
+	const valuesOf = (parts, skip) => {
+		const values = [];
+		const errors = [];
+		for (const part of parts) {
+			const result = part.evaluate();
+			if (result.ok) values.push(result.value);
+			else if (skip?.(result.error) === true) values.push(SKIP);
+			else if (profile.combine === void 0) return result;
+			else errors.push(result.error);
+		}
+		if (errors.length === 0 || profile.combine === void 0) return { values };
+		return {
+			ok: false,
+			error: errors.length === 1 ? errors[0] : profile.combine(errors)
+		};
+	};
+	const lit = ({ doc }) => ok(doc.value);
+	const ref = ({ doc, parts, fill, address, context, resolve: walk }) => {
+		const path = doc.value;
+		if (!Array.isArray(path) || path.length === 0) return fail("#VALUE!", "The value of ref is a path: a list that starts with a root, for example [\"names\", \"a\"].");
+		let steps = path;
+		if (parts.length > 0) {
+			const all = valuesOfStrict(parts);
+			if (!("values" in all)) return all;
+			steps = fill(all.values);
+		}
+		const head = path[0] === "names" && typeof path[1] === "string" ? path[1] : void 0;
+		const bound = head === void 0 ? void 0 : own(context.names, head);
+		if (bound instanceof Held) return {
+			ok: false,
+			error: bound.error
+		};
+		const found = walk(steps);
+		if (!found.ok) return fail(found.code, found.reason);
+		if (address === true) return ok(found.thing);
+		const reached = valueOfThing(found.thing);
+		if (reached instanceof Held) return {
+			ok: false,
+			error: reached.error
+		};
+		if (profile.missing?.(reached) === true) return fail("#N/A", "The path reaches no value.");
+		return ok(reached);
+	};
+	const step = ({ doc, parts, fill }) => {
+		if (parts.length === 0) return ok(doc);
+		const all = valuesOfStrict(parts);
+		return "values" in all ? ok({
+			...doc,
+			value: fill(all.values)
+		}) : all;
+	};
+	const record = ({ parts }) => {
+		const all = valuesOf(parts, profile.omit);
+		if (!("values" in all)) return all;
+		const out = {};
+		parts.forEach((part, index) => {
+			const value = all.values[index];
+			if (value !== SKIP) setField(out, String(part.path[0]), value);
+		});
+		return ok(out);
+	};
+	const list = ({ parts }) => {
+		const all = valuesOf(parts);
+		return "values" in all ? ok([...all.values]) : all;
+	};
+	const letIn = ({ parts, context }) => {
+		const names = {};
+		for (const key of Object.keys(context.names)) setField(names, key, context.names[key]);
+		for (const binding of partsUnder(parts, "bind")) {
+			const result = binding.evaluate();
+			setField(names, String(binding.path[1]), result.ok ? result.value : new Held(result.error));
+		}
+		return partNamed(parts, "body").evaluate({
+			...context,
+			names
+		});
+	};
+	const fn = ({ data, parts, context }) => {
+		const params = isRecord(data) ? data["params"] : void 0;
+		if (!Array.isArray(params) || !params.every((param) => typeof param === "string") || new Set(params).size !== params.length) return fail("#VALUE!", "The params of fn are a list of different texts.");
+		const names = params;
+		const body = partNamed(parts, "body");
+		const closure = (...args) => {
+			const scope = {};
+			for (const key of Object.keys(context.names)) setField(scope, key, context.names[key]);
+			names.forEach((name, index) => setField(scope, name, args[index]));
+			const result = body.evaluate({
+				...context,
+				names: scope
+			});
+			if (!result.ok) throw new Failure(result.error);
+			return result.value;
+		};
+		Object.defineProperty(closure, CLOSURE$1, { value: { params: names } });
+		return ok(closure);
+	};
+	const call = ({ parts }) => {
+		const target = partNamed(parts, "fn").evaluate();
+		if (!target.ok) return target;
+		if (typeof target.value !== "function") return fail("#VALUE!", "The fn of call must give a function.");
+		const all = valuesOfStrict(partsUnder(parts, "args"));
+		if (!("values" in all)) return all;
+		try {
+			return ok(target.value(...all.values));
+		} catch (error) {
+			return thrown(error, "the function of call");
+		}
+	};
+	const choice = ({ parts }) => {
+		const test = partNamed(parts, "test").evaluate();
+		if (!test.ok) return test;
+		const truth = truthy(test.value);
+		if (truth === void 0) return noTruth("test of if");
+		if (truth) return partNamed(parts, "then").evaluate();
+		const other = partNamed(parts, "else");
+		if (other !== void 0) return other.evaluate();
+		return ok(Object.hasOwn(profile, "otherwise") ? profile.otherwise : null);
+	};
+	/** FORMULA.LOGIC: `and` stops at the first false term, and `or` at the first true term. */
+	const logic = (stopAt, what) => ({ parts }) => {
+		let last = ok(!stopAt);
+		for (const part of parts) {
+			last = part.evaluate();
+			if (!last.ok) return last;
+			const truth = truthy(last.value);
+			if (truth === void 0) return noTruth(what);
+			if (truth === stopAt) return profile.logic === "value" ? last : ok(stopAt);
+		}
+		return profile.logic === "value" ? last : ok(!stopAt);
+	};
+	const op = ({ typePath, parts }) => {
+		const name = typePath.slice(1).join(".");
+		const lazy = own(profile.lazy, name);
+		if (lazy !== void 0) try {
+			return lazy(parts.map((part) => () => part.evaluate()));
+		} catch (error) {
+			return thrown(error, `the operation ${name}`);
+		}
+		const apply = opOf(name);
+		if (apply === void 0) return fail("#NAME?", `The language has no operation ${name}.`);
+		const all = valuesOf(parts);
+		if (!("values" in all)) return all;
+		try {
+			const out = apply(...all.values);
+			return profile.check?.(out, name) ?? ok(out);
+		} catch (error) {
+			return thrown(error, `the operation ${name}`);
+		}
+	};
+	const ext = ({ typePath, doc, context }) => {
+		const name = typePath.slice(1).join(".");
+		const handler = own(profile.ext, name) ?? own(STD_EXT, name);
+		if (handler === void 0) return fail("#NAME?", `The language has no extension ${name}.`);
+		try {
+			return handler(doc.value, context);
+		} catch (error) {
+			return thrown(error, `the extension ${name}`);
+		}
+	};
+	return { evaluators: {
+		"formula.lit": lit,
+		"formula.ref": ref,
+		"formula.step": step,
+		"formula.record": record,
+		"formula.list": list,
+		"formula.let": letIn,
+		"formula.fn": fn,
+		"formula.call": call,
+		"formula.if": choice,
+		"formula.and": logic(false, "term of and"),
+		"formula.or": logic(true, "term of or"),
+		"formula.op": op,
+		"formula.ext": ext
+	} };
+}
+/** The mark of a field that the profile leaves out of a record (FORMULA.RECORD). */
+const SKIP = Symbol("skip");
+/** The values of parts in order. The first error stops them, also with `combine` (FORMULA.STEPS, FORMULA.FN). */
+function valuesOfStrict(parts) {
+	const values = [];
+	for (const part of parts) {
+		const result = part.evaluate();
+		if (!result.ok) return result;
+		values.push(result.value);
+	}
+	return { values };
+}
+//#endregion
+//#region src/agree.ts
+/**
+* This function tells if two values are the same for `agree`. Lists and plain records compare item by item and field
+* by field, and the order of the fields does not matter. Each other leaf compares with `Object.is`, thus `-0` is not
+* `0`, and `NaN` is `NaN`. The identity of a list or of a plain record is not compared.
+*
+* Two closures of `fn` are the same when they have the same parameters. Two `Held` values are the same when their
+* errors have the same code and place. Each other object is the same only as itself, unless the rule of the caller
+* tells otherwise.
+*
+* `docEquals` uses the same rules for lists, plain records and the other objects. It has no rules for closures, for
+* `Held` values and for a rule of the caller. Thus two closures are equal there only when they are the same function.
+*
+* @param a - The first value.
+* @param b - The second value.
+* @param equal - The rule of the caller for other values. It answers first, and `undefined` gives the rules above.
+* @returns `true` when the values are the same.
+*/
+function sameValue(a, b, equal) {
+	const stack = [[a, b]];
+	const seen = /* @__PURE__ */ new Map();
+	while (stack.length > 0) {
+		const [x, y] = stack.pop();
+		if (Object.is(x, y)) continue;
+		const told = equal?.(x, y);
+		if (told !== void 0) {
+			if (told) continue;
+			return false;
+		}
+		if (typeof x !== "object" && typeof x !== "function") return false;
+		if (typeof y !== "object" && typeof y !== "function") return false;
+		if (x === null || y === null) return false;
+		const pairs = seen.get(x) ?? /* @__PURE__ */ new Set();
+		if (pairs.has(y)) continue;
+		pairs.add(y);
+		seen.set(x, pairs);
+		if (isClosure(x) || isClosure(y)) {
+			if (!(isClosure(x) && isClosure(y))) return false;
+			stack.push([closureParams(x), closureParams(y)]);
+			continue;
+		}
+		if (x instanceof Held || y instanceof Held) {
+			if (!(x instanceof Held && y instanceof Held) || errorDiffers(x.error, y.error, false) !== void 0) return false;
+			continue;
+		}
+		if (Array.isArray(x) || Array.isArray(y)) {
+			if (!Array.isArray(x) || !Array.isArray(y) || x.length !== y.length) return false;
+			for (let index = 0; index < x.length; index += 1) stack.push([x[index], y[index]]);
+			continue;
+		}
+		if (!isRecord(x) || !isRecord(y)) return false;
+		const keys = Object.keys(x);
+		if (keys.length !== Object.keys(y).length) return false;
+		for (const key of keys) {
+			if (!Object.hasOwn(y, key)) return false;
+			stack.push([x[key], y[key]]);
+		}
+	}
+	return true;
+}
+const CLOSURE = Symbol.for("coeval.closure");
+function closureParams(fn) {
+	return fn[CLOSURE]?.params;
+}
+function codeAndPlace(error) {
+	return error.place === void 0 ? error.code : `${error.code} at [${error.place.join(", ")}]`;
+}
+/** This function gives the difference of two errors, or `undefined` when they agree. */
+function errorDiffers(a, b, strict) {
+	if (a.code !== b.code) return `The plan gives ${codeAndPlace(a)}, and the tier gives ${codeAndPlace(b)}.`;
+	if (strict && (a.place === void 0 || b.place === void 0)) return `An error ${a.code} has no place.`;
+	if (a.place !== void 0 && b.place !== void 0 && !docEquals(a.place, b.place)) return `The error ${a.code} has the place [${a.place.join(", ")}] in the plan, and [${b.place.join(", ")}] in the tier.`;
+	if (strict && a.reason !== b.reason) return `The error ${a.code} has another reason in the tier: "${b.reason}" for "${a.reason}".`;
+}
+/** A host stack overflow is the one permitted difference (VALUE.DEPTH): the tiers use different numbers of frames. */
+function overflowed(result) {
+	return !result.ok && result.error.code === "#DEPTH!" && isStackOverflow(result.error.cause);
+}
+/** This function gives the difference of two results, or `undefined` when they agree. */
+function resultDiffers(a, b, options) {
+	if (a.ok && b.ok) return sameValue(a.value, b.value, options.equal) ? void 0 : "The plan and the tier give different values.";
+	if (!a.ok && !b.ok) return errorDiffers(a.error, b.error, options.strict === true);
+	return a.ok ? `The plan gives a value, and the tier gives ${codeAndPlace(b.error)}.` : `The plan gives ${codeAndPlace(a.error)}, and the tier gives a value.`;
+}
+/** This function gives the difference of two lists of effects, or `undefined` when they agree (EFFECT.ORDER). */
+function effectsDiffer(a, b, options) {
+	if (a.length !== b.length) return `The plan causes ${a.length} effects, and the tier causes ${b.length}.`;
+	for (let index = 0; index < a.length; index += 1) {
+		const x = a[index];
+		const y = b[index];
+		if (x.kind !== y.kind || !docEquals(x.place, y.place) || !sameValue(x.payload, y.payload, options.equal)) return `The effect ${index} differs: ${x.kind} at [${x.place.join(", ")}] in the plan, and ${y.kind} at [${y.place.join(", ")}] in the tier.`;
+	}
+}
+/**
+* This function evaluates a document with a plan and with other tiers, and compares the results (PLAN.AGREES). Two
+* results agree when they have the same value by `sameValue`, or errors with the same code, and the same place when
+* both have one. The effects must have the same kinds, places and payloads, in the same order. A language gives its
+* own tier with the option `other`.
+*
+* @param machine - The world and the code of the evaluators.
+* @param doc - The document.
+* @param context - The names and the capabilities at the root.
+* @param options - The tiers, the definitions for the reference, the rules of the comparison and the second tier.
+* @returns The result of the plan, or the first tier that disagrees and the reason.
+*/
+function agree(machine, doc, context = makeContext(), options = {}) {
+	const declared = options.declaredType === void 0 ? {} : { declaredType: options.declaredType };
+	const observe = options.observe;
+	observe?.();
+	const plan = prepare(machine, doc, declared);
+	const effects = [];
+	const result = plan.evaluate(context, { effects });
+	const saw = observe?.();
+	const differs = (other, otherEffects) => {
+		if (overflowed(result) || overflowed(other)) return void 0;
+		const why = resultDiffers(result, other, options) ?? (otherEffects === void 0 ? void 0 : effectsDiffer(effects, otherEffects, options));
+		if (why !== void 0 || observe === void 0) return why;
+		return sameValue(saw, observe(), options.equal) ? void 0 : "The host saw other calls in the tier.";
+	};
+	for (const tier of options.tiers ?? [
+		"reference",
+		"traced",
+		"again"
+	]) {
+		let other;
+		let otherEffects = [];
+		if (tier === "reference") other = reference(machine, doc, context, {
+			...declared,
+			effects: otherEffects,
+			...options.definitions === void 0 ? {} : { definitions: options.definitions }
+		});
+		else if (tier === "traced") {
+			const traced = evaluate(machine, doc, context, options.declaredType);
+			other = traced.result;
+			otherEffects = [...traced.effects];
+		} else other = plan.evaluate(context, { effects: otherEffects });
+		const why = differs(other, otherEffects);
+		if (why !== void 0) return {
+			ok: false,
+			tier,
+			plan: result,
+			other,
+			reason: why
+		};
+	}
+	if (options.other !== void 0) {
+		let given;
+		try {
+			given = options.other(doc, context);
+		} catch (error) {
+			given = thrown(error, "the tier");
+		}
+		const other = "result" in given ? given.result : given;
+		const why = differs(other, "result" in given ? given.effects : void 0);
+		if (why !== void 0) return {
+			ok: false,
+			tier: "other",
+			plan: result,
+			other,
+			reason: why
+		};
+	}
+	return {
+		ok: true,
+		result,
+		effects
+	};
+}
+//#endregion
+//#region src/generate.ts
+/**
+* This function makes a source of random numbers with a seed (the algorithm mulberry32). It needs no package.
+*
+* @param seed - The seed: a whole number.
+* @returns The source.
+*/
+function random(seed) {
+	let state = seed >>> 0;
+	const next = () => {
+		state = state + 1831565813 >>> 0;
+		let t = state;
+		t = Math.imul(t ^ t >>> 15, t | 1);
+		t ^= t + Math.imul(t ^ t >>> 7, t | 61);
+		return ((t ^ t >>> 14) >>> 0) / 4294967296;
+	};
+	const int = (below) => Math.floor(next() * below);
+	return {
+		next,
+		int,
+		chance: (p) => next() < p,
+		pick: (items) => items[int(items.length)]
+	};
+}
+/**
+* This function lists the types of a world: each kind and each alias, also in a namespace. A namespace with a
+* fallback gives no types, because each key names a kind.
+*
+* @param world - The world.
+* @returns The keys of each type.
+*/
+function typesOf(world) {
+	const out = [];
+	const visit = (entries, prefix) => {
+		for (const key of Object.keys(entries)) {
+			const entry = entries[key];
+			if (isKind(entry) || isAlias(entry)) out.push([...prefix, key]);
+			else if (isNamespace(entry)) visit(entry.kinds, [...prefix, key]);
+		}
+	};
+	visit(world.kinds, []);
+	return out;
+}
+const NAMES = [
+	"a",
+	"b",
+	"x",
+	"n",
+	"last",
+	"__proto__"
+];
+const FIELDS = [
+	"a",
+	"b",
+	"c",
+	"1",
+	"__proto__"
+];
+const KEYS = [
+	"a",
+	"b",
+	"x",
+	0,
+	1,
+	"0",
+	"length",
+	"type",
+	"value",
+	"parent"
+];
+/** This function tells if a kind can be a leaf: it needs no part. */
+function leafKind(kind) {
+	const shape = kind?.parts;
+	return shape === void 0 || shape.shape === "none" || shape.shape === "list" || shape.shape === "map" || shape.shape === "text" || shape.shape === "number" || shape.shape === "one";
+}
+/**
+* This function builds a random document for a world from the contracts of its kinds. It reads the shapes of the
+* parts, the declared types, the permitted kinds and the names that the scope rules bind. Some choices are malformed
+* on purpose, for example an unknown kind or an unknown name under a namespace with a fallback. Other examples are a
+* value without its shape, a bare value without a type and a name that nothing binds. The depth and the size have
+* limits.
+*
+* @param world - The world.
+* @param options - The seed, the types, the limits and the data of the leaves.
+* @returns The document, as JSON.
+*/
+function generate(world, options) {
+	const rng = random(options.seed);
+	const types = options.types ?? typesOf(world);
+	const maxDepth = options.maxDepth ?? 4;
+	const maxSize = options.maxSize ?? 24;
+	const malformed = options.malformed ?? .05;
+	const keys = options.keys ?? KEYS;
+	const stepTypes = types.filter((type) => {
+		const found = lookupKind(world, type);
+		return found.ok && Object.hasOwn(found.kind.verbs, "step");
+	});
+	const unknownNames = Object.keys(world.kinds).filter((key) => {
+		const entry = world.kinds[key];
+		return isNamespace(entry) && entry.fallback !== void 0;
+	}).map((key) => [key, "nope"]);
+	let size = 0;
+	const kindOf = (type) => {
+		const found = lookupKind(world, type);
+		return found.ok ? found.kind : void 0;
+	};
+	const anyJson = (depth = 0) => {
+		const roll = rng.int(depth > 1 ? 6 : 8);
+		if (roll === 0) return null;
+		if (roll === 1) return rng.chance(.5);
+		if (roll === 2) return rng.pick([
+			0,
+			1,
+			2,
+			-1,
+			.5,
+			1e21
+		]);
+		if (roll === 3) return rng.pick([
+			"",
+			"a",
+			"text",
+			"0"
+		]);
+		if (roll === 4) return rng.int(10);
+		if (roll === 5) return rng.pick(NAMES);
+		if (roll === 6) return Array.from({ length: rng.int(3) }, () => anyJson(depth + 1));
+		const out = {};
+		for (let index = rng.int(3); index > 0; index -= 1) Object.defineProperty(out, rng.pick(FIELDS), {
+			value: anyJson(depth + 1),
+			enumerable: true,
+			writable: true,
+			configurable: true
+		});
+		return out;
+	};
+	const dataOf = (type) => options.data?.(type, rng) ?? anyJson();
+	const renderType = (type) => {
+		const roll = rng.next();
+		if (roll < .06) return {
+			type: "ref",
+			value: ["world", ...type]
+		};
+		if (type.length === 1 && roll < .8) return type[0];
+		return [...type];
+	};
+	const permitted = (type, kinds) => kinds === void 0 || kinds.some((kind) => kind.length <= type.length && kind.every((key, index) => String(key) === String(type[index])));
+	const pickName = (names) => names.length === 0 || rng.chance(malformed) ? rng.pick(["unbound", "zz"]) : rng.pick(names);
+	const someNames = () => {
+		const out = /* @__PURE__ */ new Set();
+		for (let index = 1 + rng.int(2); index > 0; index -= 1) out.add(rng.pick(NAMES));
+		return [...out];
+	};
+	const envelope = (type, value, header) => {
+		const out = {
+			type: renderType(type),
+			value
+		};
+		if (header !== void 0) out["name"] = header;
+		if (options.own !== void 0 && options.own.length > 0 && rng.chance(.03)) out["own"] = { eval: rng.pick(options.own) };
+		return out;
+	};
+	/** A path from a root (D10). It uses the names in scope, and sometimes a step document. */
+	const pathFor = (pos, refKind) => {
+		if (rng.chance(malformed)) return rng.pick([
+			"names",
+			[],
+			{ names: "a" },
+			["nowhere", "a"]
+		]);
+		const root = pos.names.length > 0 && rng.chance(.75) ? "names" : rng.pick(ROOTS.filter((name) => name !== "names"));
+		const path = [root];
+		if (root === "names") path.push(pickName(pos.names));
+		if (root === "world") path.push(String(rng.pick(types)[0]));
+		for (let index = rng.int(3); index > 0; index -= 1) if (stepTypes.length > 0 && rng.chance(.2)) {
+			const type = rng.pick(stepTypes);
+			const kind = kindOf(type);
+			const value = refKind?.parts?.shape === "deep" && kind?.parts !== void 0 ? valueOf(kind.parts, [], {
+				...pos,
+				depth: pos.depth + 1
+			}, emptyScope()) : dataOf(type);
+			path.push({
+				type: renderType(type),
+				value
+			});
+		} else path.push(rng.pick(keys));
+		return path;
+	};
+	const emptyScope = () => ({
+		rules: [],
+		names: [],
+		covered: [],
+		sources: /* @__PURE__ */ new Map()
+	});
+	/** This function decides the names of the scope rules before the parts, so that each part knows what it sees. */
+	const scopeOf = (kind) => {
+		const rules = kind.scope ?? [];
+		const scope = {
+			rules,
+			names: [],
+			covered: rules.map(() => 0),
+			sources: /* @__PURE__ */ new Map()
+		};
+		for (const rule of rules) {
+			const source = rule.names;
+			let names = [];
+			if ("fixed" in source) names = [...source.fixed];
+			else if ("keysAt" in source) {
+				names = someNames();
+				scope.sources.set(source.keysAt.join("."), { keys: names });
+			} else if ("listAt" in source) {
+				names = someNames();
+				scope.sources.set(source.listAt.join("."), { list: rng.chance(malformed) ? [...names, ...names] : names });
+			} else if ("textAt" in source) {
+				names = [rng.pick(NAMES)];
+				scope.sources.set(source.textAt.join("."), { text: names[0] });
+			}
+			scope.names.push(names);
+		}
+		return scope;
+	};
+	/** The names that a part sees from the scope rules of its parent. A rule `sequential` shows only earlier names. */
+	const seenBy = (scope, path) => {
+		const names = [];
+		let headers = false;
+		scope.rules.forEach((rule, index) => {
+			if (!rule.in.some((pattern) => pathMatches(path, pattern))) return;
+			const ruleNames = scope.names[index] ?? [];
+			if ("headers" in rule.names) headers = true;
+			if (rule.sequential !== true || "headers" in rule.names || (scope.covered[index] ?? 0) > 0) names.push(...ruleNames);
+		});
+		return {
+			names,
+			headers
+		};
+	};
+	/** This function records the part at a path, and the header name that it got, for the rules that cover it. */
+	const saw = (scope, path, part) => {
+		const header = isEnvelope(part) && typeof part.name === "string" ? part.name : void 0;
+		scope.rules.forEach((rule, index) => {
+			if (!rule.in.some((pattern) => pathMatches(path, pattern))) return;
+			scope.covered[index] = (scope.covered[index] ?? 0) + 1;
+			if ("headers" in rule.names && header !== void 0) scope.names[index]?.push(header);
+		});
+	};
+	const partAt = (pos, scope, path, spec, parentType) => {
+		const seen = seenBy(scope, path);
+		const header = seen.headers && rng.chance(.5) ? rng.pick(NAMES) : void 0;
+		const part = docAt({
+			declared: spec.of,
+			kinds: "kinds" in spec ? spec.kinds : void 0,
+			names: seen.names.length === 0 ? pos.names : [...pos.names, ...seen.names],
+			depth: pos.depth + 1,
+			hint: parentType === void 0 ? void 0 : options.hints?.(parentType, path)
+		}, header);
+		saw(scope, path, part);
+		return part;
+	};
+	/** This function builds a value of a shape (SHAPE.*). A part is a document at the next depth. */
+	const valueOf = (shape, path, pos, scope, type) => {
+		const source = scope.sources.get(path.join("."));
+		if (source !== void 0 && "list" in source) return [...source.list];
+		if (source !== void 0 && "text" in source) return source.text;
+		const term = (of) => of === void 0 ? { shape: "term" } : {
+			shape: "term",
+			of
+		};
+		const small = () => pos.depth >= maxDepth ? 0 : size >= maxSize ? rng.int(2) : rng.int(4);
+		if (shape === void 0 || shape.shape === "none") return path.length === 0 && type !== void 0 ? dataOf(type) : anyJson();
+		switch (shape.shape) {
+			case "term": return partAt(pos, scope, path, shape, type);
+			case "list": {
+				const items = Array.from({ length: small() }, (_, index) => valueOf(shape.item ?? term(shape.of), [...path, index], pos, scope, type));
+				if (shape.distinct !== true || rng.chance(malformed)) return items;
+				return items.filter((item, index) => !items.slice(0, index).some((before) => docEquals(before, item)));
+			}
+			case "map": {
+				const out = {};
+				const names = source !== void 0 && "keys" in source ? source.keys : Array.from({ length: small() }, () => rng.pick(FIELDS));
+				for (const key of names) Object.defineProperty(out, key, {
+					value: valueOf(shape.item ?? term(shape.of), [...path, key], pos, scope, type),
+					enumerable: true,
+					writable: true,
+					configurable: true
+				});
+				return out;
+			}
+			case "record": {
+				const named = Array.isArray(shape.fields) ? Object.fromEntries(shape.fields.map((name) => [name, term(shape.of)])) : shape.fields;
+				const fieldKeys = /* @__PURE__ */ new Set([...shape.required ?? [], ...Object.keys(named).filter(() => rng.chance(.75))]);
+				if (shape.closed !== true && shape.rest === void 0 && rng.chance(.15)) fieldKeys.add("extra");
+				const ordered = rng.chance(.2) ? [...fieldKeys].reverse() : [...fieldKeys];
+				const out = {};
+				for (const key of ordered) {
+					if (rng.chance(malformed / 2) && (shape.required ?? []).includes(key)) continue;
+					const fieldShape = Object.hasOwn(named, key) ? named[key] : shape.rest;
+					Object.defineProperty(out, key, {
+						value: valueOf(fieldShape, [...path, key], pos, scope, type),
+						enumerable: true,
+						writable: true,
+						configurable: true
+					});
+				}
+				if (shape.closed === true && rng.chance(malformed)) out["stray"] = 1;
+				return out;
+			}
+			case "deep": return rng.chance(.5) ? [partAt(pos, scope, [...path, 0], term(shape.of), type), anyJson()] : {
+				at: partAt(pos, scope, [...path, "at"], term(shape.of), type),
+				data: anyJson()
+			};
+			case "text": return rng.chance(malformed) ? 1 : rng.pick([
+				"",
+				"a",
+				"label"
+			]);
+			case "number": {
+				if (rng.chance(malformed)) return "1";
+				const value = (shape.min ?? -2) + rng.int(5) + (shape.whole === true ? 0 : rng.pick([0, .5]));
+				return shape.max !== void 0 && value > shape.max ? shape.max : value;
+			}
+			case "one": return rng.chance(malformed) ? "other" : rng.pick(shape.values);
+		}
+	};
+	/**
+	* A malformed document: an unknown kind, or an unknown name under a namespace with a fallback. It can also be a
+	* bad shape, a bare value without a type, or a bad reference.
+	*/
+	const brokenAt = (pos) => {
+		const roll = rng.int(5);
+		if (roll === 0 && unknownNames.length > 0 && rng.chance(.5)) {
+			const type = rng.pick(unknownNames);
+			const kind = kindOf(type);
+			return envelope(type, kind?.parts === void 0 ? dataOf(type) : valueOf(kind.parts, [], pos, scopeOf(kind), type));
+		}
+		if (roll === 0) return {
+			type: rng.pick(["nothing", ["no", "such"]]),
+			value: 1
+		};
+		if (roll === 1) return pos.declared === void 0 ? rng.pick([
+			7,
+			"bare",
+			[1]
+		]) : {
+			type: "ref",
+			value: ["names", "unbound"]
+		};
+		if (roll === 2) {
+			const shaped = types.filter((type) => kindOf(type)?.parts !== void 0);
+			if (shaped.length > 0) return envelope(rng.pick(shaped), rng.pick([
+				7,
+				"x",
+				null
+			]));
+		}
+		if (roll === 3) return {
+			type: "ref",
+			value: rng.pick([
+				["names", "unbound"],
+				["nowhere"],
+				"names"
+			])
+		};
+		return {
+			type: rng.pick(types),
+			value: anyJson()
+		};
+	};
+	const docAt = (pos, header) => {
+		size += 1;
+		const leaf = pos.depth >= maxDepth || size >= maxSize;
+		if (rng.chance(malformed)) return brokenAt(pos);
+		if (pos.declared !== void 0 && rng.chance(leaf ? .7 : .3)) {
+			const bare = dataOf([pos.declared]);
+			if (!isEnvelope(bare) || permitted(typePath(bare.type) ?? [], pos.kinds)) return bare;
+		}
+		let candidates = types.filter((type) => permitted(type, pos.kinds) && (!leaf || leafKind(kindOf(type))));
+		if (pos.hint !== void 0 && rng.chance(.6)) {
+			const hinted = candidates.filter((type) => pos.hint?.some((hint) => hint.length === type.length && hint.every((key, index) => key === type[index])));
+			if (hinted.length > 0) candidates = hinted;
+		}
+		if (candidates.length === 0) candidates = [...types];
+		const type = rng.pick(candidates);
+		const kind = kindOf(type);
+		if (type.length === 1 && type[0] === "ref") return envelope(type, pathFor(pos, kind), header);
+		const value = kind === void 0 ? dataOf(type) : valueOf(kind.parts, [], pos, scopeOf(kind), type);
+		return envelope(type, value, header);
+	};
+	return docAt({
+		declared: options.declaredType,
+		kinds: void 0,
+		names: options.names ?? [],
+		depth: 0,
+		hint: void 0
+	});
 }
 //#endregion
-export { CONSTRUCTS, ENVELOPE_KEYS, Failure, Held, PARTS, PART_INFO, ROOTS, RUNGS, STD_CAPS, STD_EVALUATORS, STD_EXT, STD_MACHINE, STD_RUNNERS, STD_WALKERS, STD_WORLD, THING, ask, capKeys, check, checkSteps, classify, context, dataEdges, derefStep, describe, docEquals, effectEdges, entriesAsJson, evaluate, fail, failures, field, flatten, formulaEvaluators, formulaKinds, formulaMachine, fromJson, intersectCaps, isAlias, isAllowedOrder, isClosure, isEnvelope, isHostThing, isKey, isKind, isNamespace, isRecord, isRef, isStackOverflow, isTypeRef, jsTruthy, kindDocument, kindNamed, kindOf, layers, looksLikeKind, lookupKind, makeContext, mapRefs, narrow, nearestWalker, nodeAt, ok, partCaps, pathMatches, permits, placed, planner, prepare, ref, refsOf, resolve, run, splitParts, stored, tag, thrown, toJson, typeName, typePath, typed, valueOfThing, walk, worldThing };
+export { CONSTRUCTS, ENVELOPE_KEYS, Failure, Held, PARTS, PART_INFO, ROOTS, RUNGS, STD_CAPS, STD_EVALUATORS, STD_EXT, STD_MACHINE, STD_RUNNERS, STD_WALKERS, STD_WORLD, THING, agree, ask, capKeys, check, checkSteps, classify, context, dataEdges, derefStep, describe, docEquals, effectEdges, entriesAsJson, evaluate, fail, failures, field, flatten, formulaDefinitions, formulaEvaluators, formulaKinds, formulaKnown, formulaMachine, fromJson, generate, intersectCaps, isAlias, isAllowedOrder, isClosure, isEnvelope, isHostThing, isKey, isKind, isNamespace, isRecord, isRef, isStackOverflow, isTypeRef, jsTruthy, kindDocument, kindNamed, kindOf, layers, looksLikeKind, lookupKind, makeContext, mapRefs, narrow, nearestWalker, nodeAt, ok, partCaps, partsOf, pathMatches, permits, placed, planner, prepare, random, ref, reference, refsOf, resolve, run, sameValue, splitParts, stored, tag, thrown, toJson, typeName, typePath, typed, typesOf, valueOfThing, walk, worldThing };
 
 //# sourceMappingURL=index.js.map