@cerbos/orm-prisma 4.1.0 → 5.0.0

package/src/translator.test.ts

@@ -1,1305 +1,320 @@
-import * as fs from "fs";
-import * as path from "path";
-
 import { describe, expect, test } from "@jest/globals";
+import type { JsonValue } from "@bufbuild/protobuf";
 import type {
   PlanExpressionOperand,
   PlanResourcesResponse,
+  Value,
 } from "@cerbos/core";
 
-import { queryPlanToPrisma, PlanKind } from ".";
+import { queryPlanToPrisma, PlanKind, UnsupportedQueryPlanError } from ".";
 import type {
   Mapper,
+  MapperConfig,
   NullAttributeRepresentation,
   PrismaFilter,
   QueryPlanToPrismaResult,
 } from ".";
-import {
-  CONFORMANCE_DIR,
-  MAPPER,
-  MODEL,
-  classifyActionsForAdapter,
-  planFromWireFixture,
-  wireFixtureActions,
-} from "./corpus";
-import type { ActionsFile } from "./corpus";
+import { MAPPER, MODEL, pdpTags, planOf, readGolden, readGoldens } from "./corpus";
+import { isObject } from "./narrowing";
+
+type Relation = NonNullable<MapperConfig["relation"]>;
+
+/** `response` with `field` replaced by a value its type rules out: a plan the SDK never decodes. */
+const overwritten = (response: PlanResourcesResponse, field: string, value: Value): PlanResourcesResponse =>
+  Object.defineProperty({ ...response }, field, { value, enumerable: true });
 
 /**
- * Translator unit test: for every action in the shared `../conformance/` corpus, the filter this
- * adapter emits. Offline — no Cerbos sidecar, no database, no generated Prisma client.
- *
- * A per-adapter suite used to braid four assertions into every test. Three of them are somebody
- * else's job now, and this file makes only the fourth:
+ * Offline unit tests: what a caller can pass that the conformance corpus cannot vary (mapper forms,
+ * `subqueryFilter`, element nullability, `nullAttributeRepresentation`), the refusal type, the
+ * timestamp literal contract, and plans the planner cannot produce.
  *
- * | assertion | who owns it |
- * | --- | --- |
- * | the plan the PDP produces for a policy | `conformance/wire-fixtures/`, replanned and diffed by the `Conformance Corpus` workflow |
- * | which shapes this adapter must refuse, and with what message | `conformance/actions.json` — read below, not restated |
- * | the rows a filter returns | `adversarial.test.ts`, against a real store with `check()` as the oracle |
- * | **the filter this adapter emits for a plan** | **here** |
- *
- * **The plans are read, not written.** A hand-built plan is a *belief* about what the planner
- * emits, and this repository keeps golden fixtures because that belief has been wrong before: a
- * planner change used to fail fixture regeneration and silently leave every adapter's hand-written
- * plans describing a wire contract that no longer existed. Sourcing from fixtures inverts that —
- * the drift check now protects the plans this file asserts against. See
- * [ADR 0006](../../docs/adr/0006-translator-unit-tests-take-their-plans-from-wire-fixtures.md).
- *
- * **What a pinned filter buys over the harness.** The harness proves the filter returns the right
- * rows *against the 21 rows it seeds*. Two different filters can agree on all of them and
- * disagree on the row a consumer has, so a rewrite that quietly changes the emitted SQL passes
- * there and shows up here as a diff a reviewer reads. It is also the only place a
- * `nullAttributeRepresentation` boundary, a timestamp literal, or a mapping the corpus cannot
- * express (`subqueryFilter`) can be pinned at all.
- *
- * **Adding a corpus action fails this file.** Every wire fixture must be classified here exactly
- * once — expected filter, expected plan kind, or expected throw — and the guard at the bottom is
- * what makes a new action land as a failure rather than as silence.
+ * Which rows a corpus case returns is the conformance harness's job (`adversarial.test.ts`); nothing
+ * here pins the filter emitted for a corpus case. Plans come from the current PDP's golden files,
+ * read by case id, rather than being typed by hand.
  */
 
-const actionsFile: ActionsFile = JSON.parse(
-  fs.readFileSync(path.join(CONFORMANCE_DIR, "actions.json"), "utf8")
-);
+const CURRENT = pdpTags()[0]!;
 
-/**
- * The shapes `actions.json` says this adapter must refuse, each with the message it must refuse
- * them with. Identical to the classification `adversarial.test.ts` asserts against a live PDP;
- * asserting it here as well is what lets the completeness guard below be total, and it costs a
- * millisecond rather than a container.
- */
-const { throwingActions: THROWING_ACTIONS } = classifyActionsForAdapter(
-  actionsFile,
-  "prisma"
-);
+/** The current PDP's recorded plan for a corpus case, `__NOW_MINUS_24H__` filled as `now`. */
+function planFor(id: string, now?: string): Promise<PlanResourcesResponse> {
+  return planOf(readGolden(CURRENT, id), now);
+}
 
-function translate(
-  action: string,
+async function translate(
+  id: string,
   options: {
     mapper?: Mapper;
     nullAttributeRepresentation?: NullAttributeRepresentation;
   } = {}
-): QueryPlanToPrismaResult {
+): Promise<QueryPlanToPrismaResult> {
   return queryPlanToPrisma({
-    queryPlan: planFromWireFixture(action),
+    queryPlan: await planFor(id),
     mapper: options.mapper ?? MAPPER,
     model: MODEL,
-    ...(options.nullAttributeRepresentation
-      ? { nullAttributeRepresentation: options.nullAttributeRepresentation }
-      : {}),
+    // Varied explicitly below; the adapter's own default is pinned under "nullAttributeRepresentation".
+    nullAttributeRepresentation: options.nullAttributeRepresentation ?? "explicit",
   });
 }
 
-/**
- * The plan kind for the two corpus actions the planner resolves without a condition.
- *
- * `p-has` is `knownDivergences` for every adapter — the planner folds `has(unknown attr)` to
- * ALWAYS_ALLOWED, so the harness cannot compare it against the oracle. Translation is still
- * defined, and pinning it here is the only assertion the corpus makes about the action.
- */
-const EXPECTED_KINDS: Record<
-  string,
-  PlanKind.ALWAYS_ALLOWED | PlanKind.ALWAYS_DENIED
-> = {
-  "in-empty": PlanKind.ALWAYS_DENIED,
-  "p-has": PlanKind.ALWAYS_ALLOWED,
-};
+describe("the refusal type", () => {
+  test("an untranslatable shape raises UnsupportedQueryPlanError, which is an Error", async () => {
+    let raised: unknown;
 
-/**
- * The `where` input this adapter emits for every corpus action it can translate, under `MAPPER`
- * and the default (`"explicit"`) null representation.
- *
- * Alphabetical by action, so the diff of a translator change reads as a list of the shapes it
- * moved. Comments are on the entries where the emitted shape is the whole point of the action;
- * the rest are pins.
- */
-const EXPECTED_FILTERS: Record<string, PrismaFilter> = {
-  // The three-valued-logic guard. `every` collapses UNKNOWN to false at the EXISTS boundary, so
-  // an element whose `name` is NULL would be silently satisfied; CEL raises a missing-attribute
-  // error and check() denies. The second conjunct is what keeps the two aligned, and it is only
-  // emitted because the mapper declares `name` nullable.
-  "all-on-empty": {
-    AND: [
-      { tags: { every: { name: { equals: "public" } } } },
-      { tags: { none: { name: null } } },
-    ],
-  },
-  "arith-add": { aNumber: { gt: 1 } },
-  "arith-div": { aNumber: { equals: 2 } },
-  "arith-div-frac": { aNumber: { gte: 3 } },
-  "arith-mult-neg": { OR: [{ aNumber: { gt: -1.5 } }, { aNumber: { gte: -1 } }] },
-  "arith-sub": { aNumber: { lte: 3 } },
-  // Value-first: the plan reads `K < add(aNumber, K)`, and the mirrored operator is the whole
-  // assertion. Emitting `lt` here would invert the comparison — this repository's canonical bug
-  // class, and the reason `vf-*` and `arith-vf` pin the same filter as their column-first twins.
-  "arith-vf": { aNumber: { gt: 1 } },
-  // A constant receiver with a column needle: `K.contains(aString)` cannot become a LIKE, so the
-  // adapter enumerates every substring of the constant and tests membership. The enumeration is
-  // long, and pinning it verbatim is the point — an off-by-one at either end of the window is
-  // invisible in a row comparison over 22 seeds and obvious in this list.
-  "cr-contains": {
-    aString: {
-      in: [
-        "",
-        "s",
-        "s1",
-        "s10",
-        "s100",
-        "s100X",
-        "s100Xd",
-        "s100Xdo",
-        "s100Xdon",
-        "s100Xdone",
-        "s100Xdone-",
-        "s100Xdone-t",
-        "s100Xdone-ta",
-        "s100Xdone-tai",
-        "s100Xdone-tail",
-        "s100Xdone-tail\\",
-        "s100Xdone-tail\\o",
-        "s100Xdone-tail\\on",
-        "s100Xdone-tail\\one",
-        "s100Xdone-tail\\one-",
-        "s100Xdone-tail\\one-e",
-        "s100Xdone-tail\\one-en",
-        "s100Xdone-tail\\one-end",
-        "1",
-        "10",
-        "100",
-        "100X",
-        "100Xd",
-        "100Xdo",
-        "100Xdon",
-        "100Xdone",
-        "100Xdone-",
-        "100Xdone-t",
-        "100Xdone-ta",
-        "100Xdone-tai",
-        "100Xdone-tail",
-        "100Xdone-tail\\",
-        "100Xdone-tail\\o",
-        "100Xdone-tail\\on",
-        "100Xdone-tail\\one",
-        "100Xdone-tail\\one-",
-        "100Xdone-tail\\one-e",
-        "100Xdone-tail\\one-en",
-        "100Xdone-tail\\one-end",
-        "0",
-        "00",
-        "00X",
-        "00Xd",
-        "00Xdo",
-        "00Xdon",
-        "00Xdone",
-        "00Xdone-",
-        "00Xdone-t",
-        "00Xdone-ta",
-        "00Xdone-tai",
-        "00Xdone-tail",
-        "00Xdone-tail\\",
-        "00Xdone-tail\\o",
-        "00Xdone-tail\\on",
-        "00Xdone-tail\\one",
-        "00Xdone-tail\\one-",
-        "00Xdone-tail\\one-e",
-        "00Xdone-tail\\one-en",
-        "00Xdone-tail\\one-end",
-        "0X",
-        "0Xd",
-        "0Xdo",
-        "0Xdon",
-        "0Xdone",
-        "0Xdone-",
-        "0Xdone-t",
-        "0Xdone-ta",
-        "0Xdone-tai",
-        "0Xdone-tail",
-        "0Xdone-tail\\",
-        "0Xdone-tail\\o",
-        "0Xdone-tail\\on",
-        "0Xdone-tail\\one",
-        "0Xdone-tail\\one-",
-        "0Xdone-tail\\one-e",
-        "0Xdone-tail\\one-en",
-        "0Xdone-tail\\one-end",
-        "X",
-        "Xd",
-        "Xdo",
-        "Xdon",
-        "Xdone",
-        "Xdone-",
-        "Xdone-t",
-        "Xdone-ta",
-        "Xdone-tai",
-        "Xdone-tail",
-        "Xdone-tail\\",
-        "Xdone-tail\\o",
-        "Xdone-tail\\on",
-        "Xdone-tail\\one",
-        "Xdone-tail\\one-",
-        "Xdone-tail\\one-e",
-        "Xdone-tail\\one-en",
-        "Xdone-tail\\one-end",
-        "d",
-        "do",
-        "don",
-        "done",
-        "done-",
-        "done-t",
-        "done-ta",
-        "done-tai",
-        "done-tail",
-        "done-tail\\",
-        "done-tail\\o",
-        "done-tail\\on",
-        "done-tail\\one",
-        "done-tail\\one-",
-        "done-tail\\one-e",
-        "done-tail\\one-en",
-        "done-tail\\one-end",
-        "o",
-        "on",
-        "one",
-        "one-",
-        "one-t",
-        "one-ta",
-        "one-tai",
-        "one-tail",
-        "one-tail\\",
-        "one-tail\\o",
-        "one-tail\\on",
-        "one-tail\\one",
-        "one-tail\\one-",
-        "one-tail\\one-e",
-        "one-tail\\one-en",
-        "one-tail\\one-end",
-        "n",
-        "ne",
-        "ne-",
-        "ne-t",
-        "ne-ta",
-        "ne-tai",
-        "ne-tail",
-        "ne-tail\\",
-        "ne-tail\\o",
-        "ne-tail\\on",
-        "ne-tail\\one",
-        "ne-tail\\one-",
-        "ne-tail\\one-e",
-        "ne-tail\\one-en",
-        "ne-tail\\one-end",
-        "e",
-        "e-",
-        "e-t",
-        "e-ta",
-        "e-tai",
-        "e-tail",
-        "e-tail\\",
-        "e-tail\\o",
-        "e-tail\\on",
-        "e-tail\\one",
-        "e-tail\\one-",
-        "e-tail\\one-e",
-        "e-tail\\one-en",
-        "e-tail\\one-end",
-        "-",
-        "-t",
-        "-ta",
-        "-tai",
-        "-tail",
-        "-tail\\",
-        "-tail\\o",
-        "-tail\\on",
-        "-tail\\one",
-        "-tail\\one-",
-        "-tail\\one-e",
-        "-tail\\one-en",
-        "-tail\\one-end",
-        "t",
-        "ta",
-        "tai",
-        "tail",
-        "tail\\",
-        "tail\\o",
-        "tail\\on",
-        "tail\\one",
-        "tail\\one-",
-        "tail\\one-e",
-        "tail\\one-en",
-        "tail\\one-end",
-        "a",
-        "ai",
-        "ail",
-        "ail\\",
-        "ail\\o",
-        "ail\\on",
-        "ail\\one",
-        "ail\\one-",
-        "ail\\one-e",
-        "ail\\one-en",
-        "ail\\one-end",
-        "i",
-        "il",
-        "il\\",
-        "il\\o",
-        "il\\on",
-        "il\\one",
-        "il\\one-",
-        "il\\one-e",
-        "il\\one-en",
-        "il\\one-end",
-        "l",
-        "l\\",
-        "l\\o",
-        "l\\on",
-        "l\\one",
-        "l\\one-",
-        "l\\one-e",
-        "l\\one-en",
-        "l\\one-end",
-        "\\",
-        "\\o",
-        "\\on",
-        "\\one",
-        "\\one-",
-        "\\one-e",
-        "\\one-en",
-        "\\one-end",
-        "one-e",
-        "one-en",
-        "one-end",
-        "ne-e",
-        "ne-en",
-        "ne-end",
-        "e-e",
-        "e-en",
-        "e-end",
-        "-e",
-        "-en",
-        "-end",
-        "en",
-        "end",
-        "nd",
-      ],
-    },
-  },
-  "cr-endswith": {
-    aString: {
-      in: [
-        "",
-        "prefix-xaXby",
-        "refix-xaXby",
-        "efix-xaXby",
-        "fix-xaXby",
-        "ix-xaXby",
-        "x-xaXby",
-        "-xaXby",
-        "xaXby",
-        "aXby",
-        "Xby",
-        "by",
-        "y",
-      ],
-    },
-  },
-  "cr-startswith": {
-    aString: {
-      in: [
-        "",
-        "x",
-        "xa",
-        "xaX",
-        "xaXb",
-        "xaXby",
-        "xaXby-",
-        "xaXby-t",
-        "xaXby-ta",
-        "xaXby-tai",
-        "xaXby-tail",
-      ],
-    },
-  },
-  "cr-startswith-concat": {
-    aString: {
-      in: [
-        "",
-        "x",
-        "xa",
-        "xaX",
-        "xaXb",
-        "xaXby",
-        "xaXby-",
-        "xaXby-t",
-        "xaXby-ta",
-        "xaXby-tai",
-        "xaXby-tail",
-      ],
-    },
-  },
-  "cs-contains": { aString: { contains: "one" } },
-  "cs-endswith": { aString: { endsWith: "one" } },
-  "cs-eq": { aString: { equals: "one" } },
-  "cs-startswith": { aString: { startsWith: "one" } },
-  "double-negation": { NOT: { aBool: { equals: false } } },
-  "double-threshold": { AND: [{ aNumber: { gte: 1.5 } }, { aNumber: { gt: 1 } }] },
-  "empty-string-eq": { aString: { equals: "" } },
-  "exists-on-empty": { tags: { some: { name: { equals: "public" } } } },
-  "field-to-field": {
-    aString: { equals: { _ref: "aOptionalString", _container: "AdversarialResource" } },
-  },
-  "gt-bare": { aNumber: { gt: 1 } },
-  "hier-ancestor-cf": { scope: { startsWith: "dept.eng." } },
-  "hier-ancestor-ff": { scope: { in: ["dept", "dept.eng"] } },
-  "hier-descendent-cf": { scope: { in: ["dept", "dept.eng"] } },
-  "hier-descendent-ff": { scope: { startsWith: "dept.eng." } },
-  "hier-list-id": { id: { equals: "f1" } },
-  "hier-meta-in": { scope: { in: ["50%", "50%.a_b"] } },
-  "hier-overlaps-cf": {
-    OR: [
-      { scope: { in: ["dept"] } },
-      { scope: { equals: "dept.eng" } },
-      { scope: { startsWith: "dept.eng." } },
-    ],
-  },
-  "hier-overlaps-ff": {
-    OR: [
-      { scope: { in: ["dept"] } },
-      { scope: { equals: "dept.eng" } },
-      { scope: { startsWith: "dept.eng." } },
-    ],
-  },
-  "id-concat-vf": { id: { equals: "f1" } },
-  // The primary key, which arrives as the variable `request.resource.id` rather than through
-  // `attr` — the planner leaves the resource's own identity symbolic because PlanResources is
-  // asked about a kind, not a row. An adapter that resolves references by stripping a
-  // `request.resource.attr.` prefix never reaches this name, and fails silently when it does not.
-  "id-eq-const": { id: { equals: "f1" } },
-  // `_ref`/`_container` is Prisma's field-reference encoding: comparing two columns needs the
-  // model name, which is why `queryPlanToPrisma` takes `model`.
-  "id-f2f": { aString: { equals: { _ref: "id", _container: "AdversarialResource" } } },
-  "id-f2f-ne": {
-    NOT: { aString: { equals: { _ref: "id", _container: "AdversarialResource" } } },
-  },
-  "in-null-elem-hasint": {
-    OR: [{ tags: { some: { name: "public" } } }, { tags: { some: { name: null } } }],
-  },
-  "in-null-elem-mixed": {
-    OR: [{ aOptionalString: { in: ["x", "one_two"] } }, { aOptionalString: null }],
-  },
-  "in-null-elem-neg": {
-    NOT: {
-      OR: [{ aOptionalString: { in: ["x", "one_two"] } }, { aOptionalString: null }],
-    },
-  },
-  "in-null-elem-only": { aOptionalString: { equals: null } },
-  "in-null-elem-only-neg": { NOT: { aOptionalString: { equals: null } } },
-  "in-null-elem-rel": { tags: { some: { name: null } } },
-  "in-null-elem-rel-neg": { NOT: { tags: { some: { name: null } } } },
-  "in-single": { aString: { equals: "one" } },
-  "lambda-in-principal": { tags: { some: { name: { in: ["public", "special"] } } } },
-  "le-bare": { aNumber: { lte: 2 } },
-  "like-bracket": { aString: { startsWith: "[SEC]" } },
-  "macro-depth3-all": {
-    categories: {
-      some: {
-        subCategories: { every: { labels: { some: { name: { equals: "gold" } } } } },
-      },
-    },
-  },
-  "macro-depth3-exists": {
-    categories: {
-      some: {
-        subCategories: { some: { labels: { some: { name: { equals: "gold" } } } } },
-      },
-    },
-  },
-  "macro-depth3-not-exists": {
-    AND: [
-      {
-        NOT: {
-          categories: {
-            some: {
-              subCategories: { some: { labels: { some: { name: { equals: "gold" } } } } },
-            },
-          },
-        },
-      },
-      {
-        NOT: {
-          categories: {
-            some: {
-              AND: [
-                {
-                  NOT: {
-                    subCategories: { some: { labels: { some: { name: { equals: "gold" } } } } },
-                  },
-                },
-                {
-                  subCategories: {
-                    some: {
-                      AND: [
-                        {
-                          NOT: { labels: { some: { name: { equals: "gold" } } } },
-                        },
-                        { labels: { some: { name: null } } },
-                      ],
-                    },
-                  },
-                },
-              ],
-            },
-          },
-        },
-      },
-    ],
-  },
-  "n-all-mixed-null": {
-    AND: [
-      { tags: { every: { name: { not: "x" } } } },
-      { tags: { none: { name: null } } },
-    ],
-  },
-  "n-not-all-absorb": { tags: { some: { NOT: { name: { not: "public" } } } } },
-  "n-not-all-null": { tags: { some: { NOT: { name: { equals: "public" } } } } },
-  "nan-ord-inf": {
-    OR: [
-      { aBool: { equals: true } },
-      { AND: [{ aBool: { equals: true } }, { aBool: { equals: false } }] },
-    ],
-  },
-  "nan-ord-le": {
-    OR: [
-      {
-        AND: [
-          { aBool: { equals: true } },
-          {
-            OR: [
-              {
-                AND: [{ aBool: { equals: true } }, { aBool: { equals: false } }],
-              },
-            ],
-          },
-        ],
-      },
-      {
-        AND: [
-          { aBool: { equals: false } },
-          {
-            OR: [
-              { aBool: { equals: true } },
-              {
-                AND: [{ aBool: { equals: true } }, { aBool: { equals: false } }],
-              },
-            ],
-          },
-        ],
-      },
-      { AND: [{ aBool: { equals: true } }, { aBool: { equals: false } }] },
-    ],
-  },
-  "nan-ord-ternary": {
-    OR: [
-      { aBool: { equals: true } },
-      { AND: [{ aBool: { equals: true } }, { aBool: { equals: false } }] },
-    ],
-  },
-  "nan-ord-ternary-vf": {
-    OR: [
-      { aBool: { equals: true } },
-      { AND: [{ aBool: { equals: true } }, { aBool: { equals: false } }] },
-    ],
-  },
-  "nary-and": {
-    AND: [
-      { aBool: { equals: true } },
-      { aNumber: { gte: 0 } },
-      { aString: { not: "one" } },
-    ],
-  },
-  "neg-number": { aNumber: { lt: -1 } },
-  // The De Morgan branch. `NOT` over a conjunction was unreachable from the corpus until #387,
-  // and it is the same wire shape a DENY-composed `nand` rule produces — byte-identical
-  // `filter.condition` JSON, which is why the DENY spelling ported as a delete.
-  "not-and": { NOT: { AND: [{ aBool: { equals: true } }, { aString: { not: "one" } }] } },
-  "not-empty": { NOT: { tags: { none: {} } } },
-  "not-exists": {
-    AND: [
-      { NOT: { tags: { some: { name: { equals: "private" } } } } },
-      { NOT: { tags: { some: { name: null } } } },
-    ],
-  },
-  "not-gt": { NOT: { aNumber: { gt: 1 } } },
-  "not-lt": { NOT: { aNumber: { lt: 2 } } },
-  "null-eq": { aOptionalString: { equals: null } },
-  "null-eq-missing": { aOptionalString: { equals: null } },
-  "null-ne": { aOptionalString: { not: null } },
-  "null-not-eq": { NOT: { aOptionalString: { equals: null } } },
-  "null-value-f2f": {
-    OR: [
-      { AND: [{ aOptionalString: null }, { scope: null }] },
-      {
-        AND: [
-          { aOptionalString: { not: null } },
-          { scope: { not: null } },
-          {
-            aOptionalString: { equals: { _ref: "scope", _container: "AdversarialResource" } },
-          },
-        ],
-      },
-    ],
-  },
-  "null-value-ne-const": {
-    NOT: {
-      AND: [{ aOptionalString: { not: null } }, { aOptionalString: { equals: "x" } }],
-    },
-  },
-  // Under the explicit-null convention CEL holds a null VALUE, so `null != "x"` is TRUE and
-  // `null == "x"` is FALSE — both definite. Prisma's bare `{ not: "x" }` drops the row under both
-  // polarities, so the equality family is rendered so it can never depend on SQL's UNKNOWN. The
-  // `not: null` conjunct is that rendering, and it is what the `owner`/`coOwner` declarations in
-  // the mapper buy (cerbos/query-plan-adapters#308).
-  "null-value-not-eq-const": {
-    NOT: {
-      AND: [{ aOptionalString: { not: null } }, { aOptionalString: { equals: "x" } }],
-    },
-  },
-  "null-value-not-in-const": {
-    NOT: {
-      AND: [
-        { aOptionalString: { not: null } },
-        { aOptionalString: { in: ["x", "one_two"] } },
-      ],
-    },
-  },
-  "null-value-pv-not-exists": {
-    AND: [
-      {
-        NOT: {
-          AND: [
-            { aOptionalString: { not: null } },
-            { aOptionalString: { equals: "set" } },
-          ],
-        },
-      },
-      {
-        NOT: {
-          AND: [
-            { aOptionalString: { not: null } },
-            { aOptionalString: { equals: "same" } },
-          ],
-        },
-      },
-      {
-        NOT: {
-          AND: [
-            { aOptionalString: { not: null } },
-            { aOptionalString: { equals: "" } },
-          ],
-        },
-      },
-      {
-        NOT: {
-          AND: [
-            { aOptionalString: { not: null } },
-            { aOptionalString: { equals: "%_o" } },
-          ],
-        },
-      },
-      {
-        NOT: {
-          AND: [
-            { aOptionalString: { not: null } },
-            { aOptionalString: { equals: "X" } },
-          ],
-        },
-      },
-      {
-        NOT: {
-          AND: [
-            { aOptionalString: { not: null } },
-            { aOptionalString: { equals: "Y" } },
-          ],
-        },
-      },
-      {
-        NOT: {
-          AND: [
-            { aOptionalString: { not: null } },
-            { aOptionalString: { equals: "MIRROR" } },
-          ],
-        },
-      },
-      {
-        NOT: {
-          AND: [
-            { aOptionalString: { not: null } },
-            { aOptionalString: { equals: "filler-1" } },
-          ],
-        },
-      },
-      {
-        NOT: {
-          AND: [
-            { aOptionalString: { not: null } },
-            { aOptionalString: { equals: "filler-2" } },
-          ],
-        },
-      },
-      {
-        NOT: {
-          AND: [
-            { aOptionalString: { not: null } },
-            { aOptionalString: { equals: "filler-3" } },
-          ],
-        },
-      },
-      {
-        NOT: {
-          AND: [
-            { aOptionalString: { not: null } },
-            { aOptionalString: { equals: "filler-4" } },
-          ],
-        },
-      },
-    ],
-  },
-  "optional-ne": { aOptionalString: { not: "x" } },
-  "or-eq-exists": {
-    OR: [
-      { aBool: { equals: true } },
-      { tags: { some: { name: { equals: "public" } } } },
-    ],
-  },
-  "or-eq-in": { OR: [{ aBool: { equals: true } }, { tags: { some: { name: "public" } } }] },
-  "outer-attr-depth2": {
-    AND: [
-      {
-        categories: { some: { subCategories: { some: { name: { equals: "finance" } } } } },
-      },
-      { aBool: { equals: true } },
-    ],
-  },
-  "p-arith-in-lambda": {
-    AND: [{ tags: { some: { name: { equals: "public" } } } }, { aNumber: { gt: 1 } }],
-  },
-  "p-double-frac": {
-    AND: [
-      { aNumber: { equals: 2.9999999999999996 } },
-      { aNumber: { gt: 2 } },
-      { aNumber: { lt: 3 } },
-    ],
-  },
-  "p-hasintersection-map": {
-    AND: [
-      {
-        tags: {
-          some: { name: { in: ["public", "h\u00e9llo\ud83d\ude80", "100%_x"] } },
-        },
-      },
-      { NOT: { tags: { some: { name: null } } } },
-    ],
-  },
-  "p-in-null-multi": { aOptionalString: { in: ["x", "one_two"] } },
-  "p-in-null-single": { aOptionalString: { equals: "x" } },
-  "p-lambda-inner-f2f": {
-    tags: {
-      some: { tagId: { equals: { _ref: "name", _container: "AdversarialTag" } } },
-    },
-  },
-  "p-not-exists-empty": {
-    AND: [
-      { NOT: { tags: { some: { name: { equals: "public" } } } } },
-      { NOT: { tags: { some: { name: null } } } },
-    ],
-  },
-  "p-not-ternary-null": {
-    NOT: {
-      OR: [
-        { AND: [{ aOptionalString: { not: "x" } }, { aNumber: { gt: 1 } }] },
-        {
-          AND: [
-            { aOptionalString: { not: "x" } },
-            { NOT: { aOptionalString: { not: "x" } } },
-          ],
-        },
-      ],
-    },
-  },
-  "p-struct": { aString: { equals: "one" } },
-  "p-ternary-in-exists": {
-    OR: [
-      {
-        AND: [
-          { aBool: { equals: true } },
-          { tags: { some: { name: { equals: "public" } } } },
-        ],
-      },
-      { AND: [{ aBool: { equals: true } }, { aBool: { equals: false } }] },
-    ],
-  },
-  "p-ternary-of-ternaries": {
-    OR: [
-      {
-        AND: [
-          { aBool: { equals: true } },
-          {
-            OR: [
-              {
-                AND: [{ NOT: { aString: { equals: "" } } }, { aNumber: { gt: 1 } }],
-              },
-              {
-                AND: [
-                  { aString: { equals: "" } },
-                  { NOT: { aString: { equals: "" } } },
-                ],
-              },
-            ],
-          },
-        ],
-      },
-      {
-        AND: [
-          { aBool: { equals: false } },
-          {
-            OR: [
-              { NOT: { aNumber: { lt: 0 } } },
-              { AND: [{ aNumber: { lt: 0 } }, { NOT: { aNumber: { lt: 0 } } }] },
-            ],
-          },
-        ],
-      },
-      { AND: [{ aBool: { equals: true } }, { aBool: { equals: false } }] },
-    ],
-  },
-  "p-ternary-under-all": {
-    OR: [
-      {
-        AND: [
-          { aBool: { equals: true } },
-          {
-            AND: [
-              { tags: { every: { name: { not: "private" } } } },
-              { tags: { none: { name: null } } },
-            ],
-          },
-        ],
-      },
-      { aBool: { equals: false } },
-      { AND: [{ aBool: { equals: true } }, { aBool: { equals: false } }] },
-    ],
-  },
-  "p-ternary-vs-ternary": {
-    OR: [
-      {
-        AND: [
-          { aBool: { equals: true } },
-          {
-            OR: [
-              { AND: [{ aString: { equals: "" } }, { aNumber: { gt: 1 } }] },
-              {
-                AND: [{ NOT: { aString: { equals: "" } } }, { aNumber: { gt: 2 } }],
-              },
-              {
-                AND: [
-                  { aString: { equals: "" } },
-                  { NOT: { aString: { equals: "" } } },
-                ],
-              },
-            ],
-          },
-        ],
-      },
-      {
-        AND: [
-          { aBool: { equals: false } },
-          {
-            OR: [
-              {
-                AND: [
-                  { aString: { equals: "" } },
-                  { NOT: { aString: { equals: "" } } },
-                ],
-              },
-            ],
-          },
-        ],
-      },
-      { AND: [{ aBool: { equals: true } }, { aBool: { equals: false } }] },
-    ],
-  },
-  "pv-all": {
-    AND: [
-      { aOptionalString: { not: "set" } },
-      { aOptionalString: { not: "same" } },
-      { aOptionalString: { not: "" } },
-      { aOptionalString: { not: "%_o" } },
-      { aOptionalString: { not: "X" } },
-      { aOptionalString: { not: "Y" } },
-      { aOptionalString: { not: "MIRROR" } },
-      { aOptionalString: { not: "filler-1" } },
-      { aOptionalString: { not: "filler-2" } },
-      { aOptionalString: { not: "filler-3" } },
-      { aOptionalString: { not: "filler-4" } },
-    ],
-  },
-  "pv-all-unrolled": {
-    AND: [
-      { aOptionalString: { not: "set" } },
-      {
-        AND: [{ aOptionalString: { not: "" } }, { aOptionalString: { not: "%_o" } }],
-      },
-    ],
-  },
-  "pv-exists": {
-    OR: [
-      { aOptionalString: { equals: "set" } },
-      { aOptionalString: { equals: "same" } },
-      { aOptionalString: { equals: "" } },
-      { aOptionalString: { equals: "%_o" } },
-      { aOptionalString: { equals: "X" } },
-      { aOptionalString: { equals: "Y" } },
-      { aOptionalString: { equals: "MIRROR" } },
-      { aOptionalString: { equals: "filler-1" } },
-      { aOptionalString: { equals: "filler-2" } },
-      { aOptionalString: { equals: "filler-3" } },
-      { aOptionalString: { equals: "filler-4" } },
-    ],
-  },
-  "pv-exists-unrolled": {
-    OR: [
-      { aOptionalString: { equals: "set" } },
-      {
-        OR: [
-          { aOptionalString: { equals: "" } },
-          { aOptionalString: { equals: "%_o" } },
-        ],
-      },
-    ],
-  },
-  "rel-bool-hop": { parent: { is: { aBool: { equals: true } } } },
-  "rel-bool-hop2": { parent: { is: { inner: { is: { aBool: { equals: true } } } } } },
-  "rel-contains-hop": { parent: { is: { aString: { contains: "done" } } } },
-  "rel-eq-hop": { parent: { is: { aString: { equals: "One" } } } },
-  "rel-eq-num-hop": { parent: { is: { aNumber: { equals: 2 } } } },
-  "rel-ge-hop": { parent: { is: { aNumber: { gte: 2 } } } },
-  "rel-gt-hop": { parent: { is: { aNumber: { gt: 2 } } } },
-  "rel-hop-and-root": {
-    AND: [
-      { aBool: { equals: true } },
-      { parent: { is: { aString: { contains: "re" } } } },
-    ],
-  },
-  "rel-hop2-or-exists": {
-    OR: [
-      { parent: { is: { inner: { is: { aBool: { equals: true } } } } } },
-      { categories: { some: { name: { equals: "business" } } } },
-    ],
-  },
-  "rel-le-hop": { parent: { is: { aNumber: { lte: 2 } } } },
-  "rel-lt-hop": { parent: { is: { aNumber: { lt: 2 } } } },
-  "rel-ne-null-hop": { parent: { is: { aOptionalString: { not: null } } } },
-  // The absent-parent guard. `NOT { parent: { is: P } }` is satisfied by a row with no parent at
-  // all, while CEL raises a missing-attribute error on the hop and check() denies. The first
-  // conjunct — an existence test on the hop itself — is what keeps a negated shape over an
-  // OPTIONAL to-one relation from over-granting. The positive shapes cannot discriminate it,
-  // which is why the corpus carries the negated ones (ADR 0005).
-  "rel-not-bool-hop": {
-    AND: [
-      { parent: { is: {} } },
-      { NOT: { parent: { is: { aBool: { equals: true } } } } },
-    ],
-  },
-  "rel-range-hop": {
-    AND: [
-      { parent: { is: { aNumber: { gt: 2 } } } },
-      { parent: { is: { aNumber: { lt: 12 } } } },
-    ],
-  },
-  "rel-startswith-hop2": { parent: { is: { inner: { is: { aString: { startsWith: "100" } } } } } },
-  "root-bare-bool": { aBool: { equals: true } },
-  "root-or": { OR: [{ aBool: { equals: true } }, { aNumber: { lt: 0 } }] },
-  "ternary-bare": {
-    OR: [
-      { AND: [{ aBool: { equals: true } }, { aString: { equals: "one" } }] },
-      { AND: [{ aBool: { equals: false } }, { aNumber: { lt: 0 } }] },
-      { AND: [{ aBool: { equals: true } }, { aBool: { equals: false } }] },
-    ],
-  },
-  "ternary-cmp": {
-    OR: [
-      { AND: [{ aBool: { equals: true } }, { aNumber: { gt: 1 } }] },
-      { AND: [{ aBool: { equals: true } }, { aBool: { equals: false } }] },
-    ],
-  },
-  "ternary-expr-cond": {
-    OR: [
-      { AND: [{ aString: { startsWith: "100" } }, { aNumber: { gte: 0 } }] },
-      {
-        AND: [
-          { aString: { startsWith: "100" } },
-          { NOT: { aString: { startsWith: "100" } } },
-        ],
-      },
-    ],
-  },
-  "ternary-negated": {
-    NOT: {
-      OR: [
-        { AND: [{ aBool: { equals: true } }, { aNumber: { gt: 1 } }] },
-        { AND: [{ aBool: { equals: true } }, { aBool: { equals: false } }] },
-      ],
-    },
-  },
-  "ternary-nested": {
-    OR: [
-      {
-        AND: [
-          { aBool: { equals: true } },
-          {
-            OR: [
-              {
-                AND: [{ NOT: { aString: { equals: "" } } }, { aNumber: { gte: 2 } }],
-              },
-              {
-                AND: [
-                  { aString: { equals: "" } },
-                  { NOT: { aString: { equals: "" } } },
-                ],
-              },
-            ],
-          },
-        ],
-      },
-      { AND: [{ aBool: { equals: true } }, { aBool: { equals: false } }] },
-    ],
-  },
-  "ternary-null-cond": {
-    OR: [
-      { AND: [{ aOptionalString: { not: "x" } }, { aNumber: { gt: 1 } }] },
-      {
-        AND: [
-          { aOptionalString: { not: "x" } },
-          { NOT: { aOptionalString: { not: "x" } } },
-        ],
-      },
-    ],
-  },
-  "ternary-value-first": {
-    OR: [
-      { AND: [{ aBool: { equals: true } }, { aNumber: { gt: 0 } }] },
-      { AND: [{ aBool: { equals: true } }, { aBool: { equals: false } }] },
-    ],
-  },
-  "triple-negation": { NOT: { NOT: { aBool: { equals: false } } } },
-  "ts-eq": { createdAt: { equals: "2024-06-01T00:00:00.000Z" } },
-  "ts-eq-offset": { createdAt: { equals: "2024-06-01T00:00:00.000Z" } },
-  "ts-ne": { createdAt: { not: "2024-06-01T00:00:00.000Z" } },
-  "unicode-eq": { aString: { equals: "h\u00e9llo\ud83d\ude80" } },
-  "vf-ge": { aNumber: { lte: 2 } },
-  "vf-hasint": { tags: { some: { name: { in: ["public", "other"] } } } },
-  "vf-le": { aNumber: { gte: 3 } },
-  "vf-lt": { aNumber: { gt: 1 } },
-  "vf-ne": { aString: { not: "one" } },
-  "vf-null-ne": { aOptionalString: { not: null } },
-  "vf-size": { tags: { some: {} } },
-  "w1-exists-chain": {
-    categories: { some: { subCategories: { some: { name: { equals: "finance" } } } } },
-  },
-  "w1-in-chain": { categories: { some: { subCategories: { some: { name: "finance" } } } } },
-  // The same absent-hop guard as `rel-not-bool-hop`, one level up a multi-hop chain: the negation
-  // is joined through every intermediate relation, never off the root, and the leading existence
-  // test is what stops a row with no category at all from satisfying the negation.
-  "w1-not-exists-chain": {
-    AND: [
-      { categories: { some: {} } },
-      {
-        NOT: {
-          categories: { some: { subCategories: { some: { name: { equals: "finance" } } } } },
-        },
-      },
-    ],
-  },
-  "w1-not-hasint-chain": {
-    AND: [
-      { categories: { some: {} } },
-      {
-        NOT: {
-          categories: { some: { subCategories: { some: { name: "finance" } } } },
-        },
-      },
-    ],
-  },
-  "w1-not-in-chain": {
-    AND: [
-      { categories: { some: {} } },
-      {
-        NOT: {
-          categories: { some: { subCategories: { some: { name: "finance" } } } },
-        },
-      },
-    ],
-  },
-  "w1-not-size-chain": {
-    AND: [
-      { categories: { some: {} } },
-      { NOT: { categories: { some: { subCategories: { some: {} } } } } },
-    ],
-  },
-  "w1-size-chain": { categories: { some: { subCategories: { some: {} } } } },
-  "w1-size-zero-chain": { categories: { some: { subCategories: { none: {} } } } },
-  "w1-ternary-chain-cond": {
-    OR: [
-      {
-        AND: [
-          {
-            categories: { some: { subCategories: { some: { name: "finance" } } } },
-          },
-          { aBool: { equals: true } },
-        ],
-      },
-      {
-        AND: [
-          {
-            AND: [
-              { categories: { some: {} } },
-              {
-                NOT: {
-                  categories: { some: { subCategories: { some: { name: "finance" } } } },
-                },
-              },
-            ],
-          },
-          { aBool: { equals: false } },
-        ],
-      },
-      {
-        AND: [
-          {
-            categories: { some: { subCategories: { some: { name: "finance" } } } },
-          },
-          {
-            AND: [
-              { categories: { some: {} } },
-              {
-                NOT: {
-                  categories: { some: { subCategories: { some: { name: "finance" } } } },
-                },
-              },
-            ],
-          },
-        ],
-      },
-    ],
-  },
-};
-
-describe("corpus shapes", () => {
-  test.each(Object.entries(EXPECTED_FILTERS))(
-    "%s emits the pinned filter",
-    (action, filters) => {
-      expect(translate(action)).toStrictEqual({
-        kind: PlanKind.CONDITIONAL,
-        filters,
-      });
+    try {
+      await translate("collection/index/first-element-of-string-list");
+    } catch (error) {
+      raised = error;
     }
-  );
 
-  test.each(Object.entries(EXPECTED_KINDS))(
-    "%s resolves without a condition",
-    (action, kind) => {
-      expect(translate(action)).toStrictEqual({ kind });
-    }
-  );
+    expect(raised).toBeInstanceOf(UnsupportedQueryPlanError);
+    expect(raised).toBeInstanceOf(Error);
+    expect(raised).toMatchObject({ name: "UnsupportedQueryPlanError" });
+  });
 
-  // The message, not just the throw: a mapper typo or an unrelated validation satisfies a bare
-  // `toThrow()` just as well as the limitation the corpus documents (#326). The harness makes the
-  // same assertion against a live PDP; here it costs a millisecond and covers the whole roster,
-  // which is what lets the completeness guard below be total.
-  test.each(THROWING_ACTIONS)(
-    "%s is refused with the message actions.json pins (%s)",
-    (action, _reason, message) => {
-      expect(() => translate(action)).toThrow(message);
+  test("mapper misconfiguration is a plain Error, not a refusal", async () => {
+    const queryPlan = await planFor("comparison/equals/field-to-field");
+    let raised: unknown;
+
+    try {
+      queryPlanToPrisma({ queryPlan, mapper: MAPPER });
+    } catch (error) {
+      raised = error;
     }
-  );
 
-  test("every corpus action is classified here exactly once", () => {
-    const filters = Object.keys(EXPECTED_FILTERS);
-    const kinds = Object.keys(EXPECTED_KINDS);
-    const throwing = THROWING_ACTIONS.map(([action]) => action);
-    const classified = [...filters, ...kinds, ...throwing].sort();
-
-    // Total: a corpus action with no entry here lands as a failure rather than as silence. This
-    // is the assertion that makes the file self-maintaining — adding a hostile shape to the
-    // corpus forces someone to look at the filter this adapter emits for it.
-    expect(classified).toEqual(wireFixtureActions());
-    // Disjoint: an action pinned as a filter AND declared unsupported would satisfy the union
-    // above while asserting two contradictory things.
-    expect(classified).toEqual([...new Set(classified)].sort());
-    // The table is alphabetical, so a translator change reads as the list of shapes it moved.
-    expect(filters).toEqual([...filters].sort());
-
-    // Tripwires. Bump them deliberately: a count that moves without anyone noticing is how a
-    // shape gets dropped from a table nobody reads end to end.
-    expect({
-      filters: filters.length,
-      kinds: kinds.length,
-      throwing: throwing.length,
-    }).toEqual({ filters: 136, kinds: 2, throwing: 61 });
+    expect(raised).toBeInstanceOf(Error);
+    expect(raised).not.toBeInstanceOf(UnsupportedQueryPlanError);
+    expect(raised).toHaveProperty("message", expect.stringContaining("requires the `model` option"));
+  });
+});
+
+describe("declared scalar types", () => {
+  test("an undeclared type preserves the legacy mapper contract", async () => {
+    expect(
+      await translate("type-mismatch/equals/string-field-against-number-principal", {
+        mapper: { "request.resource.attr.aString": { field: "aString" } },
+      }),
+    ).toEqual({
+      kind: PlanKind.CONDITIONAL,
+      filters: { aString: { equals: 0 } },
+    });
   });
 });
 
+/** The shared mapper with every per-attribute null declaration stripped. */
+const UNDECLARED: Record<string, MapperConfig> = Object.fromEntries(
+  Object.entries(MAPPER).map(([reference, config]) => {
+    const { nullAttributeRepresentation: _stripped, ...rest } = config;
+
+    return [reference, rest];
+  })
+);
+
+/** Whether any operand anywhere in the wire plan is a literal null, or a list containing one. */
+function carriesNullLiteral(node: JsonValue | undefined): boolean {
+  if (Array.isArray(node)) return node.some(carriesNullLiteral);
+
+  if (!isObject(node)) return false;
+  const record = node;
+
+  if ("value" in record) {
+    const value = record["value"];
+
+    return value === null || (Array.isArray(value) && value.includes(null));
+  }
+
+  return Object.values(record).some((child) =>
+    Array.isArray(child) ? child.some(carriesNullLiteral) : carriesNullLiteral(child)
+  );
+}
+
 describe("nullAttributeRepresentation", () => {
-  // `null-eq-missing` is the corpus's `nullRepresentationOmitted` probe: `== null` against an
-  // attribute the caller OMITS when the column is NULL. The two conventions are indistinguishable
-  // on the wire — the planner emits the same `eq(attr, null)` either way — so the adapter has to
-  // be told, and the whole behaviour is a translator property with no store in it.
-  test("explicit: a null operand becomes an IS NULL filter", () => {
+  // `== null` against an attribute the caller OMITS when the column is NULL. The two conventions
+  // are indistinguishable on the wire — the planner emits the same `eq(attr, null)` either way — so
+  // the adapter has to be told. The corpus mapping declares it per attribute; these vary the
+  // call-level option and the declaration, which the corpus cannot.
+  const MISSING = "null/equals/null-literal-on-missing-attribute";
+  const NEVER = { kind: PlanKind.CONDITIONAL, filters: { NOT: { aOptionalString: { startsWith: "" } } } };
+
+  test("unset: the default is omitted, so == null selects no row", async () => {
+    // The default is the convention whose wrong guess fails closed (ADR 0011).
     expect(
-      translate("null-eq-missing", { nullAttributeRepresentation: "explicit" })
-    ).toStrictEqual({
+      queryPlanToPrisma({ queryPlan: await planFor(MISSING), mapper: UNDECLARED, model: MODEL })
+    ).toEqual(NEVER);
+  });
+
+  test("explicit: == null is an IS NULL filter", async () => {
+    expect(await translate(MISSING, { mapper: UNDECLARED })).toStrictEqual({
       kind: PlanKind.CONDITIONAL,
       filters: { aOptionalString: { equals: null } },
     });
   });
 
-  test("omitted: the same plan is refused rather than translated", () => {
+  test("omitted: the same plan selects no row rather than the NULL ones", async () => {
     // A NULL column sends no attribute, so check() denies on a missing-attribute error while the
-    // filter above would return exactly those rows (#302).
-    expect(() =>
-      translate("null-eq-missing", { nullAttributeRepresentation: "omitted" })
-    ).toThrow("missing-attribute error");
+    // IS NULL filter would return exactly those rows (#302); a present value is never null, so
+    // `== null` is FALSE for it — `NOT LIKE '%'`, which stays UNKNOWN on the NULL rows.
+    expect(
+      await translate(MISSING, { mapper: UNDECLARED, nullAttributeRepresentation: "omitted" })
+    ).toEqual(NEVER);
+  });
+
+  test("a per-attribute declaration overrides the call-level option, in both directions", async () => {
+    // Declared omitted, called explicit: no IS NULL filter (#308).
+    expect(await translate(MISSING)).toEqual(NEVER);
+    // Declared explicit (`owner`), called omitted: translated.
+    expect(
+      (await translate("null/equals/null-literal", { nullAttributeRepresentation: "omitted" })).kind
+    ).toBe(PlanKind.CONDITIONAL);
+    // Strip the declaration and the same call selects no row.
+    expect(
+      await translate("null/equals/null-literal", {
+        mapper: UNDECLARED,
+        nullAttributeRepresentation: "omitted",
+      })
+    ).toEqual(NEVER);
+  });
+
+  // The rejection must key off the null OPERAND, not a list of operators: `hasIntersection(tagNames,
+  // ["public", null])` carries one in its value list. Enumerating the goldens rather than naming
+  // shapes covers a newly added case carrying a null constant automatically.
+  // A plan whose null comparison settles passes too: `x == null` is FALSE for a present value and
+  // an error for a missing one, rendered with presence tests that are UNKNOWN on NULL. Any
+  // NULL-selecting filter needs an IS NULL leaf, i.e. a null literal in the emitted where-input.
+  test("no plan carrying a null literal emits an IS NULL filter under call-level omitted", async () => {
+    const carrying = readGoldens(CURRENT).filter((golden) => carriesNullLiteral(golden.plan));
+    const ids = carrying.map((golden) => golden.id);
+    expect(ids).toContain(MISSING);
+    expect(ids).toContain("null/has-intersection/literal-list-with-null-element");
+
+    const plans = await Promise.all(carrying.map((golden) => planOf(golden)));
+
+    const notRejected = carrying.flatMap((golden, index) => {
+      try {
+        const result = queryPlanToPrisma({
+          queryPlan: plans[index]!,
+          mapper: UNDECLARED,
+          model: MODEL,
+          nullAttributeRepresentation: "omitted",
+        });
+
+        return result.kind === PlanKind.CONDITIONAL && JSON.stringify(result.filters).includes("null")
+          ? [golden.id]
+          : [];
+      } catch (error) {
+        // A positional read of a list compares an element, not an optionally absent field; the
+        // index operator has no Prisma filter form under either representation. A null inside a
+        // whole-list literal is an element too, and comparing a list is refused under either, as
+        // is an `in` over a computed member. A null arithmetic operand has no CEL overload, so its
+        // fold is refused under either.
+        const message = String(error);
+
+        return message.includes("missing-attribute error") ||
+          message.includes("Unsupported operator: index") ||
+          message.includes("in requires a field member and literal list") ||
+          message.includes("Prisma cannot compare list or map elements") ||
+          message.includes("in over a scalar is a CEL error") ||
+          message.includes("operator requires string or number operands")
+          ? []
+          : [`${golden.id} (${message})`];
+      }
+    });
+
+    expect(notRejected).toEqual([]);
+  });
+});
+
+describe("reentrant function mappers", () => {
+  // Function mappers are caller-supplied, so the corpus cannot exercise nested adapter calls. The
+  // nested call's "omitted" must not leak into the outer "explicit" translation of `== null`.
+  test.each([
+    "null/equals/null-literal-on-missing-attribute",
+    "collection/all/empty-collection",
+  ])("keeps %s isolated from a nested translation", async (action) => {
+    const expected = await translate(action, { mapper: UNDECLARED });
+    const nested = await planFor("arithmetic/add/field-plus-constant");
+    let calls = 0;
+
+    const mapper: Mapper = (key) => {
+      calls++;
+      queryPlanToPrisma({
+        queryPlan: nested,
+        mapper: MAPPER,
+        model: "NestedModel",
+        nullAttributeRepresentation: "omitted",
+      });
+
+      return UNDECLARED[key] ?? { field: key };
+    };
+
+    expect(await translate(action, { mapper })).toStrictEqual(expected);
+    expect(calls).toBeGreaterThan(0);
+  });
+});
+
+test("an unplannable nested map does not register nullable fields on the outer lambda", async () => {
+  // CEL cannot reach this branch: Cerbos 0.54.0 rejects
+  // R.attr.tags.all(t, R.attr.tags.map(x, x.name)) with
+  // "expected type 'bool' but found 'list(dyn)'". This is a hand-crafted plan contract. A list
+  // where a boolean is required is a CEL error, so the body settles to false (all() holds only
+  // over no tags) before any lambda scope is entered.
+  const condition: PlanExpressionOperand = {
+    operator: "all",
+    operands: [
+      { name: "request.resource.attr.tags" },
+      {
+        operator: "lambda",
+        operands: [
+          {
+            operator: "map",
+            operands: [
+              { name: "request.resource.attr.tags" },
+              {
+                operator: "lambda",
+                operands: [{ name: "x.name" }, { name: "x" }],
+              },
+            ],
+          },
+          { name: "t" },
+        ],
+      },
+    ],
+  };
+
+  const result = queryPlanToPrisma({
+    queryPlan: { ...(await planFor("collection/all/empty-collection")), kind: PlanKind.CONDITIONAL, condition },
+    mapper: MAPPER,
+    model: MODEL,
+  });
+
+  expect(result).toStrictEqual({
+    kind: PlanKind.CONDITIONAL,
+    filters: { tags: { none: {} } },
   });
 });
 
 describe("timestamp literals", () => {
-  // `regenerate-wire-fixtures.sh` rewrites the folded `now() - duration("24h")` literal in
-  // `ts-window` to a placeholder, because it differs on every capture. That makes this the one
-  // fixture whose value the reader chooses — so it is also the one place the whole timestamp
-  // boundary can be walked, by substituting the instant and asking what the adapter does with it.
-  const at = (plannedAt: string) =>
+  // The golden records the folded `now() - duration("24h")` literal as `__NOW_MINUS_24H__`, because
+  // it differs on every capture. That makes this the one plan whose value the reader chooses — so
+  // it is also the one place the whole timestamp boundary can be walked, by substituting the
+  // instant and asking what the adapter does with it.
+  const at = async (plannedAt: string) =>
     queryPlanToPrisma({
-      queryPlan: planFromWireFixture("ts-window", plannedAt),
+      queryPlan: await planFor("timestamp/less-than/relative-window", plannedAt),
       mapper: MAPPER,
       model: MODEL,
     });
 
-  test("a nanosecond instant — what the PDP actually folds — is refused", () => {
-    // This, and nothing else, is why `ts-window` and `ts-vf` are `adapterUnsupported`. A tidy
-    // millisecond substitution in the loader would translate cleanly and quietly contradict
-    // actions.json.
-    expect(() => translate("ts-window")).toThrow(
-      "Timestamp value exceeds millisecond precision"
-    );
-  });
-
-  test("the same plan at millisecond precision translates", () => {
-    expect(at("2026-08-11T09:13:39.123Z")).toStrictEqual({
+  test("a nanosecond instant — what the PDP actually folds — compares against the next millisecond", async () => {
+    // A DateTime attribute is a whole millisecond, so `a < T` for a T between two milliseconds is
+    // `a < ceil(T)`. The corpus loader substitutes a nanosecond instant for the same reason.
+    expect(await at("2026-08-11T09:13:39.123456789Z")).toStrictEqual({
       kind: PlanKind.CONDITIONAL,
-      filters: { createdAt: { lt: "2026-08-11T09:13:39.123Z" } },
+      filters: { createdAt: { lt: "2026-08-11T09:13:39.124Z" } },
     });
   });
 
-  test("excess fractional digits are accepted only when they are zero", () => {
-    expect(at("2026-08-11T09:13:39.123000Z")).toStrictEqual({
+  test("excess fractional digits are accepted only when they are zero", async () => {
+    expect(await at("2026-08-11T09:13:39.123000Z")).toStrictEqual({
       kind: PlanKind.CONDITIONAL,
       filters: { createdAt: { lt: "2026-08-11T09:13:39.123Z" } },
     });
@@ -1312,10 +327,9 @@ describe("timestamp literals", () => {
     ["a date with no time part", "2024-01-01"],
     ["a year outside CEL's instant range", "0000-01-01T00:00:00Z"],
     ["a day that does not exist", "2024-02-30T00:00:00Z"],
-    ["sub-millisecond precision", "2024-01-01T00:00:00.1234Z"],
     ["an offset that pushes past the maximum instant", "9999-12-31T23:00:00-02:00"],
-  ])("%s fails closed", (_label, value) => {
-    expect(() => at(value)).toThrow(/RFC 3339|millisecond|instant range/);
+  ])("%s fails closed", async (_label, value) => {
+    await expect(at(value)).rejects.toThrow(/RFC 3339|millisecond|instant range/);
   });
 });
 
@@ -1331,40 +345,45 @@ describe("relation subqueryFilter", () => {
    */
   const VISIBLE_ONLY: PrismaFilter = { name: { not: "hidden" } };
 
-  const mapperFor = (subqueryFilter?: PrismaFilter): Mapper => ({
-    "request.resource.attr.tags": {
-      relation: {
-        name: "tags",
-        type: "many",
-        fields: { name: { field: "name" } },
-        ...(subqueryFilter ? { subqueryFilter } : {}),
-      },
-    },
-  });
+  const mapperFor = (subqueryFilter?: PrismaFilter): Mapper => {
+    const relation: Relation = {
+      name: "tags",
+      type: "many",
+      // `nullable: false` keeps the element NULL guard (see "relation element nullability"
+      // below) out of these filters, so they isolate what the declaration changes.
+      fields: { name: { field: "name", nullable: false } },
+    };
+
+    if (subqueryFilter) relation.subqueryFilter = subqueryFilter;
+
+    return { "request.resource.attr.tags": { relation } };
+  };
+
+  const filtersFor = async (action: string, subqueryFilter?: PrismaFilter) => {
+    const result = await translate(action, { mapper: mapperFor(subqueryFilter) });
 
-  const filtersFor = (action: string, subqueryFilter?: PrismaFilter) => {
-    const result = translate(action, { mapper: mapperFor(subqueryFilter) });
     if (result.kind !== PlanKind.CONDITIONAL) {
       throw new Error(`Expected CONDITIONAL result for ${action}`);
     }
+
     return result.filters;
   };
 
-  test("declared: exists() examines only the records the application serialised", () => {
-    expect(filtersFor("exists-on-empty", VISIBLE_ONLY)).toStrictEqual({
+  test("declared: exists() examines only the records the application serialised", async () => {
+    expect(await filtersFor("collection/exists/empty-collection", VISIBLE_ONLY)).toStrictEqual({
       tags: {
         some: { AND: [{ name: { not: "hidden" } }, { name: { equals: "public" } }] },
       },
     });
   });
 
-  test("declared: all() narrows the records examined, not the records required", () => {
+  test("declared: all() narrows the records examined, not the records required", async () => {
     // `every: AND(visible, P)` would REQUIRE every record to be visible, dropping any row that
     // holds a hidden tag. The rewrite to `none: AND(visible, NOT P)` is what makes the
     // declaration mean "ignore what the application hides" — including the empty-collection case,
     // where CEL's all() is vacuously true and check() agrees because the application sent an
     // empty list for the same reason.
-    expect(filtersFor("all-on-empty", VISIBLE_ONLY)).toStrictEqual({
+    expect(await filtersFor("collection/all/empty-collection", VISIBLE_ONLY)).toStrictEqual({
       tags: {
         none: {
           AND: [
@@ -1376,33 +395,41 @@ describe("relation subqueryFilter", () => {
     });
   });
 
-  test("declared: an emptiness check counts only the visible records", () => {
-    expect(filtersFor("not-empty", VISIBLE_ONLY)).toStrictEqual({
+  test("declared: an emptiness check counts only the visible records", async () => {
+    expect(await filtersFor("size/equals/negated-collection-zero", VISIBLE_ONLY)).toStrictEqual({
       NOT: { tags: { none: { name: { not: "hidden" } } } },
     });
   });
-
-  test("undeclared: the emitted filter is what it was before the field existed", () => {
-    // The non-breaking guarantee. Silence must not add a clause, and must not warn.
-    expect(filtersFor("exists-on-empty")).toStrictEqual({
-      tags: { some: { name: { equals: "public" } } },
-    });
-    expect(filtersFor("all-on-empty")).toStrictEqual({
-      tags: { every: { name: { equals: "public" } } },
-    });
-    expect(filtersFor("not-empty")).toStrictEqual({
-      NOT: { tags: { none: {} } },
-    });
-  });
 });
 
 describe("the mapper contract", () => {
   // A mapper is caller-supplied, so these are caller errors rather than policy shapes: no corpus
   // action can produce them, because the corpus fixes one mapper per adapter.
 
-  test("a function mapper resolves a scalar reference", () => {
+  test.each([undefined, true, false])(
+    "hierarchy segment nullability %s is respected",
+    async (nullable) => {
+      const result = await translate("hierarchy/overlaps/path-built-from-list-value-first", {
+        mapper: { "request.resource.attr.scope": { field: "scope", nullable } },
+      });
+
+      expect(result).toStrictEqual({
+        kind: PlanKind.CONDITIONAL,
+        filters:
+          nullable === false
+            ? {}
+            : {
+                AND: [
+                  { OR: [{ scope: { equals: "" } }, { scope: { not: "" } }] },
+                ],
+              },
+      });
+    },
+  );
+
+  test("a function mapper resolves a scalar reference", async () => {
     expect(
-      translate("cs-eq", {
+      await translate("string/equals/case-sensitive", {
         mapper: (key: string) => ({
           field: key.replace("request.resource.attr.", ""),
         }),
@@ -1413,36 +440,166 @@ describe("the mapper contract", () => {
     });
   });
 
-  test("a function mapper resolves a relation", () => {
-    expect(
-      translate("rel-bool-hop", {
-        mapper: () => ({
+  test("a key under a scalar-mapped prefix is refused, not resolved to the prefix's column", async () => {
+    // cerbos/query-plan-adapters#689: the plan reads aString beneath a prefix mapped to one column.
+    await expect(
+      translate("string/equals/case-sensitive", {
+        mapper: { "request.resource.attr": { field: "owner" } },
+      }),
+    ).rejects.toThrow(UnsupportedQueryPlanError);
+  });
+
+  test.each(["collection/exists/scalar-list-equals"])(
+    "%s resolves a projection supplied through a prefix mapper",
+    async (action) => {
+      const direct = await translate(action);
+
+      if (direct.kind !== PlanKind.CONDITIONAL) {
+        throw new Error("Expected a conditional projection plan");
+      }
+
+      const mapper: Mapper = {
+        "request.resource.attr": {
           relation: {
-            name: "parent",
-            type: "one",
-            fields: { aBool: { field: "aBool" } },
+            name: "categories",
+            type: "many",
+            fields: {
+              tagNames: {
+                relation: { name: "tags", type: "many", field: "name" },
+              },
+            },
           },
-        }),
+        },
+      };
+
+      expect(await translate(action, { mapper })).toStrictEqual({
+        kind: PlanKind.CONDITIONAL,
+        filters: { categories: { some: direct.filters } },
+      });
+    },
+  );
+
+  test("negating an overlaps that folds to an unconditional filter is refused", async () => {
+    // `nullable: false` on every segment lets `overlaps(hierarchy("dept"), hierarchy(["dept",
+    // scope]))` fold to `{}` (asserted above). Prisma evaluates `{ NOT: {} }` as true, so the
+    // negation would match every row where CEL's `!true` matches none; the adapter has no
+    // field-free false condition to emit instead (cerbos/query-plan-adapters#495).
+    const fixture = await planFor("hierarchy/overlaps/path-built-from-list-value-first");
+
+    if (fixture.kind !== PlanKind.CONDITIONAL) {
+      throw new Error("Expected a conditional hierarchy plan");
+    }
+
+    expect(() =>
+      queryPlanToPrisma({
+        queryPlan: {
+          ...fixture,
+          condition: { operator: "not", operands: [fixture.condition] },
+        },
+        mapper: { "request.resource.attr.scope": { field: "scope", nullable: false } },
       })
-    ).toStrictEqual({
-      kind: PlanKind.CONDITIONAL,
-      filters: { parent: { is: { aBool: { equals: true } } } },
+    ).toThrow("Cannot negate an unconditional filter");
+  });
+
+  describe("relation element nullability", () => {
+    // Omitting the element NULL guard is what over-grants — a negated exists(), an all() or a
+    // hasIntersection() over map() would admit rows holding a NULL element that check() denies
+    // — so silence means nullable, and only `nullable: false` drops the guard
+    // (cerbos/query-plan-adapters#495). The corpus maps one element column per nullability, so
+    // it cannot vary the declaration itself.
+    const guarded = {
+      AND: [
+        { tags: { every: { name: { equals: "public" } } } },
+        { tags: { none: { name: null } } },
+      ],
+    };
+
+    const unguarded = { tags: { every: { name: { equals: "public" } } } };
+
+    const allFor = (fields?: Relation["fields"]) => {
+      const relation: Relation = { name: "tags", type: "many" };
+
+      if (fields) relation.fields = fields;
+
+      return translate("collection/all/empty-collection", {
+        mapper: { "request.resource.attr.tags": { relation } },
+      });
+    };
+
+    test.each<[string, Relation["fields"], PrismaFilter]>([
+      ["undeclared", { name: { field: "name" } }, guarded],
+      ["nullable: true", { name: { field: "name", nullable: true } }, guarded],
+      ["nullable: false", { name: { field: "name", nullable: false } }, unguarded],
+      ["an element with no field mapping at all", undefined, guarded],
+    ])("%s", async (_label, fields, filters) => {
+      expect(await allFor(fields)).toStrictEqual({
+        kind: PlanKind.CONDITIONAL,
+        filters,
+      });
     });
   });
 
-  test("size() against a scalar mapping is refused rather than guessed", () => {
-    expect(() =>
-      translate("not-empty", {
+  test("size() against a scalar mapping is refused rather than guessed", async () => {
+    await expect(
+      translate("size/equals/negated-collection-zero", {
         mapper: { "request.resource.attr.tags": { field: "tags" } },
       })
-    ).toThrow("size operator requires a relation mapping");
+    ).rejects.toThrow("size operator requires a relation mapping");
+  });
+});
+
+describe("which patterns RE2 rejects", () => {
+  // matches() raises an error on a pattern RE2 rejects, which denies every row, so the adapter
+  // must agree with RE2 on exactly which patterns those are. The corpus pins the rejected shapes
+  // it carries; this pins the one the previous hand-rolled check got wrong: a digit after a
+  // backslash is a backreference to RE2 only on its own, and an octal escape when another octal
+  // digit follows, so `\11` is a tab.
+  const matches = (pattern: string, sibling = false): PlanResourcesResponse => {
+    const test: PlanExpressionOperand = {
+      operator: "matches",
+      operands: [{ name: "request.resource.attr.aString" }, { value: pattern }],
+    };
+
+    const condition: PlanExpressionOperand = sibling
+      ? {
+          operator: "or",
+          operands: [test, { operator: "eq", operands: [{ name: "request.resource.attr.aNumber" }, { value: 5 }] }],
+        }
+      : test;
+
+    return {
+      kind: PlanKind.CONDITIONAL,
+      condition,
+      cerbosCallId: "",
+      requestId: "",
+      validationErrors: [],
+      metadata: undefined,
+    };
+  };
+
+  test("an octal escape is the character it names, not a backreference", () => {
+    const result = queryPlanToPrisma({ queryPlan: matches("^\\11"), mapper: MAPPER, model: MODEL });
+    expect(result.kind).toBe(PlanKind.CONDITIONAL);
+  });
+
+  test("a backreference is an error on every row, so only its sibling decides", () => {
+    const result = queryPlanToPrisma({
+      queryPlan: matches("(a)\\1", true),
+      mapper: MAPPER,
+      model: MODEL,
+    });
+
+    expect(result).toEqual({ kind: PlanKind.CONDITIONAL, filters: { aNumber: { equals: 5 } } });
+    expect(queryPlanToPrisma({ queryPlan: matches("\\8"), mapper: MAPPER, model: MODEL })).toEqual({
+      kind: PlanKind.ALWAYS_DENIED,
+    });
   });
 });
 
 describe("plans the planner cannot produce", () => {
   // Input validation on a public function, not policy shapes. Every other assertion in this file
-  // reads its plan from a fixture precisely because a typed plan is a belief about the planner —
-  // but these are malformed by construction, so there is no fixture to read and nothing to
+  // reads its plan from a golden file precisely because a typed plan is a belief about the planner —
+  // but these are malformed by construction, so there is no golden to read and nothing to
   // believe. They exist so a caller who hands the adapter a hand-rolled or half-decoded plan gets
   // an error rather than a filter.
   //
@@ -1451,20 +608,28 @@ describe("plans the planner cannot produce", () => {
   // pinned here by hand-built plan before #377 and are now
   // [#394](https://github.com/cerbos/query-plan-adapters/issues/394).
 
-  const plan = (condition: unknown): PlanResourcesResponse =>
-    ({
-      kind: PlanKind.CONDITIONAL,
-      condition: condition as PlanExpressionOperand,
-      cerbosCallId: "",
-      requestId: "",
-      validationErrors: [],
-      metadata: undefined,
-    }) as PlanResourcesResponse;
+  const plan = (condition: Value): PlanResourcesResponse =>
+    overwritten(
+      {
+        kind: PlanKind.CONDITIONAL,
+        condition: { value: true },
+        cerbosCallId: "",
+        requestId: "",
+        validationErrors: [],
+        metadata: undefined,
+      },
+      "condition",
+      condition,
+    );
 
   test("an unrecognised plan kind", () => {
     expect(() =>
       queryPlanToPrisma({
-        queryPlan: { kind: "INVALID_KIND" } as unknown as PlanResourcesResponse,
+        queryPlan: overwritten(
+          { kind: PlanKind.ALWAYS_ALLOWED, cerbosCallId: "", requestId: "", validationErrors: [], metadata: undefined },
+          "kind",
+          "INVALID_KIND"
+        ),
         mapper: {},
       })
     ).toThrow("Invalid query plan.");
@@ -1570,17 +735,32 @@ describe("plans the planner cannot produce", () => {
     ).toThrow("exists over a literal collection requires a list value");
   });
 
-  test("a constant-false predicate the planner should have folded", () => {
+  // An empty conjunction is `{ AND: [] }` in Prisma, which matches every row, and the constant
+  // folder would otherwise reduce it to `true` before the translator saw it
+  // (cerbos/query-plan-adapters#495). The empty disjunction is refused alongside it: neither is
+  // something the planner emits.
+  test.each<[string, Value, string]>([
+    ["an empty and", { operator: "and", operands: [] }, "and requires at least one operand"],
+    ["an empty or", { operator: "or", operands: [] }, "or requires at least one operand"],
+    [
+      "an empty and under an or",
+      {
+        operator: "or",
+        operands: [
+          { name: "request.resource.attr.aBool" },
+          { operator: "and", operands: [] },
+        ],
+      },
+      "and requires at least one operand",
+    ],
+    [
+      "an empty and under a not",
+      { operator: "not", operands: [{ operator: "and", operands: [] }] },
+      "and requires at least one operand",
+    ],
+  ])("%s", (_label, condition, message) => {
     expect(() =>
-      queryPlanToPrisma({
-        queryPlan: plan({
-          operator: "if",
-          operands: [{ value: true }, { value: false }, { value: true }],
-        }),
-        mapper: MAPPER,
-      })
-    ).toThrow(
-      "A constant-false conditional predicate must be folded by the Cerbos planner"
-    );
+      queryPlanToPrisma({ queryPlan: plan(condition), mapper: MAPPER })
+    ).toThrow(message);
   });
 });