@mark1russell7/coeval 0.19.0 → 0.20.1

package/src/stdlib.ts

@@ -1,4 +1,4 @@
-import { type Json, type Key, field, isRecord } from "./doc.ts";
+import { type Json, type Key, docEquals, field, isRecord } from "./doc.ts";
 import {
   type EvalInput,
   type Evaluator,
@@ -18,7 +18,7 @@ import {
 import { Failure } from "./errors.ts";
 import { type Cap, type HostThing, type Thing, type Walker, THING, isHostThing, valueOfThing } from "./deref.ts";
 import type { World } from "./ladder.ts";
-import { type AttributeDeclaration, type TreeContract, equationType, lookupKind } from "./world.ts";
+import { type AttributeDeclaration, type CircularRule, type TreeContract, circularOf, equationType, lookupKind } from "./world.ts";
 import { STD_DOMAINS } from "./types.ts";
 import type { SyntaxProfile } from "./syntax.ts";
 
@@ -270,12 +270,8 @@ export interface AttributeTrace {
 }
 
 /** The state of a node behind its brand. */
-interface NodeState {
+interface NodeState extends LoopNode {
   readonly build: TreeBuild;
-  readonly type: string;
-  readonly place: readonly Key[];
-  /** The tree contract of the kind of the node (D42). */
-  readonly tree: TreeContract | undefined;
   /**
    * This function gives an attribute through its ladder (TREE.LADDER).
    *
@@ -328,9 +324,12 @@ export interface AttributeAnswer {
  * This function gives the memo cell of one attribute of one node, for a host that keeps its cells between evaluations
  * (TREE.CELL, D108). The kit uses it at each demand of an attribute in an evaluation.
  *
- * The array `place` is one object for each document of a plan, and it stays the same across the evaluations of that
- * plan. A new plan gives new arrays. Thus a host keeps its cells by the identity of `place` and by `attribute`.
- * A host that keeps its cells by the keys of `place` can give a stale answer after a change of the document.
+ * The array `place` is one object for each node of a plan in its scope. It stays the same across the evaluations of
+ * that plan. The scope of a node is the node around it, or the demand that made its tree (TREE.CELL-DOCUMENT,
+ * D115). Thus a cached plan, for example the plan of an equation, gives a new array for the nodes of each document.
+ *
+ * A new plan gives new arrays. Thus a host keeps its cells by the identity of `place` and by `attribute`.
+ * A host that keeps its cells by the keys of `place` can give the answer of another node or a stale answer.
  *
  * The function gives the answer of `compute`, or a kept answer. A host with signals gives a computed signal: a change
  * of its store then makes only the attributes that read the store compute again. Each demand gives a new `compute`, and
@@ -339,7 +338,7 @@ export interface AttributeAnswer {
  * The kit marks an attribute in evaluation before it uses the cell. Thus a cycle gives `#CYCLE!` before it reaches the
  * cell again. An exception of the function that `compute` did not throw gives `#CYCLE!` with the chain of the demands.
  *
- * @param place - The keys from the root document to the document of the node.
+ * @param place - The key of the node. Its items are the keys from the root document to the document of the node.
  * @param attribute - The name of the attribute.
  * @param compute - The function that visits the rungs of the ladder.
  * @returns The answer.
@@ -428,14 +427,60 @@ const BUSY: Cell = /* @__PURE__ */ Object.freeze({ busy: true });
 const NO_ANSWER: AttributeAnswer = /* @__PURE__ */ Object.freeze({ result: undefined, by: undefined });
 
 /**
- * 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<readonly Key[], Map<string, Cell>>();
 
-/** 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<readonly Key[], TreeBuild>();
 
+/** 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<object, WeakMap<readonly Key[], readonly Key[]>>();
+
+/** 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<Map<string, Cell>, Map<string, object>>();
+
+/**
+ * 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: readonly Key[], above: NodeState | undefined): readonly Key[] {
+  let scope: object | undefined = above?.place;
+  if (scope === undefined) {
+    const demand = demands[demands.length - 1];
+    if (demand === undefined) return place;
+    let byName = demandScopes.get(demand.cells);
+    if (byName === undefined) {
+      byName = new Map();
+      demandScopes.set(demand.cells, byName);
+    }
+    scope = byName.get(demand.key);
+    if (scope === undefined) {
+      scope = {};
+      byName.set(demand.key, scope);
+    }
+  }
+  let keys = keysByScope.get(scope);
+  if (keys === undefined) {
+    keys = new WeakMap();
+    keysByScope.set(scope, keys);
+  }
+  let key = keys.get(place);
+  if (key === undefined) {
+    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<T>(map: WeakMap<readonly Key[], T>, place: readonly Key[], make: () => T): T {
   let value = map.get(place);
@@ -459,6 +504,293 @@ interface Demand {
 /** The attributes in evaluation, in the order of their demands. An evaluation does not wait, thus one list serves. */
 const demands: Demand[] = [];
 
+/** One value of an attribute in an open fixed point (D113). */
+interface LoopValue {
+  readonly result: Result | undefined;
+  readonly by: AttributeRung | undefined;
+  /** The round of an approximation. The round `0` marks a final answer of a node with the cells of a host. */
+  readonly round: number;
+  /** The plain memo of the node. A stable fixed point writes its final value there. A node with host cells has none. */
+  readonly memo: Map<string, Cell> | undefined;
+}
+
+/**
+ * A fixed point in evaluation (TREE.CIRCULAR, D113). The circular attribute that a demand reaches first leads it. Each
+ * circular attribute that a demand reaches during its rounds joins it, thus only one fixed point is open at a time.
+ */
+interface FixedPoint {
+  /** The index of the demand of the leader in `demands`. */
+  readonly depth: number;
+  round: number;
+  /** `true` when a circular attribute got a new value in this round. */
+  changed: boolean;
+  /** The values of the fixed point, by the marks of a node and by the name of the attribute. */
+  readonly values: Map<Map<string, Cell>, Map<string, LoopValue>>;
+  /** The demands of circular attributes, from the leader up. */
+  readonly circular: Set<Demand>;
+  /** The demands above the leader that read an approximation. Their results are not final. */
+  readonly tentative: Set<Demand>;
+}
+
+/** The open fixed point, or `undefined`. */
+let openPoint: FixedPoint | undefined;
+
+/**
+ * What the code of a fixed point needs of a node (D113). The state of each node holds it, thus the functions of a
+ * fixed point are module functions, and a node makes no closure for them.
+ */
+interface LoopNode {
+  readonly type: string;
+  readonly place: readonly Key[];
+  /** The tree contract of the kind of the node (D42). */
+  readonly tree: TreeContract | undefined;
+  /** The marks of the attributes in evaluation. Without the cells of a host, they are the plain memo. */
+  readonly marks: Map<string, Cell>;
+  /** The plain memo of the node. With the cells of a host, it keeps the last answer only for `has` and `trace`. */
+  readonly cells: Map<string, Cell>;
+  readonly host: AttributeCell | undefined;
+  /** This function visits the rungs of the ladder of an attribute in their order, until one answers (TREE.LADDER). */
+  readonly climb: (key: string) => AttributeAnswer | undefined;
+}
+
+/** For each table `tree.attributes`, `true` when an attribute of it declares `circular`. */
+const circularTables = /* @__PURE__ */ new WeakMap<object, boolean>();
+
+/** For each declaration `circular` that is an object, its rule. */
+const circularRules = /* @__PURE__ */ new WeakMap<object, CircularRule>();
+
+/** This function tells if a tree contract declares a circular attribute. The answer for a table is computed one time. */
+function hasCircular(tree: TreeContract | undefined): boolean {
+  const table = tree?.attributes;
+  if (table === undefined) return false;
+  let known = circularTables.get(table);
+  if (known === undefined) {
+    known = Object.keys(table).some((key) => {
+      const declared: unknown = entryOf(table, key);
+      return typeof declared === "object" && declared !== null && (declared as AttributeDeclaration).circular !== undefined;
+    });
+    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: TreeContract | undefined, key: string): CircularRule | undefined {
+  const declared: unknown = entryOf(tree?.attributes, key)?.circular;
+  if (declared === undefined) return undefined;
+  if (typeof declared !== "object" || declared === null) return circularOf(declared);
+  let rule = circularRules.get(declared);
+  if (rule === undefined) {
+    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: FixedPoint, marks: Map<string, Cell>): Map<string, LoopValue> {
+  let values = loop.values.get(marks);
+  if (values === undefined) {
+    values = 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: FixedPoint): void {
+  for (let index = loop.depth + 1; index < demands.length; index += 1) loop.tentative.add(demands[index] as Demand);
+}
+
+/** This function tells if two approximations are the same: two values by DOC.EQUALS, two errors by code and reason. */
+function sameApproximation(a: Result | undefined, b: Result | undefined): boolean {
+  if (a === undefined || b === undefined) 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: FixedPoint): void {
+  for (const values of loop.values.values()) {
+    for (const [key, value] of values) {
+      if (value.memo !== undefined && 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: string, limit: number): string {
+  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: FixedPoint, n: LoopNode, key: string): Result | undefined {
+  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] as Demand);
+  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 !== undefined ? 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: LoopNode, key: string, rule: CircularRule & { readonly ok: true }): AttributeAnswer {
+  const leader = demands[demands.length - 1] as Demand;
+  const loop: FixedPoint = { depth: demands.length - 1, round: 0, changed: false, values: new Map(), circular: new Set([leader]), tentative: new Set() };
+  openPoint = loop;
+  try {
+    let before: Result | undefined = ok(rule.start);
+    for (;;) {
+      loop.round += 1;
+      loop.changed = false;
+      const answer = n.climb(key) ?? NO_ANSWER;
+      // An error is not a value of the fixed point. The other attributes of the cycle evaluate again at their next demand.
+      if (answer.result !== undefined && !answer.result.ok) return answer;
+      if (!sameApproximation(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: undefined });
+      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 = undefined;
+  }
+}
+
+/**
+ * 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: FixedPoint, n: LoopNode, key: string, rule: CircularRule & { readonly ok: true }, kept: LoopValue | undefined): Result | undefined {
+  let value = kept;
+  if (value === undefined || value.round !== loop.round) {
+    const demand: 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: AttributeAnswer;
+    try {
+      answer = n.climb(key) ?? NO_ANSWER;
+    } finally {
+      demands.pop();
+      n.marks.delete(key);
+    }
+    if (!sameApproximation(value === undefined ? ok(rule.start) : value.result, answer.result)) loop.changed = true;
+    value = { result: answer.result, by: answer.by, round: loop.round, memo: n.host === undefined ? n.cells : undefined };
+    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: LoopNode, key: string, rule: (CircularRule & { readonly ok: true }) | undefined): Result | undefined {
+  const demand: 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: AttributeAnswer;
+  try {
+    answer = rule === undefined ? (n.climb(key) ?? NO_ANSWER) : roundsOf(n, key, rule);
+  } catch (error) {
+    // An exception of the host, for example an overflow of the stack, leaves the attribute without a result.
+    n.marks.delete(key);
+    throw error;
+  } finally {
+    demands.pop();
+  }
+  if (loop !== undefined && loop.tentative.has(demand)) {
+    n.marks.delete(key);
+    return answer.result;
+  }
+  if (n.host !== undefined) {
+    // The fixed point keeps a final answer of a node with host cells until it ends (D113).
+    n.marks.delete(key);
+    if (loop !== undefined) loopValues(loop, n.marks).set(key, { result: answer.result, by: answer.by, round: 0, memo: undefined });
+  }
+  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: LoopNode, key: string): Result | undefined {
+  const loop = openPoint;
+  return loop === undefined ? 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: LoopNode, key: string, rule: CircularRule & { readonly ok: true }, host: AttributeCell): Result | undefined {
+  const text = attributeText(key, n.type, n.place);
+  n.marks.set(key, BUSY);
+  demands.push({ cells: n.marks, key, text });
+  let thrown: unknown = NOT_THROWN;
+  let answer: AttributeAnswer;
+  try {
+    answer = host(n.place, key, () => {
+      try {
+        return roundsOf(n, key, rule);
+      } catch (error) {
+        thrown = error;
+        throw error;
+      }
+    });
+  } catch (error) {
+    // An exception of the kit or of the stack goes on, as without a host. Another exception is a cycle of the host.
+    if (error === thrown) throw error;
+    const chain = demands.map((demand) => demand.text).join(" -> ");
+    answer = { result: fail("#CYCLE!", `The cells of the host found a cycle in the demands: ${chain}.`, { cause: error }), by: undefined };
+  } 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: LoopNode, key: string): Result | undefined {
+  const rule = circularRule(n.tree, key);
+  if (rule !== undefined && !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: undefined });
+    return result;
+  }
+  const loop = openPoint;
+  if (loop !== undefined) {
+    const kept = loop.values.get(n.marks)?.get(key);
+    if (rule !== undefined) return roundIn(loop, n, key, rule, kept);
+    if (kept !== undefined) return kept.result;
+    return localIn(n, key, undefined);
+  }
+  if (rule === undefined || n.host === undefined) return localIn(n, key, rule);
+  return leaderOnHost(n, key, rule, n.host);
+}
+
 function attributeText(key: string, type: string, place: readonly Key[]): string {
   return `${key} of ${type} at [${place.join(", ")}]`;
 }
@@ -528,10 +860,11 @@ function plainOf(value: unknown, path: Set<object>): Result {
  * 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: EvalInput, build: TreeBuild, outer: Thing | undefined, host: AttributeCell | undefined): HostThing {
-  const { parts, context, kind: type, place, machine } = input;
+function treeThing(input: EvalInput, place: readonly Key[], build: TreeBuild, outer: Thing | undefined, host: AttributeCell | undefined): HostThing {
+  const { parts, context, kind: type, machine } = input;
   // The equations evaluate in the evaluation that made the node, thus their reads go in its list (READS.EQUATION).
   const runtime = (input as InputWithRuntime)[RUNTIME];
   const { tree, of } = contractOf(machine, input.typePath);
@@ -539,8 +872,10 @@ function treeThing(input: EvalInput, build: TreeBuild, outer: Thing | undefined,
   // Only a node of the same tree is a parent for the rungs `parent` and `copy`.
   const up = above !== undefined && above.build === build ? above : undefined;
   const cells = new Map<string, Cell>();
-  // With the cells of a host, the marks of a place serve each node of the place (TREE.CELL).
+  // With the cells of a host, the marks of a key serve each node of the key (TREE.CELL).
   const marks = host === undefined ? cells : keptAt(marksByPlace, place, () => new Map<string, Cell>());
+  // Only a node whose kind declares a circular attribute takes the path of D113 outside a fixed point.
+  const circular = hasCircular(tree);
   /** The positions of the items of the list `children`, for the names of the children. */
   let positions: { readonly list: readonly unknown[]; readonly at: Map<unknown, number> } | undefined;
 
@@ -594,8 +929,9 @@ function treeThing(input: EvalInput, build: TreeBuild, outer: Thing | undefined,
       ? undefined
       : (key: string): Result | undefined => {
           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 === undefined && up?.tree === undefined && !parts.some((item) => item.key === key)) return undefined;
+          if (circular || openPoint !== undefined) return circularRead(state, key);
           marks.set(key, BUSY);
           demands.push({ cells: marks, key, text });
           let thrown: unknown = NOT_THROWN;
@@ -625,9 +961,11 @@ function treeThing(input: EvalInput, build: TreeBuild, outer: Thing | undefined,
   const read = (key: string): Result | undefined => {
     if (through !== undefined) return through(key);
     const cell = cells.get(key);
-    if (cell !== undefined) return cell.busy ? cycleAt(cells, key, attributeText(key, type, place)) : cell.result;
+    if (cell !== undefined) return cell.busy ? busyAt(state, key) : cell.result;
     // A node without a contract has only its parts, as before D42. Thus a missing part needs no cell.
     if (tree === undefined && up?.tree === undefined && !parts.some((item) => item.key === key)) return undefined;
+    // A circular attribute and each demand in an open fixed point take the code of D113 (TREE.CIRCULAR).
+    if (circular || openPoint !== undefined) return circularRead(state, key);
     cells.set(key, BUSY);
     demands.push({ cells, key, text: attributeText(key, type, place) });
     let answer: { readonly result: Result; readonly by: AttributeRung } | undefined;
@@ -649,6 +987,10 @@ function treeThing(input: EvalInput, build: TreeBuild, outer: Thing | undefined,
     type,
     place,
     tree,
+    marks,
+    cells,
+    host,
+    climb,
     read,
     equation(term, names) {
       if (machine === undefined) return fail("#NOEVAL", "The evaluation of an equation needs the machine.");
@@ -759,11 +1101,13 @@ function treeNode(input: EvalInput, host: AttributeCell | undefined): Result {
   const found = input.resolve(SELF_PATH, NO_HOPS);
   const outer = found.ok ? found.thing : undefined;
   const above = stateOf(outer);
-  if (above !== undefined && above.build.open) return ok(treeThing(input, above.build, outer, host));
+  // With the cells of a host, the key of a node holds its scope (D115). Without them, the place of the plan serves.
+  const place = host === undefined ? input.place : cellPlace(input.place, above);
+  if (above !== undefined && above.build.open) return ok(treeThing(input, place, above.build, outer, host));
   // With the cells of a host, a kept value can hold a node of an earlier evaluation. Thus that node stays in the tree.
-  const build: TreeBuild = host === undefined ? { open: true } : keptAt(buildsByPlace, input.place, () => ({ open: true }));
+  const build: TreeBuild = host === undefined ? { 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) as NodeState).json(new Set());
   } finally {

package/src/steps.ts

@@ -0,0 +1,181 @@
+/**
+ * The steps of a language (STEPS.*). A step is a level of the power of a language. A low step accepts only programs
+ * that end for a known reason, for example loops with a fixed count. A high step accepts more programs. The language
+ * declares the step of each construct as data. `stepOf` gives the lowest step that a document needs, with the reason,
+ * and `checkStep` compares that step with the highest step that the host accepts. A document cannot raise its own
+ * step, because the declaration and the limit come from the language and the host. The ladder of `ask` (`ladder.ts`)
+ * is a different thing: it finds the evaluator of a verb.
+ */
+
+/** A key of a path from the root to a node: a field name or a position. */
+export type StepKey = string | number;
+
+/** The steps of a language, from the lowest to the highest, and the step that each construct needs. It is data. */
+export interface StepLadder<S extends string = string> {
+  /** The names of the steps, from the lowest to the highest. */
+  readonly steps: readonly S[];
+  /** The step that each construct needs. A construct without an entry needs the lowest step. */
+  readonly constructs: Readonly<Record<string, S>>;
+}
+
+/** The walk of the documents of a language. The language gives these two functions. */
+export interface StepWalk<N> {
+  /** This function gives the name of the construct of a node, or `undefined` for a node without a construct. */
+  readonly construct: (node: N) => string | undefined;
+  /** This function gives the child nodes of a node in document order, each with the key of its path. */
+  readonly children: (node: N) => Iterable<readonly [StepKey, N]>;
+}
+
+/** The reason for a step: the first node in document order whose construct needs that step. */
+export interface StepReason<N, S extends string = string> {
+  /** The name of the construct. */
+  readonly construct: string;
+  /** The step that the construct needs. */
+  readonly step: S;
+  /** The keys from the root to the node. The root has the empty path. */
+  readonly path: readonly StepKey[];
+  readonly node: N;
+}
+
+/** The lowest step that a document needs. */
+export interface StepNeed<N, S extends string = string> {
+  readonly step: S;
+  /** The reason. It is `undefined` when no construct needs more than the lowest step. */
+  readonly reason?: StepReason<N, S>;
+}
+
+/** The refusal of a document whose step is higher than the limit of the host. */
+export interface StepRefusal<N, S extends string = string> {
+  /** The step that the document needs. */
+  readonly needed: S;
+  /** The highest step that the host accepts. */
+  readonly maxStep: S;
+  /** The reason of the step. A need that a host makes without `stepOf` can have no reason. */
+  readonly reason?: StepReason<N, S>;
+  /** The text of the refusal. It names the needed step and the limit, and the construct and its path of the reason. */
+  readonly message: string;
+}
+
+/**
+ * This function makes a ladder of steps, and it checks the declaration (STEPS.LADDER). The list of steps must have one
+ * step or more, with no name two times. The step of each construct must be a step of the list.
+ *
+ * @param steps - The names of the steps, from the lowest to the highest.
+ * @param constructs - The step that each construct needs.
+ * @returns The ladder, frozen.
+ * @throws TypeError for a declaration that is not valid, because it is a defect of the language.
+ */
+export function stepLadder<const S extends string>(steps: readonly S[], constructs: Readonly<Record<string, NoInfer<S>>>): StepLadder<S> {
+  if (steps.length === 0) throw new TypeError("a ladder of steps needs one step or more");
+  const seen = new Set<string>();
+  for (const step of steps) {
+    if (typeof step !== "string") throw new TypeError(`the step ${String(step)} is not a name`);
+    if (seen.has(step)) throw new TypeError(`the step "${step}" is in the ladder two times`);
+    seen.add(step);
+  }
+  for (const [construct, step] of Object.entries(constructs)) {
+    if (!seen.has(step)) throw new TypeError(`the construct "${construct}" needs the step "${String(step)}", which is not a step of the ladder`);
+  }
+  return Object.freeze({ steps: Object.freeze([...steps]), constructs: Object.freeze({ ...constructs }) });
+}
+
+/**
+ * This function tells if a value is a step of a ladder. A host uses it to check its option for the highest step.
+ *
+ * @param ladder - The ladder.
+ * @param value - The value.
+ * @returns `true` when the value is the name of a step of the ladder.
+ */
+export function isStep<S extends string>(ladder: StepLadder<S>, value: unknown): value is S {
+  return typeof value === "string" && ladder.steps.includes(value as S);
+}
+
+/**
+ * This function gives the position of a step in its ladder. The lowest step has the position 0.
+ *
+ * @param ladder - The ladder.
+ * @param step - The step.
+ * @returns The position.
+ * @throws TypeError for a name that is not a step of the ladder.
+ */
+export function stepRank<S extends string>(ladder: StepLadder<S>, step: S): number {
+  const rank = ladder.steps.indexOf(step);
+  if (rank < 0) throw new TypeError(`"${String(step)}" is not a step of the ladder. The steps are ${ladder.steps.join(", ")}`);
+  return rank;
+}
+
+/** An item of the walk: a node, the key of its path and the item of its parent. Thus a path costs nothing until a reason needs it. */
+interface Visit<N> {
+  readonly node: N;
+  readonly key: StepKey | undefined;
+  readonly parent: Visit<N> | undefined;
+}
+
+function pathOf<N>(visit: Visit<N>): StepKey[] {
+  const path: StepKey[] = [];
+  for (let v: Visit<N> | undefined = visit; v?.key !== undefined; v = v.parent) path.push(v.key);
+  return path.reverse();
+}
+
+/**
+ * This function gives the lowest step that a document needs, with the reason (STEPS.LOWEST, STEPS.REASON). The step is
+ * the highest step of the constructs of its nodes. The reason is the first node in document order with that step. The
+ * walk uses its own stack, thus a deep document does not overflow (STEPS.LINEAR). It visits a shared node one time,
+ * and it stops at the first node with the highest step of the ladder.
+ *
+ * @param ladder - The ladder of the language.
+ * @param walk - The construct and the child nodes of a node.
+ * @param root - The root node of the document.
+ * @returns The step, and the reason when the step is not the lowest step.
+ */
+export function stepOf<N, S extends string>(ladder: StepLadder<S>, walk: StepWalk<N>, root: N): StepNeed<N, S> {
+  const top = ladder.steps.length - 1;
+  let best = 0;
+  let reason: StepReason<N, S> | undefined;
+  const seen = new Set<unknown>();
+  const todo: Visit<N>[] = [{ node: root, key: undefined, parent: undefined }];
+  for (let visit = todo.pop(); visit !== undefined; visit = todo.pop()) {
+    const { node } = visit;
+    if (typeof node === "object" && node !== null) {
+      if (seen.has(node)) continue;
+      seen.add(node);
+    }
+    const construct = walk.construct(node);
+    const step = construct === undefined || !Object.hasOwn(ladder.constructs, construct) ? undefined : ladder.constructs[construct];
+    const rank = step === undefined ? 0 : ladder.steps.indexOf(step);
+    if (rank > best) {
+      best = rank;
+      reason = { construct: construct as string, step: step as S, path: pathOf(visit), node };
+      if (best === top) break;
+    }
+    const kids = [...walk.children(node)];
+    for (let i = kids.length - 1; i >= 0; i--) {
+      const [key, child] = kids[i] as readonly [StepKey, N];
+      todo.push({ node: child, key, parent: visit });
+    }
+  }
+  const step = ladder.steps[best] as S;
+  return reason === undefined ? { step } : { step, reason };
+}
+
+/**
+ * This function compares the step of a document with the highest step that the host accepts (STEPS.MAX). The limit
+ * changes only which documents the host accepts. The language evaluates an accepted document as before, thus a limit
+ * does not change a value.
+ *
+ * @param ladder - The ladder of the language.
+ * @param need - The step of the document, from `stepOf`.
+ * @param maxStep - The highest step that the host accepts.
+ * @returns `undefined` when the host accepts the document, or the refusal that names the needed step.
+ * @throws TypeError when `maxStep` or the step of `need` is not a step of the ladder.
+ */
+export function checkStep<N, S extends string>(ladder: StepLadder<S>, need: StepNeed<N, S>, maxStep: S): StepRefusal<N, S> | undefined {
+  const limit = stepRank(ladder, maxStep);
+  const needed = stepRank(ladder, need.step);
+  if (needed <= limit) return undefined;
+  const head = `the document needs the step ${need.step}, and the host accepts the steps up to ${maxStep}`;
+  const reason = need.reason;
+  if (reason === undefined) return { needed: need.step, maxStep, message: head };
+  const where = reason.path.length === 0 ? "at the root" : `at the path ${JSON.stringify(reason.path)}`;
+  return { needed: need.step, maxStep, reason, message: `${head}. The construct "${reason.construct}" ${where} needs the step ${reason.step}` };
+}