@servicenow/sdk-build-plugins 4.2.0 → 4.4.0

package/src/flow/flow-logic/flow-logic-plugin-helpers.ts

@@ -0,0 +1,2550 @@
+import type { Factory, Diagnostics, Result, Transform, Database, StringShape } from '@servicenow/sdk-build-core'
+import type {
+    FlowLogicInstanceShape,
+    ConditionalLogicInstanceShape,
+    ForEachInstanceShape,
+    GoBackToInstanceShape,
+    TryCatchInstanceShape,
+    DoInParallelInstanceShape,
+    SetFlowVariablesInstanceShape,
+    AssignSubflowOutputsInstanceShape,
+} from './flow-logic-shapes'
+import {
+    ts,
+    IdentifierShape,
+    ObjectShape,
+    ArrayShape,
+    Shape,
+    Record,
+    PropertyAccessShape,
+    TemplateExpressionShape,
+    CallExpressionShape,
+    DurationShape,
+} from '@servicenow/sdk-build-core'
+import { PillShape, PillTemplateShape } from '../utils/data-pill-shapes'
+import { gunzipSync } from 'zlib'
+import { normalizeInputValue } from '../plugins/flow-instance-plugin'
+import { FDInlineScriptCallShape } from '../plugins/inline-script-plugin'
+import { InlineScriptShape } from '../utils/flow-shapes'
+import {
+    FlowLogicSysId,
+    FLOW_LOGIC,
+    NAME_MAP,
+    DURATION_TYPE_PROPS,
+    WAIT_FOR_A_DURATION_INPUT_DESCRIPTORS,
+} from './flow-logic-constants'
+import { resolveDataPillShape, sysIdToUuid } from '../utils/utils'
+import { ArrowFunctionShape } from '../../arrow-function-plugin'
+import { NowIdShape } from '../../now-id-plugin'
+import { validateFlowLogic, validateSibling } from './flow-logic-diagnostics'
+import { determineRootIdentifierAndPath } from '../plugins/flow-data-pill-plugin'
+import type { Duration } from '@servicenow/sdk-core/runtime/db'
+
+async function buildFlowLogicInstanceRecord(
+    expr: FlowLogicInstanceShape,
+    factory: Factory,
+    values: FlowLogicValues
+): Promise<Record> {
+    const partialRecord = await factory.createRecord({
+        source: expr,
+        table: 'sys_hub_flow_logic_instance_v2',
+        explicitId: expr.getSysId(),
+        properties: {
+            comment: expr.getAnnotation()?.getValue() ?? '',
+            logic_definition: FlowLogicSysId.getLogicId(expr.getCallee() as FLOW_LOGIC),
+            values: values,
+        },
+    })
+    return partialRecord.merge({ ui_id: sysIdToUuid(partialRecord.getId().getValue()) })
+}
+
+interface FlowLogicValueInput {
+    name: string
+    value: string
+    displayValue?: string
+    children?: unknown[]
+    parameter?: { [key: string]: unknown }
+}
+
+interface FlowLogicValueWithScript extends FlowLogicValueInput {
+    scriptActive?: boolean
+}
+
+interface AssignSubflowOutput extends FlowLogicValueWithScript {}
+
+interface SetFlowVariablesInput extends FlowLogicValueWithScript {}
+
+interface WaitForADurationInput extends FlowLogicValueInput {
+    id: string
+    scriptActive: boolean
+}
+
+export interface FlowLogicValues {
+    inputs: FlowLogicValueInput[]
+    outputsToAssign: AssignSubflowOutput[]
+    variables: SetFlowVariablesInput[]
+    decisionTableInputs: []
+    dynamicInputs: []
+    workflowInputs: []
+}
+
+/**
+ * Creates an empty FlowLogicValues object with all fields initialized to empty arrays
+ * @returns Empty FlowLogicValues structure
+ */
+export function createEmptyFlowLogicValues(): FlowLogicValues {
+    return {
+        inputs: [],
+        outputsToAssign: [],
+        variables: [],
+        decisionTableInputs: [],
+        dynamicInputs: [],
+        workflowInputs: [],
+    }
+}
+
+type FlowLogicParseResult =
+    | { condition?: string; label?: string } // If/ElseIf/Else
+    | string // GoBackTo step ID
+    | { [key: string]: unknown } // Generic for future types
+
+/**
+ * FlowLogicValueProcessor handles bidirectional conversion between Fluent TypeScript
+ * flow logic calls and ServiceNow XML flow records.
+ *
+ * ## Architecture
+ *
+ * **Forward Flow (Fluent → XML):**
+ * - `prepare()` converts TypeScript flow logic calls to ServiceNow XML format
+ * - Extracts configuration properties and creates structured input data
+ * - Data gets gzipped and stored in sys_hub_flow_logic_instance_v2 records
+ *
+ * **Reverse Flow (XML → Fluent):**
+ * - `parse()` converts ServiceNow XML records back to TypeScript
+ * - Unzips and parses stored JSON data
+ * - Reconstructs original configuration objects for shape generation
+ *
+ * ## Data Structure
+ *
+ * All flow logic data is stored as FlowLogicValues containing an array of
+ * FlowLogicValueInput objects with name/value pairs that represent the
+ * original TypeScript configuration properties.
+ */
+namespace FlowLogicValueProcessor {
+    /**
+     * Generic factory function for creating flow logic entry objects.
+     * All entry types (AssignSubflowOutput, SetFlowVariablesInput, FlowLogicValueInput)
+     * share the same structure, differing only in displayValue and type name.
+     *
+     * @param name - Entry name
+     * @param value - Entry value (may contain datapills like "{{trigger.name}}")
+     * @param children - Optional children array for complex objects (FlowObject/FlowArray)
+     * @param displayValue - Display value shown in ServiceNow UI (defaults to value)
+     * @returns Entry object with the specified type
+     */
+    function createEntry<T extends SetFlowVariablesInput | AssignSubflowOutput | FlowLogicValueInput>(
+        name: string,
+        value: string,
+        children?: unknown[],
+        displayValue: string = value
+    ): T {
+        return {
+            name,
+            value,
+            displayValue,
+            children: children || [],
+            parameter: {},
+            scriptActive: false,
+        } as T
+    }
+
+    function createInput(name: string, value: string): FlowLogicValueInput {
+        return createEntry<FlowLogicValueInput>(name, value)
+    }
+
+    /**
+     * Creates an AssignSubflowOutput entry with full display value.
+     * Used when generating XML from Fluent code for assignSubflowOutputs.
+     *
+     * @param name - Output name
+     * @param value - Output value (may contain datapills like "{{trigger.name}}")
+     * @param children - Optional children array for complex objects (FlowObject/FlowArray)
+     * @returns AssignSubflowOutput with displayValue set to the value
+     */
+    function createOutput(name: string, value: string, children?: unknown[]): AssignSubflowOutput {
+        return createEntry<AssignSubflowOutput>(name, value, children)
+    }
+
+    /**
+     * Creates a SetFlowVariablesInput entry for the 'variables' array with full display value.
+     * Used when generating XML from Fluent code.
+     *
+     * @param name - Variable name
+     * @param value - Variable value (may contain datapills like "{{trigger.name}}")
+     * @param children - Optional children array for complex objects (FlowObject/FlowArray)
+     * @returns SetFlowVariablesInput with displayValue set to the value
+     */
+    function createVariable(name: string, value: string, children?: unknown[]): SetFlowVariablesInput {
+        return createEntry<SetFlowVariablesInput>(name, value, children)
+    }
+
+    /**
+     * Creates a SetFlowVariablesInput entry for the 'inputs' array with empty display value.
+     * Used when generating XML from Fluent code for the inputs array (required for backward compatibility).
+     *
+     * @param name - Variable name
+     * @param value - Variable value
+     * @param children - Optional children array for complex objects (FlowObject/FlowArray)
+     * @returns SetFlowVariablesInput with empty displayValue
+     */
+    function createVariableInput(name: string, value: string, children?: unknown[]): SetFlowVariablesInput {
+        return createEntry<SetFlowVariablesInput>(name, value, children, '')
+    }
+
+    // Factory pattern for value preparation
+    type InputValuePreparer = (
+        data: ObjectShape | Record | StringShape,
+        args?: { [key: string]: unknown }
+    ) => FlowLogicValueInput[]
+
+    const INPUT_VALUE_PREPARERS: { [K in FLOW_LOGIC]: InputValuePreparer } = {
+        [FLOW_LOGIC.ELSE]: () => [],
+        [FLOW_LOGIC.GOBACKTO]: (data: Shape) => prepareGoBackTo(data.isString() ? data.asString() : data.asRecord()),
+        [FLOW_LOGIC.IF]: (data) => prepareIfElse(data.asObject()),
+        [FLOW_LOGIC.ELSEIF]: (data) => prepareIfElse(data.asObject()),
+        [FLOW_LOGIC.WAIT_FOR_A_DURATION]: (data) => prepareWaitForADuration(data.asObject()),
+        [FLOW_LOGIC.EXITLOOP]: () => [],
+        [FLOW_LOGIC.ENDFLOW]: () => [],
+        [FLOW_LOGIC.SKIP_ITERATION]: () => [],
+        [FLOW_LOGIC.FOR_EACH]: (data) => prepareForEach(data.asString()),
+        [FLOW_LOGIC.DO_IN_PARALLEL]: () => [],
+        [FLOW_LOGIC.TRY_CATCH]: () => [],
+        [FLOW_LOGIC.SET_FLOW_VARIABLES]: (data) => {
+            return prepareSetFlowVariables(data.asObject(), '')
+        },
+        [FLOW_LOGIC.ASSIGN_SUBFLOW_OUTPUTS]: (data) => {
+            return prepareAssignSubflowOutputs(data.asObject())
+        },
+    }
+
+    /**
+     * Converts Fluent TypeScript flow logic calls into ServiceNow XML format.
+     *
+     * **Process:**
+     * 1. Takes the flow logic type (e.g., 'IF') and configuration data
+     * 2. Uses the appropriate VALUE_PREPARER function
+     * 3. Extracts relevant properties (condition, label, etc.)
+     * 4. Creates FlowLogicValueInput objects with name/value pairs
+     * 5. Returns FlowLogicValues structure that gets gzipped into XML
+     *
+     * **Example:**
+     * ```typescript
+     * // Input: If({ condition: "user.role === 'admin'", label: "Admin Check" })
+     * // Output: { inputs: [
+     * //   { name: 'condition_name', value: 'Admin Check' },
+     * //   { name: 'condition', value: "user.role === 'admin'" }
+     * // ]}
+     * ```
+     *
+     * @param logicType - The flow logic type key (e.g., 'IF', 'ELSEIF', 'GOBACKTO')
+     * @param data - Configuration data from the Fluent TypeScript call
+     * @param args - Optional arguments including childNameMetadata for FlowArray fields
+     * @returns FlowLogicValues structure ready for XML serialization
+     */
+    export function prepare(
+        logicType: FLOW_LOGIC,
+        data: ObjectShape | Record | StringShape,
+        args?: { [key: string]: unknown; childNameMetadata?: Map<string, string> }
+    ): FlowLogicValues {
+        const preparer = INPUT_VALUE_PREPARERS[logicType]
+        if (!preparer) {
+            throw new Error(`Unsupported flow logic type: ${logicType}`)
+        }
+
+        const preparedData = preparer(data, args)
+
+        return {
+            outputsToAssign: logicType === FLOW_LOGIC.ASSIGN_SUBFLOW_OUTPUTS ? preparedData : [],
+            variables:
+                logicType === FLOW_LOGIC.SET_FLOW_VARIABLES
+                    ? prepareSetFlowVariables(data.asObject(), 'variables')
+                    : [],
+            decisionTableInputs: [],
+            dynamicInputs: [],
+            workflowInputs: [],
+            inputs: logicType === FLOW_LOGIC.ASSIGN_SUBFLOW_OUTPUTS ? [] : preparedData,
+        }
+    }
+
+    function prepareIfElse(config: ObjectShape): FlowLogicValueInput[] {
+        const inputs: FlowLogicValueInput[] = []
+        // After datapill resolution, values are already resolved strings, so use getValue() directly
+        const conditionValue = config.get('condition')?.getValue()
+        const conditionString = typeof conditionValue === 'string' ? conditionValue : String(conditionValue ?? '')
+        const labelValue = config.get('label')?.getValue()
+        const label = labelValue && typeof labelValue === 'string' ? labelValue : ''
+
+        if (!conditionString) {
+            return []
+        }
+
+        if (label) {
+            inputs.push(createInput('condition_name', label))
+        }
+
+        inputs.push(createInput('condition', conditionString))
+        return inputs
+    }
+
+    function prepareGoBackTo(step: Record | StringShape): FlowLogicValueInput[] {
+        const stepId = step.isRecord() ? step.get('ui_id').asString().getValue() : step.asString().getValue()
+        return [createInput('go_back_to_step', stepId)]
+    }
+
+    function prepareForEach(config: StringShape): FlowLogicValueInput[] {
+        // ForEach needs to extract the items array from the first argument
+        // The structure is: ForEach(items, config, body)
+        // For now, we create a basic items input descriptor based on the XML structure we found
+
+        const inputs: FlowLogicValueInput[] = []
+
+        // Create the items input descriptor based on the XML structure we found
+        const itemsInput: FlowLogicValueInput = {
+            name: 'items',
+            value: config.getValue(),
+            displayValue: config.getValue(),
+        }
+
+        inputs.push(itemsInput)
+        return inputs
+    }
+
+    function prepareWaitForADuration(config: ObjectShape): WaitForADurationInput[] {
+        const inputDescriptors = JSON.parse(JSON.stringify(WAIT_FOR_A_DURATION_INPUT_DESCRIPTORS))
+
+        // Helper to safely get config value as string (after datapill resolution, values are already resolved)
+        const getConfigValue = (key: string): string => {
+            const value = config.get(key)?.getValue()
+            return value !== undefined && value !== null ? String(value) : ''
+        }
+
+        // Map the instanceProps to the correct fields in the template
+        // durationType: explicit_duration | relative_duration | percentage_duration
+        const durationType = getConfigValue('durationType')
+
+        // Duration field is optional (not required for percentage_duration)
+        const durationField = config.get('duration')
+        const duration =
+            durationField && !durationField.isUndefined()
+                ? new DurationShape({
+                      source: config.getOriginalNode(),
+                      value: durationField.getValue() as Duration,
+                  })
+                : durationField
+
+        const schedule = getConfigValue('schedule')
+        const durationTypeDisplayMap: { [key: string]: string } = {
+            explicit_duration: 'Explicit duration',
+            relative_duration: 'Relative duration',
+            percentage_duration: 'Percentage duration',
+        }
+
+        const updateDescriptor = (index: number, value: string, displayValue?: string, parameterType?: string) => {
+            if (inputDescriptors[index]) {
+                inputDescriptors[index].value = value
+                inputDescriptors[index].displayValue = displayValue ?? value
+                // Add parameter.type to preserve type information for round-trip transformation
+                if (parameterType) {
+                    inputDescriptors[index].parameter = { type: parameterType }
+                }
+            }
+        }
+
+        updateDescriptor(0, durationType, durationTypeDisplayMap[durationType])
+        const durationValue = duration?.toString()?.getValue() || ''
+        // Include 'glide_duration' type so XML → Fluent transform knows to create DurationShape
+        updateDescriptor(3, durationValue, durationValue, 'glide_duration')
+        updateDescriptor(6, schedule)
+
+        if (durationType === 'relative_duration') {
+            updateDescriptor(4, getConfigValue('relativeOperator'))
+            updateDescriptor(5, getConfigValue('relativeDatetime'))
+        }
+
+        if (durationType === 'percentage_duration') {
+            updateDescriptor(2, getConfigValue('percentage'))
+            updateDescriptor(1, getConfigValue('percentageDatetime'))
+        }
+
+        return inputDescriptors
+    }
+
+    /**
+     * Checks if a value is a serialized inline script object.
+     * Inline script objects have the shape: { scriptActive: true, script: {...}, name, value, ... }
+     *
+     * @param value - The value to check
+     * @returns true if value is an inline script object, false otherwise
+     */
+    function isSerializedInlineScript(value: unknown): boolean {
+        return (
+            typeof value === 'object' &&
+            value !== null &&
+            !Array.isArray(value) &&
+            (value as { scriptActive?: boolean }).scriptActive === true
+        )
+    }
+
+    /**
+     * Builds a flattened children array from a nested object or array.
+     * Used for the 'children' field in SetFlowVariablesInput for complex objects (FlowObject/FlowArray).
+     *
+     * @param value - The object or array value
+     * @param childName - Optional childName for FlowArray elements (e.g., 'tag', 'color')
+     * @returns Array of child entries with name, value, displayValue, and scriptActive fields
+     */
+    function buildChildrenArray(value: unknown, childName?: string): unknown[] {
+        const children: unknown[] = []
+
+        if (Array.isArray(value)) {
+            // FlowArray: Create a child entry for each array element
+            // Use childName if provided (matches UI behavior), otherwise empty string (backward compatibility)
+            const elementName = childName || ''
+
+            for (const element of value) {
+                if (typeof element === 'object' && element !== null) {
+                    // Nested object in array
+                    children.push({
+                        name: elementName,
+                        value: '',
+                        displayValue: '',
+                        children: buildChildrenArray(element),
+                        scriptActive: false,
+                    })
+                } else {
+                    // Primitive in array
+                    const elementStr =
+                        element === null || element === undefined || element === '' ? '' : String(element)
+                    children.push({
+                        name: elementName,
+                        value: elementStr,
+                        displayValue: elementStr,
+                        scriptActive: false,
+                    })
+                }
+            }
+        } else if (typeof value === 'object' && value !== null) {
+            // FlowObject: Create a child entry for each field
+            for (const [fieldName, fieldValue] of Object.entries(value)) {
+                if (typeof fieldValue === 'object' && fieldValue !== null && !Array.isArray(fieldValue)) {
+                    // Nested object
+                    children.push({
+                        name: fieldName,
+                        value: '',
+                        displayValue: '',
+                        children: buildChildrenArray(fieldValue),
+                        scriptActive: false,
+                    })
+                } else if (Array.isArray(fieldValue)) {
+                    // Nested array - Note: nested arrays don't have childName metadata yet
+                    children.push({
+                        name: fieldName,
+                        value: '',
+                        displayValue: '',
+                        children: buildChildrenArray(fieldValue),
+                        scriptActive: false,
+                    })
+                } else {
+                    // Primitive field
+                    const fieldStr =
+                        fieldValue === null || fieldValue === undefined || fieldValue === '' ? '' : String(fieldValue)
+                    children.push({
+                        name: fieldName,
+                        value: fieldStr,
+                        displayValue: fieldStr,
+                        scriptActive: false,
+                    })
+                }
+            }
+        }
+
+        return children
+    }
+
+    /**
+     * Generic helper to prepare entries from ObjectShape for XML serialization.
+     * Extracts key-value pairs and applies a factory function to create typed entries.
+     *
+     * Handles inline script objects (with scriptActive: true) by returning them as-is.
+     * Also handles complex objects (FlowObject/FlowArray) by building children arrays.
+     *
+     * @param values - ObjectShape containing name-value pairs from Fluent code
+     * @param factory - Factory function to create entry objects from key-value pairs
+     * @param childNameMetadata - Optional map of field name → childName for FlowArray fields
+     * @param useDottedNames - If true, use "fieldName.childName" format for array elements (assignSubflowOutputs)
+     * @returns Array of entries ready for XML serialization
+     */
+    function prepareEntries<T>(
+        values: ObjectShape,
+        factory: (key: string, value: string, children?: unknown[]) => T
+    ): T[] {
+        if (!values || values.isUndefined()) {
+            return []
+        }
+
+        const results: T[] = []
+        const entries = values.entries({ resolve: false })
+
+        for (const [key, shape] of entries) {
+            // Check if the shape is an ObjectShape (for FlowObject assignments)
+            if (shape.is(ObjectShape)) {
+                const serializedObj = serializeShapeToValue(shape)
+
+                // Check if the serialized value is an inline script (has scriptActive: true)
+                if (isSerializedInlineScript(serializedObj)) {
+                    // Inline scripts are already in the correct format - return as-is
+                    results.push(serializedObj as unknown as T)
+                    continue
+                }
+
+                // Regular FlowObject - children with correct names will be added by resolveComplexInput in postProcess
+                const children = buildChildrenArray(serializedObj)
+                results.push(factory(key, JSON.stringify(serializedObj), children))
+                continue
+            }
+
+            // Check if the shape is an ArrayShape (for FlowArray assignments)
+            if (shape.is(ArrayShape)) {
+                const arrShape = shape.as(ArrayShape)
+                const serializedArr: unknown[] = []
+                for (const elem of arrShape.getElements()) {
+                    serializedArr.push(serializeShapeToValue(elem))
+                }
+                // Children with correct names will be added by resolveComplexInput in postProcess
+                const children = buildChildrenArray(serializedArr)
+                results.push(factory(key, JSON.stringify(serializedArr), children))
+                continue
+            }
+
+            // For all other shapes, get their value
+            const value = shape.getValue()
+
+            // Check if value is a serialized inline script object
+            if (isSerializedInlineScript(value)) {
+                // Inline scripts are already in the correct format - return as-is
+                results.push(value as unknown as T)
+                continue
+            }
+
+            // Check if value is a plain object or array (shouldn't happen but just in case)
+            if (typeof value === 'object' && value !== null) {
+                const children = buildChildrenArray(value)
+                results.push(factory(key, JSON.stringify(value), children))
+                continue
+            }
+
+            // Primitive values (string, number, boolean, datapills)
+            results.push(factory(key, String(value)))
+        }
+
+        return results
+    }
+
+    /**
+     * Recursively serializes a Shape to a plain JavaScript value, preserving datapills as pill strings.
+     * @param shape - The shape to serialize
+     * @returns Plain JavaScript value with datapills as strings like "{{trigger.name}}"
+     */
+    function serializeShapeToValue(shape: Shape): unknown {
+        if (shape.is(ObjectShape)) {
+            const obj: { [key: string]: unknown } = {}
+            for (const [key, valueShape] of shape.as(ObjectShape).entries({ resolve: false })) {
+                obj[key] = serializeShapeToValue(valueShape)
+            }
+            return obj
+        }
+
+        if (shape.is(ArrayShape)) {
+            const arr: unknown[] = []
+            for (const elem of shape.as(ArrayShape).getElements()) {
+                arr.push(serializeShapeToValue(elem))
+            }
+            return arr
+        }
+
+        // Handle TemplateExpressionShape (template strings with datapills)
+        if (shape.is(TemplateExpressionShape)) {
+            // TemplateExpressionShape should have been converted to PillTemplateShape by DataPillPlugin
+            // If it's a PillTemplateShape, get its value
+            if (shape.is(PillTemplateShape)) {
+                return shape.as(PillTemplateShape).getValue()
+            }
+            // Otherwise, get the regular value
+            return shape.getValue()
+        }
+
+        // Handle PillShape (wfa.dataPill() is converted to PillShape by WfaDataPillPlugin)
+        if (shape.is(PillShape)) {
+            return shape.as(PillShape).getValue()
+        }
+
+        // For all other shapes (primitives, etc.), get the value
+        return shape.getValue()
+    }
+
+    /**
+     * Prepares SetFlowVariables data for XML serialization.
+     * Converts an ObjectShape containing variable assignments into an array of SetFlowVariablesInput entries.
+     *
+     * The `type` parameter determines which array format to use:
+     * - 'variables': Creates entries with full displayValue (for the 'variables' array in XML)
+     * - default: Creates entries with empty displayValue (for the 'inputs' array in XML)
+     *
+     * This dual behavior is required because ServiceNow stores SetFlowVariables data in both
+     * the 'variables' array and the 'inputs' array for backward compatibility.
+     *
+     * @param values - ObjectShape containing variable name-value pairs from Fluent code
+     * @param type - Optional type flag ('variables' for variables array, default for inputs array)
+     * @returns Array of SetFlowVariablesInput entries ready for XML serialization
+     *
+     * @example
+     * // Fluent: { user: params.trigger.name, count: 42 }
+     * // Variables array: [{ name: 'user', value: '{{trigger.name}}', displayValue: '{{trigger.name}}' }, ...]
+     * // Inputs array: [{ name: 'user', value: '{{trigger.name}}', displayValue: '' }, ...]
+     */
+    function prepareSetFlowVariables(values: ObjectShape, type: string = ''): SetFlowVariablesInput[] {
+        return prepareEntries(values, (key, value, children) => {
+            // Choose appropriate creator based on type flag
+            if (type === 'variables') {
+                return createVariable(key, value, children)
+            } else {
+                return createVariableInput(key, value, children)
+            }
+        })
+    }
+
+    /**
+     * Prepares AssignSubflowOutputs data for XML serialization.
+     * Converts an ObjectShape containing output assignments into an array of AssignSubflowOutput entries.
+     *
+     * @param values - ObjectShape containing output name-value pairs from Fluent code
+     * @returns Array of AssignSubflowOutput entries ready for XML serialization
+     *
+     * @example
+     * // Fluent: { result: params.action.output, status: 'complete' }
+     * // XML: [{ name: 'result', value: '{{action.output}}', displayValue: '{{action.output}}', scriptActive: false }, ...]
+     *
+     * Note: childName for FlowArray fields is now set automatically by resolveComplexInput in postProcess functions
+     */
+    function prepareAssignSubflowOutputs(values: ObjectShape): AssignSubflowOutput[] {
+        return prepareEntries(values, createOutput)
+    }
+
+    // Factory pattern for value parsing
+    type ValueParser = (inputs: FlowLogicValueInput[]) => FlowLogicParseResult
+
+    const VALUE_PARSERS: { [K in FLOW_LOGIC]: ValueParser } = {
+        [FLOW_LOGIC.GOBACKTO]: parseGoBackTo,
+        [FLOW_LOGIC.IF]: parseIfElse,
+        [FLOW_LOGIC.ELSEIF]: parseIfElse,
+        [FLOW_LOGIC.ELSE]: parseIfElse,
+        [FLOW_LOGIC.WAIT_FOR_A_DURATION]: () => ({}),
+        [FLOW_LOGIC.EXITLOOP]: () => ({}),
+        [FLOW_LOGIC.ENDFLOW]: () => ({}),
+        [FLOW_LOGIC.SKIP_ITERATION]: () => ({}),
+        [FLOW_LOGIC.FOR_EACH]: parseForEach,
+        [FLOW_LOGIC.DO_IN_PARALLEL]: () => ({}),
+        [FLOW_LOGIC.TRY_CATCH]: () => ({}),
+        [FLOW_LOGIC.SET_FLOW_VARIABLES]: () => ({}),
+        [FLOW_LOGIC.ASSIGN_SUBFLOW_OUTPUTS]: () => ({}),
+    }
+
+    /**
+     * Converts ServiceNow XML flow logic records back to Fluent TypeScript.
+     *
+     * **Process:**
+     * 1. Takes gzipped JSON string from XML record
+     * 2. Unzips and parses the FlowLogicValues structure
+     * 3. Uses the appropriate VALUE_PARSER function
+     * 4. Reconstructs the original configuration object
+     * 5. Returns structured data for shape generation
+     *
+     * **Example:**
+     * ```typescript
+     * // Input: gzipped JSON with inputs array
+     * // Output: { condition: "user.role === 'admin'", label: "Admin Check"    /**
+     * Parses flow logic values from gzipped JSON string
+     * @param logicType - The flow logic type key (e.g., 'IF', 'ELSEIF', 'GOBACKTO')
+     * @param gZippedString - Base64 encoded gzipped JSON from XML record
+     * @param typeMap - Optional map of variable/output names to their internal types for proper type conversion
+     * @param labelCacheMap - Optional map of datapill names to their types from the label cache
+     * @returns Parsed configuration object for TypeScript shape generation
+     */
+    export function parse(
+        logicType: FLOW_LOGIC,
+        gZippedString: string,
+        typeMap?: Map<string, string>,
+        labelCacheMap?: Map<string, string>
+    ): FlowLogicParseResult {
+        const valuesJson = parseGzippedJson(gZippedString)
+
+        // Special handling for SET_FLOW_VARIABLES - data is in variables array
+        if (logicType === FLOW_LOGIC.SET_FLOW_VARIABLES) {
+            if (valuesJson?.variables?.length) {
+                return parseEntriesFromArray(valuesJson.variables, typeMap, labelCacheMap)
+            }
+            return {}
+        }
+
+        // Special handling for ASSIGN_SUBFLOW_OUTPUTS - data is in outputsToAssign array
+        if (logicType === FLOW_LOGIC.ASSIGN_SUBFLOW_OUTPUTS) {
+            if (valuesJson?.outputsToAssign?.length) {
+                return parseEntriesFromArray(valuesJson.outputsToAssign, typeMap, labelCacheMap)
+            }
+            return {}
+        }
+
+        if (!valuesJson?.inputs?.length) {
+            if (logicType === FLOW_LOGIC.GOBACKTO) {
+                throw new Error('Malformed/unsupported input payload in GoBackTo Instance')
+            }
+            return {}
+        }
+
+        const parser = VALUE_PARSERS[logicType]
+        if (!parser) {
+            throw new Error(`Unsupported flow logic type for parsing: ${logicType}`)
+        }
+
+        return parser(valuesJson.inputs)
+    }
+
+    function parseGzippedJson(gZippedString: string): FlowLogicValues | null {
+        try {
+            const unzipped = gunzipSync(Buffer.from(gZippedString, 'base64')).toString()
+            return JSON.parse(unzipped)
+        } catch {
+            return null
+        }
+    }
+
+    function parseIfElse(inputs: FlowLogicValueInput[]): { condition?: string; label?: string } {
+        const result: { condition?: string; label?: string } = {}
+
+        for (const input of inputs) {
+            if (input.name === 'condition' && input.value) {
+                result.condition = input.value
+            } else if (input.name === 'condition_name' && input.value) {
+                result.label = input.value
+            }
+        }
+
+        return result
+    }
+
+    function parseGoBackTo(inputs: FlowLogicValueInput[]): string {
+        for (const input of inputs) {
+            if (input.name === 'go_back_to_step' && input.value) {
+                return input.value
+            }
+        }
+        throw new Error('Malformed/unsupported input payload in GoBackTo Instance')
+    }
+
+    function parseForEach(inputs: FlowLogicValueInput[]): { items?: string } {
+        const result: { items?: string } = {}
+
+        for (const input of inputs) {
+            if (input.name === 'items' && input.value) {
+                result.items = input.value
+            }
+        }
+
+        return result
+    }
+
+    // Constants for type handling
+    const ARRAY_TYPE_PREFIX = 'array.' as const
+    const ARRAY_TYPE_PREFIX_LENGTH = ARRAY_TYPE_PREFIX.length
+    const EXCLUDED_TYPE_ANNOTATIONS = new Set(['string', 'glide_date_time'])
+
+    /**
+     * Interface for child entry structure used in parsing
+     */
+    interface ChildEntry {
+        name?: string
+        value?: string
+        children?: unknown[]
+        parameter?: {
+            type?: string
+        }
+    }
+
+    /**
+     * Extracts the base name from a dotted path (e.g., "project.name" -> "name")
+     * For assignSubflowOutputs, names are prefixed with parent (e.g., "project.name", "project.tasks")
+     * We need to strip the prefix to get the actual field name
+     * @param name - Full path name
+     * @returns Base name after the last dot
+     */
+    function getBaseName(name?: string): string {
+        if (!name) {
+            return ''
+        }
+        const lastDot = name.lastIndexOf('.')
+        return lastDot >= 0 ? name.substring(lastDot + 1) : name
+    }
+
+    /**
+     * Extracts element type from array type string
+     * @param type - Type string like "array.integer" or "string"
+     * @returns Element type or undefined
+     */
+    function extractArrayElementType(type?: string): string | undefined {
+        if (!type || !type.startsWith(ARRAY_TYPE_PREFIX)) {
+            return undefined
+        }
+        return type.substring(ARRAY_TYPE_PREFIX_LENGTH)
+    }
+
+    /**
+     * Strip type annotation from datapill strings.
+     * ServiceNow stores datapills with type annotations like {{trigger.name|string}}.
+     * We need to remove the |type part before creating PropertyAccessShape.
+     *
+     * @param value - The value to clean (may be datapill string or regular value)
+     * @returns Cleaned value with type annotation removed
+     */
+    function stripDatapillTypeAnnotation(value: string): string {
+        // Check if this is a datapill string (starts with {{ and ends with }})
+        if (value.startsWith('{{') && value.endsWith('}}')) {
+            // Extract content between {{ and }}
+            const content = value.slice(2, -2)
+            // Split by | and take only the first part (the path without type annotation)
+            const pathOnly = content.split('|')[0]
+            // Return cleaned datapill
+            return `{{${pathOnly}}}`
+        }
+        // Not a datapill, return as-is
+        return value
+    }
+
+    /**
+     * Adds type annotation to a datapill if needed based on label cache
+     * @param pillName - Datapill name without braces
+     * @param labelCacheMap - Map of datapill names to types
+     * @returns Datapill with annotation if applicable
+     */
+    function addTypeAnnotationIfNeeded(pillName: string, labelCacheMap?: Map<string, string>): string {
+        if (!labelCacheMap) {
+            return `{{${pillName}}}`
+        }
+
+        const cachedType = labelCacheMap.get(pillName.trim())
+        if (cachedType && !EXCLUDED_TYPE_ANNOTATIONS.has(cachedType)) {
+            return `{{${pillName}|${cachedType}}}`
+        }
+
+        return `{{${pillName}}}`
+    }
+
+    /**
+     * Processes a pure datapill value (starts and ends with {{}})
+     * @param value - Pure datapill string
+     * @param labelCacheMap - Map of datapill names to types
+     * @returns Processed datapill with type annotation if needed
+     */
+    function processPureDatapill(value: string, labelCacheMap?: Map<string, string>): string {
+        const strippedValue = stripDatapillTypeAnnotation(value)
+        const pillName = strippedValue.slice(2, -2) // Remove {{ and }}
+        return addTypeAnnotationIfNeeded(pillName, labelCacheMap)
+    }
+
+    /**
+     * Processes a template expression containing datapills mixed with text
+     * @param value - Template expression string
+     * @param labelCacheMap - Map of datapill names to types
+     * @returns Processed template with type annotations added to datapills
+     */
+    function processTemplateExpression(value: string, labelCacheMap?: Map<string, string>): string {
+        if (!labelCacheMap) {
+            return value
+        }
+
+        const datapillRegex = /\{\{([^}|]+)(?:\|[^}]+)?\}\}/g
+        return value.replace(datapillRegex, (_match, pillName) => addTypeAnnotationIfNeeded(pillName, labelCacheMap))
+    }
+
+    /**
+     * Converts a primitive value based on its type
+     * @param value - String value to convert
+     * @param uiType - Type information
+     * @returns Converted value
+     */
+    function convertPrimitiveValue(value: string, uiType?: string): unknown {
+        // Preserve empty strings - don't convert them to 0 or false
+        if (value === '') {
+            return value
+        }
+
+        if (uiType === 'integer') {
+            const num = Number(value)
+            return Number.isNaN(num) ? value : num
+        }
+
+        if (uiType === 'boolean') {
+            if (value === 'true' || value === '1') {
+                return true
+            }
+            if (value === 'false' || value === '0') {
+                return false
+            }
+            return value
+        }
+
+        return stripDatapillTypeAnnotation(value)
+    }
+
+    /**
+     * Recursively applies type conversion to an object and its nested objects
+     * @param obj - Object to apply type conversion to
+     * @param typeMap - Map of field names to their types
+     * @returns Object with type-converted values
+     */
+    function applyTypeConversionToObject(obj: unknown, typeMap: Map<string, string>): unknown {
+        if (typeof obj !== 'object' || obj === null) {
+            return obj
+        }
+        if (Array.isArray(obj)) {
+            return obj
+        }
+        const result: { [key: string]: unknown } = {}
+        for (const [key, value] of Object.entries(obj)) {
+            const fieldType = typeMap.get(key)
+            if (typeof value === 'string' && fieldType) {
+                result[key] = convertPrimitiveValue(value, fieldType)
+            } else if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+                // Recursively apply to nested objects
+                result[key] = applyTypeConversionToObject(value, typeMap)
+            } else {
+                result[key] = value
+            }
+        }
+        return result
+    }
+
+    /**
+     * Converts a string value to the appropriate type based on uiType
+     * @param value - String value to convert
+     * @param uiType - Type information from parameter (e.g., 'integer', 'boolean', 'string')
+     * @param labelCacheMap - Optional map of datapill names to their types from the label cache
+     * @returns Properly typed value
+     */
+    function convertChildValueToType(value: string, uiType?: string, labelCacheMap?: Map<string, string>): unknown {
+        // Check if value contains datapills (either pure datapill or template expression)
+        if (value.includes('{{') && value.includes('}}')) {
+            if (value.startsWith('{{') && value.endsWith('}}')) {
+                // Pure datapill
+                return processPureDatapill(value, labelCacheMap)
+            }
+            // Template expression with datapills
+            return processTemplateExpression(value, labelCacheMap)
+        }
+
+        // Non-datapill value - convert based on type
+        return convertPrimitiveValue(value, uiType)
+    }
+
+    /**
+     * Extracts the element type from a parent entry for primitive arrays.
+     * Parses the complexObjectSchema from the parent's value to get child_type.
+     *
+     * @param parentEntry - Parent entry containing the schema information
+     * @returns Element type (e.g., 'integer', 'boolean', 'string') or undefined
+     */
+    function getArrayElementType(parentEntry: { value?: unknown }): string | undefined {
+        if (!parentEntry.value || typeof parentEntry.value !== 'string') {
+            return undefined
+        }
+
+        try {
+            const parsed = JSON.parse(parentEntry.value)
+            if (parsed.complexObjectSchema) {
+                // Find the $COCollectionField.$type_facets
+                for (const schemaKey in parsed.complexObjectSchema) {
+                    const schema = parsed.complexObjectSchema[schemaKey]
+                    if (schema && schema.$COCollectionField && schema['$COCollectionField.$type_facets']) {
+                        const typeFacets = schema['$COCollectionField.$type_facets']
+                        if (typeFacets.SimpleMapFacet) {
+                            const facetData = JSON.parse(typeFacets.SimpleMapFacet)
+                            return facetData.child_type
+                        }
+                    }
+                }
+            }
+        } catch {
+            // Ignore parsing errors
+        }
+        return undefined
+    }
+
+    /**
+     * Extracts type schema from a parent entry's complexObjectSchema.
+     * The schema contains nested field type information that can be used for type conversion.
+     *
+     * @param parentEntry - Parent entry containing the schema in its value field
+     * @returns Map of field paths to their types (e.g., 'timeout' -> 'integer')
+     */
+    function extractNestedTypeSchema(parentEntry: { value?: unknown }): Map<string, string> | undefined {
+        const typeMap = new Map<string, string>()
+
+        if (!parentEntry.value || typeof parentEntry.value !== 'string') {
+            return undefined
+        }
+
+        try {
+            const parsed = JSON.parse(parentEntry.value)
+            const complexObjectSchema = parsed.complexObjectSchema
+
+            if (!complexObjectSchema) {
+                return undefined
+            }
+
+            // Iterate through schema keys (e.g., "FlowDesigner:FD8fc76f46892b4980af21eb5f7b164ef2")
+            for (const schemaKey in complexObjectSchema) {
+                const schema = complexObjectSchema[schemaKey]
+                if (!schema || typeof schema !== 'object') {
+                    continue
+                }
+
+                // Extract field types from the schema
+                for (const fieldName in schema) {
+                    if (fieldName.endsWith('.$field_facets') || fieldName.endsWith('.$type_facets')) {
+                        continue
+                    }
+
+                    const fieldValue = schema[fieldName]
+
+                    // Check if this is a nested object with its own fields
+                    if (typeof fieldValue === 'object' && fieldValue !== null) {
+                        // Nested object - recursively extract types
+                        for (const nestedFieldName in fieldValue) {
+                            if (nestedFieldName.endsWith('.$field_facets')) {
+                                continue
+                            }
+                            const nestedType = fieldValue[nestedFieldName]
+                            if (typeof nestedType === 'string') {
+                                // Map nested field names (e.g., 'timeout' under 'settings')
+                                typeMap.set(nestedFieldName, nestedType.toLowerCase())
+                            }
+                        }
+                    } else if (typeof fieldValue === 'string') {
+                        // Direct type (e.g., "Integer", "Boolean", "String")
+                        typeMap.set(fieldName, fieldValue.toLowerCase())
+                    }
+                }
+            }
+
+            return typeMap.size > 0 ? typeMap : undefined
+        } catch {
+            // Ignore parsing errors
+            return undefined
+        }
+    }
+
+    /**
+     * Recursively parses children array to reconstruct nested objects and arrays
+     * @param children - Array of child entries with name, value, and optional nested children
+     * @param elementType - Type hint for array elements (e.g., 'string', 'integer')
+     * @param nestedTypeMap - Optional map of field names to types for nested FlowObjects
+     * @param complexObjectData - Optional complex object data for merging with children
+     * @param labelCacheMap - Optional map of datapill names to their types from the label cache
+     * @returns Reconstructed nested object or array
+     */
+    function parseChildrenArray(
+        children: unknown[],
+        elementType?: string,
+        nestedTypeMap?: Map<string, string>,
+        complexObjectData?: unknown,
+        labelCacheMap?: Map<string, string>
+    ): unknown {
+        if (!Array.isArray(children) || children.length === 0) {
+            return undefined
+        }
+
+        // Check if this is an array or object:
+        // - Array (SDK): all children have empty names
+        // - Array (UI): all children have the SAME non-empty name (childName repeated)
+        // - Object: children have different names (field names)
+        const childObj = children[0] as ChildEntry
+
+        const firstBaseName = getBaseName(childObj.name)
+
+        // Check if all children have the same base name (indicating FlowArray with repeated childName)
+        const allSameName =
+            children.length > 1 &&
+            children.every((c) => {
+                const entry = c as ChildEntry
+                return getBaseName(entry.name) === firstBaseName
+            })
+
+        // Check if the base name is empty (array elements without explicit names)
+        const hasEmptyBaseName = !firstBaseName || firstBaseName === ''
+
+        const isArray = hasEmptyBaseName || allSameName
+
+        if (isArray) {
+            // FlowArray: reconstruct array of elements
+            const result: unknown[] = []
+            for (const child of children) {
+                const childEntry = child as ChildEntry
+                if (childEntry.children && childEntry.children.length > 0) {
+                    // Nested object or array - get corresponding complexObject data for this element
+                    let elementComplexData: unknown | undefined
+                    if (Array.isArray(complexObjectData) && result.length < complexObjectData.length) {
+                        elementComplexData = complexObjectData[result.length]
+                    }
+                    result.push(
+                        parseChildrenArray(childEntry.children, undefined, undefined, elementComplexData, labelCacheMap)
+                    )
+                } else if (childEntry.value !== undefined && childEntry.value !== null && childEntry.value !== '') {
+                    // Primitive value - convert to proper type
+                    // Use parameter type if available, otherwise use passed elementType
+                    const uiType = childEntry.parameter?.type || elementType
+                    const convertedValue =
+                        typeof childEntry.value === 'string'
+                            ? convertChildValueToType(childEntry.value, uiType, labelCacheMap)
+                            : childEntry.value
+                    result.push(convertedValue)
+                } else if (Array.isArray(complexObjectData) && result.length < complexObjectData.length) {
+                    // Value is empty/null, try to get from complexObject
+                    result.push(complexObjectData[result.length])
+                }
+            }
+            return result
+        } else {
+            // FlowObject: reconstruct object with named fields
+            const result: { [key: string]: unknown } = {}
+
+            for (const child of children) {
+                const childEntry = child as ChildEntry
+                if (!childEntry.name) {
+                    continue
+                }
+                // Strip parent prefix from field name (e.g., "project.name" -> "name")
+                // This is needed for assignSubflowOutputs where names are prefixed with parent
+                const fieldName = getBaseName(childEntry.name)
+
+                if (childEntry.children && childEntry.children.length > 0) {
+                    // Nested object or array
+                    // Extract element type from parameter.type if this is an array (e.g., "array.integer" -> "integer")
+                    const childElementType = extractArrayElementType(childEntry.parameter?.type)
+
+                    // Extract nested complex object data for this field
+                    let nestedComplexData: unknown
+                    if (
+                        complexObjectData &&
+                        typeof complexObjectData === 'object' &&
+                        !Array.isArray(complexObjectData)
+                    ) {
+                        const objData = complexObjectData as { [key: string]: unknown }
+                        nestedComplexData = objData[fieldName]
+                    }
+
+                    // Extract type schema for this nested child
+                    // Try to get schema from the child entry itself, or fall back to parent's type map
+                    const childTypeMap = extractNestedTypeSchema(childEntry) || nestedTypeMap
+
+                    result[fieldName] = parseChildrenArray(
+                        childEntry.children,
+                        childElementType,
+                        childTypeMap,
+                        nestedComplexData,
+                        labelCacheMap
+                    )
+                } else if (childEntry.value !== undefined && childEntry.value !== null && childEntry.value !== '') {
+                    // Primitive value - convert to proper type
+                    // Try parameter type first, then nested type map, then no type
+                    const uiType = childEntry.parameter?.type || nestedTypeMap?.get(childEntry.name)
+                    const convertedValue =
+                        typeof childEntry.value === 'string'
+                            ? convertChildValueToType(childEntry.value, uiType, labelCacheMap)
+                            : childEntry.value
+                    result[fieldName] = convertedValue
+                } else if (
+                    complexObjectData &&
+                    typeof complexObjectData === 'object' &&
+                    !Array.isArray(complexObjectData)
+                ) {
+                    // No value in children, try to get from complexObject
+                    const objData = complexObjectData as { [key: string]: unknown }
+                    if (fieldName in objData) {
+                        const value = objData[fieldName]
+                        // Apply type conversion if we have type information
+                        const uiType = nestedTypeMap?.get(childEntry.name) || nestedTypeMap?.get(fieldName)
+                        if (typeof value === 'string' && uiType) {
+                            result[fieldName] = convertPrimitiveValue(value, uiType)
+                        } else {
+                            result[fieldName] = value
+                        }
+                    }
+                } else if (childEntry.parameter?.type && childEntry.parameter.type.startsWith('array')) {
+                    // Array field with no children or value - initialize as empty array
+                    result[fieldName] = []
+                }
+            }
+
+            // Merge any fields from complexObject that aren't in children
+            // This handles primitive arrays that are only in complexObject
+            if (complexObjectData && typeof complexObjectData === 'object' && !Array.isArray(complexObjectData)) {
+                const objData = complexObjectData as { [key: string]: unknown }
+                for (const key of Object.keys(objData)) {
+                    if (!(key in result)) {
+                        result[key] = objData[key]
+                    }
+                }
+            }
+
+            return result
+        }
+    }
+
+    /**
+     * Extracts plain values from ServiceNow's $cv wrapped format.
+     */
+    function extractComplexObjectValues(complexObject: unknown): unknown {
+        if (typeof complexObject !== 'object' || complexObject === null) {
+            return complexObject
+        }
+
+        const obj = complexObject as { $cv?: { $v?: unknown }; $COCollectionField?: unknown }
+        if (obj.$cv && '$v' in obj.$cv) {
+            return obj.$cv.$v
+        }
+
+        if (obj.$COCollectionField) {
+            return extractComplexObjectValues(obj.$COCollectionField)
+        }
+
+        if (Array.isArray(complexObject)) {
+            return complexObject.map((item) => extractComplexObjectValues(item))
+        }
+
+        const result: { [key: string]: unknown } = {}
+        for (const [key, value] of Object.entries(complexObject)) {
+            if (key === 'name$' || key === '$COCollectionField') {
+                continue
+            }
+            result[key] = extractComplexObjectValues(value)
+        }
+        return result
+    }
+
+    /**
+     * Reconstructs FlowObject/FlowArray from complexObjectSchema with mapped datapills.
+     * This handles the UI format where children array is empty but datapills are stored in facets.
+     */
+    function reconstructFromMappedFacets(schema: unknown, complexObject: unknown): unknown {
+        if (typeof schema !== 'object' || schema === null) {
+            return null
+        }
+
+        const schemaObj = schema as { [key: string]: unknown }
+        const typeKey = Object.keys(schemaObj).find((k) => k.startsWith('FlowDesigner:'))
+        if (!typeKey) {
+            return null
+        }
+
+        const template = schemaObj[typeKey]
+        if (typeof template !== 'object' || template === null) {
+            return null
+        }
+
+        const templateObj = template as { [key: string]: unknown }
+        const literalValues = extractComplexObjectValues(complexObject)
+        const mappings = extractMappingsFromFacets(templateObj)
+
+        if (mappings.size === 0) {
+            return literalValues
+        }
+
+        return applyMappingsToValues(literalValues, mappings)
+    }
+
+    /**
+     * Extracts datapill mappings from field facets in the schema template.
+     * Recursively searches through nested objects and arrays to find all $field_facets.
+     */
+    function extractMappingsFromFacets(template: { [key: string]: unknown }): Map<string, string> {
+        const mappings = new Map<string, string>()
+
+        function extractFromObject(obj: unknown): void {
+            if (typeof obj !== 'object' || obj === null) {
+                return
+            }
+
+            if (Array.isArray(obj)) {
+                for (const item of obj) {
+                    extractFromObject(item)
+                }
+                return
+            }
+
+            const objMap = obj as { [key: string]: unknown }
+            for (const key of Object.keys(objMap)) {
+                if (key.endsWith('.$field_facets')) {
+                    const facets = objMap[key]
+                    if (typeof facets !== 'object' || facets === null) {
+                        continue
+                    }
+
+                    const facetsObj = facets as { SimpleMapFacet?: string }
+                    const simpleMapFacetStr = facetsObj.SimpleMapFacet
+
+                    if (typeof simpleMapFacetStr === 'string') {
+                        try {
+                            const facetObj = JSON.parse(simpleMapFacetStr) as { mapped?: string }
+                            if (facetObj.mapped) {
+                                const mappedObj = JSON.parse(facetObj.mapped) as { [key: string]: string }
+                                for (const [path, datapill] of Object.entries(mappedObj)) {
+                                    mappings.set(path, stripDatapillTypeAnnotation(datapill))
+                                }
+                            }
+                        } catch {
+                            // Skip invalid facets
+                        }
+                    }
+                } else {
+                    // Recursively search nested objects
+                    extractFromObject(objMap[key])
+                }
+            }
+        }
+
+        extractFromObject(template)
+        return mappings
+    }
+
+    /**
+     * Applies datapill mappings to literal values by setting values at dotted paths.
+     */
+    function applyMappingsToValues(values: unknown, mappings: Map<string, string>): unknown {
+        const result = JSON.parse(JSON.stringify(values))
+
+        for (const [path, datapill] of mappings.entries()) {
+            setValueAtPath(result, path, datapill)
+        }
+
+        return result
+    }
+
+    /**
+     * Sets a value at a dotted path in an object/array structure.
+     * Handles array indices like "tasks[0].dueDate".
+     */
+    function setValueAtPath(obj: unknown, path: string, value: unknown): void {
+        const parts = path.split(/\.|\[|\]/).filter((p) => p !== '')
+        let current = obj as { [key: string]: unknown } | unknown[]
+
+        for (let i = 0; i < parts.length - 1; i++) {
+            const part = parts[i]
+            if (!part) {
+                continue
+            }
+            const nextPart = parts[i + 1]
+
+            if (nextPart && /^\d+$/.test(nextPart)) {
+                if (Array.isArray(current)) {
+                    const idx = Number.parseInt(part, 10)
+                    if (!current[idx]) {
+                        current[idx] = {}
+                    }
+                    current = current[idx] as { [key: string]: unknown } | unknown[]
+                } else {
+                    if (!Array.isArray(current[part])) {
+                        current[part] = []
+                    }
+                    current = current[part] as unknown[]
+                }
+            } else if (/^\d+$/.test(part)) {
+                const idx = Number.parseInt(part, 10)
+                if (Array.isArray(current)) {
+                    if (!current[idx]) {
+                        current[idx] = {}
+                    }
+                    current = current[idx] as { [key: string]: unknown }
+                }
+            } else {
+                if (Array.isArray(current)) {
+                    const idx = Number.parseInt(part, 10)
+                    if (!current[idx]) {
+                        current[idx] = {}
+                    }
+                    current = current[idx] as { [key: string]: unknown }
+                } else {
+                    if (typeof current[part] !== 'object' || current[part] === null) {
+                        current[part] = {}
+                    }
+                    current = current[part] as { [key: string]: unknown }
+                }
+            }
+        }
+
+        const lastPart = parts[parts.length - 1]
+        if (lastPart) {
+            if (/^\d+$/.test(lastPart)) {
+                const idx = Number.parseInt(lastPart, 10)
+                if (Array.isArray(current)) {
+                    current[idx] = value
+                }
+            } else {
+                if (!Array.isArray(current)) {
+                    current[lastPart] = value
+                }
+            }
+        }
+    }
+
+    /**
+     * Generic helper to parse an array of entries with name-value pairs into an object.
+     * Converts string values to appropriate types using type information from the schema.
+     *
+     * **Inline Script Support:**
+     * Detects entries with `scriptActive: true` and creates FDInlineScriptCallShape objects
+     * that represent `wfa.inlineScript('...')` calls in the generated Fluent code.
+     *
+     * **FlowObject/FlowArray Support:**
+     * Detects entries with non-empty `children` arrays and recursively parses them back
+     * into nested objects or arrays, reversing the buildChildrenArray operation.
+     *
+     * @param entries - Array of entries with name, value, and optional scriptActive/script properties
+     * @param typeMap - Optional map of names to their internal types for proper type conversion
+     * @param record - Optional source Record for creating FDInlineScriptCallShape with proper source
+     * @returns Object with names as keys and properly typed values or FDInlineScriptCallShape for inline scripts
+     */
+    function parseEntriesFromArray<
+        T extends {
+            name?: string
+            value?: unknown
+            scriptActive?: boolean
+            script?: { [key: string]: { scriptActive: boolean; script: string } }
+            children?: unknown[]
+        },
+    >(entries: T[], typeMap?: Map<string, string>, labelCacheMap?: Map<string, string>): { [key: string]: unknown } {
+        const result: { [key: string]: unknown } = {}
+
+        for (const entry of entries) {
+            if (!entry.name) {
+                continue
+            }
+
+            // Check if this is an inline script (matches flow-instance-plugin.ts pattern)
+            // Return script metadata that buildVariableOrOutputArguments will recognize
+            if (entry.scriptActive === true && entry.script) {
+                const scriptData = entry.script[entry.name]
+                if (scriptData?.script) {
+                    // Return metadata object (not a Shape) so it can be processed later
+                    result[entry.name] = {
+                        scriptActive: true,
+                        scriptContent: scriptData.script,
+                    }
+                    continue
+                }
+            }
+
+            // Check if this entry has children (FlowObject/FlowArray)
+            if (entry.children && Array.isArray(entry.children) && entry.children.length > 0) {
+                // Special case: empty arrays are represented as a single child with empty string value
+                // Empty arrays have: no name, empty string value, and undefined children (not empty array)
+                // Arrays with objects (like [{item: ''}]) have children with names and/or children arrays
+                const firstChild = entry.children[0] as { name?: string; value?: string; children?: unknown[] }
+                const isEmptyArray =
+                    entry.children.length === 1 &&
+                    firstChild.value === '' &&
+                    !firstChild.name && // Empty arrays have no name on the child element
+                    firstChild.children === undefined // Empty arrays have undefined children, not empty array
+
+                if (isEmptyArray) {
+                    result[entry.name] = []
+                    continue
+                }
+
+                // If parent value is a datapill (pure or template expression), use it directly and ignore children
+                // This handles the case where a datapill is assigned to a FlowObject variable
+                // Check for datapills: starts with {{ (pure datapill) or contains {{ but not starting with { (template expression)
+                const isDatapillValue =
+                    entry.value &&
+                    typeof entry.value === 'string' &&
+                    (entry.value.startsWith('{{') ||
+                        (entry.value.includes('{{') && entry.value.includes('}}') && !entry.value.startsWith('{')))
+
+                if (isDatapillValue) {
+                    const uiType = typeMap?.get(entry.name)
+                    const convertedValue = convertChildValueToType(entry.value as string, uiType, labelCacheMap)
+                    result[entry.name] = convertedValue
+                    continue
+                }
+
+                // Try to extract actual values from complexObject field if available
+                if (entry.value && typeof entry.value === 'string' && !childrenContainDatapills(entry.children)) {
+                    try {
+                        const parsed = JSON.parse(entry.value)
+                        if (parsed.complexObject) {
+                            const extractedValue = extractComplexObjectValues(parsed.complexObject)
+
+                            // Apply type conversion using schema information
+                            const nestedTypeMap = extractNestedTypeSchema(entry)
+                            if (
+                                nestedTypeMap &&
+                                typeof extractedValue === 'object' &&
+                                extractedValue !== null &&
+                                !Array.isArray(extractedValue)
+                            ) {
+                                // For FlowObject, apply type conversion to each field (including nested objects)
+                                result[entry.name] = applyTypeConversionToObject(extractedValue, nestedTypeMap)
+                            } else {
+                                result[entry.name] = extractedValue
+                            }
+                            continue
+                        }
+                    } catch {
+                        // Fall through to children parsing
+                    }
+                }
+
+                // Fallback: Parse structure from children array
+                // Extract complexObject data if available for merging with children
+                let complexObjData: unknown
+                if (entry.value && typeof entry.value === 'string') {
+                    try {
+                        const parsed = JSON.parse(entry.value)
+                        if (parsed.complexObject) {
+                            complexObjData = extractComplexObjectValues(parsed.complexObject)
+                        }
+                    } catch {
+                        // Ignore parse errors
+                    }
+                }
+                const elementType = getArrayElementType(entry)
+                const nestedTypeMap = extractNestedTypeSchema(entry)
+                const parsedValue = parseChildrenArray(
+                    entry.children,
+                    elementType,
+                    nestedTypeMap,
+                    complexObjData,
+                    labelCacheMap
+                )
+                result[entry.name] = parsedValue
+                continue
+            }
+
+            // Handle UI format: children empty but complexObjectSchema has mapped datapills in facets
+            if (entry.value && typeof entry.value === 'string') {
+                try {
+                    const parsed = JSON.parse(entry.value)
+                    if (parsed.complexObjectSchema && parsed.complexObject) {
+                        // Extract datapills from mapped facets and merge with literal values
+                        const reconstructed = reconstructFromMappedFacets(
+                            parsed.complexObjectSchema,
+                            parsed.complexObject
+                        )
+                        if (reconstructed !== null) {
+                            result[entry.name] = reconstructed
+                            continue
+                        }
+                    }
+                } catch {
+                    // Fall through to regular value handling
+                }
+            }
+
+            // Handle regular values (non-inline-script)
+            if (entry.value !== undefined && entry.value !== null) {
+                // Get the type for this entry from the schema
+                const uiType = typeMap?.get(entry.name)
+
+                // Strip type annotation from datapill strings before normalization
+                // ServiceNow stores datapills with type annotations like {{trigger.name|string}}
+                const valueStr = String(entry.value)
+                const cleanedValue = stripDatapillTypeAnnotation(valueStr)
+
+                // Use normalizeInputValue to handle type conversion
+                // This converts:
+                // - "true"/"false" → boolean (when uiType is 'boolean')
+                // - "1"/"0" → true/false (when uiType is 'boolean')
+                // - "123" → number
+                // - JSON strings → parsed objects
+                // - Datapills like "{{trigger.name}}" → kept as string (for later conversion)
+                const normalizedValue = normalizeInputValue(cleanedValue, uiType)
+                result[entry.name] = normalizedValue
+            }
+        }
+
+        return result
+    }
+}
+
+/**
+ * Helper function to check if children array contains any datapill values.
+ * Datapills are indicated by {{...}} syntax in the value field.
+ *
+ * @param children - The children array to check
+ * @returns true if any child has a datapill value
+ */
+export function childrenContainDatapills(children: unknown[]): boolean {
+    for (const child of children) {
+        if (typeof child === 'object' && child !== null) {
+            const childObj = child as { value?: string; children?: unknown[] }
+
+            // Check if this child has a datapill value (pure datapill or template expression)
+            if (childObj.value && typeof childObj.value === 'string') {
+                // Check for pure datapill or template expression containing datapills
+                if (childObj.value.includes('{{') && childObj.value.includes('}}')) {
+                    return true
+                }
+            }
+
+            // Recursively check nested children
+            if (childObj.children && Array.isArray(childObj.children) && childObj.children.length > 0) {
+                if (childrenContainDatapills(childObj.children)) {
+                    return true
+                }
+            }
+        }
+    }
+    return false
+}
+
+// Type guard functions for each shape type
+export function isConditionalLogicShape(expr: FlowLogicInstanceShape): expr is ConditionalLogicInstanceShape {
+    return [FLOW_LOGIC.IF, FLOW_LOGIC.ELSEIF, FLOW_LOGIC.ELSE].includes(expr.getCallee() as FLOW_LOGIC)
+}
+
+export function isForEachShape(expr: FlowLogicInstanceShape): expr is ForEachInstanceShape {
+    return expr.getCallee() === FLOW_LOGIC.FOR_EACH
+}
+
+export function isGoBackToShape(expr: FlowLogicInstanceShape): expr is GoBackToInstanceShape {
+    return expr.getCallee() === FLOW_LOGIC.GOBACKTO
+}
+
+export function isTryCatchShape(expr: FlowLogicInstanceShape): expr is TryCatchInstanceShape {
+    return expr.getCallee() === FLOW_LOGIC.TRY_CATCH
+}
+
+export function isDoInParallelShape(expr: FlowLogicInstanceShape): expr is DoInParallelInstanceShape {
+    return expr.getCallee() === FLOW_LOGIC.DO_IN_PARALLEL
+}
+
+export function isSetFlowVariablesShape(expr: FlowLogicInstanceShape): expr is SetFlowVariablesInstanceShape {
+    return expr.getCallee() === FLOW_LOGIC.SET_FLOW_VARIABLES
+}
+
+export function isAssignSubflowOutputsShape(expr: FlowLogicInstanceShape): expr is AssignSubflowOutputsInstanceShape {
+    return expr.getCallee() === FLOW_LOGIC.ASSIGN_SUBFLOW_OUTPUTS
+}
+
+/**
+ * Checks if a shape is a datapill shape (PropertyAccessShape, TemplateExpressionShape, IdentifierShape, PillShape, or PillTemplateShape)
+ */
+export function isDataPillShape(shape: Shape): boolean {
+    return (
+        shape instanceof PropertyAccessShape ||
+        shape instanceof TemplateExpressionShape ||
+        shape instanceof IdentifierShape ||
+        shape instanceof PillShape ||
+        shape instanceof PillTemplateShape
+    )
+}
+
+/**
+ * Recursively resolves datapills in nested values (for FlowObjects/FlowArrays).
+ *
+ * @param value - The value to resolve datapills in
+ * @param transform - Transform context for shape conversion
+ * @returns Resolved value with datapills replaced
+ */
+async function resolveNestedDataPills(value: unknown, transform: Transform): Promise<unknown> {
+    // Handle datapill shapes
+    if (value instanceof Shape && isDataPillShape(value)) {
+        return await resolveDataPillShape(
+            value as PropertyAccessShape | TemplateExpressionShape | IdentifierShape | PillShape,
+            transform
+        )
+    }
+
+    // Handle ObjectShape - need to resolve its entries
+    if (value instanceof Shape && (value.isObject() || value.is(DurationShape))) {
+        const objectShape = value.isObject()
+            ? value.asObject()
+            : Shape.from(value.getSource(), value.as(DurationShape).getDuration()).asObject()
+        const resolvedObj: { [key: string]: unknown } = {}
+        const entries = objectShape.entries({ resolve: false })
+        for (const [key, shape] of entries) {
+            resolvedObj[key] = await resolveNestedDataPills(shape, transform)
+        }
+        return resolvedObj
+    }
+
+    // Handle ArrayShape - need to resolve its elements
+    if (value instanceof Shape && value.isArray()) {
+        const arrayShape = value.asArray()
+        const resolvedArray: unknown[] = []
+        // IMPORTANT: Use getElements(false) to prevent premature resolution of CallExpressionShapes
+        const elements = arrayShape.getElements(false)
+        for (const element of elements) {
+            if (element === undefined) {
+                continue
+            }
+            resolvedArray.push(await resolveNestedDataPills(element, transform))
+        }
+        return resolvedArray
+    }
+
+    // Handle CallExpressionShape for wfa.dataPill() - convert to pill string
+    if (value instanceof Shape && value.is(CallExpressionShape)) {
+        const callExpr = value.as(CallExpressionShape)
+        if (callExpr.getCallee() === 'wfa.dataPill') {
+            // The first argument is a PropertyAccessShape (e.g., params.inputs.inputString)
+            // The second argument is the type hint (e.g., 'string', 'integer')
+            const firstArg = callExpr.getArgument(0)
+            const secondArg = callExpr.getArgument(1)
+
+            if (firstArg && firstArg.is(PropertyAccessShape)) {
+                // Extract the pill components from PropertyAccessShape
+                const propAccess = firstArg.as(PropertyAccessShape)
+                const elements = propAccess.getElements()
+
+                if (elements.length >= 2) {
+                    const propertyNames: string[] = []
+                    elements.forEach((element) => {
+                        if (element.is(IdentifierShape)) {
+                            propertyNames.push(element.as(IdentifierShape).getName())
+                        }
+                    })
+
+                    // Use the same logic as DataPillPlugin to determine root identifier and path
+                    const { rootIdentifier, pathStr } = determineRootIdentifierAndPath(
+                        propertyNames,
+                        // We don't have diagnostics here, casting through unknown to satisfy the type
+                        // The function will return null values if this object is used
+                        {} as unknown as Diagnostics,
+                        propAccess
+                    )
+
+                    // Get type hint if provided
+                    let typePart = ''
+                    if (secondArg && secondArg.isString()) {
+                        const typeHint = secondArg.asString().getValue()
+                        typePart = `|${typeHint}`
+                    }
+
+                    // Return pill format: {{rootIdentifier.path|type}}
+                    if (rootIdentifier) {
+                        return pathStr
+                            ? `{{${rootIdentifier}.${pathStr}${typePart}}}`
+                            : `{{${rootIdentifier}${typePart}}}`
+                    }
+                }
+            }
+
+            // If already converted to PillShape or try normal resolution
+            if (firstArg && isDataPillShape(firstArg)) {
+                return await resolveDataPillShape(
+                    firstArg as PropertyAccessShape | TemplateExpressionShape | IdentifierShape | PillShape,
+                    transform
+                )
+            }
+        }
+    }
+
+    // Extract value from other Shape types
+    if (value instanceof Shape) {
+        value = value.getValue()
+    }
+
+    // Recursively handle arrays
+    if (Array.isArray(value)) {
+        const resolvedArray: unknown[] = []
+        for (const element of value) {
+            // Skip undefined elements
+            if (element === undefined) {
+                continue
+            }
+            resolvedArray.push(await resolveNestedDataPills(element, transform))
+        }
+        return resolvedArray
+    }
+
+    // Recursively handle objects
+    if (typeof value === 'object' && value !== null) {
+        const resolvedObj: { [key: string]: unknown } = {}
+        for (const [key, val] of Object.entries(value)) {
+            // Skip undefined values
+            if (val === undefined) {
+                continue
+            }
+            resolvedObj[key] = await resolveNestedDataPills(val, transform)
+        }
+        return resolvedObj
+    }
+
+    // Return primitive values as-is
+    return value
+}
+
+/**
+ * Processes inline scripts in flow logic values (setFlowVariables, assignSubflowOutputs).
+ * Follows the same pattern as checkAndResolveInlineScripts() in flow-instance-plugin.ts.
+ *
+ * @param config - The ObjectShape containing config properties
+ * @returns Array of [key, value] tuples where inline scripts are serialized
+ */
+function processInlineScriptsInFlowLogic(config: ObjectShape): Array<[string, unknown]> {
+    const entries = config.entries({ resolve: false })
+    const results: [string, unknown][] = []
+
+    for (const [key, shape] of entries) {
+        // Handle wfa.inlineScript() calls
+        if (shape instanceof FDInlineScriptCallShape) {
+            const scriptContent = shape.getScriptContent()
+            // Wrap in TemplateExpressionShape for proper serialization
+            const templateShape = new TemplateExpressionShape({
+                source: shape,
+                literalText: scriptContent,
+            })
+            // Create InlineScriptShape for Flow Designer serialization
+            const inlineScript = new InlineScriptShape({
+                source: templateShape,
+                scriptContent,
+            })
+            // Convert to Flow Designer JSON format
+            const scriptValue = inlineScript.toFlowDesignerJson(key)
+            results.push([key, scriptValue])
+        }
+    }
+
+    return results
+}
+
+/**
+ * Resolves datapills and inline scripts in flow logic config properties.
+ * Similar to prepareActionInstanceValueJson() in flow-instance-plugin.ts.
+ *
+ * @param config - The ObjectShape containing config properties
+ * @param transform - Transform context for shape conversion
+ * @param diagnostics - Diagnostics for reporting errors
+ * @returns ObjectShape with resolved datapill and inline script values
+ */
+async function resolveConfigDataPills(
+    config: ObjectShape,
+    transform: Transform,
+    diagnostics: Diagnostics
+): Promise<ObjectShape> {
+    const entries = config.entries({ resolve: false })
+    const dataPillProps: { [key: string]: unknown } = {}
+
+    // Step 1: Resolve datapills (including nested datapills in FlowObject/FlowArray values)
+    for (const [key, shape] of entries) {
+        // Validate: annotation field must not contain datapills or inline scripts
+        if (key === 'annotation' && (isDataPillShape(shape) || shape instanceof FDInlineScriptCallShape)) {
+            diagnostics.error(
+                shape,
+                'Datapills and inline scripts are not allowed in the annotation field. Please use a static string value.'
+            )
+            // Still extract the value to continue processing
+            dataPillProps[key] = shape.getValue()
+            continue
+        }
+
+        if (isDataPillShape(shape)) {
+            dataPillProps[key] = await resolveDataPillShape(
+                shape as PropertyAccessShape | TemplateExpressionShape | IdentifierShape | PillShape,
+                transform
+            )
+        } else {
+            // Recursively resolve nested datapills in FlowObject/FlowArray values
+            dataPillProps[key] = await resolveNestedDataPills(shape, transform)
+        }
+    }
+
+    // Step 2: Process inline scripts (wfa.inlineScript() calls)
+    // This serializes inline scripts into Flow Designer JSON format with scriptActive: true
+    const inlineScriptResults = processInlineScriptsInFlowLogic(config)
+    const inlineScriptMap = new Map(inlineScriptResults)
+
+    // Step 3: Replace raw inline script strings with their serialized JSON objects
+    // For fields with inline scripts: replace the raw string from Step 1 with the properly
+    // serialized Flow Designer JSON object from Step 2. All other fields remain unchanged.
+    const mergedProps: { [key: string]: unknown } = {}
+    for (const [key, value] of Object.entries(dataPillProps)) {
+        mergedProps[key] = inlineScriptMap.has(key) ? inlineScriptMap.get(key) : value
+    }
+
+    return Shape.from(config.getSource(), mergedProps).asObject()
+}
+
+/**
+ * Extracts the appropriate data from different flow logic shape types.
+ * Resolves datapills in config properties for If, ElseIf, Else, ForEach, and WaitForADuration.
+ */
+async function extractDataFromShape(
+    expr: FlowLogicInstanceShape,
+    transform: Transform,
+    diagnostics: Diagnostics
+): Promise<ObjectShape | Record | StringShape> {
+    // Use a more elegant approach with early returns for each shape type
+    if (isGoBackToShape(expr)) {
+        return expr.getStep()
+    }
+
+    if (isSetFlowVariablesShape(expr)) {
+        const variablesToSet = expr.getVariablesToSet()
+        return await resolveConfigDataPills(variablesToSet, transform, diagnostics)
+    }
+
+    if (isAssignSubflowOutputsShape(expr)) {
+        const assignedSubflowOutputs = expr.getAssignedSubflowOutputs()
+        return await resolveConfigDataPills(assignedSubflowOutputs, transform, diagnostics)
+    }
+
+    if (isForEachShape(expr)) {
+        // Check if argument 0 (items) is a PropertyAccessShape before processing
+        const itemsArg = expr.getArgument(0, false)
+        if (itemsArg?.is(PropertyAccessShape)) {
+            const items = expr.getItems()
+            const itemString = await resolveDataPillShape(items, transform)
+            return Shape.from(expr, itemString).asString()
+        }
+        // If not a PropertyAccessShape (e.g., StringLiteralShape when no data pill assigned),
+        // return empty string instead of falling through to default case (which returns ObjectShape)
+        return Shape.from(expr, '').asString()
+    }
+
+    // For conditional logic (If/ElseIf/Else) and WAIT_FOR_A_DURATION, resolve datapills in config
+    const logicType = expr.getCallee() as FLOW_LOGIC
+    if (isConditionalLogicShape(expr) || logicType === FLOW_LOGIC.WAIT_FOR_A_DURATION) {
+        const config = expr.getConfig()
+        return await resolveConfigDataPills(config, transform, diagnostics)
+    }
+
+    // Default case: extract config as-is for other shape types
+    return expr.getConfig()
+}
+
+/**
+ * Main function to process flow logic instances and build records
+ */
+export async function getFlowLogicInstanceRecord(
+    expr: FlowLogicInstanceShape,
+    context: { diagnostics: Diagnostics; transform: Transform; factory: Factory }
+): Promise<Result<Record>> {
+    const { diagnostics, transform, factory } = context
+    const logicType = expr.getCallee() as FLOW_LOGIC
+
+    // Validate flow logic context
+    const diagnosticError = validateFlowLogic(expr, diagnostics)
+    if (diagnosticError) {
+        diagnostics.error(expr, diagnosticError)
+        return { success: false }
+    }
+
+    // Extract data based on shape type using type-specific extractors
+    const data = await extractDataFromShape(expr, transform, diagnostics)
+    // Note: childName for arrays is now handled in resolveComplexInput within postProcess functions
+    const values = FlowLogicValueProcessor.prepare(logicType, data)
+    let instanceRecord: Record = await buildFlowLogicInstanceRecord(expr, factory, values)
+
+    if (isAssignSubflowOutputsShape(expr)) {
+        instanceRecord = instanceRecord.merge({
+            outputs_assigned: expr.getAssignedSubflowOutputsAsString(),
+        })
+    }
+
+    if (isSetFlowVariablesShape(expr)) {
+        instanceRecord = instanceRecord.merge({
+            flow_variables_assigned: expr.getVariablesToSetAsString(),
+        })
+    }
+
+    instanceRecord = instanceRecord.merge({
+        values: values,
+    })
+    // Handle sibling connections for conditional logic types
+    if (requiresSiblingValidation(logicType)) {
+        const siblingResult = await handleSiblingConnection(expr, transform, diagnostics)
+        if (!siblingResult.success) {
+            return siblingResult
+        }
+        if (siblingResult.value.connectedTo) {
+            instanceRecord = instanceRecord.merge({
+                connected_to: siblingResult.value.connectedTo,
+                values: values,
+            })
+        }
+    }
+
+    return { success: true, value: instanceRecord }
+}
+
+function requiresSiblingValidation(logicType: FLOW_LOGIC): boolean {
+    return [FLOW_LOGIC.IF, FLOW_LOGIC.ELSEIF, FLOW_LOGIC.ELSE].includes(logicType)
+}
+
+async function handleSiblingConnection(
+    expr: FlowLogicInstanceShape,
+    transform: Transform,
+    diagnostics: Diagnostics
+): Promise<Result<{ connectedTo?: string }>> {
+    const sibling = expr
+        .getOriginalNode()
+        .getParent()
+        ?.getPreviousSibling((node) => !ts.Node.isCommentStatement(node))
+        ?.asKind(ts.SyntaxKind.ExpressionStatement)
+        ?.getExpression()
+        .asKind(ts.SyntaxKind.CallExpression)
+
+    const siblingError = validateSibling(expr, sibling)
+    if (siblingError) {
+        diagnostics.error(expr, siblingError)
+        return { success: false }
+    }
+
+    const logicType = expr.getCallee() as FLOW_LOGIC
+    if (sibling && (logicType === FLOW_LOGIC.ELSE || logicType === FLOW_LOGIC.ELSEIF)) {
+        const siblingRecord = await transform.toRecord(sibling)
+        if (siblingRecord.success) {
+            return { success: true, value: { connectedTo: siblingRecord.value.get('ui_id').asString().getValue() } }
+        }
+    }
+
+    return { success: true, value: {} }
+}
+
+type FlowLogicArgumentBuilder = (record: Record, logicBodyShapes: Shape[], database: Database) => Shape<unknown>[]
+
+const FLOW_LOGIC_ARGUMENT_BUILDERS: { [K in FLOW_LOGIC]: FlowLogicArgumentBuilder } = {
+    [FLOW_LOGIC.GOBACKTO]: (record, _, database) => {
+        const stepId = FlowLogicValueProcessor.parse(
+            FLOW_LOGIC.GOBACKTO,
+            record.get('values').asString().getValue()
+        ) as string
+
+        const stepRecord =
+            database.get('sys_hub_action_instance_v2', { ui_id: stepId, flow: record.get('flow').getValue() }) ||
+            database.get('sys_hub_sub_flow_instance_v2', { ui_id: stepId, flow: record.get('flow').getValue() }) ||
+            database.get('sys_hub_flow_logic_instance_v2', { ui_id: stepId, flow: record.get('flow').getValue() })
+
+        if (!stepRecord) {
+            throw new Error(`Step with id ${stepId} not found`)
+        }
+
+        // Target step validation is now handled during FlowLogicInstanceShape.toRecord phase
+        // No validation needed here anymore
+
+        const firstArg = new ObjectShape({
+            source: record,
+            properties: {
+                annotation: record.get('comment').asString().getValue(),
+                $id: NowIdShape.from(record),
+            },
+        })
+
+        const source = stepRecord.getSource()
+        if (source instanceof CallExpressionShape) {
+            const identifier = stepRecord
+                .getOriginalNode()
+                ?.getFirstAncestorByKind(ts.SyntaxKind.VariableDeclaration)
+                ?.getNameNode()
+
+            if (identifier) {
+                return [
+                    firstArg,
+                    new IdentifierShape({
+                        source: record,
+                        name: identifier.getText(),
+                    }),
+                ]
+            }
+        }
+
+        return [firstArg, Shape.from(record, stepId)]
+    },
+
+    [FLOW_LOGIC.IF]: buildConditionalArguments,
+    [FLOW_LOGIC.ELSEIF]: buildConditionalArguments,
+    [FLOW_LOGIC.ELSE]: buildConditionalArguments,
+    [FLOW_LOGIC.ENDFLOW]: buildBasicArguments,
+    [FLOW_LOGIC.EXITLOOP]: buildBasicArguments,
+    [FLOW_LOGIC.SKIP_ITERATION]: buildBasicArguments,
+    [FLOW_LOGIC.WAIT_FOR_A_DURATION]: buildWaitForADurationArguments,
+    [FLOW_LOGIC.FOR_EACH]: buildForEachArguments,
+    [FLOW_LOGIC.DO_IN_PARALLEL]: buildBasicArguments,
+    [FLOW_LOGIC.TRY_CATCH]: buildBasicArguments,
+    [FLOW_LOGIC.SET_FLOW_VARIABLES]: buildSetFlowVariablesArguments,
+    [FLOW_LOGIC.ASSIGN_SUBFLOW_OUTPUTS]: buildAssignSubflowOutputsArguments,
+}
+
+/**
+ * Generic helper to build arguments for flow logic operations that follow the pattern:
+ * (config, schema, values)
+ *
+ * This pattern is used by SetFlowVariables and AssignSubflowOutputs.
+ *
+ * @param record - ServiceNow sys_hub_flow_logic_instance_v2 record
+ * @param database - Database to query for type information
+ * @param tableName - Table name to query for schema records (e.g., 'sys_hub_flow_variable', 'sys_hub_flow_output')
+ * @param flowLogicType - Flow logic type for parsing (e.g., FLOW_LOGIC.SET_FLOW_VARIABLES)
+ * @param schemaRef - Schema reference string (e.g., '{{flowVariables}}', '{{outputs}}')
+ * @returns Array of three Shape arguments
+ */
+function buildVariableOrOutputArguments(
+    record: Record,
+    database: Database,
+    tableName: string,
+    flowLogicType: FLOW_LOGIC,
+    schemaRef: string
+): Shape<unknown>[] {
+    const comment = record.get('comment').asString().getValue()
+    const valuesString = record.get('values').asString().getValue()
+    const flowId = record.get('flow').asString().getValue()
+
+    // Get flow definition and extract type information from schema
+    const typeMap = new Map<string, string>()
+    let labelCacheMap: Map<string, string> | undefined
+    const flowRecord = database.get('sys_hub_flow', flowId)
+
+    if (flowRecord) {
+        // Get the schema records that belong to this flow
+        const schemaRecords = database.query(tableName).filter((v) => v.get('model').getValue() === flowId)
+
+        for (const schemaRecord of schemaRecords) {
+            const name = schemaRecord.get('element').asString().getValue()
+            const internalType = schemaRecord.get('internal_type').asString().getValue()
+            typeMap.set(name, internalType)
+        }
+
+        // Extract label cache from flow record for datapill type preservation
+        try {
+            const labelCacheValue = flowRecord.get('label_cache')?.getValue()
+            if (labelCacheValue && typeof labelCacheValue === 'string') {
+                // Parse label cache JSON and create name->type map
+                const labelCacheEntries = JSON.parse(labelCacheValue) as Array<{ name: string; type: string }>
+                labelCacheMap = new Map<string, string>()
+                for (const entry of labelCacheEntries) {
+                    if (entry.name && entry.type) {
+                        labelCacheMap.set(entry.name, entry.type)
+                    }
+                }
+            }
+        } catch {
+            // If label cache extraction fails, continue without it
+            labelCacheMap = undefined
+        }
+    }
+
+    // Parse the values from the gzipped string with type conversion
+    // Returns object with properly typed values, inline script markers, or datapill strings
+    const parsedData = FlowLogicValueProcessor.parse(flowLogicType, valuesString, typeMap, labelCacheMap) as {
+        [key: string]: unknown
+    }
+
+    // Build the config object (first argument)
+    const configArg = new ObjectShape({
+        source: record,
+        properties: {
+            ...(comment ? { annotation: comment } : {}),
+            $id: NowIdShape.from(record),
+        },
+    })
+
+    // Second argument: schema reference ({{flowVariables}} or {{outputs}})
+    // Keep as string - will be transformed to PropertyAccessShape by datapill transformer
+    // The transformer will use the actual parameter name from the arrow function context
+    const schemaArg = Shape.from(record, schemaRef)
+
+    // Build the values object (third argument)
+    // Process inline scripts and create FDInlineScriptCallShape (matching action plugin pattern)
+    const valueProperties: { [key: string]: Shape } = {}
+    for (const [key, value] of Object.entries(parsedData)) {
+        // Check for inline script (has scriptActive and scriptContent from XML)
+        if (value && typeof value === 'object' && 'scriptActive' in value && 'scriptContent' in value) {
+            // Create FDInlineScriptCallShape for inline scripts (same as actions)
+            const script = value as { scriptActive: boolean; scriptContent: string }
+            valueProperties[key] = new FDInlineScriptCallShape({
+                source: record,
+                scriptContent: script.scriptContent,
+            })
+        } else {
+            // Primitive value or string - convert using Shape.from()
+            valueProperties[key] = Shape.from(record, value)
+        }
+    }
+
+    const valuesArg = new ObjectShape({
+        source: record,
+        properties: valueProperties,
+    })
+
+    return [configArg, schemaArg, valuesArg]
+}
+
+/**
+ * Builds arguments for SetFlowVariables when converting XML to Fluent.
+ * Creates the three arguments required by the SetFlowVariables API:
+ * 1. Config object with $id and optional annotation
+ * 2. Schema reference (placeholder for params.flowVariables)
+ * 3. Values object with variable assignments
+ *
+ * **Type Conversion Pipeline:**
+ * XML (gzipped) → parse() → normalizeInputValue(with type) → typed values → Shape.from() → Shapes
+ *
+ * **Example:**
+ * ```typescript
+ * // XML: { variables: [{ name: "count", value: "123" }, { name: "active", value: "1" }] }
+ * // Result: SetFlowVariables({ $id: ... }, params.flowVariables, { count: 123, active: true })
+ * ```
+ *
+ * @param record - ServiceNow sys_hub_flow_logic_instance_v2 record
+ * @param _logicBodyShapes - Unused parameter (required by FlowLogicArgumentBuilder interface)
+ * @param database - Database to query for flow variable schemas
+ * @returns Array of three Shape arguments for SetFlowVariables call
+ */
+function buildSetFlowVariablesArguments(
+    record: Record,
+    _logicBodyShapes: Shape[],
+    database: Database
+): Shape<unknown>[] {
+    return buildVariableOrOutputArguments(
+        record,
+        database,
+        'sys_hub_flow_variable',
+        FLOW_LOGIC.SET_FLOW_VARIABLES,
+        '{{flowVariables}}'
+    )
+}
+
+/**
+ * Builds arguments for AssignSubflowOutputs when converting XML to Fluent.
+ * Creates the three arguments required by the AssignSubflowOutputs API:
+ * 1. Config object with $id and optional annotation
+ * 2. Schema reference (placeholder for params.outputs or subflow outputs schema)
+ * 3. Values object with output assignments
+ *
+ * **Type Conversion Pipeline:**
+ * XML (gzipped) → parse() → normalizeInputValue(with type) → typed values → Shape.from() → Shapes
+ *
+ * **Example:**
+ * ```typescript
+ * // XML: { outputsToAssign: [{ name: "result", value: "success" }, { name: "isComplete", value: "1" }] }
+ * // Result: AssignSubflowOutputs({ $id: ... }, params.outputs, { result: "success", isComplete: true })
+ * ```
+ *
+ * @param record - ServiceNow sys_hub_flow_logic_instance_v2 record
+ * @param _logicBodyShapes - Unused parameter (required by FlowLogicArgumentBuilder interface)
+ * @param database - Database to query for subflow output schemas
+ * @returns Array of three Shape arguments for AssignSubflowOutputs call
+ */
+function buildAssignSubflowOutputsArguments(
+    record: Record,
+    _logicBodyShapes: Shape[],
+    database: Database
+): Shape<unknown>[] {
+    return buildVariableOrOutputArguments(
+        record,
+        database,
+        'sys_hub_flow_output',
+        FLOW_LOGIC.ASSIGN_SUBFLOW_OUTPUTS,
+        '{{outputs}}'
+    )
+}
+
+function buildBasicArguments(record: Record): Shape<unknown>[] {
+    return [
+        new ObjectShape({
+            source: record,
+            properties: {
+                annotation: record.get('comment').asString().getValue(),
+                $id: NowIdShape.from(record),
+            },
+        }),
+    ]
+}
+
+function buildWaitForADurationArguments(
+    record: Record,
+    _logicBodyShapes: Shape[],
+    database: Database
+): Shape<unknown>[] {
+    const zippedInputs = record.get('values').asString().getValue()
+    const logicDefinitionId = record.get('logic_definition').asString().getValue()
+    const logicDefinition = database.get('sys_hub_flow_logic_definition', logicDefinitionId)
+
+    const definitionInputs = logicDefinition
+        ?.flat()
+        .filter((v): v is Record => v.is(Record) && v.getTable() === 'sys_hub_flow_logic_input')
+
+    const inputsShape = buildInputsShapeFromZipped({
+        zippedInputs,
+        definitionInputs,
+        record,
+    })
+
+    const comment = record.get('comment').asString().getValue()
+    const uuid = record.get('ui_id').asString().getValue()
+
+    // Get properties from inputsShape (which is now an ObjectShape)
+    // Use entries({ resolve: false }) to preserve shape types (DurationShape, etc.)
+    const inputProperties = inputsShape ? Object.fromEntries(inputsShape.entries({ resolve: false })) : {}
+
+    const mergedProperties = {
+        ...(comment ? { annotation: comment } : {}),
+        $id: NowIdShape.from(record),
+        ...(uuid ? { uuid } : {}),
+        ...inputProperties,
+    }
+
+    const finalArg = new ObjectShape({
+        source: record,
+        properties: mergedProperties,
+    })
+
+    return [finalArg]
+}
+
+function buildConditionalArguments(record: Record, logicBodyShapes: Shape[]): Shape<unknown>[] {
+    const logicName = FlowLogicSysId.getLogicName(record.get('logic_definition').asString().getValue()) as FLOW_LOGIC
+    const valuesJson = FlowLogicValueProcessor.parse(logicName, record.get('values').asString().getValue()) as {
+        condition?: string
+        label?: string
+    }
+
+    const properties = {
+        ...valuesJson,
+        annotation: record.get('comment').asString().getValue(),
+        $id: NowIdShape.from(record),
+    }
+
+    const firstArg = new ObjectShape({ source: record, properties })
+    return [
+        firstArg,
+        new ArrowFunctionShape({
+            source: record,
+            parameters: [],
+            statements: logicBodyShapes,
+        }),
+    ]
+}
+
+/**
+ * Builds arguments for ForEach flow logic from XML record.
+ * Converts XML structure back to Fluent ForEach syntax.
+ *
+ * @param record - The sys_hub_flow_logic_instance_v2 record
+ * @param logicBodyShapes - The child shapes that form the loop body
+ * @returns Array of shapes: [items, config, body]
+ *
+ * @example
+ * // XML with values: { items: "{{trigger.array_field}}" }
+ * // Converts to: ForEach(params.trigger.array_field, { $id, annotation }, (item) => {...})
+ */
+/**
+ * Build arguments for forEach flow logic with intelligent parameter name preservation.
+ *
+ * PARAMETER NAMING STRATEGY (Priority Order):
+ *
+ * 1. **Original Source Extraction** (Round-Trip Preservation):
+ *    - For Fluent-authored flows, extracts parameter name from original AST
+ *    - Preserves user-chosen names: (dept), (category), (item_0), etc.
+ *    - Enables lossless round-trips: Fluent → XML → Fluent
+ *
+ * 2. **Order-Based Naming** (UI-Authored Flows):
+ *    - For UI-authored flows (no original source), generates item_${order}
+ *    - Creates predictable names: item_0, item_1, item_2
+ *    - Disambiguates nested forEach loops clearly
+ *
+ * 3. **Default Fallback** (Edge Cases):
+ *    - Falls back to 'item' if neither strategy succeeds
+ *
+ * @example Round-Trip Preservation
+ * // Original Fluent code:
+ * forEach(users, {...}, (dept) => {
+ *   forEach(categories, {...}, (category) => {
+ *     action(..., { msg: `${dept.name} - ${category.value}` })
+ *   })
+ * })
+ *
+ * // After deploy + pull: PRESERVED!
+ * forEach(users, {...}, (dept) => {  // ✅ 'dept' preserved
+ *   forEach(categories, {...}, (category) => {  // ✅ 'category' preserved
+ *     action(..., { msg: `${dept.name} - ${category.value}` })
+ *   })
+ * })
+ *
+ * @example UI-Authored Flow
+ * // Flow created in UI, pulled to Fluent:
+ * forEach(users, {...}, (item_0) => {  // Generated from order=0
+ *   forEach(categories, {...}, (item_3) => {  // Generated from order=3
+ *     action(..., { msg: `${item_0.name} - ${item_3.value}` })
+ *   })
+ * })
+ *
+ * @param record - The forEach flow logic instance record
+ * @param logicBodyShapes - The shapes within the forEach body
+ * @returns Array of shapes [items, config, body] for forEach arguments
+ */
+
+/**
+ * Extracts the forEach parameter name from the original source (for round-trip preservation).
+ * Falls back to order-based naming for UI-authored flows, or 'item' as final fallback.
+ *
+ * @param record - The forEach flow logic record
+ * @returns The parameter name to use in the arrow function
+ */
+function extractForEachParameterName(record: Record): string {
+    try {
+        const originalSource = record.getOriginalSource()
+
+        // Check if we have a valid ts.Node
+        if (!ts.Node.isNode(originalSource)) {
+            return getFallbackParameterName(record)
+        }
+
+        // For forEach: wfa.flowLogic.forEach(items, config, (param) => {...})
+        // Third argument (index 2) is the arrow function
+        const arrowFn = (originalSource as ts.CallExpression).getArguments()[2]?.asKind(ts.SyntaxKind.ArrowFunction)
+
+        if (!arrowFn) {
+            return getFallbackParameterName(record)
+        }
+
+        const params = arrowFn.getParameters()
+        const paramName = params[0]?.getName()
+
+        return paramName || getFallbackParameterName(record)
+    } catch {
+        // Failed to extract parameter name - using fallback
+        return getFallbackParameterName(record)
+    }
+}
+
+/**
+ * Gets the fallback parameter name based on order or default.
+ */
+function getFallbackParameterName(record: Record): string {
+    const order = record.get('order')?.getValue() as string | undefined
+    return order ? `item_${order}` : 'item'
+}
+
+function buildForEachArguments(record: Record, logicBodyShapes: Shape[]): Shape<unknown>[] {
+    // 1. Parse values field to extract items data pill string
+    const logicName = FlowLogicSysId.getLogicName(record.get('logic_definition').asString().getValue()) as FLOW_LOGIC
+
+    const valuesJson = FlowLogicValueProcessor.parse(logicName, record.get('values').asString().getValue()) as {
+        items?: string
+    }
+
+    // 2. Return items as raw string - will be converted by processInstanceForDatapills
+    // with the correct parameter name extracted from the flow
+    const itemsString = valuesJson.items || ''
+    const itemsShape = Shape.from(record, itemsString)
+
+    // 3. Build config ObjectShape
+    const configShape = new ObjectShape({
+        source: record,
+        properties: {
+            annotation: record.get('comment').asString().getValue(),
+            $id: NowIdShape.from(record),
+        },
+    })
+
+    // 4. Build body ArrowFunctionShape with parameter name extraction
+    // Strategy for parameter naming (in priority order):
+    //   1. Extract from original source (for round-trip preservation) - e.g., user wrote (item_0), (dept), etc.
+    //   2. Use order-based naming for UI-authored flows - e.g., item_0, item_1, item_2
+    //   3. Fall back to 'item' if order is unavailable
+
+    const parameterName = extractForEachParameterName(record)
+
+    const bodyShape = new ArrowFunctionShape({
+        source: record,
+        parameters: [new IdentifierShape({ source: record, name: parameterName })],
+        statements: logicBodyShapes,
+    })
+
+    // 5. Return in correct order: [items, config, body]
+    return [itemsShape, configShape, bodyShape]
+}
+
+function buildInputsShapeFromZipped({
+    zippedInputs,
+    definitionInputs,
+    record,
+}: {
+    zippedInputs: string
+    definitionInputs: Record[] | undefined
+    record: Record
+}): ObjectShape | undefined {
+    if (!zippedInputs) {
+        return undefined
+    }
+
+    // Type definition includes parameter field which contains type information from XML
+    let inputsJson: {
+        inputs: Array<{
+            name: string
+            value: string
+            parameter?: { type?: string; [key: string]: unknown }
+        }>
+    }
+    try {
+        const inputsBuffer = gunzipSync(Buffer.from(zippedInputs, 'base64'))
+        inputsJson = JSON.parse(inputsBuffer.toString('utf8'))
+    } catch {
+        // Failed to parse zipped inputs - returning undefined
+        return undefined
+    }
+
+    const inputs: { [key: string]: unknown } = {}
+    if (inputsJson.inputs) {
+        const durationTypeInput = inputsJson.inputs.find((i) => i.name === 'duration_type')
+        const durationType = (durationTypeInput ? normalizeInputValue(durationTypeInput.value) : '') as string
+        const validProps = DURATION_TYPE_PROPS[durationType]
+
+        if (validProps) {
+            for (const input of inputsJson.inputs) {
+                const mappedName = NAME_MAP[input.name] ?? input.name
+
+                if (validProps.has(mappedName)) {
+                    const defInput = definitionInputs?.find((def) => def.get('element').getValue() === input.name)
+                    const uiType = defInput?.get('ui_type')?.asString()?.getValue()
+
+                    // Use uiType or fallback to parameter.type (consistent with flow-instance-plugin)
+                    const effectiveType = uiType ?? input.parameter?.type
+                    const value = normalizeInputValue(input.value, effectiveType, record)
+
+                    if (value !== '') {
+                        inputs[mappedName] = value
+                    }
+                }
+            }
+        }
+    }
+
+    return Shape.from(record, inputs).asObject()
+}
+
+export function getFlowLogicArguments(
+    logicName: FLOW_LOGIC,
+    record: Record,
+    logicBodyShapes: Shape[],
+    database: Database
+): Shape<unknown>[] {
+    const builder = FLOW_LOGIC_ARGUMENT_BUILDERS[logicName]
+
+    if (!builder) {
+        throw new Error(`Unsupported flow logic type for argument building: ${logicName}`)
+    }
+
+    return builder(record, logicBodyShapes, database)
+}