@winkjs/composer 0.0.2 → 0.4.0

package/src/flow/for-each.js

@@ -0,0 +1,225 @@
+/**
+ * @fileoverview `forEach` - the chain fan. It runs a callback once per field in a
+ * concrete list, giving each run an `each` handle, and adds one copy of the chain
+ * the callback builds for that field. It is the multi-node sibling of array sugar:
+ * array sugar fans a single node across a field list; `forEach` fans a whole chain,
+ * including predicate-input nodes (e.g. `persistenceCheck`) and two-input nodes
+ * (e.g. `ratio`) that array sugar cannot reach.
+ *
+ * Everything happens at build time. The fan expands into ordinary node specs through
+ * the same machinery the per-node DSL methods use - the signature-pattern dispatch
+ * (`spec-builder.js`), the shared router (`get-target-array.js`), the collision
+ * checkers, and `init` validation - so nothing new runs per message and the wiring,
+ * partition, and run layers are untouched.
+ *
+ * Naming is the fan-owned scheme (ADR-006/ADR-007): a node's
+ * name takes the field as a suffix (`clean` -> `clean_scb1`); a node's output takes
+ * the field as a prefix (the output labelled `delta` is stored as `scb1_delta`). The
+ * scheme is fixed, not the configurable naming policy, so the names are predictable -
+ * which `each.out` and the reduce nodes (`tally`, `unbalance`) rely on.
+ *
+ * @see get-target-array.js - the shared spec router
+ * @see resolve-pick-by-field.js - the build-time pickByField resolver
+ * @see expand-single-input-array.js - the single-node fan (array sugar)
+ */
+
+import * as nodes from '../nodes/index.js';
+import { validateWithSchema } from '../core/utils/validate/index.js';
+import { schemas } from './signatures-schema.js';
+import { SIGNATURE_PATTERNS } from './consts.js';
+import { getSignaturePattern } from './get-signature-pattern.js';
+import { specBuilder } from './spec-builder.js';
+import { getTargetArray } from './get-target-array.js';
+import { resolvePickByField } from './resolve-pick-by-field.js';
+
+/**
+ * Locate the index of a named argument slot in a signature schema (the source of
+ * truth for argument positions). Returns -1 when the pattern has no such slot.
+ *
+ * @param {Array} slots - The positional schema for a signature pattern
+ * @param {string} name - The slot name to find ('outputs' or 'options')
+ * @returns {number} The slot index, or -1
+ */
+const slotIndex = function ( slots, name ) {
+    for ( let i = 0; i < slots.length; i += 1 ) {
+        if ( slots[ i ].name === name ) {
+            return i;
+        }
+    }
+    return -1;
+}; // slotIndex()
+
+/**
+ * Build `api.forEach`. Precomputes node metadata once, then returns the chainable
+ * `forEach( fields, callback )` method.
+ *
+ * @param {Object} api - The fluent API object (returned by forEach for chaining)
+ * @param {Object} flowState - Shared flow build state (definitions, checkers, etc.)
+ * @returns {Function} The forEach method
+ */
+export const makeForEach = function ( api, flowState ) {
+    const {
+        flowDefinition,
+        importSet,
+        isNodeNameDuplicate,
+        switchState,
+        groupByState,
+        markPipelineStarted
+    } = flowState;
+
+    // Precompute metadata once, over the same DSL-eligible node filter flow.js uses.
+    const metaByNode = Object.create( null );
+    const nodeNames = Object.keys( nodes ).filter( ( n ) => ( typeof nodes[ n ]?.getDSLMetadata === 'function' ) );
+    for ( let i = 0; i < nodeNames.length; i += 1 ) {
+        metaByNode[ nodeNames[ i ] ] = nodes[ nodeNames[ i ] ].getDSLMetadata();
+    }
+
+    // Expand one fanned node call for one field: transform the args (fan naming +
+    // pickByField resolution), then build, validate, and route the spec through the
+    // shared machinery. `recorded` maps each output label to its stored field, for
+    // this channel's `each.out`.
+    const fanBuild = function ( node, meta, field, recorded, args ) {
+        importSet.add( node );
+
+        const pattern = getSignaturePattern( meta.specSchema );
+        const callContext = `.forEach[ ${field} ].${node}( ${args[ 0 ]} )`;
+
+        try {
+            // Controllers orchestrate other nodes by name; fanning one would leave its
+            // trigger targets unfanned and pointing at the wrong nodes. Reject it loudly
+            // rather than emit a silently-wrong per-field controller.
+            if ( pattern === SIGNATURE_PATTERNS.nameLogic ) {
+                throw new Error(
+                    `WinkComposer/flow: forEach cannot fan a controller ('${args[ 0 ]}'); ` +
+                    'fan data-processing nodes only.'
+                );
+            }
+
+            // Validate the original args, so any message names what the author wrote.
+            const status = validateWithSchema( schemas[ pattern ], [ ...args ], 'Arg' );
+            status.throwIfInvalid( 'argument' );
+
+            const slots = schemas[ pattern ];
+            const outIdx = slotIndex( slots, 'outputs' );
+            const optIdx = slotIndex( slots, 'options' );
+
+            const t = [ ...args ];
+            t[ 0 ] = `${args[ 0 ]}_${field}`;
+
+            // Node-name collision check before building stats (matches make-node-method),
+            // so a rejected node never registers its output params in the global checker.
+            if ( isNodeNameDuplicate( t[ 0 ] ) ) {
+                throw new Error( `WinkComposer/flow: duplicate node ${t[ 0 ]} found.` );
+            }
+
+            // Outputs: store each labelled output as `${field}_${label}`, and record the
+            // label -> stored-field map so a later step can read it via each.out.
+            if ( outIdx >= 0 ) {
+                const rawOutputs = args[ outIdx ];
+                const fanOutputs = Object.create( null );
+                const outKeys = Object.keys( rawOutputs );
+                for ( let i = 0; i < outKeys.length; i += 1 ) {
+                    const label = rawOutputs[ outKeys[ i ] ];
+                    if ( Object.prototype.hasOwnProperty.call( recorded, label ) ) {
+                        console.warn(
+                            `WinkComposer/flow: forEach output label '${label}' written by ` +
+                            `more than one step on field '${field}'; each.out will return the last.`
+                        );
+                    }
+                    recorded[ label ] = `${field}_${label}`;
+                    fanOutputs[ outKeys[ i ] ] = `${field}_${label}`;
+                }
+                t[ outIdx ] = fanOutputs;
+            }
+
+            // Options: resolve any pickByField marker to this channel's value. Every
+            // fannable pattern has an options slot, so optIdx is always >= 0 here; the
+            // guard is only for an omitted (optional) options argument.
+            if ( optIdx < t.length ) {
+                t[ optIdx ] = resolvePickByField( args[ optIdx ], field );
+            }
+
+            const buildSpecFor = specBuilder( meta );
+            const spec = buildSpecFor[ pattern ]( t );
+            const targetArray = getTargetArray( switchState, groupByState, flowDefinition );
+            nodes[ node ].init( spec );
+            targetArray.push( spec );
+        } catch ( error ) {
+            throw new Error(
+                `WinkComposer/flow: Failed to process "${callContext}"\n` +
+                `  Reason: ${error.message}\n`
+            );
+        }
+    }; // fanBuild()
+
+    // Build the per-channel `each` handle: the node methods (fan-aware, chainable),
+    // the current field, and each.out for reading an earlier step's stored field.
+    const makeEachHandle = function ( field ) {
+        const recorded = Object.create( null );
+        const each = Object.create( null );
+
+        for ( let i = 0; i < nodeNames.length; i += 1 ) {
+            const node = nodeNames[ i ];
+            each[ node ] = function ( ...args ) {
+                fanBuild( node, metaByNode[ node ], field, recorded, args );
+                return each;
+            };
+        }
+
+        each.field = field;
+        each.out = function ( label ) {
+            if ( !Object.prototype.hasOwnProperty.call( recorded, label ) ) {
+                throw new Error(
+                    `WinkComposer/flow: each.out( '${label}' ) on field '${field}': ` +
+                    `no earlier step in this chain wrote an output labelled '${label}'.`
+                );
+            }
+            return recorded[ label ];
+        };
+
+        return each;
+    }; // makeEachHandle()
+
+    // The shared per-field routine. The plain-array driver below calls it in a loop;
+    // a future groupBy-deferred path would call the same routine per resolved field.
+    const expandForField = function ( field, callback ) {
+        callback( makeEachHandle( field ) );
+    }; // expandForField()
+
+    return function ( fields, callback ) {
+        // forEach inside a groupBy is deferred: there the field list is a pickByGroup
+        // that only resolves at .endGroup(), so the callback cannot run where written.
+        if ( groupByState.active ) {
+            throw new Error(
+                'WinkComposer/flow: forEach inside groupBy is not supported yet; ' +
+                'the field list must be a concrete array at the call site.'
+            );
+        }
+        if ( !Array.isArray( fields ) || fields.length === 0 ) {
+            throw new Error( 'WinkComposer/flow: forEach requires a non-empty array of field names.' );
+        }
+        if ( typeof callback !== 'function' ) {
+            throw new Error( 'WinkComposer/flow: forEach requires a callback function.' );
+        }
+
+        const seen = Object.create( null );
+        for ( let i = 0; i < fields.length; i += 1 ) {
+            const field = fields[ i ];
+            if ( typeof field !== 'string' || field.length === 0 ) {
+                throw new Error( 'WinkComposer/flow: forEach field names must be non-empty strings.' );
+            }
+            if ( Object.prototype.hasOwnProperty.call( seen, field ) ) {
+                throw new Error( `WinkComposer/flow: forEach duplicate field '${field}' in field list.` );
+            }
+            seen[ field ] = 1;
+        }
+
+        markPipelineStarted();
+
+        for ( let i = 0; i < fields.length; i += 1 ) {
+            expandForField( fields[ i ], callback );
+        }
+
+        return api;
+    };
+}; // makeForEach()

package/src/flow/get-signature-pattern.js

@@ -0,0 +1,31 @@
+import { SIGNATURE_PATTERNS } from './consts.js';
+
+export const getSignaturePattern = function ( schema ) {
+    // Controller node
+    if ( !schema.from && schema.logic ) return SIGNATURE_PATTERNS.nameLogic;
+
+    // Pure predicate based nodes (no inputs)
+    if ( !schema.from && schema.predicate ) {
+        return schema.stats?.required ?
+            // e.g. presistenceCheck
+            SIGNATURE_PATTERNS.namePredicateOutputsOptions :
+            // e.f. PassIf
+            SIGNATURE_PATTERNS.namePredicateOptions;
+    }
+
+    // Input-based nodes
+    const props = schema.from?.properties;
+    // This schema has no `from`, `logic`, or `predicate`, so its shape is not one we
+    // recognize. Return `unknown` so make-node-method.js can raise its clear "unknown
+    // signature pattern" error, instead of crashing on `props.x` below with a raw
+    // TypeError.
+    if ( !props ) return SIGNATURE_PATTERNS.unknown;
+    if ( props.x && !props.y && !schema.stats ) return SIGNATURE_PATTERNS.nameXOptions; // momentsDigest: outputs are implied
+    // Single input node i.e. only `x` e.g. delta
+    if ( props.x && !props.y ) return SIGNATURE_PATTERNS.nameXOutputsOptions;
+    // Dual input node i.e. `x` and `y` e.g. diff
+    if ( props.x && props.y ) return SIGNATURE_PATTERNS.nameXYOutputsOptions;
+
+    // Unable to determine signature pattern
+    return SIGNATURE_PATTERNS.unknown;
+}; // getSignaturePattern()

package/src/flow/get-target-array.js

@@ -0,0 +1,46 @@
+/**
+ * @fileoverview Routes built node specs to the array they belong in, based on the
+ * flow's current switch/case/groupBy state. This is the single router used by every
+ * spec-producing path in the flow DSL: the per-node method (`make-node-method.js`)
+ * and the `forEach` fan (`for-each.js`). Keeping it in one leaf module means both
+ * paths land specs identically and there is no second copy to drift.
+ *
+ * Why a function and not a field: the target depends on transient build state
+ * (are we collecting a groupBy template? inside a `.case()`? in the linear flow?),
+ * which is only known at the moment a spec is produced.
+ */
+
+/**
+ * Determines the target array for spec accumulation based on switch/case/groupBy state.
+ *
+ * @param {Object} switchState - The switch/case state machine
+ * @param {Object} groupByState - The groupBy state machine
+ * @param {Array} flowDefinition - Default target for single-pipeline mode
+ * @returns {Array} Target array to push specs into
+ * @throws {Error} If node is called in invalid state (outside case block, after break)
+ */
+export const getTargetArray = function ( switchState, groupByState, flowDefinition ) {
+    // GroupBy template collection mode - route to template array
+    if ( groupByState && groupByState.active ) {
+        return groupByState.templateSpecs;
+    }
+
+    // Switch/case routing
+    if ( switchState && switchState.active ) {
+        if ( switchState.currentCase === null ) {
+            throw new Error(
+                'WinkComposer/flow: node called outside of a .case() block - ' +
+                'after .switch(), you must call .case() before adding nodes'
+            );
+        }
+        if ( switchState.caseEnded ) {
+            throw new Error(
+                'WinkComposer/flow: node called after .break() - ' +
+                'start a new .case() before adding more nodes'
+            );
+        }
+        return switchState.caseSpecs[ switchState.currentCase ];
+    }
+
+    return flowDefinition;
+}; // getTargetArray()

package/src/flow/inspect.js

@@ -0,0 +1,67 @@
+// flow/inspect.js
+
+/**
+ * @fileoverview Flow inspection for debugging.
+ *
+ * Returns structured information about the flow configuration
+ * for debugging and documentation purposes.
+ *
+ * Supports both single-pipeline and multi-specialization (switch/case) modes.
+ */
+
+/**
+ * Returns debug information about the flow.
+ *
+ * @param {string} flowName - Name of the flow
+ * @param {Array} flowDefinition - Node specifications (for single-pipeline mode)
+ * @param {Set} importSet - Set of node names used
+ * @param {Object} runtime - Runtime configuration
+ * @param {Object} [switchState] - Switch/case state machine (for multi-specialization)
+ * @returns {Object} Flow inspection data
+ */
+export const inspectFlow = function ( flowName, flowDefinition, importSet, runtime, switchState ) {
+    const result = {
+        flowName,
+        imports: Array.from( importSet ).sort(),
+        runtime: {
+            hasSource: runtime.source !== null,
+            emitterCount: Object.keys( runtime.emitters ).length,
+            storageCount: Object.keys( runtime.storages || {} ).length,
+            partitionField: runtime.partitionField,
+            specializationField: runtime.specializationField,
+            yieldThreshold: runtime.yieldThreshold,
+            assetClass: runtime.assetClass ? {
+                name: runtime.assetClass.name,
+                insightTypes: Object.keys( runtime.assetClass.insightTypes || {} )
+            } : null
+        }
+    };
+
+    if ( switchState && switchState.active ) {
+        // Multi-specialization mode
+        result.mode = 'multi-specialization';
+        result.specializations = Object.create( null );
+
+        let totalNodes = 0;
+        for ( let i = 0; i < switchState.caseOrder.length; i += 1 ) {
+            const key = switchState.caseOrder[ i ];
+            const specs = switchState.caseSpecs[ key ];
+            result.specializations[ key ] = {
+                nodeCount: specs.length,
+                nodes: specs.map( ( s ) => ( { name: s.name, type: s.nodeType } ) )
+            };
+            totalNodes += specs.length;
+        }
+
+        result.nodeCount = totalNodes;
+        result.caseOrder = switchState.caseOrder.slice();
+    } else {
+        // Single-pipeline mode (backward compatible)
+        result.mode = 'single-pipeline';
+        result.nodeCount = flowDefinition.length;
+        result.nodes = flowDefinition.map( ( s ) => ( { name: s.name, type: s.nodeType } ) );
+    }
+
+    return result;
+};
+

package/src/flow/load-node-module.js

@@ -0,0 +1,81 @@
+// flow/load-node-module.js
+
+/**
+ * @fileoverview Dynamic loader for node modules at runtime.
+ *
+ * Provides lazy loading of node modules using dynamic imports. This keeps
+ * the DSL build phase lightweight by deferring module loading until .run()
+ * is called. Validates node names against the canonical list before loading.
+ */
+
+import { toKebab } from '../core/utils/flow/index.js';
+import { isValidNodeName } from '../nodes/node-names.js';
+
+/**
+ * Cache for loaded node modules to avoid redundant dynamic imports.
+ * @type {Map<string, object>}
+ */
+const moduleCache = new Map();
+
+/**
+ * Dynamically loads a node module by its camelCase name.
+ *
+ * @param {string} nodeName - camelCase node name (e.g., 'esMean', 'pageHinkley')
+ * @returns {Promise<object>} The node module exports (init, update, publishTo, etc.)
+ * @throws {Error} If nodeName is not a valid node
+ *
+ * @example
+ * const esMean = await loadNodeModule('esMean');
+ * // esMean.init, esMean.update, esMean.publishTo, etc.
+ */
+export const loadNodeModule = async function ( nodeName ) {
+    // Validate node name
+    if ( !isValidNodeName( nodeName ) ) {
+        throw new Error( `Unknown node type: "${nodeName}"` );
+    }
+
+    // Return cached module if available
+    if ( moduleCache.has( nodeName ) ) {
+        return moduleCache.get( nodeName );
+    }
+
+    const kebabName = toKebab( nodeName );
+    const nodeModule = await import( `../nodes/${kebabName}/index.js` );
+
+    // Cache for subsequent calls
+    moduleCache.set( nodeName, nodeModule );
+
+    return nodeModule;
+};
+
+/**
+ * Loads multiple node modules in parallel.
+ *
+ * @param {string[]} nodeNames - Array of camelCase node names
+ * @returns {Promise<Map<string, object>>} Map of nodeName -> module
+ * @throws {Error} If any nodeName is invalid
+ *
+ * @example
+ * const modules = await loadNodeModules(['esMean', 'threshold', 'emitIf']);
+ * modules.get('esMean').update(state, msg);
+ */
+export const loadNodeModules = async function ( nodeNames ) {
+    const uniqueNames = [ ...new Set( nodeNames ) ];
+
+    const loadPromises = uniqueNames.map( async ( name ) => {
+        const mod = await loadNodeModule( name );
+        return [ name, mod ];
+    } );
+
+    const entries = await Promise.all( loadPromises );
+
+    return new Map( entries );
+};
+
+/**
+ * Clears the module cache. Useful for testing or hot-reloading scenarios.
+ */
+export const clearModuleCache = function () {
+    moduleCache.clear();
+};
+

package/src/flow/make-node-method.js

@@ -0,0 +1,112 @@
+import * as nodes from '../nodes/index.js';
+import { validateWithSchema } from '../core/utils/validate/index.js';
+import { schemas } from './signatures-schema.js';
+import { expandSingleInputArraySugar } from './expand-single-input-array.js';
+import { SIGNATURE_PATTERNS } from './consts.js';
+import { getSignaturePattern } from './get-signature-pattern.js';
+import { specBuilder } from './spec-builder.js';
+import { getTargetArray } from './get-target-array.js';
+
+/**
+ * Creates a chainable DSL method for a WinkComposer node.
+ *
+ * @param {Object} api - The fluent API object to extend
+ * @param {string} node - Node type name (e.g., 'esMean')
+ * @param {Object} meta - Node metadata from getDSLMetadata()
+ * @param {Object} flowState - Shared state including definitions and collision checkers
+ * @returns {Function} Chainable method that validates and adds node specs
+ *
+ * @example
+ * const method = makeNodeMethod(api, 'esMean', meta, flowState);
+ * method('smooth', 'temperature', { esMean: 'smoothTemp' }, { alpha: 0.3 });
+ */
+export const makeNodeMethod = function ( api, node, meta, flowState ) {
+    const {
+        flowDefinition,
+        importSet,
+        isNodeNameDuplicate,
+        switchState,
+        groupByState,
+        markPipelineStarted
+    } = flowState;
+
+    return function ( ...args ) {
+        // Mark pipeline as started (blocks subsequent config method calls)
+        if ( markPipelineStarted ) {
+            markPipelineStarted();
+        }
+
+        importSet.add( node );
+
+        let built = null;
+        const schema = meta.specSchema;
+
+        // During groupBy, use the template-local node-name checker. Node names are
+        // prefixed per group at expansion (idle_corr, cruise_corr), so the global
+        // checker would false-positive on the shared template names.
+        const isGroupByActive = groupByState && groupByState.active;
+        const effectiveNodeChecker = isGroupByActive ?
+            groupByState.templateNodeChecker :
+            isNodeNameDuplicate;
+
+        const buildSpecFor = specBuilder( meta );
+
+        // Create effective flowState for sugar expansion
+        const effectiveFlowState = isGroupByActive ?
+            { ...flowState, isNodeNameDuplicate: effectiveNodeChecker } :
+            flowState;
+        // The eligible nodes must have `x` defined as `string` and there is no `y`
+        // property. Note on logic:
+        // Safe because of short-circuit:
+        // - If the left check fails, the right check is not evaluated.
+        // - If the left check passes, then `schema.from.properties` must exist.
+        const isEligible = schema.from?.properties?.x?.type === 'string' && !schema.from.properties.y;
+        const isSugar = isEligible && Array.isArray( args[ 1 ] );
+        const callContext = `.${node}( ${args[ 0 ]}${args.length > 1 ? `, +${args.length - 1}` : ''} )${isSugar ? ` → ${args[ 1 ].join( ', ' )}` : ''}`;
+
+        try {
+            // Array syntactic sugar for single-input nodes only: ( name, [x...], options )—this
+            // signature generates the `storeAs` names automatically using the fixed
+            // `${field}_${label}` rule. If explicit `storeAs` naming is required then
+            // use the alternate signature: ( name, x, output, options? ).
+            //
+            if ( isSugar ) {
+                // Use our standard validators to verify the input signature before building.
+                const status = validateWithSchema( schemas[ SIGNATURE_PATTERNS.nameSugarOutputsOptions ], [ ...args ], 'Arg' );
+                const pattern = getSignaturePattern( schema );
+                status.throwIfInvalid( 'argument' );
+                built = expandSingleInputArraySugar( meta, [ ...args ], effectiveFlowState, pattern );
+            } else {
+                // Canonical builder path
+                const instName = args[ 0 ];
+                if ( effectiveNodeChecker( instName ) ) throw Error( `WinkComposer/flow: duplicate node ${instName} found.` );
+                const pattern = getSignaturePattern( schema );
+                if ( pattern === SIGNATURE_PATTERNS.unknown ) throw Error( `WinkComposer/flow: unknown signature pattern found for ${instName}.` );
+                const status = validateWithSchema( schemas[ pattern ], [ ...args ], 'Arg' );
+                status.throwIfInvalid( 'argument' );
+                built = buildSpecFor[ pattern ]( [ ...args ] );
+            }
+
+            // Normalize to array: allows downstream code to handle both single specs
+            // and spec arrays uniformly without conditional logic.
+            const specs = Array.isArray( built ) ? built : [ built ];
+
+            // Determine target array based on switch/case/groupBy state
+            const targetArray = getTargetArray( switchState, groupByState, flowDefinition );
+
+            // Apply flow-level naming and use initialize for spec to check any error.
+            for ( let j = 0; j < specs.length; j += 1 ) {
+                nodes[ node ].init( specs[ j ] );
+                targetArray.push( specs[ j ] );
+            }
+        } catch ( error ) {
+            const enhancedError = new Error(
+                `WinkComposer/flow: Failed to process "${callContext}"\n` +
+                `  Reason: ${error.message}\n`
+            );
+
+            throw enhancedError;
+        }
+        return api;
+    };
+}; // makeNodeMethod()

package/src/flow/resolve-pick-by-field.js

@@ -0,0 +1,77 @@
+/**
+ * @fileoverview Build-time resolver for `pickByField` markers inside a `forEach`.
+ *
+ * A `pickByField( map )` marker is a function carrying
+ * `.semantics = { type: 'pickByField', map }`; it stands for "the value for the
+ * current fan channel". When a `forEach` expands a chain for one field, this walker
+ * replaces every such marker in that node's options with `map[ field ]` — a plain
+ * value baked into the spec before the node is initialized. After it runs, nothing
+ * of `pickByField` survives into the wired pipeline, so it costs nothing per message.
+ *
+ * It mirrors `resolve-tunables.js` (the groupBy resolver) on every pass-through:
+ * other tunables and plain predicates are preserved for runtime, primitives pass
+ * straight through, and arrays and plain objects are rebuilt with their entries
+ * resolved. It differs only at the leaf — it resolves `pickByField` by the current
+ * field (throwing on a missing key), where the groupBy resolver resolves
+ * `lookupByField` by the group value (with a default). The two leaf rules diverge,
+ * which is why this is a separate module rather than a shared walker.
+ *
+ * @see resolve-tunables.js - the groupBy sibling resolver
+ * @see ADR-006 - Tunable Pattern for Dynamic Parameters
+ */
+
+/**
+ * Recursively resolves `pickByField` markers in an options value for one fan field.
+ *
+ * @param {*} value - The value to process (an option, or a nested part of one)
+ * @param {string} field - The current fan channel's field name (each.field)
+ * @returns {*} The value with every pickByField marker replaced by map[ field ]
+ * @throws {Error} If a pickByField map has no entry for `field`
+ */
+export const resolvePickByField = function ( value, field ) {
+    // A pickByField marker: resolve to map[ field ]. A missing key is a build error,
+    // not a silent undefined that would slip through to the first message.
+    if ( typeof value === 'function' && value.semantics && value.semantics.type === 'pickByField' ) {
+        const map = value.semantics.map;
+        if ( !Object.prototype.hasOwnProperty.call( map, field ) ) {
+            throw new Error(
+                `WinkComposer/flow: pickByField has no entry for field '${field}' ` +
+                `(map keys: ${Object.keys( map ).join( ', ' )}).`
+            );
+        }
+        // Return the resolved value as-is; do not recurse into it, so a resolved
+        // field-keyed object (e.g. a sanitize range) reaches the node's own resolver
+        // intact.
+        return map[ field ];
+    }
+
+    // Any other function - a plain predicate, or a different tunable like
+    // lookupByField - is preserved for runtime. pickByField is the only marker this
+    // resolver owns.
+    if ( typeof value === 'function' ) {
+        return value;
+    }
+
+    // Null/undefined/primitives pass through unchanged.
+    if ( value === null || value === undefined || typeof value !== 'object' ) {
+        return value;
+    }
+
+    // Arrays - resolve each element into a new array.
+    if ( Array.isArray( value ) ) {
+        const result = [];
+        for ( let i = 0; i < value.length; i += 1 ) {
+            result.push( resolvePickByField( value[ i ], field ) );
+        }
+        return result;
+    }
+
+    // Objects - resolve each property into a clean object.
+    const result = Object.create( null );
+    const keys = Object.keys( value );
+    for ( let i = 0; i < keys.length; i += 1 ) {
+        result[ keys[ i ] ] = resolvePickByField( value[ keys[ i ] ], field );
+    }
+
+    return result;
+}; // resolvePickByField()