@mark1russell7/coeval 0.7.1 → 0.9.0

package/src/static.ts

@@ -1,7 +1,7 @@
-import { type Envelope, type Json, type Key, isEnvelope, isKey, isRecord, typeName } from "./doc.ts";
-import type { Kind, NamesSource, ScopeRule, World } from "./world.ts";
+import { type Envelope, type Json, type Key, isKey, isRecord, typeName } from "./doc.ts";
+import { type Kind, type Namespace, type World, type WorldEntry, equationType, isKind, isNamespace } from "./world.ts";
 import { ask } from "./ladder.ts";
-import { type PartSlot, partsOf, pathMatches } from "./parts.ts";
+import { type PartSlot, partsOf, scopesOf } from "./parts.ts";
 import { type Cap, type Context, type Root, ROOTS, context, isRef, walkerOf, worldThing } from "./deref.ts";
 import type { ErrorCode } from "./errors.ts";
 import { type Machine, partCaps, permits, waitedReason } from "./evaluate.ts";
@@ -67,75 +67,6 @@ export interface WalkOptions {
   readonly problem?: (problem: WalkProblem) => void;
 }
 
-function valueAt(value: unknown, path: readonly Key[]): unknown {
-  let here: unknown = value;
-  for (const key of path) {
-    if (Array.isArray(here)) here = here[Number(key)];
-    else if (isRecord(here) && Object.hasOwn(here, String(key))) here = here[String(key)];
-    else return undefined;
-  }
-  return here;
-}
-
-function headerName(item: Json): string | undefined {
-  return isEnvelope(item) && typeof (item as { readonly name?: unknown }).name === "string" ? (item as { readonly name: string }).name : undefined;
-}
-
-function namesOf(source: NamesSource, value: unknown, covered: readonly PartSlot[]): readonly string[] {
-  if ("fixed" in source) return source.fixed;
-  if ("keysAt" in source) {
-    const at = valueAt(value, source.keysAt);
-    return isRecord(at) ? Object.keys(at) : [];
-  }
-  if ("listAt" in source) {
-    const at = valueAt(value, source.listAt);
-    return Array.isArray(at) ? (at as readonly unknown[]).filter((item): item is string => typeof item === "string") : [];
-  }
-  if ("textAt" in source) {
-    const at = valueAt(value, source.textAt);
-    if (typeof at === "string") return [at];
-    return source.otherwise === undefined ? [] : [source.otherwise];
-  }
-  return covered.map((slot) => headerName(slot.item)).filter((name): name is string => name !== undefined);
-}
-
-/**
- * This function gives the names that the scope rules of a kind give each part, and the names that only later parts
- * see. `check` and `conforms` read the scope rules with it.
- *
- * @param rules - The scope rules of the kind.
- * @param value - The value of the document.
- * @param slots - The parts of the value, in order.
- * @returns The names that each part sees, and the names that only the later parts see, by the index of the part.
- */
-export function scopesOf(rules: readonly ScopeRule[] | undefined, value: unknown, slots: readonly PartSlot[]): { readonly sees: readonly (readonly string[])[]; readonly later: readonly (readonly string[])[] } {
-  const sees: string[][] = slots.map(() => []);
-  const later: string[][] = slots.map(() => []);
-  for (const rule of rules ?? []) {
-    const covered = slots.map((slot, index) => ({ slot, index })).filter(({ slot }) => rule.in.some((pattern) => pathMatches(slot.path, pattern)));
-    if (rule.sequential !== true) {
-      const names = namesOf(rule.names, value, covered.map(({ slot }) => slot));
-      for (const { index } of covered) sees[index]?.push(...names);
-      continue;
-    }
-    if ("headers" in rule.names) {
-      covered.forEach(({ index }, position) => {
-        const before = covered.slice(0, position).map(({ slot }) => headerName(slot.item)).filter((name): name is string => name !== undefined);
-        const after = covered.slice(position).map(({ slot }) => headerName(slot.item)).filter((name): name is string => name !== undefined);
-        sees[index]?.push(...before);
-        later[index]?.push(...after);
-      });
-      continue;
-    }
-    const names = namesOf(rule.names, value, covered.map(({ slot }) => slot));
-    covered.forEach(({ index }, position) => {
-      if (position > 0) sees[index]?.push(...names);
-      else later[index]?.push(...names);
-    });
-  }
-  return { sees, later };
-}
-
 /** The names of a walk without names. A walk does not change a set at any time: it makes a new set to add names. */
 const NO_NAMES: ReadonlySet<string> = /* @__PURE__ */ new Set();
 
@@ -577,6 +508,74 @@ export function typeCheck(machine: Machine, doc: unknown, options: CheckOptions
   return { type: pass.type, issues: pass.issues.length === 0 ? issues : [...issues, ...pass.issues], places: pass.places };
 }
 
+/**
+ * A problem of a world that `checkWorld` finds before a document exists (STATIC.COVERAGE). Each document of the
+ * kind gives this problem for the verb, thus `check` with the verb finds it too.
+ */
+export interface WorldIssue {
+  /** The code of the problem. `#NOEVAL`: no rung of the ladder gives an evaluator for the verb. */
+  readonly code: "#NOEVAL";
+  /** The keys of the kind from the root of the world. For a fallback kind, the keys of its namespace. */
+  readonly kind: readonly Key[];
+  /** `true` for the fallback kind of a namespace or of the world. */
+  readonly fallback?: true;
+  /** The verb without an evaluator. */
+  readonly verb: string;
+  readonly reason: string;
+}
+
+/** This function tells if a table of verbs has an entry for a verb. */
+function hasVerb(table: Readonly<Record<string, string>> | undefined, verb: string): boolean {
+  return table !== undefined && Object.hasOwn(table, verb);
+}
+
+/**
+ * This function checks the world of a machine before a document exists. It finds each kind that has no entry for a
+ * verb of the list, when the world has no default for that verb (STATIC.COVERAGE). A document of such a kind gets no
+ * evaluator for the verb, thus the check gives the same proof of coverage as a type system.
+ *
+ * The check visits each kind of each namespace, at each depth, and the fallback kind of each namespace and of the
+ * world. It does not follow an alias, because the kind of an alias has its own place. The check reads only the world.
+ *
+ * @param machine - The machine, for its world.
+ * @param verbs - The verbs that each kind of the language must answer, for example `eval`, `view` and `type`.
+ * @returns One issue for each kind and verb without an evaluator. The order is the order of the world, then the
+ *   order of the verbs. The fallback kind of a namespace comes after the entries of that namespace.
+ */
+export function checkWorld(machine: Machine, verbs: readonly string[]): readonly WorldIssue[] {
+  const world = machine.world;
+  const open = verbs.filter((verb) => !hasVerb(world.defaults, verb));
+  const out: WorldIssue[] = [];
+  if (open.length === 0) return out;
+  const visit = (kind: Kind, path: readonly Key[], fallback: boolean): void => {
+    const text = path.join(".");
+    const name = fallback ? (path.length === 0 ? "the fallback kind of the world" : `the fallback kind of ${text}`) : `the kind ${text}`;
+    for (const verb of open) {
+      if (hasVerb(kind.verbs, verb)) continue;
+      const reason = `${name.charAt(0).toUpperCase()}${name.slice(1)} has no entry for the verb ${verb}, and the world has no default for it.`;
+      out.push(fallback ? { code: "#NOEVAL", kind: path, fallback: true, verb, reason } : { code: "#NOEVAL", kind: path, verb, reason });
+    }
+  };
+  // The set holds the namespaces on the way, thus a namespace that holds itself does not loop.
+  const way = new Set<Namespace>();
+  const entries = (kinds: Readonly<Record<string, WorldEntry>>, path: readonly Key[]): void => {
+    for (const key of Object.keys(kinds)) {
+      const entry = kinds[key];
+      const here = [...path, key];
+      if (isKind(entry)) visit(entry, here, false);
+      else if (isNamespace(entry) && !way.has(entry)) {
+        way.add(entry);
+        entries(entry.kinds, here);
+        if (entry.fallback !== undefined) visit(entry.fallback, here, true);
+        way.delete(entry);
+      }
+    }
+  };
+  entries(world.kinds, []);
+  if (world.fallback !== undefined) visit(world.fallback, [], true);
+  return out;
+}
+
 /**
  * A runner under an evaluator in a check of a run. The run drives its steps without a wait, thus only a wait for an
  * effect of its runners fails (RUN.DRIVE-NESTED).
@@ -595,11 +594,55 @@ interface Drive {
 /** What the code of a document does with a wait: an evaluator stops it, and a runner passes it on. */
 type Waits = boolean | Drive;
 
+/** The names that an equation of `down` sees (TREE.DOWN). */
+const DOWN_NAMES: readonly string[] = /* @__PURE__ */ Object.freeze(["child", "index", "prev"]);
+
+/** The names that the term `combine` of a fold sees (TREE.FOLD). */
+const FOLD_NAMES: readonly string[] = /* @__PURE__ */ Object.freeze(["acc", "item"]);
+
+/**
+ * This function gives each equation of the tree contract of a kind, with the names that it sees (D42). An equation of
+ * `equations`, a `unit` and a `default` see no names.
+ */
+function equationsOf(kind: Kind): readonly { readonly label: string; readonly term: Json; readonly names: readonly string[] }[] {
+  const tree = kind.tree;
+  if (tree === undefined) return [];
+  const out: { readonly label: string; readonly term: Json; readonly names: readonly string[] }[] = [];
+  for (const [name, term] of Object.entries(tree.equations ?? {})) out.push({ label: `tree.equations.${name}`, term, names: [] });
+  for (const [name, term] of Object.entries(tree.down ?? {})) out.push({ label: `tree.down.${name}`, term, names: DOWN_NAMES });
+  for (const [name, declared] of Object.entries(tree.attributes ?? {})) {
+    if (declared.fold !== undefined) {
+      out.push({ label: `tree.attributes.${name}.fold.unit`, term: declared.fold.unit, names: [] });
+      out.push({ label: `tree.attributes.${name}.fold.combine`, term: declared.fold.combine, names: FOLD_NAMES });
+    }
+    if (declared.default !== undefined) out.push({ label: `tree.attributes.${name}.default`, term: declared.default, names: [] });
+  }
+  return out;
+}
+
+/**
+ * This function checks the equations of the tree contract of a kind, each with the names of its rung (TREE.DOWN-NAMES).
+ * An equation evaluates without capabilities, thus a check with capabilities gives it none. Each issue gets the place
+ * of the document of the kind, and its reason names the equation.
+ */
+function equationIssues(machine: Machine, kind: Kind, kindText: string, options: CheckOptions, seen: Set<Kind>): readonly Issue[] {
+  const of = equationType(kind);
+  const out: Issue[] = [];
+  for (const { label, term, names } of equationsOf(kind)) {
+    const inner: CheckOptions = { names, ...(of === undefined ? {} : { declaredType: of }), ...(options.caps === undefined ? {} : { caps: [] }) };
+    for (const issue of checkAll(machine, term, inner, undefined, seen)) {
+      out.push({ code: issue.code, place: [], reason: `In the equation ${label} of the kind ${kindText}: ${issue.reason}` });
+    }
+  }
+  return out;
+}
+
 /**
  * This function finds the issues of `check`. With a list of nodes, it also records each document that it visits for
- * the pass of types. It marks each document with an issue.
+ * the pass of types. It marks each document with an issue. The set `seen` holds the kinds whose equations the check
+ * walked, thus it walks the equations of each kind one time.
  */
-function checkAll(machine: Machine, doc: unknown, options: CheckOptions, nodes: TypeNode[] | undefined): readonly Issue[] {
+function checkAll(machine: Machine, doc: unknown, options: CheckOptions, nodes: TypeNode[] | undefined, seen: Set<Kind> = new Set()): readonly Issue[] {
   const issues: Issue[] = [];
   const verb = options.verb ?? "eval";
   const indices = nodes === undefined ? undefined : new Map<DocVisit, number>();
@@ -643,6 +686,11 @@ function checkAll(machine: Machine, doc: unknown, options: CheckOptions, nodes:
         push({ code: "#KIND?", place: v.place, reason: `The world has no kind ${typeName(v.doc.type)}.`, at: v.at });
         return "skip";
       }
+      // The equations of a kind are code of the kind. The check walks them at the first document of the kind (D42).
+      if (v.kind?.tree !== undefined && !seen.has(v.kind)) {
+        seen.add(v.kind);
+        for (const issue of equationIssues(machine, v.kind, typeName(v.doc.type), options, seen)) push({ ...issue, place: v.place, at: v.at });
+      }
       const name = answer.evaluator;
       if (current !== undefined) current.evaluator = name;
       // A runner hides the evaluator of its name (MACHINE.RUNNER), as in the compilation of a plan.

package/src/stdlib.ts

@@ -1,8 +1,21 @@
 import { type Json, type Key, field, isRecord } from "./doc.ts";
-import { type Context, type EvalInput, type Evaluator, type Machine, type Part, type Result, type RunPart, type Runner, type Steps, fail, ok } from "./evaluate.ts";
+import {
+  type EvalInput,
+  type Evaluator,
+  type Machine,
+  type Plan,
+  type Result,
+  type RunPart,
+  type Runner,
+  type Steps,
+  fail,
+  ok,
+  planner,
+} from "./evaluate.ts";
 import { Failure } from "./errors.ts";
-import { type HostThing, type Thing, type Walker, THING, isHostThing, valueOfThing } from "./deref.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 { STD_DOMAINS } from "./types.ts";
 
 /**
@@ -58,6 +71,8 @@ export const STD_WORLD: World = {
       // A node that nothing reads keeps its attributes without an evaluation (TREE.LAZY).
       pure: true,
       lazy: [{}],
+      // The code resolves self to find an open tree and the parent (C4, D44).
+      reads: ["self"],
       summary: "A node of a tree. Each part is an attribute that evaluates on demand, one time, with the node as self.",
     },
     box: {
@@ -66,6 +81,7 @@ export const STD_WORLD: World = {
       caps: [{ rule: "mask" }],
       pure: true,
       lazy: [{}],
+      reads: ["self"],
       summary: "A node of a tree, as panel. A formula in a box can read its parent and its siblings.",
     },
     math: {
@@ -188,11 +204,57 @@ interface TreeBuild {
   open: boolean;
 }
 
+/** The rungs of the ladder of an attribute, in their order (TREE.LADDER, D42). */
+export type AttributeRung = "own" | "kind" | "parent" | "copy" | "default";
+
+/** The rungs of the ladder of an attribute, in their order (TREE.LADDER, D42). */
+export const ATTRIBUTE_RUNGS: readonly AttributeRung[] = /* @__PURE__ */ Object.freeze(["own", "kind", "parent", "copy", "default"] as const);
+
+/** The record of the demand of one attribute of a node (TREE.RUNGS). */
+export interface AttributeTrace {
+  readonly attribute: string;
+  /** The rungs that the demand visited, in their order. The last one answered, unless no rung answered. */
+  readonly rungs: readonly AttributeRung[];
+  /** The rung that answered. It is `undefined` when no rung answered. */
+  readonly by?: AttributeRung;
+}
+
 /** The state of a node behind its brand. */
 interface NodeState {
   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).
+   *
+   * @param key - The name of the attribute.
+   * @returns The result, or `undefined` when no rung answers.
+   */
+  read(key: string): Result | undefined;
+  /**
+   * This function evaluates an equation of the kind of the node, with the node as `self` and no capabilities.
+   *
+   * @param term - The equation.
+   * @param names - The names that the equation sees.
+   * @returns The result.
+   */
+  equation(term: Json, names: Readonly<Record<string, unknown>>): Result;
+  /**
+   * This function gives the names of a child for an equation of `down`: `child`, `index` and `prev` (TREE.DOWN).
+   *
+   * @param child - The thing of the child.
+   * @returns The names, or the error of the list `children`.
+   */
+  childNames(child: HostThing): Result;
+  /**
+   * This function gives the record of the demand of an attribute that ended (TREE.RUNGS).
+   *
+   * @param key - The name of the attribute.
+   * @returns The record, or `undefined` before the end of the demand.
+   */
+  trace(key: string): AttributeTrace | undefined;
   /**
    * This function gives the JSON of the node: each attribute in the order of the parts, with the JSON of each node in
    * its value.
@@ -203,8 +265,60 @@ interface NodeState {
   json(path: Set<object>): Result;
 }
 
-/** The memo cell of one attribute: in evaluation, or done with its result. */
-type Cell = { readonly busy: true } | { readonly busy: false; readonly result: Result };
+/**
+ * The memo cell of one attribute: in evaluation, or done with its result and the rung that answered. A done cell
+ * without a result tells that no rung answered.
+ */
+type Cell = { readonly busy: true } | { readonly busy: false; readonly result: Result | undefined; readonly by: AttributeRung | undefined };
+
+/** The capabilities of an equation: none (CAP.PURE). */
+const NO_CAPS: readonly Cap[] = /* @__PURE__ */ Object.freeze([]);
+
+/** The names of an equation of `equations`, of a `unit` and of a `default`. */
+const NO_NAMES: Readonly<Record<string, unknown>> = /* @__PURE__ */ Object.freeze({});
+
+/** The planners of equations, for each machine and each type of a bare equation (TREE.PLAN). */
+const equationPlanners = /* @__PURE__ */ new WeakMap<Machine, Map<string, (doc: unknown) => Plan>>();
+
+/**
+ * This function gives the plan of an equation. Each equation compiles one time for each machine (PLAN.CACHE). The
+ * plan of the document does not keep it (PLAN.LEAN).
+ */
+function equationPlan(machine: Machine, of: string | undefined, term: Json): Plan {
+  let byType = equationPlanners.get(machine);
+  if (byType === undefined) {
+    byType = new Map();
+    equationPlanners.set(machine, byType);
+  }
+  const key = of ?? "";
+  let plans = byType.get(key);
+  if (plans === undefined) {
+    plans = planner(machine, of === undefined ? {} : { declaredType: of });
+    byType.set(key, plans);
+  }
+  return plans(term);
+}
+
+/** This function gives the own entry of a table of a tree contract, or `undefined`. */
+function entryOf<T>(table: Readonly<Record<string, T>> | undefined, key: string): T | undefined {
+  return table !== undefined && Object.hasOwn(table, key) ? table[key] : undefined;
+}
+
+/** The contract of the kind of a node: its tree contract and the type of a bare equation. */
+interface NodeContract {
+  readonly tree: TreeContract | undefined;
+  readonly of: string | undefined;
+}
+
+const NO_CONTRACT: NodeContract = /* @__PURE__ */ Object.freeze({ tree: undefined, of: undefined });
+
+/** This function finds the tree contract of the kind of a node in the world of the machine. */
+function contractOf(machine: Machine | undefined, typePath: readonly Key[]): NodeContract {
+  if (machine === undefined || typePath.length === 0) return NO_CONTRACT;
+  const found = lookupKind(machine.world, typePath);
+  if (!found.ok || found.kind.tree === undefined) return NO_CONTRACT;
+  return { tree: found.kind.tree, of: equationType(found.kind) };
+}
 
 const BUSY: Cell = /* @__PURE__ */ Object.freeze({ busy: true });
 
@@ -282,21 +396,72 @@ function plainOf(value: unknown, path: Set<object>): Result {
 
 /**
  * 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.
+ * step `type` gives its type. Another step reads an attribute through its ladder (TREE.LADDER). The rungs are a part of
+ * the node, an equation of its kind and an equation `down` of the kind of its parent. A copy from the parent, then a
+ * 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).
  */
-function treeThing(parts: readonly Part[], context: Context, type: string, place: readonly Key[], build: TreeBuild): HostThing {
+function treeThing(input: EvalInput, build: TreeBuild, outer: Thing | undefined): HostThing {
+  const { parts, context, kind: type, place, machine } = input;
+  const { tree, of } = contractOf(machine, input.typePath);
+  const above = stateOf(outer);
+  // 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>();
+  /** 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;
+
+  const fold = (key: string, declared: NonNullable<AttributeDeclaration["fold"]>): Result => {
+    let acc = state.equation(declared.unit, NO_NAMES);
+    if (!acc.ok) return acc;
+    const children = read("children");
+    if (children === undefined) return acc;
+    if (!children.ok) return children;
+    if (!Array.isArray(children.value)) return fail("#VALUE!", `The fold of ${key} needs a list in children.`);
+    for (const item of children.value as readonly unknown[]) {
+      const child = stateOf(item);
+      // An item that is not a node of this tree does not count.
+      if (child === undefined || child.build !== build) continue;
+      const value = child.read(key);
+      if (value === undefined) return fail("#N/A", `No rung gives ${attributeText(key, child.type, child.place)}.`);
+      if (!value.ok) return value;
+      acc = state.equation(declared.combine, { acc: acc.value, item: value.value });
+      if (!acc.ok) return acc;
+    }
+    return acc;
+  };
+
+  /** This function visits the rungs of the ladder of an attribute in their order, until one answers. */
+  const climb = (key: string): { readonly result: Result; readonly by: AttributeRung } | undefined => {
+    const part = parts.find((item) => item.key === key);
+    if (part !== undefined) return { result: part.evaluate({ ...context, self: node }), by: "own" };
+    const equation = entryOf(tree?.equations, key);
+    if (equation !== undefined) return { result: state.equation(equation, NO_NAMES), by: "kind" };
+    const down = up === undefined ? undefined : entryOf(up.tree?.down, key);
+    if (up !== undefined && down !== undefined) {
+      const names = up.childNames(node);
+      return { result: names.ok ? up.equation(down, names.value as Readonly<Record<string, unknown>>) : names, by: "parent" };
+    }
+    const declared = entryOf(tree?.attributes, key);
+    if (declared?.copy === true && up !== undefined) {
+      const copied = up.read(key);
+      if (copied !== undefined) return { result: copied, by: "copy" };
+    }
+    if (declared?.fold !== undefined) return { result: fold(key, declared.fold), by: "default" };
+    if (declared?.default !== undefined) return { result: state.equation(declared.default, NO_NAMES), by: "default" };
+    return undefined;
+  };
+
   const read = (key: string): Result | undefined => {
     const cell = cells.get(key);
     if (cell !== undefined) return cell.busy ? cycleAt(cells, key, attributeText(key, type, place)) : cell.result;
-    const part = parts.find((item) => item.key === key);
-    if (part === undefined) return undefined;
+    // 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;
     cells.set(key, BUSY);
     demands.push({ cells, key, text: attributeText(key, type, place) });
-    let result: Result;
+    let answer: { readonly result: Result; readonly by: AttributeRung } | undefined;
     try {
-      result = part.evaluate({ ...context, self: node });
+      answer = climb(key);
     } catch (error) {
       // An exception of the host, for example an overflow of the stack, leaves the attribute without a result.
       cells.delete(key);
@@ -304,13 +469,40 @@ function treeThing(parts: readonly Part[], context: Context, type: string, place
     } finally {
       demands.pop();
     }
-    cells.set(key, { busy: false, result });
-    return result;
+    cells.set(key, { busy: false, result: answer?.result, by: answer?.by });
+    return answer?.result;
   };
+
   const state: NodeState = {
     build,
     type,
     place,
+    tree,
+    read,
+    equation(term, names) {
+      if (machine === undefined) return fail("#NOEVAL", "The evaluation of an equation needs the machine.");
+      return equationPlan(machine, of, term).evaluate({ ...context, names, caps: NO_CAPS, self: node });
+    },
+    childNames(child) {
+      const children = read("children");
+      if (children !== undefined && !children.ok) return children;
+      const list = children !== undefined && Array.isArray(children.value) ? (children.value as readonly unknown[]) : [];
+      if (positions?.list !== list) {
+        const at = new Map<unknown, number>();
+        list.forEach((item, index) => {
+          if (!at.has(item)) at.set(item, index);
+        });
+        positions = { list, at };
+      }
+      const index = positions.at.get(child);
+      return ok({ child, index: index ?? null, prev: index === undefined || index === 0 ? null : list[index - 1] });
+    },
+    trace(key) {
+      const cell = cells.get(key);
+      if (cell === undefined || cell.busy) return undefined;
+      const rungs = cell.by === undefined ? ATTRIBUTE_RUNGS : ATTRIBUTE_RUNGS.slice(0, ATTRIBUTE_RUNGS.indexOf(cell.by) + 1);
+      return cell.by === undefined ? { attribute: key, rungs } : { attribute: key, rungs, by: cell.by };
+    },
     json(path) {
       path.add(node);
       try {
@@ -334,7 +526,7 @@ function treeThing(parts: readonly Part[], context: Context, type: string, place
     type,
     label: `node ${type}`,
     deref(key: Key): Thing | undefined {
-      if (key === "parent") return context.self;
+      if (key === "parent") return outer;
       if (key === "type") return type;
       const result = read(String(key));
       if (result === undefined) return undefined;
@@ -343,7 +535,9 @@ function treeThing(parts: readonly Part[], context: Context, type: string, place
     },
     has(key: Key): boolean {
       // DEREF.HOST-UNDEFINED: an attribute with the value undefined is a field, not a missing step.
-      return key === "parent" || key === "type" || parts.some((part) => part.key === String(key));
+      if (key === "parent" || key === "type" || parts.some((part) => part.key === String(key))) return true;
+      const cell = cells.get(String(key));
+      return cell !== undefined && !cell.busy && cell.result !== undefined;
     },
     toJson(): unknown {
       const result = state.json(new Set());
@@ -354,15 +548,36 @@ function treeThing(parts: readonly Part[], context: Context, type: string, place
   return node;
 }
 
+/**
+ * This function gives the record of the demand of an attribute of a node of the decorated tree (TREE.RUNGS). The
+ * record holds the rungs that the demand visited, and the rung that answered. An explorer draws the ladder with it.
+ *
+ * @param node - The thing of a node.
+ * @param attribute - The name of the attribute.
+ * @returns The record, or `undefined` for a thing that is not a node or an attribute that no demand reached.
+ */
+export function attributeTrace(node: Thing, attribute: string): AttributeTrace | undefined {
+  return stateOf(node)?.trace(attribute);
+}
+
+/** The path of the root `self`. A node of the tree resolves it, thus the list of reads holds the read (C4). */
+const SELF_PATH: readonly Json[] = /* @__PURE__ */ Object.freeze(["self"]);
+
+/** The options of the resolution of `self`: the node needs no hops. */
+const NO_HOPS = /* @__PURE__ */ Object.freeze({ hops: false });
+
 /**
  * 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.
+ * thing, and no attribute evaluates. Else the node is the root of a new tree, and it gives the JSON of the tree. The
+ * node reads `self` through `resolve` (C4, D44). A machine that closes the root `self` thus gives no nested trees.
  */
-function treeNode({ parts, context, kind, place }: EvalInput): Result {
-  const above = stateOf(context.self);
-  if (above !== undefined && above.build.open) return ok(treeThing(parts, context, kind, place, above.build));
+function treeNode(input: EvalInput): 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));
   const build: TreeBuild = { open: true };
-  const root = treeThing(parts, context, kind, place, build);
+  const root = treeThing(input, build, outer);
   try {
     return (stateOf(root) as NodeState).json(new Set());
   } finally {

package/src/world.ts

@@ -1,5 +1,5 @@
 import { type Envelope, type Json, type Key, type TypeRef, field, isRecord, typePath } from "./doc.ts";
-import type { Cap } from "./deref.ts";
+import type { Cap, Root } from "./deref.ts";
 import type { ValueType } from "./types.ts";
 
 /** The two sides of evaluation. `derive` is pure. `run` causes effects in order. */
@@ -114,11 +114,59 @@ export interface LazyRule {
  *   because the static facts do not see that read.
  * - `volatile`: `true` when its result can change while each read gives the same thing, for example a clock.
  * - `lazy`: the parts that an evaluation can skip and still give a value.
+ * - `reads`: the roots that the code of the kind resolves as a whole, with the path of one root. The static facts
+ *   give a read of each root at each document of the kind (D44). The tree node reads `self` this way.
  */
 export interface KindFacts {
   readonly pure?: boolean;
   readonly volatile?: boolean;
   readonly lazy?: readonly LazyRule[];
+  readonly reads?: readonly Root[];
+}
+
+/**
+ * The declaration of one attribute of the nodes of a kind (D42). The last two rungs of the ladder of an attribute
+ * read it (TREE.LADDER). Each term is a document. A bare term gets the type `of` of the parts of the kind.
+ *
+ * - `copy`: `true` gives a node without an answer of the first three rungs the same attribute of its parent
+ *   (TREE.COPY).
+ * - `fold`: the value of a node without an answer of the first four rungs. The fold starts with the term `unit`.
+ *   Then the term `combine` adds the attribute of each node in the list `children`, one at a time (TREE.FOLD).
+ *   `combine` sees the names `acc` and `item`.
+ * - `default`: the term that gives the value when no rung before it answers and the declaration has no fold.
+ */
+export interface AttributeDeclaration {
+  readonly copy?: boolean;
+  readonly fold?: { readonly unit: Json; readonly combine: Json };
+  readonly default?: Json;
+}
+
+/**
+ * The tree contract of a kind (D42): the equations of the attributes of its nodes. Each equation is a document that
+ * evaluates with the node as `self` and without capabilities. A bare equation gets the type `of` of the parts of the
+ * kind.
+ *
+ * - `equations`: the attributes of the node itself. An equation sees no names.
+ * - `down`: the attributes of each child of the node. `self` is this node. An equation sees the names `child`,
+ *   `index` and `prev` (TREE.DOWN).
+ * - `attributes`: the declarations of the attributes of the node, for the rungs `copy` and `default`.
+ */
+export interface TreeContract {
+  readonly equations?: Readonly<Record<string, Json>>;
+  readonly down?: Readonly<Record<string, Json>>;
+  readonly attributes?: Readonly<Record<string, AttributeDeclaration>>;
+}
+
+/**
+ * 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.
+ *
+ * @param kind - The kind.
+ * @returns The type, or `undefined` when the shape declares none.
+ */
+export function equationType(kind: Kind): string | undefined {
+  const parts = kind.parts as { readonly of?: string; readonly rest?: { readonly of?: string } } | undefined;
+  return parts?.of ?? parts?.rest?.of;
 }
 
 /**
@@ -157,6 +205,11 @@ export interface Kind extends KindFacts {
    * document of the kind, in the place of the type that the rule of the evaluator synthesizes.
    */
   readonly result?: ValueType;
+  /**
+   * The equations and the declarations of the attributes of a node of the decorated tree (D42). Only the evaluator
+   * `tree.node` reads them, and `check` checks each equation one time (TREE.LADDER).
+   */
+  readonly tree?: TreeContract;
   /** One sentence that tells what the kind is. */
   readonly summary?: string;
 }