@mark1russell7/coeval 0.7.0 → 0.8.0

package/build/index.d.ts

@@ -24,8 +24,8 @@ type TypeRef = string | readonly Key[] | {
   readonly value: readonly Json[];
 };
 /**
- * A typed document: an envelope with a header and a value. The header names the type of the value. The value is
- * not changed by the envelope at any time. Thus any JSON value can have a type: a number, a list, a text or a record.
+ * A typed document: an envelope with a header and a value. The header names the type of the value. The envelope
+ * does not change the value at any time. Thus any JSON value can have a type: a number, a list, a text or a record.
  */
 type Envelope = {
   /** The type: a reference to a kind of the world. */
@@ -539,6 +539,32 @@ interface Domain {
    * a step with the key into a member reaches a member of the type. A key without a type gives `unknown`.
    */
   readonly steps?: Readonly<Record<string, ValueType>>;
+  /**
+   * The codec of the members: it writes a member as JSON and reads it again (D40). A document holds a member as the
+   * standard extension `ext.domain`. A domain without a codec has no such document.
+   */
+  readonly codec?: DomainCodec;
+}
+/**
+ * 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).
+ */
+interface DomainCodec {
+  /**
+   * This function writes a member of the domain as JSON.
+   *
+   * @param value - A member of the domain.
+   * @returns The JSON of the member.
+   */
+  readonly encode: (value: unknown) => Json;
+  /**
+   * This function reads the JSON of a member again. It throws for JSON that does not write a member.
+   *
+   * @param data - The JSON that `encode` gave.
+   * @returns The member.
+   */
+  readonly decode: (data: Json) => unknown;
 }
 /** A problem of a value type: the keys from the root of the term to the problem, and the reason. */
 interface TypeIssue {
@@ -789,6 +815,48 @@ interface KindFacts {
   readonly volatile?: boolean;
   readonly lazy?: readonly LazyRule[];
 }
+/**
+ * The declaration of one attribute of the nodes of a kind (D42). The last two rungs of the ladder of an attribute
+ * read it (TREE.LADDER). Each term is a document. A bare term gets the type `of` of the parts of the kind.
+ *
+ * - `copy`: `true` gives a node without an answer of the first three rungs the same attribute of its parent
+ *   (TREE.COPY).
+ * - `fold`: the value of a node without an answer of the first four rungs. The fold starts with the term `unit`.
+ *   Then the term `combine` adds the attribute of each node in the list `children`, one at a time (TREE.FOLD).
+ *   `combine` sees the names `acc` and `item`.
+ * - `default`: the term that gives the value when no rung before it answers and the declaration has no fold.
+ */
+interface AttributeDeclaration {
+  readonly copy?: boolean;
+  readonly fold?: {
+    readonly unit: Json;
+    readonly combine: Json;
+  };
+  readonly default?: Json;
+}
+/**
+ * The tree contract of a kind (D42): the equations of the attributes of its nodes. Each equation is a document that
+ * evaluates with the node as `self` and without capabilities. A bare equation gets the type `of` of the parts of the
+ * kind.
+ *
+ * - `equations`: the attributes of the node itself. An equation sees no names.
+ * - `down`: the attributes of each child of the node. `self` is this node. An equation sees the names `child`,
+ *   `index` and `prev` (TREE.DOWN).
+ * - `attributes`: the declarations of the attributes of the node, for the rungs `copy` and `default`.
+ */
+interface TreeContract {
+  readonly equations?: Readonly<Record<string, Json>>;
+  readonly down?: Readonly<Record<string, Json>>;
+  readonly attributes?: Readonly<Record<string, AttributeDeclaration>>;
+}
+/**
+ * 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.
+ *
+ * @param kind - The kind.
+ * @returns The type, or `undefined` when the shape declares none.
+ */
+export declare function equationType(kind: Kind): string | undefined;
 /**
  * A kind gives the name of an evaluator for each verb, and the contract of its value. The contract serves each verb.
  * For each verb, the kernel splits the parts and narrows their capabilities by it, and `check` reads its scope rules.
@@ -825,6 +893,11 @@ interface Kind extends KindFacts {
    * document of the kind, in the place of the type that the rule of the evaluator synthesizes.
    */
   readonly result?: ValueType;
+  /**
+   * The equations and the declarations of the attributes of a node of the decorated tree (D42). Only the evaluator
+   * `tree.node` reads them, and `check` checks each equation one time (TREE.LADDER).
+   */
+  readonly tree?: TreeContract;
   /** One sentence that tells what the kind is. */
   readonly summary?: string;
 }
@@ -1004,94 +1077,6 @@ export declare function kindNamed(world: World, name: TypeRef): Kind | undefined
  */
 export declare function ask(world: World, doc: Header, verb: string, options?: AskOptions): Answer;
 //#endregion
-//#region src/parts.d.ts
-/** One part of a value: its place in the value, the JSON of the part, and the type that its position declares. */
-interface PartSlot {
-  /** The keys from the value of the document to the part. */
-  readonly path: readonly Key[];
-  /** The path as one text, with a dot between the keys, for example `bind.x`. A part of a list has its index. */
-  readonly key: string;
-  readonly item: Json;
-  readonly of?: string;
-  /** `true` when the position of the part declares an address: a reference there gives what its path reaches. */
-  readonly address?: true;
-  /** The value type that the shape declares for the part (`expect`). Only a check of types reads it. */
-  readonly expect?: ValueType;
-}
-/** The value of a document, split into its parts, by the shape that its kind declares. */
-type Split = {
-  readonly ok: true;
-  /** The parts, in the order of the value. */
-  readonly parts: readonly PartSlot[];
-  /** The value without the parts: a field that holds a part is not in it, and a list of parts gives `null`. */
-  readonly data: Json;
-  /**
-   * This function gives the value with a handle in the place of each part.
-   *
-   * @param handles - One handle for each part, in the order of `parts`.
-   * @returns The value with the handles.
-   */
-  fill<P>(handles: readonly P[]): unknown;
-} | {
-  readonly ok: false;
-  readonly reason: string;
-  readonly at: readonly Key[];
-};
-/**
- * This function splits a value into its parts, by the shape that its kind declares. The evaluator, the view and
- * the static kit use the same split, thus each one sees the same parts.
- *
- * @param shape - The shape of the value. The default is data.
- * @param value - The value of the document.
- * @returns The parts and a way to fill their places, or the reason why the value does not have the shape.
- */
-export declare function splitParts(shape: Shape | undefined, value: Json): Split;
-/**
- * The kind and the parts of one document: what `partsOf` gives. `ok` is `false` only when the value is not a
- * document: it has no envelope, and its position declares no type. A value without the shape of its kind gives a
- * failed `split`.
- */
-type DocParts = {
-  readonly ok: true;
-  /** The document. A bare value gets the type that its position declares. */
-  readonly doc: Envelope;
-  /** `true` when the type came from the position and not from an envelope. */
-  readonly declared: boolean;
-  /** The kind, or `undefined` when the world has no kind for the type. Then the value is data. */
-  readonly kind: Kind | undefined;
-  /** The keys of the kind after each alias, or `undefined` without a kind. */
-  readonly typePath: readonly Key[] | undefined;
-  /**
-   * The split of the value by the shape of the kind. The reason of a failed split is the reason of the `#VALUE!`
-   * of an evaluation: it names the kind. Its `at` gives the keys from the value to the problem.
-   */
-  readonly split: Split;
-} | {
-  readonly ok: false;
-  readonly code: "#PART?";
-  readonly reason: string;
-};
-/**
- * This function reads one document by the contracts of the world. It finds the kind of the type. A bare value gets
- * the type that its position declares. Then the function splits the value by the shape of the kind. The plan, the
- * reference interpreter and the static kit read each document with this function. Thus they see the same parts.
- *
- * @param world - The world of the kinds.
- * @param value - The document, or a bare value.
- * @param declaredType - The type that the position of a bare value declares.
- * @returns The document, its kind and its parts, or the reason why the value is not a document.
- */
-export declare function partsOf(world: World, value: unknown, declaredType?: string): DocParts;
-/**
- * This function tells if the path of a part matches a pattern of a scope rule. The key `"*"` of a pattern matches
- * each key.
- *
- * @param path - The path of the part.
- * @param pattern - The pattern.
- * @returns `true` when the path matches.
- */
-export declare function pathMatches(path: readonly Key[], pattern: readonly Key[]): boolean;
-//#endregion
 //#region src/static.d.ts
 /** One document that a walk visits. */
 interface DocVisit {
@@ -1743,6 +1728,8 @@ interface EvalInput {
   readonly context: Context;
   /** The keys from the root document to this document. */
   readonly place: readonly Key[];
+  /** The machine of the evaluation, for example for its domains (D40). The kernel sets it. */
+  readonly machine?: Machine;
   /** `true` when the position of the document declares an address. */
   readonly address?: boolean;
   /**
@@ -1798,6 +1785,8 @@ interface RunInput {
   readonly parts: readonly RunPart[];
   readonly context: Context;
   readonly place: readonly Key[];
+  /** The machine of the evaluation, for example for its domains (D40). The kernel sets it. */
+  readonly machine?: Machine;
   resolve(path: readonly unknown[], options?: ResolveOptions): Resolution;
   /**
    * This function causes an effect. In a run, the host does the effect, and the steps wait when the host waits. In
@@ -2006,6 +1995,11 @@ interface PrepareOptions {
    * The default is `eval` (VERB.PREPARE).
    */
   readonly verb?: string;
+  /**
+   * `false`: no part of the plan folds. The default is `true`. Then a closed pure part of a plan without a trace
+   * evaluates one time, when the plan compiles. Its result is one frozen value for each evaluation (PLAN.FOLD).
+   */
+  readonly fold?: boolean;
 }
 /** A compiled document. It evaluates many times, and it does the work of the ladder one time. */
 interface Plan {
@@ -2062,8 +2056,8 @@ export declare function planner(machine: Machine, options?: PrepareOptions): (do
  * tells where its parts are. The evaluator gets each part sealed: it can evaluate the part, and it cannot read its
  * value.
  *
- * A failure gives an error value, and the function does not throw. An effect is recorded in its order, and the host
- * does not do it. A mock can answer each effect at once (RUN.MOCK).
+ * A failure gives an error value, and the function does not throw. The function records each effect in its order,
+ * and the host does not do it. A mock can answer each effect at once (RUN.MOCK).
  *
  * @param machine - The world and the code of the evaluators.
  * @param doc - The document, as JSON.
@@ -2275,6 +2269,94 @@ export declare function classify(shapes: readonly Shape$1[], value: Json): Class
  */
 export declare function tag(value: Json, kind: string): Envelope;
 //#endregion
+//#region src/parts.d.ts
+/** One part of a value: its place in the value, the JSON of the part, and the type that its position declares. */
+interface PartSlot {
+  /** The keys from the value of the document to the part. */
+  readonly path: readonly Key[];
+  /** The path as one text, with a dot between the keys, for example `bind.x`. A part of a list has its index. */
+  readonly key: string;
+  readonly item: Json;
+  readonly of?: string;
+  /** `true` when the position of the part declares an address: a reference there gives what its path reaches. */
+  readonly address?: true;
+  /** The value type that the shape declares for the part (`expect`). Only a check of types reads it. */
+  readonly expect?: ValueType;
+}
+/** The value of a document, split into its parts, by the shape that its kind declares. */
+type Split = {
+  readonly ok: true;
+  /** The parts, in the order of the value. */
+  readonly parts: readonly PartSlot[];
+  /** The value without the parts: a field that holds a part is not in it, and a list of parts gives `null`. */
+  readonly data: Json;
+  /**
+   * This function gives the value with a handle in the place of each part.
+   *
+   * @param handles - One handle for each part, in the order of `parts`.
+   * @returns The value with the handles.
+   */
+  fill<P>(handles: readonly P[]): unknown;
+} | {
+  readonly ok: false;
+  readonly reason: string;
+  readonly at: readonly Key[];
+};
+/**
+ * This function splits a value into its parts, by the shape that its kind declares. The evaluator, the view and
+ * the static kit use the same split, thus each one sees the same parts.
+ *
+ * @param shape - The shape of the value. The default is data.
+ * @param value - The value of the document.
+ * @returns The parts and a way to fill their places, or the reason why the value does not have the shape.
+ */
+export declare function splitParts(shape: Shape | undefined, value: Json): Split;
+/**
+ * The kind and the parts of one document: what `partsOf` gives. `ok` is `false` only when the value is not a
+ * document: it has no envelope, and its position declares no type. A value without the shape of its kind gives a
+ * failed `split`.
+ */
+type DocParts = {
+  readonly ok: true;
+  /** The document. A bare value gets the type that its position declares. */
+  readonly doc: Envelope;
+  /** `true` when the type came from the position and not from an envelope. */
+  readonly declared: boolean;
+  /** The kind, or `undefined` when the world has no kind for the type. Then the value is data. */
+  readonly kind: Kind | undefined;
+  /** The keys of the kind after each alias, or `undefined` without a kind. */
+  readonly typePath: readonly Key[] | undefined;
+  /**
+   * The split of the value by the shape of the kind. The reason of a failed split is the reason of the `#VALUE!`
+   * of an evaluation: it names the kind. Its `at` gives the keys from the value to the problem.
+   */
+  readonly split: Split;
+} | {
+  readonly ok: false;
+  readonly code: "#PART?";
+  readonly reason: string;
+};
+/**
+ * This function reads one document by the contracts of the world. It finds the kind of the type. A bare value gets
+ * the type that its position declares. Then the function splits the value by the shape of the kind. The plan, the
+ * reference interpreter and the static kit read each document with this function. Thus they see the same parts.
+ *
+ * @param world - The world of the kinds.
+ * @param value - The document, or a bare value.
+ * @param declaredType - The type that the position of a bare value declares.
+ * @returns The document, its kind and its parts, or the reason why the value is not a document.
+ */
+export declare function partsOf(world: World, value: unknown, declaredType?: string): DocParts;
+/**
+ * This function tells if the path of a part matches a pattern of a scope rule. The key `"*"` of a pattern matches
+ * each key.
+ *
+ * @param path - The path of the part.
+ * @param pattern - The pattern.
+ * @returns `true` when the path matches.
+ */
+export declare function pathMatches(path: readonly Key[], pattern: readonly Key[]): boolean;
+//#endregion
 //#region src/stdlib.d.ts
 /**
  * The world of the examples: small kinds for numbers, lists, conditions, names, sequences and effects.
@@ -2283,6 +2365,27 @@ export declare function tag(value: Json, kind: string): Envelope;
 export declare const STD_WORLD: World;
 /** 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";
+/** 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). */
+interface AttributeTrace {
+  readonly attribute: string;
+  /** The rungs that the demand visited, in their order. The last one answered, unless no rung answered. */
+  readonly rungs: readonly AttributeRung[];
+  /** The rung that answered. It is `undefined` when no rung answered. */
+  readonly by?: AttributeRung;
+}
+/**
+ * This function gives the record of the demand of an attribute of a node of the decorated tree (TREE.RUNGS). The
+ * record holds the rungs that the demand visited, and the rung that answered. An explorer draws the ladder with it.
+ *
+ * @param node - The thing of a node.
+ * @param attribute - The name of the attribute.
+ * @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;
 /** The options of a walker `nearest`. */
 interface NearestOptions {
   /**
@@ -2565,14 +2668,18 @@ type OpFn = (...args: never[]) => unknown;
  * example a default for an error.
  */
 type LazyOp = (args: readonly (() => Result)[]) => Result;
-/** The code of an extension: it gives the value of the data of an extension document, in the context of the document. */
-type ExtFn = (data: Json, context: Context) => Result;
+/**
+ * The code of an extension: it gives the value of the data of an extension document, in the context of the document.
+ * It also gets the domains of the machine, for the codecs of `ext.domain` (D40).
+ */
+type ExtFn = (data: Json, context: Context, domains?: Readonly<Record<string, Domain>>) => Result;
 /**
  * The rules of one formula language: its operations, and the rules that differ between languages.
  *
  * - `ops`: the operations of the namespace `ops`, by their name (the keys after `ops`, with dots between them).
  * - `lazy`: the operations that evaluate their arguments themselves.
- * - `ext`: the extensions of the namespace `ext`, by their name. The kit has `ext.undefined` and `ext.number`.
+ * - `ext`: the extensions of the namespace `ext`, by their name. The kit has `ext.undefined`, `ext.number` and
+ *   `ext.domain`.
  * - `truthy`: the truth of a value for `if`, `and` and `or`. `undefined` is an error `#VALUE!`. The default
  *   accepts only `true` and `false`.
  * - `otherwise`: the value of an `if` without `else`. The default is `null`. A profile with this key gives its value,
@@ -2639,7 +2746,10 @@ type Closure = ((...args: readonly unknown[]) => unknown) & {
  * @returns `true` for a closure.
  */
 export declare function isClosure(value: unknown): value is Closure;
-/** The standard extensions: the values that JSON cannot write. */
+/**
+ * The standard extensions: the values that JSON cannot write. `ext.domain` reads a member of a domain through the
+ * codec of the domain (EXT.DOMAIN, D40).
+ */
 export declare const STD_EXT: Readonly<Record<string, ExtFn>>;
 /** The truth of a value in the rules of JavaScript: `0`, `""`, `null`, `undefined` and `NaN` are false. */
 export declare function jsTruthy(value: unknown): boolean;
@@ -2701,6 +2811,189 @@ export declare function formulaFacts(profile?: FormulaProfile): (path: readonly
  */
 export declare function formulaMachine(profile?: FormulaProfile, more?: MachinePart): Machine;
 //#endregion
+//#region src/codec.d.ts
+/** The domains of a machine, by their names. */
+type Domains = Readonly<Record<string, Domain>> | undefined;
+/**
+ * This function reads the value of an extension `ext.domain` (EXT.DOMAIN). The value is a record with only the text
+ * `domain` and the JSON `data`. The codec of the named domain reads the data, and the result must be a member of the
+ * domain.
+ *
+ * @param data - The value of the extension document.
+ * @param domains - The domains of the machine.
+ * @returns The member, `#NAME?` for a domain without a codec, or `#VALUE!` for data that the codec cannot read.
+ */
+export declare function decodeDomain(data: Json, domains: Domains): Result;
+/**
+ * This function writes a host value as a term document of the formula kit (EXT.ENCODE, D40). Thus the same value has
+ * the same document in each language (D12).
+ *
+ * - A value that JSON writes exactly stays as it is. A literal with the shape of an envelope goes into `lit`.
+ * - `NaN`, an infinity and `-0` become `ext.number`, and `undefined` becomes `ext.undefined`.
+ * - A member of a domain with a codec becomes `ext.domain`. The domains go in the order of their names.
+ * - A list or a plain record with such a value becomes the construct `list` or `record`.
+ *
+ * @param machine - The machine, or only its domains.
+ * @param value - The host value.
+ * @returns The document. `decodeValue` gives the value again (EXT.ROUNDTRIP).
+ * @throws {TypeError} The value has a cycle, or it is not JSON and no domain with a codec holds it.
+ */
+export declare function encodeValue(machine: Pick<Machine, "domains">, value: unknown): Json;
+/**
+ * This function reads a document of `encodeValue` again: it evaluates the document as a term, in an empty context.
+ * A bare root value is a literal.
+ *
+ * @param machine - A machine of the formula kit, with the domains of the document.
+ * @param doc - The document.
+ * @returns The value, or the error of the evaluation.
+ */
+export declare function decodeValue(machine: Machine, doc: unknown): Result;
+//#endregion
+//#region src/syntax.d.ts
+/** The place of an operator: before its term, between two terms, or after its term. */
+type SyntaxFixity = "prefix" | "infix" | "postfix";
+/**
+ * The grouping of a chain of one infix operator. `left` reads `a - b - c` as `(a - b) - c`, and `right` reads
+ * `a ^ b ^ c` as `a ^ (b ^ c)`. `none` refuses a chain. `flat` reads a chain as one document with each term.
+ */
+type SyntaxAssoc = "left" | "right" | "none" | "flat";
+/** One operator of a syntax profile. */
+interface SyntaxOperator {
+  /** The text of the operator, for example `+`, `<>` or `and`. A word operator is a plain name. */
+  readonly symbol: string;
+  /** The place of the operator. */
+  readonly fixity: SyntaxFixity;
+  /** The precedence. A larger number binds more tightly. */
+  readonly prec: number;
+  /** The grouping of a chain of an infix operator. The default is `left`. */
+  readonly assoc?: SyntaxAssoc;
+  /** The type of the document that the operator makes, with dots between the keys, for example `ops.add` or `and`. */
+  readonly kind: string;
+}
+/** The literal rules of a syntax profile. */
+interface SyntaxLiterals {
+  /** `false` removes the decimal numbers. The default is `true`. */
+  readonly numbers?: boolean;
+  /** `true` puts a minus sign right before a digit into the number, where a term starts. The default is `true`. */
+  readonly signed?: boolean;
+  /** The texts: the quote and the escape of a quote. `false` removes the texts. The default is `"` with backslashes. */
+  readonly strings?: false | {
+    readonly quote?: "\"" | "'";
+    readonly escape?: "backslash" | "double";
+  };
+  /** The words that are literals, with their values. The default is `true`, `false` and `null`. */
+  readonly words?: Readonly<Record<string, unknown>>;
+}
+/** A reference syntax that a pattern gives, for example the address `A1` of a cell. */
+interface SyntaxRefPattern {
+  /** The pattern of the text of a reference. The parser tries it before a name. */
+  readonly pattern: RegExp;
+  /** This function gives the path of the reference from its text. */
+  readonly read: (text: string) => readonly Key[];
+  /** This function gives the text of a path, or `undefined` when the pattern does not write the path. */
+  readonly write: (path: readonly unknown[]) => string | undefined;
+}
+/** The reference syntax of a syntax profile. */
+interface SyntaxRefs {
+  /** The root of a bare name. The default is `names`. Thus `x` is the path `["names", "x"]`. */
+  readonly bare?: string;
+  /** The roots that the text names first, for example `self.price`. The default is `self`, `world`, `event` and `caps`. */
+  readonly roots?: readonly string[];
+  /** `false` removes the field steps `a.b`. The default is `true`. */
+  readonly fields?: boolean;
+  /** The patterns of other references. */
+  readonly patterns?: readonly SyntaxRefPattern[];
+}
+/** A call form: a name with arguments in parentheses that makes a construct, for example `if(test, then, else)`. */
+interface SyntaxForm {
+  /** The name in the text. */
+  readonly name: string;
+  /** The type of the document, with dots between the keys. */
+  readonly kind: string;
+  /** The fields of the value, in the order of the arguments. Without them, the value is the list of the arguments. */
+  readonly fields?: readonly string[];
+  /** The smallest number of arguments. The default is the number of the fields, or `0`. */
+  readonly min?: number;
+}
+/** The call syntax of a syntax profile. */
+interface SyntaxCalls {
+  /** The operations that a call `name(args)` can name. `true` permits each name. The default is `true`. */
+  readonly ops?: boolean | readonly string[];
+  /** The call forms of constructs. A form wins over an operation with the same name. */
+  readonly forms?: readonly SyntaxForm[];
+  /** The text between two arguments. The default is `,`. */
+  readonly separator?: 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
+ * and a language read the same rules.
+ */
+interface SyntaxProfile {
+  /** The operators. */
+  readonly operators?: readonly SyntaxOperator[];
+  /** The literal rules. */
+  readonly literals?: SyntaxLiterals;
+  /** The reference syntax. */
+  readonly refs?: SyntaxRefs;
+  /** The call syntax. */
+  readonly calls?: SyntaxCalls;
+  /** The deepest nesting that `parse` accepts. The default is `256`. */
+  readonly maxDepth?: number;
+}
+/** A problem of a text: its character offset, its length and a message. */
+interface SyntaxIssue {
+  /** The 0-based character offset of the problem. */
+  readonly offset: number;
+  /** The number of characters of the problem. `0` marks a place between two characters. */
+  readonly length: number;
+  /** The message. */
+  readonly message: string;
+}
+/** The result of `parse`: a document, or the problems of the text. */
+type ParseResult = {
+  readonly ok: true;
+  readonly doc: Json;
+} | {
+  readonly ok: false;
+  readonly issues: readonly SyntaxIssue[];
+};
+/**
+ * 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.
+ */
+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).
+ *
+ * @param profile - The syntax profile.
+ * @param text - The text.
+ * @returns The document, or the issues of the text.
+ * @throws {TypeError} The profile is not valid, for example an operator has two entries of the same place.
+ */
+export declare function parse(profile: SyntaxProfile, text: string): ParseResult;
+/**
+ * This function writes a document as text with the rules of a profile (SYNTAX.PRINT). It writes the fewest
+ * parentheses that keep the tree. `parse` reads the text back to the same document (SYNTAX.ROUNDTRIP).
+ *
+ * @param profile - The syntax profile.
+ * @param doc - The document.
+ * @returns The text, or `#VALUE!` at the place of a document that the profile cannot write.
+ * @throws {TypeError} The profile is not valid.
+ */
+export declare function print(profile: SyntaxProfile, doc: unknown): Result<string>;
+/**
+ * This function makes the part of a merge that adds the verb `format` to a machine (D23, D41). Its default writes
+ * each document with the printer of the profile. A part gives its own text through the ladder, thus an own entry or
+ * a kind entry of `format` still wins.
+ *
+ * @param profile - The syntax profile.
+ * @returns The part for `mergeMachines`.
+ */
+export declare function syntaxFormat(profile: SyntaxProfile): MachinePart;
+//#endregion
 //#region src/reference.d.ts
 /**
  * The definitional code of the reference, by evaluator name. The reference cannot read compiled code, thus each
@@ -2763,9 +3056,11 @@ export declare function formulaDefinitions(profile?: FormulaProfile): Definition
  * - `reference`: the reference interpreter, which compiles nothing.
  * - `traced`: the traced evaluation, `evaluate`.
  * - `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.
  * - `other`: the second tier of a language, from the option `other`.
  */
-type Tier = "reference" | "traced" | "again" | "other";
+type Tier = "reference" | "traced" | "again" | "folds" | "other";
 /** What a second tier gives: its result, and its effects when it records them. */
 interface TierResult {
   readonly result: Result;
@@ -2790,7 +3085,10 @@ interface AgreeOptions {
   readonly verb?: string;
   /** 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 and a second evaluation. */
+  /**
+   * 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.
+   */
   readonly tiers?: readonly Exclude<Tier, "other">[];
   /**
    * This function gives the result of the second tier of a language, for example a compiler to loops.
@@ -2819,7 +3117,8 @@ interface AgreeOptions {
   /**
    * This function gives what the host saw since its last call, for example the calls of an operation. `agree` uses
    * it before the plan and after each tier, and compares the results. Thus a tier that evaluates a part that the plan
-   * does not evaluate fails.
+   * does not evaluate fails. A fold moves the calls of a part to the compilation, thus with this option the plan has
+   * no folds. The tier `folds` then has folds, and `agree` does not compare its calls.
    *
    * @returns What the host saw.
    */
@@ -3611,5 +3910,5 @@ interface SampleOptions {
  */
 export declare function typeFromSamples(values: readonly unknown[], options?: SampleOptions): ValueType;
 //#endregion
-export type { AgreeOptions, Agreement, Alias, AllOptions, Answer, AskOptions, Cap, CapsRule, CheckOptions, Classification, Closure, Code, CompileInput, CompiledEvaluator, CompiledPart, CompiledRunner, ConformOptions, ConformProbe, Construct, Context, Part as ContextPart, Definitions, DerefCode, DocFacts, DocParts, DocVisit, Domain, 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, Part$1 as Part, PartInfo, Shape as PartShape, PartSlot, PartType, PartsSpec, Perform, Plan, 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, Thing, Tier, TierInput, TierResult, TraceNode, TypeInput, TypeIssue, TypeProblem, TypeReading, TypeRef, TypeRule, Typed, Typing, Use, ValueType, VerifyOptions, WalkInput, WalkOptions, WalkProblem, WalkResult, Walker, World, WorldEntry, WorldPart };
+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, 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, VerifyOptions, WalkInput, WalkOptions, WalkProblem, WalkResult, Walker, World, WorldEntry, WorldPart };
 //# sourceMappingURL=index.d.ts.map