ga4-export-fixer 0.8.0 → 0.9.0-dev.10

package/tables/ga4EventsEnhanced/index.js

@@ -197,51 +197,46 @@ const _generateEnhancedEventsSQL = (mergedConfig) => {
         return excludedColumns;
     };
 
-    // initial step: extract data from the export tables
+    // initial step: extract data from the export tables.
+    // Explicit columns first (transforms + package-promoted + user-excluded sentinels);
+    // then pass-through entries for every GA4 export column not already accounted for.
+    // After this, Object.keys(eventDataStep.select.columns) is the complete column set of event_data.
+    const eventDataExplicitColumns = {
+        // exclude default export columns that are not needed
+        // do this first so that the columns defined later are not excluded
+        ...getExcludedColumns(),
+        event_date: helpers.eventDate,
+        event_datetime: `extract(datetime from timestamp_micros(${helpers.getEventTimestampMicros(mergedConfig.customTimestampParam)}) at time zone '${mergedConfig.timezone}')`,
+        event_custom_timestamp: mergedConfig.customTimestampParam ? helpers.getEventTimestampMicros(mergedConfig.customTimestampParam) : undefined,
+        session_id: helpers.sessionId,
+        // page details
+        page_location: helpers.unnestEventParam('page_location', 'string'),
+        page: helpers.extractPageDetails(),
+        // promote event params to columns
+        ...promotedEventParameters(),
+        event_params: helpers.filterEventParams(mergedConfig.excludedEventParams, 'exclude'),
+        // rename traffic_source for clarity
+        user_traffic_source: 'traffic_source',
+        // ecommerce
+        ecommerce: helpers.fixEcommerceStruct('ecommerce'),
+        // assign a unique row id, used for handling item-level attribution and enrichment
+        _item_row_id: itemListAttribution ? helpers.itemRowId(ecommerceEventsFilter) : undefined,
+        // flag if the data is "final" and is not expected to change anymore
+        data_is_final: helpers.isFinalData(mergedConfig.dataIsFinal.detectionMethod, mergedConfig.dataIsFinal.dayThreshold),
+        export_type: helpers.getGa4ExportType('_table_suffix'),
+        // prep columns for later steps
+        entrances: helpers.unnestEventParam('entrances', 'int'),
+        session_params_prep: mergedConfig.sessionParams.length > 0 ? helpers.filterEventParams(mergedConfig.sessionParams, 'include') : undefined,
+    };
+    // Pass through every GA4 export column not already covered by an explicit transform,
+    // promotion, exclusion sentinel, or value-side rename in eventDataExplicitColumns.
+    const eventDataPassThroughs = utils.buildPassThroughs(eventDataExplicitColumns, helpers.ga4ExportColumns);
     const eventDataStep = {
         name: 'event_data',
         select: {
             columns: {
-                // exclude default export columns that are not needed
-                // do this first so that the columns defined later are not excluded
-                ...getExcludedColumns(),
-                // date and time
-                event_date: helpers.eventDate,
-                event_datetime: `extract(datetime from timestamp_micros(${helpers.getEventTimestampMicros(mergedConfig.customTimestampParam)}) at time zone '${mergedConfig.timezone}')`,
-                event_timestamp: 'event_timestamp',
-                event_custom_timestamp: mergedConfig.customTimestampParam ? helpers.getEventTimestampMicros(mergedConfig.customTimestampParam) : undefined,
-                // event name
-                event_name: 'event_name',
-                // identifiers
-                session_id: helpers.sessionId,
-                user_pseudo_id: 'user_pseudo_id',
-                user_id: 'user_id',
-                // page
-                page_location: helpers.unnestEventParam('page_location', 'string'),
-                page: helpers.extractPageDetails(),
-                // event parameters and user properties
-                ...promotedEventParameters(),
-                event_params: helpers.filterEventParams(mergedConfig.excludedEventParams, 'exclude'),
-                user_properties: 'user_properties',
-                // traffic source
-                collected_traffic_source: 'collected_traffic_source',
-                session_traffic_source_last_click: 'session_traffic_source_last_click',
-                user_traffic_source: 'traffic_source',
-                // ecommerce
-                ecommerce: helpers.fixEcommerceStruct('ecommerce'),
-                items: 'items',
-                _item_list_attribution_row_id: itemListAttribution ? helpers.itemListAttributionRowId(ecommerceEventsFilter) : undefined,
-                // flag if the data is "final" and is not expected to change anymore
-                data_is_final: helpers.isFinalData(mergedConfig.dataIsFinal.detectionMethod, mergedConfig.dataIsFinal.dayThreshold),
-                export_type: helpers.getGa4ExportType('_table_suffix'),
-                // prep columns for later steps
-                entrances: helpers.unnestEventParam('entrances', 'int'),
-                session_params_prep: mergedConfig.sessionParams.length > 0 ? helpers.filterEventParams(mergedConfig.sessionParams, 'include') : undefined,
-                // include all other columns from the export data
-                get '[sql]other_columns'() {
-                    const definedColumns = Object.keys(this);
-                    return `* except (${definedColumns.filter(column => helpers.isGa4ExportColumn(column)).join(', ')})`;
-                },
+                ...eventDataExplicitColumns,
+                ...eventDataPassThroughs,
             },
         },
         from: mergedConfig.sourceTable,
@@ -268,60 +263,192 @@ ${excludedEventsSQL}`,
         'group by': 'session_id',
     };
 
-    // item list attribution CTEs:
-    // 1. item_list_unnest: unnest items from ecommerce events, compute attribution via window function
-    // 2. item_list_data: re-aggregate items with attributed list fields
-    const itemListSteps = itemListAttribution ? (() => {
-        const attrExpr = helpers.itemListAttributionExpr(
-            itemListAttribution.lookbackType,
-            timestampColumn,
-            itemListAttribution.lookbackTimeMs
-        );
+    // Build enrichment-source CTEs and gather per-level join/column data. The utility routes
+    // event-level and item-level entries through separate output channels.
+    const { steps: enrichmentSteps, event: eventEnrichments, item: itemEnrichments }
+        = utils.buildEnrichments(mergedConfig.enrichments);
+
+    // Validate item-level joinKey columns and collect any event_data columns that need to
+    // be carried up to items_unnested as top-level columns (so the LEFT JOIN inside
+    // items_rebuilt can USING(...) on them). Item-struct fields are already top-level on
+    // items_unnested and need no extension.
+    const itemJoinKeysFromEventData = new Set();
+    for (const [i, e] of (mergedConfig.enrichments ?? []).entries()) {
+        const level = e.level ?? 'event';
+        if (level !== 'item') continue;
+        const joinKeys = Array.isArray(e.joinKey) ? e.joinKey : [e.joinKey];
+        for (const c of joinKeys) {
+            if (helpers.ga4ItemStructFields.includes(c)) {
+                // Already a top-level column on items_unnested.
+            } else if (c in eventDataStep.select.columns && eventDataStep.select.columns[c] !== undefined) {
+                itemJoinKeysFromEventData.add(c);
+            } else {
+                throw new Error(
+                    `config.enrichments[${i}] (name: '${e.name}') uses item-level joinKey '${c}', ` +
+                    `which is neither a field on the GA4 items struct (helpers.ga4ItemStructFields) ` +
+                    `nor a column on event_data. Valid item-level joinKeys are item-struct fields ` +
+                    `(e.g. item_id, item_category) or any event_data column (e.g. user_pseudo_id, event_date).`
+                );
+            }
+        }
+    }
+
+    // Shared item-array CTEs:
+    // 1. items_unnested: unnest items from ecommerce events; LAST_VALUE attribution window
+    //    is emitted only when itemListAttribution is configured.
+    // 2. items_rebuilt: re-aggregate items via explicit struct(...) construction;
+    //    LEFT JOIN enrich_<name> for each item-level enrichment.
+    // Activation: emitted when EITHER itemListAttribution is configured OR at least one
+    // item-level enrichment is present.
+    const itemEnrichmentsActive = itemEnrichments.joins.length > 0;
+    const itemsScaffoldActive = !!itemListAttribution || itemEnrichmentsActive;
+    const itemListSteps = itemsScaffoldActive ? (() => {
         const passthroughEvents = `event_name in ('view_item_list', 'select_item', 'view_promotion', 'select_promotion')`;
 
-        const attributionStep = {
-            name: 'item_list_attribution',
-            select: {
-                columns: {
-                    '_item_list_attribution_row_id': '_item_list_attribution_row_id',
-                    'event_name': 'event_name',
-                    'item': 'item',
-                    '_item_list_attr': attrExpr,
-                },
-            },
+        // Flatten the item struct: every standard items-struct field is selected as a
+        // top-level column of items_unnested. This makes downstream joins simpler
+        // (LEFT JOIN ... USING(item_id) works without aliasing tricks) and lets items_rebuilt
+        // reference fields as bare column names instead of `item.<col>`.
+        const itemFieldColumns = {};
+        for (const f of helpers.ga4ItemStructFields) {
+            itemFieldColumns[f] = `item.${f}`;
+        }
+
+        // Carry up any event_data joinKey columns used by item-level enrichments so the
+        // USING(...) clause in items_rebuilt can bind against top-level identifiers.
+        // Skip ones already in the base columns above (e.g. event_date is always carried).
+        const baseColumnNames = new Set(['_item_row_id', 'event_name', 'event_date', ...Object.keys(itemFieldColumns)]);
+        const extraJoinKeyColumns = {};
+        for (const c of itemJoinKeysFromEventData) {
+            if (!baseColumnNames.has(c)) {
+                extraJoinKeyColumns[c] = c;
+            }
+        }
+
+        // items_unnested base columns. The _item_list_attr struct (LAST_VALUE window) is
+        // added only when itemListAttribution is configured — when only item enrichments
+        // are active, the window function is omitted entirely for cleaner SQL.
+        const unnestedSelectColumns = {
+            '_item_row_id': '_item_row_id',
+            'event_name': 'event_name',
+            // event_date is carried forward for ability to use it in data enrichment joins
+            'event_date': 'event_date',
+            ...itemFieldColumns,
+            ...extraJoinKeyColumns,
+        };
+        if (itemListAttribution) {
+            unnestedSelectColumns._item_list_attr = helpers.itemListAttributionExpr(
+                itemListAttribution.lookbackType,
+                timestampColumn,
+                itemListAttribution.lookbackTimeMs
+            );
+        }
+
+        const unnestedStep = {
+            name: 'items_unnested',
+            select: { columns: unnestedSelectColumns },
             from: 'event_data, unnest(items) as item',
             where: `event_name in (${ecommerceEventsFilter})`,
         };
 
-        const dataStep = {
-            name: 'item_list_data',
+        // Build the per-field expression map for the items struct. Seed with the canonical
+        // GA4 items-struct fields — each references the matching top-level column on
+        // items_unnested. When itemListAttribution is configured, override the three
+        // attribution entries with their package-generated coalesce-with-passthrough
+        // expressions. Item-level enrichment columns layer on top via the spread below.
+        const preItemExpressions = {};
+        for (const f of helpers.ga4ItemStructFields) {
+            preItemExpressions[f] = f;
+        }
+        if (itemListAttribution) {
+            preItemExpressions.item_list_name = `coalesce(if(${passthroughEvents}, item_list_name, _item_list_attr.item_list_name), '(not set)')`;
+            preItemExpressions.item_list_id = `coalesce(if(${passthroughEvents}, item_list_id, _item_list_attr.item_list_id), '(not set)')`;
+            preItemExpressions.item_list_index = `coalesce(if(${passthroughEvents}, item_list_index, _item_list_attr.item_list_index))`;
+        }
+
+        // Wrap overlapping item-level enrichment columns in coalesce(<enrichExpr>, <originalExpr>)
+        // so a missed JOIN falls back to the existing item field value. Purely additive
+        // columns (no overlap) pass through unchanged.
+        const wrappedItemEnrichmentColumns = {};
+        for (const [col, enrichExpr] of Object.entries(itemEnrichments.columns)) {
+            const originalExpr = preItemExpressions[col];
+            wrappedItemEnrichmentColumns[col] = originalExpr
+                ? `coalesce(${enrichExpr}, ${originalExpr})`
+                : enrichExpr;
+        }
+
+        // Final struct: standard fields first, then enrichment overrides spread on top
+        // (overlapping keys replace preItemExpressions entries; additive keys are appended).
+        const finalItemStructFields = { ...preItemExpressions, ...wrappedItemEnrichmentColumns };
+
+        const itemStructClauses = Object.entries(finalItemStructFields)
+            .map(([col, expr]) => `${expr} as ${col}`)
+            .join(',\n        ');
+
+        const rebuiltStep = {
+            name: 'items_rebuilt',
             select: {
                 columns: {
-                    '_item_list_attribution_row_id': '_item_list_attribution_row_id',
-                    'items': `array_agg(
-      (select as struct item.* replace(
-        coalesce(if(${passthroughEvents}, item.item_list_name, _item_list_attr.item_list_name), '(not set)') as item_list_name,
-        coalesce(if(${passthroughEvents}, item.item_list_id, _item_list_attr.item_list_id), '(not set)') as item_list_id,
-        coalesce(if(${passthroughEvents}, item.item_list_index, _item_list_attr.item_list_index)) as item_list_index
-      ))
-    )`,
+                    '_item_row_id': '_item_row_id',
+                    'items': `array_agg(struct(
+        ${itemStructClauses}
+      ))`,
                 },
             },
-            from: 'item_list_attribution',
-            'group by': '_item_list_attribution_row_id',
+            from: 'items_unnested',
+            'group by': '_item_row_id',
         };
+        // Item-level enrichment joins (only attach when present). Each enrichment's LEFT JOIN
+        // binds against top-level columns on items_unnested (item-struct fields, or event_data
+        // joinKey columns carried up via extraJoinKeyColumns above).
+        if (itemEnrichmentsActive) {
+            rebuiltStep.joins = itemEnrichments.joins;
+        }
 
-        return [attributionStep, dataStep];
+        return [unnestedStep, rebuiltStep];
     })() : null;
 
     const finalColumnOrder = getFinalColumnOrder(eventDataStep, sessionDataStep);
 
-    // When item list attribution is enabled, override the items column and exclude _item_list_attribution_row_id
+    // When the items scaffold is active, override the items column and exclude _item_row_id
     // COALESCE handles events without items (not in ecommerce filter) where the LEFT JOIN returns NULL
     const itemListOverrides = itemListSteps ? {
-        items: 'coalesce(item_list_data.items, event_data.items)',
+        items: 'coalesce(items_rebuilt.items, event_data.items)',
     } : {};
-    const itemListExcludedColumns = itemListSteps ? ['_item_list_attribution_row_id'] : [];
+    const itemListExcludedColumns = itemListSteps ? ['_item_row_id'] : [];
+
+    // Wrap overlapping event-level enrichment columns in coalesce(enrich_<name>.<col>, <original>)
+    // so a missed JOIN falls back to the existing value. Purely additive columns (no overlap)
+    // pass through unchanged. Source-of-original precedence matches the final SELECT's spread
+    // order: itemListOverrides first (overrides finalColumnOrder for `items`), then
+    // session_data (wins over event_data in getFinalColumnOrder when both have the column).
+    const wrappedEventEnrichmentColumns = {};
+    for (const [col, enrichExpr] of Object.entries(eventEnrichments.columns)) {
+        let originalExpr;
+        if (col in itemListOverrides) {
+            originalExpr = itemListOverrides[col];
+        } else if (col in sessionDataStep.select.columns) {
+            originalExpr = `session_data.${col}`;
+        } else if (col in eventDataStep.select.columns && eventDataStep.select.columns[col] !== undefined) {
+            originalExpr = `event_data.${col}`;
+        }
+        wrappedEventEnrichmentColumns[col] = originalExpr
+            ? `coalesce(${enrichExpr}, ${originalExpr})`
+            : enrichExpr;
+    }
+
+    // List all column names that have already been defined or should be left out
+    // Used for the final pass-through: include the rest of the coulumns that haven't been explicitly listed yet
+    const alreadyMapped = [
+        ...Object.keys(finalColumnOrder),
+        ...Object.keys(itemListOverrides),
+        ...eventEnrichments.columnNames,
+        'entrances',
+        mergedConfig.sessionParams.length > 0 ? 'session_params_prep' : undefined,
+        'data_is_final',
+        'export_type',
+        ...itemListExcludedColumns,
+    ];
 
     // Join event_data and session_data, include additional logic
     // Named 'enhanced_events' so user-supplied customSteps can reference it as a stable handle.
@@ -332,24 +459,11 @@ ${excludedEventsSQL}`,
                 // get the most important columns in the correct order
                 ...finalColumnOrder,
                 ...itemListOverrides,
-                // get the rest of the event_data columns
-                '[sql]event_data': utils.selectOtherColumns(
-                    eventDataStep,
-                    Object.keys(finalColumnOrder),
-                    [
-                        'entrances',
-                        mergedConfig.sessionParams.length > 0 ? 'session_params_prep' : undefined,
-                        'data_is_final',
-                        'export_type',
-                        ...itemListExcludedColumns,
-                    ]
-                ),
-                // get the rest of the session_data columns
-                '[sql]session_data': utils.selectOtherColumns(
-                    sessionDataStep,
-                    Object.keys(finalColumnOrder),
-                    []
-                ),
+                // event-level enrichment columns: coalesce with the original when overlapping; otherwise add.
+                ...wrappedEventEnrichmentColumns,
+                // explicit pass-throughs for the rest of event_data and session_data
+                ...utils.buildQualifiedPassThroughs(eventDataStep, alreadyMapped),
+                ...utils.buildQualifiedPassThroughs(sessionDataStep, alreadyMapped),
                 // include additional columns
                 row_inserted_timestamp: 'current_timestamp()',
                 data_is_final: 'data_is_final',
@@ -360,28 +474,29 @@ ${excludedEventsSQL}`,
         joins: [
             ...(itemListSteps ? [{
                 type: 'left',
-                table: 'item_list_data',
-                on: 'using(_item_list_attribution_row_id)'
+                table: 'items_rebuilt',
+                on: 'using(_item_row_id)'
             }] : []),
             {
                 type: 'left',
                 table: 'session_data',
                 on: 'using(session_id)'
-            }
+            },
+            // The left joins for the event-level enrichment ctes
+            ...eventEnrichments.joins,
         ],
         where: helpers.incrementalDateFilter(mergedConfig)
     };
 
     const packageSteps = [
+        ...enrichmentSteps,
         eventDataStep,
         ...(itemListSteps ?? []),
         sessionDataStep,
         enhancedEventsStep,
     ];
 
-    // Layer 2 validation: customSteps name must not collide with package step names.
-    // Reserved set is derived from packageSteps at runtime (single source of truth) — what
-    // is reserved depends on config (e.g. item_list_* exist only when itemListAttribution is on).
+    // Ensure that the custom step names don't collide with the default or data enrichment step names
     const customSteps = mergedConfig.customSteps ?? [];
     if (customSteps.length > 0) {
         const reservedNames = new Set(packageSteps.map(s => s.name));
@@ -395,6 +510,7 @@ ${excludedEventsSQL}`,
         }
     }
 
+    // Include custom steps last in the list
     const steps = [...packageSteps, ...customSteps];
 
     return utils.queryBuilder(steps);

package/tables/ga4EventsEnhanced/validation.js

@@ -201,11 +201,11 @@ const validateEnhancedEventsConfig = (config, options = {}) => {
         }
     }
 
-    // customSteps - optional array of queryBuilder step objects appended to the pipeline
-    // Layer 1 (config shape): array, objects with non-empty name, no duplicates within customSteps.
+    // customSteps - optional array of queryBuilder step objects appended to the pipeline.
+    // Config-shape checks only: array, objects with non-empty name, no duplicates within customSteps.
     // Step-shape validation (clause keys, etc.) deferred to queryBuilder.
-    // Collision-with-package-names check deferred to _generateEnhancedEventsSQL (Layer 2),
-    // since the reserved set is config-dependent (e.g. item_list_* only exist when itemListAttribution is on).
+    // Collision-with-package-names check deferred to _generateEnhancedEventsSQL, since the
+    // reserved set is config-dependent (e.g. item_list_* only exist when itemListAttribution is on).
     if (config.customSteps !== undefined) {
         if (!Array.isArray(config.customSteps)) {
             throw new Error(`config.customSteps must be an array. Received: ${JSON.stringify(config.customSteps)}`);
@@ -225,6 +225,101 @@ const validateEnhancedEventsConfig = (config, options = {}) => {
             seenNames.add(step.name);
         }
     }
+
+    // enrichments - optional array of declarative external-data enrichment specs.
+    // Config-shape checks only. Reserved-name collision and item-level joinKey resolution
+    // happen in _generateEnhancedEventsSQL, where the reserved set and item-level join targets
+    // are derived from the resolved config.
+    if (config.enrichments !== undefined) {
+        if (!Array.isArray(config.enrichments)) {
+            throw new Error(`config.enrichments must be an array. Received: ${JSON.stringify(config.enrichments)}`);
+        }
+        const validLevels = ['event', 'item'];
+        const seenNames = new Set();
+        for (let i = 0; i < config.enrichments.length; i++) {
+            const entry = config.enrichments[i];
+            if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+                throw new Error(`config.enrichments[${i}] must be a non-null object. Received: ${JSON.stringify(entry)}`);
+            }
+            if (typeof entry.name !== 'string' || !entry.name.trim()) {
+                throw new Error(`config.enrichments[${i}].name must be a non-empty string. Received: ${JSON.stringify(entry.name)}`);
+            }
+            if (seenNames.has(entry.name)) {
+                throw new Error(`config.enrichments contains duplicate name '${entry.name}'. Each enrichments entry must have a unique name.`);
+            }
+            seenNames.add(entry.name);
+            if (entry.level !== undefined && !validLevels.includes(entry.level)) {
+                throw new Error(`config.enrichments[${i}].level must be one of: ${validLevels.join(', ')}. Received: ${JSON.stringify(entry.level)}`);
+            }
+            // source: Dataform table reference object or backtick-quoted string
+            if (entry.source === undefined || entry.source === null) {
+                throw new Error(`config.enrichments[${i}].source is required.`);
+            }
+            if (isDataformTableReferenceObject(entry.source)) {
+                // Valid Dataform reference
+            } else if (typeof entry.source === 'string') {
+                if (!entry.source.trim()) {
+                    throw new Error(`config.enrichments[${i}].source must be a non-empty string. Received empty string.`);
+                }
+                if (!/^`[^\.]+\.[^\.]+\.[^\.]+`$/.test(entry.source.trim())) {
+                    throw new Error(`config.enrichments[${i}].source must be in the format '\`project.dataset.table\`' (with backticks) or a Dataform table reference. Received: ${JSON.stringify(entry.source)}`);
+                }
+            } else {
+                throw new Error(`config.enrichments[${i}].source must be a Dataform table reference object or a string in format '\`project.dataset.table\`'. Received: ${JSON.stringify(entry.source)}`);
+            }
+            // joinKey: required, plain SQL identifier OR non-empty array of plain SQL identifiers.
+            // Plain identifier = ^[a-zA-Z_][a-zA-Z0-9_]*$ — no aliases (`id as user_id`), no backticks,
+            // no dotted paths. Users with mismatched dim-column names alias in an upstream Dataform view.
+            const sqlIdentifier = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+            const aliasingHint = ' Aliases like \'id as user_id\' are not supported here; alias in an upstream Dataform view if your dim has a different column name.';
+            if (entry.joinKey === undefined || entry.joinKey === null) {
+                throw new Error(`config.enrichments[${i}].joinKey is required.`);
+            }
+            if (typeof entry.joinKey === 'string') {
+                if (!entry.joinKey.trim()) {
+                    throw new Error(`config.enrichments[${i}].joinKey must be a non-empty string. Received empty string.`);
+                }
+                if (!sqlIdentifier.test(entry.joinKey)) {
+                    throw new Error(`config.enrichments[${i}].joinKey must be a plain SQL identifier. Received: ${JSON.stringify(entry.joinKey)}.${aliasingHint}`);
+                }
+            } else if (Array.isArray(entry.joinKey)) {
+                if (entry.joinKey.length === 0) {
+                    throw new Error(`config.enrichments[${i}].joinKey must be a non-empty array when provided as an array.`);
+                }
+                for (let j = 0; j < entry.joinKey.length; j++) {
+                    const k = entry.joinKey[j];
+                    if (typeof k !== 'string' || !k.trim()) {
+                        throw new Error(`config.enrichments[${i}].joinKey[${j}] must be a non-empty string. Received: ${JSON.stringify(k)}`);
+                    }
+                    if (!sqlIdentifier.test(k)) {
+                        throw new Error(`config.enrichments[${i}].joinKey[${j}] must be a plain SQL identifier. Received: ${JSON.stringify(k)}.${aliasingHint}`);
+                    }
+                }
+            } else {
+                throw new Error(`config.enrichments[${i}].joinKey must be a string or a non-empty array of strings. Received: ${JSON.stringify(entry.joinKey)}`);
+            }
+            // columns: required, non-empty array of plain SQL identifiers (no aliasing).
+            if (!Array.isArray(entry.columns)) {
+                throw new Error(`config.enrichments[${i}].columns must be an array. Received: ${JSON.stringify(entry.columns)}`);
+            }
+            if (entry.columns.length === 0) {
+                throw new Error(`config.enrichments[${i}].columns must be non-empty. List the source columns to add to the output (excluding joinKey).`);
+            }
+            for (let j = 0; j < entry.columns.length; j++) {
+                const c = entry.columns[j];
+                if (typeof c !== 'string' || !c.trim()) {
+                    throw new Error(`config.enrichments[${i}].columns[${j}] must be a non-empty string. Received: ${JSON.stringify(c)}`);
+                }
+                if (!sqlIdentifier.test(c)) {
+                    throw new Error(`config.enrichments[${i}].columns[${j}] must be a plain SQL identifier. Received: ${JSON.stringify(c)}.${aliasingHint}`);
+                }
+            }
+            // dedupe: optional boolean
+            if (entry.dedupe !== undefined && typeof entry.dedupe !== 'boolean') {
+                throw new Error(`config.enrichments[${i}].dedupe must be a boolean when provided. Received: ${JSON.stringify(entry.dedupe)}`);
+            }
+        }
+    }
   } catch (e) {
     e.message = `Config validation: ${e.message}`;
     throw e;