@mark1russell7/coeval 0.19.0 → 0.20.0

package/build/index.js

@@ -354,6 +354,54 @@ function describe(value) {
 	}
 }
 // src/world.ts
+/** The most rounds of a circular attribute without its own `limit` (TREE.CIRCULAR-LIMIT, D113). */
+const CIRCULAR_LIMIT = 100;
+/** This function tells if a value is JSON data: `null`, a truth value, a finite number, a text, or a container of them. */
+function isJsonData(value) {
+	const stack = [value];
+	const seen = /* @__PURE__ */ new Set();
+	while (stack.length > 0) {
+		const item = stack.pop();
+		if (item === null || typeof item === "string" || typeof item === "boolean") continue;
+		if (typeof item === "number") {
+			if (!Number.isFinite(item)) return false;
+			continue;
+		}
+		if (!Array.isArray(item) && !isRecord(item)) return false;
+		if (seen.has(item)) continue;
+		seen.add(item);
+		for (const inner of Object.values(item)) stack.push(inner);
+	}
+	return true;
+}
+/**
+* This function reads the declaration `circular` of an attribute (D113). The tree kit, the reference, `check` and the
+* graph of attribute instances read it with this one function.
+*
+* @param declared - The value of the field `circular`.
+* @returns The start value and the limit, or the reason when the declaration has no correct form.
+*/
+function circularOf(declared) {
+	if (!isRecord(declared) || !Object.hasOwn(declared, "start")) return {
+		ok: false,
+		reason: "The declaration circular needs a record with the field start."
+	};
+	const start = field(declared, "start");
+	if (!isJsonData(start)) return {
+		ok: false,
+		reason: "The start value of the declaration circular must be JSON data."
+	};
+	const limit = Object.hasOwn(declared, "limit") ? field(declared, "limit") : 100;
+	if (typeof limit !== "number" || !Number.isSafeInteger(limit) || limit < 1) return {
+		ok: false,
+		reason: "The limit of the declaration circular must be a whole number of 1 or more."
+	};
+	return {
+		ok: true,
+		start,
+		limit
+	};
+}
 /**
 * This function gives the type of a bare equation of a kind (D42). It is the type `of` of the shape of its parts, or
 * else the type `of` of the shape `rest` of a record. The plan, the reference and `check` read it with this one function.
@@ -5622,12 +5670,55 @@ const NO_ANSWER = /* @__PURE__ */ Object.freeze({
 	by: void 0
 });
 /**
-* The marks of the attributes in evaluation, for each place of a plan, with the cells of a host (TREE.CELL). Nodes of
-* two evaluations share their place and their kept cells, thus they share their marks.
+* The marks of the attributes in evaluation, for each key of a node, with the cells of a host (TREE.CELL). Nodes of
+* two evaluations share their key and their kept cells, thus they share their marks. Nodes of two documents have
+* different keys, thus a nested evaluation gets its own marks (TREE.CELL-NESTED, D115).
 */
 const marksByPlace = /* @__PURE__ */ new WeakMap();
-/** The trees of the cells of a host, for each place of a root in a plan. Nodes of two evaluations stay in one tree. */
+/** The trees of the cells of a host, for each key of a root. Nodes of two evaluations stay in one tree. */
 const buildsByPlace = /* @__PURE__ */ new WeakMap();
+/** The keys of the nodes with the cells of a host, for each scope and each place of a plan (D115). */
+const keysByScope = /* @__PURE__ */ new WeakMap();
+/** The scopes of the roots that a demand made, for each marks of a node and each name of an attribute (D115). */
+const demandScopes = /* @__PURE__ */ new WeakMap();
+/**
+* This function gives the key of a node with the cells of a host (TREE.CELL-DOCUMENT, D115). The key of the node
+* around the node is its scope. A root without such a node has the scope of the open demand, or no scope.
+* Without a scope, the key is the place of the plan. Thus a cached plan gives a new key for the nodes of each
+* document, and each evaluation of a document gives the same keys.
+*
+* @param place - The place of the document of the node in its plan.
+* @param above - The state of the node around the node, or `undefined`.
+* @returns The key: an array with the keys of `place`.
+*/
+function cellPlace(place, above) {
+	let scope = above?.place;
+	if (scope === void 0) {
+		const demand = demands[demands.length - 1];
+		if (demand === void 0) return place;
+		let byName = demandScopes.get(demand.cells);
+		if (byName === void 0) {
+			byName = /* @__PURE__ */ new Map();
+			demandScopes.set(demand.cells, byName);
+		}
+		scope = byName.get(demand.key);
+		if (scope === void 0) {
+			scope = {};
+			byName.set(demand.key, scope);
+		}
+	}
+	let keys = keysByScope.get(scope);
+	if (keys === void 0) {
+		keys = /* @__PURE__ */ new WeakMap();
+		keysByScope.set(scope, keys);
+	}
+	let key = keys.get(place);
+	if (key === void 0) {
+		key = Object.freeze([...place]);
+		keys.set(place, key);
+	}
+	return key;
+}
 /** This function gives the value of a weak map, or puts a new value in it. */
 function keptAt(map, place, make) {
 	let value = map.get(place);
@@ -5641,6 +5732,277 @@ function keptAt(map, place, make) {
 const NOT_THROWN = /* @__PURE__ */ Symbol("coeval.tree.not-thrown");
 /** The attributes in evaluation, in the order of their demands. An evaluation does not wait, thus one list serves. */
 const demands = [];
+/** The open fixed point, or `undefined`. */
+let openPoint;
+/** For each table `tree.attributes`, `true` when an attribute of it declares `circular`. */
+const circularTables = /* @__PURE__ */ new WeakMap();
+/** For each declaration `circular` that is an object, its rule. */
+const circularRules = /* @__PURE__ */ new WeakMap();
+/** This function tells if a tree contract declares a circular attribute. The answer for a table is computed one time. */
+function hasCircular(tree) {
+	const table = tree?.attributes;
+	if (table === void 0) return false;
+	let known = circularTables.get(table);
+	if (known === void 0) {
+		known = Object.keys(table).some((key) => {
+			const declared = entryOf(table, key);
+			return typeof declared === "object" && declared !== null && declared.circular !== void 0;
+		});
+		circularTables.set(table, known);
+	}
+	return known;
+}
+/** This function gives the declaration `circular` of an attribute of a tree contract (D113), or `undefined`. */
+function circularRule(tree, key) {
+	const declared = entryOf(tree?.attributes, key)?.circular;
+	if (declared === void 0) return void 0;
+	if (typeof declared !== "object" || declared === null) return circularOf(declared);
+	let rule = circularRules.get(declared);
+	if (rule === void 0) {
+		rule = circularOf(declared);
+		circularRules.set(declared, rule);
+	}
+	return rule;
+}
+/** This function gives the values of a fixed point for the marks of a node. */
+function loopValues(loop, marks) {
+	let values = loop.values.get(marks);
+	if (values === void 0) {
+		values = /* @__PURE__ */ new Map();
+		loop.values.set(marks, values);
+	}
+	return values;
+}
+/** This function marks each demand above the leader: each one read an approximation, thus its result is not final. */
+function markTentative(loop) {
+	for (let index = loop.depth + 1; index < demands.length; index += 1) loop.tentative.add(demands[index]);
+}
+/** This function tells if two approximations are the same: two values by DOC.EQUALS, two errors by code and reason. */
+function sameApproximation$1(a, b) {
+	if (a === void 0 || b === void 0) return a === b;
+	if (a.ok && b.ok) return docEquals(a.value, b.value);
+	if (!a.ok && !b.ok) return a.error.code === b.error.code && a.error.reason === b.error.reason;
+	return false;
+}
+/** This function writes the final value of each circular attribute of the last round in the plain memo of its node. */
+function settle(loop) {
+	for (const values of loop.values.values()) for (const [key, value] of values) if (value.memo !== void 0 && value.round === loop.round) value.memo.set(key, {
+		busy: false,
+		result: value.result,
+		by: value.by
+	});
+}
+/** The text of the fixed point of a circular attribute that does not become stable (TREE.CIRCULAR-LIMIT). */
+function limitReason(text, limit) {
+	return `The cycle of the circular attribute ${text} does not become stable within its limit of ${limit} ${limit === 1 ? "round" : "rounds"}.`;
+}
+/**
+* This function answers a demand that reached an attribute in evaluation in an open fixed point (TREE.CYCLE). A chain
+* of circular attributes gives the current approximation (TREE.CIRCULAR). Each other chain gives `#CYCLE!`.
+*/
+function reachedIn(loop, n, key) {
+	const first = demands.findIndex((demand) => demand.cells === n.marks && demand.key === key);
+	let circular = first >= loop.depth;
+	for (let index = first; circular && index < demands.length; index += 1) circular = loop.circular.has(demands[index]);
+	if (!circular) return cycleAt(n.marks, key, attributeText(key, n.type, n.place));
+	const rule = circularRule(n.tree, key);
+	const kept = loop.values.get(n.marks)?.get(key);
+	markTentative(loop);
+	return kept !== void 0 ? kept.result : ok(rule?.ok === true ? rule.start : null);
+}
+/**
+* This function evaluates the leader of a fixed point (TREE.CIRCULAR, D113). Its demand is the last one. Each round
+* visits the ladder again, and the rounds end when no circular attribute gets a new value. An error ends the rounds
+* at once. After the last round of the limit, the leader gives `#CYCLE!` at the place of its node.
+*/
+function roundsOf(n, key, rule) {
+	const leader = demands[demands.length - 1];
+	const loop = {
+		depth: demands.length - 1,
+		round: 0,
+		changed: false,
+		values: /* @__PURE__ */ new Map(),
+		circular: /* @__PURE__ */ new Set([leader]),
+		tentative: /* @__PURE__ */ new Set()
+	};
+	openPoint = loop;
+	try {
+		let before = ok(rule.start);
+		for (;;) {
+			loop.round += 1;
+			loop.changed = false;
+			const answer = n.climb(key) ?? NO_ANSWER;
+			if (answer.result !== void 0 && !answer.result.ok) return answer;
+			if (!sameApproximation$1(before, answer.result)) loop.changed = true;
+			before = answer.result;
+			loopValues(loop, n.marks).set(key, {
+				result: answer.result,
+				by: answer.by,
+				round: loop.round,
+				memo: void 0
+			});
+			if (!loop.changed) {
+				settle(loop);
+				return answer;
+			}
+			if (loop.round >= rule.limit) return {
+				result: fail("#CYCLE!", limitReason(attributeText(key, n.type, n.place), rule.limit), { place: n.place }),
+				by: answer.by
+			};
+		}
+	} finally {
+		openPoint = void 0;
+	}
+}
+/**
+* This function evaluates a circular attribute in the open fixed point of another leader, one time in each round
+* (D113). A later demand in the same round gets the value of the round. Each value is an approximation.
+*/
+function roundIn(loop, n, key, rule, kept) {
+	let value = kept;
+	if (value === void 0 || value.round !== loop.round) {
+		const demand = {
+			cells: n.marks,
+			key,
+			text: attributeText(key, n.type, n.place)
+		};
+		n.marks.set(key, BUSY);
+		demands.push(demand);
+		loop.circular.add(demand);
+		let answer;
+		try {
+			answer = n.climb(key) ?? NO_ANSWER;
+		} finally {
+			demands.pop();
+			n.marks.delete(key);
+		}
+		if (!sameApproximation$1(value === void 0 ? ok(rule.start) : value.result, answer.result)) loop.changed = true;
+		value = {
+			result: answer.result,
+			by: answer.by,
+			round: loop.round,
+			memo: n.host === void 0 ? n.cells : void 0
+		};
+		loopValues(loop, n.marks).set(key, value);
+	}
+	markTentative(loop);
+	return value.result;
+}
+/**
+* This function evaluates an attribute without the cell of the host: with the plain memo, or in an open fixed point
+* (D113). A result that read an approximation is not final, thus no memo keeps it.
+*/
+function localIn(n, key, rule) {
+	const demand = {
+		cells: n.marks,
+		key,
+		text: attributeText(key, n.type, n.place)
+	};
+	const loop = openPoint;
+	n.marks.set(key, BUSY);
+	demands.push(demand);
+	let answer;
+	try {
+		answer = rule === void 0 ? n.climb(key) ?? NO_ANSWER : roundsOf(n, key, rule);
+	} catch (error) {
+		n.marks.delete(key);
+		throw error;
+	} finally {
+		demands.pop();
+	}
+	if (loop !== void 0 && loop.tentative.has(demand)) {
+		n.marks.delete(key);
+		return answer.result;
+	}
+	if (n.host !== void 0) {
+		n.marks.delete(key);
+		if (loop !== void 0) loopValues(loop, n.marks).set(key, {
+			result: answer.result,
+			by: answer.by,
+			round: 0,
+			memo: void 0
+		});
+	}
+	n.cells.set(key, {
+		busy: false,
+		result: answer.result,
+		by: answer.by
+	});
+	return answer.result;
+}
+/**
+* This function answers a demand that reached an attribute in evaluation (TREE.CYCLE). Outside a fixed point, it gives
+* `#CYCLE!` with the chain. In an open fixed point, `reachedIn` answers (TREE.CIRCULAR).
+*/
+function busyAt(n, key) {
+	const loop = openPoint;
+	return loop === void 0 ? cycleAt(n.marks, key, attributeText(key, n.type, n.place)) : reachedIn(loop, n, key);
+}
+/**
+* This function evaluates the leader of a fixed point through the cell of the host (TREE.CELL, D113). The cell of the
+* leader gets the final value of the fixed point, from a computation that contains each round.
+*/
+function leaderOnHost(n, key, rule, host) {
+	const text = attributeText(key, n.type, n.place);
+	n.marks.set(key, BUSY);
+	demands.push({
+		cells: n.marks,
+		key,
+		text
+	});
+	let thrown = NOT_THROWN;
+	let answer;
+	try {
+		answer = host(n.place, key, () => {
+			try {
+				return roundsOf(n, key, rule);
+			} catch (error) {
+				thrown = error;
+				throw error;
+			}
+		});
+	} catch (error) {
+		if (error === thrown) throw error;
+		answer = {
+			result: fail("#CYCLE!", `The cells of the host found a cycle in the demands: ${demands.map((demand) => demand.text).join(" -> ")}.`, { cause: error }),
+			by: void 0
+		};
+	} finally {
+		demands.pop();
+		n.marks.delete(key);
+	}
+	n.cells.set(key, {
+		busy: false,
+		result: answer.result,
+		by: answer.by
+	});
+	return answer.result;
+}
+/**
+* This function gives an attribute of a node with circular attributes, or an attribute in an open fixed point (D113).
+* The memo and the marks of the node do not hold the attribute. An open fixed point does not use the cells of the host.
+*/
+function circularRead(n, key) {
+	const rule = circularRule(n.tree, key);
+	if (rule !== void 0 && !rule.ok) {
+		const result = fail("#VALUE!", `The attribute ${attributeText(key, n.type, n.place)} has a bad declaration circular. ${rule.reason}`);
+		n.cells.set(key, {
+			busy: false,
+			result,
+			by: void 0
+		});
+		return result;
+	}
+	const loop = openPoint;
+	if (loop !== void 0) {
+		const kept = loop.values.get(n.marks)?.get(key);
+		if (rule !== void 0) return roundIn(loop, n, key, rule, kept);
+		if (kept !== void 0) return kept.result;
+		return localIn(n, key, void 0);
+	}
+	if (rule === void 0 || n.host === void 0) return localIn(n, key, rule);
+	return leaderOnHost(n, key, rule, n.host);
+}
 function attributeText(key, type, place) {
 	return `${key} of ${type} at [${place.join(", ")}]`;
 }
@@ -5710,16 +6072,18 @@ function plainOf(value, path) {
 * fold or a default, come last. A failed attribute throws `Failure` with its own error, thus a reference to it gives that error.
 * The argument `outer` is the self of the context, that `treeNode` resolved. The node reads no root of the context directly (C4).
 *
-* The argument `host` gives the memo cells of the host (TREE.CELL), or `undefined` for the plain memo of the node.
+* The argument `place` is the key of the node. With the cells of a host, `cellPlace` gives it. Else it is the place of
+* the plan. The argument `host` gives the memo cells of the host (TREE.CELL), or `undefined` for the plain memo of the node.
 */
-function treeThing(input, build, outer, host) {
-	const { parts, context, kind: type, place, machine } = input;
+function treeThing(input, place, build, outer, host) {
+	const { parts, context, kind: type, machine } = input;
 	const runtime = input[RUNTIME];
 	const { tree, of } = contractOf$1(machine, input.typePath);
 	const above = stateOf(outer);
 	const up = above !== void 0 && above.build === build ? above : void 0;
 	const cells = /* @__PURE__ */ new Map();
 	const marks = host === void 0 ? cells : keptAt(marksByPlace, place, () => /* @__PURE__ */ new Map());
+	const circular = hasCircular(tree);
 	/** The positions of the items of the list `children`, for the names of the children. */
 	let positions;
 	const fold = (key, declared) => {
@@ -5789,8 +6153,9 @@ function treeThing(input, build, outer, host) {
 	*/
 	const through = host === void 0 ? void 0 : (key) => {
 		const text = attributeText(key, type, place);
-		if (marks.has(key)) return cycleAt(marks, key, text);
+		if (marks.has(key)) return busyAt(state, key);
 		if (tree === void 0 && up?.tree === void 0 && !parts.some((item) => item.key === key)) return void 0;
+		if (circular || openPoint !== void 0) return circularRead(state, key);
 		marks.set(key, BUSY);
 		demands.push({
 			cells: marks,
@@ -5828,8 +6193,9 @@ function treeThing(input, build, outer, host) {
 	const read = (key) => {
 		if (through !== void 0) return through(key);
 		const cell = cells.get(key);
-		if (cell !== void 0) return cell.busy ? cycleAt(cells, key, attributeText(key, type, place)) : cell.result;
+		if (cell !== void 0) return cell.busy ? busyAt(state, key) : cell.result;
 		if (tree === void 0 && up?.tree === void 0 && !parts.some((item) => item.key === key)) return void 0;
+		if (circular || openPoint !== void 0) return circularRead(state, key);
 		cells.set(key, BUSY);
 		demands.push({
 			cells,
@@ -5857,6 +6223,10 @@ function treeThing(input, build, outer, host) {
 		type,
 		place,
 		tree,
+		marks,
+		cells,
+		host,
+		climb,
 		read,
 		equation(term, names) {
 			if (machine === void 0) return fail("#NOEVAL", "The evaluation of an equation needs the machine.");
@@ -5980,10 +6350,11 @@ function treeNode(input, host) {
 	const found = input.resolve(SELF_PATH, NO_HOPS);
 	const outer = found.ok ? found.thing : void 0;
 	const above = stateOf(outer);
-	if (above !== void 0 && above.build.open) return ok(treeThing(input, above.build, outer, host));
-	const build = host === void 0 ? { open: true } : keptAt(buildsByPlace, input.place, () => ({ open: true }));
+	const place = host === void 0 ? input.place : cellPlace(input.place, above);
+	if (above !== void 0 && above.build.open) return ok(treeThing(input, place, above.build, outer, host));
+	const build = host === void 0 ? { open: true } : keptAt(buildsByPlace, place, () => ({ open: true }));
 	build.open = true;
-	const root = treeThing(input, build, outer, host);
+	const root = treeThing(input, place, build, outer, host);
 	try {
 		return stateOf(root).json(/* @__PURE__ */ new Set());
 	} finally {
@@ -7465,16 +7836,24 @@ function valueOf$1(info) {
 function hasOwnEntry(table, name) {
 	return table !== void 0 && Object.hasOwn(table, name);
 }
+/** This function tells if the kind of a node declares an attribute `circular` (D113). */
+function isCircular(kind, attribute) {
+	return (hasOwnEntry(kind.tree?.attributes, attribute) ? kind.tree?.attributes?.[attribute] : void 0)?.circular !== void 0;
+}
 /** This function gives the vertex of an attribute of a node. A new vertex goes on the work list for its rungs. */
 function vertexOf(b, node, attribute) {
 	const id = attributeVertexId(node.visit.place, attribute);
 	if (!b.vertices.has(id)) {
-		b.vertices.set(id, {
+		const vertex = {
 			id,
 			place: node.visit.place,
 			attribute,
 			type: node.text
-		});
+		};
+		b.vertices.set(id, isCircular(node.kind, attribute) ? {
+			...vertex,
+			circular: true
+		} : vertex);
 		b.nodes.set(id, node);
 		if (!node.parts.has(attribute)) b.work.push(id);
 	}
@@ -7873,12 +8252,22 @@ function attributeGraph(machine, doc, options = {}) {
 		edges: b.edges,
 		graph,
 		unknown: b.edges.filter((e) => e.from === void 0),
-		cycles: cycles(graph).map((cycle) => ({
-			vertices: cycle.nodes,
-			certain: cycle.certain
-		}))
+		cycles: cycles(graph).map((cycle) => {
+			const found = {
+				vertices: cycle.nodes,
+				certain: cycle.certain
+			};
+			return allCircular(b, cycle.nodes) ? {
+				...found,
+				circular: true
+			} : found;
+		})
 	};
 }
+/** This function tells if each vertex of a list is a circular attribute (D113). */
+function allCircular(b, ids) {
+	return ids.every((id) => b.vertices.get(id)?.circular === true);
+}
 function vertexText(vertex) {
 	return `${vertex.attribute} of ${vertex.type} at [${vertex.place.join(", ")}]`;
 }
@@ -7888,6 +8277,9 @@ function vertexText(vertex) {
 * certain cycle that these reads reach always gives `#CYCLE!`. The issue gets the place of the read that closes the
 * cycle in the order of the run, and the reason of the run. A cycle through a lazy read or an unknown read is not an issue.
 *
+* A cycle whose attributes are each circular gives a fixed point, thus it is not an issue (TREE.CIRCULAR-CHECK). In a
+* cycle with a plain attribute, the run gives `#CYCLE!` at the first read that closes a chain with a plain attribute.
+*
 * @param machine - The world and the code of the evaluators.
 * @param doc - The document, as JSON.
 * @param options - The type of a bare root value.
@@ -7898,7 +8290,7 @@ function cycleIssues(machine, doc, options) {
 	const graph = nodeGraph(b);
 	const certain = /* @__PURE__ */ new Map();
 	cycles(graph).forEach((cycle, index) => {
-		if (cycle.certain) for (const id of cycle.nodes) certain.set(id, index);
+		if (cycle.certain && !allCircular(b, cycle.nodes)) for (const id of cycle.nodes) certain.set(id, index);
 	});
 	if (certain.size === 0) return [];
 	const eager = /* @__PURE__ */ new Map();
@@ -7946,9 +8338,11 @@ function cycleIssues(machine, doc, options) {
 			if (seen === "done") continue;
 			const cycle = certain.get(from);
 			if (cycle === void 0 || reported.has(cycle)) continue;
-			reported.add(cycle);
 			const first = stack.findIndex((frame) => frame.id === from);
-			const chain = [...stack.slice(first).map((frame) => frame.id), from].map((id) => vertexText(b.vertices.get(id)));
+			const ids = stack.slice(first).map((frame) => frame.id);
+			if (allCircular(b, ids)) continue;
+			reported.add(cycle);
+			const chain = [...ids, from].map((id) => vertexText(b.vertices.get(id)));
 			out.push({
 				code: "#CYCLE!",
 				place: e.place,
@@ -8592,7 +8986,8 @@ function equationIssues(machine, kind, kindText, options, state) {
 }
 /**
 * This function finds the issues of the contract of a tree kind (TREE.CHECK-RESERVED). An attribute with the name of a
-* structural step gets no read. A tree kind of the run side contradicts the evaluation on demand of its attributes.
+* structural step gets no read. A tree kind of the run side contradicts the evaluation on demand of its attributes. A
+* declaration `circular` without a start value or with a bad limit gives `#VALUE!` (TREE.CIRCULAR-CHECK).
 */
 function contractIssues(kind, kindText) {
 	const out = [];
@@ -8609,6 +9004,14 @@ function contractIssues(kind, kindText) {
 			reason: `The kind ${kindText} gives the reserved attribute tree.${table}.${name}: ${why}.`
 		});
 	}
+	for (const [name, declared] of Object.entries(tree?.attributes ?? {})) {
+		const rule = declared.circular === void 0 ? void 0 : circularOf(declared.circular);
+		if (rule !== void 0 && !rule.ok) out.push({
+			code: "#VALUE!",
+			place: [],
+			reason: `The kind ${kindText} has a bad declaration tree.attributes.${name}.circular. ${rule.reason}`
+		});
+	}
 	if (kind.side === "run") out.push({
 		code: "#CALC!",
 		place: [],
@@ -12124,31 +12527,146 @@ const REF_RUNGS = [
 		return declared?.default === void 0 ? void 0 : equationOf(node, declared.default, {});
 	}]
 ];
-/** TREE.ONCE, TREE.MEMO and TREE.CYCLE: the result of one attribute, or `undefined` when no rung of its ladder answers. */
+/** TREE.LADDER: the answer of the first rung that answers, or `undefined`. */
+function ladderOf(node, name) {
+	for (const [, rung] of REF_RUNGS) {
+		const result = rung(node, name);
+		if (result !== void 0) return result;
+	}
+}
+/** The open fixed point of the reference, or `undefined`. */
+let refPoint;
+/** TREE.CIRCULAR-CHECK: the declaration `circular` of an attribute of a node, or `undefined`. */
+function circularRuleOf(node, name) {
+	const declared = termIn(node.contract?.attributes, name)?.circular;
+	return declared === void 0 ? void 0 : circularOf(declared);
+}
+/** TREE.CIRCULAR: two approximations are the same when two values are equal (DOC.EQUALS) or two errors have one code and reason. */
+function sameApproximation(a, b) {
+	if (a === void 0 || b === void 0) return a === b;
+	if (a.ok && b.ok) return docEquals(a.value, b.value);
+	if (!a.ok && !b.ok) return a.error.code === b.error.code && a.error.reason === b.error.reason;
+	return false;
+}
+/** TREE.CIRCULAR: the attributes above the leader read an approximation, thus their results are not final. */
+function readApproximation(point) {
+	for (const entry of inEvaluation.slice(point.depth + 1)) entry.tentative = true;
+}
+function approximationsOf(point, node) {
+	const known = point.values.get(node);
+	if (known !== void 0) return known;
+	const made = /* @__PURE__ */ new Map();
+	point.values.set(node, made);
+	return made;
+}
+/**
+* TREE.CIRCULAR and TREE.CIRCULAR-LIMIT: the rounds of the leader of a fixed point. A round without a new value ends
+* the rounds, and each circular attribute of that round keeps its value. An error ends the rounds at once. The last
+* round of the limit gives `#CYCLE!` at the place of the node of the leader.
+*/
+function fixedPointOf(node, name, rule) {
+	const point = {
+		depth: inEvaluation.length - 1,
+		round: 0,
+		changed: false,
+		values: /* @__PURE__ */ new Map()
+	};
+	refPoint = point;
+	try {
+		let before = ok(rule.start);
+		for (;;) {
+			point.round += 1;
+			point.changed = false;
+			const result = ladderOf(node, name);
+			if (result !== void 0 && !result.ok) return result;
+			if (!sameApproximation(before, result)) point.changed = true;
+			before = result;
+			approximationsOf(point, node).set(name, {
+				result,
+				round: point.round
+			});
+			if (!point.changed) {
+				for (const [member, values] of point.values) for (const [key, value] of values) if (value.round === point.round && value.result !== void 0) member.values.set(key, value.result);
+				return result;
+			}
+			if (point.round >= rule.limit) return fail("#CYCLE!", `The cycle of the circular attribute ${nameOfAttribute(node, name)} does not become stable within its limit of ${rule.limit} ${rule.limit === 1 ? "round" : "rounds"}.`, { place: node.place });
+		}
+	} finally {
+		refPoint = void 0;
+	}
+}
+/** TREE.CIRCULAR: a circular attribute in the open fixed point of another leader evaluates one time in each round. */
+function roundOf(point, node, name, rule) {
+	let value = point.values.get(node)?.get(name);
+	if (value === void 0 || value.round !== point.round) {
+		node.pending.add(name);
+		inEvaluation.push({
+			node,
+			name,
+			circular: true,
+			tentative: false
+		});
+		let result;
+		try {
+			result = ladderOf(node, name);
+		} finally {
+			node.pending.delete(name);
+			inEvaluation.pop();
+		}
+		if (!sameApproximation(value === void 0 ? ok(rule.start) : value.result, result)) point.changed = true;
+		value = {
+			result,
+			round: point.round
+		};
+		approximationsOf(point, node).set(name, value);
+	}
+	readApproximation(point);
+	return value.result;
+}
+/**
+* TREE.ONCE, TREE.MEMO, TREE.CYCLE and TREE.CIRCULAR: the result of one attribute, or `undefined` when no rung of its
+* ladder answers. A result that read an approximation of an open fixed point is not kept.
+*/
 function attributeOf(node, 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);
+		const point = refPoint;
+		if (point !== void 0 && from >= point.depth && inEvaluation.slice(from).every((entry) => entry.circular)) {
+			readApproximation(point);
+			const kept = point.values.get(node)?.get(name);
+			if (kept !== void 0) return kept.result;
+			const rule = circularRuleOf(node, name);
+			return ok(rule?.ok === true ? rule.start : null);
+		}
 		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(" -> ")}.`);
 	}
-	node.pending.add(name);
-	inEvaluation.push({
+	const rule = circularRuleOf(node, name);
+	if (rule !== void 0 && !rule.ok) {
+		const bad = fail("#VALUE!", `The attribute ${nameOfAttribute(node, name)} has a bad declaration circular. ${rule.reason}`);
+		node.values.set(name, bad);
+		return bad;
+	}
+	const point = refPoint;
+	if (point !== void 0 && rule !== void 0) return roundOf(point, node, name, rule);
+	const entry = {
 		node,
-		name
-	});
+		name,
+		circular: rule !== void 0,
+		tentative: false
+	};
+	node.pending.add(name);
+	inEvaluation.push(entry);
+	let result;
 	try {
-		for (const [, rung] of REF_RUNGS) {
-			const result = rung(node, name);
-			if (result === void 0) continue;
-			node.values.set(name, result);
-			return result;
-		}
-		return;
+		result = rule === void 0 ? ladderOf(node, name) : fixedPointOf(node, name, rule);
 	} finally {
 		node.pending.delete(name);
 		inEvaluation.pop();
 	}
+	if (!entry.tentative && result !== void 0) node.values.set(name, result);
+	return result;
 }
 /** TREE.RESULT: the JSON of a node. `open` holds the nodes and the containers whose JSON is in progress. */
 function jsonOfNode(node, self, open) {
@@ -16814,6 +17332,6 @@ function samplesAt(values, closed, depth) {
 function typeFromSamples(values, options = {}) {
 	return samplesAt(values, options.closed === true, 0);
 }
-export { ATTRIBUTE_RUNGS, CAPS_TYPE, CONSTRUCTS, ENVELOPE_KEYS, Failure, Held, JOURNAL, MergeError, PARTS, PART_INFO, ROOTS, RUNGS, STD_CAPS, STD_DEFINITIONS, STD_DOMAINS, STD_EVALUATORS, STD_EXT, STD_MACHINE, STD_RUNNERS, STD_SYNTAX, STD_WALKERS, STD_WORLD, THING, WORLD_SYNTAX, agree, agreeRun, agreeSchedule, ask, attributeGraph, attributeTrace, attributeVertexId, capKeys, check, checkLatent, checkSteps, checkWorld, classify, components, conforms, context, cycles, dataEdges, decodeDomain, decodeLog, decodeValue, derefStep, describe, docEquals, durable, edgesOf, effectEdges, effectsOf, effectsOfVerb, encodeLog, encodeValue, entriesAsJson, equationType, evaluate, extendDomain, factsOf, fail, failures, field, fits, flatten, formulaDefinitions, formulaEvaluators, formulaFacts, formulaKinds, formulaKnown, formulaMachine, fromJson, generate, heights, intersectCaps, isAlias, isAllowedOrder, isClosure, isEnvelope, isHostThing, isKey, isKind, isNamespace, isRecord, isRef, isStackOverflow, isTypeRef, join, jsTruthy, kindDocument, kindNamed, kindOf, layers, looksLikeKind, lookupKind, makeContext, mapRefs, member, mergeMachines, mergeWorlds, narrow, nearestWalker, necessary, nodeAt, nodeLayers, ok, parse, partCaps, partsOf, pathMatches, permits, placeOf, placed, planner, prepare, print, printReads, random, recorder, ref, reference, referenceRun, refsOf, replayer, resolve, restrictMachine, restrictWorld, run, sameResult, sameValue, schedule, splitParts, stored, syntaxFormat, tag, thrown, toJson, treeNodeEvaluator, typeCheck, typeFromSamples, typeFromSchema, typeIssues, typeName, typePath, typeText, typed, typesOf, valueOfThing, verifyReads, walk, worldThing };
+export { ATTRIBUTE_RUNGS, CAPS_TYPE, CIRCULAR_LIMIT, CONSTRUCTS, ENVELOPE_KEYS, Failure, Held, JOURNAL, MergeError, PARTS, PART_INFO, ROOTS, RUNGS, STD_CAPS, STD_DEFINITIONS, STD_DOMAINS, STD_EVALUATORS, STD_EXT, STD_MACHINE, STD_RUNNERS, STD_SYNTAX, STD_WALKERS, STD_WORLD, THING, WORLD_SYNTAX, agree, agreeRun, agreeSchedule, ask, attributeGraph, attributeTrace, attributeVertexId, capKeys, check, checkLatent, checkSteps, checkWorld, circularOf, classify, components, conforms, context, cycles, dataEdges, decodeDomain, decodeLog, decodeValue, derefStep, describe, docEquals, durable, edgesOf, effectEdges, effectsOf, effectsOfVerb, encodeLog, encodeValue, entriesAsJson, equationType, evaluate, extendDomain, factsOf, fail, failures, field, fits, flatten, formulaDefinitions, formulaEvaluators, formulaFacts, formulaKinds, formulaKnown, formulaMachine, fromJson, generate, heights, intersectCaps, isAlias, isAllowedOrder, isClosure, isEnvelope, isHostThing, isKey, isKind, isNamespace, isRecord, isRef, isStackOverflow, isTypeRef, join, jsTruthy, kindDocument, kindNamed, kindOf, layers, looksLikeKind, lookupKind, makeContext, mapRefs, member, mergeMachines, mergeWorlds, narrow, nearestWalker, necessary, nodeAt, nodeLayers, ok, parse, partCaps, partsOf, pathMatches, permits, placeOf, placed, planner, prepare, print, printReads, random, recorder, ref, reference, referenceRun, refsOf, replayer, resolve, restrictMachine, restrictWorld, run, sameResult, sameValue, schedule, splitParts, stored, syntaxFormat, tag, thrown, toJson, treeNodeEvaluator, typeCheck, typeFromSamples, typeFromSchema, typeIssues, typeName, typePath, typeText, typed, typesOf, valueOfThing, verifyReads, walk, worldThing };
 
 //# sourceMappingURL=index.js.map