@cerbos/orm-prisma 4.1.0 → 5.0.0

package/src/types.ts

@@ -0,0 +1,1310 @@
+// A plan-to-plan rewrite that settles comparisons whose outcome the mapped column types already
+// decide: CEL's heterogeneous equality, and the no-overload errors a mistyped operand raises.
+// Runs before constant folding, so every constant it produces folds away like any other.
+
+import type { PlanExpressionOperand, Value } from "@cerbos/core";
+
+import { ARITHMETIC_OPERATORS } from "./evaluate";
+import { literalValue } from "./literals";
+import { enterLambdaScope, lookupMapping, resolveFieldReference } from "./mapping";
+import type { ResolvedFieldReference, TranslationContext } from "./mapping";
+import type { MapperConfig } from "./index";
+import { isInvalidPattern } from "./regex";
+import { constantFoldExpression } from "./rewrite";
+import { rewriteTemporalComparison } from "./timestamp";
+import { COMPARISON_OPERATORS, isNamedOperand, isOperatorOperand, isValueOperand } from "./plan";
+import type { NamedOperand, OperatorOperand } from "./plan";
+import { isBoolean, isNumber, isString, pair, triple, typeofValue } from "./narrowing";
+
+/**
+ * The CEL type an operand is known to have. Numbers are one family: CEL's heterogeneous equality
+ * compares an int, a uint and a double numerically, so `1 == 1.0` is true across them.
+ */
+type CelType = "string" | "number" | "boolean" | "null" | "list" | "map";
+
+/**
+ * The values one leaf can take across the rows. `error` is a CEL evaluation error, which Cerbos
+ * denies: a no-overload call, or a missing attribute (an omitted NULL column, an absent to-one
+ * parent) reached before the comparison could decide.
+ */
+type Outcomes = {
+  true?: boolean;
+  false?: boolean;
+  error?: boolean;
+  /**
+   * When the only error is a missing column: each such column's presence test, TRUE when the
+   * value is there and UNKNOWN when it is NULL (see presence).
+   */
+  missing?: PlanExpressionOperand[];
+  /**
+   * When the only error is a missing attribute reached through a to-one relation: a test TRUE
+   * exactly when the relation exists and the column is not NULL, and FALSE or UNKNOWN otherwise.
+   * Unlike `missing`, a relation filter cannot promise UNKNOWN for the error rows (Prisma matches a
+   * to-one relation through a join or subquery, which can collapse UNKNOWN to FALSE), so the test
+   * is only used where the leaf's polarity is fixed and FALSE-or-UNKNOWN is the value that
+   * polarity needs (see settleTypeMismatches).
+   */
+  reached?: PlanExpressionOperand;
+};
+
+const ORDERING_OPERATORS = new Set(["lt", "le", "gt", "ge"]);
+const STRING_OPERATORS = new Set(["contains", "startsWith", "endsWith", "matches"]);
+const HIERARCHY_OPERATORS = new Set(["overlaps", "ancestorOf", "descendentOf"]);
+const LIST_OPERATORS = new Set(["filter", "map", "except"]);
+
+/**
+ * Replaces every leaf whose outcome the mapped value types settle with the constant that decides
+ * the same rows, then leaves the rest of the plan to the translator.
+ *
+ * CEL's `&&`, `||` and `!` are Kleene's strong three-valued logic with an error in the role of
+ * UNKNOWN, and `exists`/`all` are its disjunction and conjunction over the elements. Kleene logic
+ * is regular — a formula that is TRUE with an UNKNOWN operand is TRUE whatever that operand is —
+ * so under an even number of negations a leaf that is only ever FALSE or an error decides every
+ * row exactly as a constant FALSE does, and under an odd number a leaf that is only ever TRUE or
+ * an error decides every row exactly as a constant TRUE does. A leaf that can be both TRUE and
+ * FALSE, or that sits where its polarity is not fixed (a ternary condition, an operand of `==`,
+ * the body of `exists_one`), is left for the translator to lower or refuse.
+ */
+export function settleTypeMismatches(
+  expr: PlanExpressionOperand,
+  context: TranslationContext,
+  positive = true
+): PlanExpressionOperand {
+  if (!isOperatorOperand(expr)) return expr;
+
+  switch (expr.operator) {
+    case "and":
+    case "or":
+      return {
+        operator: expr.operator,
+        operands: expr.operands.map((operand) =>
+          settleTypeMismatches(operand, context, positive)
+        ),
+      };
+    case "not":
+      return {
+        operator: "not",
+        operands: expr.operands.map((operand) =>
+          settleTypeMismatches(operand, context, !positive)
+        ),
+      };
+    case "exists":
+    case "all":
+      return settleLambdaBody(expr, context, positive);
+  }
+
+  const cast =
+    unwrapBooleanComparison(expr) ??
+    distributeTernary(expr, context) ??
+    rewriteCastComparison(expr, context, positive) ??
+    rewriteConcatenation(expr, context) ??
+    rewriteTemporalComparison(expr, positive) ??
+    splitDivision(expr, context);
+
+  if (cast !== undefined) return settleTypeMismatches(cast, context, positive);
+
+  const outcomes = leafOutcomes(expr, context);
+
+  if (outcomes === undefined) return rewriteLiteralLists(expr, context);
+
+  // Definite once every column is present, and an error otherwise: the presence tests carry the
+  // error as SQL UNKNOWN, which decides the row as CEL's error does under either polarity.
+  if (outcomes.missing !== undefined && outcomes.true !== outcomes.false) {
+    const present: PlanExpressionOperand =
+      outcomes.missing.length === 1
+        ? outcomes.missing[0]!
+        : { operator: "and", operands: outcomes.missing };
+
+    if (outcomes.missing.length === 0) return { value: outcomes.true === true };
+
+    return outcomes.true ? present : { operator: "not", operands: [present] };
+  }
+
+  if (positive && !outcomes.true) return { value: false };
+
+  if (!positive && !outcomes.false) return { value: true };
+
+  // What is left is a leaf that is TRUE (positive) or FALSE (negative) once the relation and its
+  // column are present, and an error otherwise. The error rows must not satisfy the leaf's
+  // polarity: `reached` is FALSE or UNKNOWN on them, so it stands for the TRUE leaf under an even
+  // number of negations, and its negation for the FALSE leaf under an odd number, where that
+  // negation meets the enclosing one and is TRUE only for a present value (Kleene logic is
+  // regular, so an error leaf decides no more rows than the value its polarity can least use).
+  if (outcomes.reached !== undefined) {
+    return positive ? outcomes.reached : { operator: "not", operands: [outcomes.reached] };
+  }
+
+  if (!outcomes.error && !(outcomes.true && outcomes.false)) {
+    return { value: outcomes.true === true };
+  }
+
+  return expr;
+}
+
+/** `exists(c, P)` and `all(c, P)` are monotone in P, so the body keeps the macro's polarity. */
+function settleLambdaBody(
+  expr: OperatorOperand,
+  context: TranslationContext,
+  positive: boolean
+): PlanExpressionOperand {
+  const [collection, lambda] = expr.operands;
+
+  if (
+    collection === undefined ||
+    !isNamedOperand(collection) ||
+    lambda === undefined ||
+    !isOperatorOperand(lambda) ||
+    lambda.operator !== "lambda" ||
+    // A two-variable comprehension binds a second variable; rebuilding the lambda below would
+    // drop it. It is left whole for the translator to refuse.
+    lambda.operands.length !== 2
+  ) {
+    return expr;
+  }
+
+  const [body, variable] = lambda.operands;
+
+  if (body === undefined || variable === undefined || !isNamedOperand(variable)) {
+    return expr;
+  }
+
+  const scoped = scopedContext(context, collection.name, variable.name);
+
+  if (scoped === undefined) return expr;
+
+  return {
+    operator: expr.operator,
+    operands: [
+      collection,
+      { operator: "lambda", operands: [settleTypeMismatches(body, scoped, positive), variable] },
+    ],
+  };
+}
+
+/** The context a lambda body over `collectionName` resolves its element references in. */
+function scopedContext(
+  context: TranslationContext,
+  collectionName: string,
+  variableName: string
+): TranslationContext | undefined {
+  const { relations } = resolveFieldReference(collectionName, context);
+
+  if (!relations || relations.length === 0) return undefined;
+
+  return enterLambdaScope(context, collectionName, {
+    variableName,
+    relationModel: relations[relations.length - 1]!.model,
+    nullableFields: new Set(),
+    unknownFilters: [],
+  });
+}
+
+// -- casts ---------------------------------------------------------------------------------------
+
+/**
+ * `cmp(c ? a : b, x)` as `(c && cmp(a, x)) || (!c && cmp(b, x))`, when that lets a branch settle.
+ * A ternary evaluates only the branch it selects, so the comparison distributes over it; the
+ * expansion is exact only when `c` itself cannot be an error, so `c` must be a boolean column that
+ * is never missing. Any other ternary is left to the translator's own lowering.
+ */
+function distributeTernary(
+  expr: OperatorOperand,
+  context: TranslationContext
+): PlanExpressionOperand | undefined {
+  if (!COMPARISON_OPERATORS.has(expr.operator) || expr.operands.length !== 2) return undefined;
+
+  const index = expr.operands.findIndex(
+    (operand) => isOperatorOperand(operand) && operand.operator === "if" && operand.operands.length === 3
+  );
+
+  if (index === -1) return undefined;
+
+  const ternary = expr.operands[index];
+
+  if (ternary === undefined || !isOperatorOperand(ternary)) return undefined;
+
+  const [condition, whenTrue, whenFalse] = triple(ternary.operands);
+
+  if (!isNamedOperand(condition)) return undefined;
+  const fieldRef = resolveFieldReference(condition.name, context);
+
+  if (scalarType(fieldRef) !== "boolean" || fieldRef.relations?.length) return undefined;
+  // A missing condition is an error that selects neither branch; its presence test keeps it one.
+  const conditionPresent = mayBeMissing(fieldRef) ? presence(condition, fieldRef) : undefined;
+
+  // A relation reached in a branch would be required around the whole expansion under an
+  // enclosing negation (see negateRequiringHops), where CEL never evaluates the unselected branch.
+  const reachesRelation = (operand: PlanExpressionOperand): boolean =>
+    isNamedOperand(operand)
+      ? (resolveFieldReference(operand.name, context).relations?.length ?? 0) > 0
+      : isOperatorOperand(operand) && operand.operands.some(reachesRelation);
+
+  if (expr.operands.some(reachesRelation)) return undefined;
+
+  const branch = (value: PlanExpressionOperand): PlanExpressionOperand =>
+    constantFoldExpression({
+      operator: expr.operator,
+      operands: expr.operands.map((operand, i) => (i === index ? value : operand)),
+    });
+
+  const [onTrue, onFalse] = [branch(whenTrue), branch(whenFalse)];
+
+  const settles = (leaf: PlanExpressionOperand) =>
+    isValueOperand(leaf) || (isOperatorOperand(leaf) && leafOutcomes(leaf, context) !== undefined);
+
+  if (!settles(onTrue) && !settles(onFalse)) return undefined;
+
+  return {
+    operator: "or",
+    operands: [
+      { operator: "and", operands: [condition, onTrue] },
+      { operator: "and", operands: [{ operator: "not", operands: [condition] }, onFalse] },
+      ...(conditionPresent === undefined
+        ? []
+        : [{ operator: "not", operands: [conditionPresent] }]),
+    ],
+  };
+}
+
+/** Operators whose value is a boolean (or an error), never anything else. */
+const BOOLEAN_OPERATORS = new Set([
+  "and",
+  "or",
+  "not",
+  "eq",
+  "ne",
+  "lt",
+  "le",
+  "gt",
+  "ge",
+  "in",
+  "contains",
+  "startsWith",
+  "endsWith",
+  "matches",
+  "exists",
+  "all",
+  "exists_one",
+  "hasIntersection",
+]);
+
+/**
+ * `b == true`, `b != false` (and the mirrors) over a boolean-valued `b` are `b`; `b == false` and
+ * `b != true` are `!b`. An error in `b` is an error either way.
+ */
+function unwrapBooleanComparison(expr: OperatorOperand): PlanExpressionOperand | undefined {
+  if ((expr.operator !== "eq" && expr.operator !== "ne") || expr.operands.length !== 2) {
+    return undefined;
+  }
+
+  const [first, second] = pair(expr.operands);
+  const [inner, literal] = isValueOperand(first) ? [second, first] : [first, second];
+
+  if (
+    !isValueOperand(literal) ||
+    !isBoolean(literal.value) ||
+    !isOperatorOperand(inner) ||
+    !BOOLEAN_OPERATORS.has(inner.operator)
+  ) {
+    return undefined;
+  }
+
+  const same = (expr.operator === "eq") === literal.value;
+
+  return same ? inner : { operator: "not", operands: [inner] };
+}
+
+/**
+ * `string(column) == "lit"` and `int(column) == k` (and their `!=` forms), solved for the column
+ * the cast wraps: a Prisma filter has no cast, but these conversions are invertible.
+ *
+ * - `string(b)` of a boolean is `"true"` or `"false"`, for a column or any boolean-valued
+ *   expression (see renderedBooleanComparison).
+ * - `string(d)` of a number is cel-go's shortest `%g` rendering, so exactly one double prints as a
+ *   given literal — or none does, and the comparison is settled like any type mismatch.
+ * - `int(d)` truncates toward zero, and raises an error outside (-2^63, 2^63). A threshold is a
+ *   half-open interval that would need that bound spelled out, which an `Int` column rejects, so
+ *   only `==` outside a `!` and `!=` under one are translated: the interval `==` solves to already
+ *   excludes every value that overflows, and the error then decides the row as the constant does.
+ *
+ * A column the caller sends as an explicit null is left alone: the cast of a null VALUE is an
+ * error, where the comparison it would be rewritten to is definite.
+ */
+function rewriteCastComparison(
+  expr: OperatorOperand,
+  context: TranslationContext,
+  positive: boolean
+): PlanExpressionOperand | undefined {
+  const { operator } = expr;
+
+  if ((operator !== "eq" && operator !== "ne") || expr.operands.length !== 2) return undefined;
+  const [first, second] = pair(expr.operands);
+  const [cast, literal] = isOperatorOperand(first) ? [first, second] : [second, first];
+
+  if (
+    !isOperatorOperand(cast) ||
+    cast.operands.length !== 1 ||
+    !isValueOperand(literal) ||
+    literal.value === null
+  ) {
+    return undefined;
+  }
+
+  const column = cast.operands[0]!;
+  const value = literal.value;
+
+  if (cast.operator === "string" && isString(value) && !isNamedOperand(column)) {
+    if (isBooleanValued(column, context)) {
+      return renderedBooleanComparison(column, value, operator);
+    }
+
+    // string(int(x)) renders the int in plain decimal, so the comparison is int(x) == k for the
+    // one k that renders as the literal, solved below on the next pass. A literal no int renders
+    // as, or one past 2^53, is left alone: the int's overflow error has no bound an Int column
+    // accepts.
+    const rendered = isOperatorOperand(column) && column.operator === "int" ? Number(value) : NaN;
+
+    return /^(0|-?[1-9][0-9]*)$/.test(value) && Number.isSafeInteger(rendered)
+      ? { operator, operands: [column, { value: rendered }] }
+      : undefined;
+  }
+
+  if (!isNamedOperand(column)) return undefined;
+  const fieldRef = resolveFieldReference(column.name, context);
+
+  if (fieldRef.nullAttributeRepresentation === "explicit") return undefined;
+  const type = scalarType(fieldRef);
+
+  // A column reached through a to-one relation is solved for only as a boolean rendering: the
+  // comparison it becomes is one the translator already guards through the hop.
+  if (fieldRef.relations?.length && (cast.operator !== "string" || type !== "boolean")) {
+    return undefined;
+  }
+
+  const compare = (op: string, v: Value): PlanExpressionOperand => ({
+    operator: op,
+    operands: [column, { value: v }],
+  });
+
+  const equality = (v: Value): PlanExpressionOperand => compare(operator, v);
+
+  // No value of the column prints as the literal: the comparison is settled by its type alone.
+  const unmatched: PlanExpressionOperand = {
+    operator,
+    operands: [column, { operator: "struct", operands: [] }],
+  };
+
+  if (cast.operator === "string" && isString(value)) {
+    if (type === "boolean") {
+      return value === "true" || value === "false" ? equality(value === "true") : unmatched;
+    }
+
+    if (type === "number") {
+      const parsed = Number(value);
+
+      return value.trim() !== "" && formatCelDouble(parsed) === value
+        ? equality(parsed)
+        : unmatched;
+    }
+
+    return undefined;
+  }
+
+  if (cast.operator === "int" && type === "number" && isNumber(value)) {
+    if ((operator === "eq") !== positive) return undefined;
+
+    if (!Number.isInteger(value)) return unmatched;
+
+    const range: PlanExpressionOperand = {
+      operator: "and",
+      operands:
+        value > 0
+          ? [compare("ge", value), compare("lt", value + 1)]
+          : value < 0
+            ? [compare("gt", value - 1), compare("le", value)]
+            : [compare("gt", -1), compare("lt", 1)],
+    };
+
+    return operator === "eq" ? range : { operator: "not", operands: [range] };
+  }
+
+  return undefined;
+}
+
+/**
+ * `string(b) == "lit"` (and `!=`) over a boolean-valued expression `b`: CEL renders a boolean as
+ * `"true"` or `"false"`, so the comparison is `b`, `!b`, or for any other literal false wherever
+ * `b` evaluates, and an error wherever `b` is one — which `b && !b` is, exactly.
+ */
+function renderedBooleanComparison(
+  expression: PlanExpressionOperand,
+  literal: string,
+  operator: string
+): PlanExpressionOperand {
+  const negated: PlanExpressionOperand = { operator: "not", operands: [expression] };
+
+  const holds: PlanExpressionOperand =
+    literal === "true"
+      ? expression
+      : literal === "false"
+        ? negated
+        : { operator: "and", operands: [expression, negated] };
+
+  return operator === "eq" ? holds : { operator: "not", operands: [holds] };
+}
+
+/**
+ * Whether `expr` is a boolean, or an error, on every row: a boolean operator, a boolean literal,
+ * a boolean column, or a ternary whose arms both are.
+ */
+function isBooleanValued(expr: PlanExpressionOperand, context: TranslationContext): boolean {
+  if (isValueOperand(expr)) return isBoolean(expr.value);
+
+  if (isNamedOperand(expr)) {
+    return scalarType(resolveFieldReference(expr.name, context)) === "boolean";
+  }
+
+  if (BOOLEAN_OPERATORS.has(expr.operator)) return true;
+
+  return (
+    expr.operator === "if" &&
+    expr.operands.length === 3 &&
+    expr.operands.slice(1).every((arm) => isBooleanValued(arm, context))
+  );
+}
+
+/**
+ * A comparison whose only column appears as `x / x` or `x / ±0`, split on the sign of `x`. CEL
+ * numbers are doubles, so neither division raises an error: `x / x` is 1, or NaN at zero, and
+ * `x / ±0` is an infinity signed by both operands, or NaN at zero. Each arm substitutes that
+ * constant, leaving a comparison between constants that folds; the arms' guards are plain
+ * comparisons on `x`, UNKNOWN on a NULL column, as the missing attribute's error requires.
+ */
+function splitDivision(
+  expr: OperatorOperand,
+  context: TranslationContext
+): PlanExpressionOperand | undefined {
+  if (!COMPARISON_OPERATORS.has(expr.operator)) return undefined;
+  const column = divisionColumn(expr);
+
+  if (column === undefined) return undefined;
+  const fieldRef = resolveFieldReference(column.name, context);
+
+  if (
+    fieldRef.valueType !== "number" ||
+    (fieldRef.relations?.length ?? 0) > 0 ||
+    fieldRef.nullAttributeRepresentation === "explicit"
+  ) {
+    return undefined;
+  }
+
+  const sign = (op: string): PlanExpressionOperand => ({
+    operator: op,
+    operands: [column, { value: 0 }],
+  });
+
+  const arms: PlanExpressionOperand[] = [];
+
+  for (const [guard, x] of [
+    ["gt", 1],
+    ["lt", -1],
+    ["eq", 0],
+  ] as const) {
+    const substituted = substituteDivision(expr, column.name, x);
+
+    if (substituted === undefined) return undefined;
+    arms.push({ operator: "and", operands: [sign(guard), substituted] });
+  }
+
+  return { operator: "or", operands: arms };
+}
+
+/** The one column of a comparison when every reference to it sits in `x / x` or `x / ±0`. */
+function divisionColumn(expr: PlanExpressionOperand): NamedOperand | undefined {
+  let column: NamedOperand | undefined;
+  let divided = false;
+
+  const visit = (node: PlanExpressionOperand): boolean => {
+    if (isNamedOperand(node)) {
+      if (column !== undefined && column.name !== node.name) return false;
+      column = node;
+
+      return false;
+    }
+
+    if (!isOperatorOperand(node)) return true;
+
+    if (node.operator === "lambda") return false;
+
+    const division = columnDivision(node);
+
+    if (division !== undefined) {
+      const { numerator } = division;
+
+      if (column !== undefined && column.name !== numerator.name) return false;
+      column = numerator;
+      divided = true;
+
+      return true;
+    }
+
+    return node.operands.every(visit);
+  };
+
+  return visit(expr) && divided ? column : undefined;
+}
+
+/** `divisor` is the constant zero, signed, or undefined where the column divides itself. */
+type ColumnDivision = { numerator: NamedOperand; divisor: number | undefined };
+
+/** `x / x` or `x / 0` over a column: the division whose quotient the column's value decides. */
+function columnDivision(node: OperatorOperand): ColumnDivision | undefined {
+  if (node.operator !== "div" || node.operands.length !== 2) return undefined;
+  const [numerator, denominator] = pair(node.operands);
+
+  if (!isNamedOperand(numerator)) return undefined;
+
+  if (isNamedOperand(denominator)) {
+    return denominator.name === numerator.name ? { numerator, divisor: undefined } : undefined;
+  }
+
+  return isValueOperand(denominator) && isNumber(denominator.value) && denominator.value === 0
+    ? { numerator, divisor: denominator.value }
+    : undefined;
+}
+
+/**
+ * `expr` with every division of the column replaced by its value when the column has the sign of
+ * `x`, or undefined when the column is still referenced outside one.
+ */
+function substituteDivision(
+  expr: PlanExpressionOperand,
+  name: string,
+  x: number
+): PlanExpressionOperand | undefined {
+  if (isNamedOperand(expr)) return undefined;
+
+  if (!isOperatorOperand(expr)) return expr;
+
+  const division = columnDivision(expr);
+
+  if (division !== undefined) return { value: x / (division.divisor ?? x) };
+
+  const operands: PlanExpressionOperand[] = [];
+
+  for (const operand of expr.operands) {
+    const substituted = substituteDivision(operand, name, x);
+
+    if (substituted === undefined) return undefined;
+    operands.push(substituted);
+  }
+
+  return { operator: expr.operator, operands };
+}
+
+/** Past this many code points, a literal is not split across a concatenation of columns. */
+const MAX_CONCATENATION_SPLITS = 256;
+
+/** Past this many ways to split the literal, the concatenation is left to the translator. */
+const MAX_CONCATENATION_ARMS = 256;
+
+/**
+ * `a + "sep" + b == "lit"` over string columns and string literals, with at least two columns:
+ * one arm per way of splitting the literal into consecutive pieces, each column taking one piece
+ * (`a == prefix && b == suffix`) and each literal term matching its own text in place. Each arm
+ * also ORs in `!startsWith(column, "")` for every column — FALSE for a present value, UNKNOWN for a
+ * NULL one — so a missing operand leaves the whole comparison UNKNOWN under both polarities, as
+ * the error `+` raises on it does in CEL.
+ */
+function rewriteConcatenation(
+  expr: OperatorOperand,
+  context: TranslationContext
+): PlanExpressionOperand | undefined {
+  const { operator } = expr;
+
+  if ((operator !== "eq" && operator !== "ne") || expr.operands.length !== 2) return undefined;
+  const [first, second] = pair(expr.operands);
+  const [sum, literal] = isOperatorOperand(first) ? [first, second] : [second, first];
+
+  if (
+    !isOperatorOperand(sum) ||
+    sum.operator !== "add" ||
+    !isValueOperand(literal) ||
+    !isString(literal.value)
+  ) {
+    return undefined;
+  }
+
+  const terms = concatenationTerms(sum);
+
+  if (terms === undefined) return undefined;
+  const columns = terms.filter(isNamedOperand);
+
+  if (
+    columns.length < 2 ||
+    columns.some((column) => {
+      const fieldRef = resolveFieldReference(column.name, context);
+
+      return fieldRef.valueType !== "string" || (fieldRef.relations?.length ?? 0) > 0;
+    })
+  ) {
+    return undefined;
+  }
+
+  const codePoints = Array.from(literal.value);
+
+  if (codePoints.length > MAX_CONCATENATION_SPLITS) return undefined;
+
+  const arms: PlanExpressionOperand[] = [];
+
+  const split = (index: number, offset: number, pieces: PlanExpressionOperand[]): boolean => {
+    if (index === terms.length) {
+      if (offset !== codePoints.length) return true;
+      arms.push(pieces.length === 1 ? pieces[0]! : { operator: "and", operands: pieces });
+
+      return arms.length <= MAX_CONCATENATION_ARMS;
+    }
+
+    const term = terms[index]!;
+
+    if ("value" in term) {
+      const text = Array.from(term.value);
+      const matches = text.every((point, i) => codePoints[offset + i] === point);
+
+      return !matches || split(index + 1, offset + text.length, pieces);
+    }
+
+    const last = index === terms.length - 1;
+
+    for (let end = last ? codePoints.length : offset; end <= codePoints.length; end++) {
+      const piece = codePoints.slice(offset, end).join("");
+      const equality = { operator: "eq", operands: [term, { value: piece }] };
+
+      if (!split(index + 1, end, [...pieces, equality])) return false;
+    }
+
+    return true;
+  };
+
+  if (!split(0, 0, [])) return undefined;
+
+  for (const column of columns) {
+    arms.push({
+      operator: "not",
+      operands: [{ operator: "startsWith", operands: [column, { value: "" }] }],
+    });
+  }
+
+  const equality: PlanExpressionOperand = { operator: "or", operands: arms };
+
+  return operator === "eq" ? equality : { operator: "not", operands: [equality] };
+}
+
+/** The terms of a nested `add` of string columns and string literals, left to right. */
+function concatenationTerms(
+  expr: PlanExpressionOperand
+): (NamedOperand | { value: string })[] | undefined {
+  if (isNamedOperand(expr)) return [expr];
+
+  if (isValueOperand(expr)) {
+    return isString(expr.value) ? [{ value: expr.value }] : undefined;
+  }
+
+  if (!isOperatorOperand(expr) || expr.operator !== "add" || expr.operands.length !== 2) {
+    return undefined;
+  }
+
+  const left = concatenationTerms(expr.operands[0]!);
+  const right = concatenationTerms(expr.operands[1]!);
+
+  return left && right && [...left, ...right];
+}
+
+/**
+ * CEL's string() of a double: cel-go's `fmt.Sprintf("%g", d)`, the shortest digits that
+ * round-trip, in exponent form below 1e-4 or from 1e+06.
+ */
+export function formatCelDouble(x: number): string {
+  if (Number.isNaN(x)) return "NaN";
+
+  if (x === Infinity) return "+Inf";
+
+  if (x === -Infinity) return "-Inf";
+
+  if (x === 0) return Object.is(x, -0) ? "-0" : "0";
+  const sign = x < 0 ? "-" : "";
+  const exponential = Math.abs(x).toExponential();
+  const exponentAt = exponential.indexOf("e");
+  const mantissa = exponential.slice(0, exponentAt);
+  const exponentText = exponential.slice(exponentAt + 1);
+  const digits = mantissa.replace(".", "");
+  const exponent = Number(exponentText);
+
+  if (exponent < -4 || exponent >= 6) {
+    const fraction = digits.length > 1 ? `.${digits.slice(1)}` : "";
+    const magnitude = String(Math.abs(exponent)).padStart(2, "0");
+
+    return `${sign}${digits[0]}${fraction}e${exponent < 0 ? "-" : "+"}${magnitude}`;
+  }
+
+  const point = exponent + 1;
+
+  if (point <= 0) return `${sign}0.${"0".repeat(-point)}${digits}`;
+
+  if (point >= digits.length) return `${sign}${digits}${"0".repeat(point - digits.length)}`;
+
+  return `${sign}${digits.slice(0, point)}.${digits.slice(point)}`;
+}
+
+// -- the leaves ----------------------------------------------------------------------------------
+
+function leafOutcomes(
+  expr: OperatorOperand,
+  context: TranslationContext
+): Outcomes | undefined {
+  const { operator, operands } = expr;
+
+  // A pattern RE2 rejects fails on every row it is evaluated for.
+  if (operator === "matches" && operands.length === 2) {
+    const pattern = operands[1]!;
+
+    if (isValueOperand(pattern) && isString(pattern.value) && isInvalidPattern(pattern.value)) {
+      return { error: true };
+    }
+  }
+
+  // A list where a boolean is required: CEL's logical operators raise a no-overload error on it,
+  // and a condition that is not a boolean denies.
+  if (LIST_OPERATORS.has(operator)) return { error: true };
+
+  if (COMPARISON_OPERATORS.has(operator) && operands.length === 2) {
+    const [left, right] = pair(operands);
+    // NaN equals nothing and orders against nothing — not even a string, on the current PDP.
+    const nan = [left, right].find((o) => isValueOperand(o) && Number.isNaN(o.value));
+
+    if (nan !== undefined) {
+      const other = nan === left ? right : left;
+
+      if (!isNamedOperand(other) && !isValueOperand(other)) return undefined;
+
+      return definite(operator === "ne", [other], context);
+    }
+
+    const nullComparison = omittedNullComparison(operator, left, right, context);
+
+    if (nullComparison !== undefined) return nullComparison;
+
+    const size = [left, right].find(
+      (o): o is OperatorOperand => isOperatorOperand(o) && o.operator === "size"
+    );
+
+    if (size !== undefined) {
+      // size() has overloads for strings, lists and maps only.
+      const [subject] = size.operands;
+      const type = subject && scalarFieldType(subject, context);
+
+      return type === "number" || type === "boolean" ? { error: true } : undefined;
+    }
+
+    // A bare date-time column is the RFC 3339 STRING the application sends, and a string never
+    // orders against a timestamp: no overload, so an error on every row. Equality across the two
+    // types is heterogeneous, and false.
+    if (comparesRawTemporalWithTimestamp(left, right, context)) {
+      return ORDERING_OPERATORS.has(operator)
+        ? { error: true }
+        : definite(operator !== "eq", [left, right], context);
+    }
+
+    const leftType = operandType(left, context);
+    const rightType = operandType(right, context);
+
+    if (
+      leftType === undefined ||
+      rightType === undefined ||
+      leftType.type === rightType.type ||
+      leftType.type === "null" ||
+      rightType.type === "null"
+    ) {
+      return undefined;
+    }
+
+    if (ORDERING_OPERATORS.has(operator)) return { error: true };
+
+    return definite(operator !== "eq", [left, right], context);
+  }
+
+  if (STRING_OPERATORS.has(operator) && operands.length === 2) {
+    const mistyped = operands.some((operand) => {
+      const type = operandType(operand, context)?.type;
+
+      return type !== undefined && type !== "string" && type !== "null";
+    });
+
+    return mistyped ? { error: true } : undefined;
+  }
+
+  if (HIERARCHY_OPERATORS.has(operator)) {
+    // hierarchy() parses a string; any other scalar is a no-overload error.
+    const mistyped = operands.some((operand) => {
+      if (!isOperatorOperand(operand) || operand.operator !== "hierarchy") return false;
+      const [subject] = operand.operands;
+      const type = subject && scalarFieldType(subject, context);
+
+      return type === "number" || type === "boolean";
+    });
+
+    return mistyped ? { error: true } : undefined;
+  }
+
+  if (operator === "in" && operands.length === 2) {
+    const [member, collection] = pair(operands);
+    // A literal member against a mapped list whose elements can never equal it.
+    const memberType = literalType(member);
+    const list = collectionElementType(collection, context);
+
+    if (memberType !== undefined && memberType !== "null" && list !== undefined) {
+      return memberType === list.type ? undefined : { false: true, error: list.mayBeMissing };
+    }
+
+    // A field member against a literal list none of whose elements it can equal.
+    const field = operandType(member, context);
+    const elements = literalElements(collection);
+
+    if (field !== undefined && elements !== undefined) {
+      return elements.every((element) => isMismatch(field.type, element))
+        ? definite(false, [member], context)
+        : undefined;
+    }
+
+    return undefined;
+  }
+
+  if (operator === "hasIntersection" && operands.length === 2) {
+    const [left, right] = pair(operands);
+
+    for (const [list, literal] of [
+      [left, right],
+      [right, left],
+    ] as const) {
+      const elementType = collectionElementType(list, context);
+      const elements = literalElements(literal);
+
+      if (elementType !== undefined && elements !== undefined) {
+        return elements.every((element) => isMismatch(elementType.type, element))
+          ? { false: true, error: elementType.mayBeMissing }
+          : undefined;
+      }
+    }
+  }
+
+  return undefined;
+}
+
+/** Whether one operand is a bare `dateTime` column and the other a `timestamp(...)` call. */
+function comparesRawTemporalWithTimestamp(
+  left: PlanExpressionOperand,
+  right: PlanExpressionOperand,
+  context: TranslationContext
+): boolean {
+  return [
+    [left, right],
+    [right, left],
+  ].some(
+    ([column, other]) =>
+      isNamedOperand(column!) &&
+      isOperatorOperand(other!) &&
+      other.operator === "timestamp" &&
+      resolveFieldReference(column.name, context).valueType === "dateTime"
+  );
+}
+
+/**
+ * `x == null` / `x != null` over a column the caller omits when NULL: a present value is never
+ * null, and an absent one is a missing-attribute error, so neither outcome can select the NULL
+ * rows an `IS NULL` would.
+ *
+ * A column read through to-one relations (`parent.x`) is also missing when a relation on the way
+ * is absent. Its presence test is `reached` rather than `missing`: a relation filter is not
+ * guaranteed to be UNKNOWN on the rows it fails, so it only answers where polarity is fixed.
+ */
+function omittedNullComparison(
+  operator: string,
+  left: PlanExpressionOperand,
+  right: PlanExpressionOperand,
+  context: TranslationContext
+): Outcomes | undefined {
+  if (operator !== "eq" && operator !== "ne") return undefined;
+  const [field, literal] = isNamedOperand(left) ? [left, right] : [right, left];
+
+  if (!isNamedOperand(field) || !isValueOperand(literal) || literal.value !== null) {
+    return undefined;
+  }
+
+  const fieldRef = resolveFieldReference(field.name, context);
+  const relations = fieldRef.relations ?? [];
+
+  if (relations.some((relation) => relation.type !== "one")) return undefined;
+  const convention = fieldRef.nullAttributeRepresentation ?? context.nullRepresentation;
+
+  if (convention !== "omitted") return undefined;
+  const test = presence(field, fieldRef);
+
+  const presenceTest =
+    test === undefined ? {} : relations.length > 0 ? { reached: test } : { missing: [test] };
+
+  return {
+    [operator === "eq" ? "false" : "true"]: true,
+    error: true,
+    ...presenceTest,
+  };
+}
+
+/**
+ * A leaf that is `value` whenever the named operands among `operands` are present, and a
+ * missing-attribute error when one is not.
+ */
+function definite(
+  value: boolean,
+  operands: PlanExpressionOperand[],
+  context: TranslationContext
+): Outcomes {
+  const missing: PlanExpressionOperand[] = [];
+  let unknowable = false;
+
+  const visit = (operand: PlanExpressionOperand): void => {
+    if (literalValue(operand) !== undefined) return;
+
+    // Arithmetic raises the error of any column it reads; another expression's errors are not
+    // known here, so its leaf is left as it stands.
+    if (isOperatorOperand(operand)) {
+      if (ARITHMETIC_OPERATORS.has(operand.operator)) operand.operands.forEach(visit);
+      else unknowable = true;
+
+      return;
+    }
+
+    if (!isNamedOperand(operand)) return;
+    const fieldRef = resolveFieldReference(operand.name, context);
+
+    if (!mayBeMissing(fieldRef)) return;
+    const test = presence(operand, fieldRef);
+
+    if (test === undefined) unknowable = true;
+    else missing.push(test);
+  };
+
+  operands.forEach(visit);
+
+  return {
+    [value ? "true" : "false"]: true,
+    error: unknowable || missing.length > 0,
+    missing: unknowable ? undefined : missing,
+  };
+}
+
+/**
+ * A predicate TRUE for a present value of the column and UNKNOWN for a NULL one, spelled with
+ * the plain comparisons the translator leaves to SQL's three-valued logic. Undefined for a column
+ * whose type is not declared.
+ */
+export function presence(
+  column: NamedOperand,
+  fieldRef: ResolvedFieldReference
+): PlanExpressionOperand | undefined {
+  const compare = (operator: string, value: Value): PlanExpressionOperand => ({
+    operator,
+    operands: [column, { value }],
+  });
+
+  switch (scalarType(fieldRef)) {
+    case "string":
+      return compare("startsWith", "");
+    case "number":
+      return { operator: "or", operands: [compare("gt", 0), compare("le", 0)] };
+    case "boolean":
+      return { operator: "or", operands: [compare("eq", true), compare("eq", false)] };
+    default:
+      return undefined;
+  }
+}
+
+/**
+ * Drops, from a literal list compared by element equality, every element that can never equal
+ * the other side's elements: each one contributes a definite false to CEL's membership test, so
+ * the list without it decides every row the same way.
+ */
+function rewriteLiteralLists(
+  expr: OperatorOperand,
+  context: TranslationContext
+): PlanExpressionOperand {
+  const { operator, operands } = expr;
+
+  if (operands.length !== 2) return expr;
+  const [first, second] = pair(operands);
+
+  if (operator === "in") {
+    const field = operandType(first, context);
+
+    if (field === undefined) return expr;
+    const pruned = pruneLiteralList(second, field.type);
+
+    return pruned === undefined ? expr : { operator, operands: [first, pruned] };
+  }
+
+  if (operator === "hasIntersection") {
+    const leftList = collectionElementType(first, context);
+
+    if (leftList !== undefined) {
+      const pruned = pruneLiteralList(second, leftList.type);
+
+      return pruned === undefined ? expr : { operator, operands: [first, pruned] };
+    }
+
+    const rightList = collectionElementType(second, context);
+
+    if (rightList !== undefined) {
+      const pruned = pruneLiteralList(first, rightList.type);
+
+      return pruned === undefined ? expr : { operator, operands: [pruned, second] };
+    }
+  }
+
+  return expr;
+}
+
+/** The literal list without its mismatched elements, or undefined when nothing is dropped. */
+function pruneLiteralList(
+  operand: PlanExpressionOperand,
+  type: CelType
+): PlanExpressionOperand | undefined {
+  if (!isValueOperand(operand) || !Array.isArray(operand.value)) return undefined;
+  const kept = operand.value.filter((element) => !isMismatch(type, element));
+
+  if (kept.length === operand.value.length || kept.length === 0) return undefined;
+
+  return { value: kept };
+}
+
+// -- operand types -------------------------------------------------------------------------------
+
+type KnownType = { type: CelType; mayBeMissing: boolean };
+
+function valueType(value: Value): CelType | undefined {
+  if (value === null) return "null";
+
+  if (Array.isArray(value)) return "list";
+
+  switch (typeofValue(value)) {
+    case "string":
+      return "string";
+    case "number":
+      return "number";
+    case "boolean":
+      return "boolean";
+    case "object":
+      return "map";
+    default:
+      return undefined;
+  }
+}
+
+function isMismatch(type: CelType, element: Value): boolean {
+  const elementType = valueType(element);
+
+  return elementType !== undefined && elementType !== "null" && elementType !== type;
+}
+
+/** The CEL type of a literal operand: a value, or a `list(...)`/`struct(...)` constructor. */
+function literalType(operand: PlanExpressionOperand): CelType | undefined {
+  if (isValueOperand(operand)) return valueType(operand.value);
+
+  if (isOperatorOperand(operand)) {
+    if (operand.operator === "list") return "list";
+
+    if (operand.operator === "struct") return "map";
+  }
+
+  return undefined;
+}
+
+/** The elements of a literal list operand, with nested constructors standing in for their type. */
+function literalElements(operand: PlanExpressionOperand): Value[] | undefined {
+  if (isValueOperand(operand)) {
+    return Array.isArray(operand.value) ? operand.value : undefined;
+  }
+
+  if (isOperatorOperand(operand) && operand.operator === "list") {
+    const elements: Value[] = [];
+
+    for (const element of operand.operands) {
+      if (isValueOperand(element)) {
+        elements.push(element.value);
+        continue;
+      }
+
+      const type = literalType(element);
+
+      if (type === "list") elements.push([]);
+      else if (type === "map") elements.push({});
+      else return undefined;
+    }
+
+    return elements;
+  }
+
+  return undefined;
+}
+
+function operandType(
+  operand: PlanExpressionOperand,
+  context: TranslationContext
+): KnownType | undefined {
+  const literal = literalType(operand);
+
+  if (literal !== undefined) return { type: literal, mayBeMissing: false };
+
+  if (isOperatorOperand(operand)) return arithmeticType(operand, context);
+
+  if (!isNamedOperand(operand)) return undefined;
+  const fieldRef = resolveFieldReference(operand.name, context);
+  const type = scalarType(fieldRef);
+
+  if (type === undefined) return undefined;
+
+  // A relation-backed reference that is not a to-one scalar is a collection, not a scalar.
+  if (fieldRef.relations?.some((relation) => relation.type !== "one")) return undefined;
+
+  return { type, mayBeMissing: mayBeMissing(fieldRef) };
+}
+
+/**
+ * The type of `a + b`, `a - b`, `a * b` or `a / b` when both operands are known numbers, or of
+ * `a + b` when both are strings: the result's type, missing when either operand is. Any other
+ * pairing is left unknown, as a no-overload error is only certain of the typed ones.
+ */
+function arithmeticType(
+  expr: OperatorOperand,
+  context: TranslationContext
+): KnownType | undefined {
+  if (!ARITHMETIC_OPERATORS.has(expr.operator) || expr.operands.length !== 2) return undefined;
+  const [left, right] = expr.operands.map((operand) => operandType(operand, context));
+
+  if (left === undefined || right === undefined || left.type !== right.type) return undefined;
+
+  if (left.type !== "number" && (left.type !== "string" || expr.operator !== "add")) {
+    return undefined;
+  }
+
+  return { type: left.type, mayBeMissing: left.mayBeMissing || right.mayBeMissing };
+}
+
+function scalarFieldType(
+  operand: PlanExpressionOperand,
+  context: TranslationContext
+): CelType | undefined {
+  return operandType(operand, context)?.type;
+}
+
+/** Date-time columns are RFC 3339 strings in CEL but not in the store, so they stay unknown. */
+function scalarType(fieldRef: ResolvedFieldReference): CelType | undefined {
+  switch (fieldRef.valueType) {
+    case "string":
+    case "number":
+    case "boolean":
+      return fieldRef.valueType;
+    default:
+      return undefined;
+  }
+}
+
+/**
+ * Whether evaluating the reference can raise a missing-attribute error: a to-one hop that may be
+ * absent, or a column that may be NULL. A column sent as an explicit null holds a null VALUE,
+ * which heterogeneous equality compares definitely. Only `nullable: false` says a column is never
+ * NULL: an undeclared mapping is not evidence of NOT NULL, and settling a comparison as if it
+ * were would admit the NULL rows under a negation.
+ */
+function mayBeMissing(fieldRef: ResolvedFieldReference): boolean {
+  if (fieldRef.relations?.some((relation) => relation.type === "one")) return true;
+
+  if (fieldRef.nullAttributeRepresentation === "explicit") return false;
+
+  return fieldRef.nullable !== false;
+}
+
+/**
+ * The element type of a mapped list: a relation-backed list reference, or `map()` projecting one
+ * element column. Undefined when the mapping does not declare it.
+ */
+function collectionElementType(
+  operand: PlanExpressionOperand,
+  context: TranslationContext
+): KnownType | undefined {
+  if (isNamedOperand(operand)) {
+    const fieldRef = resolveFieldReference(operand.name, context);
+    const relations = fieldRef.relations;
+
+    if (!relations || relations.length === 0) return undefined;
+    const last = relations[relations.length - 1]!;
+
+    if (last.type !== "many" || last.field === undefined) return undefined;
+
+    const declared =
+      lookupMapping(context.mapper, operand.name)?.valueType ??
+      elementFieldValueType(context, operand.name, last.field);
+
+    const type = declared && scalarType({ path: [], valueType: declared });
+
+    if (type === undefined) return undefined;
+
+    return { type, mayBeMissing: relations.some((relation) => relation.type === "one") };
+  }
+
+  if (isOperatorOperand(operand) && operand.operator === "map") {
+    const [collection, lambda] = operand.operands;
+
+    if (
+      collection === undefined ||
+      !isNamedOperand(collection) ||
+      lambda === undefined ||
+      !isOperatorOperand(lambda) ||
+      lambda.operator !== "lambda"
+    ) {
+      return undefined;
+    }
+
+    const [projection, variable] = lambda.operands;
+
+    if (
+      projection === undefined ||
+      !isNamedOperand(projection) ||
+      variable === undefined ||
+      !isNamedOperand(variable)
+    ) {
+      return undefined;
+    }
+
+    const scoped = scopedContext(context, collection.name, variable.name);
+
+    if (scoped === undefined) return undefined;
+    const type = scalarType(resolveFieldReference(projection.name, scoped));
+
+    if (type === undefined) return undefined;
+
+    // A projected element column can be missing on an element, which errors the whole map().
+    return { type, mayBeMissing: true };
+  }
+
+  return undefined;
+}
+
+/** The declared valueType of the projected element column of a relation-backed list. */
+function elementFieldValueType(
+  context: TranslationContext,
+  reference: string,
+  field: string
+): MapperConfig["valueType"] {
+  const relation = lookupMapping(context.mapper, reference)?.relation;
+
+  return relation?.fields?.[field]?.valueType;
+}