@mark1russell7/coeval 0.21.0 → 0.23.0

package/src/meaning.ts

@@ -58,12 +58,14 @@ export interface ScheduleEngine {
   read(id: string): Result;
 }
 
-/** What a new engine gets beside its machine: the context of the host, and the type of a bare root value. */
+/** What a new engine gets beside its machine. These are the context of the host, the type of a bare root value and the `self` of each node. */
 export interface ScheduleEngineStart {
   /** The first context of the host, without the root `world`. */
   readonly context: Context;
   /** The type of a bare root value, when the options of the harness name one. */
   readonly declaredType?: string;
+  /** The `self` of each node, when the options of the harness have `selves`. It has the form of the option of `schedule`. */
+  readonly selfOf?: (id: string, host: Context) => unknown;
 }
 
 /**
@@ -110,6 +112,12 @@ export interface AgreeScheduleOptions {
   readonly values?: readonly unknown[];
   /** The contexts of the host at the start of the runs, one after the other. */
   readonly contexts?: readonly Context[];
+  /**
+   * The values of the `self` of a node (SCHED.NODE-AGREES). With them, the option `selfOf` of each engine gives each
+   * node its own `self`. Some nodes then share one document, and a change of data can give a node a new `self`. The
+   * value `undefined` keeps the `self` of the host. The default gives each node the context of the host.
+   */
+  readonly selves?: readonly unknown[];
   /** The number of runs. The default is 100. */
   readonly count?: number;
   /** The number of commands in one run. The default is 30. */
@@ -155,6 +163,10 @@ export interface ScheduleAgreementCounts {
   readonly same: number;
   /** The new machines. */
   readonly machines: number;
+  /** The changes of data with a new `self` of a node, only with the option `selves`. */
+  readonly selves: number;
+  /** The documents that a node shares with another node, only with the option `selves`. */
+  readonly shared: number;
 }
 
 /** The outcome of `agreeSchedule`: what the harness reached, or the first disagreement. */
@@ -266,7 +278,7 @@ function shuffle<T>(items: readonly T[], rng: Random): T[] {
  * This function evaluates each node of a graph from scratch, with the meaning of D31. Each node gets a new plan and
  * one value. The algorithm of Tarjan over the demands finds the cycles. The function keeps nothing between calls.
  */
-function fromScratch(machine: Machine, docs: ReadonlyMap<string, unknown>, base: Context, declaredType: string | undefined): ReadonlyMap<string, Result> {
+function fromScratch(machine: Machine, docs: ReadonlyMap<string, unknown>, base: Context, declaredType: string | undefined, own: ReadonlyMap<string, unknown> | undefined): ReadonlyMap<string, Result> {
   const declared = declaredType === undefined ? {} : { declaredType };
   const values = new Map<string, Result>();
   const index = new Map<string, number>();
@@ -298,7 +310,8 @@ function fromScratch(machine: Machine, docs: ReadonlyMap<string, unknown>, base:
     lowest.set(id, index.get(id) as number);
     component.push(id);
     evaluating.push(id);
-    let result = prepare(machine, docs.get(id), declared).evaluate(ctx);
+    const self = own?.get(id);
+    let result = prepare(machine, docs.get(id), declared).evaluate(self === undefined ? ctx : { ...ctx, self });
     evaluating.pop();
     if ((lowest.get(id) as number) < (index.get(id) as number)) result = cycleOf(id);
     else if (component.splice(component.indexOf(id)).length > 1 || selfReads.has(id)) result = cycleOf(id);
@@ -340,7 +353,8 @@ function named(result: Result): string {
 /**
  * This function examines an engine of a host against an evaluation from scratch (SCHED.AGREES, R4 P4, D58). Each run
  * makes a new engine and a random graph of named nodes from the document generator. Then it gives random commands:
- * edits, new nodes, removed nodes, the same document again, new machines and changes of data.
+ * edits, new nodes, removed nodes, the same document again, new machines and changes of data. The option `selves`
+ * adds a `self` for each node and documents that nodes share (SCHED.NODE-AGREES).
  *
  * - Each read command evaluates the whole graph from scratch two times, with the meaning of D31.
  * - It then demands each node in a random order, or one node, and compares each answer with `sameResult`.
@@ -366,6 +380,7 @@ export function agreeSchedule(engine: ScheduleEngineFactory, options: AgreeSched
   const hostNames = options.names ?? ["a", "b", "x", "n"];
   const hostValues = options.values ?? standardValues();
   const contexts = options.contexts ?? standardContexts();
+  const selves = options.selves;
   const total = options.count ?? 100;
   const steps = options.steps ?? 30;
   const first = options.seed ?? 9_000_011;
@@ -376,7 +391,7 @@ export function agreeSchedule(engine: ScheduleEngineFactory, options: AgreeSched
     if (isClosure(a) || isClosure(b)) return isClosure(a) && isClosure(b) && docEquals(closureParams(a), closureParams(b));
     return undefined;
   };
-  const counts = { reads: 0, compared: 0, unrepeatable: 0, values: 0, cycles: 0, runs: 0, data: 0, empty: 0, edits: 0, additions: 0, removes: 0, same: 0, machines: 0 };
+  const counts = { reads: 0, compared: 0, unrepeatable: 0, values: 0, cycles: 0, runs: 0, data: 0, empty: 0, edits: 0, additions: 0, removes: 0, same: 0, machines: 0, selves: 0, shared: 0 };
   const declared = declaredType === undefined ? {} : { declaredType };
   for (let run = 0; run < total; run += 1) {
     const seed = first + run;
@@ -385,7 +400,18 @@ export function agreeSchedule(engine: ScheduleEngineFactory, options: AgreeSched
     let at = 0;
     let machine = machines[0] as Machine;
     let made = 0;
+    const own = selves === undefined ? undefined : new Map<string, unknown>();
+    const pool: unknown[] = [];
     const make = (): unknown => {
+      if (selves !== undefined && pool.length > 0 && rng.chance(0.4)) {
+        counts.shared += 1;
+        return rng.pick(pool);
+      }
+      const doc = generated();
+      pool.push(doc);
+      return doc;
+    };
+    const generated = (): unknown => {
       if (rng.chance(wired)) return wire(rng, node);
       const roll = rng.int(10);
       if (roll === 0) return value(rng);
@@ -395,15 +421,16 @@ export function agreeSchedule(engine: ScheduleEngineFactory, options: AgreeSched
       return runs && roll === 9 ? { type: "log", value: [doc] } : doc;
     };
     const docs = new Map<string, unknown>(nodes.map((id) => [id, make()]));
+    if (own !== undefined && selves !== undefined) for (const id of nodes) own.set(id, rng.pick(selves));
     const start = contexts[run % contexts.length] as Context;
     let base: Context = { ...start, names: { ...start.names } };
-    const host = engine(machine, { ...declared, context: base });
+    const host = engine(machine, { ...declared, context: base, ...(own === undefined ? {} : { selfOf: (id: string) => own.get(id) }) });
     for (const [id, doc] of docs) host.set(id, doc);
     for (let step = 0; step < steps; step += 1) {
       const what = rng.int(12);
       if (what < 4) {
-        const fresh = fromScratch(machine, docs, base, declaredType);
-        const again = fromScratch(machine, docs, base, declaredType);
+        const fresh = fromScratch(machine, docs, base, declaredType, own);
+        const again = fromScratch(machine, docs, base, declaredType, own);
         const ids = shuffle([...docs.keys()], rng);
         // Half of the reads demand each node in a random order, and the other half demand one node.
         for (const id of rng.chance(0.5) ? ids : ids.slice(0, 1)) {
@@ -428,9 +455,15 @@ export function agreeSchedule(engine: ScheduleEngineFactory, options: AgreeSched
           }
         }
       } else if (what < 6) {
-        base = { ...base, names: change(base, rng, hostNames, hostValues) };
+        if (own !== undefined && selves !== undefined && rng.chance(0.5)) {
+          // A new `self` of one node, with the same context object of the host.
+          own.set(rng.pick(nodes), rng.pick(selves));
+          counts.selves += 1;
+        } else {
+          base = { ...base, names: change(base, rng, hostNames, hostValues) };
+          counts.data += 1;
+        }
         host.changeData(base);
-        counts.data += 1;
       } else if (what === 6) {
         // A change of data that changes no value: the same context object again.
         host.changeData(base);

package/src/parts.ts

@@ -41,10 +41,13 @@ export type Split =
   | { readonly ok: false; readonly reason: string; readonly at: readonly Key[] };
 
 class Bad {
-  constructor(
-    readonly reason: string,
-    readonly at: readonly Key[],
-  ) {}
+  readonly reason: string;
+  readonly at: readonly Key[];
+
+  constructor(reason: string, at: readonly Key[]) {
+    this.reason = reason;
+    this.at = at;
+  }
 }
 
 /** This function sets an own data property. Only the key `__proto__` needs `defineProperty`. */

package/src/providers.ts

@@ -150,6 +150,7 @@ function unionOf(types: readonly ValueType[]): ValueType {
 
 /** The state of one reading of a schema: the root, the issues and the definitions that it read. */
 class SchemaReader {
+  readonly root: unknown;
   readonly issues: TypeIssue[] = [];
   /** The type of each definition that a reference reached. Each reading of a definition is sound, thus the first stays. */
   readonly defs = new Map<string, ValueType>();
@@ -158,7 +159,9 @@ class SchemaReader {
   /** The number of schemas with an own `$id` around the current schema. A reference inside them has another base. */
   inner = 0;
 
-  constructor(readonly root: unknown) {}
+  constructor(root: unknown) {
+    this.root = root;
+  }
 
   issue(at: readonly Key[], reason: string): void {
     this.issues.push({ at, reason });

package/src/reference.ts

@@ -1,9 +1,23 @@
 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 CircularRule, type Kind, type TreeContract, circularOf, collectOf, equationType, lookupKind } from "./world.ts";
+import {
+  type AttributeDeclaration,
+  type CapsRule,
+  type CircularRule,
+  type Kind,
+  type TreeContract,
+  GENERATION_LIMIT,
+  atArgsOf,
+  atRuleOf,
+  circularOf,
+  collectOf,
+  documentKey,
+  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";
+import { type AttributeRung, AT_READERS, STD_EVALUATORS } from "./stdlib.ts";
 import { type EvalError, type Failed, type Result, Failure, describe, fail, ok, placed, thrown } from "./errors.ts";
 import {
   type AllOptions,
@@ -113,6 +127,8 @@ interface Env {
   scope: Scope;
   /** The count of the drives without a wait that are active. In a run, an effect under one does not reach the host (RUN.HELD). */
   held: number;
+  /** The count of the applications of closures that run at this time: the clock of `call` (FORMULA.CALL-DEPTH, D125). */
+  applying: number;
   /** The record of the reads. A nested evaluation for an equation of a tree keeps the record of its tree. */
   readonly reading: Reading | undefined;
 }
@@ -674,6 +690,7 @@ function envOf(machine: Machine, options: ReferenceOptions, running: boolean, ro
     verb: options.verb ?? "eval",
     scope: { prefix: "", counts: new Map(), alls: 0 },
     held: 0,
+    applying: 0,
     reading: outer ?? (options.reads === undefined ? undefined : { list: options.reads, root }),
   };
 }
@@ -879,6 +896,55 @@ function collectIn(node: RefNode, name: string, declared: unknown): Result {
   return visit(node) ?? acc;
 }
 
+/** TREE.HIGHER-DEPTH: the depth of each root of a generated document in the reference. */
+const refGenerations = /* @__PURE__ */ new WeakMap<RefNode, number>();
+
+/** TREE.HIGHER-DEPTH: the depth of the nearest root of a generated document at or above a node of the reference, or 0. */
+function generationIn(node: RefNode): number {
+  for (let at: RefNode | undefined = node; at !== undefined; at = at.up) {
+    const depth = refGenerations.get(at);
+    if (depth !== undefined) return depth;
+  }
+  return 0;
+}
+
+/**
+ * TREE.HIGHER: a higher-order attribute. The equation gives a document as data, and the document evaluates with the
+ * node as `self`. The reference compiles each document again, thus a structural key is not a part of the meaning.
+ */
+function higherOf(node: RefNode, name: string, term: Json): Result {
+  const value = equationOf(node, term, {});
+  if (!value.ok) return value;
+  const text = nameOfAttribute(node, name);
+  if (documentKey(value.value) === undefined) return fail("#VALUE!", `The equation of the higher-order attribute ${text} gives a value that is not JSON data.`);
+  const depth = generationIn(node) + 1;
+  if (depth > GENERATION_LIMIT) return fail("#DEPTH!", `The higher-order attribute ${text} is under more than ${GENERATION_LIMIT} generated documents.`);
+  const root = equationOf(node, value.value as Json, {});
+  if (!root.ok) return root;
+  const made = refNodeOf(root.value);
+  if (made === undefined) return fail("#VALUE!", `The document of the higher-order attribute ${text} gives no node of the tree.`);
+  refGenerations.set(made, depth);
+  return root;
+}
+
+/** TREE.FORWARD: the last rung. The attribute `forwards` gives a node, and that node answers through its own ladder. */
+function forwardOf(node: RefNode, name: string): Result | undefined {
+  const target: unknown = node.contract?.forwards;
+  if (target === undefined || target === name) return undefined;
+  const text = nameOfAttribute(node, name);
+  if (typeof target !== "string") return fail("#VALUE!", `The attribute ${text} has a contract with a bad field forwards. It must be a text.`);
+  const value = attributeOf(node, target);
+  if (value === undefined || !value.ok) return value;
+  const to = refNodeOf(value.value);
+  if (to === undefined) return fail("#VALUE!", `The attribute ${target} that ${text} forwards to gives no node of a tree.`);
+  if (!refGenerations.has(to)) {
+    const depth = generationIn(node) + 1;
+    if (depth > GENERATION_LIMIT) return fail("#DEPTH!", `The attribute ${text} forwards through more than ${GENERATION_LIMIT} generated documents.`);
+    refGenerations.set(to, depth);
+  }
+  return attributeOf(to, name);
+}
+
 /**
  * TREE.LADDER: the rungs of the ladder of an attribute, in their order. A rung gives `undefined` when it does not
  * answer, and the next rung then tries.
@@ -909,9 +975,11 @@ const REF_RUNGS: readonly (readonly [AttributeRung, (node: RefNode, name: string
       const declared = termIn(node.contract?.attributes, name);
       if (declared?.fold !== undefined) return foldOf(node, name, declared.fold);
       if (declared?.collect !== undefined) return collectIn(node, name, declared.collect);
-      return declared?.default === undefined ? undefined : equationOf(node, declared.default, {});
+      if (declared?.default !== undefined) return equationOf(node, declared.default, {});
+      return declared?.higher === undefined ? undefined : higherOf(node, name, declared.higher);
     },
   ],
+  ["forward", forwardOf],
 ];
 
 /** TREE.LADDER: the answer of the first rung that answers, or `undefined`. */
@@ -1069,6 +1137,53 @@ function attributeOf(node: RefNode, name: string): Result | undefined {
   return result;
 }
 
+/** TREE.AT: one instance of an attribute with parameters of a node. Its result is `undefined` while it evaluates. */
+interface RefInstance {
+  readonly attr: string;
+  readonly names: unknown;
+  result: Result | undefined;
+}
+
+/** TREE.AT: the instances of each node of the reference. Two arguments are the same instance by DOC.EQUALS. */
+const refInstances = /* @__PURE__ */ new WeakMap<RefNode, RefInstance[]>();
+
+/**
+ * TREE.AT: the instance of an attribute with parameters, or `undefined` when the kind has no entry in `tree.at`. The
+ * equation sees the arguments as names. A demand of an instance in evaluation gives `#CYCLE!`, also in a fixed point.
+ */
+function instanceOf(node: RefNode, attr: string, args: unknown): Result | undefined {
+  const declared = termIn(node.contract?.at, attr);
+  if (declared === undefined) return undefined;
+  const rule = atRuleOf(declared);
+  if (!rule.ok) return fail("#VALUE!", `The attribute ${nameOfAttribute(node, attr)} has a bad entry tree.at. ${rule.reason}`);
+  const given = atArgsOf(rule.params, args);
+  if (!given.ok) return fail("#VALUE!", `The step tree.at of ${nameOfAttribute(node, attr)} has bad arguments. ${given.reason}`);
+  const name = `${attr} with ${given.key}`;
+  const list = refInstances.get(node) ?? [];
+  refInstances.set(node, list);
+  const found = list.find((item) => item.attr === attr && docEquals(item.names, given.names));
+  if (found?.result !== undefined) return found.result;
+  if (found !== undefined) {
+    const from = inEvaluation.findIndex((entry) => entry.node === node && entry.name === name);
+    const steps = inEvaluation.slice(from).map((entry) => nameOfAttribute(entry.node, entry.name));
+    return fail("#CYCLE!", `The attributes form a cycle: ${[...steps, nameOfAttribute(node, name)].join(" -> ")}.`);
+  }
+  const item: RefInstance = { attr, names: given.names, result: undefined };
+  list.push(item);
+  const entry = { node, name, circular: false, tentative: false };
+  inEvaluation.push(entry);
+  let result: Result | undefined;
+  try {
+    result = equationOf(node, rule.equation, given.names);
+  } finally {
+    inEvaluation.pop();
+    // A result that read an approximation is not kept (TREE.CIRCULAR).
+    if (result === undefined || entry.tentative) list.splice(list.indexOf(item), 1);
+    else item.result = result;
+  }
+  return result;
+}
+
 /** TREE.RESULT: the JSON of a node. `open` holds the nodes and the containers whose JSON is in progress. */
 function jsonOfNode(node: RefNode, self: HostThing, open: readonly object[]): Result {
   const record: Record<string, unknown> = {};
@@ -1157,6 +1272,7 @@ const treeDefinition: EvalFn = ({ parts, context, kind, place, machine, typePath
   };
   node.thing = self;
   refNodes.set(self, node);
+  AT_READERS.set(self, (attr, args) => instanceOf(node, attr, args));
   if (nested) return ok(self);
   try {
     return jsonOfNode(node, self, []);
@@ -1285,13 +1401,22 @@ export function formulaDefinitions(profile: FormulaProfile = {}): Definitions {
     }
     const names = params as readonly string[];
     const body = partNamed(parts, "body") as Part;
+    // FORMULA.CALL-DEPTH: the evaluation that makes the closure counts its applications. A quarter of maxDepth is the limit.
+    const clock = activeEnvs[activeEnvs.length - 1] ?? { applying: 0, maxDepth: 1000 };
+    const limit = Math.ceil(clock.maxDepth / 4);
     const closure = (...args: readonly unknown[]): unknown => {
-      const scope: Record<string, unknown> = {};
-      for (const key of Object.keys(context.names)) setField(scope, key, context.names[key]);
-      names.forEach((name, index) => setField(scope, name, args[index]));
-      const result = body.evaluate({ ...context, names: scope });
-      if (!result.ok) throw new Failure(result.error);
-      return result.value;
+      if (clock.applying >= limit) throw new Failure(fail("#DEPTH!", `The applications of functions nest deeper than ${limit} levels.`).error);
+      clock.applying += 1;
+      try {
+        const scope: Record<string, unknown> = {};
+        for (const key of Object.keys(context.names)) setField(scope, key, context.names[key]);
+        names.forEach((name, index) => setField(scope, name, args[index]));
+        const result = body.evaluate({ ...context, names: scope });
+        if (!result.ok) throw new Failure(result.error);
+        return result.value;
+      } finally {
+        clock.applying -= 1;
+      }
     };
     Object.defineProperty(closure, CLOSURE, { value: { params: names } });
     return ok(closure);