@mark1russell7/coeval 0.15.0 → 0.17.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package",
   "name": "@mark1russell7/coeval",
-  "version": "0.15.0",
+  "version": "0.17.0",
   "description": "coeval: the kernel of declarative languages. Documents in envelopes, a ladder that finds the evaluator, kind contracts, compiled plans, a static kit, a formula kit and a run side with capabilities.",
   "type": "module",
   "main": "./build/index.js",

package/src/agree.ts

@@ -1,10 +1,10 @@
 import { type Key, docEquals, equalWith } from "./doc.ts";
-import type { Context } from "./deref.ts";
+import { type Context, isHostThing } from "./deref.ts";
 import { type EvalError, type Result, isStackOverflow, thrown } from "./errors.ts";
-import { type Effect, type Journal, type Machine, type Perform, JOURNAL, evaluate, makeContext, prepare, run } from "./evaluate.ts";
+import { type Effect, type Machine, type Perform, type Read, JOURNAL, evaluate, makeContext, prepare, run, sharedCopy } from "./evaluate.ts";
 import { Held, isClosure } from "./formula.ts";
 import { type Definitions, reference, referenceRun } from "./reference.ts";
-import { type ReplaySettle, recorder, replayer } from "./replay.ts";
+import { type ReplaySettle, recorder, relay, replayer } from "./replay.ts";
 
 /**
  * A tier that `agree` compares with the plan.
@@ -14,9 +14,11 @@ import { type ReplaySettle, recorder, replayer } from "./replay.ts";
  * - `again`: a second evaluation of the same plan.
  * - `folds`: a second plan with the other choice of folds (PLAN.FOLD). It has no folds when the plan has them, and
  *   it has folds when the option `observe` stops the folds of the plan.
+ * - `fixed`: a plan that declares each name of plain data fixed (PLAN.FIXED). It evaluates with a frozen copy of
+ *   each such name, and then with the context of `agree`. `agreeRun` does not have this tier.
  * - `other`: the second tier of a language, from the option `other`.
  */
-export type Tier = "reference" | "traced" | "again" | "folds" | "other";
+export type Tier = "reference" | "traced" | "again" | "folds" | "fixed" | "other";
 
 /** What a second tier gives: its result, and its effects when it records them. */
 export interface TierResult {
@@ -45,8 +47,8 @@ export interface AgreeOptions {
   /** The definitional code of the compiled evaluators of the machine, for the reference. */
   readonly definitions?: Definitions;
   /**
-   * The tiers to compare with the plan. The default is the reference, the traced evaluation, a second evaluation and
-   * the plan with the other choice of folds.
+   * The tiers to compare with the plan. The default is the reference, the traced evaluation, a second evaluation, the
+   * plan with the other choice of folds and the plan with fixed names.
    */
   readonly tiers?: readonly Exclude<Tier, "other">[];
   /**
@@ -85,11 +87,20 @@ export interface AgreeOptions {
 }
 
 /** The tiers that `agree` compares when its options name none. */
-const DEFAULT_TIERS: readonly Exclude<Tier, "other">[] = /* @__PURE__ */ Object.freeze(["reference", "traced", "again", "folds"]);
+const DEFAULT_TIERS: readonly Exclude<Tier, "other">[] = /* @__PURE__ */ Object.freeze(["reference", "traced", "again", "folds", "fixed"]);
 
 /** The outcome of `agree`: the result of the plan, or the first tier that disagrees with it. */
 export type Agreement =
-  | { readonly ok: true; readonly result: Result; readonly effects: readonly Effect[] }
+  | {
+      readonly ok: true;
+      readonly result: Result;
+      readonly effects: readonly Effect[];
+      /**
+       * The free reads of the plan that `agreeRun` compared with the reference run (RUN.AGREES-READS). It is absent
+       * when no read compared, for example in `agree`.
+       */
+      readonly reads?: readonly Read[];
+    }
   | {
       readonly ok: false;
       readonly tier: Tier;
@@ -132,7 +143,8 @@ function sameInTiers(x: unknown, y: unknown): boolean | undefined {
 
 const CLOSURE = /* @__PURE__ */ Symbol.for("coeval.closure");
 
-function closureParams(fn: object): unknown {
+/** This function gives the parameters of a closure of `fn`, or `undefined` for another function. */
+export function closureParams(fn: object): unknown {
   return (fn as { readonly [CLOSURE]?: { readonly params: readonly string[] } })[CLOSURE]?.params;
 }
 
@@ -184,6 +196,57 @@ function effectsDiffer(a: readonly Effect[], b: readonly Effect[], options: Agre
   return undefined;
 }
 
+/**
+ * This function compares the plan with the tier `fixed` (PLAN.FIXED). The tier declares each name of plain data fixed,
+ * with a frozen copy of its value. It evaluates with these copies, thus the folds with fixed names give the result.
+ * Then it evaluates with the context of `agree`, thus the code without the fold gives the result. A fold moves the
+ * calls of the host to the compilation, thus only the result and the effects compare.
+ */
+function fixedDiffers(
+  machine: Machine,
+  doc: unknown,
+  context: Context,
+  result: Result,
+  effects: readonly Effect[],
+  given: { readonly declaredType?: string; readonly verb?: string; readonly perform?: Perform },
+  options: AgreeOptions,
+): { readonly other: Result; readonly reason: string } | undefined {
+  const { perform, ...declared } = given;
+  const held = fixedContext(context);
+  const plan = prepare(machine, doc, { ...declared, fixed: { names: held.fixed } });
+  for (const each of [held.context, context]) {
+    const tierEffects: Effect[] = [];
+    const other = plan.evaluate(each, { effects: tierEffects, ...(perform === undefined ? {} : { perform }) });
+    options.observe?.();
+    if (overflowed(result) || overflowed(other)) continue;
+    const reason = resultDiffers(result, other, options) ?? effectsDiffer(effects, tierEffects, options);
+    if (reason !== undefined) return { other, reason };
+  }
+  return undefined;
+}
+
+/**
+ * This function gives the context of the tier `fixed`. Each name of plain data gets a deeply frozen copy of its value,
+ * and the record of the fixed names holds the same copy. Each other name keeps its value.
+ */
+function fixedContext(context: Context): { readonly context: Context; readonly fixed: Readonly<Record<string, unknown>> } {
+  const given = context.names;
+  const names = Object.create(Object.getPrototypeOf(given) as object | null) as Record<string, unknown>;
+  const fixed = Object.create(null) as Record<string, unknown>;
+  for (const key of Reflect.ownKeys(given)) {
+    let field = Object.getOwnPropertyDescriptor(given, key) as PropertyDescriptor;
+    if (typeof key === "string" && "value" in field) {
+      const copy = sharedCopy(field.value);
+      if (copy !== undefined || field.value === undefined) {
+        Object.defineProperty(fixed, key, { value: copy, enumerable: true });
+        field = { ...field, value: copy };
+      }
+    }
+    Object.defineProperty(names, key, field);
+  }
+  return { context: { ...context, names }, fixed };
+}
+
 /**
  * This function evaluates a document with a plan and with other tiers, and compares the results (PLAN.AGREES). Two
  * results agree when they have the same value by `sameValue`, or errors with the same code, and the same place when
@@ -228,6 +291,10 @@ export function agree(machine: Machine, doc: unknown, context: Context = makeCon
       const traced = evaluate(machine, doc, context, { ...declared, ...mock });
       other = traced.result;
       otherEffects = [...traced.effects];
+    } else if (tier === "fixed") {
+      const why = fixedDiffers(machine, doc, context, result, effects, { ...declared, ...mock }, options);
+      if (why !== undefined) return { ok: false, tier, plan: result, other: why.other, reason: why.reason };
+      continue;
     } else if (tier === "folds") {
       other = prepare(machine, doc, { ...declared, fold: !folds }).evaluate(context, { effects: otherEffects, ...mock });
       if (observe !== undefined) {
@@ -282,12 +349,9 @@ interface Watched {
 function watched(perform: Perform): Watched {
   const effects: Effect[] = [];
   const settles: ReplaySettle[] = [];
-  const inner = (perform as { readonly [JOURNAL]?: Journal })[JOURNAL];
-  const settled = (all: string, item: number): void => {
+  const journal = relay(perform, (all, item) => {
     settles.push({ all, item });
-    inner?.settled?.(all, item);
-  };
-  const journal: Journal = inner?.next === undefined ? { settled } : { settled, next: (all, waiting) => inner.next?.(all, waiting) };
+  });
   const host = (effect: Effect): unknown => {
     effects.push(effect);
     return perform(effect);
@@ -309,6 +373,87 @@ function settlesDiffer(a: readonly ReplaySettle[], b: readonly ReplaySettle[]):
   return undefined;
 }
 
+/** The roots beside `self` that a value without static reads keeps whole (READS.KEPT). */
+const KEPT_ROOTS: readonly string[] = /* @__PURE__ */ Object.freeze(["names", "world", "event", "caps"]);
+
+/**
+ * This function tells if the plan does not know the reads of a run. A value without static reads keeps each root
+ * (READS.KEPT), thus the list holds a kept read of each whole root.
+ */
+function readsUnknown(reads: readonly Read[]): boolean {
+  return KEPT_ROOTS.every((root) => reads.some((read) => read.kept === true && read.path.length === 1 && read.path[0] === root));
+}
+
+/**
+ * This function gives the reads that `agreeRun` compares: the free reads of the resolutions (RUN.AGREES-READS). A
+ * kept read is the bound of the plan for the later reads of a value, and the reference has no such bound.
+ */
+function resolutions(reads: readonly Read[]): readonly Read[] {
+  return reads.filter((read) => read.free && read.kept !== true);
+}
+
+function pathText(path: readonly unknown[] | undefined): string {
+  if (path === undefined) return "no read";
+  try {
+    return JSON.stringify(path);
+  } catch {
+    return path.map(String).join(", ");
+  }
+}
+
+/**
+ * This function gives the rule of a comparison of reads. The rule of the caller answers first. Each tier makes its
+ * own nodes of a tree and its own adopted things. Thus two host things are the same when they have the same label,
+ * and they are nodes or have the same JSON object.
+ */
+function sameThing(equal: AgreeOptions["equal"]): (a: unknown, b: unknown) => boolean | undefined {
+  return (a, b) => {
+    const told = equal?.(a, b);
+    if (told !== undefined) return told;
+    if (!isHostThing(a) || !isHostThing(b)) return undefined;
+    if (a.label !== b.label) return false;
+    if (a.label.startsWith("node ")) return true;
+    try {
+      return Object.is(a.toJson(), b.toJson());
+    } catch {
+      return false;
+    }
+  };
+}
+
+/** This function gives the difference of what two reads reached, or `undefined` when they agree. */
+function reachedDiffers(a: Result, b: Result, equal: (a: unknown, b: unknown) => boolean | undefined, strict: boolean): string | undefined {
+  if (a.ok && b.ok) return sameValue(a.value, b.value, equal) ? undefined : "The read reaches another value in the tier.";
+  if (!a.ok && !b.ok) {
+    if (a.error.code !== b.error.code) return `The read gives ${a.error.code} in the plan, and ${b.error.code} in the tier.`;
+    return strict && a.error.reason !== b.error.reason ? `The read gives ${a.error.code} with another reason in the tier: "${b.error.reason}" for "${a.error.reason}".` : undefined;
+  }
+  if (!b.ok) return `The read reaches a value in the plan, and ${b.error.code} in the tier.`;
+  return `The read gives ${(a as { readonly error: EvalError }).error.code} in the plan, and a value in the tier.`;
+}
+
+/**
+ * This function gives the first difference of the reads of the plan and of a tier, or `undefined` when they agree
+ * (RUN.AGREES-READS). Only the free reads of the resolutions compare, in their order. When the plan does not know its
+ * reads, the function compares nothing.
+ */
+function readsDiffer(plan: readonly Read[], tier: readonly Read[], options: AgreeOptions): string | undefined {
+  if (readsUnknown(plan)) return undefined;
+  const a = resolutions(plan);
+  const b = resolutions(tier);
+  const equal = sameThing(options.equal);
+  for (let index = 0; index < Math.max(a.length, b.length); index += 1) {
+    const x = a[index];
+    const y = b[index];
+    if (x === undefined || y === undefined || !sameValue(x.path, y.path, equal)) {
+      return `The free read ${index} is ${pathText(x?.path)} in the plan, and ${pathText(y?.path)} in the tier.`;
+    }
+    const why = reachedDiffers(x.reached, y.reached, equal, options.strict === true);
+    if (why !== undefined) return `The free read ${index} of ${pathText(x.path)} differs. ${why}`;
+  }
+  return undefined;
+}
+
 /**
  * This function compares the run of a document in a plan with its run in other tiers (RUN.AGREES). First the plan
  * starts the run with a recorder around the host. Then each tier replays the log of that run. These tiers are the
@@ -317,6 +462,13 @@ function settlesDiffer(a: readonly ReplaySettle[], b: readonly ReplaySettle[]):
  * The rules of `agree` compare the results and the effects, with their addresses and outcomes. A tier must also
  * settle the waits of each `all` in the order of the plan, thus a replay keeps the order of the waits.
  *
+ * The reference run must also give the free reads of the plan, in their order (RUN.AGREES-READS). Another replay of
+ * the plan records these reads. A kept read does not compare. When the plan keeps each root, its reads are not known,
+ * and no read compares.
+ *
+ * One replayer of the log serves each tier and the replay for the reads (RUN.AGREES-ONE-REPLAYER). The replayer keeps
+ * no state of a run (RUN.REPLAY-RUNS), thus each tier replays the same log as with a replayer of its own.
+ *
  * @param machine - The world, the evaluators and the runners.
  * @param doc - The document.
  * @param context - The names and the capabilities at the root.
@@ -338,13 +490,22 @@ export async function agreeRun(machine: Machine, doc: unknown, context: Context
   const result = await plan.run(context, { perform: first.perform });
   const saw = observe?.();
   const log = recording.log();
+  // The reads of the plan come from another replay, thus the run of the plan above keeps its folds (PLAN.FOLD).
+  let planReads: readonly Read[] | undefined;
+  let compared: readonly Read[] | undefined;
+  // The kernel tells the journal the count of the waits that settled, thus one replayer serves each tier (RUN.AGREES-ONE-REPLAYER).
+  const replay = replayer(log);
 
   for (const tier of options.tiers ?? DEFAULT_TIERS) {
-    const replay = watched(replayer(log));
-    const host = { perform: replay.perform };
+    // A run has no tier with fixed names (PLAN.FIXED).
+    if (tier === "fixed") continue;
+    const tierReplay = watched(replay);
+    const host = { perform: tierReplay.perform };
     let other: Result;
+    let tierReads: Read[] | undefined;
     if (tier === "reference") {
-      other = await referenceRun(machine, doc, context, { ...declared, ...host, ...(options.definitions === undefined ? {} : { definitions: options.definitions }) });
+      tierReads = [];
+      other = await referenceRun(machine, doc, context, { ...declared, ...host, reads: tierReads, ...(options.definitions === undefined ? {} : { definitions: options.definitions }) });
     } else if (tier === "traced") {
       other = (await run(machine, doc, context, { ...declared, ...host })).result;
     } else if (tier === "folds") {
@@ -356,12 +517,23 @@ export async function agreeRun(machine: Machine, doc: unknown, context: Context
     const compareCalls = observe !== undefined && tier !== "folds";
     const calls = observe?.();
     if (overflowed(result) || overflowed(other)) continue;
-    const why =
+    let why =
       resultDiffers(result, other, options) ??
-      effectsDiffer(first.effects, replay.effects, options) ??
-      settlesDiffer(first.settles, replay.settles) ??
+      effectsDiffer(first.effects, tierReplay.effects, options) ??
+      settlesDiffer(first.settles, tierReplay.settles) ??
       (compareCalls && !sameValue(saw, calls, options.equal) ? "The host saw other calls in the tier." : undefined);
+    if (why === undefined && tierReads !== undefined) {
+      if (planReads === undefined) {
+        const reads: Read[] = [];
+        await plan.run(context, { perform: replay, reads });
+        // The calls of this replay are not a tier, thus the next tier compares only its own calls.
+        observe?.();
+        planReads = reads;
+      }
+      why = readsDiffer(planReads, tierReads, options);
+      if (why === undefined && !readsUnknown(planReads)) compared = resolutions(planReads);
+    }
     if (why !== undefined) return { ok: false, tier, plan: result, other, reason: why };
   }
-  return { ok: true, result, effects: first.effects };
+  return compared === undefined ? { ok: true, result, effects: first.effects } : { ok: true, result, effects: first.effects, reads: compared };
 }

package/src/conform.ts

@@ -32,6 +32,8 @@ import { type PartSlot, type Split, pathMatches, scopesOf, splitParts } from "./
 import { type Definitions, STD_DEFINITIONS } from "./reference.ts";
 import { STD_EVALUATORS } from "./stdlib.ts";
 import { sameValue } from "./agree.ts";
+import { declaredTruthOf } from "./formula.ts";
+import { membersOf, typeIssues, typeText } from "./types.ts";
 import { type Random, random } from "./generate.ts";
 import { type Kind, type LazyRule, type Shape, type World, type WorldEntry, effectsOfVerb, isKind, isNamespace, lookupKind } from "./world.ts";
 
@@ -56,8 +58,10 @@ import { type Kind, type LazyRule, type Shape, type World, type WorldEntry, effe
  * - `C8`: compiled code gives the result of code that compiles again at the time of the evaluation.
  * - `local`: the code keeps no state from one call to the next.
  * - `agree`: compiled code gives the result of its definition for the reference interpreter.
+ * - `truth`: the own `truthy` of a formula profile gives `true` or `false` for each member of its `truthType` (D86).
+ *   Only `formula.if`, `formula.and` and `formula.or` of the formula kit get this check.
  */
-export type Obligation = "C1" | "C2" | "C3" | "C4" | "C5" | "C6" | "C7" | "C8" | "local" | "agree";
+export type Obligation = "C1" | "C2" | "C3" | "C4" | "C5" | "C6" | "C7" | "C8" | "local" | "agree" | "truth";
 
 /** The probe of a finding: the document, the result of each probe part, the capabilities and the handler. */
 export interface ConformProbe {
@@ -132,7 +136,7 @@ export interface ConformOptions {
 }
 
 /** The order of the obligations in the list of findings. */
-const ORDER: readonly Obligation[] = ["C1", "C2", "C3", "C4", "C5", "C6", "C7", "C8", "local", "agree"];
+const ORDER: readonly Obligation[] = ["C1", "C2", "C3", "C4", "C5", "C6", "C7", "C8", "local", "agree", "truth"];
 
 /** A function in the results of the probe parts. It gives the count of its arguments. */
 const PROBE_FN = (...args: readonly unknown[]): number => args.length;
@@ -1025,6 +1029,34 @@ function examine(env: Env, sample: Sample, contract: Contract): void {
   }
 }
 
+/**
+ * This function checks the declared truth of a profile (D86). The function `truthy` must give `true` or `false` for
+ * each member of `truthType`, and it must not throw. The members come from the lists `values` of the domains of the
+ * type. A type without such a list gets the values of the results of the palette that are its members.
+ */
+function checkTruth(env: Env, code: unknown, probe: (value: unknown) => ConformProbe): void {
+  const truth = declaredTruthOf(code);
+  if (truth === undefined) return;
+  const domains = env.machine.domains;
+  // The check gives an issue for a bad type, and it then needs nothing of a test (D81).
+  if (typeIssues(truth.truthType, domains).length > 0) return;
+  const samples = env.results.flatMap((result) => (result.ok ? [result.value] : []));
+  const of = (value: unknown): string => `the member ${valueText(value)} of the truth type ${typeText(truth.truthType)}`;
+  for (const value of membersOf(truth.truthType, domains, samples)) {
+    let given: unknown;
+    try {
+      given = truth.truthy(value);
+    } catch (error) {
+      report(env, "truth", `The function truthy of the profile throws for ${of(value)}: ${describe(error)}`, () => probe(value));
+      return;
+    }
+    if (typeof given === "boolean") continue;
+    const what = given === undefined ? "no truth" : valueText(given);
+    report(env, "truth", `The function truthy of the profile gives ${what} for ${of(value)}. A truth is true or false.`, () => probe(value));
+    return;
+  }
+}
+
 /**
  * This function examines one evaluator or runner of a machine against the obligations of host code (K92, D36). It
  * starts the code directly, without the kernel, with probe parts and a probe runtime. It generates probe documents from
@@ -1032,8 +1064,10 @@ function examine(env: Env, sample: Sample, contract: Contract): void {
  *
  * The checks follow the obligations C1 to C8 of `docs/SEMANTICS.md`. Two more checks follow the premises of the
  * simulation of the plan. The check `local` finds state that stays from one call to the next. The check `agree` compares
- * compiled code with its definition. The
- * finding of an obligation names the first probe that breaks it. An empty list means that each probe conforms.
+ * compiled code with its definition. The finding of an obligation names the first probe that breaks it. An empty list
+ * means that each probe conforms.
+ *
+ * The check `truth` tests the declared truth of a formula profile (D86).
  *
  * @param machine - The machine with the code and the world of the kinds.
  * @param name - The name of the evaluator or of the runner. A runner wins over an evaluator of the same name.
@@ -1064,13 +1098,23 @@ export function conforms(machine: Machine, name: string, options: ConformOptions
     found: new Map(),
   };
   const types = options.types ?? typesNaming(machine.world, name, verb);
+  let first: Sample | undefined;
   if (types.length === 0) throw new Error(`No kind of the world names ${name} for the verb ${verb}. Give the types of the probe documents in the option types.`);
   for (const type of types) {
     const found = lookupKind(machine.world, type);
     if (!found.ok) throw new Error(`The world has no kind for the type ${typeName(type)}.`);
     const contract = contractOf(env, found.kind, found.path, options.caps);
     const extra = own(options.values, typeName(type)) ?? own(options.values, found.path.join(".")) ?? [];
-    for (const sample of samplesOf(type, found.path, found.kind, contract, extra)) examine(env, sample, contract);
+    for (const sample of samplesOf(type, found.path, found.kind, contract, extra)) {
+      first ??= sample;
+      examine(env, sample, contract);
+    }
   }
+  // A probe of the truth gives the member to each part of the first probe document.
+  checkTruth(env, code, (value) =>
+    first === undefined
+      ? { type: typeName(types[0] as TypeRef), doc: { type: types[0] as TypeRef, value: null }, results: {}, waits: [], caps: NO_CAPS, running: runner }
+      : probeOf(first, { results: first.split.parts.map(() => ok(value)), waits: [], caps: NO_CAPS, running: runner }),
+  );
   return ORDER.filter((obligation) => env.found.has(obligation)).map((obligation) => env.found.get(obligation) as Finding);
 }

package/src/deref.ts

@@ -48,6 +48,15 @@ export interface HostThing {
    * @returns What the keys reach, or `undefined` when they reach nothing. `{ thing: undefined }` tells that the keys reach a field that holds `undefined`.
    */
   resolve?(keys: readonly Key[]): { readonly thing: Thing } | undefined;
+  /**
+   * This optional function answers one step only when the host has its value without new work (SCHED.CLOSURE). A
+   * kept read of a closure uses it, because the evaluation did not ask for that read. A schedule gives the value of
+   * a node that has its result in the data epoch. A throw gives the error of the step.
+   *
+   * @param key - The key of the step.
+   * @returns What the step reaches, or `undefined` when the host does not know it yet. Then the kept read ends at the thing.
+   */
+  known?(key: Key): { readonly thing: Thing } | undefined;
 }
 
 /** Something that a path can reach: any value of the host, or a host thing. */
@@ -92,8 +101,31 @@ export interface Context {
   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 code of a `deref` evaluator: it answers one step of a path on a document of its kind. A field that holds
+ * `undefined` also gives `undefined`. The optional function `has` of the code tells the two cases apart
+ * (DEREF.KIND-UNDEFINED). A host gives the code a `has` with `Object.assign(code, { has })`.
+ */
+export interface DerefCode {
+  /**
+   * This function answers one step on a document.
+   *
+   * @param doc - The document.
+   * @param key - The key of the step.
+   * @returns What the step reaches, or `undefined` when it reaches nothing.
+   */
+  (doc: Envelope, key: Key): Thing | undefined;
+  /**
+   * This optional function tells if a document has a field for a key. The kernel asks it only when the code gives
+   * `undefined`. Then `true` tells that the field holds `undefined`. A code without `has` reads `undefined` as a
+   * missing field, as a host thing does (DEREF.HOST-UNDEFINED).
+   *
+   * @param doc - The document.
+   * @param key - The key of the step.
+   * @returns `true` when the document has the field.
+   */
+  readonly has?: (doc: Envelope, key: Key) => boolean;
+}
 
 /**
  * The result of a step document: what it reached, or the reason of a failure. A failure can give its code, for
@@ -109,13 +141,32 @@ export interface WalkInput {
   readonly here: Thing;
   readonly context: Context;
   /**
-   * This function answers one step on a thing, through the ladder.
+   * This function answers one step on a thing, through the ladder. A field that holds `undefined` also gives
+   * `undefined`. The function `has` tells the two cases apart (DEREF.WALKER-UNDEFINED).
    *
    * @param thing - The thing.
    * @param key - The key.
    * @returns What the step reaches, or `undefined`.
    */
   deref(thing: Thing, key: Key): Thing | undefined;
+  /**
+   * This optional function tells if a step on a thing reaches a field, through the ladder. A walker needs it only
+   * when `deref` gives `undefined`. Then `true` tells that the field holds `undefined` (DEREF.WALKER-UNDEFINED).
+   * Each resolution of the kernel gives it. The function asks the ladder again, thus a host thing answers the step again.
+   *
+   * @param thing - The thing.
+   * @param key - The key.
+   * @returns `true` when the step reaches a field, also a field that holds `undefined`.
+   */
+  has?(thing: Thing, key: Key): boolean;
+  /**
+   * This optional function records one hop inside the walk (HOP.EACH-STEP). The resolution gives it only when it
+   * records hops. The hop of the whole walk comes after these hops, as before.
+   *
+   * @param key - The key that the walk followed.
+   * @param thing - The thing that the key reached.
+   */
+  readonly visit?: (key: Key, thing: Thing) => void;
 }
 
 /** A walker: the code of the verb `step` of a kind of step documents. */
@@ -301,8 +352,10 @@ export function derefStep(nav: Navigator, thing: Thing, key: Key): { readonly th
     // A navigator without the code of a deref needs no lookup of the kind: no rung can answer.
     const answer = derefs === undefined ? undefined : answerOf(nav.world, ownEntries(envelope), kindFor(nav.world, envelope.type), "deref", (name) => codeIn(derefs, name));
     if (answer !== undefined) {
-      const reached = (derefs as Readonly<Record<string, DerefCode>>)[answer.name]?.(envelope, key);
-      return reached === undefined ? undefined : { thing: reached, by: answer.rung };
+      const code = (derefs as Readonly<Record<string, DerefCode>>)[answer.name];
+      const reached = code?.(envelope, key);
+      // DEREF.KIND-UNDEFINED: the `has` of the code tells a field that holds undefined from a missing field.
+      return reached !== undefined || code?.has?.(envelope, key) === true ? { thing: reached, by: answer.rung } : undefined;
     }
     const reached = plainStep(envelope.value, key);
     return reached === NOTHING ? undefined : { thing: reached, by: "default" };
@@ -579,6 +632,38 @@ export function resolve(nav: Navigator, ctx: Context, path: readonly unknown[],
   return resolveFully(nav, ctx, path, options.hops === false ? undefined : [], undefined);
 }
 
+/** The functions `deref` and `has` of the input of a walker, for one navigator. */
+interface WalkSteps {
+  readonly nav: Navigator;
+  readonly deref: (thing: Thing, key: Key) => Thing | undefined;
+  readonly has: (thing: Thing, key: Key) => boolean;
+}
+
+/** The functions of the last navigator that gave a walker its input. A walk with the same navigator makes no new functions. */
+let lastSteps: WalkSteps | undefined;
+
+/**
+ * This function gives the functions `deref` and `has` of the input of a walker. They depend only on the navigator,
+ * thus the function keeps the functions of the last navigator (K170).
+ */
+function walkSteps(nav: Navigator): WalkSteps {
+  if (lastSteps !== undefined && lastSteps.nav === nav) return lastSteps;
+  const adopt = nav.adopt;
+  lastSteps = {
+    nav,
+    deref:
+      adopt === undefined
+        ? (thing, key) => derefStep(nav, thing, key)?.thing
+        : (thing, key) => {
+            const reached = derefStep(nav, thing, key);
+            return reached === undefined ? undefined : adopt(reached.thing);
+          },
+    // DEREF.WALKER-UNDEFINED: the same ladder tells a field that holds undefined from a missing field.
+    has: (thing, key) => derefStep(nav, thing, key) !== undefined,
+  };
+  return lastSteps;
+}
+
 /**
  * This function resolves a path with the full algorithm of `resolve`.
  *
@@ -651,15 +736,13 @@ function resolveFully(nav: Navigator, ctx: Context, path: readonly unknown[], ho
         const walker = given === undefined ? walkerOf(nav, step) : (given ?? undefined);
         if (walker === undefined) return failed("#STEP?", "A step is a key, or a document of a kind with the verb step.");
         const envelope = step as Envelope;
-        const result = walker({
-          data: envelope.value,
-          here,
-          context: ctx,
-          deref: (thing, key) => {
-            const reached = derefStep(nav, thing, key);
-            return reached === undefined ? undefined : adopt(reached.thing);
-          },
-        });
+        const { deref, has } = walkSteps(nav);
+        // A resolution without a record of hops gives no `visit`, thus a walker records nothing (HOP.EACH-STEP).
+        const result = walker(
+          hops === undefined
+            ? { data: envelope.value, here, context: ctx, deref, has }
+            : { data: envelope.value, here, context: ctx, deref, has, visit: (key, thing) => hops.push({ step: key, thing, by: "step" }) },
+        );
         if (!result.ok) return failed(result.code ?? "#N/A", result.reason);
         here = adopt(result.thing);
         hops?.push({ step: envelope as Json, thing: here, by: "step" });