prisma-guard 1.20.0 → 1.21.0

package/dist/runtime/index.cjs

@@ -57,11 +57,92 @@ var CallerError = class extends Error {
     this.name = "CallerError";
   }
 };
+function formatIssue(issue) {
+  const path = issue.path.length > 0 ? `${issue.path.join(".")}: ` : "";
+  const code = issue.code;
+  if (code === "invalid_union") {
+    const unionErrors = issue.unionErrors;
+    if (unionErrors && unionErrors.length > 0) {
+      const branches = unionErrors.map((ue, i) => {
+        const nested = ue.issues.map(formatIssue).join(", ");
+        return `branch ${i + 1}: [${nested}]`;
+      }).join(" | ");
+      return `${path}No matching variant (${branches})`;
+    }
+    return `${path}No matching variant`;
+  }
+  if (issue.code === "unrecognized_keys") {
+    const keys = issue.keys;
+    if (keys && keys.length > 0) {
+      return `${path}Unrecognized key(s): ${keys.join(", ")}`;
+    }
+  }
+  if (issue.code === "invalid_type") {
+    const expected = issue.expected;
+    const received = issue.received;
+    if (expected && received) {
+      return `${path}Expected ${expected}, received ${received}`;
+    }
+  }
+  if (code === "invalid_enum_value") {
+    const options = issue.options;
+    if (options) {
+      return `${path}Invalid value. Expected one of: ${options.join(", ")}`;
+    }
+  }
+  if (code === "too_small") {
+    const minimum = issue.minimum;
+    const type = issue.type;
+    if (type === "string" && minimum !== void 0) {
+      return `${path}String must contain at least ${minimum} character(s)`;
+    }
+    if (type === "array" && minimum !== void 0) {
+      return `${path}Array must contain at least ${minimum} element(s)`;
+    }
+    if (type === "number" && minimum !== void 0) {
+      return `${path}Number must be >= ${minimum}`;
+    }
+    return `${path}${issue.message}`;
+  }
+  if (code === "too_big") {
+    const maximum = issue.maximum;
+    const type = issue.type;
+    if (type === "string" && maximum !== void 0) {
+      return `${path}String must contain at most ${maximum} character(s)`;
+    }
+    if (type === "array" && maximum !== void 0) {
+      return `${path}Array must contain at most ${maximum} element(s)`;
+    }
+    if (type === "number" && maximum !== void 0) {
+      return `${path}Number must be <= ${maximum}`;
+    }
+    return `${path}${issue.message}`;
+  }
+  if (code === "invalid_format") {
+    const format = issue.format;
+    if (format) {
+      return `${path}Invalid ${format} format`;
+    }
+  }
+  if (code === "invalid_value") {
+    const values = issue.values;
+    if (values) {
+      return `${path}Invalid value. Expected one of: ${values.join(", ")}`;
+    }
+  }
+  return `${path}${issue.message}`;
+}
 function formatZodError(err) {
-  return err.issues.map((i) => {
-    const p = i.path.length > 0 ? `${i.path.join(".")}: ` : "";
-    return `${p}${i.message}`;
-  }).join("; ");
+  return err.issues.map(formatIssue).join("; ");
+}
+function wrapParseError(err, context) {
+  if (err instanceof ShapeError) {
+    throw new ShapeError(`${context}: ${err.message}`, { cause: err });
+  }
+  if (err && typeof err === "object" && "issues" in err) {
+    throw new ShapeError(`${context}: ${formatZodError(err)}`, { cause: err });
+  }
+  throw err;
 }
 
 // src/shared/scalar-base.ts
@@ -207,15 +288,19 @@ function coerceToArray(value) {
     return value;
   const keys = Object.keys(value);
   if (keys.length === 0)
-    return [];
+    return value;
   const allNumeric = keys.every((k) => /^\d+$/.test(k));
   if (!allNumeric)
     return value;
-  const sorted = keys.map(Number).sort((a, b) => a - b);
+  const indices = keys.map(Number).sort((a, b) => a - b);
+  for (let i = 0; i < indices.length; i++) {
+    if (indices[i] !== i)
+      return value;
+  }
   const obj = value;
-  const result = [];
-  for (const idx of sorted) {
-    result.push(obj[String(idx)]);
+  const result = new Array(indices.length);
+  for (let i = 0; i < indices.length; i++) {
+    result[i] = obj[String(i)];
   }
   return result;
 }
@@ -233,7 +318,8 @@ var SCALAR_OPERATORS = {
     "gt",
     "gte",
     "lt",
-    "lte"
+    "lte",
+    "search"
   ]),
   Int: /* @__PURE__ */ new Set(["equals", "not", "gt", "gte", "lt", "lte", "in", "notIn"]),
   Float: /* @__PURE__ */ new Set(["equals", "not", "gt", "gte", "lt", "lte", "in", "notIn"]),
@@ -335,7 +421,7 @@ function createScalarListOperatorSchema(fieldMeta, operator, enumMap, scalarBase
 }
 function createJsonOperatorSchema(fieldMeta, operator) {
   const jsonValue = import_zod2.z.unknown();
-  if (operator === "equals" || operator === "not") {
+  if (operator === "equals") {
     return !fieldMeta.isRequired ? import_zod2.z.union([jsonValue, import_zod2.z.null()]) : jsonValue;
   }
   if (operator === "path") {
@@ -351,6 +437,29 @@ function createJsonOperatorSchema(fieldMeta, operator) {
     `Operator "${operator}" not supported for Json fields`
   );
 }
+function buildNotFilterSchema(fieldMeta, scalarSchema, enumMap, scalarBase) {
+  const allOps = getSupportedOperators(fieldMeta);
+  const nestedOps = allOps.filter((o) => o !== "not");
+  if (nestedOps.length === 0)
+    return scalarSchema;
+  const nestedSchemas = {};
+  for (const op of nestedOps) {
+    nestedSchemas[op] = createOperatorSchema(
+      fieldMeta,
+      op,
+      enumMap,
+      scalarBase
+    ).optional();
+  }
+  const nestedKeys = Object.keys(nestedSchemas);
+  const nestedObj = import_zod2.z.object(nestedSchemas).strict().refine(
+    (v) => nestedKeys.some(
+      (k) => v[k] !== void 0
+    ),
+    { message: "not filter must specify at least one operator" }
+  );
+  return import_zod2.z.union([scalarSchema, nestedObj]);
+}
 function createOperatorSchema(fieldMeta, operator, enumMap, scalarBase) {
   if (fieldMeta.isList) {
     return createScalarListOperatorSchema(
@@ -371,9 +480,13 @@ function createOperatorSchema(fieldMeta, operator, enumMap, scalarBase) {
       );
     }
     const enumSchema = import_zod2.z.enum(values);
-    if (operator === "equals" || operator === "not") {
+    if (operator === "equals") {
       return !fieldMeta.isRequired ? import_zod2.z.union([enumSchema, import_zod2.z.null()]) : enumSchema;
     }
+    if (operator === "not") {
+      const scalarSchema = !fieldMeta.isRequired ? import_zod2.z.union([enumSchema, import_zod2.z.null()]) : enumSchema;
+      return buildNotFilterSchema(fieldMeta, scalarSchema, enumMap, scalarBase);
+    }
     const itemSchema = !fieldMeta.isRequired ? import_zod2.z.union([enumSchema, import_zod2.z.null()]) : enumSchema;
     return import_zod2.z.preprocess(coerceToArray, import_zod2.z.array(itemSchema));
   }
@@ -384,6 +497,11 @@ function createOperatorSchema(fieldMeta, operator, enumMap, scalarBase) {
         `Operator "${operator}" not supported for type "Json"`
       );
     }
+    if (operator === "not") {
+      const jsonValue = import_zod2.z.unknown();
+      const scalarSchema = !fieldMeta.isRequired ? import_zod2.z.union([jsonValue, import_zod2.z.null()]) : jsonValue;
+      return buildNotFilterSchema(fieldMeta, scalarSchema, enumMap, scalarBase);
+    }
     return createJsonOperatorSchema(fieldMeta, operator);
   }
   const supportedOps = SCALAR_OPERATORS[fieldMeta.type];
@@ -406,9 +524,13 @@ function createOperatorSchema(fieldMeta, operator, enumMap, scalarBase) {
   }
   const scalar = factory();
   const coerced = wrapWithInputCoercion(fieldMeta.type, false, scalar);
-  if (operator === "equals" || operator === "not") {
+  if (operator === "equals") {
     return !fieldMeta.isRequired ? import_zod2.z.union([coerced, import_zod2.z.null()]) : coerced;
   }
+  if (operator === "not") {
+    const scalarSchema = !fieldMeta.isRequired ? import_zod2.z.union([coerced, import_zod2.z.null()]) : coerced;
+    return buildNotFilterSchema(fieldMeta, scalarSchema, enumMap, scalarBase);
+  }
   if (operator === "in" || operator === "notIn") {
     const itemSchema = !fieldMeta.isRequired ? import_zod2.z.union([coerced, import_zod2.z.null()]) : coerced;
     return import_zod2.z.preprocess(coerceToArray, import_zod2.z.array(itemSchema));
@@ -817,6 +939,8 @@ function deepClone(value) {
         return new Date(value.getTime());
       if (value instanceof Uint8Array)
         return value.slice();
+      if (value instanceof RegExp)
+        return new RegExp(value.source, value.flags);
       if (Array.isArray(value))
         return value.map(deepClone);
       const proto = Object.getPrototypeOf(value);
@@ -834,7 +958,10 @@ function deepClone(value) {
 }
 
 // src/runtime/query-builder-forced.ts
-var EMPTY_WHERE_FORCED = { conditions: {}, relations: {} };
+var EMPTY_WHERE_FORCED = {
+  conditions: {},
+  relations: {}
+};
 function hasWhereForced(f) {
   return Object.keys(f.conditions).length > 0 || Object.keys(f.relations).length > 0;
 }
@@ -894,7 +1021,7 @@ function mergeUniqueWhereForced(where, forced) {
   }
   return result;
 }
-function applyBuiltShape(built, body, isUniqueMethod) {
+function applyBuiltShape(built, body, isUniqueMethod, modelName) {
   let parseable = body;
   const hasWhereInSchema = "where" in built.zodSchema.shape;
   if (isPlainObject(body)) {
@@ -920,7 +1047,20 @@ function applyBuiltShape(built, body, isUniqueMethod) {
       }
     }
   }
-  const validated = built.zodSchema.parse(parseable);
+  let validated;
+  try {
+    validated = built.zodSchema.parse(parseable);
+  } catch (err) {
+    if (err instanceof ShapeError)
+      throw err;
+    if (err && typeof err === "object" && "issues" in err) {
+      const context = modelName ? `Invalid query on model "${modelName}"` : "Invalid query";
+      throw new ShapeError(`${context}: ${formatZodError(err)}`, {
+        cause: err
+      });
+    }
+    throw err;
+  }
   if (hasWhereForced(built.forcedWhere)) {
     validated.where = isUniqueMethod ? mergeUniqueWhereForced(
       validated.where,
@@ -1295,7 +1435,8 @@ function createWhereBuilder(typeMap, enumMap, scalarBase) {
           model,
           fieldSchemas,
           relationForced,
-          currentDepth
+          currentDepth,
+          scalarConditions
         );
         continue;
       }
@@ -1377,7 +1518,7 @@ function createWhereBuilder(typeMap, enumMap, scalarBase) {
       }
     }
   }
-  function processRelationFilter(key, value, fieldMeta, model, fieldSchemas, parentRelations, depth) {
+  function processRelationFilter(key, value, fieldMeta, model, fieldSchemas, parentRelations, depth, parentConditions) {
     if (!isPlainObject(value)) {
       throw new ShapeError(
         `Relation filter for "${key}" must be an object with operators (some, every, none, is, isNot)`
@@ -1392,6 +1533,7 @@ function createWhereBuilder(typeMap, enumMap, scalarBase) {
     const opSchemas = {};
     const opForced = {};
     let hasClientOps = false;
+    let hasForcedNull = false;
     for (const [op, opValue] of Object.entries(value)) {
       if (!allowedOps.has(op)) {
         const allowed = [...allowedOps].join(", ");
@@ -1399,9 +1541,24 @@ function createWhereBuilder(typeMap, enumMap, scalarBase) {
           `Operator "${op}" not supported for ${fieldMeta.isList ? "to-many" : "to-one"} relation "${key}". Allowed: ${allowed}`
         );
       }
+      if (opValue === null) {
+        if (!TO_ONE_RELATION_OPS.has(op)) {
+          throw new ShapeError(
+            `Null value for operator "${op}" is only valid on to-one relation operators (is, isNot), not on "${key}"`
+          );
+        }
+        const existing = parentConditions[key];
+        if (existing && isPlainObject(existing)) {
+          existing[op] = null;
+        } else {
+          parentConditions[key] = { [op]: null };
+        }
+        hasForcedNull = true;
+        continue;
+      }
       if (!isPlainObject(opValue)) {
         throw new ShapeError(
-          `Relation filter operator "${op}" on "${key}" must be an object defining nested where fields`
+          `Relation filter operator "${op}" on "${key}" must be an object defining nested where fields, or null for to-one existence checks`
         );
       }
       const nested = buildWhereSchema(fieldMeta.type, opValue, depth + 1);
@@ -1427,7 +1584,7 @@ function createWhereBuilder(typeMap, enumMap, scalarBase) {
         opForced[op] = nested.forced;
       }
     }
-    if (!hasClientOps && Object.keys(opForced).length === 0) {
+    if (!hasClientOps && Object.keys(opForced).length === 0 && !hasForcedNull) {
       throw new ShapeError(
         `Relation filter for "${key}" on model "${model}" produced no conditions. Define at least one nested field in the operator shape.`
       );
@@ -1435,7 +1592,7 @@ function createWhereBuilder(typeMap, enumMap, scalarBase) {
     if (hasClientOps) {
       const clientOpKeys = Object.keys(opSchemas);
       const opObjSchema = import_zod4.z.object(opSchemas).strict();
-      if (Object.keys(opForced).length === 0) {
+      if (Object.keys(opForced).length === 0 && !hasForcedNull) {
         fieldSchemas[key] = opObjSchema.refine(
           (v) => clientOpKeys.some(
             (k) => v[k] !== void 0
@@ -1737,25 +1894,26 @@ function createArgsBuilder(typeMap, enumMap, uniqueMap, scalarBase) {
     return import_zod5.z.union([singleSchema, import_zod5.z.preprocess(coerceToArray, import_zod5.z.array(singleSchema).min(1))]).optional();
   }
   function buildTakeSchema(config) {
-    if (!Number.isFinite(config.max) || !Number.isInteger(config.max)) {
-      throw new ShapeError(`take max must be a finite integer, got ${config.max}`);
+    const normalized = typeof config === "number" ? { max: config, default: config } : config;
+    if (!Number.isFinite(normalized.max) || !Number.isInteger(normalized.max)) {
+      throw new ShapeError(`take max must be a finite integer, got ${normalized.max}`);
     }
-    if (config.max < 1) {
-      throw new ShapeError(`take max must be at least 1, got ${config.max}`);
+    if (normalized.max < 1) {
+      throw new ShapeError(`take max must be at least 1, got ${normalized.max}`);
     }
-    if (config.default !== void 0) {
-      if (!Number.isFinite(config.default) || !Number.isInteger(config.default)) {
-        throw new ShapeError(`take default must be a finite integer, got ${config.default}`);
+    if (normalized.default !== void 0) {
+      if (!Number.isFinite(normalized.default) || !Number.isInteger(normalized.default)) {
+        throw new ShapeError(`take default must be a finite integer, got ${normalized.default}`);
       }
-      if (config.default < 1) {
-        throw new ShapeError(`take default must be at least 1, got ${config.default}`);
+      if (normalized.default < 1) {
+        throw new ShapeError(`take default must be at least 1, got ${normalized.default}`);
       }
-      if (config.default > config.max) {
+      if (normalized.default > normalized.max) {
         throw new ShapeError("take default cannot exceed max");
       }
-      return import_zod5.z.number().int().min(1).max(config.max).default(config.default);
+      return import_zod5.z.number().int().min(1).max(normalized.max).default(normalized.default);
     }
-    return import_zod5.z.number().int().min(1).max(config.max).optional();
+    return import_zod5.z.number().int().min(1).max(normalized.max).optional();
   }
   function buildCursorSchema(model, cursorConfig) {
     const modelFields = typeMap[model];
@@ -1862,10 +2020,21 @@ function createArgsBuilder(typeMap, enumMap, uniqueMap, scalarBase) {
       ).optional();
     }
     const havingFieldKeys = Object.keys(fieldSchemas);
-    return import_zod5.z.object(fieldSchemas).strict().refine(
-      (v) => havingFieldKeys.some((k) => v[k] !== void 0),
-      { message: "having must specify at least one field" }
-    ).optional();
+    const havingSchema = import_zod5.z.lazy(() => {
+      const allSchemas = { ...fieldSchemas };
+      allSchemas["AND"] = import_zod5.z.preprocess(coerceToArray, import_zod5.z.array(havingSchema).min(1)).optional();
+      allSchemas["OR"] = import_zod5.z.preprocess(coerceToArray, import_zod5.z.array(havingSchema).min(1)).optional();
+      allSchemas["NOT"] = import_zod5.z.union([
+        havingSchema,
+        import_zod5.z.preprocess(coerceToArray, import_zod5.z.array(havingSchema).min(1))
+      ]).optional();
+      const allKeys = [...havingFieldKeys, "AND", "OR", "NOT"];
+      return import_zod5.z.object(allSchemas).strict().refine(
+        (v) => allKeys.some((k) => v[k] !== void 0),
+        { message: "having must specify at least one field or combinator" }
+      );
+    });
+    return havingSchema.optional();
   }
   function buildAggregateFieldSchema(model, opName, fieldConfig) {
     const modelFields = typeMap[model];
@@ -2637,6 +2806,17 @@ function createQueryBuilder(typeMap, enumMap, uniqueMap, scalarBase) {
       return null;
     return { key: matched, shape: shapes[matched] };
   }
+  function resolveDefaultShape(config, model, method, normalizedBody, opts, builtCache, isUnique) {
+    const shapeOrFn = config["default"];
+    let built;
+    if (typeof shapeOrFn === "function") {
+      const resolved = resolveAndValidateShape(shapeOrFn, opts?.ctx);
+      built = buildShapeZodSchema(model, method, resolved);
+    } else {
+      built = builtCache.get("default");
+    }
+    return applyBuiltShape(built, normalizedBody, isUnique);
+  }
   function buildQuerySchema(model, method, config) {
     const isSingle = typeof config === "function" || isShapeConfig(config);
     const builtCache = /* @__PURE__ */ new Map();
@@ -2688,23 +2868,39 @@ function createQueryBuilder(typeMap, enumMap, uniqueMap, scalarBase) {
               "Pass caller via opts.caller, not in the request body."
             );
           }
+          const namedConfig = config;
           const caller = opts?.caller;
           if (typeof caller !== "string") {
-            const allowed = Object.keys(
-              config
-            );
+            if ("default" in namedConfig) {
+              return resolveDefaultShape(
+                namedConfig,
+                model,
+                method,
+                normalizedBody,
+                opts,
+                builtCache,
+                isUnique
+              );
+            }
+            const allowed = Object.keys(namedConfig);
             throw new CallerError(
               `Missing caller. This query uses named shape routing with keys: ${allowed.map((k) => `"${k}"`).join(", ")}. Provide caller via opts.caller.`
             );
           }
-          const matched = matchCaller(
-            config,
-            caller
-          );
+          const matched = matchCaller(namedConfig, caller);
           if (!matched) {
-            const allowed = Object.keys(
-              config
-            );
+            if ("default" in namedConfig) {
+              return resolveDefaultShape(
+                namedConfig,
+                model,
+                method,
+                normalizedBody,
+                opts,
+                builtCache,
+                isUnique
+              );
+            }
+            const allowed = Object.keys(namedConfig);
             throw new CallerError(
               `Unknown caller: "${caller}". Allowed: ${allowed.map((k) => `"${k}"`).join(", ")}`
             );
@@ -2737,23 +2933,10 @@ var READ_OPS = /* @__PURE__ */ new Set([
   "findFirstOrThrow",
   "count"
 ]);
-var AGGREGATE_OPS = /* @__PURE__ */ new Set([
-  "aggregate",
-  "groupBy"
-]);
-var FIND_UNIQUE_OPS = /* @__PURE__ */ new Set([
-  "findUnique",
-  "findUniqueOrThrow"
-]);
-var CREATE_OPS = /* @__PURE__ */ new Set([
-  "create",
-  "createMany",
-  "createManyAndReturn"
-]);
-var UNIQUE_MUTATION_OPS = /* @__PURE__ */ new Set([
-  "update",
-  "delete"
-]);
+var AGGREGATE_OPS = /* @__PURE__ */ new Set(["aggregate", "groupBy"]);
+var FIND_UNIQUE_OPS = /* @__PURE__ */ new Set(["findUnique", "findUniqueOrThrow"]);
+var CREATE_OPS = /* @__PURE__ */ new Set(["create", "createMany", "createManyAndReturn"]);
+var UNIQUE_MUTATION_OPS = /* @__PURE__ */ new Set(["update", "delete"]);
 var MULTI_MUTATION_OPS = /* @__PURE__ */ new Set([
   "updateMany",
   "updateManyAndReturn",
@@ -2882,7 +3065,9 @@ function createScopeExtension(scopeMap, contextFn, guardConfig, logger) {
         for (const s of presentScopes) {
           validateScopeValue(s.root, ctx[s.root]);
         }
-        const presentConditions = presentScopes.map((s) => ({ [s.fk]: ctx[s.root] }));
+        const presentConditions = presentScopes.map((s) => ({
+          [s.fk]: ctx[s.root]
+        }));
         const missingRoots = scopes.filter((s) => ctx[s.root] == null).map((s) => s.root);
         const isMutation = CREATE_OPS.has(operation) || UNIQUE_MUTATION_OPS.has(operation) || MULTI_MUTATION_OPS.has(operation) || operation === "upsert";
         if (missingRoots.length > 0) {
@@ -2912,14 +3097,32 @@ function createScopeExtension(scopeMap, contextFn, guardConfig, logger) {
               throw new ShapeError(`upsert expects create to be an object`);
             }
             nextArgs.create = { ...args.create };
-            enforceDataScope(nextArgs.create, scopes, overrides, log, model, operation, onScopeRelationWrite, "create");
+            enforceDataScope(
+              nextArgs.create,
+              scopes,
+              overrides,
+              log,
+              model,
+              operation,
+              onScopeRelationWrite,
+              "create"
+            );
           }
           if (args.update !== void 0 && args.update !== null) {
             if (typeof args.update !== "object" || Array.isArray(args.update)) {
               throw new ShapeError(`upsert expects update to be an object`);
             }
             nextArgs.update = { ...args.update };
-            enforceDataScope(nextArgs.update, scopes, overrides, log, model, operation, onScopeRelationWrite, "mutate");
+            enforceDataScope(
+              nextArgs.update,
+              scopes,
+              overrides,
+              log,
+              model,
+              operation,
+              onScopeRelationWrite,
+              "mutate"
+            );
           }
           return query(nextArgs);
         }
@@ -2929,7 +3132,15 @@ function createScopeExtension(scopeMap, contextFn, guardConfig, logger) {
               `Scoped model "${model}" does not allow ${operation} via scope extension (findUniqueMode is "reject"). Use findFirst with explicit where conditions instead.`
             );
           }
-          return handleFindUnique(args, query, conditions, scopes, operation, log);
+          return handleFindUnique(
+            args,
+            query,
+            conditions,
+            scopes,
+            operation,
+            log,
+            model
+          );
         }
         if (READ_OPS.has(operation)) {
           nextArgs.where = buildAndConditions(args.where, conditions);
@@ -2957,7 +3168,16 @@ function createScopeExtension(scopeMap, contextFn, guardConfig, logger) {
             }
             nextArgs.data = args.data.map((d) => {
               const item = { ...d };
-              enforceDataScope(item, scopes, overrides, log, model, operation, onScopeRelationWrite, "create");
+              enforceDataScope(
+                item,
+                scopes,
+                overrides,
+                log,
+                model,
+                operation,
+                onScopeRelationWrite,
+                "create"
+              );
               return item;
             });
           } else {
@@ -2965,7 +3185,16 @@ function createScopeExtension(scopeMap, contextFn, guardConfig, logger) {
               throw new ShapeError(`${operation} expects data to be an object`);
             }
             nextArgs.data = { ...args.data };
-            enforceDataScope(nextArgs.data, scopes, overrides, log, model, operation, onScopeRelationWrite, "create");
+            enforceDataScope(
+              nextArgs.data,
+              scopes,
+              overrides,
+              log,
+              model,
+              operation,
+              onScopeRelationWrite,
+              "create"
+            );
           }
           return query(nextArgs);
         }
@@ -2976,7 +3205,16 @@ function createScopeExtension(scopeMap, contextFn, guardConfig, logger) {
               throw new ShapeError(`${operation} expects data to be an object`);
             }
             nextArgs.data = { ...args.data };
-            enforceDataScope(nextArgs.data, scopes, overrides, log, model, operation, onScopeRelationWrite, "mutate");
+            enforceDataScope(
+              nextArgs.data,
+              scopes,
+              overrides,
+              log,
+              model,
+              operation,
+              onScopeRelationWrite,
+              "mutate"
+            );
           }
           return query(nextArgs);
         }
@@ -2987,7 +3225,16 @@ function createScopeExtension(scopeMap, contextFn, guardConfig, logger) {
               throw new ShapeError(`${operation} expects data to be an object`);
             }
             nextArgs.data = { ...args.data };
-            enforceDataScope(nextArgs.data, scopes, overrides, log, model, operation, onScopeRelationWrite, "mutate");
+            enforceDataScope(
+              nextArgs.data,
+              scopes,
+              overrides,
+              log,
+              model,
+              operation,
+              onScopeRelationWrite,
+              "mutate"
+            );
           }
           return query(nextArgs);
         }
@@ -2998,7 +3245,7 @@ function createScopeExtension(scopeMap, contextFn, guardConfig, logger) {
     }
   };
 }
-async function handleFindUnique(args, query, conditions, scopes, operation, log) {
+async function handleFindUnique(args, query, conditions, scopes, operation, log, model) {
   const nextArgs = { ...args };
   const injectedFks = [];
   const originalSelect = args?.select;
@@ -3016,7 +3263,9 @@ async function handleFindUnique(args, query, conditions, scopes, operation, log)
   if (result === null)
     return result;
   if (typeof result !== "object" || result === null) {
-    throw new ShapeError("findUnique result must be an object or null");
+    throw new ShapeError(
+      `${operation} on model "${model}" returned a non-object, non-null result`
+    );
   }
   const resultObj = result;
   let verifyObj = resultObj;
@@ -3025,22 +3274,29 @@ async function handleFindUnique(args, query, conditions, scopes, operation, log)
     const where = args?.where;
     if (!where || typeof where !== "object" || Array.isArray(where)) {
       throw new PolicyError(
-        `prisma-guard: Cannot verify scope \u2014 missing FK fields (${missingFks.join(", ")}) and findUnique args.where is not a valid object.`
+        `prisma-guard: Cannot verify scope on model "${model}" for ${operation} \u2014 missing FK fields (${missingFks.join(", ")}) in result and args.where is not a valid object. Ensure the where clause is a plain object so the verification query can re-fetch FK values.`
       );
     }
     let verifyResult;
     try {
       verifyResult = await query({ where, select: buildFkSelect(fks) });
     } catch (err) {
+      log.warn(
+        `prisma-guard: Scope verification re-query failed for ${operation} on model "${model}": ${err?.message ?? String(err)}`
+      );
       throw new PolicyError(
-        `prisma-guard: Scope verification query failed for findUnique: ${err?.message ?? String(err)}`
+        `prisma-guard: Scope verification re-query failed for ${operation} on model "${model}". The re-query to fetch FK fields (${fks.join(", ")}) returned a database error. Check server logs for the underlying cause.`
       );
     }
     if (verifyResult === null) {
-      throw new PolicyError("prisma-guard: Scope verification query returned null for an existing findUnique result");
+      throw new PolicyError(
+        `prisma-guard: Scope verification re-query on model "${model}" returned null for an existing ${operation} result. The record may have been deleted between the original query and verification.`
+      );
     }
     if (typeof verifyResult !== "object" || verifyResult === null) {
-      throw new PolicyError("prisma-guard: Scope verification result must be an object");
+      throw new PolicyError(
+        `prisma-guard: Scope verification re-query on model "${model}" returned a non-object result.`
+      );
     }
     verifyObj = verifyResult;
   }
@@ -3048,12 +3304,14 @@ async function handleFindUnique(args, query, conditions, scopes, operation, log)
     const [fk, value] = Object.entries(condition)[0];
     if (!(fk in verifyObj)) {
       throw new PolicyError(
-        `prisma-guard: Cannot verify scope on "${fk}" \u2014 field not present in verification result. Ensure FK fields are selectable.`
+        `prisma-guard: Cannot verify scope on model "${model}" \u2014 FK field "${fk}" not present in verification result. Ensure "${fk}" is selectable on model "${model}" (not excluded by select or field-level access).`
       );
     }
     if (!looseEqual(verifyObj[fk], value, log, fk)) {
       if (operation === "findUniqueOrThrow") {
-        throw new PolicyError("Record not accessible in current scope");
+        throw new PolicyError(
+          `Record on model "${model}" not accessible in current scope`
+        );
       }
       return null;
     }
@@ -3758,11 +4016,22 @@ function buildDataSchema(model, dataConfig, mode, typeMap, schemaBuilder, zodDef
     forced
   };
 }
-function validateAndMergeData(bodyData, cached, method) {
+function validateAndMergeData(bodyData, cached, method, modelName) {
   if (bodyData === void 0 || bodyData === null) {
     throw new ShapeError(`${method} requires "data" in request body`);
   }
-  const validated = cached.schema.parse(bodyData);
+  let validated;
+  try {
+    validated = cached.schema.parse(bodyData);
+  } catch (err) {
+    if (err instanceof ShapeError)
+      throw err;
+    if (err && typeof err === "object" && "issues" in err) {
+      const context = modelName ? `Invalid data for ${method} on model "${modelName}"` : `Invalid data for ${method}`;
+      throw new ShapeError(`${context}: ${formatZodError(err)}`, { cause: err });
+    }
+    throw err;
+  }
   return { ...validated, ...deepClone(cached.forced) };
 }
 function hasDataRefines(dataConfig) {
@@ -3832,14 +4101,26 @@ function resolveShape(input, body, contextFn, caller) {
     );
   }
   if (typeof caller !== "string") {
+    if ("default" in namedMap) {
+      const shapeOrFn2 = namedMap["default"];
+      const wasDynamic2 = typeof shapeOrFn2 === "function";
+      const shape2 = wasDynamic2 ? resolveDynamicShape(shapeOrFn2, contextFn) : shapeOrFn2;
+      return { shape: shape2, body: parsed, matchedKey: "default", wasDynamic: wasDynamic2 };
+    }
     const patterns2 = Object.keys(namedMap);
     throw new CallerError(
-      `Missing caller. This guard uses named shape routing with keys: ${patterns2.map((k) => `"${k}"`).join(", ")}. Provide caller as second argument to .guard() or set "caller" in the context function.`
+      `Missing caller. This guard uses named shape routing with keys: ${patterns2.map((k) => `"${k}"`).join(", ")}. Provide caller as second argument to .guard() or set "caller" in the context function, or add a "default" variant.`
     );
   }
   const patterns = Object.keys(namedMap);
   const matched = matchCallerPattern(patterns, caller);
   if (!matched) {
+    if ("default" in namedMap) {
+      const shapeOrFn2 = namedMap["default"];
+      const wasDynamic2 = typeof shapeOrFn2 === "function";
+      const shape2 = wasDynamic2 ? resolveDynamicShape(shapeOrFn2, contextFn) : shapeOrFn2;
+      return { shape: shape2, body: parsed, matchedKey: "default", wasDynamic: wasDynamic2 };
+    }
     throw new CallerError(
       `Unknown caller: "${caller}". Allowed: ${patterns.map((k) => `"${k}"`).join(", ")}`
     );
@@ -4205,7 +4486,10 @@ function createModelGuardExtension(config) {
         const cached = uniqueWhereCache.get(cacheKey);
         if (cached)
           return cached;
-        const built = queryBuilder.buildUniqueWhereSchema(modelName, whereConfig);
+        const built = queryBuilder.buildUniqueWhereSchema(
+          modelName,
+          whereConfig
+        );
         uniqueWhereCache.set(cacheKey, built);
         return built;
       }
@@ -4290,7 +4574,15 @@ function createModelGuardExtension(config) {
       } else {
         projectionBody = buildDefaultProjectionBody(shape);
       }
-      const validated = projection.zodSchema.parse(projectionBody);
+      let validated;
+      try {
+        validated = projection.zodSchema.parse(projectionBody);
+      } catch (err) {
+        wrapParseError(
+          err,
+          `Invalid select/include projection on model "${modelName}" for ${method}`
+        );
+      }
       if (Object.keys(projection.forcedIncludeTree).length > 0) {
         applyForcedTree(validated, "include", projection.forcedIncludeTree);
       }
@@ -4327,7 +4619,11 @@ function createModelGuardExtension(config) {
           }
           sanitizedWhere = w;
         }
-        validatedWhere = built.schema.parse(sanitizedWhere);
+        try {
+          validatedWhere = built.schema.parse(sanitizedWhere);
+        } catch (err) {
+          wrapParseError(err, `Invalid "where" clause on model "${modelName}"`);
+        }
       } else if (bodyWhere !== void 0) {
         if (bodyWhere === null || !isPlainObject(bodyWhere) || Object.keys(bodyWhere).length > 0) {
           let hasOnlyForcedKeys = false;
@@ -4357,7 +4653,10 @@ function createModelGuardExtension(config) {
         wasDynamic
       );
       if (Object.keys(where).length === 0) {
-        throw new ShapeError(`${method} requires a where condition`);
+        const expectedFields = shape.where ? Object.keys(shape.where).join(", ") : "none defined";
+        throw new ShapeError(
+          `${method} on model "${modelName}" requires a where condition. Expected fields: ${expectedFields}`
+        );
       }
       return where;
     }
@@ -4369,20 +4668,30 @@ function createModelGuardExtension(config) {
       if (built.schema) {
         if (bodyWhere !== void 0 && bodyWhere !== null) {
           if (!isPlainObject(bodyWhere)) {
-            throw new ShapeError("Unique where must be an object");
+            throw new ShapeError(
+              `Invalid "where" on model "${modelName}": unique where must be a plain object`
+            );
           }
           const sanitized = { ...bodyWhere };
           for (const key of built.forcedOnlyKeys) {
             delete sanitized[key];
           }
-          result = built.schema.parse(sanitized);
+          try {
+            result = built.schema.parse(sanitized);
+          } catch (err) {
+            const allowedFields = Object.keys(shape.where).join(", ");
+            wrapParseError(
+              err,
+              `Invalid unique "where" on model "${modelName}". Allowed fields: ${allowedFields}`
+            );
+          }
         }
       } else if (bodyWhere !== void 0 && bodyWhere !== null) {
         if (isPlainObject(bodyWhere)) {
           const hasOnlyForcedKeys = built.forcedOnlyKeys.size > 0 && Object.keys(bodyWhere).every((k) => built.forcedOnlyKeys.has(k));
           if (!hasOnlyForcedKeys && Object.keys(bodyWhere).length > 0) {
             throw new ShapeError(
-              "Unique where shape contains only forced values. Client where input is not accepted."
+              `Unique where on model "${modelName}" contains only forced values. Client where input is not accepted.`
             );
           }
         }
@@ -4400,7 +4709,12 @@ function createModelGuardExtension(config) {
         wasDynamic
       );
       if (Object.keys(where).length === 0) {
-        throw new ShapeError(`${method} requires a where condition`);
+        const constraints = uniqueMap[modelName];
+        const constraintDesc = constraints ? constraints.map((c) => `(${c.join(", ")})`).join(" | ") : "unknown";
+        const expectedFields = shape.where ? Object.keys(shape.where).join(", ") : "none defined";
+        throw new ShapeError(
+          `${method} on model "${modelName}" requires a unique where condition. Unique constraints: ${constraintDesc}. Shape allows: ${expectedFields}`
+        );
       }
       return where;
     }
@@ -4443,7 +4757,7 @@ function createModelGuardExtension(config) {
         );
         const isUnique = UNIQUE_READ_METHODS.has(method);
         const effectiveBody = buildEffectiveReadBody(resolved);
-        const args = applyBuiltShape(built, effectiveBody, isUnique);
+        const args = applyBuiltShape(built, effectiveBody, isUnique, modelName);
         if (isUnique && args.where) {
           validateResolvedUniqueWhere(
             modelName,
@@ -4499,7 +4813,8 @@ function createModelGuardExtension(config) {
           const data = validateAndMergeData(
             resolved.body.data,
             dataSchema,
-            method
+            method,
+            modelName
           );
           args = { data };
         } else {
@@ -4508,7 +4823,7 @@ function createModelGuardExtension(config) {
           if (resolved.body.data.length === 0)
             throw new ShapeError(`${method} received empty data array`);
           const data = resolved.body.data.map(
-            (item) => validateAndMergeData(item, dataSchema, method)
+            (item) => validateAndMergeData(item, dataSchema, method, modelName)
           );
           args = { data };
         }
@@ -4562,7 +4877,8 @@ function createModelGuardExtension(config) {
         const data = validateAndMergeData(
           resolved.body.data,
           dataSchema,
-          method
+          method,
+          modelName
         );
         let where;
         if (isUniqueWhere) {
@@ -4728,7 +5044,8 @@ function createModelGuardExtension(config) {
         const createData = validateAndMergeData(
           resolved.body.create,
           createDataSchema,
-          "upsert (create)"
+          "upsert (create)",
+          modelName
         );
         const updateDataSchema = getDataSchema(
           "update",
@@ -4739,7 +5056,8 @@ function createModelGuardExtension(config) {
         const updateData = validateAndMergeData(
           resolved.body.update,
           updateDataSchema,
-          "upsert (update)"
+          "upsert (update)",
+          modelName
         );
         const where = requireUniqueWhere(
           resolved.shape,