@uipath/maestro-builder-sdk 6.34.0 → 6.35.0

package/dist/core/form-field-type.js

@@ -1,3 +1,5 @@
+import { jsonClone } from './json-clone.js';
+import { isRecord } from './node-envelope.js';
 import { nearestName } from './edit-distance.js';
 import { ownEntry } from './own-entry.js';
 /**
@@ -228,60 +230,129 @@ export function formFieldJsonSchema(type) {
 /**
  * A picker field's choices as the form row carries them (`options`, each
  * `{ id, value, label }` — the product's `optionShape`), copied so the wire
- * never aliases the author's array. `undefined` when the field has none.
- * Both serializers (human task, quick-form escalation) write through this.
+ * never aliases the author's array.
  */
-export function formFieldOptionsWire(options) {
-    return options === undefined ? undefined : options.map((o) => ({ id: o.id, value: o.value, label: o.label }));
+function formFieldOptionsWire(options) {
+    return options.map((o) => ({ id: o.id, value: o.value, label: o.label }));
 }
-/** Whether a value is one well-formed choice: string `id`, `value` and `label`, all three the product requires. */
-function isFormFieldOption(o) {
-    if (o === null || typeof o !== 'object')
-        return false;
-    const r = o;
-    return typeof r.id === 'string' && typeof r.value === 'string' && typeof r.label === 'string';
+// ─── The whole field row (#1250) ─────────────────────────────────────────────
+/**
+ * Every key of a quick-form field row, in the platform's own order
+ * (`@uipath/hitl-schema-types` 1.2.0 `fieldSchemaFor`). The contract test
+ * compares this list with the real package, so a key added upstream fails
+ * there until the SDK decides how to carry it.
+ */
+export const FORM_FIELD_ROW_KEYS = [
+    'id', 'type', 'label', 'direction', 'required', 'variable', 'binding', 'value',
+    'rules', 'requiredMessage', 'colSpan', 'controlType', 'options', 'defaultValue', 'description',
+];
+/** The platform's controls (`controlType`), in its own order. */
+export const FORM_FIELD_CONTROL_TYPES = [
+    'text', 'textarea', 'numberInput', 'datePicker', 'dateAndTimePicker', 'checkbox',
+    'dropdown', 'radioGroup', 'multiSelect', 'checkboxGroup', 'fileUpload',
+];
+const isString = (v) => typeof v === 'string';
+/*
+ * The shapes below check only the keys the platform defines. Its `optionShape`,
+ * `fieldRuleSchema` and `fieldConditionSchema` are plain `z.object`s, which
+ * STRIP an unknown key rather than refuse it, so an extra key is not a reason
+ * for `check` to fail. Decompile drops one (`stripSetting`) and reports it
+ * (`formFieldRowLoss`), because the SDK's source types have no place for it.
+ */
+const OPTION_KEYS = ['id', 'value', 'label'];
+const RULE_KEYS = ['id', 'conditions', 'operator', 'effects'];
+const CONDITION_KEYS = ['when', 'is', 'isNot', 'in', 'notIn', 'matches', 'custom'];
+function isOptions(v) {
+    return Array.isArray(v) && v.every((o) => isRecord(o) && isString(o.id) && isString(o.value) && isString(o.label));
+}
+/** `fieldConditionSchema`: `when` plus optional `is`/`isNot`/`in`/`notIn`/`matches`/`custom`. */
+function isCondition(v) {
+    return isRecord(v)
+        && isString(v.when)
+        && (v.in === undefined || Array.isArray(v.in)) && (v.notIn === undefined || Array.isArray(v.notIn))
+        && (v.matches === undefined || isString(v.matches)) && (v.custom === undefined || isString(v.custom));
 }
+/** `fieldRuleSchema`: `{ id, conditions, operator?, effects }`. */
+function isRules(v) {
+    return Array.isArray(v) && v.every((r) => isRecord(r)
+        && isString(r.id) && Array.isArray(r.conditions) && r.conditions.every(isCondition)
+        && (r.operator === undefined || r.operator === 'AND' || r.operator === 'OR') && isRecord(r.effects));
+}
+/**
+ * The settings keys (`FormFieldSettings`), in the platform's row order, each
+ * with the shape the platform's schema accepts. `Record<keyof …>` makes tsc
+ * refuse a settings key without an entry here.
+ */
+const SETTINGS = {
+    rules: isRules,
+    requiredMessage: isString,
+    colSpan: (v) => Number.isInteger(v) && v >= 1 && v <= 12,
+    controlType: (v) => FORM_FIELD_CONTROL_TYPES.includes(v),
+    options: isOptions,
+    defaultValue: (v) => isString(v) || (Array.isArray(v) && v.every(isString)),
+    description: isString,
+};
+/** Whether `value` has the platform's shape for the settings key `key`; false for any other key. */
+const validSetting = (key, value) => ownEntry(SETTINGS, key)?.(value) === true;
+/** What each settings key must be, for `check`'s message. */
+const SETTINGS_SHAPE = {
+    rules: "a list of { id, conditions: [{ when, … }], operator?: 'AND' | 'OR', effects: { … } }",
+    requiredMessage: 'a string',
+    colSpan: 'an integer from 1 to 12 (the form\'s 12-column grid)',
+    controlType: `one of ${FORM_FIELD_CONTROL_TYPES.join(', ')}`,
+    options: 'a list of { id, value, label }, all strings',
+    defaultValue: 'a string, or a list of strings for a multi-select',
+    description: 'a string',
+};
 /**
- * A form row's `options` read back for source: the well-formed choices
- * (string `id`, `value`, `label` — all three the product requires), or
- * `undefined` when the row has no `options` array. A malformed entry is left
- * out, not coerced: `{ id: 'o1', value: 1 }` is not rewritten to
- * `value: '1', label: ''`. Decompile (human task and quick-form escalation)
- * reads through this, so a canvas dropdown's choices survive an edit.
+ * Each settings key a field sets to a value the platform's schema refuses, as
+ * `key: value (what it must be)`. Empty when every setting is valid. `check`
+ * reports these: a form with one fails the platform's validation.
  *
  * @example
- * liftFormFieldOptions([{ id: 'o1', value: 'a', label: 'A' }, { id: 'o2', value: 2 }])
- * // [{ id: 'o1', value: 'a', label: 'A' }]
+ * formFieldSettingProblems({ colSpan: 13 }) // ['colSpan: 13 (must be an integer from 1 to 12 …)']
  */
-export function liftFormFieldOptions(raw) {
-    if (!Array.isArray(raw))
-        return undefined;
-    return raw.filter(isFormFieldOption).map((o) => ({ id: o.id, value: o.value, label: o.label }));
+export function formFieldSettingProblems(f) {
+    if (!isRecord(f))
+        return [];
+    return FORM_FIELD_SETTINGS_KEYS
+        .filter((key) => f[key] !== undefined && !validSetting(key, f[key]))
+        .map((key) => `${key}: ${JSON.stringify(f[key])} (must be ${ownEntry(SETTINGS_SHAPE, key)})`);
 }
+/** The `FormFieldSettings` keys, in the platform's row order. */
+export const FORM_FIELD_SETTINGS_KEYS = Object.keys(SETTINGS);
+/** The `controlType`s that render a field's `options` as choices. */
+const PICKER_CONTROL_TYPES = ['dropdown', 'radioGroup', 'multiSelect', 'checkboxGroup'];
 /**
- * What is wrong with a form field's `options`, or `undefined` when nothing is.
- * `check` reports each (human task and quick-form escalation):
+ * What is wrong with a form field's choices, or `undefined` when nothing is.
+ * `check` reports each (human task and quick-form escalation). A field is a
+ * picker when its type is a choice-control spelling (`singleSelect`,
+ * `multiSelect`, `enum`) or its `controlType` is a picker control (`dropdown`,
+ * `radioGroup`, `multiSelect`, `checkboxGroup`).
+ *
+ * - `'missing'`: a picker with no choices. The form publishes an empty picker.
+ * - `'ignored'`: choices on a field that is not a picker. The form renders a
+ *   plain input and never shows them.
  *
- * - `'malformed'`: `options` is there but is not an array of `{ id, value,
- *   label }` strings. Serialize would throw or write rows the platform refuses.
- * - `'missing'`: a choice-control type (`singleSelect`, `multiSelect`, `enum`)
- *   with no choices. The form publishes an empty picker.
- * - `'ignored'`: choices on a type that is not a choice control. The form
- *   renders a plain input and never shows them.
+ * `options` that do not have the platform's shape are reported by
+ * `formFieldSettingProblems` instead, so they get no second diagnostic here.
  *
  * @example
- * formFieldOptionsProblem('singleSelect', undefined)                         // 'missing'
- * formFieldOptionsProblem('singleSelect', {})                                // 'malformed'
- * formFieldOptionsProblem('string', [{ id: 'o1', value: 'a', label: 'A' }]) // 'ignored'
- * formFieldOptionsProblem('enum', [{ id: 'o1', value: 'a', label: 'A' }])   // undefined
+ * formFieldOptionsProblem({ type: 'singleSelect' })                                         // 'missing'
+ * formFieldOptionsProblem({ type: 'string', options: [{ id: 'o1', value: 'a', label: 'A' }] }) // 'ignored'
+ * formFieldOptionsProblem({ type: 'string', controlType: 'dropdown', options: [{ id: 'o1', value: 'a', label: 'A' }] }) // undefined
  */
-export function formFieldOptionsProblem(type, options) {
-    if (options !== undefined && (!Array.isArray(options) || !options.every(isFormFieldOption)))
-        return 'malformed';
-    const isControl = controlFormFieldType(type) !== undefined;
-    if (isControl && (options === undefined || options.length === 0))
+export function formFieldOptionsProblem(f) {
+    if (!isRecord(f))
+        return undefined;
+    if (f.options !== undefined && !validSetting('options', f.options))
+        return undefined;
+    const picker = controlFormFieldType(f.type) !== undefined
+        || (typeof f.controlType === 'string' && PICKER_CONTROL_TYPES.includes(f.controlType));
+    const count = Array.isArray(f.options) ? f.options.length : 0;
+    if (picker && count === 0)
         return 'missing';
-    if (!isControl && options !== undefined && options.length > 0)
+    if (!picker && count > 0)
         return 'ignored';
     return undefined;
 }
@@ -291,14 +362,12 @@ export function formFieldOptionsProblem(type, options) {
  */
 export function formFieldOptionsWhy(problem, type) {
     switch (problem) {
-        case 'malformed':
-            return `has \`options\` that are not a list of { id, value, label } strings. Serialize cannot write them, `
-                + `and the platform requires all three on every choice`;
         case 'missing':
-            return `is a ${JSON.stringify(type)} picker with no \`options\`, so the form publishes an empty picker`;
+            return `is a picker with no \`options\`, so the form publishes an empty picker`;
         case 'ignored':
-            return `has \`options\` but its type ${JSON.stringify(type)} is not a choice control, so the form renders a `
-                + `plain input and never shows them. Use 'singleSelect' or 'enum' (a dropdown) or 'multiSelect'`;
+            return `has \`options\` but its type ${JSON.stringify(type)} is not a choice control and it sets no picker `
+                + `\`controlType\`, so the form renders a plain input and never shows them. Use 'singleSelect' or 'enum' `
+                + `(a dropdown) or 'multiSelect', or set controlType: 'dropdown'`;
     }
 }
 /**
@@ -319,3 +388,152 @@ export function wireFormFieldType(type) {
         ? SDK_ALIASES[type]
         : type;
 }
+/**
+ * A field's settings as the form row carries them: each key the author set,
+ * in the platform's row order, copied so the wire never aliases the author's
+ * objects. Both serializers (human task, quick-form escalation) append this
+ * after the row's own keys.
+ *
+ * @example
+ * formFieldSettingsWire({ colSpan: 6, controlType: 'dropdown' }) // { colSpan: 6, controlType: 'dropdown' }
+ */
+export function formFieldSettingsWire(f) {
+    const wire = {};
+    for (const key of FORM_FIELD_SETTINGS_KEYS) {
+        const v = f[key];
+        if (v === undefined)
+            continue;
+        wire[key] = key === 'options' ? formFieldOptionsWire(v) : jsonClone(v);
+    }
+    return wire;
+}
+/** `o` with only `keys`, in `o`'s own order. */
+const pick = (o, keys) => Object.fromEntries(Object.entries(o).filter(([k]) => keys.includes(k)));
+/** The keys of `o` outside `keys`, each as `<at>.<key>`. */
+const extraKeys = (o, keys, at) => Object.keys(o).filter((k) => !keys.includes(k)).map((k) => `${at}.${k}`);
+/**
+ * A valid `options` or `rules` value without the keys the platform's schema
+ * does not define (it strips them too); any other setting as given.
+ */
+function stripSetting(key, v) {
+    if (key === 'options')
+        return v.map((o) => pick(o, OPTION_KEYS));
+    if (key === 'rules') {
+        return v.map((r) => ({
+            ...pick(r, RULE_KEYS),
+            conditions: r.conditions.map((c) => pick(c, CONDITION_KEYS)),
+        }));
+    }
+    return v;
+}
+/** The keys `stripSetting` drops from a valid `options` or `rules` value, e.g. `options[0].color`. */
+function settingExtraKeys(key, v) {
+    if (key === 'options') {
+        return v.flatMap((o, i) => extraKeys(o, OPTION_KEYS, `options[${i}]`));
+    }
+    if (key === 'rules') {
+        return v.flatMap((r, i) => [
+            ...extraKeys(r, RULE_KEYS, `rules[${i}]`),
+            ...r.conditions
+                .flatMap((c, j) => extraKeys(c, CONDITION_KEYS, `rules[${i}].conditions[${j}]`)),
+        ]);
+    }
+    return [];
+}
+/**
+ * A form row's settings read back for source: each settings key whose value
+ * has the platform's shape, copied, without any key the platform's schema does
+ * not define. A key with any other value is left out here; both cases are
+ * reported by `formFieldRowLoss`.
+ */
+export function liftFormFieldSettings(row) {
+    const settings = {};
+    for (const key of FORM_FIELD_SETTINGS_KEYS) {
+        if (row[key] !== undefined && validSetting(key, row[key]))
+            settings[key] = jsonClone(stripSetting(key, row[key]));
+    }
+    return settings;
+}
+/**
+ * A field's settings as source options, in the platform's row order, for the
+ * decompilers' printers. `value` prints one data value (`'high'`, `6`,
+ * `[{ id: 'o1', … }]`).
+ */
+export function formFieldSettingsSource(settings, value) {
+    return FORM_FIELD_SETTINGS_KEYS.map((key) => [key, settings[key] === undefined ? undefined : value(settings[key])]);
+}
+/**
+ * The keys of a form row the SDK cannot carry into source, each with why.
+ * Empty when decompile → compile writes the row back as it was. The lifts
+ * report a non-empty list as a warning (an error under `--strict`), so no key
+ * is dropped silently.
+ *
+ * @example
+ * formFieldRowLoss({ id: 'a', label: 'A', type: 'string', direction: 'output', colSpan: 13 }, 'human task')
+ * // ['colSpan: 13 (not the platform\'s shape for it)']
+ */
+export function formFieldRowLoss(row, site) {
+    const loss = [];
+    const id = String(row.id ?? '');
+    const direction = row.direction;
+    const say = (key, why) => {
+        loss.push(`${key}: ${JSON.stringify(row[key])} (${why})`);
+    };
+    for (const key of Object.keys(row)) {
+        if (row[key] === undefined)
+            continue;
+        if (!FORM_FIELD_ROW_KEYS.includes(key)) {
+            say(key, 'not a key of the platform\'s field schema');
+        }
+        else if (Object.hasOwn(SETTINGS, key)) {
+            if (!validSetting(key, row[key]))
+                say(key, 'not the platform\'s shape for it');
+            else {
+                const extra = settingExtraKeys(key, row[key]);
+                if (extra.length > 0)
+                    say(key, `${extra.join(', ')}: not in the platform's schema, which drops it too`);
+            }
+        }
+        else if (key === 'label') {
+            if (!isString(row.label))
+                say(key, 'not a string');
+        }
+        else if (key === 'value') {
+            say(key, 'the form editor\'s structured binding; a .flow stores it as `binding`, which is all the SDK reads');
+        }
+        else if (key === 'required') {
+            // `required: false` is the default: compile omits it, and the form behaves the same.
+            if (typeof row.required !== 'boolean')
+                say(key, 'not a boolean');
+            else if (direction === 'input' && row.required)
+                say(key, 'on a shown field, which the SDK does not model');
+        }
+        else if (key === 'binding') {
+            if (site === 'escalation')
+                say(key, 'on an escalation form, which the SDK writes without bindings');
+            else if (direction === 'output')
+                say(key, 'on an asked field, which the SDK writes without one');
+            else if (!isString(row.binding))
+                say(key, 'not a string');
+        }
+        else if (key === 'variable') {
+            if (site === 'escalation')
+                say(key, 'on an escalation form, which the SDK writes without variables');
+            else if (direction !== 'output')
+                say(key, 'on a shown or pre-filled field, which the SDK writes without one');
+            else if (row.variable !== `vars.${id}`)
+                say(key, `the SDK writes 'vars.${id}', the field's own id`);
+        }
+    }
+    return loss;
+}
+/**
+ * The warning (or `--strict` error) for a row `formFieldRowLoss` reported.
+ * `where` names the form, e.g. `human task "review"`.
+ */
+export function formFieldRowLossMessage(where, fieldId, loss) {
+    return `${where} form field ${JSON.stringify(fieldId)} has ${loss.length === 1 ? 'a key' : 'keys'} the SDK cannot `
+        + `write back: ${loss.join('; ')}. Compile writes the field without ${loss.length === 1 ? 'it' : 'them'}, so `
+        + `merging an edit of this node loses ${loss.length === 1 ? 'it' : 'them'}. Edit this field in the canvas or `
+        + `the .flow JSON instead.`;
+}

package/dist/decompile.js

@@ -51,7 +51,7 @@ import { OUTCOME_HANDLE_NODE_TYPES } from './core/hitl-routing.js';
 import { contributionPort, forwardFanOut } from './core/definition-handles.js';
 import { STICKY_NOTE_TYPE } from './core/definitionless-node-types.js';
 import { eventFilterFromTreeLeaf } from './core/event-filters.js';
-import { liftFormFieldOptions, sourceFormFieldType } from './core/form-field-type.js';
+import { formFieldRowLoss, formFieldRowLossMessage, formFieldSettingsSource, liftFormFieldSettings, sourceFormFieldType, } from './core/form-field-type.js';
 /**
  * The trigger id of the flow currently being decompiled, so a reference through a
  * RENAMED trigger is still recognized as `input('x')` rather than falling back to
@@ -280,6 +280,19 @@ function opts(entries) {
     const parts = entries.filter(([, v]) => v !== undefined).map(([k, v]) => `${key(k)}: ${v}`);
     return parts.length ? `{ ${parts.join(', ')} }` : '';
 }
+/**
+ * Plain JSON data as source, in the `{ k: v }` / `[a, b]` spelling the
+ * printers use (a form field's `options`, `rules`, `defaultValue`).
+ */
+function dataSource(v) {
+    if (Array.isArray(v))
+        return `[${v.map(dataSource).join(', ')}]`;
+    if (v !== null && typeof v === 'object') {
+        const parts = Object.entries(v).filter(([, x]) => x !== undefined).map(([k, x]) => `${key(k)}: ${dataSource(x)}`);
+        return parts.length ? `{ ${parts.join(', ')} }` : '{}';
+    }
+    return tsLiteral(v);
+}
 /** A collector for indented source lines. */
 class Emit {
     indentUnit;
@@ -618,6 +631,11 @@ function liftRegistered(node, impl = registeredImpl(node), graph) {
         // when the file carries none (a hand-trimmed or SDK-written file).
         definition: () => runDefs.get(`${node.type}@${version}`) ?? BUNDLED_DEFINITIONS[`${node.type}@${version}`] ?? runDefs.get(node.type),
         warn: warnOnce,
+        lossy: (message) => {
+            if (runStrict)
+                throw new Error(`decompile: ${message}`);
+            warnOnce(message);
+        },
         outPorts: () => (graph?.outEdges(node.id) ?? []).map((e) => e.sourcePort),
         convergedFanOut: () => graph?.convergedFanOut(node.id) === true,
     };
@@ -1343,17 +1361,28 @@ function emitAgentCluster(node, imp, inputNames, graph) {
             ['variant', isQuickForm ? tsLiteral('quick-form') : undefined],
             ['name', tsLiteral(rPlain(e, 'name') ?? '')],
             ['description', rPlain(e, 'description') !== undefined ? tsLiteral(rPlain(e, 'description')) : undefined],
-            ['fields', rows.length ? `[${rows.map((f) => opts([
-                    ['id', tsText(f.id)],
-                    ['type', tsLiteral(sourceFormFieldType(f.type ?? 'string'))],
-                    ['direction', tsLiteral(String(f.direction ?? 'output'))],
-                    ['options', (() => {
-                            const options = liftFormFieldOptions(f.options);
-                            return options === undefined ? undefined : `[${options.map((o) => opts([
-                                ['id', tsLiteral(o.id)], ['value', tsLiteral(o.value)], ['label', tsLiteral(o.label)],
-                            ])).join(', ')}]`;
-                        })()],
-                ])).join(', ')}]` : undefined],
+            ['fields', rows.length ? `[${rows.map((f) => {
+                    const id = String(f.id ?? '');
+                    const direction = String(f.direction ?? 'output');
+                    // Every row key the source cannot carry is reported, never dropped
+                    // silently: a warning, an error under --strict (#1250).
+                    const loss = formFieldRowLoss(f, 'escalation');
+                    if (loss.length > 0) {
+                        const message = formFieldRowLossMessage(`quick-form escalation ${JSON.stringify(rPlain(e, 'name') ?? e.id)} on agent ${JSON.stringify(node.id)}`, id, loss);
+                        if (runStrict)
+                            throw new Error(`decompile: ${message}`);
+                        warnOnce(message);
+                    }
+                    return opts([
+                        ['id', tsText(f.id)],
+                        // serialize defaults a row's label to its id.
+                        ['label', typeof f.label === 'string' && f.label !== id ? tsLiteral(f.label) : undefined],
+                        ['type', tsLiteral(sourceFormFieldType(f.type ?? 'string'))],
+                        ['direction', tsLiteral(direction)],
+                        ['required', typeof f.required === 'boolean' && direction !== 'input' ? String(f.required) : undefined],
+                        ...formFieldSettingsSource(liftFormFieldSettings(f), dataSource),
+                    ]);
+                }).join(', ')}]` : undefined],
             ['app', app === undefined ? undefined : opts([
                     ['key', tsText(app.key)],
                     ['name', tsText(app.name)],

package/dist/flow-node-type.d.ts

@@ -162,6 +162,12 @@ export interface FlowDeserializeContext {
     definition(): unknown;
     /** Report something the lift could not keep. Decompile prints it once. */
     warn(message: string): void;
+    /**
+     * Report something the source cannot carry, so compile would drop it: a
+     * warning, or under `--strict` (`bestEffort: false`) an error that stops
+     * decompile.
+     */
+    lossy(message: string): void;
     /** The source ports this node's out-edges leave from, in edge order (an empty list outside a graph). */
     outPorts(): readonly string[];
     /**

package/dist/nodes/hitl/flow/check.js

@@ -1,6 +1,6 @@
 import { Expr } from '../../../core/expr.js';
 import { nearestName } from '../../../core/edit-distance.js';
-import { FORM_FIELD_TYPES, formFieldOptionsProblem, formFieldOptionsWhy, formFieldTypeHint, formFieldTypeWhy, validFormFieldTypesText } from '../../../core/form-field-type.js';
+import { FORM_FIELD_TYPES, formFieldOptionsProblem, formFieldOptionsWhy, formFieldSettingProblems, formFieldTypeHint, formFieldTypeWhy, validFormFieldTypesText, } from '../../../core/form-field-type.js';
 import { isAnswerField } from '../../../core/hitl-answers.js';
 import { hitlDerivesOutcomeHandles, outcomeIdOf } from '../../../core/hitl-routing.js';
 export const HITL_DIAGNOSTICS = {
@@ -23,8 +23,9 @@ export const HITL_DIAGNOSTICS = {
     HITL_DUP_FIELD: { severity: 'error', summary: 'a form field id declared twice' },
     HITL_FIELD_RESERVED_ID: { severity: 'error', summary: 'a form field id the result already uses' },
     HITL_FIELD_TYPE_UNKNOWN: { severity: 'error', summary: 'a form field type the platform does not recognize' },
-    HITL_FIELD_OPTIONS: { severity: 'error', summary: 'a picker with no choices, or choices that are not { id, value, label } strings' },
-    HITL_FIELD_OPTIONS_IGNORED: { severity: 'warning', summary: 'choices on a field type that does not render them' },
+    HITL_FIELD_OPTIONS: { severity: 'error', summary: 'a picker with no choices' },
+    HITL_FIELD_OPTIONS_IGNORED: { severity: 'warning', summary: 'choices on a field that does not render them' },
+    HITL_FIELD_SETTING_INVALID: { severity: 'error', summary: 'a form field setting (controlType, colSpan, …) the platform refuses' },
     HITL_FIELD_NO_VALUE: { severity: 'error', summary: 'a shown field with no value' },
     HITL_FIELD_VALUE_NOT_REF: { severity: 'error', summary: 'a shown field filled from a literal' },
     HITL_FIELD_VALUE_NOT_PATH: { severity: 'error', summary: 'a shown field filled from a computed expression' },
@@ -217,10 +218,13 @@ export function checkHitl(inputs, ctx) {
             at('HITL_FIELD_TYPE_UNKNOWN', `Human task "${step}" gives the form field "${id}" the type ${JSON.stringify(f?.type)}, `
                 + `${formFieldTypeWhy(f?.type)}. Valid: ${validFormFieldTypesText()}.`, formFieldTypeHint(f?.type));
         }
-        const optionsProblem = formFieldOptionsProblem(f?.type, f.options);
+        const optionsProblem = formFieldOptionsProblem(f);
         if (optionsProblem !== undefined) {
             at(optionsProblem === 'ignored' ? 'HITL_FIELD_OPTIONS_IGNORED' : 'HITL_FIELD_OPTIONS', `Human task "${step}"'s form field "${id}" ${formFieldOptionsWhy(optionsProblem, f?.type)}.`, `options: [{ id: 'opt-1', value: 'high', label: 'High' }, { id: 'opt-2', value: 'low', label: 'Low' }]`);
         }
+        for (const problem of formFieldSettingProblems(f)) {
+            at('HITL_FIELD_SETTING_INVALID', `Human task "${step}" gives the form field "${id}" ${problem}. The platform refuses the form.`);
+        }
         if (isAnswerField(f))
             answers++; // an `output`, or an `inOut` whose reviewed value comes back
         if (f?.direction === 'input' || f?.direction === 'inOut') {

package/dist/nodes/hitl/flow/node-type.js

@@ -13,7 +13,7 @@
  * every edge out of an outcome-handle node to.
  */
 import { Expr, toExpr } from '../../../core/expr.js';
-import { formFieldJsonSchema, formFieldOptionsWire, liftFormFieldOptions, sourceFormFieldType, wireFormFieldType } from '../../../core/form-field-type.js';
+import { formFieldJsonSchema, formFieldRowLoss, formFieldRowLossMessage, formFieldSettingsSource, formFieldSettingsWire, liftFormFieldSettings, sourceFormFieldType, wireFormFieldType, } from '../../../core/form-field-type.js';
 import { isAnswerField } from '../../../core/hitl-answers.js';
 import { OUTCOME_HANDLE_NODE_TYPES, hitlExitModel, outcomeIdOf, outcomeSlug } from '../../../core/hitl-routing.js';
 import { jsonClone } from '../../../core/json-clone.js';
@@ -75,23 +75,23 @@ function hitlInputs(inputs, nodeType, ctx) {
             // contract flow-v1's serializer reads), and the WRITE target is the field
             // id itself — deliberately decoupled from the binding, so no `variable`.
             base.binding = bindingPath(f.value, ctx);
-            if (f.required)
-                base.required = true;
+            const required = f.required;
+            if (typeof required === 'boolean')
+                base.required = required;
         }
         else {
             // The answer's landing variable. The platform falls back to the field id
             // when this is absent; naming it keeps the emitted flow explicit and
             // matches what the designer writes.
             base.variable = `vars.${f.id}`;
-            if (f.required)
-                base.required = true;
+            const required = f.required;
+            if (typeof required === 'boolean')
+                base.required = required;
         }
-        // A picker's choices (a `singleSelect` dropdown, a `multiSelect`), as the
-        // canvas stores them on the row (#1235).
-        const options = formFieldOptionsWire(f.options);
-        if (options !== undefined)
-            base.options = options;
-        return base;
+        // The field's settings — `controlType`, a picker's `options`,
+        // `defaultValue`, `colSpan`, `rules`, … — as the canvas stores them on the
+        // row, in the platform's key order (#1235, #1250).
+        return { ...base, ...formFieldSettingsWire(f) };
     });
     const outcomes = (inputs?.outcomes ?? []).map((o, i) => {
         const name = typeof o === 'string' ? o : o?.name;
@@ -331,7 +331,11 @@ function liftHitl(node, typeName, ctx) {
         const id = String(f.id ?? '');
         const direction = String(f.direction ?? 'output');
         const value = direction === 'input' || direction === 'inOut' ? bindingExpr(f.binding) : undefined;
-        const options = liftFormFieldOptions(f.options);
+        // Every row key the source cannot carry is reported, never dropped
+        // silently: a warning, an error under --strict (#1250).
+        const loss = formFieldRowLoss(f, 'human task');
+        if (loss.length > 0)
+            ctx.lossy(formFieldRowLossMessage(`human task ${JSON.stringify(n.id)}`, id, loss));
         return {
             id,
             // serialize defaults a row's label to its id.
@@ -341,8 +345,8 @@ function liftHitl(node, typeName, ctx) {
             type: sourceFormFieldType(f.type ?? 'string'),
             direction,
             ...(value !== undefined ? { value } : {}),
-            ...(f.required === true ? { required: true } : {}),
-            ...(options !== undefined ? { options } : {}),
+            ...(typeof f.required === 'boolean' && direction !== 'input' ? { required: f.required } : {}),
+            ...liftFormFieldSettings(f),
         };
     });
     const outcomeRows = (Array.isArray(schema.outcomes) ? schema.outcomes : []);
@@ -504,12 +508,8 @@ function printHitl({ inputs }, ctx) {
         ['type', ctx.string(f.type)],
         ['direction', ctx.string(f.direction)],
         ['value', f.value !== undefined ? ctx.value(f.value) : undefined],
-        ['required', f.required ? 'true' : undefined],
-        ['options', f.options !== undefined ? `[${f.options.map((o) => obj([
-                ['id', ctx.string(o.id)],
-                ['value', ctx.string(o.value)],
-                ['label', ctx.string(o.label)],
-            ], ctx)).join(', ')}]` : undefined],
+        ['required', f.required !== undefined ? String(f.required) : undefined],
+        ...formFieldSettingsSource(f, ctx.value),
     ], ctx));
     const outcomes = h.outcomes.map((o) => (typeof o === 'string' ? ctx.string(o) : obj([
         ['name', ctx.string(o.name)],

package/dist/serialize.js

@@ -20,7 +20,7 @@ import { FLOW_NODE_TYPES } from './flow-node-registry.js';
 import { stepExits } from './flow-step-exits.js';
 import { resolveVersionCarried } from './core/nodes/versioned.js';
 import { indexCarriedDefinitions } from './core/carried-definitions.js';
-import { formFieldJsonSchema, formFieldOptionsWire, wireFormFieldType } from './core/form-field-type.js';
+import { formFieldJsonSchema, formFieldSettingsWire, wireFormFieldType } from './core/form-field-type.js';
 import { ConnectorResolveError } from './core/connector-resolve-error.js';
 import { connectionConnectors } from './bindings-v2.js';
 import { BindingRefusal, GUID_RE, bindingLabelRefusal, bindingMissingMessage, missingBindingLabels } from './core/binding-messages.js';
@@ -5751,14 +5751,17 @@ export function serialize(built, opts = {}) {
                     qnode.display = { ...qnode.display, shape: 'circle' };
                     delete qnode.model;
                     const rows = (esc.fields ?? []).map((f) => {
-                        const options = formFieldOptionsWire(f.options);
+                        const required = f.direction === 'input' ? undefined : f.required;
                         return {
                             id: f.id,
                             label: f.label ?? f.id,
                             type: wireFormFieldType(f.type),
                             direction: f.direction,
-                            // A picker's choices, as the human task's rows carry them (#1235).
-                            ...(options !== undefined ? { options } : {}),
+                            ...(typeof required === 'boolean' ? { required } : {}),
+                            // The field's settings (`controlType`, a picker's `options`,
+                            // `defaultValue`, `colSpan`, …), as the human task's rows carry
+                            // them (#1235, #1250).
+                            ...formFieldSettingsWire(f),
                         };
                     });
                     const qsource = esc.source ?? derivedEscalationSource(built.id, step.name, esc.name);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uipath/maestro-builder-sdk",
-  "version": "6.34.0",
+  "version": "6.35.0",
   "description": "Build UiPath Flow, Case, and BPMN artifacts by writing TypeScript.",
   "license": "MIT",
   "homepage": "https://docs.uipath.com/maestro",
@@ -93,5 +93,5 @@
     "@types/node": "^22.7.0",
     "esbuild": "^0.28.1"
   },
-  "gitref": "aa9dc9a7c6f6adc8edbf4c20d0681307073bb53b"
+  "gitref": "467e33fe1378eddf63acb88201f18ecac8a73967"
 }