@mark1russell7/coeval 0.0.0-stage → 0.1.0

package/build/index.d.ts

@@ -0,0 +1,916 @@
+//#region src/doc.d.ts
+/** A JSON value. */
+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 JSON record (not an array and not null).
+ *
+ * @param value - The value to examine.
+ * @returns `true` for a record.
+ */
+export declare function isRecord(value: Json | undefined): 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: Json | undefined): 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: Json | undefined): boolean;
+/**
+ * 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: Json | undefined): value is JsonRecord & Envelope;
+/**
+ * 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: Json | undefined): Envelope | undefined;
+//#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. A part is a typed document that the evaluator gets sealed.
+ *
+ * - `none`: the value is data. It has no parts.
+ * - `list`: the value is a list, and each item is a part.
+ * - `record`: the value is a record. The named fields are parts, and the other fields are data.
+ *
+ * `of` is the type of a bare item. An item without an envelope gets this type from its container.
+ */
+type PartsSpec = {
+  readonly shape: "none";
+} | {
+  readonly shape: "list";
+  readonly of?: string;
+} | {
+  readonly shape: "record";
+  readonly fields: readonly string[];
+  readonly of?: string;
+};
+/** 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?: PartsSpec;
+  /** The side of the kind. A kind of the run side causes effects. The default is `derive`. */
+  readonly side?: Side;
+  /** One sentence that tells what the kind is. */
+  readonly summary?: string;
+}
+/** A namespace: a group of entries under one key of the world. */
+interface Namespace {
+  readonly kinds: Readonly<Record<string, WorldEntry>>;
+}
+/** 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 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.
+ *
+ * @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;
+//#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. */
+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`.
+   */
+  deref(key: Key): Thing | undefined;
+  /**
+   * This function gives the thing as a value, when a reference ends on it.
+   *
+   * @returns The value.
+   */
+  toJson(): Json;
+}
+/** Something that a path can reach: a JSON value, or a host thing. */
+type Thing = Json | HostThing;
+/**
+ * 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: Thing | undefined): 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];
+/**
+ * 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, Json>>;
+  readonly world: Thing;
+  readonly event: Thing;
+  readonly caps: readonly string[];
+}
+/** 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. */
+interface Navigator {
+  readonly world: World;
+  readonly derefs?: Readonly<Record<string, DerefCode>>;
+  readonly walkers?: Readonly<Record<string, Walker>>;
+}
+/** 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 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: "#REF!" | "#CYCLE!" | "#STEP?";
+  readonly reason: string;
+  readonly hops: readonly Hop[];
+};
+/**
+ * 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: a field
+ * of a record, 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`.
+ */
+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`.
+ *
+ * @param thing - The thing.
+ * @returns `true` for a reference document.
+ */
+export declare function isRef(thing: Thing | undefined): 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).
+ *
+ * @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).
+ *
+ * @param nav - The world and the code of the evaluators.
+ * @param ctx - The context.
+ * @param path - The steps.
+ * @returns What the path reached and each hop, or an error.
+ */
+export declare function resolve(nav: Navigator, ctx: Context, path: readonly Json[]): Resolution;
+/**
+ * This function gives the value of a thing: the thing itself for JSON, or the value that a host thing gives.
+ *
+ * @param thing - The thing.
+ * @returns The value.
+ */
+export declare function valueOfThing(thing: Thing): Json;
+//#endregion
+//#region src/classify.d.ts
+/** A shape proposes a kind for each document that has all of its fields. */
+interface Shape {
+  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[], 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 key, the JSON of the part, and the type that its position declares. */
+interface PartSlot {
+  readonly key: string;
+  readonly item: Json;
+  readonly of?: string;
+}
+/** The value of a document, split into its data and its parts. */
+type Split = {
+  readonly ok: true;
+  readonly data: Json;
+  readonly parts: readonly PartSlot[];
+} | {
+  readonly ok: false;
+  readonly reason: string;
+};
+/**
+ * This function splits a value into its data and its parts, by the contract of its kind. The evaluator and the
+ * view use the same split, thus a picture shows the parts that the evaluation gets.
+ *
+ * @param spec - The contract of the parts.
+ * @param value - The value of the document.
+ * @returns The data and the parts, or the reason why the value does not obey the contract.
+ */
+export declare function splitParts(spec: PartsSpec | undefined, value: Json): Split;
+//#endregion
+//#region src/evaluate.d.ts
+/** The code of an error value. */
+type ErrorCode = "#KIND?" | "#NOEVAL" | "#PART?" | "#NAME?" | "#REF!" | "#CYCLE!" | "#STEP?" | "#VALUE!" | "#ARGS" | "#CAP!" | "#CALC!" | "#DEPTH!";
+/** An error value: a code and a reason. An evaluation gives an error value, and it does not throw. */
+interface EvalError {
+  readonly code: ErrorCode;
+  readonly reason: string;
+}
+/** The result of an evaluation: a value, or an error value. */
+type Result = {
+  readonly ok: true;
+  readonly value: Json;
+} | {
+  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(value: Json): Result;
+/**
+ * This function makes a result with an error value.
+ *
+ * @param code - The code of the error.
+ * @param reason - One sentence that tells the cause.
+ * @returns The result.
+ */
+export declare function fail(code: ErrorCode, reason: string): Result;
+/**
+ * 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, Json>>, caps?: readonly string[], self?: Thing): Context;
+/**
+ * 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 position of the part in its parent: an index of a list, or a field of a record. */
+  readonly key: string;
+  /** 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 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;
+  /**
+   * This function resolves a path from the context of the document.
+   *
+   * @param path - The steps. The first step is a root.
+   * @returns What the path reached, with each hop.
+   */
+  resolve(path: readonly Json[]): 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: string, payload: Json): Result;
+}
+/** An evaluator: a function from the input of a document to a result. */
+type Evaluator = (input: EvalInput) => Result;
+/**
+ * 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.
+ */
+type Steps = Generator<Promise<Result>, Result, Result>;
+/** A part for a runner. Its evaluation can wait for the effects in it. */
+interface RunPart {
+  /** The position of the part in its parent: an index of a list, or a field of a record. */
+  readonly key: string;
+  /** 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 {
+  /** The text of the type of the document. */
+  readonly kind: string;
+  /** The value of the document without its parts. */
+  readonly data: Json;
+  /** The parts, in the order of the value. */
+  readonly parts: readonly RunPart[];
+  /** The context of the document. */
+  readonly context: Context;
+  /**
+   * This function resolves a path from the context of the document.
+   *
+   * @param path - The steps. The first step is a root.
+   * @returns What the path reached, with each hop.
+   */
+  resolve(path: readonly Json[]): Resolution;
+  /**
+   * This function causes an effect. The context must have the capability. 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: string, payload: Json): Steps;
+}
+/**
+ * A runner: the code of a kind whose parts or effects can wait, as a generator function. 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 = (input: RunInput) => Steps;
+/** A machine: a world of kinds, and the code of each evaluator name, of each `deref` and of each walker. */
+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>>;
+  /** The deepest nesting of evaluations. The default is 200. */
+  readonly maxDepth?: number;
+}
+/** An effect that an evaluation caused, in the order of the effects. */
+interface Effect {
+  readonly index: number;
+  readonly kind: string;
+  readonly payload: Json;
+  /** The ID of the trace node that caused the effect. */
+  readonly node: number;
+  /** The number of events before the effect. The effect comes before the end of its node. */
+  readonly at: number;
+}
+/** 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) => Json | Promise<Json>;
+/** 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;
+}
+/**
+ * This function tells if the capabilities permit an effect. A capability permits the kind of its name, and each kind
+ * in its namespace: `store` permits `store.update`.
+ *
+ * @param caps - The capabilities of the context.
+ * @param kind - The kind of the effect.
+ * @returns `true` when one capability permits it.
+ */
+export declare function permits(caps: readonly string[], kind: string): 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. */
+  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, Json>>;
+  /** The capabilities that the document had when its evaluation started. */
+  readonly caps: readonly string[];
+  /** 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;
+}
+/**
+ * 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: Json, 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.
+ *
+ * @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, and the type of a bare root value.
+ * @returns The result, the trace and the effects in their order, when the run ends.
+ */
+export declare function run(machine: Machine, doc: Json, 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 string[]): 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[];
+//#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 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 ["names", "focus", "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
+export type { Alias, Answer, AskOptions, Classification, Construct, Context, Part as ContextPart, DerefCode, Edge, Effect, Envelope, ErrorCode, EvalError, EvalInput, Evaluator, Give, Header, Hop, HopBy, HostThing, Json, JsonRecord, Key, Kind, KindSource, Lookup, Machine, Namespace, Navigator, OrderProblem, Outcome, Part$1 as Part, PartInfo, PartSlot, PartsSpec, Perform, Resolution, Result, Root, Run, RunInput, RunOptions, RunPart, Rung, Runner, Shape, Side, Split, Step, StepSpec, Thing, TraceNode, TypeRef, Use, WalkInput, WalkResult, Walker, World, WorldEntry };
+//# sourceMappingURL=index.d.ts.map