@uipath/maestro-builder-sdk 6.33.2 → 6.35.0

package/dist/core/form-field-type.d.ts

@@ -26,7 +26,7 @@
  * agent quick-form escalations), decompile, and the serializers' output
  * schemas.
  */
-import type { CanonicalFormFieldType, ControlFormFieldType, FormFieldOption } from './actions.js';
+import type { CanonicalFormFieldType, ControlFormFieldType, FormFieldControlType, FormFieldSettings } from './actions.js';
 /** The product's 11 canonical quick-form field types, in its own order. */
 export declare const CANONICAL_FORM_FIELD_TYPES: CanonicalFormFieldType[];
 /** The SDK's legacy spellings (`text`, `date-time`), for diagnostics that list them. */
@@ -117,48 +117,50 @@ export declare function formFieldJsonSchema(type: unknown): {
     format?: string;
 } | undefined;
 /**
- * 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.
+ * 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 declare function formFieldOptionsWire(options: readonly FormFieldOption[] | undefined): FormFieldOption[] | undefined;
+export declare const FORM_FIELD_ROW_KEYS: readonly ["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 declare const FORM_FIELD_CONTROL_TYPES: readonly FormFieldControlType[];
 /**
- * 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 declare function liftFormFieldOptions(raw: unknown): FormFieldOption[] | undefined;
+export declare function formFieldSettingProblems(f: unknown): string[];
+/** The `FormFieldSettings` keys, in the platform's row order. */
+export declare const FORM_FIELD_SETTINGS_KEYS: (keyof FormFieldSettings)[];
 /**
- * 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`).
  *
- * - `'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.
+ * - `'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.
+ *
+ * `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 declare function formFieldOptionsProblem(type: unknown, options: unknown): 'malformed' | 'missing' | 'ignored' | undefined;
+export declare function formFieldOptionsProblem(f: unknown): 'missing' | 'ignored' | undefined;
 /**
  * The reason text for a `formFieldOptionsProblem`, worded for a diagnostic
  * that starts "… the field "<id>" …".
  */
-export declare function formFieldOptionsWhy(problem: 'malformed' | 'missing' | 'ignored', type: unknown): string;
+export declare function formFieldOptionsWhy(problem: 'missing' | 'ignored', type: unknown): string;
 /**
  * The spelling a form field's type is written in on the wire: the product's
  * canonical one for the SDK's legacy spellings (`text` is written `string`,
@@ -173,3 +175,49 @@ export declare function formFieldOptionsWhy(problem: 'malformed' | 'missing' | '
  * wireFormFieldType('number')    // 'number'
  */
 export declare function wireFormFieldType(type: unknown): unknown;
+/**
+ * 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 declare function formFieldSettingsWire(f: FormFieldSettings): Record<string, unknown>;
+/**
+ * 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 declare function liftFormFieldSettings(row: Record<string, unknown>): FormFieldSettings;
+/**
+ * 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 declare function formFieldSettingsSource(settings: FormFieldSettings, value: (v: unknown) => string): Array<[string, string | undefined]>;
+/**
+ * Where a form row lives, which decides which of its binding keys the SDK
+ * derives: a human task writes `binding` for a shown or pre-filled field and
+ * `variable: 'vars.<id>'` for an asked one; a quick-form escalation writes
+ * neither (the agent fills the form).
+ */
+export type FormRowSite = 'human task' | 'escalation';
+/**
+ * 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 declare function formFieldRowLoss(row: Record<string, unknown>, site: FormRowSite): string[];
+/**
+ * The warning (or `--strict` error) for a row `formFieldRowLoss` reported.
+ * `where` names the form, e.g. `human task "review"`.
+ */
+export declare function formFieldRowLossMessage(where: string, fieldId: string, loss: readonly string[]): string;

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') {