@mark1russell7/coeval 0.18.0 → 0.20.0

package/src/reads.ts

@@ -22,8 +22,41 @@ export type ReadsCheck =
       readonly read: Read;
       /** What the path of that read reaches in the new context. */
       readonly now: Result;
+      /**
+       * `true` when the read reaches the same thing by `sameResult`, but the print of that thing changed
+       * (READS.IN-PLACE). Only the option `prints` gives this mark.
+       */
+      readonly inPlace?: true;
     };
 
+/** The options of `printReads` (READS.IN-PLACE, D112). */
+export interface PrintOptions {
+  /**
+   * The most entries in the print of one value. Each value, each field name and each mark counts as one entry. A
+   * larger value gets no print, and `verifyReads` then gives its read as changed. The default is 10000.
+   */
+  readonly limit?: number;
+  /**
+   * The stamp of the host for an object, for example the version of a host thing. A stamp other than `undefined`
+   * takes the place of the fields of that object in the print. A stamp compares with `Object.is`.
+   *
+   * @param value - An object of the value of a read.
+   * @returns The stamp, or `undefined` for the walk of the fields.
+   */
+  readonly stamp?: (value: object) => unknown;
+}
+
+/**
+ * The prints of a list of reads, from `printReads`. `verifyReads` takes them with the option `prints`. The prints
+ * keep their options, thus the verification walks each value with the same rules.
+ */
+export interface ReadPrints {
+  /** The print of each read, at the index of the read. A read without an object in its value has no print. */
+  readonly prints: readonly (readonly unknown[] | undefined)[];
+  /** The options of the prints. */
+  readonly options: PrintOptions;
+}
+
 /** The options of `verifyReads`. */
 export interface VerifyOptions {
   /**
@@ -35,11 +68,154 @@ export interface VerifyOptions {
    * @returns `true` when the two things are the same, or `undefined` for the rules of `sameResult`.
    */
   readonly equal?: (a: unknown, b: unknown) => boolean | undefined;
+  /**
+   * The prints of the reads, from `printReads` after the evaluation (READS.IN-PLACE). When the prints are given, a
+   * read that reaches the same thing also compares its print. Thus a change in place of a host value is a changed
+   * read. Without the prints, the verification does no work for them.
+   */
+  readonly prints?: ReadPrints;
 }
 
 /** One answer serves each list whose reads are all the same. */
 const SAME: ReadsCheck = /* @__PURE__ */ Object.freeze({ same: true });
 
+/** The default limit of the entries in the print of one value. */
+const PRINT_LIMIT = 10_000;
+
+/** The marks of a print. Each mark is a private object, thus no value of a host is the same as a mark. */
+const OBJECT = /* @__PURE__ */ Object.freeze({ mark: "object" });
+const LIST = /* @__PURE__ */ Object.freeze({ mark: "list" });
+const DATE = /* @__PURE__ */ Object.freeze({ mark: "date" });
+const MAP = /* @__PURE__ */ Object.freeze({ mark: "map" });
+const SET = /* @__PURE__ */ Object.freeze({ mark: "set" });
+const SEEN = /* @__PURE__ */ Object.freeze({ mark: "seen" });
+const STAMP = /* @__PURE__ */ Object.freeze({ mark: "stamp" });
+
+/** The print of a value that the walk cannot finish: it is too large, or the host threw. It is not the same as any print. */
+const NO_PRINT: readonly unknown[] = /* @__PURE__ */ Object.freeze([]);
+
+/**
+ * This function gives the print of a value: a flat list of its parts, in the order of a walk (D112). Two prints are
+ * the same when they have the same length, and each entry is the same by `Object.is`.
+ *
+ * - An object starts with a mark and its prototype. A list adds its length, a date its time, and a map or a set
+ *   its size and its entries. Then come the count of the own enumerable fields, each name and the kind of each field.
+ * - A field with a getter gives the getter function. The walk does not start host code of a field.
+ * - A primitive value and a function are entries. A function compares by its identity.
+ * - An object that the walk already visited gives the mark `SEEN` and its number. Thus a cycle ends.
+ * - A value with more than `limit` entries, or an exception of the host, gives `NO_PRINT`.
+ *
+ * @param value - The value of a read.
+ * @param options - The limit and the stamp of the host.
+ * @returns The print.
+ */
+function printOf(value: unknown, options: PrintOptions): readonly unknown[] {
+  const limit = options.limit ?? PRINT_LIMIT;
+  const stamp = options.stamp;
+  const out: unknown[] = [];
+  const ids = new Map<object, number>();
+  const stack: unknown[] = [value];
+  try {
+    while (stack.length > 0) {
+      if (out.length > limit) return NO_PRINT;
+      const x = stack.pop();
+      if (typeof x !== "object" || x === null) {
+        out.push(x);
+        continue;
+      }
+      const id = ids.get(x);
+      if (id !== undefined) {
+        out.push(SEEN, id);
+        continue;
+      }
+      ids.set(x, ids.size);
+      const stamped = stamp?.(x);
+      if (stamped !== undefined) {
+        out.push(STAMP, stamped);
+        continue;
+      }
+      const children: unknown[] = [];
+      out.push(OBJECT, Object.getPrototypeOf(x));
+      if (Array.isArray(x)) out.push(LIST, x.length);
+      else if (x instanceof Date) out.push(DATE, Date.prototype.getTime.call(x));
+      else if (x instanceof Map) {
+        out.push(MAP, x.size);
+        if (out.length + 2 * x.size > limit) return NO_PRINT;
+        for (const [key, item] of Map.prototype.entries.call(x) as IterableIterator<[unknown, unknown]>) children.push(key, item);
+      } else if (x instanceof Set) {
+        out.push(SET, x.size);
+        if (out.length + x.size > limit) return NO_PRINT;
+        for (const item of Set.prototype.values.call(x) as IterableIterator<unknown>) children.push(item);
+      }
+      const keys = Object.keys(x);
+      if (out.length + 3 * keys.length > limit) return NO_PRINT;
+      out.push(keys.length);
+      for (const key of keys) {
+        const field = Object.getOwnPropertyDescriptor(x, key);
+        // A field that a proxy hides between `keys` and its descriptor reads as a field without a value.
+        const data = field === undefined || "value" in field;
+        out.push(key, data);
+        children.push(field === undefined ? undefined : "value" in field ? field.value : field.get);
+      }
+      // The stack gives the last entry first, thus the children go on it in the reverse order.
+      for (let index = children.length - 1; index >= 0; index -= 1) stack.push(children[index]);
+    }
+  } catch {
+    return NO_PRINT;
+  }
+  return out.length > limit ? NO_PRINT : out;
+}
+
+/** This function tells if two prints are the same. `NO_PRINT` is not the same as any print, also not as itself. */
+function samePrint(a: readonly unknown[], b: readonly unknown[]): boolean {
+  if (a === NO_PRINT || b === NO_PRINT || a.length !== b.length) return false;
+  for (let index = 0; index < a.length; index += 1) if (!Object.is(a[index], b[index])) return false;
+  return true;
+}
+
+/** This function gives the print of the value of a result, or `undefined` when the value holds no object. */
+function printOfResult(result: Result, options: PrintOptions, cache: Map<object, readonly unknown[]>): readonly unknown[] | undefined {
+  if (!result.ok || typeof result.value !== "object" || result.value === null) return undefined;
+  const value = result.value;
+  let print = cache.get(value);
+  if (print === undefined) {
+    print = printOf(value, options);
+    cache.set(value, print);
+  }
+  return print;
+}
+
+/**
+ * This function gives the prints of the values of a list of reads (READS.IN-PLACE, D112). A host starts it after
+ * the evaluation, and it gives the prints to `verifyReads` with the option `prints`.
+ *
+ * - The print of a value walks its lists, its plain records and the own enumerable fields of each other object. A
+ *   date adds its time, and a map or a set adds its entries.
+ * - A read that is not free, a read that reached an error and a read with a primitive value get no print.
+ * - A cycle ends, because the walk visits each object one time.
+ * - A value with more entries than the limit gets no print. `verifyReads` then gives that read as changed.
+ *
+ * The walk does not see the state in a closure or a private field. It does not see a field with a symbol name, a
+ * field that is not enumerable or the value of a getter. A host gives a stamp for such an object, for example its version.
+ *
+ * @param reads - The reads of the evaluation, from the option `reads`.
+ * @param options - The limit and the stamp of the host.
+ * @returns The prints, for the option `prints` of `verifyReads`.
+ */
+export function printReads(reads: readonly Read[], options: PrintOptions = {}): ReadPrints {
+  const cache = new Map<object, readonly unknown[]>();
+  const prints = reads.map((read) => (read.free ? printOfResult(read.reached, options, cache) : undefined));
+  return { prints, options };
+}
+
+/** This function tells if the print of a read changed, when the read has a print. */
+function changedInPlace(prints: ReadPrints, index: number, now: Result, cache: Map<object, readonly unknown[]>): boolean {
+  const old = prints.prints[index];
+  if (old === undefined) return false;
+  const print = printOfResult(now, prints.options, cache);
+  return print === undefined || !samePrint(old, print);
+}
+
 /** This function tells if two lists of hops are the same: the same steps, rungs and things, in order. */
 function sameHops(a: readonly Hop[], b: readonly Hop[] | undefined, equal: VerifyOptions["equal"]): boolean {
   if (b === undefined || a.length !== b.length) return false;
@@ -78,18 +254,22 @@ function heldStop(root: Context, path: readonly unknown[]): Result | undefined {
  *   extension of a profile can read outside `resolve`. The schedule asks `factsOf` first.
  *
  * The values of the context must not change in place, as PLAN.CACHE says for the documents. A value that changed in
- * place is the same object, thus the function cannot see the change.
+ * place is the same object, thus `sameResult` cannot see the change. The option `prints` finds such a change
+ * (READS.IN-PLACE). The prints come from `printReads` after the evaluation, and the answer then has the mark `inPlace`.
  *
  * @param target - The machine of the evaluation, or its plan.
  * @param reads - The reads of the evaluation, from the option `reads`.
  * @param context - The new context.
- * @param options - The rule of the host for two things.
+ * @param options - The rule of the host for two things, and the prints of the reads.
  * @returns `{ same: true }` when each free read reaches the same thing, or else the first changed read.
  */
 export function verifyReads(target: Machine | Plan, reads: readonly Read[], context: Context, options: VerifyOptions = {}): ReadsCheck {
   const machine = "evaluators" in target ? target : target.machine;
   const root = rootContext(machine, context);
   const equal = options.equal;
+  const prints = options.prints;
+  // The prints of the new values, made only with the option `prints`. Two reads of one object share its print.
+  let printed: Map<object, readonly unknown[]> | undefined;
   for (let index = 0; index < reads.length; index += 1) {
     const read = reads[index] as Read;
     if (!read.free) continue;
@@ -100,6 +280,7 @@ export function verifyReads(target: Machine | Plan, reads: readonly Read[], cont
       const now = keptAgain(machine, root, read.path);
       if (now === undefined) return { same: false, index, read, now: fail("#N/A", "The host does not know the value of the kept read yet.") };
       if (!sameResult(read.reached, now, equal)) return { same: false, index, read, now };
+      if (prints !== undefined && changedInPlace(prints, index, now, (printed ??= new Map()))) return { same: false, index, read, now, inPlace: true };
       continue;
     }
     const asked = read.hops !== undefined;
@@ -107,6 +288,9 @@ export function verifyReads(target: Machine | Plan, reads: readonly Read[], cont
     if (!sameResult(read.reached, now.reached, equal) || (read.hops !== undefined && !sameHops(read.hops, now.hops, equal))) {
       return { same: false, index, read, now: now.reached };
     }
+    if (prints !== undefined && changedInPlace(prints, index, now.reached, (printed ??= new Map()))) {
+      return { same: false, index, read, now: now.reached, inPlace: true };
+    }
   }
   return SAME;
 }

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. */