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

package/lib/operations/DefinitionCreateOperation.js

@@ -0,0 +1,1270 @@
+/*
+ * 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 { createSuccessResult, createFailureResult } from '../models/service-result.js';
+import { MAX_PAGINATION_LIMIT } from '../services/constants.js';
+import { DefinitionFieldGenerationService } from '../services/DefinitionFieldGenerationService.js';
+/**
+ * Error codes specific to create operations.
+ */
+export const CreateErrorCodes = {
+    /** Object filtering failed */
+    FILTER_FAILED: 'CREATE_FILTER_FAILED',
+    /** No objects found matching filters */
+    NO_OBJECTS_FOUND: 'CREATE_NO_OBJECTS_FOUND',
+    /** None of the specified --objects exist in the org */
+    OBJECTS_NOT_FOUND: 'CREATE_OBJECTS_NOT_FOUND',
+    /** Operation failed unexpectedly */
+    OPERATION_FAILED: 'CREATE_OPERATION_FAILED',
+    /** No objects have been profiled yet */
+    NO_PROFILED_OBJECTS: 'CREATE_NO_PROFILED_OBJECTS',
+    /** REQ-002 portability run is missing the required category (CLI-4215) */
+    PORTABILITY_CATEGORY_REQUIRED: 'CREATE_PORTABILITY_CATEGORY_REQUIRED',
+};
+/**
+ * Orchestrates bulk creation of profiling definitions for filtered objects.
+ *
+ * Follows the 4-layer architecture: Command -> Operation -> Service -> API
+ * This operation layer handles business logic orchestration:
+ * 1. Filters objects using ObjectFilteringService
+ * 2. Checks for existing definitions using ProfilingDefinitionService
+ * 3. Creates definitions for new objects only (deduplication)
+ * 4. Reports created/failed/skipped statistics
+ *
+ * Pure field generation logic (naming, categorisation, description, candidate inputs)
+ * is delegated to DefinitionFieldGenerationService.
+ */
+/**
+ * Format a name list for inline display in a cascade-summary warning: first 5 names
+ * joined by ', ', with a `, +K more` suffix when the total exceeds 5. The asymmetric
+ * "5 concrete + 1 magnitude number" balances category recognition against terminal width.
+ *
+ * Module-scope (not a class method) — pure transformation, no instance or static class
+ * dependencies. See `emitCascadeSummaries` for the consumer (CLI-3341).
+ */
+const CASCADE_SUMMARY_TRUNCATE_AT = 5;
+function formatTruncatedNames(names) {
+    if (names.length <= CASCADE_SUMMARY_TRUNCATE_AT)
+        return names.join(', ');
+    const visible = names.slice(0, CASCADE_SUMMARY_TRUNCATE_AT).join(', ');
+    const overflow = names.length - CASCADE_SUMMARY_TRUNCATE_AT;
+    return `${visible}, +${overflow} more`;
+}
+/**
+ * Emit at most one aggregated summary line for the `--method full` cascade —
+ * one for the non-empty RT skip bucket. Mirrors the single-summary pattern at
+ * `buildFullCandidateInputs` for RecordTypeService absence + RT inputs failure.
+ *
+ * No prefix is used (matches the existing single-summary warning convention in this file);
+ * the `X of N objects` phrasing differentiates aggregate from per-object warnings.
+ *
+ * Truncation: first 5 names listed inline, with `, +K more` suffix when total > 5.
+ * When the bucket is empty, no line is emitted (suppression rule).
+ *
+ * `rtStatus` parity: when `rtStatus === 'all'`, the qualifier is dropped to match the
+ * standalone warning shape ('has no record types' vs 'has no active record types').
+ *
+ * CLI-3611: outcome skip bucket removed — silently skipping objects without outcome
+ * fields is expected platform behavior in --method full, not an error condition.
+ */
+function emitCascadeSummaries(cascade, totalObjects, rtStatus, warnings) {
+    if (cascade.noRecordTypes.length > 0) {
+        const qualifier = rtStatus === 'all' ? '' : `${rtStatus} `;
+        warnings.push(`${cascade.noRecordTypes.length} of ${totalObjects} objects have no ${qualifier}record types — record type variant omitted (${formatTruncatedNames(cascade.noRecordTypes)}).`);
+    }
+}
+export class DefinitionCreateOperation {
+    definitionService;
+    filteringService;
+    logger;
+    profilingSummaryService;
+    recordTypeService;
+    dataAvailabilityService;
+    restClient;
+    /** Exposes the date literal constant map for external consumers and tests. */
+    static DATE_LITERAL_MAP = DefinitionFieldGenerationService.DATE_LITERAL_MAP;
+    /** The bullet separator used in definition names. */
+    static NAME_SEPARATOR = DefinitionFieldGenerationService.NAME_SEPARATOR;
+    /**
+     * Creates a new DefinitionCreateOperation instance.
+     *
+     * @param definitionService - Service for creating and querying profiling definitions
+     * @param filteringService - Service for filtering Salesforce objects
+     * @param logger - Optional logger for debug output
+     * @param profilingSummaryService - Optional service for querying profiled objects (required when profiled=true)
+     * @param recordTypeService - Optional service for querying record types (required when method=recordtype)
+     */
+    constructor(definitionService, filteringService, logger, profilingSummaryService, recordTypeService, dataAvailabilityService, restClient) {
+        this.definitionService = definitionService;
+        this.filteringService = filteringService;
+        this.logger = logger;
+        this.profilingSummaryService = profilingSummaryService;
+        this.recordTypeService = recordTypeService;
+        this.dataAvailabilityService = dataAvailabilityService;
+        this.restClient = restClient;
+    }
+    // ── Public Static Methods ────────────────────────────────────────────
+    /**
+     * 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(...args) {
+        return DefinitionFieldGenerationService.resolveDefinitionName(...args);
+    }
+    /**
+     * Resolves all definition metadata (category, timeCategory, segmentCategory, description)
+     * from the method and context. Single source of truth for definition classification.
+     */
+    static resolveDefinitionMetadata(...args) {
+        return DefinitionFieldGenerationService.resolveDefinitionMetadata(...args);
+    }
+    /**
+     * Formats a human-readable message for a per-object result.
+     */
+    static formatObjectMessage(result) {
+        switch (result.status) {
+            case 'success':
+                return `created "${result.definitionName}"`;
+            case 'skip':
+                return 'definition already exists';
+            case 'fail':
+                return result.error ?? 'unknown error';
+            case 'preview':
+                return `would create "${result.definitionName}"`;
+        }
+    }
+    /**
+     * Derives the time category display value from an input's method and year.
+     */
+    static resolveTimeCategory(input) {
+        if (!input)
+            return undefined;
+        if (input.timeCategory)
+            return input.timeCategory;
+        if (input.method === 'metadata')
+            return 'N/A';
+        if (input.comparativeYear !== undefined) {
+            return input.usePrior
+                ? `${input.comparativeYear} vs Prior`
+                : `${input.comparativeYear} vs ${input.comparativeYear - 1}`;
+        }
+        if (input.historicalYear !== undefined) {
+            return String(input.historicalYear);
+        }
+        return 'Lifetime';
+    }
+    /**
+     * Derives the segment category display value from an input. Prefers the
+     * pre-resolved `input.segmentCategory` (populated by the field generation
+     * service, which honors the --segment-category override and falls back to
+     * method-derived defaults like 'N/A', 'Historical', or record type name).
+     * Falls back to `input.recordTypeName` for back-compat with consumers that
+     * build inputs without going through `resolveDefinitionMetadata`.
+     */
+    static resolveSegmentCategory(input) {
+        if (!input)
+            return undefined;
+        return input.segmentCategory ?? input.recordTypeName;
+    }
+    /**
+     * 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 DefinitionFieldGenerationService.getOutcomeField(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.
+     */
+    static buildOutcomeInput(...args) {
+        return DefinitionFieldGenerationService.buildOutcomeInput(...args);
+    }
+    /**
+     * 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')
+     * @returns JSON string compatible with GlobalProfilingService.createProfilingDefinition()
+     */
+    static buildOutcomeFilterJson(...args) {
+        return DefinitionFieldGenerationService.buildOutcomeFilterJson(...args);
+    }
+    // ── Private Static Helpers (execution) ────────────────────────────
+    /**
+     * Applies outcome pre-filtering for the REST path. For outcome method, only objects
+     * with outcome fields (Opportunity, Case, Lead) are eligible. Returns a failure result
+     * when no eligible objects remain; otherwise returns the filtered array.
+     */
+    /**
+     * Composes the `nameSuffix` value sent to the ISV `create-smart` REST endpoint, layering the
+     * `No Value Frequency` disambiguator ahead of any user-supplied `--name-suffix`. The bullet
+     * separator prefix (`• `) is required because the server joins suffix segments with a
+     * plain space — this CLI carries the bullet so the final rendered name reads consistently
+     * with locally-built names from `DefinitionFieldGenerationService.buildName`.
+     *
+     * CLI-3064: Without the disambiguator, value-frequency and no-value-frequency variants of
+     * the same (object, method, time-segment) resolve to identical names on both client and
+     * server; the second invocation is silently dropped by the name-keyed dedup gate. Layering
+     * the disambiguator ahead of the user suffix preserves the user's `--name-suffix` semantics
+     * while disambiguating the variant.
+     *
+     * @param userSuffix - User-supplied `--name-suffix` value (optional)
+     * @param noValueFrequency - True when the request originates from `--no-value-frequency`
+     * @returns Composed suffix to send as `SmartCreateRequest.options.nameSuffix`, or undefined when neither applies
+     */
+    static composeRestNameSuffix(userSuffix, noValueFrequency) {
+        const SEP = '• ';
+        const variant = noValueFrequency ? 'No Value Frequency' : undefined;
+        if (variant && userSuffix)
+            return `${SEP}${variant} ${SEP}${userSuffix}`;
+        if (variant)
+            return `${SEP}${variant}`;
+        if (userSuffix)
+            return `${SEP}${userSuffix}`;
+        return undefined;
+    }
+    /**
+     * Applies a NamespaceFilter to a list of objects (CLI-3801).
+     *
+     * Mirrors the semantics of ObjectFilteringService.applyNamespaceFilter so the
+     * profiled-objects path produces the same set as the filtered-objects path
+     * when given the same filter.
+     */
+    static mergeUnresolvedFailures(result, unresolvedNames) {
+        if (unresolvedNames.length === 0 || !result.success)
+            return result;
+        const data = result.data;
+        data.failed += unresolvedNames.length;
+        data.total += unresolvedNames.length;
+        for (const name of unresolvedNames) {
+            data.failures.push({ objectName: name, error: 'Object not found in org', errorCode: 'E4101' });
+        }
+        return result;
+    }
+    static applyNamespaceFilter(objects, filter) {
+        if (filter === undefined || filter.kind === 'all')
+            return objects;
+        if (filter.kind === 'unmanaged') {
+            return objects.filter((obj) => obj.namespace === undefined);
+        }
+        const lowerSet = new Set(filter.namespaces.map((n) => n.toLowerCase()));
+        return objects.filter((obj) => obj.namespace !== undefined && lowerSet.has(obj.namespace.toLowerCase()));
+    }
+    static applyOutcomeFilter(objects, method, emptyResult, startTime) {
+        if (method !== 'outcome')
+            return objects;
+        const eligible = objects.filter((o) => DefinitionCreateOperation.getOutcomeField(o.name) !== undefined);
+        if (eligible.length === 0) {
+            return createFailureResult(emptyResult, CreateErrorCodes.NO_OBJECTS_FOUND, 'No objects with outcome fields found. Outcome definitions support Opportunity (Won vs Lost), Case (Closed vs Open), and Lead (Converted vs Unconverted) only.', { metadata: { duration: Date.now() - startTime } });
+        }
+        return eligible;
+    }
+    /**
+     * Invokes the onPreviewReady callback if provided and not in dry-run mode.
+     * Returns a cancellation result if the user declines, or undefined to proceed.
+     */
+    static async invokePreviewCallback(options, createInputs, skippedInputs, totalCount, skippedCount, recordCounts, emptyResult, startTime) {
+        if (!options.onPreviewReady || options.dryRun)
+            return undefined;
+        try {
+            const proceed = await options.onPreviewReady({
+                toCreate: createInputs,
+                toSkip: skippedInputs,
+                total: totalCount,
+                recordCounts,
+            });
+            if (!proceed) {
+                return createSuccessResult({ ...emptyResult, cancelled: true, skipped: skippedCount, total: totalCount }, { message: 'Creation cancelled by user.', metadata: { duration: Date.now() - startTime } });
+            }
+            return undefined;
+        }
+        catch (err) {
+            return createFailureResult(emptyResult, CreateErrorCodes.OPERATION_FAILED, `Confirmation prompt failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    /**
+     * Maps a server-side SmartCreateDefinitionResult to an ObjectResult.
+     */
+    static mapServerResult(sr) {
+        return {
+            objectName: sr.objectName,
+            objectLabel: sr.objectName,
+            status: sr.status === 'created'
+                ? 'success'
+                : sr.status === 'skipped'
+                    ? 'skip'
+                    : sr.status === 'preview'
+                        ? 'preview'
+                        : 'fail',
+            definitionName: sr.definitionName,
+            definitionId: sr.definitionId,
+            definitionKey: sr.definitionKey,
+            fieldCount: sr.fieldCount,
+            type: sr.type,
+            category: sr.category,
+            timeCategory: sr.timeCategory,
+            segmentCategory: sr.segmentCategory,
+        };
+    }
+    /** Derives the definition type for a dry-run preview result from the requested method. */
+    static derivePreviewType(method) {
+        if (method === 'metadata')
+            return 'metadata';
+        if (method === 'historical')
+            return 'historical';
+        return 'comparative';
+    }
+    /** Derives the definition category for a dry-run preview result from the requested method. */
+    static derivePreviewCategory(method) {
+        if (method === 'metadata')
+            return 'Metadata';
+        if (method === 'recordtype')
+            return 'Record Types';
+        if (method === 'outcome')
+            return 'Comparative';
+        return 'Baseline';
+    }
+    /**
+     * Normalizes a REST-path result for dry-run uniformity (CLI-1832).
+     *
+     * When options.dryRun is true and the server returned status='skipped' (because the
+     * definition already exists), the JSON result's per-item status is remapped to 'preview'
+     * so callers see uniform dry-run output across create and skip paths. This mirrors the
+     * local-path buildDryRunResult behavior (see :936-937). Progress callbacks still fire
+     * with status='skip' so human UX differentiates "already exists" from "would create".
+     *
+     * After normalization, type/category are back-filled from the method when undefined
+     * (ISV create-smart omits classification fields per CLI-1756). 'full' is excluded
+     * because it produces multiple definition types per object.
+     */
+    static normalizeDryRunResult(r, sr, isDryRun, method) {
+        if (isDryRun && sr.status === 'skipped') {
+            // eslint-disable-next-line no-param-reassign -- normalizing result status in-place for uniform dry-run output (CLI-1832)
+            r.status = 'preview';
+        }
+        if (r.status === 'preview' && r.type === undefined && method !== 'full') {
+            // eslint-disable-next-line no-param-reassign -- back-filling classification in-place (CLI-1756: ISV omits these)
+            r.type = DefinitionCreateOperation.derivePreviewType(method);
+            // eslint-disable-next-line no-param-reassign -- back-filling classification in-place (CLI-1756)
+            r.category = DefinitionCreateOperation.derivePreviewCategory(method);
+        }
+        // CLI-3392: ISV create-smart omits classification for skipped definitions outside dry-run too.
+        if (!isDryRun && sr.status === 'skipped' && r.type === undefined && method !== 'full') {
+            // eslint-disable-next-line no-param-reassign -- back-filling classification in-place (CLI-3392: ISV omits type/category for skipped)
+            r.type = DefinitionCreateOperation.derivePreviewType(method);
+            // eslint-disable-next-line no-param-reassign -- back-filling classification in-place (CLI-3392)
+            r.category = r.category ?? DefinitionCreateOperation.derivePreviewCategory(method);
+        }
+    }
+    /** Fires the onObjectComplete progress callback for a single processed result. */
+    static notifyObjectComplete(r, sr, current, total, options) {
+        // CLI-1832: dry-run normalizes server 'skipped' → r.status='preview' for uniform JSON
+        // output. The progress callback still surfaces 'skip' from the original server status
+        // so human UX differentiates "already exists" from "would create". This mirrors
+        // buildDryRunResult's local-path behavior (see :936-937 and :945).
+        const callbackStatus = sr.status === 'skipped' ? 'skip' : r.status === 'preview' ? 'preview' : r.status;
+        const callbackMessage = sr.status === 'skipped'
+            ? 'definition already exists'
+            : r.status === 'success'
+                ? `created "${r.definitionName}"`
+                : r.status === 'skip'
+                    ? 'definition already exists'
+                    : r.error ?? sr.errorMessage ?? 'unknown';
+        options.onObjectComplete?.({
+            objectName: r.objectName,
+            status: callbackStatus,
+            message: callbackMessage,
+            current,
+            total,
+            type: r.type,
+            definitionName: r.definitionName,
+            definitionKey: r.definitionKey,
+            recordTypeName: r.segmentCategory,
+            category: r.category,
+            timeCategory: r.timeCategory,
+            segmentCategory: r.segmentCategory,
+            fieldCount: r.fieldCount,
+        });
+    }
+    // ── Public Instance Methods ──────────────────────────────────────────
+    /**
+     * Executes the definition create operation.
+     *
+     * @param options - Create operation options
+     * @returns ServiceResult containing creation statistics
+     */
+    // eslint-disable-next-line complexity -- 7-step orchestration pipeline with error handling at each step
+    async execute(options) {
+        const startTime = Date.now();
+        const emptyResult = {
+            created: 0,
+            failed: 0,
+            skipped: 0,
+            total: 0,
+            failures: [],
+            results: [],
+        };
+        try {
+            this.logger?.log('Starting definition create operation');
+            const operationWarnings = [];
+            // CLI-4215 (REQ-002): the bulk-recipe portability path requires a category applied
+            // identically to every definition in the run. Fail closed before any object
+            // resolution or writes when it is missing or blank.
+            if (options.portabilityNaming === true && (options.category === undefined || options.category.trim() === '')) {
+                return createFailureResult(emptyResult, CreateErrorCodes.PORTABILITY_CATEGORY_REQUIRED, 'A category is required for REQ-002 bulk runs. Supply a non-empty category so every definition in the run is grouped consistently.', { metadata: { duration: Date.now() - startTime } });
+            }
+            // Step 1: Resolve objects
+            const resolveResult = await this.resolveObjects(options, operationWarnings);
+            if (!resolveResult.success) {
+                return createFailureResult(emptyResult, resolveResult.errorCode, resolveResult.message, {
+                    metadata: { duration: Date.now() - startTime },
+                });
+            }
+            // CLI-4214: thread the record-count reconciliation truncation disclosure (surfaced by the
+            // filtered-objects path) into the operation warnings so callers never lose it.
+            if (resolveResult.warnings && resolveResult.warnings.length > 0) {
+                operationWarnings.push(...resolveResult.warnings);
+            }
+            // CLI-4090: Track explicitly-requested objects that were not found in the org.
+            // These are surfaced as failures in the final result so the exit code reflects
+            // the partial failure.
+            const unresolvedNames = options.objects && options.objects.length > 0
+                ? options.objects.filter((name) => !resolveResult.data.some((obj) => obj.name.toLowerCase() === name.toLowerCase()))
+                : [];
+            const objectsBeforeLimit = this.applyMinRecordsThreshold(resolveResult.data, options, emptyResult, startTime);
+            if (!Array.isArray(objectsBeforeLimit))
+                return objectsBeforeLimit;
+            // Step 1b: Apply --limit to cap the number of objects processed
+            const { limited: objects, warning: objectLimitWarning } = this.applyObjectLimit(objectsBeforeLimit, options.limit);
+            if (objectLimitWarning) {
+                operationWarnings.push(objectLimitWarning);
+            }
+            // Step 2: Fetch record counts for resolved objects
+            const uniqueObjectNames = [...new Set(objects.map((o) => o.name))];
+            const countsResult = await this.filteringService.getRecordCounts(uniqueObjectNames);
+            const recordCounts = countsResult.success ? countsResult.data : new Map();
+            const method = options.method ?? 'metadata';
+            const year = options.year ?? new Date().getFullYear();
+            // Resolve year range: prefer explicit yearRange, fall back to year + usePrior
+            const yearRange = options.yearRange ?? {
+                entries: method === 'metadata' ? [] : [{ year, unbounded: options.usePrior ?? false }],
+            };
+            options.onProgress?.(`Checking existing definitions for ${objects.length} objects...`);
+            // Step 2.5: Build data availability grid (concurrent with Step 3)
+            let availabilityGrid;
+            if (this.dataAvailabilityService && yearRange.entries.length > 0) {
+                const gridResult = await this.dataAvailabilityService.buildGrid(uniqueObjectNames, yearRange);
+                if (gridResult.success) {
+                    availabilityGrid = gridResult.data;
+                }
+                else {
+                    this.logger?.log(`Data availability grid failed: ${gridResult.message ?? 'unknown'}`);
+                }
+            }
+            // REST API path: delegate to server when restClient is available.
+            // Fall back to the local path when:
+            //   method='full'                                — server creates only 1 definition; local path composes all sub-methods
+            //   lifetimePrimary=true                         — ISV Apex DefinitionFieldGenerationService has no lifetime-primary
+            //                                                  support (CLI-2944); local path pre-computes the lifetime filter
+            //                                                  JSON, name, timeCategory, and segmentCategory and persists them
+            //                                                  verbatim via create-definition. Remove this branch once the ISV
+            //                                                  Apex side mirrors the TS lifetime logic.
+            //   timeCategory or segmentCategory override set — local path applies overrides verbatim through ctx builders (CLI-2957).
+            // CLI-3099 (ISV-7889 + ISV-7888 deployed): the previous "force local path for comparative
+            // + dateLiteralRange" clause was removed once ISV smart-create began emitting SetA+SetB
+            // filterJson for the comparative + dateLiteralEntries path. Comparative date-literal
+            // cascades now flow through the server smart-create endpoint like every other method.
+            // CLI-3425 + CLI-3834: force local path for ALL method=recordtype invocations — the ISV
+            // create-smart endpoint (a) ignores options.category for method=recordtype standalone,
+            // silently storing the hard-coded default "Record Types" instead, and (b) does NOT populate
+            // the server-side RT-scope filter fields (Prop_IsFiltered_SetA__c, Prop_Filter_JSON_SetA__c,
+            // Prop_Filter_SetA__c), so post-CLI-3834 defs would profile object-wide rather than restricted
+            // to the chosen RT. The local path (a) sends primaryCategory verbatim and (b) composes the
+            // RecordTypeId equality into filterJson via composeRecordTypeFilter (CLI-3843 + 770268a2 Id
+            // quoting). Both --category and --recordtype filters are honoured in the local fan-out.
+            // CLI-3446: force local path for historical + dateLiteralRange — the ISV create-smart
+            // endpoint fails to translate `:N`-suffix literals (N_YEARS_AGO:N, LAST_N_YEARS:N) into
+            // filterJson, producing defs with IsFiltered_SetA=false and Filter_JSON_SetA=null. The
+            // local path constructs filterJson correctly via buildDateLiteralFilterJson. Remove the
+            // historical dateLiteralRange disjunct once the ISV create-smart endpoint mirrors the TS
+            // date-literal logic for historical methods.
+            // CLI-4215 (REQ-002 portability naming): force the local path so definition names are
+            // built deterministically by DefinitionFieldGenerationService as `${label} • ${suffix}`.
+            // The ISV create-smart endpoint joins suffix segments server-side, which cannot guarantee
+            // the exact form REQ-002 requires; the local path applies the simplified naming verbatim.
+            const useLocalPath = options.method === 'full' ||
+                options.lifetimePrimary === true ||
+                options.timeCategory !== undefined ||
+                options.segmentCategory !== undefined ||
+                (options.dateLiteralRange !== undefined && options.method === 'historical') ||
+                options.method === 'recordtype' ||
+                options.portabilityNaming === true;
+            if (this.restClient && !useLocalPath) {
+                return DefinitionCreateOperation.mergeUnresolvedFailures(await this.executeCreationViaRest(objects, options, operationWarnings, startTime, availabilityGrid, recordCounts), unresolvedNames);
+            }
+            // Step 3: Check for existing definitions (local path — fallback when no REST client)
+            const existingDefsResult = await this.fetchAllExistingDefinitions();
+            if (!existingDefsResult.success) {
+                this.logger?.log('Failed to query existing definitions');
+            }
+            const existingDefinitions = existingDefsResult.success ? existingDefsResult.data : [];
+            const existingNames = new Set(existingDefinitions.map((def) => def.name));
+            // Step 4: Build candidate inputs
+            const candidateResult = await this.buildCandidateInputsForMethod(objects, method, year, yearRange, options, operationWarnings);
+            if (!candidateResult.success) {
+                return createFailureResult(emptyResult, candidateResult.errorCode, candidateResult.message, {
+                    metadata: { duration: Date.now() - startTime },
+                });
+            }
+            const candidateInputs = candidateResult.data;
+            // Step 5: Deduplicate (partition into create vs skip)
+            const createInputsBeforeLimit = [];
+            const skippedInputs = [];
+            for (const input of candidateInputs) {
+                if (existingNames.has(input.name)) {
+                    skippedInputs.push(input);
+                }
+                else {
+                    createInputsBeforeLimit.push(input);
+                }
+            }
+            const skippedCount = skippedInputs.length;
+            if (createInputsBeforeLimit.length === 0) {
+                const totalDefs = candidateInputs.length;
+                if (totalDefs === 0) {
+                    // No candidates generated (e.g., no record types found for --method recordtype)
+                    return createFailureResult({ ...emptyResult, total: 0 }, CreateErrorCodes.NO_OBJECTS_FOUND, operationWarnings.length > 0
+                        ? `No candidate definitions were generated: ${operationWarnings.join('; ')}`
+                        : 'No candidate definitions were generated. Check object filters, record types, or method selection.', { metadata: { duration: Date.now() - startTime } });
+                }
+                // CLI-3419 AC14: all N candidates already exist — idempotent skip-only success.
+                // Bypass the preview callback (nothing to create, nothing to confirm) and delegate
+                // to the dry-run / create path with empty createInputs so the skip callbacks fire
+                // and the result carries `created=0, skipped=N, success=true`.
+                this.logger?.log(`All ${totalDefs} definitions already exist`);
+                if (options.dryRun) {
+                    return DefinitionCreateOperation.mergeUnresolvedFailures(this.buildDryRunResult([], skippedInputs, totalDefs, operationWarnings, options, startTime, availabilityGrid, recordCounts), unresolvedNames);
+                }
+                return DefinitionCreateOperation.mergeUnresolvedFailures(await this.executeCreation([], skippedInputs, totalDefs, operationWarnings, options, startTime, availabilityGrid, recordCounts), unresolvedNames);
+            }
+            this.logger?.log(`${createInputsBeforeLimit.length} definitions to create, ${skippedCount} already exist`);
+            // Apply --limit safety cap
+            const { limited: createInputs, warning: limitWarning } = this.applyInputLimit(createInputsBeforeLimit, options.limit);
+            if (limitWarning) {
+                operationWarnings.push(limitWarning);
+            }
+            const totalForPreview = createInputs.length + skippedCount;
+            options.onProgress?.(`${totalForPreview} ${totalForPreview === 1 ? 'definition' : 'definitions'} to create`);
+            // Step 6: Preview callback (unless dry-run)
+            const cancelResult = await DefinitionCreateOperation.invokePreviewCallback(options, createInputs, skippedInputs, candidateInputs.length, skippedCount, recordCounts, emptyResult, startTime);
+            if (cancelResult)
+                return cancelResult;
+            // Step 7: Dry run or create
+            if (options.dryRun) {
+                return DefinitionCreateOperation.mergeUnresolvedFailures(this.buildDryRunResult(createInputs, skippedInputs, candidateInputs.length, operationWarnings, options, startTime, availabilityGrid, recordCounts), unresolvedNames);
+            }
+            return DefinitionCreateOperation.mergeUnresolvedFailures(await this.executeCreation(createInputs, skippedInputs, candidateInputs.length, operationWarnings, options, startTime, availabilityGrid, recordCounts), unresolvedNames);
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            this.logger?.log(`Definition create operation failed: ${errorMessage}`);
+            return createFailureResult(emptyResult, CreateErrorCodes.OPERATION_FAILED, errorMessage, {
+                metadata: { duration: Date.now() - startTime },
+            });
+        }
+    }
+    // ── Private Instance Methods ─────────────────────────────────────────
+    /**
+     * Applies the --min-records threshold, returning the filtered list or an early failure result.
+     */
+    applyMinRecordsThreshold(objects, options, emptyResult, startTime) {
+        if (!options.minRecords || options.minRecords <= 0)
+            return objects;
+        const filtered = this.applyMinRecordsFilter(objects, options.minRecords);
+        if (filtered.length === 0) {
+            return createFailureResult(emptyResult, CreateErrorCodes.NO_OBJECTS_FOUND, `No objects found with at least ${options.minRecords} records`, { metadata: { duration: Date.now() - startTime } });
+        }
+        return filtered;
+    }
+    /**
+     * Builds record-type candidate inputs by querying the RecordTypeService for each object.
+     *
+     * @param cascade - Optional accumulator. Presence signals cascade-mode (`buildFullCandidateInputs`):
+     * objects with no record types are pushed to `cascade.noRecordTypes` instead of warning per-object.
+     * Absence is the standalone caller \u2014 per-object warnings fire as before.
+     * Only the empty-result branch is routed; failed-query and `--recordtype X` no-match branches
+     * remain per-object (a query failure is genuinely per-object actionable, and a user-specified
+     * record-type narrowing justifies per-object diagnostics).
+     */
+    async buildRecordTypeCandidateInputs(objects, yearRange, options, warnings, cascade) {
+        if (!this.recordTypeService) {
+            return createFailureResult([], CreateErrorCodes.OPERATION_FAILED, 'RecordTypeService is required when method=recordtype');
+        }
+        const inputs = [];
+        const isSingleObject = objects.length === 1;
+        const rtStatus = options.recordTypeStatus ?? 'active';
+        for (const obj of objects) {
+            // eslint-disable-next-line no-await-in-loop -- Sequential per-object queries with per-object error handling
+            const rtResult = await this.recordTypeService.getRecordTypesByStatus(obj.name, rtStatus);
+            if (!rtResult.success) {
+                warnings.push(`Failed to query record types for ${obj.name}: ${rtResult.message}`);
+                continue;
+            }
+            let recordTypes = rtResult.data;
+            if (recordTypes.length === 0) {
+                if (cascade) {
+                    cascade.noRecordTypes.push(obj.name);
+                }
+                else {
+                    const statusLabel = rtStatus === 'all' ? '' : ` ${rtStatus}`;
+                    warnings.push(`Object '${obj.name}' has no${statusLabel} record types \u2014 skipping.`);
+                }
+                continue;
+            }
+            // Apply --recordtype filter (case-insensitive on Name OR DeveloperName).
+            // DeveloperName matching supports cross-org scripting where Names may be
+            // translated/customized but DeveloperNames are stable API identifiers.
+            if (options.recordType) {
+                const targetLower = options.recordType.toLowerCase();
+                recordTypes = recordTypes.filter((rt) => rt.name.toLowerCase() === targetLower || rt.developerName.toLowerCase() === targetLower);
+                if (recordTypes.length === 0) {
+                    if (isSingleObject) {
+                        const available = rtResult.data
+                            .map((rt) => (rt.name === rt.developerName ? rt.name : `${rt.name} (${rt.developerName})`))
+                            .join(', ');
+                        return createFailureResult([], CreateErrorCodes.NO_OBJECTS_FOUND, `Record type '${options.recordType}' not found on ${obj.name}. Active record types: ${available}`);
+                    }
+                    warnings.push(`Object '${obj.name}' does not have record type '${options.recordType}' \u2014 skipping.`);
+                    continue;
+                }
+            }
+            for (const rt of recordTypes) {
+                // CLI-3834: pass the full record-type ref (id + name) so buildInputsForRecordType
+                // can populate the server-side filter fields with the RT scope. Passing rt.name
+                // alone caused profiling to run object-wide.
+                inputs.push(...DefinitionFieldGenerationService.buildInputsForRecordType(obj, rt, yearRange, options));
+            }
+        }
+        return createSuccessResult(inputs);
+    }
+    /**
+     * Builds full candidate inputs by composing metadata + historical + comparative + recordtype methods.
+     * Degrades gracefully to metadata + historical + comparative when RecordTypeService is absent.
+     */
+    async buildFullCandidateInputs(objects, year, yearRange, options, warnings) {
+        // Cascade-mode accumulator: per-builder empty-result skips push here instead of
+        // emitting per-object warnings. After both builders run, we emit at most one
+        // aggregated summary line (RT bucket only). Mirrors the single-summary pattern
+        // already established below for RecordTypeService absence (CLI-3341).
+        //
+        // CLI-3611: outcome bucket removed — silently skipping objects without outcome
+        // fields is expected behavior in --method full (platform limits to Opportunity/Case/Lead).
+        const cascade = { noRecordTypes: [] };
+        // Phase 1: Build metadata + historical + comparative inputs
+        const allInputs = [
+            ...DefinitionFieldGenerationService.buildCandidateInputs(objects, 'metadata', year, yearRange, options),
+            ...DefinitionFieldGenerationService.buildCandidateInputs(objects, 'historical', year, yearRange, options),
+            ...DefinitionFieldGenerationService.buildCandidateInputs(objects, 'comparative', year, yearRange, options),
+        ];
+        // Phase 1b: Build business process outcome inputs (always available — no service dependency)
+        // yearRange applies when user explicitly provided --year/--from/--to (options.year is set).
+        // Without explicit year flags, outcome defaults to lifetime (no year scoping).
+        const outcomeYearRange = options.year !== undefined ? yearRange : undefined;
+        allInputs.push(...DefinitionFieldGenerationService.buildOutcomeCandidateInputs(objects, options, warnings, outcomeYearRange, cascade));
+        // Phase 2: Build recordtype inputs (soft degradation if service absent)
+        if (!this.recordTypeService) {
+            warnings.push('RecordTypeService not available — full method degrading to metadata + historical + comparative + outcome only.');
+            emitCascadeSummaries(cascade, objects.length, options.recordTypeStatus ?? 'active', warnings);
+            return createSuccessResult(allInputs);
+        }
+        const rtResult = await this.buildRecordTypeCandidateInputs(objects, yearRange, options, warnings, cascade);
+        const rtInputs = rtResult.success ? rtResult.data : [];
+        if (!rtResult.success) {
+            warnings.push(`Record type inputs failed: ${rtResult.message ?? 'unknown error'} — using metadata + historical + comparative only.`);
+        }
+        // Emit aggregated skip summaries for both buckets (suppressed when bucket is empty).
+        emitCascadeSummaries(cascade, objects.length, options.recordTypeStatus ?? 'active', warnings);
+        // Phase 3: Merge and deduplicate by name (defensive — names are structurally distinct)
+        const seen = new Set();
+        const merged = [];
+        for (const input of [...allInputs, ...rtInputs]) {
+            if (!seen.has(input.name)) {
+                seen.add(input.name);
+                merged.push(input);
+            }
+        }
+        return createSuccessResult(merged);
+    }
+    /**
+     * Builds candidate inputs for any method, delegating to the appropriate builder.
+     */
+    async buildCandidateInputsForMethod(objects, method, year, yearRange, options, warnings) {
+        if (method === 'recordtype') {
+            return this.buildRecordTypeCandidateInputs(objects, yearRange, options, warnings);
+        }
+        if (method === 'outcome') {
+            // Only apply yearRange when user explicitly provided --year/--from/--to
+            const outcomeYR = options.year !== undefined ? yearRange : undefined;
+            return createSuccessResult(DefinitionFieldGenerationService.buildOutcomeCandidateInputs(objects, options, warnings, outcomeYR));
+        }
+        if (method === 'full') {
+            return this.buildFullCandidateInputs(objects, year, yearRange, options, warnings);
+        }
+        return createSuccessResult(DefinitionFieldGenerationService.buildCandidateInputs(objects, method, year, yearRange, options));
+    }
+    /**
+     * Builds a dry run result without creating any definitions.
+     */
+    buildDryRunResult(createInputs, skippedInputs, totalCount, warnings, options, startTime, availabilityGrid, recordCounts) {
+        // Build preview results from the inputs (fieldCount unavailable in dry runs)
+        const results = [];
+        for (const input of createInputs) {
+            results.push({
+                objectName: input.objectName,
+                objectLabel: input.objectLabel,
+                status: 'preview',
+                definitionName: input.name,
+                type: input.method,
+                category: input.category,
+                timeCategory: DefinitionCreateOperation.resolveTimeCategory(input),
+                segmentCategory: DefinitionCreateOperation.resolveSegmentCategory(input),
+            });
+        }
+        for (const input of skippedInputs) {
+            results.push({
+                objectName: input.objectName,
+                objectLabel: input.objectLabel,
+                status: 'preview',
+                definitionName: input.name,
+                type: DefinitionCreateOperation.derivePreviewType(options.method ?? 'metadata'),
+                category: input.category ?? DefinitionCreateOperation.derivePreviewCategory(options.method ?? 'metadata'),
+                timeCategory: DefinitionCreateOperation.resolveTimeCategory(input),
+                segmentCategory: DefinitionCreateOperation.resolveSegmentCategory(input),
+            });
+        }
+        // Fire callbacks — createInputs get 'preview', skippedInputs get 'skip' (progress display only;
+        // JSON result uses 'preview' for both so callers see a uniform dry-run output).
+        if (options.onObjectComplete) {
+            const createCount = createInputs.length;
+            for (let i = 0; i < results.length; i++) {
+                const r = results[i];
+                const isSkipped = i >= createCount;
+                options.onObjectComplete({
+                    objectName: r.objectName,
+                    status: isSkipped ? 'skip' : 'preview',
+                    message: isSkipped ? 'definition already exists' : `would create "${r.definitionName}"`,
+                    current: i + 1,
+                    total: results.length,
+                    type: r.type,
+                    definitionName: r.definitionName,
+                    definitionKey: r.definitionKey,
+                    recordTypeName: r.segmentCategory,
+                    category: r.category,
+                    timeCategory: r.timeCategory,
+                    segmentCategory: r.segmentCategory,
+                });
+            }
+        }
+        const dryRunResult = {
+            created: createInputs.length,
+            failed: 0,
+            skipped: skippedInputs.length,
+            total: totalCount,
+            dryRun: true,
+            failures: [],
+            results,
+            availabilityGrid,
+            recordCounts,
+        };
+        this.logger?.log(`Dry run: would create ${createInputs.length} definitions`);
+        return createSuccessResult(dryRunResult, {
+            message: `Dry run: would create ${createInputs.length} profiling definitions`,
+            warnings: warnings.length > 0 ? warnings : undefined,
+            metadata: { duration: Date.now() - startTime },
+        });
+    }
+    /**
+     * Executes sequential creation of definitions with per-item progress callbacks.
+     */
+    async executeCreation(createInputs, skippedInputs, totalCount, operationWarnings, options, startTime, availabilityGrid, recordCounts) {
+        const results = [];
+        const failures = [];
+        const totalItems = createInputs.length + skippedInputs.length;
+        let itemIndex = 0;
+        let createdCount = 0;
+        let failedCount = 0;
+        // Fire skipped items first
+        for (const input of skippedInputs) {
+            itemIndex++;
+            const r = {
+                objectName: input.objectName,
+                objectLabel: input.objectLabel,
+                status: 'skip',
+                definitionName: input.name,
+                type: input.method,
+                category: input.category,
+                timeCategory: DefinitionCreateOperation.resolveTimeCategory(input),
+                segmentCategory: DefinitionCreateOperation.resolveSegmentCategory(input),
+            };
+            results.push(r);
+            options.onObjectComplete?.({
+                objectName: r.objectName,
+                status: 'skip',
+                message: 'definition already exists',
+                current: itemIndex,
+                total: totalItems,
+                type: r.type,
+                definitionName: r.definitionName,
+                recordTypeName: r.segmentCategory,
+                category: r.category,
+                timeCategory: r.timeCategory,
+                segmentCategory: r.segmentCategory,
+            });
+        }
+        // Create definitions one at a time for real-time progress
+        for (const input of createInputs) {
+            itemIndex++;
+            // eslint-disable-next-line no-await-in-loop -- Sequential for real-time progress feedback
+            const createResult = await this.definitionService.createDefinition(input);
+            if (createResult.success && createResult.data) {
+                const def = createResult.data;
+                const fieldCount = createResult.metadata?.fieldCount ?? undefined;
+                createdCount++;
+                const r = {
+                    objectName: input.objectName,
+                    objectLabel: def.objectLabel ?? input.objectLabel,
+                    status: 'success',
+                    definitionName: def.name,
+                    definitionId: def.id,
+                    definitionKey: def.key,
+                    type: input.method,
+                    fieldCount,
+                    category: def.category ?? input.category,
+                    timeCategory: def.timeCategory ?? DefinitionCreateOperation.resolveTimeCategory(input),
+                    segmentCategory: def.segmentCategory ?? DefinitionCreateOperation.resolveSegmentCategory(input),
+                };
+                results.push(r);
+                options.onObjectComplete?.({
+                    objectName: r.objectName,
+                    status: 'success',
+                    message: DefinitionCreateOperation.formatObjectMessage(r),
+                    current: itemIndex,
+                    total: totalItems,
+                    type: r.type,
+                    definitionName: r.definitionName,
+                    definitionKey: r.definitionKey,
+                    recordTypeName: r.segmentCategory,
+                    category: r.category,
+                    timeCategory: r.timeCategory,
+                    segmentCategory: r.segmentCategory,
+                    fieldCount: r.fieldCount,
+                });
+            }
+            else {
+                failedCount++;
+                const errorMsg = createResult.message ?? 'Unknown error';
+                failures.push({
+                    objectName: input.objectName,
+                    error: errorMsg,
+                    errorCode: createResult.errorCode ?? CreateErrorCodes.OPERATION_FAILED,
+                });
+                const r = {
+                    objectName: input.objectName,
+                    objectLabel: input.objectLabel,
+                    status: 'fail',
+                    definitionName: input.name,
+                    type: input.method,
+                    error: errorMsg,
+                    category: input.category,
+                    timeCategory: DefinitionCreateOperation.resolveTimeCategory(input),
+                    segmentCategory: DefinitionCreateOperation.resolveSegmentCategory(input),
+                };
+                results.push(r);
+                options.onObjectComplete?.({
+                    objectName: r.objectName,
+                    status: 'fail',
+                    message: errorMsg,
+                    current: itemIndex,
+                    total: totalItems,
+                    type: r.type,
+                    definitionName: r.definitionName,
+                    recordTypeName: r.segmentCategory,
+                    category: r.category,
+                    timeCategory: r.timeCategory,
+                    segmentCategory: r.segmentCategory,
+                });
+            }
+        }
+        const result = {
+            created: createdCount,
+            failed: failedCount,
+            skipped: skippedInputs.length,
+            total: totalCount,
+            failures,
+            results,
+            availabilityGrid,
+            recordCounts,
+        };
+        const duration = Date.now() - startTime;
+        this.logger?.log(`Created ${createdCount} definitions, ${failedCount} failed, ${skippedInputs.length} skipped`);
+        options.onProgress?.(`Complete: ${createdCount} created, ${failedCount} failed, ${skippedInputs.length} skipped`);
+        return createSuccessResult(result, {
+            message: `Created ${createdCount} profiling definitions`,
+            warnings: operationWarnings.length > 0 ? operationWarnings : undefined,
+            metadata: { duration },
+        });
+    }
+    /**
+     * Executes definition creation via the ISV REST API (create-smart endpoint).
+     * Server handles naming, categorization, deduplication, and creation.
+     * The CLI only provides objects, method, and options — no local business logic.
+     */
+    async executeCreationViaRest(objects, options, operationWarnings, startTime, availabilityGrid, recordCounts) {
+        const emptyResult = { created: 0, failed: 0, skipped: 0, total: 0, failures: [], results: [] };
+        this.logger?.log('Delegating definition creation to ISV REST API (create-smart)');
+        options.onProgress?.('Creating definitions via server-side pipeline...');
+        const method = options.method ?? 'metadata';
+        // Apply --limit safety cap before sending to ISV (ISV sees only the capped list).
+        const { limited: limitedObjects, warning: limitWarning } = this.applyObjectLimit(objects, options.limit);
+        if (limitWarning)
+            operationWarnings.push(limitWarning);
+        // Outcome pre-filter: only Opportunity, Case, Lead have outcome fields (CLI-1792).
+        const objectsToCreate = DefinitionCreateOperation.applyOutcomeFilter(limitedObjects, method, emptyResult, startTime);
+        if (!Array.isArray(objectsToCreate))
+            return objectsToCreate;
+        const restResult = await this.restClient.createSmart({
+            objects: objectsToCreate.map((o) => ({ name: o.name, label: o.label })),
+            method,
+            options: {
+                category: options.category,
+                timeCategory: options.timeCategory,
+                segmentCategory: options.segmentCategory,
+                year: options.year,
+                usePrior: options.usePrior,
+                noValueFrequency: options.noValueFrequency,
+                namePrefix: options.namePrefix,
+                // Prepend bullet separator — ISV joins suffix with a plain space, so we carry the bullet.
+                // CLI-3064: When --no-value-frequency is set, the resolved name on both client and server
+                // must include a "No Value Frequency" disambiguator \u2014 otherwise the value-frequency and
+                // no-value-frequency variants of the same (object, method, time-segment) collide on the
+                // name-keyed dedup gate and the second is silently skipped. The disambiguator is layered
+                // ahead of any user-supplied --name-suffix so user suffixes compose cleanly on top.
+                nameSuffix: DefinitionCreateOperation.composeRestNameSuffix(options.nameSuffix, options.noValueFrequency),
+                origin: options.origin,
+                recordType: options.recordType,
+                description: options.description,
+                dryRun: options.dryRun,
+                dateLiteralRange: options.dateLiteralRange,
+                yearEntries: options.yearRange?.entries.length
+                    ? options.yearRange.entries.map(({ year, unbounded }) => ({ year, unbounded }))
+                    : undefined,
+            },
+        });
+        if (!restResult.success) {
+            return createFailureResult(emptyResult, CreateErrorCodes.OPERATION_FAILED, restResult.message ?? 'REST API call failed', {
+                metadata: { duration: Date.now() - startTime },
+            });
+        }
+        const serverResponse = restResult.data;
+        const failures = [];
+        let createdCount = 0;
+        let failedCount = 0;
+        let skippedCount = 0;
+        // Map all server results synchronously, then enrich classification in parallel (CLI-1756).
+        const serverResults = serverResponse.results ?? [];
+        const resultPairs = serverResults.map((sr) => ({ sr, r: DefinitionCreateOperation.mapServerResult(sr) }));
+        // CLI-1756: ISV create-smart no longer returns classification fields (type, category,
+        // timeCategory, segmentCategory). Enrich all created definitions in parallel via GET
+        // so downstream consumers (JSON output, NUT assertions) see full classification metadata.
+        await this.enrichClassificationFields(resultPairs);
+        const results = [];
+        for (const { sr, r } of resultPairs) {
+            DefinitionCreateOperation.normalizeDryRunResult(r, sr, options.dryRun === true, method);
+            results.push(r);
+            if (sr.status === 'created' || sr.status === 'preview') {
+                createdCount++;
+            }
+            else if (sr.status === 'skipped') {
+                skippedCount++;
+            }
+            else if (sr.status === 'failed') {
+                failedCount++;
+                failures.push({
+                    objectName: sr.objectName,
+                    error: sr.errorMessage ?? 'Unknown error',
+                    errorCode: CreateErrorCodes.OPERATION_FAILED,
+                });
+            }
+            DefinitionCreateOperation.notifyObjectComplete(r, sr, results.length, serverResults.length, options);
+        }
+        const createResult = {
+            created: createdCount,
+            failed: failedCount,
+            skipped: skippedCount,
+            total: serverResults.length,
+            dryRun: options.dryRun,
+            failures,
+            results,
+            availabilityGrid,
+            recordCounts,
+        };
+        return createSuccessResult(createResult, {
+            message: options.dryRun
+                ? `Preview: ${results.length} definitions`
+                : `Created ${createdCount} profiling definitions`,
+            warnings: operationWarnings.length > 0 ? operationWarnings : undefined,
+            metadata: { duration: Date.now() - startTime },
+        });
+    }
+    /**
+     * Enriches classification fields (type, category, timeCategory, segmentCategory) on created
+     * results in parallel. CLI-1756: ISV create-smart no longer returns these fields in its response.
+     */
+    async enrichClassificationFields(pairs) {
+        await Promise.all(pairs
+            .filter(({ sr, r }) => (sr.status === 'created' || sr.status === 'skipped') && sr.definitionId && r.type === undefined)
+            .map(async ({ sr, r }) => {
+            const enrichResult = await this.definitionService.getDefinitionById(sr.definitionId);
+            if (enrichResult.success && enrichResult.data) {
+                const def = enrichResult.data;
+                // eslint-disable-next-line no-param-reassign -- enriching response object in-place (CLI-1756: ISV omits classification in create response)
+                r.type = def.type;
+                // eslint-disable-next-line no-param-reassign -- enriching response object in-place (CLI-1756)
+                r.category = def.category;
+                // eslint-disable-next-line no-param-reassign -- enriching response object in-place (CLI-1756)
+                r.timeCategory = def.timeCategory;
+                // eslint-disable-next-line no-param-reassign -- enriching response object in-place (CLI-1756)
+                r.segmentCategory = def.segmentCategory;
+            }
+            else {
+                this.logger?.log(`CLI-1756: Failed to enrich classification for ${sr.objectName}: ${enrichResult.message ?? 'unknown'}`);
+            }
+        }));
+    }
+    /**
+     * Resolves objects by explicit names, profiled set, or filtering criteria.
+     */
+    async resolveObjects(options, warnings) {
+        if (options.profiled) {
+            return this.resolveProfiledObjects(options, warnings);
+        }
+        if (options.objects && options.objects.length > 0) {
+            return this.resolveExplicitObjects(options.objects, warnings, options.onProgress);
+        }
+        return this.resolveFilteredObjects(options);
+    }
+    /**
+     * Resolves objects that have successful metadata profiling results.
+     */
+    async resolveProfiledObjects(options, warnings) {
+        options.onProgress?.('Querying profiled objects...');
+        this.logger?.log('Querying profiled objects from ProfilingSummaryService');
+        if (!this.profilingSummaryService) {
+            return createFailureResult([], CreateErrorCodes.OPERATION_FAILED, 'ProfilingSummaryService is required when profiled=true');
+        }
+        const profiledResult = await this.profilingSummaryService.queryProfiledObjects();
+        if (!profiledResult.success) {
+            return createFailureResult([], CreateErrorCodes.FILTER_FAILED, profiledResult.message);
+        }
+        let profiledNames = profiledResult.data;
+        if (profiledNames.length === 0) {
+            return createFailureResult([], CreateErrorCodes.NO_PROFILED_OBJECTS, 'No objects have been profiled yet. Run profiling with --method metadata first.');
+        }
+        this.logger?.log(`Found ${profiledNames.length} profiled objects`);
+        if (options.objects && options.objects.length > 0) {
+            const profiledSet = new Set(profiledNames.map((n) => n.toLowerCase()));
+            const intersected = [];
+            for (const obj of options.objects) {
+                if (profiledSet.has(obj.toLowerCase())) {
+                    intersected.push(obj);
+                }
+                else {
+                    warnings.push(`Object '${obj}' is not in the profiled set and will be skipped.`);
+                }
+            }
+            if (intersected.length === 0) {
+                return createFailureResult([], CreateErrorCodes.NO_PROFILED_OBJECTS, 'None of the specified objects have been profiled. Run profiling with --method metadata first.');
+            }
+            profiledNames = intersected;
+        }
+        options.onProgress?.(`Resolving ${profiledNames.length} profiled objects...`);
+        const resolveResult = await this.filteringService.getObjectsByName(profiledNames);
+        if (!resolveResult.success) {
+            return createFailureResult([], CreateErrorCodes.FILTER_FAILED, resolveResult.message);
+        }
+        if (resolveResult.warnings && resolveResult.warnings.length > 0) {
+            warnings.push(...resolveResult.warnings);
+        }
+        if (resolveResult.data.length === 0) {
+            return createFailureResult([], CreateErrorCodes.OBJECTS_NOT_FOUND, 'None of the profiled objects exist in the org');
+        }
+        let filtered = resolveResult.data;
+        if (options.filter && options.filter !== 'all') {
+            filtered = filtered.filter((obj) => (options.filter === 'custom' ? obj.isCustom : !obj.isCustom));
+        }
+        filtered = DefinitionCreateOperation.applyNamespaceFilter(filtered, options.namespace);
+        if (options.pattern) {
+            const pattern = options.pattern;
+            if (pattern.includes('*')) {
+                const regex = new RegExp('^' + pattern.replace(/\*/g, '.*') + '$', 'i');
+                filtered = filtered.filter((obj) => regex.test(obj.name));
+            }
+            else {
+                const lower = pattern.toLowerCase();
+                filtered = filtered.filter((obj) => obj.name.toLowerCase().includes(lower));
+            }
+        }
+        if (filtered.length === 0) {
+            return createFailureResult([], CreateErrorCodes.NO_OBJECTS_FOUND, 'No profiled objects match the specified filters');
+        }
+        this.logger?.log(`Resolved ${filtered.length} profiled objects after filtering`);
+        return createSuccessResult(filtered);
+    }
+    /**
+     * Resolves objects by explicit API names.
+     */
+    async resolveExplicitObjects(objectNames, warnings, onProgress) {
+        onProgress?.('Resolving specified objects...');
+        this.logger?.log(`Resolving ${objectNames.length} explicitly specified objects`);
+        const resolveResult = await this.filteringService.getObjectsByName(objectNames);
+        if (!resolveResult.success) {
+            this.logger?.log(`Object resolution failed: ${resolveResult.message}`);
+            return createFailureResult([], CreateErrorCodes.FILTER_FAILED, resolveResult.message);
+        }
+        if (resolveResult.warnings && resolveResult.warnings.length > 0) {
+            // Surface "not found" warnings immediately via progress callback
+            for (const w of resolveResult.warnings) {
+                onProgress?.(w);
+            }
+            warnings.push(...resolveResult.warnings);
+        }
+        if (resolveResult.data.length === 0) {
+            const notFoundNames = objectNames.join(', ');
+            this.logger?.log(`None of the specified objects exist in the org: ${notFoundNames}`);
+            return createFailureResult([], CreateErrorCodes.OBJECTS_NOT_FOUND, `None of the specified objects exist in the org: ${notFoundNames}`);
+        }
+        this.logger?.log(`Resolved ${resolveResult.data.length} of ${objectNames.length} specified objects`);
+        return createSuccessResult(resolveResult.data);
+    }
+    /**
+     * Resolves objects by filtering criteria.
+     */
+    async resolveFilteredObjects(options) {
+        options.onProgress?.('Filtering objects...');
+        const filterOptions = {
+            type: options.filter,
+            namespace: options.namespace,
+            classification: options.classification,
+            withRecords: options.minRecords && options.minRecords > 0 ? true : options.withRecords,
+            withoutRecords: options.withoutRecords,
+            hasRecordTypes: options.withRecordTypes,
+            // CLI-3085: __mdt and other non-layoutable system objects (history/share/feed/big/platform-event)
+            // are never valid profiling targets — opt in to the in-memory layoutable + keyPrefix predicate
+            // unconditionally so the create flow stays tight regardless of classification path behavior.
+            excludeSystemObjects: true,
+        };
+        if (options.pattern) {
+            filterOptions.nameFilter = {
+                value: options.pattern,
+                operator: options.pattern.includes('*') ? 'wildcard' : 'contains',
+            };
+        }
+        const filterResult = await this.filteringService.filter(filterOptions);
+        if (!filterResult.success) {
+            this.logger?.log(`Object filtering failed: ${filterResult.message}`);
+            return createFailureResult([], CreateErrorCodes.FILTER_FAILED, filterResult.message);
+        }
+        if (filterResult.data.length === 0) {
+            this.logger?.log('No objects found matching the specified filters');
+            return createFailureResult([], CreateErrorCodes.NO_OBJECTS_FOUND, 'No objects found matching the specified filters');
+        }
+        this.logger?.log(`Found ${filterResult.data.length} objects matching filters`);
+        // CLI-4214: carry forward the filtering chain's reconciliation truncation disclosure so the
+        // operation can surface it in its result warnings instead of silently dropping it.
+        return createSuccessResult(filterResult.data, {
+            warnings: filterResult.warnings && filterResult.warnings.length > 0 ? filterResult.warnings : undefined,
+        });
+    }
+    /**
+     * Filters objects by minimum record count threshold.
+     */
+    applyMinRecordsFilter(objects, minRecords) {
+        const filtered = objects.filter((obj) => (obj.recordCount ?? 0) >= minRecords);
+        this.logger?.log(`After min-records filter (>=${minRecords}): ${filtered.length} of ${objects.length} objects remain`);
+        return filtered;
+    }
+    /**
+     * Applies a safety cap to the number of definition inputs to process.
+     */
+    applyInputLimit(inputs, limit) {
+        if (!limit || limit <= 0 || inputs.length <= limit) {
+            return { limited: inputs };
+        }
+        this.logger?.log(`Applied limit: ${limit} of ${inputs.length} definitions`);
+        return {
+            limited: inputs.slice(0, limit),
+            warning: `Results limited to ${limit} definitions (${inputs.length} matched). Use --limit to increase.`,
+        };
+    }
+    /**
+     * Applies a safety cap to the number of SObjects sent to the ISV REST API.
+     * Mirrors applyInputLimit for the REST path where objects are capped before the ISV call.
+     */
+    applyObjectLimit(objects, limit) {
+        if (!limit || limit <= 0 || objects.length <= limit) {
+            return { limited: objects };
+        }
+        this.logger?.log(`Applied object limit: ${limit} of ${objects.length} objects`);
+        return {
+            limited: objects.slice(0, limit),
+            warning: `Results limited to ${limit} definitions (${objects.length} matched). Use --limit to increase.`,
+        };
+    }
+    /**
+     * Fetches all existing profiling definitions using pagination.
+     */
+    async fetchAllExistingDefinitions() {
+        const allDefinitions = [];
+        let offset = 0;
+        const pageSize = MAX_PAGINATION_LIMIT;
+        // eslint-disable-next-line no-constant-condition -- Pagination loop exits on short page or failure
+        while (true) {
+            // eslint-disable-next-line no-await-in-loop -- Sequential pagination: each page depends on knowing if more exist
+            const pageResult = await this.definitionService.getDefinitions({ limit: pageSize, offset });
+            if (!pageResult.success) {
+                if (allDefinitions.length > 0) {
+                    this.logger?.log(`Pagination failed at offset ${offset}, using ${allDefinitions.length} definitions fetched so far`);
+                    return createSuccessResult(allDefinitions, {
+                        warnings: [`Pagination incomplete: failed at offset ${offset}. Deduplication may be partial.`],
+                    });
+                }
+                return pageResult;
+            }
+            allDefinitions.push(...pageResult.data);
+            if (pageResult.data.length < pageSize) {
+                break;
+            }
+            offset += pageSize;
+        }
+        this.logger?.log(`Fetched ${allDefinitions.length} total existing definitions across pagination`);
+        return createSuccessResult(allDefinitions, {
+            message: `Found ${allDefinitions.length} existing definitions`,
+        });
+    }
+}
+//# sourceMappingURL=DefinitionCreateOperation.js.map