@mark1russell7/coeval 0.4.2 → 0.5.0

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;
@@ -283,7 +299,7 @@ var Failure = class extends Error {
 */
 function isStackOverflow(error) {
 	try {
-		return error instanceof RangeError && /call stack/i.test(error.message);
+		return (error instanceof RangeError || error instanceof SyntaxError) && error.message.includes("call stack");
 	} catch {
 		return true;
 	}
@@ -1040,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.";
@@ -1141,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);
@@ -1211,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.
 *
@@ -1655,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,
@@ -1682,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;
@@ -1712,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;
 	}
@@ -1722,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);
@@ -1748,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,
@@ -2184,7 +2257,8 @@ const STD_WORLD = {
 				],
 				of: "number"
 			},
-			summary: "A node of a tree. Its parts see it as self, and each node links to its parent."
+			caps: [{ rule: "mask" }],
+			summary: "A node of a tree. Each part is an attribute that evaluates on demand, one time, with the node as self."
 		},
 		box: {
 			verbs: {
@@ -2200,7 +2274,8 @@ const STD_WORLD = {
 				],
 				of: "number"
 			},
-			summary: "A node of a tree, as panel. A formula in a box can read the parent of the box."
+			caps: [{ rule: "mask" }],
+			summary: "A node of a tree, as panel. A formula in a box can read its parent and its siblings."
 		},
 		math: { kinds: {
 			sum: {
@@ -2317,53 +2392,167 @@ const STD_EVALUATORS = {
 		const found = resolve(data);
 		return found.ok ? ok(valueOfThing(found.thing)) : fail(found.code, found.reason);
 	},
-	"tree.node": (input) => treeNode(input.parts, input.context, input.kind)
+	"tree.node": (input) => treeNode(input)
 };
+/** The brand of a node of the decorated tree. Its value is the state that the kit reads. */
+const TREE_NODE = Symbol.for("coeval.tree.node");
+const BUSY = Object.freeze({ busy: true });
+/** The attributes in evaluation, in the order of their demands. An evaluation does not wait, thus one list serves. */
+const demands = [];
+function attributeText(key, type, place) {
+	return `${key} of ${type} at [${place.join(", ")}]`;
+}
+/** This function gives the `#CYCLE!` of a demand that reached an attribute in evaluation, with the chain of demands. */
+function cycleAt(cells, key, text) {
+	const first = demands.findIndex((demand) => demand.cells === cells && demand.key === key);
+	const chain = first === -1 ? [text] : demands.slice(first).map((demand) => demand.text);
+	chain.push(text);
+	return fail("#CYCLE!", `The attributes form a cycle: ${chain.join(" -> ")}.`);
+}
+function stateOf(thing) {
+	return typeof thing === "object" && thing !== null ? thing[TREE_NODE] : void 0;
+}
+/** This function sets an own field, also the field `__proto__` (SHAPE.PROTO). */
+function putField(target, key, value) {
+	Object.defineProperty(target, key, {
+		value,
+		enumerable: true,
+		writable: true,
+		configurable: true
+	});
+}
 /**
-* This function evaluates a node of a tree. The node is a host thing. A step `parent` reaches the node that holds
-* it. A step with the name of a part evaluates that part on demand, one time. Each part sees the node as self.
+* This function gives a value with the JSON of each node of a tree in it. A list or a plain record is new only when
+* it holds a node. A container that holds itself stays as it is.
 */
-function treeNode(parts, context, type) {
-	const memo = /* @__PURE__ */ new Map();
+function plainOf(value, path) {
+	const state = stateOf(value);
+	if (state !== void 0) {
+		if (path.has(value)) return fail("#CYCLE!", `The JSON of the node ${state.type} at [${state.place.join(", ")}] holds the node itself.`);
+		return state.json(path);
+	}
+	if (typeof value !== "object" || value === null || path.has(value) || isHostThing(value)) return ok(value);
+	if (!Array.isArray(value) && !isRecord(value)) return ok(value);
+	path.add(value);
+	try {
+		if (Array.isArray(value)) {
+			let list;
+			for (let index = 0; index < value.length; index += 1) {
+				const item = plainOf(value[index], path);
+				if (!item.ok) return item;
+				if (item.value !== value[index]) (list ??= [...value])[index] = item.value;
+			}
+			return ok(list ?? value);
+		}
+		const record = value;
+		let out;
+		for (const key of Object.keys(record)) {
+			const item = plainOf(record[key], path);
+			if (!item.ok) return item;
+			if (item.value === record[key]) continue;
+			if (out === void 0) {
+				out = {};
+				for (const other of Object.keys(record)) putField(out, other, record[other]);
+			}
+			putField(out, key, item.value);
+		}
+		return ok(out ?? value);
+	} finally {
+		path.delete(value);
+	}
+}
+/**
+* This function makes a node of the decorated tree. A step `parent` gives the self of the context of the node, and a
+* step `type` gives its type. A step with the key of a part reads that attribute. A failed attribute throws `Failure`
+* with its own error, thus a reference to it gives that error.
+*/
+function treeThing(parts, context, type, place, build) {
+	const cells = /* @__PURE__ */ new Map();
 	const read = (key) => {
-		const known = memo.get(key);
-		if (known !== void 0) return known;
+		const cell = cells.get(key);
+		if (cell !== void 0) return cell.busy ? cycleAt(cells, key, attributeText(key, type, place)) : cell.result;
 		const part = parts.find((item) => item.key === key);
 		if (part === void 0) return void 0;
-		const result = part.evaluate({
-			...context,
-			self: me
+		cells.set(key, BUSY);
+		demands.push({
+			cells,
+			key,
+			text: attributeText(key, type, place)
+		});
+		let result;
+		try {
+			result = part.evaluate({
+				...context,
+				self: node
+			});
+		} catch (error) {
+			cells.delete(key);
+			throw error;
+		} finally {
+			demands.pop();
+		}
+		cells.set(key, {
+			busy: false,
+			result
 		});
-		memo.set(key, result);
 		return result;
 	};
-	const me = {
+	const state = {
+		build,
+		type,
+		place,
+		json(path) {
+			path.add(node);
+			try {
+				const out = {};
+				for (const part of parts) {
+					const result = read(part.key);
+					if (!result.ok) return result;
+					const value = plainOf(result.value, path);
+					if (!value.ok) return value;
+					putField(out, part.key, value.value);
+				}
+				return ok(out);
+			} finally {
+				path.delete(node);
+			}
+		}
+	};
+	const node = {
 		[THING]: true,
+		[TREE_NODE]: state,
 		type,
 		label: `node ${type}`,
 		deref(key) {
 			if (key === "parent") return context.self;
 			if (key === "type") return type;
 			const result = read(String(key));
-			return result?.ok === true ? result.value : void 0;
+			if (result === void 0) return void 0;
+			if (!result.ok) throw new Failure(result.error);
+			return result.value;
 		},
 		toJson() {
-			const out = {};
-			for (const part of parts) {
-				const result = read(part.key);
-				out[part.key] = result?.ok === true ? result.value : null;
-			}
-			return out;
+			const result = state.json(/* @__PURE__ */ new Set());
+			if (!result.ok) throw new Failure(result.error);
+			return result.value;
 		}
 	};
-	const out = {};
-	for (const part of parts) {
-		const result = read(part.key);
-		if (result === void 0) continue;
-		if (!result.ok) return result;
-		out[part.key] = result.value;
+	return node;
+}
+/**
+* This function evaluates a node of the decorated tree. Inside an attribute of an open tree, the node gives its host
+* thing, and no attribute evaluates. Else the node is the root of a new tree, and it gives the JSON of the tree.
+*/
+function treeNode({ parts, context, kind, place }) {
+	const above = stateOf(context.self);
+	if (above !== void 0 && above.build.open) return ok(treeThing(parts, context, kind, place, above.build));
+	const build = { open: true };
+	const root = treeThing(parts, context, kind, place, build);
+	try {
+		return stateOf(root).json(/* @__PURE__ */ new Set());
+	} finally {
+		build.open = false;
 	}
-	return ok(out);
 }
 function hostType(node, wanted) {
 	return isHostThing(node) && node.type === wanted;
@@ -3020,40 +3209,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;
 		}
@@ -3185,7 +3366,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.
@@ -3227,6 +3409,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("."));
@@ -3259,7 +3450,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!",
@@ -3366,7 +3557,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.";
@@ -3430,7 +3621,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: [{
@@ -3582,7 +3780,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) {
@@ -3615,8 +3813,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 };
@@ -3637,7 +3835,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 };
@@ -3654,7 +3852,7 @@ function formulaEvaluators(profile = {}) {
 			};
 		}),
 		"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) => {
@@ -3675,7 +3873,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"];
@@ -3794,14 +3992,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: {
@@ -3814,7 +4050,8 @@ function formulaMachine(profile = {}, more = {}) {
 		evaluators: {
 			...formulaEvaluators(profile),
 			...more.evaluators
-		}
+		},
+		known
 	};
 }
 //#endregion
@@ -3822,7 +4059,10 @@ function formulaMachine(profile = {}, more = {}) {
 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. */
+/**
+* This function finds the code of an evaluator name. A runner wins over an evaluator of the same name. A standard
+* evaluator gets the definition of the reference, unless the options give another definition (REF.TREE).
+*/
 function choose(env, name) {
 	const runner = own(env.machine.runners, name);
 	if (runner !== void 0) {
@@ -3832,7 +4072,8 @@ function choose(env, name) {
 	}
 	const evaluator = own(env.machine.evaluators, name);
 	if (evaluator === void 0) return void 0;
-	const defined = own(env.definitions.evaluators, name);
+	const standard = evaluator === own(STD_EVALUATORS, name) ? own(STD_DEFINITIONS.evaluators, name) : void 0;
+	const defined = own(env.definitions.evaluators, name) ?? standard;
 	if (defined !== void 0) return { evaluator: defined };
 	return typeof evaluator === "function" ? { evaluator } : { gap: `The reference has no definition of the compiled evaluator ${name}.` };
 }
@@ -3843,31 +4084,22 @@ function choose(env, name) {
 */
 function examine(env, at) {
 	const { place, declared } = at;
-	const envelope = isEnvelope(at.value) ? at.value : void 0;
-	if (envelope === void 0 && declared === void 0) return fail("#PART?", "The value has no envelope, and its position declares no type.", { place });
+	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 = envelope ?? {
-		type: declared,
-		value: at.value
-	};
+	const { doc, kind, split } = read;
 	const kindText = typeName(doc.type);
-	const world = env.machine.world;
-	const answer = ask(world, envelope ?? {}, "eval", declared === void 0 ? {} : { declaredType: declared });
+	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 });
-	const found = lookupKind(world, doc.type);
-	const kind = found.ok ? found.kind : void 0;
-	const split = splitParts(kind?.parts, doc.value);
-	if (!split.ok) {
-		const where = split.at.length === 0 ? "" : ` (at ${split.at.join(".")})`;
-		return fail("#VALUE!", `${split.reason}${where} The kind is ${kindText}.`, { place });
-	}
+	if (!split.ok) return fail("#VALUE!", split.reason, { place });
 	return {
 		doc,
 		kindText,
-		typePath: found.ok ? found.path : [],
+		typePath: read.typePath ?? [],
 		kind,
 		name,
 		chosen,
@@ -4106,6 +4338,126 @@ function reference(machine, doc, context = makeContext(), options = {}) {
 		return placed(thrown(error, "the reference"), []);
 	}
 }
+const refNodes = /* @__PURE__ */ new WeakMap();
+/** The attributes in evaluation in the reference, in the order of their demands (TREE.CYCLE). */
+const inEvaluation = [];
+function nameOfAttribute(node, name) {
+	return `${name} of ${node.kind} at [${node.place.join(", ")}]`;
+}
+function refNodeOf(thing) {
+	return typeof thing === "object" && thing !== null ? refNodes.get(thing) : void 0;
+}
+/** TREE.ONCE, TREE.MEMO and TREE.CYCLE: the result of one attribute, or `undefined` when the node has no such part. */
+function attributeOf(node, self, name) {
+	const done = node.values.get(name);
+	if (done !== void 0) return done;
+	if (node.pending.has(name)) {
+		const from = inEvaluation.findIndex((entry) => entry.node === node && entry.name === name);
+		return fail("#CYCLE!", `The attributes form a cycle: ${[...from < 0 ? [nameOfAttribute(node, name)] : inEvaluation.slice(from).map((entry) => nameOfAttribute(entry.node, entry.name)), nameOfAttribute(node, name)].join(" -> ")}.`);
+	}
+	const part = node.parts.find((item) => item.key === name);
+	if (part === void 0) return void 0;
+	node.pending.add(name);
+	inEvaluation.push({
+		node,
+		name
+	});
+	try {
+		const result = part.evaluate({
+			...node.ctx,
+			self
+		});
+		node.values.set(name, result);
+		return result;
+	} finally {
+		node.pending.delete(name);
+		inEvaluation.pop();
+	}
+}
+/** TREE.RESULT: the JSON of a node. `open` holds the nodes and the containers whose JSON is in progress. */
+function jsonOfNode(node, self, open) {
+	const record = {};
+	for (const part of node.parts) {
+		const result = attributeOf(node, self, part.key);
+		if (!result.ok) return result;
+		const value = plainValue(result.value, [...open, self]);
+		if (!value.ok) return value;
+		setField(record, part.key, value.value);
+	}
+	return ok(record);
+}
+/** This function gives a copy of a value with the JSON of each node in it. */
+function plainValue(value, open) {
+	const node = refNodeOf(value);
+	if (node !== void 0) {
+		if (open.includes(value)) return fail("#CYCLE!", `The JSON of the node ${node.kind} at [${node.place.join(", ")}] holds the node itself.`);
+		return jsonOfNode(node, value, open);
+	}
+	if (typeof value !== "object" || value === null || isHostThing(value) || open.includes(value)) return ok(value);
+	if (Array.isArray(value)) {
+		const items = [];
+		for (const item of value) {
+			const plain = plainValue(item, [...open, value]);
+			if (!plain.ok) return plain;
+			items.push(plain.value);
+		}
+		return ok(items);
+	}
+	if (!isRecord(value)) return ok(value);
+	const copy = {};
+	for (const key of Object.keys(value)) {
+		const plain = plainValue(value[key], [...open, value]);
+		if (!plain.ok) return plain;
+		setField(copy, key, plain.value);
+	}
+	return ok(copy);
+}
+/**
+* TREE.LAZY, TREE.PARENT, TREE.SIBLING and TREE.ERROR: a node of an open tree gives its thing, and the root of a new
+* tree gives its JSON. A step on the thing reads an attribute, and a failed attribute throws its own error.
+*/
+const treeDefinition = ({ parts, context, kind, place }) => {
+	const outer = refNodeOf(context.self);
+	const nested = outer !== void 0 && outer.tree.open;
+	const node = {
+		tree: nested ? outer.tree : { open: true },
+		kind,
+		place,
+		parts,
+		ctx: context,
+		values: /* @__PURE__ */ new Map(),
+		pending: /* @__PURE__ */ new Set()
+	};
+	const self = {
+		[THING]: true,
+		type: kind,
+		label: `node ${kind}`,
+		deref: (key) => {
+			if (key === "parent") return context.self;
+			if (key === "type") return kind;
+			const result = attributeOf(node, self, String(key));
+			if (result === void 0 || result.ok) return result?.ok === true ? result.value : void 0;
+			throw new Failure(result.error);
+		},
+		toJson: () => {
+			const result = jsonOfNode(node, self, []);
+			if (result.ok) return result.value;
+			throw new Failure(result.error);
+		}
+	};
+	refNodes.set(self, node);
+	if (nested) return ok(self);
+	try {
+		return jsonOfNode(node, self, []);
+	} finally {
+		node.tree.open = false;
+	}
+};
+/**
+* The definitions of the reference for the evaluators of the standard machine that need their own reading. The
+* reference uses them for the standard evaluators, also without the option `definitions`. It holds `tree.node`.
+*/
+const STD_DEFINITIONS = { evaluators: { "tree.node": treeDefinition } };
 const CLOSURE$1 = Symbol.for("coeval.closure");
 /** This function sets an own field, also the field `__proto__` (SHAPE.PROTO). */
 function setField(target, key, value) {
@@ -4327,8 +4679,14 @@ function valuesOfStrict(parts) {
 /**
 * 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`. 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. Identity is not compared.
+* `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.
@@ -4564,8 +4922,9 @@ function leafKind(kind) {
 /**
 * 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. Examples are an unknown kind, a value without its shape, a bare value without a type and a name that
-* nothing binds. The depth and the size have limits.
+* 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.
@@ -4578,10 +4937,16 @@ function generate(world, options) {
 	const maxSize = options.maxSize ?? 24;
 	const malformed = options.malformed ?? .05;
 	const keys = options.keys ?? KEYS;
+	const steps = options.steps ?? 2;
+	const roots = options.roots ?? ROOTS;
 	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);
@@ -4651,11 +5016,12 @@ function generate(world, options) {
 			{ names: "a" },
 			["nowhere", "a"]
 		]);
-		const root = pos.names.length > 0 && rng.chance(.75) ? "names" : rng.pick(ROOTS.filter((name) => name !== "names"));
+		const others = roots.filter((name) => name !== "names");
+		const root = roots.includes("names") && pos.names.length > 0 && (others.length === 0 || rng.chance(.75)) || others.length === 0 ? "names" : rng.pick(others);
 		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)) {
+		for (let index = rng.int(steps + 1); 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, [], {
@@ -4804,9 +5170,17 @@ function generate(world, options) {
 			case "one": return rng.chance(malformed) ? "other" : rng.pick(shape.values);
 		}
 	};
-	/** A malformed document: an unknown kind, a bad shape, a bare value without a type, or a bad reference. */
+	/**
+	* 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
@@ -4844,7 +5218,10 @@ function generate(world, options) {
 		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)) return dataOf([pos.declared]);
+		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])));
@@ -4866,6 +5243,6 @@ function generate(world, options) {
 	});
 }
 //#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, agree, ask, capKeys, check, checkSteps, classify, context, dataEdges, derefStep, describe, docEquals, effectEdges, entriesAsJson, evaluate, fail, failures, field, flatten, formulaDefinitions, formulaEvaluators, formulaKinds, 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, pathMatches, permits, placed, planner, prepare, random, ref, reference, refsOf, resolve, run, sameValue, splitParts, stored, tag, thrown, toJson, typeName, typePath, typed, typesOf, valueOfThing, walk, worldThing };
+export { CONSTRUCTS, ENVELOPE_KEYS, Failure, Held, PARTS, PART_INFO, ROOTS, RUNGS, STD_CAPS, STD_DEFINITIONS, 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