@cerbos/orm-prisma 4.1.0 → 5.0.0

package/src/corpus.ts

@@ -1,289 +1,437 @@
 import * as fs from "fs";
 import * as path from "path";
+import { isDeepStrictEqual } from "util";
 
-import {
-  PlanExpression,
-  PlanExpressionValue,
-  PlanExpressionVariable,
-} from "@cerbos/core";
-import type {
-  PlanExpressionOperand,
-  PlanResourcesResponse,
-  Value,
-} from "@cerbos/core";
+import { fromBinary, fromJson, fromJsonString, toBinary } from "@bufbuild/protobuf";
+import type { JsonObject, JsonValue } from "@bufbuild/protobuf";
+import type { PlanResourcesRequest } from "@cerbos/api/cerbos/request/v1/request_pb";
+import type { PlanResourcesResponse as PlanResourcesResponseMessage } from "@cerbos/api/cerbos/response/v1/response_pb";
+import { CerbosService } from "@cerbos/api/cerbos/svc/v1/svc_pb";
+import type { PlanResourcesResponse } from "@cerbos/core";
+import { GRPC } from "@cerbos/grpc";
+import { HTTP } from "@cerbos/http";
+import { Server, ServerCredentials } from "@grpc/grpc-js";
+import type { sendUnaryData, ServerUnaryCall } from "@grpc/grpc-js";
+import { afterAll } from "@jest/globals";
 
-import { PlanKind, MapperConfig } from ".";
+import type { MapperConfig } from ".";
+import { isObject, isString } from "./narrowing";
 
 /**
- * The parts of the shared `../conformance/` corpus that both of this adapter's suites read.
- *
- * `adversarial.test.ts` plans against a real PDP and executes the translated query;
- * `translator.test.ts` reads the same actions off the golden wire fixtures and asserts nothing
- * but the emitted filter. They must agree on two things or they prove less than they appear to:
- *
- * - **the mapper.** The unit test pins the filter this adapter emits for a mapping; the harness
- *   proves that same filter returns the rows the PDP allows. Two copies that drifted would leave
- *   the pinned filters describing a mapping no harness ever executes.
- * - **the classification.** Which actions this adapter must refuse, and with which message, is a
- *   corpus decision (`actions.json`), not a per-suite one.
+ * What both of this adapter's suites read from the shared `../conformance/` corpus: the recorded
+ * golden plans and the one mapper every case is translated through. `adversarial.test.ts` replays
+ * the goldens against a real store; `translator.test.ts` uses the same mapper for the caller-option
+ * tests the corpus cannot vary.
  *
+ * Duplicated across adapters on purpose — adapters share data, not code (ADR 0007).
  * Test-only: excluded from `tsc --build` by `tsconfig.json`, so nothing here reaches `lib/`.
  */
 
-export const CONFORMANCE_DIR = path.join(
-  __dirname,
-  "..",
-  "..",
-  "conformance"
-);
+export const CONFORMANCE_DIR = path.join(__dirname, "..", "..", "conformance");
 
-const WIRE_FIXTURES_DIR = path.join(CONFORMANCE_DIR, "wire-fixtures");
+/** A file the conformance generator wrote: its shape is the generator's contract with these types. */
+function readJson<T>(file: string): T {
+  return JSON.parse(fs.readFileSync(file, "utf8"));
+}
+
+export function readCorpusJson<T>(file: string): T {
+  return readJson(path.join(CONFORMANCE_DIR, file));
+}
 
 /** The Prisma model the corpus's resource kind maps onto. */
 export const MODEL = "AdversarialResource";
 
-// -- actions.json --------------------------------------------------------------------------------
+// -- the golden files ----------------------------------------------------------------------------
+
+export interface Golden {
+  id: string;
+  pdp: string;
+  tier: "core" | "extended" | "adversarial";
+  plan: JsonObject;
+  allowed: string[];
+  plannerDivergence: { pdp?: string[]; issue: string; reason?: string } | null;
+}
+
+/** The PDP tags the goldens were recorded against: current first, then previous. */
+export function pdpTags(): string[] {
+  const versions = readCorpusJson<Record<
+    "current" | "previous",
+    { tag: string }
+  >>("pdp-versions.json");
 
-export interface UnsupportedShape {
-  action: string;
-  shape: string;
-  /** One entry per adapter that must reject the shape; the corpus asserts the key set. */
-  messages: Record<string, string>;
+  return [versions.current.tag, versions.previous.tag];
 }
 
-export interface AdapterUnsupportedEntry {
-  action: string;
-  reason: string;
-  /** Absent on `adapterSupportedExpected` / `nullRepresentationOmitted`, required on a throw. */
-  message?: string;
+/** Every golden file recorded against `tag`, sorted by case id. */
+export function readGoldens(tag: string): Golden[] {
+  const root = FUZZ_DIR ? path.join(FUZZ_DIR, tag) : path.join(CONFORMANCE_DIR, "golden", tag);
+
+  const files = fs.readdirSync(root, { recursive: true, encoding: "utf8" })
+    .filter((file) => file.endsWith(".json"))
+    .map((file) => readJson<Golden>(path.join(root, file)));
+
+  return files.sort((a, b) => a.id.localeCompare(b.id));
 }
 
+export function readGolden(tag: string, id: string): Golden {
+  return readJson(path.join(CONFORMANCE_DIR, "golden", tag, `${id}.json`));
+}
+
+// -- fuzz mode ------------------------------------------------------------------------------------
+
 /**
- * A `nullRepresentationOmitted` entry. Every adapter must reject these — the two NULL conventions
- * are indistinguishable on the wire — so `messages` names the whole roster with no promotions to
- * subtract.
+ * The directory a fuzz run was recorded into (conformance/README.md, "Fuzzing"). When it is set,
+ * `readGoldens` reads the generated cases from it instead of the corpus, and the harness judges
+ * each case by `fuzzVerdict` instead of the ledger: a refusal is always acceptable, since the
+ * ledger has no entry for a shape nobody has written down yet.
  */
-export interface NullRepresentationOmittedEntry {
-  action: string;
-  reason: string;
-  messages: Record<string, string>;
+export const FUZZ_DIR = process.env["QPA_FUZZ_DIR"] || undefined;
+
+export interface FuzzVerdict {
+  pdp: string;
+  id: string;
+  verdict: "match" | "refused" | "over-grant" | "under-grant" | "error";
+  expected?: string[];
+  returned?: string[];
+  detail?: string;
+}
+
+/** Judges the ids a translated filter returned against the ids the PDP allowed. */
+export function fuzzVerdict(golden: Golden, expected: string[], returned: string[]): FuzzVerdict {
+  const base = { pdp: golden.pdp, id: golden.id };
+
+  // Compared element by element: under jest the arrays come from different realms, which
+  // isDeepStrictEqual tells apart.
+  if (returned.length === expected.length && returned.every((id, i) => id === expected[i])) {
+    return { ...base, verdict: "match" };
+  }
+
+  const allowed = new Set(expected);
+  const got = new Set(returned);
+
+  const verdict = returned.some((id) => !allowed.has(id))
+    ? "over-grant"
+    : expected.some((id) => !got.has(id))
+      ? "under-grant"
+      : "error";
+
+  if (verdict === "error") {
+    return { ...base, verdict, expected, returned, detail: "the right rows, but repeated or out of order" };
+  }
+
+  return { ...base, verdict, expected, returned };
+}
+
+/** A translation or query that threw, judged: the adapter's refusal type is the invariant working. */
+export function fuzzThrown(golden: Golden, cause: unknown, refusal: abstract new (...args: never[]) => Error): FuzzVerdict {
+  const base = { pdp: golden.pdp, id: golden.id };
+
+  if (cause instanceof refusal) return { ...base, verdict: "refused" };
+
+  return { ...base, verdict: "error", detail: cause instanceof Error ? `${cause.name}: ${cause.message}` : String(cause) };
+}
+
+/** Fails the case unless its verdict is a match or a refusal. */
+export function assertFuzzVerdict(verdict: FuzzVerdict): void {
+  if (verdict.verdict === "match" || verdict.verdict === "refused") return;
+  throw new Error(
+    `${verdict.verdict}: expected [${verdict.expected?.join(", ") ?? ""}], returned [${verdict.returned?.join(", ") ?? ""}]${verdict.detail ? `: ${verdict.detail}` : ""}`,
+  );
 }
 
-export interface KnownDivergence {
-  action: string;
-  adapters: string[];
+/** Writes `<FUZZ_DIR>/results/<adapter>-<store>.json`, which `fuzz-report` reads. */
+export function writeFuzzResults(adapter: string, store: string, results: FuzzVerdict[]): void {
+  if (!FUZZ_DIR) return;
+  const dir = path.join(FUZZ_DIR, "results");
+  fs.mkdirSync(dir, { recursive: true });
+  const sorted = [...results].sort((a, b) => a.id.localeCompare(b.id) || a.pdp.localeCompare(b.pdp));
+  fs.writeFileSync(
+    path.join(dir, `${adapter}-${store}.json`),
+    `${JSON.stringify({ adapter, store, results: sorted }, null, 2)}\n`,
+  );
 }
 
-export interface ActionsFile {
-  conformance: string[];
-  adapterUnsupported?: Record<string, AdapterUnsupportedEntry[]>;
-  adapterSupportedExpected?: Record<string, AdapterUnsupportedEntry[]>;
-  expectedUnsupported: UnsupportedShape[];
-  nullRepresentationOmitted: NullRepresentationOmittedEntry[];
-  knownDivergences?: KnownDivergence[];
+/**
+ * The instant substituted for `__NOW_MINUS_24H__`, the literal the planner folds
+ * `now() - duration("24h")` into. The PDP folds its clock at nanosecond precision, so the
+ * substitute carries sub-millisecond digits too: a tidy millisecond instant would translate here
+ * while the same case refuses in production (`Timestamp value exceeds millisecond precision`).
+ */
+export function nowMinus24h(): string {
+  const ms = new Date(Date.now() - 24 * 60 * 60 * 1000).toISOString();
+
+  return `${ms.slice(0, -1)}456789Z`;
 }
 
+// -- the plans, as the SDK returns them ----------------------------------------------------------
+
+/*
+ * A golden reaches the adapter through both official JS clients, `@cerbos/http` and
+ * `@cerbos/grpc`, so it arrives as an application's `planResources` call returns it. Only the PDP
+ * is replaced: each transport has a stub that answers PlanResources with the response registered
+ * under the request's `requestId`, a token unique to one call. A plan the two clients decode
+ * differently fails the case, so every case also proves the adapter is handed the same input
+ * whichever transport the application uses.
+ */
+
 /**
- * A shape this adapter must refuse, with the substring its error has to contain.
- *
- * The message is what turns "it threw" into "it threw for the declared reason": without it a
- * mapper typo or an unrelated validation satisfies the assertion just as well as the limitation
- * the corpus documents (cerbos/query-plan-adapters#326).
+ * The base URL of the stubbed HTTP PDP. `.invalid` never resolves, so a request that escapes the
+ * stub fails rather than reaching a real server.
  */
-export type ThrowingAction = readonly [
-  action: string,
-  reason: string,
-  message: string,
-];
-
-export interface ActionClassification {
-  oracleActions: string[];
-  throwingActions: ThrowingAction[];
-  supportedExpected: Set<string>;
+const STUB_HTTP_PDP = "http://stub-pdp.invalid";
+
+const planResources = CerbosService.method.planResources;
+
+/** The response bodies waiting to be served, by the `requestId` of the call that will read them. */
+const pendingResponses = new Map<string, JsonObject>();
+let requestCount = 0;
+
+function takeResponse(requestId: string): JsonObject {
+  const body = pendingResponses.get(requestId);
+  pendingResponses.delete(requestId);
+
+  if (body === undefined) throw new Error(`stub PDP: no response for request ${requestId}`);
+
+  return body;
 }
 
-/** The pinned message, or a failure — a throwing action without one asserts nothing. */
-export function requireMessage(
-  label: string,
-  message: string | undefined
-): string {
-  if (message === undefined || message === "") {
-    throw new Error(
-      `actions.json pins no throw message for ${label}: the throw suite would accept a failure for any reason`
-    );
-  }
-  return message;
+function requestUrl(input: Parameters<typeof fetch>[0]): string {
+  if (isString(input)) return input;
+
+  return input instanceof URL ? input.href : input.url;
 }
 
-export function classifyActionsForAdapter(
-  manifest: ActionsFile,
-  adapter: string
-): ActionClassification {
-  const unsupported = manifest.adapterUnsupported?.[adapter] ?? [];
-  const unsupportedActions = new Set(unsupported.map((entry) => entry.action));
-  const supportedExpected = new Set(
-    (manifest.adapterSupportedExpected?.[adapter] ?? []).map(
-      (entry) => entry.action
-    )
-  );
-  const oracleActions = [
-    ...manifest.conformance.filter(
-      (action) => !unsupportedActions.has(action)
-    ),
-    ...supportedExpected,
-  ];
-  const throwingActions: ThrowingAction[] = [
-    ...unsupported.map(
-      (entry): ThrowingAction => [
-        entry.action,
-        entry.reason,
-        requireMessage(`adapterUnsupported.${adapter}.${entry.action}`, entry.message),
-      ]
-    ),
-    ...manifest.expectedUnsupported
-      .filter((entry) => !supportedExpected.has(entry.action))
-      .map((entry): ThrowingAction => [
-        entry.action,
-        entry.shape,
-        requireMessage(
-          `expectedUnsupported.${entry.action}.messages.${adapter}`,
-          entry.messages?.[adapter]
-        ),
-      ]),
-  ];
-
-  return {
-    oracleActions: [...new Set(oracleActions)].sort(),
-    throwingActions: throwingActions.sort(([left], [right]) =>
-      left.localeCompare(right)
-    ),
-    supportedExpected,
+/**
+ * An `@cerbos/http` client whose PlanResources call is answered here. Only requests to
+ * `STUB_HTTP_PDP` are intercepted; every other `fetch` goes through untouched.
+ */
+function httpClient(): HTTP {
+  const passthrough = globalThis.fetch;
+  globalThis.fetch = async (input, init) => {
+    if (!requestUrl(input).startsWith(STUB_HTTP_PDP)) return passthrough(input, init);
+    const { requestId } = fromJsonString(planResources.input, String(init?.body), { ignoreUnknownFields: true });
+
+    return new Response(toProtoJson(takeResponse(requestId)), {
+      status: 200,
+      headers: { "Content-Type": "application/json" },
+    });
   };
-}
 
-// -- the golden wire fixtures --------------------------------------------------------------------
+  return new HTTP(STUB_HTTP_PDP);
+}
 
 /**
- * The instant `regenerate-wire-fixtures.sh` substitutes for the one operand it cannot pin.
- *
- * `ts-window` and `ts-vf` compare against `now() - duration("24h")`, which the planner folds to a
- * literal timestamp: a different value on every capture, so the script rewrites it to
- * `__NOW_MINUS_24H__` to keep the drift check deterministic. Reading the fixture back therefore
- * means choosing a value, and the choice is load-bearing rather than arbitrary — Cerbos emits the
- * PDP's clock at nanosecond precision, which is exactly why both actions are `adapterUnsupported`
- * for this adapter (`Timestamp value exceeds millisecond precision`). A tidy millisecond instant
- * here would translate cleanly and quietly contradict `actions.json`, so the fraction carries the
- * nine digits a real plan carries. `translator.test.ts` pins both sides of that boundary, which is
- * what the `plannedAt` override on `planFromWireFixture` is for.
+ * An `@cerbos/grpc` client connected to an in-process gRPC server on a loopback port, which
+ * answers PlanResources with the registered response encoded as the protobuf a PDP sends.
  */
-export const PLANNED_AT = "2026-08-11T09:13:39.123456789Z";
+async function grpcClient(): Promise<{ client: GRPC; server: Server }> {
+  const server = new Server();
+  server.addService(
+    {
+      planResources: {
+        path: `/${CerbosService.typeName}/${planResources.name}`,
+        requestStream: false,
+        responseStream: false,
+        requestSerialize: (message: PlanResourcesRequest) =>
+          Buffer.from(toBinary(planResources.input, message)),
+        requestDeserialize: (bytes: Buffer) => fromBinary(planResources.input, bytes),
+        responseSerialize: (message: PlanResourcesResponseMessage) =>
+          Buffer.from(toBinary(planResources.output, message)),
+        responseDeserialize: (bytes: Buffer) => fromBinary(planResources.output, bytes),
+      },
+    },
+    {
+      planResources: (
+        call: ServerUnaryCall<PlanResourcesRequest, PlanResourcesResponseMessage>,
+        respond: sendUnaryData<PlanResourcesResponseMessage>
+      ) => {
+        try {
+          respond(null, fromJson(planResources.output, takeResponse(call.request.requestId)));
+        } catch (error) {
+          respond(error instanceof Error ? error : new Error(String(error)), null);
+        }
+      },
+    }
+  );
 
-interface WireOperand {
-  expression?: { operator: string; operands: WireOperand[] };
-  variable?: string;
-  value?: unknown;
+  const port = await new Promise<number>((resolve, reject) =>
+    server.bindAsync("127.0.0.1:0", ServerCredentials.createInsecure(), (error, bound) =>
+      error ? reject(error) : resolve(bound)
+    )
+  );
+
+  // The stub is on loopback; never route it through an ambient proxy.
+  const client = new GRPC(`127.0.0.1:${port}`, {
+    tls: false,
+    channelOptions: { "grpc.enable_http_proxy": 0 },
+  });
+
+  return { client, server };
 }
 
-interface WireFixture {
-  action: string;
-  resourceKind: string;
-  filter: { kind: string; condition?: WireOperand };
+let stubClients: Promise<{ http: HTTP; grpc: GRPC; server: Server }> | undefined;
+
+function sdkClients(): Promise<{ http: HTTP; grpc: GRPC; server: Server }> {
+  stubClients ??= grpcClient().then(({ client, server }) => ({
+    http: httpClient(),
+    grpc: client,
+    server,
+  }));
+
+  return stubClients;
 }
 
-function operandFromWire(
-  node: WireOperand,
-  plannedAt: string
-): PlanExpressionOperand {
-  if (node.expression) {
-    return new PlanExpression(
-      node.expression.operator,
-      node.expression.operands.map((child) => operandFromWire(child, plannedAt))
+afterAll(async () => {
+  if (!stubClients) return;
+  const { grpc, server } = await stubClients;
+  grpc.close();
+  server.forceShutdown();
+});
+
+/**
+ * JSON as the PDP writes it. `JSON.stringify` writes -0 as `0`, where protojson keeps the sign, so
+ * a stub serialising with it would hand the SDK a different number from the one the PDP sends.
+ */
+function toProtoJson(node: JsonValue): string {
+  if (Object.is(node, -0)) return "-0";
+
+  if (Array.isArray(node)) return `[${node.map(toProtoJson).join(",")}]`;
+
+  if (isObject(node)) {
+    const members = Object.entries(node).map(
+      ([key, child]) => `${JSON.stringify(key)}:${toProtoJson(child)}`
     );
+
+    return `{${members.join(",")}}`;
   }
-  if (node.variable !== undefined) {
-    return new PlanExpressionVariable(node.variable);
-  }
-  if (!("value" in node)) {
-    throw new Error(
-      `Wire fixture operand is neither an expression, a variable nor a value: ${JSON.stringify(node)}`
+
+  return JSON.stringify(node);
+}
+
+function substituteNow(node: JsonValue, now: string): JsonValue {
+  if (node === "__NOW_MINUS_24H__") return now;
+
+  if (Array.isArray(node)) return node.map((child) => substituteNow(child, now));
+
+  if (isObject(node)) {
+    return Object.fromEntries(
+      Object.entries(node).map(([key, child]) => [key, substituteNow(child, now)])
     );
   }
-  // The one cast in this file. A fixture is JSON the PDP produced, so its leaves are already
-  // exactly the JSON shapes `Value` admits — but `JSON.parse` cannot say so, and re-validating a
-  // file the corpus workflow regenerates and diffs would assert nothing new.
-  return new PlanExpressionValue(
-    (node.value === "__NOW_MINUS_24H__" ? plannedAt : node.value) as Value
-  );
+
+  return node;
 }
 
-/** Every action the corpus has a golden wire fixture for, sorted. */
-export function wireFixtureActions(): string[] {
-  return fs
-    .readdirSync(WIRE_FIXTURES_DIR)
-    .filter((name) => name.endsWith(".json"))
-    .map((name) => name.slice(0, -".json".length))
-    .sort();
+/** One PlanResources call through `client`, answered with `response`. */
+function fetchPlan(
+  client: HTTP | GRPC,
+  golden: Golden,
+  response: JsonObject
+): Promise<PlanResourcesResponse> {
+  const requestId = `${golden.id}#${++requestCount}`;
+  pendingResponses.set(requestId, response);
+
+  return client.planResources({
+    requestId,
+    principal: { id: "stub", roles: ["USER"] },
+    resource: { kind: "conformance" },
+    action: golden.id,
+  });
 }
 
 /**
- * The plan the pinned PDP produced for `action`, decoded into the shape the SDK hands callers.
- *
- * The fixture is the PDP's HTTP response, so the decoding here is the one `@cerbos/http` performs
- * — `{expression|variable|value}` nodes into `PlanExpression` / `PlanExpressionVariable` /
- * `PlanExpressionValue`. It is deliberately not a hand-built plan: a plan somebody typed is a
- * belief about what the planner emits, and this repository keeps fixtures precisely because that
- * belief has been wrong before. See docs/adr/0006.
+ * A golden's plan as the SDK returns it: the recorded `filter` is served as the response to a
+ * stubbed PlanResources call over each transport, so the SDK's own decoding produces what the
+ * adapter receives.
  */
-export function planFromWireFixture(
-  action: string,
-  plannedAt: string = PLANNED_AT
-): PlanResourcesResponse {
-  const fixture: WireFixture = JSON.parse(
-    fs.readFileSync(path.join(WIRE_FIXTURES_DIR, `${action}.json`), "utf8")
-  );
-  const base = {
-    cerbosCallId: "",
-    requestId: "",
-    validationErrors: [],
-    metadata: undefined,
+export async function planOf(
+  golden: Golden,
+  now: string = nowMinus24h()
+): Promise<PlanResourcesResponse> {
+  const response: JsonObject = {
+    requestId: golden.id,
+    action: golden.id,
+    resourceKind: "conformance",
+    policyVersion: "default",
+    filter: substituteNow(golden.plan, now),
   };
-  switch (fixture.filter.kind) {
-    case PlanKind.CONDITIONAL:
-      if (!fixture.filter.condition) {
-        throw new Error(`Wire fixture ${action} is conditional with no condition`);
-      }
-      return {
-        ...base,
-        kind: PlanKind.CONDITIONAL,
-        condition: operandFromWire(fixture.filter.condition, plannedAt),
-      };
-    case PlanKind.ALWAYS_ALLOWED:
-    case PlanKind.ALWAYS_DENIED:
-      return { ...base, kind: fixture.filter.kind };
-    default:
-      throw new Error(
-        `Wire fixture ${action} has an unrecognised filter kind ${fixture.filter.kind}`
-      );
+
+  const { http, grpc } = await sdkClients();
+
+  const [overHttp, overGrpc] = await Promise.all([
+    fetchPlan(http, golden, response),
+    fetchPlan(grpc, golden, response),
+  ]);
+
+  if (!isDeepStrictEqual(overHttp, overGrpc)) {
+    throw new Error(`${golden.id}: @cerbos/http and @cerbos/grpc decode the plan differently`);
   }
+
+  return overGrpc;
 }
 
 // -- the mapper ----------------------------------------------------------------------------------
 
-export const MAPPER: Record<string, MapperConfig> = {
-  // The primary key, reached as `request.resource.id` rather than through `attr` (the `id-*`
-  // actions). It is a mapping like any other here, which is the point: an adapter that resolves
+interface ConformanceMapper {
+  [reference: string]: MapperConfig;
+}
+
+export const MAPPER: ConformanceMapper = {
+  // The primary key, reached as `request.resource.id` rather than through `attr` (the
+  // `identifier/*` cases). It is a mapping like any other here, which is the point: an adapter that resolves
   // references by stripping a `request.resource.attr.` prefix never sees this name.
-  "request.resource.id": { field: "id" },
-  "request.resource.attr.aBool": { field: "aBool" },
-  "request.resource.attr.aString": { field: "aString" },
-  "request.resource.attr.aNumber": { field: "aNumber" },
-  "request.resource.attr.aDouble": { field: "aDouble" },
-  "request.resource.attr.aOptionalString": { field: "aOptionalString" },
-  "request.resource.attr.createdBy": { field: "createdBy" },
-  "request.resource.attr.scope": { field: "scope" },
+  "request.resource.id": { field: "id", valueType: "string" },
+  // Every attribute resources.json OMITS when its column is NULL follows the omitted convention:
+  // aBool, aString and aNumber (NULL on j3, j1, j2), aOptionalString, aDouble, scope, createdAt,
+  // updatedAt, obj.inner and every `parent` field. A null literal against one is then a
+  // missing-attribute error the PDP denies, never an IS NULL match (#528).
+  "request.resource.attr.aBool": {
+    field: "aBool",
+    valueType: "boolean",
+    nullable: true,
+    nullAttributeRepresentation: "omitted",
+  },
+  "request.resource.attr.aString": {
+    field: "aString",
+    valueType: "string",
+    nullable: true,
+    nullAttributeRepresentation: "omitted",
+  },
+  "request.resource.attr.aNumber": {
+    field: "aNumber",
+    valueType: "number",
+    nullable: true,
+    nullAttributeRepresentation: "omitted",
+  },
+  "request.resource.attr.aDouble": {
+    field: "aDouble",
+    valueType: "number",
+    nullAttributeRepresentation: "omitted",
+  },
+  // resources.json OMITS aOptionalString when the column is NULL, so `== null` against it is a
+  // missing-attribute error the PDP denies, never an IS NULL match.
+  "request.resource.attr.aOptionalString": {
+    field: "aOptionalString",
+    valueType: "string",
+    nullable: true,
+    nullAttributeRepresentation: "omitted",
+  },
+  "request.resource.attr.createdBy": { field: "createdBy", valueType: "string" },
+  "request.resource.attr.scope": {
+    field: "scope",
+    valueType: "string",
+    nullable: true,
+    nullAttributeRepresentation: "omitted",
+  },
   "request.resource.attr.createdAt": {
     field: "createdAt",
     valueType: "dateTime",
+    nullAttributeRepresentation: "omitted",
+  },
+  "request.resource.attr.updatedAt": {
+    field: "updatedAt",
+    valueType: "dateTime",
+    nullAttributeRepresentation: "omitted",
   },
   // `owner` and `coOwner` alias columns that `aOptionalString` and `scope` also map, under the
   // OTHER null convention: the oracle sends a real null attribute for them rather than omitting
@@ -291,42 +439,52 @@ export const MAPPER: Record<string, MapperConfig> = {
   // and leaves it untouched for every other mapping (cerbos/query-plan-adapters#308).
   "request.resource.attr.owner": {
     field: "aOptionalString",
+    valueType: "string",
     nullable: true,
     nullAttributeRepresentation: "explicit",
   },
   "request.resource.attr.coOwner": {
     field: "scope",
+    valueType: "string",
     nullable: true,
     nullAttributeRepresentation: "explicit",
   },
-  // obj.inner is not a real nested column — mirrors aString, same trick the spring-data
-  // reference harness uses for the p-struct probe. `parent.inner` below is the opposite: a real
-  // two-level join. The two are kept side by side on purpose.
-  "request.resource.attr.obj.inner": { field: "aString" },
-  // The corpus's one REAL to-one chain (the `rel-*` actions). `type: "one"` is what makes the
+  // obj.inner is not a real nested column — mirrors aString, same trick the spring-data reference
+  // harness uses for the comparison/equals/nested-map-member case. `parent.inner` below is the
+  // opposite: a real two-level join. The two are kept side by side on purpose.
+  "request.resource.attr.obj.inner": {
+    field: "aString",
+    valueType: "string",
+    nullable: true,
+    nullAttributeRepresentation: "omitted",
+  },
+  // The corpus's one REAL to-one chain (the `relation/*` cases). `type: "one"` is what makes the
   // adapter emit `is:` rather than `some:`, and `is:` on an optional relation is what requires
   // the hop to exist — the absent-parent guard the negated shapes discriminate. `inner` nests
   // the same declaration one level further out; two levels is where alias scoping breaks.
+  // A column reached through a relation takes the relation entry's null convention, so the one
+  // declaration here covers every `parent.*` and `parent.inner.*` field.
   "request.resource.attr.parent": {
+    nullAttributeRepresentation: "omitted",
     relation: {
       name: "parent",
       type: "one",
       model: "AdversarialParent",
       fields: {
-        aBool: { field: "aBool" },
-        aString: { field: "aString" },
-        aNumber: { field: "aNumber" },
-        aOptionalString: { field: "aOptionalString", nullable: true },
+        aBool: { field: "aBool", valueType: "boolean", nullable: true },
+        aString: { field: "aString", valueType: "string", nullable: true },
+        aNumber: { field: "aNumber", valueType: "number", nullable: true },
+        aOptionalString: { field: "aOptionalString", valueType: "string", nullable: true  },
         inner: {
           relation: {
             name: "inner",
             type: "one",
             model: "AdversarialInner",
             fields: {
-              aBool: { field: "aBool" },
-              aString: { field: "aString" },
-              aNumber: { field: "aNumber" },
-              aOptionalString: { field: "aOptionalString", nullable: true },
+              aBool: { field: "aBool", valueType: "boolean", nullable: true },
+              aString: { field: "aString", valueType: "string", nullable: true },
+              aNumber: { field: "aNumber", valueType: "number", nullable: true },
+              aOptionalString: { field: "aOptionalString", valueType: "string", nullable: true  },
             },
           },
         },
@@ -337,14 +495,15 @@ export const MAPPER: Record<string, MapperConfig> = {
     relation: {
       name: "tags",
       type: "many",
-      // Model name enables field-to-field comparisons between tag columns; the nullable
-      // flag on `name` enables the adapter's three-valued-logic guards for collection
-      // macros over elements whose name column is NULL (a missing attribute — a CEL
-      // error, hence deny — on the check side).
+      // Model name enables field-to-field comparisons between tag columns. `name` is NULLable
+      // in the schema, so it keeps the adapter's three-valued-logic guards for collection
+      // macros over elements whose name column is NULL (a missing attribute — a CEL error,
+      // hence deny — on the check side). Those guards are the default; every REQUIRED element
+      // column below says `nullable: false`, because Prisma rejects `{ name: null }` on one.
       model: "AdversarialTag",
       fields: {
-        id: { field: "tagId" },
-        name: { field: "name", nullable: true },
+        id: { field: "tagId", nullable: false },
+        name: { field: "name", valueType: "string", nullable: true  },
       },
     },
   },
@@ -353,7 +512,30 @@ export const MAPPER: Record<string, MapperConfig> = {
       name: "tags",
       type: "many",
       field: "name",
-      fields: { name: { field: "name", nullable: true } },
+      fields: { name: { field: "name", valueType: "string", nullable: true  } },
+    },
+  },
+  // The two homogeneous scalar lists, one owned row per element, projected the way `tagNames`
+  // is. `valueType` sits on the list mapping itself because that is where a membership test reads
+  // it: a literal of another type (`"2" in aNumberList`) is refused rather than bound, since CEL's
+  // heterogeneous equality answers it false and a store that coerces would not. The element column
+  // is nullable because a6 and a4 hold a null element, which is a VALUE in CEL.
+  "request.resource.attr.aNumberList": {
+    valueType: "number",
+    relation: {
+      name: "numberList",
+      type: "many",
+      field: "value",
+      fields: { value: { field: "value", valueType: "number", nullable: true } },
+    },
+  },
+  "request.resource.attr.aBoolList": {
+    valueType: "boolean",
+    relation: {
+      name: "boolList",
+      type: "many",
+      field: "value",
+      fields: { value: { field: "value", valueType: "boolean", nullable: true } },
     },
   },
   "request.resource.attr.categories": {
@@ -361,19 +543,19 @@ export const MAPPER: Record<string, MapperConfig> = {
       name: "categories",
       type: "many",
       fields: {
-        name: { field: "name" },
+        name: { field: "name", valueType: "string", nullable: false },
         subCategories: {
           relation: {
             name: "subCategories",
             type: "many",
             fields: {
-              name: { field: "name" },
+              name: { field: "name", valueType: "string", nullable: false },
               labels: {
                 relation: {
                   name: "labels",
                   type: "many",
                   fields: {
-                    name: { field: "name", nullable: true },
+                    name: { field: "name", valueType: "string", nullable: true  },
                   },
                 },
               },
@@ -383,20 +565,21 @@ export const MAPPER: Record<string, MapperConfig> = {
       },
     },
   },
-  // Multi-hop chain probe (W1): mainCategory mirrors the SAME categories/subCategories relation
-  // as a single-object dotted chain on the check side (every seed holds at most one category),
-  // pinning that the adapter joins through every intermediate hop, never off the root.
+  // The multi-hop chain (the `relation/*/*-to-one-chain` cases): mainCategory mirrors the SAME
+  // categories/subCategories relation as a single-object dotted chain on the check side (every
+  // seed holds at most one category), pinning that the adapter joins through every intermediate
+  // hop, never off the root.
   "request.resource.attr.mainCategory": {
     relation: {
       name: "categories",
       type: "many",
       fields: {
-        name: { field: "name" },
+        name: { field: "name", valueType: "string", nullable: false },
         subCategories: {
           relation: {
             name: "subCategories",
             type: "many",
-            fields: { name: { field: "name" } },
+            fields: { name: { field: "name", valueType: "string", nullable: false } },
           },
         },
         // subNames: the same 2-hop chain but with a bare `field`, so plain `in` membership