@mark1russell7/coeval 0.4.0 → 0.4.2

package/package.json

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

@@ -0,0 +1,231 @@
+import { type Key, docEquals, isRecord } 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 { Held, isClosure } from "./formula.ts";
+import { type Definitions, reference } from "./reference.ts";
+
+/**
+ * A tier that `agree` compares with the plan.
+ *
+ * - `reference`: the reference interpreter, which compiles nothing.
+ * - `traced`: the traced evaluation, `evaluate`.
+ * - `again`: a second evaluation of the same plan.
+ * - `other`: the second tier of a language, from the option `other`.
+ */
+export type Tier = "reference" | "traced" | "again" | "other";
+
+/** What a second tier gives: its result, and its effects when it records them. */
+export interface TierResult {
+  readonly result: Result;
+  readonly effects?: readonly Effect[];
+}
+
+/** The options of `agree`. */
+export interface AgreeOptions {
+  /** The type of a bare root value. */
+  readonly declaredType?: 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. */
+  readonly tiers?: readonly Exclude<Tier, "other">[];
+  /**
+   * This function gives the result of the second tier of a language, for example a compiler to loops.
+   *
+   * @param doc - The document.
+   * @param context - The context.
+   * @returns The result, or the result with the effects.
+   */
+  readonly other?: (doc: unknown, context: Context) => Result | TierResult;
+  /**
+   * This function compares two values that the rules of `sameValue` do not know, for example two dates.
+   *
+   * @param a - The value of the plan.
+   * @param b - The value of the other tier.
+   * @returns `true` or `false`, or `undefined` to use the rules of `sameValue`.
+   */
+  readonly equal?: (a: unknown, b: unknown) => boolean | undefined;
+  /** `true`: two errors must also have the same reason, and each error must have a place. */
+  readonly strict?: boolean;
+  /**
+   * This function gives what the host saw since its last call, for example the calls of an operation. `agree` uses
+   * it before the plan and after each tier, and compares the results. Thus a tier that evaluates a part that the plan
+   * does not evaluate fails.
+   *
+   * @returns What the host saw.
+   */
+  readonly observe?: () => unknown;
+}
+
+/** The outcome of `agree`: the result of the plan, or the first tier that disagrees with it. */
+export type Agreement =
+  | { readonly ok: true; readonly result: Result; readonly effects: readonly Effect[] }
+  | {
+      readonly ok: false;
+      readonly tier: Tier;
+      /** The result of the plan. */
+      readonly plan: Result;
+      /** The result of the tier that disagrees. */
+      readonly other: Result;
+      /** One sentence that tells the difference. */
+      readonly reason: string;
+    };
+
+/**
+ * This function tells if two values are the same for `agree`. Lists and plain records compare item by item and field
+ * by field, and the order of the fields does not matter. Each other leaf compares with `Object.is`, thus `-0` is not
+ * `0`, and `NaN` is `NaN`. Two closures of `fn` are the same when they have the same parameters. Two `Held` values
+ * are the same when their errors have the same code and place. Identity is not compared.
+ *
+ * @param a - The first value.
+ * @param b - The second value.
+ * @param equal - The rule of the caller for other values. It answers first, and `undefined` gives the rules above.
+ * @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;
+}
+
+const CLOSURE = Symbol.for("coeval.closure");
+
+function closureParams(fn: object): unknown {
+  return (fn as { readonly [CLOSURE]?: { readonly params: readonly string[] } })[CLOSURE]?.params;
+}
+
+function codeAndPlace(error: EvalError): string {
+  return error.place === undefined ? error.code : `${error.code} at [${error.place.join(", ")}]`;
+}
+
+/** This function gives the difference of two errors, or `undefined` when they agree. */
+function errorDiffers(a: EvalError, b: EvalError, strict: boolean): string | undefined {
+  if (a.code !== b.code) return `The plan gives ${codeAndPlace(a)}, and the tier gives ${codeAndPlace(b)}.`;
+  if (strict && (a.place === undefined || b.place === undefined)) return `An error ${a.code} has no place.`;
+  if (a.place !== undefined && b.place !== undefined && !docEquals(a.place as readonly Key[], b.place as readonly Key[])) {
+    return `The error ${a.code} has the place [${a.place.join(", ")}] in the plan, and [${b.place.join(", ")}] in the tier.`;
+  }
+  if (strict && a.reason !== b.reason) return `The error ${a.code} has another reason in the tier: "${b.reason}" for "${a.reason}".`;
+  return undefined;
+}
+
+/** A host stack overflow is the one permitted difference (VALUE.DEPTH): the tiers use different numbers of frames. */
+function overflowed(result: Result): boolean {
+  return !result.ok && result.error.code === "#DEPTH!" && isStackOverflow(result.error.cause);
+}
+
+/** This function gives the difference of two results, or `undefined` when they agree. */
+function resultDiffers(a: Result, b: Result, options: AgreeOptions): string | undefined {
+  if (a.ok && b.ok) return sameValue(a.value, b.value, options.equal) ? undefined : "The plan and the tier give different values.";
+  if (!a.ok && !b.ok) return errorDiffers(a.error, b.error, options.strict === true);
+  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). */
+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) {
+    const x = a[index] as Effect;
+    const y = b[index] as Effect;
+    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.`;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * 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`.
+ *
+ * @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.
+ * @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 observe = options.observe;
+  observe?.();
+  const plan = prepare(machine, doc, declared);
+  const effects: Effect[] = [];
+  const result = plan.evaluate(context, { effects });
+  const saw = observe?.();
+
+  const differs = (other: Result, otherEffects: readonly Effect[] | undefined): string | undefined => {
+    if (overflowed(result) || overflowed(other)) return undefined;
+    const why = resultDiffers(result, other, options) ?? (otherEffects === undefined ? undefined : effectsDiffer(effects, otherEffects, options));
+    if (why !== undefined || observe === undefined) return why;
+    return sameValue(saw, observe(), options.equal) ? undefined : "The host saw other calls in the tier.";
+  };
+
+  for (const tier of options.tiers ?? ["reference", "traced", "again"]) {
+    let other: Result;
+    let otherEffects: Effect[] = [];
+    if (tier === "reference") {
+      other = reference(machine, doc, context, { ...declared, effects: otherEffects, ...(options.definitions === undefined ? {} : { definitions: options.definitions }) });
+    } else if (tier === "traced") {
+      const traced = evaluate(machine, doc, context, options.declaredType);
+      other = traced.result;
+      otherEffects = [...traced.effects];
+    } else {
+      other = plan.evaluate(context, { effects: otherEffects });
+    }
+    const why = differs(other, otherEffects);
+    if (why !== undefined) return { ok: false, tier, plan: result, other, reason: why };
+  }
+
+  if (options.other !== undefined) {
+    let given: Result | TierResult;
+    try {
+      given = options.other(doc, context);
+    } catch (error) {
+      given = thrown(error, "the tier");
+    }
+    const other = "result" in given ? given.result : given;
+    const why = differs(other, "result" in given ? given.effects : undefined);
+    if (why !== undefined) return { ok: false, tier: "other", plan: result, other, reason: why };
+  }
+  return { ok: true, result, effects };
+}

package/src/errors.ts

@@ -104,7 +104,12 @@ export class Failure extends Error {
  * @returns `true` for a stack overflow.
  */
 export function isStackOverflow(error: unknown): boolean {
-  return error instanceof RangeError && /call stack/i.test(error.message);
+  try {
+    return error instanceof RangeError && /call stack/i.test(error.message);
+  } catch {
+    // Near the limit of the stack, the test itself overflows: the regular expression throws a SyntaxError.
+    return true;
+  }
 }
 
 /**

package/src/evaluate.ts

@@ -1,7 +1,7 @@
 import { type Envelope, type Json, type Key, type TypeRef, isEnvelope, typeName } from "./doc.ts";
-import { type Split, splitParts } from "./parts.ts";
+import { type Split, pathMatches, splitParts } from "./parts.ts";
 import { ask, type Answer } from "./ladder.ts";
-import { type Lookup, type Side, type World, lookupKind } from "./world.ts";
+import { type CapsRule, type Lookup, type Side, type World, lookupKind } from "./world.ts";
 import { type ErrorCode, type EvalError, type Result, fail, ok, placed, thrown, describe } from "./errors.ts";
 import {
   type Cap,
@@ -74,6 +74,58 @@ export function narrow(parent: Context, next: Context): Context {
   return caps.length === next.caps.length ? next : { ...next, caps };
 }
 
+/** No capabilities. One list serves each masked part. */
+const NO_CAPS: readonly Cap[] = Object.freeze([]);
+
+/** No capability rules. One list serves each part that no rule narrows. */
+const NO_RULES: readonly CapsRule[] = Object.freeze([]);
+
+/**
+ * This function gives the capabilities that two lists both permit. An effect is permitted by the result when each
+ * list permits it. When the list `b` permits each capability of `a`, the result is the list `a` itself.
+ *
+ * @param a - The first list, for example the capabilities of a document.
+ * @param b - The second list, for example the list of a rule `only`.
+ * @returns The capabilities that both lists permit.
+ */
+export function intersectCaps(a: readonly Cap[], b: readonly Cap[]): readonly Cap[] {
+  if (a.every((cap) => permits(b, cap))) return a;
+  const out: Cap[] = [];
+  for (const cap of b) if (permits(a, cap)) out.push(cap);
+  for (const cap of a) if (permits(b, cap) && !permits(out, cap)) out.push(cap);
+  return out;
+}
+
+/** This function gives the capability rules of a kind that cover a part and change its capabilities. */
+function rulesFor(rules: readonly CapsRule[] | undefined, path: readonly Key[]): readonly CapsRule[] {
+  if (rules === undefined || rules.length === 0) return NO_RULES;
+  const out = rules.filter((rule) => rule.rule !== "same" && (rule.in === undefined || rule.in.some((pattern) => pathMatches(path, pattern))));
+  return out.length === 0 ? NO_RULES : out;
+}
+
+/** This function applies the rules that cover a part to the capabilities of its document. */
+function capsUnder(rules: readonly CapsRule[], caps: readonly Cap[]): readonly Cap[] {
+  let out = caps;
+  for (const rule of rules) {
+    if (rule.rule === "mask") return NO_CAPS;
+    if (rule.rule === "only") out = intersectCaps(out, rule.caps);
+  }
+  return out;
+}
+
+/**
+ * This function gives the capabilities that a kind gives one of its parts, by the capability rules of its contract.
+ * The kernel and the static kit both use it, thus a run and a check narrow the same way.
+ *
+ * @param rules - The capability rules of the kind (`Kind.caps`).
+ * @param path - The path of the part in the value of the document.
+ * @param caps - The capabilities of the document.
+ * @returns The capabilities of the part: the same list or a smaller one.
+ */
+export function partCaps(rules: readonly CapsRule[] | undefined, path: readonly Key[], caps: readonly Cap[]): readonly Cap[] {
+  return capsUnder(rulesFor(rules, path), caps);
+}
+
 /**
  * The steps of an evaluation that can wait. It yields a promise only when the host makes it wait. A runner takes the
  * result of a part with `yield*`, thus a run goes on at once until an effect waits. A runner does not yield a
@@ -780,7 +832,11 @@ interface Compiler {
 }
 
 function failing(c: Compiler, meta: Meta, place: readonly Key[], code: ErrorCode, reason: string): { readonly code: Code; readonly run: RunCode } {
-  const result = fail(code, reason, { place });
+  return failingWith(c, meta, fail(code, reason, { place }));
+}
+
+/** This function gives the code of a document that fails with one result at each evaluation. */
+function failingWith(c: Compiler, meta: Meta, result: Result): { readonly code: Code; readonly run: RunCode } {
   const plain: Code = () => result;
   return finish(c, meta, plain, function* () {
     return result;
@@ -892,7 +948,10 @@ function compileNode(c: Compiler, value: unknown, place: readonly Key[], declare
   }
   const parts: CompiledPart[] = split.parts.map((slot) => {
     const item = slot.item;
-    const compiled = compileNode(c, item, place.concat(slot.path), slot.of, depth + 1, slot.address === true);
+    // The capability rules of the contract narrow the context of the part, thus no evaluator can forget them.
+    const own = compileNode(c, item, place.concat(slot.path), slot.of, depth + 1, slot.address === true);
+    const rules = rulesFor(kind?.caps, slot.path);
+    const compiled = rules.length === 0 ? own : gated(rules, own);
     // The binding name is in the header of an envelope. Most parts have no name, thus the cheap test comes first.
     const header = typeof (item as { readonly name?: unknown } | null)?.name === "string" && isEnvelope(item) ? (item as { readonly name: string }).name : undefined;
     return header === undefined
@@ -912,15 +971,24 @@ function compileNode(c: Compiler, value: unknown, place: readonly Key[], declare
     fill: fillOf(split, doc),
     ...(address ? { address: true } : {}),
   };
+  // A compiler that throws fails its own document when that document evaluates, with its place (PLAN.FAIL-LATE).
   if (runner !== undefined) {
-    const inner: RunCode = isCompiledRunner(runner) ? runner.compileRun(input) : interpretRun(runner, input, split.fill);
+    let inner: RunCode;
+    try {
+      inner = isCompiledRunner(runner) ? runner.compileRun(input) : interpretRun(runner, input, split.fill);
+    } catch (error) {
+      return failingWith(c, meta, placed(thrown(error, `the runner ${name}`), place));
+    }
     const run = placedRun(inner, place, name);
     return finish(c, meta, runnerCode(run, place, kindText), run);
   }
 
-  const inner: Code = isCompiledEvaluator(evaluator as Evaluator)
-    ? (evaluator as CompiledEvaluator).compile(input)
-    : interpret(evaluator as EvalFn, input, split.fill);
+  let inner: Code;
+  try {
+    inner = isCompiledEvaluator(evaluator as Evaluator) ? (evaluator as CompiledEvaluator).compile(input) : interpret(evaluator as EvalFn, input, split.fill);
+  } catch (error) {
+    return failingWith(c, meta, placed(thrown(error, `the evaluator ${name}`), place));
+  }
   const code = placedCode(inner, place, name);
   return finish(c, meta, code, runOf(code));
 }
@@ -942,6 +1010,20 @@ function placedCode(inner: Code, place: readonly Key[], name: string): Code {
   };
 }
 
+/**
+ * This function gives the code of a part that capability rules cover. The code narrows the context of the part by
+ * the rules before the part starts.
+ */
+function gated(rules: readonly CapsRule[], part: { readonly code: Code; readonly run: RunCode }): { readonly code: Code; readonly run: RunCode } {
+  const inner = part.code;
+  const steps = part.run;
+  const under = (ctx: Context): Context => {
+    const caps = capsUnder(rules, ctx.caps);
+    return caps === ctx.caps || (caps.length === 0 && ctx.caps.length === 0) ? ctx : { ...ctx, caps };
+  };
+  return { code: (ctx, rt) => inner(under(ctx), rt), run: (ctx, rt) => steps(under(ctx), rt) };
+}
+
 /** This function gives the steps of a runner, with the place of each error and of each exception. */
 function placedRun(inner: RunCode, place: readonly Key[], name: string): RunCode {
   return function* (ctx, rt) {
@@ -953,12 +1035,15 @@ function placedRun(inner: RunCode, place: readonly Key[], name: string): RunCode
   };
 }
 
-/** This function gives the code of a runner in an evaluation: its steps, which cannot wait. */
+/**
+ * This function gives the code of a runner in an evaluation: its steps, which cannot wait. A step that waits gives
+ * `#CALC!` at the place of the runner, where the error started (RUN.WAIT).
+ */
 function runnerCode(run: RunCode, place: readonly Key[], kindText: string): Code {
   return (ctx, rt) =>
     rt.running
       ? fail("#CALC!", `${kindText} waits for effects, and its parent cannot wait. Give the parent a runner.`, { place })
-      : drive(run(ctx, rt));
+      : placed(drive(run(ctx, rt)), place);
 }
 
 /** This function gives the steps of a run of an evaluator. The code runs at the first step, and it does not wait. */
@@ -1050,7 +1135,7 @@ export function prepare(machine: Machine, doc: unknown, options: PrepareOptions
   try {
     root = compileNode(c, doc, [], options.declaredType, 0);
   } catch (error) {
-    const result = thrown(error, "the compilation");
+    const result = placed(thrown(error, "the compilation"), []);
     root = {
       code: () => result,
       run: function* () {

package/src/formula.ts

@@ -225,16 +225,18 @@ export function formulaEvaluators(profile: FormulaProfile = {}): Readonly<Record
         if (missing !== undefined && missing(reached)) return fail("#N/A", "The path reaches no value.");
         return ok(reached);
       };
-      // The step documents of a path are its parts when the kind ref has a deep shape. They evaluate first, in order.
-      const computed = parts.length > 0;
+      const held = (ctx: Context): Failed | undefined => {
+        if (head === undefined || !Object.hasOwn(ctx.names, head)) return undefined;
+        const bound = ctx.names[head];
+        return bound instanceof Held ? { ok: false, error: bound.error } : undefined;
+      };
+      if (parts.length === 0) return (ctx, rt) => held(ctx) ?? give(rt.resolve(ctx, path));
+      // The step documents of a path are its parts when the kind ref has a deep shape. They evaluate first, in order,
+      // thus the error of a step comes before the error of a binding that the path reads (FORMULA.STEPS).
       return (ctx, rt) => {
-        if (head !== undefined && Object.hasOwn(ctx.names, head)) {
-          const bound = ctx.names[head];
-          if (bound instanceof Held) return { ok: false, error: bound.error };
-        }
-        if (!computed) return give(rt.resolve(ctx, path));
         const steps = valuesOf(parts, ctx, rt);
-        return Array.isArray(steps) ? give(rt.resolve(ctx, fill(steps) as readonly unknown[])) : steps;
+        if (!Array.isArray(steps)) return steps;
+        return held(ctx) ?? give(rt.resolve(ctx, fill(steps) as readonly unknown[]));
       };
     }),