@mark1russell7/coeval 0.6.1 → 0.6.3

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package",
   "name": "@mark1russell7/coeval",
-  "version": "0.6.1",
+  "version": "0.6.3",
   "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",
@@ -36,6 +36,7 @@
   "devDependencies": {
     "@mark1russell7/cue": "github:mark1russell7/cue",
     "@types/node": "^26.6.4",
+    "esbuild": "^0.28.2",
     "typescript": "^7.0.2",
     "vitest": "^5.0.3"
   },

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,6 +21,12 @@ 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 options of `agree`. */
 export interface AgreeOptions {
   /** The type of a bare root value. */
@@ -34,9 +40,15 @@ export interface AgreeOptions {
    *
    * @param doc - The document.
    * @param context - The context.
+   * @param input - The mock of the host, when `agree` has one.
    * @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 +92,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,50 +102,17 @@ 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 = Symbol.for("coeval.closure");
+const CLOSURE = /* @__PURE__ */ Symbol.for("coeval.closure");
 
 function closureParams(fn: object): unknown {
   return (fn as { readonly [CLOSURE]?: { readonly params: readonly string[] } })[CLOSURE]?.params;
@@ -165,7 +145,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 +157,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 +170,22 @@ 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 mock = options.perform === undefined ? {} : { perform: options.perform };
   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 +199,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 +214,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, mock);
     } catch (error) {
       given = thrown(error, "the tier");
     }

package/src/deref.ts

@@ -6,7 +6,7 @@ import type { ErrorCode } from "./errors.ts";
  * The brand of a host thing: an object of the host that answers the steps of a path itself. The brand is a
  * global symbol, thus two copies of the kernel in one program know the things of each other.
  */
-export const THING: unique symbol = Symbol.for("coeval.thing") as never;
+export const THING: unique symbol = /* @__PURE__ */ Symbol.for("coeval.thing") as never;
 
 /**
  * A host thing: an object that answers the steps of a path itself, for example a node of a live tree. It is the
@@ -17,12 +17,22 @@ export interface HostThing {
   /** A short text for a reader, for example `node card`. */
   readonly label: string;
   /**
-   * This function answers one step.
+   * This function answers one step. A field that holds `undefined` also gives `undefined`. The function `has` tells
+   * the two cases apart (DEREF.HOST-UNDEFINED).
    *
    * @param key - The key of the step.
    * @returns What the step reaches, or `undefined` when it reaches nothing.
    */
   deref(key: Key): Thing | undefined;
+  /**
+   * This optional function tells if the thing has a field for a key. The kernel asks it only when `deref` gives
+   * `undefined`. Then `true` tells that the field holds `undefined`. A thing without `has` reads `undefined` as a
+   * missing field.
+   *
+   * @param key - The key of the step.
+   * @returns `true` when the thing has the field.
+   */
+  has?(key: Key): boolean;
   /**
    * This function gives the thing as a value, when a reference ends on it.
    *
@@ -34,7 +44,7 @@ export interface HostThing {
    * path without one call for each step.
    *
    * @param keys - The keys.
-   * @returns What the keys reach, or `undefined` when they reach nothing.
+   * @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;
 }
@@ -183,7 +193,8 @@ function plainStep(thing: unknown, key: Key): { readonly found: true; readonly v
 export function derefStep(nav: Navigator, thing: Thing, key: Key): { readonly thing: Thing; readonly by: HopBy } | undefined {
   if (isHostThing(thing)) {
     const reached = thing.deref(key);
-    return reached === undefined ? undefined : { thing: reached, by: "own" };
+    // DEREF.HOST-UNDEFINED: `has` tells a field that holds undefined from a missing field.
+    return reached !== undefined || thing.has?.(key) === true ? { thing: reached, by: "own" } : undefined;
   }
   if (nav.plain !== true && isEnvelope(thing)) {
     const envelope = thing as JsonRecord & Envelope;
@@ -220,7 +231,7 @@ export function isRef(thing: unknown): thing is Envelope & { readonly value: rea
   return path !== undefined && path.length === 1 && path[0] === "ref";
 }
 
-const worlds = new WeakMap<World, Json>();
+const worlds = /* @__PURE__ */ new WeakMap<World, Json>();
 
 /**
  * This function makes the thing of the root `world`: the entries of the world as JSON. An alias is a reference
@@ -256,7 +267,7 @@ export function context(parts: Partial<Context> = {}): Context {
 }
 
 const MAX_COLLAPSE = 64;
-const NO_HOPS: readonly Hop[] = Object.freeze([]);
+const NO_HOPS: readonly Hop[] = /* @__PURE__ */ Object.freeze([]);
 
 /** A value that can be a reference document: a record with the type `ref`. The full check comes after. */
 function mayBeRef(thing: unknown): boolean {

package/src/doc.ts

@@ -230,20 +230,41 @@ export function fromJson(value: unknown): Envelope | undefined {
  * with this function does not keep a stale host value.
  *
  * The function does not use the stack for the depth, thus a deep document cannot overflow it. A cycle of lists or
- * records does not make it loop. `sameValue` of `agree` uses the same rules, and it adds rules for closures and for
- * a rule of the caller.
+ * records does not make it loop. `sameValue` of `agree` and `sameResult` use the same walk, and each adds its rules
+ * for other values (D20).
  *
  * @param a - The first value.
  * @param b - The second value.
  * @returns `true` when the values are equal.
  */
 export function docEquals(a: unknown, b: unknown): boolean {
+  return equalWith(a, b, undefined);
+}
+
+/** A rule for two values that are not the same by `Object.is`: `true`, `false`, or `undefined` for the next rule. */
+export type SameRule = (a: unknown, b: unknown) => boolean | undefined;
+
+/**
+ * This function is the one walk of `docEquals`, `sameValue` and `sameResult` (D20). It compares two values by the
+ * rules of `docEquals`. A rule of the caller answers first for each pair that is not the same by `Object.is`.
+ *
+ * @param a - The first value.
+ * @param b - The second value.
+ * @param rule - The rule of the caller. Its `undefined` gives the rules of `docEquals`.
+ * @returns `true` when the values are equal.
+ */
+export function equalWith(a: unknown, b: unknown, rule: SameRule | undefined): boolean {
   const stack: [unknown, unknown][] = [[a, b]];
   // The pairs of containers that the comparison already visits. It is made at the first pair of containers.
   let seen: Map<object, Set<object>> | undefined;
   while (stack.length > 0) {
     const [x, y] = stack.pop() as [unknown, unknown];
     if (Object.is(x, y)) continue;
+    const told = rule?.(x, y);
+    if (told !== undefined) {
+      if (told) continue;
+      return false;
+    }
     const list = Array.isArray(x);
     if (list !== Array.isArray(y)) return false;
     // An object that is not a list and not a plain record is a host value: Object.is above compared it.

package/src/errors.ts

@@ -16,7 +16,8 @@ export type KernelCode =
   | "#CAP!"
   | "#CALC!"
   | "#DEPTH!"
-  | "#ABORT";
+  | "#ABORT"
+  | "#REPLAY!";
 
 /** The code of an error value. A language can add its own codes. Each code starts with `#`. */
 export type ErrorCode = KernelCode | `#${string}`;