@mark1russell7/coeval 0.22.0 → 0.23.0

package/src/deref.ts

@@ -58,6 +58,15 @@ export interface HostThing {
    * @returns What the step reaches, or `undefined` when the host does not know it yet. Then the kept read ends at the thing.
    */
   known?(key: Key): { readonly thing: Thing } | undefined;
+  /**
+   * This optional function holds a kept read (SCHED.OWN-NODE). The evaluation did not ask for that read. Thus a host
+   * that follows the reads of an evaluation can tell the two apart. The kernel calls this function of the root `world`
+   * around each kept read that resolves its path.
+   *
+   * @param read - This function does the read.
+   * @returns What `read` gives.
+   */
+  keeping?<T>(read: () => T): T;
 }
 
 /** Something that a path can reach: any value of the host, or a host thing. */
@@ -522,7 +531,8 @@ function walkQuick(start: unknown, path: readonly unknown[], plain: boolean, key
 /**
  * A compiled path: one static path for one navigator (PLAN.PATH). `compilePath` reads the root, the open roots and
  * the steps one time. It asks the ladder of the verb `step` for each step document one time. Each resolution then
- * examines only the values of the context.
+ * examines only the values of the context. Code of a language reads a compiled path with `resolveCompiled`, thus the
+ * list of reads gets the read (PLAN.PATH-READS).
  */
 export interface CompiledPath {
   /** The steps of the path, as the document gives them. The list of reads records these steps. */
@@ -530,7 +540,8 @@ export interface CompiledPath {
   /** The navigator of the compilation. A runtime with another navigator resolves the steps again. */
   readonly nav: Navigator;
   /**
-   * This function resolves the path from a context, without a record of hops.
+   * This function resolves the path from a context, without a record of hops. It records no read and it does not
+   * apply the grant of the evaluation, as `resolve` does not. Use it only outside an evaluation.
    *
    * @param ctx - The context.
    * @returns The same resolution as `resolve(nav, ctx, path, { hops: false })`.
@@ -592,8 +603,11 @@ class StaticPath implements CompiledPath {
  * - The walker of each step document comes from the ladder one time, here. The navigator and the step document do
  *   not change, thus the answer does not change either.
  *
+ * An evaluator of a language calls this function in its `compile`, with the field `machine` of the input, and reads the
+ * result with `resolveCompiled` (PLAN.PATH-EXPORT).
+ *
  * @param nav - The navigator. A plan compiles its paths for its machine.
- * @param path - The steps. The first step is a root.
+ * @param path - The steps. The first step is a root. The compiled path keeps this list, thus the host must not change it.
  * @returns The compiled path.
  */
 export function compilePath(nav: Navigator, path: readonly unknown[]): CompiledPath {

package/src/durable.ts

@@ -1,5 +1,5 @@
 import type { Context } from "./deref.ts";
-import type { Result } from "./errors.ts";
+import { type Result, overflowCount } from "./errors.ts";
 import { type Machine, type Plan, type PrepareOptions, type Read, prepare } from "./evaluate.ts";
 import { type DocFacts, type FactsOptions, factsOf } from "./facts.ts";
 import { type PrintOptions, type ReadPrints, type VerifyOptions, printReads, verifyReads } from "./reads.ts";
@@ -126,20 +126,24 @@ const NO_READS: readonly Read[] = /* @__PURE__ */ Object.freeze([]);
 /** The key of the document `-0` in a cache of value documents. A `Map` finds the entry of `0` for `-0`. */
 const NEGATIVE_ZERO = /* @__PURE__ */ Symbol("coeval.negative-zero");
 
-/** This function makes a cache by document. A document object gives its value one time, as PLAN.CACHE says. */
-function byDocument<T>(make: (doc: unknown) => T): (doc: unknown) => T {
+/**
+ * This function makes a cache by document. A document object gives its value one time, as PLAN.CACHE says. A value
+ * that `lasts` refuses stays out of the cache, and the next call makes it again.
+ */
+function byDocument<T>(make: (doc: unknown) => T, lasts?: () => boolean): (doc: unknown) => T {
   const objects = new WeakMap<object, T>();
   const values = new Map<unknown, T>();
   return (doc) => {
     if (typeof doc === "object" && doc !== null) {
       if (objects.has(doc)) return objects.get(doc) as T;
       const made = make(doc);
-      objects.set(doc, made);
+      if (lasts === undefined || lasts()) objects.set(doc, made);
       return made;
     }
     const key = Object.is(doc, -0) ? NEGATIVE_ZERO : doc;
     if (values.has(key)) return values.get(key) as T;
     const made = make(doc);
+    if (lasts !== undefined && !lasts()) return made;
     if (values.size >= MAX_VALUES) values.clear();
     values.set(key, made);
     return made;
@@ -180,11 +184,19 @@ export function durable(machine: Machine, options: DurableOptions = {}): Durable
   const results = new Map<unknown, Entry>();
   let current = machine;
   let epochs: Epochs = { structure: 0, data: 0 };
-  const plansOf = (m: Machine): ((doc: unknown) => Plan) =>
-    byDocument((doc) => {
-      counts.compiles += 1;
-      return prepare(m, doc, prepareOptions);
-    });
+  const plansOf = (m: Machine): ((doc: unknown) => Plan) => {
+    let before = 0;
+    // A compilation near the limit of the stack gives a plan that fails. That failure depends on the depth of the
+    // demand, not on the document, thus such a plan stays out of the cache (SCHED.DEEP-CYCLE-CHANGE).
+    return byDocument(
+      (doc) => {
+        counts.compiles += 1;
+        before = overflowCount();
+        return prepare(m, doc, prepareOptions);
+      },
+      () => overflowCount() === before,
+    );
+  };
   const factsFor = (m: Machine): ((doc: unknown) => DocFacts) =>
     byDocument((doc) => {
       counts.facts += 1;

package/src/errors.ts

@@ -116,6 +116,19 @@ export function isStackOverflow(error: unknown): boolean {
   }
 }
 
+/** The count of the stack overflows that `thrown` changed into `#DEPTH!`. */
+let overflows = 0;
+
+/**
+ * This function gives the count of the stack overflows that `thrown` changed into `#DEPTH!`. A schedule compares two
+ * counts. Thus it finds an overflow also when a document catches the error (SCHED.DEEP-CYCLE).
+ *
+ * @returns The count since the start of the process.
+ */
+export function overflowCount(): number {
+  return overflows;
+}
+
 /**
  * This function changes an exception into an error value. A `Failure` gives its error value. A stack overflow
  * gives `#DEPTH!`. Each other exception gives `#CALC!`, with the exception as the cause.
@@ -126,7 +139,10 @@ export function isStackOverflow(error: unknown): boolean {
  */
 export function thrown(error: unknown, who: string): Failed {
   if (error instanceof Failure) return { ok: false, error: error.error };
-  if (isStackOverflow(error)) return fail("#DEPTH!", `The nesting of ${who} is too deep for the stack of the host.`, { cause: error });
+  if (isStackOverflow(error)) {
+    overflows += 1;
+    return fail("#DEPTH!", `The nesting of ${who} is too deep for the stack of the host.`, { cause: error });
+  }
   return fail("#CALC!", `${upper(who)} threw: ${describe(error)}`, { cause: error });
 }
 

package/src/evaluate.ts

@@ -1004,9 +1004,24 @@ function keptPath(nav: Navigator, root: Context, path: readonly unknown[]): Kept
   }
 }
 
+/**
+ * This function resolves the path of a kept read. A reference on the path can reach a node of a schedule, thus the
+ * resolution goes through `keeping` of the root `world` (SCHED.OWN-NODE).
+ *
+ * @param nav - The world and the code of the evaluators.
+ * @param ctx - The context.
+ * @param path - The path of the kept read.
+ * @returns What the path reaches.
+ */
+function readKept(nav: Navigator, ctx: Context, path: readonly unknown[]): Result {
+  const read = (): Result => readAgain(nav, ctx, path, false).reached;
+  const world = ctx.world;
+  return isHostThing(world) && world.keeping !== undefined ? world.keeping(read) : read();
+}
+
 /**
  * This function resolves the path of a kept read again, for `verifyReads` (SCHED.CLOSURE). It walks the path as
- * `keptPath` did. A host thing with `known` answers its step. A path without such a step resolves with `readAgain`.
+ * `keptPath` did. A host thing with `known` answers its step. A path without such a step resolves with `readKept`.
  *
  * @param nav - The world and the code of the evaluators.
  * @param ctx - The new context.
@@ -1018,7 +1033,7 @@ export function keptAgain(nav: Navigator, ctx: Context, path: readonly unknown[]
   let here = adopt(ctx[path[0] as Root]);
   let known = false;
   // Before a step of `known`, each other answer of the walk is the answer of `readAgain`, as before SCHED.CLOSURE.
-  const other = (): Result | undefined => (known ? undefined : readAgain(nav, ctx, path, false).reached);
+  const other = (): Result | undefined => (known ? undefined : readKept(nav, ctx, path));
   for (let index = 1; index < path.length; index += 1) {
     if (isHostThing(here)) {
       if (here.known === undefined) return other();
@@ -1049,6 +1064,22 @@ function readingOf(list: Read[] | undefined, root: Context): Reading | undefined
 
 /** This class holds the state of one evaluation or run: the machine, the effects, the clock and the trace. */
 class Session implements Runtime {
+  readonly machine: Machine;
+  /**
+   * The epoch of the evaluation: the list of capabilities that the host gave the root (CAP.NARROW-KEPT). A context
+   * keeps its grant only in an evaluation of the same epoch.
+   */
+  readonly epoch: readonly Cap[];
+  readonly running: boolean;
+  readonly traced: boolean;
+  readonly perform: Perform | undefined;
+  readonly signal: StopSignal | 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;
+
   /** The list of the effects. It is made at the first effect, thus an evaluation without effects makes no list. */
   private list: Effect[] | undefined;
   tick = 0;
@@ -1067,23 +1098,22 @@ class Session implements Runtime {
   private scope: Scope | undefined;
 
   constructor(
-    readonly machine: Machine,
-    /**
-     * The epoch of the evaluation: the list of capabilities that the host gave the root (CAP.NARROW-KEPT). A context
-     * keeps its grant only in an evaluation of the same epoch.
-     */
-    readonly epoch: readonly Cap[],
-    readonly running: boolean,
-    readonly traced: boolean,
-    readonly perform: Perform | undefined,
-    readonly signal: StopSignal | undefined,
+    machine: Machine,
+    epoch: readonly Cap[],
+    running: boolean,
+    traced: boolean,
+    perform: Perform | undefined,
+    signal: StopSignal | undefined,
     effects: Effect[] | 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,
+    reading: Reading | undefined = undefined,
   ) {
+    this.machine = machine;
+    this.epoch = epoch;
+    this.running = running;
+    this.traced = traced;
+    this.perform = perform;
+    this.signal = signal;
+    this.reading = reading;
     this.list = effects;
     this.holder = traced ? holderNode() : undefined;
     this.current = this.holder;
@@ -1185,7 +1215,7 @@ class Session implements Runtime {
     if (paths.has(text) || paths.has(JSON.stringify([root]))) return true;
     paths.add(text);
     if (path.length === 1 && root === "self") reading.self = true;
-    reading.list.push({ path, reached: walk.reached ?? readAgain(this.machine, reading.root, path, false).reached, free: true, kept: true });
+    reading.list.push({ path, reached: walk.reached ?? readKept(this.machine, reading.root, path), free: true, kept: true });
     return true;
   }
 
@@ -1197,7 +1227,7 @@ class Session implements Runtime {
     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 });
+      reading.list.push({ path, reached: readKept(this.machine, reading.root, path), free: true, kept: true });
     }
   }
 
@@ -1422,7 +1452,9 @@ 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.
+ * path. Each other runtime gets the steps through `resolve`, thus a runtime that wraps another runtime sees each path
+ * (PLAN.PATH-ROUTE). The result and the list of reads are the same as for `rt.resolve(ctx, compiled.path)`
+ * (PLAN.PATH-READS).
  *
  * @param rt - The runtime.
  * @param ctx - The context.
@@ -1831,6 +1863,7 @@ function freeOf(doc: Envelope, kind: Kind, slots: readonly PartSlot[], frees: re
 
 /** This class is the runtime of a fold. It reads only the names that the folded part binds, and it causes no effect. */
 class Probe implements Runtime {
+  readonly machine: Machine;
   readonly running = false;
   /** `true` after the part asked for something that a fold cannot give. */
   refused = false;
@@ -1842,7 +1875,8 @@ class Probe implements Runtime {
    */
   readonly root: Context;
 
-  constructor(readonly machine: Machine) {
+  constructor(machine: Machine) {
+    this.machine = machine;
     const refuse = (): void => {
       this.refused = true;
     };

package/src/formula.ts

@@ -97,7 +97,11 @@ const SKIPPED: unique symbol = /* @__PURE__ */ Symbol("skipped");
 
 /** The value of a name whose binding failed. A reference to the name gives the error. */
 export class Held {
-  constructor(readonly error: EvalError) {}
+  readonly error: EvalError;
+
+  constructor(error: EvalError) {
+    this.error = error;
+  }
 }
 
 const CLOSURE: unique symbol = /* @__PURE__ */ Symbol.for("coeval.closure") as never;
@@ -242,6 +246,36 @@ function isSignature(value: unknown): value is Signature {
   return typeof value === "object" && value !== null && Array.isArray((value as { readonly params?: unknown }).params) && Object.hasOwn(value, "to");
 }
 
+/** This function gives the signatures of an operation as the profile holds them, or `undefined` for no entry. */
+function rawSignatures(profile: FormulaProfile, name: string): readonly unknown[] | undefined {
+  const sigs = profile.sigs;
+  if (sigs === undefined) return undefined;
+  let found: unknown;
+  if (typeof sigs === "function") {
+    try {
+      found = sigs(name);
+    } catch {
+      return undefined;
+    }
+  } else {
+    found = Object.hasOwn(sigs, name) ? sigs[name] : undefined;
+  }
+  if (found === undefined) return undefined;
+  return Array.isArray(found) ? found : [found];
+}
+
+/**
+ * This function gives each signature of an operation that has the form of a signature, for `conforms` (D137). The
+ * kernel does not export the function.
+ *
+ * @param profile - The profile.
+ * @param name - The name of the operation.
+ * @returns The signatures.
+ */
+export function signaturesOf(profile: FormulaProfile, name: string): readonly Signature[] {
+  return (rawSignatures(profile, name) ?? []).filter(isSignature);
+}
+
 /** This function tells if two signatures have the same parameters and the same rest parameter. */
 function sameParams(a: Signature, b: Signature): boolean {
   if (!docEquals(a.params, b.params)) return false;
@@ -329,22 +363,7 @@ function formulaTypes(profile: FormulaProfile): Readonly<Record<string, TypeRule
   };
   const logicValue = profile.logic === "value";
   const otherwise = Object.hasOwn(profile, "otherwise") ? valueType(profile.otherwise) : "null";
-  const lookup = (name: string): readonly unknown[] | undefined => {
-    const sigs = profile.sigs;
-    if (sigs === undefined) return undefined;
-    let found: unknown;
-    if (typeof sigs === "function") {
-      try {
-        found = sigs(name);
-      } catch {
-        return undefined;
-      }
-    } else {
-      found = Object.hasOwn(sigs, name) ? sigs[name] : undefined;
-    }
-    if (found === undefined) return undefined;
-    return Array.isArray(found) ? found : [found];
-  };
+  const lookup = (name: string): readonly unknown[] | undefined => rawSignatures(profile, name);
   const nameOf = (input: TypeInput): string => input.typePath.slice(1).join(".");
   /** The signatures of an operation. Each type of a signature is a contract, thus the check examines it one time. */
   const signatures = (input: TypeInput): { readonly sigs: readonly Signature[]; readonly bad: boolean } | undefined => {
@@ -644,6 +663,29 @@ export function declaredTruthOf(code: unknown): DeclaredTruth | undefined {
   return (typeof code === "object" || typeof code === "function") && code !== null ? truthByCode.get(code) : undefined;
 }
 
+/** An evaluator of the kit that reads functions of a profile: its name, and the fields of the profile (D137). */
+export interface ProfileReader {
+  readonly name: string;
+  readonly profile: FormulaProfile;
+}
+
+/** The evaluators of the kit that `conforms` examines the functions of a profile with. */
+const PROFILE_READERS: readonly string[] = ["formula.op", "formula.ext", "formula.record", "formula.ref"];
+
+/** The profile of each evaluator of the kit that reads its functions, for `conforms` (D137). */
+const readerByCode = /* @__PURE__ */ new WeakMap<object, ProfileReader>();
+
+/**
+ * This function gives the profile of an evaluator of the kit, when that evaluator reads functions of the profile
+ * (D137). The kernel does not export the function.
+ *
+ * @param code - The evaluator or the runner.
+ * @returns The name of the evaluator and the profile, or `undefined`.
+ */
+export function profileReaderOf(code: unknown): ProfileReader | undefined {
+  return (typeof code === "object" || typeof code === "function") && code !== null ? readerByCode.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);
@@ -656,6 +698,7 @@ function makeEvaluators(profile: FormulaProfile): Readonly<Record<string, Evalua
     const type = Object.hasOwn(types, name) ? types[name] : undefined;
     const made = Object.freeze(type === undefined ? evaluator : { compile: evaluator.compile, type });
     if (truth !== undefined && TRUTH_READERS.includes(name)) truthByCode.set(made, truth);
+    if (PROFILE_READERS.includes(name)) readerByCode.set(made, { name, profile });
     out[name] = made;
   }
   return Object.freeze(out);

package/src/index.ts

@@ -60,9 +60,11 @@ export {
   type World,
   type WorldEntry,
   CIRCULAR_LIMIT,
+  GENERATION_LIMIT,
   argsKey,
   atArgsOf,
   atRuleOf,
+  documentKey,
   circularOf,
   collectOf,
   effectsOfVerb,
@@ -104,6 +106,7 @@ export {
 export { type StepKey, type StepLadder, type StepNeed, type StepReason, type StepRefusal, type StepWalk, checkStep, isStep, stepLadder, stepOf, stepRank } from "./steps.ts";
 export {
   type Cap,
+  type CompiledPath,
   type Context,
   type DerefCode,
   type Hop,
@@ -121,6 +124,7 @@ export {
   type Walker,
   ROOTS,
   THING,
+  compilePath,
   context,
   derefStep,
   isHostThing,
@@ -176,6 +180,7 @@ export {
   permits,
   planner,
   prepare,
+  resolveCompiled,
   run,
 } from "./evaluate.ts";
 export {
@@ -255,10 +260,12 @@ export {
   jsTruthy,
 } from "./formula.ts";
 export { decodeDomain, decodeValue, encodeValue } from "./codec.ts";
+export { type CodecFinding, type CodecLaw, type CodecLawsOptions, type CodecProbe, codecLaws } from "./codec-laws.ts";
 export {
   type ParseResult,
   type SyntaxAssoc,
   type SyntaxCalls,
+  type SyntaxConstructs,
   type SyntaxEnvelopes,
   type SyntaxFixity,
   type SyntaxForm,
@@ -270,6 +277,7 @@ export {
   type SyntaxProfile,
   type SyntaxRefPattern,
   type SyntaxRefs,
+  MAX_SYNTAX_ISSUES,
   STD_SYNTAX,
   parse,
   print,
@@ -282,12 +290,14 @@ export { sameResult } from "./same.ts";
 export { type PrintOptions, type ReadPrints, type ReadsCheck, type VerifyOptions, printReads, verifyReads } from "./reads.ts";
 export { type Durable, type DurableCounts, type DurableOptions, type Epochs, durable } from "./durable.ts";
 export {
+  type CycleIssue,
   type NodeEdge,
   type NodeInfo,
   type NodeRunOptions,
   type Schedule,
   type ScheduleCounts,
   type ScheduleOptions,
+  checkCycles,
   edgesOf,
   schedule,
 } from "./schedule.ts";

package/src/instances.ts

@@ -504,7 +504,22 @@ function rungReads(b: Builder, id: string): void {
     collectReads(b, node, key, collect, later);
     return;
   }
-  if (declared?.default !== undefined) termReads(b, termRefs(b, node.kind, `tree.attributes.${key}.default`, declared.default), node, undefined, later);
+  if (declared?.default !== undefined) {
+    termReads(b, termRefs(b, node.kind, `tree.attributes.${key}.default`, declared.default), node, undefined, later);
+    return;
+  }
+  // The document of a higher-order attribute is known only in the run, thus its reads are not known (TREE.HIGHER-CHECK).
+  if (declared?.higher !== undefined) {
+    termReads(b, termRefs(b, node.kind, `tree.attributes.${key}.higher`, declared.higher), node, undefined, later);
+    edge(b, undefined, later);
+    return;
+  }
+  // The last rung reads the attribute `forwards` and an attribute of a node that only the run knows (TREE.FORWARD-CHECK).
+  const forwards = tree?.forwards;
+  if (typeof forwards === "string" && forwards !== key) {
+    edge(b, vertexOf(b, node, forwards), later);
+    edge(b, undefined, later);
+  }
 }
 
 /** This function gives the list children of a node before the run. A node without a rung for it has no children. */

package/src/meaning.ts

@@ -58,12 +58,14 @@ export interface ScheduleEngine {
   read(id: string): Result;
 }
 
-/** What a new engine gets beside its machine: the context of the host, and the type of a bare root value. */
+/** What a new engine gets beside its machine. These are the context of the host, the type of a bare root value and the `self` of each node. */
 export interface ScheduleEngineStart {
   /** The first context of the host, without the root `world`. */
   readonly context: Context;
   /** The type of a bare root value, when the options of the harness name one. */
   readonly declaredType?: string;
+  /** The `self` of each node, when the options of the harness have `selves`. It has the form of the option of `schedule`. */
+  readonly selfOf?: (id: string, host: Context) => unknown;
 }
 
 /**
@@ -110,6 +112,12 @@ export interface AgreeScheduleOptions {
   readonly values?: readonly unknown[];
   /** The contexts of the host at the start of the runs, one after the other. */
   readonly contexts?: readonly Context[];
+  /**
+   * The values of the `self` of a node (SCHED.NODE-AGREES). With them, the option `selfOf` of each engine gives each
+   * node its own `self`. Some nodes then share one document, and a change of data can give a node a new `self`. The
+   * value `undefined` keeps the `self` of the host. The default gives each node the context of the host.
+   */
+  readonly selves?: readonly unknown[];
   /** The number of runs. The default is 100. */
   readonly count?: number;
   /** The number of commands in one run. The default is 30. */
@@ -155,6 +163,10 @@ export interface ScheduleAgreementCounts {
   readonly same: number;
   /** The new machines. */
   readonly machines: number;
+  /** The changes of data with a new `self` of a node, only with the option `selves`. */
+  readonly selves: number;
+  /** The documents that a node shares with another node, only with the option `selves`. */
+  readonly shared: number;
 }
 
 /** The outcome of `agreeSchedule`: what the harness reached, or the first disagreement. */
@@ -266,7 +278,7 @@ function shuffle<T>(items: readonly T[], rng: Random): T[] {
  * This function evaluates each node of a graph from scratch, with the meaning of D31. Each node gets a new plan and
  * one value. The algorithm of Tarjan over the demands finds the cycles. The function keeps nothing between calls.
  */
-function fromScratch(machine: Machine, docs: ReadonlyMap<string, unknown>, base: Context, declaredType: string | undefined): ReadonlyMap<string, Result> {
+function fromScratch(machine: Machine, docs: ReadonlyMap<string, unknown>, base: Context, declaredType: string | undefined, own: ReadonlyMap<string, unknown> | undefined): ReadonlyMap<string, Result> {
   const declared = declaredType === undefined ? {} : { declaredType };
   const values = new Map<string, Result>();
   const index = new Map<string, number>();
@@ -298,7 +310,8 @@ function fromScratch(machine: Machine, docs: ReadonlyMap<string, unknown>, base:
     lowest.set(id, index.get(id) as number);
     component.push(id);
     evaluating.push(id);
-    let result = prepare(machine, docs.get(id), declared).evaluate(ctx);
+    const self = own?.get(id);
+    let result = prepare(machine, docs.get(id), declared).evaluate(self === undefined ? ctx : { ...ctx, self });
     evaluating.pop();
     if ((lowest.get(id) as number) < (index.get(id) as number)) result = cycleOf(id);
     else if (component.splice(component.indexOf(id)).length > 1 || selfReads.has(id)) result = cycleOf(id);
@@ -340,7 +353,8 @@ function named(result: Result): string {
 /**
  * This function examines an engine of a host against an evaluation from scratch (SCHED.AGREES, R4 P4, D58). Each run
  * makes a new engine and a random graph of named nodes from the document generator. Then it gives random commands:
- * edits, new nodes, removed nodes, the same document again, new machines and changes of data.
+ * edits, new nodes, removed nodes, the same document again, new machines and changes of data. The option `selves`
+ * adds a `self` for each node and documents that nodes share (SCHED.NODE-AGREES).
  *
  * - Each read command evaluates the whole graph from scratch two times, with the meaning of D31.
  * - It then demands each node in a random order, or one node, and compares each answer with `sameResult`.
@@ -366,6 +380,7 @@ export function agreeSchedule(engine: ScheduleEngineFactory, options: AgreeSched
   const hostNames = options.names ?? ["a", "b", "x", "n"];
   const hostValues = options.values ?? standardValues();
   const contexts = options.contexts ?? standardContexts();
+  const selves = options.selves;
   const total = options.count ?? 100;
   const steps = options.steps ?? 30;
   const first = options.seed ?? 9_000_011;
@@ -376,7 +391,7 @@ export function agreeSchedule(engine: ScheduleEngineFactory, options: AgreeSched
     if (isClosure(a) || isClosure(b)) return isClosure(a) && isClosure(b) && docEquals(closureParams(a), closureParams(b));
     return undefined;
   };
-  const counts = { reads: 0, compared: 0, unrepeatable: 0, values: 0, cycles: 0, runs: 0, data: 0, empty: 0, edits: 0, additions: 0, removes: 0, same: 0, machines: 0 };
+  const counts = { reads: 0, compared: 0, unrepeatable: 0, values: 0, cycles: 0, runs: 0, data: 0, empty: 0, edits: 0, additions: 0, removes: 0, same: 0, machines: 0, selves: 0, shared: 0 };
   const declared = declaredType === undefined ? {} : { declaredType };
   for (let run = 0; run < total; run += 1) {
     const seed = first + run;
@@ -385,7 +400,18 @@ export function agreeSchedule(engine: ScheduleEngineFactory, options: AgreeSched
     let at = 0;
     let machine = machines[0] as Machine;
     let made = 0;
+    const own = selves === undefined ? undefined : new Map<string, unknown>();
+    const pool: unknown[] = [];
     const make = (): unknown => {
+      if (selves !== undefined && pool.length > 0 && rng.chance(0.4)) {
+        counts.shared += 1;
+        return rng.pick(pool);
+      }
+      const doc = generated();
+      pool.push(doc);
+      return doc;
+    };
+    const generated = (): unknown => {
       if (rng.chance(wired)) return wire(rng, node);
       const roll = rng.int(10);
       if (roll === 0) return value(rng);
@@ -395,15 +421,16 @@ export function agreeSchedule(engine: ScheduleEngineFactory, options: AgreeSched
       return runs && roll === 9 ? { type: "log", value: [doc] } : doc;
     };
     const docs = new Map<string, unknown>(nodes.map((id) => [id, make()]));
+    if (own !== undefined && selves !== undefined) for (const id of nodes) own.set(id, rng.pick(selves));
     const start = contexts[run % contexts.length] as Context;
     let base: Context = { ...start, names: { ...start.names } };
-    const host = engine(machine, { ...declared, context: base });
+    const host = engine(machine, { ...declared, context: base, ...(own === undefined ? {} : { selfOf: (id: string) => own.get(id) }) });
     for (const [id, doc] of docs) host.set(id, doc);
     for (let step = 0; step < steps; step += 1) {
       const what = rng.int(12);
       if (what < 4) {
-        const fresh = fromScratch(machine, docs, base, declaredType);
-        const again = fromScratch(machine, docs, base, declaredType);
+        const fresh = fromScratch(machine, docs, base, declaredType, own);
+        const again = fromScratch(machine, docs, base, declaredType, own);
         const ids = shuffle([...docs.keys()], rng);
         // Half of the reads demand each node in a random order, and the other half demand one node.
         for (const id of rng.chance(0.5) ? ids : ids.slice(0, 1)) {
@@ -428,9 +455,15 @@ export function agreeSchedule(engine: ScheduleEngineFactory, options: AgreeSched
           }
         }
       } else if (what < 6) {
-        base = { ...base, names: change(base, rng, hostNames, hostValues) };
+        if (own !== undefined && selves !== undefined && rng.chance(0.5)) {
+          // A new `self` of one node, with the same context object of the host.
+          own.set(rng.pick(nodes), rng.pick(selves));
+          counts.selves += 1;
+        } else {
+          base = { ...base, names: change(base, rng, hostNames, hostValues) };
+          counts.data += 1;
+        }
         host.changeData(base);
-        counts.data += 1;
       } else if (what === 6) {
         // A change of data that changes no value: the same context object again.
         host.changeData(base);

package/src/parts.ts

@@ -41,10 +41,13 @@ export type Split =
   | { readonly ok: false; readonly reason: string; readonly at: readonly Key[] };
 
 class Bad {
-  constructor(
-    readonly reason: string,
-    readonly at: readonly Key[],
-  ) {}
+  readonly reason: string;
+  readonly at: readonly Key[];
+
+  constructor(reason: string, at: readonly Key[]) {
+    this.reason = reason;
+    this.at = at;
+  }
 }
 
 /** This function sets an own data property. Only the key `__proto__` needs `defineProperty`. */

package/src/providers.ts

@@ -150,6 +150,7 @@ function unionOf(types: readonly ValueType[]): ValueType {
 
 /** The state of one reading of a schema: the root, the issues and the definitions that it read. */
 class SchemaReader {
+  readonly root: unknown;
   readonly issues: TypeIssue[] = [];
   /** The type of each definition that a reference reached. Each reading of a definition is sound, thus the first stays. */
   readonly defs = new Map<string, ValueType>();
@@ -158,7 +159,9 @@ class SchemaReader {
   /** The number of schemas with an own `$id` around the current schema. A reference inside them has another base. */
   inner = 0;
 
-  constructor(readonly root: unknown) {}
+  constructor(root: unknown) {
+    this.root = root;
+  }
 
   issue(at: readonly Key[], reason: string): void {
     this.issues.push({ at, reason });