@peernova/cuneiform-sf 1.0.2 → 1.0.4-beta.10

package/lib/services/DefinitionFieldGenerationService.js

@@ -0,0 +1,899 @@
+/*
+ * Copyright (c) 2026, PeerNova, Inc. All Rights Reserved.
+ * PROPRIETARY AND CONFIDENTIAL. Unauthorized copying, modification,
+ * or distribution is strictly prohibited. Use is governed by the
+ * Master Subscription Agreement (MSA) between PeerNova, Inc. and the
+ * licensee. See LICENSE file in the repo root.
+ */
+import { buildDateLiteralFilterJson, buildComparativeDateLiteralFilterJson, buildComparativeYearFilterJson, buildHistoricalYearFilterJson, buildLifetimeComparativeFilterJson, composeRecordTypeFilter, DATE_LITERAL_CONSTANTS, humanizeDateField, LITERAL_CASCADES, yearBoundaryISO, yearBoundaryDisplay, } from '../models/date-literal.js';
+/**
+ * Complete mapping of date literal keys to their expression builder constants
+ * and SOQL equivalents. Source: ISV `constantsUtils.js` in `fsc_expressionBuilder3`.
+ */
+const DATE_LITERAL_MAP = {
+    TODAY: { constant: '$Constant.Today', soqlLiteral: 'TODAY', displayName: 'Today' },
+    YESTERDAY: { constant: '$Constant.Yesterday', soqlLiteral: 'YESTERDAY', displayName: 'Yesterday' },
+    THIS_WEEK: { constant: '$Constant.ThisWeek', soqlLiteral: 'THIS_WEEK', displayName: 'This Week' },
+    LAST_WEEK: { constant: '$Constant.LastWeek', soqlLiteral: 'LAST_WEEK', displayName: 'Last Week' },
+    THIS_MONTH: { constant: '$Constant.ThisMonth', soqlLiteral: 'THIS_MONTH', displayName: 'This Month' },
+    LAST_MONTH: { constant: '$Constant.LastMonth', soqlLiteral: 'LAST_MONTH', displayName: 'Last Month' },
+    THIS_QUARTER: { constant: '$Constant.ThisQuarter', soqlLiteral: 'THIS_QUARTER', displayName: 'This Quarter' },
+    LAST_QUARTER: { constant: '$Constant.LastQuarter', soqlLiteral: 'LAST_QUARTER', displayName: 'Last Quarter' },
+    THIS_YEAR: { constant: '$Constant.ThisYear', soqlLiteral: 'THIS_YEAR', displayName: 'This Year' },
+    LAST_YEAR: { constant: '$Constant.LastYear', soqlLiteral: 'LAST_YEAR', displayName: 'Last Year' },
+    TWO_YEARS_AGO: { constant: '$Constant.TwoYearsAgo', soqlLiteral: 'N_YEARS_AGO:2', displayName: 'Two Years Ago' },
+    THREE_YEARS_AGO: {
+        constant: '$Constant.ThreeYearsAgo',
+        soqlLiteral: 'N_YEARS_AGO:3',
+        displayName: 'Three Years Ago',
+    },
+    LAST_TWO_YEARS: {
+        constant: '$Constant.LastTwoYears',
+        soqlLiteral: 'LAST_N_YEARS:2',
+        displayName: 'Last Two Years',
+    },
+    LAST_THREE_YEARS: {
+        constant: '$Constant.LastThreeYears',
+        soqlLiteral: 'LAST_N_YEARS:3',
+        displayName: 'Last Three Years',
+    },
+};
+/**
+ * Business process outcome field mapping.
+ * These boolean fields are system-maintained, universal across all orgs.
+ */
+const OUTCOME_FIELD_MAP = {
+    Opportunity: { fieldName: 'IsWon', trueLabel: 'Won', falseLabel: 'Lost' },
+    Case: { fieldName: 'IsClosed', trueLabel: 'Closed', falseLabel: 'Open' },
+    Lead: { fieldName: 'IsConverted', trueLabel: 'Converted', falseLabel: 'Unconverted' },
+};
+/**
+ * Pure field generation service for profiling definitions.
+ *
+ * Encapsulates stateless naming, categorisation, description, and candidate-input
+ * building logic extracted from DefinitionCreateOperation. Every method is
+ * `public static` — no constructor dependencies, no adapters, no connection.
+ *
+ * The DefinitionCreateOperation delegates to this service for:
+ * - Definition name resolution (buildName, resolveDefinitionName)
+ * - Category / time-category / segment-category resolution
+ * - Description template generation
+ * - Candidate input construction for metadata, historical, comparative, record-type, and outcome methods
+ * - Outcome field lookup and filter JSON construction
+ */
+export class DefinitionFieldGenerationService {
+    /** Exposes the date literal constant map for external consumers and tests. */
+    static DATE_LITERAL_MAP = DATE_LITERAL_MAP;
+    /** The bullet separator used in definition names. */
+    static NAME_SEPARATOR = ' \u2022 ';
+    // ── Public API (composition) ──────────────────────────────────────
+    /**
+     * Resolves the definition name from the method and context.
+     * Single source of truth for definition naming across all definition types.
+     *
+     * @param label - Object label (e.g., 'Account', 'Lead')
+     * @param method - ISV method (metadata, historical, comparative)
+     * @param context - Optional context: timeLabel, year, recordTypeName, outcomeLabels, unbounded
+     * @returns The formatted definition name
+     */
+    static resolveDefinitionName(label, method, context) {
+        // REQ-002 portability naming (CLI-4215): the bulk-recipe mode emits the simplified
+        // `${label} • ${suffix}` (object + suffix only, bullet delimiter per CLI-4215 review) and
+        // skips the `All Fields`/time-segment composition. namePrefix and the normal bullet suffix
+        // join do not apply here. The required suffix is enforced at the command boundary (CLI-4264);
+        // without one, fall back to the bare label rather than a trailing separator.
+        if (context?.portabilityNaming) {
+            return context.nameSuffix
+                ? `${label}${DefinitionFieldGenerationService.NAME_SEPARATOR}${context.nameSuffix}`
+                : label;
+        }
+        const baseName = DefinitionFieldGenerationService.buildName(label, method, context ?? {});
+        const sep = DefinitionFieldGenerationService.NAME_SEPARATOR;
+        // namePrefix joins with a plain space (matching REST path ISV behavior).
+        // nameSuffix joins with the bullet separator (• ).
+        const withSuffix = context?.nameSuffix ? `${baseName}${sep}${context.nameSuffix}` : baseName;
+        return context?.namePrefix ? `${context.namePrefix} ${withSuffix}` : withSuffix;
+    }
+    /**
+     * Resolves all definition metadata (category, timeCategory, segmentCategory, description)
+     * from the method and context. Single source of truth for definition classification.
+     *
+     * @param label - Object label (e.g., 'Account', 'Lead')
+     * @param method - ISV method (metadata, historical, comparative)
+     * @param context - Optional context: timeLabel, year, recordTypeName, outcomeLabels, overrides
+     * @returns Resolved metadata for the definition
+     */
+    static resolveDefinitionMetadata(label, method, context) {
+        const ctx = context ?? {};
+        return {
+            category: DefinitionFieldGenerationService.resolveCategory(method, ctx),
+            timeCategory: DefinitionFieldGenerationService.resolveTimeCategoryFromContext(method, ctx),
+            segmentCategory: DefinitionFieldGenerationService.resolveSegmentCategory(method, ctx),
+            description: ctx.descriptionOverride ??
+                DefinitionFieldGenerationService.resolveDescription(label, method, ctx) + (ctx.origin ? ` ${ctx.origin}` : ''),
+        };
+    }
+    /**
+     * Maps Salesforce objects to their outcome boolean fields.
+     *
+     * @param objectName - Salesforce object API name (e.g., 'Opportunity', 'Case', 'Lead')
+     * @returns Outcome field mapping, or undefined if the object has no outcome field
+     */
+    static getOutcomeField(objectName) {
+        return OUTCOME_FIELD_MAP[objectName];
+    }
+    /**
+     * Builds a single outcome definition input for a given object, outcome mapping, and optional time/RT context.
+     * Consolidates the repeated context + input construction pattern used across buildOutcomeCandidateInputs
+     * and buildInputsForRecordType.
+     *
+     * @param obj - Resolved SObject metadata
+     * @param outcome - Outcome field mapping for the object
+     * @param options - Field generation options
+     * @param timeLabel - Optional time label (e.g., 'This Year')
+     * @param recordTypeName - Optional record type developer name
+     * @param dateLiteral - Optional date literal key
+     * @param dateField - Optional date field API name
+     * @returns A single CreateDefinitionInput for the outcome comparison
+     */
+    static buildOutcomeInput(obj, outcome, options, timeLabel, recordTypeName, dateLiteral, dateField) {
+        const ctx = {
+            outcomeLabels: { trueLabel: outcome.trueLabel, falseLabel: outcome.falseLabel },
+            timeLabel,
+            recordTypeName: recordTypeName ?? options.recordType,
+            categoryOverride: options.category,
+            timeCategoryOverride: options.timeCategory,
+            segmentCategoryOverride: options.segmentCategory,
+            descriptionOverride: options.description,
+            noValueFrequency: options.noValueFrequency,
+            namePrefix: options.namePrefix,
+            nameSuffix: options.nameSuffix,
+            portabilityNaming: options.portabilityNaming,
+            origin: options.origin,
+            dateField,
+        };
+        return {
+            name: DefinitionFieldGenerationService.resolveDefinitionName(obj.label, 'metadata', ctx),
+            objectName: obj.name,
+            objectLabel: obj.label,
+            // CLI-3375: wire-level method='outcome' for outcome candidates (honest tagging).
+            // Internal name/metadata resolution still uses 'metadata' as the resolution key — the
+            // resolution functions key off semantic shape, not the wire-level method tag.
+            method: 'outcome',
+            ...DefinitionFieldGenerationService.resolveDefinitionMetadata(obj.label, 'metadata', ctx),
+            isActive: true,
+            noValueFrequency: options.noValueFrequency,
+            discoverFields: true,
+            recordTypeName: recordTypeName ?? options.recordType,
+            filterJson: DefinitionFieldGenerationService.buildOutcomeFilterJson(outcome.fieldName, obj.name, dateLiteral, dateField, obj.label),
+        };
+    }
+    /**
+     * Builds an ISV-compatible filterJson string for business process outcome comparisons.
+     * SetA filters for the true outcome, SetB filters for the false outcome.
+     * Produces the expression builder JSON schema that `fsc_expressionBuilder3` expects.
+     *
+     * @param fieldName - Boolean field API name (e.g., 'IsWon', 'IsClosed', 'IsConverted')
+     * @param objectName - Salesforce object API name (e.g., 'Opportunity', 'Case', 'Lead')
+     * @param dateLiteral - Optional date literal key for time-scoped outcome filters
+     * @param dateField - Optional date field API name
+     * @param objectLabel - Optional object label for display in date expressions
+     * @returns JSON string compatible with GlobalProfilingService.createProfilingDefinition()
+     */
+    static buildOutcomeFilterJson(fieldName, objectName, dateLiteral, dateField, objectLabel, yearBoundary) {
+        const buildExpression = (boolValue) => {
+            const expressions = [
+                {
+                    objectType: objectName,
+                    parameter: boolValue ? '$Constant.TrueValue' : '$Constant.FalseValue',
+                    parameterValue: String(boolValue),
+                    dataType: 'BOOLEAN',
+                    label: `${objectName}: ${fieldName}`,
+                    type: objectName,
+                    fieldName,
+                    operator: 'equals',
+                    operatorSymbol: '=',
+                    value: `$${objectName}.${fieldName}`,
+                    dateLiteral: '',
+                },
+            ];
+            if (dateLiteral && dateField) {
+                const constantValue = DATE_LITERAL_CONSTANTS[dateLiteral] ?? dateLiteral;
+                expressions.push({
+                    objectType: objectName,
+                    parameter: constantValue,
+                    parameterValue: dateLiteral,
+                    dataType: 'DATETIME',
+                    label: `${objectLabel ?? objectName}: ${humanizeDateField(dateField)}`,
+                    type: objectName,
+                    fieldName: dateField,
+                    operator: 'equals',
+                    operatorSymbol: '=',
+                    value: `$${objectName}.${dateField}`,
+                    dateLiteral,
+                });
+            }
+            // Year boundary expressions: >= Jan 1 YYYY AND < Jan 1 YYYY+1
+            if (yearBoundary && dateField) {
+                const yField = dateField;
+                const yLabel = `${objectLabel ?? objectName}: ${humanizeDateField(dateField)}`;
+                const yValue = `$${objectName}.${yField}`;
+                // yearBoundaryISO and yearBoundaryDisplay imported from date-literal.ts
+                const yearStart = yearBoundaryISO(yearBoundary.year);
+                const yearEnd = yearBoundaryISO(yearBoundary.year + 1);
+                const yearStartDisplay = yearBoundaryDisplay(yearBoundary.year);
+                const yearEndDisplay = yearBoundaryDisplay(yearBoundary.year + 1);
+                expressions.push({
+                    objectType: objectName,
+                    parameter: yearStartDisplay,
+                    parameterValue: yearStart,
+                    dataType: 'DATETIME',
+                    label: yLabel,
+                    type: objectName,
+                    fieldName: yField,
+                    operator: 'greater_or_equal',
+                    operatorSymbol: '>=',
+                    value: yValue,
+                    dateLiteral: '',
+                });
+                expressions.push({
+                    objectType: objectName,
+                    parameter: yearEndDisplay,
+                    parameterValue: yearEnd,
+                    dataType: 'DATETIME',
+                    label: yLabel,
+                    type: objectName,
+                    fieldName: yField,
+                    operator: 'less_than',
+                    operatorSymbol: '<',
+                    value: yValue,
+                    dateLiteral: '',
+                });
+            }
+            return { expressions, logicType: 'AND' };
+        };
+        let dateClause = '';
+        if (dateLiteral && dateField) {
+            dateClause = ` AND ${dateField} = ${dateLiteral}`;
+        }
+        else if (yearBoundary && dateField) {
+            // yearBoundaryISO imported from date-literal.ts
+            dateClause = ` AND ${dateField} >= ${yearBoundaryISO(yearBoundary.year)} AND ${dateField} < ${yearBoundaryISO(yearBoundary.year + 1)}`;
+        }
+        const payload = {
+            hasFilters: true,
+            setA: { json: buildExpression(true), expression: `${fieldName} = true${dateClause}` },
+            setB: { json: buildExpression(false), expression: `${fieldName} = false${dateClause}` },
+        };
+        return JSON.stringify(payload);
+    }
+    // ── Naming / Metadata Resolution ──────────────────────────────────
+    /**
+     * Builds the base definition name from an object label, method, and context.
+     *
+     * @param label - Object label (e.g., 'Account', 'Lead')
+     * @param method - ISV method string
+     * @param ctx - Definition metadata context
+     * @returns Formatted base definition name (without prefix/suffix)
+     */
+    static buildName(label, method, ctx) {
+        const s = DefinitionFieldGenerationService.NAME_SEPARATOR;
+        const prefix = ctx.recordTypeName ? `${label}${s}All Fields${s}${ctx.recordTypeName}` : `${label}${s}All Fields`;
+        if (ctx.outcomeLabels) {
+            const timeSegment = ctx.timeLabel ?? 'Lifetime';
+            // Outcome variants embed the trueLabel vs falseLabel in the name, which already
+            // carries the semantic distinction. The noValueFrequency disambiguator is omitted
+            // here because outcome definitions never share names with non-outcome definitions
+            // of the same object.
+            return `${prefix}${s}${timeSegment}${s}${ctx.outcomeLabels.trueLabel} vs ${ctx.outcomeLabels.falseLabel}`;
+        }
+        if (method === 'metadata') {
+            // Metadata-only definitions never capture value frequency, so the disambiguator
+            // would be a meaningless name change. Metadata names remain stable.
+            return `${prefix}${s}Metadata Only`;
+        }
+        // Resolve the time segment for non-metadata, non-outcome variants.
+        let timeSegment;
+        if (ctx.lifetimePrimary) {
+            // Lifetime-vs-X comparative variant (CLI-2944) — name's time segment is "Lifetime vs {timeLabel}".
+            timeSegment = `Lifetime vs ${DefinitionFieldGenerationService.resolveLifetimeTimeLabel(ctx)}`;
+        }
+        else if (ctx.timeLabel) {
+            // Comparative definitions include "vs Prior" to distinguish from historical with the same time label.
+            // Without this, "Account • All Fields • This Year" would collide for both methods in --method full.
+            timeSegment = method === 'comparative' ? `${ctx.timeLabel} vs Prior` : ctx.timeLabel;
+        }
+        else if (method === 'historical') {
+            timeSegment = ctx.year !== undefined ? `${ctx.year}` : 'Lifetime';
+        }
+        else {
+            // Comparative with year — include time dimension in name
+            const effectiveYear = ctx.year ?? new Date().getFullYear();
+            timeSegment = ctx.unbounded ? `${effectiveYear} vs Prior` : `${effectiveYear} vs ${effectiveYear - 1}`;
+        }
+        // CLI-3064: Append "No Value Frequency" disambiguator when noValueFrequency is set.
+        // Mirrors the comparative `vs Prior` disambiguator pattern above — without this,
+        // value-frequency and no-value-frequency variants of the same (object, method,
+        // time-segment, recordType) collide on the name-keyed dedup gate and the second is
+        // silently skipped. The disambiguator becomes part of the base name so user-supplied
+        // `--name-prefix` and `--name-suffix` compose cleanly around it in resolveDefinitionName.
+        const variantSuffix = ctx.noValueFrequency ? `${s}No Value Frequency` : '';
+        return `${prefix}${s}${timeSegment}${variantSuffix}`;
+    }
+    /**
+     * Resolves the time-segment label for the lifetime-vs-X comparative variant. Prefers an explicit
+     * timeLabel (set by the operation layer for date literals or year-range spans), then falls back
+     * to the year for single-year cascade entries. Used by buildName, resolveTimeCategoryFromContext,
+     * and resolveDescription so the lifetime variant renders consistently.
+     */
+    static resolveLifetimeTimeLabel(ctx) {
+        if (ctx.timeLabel)
+            return ctx.timeLabel;
+        if (ctx.year !== undefined)
+            return String(ctx.year);
+        return 'Lifetime';
+    }
+    /**
+     * Resolves the primary category from method and context.
+     *
+     * @param method - ISV method string
+     * @param ctx - Definition metadata context
+     * @returns Category string (e.g., 'Metadata', 'Baseline', 'Comparative', 'Record Types')
+     */
+    static resolveCategory(method, ctx) {
+        if (ctx.categoryOverride)
+            return ctx.categoryOverride;
+        if (ctx.outcomeLabels)
+            return 'Comparative';
+        if (ctx.recordTypeName)
+            return 'Record Types';
+        if (method === 'metadata')
+            return 'Metadata';
+        return 'Baseline';
+    }
+    /**
+     * Resolves the time category from method and context.
+     *
+     * @param method - ISV method string
+     * @param ctx - Definition metadata context
+     * @returns Time category string (e.g., 'N/A', 'Lifetime', '2025 vs 2024')
+     */
+    static resolveTimeCategoryFromContext(method, ctx) {
+        if (ctx.timeCategoryOverride)
+            return ctx.timeCategoryOverride;
+        if (method === 'metadata' && !ctx.outcomeLabels)
+            return 'N/A';
+        // Lifetime-vs-X comparative variant (CLI-2944) — timeCategory mirrors the name's time segment.
+        if (ctx.lifetimePrimary) {
+            return `Lifetime vs ${DefinitionFieldGenerationService.resolveLifetimeTimeLabel(ctx)}`;
+        }
+        if (ctx.timeLabel) {
+            // Match buildName: comparative with time label uses "vs Prior" suffix
+            if (method === 'comparative' && !ctx.outcomeLabels)
+                return `${ctx.timeLabel} vs Prior`;
+            return ctx.timeLabel;
+        }
+        if (ctx.year !== undefined && method === 'comparative') {
+            return ctx.unbounded ? `${ctx.year} vs Prior` : `${ctx.year} vs ${ctx.year - 1}`;
+        }
+        if (ctx.year !== undefined)
+            return String(ctx.year);
+        return 'Lifetime';
+    }
+    /**
+     * Resolves the segment category from method and context.
+     *
+     * @param method - ISV method string
+     * @param ctx - Definition metadata context
+     * @returns Segment category string (e.g., 'N/A', 'Historical', 'Comparative', record type name)
+     */
+    static resolveSegmentCategory(method, ctx) {
+        if (ctx.segmentCategoryOverride)
+            return ctx.segmentCategoryOverride;
+        // Outcome check must precede metadata check because outcomes use method='metadata' at the ISV boundary
+        if (ctx.outcomeLabels)
+            return `${ctx.outcomeLabels.trueLabel} vs ${ctx.outcomeLabels.falseLabel}`;
+        if (method === 'metadata')
+            return 'N/A';
+        if (ctx.recordTypeName)
+            return ctx.recordTypeName;
+        // Lifetime-vs-X comparative variant (CLI-2944) — segmentCategory is "Comparative" regardless of
+        // whether the secondary filter is year-based or date-literal-based (AC8).
+        if (ctx.lifetimePrimary)
+            return 'Comparative';
+        if (method === 'comparative' && (ctx.year !== undefined || ctx.timeLabel !== undefined))
+            return 'Comparative';
+        return 'Historical';
+    }
+    /**
+     * Generates a human-readable description from label, method, and context.
+     *
+     * @param label - Object label (e.g., 'Account', 'Lead')
+     * @param method - ISV method string
+     * @param ctx - Definition metadata context
+     * @returns Generated description string
+     */
+    static resolveDescription(label, method, ctx) {
+        // Metadata-only (CRa) — no field statistics or value frequency
+        if (method === 'metadata' && !ctx.outcomeLabels) {
+            return (`Metadata profiling for ${label}. Captures Salesforce object and field metadata including ` +
+                'data types, namespaces, field descriptions, help text, and custom field dependency counts across ' +
+                'layouts, reports, and low-code/pro-code sources. Does not capture field profiling statistics, ' +
+                'value frequency results, or KPI results.');
+        }
+        // Build captures clause based on noValueFrequency
+        const captures = ctx.noValueFrequency
+            ? 'Captures object and field metadata, field utilization rates, and distinctness and default value analysis'
+            : 'Captures object and field metadata, field utilization rates, distinctness and default value analysis, and value frequency distributions';
+        const boundary = ctx.noValueFrequency
+            ? ' Does not capture value frequency distributions or KPI results.'
+            : ' Does not capture KPI results.';
+        // Business process outcome comparison (SetA + SetB)
+        if (ctx.outcomeLabels) {
+            return (`Business outcome comparison for ${label} \u2014 ${ctx.outcomeLabels.trueLabel} vs ${ctx.outcomeLabels.falseLabel}. ` +
+                `${captures} for both ${ctx.outcomeLabels.trueLabel} and ${ctx.outcomeLabels.falseLabel} record sets.${boundary}`);
+        }
+        // Lifetime-vs-X comparative variant (CLI-2944) \u2014 must precede recordTypeName branch so the
+        // lifetime template wins when both lifetimePrimary and recordTypeName are set (AC9 second template).
+        if (ctx.lifetimePrimary) {
+            const lifetimeLabel = DefinitionFieldGenerationService.resolveLifetimeTimeLabel(ctx);
+            if (ctx.recordTypeName) {
+                return (`Comparative profiling for ${label} (${ctx.recordTypeName}) \u2014 all records vs records from ${lifetimeLabel}, ` +
+                    `scoped to the ${ctx.recordTypeName} record type. ${captures} for both record sets.${boundary}`);
+            }
+            return (`Comparative profiling for ${label} \u2014 all records vs records from ${lifetimeLabel}. ` +
+                `${captures} for both the complete record set and the ${lifetimeLabel} record set.${boundary}`);
+        }
+        // Record type scoped
+        if (ctx.recordTypeName) {
+            const scope = ctx.timeLabel
+                ? `filtered to ${ctx.timeLabel}`
+                : ctx.year !== undefined
+                    ? `comparing ${ctx.year} vs ${ctx.year - 1}`
+                    : 'across all records';
+            return (`Record type profiling for ${label} \u2014 ${ctx.recordTypeName}. ` +
+                `${captures} scoped to the ${ctx.recordTypeName} record type ${scope}.${boundary}`);
+        }
+        // Historical / comparative with date literal
+        if (ctx.timeLabel) {
+            const dateFieldLabel = humanizeDateField(ctx.dateField ?? 'CreatedDate');
+            return (`Historical profiling for ${label} \u2014 ${ctx.timeLabel}. ` +
+                `${captures} across the profiled record set. Records filtered to ${ctx.timeLabel} by ${dateFieldLabel}.${boundary}`);
+        }
+        // Historical lifetime (no filter)
+        if (method === 'historical') {
+            return (`Historical profiling for ${label} \u2014 all records. ` +
+                `${captures} across the complete record set with no time-based filtering.${boundary}`);
+        }
+        // Year-based comparative
+        const y = ctx.year ?? new Date().getFullYear();
+        return (`Comparative profiling for ${label} \u2014 ${y} vs ${y - 1}. ` +
+            `${captures} across the profiled record set.${boundary}`);
+    }
+    // ── Candidate Input Builders ──────────────────────────────────────
+    /**
+     * Selects the comparative filter JSON for a date-literal entry.
+     * lifetimePrimary → SetA empty (all records), SetB = supplied literal.
+     * regular comparative → SetA = literal, SetB = prior from LITERAL_CASCADES[literal][1]; falls back to SetA-only when no prior exists.
+     * historical/metadata → SetA only.
+     */
+    static pickDateLiteralComparativeFilter(literal, isLifetimeComparative, dateField, objectName, objectLabel, isRegularComparative) {
+        if (isLifetimeComparative) {
+            return buildLifetimeComparativeFilterJson(dateField, { kind: 'dateLiteral', literal }, objectName, objectLabel);
+        }
+        if (isRegularComparative) {
+            const priorLiteral = LITERAL_CASCADES[literal][1];
+            if (priorLiteral) {
+                return buildComparativeDateLiteralFilterJson(dateField, literal, priorLiteral, objectName, objectLabel);
+            }
+        }
+        return buildDateLiteralFilterJson(dateField, literal, objectName, objectLabel);
+    }
+    /**
+     * Selects the comparative filter JSON for a year-range entry. Returns the lifetime-vs-X
+     * variant when in lifetimePrimary mode; otherwise the existing year-vs-prior comparative
+     * filter (CLI-2944).
+     */
+    static pickYearComparativeFilter(entry, lifetimePrimary, objectName, objectLabel) {
+        if (lifetimePrimary) {
+            return buildLifetimeComparativeFilterJson('CreatedDate', { kind: 'year', year: entry.year }, objectName, objectLabel);
+        }
+        return buildComparativeYearFilterJson('CreatedDate', entry.year, !!entry.unbounded, objectName, objectLabel);
+    }
+    /**
+     * Builds candidate CreateDefinitionInput entries for non-recordtype methods.
+     *
+     * For comparative method, creates one input per object per YearRange entry.
+     * For metadata/historical, creates one input per object (yearRange is ignored).
+     *
+     * @param objects - Resolved SObject metadata entries
+     * @param method - ISV method (metadata, historical, comparative)
+     * @param year - Comparative year (default: current year)
+     * @param yearRange - Resolved year range entries
+     * @param options - Field generation options
+     * @returns Array of candidate definition inputs
+     */
+    static buildCandidateInputs(objects, method, year, yearRange, options) {
+        const inputs = [];
+        // CLI-3375: metadata-only definitions are filter-irrelevant by contract — they describe field
+        // shape, not time-scoped data. Producing one (object × dateLiteralEntry) input with filterJson
+        // populated caused two leaks: (1) the persisted record carried a misleading CreatedDate filter,
+        // and (2) DefinitionQueryBuilder.buildCreateDefinitionRequestBody's guard
+        // `input.method==='metadata' && !input.filterJson` falsified, falling through to the default
+        // `["CRa","CRb","CRc"]` insightGroups instead of the `["CRa"]` metadata-only set. Collapse to
+        // one filter-free input per object for the metadata variant; historical/comparative continue
+        // to expand over the date-literal range below.
+        if (options.dateLiteralRange && options.dateLiteralRange.entries.length > 0 && method === 'metadata') {
+            return DefinitionFieldGenerationService.buildMetadataInputsForObjects(objects, options);
+        }
+        if (options.dateLiteralRange && options.dateLiteralRange.entries.length > 0) {
+            return DefinitionFieldGenerationService.buildDateLiteralInputs(objects, method, options);
+        }
+        // Year-based path (existing behavior)
+        if (method === 'comparative' && yearRange.entries.length > 0) {
+            const lifetimePrimary = options.lifetimePrimary === true;
+            for (const obj of objects) {
+                for (const entry of yearRange.entries) {
+                    const filterJson = DefinitionFieldGenerationService.pickYearComparativeFilter(entry, lifetimePrimary, obj.name, obj.label);
+                    const ctx = {
+                        year: entry.year,
+                        unbounded: entry.unbounded,
+                        lifetimePrimary,
+                        recordTypeName: options.recordType,
+                        categoryOverride: options.category,
+                        timeCategoryOverride: options.timeCategory,
+                        segmentCategoryOverride: options.segmentCategory,
+                        descriptionOverride: options.description,
+                        noValueFrequency: options.noValueFrequency,
+                        namePrefix: options.namePrefix,
+                        nameSuffix: options.nameSuffix,
+                        portabilityNaming: options.portabilityNaming,
+                        origin: options.origin,
+                    };
+                    inputs.push({
+                        name: DefinitionFieldGenerationService.resolveDefinitionName(obj.label, method, ctx),
+                        objectName: obj.name,
+                        objectLabel: obj.label,
+                        method,
+                        ...DefinitionFieldGenerationService.resolveDefinitionMetadata(obj.label, method, ctx),
+                        isActive: true,
+                        lifetimePrimary,
+                        noValueFrequency: options.noValueFrequency,
+                        recordTypeName: options.recordType,
+                        discoverFields: true,
+                        filterJson,
+                    });
+                }
+            }
+        }
+        else {
+            for (const obj of objects) {
+                const isComparative = method === 'comparative';
+                // Only apply year to historical when explicitly requested (not as part of --method full)
+                const historicalWithYear = method === 'historical' && options.year !== undefined && options.method === 'historical';
+                const ctx = {
+                    year: isComparative || historicalWithYear ? year : undefined,
+                    unbounded: options.usePrior,
+                    recordTypeName: options.recordType,
+                    categoryOverride: options.category,
+                    timeCategoryOverride: options.timeCategory,
+                    segmentCategoryOverride: options.segmentCategory,
+                    descriptionOverride: options.description,
+                    noValueFrequency: options.noValueFrequency,
+                    namePrefix: options.namePrefix,
+                    nameSuffix: options.nameSuffix,
+                    portabilityNaming: options.portabilityNaming,
+                    origin: options.origin,
+                };
+                // Build filter JSON based on method + year
+                let filterJson;
+                if (isComparative) {
+                    filterJson = buildComparativeYearFilterJson('CreatedDate', year, !!options.usePrior, obj.name, obj.label);
+                }
+                else if (historicalWithYear) {
+                    filterJson = buildHistoricalYearFilterJson('CreatedDate', year, obj.name, obj.label);
+                }
+                inputs.push({
+                    name: DefinitionFieldGenerationService.resolveDefinitionName(obj.label, method, ctx),
+                    objectName: obj.name,
+                    objectLabel: obj.label,
+                    method,
+                    ...DefinitionFieldGenerationService.resolveDefinitionMetadata(obj.label, method, ctx),
+                    isActive: true,
+                    noValueFrequency: options.noValueFrequency,
+                    recordTypeName: options.recordType,
+                    discoverFields: true,
+                    ...(filterJson ? { filterJson } : {}),
+                });
+            }
+        }
+        return inputs;
+    }
+    /**
+     * Builds candidate inputs for a single record type on a single object.
+     *
+     * Creates 1 historical + N comparative definitions (one per YearRange entry).
+     * For outcome-capable objects in full method, also adds outcome split per RT.
+     *
+     * CLI-3834: every emitted input carries a `filterJson` whose SetA carries a `RecordTypeId =
+     * <rt.id>` condition AND-composed with any existing time scope. SetB receives the same scope
+     * when the underlying filter helper produces it (year-based comparative). Without this, the
+     * server-side WHERE clause has no RT filter and profiling runs object-wide.
+     *
+     * @param obj - Resolved SObject metadata
+     * @param rt - Record type reference (id + developer name) — typically the upstream `RecordTypeInfo`. `id` is used to populate the server-side filter; `name` populates the label/segment fields.
+     * @param yearRange - Resolved year range entries
+     * @param options - Field generation options
+     * @returns Array of candidate definition inputs for this record type
+     */
+    static buildInputsForRecordType(obj, rt, yearRange, options) {
+        const inputs = [];
+        // Only cross record types with outcomes in full method — standalone --method recordtype should not add outcome variants
+        const outcome = options.method === 'full' ? DefinitionFieldGenerationService.getOutcomeField(obj.name) : undefined;
+        const composeRt = (existing) => composeRecordTypeFilter(existing, rt.id, obj.name, obj.label);
+        // Date literal path: create one definition per date literal entry (no lifetime baseline)
+        if (options.dateLiteralRange && options.dateLiteralRange.entries.length > 0) {
+            const dateField = options.dateLiteralRange.dateField;
+            for (const dlEntry of options.dateLiteralRange.entries) {
+                const ctx = {
+                    timeLabel: dlEntry.label,
+                    dateField,
+                    recordTypeName: rt.name,
+                    categoryOverride: options.category,
+                    timeCategoryOverride: options.timeCategory,
+                    segmentCategoryOverride: options.segmentCategory,
+                    descriptionOverride: options.description,
+                    noValueFrequency: options.noValueFrequency,
+                    namePrefix: options.namePrefix,
+                    nameSuffix: options.nameSuffix,
+                    portabilityNaming: options.portabilityNaming,
+                    origin: options.origin,
+                };
+                inputs.push({
+                    name: DefinitionFieldGenerationService.resolveDefinitionName(obj.label, 'comparative', ctx),
+                    objectName: obj.name,
+                    objectLabel: obj.label,
+                    method: 'comparative',
+                    ...DefinitionFieldGenerationService.resolveDefinitionMetadata(obj.label, 'comparative', ctx),
+                    isActive: true,
+                    noValueFrequency: options.noValueFrequency,
+                    recordTypeName: rt.name,
+                    discoverFields: true,
+                    filterJson: composeRt(buildDateLiteralFilterJson(dateField, dlEntry.literal, obj.name, obj.label)),
+                });
+                // Outcome x record type x date literal: for outcome-capable objects, add outcome split per RT per time
+                if (outcome) {
+                    const outcomeInput = DefinitionFieldGenerationService.buildOutcomeInput(obj, outcome, options, dlEntry.label, rt.name, dlEntry.literal, dateField);
+                    outcomeInput.filterJson = composeRt(outcomeInput.filterJson);
+                    inputs.push(outcomeInput);
+                }
+            }
+            return inputs;
+        }
+        // Year-based path (existing behavior)
+        // 1. Lifetime historical (no year filter) — shows overall record type usage
+        const lifetimeCtx = {
+            recordTypeName: rt.name,
+            categoryOverride: options.category,
+            timeCategoryOverride: options.timeCategory,
+            segmentCategoryOverride: options.segmentCategory,
+            descriptionOverride: options.description,
+            noValueFrequency: options.noValueFrequency,
+            namePrefix: options.namePrefix,
+            nameSuffix: options.nameSuffix,
+            portabilityNaming: options.portabilityNaming,
+            origin: options.origin,
+        };
+        inputs.push({
+            name: DefinitionFieldGenerationService.resolveDefinitionName(obj.label, 'historical', lifetimeCtx),
+            objectName: obj.name,
+            objectLabel: obj.label,
+            method: 'historical',
+            ...DefinitionFieldGenerationService.resolveDefinitionMetadata(obj.label, 'historical', lifetimeCtx),
+            isActive: true,
+            noValueFrequency: options.noValueFrequency,
+            recordTypeName: rt.name,
+            discoverFields: true,
+            filterJson: composeRt(undefined),
+        });
+        // Outcome x record type (Lifetime): for outcome-capable objects, add outcome split per RT
+        if (outcome) {
+            const outcomeInput = DefinitionFieldGenerationService.buildOutcomeInput(obj, outcome, options, undefined, rt.name);
+            outcomeInput.filterJson = composeRt(outcomeInput.filterJson);
+            inputs.push(outcomeInput);
+        }
+        // 2+. Comparative definitions from year range entries
+        for (const entry of yearRange.entries) {
+            const compCtx = {
+                year: entry.year,
+                unbounded: entry.unbounded,
+                recordTypeName: rt.name,
+                categoryOverride: options.category,
+                timeCategoryOverride: options.timeCategory,
+                segmentCategoryOverride: options.segmentCategory,
+                descriptionOverride: options.description,
+                noValueFrequency: options.noValueFrequency,
+                namePrefix: options.namePrefix,
+                nameSuffix: options.nameSuffix,
+                portabilityNaming: options.portabilityNaming,
+                origin: options.origin,
+            };
+            inputs.push({
+                name: DefinitionFieldGenerationService.resolveDefinitionName(obj.label, 'comparative', compCtx),
+                objectName: obj.name,
+                objectLabel: obj.label,
+                method: 'comparative',
+                ...DefinitionFieldGenerationService.resolveDefinitionMetadata(obj.label, 'comparative', compCtx),
+                isActive: true,
+                noValueFrequency: options.noValueFrequency,
+                recordTypeName: rt.name,
+                discoverFields: true,
+                filterJson: composeRt(buildComparativeYearFilterJson('CreatedDate', entry.year, !!entry.unbounded, obj.name, obj.label)),
+            });
+        }
+        return inputs;
+    }
+    /**
+     * Builds candidate inputs for business process outcome profiling.
+     * Creates one definition per object that has a business process outcome boolean field.
+     *
+     * @param objects - Resolved SObject metadata entries
+     * @param options - Field generation options
+     * @param warnings - Mutable warnings array to append skip messages (standalone callers only)
+     * @param yearRange - Optional year range for outcome scoping
+     * @param cascade - Optional accumulator. Presence signals cascade-mode (`buildFullCandidateInputs`):
+     * objects with no outcome field are silently skipped — no warning is emitted (CLI-3611).
+     * Absence is the standalone caller (`--method outcome`) — per-object warning fires as before.
+     * @returns Array of candidate definition inputs for outcome-capable objects
+     */
+    static buildOutcomeCandidateInputs(objects, options, warnings, yearRange, cascade) {
+        const inputs = [];
+        for (const obj of objects) {
+            const outcome = DefinitionFieldGenerationService.getOutcomeField(obj.name);
+            if (!outcome) {
+                if (!cascade) {
+                    warnings.push(`${obj.name} has no outcome field — skipped for outcome profiling.`);
+                }
+                // CLI-3611: cascade mode (--method full) silently skips objects without outcome fields.
+                // Outcome support is limited to Opportunity/Case/Lead by platform design — skipping
+                // other objects is expected, not an error condition worth surfacing to the user.
+                continue;
+            }
+            // Date literal path: create one outcome definition per object x date literal entry
+            if (options.dateLiteralRange && options.dateLiteralRange.entries.length > 0) {
+                const dateField = options.dateLiteralRange.dateField;
+                for (const dlEntry of options.dateLiteralRange.entries) {
+                    inputs.push(DefinitionFieldGenerationService.buildOutcomeInput(obj, outcome, options, dlEntry.label, undefined, dlEntry.literal, dateField));
+                }
+                continue;
+            }
+            // Year path: create one outcome definition per year, scoped to that year.
+            // Outcome splits (Won vs Lost) operate within each year — both SetA and SetB
+            // are scoped to the same time window. --use-prior (unbounded) is silently
+            // ignored — the year is used for scoping regardless.
+            if (yearRange && yearRange.entries.length > 0) {
+                for (const entry of yearRange.entries) {
+                    const ctx = {
+                        outcomeLabels: { trueLabel: outcome.trueLabel, falseLabel: outcome.falseLabel },
+                        timeLabel: String(entry.year),
+                        year: entry.year,
+                        unbounded: false,
+                        recordTypeName: options.recordType,
+                        categoryOverride: options.category,
+                        timeCategoryOverride: options.timeCategory,
+                        segmentCategoryOverride: options.segmentCategory,
+                        descriptionOverride: options.description,
+                        noValueFrequency: options.noValueFrequency,
+                        namePrefix: options.namePrefix,
+                        nameSuffix: options.nameSuffix,
+                        portabilityNaming: options.portabilityNaming,
+                        origin: options.origin,
+                    };
+                    inputs.push({
+                        name: DefinitionFieldGenerationService.resolveDefinitionName(obj.label, 'metadata', ctx),
+                        objectName: obj.name,
+                        objectLabel: obj.label,
+                        // CLI-3375: wire-level method='outcome' for year-scoped outcome candidates (honest tagging).
+                        // Name/metadata resolution still keys off 'metadata' — semantic shape only.
+                        method: 'outcome',
+                        ...DefinitionFieldGenerationService.resolveDefinitionMetadata(obj.label, 'metadata', ctx),
+                        isActive: true,
+                        noValueFrequency: options.noValueFrequency,
+                        discoverFields: true,
+                        recordTypeName: options.recordType,
+                        filterJson: DefinitionFieldGenerationService.buildOutcomeFilterJson(outcome.fieldName, obj.name, undefined, 'CreatedDate', obj.label, { year: entry.year, unbounded: entry.unbounded }),
+                    });
+                }
+                continue;
+            }
+            // Lifetime path (no date literal, no year): original behavior — single definition per object
+            inputs.push(DefinitionFieldGenerationService.buildOutcomeInput(obj, outcome, options));
+        }
+        return inputs;
+    }
+    /**
+     * Builds one filter-free metadata-only input per object. Extracted from `buildCandidateInputs`
+     * (CLI-3375) to enforce the contract that a metadata-only definition is filter-irrelevant by
+     * design — independent of whether the caller passed a date-literal range. Used by the
+     * metadata-variant short-circuit at the top of `buildCandidateInputs`.
+     */
+    static buildMetadataInputsForObjects(objects, options) {
+        const inputs = [];
+        for (const obj of objects) {
+            const ctx = {
+                recordTypeName: options.recordType,
+                categoryOverride: options.category,
+                timeCategoryOverride: options.timeCategory,
+                segmentCategoryOverride: options.segmentCategory,
+                descriptionOverride: options.description,
+                noValueFrequency: options.noValueFrequency,
+                namePrefix: options.namePrefix,
+                nameSuffix: options.nameSuffix,
+                portabilityNaming: options.portabilityNaming,
+                origin: options.origin,
+            };
+            inputs.push({
+                name: DefinitionFieldGenerationService.resolveDefinitionName(obj.label, 'metadata', ctx),
+                objectName: obj.name,
+                objectLabel: obj.label,
+                method: 'metadata',
+                ...DefinitionFieldGenerationService.resolveDefinitionMetadata(obj.label, 'metadata', ctx),
+                isActive: true,
+                noValueFrequency: options.noValueFrequency,
+                recordTypeName: options.recordType,
+                discoverFields: true,
+            });
+        }
+        return inputs;
+    }
+    /**
+     * Builds (object × dateLiteralEntry) inputs for historical and comparative methods. Extracted
+     * from `buildCandidateInputs` (CLI-3375) to keep that method's cyclomatic complexity within
+     * lint limits after introducing the metadata-variant short-circuit. The metadata variant does
+     * NOT route through here — see `buildMetadataInputsForObjects` for that path.
+     */
+    static buildDateLiteralInputs(objects, 
+    // Includes 'metadata' for type compatibility with the caller's narrower union; in practice the
+    // caller short-circuits the metadata variant via `buildMetadataInputsForObjects` before reaching here.
+    method, options) {
+        const inputs = [];
+        const dateField = options.dateLiteralRange.dateField;
+        for (const obj of objects) {
+            for (const dlEntry of options.dateLiteralRange.entries) {
+                const isLifetimeComparative = method === 'comparative' && options.lifetimePrimary === true;
+                const isRegularComparative = method === 'comparative' && options.lifetimePrimary !== true;
+                const ctx = {
+                    timeLabel: dlEntry.label,
+                    dateField,
+                    lifetimePrimary: isLifetimeComparative,
+                    recordTypeName: options.recordType,
+                    categoryOverride: options.category,
+                    timeCategoryOverride: options.timeCategory,
+                    segmentCategoryOverride: options.segmentCategory,
+                    descriptionOverride: options.description,
+                    noValueFrequency: options.noValueFrequency,
+                    namePrefix: options.namePrefix,
+                    nameSuffix: options.nameSuffix,
+                    portabilityNaming: options.portabilityNaming,
+                    origin: options.origin,
+                };
+                const filterJson = DefinitionFieldGenerationService.pickDateLiteralComparativeFilter(dlEntry.literal, isLifetimeComparative, dateField, obj.name, obj.label, isRegularComparative);
+                inputs.push({
+                    name: DefinitionFieldGenerationService.resolveDefinitionName(obj.label, method, ctx),
+                    objectName: obj.name,
+                    objectLabel: obj.label,
+                    method,
+                    ...DefinitionFieldGenerationService.resolveDefinitionMetadata(obj.label, method, ctx),
+                    isActive: true,
+                    lifetimePrimary: isLifetimeComparative,
+                    noValueFrequency: options.noValueFrequency,
+                    recordTypeName: options.recordType,
+                    discoverFields: true,
+                    filterJson,
+                });
+            }
+        }
+        return inputs;
+    }
+}
+//# sourceMappingURL=DefinitionFieldGenerationService.js.map