@mark1russell7/coeval 0.22.0 → 0.23.0

package/build/index.d.ts

@@ -337,7 +337,8 @@ interface Domain {
 /**
  * The codec of a domain: it writes a member of the domain as JSON, and it reads the JSON again (D40). Both functions
  * must be pure. `decode(encode(v))` must equal `v` by `sameValue` (EXT.ROUNDTRIP). The codec must give one JSON
- * value for each member, thus the same value has the same document in each language (D12).
+ * value for each member, thus the same value has the same document in each language (D12). `codecLaws` examines
+ * these laws for the members of the domain (D130).
  */
 interface DomainCodec {
   /**
@@ -537,6 +538,15 @@ interface HostThing {
   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. */
 type Thing = unknown;
@@ -758,6 +768,44 @@ export declare function worldThing(world: World): Json;
  * @returns The context.
  */
 export declare function context(parts?: Partial<Context>): Context;
+/**
+ * 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. Code of a language reads a compiled path with `resolveCompiled`, thus the
+ * list of reads gets the read (PLAN.PATH-READS).
+ */
+interface CompiledPath {
+  /** The steps of the path, as the document gives them. The list of reads records these steps. */
+  readonly path: readonly unknown[];
+  /** 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. 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 })`.
+   */
+  resolve(ctx: Context): Resolution;
+}
+/**
+ * This function compiles one static path for one navigator. The resolver gives the same thing, error and reason as
+ * `resolve` without hops (PLAN.PATH-SAME). It keeps no value of a context.
+ *
+ * - Some paths take the full algorithm at once, because the short path cannot answer them. A path from `caps` or from
+ *   a closed root is one. A path with a step document and each path of a navigator with `adopt` are others.
+ * - Each other path walks the short path from its root, and it takes the full algorithm when the values need it.
+ * - 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. The compiled path keeps this list, thus the host must not change it.
+ * @returns The compiled path.
+ */
+export declare function compilePath(nav: Navigator, path: readonly unknown[]): CompiledPath;
 /**
  * This function resolves a path from a context, and records each hop.
  *
@@ -962,6 +1010,8 @@ interface KindFacts {
  *   whose attributes each declare `circular` gives a fixed point.
  * - `collect`: the value of a node without an answer of the first four rungs and without a fold. The node combines
  *   the contributions of each node of its subtree (TREE.COLLECT, D122).
+ * - `higher`: the value of a node without an answer of the rungs before it. The term gives a document as data. The kit
+ *   evaluates that document with the node as `self`, thus its root is a new node under the node (TREE.HIGHER, D126).
  */
 interface AttributeDeclaration {
   readonly copy?: boolean;
@@ -972,6 +1022,7 @@ interface AttributeDeclaration {
   readonly default?: Json;
   readonly circular?: CircularDeclaration;
   readonly collect?: CollectDeclaration;
+  readonly higher?: Json;
 }
 /**
  * The declaration `collect` of an attribute (TREE.COLLECT, D122). The node of the attribute visits each node of its
@@ -1012,6 +1063,8 @@ interface CircularDeclaration {
   readonly start: Json;
   readonly limit?: number;
 }
+/** The most generated documents on the way from a node to the root of its tree (TREE.HIGHER-DEPTH, D126). */
+export declare const GENERATION_LIMIT = 64;
 /** The most rounds of a circular attribute without its own `limit` (TREE.CIRCULAR-LIMIT, D113). */
 export declare const CIRCULAR_LIMIT = 100;
 /** A declaration `circular` that the kit can use: its start value and its limit, or the reason of a bad declaration. */
@@ -1052,6 +1105,8 @@ export declare function collectOf(declared: unknown): CollectRule;
  *   equation sees no names.
  * - `at`: the attributes with parameters of the node (TREE.AT, D124). Only the step `tree.at` reads them, and the
  *   equation sees each parameter as a name.
+ * - `forwards`: the name of an attribute that gives a node. An attribute that no other rung answers comes from that
+ *   node (TREE.FORWARD, D126).
  */
 interface TreeContract {
   readonly equations?: Readonly<Record<string, Json>>;
@@ -1059,6 +1114,7 @@ interface TreeContract {
   readonly attributes?: Readonly<Record<string, AttributeDeclaration>>;
   readonly contributes?: Readonly<Record<string, Json>>;
   readonly at?: Readonly<Record<string, AtEquation>>;
+  readonly forwards?: string;
 }
 /**
  * An attribute with parameters (TREE.AT, D124), as `paramAttr` in Kiama. The step `tree.at` gives the arguments. The
@@ -1112,6 +1168,15 @@ export declare function atArgsOf(params: readonly string[], args: unknown): AtAr
  * @returns The JSON text, or `undefined` for a value that is not JSON data: a number that is not finite, a host value or a cycle.
  */
 export declare function argsKey(value: unknown): string | undefined;
+/**
+ * This function gives the structural key of a document (TREE.HIGHER-PLAN, D126). The fields of a record keep their
+ * order, because the order of the parts decides the order of the JSON and the first error. Thus one key means one
+ * document, and the two documents are equal by DOC.EQUALS.
+ *
+ * @param doc - The document.
+ * @returns The JSON text, or `undefined` for a value that is not JSON data.
+ */
+export declare function documentKey(doc: unknown): string | undefined;
 /**
  * This function gives the type of a bare equation of a kind (D42). It is the type `of` of the shape of its parts, or
  * else the type `of` of the shape `rest` of a record. The plan, the reference and `check` read it with this one function.
@@ -2481,6 +2546,18 @@ interface EvaluateOptions {
   /** A list that gets each read, in the order of the resolutions (READS.RECORD). */
   readonly reads?: Read[];
 }
+/**
+ * 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
+ * (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.
+ * @param compiled - The compiled path, from `compilePath`.
+ * @returns What the path reached, or an error.
+ */
+export declare function resolveCompiled(rt: Runtime, ctx: Context, compiled: CompiledPath): Resolution;
 /** The options of a compilation. */
 interface PrepareOptions {
   /** The type of a bare root value. */
@@ -3091,6 +3168,21 @@ interface SyntaxHeader {
    */
   readonly bind?: string;
 }
+/**
+ * The text forms of the constructs of the formula kit (K145, D127). Each field is the kind of one form, with dots
+ * between the keys. A construct without a field has no text. Each text of a form was an issue before, and no form
+ * reserves a name.
+ */
+interface SyntaxConstructs {
+  /** The kind of the form `{a: 1, b: x}`. Its value is a record of documents. */
+  readonly record?: string;
+  /** The kind of the form `let {a: 1} in a + 1`. Its value has the fields `bind` and `body`. */
+  readonly let?: string;
+  /** The kind of the form `(x, y) => x + y`. Its value has the fields `params` and `body`. */
+  readonly fn?: string;
+  /** The kind of the form `(f)(1, 2)`: a call of a value. Its value has the fields `fn` and `args`. */
+  readonly call?: string;
+}
 /**
  * The text syntax of a language (D41): an operator table, literal rules, reference syntax and call syntax. `parse`
  * reads a text into a document, and `print` writes a document as text. The profile is data, thus a site, an editor
@@ -3107,6 +3199,8 @@ interface SyntaxProfile {
   readonly calls?: SyntaxCalls;
   /** The text of the header of a document. */
   readonly header?: SyntaxHeader;
+  /** The text forms of the constructs. Without a field, the construct has no text. */
+  readonly constructs?: SyntaxConstructs;
   /** The deepest nesting that `parse` accepts. The default is `256`. */
   readonly maxDepth?: number;
 }
@@ -3119,7 +3213,12 @@ interface SyntaxIssue {
   /** The message. */
   readonly message: string;
 }
-/** The result of `parse`: a document, or the problems of the text. */
+/**
+ * The most issues that `parse` gives for one text (D138). A person reads a list of this size, and a text with more
+ * issues needs another kind of help.
+ */
+export declare const MAX_SYNTAX_ISSUES = 20;
+/** The result of `parse`: a document, or the problems of the text in the order of their offsets (D138). */
 type ParseResult = {
   readonly ok: true;
   readonly doc: Json;
@@ -3131,12 +3230,14 @@ type ParseResult = {
  * The standard syntax of the formula kit. It gives the site and the playground a text form. The operators are
  * `or`, `and`, `not`, the comparisons, `+ - * / %`, a minus sign and `^`, from the loosest to the tightest. A call
  * `name(args)` applies the operation `ops.name`. `if(test, then, else)` and `list(items)` make the constructs. The
- * text `total = 2 + 3` gives the document the header name `total` (D62).
+ * text `total = 2 + 3` gives the document the header name `total` (D62). The forms `{a: 1}`, `let {a: 1} in a`,
+ * `(x) => x` and `(f)(1)` make `record`, `let`, `fn` and `call` (D127).
  */
 export declare const STD_SYNTAX: SyntaxProfile;
 /**
  * This function reads a text into a document with the rules of a profile (SYNTAX.PARSE). It does not throw for a
- * bad text. The issue gives the offset, the length and a message (SYNTAX.SPAN).
+ * bad text. Each issue gives the offset, the length and a message (SYNTAX.SPAN). The field `issues` gives at most
+ * `MAX_SYNTAX_ISSUES` issues (SYNTAX.ISSUES-ALL). A host that reads the first issue reads the first fault of the text.
  *
  * @param profile - The syntax profile.
  * @param text - The text.
@@ -3185,7 +3286,7 @@ export declare const WORLD_SYNTAX: SyntaxProfile;
 /** The code of the evaluators of the standard world, by name. */
 export declare const STD_EVALUATORS: Readonly<Record<string, Evaluator>>;
 /** The rungs of the ladder of an attribute, in their order (TREE.LADDER, D42). */
-type AttributeRung = "own" | "kind" | "parent" | "copy" | "default";
+type AttributeRung = "own" | "kind" | "parent" | "copy" | "default" | "forward";
 /** The rungs of the ladder of an attribute, in their order (TREE.LADDER, D42). */
 export declare const ATTRIBUTE_RUNGS: readonly AttributeRung[];
 /** The record of the demand of one attribute of a node (TREE.RUNGS). */
@@ -3656,6 +3757,65 @@ export declare function encodeValue(machine: Pick<Machine, "domains">, value: un
  * @returns The value, or the error of the evaluation.
  */
 export declare function decodeValue(machine: Machine, doc: unknown): Result;
+/**
+ * A law of a codec that `codecLaws` checks.
+ *
+ * - `samples`: the check has at least one member of the domain. Without a member, the check proves nothing.
+ * - `encode`: `encode` writes each member, and it does not throw.
+ * - `json`: the data of `encode` is JSON. `JSON.parse(JSON.stringify(data))` gives equal data, thus the data has no
+ *   `NaN`, no `-0`, no infinity, no `undefined`, no function, no host object and no cycle.
+ * - `stable`: the same member has one document. A second `encode` of the member gives equal data, and so does an
+ *   `encode` of the decoded member. The check compares with `docEquals`.
+ * - `decode`: `decodeDomain` reads the JSON copy of the data, and it gives a member of the domain.
+ * - `roundtrip`: the decoded member equals the member by `sameValue`.
+ */
+type CodecLaw = "samples" | "encode" | "json" | "stable" | "decode" | "roundtrip";
+/** The probe of a finding of `codecLaws`: the domain, the member and the data of the member. */
+interface CodecProbe {
+  /** The name of the domain. */
+  readonly domain: string;
+  /** The member that shows the finding. The law `samples` has no member, thus the value is `undefined`. */
+  readonly value: unknown;
+  /** The data that `encode` gave for the member. The laws `samples` and `encode` have no data. */
+  readonly data?: unknown;
+}
+/** One law that a codec breaks, with the reason and the first probe that shows it. The form is the form of `Finding`. */
+interface CodecFinding {
+  readonly obligation: CodecLaw;
+  /** One sentence that tells what the codec did. */
+  readonly reason: string;
+  readonly probe: CodecProbe;
+}
+/** The options of `codecLaws`. */
+interface CodecLawsOptions {
+  /** More members of the domain. They come first. A value that is not a member of the domain gets no test. */
+  readonly samples?: readonly unknown[];
+  /**
+   * This function compares two values that the rules of `sameValue` do not know, as in `agree`. A member that is an
+   * object needs this rule, for example a date, because `sameValue` compares an object only with itself.
+   *
+   * @param a - The first value.
+   * @param b - The second value.
+   * @returns `true` or `false`, or `undefined` for the rules of `sameValue`.
+   */
+  readonly equal?: (a: unknown, b: unknown) => boolean | undefined;
+}
+/**
+ * This function examines the laws of the codec of one domain of a machine (K141, D130). A test of a language starts it
+ * for each domain with a codec. The members are the list `values` of the domain, or else the given samples, the edge
+ * values and the lists `samples` of the domains. Each value that is not a member gets no test.
+ *
+ * The law `decode` reads the JSON copy of the data through `decodeDomain`, as an evaluation of `ext.domain` does. Thus
+ * a codec that reads a data object by its identity breaks a law. The finding of a law names the first member that
+ * breaks it. An empty list means that each member keeps each law.
+ *
+ * @param machine - The machine, or only its domains.
+ * @param name - The name of the domain.
+ * @param options - The samples and the rule of equality.
+ * @returns The first finding of each law that the codec breaks, in the order of the laws.
+ * @throws {Error} The machine has no domain with the name, or the domain has no codec.
+ */
+export declare function codecLaws(machine: Pick<Machine, "domains">, name: string, options?: CodecLawsOptions): readonly CodecFinding[];
 /**
  * The definitional code of the reference, by evaluator name. The reference cannot read compiled code, thus each
  * compiled evaluator or runner of a machine needs a definition here. A function evaluator needs none.
@@ -3913,12 +4073,20 @@ export declare function agreeRun(machine: Machine, doc: unknown, context?: Conte
  * - `C8`: compiled code gives the result of code that compiles again at the time of the evaluation.
  * - `local`: the code keeps no state from one call to the next.
  * - `agree`: compiled code gives the result of its definition for the reference interpreter.
+ * - `parallel`: the code gives the same result, the same parts and the same effects in each order of the waits of
+ *   `all` (D128). Only a runner gets this check.
  * - `truth`: the own `truthy` of a formula profile gives `true` or `false` for each member of its `truthType` (D86).
  *   Only `formula.if`, `formula.and` and `formula.or` of the formula kit get this check.
  * - `cover`: each sample of a covered domain of the machine is in one domain of each cover of the domain (D94). Each
  *   evaluator and each runner gets this check, because `fits` trusts the covers for each program.
- */
-type Obligation = "C1" | "C2" | "C3" | "C4" | "C5" | "C6" | "C7" | "C8" | "local" | "agree" | "truth" | "cover";
+ * - `result`: a walker, the code of a `deref` or a function of a profile gives the form that its type states. A walker
+ *   and the code of a `deref` throw nothing, except a `Failure` (D137).
+ * - `ladder`: a walker steps on a host thing only through `deref` and `has` of its input (D137).
+ * - `hops`: each `visit` of a walker tells a step that the walk followed. Without `visit`, the walk stays the same (D137).
+ * - `has`: the function `has` of the code of a `deref` gives a truth, and `true` for each key that the code answers (D137).
+ * - `typed`: a walker keeps its type rule, an operation its signatures and an extension its entry in `extTypes` (D137).
+ */
+type Obligation = "C1" | "C2" | "C3" | "C4" | "C5" | "C6" | "C7" | "C8" | "local" | "agree" | "parallel" | "truth" | "cover" | "result" | "ladder" | "hops" | "has" | "typed";
 /** The probe of a finding: the document, the result of each probe part, the capabilities and the handler. */
 interface ConformProbe {
   /** The text of the type of the document. */
@@ -3933,6 +4101,10 @@ interface ConformProbe {
   readonly caps: readonly Cap[];
   /** `true` in a run, in which the host does each effect and a part can wait. */
   readonly running: boolean;
+  /** The thing before the step, in a finding of a walker. */
+  readonly here?: unknown;
+  /** The key of the step, in a finding of the code of a `deref`. */
+  readonly key?: Key;
 }
 /** One obligation that the code breaks, with the reason and the first probe that shows it. */
 interface Finding {
@@ -3947,6 +4119,9 @@ interface ConformOptions {
    * The verb that the evaluator serves. The default is `eval`. The facts `pure` and `lazy` of a contract describe only
    * `eval`, thus `conforms` checks C3 and C4 only for `eval` (D23). `conforms` checks C2 for each verb that the
    * contract declares effects for: `eval`, and each verb with an entry in `verbEffects` (D49).
+   *
+   * The verb `step` selects the walker of the name, and the verb `deref` selects the code of the `deref` of the name
+   * (D137). Without the option, a name that no evaluator and no runner has selects its walker, and then its `deref`.
    */
   readonly verb?: string;
   /**
@@ -3969,11 +4144,16 @@ interface ConformOptions {
    * definition from `STD_DEFINITIONS`.
    */
   readonly definitions?: Definitions;
+  /**
+   * More things before the step of a walker (D137). Use them for the things that a walker needs, for example a host
+   * thing of the language. The default holds three probe nodes, a document, `undefined` and the values of the results.
+   */
+  readonly things?: readonly unknown[];
   /** The capabilities of half of the probes. The other half has none. The default is the declared effects and `probe`. */
   readonly caps?: readonly Cap[];
   /** The names of the context of each probe. */
   readonly names?: Readonly<Record<string, unknown>>;
-  /** The seed of the random results. The same seed gives the same probes. The default is 1. */
+  /** The seed of the random results and of the orders of `all`. The same seed gives the same probes. The default is 1. */
   readonly seed?: number;
   /** The count of probes with random results for each probe document. The default is 12. */
   readonly runs?: number;
@@ -3998,11 +4178,18 @@ interface ConformOptions {
  * compiled code with its definition. The finding of an obligation names the first probe that breaks it. An empty list
  * means that each probe conforms.
  *
+ * The check `parallel` starts a runner with a choice of waits under `all` again, in other orders of the waits (D128).
  * The check `truth` tests the declared truth of a formula profile (D86). The check `cover` tests the covers of the
  * domains of the machine from samples (D94).
  *
+ * The name can also select a walker or the code of a `deref` (D137). The checks of a walker are `result`, `local`,
+ * `ladder`, `hops`, `typed` and `C4`. The checks of the code of a `deref` are `result`, `local` and `has`. The evaluators
+ * `formula.op` and `formula.ext` also examine each operation and each extension that the tables of their profile list.
+ * The checks `typed` and `result` test the functions of the profile directly.
+ *
  * @param machine - The machine with the code and the world of the kinds.
- * @param name - The name of the evaluator or of the runner. A runner wins over an evaluator of the same name.
+ * @param name - The name of the code. A runner wins over an evaluator of the same name, and each of them wins over a
+ *   walker or a `deref` without the option `verb`.
  * @param options - The verb, the types and the values of the probe documents, and the results of the probe parts. Also
  *   the definitions, the capabilities, the names, the seed, the mock and the rule of equality.
  * @returns The first finding of each obligation that the code breaks, in the order of the obligations.
@@ -4247,6 +4434,105 @@ interface Durable {
  * @returns The cache.
  */
 export declare function durable(machine: Machine, options?: DurableOptions): Durable;
+/** 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> {
+  /** The node that the read reaches. It is `undefined` when the read can reach each node (GRAPH.UNKNOWN). */
+  readonly to: Id | undefined;
+  /** `true` when only a lazy part reaches the read. An evaluation can then give a value without it (FACTS.LAZY). */
+  readonly lazy: boolean;
+}
+/** One node of a graph, with its edges. `NodeInfo` of a schedule is such a node. */
+interface GraphNode<Id> {
+  /** The edges to the nodes that the node reads. */
+  readonly edges: readonly GraphEdge<Id>[];
+  /** The side of the node. A node on the run side is a sink: no edge reaches it (SCHED.SIDE). The default is `derive`. */
+  readonly side?: Side;
+}
+/**
+ * A graph of nodes, by name. The order of the map is the order of the nodes in each answer. The function `graph` of
+ * a schedule gives such a graph. An edge to a name that is not in the map, or to a sink, is not an edge of the
+ * analysis.
+ */
+type NodeGraph<Id> = ReadonlyMap<Id, GraphNode<Id>>;
+/** The options of an analysis. */
+interface GraphOptions {
+  /**
+   * `true`: the analysis keeps only the eager edges with a target node. Such a read occurs in each evaluation in
+   * which each document around it gives a value (FACTS.LAZY). The default keeps each edge.
+   */
+  readonly eager?: boolean;
+}
+/** One static cycle of a graph (GRAPH.CYCLE). */
+interface GraphCycle<Id> {
+  /** The nodes of the cycle, in the order of the graph. */
+  readonly nodes: readonly Id[];
+  /**
+   * `true` when the eager edges with a target close the cycle. `false` when the cycle needs a lazy edge or an edge
+   * without a target. The value of each node still comes from the demand (D31).
+   */
+  readonly certain: boolean;
+}
+/**
+ * This function gives the strongly connected components of a graph of nodes (GRAPH.SCC), with the algorithm of
+ * Tarjan. It keeps its own stack, thus a chain of 100000 nodes does not overflow the stack of the host.
+ *
+ * - Each component comes after each component that it reads: the deepest component comes first.
+ * - A node that is on no cycle is a component of one node.
+ * - The nodes of a component are in the order of the graph.
+ *
+ * @param graph - The nodes, each with its edges.
+ * @param options - The option `eager` keeps only the eager edges with a target node.
+ * @returns The components, deepest first.
+ */
+export declare function components<Id>(graph: NodeGraph<Id>, options?: GraphOptions): readonly (readonly Id[])[];
+/**
+ * This function gives the height of each node: the order of a push schedule (GRAPH.ORDER). A schedule that evaluates
+ * the nodes from the lowest height up evaluates each node after each node that it reads, except on a cycle.
+ *
+ * - A node that reads no node outside its component has the height 0.
+ * - Each other node is one higher than the highest node that it reads outside its component.
+ * - The nodes of one component have one height.
+ * - An edge without a target reads each node that is not a sink (GRAPH.UNKNOWN).
+ *
+ * @param graph - The nodes, each with its edges.
+ * @param options - The option `eager` keeps only the eager edges with a target node.
+ * @returns The height of each node, in the order of the graph.
+ */
+export declare function heights<Id>(graph: NodeGraph<Id>, options?: GraphOptions): ReadonlyMap<Id, number>;
+/**
+ * This function puts the nodes in layers by their heights, in linear time (GRAPH.LAYERS). The first layer has the
+ * height 0. Two nodes of one layer read each other only inside one component. Thus a push schedule can evaluate the
+ * components of one layer at the same time.
+ *
+ * @param graph - The nodes, each with its edges.
+ * @param options - The option `eager` keeps only the eager edges with a target node.
+ * @returns The layers, from the height 0 up. Each layer keeps the order of the graph.
+ */
+export declare function nodeLayers<Id>(graph: NodeGraph<Id>, options?: GraphOptions): readonly (readonly Id[])[];
+/**
+ * This function gives the nodes that a set of observed nodes needs (GRAPH.NECESSARY). These are the observed nodes,
+ * and each node with a path of edges from them. A push schedule evaluates only these nodes. An observed name that is
+ * not a node of the graph adds nothing.
+ *
+ * @param graph - The nodes, each with its edges.
+ * @param observed - The nodes that the host shows or reads.
+ * @param options - The option `eager` keeps only the eager edges with a target node.
+ * @returns The necessary nodes, in the order of the graph.
+ */
+export declare function necessary<Id>(graph: NodeGraph<Id>, observed: Iterable<Id>, options?: GraphOptions): ReadonlySet<Id>;
+/**
+ * This function gives the static cycles of a graph (GRAPH.CYCLE): each component with two or more nodes, and each
+ * node with an edge to itself. A cycle of the eager edges with a target is certain, and `check` or a host can report
+ * it before a run. Another cycle is possible: an evaluation can skip a lazy read.
+ *
+ * - A component of all the edges that is also a component of the eager edges is one certain cycle.
+ * - Each other component of all the edges is one possible cycle, and each certain cycle in it comes after it.
+ * - A read can still fail before it occurs. Thus the demand of D31, not a static cycle, gives the value of each node.
+ *
+ * @param graph - The nodes, each with its edges.
+ * @returns The cycles, deepest first.
+ */
+export declare function cycles<Id>(graph: NodeGraph<Id>): readonly GraphCycle<Id>[];
 /** One edge of a graph of nodes: a static read of a node from the document of another node (SCHED.EDGES). */
 interface NodeEdge {
   /**
@@ -4278,6 +4564,17 @@ interface NodeInfo {
 interface ScheduleOptions extends DurableOptions {
   /** The context of the host: the names, `self`, `event` and the capabilities. The schedule sets the root `world` to the nodes. */
   readonly context?: Context;
+  /**
+   * This function gives a node its own `self` (SCHED.NODE-CONTEXT, D135). Thus one document at each cell of a grid
+   * shares one plan, and each cell has its own value and its own reads. In one data epoch, the function gives the same
+   * data for a node. New data comes with `changeData`, and each node then verifies its reads with its new `self`.
+   * Without the function, each node gets the context of the host.
+   *
+   * @param id - The name of the node.
+   * @param host - The context of the host, without the nodes at the root `world`.
+   * @returns The `self` of the node, or `undefined` for the `self` of the host.
+   */
+  readonly selfOf?: (id: string, host: Context) => Thing;
 }
 /** The work of a schedule since its start: the work of its `durable` cache, and the demands ahead of a node. */
 interface ScheduleCounts extends DurableCounts {
@@ -4305,7 +4602,7 @@ interface Schedule {
   readonly epochs: Epochs;
   /** The work of the schedule since its start: the compilations, the evaluations, the verifications, the reuses and the demands ahead. */
   readonly counts: ScheduleCounts;
-  /** The context of each node in the current data epoch: the context of the host, with the nodes at the root `world`. */
+  /** The context of the current data epoch: the context of the host, with the nodes at the root `world`. The option `selfOf` changes only the `self` of a node. */
   readonly context: Context;
   /**
    * This function gives each node with its facts, its side and its edges (SCHED.GRAPH). The map stays the same object
@@ -4320,7 +4617,7 @@ interface Schedule {
    *
    * - First, the schedule demands each node that the eager edges reach, deepest first (SCHED.LONG-CHAIN).
    * - After a change, a pure node verifies its reads, and it keeps its result when each read is the same (SCHED.STALE).
-   * - Each node of a cycle gives `#CYCLE!`, in each order of demands (SCHED.CYCLE).
+   * - Each node of a cycle gives `#CYCLE!`, in each order of demands (SCHED.CYCLE), at each length (SCHED.DEEP-CYCLE).
    * - A node on the run side gives `#REF!`, because the schedule does not evaluate it (SCHED.SIDE).
    *
    * @param id - The name of the node.
@@ -4344,7 +4641,8 @@ interface Schedule {
   remove(id: string): boolean;
   /**
    * This function tells the schedule that the data of the host changed (DURABLE.EPOCHS). The values of a context do
-   * not change in place, thus new data comes in a new context, or through a host thing.
+   * not change in place, thus new data comes in a new context, or through a host thing. A new `self` of a node is a
+   * change of data too (SCHED.NODE-STALE).
    *
    * @param context - The new context of the host, or `undefined` to keep the context.
    */
@@ -4357,7 +4655,8 @@ interface Schedule {
   changeMachine(machine: Machine): void;
   /**
    * This function starts a run of the document of a node, and the host does each effect (SCHED.RUN). Only the host
-   * starts a run, for example at an event. A change of data does not start or repeat a run (L3).
+   * starts a run, for example at an event. A change of data does not start or repeat a run (L3). The run gets the
+   * `self` of its node (SCHED.NODE-CONTEXT).
    *
    * @param id - The name of the node.
    * @param options - The event, the host code that does the effects, and a signal to stop the run.
@@ -4377,6 +4676,32 @@ interface Schedule {
  * @returns The edges, in the order of the reads.
  */
 export declare function edgesOf(facts: DocFacts): readonly NodeEdge[];
+/**
+ * One certain cycle of a schedule, in the form of an issue of `check` (SCHED.CYCLE-ISSUES). The first node of `nodes`
+ * gives the place and the reason. The place is the key of that node under the root `world`, and the reason has the
+ * text of `#CYCLE!` for that node.
+ */
+interface CycleIssue extends Issue {
+  readonly code: "#CYCLE!";
+  /** The nodes of the cycle, sorted by name as the record of the root `world` sorts them. */
+  readonly nodes: readonly string[];
+}
+/**
+ * This function gives the certain cycles of a schedule before a run (SCHED.CYCLE-ISSUES, D131). It reads only `graph()`,
+ * thus it evaluates no node. A host calls it when it needs the answer. A run does not call it.
+ *
+ * - Each certain cycle of `cycles` gives one issue. The issue has the place `[id]` of its first node.
+ * - A possible cycle gives no issue, because a run can skip its lazy read (SCHED.CYCLE-CERTAIN).
+ * - The order of the `set` calls does not change the answer (SCHED.CYCLE-ORDER).
+ * - No node of an issue gives a value. A read can fail before it reaches the cycle, and the node then gives that
+ *   error (SCHED.CYCLE-AGREES). Thus the demand of D33 still gives the result of each node.
+ *
+ * @param target - The schedule, or another object that gives a graph of nodes.
+ * @returns One issue for each certain cycle, sorted by the first node of each issue.
+ */
+export declare function checkCycles(target: {
+  graph(): NodeGraph<string>;
+}): readonly CycleIssue[];
 /**
  * This function makes the demand schedule of a graph of named nodes (S1, R4, D31). A host gives each node a name and
  * a document. The root `world` of each node reaches the other nodes by name. The context of the host gives the other
@@ -4392,12 +4717,16 @@ export declare function edgesOf(facts: DocFacts): readonly NodeEdge[];
  * - A demand of the host, or of a run, first demands each node that the eager edges reach, deepest first. Thus each
  *   read of such a node finds a value, and a chain of 100000 nodes does not overflow the stack (SCHED.LONG-CHAIN).
  *   Each such demand starts with no node in evaluation, thus the order of demands keeps the values of D31.
+ * - After an overflow of the stack, a walk with its own stack follows the same reads. It gives each node of a cycle
+ *   `#CYCLE!` at each length (SCHED.DEEP-CYCLE, D139). A demand without an overflow does no such work.
  * - A node on the run side is a sink. Only `run` evaluates it, and only the host uses `run`.
+ * - The option `selfOf` gives a node its own `self` (D135). The plan, the facts and the edges stay for each document
+ *   object, thus nodes with one document share them. The value, the reads and the place on a cycle stay for each node.
  *
  * The host keeps the promises of `durable`. The documents and the values of a context do not change in place.
  *
  * @param machine - The machine of the first structure epoch.
- * @param options - The options of `durable`, and the context of the host.
+ * @param options - The options of `durable`, the context of the host and the `self` of each node.
  * @returns The schedule.
  */
 export declare function schedule(machine: Machine, options?: ScheduleOptions): Schedule;
@@ -4520,12 +4849,14 @@ 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. */
 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;
 }
 /**
  * This function makes a new engine with no nodes. The harness makes one engine for each run. The function `schedule`
@@ -4570,6 +4901,12 @@ 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. */
@@ -4614,6 +4951,10 @@ 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. */
 type ScheduleAgreement = {
@@ -4645,7 +4986,8 @@ type ScheduleAgreement = {
 /**
  * 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`.
@@ -4660,105 +5002,6 @@ type ScheduleAgreement = {
  * @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;
-/** 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> {
-  /** The node that the read reaches. It is `undefined` when the read can reach each node (GRAPH.UNKNOWN). */
-  readonly to: Id | undefined;
-  /** `true` when only a lazy part reaches the read. An evaluation can then give a value without it (FACTS.LAZY). */
-  readonly lazy: boolean;
-}
-/** One node of a graph, with its edges. `NodeInfo` of a schedule is such a node. */
-interface GraphNode<Id> {
-  /** The edges to the nodes that the node reads. */
-  readonly edges: readonly GraphEdge<Id>[];
-  /** The side of the node. A node on the run side is a sink: no edge reaches it (SCHED.SIDE). The default is `derive`. */
-  readonly side?: Side;
-}
-/**
- * A graph of nodes, by name. The order of the map is the order of the nodes in each answer. The function `graph` of
- * a schedule gives such a graph. An edge to a name that is not in the map, or to a sink, is not an edge of the
- * analysis.
- */
-type NodeGraph<Id> = ReadonlyMap<Id, GraphNode<Id>>;
-/** The options of an analysis. */
-interface GraphOptions {
-  /**
-   * `true`: the analysis keeps only the eager edges with a target node. Such a read occurs in each evaluation in
-   * which each document around it gives a value (FACTS.LAZY). The default keeps each edge.
-   */
-  readonly eager?: boolean;
-}
-/** One static cycle of a graph (GRAPH.CYCLE). */
-interface GraphCycle<Id> {
-  /** The nodes of the cycle, in the order of the graph. */
-  readonly nodes: readonly Id[];
-  /**
-   * `true` when the eager edges with a target close the cycle. `false` when the cycle needs a lazy edge or an edge
-   * without a target. The value of each node still comes from the demand (D31).
-   */
-  readonly certain: boolean;
-}
-/**
- * This function gives the strongly connected components of a graph of nodes (GRAPH.SCC), with the algorithm of
- * Tarjan. It keeps its own stack, thus a chain of 100000 nodes does not overflow the stack of the host.
- *
- * - Each component comes after each component that it reads: the deepest component comes first.
- * - A node that is on no cycle is a component of one node.
- * - The nodes of a component are in the order of the graph.
- *
- * @param graph - The nodes, each with its edges.
- * @param options - The option `eager` keeps only the eager edges with a target node.
- * @returns The components, deepest first.
- */
-export declare function components<Id>(graph: NodeGraph<Id>, options?: GraphOptions): readonly (readonly Id[])[];
-/**
- * This function gives the height of each node: the order of a push schedule (GRAPH.ORDER). A schedule that evaluates
- * the nodes from the lowest height up evaluates each node after each node that it reads, except on a cycle.
- *
- * - A node that reads no node outside its component has the height 0.
- * - Each other node is one higher than the highest node that it reads outside its component.
- * - The nodes of one component have one height.
- * - An edge without a target reads each node that is not a sink (GRAPH.UNKNOWN).
- *
- * @param graph - The nodes, each with its edges.
- * @param options - The option `eager` keeps only the eager edges with a target node.
- * @returns The height of each node, in the order of the graph.
- */
-export declare function heights<Id>(graph: NodeGraph<Id>, options?: GraphOptions): ReadonlyMap<Id, number>;
-/**
- * This function puts the nodes in layers by their heights, in linear time (GRAPH.LAYERS). The first layer has the
- * height 0. Two nodes of one layer read each other only inside one component. Thus a push schedule can evaluate the
- * components of one layer at the same time.
- *
- * @param graph - The nodes, each with its edges.
- * @param options - The option `eager` keeps only the eager edges with a target node.
- * @returns The layers, from the height 0 up. Each layer keeps the order of the graph.
- */
-export declare function nodeLayers<Id>(graph: NodeGraph<Id>, options?: GraphOptions): readonly (readonly Id[])[];
-/**
- * This function gives the nodes that a set of observed nodes needs (GRAPH.NECESSARY). These are the observed nodes,
- * and each node with a path of edges from them. A push schedule evaluates only these nodes. An observed name that is
- * not a node of the graph adds nothing.
- *
- * @param graph - The nodes, each with its edges.
- * @param observed - The nodes that the host shows or reads.
- * @param options - The option `eager` keeps only the eager edges with a target node.
- * @returns The necessary nodes, in the order of the graph.
- */
-export declare function necessary<Id>(graph: NodeGraph<Id>, observed: Iterable<Id>, options?: GraphOptions): ReadonlySet<Id>;
-/**
- * This function gives the static cycles of a graph (GRAPH.CYCLE): each component with two or more nodes, and each
- * node with an edge to itself. A cycle of the eager edges with a target is certain, and `check` or a host can report
- * it before a run. Another cycle is possible: an evaluation can skip a lazy read.
- *
- * - A component of all the edges that is also a component of the eager edges is one certain cycle.
- * - Each other component of all the edges is one possible cycle, and each certain cycle in it comes after it.
- * - A read can still fail before it occurs. Thus the demand of D31, not a static cycle, gives the value of each node.
- *
- * @param graph - The nodes, each with its edges.
- * @returns The cycles, deepest first.
- */
-export declare function cycles<Id>(graph: NodeGraph<Id>): readonly GraphCycle<Id>[];
 /** One vertex of the graph of attribute instances: one attribute of one node of the decorated tree (D107). */
 interface AttributeVertex {
   /** The name of the vertex: the JSON text of the place of the node with the name of the attribute after it. */
@@ -5133,5 +5376,5 @@ interface SampleOptions {
  * @returns The type.
  */
 export declare function typeFromSamples(values: readonly unknown[], options?: SampleOptions): ValueType;
-export type { AgreeOptions, AgreeRunOptions, AgreeScheduleOptions, Agreement, Alias, AllOptions, Answer, AskOptions, AtArgs, AtEquation, AtRule, AttributeAnswer, AttributeCell, AttributeCycle, AttributeDeclaration, AttributeEdge, AttributeGraph, AttributeGraphOptions, AttributeRung, AttributeTrace, AttributeVertex, Cap, CapsRule, CheckOptions, CircularDeclaration, CircularRule, Classification, Closure, Code, CollectDeclaration, CollectRule, CompileInput, CompiledEvaluator, CompiledPart, CompiledRunner, ConformOptions, ConformProbe, Construct, Context, Part as ContextPart, Declared, 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, PrintOptions, Random, Read, ReadPrints, ReadsCheck, Recorder, RefUse, ReferenceOptions, ReferenceRunOptions, ReplayCausePartsJson, ReplayEntry, ReplayEntryJson, ReplayErrorJson, ReplayExceptionJson, ReplayLog, ReplayLogJson, ReplayOptions, ReplayPartJson, ReplayPartsJson, ReplayResultJson, 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, StepKey, StepLadder, StepNeed, StepReason, StepRefusal, StepSpec, StepWalk, Steps, StopSignal, Stored, SyntaxAssoc, SyntaxCalls, SyntaxEnvelopes, SyntaxFixity, SyntaxForm, SyntaxFormArgs, SyntaxHeader, SyntaxIssue, SyntaxLiterals, SyntaxOperator, SyntaxProfile, SyntaxRefPattern, SyntaxRefs, Thing, Tier, TierInput, TierResult, TraceNode, TreeContract, TreeOptions, TypeInput, TypeIssue, TypeProblem, TypeReading, TypeRef, TypeRule, Typed, Typing, Use, ValueType, VerbEffects, VerifyOptions, WalkInput, WalkOptions, WalkProblem, WalkResult, WalkTypeInput, Walker, World, WorldEntry, WorldIssue, WorldOptions, WorldPart };
+export type { AgreeOptions, AgreeRunOptions, AgreeScheduleOptions, Agreement, Alias, AllOptions, Answer, AskOptions, AtArgs, AtEquation, AtRule, AttributeAnswer, AttributeCell, AttributeCycle, AttributeDeclaration, AttributeEdge, AttributeGraph, AttributeGraphOptions, AttributeRung, AttributeTrace, AttributeVertex, Cap, CapsRule, CheckOptions, CircularDeclaration, CircularRule, Classification, Closure, Code, CodecFinding, CodecLaw, CodecLawsOptions, CodecProbe, CollectDeclaration, CollectRule, CompileInput, CompiledEvaluator, CompiledPart, CompiledPath, CompiledRunner, ConformOptions, ConformProbe, Construct, Context, Part as ContextPart, CycleIssue, Declared, 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, PrintOptions, Random, Read, ReadPrints, ReadsCheck, Recorder, RefUse, ReferenceOptions, ReferenceRunOptions, ReplayCausePartsJson, ReplayEntry, ReplayEntryJson, ReplayErrorJson, ReplayExceptionJson, ReplayLog, ReplayLogJson, ReplayOptions, ReplayPartJson, ReplayPartsJson, ReplayResultJson, 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, StepKey, StepLadder, StepNeed, StepReason, StepRefusal, StepSpec, StepWalk, Steps, StopSignal, Stored, SyntaxAssoc, SyntaxCalls, SyntaxConstructs, SyntaxEnvelopes, SyntaxFixity, SyntaxForm, SyntaxFormArgs, SyntaxHeader, SyntaxIssue, SyntaxLiterals, SyntaxOperator, SyntaxProfile, SyntaxRefPattern, SyntaxRefs, Thing, Tier, TierInput, TierResult, TraceNode, TreeContract, TreeOptions, TypeInput, TypeIssue, TypeProblem, TypeReading, TypeRef, TypeRule, Typed, Typing, Use, ValueType, VerbEffects, VerifyOptions, WalkInput, WalkOptions, WalkProblem, WalkResult, WalkTypeInput, Walker, World, WorldEntry, WorldIssue, WorldOptions, WorldPart };
 //# sourceMappingURL=index.d.ts.map