@mark1russell7/coeval 0.4.1 → 0.4.3

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package",
   "name": "@mark1russell7/coeval",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "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

@@ -0,0 +1,237 @@
+import { type Key, docEquals, isRecord } from "./doc.ts";
+import type { Context } from "./deref.ts";
+import { type EvalError, type Result, isStackOverflow, thrown } from "./errors.ts";
+import { type Effect, type Machine, evaluate, makeContext, prepare } from "./evaluate.ts";
+import { Held, isClosure } from "./formula.ts";
+import { type Definitions, reference } from "./reference.ts";
+
+/**
+ * A tier that `agree` compares with the plan.
+ *
+ * - `reference`: the reference interpreter, which compiles nothing.
+ * - `traced`: the traced evaluation, `evaluate`.
+ * - `again`: a second evaluation of the same plan.
+ * - `other`: the second tier of a language, from the option `other`.
+ */
+export type Tier = "reference" | "traced" | "again" | "other";
+
+/** What a second tier gives: its result, and its effects when it records them. */
+export interface TierResult {
+  readonly result: Result;
+  readonly effects?: readonly Effect[];
+}
+
+/** The options of `agree`. */
+export interface AgreeOptions {
+  /** The type of a bare root value. */
+  readonly declaredType?: string;
+  /** The definitional code of the compiled evaluators of the machine, for the reference. */
+  readonly definitions?: Definitions;
+  /** The tiers to compare with the plan. The default is the reference, the traced evaluation and a second evaluation. */
+  readonly tiers?: readonly Exclude<Tier, "other">[];
+  /**
+   * This function gives the result of the second tier of a language, for example a compiler to loops.
+   *
+   * @param doc - The document.
+   * @param context - The context.
+   * @returns The result, or the result with the effects.
+   */
+  readonly other?: (doc: unknown, context: Context) => Result | TierResult;
+  /**
+   * This function compares two values that the rules of `sameValue` do not know, for example two dates.
+   *
+   * @param a - The value of the plan.
+   * @param b - The value of the other tier.
+   * @returns `true` or `false`, or `undefined` to use the rules of `sameValue`.
+   */
+  readonly equal?: (a: unknown, b: unknown) => boolean | undefined;
+  /** `true`: two errors must also have the same reason, and each error must have a place. */
+  readonly strict?: boolean;
+  /**
+   * This function gives what the host saw since its last call, for example the calls of an operation. `agree` uses
+   * it before the plan and after each tier, and compares the results. Thus a tier that evaluates a part that the plan
+   * does not evaluate fails.
+   *
+   * @returns What the host saw.
+   */
+  readonly observe?: () => unknown;
+}
+
+/** The outcome of `agree`: the result of the plan, or the first tier that disagrees with it. */
+export type Agreement =
+  | { readonly ok: true; readonly result: Result; readonly effects: readonly Effect[] }
+  | {
+      readonly ok: false;
+      readonly tier: Tier;
+      /** The result of the plan. */
+      readonly plan: Result;
+      /** The result of the tier that disagrees. */
+      readonly other: Result;
+      /** One sentence that tells the difference. */
+      readonly reason: string;
+    };
+
+/**
+ * This function tells if two values are the same for `agree`. Lists and plain records compare item by item and field
+ * by field, and the order of the fields does not matter. Each other leaf compares with `Object.is`, thus `-0` is not
+ * `0`, and `NaN` is `NaN`. The identity of a list or of a plain record is not compared.
+ *
+ * Two closures of `fn` are the same when they have the same parameters. Two `Held` values are the same when their
+ * errors have the same code and place. Each other object is the same only as itself, unless the rule of the caller
+ * tells otherwise.
+ *
+ * `docEquals` uses the same rules for lists, plain records and the other objects. It has no rules for closures, for
+ * `Held` values and for a rule of the caller. Thus two closures are equal there only when they are the same function.
+ *
+ * @param a - The first value.
+ * @param b - The second value.
+ * @param equal - The rule of the caller for other values. It answers first, and `undefined` gives the rules above.
+ * @returns `true` when the values are the same.
+ */
+export function sameValue(a: unknown, b: unknown, equal?: (a: unknown, b: unknown) => boolean | undefined): boolean {
+  const stack: (readonly [unknown, unknown])[] = [[a, b]];
+  const seen = new Map<object, Set<object>>();
+  while (stack.length > 0) {
+    const [x, y] = stack.pop() as readonly [unknown, unknown];
+    if (Object.is(x, y)) continue;
+    const told = equal?.(x, y);
+    if (told !== undefined) {
+      if (told) continue;
+      return false;
+    }
+    if (typeof x !== "object" && typeof x !== "function") return false;
+    if (typeof y !== "object" && typeof y !== "function") return false;
+    if (x === null || y === null) return false;
+    // A pair that the comparison already visits is the same, unless another pair shows a difference.
+    const pairs = seen.get(x) ?? new Set<object>();
+    if (pairs.has(y)) continue;
+    pairs.add(y);
+    seen.set(x, pairs);
+    if (isClosure(x) || isClosure(y)) {
+      if (!(isClosure(x) && isClosure(y))) return false;
+      stack.push([closureParams(x), closureParams(y)]);
+      continue;
+    }
+    if (x instanceof Held || y instanceof Held) {
+      if (!(x instanceof Held && y instanceof Held) || errorDiffers(x.error, y.error, false) !== undefined) return false;
+      continue;
+    }
+    if (Array.isArray(x) || Array.isArray(y)) {
+      if (!Array.isArray(x) || !Array.isArray(y) || x.length !== y.length) return false;
+      for (let index = 0; index < x.length; index += 1) stack.push([x[index], y[index]]);
+      continue;
+    }
+    if (!isRecord(x) || !isRecord(y)) return false;
+    const keys = Object.keys(x);
+    if (keys.length !== Object.keys(y).length) return false;
+    for (const key of keys) {
+      if (!Object.hasOwn(y, key)) return false;
+      stack.push([x[key], y[key]]);
+    }
+  }
+  return true;
+}
+
+const CLOSURE = Symbol.for("coeval.closure");
+
+function closureParams(fn: object): unknown {
+  return (fn as { readonly [CLOSURE]?: { readonly params: readonly string[] } })[CLOSURE]?.params;
+}
+
+function codeAndPlace(error: EvalError): string {
+  return error.place === undefined ? error.code : `${error.code} at [${error.place.join(", ")}]`;
+}
+
+/** This function gives the difference of two errors, or `undefined` when they agree. */
+function errorDiffers(a: EvalError, b: EvalError, strict: boolean): string | undefined {
+  if (a.code !== b.code) return `The plan gives ${codeAndPlace(a)}, and the tier gives ${codeAndPlace(b)}.`;
+  if (strict && (a.place === undefined || b.place === undefined)) return `An error ${a.code} has no place.`;
+  if (a.place !== undefined && b.place !== undefined && !docEquals(a.place as readonly Key[], b.place as readonly Key[])) {
+    return `The error ${a.code} has the place [${a.place.join(", ")}] in the plan, and [${b.place.join(", ")}] in the tier.`;
+  }
+  if (strict && a.reason !== b.reason) return `The error ${a.code} has another reason in the tier: "${b.reason}" for "${a.reason}".`;
+  return undefined;
+}
+
+/** A host stack overflow is the one permitted difference (VALUE.DEPTH): the tiers use different numbers of frames. */
+function overflowed(result: Result): boolean {
+  return !result.ok && result.error.code === "#DEPTH!" && isStackOverflow(result.error.cause);
+}
+
+/** This function gives the difference of two results, or `undefined` when they agree. */
+function resultDiffers(a: Result, b: Result, options: AgreeOptions): string | undefined {
+  if (a.ok && b.ok) return sameValue(a.value, b.value, options.equal) ? undefined : "The plan and the tier give different values.";
+  if (!a.ok && !b.ok) return errorDiffers(a.error, b.error, options.strict === true);
+  return a.ok ? `The plan gives a value, and the tier gives ${codeAndPlace((b as { readonly error: EvalError }).error)}.` : `The plan gives ${codeAndPlace(a.error)}, and the tier gives a value.`;
+}
+
+/** This function gives the difference of two lists of effects, or `undefined` when they agree (EFFECT.ORDER). */
+function effectsDiffer(a: readonly Effect[], b: readonly Effect[], options: AgreeOptions): string | undefined {
+  if (a.length !== b.length) return `The plan causes ${a.length} effects, and the tier causes ${b.length}.`;
+  for (let index = 0; index < a.length; index += 1) {
+    const x = a[index] as Effect;
+    const y = b[index] as Effect;
+    if (x.kind !== y.kind || !docEquals(x.place as readonly Key[], y.place as readonly Key[]) || !sameValue(x.payload, y.payload, options.equal)) {
+      return `The effect ${index} differs: ${x.kind} at [${x.place.join(", ")}] in the plan, and ${y.kind} at [${y.place.join(", ")}] in the tier.`;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * This function evaluates a document with a plan and with other tiers, and compares the results (PLAN.AGREES). Two
+ * results agree when they have the same value by `sameValue`, or errors with the same code, and the same place when
+ * both have one. The effects must have the same kinds, places and payloads, in the same order. A language gives its
+ * own tier with the option `other`.
+ *
+ * @param machine - The world and the code of the evaluators.
+ * @param doc - The document.
+ * @param context - The names and the capabilities at the root.
+ * @param options - The tiers, the definitions for the reference, the rules of the comparison and the second tier.
+ * @returns The result of the plan, or the first tier that disagrees and the reason.
+ */
+export function agree(machine: Machine, doc: unknown, context: Context = makeContext(), options: AgreeOptions = {}): Agreement {
+  const declared = options.declaredType === undefined ? {} : { declaredType: options.declaredType };
+  const observe = options.observe;
+  observe?.();
+  const plan = prepare(machine, doc, declared);
+  const effects: Effect[] = [];
+  const result = plan.evaluate(context, { effects });
+  const saw = observe?.();
+
+  const differs = (other: Result, otherEffects: readonly Effect[] | undefined): string | undefined => {
+    if (overflowed(result) || overflowed(other)) return undefined;
+    const why = resultDiffers(result, other, options) ?? (otherEffects === undefined ? undefined : effectsDiffer(effects, otherEffects, options));
+    if (why !== undefined || observe === undefined) return why;
+    return sameValue(saw, observe(), options.equal) ? undefined : "The host saw other calls in the tier.";
+  };
+
+  for (const tier of options.tiers ?? ["reference", "traced", "again"]) {
+    let other: Result;
+    let otherEffects: Effect[] = [];
+    if (tier === "reference") {
+      other = reference(machine, doc, context, { ...declared, effects: otherEffects, ...(options.definitions === undefined ? {} : { definitions: options.definitions }) });
+    } else if (tier === "traced") {
+      const traced = evaluate(machine, doc, context, options.declaredType);
+      other = traced.result;
+      otherEffects = [...traced.effects];
+    } else {
+      other = plan.evaluate(context, { effects: otherEffects });
+    }
+    const why = differs(other, otherEffects);
+    if (why !== undefined) return { ok: false, tier, plan: result, other, reason: why };
+  }
+
+  if (options.other !== undefined) {
+    let given: Result | TierResult;
+    try {
+      given = options.other(doc, context);
+    } catch (error) {
+      given = thrown(error, "the tier");
+    }
+    const other = "result" in given ? given.result : given;
+    const why = differs(other, "result" in given ? given.effects : undefined);
+    if (why !== undefined) return { ok: false, tier: "other", plan: result, other, reason: why };
+  }
+  return { ok: true, result, effects };
+}

package/src/doc.ts

@@ -221,9 +221,17 @@ export function fromJson(value: unknown): Envelope | undefined {
 }
 
 /**
- * This function tells if two JSON values are equal. Equal values have the same texts, numbers and truth values,
- * the same items in the same order, and the same fields. The order of the fields does not matter. It does not use the stack for the
- * depth, thus a deep document cannot overflow it.
+ * This function tells if two values are equal. Plain JSON compares by its structure. Equal values have the same
+ * texts, numbers and truth values, the same items in the same order, and the same fields. The order of the fields
+ * does not matter. Each leaf compares with `Object.is`, thus `-0` is not `0`, and `NaN` is `NaN`.
+ *
+ * Only lists and plain records (`isRecord`) compare by their items and fields. Each other object compares by
+ * identity: a date, a map, a function and an instance of a class are equal only to themselves. Thus an early cutoff
+ * with this function does not keep a stale host value.
+ *
+ * The function does not use the stack for the depth, thus a deep document cannot overflow it. A cycle of lists or
+ * records does not make it loop. `sameValue` of `agree` uses the same rules, and it adds rules for closures and for
+ * a rule of the caller.
  *
  * @param a - The first value.
  * @param b - The second value.
@@ -231,15 +239,25 @@ export function fromJson(value: unknown): Envelope | undefined {
  */
 export function docEquals(a: unknown, b: unknown): boolean {
   const stack: [unknown, unknown][] = [[a, b]];
+  // The pairs of containers that the comparison already visits. It is made at the first pair of containers.
+  let seen: Map<object, Set<object>> | undefined;
   while (stack.length > 0) {
     const [x, y] = stack.pop() as [unknown, unknown];
     if (Object.is(x, y)) continue;
-    if (typeof x !== "object" || typeof y !== "object" || x === null || y === null) return false;
-    if (Array.isArray(x) !== Array.isArray(y)) return false;
-    if (Array.isArray(x)) {
+    const list = Array.isArray(x);
+    if (list !== Array.isArray(y)) return false;
+    // An object that is not a list and not a plain record is a host value: Object.is above compared it.
+    if (!list && (!isRecord(x) || !isRecord(y))) return false;
+    seen ??= new Map();
+    const pairs = seen.get(x as object);
+    if (pairs?.has(y as object) === true) continue;
+    if (pairs === undefined) seen.set(x as object, new Set([y as object]));
+    else pairs.add(y as object);
+    if (list) {
+      const xs = x as readonly unknown[];
       const ys = y as readonly unknown[];
-      if (x.length !== ys.length) return false;
-      for (let index = 0; index < x.length; index += 1) stack.push([x[index], ys[index]]);
+      if (xs.length !== ys.length) return false;
+      for (let index = 0; index < xs.length; index += 1) stack.push([xs[index], ys[index]]);
       continue;
     }
     const xr = x as Readonly<Record<string, unknown>>;

package/src/errors.ts

@@ -104,7 +104,12 @@ export class Failure extends Error {
  * @returns `true` for a stack overflow.
  */
 export function isStackOverflow(error: unknown): boolean {
-  return error instanceof RangeError && /call stack/i.test(error.message);
+  try {
+    return error instanceof RangeError && /call stack/i.test(error.message);
+  } catch {
+    // Near the limit of the stack, the test itself overflows: the regular expression throws a SyntaxError.
+    return true;
+  }
 }
 
 /**

package/src/evaluate.ts

@@ -1,7 +1,7 @@
 import { type Envelope, type Json, type Key, type TypeRef, isEnvelope, typeName } from "./doc.ts";
-import { type Split, pathMatches, splitParts } from "./parts.ts";
+import { type Split, partsOf, pathMatches } from "./parts.ts";
 import { ask, type Answer } from "./ladder.ts";
-import { type CapsRule, type Lookup, type Side, type World, lookupKind } from "./world.ts";
+import type { CapsRule, Kind, Side, World } from "./world.ts";
 import { type ErrorCode, type EvalError, type Result, fail, ok, placed, thrown, describe } from "./errors.ts";
 import {
   type Cap,
@@ -428,6 +428,7 @@ export type Runner = RunFn | CompiledRunner;
  *
  * - `maxDepth`: the deepest nesting of documents. The default is 1000.
  * - `permits`: the rule of the host for an effect. The default is the function `permits` on the capabilities.
+ * - `known`: the names that the evaluators know, for `check`. Without it, `check` does not check such names.
  */
 export interface Machine extends Navigator {
   readonly evaluators: Readonly<Record<string, Evaluator>>;
@@ -435,6 +436,16 @@ export interface Machine extends Navigator {
   readonly runners?: Readonly<Record<string, Runner>>;
   readonly maxDepth?: number;
   readonly permits?: (caps: readonly Cap[], kind: readonly Key[], context: Context) => boolean;
+  /**
+   * This function tells if an evaluator knows the name in the path of a kind. An example is the operation
+   * `["ops", "add"]` of a formula language: a fallback kind names it, and the evaluator finds it in a table.
+   * `check` asks it for each document with an evaluator. The function must be pure.
+   *
+   * @param path - The keys of the kind of the document, after each alias.
+   * @param evaluator - The name of the evaluator that the ladder gives the document.
+   * @returns `true` when the evaluator knows the name, or else the reason of the `#NAME?` that a run gives.
+   */
+  readonly known?: (path: readonly Key[], evaluator: string) => true | string;
 }
 
 /** One evaluation in a trace. The children are the evaluations of its parts, in the order that they started. */
@@ -832,7 +843,11 @@ interface Compiler {
 }
 
 function failing(c: Compiler, meta: Meta, place: readonly Key[], code: ErrorCode, reason: string): { readonly code: Code; readonly run: RunCode } {
-  const result = fail(code, reason, { place });
+  return failingWith(c, meta, fail(code, reason, { place }));
+}
+
+/** This function gives the code of a document that fails with one result at each evaluation. */
+function failingWith(c: Compiler, meta: Meta, result: Result): { readonly code: Code; readonly run: RunCode } {
   const plain: Code = () => result;
   return finish(c, meta, plain, function* () {
     return result;
@@ -890,12 +905,12 @@ function finish(c: Compiler, meta: Meta, code: Code, run: RunCode): { readonly c
  * This function finds the evaluator of the verb `eval` without the record of the rungs, for a compilation without a
  * trace. It gives the same evaluator as `ask`: the own entry, then the kind, then the default of the world.
  */
-function evaluatorOf(world: World, envelope: Envelope | undefined, found: Lookup): { readonly name?: string; readonly unknown: boolean } {
+function evaluatorOf(world: World, envelope: Envelope | undefined, kind: Kind | undefined): { readonly name?: string; readonly unknown: boolean } {
   const own = envelope?.own;
   const ownName = own !== undefined && Object.hasOwn(own, "eval") ? own["eval"] : undefined;
   if (ownName !== undefined) return { name: ownName, unknown: false };
-  if (!found.ok) return { unknown: true };
-  const verbs = found.kind.verbs;
+  if (kind === undefined) return { unknown: true };
+  const verbs = kind.verbs;
   const name = Object.hasOwn(verbs, "eval") ? verbs["eval"] : Object.hasOwn(world.defaults, "eval") ? world.defaults["eval"] : undefined;
   return name === undefined ? { unknown: false } : { name, unknown: false };
 }
@@ -904,17 +919,17 @@ function evaluatorOf(world: World, envelope: Envelope | undefined, found: Lookup
 const NO_META: Meta = Object.freeze({ path: [], doc: { type: "?", value: null }, declared: false, answer: NO_ANSWER, side: "derive" });
 
 function compileNode(c: Compiler, value: unknown, place: readonly Key[], declared: string | undefined, depth: number, address = false): { readonly code: Code; readonly run: RunCode } {
-  const envelope = isEnvelope(value) ? (value as Envelope) : undefined;
-  const doc: Envelope = envelope ?? { type: declared ?? "?", value: value as Json };
-  const meta0: Meta = c.traced ? { path: place.map(String), doc, declared: envelope === undefined, answer: NO_ANSWER, side: "derive" } : NO_META;
-  if (envelope === undefined && declared === undefined) {
-    return failing(c, meta0, place, "#PART?", "The value has no envelope, and its position declares no type.");
+  const world = c.machine.world;
+  const read = partsOf(world, value, declared);
+  if (!read.ok) {
+    const meta: Meta = c.traced ? { path: place.map(String), doc: { type: "?", value: value as Json }, declared: true, answer: NO_ANSWER, side: "derive" } : NO_META;
+    return failing(c, meta, place, read.code, read.reason);
   }
+  const { doc, kind, split } = read;
+  const envelope = read.declared ? undefined : doc;
+  const meta0: Meta = c.traced ? { path: place.map(String), doc, declared: read.declared, answer: NO_ANSWER, side: "derive" } : NO_META;
   if (depth > c.maxDepth) return failing(c, meta0, place, "#DEPTH!", `The nesting is deeper than ${c.maxDepth} documents.`);
 
-  const world = c.machine.world;
-  const found = lookupKind(world, doc.type);
-  const kind = found.ok ? found.kind : undefined;
   let meta = meta0;
   let name: string | undefined;
   let unknown: boolean;
@@ -924,7 +939,7 @@ function compileNode(c: Compiler, value: unknown, place: readonly Key[], declare
     name = answer.evaluator;
     unknown = answer.error === "unknown-kind";
   } else {
-    const quick = evaluatorOf(world, envelope, found);
+    const quick = evaluatorOf(world, envelope, kind);
     name = quick.name;
     unknown = quick.unknown;
   }
@@ -937,11 +952,7 @@ function compileNode(c: Compiler, value: unknown, place: readonly Key[], declare
     return failing(c, meta, place, "#NOEVAL", `No rung gives an evaluator for ${kindText}.`);
   }
 
-  const split = splitParts(kind?.parts, doc.value);
-  if (!split.ok) {
-    const at = split.at.length === 0 ? "" : ` (at ${split.at.join(".")})`;
-    return failing(c, meta, place, "#VALUE!", `${split.reason}${at} The kind is ${kindText}.`);
-  }
+  if (!split.ok) return failing(c, meta, place, "#VALUE!", split.reason);
   const parts: CompiledPart[] = split.parts.map((slot) => {
     const item = slot.item;
     // The capability rules of the contract narrow the context of the part, thus no evaluator can forget them.
@@ -954,7 +965,7 @@ function compileNode(c: Compiler, value: unknown, place: readonly Key[], declare
       ? { key: slot.key, path: slot.path, code: compiled.code, run: compiled.run }
       : { key: slot.key, path: slot.path, name: header, code: compiled.code, run: compiled.run };
   });
-  const typePath = found.ok ? found.path : [];
+  const typePath = read.typePath ?? [];
   const input: CompileInput = {
     kind: kindText,
     typePath,
@@ -967,15 +978,24 @@ function compileNode(c: Compiler, value: unknown, place: readonly Key[], declare
     fill: fillOf(split, doc),
     ...(address ? { address: true } : {}),
   };
+  // A compiler that throws fails its own document when that document evaluates, with its place (PLAN.FAIL-LATE).
   if (runner !== undefined) {
-    const inner: RunCode = isCompiledRunner(runner) ? runner.compileRun(input) : interpretRun(runner, input, split.fill);
+    let inner: RunCode;
+    try {
+      inner = isCompiledRunner(runner) ? runner.compileRun(input) : interpretRun(runner, input, split.fill);
+    } catch (error) {
+      return failingWith(c, meta, placed(thrown(error, `the runner ${name}`), place));
+    }
     const run = placedRun(inner, place, name);
     return finish(c, meta, runnerCode(run, place, kindText), run);
   }
 
-  const inner: Code = isCompiledEvaluator(evaluator as Evaluator)
-    ? (evaluator as CompiledEvaluator).compile(input)
-    : interpret(evaluator as EvalFn, input, split.fill);
+  let inner: Code;
+  try {
+    inner = isCompiledEvaluator(evaluator as Evaluator) ? (evaluator as CompiledEvaluator).compile(input) : interpret(evaluator as EvalFn, input, split.fill);
+  } catch (error) {
+    return failingWith(c, meta, placed(thrown(error, `the evaluator ${name}`), place));
+  }
   const code = placedCode(inner, place, name);
   return finish(c, meta, code, runOf(code));
 }
@@ -1022,12 +1042,15 @@ function placedRun(inner: RunCode, place: readonly Key[], name: string): RunCode
   };
 }
 
-/** This function gives the code of a runner in an evaluation: its steps, which cannot wait. */
+/**
+ * This function gives the code of a runner in an evaluation: its steps, which cannot wait. A step that waits gives
+ * `#CALC!` at the place of the runner, where the error started (RUN.WAIT).
+ */
 function runnerCode(run: RunCode, place: readonly Key[], kindText: string): Code {
   return (ctx, rt) =>
     rt.running
       ? fail("#CALC!", `${kindText} waits for effects, and its parent cannot wait. Give the parent a runner.`, { place })
-      : drive(run(ctx, rt));
+      : placed(drive(run(ctx, rt)), place);
 }
 
 /** This function gives the steps of a run of an evaluator. The code runs at the first step, and it does not wait. */
@@ -1119,7 +1142,7 @@ export function prepare(machine: Machine, doc: unknown, options: PrepareOptions
   try {
     root = compileNode(c, doc, [], options.declaredType, 0);
   } catch (error) {
-    const result = thrown(error, "the compilation");
+    const result = placed(thrown(error, "the compilation"), []);
     root = {
       code: () => result,
       run: function* () {

package/src/formula.ts

@@ -1,4 +1,4 @@
-import { type Json, isRecord } from "./doc.ts";
+import { type Json, type Key, isRecord } from "./doc.ts";
 import type { Kind, WorldEntry } from "./world.ts";
 import { type Context, type Resolution, valueOfThing } from "./deref.ts";
 import { type EvalError, type Failed, type Result, Failure, fail, ok, thrown } from "./errors.ts";
@@ -142,7 +142,7 @@ export function formulaKinds(): Readonly<Record<string, WorldEntry>> {
     },
     fn: {
       verbs: { eval: "formula.fn" },
-      parts: { shape: "record", fields: { body: term }, required: ["params", "body"] },
+      parts: { shape: "record", fields: { params: { shape: "list", item: { shape: "text" }, distinct: true }, body: term }, required: ["params", "body"] },
       scope: [{ names: { listAt: ["params"] }, in: [["body"]] }],
       summary: "A function: its parameters are names for its body.",
     },
@@ -225,16 +225,18 @@ export function formulaEvaluators(profile: FormulaProfile = {}): Readonly<Record
         if (missing !== undefined && missing(reached)) return fail("#N/A", "The path reaches no value.");
         return ok(reached);
       };
-      // The step documents of a path are its parts when the kind ref has a deep shape. They evaluate first, in order.
-      const computed = parts.length > 0;
+      const held = (ctx: Context): Failed | undefined => {
+        if (head === undefined || !Object.hasOwn(ctx.names, head)) return undefined;
+        const bound = ctx.names[head];
+        return bound instanceof Held ? { ok: false, error: bound.error } : undefined;
+      };
+      if (parts.length === 0) return (ctx, rt) => held(ctx) ?? give(rt.resolve(ctx, path));
+      // The step documents of a path are its parts when the kind ref has a deep shape. They evaluate first, in order,
+      // thus the error of a step comes before the error of a binding that the path reads (FORMULA.STEPS).
       return (ctx, rt) => {
-        if (head !== undefined && Object.hasOwn(ctx.names, head)) {
-          const bound = ctx.names[head];
-          if (bound instanceof Held) return { ok: false, error: bound.error };
-        }
-        if (!computed) return give(rt.resolve(ctx, path));
         const steps = valuesOf(parts, ctx, rt);
-        return Array.isArray(steps) ? give(rt.resolve(ctx, fill(steps) as readonly unknown[])) : steps;
+        if (!Array.isArray(steps)) return steps;
+        return held(ctx) ?? give(rt.resolve(ctx, fill(steps) as readonly unknown[]));
       };
     }),
 
@@ -472,18 +474,60 @@ export function formulaEvaluators(profile: FormulaProfile = {}): Readonly<Record
   };
 }
 
+/**
+ * This function makes the hook `known` of the formula kit for one profile (STATIC.KNOWN). The evaluator
+ * `formula.op` knows an operation of `lazy` or of `ops`. A profile whose `ops` is a function answers through a call
+ * of that function. A function that throws counts as an answer, because the run then gives `#CALC!`. The evaluator
+ * `formula.ext` knows an extension of `ext` and each standard extension. The hook knows each name of the other
+ * evaluators.
+ *
+ * @param profile - The operations and the extensions of the language.
+ * @returns The hook: `true`, or the reason of the `#NAME?` that the evaluator gives in a run.
+ */
+export function formulaKnown(profile: FormulaProfile = {}): (path: readonly Key[], evaluator: string) => true | string {
+  const hasOp = (name: string): boolean => {
+    if (profile.lazy !== undefined && Object.hasOwn(profile.lazy, name)) return true;
+    const ops = profile.ops;
+    if (ops === undefined) return false;
+    if (typeof ops !== "function") return Object.hasOwn(ops, name);
+    try {
+      return ops(name) !== undefined;
+    } catch {
+      return true;
+    }
+  };
+  const hasExt = (name: string): boolean => (profile.ext !== undefined && Object.hasOwn(profile.ext, name)) || Object.hasOwn(STD_EXT, name);
+  return (path, evaluator) => {
+    if (evaluator !== "formula.op" && evaluator !== "formula.ext") return true;
+    // The evaluators give the same reasons when they do not find the name.
+    const name = path.slice(1).join(".");
+    if (evaluator === "formula.op") return hasOp(name) ? true : `The language has no operation ${name}.`;
+    return hasExt(name) ? true : `The language has no extension ${name}.`;
+  };
+}
+
 /**
  * This function makes a machine for a formula language. The machine has the kinds and the evaluators of the
- * formula kit. It also has the kinds, the evaluators and the walkers that the language adds.
+ * formula kit. It also has the kinds, the evaluators and the walkers that the language adds. Its hook `known` comes
+ * from the profile (`formulaKnown`). A hook `known` of the language answers each name that the kit knows.
  *
  * @param profile - The operations and the rules of the language.
  * @param more - The parts of a machine that the language adds. Its kinds win over the kinds of the kit.
  * @returns The machine.
  */
 export function formulaMachine(profile: FormulaProfile = {}, more: Partial<Machine> = {}): Machine {
+  const kit = formulaKnown(profile);
+  // An evaluator or a runner of the language with the name of an evaluator of the kit replaces it, and the kit does not answer for it.
+  const replaced = (name: string): boolean => (more.evaluators !== undefined && Object.hasOwn(more.evaluators, name)) || (more.runners !== undefined && Object.hasOwn(more.runners, name));
+  const theirs = more.known;
+  const known = (path: readonly Key[], evaluator: string): true | string => {
+    const answer = replaced(evaluator) ? true : kit(path, evaluator);
+    return answer === true && theirs !== undefined ? theirs(path, evaluator) : answer;
+  };
   return {
     ...more,
     world: { kinds: { ...formulaKinds(), ...more.world?.kinds }, defaults: { ...more.world?.defaults } },
     evaluators: { ...formulaEvaluators(profile), ...more.evaluators },
+    known,
   };
 }