@cerbos/orm-prisma 4.0.0 → 4.1.0

package/src/index.ts

@@ -124,6 +124,36 @@ export type MapperConfig = {
    * deny-aligned. Declaring nullability here enables those guards.
    */
   nullable?: boolean;
+  /**
+   * Declares that this column can be SQL NULL **and** how the caller represents that NULL in the
+   * attributes it sends to `check()`. Declaring it asserts both facts; leaving it undeclared means
+   * "treat this column as NOT NULL", which is the historical rendering.
+   *
+   * This is per attribute rather than per call because one policy suite can legitimately mix the
+   * two conventions — the same column can be mapped twice, sent as an explicit null under one
+   * attribute name and omitted under another. The call-level option cannot express that, which is
+   * what made cerbos/query-plan-adapters#308 unfixable with #302's option alone.
+   *
+   * - `"explicit"` — a NULL column is sent as an explicit `null` attribute, so CEL holds a null
+   *   VALUE. `null != "x"` is then TRUE and `null == "x"` is FALSE, both definite, while Prisma's
+   *   `{ not: "x" }` drops the row under both polarities. The equality family (`equals`, `not`,
+   *   `in`) is therefore rendered so it can never depend on SQL's UNKNOWN.
+   * - `"omitted"` — a NULL column sends no attribute, so CEL raises a missing-attribute error and
+   *   `check()` denies. Dropping the row is already right, so the rendering is unchanged; what the
+   *   declaration adds is the same null-operand rejection the call-level `"omitted"` performs,
+   *   scoped to this attribute.
+   *
+   * Only the equality family is affected. `lt`/`lte`/`gt`/`gte` and the string operators raise a
+   * no-overload error on a null receiver in CEL, which denies under both polarities exactly as a
+   * dropped row does, so they are left alone.
+   *
+   * Distinct from `nullable` above, which declares that a *relation element* column can be NULL so
+   * collection macros gain their three-valued guards. The two are independent: `nullable` is about
+   * what a subquery does with an UNKNOWN element, this is about what the caller sent to the PDP.
+   *
+   * See https://github.com/cerbos/query-plan-adapters/issues/308.
+   */
+  nullAttributeRepresentation?: NullAttributeRepresentation;
   relation?: {
     name: string;
     type: "one" | "many";
@@ -135,6 +165,29 @@ export type MapperConfig = {
     model?: string;
     field?: string;
     fields?: Record<string, MapperConfig>;
+    /**
+     * The predicate the application itself applies when it reads this relation — a soft-delete
+     * flag, a tenant column, a subtype discriminator, whatever narrows the rows that became the
+     * resource attributes.
+     *
+     * Prisma has no schema-level filtered relation. A `where` injected by a client extension or
+     * middleware rewrites the *top-level* query, never the nested `some`/`every`/`none` this
+     * adapter generates, so a narrowing the application applies to its own reads does not reach
+     * the subquery — and the subquery then matches records the application never serialised, a
+     * filter that returns rows the PDP denies. Declaring the predicate here restores the
+     * equality; the adapter cannot detect the omission, which is why the field is optional and
+     * silence is not a warning. See "Mapping hazards" in the README.
+     *
+     * It is a Prisma where-input over the RELATED model, ANDed into the nested filter, and it
+     * constrains every operator reached through this relation under both polarities. `every` is
+     * rewritten to the equivalent `none` so the restriction narrows the records examined rather
+     * than the records required to match.
+     *
+     * ```ts
+     * relation: { name: "tags", type: "many", subqueryFilter: { deletedAt: null } }
+     * ```
+     */
+    subqueryFilter?: PrismaFilter;
   };
 };
 
@@ -142,6 +195,22 @@ export type Mapper =
   | Record<string, MapperConfig>
   | ((key: string) => MapperConfig);
 
+/**
+ * How the caller represents a NULL column when building the attributes it sends to `check()`.
+ *
+ * The planner emits the same `eq(attr, null)` node either way, so the plan cannot reveal which
+ * convention is in use and the adapter has to be told.
+ *
+ * - `"explicit"` (default) — a NULL column is sent as an explicit `null` attribute. CEL compares
+ *   `null == null`, so `IS NULL` selects exactly the rows `check()` allows.
+ * - `"omitted"` — a NULL column sends no attribute at all. CEL then raises a missing-attribute
+ *   error, which Cerbos treats as a deny, so a filter that *selects* NULL rows returns rows the
+ *   PDP denies. Null comparison operands are rejected instead of translated.
+ *
+ * See https://github.com/cerbos/query-plan-adapters/issues/302.
+ */
+export type NullAttributeRepresentation = "explicit" | "omitted";
+
 export interface QueryPlanToPrismaArgs {
   queryPlan: PlanResourcesResponse;
   mapper?: Mapper;
@@ -151,6 +220,11 @@ export interface QueryPlanToPrismaArgs {
    * references and need the model name as their container.
    */
   model?: string;
+  /**
+   * Which NULL-column representation the caller uses when building `check()` attributes.
+   * Defaults to `"explicit"`, preserving the historical `IS NULL` translation.
+   */
+  nullAttributeRepresentation?: NullAttributeRepresentation;
 }
 
 export type QueryPlanToPrismaResult =
@@ -426,14 +500,21 @@ type RelationConfig = {
   model?: string;
   field?: string;
   nestedMapper?: Record<string, MapperConfig>;
+  subqueryFilter?: PrismaFilter;
 };
 
 type ResolvedFieldReference = {
   path: string[];
   relations?: RelationConfig[];
   valueType?: "dateTime";
+  nullAttributeRepresentation?: NullAttributeRepresentation;
 };
 
+/** Whether this reference is one the caller sends as an explicit `null` when the column is NULL. */
+function isExplicitNullReference(fieldRef: ResolvedFieldReference): boolean {
+  return fieldRef.nullAttributeRepresentation === "explicit";
+}
+
 type ResolvedValue = {
   value: any;
 };
@@ -450,38 +531,6 @@ function isResolvedValue(operand: ResolvedOperand): operand is ResolvedValue {
   return "value" in operand;
 }
 
-function getNamedOperand(
-  operands: PlanExpressionOperand[],
-  message: string
-): NamedOperand {
-  const operand = operands.find(isNamedOperand);
-  if (!operand) {
-    throw new Error(message);
-  }
-  return operand;
-}
-
-function getValueOperand(
-  operands: PlanExpressionOperand[],
-  message: string
-): ValueOperand {
-  const operand = operands.find(isValueOperand);
-  if (!operand) {
-    throw new Error(message);
-  }
-  return operand;
-}
-
-function requireResolvedFieldReference(
-  operand: ResolvedOperand,
-  message: string
-): ResolvedFieldReference {
-  if (!isResolvedFieldReference(operand)) {
-    throw new Error(message);
-  }
-  return operand;
-}
-
 function requireResolvedValue(
   operand: ResolvedOperand,
   message: string
@@ -510,16 +559,43 @@ function buildFieldEqualsFilter(
   return wrapRelations(fieldRef.relations, { [fieldName]: { equals: value } });
 }
 
+function buildDirectOrInLeaf(
+  fieldRef: ResolvedFieldReference,
+  values: Value[]
+): PrismaFilter {
+  const fieldName = getLeafField(fieldRef.path);
+  return values.length === 1
+    ? { [fieldName]: values[0] }
+    : { [fieldName]: { in: values } };
+}
+
 function buildFieldDirectOrInFilter(
   fieldRef: ResolvedFieldReference,
   values: Value[]
+): PrismaFilter {
+  return wrapRelations(fieldRef.relations, buildDirectOrInLeaf(fieldRef, values));
+}
+
+/**
+ * `field IS NOT NULL AND <leaf>`, so a NULL column makes the whole thing definitely FALSE rather
+ * than merely unmatched — which is what lets an enclosing `NOT` include the row.
+ *
+ * Prisma has no three-valued logic to expose: a record either matches a `where` or it does not.
+ * That is exactly why the guard has to be explicit — `{ NOT: { field: { equals: "x" } } }` leans on
+ * the generated SQL's UNKNOWN, which excludes the record under both polarities, and an
+ * explicit-null attribute needs the negation to include it.
+ *
+ * The guard is ANDed with the leaf BEFORE the relation wrapping, so both halves are evaluated
+ * against the same element rather than against two independently-matched ones.
+ */
+function guardedFieldFilter(
+  fieldRef: ResolvedFieldReference,
+  leaf: PrismaFilter
 ): PrismaFilter {
   const fieldName = getLeafField(fieldRef.path);
-  const baseFilter =
-    values.length === 1
-      ? { [fieldName]: values[0] }
-      : { [fieldName]: { in: values } };
-  return wrapRelations(fieldRef.relations, baseFilter);
+  return wrapRelations(fieldRef.relations, {
+    AND: [{ [fieldName]: { not: null } }, leaf],
+  });
 }
 
 function buildMembershipFilter(
@@ -527,12 +603,30 @@ function buildMembershipFilter(
   values: Value[]
 ): PrismaFilter {
   const nonNullValues = values.filter((value) => value !== null);
+  const carriesNull = nonNullValues.length !== values.length;
+  if (carriesNull) {
+    assertNullOperandTranslatable(
+      "a null element in an `in` list",
+      fieldRef.nullAttributeRepresentation
+    );
+  }
   const filters: PrismaFilter[] = [];
 
   if (nonNullValues.length > 0 || values.length === 0) {
-    filters.push(buildFieldDirectOrInFilter(fieldRef, nonNullValues));
+    // Without a null element nothing has made the membership definite yet: a NULL column is
+    // dropped by `{ in: [...] }` under BOTH polarities, while CEL compares a null VALUE against
+    // each element and gets a definite false, so its negation is TRUE. With a null element the
+    // `[null]` disjunct below already settles it.
+    filters.push(
+      carriesNull || !isExplicitNullReference(fieldRef)
+        ? buildFieldDirectOrInFilter(fieldRef, nonNullValues)
+        : guardedFieldFilter(
+            fieldRef,
+            buildDirectOrInLeaf(fieldRef, nonNullValues)
+          )
+    );
   }
-  if (nonNullValues.length !== values.length) {
+  if (carriesNull) {
     filters.push(buildFieldDirectOrInFilter(fieldRef, [null]));
   }
 
@@ -563,6 +657,33 @@ type LambdaScope = {
 };
 let lambdaScopes: LambdaScope[] = [];
 let rootModelName: string | undefined;
+let nullRepresentation: NullAttributeRepresentation = "explicit";
+
+/**
+ * Guards every site that would emit a NULL-selecting predicate out of a `null` comparison
+ * operand.
+ *
+ * Under the `"omitted"` representation a NULL column carries no attribute, so CEL raises a
+ * missing-attribute error and `check()` denies the row — `IS NULL` would return exactly the rows
+ * the PDP refuses. The rejection is deliberately wider than the over-granting shapes: `ne(x,
+ * null)` on its own is aligned, but Prisma applies negation by wrapping (`{ NOT: ... }`) rather
+ * than by pushing it into the leaf, so a leaf cannot tell whether an enclosing `not` will flip
+ * `IS NOT NULL` back into a NULL-selecting predicate. Rejecting every null operand is correct
+ * under any nesting; narrowing it requires negation-parity tracking.
+ */
+function assertNullOperandTranslatable(
+  context: string,
+  declared?: NullAttributeRepresentation
+): void {
+  if ((declared ?? nullRepresentation) === "omitted") {
+    throw new Error(
+      `Cannot translate ${context} under nullAttributeRepresentation "omitted": a NULL column ` +
+        "sends no attribute, so Cerbos evaluates the comparison as a missing-attribute error " +
+        "(deny) while a NULL-selecting filter would return those rows. Send NULL columns as " +
+        'explicit nulls and use "explicit", or keep this shape out of the policy.'
+    );
+  }
+}
 
 /**
  * Converts a Cerbos query plan to a Prisma filter.
@@ -571,7 +692,9 @@ export function queryPlanToPrisma({
   queryPlan,
   mapper = {},
   model,
+  nullAttributeRepresentation = "explicit",
 }: QueryPlanToPrismaArgs): QueryPlanToPrismaResult {
+  nullRepresentation = nullAttributeRepresentation;
   switch (queryPlan.kind) {
     case PlanKind.ALWAYS_ALLOWED:
       return { kind: PlanKind.ALWAYS_ALLOWED };
@@ -595,6 +718,18 @@ export function queryPlanToPrisma({
           "A constant-false conditional predicate must be folded by the Cerbos planner"
         );
       }
+      // A `map()` at the ROOT of the condition returns a list, not a boolean. Translating it
+      // produces a projection filter that is not a valid Prisma `where` clause — the shape
+      // must be refused HERE rather than left for findMany to reject at query time, because
+      // a projection that happened to coerce would be a silently-wrong filter. (`filter()`
+      // as a condition is already rejected inside handleCollectionOperator with its own
+      // message; nested inside a comparison or size() both remain translatable.)
+      if (isOperatorOperand(condition) && condition.operator === "map") {
+        throw new Error(
+          "map() returns a list, not a boolean, so it cannot be a condition on its own; " +
+            "only comparisons or size() over its result have a boolean meaning"
+        );
+      }
       return {
         kind: PlanKind.CONDITIONAL,
         filters: buildPrismaFilterFromCerbosExpression(condition, mapper),
@@ -1020,6 +1155,7 @@ function resolveFieldReference(
         model: activeConfig.relation.model,
         field: activeConfig.relation.field,
         nestedMapper: fields,
+        subqueryFilter: activeConfig.relation.subqueryFilter,
       },
     ];
 
@@ -1046,6 +1182,7 @@ function resolveFieldReference(
             model: nextConfig.relation.model,
             field: nextConfig.relation.field,
             nestedMapper: nextConfig.relation.fields,
+            subqueryFilter: nextConfig.relation.subqueryFilter,
           });
           currentMapper = nextConfig.relation.fields || {};
           currentParts = currentParts.slice(1);
@@ -1064,6 +1201,7 @@ function resolveFieldReference(
       path: field ? [field] : remainingParts,
       relations,
       valueType: activeConfig.valueType,
+      nullAttributeRepresentation: activeConfig.nullAttributeRepresentation,
     };
   }
 
@@ -1071,6 +1209,7 @@ function resolveFieldReference(
   return {
     path: [activeConfig?.field || reference],
     valueType: activeConfig?.valueType,
+    nullAttributeRepresentation: activeConfig?.nullAttributeRepresentation,
   };
 }
 
@@ -1085,9 +1224,167 @@ function getPrismaRelationOperator(relation: {
   return relation.type === "one" ? "is" : "some";
 }
 
+/**
+ * One relation-scoped filter (`{ tags: { some: … } }`), narrowed by the store-side predicate the
+ * caller declared on the mapping.
+ *
+ * Every nested relation filter the adapter emits goes through here, so a declared
+ * `subqueryFilter` reaches the collection macros, the membership shapes, the emptiness checks and
+ * the hop-existence guard alike. Adding a new relation shape means routing it through here, or
+ * the declaration silently stops applying to it.
+ *
+ * `every` is the one operator that cannot simply absorb the predicate. `{ every: AND(W, P) }`
+ * would REQUIRE every record to satisfy W, which is the opposite of "ignore the records W hides",
+ * so it is rewritten to `{ none: AND(W, NOT P) }` — no visible record violates P. Both agree with
+ * `every` when nothing is declared, and both stay vacuously true over an empty relation.
+ */
+function relationFilter(
+  relation: RelationConfig,
+  operator: string,
+  inner: PrismaFilter
+): PrismaFilter {
+  const declared = relation.subqueryFilter;
+  if (declared === undefined) {
+    return { [relation.name]: { [operator]: inner } };
+  }
+  const narrow = (filter: PrismaFilter): PrismaFilter =>
+    Object.keys(filter).length === 0 ? declared : { AND: [declared, filter] };
+  if (operator === "every") {
+    return Object.keys(inner).length === 0
+      ? { [relation.name]: { every: inner } }
+      : { [relation.name]: { none: { AND: [declared, { NOT: inner }] } } };
+  }
+  return { [relation.name]: { [operator]: narrow(inner) } };
+}
+
 /**
  * Builds a nested relation filter for Prisma queries.
  */
+/**
+ * "Every intermediate hop of a dotted path exists", as a Prisma filter.
+ *
+ * CEL cannot dot through a list, so each intermediate segment of `a.b.c` is a to-ONE
+ * parent: absent, the caller sends no attribute and CEL raises a missing-path error, which
+ * denies. `NOT { categories: { some: { subCategories: { some: P } } } }` is TRUE for a row
+ * with no category at all, so the negation returns rows the PDP denies — the parent must be
+ * required separately (cerbos/query-plan-adapters#309).
+ *
+ * Returns undefined when the reference has no intermediate hop, so a direct relation keeps
+ * its empty-collection semantics (`!tags.exists(...)` over zero tags is still TRUE).
+ */
+function buildLeadingHopsExistFilter(
+  head: RelationConfig,
+  restRelations: RelationConfig[]
+): PrismaFilter | undefined {
+  if (restRelations.length === 0) {
+    return undefined;
+  }
+  // The last entry is the collection being iterated; everything before it is a hop.
+  return buildHopsExistFilter([head, ...restRelations.slice(0, -1)]);
+}
+
+/**
+ * "Every one of these relations exists", as a nested Prisma filter with an empty innermost
+ * predicate — `{ parent: { is: { inner: { is: {} } } } }`.
+ */
+function buildHopsExistFilter(
+  hops: RelationConfig[]
+): PrismaFilter | undefined {
+  if (hops.length === 0) {
+    return undefined;
+  }
+  let inner: PrismaFilter = {};
+  for (let i = hops.length - 1; i >= 0; i--) {
+    const relation = assertDefined(hops[i], "Relation mapping is missing");
+    inner = relationFilter(relation, getPrismaRelationOperator(relation), inner);
+  }
+  return inner;
+}
+
+/**
+ * "Every to-one hop this expression dots through exists", as a Prisma filter, or undefined
+ * when it dots through none.
+ *
+ * Prisma has no UNKNOWN: a chained relation filter is exact under the POSITIVE polarity —
+ * `categories: { some: { subCategories: { some: P } } }` cannot hold without the category —
+ * but `NOT` inverts the hop requirement along with the predicate, so every operator built on
+ * a chain readmits the parentless rows once negated. #309 fixed that inside the collection
+ * macros, which left the sibling operators reached through the same chain unguarded:
+ * membership and `hasIntersection` (cerbos/query-plan-adapters#315), and the negated count
+ * spelling `!(size(chain) > 0)` (#316), all of which the macros' guard never saw.
+ *
+ * Requiring the hops OUTSIDE the negation is what fixes all of them at once, and it is
+ * unconditionally faithful to CEL rather than a per-operator patch: a missing hop is a
+ * missing-path error, which denies under BOTH polarities, so the requirement never depends
+ * on which operator sits above the chain.
+ *
+ * Lambda bodies are deliberately not walked — their references resolve against a scoped
+ * mapper, and a negated macro carries its own guard through buildNegatedCollectionFilter.
+ */
+function buildExpressionHopsExistFilter(
+  operand: PlanExpressionOperand,
+  mapper: Mapper
+): PrismaFilter | undefined {
+  const hops: PrismaFilter[] = [];
+  const seen = new Set<string>();
+
+  const visit = (expr: PlanExpressionOperand): void => {
+    if (isNamedOperand(expr)) {
+      if (seen.has(expr.name)) {
+        return;
+      }
+      seen.add(expr.name);
+      const { relations } = resolveFieldReference(expr.name, mapper);
+      if (!relations || relations.length === 0) {
+        return;
+      }
+      // Every to-ONE relation on the path is a hop that must EXIST — including a TRAILING one,
+      // which is the case a chain of to-many relations never produces. `parent.aBool` resolves
+      // to a single to-one relation, and `NOT { parent: { is: { aBool: true } } }` is TRUE for
+      // a row with no parent at all, so the negation returns rows the PDP denies. A trailing
+      // to-MANY relation is the collection being iterated rather than a hop, and keeps its
+      // empty-collection semantics (`!tags.exists(...)` over zero tags is still TRUE).
+      const last = assertDefined(
+        relations[relations.length - 1],
+        "Relation mapping is missing"
+      );
+      const hopFilter = buildHopsExistFilter(
+        last.type === "one" ? relations : relations.slice(0, -1)
+      );
+      if (hopFilter !== undefined) {
+        hops.push(hopFilter);
+      }
+      return;
+    }
+    if (!isOperatorOperand(expr) || expr.operator === "lambda") {
+      return;
+    }
+    expr.operands.forEach(visit);
+  };
+
+  visit(operand);
+
+  if (hops.length === 0) {
+    return undefined;
+  }
+  return hops.length === 1
+    ? assertDefined(hops[0], "Leading-hops filter is missing")
+    : { AND: hops };
+}
+
+/**
+ * `{ NOT: filter }`, with every to-one hop `operand` dots through required OUTSIDE the
+ * negation so an absent parent stays denied (see buildExpressionHopsExistFilter).
+ */
+function negateRequiringHops(
+  operand: PlanExpressionOperand,
+  filter: PrismaFilter,
+  mapper: Mapper
+): PrismaFilter {
+  const hops = buildExpressionHopsExistFilter(operand, mapper);
+  return hops === undefined ? { NOT: filter } : { AND: [hops, { NOT: filter }] };
+}
+
 function buildNestedRelationFilter(
   relations: RelationConfig[],
   fieldFilter: any
@@ -1114,7 +1411,7 @@ function buildNestedRelationFilter(
       }
     }
 
-    currentFilter = { [relation.name]: { [relationOperator]: currentFilter } };
+    currentFilter = relationFilter(relation, relationOperator, currentFilter);
   }
 
   return currentFilter;
@@ -1339,10 +1636,6 @@ function buildPrismaFilterFromCerbosExpression(
       return handleStringOperator(operator, operands, mapper);
     }
 
-    case "isSet": {
-      return handleIsSetOperator(operands, mapper);
-    }
-
     case "hasIntersection": {
       return handleHasIntersectionOperator(operands, mapper);
     }
@@ -1390,6 +1683,26 @@ function containsCollectionOperator(expr: PlanExpressionOperand): boolean {
   return expr.operands.some(containsCollectionOperator);
 }
 
+/**
+ * Whether `expr` dots through at least one intermediate to-one hop, so negating it needs the
+ * hop requirement of buildExpressionHopsExistFilter.
+ */
+function referencesChainedRelation(
+  expr: PlanExpressionOperand,
+  mapper: Mapper
+): boolean {
+  if (isNamedOperand(expr)) {
+    const { relations } = resolveFieldReference(expr.name, mapper);
+    return relations !== undefined && relations.length > 1;
+  }
+  if (!isOperatorOperand(expr) || expr.operator === "lambda") {
+    return false;
+  }
+  return expr.operands.some((operand) =>
+    referencesChainedRelation(operand, mapper)
+  );
+}
+
 /**
  * Builds the filter for `!expr`. Plain field predicates negate correctly with Prisma's NOT
  * (SQL three-valued logic keeps NULL rows excluded under both polarities), but relation
@@ -1417,12 +1730,23 @@ function buildNegatedFilter(
     if (!relations || relations.length === 0) {
       return buildFieldEqualsFilter(fieldRef, false);
     }
-    return {
-      NOT: buildPrismaFilterFromCerbosExpression(operand, mapper),
-    };
+    return negateRequiringHops(
+      operand,
+      buildPrismaFilterFromCerbosExpression(operand, mapper),
+      mapper
+    );
   }
 
-  if (isOperatorOperand(operand) && containsCollectionOperator(operand)) {
+  // `and`/`or` must be pushed through with De Morgan whenever a branch can be UNKNOWN, so
+  // CEL's error absorption survives: `!(A && B)` with A erroring and B false is TRUE in CEL,
+  // and `OR[!A, !B]` reproduces that where a single outer NOT over the conjunction — with the
+  // hop requirement ANDed outside it — would deny. A chained relation is the second source of
+  // UNKNOWN besides the collection macros, so it opens the same push-down.
+  if (
+    isOperatorOperand(operand) &&
+    (containsCollectionOperator(operand) ||
+      referencesChainedRelation(operand, mapper))
+  ) {
     switch (operand.operator) {
       case "and":
         return {
@@ -1453,9 +1777,11 @@ function buildNegatedFilter(
     }
   }
 
-  return {
-    NOT: buildPrismaFilterFromCerbosExpression(operand, mapper),
-  };
+  return negateRequiringHops(
+    operand,
+    buildPrismaFilterFromCerbosExpression(operand, mapper),
+    mapper
+  );
 }
 
 function getTernaryOperands(operands: PlanExpressionOperand[]): {
@@ -1515,6 +1841,18 @@ function buildBooleanBranchFilter(
   return { kind: "constant", value: branch.value };
 }
 
+/**
+ * "The ternary's condition is definitively FALSE", which is exactly buildNegatedFilter's
+ * contract — three-valued, so a condition that is UNKNOWN (a NULL column, an erroring lambda
+ * body, an absent to-one parent) selects NEITHER branch.
+ *
+ * It delegates rather than spelling a second negation. A private copy is how the ternary
+ * missed the hop requirement #315/#316 added: a bare `NOT` over a chain filter is TRUE when
+ * the to-one parent is absent, so the else-branch was selected for rows CEL denies outright —
+ * the missing path is an evaluation error, not a false condition
+ * (cerbos/query-plan-adapters#334). Delegating also gives the ternary the De Morgan push-down,
+ * which a chained `and`/`or` condition needs for CEL's error absorption to survive.
+ */
 function buildFalseConditionFilter(
   condition: PlanExpressionOperand,
   mapper: Mapper
@@ -1523,26 +1861,7 @@ function buildFalseConditionFilter(
     throw new Error("Constant ternary conditions must be folded before use");
   }
 
-  if (isNamedOperand(condition)) {
-    const fieldRef = resolveFieldReference(condition.name, mapper);
-    if (!fieldRef.relations || fieldRef.relations.length === 0) {
-      return buildFieldEqualsFilter(fieldRef, false);
-    }
-    return {
-      NOT: buildFieldEqualsFilter(fieldRef, true),
-    };
-  }
-
-  if (isOperatorOperand(condition) && condition.operator === "not") {
-    return buildPrismaFilterFromCerbosExpression(
-      assertDefined(condition.operands[0], "not operator requires an operand"),
-      mapper
-    );
-  }
-
-  return {
-    NOT: buildPrismaFilterFromCerbosExpression(condition, mapper),
-  };
+  return buildNegatedFilter(condition, mapper);
 }
 
 function buildGuardedTernaryFilter({
@@ -1886,7 +2205,7 @@ function handleSizeComparison(
   }
 
   const prismaOp = isNonEmpty ? "some" : "none";
-  const leafFilter = { [deepest.name]: { [prismaOp]: {} } };
+  const leafFilter = relationFilter(deepest, prismaOp, {});
 
   if (relations.length === 1) {
     return leafFilter;
@@ -2023,6 +2342,31 @@ function buildComparisonFilter(
     `Unsupported operator: ${operator}`
   );
 
+  if (value === null) {
+    assertNullOperandTranslatable(
+      `\`${operator}\` against a null operand`,
+      fieldRef.nullAttributeRepresentation
+    );
+  }
+
+  // An attribute the caller sends as an explicit null holds a null VALUE in CEL, so equality
+  // against a non-null operand is a definite FALSE and inequality a definite TRUE. Prisma leans
+  // on SQL's UNKNOWN for both, which drops the row under either polarity, so the presence of the
+  // column has to become part of the predicate. Confined to the equality family: an ordering
+  // comparison against a null receiver is a no-overload error in CEL, which denies exactly as the
+  // dropped row does.
+  if (value !== null && isExplicitNullReference(fieldRef)) {
+    const fieldName = getLeafField(fieldRef.path);
+    if (operator === "eq") {
+      return guardedFieldFilter(fieldRef, { [fieldName]: { equals: value } });
+    }
+    if (operator === "ne") {
+      return {
+        NOT: guardedFieldFilter(fieldRef, { [fieldName]: { equals: value } }),
+      };
+    }
+  }
+
   if (typeof value === "number" && !Number.isInteger(value)) {
     const fieldName = getLeafField(fieldRef.path);
     const lower = Math.floor(value);
@@ -2135,11 +2479,55 @@ function buildFieldToFieldFilter(
 
   const leftField = getLeafField(left.path);
   const rightField = getLeafField(right.path);
-  return {
-    [leftField]: {
-      [prismaOperator]: { _ref: rightField, _container: container },
-    },
-  };
+  const fieldReference = { _ref: rightField, _container: container };
+
+  // Two explicit nulls are EQUAL in CEL, and a null against a value is definitely NOT equal.
+  // A bare field reference gives UNKNOWN for both, which drops the row under either polarity.
+  const leftExplicit = isExplicitNullReference(left);
+  const rightExplicit = isExplicitNullReference(right);
+  // Mixing the two conventions across one comparison has no faithful rendering. The declared side
+  // needs a definite answer for its NULL (CEL holds a null VALUE); the undeclared side needs
+  // UNKNOWN for its NULL (a missing attribute, which CEL denies under both polarities). A definite
+  // predicate returns rows the PDP refuses; a plain one drops rows the PDP allows. Refuse it
+  // rather than pick a direction — declare both attributes, or neither.
+  if (leftExplicit !== rightExplicit && (operator === "eq" || operator === "ne")) {
+    throw new Error(
+      `Cannot translate \`${operator}\` between two columns under mixed null conventions: ` +
+        "cannot compare an attribute declared explicit-null with one on the omitted convention: the omitted side is UNKNOWN for a NULL column while the declared side is definite, and no single predicate is both. Declare nullAttributeRepresentation on both mapper entries, or on neither."
+    );
+  }
+  if (leftExplicit && rightExplicit && (operator === "eq" || operator === "ne")) {
+    const present: PrismaFilter[] = [];
+    if (leftExplicit) {
+      present.push({ [leftField]: { not: null } });
+    }
+    if (rightExplicit) {
+      present.push({ [rightField]: { not: null } });
+    }
+    const equality: PrismaFilter =
+      leftExplicit && rightExplicit
+        ? {
+            OR: [
+              { AND: [{ [leftField]: null }, { [rightField]: null }] },
+              { AND: [...present, { [leftField]: { equals: fieldReference } }] },
+            ],
+          }
+        : { AND: [...present, { [leftField]: { equals: fieldReference } }] };
+    return operator === "eq" ? equality : { NOT: equality };
+  }
+
+  // `ne` is the one operator whose Prisma spelling cannot carry a field reference: `not` nests a
+  // NestedStringFilter, which has no `_ref` form, so `{ col: { not: { _ref } } }` is rejected by
+  // the client rather than executed. Hoisting the negation to the top-level `NOT` combinator says
+  // the same thing with a shape that does accept one — the same rewrite the explicit-null branch
+  // above already performs. Three-valued logic is unchanged by the hoist: a NULL on either side
+  // makes the inner equality UNKNOWN, and `NOT UNKNOWN` is still UNKNOWN, so the row stays out
+  // under both polarities, which is what a missing attribute does on the check side.
+  if (operator === "ne") {
+    return { NOT: { [leftField]: { equals: fieldReference } } };
+  }
+
+  return { [leftField]: { [prismaOperator]: fieldReference } };
 }
 
 /**
@@ -2220,10 +2608,18 @@ function handleStringOperator(
     // Prisma emits LIKE without an ESCAPE clause and does not escape wildcard characters,
     // so a needle containing % or _ would match as a pattern instead of literally (e.g.
     // startsWith("100%") wrongly matches "100xdone"). Fail loudly rather than filter wrong.
-    if (/[%_]/.test(value)) {
+    //
+    // A backslash is the same hazard reached from the other direction, and only an executed
+    // PostgreSQL leg surfaces it (cerbos/query-plan-adapters#320): SQLite's LIKE has no escape
+    // character at all, so `\` is literal there, while PostgreSQL and MySQL treat it as the
+    // DEFAULT escape character even with no ESCAPE clause. `endsWith("\\")` is then a pattern
+    // ending in an escape character — a hard error on PostgreSQL — and a `\x` anywhere inside
+    // silently drops the backslash, so `contains("a\\b")` matches "ab", a row the PDP denies.
+    if (/[%_\\]/.test(value)) {
       throw new Error(
-        `Cannot translate ${operator} with a needle containing LIKE metacharacters (% or _): ` +
-          "Prisma does not escape wildcards in string filters"
+        `Cannot translate ${operator} with a needle containing LIKE metacharacters (%, _ or \\): ` +
+          "Prisma does not escape wildcards in string filters, and \\ is the default LIKE " +
+          "escape character on PostgreSQL and MySQL"
       );
     }
     const fieldName = getLeafField(receiver.path);
@@ -2282,30 +2678,6 @@ function handleStringOperator(
   );
 }
 
-/**
- * Helper function to handle "isSet" operator
- */
-function handleIsSetOperator(
-  operands: PlanExpressionOperand[],
-  mapper: Mapper
-): PrismaFilter {
-  const nameOperand = getNamedOperand(operands, "Name operand is undefined");
-  const valueOperand = getValueOperand(operands, "Value operand is undefined");
-  const fieldRef = requireResolvedFieldReference(
-    resolveOperand(nameOperand, mapper),
-    "Name operand must resolve to a field reference"
-  );
-  const resolvedValue = requireResolvedValue(
-    resolveOperand(valueOperand, mapper),
-    "Value operand must resolve to a value"
-  );
-
-  const fieldName = getLeafField(fieldRef.path);
-  return wrapRelations(fieldRef.relations, {
-    [fieldName]: resolvedValue.value ? { not: null } : { equals: null },
-  });
-}
-
 /**
  * Helper function to handle "hasIntersection" operator
  */
@@ -2635,7 +3007,7 @@ function wrapCollectionElementFilter(
     parts.restRelations.length > 0
       ? buildNestedRelationFilter(parts.restRelations, elementFilter)
       : elementFilter;
-  return { [parts.head.name]: { some: inner } };
+  return relationFilter(parts.head, "some", inner);
 }
 
 function throwUnsupportedCollectionOperator(operator: string): never {
@@ -2680,7 +3052,7 @@ function handleCollectionOperator(
     case "exists": {
       // A NULL element keeps the per-element predicate UNKNOWN, so it can never create a
       // false positive here; a CEL error (deny) coincides with "no match" — no guard needed.
-      const filter = { [head.name]: { some: filterValue } };
+      const filter = relationFilter(head, "some", filterValue);
       const unknownElement = buildUnknownElementFilter(parts);
       if (unknownElement !== undefined) {
         recordNestedCollectionUnknownFilter({
@@ -2693,14 +3065,14 @@ function handleCollectionOperator(
       return filter;
     }
     case "except":
-      return { [head.name]: { some: { NOT: filterValue } } };
+      return relationFilter(head, "some", { NOT: filterValue });
     case "all": {
       if (parts.restRelations.length > 0) {
         throw new Error(
           "all() over a multi-hop relation chain is not supported"
         );
       }
-      const base = { [head.name]: { every: filterValue } };
+      const base = relationFilter(head, "every", filterValue);
       if (nullableFields.size === 0) {
         return base;
       }
@@ -2711,7 +3083,7 @@ function handleCollectionOperator(
       return {
         AND: [
           base,
-          { [head.name]: { none: buildNullWitnessFilter(nullableFields) } },
+          relationFilter(head, "none", buildNullWitnessFilter(nullableFields)),
         ],
       };
     }
@@ -2745,10 +3117,22 @@ function buildNegatedCollectionFilter(
 
   const parts = buildCollectionLambdaParts(operator, operands, mapper);
   const { head, filterValue, nullableFields } = parts;
+  // An absent to-one parent must stay denied under negation rather than satisfying it
+  // vacuously (#309).
+  const leadingHopsExist = buildLeadingHopsExistFilter(
+    head,
+    parts.restRelations
+  );
+  const requireLeadingHops = (filter: PrismaFilter): PrismaFilter =>
+    leadingHopsExist === undefined
+      ? filter
+      : { AND: [leadingHopsExist, filter] };
 
   switch (operator) {
     case "exists": {
-      const base = { NOT: { [head.name]: { some: filterValue } } };
+      const base = requireLeadingHops({
+        NOT: relationFilter(head, "some", filterValue),
+      });
       const unknownElement = buildUnknownElementFilter(parts);
       if (unknownElement === undefined) {
         return base;
@@ -2770,17 +3154,19 @@ function buildNegatedCollectionFilter(
     case "all":
       // !all is TRUE only with a definitive false witness, which also absorbs error
       // elements — exactly `some(NOT P)` in SQL (NULL columns keep NOT P UNKNOWN).
-      return { [head.name]: { some: { NOT: filterValue } } };
+      return relationFilter(head, "some", { NOT: filterValue });
     case "except": {
       // !except(c,P) = every element definitively matches P.
-      const base = { [head.name]: { none: { NOT: filterValue } } };
+      const base = requireLeadingHops(
+        relationFilter(head, "none", { NOT: filterValue })
+      );
       if (nullableFields.size === 0) {
         return base;
       }
       return {
         AND: [
           base,
-          { [head.name]: { none: buildNullWitnessFilter(nullableFields) } },
+          relationFilter(head, "none", buildNullWitnessFilter(nullableFields)),
         ],
       };
     }
@@ -3267,15 +3653,18 @@ function handleOverlapsOperator(
  *
  * `startsWith` compiles to `LIKE` with no `ESCAPE` clause, so `%` and `_` in the prefix
  * match as wildcards instead of literally and widen the filter past what the PDP allows.
- * `[` is unsafe for a separate reason: SQL Server opens a character class on `[` even when
- * an `ESCAPE` clause is declared, so it cannot be made literal at all. Fail loudly rather
- * than emit a filter that admits denied rows.
+ * `\` is unsafe because PostgreSQL and MySQL treat it as the DEFAULT escape character with no
+ * `ESCAPE` clause present, where SQLite has none at all — so the same prefix means different
+ * things per provider. `[` is unsafe for a third reason: SQL Server opens a character class on
+ * `[` even when an `ESCAPE` clause is declared, so it cannot be made literal at all. Fail loudly
+ * rather than emit a filter that admits denied rows.
  */
 function assertLikeSafePrefix(prefix: string): void {
-  if (/[%_\[]/.test(prefix)) {
+  if (/[%_\[\\]/.test(prefix)) {
     throw new Error(
-      "Cannot translate hierarchy prefix matching with LIKE metacharacters (%, _ or [): " +
-        "Prisma emits LIKE without an ESCAPE clause, and [ opens a character class on SQL Server even with one"
+      "Cannot translate hierarchy prefix matching with LIKE metacharacters (%, _, \\ or [): " +
+        "Prisma emits LIKE without an ESCAPE clause, \\ is the default escape character on " +
+        "PostgreSQL and MySQL, and [ opens a character class on SQL Server even with one"
     );
   }
 }