@mark1russell7/coeval 0.8.0 → 0.10.0

package/package.json

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

@@ -32,7 +32,7 @@ import { type Definitions, STD_DEFINITIONS } from "./reference.ts";
 import { STD_EVALUATORS } from "./stdlib.ts";
 import { sameValue } from "./agree.ts";
 import { type Random, random } from "./generate.ts";
-import { type Kind, type LazyRule, type Shape, type World, type WorldEntry, isKind, isNamespace, lookupKind } from "./world.ts";
+import { type Kind, type LazyRule, type Shape, type World, type WorldEntry, effectsOfVerb, isKind, isNamespace, lookupKind } from "./world.ts";
 
 /*
  * The conformance tests of one evaluator (K92, R7 P3, D36). `conforms` calls the code of one evaluator or runner
@@ -85,8 +85,9 @@ export interface Finding {
 /** The options of `conforms`. */
 export interface ConformOptions {
   /**
-   * The verb that the evaluator serves. The default is `eval`. The facts of a contract (`effects`, `pure` and `lazy`)
-   * describe only `eval`, thus `conforms` checks C2, C3 and C4 only for `eval` (D23).
+   * The verb that the evaluator serves. The default is `eval`. The facts `pure` and `lazy` of a contract describe only
+   * `eval`, thus `conforms` checks C3 and C4 only for `eval` (D23). `conforms` checks C2 for each verb that the
+   * contract declares effects for: `eval`, and each verb with an entry in `verbEffects` (D49).
    */
   readonly verb?: string;
   /**
@@ -276,6 +277,8 @@ interface Contract {
   readonly lazy: readonly LazyRule[] | undefined;
   /** `true` when the facts describe the verb: they describe only `eval`. */
   readonly describes: boolean;
+  /** `true` when the contract declares the effects of the verb: for `eval`, and for a verb in `verbEffects`. */
+  readonly declares: boolean;
   readonly caps: readonly Cap[];
 }
 
@@ -487,13 +490,16 @@ function typesNaming(world: World, name: string, verb: string): readonly TypeRef
 /** This function gives the facts of the kind of a type. The hook `facts` of the machine wins over the contract. */
 function contractOf(env: Env, kind: Kind, typePath: readonly Key[], caps: readonly Cap[] | undefined): Contract {
   const facts = env.machine.facts?.(typePath, env.name);
-  const effects = kind.effects;
+  // A verb without a declaration keeps the effects of eval for the capabilities of the probes, as before D49.
+  const own = effectsOfVerb(kind, env.verb);
+  const effects = own ?? kind.effects;
   const declared: readonly Cap[] = effects === undefined ? [] : effects === "type" ? [typePath] : effects;
   return {
     declared,
     pure: (facts?.pure ?? kind.pure) === true,
     lazy: facts?.lazy ?? kind.lazy,
     describes: env.verb === "eval",
+    declares: own !== undefined,
     caps: caps ?? [...declared, "probe"],
   };
 }
@@ -872,13 +878,15 @@ function checkShot(env: Env, sample: Sample, contract: Contract, scenario: Scena
       report(env, "C1", `The code gives its effect ${effect.kind} ${capsText(effect.context.caps)}, and its document has ${capsText(docCaps)}.`, probe);
     }
   }
-  if (contract.describes) {
-    // C2: only the declared effects.
+  if (contract.declares) {
+    // C2: only the declared effects of the verb (VERB.EFFECTS).
     for (const effect of shot.caused) {
       if (!permits(contract.declared, effect.kind)) {
-        report(env, "C2", `The code causes the effect ${effect.kind}, and the contract of ${sample.type} declares ${contract.declared.length === 0 ? "no effects" : capsText(contract.declared)}.`, probe);
+        report(env, "C2", `The code causes the effect ${effect.kind}, and the contract of ${sample.type} declares ${contract.declared.length === 0 ? "no effects" : capsText(contract.declared)}${env.verb === "eval" ? "" : ` for the verb ${env.verb}`}.`, probe);
       }
     }
+  }
+  if (contract.describes) {
     // C4: a pure kind causes no effect.
     const first = shot.caused[0];
     if (contract.pure && first !== undefined) report(env, "C4", `The kind ${sample.type} is pure, and the code causes the effect ${first.kind}.`, probe);

package/src/evaluate.ts

@@ -913,6 +913,8 @@ class Session implements Runtime {
     const free = isFree(reading.root, ctx, path);
     // A kind that sets another self can give the old self on, as the parent of a node of a tree does (READS.KEPT).
     if (!free && path[0] === "self" && !reading.self) this.keep(reading, ["self"]);
+    // A free read of the whole root self already holds what a kept read of self holds, as the root of a tree reads it.
+    else if (free && path.length === 1 && path[0] === "self") reading.self = true;
     let found: Resolution;
     try {
       found = this.find(ctx, path, compiled, hops);

package/src/facts.ts

@@ -8,7 +8,8 @@ import { type DocVisit, declaredEffects, walk } from "./static.ts";
 
 /**
  * One read of a document: a free reference, with its marks (FACTS.READS). A plan resolves the path of the reference
- * when it evaluates the reference. The static read covers each path that the plan resolves there (FACTS.SOUND).
+ * when it evaluates the reference. The static read covers each path that the plan resolves there (FACTS.SOUND). A
+ * root that a kind declares in `reads` is a read too, with the path of the root alone.
  */
 export interface StaticRead {
   /** The root of the path. */
@@ -34,7 +35,10 @@ export interface StaticRead {
 
 /** The static facts of one document (D24). They depend only on the document and the machine, not on a context. */
 export interface DocFacts {
-  /** The free references, in the order of the document (FACTS.READS). A reference to a name that a kind binds is not here. */
+  /**
+   * The free references, in the order of the document (FACTS.READS). A reference to a name that a kind binds is not
+   * here. The roots that a kind declares in `reads` are here too, each one at the place of its document.
+   */
   readonly reads: readonly StaticRead[];
   /** `"run"` when one kind of the document is on the run side (FACTS.SIDE). */
   readonly side: Side;
@@ -146,7 +150,8 @@ function partLazy(above: Above, parent: DocVisit, slot: readonly Key[]): boolean
  * by the contracts of its kinds:
  *
  * - `reads`: each free reference, with the root and the keys of its path. A read under a lazy part has the mark
- *   `lazy`, for example a read in a branch of `if`. A read after a step document has `exact: false`.
+ *   `lazy`, for example a read in a branch of `if`. A read after a step document has `exact: false`. A kind that
+ *   declares `reads` adds a read of each of its roots at each document of the kind.
  * - `side` and `effects`: from the contract of each kind.
  * - `pure`: each kind declares `pure`, and the document has no effect and is not volatile.
  * - `volatile`: a kind, an operation or a step document declares `volatile`, or the host marks a read.
@@ -200,13 +205,22 @@ export function factsOf(machine: Machine, doc: unknown, options: FactsOptions =
       }
       const code = codeOf(world, v.declared ? undefined : v.doc.own, kind, verb, "eval");
       const answer = code.name === undefined ? undefined : hook?.(v.typePath ?? [], code.name);
+      let roots: readonly Root[] | undefined;
       if (code.described) {
         note(answer?.pure ?? kind.pure, answer?.volatile ?? kind.volatile);
         above.set(v, { lazy, rules: answer?.lazy ?? kind.lazy });
+        roots = answer?.reads ?? kind.reads;
       } else {
         // The contract of the kind does not describe this code. Only the hook can.
         note(answer?.pure, answer?.volatile);
         above.set(v, { lazy, rules: answer?.lazy ?? EACH });
+        roots = answer?.reads;
+      }
+      // The code of the kind resolves each of these roots as a whole, at the place of its document (FACTS.KIND-READS).
+      for (const root of roots ?? NONE) {
+        const read: StaticRead = { root, keys: NONE, exact: true, lazy, address: false, path: [root], place: tight(v.place), at: tight(v.at) };
+        reads.push(read);
+        if (options.volatile?.(read) === true) volatile = true;
       }
       if (kind.side === "run") side = "run";
       // check and effectsOf read the declared effects with the same function (D27).

package/src/formula.ts

@@ -4,7 +4,7 @@ import { type CompiledPath, type Context, type Resolution, compilePath, valueOfT
 import { type EvalError, type Failed, type Result, Failure, fail, ok, thrown } from "./errors.ts";
 import { type Code, type CompileInput, type CompiledEvaluator, type CompiledPart, type Evaluator, type Machine, type Runtime, resolveCompiled } from "./evaluate.ts";
 import { type MachinePart, mergeMachines } from "./merge.ts";
-import { type Domain, type ValueType, HEADER_KEYS, STD_DOMAINS, callable, fieldOf, fits, fnOf, holdsEnvelope, isPrecise, isUnknown, itemOf, join, stepType, typeText } from "./types.ts";
+import { type Domain, type ValueType, HEADER_KEYS, STD_DOMAINS, callable, fieldOf, fits, fnOf, holdsEnvelope, isPrecise, isUnknown, itemOf, join, member, stepType, typeText } from "./types.ts";
 import type { TypeInput, TypeRule } from "./typing.ts";
 import { decodeDomain, domainTypeOf } from "./codec.ts";
 
@@ -42,6 +42,8 @@ export type ExtFn = (data: Json, context: Context, domains?: Readonly<Record<str
  *   evaluates, and one failed part gives its own error. Without it, the first error stops the evaluation.
  * - `pure`: the pure operations, for `factsOf` (D24). `true` names each operation that is not volatile. The default
  *   names no operation.
+ * - `pureExt`: the pure extensions of `ext`, by their name, for `factsOf` and the folds of a plan (PLAN.FOLD, D47).
+ *   The default names no extension. A standard extension is pure without a name here.
  * - `volatile`: the operations whose results can change while their arguments stay the same, for example a clock.
  * - `sigs`: the signatures of the operations, by their name, for a check of types (TYPE.SIGNATURE). A list gives
  *   overloads. An operation without a signature takes and gives `unknown` (TYPE.GRADUAL).
@@ -61,13 +63,14 @@ export interface FormulaProfile {
   readonly check?: (value: unknown, op: string) => Result | undefined;
   readonly combine?: (errors: readonly EvalError[]) => EvalError;
   readonly pure?: true | readonly string[];
+  readonly pureExt?: readonly string[];
   readonly volatile?: readonly string[];
   readonly sigs?: Readonly<Record<string, Signature | readonly Signature[]>> | ((name: string) => Signature | readonly Signature[] | undefined);
 }
 
 /**
- * The signature of an operation: the value types of its parameters and of its result (TYPE.SIGNATURE). A parameter of
- * the type `unknown` at the end of `params` is optional. A later version can add a key, for example the type that a
+ * The signature of an operation: the value types of its parameters and of its result (TYPE.SIGNATURE). A parameter at
+ * the end of `params` is optional when `undefined` is a member of its type, for example `unknown`. A later version can add a key, for example the type that a
  * true result proves.
  */
 export interface Signature {
@@ -209,9 +212,13 @@ export function formulaKinds(): Readonly<Record<string, WorldEntry>> {
   return kinds as Readonly<Record<string, WorldEntry>>;
 }
 
-/** This function gives the type of a value of a profile: the value itself as `one`. `undefined` and a function give `unknown`. */
+/**
+ * This function gives the type of a value of a profile: the value itself as `one`. `undefined` gives the base type
+ * `undefined`, because JSON and thus `one` cannot hold it (D48). A function gives `unknown`.
+ */
 function valueType(value: unknown): ValueType {
-  return value === undefined || typeof value === "function" ? "unknown" : { one: [value as Json] };
+  if (value === undefined) return "undefined";
+  return typeof value === "function" ? "unknown" : { one: [value as Json] };
 }
 
 /** This function tells if a value has the form of a signature: a record with `params` as a list, and `to`. */
@@ -236,14 +243,14 @@ function listText(names: readonly string[]): string {
 }
 
 /**
- * This function tells if a signature takes a count of arguments. A parameter of the type `unknown` at the end is
- * optional, because a missing argument is `undefined`.
+ * This function tells if a signature takes a count of arguments. A parameter at the end is optional when its type
+ * holds `undefined`, because a missing argument is `undefined`. `unknown` and the base type `undefined` hold it.
  *
  * @returns `undefined` when the number is correct, or else the text of the numbers that the signature takes.
  */
 function arityOf(sig: Signature, count: number, domains: Machine["domains"]): string | undefined {
   let least = sig.params.length;
-  while (least > 0 && isUnknown(sig.params[least - 1], domains)) least -= 1;
+  while (least > 0 && member(undefined, sig.params[least - 1] as ValueType, domains)) least -= 1;
   const most = sig.rest === undefined ? sig.params.length : Number.POSITIVE_INFINITY;
   if (count >= least && count <= most) return undefined;
   if (most === Number.POSITIVE_INFINITY) return `at least ${argumentsText(least)}`;
@@ -487,6 +494,8 @@ function formulaTypes(profile: FormulaProfile): Readonly<Record<string, TypeRule
         const name = nameOf(input);
         const own = profile.ext !== undefined && Object.hasOwn(profile.ext, name);
         if (own) return "unknown";
+        // The standard extensions give the values that JSON cannot write, thus each has a base type (D48).
+        if (name === "undefined") return "undefined";
         if (name === "number") return "number";
         return name === "domain" ? domainTypeOf(input.doc.value, input.machine.domains) : "unknown";
       },
@@ -498,19 +507,119 @@ function formulaTypes(profile: FormulaProfile): Readonly<Record<string, TypeRule
  * This function makes the evaluators of the formula kit for one language. Each evaluator compiles its document
  * one time into code. Each evaluator also holds its type rule, for a check of types (TYPE.SYNTH).
  *
+ * Equal profiles give the same evaluator objects (COMPOSE.UNIFY, D46). Thus two machines of one profile merge without
+ * a conflict. Each call gives a new record. Each evaluator object is frozen, because many machines can share it.
+ *
  * @param profile - The operations and the rules of the language.
  * @returns The evaluators, by their name.
  */
 export function formulaEvaluators(profile: FormulaProfile = {}): Readonly<Record<string, Evaluator>> {
+  return { ...kitOf(profile).evaluators };
+}
+
+/** This function makes new evaluators of the formula kit for the fields of one profile. */
+function makeEvaluators(profile: FormulaProfile): Readonly<Record<string, Evaluator>> {
   const evaluators = formulaCode(profile);
   const types = formulaTypes(profile);
   const out: Record<string, Evaluator> = {};
   for (const name of Object.keys(evaluators)) {
     const evaluator = evaluators[name] as CompiledEvaluator;
     const type = Object.hasOwn(types, name) ? types[name] : undefined;
-    out[name] = type === undefined ? evaluator : { compile: evaluator.compile, type };
+    out[name] = Object.freeze(type === undefined ? evaluator : { compile: evaluator.compile, type });
+  }
+  return Object.freeze(out);
+}
+
+/** The keys of a profile that the kit reads. The kit ignores each other key. */
+const PROFILE_KEYS = /* @__PURE__ */ Object.freeze([
+  "ops",
+  "lazy",
+  "ext",
+  "truthy",
+  "otherwise",
+  "logic",
+  "omit",
+  "missing",
+  "check",
+  "combine",
+  "pure",
+  "pureExt",
+  "volatile",
+  "sigs",
+] as const satisfies readonly (keyof FormulaProfile)[]);
+
+/** The evaluators and the hooks of the formula kit for one profile, with the fields that made them. */
+interface Kit {
+  readonly fields: FormulaProfile;
+  readonly evaluators: Readonly<Record<string, Evaluator>>;
+  readonly known: (path: readonly Key[], evaluator: string) => true | string;
+  readonly facts: (path: readonly Key[], code: string) => KindFacts | undefined;
+}
+
+/** The number of recent kits that a profile in a new object can find by its fields. */
+const RECENT_KITS = 16;
+
+/** The kit of each profile object. A kit goes when its profile object goes. */
+const kitsByProfile = /* @__PURE__ */ new WeakMap<object, Kit>();
+
+/** The recent kits, the most recent first. The list holds `RECENT_KITS` kits or fewer. */
+const recentKits: Kit[] = [];
+
+/**
+ * This function gives the canonical form of a profile: a frozen record of the fields that the kit reads. A field
+ * with the value `undefined` is absent, but `otherwise` is present when the profile has it as an own key. A list
+ * is a frozen copy. Each other value stays the same object.
+ */
+function fieldsOf(profile: FormulaProfile): FormulaProfile {
+  const out: Record<string, unknown> = {};
+  for (const key of PROFILE_KEYS) {
+    if (key === "otherwise" ? !Object.hasOwn(profile, key) : profile[key] === undefined) continue;
+    const value: unknown = profile[key];
+    out[key] = Array.isArray(value) ? Object.freeze([...(value as unknown[])]) : value;
+  }
+  return Object.freeze(out);
+}
+
+/**
+ * This function tells if two canonical forms are equal. They must have the same keys. A function, a record and a host
+ * value are equal only to themselves. Two lists are equal when their items are the same, in order.
+ */
+function sameFields(a: FormulaProfile, b: FormulaProfile): boolean {
+  const left = a as Readonly<Record<string, unknown>>;
+  const right = b as Readonly<Record<string, unknown>>;
+  const keys = Object.keys(left);
+  if (keys.length !== Object.keys(right).length) return false;
+  return keys.every((key) => {
+    if (!Object.hasOwn(right, key)) return false;
+    const x = left[key];
+    const y = right[key];
+    if (Object.is(x, y)) return true;
+    return Array.isArray(x) && Array.isArray(y) && x.length === y.length && x.every((item, index) => Object.is(item, y[index]));
+  });
+}
+
+/**
+ * This function gives the kit of a profile (D46). A profile object that the kit knows, with the same fields, gives its
+ * kit. Then a recent kit with equal fields serves a new profile object. Else the function makes a new kit from the
+ * canonical form. Thus a later change of a field of the profile object gives a new kit, and an old kit does not change.
+ */
+function kitOf(profile: FormulaProfile): Kit {
+  const fields = fieldsOf(profile);
+  const known = kitsByProfile.get(profile);
+  if (known !== undefined && sameFields(known.fields, fields)) return known;
+  const index = recentKits.findIndex((kit) => sameFields(kit.fields, fields));
+  let kit: Kit;
+  if (index >= 0) {
+    kit = recentKits[index] as Kit;
+    recentKits.splice(index, 1);
+  } else {
+    const hook = makeKnown(fields);
+    kit = { fields, evaluators: makeEvaluators(fields), known: hook, facts: makeFacts(fields, hook) };
   }
-  return out;
+  recentKits.unshift(kit);
+  if (recentKits.length > RECENT_KITS) recentKits.length = RECENT_KITS;
+  kitsByProfile.set(profile, kit);
+  return kit;
 }
 
 /** This function makes the code of the evaluators of the formula kit, without their type rules. */
@@ -848,10 +957,17 @@ function formulaCode(profile: FormulaProfile): Readonly<Record<string, CompiledE
  * `formula.ext` knows an extension of `ext` and each standard extension. The hook knows each name of the other
  * evaluators.
  *
+ * Equal profiles give the same hook (D46).
+ *
  * @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 {
+  return kitOf(profile).known;
+}
+
+/** This function makes a new hook `known` for the fields of one profile. */
+function makeKnown(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;
@@ -873,10 +989,13 @@ export function formulaKnown(profile: FormulaProfile = {}): (path: readonly Key[
   };
 }
 
-/** The facts of an extension of the profile. It gets the context, thus it can read outside `resolve`. */
+/**
+ * The facts of an extension of the profile that `pureExt` does not name. It gets the context, thus it can read outside
+ * `resolve`.
+ */
 const NOT_PURE: KindFacts = /* @__PURE__ */ Object.freeze({ pure: false });
 
-/** The facts of a standard extension. */
+/** The facts of a standard extension, and of an extension that `pureExt` names. */
 const PURE: KindFacts = /* @__PURE__ */ Object.freeze({ pure: true });
 
 /** The lazy rule of a lazy operation: it covers each argument. */
@@ -888,19 +1007,30 @@ const EACH_PART: readonly LazyRule[] = /* @__PURE__ */ Object.freeze([/* @__PURE
  *
  * - An operation of `lazy` has a lazy rule for each argument.
  * - An operation is pure when the profile names it in `pure`, or when `pure` is `true`. A volatile operation is not pure.
- * - A standard extension is pure. An extension of the profile gets the context, thus it is not pure.
+ * - A standard extension is pure. An extension of the profile is pure only when the profile names it in `pureExt` (D47).
+ *   Such an extension keeps C4: it reads the context only through `resolve`.
+ *
+ * Equal profiles give the same hook (D46).
  *
  * @param profile - The operations, the extensions and their facts.
  * @returns The hook: the facts of a name, or `undefined` for the facts of the contract.
  */
 export function formulaFacts(profile: FormulaProfile = {}): (path: readonly Key[], code: string) => KindFacts | undefined {
+  return kitOf(profile).facts;
+}
+
+/** This function makes a new hook `facts` for the fields of one profile, with the hook `known` of the same fields. */
+function makeFacts(profile: FormulaProfile, known: (path: readonly Key[], evaluator: string) => true | string): (path: readonly Key[], code: string) => KindFacts | undefined {
   const volatile = new Set(profile.volatile ?? []);
   const pure = profile.pure === true ? undefined : new Set(profile.pure ?? []);
-  const known = formulaKnown(profile);
+  const pureExt = new Set(profile.pureExt ?? []);
   return (path, code) => {
     if (code !== "formula.op" && code !== "formula.ext") return undefined;
     const name = path.slice(1).join(".");
-    if (code === "formula.ext") return profile.ext !== undefined && Object.hasOwn(profile.ext, name) ? NOT_PURE : Object.hasOwn(STD_EXT, name) ? PURE : undefined;
+    if (code === "formula.ext") {
+      if (profile.ext !== undefined && Object.hasOwn(profile.ext, name)) return pureExt.has(name) ? PURE : NOT_PURE;
+      return Object.hasOwn(STD_EXT, name) ? PURE : undefined;
+    }
     // An operation that the language does not have gives #NAME?. The kit gives it no facts.
     if (known(path, code) !== true) return undefined;
     const isVolatile = volatile.has(name);
@@ -922,14 +1052,16 @@ export function formulaFacts(profile: FormulaProfile = {}): (path: readonly Key[
  * The kit gives the domains of the kernel (`STD_DOMAINS`). Thus a domain of the language with the name `number` is a
  * conflict. The language names `["domains", "number"]` in `replaces` to replace it.
  *
+ * Equal profiles give the same evaluators and the same hooks (COMPOSE.UNIFY, D46). Thus two machines of one profile
+ * merge, also when each adds its own language. Two profiles with different fields give different evaluators, and
+ * their machines conflict at each evaluator name of the kit.
+ *
  * @param profile - The operations and the rules of the language.
  * @param more - The parts of a machine that the language adds, with the paths of the entries that it replaces.
  * @returns The machine.
  * @throws {MergeError} The language and the kit have a conflict.
  */
 export function formulaMachine(profile: FormulaProfile = {}, more: MachinePart = {}): Machine {
-  return mergeMachines(
-    { world: { kinds: formulaKinds() }, evaluators: formulaEvaluators(profile), domains: STD_DOMAINS, known: formulaKnown(profile), facts: formulaFacts(profile) },
-    more,
-  );
+  const kit = kitOf(profile);
+  return mergeMachines({ world: { kinds: formulaKinds() }, evaluators: { ...kit.evaluators }, domains: STD_DOMAINS, known: kit.known, facts: kit.facts }, more);
 }

package/src/index.ts

@@ -49,8 +49,10 @@ export {
   type Shape as PartShape,
   type Side,
   type TreeContract,
+  type VerbEffects,
   type World,
   type WorldEntry,
+  effectsOfVerb,
   entriesAsJson,
   equationType,
   isAlias,
@@ -202,7 +204,9 @@ export {
   type Typing,
   type WalkOptions,
   type WalkProblem,
+  type WorldIssue,
   check,
+  checkWorld,
   mapRefs,
   refsOf,
   typeCheck,

package/src/providers.ts

@@ -235,6 +235,7 @@ function samplesAt(values: readonly unknown[], closed: boolean, depth: number):
   let lists = false;
   for (const value of values) {
     if (value === null) bases.add("null");
+    else if (value === undefined) bases.add("undefined");
     else if (typeof value === "boolean") bases.add("bool");
     else if (typeof value === "number") bases.add("number");
     else if (typeof value === "string") bases.add("text");
@@ -243,10 +244,10 @@ function samplesAt(values: readonly unknown[], closed: boolean, depth: number):
       // A hole of a list holds undefined, thus a loop by index reads it too.
       for (let index = 0; index < value.length; index += 1) items.push(value[index]);
     } else if (isRecord(value)) records.push(value);
-    // A value without a type of the kernel, for example a function or undefined, has each type.
+    // A value without a type of the kernel, for example a function, has each type.
     else return "unknown";
   }
-  for (const base of ["null", "bool", "number", "text"]) if (bases.has(base)) types.push(base);
+  for (const base of ["null", "undefined", "bool", "number", "text"]) if (bases.has(base)) types.push(base);
   if (lists) types.push({ list: samplesAt(items, closed, depth + 1) });
   if (records.length > 0) {
     // All records join into one record. A field that a record does not have is optional.
@@ -268,7 +269,7 @@ function samplesAt(values: readonly unknown[], closed: boolean, depth: number):
  * This function infers a value type from sample values (TYPE.SAMPLES), as a type provider of F# does. A host uses it
  * for the type of a root, for example from some events.
  *
- * - `null`, a truth value, a number and a text give their base types, not their values.
+ * - `null`, `undefined`, a truth value, a number and a text give their base types, not their values.
  * - The items of each list join into one type of items.
  * - All records join into one record with each key of the samples. A key that a record does not have is optional.
  * - Values of different forms give a union, as `join` gives. No samples give `never`.

package/src/reference.ts

@@ -634,10 +634,13 @@ function plainValue(value: unknown, open: readonly object[]): Result {
 
 /**
  * TREE.LAZY, TREE.PARENT, TREE.SIBLING and TREE.ERROR: a node of an open tree gives its thing, and the root of a new
- * tree gives its JSON. A step on the thing reads an attribute, and a failed attribute throws its own error.
+ * tree gives its JSON. A step on the thing reads an attribute, and a failed attribute throws its own error. The node
+ * reads `self` only through `resolve` (C4, TREE.SELF).
  */
-const treeDefinition: EvalFn = ({ parts, context, kind, place, machine, typePath }) => {
-  const outer = refNodeOf(context.self);
+const treeDefinition: EvalFn = ({ parts, context, kind, place, machine, typePath, resolve: walk }) => {
+  const reached = walk(["self"]);
+  const parent: Thing | undefined = reached.ok ? reached.thing : undefined;
+  const outer = refNodeOf(parent);
   const nested = outer !== undefined && outer.tree.open;
   const found = machine === undefined || typePath.length === 0 ? undefined : lookupKind(machine.world, typePath);
   const contract = found?.ok === true ? found.kind.tree : undefined;
@@ -661,7 +664,7 @@ const treeDefinition: EvalFn = ({ parts, context, kind, place, machine, typePath
     type: kind,
     label: `node ${kind}`,
     deref: (key): Thing | undefined => {
-      if (key === "parent") return context.self;
+      if (key === "parent") return parent;
       if (key === "type") return kind;
       const result = attributeOf(node, String(key));
       if (result === undefined || result.ok) return result?.ok === true ? result.value : undefined;