@mark1russell7/coeval 0.6.2 → 0.6.3

package/src/index.ts

@@ -118,7 +118,9 @@ export {
   type EvalFn,
   type EvalInput,
   type EvalOptions,
+  type EvaluateOptions,
   type Evaluator,
+  type Journal,
   type Machine,
   type Part,
   type Perform,
@@ -135,6 +137,7 @@ export {
   type Steps,
   type StopSignal,
   type TraceNode,
+  JOURNAL,
   capKeys,
   evaluate,
   failures,
@@ -198,5 +201,7 @@ export {
   jsTruthy,
 } from "./formula.ts";
 export { type Definitions, type ReferenceOptions, STD_DEFINITIONS, formulaDefinitions, reference } from "./reference.ts";
-export { type AgreeOptions, type Agreement, type Tier, type TierResult, agree, sameValue } from "./agree.ts";
+export { type AgreeOptions, type Agreement, type Tier, type TierInput, type TierResult, agree, sameValue } from "./agree.ts";
+export { sameResult } from "./same.ts";
+export { type Recorder, type ReplayEntry, type ReplayLog, type ReplayOptions, type ReplaySettle, recorder, replayer } from "./replay.ts";
 export { type GenerateOptions, type Random, generate, random, typesOf } from "./generate.ts";

package/src/reference.ts

@@ -4,7 +4,7 @@ import type { CapsRule, Kind } from "./world.ts";
 import { type PartSlot, type Split, partsOf, pathMatches } from "./parts.ts";
 import { type Cap, type Context, type HostThing, type Resolution, type ResolveOptions, type Thing, THING, isHostThing, resolve, valueOfThing, worldThing } from "./deref.ts";
 import { STD_EVALUATORS } from "./stdlib.ts";
-import { type EvalError, type Failed, type Result, Failure, fail, ok, placed, thrown } from "./errors.ts";
+import { type EvalError, type Failed, type Result, Failure, describe, fail, ok, placed, thrown } from "./errors.ts";
 import {
   type AllOptions,
   type Effect,
@@ -12,6 +12,7 @@ import {
   type EvalInput,
   type Machine,
   type Part,
+  type Perform,
   type RunFn,
   type RunInput,
   type RunPart,
@@ -19,6 +20,7 @@ import {
   intersectCaps,
   makeContext,
   permits,
+  placeText,
 } from "./evaluate.ts";
 import { type FormulaProfile, type OpFn, Held, STD_EXT } from "./formula.ts";
 
@@ -45,6 +47,18 @@ export interface ReferenceOptions {
   readonly definitions?: Definitions;
   /** A list that gets each effect, in its order. */
   readonly effects?: Effect[];
+  /** The mock of the host (RUN.MOCK). It answers each effect at once. Without it, an effect gives its payload. */
+  readonly perform?: Perform;
+}
+
+/** The scope of the addresses of effects (RUN.ADDRESS): the root of the evaluation, or one item of `all`. */
+interface Scope {
+  /** The text before each address of the scope. */
+  readonly prefix: string;
+  /** The number of earlier effects at each place of the scope, by the text of the place. */
+  readonly counts: Map<string, number>;
+  /** The number of earlier uses of `all` in the scope. */
+  alls: number;
 }
 
 /** The state of one evaluation of the reference. */
@@ -53,6 +67,9 @@ interface Env {
   readonly definitions: Definitions;
   readonly effects: Effect[];
   readonly maxDepth: number;
+  readonly perform: Perform | undefined;
+  /** The scope of the code that evaluates at this time. `all` changes it for each item. */
+  scope: Scope;
 }
 
 /** The code that answers a document: a function evaluator, a runner, or a gap of the reference. */
@@ -167,15 +184,52 @@ function resolveFully(machine: Machine, ctx: Context, path: readonly unknown[],
   return options?.hops === true ? found : { ...found, hops: [] };
 }
 
-/** This function records an effect when the capabilities permit it (RUN.CAP, CAP.HOOK). */
-function record(env: Env, ctx: Context, kind: Cap, payload: unknown, place: readonly Key[]): Failed | undefined {
+/**
+ * This function causes an effect when the capabilities permit it (RUN.CAP, CAP.HOOK). It records the effect with its
+ * address (RUN.ADDRESS) and its outcome (RUN.OUTCOME). The mock answers the effect at once (RUN.MOCK). Without a
+ * mock, the effect gives its payload (RUN.EVAL).
+ */
+function cause(env: Env, ctx: Context, kind: Cap, payload: unknown, place: readonly Key[]): Result {
   const keys = typeof kind === "string" ? kind.split(".") : kind;
   const text = keys.join(".");
   const machine = env.machine;
   const allowed = machine.permits === undefined ? permits(ctx.caps, keys) : machine.permits(ctx.caps, keys, ctx);
   if (!allowed) return fail("#CAP!", `The context has no capability for the effect ${text}.`, { place });
-  env.effects.push({ index: env.effects.length, kind: text, path: keys, payload, node: -1, at: 0, place, context: ctx });
-  return undefined;
+  const at = placeText(place);
+  const count = env.scope.counts.get(at) ?? 0;
+  env.scope.counts.set(at, count + 1);
+  const effect: { -readonly [K in keyof Effect]: Effect[K] } = {
+    index: env.effects.length,
+    kind: text,
+    path: keys,
+    payload,
+    node: -1,
+    at: 0,
+    place,
+    context: ctx,
+    address: `${env.scope.prefix}${at}#${count}`,
+  };
+  env.effects.push(effect);
+  effect.outcome = answer(env.perform, effect, place);
+  return effect.outcome;
+}
+
+/**
+ * This function gives the answer of the mock to an effect. A throw gives `#CALC!` with the cause, and a `Failure`
+ * gives its own error value. A promise gives `#CALC!`, because an evaluation does not wait.
+ */
+function answer(perform: Perform | undefined, effect: Effect, place: readonly Key[]): Result {
+  if (perform === undefined) return ok(effect.payload);
+  let given: unknown;
+  try {
+    given = perform(effect);
+  } catch (error) {
+    if (error instanceof Failure) return placed({ ok: false, error: error.error }, place);
+    return fail("#CALC!", `The host failed the effect ${effect.kind}: ${describe(error)}`, { place, cause: error });
+  }
+  if (!(given instanceof Promise)) return ok(given);
+  void given.catch(() => undefined);
+  return fail("#CALC!", `The mock gave a promise for the effect ${effect.kind}, and an evaluation does not wait.`, { place });
 }
 
 /** This function evaluates a document. Each error gets the place of the document where it started (K5). */
@@ -247,7 +301,7 @@ function evalInput(env: Env, seen: Seen, at: At): EvalInput {
     place: at.place,
     ...(at.address ? { address: true } : {}),
     resolve: (path, options) => resolveFully(env.machine, at.ctx, path, options),
-    effect: (kind, payload) => record(env, at.ctx, kind, payload, at.place) ?? ok(payload),
+    effect: (kind, payload) => cause(env, at.ctx, kind, payload, at.place),
     fill,
   };
 }
@@ -275,9 +329,9 @@ function runInput(env: Env, seen: Seen, at: At): RunInput {
     place: at.place,
     resolve: (path, options) => resolveFully(env.machine, at.ctx, path, options),
     effect: function* (kind, payload) {
-      return record(env, at.ctx, kind, payload, at.place) ?? ok(payload);
+      return cause(env, at.ctx, kind, payload, at.place);
     },
-    all: (list, options) => together(list, options),
+    all: (list, options) => together(env, list, options),
     fill,
   };
 }
@@ -287,14 +341,21 @@ function runInput(env: Env, seen: Seen, at: At): RunInput {
  * goes on until it ends or waits. In an evaluation, a part that waits does not end, thus it keeps its place in the
  * limit. With `failFast`, the first failure stops the parts that wait, and the later parts do not start
  * (RUN.FAIL-FAST). When no part failed and a part waits, the steps wait, and the drive gives `#CALC!`.
+ *
+ * Each part has its own scope of addresses. Its prefix names the use of `all` in the scope around it, and the part
+ * (RUN.ADDRESS).
  */
-function* together(list: readonly RunPart[], options: AllOptions = {}): Generator<Promise<unknown>, readonly Result[], unknown> {
+function* together(env: Env, list: readonly RunPart[], options: AllOptions = {}): Generator<Promise<unknown>, readonly Result[], unknown> {
   const limit = Math.max(1, options.concurrency ?? list.length);
   const results: (Result | undefined)[] = list.map(() => undefined);
   const waiting: { readonly steps: Steps; readonly promise: Promise<unknown> }[] = [];
+  const outer = env.scope;
+  const address = `${outer.prefix}all${outer.alls}`;
+  outer.alls += 1;
   let failed = false;
   for (let index = 0; index < list.length && !failed && waiting.length < limit; index += 1) {
     let result: Result | undefined;
+    env.scope = { prefix: `${address}.${index}/`, counts: new Map(), alls: 0 };
     try {
       const steps = (list[index] as RunPart).evaluate();
       const step = steps.next();
@@ -302,6 +363,8 @@ function* together(list: readonly RunPart[], options: AllOptions = {}): Generato
       else waiting.push({ steps, promise: step.value });
     } catch (error) {
       result = thrown(error, "a part");
+    } finally {
+      env.scope = outer;
     }
     results[index] = result;
     if (result !== undefined && options.failFast === true && !result.ok) failed = true;
@@ -325,16 +388,23 @@ function* together(list: readonly RunPart[], options: AllOptions = {}): Generato
 /**
  * This function evaluates a document by the rules, without a compilation. It is the reference of the plans: a plan,
  * a traced plan and the second tier of a language must give its results. It covers evaluations, not runs: an effect
- * gives its payload, and a part that waits gives `#CALC!`.
+ * gives the answer of the mock or its payload, and a part that waits gives `#CALC!`.
  *
  * @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 type of a bare root value, the definitions of compiled code, and a list for the effects.
+ * @param options - The type of a bare root value, the definitions of compiled code, a list for the effects and a mock.
  * @returns The result.
  */
 export function reference(machine: Machine, doc: unknown, context: Context = makeContext(), options: ReferenceOptions = {}): Result {
-  const env: Env = { machine, definitions: options.definitions ?? {}, effects: options.effects ?? [], maxDepth: machine.maxDepth ?? 1000 };
+  const env: Env = {
+    machine,
+    definitions: options.definitions ?? {},
+    effects: options.effects ?? [],
+    maxDepth: machine.maxDepth ?? 1000,
+    perform: options.perform,
+    scope: { prefix: "", counts: new Map(), alls: 0 },
+  };
   const ctx = context.world === null ? { ...context, world: worldThing(machine.world) } : context;
   try {
     return evaluateAt(env, { value: doc, place: [], declared: options.declaredType, depth: 0, address: false, ctx });
@@ -461,6 +531,7 @@ const treeDefinition: EvalFn = ({ parts, context, kind, place }) => {
       if (result === undefined || result.ok) return result?.ok === true ? result.value : undefined;
       throw new Failure(result.error);
     },
+    has: (key) => key === "parent" || key === "type" || parts.some((part) => part.key === String(key)),
     toJson: () => {
       const result = jsonOfNode(node, self, []);
       if (result.ok) return result.value;

package/src/replay.ts

@@ -0,0 +1,159 @@
+import { docEquals } from "./doc.ts";
+import { type Result, Failure, fail } from "./errors.ts";
+import { type Effect, type Journal, type Perform, JOURNAL } from "./evaluate.ts";
+
+/*
+ * Record and replay (R2 P2, D19). A recorder wraps the function `perform` of a host and keeps a log. The log has each
+ * effect with its address, its request and its outcome, and the order in which the waits of each `all` settled. A
+ * replayer answers each effect from the log by its address, thus a replay does no host effect. The kernel gives the
+ * address and the outcome of each effect. The journal on the function `perform` carries the order of the waits.
+ */
+
+/** One effect of a log: its address, its request and its outcome. */
+export interface ReplayEntry {
+  /** The address of the effect (RUN.ADDRESS), for example `1#0` or `all0.1/1#0`. */
+  readonly address: string;
+  /** The kind of the effect, as a text with dots. */
+  readonly kind: string;
+  readonly payload: unknown;
+  /** The outcome of the effect (RUN.OUTCOME). It is absent when the recorded run stopped before the answer came. */
+  readonly outcome?: Result;
+  /** `true` when the host made the run wait for the outcome. */
+  readonly waited: boolean;
+}
+
+/** An item of an `all` whose wait settled in the recorded run. */
+export interface ReplaySettle {
+  /** The address of the `all`, for example `all0` or `all0.1/all0`. */
+  readonly all: string;
+  /** The index of the item. */
+  readonly item: number;
+}
+
+/** The log of a run: each effect in the order of the requests, and the order in which the waits of each `all` settled. */
+export interface ReplayLog {
+  readonly effects: readonly ReplayEntry[];
+  readonly settles: readonly ReplaySettle[];
+}
+
+/** A recorder: the function `perform` for a run, and the log of that run (RUN.RECORD). */
+export interface Recorder {
+  /** The function to give the run. It gives each effect to the function `perform` of the host, and it records the effect. */
+  readonly perform: Perform;
+  /**
+   * This function gives the log of the run until this time. An effect gets its outcome when the answer comes.
+   *
+   * @returns The log.
+   */
+  log(): ReplayLog;
+}
+
+/** The options of a replayer. */
+export interface ReplayOptions {
+  /**
+   * `false`: each answer comes at once, also for an effect that waited in the recorded run. An evaluation needs this
+   * value, because it does not wait. The default is `true`: an effect waits when it waited in the recorded run.
+   */
+  readonly wait?: boolean;
+}
+
+/**
+ * This function makes a recorder (RUN.RECORD). The recorder gives each effect to the function `perform` of the host.
+ * Its log keeps each effect with its address, its kind, its payload and the outcome that the kernel gives it. The log
+ * also keeps the order in which the waits of each `all` settle.
+ *
+ * @param perform - The function of the host. Without it, each effect gives its payload, as in a run without a host.
+ * @returns The function `perform` for the run, and the log.
+ */
+export function recorder(perform?: Perform): Recorder {
+  const seen: { readonly effect: Effect; waited: boolean }[] = [];
+  const settles: ReplaySettle[] = [];
+  const journal: Journal = {
+    settled: (all, item) => {
+      settles.push({ all, item });
+    },
+  };
+  const host = (effect: Effect): unknown => {
+    const entry = { effect, waited: false };
+    seen.push(entry);
+    const answer = perform === undefined ? effect.payload : perform(effect);
+    if (answer instanceof Promise) entry.waited = true;
+    return answer;
+  };
+  return {
+    perform: Object.assign(host, { [JOURNAL]: journal }),
+    log: () => ({
+      effects: seen.map(({ effect, waited }) => ({
+        address: effect.address ?? "",
+        kind: effect.kind,
+        payload: effect.payload,
+        waited,
+        ...(effect.outcome === undefined ? {} : { outcome: effect.outcome }),
+      })),
+      settles: [...settles],
+    }),
+  };
+}
+
+/**
+ * This function makes a replayer: a function `perform` that answers each effect from a log, by its address (RUN.REPLAY). A
+ * recorded error comes again with its code, its reason, its place and its cause. The waits of each `all` settle in the
+ * recorded order. An effect that the log does not have at its address gives `#REPLAY!` (RUN.REPLAY-MISMATCH).
+ *
+ * A replayer keeps its place in the order of the waits, thus each run needs a new replayer.
+ *
+ * @param log - The log of a recorder.
+ * @param options - `wait: false` for an evaluation.
+ * @returns The function `perform` for the replay.
+ */
+export function replayer(log: ReplayLog, options: ReplayOptions = {}): Perform {
+  const wait = options.wait !== false;
+  const entries = new Map<string, ReplayEntry>();
+  for (const entry of log.effects) entries.set(entry.address, entry);
+  const order = new Map<string, number[]>();
+  for (const settle of log.settles) {
+    const items = order.get(settle.all);
+    if (items === undefined) order.set(settle.all, [settle.item]);
+    else items.push(settle.item);
+  }
+  const journal: Journal = {
+    next: (all, waiting) => {
+      const items = order.get(all);
+      const item = items?.[0];
+      if (items === undefined || item === undefined || !waiting.includes(item)) return undefined;
+      items.shift();
+      return item;
+    },
+  };
+  const perform = (effect: Effect): unknown => {
+    const entry = effect.address === undefined ? undefined : entries.get(effect.address);
+    const wrong = mismatch(effect, entry);
+    if (wrong !== undefined || entry === undefined) throw wrong;
+    const outcome = entry.outcome;
+    const failure =
+      outcome === undefined
+        ? replayError(effect, `The log has no outcome for the effect ${effect.kind} at ${effect.address ?? ""}: the recorded run stopped before the answer.`)
+        : outcome.ok
+          ? undefined
+          : new Failure(outcome.error);
+    const value = outcome?.ok === true ? outcome.value : undefined;
+    if (wait && entry.waited) return failure === undefined ? Promise.resolve(value) : Promise.reject(failure);
+    if (failure !== undefined) throw failure;
+    return value;
+  };
+  return Object.assign(perform, { [JOURNAL]: journal });
+}
+
+/** This function gives the error of an effect that the log does not have at its address, or `undefined`. */
+function mismatch(effect: Effect, entry: ReplayEntry | undefined): Failure | undefined {
+  const at = effect.address ?? "";
+  if (entry === undefined) return replayError(effect, `The log has no effect at the address ${at}, and the run asks for the effect ${effect.kind}.`);
+  if (entry.kind !== effect.kind) return replayError(effect, `The log has the effect ${entry.kind} at the address ${at}, and the run asks for the effect ${effect.kind}.`);
+  if (!docEquals(entry.payload, effect.payload)) return replayError(effect, `The effect ${effect.kind} at the address ${at} has another payload than the log.`);
+  return undefined;
+}
+
+/** This function gives the exception that carries `#REPLAY!` to the kernel, with the place of the effect. */
+function replayError(effect: Effect, reason: string): Failure {
+  return new Failure(fail("#REPLAY!", reason, { place: effect.place }).error);
+}

package/src/same.ts

@@ -0,0 +1,42 @@
+import { type Key, docEquals, equalWith } from "./doc.ts";
+import type { EvalError, Result } from "./errors.ts";
+import { Held } from "./formula.ts";
+
+/**
+ * This function tells if two results are the same for an early cutoff (RESULT.SAME). A schedule uses it to stop the
+ * work when a part that evaluates again gives the same result. A wrong `true` keeps a stale value, but a wrong `false`
+ * only costs work. Thus each rule gives `false` when it is not sure.
+ *
+ * - Two values compare by the rules of `docEquals`. Lists and plain records compare by their items and fields. Each
+ *   other value compares with `Object.is`.
+ * - Thus `-0` is not `0`, and `NaN` is `NaN`. A date, a map and a closure of `fn` are the same only as themselves.
+ * - Two errors are the same when they have the same code, reason and place (RESULT.SAME-ERROR). The cause is not
+ *   compared. A `Held` value compares its error by the same rule.
+ * - A value and an error are not the same.
+ *
+ * `sameValue` of `agree` uses the same walk, with rules for two tiers (D20). It compares two closures by their
+ * parameters, and two errors by their code and place.
+ *
+ * @param a - The earlier result.
+ * @param b - The new result.
+ * @param equal - The rule of the host for two values, for example two dates. It answers first, and `undefined` gives the rules above.
+ * @returns `true` when the results are the same.
+ */
+export function sameResult(a: Result<unknown>, b: Result<unknown>, equal?: (a: unknown, b: unknown) => boolean | undefined): boolean {
+  if (a.ok && b.ok) return equalWith(a.value, b.value, equal === undefined ? sameHeld : (x, y) => equal(x, y) ?? sameHeld(x, y));
+  if (!a.ok && !b.ok) return sameError(a.error, b.error);
+  return false;
+}
+
+/** The rule of `sameResult` for held errors. Two `Held` values are the same when their errors are the same. */
+function sameHeld(x: unknown, y: unknown): boolean | undefined {
+  if (x instanceof Held || y instanceof Held) return x instanceof Held && y instanceof Held && sameError(x.error, y.error);
+  return undefined;
+}
+
+/** Two errors are the same when they have the same code, reason and place. An error without a place has no place in both. */
+function sameError(a: EvalError, b: EvalError): boolean {
+  if (a.code !== b.code || a.reason !== b.reason) return false;
+  if (a.place === undefined || b.place === undefined) return a.place === b.place;
+  return docEquals(a.place as readonly Key[], b.place as readonly Key[]);
+}

package/src/stdlib.ts

@@ -324,6 +324,10 @@ function treeThing(parts: readonly Part[], context: Context, type: string, place
       if (!result.ok) throw new Failure(result.error);
       return result.value;
     },
+    has(key: Key): boolean {
+      // DEREF.HOST-UNDEFINED: an attribute with the value undefined is a field, not a missing step.
+      return key === "parent" || key === "type" || parts.some((part) => part.key === String(key));
+    },
     toJson(): unknown {
       const result = state.json(new Set());
       if (!result.ok) throw new Failure(result.error);