trilean 0.0.0 → 1.0.0

package/dist/evaluator.cjs

@@ -0,0 +1,482 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_computed_value = require("./computed-value.cjs");
+const require_evaluation = require("./evaluation.cjs");
+const require_functions = require("./functions.cjs");
+//#region src/evaluator.ts
+/**
+* `evaluatePredicateInternal` and `evaluateValueInternal` are co-located in this one file, rather than split across `predicate-evaluator.ts`/`value-evaluator.ts`, because they are mutually recursive: a predicate leaf (`compare`, `textCompare`, `memberOf`, `exists`) holds `ExpressionNode` operands, and an expression node (`conditional`'s `when`, a fold's `filter`) holds `PredicateNode` operands. Splitting them across modules would make each half import the other, and whichever module finished loading second would see the other's export as `undefined` at its own module-evaluation time -- a genuine circular-import TDZ hazard, not merely a style preference.
+*/
+/** The three-valued AND table: `false` is absorbing regardless of the other operand's indeterminacy; otherwise both-definite folds to a boolean AND; otherwise indeterminate, with the tie-break rule (declared operand order, left before right) applied via `firstIndeterminate`. */
+function combineAnd(left, right) {
+	if (left.status === "definite" && !left.value) return require_evaluation.definite(false);
+	if (right.status === "definite" && !right.value) return require_evaluation.definite(false);
+	const reason = require_evaluation.firstIndeterminate(left, right);
+	if (reason !== void 0) return {
+		status: "indeterminate",
+		reason
+	};
+	return require_evaluation.definite(true);
+}
+/** The three-valued OR table: mirror image of `combineAnd`, with `true` absorbing. */
+function combineOr(left, right) {
+	if (left.status === "definite" && left.value) return require_evaluation.definite(true);
+	if (right.status === "definite" && right.value) return require_evaluation.definite(true);
+	const reason = require_evaluation.firstIndeterminate(left, right);
+	if (reason !== void 0) return {
+		status: "indeterminate",
+		reason
+	};
+	return require_evaluation.definite(false);
+}
+function applyComparisonOperator(op, left, right) {
+	switch (op) {
+		case "gt": return left > right;
+		case "gte": return left >= right;
+		case "lt": return left < right;
+		case "lte": return left <= right;
+		case "eq": return left === right;
+		case "neq": return left !== right;
+		default: throw new Error("unreachable comparison operator");
+	}
+}
+const millisecondsPerDurationUnit = {
+	ms: 1,
+	s: 1e3,
+	min: 6e4,
+	h: 36e5,
+	d: 864e5
+};
+/** Normalises a `duration`'s magnitude to milliseconds, the common base unit for combining or comparing two `duration`s (or an `instant` and a `duration`) of potentially different `DurationUnit`s -- shared by `compareValues`'s own `duration` branch below and by the temporal arithmetic further down. */
+function toMilliseconds(value, unit) {
+	return value * millisecondsPerDurationUnit[unit];
+}
+/** `Date.parse` reports an unparseable timestamp as `NaN`, and every downstream use of that `NaN` then fails silently rather than loudly: every comparison against it is `false` (so `neq` between two unparseable instants would come back definitely `true`), a subtraction yields a `NaN`-magnitude duration, and `new Date(NaN).toISOString()` throws a `RangeError` outright -- a thrown exception for a data-quality problem, which this design never does (see `Evaluation<T>`'s own doc comment in evaluation.ts). An `instant` whose string will not parse is a value the operation cannot use, so every caller below reports it as `wrong-type`, exactly like any other unusable operand. */
+function toEpochMilliseconds(value) {
+	const epochMilliseconds = Date.parse(value);
+	return Number.isNaN(epochMilliseconds) ? void 0 : epochMilliseconds;
+}
+function unparseableInstant(value) {
+	return require_evaluation.indeterminate("wrong-type", `'${value}' is not a parseable ISO-8601 timestamp`);
+}
+/** The representable timestamp range is finite, so a valid instant shifted by a large enough duration lands outside it, where `new Date(...).toISOString()` throws a `RangeError`. Checking the shifted date against the platform's own notion of a valid time value keeps that inside the three-outcome model as a `domain-error` -- an operation pushed outside its valid domain, the same category as division by zero -- and avoids hardcoding the range bound. */
+function instantFromEpochMilliseconds(epochMilliseconds) {
+	const shifted = new Date(epochMilliseconds);
+	if (Number.isNaN(shifted.getTime())) return require_evaluation.indeterminate("domain-error", "the resulting instant falls outside the representable timestamp range");
+	return require_evaluation.definite({
+		kind: "instant",
+		value: shifted.toISOString()
+	});
+}
+/** `compare`'s two operands: valid kinds are `number` (matching units required), `instant` (ordered by parsed epoch millisecond), or `duration` (ordered by magnitude normalised to milliseconds) -- `text` is never valid here (see `textCompare`), and a kind mismatch between the two operands is `wrong-type`. Narrowing `right` against a literal `left.kind` case (rather than asserting it) is what lets both sides stay properly typed with no `as`. */
+function compareValues(op, left, right) {
+	switch (left.kind) {
+		case "number":
+			if (right.kind !== "number") return require_evaluation.indeterminate("wrong-type", `cannot compare a 'number' value with a '${right.kind}' value`);
+			if (!require_computed_value.unitsEqual(left.unit, right.unit)) return require_evaluation.indeterminate("wrong-type", "cannot compare numbers with incompatible units");
+			return require_evaluation.definite(applyComparisonOperator(op, left.value, right.value));
+		case "text": return require_evaluation.indeterminate("wrong-type", "text values are not comparable via 'compare'; use 'textCompare'");
+		case "instant": {
+			if (right.kind !== "instant") return require_evaluation.indeterminate("wrong-type", `cannot compare an 'instant' value with a '${right.kind}' value`);
+			const leftEpoch = toEpochMilliseconds(left.value);
+			if (leftEpoch === void 0) return unparseableInstant(left.value);
+			const rightEpoch = toEpochMilliseconds(right.value);
+			if (rightEpoch === void 0) return unparseableInstant(right.value);
+			return require_evaluation.definite(applyComparisonOperator(op, leftEpoch, rightEpoch));
+		}
+		case "duration":
+			if (right.kind !== "duration") return require_evaluation.indeterminate("wrong-type", `cannot compare a 'duration' value with a '${right.kind}' value`);
+			return require_evaluation.definite(applyComparisonOperator(op, toMilliseconds(left.value, left.unit), toMilliseconds(right.value, right.unit)));
+		default: throw new Error("unreachable computed-value kind");
+	}
+}
+/** `textCompare`'s two operands must both resolve to the `text` computed-value kind -- any other kind, on either operand, is `wrong-type` (see the `textCompare` section of README.md). `equals`/`notEquals` are exact string equality; `matches`/`notMatches` interpret `right`'s text as an ECMAScript regular expression tested against `left`'s text. An invalid pattern is `wrong-type` rather than a thrown exception -- every data-quality problem stays inside the `Evaluation` result, per `Evaluation<T>`'s own doc comment in evaluation.ts. */
+function compareText(op, left, right) {
+	if (left.kind !== "text") return require_evaluation.indeterminate("wrong-type", `'textCompare' requires 'text' operands; the left operand is '${left.kind}'`);
+	if (right.kind !== "text") return require_evaluation.indeterminate("wrong-type", `'textCompare' requires 'text' operands; the right operand is '${right.kind}'`);
+	switch (op) {
+		case "equals": return require_evaluation.definite(left.value === right.value);
+		case "notEquals": return require_evaluation.definite(left.value !== right.value);
+		case "matches":
+		case "notMatches": {
+			let pattern;
+			try {
+				pattern = new RegExp(right.value);
+			} catch {
+				return require_evaluation.indeterminate("wrong-type", `'${right.value}' is not a valid regular expression pattern`);
+			}
+			const isMatch = pattern.test(left.value);
+			return require_evaluation.definite(op === "matches" ? isMatch : !isMatch);
+		}
+		default: throw new Error("unreachable text comparison operator");
+	}
+}
+/** `memberOf`'s own value-equality test between two computed values -- kind-agnostic across `number`/`text`/`instant`/`duration` (see the `memberOf` section of README.md, and its "Derived aggregates" note that this equality is kind-agnostic across every computed-value kind), unlike `compare`'s own `eq`, which rejects a `text` operand outright and directs callers to `textCompare` instead. A kind mismatch, or a `number` pair with an incompatible unit, is `wrong-type` -- never simply "not equal". Narrowing `candidate` against a literal `operand.kind` case (rather than asserting it) is the same technique `compareValues` uses above. */
+function computeMembershipMatch(operand, candidate) {
+	switch (operand.kind) {
+		case "number":
+			if (candidate.kind !== "number") return require_evaluation.indeterminate("wrong-type", `cannot compare a 'number' value with a '${candidate.kind}' value for membership`);
+			if (!require_computed_value.unitsEqual(operand.unit, candidate.unit)) return require_evaluation.indeterminate("wrong-type", "cannot compare numbers with incompatible units for membership");
+			return require_evaluation.definite(operand.value === candidate.value);
+		case "text":
+			if (candidate.kind !== "text") return require_evaluation.indeterminate("wrong-type", `cannot compare a 'text' value with a '${candidate.kind}' value for membership`);
+			return require_evaluation.definite(operand.value === candidate.value);
+		case "instant": {
+			if (candidate.kind !== "instant") return require_evaluation.indeterminate("wrong-type", `cannot compare an 'instant' value with a '${candidate.kind}' value for membership`);
+			const operandEpoch = toEpochMilliseconds(operand.value);
+			if (operandEpoch === void 0) return unparseableInstant(operand.value);
+			const candidateEpoch = toEpochMilliseconds(candidate.value);
+			if (candidateEpoch === void 0) return unparseableInstant(candidate.value);
+			return require_evaluation.definite(operandEpoch === candidateEpoch);
+		}
+		case "duration":
+			if (candidate.kind !== "duration") return require_evaluation.indeterminate("wrong-type", `cannot compare a 'duration' value with a '${candidate.kind}' value for membership`);
+			return require_evaluation.definite(toMilliseconds(operand.value, operand.unit) === toMilliseconds(candidate.value, candidate.unit));
+		default: throw new Error("unreachable computed-value kind");
+	}
+}
+/** `power`/`modulo` have no defined unit-combination rule in this design (unlike `add`/`subtract`'s "identical units" requirement or `multiply`/`divide`'s dimensional-exponent combination) -- scoping them to dimensionless operands avoids inventing an unspecified unit-scaling semantics for a fractional or runtime-determined exponent. */
+function isDimensionless(unit) {
+	return require_computed_value.unitsEqual(unit, void 0);
+}
+/** `negate` is never sugar for "zero minus the value" (see the `arithmetic`/`negate` section of README.md) -- a `duration`'s magnitude is negated directly, in its own original unit, with no subtraction or millisecond normalisation involved. */
+function applyNegate(operand) {
+	switch (operand.kind) {
+		case "number": return require_evaluation.definite({
+			kind: "number",
+			value: -operand.value,
+			unit: operand.unit
+		});
+		case "duration": return require_evaluation.definite({
+			kind: "duration",
+			value: -operand.value,
+			unit: operand.unit
+		});
+		case "text":
+		case "instant": return require_evaluation.indeterminate("wrong-type", `cannot negate a '${operand.kind}' value`);
+		default: throw new Error("unreachable computed-value kind");
+	}
+}
+function applyArithmeticOnNumbers(op, left, right) {
+	switch (op) {
+		case "add":
+			if (!require_computed_value.unitsEqual(left.unit, right.unit)) return require_evaluation.indeterminate("wrong-type", "cannot add numbers with incompatible units");
+			return require_evaluation.definite({
+				kind: "number",
+				value: left.value + right.value,
+				unit: left.unit
+			});
+		case "subtract":
+			if (!require_computed_value.unitsEqual(left.unit, right.unit)) return require_evaluation.indeterminate("wrong-type", "cannot subtract numbers with incompatible units");
+			return require_evaluation.definite({
+				kind: "number",
+				value: left.value - right.value,
+				unit: left.unit
+			});
+		case "multiply": return require_evaluation.definite({
+			kind: "number",
+			value: left.value * right.value,
+			unit: require_computed_value.combineUnitsForMultiply(left.unit, right.unit)
+		});
+		case "divide":
+			if (right.value === 0) return require_evaluation.indeterminate("domain-error", "division by zero");
+			return require_evaluation.definite({
+				kind: "number",
+				value: left.value / right.value,
+				unit: require_computed_value.combineUnitsForDivide(left.unit, right.unit)
+			});
+		case "power":
+			if (!isDimensionless(left.unit) || !isDimensionless(right.unit)) return require_evaluation.indeterminate("wrong-type", "'power' requires dimensionless operands");
+			if (left.value < 0 && !Number.isInteger(right.value)) return require_evaluation.indeterminate("domain-error", "a negative base raised to a non-integer power is not a real number");
+			if (left.value === 0 && right.value < 0) return require_evaluation.indeterminate("domain-error", "zero raised to a negative power is a division by zero");
+			return require_evaluation.definite({
+				kind: "number",
+				value: left.value ** right.value
+			});
+		case "modulo":
+			if (!isDimensionless(left.unit) || !isDimensionless(right.unit)) return require_evaluation.indeterminate("wrong-type", "'modulo' requires dimensionless operands");
+			if (right.value === 0) return require_evaluation.indeterminate("domain-error", "modulo by zero");
+			return require_evaluation.definite({
+				kind: "number",
+				value: left.value % right.value
+			});
+		default: throw new Error("unreachable arithmetic operator");
+	}
+}
+/** The only same-kind, non-`number` arithmetic this design defines: two `duration`s combine by normalising both to milliseconds first (see `toMilliseconds`), reporting the result in milliseconds -- `multiply`/`divide`/`power`/`modulo` have no representable result unit for a `duration` squared or a dimensionless ratio, so they are `wrong-type` rather than invented. */
+function applyArithmeticOnDurations(op, left, right) {
+	switch (op) {
+		case "add": return require_evaluation.definite({
+			kind: "duration",
+			value: toMilliseconds(left.value, left.unit) + toMilliseconds(right.value, right.unit),
+			unit: "ms"
+		});
+		case "subtract": return require_evaluation.definite({
+			kind: "duration",
+			value: toMilliseconds(left.value, left.unit) - toMilliseconds(right.value, right.unit),
+			unit: "ms"
+		});
+		case "multiply":
+		case "divide":
+		case "power":
+		case "modulo": return require_evaluation.indeterminate("wrong-type", `arithmetic operator '${op}' is not defined between two 'duration' values`);
+		default: throw new Error("unreachable arithmetic operator");
+	}
+}
+/**
+* Dispatches `arithmetic` by operand kind. The three cross-kind temporal combinations this design defines (`instant - instant`, `instant + duration`, `duration + instant`) are checked explicitly first, in that order, against the exact operator each requires; any other combination touching an `instant` is `wrong-type` (see "Temporal values" in README.md -- e.g. adding two instants, or subtracting a `duration` from an `instant`, are deliberately *not* defined). Same-kind `duration`/`duration` combinations are delegated to `applyArithmeticOnDurations`; a `duration` paired with anything other than an `instant` or another `duration` is `wrong-type`. Everything remaining requires two `number` operands.
+*/
+function applyArithmetic(op, left, right) {
+	if (left.kind === "instant" && right.kind === "instant" && op === "subtract") {
+		const leftEpoch = toEpochMilliseconds(left.value);
+		if (leftEpoch === void 0) return unparseableInstant(left.value);
+		const rightEpoch = toEpochMilliseconds(right.value);
+		if (rightEpoch === void 0) return unparseableInstant(right.value);
+		return require_evaluation.definite({
+			kind: "duration",
+			value: leftEpoch - rightEpoch,
+			unit: "ms"
+		});
+	}
+	if (left.kind === "instant" && right.kind === "duration" && op === "add") {
+		const leftEpoch = toEpochMilliseconds(left.value);
+		if (leftEpoch === void 0) return unparseableInstant(left.value);
+		return instantFromEpochMilliseconds(leftEpoch + toMilliseconds(right.value, right.unit));
+	}
+	if (left.kind === "duration" && right.kind === "instant" && op === "add") {
+		const rightEpoch = toEpochMilliseconds(right.value);
+		if (rightEpoch === void 0) return unparseableInstant(right.value);
+		return instantFromEpochMilliseconds(rightEpoch + toMilliseconds(left.value, left.unit));
+	}
+	if (left.kind === "instant" || right.kind === "instant") return require_evaluation.indeterminate("wrong-type", `arithmetic operator '${op}' is not defined between a '${left.kind}' and a '${right.kind}' value`);
+	if (left.kind === "duration" && right.kind === "duration") return applyArithmeticOnDurations(op, left, right);
+	if (left.kind === "duration" || right.kind === "duration") return require_evaluation.indeterminate("wrong-type", `arithmetic operator '${op}' is not defined between a '${left.kind}' and a '${right.kind}' value`);
+	if (left.kind !== "number") return require_evaluation.indeterminate("wrong-type", `arithmetic requires numeric operands; got a '${left.kind}' value`);
+	if (right.kind !== "number") return require_evaluation.indeterminate("wrong-type", `arithmetic requires numeric operands; got a '${right.kind}' value`);
+	return applyArithmeticOnNumbers(op, left, right);
+}
+/**
+* Collection resolution shared by the quantifiers (`some`/`every`, below) and by `fold` (a later phase): resolves the opaque `collection` reference to its concrete candidate list via `resolvers.resolveCollection`, then evaluates each candidate's optional `filter` with that candidate as its own evaluation context and the accumulator reset to `undefined` -- see the README's "Evaluation context" and "Pre-filtering which items participate" sections. Deliberately stops short of deciding how an indeterminate filter combines with the rest of the surrounding node: `some`/`every` fold a filter-indeterminate item in as its own vote via the surrounding OR/AND absorption, while `fold` has no absorbing value at all and goes indeterminate outright on the same condition -- the two callers need genuinely different combination logic over these same per-item outcomes, so this helper only produces the outcomes and leaves combining them to the caller.
+*/
+async function resolveParticipatingItems(collection, filter, context, resolvers, functions) {
+	const candidates = await resolvers.resolveCollection(collection, context);
+	return Promise.all(candidates.map(async (item) => {
+		if (filter === void 0) return {
+			item,
+			filterOutcome: "include"
+		};
+		const filterResult = await evaluatePredicateInternal(filter, item, resolvers, void 0, functions);
+		if (filterResult.status === "indeterminate") return {
+			item,
+			filterOutcome: filterResult
+		};
+		return {
+			item,
+			filterOutcome: filterResult.value ? "include" : "exclude"
+		};
+	}));
+}
+/** The first participating item (in declared collection order) whose `filter` evaluation was itself indeterminate, or `undefined` if every participating item's filter resolved definitely -- a filter-excluded item's own `"exclude"` outcome never counts here. Used only by `fold`, which -- unlike `some`/`every`'s OR/AND absorption -- has no absorbing value at all: any participating item's indeterminate filter makes the whole fold indeterminate outright, with no other item's outcome able to override it. */
+function firstFilterIndeterminate(participating) {
+	for (const { filterOutcome } of participating) {
+		if (filterOutcome === "include" || filterOutcome === "exclude") continue;
+		if (filterOutcome.status === "indeterminate") return filterOutcome.reason;
+	}
+}
+async function evaluatePredicateInternal(node, context, resolvers, accumulator, functions) {
+	switch (node.kind) {
+		case "not": {
+			const operand = await evaluatePredicateInternal(node.operand, context, resolvers, accumulator, functions);
+			if (operand.status === "indeterminate") return operand;
+			return require_evaluation.definite(!operand.value);
+		}
+		case "and": {
+			const [left, right] = await Promise.all([evaluatePredicateInternal(node.left, context, resolvers, accumulator, functions), evaluatePredicateInternal(node.right, context, resolvers, accumulator, functions)]);
+			return combineAnd(left, right);
+		}
+		case "or": {
+			const [left, right] = await Promise.all([evaluatePredicateInternal(node.left, context, resolvers, accumulator, functions), evaluatePredicateInternal(node.right, context, resolvers, accumulator, functions)]);
+			return combineOr(left, right);
+		}
+		case "allOf": return (await Promise.all(node.operands.map(async (operand) => evaluatePredicateInternal(operand, context, resolvers, accumulator, functions)))).reduce(combineAnd, require_evaluation.definite(true));
+		case "anyOf": return (await Promise.all(node.operands.map(async (operand) => evaluatePredicateInternal(operand, context, resolvers, accumulator, functions)))).reduce(combineOr, require_evaluation.definite(false));
+		case "compare": {
+			const [left, right] = await Promise.all([evaluateValueInternal(node.left, context, resolvers, accumulator, functions), evaluateValueInternal(node.right, context, resolvers, accumulator, functions)]);
+			if (left.status === "indeterminate") return left;
+			if (right.status === "indeterminate") return right;
+			return compareValues(node.op, left.value, right.value);
+		}
+		case "textCompare": {
+			const [left, right] = await Promise.all([evaluateValueInternal(node.left, context, resolvers, accumulator, functions), evaluateValueInternal(node.right, context, resolvers, accumulator, functions)]);
+			if (left.status === "indeterminate") return left;
+			if (right.status === "indeterminate") return right;
+			return compareText(node.op, left.value, right.value);
+		}
+		case "memberOf": {
+			const operandResult = await evaluateValueInternal(node.operand, context, resolvers, accumulator, functions);
+			if (operandResult.status === "indeterminate") return operandResult;
+			const candidateOutcomes = await Promise.all(node.candidates.map(async (candidate) => {
+				const candidateResult = await evaluateValueInternal(candidate, context, resolvers, accumulator, functions);
+				if (candidateResult.status === "indeterminate") return candidateResult;
+				return computeMembershipMatch(operandResult.value, candidateResult.value);
+			}));
+			for (const outcome of candidateOutcomes) if (outcome.status === "definite" && outcome.value) return require_evaluation.definite(node.op === "in");
+			const reason = require_evaluation.firstIndeterminate(...candidateOutcomes);
+			if (reason !== void 0) return {
+				status: "indeterminate",
+				reason
+			};
+			return require_evaluation.definite(node.op === "notIn");
+		}
+		case "exists": {
+			const operandResult = await evaluateValueInternal(node.operand, context, resolvers, accumulator, functions);
+			if (operandResult.status === "indeterminate" && operandResult.reason.code === "not-found") return require_evaluation.definite(false);
+			return require_evaluation.definite(true);
+		}
+		case "some":
+		case "every": {
+			const participating = await resolveParticipatingItems(node.collection, node.filter, context, resolvers, functions);
+			const votes = (await Promise.all(participating.map(async ({ item, filterOutcome }) => {
+				if (filterOutcome === "exclude") return void 0;
+				if (filterOutcome !== "include") return filterOutcome;
+				return evaluatePredicateInternal(node.item, item, resolvers, void 0, functions);
+			}))).filter((vote) => vote !== void 0);
+			const combine = node.kind === "some" ? combineOr : combineAnd;
+			const identity = node.kind === "some" ? require_evaluation.definite(false) : require_evaluation.definite(true);
+			return votes.reduce(combine, identity);
+		}
+		default: throw new Error("unreachable predicate node kind");
+	}
+}
+async function evaluateValueInternal(node, context, resolvers, accumulator, functions) {
+	switch (node.kind) {
+		case "reference": {
+			const resolution = await resolvers.resolveValue(node.key, context);
+			if (!resolution.found) return require_evaluation.indeterminate("not-found", `no value found for reference key ${JSON.stringify(node.key)}`);
+			if (node.unit !== void 0) {
+				if (resolution.value.kind !== "number") return require_evaluation.indeterminate("wrong-type", "a unit was expected on a reference that resolved to a non-numeric value");
+				if (!require_computed_value.unitsEqual(node.unit, resolution.value.unit)) return require_evaluation.indeterminate("wrong-type", "the resolved value's unit does not match the reference's expected unit");
+			}
+			return require_evaluation.definite(resolution.value);
+		}
+		case "accumulator":
+			if (accumulator === void 0) return require_evaluation.indeterminate("wrong-type", "accumulator used outside a reduce fold's combine expression");
+			return require_evaluation.definite(accumulator);
+		case "call": {
+			const argResults = await Promise.all(node.args.map(async (arg) => evaluateValueInternal(arg, context, resolvers, accumulator, functions)));
+			const args = [];
+			for (const result of argResults) {
+				if (result.status === "indeterminate") return result;
+				args.push(result.value);
+			}
+			const fn = Object.hasOwn(functions, node.fn) ? functions[node.fn] : void 0;
+			if (fn === void 0) return require_evaluation.indeterminate("wrong-type", `no function registered under the name '${node.fn}'`);
+			const outcome = fn(args);
+			if ("domainError" in outcome) return require_evaluation.indeterminate("domain-error", outcome.domainError);
+			return require_evaluation.definite(outcome);
+		}
+		case "numberLiteral": return require_evaluation.definite({
+			kind: "number",
+			value: node.value,
+			unit: node.unit
+		});
+		case "textLiteral": return require_evaluation.definite({
+			kind: "text",
+			value: node.value
+		});
+		case "instantLiteral": return require_evaluation.definite({
+			kind: "instant",
+			value: node.value
+		});
+		case "durationLiteral": return require_evaluation.definite({
+			kind: "duration",
+			value: node.value,
+			unit: node.unit
+		});
+		case "arithmetic": {
+			const [left, right] = await Promise.all([evaluateValueInternal(node.left, context, resolvers, accumulator, functions), evaluateValueInternal(node.right, context, resolvers, accumulator, functions)]);
+			if (left.status === "indeterminate") return left;
+			if (right.status === "indeterminate") return right;
+			return applyArithmetic(node.op, left.value, right.value);
+		}
+		case "negate": {
+			const operand = await evaluateValueInternal(node.operand, context, resolvers, accumulator, functions);
+			if (operand.status === "indeterminate") return operand;
+			return applyNegate(operand.value);
+		}
+		case "lookup": {
+			const keyResults = await Promise.all(node.keys.map(async (key) => evaluateValueInternal(key, context, resolvers, accumulator, functions)));
+			const keyValues = [];
+			for (const result of keyResults) {
+				if (result.status === "indeterminate") return result;
+				keyValues.push(result.value);
+			}
+			const resolution = await resolvers.resolveLookup(node.table, keyValues, context);
+			if (!resolution.found) return require_evaluation.indeterminate("not-found", `no match found in lookup table ${JSON.stringify(node.table)}`);
+			return require_evaluation.definite(resolution.value);
+		}
+		case "conditional":
+			for (const { when, then } of node.cases) {
+				const whenResult = await evaluatePredicateInternal(when, context, resolvers, accumulator, functions);
+				if (whenResult.status === "indeterminate") return whenResult;
+				if (whenResult.value) return evaluateValueInternal(then, context, resolvers, accumulator, functions);
+			}
+			return evaluateValueInternal(node.fallback, context, resolvers, accumulator, functions);
+		case "fold": {
+			const participating = await resolveParticipatingItems(node.collection, node.filter, context, resolvers, functions);
+			const filterIndeterminateReason = firstFilterIndeterminate(participating);
+			if (filterIndeterminateReason !== void 0) return {
+				status: "indeterminate",
+				reason: filterIndeterminateReason
+			};
+			const includedItems = participating.filter(({ filterOutcome }) => filterOutcome === "include").map(({ item }) => item);
+			if (node.combiner.mode === "reduce") {
+				const initialResult = await evaluateValueInternal(node.combiner.initial, context, resolvers, void 0, functions);
+				if (initialResult.status === "indeterminate") return initialResult;
+				let runningAccumulator = initialResult.value;
+				for (const item of includedItems) {
+					const stepResult = await evaluateValueInternal(node.combiner.combine, item, resolvers, runningAccumulator, functions);
+					if (stepResult.status === "indeterminate") return stepResult;
+					runningAccumulator = stepResult.value;
+				}
+				return require_evaluation.definite(runningAccumulator);
+			}
+			if (includedItems.length === 0) return require_evaluation.indeterminate("domain-error", `'${node.combiner.mode}' has no participating items to seed a running result from`);
+			const dominatesOp = node.combiner.mode === "max" ? "gt" : "lt";
+			let runningExtremum;
+			for (const item of includedItems) {
+				const itemResult = await evaluateValueInternal(node.combiner.item, item, resolvers, void 0, functions);
+				if (itemResult.status === "indeterminate") return itemResult;
+				if (runningExtremum === void 0) {
+					runningExtremum = itemResult.value;
+					continue;
+				}
+				const comparison = compareValues(dominatesOp, itemResult.value, runningExtremum);
+				if (comparison.status === "indeterminate") return comparison;
+				if (comparison.value) runningExtremum = itemResult.value;
+			}
+			if (runningExtremum === void 0) throw new Error("unreachable: max/min over a non-empty participating list produced no running result");
+			return require_evaluation.definite(runningExtremum);
+		}
+		case "delegate": {
+			if (resolvers.resolveDelegate === void 0) return require_evaluation.indeterminate("wrong-type", `no delegate handler registered for external system '${node.system}'`);
+			const resolution = await resolvers.resolveDelegate(node.system, node.payload, context);
+			if (!resolution.found) return require_evaluation.indeterminate("not-found", `delegate handler for external system '${node.system}' reported no value`);
+			return require_evaluation.definite(resolution.value);
+		}
+		default: throw new Error("unreachable expression node kind");
+	}
+}
+/**
+* Builds a bound `{ evaluatePredicate, evaluateValue }` pair over a caller-supplied function registry for `call` nodes -- the registry is bound once, at construction time, unlike `resolvers`, which are supplied fresh to every call. The bare module-level `evaluatePredicate`/`evaluateValue` exports below are `createEvaluator({})`'s output.
+*/
+function createEvaluator({ functions = require_functions.emptyFunctionRegistry }) {
+	return {
+		evaluatePredicate: async (node, context, resolvers) => evaluatePredicateInternal(node, context, resolvers, void 0, functions),
+		evaluateValue: async (node, context, resolvers) => evaluateValueInternal(node, context, resolvers, void 0, functions)
+	};
+}
+const { evaluatePredicate, evaluateValue } = createEvaluator({});
+//#endregion
+exports.createEvaluator = createEvaluator;
+exports.evaluatePredicate = evaluatePredicate;
+exports.evaluateValue = evaluateValue;

package/dist/evaluator.d.cts

@@ -0,0 +1,18 @@
+import { ComputedValue } from "./computed-value.cjs";
+import { ExpressionNode, PredicateNode } from "./tree.cjs";
+import { Evaluation } from "./evaluation.cjs";
+import { FunctionRegistry } from "./functions.cjs";
+import { EvaluationContext, Resolvers } from "./resolvers.cjs";
+//#region src/evaluator.d.ts
+/**
+ * Builds a bound `{ evaluatePredicate, evaluateValue }` pair over a caller-supplied function registry for `call` nodes -- the registry is bound once, at construction time, unlike `resolvers`, which are supplied fresh to every call. The bare module-level `evaluatePredicate`/`evaluateValue` exports below are `createEvaluator({})`'s output.
+ */
+declare function createEvaluator({ functions }: {
+  functions?: FunctionRegistry;
+}): {
+  evaluatePredicate: (node: PredicateNode, context: EvaluationContext, resolvers: Readonly<Resolvers>) => Promise<Evaluation<boolean>>;
+  evaluateValue: (node: ExpressionNode, context: EvaluationContext, resolvers: Readonly<Resolvers>) => Promise<Evaluation<ComputedValue>>;
+};
+declare const evaluatePredicate: (node: PredicateNode, context: EvaluationContext, resolvers: Readonly<Resolvers>) => Promise<Evaluation<boolean>>, evaluateValue: (node: ExpressionNode, context: EvaluationContext, resolvers: Readonly<Resolvers>) => Promise<Evaluation<ComputedValue>>;
+//#endregion
+export { createEvaluator, evaluatePredicate, evaluateValue };

package/dist/evaluator.d.ts

@@ -0,0 +1,18 @@
+import { ComputedValue } from "./computed-value.js";
+import { ExpressionNode, PredicateNode } from "./tree.js";
+import { Evaluation } from "./evaluation.js";
+import { FunctionRegistry } from "./functions.js";
+import { EvaluationContext, Resolvers } from "./resolvers.js";
+//#region src/evaluator.d.ts
+/**
+ * Builds a bound `{ evaluatePredicate, evaluateValue }` pair over a caller-supplied function registry for `call` nodes -- the registry is bound once, at construction time, unlike `resolvers`, which are supplied fresh to every call. The bare module-level `evaluatePredicate`/`evaluateValue` exports below are `createEvaluator({})`'s output.
+ */
+declare function createEvaluator({ functions }: {
+  functions?: FunctionRegistry;
+}): {
+  evaluatePredicate: (node: PredicateNode, context: EvaluationContext, resolvers: Readonly<Resolvers>) => Promise<Evaluation<boolean>>;
+  evaluateValue: (node: ExpressionNode, context: EvaluationContext, resolvers: Readonly<Resolvers>) => Promise<Evaluation<ComputedValue>>;
+};
+declare const evaluatePredicate: (node: PredicateNode, context: EvaluationContext, resolvers: Readonly<Resolvers>) => Promise<Evaluation<boolean>>, evaluateValue: (node: ExpressionNode, context: EvaluationContext, resolvers: Readonly<Resolvers>) => Promise<Evaluation<ComputedValue>>;
+//#endregion
+export { createEvaluator, evaluatePredicate, evaluateValue };