@mark1russell7/coeval 0.6.2 → 0.7.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package",
   "name": "@mark1russell7/coeval",
-  "version": "0.6.2",
+  "version": "0.7.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,7 +1,7 @@
-import { type Key, docEquals, isRecord } from "./doc.ts";
+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, evaluate, makeContext, prepare } from "./evaluate.ts";
+import { type Effect, type Machine, type Perform, evaluate, makeContext, prepare } from "./evaluate.ts";
 import { Held, isClosure } from "./formula.ts";
 import { type Definitions, reference } from "./reference.ts";
 
@@ -21,10 +21,24 @@ export interface TierResult {
   readonly effects?: readonly Effect[];
 }
 
+/** What `agree` gives the second tier of a language beside the document and the context. */
+export interface TierInput {
+  /** The mock of the host, when `agree` has one (AGREE.MOCK). The tier answers each effect with it. */
+  readonly perform?: Perform;
+  /** The verb of `agree`, when its options name one (VERB.AGREE). A tier that does not serve the verb fails. */
+  readonly verb?: string;
+}
+
 /** The options of `agree`. */
 export interface AgreeOptions {
   /** The type of a bare root value. */
   readonly declaredType?: string;
+  /**
+   * The verb of each tier, as in `prepare`. The default is `eval`. The plan, the reference, the traced evaluation and a
+   * second evaluation each ask the ladder for this verb (VERB.AGREE). The second tier of a language gets it in its
+   * input.
+   */
+  readonly verb?: string;
   /** 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 and a second evaluation. */
@@ -34,9 +48,15 @@ export interface AgreeOptions {
    *
    * @param doc - The document.
    * @param context - The context.
+   * @param input - The mock of the host and the verb, when `agree` has them.
    * @returns The result, or the result with the effects.
    */
-  readonly other?: (doc: unknown, context: Context) => Result | TierResult;
+  readonly other?: (doc: unknown, context: Context, input: TierInput) => Result | TierResult;
+  /**
+   * The mock of the host (RUN.MOCK, AGREE.MOCK). Each tier gets it, thus the tiers agree on documents with effects. A
+   * mock must give the same answer to the same effect, because each tier asks it again.
+   */
+  readonly perform?: Perform;
   /**
    * This function compares two values that the rules of `sameValue` do not know, for example two dates.
    *
@@ -80,8 +100,9 @@ export type Agreement =
  * errors have the same code and place. Each other object is the same only as itself, unless the rule of the caller
  * tells otherwise.
  *
- * `docEquals` uses the same rules for lists, plain records and the other objects. It has no rules for closures, for
- * `Held` values and for a rule of the caller. Thus two closures are equal there only when they are the same function.
+ * `docEquals` and `sameResult` use the same walk (D20). `docEquals` has no rules for closures, for `Held` values and
+ * for a rule of the caller. `sameResult` is for an early cutoff, thus a closure is the same there only as itself, and
+ * two errors also need the same reason.
  *
  * @param a - The first value.
  * @param b - The second value.
@@ -89,47 +110,14 @@ export type Agreement =
  * @returns `true` when the values are the same.
  */
 export function sameValue(a: unknown, b: unknown, equal?: (a: unknown, b: unknown) => boolean | undefined): boolean {
-  const stack: (readonly [unknown, unknown])[] = [[a, b]];
-  const seen = new Map<object, Set<object>>();
-  while (stack.length > 0) {
-    const [x, y] = stack.pop() as readonly [unknown, unknown];
-    if (Object.is(x, y)) continue;
-    const told = equal?.(x, y);
-    if (told !== undefined) {
-      if (told) continue;
-      return false;
-    }
-    if (typeof x !== "object" && typeof x !== "function") return false;
-    if (typeof y !== "object" && typeof y !== "function") return false;
-    if (x === null || y === null) return false;
-    // A pair that the comparison already visits is the same, unless another pair shows a difference.
-    const pairs = seen.get(x) ?? new Set<object>();
-    if (pairs.has(y)) continue;
-    pairs.add(y);
-    seen.set(x, pairs);
-    if (isClosure(x) || isClosure(y)) {
-      if (!(isClosure(x) && isClosure(y))) return false;
-      stack.push([closureParams(x), closureParams(y)]);
-      continue;
-    }
-    if (x instanceof Held || y instanceof Held) {
-      if (!(x instanceof Held && y instanceof Held) || errorDiffers(x.error, y.error, false) !== undefined) return false;
-      continue;
-    }
-    if (Array.isArray(x) || Array.isArray(y)) {
-      if (!Array.isArray(x) || !Array.isArray(y) || x.length !== y.length) return false;
-      for (let index = 0; index < x.length; index += 1) stack.push([x[index], y[index]]);
-      continue;
-    }
-    if (!isRecord(x) || !isRecord(y)) return false;
-    const keys = Object.keys(x);
-    if (keys.length !== Object.keys(y).length) return false;
-    for (const key of keys) {
-      if (!Object.hasOwn(y, key)) return false;
-      stack.push([x[key], y[key]]);
-    }
-  }
-  return true;
+  return equalWith(a, b, equal === undefined ? sameInTiers : (x, y) => equal(x, y) ?? sameInTiers(x, y));
+}
+
+/** The rules of `sameValue` for the values that two tiers make again: closures and held errors. */
+function sameInTiers(x: unknown, y: unknown): boolean | undefined {
+  if (isClosure(x) || isClosure(y)) return isClosure(x) && isClosure(y) && docEquals(closureParams(x), closureParams(y));
+  if (x instanceof Held || y instanceof Held) return x instanceof Held && y instanceof Held && errorDiffers(x.error, y.error, false) === undefined;
+  return undefined;
 }
 
 const CLOSURE = /* @__PURE__ */ Symbol.for("coeval.closure");
@@ -165,7 +153,10 @@ function resultDiffers(a: Result, b: Result, options: AgreeOptions): string | un
   return a.ok ? `The plan gives a value, and the tier gives ${codeAndPlace((b as { readonly error: EvalError }).error)}.` : `The plan gives ${codeAndPlace(a.error)}, and the tier gives a value.`;
 }
 
-/** This function gives the difference of two lists of effects, or `undefined` when they agree (EFFECT.ORDER). */
+/**
+ * This function gives the difference of two lists of effects, or `undefined` when they agree (EFFECT.ORDER). When both
+ * tiers record the address or the outcome of an effect, these must agree too (AGREE.MOCK).
+ */
 function effectsDiffer(a: readonly Effect[], b: readonly Effect[], options: AgreeOptions): string | undefined {
   if (a.length !== b.length) return `The plan causes ${a.length} effects, and the tier causes ${b.length}.`;
   for (let index = 0; index < a.length; index += 1) {
@@ -174,6 +165,11 @@ function effectsDiffer(a: readonly Effect[], b: readonly Effect[], options: Agre
     if (x.kind !== y.kind || !docEquals(x.place as readonly Key[], y.place as readonly Key[]) || !sameValue(x.payload, y.payload, options.equal)) {
       return `The effect ${index} differs: ${x.kind} at [${x.place.join(", ")}] in the plan, and ${y.kind} at [${y.place.join(", ")}] in the tier.`;
     }
+    if (x.address !== undefined && y.address !== undefined && x.address !== y.address) {
+      return `The effect ${index} has the address ${x.address} in the plan, and ${y.address} in the tier.`;
+    }
+    const why = x.outcome !== undefined && y.outcome !== undefined ? resultDiffers(x.outcome, y.outcome, options) : undefined;
+    if (why !== undefined) return `The outcome of the effect ${index} differs. ${why}`;
   }
   return undefined;
 }
@@ -182,21 +178,26 @@ function effectsDiffer(a: readonly Effect[], b: readonly Effect[], options: Agre
  * 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
  * both have one. The effects must have the same kinds, places and payloads, in the same order. A language gives its
- * own tier with the option `other`.
+ * own tier with the option `other`. Each tier gets the mock of the option `perform` (AGREE.MOCK).
  *
  * @param machine - The world and the code of the evaluators.
  * @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 second tier.
+ * @param options - The tiers, the definitions for the reference, the rules of the comparison, the second tier and the mock.
  * @returns The result of the plan, or the first tier that disagrees and the reason.
  */
 export function agree(machine: Machine, doc: unknown, context: Context = makeContext(), options: AgreeOptions = {}): Agreement {
-  const declared = options.declaredType === undefined ? {} : { declaredType: options.declaredType };
+  const declared = {
+    ...(options.declaredType === undefined ? {} : { declaredType: options.declaredType }),
+    ...(options.verb === undefined ? {} : { verb: options.verb }),
+  };
+  const mock = options.perform === undefined ? {} : { perform: options.perform };
+  const tierInput: TierInput = { ...mock, ...(options.verb === undefined ? {} : { verb: options.verb }) };
   const observe = options.observe;
   observe?.();
   const plan = prepare(machine, doc, declared);
   const effects: Effect[] = [];
-  const result = plan.evaluate(context, { effects });
+  const result = plan.evaluate(context, { effects, ...mock });
   const saw = observe?.();
 
   const differs = (other: Result, otherEffects: readonly Effect[] | undefined): string | undefined => {
@@ -210,13 +211,13 @@ export function agree(machine: Machine, doc: unknown, context: Context = makeCon
     let other: Result;
     let otherEffects: Effect[] = [];
     if (tier === "reference") {
-      other = reference(machine, doc, context, { ...declared, effects: otherEffects, ...(options.definitions === undefined ? {} : { definitions: options.definitions }) });
+      other = reference(machine, doc, context, { ...declared, ...mock, effects: otherEffects, ...(options.definitions === undefined ? {} : { definitions: options.definitions }) });
     } else if (tier === "traced") {
-      const traced = evaluate(machine, doc, context, options.declaredType);
+      const traced = evaluate(machine, doc, context, { ...declared, ...mock });
       other = traced.result;
       otherEffects = [...traced.effects];
     } else {
-      other = plan.evaluate(context, { effects: otherEffects });
+      other = plan.evaluate(context, { effects: otherEffects, ...mock });
     }
     const why = differs(other, otherEffects);
     if (why !== undefined) return { ok: false, tier, plan: result, other, reason: why };
@@ -225,7 +226,7 @@ export function agree(machine: Machine, doc: unknown, context: Context = makeCon
   if (options.other !== undefined) {
     let given: Result | TierResult;
     try {
-      given = options.other(doc, context);
+      given = options.other(doc, context, tierInput);
     } catch (error) {
       given = thrown(error, "the tier");
     }