@mark1russell7/coeval 0.19.0 → 0.20.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package",
   "name": "@mark1russell7/coeval",
-  "version": "0.19.0",
+  "version": "0.20.1",
   "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",
@@ -36,6 +36,8 @@
   ],
   "devDependencies": {
     "@mark1russell7/cue": "^1.0.2",
+    "@mark1russell7/rigor-bench": "^0.2.1",
+    "@mark1russell7/rigor-statistics": "^0.1.5",
     "@types/node": "^26.6.4",
     "esbuild": "^0.28.2",
     "typescript": "^7.0.2",

package/src/index.ts

@@ -38,6 +38,8 @@ export {
   type Alias,
   type AttributeDeclaration,
   type CapsRule,
+  type CircularDeclaration,
+  type CircularRule,
   type Kind,
   type KindFacts,
   type LazyRule,
@@ -52,6 +54,8 @@ export {
   type VerbEffects,
   type World,
   type WorldEntry,
+  CIRCULAR_LIMIT,
+  circularOf,
   effectsOfVerb,
   entriesAsJson,
   equationType,
@@ -88,6 +92,7 @@ export {
   kindNamed,
   kindOf,
 } from "./ladder.ts";
+export { type StepKey, type StepLadder, type StepNeed, type StepReason, type StepRefusal, type StepWalk, checkStep, isStep, stepLadder, stepOf, stepRank } from "./steps.ts";
 export {
   type Cap,
   type Context,

package/src/instances.ts

@@ -37,6 +37,8 @@ export interface AttributeVertex {
   readonly attribute: string;
   /** The text of the type of the node. */
   readonly type: string;
+  /** `true` when the kind of the node declares the attribute `circular` (TREE.CIRCULAR-CHECK). Else the field is absent. */
+  readonly circular?: true;
 }
 
 /** One read of an attribute by the code of another attribute (D107). */
@@ -57,6 +59,11 @@ export interface AttributeCycle {
   readonly vertices: readonly string[];
   /** `true` when the eager reads with a known source close the cycle (GRAPH.CYCLE). */
   readonly certain: boolean;
+  /**
+   * `true` when each attribute of the cycle is circular: the run gives its fixed point, thus `check` gives no issue
+   * (TREE.CIRCULAR-CHECK). Else the field is absent.
+   */
+  readonly circular?: true;
 }
 
 /** The graph of attribute instances of a document (TREE.GRAPH). */
@@ -195,11 +202,18 @@ interface Reader {
   readonly at: readonly Key[];
 }
 
+/** This function tells if the kind of a node declares an attribute `circular` (D113). */
+function isCircular(kind: Kind, attribute: string): boolean {
+  const declared = hasOwnEntry(kind.tree?.attributes, attribute) ? kind.tree?.attributes?.[attribute] : undefined;
+  return declared?.circular !== undefined;
+}
+
 /** This function gives the vertex of an attribute of a node. A new vertex goes on the work list for its rungs. */
 function vertexOf(b: Builder, node: NodeInfo, attribute: string): string {
   const id = attributeVertexId(node.visit.place, attribute);
   if (!b.vertices.has(id)) {
-    b.vertices.set(id, { id, place: node.visit.place, attribute, type: node.text });
+    const vertex: AttributeVertex = { id, place: node.visit.place, attribute, type: node.text };
+    b.vertices.set(id, isCircular(node.kind, attribute) ? { ...vertex, circular: true } : vertex);
     b.nodes.set(id, node);
     if (!node.parts.has(attribute)) b.work.push(id);
   }
@@ -558,10 +572,18 @@ export function attributeGraph(machine: Machine, doc: unknown, options: Attribut
     edges: b.edges,
     graph,
     unknown: b.edges.filter((e) => e.from === undefined),
-    cycles: cycles(graph).map((cycle) => ({ vertices: cycle.nodes, certain: cycle.certain })),
+    cycles: cycles(graph).map((cycle) => {
+      const found: AttributeCycle = { vertices: cycle.nodes, certain: cycle.certain };
+      return allCircular(b, cycle.nodes) ? { ...found, circular: true } : found;
+    }),
   };
 }
 
+/** This function tells if each vertex of a list is a circular attribute (D113). */
+function allCircular(b: Builder, ids: readonly string[]): boolean {
+  return ids.every((id) => b.vertices.get(id)?.circular === true);
+}
+
 function vertexText(vertex: AttributeVertex): string {
   return `${vertex.attribute} of ${vertex.type} at [${vertex.place.join(", ")}]`;
 }
@@ -572,6 +594,9 @@ function vertexText(vertex: AttributeVertex): string {
  * certain cycle that these reads reach always gives `#CYCLE!`. The issue gets the place of the read that closes the
  * cycle in the order of the run, and the reason of the run. A cycle through a lazy read or an unknown read is not an issue.
  *
+ * A cycle whose attributes are each circular gives a fixed point, thus it is not an issue (TREE.CIRCULAR-CHECK). In a
+ * cycle with a plain attribute, the run gives `#CYCLE!` at the first read that closes a chain with a plain attribute.
+ *
  * @param machine - The world and the code of the evaluators.
  * @param doc - The document, as JSON.
  * @param options - The type of a bare root value.
@@ -582,7 +607,7 @@ export function cycleIssues(machine: Machine, doc: unknown, options: CheckOption
   const graph = nodeGraph(b);
   const certain = new Map<string, number>();
   cycles(graph).forEach((cycle, index) => {
-    if (cycle.certain) for (const id of cycle.nodes) certain.set(id, index);
+    if (cycle.certain && !allCircular(b, cycle.nodes)) for (const id of cycle.nodes) certain.set(id, index);
   });
   if (certain.size === 0) return [];
   // The eager reads with a known source of each vertex, in the order of its code, with the index of each edge.
@@ -627,9 +652,12 @@ export function cycleIssues(machine: Machine, doc: unknown, options: CheckOption
       // The read reaches an attribute in evaluation: the run gives #CYCLE! here, with the chain of the demands.
       const cycle = certain.get(from);
       if (cycle === undefined || reported.has(cycle)) continue;
-      reported.add(cycle);
       const first = stack.findIndex((frame) => frame.id === from);
-      const chain = [...stack.slice(first).map((frame) => frame.id), from].map((id) => vertexText(b.vertices.get(id) as AttributeVertex));
+      const ids = stack.slice(first).map((frame) => frame.id);
+      // A chain of circular attributes reads an approximation in the run, thus it does not close the cycle (D113).
+      if (allCircular(b, ids)) continue;
+      reported.add(cycle);
+      const chain = [...ids, from].map((id) => vertexText(b.vertices.get(id) as AttributeVertex));
       out.push({ code: "#CYCLE!", place: e.place, reason: `The attributes form a cycle: ${chain.join(" -> ")}.`, at: b.ats[index] as readonly Key[] });
     }
   }

package/src/reference.ts

@@ -1,6 +1,6 @@
-import { type Envelope, type Json, type Key, isEnvelope, isKey, isRecord, typeName } from "./doc.ts";
+import { type Envelope, type Json, type Key, docEquals, isEnvelope, isKey, isRecord, typeName } from "./doc.ts";
 import { ask } from "./ladder.ts";
-import { type AttributeDeclaration, type CapsRule, type Kind, type TreeContract, equationType, lookupKind } from "./world.ts";
+import { type AttributeDeclaration, type CapsRule, type CircularRule, type Kind, type TreeContract, circularOf, equationType, lookupKind } from "./world.ts";
 import { type PartSlot, type Split, partsOf, pathMatches } from "./parts.ts";
 import { type Cap, type Context, type HostThing, type Resolution, type ResolveOptions, type Thing, ROOTS, THING, isHostThing, resolve, valueOfThing, worldThing } from "./deref.ts";
 import { type AttributeRung, STD_EVALUATORS } from "./stdlib.ts";
@@ -776,7 +776,7 @@ interface RefNode {
 const refNodes = /* @__PURE__ */ new WeakMap<object, RefNode>();
 
 /** The attributes in evaluation in the reference, in the order of their demands (TREE.CYCLE). */
-const inEvaluation: { readonly node: RefNode; readonly name: string }[] = [];
+const inEvaluation: { readonly node: RefNode; readonly name: string; readonly circular: boolean; tentative: boolean }[] = [];
 
 function nameOfAttribute(node: RefNode, name: string): string {
   return `${name} of ${node.kind} at [${node.place.join(", ")}]`;
@@ -865,29 +865,159 @@ const REF_RUNGS: readonly (readonly [AttributeRung, (node: RefNode, name: string
   ],
 ];
 
-/** TREE.ONCE, TREE.MEMO and TREE.CYCLE: the result of one attribute, or `undefined` when no rung of its ladder answers. */
+/** TREE.LADDER: the answer of the first rung that answers, or `undefined`. */
+function ladderOf(node: RefNode, name: string): Result | undefined {
+  for (const [, rung] of REF_RUNGS) {
+    const result = rung(node, name);
+    if (result !== undefined) return result;
+  }
+  return undefined;
+}
+
+/** One approximation of a circular attribute in the reference, with its round (TREE.CIRCULAR). */
+interface RefApproximation {
+  readonly result: Result | undefined;
+  readonly round: number;
+}
+
+/**
+ * TREE.CIRCULAR: a fixed point in evaluation in the reference. The first circular attribute of a demand leads it, and
+ * each circular attribute that a demand reaches during its rounds joins it.
+ */
+interface RefPoint {
+  /** The index of the leader in `inEvaluation`. */
+  readonly depth: number;
+  round: number;
+  changed: boolean;
+  readonly values: Map<RefNode, Map<string, RefApproximation>>;
+}
+
+/** The open fixed point of the reference, or `undefined`. */
+let refPoint: RefPoint | undefined;
+
+/** TREE.CIRCULAR-CHECK: the declaration `circular` of an attribute of a node, or `undefined`. */
+function circularRuleOf(node: RefNode, name: string): CircularRule | undefined {
+  const declared = termIn(node.contract?.attributes, name)?.circular;
+  return declared === undefined ? undefined : circularOf(declared);
+}
+
+/** TREE.CIRCULAR: two approximations are the same when two values are equal (DOC.EQUALS) or two errors have one code and reason. */
+function sameApproximation(a: Result | undefined, b: Result | undefined): boolean {
+  if (a === undefined || b === undefined) return a === b;
+  if (a.ok && b.ok) return docEquals(a.value, b.value);
+  if (!a.ok && !b.ok) return a.error.code === b.error.code && a.error.reason === b.error.reason;
+  return false;
+}
+
+/** TREE.CIRCULAR: the attributes above the leader read an approximation, thus their results are not final. */
+function readApproximation(point: RefPoint): void {
+  for (const entry of inEvaluation.slice(point.depth + 1)) entry.tentative = true;
+}
+
+function approximationsOf(point: RefPoint, node: RefNode): Map<string, RefApproximation> {
+  const known = point.values.get(node);
+  if (known !== undefined) return known;
+  const made = new Map<string, RefApproximation>();
+  point.values.set(node, made);
+  return made;
+}
+
+/**
+ * TREE.CIRCULAR and TREE.CIRCULAR-LIMIT: the rounds of the leader of a fixed point. A round without a new value ends
+ * the rounds, and each circular attribute of that round keeps its value. An error ends the rounds at once. The last
+ * round of the limit gives `#CYCLE!` at the place of the node of the leader.
+ */
+function fixedPointOf(node: RefNode, name: string, rule: CircularRule & { readonly ok: true }): Result | undefined {
+  const point: RefPoint = { depth: inEvaluation.length - 1, round: 0, changed: false, values: new Map() };
+  refPoint = point;
+  try {
+    let before: Result | undefined = ok(rule.start);
+    for (;;) {
+      point.round += 1;
+      point.changed = false;
+      const result = ladderOf(node, name);
+      if (result !== undefined && !result.ok) return result;
+      if (!sameApproximation(before, result)) point.changed = true;
+      before = result;
+      approximationsOf(point, node).set(name, { result, round: point.round });
+      if (!point.changed) {
+        for (const [member, values] of point.values) {
+          for (const [key, value] of values) if (value.round === point.round && value.result !== undefined) member.values.set(key, value.result);
+        }
+        return result;
+      }
+      if (point.round >= rule.limit) {
+        return fail("#CYCLE!", `The cycle of the circular attribute ${nameOfAttribute(node, name)} does not become stable within its limit of ${rule.limit} ${rule.limit === 1 ? "round" : "rounds"}.`, {
+          place: node.place,
+        });
+      }
+    }
+  } finally {
+    refPoint = undefined;
+  }
+}
+
+/** TREE.CIRCULAR: a circular attribute in the open fixed point of another leader evaluates one time in each round. */
+function roundOf(point: RefPoint, node: RefNode, name: string, rule: CircularRule & { readonly ok: true }): Result | undefined {
+  let value = point.values.get(node)?.get(name);
+  if (value === undefined || value.round !== point.round) {
+    node.pending.add(name);
+    inEvaluation.push({ node, name, circular: true, tentative: false });
+    let result: Result | undefined;
+    try {
+      result = ladderOf(node, name);
+    } finally {
+      node.pending.delete(name);
+      inEvaluation.pop();
+    }
+    if (!sameApproximation(value === undefined ? ok(rule.start) : value.result, result)) point.changed = true;
+    value = { result, round: point.round };
+    approximationsOf(point, node).set(name, value);
+  }
+  readApproximation(point);
+  return value.result;
+}
+
+/**
+ * TREE.ONCE, TREE.MEMO, TREE.CYCLE and TREE.CIRCULAR: the result of one attribute, or `undefined` when no rung of its
+ * ladder answers. A result that read an approximation of an open fixed point is not kept.
+ */
 function attributeOf(node: RefNode, name: string): Result | undefined {
   const done = node.values.get(name);
   if (done !== undefined) return done;
   if (node.pending.has(name)) {
     const from = inEvaluation.findIndex((entry) => entry.node === node && entry.name === name);
+    const point = refPoint;
+    if (point !== undefined && from >= point.depth && inEvaluation.slice(from).every((entry) => entry.circular)) {
+      readApproximation(point);
+      const kept = point.values.get(node)?.get(name);
+      if (kept !== undefined) return kept.result;
+      const rule = circularRuleOf(node, name);
+      return ok(rule?.ok === true ? rule.start : null);
+    }
     const steps = from < 0 ? [nameOfAttribute(node, name)] : inEvaluation.slice(from).map((entry) => nameOfAttribute(entry.node, entry.name));
     return fail("#CYCLE!", `The attributes form a cycle: ${[...steps, nameOfAttribute(node, name)].join(" -> ")}.`);
   }
+  const rule = circularRuleOf(node, name);
+  if (rule !== undefined && !rule.ok) {
+    const bad = fail("#VALUE!", `The attribute ${nameOfAttribute(node, name)} has a bad declaration circular. ${rule.reason}`);
+    node.values.set(name, bad);
+    return bad;
+  }
+  const point = refPoint;
+  if (point !== undefined && rule !== undefined) return roundOf(point, node, name, rule);
+  const entry = { node, name, circular: rule !== undefined, tentative: false };
   node.pending.add(name);
-  inEvaluation.push({ node, name });
+  inEvaluation.push(entry);
+  let result: Result | undefined;
   try {
-    for (const [, rung] of REF_RUNGS) {
-      const result = rung(node, name);
-      if (result === undefined) continue;
-      node.values.set(name, result);
-      return result;
-    }
-    return undefined;
+    result = rule === undefined ? ladderOf(node, name) : fixedPointOf(node, name, rule);
   } finally {
     node.pending.delete(name);
     inEvaluation.pop();
   }
+  if (!entry.tentative && result !== undefined) node.values.set(name, result);
+  return result;
 }
 
 /** TREE.RESULT: the JSON of a node. `open` holds the nodes and the containers whose JSON is in progress. */

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, type WorldEntry, eachKind, effectsOfVerb, equationType, isKind, isNamespace } from "./world.ts";
+import { type Kind, type World, type WorldEntry, circularOf, eachKind, effectsOfVerb, 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";
@@ -867,7 +867,8 @@ function equationIssues(machine: Machine, kind: Kind, kindText: string, options:
 
 /**
  * This function finds the issues of the contract of a tree kind (TREE.CHECK-RESERVED). An attribute with the name of a
- * structural step gets no read. A tree kind of the run side contradicts the evaluation on demand of its attributes.
+ * 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).
  */
 function contractIssues(kind: Kind, kindText: string): readonly Issue[] {
   const out: Issue[] = [];
@@ -878,6 +879,11 @@ function contractIssues(kind: Kind, kindText: string): readonly Issue[] {
       if (why !== undefined) out.push({ code: "#NAME?", place: [], reason: `The kind ${kindText} gives the reserved attribute tree.${table}.${name}: ${why}.` });
     }
   }
+  // A declaration circular needs a start value and a correct limit (TREE.CIRCULAR-CHECK, D113).
+  for (const [name, declared] of Object.entries(tree?.attributes ?? {})) {
+    const rule = declared.circular === undefined ? undefined : circularOf(declared.circular);
+    if (rule !== undefined && !rule.ok) out.push({ code: "#VALUE!", place: [], reason: `The kind ${kindText} has a bad declaration tree.attributes.${name}.circular. ${rule.reason}` });
+  }
   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.` });
   }