@mark1russell7/coeval 0.14.0 → 0.16.0

package/build/index.d.ts

@@ -302,6 +302,17 @@ interface HostThing {
   resolve?(keys: readonly Key[]): {
     readonly thing: Thing;
   } | undefined;
+  /**
+   * This optional function answers one step only when the host has its value without new work (SCHED.CLOSURE). A
+   * kept read of a closure uses it, because the evaluation did not ask for that read. A schedule gives the value of
+   * a node that has its result in the data epoch. A throw gives the error of the step.
+   *
+   * @param key - The key of the step.
+   * @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;
 }
 /** Something that a path can reach: any value of the host, or a host thing. */
 type Thing = unknown;
@@ -366,6 +377,14 @@ interface WalkInput {
    * @returns What the step reaches, or `undefined`.
    */
   deref(thing: Thing, key: Key): Thing | undefined;
+  /**
+   * This optional function records one hop inside the walk (HOP.EACH-STEP). The resolution gives it only when it
+   * records hops. The hop of the whole walk comes after these hops, as before.
+   *
+   * @param key - The key that the walk followed.
+   * @param thing - The thing that the key reached.
+   */
+  readonly visit?: (key: Key, thing: Thing) => void;
 }
 /** A walker: the code of the verb `step` of a kind of step documents. */
 type Walker = (input: WalkInput) => WalkResult;
@@ -1501,6 +1520,103 @@ interface Typed {
   readonly expected?: ValueType;
 }
 //#endregion
+//#region src/facts.d.ts
+/**
+ * One read of a document: a free reference, with its marks (FACTS.READS). A plan resolves the path of the reference
+ * when it evaluates the reference. The static read covers each path that the plan resolves there (FACTS.SOUND). A
+ * root that a kind declares in `reads` is a read too, with the path of the root alone.
+ */
+interface StaticRead {
+  /** The root of the path. */
+  readonly root: Root;
+  /** The keys after the root, up to the first step that is not a key. */
+  readonly keys: readonly Key[];
+  /**
+   * `true` when each step after the root is a key. Then the plan resolves this path and no other. A step document,
+   * for example `nearest`, makes it `false`: the plan resolves a path that starts with the keys.
+   */
+  readonly exact: boolean;
+  /** `true` when only a lazy part reaches the reference. An evaluation can then give a value without this read (FACTS.LAZY). */
+  readonly lazy: boolean;
+  /** `true` when the position of the reference declares an address. The read gives what the path reaches, not its value. */
+  readonly address: boolean;
+  /** The path of the reference: its root and its steps. */
+  readonly path: readonly Json[];
+  /** The keys from the root document to the reference document, through the parts. */
+  readonly place: readonly Key[];
+  /** The keys from the root JSON value to the reference document. */
+  readonly at: readonly Key[];
+}
+/** The static facts of one document (D24). They depend only on the document and the machine, not on a context. */
+interface DocFacts {
+  /**
+   * The free references, in the order of the document (FACTS.READS). A reference to a name that a kind binds is not
+   * here. The roots that a kind declares in `reads` are here too, each one at the place of its document.
+   */
+  readonly reads: readonly StaticRead[];
+  /** `"run"` when one kind of the document is on the run side (FACTS.SIDE). */
+  readonly side: Side;
+  /** The kinds of the effects that the contracts declare, as texts with dots, each one time (FACTS.EFFECTS). */
+  readonly effects: readonly string[];
+  /**
+   * `true` when each kind of the document declares `pure`, and the document has no effect and is not volatile. Then
+   * its result depends only on what its reads give (FACTS.PURE).
+   */
+  readonly pure: boolean;
+  /** `true` when the result can change while each read gives the same thing, for example with a clock (FACTS.VOLATILE). */
+  readonly volatile: boolean;
+  /** The number of documents in the document: a hint of the cost of an evaluation. */
+  readonly size: number;
+}
+/** The options of `factsOf`. */
+interface FactsOptions {
+  /** The type of a bare root value. */
+  readonly declaredType?: string;
+  /**
+   * The verb whose evaluators the facts describe, as in `prepare`. The default is `eval`. The contract of a kind
+   * describes the code of `eval` only. For another verb, only the hook `facts` describes the code (FACTS.VERB).
+   */
+  readonly verb?: string;
+  /**
+   * This function tells if a read reaches a volatile value of the host, for example a function that reads a clock.
+   * A read that it marks makes the document volatile (FACTS.VOLATILE).
+   *
+   * @param read - The read.
+   * @returns `true` when the read reaches a volatile value.
+   */
+  readonly volatile?: (read: StaticRead) => boolean;
+}
+/**
+ * This function gives the static facts of a document, for a schedule (R4 P2, D24). It walks the document one time,
+ * by the contracts of its kinds:
+ *
+ * - `reads`: each free reference, with the root and the keys of its path. A read under a lazy part has the mark
+ *   `lazy`, for example a read in a branch of `if`. A read after a step document has `exact: false`. A kind that
+ *   declares `reads` adds a read of each of its roots at each document of the kind.
+ * - `side` and `effects`: from the contract of each kind.
+ * - `pure`: each kind declares `pure`, and the document has no effect and is not volatile.
+ * - `volatile`: a kind, an operation or a step document declares `volatile`, or the host marks a read.
+ *
+ * The hook `facts` of the machine answers for a name that a fallback kind covers, for example an operation. Its
+ * answer wins over the contract of the kind. The contract of a kind does not describe the evaluator of an own
+ * entry. Thus a document with an own entry for another evaluator is not pure, and each of its parts is lazy. The
+ * hook can still answer for that evaluator.
+ *
+ * The option `verb` names the verb whose code the facts describe (FACTS.VERB). A contract describes the code of
+ * `eval`, thus the rule of an own entry applies to each document for another verb. The side and the effects come
+ * from the contracts for each verb.
+ *
+ * A read is one resolution of its path. A reference that the resolution reaches and follows is a part of that read
+ * (DEREF.COLLAPSE), not a separate read. The facts depend only on the document and the machine. Thus a host computes
+ * them again only after an edit of the document or of the machine.
+ *
+ * @param machine - The world, the code and the hook `facts`.
+ * @param doc - The document, as JSON.
+ * @param options - The type of a bare root value, the verb and the volatile reads of the host.
+ * @returns The facts.
+ */
+export declare function factsOf(machine: Machine, doc: unknown, options?: FactsOptions): DocFacts;
+//#endregion
 //#region src/evaluate.d.ts
 /**
  * This function makes a context with names and capabilities. The other roots are empty, and an evaluation sets
@@ -1614,8 +1730,8 @@ interface Read {
    */
   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.
+   * `true` when the kernel adds the read, because a value keeps the context for later (READS.KEPT). Such a read has
+   * a whole root as its path, or a path that a closure can read (READS.CLOSURE).
    */
   readonly kept?: true;
   /** The hops of the resolution, only when the code asked for them. `verifyReads` then compares each hop too. */
@@ -1700,9 +1816,13 @@ interface Runtime {
   /**
    * 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).
+   * gets a kept read of each path that the value can read (READS.CLOSURE). Without the static reads, the list gets a
+   * read of each root of the context (READS.KEPT).
+   *
+   * @param context - The context that the value keeps.
+   * @param reads - This function gives the static reads of the value, or `undefined` when they are not known.
    */
-  keepsContext?(): void;
+  keepsContext?(context?: Context, reads?: () => readonly StaticRead[] | undefined): void;
 }
 /**
  * The options of a drive of parts at the same time.
@@ -2077,6 +2197,17 @@ interface PrepareOptions {
    * evaluates one time, when the plan compiles. Its result is one frozen value for each evaluation (PLAN.FOLD).
    */
   readonly fold?: boolean;
+  /**
+   * The values that the host declares fixed for each evaluation of the plan (PLAN.FIXED, D60). The field `names` gives
+   * a value for each fixed name. A path from a fixed name then resolves one time, when the plan compiles, and a pure
+   * part that reads only fixed names folds. Only a deeply frozen value of plain data fixes its name.
+   *
+   * Each folded part compares the value of its names with one own-key test and `Object.is`. A different value gives
+   * the code without the fold. A plan without folds ignores this option.
+   */
+  readonly fixed?: {
+    readonly names?: Readonly<Record<string, unknown>>;
+  };
 }
 /** A compiled document. It evaluates many times, and it does the work of the ladder one time. */
 interface Plan {
@@ -2463,6 +2594,15 @@ interface AttributeTrace {
  * @returns The record, or `undefined` for a thing that is not a node or an attribute that no demand reached.
  */
 export declare function attributeTrace(node: Thing, attribute: string): AttributeTrace | undefined;
+/**
+ * This function gives the place of a node of the decorated tree: the keys from the root document to the document of
+ * the node (HOP.PLACE). A view puts each hop of a resolution on its node with it. The node keeps its place already,
+ * thus the function adds no record.
+ *
+ * @param thing - A thing, for example the thing of a hop.
+ * @returns The keys of the place, or `undefined` for a thing that is not a node of the decorated tree.
+ */
+export declare function placeOf(thing: Thing): readonly Key[] | undefined;
 /** The options of a walker `nearest`. */
 interface NearestOptions {
   /**
@@ -2475,13 +2615,18 @@ interface NearestOptions {
   readonly matches?: (node: Thing, wanted: Json | undefined) => boolean;
   /** The most hops of one walk. The default is 256. */
   readonly maxHops?: number;
+  /**
+   * `true`: the walk records one hop for each node on the way before the node that it reaches (HOP.EACH-STEP). Each
+   * such hop has the followed key as its step. The default is `false`: one hop for the whole walk.
+   */
+  readonly eachStep?: boolean;
 }
 /**
  * This function makes a walker `nearest`. The walker follows a key (the default is `parent`) until the node that it
  * reaches has the wanted type. With `self: true`, the node where the walk starts is the first candidate. A node
- * without that key ends the walk with an error.
+ * without that key ends the walk with an error. With `eachStep`, a resolution with hops gets a hop for each node on the way.
  *
- * @param options - The test of a type and the most hops.
+ * @param options - The test of a type, the most hops and the record of each step.
  * @returns The walker.
  */
 export declare function nearestWalker(options?: NearestOptions): Walker;
@@ -2598,103 +2743,6 @@ interface Construct {
 /** Six constructs that show the range of the context. */
 export declare const CONSTRUCTS: readonly Construct[];
 //#endregion
-//#region src/facts.d.ts
-/**
- * One read of a document: a free reference, with its marks (FACTS.READS). A plan resolves the path of the reference
- * when it evaluates the reference. The static read covers each path that the plan resolves there (FACTS.SOUND). A
- * root that a kind declares in `reads` is a read too, with the path of the root alone.
- */
-interface StaticRead {
-  /** The root of the path. */
-  readonly root: Root;
-  /** The keys after the root, up to the first step that is not a key. */
-  readonly keys: readonly Key[];
-  /**
-   * `true` when each step after the root is a key. Then the plan resolves this path and no other. A step document,
-   * for example `nearest`, makes it `false`: the plan resolves a path that starts with the keys.
-   */
-  readonly exact: boolean;
-  /** `true` when only a lazy part reaches the reference. An evaluation can then give a value without this read (FACTS.LAZY). */
-  readonly lazy: boolean;
-  /** `true` when the position of the reference declares an address. The read gives what the path reaches, not its value. */
-  readonly address: boolean;
-  /** The path of the reference: its root and its steps. */
-  readonly path: readonly Json[];
-  /** The keys from the root document to the reference document, through the parts. */
-  readonly place: readonly Key[];
-  /** The keys from the root JSON value to the reference document. */
-  readonly at: readonly Key[];
-}
-/** The static facts of one document (D24). They depend only on the document and the machine, not on a context. */
-interface DocFacts {
-  /**
-   * The free references, in the order of the document (FACTS.READS). A reference to a name that a kind binds is not
-   * here. The roots that a kind declares in `reads` are here too, each one at the place of its document.
-   */
-  readonly reads: readonly StaticRead[];
-  /** `"run"` when one kind of the document is on the run side (FACTS.SIDE). */
-  readonly side: Side;
-  /** The kinds of the effects that the contracts declare, as texts with dots, each one time (FACTS.EFFECTS). */
-  readonly effects: readonly string[];
-  /**
-   * `true` when each kind of the document declares `pure`, and the document has no effect and is not volatile. Then
-   * its result depends only on what its reads give (FACTS.PURE).
-   */
-  readonly pure: boolean;
-  /** `true` when the result can change while each read gives the same thing, for example with a clock (FACTS.VOLATILE). */
-  readonly volatile: boolean;
-  /** The number of documents in the document: a hint of the cost of an evaluation. */
-  readonly size: number;
-}
-/** The options of `factsOf`. */
-interface FactsOptions {
-  /** The type of a bare root value. */
-  readonly declaredType?: string;
-  /**
-   * The verb whose evaluators the facts describe, as in `prepare`. The default is `eval`. The contract of a kind
-   * describes the code of `eval` only. For another verb, only the hook `facts` describes the code (FACTS.VERB).
-   */
-  readonly verb?: string;
-  /**
-   * This function tells if a read reaches a volatile value of the host, for example a function that reads a clock.
-   * A read that it marks makes the document volatile (FACTS.VOLATILE).
-   *
-   * @param read - The read.
-   * @returns `true` when the read reaches a volatile value.
-   */
-  readonly volatile?: (read: StaticRead) => boolean;
-}
-/**
- * This function gives the static facts of a document, for a schedule (R4 P2, D24). It walks the document one time,
- * by the contracts of its kinds:
- *
- * - `reads`: each free reference, with the root and the keys of its path. A read under a lazy part has the mark
- *   `lazy`, for example a read in a branch of `if`. A read after a step document has `exact: false`. A kind that
- *   declares `reads` adds a read of each of its roots at each document of the kind.
- * - `side` and `effects`: from the contract of each kind.
- * - `pure`: each kind declares `pure`, and the document has no effect and is not volatile.
- * - `volatile`: a kind, an operation or a step document declares `volatile`, or the host marks a read.
- *
- * The hook `facts` of the machine answers for a name that a fallback kind covers, for example an operation. Its
- * answer wins over the contract of the kind. The contract of a kind does not describe the evaluator of an own
- * entry. Thus a document with an own entry for another evaluator is not pure, and each of its parts is lazy. The
- * hook can still answer for that evaluator.
- *
- * The option `verb` names the verb whose code the facts describe (FACTS.VERB). A contract describes the code of
- * `eval`, thus the rule of an own entry applies to each document for another verb. The side and the effects come
- * from the contracts for each verb.
- *
- * A read is one resolution of its path. A reference that the resolution reaches and follows is a part of that read
- * (DEREF.COLLAPSE), not a separate read. The facts depend only on the document and the machine. Thus a host computes
- * them again only after an edit of the document or of the machine.
- *
- * @param machine - The world, the code and the hook `facts`.
- * @param doc - The document, as JSON.
- * @param options - The type of a bare root value, the verb and the volatile reads of the host.
- * @returns The facts.
- */
-export declare function factsOf(machine: Machine, doc: unknown, options?: FactsOptions): DocFacts;
-//#endregion
 //#region src/effects.d.ts
 /** The options of `effectsOf`. */
 interface EffectsOptions {
@@ -3116,10 +3164,20 @@ interface ReferenceOptions {
    */
   readonly verb?: string;
 }
+/** The options of a run of the reference: the options of an evaluation, with the host and a signal (REF.RUN). */
+interface ReferenceRunOptions extends ReferenceOptions {
+  /**
+   * The host code that does each effect of a runner. A promise from it makes the run wait. Without it, an effect gives
+   * its payload. A journal on the function sets the order of the waits of each `all` (RUN.REPLAY).
+   */
+  readonly perform?: Perform;
+  /** A signal of the host. When it aborts, the run stops with `#ABORT` (RUN.ABORT). */
+  readonly signal?: StopSignal;
+}
 /**
  * This function evaluates a document by the rules, without a compilation. It is the reference of the plans: a plan,
- * a traced plan and the second tier of a language must give its results. It covers evaluations, not runs: an effect
- * gives the answer of the mock or its payload, and a part that waits gives `#CALC!`.
+ * a traced plan and the second tier of a language must give its results. In an evaluation, an effect gives the answer
+ * of the mock or its payload, and a part that waits gives `#CALC!`. `referenceRun` reads the rules of a run.
  *
  * The verb of the options goes up the ladder at each document, as in `prepare`. Each verb has the same rules: the
  * ladder, the contract of the kind and the sealed parts (VERB.AGREE).
@@ -3131,6 +3189,22 @@ interface ReferenceOptions {
  * @returns The result.
  */
 export declare function reference(machine: Machine, doc: unknown, context?: Context, options?: ReferenceOptions): Result;
+/**
+ * This function starts a run of a document by the rules, without a compilation (REF.RUN). The host does each effect of a runner,
+ * and a step waits when the host waits (RUN.SEQ). `all` settles the waits in the order of the host, or in the order
+ * of the journal of a replay (RUN.REPLAY). An effect of an evaluator gives `#CALC!` (RUN.NEEDS-RUNNER). A signal that
+ * aborts stops the run with `#ABORT` (RUN.ABORT).
+ *
+ * The part of the run before the first wait happens at once, in the call (RUN.EAGER). `agreeRun` compares the run of
+ * a plan with this run.
+ *
+ * @param machine - The world, the evaluators and the runners.
+ * @param doc - The document.
+ * @param context - The names and the capabilities at the root.
+ * @param options - The options of `reference`, the host and a signal.
+ * @returns The result, when the run ends.
+ */
+export declare function referenceRun(machine: Machine, doc: unknown, context?: Context, options?: ReferenceRunOptions): Promise<Result>;
 /**
  * The definitions of the reference for the evaluators of the standard machine that need their own reading. The
  * reference uses them for the standard evaluators, also without the option `definitions`. It holds `tree.node`.
@@ -3155,9 +3229,11 @@ export declare function formulaDefinitions(profile?: FormulaProfile): Definition
  * - `again`: a second evaluation of the same plan.
  * - `folds`: a second plan with the other choice of folds (PLAN.FOLD). It has no folds when the plan has them, and
  *   it has folds when the option `observe` stops the folds of the plan.
+ * - `fixed`: a plan that declares each name of plain data fixed (PLAN.FIXED). It evaluates with a frozen copy of
+ *   each such name, and then with the context of `agree`. `agreeRun` does not have this tier.
  * - `other`: the second tier of a language, from the option `other`.
  */
-type Tier = "reference" | "traced" | "again" | "folds" | "other";
+type Tier = "reference" | "traced" | "again" | "folds" | "fixed" | "other";
 /** What a second tier gives: its result, and its effects when it records them. */
 interface TierResult {
   readonly result: Result;
@@ -3183,8 +3259,8 @@ interface AgreeOptions {
   /** The definitional code of the compiled evaluators of the machine, for the reference. */
   readonly definitions?: Definitions;
   /**
-   * The tiers to compare with the plan. The default is the reference, the traced evaluation, a second evaluation and
-   * the plan with the other choice of folds.
+   * The tiers to compare with the plan. The default is the reference, the traced evaluation, a second evaluation, the
+   * plan with the other choice of folds and the plan with fixed names.
    */
   readonly tiers?: readonly Exclude<Tier, "other">[];
   /**
@@ -3268,6 +3344,29 @@ export declare function sameValue(a: unknown, b: unknown, equal?: (a: unknown, b
  * @returns The result of the plan, or the first tier that disagrees and the reason.
  */
 export declare function agree(machine: Machine, doc: unknown, context?: Context, options?: AgreeOptions): Agreement;
+/** The options of `agreeRun`: the options of `agree` without the second tier of a language. */
+interface AgreeRunOptions extends Omit<AgreeOptions, "other" | "perform"> {
+  /**
+   * The host of the run of the plan (RUN.AGREES). A recorder wraps it, and each other tier replays the log of that run.
+   * Thus the host does each effect one time. Without it, an effect gives its payload.
+   */
+  readonly perform?: Perform;
+}
+/**
+ * This function compares the run of a document in a plan with its run in other tiers (RUN.AGREES). First the plan
+ * starts the run with a recorder around the host. Then each tier replays the log of that run. These tiers are the
+ * reference run, the traced run, a second run of the plan and the plan with the other choice of folds.
+ *
+ * The rules of `agree` compare the results and the effects, with their addresses and outcomes. A tier must also
+ * settle the waits of each `all` in the order of the plan, thus a replay keeps the order of the waits.
+ *
+ * @param machine - The world, the evaluators and the runners.
+ * @param doc - The document.
+ * @param context - The names and the capabilities at the root.
+ * @param options - The tiers, the definitions for the reference, the rules of the comparison and the host.
+ * @returns The result of the plan, or the first tier that disagrees and the reason.
+ */
+export declare function agreeRun(machine: Machine, doc: unknown, context?: Context, options?: AgreeRunOptions): Promise<Agreement>;
 //#endregion
 //#region src/conform.d.ts
 /**
@@ -3712,6 +3811,269 @@ export declare function edgesOf(facts: DocFacts): readonly NodeEdge[];
  */
 export declare function schedule(machine: Machine, options?: ScheduleOptions): Schedule;
 //#endregion
+//#region src/generate.d.ts
+/** A source of random numbers with a seed. The same seed gives the same numbers. */
+interface Random {
+  /** This function gives a number from 0 up to 1, without 1. */
+  next(): number;
+  /** This function gives a whole number from 0 up to `below`, without `below`. */
+  int(below: number): number;
+  /** This function gives `true` with the chance `p`. */
+  chance(p: number): boolean;
+  /** This function gives one item of a list that is not empty. */
+  pick<T>(items: readonly T[]): T;
+}
+/**
+ * This function makes a source of random numbers with a seed (the algorithm mulberry32). It needs no package.
+ *
+ * @param seed - The seed: a whole number.
+ * @returns The source.
+ */
+export declare function random(seed: number): Random;
+/** The options of `generate`. */
+interface GenerateOptions {
+  /** The seed. The same seed and the same options give the same document. */
+  readonly seed: number;
+  /** The types that a document can have. The default is `typesOf(world)`. A namespace with a fallback needs its keys here. */
+  readonly types?: readonly (readonly Key[])[];
+  /** The type of a bare root value. */
+  readonly declaredType?: string;
+  /** The names that the host binds at the root. */
+  readonly names?: readonly string[];
+  /** The deepest nesting of documents. The default is 4. */
+  readonly maxDepth?: number;
+  /** The most documents in one document. The default is 24. */
+  readonly maxSize?: number;
+  /** The chance of a malformed choice at each document. The default is 0.05. */
+  readonly malformed?: number;
+  /**
+   * This function gives the data of a document of a type without parts, for example a number for the kind `number`.
+   *
+   * @param type - The keys of the type.
+   * @param random - The source of random numbers.
+   * @returns The data, or `undefined` for a random JSON value.
+   */
+  readonly data?: (type: readonly Key[], random: Random) => Json | undefined;
+  /**
+   * This function gives the types to prefer for a part, for example a function for the field `fn` of `call`.
+   *
+   * @param type - The keys of the type of the parent.
+   * @param path - The path of the part in the value of the parent.
+   * @returns The types, or `undefined` for no preference.
+   */
+  readonly hints?: (type: readonly Key[], path: readonly Key[]) => readonly (readonly Key[])[] | undefined;
+  /** The evaluator names for own entries. The default is none. */
+  readonly own?: readonly string[];
+  /** The keys for the steps of a path after its root and its name. */
+  readonly keys?: readonly Key[];
+  /** The roots that a path can start at. The default is each root. */
+  readonly roots?: readonly Root[];
+  /** The most steps of a path after its root and its name. The default is 2. */
+  readonly steps?: number;
+}
+/**
+ * This function lists the types of a world: each kind and each alias, also in a namespace. A namespace with a
+ * fallback gives no types, because each key names a kind.
+ *
+ * @param world - The world.
+ * @returns The keys of each type.
+ */
+export declare function typesOf(world: World): readonly (readonly Key[])[];
+/**
+ * This function builds a random document for a world from the contracts of its kinds. It reads the shapes of the
+ * parts, the declared types, the permitted kinds and the names that the scope rules bind. Some choices are malformed
+ * on purpose, for example an unknown kind or an unknown name under a namespace with a fallback. Other examples are a
+ * value without its shape, a bare value without a type and a name that nothing binds. The depth and the size have
+ * limits.
+ *
+ * @param world - The world.
+ * @param options - The seed, the types, the limits and the data of the leaves.
+ * @returns The document, as JSON.
+ */
+export declare function generate(world: World, options: GenerateOptions): unknown;
+//#endregion
+//#region src/meaning.d.ts
+/**
+ * The smallest interface of the engine of a host that `agreeSchedule` examines (SCHED.AGREES). The demand schedule of
+ * `schedule` has this interface.
+ */
+interface ScheduleEngine {
+  /**
+   * This function adds a node, or gives a node a new document. The harness also gives the same document object again:
+   * a change of the structure without an edit.
+   *
+   * @param id - The name of the node.
+   * @param doc - The document of the node. It does not change in place.
+   */
+  set(id: string, doc: unknown): void;
+  /**
+   * This function removes a node. A later read of the node by another node gives the error of a missing step.
+   *
+   * @param id - The name of the node.
+   */
+  remove(id: string): unknown;
+  /**
+   * This function gives the engine the new context of the host. The values of a context do not change in place. The
+   * same context object again is a change of data that changes no value.
+   *
+   * @param context - The context of the host, without the root `world`.
+   */
+  changeData(context: Context): void;
+  /**
+   * This function gives the engine a new machine. The harness gives no new machine to an engine without this function.
+   *
+   * @param machine - The new machine.
+   */
+  changeMachine?(machine: Machine): void;
+  /**
+   * This function demands a node and gives its answer.
+   *
+   * @param id - The name of the node. The engine has the node.
+   * @returns The result of the node.
+   */
+  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. */
+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;
+}
+/**
+ * This function makes a new engine with no nodes. The harness makes one engine for each run. The function `schedule`
+ * has this form.
+ */
+type ScheduleEngineFactory = (machine: Machine, start: ScheduleEngineStart) => ScheduleEngine;
+/**
+ * The options of `agreeSchedule`. The defaults fit `STD_MACHINE`. A host with another machine also gives `generate`,
+ * `value` and `wire`, and it sets `runs` to `false` when its world has no kind `log`.
+ */
+interface AgreeScheduleOptions {
+  /** The machines. The first machine starts each run, and the command of a new machine takes the next one. The default is `STD_MACHINE` and a copy. */
+  readonly machines?: readonly Machine[];
+  /** The type of a bare root value, for each engine, each plan and each fact. */
+  readonly declaredType?: string;
+  /** The options of the document generator. Each generated path from `names` to a node changes into a path from `world`. */
+  readonly generate?: Omit<GenerateOptions, "seed" | "names">;
+  /**
+   * This function gives a small value document.
+   *
+   * @param rng - The source of random numbers.
+   * @returns The document.
+   */
+  readonly value?: (rng: Random) => unknown;
+  /**
+   * This function gives a document that reads one or two nodes, for dense graphs with many cycles.
+   *
+   * @param rng - The source of random numbers.
+   * @param node - This function gives a reference to a random node.
+   * @returns The document.
+   */
+  readonly wire?: (rng: Random, node: () => Json) => unknown;
+  /** The share of the nodes that `wire` gives. The default is 0.2. */
+  readonly wired?: number;
+  /** `true`: one generated document in ten goes into the kind `log`, thus the node is on the run side. The default is `true`. */
+  readonly runs?: boolean;
+  /** The names of the nodes. The default is five names. */
+  readonly nodes?: readonly string[];
+  /** The names that the context of the host binds at the root `names`. The default is `a`, `b`, `x` and `n`. */
+  readonly names?: readonly string[];
+  /** The values that a change of data gives a name of the host. The default has equal values, host values and a `Held` error. */
+  readonly values?: readonly unknown[];
+  /** The contexts of the host at the start of the runs, one after the other. */
+  readonly contexts?: readonly Context[];
+  /** The number of runs. The default is 100. */
+  readonly count?: number;
+  /** The number of commands in one run. The default is 30. */
+  readonly steps?: number;
+  /** The seed of the first run, and one more for each later run. The default is 9000011. */
+  readonly seed?: number;
+  /**
+   * This function compares two values that the rules of `sameResult` do not know. It answers first. Without an answer,
+   * two closures of `fn` are the same when they have the same parameters.
+   *
+   * @param a - The value of the engine, or of the first evaluation from scratch.
+   * @param b - The value from scratch.
+   * @returns `true` or `false`, or `undefined` for the other rules.
+   */
+  readonly equal?: (a: unknown, b: unknown) => boolean | undefined;
+}
+/** What the harness reached: the commands, the reads, and the kinds of answers that it compared. */
+interface ScheduleAgreementCounts {
+  /** The reads of a node. */
+  readonly reads: number;
+  /** The reads with one answer from scratch, which the harness compared. */
+  readonly compared: number;
+  /** The reads whose answer from scratch is new at each evaluation. The harness does not compare them. */
+  readonly unrepeatable: number;
+  /** The compared answers that are a value. */
+  readonly values: number;
+  /** The compared answers that are the `#CYCLE!` of the node. */
+  readonly cycles: number;
+  /** The compared answers that are the `#REF!` of a node on the run side. */
+  readonly runs: number;
+  /** The changes of data with new names of the host. */
+  readonly data: number;
+  /** The changes of data that change no value. */
+  readonly empty: number;
+  /** The new documents of a node. */
+  readonly edits: number;
+  /** The new nodes. */
+  readonly additions: number;
+  /** The removed nodes. */
+  readonly removes: number;
+  /** The changes of the structure with the same document object. */
+  readonly same: number;
+  /** The new machines. */
+  readonly machines: number;
+}
+/** The outcome of `agreeSchedule`: what the harness reached, or the first disagreement. */
+type ScheduleAgreement = {
+  readonly ok: true;
+  readonly counts: ScheduleAgreementCounts;
+} | {
+  readonly ok: false;
+  /** The seed of the run. */
+  readonly seed: number;
+  /** The index of the command in the run. */
+  readonly step: number;
+  /** The node of the read. */
+  readonly node: string;
+  /** The answer of the engine. */
+  readonly engine: Result;
+  /** The answer of the evaluation from scratch. */
+  readonly scratch: Result;
+  /** The documents of the nodes at the read. */
+  readonly docs: ReadonlyMap<string, unknown>;
+  /** The context of the host at the read. */
+  readonly context: Context;
+  /** The machine at the read. */
+  readonly machine: Machine;
+  /** One sentence that tells the difference. */
+  readonly reason: string;
+  /** What the harness reached up to the read. */
+  readonly counts: ScheduleAgreementCounts;
+};
+/**
+ * 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.
+ *
+ * - 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`.
+ * - A read whose answer from scratch differs between the two evaluations is not compared.
+ * - Two errors agree when they have the same code, reason and place. Thus an engine gives the `#CYCLE!` and the
+ *   `#REF!` of D31.
+ *
+ * The same seed and the same options give the same commands, thus a disagreement occurs again.
+ *
+ * @param engine - This function makes a new engine for each run, for example `schedule`.
+ * @param options - The machines, the generator, the contexts, the number of runs and the rule for host values.
+ * @returns What the harness reached, or the first read whose answer differs from the answer from scratch.
+ */
+export declare function agreeSchedule(engine: ScheduleEngineFactory, options?: AgreeScheduleOptions): ScheduleAgreement;
+//#endregion
 //#region src/graph.d.ts
 /** One edge of a graph of nodes: a read of a node by another node. `NodeEdge` of a schedule is such an edge. */
 interface GraphEdge<Id> {
@@ -3879,87 +4241,6 @@ export declare function recorder(perform?: Perform): Recorder;
  */
 export declare function replayer(log: ReplayLog, options?: ReplayOptions): Perform;
 //#endregion
-//#region src/generate.d.ts
-/** A source of random numbers with a seed. The same seed gives the same numbers. */
-interface Random {
-  /** This function gives a number from 0 up to 1, without 1. */
-  next(): number;
-  /** This function gives a whole number from 0 up to `below`, without `below`. */
-  int(below: number): number;
-  /** This function gives `true` with the chance `p`. */
-  chance(p: number): boolean;
-  /** This function gives one item of a list that is not empty. */
-  pick<T>(items: readonly T[]): T;
-}
-/**
- * This function makes a source of random numbers with a seed (the algorithm mulberry32). It needs no package.
- *
- * @param seed - The seed: a whole number.
- * @returns The source.
- */
-export declare function random(seed: number): Random;
-/** The options of `generate`. */
-interface GenerateOptions {
-  /** The seed. The same seed and the same options give the same document. */
-  readonly seed: number;
-  /** The types that a document can have. The default is `typesOf(world)`. A namespace with a fallback needs its keys here. */
-  readonly types?: readonly (readonly Key[])[];
-  /** The type of a bare root value. */
-  readonly declaredType?: string;
-  /** The names that the host binds at the root. */
-  readonly names?: readonly string[];
-  /** The deepest nesting of documents. The default is 4. */
-  readonly maxDepth?: number;
-  /** The most documents in one document. The default is 24. */
-  readonly maxSize?: number;
-  /** The chance of a malformed choice at each document. The default is 0.05. */
-  readonly malformed?: number;
-  /**
-   * This function gives the data of a document of a type without parts, for example a number for the kind `number`.
-   *
-   * @param type - The keys of the type.
-   * @param random - The source of random numbers.
-   * @returns The data, or `undefined` for a random JSON value.
-   */
-  readonly data?: (type: readonly Key[], random: Random) => Json | undefined;
-  /**
-   * This function gives the types to prefer for a part, for example a function for the field `fn` of `call`.
-   *
-   * @param type - The keys of the type of the parent.
-   * @param path - The path of the part in the value of the parent.
-   * @returns The types, or `undefined` for no preference.
-   */
-  readonly hints?: (type: readonly Key[], path: readonly Key[]) => readonly (readonly Key[])[] | undefined;
-  /** The evaluator names for own entries. The default is none. */
-  readonly own?: readonly string[];
-  /** The keys for the steps of a path after its root and its name. */
-  readonly keys?: readonly Key[];
-  /** The roots that a path can start at. The default is each root. */
-  readonly roots?: readonly Root[];
-  /** The most steps of a path after its root and its name. The default is 2. */
-  readonly steps?: number;
-}
-/**
- * This function lists the types of a world: each kind and each alias, also in a namespace. A namespace with a
- * fallback gives no types, because each key names a kind.
- *
- * @param world - The world.
- * @returns The keys of each type.
- */
-export declare function typesOf(world: World): readonly (readonly Key[])[];
-/**
- * This function builds a random document for a world from the contracts of its kinds. It reads the shapes of the
- * parts, the declared types, the permitted kinds and the names that the scope rules bind. Some choices are malformed
- * on purpose, for example an unknown kind or an unknown name under a namespace with a fallback. Other examples are a
- * value without its shape, a bare value without a type and a name that nothing binds. The depth and the size have
- * limits.
- *
- * @param world - The world.
- * @param options - The seed, the types, the limits and the data of the leaves.
- * @returns The document, as JSON.
- */
-export declare function generate(world: World, options: GenerateOptions): unknown;
-//#endregion
 //#region src/providers.d.ts
 /** The type that a provider reads, and the problems of the reading. Each problem tells what the type does not test. */
 interface TypeReading {
@@ -4008,5 +4289,5 @@ interface SampleOptions {
  */
 export declare function typeFromSamples(values: readonly unknown[], options?: SampleOptions): ValueType;
 //#endregion
-export type { AgreeOptions, Agreement, Alias, AllOptions, Answer, AskOptions, AttributeDeclaration, AttributeRung, AttributeTrace, Cap, CapsRule, CheckOptions, Classification, Closure, Code, CompileInput, CompiledEvaluator, CompiledPart, CompiledRunner, ConformOptions, ConformProbe, Construct, Context, Part as ContextPart, Definitions, DerefCode, DocFacts, DocParts, DocVisit, Domain, DomainCodec, DomainExtension, Durable, DurableCounts, DurableOptions, Edge, Effect, EffectsOptions, Envelope, Epochs, ErrorCode, EvalError, EvalFn, EvalInput, EvalOptions, EvaluateOptions, Evaluator, ExtFn, FactsOptions, Failed, Finding, FormulaProfile, GenerateOptions, Give, GraphCycle, GraphEdge, GraphNode, GraphOptions, Header, Hop, HopBy, HostThing, Issue, Journal, Json, JsonRecord, KernelCode, Key, Kind, KindFacts, KindSource, LazyOp, LazyRule, Lookup, Machine, MachinePart, MergeConflict, MergePath, NamesSource, Namespace, Navigator, NearestOptions, NodeEdge, NodeGraph, NodeInfo, NodeRunOptions, Obligation, OpFn, OrderProblem, Outcome, ParseResult, Part$1 as Part, PartInfo, Shape as PartShape, PartSlot, PartType, PartsSpec, Perform, Plan, PlanRunOptions, PrepareOptions, Random, Read, ReadsCheck, Recorder, RefUse, ReferenceOptions, ReplayEntry, ReplayLog, ReplayOptions, ReplaySettle, Resolution, ResolveCode, ResolveOptions, Result, Root, RootTypes, Run, RunCode, RunFn, RunInput, RunOptions, RunPart, Rung, Runner, Runtime, SampleOptions, Schedule, ScheduleCounts, ScheduleOptions, ScopeRule, Shape$1 as Shape, Side, Signature, Split, StaticRead, Step, StepSpec, Steps, StopSignal, Stored, SyntaxAssoc, SyntaxCalls, SyntaxFixity, SyntaxForm, SyntaxIssue, SyntaxLiterals, SyntaxOperator, SyntaxProfile, SyntaxRefPattern, SyntaxRefs, Thing, Tier, TierInput, TierResult, TraceNode, TreeContract, TypeInput, TypeIssue, TypeProblem, TypeReading, TypeRef, TypeRule, Typed, Typing, Use, ValueType, VerbEffects, VerifyOptions, WalkInput, WalkOptions, WalkProblem, WalkResult, Walker, World, WorldEntry, WorldIssue, WorldPart };
+export type { AgreeOptions, AgreeRunOptions, AgreeScheduleOptions, Agreement, Alias, AllOptions, Answer, AskOptions, AttributeDeclaration, AttributeRung, AttributeTrace, Cap, CapsRule, CheckOptions, Classification, Closure, Code, CompileInput, CompiledEvaluator, CompiledPart, CompiledRunner, ConformOptions, ConformProbe, Construct, Context, Part as ContextPart, Definitions, DerefCode, DocFacts, DocParts, DocVisit, Domain, DomainCodec, DomainExtension, Durable, DurableCounts, DurableOptions, Edge, Effect, EffectsOptions, Envelope, Epochs, ErrorCode, EvalError, EvalFn, EvalInput, EvalOptions, EvaluateOptions, Evaluator, ExtFn, FactsOptions, Failed, Finding, FormulaProfile, GenerateOptions, Give, GraphCycle, GraphEdge, GraphNode, GraphOptions, Header, Hop, HopBy, HostThing, Issue, Journal, Json, JsonRecord, KernelCode, Key, Kind, KindFacts, KindSource, LazyOp, LazyRule, Lookup, Machine, MachinePart, MergeConflict, MergePath, NamesSource, Namespace, Navigator, NearestOptions, NodeEdge, NodeGraph, NodeInfo, NodeRunOptions, Obligation, OpFn, OrderProblem, Outcome, ParseResult, Part$1 as Part, PartInfo, Shape as PartShape, PartSlot, PartType, PartsSpec, Perform, Plan, PlanRunOptions, PrepareOptions, Random, Read, ReadsCheck, Recorder, RefUse, ReferenceOptions, ReferenceRunOptions, ReplayEntry, ReplayLog, ReplayOptions, ReplaySettle, Resolution, ResolveCode, ResolveOptions, Result, Root, RootTypes, Run, RunCode, RunFn, RunInput, RunOptions, RunPart, Rung, Runner, Runtime, SampleOptions, Schedule, ScheduleAgreement, ScheduleAgreementCounts, ScheduleCounts, ScheduleEngine, ScheduleEngineFactory, ScheduleEngineStart, ScheduleOptions, ScopeRule, Shape$1 as Shape, Side, Signature, Split, StaticRead, Step, StepSpec, Steps, StopSignal, Stored, SyntaxAssoc, SyntaxCalls, SyntaxFixity, SyntaxForm, SyntaxIssue, SyntaxLiterals, SyntaxOperator, SyntaxProfile, SyntaxRefPattern, SyntaxRefs, Thing, Tier, TierInput, TierResult, TraceNode, TreeContract, TypeInput, TypeIssue, TypeProblem, TypeReading, TypeRef, TypeRule, Typed, Typing, Use, ValueType, VerbEffects, VerifyOptions, WalkInput, WalkOptions, WalkProblem, WalkResult, Walker, World, WorldEntry, WorldIssue, WorldPart };
 //# sourceMappingURL=index.d.ts.map