@mark1russell7/coeval 0.6.2 → 0.7.0

package/src/reads.ts

@@ -0,0 +1,105 @@
+import { docEquals } from "./doc.ts";
+import { type Result, ok } from "./errors.ts";
+import type { Context, Hop } from "./deref.ts";
+import { type Machine, type Plan, type Read, readAgain, rootContext } from "./evaluate.ts";
+import { Held } from "./formula.ts";
+import { sameResult } from "./same.ts";
+
+/*
+ * The verifying trace of a schedule (R4 P3, D26). An evaluation with the option `reads` records each path that it
+ * resolves, and what the path reached. A pure document is a function of its reads. Thus when each free read reaches
+ * the same thing in a new context, the old result stays valid, and the schedule keeps it without an evaluation.
+ */
+
+/** The answer of `verifyReads`: the old result stays valid, or the first read that reaches another thing. */
+export type ReadsCheck =
+  | { readonly same: true }
+  | {
+      readonly same: false;
+      /** The index of the first changed read in the list. */
+      readonly index: number;
+      /** The first changed read, as the evaluation recorded it. */
+      readonly read: Read;
+      /** What the path of that read reaches in the new context. */
+      readonly now: Result;
+    };
+
+/** The options of `verifyReads`. */
+export interface VerifyOptions {
+  /**
+   * The rule of the host for two things, as in `sameResult`. It answers first, and `undefined` gives the rules of
+   * `sameResult`. An example is a rule for a host thing that keeps a version.
+   *
+   * @param a - The thing of the recorded read.
+   * @param b - The thing in the new context.
+   * @returns `true` when the two things are the same, or `undefined` for the rules of `sameResult`.
+   */
+  readonly equal?: (a: unknown, b: unknown) => boolean | undefined;
+}
+
+/** One answer serves each list whose reads are all the same. */
+const SAME: ReadsCheck = /* @__PURE__ */ Object.freeze({ same: true });
+
+/** This function tells if two lists of hops are the same: the same steps, rungs and things, in order. */
+function sameHops(a: readonly Hop[], b: readonly Hop[] | undefined, equal: VerifyOptions["equal"]): boolean {
+  if (b === undefined || a.length !== b.length) return false;
+  for (let index = 0; index < a.length; index += 1) {
+    const x = a[index] as Hop;
+    const y = b[index] as Hop;
+    if (x.by !== y.by || !docEquals(x.step, y.step) || !sameResult(ok(x.thing), ok(y.thing), equal)) return false;
+  }
+  return true;
+}
+
+/**
+ * This function gives the error of a name that holds a held error and stops a longer path, or `undefined`. A
+ * reference of the formula kit tests the binding of its first name before it resolves the rest of the path
+ * (FORMULA.LET). The resolution of the whole path does not show that test.
+ */
+function heldStop(root: Context, path: readonly unknown[]): Result | undefined {
+  const name = path[1];
+  if (path.length <= 2 || path[0] !== "names" || typeof name !== "string" || !Object.hasOwn(root.names, name)) return undefined;
+  const bound = root.names[name];
+  return bound instanceof Held ? { ok: false, error: bound.error } : undefined;
+}
+
+/**
+ * This function tells if an old result stays valid in a new context (READS.VERIFY, D26). It resolves the path of
+ * each free read again, in the order of the list, and it compares what the path reaches with `sameResult`. It stops at
+ * the first read that reaches another thing, and it gives that read (READS.CHANGED).
+ *
+ * - A read that is not free reads a binding that a kind made from earlier reads, for example a name of `let`. The
+ *   function does not resolve it again.
+ * - A thing compares as in `sameResult`. Thus a host thing or a date is the same only as itself. A host gives a new
+ *   object for a new state, or the option `equal`.
+ * - A longer path through a name that holds a `Held` in the new context is a changed read. A reference of the formula
+ *   kit gives the error of that binding, and the resolution of the path does not show it.
+ * - The answer is sound only for a pure document (FACTS.PURE). A document with an effect, a volatile operation or an
+ *   extension of a profile can read outside `resolve`. The schedule asks `factsOf` first.
+ *
+ * The values of the context must not change in place, as PLAN.CACHE says for the documents. A value that changed in
+ * place is the same object, thus the function cannot see the change.
+ *
+ * @param target - The machine of the evaluation, or its plan.
+ * @param reads - The reads of the evaluation, from the option `reads`.
+ * @param context - The new context.
+ * @param options - The rule of the host for two things.
+ * @returns `{ same: true }` when each free read reaches the same thing, or else the first changed read.
+ */
+export function verifyReads(target: Machine | Plan, reads: readonly Read[], context: Context, options: VerifyOptions = {}): ReadsCheck {
+  const machine = "evaluators" in target ? target : target.machine;
+  const root = rootContext(machine, context);
+  const equal = options.equal;
+  for (let index = 0; index < reads.length; index += 1) {
+    const read = reads[index] as Read;
+    if (!read.free) continue;
+    const stop = heldStop(root, read.path);
+    if (stop !== undefined) return { same: false, index, read, now: stop };
+    const asked = read.hops !== undefined;
+    const now = readAgain(machine, root, read.path, asked);
+    if (!sameResult(read.reached, now.reached, equal) || (read.hops !== undefined && !sameHops(read.hops, now.hops, equal))) {
+      return { same: false, index, read, now: now.reached };
+    }
+  }
+  return SAME;
+}

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,8 @@ import {
   intersectCaps,
   makeContext,
   permits,
+  placeText,
+  waitedReason,
 } from "./evaluate.ts";
 import { type FormulaProfile, type OpFn, Held, STD_EXT } from "./formula.ts";
 
@@ -45,6 +48,23 @@ 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 verb that goes up the ladder at each document, as in `prepare`. The default is `eval`. The reference reads
+   * each verb by the same rules (VERB.AGREE).
+   */
+  readonly verb?: string;
+}
+
+/** 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 +73,11 @@ interface Env {
   readonly definitions: Definitions;
   readonly effects: Effect[];
   readonly maxDepth: number;
+  readonly perform: Perform | undefined;
+  /** The verb that goes up the ladder at each document. Each part evaluates with the same verb. */
+  readonly verb: string;
+  /** 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. */
@@ -104,8 +129,8 @@ function choose(env: Env, name: string): Chosen | undefined {
 
 /**
  * This function reads one document by the rules, in their order. First come an envelope or a declared type
- * (EVAL.ERRORS) and the limit of the depth (PLAN.DEPTH). Then come the ladder (LADDER.*), an evaluator and the shape
- * of the parts (SHAPE.*).
+ * (EVAL.ERRORS) and the limit of the depth (PLAN.DEPTH). Then come the ladder of the verb (LADDER.*, VERB.LADDER), an
+ * evaluator and the shape of the parts (SHAPE.*).
  */
 function examine(env: Env, at: At): Seen | Failed {
   const { place, declared } = at;
@@ -116,7 +141,7 @@ function examine(env: Env, at: At): Seen | Failed {
   if (at.depth > env.maxDepth) return fail("#DEPTH!", `The nesting is deeper than ${env.maxDepth} documents.`, { place });
   const { doc, kind, split } = read;
   const kindText = typeName(doc.type);
-  const answer = ask(world, read.declared ? {} : doc, "eval", declared === undefined ? {} : { declaredType: declared });
+  const answer = ask(world, read.declared ? {} : doc, env.verb, declared === undefined ? {} : { declaredType: declared });
   if (answer.error === "unknown-kind") return fail("#KIND?", `The world has no kind ${kindText}.`, { place });
   const name = answer.evaluator;
   const chosen = name === undefined ? undefined : choose(env, name);
@@ -167,15 +192,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). */
@@ -189,7 +251,7 @@ function evaluateSeen(env: Env, seen: Seen, at: At): Result {
   const { chosen } = seen;
   const { place } = at;
   if ("gap" in chosen) return fail("#NOEVAL", chosen.gap, { place });
-  if ("runner" in chosen) return drive(runSeen(env, seen, at, chosen.runner), place);
+  if ("runner" in chosen) return drive(runSeen(env, seen, at, chosen.runner), place, seen.kindText);
   const input = evalInput(env, seen, at);
   try {
     return placed(chosen.evaluator(input), place);
@@ -215,11 +277,11 @@ function* runSeen(env: Env, seen: Seen, at: At, runner: RunFn): Steps {
 }
 
 /** This function drives steps that cannot wait. A step that waits gives `#CALC!` at the document (RUN.WAIT). */
-function drive(steps: Steps, place: readonly Key[]): Result {
+function drive(steps: Steps, place: readonly Key[], kindText: string): Result {
   const step = steps.next();
   if (step.done === true) return step.value;
   void step.value.catch(() => undefined);
-  const waited = fail("#CALC!", "A part waited, and its parent cannot wait.", { place });
+  const waited = fail("#CALC!", waitedReason(kindText), { place });
   steps.return(waited);
   return waited;
 }
@@ -247,7 +309,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 +337,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 +349,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 +371,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 +396,27 @@ 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!`.
+ *
+ * The verb of the options goes up the ladder at each document, as in `prepare`. Each verb has the same rules: the
+ * ladder, the contract of the kind and the sealed parts (VERB.AGREE).
  *
  * @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, a mock and the verb.
  * @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,
+    verb: options.verb ?? "eval",
+    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 +543,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[]);
+}