@mark1russell7/coeval 0.16.0 → 0.18.0

package/src/evaluate.ts

@@ -146,13 +146,23 @@ const GRANT = /* @__PURE__ */ Symbol("coeval.grant");
 /**
  * The key of the epoch of a grant (CAP.NARROW-KEPT). The epoch is the list of capabilities that the host gave the root
  * of the evaluation of the grant. A spread of a context keeps its epoch, as it keeps its grant. An
- * effect and a resolution read a context of another epoch as a context without a grant.
+ * effect and a resolution read a context of another epoch as a context without a grant. The root has no field of
+ * the epoch, because its grant is the list of the host (`epochOf`).
  */
 const EPOCH = /* @__PURE__ */ Symbol("coeval.epoch");
 
 /** A context with the grant of the kernel and the epoch of that grant. */
 type Granted = Context & { readonly [GRANT]?: readonly Cap[]; readonly [EPOCH]?: readonly Cap[] | undefined };
 
+/**
+ * This function gives the epoch of the grant of a context (CAP.NARROW-KEPT). A context without the field of the epoch
+ * has the epoch of its grant. Only a root has no field, thus its grant is the list of the host. The root then has
+ * one field fewer, and each evaluation makes it faster (K154).
+ */
+function epochOf(ctx: Context): readonly Cap[] | undefined {
+  return (ctx as Granted)[EPOCH] ?? (ctx as Granted)[GRANT];
+}
+
 /**
  * This function gives the capabilities that a context and its grant both permit, the meet `intersectCaps` (CAP.MEET).
  * A context whose grant is its own list gives that list after one comparison. A context without a grant gives none.
@@ -171,10 +181,37 @@ function grantedCaps(ctx: Context): readonly Cap[] {
 function granted(ctx: Context): Context {
   if ((ctx as Granted)[GRANT] === ctx.caps) return ctx;
   const caps = grantedCaps(ctx);
-  const out: Granted = { ...ctx, caps, [GRANT]: caps };
+  const out: Granted = { ...ctx, caps, [GRANT]: caps, [EPOCH]: epochOf(ctx) };
   return out;
 }
 
+/**
+ * This function tells if a list of capabilities is equal to the epoch of the evaluation (CAP.EPOCH-EQUAL). An equal list
+ * has the same length, and at each index the same text or the same keys in the same order. The runtime uses it only
+ * when the two lists are not the same object. Thus a host that gives a new copy of its list for each evaluation keeps
+ * the grant of a kept context.
+ */
+function sameCaps(caps: readonly Cap[] | undefined, epoch: readonly Cap[]): boolean {
+  if (caps === undefined || caps.length !== epoch.length) return false;
+  for (let index = 0; index < caps.length; index += 1) {
+    const a = caps[index] as Cap;
+    const b = epoch[index] as Cap;
+    if (a === b) continue;
+    if (typeof a === "string" || typeof b === "string" || a.length !== b.length) return false;
+    for (let key = 0; key < a.length; key += 1) if (!Object.is(a[key], b[key])) return false;
+  }
+  return true;
+}
+
+/**
+ * This function tells if a context has the epoch of the evaluation: the same list, or an equal list (CAP.NARROW-KEPT,
+ * CAP.EPOCH-EQUAL). The comparison of the entries happens only when the two lists are not the same object.
+ */
+function inEpoch(ctx: Context, epoch: readonly Cap[]): boolean {
+  const own = epochOf(ctx);
+  return own === epoch || sameCaps(own, epoch);
+}
+
 /**
  * This function gives a context of another epoch the epoch of the evaluation, without capabilities (CAP.NARROW-KEPT).
  * Thus the context reads as a context without a grant. The kernel cannot know the document of the context in this
@@ -190,13 +227,23 @@ function ungranted(ctx: Context, epoch: readonly Cap[]): Context {
  * The context has the meet of its list and its grant, and a context without a grant has none. Thus a read of the root
  * `caps` and a walker of a step document get the capabilities of the document from a widened context.
  * A context that the code narrowed keeps its own list. A context whose list does not change stays the same object.
- * A context of another epoch has no capabilities (CAP.NARROW-KEPT).
+ *
+ * A context of another epoch has no capabilities (CAP.NARROW-KEPT). An equal list of the host is the same epoch
+ * (CAP.EPOCH-EQUAL). The first test answers for a context of the epoch whose grant is its list, for example the root.
+ * The other contexts go to `readableOther`, thus the hot part of the function stays small (K154).
  */
 function readable(ctx: Context, epoch: readonly Cap[]): Context {
-  if ((ctx as Granted)[EPOCH] !== epoch) return ctx.caps.length === 0 ? ctx : ungranted(ctx, epoch);
+  const grant = (ctx as Granted)[GRANT];
+  if (grant === ctx.caps && ((ctx as Granted)[EPOCH] ?? grant) === epoch) return ctx;
+  return readableOther(ctx, epoch);
+}
+
+/** This function gives the result of `readable` for each other context: a context of another epoch or a narrowed context. */
+function readableOther(ctx: Context, epoch: readonly Cap[]): Context {
+  if (!inEpoch(ctx, epoch)) return ctx.caps.length === 0 ? ctx : ungranted(ctx, epoch);
   const caps = grantedCaps(ctx);
   if (caps === ctx.caps || (caps.length === 0 && ctx.caps.length === 0)) return ctx;
-  const out: Granted = { ...ctx, caps, [GRANT]: caps };
+  const out: Granted = { ...ctx, caps, [GRANT]: caps, [EPOCH]: epochOf(ctx) };
   return out;
 }
 
@@ -207,8 +254,8 @@ function readable(ctx: Context, epoch: readonly Cap[]): Context {
  */
 function handed(parent: Context, next: Context): Context {
   const ctx = narrow(parent, next);
-  const epoch = (parent as Granted)[EPOCH];
-  if ((ctx as Granted)[GRANT] === ctx.caps && (ctx as Granted)[EPOCH] === epoch) return ctx;
+  const epoch = epochOf(parent);
+  if ((ctx as Granted)[GRANT] === ctx.caps && epochOf(ctx) === epoch) return ctx;
   const out: Granted = { ...ctx, [GRANT]: ctx.caps, [EPOCH]: epoch };
   return out;
 }
@@ -358,9 +405,11 @@ export interface Journal {
    *
    * @param all - The address of the `all`.
    * @param waiting - The indices of the items that wait.
+   * @param before - The number of the waits of this `all` that settled before this call. The kernel gives it, thus a
+   *   replayer keeps no state of a run (RUN.REPLAY-RUNS). An older copy of the kernel does not give it.
    * @returns The index of an item that waits, or `undefined` for the order of the host.
    */
-  readonly next?: (all: string, waiting: readonly number[]) => number | undefined;
+  readonly next?: (all: string, waiting: readonly number[], before?: number) => number | undefined;
 }
 
 /** This function gives the journal of a function `perform`, when it has one. */
@@ -1004,6 +1053,11 @@ class Session implements Runtime {
   private list: Effect[] | undefined;
   tick = 0;
   nextId = 0;
+  /**
+   * The count of the drives without a wait that are active at this time. In a run, an effect under such a drive does
+   * not reach the host (RUN.HELD).
+   */
+  held = 0;
   current: Building | undefined;
   readonly holder: Building | undefined;
   /**
@@ -1024,8 +1078,11 @@ class Session implements Runtime {
     readonly perform: Perform | undefined,
     readonly signal: StopSignal | undefined,
     effects: Effect[] | undefined,
-    /** The record of the reads. Without it, a resolution records nothing. */
-    private readonly reading: Reading | undefined = undefined,
+    /**
+     * The record of the reads. Without it, a resolution records nothing. A nested evaluation of an equation of a tree
+     * shares the record of the evaluation around it (READS.EQUATION).
+     */
+    readonly reading: Reading | undefined = undefined,
   ) {
     this.list = effects;
     this.holder = traced ? holderNode() : undefined;
@@ -1152,10 +1209,10 @@ class Session implements Runtime {
    * This function checks the capability of an effect, and records the effect with its address (RUN.ADDRESS). The
    * context keeps only the capabilities of its grant, thus compiled code cannot widen the context of its own effect
    * (CAP.NARROW-CODE). A context of another epoch has no capabilities, thus code cannot keep a context for a later
-   * evaluation with fewer capabilities (CAP.NARROW-KEPT).
+   * evaluation with fewer capabilities (CAP.NARROW-KEPT). An equal list of the host is the same epoch (CAP.EPOCH-EQUAL).
    */
   private record(given: Context, kind: Cap, payload: unknown, place: readonly Key[]): Result | Recorded {
-    const ctx = (given as Granted)[EPOCH] === this.epoch ? granted(given) : ungranted(given, this.epoch);
+    const ctx = inEpoch(given, this.epoch) ? granted(given) : ungranted(given, this.epoch);
     const keys = typeof kind === "string" ? kind.split(".") : kind;
     const text = keys.join(".");
     if (!this.permitted(ctx, keys)) return fail("#CAP!", `The context has no capability for the effect ${text}.`, { place });
@@ -1213,6 +1270,13 @@ class Session implements Runtime {
     if ("ok" in made) return made;
     const perform = this.perform;
     if (!this.running || perform === undefined) return this.answer(made, place);
+    if (this.held > 0) {
+      // The parent cannot wait for the answer of the host, thus the host does not get the effect (RUN.HELD).
+      made.outcome = fail("#CALC!", heldReason(made.kind), { place });
+      // The drive stops at this wait, and gives the #CALC! of the runner.
+      yield HELD;
+      return made.outcome;
+    }
     let done: unknown;
     try {
       done = perform(made);
@@ -1246,6 +1310,7 @@ class Session implements Runtime {
     }
     const active: Active[] = [];
     let next = 0;
+    let before = 0;
     const settle = (index: number, result: Result): void => {
       results[index] = result;
       if (failFast && !result.ok) failed = true;
@@ -1297,7 +1362,7 @@ class Session implements Runtime {
     start();
     while (active.length > 0 && !failed) {
       // A replay settles the waits in the recorded order. Each other run takes the first wait that settles.
-      const chosen = journal?.next?.(address, active.map((item) => item.index));
+      const chosen = journal?.next?.(address, active.map((item) => item.index), before);
       const pick = chosen === undefined ? undefined : active.find((item) => item.index === chosen);
       const settled = (yield pick === undefined ? Promise.race(active.map((item) => item.pending)) : pick.pending) as {
         readonly item: Active;
@@ -1306,6 +1371,7 @@ class Session implements Runtime {
         readonly threw: boolean;
       };
       journal?.settled?.(address, settled.item.index);
+      before += 1;
       active.splice(active.indexOf(settled.item), 1);
       advance(settled.item.index, settled.item.steps, settled);
       start();
@@ -1398,6 +1464,21 @@ export function waitedReason(kindText: string): string {
   return `${kindText} waits for effects, and its parent cannot wait. Give the parent a runner.`;
 }
 
+/**
+ * This function gives the reason of an effect that a run does not give to the host: the parent of its runner cannot
+ * wait (RUN.HELD). The plan and the reference give the same reason.
+ *
+ * @param kind - The kind of the effect.
+ * @returns The reason.
+ */
+export function heldReason(kind: Cap): string {
+  const text = typeof kind === "string" ? kind : kind.join(".");
+  return `The parent of the runner cannot wait, thus the host does not get the effect ${text}.`;
+}
+
+/** The wait of an effect that a run does not give to the host. A drive without a wait stops at it (RUN.HELD). */
+const HELD: Promise<unknown> = /* @__PURE__ */ Promise.resolve(undefined);
+
 /** This function drives steps that cannot wait. A step that waits stops the steps, and gives `#CALC!`. */
 function drive(steps: Steps, kindText: string): Result {
   const step = steps.next();
@@ -2070,7 +2151,7 @@ function gated(rules: readonly CapsRule[], part: Compiled): Compiled {
     const ctx = granted(given);
     const caps = capsUnder(rules, ctx.caps);
     if (caps === ctx.caps || (caps.length === 0 && ctx.caps.length === 0)) return ctx;
-    const out: Granted = { ...ctx, caps, [GRANT]: caps };
+    const out: Granted = { ...ctx, caps, [GRANT]: caps, [EPOCH]: epochOf(ctx) };
     return out;
   };
   // The steps of an evaluator are `runOf` of its code, thus `runOf` of this code narrows the context the same way.
@@ -2094,10 +2175,19 @@ function placedRun(inner: RunCode, place: readonly Key[], name: string): RunCode
 /**
  * This function gives the code of a runner under a parent that cannot wait: its steps, driven without a wait. An
  * evaluation and a run both drive them (RUN.DRIVE-NESTED). Only a step that really waits gives `#CALC!`, at the place
- * of the runner, where the error started (RUN.WAIT).
+ * of the runner, where the error started (RUN.WAIT). In a run, an effect under the runner does not reach the host,
+ * because the parent cannot wait for its answer (RUN.HELD).
  */
 function runnerCode(run: RunCode, place: readonly Key[], kindText: string): Code {
-  return (ctx, rt) => placed(drive(run(ctx, rt), kindText), place);
+  return (ctx, rt) => {
+    if (!rt.running || !(rt instanceof Session)) return placed(drive(run(ctx, rt), kindText), place);
+    rt.held += 1;
+    try {
+      return placed(drive(run(ctx, rt), kindText), place);
+    } finally {
+      rt.held -= 1;
+    }
+  };
 }
 
 /**
@@ -2126,6 +2216,36 @@ function fillOf(split: Extract<Split, { readonly ok: true }>, doc: Envelope): <P
   return (items) => (split.parts.length === 0 ? doc.value : split.fill(items));
 }
 
+/**
+ * The key of the runtime on the input of an evaluator. Only the kernel reads it. The node of a tree evaluates its
+ * equations in the evaluation of this runtime, thus their reads go in its list (READS.EQUATION). A copy of the input
+ * with a spread keeps the key.
+ */
+export const RUNTIME: unique symbol = /* @__PURE__ */ Symbol("coeval.runtime") as never;
+
+/** The input of an evaluator, with the runtime of its evaluation. */
+export interface InputWithRuntime extends EvalInput {
+  readonly [RUNTIME]?: Runtime;
+}
+
+/**
+ * This function evaluates a plan inside the evaluation of another runtime, for example an equation of a tree inside
+ * the evaluation of its tree (READS.EQUATION). The plan gets its own runtime, as in `plan.evaluate`. The reads of the
+ * plan go in the record of the reads of `outer`. The context at the root of `outer` tells which reads are free
+ * (READS.FREE). Without such a record, the function gives `plan.evaluate(context)`.
+ *
+ * @param plan - The plan.
+ * @param context - The context of the plan.
+ * @param outer - The runtime of the evaluation around the plan, or `undefined`.
+ * @returns The result.
+ */
+export function evaluateWithin(plan: Plan, context: Context, outer: Runtime | undefined): Result {
+  const reading = outer instanceof Session ? outer.reading : undefined;
+  if (reading === undefined || !(plan instanceof CompiledPlan)) return plan.evaluate(context);
+  const machine = plan.machine;
+  const ctx = rootContext(machine, context);
+  return plan.code(ctx, new Session(machine, ctx.caps, false, plan.traced, undefined, undefined, undefined, reading));
+}
 
 function interpret(fn: EvalFn, input: CompileInput, fill: <P>(handles: readonly P[]) => unknown): Code {
   const { kind, typePath, doc, data, place, machine } = input;
@@ -2155,7 +2275,8 @@ function interpret(fn: EvalFn, input: CompileInput, fill: <P>(handles: readonly
       resolve: (path, options) => rt.resolve(ctx, path, options),
       effect: (effectKind, payload) => rt.effect(ctx, effectKind, payload, place),
       fill: refill,
-    });
+      [RUNTIME]: rt,
+    } as InputWithRuntime);
   };
 }
 
@@ -2192,16 +2313,25 @@ function interpretRun(fn: RunFn, input: CompileInput, fill: <P>(handles: readonl
 /**
  * This function gives the context at the root of an evaluation. It is the context of the host, with the world of
  * the machine when the context has none. The host gives the capabilities, thus the root has the grant of each one
- * (CAP.NARROW-CODE). The list of the host is also the epoch of the grant (CAP.NARROW-KEPT). An evaluation and
- * `verifyReads` share it.
+ * (CAP.NARROW-CODE). The list of the host is also the epoch of the grant (CAP.NARROW-KEPT). The root has no field of
+ * the epoch, thus it has the shape of a context before K120 (K154). An evaluation and `verifyReads` share it.
+ *
+ * The function reads the epoch of the context one time, and one test keeps a context that is already a root (K169).
  *
  * @param machine - The machine.
  * @param ctx - The context of the host.
  * @returns The context at the root.
  */
 export function rootContext(machine: Machine, ctx: Context): Context {
-  if (ctx.world !== null && (ctx as Granted)[GRANT] === ctx.caps && (ctx as Granted)[EPOCH] === ctx.caps) return ctx;
-  const root: Granted = { ...ctx, world: ctx.world === null ? worldThing(machine.world) : ctx.world, [GRANT]: ctx.caps, [EPOCH]: ctx.caps };
+  const epoch = (ctx as Granted)[EPOCH];
+  if (ctx.world !== null && (ctx as Granted)[GRANT] === ctx.caps && (epoch === undefined || epoch === ctx.caps)) return ctx;
+  const world = ctx.world === null ? worldThing(machine.world) : ctx.world;
+  if (epoch === undefined) {
+    const root: Granted = { ...ctx, world, [GRANT]: ctx.caps };
+    return root;
+  }
+  // A context of the kernel as the context of the host gets the list of the host as its epoch.
+  const root: Granted = { ...ctx, world, [GRANT]: ctx.caps, [EPOCH]: ctx.caps };
   return root;
 }
 

package/src/facts.ts

@@ -1,10 +1,10 @@
 import { type Json, type Key, isEnvelope, isKey } from "./doc.ts";
-import { type Kind, type LazyRule, type Side, type World, lookupKind } from "./world.ts";
+import { type Kind, type LazyRule, type Side, type World, equationType, lookupKind } from "./world.ts";
 import { answerOf } from "./ladder.ts";
 import { pathMatches, splitParts } from "./parts.ts";
 import { type Root, ROOTS, isRef } from "./deref.ts";
 import type { Machine } from "./evaluate.ts";
-import { type DocVisit, declaredEffects, walk } from "./static.ts";
+import { type DocVisit, type WalkOptions, declaredEffects, equationsOf, walk } from "./static.ts";
 
 /**
  * One read of a document: a free reference, with its marks (FACTS.READS). A plan resolves the path of the reference
@@ -27,9 +27,12 @@ export interface StaticRead {
   readonly address: boolean;
   /** The path of the reference: its root and its steps. */
   readonly path: readonly Json[];
-  /** The keys from the root document to the reference document, through the parts. */
+  /**
+   * The keys from the root document to the reference document, through the parts. A read of an equation has the
+   * place of the first document of its tree kind (FACTS.EQUATIONS).
+   */
   readonly place: readonly Key[];
-  /** The keys from the root JSON value to the reference document. */
+  /** The keys from the root JSON value to the reference document, or to the document of the kind for an equation. */
   readonly at: readonly Key[];
 }
 
@@ -151,9 +154,11 @@ function partLazy(above: Above, parent: DocVisit, slot: readonly Key[]): boolean
  *
  * - `reads`: each free reference, with the root and the keys of its path. A read under a lazy part has the mark
  *   `lazy`, for example a read in a branch of `if`. A read after a step document has `exact: false`. A kind that
- *   declares `reads` adds a read of each of its roots at each document of the kind.
+ *   declares `reads` adds a read of each of its roots at each document of the kind. The first document of a tree
+ *   kind also gets the lazy reads of the equations of its kind (FACTS.EQUATIONS). A read from `self` or from a name
+ *   of a rung is not one of them, because it is not free (READS.EQUATION).
  * - `side` and `effects`: from the contract of each kind.
- * - `pure`: each kind declares `pure`, and the document has no effect and is not volatile.
+ * - `pure`: each kind declares `pure`, also in an equation, and the document has no effect and is not volatile.
  * - `volatile`: a kind, an operation or a step document declares `volatile`, or the host marks a read.
  *
  * The hook `facts` of the machine answers for a name that a fallback kind covers, for example an operation. Its
@@ -177,7 +182,6 @@ function partLazy(above: Above, parent: DocVisit, slot: readonly Key[]): boolean
 export function factsOf(machine: Machine, doc: unknown, options: FactsOptions = {}): DocFacts {
   const world = machine.world;
   const hook = machine.facts;
-  const verb = options.verb ?? "eval";
   const reads: StaticRead[] = [];
   const effects: string[] = [];
   const above = new Map<DocVisit, Above>();
@@ -185,82 +189,113 @@ export function factsOf(machine: Machine, doc: unknown, options: FactsOptions =
   let pure = true;
   let volatile = false;
   let size = 0;
+  // The tree kinds whose equations the facts walked. The first document of each such kind gets their reads (FACTS.EQUATIONS).
+  let seen: Set<Kind> | undefined;
   const note = (isPure: boolean | undefined, isVolatile: boolean | undefined): void => {
     if (isPure !== true) pure = false;
     if (isVolatile === true) volatile = true;
   };
-  walk(
-    world,
-    doc,
-    (v) => {
-      size += 1;
-      const up = v.parent === undefined ? undefined : above.get(v.parent);
-      const lazy = up !== undefined && v.parent !== undefined && (up.lazy || partLazy(up, v.parent, v.slot));
-      const kind = v.kind;
-      if (kind === undefined) {
-        // A kind that the world does not have gives #KIND?, and the walk does not visit its value.
-        pure = false;
-        above.set(v, { lazy, rules: undefined });
-        return undefined;
-      }
-      const code = codeOf(world, v.declared ? undefined : v.doc.own, kind, verb, "eval");
-      const answer = code.name === undefined ? undefined : hook?.(v.typePath ?? [], code.name);
-      let roots: readonly Root[] | undefined;
-      if (code.described) {
-        note(answer?.pure ?? kind.pure, answer?.volatile ?? kind.volatile);
-        above.set(v, { lazy, rules: answer?.lazy ?? kind.lazy });
-        roots = answer?.reads ?? kind.reads;
-      } else {
-        // The contract of the kind does not describe this code. Only the hook can.
-        note(answer?.pure, answer?.volatile);
-        above.set(v, { lazy, rules: answer?.lazy ?? EACH });
-        roots = answer?.reads;
-      }
-      // The code of the kind resolves each of these roots as a whole, at the place of its document (FACTS.KIND-READS).
-      for (const root of roots ?? NONE) {
-        const read: StaticRead = { root, keys: NONE, exact: true, lazy, address: false, path: [root], place: tight(v.place), at: tight(v.at) };
-        reads.push(read);
-        if (options.volatile?.(read) === true) volatile = true;
-      }
-      if (kind.side === "run") side = "run";
-      // check and effectsOf read the declared effects with the same function (D27).
-      for (const keys of declaredEffects(v)) {
-        const text = keys.join(".");
-        if (!effects.includes(text)) effects.push(text);
-      }
-      if (!isRef(v.doc)) return undefined;
-      const path = v.doc.value;
-      const root = path[0];
-      if (typeof root !== "string" || !(ROOTS as readonly string[]).includes(root)) return undefined;
-      let exact = true;
-      const keys: Key[] = [];
-      for (let index = 1; index < path.length; index += 1) {
-        const step = path[index];
-        if (exact && isKey(step)) {
-          keys.push(step);
-          continue;
-        }
-        exact = false;
-        // A step document runs the walker that the ladder finds for the verb step.
-        const found = isEnvelope(step) ? lookupKind(world, step.type) : undefined;
-        if (found?.ok !== true) {
+  const add = (read: StaticRead): void => {
+    reads.push(read);
+    if (options.volatile?.(read) === true) volatile = true;
+  };
+  /**
+   * This function walks a document. Without `node`, it walks the document of the facts. With `node`, it walks an
+   * equation of a tree kind, and each read gets the place of that node: the first document of the kind.
+   */
+  const scan = (term: unknown, walkOptions: WalkOptions, verb: string, node: DocVisit | undefined): void => {
+    walk(
+      world,
+      term,
+      (v) => {
+        if (node === undefined) size += 1;
+        const up = v.parent === undefined ? undefined : above.get(v.parent);
+        // An equation evaluates only when a demand reaches its attribute, thus each read of an equation is lazy (TREE.LAZY).
+        const lazy = node !== undefined || (up !== undefined && v.parent !== undefined && (up.lazy || partLazy(up, v.parent, v.slot)));
+        const place = node ?? v;
+        const kind = v.kind;
+        if (kind === undefined) {
+          // A kind that the world does not have gives #KIND?, and the walk does not visit its value.
           pure = false;
-          continue;
+          above.set(v, { lazy, rules: undefined });
+          return undefined;
+        }
+        const code = codeOf(world, v.declared ? undefined : v.doc.own, kind, verb, "eval");
+        const answer = code.name === undefined ? undefined : hook?.(v.typePath ?? [], code.name);
+        let roots: readonly Root[] | undefined;
+        if (code.described) {
+          note(answer?.pure ?? kind.pure, answer?.volatile ?? kind.volatile);
+          above.set(v, { lazy, rules: answer?.lazy ?? kind.lazy });
+          roots = answer?.reads ?? kind.reads;
+        } else {
+          // The contract of the kind does not describe this code. Only the hook can.
+          note(answer?.pure, answer?.volatile);
+          above.set(v, { lazy, rules: answer?.lazy ?? EACH });
+          roots = answer?.reads;
         }
-        const walker = codeOf(world, (step as { readonly own?: Readonly<Record<string, string>> }).own, found.kind, "step", "step");
-        const stepAnswer = walker.name === undefined ? undefined : hook?.(found.path, walker.name);
-        if (walker.described) note(stepAnswer?.pure ?? found.kind.pure, stepAnswer?.volatile ?? found.kind.volatile);
-        else note(stepAnswer?.pure, stepAnswer?.volatile);
-      }
-      const first = path[1];
-      // A reference to a name that a kind around it binds reads inside the document: it is not a read.
-      if (root === "names" && isKey(first) && v.names.has(String(first))) return undefined;
-      const read: StaticRead = { root: root as Root, keys: tight(keys), exact, lazy, address: v.address === true, path, place: tight(v.place), at: tight(v.at) };
-      reads.push(read);
-      if (options.volatile?.(read) === true) volatile = true;
-      return undefined;
-    },
-    options.declaredType === undefined ? {} : { declaredType: options.declaredType },
-  );
+        // The code of the kind resolves each of these roots as a whole, at the place of its document (FACTS.KIND-READS).
+        for (const root of roots ?? NONE) {
+          // In an equation, the root self is the node, thus its read is not free (READS.EQUATION).
+          if (node !== undefined && root === "self") continue;
+          add({ root, keys: NONE, exact: true, lazy, address: false, path: [root], place: tight(place.place), at: tight(place.at) });
+        }
+        // An equation evaluates without capabilities, thus an effect in it never reaches the host. It is still not pure.
+        if (kind.side === "run") {
+          if (node === undefined) side = "run";
+          else pure = false;
+        }
+        // check and effectsOf read the declared effects with the same function (D27).
+        for (const keys of declaredEffects(v)) {
+          if (node !== undefined) {
+            pure = false;
+            continue;
+          }
+          const text = keys.join(".");
+          if (!effects.includes(text)) effects.push(text);
+        }
+        // The equations of a tree kind are code of the kind. The first document of the kind gets their reads (FACTS.EQUATIONS).
+        if (kind.tree !== undefined && !(seen ??= new Set()).has(kind)) {
+          seen.add(kind);
+          const of = equationType(kind);
+          for (const { term: equation, names } of equationsOf(kind)) scan(equation, of === undefined ? { names } : { names, declaredType: of }, "eval", place);
+        }
+        if (!isRef(v.doc)) return undefined;
+        const path = v.doc.value;
+        const root = path[0];
+        if (typeof root !== "string" || !(ROOTS as readonly string[]).includes(root)) return undefined;
+        // In an equation, the root self is the node, thus its read is not free. A step out of the tree reads the outer
+        // self through the node, and the read of the whole root self that the tree node makes covers it (TREE.SELF).
+        if (node !== undefined && root === "self") return undefined;
+        let exact = true;
+        const keys: Key[] = [];
+        for (let index = 1; index < path.length; index += 1) {
+          const step = path[index];
+          if (exact && isKey(step)) {
+            keys.push(step);
+            continue;
+          }
+          exact = false;
+          // A step document runs the walker that the ladder finds for the verb step.
+          const found = isEnvelope(step) ? lookupKind(world, step.type) : undefined;
+          if (found?.ok !== true) {
+            pure = false;
+            continue;
+          }
+          const walker = codeOf(world, (step as { readonly own?: Readonly<Record<string, string>> }).own, found.kind, "step", "step");
+          const stepAnswer = walker.name === undefined ? undefined : hook?.(found.path, walker.name);
+          if (walker.described) note(stepAnswer?.pure ?? found.kind.pure, stepAnswer?.volatile ?? found.kind.volatile);
+          else note(stepAnswer?.pure, stepAnswer?.volatile);
+        }
+        const first = path[1];
+        // A reference to a name that a kind around it binds reads inside the document: it is not a read. The names of
+        // an equation are names that its rung binds (TREE.DOWN, TREE.FOLD).
+        if (root === "names" && isKey(first) && v.names.has(String(first))) return undefined;
+        add({ root: root as Root, keys: tight(keys), exact, lazy, address: v.address === true, path, place: tight(place.place), at: tight(place.at) });
+        return undefined;
+      },
+      walkOptions,
+    );
+  };
+  scan(doc, options.declaredType === undefined ? {} : { declaredType: options.declaredType }, options.verb ?? "eval", undefined);
   return { reads: tight(reads), side, effects: tight(effects), pure: pure && !volatile && effects.length === 0 && side === "derive", volatile, size };
 }