@mark1russell7/coeval 0.14.0 → 0.16.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package",
   "name": "@mark1russell7/coeval",
-  "version": "0.14.0",
+  "version": "0.16.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, sharedCopy } 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.
@@ -13,9 +14,11 @@ import { type Definitions, reference } from "./reference.ts";
  * - `again`: a second evaluation of the same plan.
  * - `folds`: a second plan with the other choice of folds (PLAN.FOLD). It has no folds when the plan has them, and
  *   it has folds when the option `observe` stops the folds of the plan.
+ * - `fixed`: a plan that declares each name of plain data fixed (PLAN.FIXED). It evaluates with a frozen copy of
+ *   each such name, and then with the context of `agree`. `agreeRun` does not have this tier.
  * - `other`: the second tier of a language, from the option `other`.
  */
-export type Tier = "reference" | "traced" | "again" | "folds" | "other";
+export type Tier = "reference" | "traced" | "again" | "folds" | "fixed" | "other";
 
 /** What a second tier gives: its result, and its effects when it records them. */
 export interface TierResult {
@@ -44,8 +47,8 @@ export interface AgreeOptions {
   /** The definitional code of the compiled evaluators of the machine, for the reference. */
   readonly definitions?: Definitions;
   /**
-   * The tiers to compare with the plan. The default is the reference, the traced evaluation, a second evaluation and
-   * the plan with the other choice of folds.
+   * The tiers to compare with the plan. The default is the reference, the traced evaluation, a second evaluation, the
+   * plan with the other choice of folds and the plan with fixed names.
    */
   readonly tiers?: readonly Exclude<Tier, "other">[];
   /**
@@ -84,7 +87,7 @@ export interface AgreeOptions {
 }
 
 /** The tiers that `agree` compares when its options name none. */
-const DEFAULT_TIERS: readonly Exclude<Tier, "other">[] = /* @__PURE__ */ Object.freeze(["reference", "traced", "again", "folds"]);
+const DEFAULT_TIERS: readonly Exclude<Tier, "other">[] = /* @__PURE__ */ Object.freeze(["reference", "traced", "again", "folds", "fixed"]);
 
 /** The outcome of `agree`: the result of the plan, or the first tier that disagrees with it. */
 export type Agreement =
@@ -131,7 +134,8 @@ function sameInTiers(x: unknown, y: unknown): boolean | undefined {
 
 const CLOSURE = /* @__PURE__ */ Symbol.for("coeval.closure");
 
-function closureParams(fn: object): unknown {
+/** This function gives the parameters of a closure of `fn`, or `undefined` for another function. */
+export function closureParams(fn: object): unknown {
   return (fn as { readonly [CLOSURE]?: { readonly params: readonly string[] } })[CLOSURE]?.params;
 }
 
@@ -183,6 +187,57 @@ function effectsDiffer(a: readonly Effect[], b: readonly Effect[], options: Agre
   return undefined;
 }
 
+/**
+ * This function compares the plan with the tier `fixed` (PLAN.FIXED). The tier declares each name of plain data fixed,
+ * with a frozen copy of its value. It evaluates with these copies, thus the folds with fixed names give the result.
+ * Then it evaluates with the context of `agree`, thus the code without the fold gives the result. A fold moves the
+ * calls of the host to the compilation, thus only the result and the effects compare.
+ */
+function fixedDiffers(
+  machine: Machine,
+  doc: unknown,
+  context: Context,
+  result: Result,
+  effects: readonly Effect[],
+  given: { readonly declaredType?: string; readonly verb?: string; readonly perform?: Perform },
+  options: AgreeOptions,
+): { readonly other: Result; readonly reason: string } | undefined {
+  const { perform, ...declared } = given;
+  const held = fixedContext(context);
+  const plan = prepare(machine, doc, { ...declared, fixed: { names: held.fixed } });
+  for (const each of [held.context, context]) {
+    const tierEffects: Effect[] = [];
+    const other = plan.evaluate(each, { effects: tierEffects, ...(perform === undefined ? {} : { perform }) });
+    options.observe?.();
+    if (overflowed(result) || overflowed(other)) continue;
+    const reason = resultDiffers(result, other, options) ?? effectsDiffer(effects, tierEffects, options);
+    if (reason !== undefined) return { other, reason };
+  }
+  return undefined;
+}
+
+/**
+ * This function gives the context of the tier `fixed`. Each name of plain data gets a deeply frozen copy of its value,
+ * and the record of the fixed names holds the same copy. Each other name keeps its value.
+ */
+function fixedContext(context: Context): { readonly context: Context; readonly fixed: Readonly<Record<string, unknown>> } {
+  const given = context.names;
+  const names = Object.create(Object.getPrototypeOf(given) as object | null) as Record<string, unknown>;
+  const fixed = Object.create(null) as Record<string, unknown>;
+  for (const key of Reflect.ownKeys(given)) {
+    let field = Object.getOwnPropertyDescriptor(given, key) as PropertyDescriptor;
+    if (typeof key === "string" && "value" in field) {
+      const copy = sharedCopy(field.value);
+      if (copy !== undefined || field.value === undefined) {
+        Object.defineProperty(fixed, key, { value: copy, enumerable: true });
+        field = { ...field, value: copy };
+      }
+    }
+    Object.defineProperty(names, key, field);
+  }
+  return { context: { ...context, names }, fixed };
+}
+
 /**
  * This function evaluates a document with a plan and with other tiers, and compares the results (PLAN.AGREES). Two
  * results agree when they have the same value by `sameValue`, or errors with the same code, and the same place when
@@ -227,6 +282,10 @@ export function agree(machine: Machine, doc: unknown, context: Context = makeCon
       const traced = evaluate(machine, doc, context, { ...declared, ...mock });
       other = traced.result;
       otherEffects = [...traced.effects];
+    } else if (tier === "fixed") {
+      const why = fixedDiffers(machine, doc, context, result, effects, { ...declared, ...mock }, options);
+      if (why !== undefined) return { ok: false, tier, plan: result, other: why.other, reason: why.reason };
+      continue;
     } else if (tier === "folds") {
       other = prepare(machine, doc, { ...declared, fold: !folds }).evaluate(context, { effects: otherEffects, ...mock });
       if (observe !== undefined) {
@@ -257,3 +316,112 @@ 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) {
+    // A run has no tier with fixed names (PLAN.FIXED).
+    if (tier === "fixed") continue;
+    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/deref.ts

@@ -48,6 +48,15 @@ export interface HostThing {
    * @returns What the keys reach, or `undefined` when they reach nothing. `{ thing: undefined }` tells that the keys reach a field that holds `undefined`.
    */
   resolve?(keys: readonly Key[]): { readonly thing: Thing } | undefined;
+  /**
+   * This optional function answers one step only when the host has its value without new work (SCHED.CLOSURE). A
+   * kept read of a closure uses it, because the evaluation did not ask for that read. A schedule gives the value of
+   * a node that has its result in the data epoch. A throw gives the error of the step.
+   *
+   * @param key - The key of the step.
+   * @returns What the step reaches, or `undefined` when the host does not know it yet. Then the kept read ends at the thing.
+   */
+  known?(key: Key): { readonly thing: Thing } | undefined;
 }
 
 /** Something that a path can reach: any value of the host, or a host thing. */
@@ -116,6 +125,14 @@ export interface WalkInput {
    * @returns What the step reaches, or `undefined`.
    */
   deref(thing: Thing, key: Key): Thing | undefined;
+  /**
+   * This optional function records one hop inside the walk (HOP.EACH-STEP). The resolution gives it only when it
+   * records hops. The hop of the whole walk comes after these hops, as before.
+   *
+   * @param key - The key that the walk followed.
+   * @param thing - The thing that the key reached.
+   */
+  readonly visit?: (key: Key, thing: Thing) => void;
 }
 
 /** A walker: the code of the verb `step` of a kind of step documents. */
@@ -651,15 +668,16 @@ function resolveFully(nav: Navigator, ctx: Context, path: readonly unknown[], ho
         const walker = given === undefined ? walkerOf(nav, step) : (given ?? undefined);
         if (walker === undefined) return failed("#STEP?", "A step is a key, or a document of a kind with the verb step.");
         const envelope = step as Envelope;
-        const result = walker({
-          data: envelope.value,
-          here,
-          context: ctx,
-          deref: (thing, key) => {
-            const reached = derefStep(nav, thing, key);
-            return reached === undefined ? undefined : adopt(reached.thing);
-          },
-        });
+        const deref = (thing: Thing, key: Key): Thing | undefined => {
+          const reached = derefStep(nav, thing, key);
+          return reached === undefined ? undefined : adopt(reached.thing);
+        };
+        // A resolution without a record of hops gives no `visit`, thus a walker records nothing (HOP.EACH-STEP).
+        const result = walker(
+          hops === undefined
+            ? { data: envelope.value, here, context: ctx, deref }
+            : { data: envelope.value, here, context: ctx, deref, visit: (key, thing) => hops.push({ step: key, thing, by: "step" }) },
+        );
         if (!result.ok) return failed(result.code ?? "#N/A", result.reason);
         here = adopt(result.thing);
         hops?.push({ step: envelope as Json, thing: here, by: "step" });