@mark1russell7/coeval 0.0.0-stage → 0.2.0

package/build/index.d.ts

@@ -0,0 +1,1600 @@
+//#region src/doc.d.ts
+/** A JSON value. A document is JSON. */
+type Json = null | boolean | number | string | readonly Json[] | {
+  readonly [key: string]: Json;
+};
+/** A JSON record. */
+type JsonRecord = {
+  readonly [key: string]: Json;
+};
+/** One step of a path that is a plain key: a name, or an index of a list. */
+type Key = string | number;
+/**
+ * The type of a document is a reference into the world (the registry of kinds).
+ *
+ * - A text is a base reference with one key: `"add"`.
+ * - A list of keys is a base reference with a path: `["git", "push"]`.
+ * - A document of type `ref` is the same reference, expanded. Its path starts at the root `world`.
+ *
+ * The kernel resolves a base reference itself. The expanded form is necessary only to attach more to the
+ * reference. Thus the chain of types stops at a base reference.
+ */
+type TypeRef = string | readonly Key[] | {
+  readonly type: "ref";
+  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.
+ */
+type Envelope = {
+  /** The type: a reference to a kind of the world. */
+  readonly type: TypeRef;
+  /** The value. */
+  readonly value: Json;
+  /** The name of a binding. A sequence gives the result of this document to the later steps under this name. */
+  readonly name?: string;
+  /** The own entries: one evaluator name for each verb. An own entry changes only this document. */
+  readonly own?: Readonly<Record<string, string>>;
+};
+/** The keys that an envelope can have. */
+export declare const ENVELOPE_KEYS: readonly ["type", "value", "name", "own"];
+/**
+ * This function tells if a value is a plain record: an object with the prototype of a plain object, or with no
+ * prototype. A list, `null`, a date, a map and an instance of a class are not plain records.
+ *
+ * @param value - The value to examine.
+ * @returns `true` for a plain record.
+ */
+export declare function isRecord(value: unknown): value is JsonRecord;
+/**
+ * This function reads a field of a record. It reads only the own fields, thus `constructor` is not a field.
+ *
+ * @param record - The record.
+ * @param key - The name of the field.
+ * @returns The value of the field, or `undefined` when the record has no such field.
+ */
+export declare function field(record: JsonRecord, key: string): Json | undefined;
+/**
+ * This function tells if a value is a key of a path: a text, or a whole number from 0.
+ *
+ * @param value - The value to examine.
+ * @returns `true` for a key.
+ */
+export declare function isKey(value: unknown): value is Key;
+/**
+ * This function tells if a value is a reference to a type. The reference is a text, a list of keys, or a document
+ * of type `ref` whose path starts at the root `world`.
+ *
+ * @param value - The value to examine.
+ * @returns `true` for a reference to a type.
+ */
+export declare function isTypeRef(value: unknown): value is TypeRef;
+/**
+ * This function gives the path of a reference to a type, from the root of the world.
+ *
+ * @param type - The reference.
+ * @returns The keys from the root of the world, or `undefined` for a computed step that has no fixed key.
+ */
+export declare function typePath(type: TypeRef): readonly Key[] | undefined;
+/**
+ * This function gives the text of a type for a reader: its keys, joined with a dot.
+ *
+ * @param type - The reference to the type.
+ * @returns The text, for example `git.push`.
+ */
+export declare function typeName(type: TypeRef): string;
+/**
+ * This function tells if a value has the form of an envelope. That form is a record with a reference to a type
+ * and a `value`. It has no other keys than the keys of an envelope. A contract decides where an envelope is
+ * expected. This function only checks the form.
+ *
+ * @param value - The value to examine.
+ * @returns `true` when the value has the form of an envelope.
+ */
+export declare function isEnvelope(value: unknown): value is JsonRecord & Envelope;
+/** A stored document: an envelope, and the keys of its store beside it, for example `_id`. */
+interface Stored {
+  readonly envelope: Envelope;
+  /** The keys of the store, with their values. */
+  readonly header: Readonly<Record<string, Json>>;
+}
+/**
+ * This function reads a stored document: an envelope that also has the keys of a store, for example `{ _id, type,
+ * value }`. Only the keys in the list can be beside the keys of the envelope.
+ *
+ * @param value - The value to examine.
+ * @param header - The keys of the store that the document can have.
+ * @returns The envelope and the keys of the store, or `undefined` when the value has another form.
+ */
+export declare function stored(value: unknown, header: readonly string[]): Stored | undefined;
+/**
+ * This function makes an envelope.
+ *
+ * @param type - The reference to the kind.
+ * @param value - The value.
+ * @param header - The optional name and own entries.
+ * @returns The envelope.
+ */
+export declare function typed(type: TypeRef, value: Json, header?: {
+  readonly name?: string;
+  readonly own?: Record<string, string>;
+}): Envelope;
+/**
+ * This function makes a reference document: a path from a root of the context.
+ *
+ * @param path - The steps. The first step is a root: `self`, `names`, `world`, `event` or `caps`.
+ * @returns The document of type `ref`.
+ */
+export declare function ref(...path: readonly Json[]): Envelope;
+/**
+ * This function gives an envelope as a JSON record, for a store or for a view.
+ *
+ * @param doc - The envelope.
+ * @returns The same envelope as JSON.
+ */
+export declare function toJson(doc: Envelope): JsonRecord;
+/**
+ * This function reads an envelope from JSON. A value without the form of an envelope gives `undefined`.
+ *
+ * @param value - The JSON value.
+ * @returns The envelope, or `undefined`.
+ */
+export declare function fromJson(value: unknown): Envelope | undefined;
+/**
+ * This function tells if two JSON values are equal. Equal values have the same texts, numbers and truth values,
+ * the same items in the same order, and the same fields. The order of the fields does not matter. It does not use the stack for the
+ * depth, thus a deep document cannot overflow it.
+ *
+ * @param a - The first value.
+ * @param b - The second value.
+ * @returns `true` when the values are equal.
+ */
+export declare function docEquals(a: unknown, b: unknown): boolean;
+//#endregion
+//#region src/errors.d.ts
+/** The codes that the kernel gives. */
+type KernelCode = "#KIND?" | "#NOEVAL" | "#PART?" | "#NAME?" | "#REF!" | "#N/A" | "#CYCLE!" | "#STEP?" | "#VALUE!" | "#NUM!" | "#ARGS" | "#CAP!" | "#CALC!" | "#DEPTH!" | "#ABORT";
+/** The code of an error value. A language can add its own codes. Each code starts with `#`. */
+type ErrorCode = KernelCode | `#${string}`;
+/**
+ * An error value: a code and a reason. An evaluation gives an error value, and it does not throw.
+ *
+ * - `place`: the keys from the root document to the document that failed.
+ * - `cause`: the error of the host that caused this error, for example the exception of an effect.
+ */
+interface EvalError {
+  readonly code: ErrorCode;
+  readonly reason: string;
+  readonly place?: readonly Key[];
+  readonly cause?: unknown;
+}
+/** The result of an evaluation: a value, or an error value. A value can be any value of the host. */
+type Result<V = unknown> = {
+  readonly ok: true;
+  readonly value: V;
+} | {
+  readonly ok: false;
+  readonly error: EvalError;
+};
+/** A result with an error value. */
+type Failed = {
+  readonly ok: false;
+  readonly error: EvalError;
+};
+/**
+ * This function makes a result with a value.
+ *
+ * @param value - The value.
+ * @returns The result.
+ */
+export declare function ok<V>(value: V): Result<V>;
+/**
+ * This function makes a result with an error value.
+ *
+ * @param code - The code of the error.
+ * @param reason - One sentence that tells the cause.
+ * @param more - The place and the cause of the error, when they are known.
+ * @returns The result.
+ */
+export declare function fail(code: ErrorCode, reason: string, more?: {
+  readonly place?: readonly Key[];
+  readonly cause?: unknown;
+}): Failed;
+/**
+ * This function gives a failed result its place, when it has none. A result with a value, or an error with a
+ * place, stays the same object.
+ *
+ * @param result - The result.
+ * @param place - The keys from the root document to the document that failed.
+ * @returns The result with a place.
+ */
+export declare function placed<V>(result: Result<V>, place: readonly Key[]): Result<V>;
+/**
+ * An exception that carries an error value through code of the host. A closure of a formula throws it when the
+ * host calls the closure and the closure fails. The kernel catches it and gives its error value again.
+ */
+export declare class Failure extends Error {
+  readonly error: EvalError;
+  /**
+   * This constructor makes the exception.
+   *
+   * @param error - The error value that the exception carries.
+   */
+  constructor(error: EvalError);
+}
+/**
+ * This function tells if an exception is the overflow of the stack of the host.
+ *
+ * @param error - The exception.
+ * @returns `true` for a stack overflow.
+ */
+export declare function isStackOverflow(error: unknown): boolean;
+/**
+ * This function changes an exception into an error value. A `Failure` gives its error value. A stack overflow
+ * gives `#DEPTH!`. Each other exception gives `#CALC!`, with the exception as the cause.
+ *
+ * @param error - The exception.
+ * @param who - A short text that names the code that threw, for example `the evaluator math.add`.
+ * @returns The failed result.
+ */
+export declare function thrown(error: unknown, who: string): Failed;
+/**
+ * This function gives a short text for an exception or any value. It does not throw.
+ *
+ * @param value - The value.
+ * @returns The text.
+ */
+export declare function describe(value: unknown): string;
+//#endregion
+//#region src/world.d.ts
+/** The two sides of evaluation. `derive` is pure. `run` causes effects in order. */
+type Side = "derive" | "run";
+/**
+ * Where the parts of a value are: the shape of the value. A part is a typed document that the evaluator gets
+ * sealed. `of` is the type of a bare part: a part without an envelope gets this type from its position.
+ *
+ * - `none`: the value is data. It has no parts.
+ * - `term`: the value itself is one part.
+ * - `list`: the value is a list. Each item has the shape `item` (the default is a part).
+ * - `map`: the value is a record. Each field has the shape `item` (the default is a part).
+ * - `record`: the value is a record. Each named field has its shape. A list of names makes each named field a
+ *   part. The other fields have the shape `rest` (the default is data). `required` names the fields that must be.
+ * - `deep`: each envelope at any depth of the value is a part, and the rest is data.
+ */
+type Shape = {
+  readonly shape: "none";
+} | {
+  readonly shape: "term";
+  readonly of?: string;
+} | {
+  readonly shape: "list";
+  readonly of?: string;
+  readonly item?: Shape;
+} | {
+  readonly shape: "map";
+  readonly of?: string;
+  readonly item?: Shape;
+} | {
+  readonly shape: "record";
+  readonly fields: readonly string[] | Readonly<Record<string, Shape>>;
+  readonly of?: string;
+  readonly required?: readonly string[];
+  readonly rest?: Shape;
+} | {
+  readonly shape: "deep";
+  readonly of?: string;
+};
+/** The former name of `Shape`. */
+type PartsSpec = Shape;
+/**
+ * Where the names of a scope rule come from.
+ *
+ * - `fixed`: the names in the list.
+ * - `keysAt`: the keys of the record at this path of the value, for example the bindings of a `let`.
+ * - `listAt`: the texts of the list at this path of the value, for example the parameters of a `fn`.
+ * - `textAt`: the text at this path of the value, or `otherwise` when the value has no text there.
+ * - `headers`: the binding name (`name`) of each part that the rule covers.
+ */
+type NamesSource = {
+  readonly fixed: readonly string[];
+} | {
+  readonly keysAt: readonly Key[];
+} | {
+  readonly listAt: readonly Key[];
+} | {
+  readonly textAt: readonly Key[];
+  readonly otherwise?: string;
+} | {
+  readonly headers: true;
+};
+/**
+ * A scope rule of a kind: names that the kind binds, and the parts that see them. The static kit reads the rules,
+ * and the evaluator of the kind binds the same names when it evaluates the parts.
+ */
+interface ScopeRule {
+  readonly names: NamesSource;
+  /** The parts that see the names, as patterns of their paths in the value. The key `"*"` matches each key. */
+  readonly in: readonly (readonly Key[])[];
+  /** `true`: a part sees only the names of the parts before it, as in a sequence. */
+  readonly sequential?: boolean;
+}
+/** A kind gives the name of an evaluator for each verb, and the contract of its value. */
+interface Kind {
+  readonly verbs: Readonly<Record<string, string>>;
+  /** Where the parts of the value are. The default is `none`. */
+  readonly parts?: Shape;
+  /** The names that the kind binds for its parts. */
+  readonly scope?: readonly ScopeRule[];
+  /** The side of the kind. A kind of the run side causes effects. The default is `derive`. */
+  readonly side?: Side;
+  /**
+   * The effects that a document of this kind can cause. It is a list of the kinds of the effects. The text
+   * `"type"` means that the kind of the effect is the type of the document itself, as for a call.
+   */
+  readonly effects?: "type" | readonly string[];
+  /** One sentence that tells what the kind is. */
+  readonly summary?: string;
+}
+/** A namespace: a group of entries under one key of the world. `fallback` is the kind of each other key in it. */
+interface Namespace {
+  readonly kinds: Readonly<Record<string, WorldEntry>>;
+  readonly fallback?: Kind;
+}
+/** An alias: a reference to another entry of the world. The lookup follows it (collapse). */
+type Alias = {
+  readonly type: "ref";
+  readonly value: readonly Json[];
+};
+/** One entry of the world: a kind, a namespace, or an alias. */
+type WorldEntry = Kind | Namespace | Alias;
+/** A world holds the kinds and the defaults that answer the questions. */
+interface World {
+  readonly kinds: Readonly<Record<string, WorldEntry>>;
+  readonly defaults: Readonly<Record<string, string>>;
+}
+/** The result of a lookup of a type in the world. */
+type Lookup = {
+  readonly ok: true;
+  readonly kind: Kind;
+  readonly path: readonly Key[];
+  readonly aliases: number;
+} | {
+  readonly ok: false;
+  readonly reason: "unknown" | "cycle" | "not-a-kind" | "computed";
+  readonly path: readonly Key[];
+};
+/**
+ * This function tells if an entry of the world is a kind.
+ *
+ * @param entry - The entry.
+ * @returns `true` for a kind.
+ */
+export declare function isKind(entry: WorldEntry | undefined): entry is Kind;
+/**
+ * This function tells if an entry of the world is an alias.
+ *
+ * @param entry - The entry.
+ * @returns `true` for an alias.
+ */
+export declare function isAlias(entry: WorldEntry | undefined): entry is Alias;
+/**
+ * This function tells if an entry of the world is a namespace.
+ *
+ * @param entry - The entry.
+ * @returns `true` for a namespace.
+ */
+export declare function isNamespace(entry: WorldEntry | undefined): entry is Namespace;
+/**
+ * This function finds the kind that a type names. It walks the path from the root of the world, one key at a
+ * time. An alias on the way is followed until a kind answers (collapse). A cycle of aliases stops the lookup. In a
+ * namespace with a fallback, a key that the namespace does not have gets the fallback kind.
+ *
+ * @param world - The world.
+ * @param type - The reference to the type.
+ * @returns The kind and the path of the kind after each alias, or the reason of a failure.
+ */
+export declare function lookupKind(world: World, type: TypeRef): Lookup;
+/**
+ * This function gives the entries of a world as a JSON record, so that a reference can walk it. A kind is a
+ * record with its verbs, an alias is a reference document, and a namespace is a record of its entries.
+ *
+ * @param entries - The entries.
+ * @returns The JSON form.
+ */
+export declare function entriesAsJson(entries: Readonly<Record<string, WorldEntry>>): Json;
+/**
+ * This function makes the document of a kind, so that a view can draw it as each other document.
+ *
+ * @param name - The name of the kind.
+ * @param kind - The kind.
+ * @returns The document of type `kind`.
+ */
+export declare function kindDocument(name: string, kind: Kind): Envelope;
+/**
+ * This function tells if a JSON value is the record of a kind.
+ *
+ * @param value - The value.
+ * @returns `true` when the value has verbs.
+ */
+export declare function looksLikeKind(value: unknown): boolean;
+//#endregion
+//#region src/ladder.d.ts
+/** The rungs of the ladder, in the order that a question visits them. */
+export declare const RUNGS: readonly ["own", "kind", "default"];
+/** One rung of the ladder. */
+type Rung = (typeof RUNGS)[number];
+/** The place where the ladder found the type. */
+type KindSource = "document" | "container";
+/**
+ * The outcome of one rung.
+ *
+ * - `answers`: the rung gives an evaluator.
+ * - `no-entry`: the rung has nothing for this verb, thus the question goes to the next rung.
+ * - `skipped`: the rung does not apply, because no type is known.
+ * - `unknown-kind`: the type is not a kind of the world. The question stops.
+ */
+type Outcome = "answers" | "no-entry" | "skipped" | "unknown-kind";
+/** The record of one rung that a question visited. */
+interface Step {
+  readonly rung: Rung;
+  readonly outcome: Outcome;
+  /** The evaluator, when the outcome is `answers`. */
+  readonly evaluator?: string;
+  /** The text of the type, at the kind rung. */
+  readonly kind?: string;
+  /** The place of the type, at the kind rung. */
+  readonly source?: KindSource;
+}
+/** The answer to a question. It keeps the record of each rung that the question visited. */
+interface Answer {
+  readonly verb: string;
+  /** The evaluator that answers. A question that stops with an error has no evaluator. */
+  readonly evaluator?: string;
+  /** The rung that answered. */
+  readonly rung?: Rung;
+  /** The reason when no rung answers. */
+  readonly error?: "unknown-kind" | "no-answer";
+  readonly steps: readonly Step[];
+}
+/**
+ * The header that the ladder reads: the type and the own entries. An envelope is a header. A bare value has an
+ * empty header, and its position can declare its type.
+ */
+interface Header {
+  readonly type?: TypeRef;
+  readonly own?: Readonly<Record<string, string>>;
+}
+/** The options of a question. */
+interface AskOptions {
+  /** The type that the position of a bare value declares. The type of an envelope wins. */
+  readonly declaredType?: string;
+}
+/**
+ * This function finds the kind that a type names, and follows each alias. It gives `undefined` for an unknown
+ * type.
+ *
+ * @param world - The world.
+ * @param type - The reference to the type.
+ * @returns The kind, or `undefined`.
+ */
+export declare function kindOf(world: World, type: TypeRef): Kind | undefined;
+/**
+ * This function finds a kind by a text type. It is the same as `kindOf` for a one-key reference.
+ *
+ * @param world - The world.
+ * @param name - The text of the type.
+ * @returns The kind, or `undefined`.
+ */
+export declare function kindNamed(world: World, name: TypeRef): Kind | undefined;
+/**
+ * This function asks a document a question, and gives the evaluator that answers it.
+ *
+ * The question visits the rungs in order: the own entry of the envelope, then its kind, then the default of the
+ * world. The type comes from the envelope, or else from the type that the position declares. The type is a
+ * reference into the world. The ladder does not guess a type from the shape of a value.
+ *
+ * @param world - The kinds and the defaults.
+ * @param doc - The header of the document: an envelope, or `{}` for a bare value.
+ * @param verb - The verb of the question, for example `eval` or `view`.
+ * @param options - The type that the position declares.
+ * @returns The answer, with the record of each rung that the question visited.
+ */
+export declare function ask(world: World, doc: Header, verb: string, options?: AskOptions): Answer;
+//#endregion
+//#region src/deref.d.ts
+/**
+ * The brand of a host thing: an object of the host that answers the steps of a path itself. The brand is a
+ * global symbol, thus two copies of the kernel in one program know the things of each other.
+ */
+export declare const THING: unique symbol;
+/**
+ * A host thing: an object that answers the steps of a path itself, for example a node of a live tree. It is the
+ * own entry of the ladder for the verb `deref`.
+ */
+interface HostThing {
+  readonly [THING]: true;
+  /** A short text for a reader, for example `node card`. */
+  readonly label: string;
+  /**
+   * This function answers one step.
+   *
+   * @param key - The key of the step.
+   * @returns What the step reaches, or `undefined` when it reaches nothing.
+   */
+  deref(key: Key): Thing | undefined;
+  /**
+   * This function gives the thing as a value, when a reference ends on it.
+   *
+   * @returns The value.
+   */
+  toJson(): unknown;
+  /**
+   * This optional function answers all the steps of a path that are keys, in one call. A store uses it to read a
+   * path without one call for each step.
+   *
+   * @param keys - The keys.
+   * @returns What the keys reach, or `undefined` when they reach nothing.
+   */
+  resolve?(keys: readonly Key[]): {
+    readonly thing: Thing;
+  } | undefined;
+}
+/** Something that a path can reach: any value of the host, or a host thing. */
+type Thing = unknown;
+/**
+ * This function tells if a thing is a host thing.
+ *
+ * @param thing - The thing.
+ * @returns `true` for a host thing.
+ */
+export declare function isHostThing(thing: unknown): thing is HostThing;
+/** The roots of a context. Each path starts with one of them. */
+export declare const ROOTS: readonly ["self", "names", "world", "event", "caps"];
+/** One root of a context. */
+type Root = (typeof ROOTS)[number];
+/**
+ * A capability: the name of a kind of effect, or its keys. A capability permits its kind and each kind under it.
+ * Keys are necessary when a key has a dot in it.
+ */
+type Cap = string | readonly Key[];
+/**
+ * The context of a term: a record with five roots. A reference reaches outside its term only through them.
+ *
+ * - `self`: the node that the term is part of.
+ * - `names`: the values that the evaluators around the term bound.
+ * - `world`: the registry of kinds.
+ * - `event`: the event that started a run.
+ * - `caps`: the effects that the term can cause.
+ */
+interface Context {
+  readonly self: Thing;
+  readonly names: Readonly<Record<string, unknown>>;
+  readonly world: Thing;
+  readonly event: Thing;
+  readonly caps: readonly Cap[];
+}
+/** The code of a `deref` evaluator: it answers one step of a path on a document of its kind. */
+type DerefCode = (doc: Envelope, key: Key) => Thing | undefined;
+/** The result of a step document: what it reached, or the reason of a failure. */
+type WalkResult = {
+  readonly ok: true;
+  readonly thing: Thing;
+} | {
+  readonly ok: false;
+  readonly reason: string;
+};
+/** The input of a walker: the code of a step document, for example `nearest`. */
+interface WalkInput {
+  /** The value of the step document. */
+  readonly data: Json;
+  /** The thing that the path reached before this step. */
+  readonly here: Thing;
+  readonly context: Context;
+  /**
+   * This function answers one step on a thing, through the ladder.
+   *
+   * @param thing - The thing.
+   * @param key - The key.
+   * @returns What the step reaches, or `undefined`.
+   */
+  deref(thing: Thing, key: Key): Thing | undefined;
+}
+/** A walker: the code of the verb `step` of a kind of step documents. */
+type Walker = (input: WalkInput) => WalkResult;
+/**
+ * What a resolution needs: the world, and the code of the `deref` evaluators and of the walkers.
+ *
+ * - `plain`: `true` when the values are data. Then a step does not ask the kind of an envelope, and a reference
+ *   that a step reaches stays a value (no collapse).
+ * - `roots`: the roots that a path can start at. The default is each root.
+ */
+interface Navigator {
+  readonly world: World;
+  readonly derefs?: Readonly<Record<string, DerefCode>>;
+  readonly walkers?: Readonly<Record<string, Walker>>;
+  readonly plain?: boolean;
+  readonly roots?: readonly Root[];
+}
+/** The way that one hop of a path was answered. */
+type HopBy = "root" | "own" | "kind" | "default" | "step" | "collapse";
+/** One hop of a path: the step, what it reached, and who answered it. */
+interface Hop {
+  readonly step: Json;
+  readonly thing: Thing;
+  readonly by: HopBy;
+}
+/** The codes of a failed resolution. */
+type ResolveCode = "#REF!" | "#NAME?" | "#N/A" | "#CYCLE!" | "#STEP?";
+/** The result of a resolution: what the path reached, with each hop, or an error with the hops before it. */
+type Resolution = {
+  readonly ok: true;
+  readonly thing: Thing;
+  readonly hops: readonly Hop[];
+} | {
+  readonly ok: false;
+  readonly code: ResolveCode;
+  readonly reason: string;
+  readonly hops: readonly Hop[];
+};
+/** The options of a resolution. */
+interface ResolveOptions {
+  /** `false`: do not record the hops. The default is `true`. */
+  readonly hops?: boolean;
+}
+/**
+ * This function answers one step of a path on a thing, through the ladder of the verb `deref`. A host thing
+ * answers for itself (own). A document asks its own entry, then its kind. The default goes into the value: an own
+ * field of an object, or an item of a list.
+ *
+ * @param nav - The world and the code of the evaluators.
+ * @param thing - The thing that the path reached.
+ * @param key - The key of the step.
+ * @returns What the step reaches and the rung that answered, or `undefined` when it reaches nothing.
+ */
+export declare function derefStep(nav: Navigator, thing: Thing, key: Key): {
+  readonly thing: Thing;
+  readonly by: HopBy;
+} | undefined;
+/**
+ * This function tells if a thing is a reference document: an envelope of the type `ref` with a list for its path.
+ *
+ * @param thing - The thing.
+ * @returns `true` for a reference document.
+ */
+export declare function isRef(thing: unknown): thing is Envelope & {
+  readonly value: readonly Json[];
+};
+/**
+ * This function makes the thing of the root `world`: the entries of the world as JSON. An alias is a reference
+ * document in it, thus a walk through the world follows each alias (collapse). The thing of a world is made one
+ * time.
+ *
+ * @param world - The world.
+ * @returns The thing.
+ */
+export declare function worldThing(world: World): Json;
+/**
+ * This function makes a context. The world comes from the navigator when the call gives none.
+ *
+ * @param parts - The roots to set.
+ * @returns The context.
+ */
+export declare function context(parts?: Partial<Context>): Context;
+/**
+ * This function resolves a path from a context, and records each hop.
+ *
+ * The first step is a root of the context. Each later step is a key or a step document. A key goes up the ladder
+ * of the verb `deref` on the thing that the path reached. A step document is evaluated by the walker of its kind,
+ * with the thing that the path reached. After each hop, a reference document is followed until the path reaches
+ * something else (collapse), except in a plain navigation.
+ *
+ * The codes of a failure:
+ *
+ * - `#REF!`: the path has no root, or a root that is not open here.
+ * - `#NAME?`: the root `names` has no such name.
+ * - `#N/A`: a step reaches nothing.
+ * - `#STEP?`: a step is not a key and not a step document.
+ * - `#CYCLE!`: the references form a cycle.
+ *
+ * @param nav - The world and the code of the evaluators.
+ * @param ctx - The context.
+ * @param path - The steps.
+ * @param options - `hops: false` does not record the hops.
+ * @returns What the path reached and each hop, or an error.
+ */
+export declare function resolve(nav: Navigator, ctx: Context, path: readonly unknown[], options?: ResolveOptions): Resolution;
+/**
+ * This function gives the value of a thing: the value that a host thing gives, or else the thing itself.
+ *
+ * @param thing - The thing.
+ * @returns The value.
+ */
+export declare function valueOfThing(thing: Thing): unknown;
+//#endregion
+//#region src/classify.d.ts
+/** A shape proposes a kind for each document that has all of its fields. */
+interface Shape$1 {
+  readonly name: string;
+  readonly fields: readonly string[];
+  readonly kind: string;
+}
+/** The result of a classification. */
+interface Classification {
+  /** The kind of the one most specific shape. */
+  readonly kind?: string;
+  /** The names of the most specific shapes. */
+  readonly candidates: readonly string[];
+  /** `no-match`: no shape applies. `ambiguous`: two or more shapes match equally well. */
+  readonly error?: "no-match" | "ambiguous";
+}
+/**
+ * This function proposes a kind for a value without a type, from the fields that the value has.
+ * A shape applies when the value has each field of the shape. The most specific shapes are the ones that
+ * no other applicable shape contains. A host uses a classifier when data comes in, and then tags the data.
+ * The ladder does not call a classifier.
+ *
+ * @param shapes - The shapes to examine.
+ * @param value - The value without a type.
+ * @returns The proposed kind, or an error with the candidates.
+ */
+export declare function classify(shapes: readonly Shape$1[], value: Json): Classification;
+/**
+ * This function puts a value in an envelope with a type. The value does not change.
+ *
+ * @param value - The value.
+ * @param kind - The name of the kind.
+ * @returns The envelope.
+ */
+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;
+}
+/** 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;
+/**
+ * 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/evaluate.d.ts
+/**
+ * This function makes a context with names and capabilities. The other roots are empty, and an evaluation sets
+ * the world.
+ *
+ * @param names - The names and their values.
+ * @param caps - The effects that the term can cause.
+ * @param self - The node of the term, if it has one.
+ * @returns The context.
+ */
+export declare function makeContext(names?: Readonly<Record<string, unknown>>, caps?: readonly Cap[], self?: Thing): Context;
+/**
+ * This function gives the keys of a capability or of a kind of effect: a text is split at its dots.
+ *
+ * @param kind - The text or the keys.
+ * @returns The keys, as texts.
+ */
+export declare function capKeys(kind: Cap): readonly string[];
+/**
+ * This function tells if the capabilities permit an effect. A capability permits the kind of its name, and each kind
+ * under it: `store` permits `store.update`. The comparison is key by key, thus `fs.read` does not permit the
+ * kind with the keys `fs` and `read.json`.
+ *
+ * @param caps - The capabilities of the context.
+ * @param kind - The kind of the effect: a text with dots, or its keys.
+ * @returns `true` when one capability permits it.
+ */
+export declare function permits(caps: readonly Cap[], kind: Cap): boolean;
+/**
+ * This function narrows a context for a part: the part keeps only the capabilities that the context of its parent
+ * permits. Thus an evaluator cannot give a part more effects than it has.
+ *
+ * @param parent - The context of the parent.
+ * @param next - The context that the evaluator gives the part.
+ * @returns The context of the part.
+ */
+export declare function narrow(parent: Context, next: Context): Context;
+/**
+ * The steps of an evaluation that can wait. It yields a promise only when the host makes it wait. A runner takes the
+ * result of a part with `yield*`, thus a run goes on at once until an effect waits. A runner does not yield a
+ * promise itself: it uses `yield*` on the steps that the kernel gives.
+ */
+type Steps = Generator<Promise<unknown>, Result, unknown>;
+/** An effect that an evaluation caused, in the order of the effects. */
+interface Effect {
+  readonly index: number;
+  /** The kind of the effect, as a text with dots. */
+  readonly kind: string;
+  /** The keys of the kind of the effect. */
+  readonly path: readonly Key[];
+  readonly payload: unknown;
+  /** The ID of the trace node that caused the effect, or -1 without a trace. */
+  readonly node: number;
+  /** The number of events before the effect. The effect comes before the end of its node. */
+  readonly at: number;
+  /** The keys from the root document to the document that caused the effect. */
+  readonly place: readonly Key[];
+  /** The context of the document that caused the effect: its names, its node and its capabilities. */
+  readonly context: Context;
+}
+/** The host side of a run: it does one effect, and gives its result. A throw or a rejection is an error value. */
+type Perform = (effect: Effect) => unknown;
+/**
+ * The runtime of one evaluation or run. Compiled code gets it with the context, and asks it to resolve paths and
+ * to cause effects.
+ */
+interface Runtime {
+  readonly machine: Machine;
+  /** `true` in a run: the host does each effect, and a part that waits needs a parent that can wait. */
+  readonly running: boolean;
+  /**
+   * This function resolves a path from a context.
+   *
+   * @param ctx - The context.
+   * @param path - The steps. The first step is a root.
+   * @param options - `hops: true` records each hop. The default records them only in a traced evaluation.
+   * @returns What the path reached, or an error.
+   */
+  resolve(ctx: Context, path: readonly unknown[], options?: ResolveOptions): Resolution;
+  /**
+   * This function causes an effect from an evaluator. In a run, an evaluator cannot cause an effect: the host does
+   * each effect, thus only a runner can wait for it.
+   *
+   * @param ctx - The context of the document.
+   * @param kind - The kind of the effect.
+   * @param payload - The data of the effect.
+   * @param place - The place of the document.
+   * @returns The payload, or an error value.
+   */
+  effect(ctx: Context, kind: Cap, payload: unknown, place: readonly Key[]): Result;
+  /**
+   * This function causes an effect from a runner. In a run, the host does it, and the steps wait when the host
+   * waits.
+   *
+   * @param ctx - The context of the document.
+   * @param kind - The kind of the effect.
+   * @param payload - The data of the effect.
+   * @param place - The place of the document.
+   * @returns The steps that give the result of the host, or an error value.
+   */
+  runEffect(ctx: Context, kind: Cap, payload: unknown, place: readonly Key[]): Steps;
+  /**
+   * This function drives several steps at the same time. When one waits, the others go on.
+   *
+   * @param list - One function for each item. Each function starts the steps of its item.
+   * @param options - The most items that run at the same time. The default is each item.
+   * @returns The steps that give each result, in the order of the list.
+   */
+  all(list: readonly (() => Steps)[], options?: {
+    readonly concurrency?: number;
+  }): Generator<Promise<unknown>, readonly Result[], unknown>;
+}
+/** Compiled code: the evaluation of a document in a context. */
+type Code = (ctx: Context, rt: Runtime) => Result;
+/** Compiled code that can wait: the run of a document in a context. */
+type RunCode = (ctx: Context, rt: Runtime) => Steps;
+/** A compiled part: its place in its parent, its binding name, and its code. It has no field with its value. */
+interface CompiledPart {
+  /** The path in the value of the parent as one text, for example `0` or `bind.x`. */
+  readonly key: string;
+  /** The keys from the value of the parent to the part. */
+  readonly path: readonly Key[];
+  /** The binding name from the header of the part. */
+  readonly name?: string;
+  /** The code that evaluates the part. */
+  readonly code: Code;
+  /** The code that runs the part. Its steps can wait. */
+  readonly run: RunCode;
+}
+/** The input of a compiler: the document, its kind, and its parts, compiled. */
+interface CompileInput {
+  /** The text of the type of the document, for example `add` or `math.sum` after its alias. */
+  readonly kind: string;
+  /** The keys of the kind after each alias. */
+  readonly typePath: readonly Key[];
+  readonly doc: Envelope;
+  /** The value of the document with a compiled part in the place of each part. */
+  readonly value: unknown;
+  /** The value of the document without its parts. */
+  readonly data: Json;
+  /** The compiled parts, in the order of the value. */
+  readonly parts: readonly CompiledPart[];
+  /** The keys from the root document to this document. */
+  readonly place: readonly Key[];
+  readonly machine: Machine;
+}
+/**
+ * A sealed part. An evaluator can read the binding name of a part and evaluate it. It cannot read the value of the
+ * part, thus two parts that give the same results can replace each other.
+ */
+interface Part$1 {
+  /** The path in the value of the parent as one text, for example `0` or `bind.x`. */
+  readonly key: string;
+  /** The keys from the value of the parent to the part. */
+  readonly path: readonly Key[];
+  /** The binding name from the header of the part. */
+  readonly name?: string;
+  /**
+   * This function evaluates the part. Each call is a new evaluation.
+   *
+   * @param context - The context for the part. The default is the context of the parent.
+   * @returns The result of the part.
+   */
+  evaluate(context?: Context): Result;
+}
+/** The input of an evaluator. */
+interface EvalInput {
+  /** The text of the type of the document, for example `add` or `math.sum` after its alias. */
+  readonly kind: string;
+  /** The keys of the kind after each alias. */
+  readonly typePath: readonly Key[];
+  readonly doc: Envelope;
+  /** The value of the document with a sealed part in the place of each part. */
+  readonly value: unknown;
+  /** The value of the document without its parts. */
+  readonly data: Json;
+  /** The parts, in the order of the value. */
+  readonly parts: readonly Part$1[];
+  /** The context of the document. */
+  readonly context: Context;
+  /** The keys from the root document to this document. */
+  readonly place: readonly Key[];
+  /**
+   * This function resolves a path from the context of the document.
+   *
+   * @param path - The steps. The first step is a root.
+   * @param options - `hops: true` records each hop.
+   * @returns What the path reached, or an error.
+   */
+  resolve(path: readonly unknown[], options?: ResolveOptions): Resolution;
+  /**
+   * This function causes an effect. The context must have the capability for the kind of the effect. In a run, an
+   * evaluator cannot cause an effect: the host does each effect, thus only a runner can wait for it.
+   *
+   * @param kind - The kind of the effect, for example `log`.
+   * @param payload - The data of the effect.
+   * @returns The payload, or the error `#CAP!`.
+   */
+  effect(kind: Cap, payload: unknown): Result;
+}
+/** A part for a runner. Its evaluation can wait for the effects in it. */
+interface RunPart {
+  /** The path in the value of the parent as one text. */
+  readonly key: string;
+  /** The keys from the value of the parent to the part. */
+  readonly path: readonly Key[];
+  /** The binding name from the header of the part. */
+  readonly name?: string;
+  /**
+   * This function evaluates the part. Each call is a new evaluation. Take its result with `yield*`.
+   *
+   * @param context - The context for the part. The default is the context of the parent.
+   * @returns The steps of the evaluation of the part.
+   */
+  evaluate(context?: Context): Steps;
+}
+/** The input of a runner: the input of an evaluator, with parts and effects that can wait. */
+interface RunInput {
+  readonly kind: string;
+  readonly typePath: readonly Key[];
+  readonly doc: Envelope;
+  /** The value of the document with a part for a runner in the place of each part. */
+  readonly value: unknown;
+  readonly data: Json;
+  readonly parts: readonly RunPart[];
+  readonly context: Context;
+  readonly place: readonly Key[];
+  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
+   * an evaluation, the effect gives its payload. Take its result with `yield*`.
+   *
+   * @param kind - The kind of the effect, for example `log`.
+   * @param payload - The data of the effect.
+   * @returns The steps that give the result of the host, or an error value.
+   */
+  effect(kind: Cap, payload: unknown): Steps;
+  /**
+   * This function evaluates parts at the same time. Take the results with `yield*`.
+   *
+   * @param parts - The parts.
+   * @param options - The most parts that run at the same time.
+   * @returns The steps that give each result, in the order of the parts.
+   */
+  all(parts: readonly RunPart[], options?: {
+    readonly concurrency?: number;
+  }): Generator<Promise<unknown>, readonly Result[], unknown>;
+}
+/** An evaluator that is a function of its input. The kernel calls it for each evaluation. */
+type EvalFn = (input: EvalInput) => Result;
+/** An evaluator that compiles a document one time into code. The code then evaluates it many times. */
+interface CompiledEvaluator {
+  /**
+   * This function compiles a document.
+   *
+   * @param input - The document, its kind and its compiled parts.
+   * @returns The code that evaluates the document.
+   */
+  readonly compile: (input: CompileInput) => Code;
+}
+/** An evaluator: a function of its input, or a compiler. */
+type Evaluator = EvalFn | CompiledEvaluator;
+/** A runner that is a generator function of its input. */
+type RunFn = (input: RunInput) => Steps;
+/** A runner that compiles a document one time into code that can wait. */
+interface CompiledRunner {
+  /**
+   * This function compiles a document.
+   *
+   * @param input - The document, its kind and its compiled parts.
+   * @returns The code that runs the document.
+   */
+  readonly compileRun: (input: CompileInput) => RunCode;
+}
+/**
+ * A runner: the code of a kind whose parts or effects can wait. The same runner serves an evaluation, which does
+ * not wait at any time, and a run, in which the host does each effect.
+ */
+type Runner = RunFn | CompiledRunner;
+/**
+ * A machine: a world of kinds, and the code of each evaluator name, of each `deref` and of each walker.
+ *
+ * - `maxDepth`: the deepest nesting of documents. The default is 1000.
+ * - `permits`: the rule of the host for an effect. The default is the function `permits` on the capabilities.
+ */
+interface Machine extends Navigator {
+  readonly evaluators: Readonly<Record<string, Evaluator>>;
+  /** The runners, by evaluator name. A runner wins over an evaluator of the same name. */
+  readonly runners?: Readonly<Record<string, Runner>>;
+  readonly maxDepth?: number;
+  readonly permits?: (caps: readonly Cap[], kind: readonly Key[], context: Context) => boolean;
+}
+/** One evaluation in a trace. The children are the evaluations of its parts, in the order that they started. */
+interface TraceNode {
+  readonly id: number;
+  /** The keys from the root document to this document, as texts. */
+  readonly path: readonly string[];
+  /** The document. A bare value has the type that its position declares. */
+  readonly doc: Envelope;
+  /** `true` when the type came from the container and not from an envelope. */
+  readonly declared: boolean;
+  /** The answer of the ladder to the verb `eval`. */
+  readonly answer: Answer;
+  readonly side: Side;
+  /** The names that the document could read when its evaluation started. */
+  readonly names: readonly string[];
+  /** The names and their values when the evaluation started. */
+  readonly scope: Readonly<Record<string, unknown>>;
+  /** The capabilities that the document had when its evaluation started. */
+  readonly caps: readonly Cap[];
+  /** A short text for the root `self` when the evaluation started. */
+  readonly self: string;
+  /** The time of the start. Each start and each end takes one tick. */
+  readonly enter: number;
+  /** The time of the end. */
+  readonly exit: number;
+  readonly result: Result;
+  readonly children: readonly TraceNode[];
+  /** The indices of the effects that this document caused itself. */
+  readonly effects: readonly number[];
+}
+/** The record of one evaluation of a document. */
+interface Run {
+  readonly result: Result;
+  readonly trace: TraceNode;
+  readonly effects: readonly Effect[];
+  /** The number of ticks. */
+  readonly time: number;
+}
+/** A signal of the host that stops a run: the shape of the standard `AbortSignal`. */
+interface StopSignal {
+  readonly aborted: boolean;
+  readonly reason?: unknown;
+  addEventListener(type: "abort", listener: () => void, options?: {
+    readonly once?: boolean;
+  }): void;
+}
+/** The options of a run. */
+interface RunOptions {
+  /** The host code that does each effect. Without it, an effect gives its payload, as in an evaluation. */
+  readonly perform?: Perform;
+  /** The type of a bare root value. */
+  readonly declaredType?: string;
+  /** A signal of the host. When it aborts, the run stops with `#ABORT`. */
+  readonly signal?: StopSignal;
+}
+/** The options of an evaluation of a plan. */
+interface EvalOptions {
+  /** A list that gets each effect, in its order. */
+  readonly effects?: Effect[];
+}
+/** The options of a compilation. */
+interface PrepareOptions {
+  /** The type of a bare root value. */
+  readonly declaredType?: string;
+  /** `true`: each evaluation records a trace. The default is `false`. */
+  readonly trace?: boolean;
+}
+/** A compiled document. It evaluates many times, and it does the work of the ladder one time. */
+interface Plan {
+  readonly machine: Machine;
+  /** `true` when each evaluation records a trace. */
+  readonly traced: boolean;
+  /** The compiled root document. */
+  readonly root: CompiledPart;
+  /**
+   * This function evaluates the document. It does not wait, and the host does no effect.
+   *
+   * @param context - The names and the capabilities at the root.
+   * @param options - A list that gets the effects.
+   * @returns The result.
+   */
+  evaluate(context?: Context, options?: EvalOptions): Result;
+  /**
+   * This function runs the document: the host does each effect, and the run waits when the host waits.
+   *
+   * @param context - The names and the capabilities at the root.
+   * @param options - The host code that does the effects, and a signal to stop the run.
+   * @returns The result, when the run ends.
+   */
+  run(context?: Context, options?: RunOptions): Promise<Result>;
+}
+/**
+ * This function compiles a document into a plan. The ladder, the kinds and the parts are known after it. A plan
+ * evaluates many times. A document that does not compile gives a plan that fails with the reason, when it evaluates.
+ *
+ * @param machine - The world and the code of the evaluators.
+ * @param doc - The document, as JSON.
+ * @param options - The type of a bare root value, and a trace.
+ * @returns The plan.
+ */
+export declare function prepare(machine: Machine, doc: unknown, options?: PrepareOptions): Plan;
+/**
+ * This function makes a cache of plans for one machine. A document object compiles one time. Use it only for
+ * documents that do not change after they are made.
+ *
+ * @param machine - The machine.
+ * @param options - The options of each compilation.
+ * @returns A function that gives the plan of a document.
+ */
+export declare function planner(machine: Machine, options?: PrepareOptions): (doc: unknown) => Plan;
+/**
+ * This function evaluates a document, and records each evaluation in a trace.
+ *
+ * The verb `eval` goes up the ladder for each document. The kind of the document 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 nothing does it.
+ *
+ * @param machine - The world and the code of the evaluators.
+ * @param doc - The document, as JSON.
+ * @param context - The names and the capabilities at the root.
+ * @param declaredType - The type of a bare root value.
+ * @returns The result, the trace and the effects in their order.
+ */
+export declare function evaluate(machine: Machine, doc: unknown, context?: Context, declaredType?: string): Run;
+/**
+ * This function runs a document: an evaluation in which the host does each effect. A runner waits for its
+ * parts and for its effects, thus a step can read the result of the step before. The part of the run before the
+ * first wait happens at once, in the call. The run records a trace.
+ *
+ * @param machine - The world, the evaluators and the runners.
+ * @param doc - The document, as JSON.
+ * @param context - The names and the capabilities at the root.
+ * @param options - The host code that does the effects, the type of a bare root value, and a signal.
+ * @returns The result, the trace and the effects in their order, when the run ends.
+ */
+export declare function run(machine: Machine, doc: unknown, context?: Context, options?: RunOptions): Promise<Run>;
+/**
+ * This function finds a node of a trace by its path.
+ *
+ * @param trace - The root of the trace.
+ * @param path - The keys from the root.
+ * @returns The first evaluation at that path, or `undefined` when the document did not evaluate.
+ */
+export declare function nodeAt(trace: TraceNode, path: readonly Key[]): TraceNode | undefined;
+/**
+ * This function lists the nodes of a trace in the order of their start.
+ *
+ * @param trace - The root of the trace.
+ * @returns Each node, the root first.
+ */
+export declare function flatten(trace: TraceNode): readonly TraceNode[];
+/**
+ * This function lists the errors of a trace: each node whose result is an error and whose parts did not fail
+ * the same way. These nodes are where each error started.
+ *
+ * @param trace - The root of the trace.
+ * @returns The errors, in the order of their start.
+ */
+export declare function failures(trace: TraceNode): readonly EvalError[];
+//#endregion
+//#region src/stdlib.d.ts
+/**
+ * The world of the examples: small kinds for numbers, lists, conditions, names, sequences and effects.
+ * Each kind names an evaluator for `eval` and a view for `view`. The site draws each document with its view.
+ */
+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 options of a walker `nearest`. */
+interface NearestOptions {
+  /**
+   * This function tells if a node has the wanted type. The default compares the field `type` of a host thing.
+   *
+   * @param node - The node that the walk reached.
+   * @param wanted - The type that the step document asks for.
+   * @returns `true` when the node has the type.
+   */
+  readonly matches?: (node: Thing, wanted: Json | undefined) => boolean;
+  /** The most hops of one walk. The default is 256. */
+  readonly maxHops?: number;
+}
+/**
+ * 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.
+ *
+ * @param options - The test of a type and the most hops.
+ * @returns The walker.
+ */
+export declare function nearestWalker(options?: NearestOptions): Walker;
+/** The walkers of the standard world, by name. */
+export declare const STD_WALKERS: Readonly<Record<string, Walker>>;
+/**
+ * The runners of the standard world, by name: the kinds that can hold effects. Each one evaluates its parts in
+ * order. In a run, an effect ends before the next step starts.
+ */
+export declare const STD_RUNNERS: Readonly<Record<string, Runner>>;
+/** The machine of the examples: the standard world, its evaluators, its runners and its walkers. */
+export declare const STD_MACHINE: Machine;
+/** The capabilities of the examples at the root: the two effects of the standard world. */
+export declare const STD_CAPS: readonly string[];
+//#endregion
+//#region src/order.d.ts
+/** One step of a sequence: its name, the names of the earlier steps that it reads, and if it has an effect. */
+interface StepSpec {
+  readonly id: string;
+  readonly reads: readonly string[];
+  readonly effect: boolean;
+}
+/** An edge from a step that must come first to a step that must come after it. */
+type Edge = readonly [before: string, after: string];
+/** A reference that a sequence cannot resolve. */
+interface OrderProblem {
+  readonly step: string;
+  readonly reads: string;
+  /** `unknown-name`: no step has this name. `read-before-defined`: the step with this name comes later. */
+  readonly problem: "unknown-name" | "read-before-defined";
+}
+/**
+ * This function finds the references that a sequence cannot resolve. A step can read only the steps before it.
+ *
+ * @param steps - The steps, in the written order.
+ * @returns One problem for each bad reference, in the written order.
+ */
+export declare function checkSteps(steps: readonly StepSpec[]): readonly OrderProblem[];
+/**
+ * This function gives the data edges: a step comes after each earlier step that it reads.
+ *
+ * @param steps - The steps, in the written order.
+ * @returns The edges. A bad reference gives no edge.
+ */
+export declare function dataEdges(steps: readonly StepSpec[]): readonly Edge[];
+/**
+ * This function gives the effect edges: each step with an effect comes after the previous step with an effect.
+ * Effects keep their written order. Steps without an effect get no effect edge.
+ *
+ * @param steps - The steps, in the written order.
+ * @returns The edges, one for each pair of consecutive effect steps.
+ */
+export declare function effectEdges(steps: readonly StepSpec[]): readonly Edge[];
+/**
+ * This function tells if an order of the steps gives the same meaning as the written order.
+ * The order must contain each step one time, and it must obey the data edges and the effect edges.
+ *
+ * @param steps - The steps, in the written order.
+ * @param order - The names of the steps in the order to examine.
+ * @returns `true` when the order is permitted.
+ */
+export declare function isAllowedOrder(steps: readonly StepSpec[], order: readonly string[]): boolean;
+/**
+ * This function puts the steps in layers. Each step goes one layer after the last step that it must follow.
+ * The steps of one layer do not depend on each other, thus they can run at the same time.
+ *
+ * @param steps - The steps, in the written order.
+ * @returns The layers, first to last. Each layer keeps the written order.
+ */
+export declare function layers(steps: readonly StepSpec[]): readonly (readonly string[])[];
+//#endregion
+//#region src/context.d.ts
+/** The parts of a context. A term can reach outside itself only through these parts. */
+export declare const PARTS: readonly ["self", "names", "world", "event", "caps"];
+/** One part of a context. */
+type Part = (typeof PARTS)[number];
+/** The description of one part of a context. */
+interface PartInfo {
+  readonly part: Part;
+  readonly title: string;
+  /** What a reference through this part reaches. */
+  readonly reaches: string;
+  /** The direction in which a reference through this part goes. */
+  readonly direction: string;
+}
+/** The descriptions of the parts, in the order of `PARTS`. */
+export declare const PART_INFO: readonly PartInfo[];
+/**
+ * What a construct gives the parts of its body, for one part of the context.
+ *
+ * - `same`: the parts get the same value.
+ * - `extends`: the parts get the value with more names.
+ * - `moves`: the parts get a new position.
+ * - `narrows`: the parts get a smaller set.
+ * - `sets`: the parts get a new value.
+ * - `none`: the parts get nothing.
+ */
+type Give = "same" | "extends" | "moves" | "narrows" | "sets" | "none";
+/** How a construct uses one part of the context. */
+interface Use {
+  readonly reads: boolean;
+  readonly gives: Give;
+  readonly note: string;
+}
+/** A construct of a language, and how it uses each part of the context. */
+interface Construct {
+  readonly id: string;
+  readonly title: string;
+  readonly side: Side;
+  readonly summary: string;
+  readonly example: Envelope;
+  readonly uses: Readonly<Record<Part, Use>>;
+}
+/** Six constructs that show the range of the context. */
+export declare const CONSTRUCTS: readonly Construct[];
+//#endregion
+//#region src/static.d.ts
+/** One document that a walk visits. */
+interface DocVisit {
+  /** The keys from the root document to this document, through the parts. It is the place of an error. */
+  readonly place: readonly Key[];
+  /** The keys from the root JSON value to this document. A change at this path changes this document. */
+  readonly at: readonly Key[];
+  /** The document. A bare value has 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 of the document, when the world has it. */
+  readonly kind?: Kind;
+  /** The keys of the kind after each alias. */
+  readonly typePath?: readonly Key[];
+  /** The number of documents around this document. The root has 0. */
+  readonly depth: number;
+  /** The names that the kinds around this document bind for it. */
+  readonly names: ReadonlySet<string>;
+  /** The names that a sequence around this document binds only for the parts after it. */
+  readonly later: ReadonlySet<string>;
+}
+/** A position that a walk cannot read as a document. */
+interface WalkProblem {
+  readonly place: readonly Key[];
+  readonly at: readonly Key[];
+  readonly code: "#PART?" | "#VALUE!";
+  readonly reason: string;
+}
+/** The options of a walk. */
+interface WalkOptions {
+  /** The type of a bare root value. */
+  readonly declaredType?: string;
+  /** The names that the host binds at the root. */
+  readonly names?: readonly string[];
+  /**
+   * This function gets each position that is not a document.
+   *
+   * @param problem - The position and the reason.
+   */
+  readonly problem?: (problem: WalkProblem) => void;
+}
+/**
+ * This function visits each document of a document: the root and each part at each depth, by the contracts of the
+ * kinds. A part of a kind that the world does not have is not visited. The walk uses no stack of the host for the
+ * depth, thus a deep document cannot overflow it.
+ *
+ * @param world - The world of the kinds.
+ * @param doc - The document, as JSON.
+ * @param visit - The function that gets each document. It gives `"skip"` to not visit the parts of a document.
+ * @param options - The type of a bare root value, the names of the host, and a function for the problems.
+ */
+export declare function walk(world: World, doc: unknown, visit: (visit: DocVisit) => void | "skip", options?: WalkOptions): void;
+/** One reference of a document. */
+interface RefUse {
+  /** The place of 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 path of the reference: its root and its steps. */
+  readonly path: readonly Json[];
+  readonly root: string;
+  /** `false` when a kind around the reference binds its first name. A reference to another root is free. */
+  readonly free: boolean;
+}
+/**
+ * This function finds each reference of a document: each document of the type `ref` that a walk reaches. A
+ * reference to a name that a kind around it binds is not free. The others are what the document reads from
+ * outside: its dependencies.
+ *
+ * @param world - The world of the kinds.
+ * @param doc - The document, as JSON.
+ * @param options - The type of a bare root value. The names of the host do not change the result.
+ * @returns The references, in the order of the document.
+ */
+export declare function refsOf(world: World, doc: unknown, options?: WalkOptions): readonly RefUse[];
+/**
+ * This function changes the free references of a document. The document is not changed: the function gives a new
+ * document that shares each part without a change.
+ *
+ * @param world - The world of the kinds.
+ * @param doc - The document, as JSON.
+ * @param change - The function that gives the new document of a reference, or `undefined` to keep it.
+ * @param options - The type of a bare root value, and the names that the host binds at the root.
+ * @returns The new document.
+ */
+export declare function mapRefs(world: World, doc: unknown, change: (use: RefUse) => unknown, options?: WalkOptions): unknown;
+/** A problem that a check finds before a document runs. */
+interface Issue {
+  readonly code: ErrorCode;
+  /** The keys from the root document to the document with the problem. */
+  readonly place: readonly Key[];
+  readonly reason: string;
+}
+/** The options of a check. */
+interface CheckOptions {
+  /** The type of a bare root value. */
+  readonly declaredType?: string;
+  /** The names that the host binds at the root. `"any"` does not check the names. The default is no names. */
+  readonly names?: readonly string[] | "any";
+  /** The capabilities at the root. Without them, the check does not check the effects. */
+  readonly caps?: readonly Cap[];
+}
+/**
+ * This function checks a document before an evaluation, by the contracts of its kinds. It finds the problems
+ * that an evaluation finds when it reaches them:
+ *
+ * - `#KIND?`: a kind that the world does not have.
+ * - `#NOEVAL`: no evaluator.
+ * - `#VALUE!`: a value without the shape of its kind.
+ * - `#PART?`: a value without a type.
+ * - `#DEPTH!`: too much nesting.
+ * - `#REF!` and `#STEP?`: a bad path.
+ * - `#NAME?`: a name that nothing binds.
+ * - `#CAP!`: an effect that the capabilities do not permit.
+ *
+ * @param machine - The world and the code of the evaluators.
+ * @param doc - The document, as JSON.
+ * @param options - The type of a bare root value, the names of the host and the capabilities.
+ * @returns The problems, in the order of the document.
+ */
+export declare function check(machine: Machine, doc: unknown, options?: CheckOptions): readonly Issue[];
+//#endregion
+//#region src/formula.d.ts
+/** An operation of a formula language: a function of the values of its arguments. */
+type OpFn = (...args: never[]) => unknown;
+/**
+ * A lazy operation: it gets one function for each argument. It evaluates only the arguments that it needs, for
+ * 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. */
+type ExtFn = (data: Json) => 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`.
+ * - `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`.
+ * - `logic`: what `and` and `or` give: a truth value (the default), or the value that decided.
+ * - `omit`: the errors that leave a field out of a `record`, as an absent value.
+ * - `missing`: the values that a reference cannot give. Such a value gives `#N/A`.
+ * - `check`: a check of the value of an operation, for example "a number must be finite".
+ */
+interface FormulaProfile {
+  readonly ops?: Readonly<Record<string, OpFn>> | ((name: string) => OpFn | undefined);
+  readonly lazy?: Readonly<Record<string, LazyOp>>;
+  readonly ext?: Readonly<Record<string, ExtFn>>;
+  readonly truthy?: (value: unknown) => boolean | undefined;
+  readonly otherwise?: unknown;
+  readonly logic?: "boolean" | "value";
+  readonly omit?: (error: EvalError) => boolean;
+  readonly missing?: (value: unknown) => boolean;
+  readonly check?: (value: unknown, op: string) => Result | undefined;
+}
+/** The value of a name whose binding failed. A reference to the name gives the error. */
+export declare class Held {
+  readonly error: EvalError;
+  constructor(error: EvalError);
+}
+declare const CLOSURE: unique symbol;
+/** A function that the construct `fn` made. It throws a `Failure` when its body fails. */
+type Closure = ((...args: readonly unknown[]) => unknown) & {
+  readonly [CLOSURE]: {
+    readonly params: readonly string[];
+  };
+};
+/**
+ * This function tells if a value is a function that the construct `fn` made.
+ *
+ * @param value - The value.
+ * @returns `true` for a closure.
+ */
+export declare function isClosure(value: unknown): value is Closure;
+/** The standard extensions: the values that JSON cannot write. */
+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;
+/**
+ * This function makes the kinds of the formula kit, for a world. The kinds are the shared constructs of D13 and
+ * the namespaces `ops` and `ext`. A bare value in a position of a term is a literal.
+ *
+ * @returns The entries of the world, by their key.
+ */
+export declare function formulaKinds(): Readonly<Record<string, WorldEntry>>;
+/**
+ * This function makes the evaluators of the formula kit for one language. Each evaluator compiles its document
+ * one time into code.
+ *
+ * @param profile - The operations and the rules of the language.
+ * @returns The evaluators, by their name.
+ */
+export declare function formulaEvaluators(profile?: FormulaProfile): Readonly<Record<string, Evaluator>>;
+/**
+ * This function makes a machine for a formula language. The machine has the kinds and the evaluators of the
+ * formula kit. It also has the kinds, the evaluators and the walkers that the language adds.
+ *
+ * @param profile - The operations and the rules of the language.
+ * @param more - The parts of a machine that the language adds. Its kinds win over the kinds of the kit.
+ * @returns The machine.
+ */
+export declare function formulaMachine(profile?: FormulaProfile, more?: Partial<Machine>): Machine;
+//#endregion
+export type { Alias, Answer, AskOptions, Cap, CheckOptions, Classification, Closure, Code, CompileInput, CompiledEvaluator, CompiledPart, CompiledRunner, Construct, Context, Part as ContextPart, DerefCode, DocVisit, Edge, Effect, Envelope, ErrorCode, EvalError, EvalFn, EvalInput, EvalOptions, Evaluator, ExtFn, Failed, FormulaProfile, Give, Header, Hop, HopBy, HostThing, Issue, Json, JsonRecord, KernelCode, Key, Kind, KindSource, LazyOp, Lookup, Machine, NamesSource, Namespace, Navigator, NearestOptions, OpFn, OrderProblem, Outcome, Part$1 as Part, PartInfo, Shape as PartShape, PartSlot, PartsSpec, Perform, Plan, PrepareOptions, RefUse, Resolution, ResolveCode, ResolveOptions, Result, Root, Run, RunCode, RunFn, RunInput, RunOptions, RunPart, Rung, Runner, Runtime, ScopeRule, Shape$1 as Shape, Side, Split, Step, StepSpec, Steps, StopSignal, Stored, Thing, TraceNode, TypeRef, Use, WalkInput, WalkOptions, WalkProblem, WalkResult, Walker, World, WorldEntry };
+//# sourceMappingURL=index.d.ts.map