@mark1russell7/coeval 0.14.0 → 0.16.0

package/src/evaluate.ts

@@ -4,6 +4,7 @@ import { answerOf, ask, type Answer } from "./ladder.ts";
 import type { CapsRule, Kind, KindFacts, Side } from "./world.ts";
 import type { Domain } from "./types.ts";
 import type { TypeRule } from "./typing.ts";
+import type { StaticRead } from "./facts.ts";
 import { type ErrorCode, type EvalError, type Result, Failure, fail, ok, placed, thrown, describe } from "./errors.ts";
 import {
   type Cap,
@@ -17,6 +18,7 @@ import {
   type Thing,
   ROOTS,
   context as makeRootContext,
+  derefStep,
   isHostThing,
   isRef,
   resolve,
@@ -269,8 +271,8 @@ export interface Read {
    */
   readonly free: boolean;
   /**
-   * `true` when the kernel adds the read, because a value keeps a root of the context for later (READS.KEPT). Such a
-   * read has the whole root as its path.
+   * `true` when the kernel adds the read, because a value keeps the context for later (READS.KEPT). Such a read has
+   * a whole root as its path, or a path that a closure can read (READS.CLOSURE).
    */
   readonly kept?: true;
   /** The hops of the resolution, only when the code asked for them. `verifyReads` then compares each hop too. */
@@ -459,9 +461,13 @@ export interface Runtime {
   /**
    * This optional function tells the runtime that a value keeps the context for later, for example a closure of
    * `fn`. A later use of the value reads that context, and no evaluation records these reads. Thus the list of reads
-   * gets a read of each root of the context (READS.KEPT).
+   * gets a kept read of each path that the value can read (READS.CLOSURE). Without the static reads, the list gets a
+   * read of each root of the context (READS.KEPT).
+   *
+   * @param context - The context that the value keeps.
+   * @param reads - This function gives the static reads of the value, or `undefined` when they are not known.
    */
-  keepsContext?(): void;
+  keepsContext?(context?: Context, reads?: () => readonly StaticRead[] | undefined): void;
 }
 
 /**
@@ -894,6 +900,97 @@ interface Reading {
   kept: boolean;
   /** `true` after the kernel added the read of the root `self`. */
   self: boolean;
+  /** The paths of the kept reads of closures, as JSON texts (READS.CLOSURE). The set is made at the first such read. */
+  paths?: Set<string>;
+}
+
+/** The walk of a kept path: the path, and what it reached when a host thing answered a step with `known`. */
+interface KeptWalk {
+  readonly path: readonly unknown[];
+  /** What the path reached. Without it, the read resolves its path with `readAgain`. */
+  readonly reached?: Result;
+}
+
+/**
+ * This function gives the path of a kept read (READS.CLOSURE). The evaluation did not ask for the read. Thus the read
+ * does not step into a host thing with `deref`. A host thing with `known` answers a step without new work
+ * (SCHED.CLOSURE). Each other host thing ends the path, and a host thing that does not know the step ends it too.
+ * A reference in the data reads the context of its reader, thus the function then gives `undefined`.
+ *
+ * @param nav - The world and the code of the evaluators.
+ * @param root - The context at the root of the evaluation.
+ * @param path - The root and the keys of the static read.
+ * @returns The path of the kept read with what it reached after a step of `known`, or `undefined` for a reference on the way.
+ */
+function keptPath(nav: Navigator, root: Context, path: readonly unknown[]): KeptWalk | undefined {
+  const adopt = nav.adopt ?? ((value: unknown): Thing => value);
+  let here = adopt(root[path[0] as Root]);
+  // This mark is `true` after a step of `known`. Then the walk gives what the path reached, and no resolution follows.
+  let known = false;
+  const end = (index: number): KeptWalk => {
+    const kept = index >= path.length ? path : path.slice(0, index);
+    return known ? { path: kept, reached: ok(here) } : { path: kept };
+  };
+  for (let index = 1; ; index += 1) {
+    if (isHostThing(here)) {
+      if (index >= path.length || here.known === undefined) return end(index);
+      let step: { readonly thing: Thing } | undefined;
+      try {
+        step = here.known(path[index] as Key);
+      } catch (error) {
+        // A failed value gives its error to the read, as an exception in `readAgain` does.
+        return { path: path.slice(0, index + 1), reached: thrown(error, READ_FAILED) };
+      }
+      if (step === undefined) return end(index);
+      known = true;
+      here = adopt(step.thing);
+      continue;
+    }
+    if (nav.plain !== true && isRef(here)) return undefined;
+    if (index >= path.length) return end(index);
+    const reached = derefStep(nav, here, path[index] as Key);
+    // A step that reaches nothing fails, and the resolution of the path fails at the same step.
+    if (reached === undefined) return known ? end(index) : { path };
+    here = adopt(reached.thing);
+  }
+}
+
+/**
+ * This function resolves the path of a kept read again, for `verifyReads` (SCHED.CLOSURE). It walks the path as
+ * `keptPath` did. A host thing with `known` answers its step. A path without such a step resolves with `readAgain`.
+ *
+ * @param nav - The world and the code of the evaluators.
+ * @param ctx - The new context.
+ * @param path - The path of the kept read.
+ * @returns What the path reaches, or `undefined` when a host does not know a step yet. Then the read changed.
+ */
+export function keptAgain(nav: Navigator, ctx: Context, path: readonly unknown[]): Result | undefined {
+  const adopt = nav.adopt ?? ((value: unknown): Thing => value);
+  let here = adopt(ctx[path[0] as Root]);
+  let known = false;
+  // Before a step of `known`, each other answer of the walk is the answer of `readAgain`, as before SCHED.CLOSURE.
+  const other = (): Result | undefined => (known ? undefined : readAgain(nav, ctx, path, false).reached);
+  for (let index = 1; index < path.length; index += 1) {
+    if (isHostThing(here)) {
+      if (here.known === undefined) return other();
+      let step: { readonly thing: Thing } | undefined;
+      try {
+        step = here.known(path[index] as Key);
+      } catch (error) {
+        return thrown(error, READ_FAILED);
+      }
+      if (step === undefined) return undefined;
+      known = true;
+      here = adopt(step.thing);
+      continue;
+    }
+    if (nav.plain !== true && isRef(here)) return other();
+    const reached = derefStep(nav, here, path[index] as Key);
+    if (reached === undefined) return other();
+    here = adopt(reached.thing);
+  }
+  if (!known) return other();
+  return nav.plain !== true && isRef(here) ? undefined : ok(here);
 }
 
 /** This function makes the record of the reads of an evaluation, when the host gives a list. */
@@ -995,13 +1092,46 @@ class Session implements Runtime {
     return resolve(this.machine, ctx, path, hops ? WITH_HOPS : WITHOUT_HOPS);
   }
 
-  keepsContext(): void {
+  keepsContext(ctx?: Context, reads?: () => readonly StaticRead[] | undefined): void {
     const reading = this.reading;
     if (reading === undefined || reading.kept) return;
+    const known = ctx === undefined ? undefined : reads?.();
+    // A value without its static reads can read each root later (READS.KEPT).
+    if (ctx !== undefined && known !== undefined && known.every((read) => this.keepRead(reading, ctx, read))) return;
     reading.kept = true;
     this.keep(reading, reading.self ? ROOTS.filter((root) => root !== "self") : ROOTS);
   }
 
+  /**
+   * This function adds the kept read of one static read of a closure (READS.CLOSURE). The read resolves from the
+   * context at the root, one time in an evaluation. A name that a kind binds in the kept context gives no read,
+   * because the reads of its binding are already in the list.
+   *
+   * @returns `false` when the path meets a reference in the data. Then the closure keeps each whole root.
+   */
+  private keepRead(reading: Reading, ctx: Context, read: StaticRead): boolean {
+    const root = read.root;
+    const exact: readonly unknown[] = [root, ...read.keys];
+    if (!isFree(reading.root, ctx, exact)) {
+      // A kind that sets another self can give the old self on, as for a direct read (READS.KEPT).
+      if (root === "self" && !reading.self) this.keep(reading, ["self"]);
+      return true;
+    }
+    // A read of the whole root self already holds each path of self.
+    if (root === "self" && reading.self) return true;
+    // A step document can walk outside the keys of its path, thus such a read keeps the whole root.
+    const walk = keptPath(this.machine, reading.root, read.exact ? exact : [root]);
+    if (walk === undefined) return false;
+    const path = walk.path;
+    const paths = (reading.paths ??= new Set());
+    const text = JSON.stringify(path);
+    if (paths.has(text) || paths.has(JSON.stringify([root]))) return true;
+    paths.add(text);
+    if (path.length === 1 && root === "self") reading.self = true;
+    reading.list.push({ path, reached: walk.reached ?? readAgain(this.machine, reading.root, path, false).reached, free: true, kept: true });
+    return true;
+  }
+
   /**
    * This function adds a read of each whole root to the list, from the context at the root (READS.KEPT). An exception
    * of the host gives the error value of the read, because the evaluation did not ask for the read.
@@ -1338,6 +1468,15 @@ export interface PrepareOptions {
    * evaluates one time, when the plan compiles. Its result is one frozen value for each evaluation (PLAN.FOLD).
    */
   readonly fold?: boolean;
+  /**
+   * The values that the host declares fixed for each evaluation of the plan (PLAN.FIXED, D60). The field `names` gives
+   * a value for each fixed name. A path from a fixed name then resolves one time, when the plan compiles, and a pure
+   * part that reads only fixed names folds. Only a deeply frozen value of plain data fixes its name.
+   *
+   * Each folded part compares the value of its names with one own-key test and `Object.is`. A different value gives
+   * the code without the fold. A plan without folds ignores this option.
+   */
+  readonly fixed?: { readonly names?: Readonly<Record<string, unknown>> };
 }
 
 /** A compiled document. It evaluates many times, and it does the work of the ladder one time. */
@@ -1376,6 +1515,8 @@ interface Compiler {
   readonly noAnswer: Answer;
   /** `true` when closed pure parts fold (PLAN.FOLD). A plan with a trace does not fold. */
   readonly fold: boolean;
+  /** The fixed names and their values, or `undefined` when the plan has none (PLAN.FIXED). */
+  readonly fixed: Readonly<Record<string, unknown>> | undefined;
   /** The runtime of the folds of this compilation. The first fold makes it. */
   probe?: Probe;
 }
@@ -1536,7 +1677,11 @@ function compileNode(c: Compiler, value: unknown, place: readonly Key[], declare
   if (frees === undefined || kind === undefined || !pureCode(c, envelope, kind, typePath, name, quick)) return done;
   const free = freeOf(doc, kind, split.parts, frees);
   if (free === undefined) return done;
-  return free.length === 0 ? folded(c, done) : { code: done.code, run: done.run, free };
+  if (free.length === 0) return folded(c, done, undefined);
+  // A part that reads only fixed names folds, and its code compares the values of these names (PLAN.FIXED).
+  const fixed = c.fixed;
+  if (fixed !== undefined && free.every((each) => Object.hasOwn(fixed, each))) return folded(c, done, free);
+  return { code: done.code, run: done.run, free };
 }
 
 /*
@@ -1629,6 +1774,20 @@ class Probe implements Runtime {
     this.root = root;
   }
 
+  /** The context of a part that folds with fixed names: the context of the probe, with the fixed names (PLAN.FIXED). */
+  private withFixed: Context | undefined;
+
+  /**
+   * This function gives the context of a part that folds with fixed names. Its root `names` holds only the fixed
+   * names, thus the probe resolves each fixed name and refuses each other name.
+   *
+   * @param fixed - The fixed names and their values.
+   * @returns The context.
+   */
+  fixedRoot(fixed: Readonly<Record<string, unknown>>): Context {
+    return (this.withFixed ??= { ...this.root, names: fixed });
+  }
+
   resolve(ctx: Context, path: readonly unknown[]): Resolution {
     const name = path[1];
     if (path[0] === "names" && isKey(name) && Object.hasOwn(ctx.names, String(name))) {
@@ -1693,25 +1852,106 @@ function trap(refuse: () => void, copies: boolean): object {
  * one deeply frozen copy, and the code gives that copy at each evaluation (PLAN.SHARED). A fold that the probe cancels
  * gives the code without free names, thus no parent tries the fold again.
  */
-function folded(c: Compiler, done: Compiled): Compiled {
+function folded(c: Compiler, done: Compiled, fixed: readonly string[] | undefined): Compiled {
   const probe = (c.probe ??= new Probe(c.machine));
   probe.refused = false;
   probe.reads = 0;
   let constant: Result | undefined;
   try {
-    const result = done.code(probe.root, probe);
+    const root = fixed === undefined ? probe.root : probe.fixedRoot(c.fixed as Readonly<Record<string, unknown>>);
+    const result = done.code(root, probe);
     if (!probe.refused && (result.ok || result.error.code !== "#DEPTH!")) constant = sharedCopy(result) as Result | undefined;
   } catch {
     constant = undefined;
   }
   if (constant === undefined) return { code: done.code, run: done.run };
   const value = constant;
+  const original = done.code;
+  if (fixed !== undefined) return { code: fixedCode(fixed, c.fixed as Readonly<Record<string, unknown>>, value, original), run: undefined, free: fixed };
   if (probe.reads === 0) return { code: () => value, run: undefined, free: CLOSED };
   // The part reads its own names. A list of reads gets each read, thus the code evaluates again (READS.RECORD).
-  const original = done.code;
   return { code: (ctx, rt) => (rt instanceof Session && !rt.traced && !rt.recording ? value : original(ctx, rt)), run: undefined, free: CLOSED };
 }
 
+/**
+ * This function gives the code of a part that folded with fixed names (PLAN.FIXED, D60). The code gives the folded
+ * value when the context has the fixed value of each name, by an own-key test and `Object.is`. A fixed value is
+ * deeply frozen, thus the same object gives the same result. Each other context, a list of reads and another runtime
+ * get the code without the fold. The probe of a parent fold gets the folded value, and it counts a read.
+ */
+function fixedCode(names: readonly string[], fixed: Readonly<Record<string, unknown>>, value: Result, original: Code): Code {
+  if (names.length === 1) {
+    const name = names[0] as string;
+    const want = fixed[name];
+    return (ctx, rt) => {
+      const given = ctx.names;
+      return Object.hasOwn(given, name) && Object.is(given[name], want) && folds(rt) ? value : original(ctx, rt);
+    };
+  }
+  const wants = names.map((name) => fixed[name]);
+  return (ctx, rt) => {
+    const given = ctx.names;
+    for (let index = 0; index < names.length; index += 1) {
+      const name = names[index] as string;
+      if (!Object.hasOwn(given, name) || !Object.is(given[name], wants[index])) return original(ctx, rt);
+    }
+    return folds(rt) ? value : original(ctx, rt);
+  };
+}
+
+/**
+ * This function tells if the code of a part with fixed names can give its folded value in a runtime. The probe of a
+ * fold counts the read of the part, as the code without the fold reads the names.
+ */
+function folds(rt: Runtime): boolean {
+  if (rt instanceof Session) return !rt.recording;
+  if (!(rt instanceof Probe)) return false;
+  rt.reads += 1;
+  return true;
+}
+
+/**
+ * This function gives the fixed names of the options of `prepare` (PLAN.FIXED). A name fixes only when its value is
+ * deeply frozen plain data. Then no change in place can make the folded value stale.
+ *
+ * @returns A record without a prototype, or `undefined` when no name fixes.
+ */
+function fixedNamesOf(given: Readonly<Record<string, unknown>> | undefined): Readonly<Record<string, unknown>> | undefined {
+  if (given === undefined) return undefined;
+  let out: Record<string, unknown> | undefined;
+  for (const name of Object.keys(given)) {
+    const value = given[name];
+    if (!frozenPlain(value)) continue;
+    out ??= Object.create(null) as Record<string, unknown>;
+    Object.defineProperty(out, name, { value, enumerable: true });
+  }
+  return out;
+}
+
+/** This function tells if a value is plain data, as `sharedCopy` reads it, and if each of its objects is frozen. */
+function frozenPlain(value: unknown): boolean {
+  const seen = new Set<object>();
+  const walk = (here: unknown): boolean => {
+    if (typeof here === "function") return false;
+    if (typeof here !== "object" || here === null || SHARED.has(here) || seen.has(here)) return true;
+    if (!Object.isFrozen(here)) return false;
+    seen.add(here);
+    const proto: unknown = Object.getPrototypeOf(here);
+    if (Array.isArray(here) ? proto !== Array.prototype : proto !== Object.prototype && proto !== null) return false;
+    for (const key of Reflect.ownKeys(here)) {
+      const field = Object.getOwnPropertyDescriptor(here, key);
+      if (typeof key !== "string" || field === undefined || !("value" in field) || !walk(field.value)) return false;
+    }
+    return true;
+  };
+  try {
+    return walk(value);
+  } catch {
+    // A very deep value overflows the stack of the host.
+    return false;
+  }
+}
+
 /** The objects that a fold made. Each one is deeply frozen, thus a later fold uses it again and does not copy it. */
 const SHARED: WeakSet<object> = /* @__PURE__ */ new WeakSet();
 
@@ -1721,9 +1961,13 @@ const NOT_PLAIN: unique symbol = /* @__PURE__ */ Symbol("not plain");
 /**
  * This function gives a deeply frozen copy of plain data, or `undefined` for other values. Plain data is a primitive or
  * an array without holes and extra keys. It is also a record of enumerable data fields with the prototype of an object
- * or no prototype. The copy keeps cycles and shared objects. The objects of the host do not change.
+ * or no prototype. The copy keeps cycles and shared objects. The objects of the host do not change. The tier `fixed`
+ * of `agree` uses it. The package does not export it.
+ *
+ * @param value - The value.
+ * @returns The frozen copy, or `undefined`.
  */
-function sharedCopy(value: unknown): unknown {
+export function sharedCopy(value: unknown): unknown {
   try {
     const out = copyPlain(value, new Map());
     return out === NOT_PLAIN ? undefined : out;
@@ -1978,7 +2222,9 @@ export function prepare(machine: Machine, doc: unknown, options: PrepareOptions
   const verb = options.verb ?? "eval";
   const noAnswer: Answer = verb === "eval" ? NO_ANSWER : { verb, error: "no-answer", steps: [] };
   const traced = options.trace === true;
-  const c: Compiler = { machine, traced, maxDepth: machine.maxDepth ?? 1000, verb, noAnswer, fold: !traced && options.fold !== false };
+  const fold = !traced && options.fold !== false;
+  const fixed = fold ? fixedNamesOf(options.fixed?.names) : undefined;
+  const c: Compiler = { machine, traced, maxDepth: machine.maxDepth ?? 1000, verb, noAnswer, fold, fixed };
   let root: Compiled;
   try {
     root = compileNode(c, doc, [], options.declaredType, 0);

package/src/formula.ts

@@ -7,6 +7,7 @@ import { type MachinePart, mergeMachines } from "./merge.ts";
 import { type Domain, type ValueType, HEADER_KEYS, STD_DOMAINS, callable, fieldOf, fits, fnOf, holdsEnvelope, isPrecise, isUnknown, itemOf, join, member, stepType, typeText } from "./types.ts";
 import type { TypeInput, TypeRule } from "./typing.ts";
 import { decodeDomain, domainTypeOf } from "./codec.ts";
+import { type StaticRead, factsOf } from "./facts.ts";
 
 /** An operation of a formula language: a function of the values of its arguments. */
 export type OpFn = (...args: never[]) => unknown;
@@ -777,7 +778,7 @@ function formulaCode(profile: FormulaProfile): Readonly<Record<string, CompiledE
       };
     }),
 
-    "formula.fn": compiled(({ value, data }) => {
+    "formula.fn": compiled(({ value, data, doc, machine }) => {
       const params = isRecord(data) ? data["params"] : undefined;
       if (!Array.isArray(params) || !params.every((param) => typeof param === "string") || new Set(params).size !== params.length) {
         const bad = fail("#VALUE!", "The params of fn are a list of different texts.");
@@ -785,9 +786,22 @@ function formulaCode(profile: FormulaProfile): Readonly<Record<string, CompiledE
       }
       const names = params as readonly string[];
       const body = partsOf(value)["body"] as CompiledPart;
+      // The static reads of the function come at the first closure of an evaluation with a list of reads.
+      let known: readonly StaticRead[] | undefined | null = null;
+      const reads = (): readonly StaticRead[] | undefined => {
+        if (known !== null) return known;
+        // Only a pure document reads its context through the runtime alone (FACTS.PURE). Each other closure keeps each root.
+        try {
+          const facts = factsOf(machine, doc);
+          known = facts.pure ? facts.reads : undefined;
+        } catch {
+          known = undefined;
+        }
+        return known;
+      };
       return (ctx, rt) => {
-        // A closure keeps the context for each later use, thus the list of reads gets each root (READS.KEPT).
-        rt.keepsContext?.();
+        // A closure keeps the context for each later use, thus the list of reads gets each path that it can read (READS.CLOSURE).
+        rt.keepsContext?.(ctx, reads);
         const closure = (...args: readonly unknown[]): unknown => {
           const scope: Record<string, unknown> = { ...ctx.names };
           names.forEach((name, index) => setOwn(scope, name, args[index]));

package/src/index.ts

@@ -176,6 +176,7 @@ export {
   STD_WORLD,
   attributeTrace,
   nearestWalker,
+  placeOf,
 } from "./stdlib.ts";
 export {
   type Edge,
@@ -250,8 +251,8 @@ export {
   print,
   syntaxFormat,
 } from "./syntax.ts";
-export { type Definitions, type ReferenceOptions, STD_DEFINITIONS, formulaDefinitions, reference } from "./reference.ts";
-export { type AgreeOptions, type Agreement, type Tier, type TierInput, type TierResult, agree, sameValue } from "./agree.ts";
+export { type Definitions, type ReferenceOptions, type ReferenceRunOptions, STD_DEFINITIONS, formulaDefinitions, reference, referenceRun } from "./reference.ts";
+export { type AgreeOptions, type AgreeRunOptions, type Agreement, type Tier, type TierInput, type TierResult, agree, agreeRun, sameValue } from "./agree.ts";
 export { type ConformOptions, type ConformProbe, type Finding, type Obligation, conforms } from "./conform.ts";
 export { sameResult } from "./same.ts";
 export { type ReadsCheck, type VerifyOptions, verifyReads } from "./reads.ts";
@@ -266,6 +267,15 @@ export {
   edgesOf,
   schedule,
 } from "./schedule.ts";
+export {
+  type AgreeScheduleOptions,
+  type ScheduleAgreement,
+  type ScheduleAgreementCounts,
+  type ScheduleEngine,
+  type ScheduleEngineFactory,
+  type ScheduleEngineStart,
+  agreeSchedule,
+} from "./meaning.ts";
 export { type GraphCycle, type GraphEdge, type GraphNode, type GraphOptions, type NodeGraph, components, cycles, heights, necessary, nodeLayers } from "./graph.ts";
 export { type Recorder, type ReplayEntry, type ReplayLog, type ReplayOptions, type ReplaySettle, recorder, replayer } from "./replay.ts";
 export { type GenerateOptions, type Random, generate, random, typesOf } from "./generate.ts";