@mark1russell7/coeval 0.8.0 → 0.9.0

package/package.json

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

@@ -498,19 +498,118 @@ 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",
+  "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 out;
+  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) };
+  }
+  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 +947,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;
@@ -890,13 +996,19 @@ const EACH_PART: readonly LazyRule[] = /* @__PURE__ */ Object.freeze([/* @__PURE
  * - 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.
  *
+ * 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);
   return (path, code) => {
     if (code !== "formula.op" && code !== "formula.ext") return undefined;
     const name = path.slice(1).join(".");
@@ -922,14 +1034,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

@@ -202,7 +202,9 @@ export {
   type Typing,
   type WalkOptions,
   type WalkProblem,
+  type WorldIssue,
   check,
+  checkWorld,
   mapRefs,
   refsOf,
   typeCheck,

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;

package/src/static.ts

@@ -1,5 +1,5 @@
 import { type Envelope, type Json, type Key, isKey, isRecord, typeName } from "./doc.ts";
-import { type Kind, type World, equationType } from "./world.ts";
+import { type Kind, type Namespace, type World, type WorldEntry, equationType, isKind, isNamespace } from "./world.ts";
 import { ask } from "./ladder.ts";
 import { type PartSlot, partsOf, scopesOf } from "./parts.ts";
 import { type Cap, type Context, type Root, ROOTS, context, isRef, walkerOf, worldThing } from "./deref.ts";
@@ -508,6 +508,74 @@ export function typeCheck(machine: Machine, doc: unknown, options: CheckOptions
   return { type: pass.type, issues: pass.issues.length === 0 ? issues : [...issues, ...pass.issues], places: pass.places };
 }
 
+/**
+ * A problem of a world that `checkWorld` finds before a document exists (STATIC.COVERAGE). Each document of the
+ * kind gives this problem for the verb, thus `check` with the verb finds it too.
+ */
+export interface WorldIssue {
+  /** The code of the problem. `#NOEVAL`: no rung of the ladder gives an evaluator for the verb. */
+  readonly code: "#NOEVAL";
+  /** The keys of the kind from the root of the world. For a fallback kind, the keys of its namespace. */
+  readonly kind: readonly Key[];
+  /** `true` for the fallback kind of a namespace or of the world. */
+  readonly fallback?: true;
+  /** The verb without an evaluator. */
+  readonly verb: string;
+  readonly reason: string;
+}
+
+/** This function tells if a table of verbs has an entry for a verb. */
+function hasVerb(table: Readonly<Record<string, string>> | undefined, verb: string): boolean {
+  return table !== undefined && Object.hasOwn(table, verb);
+}
+
+/**
+ * This function checks the world of a machine before a document exists. It finds each kind that has no entry for a
+ * verb of the list, when the world has no default for that verb (STATIC.COVERAGE). A document of such a kind gets no
+ * evaluator for the verb, thus the check gives the same proof of coverage as a type system.
+ *
+ * The check visits each kind of each namespace, at each depth, and the fallback kind of each namespace and of the
+ * world. It does not follow an alias, because the kind of an alias has its own place. The check reads only the world.
+ *
+ * @param machine - The machine, for its world.
+ * @param verbs - The verbs that each kind of the language must answer, for example `eval`, `view` and `type`.
+ * @returns One issue for each kind and verb without an evaluator. The order is the order of the world, then the
+ *   order of the verbs. The fallback kind of a namespace comes after the entries of that namespace.
+ */
+export function checkWorld(machine: Machine, verbs: readonly string[]): readonly WorldIssue[] {
+  const world = machine.world;
+  const open = verbs.filter((verb) => !hasVerb(world.defaults, verb));
+  const out: WorldIssue[] = [];
+  if (open.length === 0) return out;
+  const visit = (kind: Kind, path: readonly Key[], fallback: boolean): void => {
+    const text = path.join(".");
+    const name = fallback ? (path.length === 0 ? "the fallback kind of the world" : `the fallback kind of ${text}`) : `the kind ${text}`;
+    for (const verb of open) {
+      if (hasVerb(kind.verbs, verb)) continue;
+      const reason = `${name.charAt(0).toUpperCase()}${name.slice(1)} has no entry for the verb ${verb}, and the world has no default for it.`;
+      out.push(fallback ? { code: "#NOEVAL", kind: path, fallback: true, verb, reason } : { code: "#NOEVAL", kind: path, verb, reason });
+    }
+  };
+  // The set holds the namespaces on the way, thus a namespace that holds itself does not loop.
+  const way = new Set<Namespace>();
+  const entries = (kinds: Readonly<Record<string, WorldEntry>>, path: readonly Key[]): void => {
+    for (const key of Object.keys(kinds)) {
+      const entry = kinds[key];
+      const here = [...path, key];
+      if (isKind(entry)) visit(entry, here, false);
+      else if (isNamespace(entry) && !way.has(entry)) {
+        way.add(entry);
+        entries(entry.kinds, here);
+        if (entry.fallback !== undefined) visit(entry.fallback, here, true);
+        way.delete(entry);
+      }
+    }
+  };
+  entries(world.kinds, []);
+  if (world.fallback !== undefined) visit(world.fallback, [], true);
+  return out;
+}
+
 /**
  * A runner under an evaluator in a check of a run. The run drives its steps without a wait, thus only a wait for an
  * effect of its runners fails (RUN.DRIVE-NESTED).

package/src/stdlib.ts

@@ -71,6 +71,8 @@ export const STD_WORLD: World = {
       // A node that nothing reads keeps its attributes without an evaluation (TREE.LAZY).
       pure: true,
       lazy: [{}],
+      // The code resolves self to find an open tree and the parent (C4, D44).
+      reads: ["self"],
       summary: "A node of a tree. Each part is an attribute that evaluates on demand, one time, with the node as self.",
     },
     box: {
@@ -79,6 +81,7 @@ export const STD_WORLD: World = {
       caps: [{ rule: "mask" }],
       pure: true,
       lazy: [{}],
+      reads: ["self"],
       summary: "A node of a tree, as panel. A formula in a box can read its parent and its siblings.",
     },
     math: {
@@ -396,11 +399,12 @@ function plainOf(value: unknown, path: Set<object>): Result {
  * step `type` gives its type. Another step reads an attribute through its ladder (TREE.LADDER). The rungs are a part of
  * the node, an equation of its kind and an equation `down` of the kind of its parent. A copy from the parent, then a
  * fold or a default, come last. A failed attribute throws `Failure` with its own error, thus a reference to it gives that error.
+ * The argument `outer` is the self of the context, that `treeNode` resolved. The node reads no root of the context directly (C4).
  */
-function treeThing(input: EvalInput, build: TreeBuild): HostThing {
+function treeThing(input: EvalInput, build: TreeBuild, outer: Thing | undefined): HostThing {
   const { parts, context, kind: type, place, machine } = input;
   const { tree, of } = contractOf(machine, input.typePath);
-  const above = stateOf(context.self);
+  const above = stateOf(outer);
   // Only a node of the same tree is a parent for the rungs `parent` and `copy`.
   const up = above !== undefined && above.build === build ? above : undefined;
   const cells = new Map<string, Cell>();
@@ -522,7 +526,7 @@ function treeThing(input: EvalInput, build: TreeBuild): HostThing {
     type,
     label: `node ${type}`,
     deref(key: Key): Thing | undefined {
-      if (key === "parent") return context.self;
+      if (key === "parent") return outer;
       if (key === "type") return type;
       const result = read(String(key));
       if (result === undefined) return undefined;
@@ -556,15 +560,24 @@ export function attributeTrace(node: Thing, attribute: string): AttributeTrace |
   return stateOf(node)?.trace(attribute);
 }
 
+/** The path of the root `self`. A node of the tree resolves it, thus the list of reads holds the read (C4). */
+const SELF_PATH: readonly Json[] = /* @__PURE__ */ Object.freeze(["self"]);
+
+/** The options of the resolution of `self`: the node needs no hops. */
+const NO_HOPS = /* @__PURE__ */ Object.freeze({ hops: false });
+
 /**
  * This function evaluates a node of the decorated tree. Inside an attribute of an open tree, the node gives its host
- * thing, and no attribute evaluates. Else the node is the root of a new tree, and it gives the JSON of the tree.
+ * thing, and no attribute evaluates. Else the node is the root of a new tree, and it gives the JSON of the tree. The
+ * node reads `self` through `resolve` (C4, D44). A machine that closes the root `self` thus gives no nested trees.
  */
 function treeNode(input: EvalInput): Result {
-  const above = stateOf(input.context.self);
-  if (above !== undefined && above.build.open) return ok(treeThing(input, above.build));
+  const found = input.resolve(SELF_PATH, NO_HOPS);
+  const outer = found.ok ? found.thing : undefined;
+  const above = stateOf(outer);
+  if (above !== undefined && above.build.open) return ok(treeThing(input, above.build, outer));
   const build: TreeBuild = { open: true };
-  const root = treeThing(input, build);
+  const root = treeThing(input, build, outer);
   try {
     return (stateOf(root) as NodeState).json(new Set());
   } finally {

package/src/world.ts

@@ -1,5 +1,5 @@
 import { type Envelope, type Json, type Key, type TypeRef, field, isRecord, typePath } from "./doc.ts";
-import type { Cap } from "./deref.ts";
+import type { Cap, Root } from "./deref.ts";
 import type { ValueType } from "./types.ts";
 
 /** The two sides of evaluation. `derive` is pure. `run` causes effects in order. */
@@ -114,11 +114,14 @@ export interface LazyRule {
  *   because the static facts do not see that read.
  * - `volatile`: `true` when its result can change while each read gives the same thing, for example a clock.
  * - `lazy`: the parts that an evaluation can skip and still give a value.
+ * - `reads`: the roots that the code of the kind resolves as a whole, with the path of one root. The static facts
+ *   give a read of each root at each document of the kind (D44). The tree node reads `self` this way.
  */
 export interface KindFacts {
   readonly pure?: boolean;
   readonly volatile?: boolean;
   readonly lazy?: readonly LazyRule[];
+  readonly reads?: readonly Root[];
 }
 
 /**