@mark1russell7/coeval 0.6.3 → 0.7.1

package/src/evaluate.ts

@@ -1,15 +1,21 @@
-import { type Envelope, type Json, type Key, type TypeRef, isEnvelope, typeName } from "./doc.ts";
+import { type Envelope, type Json, type Key, type TypeRef, isEnvelope, isKey, typeName } from "./doc.ts";
 import { type Split, partsOf, pathMatches } from "./parts.ts";
-import { ask, type Answer } from "./ladder.ts";
-import type { CapsRule, Kind, Side, World } from "./world.ts";
+import { answerOf, ask, type Answer } from "./ladder.ts";
+import type { CapsRule, KindFacts, Side } from "./world.ts";
+import type { Domain } from "./types.ts";
+import type { TypeRule } from "./typing.ts";
 import { type ErrorCode, type EvalError, type Result, Failure, fail, ok, placed, thrown, describe } from "./errors.ts";
 import {
   type Cap,
+  type CompiledPath,
   type Context,
+  type Hop,
   type Navigator,
   type Resolution,
   type ResolveOptions,
+  type Root,
   type Thing,
+  ROOTS,
   context as makeRootContext,
   isHostThing,
   resolve,
@@ -126,6 +132,40 @@ export function partCaps(rules: readonly CapsRule[] | undefined, path: readonly
   return capsUnder(rulesFor(rules, path), caps);
 }
 
+/**
+ * The key of the grant of a context (CAP.NARROW-CODE): the capabilities that the kernel gave the document of the
+ * context. A spread of a context keeps its grant. Thus compiled code passes the grant on in each context that it makes
+ * from the context of its document. Only the kernel writes a grant.
+ */
+const GRANT = /* @__PURE__ */ Symbol("coeval.grant");
+
+/** A context with the grant of the kernel. */
+type Granted = Context & { readonly [GRANT]?: readonly Cap[] };
+
+/**
+ * This function gives a context whose capabilities its grant permits (CAP.NARROW-CODE). A context whose grant is its
+ * own list of capabilities stays the same object. Each other context keeps only the capabilities that its grant
+ * permits, and a context without a grant keeps none. The result has the grant of its capabilities.
+ */
+function granted(ctx: Context): Context {
+  const grant = (ctx as Granted)[GRANT];
+  if (grant === ctx.caps) return ctx;
+  const caps = grant === undefined ? NO_CAPS : ctx.caps.every((cap) => permits(grant, cap)) ? ctx.caps : ctx.caps.filter((cap) => permits(grant, cap));
+  const out: Granted = { ...ctx, caps, [GRANT]: caps };
+  return out;
+}
+
+/**
+ * This function gives the context of a part of a function evaluator. It is the context that the evaluator gives,
+ * narrowed by the context of the document (CAP.NARROW), with the grant of its capabilities.
+ */
+function handed(parent: Context, next: Context): Context {
+  const ctx = narrow(parent, next);
+  if ((ctx as Granted)[GRANT] === ctx.caps) return ctx;
+  const out: Granted = { ...ctx, [GRANT]: ctx.caps };
+  return out;
+}
+
 /**
  * The steps of an evaluation that can wait. It yields a promise only when the host makes it wait. A runner takes the
  * result of a part with `yield*`, thus a run goes on at once until an effect waits. A runner does not yield a
@@ -164,6 +204,86 @@ export interface Effect {
   readonly outcome?: Result;
 }
 
+/**
+ * One read of an evaluation: a path that code resolved, and what the path reached (READS.RECORD, D26). A schedule
+ * keeps the list of the reads of an evaluation. `verifyReads` resolves each free read again in a new context, and it
+ * tells if the old result stays valid.
+ */
+export interface Read {
+  /** The path that the code resolved: its root, and its steps with the value of each step document. */
+  readonly path: readonly unknown[];
+  /**
+   * What the path reached: the thing, or the error of the resolution. A host thing stays a thing. An exception of the
+   * host gives its error value.
+   */
+  readonly reached: Result;
+  /**
+   * `true` when the read reads the context of the evaluation (READS.FREE). A read of a name that a kind binds, for
+   * example a name of `let`, is not free. A read of a `self` that a kind sets is not free either, for example a node
+   * of a tree. A path without a root is not free. `verifyReads` resolves only the free reads again.
+   */
+  readonly free: boolean;
+  /**
+   * `true` when the kernel adds the read, because a value keeps a root of the context for later (READS.KEPT). Such a
+   * read has the whole root as its path.
+   */
+  readonly kept?: true;
+  /** The hops of the resolution, only when the code asked for them. `verifyReads` then compares each hop too. */
+  readonly hops?: readonly Hop[];
+}
+
+/** The text that names a resolution in the error of an exception of the host. */
+const READ_FAILED = "the resolution of a path";
+
+/**
+ * This function gives what a resolution reached as a result: the thing, or the error with its code and its reason.
+ * The record of a read and `verifyReads` share it.
+ *
+ * @param found - The resolution.
+ * @returns The result.
+ */
+export function reachedOf(found: Resolution): Result {
+  return found.ok ? ok(found.thing) : fail(found.code, found.reason);
+}
+
+/**
+ * This function resolves the path of a read, and it gives an exception of the host as an error value. The record of
+ * a kept read and `verifyReads` use it.
+ *
+ * @param nav - The world and the code of the evaluators.
+ * @param ctx - The context.
+ * @param path - The path.
+ * @param hops - `true` records each hop.
+ * @returns What the path reached, and the hops when the resolution gave them.
+ */
+export function readAgain(nav: Navigator, ctx: Context, path: readonly unknown[], hops: boolean): { readonly reached: Result; readonly hops?: readonly Hop[] } {
+  try {
+    const found = resolve(nav, ctx, path, hops ? WITH_HOPS : WITHOUT_HOPS);
+    return hops ? { reached: reachedOf(found), hops: found.hops } : { reached: reachedOf(found) };
+  } catch (error) {
+    return { reached: thrown(error, READ_FAILED) };
+  }
+}
+
+/**
+ * This function tells if a read reads the context at the root of the evaluation (READS.FREE). A kind can bind a name
+ * or set `self` for its parts, and a read of that binding is not free. A path without a root reads no context. A read
+ * of each other root is free. When a kind changes such a root, the read resolves again to another value, thus
+ * `verifyReads` only does more work.
+ */
+function isFree(root: Context, ctx: Context, path: readonly unknown[]): boolean {
+  const head = path[0];
+  if (head === "self") return ctx === root || Object.is(ctx.self, root.self);
+  if (head !== "names") return typeof head === "string" && (ROOTS as readonly string[]).includes(head);
+  if (ctx === root || ctx.names === root.names) return true;
+  const name = path[1];
+  // A read of the whole record of the names reads each free name too.
+  if (!isKey(name)) return true;
+  const key = String(name);
+  const has = Object.hasOwn(ctx.names, key);
+  return has === Object.hasOwn(root.names, key) && (!has || Object.is(ctx.names[key], root.names[key]));
+}
+
 /**
  * The host side of a run: it does one effect, and gives its result. A throw or a rejection is an error value, and a
  * `Failure` gives its own error value. In an evaluation, this function is a mock: it answers at once, and a promise
@@ -265,7 +385,7 @@ export interface Runtime {
    * This function causes an effect from an evaluator. In a run, an evaluator cannot cause an effect: the host does
    * each effect, thus only a runner can wait for it.
    *
-   * @param ctx - The context of the document.
+   * @param ctx - The context of the document. It gives only the capabilities that the document has (CAP.NARROW-CODE).
    * @param kind - The kind of the effect.
    * @param payload - The data of the effect.
    * @param place - The place of the document.
@@ -276,7 +396,7 @@ export interface Runtime {
    * This function causes an effect from a runner. In a run, the host does it, and the steps wait when the host
    * waits.
    *
-   * @param ctx - The context of the document.
+   * @param ctx - The context of the document. It gives only the capabilities that the document has (CAP.NARROW-CODE).
    * @param kind - The kind of the effect.
    * @param payload - The data of the effect.
    * @param place - The place of the document.
@@ -291,6 +411,12 @@ export interface Runtime {
    * @returns The steps that give each result, in the order of the list.
    */
   all(list: readonly (() => Steps)[], options?: AllOptions): Generator<Promise<unknown>, readonly Result[], unknown>;
+  /**
+   * This optional function tells the runtime that a value keeps the context for later, for example a closure of
+   * `fn`. A later use of the value reads that context, and no evaluation records these reads. Thus the list of reads
+   * gets a read of each root of the context (READS.KEPT).
+   */
+  keepsContext?(): void;
 }
 
 /**
@@ -305,10 +431,17 @@ export interface AllOptions {
   readonly failFast?: boolean;
 }
 
-/** Compiled code: the evaluation of a document in a context. */
+/**
+ * Compiled code: the evaluation of a document in a context. The code gives each part a context that it makes from
+ * its own context with a spread. The part then keeps only the capabilities of the document (CAP.NARROW-CODE). A
+ * context that the code makes without a spread gives the part no capabilities.
+ */
 export type Code = (ctx: Context, rt: Runtime) => Result;
 
-/** Compiled code that can wait: the run of a document in a context. */
+/**
+ * Compiled code that can wait: the run of a document in a context. Its parts keep only the capabilities of the
+ * document, as for `Code`.
+ */
 export type RunCode = (ctx: Context, rt: Runtime) => Steps;
 
 /** A compiled part: its place in its parent, its binding name, and its code. It has no field with its value. */
@@ -390,6 +523,8 @@ export interface EvalInput {
   readonly context: Context;
   /** The keys from the root document to this document. */
   readonly place: readonly Key[];
+  /** The machine of the evaluation, for example for its domains (D40). The kernel sets it. */
+  readonly machine?: Machine;
   /** `true` when the position of the document declares an address. */
   readonly address?: boolean;
   /**
@@ -447,6 +582,8 @@ export interface RunInput {
   readonly parts: readonly RunPart[];
   readonly context: Context;
   readonly place: readonly Key[];
+  /** The machine of the evaluation, for example for its domains (D40). The kernel sets it. */
+  readonly machine?: Machine;
   resolve(path: readonly unknown[], options?: ResolveOptions): Resolution;
   /**
    * This function causes an effect. In a run, the host does the effect, and the steps wait when the host waits. In
@@ -488,6 +625,11 @@ export interface CompiledEvaluator {
    * @returns The code that evaluates the document.
    */
   readonly compile: (input: CompileInput) => Code;
+  /**
+   * The type rule of the evaluator: the value types that a check of types gives its documents and their parts
+   * (TYPE.RULE). Only a check reads it. An evaluator without a rule gives `unknown`.
+   */
+  readonly type?: TypeRule;
 }
 
 /** An evaluator: a function of its input, or a compiler. */
@@ -517,8 +659,11 @@ export type Runner = RunFn | CompiledRunner;
  * A machine: a world of kinds, and the code of each evaluator name, of each `deref` and of each walker.
  *
  * - `maxDepth`: the deepest nesting of documents. The default is 1000.
- * - `permits`: the rule of the host for an effect. The default is the function `permits` on the capabilities.
+ * - `permits`: the rule of the host for an effect. The default is the function `permits` on the capabilities. A run,
+ *   `check` and `effectsOf` ask it (CAP.PERMITS). In a check, its context has only the capabilities and the world.
  * - `known`: the names that the evaluators know, for `check`. Without it, `check` does not check such names.
+ * - `domains`: the value domains of the language, by the name of their base type (D22).
+ * - `facts`: the static facts of the names that a fallback kind covers, for `factsOf` (D24).
  */
 export interface Machine extends Navigator {
   readonly evaluators: Readonly<Record<string, Evaluator>>;
@@ -532,10 +677,26 @@ export interface Machine extends Navigator {
    * `check` asks it for each document with an evaluator. The function must be pure.
    *
    * @param path - The keys of the kind of the document, after each alias.
-   * @param evaluator - The name of the evaluator that the ladder gives the document.
+   * @param evaluator - The name of the evaluator that the ladder of the verb of the check gives the document.
    * @returns `true` when the evaluator knows the name, or else the reason of the `#NAME?` that a run gives.
    */
   readonly known?: (path: readonly Key[], evaluator: string) => true | string;
+  /**
+   * The value domains of the language, by the name of their base type, for example a color or a unit of length. A
+   * check reads them through `fits` and `member`. A domain of the kernel that the table does not name comes from
+   * `STD_DOMAINS`.
+   */
+  readonly domains?: Readonly<Record<string, Domain>>;
+  /**
+   * This function gives the static facts of the code of a name, for `factsOf` (D24). An example is the operation
+   * `["ops", "now"]` of a formula language: a fallback kind names it, and only the language knows that it is volatile.
+   * Each field of the answer wins over the same field of the contract of the kind. The function must be pure.
+   *
+   * @param path - The keys of the kind of the document, after each alias.
+   * @param code - The name of the evaluator of the document, or of the walker of a step document.
+   * @returns The facts, or `undefined` for the facts of the contract.
+   */
+  readonly facts?: (path: readonly Key[], code: string) => KindFacts | undefined;
 }
 
 /** One evaluation in a trace. The children are the evaluations of its parts, in the order that they started. */
@@ -547,7 +708,7 @@ export interface TraceNode {
   readonly doc: Envelope;
   /** `true` when the type came from the container and not from an envelope. */
   readonly declared: boolean;
-  /** The answer of the ladder to the verb `eval`. */
+  /** The answer of the ladder to the verb of the plan, `eval` by default. */
   readonly answer: Answer;
   readonly side: Side;
   /** The names that the document could read when its evaluation started. */
@@ -629,8 +790,18 @@ export interface RunOptions {
   readonly perform?: Perform;
   /** The type of a bare root value. */
   readonly declaredType?: string;
+  /**
+   * The verb of `run`, for example `format`. The default is `eval` (VERB.PREPARE). A plan keeps the verb of its
+   * `prepare`, thus `plan.run` does not read this option.
+   */
+  readonly verb?: string;
   /** A signal of the host. When it aborts, the run stops with `#ABORT`. */
   readonly signal?: StopSignal;
+  /**
+   * A list that gets each read, in the order of the resolutions (READS.RECORD). Under `all`, the order of the host
+   * decides the order of the reads of the items.
+   */
+  readonly reads?: Read[];
 }
 
 /** The options of an evaluation of a plan. */
@@ -642,20 +813,45 @@ export interface EvalOptions {
    * Without it, an effect gives its payload (RUN.EVAL).
    */
   readonly perform?: Perform;
+  /**
+   * A list that gets each read, in the order of the resolutions (READS.RECORD). Without it, the plan records no read,
+   * and each resolution costs one more test.
+   */
+  readonly reads?: Read[];
 }
 
 /** The options of `evaluate`. */
 export interface EvaluateOptions {
   /** The type of a bare root value. */
   readonly declaredType?: string;
+  /** The verb that goes up the ladder at each document, for example `format`. The default is `eval` (VERB.PREPARE). */
+  readonly verb?: string;
   /** The mock of the host (RUN.MOCK). Without it, an effect gives its payload (RUN.EVAL). */
   readonly perform?: Perform;
+  /** A list that gets each read, in the order of the resolutions (READS.RECORD). */
+  readonly reads?: Read[];
 }
 
 /** The options of a resolution without a record of hops, and with one. One object of each serves each call. */
 const WITHOUT_HOPS: ResolveOptions = /* @__PURE__ */ Object.freeze({ hops: false });
 const WITH_HOPS: ResolveOptions = /* @__PURE__ */ Object.freeze({ hops: true });
 
+/** The record of the reads of one evaluation (READS.RECORD). */
+interface Reading {
+  readonly list: Read[];
+  /** The context at the root of the evaluation. A free read has the binding of this context. */
+  readonly root: Context;
+  /** `true` after the kernel added a read of each root (READS.KEPT). */
+  kept: boolean;
+  /** `true` after the kernel added the read of the root `self`. */
+  self: boolean;
+}
+
+/** This function makes the record of the reads of an evaluation, when the host gives a list. */
+function readingOf(list: Read[] | undefined, root: Context): Reading | undefined {
+  return list === undefined ? undefined : { list, root, kept: false, self: false };
+}
+
 /** This class holds the state of one evaluation or run: the machine, the effects, the clock and the trace. */
 class Session implements Runtime {
   /** The list of the effects. It is made at the first effect, thus an evaluation without effects makes no list. */
@@ -677,6 +873,8 @@ 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,
   ) {
     this.list = effects;
     this.holder = traced ? holderNode() : undefined;
@@ -689,16 +887,77 @@ class Session implements Runtime {
   }
 
   resolve(ctx: Context, path: readonly unknown[], options?: ResolveOptions): Resolution {
+    return this.read(ctx, path, undefined, options);
+  }
+
+  /**
+   * This function resolves a compiled path (PLAN.PATH). Without a list of reads and without a trace, the compiled
+   * path answers at once. Each other resolution records its read, as `resolve` does.
+   */
+  resolvePath(ctx: Context, compiled: CompiledPath): Resolution {
+    if (this.reading === undefined && !this.traced && compiled.nav === this.machine) return compiled.resolve(ctx);
+    return this.read(ctx, compiled.path, compiled, undefined);
+  }
+
+  /** This function resolves a path, and records its read when the evaluation has a list of reads (READS.RECORD). */
+  private read(ctx: Context, path: readonly unknown[], compiled: CompiledPath | undefined, options: ResolveOptions | undefined): Resolution {
     const hops = options?.hops ?? this.traced;
+    const reading = this.reading;
+    if (reading === undefined) return this.find(ctx, path, compiled, hops);
+    const free = isFree(reading.root, ctx, path);
+    // A kind that sets another self can give the old self on, as the parent of a node of a tree does (READS.KEPT).
+    if (!free && path[0] === "self" && !reading.self) this.keep(reading, ["self"]);
+    let found: Resolution;
+    try {
+      found = this.find(ctx, path, compiled, hops);
+    } catch (error) {
+      reading.list.push({ path, reached: thrown(error, READ_FAILED), free });
+      throw error;
+    }
+    const asked = options?.hops === true;
+    reading.list.push(asked ? { path, reached: reachedOf(found), free, hops: found.hops } : { path, reached: reachedOf(found), free });
+    return found;
+  }
+
+  /**
+   * This function resolves the steps of a path. A compiled path of this machine answers a resolution without hops. A
+   * resolution with hops, and a path that compiled for another navigator, resolve the steps again.
+   */
+  private find(ctx: Context, path: readonly unknown[], compiled: CompiledPath | undefined, hops: boolean): Resolution {
+    if (compiled !== undefined && !hops && compiled.nav === this.machine) return compiled.resolve(ctx);
     return resolve(this.machine, ctx, path, hops ? WITH_HOPS : WITHOUT_HOPS);
   }
 
+  keepsContext(): void {
+    const reading = this.reading;
+    if (reading === undefined || reading.kept) return;
+    reading.kept = true;
+    this.keep(reading, reading.self ? ROOTS.filter((root) => root !== "self") : ROOTS);
+  }
+
+  /**
+   * This function adds a read of each whole root to the list, from the context at the root (READS.KEPT). An exception
+   * of the host gives the error value of the read, because the evaluation did not ask for the read.
+   */
+  private keep(reading: Reading, roots: readonly Root[]): void {
+    for (const root of roots) {
+      if (root === "self") reading.self = true;
+      const path = [root];
+      reading.list.push({ path, reached: readAgain(this.machine, reading.root, path, false).reached, free: true, kept: true });
+    }
+  }
+
   private permitted(ctx: Context, keys: readonly Key[]): boolean {
     return this.machine.permits === undefined ? permits(ctx.caps, keys) : this.machine.permits(ctx.caps, keys, ctx);
   }
 
-  /** This function checks the capability of an effect, and records the effect with its address (RUN.ADDRESS). */
-  private record(ctx: Context, kind: Cap, payload: unknown, place: readonly Key[]): Result | Recorded {
+  /**
+   * 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).
+   */
+  private record(given: Context, kind: Cap, payload: unknown, place: readonly Key[]): Result | Recorded {
+    const ctx = granted(given);
     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 });
@@ -897,6 +1156,19 @@ class Session implements Runtime {
   }
 }
 
+/**
+ * This function resolves a compiled path through a runtime (PLAN.PATH). The runtime of the kernel uses the compiled
+ * path. Each other runtime gets the steps through `resolve`, thus a runtime that wraps another runtime sees each path.
+ *
+ * @param rt - The runtime.
+ * @param ctx - The context.
+ * @param compiled - The compiled path, from `compilePath`.
+ * @returns What the path reached, or an error.
+ */
+export function resolveCompiled(rt: Runtime, ctx: Context, compiled: CompiledPath): Resolution {
+  return rt instanceof Session ? rt.resolvePath(ctx, compiled) : rt.resolve(ctx, compiled.path);
+}
+
 function holderNode(): Building {
   return {
     id: -1,
@@ -917,13 +1189,25 @@ function holderNode(): Building {
   };
 }
 
-/** This function drives steps that cannot wait. */
-function drive(steps: Steps): Result {
+/**
+ * This function gives the reason of a runner that waits where its parent cannot wait (RUN.WAIT). The plan, the
+ * reference and `check` with the option `run` give the same reason.
+ *
+ * @param kindText - The text of the type of the runner document.
+ * @returns The reason.
+ */
+export function waitedReason(kindText: string): string {
+  return `${kindText} waits for effects, and its parent cannot wait. Give the parent a runner.`;
+}
+
+/** 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();
   if (step.done === true) return step.value;
   void step.value.catch(() => undefined);
-  void steps.return(fail("#CALC!", "A part waited, and its parent cannot wait."));
-  return fail("#CALC!", "A part waited, and its parent cannot wait.");
+  const waited = fail("#CALC!", waitedReason(kindText));
+  void steps.return(waited);
+  return waited;
 }
 
 const ABORTED = /* @__PURE__ */ Symbol("aborted");
@@ -976,6 +1260,11 @@ export interface PrepareOptions {
   readonly declaredType?: string;
   /** `true`: each evaluation records a trace. The default is `false`. */
   readonly trace?: boolean;
+  /**
+   * The verb that goes up the ladder at each document, for example `format`. Each part evaluates with the same verb.
+   * The default is `eval` (VERB.PREPARE).
+   */
+  readonly verb?: string;
 }
 
 /** A compiled document. It evaluates many times, and it does the work of the ladder one time. */
@@ -990,7 +1279,7 @@ export interface Plan {
    * effect at once (RUN.MOCK).
    *
    * @param context - The names and the capabilities at the root.
-   * @param options - A list that gets the effects, and the mock of the host.
+   * @param options - A list that gets the effects, the mock of the host and a list that gets the reads.
    * @returns The result.
    */
   evaluate(context?: Context, options?: EvalOptions): Result;
@@ -998,7 +1287,7 @@ export interface Plan {
    * This function runs the document: the host does each effect, and the run waits when the host waits.
    *
    * @param context - The names and the capabilities at the root.
-   * @param options - The host code that does the effects, and a signal to stop the run.
+   * @param options - The host code that does the effects, a signal to stop the run and a list that gets the reads.
    * @returns The result, when the run ends.
    */
   run(context?: Context, options?: RunOptions): Promise<Result>;
@@ -1008,23 +1297,31 @@ interface Compiler {
   readonly machine: Machine;
   readonly traced: boolean;
   readonly maxDepth: number;
+  /** The verb that goes up the ladder at each document. */
+  readonly verb: string;
+  /** The answer of a document that the ladder did not see, in a trace. */
+  readonly noAnswer: Answer;
 }
 
-function failing(c: Compiler, meta: Meta, place: readonly Key[], code: ErrorCode, reason: string): { readonly code: Code; readonly run: RunCode } {
+function failing(c: Compiler, meta: Meta, place: readonly Key[], code: ErrorCode, reason: string): Compiled {
   return failingWith(c, meta, fail(code, reason, { place }));
 }
 
 /** This function gives the code of a document that fails with one result at each evaluation. */
-function failingWith(c: Compiler, meta: Meta, result: Result): { readonly code: Code; readonly run: RunCode } {
+function failingWith(c: Compiler, meta: Meta, result: Result): Compiled {
   const plain: Code = () => result;
-  return finish(c, meta, plain, function* () {
-    return result;
-  });
+  return finish(c, meta, plain, undefined);
 }
 
-function finish(c: Compiler, meta: Meta, code: Code, run: RunCode): { readonly code: Code; readonly run: RunCode } {
-  if (!c.traced) return { code, run };
-  const tracedCode: Code = (ctx, rt) => {
+/**
+ * This function gives the code of a document in a trace. Each node records the context that its grant permits
+ * (CAP.NARROW-CODE), as the code of the document gets it.
+ */
+function finish(c: Compiler, meta: Meta, code: Code, steps: RunCode | undefined): Compiled {
+  if (!c.traced) return { code, run: steps };
+  const run = steps ?? runOf(code);
+  const tracedCode: Code = (given, rt) => {
+    const ctx = granted(given);
     const s = rt as Session;
     const node = s.enter(meta, ctx);
     const before = s.current;
@@ -1038,7 +1335,8 @@ function finish(c: Compiler, meta: Meta, code: Code, run: RunCode): { readonly c
     s.exit(node, result);
     return result;
   };
-  const tracedRun: RunCode = function* (ctx, rt) {
+  const tracedRun: RunCode = function* (given, rt) {
+    const ctx = granted(given);
     const s = rt as Session;
     const node = s.enter(meta, ctx);
     const steps = run(ctx, rt);
@@ -1069,47 +1367,34 @@ function finish(c: Compiler, meta: Meta, code: Code, run: RunCode): { readonly c
   return { code: tracedCode, run: tracedRun };
 }
 
-/**
- * This function finds the evaluator of the verb `eval` without the record of the rungs, for a compilation without a
- * trace. It gives the same evaluator as `ask`: the own entry, then the kind, then the default of the world.
- */
-function evaluatorOf(world: World, envelope: Envelope | undefined, kind: Kind | undefined): { readonly name?: string; readonly unknown: boolean } {
-  const own = envelope?.own;
-  const ownName = own !== undefined && Object.hasOwn(own, "eval") ? own["eval"] : undefined;
-  if (ownName !== undefined) return { name: ownName, unknown: false };
-  if (kind === undefined) return { unknown: true };
-  const verbs = kind.verbs;
-  const name = Object.hasOwn(verbs, "eval") ? verbs["eval"] : Object.hasOwn(world.defaults, "eval") ? world.defaults["eval"] : undefined;
-  return name === undefined ? { unknown: false } : { name, unknown: false };
-}
-
 /** The meta of a node of a compilation without a trace. Only a trace reads the meta of a node. */
 const NO_META: Meta = /* @__PURE__ */ Object.freeze({ path: [], doc: { type: "?", value: null }, declared: false, answer: NO_ANSWER, side: "derive" });
 
-function compileNode(c: Compiler, value: unknown, place: readonly Key[], declared: string | undefined, depth: number, address = false): { readonly code: Code; readonly run: RunCode } {
+function compileNode(c: Compiler, value: unknown, place: readonly Key[], declared: string | undefined, depth: number, address = false): Compiled {
   const world = c.machine.world;
   const read = partsOf(world, value, declared);
   if (!read.ok) {
-    const meta: Meta = c.traced ? { path: place.map(String), doc: { type: "?", value: value as Json }, declared: true, answer: NO_ANSWER, side: "derive" } : NO_META;
+    const meta: Meta = c.traced ? { path: place.map(String), doc: { type: "?", value: value as Json }, declared: true, answer: c.noAnswer, side: "derive" } : NO_META;
     return failing(c, meta, place, read.code, read.reason);
   }
   const { doc, kind, split } = read;
   const envelope = read.declared ? undefined : doc;
-  const meta0: Meta = c.traced ? { path: place.map(String), doc, declared: read.declared, answer: NO_ANSWER, side: "derive" } : NO_META;
+  const meta0: Meta = c.traced ? { path: place.map(String), doc, declared: read.declared, answer: c.noAnswer, side: "derive" } : NO_META;
   if (depth > c.maxDepth) return failing(c, meta0, place, "#DEPTH!", `The nesting is deeper than ${c.maxDepth} documents.`);
 
   let meta = meta0;
   let name: string | undefined;
   let unknown: boolean;
   if (c.traced) {
-    const answer = ask(world, envelope ?? {}, "eval", declared === undefined ? {} : { declaredType: declared });
+    const answer = ask(world, envelope ?? {}, c.verb, declared === undefined ? {} : { declaredType: declared });
     meta = { ...meta0, answer, side: kind?.side ?? "derive" };
     name = answer.evaluator;
     unknown = answer.error === "unknown-kind";
   } else {
-    const quick = evaluatorOf(world, envelope, kind);
-    name = quick.name;
-    unknown = quick.unknown;
+    // A document has a type here, thus a kind that the read did not find is a kind that the world does not have.
+    const quick = answerOf(world, envelope?.own, kind ?? null, c.verb);
+    name = quick?.name;
+    unknown = quick === undefined && kind === undefined;
   }
   const kindText = typeName(doc.type);
   if (unknown) return failing(c, meta, place, "#KIND?", `The world has no kind ${kindText}.`);
@@ -1129,9 +1414,10 @@ function compileNode(c: Compiler, value: unknown, place: readonly Key[], declare
     const compiled = rules.length === 0 ? own : gated(rules, own);
     // The binding name is in the header of an envelope. Most parts have no name, thus the cheap test comes first.
     const header = typeof (item as { readonly name?: unknown } | null)?.name === "string" && isEnvelope(item) ? (item as { readonly name: string }).name : undefined;
+    const run = compiled.run ?? runOf(compiled.code);
     return header === undefined
-      ? { key: slot.key, path: slot.path, code: compiled.code, run: compiled.run }
-      : { key: slot.key, path: slot.path, name: header, code: compiled.code, run: compiled.run };
+      ? { key: slot.key, path: slot.path, code: compiled.code, run }
+      : { key: slot.key, path: slot.path, name: header, code: compiled.code, run };
   });
   const typePath = read.typePath ?? [];
   const input: CompileInput = {
@@ -1164,8 +1450,7 @@ function compileNode(c: Compiler, value: unknown, place: readonly Key[], declare
   } catch (error) {
     return failingWith(c, meta, placed(thrown(error, `the evaluator ${name}`), place));
   }
-  const code = placedCode(inner, place, name);
-  return finish(c, meta, code, runOf(code));
+  return finish(c, meta, placedCode(inner, place, name), undefined);
 }
 
 /*
@@ -1174,11 +1459,14 @@ function compileNode(c: Compiler, value: unknown, place: readonly Key[], declare
  * the split of the value. Thus a plan with these helpers keeps only its code.
  */
 
-/** This function gives the code of a document: the code of its evaluator, with the place of each error and of each exception. */
+/**
+ * This function gives the code of a document: the code of its evaluator, with the place of each error and of each
+ * exception. The code gets the context that its grant permits, thus a compiled parent cannot widen it (CAP.NARROW-CODE).
+ */
 function placedCode(inner: Code, place: readonly Key[], name: string): Code {
   return (ctx, rt) => {
     try {
-      return placed(inner(ctx, rt), place);
+      return placed(inner(granted(ctx), rt), place);
     } catch (error) {
       return placed(thrown(error, `the evaluator ${name}`), place);
     }
@@ -1187,23 +1475,31 @@ function placedCode(inner: Code, place: readonly Key[], name: string): Code {
 
 /**
  * This function gives the code of a part that capability rules cover. The code narrows the context of the part by
- * the rules before the part starts.
+ * the rules before the part starts. First the context keeps only the capabilities of its grant, thus a compiled
+ * parent cannot widen the capabilities that the rules narrow (CAP.NARROW-CODE).
  */
-function gated(rules: readonly CapsRule[], part: { readonly code: Code; readonly run: RunCode }): { readonly code: Code; readonly run: RunCode } {
+function gated(rules: readonly CapsRule[], part: Compiled): Compiled {
   const inner = part.code;
   const steps = part.run;
-  const under = (ctx: Context): Context => {
+  const under = (given: Context): Context => {
+    const ctx = granted(given);
     const caps = capsUnder(rules, ctx.caps);
-    return caps === ctx.caps || (caps.length === 0 && ctx.caps.length === 0) ? ctx : { ...ctx, caps };
+    if (caps === ctx.caps || (caps.length === 0 && ctx.caps.length === 0)) return ctx;
+    const out: Granted = { ...ctx, caps, [GRANT]: caps };
+    return out;
   };
-  return { code: (ctx, rt) => inner(under(ctx), rt), run: (ctx, rt) => steps(under(ctx), rt) };
+  // The steps of an evaluator are `runOf` of its code, thus `runOf` of this code narrows the context the same way.
+  return { code: (ctx, rt) => inner(under(ctx), rt), run: steps === undefined ? undefined : (ctx, rt) => steps(under(ctx), rt) };
 }
 
-/** This function gives the steps of a runner, with the place of each error and of each exception. */
+/**
+ * This function gives the steps of a runner, with the place of each error and of each exception. The steps get the
+ * context that its grant permits (CAP.NARROW-CODE).
+ */
 function placedRun(inner: RunCode, place: readonly Key[], name: string): RunCode {
   return function* (ctx, rt) {
     try {
-      return placed(yield* inner(ctx, rt), place);
+      return placed(yield* inner(granted(ctx), rt), place);
     } catch (error) {
       return placed(thrown(error, `the runner ${name}`), place);
     }
@@ -1211,14 +1507,21 @@ function placedRun(inner: RunCode, place: readonly Key[], name: string): RunCode
 }
 
 /**
- * This function gives the code of a runner in an evaluation: its steps, which cannot wait. A step that waits gives
- * `#CALC!` at the place of the runner, where the error started (RUN.WAIT).
+ * 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).
  */
 function runnerCode(run: RunCode, place: readonly Key[], kindText: string): Code {
-  return (ctx, rt) =>
-    rt.running
-      ? fail("#CALC!", `${kindText} waits for effects, and its parent cannot wait. Give the parent a runner.`, { place })
-      : placed(drive(run(ctx, rt)), place);
+  return (ctx, rt) => placed(drive(run(ctx, rt), kindText), place);
+}
+
+/**
+ * The code of a compiled document. The steps of a run are `undefined` for an evaluator: they are `runOf(code)`, and a
+ * plan makes them only for a run (PLAN.LEAN).
+ */
+interface Compiled {
+  readonly code: Code;
+  readonly run: RunCode | undefined;
 }
 
 /** This function gives the steps of a run of an evaluator. The code runs at the first step, and it does not wait. */
@@ -1235,8 +1538,10 @@ function fillOf(split: Extract<Split, { readonly ok: true }>, doc: Envelope): <P
 
 
 function interpret(fn: EvalFn, input: CompileInput, fill: <P>(handles: readonly P[]) => unknown): Code {
-  const { kind, typePath, doc, data, place } = input;
+  const { kind, typePath, doc, data, place, machine } = input;
   const address = input.address === true ? { address: true } : {};
+  // The code keeps the fill and not the whole input, thus it does not keep the compiled value of the document (PLAN.LEAN).
+  const refill = input.fill;
   const compiled = input.parts;
   const hasParts = compiled.length > 0;
   return (ctx, rt) => {
@@ -1244,7 +1549,7 @@ function interpret(fn: EvalFn, input: CompileInput, fill: <P>(handles: readonly
       key: part.key,
       path: part.path,
       ...(part.name === undefined ? {} : { name: part.name }),
-      evaluate: (override?: Context) => part.code(override === undefined ? ctx : narrow(ctx, override), rt),
+      evaluate: (override?: Context) => part.code(override === undefined ? ctx : handed(ctx, override), rt),
     }));
     return fn({
       kind,
@@ -1255,16 +1560,18 @@ function interpret(fn: EvalFn, input: CompileInput, fill: <P>(handles: readonly
       parts,
       context: ctx,
       place,
+      machine,
       ...address,
       resolve: (path, options) => rt.resolve(ctx, path, options),
       effect: (effectKind, payload) => rt.effect(ctx, effectKind, payload, place),
-      fill: input.fill,
+      fill: refill,
     });
   };
 }
 
 function interpretRun(fn: RunFn, input: CompileInput, fill: <P>(handles: readonly P[]) => unknown): RunCode {
-  const { kind, typePath, doc, data, place } = input;
+  const { kind, typePath, doc, data, place, machine } = input;
+  const refill = input.fill;
   const compiled = input.parts;
   const hasParts = compiled.length > 0;
   return (ctx, rt) => {
@@ -1272,7 +1579,7 @@ function interpretRun(fn: RunFn, input: CompileInput, fill: <P>(handles: readonl
       key: part.key,
       path: part.path,
       ...(part.name === undefined ? {} : { name: part.name }),
-      evaluate: (override?: Context) => part.run(override === undefined ? ctx : narrow(ctx, override), rt),
+      evaluate: (override?: Context) => part.run(override === undefined ? ctx : handed(ctx, override), rt),
     }));
     return fn({
       kind,
@@ -1283,60 +1590,106 @@ function interpretRun(fn: RunFn, input: CompileInput, fill: <P>(handles: readonl
       parts,
       context: ctx,
       place,
+      machine,
       resolve: (path, options) => rt.resolve(ctx, path, options),
       effect: (effectKind, payload) => rt.runEffect(ctx, effectKind, payload, place),
       all: (list, options) => rt.all(list.map((part) => () => part.evaluate()), options),
-      fill: input.fill,
+      fill: refill,
     });
   };
 }
 
-function rootContext(machine: Machine, ctx: Context): Context {
-  return ctx.world === null ? { ...ctx, world: worldThing(machine.world) } : ctx;
+/**
+ * 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). An evaluation and `verifyReads` share it.
+ *
+ * @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) return ctx;
+  const root: Granted = { ...ctx, world: ctx.world === null ? worldThing(machine.world) : ctx.world, [GRANT]: ctx.caps };
+  return root;
 }
 
 /**
  * This function compiles a document into a plan. The ladder, the kinds and the parts are known after it. A plan
  * evaluates many times. A document that does not compile gives a plan that fails with the reason, when it evaluates.
  *
+ * The verb of the options goes up the ladder at each document, and each part evaluates with the same verb. The
+ * default verb is `eval`. A plan of another verb, for example `format`, evaluates, runs and traces as a plan of
+ * `eval` does (VERB.PREPARE).
+ *
  * @param machine - The world and the code of the evaluators.
  * @param doc - The document, as JSON.
- * @param options - The type of a bare root value, and a trace.
+ * @param options - The type of a bare root value, a trace and the verb.
  * @returns The plan.
  */
 export function prepare(machine: Machine, doc: unknown, options: PrepareOptions = {}): Plan {
-  const c: Compiler = { machine, traced: options.trace === true, maxDepth: machine.maxDepth ?? 1000 };
-  let root: { readonly code: Code; readonly run: RunCode };
+  const verb = options.verb ?? "eval";
+  const noAnswer: Answer = verb === "eval" ? NO_ANSWER : { verb, error: "no-answer", steps: [] };
+  const c: Compiler = { machine, traced: options.trace === true, maxDepth: machine.maxDepth ?? 1000, verb, noAnswer };
+  let root: Compiled;
   try {
     root = compileNode(c, doc, [], options.declaredType, 0);
   } catch (error) {
     const result = placed(thrown(error, "the compilation"), []);
-    root = {
-      code: () => result,
-      run: function* () {
-        return result;
-      },
-    };
+    root = { code: () => result, run: undefined };
   }
-  const compiled: CompiledPart = { key: "", path: [], code: root.code, run: root.run };
-  return planOf(machine, c.traced, compiled);
+  return new CompiledPlan(machine, c.traced, root.code, root.run);
 }
 
-/** This function makes the object of a plan. Its closures keep only the machine and the compiled root. */
-function planOf(machine: Machine, traced: boolean, root: CompiledPart): Plan {
-  return {
-    machine,
-    traced,
-    root,
-    evaluate(context: Context = makeContext(), evalOptions?: EvalOptions): Result {
-      const s = new Session(machine, false, traced, evalOptions?.perform, undefined, evalOptions?.effects);
-      return root.code(rootContext(machine, context), s);
-    },
-    run(context: Context = makeContext(), runOptions: RunOptions = {}): Promise<Result> {
-      const s = new Session(machine, true, traced, runOptions.perform, runOptions.signal, undefined);
-      return driveWaiting(root.run(rootContext(machine, context), s), runOptions.signal);
-    },
-  };
+/**
+ * The object of a plan (PLAN.LEAN). The code of `evaluate` and `run` is on the class, thus a plan keeps only its
+ * machine and its compiled code. A plan makes its compiled root and the steps of a run at their first use.
+ */
+class CompiledPlan implements Plan {
+  /*
+   * The constructor writes each field one time, and the class declares the fields with `declare`. A field that a class
+   * defines first as `undefined` and then writes again is not constant for V8, and the code of an evaluation then
+   * loads it at each call.
+   */
+  declare readonly machine: Machine;
+  declare readonly traced: boolean;
+  /** The code of the root document. */
+  declare readonly code: Code;
+  /** The steps of a run of the root document. `undefined` gives `runOf(code)` at the first `run`. */
+  declare private steps: RunCode | undefined;
+  /** The compiled root, after the first read of `root`. */
+  declare private part: CompiledPart | undefined;
+
+  constructor(machine: Machine, traced: boolean, code: Code, steps: RunCode | undefined) {
+    this.machine = machine;
+    this.traced = traced;
+    this.code = code;
+    this.steps = steps;
+    this.part = undefined;
+  }
+
+  get root(): CompiledPart {
+    return (this.part ??= { key: "", path: [], code: this.code, run: this.runCode() });
+  }
+
+  /** This function gives the steps of a run of the root document. */
+  runCode(): RunCode {
+    return (this.steps ??= runOf(this.code));
+  }
+
+  evaluate(context: Context = makeContext(), evalOptions?: EvalOptions): Result {
+    const machine = this.machine;
+    const ctx = rootContext(machine, context);
+    const s = new Session(machine, false, this.traced, evalOptions?.perform, undefined, evalOptions?.effects, readingOf(evalOptions?.reads, ctx));
+    return this.code(ctx, s);
+  }
+
+  run(context: Context = makeContext(), runOptions: RunOptions = {}): Promise<Result> {
+    const machine = this.machine;
+    const ctx = rootContext(machine, context);
+    const s = new Session(machine, true, this.traced, runOptions.perform, runOptions.signal, undefined, readingOf(runOptions.reads, ctx));
+    return driveWaiting(this.runCode()(ctx, s), runOptions.signal);
+  }
 }
 
 /**
@@ -1359,6 +1712,8 @@ export function planner(machine: Machine, options: PrepareOptions = {}): (doc: u
       }
       return plan;
     }
+    // A map treats -0 and 0 as one key, so -0 gets its own plan each time.
+    if (Object.is(doc, -0)) return prepare(machine, doc, options);
     let plan = values.get(doc);
     if (plan === undefined) {
       plan = prepare(machine, doc, options);
@@ -1378,23 +1733,30 @@ function record(s: Session, result: Result): Run {
 /**
  * This function evaluates a document, and records each evaluation in a trace.
  *
- * The verb `eval` goes up the ladder for each document. The kind of the document tells where its parts are. The
- * evaluator gets each part sealed: it can evaluate the part, and it cannot read its value. A failure gives an error
- * value, and the function does not throw. An effect is recorded in its order, and the host does not do it. A mock
- * can answer each effect at once (RUN.MOCK).
+ * The verb of the options goes up the ladder for each document. The default verb is `eval`. The kind of the document
+ * tells where its parts are. The evaluator gets each part sealed: it can evaluate the part, and it cannot read its
+ * value.
+ *
+ * A failure gives an error value, and the function does not throw. An effect is recorded in its order, and the host
+ * does not do it. A mock can answer each effect at once (RUN.MOCK).
  *
  * @param machine - The world and the code of the evaluators.
  * @param doc - The document, as JSON.
  * @param context - The names and the capabilities at the root.
- * @param options - The type of a bare root value, or the options: that type and the mock of the host.
+ * @param options - The type of a bare root value, or the options: that type, the mock of the host, the verb and a list for the reads.
  * @returns The result, the trace and the effects in their order.
  */
 export function evaluate(machine: Machine, doc: unknown, context: Context = makeContext(), options?: string | EvaluateOptions): Run {
   const given: EvaluateOptions = typeof options === "string" ? { declaredType: options } : (options ?? {});
   const declaredType = given.declaredType;
-  const plan = prepare(machine, doc, { trace: true, ...(declaredType === undefined ? {} : { declaredType }) });
-  const s = new Session(machine, false, true, given.perform, undefined, undefined);
-  const result = plan.root.code(rootContext(machine, context), s);
+  const plan = prepare(machine, doc, {
+    trace: true,
+    ...(declaredType === undefined ? {} : { declaredType }),
+    ...(given.verb === undefined ? {} : { verb: given.verb }),
+  });
+  const ctx = rootContext(machine, context);
+  const s = new Session(machine, false, true, given.perform, undefined, undefined, readingOf(given.reads, ctx));
+  const result = (plan as CompiledPlan).code(ctx, s);
   return record(s, result);
 }
 
@@ -1406,13 +1768,18 @@ export function evaluate(machine: Machine, doc: unknown, context: Context = make
  * @param machine - The world, the evaluators and the runners.
  * @param doc - The document, as JSON.
  * @param context - The names and the capabilities at the root.
- * @param options - The host code that does the effects, the type of a bare root value, and a signal.
+ * @param options - The host code that does the effects, the type of a bare root value, a signal, the verb and a list for the reads.
  * @returns The result, the trace and the effects in their order, when the run ends.
  */
 export async function run(machine: Machine, doc: unknown, context: Context = makeContext(), options: RunOptions = {}): Promise<Run> {
-  const plan = prepare(machine, doc, { trace: true, ...(options.declaredType === undefined ? {} : { declaredType: options.declaredType }) });
-  const s = new Session(machine, true, true, options.perform, options.signal, undefined);
-  const result = await driveWaiting(plan.root.run(rootContext(machine, context), s), options.signal);
+  const plan = prepare(machine, doc, {
+    trace: true,
+    ...(options.declaredType === undefined ? {} : { declaredType: options.declaredType }),
+    ...(options.verb === undefined ? {} : { verb: options.verb }),
+  });
+  const ctx = rootContext(machine, context);
+  const s = new Session(machine, true, true, options.perform, options.signal, undefined, readingOf(options.reads, ctx));
+  const result = await driveWaiting((plan as CompiledPlan).runCode()(ctx, s), options.signal);
   return record(s, result);
 }