@mark1russell7/coeval 0.0.0-stage → 0.2.0

package/src/static.ts

@@ -0,0 +1,364 @@
+import { type Envelope, type Json, type Key, isEnvelope, isKey, isRecord, typeName } from "./doc.ts";
+import { type Kind, type NamesSource, type ScopeRule, type World, lookupKind } from "./world.ts";
+import { ask } from "./ladder.ts";
+import { type PartSlot, pathMatches, splitParts } from "./parts.ts";
+import { type Cap, type Root, ROOTS, isRef } from "./deref.ts";
+import type { ErrorCode } from "./errors.ts";
+import { type Machine, permits } from "./evaluate.ts";
+
+/** One document that a walk visits. */
+export interface DocVisit {
+  /** The keys from the root document to this document, through the parts. It is the place of an error. */
+  readonly place: readonly Key[];
+  /** The keys from the root JSON value to this document. A change at this path changes this document. */
+  readonly at: readonly Key[];
+  /** The document. A bare value has the type that its position declares. */
+  readonly doc: Envelope;
+  /** `true` when the type came from the position and not from an envelope. */
+  readonly declared: boolean;
+  /** The kind of the document, when the world has it. */
+  readonly kind?: Kind;
+  /** The keys of the kind after each alias. */
+  readonly typePath?: readonly Key[];
+  /** The number of documents around this document. The root has 0. */
+  readonly depth: number;
+  /** The names that the kinds around this document bind for it. */
+  readonly names: ReadonlySet<string>;
+  /** The names that a sequence around this document binds only for the parts after it. */
+  readonly later: ReadonlySet<string>;
+}
+
+/** A position that a walk cannot read as a document. */
+export interface WalkProblem {
+  readonly place: readonly Key[];
+  readonly at: readonly Key[];
+  readonly code: "#PART?" | "#VALUE!";
+  readonly reason: string;
+}
+
+/** The options of a walk. */
+export interface WalkOptions {
+  /** The type of a bare root value. */
+  readonly declaredType?: string;
+  /** The names that the host binds at the root. */
+  readonly names?: readonly string[];
+  /**
+   * This function gets each position that is not a document.
+   *
+   * @param problem - The position and the reason.
+   */
+  readonly problem?: (problem: WalkProblem) => void;
+}
+
+function valueAt(value: unknown, path: readonly Key[]): unknown {
+  let here: unknown = value;
+  for (const key of path) {
+    if (Array.isArray(here)) here = here[Number(key)];
+    else if (isRecord(here) && Object.hasOwn(here, String(key))) here = here[String(key)];
+    else return undefined;
+  }
+  return here;
+}
+
+function headerName(item: Json): string | undefined {
+  return isEnvelope(item) && typeof (item as { readonly name?: unknown }).name === "string" ? (item as { readonly name: string }).name : undefined;
+}
+
+function namesOf(source: NamesSource, value: unknown, covered: readonly PartSlot[]): readonly string[] {
+  if ("fixed" in source) return source.fixed;
+  if ("keysAt" in source) {
+    const at = valueAt(value, source.keysAt);
+    return isRecord(at) ? Object.keys(at) : [];
+  }
+  if ("listAt" in source) {
+    const at = valueAt(value, source.listAt);
+    return Array.isArray(at) ? (at as readonly unknown[]).filter((item): item is string => typeof item === "string") : [];
+  }
+  if ("textAt" in source) {
+    const at = valueAt(value, source.textAt);
+    if (typeof at === "string") return [at];
+    return source.otherwise === undefined ? [] : [source.otherwise];
+  }
+  return covered.map((slot) => headerName(slot.item)).filter((name): name is string => name !== undefined);
+}
+
+/** The names that the scope rules of a kind give each part, and the names that only later parts see. */
+function scopesOf(rules: readonly ScopeRule[] | undefined, value: unknown, slots: readonly PartSlot[]): { readonly sees: readonly (readonly string[])[]; readonly later: readonly (readonly string[])[] } {
+  const sees: string[][] = slots.map(() => []);
+  const later: string[][] = slots.map(() => []);
+  for (const rule of rules ?? []) {
+    const covered = slots.map((slot, index) => ({ slot, index })).filter(({ slot }) => rule.in.some((pattern) => pathMatches(slot.path, pattern)));
+    if (rule.sequential !== true) {
+      const names = namesOf(rule.names, value, covered.map(({ slot }) => slot));
+      for (const { index } of covered) sees[index]?.push(...names);
+      continue;
+    }
+    if ("headers" in rule.names) {
+      covered.forEach(({ index }, position) => {
+        const before = covered.slice(0, position).map(({ slot }) => headerName(slot.item)).filter((name): name is string => name !== undefined);
+        const after = covered.slice(position).map(({ slot }) => headerName(slot.item)).filter((name): name is string => name !== undefined);
+        sees[index]?.push(...before);
+        later[index]?.push(...after);
+      });
+      continue;
+    }
+    const names = namesOf(rule.names, value, covered.map(({ slot }) => slot));
+    covered.forEach(({ index }, position) => {
+      if (position > 0) sees[index]?.push(...names);
+      else later[index]?.push(...names);
+    });
+  }
+  return { sees, later };
+}
+
+/**
+ * This function visits each document of a document: the root and each part at each depth, by the contracts of the
+ * kinds. A part of a kind that the world does not have is not visited. The walk uses no stack of the host for the
+ * depth, thus a deep document cannot overflow it.
+ *
+ * @param world - The world of the kinds.
+ * @param doc - The document, as JSON.
+ * @param visit - The function that gets each document. It gives `"skip"` to not visit the parts of a document.
+ * @param options - The type of a bare root value, the names of the host, and a function for the problems.
+ */
+export function walk(world: World, doc: unknown, visit: (visit: DocVisit) => void | "skip", options: WalkOptions = {}): void {
+  interface Item {
+    readonly value: unknown;
+    readonly place: readonly Key[];
+    readonly at: readonly Key[];
+    readonly declared: string | undefined;
+    readonly depth: number;
+    readonly names: ReadonlySet<string>;
+    readonly later: ReadonlySet<string>;
+  }
+  const stack: Item[] = [
+    { value: doc, place: [], at: [], declared: options.declaredType, depth: 0, names: new Set(options.names ?? []), later: new Set() },
+  ];
+  while (stack.length > 0) {
+    const item = stack.pop() as Item;
+    const envelope = isEnvelope(item.value) ? (item.value as Envelope) : undefined;
+    if (envelope === undefined && item.declared === undefined) {
+      options.problem?.({ place: item.place, at: item.at, code: "#PART?", reason: "The value has no envelope, and its position declares no type." });
+      continue;
+    }
+    const doc: Envelope = envelope ?? { type: item.declared ?? "?", value: item.value as Json };
+    const found = lookupKind(world, doc.type);
+    const kind = found.ok ? found.kind : undefined;
+    const answer = visit({
+      place: item.place,
+      at: item.at,
+      doc,
+      declared: envelope === undefined,
+      ...(kind === undefined ? {} : { kind, typePath: found.ok ? found.path : [] }),
+      depth: item.depth,
+      names: item.names,
+      later: item.later,
+    });
+    if (answer === "skip" || kind === undefined) continue;
+    const split = splitParts(kind.parts, doc.value);
+    if (!split.ok) {
+      const at = split.at.length === 0 ? "" : ` (at ${split.at.join(".")})`;
+      options.problem?.({ place: item.place, at: item.at, code: "#VALUE!", reason: `${split.reason}${at} The kind is ${typeName(doc.type)}.` });
+      continue;
+    }
+    const { sees, later } = scopesOf(kind.scope, doc.value, split.parts);
+    const base = envelope === undefined ? item.at : [...item.at, "value"];
+    for (let index = split.parts.length - 1; index >= 0; index -= 1) {
+      const slot = split.parts[index] as PartSlot;
+      const extra = sees[index] ?? [];
+      const hidden = later[index] ?? [];
+      stack.push({
+        value: slot.item,
+        place: [...item.place, ...slot.path],
+        at: [...base, ...slot.path],
+        declared: slot.of,
+        depth: item.depth + 1,
+        names: extra.length === 0 ? item.names : new Set([...item.names, ...extra]),
+        later: hidden.length === 0 ? item.later : new Set([...item.later, ...hidden]),
+      });
+    }
+  }
+}
+
+/** One reference of a document. */
+export interface RefUse {
+  /** The place of the reference document, through the parts. */
+  readonly place: readonly Key[];
+  /** The keys from the root JSON value to the reference document. */
+  readonly at: readonly Key[];
+  /** The path of the reference: its root and its steps. */
+  readonly path: readonly Json[];
+  readonly root: string;
+  /** `false` when a kind around the reference binds its first name. A reference to another root is free. */
+  readonly free: boolean;
+}
+
+/**
+ * This function finds each reference of a document: each document of the type `ref` that a walk reaches. A
+ * reference to a name that a kind around it binds is not free. The others are what the document reads from
+ * outside: its dependencies.
+ *
+ * @param world - The world of the kinds.
+ * @param doc - The document, as JSON.
+ * @param options - The type of a bare root value. The names of the host do not change the result.
+ * @returns The references, in the order of the document.
+ */
+export function refsOf(world: World, doc: unknown, options: WalkOptions = {}): readonly RefUse[] {
+  const out: RefUse[] = [];
+  // The walk gets no names of the host: a name that the host binds is a dependency, thus its reference is free.
+  const { names: _host, ...rest } = options;
+  walk(
+    world,
+    doc,
+    (v) => {
+      if (!isRef(v.doc)) return undefined;
+      const path = v.doc.value as readonly Json[];
+      const root = typeof path[0] === "string" ? path[0] : "";
+      const first = path[1];
+      const bound = root === "names" && isKey(first) && v.names.has(String(first));
+      out.push({ place: v.place, at: v.at, path, root, free: !bound });
+      return "skip";
+    },
+    rest,
+  );
+  return out;
+}
+
+function setAt(value: unknown, path: readonly Key[], next: unknown): unknown {
+  if (path.length === 0) return next;
+  const [key, ...rest] = path as [Key, ...Key[]];
+  if (Array.isArray(value)) {
+    const copy = [...value];
+    copy[Number(key)] = setAt(value[Number(key)], rest, next);
+    return copy;
+  }
+  const record = (isRecord(value) ? value : {}) as Readonly<Record<string, unknown>>;
+  const copy: Record<string, unknown> = {};
+  for (const name of Object.keys(record)) Object.defineProperty(copy, name, { value: record[name], enumerable: true, writable: true, configurable: true });
+  Object.defineProperty(copy, String(key), { value: setAt(record[String(key)], rest, next), enumerable: true, writable: true, configurable: true });
+  return copy;
+}
+
+/**
+ * This function changes the free references of a document. The document is not changed: the function gives a new
+ * document that shares each part without a change.
+ *
+ * @param world - The world of the kinds.
+ * @param doc - The document, as JSON.
+ * @param change - The function that gives the new document of a reference, or `undefined` to keep it.
+ * @param options - The type of a bare root value, and the names that the host binds at the root.
+ * @returns The new document.
+ */
+export function mapRefs(world: World, doc: unknown, change: (use: RefUse) => unknown, options: WalkOptions = {}): unknown {
+  let out = doc;
+  for (const use of refsOf(world, doc, options)) {
+    if (!use.free) continue;
+    const next = change(use);
+    if (next !== undefined) out = setAt(out, use.at, next);
+  }
+  return out;
+}
+
+/** A problem that a check finds before a document runs. */
+export interface Issue {
+  readonly code: ErrorCode;
+  /** The keys from the root document to the document with the problem. */
+  readonly place: readonly Key[];
+  readonly reason: string;
+}
+
+/** The options of a check. */
+export interface CheckOptions {
+  /** The type of a bare root value. */
+  readonly declaredType?: string;
+  /** The names that the host binds at the root. `"any"` does not check the names. The default is no names. */
+  readonly names?: readonly string[] | "any";
+  /** The capabilities at the root. Without them, the check does not check the effects. */
+  readonly caps?: readonly Cap[];
+}
+
+/**
+ * This function checks a document before an evaluation, by the contracts of its kinds. It finds the problems
+ * that an evaluation finds when it reaches them:
+ *
+ * - `#KIND?`: a kind that the world does not have.
+ * - `#NOEVAL`: no evaluator.
+ * - `#VALUE!`: a value without the shape of its kind.
+ * - `#PART?`: a value without a type.
+ * - `#DEPTH!`: too much nesting.
+ * - `#REF!` and `#STEP?`: a bad path.
+ * - `#NAME?`: a name that nothing binds.
+ * - `#CAP!`: an effect that the capabilities do not permit.
+ *
+ * @param machine - The world and the code of the evaluators.
+ * @param doc - The document, as JSON.
+ * @param options - The type of a bare root value, the names of the host and the capabilities.
+ * @returns The problems, in the order of the document.
+ */
+export function check(machine: Machine, doc: unknown, options: CheckOptions = {}): readonly Issue[] {
+  const issues: Issue[] = [];
+  const maxDepth = machine.maxDepth ?? 1000;
+  const anyName = options.names === "any";
+  const roots: readonly string[] = machine.roots ?? ROOTS;
+  const has = (table: Readonly<Record<string, unknown>> | undefined, name: string): boolean => table !== undefined && Object.hasOwn(table, name);
+  walk(
+    machine.world,
+    doc,
+    (v) => {
+      if (v.depth > maxDepth) {
+        issues.push({ code: "#DEPTH!", place: v.place, reason: `The nesting is deeper than ${maxDepth} documents.` });
+        return "skip";
+      }
+      const header = v.declared ? {} : v.doc;
+      const answer = ask(machine.world, header, "eval", v.declared ? { declaredType: typeName(v.doc.type) } : {});
+      if (answer.error === "unknown-kind") {
+        issues.push({ code: "#KIND?", place: v.place, reason: `The world has no kind ${typeName(v.doc.type)}.` });
+        return "skip";
+      }
+      const name = answer.evaluator;
+      if (name === undefined || (!has(machine.evaluators, name) && !has(machine.runners, name))) {
+        issues.push({ code: "#NOEVAL", place: v.place, reason: `No rung gives an evaluator for ${typeName(v.doc.type)}.` });
+      }
+      if (options.caps !== undefined && v.kind?.effects !== undefined) {
+        const kinds: readonly (readonly Key[])[] = v.kind.effects === "type" ? [v.typePath ?? []] : v.kind.effects.map((kind) => kind.split("."));
+        for (const kind of kinds) {
+          if (!permits(options.caps, kind)) issues.push({ code: "#CAP!", place: v.place, reason: `The capabilities do not permit the effect ${kind.join(".")}.` });
+        }
+      }
+      if (!isRef(v.doc)) return undefined;
+      const path = v.doc.value as readonly Json[];
+      const root = path[0];
+      if (typeof root !== "string" || !(ROOTS as readonly string[]).includes(root)) {
+        issues.push({ code: "#REF!", place: v.place, reason: `A path starts with a root: ${ROOTS.join(", ")}.` });
+        return "skip";
+      }
+      if (!roots.includes(root)) {
+        issues.push({ code: "#REF!", place: v.place, reason: `The root ${root} is not open here. The open roots are ${roots.join(", ")}.` });
+      }
+      const first = path[1];
+      if (root === ("names" as Root) && !anyName && isKey(first) && !v.names.has(String(first))) {
+        const later = v.later.has(String(first));
+        issues.push({
+          code: "#NAME?",
+          place: v.place,
+          reason: later ? `The name ${String(first)} is bound by a later step.` : `Nothing binds the name ${String(first)}.`,
+        });
+      }
+      path.slice(1).forEach((step) => {
+        if (isKey(step)) return;
+        const found = isEnvelope(step) ? lookupKind(machine.world, step.type) : undefined;
+        const walker = found?.ok === true && Object.hasOwn(found.kind.verbs, "step") ? found.kind.verbs["step"] : undefined;
+        if (walker === undefined || !has(machine.walkers, walker)) {
+          issues.push({ code: "#STEP?", place: v.place, reason: "A step is a key, or a document of a kind with the verb step." });
+        }
+      });
+      return "skip";
+    },
+    {
+      ...(options.declaredType === undefined ? {} : { declaredType: options.declaredType }),
+      ...(Array.isArray(options.names) ? { names: options.names } : {}),
+      problem: (problem) => issues.push({ code: problem.code, place: problem.place, reason: problem.reason }),
+    },
+  );
+  return issues;
+}

package/src/stdlib.ts

@@ -0,0 +1,310 @@
+import { type Json, type Key, field, isRecord } from "./doc.ts";
+import { type Context, type Evaluator, type Machine, type Part, type Result, type RunPart, type Runner, type Steps, fail, ok } from "./evaluate.ts";
+import { type HostThing, type Thing, type Walker, THING, isHostThing, valueOfThing } from "./deref.ts";
+import type { World } from "./ladder.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 const STD_WORLD: World = {
+  kinds: {
+    number: { verbs: { eval: "data.number", view: "view.value" }, summary: "A number. Its value is the result." },
+    text: { verbs: { eval: "data.text", view: "view.value" }, summary: "A text. Its value is the result." },
+    bool: { verbs: { eval: "data.bool", view: "view.value" }, summary: "A truth value. Its value is the result." },
+    add: {
+      verbs: { eval: "math.add", view: "view.op" },
+      parts: { shape: "list", of: "number" },
+      summary: "The sum of its parts. A bare number in its list gets the type number.",
+    },
+    multiply: {
+      verbs: { eval: "math.multiply", view: "view.op" },
+      parts: { shape: "list", of: "number" },
+      summary: "The product of its parts.",
+    },
+    greater: {
+      verbs: { eval: "math.greater", view: "view.op" },
+      parts: { shape: "list", of: "number" },
+      summary: "True when the first part is greater than the second part.",
+    },
+    list: { verbs: { eval: "list.all", view: "view.op" }, parts: { shape: "list" }, summary: "The results of its parts, as a list." },
+    if: {
+      verbs: { eval: "control.if", view: "view.op" },
+      parts: { shape: "record", fields: ["test", "then", "else"] },
+      summary: "It evaluates the test, then only the branch that the test selects.",
+    },
+    ref: {
+      verbs: { eval: "ref.resolve", view: "view.ref" },
+      summary: "A path from a root of the context. Each step goes up the ladder of the verb deref.",
+    },
+    nearest: {
+      verbs: { step: "walk.nearest", view: "view.card" },
+      summary: "A step of a path: it follows a key again and again, until it reaches a node of a type.",
+    },
+    panel: {
+      verbs: { eval: "tree.node", view: "view.op" },
+      parts: { shape: "record", fields: ["width", "height", "children"], of: "number" },
+      summary: "A node of a tree. Its parts see it as self, and each node links to its parent.",
+    },
+    box: {
+      verbs: { eval: "tree.node", view: "view.op" },
+      parts: { shape: "record", fields: ["width", "height", "children"], of: "number" },
+      summary: "A node of a tree, as panel. A formula in a box can read the parent of the box.",
+    },
+    math: {
+      kinds: {
+        sum: { type: "ref", value: ["world", "add"] },
+        product: { type: "ref", value: ["world", "multiply"] },
+      },
+    },
+    seq: {
+      verbs: { eval: "control.seq", view: "view.seq" },
+      parts: { shape: "list" },
+      scope: [
+        { names: { headers: true }, in: [["*"]], sequential: true },
+        { names: { fixed: ["last"] }, in: [["*"]], sequential: true },
+      ],
+      summary: "Its steps, in order. The result of a named step is a name for the later steps.",
+    },
+    pure: {
+      verbs: { eval: "control.pure", view: "view.op" },
+      parts: { shape: "list" },
+      summary: "It evaluates its part without capabilities, thus an effect in it fails.",
+    },
+    log: {
+      verbs: { eval: "effect.log", view: "view.op" },
+      parts: { shape: "list", of: "text" },
+      side: "run",
+      summary: "It writes the result of its part to the log. This is an effect.",
+    },
+    write: {
+      verbs: { eval: "effect.write", view: "view.op" },
+      parts: { shape: "record", fields: ["value"] },
+      side: "run",
+      summary: "It writes the result of its part to the store, at its key. This is an effect.",
+    },
+  },
+  defaults: { view: "view.card" },
+};
+
+function isNumber(value: unknown): value is number {
+  return typeof value === "number" && Number.isFinite(value);
+}
+
+/** This function evaluates each part, collects the errors, and gives the values when no part failed. */
+function allValues(results: readonly Result[]): { readonly values: readonly unknown[] } | { readonly error: Result } {
+  const errors = results.filter((result) => !result.ok);
+  const first = errors[0];
+  if (first !== undefined && errors.length === 1) return { error: first };
+  if (errors.length > 1) return { error: fail("#ARGS", `${errors.length} parts failed.`) };
+  return { values: results.map((result) => (result.ok ? result.value : null)) };
+}
+
+function numbers(values: readonly unknown[], kind: string): readonly number[] | Result {
+  const bad = values.findIndex((value) => !isNumber(value));
+  if (bad !== -1) return fail("#VALUE!", `Part ${bad} of ${kind} is not a number.`);
+  return values.filter(isNumber);
+}
+
+function dataOf(type: "number" | "string" | "boolean"): Evaluator {
+  return ({ data }) =>
+    typeof data === type && (type !== "number" || isNumber(data))
+      ? ok(data)
+      : fail("#VALUE!", `The value must be a ${type === "string" ? "text" : type}.`);
+}
+
+/** The code of the evaluators of the standard world, by name. */
+export const STD_EVALUATORS: Readonly<Record<string, Evaluator>> = {
+  "data.number": dataOf("number"),
+  "data.text": dataOf("string"),
+  "data.bool": dataOf("boolean"),
+  "math.add": ({ parts }) => {
+    const all = allValues(parts.map((part) => part.evaluate()));
+    if ("error" in all) return all.error;
+    const values = numbers(all.values, "add");
+    return Array.isArray(values) ? ok(values.reduce((sum, value) => sum + value, 0)) : (values as Result);
+  },
+  "math.multiply": ({ parts }) => {
+    const all = allValues(parts.map((part) => part.evaluate()));
+    if ("error" in all) return all.error;
+    const values = numbers(all.values, "multiply");
+    return Array.isArray(values) ? ok(values.reduce((product, value) => product * value, 1)) : (values as Result);
+  },
+  "math.greater": ({ parts }) => {
+    if (parts.length !== 2) return fail("#VALUE!", "greater needs exactly two parts.");
+    const all = allValues(parts.map((part) => part.evaluate()));
+    if ("error" in all) return all.error;
+    const values = numbers(all.values, "greater");
+    if (!Array.isArray(values)) return values as Result;
+    const [a, b] = values as readonly number[];
+    return ok((a ?? 0) > (b ?? 0));
+  },
+  "ref.resolve": ({ data, resolve }) => {
+    if (!Array.isArray(data) || data.length === 0) {
+      return fail("#VALUE!", "The value of ref is a path: a list that starts with a root, for example [\"names\", \"a\"].");
+    }
+    const found = resolve(data as readonly Json[]);
+    return found.ok ? ok(valueOfThing(found.thing)) : fail(found.code, found.reason);
+  },
+  "tree.node": (input) => treeNode(input.parts, input.context, input.kind),
+};
+
+/**
+ * This function evaluates a node of a tree. The node is a host thing. A step `parent` reaches the node that holds
+ * it. A step with the name of a part evaluates that part on demand, one time. Each part sees the node as self.
+ */
+function treeNode(parts: readonly Part[], context: Context, type: string): Result {
+  const memo = new Map<string, Result>();
+  const read = (key: string): Result | undefined => {
+    const known = memo.get(key);
+    if (known !== undefined) return known;
+    const part = parts.find((item) => item.key === key);
+    if (part === undefined) return undefined;
+    const result = part.evaluate({ ...context, self: me });
+    memo.set(key, result);
+    return result;
+  };
+  const me: HostThing & { readonly type: string } = {
+    [THING]: true,
+    type,
+    label: `node ${type}`,
+    deref(key: Key): Thing | undefined {
+      if (key === "parent") return context.self;
+      if (key === "type") return type;
+      const result = read(String(key));
+      return result?.ok === true ? result.value : undefined;
+    },
+    toJson(): unknown {
+      const out: Record<string, unknown> = {};
+      for (const part of parts) {
+        const result = read(part.key);
+        out[part.key] = result?.ok === true ? result.value : null;
+      }
+      return out;
+    },
+  };
+  const out: Record<string, unknown> = {};
+  for (const part of parts) {
+    const result = read(part.key);
+    if (result === undefined) continue;
+    if (!result.ok) return result;
+    out[part.key] = result.value;
+  }
+  return ok(out);
+}
+
+/** The options of a walker `nearest`. */
+export interface NearestOptions {
+  /**
+   * This function tells if a node has the wanted type. The default compares the field `type` of a host thing.
+   *
+   * @param node - The node that the walk reached.
+   * @param wanted - The type that the step document asks for.
+   * @returns `true` when the node has the type.
+   */
+  readonly matches?: (node: Thing, wanted: Json | undefined) => boolean;
+  /** The most hops of one walk. The default is 256. */
+  readonly maxHops?: number;
+}
+
+function hostType(node: Thing, wanted: Json | undefined): boolean {
+  return isHostThing(node) && (node as { readonly type?: unknown }).type === wanted;
+}
+
+/**
+ * This function makes a walker `nearest`. The walker follows a key (the default is `parent`) until the node that it
+ * reaches has the wanted type. With `self: true`, the node where the walk starts is the first candidate. A node
+ * without that key ends the walk with an error.
+ *
+ * @param options - The test of a type and the most hops.
+ * @returns The walker.
+ */
+export function nearestWalker(options: NearestOptions = {}): Walker {
+  const matches = options.matches ?? hostType;
+  const maxHops = options.maxHops ?? 256;
+  return ({ data, here, deref }) => {
+    const follow = isRecord(data) && typeof field(data, "follow") === "string" ? String(field(data, "follow")) : "parent";
+    const wanted = isRecord(data) ? field(data, "type") : undefined;
+    const fromSelf = isRecord(data) && field(data, "self") === true;
+    let at: Thing | undefined = here;
+    for (let hops = 0; hops < maxHops; hops += 1) {
+      if (hops > 0 || !fromSelf) at = at === undefined || at === null ? undefined : deref(at, follow);
+      if (at === undefined || at === null) return { ok: false, reason: `No node of the type ${String(wanted)} is on the way.` };
+      if (matches(at, wanted)) return { ok: true, thing: at };
+    }
+    return { ok: false, reason: "The walk is too long." };
+  };
+}
+
+const nearest: Walker = nearestWalker();
+
+/** The walkers of the standard world, by name. */
+export const STD_WALKERS: Readonly<Record<string, Walker>> = { "walk.nearest": nearest };
+
+/** This function evaluates parts one after the other, and stops at the first error. */
+function* inOrder(parts: readonly RunPart[]): Generator<Promise<unknown>, { readonly values: readonly unknown[] } | { readonly error: Result }, unknown> {
+  const values: unknown[] = [];
+  for (const part of parts) {
+    const result = yield* part.evaluate();
+    if (!result.ok) return { error: result };
+    values.push(result.value);
+  }
+  return { values };
+}
+
+/**
+ * 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 const STD_RUNNERS: Readonly<Record<string, Runner>> = {
+  "control.seq": function* ({ parts, context }): Steps {
+    let names: Record<string, unknown> = { ...context.names };
+    let last: unknown = null;
+    for (const part of parts) {
+      const result = yield* part.evaluate({ ...context, names });
+      if (!result.ok) return result;
+      names = { ...names, last: result.value };
+      if (part.name !== undefined) names = { ...names, [part.name]: result.value };
+      last = result.value;
+    }
+    return ok(last);
+  },
+  "control.pure": function* ({ parts, context }) {
+    const only = parts[0];
+    if (only === undefined) return fail("#VALUE!", "pure needs one part.");
+    return yield* only.evaluate({ ...context, caps: [] });
+  },
+  "control.if": function* ({ parts }) {
+    const test = parts.find((part) => part.key === "test");
+    if (test === undefined) return fail("#VALUE!", "if needs a test.");
+    const chosen = yield* test.evaluate();
+    if (!chosen.ok) return chosen;
+    if (typeof chosen.value !== "boolean") return fail("#VALUE!", "The test of if must give a truth value.");
+    const branch = parts.find((part) => part.key === (chosen.value === true ? "then" : "else"));
+    return branch === undefined ? ok(null) : yield* branch.evaluate();
+  },
+  "list.all": function* ({ parts }) {
+    const all = yield* inOrder(parts);
+    return "error" in all ? all.error : ok(all.values);
+  },
+  "effect.log": function* ({ parts, effect }) {
+    const all = yield* inOrder(parts);
+    if ("error" in all) return all.error;
+    return yield* effect("log", all.values.length === 1 ? (all.values[0] ?? null) : all.values);
+  },
+  "effect.write": function* ({ parts, data, effect }) {
+    const key = isRecord(data) ? field(data, "key") : undefined;
+    if (typeof key !== "string") return fail("#VALUE!", "write needs a text key.");
+    const value = parts.find((part) => part.key === "value");
+    if (value === undefined) return fail("#VALUE!", "write needs a value.");
+    const result = yield* value.evaluate();
+    if (!result.ok) return result;
+    return yield* effect("write", { key, value: result.value });
+  },
+};
+
+/** The machine of the examples: the standard world, its evaluators, its runners and its walkers. */
+export const STD_MACHINE: Machine = { world: STD_WORLD, evaluators: STD_EVALUATORS, runners: STD_RUNNERS, walkers: STD_WALKERS };
+
+/** The capabilities of the examples at the root: the two effects of the standard world. */
+export const STD_CAPS: readonly string[] = ["log", "write"];