@mark1russell7/coeval 0.14.0 → 0.15.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package",
   "name": "@mark1russell7/coeval",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "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",

package/src/agree.ts

@@ -1,9 +1,10 @@
 import { type Key, docEquals, equalWith } from "./doc.ts";
 import type { Context } from "./deref.ts";
 import { type EvalError, type Result, isStackOverflow, thrown } from "./errors.ts";
-import { type Effect, type Machine, type Perform, evaluate, makeContext, prepare } from "./evaluate.ts";
+import { type Effect, type Journal, type Machine, type Perform, JOURNAL, evaluate, makeContext, prepare, run } from "./evaluate.ts";
 import { Held, isClosure } from "./formula.ts";
-import { type Definitions, reference } from "./reference.ts";
+import { type Definitions, reference, referenceRun } from "./reference.ts";
+import { type ReplaySettle, recorder, replayer } from "./replay.ts";
 
 /**
  * A tier that `agree` compares with the plan.
@@ -257,3 +258,110 @@ export function agree(machine: Machine, doc: unknown, context: Context = makeCon
   }
   return { ok: true, result, effects };
 }
+
+/** The options of `agreeRun`: the options of `agree` without the second tier of a language. */
+export interface AgreeRunOptions extends Omit<AgreeOptions, "other" | "perform"> {
+  /**
+   * The host of the run of the plan (RUN.AGREES). A recorder wraps it, and each other tier replays the log of that run.
+   * Thus the host does each effect one time. Without it, an effect gives its payload.
+   */
+  readonly perform?: Perform;
+}
+
+/** The function `perform` of one run, with the effects that it got and the waits of `all` that settled. */
+interface Watched {
+  readonly perform: Perform;
+  readonly effects: Effect[];
+  readonly settles: ReplaySettle[];
+}
+
+/**
+ * This function wraps the function `perform` of a run. The wrapper keeps each effect and each wait of `all` that
+ * settles. It gives each effect to the inner function, and each call of its journal to the inner journal.
+ */
+function watched(perform: Perform): Watched {
+  const effects: Effect[] = [];
+  const settles: ReplaySettle[] = [];
+  const inner = (perform as { readonly [JOURNAL]?: Journal })[JOURNAL];
+  const settled = (all: string, item: number): void => {
+    settles.push({ all, item });
+    inner?.settled?.(all, item);
+  };
+  const journal: Journal = inner?.next === undefined ? { settled } : { settled, next: (all, waiting) => inner.next?.(all, waiting) };
+  const host = (effect: Effect): unknown => {
+    effects.push(effect);
+    return perform(effect);
+  };
+  return { perform: Object.assign(host, { [JOURNAL]: journal }), effects, settles };
+}
+
+function settleText(settle: ReplaySettle | undefined): string {
+  return settle === undefined ? "no item" : `the item ${settle.item} of ${settle.all}`;
+}
+
+/** This function gives the first difference of two orders of the waits of `all`, or `undefined` when they agree. */
+function settlesDiffer(a: readonly ReplaySettle[], b: readonly ReplaySettle[]): string | undefined {
+  for (let index = 0; index < Math.max(a.length, b.length); index += 1) {
+    const x = a[index];
+    const y = b[index];
+    if (x?.all !== y?.all || x?.item !== y?.item) return `The wait ${index} settles ${settleText(x)} in the plan, and ${settleText(y)} in the tier.`;
+  }
+  return undefined;
+}
+
+/**
+ * This function compares the run of a document in a plan with its run in other tiers (RUN.AGREES). First the plan
+ * starts the run with a recorder around the host. Then each tier replays the log of that run. These tiers are the
+ * reference run, the traced run, a second run of the plan and the plan with the other choice of folds.
+ *
+ * The rules of `agree` compare the results and the effects, with their addresses and outcomes. A tier must also
+ * settle the waits of each `all` in the order of the plan, thus a replay keeps the order of the waits.
+ *
+ * @param machine - The world, the evaluators and the runners.
+ * @param doc - The document.
+ * @param context - The names and the capabilities at the root.
+ * @param options - The tiers, the definitions for the reference, the rules of the comparison and the host.
+ * @returns The result of the plan, or the first tier that disagrees and the reason.
+ */
+export async function agreeRun(machine: Machine, doc: unknown, context: Context = makeContext(), options: AgreeRunOptions = {}): Promise<Agreement> {
+  const declared = {
+    ...(options.declaredType === undefined ? {} : { declaredType: options.declaredType }),
+    ...(options.verb === undefined ? {} : { verb: options.verb }),
+  };
+  const observe = options.observe;
+  observe?.();
+  // A fold moves host calls to the compilation, thus a plan whose calls the host compares has no folds (PLAN.FOLD).
+  const folds = observe === undefined;
+  const plan = prepare(machine, doc, { ...declared, fold: folds });
+  const recording = recorder(options.perform);
+  const first = watched(recording.perform);
+  const result = await plan.run(context, { perform: first.perform });
+  const saw = observe?.();
+  const log = recording.log();
+
+  for (const tier of options.tiers ?? DEFAULT_TIERS) {
+    const replay = watched(replayer(log));
+    const host = { perform: replay.perform };
+    let other: Result;
+    if (tier === "reference") {
+      other = await referenceRun(machine, doc, context, { ...declared, ...host, ...(options.definitions === undefined ? {} : { definitions: options.definitions }) });
+    } else if (tier === "traced") {
+      other = (await run(machine, doc, context, { ...declared, ...host })).result;
+    } else if (tier === "folds") {
+      other = await prepare(machine, doc, { ...declared, fold: !folds }).run(context, host);
+    } else {
+      other = await plan.run(context, host);
+    }
+    // The folds of the tier folds call the host when it compiles. Thus only its result, effects and waits compare.
+    const compareCalls = observe !== undefined && tier !== "folds";
+    const calls = observe?.();
+    if (overflowed(result) || overflowed(other)) continue;
+    const why =
+      resultDiffers(result, other, options) ??
+      effectsDiffer(first.effects, replay.effects, options) ??
+      settlesDiffer(first.settles, replay.settles) ??
+      (compareCalls && !sameValue(saw, calls, options.equal) ? "The host saw other calls in the tier." : undefined);
+    if (why !== undefined) return { ok: false, tier, plan: result, other, reason: why };
+  }
+  return { ok: true, result, effects: first.effects };
+}

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,32 @@ 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>;
+}
+
+/**
+ * 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, and the path ends at the first host thing. The host gives a new thing for a new state.
+ * 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, or `undefined` for a reference on the way.
+ */
+function keptPath(nav: Navigator, root: Context, path: readonly unknown[]): readonly unknown[] | undefined {
+  const adopt = nav.adopt ?? ((value: unknown): Thing => value);
+  let here = adopt(root[path[0] as Root]);
+  for (let index = 1; ; index += 1) {
+    if (isHostThing(here)) return index === path.length ? path : path.slice(0, index);
+    if (nav.plain !== true && isRef(here)) return undefined;
+    if (index >= path.length) return path;
+    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 path;
+    here = adopt(reached.thing);
+  }
 }
 
 /** This function makes the record of the reads of an evaluation, when the host gives a list. */
@@ -995,13 +1027,45 @@ 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 path = keptPath(this.machine, reading.root, read.exact ? exact : [root]);
+    if (path === undefined) return false;
+    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: 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.

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

@@ -250,8 +250,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";