@mark1russell7/coeval 0.13.0 → 0.15.0

package/build/index.js

@@ -2905,6 +2905,12 @@ function partCaps(rules, path, caps) {
 */
 const GRANT = /* @__PURE__ */ Symbol("coeval.grant");
 /**
+* The key of the epoch of a grant (CAP.NARROW-KEPT). The epoch is the list of capabilities that the host gave the root
+* of the evaluation of the grant. A spread of a context keeps its epoch, as it keeps its grant. An
+* effect and a resolution read a context of another epoch as a context without a grant.
+*/
+const EPOCH = /* @__PURE__ */ Symbol("coeval.epoch");
+/**
 * This function gives the capabilities that a context and its grant both permit, the meet `intersectCaps` (CAP.MEET).
 * A context whose grant is its own list gives that list after one comparison. A context without a grant gives none.
 */
@@ -2928,12 +2934,27 @@ function granted(ctx) {
 	};
 }
 /**
+* This function gives a context of another epoch the epoch of the evaluation, without capabilities (CAP.NARROW-KEPT).
+* Thus the context reads as a context without a grant. The kernel cannot know the document of the context in this
+* evaluation.
+*/
+function ungranted(ctx, epoch) {
+	return {
+		...ctx,
+		caps: NO_CAPS$2,
+		[GRANT]: NO_CAPS$2,
+		[EPOCH]: epoch
+	};
+}
+/**
 * This function gives the context in which the runtime resolves a path of compiled code (CAP.CAPS-GRANT, CAP.MEET).
 * The context has the meet of its list and its grant, and a context without a grant has none. Thus a read of the root
 * `caps` and a walker of a step document get the capabilities of the document from a widened context.
 * A context that the code narrowed keeps its own list. A context whose list does not change stays the same object.
+* A context of another epoch has no capabilities (CAP.NARROW-KEPT).
 */
-function readable(ctx) {
+function readable(ctx, epoch) {
+	if (ctx[EPOCH] !== epoch) return ctx.caps.length === 0 ? ctx : ungranted(ctx, epoch);
 	const caps = grantedCaps(ctx);
 	if (caps === ctx.caps || caps.length === 0 && ctx.caps.length === 0) return ctx;
 	return {
@@ -2944,14 +2965,17 @@ function readable(ctx) {
 }
 /**
 * This function gives the context of a part of a function evaluator. It is the context that the evaluator gives,
-* narrowed by the context of the document (CAP.NARROW), with the grant of its capabilities.
+* narrowed by the context of the document (CAP.NARROW), with the grant of its capabilities. The grant has the epoch
+* of the document, because the document permits each of its capabilities (CAP.NARROW-KEPT).
 */
 function handed(parent, next) {
 	const ctx = narrow(parent, next);
-	if (ctx[GRANT] === ctx.caps) return ctx;
+	const epoch = parent[EPOCH];
+	if (ctx[GRANT] === ctx.caps && ctx[EPOCH] === epoch) return ctx;
 	return {
 		...ctx,
-		[GRANT]: ctx.caps
+		[GRANT]: ctx.caps,
+		[EPOCH]: epoch
 	};
 }
 /** The text that names a resolution in the error of an exception of the host. */
@@ -3058,6 +3082,28 @@ const NO_ANSWER = {
 /** The options of a resolution without a record of hops, and with one. One object of each serves each call. */
 const WITHOUT_HOPS = /* @__PURE__ */ Object.freeze({ hops: false });
 const WITH_HOPS = /* @__PURE__ */ Object.freeze({ hops: true });
+/**
+* This function gives the path of a kept read (READS.CLOSURE). The evaluation did not ask for the read. Thus the read
+* does not step into a host thing, and the path ends at the first host thing. The host gives a new thing for a new state.
+* A reference in the data reads the context of its reader, thus the function then gives `undefined`.
+*
+* @param nav - The world and the code of the evaluators.
+* @param root - The context at the root of the evaluation.
+* @param path - The root and the keys of the static read.
+* @returns The path of the kept read, or `undefined` for a reference on the way.
+*/
+function keptPath(nav, root, path) {
+	const adopt = nav.adopt ?? ((value) => value);
+	let here = adopt(root[path[0]]);
+	for (let index = 1;; index += 1) {
+		if (isHostThing(here)) return index === path.length ? path : path.slice(0, index);
+		if (nav.plain !== true && isRef(here)) return void 0;
+		if (index >= path.length) return path;
+		const reached = derefStep(nav, here, path[index]);
+		if (reached === void 0) return path;
+		here = adopt(reached.thing);
+	}
+}
 /** This function makes the record of the reads of an evaluation, when the host gives a list. */
 function readingOf(list, root) {
 	return list === void 0 ? void 0 : {
@@ -3070,6 +3116,7 @@ function readingOf(list, root) {
 /** This class holds the state of one evaluation or run: the machine, the effects, the clock and the trace. */
 var Session = class {
 	machine;
+	epoch;
 	running;
 	traced;
 	perform;
@@ -3086,8 +3133,9 @@ var Session = class {
 	* root scope is made at the first effect or `all`, thus an evaluation without effects makes no scope.
 	*/
 	scope;
-	constructor(machine, running, traced, perform, signal, effects, reading = void 0) {
+	constructor(machine, epoch, running, traced, perform, signal, effects, reading = void 0) {
 		this.machine = machine;
+		this.epoch = epoch;
 		this.running = running;
 		this.traced = traced;
 		this.perform = perform;
@@ -3110,7 +3158,7 @@ var Session = class {
 	* `caps` and a walker of a step document get the capabilities of the document.
 	*/
 	resolve(ctx, path, options) {
-		return this.read(readable(ctx), path, void 0, options);
+		return this.read(readable(ctx, this.epoch), path, void 0, options);
 	}
 	/**
 	* This function resolves a compiled path (PLAN.PATH). Without a list of reads and without a trace, the compiled
@@ -3118,7 +3166,7 @@ var Session = class {
 	* that the grant permits (CAP.CAPS-GRANT, CAP.MEET).
 	*/
 	resolvePath(given, compiled) {
-		const ctx = readable(given);
+		const ctx = readable(given, this.epoch);
 		if (this.reading === void 0 && !this.traced && compiled.nav === this.machine) return compiled.resolve(ctx);
 		return this.read(ctx, compiled.path, compiled, void 0);
 	}
@@ -3162,13 +3210,45 @@ var Session = class {
 		if (compiled !== void 0 && !hops && compiled.nav === this.machine) return compiled.resolve(ctx);
 		return resolve(this.machine, ctx, path, hops ? WITH_HOPS : WITHOUT_HOPS);
 	}
-	keepsContext() {
+	keepsContext(ctx, reads) {
 		const reading = this.reading;
 		if (reading === void 0 || reading.kept) return;
+		const known = ctx === void 0 ? void 0 : reads?.();
+		if (ctx !== void 0 && known !== void 0 && known.every((read) => this.keepRead(reading, ctx, read))) return;
 		reading.kept = true;
 		this.keep(reading, reading.self ? ROOTS.filter((root) => root !== "self") : ROOTS);
 	}
 	/**
+	* This function adds the kept read of one static read of a closure (READS.CLOSURE). The read resolves from the
+	* context at the root, one time in an evaluation. A name that a kind binds in the kept context gives no read,
+	* because the reads of its binding are already in the list.
+	*
+	* @returns `false` when the path meets a reference in the data. Then the closure keeps each whole root.
+	*/
+	keepRead(reading, ctx, read) {
+		const root = read.root;
+		const exact = [root, ...read.keys];
+		if (!isFree(reading.root, ctx, exact)) {
+			if (root === "self" && !reading.self) this.keep(reading, ["self"]);
+			return true;
+		}
+		if (root === "self" && reading.self) return true;
+		const path = keptPath(this.machine, reading.root, read.exact ? exact : [root]);
+		if (path === void 0) return false;
+		const paths = reading.paths ??= /* @__PURE__ */ new Set();
+		const text = JSON.stringify(path);
+		if (paths.has(text) || paths.has(JSON.stringify([root]))) return true;
+		paths.add(text);
+		if (path.length === 1 && root === "self") reading.self = true;
+		reading.list.push({
+			path,
+			reached: readAgain(this.machine, reading.root, path, false).reached,
+			free: true,
+			kept: true
+		});
+		return true;
+	}
+	/**
 	* This function adds a read of each whole root to the list, from the context at the root (READS.KEPT). An exception
 	* of the host gives the error value of the read, because the evaluation did not ask for the read.
 	*/
@@ -3190,10 +3270,11 @@ var Session = class {
 	/**
 	* This function checks the capability of an effect, and records the effect with its address (RUN.ADDRESS). The
 	* context keeps only the capabilities of its grant, thus compiled code cannot widen the context of its own effect
-	* (CAP.NARROW-CODE).
+	* (CAP.NARROW-CODE). A context of another epoch has no capabilities, thus code cannot keep a context for a later
+	* evaluation with fewer capabilities (CAP.NARROW-KEPT).
 	*/
 	record(given, kind, payload, place) {
-		const ctx = granted(given);
+		const ctx = given[EPOCH] === this.epoch ? granted(given) : ungranted(given, this.epoch);
 		const keys = typeof kind === "string" ? kind.split(".") : kind;
 		const text = keys.join(".");
 		if (!this.permitted(ctx, keys)) return fail("#CAP!", `The context has no capability for the effect ${text}.`, { place });
@@ -4027,18 +4108,20 @@ function interpretRun(fn, input, fill) {
 /**
 * This function gives the context at the root of an evaluation. It is the context of the host, with the world of
 * the machine when the context has none. The host gives the capabilities, thus the root has the grant of each one
-* (CAP.NARROW-CODE). An evaluation and `verifyReads` share it.
+* (CAP.NARROW-CODE). The list of the host is also the epoch of the grant (CAP.NARROW-KEPT). An evaluation and
+* `verifyReads` share it.
 *
 * @param machine - The machine.
 * @param ctx - The context of the host.
 * @returns The context at the root.
 */
 function rootContext(machine, ctx) {
-	if (ctx.world !== null && ctx[GRANT] === ctx.caps) return ctx;
+	if (ctx.world !== null && ctx[GRANT] === ctx.caps && ctx[EPOCH] === ctx.caps) return ctx;
 	return {
 		...ctx,
 		world: ctx.world === null ? worldThing(machine.world) : ctx.world,
-		[GRANT]: ctx.caps
+		[GRANT]: ctx.caps,
+		[EPOCH]: ctx.caps
 	};
 }
 /**
@@ -4109,13 +4192,13 @@ var CompiledPlan = class {
 	evaluate(context = makeContext(), evalOptions) {
 		const machine = this.machine;
 		const ctx = rootContext(machine, context);
-		const s = new Session(machine, false, this.traced, evalOptions?.perform, void 0, evalOptions?.effects, readingOf(evalOptions?.reads, ctx));
+		const s = new Session(machine, ctx.caps, false, this.traced, evalOptions?.perform, void 0, evalOptions?.effects, readingOf(evalOptions?.reads, ctx));
 		return this.code(ctx, s);
 	}
 	run(context = makeContext(), runOptions = {}) {
 		const machine = this.machine;
 		const ctx = rootContext(machine, context);
-		const s = new Session(machine, true, this.traced, runOptions.perform, runOptions.signal, void 0, readingOf(runOptions.reads, ctx));
+		const s = new Session(machine, ctx.caps, true, this.traced, runOptions.perform, runOptions.signal, void 0, readingOf(runOptions.reads, ctx));
 		return driveWaiting(this.runCode()(ctx, s), runOptions.signal);
 	}
 };
@@ -4184,7 +4267,7 @@ function evaluate(machine, doc, context = makeContext(), options) {
 		...given.verb === void 0 ? {} : { verb: given.verb }
 	});
 	const ctx = rootContext(machine, context);
-	const s = new Session(machine, false, true, given.perform, void 0, void 0, readingOf(given.reads, ctx));
+	const s = new Session(machine, ctx.caps, false, true, given.perform, void 0, void 0, readingOf(given.reads, ctx));
 	return record(s, plan.code(ctx, s));
 }
 /**
@@ -4205,7 +4288,7 @@ async function run(machine, doc, context = makeContext(), options = {}) {
 		...options.verb === void 0 ? {} : { verb: options.verb }
 	});
 	const ctx = rootContext(machine, context);
-	const s = new Session(machine, true, true, options.perform, options.signal, void 0, readingOf(options.reads, ctx));
+	const s = new Session(machine, ctx.caps, true, true, options.perform, options.signal, void 0, readingOf(options.reads, ctx));
 	return record(s, await driveWaiting(plan.runCode()(ctx, s), options.signal));
 }
 /**
@@ -7510,7 +7593,7 @@ function formulaCode(profile) {
 				}, rt);
 			};
 		}),
-		"formula.fn": compiled(({ value, data }) => {
+		"formula.fn": compiled(({ value, data, doc, machine }) => {
 			const params = isRecord(data) ? data["params"] : void 0;
 			if (!Array.isArray(params) || !params.every((param) => typeof param === "string") || new Set(params).size !== params.length) {
 				const bad = fail("#VALUE!", "The params of fn are a list of different texts.");
@@ -7518,8 +7601,19 @@ function formulaCode(profile) {
 			}
 			const names = params;
 			const body = partsOf$1(value)["body"];
+			let known = null;
+			const reads = () => {
+				if (known !== null) return known;
+				try {
+					const facts = factsOf(machine, doc);
+					known = facts.pure ? facts.reads : void 0;
+				} catch {
+					known = void 0;
+				}
+				return known;
+			};
 			return (ctx, rt) => {
-				rt.keepsContext?.();
+				rt.keepsContext?.(ctx, reads);
 				const closure = (...args) => {
 					const scope = { ...ctx.names };
 					names.forEach((name, index) => setOwn$1(scope, name, args[index]));
@@ -8733,6 +8827,42 @@ function resolveFully(machine, ctx, path, options) {
 * mock, the effect gives its payload (RUN.EVAL).
 */
 function cause(env, ctx, kind, payload, place) {
+	const effect = recordEffect(env, ctx, kind, payload, place);
+	if ("ok" in effect) return effect;
+	effect.outcome = answer(env.perform, effect, place);
+	return effect.outcome;
+}
+/**
+* This function causes the effect of an evaluator. In a run, the host does each effect, thus only a runner can cause
+* one. The effect then gives `#CALC!` before the test of its capability (RUN.NEEDS-RUNNER).
+*/
+function causeFromEvaluator(env, ctx, kind, payload, place) {
+	const text = typeof kind === "string" ? kind : kind.join(".");
+	if (env.running) return fail("#CALC!", `The effect ${text} needs a runner: in a run, the host does each effect.`, { place });
+	return cause(env, ctx, kind, payload, place);
+}
+/**
+* This function causes the effect of a runner. In an evaluation, the mock answers it at once. In a run, the host does
+* it, and a promise from the host makes the steps wait (RUN.SEQ). An effect whose wait a stop ends keeps no outcome
+* (RUN.OUTCOME).
+*/
+function* causeAndWait(env, ctx, kind, payload, place) {
+	if (!env.running) return cause(env, ctx, kind, payload, place);
+	const effect = recordEffect(env, ctx, kind, payload, place);
+	if ("ok" in effect) return effect;
+	const perform = env.perform;
+	if (perform === void 0) return effect.outcome = ok(payload);
+	let given;
+	try {
+		given = perform(effect);
+	} catch (error) {
+		return effect.outcome = hostError(effect, place, error);
+	}
+	if (!(given instanceof Promise)) return effect.outcome = ok(given);
+	return effect.outcome = yield given.then((value) => ok(value), (error) => hostError(effect, place, error));
+}
+/** This function checks the capability of an effect, and records the effect with its address (RUN.CAP, RUN.ADDRESS). */
+function recordEffect(env, ctx, kind, payload, place) {
 	const keys = typeof kind === "string" ? kind.split(".") : kind;
 	const text = keys.join(".");
 	const machine = env.machine;
@@ -8752,8 +8882,18 @@ function cause(env, ctx, kind, payload, place) {
 		address: `${env.scope.prefix}${at}#${count}`
 	};
 	env.effects.push(effect);
-	effect.outcome = answer(env.perform, effect, place);
-	return effect.outcome;
+	return effect;
+}
+/** This function gives the outcome of an effect that the host failed. A `Failure` gives its own error value (RUN.CAUSE). */
+function hostError(effect, place, 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
+	});
 }
 /**
 * This function gives the answer of the mock to an effect. A throw gives `#CALC!` with the cause, and a `Failure`
@@ -8765,14 +8905,7 @@ function answer(perform, effect, place) {
 	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
-		});
+		return hostError(effect, place, error);
 	}
 	if (!(given instanceof Promise)) return ok(given);
 	given.catch(() => void 0);
@@ -8843,7 +8976,7 @@ function evalInput(env, seen, at) {
 		machine: env.machine,
 		...at.address ? { address: true } : {},
 		resolve: (path, options) => resolveFully(env.machine, at.ctx, path, options),
-		effect: (kind, payload) => cause(env, at.ctx, kind, payload, at.place),
+		effect: (kind, payload) => causeFromEvaluator(env, at.ctx, kind, payload, at.place),
 		fill
 	};
 }
@@ -8870,67 +9003,116 @@ function runInput(env, seen, at) {
 		place: at.place,
 		machine: env.machine,
 		resolve: (path, options) => resolveFully(env.machine, at.ctx, path, options),
-		effect: function* (kind, payload) {
-			return cause(env, at.ctx, kind, payload, at.place);
-		},
+		effect: (kind, payload) => causeAndWait(env, at.ctx, kind, payload, at.place),
 		all: (list, options) => together(env, list, options),
 		fill
 	};
 }
 /**
 * This function evaluates parts for `all` (RUN.ALL). The parts start in their order, up to the limit, and each part
-* 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!`.
+* goes on until it ends or waits. A part that waits 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 a part waits, the steps wait for the next part that settles. The journal of the host can choose that part
+* (RUN.REPLAY), and it gets each part that settled (RUN.RECORD). In an evaluation, the drive stops at the first wait
+* and gives `#CALC!`. In a run, the host settles the wait, and the part goes on in its own scope.
 *
 * 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(env, list, options = {}) {
 	const limit = Math.max(1, options.concurrency ?? list.length);
+	const failFast = options.failFast === true;
 	const results = list.map(() => void 0);
+	const scopes = [];
 	const waiting = [];
 	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;
-		env.scope = {
-			prefix: `${address}.${index}/`,
-			counts: /* @__PURE__ */ new Map(),
-			alls: 0
-		};
+	let started = 0;
+	const end = (index, result) => {
+		results[index] = result;
+		if (failFast && !result.ok) failed = true;
+	};
+	/** This function gives a part its input in its own scope, and keeps it in the list when it waits again. */
+	const goOn = (index, steps, input) => {
+		const around = env.scope;
+		env.scope = scopes[index];
+		let step;
 		try {
-			const steps = list[index].evaluate();
-			const step = steps.next();
-			if (step.done === true) result = step.value;
-			else waiting.push({
-				steps,
-				promise: step.value
-			});
+			step = input.threw ? steps.throw(input.error) : steps.next(input.value);
 		} catch (error) {
-			result = thrown(error, "a part");
+			end(index, thrown(error, "a part"));
+			return;
 		} finally {
-			env.scope = outer;
+			env.scope = around;
 		}
-		results[index] = result;
-		if (result !== void 0 && options.failFast === true && !result.ok) failed = true;
-	}
-	if (failed) {
-		const stopped = fail("#ABORT", "The part stopped: a part before it failed, and the parts run with failFast.");
-		for (const item of waiting) try {
-			item.steps.return(stopped);
-		} catch {}
-		return results.map((result) => result ?? stopped);
+		if (step.done === true) {
+			end(index, step.value);
+			return;
+		}
+		const waiter = {
+			index,
+			steps,
+			next: Promise.resolve()
+		};
+		waiter.next = step.value.then((value) => ({
+			waiter,
+			value,
+			threw: false
+		}), (error) => ({
+			waiter,
+			error,
+			threw: true
+		}));
+		waiting.push(waiter);
+	};
+	/** This function starts the next parts in their order, while the limit permits it and no part failed. */
+	const startMore = () => {
+		while (!failed && waiting.length < limit && started < list.length) {
+			const index = started;
+			started += 1;
+			scopes[index] = {
+				prefix: `${address}.${index}/`,
+				counts: /* @__PURE__ */ new Map(),
+				alls: 0
+			};
+			const around = env.scope;
+			env.scope = scopes[index];
+			let steps;
+			try {
+				steps = list[index].evaluate();
+			} catch (error) {
+				end(index, thrown(error, "a part"));
+				continue;
+			} finally {
+				env.scope = around;
+			}
+			goOn(index, steps, { threw: false });
+		}
+	};
+	startMore();
+	while (waiting.length > 0 && !failed) {
+		const chosen = env.journal?.next?.(address, waiting.map((waiter) => waiter.index));
+		const pick = chosen === void 0 ? void 0 : waiting.find((waiter) => waiter.index === chosen);
+		const resumed = yield pick === void 0 ? Promise.race(waiting.map((waiter) => waiter.next)) : pick.next;
+		env.journal?.settled?.(address, resumed.waiter.index);
+		waiting.splice(waiting.indexOf(resumed.waiter), 1);
+		goOn(resumed.waiter.index, resumed.waiter.steps, resumed);
+		startMore();
 	}
-	if (waiting.length > 0) yield Promise.race(waiting.map((item) => item.promise));
-	return results;
+	if (!failed) return results;
+	const stopped = fail("#ABORT", "The part stopped: a part before it failed, and the parts run with failFast.");
+	for (const waiter of waiting) try {
+		waiter.steps.return(stopped);
+	} catch {}
+	return results.map((result) => result ?? stopped);
 }
 /**
 * 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 the answer of the mock or its payload, and a part that waits gives `#CALC!`.
+* a traced plan and the second tier of a language must give its results. In an evaluation, an effect gives the answer
+* of the mock or its payload, and a part that waits gives `#CALC!`. `referenceRun` reads the rules of a run.
 *
 * 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).
@@ -8942,12 +9124,43 @@ function* together(env, list, options = {}) {
 * @returns The result.
 */
 function reference(machine, doc, context = makeContext(), options = {}) {
-	const env = {
+	const env = envOf(machine, options, false);
+	try {
+		return within(env, () => evaluateAt(env, rootAt(machine, doc, context, options)));
+	} catch (error) {
+		return placed(thrown(error, "the reference"), []);
+	}
+}
+/**
+* This function starts a run of a document by the rules, without a compilation (REF.RUN). The host does each effect of a runner,
+* and a step waits when the host waits (RUN.SEQ). `all` settles the waits in the order of the host, or in the order
+* of the journal of a replay (RUN.REPLAY). An effect of an evaluator gives `#CALC!` (RUN.NEEDS-RUNNER). A signal that
+* aborts stops the run with `#ABORT` (RUN.ABORT).
+*
+* The part of the run before the first wait happens at once, in the call (RUN.EAGER). `agreeRun` compares the run of
+* a plan with this run.
+*
+* @param machine - The world, the evaluators and the runners.
+* @param doc - The document.
+* @param context - The names and the capabilities at the root.
+* @param options - The options of `reference`, the host and a signal.
+* @returns The result, when the run ends.
+*/
+function referenceRun(machine, doc, context = makeContext(), options = {}) {
+	const env = envOf(machine, options, true);
+	return driveRun(env, stepsAt(env, rootAt(machine, doc, context, options)), options.signal).catch((error) => placed(thrown(error, "the reference"), []));
+}
+/** This function makes the state of the reference for one evaluation or one run. */
+function envOf(machine, options, running) {
+	const perform = options.perform;
+	return {
 		machine,
 		definitions: options.definitions ?? {},
 		effects: options.effects ?? [],
 		maxDepth: machine.maxDepth ?? 1e3,
-		perform: options.perform,
+		perform,
+		journal: perform === void 0 ? void 0 : perform[JOURNAL],
+		running,
 		verb: options.verb ?? "eval",
 		scope: {
 			prefix: "",
@@ -8955,26 +9168,66 @@ function reference(machine, doc, context = makeContext(), options = {}) {
 			alls: 0
 		}
 	};
+}
+/** This function gives the root position of a document. A context without a world gets the world of the machine. */
+function rootAt(machine, doc, context, options) {
 	const ctx = context.world === null ? {
 		...context,
 		world: worldThing(machine.world)
 	} : context;
+	return {
+		value: doc,
+		place: [],
+		declared: options.declaredType,
+		depth: 0,
+		address: false,
+		ctx
+	};
+}
+/**
+* This function does one synchronous step of an evaluation or a run. A node of a tree reads the definitions of the
+* evaluation for its equations (TREE.LADDER). Thus the state of the evaluation is the innermost one in the step.
+*/
+function within(env, step) {
 	activeEnvs.push(env);
 	try {
-		return evaluateAt(env, {
-			value: doc,
-			place: [],
-			declared: options.declaredType,
-			depth: 0,
-			address: false,
-			ctx
-		});
-	} catch (error) {
-		return placed(thrown(error, "the reference"), []);
+		return step();
 	} finally {
 		activeEnvs.pop();
 	}
 }
+/** The mark of a signal that aborted. */
+const STOPPED$1 = /* @__PURE__ */ Symbol("stopped");
+/**
+* This function drives the steps of a run. Each step waits for its promise. A rejection goes into the steps as an
+* exception. A signal that aborts stops the steps with `#ABORT`, also before the first step (RUN.ABORT).
+*/
+async function driveRun(env, steps, signal) {
+	const stop = () => {
+		const aborted = fail("#ABORT", `The host stopped the run: ${describe(signal?.reason ?? "no reason")}`, { cause: signal?.reason });
+		try {
+			within(env, () => steps.return(aborted));
+		} catch {}
+		return aborted;
+	};
+	if (signal?.aborted === true) return stop();
+	const stopping = signal === void 0 ? void 0 : new Promise((resolve) => {
+		signal.addEventListener("abort", () => resolve(STOPPED$1), { once: true });
+	});
+	let step = within(env, () => steps.next());
+	while (step.done !== true) {
+		let input;
+		try {
+			input = await (stopping === void 0 ? step.value : Promise.race([step.value, stopping]));
+		} catch (error) {
+			step = within(env, () => steps.throw(error));
+			continue;
+		}
+		if (input === STOPPED$1) return stop();
+		step = within(env, () => steps.next(input));
+	}
+	return step.value;
+}
 /** The evaluations of the reference that run at this time, the innermost last. */
 const activeEnvs = [];
 const refNodes = /* @__PURE__ */ new WeakMap();
@@ -9408,6 +9661,101 @@ function valuesOfStrict(parts) {
 	return { values };
 }
 //#endregion
+//#region src/replay.ts
+/**
+* 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.
+*/
+function recorder(perform) {
+	const seen = [];
+	const settles = [];
+	const journal = { settled: (all, item) => {
+		settles.push({
+			all,
+			item
+		});
+	} };
+	const host = (effect) => {
+		const entry = {
+			effect,
+			waited: false
+		};
+		seen.push(entry);
+		const answer = perform === void 0 ? 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 === void 0 ? {} : { 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.
+*/
+function replayer(log, options = {}) {
+	const wait = options.wait !== false;
+	const entries = /* @__PURE__ */ new Map();
+	for (const entry of log.effects) entries.set(entry.address, entry);
+	const order = /* @__PURE__ */ new Map();
+	for (const settle of log.settles) {
+		const items = order.get(settle.all);
+		if (items === void 0) order.set(settle.all, [settle.item]);
+		else items.push(settle.item);
+	}
+	const journal = { next: (all, waiting) => {
+		const items = order.get(all);
+		const item = items?.[0];
+		if (items === void 0 || item === void 0 || !waiting.includes(item)) return void 0;
+		items.shift();
+		return item;
+	} };
+	const perform = (effect) => {
+		const entry = effect.address === void 0 ? void 0 : entries.get(effect.address);
+		const wrong = mismatch(effect, entry);
+		if (wrong !== void 0 || entry === void 0) throw wrong;
+		const outcome = entry.outcome;
+		const failure = outcome === void 0 ? replayError(effect, `The log has no outcome for the effect ${effect.kind} at ${effect.address ?? ""}: the recorded run stopped before the answer.`) : outcome.ok ? void 0 : new Failure(outcome.error);
+		const value = outcome?.ok === true ? outcome.value : void 0;
+		if (wait && entry.waited) return failure === void 0 ? Promise.resolve(value) : Promise.reject(failure);
+		if (failure !== void 0) 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, entry) {
+	const at = effect.address ?? "";
+	if (entry === void 0) 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.`);
+}
+/** This function gives the exception that carries `#REPLAY!` to the kernel, with the place of the effect. */
+function replayError(effect, reason) {
+	return new Failure(fail("#REPLAY!", reason, { place: effect.place }).error);
+}
+//#endregion
 //#region src/agree.ts
 /** The tiers that `agree` compares when its options name none. */
 const DEFAULT_TIERS = /* @__PURE__ */ Object.freeze([
@@ -9595,6 +9943,113 @@ function agree(machine, doc, context = makeContext(), options = {}) {
 		effects
 	};
 }
+/**
+* This function wraps the function `perform` of a run. The wrapper keeps each effect and each wait of `all` that
+* settles. It gives each effect to the inner function, and each call of its journal to the inner journal.
+*/
+function watched(perform) {
+	const effects = [];
+	const settles = [];
+	const inner = perform[JOURNAL];
+	const settled = (all, item) => {
+		settles.push({
+			all,
+			item
+		});
+		inner?.settled?.(all, item);
+	};
+	const journal = inner?.next === void 0 ? { settled } : {
+		settled,
+		next: (all, waiting) => inner.next?.(all, waiting)
+	};
+	const host = (effect) => {
+		effects.push(effect);
+		return perform(effect);
+	};
+	return {
+		perform: Object.assign(host, { [JOURNAL]: journal }),
+		effects,
+		settles
+	};
+}
+function settleText(settle) {
+	return settle === void 0 ? "no item" : `the item ${settle.item} of ${settle.all}`;
+}
+/** This function gives the first difference of two orders of the waits of `all`, or `undefined` when they agree. */
+function settlesDiffer(a, b) {
+	for (let index = 0; index < Math.max(a.length, b.length); index += 1) {
+		const x = a[index];
+		const y = b[index];
+		if (x?.all !== y?.all || x?.item !== y?.item) return `The wait ${index} settles ${settleText(x)} in the plan, and ${settleText(y)} in the tier.`;
+	}
+}
+/**
+* This function compares the run of a document in a plan with its run in other tiers (RUN.AGREES). First the plan
+* starts the run with a recorder around the host. Then each tier replays the log of that run. These tiers are the
+* reference run, the traced run, a second run of the plan and the plan with the other choice of folds.
+*
+* The rules of `agree` compare the results and the effects, with their addresses and outcomes. A tier must also
+* settle the waits of each `all` in the order of the plan, thus a replay keeps the order of the waits.
+*
+* @param machine - The world, the evaluators and the runners.
+* @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 host.
+* @returns The result of the plan, or the first tier that disagrees and the reason.
+*/
+async function agreeRun(machine, doc, context = makeContext(), options = {}) {
+	const declared = {
+		...options.declaredType === void 0 ? {} : { declaredType: options.declaredType },
+		...options.verb === void 0 ? {} : { verb: options.verb }
+	};
+	const observe = options.observe;
+	observe?.();
+	const folds = observe === void 0;
+	const plan = prepare(machine, doc, {
+		...declared,
+		fold: folds
+	});
+	const recording = recorder(options.perform);
+	const first = watched(recording.perform);
+	const result = await plan.run(context, { perform: first.perform });
+	const saw = observe?.();
+	const log = recording.log();
+	for (const tier of options.tiers ?? DEFAULT_TIERS) {
+		const replay = watched(replayer(log));
+		const host = { perform: replay.perform };
+		let other;
+		if (tier === "reference") other = await referenceRun(machine, doc, context, {
+			...declared,
+			...host,
+			...options.definitions === void 0 ? {} : { definitions: options.definitions }
+		});
+		else if (tier === "traced") other = (await run(machine, doc, context, {
+			...declared,
+			...host
+		})).result;
+		else if (tier === "folds") other = await prepare(machine, doc, {
+			...declared,
+			fold: !folds
+		}).run(context, host);
+		else other = await plan.run(context, host);
+		const compareCalls = observe !== void 0 && tier !== "folds";
+		const calls = observe?.();
+		if (overflowed(result) || overflowed(other)) continue;
+		const why = resultDiffers(result, other, options) ?? effectsDiffer(first.effects, replay.effects, options) ?? settlesDiffer(first.settles, replay.settles) ?? (compareCalls && !sameValue(saw, calls, options.equal) ? "The host saw other calls in the tier." : void 0);
+		if (why !== void 0) return {
+			ok: false,
+			tier,
+			plan: result,
+			other,
+			reason: why
+		};
+	}
+	return {
+		ok: true,
+		result,
+		effects: first.effects
+	};
+}
 //#endregion
 //#region src/generate.ts
 /**
@@ -11810,101 +12265,6 @@ function schedule(machine, options = {}) {
 	};
 }
 //#endregion
-//#region src/replay.ts
-/**
-* 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.
-*/
-function recorder(perform) {
-	const seen = [];
-	const settles = [];
-	const journal = { settled: (all, item) => {
-		settles.push({
-			all,
-			item
-		});
-	} };
-	const host = (effect) => {
-		const entry = {
-			effect,
-			waited: false
-		};
-		seen.push(entry);
-		const answer = perform === void 0 ? 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 === void 0 ? {} : { 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.
-*/
-function replayer(log, options = {}) {
-	const wait = options.wait !== false;
-	const entries = /* @__PURE__ */ new Map();
-	for (const entry of log.effects) entries.set(entry.address, entry);
-	const order = /* @__PURE__ */ new Map();
-	for (const settle of log.settles) {
-		const items = order.get(settle.all);
-		if (items === void 0) order.set(settle.all, [settle.item]);
-		else items.push(settle.item);
-	}
-	const journal = { next: (all, waiting) => {
-		const items = order.get(all);
-		const item = items?.[0];
-		if (items === void 0 || item === void 0 || !waiting.includes(item)) return void 0;
-		items.shift();
-		return item;
-	} };
-	const perform = (effect) => {
-		const entry = effect.address === void 0 ? void 0 : entries.get(effect.address);
-		const wrong = mismatch(effect, entry);
-		if (wrong !== void 0 || entry === void 0) throw wrong;
-		const outcome = entry.outcome;
-		const failure = outcome === void 0 ? replayError(effect, `The log has no outcome for the effect ${effect.kind} at ${effect.address ?? ""}: the recorded run stopped before the answer.`) : outcome.ok ? void 0 : new Failure(outcome.error);
-		const value = outcome?.ok === true ? outcome.value : void 0;
-		if (wait && entry.waited) return failure === void 0 ? Promise.resolve(value) : Promise.reject(failure);
-		if (failure !== void 0) 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, entry) {
-	const at = effect.address ?? "";
-	if (entry === void 0) 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.`);
-}
-/** This function gives the exception that carries `#REPLAY!` to the kernel, with the place of the effect. */
-function replayError(effect, reason) {
-	return new Failure(fail("#REPLAY!", reason, { place: effect.place }).error);
-}
-//#endregion
 //#region src/providers.ts
 /** The deepest schema that `typeFromSchema` reads. A deeper schema reads as `unknown`. */
 const MAX_SCHEMA_DEPTH = 256;
@@ -12215,6 +12575,6 @@ function typeFromSamples(values, options = {}) {
 	return samplesAt(values, options.closed === true, 0);
 }
 //#endregion
-export { ATTRIBUTE_RUNGS, CAPS_TYPE, CONSTRUCTS, ENVELOPE_KEYS, Failure, Held, JOURNAL, MergeError, PARTS, PART_INFO, ROOTS, RUNGS, STD_CAPS, STD_DEFINITIONS, STD_DOMAINS, STD_EVALUATORS, STD_EXT, STD_MACHINE, STD_RUNNERS, STD_SYNTAX, STD_WALKERS, STD_WORLD, THING, agree, ask, attributeTrace, capKeys, check, checkLatent, checkSteps, checkWorld, classify, components, conforms, context, cycles, dataEdges, decodeDomain, decodeValue, derefStep, describe, docEquals, durable, edgesOf, effectEdges, effectsOf, effectsOfVerb, encodeValue, entriesAsJson, equationType, evaluate, extendDomain, factsOf, fail, failures, field, fits, flatten, formulaDefinitions, formulaEvaluators, formulaFacts, formulaKinds, formulaKnown, formulaMachine, fromJson, generate, heights, intersectCaps, isAlias, isAllowedOrder, isClosure, isEnvelope, isHostThing, isKey, isKind, isNamespace, isRecord, isRef, isStackOverflow, isTypeRef, join, jsTruthy, kindDocument, kindNamed, kindOf, layers, looksLikeKind, lookupKind, makeContext, mapRefs, member, mergeMachines, mergeWorlds, narrow, nearestWalker, necessary, nodeAt, nodeLayers, ok, parse, partCaps, partsOf, pathMatches, permits, placed, planner, prepare, print, random, recorder, ref, reference, refsOf, replayer, resolve, restrictMachine, restrictWorld, run, sameResult, sameValue, schedule, splitParts, stored, syntaxFormat, tag, thrown, toJson, typeCheck, typeFromSamples, typeFromSchema, typeIssues, typeName, typePath, typeText, typed, typesOf, valueOfThing, verifyReads, walk, worldThing };
+export { ATTRIBUTE_RUNGS, CAPS_TYPE, CONSTRUCTS, ENVELOPE_KEYS, Failure, Held, JOURNAL, MergeError, PARTS, PART_INFO, ROOTS, RUNGS, STD_CAPS, STD_DEFINITIONS, STD_DOMAINS, STD_EVALUATORS, STD_EXT, STD_MACHINE, STD_RUNNERS, STD_SYNTAX, STD_WALKERS, STD_WORLD, THING, agree, agreeRun, ask, attributeTrace, capKeys, check, checkLatent, checkSteps, checkWorld, classify, components, conforms, context, cycles, dataEdges, decodeDomain, decodeValue, derefStep, describe, docEquals, durable, edgesOf, effectEdges, effectsOf, effectsOfVerb, encodeValue, entriesAsJson, equationType, evaluate, extendDomain, factsOf, fail, failures, field, fits, flatten, formulaDefinitions, formulaEvaluators, formulaFacts, formulaKinds, formulaKnown, formulaMachine, fromJson, generate, heights, intersectCaps, isAlias, isAllowedOrder, isClosure, isEnvelope, isHostThing, isKey, isKind, isNamespace, isRecord, isRef, isStackOverflow, isTypeRef, join, jsTruthy, kindDocument, kindNamed, kindOf, layers, looksLikeKind, lookupKind, makeContext, mapRefs, member, mergeMachines, mergeWorlds, narrow, nearestWalker, necessary, nodeAt, nodeLayers, ok, parse, partCaps, partsOf, pathMatches, permits, placed, planner, prepare, print, random, recorder, ref, reference, referenceRun, refsOf, replayer, resolve, restrictMachine, restrictWorld, run, sameResult, sameValue, schedule, splitParts, stored, syntaxFormat, tag, thrown, toJson, typeCheck, typeFromSamples, typeFromSchema, typeIssues, typeName, typePath, typeText, typed, typesOf, valueOfThing, verifyReads, walk, worldThing };
 
 //# sourceMappingURL=index.js.map