@dcdr/contracts 1.9.6

package/dist/prompt-variable-schema.contract.d.ts

@@ -0,0 +1,75 @@
+import { PromptVariable } from "./prompts.contract";
+export declare enum PromptVariableSchemaIssueCode {
+    ROOT_OBJECT = "ROOT_OBJECT",
+    KEY_NAME_INVALID = "KEY_NAME_INVALID",
+    DEFINITION_SHAPE = "DEFINITION_SHAPE",
+    TYPE_INVALID = "TYPE_INVALID",
+    ENUM_REQUIRES_FULL = "ENUM_REQUIRES_FULL",
+    REQUIRED_BOOL = "REQUIRED_BOOL",
+    DESCRIPTION_STRING = "DESCRIPTION_STRING",
+    DESCRIPTION_LEN = "DESCRIPTION_LEN",
+    MINMAX_TYPE = "MINMAX_TYPE",
+    MINMAX_NUMBER = "MINMAX_NUMBER",
+    MINMAX_INTEGER = "MINMAX_INTEGER",
+    MINMAX_STRING_INT = "MINMAX_STRING_INT",
+    MINMAX_ARRAY_INT = "MINMAX_ARRAY_INT",
+    MINMAX_ORDER = "MINMAX_ORDER",
+    ENUM_VALUES_REQUIRED = "ENUM_VALUES_REQUIRED",
+    ENUM_VALUES_STRING = "ENUM_VALUES_STRING",
+    ENUM_VALUES_EMPTY = "ENUM_VALUES_EMPTY",
+    ENUM_VALUES_LEN = "ENUM_VALUES_LEN",
+    ENUM_VALUES_UNIQUE = "ENUM_VALUES_UNIQUE",
+    ENUM_FIELDS_DISALLOWED = "ENUM_FIELDS_DISALLOWED",
+    OBJECT_FIELDS_DISALLOWED = "OBJECT_FIELDS_DISALLOWED",
+    OBJECT_PROPERTIES_OBJECT = "OBJECT_PROPERTIES_OBJECT",
+    ARRAY_ITEMS_TYPE_REQUIRED = "ARRAY_ITEMS_TYPE_REQUIRED",
+    ARRAY_ITEMS_TYPE_INVALID = "ARRAY_ITEMS_TYPE_INVALID",
+    ARRAY_ITEMS_TYPE_NO_ARRAY = "ARRAY_ITEMS_TYPE_NO_ARRAY",
+    ARRAY_FIELDS_DISALLOWED = "ARRAY_FIELDS_DISALLOWED",
+    ARRAY_OBJECT_PROPERTIES_REQUIRED = "ARRAY_OBJECT_PROPERTIES_REQUIRED",
+    OBJECT_REQUIRES_FULL = "OBJECT_REQUIRES_FULL"
+}
+export interface PromptVariableSchemaIssue {
+    path: string;
+    code: PromptVariableSchemaIssueCode;
+    params?: Record<string, string | number | boolean>;
+}
+export interface PromptVariableSchemaValidationResult {
+    valid: boolean;
+    issues: PromptVariableSchemaIssue[];
+}
+export interface PromptVariableSchemaCanonicalizeResult {
+    valid: boolean;
+    issues: PromptVariableSchemaIssue[];
+    schema?: Record<string, PromptVariable>;
+}
+export interface PromptVariableSchemaValidationOptions {
+    /** Reject shorthand "array" definitions (require full object with itemsType). */
+    strictShorthandArray?: boolean;
+    /** Reject shorthand "object" definitions (require full object with properties or explicit object definition). */
+    strictShorthandObject?: boolean;
+}
+interface CanonicalizeOptions extends PromptVariableSchemaValidationOptions {
+    maxIssues?: number;
+    /** If true, expands shorthand string defs like { field: "string" } into PromptVariable objects. */
+    expandShorthand?: boolean;
+}
+/**
+ * Validates a PromptVariable schema record.
+ *
+ * Notes
+ * - Accepts both full object definitions and shorthand string definitions.
+ * - Issue codes are stable and UI/backend can map them to messages/i18n.
+ */
+export declare function validatePromptVariableSchemaRecord(value: unknown, maxIssues?: number, options?: PromptVariableSchemaValidationOptions): PromptVariableSchemaValidationResult;
+/**
+ * Canonicalizes a PromptVariable schema record.
+ *
+ * Output
+ * - All `type/itemsType` are normalized to the canonical lowercase values from PromptVariableType.
+ * - Shorthand string definitions may be expanded to full PromptVariable objects.
+ * - Enum values are trimmed.
+ */
+export declare function canonicalizePromptVariableSchemaRecord(value: unknown, options?: CanonicalizeOptions): PromptVariableSchemaCanonicalizeResult;
+export {};
+//# sourceMappingURL=prompt-variable-schema.contract.d.ts.map

package/dist/prompt-variable-schema.contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt-variable-schema.contract.d.ts","sourceRoot":"","sources":["../src/prompt-variable-schema.contract.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAsB,MAAM,oBAAoB,CAAC;AAExE,oBAAY,6BAA6B;IACvC,WAAW,gBAAgB;IAC3B,gBAAgB,qBAAqB;IACrC,gBAAgB,qBAAqB;IACrC,YAAY,iBAAiB;IAC7B,kBAAkB,uBAAuB;IACzC,aAAa,kBAAkB;IAC/B,kBAAkB,uBAAuB;IACzC,eAAe,oBAAoB;IACnC,WAAW,gBAAgB;IAC3B,aAAa,kBAAkB;IAC/B,cAAc,mBAAmB;IACjC,iBAAiB,sBAAsB;IACvC,gBAAgB,qBAAqB;IACrC,YAAY,iBAAiB;IAC7B,oBAAoB,yBAAyB;IAC7C,kBAAkB,uBAAuB;IACzC,iBAAiB,sBAAsB;IACvC,eAAe,oBAAoB;IACnC,kBAAkB,uBAAuB;IACzC,sBAAsB,2BAA2B;IACjD,wBAAwB,6BAA6B;IACrD,wBAAwB,6BAA6B;IACrD,yBAAyB,8BAA8B;IACvD,wBAAwB,6BAA6B;IACrD,yBAAyB,8BAA8B;IACvD,uBAAuB,4BAA4B;IACnD,gCAAgC,qCAAqC;IACrE,oBAAoB,yBAAyB;CAC9C;AAED,MAAM,WAAW,yBAAyB;IACxC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,6BAA6B,CAAC;IACpC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAC;CACpD;AAED,MAAM,WAAW,oCAAoC;IACnD,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,yBAAyB,EAAE,CAAC;CACrC;AAED,MAAM,WAAW,sCAAsC;IACrD,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,yBAAyB,EAAE,CAAC;IACpC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;CACzC;AAED,MAAM,WAAW,qCAAqC;IACpD,iFAAiF;IACjF,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,iHAAiH;IACjH,qBAAqB,CAAC,EAAE,OAAO,CAAC;CACjC;AAED,UAAU,mBAAoB,SAAQ,qCAAqC;IACzE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mGAAmG;IACnG,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAwID;;;;;;GAMG;AACH,wBAAgB,kCAAkC,CAChD,KAAK,EAAE,OAAO,EACd,SAAS,GAAE,MAAW,EACtB,OAAO,CAAC,EAAE,qCAAqC,GAC9C,oCAAoC,CAyXtC;AAED;;;;;;;GAOG;AACH,wBAAgB,sCAAsC,CACpD,KAAK,EAAE,OAAO,EACd,OAAO,CAAC,EAAE,mBAAmB,GAC5B,sCAAsC,CAkIxC"}

package/dist/prompt-variable-schema.contract.js

@@ -0,0 +1,572 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PromptVariableSchemaIssueCode = void 0;
+exports.validatePromptVariableSchemaRecord = validatePromptVariableSchemaRecord;
+exports.canonicalizePromptVariableSchemaRecord = canonicalizePromptVariableSchemaRecord;
+const prompts_contract_1 = require("./prompts.contract");
+var PromptVariableSchemaIssueCode;
+(function (PromptVariableSchemaIssueCode) {
+    PromptVariableSchemaIssueCode["ROOT_OBJECT"] = "ROOT_OBJECT";
+    PromptVariableSchemaIssueCode["KEY_NAME_INVALID"] = "KEY_NAME_INVALID";
+    PromptVariableSchemaIssueCode["DEFINITION_SHAPE"] = "DEFINITION_SHAPE";
+    PromptVariableSchemaIssueCode["TYPE_INVALID"] = "TYPE_INVALID";
+    PromptVariableSchemaIssueCode["ENUM_REQUIRES_FULL"] = "ENUM_REQUIRES_FULL";
+    PromptVariableSchemaIssueCode["REQUIRED_BOOL"] = "REQUIRED_BOOL";
+    PromptVariableSchemaIssueCode["DESCRIPTION_STRING"] = "DESCRIPTION_STRING";
+    PromptVariableSchemaIssueCode["DESCRIPTION_LEN"] = "DESCRIPTION_LEN";
+    PromptVariableSchemaIssueCode["MINMAX_TYPE"] = "MINMAX_TYPE";
+    PromptVariableSchemaIssueCode["MINMAX_NUMBER"] = "MINMAX_NUMBER";
+    PromptVariableSchemaIssueCode["MINMAX_INTEGER"] = "MINMAX_INTEGER";
+    PromptVariableSchemaIssueCode["MINMAX_STRING_INT"] = "MINMAX_STRING_INT";
+    PromptVariableSchemaIssueCode["MINMAX_ARRAY_INT"] = "MINMAX_ARRAY_INT";
+    PromptVariableSchemaIssueCode["MINMAX_ORDER"] = "MINMAX_ORDER";
+    PromptVariableSchemaIssueCode["ENUM_VALUES_REQUIRED"] = "ENUM_VALUES_REQUIRED";
+    PromptVariableSchemaIssueCode["ENUM_VALUES_STRING"] = "ENUM_VALUES_STRING";
+    PromptVariableSchemaIssueCode["ENUM_VALUES_EMPTY"] = "ENUM_VALUES_EMPTY";
+    PromptVariableSchemaIssueCode["ENUM_VALUES_LEN"] = "ENUM_VALUES_LEN";
+    PromptVariableSchemaIssueCode["ENUM_VALUES_UNIQUE"] = "ENUM_VALUES_UNIQUE";
+    PromptVariableSchemaIssueCode["ENUM_FIELDS_DISALLOWED"] = "ENUM_FIELDS_DISALLOWED";
+    PromptVariableSchemaIssueCode["OBJECT_FIELDS_DISALLOWED"] = "OBJECT_FIELDS_DISALLOWED";
+    PromptVariableSchemaIssueCode["OBJECT_PROPERTIES_OBJECT"] = "OBJECT_PROPERTIES_OBJECT";
+    PromptVariableSchemaIssueCode["ARRAY_ITEMS_TYPE_REQUIRED"] = "ARRAY_ITEMS_TYPE_REQUIRED";
+    PromptVariableSchemaIssueCode["ARRAY_ITEMS_TYPE_INVALID"] = "ARRAY_ITEMS_TYPE_INVALID";
+    PromptVariableSchemaIssueCode["ARRAY_ITEMS_TYPE_NO_ARRAY"] = "ARRAY_ITEMS_TYPE_NO_ARRAY";
+    PromptVariableSchemaIssueCode["ARRAY_FIELDS_DISALLOWED"] = "ARRAY_FIELDS_DISALLOWED";
+    PromptVariableSchemaIssueCode["ARRAY_OBJECT_PROPERTIES_REQUIRED"] = "ARRAY_OBJECT_PROPERTIES_REQUIRED";
+    PromptVariableSchemaIssueCode["OBJECT_REQUIRES_FULL"] = "OBJECT_REQUIRES_FULL";
+})(PromptVariableSchemaIssueCode || (exports.PromptVariableSchemaIssueCode = PromptVariableSchemaIssueCode = {}));
+function asPromptVariableDefObject(def) {
+    return def;
+}
+const PROMPT_VARIABLE_TYPES = [
+    prompts_contract_1.PromptVariableType.INTEGER,
+    prompts_contract_1.PromptVariableType.FLOAT,
+    prompts_contract_1.PromptVariableType.STRING,
+    prompts_contract_1.PromptVariableType.BOOLEAN,
+    prompts_contract_1.PromptVariableType.JSON,
+    prompts_contract_1.PromptVariableType.ANY,
+    prompts_contract_1.PromptVariableType.ARRAY,
+    prompts_contract_1.PromptVariableType.OBJECT,
+    prompts_contract_1.PromptVariableType.ENUM,
+];
+const PROMPT_VARIABLE_TYPES_SHORTHAND = [
+    prompts_contract_1.PromptVariableType.INTEGER,
+    prompts_contract_1.PromptVariableType.FLOAT,
+    prompts_contract_1.PromptVariableType.STRING,
+    prompts_contract_1.PromptVariableType.BOOLEAN,
+    prompts_contract_1.PromptVariableType.JSON,
+    prompts_contract_1.PromptVariableType.ANY,
+    prompts_contract_1.PromptVariableType.ARRAY,
+    prompts_contract_1.PromptVariableType.OBJECT,
+];
+function isPlainObject(value) {
+    if (value === null || value === undefined)
+        return false;
+    if (Array.isArray(value))
+        return false;
+    if (typeof value !== "object")
+        return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
+function isObjectRecord(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function isValidVarName(key) {
+    return typeof key === "string" && /^[a-zA-Z0-9_]+$/.test(key);
+}
+function normalizePromptVariableType(raw) {
+    if (typeof raw !== "string")
+        return undefined;
+    const normalized = raw.trim().toLowerCase();
+    for (const t of PROMPT_VARIABLE_TYPES) {
+        if (t === normalized)
+            return t;
+    }
+    // Accept enum key names as a convenience (e.g. "STRING").
+    const upper = raw.trim().toUpperCase();
+    for (const [k, v] of Object.entries(prompts_contract_1.PromptVariableType)) {
+        if (k.toUpperCase() === upper)
+            return v;
+    }
+    return undefined;
+}
+function isFiniteNumber(value) {
+    return typeof value === "number" && Number.isFinite(value);
+}
+function explainEnumValues(values, valuesPath, push) {
+    if (!Array.isArray(values) || values.length === 0) {
+        push({
+            path: valuesPath,
+            code: PromptVariableSchemaIssueCode.ENUM_VALUES_REQUIRED,
+        });
+        return { valid: false };
+    }
+    const normalized = [];
+    for (const v of values) {
+        if (typeof v !== "string") {
+            push({
+                path: valuesPath,
+                code: PromptVariableSchemaIssueCode.ENUM_VALUES_STRING,
+            });
+            return { valid: false };
+        }
+        const s = v.trim();
+        if (!s) {
+            push({
+                path: valuesPath,
+                code: PromptVariableSchemaIssueCode.ENUM_VALUES_EMPTY,
+            });
+            return { valid: false };
+        }
+        if (s.length > 256) {
+            push({
+                path: valuesPath,
+                code: PromptVariableSchemaIssueCode.ENUM_VALUES_LEN,
+            });
+            return { valid: false };
+        }
+        normalized.push(s);
+    }
+    const unique = new Set(normalized);
+    if (unique.size !== normalized.length) {
+        push({
+            path: valuesPath,
+            code: PromptVariableSchemaIssueCode.ENUM_VALUES_UNIQUE,
+        });
+        // Keep going; this is still canonicalizable.
+    }
+    return { valid: true, normalized };
+}
+/**
+ * Validates a PromptVariable schema record.
+ *
+ * Notes
+ * - Accepts both full object definitions and shorthand string definitions.
+ * - Issue codes are stable and UI/backend can map them to messages/i18n.
+ */
+function validatePromptVariableSchemaRecord(value, maxIssues = 25, options) {
+    const issues = [];
+    const push = (issue) => {
+        if (issues.length >= maxIssues)
+            return;
+        issues.push(issue);
+    };
+    const explainDef = (def, path) => {
+        if (issues.length >= maxIssues)
+            return;
+        // Shorthand
+        if (typeof def === "string") {
+            const t = normalizePromptVariableType(def);
+            if (!t) {
+                push({
+                    path,
+                    code: PromptVariableSchemaIssueCode.TYPE_INVALID,
+                    params: { type: String(def) },
+                });
+                return;
+            }
+            if (t === prompts_contract_1.PromptVariableType.ENUM) {
+                push({ path, code: PromptVariableSchemaIssueCode.ENUM_REQUIRES_FULL });
+                return;
+            }
+            if (t === prompts_contract_1.PromptVariableType.ARRAY && options?.strictShorthandArray) {
+                push({
+                    path: `${path}.itemsType`,
+                    code: PromptVariableSchemaIssueCode.ARRAY_ITEMS_TYPE_REQUIRED,
+                });
+                return;
+            }
+            if (t === prompts_contract_1.PromptVariableType.OBJECT && options?.strictShorthandObject) {
+                push({
+                    path,
+                    code: PromptVariableSchemaIssueCode.OBJECT_REQUIRES_FULL,
+                });
+                return;
+            }
+            if (!PROMPT_VARIABLE_TYPES_SHORTHAND.includes(t)) {
+                push({
+                    path,
+                    code: PromptVariableSchemaIssueCode.TYPE_INVALID,
+                    params: { type: String(def) },
+                });
+                return;
+            }
+            return;
+        }
+        if (!isObjectRecord(def)) {
+            push({ path, code: PromptVariableSchemaIssueCode.DEFINITION_SHAPE });
+            return;
+        }
+        const obj = asPromptVariableDefObject(def);
+        const t = normalizePromptVariableType(obj.type);
+        if (!t) {
+            push({
+                path: `${path}.type`,
+                code: PromptVariableSchemaIssueCode.TYPE_INVALID,
+                params: { type: String(obj.type ?? "") },
+            });
+            return;
+        }
+        const requiredRaw = obj.required;
+        if (requiredRaw !== undefined && typeof requiredRaw !== "boolean") {
+            push({
+                path: `${path}.required`,
+                code: PromptVariableSchemaIssueCode.REQUIRED_BOOL,
+            });
+        }
+        const descriptionRaw = obj.description;
+        if (descriptionRaw !== undefined && descriptionRaw !== null) {
+            if (typeof descriptionRaw !== "string") {
+                push({
+                    path: `${path}.description`,
+                    code: PromptVariableSchemaIssueCode.DESCRIPTION_STRING,
+                });
+            }
+            else if (descriptionRaw.length > 1024) {
+                push({
+                    path: `${path}.description`,
+                    code: PromptVariableSchemaIssueCode.DESCRIPTION_LEN,
+                });
+            }
+        }
+        const hasMin = obj.min !== undefined && obj.min !== null;
+        const hasMax = obj.max !== undefined && obj.max !== null;
+        if (hasMin || hasMax) {
+            const allowMinMax = t === prompts_contract_1.PromptVariableType.INTEGER ||
+                t === prompts_contract_1.PromptVariableType.FLOAT ||
+                t === prompts_contract_1.PromptVariableType.STRING ||
+                t === prompts_contract_1.PromptVariableType.ARRAY;
+            if (!allowMinMax) {
+                push({ path, code: PromptVariableSchemaIssueCode.MINMAX_TYPE });
+            }
+            if (hasMin && !isFiniteNumber(obj.min)) {
+                push({
+                    path: `${path}.min`,
+                    code: PromptVariableSchemaIssueCode.MINMAX_NUMBER,
+                });
+            }
+            if (hasMax && !isFiniteNumber(obj.max)) {
+                push({
+                    path: `${path}.max`,
+                    code: PromptVariableSchemaIssueCode.MINMAX_NUMBER,
+                });
+            }
+            if (t === prompts_contract_1.PromptVariableType.INTEGER) {
+                if (hasMin && isFiniteNumber(obj.min) && !Number.isInteger(obj.min)) {
+                    push({
+                        path: `${path}.min`,
+                        code: PromptVariableSchemaIssueCode.MINMAX_INTEGER,
+                    });
+                }
+                if (hasMax && isFiniteNumber(obj.max) && !Number.isInteger(obj.max)) {
+                    push({
+                        path: `${path}.max`,
+                        code: PromptVariableSchemaIssueCode.MINMAX_INTEGER,
+                    });
+                }
+            }
+            if (t === prompts_contract_1.PromptVariableType.STRING) {
+                if (hasMin && (!Number.isInteger(obj.min) || obj.min < 0)) {
+                    push({
+                        path: `${path}.min`,
+                        code: PromptVariableSchemaIssueCode.MINMAX_STRING_INT,
+                    });
+                }
+                if (hasMax && (!Number.isInteger(obj.max) || obj.max < 0)) {
+                    push({
+                        path: `${path}.max`,
+                        code: PromptVariableSchemaIssueCode.MINMAX_STRING_INT,
+                    });
+                }
+            }
+            if (t === prompts_contract_1.PromptVariableType.ARRAY) {
+                if (hasMin && (!Number.isInteger(obj.min) || obj.min < 0)) {
+                    push({
+                        path: `${path}.min`,
+                        code: PromptVariableSchemaIssueCode.MINMAX_ARRAY_INT,
+                    });
+                }
+                if (hasMax && (!Number.isInteger(obj.max) || obj.max < 0)) {
+                    push({
+                        path: `${path}.max`,
+                        code: PromptVariableSchemaIssueCode.MINMAX_ARRAY_INT,
+                    });
+                }
+            }
+            if (hasMin &&
+                hasMax &&
+                isFiniteNumber(obj.min) &&
+                isFiniteNumber(obj.max) &&
+                obj.max < obj.min) {
+                push({ path, code: PromptVariableSchemaIssueCode.MINMAX_ORDER });
+            }
+        }
+        // ENUM
+        if (t === prompts_contract_1.PromptVariableType.ENUM) {
+            explainEnumValues(obj.values, `${path}.values`, push);
+            if (obj.itemsType !== undefined && obj.itemsType !== null) {
+                push({
+                    path: `${path}.itemsType`,
+                    code: PromptVariableSchemaIssueCode.ENUM_FIELDS_DISALLOWED,
+                });
+            }
+            if (obj.properties !== undefined && obj.properties !== null) {
+                push({
+                    path: `${path}.properties`,
+                    code: PromptVariableSchemaIssueCode.ENUM_FIELDS_DISALLOWED,
+                });
+            }
+            if (hasMin || hasMax) {
+                push({
+                    path,
+                    code: PromptVariableSchemaIssueCode.ENUM_FIELDS_DISALLOWED,
+                });
+            }
+            return;
+        }
+        // OBJECT
+        if (t === prompts_contract_1.PromptVariableType.OBJECT) {
+            if (obj.itemsType !== undefined && obj.itemsType !== null) {
+                push({
+                    path: `${path}.itemsType`,
+                    code: PromptVariableSchemaIssueCode.OBJECT_FIELDS_DISALLOWED,
+                });
+            }
+            if (obj.values !== undefined && obj.values !== null) {
+                push({
+                    path: `${path}.values`,
+                    code: PromptVariableSchemaIssueCode.OBJECT_FIELDS_DISALLOWED,
+                });
+            }
+            const propsRaw = obj.properties;
+            if (propsRaw !== undefined && propsRaw !== null) {
+                if (!isPlainObject(propsRaw)) {
+                    push({
+                        path: `${path}.properties`,
+                        code: PromptVariableSchemaIssueCode.OBJECT_PROPERTIES_OBJECT,
+                    });
+                }
+                else {
+                    for (const [propName, propDef] of Object.entries(propsRaw)) {
+                        if (!isValidVarName(propName)) {
+                            push({
+                                path: `${path}.properties.${String(propName)}`,
+                                code: PromptVariableSchemaIssueCode.KEY_NAME_INVALID,
+                                params: { name: String(propName) },
+                            });
+                            if (issues.length >= maxIssues)
+                                return;
+                            continue;
+                        }
+                        explainDef(propDef, `${path}.properties.${propName}`);
+                        if (issues.length >= maxIssues)
+                            return;
+                    }
+                }
+            }
+            if (hasMin || hasMax) {
+                push({
+                    path,
+                    code: PromptVariableSchemaIssueCode.OBJECT_FIELDS_DISALLOWED,
+                });
+            }
+            return;
+        }
+        // ARRAY
+        if (t === prompts_contract_1.PromptVariableType.ARRAY) {
+            const itemsTypeRaw = obj.itemsType;
+            const itemsType = normalizePromptVariableType(itemsTypeRaw);
+            if (!itemsType) {
+                push({
+                    path: `${path}.itemsType`,
+                    code: PromptVariableSchemaIssueCode.ARRAY_ITEMS_TYPE_REQUIRED,
+                });
+                return;
+            }
+            if (itemsType === prompts_contract_1.PromptVariableType.ARRAY) {
+                push({
+                    path: `${path}.itemsType`,
+                    code: PromptVariableSchemaIssueCode.ARRAY_ITEMS_TYPE_NO_ARRAY,
+                });
+                return;
+            }
+            // min/max on arrays are interpreted as minItems/maxItems and are allowed.
+            if (itemsType === prompts_contract_1.PromptVariableType.OBJECT) {
+                const propsRaw = obj.properties;
+                if (propsRaw === undefined || propsRaw === null) {
+                    push({
+                        path: `${path}.properties`,
+                        code: PromptVariableSchemaIssueCode.ARRAY_OBJECT_PROPERTIES_REQUIRED,
+                    });
+                    return;
+                }
+                if (!isPlainObject(propsRaw)) {
+                    push({
+                        path: `${path}.properties`,
+                        code: PromptVariableSchemaIssueCode.OBJECT_PROPERTIES_OBJECT,
+                    });
+                    return;
+                }
+                for (const [propName, propDef] of Object.entries(propsRaw)) {
+                    if (!isValidVarName(propName)) {
+                        push({
+                            path: `${path}.properties.${String(propName)}`,
+                            code: PromptVariableSchemaIssueCode.KEY_NAME_INVALID,
+                            params: { name: String(propName) },
+                        });
+                        if (issues.length >= maxIssues)
+                            return;
+                        continue;
+                    }
+                    explainDef(propDef, `${path}.properties.${propName}`);
+                    if (issues.length >= maxIssues)
+                        return;
+                }
+                if (obj.values !== undefined && obj.values !== null) {
+                    push({
+                        path: `${path}.values`,
+                        code: PromptVariableSchemaIssueCode.ARRAY_FIELDS_DISALLOWED,
+                    });
+                }
+            }
+            else {
+                if (obj.properties !== undefined && obj.properties !== null) {
+                    push({
+                        path: `${path}.properties`,
+                        code: PromptVariableSchemaIssueCode.ARRAY_FIELDS_DISALLOWED,
+                    });
+                }
+            }
+            if (itemsType === prompts_contract_1.PromptVariableType.ENUM) {
+                explainEnumValues(obj.values, `${path}.values`, push);
+            }
+            else {
+                if (obj.values !== undefined && obj.values !== null) {
+                    push({
+                        path: `${path}.values`,
+                        code: PromptVariableSchemaIssueCode.ARRAY_FIELDS_DISALLOWED,
+                    });
+                }
+            }
+            return;
+        }
+        // For other types, we allow itemsType only if it is a valid type and not array (compat with UI).
+        const maybeItemsType = obj.itemsType;
+        if (maybeItemsType !== undefined && maybeItemsType !== null) {
+            const it = normalizePromptVariableType(maybeItemsType);
+            if (!it) {
+                push({
+                    path: `${path}.itemsType`,
+                    code: PromptVariableSchemaIssueCode.ARRAY_ITEMS_TYPE_INVALID,
+                });
+            }
+            if (it === prompts_contract_1.PromptVariableType.ARRAY) {
+                push({
+                    path: `${path}.itemsType`,
+                    code: PromptVariableSchemaIssueCode.ARRAY_ITEMS_TYPE_NO_ARRAY,
+                });
+            }
+        }
+    };
+    // Root allowed to be null/undefined.
+    if (value === null || value === undefined) {
+        return { valid: true, issues: [] };
+    }
+    if (!isPlainObject(value)) {
+        push({ path: "", code: PromptVariableSchemaIssueCode.ROOT_OBJECT });
+        return { valid: false, issues };
+    }
+    for (const [key, def] of Object.entries(value)) {
+        if (!isValidVarName(key)) {
+            push({
+                path: String(key),
+                code: PromptVariableSchemaIssueCode.KEY_NAME_INVALID,
+                params: { name: String(key) },
+            });
+            if (issues.length >= maxIssues)
+                break;
+            continue;
+        }
+        explainDef(def, key);
+        if (issues.length >= maxIssues)
+            break;
+    }
+    return { valid: issues.length === 0, issues };
+}
+/**
+ * Canonicalizes a PromptVariable schema record.
+ *
+ * Output
+ * - All `type/itemsType` are normalized to the canonical lowercase values from PromptVariableType.
+ * - Shorthand string definitions may be expanded to full PromptVariable objects.
+ * - Enum values are trimmed.
+ */
+function canonicalizePromptVariableSchemaRecord(value, options) {
+    const maxIssues = options?.maxIssues ?? 25;
+    const expandShorthand = options?.expandShorthand !== false;
+    const validation = validatePromptVariableSchemaRecord(value, maxIssues, options);
+    if (!validation.valid)
+        return { valid: false, issues: validation.issues };
+    if (value === null || value === undefined) {
+        return { valid: true, issues: [], schema: undefined };
+    }
+    const schema = {};
+    const toPromptVariable = (def) => {
+        if (typeof def === "string") {
+            const t = normalizePromptVariableType(def);
+            // Canonical form is always full PromptVariable objects.
+            return expandShorthand
+                ? new prompts_contract_1.PromptVariable(t, false)
+                : new prompts_contract_1.PromptVariable(t, false);
+        }
+        if (!isObjectRecord(def)) {
+            // Should never happen after validation, but keep canonicalization total.
+            return new prompts_contract_1.PromptVariable(prompts_contract_1.PromptVariableType.ANY, false);
+        }
+        const obj = asPromptVariableDefObject(def);
+        const type = normalizePromptVariableType(obj.type);
+        const required = obj.required === true;
+        const description = typeof obj.description === "string" ? obj.description : undefined;
+        const min = isFiniteNumber(obj.min) ? obj.min : undefined;
+        const max = isFiniteNumber(obj.max) ? obj.max : undefined;
+        if (type === prompts_contract_1.PromptVariableType.ENUM) {
+            const enumNorm = explainEnumValues(obj.values, "values", () => {
+                /* already validated */
+            });
+            const values = enumNorm.normalized;
+            return new prompts_contract_1.PromptVariable(type, required, description, undefined, undefined, values, min, max);
+        }
+        if (type === prompts_contract_1.PromptVariableType.OBJECT) {
+            const propsRaw = obj.properties;
+            const props = isPlainObject(propsRaw)
+                ? Object.fromEntries(Object.entries(propsRaw).map(([k, v]) => [k, toPromptVariable(v)]))
+                : undefined;
+            return new prompts_contract_1.PromptVariable(type, required, description, undefined, props, undefined, min, max);
+        }
+        if (type === prompts_contract_1.PromptVariableType.ARRAY) {
+            const itemsType = normalizePromptVariableType(obj.itemsType);
+            const propsRaw = obj.properties;
+            const props = itemsType === prompts_contract_1.PromptVariableType.OBJECT && isPlainObject(propsRaw)
+                ? Object.fromEntries(Object.entries(propsRaw).map(([k, v]) => [
+                    k,
+                    toPromptVariable(v),
+                ]))
+                : undefined;
+            const values = itemsType === prompts_contract_1.PromptVariableType.ENUM && Array.isArray(obj.values)
+                ? obj.values
+                    .filter((v) => typeof v === "string")
+                    .map((v) => String(v).trim())
+                    .filter((v) => v.length > 0)
+                : undefined;
+            return new prompts_contract_1.PromptVariable(type, required, description, itemsType, props, values, min, max);
+        }
+        // For scalar/json/any
+        const itemsType = normalizePromptVariableType(obj.itemsType);
+        return new prompts_contract_1.PromptVariable(type, required, description, itemsType, undefined, undefined, min, max);
+    };
+    for (const [key, def] of Object.entries(value)) {
+        schema[key] = toPromptVariable(def);
+    }
+    return { valid: true, issues: [], schema };
+}