@mark1russell7/coeval 0.0.0-stage → 0.2.0

package/src/classify.ts

@@ -0,0 +1,54 @@
+import { type Envelope, type Json, field, isRecord, typed } from "./doc.ts";
+
+/** A shape proposes a kind for each document that has all of its fields. */
+export interface Shape {
+  readonly name: string;
+  readonly fields: readonly string[];
+  readonly kind: string;
+}
+
+/** The result of a classification. */
+export interface Classification {
+  /** The kind of the one most specific shape. */
+  readonly kind?: string;
+  /** The names of the most specific shapes. */
+  readonly candidates: readonly string[];
+  /** `no-match`: no shape applies. `ambiguous`: two or more shapes match equally well. */
+  readonly error?: "no-match" | "ambiguous";
+}
+
+function isStrictSuperset(larger: readonly string[], smaller: readonly string[]): boolean {
+  return larger.length > smaller.length && smaller.every((name) => larger.includes(name));
+}
+
+/**
+ * This function proposes a kind for a value without a type, from the fields that the value has.
+ * A shape applies when the value has each field of the shape. The most specific shapes are the ones that
+ * no other applicable shape contains. A host uses a classifier when data comes in, and then tags the data.
+ * The ladder does not call a classifier.
+ *
+ * @param shapes - The shapes to examine.
+ * @param value - The value without a type.
+ * @returns The proposed kind, or an error with the candidates.
+ */
+export function classify(shapes: readonly Shape[], value: Json): Classification {
+  const applicable = isRecord(value)
+    ? shapes.filter((shape) => shape.fields.every((name) => field(value, name) !== undefined))
+    : [];
+  const best = applicable.filter((shape) => !applicable.some((other) => isStrictSuperset(other.fields, shape.fields)));
+  const candidates = best.map((shape) => shape.name);
+  const only = best.length === 1 ? best[0] : undefined;
+  if (only !== undefined) return { kind: only.kind, candidates };
+  return { candidates, error: best.length === 0 ? "no-match" : "ambiguous" };
+}
+
+/**
+ * This function puts a value in an envelope with a type. The value does not change.
+ *
+ * @param value - The value.
+ * @param kind - The name of the kind.
+ * @returns The envelope.
+ */
+export function tag(value: Json, kind: string): Envelope {
+  return typed(kind, value);
+}

package/src/context.ts

@@ -0,0 +1,193 @@
+import type { Envelope } from "./doc.ts";
+import type { Side } from "./ladder.ts";
+
+/** The parts of a context. A term can reach outside itself only through these parts. */
+export const PARTS = ["self", "names", "world", "event", "caps"] as const;
+
+/** One part of a context. */
+export type Part = (typeof PARTS)[number];
+
+/** The description of one part of a context. */
+export interface PartInfo {
+  readonly part: Part;
+  readonly title: string;
+  /** What a reference through this part reaches. */
+  readonly reaches: string;
+  /** The direction in which a reference through this part goes. */
+  readonly direction: string;
+}
+
+/** The descriptions of the parts, in the order of `PARTS`. */
+export const PART_INFO: readonly PartInfo[] = [
+  {
+    part: "self",
+    title: "Self",
+    reaches: "A position in a structure: the node itself, its parent, its children or its siblings.",
+    direction: "Any direction that a move permits: up, down or to the side.",
+  },
+  {
+    part: "names",
+    title: "Names",
+    reaches: "The values that a binding gives: a let, a parameter, or the result of an earlier step.",
+    direction: "Back, to the place where the program binds the name.",
+  },
+
+  {
+    part: "world",
+    title: "World",
+    reaches: "The stored documents and collections, by an absolute ID or by a query.",
+    direction: "Out, to the store.",
+  },
+  {
+    part: "event",
+    title: "Event",
+    reaches: "The trigger of a run: the event and its values.",
+    direction: "From the past, to the run that the event starts.",
+  },
+  {
+    part: "caps",
+    title: "Capabilities",
+    reaches: "The effects that a term can cause. A part of the term gets the same set or a smaller set.",
+    direction: "Down, and only smaller.",
+  },
+];
+
+/**
+ * What a construct gives the parts of its body, for one part of the context.
+ *
+ * - `same`: the parts get the same value.
+ * - `extends`: the parts get the value with more names.
+ * - `moves`: the parts get a new position.
+ * - `narrows`: the parts get a smaller set.
+ * - `sets`: the parts get a new value.
+ * - `none`: the parts get nothing.
+ */
+export type Give = "same" | "extends" | "moves" | "narrows" | "sets" | "none";
+
+/** How a construct uses one part of the context. */
+export interface Use {
+  readonly reads: boolean;
+  readonly gives: Give;
+  readonly note: string;
+}
+
+/** A construct of a language, and how it uses each part of the context. */
+export interface Construct {
+  readonly id: string;
+  readonly title: string;
+  readonly side: Side;
+  readonly summary: string;
+  readonly example: Envelope;
+  readonly uses: Readonly<Record<Part, Use>>;
+}
+
+const NONE: Use = { reads: false, gives: "none", note: "It does not use this part." };
+
+/** Six constructs that show the range of the context. */
+export const CONSTRUCTS: readonly Construct[] = [
+  {
+    id: "formula",
+    title: "Formula",
+    side: "derive",
+    summary: "A pure formula that gives a value at one position of a structure.",
+    example: {
+      type: "let",
+      value: {
+        bind: { gap: 8 },
+        body: { type: ["ops", "add"], value: [{ type: "ref", value: ["self", "parent", "width"] }, { type: "ref", value: ["names", "gap"] }] },
+      },
+    },
+    uses: {
+      names: { reads: true, gives: "extends", note: "A let binds names for its body." },
+      self: { reads: true, gives: "moves", note: "A move reads the parent. An axis moves self to each target." },
+      world: NONE,
+      event: NONE,
+      caps: { reads: false, gives: "none", note: "A formula causes no effect, thus its parts get no capability." },
+    },
+  },
+  {
+    id: "sequence",
+    title: "Sequence",
+    side: "run",
+    summary: "A list of steps. A step can read the result of each earlier step by its name.",
+    example: {
+      type: "seq",
+      value: [
+        { type: ["store", "find"], value: { match: { board: "b1" } }, name: "cards" },
+        { type: ["store", "patch"], value: { ids: { type: "ref", value: ["names", "cards", "ids"] }, set: { done: true } } },
+      ],
+    },
+    uses: {
+      names: { reads: true, gives: "extends", note: "The result of each step is a name for the later steps." },
+      self: NONE,
+      world: { reads: true, gives: "same", note: "A step reads and writes the store through a procedure." },
+      event: { reads: false, gives: "same", note: "The steps get the event of the run without a change." },
+      caps: { reads: true, gives: "narrows", note: "A nested call gets the same capabilities or fewer." },
+    },
+  },
+  {
+    id: "node",
+    title: "Tree node",
+    side: "derive",
+    summary: "A node of a document tree. Its data and its box go down to its children.",
+    example: {
+      type: "node",
+      value: { data: { title: "Notes" }, children: [{ type: "text", value: { type: "ref", value: ["names", "title"] } }] },
+    },
+    uses: {
+      names: { reads: true, gives: "extends", note: "The data of the node becomes a name for its children." },
+      self: { reads: true, gives: "moves", note: "Each child becomes self for its own part." },
+      world: { reads: true, gives: "same", note: "A node can show stored documents." },
+      event: NONE,
+      caps: NONE,
+    },
+  },
+  {
+    id: "rule",
+    title: "Layout rule",
+    side: "derive",
+    summary: "A rule that gives the box of a child from the box of its parent.",
+    example: { type: ["layouts", "stack"], value: { gap: 8 } },
+    uses: {
+      names: { reads: true, gives: "none", note: "The rule reads its parameters." },
+      self: { reads: true, gives: "none", note: "The rule reads the box of the parent and the key of the child." },
+      world: NONE,
+      event: NONE,
+      caps: NONE,
+    },
+  },
+  {
+    id: "handler",
+    title: "Event handler",
+    side: "run",
+    summary: "A run that an event starts. It holds a sequence as data until the event comes.",
+    example: {
+      type: "on",
+      value: {
+        event: "click",
+        run: { type: "seq", value: [{ type: ["card", "toggle"], value: { id: { type: "ref", value: ["event", "target"] } } }] },
+      },
+    },
+    uses: {
+      names: { reads: true, gives: "same", note: "The handler reads the names of its place." },
+      self: { reads: true, gives: "same", note: "The handler knows the node that got the event." },
+      world: { reads: true, gives: "same", note: "The run reads and writes the store." },
+      event: { reads: true, gives: "sets", note: "The handler gives the event to its run." },
+      caps: { reads: true, gives: "narrows", note: "The run gets only the capabilities of the handler." },
+    },
+  },
+  {
+    id: "query",
+    title: "Query",
+    side: "derive",
+    summary: "A selection of stored documents. A storage adapter decides where it runs.",
+    example: { type: "query", value: { collection: "cards", match: { board: { type: "ref", value: ["names", "board"] } } } },
+    uses: {
+      names: { reads: true, gives: "none", note: "The query reads its parameters." },
+      self: NONE,
+      world: { reads: true, gives: "none", note: "The query reads one collection." },
+      event: NONE,
+      caps: NONE,
+    },
+  },
+];

package/src/deref.ts

@@ -0,0 +1,401 @@
+import { type Envelope, type Json, type JsonRecord, type Key, type TypeRef, field, isEnvelope, isKey, isRecord, typePath } from "./doc.ts";
+import { type World, entriesAsJson, lookupKind } from "./world.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 const THING: unique symbol = Symbol.for("coeval.thing") as never;
+
+/**
+ * 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`.
+ */
+export 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. */
+export type Thing = unknown;
+
+/**
+ * This function tells if a thing is a host thing.
+ *
+ * @param thing - The thing.
+ * @returns `true` for a host thing.
+ */
+export function isHostThing(thing: unknown): thing is HostThing {
+  return typeof thing === "object" && thing !== null && (thing as Partial<HostThing>)[THING] === true;
+}
+
+/** The roots of a context. Each path starts with one of them. */
+export const ROOTS = ["self", "names", "world", "event", "caps"] as const;
+
+/** One root of a context. */
+export 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.
+ */
+export 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.
+ */
+export 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. */
+export type DerefCode = (doc: Envelope, key: Key) => Thing | undefined;
+
+/** The result of a step document: what it reached, or the reason of a failure. */
+export 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`. */
+export 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. */
+export 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.
+ */
+export interface Navigator {
+  readonly world: World;
+  readonly derefs?: Readonly<Record<string, DerefCode>>;
+  readonly walkers?: Readonly<Record<string, Walker>>;
+  readonly plain?: boolean;
+  readonly roots?: readonly Root[];
+}
+
+/** The way that one hop of a path was answered. */
+export type HopBy = "root" | "own" | "kind" | "default" | "step" | "collapse";
+
+/** One hop of a path: the step, what it reached, and who answered it. */
+export interface Hop {
+  readonly step: Json;
+  readonly thing: Thing;
+  readonly by: HopBy;
+}
+
+/** The codes of a failed resolution. */
+export 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. */
+export 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. */
+export interface ResolveOptions {
+  /** `false`: do not record the hops. The default is `true`. */
+  readonly hops?: boolean;
+}
+
+function entryOf(verbs: Readonly<Record<string, string>> | undefined, verb: string): string | undefined {
+  return verbs !== undefined && Object.hasOwn(verbs, verb) ? verbs[verb] : undefined;
+}
+
+/** The own fields of a value: the items and the length of a list, and the own properties of an object. */
+function plainStep(thing: unknown, key: Key): { readonly found: true; readonly value: unknown } | undefined {
+  if (Array.isArray(thing)) {
+    if (key === "length") return { found: true, value: thing.length };
+    const index = typeof key === "number" ? key : /^\d+$/.test(key) ? Number(key) : -1;
+    return index >= 0 && index < thing.length ? { found: true, value: (thing as readonly unknown[])[index] } : undefined;
+  }
+  if (typeof thing === "object" && thing !== null) {
+    const name = String(key);
+    return Object.hasOwn(thing, name) ? { found: true, value: (thing as Readonly<Record<string, unknown>>)[name] } : undefined;
+  }
+  return undefined;
+}
+
+/**
+ * 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 function derefStep(nav: Navigator, thing: Thing, key: Key): { readonly thing: Thing; readonly by: HopBy } | undefined {
+  if (isHostThing(thing)) {
+    const reached = thing.deref(key);
+    return reached === undefined ? undefined : { thing: reached, by: "own" };
+  }
+  if (nav.plain !== true && isEnvelope(thing)) {
+    const envelope = thing as JsonRecord & Envelope;
+    const ownEntries = field(envelope, "own");
+    const own = isRecord(ownEntries) ? entryOf(ownEntries as Readonly<Record<string, string>>, "deref") : undefined;
+    const ownCode = own === undefined ? undefined : nav.derefs?.[own];
+    if (ownCode !== undefined) {
+      const reached = ownCode(envelope, key);
+      return reached === undefined ? undefined : { thing: reached, by: "own" };
+    }
+    const found = lookupKind(nav.world, envelope.type);
+    const name = found.ok ? entryOf(found.kind.verbs, "deref") : undefined;
+    const code = name === undefined ? undefined : nav.derefs?.[name];
+    if (code !== undefined) {
+      const reached = code(envelope, key);
+      return reached === undefined ? undefined : { thing: reached, by: "kind" };
+    }
+    const reached = plainStep(envelope.value, key);
+    return reached === undefined ? undefined : { thing: reached.value, by: "default" };
+  }
+  const reached = plainStep(thing, key);
+  return reached === undefined ? undefined : { thing: reached.value, by: "default" };
+}
+
+/**
+ * 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 function isRef(thing: unknown): thing is Envelope & { readonly value: readonly Json[] } {
+  if (!isEnvelope(thing) || !Array.isArray(thing.value)) return false;
+  const path = typePath(thing.type as TypeRef);
+  return path !== undefined && path.length === 1 && path[0] === "ref";
+}
+
+const worlds = new WeakMap<World, 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 function worldThing(world: World): Json {
+  let thing = worlds.get(world);
+  if (thing === undefined) {
+    thing = entriesAsJson(world.kinds);
+    worlds.set(world, thing);
+  }
+  return thing;
+}
+
+/**
+ * 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 function context(parts: Partial<Context> = {}): Context {
+  return {
+    self: parts.self ?? null,
+    names: parts.names ?? {},
+    world: parts.world ?? null,
+    event: parts.event ?? null,
+    caps: parts.caps ?? [],
+  };
+}
+
+const MAX_COLLAPSE = 64;
+const NO_HOPS: readonly Hop[] = Object.freeze([]);
+
+/** A value that can be a reference document: a record with the type `ref`. The full check comes after. */
+function mayBeRef(thing: unknown): boolean {
+  return typeof thing === "object" && thing !== null && (thing as { readonly type?: unknown }).type === "ref";
+}
+
+/**
+ * This function resolves the common path without a record of hops: a root, then keys, through plain values. It
+ * gives `undefined` when the path needs the full algorithm. Examples are a host thing, an envelope, a reference to
+ * follow, a step document and a failure (for its exact reason).
+ */
+function resolveQuick(nav: Navigator, ctx: Context, path: readonly unknown[]): Resolution | undefined {
+  const root = path[0];
+  if (root !== "names" && root !== "self" && root !== "event") return undefined;
+  if (nav.roots !== undefined && !(nav.roots as readonly string[]).includes(root)) return undefined;
+  let here: unknown = ctx[root];
+  const plain = nav.plain === true;
+  for (let index = 1; index < path.length; index += 1) {
+    if (typeof here !== "object" || here === null) return undefined;
+    if (!plain && mayBeRef(here)) return undefined;
+    if ((here as Partial<HostThing>)[THING] === true) return undefined;
+    const step = path[index];
+    if (Array.isArray(here)) {
+      if (typeof step !== "number" || !Number.isInteger(step) || step < 0 || step >= here.length) return undefined;
+      here = (here as readonly unknown[])[step];
+      continue;
+    }
+    if (typeof step !== "string" || !Object.hasOwn(here, step)) return undefined;
+    if (!plain && isEnvelope(here)) return undefined;
+    here = (here as Readonly<Record<string, unknown>>)[step];
+  }
+  if (!plain && mayBeRef(here)) return undefined;
+  return { ok: true, thing: here, hops: NO_HOPS };
+}
+
+/**
+ * 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 function resolve(nav: Navigator, ctx: Context, path: readonly unknown[], options: ResolveOptions = {}): Resolution {
+  if (options.hops === false) {
+    const quick = resolveQuick(nav, ctx, path);
+    if (quick !== undefined) return quick;
+  }
+  const hops: Hop[] | undefined = options.hops === false ? undefined : [];
+  const done = hops ?? NO_HOPS;
+  const failed = (code: ResolveCode, reason: string): Resolution => ({ ok: false, code, reason, hops: done });
+  let collapses = 0;
+
+  const collapse = (thing: Thing): Resolution => {
+    let here = thing;
+    if (nav.plain === true) return { ok: true, thing: here, hops: done };
+    while (isRef(here)) {
+      collapses += 1;
+      if (collapses > MAX_COLLAPSE) return failed("#CYCLE!", "The references form a cycle.");
+      const inner = walk(here.value);
+      if (!inner.ok) return inner;
+      here = inner.thing;
+      hops?.push({ step: "collapse", thing: here, by: "collapse" });
+    }
+    return { ok: true, thing: here, hops: done };
+  };
+
+  const walk = (steps: readonly unknown[]): Resolution => {
+    const root = steps[0];
+    if (typeof root !== "string" || !(ROOTS as readonly string[]).includes(root)) {
+      return failed("#REF!", `A path starts with a root: ${ROOTS.join(", ")}.`);
+    }
+    if (nav.roots !== undefined && !(nav.roots as readonly string[]).includes(root)) {
+      return failed("#REF!", `The root ${root} is not open here. The open roots are ${nav.roots.join(", ")}.`);
+    }
+    let here: Thing = ctx[root as Root];
+    hops?.push({ step: root, thing: here, by: "root" });
+    const first = collapse(here);
+    if (!first.ok) return first;
+    here = first.thing;
+    for (let index = 1; index < steps.length; index += 1) {
+      const step = steps[index];
+      if (isHostThing(here) && here.resolve !== undefined && steps.slice(index).every(isKey)) {
+        const keys = steps.slice(index) as readonly Key[];
+        const reached = here.resolve(keys);
+        if (reached === undefined) return failed("#N/A", `The path ${keys.join(".")} reaches nothing.`);
+        hops?.push({ step: keys as readonly Json[], thing: reached.thing, by: "own" });
+        return collapse(reached.thing);
+      }
+      if (isKey(step)) {
+        const reached = derefStep(nav, here, step);
+        if (reached === undefined) {
+          if (root === "names" && index === 1) return failed("#NAME?", `The context has no name ${String(step)}.`);
+          return failed("#N/A", `The step ${String(step)} reaches nothing.`);
+        }
+        hops?.push({ step, thing: reached.thing, by: reached.by });
+        here = reached.thing;
+      } else {
+        const envelope = isEnvelope(step) ? step : undefined;
+        const found = envelope === undefined ? undefined : lookupKind(nav.world, envelope.type);
+        const name = found?.ok === true ? entryOf(found.kind.verbs, "step") : undefined;
+        const walker = name === undefined ? undefined : nav.walkers?.[name];
+        if (envelope === undefined || walker === undefined) {
+          return failed("#STEP?", "A step is a key, or a document of a kind with the verb step.");
+        }
+        const result = walker({
+          data: envelope.value,
+          here,
+          context: ctx,
+          deref: (thing, key) => derefStep(nav, thing, key)?.thing,
+        });
+        if (!result.ok) return failed("#N/A", result.reason);
+        hops?.push({ step: envelope as Json, thing: result.thing, by: "step" });
+        here = result.thing;
+      }
+      const next = collapse(here);
+      if (!next.ok) return next;
+      here = next.thing;
+    }
+    return { ok: true, thing: here, hops: done };
+  };
+
+  if (path.length === 0) return failed("#REF!", "A path has at least one step: its root.");
+  return walk(path);
+}
+
+/**
+ * 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 function valueOfThing(thing: Thing): unknown {
+  return isHostThing(thing) ? thing.toJson() : thing;
+}