@mark1russell7/coeval 0.4.0 → 0.4.2

package/build/index.d.ts

@@ -247,285 +247,6 @@ export declare function thrown(error: unknown, who: string): Failed;
  */
 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.
- * - `text`, `number` and `one`: the value is data of that type. `one` names the values that it permits.
- *
- * A `term` with `address: true` is an address: a reference there gives what its path reaches, not the value. A
- * `term` with `kinds` permits only a part whose type starts with one of the paths. A `record` with `closed: true`
- * permits only its named fields. A `list` with `distinct: true` permits no two equal items.
- */
-type Shape = {
-  readonly shape: "none";
-} | {
-  readonly shape: "term";
-  readonly of?: string;
-  readonly address?: boolean;
-  readonly kinds?: readonly (readonly Key[])[];
-} | {
-  readonly shape: "list";
-  readonly of?: string;
-  readonly item?: Shape;
-  readonly distinct?: boolean;
-} | {
-  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 closed?: boolean;
-} | {
-  readonly shape: "deep";
-  readonly of?: string;
-} | {
-  readonly shape: "text";
-} | {
-  readonly shape: "number";
-  readonly whole?: boolean;
-  readonly min?: number;
-  readonly max?: number;
-} | {
-  readonly shape: "one";
-  readonly values: readonly Json[];
-};
-/** 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. `fallback` is the kind of each first key that
- * the world does not have. A world with a fallback is open: each path that starts with an unknown key names a kind.
- */
-interface World {
-  readonly kinds: Readonly<Record<string, WorldEntry>>;
-  readonly defaults: Readonly<Record<string, string>>;
-  readonly fallback?: Kind;
-}
-/** 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. In an open world, a first
- * key that the world does not have gets the fallback kind of the world.
- *
- * @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
@@ -674,74 +395,382 @@ interface ResolveOptions {
   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.
+ * 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/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.
+ * - `text`, `number` and `one`: the value is data of that type. `one` names the values that it permits.
+ *
+ * A `term` with `address: true` is an address: a reference there gives what its path reaches, not the value. A
+ * `term` with `kinds` permits only a part whose type starts with one of the paths. A `record` with `closed: true`
+ * permits only its named fields. A `list` with `distinct: true` permits no two equal items.
+ */
+type Shape = {
+  readonly shape: "none";
+} | {
+  readonly shape: "term";
+  readonly of?: string;
+  readonly address?: boolean;
+  readonly kinds?: readonly (readonly Key[])[];
+} | {
+  readonly shape: "list";
+  readonly of?: string;
+  readonly item?: Shape;
+  readonly distinct?: boolean;
+} | {
+  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 closed?: boolean;
+} | {
+  readonly shape: "deep";
+  readonly of?: string;
+} | {
+  readonly shape: "text";
+} | {
+  readonly shape: "number";
+  readonly whole?: boolean;
+  readonly min?: number;
+  readonly max?: number;
+} | {
+  readonly shape: "one";
+  readonly values: readonly Json[];
+};
+/** 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 capability rule of a kind: what the kind gives some of its parts from the capabilities of its document. A rule
+ * only narrows. A part does not get a capability that its document does not have (CAP.NARROW).
+ *
+ * - `same`: the parts get the capabilities of the document. This is the default.
+ * - `mask`: the parts get no capabilities, as the part of `pure`.
+ * - `only`: the parts get only the effects that the capabilities of the document and the list `caps` both permit.
+ *
+ * `in` names the parts that the rule covers, as patterns of their paths in the value. The key `"*"` matches each
+ * key. A rule without `in` covers each part.
+ */
+type CapsRule = {
+  readonly rule: "same";
+  readonly in?: readonly (readonly Key[])[];
+} | {
+  readonly rule: "mask";
+  readonly in?: readonly (readonly Key[])[];
+} | {
+  readonly rule: "only";
+  readonly caps: readonly Cap[];
+  readonly in?: readonly (readonly Key[])[];
+};
+/** 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 capabilities that the kind gives its parts, as rules. A part that no rule covers gets the capabilities of
+   * the document. A part that several rules cover gets only what each rule permits. The static kit reads the rules,
+   * and the kernel narrows the context of each part by them. Thus an evaluator does not narrow the capabilities
+   * itself.
+   */
+  readonly caps?: readonly CapsRule[];
+  /** 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. `fallback` is the kind of each first key that
+ * the world does not have. A world with a fallback is open: each path that starts with an unknown key names a kind.
+ */
+interface World {
+  readonly kinds: Readonly<Record<string, WorldEntry>>;
+  readonly defaults: Readonly<Record<string, string>>;
+  readonly fallback?: Kind;
+}
+/** 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 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.
+ * @param entry - The entry.
+ * @returns `true` for a kind.
  */
-export declare function derefStep(nav: Navigator, thing: Thing, key: Key): {
-  readonly thing: Thing;
-  readonly by: HopBy;
-} | undefined;
+export declare function isKind(entry: WorldEntry | undefined): entry is Kind;
 /**
- * This function tells if a thing is a reference document: an envelope of the type `ref` with a list for its path.
+ * This function tells if an entry of the world is an alias.
  *
- * @param thing - The thing.
- * @returns `true` for a reference document.
+ * @param entry - The entry.
+ * @returns `true` for an alias.
  */
-export declare function isRef(thing: unknown): thing is Envelope & {
-  readonly value: readonly Json[];
-};
+export declare function isAlias(entry: WorldEntry | undefined): entry is Alias;
 /**
- * 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.
+ * 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. In an open world, a first
+ * key that the world does not have gets the fallback kind of the world.
  *
  * @param world - The world.
- * @returns The thing.
+ * @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 worldThing(world: World): Json;
+export declare function lookupKind(world: World, type: TypeRef): Lookup;
 /**
- * This function makes a context. The world comes from the navigator when the call gives none.
+ * 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 parts - The roots to set.
- * @returns The context.
+ * @param entries - The entries.
+ * @returns The JSON form.
  */
-export declare function context(parts?: Partial<Context>): Context;
+export declare function entriesAsJson(entries: Readonly<Record<string, WorldEntry>>): Json;
 /**
- * This function resolves a path from a context, and records each hop.
+ * This function makes the document of a kind, so that a view can draw it as each other document.
  *
- * 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.
+ * @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.
  *
- * The codes of a failure:
+ * @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.
  *
- * - `#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.
+ * - `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 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.
+ * @param world - The world.
+ * @param type - The reference to the type.
+ * @returns The kind, or `undefined`.
  */
-export declare function resolve(nav: Navigator, ctx: Context, path: readonly unknown[], options?: ResolveOptions): Resolution;
+export declare function kindOf(world: World, type: TypeRef): Kind | undefined;
 /**
- * This function gives the value of a thing: the value that a host thing gives, or else the thing itself.
+ * This function finds a kind by a text type. It is the same as `kindOf` for a one-key reference.
  *
- * @param thing - The thing.
- * @returns The value.
+ * @param world - The world.
+ * @param name - The text of the type.
+ * @returns The kind, or `undefined`.
  */
-export declare function valueOfThing(thing: Thing): unknown;
+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/classify.d.ts
 /** A shape proposes a kind for each document that has all of its fields. */
@@ -866,6 +895,25 @@ export declare function permits(caps: readonly Cap[], kind: Cap): boolean;
  * @returns The context of the part.
  */
 export declare function narrow(parent: Context, next: Context): Context;
+/**
+ * This function gives the capabilities that two lists both permit. An effect is permitted by the result when each
+ * list permits it. When the list `b` permits each capability of `a`, the result is the list `a` itself.
+ *
+ * @param a - The first list, for example the capabilities of a document.
+ * @param b - The second list, for example the list of a rule `only`.
+ * @returns The capabilities that both lists permit.
+ */
+export declare function intersectCaps(a: readonly Cap[], b: readonly Cap[]): readonly Cap[];
+/**
+ * This function gives the capabilities that a kind gives one of its parts, by the capability rules of its contract.
+ * The kernel and the static kit both use it, thus a run and a check narrow the same way.
+ *
+ * @param rules - The capability rules of the kind (`Kind.caps`).
+ * @param path - The path of the part in the value of the document.
+ * @param caps - The capabilities of the document.
+ * @returns The capabilities of the part: the same list or a smaller one.
+ */
+export declare function partCaps(rules: readonly CapsRule[] | undefined, path: readonly Key[], caps: readonly Cap[]): readonly Cap[];
 /**
  * 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
@@ -1486,6 +1534,11 @@ interface DocVisit {
   readonly later: ReadonlySet<string>;
   /** `true` when the position of the document declares an address: a reference there is not a read of a value. */
   readonly address?: true | undefined;
+  /**
+   * The capabilities of the document: the capabilities of the walk, narrowed by the capability rules of the kinds
+   * around it (`Kind.caps`). A walk without capabilities gives none here.
+   */
+  readonly caps?: readonly Cap[] | undefined;
 }
 /** A position that a walk cannot read as a document. */
 interface WalkProblem {
@@ -1502,6 +1555,8 @@ interface WalkOptions {
   readonly declaredType?: string;
   /** The names that the host binds at the root. */
   readonly names?: readonly string[];
+  /** The capabilities at the root. With them, each visit gets the capabilities of its document. */
+  readonly caps?: readonly Cap[];
   /**
    * This function gets each position that is not a document.
    *
@@ -1511,14 +1566,15 @@ interface WalkOptions {
 }
 /**
  * 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
+ * kinds. A part of a kind that the world does not have is not visited. With capabilities in the options, the walk
+ * narrows them for each part by the rules of its kind, as a run does. The walk uses no stack of the host for the
  * depth, thus a deep document cannot overflow it. The time and the memory of a walk are linear in the size of the
  * document. A visit makes the keys of its place and of its path only when a reader asks for them.
  *
  * @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.
+ * @param options - The type of a bare root value, the names, the capabilities 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. */
@@ -1574,7 +1630,10 @@ interface CheckOptions {
   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. */
+  /**
+   * The capabilities at the root. Without them, the check does not check the effects. The check narrows them for
+   * each part by the capability rules of the kinds, as a run does.
+   */
   readonly caps?: readonly Cap[];
 }
 /**
@@ -1588,7 +1647,7 @@ interface CheckOptions {
  * - `#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.
+ * - `#CAP!`: an effect that the capabilities of its document do not permit. A kind around the document can narrow them.
  *
  * @param machine - The world and the code of the evaluators.
  * @param doc - The document, as JSON.
@@ -1684,5 +1743,212 @@ export declare function formulaEvaluators(profile?: FormulaProfile): Readonly<Re
  */
 export declare function formulaMachine(profile?: FormulaProfile, more?: Partial<Machine>): Machine;
 //#endregion
-export type { Alias, AllOptions, 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 };
+//#region src/reference.d.ts
+/**
+ * The definitional code of the reference, by evaluator name. The reference cannot read compiled code, thus each
+ * compiled evaluator or runner of a machine needs a definition here. A function evaluator needs none.
+ */
+interface Definitions {
+  readonly evaluators?: Readonly<Record<string, EvalFn>>;
+  readonly runners?: Readonly<Record<string, RunFn>>;
+}
+/** The options of the reference interpreter. */
+interface ReferenceOptions {
+  /** The type of a bare root value. */
+  readonly declaredType?: string;
+  /** The definitional code of the compiled evaluators and runners of the machine. */
+  readonly definitions?: Definitions;
+  /** A list that gets each effect, in its order. */
+  readonly effects?: Effect[];
+}
+/**
+ * This function evaluates a document by the rules, without a compilation. It is the reference of the plans: a plan,
+ * a traced plan and the second tier of a language must give its results. It covers evaluations, not runs: an effect
+ * gives its payload, and a part that waits gives `#CALC!`.
+ *
+ * @param machine - The world and the code of the evaluators.
+ * @param doc - The document.
+ * @param context - The names and the capabilities at the root.
+ * @param options - The type of a bare root value, the definitions of compiled code, and a list for the effects.
+ * @returns The result.
+ */
+export declare function reference(machine: Machine, doc: unknown, context?: Context, options?: ReferenceOptions): Result;
+/**
+ * This function gives the definitions of the formula kit for one profile. Each construct is a function evaluator in
+ * the most direct style. It shares no code with the compilers of `formulaEvaluators`, thus the two readings of the
+ * rules can disagree, and a test finds it.
+ *
+ * @param profile - The operations and the rules of the language.
+ * @returns The definitions, by evaluator name.
+ */
+export declare function formulaDefinitions(profile?: FormulaProfile): Definitions;
+//#endregion
+//#region src/agree.d.ts
+/**
+ * A tier that `agree` compares with the plan.
+ *
+ * - `reference`: the reference interpreter, which compiles nothing.
+ * - `traced`: the traced evaluation, `evaluate`.
+ * - `again`: a second evaluation of the same plan.
+ * - `other`: the second tier of a language, from the option `other`.
+ */
+type Tier = "reference" | "traced" | "again" | "other";
+/** What a second tier gives: its result, and its effects when it records them. */
+interface TierResult {
+  readonly result: Result;
+  readonly effects?: readonly Effect[];
+}
+/** The options of `agree`. */
+interface AgreeOptions {
+  /** The type of a bare root value. */
+  readonly declaredType?: string;
+  /** The definitional code of the compiled evaluators of the machine, for the reference. */
+  readonly definitions?: Definitions;
+  /** The tiers to compare with the plan. The default is the reference, the traced evaluation and a second evaluation. */
+  readonly tiers?: readonly Exclude<Tier, "other">[];
+  /**
+   * This function gives the result of the second tier of a language, for example a compiler to loops.
+   *
+   * @param doc - The document.
+   * @param context - The context.
+   * @returns The result, or the result with the effects.
+   */
+  readonly other?: (doc: unknown, context: Context) => Result | TierResult;
+  /**
+   * This function compares two values that the rules of `sameValue` do not know, for example two dates.
+   *
+   * @param a - The value of the plan.
+   * @param b - The value of the other tier.
+   * @returns `true` or `false`, or `undefined` to use the rules of `sameValue`.
+   */
+  readonly equal?: (a: unknown, b: unknown) => boolean | undefined;
+  /** `true`: two errors must also have the same reason, and each error must have a place. */
+  readonly strict?: boolean;
+  /**
+   * This function gives what the host saw since its last call, for example the calls of an operation. `agree` uses
+   * it before the plan and after each tier, and compares the results. Thus a tier that evaluates a part that the plan
+   * does not evaluate fails.
+   *
+   * @returns What the host saw.
+   */
+  readonly observe?: () => unknown;
+}
+/** The outcome of `agree`: the result of the plan, or the first tier that disagrees with it. */
+type Agreement = {
+  readonly ok: true;
+  readonly result: Result;
+  readonly effects: readonly Effect[];
+} | {
+  readonly ok: false;
+  readonly tier: Tier;
+  /** The result of the plan. */
+  readonly plan: Result;
+  /** The result of the tier that disagrees. */
+  readonly other: Result;
+  /** One sentence that tells the difference. */
+  readonly reason: string;
+};
+/**
+ * This function tells if two values are the same for `agree`. Lists and plain records compare item by item and field
+ * by field, and the order of the fields does not matter. Each other leaf compares with `Object.is`, thus `-0` is not
+ * `0`, and `NaN` is `NaN`. Two closures of `fn` are the same when they have the same parameters. Two `Held` values
+ * are the same when their errors have the same code and place. Identity is not compared.
+ *
+ * @param a - The first value.
+ * @param b - The second value.
+ * @param equal - The rule of the caller for other values. It answers first, and `undefined` gives the rules above.
+ * @returns `true` when the values are the same.
+ */
+export declare function sameValue(a: unknown, b: unknown, equal?: (a: unknown, b: unknown) => boolean | undefined): boolean;
+/**
+ * This function evaluates a document with a plan and with other tiers, and compares the results (PLAN.AGREES). Two
+ * results agree when they have the same value by `sameValue`, or errors with the same code, and the same place when
+ * both have one. The effects must have the same kinds, places and payloads, in the same order. A language gives its
+ * own tier with the option `other`.
+ *
+ * @param machine - The world and the code of the evaluators.
+ * @param doc - The document.
+ * @param context - The names and the capabilities at the root.
+ * @param options - The tiers, the definitions for the reference, the rules of the comparison and the second tier.
+ * @returns The result of the plan, or the first tier that disagrees and the reason.
+ */
+export declare function agree(machine: Machine, doc: unknown, context?: Context, options?: AgreeOptions): Agreement;
+//#endregion
+//#region src/generate.d.ts
+/** A source of random numbers with a seed. The same seed gives the same numbers. */
+interface Random {
+  /** This function gives a number from 0 up to 1, without 1. */
+  next(): number;
+  /** This function gives a whole number from 0 up to `below`, without `below`. */
+  int(below: number): number;
+  /** This function gives `true` with the chance `p`. */
+  chance(p: number): boolean;
+  /** This function gives one item of a list that is not empty. */
+  pick<T>(items: readonly T[]): T;
+}
+/**
+ * This function makes a source of random numbers with a seed (the algorithm mulberry32). It needs no package.
+ *
+ * @param seed - The seed: a whole number.
+ * @returns The source.
+ */
+export declare function random(seed: number): Random;
+/** The options of `generate`. */
+interface GenerateOptions {
+  /** The seed. The same seed and the same options give the same document. */
+  readonly seed: number;
+  /** The types that a document can have. The default is `typesOf(world)`. A namespace with a fallback needs its keys here. */
+  readonly types?: readonly (readonly Key[])[];
+  /** The type of a bare root value. */
+  readonly declaredType?: string;
+  /** The names that the host binds at the root. */
+  readonly names?: readonly string[];
+  /** The deepest nesting of documents. The default is 4. */
+  readonly maxDepth?: number;
+  /** The most documents in one document. The default is 24. */
+  readonly maxSize?: number;
+  /** The chance of a malformed choice at each document. The default is 0.05. */
+  readonly malformed?: number;
+  /**
+   * This function gives the data of a document of a type without parts, for example a number for the kind `number`.
+   *
+   * @param type - The keys of the type.
+   * @param random - The source of random numbers.
+   * @returns The data, or `undefined` for a random JSON value.
+   */
+  readonly data?: (type: readonly Key[], random: Random) => Json | undefined;
+  /**
+   * This function gives the types to prefer for a part, for example a function for the field `fn` of `call`.
+   *
+   * @param type - The keys of the type of the parent.
+   * @param path - The path of the part in the value of the parent.
+   * @returns The types, or `undefined` for no preference.
+   */
+  readonly hints?: (type: readonly Key[], path: readonly Key[]) => readonly (readonly Key[])[] | undefined;
+  /** The evaluator names for own entries. The default is none. */
+  readonly own?: readonly string[];
+  /** The keys for the steps of a path after its root and its name. */
+  readonly keys?: readonly Key[];
+}
+/**
+ * This function lists the types of a world: each kind and each alias, also in a namespace. A namespace with a
+ * fallback gives no types, because each key names a kind.
+ *
+ * @param world - The world.
+ * @returns The keys of each type.
+ */
+export declare function typesOf(world: World): readonly (readonly Key[])[];
+/**
+ * This function builds a random document for a world from the contracts of its kinds. It reads the shapes of the
+ * parts, the declared types, the permitted kinds and the names that the scope rules bind. Some choices are malformed
+ * on purpose. Examples are an unknown kind, a value without its shape, a bare value without a type and a name that
+ * nothing binds. The depth and the size have limits.
+ *
+ * @param world - The world.
+ * @param options - The seed, the types, the limits and the data of the leaves.
+ * @returns The document, as JSON.
+ */
+export declare function generate(world: World, options: GenerateOptions): unknown;
+//#endregion
+export type { AgreeOptions, Agreement, Alias, AllOptions, Answer, AskOptions, Cap, CapsRule, CheckOptions, Classification, Closure, Code, CompileInput, CompiledEvaluator, CompiledPart, CompiledRunner, Construct, Context, Part as ContextPart, Definitions, DerefCode, DocVisit, Edge, Effect, Envelope, ErrorCode, EvalError, EvalFn, EvalInput, EvalOptions, Evaluator, ExtFn, Failed, FormulaProfile, GenerateOptions, 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, Random, RefUse, ReferenceOptions, 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, Tier, TierResult, TraceNode, TypeRef, Use, WalkInput, WalkOptions, WalkProblem, WalkResult, Walker, World, WorldEntry };
 //# sourceMappingURL=index.d.ts.map