@mark1russell7/coeval 0.16.0 → 0.18.0

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";
 
@@ -31,8 +31,13 @@ export type ExtFn = (data: Json, context: Context, domains?: Readonly<Record<str
  * - `lazy`: the operations that evaluate their arguments themselves.
  * - `ext`: the extensions of the namespace `ext`, by their name. The kit has `ext.undefined`, `ext.number` and
  *   `ext.domain`.
+ * - `extTypes`: the value type of each extension of `ext`, by its name, for a check of types (TYPE.EXT, D103). An
+ *   extension without an entry gives `unknown` (TYPE.GRADUAL). An entry for a standard extension has no effect.
  * - `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 +55,16 @@ 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`. Each extension must give a member of its type in `extTypes`.
  */
 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 extTypes?: Readonly<Record<string, ValueType>>;
   readonly truthy?: (value: unknown) => boolean | undefined;
+  readonly truthType?: ValueType;
   readonly otherwise?: unknown;
   readonly logic?: "boolean" | "value";
   readonly omit?: (error: EvalError) => boolean;
@@ -266,12 +274,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`, `sigs` and `extTypes`.
  */
 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 +326,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 +457,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) => {
@@ -494,7 +513,14 @@ function formulaTypes(profile: FormulaProfile): Readonly<Record<string, TypeRule
       synth: (input) => {
         const name = nameOf(input);
         const own = profile.ext !== undefined && Object.hasOwn(profile.ext, name);
-        if (own) return "unknown";
+        if (own) {
+          // The declared type is a contract. A type with a problem gives unknown, thus one problem gives one issue (D103).
+          const types = profile.extTypes;
+          const declared = types !== undefined && Object.hasOwn(types, name) ? types[name] : undefined;
+          if (declared === undefined) return "unknown";
+          const type = input.contract(declared, `type of ext.${name} in extTypes`);
+          return typeIssues(type, input.machine.domains).length > 0 ? "unknown" : type;
+        }
         // The standard extensions give the values that JSON cannot write, thus each has a base type (D48).
         if (name === "undefined") return "undefined";
         if (name === "number") return "number";
@@ -518,15 +544,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);
 }
@@ -536,7 +590,9 @@ const PROFILE_KEYS = /* @__PURE__ */ Object.freeze([
   "ops",
   "lazy",
   "ext",
+  "extTypes",
   "truthy",
+  "truthType",
   "otherwise",
   "logic",
   "omit",

package/src/index.ts

@@ -174,6 +174,7 @@ export {
   STD_RUNNERS,
   STD_WALKERS,
   STD_WORLD,
+  WORLD_SYNTAX,
   attributeTrace,
   nearestWalker,
   placeOf,
@@ -238,8 +239,11 @@ export {
   type ParseResult,
   type SyntaxAssoc,
   type SyntaxCalls,
+  type SyntaxEnvelopes,
   type SyntaxFixity,
   type SyntaxForm,
+  type SyntaxFormArgs,
+  type SyntaxHeader,
   type SyntaxIssue,
   type SyntaxLiterals,
   type SyntaxOperator,
@@ -277,7 +281,25 @@ export {
   agreeSchedule,
 } from "./meaning.ts";
 export { type GraphCycle, type GraphEdge, type GraphNode, type GraphOptions, type NodeGraph, components, cycles, heights, necessary, nodeLayers } from "./graph.ts";
-export { type Recorder, type ReplayEntry, type ReplayLog, type ReplayOptions, type ReplaySettle, recorder, replayer } from "./replay.ts";
+export {
+  type Recorder,
+  type ReplayCausePartsJson,
+  type ReplayEntry,
+  type ReplayEntryJson,
+  type ReplayErrorJson,
+  type ReplayExceptionJson,
+  type ReplayLog,
+  type ReplayLogJson,
+  type ReplayPartJson,
+  type ReplayPartsJson,
+  type ReplayOptions,
+  type ReplayResultJson,
+  type ReplaySettle,
+  decodeLog,
+  encodeLog,
+  recorder,
+  replayer,
+} from "./replay.ts";
 export { type GenerateOptions, type Random, generate, random, typesOf } from "./generate.ts";
 export { type Domain, type DomainCodec, type TypeIssue, type ValueType, STD_DOMAINS, fits, join, member, typeIssues, typeText } from "./types.ts";
 export { type PartType, type RootTypes, type TypeInput, type TypeProblem, type TypeRule, type Typed, CAPS_TYPE } from "./typing.ts";

package/src/merge.ts

@@ -89,32 +89,54 @@ function same(a: unknown, b: unknown): boolean {
 
 /**
  * Two domains are the same when they are one object. They are also the same when they have the same test `is`,
- * parents, summary and steps. Thus two languages that give one test under one name give one domain.
+ * parents, summary, steps, codec, list of values, samples and covers. Thus two languages that give one test under one name give one
+ * domain. Two codecs are the same when they have the same functions `encode` and `decode` (D80).
  */
 function sameDomain(a: Domain, b: Domain): boolean {
-  return a === b || (a.is === b.is && same(a.under ?? [], b.under ?? []) && a.summary === b.summary && same(a.steps ?? {}, b.steps ?? {}));
+  if (a === b) return true;
+  // The type names each field of Domain, thus a new field fails the check of types until the merge compares it (K180).
+  const fields: { readonly [K in keyof Domain]-?: boolean } = {
+    is: a.is === b.is,
+    under: same(a.under ?? [], b.under ?? []),
+    summary: a.summary === b.summary,
+    steps: same(a.steps ?? {}, b.steps ?? {}),
+    codec: same(a.codec ?? null, b.codec ?? null),
+    values: same(a.values ?? null, b.values ?? null),
+    samples: same(a.samples ?? null, b.samples ?? null),
+    covers: same(a.covers ?? [], b.covers ?? []),
+  };
+  return Object.values(fields).every(Boolean);
 }
 
-/** What `extendDomain` adds to a domain: more parents, and the types of more steps. */
+/** What `extendDomain` adds to a domain: more parents, the types of more steps, and more covers. */
 export interface DomainExtension {
   /** The names of the parents to add. A member of the domain then also passes the test of each new parent. */
   readonly under?: readonly string[];
   /** The types of the steps to add. A step with the key of an earlier step replaces its type. */
   readonly steps?: Readonly<Record<string, ValueType>>;
+  /**
+   * The covers to add (TYPE.FITS-COVER, D85). A cover that the domain has already does not change. The language that
+   * adds a cover keeps it true, because `fits` trusts it.
+   */
+  readonly covers?: readonly (readonly string[])[];
 }
 
 /**
- * This function makes a part of a merge that adds parents or steps to a domain of an earlier part (TYPE.PARENTS). An
- * example is a domain of another language. The part reads the domain from the merge before it (`prev`). It gives a
- * copy with the same test and summary, and it names `["domains", name]` in `replaces` (D17). A domain of the kernel
- * that the earlier parts do not name comes from `STD_DOMAINS`.
+ * This function makes a part of a merge that adds parents, steps or covers to a domain of an earlier part
+ * (TYPE.PARENTS). An example is a domain of another language. The part reads the domain from the merge before it
+ * (`prev`). It gives a copy with the same test, summary, codec, list of values and samples, and it names
+ * `["domains", name]` in `replaces` (D17).
+ * A domain of the kernel that the earlier parts do not name comes from `STD_DOMAINS`.
+ *
+ * An extension does not change the codec. Thus each member keeps its document (D80).
  *
  * A new parent adds its test to the domain (TYPE.MEMBER). Thus `fits` stays sound, but a value that fails the test of
  * the parent is no longer a member. The language that adds the parent keeps the signatures of the other language
- * true. A name without a domain gives an empty part, and `typeIssues` reports each use of that name.
+ * true. A new parent of a domain in a cover of another domain can make that cover false (D85). A name without a
+ * domain gives an empty part, and `typeIssues` reports each use of that name.
  *
  * @param name - The name of the domain.
- * @param more - The parents and the steps to add.
+ * @param more - The parents, the steps and the covers to add.
  * @returns The part, as a function of the merge before it.
  */
 export function extendDomain(name: string, more: DomainExtension): (prev: Machine) => MachinePart {
@@ -125,14 +147,27 @@ export function extendDomain(name: string, more: DomainExtension): (prev: Machin
     const under = [...(found.under ?? [])];
     for (const parent of more.under ?? []) if (parent !== name && !under.includes(parent)) under.push(parent);
     const steps = { ...found.steps, ...more.steps };
-    const domain: Domain = {
+    const covers = [...(found.covers ?? [])];
+    for (const cover of more.covers ?? []) if (!covers.some((each) => same(each, cover))) covers.push([...cover]);
+    // The type names each field of Domain, thus a new field fails the check of types until the copy reads it (K180).
+    const fields: { readonly [K in keyof Domain]-?: Domain[K] | undefined } = {
       is: found.is,
-      ...(under.length === 0 ? {} : { under }),
-      ...(found.summary === undefined ? {} : { summary: found.summary }),
-      ...(Object.keys(steps).length === 0 ? {} : { steps }),
+      under: under.length === 0 ? undefined : under,
+      summary: found.summary,
+      steps: Object.keys(steps).length === 0 ? undefined : steps,
+      // A new parent only adds a test, thus each member keeps its document (D80).
+      codec: found.codec,
+      // A new parent only adds a test, thus the list of values stays complete (TYPE.FITS-FINITE).
+      values: found.values,
+      // A sample outside the new line does not count, thus the samples stay (D99).
+      samples: found.samples,
+      // A new parent only adds a test, thus each cover stays true (TYPE.FITS-COVER). A new cover is a claim of the extension.
+      covers: covers.length === 0 ? undefined : covers,
     };
+    const domain: Record<string, unknown> = {};
+    for (const [key, value] of Object.entries(fields)) if (value !== undefined) domain[key] = value;
     const domains: Record<string, Domain> = {};
-    setOwn(domains, name, domain);
+    setOwn(domains, name, domain as unknown as Domain);
     return { domains, replaces: [["domains", name]] };
   };
 }

package/src/reference.ts

@@ -1,8 +1,8 @@
-import { type Envelope, type Json, type Key, isEnvelope, isRecord, typeName } from "./doc.ts";
+import { type Envelope, type Json, type Key, isEnvelope, isKey, isRecord, typeName } from "./doc.ts";
 import { ask } from "./ladder.ts";
 import { type AttributeDeclaration, type CapsRule, type Kind, type TreeContract, equationType, lookupKind } from "./world.ts";
 import { type PartSlot, type Split, partsOf, pathMatches } from "./parts.ts";
-import { type Cap, type Context, type HostThing, type Resolution, type ResolveOptions, type Thing, THING, isHostThing, resolve, valueOfThing, worldThing } from "./deref.ts";
+import { type Cap, type Context, type HostThing, type Resolution, type ResolveOptions, type Thing, ROOTS, THING, isHostThing, resolve, valueOfThing, worldThing } from "./deref.ts";
 import { type AttributeRung, STD_EVALUATORS } from "./stdlib.ts";
 import { type EvalError, type Failed, type Result, Failure, describe, fail, ok, placed, thrown } from "./errors.ts";
 import {
@@ -14,15 +14,18 @@ import {
   type Machine,
   type Part,
   type Perform,
+  type Read,
   type RunFn,
   type RunInput,
   type RunPart,
   type Steps,
   type StopSignal,
   JOURNAL,
+  heldReason,
   makeContext,
   permits,
   placeText,
+  reachedOf,
   waitedReason,
 } from "./evaluate.ts";
 import { type FormulaProfile, type OpFn, Held, STD_EXT } from "./formula.ts";
@@ -57,6 +60,12 @@ export interface ReferenceOptions {
    * each verb by the same rules (VERB.AGREE).
    */
   readonly verb?: string;
+  /**
+   * A list that gets each read of a resolution, in its order (REF.READS). A read has the shape of a read of a plan:
+   * the path, what it reached and the mark `free`. The reads of a closure and of an equation of a tree go in the
+   * same list. The reference adds no kept reads, because it has no static reads of a closure.
+   */
+  readonly reads?: Read[];
 }
 
 /** The options of a run of the reference: the options of an evaluation, with the host and a signal (REF.RUN). */
@@ -80,6 +89,13 @@ interface Scope {
   alls: number;
 }
 
+/** The record of the reads of one evaluation of the reference (REF.READS). */
+interface Reading {
+  readonly list: Read[];
+  /** The context at the root of the evaluation. A free read reads this context. */
+  readonly root: Context;
+}
+
 /** The state of one evaluation of the reference. */
 interface Env {
   readonly machine: Machine;
@@ -95,6 +111,10 @@ interface Env {
   readonly verb: string;
   /** The scope of the code that evaluates at this time. `all` changes it for each item. */
   scope: Scope;
+  /** The count of the drives without a wait that are active. In a run, an effect under one does not reach the host (RUN.HELD). */
+  held: number;
+  /** The record of the reads. A nested evaluation for an equation of a tree keeps the record of its tree. */
+  readonly reading: Reading | undefined;
 }
 
 /** The code that answers a document: a function evaluator, a runner, or a gap of the reference. */
@@ -221,6 +241,44 @@ function resolveFully(machine: Machine, ctx: Context, path: readonly unknown[],
   return options?.hops === true ? found : { ...found, hops: [] };
 }
 
+/** The text that names a resolution in the error of an exception of the host (READS.RECORD). */
+const READ_FAILED = "the resolution of a path";
+
+/**
+ * This function resolves a path for a document, and records the read when the evaluation has a list (REF.READS,
+ * READS.RECORD). An exception of the host gives the error value of the read, and the exception goes on.
+ */
+function readAt(env: Env, ctx: Context, path: readonly unknown[], options?: ResolveOptions): Resolution {
+  const reading = env.reading;
+  if (reading === undefined) return resolveFully(env.machine, ctx, path, options);
+  const free = freeIn(reading.root, ctx, path);
+  let found: Resolution;
+  try {
+    found = resolveFully(env.machine, ctx, path, options);
+  } catch (error) {
+    reading.list.push({ path, reached: thrown(error, READ_FAILED), free });
+    throw error;
+  }
+  reading.list.push(options?.hops === true ? { path, reached: reachedOf(found), free, hops: found.hops } : { path, reached: reachedOf(found), free });
+  return found;
+}
+
+/**
+ * This function tells if a read reads the context at the root of the evaluation (READS.FREE). The reference reads
+ * the rule from SPEC. A name that a kind binds, a `self` that a kind sets and a path without a root are not free. A
+ * name that a kind does not bind keeps its value from the root.
+ */
+function freeIn(root: Context, ctx: Context, path: readonly unknown[]): boolean {
+  const head = path[0];
+  if (head === "self") return Object.is(ctx.self, root.self);
+  if (head !== "names") return typeof head === "string" && (ROOTS as readonly string[]).includes(head);
+  const name = path[1];
+  if (ctx.names === root.names || !isKey(name)) return true;
+  const key = String(name);
+  const bound = Object.hasOwn(ctx.names, key);
+  return bound === Object.hasOwn(root.names, key) && (!bound || Object.is(ctx.names[key], root.names[key]));
+}
+
 /**
  * This function causes an effect when the capabilities permit it (RUN.CAP, CAP.HOOK). It records the effect with its
  * address (RUN.ADDRESS) and its outcome (RUN.OUTCOME). The mock answers the effect at once (RUN.MOCK). Without a
@@ -254,6 +312,12 @@ function* causeAndWait(env: Env, ctx: Context, kind: Cap, payload: unknown, plac
   if ("ok" in effect) return effect;
   const perform = env.perform;
   if (perform === undefined) return (effect.outcome = ok(payload));
+  if (env.held > 0) {
+    // The parent cannot wait for the answer of the host, thus the host does not get the effect (RUN.HELD).
+    effect.outcome = fail("#CALC!", heldReason(kind), { place });
+    yield Promise.resolve(undefined);
+    return effect.outcome;
+  }
   let given: unknown;
   try {
     given = perform(effect);
@@ -327,7 +391,16 @@ function evaluateSeen(env: Env, seen: Seen, at: At): Result {
   const { chosen } = seen;
   const { place } = at;
   if ("gap" in chosen) return fail("#NOEVAL", chosen.gap, { place });
-  if ("runner" in chosen) return drive(runSeen(env, seen, at, chosen.runner), place, seen.kindText);
+  if ("runner" in chosen) {
+    if (!env.running) return drive(runSeen(env, seen, at, chosen.runner), place, seen.kindText);
+    // In a run, an effect under this drive does not reach the host (RUN.HELD).
+    env.held += 1;
+    try {
+      return drive(runSeen(env, seen, at, chosen.runner), place, seen.kindText);
+    } finally {
+      env.held -= 1;
+    }
+  }
   const input = evalInput(env, seen, at);
   try {
     return placed(chosen.evaluator(input), place);
@@ -385,7 +458,7 @@ function evalInput(env: Env, seen: Seen, at: At): EvalInput {
     place: at.place,
     machine: env.machine,
     ...(at.address ? { address: true } : {}),
-    resolve: (path, options) => resolveFully(env.machine, at.ctx, path, options),
+    resolve: (path, options) => readAt(env, at.ctx, path, options),
     effect: (kind, payload) => causeFromEvaluator(env, at.ctx, kind, payload, at.place),
     fill,
   };
@@ -413,7 +486,7 @@ function runInput(env: Env, seen: Seen, at: At): RunInput {
     context: at.ctx,
     place: at.place,
     machine: env.machine,
-    resolve: (path, options) => resolveFully(env.machine, at.ctx, path, options),
+    resolve: (path, options) => readAt(env, at.ctx, path, options),
     effect: (kind, payload) => causeAndWait(env, at.ctx, kind, payload, at.place),
     all: (list, options) => together(env, list, options),
     fill,
@@ -458,6 +531,7 @@ function* together(env: Env, list: readonly RunPart[], options: AllOptions = {})
   outer.alls += 1;
   let failed = false;
   let started = 0;
+  let before = 0;
   const end = (index: number, result: Result): void => {
     results[index] = result;
     if (failFast && !result.ok) failed = true;
@@ -508,10 +582,11 @@ function* together(env: Env, list: readonly RunPart[], options: AllOptions = {})
   };
   startMore();
   while (waiting.length > 0 && !failed) {
-    const chosen = env.journal?.next?.(address, waiting.map((waiter) => waiter.index));
+    const chosen = env.journal?.next?.(address, waiting.map((waiter) => waiter.index), before);
     const pick = chosen === undefined ? undefined : waiting.find((waiter) => waiter.index === chosen);
     const resumed = (yield pick === undefined ? Promise.race(waiting.map((waiter) => waiter.next)) : pick.next) as Resumed;
     env.journal?.settled?.(address, resumed.waiter.index);
+    before += 1;
     waiting.splice(waiting.indexOf(resumed.waiter), 1);
     goOn(resumed.waiter.index, resumed.waiter.steps, resumed);
     startMore();
@@ -543,9 +618,18 @@ function* together(env: Env, list: readonly RunPart[], options: AllOptions = {})
  * @returns The result.
  */
 export function reference(machine: Machine, doc: unknown, context: Context = makeContext(), options: ReferenceOptions = {}): Result {
-  const env = envOf(machine, options, false);
+  return evaluateRoot(machine, doc, context, options, undefined);
+}
+
+/**
+ * This function evaluates a document from its root. An equation of a tree gives the record of its tree. Thus the
+ * reads of the equation go in the list of the outer evaluation (REF.READS).
+ */
+function evaluateRoot(machine: Machine, doc: unknown, context: Context, options: ReferenceOptions, outer: Reading | undefined): Result {
+  const at = rootAt(machine, doc, context, options);
+  const env = envOf(machine, options, false, at.ctx, outer);
   try {
-    return within(env, () => evaluateAt(env, rootAt(machine, doc, context, options)));
+    return within(env, () => evaluateAt(env, at));
   } catch (error) {
     return placed(thrown(error, "the reference"), []);
   }
@@ -567,13 +651,17 @@ export function reference(machine: Machine, doc: unknown, context: Context = mak
  * @returns The result, when the run ends.
  */
 export function referenceRun(machine: Machine, doc: unknown, context: Context = makeContext(), options: ReferenceRunOptions = {}): Promise<Result> {
-  const env = envOf(machine, options, true);
-  const steps = stepsAt(env, rootAt(machine, doc, context, options));
+  const at = rootAt(machine, doc, context, options);
+  const env = envOf(machine, options, true, at.ctx, undefined);
+  const steps = stepsAt(env, at);
   return driveRun(env, steps, options.signal).catch((error: unknown) => placed(thrown(error, "the reference"), []));
 }
 
-/** This function makes the state of the reference for one evaluation or one run. */
-function envOf(machine: Machine, options: ReferenceOptions, running: boolean): Env {
+/**
+ * This function makes the state of the reference for one evaluation or one run. The record of the reads comes from
+ * the evaluation around it, or from the list of the options.
+ */
+function envOf(machine: Machine, options: ReferenceOptions, running: boolean, root: Context, outer: Reading | undefined): Env {
   const perform = options.perform;
   return {
     machine,
@@ -585,6 +673,8 @@ function envOf(machine: Machine, options: ReferenceOptions, running: boolean): E
     running,
     verb: options.verb ?? "eval",
     scope: { prefix: "", counts: new Map(), alls: 0 },
+    held: 0,
+    reading: outer ?? (options.reads === undefined ? undefined : { list: options.reads, root }),
   };
 }
 
@@ -698,13 +788,14 @@ function refNodeOf(thing: unknown): RefNode | undefined {
 
 /**
  * TREE.LADDER: an equation of the kind of a node evaluates in the reference. It gets the node as `self`, the names of
- * its rung and no capabilities. A bare equation gets the type `of` of the parts of the kind.
+ * its rung and no capabilities. A bare equation gets the type `of` of the parts of the kind. The reads of the
+ * equation go in the record of the evaluation that made the node (REF.READS).
  */
 function equationOf(node: RefNode, term: Json, names: Readonly<Record<string, unknown>>): Result {
   const env = node.env;
   if (env === undefined) return fail("#NOEVAL", "The evaluation of an equation needs the machine.");
   const ctx: Context = { ...node.ctx, names, caps: [], self: node.thing };
-  return reference(env.machine, term, ctx, { definitions: env.definitions, ...(node.of === undefined ? {} : { declaredType: node.of }) });
+  return evaluateRoot(env.machine, term, ctx, { definitions: env.definitions, ...(node.of === undefined ? {} : { declaredType: node.of }) }, env.reading);
 }
 
 function termIn<T>(table: Readonly<Record<string, T>> | undefined, name: string): T | undefined {
@@ -960,7 +1051,11 @@ export function formulaDefinitions(profile: FormulaProfile = {}): Definitions {
     // FORMULA.LET: a path through a name whose binding failed gives the error of the binding.
     const head = path[0] === "names" && typeof path[1] === "string" ? path[1] : undefined;
     const bound = head === undefined ? undefined : own(context.names, head);
-    if (bound instanceof Held) return { ok: false, error: bound.error };
+    if (bound instanceof Held) {
+      // The result comes from the binding of the name, thus the name is a read (READS.RECORD).
+      walk(["names", head]);
+      return { ok: false, error: bound.error };
+    }
     const found = walk(steps);
     if (!found.ok) return fail(found.code, found.reason);
     // FORMULA.ADDRESS: an address gives what the path reaches.