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

package/lib/services/ObjectFilteringService.js

@@ -0,0 +1,878 @@
+/*
+ * 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 { CuneiformQueryBuilder } from '../adapters/soql/cuneiform-query-builder.js';
+import { createSuccessResult, createFailureResult } from '../models/service-result.js';
+import { ServiceErrorCodes } from '../adapters/errors.js';
+import { processInBatches } from '../utils/batch-processor.js';
+import { validateNamespace, validateNonEmptyArray } from './validation.js';
+import { MAX_OBJECT_NAMES } from './constants.js';
+/** Default number of objects to process concurrently in checkDataExistsInRange. */
+const DEFAULT_CONCURRENCY_LIMIT = 5;
+/** Valid type filter values */
+const VALID_TYPES = new Set(['standard', 'custom', 'all']);
+/** Valid name filter operators */
+const VALID_OPERATORS = new Set(['startsWith', 'contains', 'equals', 'wildcard']);
+/** Valid classification values */
+const VALID_CLASSIFICATIONS = new Set(['customer', 'internal', 'all']);
+/** Namespace format pattern: starts with letter, alphanumeric only */
+const NAMESPACE_PATTERN = /^[a-zA-Z][a-zA-Z0-9]*$/;
+/**
+ * Object API name suffixes that indicate non-data objects which are never valid
+ * profiling targets: `__mdt` (Custom Metadata Types — configuration, not data),
+ * `__History` (change-tracking auxiliary), `__Share` (sharing-rule auxiliary),
+ * `__Feed` (Chatter feed auxiliary), `__ChangeEvent` (Change Data Capture event),
+ * `__e` (Platform Events — no persistent records).
+ *
+ * Big Objects (`__b`) and External Objects (`__x`) are intentionally excluded
+ * from this list — they hold queryable records and remain valid profiling
+ * targets, gated by the layoutable/keyPrefix predicate alone.
+ *
+ * The layoutable + keyPrefix predicate alone is insufficient: in some orgs
+ * Custom Metadata Types report `IsLayoutable=true` and a non-null KeyPrefix
+ * (e.g., m00) and end up in the `customer` EntityDefinition set — see CLI-3085.
+ * The ISV REST `filter-objects` endpoint does not honor `excludeSystemObjects`
+ * for `__mdt` either, so the CLI applies this name-based safety filter on both
+ * the local SOQL path and the REST response.
+ */
+const NON_DATA_SUFFIX_PATTERN = /__(mdt|History|Share|Feed|ChangeEvent|e)$/;
+/**
+ * Domain service for filtering and classifying Salesforce objects.
+ *
+ * Provides methods to filter objects by type, namespace, classification,
+ * record counts, and record types. Uses describeGlobal for metadata,
+ * EntityDefinition SOQL for customer/internal classification, and
+ * lazy-loads record type information via SOQL.
+ *
+ * @design
+ * **File Size**: This file is ~630 lines, larger than the ideal 200-400 line target.
+ * This is intentional: all filter logic, validation, and transformation code is
+ * cohesive and related. Splitting into multiple files would force readers to jump
+ * between files to understand the filter chain, hurting confidence and clarity.
+ * Per Human-Centered Code Principles, "Confidence > Maintainability" — a cohesive
+ * file beats scattered fragments.
+ *
+ * @example
+ * ```typescript
+ * const service = new ObjectFilteringService({
+ *   restApiAdapter,
+ *   soqlAdapter,
+ *   logger: console,
+ * });
+ *
+ * // Filter custom objects with records
+ * const result = await service.filter({
+ *   type: 'custom',
+ *   withRecords: true,
+ * });
+ *
+ * if (result.success) {
+ *   for (const obj of result.data) {
+ *     console.log(`${obj.name}: ${obj.recordCount} records`);
+ *   }
+ * }
+ * ```
+ */
+export class ObjectFilteringService {
+    restApiAdapter;
+    soqlAdapter;
+    concurrencyLimit;
+    logger;
+    restClient;
+    /** Lazily loaded set of object names that have active record types */
+    recordTypeCache = null;
+    /** Cache of object names that have an OwnerId field (per-session) */
+    ownerFieldCache = new Map();
+    /** Lazily loaded set of customer-facing object names from EntityDefinition (per-session) */
+    customerObjectCache = null;
+    /**
+     * Creates a new ObjectFilteringService.
+     *
+     * @param config - Service configuration with required adapters
+     */
+    constructor(config) {
+        this.restApiAdapter = config.restApiAdapter;
+        this.soqlAdapter = config.soqlAdapter;
+        this.concurrencyLimit = config.concurrencyLimit ?? DEFAULT_CONCURRENCY_LIMIT;
+        this.logger = config.logger;
+        this.restClient = config.restClient;
+    }
+    /**
+     * Validates filter options and returns a failure result if invalid.
+     *
+     * @param options - The filter options to validate
+     * @returns A failure ServiceResult if validation fails, undefined otherwise
+     */
+    static validateFilterOptions(options) {
+        // Validate type
+        if (options.type !== undefined && !VALID_TYPES.has(options.type)) {
+            return createFailureResult([], ServiceErrorCodes.INVALID_TYPE, `Invalid type parameter: "${options.type}". Must be 'standard', 'custom', or 'all'.`);
+        }
+        // Validate namespace (only if it's a non-null string)
+        if (options.namespace !== undefined && options.namespace !== null) {
+            if (!NAMESPACE_PATTERN.test(options.namespace)) {
+                return createFailureResult([], ServiceErrorCodes.INVALID_NAMESPACE, `Invalid namespace format: "${options.namespace}". Must start with a letter and contain only letters and numbers.`);
+            }
+        }
+        // Validate name filter
+        if (options.nameFilter) {
+            if (!options.nameFilter.value || options.nameFilter.value.trim().length === 0) {
+                return createFailureResult([], ServiceErrorCodes.INVALID_NAME_FILTER, 'Name filter value is required and cannot be empty.');
+            }
+            if (!VALID_OPERATORS.has(options.nameFilter.operator)) {
+                return createFailureResult([], ServiceErrorCodes.INVALID_NAME_FILTER, `Invalid name filter operator: "${options.nameFilter.operator}". Must be 'startsWith', 'contains', 'equals', or 'wildcard'.`);
+            }
+            // For wildcard operator, validate that pattern contains at least one *
+            if (options.nameFilter.operator === 'wildcard' && !options.nameFilter.value.includes('*')) {
+                return createFailureResult([], ServiceErrorCodes.INVALID_NAME_FILTER, `Wildcard pattern must contain at least one '*' character. Got: "${options.nameFilter.value}".`);
+            }
+        }
+        // Validate classification
+        if (options.classification !== undefined && !VALID_CLASSIFICATIONS.has(options.classification)) {
+            return createFailureResult([], ServiceErrorCodes.INVALID_CLASSIFICATION, `Invalid classification: "${options.classification}". Must be 'customer', 'internal', or 'all'.`);
+        }
+        return undefined;
+    }
+    /**
+     * Determines whether an object is custom.
+     * Custom object detection: name ends with __c OR custom === true.
+     *
+     * @param obj - The global describe object to check
+     * @returns True if the object is custom
+     */
+    static isCustomObject(obj) {
+        return obj.custom || obj.name.endsWith('__c');
+    }
+    /**
+     * Extracts namespace from an object API name.
+     * Namespaced objects follow the pattern: namespace__ObjectName__c
+     *
+     * @param name - The object API name
+     * @returns The namespace prefix, or undefined if unmanaged
+     */
+    static extractNamespace(name) {
+        // Namespace pattern: at least two double-underscore segments
+        // e.g., ns__Object__c -> ns, ns__Object -> ns
+        // Standard objects and non-namespaced custom objects have at most one __
+        const parts = name.split('__');
+        if (parts.length >= 3) {
+            // ns__Object__c or ns__Object__suffix
+            return parts[0];
+        }
+        return undefined;
+    }
+    /**
+     * Converts a global describe result to SObjectInfo.
+     *
+     * @param obj - The global describe object
+     * @returns SObjectInfo representation
+     */
+    static toSObjectInfo(obj) {
+        const info = {
+            name: obj.name,
+            label: obj.label,
+            isCustom: ObjectFilteringService.isCustomObject(obj),
+        };
+        const namespace = ObjectFilteringService.extractNamespace(obj.name);
+        if (namespace) {
+            info.namespace = namespace;
+        }
+        return info;
+    }
+    /**
+     * Applies type filter to objects.
+     */
+    static applyTypeFilter(objects, type) {
+        if (type === 'custom') {
+            return objects.filter((obj) => ObjectFilteringService.isCustomObject(obj));
+        }
+        // standard
+        return objects.filter((obj) => !ObjectFilteringService.isCustomObject(obj));
+    }
+    /**
+     * Applies namespace filter to objects.
+     */
+    static applyNamespaceFilter(objects, namespace) {
+        if (namespace === null) {
+            // null means unmanaged -- no namespace
+            return objects.filter((obj) => !ObjectFilteringService.extractNamespace(obj.name));
+        }
+        // Match specific namespace (case-insensitive)
+        // Salesforce namespaces are case-insensitive in org references and API calls
+        const lowerNamespace = namespace.toLowerCase();
+        return objects.filter((obj) => {
+            const ns = ObjectFilteringService.extractNamespace(obj.name);
+            return ns !== undefined && ns.toLowerCase() === lowerNamespace;
+        });
+    }
+    /**
+     * Converts a wildcard pattern (with *) to a regular expression.
+     * The * character matches any sequence of characters.
+     *
+     * @param pattern - The wildcard pattern (e.g., "Account*", "*__c", "*Contact*")
+     * @returns A RegExp that matches the pattern case-insensitively
+     */
+    static wildcardToRegex(pattern) {
+        // Escape special regex characters except *
+        const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, '\\$&');
+        // Convert * to .* (match any characters)
+        const regexPattern = escaped.replace(/\*/g, '.*');
+        // Anchor the pattern and make it case-insensitive
+        return new RegExp(`^${regexPattern}$`, 'i');
+    }
+    /**
+     * Applies name filter to objects (case-insensitive).
+     */
+    static applyNameFilter(objects, nameFilter) {
+        const lowerValue = nameFilter.value.toLowerCase();
+        // Pre-compile regex for wildcard operator
+        const wildcardRegex = nameFilter.operator === 'wildcard' ? ObjectFilteringService.wildcardToRegex(nameFilter.value) : null;
+        return objects.filter((obj) => {
+            const lowerName = obj.name.toLowerCase();
+            switch (nameFilter.operator) {
+                case 'startsWith':
+                    return lowerName.startsWith(lowerValue);
+                case 'contains':
+                    return lowerName.includes(lowerValue);
+                case 'equals':
+                    return lowerName === lowerValue;
+                case 'wildcard':
+                    return wildcardRegex.test(obj.name);
+                default:
+                    return false;
+            }
+        });
+    }
+    /**
+     * Applies system object exclusion. Excludes objects that are not valid profiling
+     * targets: layoutable === false OR keyPrefix === null (auxiliary/system objects),
+     * OR name matches NON_DATA_SUFFIX_PATTERN (CLI-3085: Salesforce reports
+     * IsLayoutable=true and a non-null KeyPrefix for Custom Metadata Types in some
+     * orgs, so the layoutable/keyPrefix predicate alone is insufficient).
+     */
+    static applySystemObjectExclusion(objects) {
+        return objects.filter((obj) => {
+            const layoutable = obj.layoutable ?? true;
+            if (!layoutable || obj.keyPrefix === null)
+                return false;
+            if (NON_DATA_SUFFIX_PATTERN.test(obj.name))
+                return false;
+            return true;
+        });
+    }
+    /**
+     * Predicate filter: keep only objects with `recordCount > 0`.
+     *
+     * Operates on already-populated counts produced by {@link populateRecordCounts};
+     * does not perform any API calls. Objects whose count was not populated (undefined
+     * recordCount, e.g. when the count query failed) are excluded — only positively
+     * confirmed non-zero counts pass.
+     */
+    static applyWithRecordsFilter(objects) {
+        return objects.filter((obj) => (obj.recordCount ?? 0) > 0);
+    }
+    /**
+     * Predicate filter: keep only objects with `recordCount === 0`.
+     *
+     * Operates on already-populated counts produced by {@link populateRecordCounts};
+     * does not perform any API calls. Objects whose count was not populated (undefined
+     * recordCount) are excluded — only positively confirmed zero counts pass.
+     */
+    static applyWithoutRecordsFilter(objects) {
+        return objects.filter((obj) => obj.recordCount === 0);
+    }
+    /**
+     * Applies withRecords or withoutRecords locally after REST delegation.
+     * Called when the Apex endpoint has returned a candidate list that still needs
+     * record-count filtering — the server intentionally does not do this step.
+     */
+    static applyPostRestRecordCountFilter(results, options) {
+        if (options.withRecords) {
+            return ObjectFilteringService.applyWithRecordsFilter(results);
+        }
+        if (options.withoutRecords) {
+            return ObjectFilteringService.applyWithoutRecordsFilter(results);
+        }
+        return results;
+    }
+    /**
+     * Excludes Custom Settings (list and hierarchy) from describe results.
+     * Custom Settings are configuration objects, not business data objects.
+     * Protected Custom Settings (visibility=Protected) must never be visible to subscribers.
+     */
+    static applyCustomSettingExclusion(objects) {
+        return objects.filter((obj) => !obj.customSetting);
+    }
+    /**
+     * Filters Salesforce objects based on combined filter criteria.
+     *
+     * Applies filters in order from cheapest to most expensive:
+     * type -> namespace -> nameFilter -> classification -> excludeSystemObjects -> customSettings -> withRecords -> hasRecordTypes
+     *
+     * @param options - Filter criteria to apply
+     * @returns ServiceResult containing filtered SObjectInfo array
+     */
+    async filter(options) {
+        const startTime = Date.now();
+        try {
+            // Validate inputs
+            const validationError = ObjectFilteringService.validateFilterOptions(options);
+            if (validationError) {
+                return validationError;
+            }
+            // REST API path: delegate metadata filtering to the server when restClient is available.
+            // withRecords/withoutRecords are intentionally NOT delegated — the server-side path uses
+            // per-object SOQL COUNT() queries that exhaust the governor budget on large orgs, causing
+            // objects without records to slip through (CLI-3083). The CLI applies them locally via
+            // GET /limits/recordCount (single call, no SOQL cost). Falls back to the local path on
+            // failure (e.g., endpoint not deployed).
+            const restFallbackResult = await this.tryRestDelegation(options, startTime);
+            if (restFallbackResult) {
+                const restResults = ObjectFilteringService.applyPostRestRecordCountFilter(restFallbackResult.data, options);
+                return createSuccessResult(restResults, {
+                    message: `Found ${restResults.length} objects matching filter criteria`,
+                    metadata: { duration: Date.now() - startTime, strategyUsed: 'rest-api' },
+                });
+            }
+            // Fetch global describe (local path)
+            const globalResult = await this.restApiAdapter.describeGlobal();
+            if (!globalResult.success) {
+                return createFailureResult([], ServiceErrorCodes.FILTER_FAILED, globalResult.message ?? 'Global describe failed', {
+                    metadata: { duration: Date.now() - startTime },
+                });
+            }
+            let sobjects = globalResult.data.sobjects;
+            // ─────────────────────────────────────────────────────────────────────────
+            // Filter Application Order (cheapest → most expensive)
+            // ─────────────────────────────────────────────────────────────────────────
+            // Filters are deliberately ordered to minimize work:
+            // 0. non-profileable — drop non-queryable objects (mirrors server-side
+            //    applyNonProfileableFilters in pnova/ObjectFilterRestService.cls).
+            //    Non-queryable objects (FeedTrackedChange, etc.) cannot be profiled,
+            //    so they must never appear in any classification bucket. Without
+            //    this gate, the local fallback returned a superset of the REST path
+            //    for `--classification customer|internal` (CLI-3310).
+            // 1. type           — in-memory flag check (instant)
+            // 2. namespace      — string parsing (instant)
+            // 3. nameFilter     — string comparison (instant)
+            // 4. classification  — 1 SOQL query (cached after first call)
+            // 5. excludeSystem   — in-memory flag check (instant)
+            // 6. customSettings  — in-memory flag check (instant, uses describe already fetched)
+            // 7. populate counts — 1 bulk REST call against the bounded result set.
+            //    The Records column is part of the documented output contract — counts
+            //    must be queried unconditionally so that "0" never doubles as a placeholder
+            //    for "we didn't ask". `withRecords` / `withoutRecords` are predicates,
+            //    not population gates (CLI-3077).
+            // 8. withRecords     — predicate against populated counts (no API call)
+            // 9. withoutRecords  — predicate against populated counts (no API call)
+            // 10. hasRecordTypes — 1 SOQL query (cached after first call)
+            // 11. withOwner      — N describe calls (1 per uncached object)
+            // ─────────────────────────────────────────────────────────────────────────
+            // 0. Non-profileable exclusion — match server's applyNonProfileableFilters.
+            //    Use !== false so that objects where queryable is absent in the API
+            //    response are kept rather than silently dropped.
+            sobjects = sobjects.filter((obj) => obj.queryable !== false);
+            // 1. Type filter (instant)
+            if (options.type && options.type !== 'all') {
+                sobjects = ObjectFilteringService.applyTypeFilter(sobjects, options.type);
+            }
+            // 2. Namespace filter (instant)
+            if (options.namespace !== undefined) {
+                sobjects = ObjectFilteringService.applyNamespaceFilter(sobjects, options.namespace);
+            }
+            // 3. Name filter (instant)
+            if (options.nameFilter) {
+                sobjects = ObjectFilteringService.applyNameFilter(sobjects, options.nameFilter);
+            }
+            // 4. Classification filter (1 SOQL query, cached after first call)
+            if (options.classification && options.classification !== 'all') {
+                sobjects = await this.applyClassificationFilter(sobjects, options.classification);
+            }
+            // 5. System object exclusion (instant)
+            if (options.excludeSystemObjects) {
+                sobjects = ObjectFilteringService.applySystemObjectExclusion(sobjects);
+            }
+            // 6. Custom Setting exclusion (instant — flag already present in global describe)
+            sobjects = ObjectFilteringService.applyCustomSettingExclusion(sobjects);
+            // Convert to SObjectInfo before expensive operations
+            let results = sobjects.map((obj) => ObjectFilteringService.toSObjectInfo(obj));
+            // Populate isCustomer classification if EntityDefinition cache is available
+            if (this.customerObjectCache !== null) {
+                results = results.map((obj) => ({ ...obj, isCustomer: this.customerObjectCache.has(obj.name) }));
+            }
+            // 6. Populate recordCount unconditionally (single bulk REST call). When the
+            //    caller asked to filter by record count, the populate step must succeed —
+            //    we can't honestly say "objects with records" if we don't know counts.
+            const countsRequired = options.withRecords === true || options.withoutRecords === true;
+            results = await this.populateRecordCounts(results, countsRequired);
+            // 7. withRecords filter (predicate against populated counts)
+            if (options.withRecords) {
+                results = ObjectFilteringService.applyWithRecordsFilter(results);
+            }
+            // 8. withoutRecords filter (predicate against populated counts)
+            if (options.withoutRecords) {
+                results = ObjectFilteringService.applyWithoutRecordsFilter(results);
+            }
+            // 9. hasRecordTypes filter (expensive — 1 SOQL query, cached after first call)
+            if (options.hasRecordTypes) {
+                results = await this.applyHasRecordTypesFilter(results);
+            }
+            // 10. withOwner filter (expensive — N API calls, 1 describe per uncached object)
+            if (options.withOwner) {
+                results = await this.applyWithOwnerFilter(results);
+            }
+            const duration = Date.now() - startTime;
+            this.logger?.log(`Filter returned ${results.length} objects in ${duration}ms`);
+            return createSuccessResult(results, {
+                message: `Found ${results.length} objects matching filter criteria`,
+                metadata: { duration },
+            });
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            this.logger?.log(`Filter failed: ${errorMessage}`);
+            return createFailureResult([], ServiceErrorCodes.FILTER_FAILED, errorMessage, {
+                metadata: { duration: Date.now() - startTime },
+            });
+        }
+    }
+    /**
+     * Filters objects by type (standard or custom).
+     *
+     * @param type - The object type to filter by
+     * @returns ServiceResult containing filtered SObjectInfo array
+     */
+    async filterByType(type) {
+        if (!VALID_TYPES.has(type)) {
+            return createFailureResult([], ServiceErrorCodes.INVALID_TYPE, `Invalid type parameter: "${type}". Must be 'standard', 'custom', or 'all'.`);
+        }
+        return this.filter({ type });
+    }
+    /**
+     * Filters objects by namespace.
+     *
+     * @param namespace - The namespace to filter by, or null for unmanaged objects
+     * @returns ServiceResult containing filtered SObjectInfo array
+     */
+    async filterByNamespace(namespace) {
+        if (namespace !== null) {
+            const error = validateNamespace(namespace);
+            if (error) {
+                return createFailureResult([], ServiceErrorCodes.INVALID_NAMESPACE, error);
+            }
+        }
+        return this.filter({ namespace });
+    }
+    /**
+     * Filters objects to only those with records (record count > 0).
+     *
+     * @returns ServiceResult containing filtered SObjectInfo array
+     */
+    async filterWithRecords() {
+        return this.filter({ withRecords: true });
+    }
+    /**
+     * Retrieves SObjectInfo for specific object names.
+     *
+     * Returns success with data for found objects and warnings for missing ones.
+     * If none are found, returns success with empty data and warnings.
+     *
+     * @param objectNames - Array of object API names to look up
+     * @returns ServiceResult containing found SObjectInfo array with warnings for missing
+     */
+    async getObjectsByName(objectNames) {
+        const startTime = Date.now();
+        // Validate input
+        const validationError = validateNonEmptyArray(objectNames, 'objectNames', MAX_OBJECT_NAMES);
+        if (validationError) {
+            return createFailureResult([], ServiceErrorCodes.INVALID_OBJECT_NAMES, validationError);
+        }
+        try {
+            // Fetch global describe
+            const globalResult = await this.restApiAdapter.describeGlobal();
+            if (!globalResult.success) {
+                return createFailureResult([], ServiceErrorCodes.FILTER_FAILED, globalResult.message ?? 'Global describe failed', {
+                    metadata: { duration: Date.now() - startTime },
+                });
+            }
+            // Build a lookup map (case-insensitive)
+            const objectMap = new Map();
+            for (const obj of globalResult.data.sobjects) {
+                objectMap.set(obj.name.toLowerCase(), obj);
+            }
+            const found = [];
+            const warnings = [];
+            for (const name of objectNames) {
+                const obj = objectMap.get(name.toLowerCase());
+                if (obj) {
+                    found.push(ObjectFilteringService.toSObjectInfo(obj));
+                }
+                else {
+                    warnings.push(`Object not found: ${name}`);
+                }
+            }
+            const duration = Date.now() - startTime;
+            this.logger?.log(`getObjectsByName: found ${found.length}/${objectNames.length} objects in ${duration}ms`);
+            return createSuccessResult(found, {
+                message: `Found ${found.length} of ${objectNames.length} requested objects`,
+                warnings: warnings.length > 0 ? warnings : undefined,
+                metadata: { duration },
+            });
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            this.logger?.log(`getObjectsByName failed: ${errorMessage}`);
+            return createFailureResult([], ServiceErrorCodes.FILTER_FAILED, errorMessage, {
+                metadata: { duration: Date.now() - startTime },
+            });
+        }
+    }
+    /**
+     * Retrieves record counts for the specified objects using the Record Count API.
+     *
+     * @param objectNames - Array of object API names to get counts for
+     * @returns ServiceResult containing a map of object name to record count
+     */
+    async getRecordCounts(objectNames) {
+        return this.restApiAdapter.getRecordCounts(objectNames);
+    }
+    /**
+     * Checks whether data exists for each probe specification using LIMIT 1 SOQL probes.
+     *
+     * Returns a flat grid of per-probe boolean results. Each probe uses a
+     * `SELECT Id FROM {Object} WHERE CreatedDate >= {yearStart} AND CreatedDate < {yearEnd} LIMIT 1`
+     * query to determine data presence efficiently. When a probe includes a `recordType`,
+     * a `RecordType.DeveloperName = '{value}'` filter is added.
+     *
+     * Probes are grouped by object and processed one object at a time. All probes for a single
+     * object (across years and record types) run concurrently, then the next object's probes fire.
+     * This keeps concurrent SOQL queries scoped to a single object's probes.
+     *
+     * Failures on individual probes are captured per-entry (hasData=false, error set) rather
+     * than failing the entire operation — the grid is informational, not blocking.
+     *
+     * @param probes - Array of probe specifications to execute
+     * @returns ServiceResult containing the availability grid
+     */
+    async checkDataExistsInRange(probes) {
+        const startTime = Date.now();
+        const grid = [];
+        if (probes.length === 0) {
+            return createSuccessResult(grid, {
+                message: 'No probes to check',
+                metadata: { duration: Date.now() - startTime },
+            });
+        }
+        // Group probes by object for per-object concurrent execution
+        const grouped = new Map();
+        for (const probe of probes) {
+            const existing = grouped.get(probe.objectApiName);
+            if (existing) {
+                existing.push(probe);
+            }
+            else {
+                grouped.set(probe.objectApiName, [probe]);
+            }
+        }
+        // Process objects in batched parallel groups; probes within each object run concurrently
+        const groupedEntries = [...grouped.entries()];
+        const batchedResults = await processInBatches(groupedEntries, this.concurrencyLimit, async ([objectName, objectProbes]) => {
+            const results = await Promise.all(objectProbes.map((spec) => this.probeDataForYear(spec)));
+            this.logger?.log(`Data probes for ${objectName}: ${objectProbes.length} probes`);
+            return results;
+        });
+        for (const results of batchedResults) {
+            grid.push(...results);
+        }
+        const duration = Date.now() - startTime;
+        const gapsCount = grid.filter((e) => !e.hasData && !e.error).length;
+        const errorsCount = grid.filter((e) => e.error !== undefined).length;
+        this.logger?.log(`Data availability check: ${grid.length} probes, ${gapsCount} gaps, ${errorsCount} errors in ${duration}ms`);
+        return createSuccessResult(grid, {
+            message: `Checked ${grid.length} probe combinations`,
+            metadata: { duration },
+        });
+    }
+    /**
+     * Probes a single object/year/recordType combination with a LIMIT 1 SOQL query.
+     * Returns a DataAvailabilityEntry — never throws.
+     */
+    async probeDataForYear(spec) {
+        const { objectApiName, year, recordType } = spec;
+        const yearStart = `${year}-01-01T00:00:00Z`;
+        const yearEnd = `${year + 1}-01-01T00:00:00Z`;
+        const builder = CuneiformQueryBuilder.create().select(['Id']).from(objectApiName);
+        if (recordType) {
+            builder.where('RecordType.DeveloperName', '=', recordType);
+            builder.andWhereDatetime('CreatedDate', '>=', yearStart);
+        }
+        else {
+            builder.whereDatetime('CreatedDate', '>=', yearStart);
+        }
+        const soql = builder.andWhereDatetime('CreatedDate', '<', yearEnd).limit(1).toSOQL();
+        const label = recordType ? `${objectApiName}/${recordType}/${year}` : `${objectApiName}/${year}`;
+        try {
+            const result = await this.soqlAdapter.query(soql);
+            if (!result.success) {
+                this.logger?.log(`Data probe failed for ${label}: ${result.message ?? 'unknown error'}`);
+                return { objectApiName, year, hasData: false, error: result.message ?? 'Query failed', recordType };
+            }
+            return { objectApiName, year, hasData: result.data.records.length > 0, recordType };
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            this.logger?.log(`Data probe exception for ${label}: ${errorMessage}`);
+            return { objectApiName, year, hasData: false, error: errorMessage, recordType };
+        }
+    }
+    /**
+     * Attempts REST delegation for object filtering.
+     * Returns the successful result, or null to signal fallback to the local SOQL path.
+     */
+    async tryRestDelegation(options, startTime) {
+        if (!this.restClient) {
+            return null;
+        }
+        const restResult = await this.filterViaRest(options, startTime);
+        if (restResult.success) {
+            return restResult;
+        }
+        this.logger?.log(`REST filter-objects failed (${restResult.message ?? 'unknown'}), falling back to local SOQL path`);
+        return null;
+    }
+    /**
+     * Lazily loads and caches the set of customer-facing object names from EntityDefinition.
+     * Uses a SOQL query against EntityDefinition to classify objects based on Salesforce metadata
+     * rather than hardcoded exclusion lists.
+     *
+     * @returns Set of customer-facing object API names
+     */
+    /**
+     * Delegates object filtering to the ISV REST API (filter-objects endpoint).
+     * Server handles the full cost-optimized filter chain.
+     */
+    async filterViaRest(options, startTime) {
+        this.logger?.log('Delegating object filtering to ISV REST API (filter-objects)');
+        const restResult = await this.restClient.filterObjects({
+            type: options.type,
+            namespace: options.namespace === null ? '' : options.namespace,
+            excludeSystemObjects: options.excludeSystemObjects,
+            namePattern: options.nameFilter?.value,
+            nameOperator: options.nameFilter?.operator,
+            classification: options.classification,
+            hasRecordTypes: options.hasRecordTypes,
+            withOwner: options.withOwner,
+        });
+        if (!restResult.success) {
+            return createFailureResult([], ServiceErrorCodes.FILTER_FAILED, restResult.message ?? 'REST filter-objects failed', {
+                metadata: { duration: Date.now() - startTime },
+            });
+        }
+        const response = restResult.data;
+        if (!response.success) {
+            const errorMsg = response.errors?.length > 0 ? response.errors[0] : 'Server-side filtering failed';
+            return createFailureResult([], ServiceErrorCodes.FILTER_FAILED, errorMsg, {
+                metadata: { duration: Date.now() - startTime },
+            });
+        }
+        // CLI-3085: server-side filter-objects endpoint does not honor
+        // excludeSystemObjects for __mdt (and parity for History/Share/Feed/ChangeEvent
+        // /b/e/x suffixes is not guaranteed). Apply a name-based safety filter on the
+        // REST response when the caller requested system-object exclusion so the
+        // create flow stays tight regardless of server behavior.
+        // Support both `results` (plural) and `result` (singular) — different ISV
+        // endpoint versions use different keys.
+        let results = response.results ?? response.result ?? [];
+        if (options.excludeSystemObjects) {
+            const before = results.length;
+            results = results.filter((obj) => !NON_DATA_SUFFIX_PATTERN.test(obj.name));
+            if (results.length !== before) {
+                this.logger?.log(`REST post-filter excluded ${before - results.length} non-data objects (CLI-3085)`);
+            }
+        }
+        // CLI-3077: populate recordCount on the server response — older server builds
+        // skip count population unless withRecords/withoutRecords is set, which would
+        // otherwise surface as the "0 records" symptom. The server-side fix on
+        // packaging/v4.12.0 also populates unconditionally; this client-side step is
+        // defense-in-depth that lets the CLI ship independently of the package release.
+        const countsRequired = options.withRecords === true || options.withoutRecords === true;
+        const populated = results.some((obj) => obj.recordCount !== undefined && obj.recordCount !== null)
+            ? results
+            : await this.populateRecordCounts(results, countsRequired);
+        return createSuccessResult(populated, {
+            message: `Filtered ${String(populated.length)} objects via REST API`,
+            metadata: { duration: Date.now() - startTime, strategyUsed: 'rest-api' },
+        });
+    }
+    async getCustomerObjects() {
+        if (this.customerObjectCache !== null) {
+            return this.customerObjectCache;
+        }
+        // EntityDefinition is a Setup object backed by metadata, not records. The
+        // platform returns it in batches and does NOT support queryMore() — the
+        // query MUST resolve in a single batch. Salesforce caps the EntityDefinition
+        // batch at 200 rows; using a larger LIMIT triggers the runtime error
+        // "EntityDefinition does not support queryMore()". 200 covers all practical
+        // orgs; objects beyond 200 customer-facing entities are classified as
+        // internal (false-negative is acceptable for the long-tail).
+        //
+        // Chained .where() calls must use andWhere() for subsequent conditions —
+        // .where() replaces the first condition each time it's called.
+        const soql = CuneiformQueryBuilder.create()
+            .select(['QualifiedApiName'])
+            .from('EntityDefinition')
+            .where('IsCustomizable', '=', true)
+            .andWhere('IsLayoutable', '=', true)
+            .andWhere('IsDeprecatedAndHidden', '=', false)
+            .limit(200)
+            .toSOQL();
+        const result = await this.soqlAdapter.query(soql);
+        if (result.success) {
+            this.customerObjectCache = new Set(result.data.records.map((r) => r.QualifiedApiName));
+        }
+        else {
+            const errorMessage = `EntityDefinition classification query failed: ${result.message ?? 'unknown error'}`;
+            this.logger?.log(errorMessage);
+            throw new Error(errorMessage);
+        }
+        return this.customerObjectCache;
+    }
+    /**
+     * Applies classification filter to objects using EntityDefinition metadata.
+     * Customer-facing objects are those present in the EntityDefinition customer set.
+     * Internal objects are everything else.
+     */
+    async applyClassificationFilter(objects, classification) {
+        const customerObjects = await this.getCustomerObjects();
+        if (classification === 'customer') {
+            return objects.filter((obj) => customerObjects.has(obj.name));
+        }
+        // internal: NOT in customer set
+        return objects.filter((obj) => !customerObjects.has(obj.name));
+    }
+    /**
+     * Populates `recordCount` on every result via a single bulk record-count REST call.
+     *
+     * Always called during {@link filter} so the Records column is populated
+     * unconditionally — see CLI-3077.
+     *
+     * Failure semantics: when `required` is true (user passed `withRecords` or
+     * `withoutRecords`), a count-query failure throws so {@link filter} returns a
+     * `FILTER_FAILED` ServiceResult — we can't honestly filter by record count if
+     * we don't know counts. When `required` is false, a failure is logged and
+     * `recordCount` is left undefined; the display renders that as `—` rather than
+     * a misleading `0`.
+     *
+     * @param objects - SObjectInfo array to enrich with record counts
+     * @param required - Whether the caller's filter chain depends on accurate counts
+     * @returns Same array with `recordCount` populated (or unchanged on soft-failure)
+     * @throws Error when `required` is true and the count query fails
+     */
+    async populateRecordCounts(objects, required) {
+        if (objects.length === 0) {
+            return objects;
+        }
+        const objectNames = objects.map((obj) => obj.name);
+        const countsResult = await this.restApiAdapter.getRecordCounts(objectNames);
+        if (!countsResult.success) {
+            const message = `Record count query failed: ${countsResult.message ?? 'unknown error'}`;
+            this.logger?.log(message);
+            if (required) {
+                throw new Error(message);
+            }
+            return objects;
+        }
+        const counts = countsResult.data;
+        return objects.map((obj) => ({ ...obj, recordCount: counts.get(obj.name) ?? 0 }));
+    }
+    /**
+     * Applies hasRecordTypes filter by querying active record types.
+     * Uses lazy-loaded cache for record type information.
+     */
+    async applyHasRecordTypesFilter(objects) {
+        const recordTypeObjects = await this.getRecordTypeObjects();
+        return objects.filter((obj) => recordTypeObjects.has(obj.name)).map((obj) => ({ ...obj, hasRecordTypes: true }));
+    }
+    /**
+     * Lazily loads and caches the set of object names that have active record types.
+     *
+     * @returns Set of object API names with active record types
+     */
+    async getRecordTypeObjects() {
+        if (this.recordTypeCache !== null) {
+            return this.recordTypeCache;
+        }
+        const soql = CuneiformQueryBuilder.create()
+            .select(['SobjectType'])
+            .from('RecordType')
+            .where('IsActive', '=', true)
+            .groupBy(['SobjectType'])
+            .toSOQL();
+        const result = await this.soqlAdapter.query(soql);
+        if (result.success) {
+            this.recordTypeCache = new Set(result.data.records.map((r) => r.SobjectType));
+        }
+        else {
+            this.logger?.log(`Record type query failed: ${result.message ?? 'unknown error'}`);
+            this.recordTypeCache = new Set();
+        }
+        return this.recordTypeCache;
+    }
+    /**
+     * Applies withOwner filter by checking if objects have an OwnerId field.
+     * Uses cached describe results for efficiency.
+     */
+    async applyWithOwnerFilter(objects) {
+        const results = [];
+        // Check owner fields in parallel
+        const ownerPromises = objects.map(async (obj) => {
+            const hasOwner = await this.hasOwnerField(obj.name);
+            if (hasOwner) {
+                return { ...obj, hasOwner: true };
+            }
+            return null;
+        });
+        const resolved = await Promise.all(ownerPromises);
+        for (const item of resolved) {
+            if (item !== null) {
+                results.push(item);
+            }
+        }
+        return results;
+    }
+    /**
+     * Checks if an object has an OwnerId field.
+     * Results are cached per-session for efficiency.
+     *
+     * @param objectName - The object API name to check
+     * @returns True if the object has an OwnerId field
+     */
+    async hasOwnerField(objectName) {
+        // Check cache first
+        if (this.ownerFieldCache.has(objectName)) {
+            return this.ownerFieldCache.get(objectName);
+        }
+        try {
+            const describeResult = await this.restApiAdapter.describeObject(objectName);
+            if (!describeResult.success) {
+                this.logger?.log(`Describe failed for ${objectName}: ${describeResult.message ?? 'unknown error'}`);
+                this.ownerFieldCache.set(objectName, false);
+                return false;
+            }
+            const hasOwner = describeResult.data.fields.some((field) => field.name === 'OwnerId');
+            this.ownerFieldCache.set(objectName, hasOwner);
+            return hasOwner;
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            this.logger?.log(`Error checking owner field for ${objectName}: ${errorMessage}`);
+            this.ownerFieldCache.set(objectName, false);
+            return false;
+        }
+    }
+}
+//# sourceMappingURL=ObjectFilteringService.js.map