@mark1russell7/coeval 0.15.0 → 0.16.0

package/build/index.js

@@ -2379,14 +2379,25 @@ function resolveFully$1(nav, ctx, path, hops, known) {
 				const walker = given === void 0 ? walkerOf(nav, step) : given ?? void 0;
 				if (walker === void 0) return failed("#STEP?", "A step is a key, or a document of a kind with the verb step.");
 				const envelope = step;
-				const result = walker({
+				const deref = (thing, key) => {
+					const reached = derefStep(nav, thing, key);
+					return reached === void 0 ? void 0 : adopt(reached.thing);
+				};
+				const result = walker(hops === void 0 ? {
 					data: envelope.value,
 					here,
 					context: ctx,
-					deref: (thing, key) => {
-						const reached = derefStep(nav, thing, key);
-						return reached === void 0 ? void 0 : adopt(reached.thing);
-					}
+					deref
+				} : {
+					data: envelope.value,
+					here,
+					context: ctx,
+					deref,
+					visit: (key, thing) => hops.push({
+						step: key,
+						thing,
+						by: "step"
+					})
 				});
 				if (!result.ok) return failed(result.code ?? "#N/A", result.reason);
 				here = adopt(result.thing);
@@ -3084,25 +3095,85 @@ 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.
+* does not step into a host thing with `deref`. A host thing with `known` answers a step without new work
+* (SCHED.CLOSURE). Each other host thing ends the path, and a host thing that does not know the step ends it too.
 * 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.
+* @returns The path of the kept read with what it reached after a step of `known`, 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]]);
+	let known = false;
+	const end = (index) => {
+		const kept = index >= path.length ? path : path.slice(0, index);
+		return known ? {
+			path: kept,
+			reached: ok(here)
+		} : { path: kept };
+	};
 	for (let index = 1;; index += 1) {
-		if (isHostThing(here)) return index === path.length ? path : path.slice(0, index);
+		if (isHostThing(here)) {
+			if (index >= path.length || here.known === void 0) return end(index);
+			let step;
+			try {
+				step = here.known(path[index]);
+			} catch (error) {
+				return {
+					path: path.slice(0, index + 1),
+					reached: thrown(error, READ_FAILED)
+				};
+			}
+			if (step === void 0) return end(index);
+			known = true;
+			here = adopt(step.thing);
+			continue;
+		}
 		if (nav.plain !== true && isRef(here)) return void 0;
-		if (index >= path.length) return path;
+		if (index >= path.length) return end(index);
+		const reached = derefStep(nav, here, path[index]);
+		if (reached === void 0) return known ? end(index) : { path };
+		here = adopt(reached.thing);
+	}
+}
+/**
+* This function resolves the path of a kept read again, for `verifyReads` (SCHED.CLOSURE). It walks the path as
+* `keptPath` did. A host thing with `known` answers its step. A path without such a step resolves with `readAgain`.
+*
+* @param nav - The world and the code of the evaluators.
+* @param ctx - The new context.
+* @param path - The path of the kept read.
+* @returns What the path reaches, or `undefined` when a host does not know a step yet. Then the read changed.
+*/
+function keptAgain(nav, ctx, path) {
+	const adopt = nav.adopt ?? ((value) => value);
+	let here = adopt(ctx[path[0]]);
+	let known = false;
+	const other = () => known ? void 0 : readAgain(nav, ctx, path, false).reached;
+	for (let index = 1; index < path.length; index += 1) {
+		if (isHostThing(here)) {
+			if (here.known === void 0) return other();
+			let step;
+			try {
+				step = here.known(path[index]);
+			} catch (error) {
+				return thrown(error, READ_FAILED);
+			}
+			if (step === void 0) return void 0;
+			known = true;
+			here = adopt(step.thing);
+			continue;
+		}
+		if (nav.plain !== true && isRef(here)) return other();
 		const reached = derefStep(nav, here, path[index]);
-		if (reached === void 0) return path;
+		if (reached === void 0) return other();
 		here = adopt(reached.thing);
 	}
+	if (!known) return other();
+	return nav.plain !== true && isRef(here) ? void 0 : ok(here);
 }
 /** This function makes the record of the reads of an evaluation, when the host gives a list. */
 function readingOf(list, root) {
@@ -3233,8 +3304,9 @@ var Session = class {
 			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 walk = keptPath(this.machine, reading.root, read.exact ? exact : [root]);
+		if (walk === void 0) return false;
+		const path = walk.path;
 		const paths = reading.paths ??= /* @__PURE__ */ new Set();
 		const text = JSON.stringify(path);
 		if (paths.has(text) || paths.has(JSON.stringify([root]))) return true;
@@ -3242,7 +3314,7 @@ var Session = class {
 		if (path.length === 1 && root === "self") reading.self = true;
 		reading.list.push({
 			path,
-			reached: readAgain(this.machine, reading.root, path, false).reached,
+			reached: walk.reached ?? readAgain(this.machine, reading.root, path, false).reached,
 			free: true,
 			kept: true
 		});
@@ -3734,7 +3806,10 @@ function compileNode(c, value, place, declared, depth, address = false) {
 	if (frees === void 0 || kind === void 0 || !pureCode(c, envelope, kind, typePath, name, quick)) return done;
 	const free = freeOf(doc, kind, split.parts, frees);
 	if (free === void 0) return done;
-	return free.length === 0 ? folded(c, done) : {
+	if (free.length === 0) return folded(c, done, void 0);
+	const fixed = c.fixed;
+	if (fixed !== void 0 && free.every((each) => Object.hasOwn(fixed, each))) return folded(c, done, free);
+	return {
 		code: done.code,
 		run: done.run,
 		free
@@ -3814,6 +3889,21 @@ var Probe = class {
 		};
 		this.root = root;
 	}
+	/** The context of a part that folds with fixed names: the context of the probe, with the fixed names (PLAN.FIXED). */
+	withFixed;
+	/**
+	* This function gives the context of a part that folds with fixed names. Its root `names` holds only the fixed
+	* names, thus the probe resolves each fixed name and refuses each other name.
+	*
+	* @param fixed - The fixed names and their values.
+	* @returns The context.
+	*/
+	fixedRoot(fixed) {
+		return this.withFixed ??= {
+			...this.root,
+			names: fixed
+		};
+	}
 	resolve(ctx, path) {
 		const name = path[1];
 		if (path[0] === "names" && isKey(name) && Object.hasOwn(ctx.names, String(name))) {
@@ -3872,13 +3962,14 @@ function trap(refuse, copies) {
 * one deeply frozen copy, and the code gives that copy at each evaluation (PLAN.SHARED). A fold that the probe cancels
 * gives the code without free names, thus no parent tries the fold again.
 */
-function folded(c, done) {
+function folded(c, done, fixed) {
 	const probe = c.probe ??= new Probe(c.machine);
 	probe.refused = false;
 	probe.reads = 0;
 	let constant;
 	try {
-		const result = done.code(probe.root, probe);
+		const root = fixed === void 0 ? probe.root : probe.fixedRoot(c.fixed);
+		const result = done.code(root, probe);
 		if (!probe.refused && (result.ok || result.error.code !== "#DEPTH!")) constant = sharedCopy(result);
 	} catch {
 		constant = void 0;
@@ -3888,18 +3979,100 @@ function folded(c, done) {
 		run: done.run
 	};
 	const value = constant;
+	const original = done.code;
+	if (fixed !== void 0) return {
+		code: fixedCode(fixed, c.fixed, value, original),
+		run: void 0,
+		free: fixed
+	};
 	if (probe.reads === 0) return {
 		code: () => value,
 		run: void 0,
 		free: CLOSED
 	};
-	const original = done.code;
 	return {
 		code: (ctx, rt) => rt instanceof Session && !rt.traced && !rt.recording ? value : original(ctx, rt),
 		run: void 0,
 		free: CLOSED
 	};
 }
+/**
+* This function gives the code of a part that folded with fixed names (PLAN.FIXED, D60). The code gives the folded
+* value when the context has the fixed value of each name, by an own-key test and `Object.is`. A fixed value is
+* deeply frozen, thus the same object gives the same result. Each other context, a list of reads and another runtime
+* get the code without the fold. The probe of a parent fold gets the folded value, and it counts a read.
+*/
+function fixedCode(names, fixed, value, original) {
+	if (names.length === 1) {
+		const name = names[0];
+		const want = fixed[name];
+		return (ctx, rt) => {
+			const given = ctx.names;
+			return Object.hasOwn(given, name) && Object.is(given[name], want) && folds(rt) ? value : original(ctx, rt);
+		};
+	}
+	const wants = names.map((name) => fixed[name]);
+	return (ctx, rt) => {
+		const given = ctx.names;
+		for (let index = 0; index < names.length; index += 1) {
+			const name = names[index];
+			if (!Object.hasOwn(given, name) || !Object.is(given[name], wants[index])) return original(ctx, rt);
+		}
+		return folds(rt) ? value : original(ctx, rt);
+	};
+}
+/**
+* This function tells if the code of a part with fixed names can give its folded value in a runtime. The probe of a
+* fold counts the read of the part, as the code without the fold reads the names.
+*/
+function folds(rt) {
+	if (rt instanceof Session) return !rt.recording;
+	if (!(rt instanceof Probe)) return false;
+	rt.reads += 1;
+	return true;
+}
+/**
+* This function gives the fixed names of the options of `prepare` (PLAN.FIXED). A name fixes only when its value is
+* deeply frozen plain data. Then no change in place can make the folded value stale.
+*
+* @returns A record without a prototype, or `undefined` when no name fixes.
+*/
+function fixedNamesOf(given) {
+	if (given === void 0) return void 0;
+	let out;
+	for (const name of Object.keys(given)) {
+		const value = given[name];
+		if (!frozenPlain(value)) continue;
+		out ??= Object.create(null);
+		Object.defineProperty(out, name, {
+			value,
+			enumerable: true
+		});
+	}
+	return out;
+}
+/** This function tells if a value is plain data, as `sharedCopy` reads it, and if each of its objects is frozen. */
+function frozenPlain(value) {
+	const seen = /* @__PURE__ */ new Set();
+	const walk = (here) => {
+		if (typeof here === "function") return false;
+		if (typeof here !== "object" || here === null || SHARED.has(here) || seen.has(here)) return true;
+		if (!Object.isFrozen(here)) return false;
+		seen.add(here);
+		const proto = Object.getPrototypeOf(here);
+		if (Array.isArray(here) ? proto !== Array.prototype : proto !== Object.prototype && proto !== null) return false;
+		for (const key of Reflect.ownKeys(here)) {
+			const field = Object.getOwnPropertyDescriptor(here, key);
+			if (typeof key !== "string" || field === void 0 || !("value" in field) || !walk(field.value)) return false;
+		}
+		return true;
+	};
+	try {
+		return walk(value);
+	} catch {
+		return false;
+	}
+}
 /** The objects that a fold made. Each one is deeply frozen, thus a later fold uses it again and does not copy it. */
 const SHARED = /* @__PURE__ */ new WeakSet();
 /** The mark of a value that is not plain data. */
@@ -3907,7 +4080,11 @@ const NOT_PLAIN = /* @__PURE__ */ Symbol("not plain");
 /**
 * This function gives a deeply frozen copy of plain data, or `undefined` for other values. Plain data is a primitive or
 * an array without holes and extra keys. It is also a record of enumerable data fields with the prototype of an object
-* or no prototype. The copy keeps cycles and shared objects. The objects of the host do not change.
+* or no prototype. The copy keeps cycles and shared objects. The objects of the host do not change. The tier `fixed`
+* of `agree` uses it. The package does not export it.
+*
+* @param value - The value.
+* @returns The frozen copy, or `undefined`.
 */
 function sharedCopy(value) {
 	try {
@@ -4145,13 +4322,16 @@ function prepare(machine, doc, options = {}) {
 		steps: []
 	};
 	const traced = options.trace === true;
+	const fold = !traced && options.fold !== false;
+	const fixed = fold ? fixedNamesOf(options.fixed?.names) : void 0;
 	const c = {
 		machine,
 		traced,
 		maxDepth: machine.maxDepth ?? 1e3,
 		verb,
 		noAnswer,
-		fold: !traced && options.fold !== false
+		fold,
+		fixed
 	};
 	let root;
 	try {
@@ -4930,6 +5110,17 @@ function treeThing(input, build, outer) {
 function attributeTrace(node, attribute) {
 	return stateOf(node)?.trace(attribute);
 }
+/**
+* This function gives the place of a node of the decorated tree: the keys from the root document to the document of
+* the node (HOP.PLACE). A view puts each hop of a resolution on its node with it. The node keeps its place already,
+* thus the function adds no record.
+*
+* @param thing - A thing, for example the thing of a hop.
+* @returns The keys of the place, or `undefined` for a thing that is not a node of the decorated tree.
+*/
+function placeOf(thing) {
+	return stateOf(thing)?.place;
+}
 /** The path of the root `self`. A node of the tree resolves it, thus the list of reads holds the read (C4). */
 const SELF_PATH = /* @__PURE__ */ Object.freeze(["self"]);
 /** The options of the resolution of `self`: the node needs no hops. */
@@ -4958,21 +5149,24 @@ function hostType(node, wanted) {
 /**
 * This function makes a walker `nearest`. The walker follows a key (the default is `parent`) until the node that it
 * reaches has the wanted type. With `self: true`, the node where the walk starts is the first candidate. A node
-* without that key ends the walk with an error.
+* without that key ends the walk with an error. With `eachStep`, a resolution with hops gets a hop for each node on the way.
 *
-* @param options - The test of a type and the most hops.
+* @param options - The test of a type, the most hops and the record of each step.
 * @returns The walker.
 */
 function nearestWalker(options = {}) {
 	const matches = options.matches ?? hostType;
 	const maxHops = options.maxHops ?? 256;
-	return ({ data, here, deref }) => {
+	const eachStep = options.eachStep === true;
+	return ({ data, here, deref, visit }) => {
 		const follow = isRecord(data) && typeof field(data, "follow") === "string" ? String(field(data, "follow")) : "parent";
 		const wanted = isRecord(data) ? field(data, "type") : void 0;
 		const fromSelf = isRecord(data) && field(data, "self") === true;
+		const record = eachStep ? visit : void 0;
 		let at = here;
 		for (let hops = 0; hops < maxHops; hops += 1) {
-			if (hops > 0 || !fromSelf) at = at === void 0 || at === null ? void 0 : deref(at, follow);
+			const stepped = hops > 0 || !fromSelf;
+			if (stepped) at = at === void 0 || at === null ? void 0 : deref(at, follow);
 			if (at === void 0 || at === null) return {
 				ok: false,
 				reason: `No node of the type ${String(wanted)} is on the way.`
@@ -4981,6 +5175,7 @@ function nearestWalker(options = {}) {
 				ok: true,
 				thing: at
 			};
+			if (stepped) record?.(follow, at);
 		}
 		return {
 			ok: false,
@@ -9762,7 +9957,8 @@ const DEFAULT_TIERS = /* @__PURE__ */ Object.freeze([
 	"reference",
 	"traced",
 	"again",
-	"folds"
+	"folds",
+	"fixed"
 ]);
 /**
 * This function tells if two values are the same for `agree`. Lists and plain records compare item by item and field
@@ -9791,6 +9987,7 @@ function sameInTiers(x, y) {
 	if (x instanceof Held || y instanceof Held) return x instanceof Held && y instanceof Held && errorDiffers(x.error, y.error, false) === void 0;
 }
 const CLOSURE = /* @__PURE__ */ Symbol.for("coeval.closure");
+/** This function gives the parameters of a closure of `fn`, or `undefined` for another function. */
 function closureParams(fn) {
 	return fn[CLOSURE]?.params;
 }
@@ -9830,6 +10027,67 @@ function effectsDiffer(a, b, options) {
 	}
 }
 /**
+* This function compares the plan with the tier `fixed` (PLAN.FIXED). The tier declares each name of plain data fixed,
+* with a frozen copy of its value. It evaluates with these copies, thus the folds with fixed names give the result.
+* Then it evaluates with the context of `agree`, thus the code without the fold gives the result. A fold moves the
+* calls of the host to the compilation, thus only the result and the effects compare.
+*/
+function fixedDiffers(machine, doc, context, result, effects, given, options) {
+	const { perform, ...declared } = given;
+	const held = fixedContext(context);
+	const plan = prepare(machine, doc, {
+		...declared,
+		fixed: { names: held.fixed }
+	});
+	for (const each of [held.context, context]) {
+		const tierEffects = [];
+		const other = plan.evaluate(each, {
+			effects: tierEffects,
+			...perform === void 0 ? {} : { perform }
+		});
+		options.observe?.();
+		if (overflowed(result) || overflowed(other)) continue;
+		const reason = resultDiffers(result, other, options) ?? effectsDiffer(effects, tierEffects, options);
+		if (reason !== void 0) return {
+			other,
+			reason
+		};
+	}
+}
+/**
+* This function gives the context of the tier `fixed`. Each name of plain data gets a deeply frozen copy of its value,
+* and the record of the fixed names holds the same copy. Each other name keeps its value.
+*/
+function fixedContext(context) {
+	const given = context.names;
+	const names = Object.create(Object.getPrototypeOf(given));
+	const fixed = Object.create(null);
+	for (const key of Reflect.ownKeys(given)) {
+		let field = Object.getOwnPropertyDescriptor(given, key);
+		if (typeof key === "string" && "value" in field) {
+			const copy = sharedCopy(field.value);
+			if (copy !== void 0 || field.value === void 0) {
+				Object.defineProperty(fixed, key, {
+					value: copy,
+					enumerable: true
+				});
+				field = {
+					...field,
+					value: copy
+				};
+			}
+		}
+		Object.defineProperty(names, key, field);
+	}
+	return {
+		context: {
+			...context,
+			names
+		},
+		fixed
+	};
+}
+/**
 * This function evaluates a document with a plan and with other tiers, and compares the results (PLAN.AGREES). Two
 * results agree when they have the same value by `sameValue`, or errors with the same code, and the same place when
 * both have one. The effects must have the same kinds, places and payloads, in the same order. A language gives its
@@ -9886,6 +10144,19 @@ function agree(machine, doc, context = makeContext(), options = {}) {
 			});
 			other = traced.result;
 			otherEffects = [...traced.effects];
+		} else if (tier === "fixed") {
+			const why = fixedDiffers(machine, doc, context, result, effects, {
+				...declared,
+				...mock
+			}, options);
+			if (why !== void 0) return {
+				ok: false,
+				tier,
+				plan: result,
+				other: why.other,
+				reason: why.reason
+			};
+			continue;
 		} else if (tier === "folds") {
 			other = prepare(machine, doc, {
 				...declared,
@@ -10015,6 +10286,7 @@ async function agreeRun(machine, doc, context = makeContext(), options = {}) {
 	const saw = observe?.();
 	const log = recording.log();
 	for (const tier of options.tiers ?? DEFAULT_TIERS) {
+		if (tier === "fixed") continue;
 		const replay = watched(replayer(log));
 		const host = { perform: replay.perform };
 		let other;
@@ -11494,6 +11766,22 @@ function verifyReads(target, reads, context, options = {}) {
 			read,
 			now: stop
 		};
+		if (read.kept === true) {
+			const now = keptAgain(machine, root, read.path);
+			if (now === void 0) return {
+				same: false,
+				index,
+				read,
+				now: fail("#N/A", "The host does not know the value of the kept read yet.")
+			};
+			if (!sameResult(read.reached, now, equal)) return {
+				same: false,
+				index,
+				read,
+				now
+			};
+			continue;
+		}
 		const asked = read.hops !== void 0;
 		const now = readAgain(machine, root, read.path, asked);
 		if (!sameResult(read.reached, now.reached, equal) || read.hops !== void 0 && !sameHops(read.hops, now.hops, equal)) return {
@@ -11766,7 +12054,7 @@ function cyclic(graph, members) {
 	return false;
 }
 /** This function gives the names of the nodes of a component, without the node `all`. */
-function named(graph, members) {
+function named$1(graph, members) {
 	const out = [];
 	for (const member of members) if (member !== graph.all) out.push(graph.ids[member]);
 	return out;
@@ -11805,7 +12093,7 @@ function components(graph, options = {}) {
 	const index = indexed(graph, options);
 	const out = [];
 	for (const members of strong(index).list) {
-		const names = named(index, members);
+		const names = named$1(index, members);
 		if (names.length > 0) out.push(names);
 	}
 	return out;
@@ -11912,7 +12200,7 @@ function cycles(graph) {
 	const out = [];
 	found.list.forEach((members, component) => {
 		if (!cyclic(every, members)) return;
-		const nodes = named(every, members);
+		const nodes = named$1(every, members);
 		const certain = inside.get(component) ?? [];
 		if (certain.length === 1 && certain[0]?.length === nodes.length) {
 			out.push({
@@ -11926,7 +12214,7 @@ function cycles(graph) {
 			certain: false
 		});
 		for (const part of certain) out.push({
-			nodes: named(eager, part),
+			nodes: named$1(eager, part),
 			certain: true
 		});
 	});
@@ -12168,10 +12456,12 @@ function schedule(machine, options = {}) {
 	};
 	/**
 	* This function gives the state of the current data epoch. Each data epoch has a new host thing at the root
-	* `world`. Thus a read that reaches the whole root changes at each change of data (READS.KEPT).
+	* `world`. Thus a read that reaches the whole root changes at each change of data (READS.KEPT). A kept read of a
+	* closure reads a node through `known`, without a demand (SCHED.CLOSURE).
 	*/
 	const current = () => {
 		if (now !== void 0) return now;
+		const values = /* @__PURE__ */ new Map();
 		const nodesThing = {
 			[THING]: true,
 			label: "nodes",
@@ -12183,14 +12473,20 @@ function schedule(machine, options = {}) {
 				return result.value;
 			},
 			has: (key) => docs.has(String(key)),
-			toJson: record
+			toJson: record,
+			known(key) {
+				const result = values.get(String(key));
+				if (result === void 0) return void 0;
+				if (!result.ok) throw new Failure(result.error);
+				return { thing: result.value };
+			}
 		};
 		now = {
 			context: rootContext(machine, {
 				...base,
 				world: nodesThing
 			}),
-			values: /* @__PURE__ */ new Map()
+			values
 		};
 		return now;
 	};
@@ -12265,6 +12561,406 @@ function schedule(machine, options = {}) {
 	};
 }
 //#endregion
+//#region src/meaning.ts
+/** A list of eight reference types. The generator then gives more references, thus more reads of nodes. */
+function moreRefs() {
+	return Array.from({ length: 8 }, () => ["ref"]);
+}
+/** The default options of the document generator, for `STD_MACHINE`. The kinds `log` and `write` need a capability. */
+function standardGenerate() {
+	return {
+		maxSize: 16,
+		types: [
+			...typesOf(STD_MACHINE.world).filter((type) => type[0] !== "log" && type[0] !== "write"),
+			...moreRefs(),
+			["if"],
+			["add"]
+		],
+		data: (type, rng) => {
+			const name = type.join(".");
+			if (name === "number") return rng.chance(.9) ? rng.pick([
+				0,
+				1,
+				2,
+				3.5,
+				-1
+			]) : "1";
+			if (name === "text") return rng.chance(.9) ? rng.pick([
+				"",
+				"a",
+				"b"
+			]) : 1;
+			if (name === "bool") return rng.chance(.9) ? rng.chance(.5) : 0;
+			if (name === "nearest") return rng.pick([{ type: "panel" }, "panel"]);
+		}
+	};
+}
+/** The default `wire`, for `STD_MACHINE`. A list evaluates each part, also after a failed part. */
+function standardWire(rng, node) {
+	if (rng.chance(.5)) return {
+		type: "list",
+		value: [node(), node()]
+	};
+	return rng.chance(.5) ? {
+		type: "add",
+		value: [node(), 1]
+	} : node();
+}
+/** The default values of the names of the host. Some are equal by structure, and some are host values. */
+function standardValues() {
+	return [
+		0,
+		1,
+		2,
+		-0,
+		NaN,
+		"two",
+		null,
+		void 0,
+		[1, 2],
+		{ a: 1 },
+		{ a: 2 },
+		{
+			type: "ref",
+			value: ["names", "a"]
+		},
+		new Held({
+			code: "#HELD",
+			reason: "The binding failed."
+		})
+	];
+}
+/** The default contexts of the host at the start of a run. */
+function standardContexts() {
+	return [context({
+		names: {
+			a: 1,
+			b: [1, "two"],
+			x: { a: 1 },
+			n: 2
+		},
+		caps: ["log"]
+	}), context({
+		names: {
+			a: "two",
+			b: 0,
+			x: null
+		},
+		self: { a: 1 },
+		event: { a: 2 }
+	})];
+}
+/** This function puts a field on a record, also the field `__proto__`. */
+function put(target, key, value) {
+	Object.defineProperty(target, key, {
+		value,
+		enumerable: true,
+		writable: true,
+		configurable: true
+	});
+}
+/** This function changes each path from `names` to a node into a path from `world`. Some paths read the whole root. */
+function linked(value, rng, nodes) {
+	if (Array.isArray(value)) {
+		const items = value.map((item) => linked(item, rng, nodes));
+		if (items[0] === "names" && typeof items[1] === "string" && nodes.includes(items[1])) return rng.chance(.03) ? ["world"] : ["world", ...items.slice(1)];
+		return items;
+	}
+	if (typeof value !== "object" || value === null) return value;
+	const out = {};
+	for (const key of Object.keys(value)) put(out, key, linked(value[key], rng, nodes));
+	return out;
+}
+/** This function gives new names of the host, with one or two changes. */
+function change(base, rng, names, values) {
+	const out = { ...base.names };
+	for (let step = 1 + rng.int(2); step > 0; step -= 1) {
+		const name = rng.pick(names);
+		if (rng.chance(.15)) delete out[name];
+		else out[name] = rng.pick(values);
+	}
+	return out;
+}
+function shuffle(items, rng) {
+	const out = [...items];
+	for (let index = out.length - 1; index > 0; index -= 1) {
+		const other = rng.int(index + 1);
+		[out[index], out[other]] = [out[other], out[index]];
+	}
+	return out;
+}
+/**
+* This function evaluates each node of a graph from scratch, with the meaning of D31. Each node gets a new plan and
+* one value. The algorithm of Tarjan over the demands finds the cycles. The function keeps nothing between calls.
+*/
+function fromScratch(machine, docs, base, declaredType) {
+	const declared = declaredType === void 0 ? {} : { declaredType };
+	const values = /* @__PURE__ */ new Map();
+	const index = /* @__PURE__ */ new Map();
+	const lowest = /* @__PURE__ */ new Map();
+	const component = [];
+	const evaluating = [];
+	const selfReads = /* @__PURE__ */ new Set();
+	const visit = (id) => {
+		const reader = evaluating[evaluating.length - 1];
+		const link = (to) => {
+			if (reader !== void 0) lowest.set(reader, Math.min(lowest.get(reader), to));
+		};
+		const done = values.get(id);
+		if (done !== void 0) {
+			if (component.includes(id)) link(index.get(id));
+			return done;
+		}
+		if (evaluating.includes(id)) {
+			link(index.get(id));
+			if (reader === id) selfReads.add(id);
+			return cycleOf(id);
+		}
+		if (factsOf(machine, docs.get(id), declared).side === "run") {
+			const refused = runSide(id);
+			values.set(id, refused);
+			return refused;
+		}
+		index.set(id, index.size);
+		lowest.set(id, index.get(id));
+		component.push(id);
+		evaluating.push(id);
+		let result = prepare(machine, docs.get(id), declared).evaluate(ctx);
+		evaluating.pop();
+		if (lowest.get(id) < index.get(id)) result = cycleOf(id);
+		else if (component.splice(component.indexOf(id)).length > 1 || selfReads.has(id)) result = cycleOf(id);
+		values.set(id, result);
+		link(lowest.get(id));
+		return result;
+	};
+	const world = {
+		[THING]: true,
+		label: "nodes",
+		deref: (key) => {
+			if (!docs.has(String(key))) return void 0;
+			const result = visit(String(key));
+			if (!result.ok) throw new Failure(result.error);
+			return result.value;
+		},
+		has: (key) => docs.has(String(key)),
+		toJson: () => {
+			const out = {};
+			for (const id of [...docs.keys()].sort()) {
+				if (factsOf(machine, docs.get(id), declared).side === "run") continue;
+				const result = visit(id);
+				if (!result.ok) throw new Failure(result.error);
+				put(out, id, result.value);
+			}
+			return out;
+		}
+	};
+	const ctx = {
+		...base,
+		world
+	};
+	for (const id of [...docs.keys()].sort()) visit(id);
+	return values;
+}
+/** This function names a result for the reason of a disagreement: its error code, or "a value". */
+function named(result) {
+	return result.ok ? "a value" : result.error.code;
+}
+/**
+* This function examines an engine of a host against an evaluation from scratch (SCHED.AGREES, R4 P4, D58). Each run
+* makes a new engine and a random graph of named nodes from the document generator. Then it gives random commands:
+* edits, new nodes, removed nodes, the same document again, new machines and changes of data.
+*
+* - Each read command evaluates the whole graph from scratch two times, with the meaning of D31.
+* - It then demands each node in a random order, or one node, and compares each answer with `sameResult`.
+* - A read whose answer from scratch differs between the two evaluations is not compared.
+* - Two errors agree when they have the same code, reason and place. Thus an engine gives the `#CYCLE!` and the
+*   `#REF!` of D31.
+*
+* The same seed and the same options give the same commands, thus a disagreement occurs again.
+*
+* @param engine - This function makes a new engine for each run, for example `schedule`.
+* @param options - The machines, the generator, the contexts, the number of runs and the rule for host values.
+* @returns What the harness reached, or the first read whose answer differs from the answer from scratch.
+*/
+function agreeSchedule(engine, options = {}) {
+	const machines = options.machines ?? [STD_MACHINE, { ...STD_MACHINE }];
+	const declaredType = options.declaredType;
+	const generateOptions = options.generate ?? standardGenerate();
+	const value = options.value ?? ((rng) => ({
+		type: "number",
+		value: rng.pick([
+			0,
+			1,
+			2
+		])
+	}));
+	const wire = options.wire ?? standardWire;
+	const wired = options.wired ?? .2;
+	const runs = options.runs ?? true;
+	const nodes = options.nodes ?? [
+		"p",
+		"q",
+		"r",
+		"s",
+		"t"
+	];
+	const hostNames = options.names ?? [
+		"a",
+		"b",
+		"x",
+		"n"
+	];
+	const hostValues = options.values ?? standardValues();
+	const contexts = options.contexts ?? standardContexts();
+	const total = options.count ?? 100;
+	const steps = options.steps ?? 30;
+	const first = options.seed ?? 9000011;
+	const given = options.equal;
+	const equal = (a, b) => {
+		const answer = given?.(a, b);
+		if (answer !== void 0) return answer;
+		if (isClosure(a) || isClosure(b)) return isClosure(a) && isClosure(b) && docEquals(closureParams(a), closureParams(b));
+	};
+	const counts = {
+		reads: 0,
+		compared: 0,
+		unrepeatable: 0,
+		values: 0,
+		cycles: 0,
+		runs: 0,
+		data: 0,
+		empty: 0,
+		edits: 0,
+		additions: 0,
+		removes: 0,
+		same: 0,
+		machines: 0
+	};
+	const declared = declaredType === void 0 ? {} : { declaredType };
+	for (let run = 0; run < total; run += 1) {
+		const seed = first + run;
+		const rng = random(seed);
+		const node = () => ({
+			type: "ref",
+			value: ["world", rng.pick(nodes)]
+		});
+		let at = 0;
+		let machine = machines[0];
+		let made = 0;
+		const make = () => {
+			if (rng.chance(wired)) return wire(rng, node);
+			const roll = rng.int(10);
+			if (roll === 0) return value(rng);
+			const names = roll < 5 ? hostNames : [
+				...hostNames,
+				...nodes,
+				...nodes,
+				...nodes
+			];
+			const doc = linked(generate(machine.world, {
+				...generateOptions,
+				names,
+				seed: seed * 31 + made++
+			}), rng, nodes);
+			return runs && roll === 9 ? {
+				type: "log",
+				value: [doc]
+			} : doc;
+		};
+		const docs = new Map(nodes.map((id) => [id, make()]));
+		const start = contexts[run % contexts.length];
+		let base = {
+			...start,
+			names: { ...start.names }
+		};
+		const host = engine(machine, {
+			...declared,
+			context: base
+		});
+		for (const [id, doc] of docs) host.set(id, doc);
+		for (let step = 0; step < steps; step += 1) {
+			const what = rng.int(12);
+			if (what < 4) {
+				const fresh = fromScratch(machine, docs, base, declaredType);
+				const again = fromScratch(machine, docs, base, declaredType);
+				const ids = shuffle([...docs.keys()], rng);
+				for (const id of rng.chance(.5) ? ids : ids.slice(0, 1)) {
+					const got = host.read(id);
+					const want = fresh.get(id);
+					counts.reads += 1;
+					if (!sameResult(want, again.get(id), equal)) {
+						counts.unrepeatable += 1;
+						continue;
+					}
+					counts.compared += 1;
+					if (sameResult(want, cycleOf(id))) counts.cycles += 1;
+					else if (sameResult(want, runSide(id))) counts.runs += 1;
+					else if (want.ok) counts.values += 1;
+					if (!sameResult(got, want, equal)) {
+						const reason = got.ok === want.ok && !got.ok ? `The engine and the evaluation from scratch give two different errors ${named(got)} and ${named(want)} for the node ${id}.` : `The engine gives ${named(got)} for the node ${id}, and the evaluation from scratch gives ${named(want)}.`;
+						return {
+							ok: false,
+							seed,
+							step,
+							node: id,
+							engine: got,
+							scratch: want,
+							docs: new Map(docs),
+							context: base,
+							machine,
+							reason,
+							counts: { ...counts }
+						};
+					}
+				}
+			} else if (what < 6) {
+				base = {
+					...base,
+					names: change(base, rng, hostNames, hostValues)
+				};
+				host.changeData(base);
+				counts.data += 1;
+			} else if (what === 6) {
+				host.changeData(base);
+				counts.empty += 1;
+			} else if (what < 9) {
+				const id = rng.pick(nodes);
+				const doc = make();
+				docs.set(id, doc);
+				host.set(id, doc);
+				counts.edits += 1;
+			} else if (what === 9) {
+				const absent = nodes.filter((id) => !docs.has(id));
+				if (absent.length > 0 && (docs.size <= 2 || rng.chance(.65))) {
+					const id = rng.pick(absent);
+					const doc = make();
+					docs.set(id, doc);
+					host.set(id, doc);
+					counts.additions += 1;
+				} else {
+					const id = rng.pick([...docs.keys()]);
+					docs.delete(id);
+					host.remove(id);
+					counts.removes += 1;
+				}
+			} else if (what === 10) {
+				const id = rng.pick([...docs.keys()]);
+				host.set(id, docs.get(id));
+				counts.same += 1;
+			} else if (host.changeMachine !== void 0) {
+				at = (at + 1) % machines.length;
+				machine = machines[at];
+				host.changeMachine(machine);
+				counts.machines += 1;
+			}
+		}
+	}
+	return {
+		ok: true,
+		counts
+	};
+}
+//#endregion
 //#region src/providers.ts
 /** The deepest schema that `typeFromSchema` reads. A deeper schema reads as `unknown`. */
 const MAX_SCHEMA_DEPTH = 256;
@@ -12575,6 +13271,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, 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 };
+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, agreeSchedule, 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, placeOf, 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