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

package/lib/services/ObjectFilteringService.js

@@ -0,0 +1,1080 @@
+/*
+ * 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 { validateNonEmptyArray } from './validation.js';
+import { FEATURE_GATED_STANDARD_OBJECTS, MAX_OBJECT_NAMES } from './constants.js';
+/** Default number of objects to process concurrently in checkDataExistsInRange. */
+const DEFAULT_CONCURRENCY_LIMIT = 5;
+/**
+ * Upper bound on suspect-set reconciliation (CLI-4214). The `/limits/recordCount` hint
+ * omits empty and not-yet-counted objects; the service reconciles those "suspects" with a
+ * LIMIT-1 probe + targeted COUNT(). This cap stops the reconciliation from degenerating into
+ * a whole-org COUNT() sweep (the CLI-3083 governor blowup). Aligned with {@link MAX_OBJECT_NAMES}.
+ * When the suspect set exceeds the cap, the first 200 are reconciled and the remainder are
+ * surfaced as a truncation warning with `recordCount` left undefined — never silently zeroed.
+ */
+const RECONCILIATION_CAP = 200;
+/** 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']);
+/**
+ * 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'.`);
+        }
+        // Namespace validation is now performed at the parser boundary
+        // (`parseNamespaceFilter` in services/namespace-filter.ts). The typed
+        // NamespaceFilter discriminated union arriving here is already validated.
+        // 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.
+     *
+     * Accepts a typed `NamespaceFilter` (or `undefined` for "no filter"). CLI-3801
+     * replaced the previous `string | null` parameter with the discriminated union
+     * parsed by `parseNamespaceFilter` at the command/MCP boundary.
+     *
+     * - `undefined` → return objects unchanged
+     * - `kind: 'all'` → return objects unchanged
+     * - `kind: 'unmanaged'` → only objects without a namespace prefix
+     * - `kind: 'managed'` → objects matching any of the listed namespaces (case-insensitive)
+     */
+    static applyNamespaceFilter(objects, filter) {
+        if (filter === undefined || filter.kind === 'all') {
+            return objects;
+        }
+        if (filter.kind === 'unmanaged') {
+            return objects.filter((obj) => !ObjectFilteringService.extractNamespace(obj.name));
+        }
+        // kind === 'managed' — match any namespace in the list (case-insensitive).
+        // Salesforce namespaces are case-insensitive in org references and API calls.
+        const lowerSet = new Set(filter.namespaces.map((n) => n.toLowerCase()));
+        return objects.filter((obj) => {
+            const ns = ObjectFilteringService.extractNamespace(obj.name);
+            return ns !== undefined && lowerSet.has(ns.toLowerCase());
+        });
+    }
+    /**
+     * Converts a NamespaceFilter to the legacy string shape accepted by the ISV
+     * REST `filter-objects` endpoint. Used only on the REST delegation path —
+     * SOQL path consumes the typed filter directly via {@link applyNamespaceFilter}.
+     *
+     * Mapping:
+     * - `undefined` → `undefined` (no filter)
+     * - `kind: 'all'` → `undefined` (no filter — every namespace)
+     * - `kind: 'unmanaged'` → `''` (REST sentinel for unmanaged)
+     * - `kind: 'managed'` → first namespace in the list (multi-namespace OR is SOQL-only; additional namespaces are dropped on this path)
+     */
+    static namespaceFilterToRestString(filter) {
+        if (filter === undefined || filter.kind === 'all')
+            return undefined;
+        if (filter.kind === 'unmanaged')
+            return '';
+        // kind === 'managed' — the REST endpoint accepts a single namespace string.
+        return filter.namespaces[0];
+    }
+    /**
+     * Returns true when the filter is a managed filter with 2+ namespaces — the
+     * REST endpoint cannot represent multi-namespace OR-union, so callers route
+     * around REST delegation and use the local SOQL fallback instead.
+     */
+    static isMultiNamespaceFilter(filter) {
+        return filter !== undefined && filter.kind === 'managed' && filter.namespaces.length >= 2;
+    }
+    /**
+     * 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),
+     * OR name is a feature-gated standard object that fails ISV schema introspection
+     * (CLI-3783: objects visible in describeGlobal but inaccessible via Apex when
+     * the underlying feature/license is not active).
+     */
+    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;
+            if (FEATURE_GATED_STANDARD_OBJECTS.has(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. The qualifying set is `limits-present-with-count>0 ∪ probe-positive`
+     * (CLI-4214). Objects whose count is genuinely unknown (undefined recordCount — bulk call
+     * failed or reconciliation was capped) 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. Only AUTHORITATIVE zeros pass — a probe-negative suspect or a SOQL
+     * fallback 0 (CLI-4214). An object whose count is genuinely unknown (undefined recordCount,
+     * e.g. reconciliation failed or was capped) is excluded — it must NOT be silently classified
+     * as empty.
+     */
+    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`,
+                    // CLI-4214: carry forward reconciliation disclosures (e.g. truncation) produced
+                    // by filterViaRest → populateRecordCounts; the rebuilt result must not drop them.
+                    warnings: restFallbackResult.warnings,
+                    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.
+            //    CLI-4214: reconciliation may surface a truncation warning (suspect set > cap).
+            const countsRequired = options.withRecords === true || options.withoutRecords === true;
+            const populateResult = await this.populateRecordCounts(results, countsRequired);
+            results = populateResult.objects;
+            const populateWarnings = populateResult.warnings;
+            // 7-8. withRecords / withoutRecords predicate against populated counts. Shared with the
+            //      REST path via applyPostRestRecordCountFilter (single branch keeps complexity bounded).
+            results = ObjectFilteringService.applyPostRestRecordCountFilter(results, options);
+            // 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`,
+                warnings: populateWarnings.length > 0 ? populateWarnings : undefined,
+                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 filter - The typed NamespaceFilter to apply (undefined returns all objects)
+     * @returns ServiceResult containing filtered SObjectInfo array
+     */
+    async filterByNamespace(filter) {
+        // Validation is performed at the parser boundary (parseNamespaceFilter); the
+        // discriminated union arriving here is already well-formed.
+        return this.filter({ namespace: filter });
+    }
+    /**
+     * 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.
+     *
+     * Multi-namespace filters (`kind: 'managed'` with 2+ namespaces) bypass REST
+     * delegation because the ISV REST `filter-objects` endpoint accepts only a
+     * single namespace string. Sending only the first namespace would silently
+     * drop the rest — a correctness gap. The local SOQL path consumes the full
+     * NamespaceFilter via {@link applyNamespaceFilter} and matches correctly.
+     */
+    async tryRestDelegation(options, startTime) {
+        if (!this.restClient) {
+            return null;
+        }
+        if (ObjectFilteringService.isMultiNamespaceFilter(options.namespace)) {
+            this.logger?.log('Multi-namespace filter requested — bypassing REST delegation, using local SOQL path for OR-union');
+            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,
+            // CLI-3801: NamespaceFilter is converted to the legacy string shape the REST
+            // endpoint accepts. The endpoint accepts a single namespace string or empty
+            // string (== unmanaged); see ObjectFilterRestService.cls. Multi-namespace
+            // OR support is SOQL-only at this layer — the REST path collapses to the
+            // first namespace as the most honest fallback (a downstream client-side
+            // filter pass on the response is not run because the server already filtered;
+            // additional namespaces are lost when REST delegation is used).
+            namespace: ObjectFilteringService.namespaceFilterToRestString(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.
+        // CLI-3783: same posture for feature-gated standard objects — the server may
+        // emit them in describeGlobal-derived results, but the ISV definition-create
+        // call fails with E4402 on Apex SObjectBase.getSObjectSchema(). Strip them
+        // post-fetch on the same `excludeSystemObjects` switch.
+        // 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) && !FEATURE_GATED_STANDARD_OBJECTS.has(obj.name));
+            if (results.length !== before) {
+                this.logger?.log(`REST post-filter excluded ${before - results.length} non-data or feature-gated objects (CLI-3085, CLI-3783)`);
+            }
+        }
+        // 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 alreadyPopulated = results.some((obj) => obj.recordCount !== undefined && obj.recordCount !== null);
+        // CLI-4214: when the server did not pre-populate counts, run the same bulk + bounded
+        // reconciliation path as the local filter so truncation disclosures propagate.
+        const { objects: populated, warnings: populateWarnings } = alreadyPopulated
+            ? { objects: results, warnings: [] }
+            : await this.populateRecordCounts(results, countsRequired);
+        return createSuccessResult(populated, {
+            message: `Filtered ${String(populated.length)} objects via REST API`,
+            warnings: populateWarnings.length > 0 ? populateWarnings : undefined,
+            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`.
+     *
+     * CLI-4214 — `/limits/recordCount` is a HINT (returns only objects with count > 0), so objects it omits arrive ABSENT from the bulk map. Those form the "suspect set": their count is NOT known authoritatively. Suspects are reconciled in two bounded stages.
+     * Stage 1: LIMIT-1 presence probe (`SELECT Id FROM {obj} LIMIT 1`), batched at `concurrencyLimit` via {@link processInBatches} — mirrors {@link checkDataExistsInRange} / {@link probeDataForYear}.
+     * Stage 2: targeted SOQL `COUNT()` over probe-POSITIVE suspects → authoritative count (provenance `'queried'`). Probe-negative suspects are authoritative empties (recordCount 0, provenance `'queried'`).
+     * The suspect reconciliation is capped at {@link RECONCILIATION_CAP} to avoid a whole-org COUNT() sweep (CLI-3083). When the suspect set exceeds the cap, the first 200 are reconciled and the remainder are surfaced via an explicit truncation warning with `recordCount` left undefined (genuinely unknown — never silently zeroed).
+     *
+     * @param objects - SObjectInfo array to enrich with record counts
+     * @param required - Whether the caller's filter chain depends on accurate counts
+     * @returns Object holding the enriched array and any disclosure warnings (e.g. truncation)
+     * @throws Error when `required` is true and the bulk count query fails entirely
+     */
+    async populateRecordCounts(objects, required) {
+        if (objects.length === 0) {
+            return { objects, warnings: [] };
+        }
+        const objectNames = objects.map((obj) => obj.name);
+        const countsResult = await this.restApiAdapter.getRecordCounts(objectNames);
+        if (!countsResult.success) {
+            // Bulk call failed entirely. Preserve the existing soft-fail semantics: required=true
+            // throws (FILTER_FAILED upstream); required=false leaves recordCount undefined (— in display).
+            const message = `Record count query failed: ${countsResult.message ?? 'unknown error'}`;
+            this.logger?.log(message);
+            if (required) {
+                throw new Error(message);
+            }
+            return { objects, warnings: [] };
+        }
+        const limitsCounts = countsResult.data;
+        // A `/limits/recordCount` value > 0 is trusted as an approximate hint (provenance 'limits').
+        // A value that is ABSENT *or* exactly 0 is a SUSPECT — the endpoint is async-maintained and
+        // empirically returns BOTH omitted objects AND stale `0`s for objects that were last counted
+        // empty but now hold records (CLI-4214 covers both facets: the omitted "Opportunity" case and
+        // the stale-zero / undercount "Account reported 1 vs 526" case). A present-0 is therefore not
+        // authoritative until a SOQL probe confirms it; reconcile it like an omission.
+        const suspects = objects
+            .filter((obj) => {
+            const c = limitsCounts.get(obj.name);
+            return c === undefined || c === 0;
+        })
+            .map((obj) => obj.name);
+        const reconciliation = await this.reconcileSuspectCounts(suspects);
+        const enriched = objects.map((obj) => {
+            const limitsCount = limitsCounts.get(obj.name);
+            // Trust the hint only when it positively reports records (> 0). Absent or 0 → use the
+            // authoritative reconciliation result instead of the untrustworthy hint value.
+            if (limitsCount !== undefined && limitsCount > 0) {
+                return { ...obj, recordCount: limitsCount, recordCountProvenance: 'limits' };
+            }
+            const reconciled = reconciliation.counts.get(obj.name);
+            if (reconciled !== undefined) {
+                return { ...obj, recordCount: reconciled, recordCountProvenance: 'queried' };
+            }
+            // Genuinely unknown (beyond the reconciliation cap, or a reconciliation probe failed):
+            // leave recordCount undefined so it is never read as an authoritative 0.
+            return { ...obj, recordCount: undefined, recordCountProvenance: undefined };
+        });
+        return { objects: enriched, warnings: reconciliation.warnings };
+    }
+    /**
+     * Two-stage bounded reconciliation of the suspect set (CLI-4214).
+     *
+     * @param suspectNames - Object API names absent from the bulk `/limits/recordCount` map
+     * @returns Authoritative counts for the reconciled subset plus any truncation warnings; objects beyond {@link RECONCILIATION_CAP} are intentionally absent from `counts`.
+     */
+    async reconcileSuspectCounts(suspectNames) {
+        const counts = new Map();
+        const warnings = [];
+        if (suspectNames.length === 0) {
+            return { counts, warnings };
+        }
+        // BOUND: cap the reconciliation so we never run COUNT() over the whole org (CLI-3083).
+        const toReconcile = suspectNames.slice(0, RECONCILIATION_CAP);
+        if (suspectNames.length > RECONCILIATION_CAP) {
+            const unreconciled = suspectNames.length - RECONCILIATION_CAP;
+            warnings.push(`Record-count reconciliation capped at ${RECONCILIATION_CAP} of ${suspectNames.length} objects; ` +
+                `${unreconciled} objects could not be authoritatively counted.`);
+        }
+        // Stage 1 (cheap): LIMIT-1 presence probe, batched at concurrencyLimit.
+        const probeResults = await processInBatches(toReconcile, this.concurrencyLimit, async (name) => ({
+            name,
+            present: await this.probeObjectHasRecords(name),
+        }));
+        const positives = [];
+        for (const { name, present } of probeResults) {
+            if (present === true) {
+                positives.push(name);
+            }
+            else if (present === false) {
+                // Probe-negative suspect → AUTHORITATIVE empty (confirmed zero).
+                counts.set(name, 0);
+            }
+            // present === undefined → the probe itself FAILED. We cannot confirm presence or
+            // absence, so the count stays unknown (absent from `counts`) — never a silent 0.
+        }
+        // Stage 2 (small): authoritative COUNT() ONLY over probe-positive suspects.
+        const countResults = await processInBatches(positives, this.concurrencyLimit, async (name) => ({
+            name,
+            count: await this.countObjectRecords(name),
+        }));
+        for (const { name, count } of countResults) {
+            if (count !== undefined) {
+                counts.set(name, count);
+            }
+        }
+        return { counts, warnings };
+    }
+    /**
+     * Stage-1 LIMIT-1 presence probe for a single suspect object (CLI-4214).
+     * Mirrors {@link probeDataForYear} — same SOQL adapter, same query builder. Never throws.
+     *
+     * @param objectApiName - The object API name to probe
+     * @returns `true` when at least one record exists, `false` when authoritatively empty, `undefined` when the probe itself FAILED (presence unknown — must not be read as empty)
+     */
+    async probeObjectHasRecords(objectApiName) {
+        const soql = CuneiformQueryBuilder.create().select(['Id']).from(objectApiName).limit(1).toSOQL();
+        try {
+            const result = await this.soqlAdapter.query(soql);
+            if (!result.success) {
+                this.logger?.log(`Record presence probe failed for ${objectApiName}: ${result.message ?? 'unknown error'}`);
+                return undefined;
+            }
+            return result.data.records.length > 0;
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            this.logger?.log(`Record presence probe exception for ${objectApiName}: ${errorMessage}`);
+            return undefined;
+        }
+    }
+    /**
+     * Stage-2 authoritative `SELECT COUNT()` for a probe-positive suspect (CLI-4214).
+     * Uses the query builder `.count()` so the total arrives in `totalSize`. Never throws.
+     *
+     * @param objectApiName - The object API name to count
+     * @returns The authoritative record count, or undefined when the count query failed
+     */
+    async countObjectRecords(objectApiName) {
+        const soql = CuneiformQueryBuilder.create().count().from(objectApiName).toSOQL();
+        try {
+            const result = await this.soqlAdapter.query(soql);
+            if (!result.success) {
+                this.logger?.log(`Record count query failed for ${objectApiName}: ${result.message ?? 'unknown error'}`);
+                return undefined;
+            }
+            return result.data.totalSize;
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            this.logger?.log(`Record count exception for ${objectApiName}: ${errorMessage}`);
+            return undefined;
+        }
+    }
+    /**
+     * 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