@mark1russell7/coeval 0.3.3 → 0.4.1

package/build/index.d.ts

@@ -247,6 +247,223 @@ export declare function thrown(error: unknown, who: string): Failed;
  */
 export declare function describe(value: unknown): string;
 //#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. A failure can give its code, for
+ * example `#REF!` for a position outside a space. The default code is `#N/A`.
+ */
+type WalkResult = {
+  readonly ok: true;
+  readonly thing: Thing;
+} | {
+  readonly ok: false;
+  readonly reason: string;
+  readonly code?: ErrorCode;
+};
+/** 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.
+ * - `adopt`: the thing of each value that a path reaches. A host gives its own values a host thing with this
+ *   function, for example a value whose fields read through signals. A host thing is not followed as a reference.
+ */
+interface Navigator {
+  readonly world: World;
+  readonly derefs?: Readonly<Record<string, DerefCode>>;
+  readonly walkers?: Readonly<Record<string, Walker>>;
+  readonly plain?: boolean;
+  readonly roots?: readonly Root[];
+  readonly adopt?: (value: unknown) => Thing;
+}
+/** 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 that a resolution gives itself. A walker can give another code for its failure. */
+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 | ErrorCode;
+  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/world.d.ts
 /** The two sides of evaluation. `derive` is pure. `run` causes effects in order. */
 type Side = "derive" | "run";
@@ -261,16 +478,24 @@ type Side = "derive" | "run";
  * - `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;
@@ -281,9 +506,20 @@ type 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;
@@ -319,6 +555,28 @@ interface ScopeRule {
   /** `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>>;
@@ -326,6 +584,13 @@ interface Kind {
   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;
   /**
@@ -507,219 +772,6 @@ export declare function kindNamed(world: World, name: TypeRef): Kind | undefined
  */
 export declare function ask(world: World, doc: Header, verb: string, options?: AskOptions): Answer;
 //#endregion
-//#region src/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.
- * - `adopt`: the thing of each value that a path reaches. A host gives its own values a host thing with this
- *   function, for example a value whose fields read through signals. A host thing is not followed as a reference.
- */
-interface Navigator {
-  readonly world: World;
-  readonly derefs?: Readonly<Record<string, DerefCode>>;
-  readonly walkers?: Readonly<Record<string, Walker>>;
-  readonly plain?: boolean;
-  readonly roots?: readonly Root[];
-  readonly adopt?: (value: unknown) => Thing;
-}
-/** 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 {
@@ -765,6 +817,8 @@ interface PartSlot {
   readonly key: string;
   readonly item: Json;
   readonly of?: string;
+  /** `true` when the position of the part declares an address: a reference there gives what its path reaches. */
+  readonly address?: true;
 }
 /** The value of a document, split into its parts, by the shape that its kind declares. */
 type Split = {
@@ -841,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
@@ -966,6 +1039,8 @@ interface CompileInput {
    * @returns The value with the items.
    */
   fill(items: readonly unknown[]): unknown;
+  /** `true` when the position of the document declares an address. A reference there gives the thing, not its value. */
+  readonly address?: boolean;
 }
 /**
  * A sealed part. An evaluator can read the binding name of a part and evaluate it. It cannot read the value of the
@@ -1003,6 +1078,8 @@ interface EvalInput {
   readonly context: Context;
   /** The keys from the root document to this document. */
   readonly place: readonly Key[];
+  /** `true` when the position of the document declares an address. */
+  readonly address?: boolean;
   /**
    * This function resolves a path from the context of the document.
    *
@@ -1437,24 +1514,37 @@ interface DocVisit {
   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 visit of the document that holds this document as a part. The root has none. */
+  readonly parent?: DocVisit | undefined;
+  /** The keys from the value of the parent to this document: the path of the part. The root has none. */
+  readonly slot: 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;
+  readonly kind?: Kind | undefined;
   /** The keys of the kind after each alias. */
-  readonly typePath?: readonly Key[];
+  readonly typePath?: readonly Key[] | undefined;
   /** 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>;
+  /** `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 {
+  /** The keys from the root document to the document with the problem. */
   readonly place: readonly Key[];
+  /** The keys from the root JSON value to the value with the problem. */
   readonly at: readonly Key[];
   readonly code: "#PART?" | "#VALUE!";
   readonly reason: string;
@@ -1465,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.
    *
@@ -1474,17 +1566,21 @@ 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
- * depth, thus a deep document cannot overflow it.
+ * 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. */
 interface RefUse {
+  /** The visit of the reference document: its parent, its depth and the names that it sees. */
+  readonly visit: DocVisit;
   /** The place of the reference document, through the parts. */
   readonly place: readonly Key[];
   /** The keys from the root JSON value to the reference document. */
@@ -1494,11 +1590,13 @@ interface RefUse {
   readonly root: string;
   /** `false` when a kind around the reference binds its first name. A reference to another root is free. */
   readonly free: boolean;
+  /** `true` when the reference is an address: its position declares it. An address does not read a value. */
+  readonly address: 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.
+ * outside: its dependencies. When the kind `ref` has parts, the walk also finds the references in its step documents.
  *
  * @param world - The world of the kinds.
  * @param doc - The document, as JSON.
@@ -1523,6 +1621,8 @@ interface Issue {
   /** The keys from the root document to the document with the problem. */
   readonly place: readonly Key[];
   readonly reason: string;
+  /** The keys from the root JSON value to the value with the problem. */
+  readonly at?: readonly Key[];
 }
 /** The options of a check. */
 interface CheckOptions {
@@ -1530,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[];
 }
 /**
@@ -1544,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.
@@ -1561,8 +1664,8 @@ type OpFn = (...args: never[]) => unknown;
  * example a default for an error.
  */
 type LazyOp = (args: readonly (() => Result)[]) => Result;
-/** The code of an extension: it gives the value of the data of an extension document. */
-type ExtFn = (data: Json) => Result;
+/** The code of an extension: it gives the value of the data of an extension document, in the context of the document. */
+type ExtFn = (data: Json, context: Context) => Result;
 /**
  * The rules of one formula language: its operations, and the rules that differ between languages.
  *
@@ -1577,6 +1680,8 @@ type ExtFn = (data: Json) => Result;
  * - `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".
+ * - `combine`: the error of two or more failed parts of an operation, a `record` or a `list`. With it, each part
+ *   evaluates, and one failed part gives its own error. Without it, the first error stops the evaluation.
  */
 interface FormulaProfile {
   readonly ops?: Readonly<Record<string, OpFn>> | ((name: string) => OpFn | undefined);
@@ -1588,6 +1693,7 @@ interface FormulaProfile {
   readonly omit?: (error: EvalError) => boolean;
   readonly missing?: (value: unknown) => boolean;
   readonly check?: (value: unknown, op: string) => Result | undefined;
+  readonly combine?: (errors: readonly EvalError[]) => EvalError;
 }
 /** The value of a name whose binding failed. A reference to the name gives the error. */
 export declare class Held {
@@ -1637,5 +1743,5 @@ 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 };
+export type { Alias, AllOptions, Answer, AskOptions, Cap, CapsRule, 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