trilean 0.0.0 → 1.0.0

package/dist/computed-value.cjs

@@ -0,0 +1,71 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let zod = require("zod");
+//#region src/computed-value.ts
+/** Dimension symbol -> exponent, e.g. `{ m: 1, s: -1 }` for metres per second. A bare symbol like `"kg"` is shorthand for `{ kg: 1 }`. */
+const UnitSchema = zod.z.record(zod.z.string(), zod.z.number());
+const DurationUnitSchema = zod.z.enum([
+	"ms",
+	"s",
+	"min",
+	"h",
+	"d"
+]);
+const ComputedValueSchema = zod.z.discriminatedUnion("kind", [
+	zod.z.object({
+		kind: zod.z.literal("number"),
+		value: zod.z.number(),
+		unit: UnitSchema.optional()
+	}),
+	zod.z.object({
+		kind: zod.z.literal("text"),
+		value: zod.z.string()
+	}),
+	zod.z.object({
+		kind: zod.z.literal("instant"),
+		value: zod.z.string()
+	}),
+	zod.z.object({
+		kind: zod.z.literal("duration"),
+		value: zod.z.number(),
+		unit: DurationUnitSchema
+	})
+]);
+/** Drops zero-exponent dimensions so that, e.g., dividing a unit by itself normalises to the same dimensionless `{}` as an absent unit -- without this, `{ m: 0 }` and `{}` would compare unequal despite representing the same dimension. */
+function normalizeUnit(unit) {
+	if (unit === void 0) return {};
+	const normalized = {};
+	for (const [dimension, exponent] of Object.entries(unit)) if (exponent !== 0) normalized[dimension] = exponent;
+	return normalized;
+}
+/** An operand with no `unit` is dimensionless (an empty map) for comparison purposes. */
+function unitsEqual(a, b) {
+	const normalizedA = normalizeUnit(a);
+	const normalizedB = normalizeUnit(b);
+	const dimensionsA = Object.keys(normalizedA);
+	const dimensionsB = Object.keys(normalizedB);
+	if (dimensionsA.length !== dimensionsB.length) return false;
+	return dimensionsA.every((dimension) => normalizedA[dimension] === normalizedB[dimension]);
+}
+/** Multiplying two unit-tagged numbers adds exponents per dimension. An operand with no `unit` is treated as dimensionless (an empty map). */
+function combineUnitsForMultiply(a, b) {
+	const normalizedA = normalizeUnit(a);
+	const normalizedB = normalizeUnit(b);
+	const combined = { ...normalizedA };
+	for (const [dimension, exponent] of Object.entries(normalizedB)) combined[dimension] = (combined[dimension] ?? 0) + exponent;
+	return normalizeUnit(combined);
+}
+/** Dividing two unit-tagged numbers subtracts exponents per dimension. An operand with no `unit` is treated as dimensionless (an empty map). */
+function combineUnitsForDivide(a, b) {
+	const normalizedA = normalizeUnit(a);
+	const normalizedB = normalizeUnit(b);
+	const combined = { ...normalizedA };
+	for (const [dimension, exponent] of Object.entries(normalizedB)) combined[dimension] = (combined[dimension] ?? 0) - exponent;
+	return normalizeUnit(combined);
+}
+//#endregion
+exports.ComputedValueSchema = ComputedValueSchema;
+exports.DurationUnitSchema = DurationUnitSchema;
+exports.UnitSchema = UnitSchema;
+exports.combineUnitsForDivide = combineUnitsForDivide;
+exports.combineUnitsForMultiply = combineUnitsForMultiply;
+exports.unitsEqual = unitsEqual;

package/dist/computed-value.d.cts

@@ -0,0 +1,43 @@
+import { z } from "zod";
+//#region src/computed-value.d.ts
+/** Dimension symbol -> exponent, e.g. `{ m: 1, s: -1 }` for metres per second. A bare symbol like `"kg"` is shorthand for `{ kg: 1 }`. */
+declare const UnitSchema: z.ZodRecord<z.ZodString, z.ZodNumber>;
+type Unit = z.infer<typeof UnitSchema>;
+declare const DurationUnitSchema: z.ZodEnum<{
+  ms: "ms";
+  s: "s";
+  min: "min";
+  h: "h";
+  d: "d";
+}>;
+type DurationUnit = z.infer<typeof DurationUnitSchema>;
+declare const ComputedValueSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+  kind: z.ZodLiteral<"number">;
+  value: z.ZodNumber;
+  unit: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+}, z.core.$strip>, z.ZodObject<{
+  kind: z.ZodLiteral<"text">;
+  value: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+  kind: z.ZodLiteral<"instant">;
+  value: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+  kind: z.ZodLiteral<"duration">;
+  value: z.ZodNumber;
+  unit: z.ZodEnum<{
+    ms: "ms";
+    s: "s";
+    min: "min";
+    h: "h";
+    d: "d";
+  }>;
+}, z.core.$strip>], "kind">;
+type ComputedValue = z.infer<typeof ComputedValueSchema>;
+/** An operand with no `unit` is dimensionless (an empty map) for comparison purposes. */
+declare function unitsEqual(a: Unit | undefined, b: Unit | undefined): boolean;
+/** Multiplying two unit-tagged numbers adds exponents per dimension. An operand with no `unit` is treated as dimensionless (an empty map). */
+declare function combineUnitsForMultiply(a: Unit | undefined, b: Unit | undefined): Unit;
+/** Dividing two unit-tagged numbers subtracts exponents per dimension. An operand with no `unit` is treated as dimensionless (an empty map). */
+declare function combineUnitsForDivide(a: Unit | undefined, b: Unit | undefined): Unit;
+//#endregion
+export { ComputedValue, ComputedValueSchema, DurationUnit, DurationUnitSchema, Unit, UnitSchema, combineUnitsForDivide, combineUnitsForMultiply, unitsEqual };

package/dist/computed-value.d.ts

@@ -0,0 +1,43 @@
+import { z } from "zod";
+//#region src/computed-value.d.ts
+/** Dimension symbol -> exponent, e.g. `{ m: 1, s: -1 }` for metres per second. A bare symbol like `"kg"` is shorthand for `{ kg: 1 }`. */
+declare const UnitSchema: z.ZodRecord<z.ZodString, z.ZodNumber>;
+type Unit = z.infer<typeof UnitSchema>;
+declare const DurationUnitSchema: z.ZodEnum<{
+  ms: "ms";
+  s: "s";
+  min: "min";
+  h: "h";
+  d: "d";
+}>;
+type DurationUnit = z.infer<typeof DurationUnitSchema>;
+declare const ComputedValueSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+  kind: z.ZodLiteral<"number">;
+  value: z.ZodNumber;
+  unit: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+}, z.core.$strip>, z.ZodObject<{
+  kind: z.ZodLiteral<"text">;
+  value: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+  kind: z.ZodLiteral<"instant">;
+  value: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+  kind: z.ZodLiteral<"duration">;
+  value: z.ZodNumber;
+  unit: z.ZodEnum<{
+    ms: "ms";
+    s: "s";
+    min: "min";
+    h: "h";
+    d: "d";
+  }>;
+}, z.core.$strip>], "kind">;
+type ComputedValue = z.infer<typeof ComputedValueSchema>;
+/** An operand with no `unit` is dimensionless (an empty map) for comparison purposes. */
+declare function unitsEqual(a: Unit | undefined, b: Unit | undefined): boolean;
+/** Multiplying two unit-tagged numbers adds exponents per dimension. An operand with no `unit` is treated as dimensionless (an empty map). */
+declare function combineUnitsForMultiply(a: Unit | undefined, b: Unit | undefined): Unit;
+/** Dividing two unit-tagged numbers subtracts exponents per dimension. An operand with no `unit` is treated as dimensionless (an empty map). */
+declare function combineUnitsForDivide(a: Unit | undefined, b: Unit | undefined): Unit;
+//#endregion
+export { ComputedValue, ComputedValueSchema, DurationUnit, DurationUnitSchema, Unit, UnitSchema, combineUnitsForDivide, combineUnitsForMultiply, unitsEqual };

package/dist/computed-value.js

@@ -0,0 +1,65 @@
+import { z } from "zod";
+//#region src/computed-value.ts
+/** Dimension symbol -> exponent, e.g. `{ m: 1, s: -1 }` for metres per second. A bare symbol like `"kg"` is shorthand for `{ kg: 1 }`. */
+const UnitSchema = z.record(z.string(), z.number());
+const DurationUnitSchema = z.enum([
+	"ms",
+	"s",
+	"min",
+	"h",
+	"d"
+]);
+const ComputedValueSchema = z.discriminatedUnion("kind", [
+	z.object({
+		kind: z.literal("number"),
+		value: z.number(),
+		unit: UnitSchema.optional()
+	}),
+	z.object({
+		kind: z.literal("text"),
+		value: z.string()
+	}),
+	z.object({
+		kind: z.literal("instant"),
+		value: z.string()
+	}),
+	z.object({
+		kind: z.literal("duration"),
+		value: z.number(),
+		unit: DurationUnitSchema
+	})
+]);
+/** Drops zero-exponent dimensions so that, e.g., dividing a unit by itself normalises to the same dimensionless `{}` as an absent unit -- without this, `{ m: 0 }` and `{}` would compare unequal despite representing the same dimension. */
+function normalizeUnit(unit) {
+	if (unit === void 0) return {};
+	const normalized = {};
+	for (const [dimension, exponent] of Object.entries(unit)) if (exponent !== 0) normalized[dimension] = exponent;
+	return normalized;
+}
+/** An operand with no `unit` is dimensionless (an empty map) for comparison purposes. */
+function unitsEqual(a, b) {
+	const normalizedA = normalizeUnit(a);
+	const normalizedB = normalizeUnit(b);
+	const dimensionsA = Object.keys(normalizedA);
+	const dimensionsB = Object.keys(normalizedB);
+	if (dimensionsA.length !== dimensionsB.length) return false;
+	return dimensionsA.every((dimension) => normalizedA[dimension] === normalizedB[dimension]);
+}
+/** Multiplying two unit-tagged numbers adds exponents per dimension. An operand with no `unit` is treated as dimensionless (an empty map). */
+function combineUnitsForMultiply(a, b) {
+	const normalizedA = normalizeUnit(a);
+	const normalizedB = normalizeUnit(b);
+	const combined = { ...normalizedA };
+	for (const [dimension, exponent] of Object.entries(normalizedB)) combined[dimension] = (combined[dimension] ?? 0) + exponent;
+	return normalizeUnit(combined);
+}
+/** Dividing two unit-tagged numbers subtracts exponents per dimension. An operand with no `unit` is treated as dimensionless (an empty map). */
+function combineUnitsForDivide(a, b) {
+	const normalizedA = normalizeUnit(a);
+	const normalizedB = normalizeUnit(b);
+	const combined = { ...normalizedA };
+	for (const [dimension, exponent] of Object.entries(normalizedB)) combined[dimension] = (combined[dimension] ?? 0) - exponent;
+	return normalizeUnit(combined);
+}
+//#endregion
+export { ComputedValueSchema, DurationUnitSchema, UnitSchema, combineUnitsForDivide, combineUnitsForMultiply, unitsEqual };

package/dist/derived-aggregates.cjs

@@ -0,0 +1,74 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region src/derived-aggregates.ts
+/**
+* `sum`, `count`, and `average` are never their own `FoldCombiner` mode -- each is a builder function that assembles an ordinary `fold` (and, for `average`, one `arithmetic` division of two ordinary folds), exactly the same treatment `derived-connectives.ts` already gives `xor`/`nand`/`nor`/`implies`/`iff`/`none` (see the "Derived aggregates" section of README.md).
+*/
+const sum = (collection, item, filter) => ({
+	kind: "fold",
+	collection,
+	filter,
+	combiner: {
+		mode: "reduce",
+		initial: {
+			kind: "numberLiteral",
+			value: 0
+		},
+		combine: {
+			kind: "arithmetic",
+			op: "add",
+			left: { kind: "accumulator" },
+			right: item
+		}
+	}
+});
+const presenceOf = (probe) => ({
+	kind: "conditional",
+	cases: [{
+		when: {
+			kind: "memberOf",
+			op: "in",
+			operand: probe,
+			candidates: [probe]
+		},
+		then: {
+			kind: "numberLiteral",
+			value: 1
+		}
+	}],
+	fallback: {
+		kind: "numberLiteral",
+		value: 0
+	}
+});
+const count = (collection, filter, probe) => ({
+	kind: "fold",
+	collection,
+	filter,
+	combiner: {
+		mode: "reduce",
+		initial: {
+			kind: "numberLiteral",
+			value: 0
+		},
+		combine: {
+			kind: "arithmetic",
+			op: "add",
+			left: { kind: "accumulator" },
+			right: probe ? presenceOf(probe) : {
+				kind: "numberLiteral",
+				value: 1
+			}
+		}
+	}
+});
+const average = (collection, item, filter) => ({
+	kind: "arithmetic",
+	op: "divide",
+	left: sum(collection, item, filter),
+	right: count(collection, filter)
+});
+//#endregion
+exports.average = average;
+exports.count = count;
+exports.presenceOf = presenceOf;
+exports.sum = sum;

package/dist/derived-aggregates.d.cts

@@ -0,0 +1,12 @@
+import { t as JsonValue } from "./json-value-B1Hjjjri.cjs";
+import { ExpressionNode, PredicateNode } from "./tree.cjs";
+//#region src/derived-aggregates.d.ts
+/**
+ * `sum`, `count`, and `average` are never their own `FoldCombiner` mode -- each is a builder function that assembles an ordinary `fold` (and, for `average`, one `arithmetic` division of two ordinary folds), exactly the same treatment `derived-connectives.ts` already gives `xor`/`nand`/`nor`/`implies`/`iff`/`none` (see the "Derived aggregates" section of README.md).
+ */
+declare const sum: (collection: JsonValue, item: ExpressionNode, filter?: PredicateNode) => ExpressionNode;
+declare const presenceOf: (probe: ExpressionNode) => ExpressionNode;
+declare const count: (collection: JsonValue, filter?: PredicateNode, probe?: ExpressionNode) => ExpressionNode;
+declare const average: (collection: JsonValue, item: ExpressionNode, filter?: PredicateNode) => ExpressionNode;
+//#endregion
+export { average, count, presenceOf, sum };

package/dist/derived-aggregates.d.ts

@@ -0,0 +1,12 @@
+import { t as JsonValue } from "./json-value-B1Hjjjri.js";
+import { ExpressionNode, PredicateNode } from "./tree.js";
+//#region src/derived-aggregates.d.ts
+/**
+ * `sum`, `count`, and `average` are never their own `FoldCombiner` mode -- each is a builder function that assembles an ordinary `fold` (and, for `average`, one `arithmetic` division of two ordinary folds), exactly the same treatment `derived-connectives.ts` already gives `xor`/`nand`/`nor`/`implies`/`iff`/`none` (see the "Derived aggregates" section of README.md).
+ */
+declare const sum: (collection: JsonValue, item: ExpressionNode, filter?: PredicateNode) => ExpressionNode;
+declare const presenceOf: (probe: ExpressionNode) => ExpressionNode;
+declare const count: (collection: JsonValue, filter?: PredicateNode, probe?: ExpressionNode) => ExpressionNode;
+declare const average: (collection: JsonValue, item: ExpressionNode, filter?: PredicateNode) => ExpressionNode;
+//#endregion
+export { average, count, presenceOf, sum };

package/dist/derived-aggregates.js

@@ -0,0 +1,70 @@
+//#region src/derived-aggregates.ts
+/**
+* `sum`, `count`, and `average` are never their own `FoldCombiner` mode -- each is a builder function that assembles an ordinary `fold` (and, for `average`, one `arithmetic` division of two ordinary folds), exactly the same treatment `derived-connectives.ts` already gives `xor`/`nand`/`nor`/`implies`/`iff`/`none` (see the "Derived aggregates" section of README.md).
+*/
+const sum = (collection, item, filter) => ({
+	kind: "fold",
+	collection,
+	filter,
+	combiner: {
+		mode: "reduce",
+		initial: {
+			kind: "numberLiteral",
+			value: 0
+		},
+		combine: {
+			kind: "arithmetic",
+			op: "add",
+			left: { kind: "accumulator" },
+			right: item
+		}
+	}
+});
+const presenceOf = (probe) => ({
+	kind: "conditional",
+	cases: [{
+		when: {
+			kind: "memberOf",
+			op: "in",
+			operand: probe,
+			candidates: [probe]
+		},
+		then: {
+			kind: "numberLiteral",
+			value: 1
+		}
+	}],
+	fallback: {
+		kind: "numberLiteral",
+		value: 0
+	}
+});
+const count = (collection, filter, probe) => ({
+	kind: "fold",
+	collection,
+	filter,
+	combiner: {
+		mode: "reduce",
+		initial: {
+			kind: "numberLiteral",
+			value: 0
+		},
+		combine: {
+			kind: "arithmetic",
+			op: "add",
+			left: { kind: "accumulator" },
+			right: probe ? presenceOf(probe) : {
+				kind: "numberLiteral",
+				value: 1
+			}
+		}
+	}
+});
+const average = (collection, item, filter) => ({
+	kind: "arithmetic",
+	op: "divide",
+	left: sum(collection, item, filter),
+	right: count(collection, filter)
+});
+//#endregion
+export { average, count, presenceOf, sum };

package/dist/derived-connectives.cjs

@@ -0,0 +1,40 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region src/derived-connectives.ts
+/**
+* `not`/`and`/`or` are the primitive `PredicateNode` object-constructors -- everything else in this file is built purely by composing these three, so its three-valued correctness is inherited from the already-verified AND/OR/NOT tables rather than requiring a separate proof (see the "Derived connectives" section of README.md).
+*/
+const not = (a) => ({
+	kind: "not",
+	operand: a
+});
+const and = (a, b) => ({
+	kind: "and",
+	left: a,
+	right: b
+});
+const or = (a, b) => ({
+	kind: "or",
+	left: a,
+	right: b
+});
+const xor = (a, b) => or(and(a, not(b)), and(not(a), b));
+const nand = (a, b) => not(and(a, b));
+const nor = (a, b) => not(or(a, b));
+const implies = (a, b) => or(not(a), b);
+const iff = (a, b) => not(xor(a, b));
+const none = (collection, item, filter) => not({
+	kind: "some",
+	collection,
+	item,
+	filter
+});
+//#endregion
+exports.and = and;
+exports.iff = iff;
+exports.implies = implies;
+exports.nand = nand;
+exports.none = none;
+exports.nor = nor;
+exports.not = not;
+exports.or = or;
+exports.xor = xor;

package/dist/derived-connectives.d.cts

@@ -0,0 +1,17 @@
+import { t as JsonValue } from "./json-value-B1Hjjjri.cjs";
+import { PredicateNode } from "./tree.cjs";
+//#region src/derived-connectives.d.ts
+/**
+ * `not`/`and`/`or` are the primitive `PredicateNode` object-constructors -- everything else in this file is built purely by composing these three, so its three-valued correctness is inherited from the already-verified AND/OR/NOT tables rather than requiring a separate proof (see the "Derived connectives" section of README.md).
+ */
+declare const not: (a: PredicateNode) => PredicateNode;
+declare const and: (a: PredicateNode, b: PredicateNode) => PredicateNode;
+declare const or: (a: PredicateNode, b: PredicateNode) => PredicateNode;
+declare const xor: (a: PredicateNode, b: PredicateNode) => PredicateNode;
+declare const nand: (a: PredicateNode, b: PredicateNode) => PredicateNode;
+declare const nor: (a: PredicateNode, b: PredicateNode) => PredicateNode;
+declare const implies: (a: PredicateNode, b: PredicateNode) => PredicateNode;
+declare const iff: (a: PredicateNode, b: PredicateNode) => PredicateNode;
+declare const none: (collection: JsonValue, item: PredicateNode, filter?: PredicateNode) => PredicateNode;
+//#endregion
+export { and, iff, implies, nand, none, nor, not, or, xor };

package/dist/derived-connectives.d.ts

@@ -0,0 +1,17 @@
+import { t as JsonValue } from "./json-value-B1Hjjjri.js";
+import { PredicateNode } from "./tree.js";
+//#region src/derived-connectives.d.ts
+/**
+ * `not`/`and`/`or` are the primitive `PredicateNode` object-constructors -- everything else in this file is built purely by composing these three, so its three-valued correctness is inherited from the already-verified AND/OR/NOT tables rather than requiring a separate proof (see the "Derived connectives" section of README.md).
+ */
+declare const not: (a: PredicateNode) => PredicateNode;
+declare const and: (a: PredicateNode, b: PredicateNode) => PredicateNode;
+declare const or: (a: PredicateNode, b: PredicateNode) => PredicateNode;
+declare const xor: (a: PredicateNode, b: PredicateNode) => PredicateNode;
+declare const nand: (a: PredicateNode, b: PredicateNode) => PredicateNode;
+declare const nor: (a: PredicateNode, b: PredicateNode) => PredicateNode;
+declare const implies: (a: PredicateNode, b: PredicateNode) => PredicateNode;
+declare const iff: (a: PredicateNode, b: PredicateNode) => PredicateNode;
+declare const none: (collection: JsonValue, item: PredicateNode, filter?: PredicateNode) => PredicateNode;
+//#endregion
+export { and, iff, implies, nand, none, nor, not, or, xor };

package/dist/derived-connectives.js

@@ -0,0 +1,31 @@
+//#region src/derived-connectives.ts
+/**
+* `not`/`and`/`or` are the primitive `PredicateNode` object-constructors -- everything else in this file is built purely by composing these three, so its three-valued correctness is inherited from the already-verified AND/OR/NOT tables rather than requiring a separate proof (see the "Derived connectives" section of README.md).
+*/
+const not = (a) => ({
+	kind: "not",
+	operand: a
+});
+const and = (a, b) => ({
+	kind: "and",
+	left: a,
+	right: b
+});
+const or = (a, b) => ({
+	kind: "or",
+	left: a,
+	right: b
+});
+const xor = (a, b) => or(and(a, not(b)), and(not(a), b));
+const nand = (a, b) => not(and(a, b));
+const nor = (a, b) => not(or(a, b));
+const implies = (a, b) => or(not(a), b);
+const iff = (a, b) => not(xor(a, b));
+const none = (collection, item, filter) => not({
+	kind: "some",
+	collection,
+	item,
+	filter
+});
+//#endregion
+export { and, iff, implies, nand, none, nor, not, or, xor };

package/dist/evaluation.cjs

@@ -0,0 +1,39 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let zod = require("zod");
+//#region src/evaluation.ts
+const IndeterminateReasonSchema = zod.z.object({
+	/** Which of the three reason categories applies. */
+	code: zod.z.enum([
+		"not-found",
+		"wrong-type",
+		"domain-error"
+	]),
+	/** A human-readable explanation, for logging and debugging. */
+	message: zod.z.string()
+});
+function definite(value) {
+	return {
+		status: "definite",
+		value
+	};
+}
+function indeterminate(code, message) {
+	return {
+		status: "indeterminate",
+		reason: {
+			code,
+			message
+		}
+	};
+}
+/**
+* Implements the tie-break rule from "The evaluation model": when several sub-evaluations could each independently be indeterminate for a different reason, take the first indeterminate reason encountered in the node's own declared operand order. Entries that are `undefined` (an operand not yet evaluated, or not applicable to this node kind) are skipped rather than treated as indeterminate.
+*/
+function firstIndeterminate(...results) {
+	for (const result of results) if (result?.status === "indeterminate") return result.reason;
+}
+//#endregion
+exports.IndeterminateReasonSchema = IndeterminateReasonSchema;
+exports.definite = definite;
+exports.firstIndeterminate = firstIndeterminate;
+exports.indeterminate = indeterminate;

package/dist/evaluation.d.cts

@@ -0,0 +1,29 @@
+import { z } from "zod";
+//#region src/evaluation.d.ts
+/**
+ * Every evaluation -- of a predicate node or an expression node -- produces exactly one of two outcomes: a definite result, or an indeterminate result carrying a reason. Never a bare boolean/number, and never a thrown exception for a data-quality problem.
+ */
+type Evaluation<T> = {
+  status: "definite";
+  value: T;
+} | {
+  status: "indeterminate";
+  reason: IndeterminateReason;
+};
+declare const IndeterminateReasonSchema: z.ZodObject<{
+  code: z.ZodEnum<{
+    "not-found": "not-found";
+    "wrong-type": "wrong-type";
+    "domain-error": "domain-error";
+  }>;
+  message: z.ZodString;
+}, z.core.$strip>;
+type IndeterminateReason = z.infer<typeof IndeterminateReasonSchema>;
+declare function definite<T>(value: T): Evaluation<T>;
+declare function indeterminate(code: IndeterminateReason["code"], message: string): Evaluation<never>;
+/**
+ * Implements the tie-break rule from "The evaluation model": when several sub-evaluations could each independently be indeterminate for a different reason, take the first indeterminate reason encountered in the node's own declared operand order. Entries that are `undefined` (an operand not yet evaluated, or not applicable to this node kind) are skipped rather than treated as indeterminate.
+ */
+declare function firstIndeterminate(...results: readonly (Evaluation<unknown> | undefined)[]): IndeterminateReason | undefined;
+//#endregion
+export { Evaluation, IndeterminateReason, IndeterminateReasonSchema, definite, firstIndeterminate, indeterminate };

package/dist/evaluation.d.ts

@@ -0,0 +1,29 @@
+import { z } from "zod";
+//#region src/evaluation.d.ts
+/**
+ * Every evaluation -- of a predicate node or an expression node -- produces exactly one of two outcomes: a definite result, or an indeterminate result carrying a reason. Never a bare boolean/number, and never a thrown exception for a data-quality problem.
+ */
+type Evaluation<T> = {
+  status: "definite";
+  value: T;
+} | {
+  status: "indeterminate";
+  reason: IndeterminateReason;
+};
+declare const IndeterminateReasonSchema: z.ZodObject<{
+  code: z.ZodEnum<{
+    "not-found": "not-found";
+    "wrong-type": "wrong-type";
+    "domain-error": "domain-error";
+  }>;
+  message: z.ZodString;
+}, z.core.$strip>;
+type IndeterminateReason = z.infer<typeof IndeterminateReasonSchema>;
+declare function definite<T>(value: T): Evaluation<T>;
+declare function indeterminate(code: IndeterminateReason["code"], message: string): Evaluation<never>;
+/**
+ * Implements the tie-break rule from "The evaluation model": when several sub-evaluations could each independently be indeterminate for a different reason, take the first indeterminate reason encountered in the node's own declared operand order. Entries that are `undefined` (an operand not yet evaluated, or not applicable to this node kind) are skipped rather than treated as indeterminate.
+ */
+declare function firstIndeterminate(...results: readonly (Evaluation<unknown> | undefined)[]): IndeterminateReason | undefined;
+//#endregion
+export { Evaluation, IndeterminateReason, IndeterminateReasonSchema, definite, firstIndeterminate, indeterminate };

package/dist/evaluation.js

@@ -0,0 +1,35 @@
+import { z } from "zod";
+//#region src/evaluation.ts
+const IndeterminateReasonSchema = z.object({
+	/** Which of the three reason categories applies. */
+	code: z.enum([
+		"not-found",
+		"wrong-type",
+		"domain-error"
+	]),
+	/** A human-readable explanation, for logging and debugging. */
+	message: z.string()
+});
+function definite(value) {
+	return {
+		status: "definite",
+		value
+	};
+}
+function indeterminate(code, message) {
+	return {
+		status: "indeterminate",
+		reason: {
+			code,
+			message
+		}
+	};
+}
+/**
+* Implements the tie-break rule from "The evaluation model": when several sub-evaluations could each independently be indeterminate for a different reason, take the first indeterminate reason encountered in the node's own declared operand order. Entries that are `undefined` (an operand not yet evaluated, or not applicable to this node kind) are skipped rather than treated as indeterminate.
+*/
+function firstIndeterminate(...results) {
+	for (const result of results) if (result?.status === "indeterminate") return result.reason;
+}
+//#endregion
+export { IndeterminateReasonSchema, definite, firstIndeterminate, indeterminate };