@uipath/data-fabric-tool 1.199.0 → 1.201.0-preview.115

package/src/utils/validate.ts

@@ -42,37 +42,222 @@ const UI_BROKEN_SUBSTITUTIONS: Record<string, string> = {
 };
 
 // System-generated columns present on every entity — reusing these names errors.
-const RESERVED_FIELD_NAMES = new Set([
-    "Id",
-    "CreatedBy",
-    "CreateTime",
-    "UpdatedBy",
-    "UpdateTime",
+// Mirrors backend `Constants.AllSystemFields` (StorageManager Common/Constants.cs).
+const RESERVED_FIELD_NAMES_LOWER = new Set([
+    "id",
+    "createdby",
+    "createtime",
+    "updatedby",
+    "updatetime",
+    "recordowner",
+    "version",
 ]);
 
-// The commonly-hit C# / VB reserved words the server rejects with
-// `RESERVED_LANGUAGE_KEYWORDS`. Match is case-insensitive: the server treats
-// `Class`, `class`, and `CLASS` all as the same keyword.
-// Not exhaustive — the authoritative list lives server-side. Any keyword that
-// slips through still hits the server error path, which the CLI surfaces
-// verbatim.
+// C# and VB reserved words the server rejects with `RESERVED_LANGUAGE_KEYWORDS`.
+// The backend calls `CodeDomProvider.IsValidIdentifier` for both C# and VB
+// (EntityValidationHelper.cs), so the CLI union is case-insensitive.
 const RESERVED_KEYWORDS_LOWER = new Set([
+    // C# reserved keywords
+    "abstract",
+    "as",
+    "base",
+    "bool",
+    "break",
+    "byte",
     "case",
+    "catch",
+    "char",
+    "checked",
     "class",
-    "if",
-    "then",
+    "const",
+    "continue",
+    "decimal",
+    "default",
+    "delegate",
+    "do",
+    "double",
     "else",
+    "enum",
+    "event",
+    "explicit",
+    "extern",
+    "false",
+    "finally",
+    "fixed",
+    "float",
+    "for",
+    "foreach",
+    "goto",
+    "if",
+    "implicit",
+    "in",
+    "int",
+    "interface",
+    "internal",
+    "is",
+    "lock",
+    "long",
+    "namespace",
     "new",
+    "null",
     "object",
+    "operator",
+    "out",
+    "override",
+    "params",
+    "private",
+    "protected",
     "public",
+    "readonly",
+    "ref",
     "return",
-    "select",
-    "internal",
-    "private",
+    "sbyte",
+    "sealed",
+    "short",
+    "sizeof",
+    "stackalloc",
     "static",
+    "string",
+    "struct",
+    "switch",
+    "this",
+    "throw",
+    "true",
+    "try",
+    "typeof",
+    "uint",
+    "ulong",
+    "unchecked",
+    "unsafe",
+    "ushort",
+    "using",
+    "virtual",
+    "void",
+    "volatile",
+    "while",
+    // VB reserved keywords (unique to VB — C# overlaps deduped by Set)
+    "addhandler",
+    "addressof",
+    "alias",
+    "and",
+    "andalso",
+    "boolean",
+    "byref",
+    "byval",
+    "call",
+    "cbool",
+    "cbyte",
+    "cchar",
+    "cdate",
+    "cdbl",
+    "cdec",
+    "cint",
+    "clng",
+    "cobj",
+    "csbyte",
+    "cshort",
+    "csng",
+    "cstr",
+    "ctype",
+    "cuint",
+    "culng",
+    "cushort",
+    "date",
+    "declare",
+    "dim",
+    "directcast",
+    "each",
+    "elseif",
+    "end",
+    "endif",
+    "erase",
+    "error",
+    "exit",
+    "friend",
+    "function",
+    "get",
+    "gettype",
+    "getxmlnamespace",
+    "global",
+    "gosub",
+    "goto",
+    "handles",
+    "implements",
+    "imports",
+    "inherits",
+    "integer",
+    "isnot",
+    "let",
+    "lib",
+    "like",
+    "loop",
+    "me",
+    "mod",
+    "module",
+    "mustinherit",
+    "mustoverride",
+    "mybase",
+    "myclass",
+    "narrowing",
+    "next",
+    "not",
+    "nothing",
+    "notinheritable",
+    "notoverridable",
+    "of",
+    "on",
+    "option",
+    "optional",
+    "or",
+    "orelse",
+    "overloads",
+    "overridable",
+    "overrides",
+    "paramarray",
+    "partial",
+    "property",
+    "raiseevent",
+    "redim",
+    "rem",
+    "removehandler",
+    "resume",
+    "select",
+    "set",
+    "shadows",
+    "shared",
+    "single",
+    "step",
+    "stop",
+    "structure",
+    "sub",
+    "synclock",
+    "then",
+    "to",
+    "trycast",
+    "uinteger",
+    "ushort",
+    "variant",
+    "wend",
+    "when",
+    "widening",
+    "with",
+    "withevents",
+    "writeonly",
+    "xor",
 ]);
 
-const NAME_PATTERN = /^[a-zA-Z][a-zA-Z0-9_]{2,99}$/;
+// SQL words confirmed to be rejected by Data Fabric for entity and field
+// names. Similar-looking words such as Status, Key, and Type are accepted, so
+// keep this list limited to names verified against the service.
+const RESERVED_SQL_KEYWORDS_LOWER = new Set(["group", "order"]);
+
+const ENTITY_NAME_PATTERN = /^[a-zA-Z][a-zA-Z0-9_]{2,99}$/;
+const FIELD_NAME_PATTERN = /^[a-zA-Z][a-zA-Z0-9]{2,99}$/;
+
+const MAX_DISPLAY_NAME_LENGTH = 128;
+const MAX_DESCRIPTION_LENGTH = 512;
+const MAX_MULTILINE_MAX_FIELDS = 10;
+const MAX_SAFE_NUMERIC_BOUND = 9_007_199_254_740_991;
 
 export type NameKind = "entity" | "field" | "choice set";
 
@@ -87,10 +272,14 @@ export function validateName(
     // Reserved / keyword checks fire before the format check so short reserved
     // names like `Id`, `If`, `New` get the actionable message instead of the
     // generic "too short" one.
-    if (kind === "field" && RESERVED_FIELD_NAMES.has(name)) {
+    if (
+        kind === "field" &&
+        RESERVED_FIELD_NAMES_LOWER.has(name.toLowerCase())
+    ) {
         return {
             message: `Field name '${name}' is reserved`,
-            instructions: `The following field names are reserved by the platform: ${[...RESERVED_FIELD_NAMES].join(", ")}. Pick a different name.`,
+            instructions:
+                "The following field names are reserved by the platform (case-insensitive): Id, CreatedBy, CreateTime, UpdatedBy, UpdateTime, RecordOwner, Version. Pick a different name.",
         };
     }
 
@@ -102,11 +291,25 @@ export function validateName(
         };
     }
 
-    if (!NAME_PATTERN.test(name)) {
+    if (
+        kind === "entity" &&
+        RESERVED_SQL_KEYWORDS_LOWER.has(name.toLowerCase())
+    ) {
+        return {
+            message: `Entity name '${name}' is a reserved SQL keyword`,
+            instructions:
+                "The platform rejects 'Order' and 'Group' as entity names. Pick a domain-specific name such as 'PurchaseOrder' or 'TeamGroup'.",
+        };
+    }
+
+    const pattern = kind === "field" ? FIELD_NAME_PATTERN : ENTITY_NAME_PATTERN;
+    if (!pattern.test(name)) {
         return {
             message: `Invalid ${kind} name '${name}'`,
             instructions:
-                "Names must start with a letter, contain only letters, digits, and underscores, and be 3-100 characters long.",
+                kind === "field"
+                    ? "Field names must start with a letter, contain only letters and digits (no underscores), and be 3-100 characters long."
+                    : "Names must start with a letter, contain only letters, digits, and underscores, and be 3-100 characters long.",
         };
     }
 
@@ -131,6 +334,128 @@ export function findInvalidFieldName(
     return null;
 }
 
+function validateMetadataLengths(
+    rec: Record<string, unknown>,
+    subject: string,
+): ValidationError | null {
+    if (rec.displayName !== undefined) {
+        if (typeof rec.displayName !== "string") {
+            return {
+                message: `${subject} 'displayName' must be a string`,
+                instructions: `Pass a text value no longer than ${MAX_DISPLAY_NAME_LENGTH} characters.`,
+            };
+        }
+        if (rec.displayName.length > MAX_DISPLAY_NAME_LENGTH) {
+            return {
+                message: `${subject} 'displayName' exceeds ${MAX_DISPLAY_NAME_LENGTH} characters`,
+                instructions: `Shorten 'displayName' to ${MAX_DISPLAY_NAME_LENGTH} characters or fewer.`,
+            };
+        }
+    }
+
+    if (rec.description !== undefined) {
+        if (typeof rec.description !== "string") {
+            return {
+                message: `${subject} 'description' must be a string`,
+                instructions: `Pass a text value no longer than ${MAX_DESCRIPTION_LENGTH} characters.`,
+            };
+        }
+        if (rec.description.length > MAX_DESCRIPTION_LENGTH) {
+            return {
+                message: `${subject} 'description' exceeds ${MAX_DESCRIPTION_LENGTH} characters`,
+                instructions: `Shorten 'description' to ${MAX_DESCRIPTION_LENGTH} characters or fewer.`,
+            };
+        }
+    }
+
+    return null;
+}
+
+/** Validate entity or choice-set metadata against fixed backend limits. */
+export function validateSchemaMetadata(
+    value: Record<string, unknown>,
+    subject: "Entity" | "Choice set",
+): ValidationError | null {
+    return validateMetadataLengths(value, subject);
+}
+
+/** Validate field metadata and case-insensitive batch collisions. */
+export function findInvalidFieldMetadata(
+    fields: unknown[],
+    entityName?: string,
+): ValidationError | null {
+    const names = new Set<string>();
+    const displayNames = new Set<string>();
+
+    for (const f of fields) {
+        if (typeof f !== "object" || f === null) continue;
+        const rec = f as Record<string, unknown>;
+        const fieldName =
+            typeof rec.fieldName === "string" ? rec.fieldName : "<field>";
+        const metadataErr = validateMetadataLengths(
+            rec,
+            `Field '${fieldName}'`,
+        );
+        if (metadataErr) return metadataErr;
+
+        if (typeof rec.fieldName !== "string") continue;
+        const normalizedName = rec.fieldName.toLowerCase();
+        if (names.has(normalizedName)) {
+            return {
+                message: `Duplicate field name '${rec.fieldName}' (case-insensitive)`,
+                instructions:
+                    "Every field in one create/addFields batch must have a unique name, ignoring case.",
+            };
+        }
+        names.add(normalizedName);
+
+        if (
+            entityName !== undefined &&
+            normalizedName === entityName.toLowerCase()
+        ) {
+            return {
+                message: `Field name '${rec.fieldName}' cannot match entity name '${entityName}'`,
+                instructions:
+                    "Entity and field names are compared case-insensitively. Pick a different field name.",
+            };
+        }
+
+        const effectiveDisplayName =
+            typeof rec.displayName === "string" && rec.displayName.length > 0
+                ? rec.displayName
+                : rec.fieldName;
+        const normalizedDisplayName = effectiveDisplayName.toLowerCase();
+        if (displayNames.has(normalizedDisplayName)) {
+            return {
+                message: `Duplicate field display name '${effectiveDisplayName}' (case-insensitive)`,
+                instructions:
+                    "Every field in one create/addFields batch must have a unique display name, ignoring case.",
+            };
+        }
+        displayNames.add(normalizedDisplayName);
+    }
+
+    return null;
+}
+
+/** A new entity cannot contain more than ten MULTILINE_MAX fields. */
+export function findTooManyMultilineMaxFields(
+    fields: unknown[],
+): ValidationError | null {
+    const count = fields.filter(
+        (field) =>
+            typeof field === "object" &&
+            field !== null &&
+            (field as Record<string, unknown>).type === "MULTILINE_MAX",
+    ).length;
+    if (count <= MAX_MULTILINE_MAX_FIELDS) return null;
+
+    return {
+        message: `Entity defines ${count} MULTILINE_MAX fields; the maximum is ${MAX_MULTILINE_MAX_FIELDS}`,
+        instructions: `Keep at most ${MAX_MULTILINE_MAX_FIELDS} MULTILINE_MAX fields on one entity.`,
+    };
+}
+
 /**
  * Scan a list of field definitions for any type value that lives in
  * `UI_BROKEN_FIELD_TYPES`. Returns the first offender's suggested
@@ -157,8 +482,8 @@ export function findUiBrokenFieldType(
     return null;
 }
 
-// `referenceFolderKey` is a per-field folder hint used by RELATIONSHIP / FILE
-// fields to point at a target that lives in a specific folder. CHOICE_SET_*
+// `referenceFolderKey` is a per-field folder hint used by RELATIONSHIP fields
+// to point at a target that lives in a specific folder. CHOICE_SET_*
 // fields resolve their folder server-side from `choiceSetId`, so passing
 // `referenceFolderKey` on a CHOICE_SET_* field is always wrong. Reject it up
 // front instead of letting the server return a misleading cross-scope error.
@@ -185,6 +510,40 @@ export function findReferenceFolderKeyOnChoiceSet(
     return null;
 }
 
+const FILE_REFERENCE_KEYS = [
+    "referenceFolderKey",
+    "referenceEntityId",
+    "referenceFieldId",
+    "choiceSetId",
+] as const;
+
+/**
+ * FILE fields are auto-wired to the platform attachment entity. Supplying
+ * reference metadata conflicts with that server-managed relationship.
+ */
+export function findReferenceFieldsOnFile(
+    fields: unknown[],
+): ValidationError | null {
+    for (const f of fields) {
+        if (typeof f !== "object" || f === null) continue;
+        const rec = f as Record<string, unknown>;
+        if (rec.type !== "FILE") continue;
+
+        const invalidKeys = FILE_REFERENCE_KEYS.filter(
+            (key) => rec[key] !== undefined,
+        );
+        if (invalidKeys.length === 0) continue;
+
+        const fieldName =
+            typeof rec.fieldName === "string" ? rec.fieldName : "<field>";
+        return {
+            message: `FILE field '${fieldName}' must not pass reference fields`,
+            instructions: `FILE fields are auto-wired by the platform. Drop ${invalidKeys.map((key) => `'${key}'`).join(", ")} from the field definition.`,
+        };
+    }
+    return null;
+}
+
 // Complex field types need extra config the SDK enum alone can't teach:
 // CHOICE_SET_* takes a choiceSetId; RELATIONSHIP takes referenceEntityId +
 // referenceFieldId. Missing extras trip a less-informative server error;
@@ -263,9 +622,12 @@ export function findInvalidFieldConstraints(
             typeof rec.fieldName === "string" ? rec.fieldName : "<field>";
 
         if (rec.lengthLimit !== undefined) {
-            if (!isNumber(rec.lengthLimit)) {
+            if (
+                !isNumber(rec.lengthLimit) ||
+                !Number.isInteger(rec.lengthLimit)
+            ) {
                 return {
-                    message: `Field '${fieldName}' 'lengthLimit' must be a number`,
+                    message: `Field '${fieldName}' 'lengthLimit' must be an integer`,
                     instructions:
                         "Pass a positive integer within the type's range (STRING 1-4000, MULTILINE_TEXT 1-10000, MULTILINE_MAX 1-131072 UTF-16 bytes).",
                 };
@@ -309,15 +671,37 @@ export function findInvalidFieldConstraints(
                     instructions: "Pass a numeric value.",
                 };
             }
+            const maxValue = rec.maxValue as number | undefined;
+            if (
+                maxValue !== undefined &&
+                (maxValue > MAX_SAFE_NUMERIC_BOUND ||
+                    maxValue < -MAX_SAFE_NUMERIC_BOUND)
+            ) {
+                return {
+                    message: `Field '${fieldName}' 'maxValue' ${rec.maxValue} is outside the supported numeric range`,
+                    instructions: `Use a value between ${-MAX_SAFE_NUMERIC_BOUND} and ${MAX_SAFE_NUMERIC_BOUND}.`,
+                };
+            }
+            const minValue = rec.minValue as number | undefined;
+            if (
+                minValue !== undefined &&
+                (minValue > MAX_SAFE_NUMERIC_BOUND ||
+                    minValue < -MAX_SAFE_NUMERIC_BOUND)
+            ) {
+                return {
+                    message: `Field '${fieldName}' 'minValue' ${rec.minValue} is outside the supported numeric range`,
+                    instructions: `Use a value between ${-MAX_SAFE_NUMERIC_BOUND} and ${MAX_SAFE_NUMERIC_BOUND}.`,
+                };
+            }
             if (
                 rec.maxValue !== undefined &&
                 rec.minValue !== undefined &&
-                (rec.minValue as number) >= (rec.maxValue as number)
+                (rec.minValue as number) > (rec.maxValue as number)
             ) {
                 return {
-                    message: `Field '${fieldName}' 'minValue' (${rec.minValue}) must be strictly less than 'maxValue' (${rec.maxValue})`,
+                    message: `Field '${fieldName}' 'minValue' (${rec.minValue}) must not exceed 'maxValue' (${rec.maxValue})`,
                     instructions:
-                        "Adjust the bounds so 'minValue < maxValue', or drop one of the two.",
+                        "Adjust the bounds so 'minValue <= maxValue', or drop one of the two.",
                 };
             }
         }
@@ -356,24 +740,93 @@ export function findInvalidFieldConstraints(
 // let the server catch anything else. The known bug where a rejected
 // value-create shifts subsequent NumberIds is documented for the caller —
 // this validator's job is to prevent the failed create in the first place.
+// Choice-value validator: backend calls C#-only `IsValidIdentifier`
+// (StorageManagementService.cs, choice-value path), so we mirror the full C#
+// reserved-keyword set. Match is case-sensitive: C# keywords are all
+// lowercase, so `Class` passes while `class` is rejected.
 const CHOICE_VALUE_KEYWORDS = new Set([
-    "internal",
-    "public",
-    "private",
-    "class",
+    "abstract",
+    "as",
+    "base",
+    "bool",
+    "break",
+    "byte",
     "case",
-    "new",
+    "catch",
+    "char",
+    "checked",
+    "class",
+    "const",
+    "continue",
+    "decimal",
     "default",
-    "static",
-    "void",
+    "delegate",
+    "do",
+    "double",
+    "else",
+    "enum",
     "event",
+    "explicit",
+    "extern",
+    "false",
+    "finally",
+    "fixed",
+    "float",
+    "for",
+    "foreach",
+    "goto",
+    "if",
+    "implicit",
+    "in",
+    "int",
+    "interface",
+    "internal",
+    "is",
     "lock",
+    "long",
+    "namespace",
+    "new",
+    "null",
     "object",
+    "operator",
+    "out",
+    "override",
+    "params",
+    "private",
+    "protected",
+    "public",
+    "readonly",
+    "ref",
+    "return",
+    "sbyte",
+    "sealed",
+    "short",
+    "sizeof",
+    "stackalloc",
+    "static",
     "string",
-    "int",
+    "struct",
+    "switch",
+    "this",
+    "throw",
+    "true",
+    "try",
+    "typeof",
+    "uint",
+    "ulong",
+    "unchecked",
+    "unsafe",
+    "ushort",
+    "using",
+    "virtual",
+    "void",
+    "volatile",
+    "while",
 ]);
 
-const CHOICE_VALUE_NAME_PATTERN = /^[a-zA-Z][a-zA-Z0-9_]{2,99}$/;
+// Server's effective cap is CodeDom's internal ~512-char identifier limit;
+// use 511 to leave one char of headroom.
+const CHOICE_VALUE_NAME_PATTERN = /^[a-zA-Z][a-zA-Z0-9]{0,510}$/;
 
 /**
  * Validate the `Name` argument of `choice-set-values create`. See
@@ -385,7 +838,7 @@ export function validateChoiceValueName(name: string): ValidationError | null {
         return {
             message: `Invalid choice-set value name '${name}'`,
             instructions:
-                "Choice-set value names must start with a letter, contain only letters, digits, and underscores, and be 3-100 characters long.",
+                "Choice-set value names must start with a letter, contain only letters and digits (no underscores), and be at most 511 characters long.",
         };
     }
 
@@ -393,13 +846,33 @@ export function validateChoiceValueName(name: string): ValidationError | null {
         return {
             message: `Choice-set value name '${name}' is a reserved C# keyword`,
             instructions:
-                "The server's choice-set-value validator is case-sensitive and rejects known reserved keywords. Use lowercase snake_case with a suffix so the token no longer matches, and move the label to --display-name. Example: --display-name \"Internal\" with a name of 'internal_audit'.",
+                "The server's choice-set-value validator is case-sensitive and rejects known reserved keywords. Add a letter or digit suffix so the token no longer matches, and move the label to --display-name. Example: --display-name \"Internal\" with a name of 'internalValue'.",
         };
     }
 
     return null;
 }
 
+/** Choice-set value labels are stored in a 500-character backend column. */
+export function validateChoiceValueDisplayName(
+    displayName: unknown,
+): ValidationError | null {
+    if (typeof displayName !== "string") {
+        return {
+            message: "Choice-set value display name must be a string",
+            instructions: "Pass a text value no longer than 500 characters.",
+        };
+    }
+    if (displayName.length > 500) {
+        return {
+            message: "Choice-set value display name exceeds 500 characters",
+            instructions:
+                "Shorten the display name to 500 characters or fewer.",
+        };
+    }
+    return null;
+}
+
 // Operator tokens the server accepts on a `queryFilters[]` leaf. Anything
 // else (`==`, `equals`, `Equals`, `like`, `BETWEEN`, `regex`, …) trips a
 // server 400 with a message that doesn't teach the tokens; catch it here.
@@ -419,6 +892,7 @@ const FILTER_OPERATORS = new Set([
 ]);
 
 const VALUELIST_OPERATORS = new Set(["in", "not in"]);
+const FILTER_FIELD_PATH_PATTERN = /^[a-zA-Z][a-zA-Z0-9_.]*$/;
 
 const FILTER_OPERATORS_LIST = [...FILTER_OPERATORS]
     .map((o) => `'${o}'`)
@@ -444,6 +918,13 @@ function validateFilterLeaf(
                 'Set fieldName to the column you want to filter, for example {"fieldName":"Status","operator":"=","value":"Active"}.',
         };
     }
+    if (!FILTER_FIELD_PATH_PATTERN.test(rec.fieldName)) {
+        return {
+            message: `${path}.fieldName '${rec.fieldName}' is invalid`,
+            instructions:
+                "Filter field names must start with a letter and contain only letters, digits, underscores, and dots.",
+        };
+    }
 
     if (typeof rec.operator !== "string") {
         return {
@@ -467,6 +948,13 @@ function validateFilterLeaf(
                     '\'in\' and \'not in\' take a JSON array of values under \'valueList\', for example {"fieldName":"Status","operator":"in","valueList":["A","B"]}.',
             };
         }
+        if (rec.valueList.length === 0) {
+            return {
+                message: `${path} operator '${rec.operator}' requires a non-empty 'valueList'`,
+                instructions:
+                    "Add at least one value to 'valueList', or remove this filter.",
+            };
+        }
     } else {
         // Every other operator uses 'value'. `null` is legal — it means
         // is-empty (with `=`) or is-not-empty (with `!=`). Missing key is
@@ -479,6 +967,17 @@ function validateFilterLeaf(
                     "Set 'value' to the JSON-string form of the compared value. Use null for is-empty ('=' with null) / is-not-empty ('!=' with null).",
             };
         }
+        if (
+            rec.value === null &&
+            rec.operator !== "=" &&
+            rec.operator !== "!="
+        ) {
+            return {
+                message: `${path} operator '${rec.operator}' cannot use a null value`,
+                instructions:
+                    "A null filter value is supported only with '=' (is empty) or '!=' (is not empty).",
+            };
+        }
     }
 
     return null;
@@ -561,6 +1060,161 @@ export function validateQueryFilter(
     return validateFilterGroup(filterGroup, "filterGroup");
 }
 
+const AGGREGATE_FUNCTIONS = new Set(["COUNT", "SUM", "AVG", "MIN", "MAX"]);
+const AGGREGATE_ALIAS_PATTERN = /^[A-Za-z][A-Za-z0-9_]{0,127}$/;
+const MAX_AGGREGATES = 5;
+const MAX_GROUP_BY_FIELDS = 5;
+
+/** Validate aggregate query shape using the backend's fixed limits. */
+export function validateQueryAggregates(
+    body: Record<string, unknown>,
+): ValidationError | null {
+    if (body.aggregates === undefined) return null;
+    if (!Array.isArray(body.aggregates)) {
+        return {
+            message: "'aggregates' must be an array",
+            instructions:
+                "Pass up to five aggregate objects with function, field, and optional alias.",
+        };
+    }
+    if (body.aggregates.length === 0) return null;
+    if (body.aggregates.length > MAX_AGGREGATES) {
+        return {
+            message: `A query supports at most ${MAX_AGGREGATES} aggregates`,
+            instructions: `Reduce 'aggregates' from ${body.aggregates.length} entries to ${MAX_AGGREGATES} or fewer.`,
+        };
+    }
+
+    if (body.groupBy !== undefined && !Array.isArray(body.groupBy)) {
+        return {
+            message: "'groupBy' must be an array",
+            instructions: "Pass field names as a JSON array.",
+        };
+    }
+    const groupBy = (body.groupBy as unknown[] | undefined) ?? [];
+    if (groupBy.length > MAX_GROUP_BY_FIELDS) {
+        return {
+            message: `A query supports at most ${MAX_GROUP_BY_FIELDS} groupBy fields`,
+            instructions: `Reduce 'groupBy' from ${groupBy.length} entries to ${MAX_GROUP_BY_FIELDS} or fewer.`,
+        };
+    }
+    if (
+        groupBy.some(
+            (field) => typeof field !== "string" || field.trim() === "",
+        )
+    ) {
+        return {
+            message: "'groupBy' field names must be non-empty strings",
+            instructions:
+                "Remove empty entries and pass valid root field names.",
+        };
+    }
+
+    const aliases = new Set<string>();
+    for (let i = 0; i < body.aggregates.length; i++) {
+        const aggregate = body.aggregates[i];
+        if (
+            typeof aggregate !== "object" ||
+            aggregate === null ||
+            Array.isArray(aggregate)
+        ) {
+            return {
+                message: `aggregates[${i}] must be an object`,
+                instructions:
+                    "Each aggregate needs function, field, and optional alias.",
+            };
+        }
+        const rec = aggregate as Record<string, unknown>;
+        if (
+            typeof rec.function !== "string" ||
+            !AGGREGATE_FUNCTIONS.has(rec.function.toUpperCase())
+        ) {
+            return {
+                message: `aggregates[${i}] has invalid function '${String(rec.function)}'`,
+                instructions:
+                    "Supported aggregate functions: COUNT, SUM, AVG, MIN, MAX.",
+            };
+        }
+        if (typeof rec.field !== "string" || rec.field.trim() === "") {
+            return {
+                message: `aggregates[${i}].field must be a non-empty string`,
+                instructions: "Set the field to aggregate.",
+            };
+        }
+
+        const alias =
+            rec.alias === undefined
+                ? `${rec.function.toUpperCase()}_${rec.field}`
+                : rec.alias;
+        if (typeof alias !== "string" || !AGGREGATE_ALIAS_PATTERN.test(alias)) {
+            return {
+                message: `Invalid aggregate alias '${String(alias)}'`,
+                instructions:
+                    "Aliases must start with a letter, contain only letters, digits, and underscores, and be at most 128 characters.",
+            };
+        }
+        const normalizedAlias = alias.toLowerCase();
+        if (aliases.has(normalizedAlias)) {
+            return {
+                message: `Duplicate aggregate alias '${alias}'`,
+                instructions:
+                    "Every aggregate alias must be unique, ignoring case. Set explicit aliases when repeated functions target the same field.",
+            };
+        }
+        aliases.add(normalizedAlias);
+    }
+
+    if (
+        body.selectedFields !== undefined &&
+        !Array.isArray(body.selectedFields)
+    ) {
+        return {
+            message: "'selectedFields' must be an array",
+            instructions: "Pass field names as a JSON array.",
+        };
+    }
+    const selectedFields = (body.selectedFields as unknown[] | undefined) ?? [];
+    if (
+        selectedFields.some(
+            (field) => typeof field !== "string" || field.trim() === "",
+        )
+    ) {
+        return {
+            message: "'selectedFields' must contain non-empty strings",
+            instructions: "Remove null, empty, or non-string entries.",
+        };
+    }
+
+    const hasBinnings =
+        Array.isArray(body.binnings) && body.binnings.length > 0;
+    if (selectedFields.length > 0 && groupBy.length === 0 && !hasBinnings) {
+        return {
+            message:
+                "'groupBy' is required when aggregates and selectedFields are used together",
+            instructions:
+                "Add every non-aggregated selected field to 'groupBy', or remove 'selectedFields'.",
+        };
+    }
+    if (!hasBinnings && selectedFields.length > 0) {
+        const grouped = new Set(
+            (groupBy as string[]).map((field) => field.toLowerCase()),
+        );
+        const missing = (selectedFields as string[]).filter(
+            (field) =>
+                !field.includes(".") && !grouped.has(field.toLowerCase()),
+        );
+        if (missing.length > 0) {
+            return {
+                message: `Selected fields missing from groupBy: ${missing.join(", ")}`,
+                instructions:
+                    "Every non-aggregated selected field must also appear in 'groupBy'.",
+            };
+        }
+    }
+
+    return null;
+}
+
 /**
  * `records insert` / `records update` silently strip any key whose target
  * field is FILE-typed — the server returns Success and the file column is