@mark1russell7/coeval 0.16.0 → 0.17.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. */
@@ -1024,8 +1073,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 +1204,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 });
@@ -1246,6 +1298,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 +1350,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 +1359,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();
@@ -2070,7 +2124,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.
@@ -2126,6 +2180,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 +2239,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 +2277,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 };
 }

package/src/formula.ts

@@ -4,8 +4,8 @@ import { type CompiledPath, type Context, type Resolution, compilePath, valueOfT
 import { type EvalError, type Failed, type Result, Failure, fail, ok, thrown } from "./errors.ts";
 import { type Code, type CompileInput, type CompiledEvaluator, type CompiledPart, type Evaluator, type Machine, type Runtime, resolveCompiled, totalCode } from "./evaluate.ts";
 import { type MachinePart, mergeMachines } from "./merge.ts";
-import { type Domain, type ValueType, HEADER_KEYS, STD_DOMAINS, callable, fieldOf, fits, fnOf, holdsEnvelope, isPrecise, isUnknown, itemOf, join, member, stepType, typeText } from "./types.ts";
-import type { TypeInput, TypeRule } from "./typing.ts";
+import { type Domain, type ValueType, HEADER_KEYS, STD_DOMAINS, callable, fieldOf, fits, fnOf, holdsEnvelope, isPrecise, isUnknown, itemOf, join, member, stepType, typeIssues, typeText } from "./types.ts";
+import type { PartType, TypeInput, TypeRule } from "./typing.ts";
 import { decodeDomain, domainTypeOf } from "./codec.ts";
 import { type StaticRead, factsOf } from "./facts.ts";
 
@@ -33,6 +33,9 @@ export type ExtFn = (data: Json, context: Context, domains?: Readonly<Record<str
  *   `ext.domain`.
  * - `truthy`: the truth of a value for `if`, `and` and `or`. `undefined` is an error `#VALUE!`. The default
  *   accepts only `true` and `false`.
+ * - `truthType`: the value type of a truth for the own `truthy`, for a check of types (TYPE.TRUTH, D81). A test of
+ *   `if` and each term of `and` and `or` must fit it. Without it, the check accepts each type there. A profile without
+ *   `truthy` ignores it, because the default truth needs `bool`.
  * - `otherwise`: the value of an `if` without `else`. The default is `null`. A profile with this key gives its value,
  *   also `undefined`.
  * - `logic`: what `and` and `or` give: a truth value (the default), or the value that decided.
@@ -50,13 +53,15 @@ export type ExtFn = (data: Json, context: Context, domains?: Readonly<Record<str
  *   overloads. An operation without a signature takes and gives `unknown` (TYPE.GRADUAL).
  *
  * A check of types trusts the signatures. Each operation must give a member of the result of each signature that
- * its arguments match. The hook `check` must keep each result in that type.
+ * its arguments match. The hook `check` must keep each result in that type. The function `truthy` must give a truth
+ * for each member of `truthType`.
  */
 export interface FormulaProfile {
   readonly ops?: Readonly<Record<string, OpFn>> | ((name: string) => OpFn | undefined);
   readonly lazy?: Readonly<Record<string, LazyOp>>;
   readonly ext?: Readonly<Record<string, ExtFn>>;
   readonly truthy?: (value: unknown) => boolean | undefined;
+  readonly truthType?: ValueType;
   readonly otherwise?: unknown;
   readonly logic?: "boolean" | "value";
   readonly omit?: (error: EvalError) => boolean;
@@ -266,12 +271,23 @@ function paramsOf(value: unknown): readonly string[] {
 
 /**
  * This function makes the type rules of the formula kit for one profile (TYPE.SYNTH, D25). Each evaluator of the kit
- * holds its rule. The rules read the rules of the profile that change a type: `truthy`, `logic`, `otherwise`, `omit`
- * and `sigs`.
+ * holds its rule. The rules read the rules of the profile that change a type: `truthy`, `truthType`, `logic`,
+ * `otherwise`, `omit` and `sigs`.
  */
 function formulaTypes(profile: FormulaProfile): Readonly<Record<string, TypeRule>> {
-  // Only the default truth accepts nothing but a truth value. A truth of the profile accepts each value.
-  const truth: ValueType | undefined = profile.truthy === undefined ? "bool" : undefined;
+  // The default truth needs a truth value. An own truth needs its declared type, or nothing without a declaration (D81).
+  const declared = profile.truthy !== undefined && profile.truthType !== undefined;
+  const truth: ValueType | undefined = profile.truthy === undefined ? "bool" : profile.truthType;
+  /**
+   * The need of a test or a term. The check examines a declared type of a truth as a contract, one time. A declared
+   * type with a problem needs nothing, thus one problem gives one issue.
+   */
+  const truthPart = (input: TypeInput, what: string): PartType => {
+    if (truth === undefined) return {};
+    if (!declared) return { expect: truth, what };
+    const type = input.contract(truth, "truth type of the profile");
+    return typeIssues(type, input.machine.domains).length > 0 ? {} : { expect: type, what };
+  };
   const logicValue = profile.logic === "value";
   const otherwise = Object.hasOwn(profile, "otherwise") ? valueType(profile.otherwise) : "null";
   const lookup = (name: string): readonly unknown[] | undefined => {
@@ -307,7 +323,7 @@ function formulaTypes(profile: FormulaProfile): Readonly<Record<string, TypeRule
     return { sigs, bad: sigs.length !== raw.length };
   };
   const logic = (word: "and" | "or"): TypeRule => ({
-    part: (_input, path) => (truth === undefined ? {} : { expect: truth, what: `term ${Number(path[0]) + 1} of ${word}` }),
+    part: (input, path) => truthPart(input, `term ${Number(path[0]) + 1} of ${word}`),
     synth: (input) => {
       if (!logicValue) return "bool";
       // With the logic "value", the result is the term that decided, or the last term.
@@ -438,7 +454,7 @@ function formulaTypes(profile: FormulaProfile): Readonly<Record<string, TypeRule
 
     "formula.if": {
       part: (input, path) => {
-        if (path[0] === "test") return truth === undefined ? {} : { expect: truth, what: "test of if" };
+        if (path[0] === "test") return truthPart(input, "test of if");
         return isUnknown(input.expected, input.machine.domains) ? {} : { expect: input.expected, what: `${String(path[0])} branch of if` };
       },
       synth: (input) => {
@@ -518,15 +534,43 @@ export function formulaEvaluators(profile: FormulaProfile = {}): Readonly<Record
   return { ...kitOf(profile).evaluators };
 }
 
+/** The declared truth of a profile: its own `truthy` and its `truthType` (D81). */
+export interface DeclaredTruth {
+  readonly truthy: (value: unknown) => boolean | undefined;
+  readonly truthType: ValueType;
+}
+
+/** The evaluators of the kit that read the truth of a value. */
+const TRUTH_READERS: readonly string[] = ["formula.if", "formula.and", "formula.or"];
+
+/** The declared truth of each evaluator of the kit that reads a truth, for `conforms` (D86). */
+const truthByCode = /* @__PURE__ */ new WeakMap<object, DeclaredTruth>();
+
+/**
+ * This function gives the declared truth of the profile of an evaluator of the kit (D86). Only `formula.if`,
+ * `formula.and` and `formula.or` of a profile with an own `truthy` and a `truthType` have one. The kernel does not
+ * export the function.
+ *
+ * @param code - The evaluator or the runner.
+ * @returns The declared truth, or `undefined`.
+ */
+export function declaredTruthOf(code: unknown): DeclaredTruth | undefined {
+  return (typeof code === "object" || typeof code === "function") && code !== null ? truthByCode.get(code) : undefined;
+}
+
 /** This function makes new evaluators of the formula kit for the fields of one profile. */
 function makeEvaluators(profile: FormulaProfile): Readonly<Record<string, Evaluator>> {
   const evaluators = formulaCode(profile);
   const types = formulaTypes(profile);
+  const { truthy, truthType } = profile;
+  const truth = truthy === undefined || truthType === undefined ? undefined : { truthy, truthType };
   const out: Record<string, Evaluator> = {};
   for (const name of Object.keys(evaluators)) {
     const evaluator = evaluators[name] as CompiledEvaluator;
     const type = Object.hasOwn(types, name) ? types[name] : undefined;
-    out[name] = Object.freeze(type === undefined ? evaluator : { compile: evaluator.compile, type });
+    const made = Object.freeze(type === undefined ? evaluator : { compile: evaluator.compile, type });
+    if (truth !== undefined && TRUTH_READERS.includes(name)) truthByCode.set(made, truth);
+    out[name] = made;
   }
   return Object.freeze(out);
 }
@@ -537,6 +581,7 @@ const PROFILE_KEYS = /* @__PURE__ */ Object.freeze([
   "lazy",
   "ext",
   "truthy",
+  "truthType",
   "otherwise",
   "logic",
   "omit",