@mark1russell7/coeval 0.3.3 → 0.4.1

package/build/index.js

@@ -450,6 +450,9 @@ function entriesAsJson(entries) {
 }
 function describeShape(shape) {
 	if (shape === void 0 || shape.shape === "none") return "none";
+	if (shape.shape === "text") return "a text";
+	if (shape.shape === "number") return "a number";
+	if (shape.shape === "one") return `one of ${JSON.stringify(shape.values)}`;
 	if (shape.shape === "term") return `a part${shape.of === void 0 ? "" : ` of ${shape.of}`}`;
 	if (shape.shape === "deep") return "each document in the value";
 	if (shape.shape === "list") return `a list${shape.of === void 0 ? "" : ` of ${shape.of}`}`;
@@ -940,7 +943,7 @@ function resolve(nav, ctx, path, options = {}) {
 						return reached === void 0 ? void 0 : adopt(reached.thing);
 					}
 				});
-				if (!result.ok) return failed("#N/A", result.reason);
+				if (!result.ok) return failed(result.code ?? "#N/A", result.reason);
 				here = adopt(result.thing);
 				hops?.push({
 					step: envelope,
@@ -1033,6 +1036,22 @@ const NO_SLOTS = Object.freeze([]);
 function hasSlots(template) {
 	return template.t !== "data";
 }
+/** This function gives the reason why a value is not data of a shape, or `undefined` when it is. */
+function dataFault(spec, item) {
+	if (spec.shape === "text") return typeof item === "string" ? void 0 : "The value must be a text.";
+	if (spec.shape === "one") return spec.values.some((value) => docEquals(value, item)) ? void 0 : `The value must be one of ${JSON.stringify(spec.values)}.`;
+	if (typeof item !== "number") return "The value must be a number.";
+	if (spec.whole === true && !Number.isInteger(item)) return "The value must be a whole number.";
+	if (spec.min !== void 0 && !(item >= spec.min)) return `The value must be ${String(spec.min)} or more.`;
+	if (spec.max !== void 0 && !(item <= spec.max)) return `The value must be ${String(spec.max)} or less.`;
+}
+/** This function stops a split when a part has a type that its position does not permit. */
+function kindFault(kinds, item, of, path) {
+	const type = isEnvelope(item) ? typePath(item.type) : of === void 0 ? void 0 : [of];
+	if (type !== void 0 && kinds.some((kind) => kind.length <= type.length && kind.every((key, index) => String(key) === String(type[index])))) return;
+	const names = kinds.map((kind) => kind.join(".")).join(", ");
+	throw new Bad(`${isEnvelope(item) ? `The kind ${typeName(item.type)} is not permitted here.` : "A value without an envelope is not permitted here."} The permitted kinds are ${names}.`, path);
+}
 /**
 * This function splits a value into its parts, by the shape that its kind declares. The evaluator, the view and
 * the static kit use the same split, thus each one sees the same parts.
@@ -1049,12 +1068,13 @@ function splitParts(shape, value) {
 		fill: () => value
 	};
 	const parts = [];
-	const slot = (item, path, of) => {
+	const slot = (item, path, of, address = false) => {
 		parts.push({
 			path,
 			key: path.join("."),
 			item,
-			...of === void 0 ? {} : { of }
+			...of === void 0 ? {} : { of },
+			...address ? { address: true } : {}
 		});
 		return {
 			t: "slot",
@@ -1093,17 +1113,33 @@ function splitParts(shape, value) {
 			t: "data",
 			value: item
 		};
-		if (spec.shape === "term") return slot(item, path, spec.of);
+		if (spec.shape === "text" || spec.shape === "number" || spec.shape === "one") {
+			const reason = dataFault(spec, item);
+			if (reason !== void 0) throw new Bad(reason, path);
+			return {
+				t: "data",
+				value: item
+			};
+		}
+		if (spec.shape === "term") {
+			if (spec.kinds !== void 0) kindFault(spec.kinds, item, spec.of, path);
+			return slot(item, path, spec.of, spec.address === true);
+		}
 		if (spec.shape === "deep") return deep(item, path, spec.of);
 		if (spec.shape === "list") {
 			if (!Array.isArray(item)) throw new Bad("The value must be a list.", path);
+			const list = item;
+			if (spec.distinct === true) {
+				const twice = list.findIndex((child, index) => list.slice(0, index).some((before) => docEquals(before, child)));
+				if (twice !== -1) throw new Bad("The items of the list must be different.", [...path, twice]);
+			}
 			const each = spec.item ?? {
 				shape: "term",
 				...spec.of === void 0 ? {} : { of: spec.of }
 			};
 			return {
 				t: "list",
-				items: item.map((child, index) => walk(each, child, [...path, index]))
+				items: list.map((child, index) => walk(each, child, [...path, index]))
 			};
 		}
 		if (!isRecord(item)) throw new Bad("The value must be a record.", path);
@@ -1124,6 +1160,7 @@ function splitParts(shape, value) {
 		}])) : spec.fields;
 		const fields = [];
 		for (const key of Object.keys(item)) {
+			if (spec.closed === true && !Object.hasOwn(named, key)) throw new Bad(`The field ${key} is not a field of this kind.`, [...path, key]);
 			const fieldShape = Object.hasOwn(named, key) ? named[key] : spec.rest;
 			fields.push([key, walk(fieldShape, item[key], [...path, key])]);
 		}
@@ -1244,6 +1281,52 @@ function narrow(parent, next) {
 		caps
 	};
 }
+/** No capabilities. One list serves each masked part. */
+const NO_CAPS = Object.freeze([]);
+/** No capability rules. One list serves each part that no rule narrows. */
+const NO_RULES = Object.freeze([]);
+/**
+* This function gives the capabilities that two lists both permit. An effect is permitted by the result when each
+* list permits it. When the list `b` permits each capability of `a`, the result is the list `a` itself.
+*
+* @param a - The first list, for example the capabilities of a document.
+* @param b - The second list, for example the list of a rule `only`.
+* @returns The capabilities that both lists permit.
+*/
+function intersectCaps(a, b) {
+	if (a.every((cap) => permits(b, cap))) return a;
+	const out = [];
+	for (const cap of b) if (permits(a, cap)) out.push(cap);
+	for (const cap of a) if (permits(b, cap) && !permits(out, cap)) out.push(cap);
+	return out;
+}
+/** This function gives the capability rules of a kind that cover a part and change its capabilities. */
+function rulesFor(rules, path) {
+	if (rules === void 0 || rules.length === 0) return NO_RULES;
+	const out = rules.filter((rule) => rule.rule !== "same" && (rule.in === void 0 || rule.in.some((pattern) => pathMatches(path, pattern))));
+	return out.length === 0 ? NO_RULES : out;
+}
+/** This function applies the rules that cover a part to the capabilities of its document. */
+function capsUnder(rules, caps) {
+	let out = caps;
+	for (const rule of rules) {
+		if (rule.rule === "mask") return NO_CAPS;
+		if (rule.rule === "only") out = intersectCaps(out, rule.caps);
+	}
+	return out;
+}
+/**
+* This function gives the capabilities that a kind gives one of its parts, by the capability rules of its contract.
+* The kernel and the static kit both use it, thus a run and a check narrow the same way.
+*
+* @param rules - The capability rules of the kind (`Kind.caps`).
+* @param path - The path of the part in the value of the document.
+* @param caps - The capabilities of the document.
+* @returns The capabilities of the part: the same list or a smaller one.
+*/
+function partCaps(rules, path, caps) {
+	return capsUnder(rulesFor(rules, path), caps);
+}
 function selfLabel(self) {
 	try {
 		if (isHostThing(self)) return self.label;
@@ -1591,7 +1674,7 @@ const NO_META = Object.freeze({
 	answer: NO_ANSWER,
 	side: "derive"
 });
-function compileNode(c, value, place, declared, depth) {
+function compileNode(c, value, place, declared, depth, address = false) {
 	const envelope = isEnvelope(value) ? value : void 0;
 	const doc = envelope ?? {
 		type: declared ?? "?",
@@ -1639,7 +1722,9 @@ function compileNode(c, value, place, declared, depth) {
 	}
 	const parts = split.parts.map((slot) => {
 		const item = slot.item;
-		const compiled = compileNode(c, item, place.concat(slot.path), slot.of, depth + 1);
+		const own = compileNode(c, item, place.concat(slot.path), slot.of, depth + 1, slot.address === true);
+		const rules = rulesFor(kind?.caps, slot.path);
+		const compiled = rules.length === 0 ? own : gated(rules, own);
 		const header = typeof item?.name === "string" && isEnvelope(item) ? item.name : void 0;
 		return header === void 0 ? {
 			key: slot.key,
@@ -1663,7 +1748,8 @@ function compileNode(c, value, place, declared, depth) {
 		parts,
 		place,
 		machine: c.machine,
-		fill: fillOf(split, doc)
+		fill: fillOf(split, doc),
+		...address ? { address: true } : {}
 	};
 	if (runner !== void 0) {
 		const run = placedRun(isCompiledRunner(runner) ? runner.compileRun(input) : interpretRun(runner, input, split.fill), place, name);
@@ -1682,6 +1768,25 @@ function placedCode(inner, place, name) {
 		}
 	};
 }
+/**
+* This function gives the code of a part that capability rules cover. The code narrows the context of the part by
+* the rules before the part starts.
+*/
+function gated(rules, part) {
+	const inner = part.code;
+	const steps = part.run;
+	const under = (ctx) => {
+		const caps = capsUnder(rules, ctx.caps);
+		return caps === ctx.caps || caps.length === 0 && ctx.caps.length === 0 ? ctx : {
+			...ctx,
+			caps
+		};
+	};
+	return {
+		code: (ctx, rt) => inner(under(ctx), rt),
+		run: (ctx, rt) => steps(under(ctx), rt)
+	};
+}
 /** This function gives the steps of a runner, with the place of each error and of each exception. */
 function placedRun(inner, place, name) {
 	return function* (ctx, rt) {
@@ -1708,6 +1813,7 @@ function fillOf(split, doc) {
 }
 function interpret(fn, input, fill) {
 	const { kind, typePath, doc, data, place } = input;
+	const address = input.address === true ? { address: true } : {};
 	const compiled = input.parts;
 	const hasParts = compiled.length > 0;
 	return (ctx, rt) => {
@@ -1726,6 +1832,7 @@ function interpret(fn, input, fill) {
 			parts,
 			context: ctx,
 			place,
+			...address,
 			resolve: (path, options) => rt.resolve(ctx, path, options),
 			effect: (effectKind, payload) => rt.effect(ctx, effectKind, payload, place),
 			fill: input.fill
@@ -2106,6 +2213,7 @@ const STD_WORLD = {
 				view: "view.op"
 			},
 			parts: { shape: "list" },
+			caps: [{ rule: "mask" }],
 			summary: "It evaluates its part without capabilities, thus an effect in it fails."
 		},
 		log: {
@@ -2118,6 +2226,7 @@ const STD_WORLD = {
 				of: "text"
 			},
 			side: "run",
+			effects: ["log"],
 			summary: "It writes the result of its part to the log. This is an effect."
 		},
 		write: {
@@ -2130,6 +2239,7 @@ const STD_WORLD = {
 				fields: ["value"]
 			},
 			side: "run",
+			effects: ["write"],
 			summary: "It writes the result of its part to the store, at its key. This is an effect."
 		}
 	},
@@ -2307,13 +2417,10 @@ const STD_RUNNERS = {
 		}
 		return ok(last);
 	},
-	"control.pure": function* ({ parts, context }) {
+	"control.pure": function* ({ parts }) {
 		const only = parts[0];
 		if (only === void 0) return fail("#VALUE!", "pure needs one part.");
-		return yield* only.evaluate({
-			...context,
-			caps: []
-		});
+		return yield* only.evaluate();
 	},
 	"control.if": function* ({ parts }) {
 		const test = parts.find((part) => part.key === "test");
@@ -2811,34 +2918,91 @@ function withoutNames(options) {
 	const { names: _host, ...rest } = options;
 	return rest;
 }
+/** This function gives the keys of a trail, from its start. It keeps the result in the trail. */
+function keysOf(trail) {
+	if (trail === void 0) return [];
+	if (trail.full !== void 0) return trail.full;
+	const steps = [];
+	let here = trail;
+	while (here !== void 0 && here.full === void 0) {
+		steps.push(here);
+		here = here.up;
+	}
+	const keys = here?.full === void 0 ? [] : [...here.full];
+	for (let index = steps.length - 1; index >= 0; index -= 1) for (const key of steps[index].keys) keys.push(key);
+	trail.full = keys;
+	return keys;
+}
+/** A visit with its paths as trails. It makes the keys of a path only when a reader asks for them. */
+var Visit = class {
+	doc;
+	declared;
+	depth;
+	names;
+	later;
+	slot;
+	parent;
+	kind;
+	typePath;
+	address;
+	caps;
+	#place;
+	#at;
+	constructor(place, at, doc, declared, depth, names, later, slot, parent, kind, typePath, address, caps) {
+		this.doc = doc;
+		this.declared = declared;
+		this.depth = depth;
+		this.names = names;
+		this.later = later;
+		this.slot = slot;
+		this.parent = parent;
+		this.kind = kind;
+		this.typePath = typePath;
+		this.address = address;
+		this.caps = caps;
+		this.#place = place;
+		this.#at = at;
+	}
+	get place() {
+		return keysOf(this.#place);
+	}
+	get at() {
+		return keysOf(this.#at);
+	}
+};
 /**
 * This function visits each document of a document: the root and each part at each depth, by the contracts of the
-* kinds. A part of a kind that the world does not have is not visited. The walk uses no stack of the host for the
-* depth, thus a deep document cannot overflow it.
+* kinds. A part of a kind that the world does not have is not visited. With capabilities in the options, the walk
+* narrows them for each part by the rules of its kind, as a run does. The walk uses no stack of the host for the
+* depth, thus a deep document cannot overflow it. The time and the memory of a walk are linear in the size of the
+* document. A visit makes the keys of its place and of its path only when a reader asks for them.
 *
 * @param world - The world of the kinds.
 * @param doc - The document, as JSON.
 * @param visit - The function that gets each document. It gives `"skip"` to not visit the parts of a document.
-* @param options - The type of a bare root value, the names of the host, and a function for the problems.
+* @param options - The type of a bare root value, the names, the capabilities and a function for the problems.
 */
 function walk(world, doc, visit, options = {}) {
-	const names = options.names === void 0 || options.names.length === 0 ? NO_NAMES : new Set(options.names);
 	const stack = [{
 		value: doc,
-		place: [],
-		at: [],
+		place: void 0,
+		at: void 0,
 		declared: options.declaredType,
 		depth: 0,
-		names,
-		later: NO_NAMES
+		names: options.names === void 0 || options.names.length === 0 ? NO_NAMES : new Set(options.names),
+		later: NO_NAMES,
+		address: false,
+		slot: [],
+		parent: void 0,
+		caps: options.caps
 	}];
 	while (stack.length > 0) {
 		const item = stack.pop();
 		const envelope = isEnvelope(item.value) ? item.value : void 0;
 		if (envelope === void 0 && item.declared === void 0) {
 			options.problem?.({
-				place: item.place,
-				at: item.at,
+				place: keysOf(item.place),
+				at: keysOf(item.at),
 				code: "#PART?",
 				reason: "The value has no envelope, and its position declares no type."
 			});
@@ -2850,50 +3014,50 @@ function walk(world, doc, visit, options = {}) {
 		};
 		const found = lookupKind(world, doc.type);
 		const kind = found.ok ? found.kind : void 0;
-		if (visit(kind === void 0 ? {
-			place: item.place,
-			at: item.at,
-			doc,
-			declared: envelope === void 0,
-			depth: item.depth,
-			names: item.names,
-			later: item.later
-		} : {
-			place: item.place,
-			at: item.at,
-			doc,
-			declared: envelope === void 0,
-			kind,
-			typePath: found.ok ? found.path : [],
-			depth: item.depth,
-			names: item.names,
-			later: item.later
-		}) === "skip" || kind === void 0) continue;
+		const here = new Visit(item.place, item.at, doc, envelope === void 0, item.depth, item.names, item.later, item.slot, item.parent, kind, found.ok ? found.path : void 0, item.address ? true : void 0, item.caps);
+		if (visit(here) === "skip" || kind === void 0) continue;
 		const split = splitParts(kind.parts, doc.value);
+		const base = envelope === void 0 ? item.at : {
+			up: item.at,
+			keys: ["value"]
+		};
 		if (!split.ok) {
 			const at = split.at.length === 0 ? "" : ` (at ${split.at.join(".")})`;
+			const where = keysOf({
+				up: base,
+				keys: split.at
+			});
 			options.problem?.({
-				place: item.place,
-				at: item.at,
+				place: keysOf(item.place),
+				at: where,
 				code: "#VALUE!",
 				reason: `${split.reason}${at} The kind is ${typeName(doc.type)}.`
 			});
 			continue;
 		}
 		const { sees, later } = scopesOf(kind.scope, doc.value, split.parts);
-		const base = envelope === void 0 ? item.at : [...item.at, "value"];
 		for (let index = split.parts.length - 1; index >= 0; index -= 1) {
 			const slot = split.parts[index];
 			const extra = sees[index] ?? [];
 			const hidden = later[index] ?? [];
 			stack.push({
 				value: slot.item,
-				place: [...item.place, ...slot.path],
-				at: [...base, ...slot.path],
+				place: slot.path.length === 0 ? item.place : {
+					up: item.place,
+					keys: slot.path
+				},
+				at: slot.path.length === 0 ? base : {
+					up: base,
+					keys: slot.path
+				},
 				declared: slot.of,
 				depth: item.depth + 1,
 				names: extra.length === 0 ? item.names : /* @__PURE__ */ new Set([...item.names, ...extra]),
-				later: hidden.length === 0 ? item.later : /* @__PURE__ */ new Set([...item.later, ...hidden])
+				later: hidden.length === 0 ? item.later : /* @__PURE__ */ new Set([...item.later, ...hidden]),
+				address: slot.address === true,
+				slot: slot.path,
+				parent: here,
+				caps: item.caps === void 0 || kind.caps === void 0 ? item.caps : partCaps(kind.caps, slot.path, item.caps)
 			});
 		}
 	}
@@ -2901,7 +3065,7 @@ function walk(world, doc, visit, options = {}) {
 /**
 * This function finds each reference of a document: each document of the type `ref` that a walk reaches. A
 * reference to a name that a kind around it binds is not free. The others are what the document reads from
-* outside: its dependencies.
+* outside: its dependencies. When the kind `ref` has parts, the walk also finds the references in its step documents.
 *
 * @param world - The world of the kinds.
 * @param doc - The document, as JSON.
@@ -2915,15 +3079,25 @@ function refsOf(world, doc, options = {}) {
 		const path = v.doc.value;
 		const root = typeof path[0] === "string" ? path[0] : "";
 		const first = path[1];
-		const bound = root === "names" && isKey(first) && v.names.has(String(first));
-		out.push({
-			place: v.place,
-			at: v.at,
+		const use = {
 			path,
 			root,
-			free: !bound
+			free: !(root === "names" && isKey(first) && v.names.has(String(first))),
+			address: v.address === true
+		};
+		Object.defineProperty(use, "place", {
+			enumerable: true,
+			get: () => v.place
 		});
-		return "skip";
+		Object.defineProperty(use, "at", {
+			enumerable: true,
+			get: () => v.at
+		});
+		Object.defineProperty(use, "visit", {
+			enumerable: false,
+			value: v
+		});
+		out.push(use);
 	}, options.names === void 0 ? options : withoutNames(options));
 	return out;
 }
@@ -2971,6 +3145,15 @@ function mapRefs(world, doc, change, options = {}) {
 	return out;
 }
 /**
+* This function gives the reason of a `#CAP!`. When a kind around the document narrowed the capabilities, the
+* reason names the nearest such kind.
+*/
+function capReason(v, kind) {
+	const text = kind.join(".");
+	for (let up = v.parent; up !== void 0; up = up.parent) if (up.caps !== void 0 && permits(up.caps, kind)) return `The capabilities do not permit the effect ${text} here. The kind ${typeName(up.doc.type)} around it narrows them for its parts.`;
+	return `The capabilities do not permit the effect ${text}.`;
+}
+/**
 * This function checks a document before an evaluation, by the contracts of its kinds. It finds the problems
 * that an evaluation finds when it reaches them:
 *
@@ -2981,7 +3164,7 @@ function mapRefs(world, doc, change, options = {}) {
 * - `#DEPTH!`: too much nesting.
 * - `#REF!` and `#STEP?`: a bad path.
 * - `#NAME?`: a name that nothing binds.
-* - `#CAP!`: an effect that the capabilities do not permit.
+* - `#CAP!`: an effect that the capabilities of its document do not permit. A kind around the document can narrow them.
 *
 * @param machine - The world and the code of the evaluators.
 * @param doc - The document, as JSON.
@@ -2999,7 +3182,8 @@ function check(machine, doc, options = {}) {
 			issues.push({
 				code: "#DEPTH!",
 				place: v.place,
-				reason: `The nesting is deeper than ${maxDepth} documents.`
+				reason: `The nesting is deeper than ${maxDepth} documents.`,
+				at: v.at
 			});
 			return "skip";
 		}
@@ -3009,7 +3193,8 @@ function check(machine, doc, options = {}) {
 			issues.push({
 				code: "#KIND?",
 				place: v.place,
-				reason: `The world has no kind ${typeName(v.doc.type)}.`
+				reason: `The world has no kind ${typeName(v.doc.type)}.`,
+				at: v.at
 			});
 			return "skip";
 		}
@@ -3017,31 +3202,48 @@ function check(machine, doc, options = {}) {
 		if (name === void 0 || !has(machine.evaluators, name) && !has(machine.runners, name)) issues.push({
 			code: "#NOEVAL",
 			place: v.place,
-			reason: `No rung gives an evaluator for ${typeName(v.doc.type)}.`
+			reason: `No rung gives an evaluator for ${typeName(v.doc.type)}.`,
+			at: v.at
 		});
-		if (options.caps !== void 0 && v.kind?.effects !== void 0) {
+		const caps = v.caps;
+		if (caps !== void 0 && v.kind?.effects !== void 0) {
 			const kinds = v.kind.effects === "type" ? [v.typePath ?? []] : v.kind.effects.map((kind) => kind.split("."));
-			for (const kind of kinds) if (!permits(options.caps, kind)) issues.push({
+			for (const kind of kinds) if (!permits(caps, kind)) issues.push({
 				code: "#CAP!",
 				place: v.place,
-				reason: `The capabilities do not permit the effect ${kind.join(".")}.`
+				reason: capReason(v, kind),
+				at: v.at
 			});
 		}
-		if (!isRef(v.doc)) return void 0;
+		const isPath = isRef(v.doc);
+		if (!isPath && v.typePath?.length === 1 && v.typePath[0] === "ref") issues.push({
+			code: "#VALUE!",
+			place: v.place,
+			reason: "The value of ref is a path: a list that starts with a root.",
+			at: [...v.at, ...v.declared ? [] : ["value"]]
+		});
+		if (!isPath) return void 0;
 		const path = v.doc.value;
 		const root = path[0];
+		const stepAt = (index) => [
+			...v.at,
+			"value",
+			...index < path.length ? [index] : []
+		];
 		if (typeof root !== "string" || !ROOTS.includes(root)) {
 			issues.push({
 				code: "#REF!",
 				place: v.place,
-				reason: `A path starts with a root: ${ROOTS.join(", ")}.`
+				reason: `A path starts with a root: ${ROOTS.join(", ")}.`,
+				at: stepAt(0)
 			});
 			return "skip";
 		}
 		if (!roots.includes(root)) issues.push({
 			code: "#REF!",
 			place: v.place,
-			reason: `The root ${root} is not open here. The open roots are ${roots.join(", ")}.`
+			reason: `The root ${root} is not open here. The open roots are ${roots.join(", ")}.`,
+			at: stepAt(0)
 		});
 		const first = path[1];
 		if (root === "names" && !anyName && isKey(first) && !v.names.has(String(first))) {
@@ -3049,33 +3251,38 @@ function check(machine, doc, options = {}) {
 			issues.push({
 				code: "#NAME?",
 				place: v.place,
-				reason: later ? `The name ${String(first)} is bound by a later step.` : `Nothing binds the name ${String(first)}.`
+				reason: later ? `The name ${String(first)} is bound by a later step.` : `Nothing binds the name ${String(first)}.`,
+				at: stepAt(1)
 			});
 		}
-		path.slice(1).forEach((step) => {
-			if (isKey(step)) return;
+		path.forEach((step, index) => {
+			if (index === 0 || isKey(step)) return;
 			const found = isEnvelope(step) ? lookupKind(machine.world, step.type) : void 0;
 			const walker = found?.ok === true && Object.hasOwn(found.kind.verbs, "step") ? found.kind.verbs["step"] : void 0;
 			if (walker === void 0 || !has(machine.walkers, walker)) issues.push({
 				code: "#STEP?",
 				place: v.place,
-				reason: "A step is a key, or a document of a kind with the verb step."
+				reason: "A step is a key, or a document of a kind with the verb step.",
+				at: stepAt(index)
 			});
 		});
-		return "skip";
 	}, {
 		...options.declaredType === void 0 ? {} : { declaredType: options.declaredType },
 		...Array.isArray(options.names) ? { names: options.names } : {},
+		...options.caps === void 0 ? {} : { caps: options.caps },
 		problem: (problem) => issues.push({
 			code: problem.code,
 			place: problem.place,
-			reason: problem.reason
+			reason: problem.reason,
+			at: problem.at
 		})
 	});
 	return issues;
 }
 //#endregion
 //#region src/formula.ts
+/** The mark of a field that the profile leaves out of a record. */
+const SKIPPED = Symbol("skipped");
 /** The value of a name whose binding failed. A reference to the name gives the error. */
 var Held = class {
 	error;
@@ -3127,6 +3334,16 @@ function setOwn(target, key, value) {
 function compiled(compile) {
 	return { compile };
 }
+/** This function evaluates parts in order. It gives the value of each part, or the first error. */
+function valuesOf(parts, ctx, rt) {
+	const values = new Array(parts.length);
+	for (let index = 0; index < parts.length; index += 1) {
+		const result = parts[index].code(ctx, rt);
+		if (!result.ok) return result;
+		values[index] = result.value;
+	}
+	return values;
+}
 function partsOf(value) {
 	return isRecord(value) ? value : {};
 }
@@ -3273,18 +3490,48 @@ function formulaEvaluators(profile = {}) {
 		return Object.hasOwn(ops, name) ? ops[name] : void 0;
 	};
 	const notTruth = (what) => fail("#VALUE!", `The ${what} must give a truth value.`);
+	const combine = profile.combine;
+	/** This function evaluates each part. Without `combine`, the first error stops it. A field that `omit` skips is absent. */
+	const collect = (parts, ctx, rt, skip) => {
+		const values = new Array(parts.length);
+		let errors;
+		for (let index = 0; index < parts.length; index += 1) {
+			const result = parts[index].code(ctx, rt);
+			if (result.ok) values[index] = result.value;
+			else if (skip !== void 0 && skip(result.error)) values[index] = SKIPPED;
+			else if (combine === void 0) return result;
+			else (errors ??= []).push(result.error);
+		}
+		if (errors === void 0 || combine === void 0) return values;
+		return {
+			ok: false,
+			error: errors.length === 1 ? errors[0] : combine(errors)
+		};
+	};
 	return {
 		"formula.lit": compiled(({ doc }) => {
 			const result = ok(doc.value);
 			return () => result;
 		}),
-		"formula.ref": compiled(({ doc }) => {
+		"formula.ref": compiled(({ doc, parts, fill, address }) => {
 			const path = doc.value;
 			if (!Array.isArray(path) || path.length === 0) {
 				const bad = fail("#VALUE!", "The value of ref is a path: a list that starts with a root, for example [\"names\", \"a\"].");
 				return () => bad;
 			}
 			const head = path[0] === "names" && typeof path[1] === "string" ? path[1] : void 0;
+			const give = (found) => {
+				if (!found.ok) return fail(found.code, found.reason);
+				if (address === true) return ok(found.thing);
+				const reached = valueOfThing(found.thing);
+				if (reached instanceof Held) return {
+					ok: false,
+					error: reached.error
+				};
+				if (missing !== void 0 && missing(reached)) return fail("#N/A", "The path reaches no value.");
+				return ok(reached);
+			};
+			const computed = parts.length > 0;
 			return (ctx, rt) => {
 				if (head !== void 0 && Object.hasOwn(ctx.names, head)) {
 					const bound = ctx.names[head];
@@ -3293,21 +3540,40 @@ function formulaEvaluators(profile = {}) {
 						error: bound.error
 					};
 				}
-				const found = rt.resolve(ctx, path);
-				if (!found.ok) return fail(found.code, found.reason);
-				const value = valueOfThing(found.thing);
-				if (value instanceof Held) return {
-					ok: false,
-					error: value.error
-				};
-				if (missing !== void 0 && missing(value)) return fail("#N/A", "The path reaches no value.");
-				return ok(value);
+				if (!computed) return give(rt.resolve(ctx, path));
+				const steps = valuesOf(parts, ctx, rt);
+				return Array.isArray(steps) ? give(rt.resolve(ctx, fill(steps))) : steps;
+			};
+		}),
+		"formula.step": compiled(({ doc, parts, fill }) => {
+			if (parts.length === 0) {
+				const same = ok(doc);
+				return () => same;
+			}
+			return (ctx, rt) => {
+				const values = valuesOf(parts, ctx, rt);
+				return Array.isArray(values) ? ok({
+					...doc,
+					value: fill(values)
+				}) : values;
 			};
 		}),
 		"formula.record": compiled(({ value }) => {
 			const fields = partsOf(value);
 			const keys = Object.keys(fields);
 			const codes = keys.map((key) => fields[key].code);
+			if (combine !== void 0) {
+				const parts = keys.map((key) => fields[key]);
+				return (ctx, rt) => {
+					const values = collect(parts, ctx, rt, omit);
+					if (!Array.isArray(values)) return values;
+					const out = {};
+					keys.forEach((key, index) => {
+						if (values[index] !== SKIPPED) setOwn(out, key, values[index]);
+					});
+					return ok(out);
+				};
+			}
 			return (ctx, rt) => {
 				const out = {};
 				for (let index = 0; index < keys.length; index += 1) {
@@ -3322,13 +3588,8 @@ function formulaEvaluators(profile = {}) {
 			};
 		}),
 		"formula.list": compiled(({ parts }) => (ctx, rt) => {
-			const out = new Array(parts.length);
-			for (let index = 0; index < parts.length; index += 1) {
-				const result = parts[index].code(ctx, rt);
-				if (!result.ok) return result;
-				out[index] = result.value;
-			}
-			return ok(out);
+			const values = collect(parts, ctx, rt);
+			return Array.isArray(values) ? ok(values) : values;
 		}),
 		"formula.let": compiled(({ value }) => {
 			const record = partsOf(value);
@@ -3443,6 +3704,15 @@ function formulaEvaluators(profile = {}) {
 			}
 			const done = (out) => check === void 0 ? ok(out) : check(out, name) ?? ok(out);
 			const failed = (error) => thrown(error, `the operation ${name}`);
+			if (combine !== void 0) return (ctx, rt) => {
+				const values = collect(parts, ctx, rt);
+				if (!Array.isArray(values)) return values;
+				try {
+					return done(fn(...values));
+				} catch (error) {
+					return failed(error);
+				}
+			};
 			if (parts.length === 1) {
 				const [a] = parts;
 				return (ctx, rt) => {
@@ -3490,9 +3760,9 @@ function formulaEvaluators(profile = {}) {
 				const unknown = fail("#NAME?", `The language has no extension ${name}.`);
 				return () => unknown;
 			}
-			return () => {
+			return (ctx) => {
 				try {
-					return handler(doc.value);
+					return handler(doc.value, ctx);
 				} catch (error) {
 					return thrown(error, `the extension ${name}`);
 				}
@@ -3525,6 +3795,6 @@ function formulaMachine(profile = {}, more = {}) {
 	};
 }
 //#endregion
-export { CONSTRUCTS, ENVELOPE_KEYS, Failure, Held, PARTS, PART_INFO, ROOTS, RUNGS, STD_CAPS, STD_EVALUATORS, STD_EXT, STD_MACHINE, STD_RUNNERS, STD_WALKERS, STD_WORLD, THING, ask, capKeys, check, checkSteps, classify, context, dataEdges, derefStep, describe, docEquals, effectEdges, entriesAsJson, evaluate, fail, failures, field, flatten, formulaEvaluators, formulaKinds, formulaMachine, fromJson, isAlias, isAllowedOrder, isClosure, isEnvelope, isHostThing, isKey, isKind, isNamespace, isRecord, isRef, isStackOverflow, isTypeRef, jsTruthy, kindDocument, kindNamed, kindOf, layers, looksLikeKind, lookupKind, makeContext, mapRefs, narrow, nearestWalker, nodeAt, ok, pathMatches, permits, placed, planner, prepare, ref, refsOf, resolve, run, splitParts, stored, tag, thrown, toJson, typeName, typePath, typed, valueOfThing, walk, worldThing };
+export { CONSTRUCTS, ENVELOPE_KEYS, Failure, Held, PARTS, PART_INFO, ROOTS, RUNGS, STD_CAPS, STD_EVALUATORS, STD_EXT, STD_MACHINE, STD_RUNNERS, STD_WALKERS, STD_WORLD, THING, ask, capKeys, check, checkSteps, classify, context, dataEdges, derefStep, describe, docEquals, effectEdges, entriesAsJson, evaluate, fail, failures, field, flatten, formulaEvaluators, formulaKinds, formulaMachine, fromJson, intersectCaps, isAlias, isAllowedOrder, isClosure, isEnvelope, isHostThing, isKey, isKind, isNamespace, isRecord, isRef, isStackOverflow, isTypeRef, jsTruthy, kindDocument, kindNamed, kindOf, layers, looksLikeKind, lookupKind, makeContext, mapRefs, narrow, nearestWalker, nodeAt, ok, partCaps, pathMatches, permits, placed, planner, prepare, ref, refsOf, resolve, run, splitParts, stored, tag, thrown, toJson, typeName, typePath, typed, valueOfThing, walk, worldThing };
 
 //# sourceMappingURL=index.js.map