@mark1russell7/coeval 0.22.0 → 0.23.0

package/src/static.ts

@@ -103,6 +103,17 @@ function keysOf(trail: Trail | undefined): readonly Key[] {
 
 /** A visit with its paths as trails. It makes the keys of a path only when a reader asks for them. */
 class Visit implements DocVisit {
+  readonly doc: Envelope;
+  readonly declared: boolean;
+  readonly depth: number;
+  readonly names: ReadonlySet<string>;
+  readonly later: ReadonlySet<string>;
+  readonly slot: readonly Key[];
+  readonly parent: DocVisit | undefined;
+  readonly kind: Kind | undefined;
+  readonly typePath: readonly Key[] | undefined;
+  readonly address: true | undefined;
+  readonly caps: readonly Cap[] | undefined;
   readonly #place: Trail | undefined;
   readonly #at: Trail | undefined;
   readonly #bound: readonly string[];
@@ -111,20 +122,31 @@ class Visit implements DocVisit {
   constructor(
     place: Trail | undefined,
     at: Trail | undefined,
-    readonly doc: Envelope,
-    readonly declared: boolean,
-    readonly depth: number,
-    readonly names: ReadonlySet<string>,
-    readonly later: ReadonlySet<string>,
-    readonly slot: readonly Key[],
-    readonly parent: DocVisit | undefined,
-    readonly kind: Kind | undefined,
-    readonly typePath: readonly Key[] | undefined,
-    readonly address: true | undefined,
-    readonly caps: readonly Cap[] | undefined,
+    doc: Envelope,
+    declared: boolean,
+    depth: number,
+    names: ReadonlySet<string>,
+    later: ReadonlySet<string>,
+    slot: readonly Key[],
+    parent: DocVisit | undefined,
+    kind: Kind | undefined,
+    typePath: readonly Key[] | undefined,
+    address: true | undefined,
+    caps: readonly Cap[] | undefined,
     bound: readonly string[],
     expect: ValueType | undefined,
   ) {
+    this.doc = doc;
+    this.declared = declared;
+    this.depth = depth;
+    this.names = names;
+    this.later = later;
+    this.slot = slot;
+    this.parent = parent;
+    this.kind = kind;
+    this.typePath = typePath;
+    this.address = address;
+    this.caps = caps;
     this.#place = place;
     this.#at = at;
     this.#bound = bound;
@@ -691,6 +713,8 @@ export function equationsOf(kind: Kind): readonly Equation[] {
       out.push({ label: `tree.attributes.${name}.fold.combine`, term: declared.fold.combine, names: FOLD_NAMES, attribute: name, down: false });
     }
     if (declared.default !== undefined) out.push({ label: `tree.attributes.${name}.default`, term: declared.default, names: [], attribute: name, down: false });
+    // Only the equation is known before the run. The document that it gives is not known (TREE.HIGHER-CHECK, D126).
+    if (declared.higher !== undefined) out.push({ label: `tree.attributes.${name}.higher`, term: declared.higher, names: [], attribute: name, down: false });
     const collect = declared.collect === undefined ? undefined : collectOf(declared.collect);
     if (collect?.ok === true && !collect.names) {
       out.push({ label: `tree.attributes.${name}.collect.unit`, term: collect.unit, names: [], attribute: name, down: false });
@@ -885,15 +909,16 @@ function hasEntry(table: Readonly<Record<string, unknown>> | undefined, name: st
 /**
  * This function tells if a rung of the ladder can answer an attribute of a node (TREE.LADDER). An unknown parent can
  * be a node of each kind of the world, thus each name of `down` in the world can answer. A copy can always answer,
- * because `check` does not know a node without a parent.
+ * because `check` does not know a node without a parent. A kind with `forwards` can answer each other name, because the
+ * forwarded node is not known before the run (TREE.FORWARD-CHECK).
  */
 export function answered(world: World, node: SeenNode, name: string): boolean {
   if (node.own?.has(name) === true) return true;
   const tree = node.kind.tree;
-  if (hasEntry(tree?.equations, name)) return true;
+  if (hasEntry(tree?.equations, name) || (tree?.forwards !== undefined && tree.forwards !== name)) return true;
   if (node.parent === undefined ? downNames(world).has(name) : hasEntry(node.parent.kind.tree?.down, name)) return true;
   const declared = tree?.attributes !== undefined && Object.hasOwn(tree.attributes, name) ? tree.attributes[name] : undefined;
-  return declared !== undefined && (declared.copy === true || declared.fold !== undefined || declared.collect !== undefined || declared.default !== undefined);
+  return declared !== undefined && (declared.copy === true || declared.fold !== undefined || declared.collect !== undefined || declared.default !== undefined || declared.higher !== undefined);
 }
 
 /**
@@ -908,6 +933,7 @@ function equationIssues(machine: Machine, kind: Kind, kindText: string, options:
   const needs: Need[] = [];
   state.needs.set(kind, needs);
   for (const name of Object.keys(kind.tree?.attributes ?? {})) needs.push({ name, why: "the kind declares it", hidden: undefined });
+  if (typeof kind.tree?.forwards === "string" && !Object.hasOwn(STRUCTURAL, kind.tree.forwards)) needs.push({ name: kind.tree.forwards, why: "the kind forwards to it", hidden: undefined });
   const self: SeenNode = { kind, text: kindText, own: undefined, parent: undefined };
   for (const { label, term, names, attribute, down, contributes, at } of equationsOf(kind)) {
     const inner: CheckOptions = { names, ...(of === undefined ? {} : { declaredType: of }), ...(options.caps === undefined ? {} : { caps: [] }) };
@@ -926,6 +952,7 @@ function equationIssues(machine: Machine, kind: Kind, kindText: string, options:
  * structural step gets no read. A tree kind of the run side contradicts the evaluation on demand of its attributes. A
  * declaration `circular` without a start value or with a bad limit gives `#VALUE!` (TREE.CIRCULAR-CHECK). A declaration
  * `collect` without its form gives `#VALUE!` too (TREE.COLLECT). So does an entry of `at` without its form (TREE.AT-CHECK).
+ * A field `forwards` that is not a text gives `#VALUE!`, and a structural name gives `#NAME?` (TREE.FORWARD-CHECK).
  */
 function contractIssues(kind: Kind, kindText: string): readonly Issue[] {
   const out: Issue[] = [];
@@ -947,6 +974,11 @@ function contractIssues(kind: Kind, kindText: string): readonly Issue[] {
     const rule = atRuleOf(declared);
     if (!rule.ok) out.push({ code: "#VALUE!", place: [], reason: `The kind ${kindText} has a bad entry tree.at.${name}. ${rule.reason}` });
   }
+  const forwards: unknown = tree?.forwards;
+  if (forwards !== undefined && typeof forwards !== "string") out.push({ code: "#VALUE!", place: [], reason: `The kind ${kindText} has a bad field tree.forwards. It must be a text.` });
+  if (typeof forwards === "string" && Object.hasOwn(STRUCTURAL, forwards)) {
+    out.push({ code: "#NAME?", place: [], reason: `The kind ${kindText} gives the reserved attribute tree.forwards: ${String(STRUCTURAL[forwards])}.` });
+  }
   if (kind.side === "run") {
     out.push({ code: "#CALC!", place: [], reason: `The tree kind ${kindText} is on the run side: a node evaluates its attributes on demand, thus in no fixed order.` });
   }

package/src/stdlib.ts

@@ -18,7 +18,19 @@ import {
 import { Failure } from "./errors.ts";
 import { type Cap, type HostThing, type Thing, type Walker, THING, isHostThing, valueOfThing } from "./deref.ts";
 import type { World } from "./ladder.ts";
-import { type AttributeDeclaration, type CircularRule, type TreeContract, atArgsOf, atRuleOf, circularOf, collectOf, equationType, lookupKind } from "./world.ts";
+import {
+  type AttributeDeclaration,
+  type CircularRule,
+  type TreeContract,
+  GENERATION_LIMIT,
+  atArgsOf,
+  atRuleOf,
+  circularOf,
+  collectOf,
+  documentKey,
+  equationType,
+  lookupKind,
+} from "./world.ts";
 import { STD_DOMAINS } from "./types.ts";
 import type { SyntaxProfile } from "./syntax.ts";
 
@@ -79,6 +91,11 @@ export const STD_WORLD: World = {
           pure: true,
           summary: "A step of a path: it reads an attribute with parameters of the node before it, with the arguments of the step (TREE.AT).",
         },
+        quote: {
+          verbs: { eval: "data.quote", view: "view.value" },
+          pure: true,
+          summary: "A document as data. Its value is the result, and nothing in it evaluates. A higher-order attribute uses it (TREE.HIGHER).",
+        },
       },
     },
     panel: {
@@ -183,6 +200,7 @@ export const WORLD_SYNTAX: SyntaxProfile = /* @__PURE__ */ Object.freeze({
       { name: "nearest", kind: "nearest", args: "named", fields: ["type", "follow", "self"] },
       { name: "tree.named", kind: "tree.named", args: "named", fields: ["name", "in"] },
       { name: "tree.at", kind: "tree.at", args: "named", fields: ["attr", "args"] },
+      { name: "tree.quote", kind: "tree.quote", args: "literal" },
       // An operator document with fewer terms than its operator takes, for example add(5) (K163, D65).
       { name: "add", kind: "add" },
       { name: "multiply", kind: "multiply" },
@@ -224,6 +242,7 @@ export const STD_EVALUATORS: Readonly<Record<string, Evaluator>> = {
   "data.number": /* @__PURE__ */ dataOf("number"),
   "data.text": /* @__PURE__ */ dataOf("string"),
   "data.bool": /* @__PURE__ */ dataOf("boolean"),
+  "data.quote": ({ data }) => ok(data ?? null),
   "math.add": ({ parts }) => {
     const all = allValues(parts.map((part) => part.evaluate()));
     if ("error" in all) return all.error;
@@ -271,10 +290,10 @@ interface TreeBuild {
 }
 
 /** The rungs of the ladder of an attribute, in their order (TREE.LADDER, D42). */
-export type AttributeRung = "own" | "kind" | "parent" | "copy" | "default";
+export type AttributeRung = "own" | "kind" | "parent" | "copy" | "default" | "forward";
 
 /** The rungs of the ladder of an attribute, in their order (TREE.LADDER, D42). */
-export const ATTRIBUTE_RUNGS: readonly AttributeRung[] = /* @__PURE__ */ Object.freeze(["own", "kind", "parent", "copy", "default"] as const);
+export const ATTRIBUTE_RUNGS: readonly AttributeRung[] = /* @__PURE__ */ Object.freeze(["own", "kind", "parent", "copy", "default", "forward"] as const);
 
 /** The record of the demand of one attribute of a node (TREE.RUNGS). */
 export interface AttributeTrace {
@@ -1000,6 +1019,106 @@ function atRead(n: NodeState, attr: string, args: unknown): Result | undefined {
   return answer.result;
 }
 
+/** The most documents and the most characters of the keys in the table of generated documents. */
+const INTERNED_DOCUMENTS = 1000;
+const INTERNED_CHARACTERS = 16_000_000;
+
+/** The first document of each structural key (TREE.HIGHER-PLAN, D126). */
+const internedDocuments = /* @__PURE__ */ new Map<string, Json>();
+
+/** The kept document of each document object. An object gets its key one time, as PLAN.CACHE says. */
+const internedObjects = /* @__PURE__ */ new WeakMap<object, Json>();
+
+/** The characters of the keys of `internedDocuments`. */
+let internedCharacters = 0;
+
+/**
+ * This function gives the one object of a document (TREE.HIGHER-PLAN, D126). `equationPlan` caches by object, thus a
+ * new object with a known key compiles nothing. The table has a limit, and a full table starts again. A document that
+ * left the table compiles again, and that costs only time.
+ *
+ * @param doc - The value of an equation.
+ * @returns The document, or `undefined` for a value that is not JSON data.
+ */
+function internedDocument(doc: unknown): Json | undefined {
+  const object = typeof doc === "object" && doc !== null;
+  const known = object ? internedObjects.get(doc) : undefined;
+  if (known !== undefined) return known;
+  const key = documentKey(doc);
+  if (key === undefined) return undefined;
+  if (!object) return doc as Json;
+  let kept = internedDocuments.get(key);
+  if (kept === undefined) {
+    if (internedDocuments.size >= INTERNED_DOCUMENTS || internedCharacters + key.length > INTERNED_CHARACTERS) {
+      internedDocuments.clear();
+      internedCharacters = 0;
+    }
+    kept = doc as Json;
+    internedDocuments.set(key, kept);
+    internedCharacters += key.length;
+  }
+  internedObjects.set(doc, kept);
+  return kept;
+}
+
+/** The depth of each root of a generated document: the generated documents from the root of the tree to it (D126). */
+const generations = /* @__PURE__ */ new WeakMap<NodeState, number>();
+
+/** This function gives the depth of the nearest root of a generated document at or above a node of a tree, or 0. */
+function generationOf(node: HostThing, build: TreeBuild): number {
+  let thing: Thing | undefined = node;
+  for (let at = stateOf(thing); at?.build === build; at = stateOf(thing)) {
+    const depth = generations.get(at);
+    if (depth !== undefined) return depth;
+    thing = (thing as HostThing).deref("parent");
+  }
+  return 0;
+}
+
+/**
+ * This function gives a higher-order attribute of a node (TREE.HIGHER, D126). The equation gives a document as data.
+ * The document evaluates as an equation, with the node as `self`. Thus its root is a node under the node: it finds the
+ * open tree, and it has the node as its parent. The function is outside the code of `read`, as a fold is.
+ */
+function generated(n: NodeState, node: HostThing, key: string, term: Json): Result {
+  const value = n.equation(term, NO_NAMES);
+  if (!value.ok) return value;
+  const doc = internedDocument(value.value);
+  const text = attributeText(key, n.type, n.place);
+  if (doc === undefined) return fail("#VALUE!", `The equation of the higher-order attribute ${text} gives a value that is not JSON data.`);
+  const depth = generationOf(node, n.build) + 1;
+  if (depth > GENERATION_LIMIT) return fail("#DEPTH!", `The higher-order attribute ${text} is under more than ${GENERATION_LIMIT} generated documents.`);
+  const root = n.equation(doc, NO_NAMES);
+  if (!root.ok) return root;
+  const made = stateOf(root.value);
+  if (made === undefined) return fail("#VALUE!", `The document of the higher-order attribute ${text} gives no node of the tree.`);
+  generations.set(made, depth);
+  return root;
+}
+
+/**
+ * This function gives the last rung of the ladder (TREE.FORWARD, D126). The attribute `forwards` gives a node, and that
+ * node answers the attribute through its own ladder. The attribute `forwards` itself gets no such answer.
+ */
+function forwarded(n: NodeState, node: HostThing, key: string, name: unknown): { readonly result: Result; readonly by: AttributeRung } | undefined {
+  if (key === name) return undefined;
+  const text = attributeText(key, n.type, n.place);
+  if (typeof name !== "string") return { result: fail("#VALUE!", `The attribute ${text} has a contract with a bad field forwards. It must be a text.`), by: "forward" };
+  const target = n.read(name);
+  if (target === undefined) return undefined;
+  if (!target.ok) return { result: target, by: "forward" };
+  const to = stateOf(target.value);
+  if (to === undefined) return { result: fail("#VALUE!", `The attribute ${name} that ${text} forwards to gives no node of a tree.`), by: "forward" };
+  // An equation can give a node without a declaration higher, thus the rung counts each node that it reaches.
+  if (!generations.has(to)) {
+    const depth = generationOf(node, n.build) + 1;
+    if (depth > GENERATION_LIMIT) return { result: fail("#DEPTH!", `The attribute ${text} forwards through more than ${GENERATION_LIMIT} generated documents.`), by: "forward" };
+    generations.set(to, depth);
+  }
+  const result = to.read(key);
+  return result === undefined ? undefined : { result, by: "forward" };
+}
+
 /**
  * This function makes a node of the decorated tree. A step `parent` gives the self of the context of the node, and a
  * step `type` gives its type. Another step reads an attribute through its ladder (TREE.LADDER). The rungs are a part of
@@ -1065,7 +1184,8 @@ function treeThing(input: EvalInput, place: readonly Key[], build: TreeBuild, ou
     if (declared?.fold !== undefined) return { result: fold(key, declared.fold), by: "default" };
     if (declared?.collect !== undefined) return { result: collected(node, key, declared.collect), by: "default" };
     if (declared?.default !== undefined) return { result: state.equation(declared.default, NO_NAMES), by: "default" };
-    return undefined;
+    if (declared?.higher !== undefined) return { result: generated(state, node, key, declared.higher), by: "default" };
+    return tree?.forwards === undefined ? undefined : forwarded(state, node, key, tree.forwards);
   };
 
   /**
@@ -1162,7 +1282,9 @@ function treeThing(input: EvalInput, place: readonly Key[], build: TreeBuild, ou
     trace(key) {
       const cell = cells.get(key);
       if (cell === undefined || cell.busy) return undefined;
-      const rungs = cell.by === undefined ? ATTRIBUTE_RUNGS : ATTRIBUTE_RUNGS.slice(0, ATTRIBUTE_RUNGS.indexOf(cell.by) + 1);
+      // The last rung is on the way only for a kind with the field forwards.
+      const end = cell.by === undefined ? ATTRIBUTE_RUNGS.length - (tree?.forwards === undefined ? 1 : 0) : ATTRIBUTE_RUNGS.indexOf(cell.by) + 1;
+      const rungs = ATTRIBUTE_RUNGS.slice(0, end);
       return cell.by === undefined ? { attribute: key, rungs } : { attribute: key, rungs, by: cell.by };
     },
     json(path) {