sp_StatUpdate.sql

SET ANSI_NULLS ON;
GO
SET QUOTED_IDENTIFIER ON;
GO

/*

sp_StatUpdate - Priority-Based Statistics Maintenance

Copyright (c) 2026 Community Contribution
https://github.com/nanoDBA/sp_StatUpdate

Purpose:    Update statistics with DMV-based priority ordering and time limits.
            Refreshes stale stats including those with NORECOMPUTE (flag preserved).

Based on:   Ola Hallengren's IndexOptimize (MIT License)
            https://ola.hallengren.com

License:    MIT License

            Permission is hereby granted, free of charge, to any person obtaining a copy
            of this software and associated documentation files (the "Software"), to deal
            in the Software without restriction, including without limitation the rights
            to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
            copies of the Software, and to permit persons to whom the Software is
            furnished to do so, subject to the following conditions:

            The above copyright notice and this permission notice shall be included in all
            copies or substantial portions of the Software.

            THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
            IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
            FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
            AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
            LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
            OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
            SOFTWARE.

Version:    2.21.2026.03.10 (Major.Minor.YYYY.MM.DD)
            - Version logged to CommandLog ExtendedInfo on each run
            - Query: ExtendedInfo.value('(/Parameters/Version)[1]', 'nvarchar(20)')

History:    2.21.2026.03.10 - Fix Phase 6 QS object_id domain mismatch (#271): replaced broken
                            module-id join with plan XML table extraction + PARSENAME bracket
                            stripping. Both staged and legacy discovery paths fixed.
            2.20.2026.03.10 - 9 RFCs: @CommandLogRetentionDays param (#251), TRENDING @Help
                            topic (#243), ObjectId/StatsId in ExtendedInfo (#250), heartbeat
                            column cache (#245), PERSIST_SAMPLE_INADEQUATE warning (#246),
                            forced plan filter (#244, #249), container OOMKill warning (#247),
                            per-signal breakdown in @ReturnDetailedResults (#252)
            2.15.2026.03.05 - Peak hours plan cache warning (#184), NORECOMPUTE+ON PARTITIONS
                            syntax fix (#215), @Help completeness for all 66 parameters (#212, #213)
            2.14.2026.03.04 - Bulk resolution: 42 issues — safety guards, warnings, discovery
                            tie-breaker, parameter validation, empty partition skip, backup
                            mid-run detection, new @OrphanedRunThresholdHours parameter (#148)
            2.13.2026.03.04 - P3 fixes: @Databases='ALL' normalized to 'ALL_DATABASES' (#159),
                            empty string parameters normalized to NULL with warning (#198)
            2.12.2026.03.04 - P2 fixes: PERSIST_SAMPLE_PERCENT silent override warning (#183),
                            ROWLOCK+READPAST deadlock retry loop with exponential backoff (#163),
                            Query Store forced plans per-stat warning after stat update (#168)
            2.11.2026.03.04 - P1/P2 fixes: container memory warning always-on (#208),
                            MAXDOP gate KB reference added (#196), @Tables unqualified
                            name multi-schema ambiguity warning (#209)
            2.10.2026.03.04 - Security/correctness fixes: @CompletionNotifyTable SQL injection (#155),
                            QS forced plan warning broken join (#187), @DelayBetweenStats WAITFOR overshoot (#210)
            2.9.2026.03.04 - P2 bug fixes: XACT_ABORT, EngineEdition label, MAXDOP gate, CommandLog advisory, log space @FailFast, Phase 6 QS per-db, CommandLog dual-accounting, TOCTOU false failures, LIKE metachar escape
            2.8.2026.03.04 - Version format update: MMDD → MM.DD for readability; no behavior change
            2.8.2026.0303 - v2.8 Bug fixes for deploy, @Tables, CommandLog:
                          - Fix: Deploy fails on pre-v2.3 servers. SQL Server validates column
                            names at compile time; wrapped ParameterFingerprint and
                            LastStatCompletedAt references in sp_executesql (5 locations).
                          - Fix: @Tables='ALL' silently matched zero tables. Now normalized
                            to NULL (case-insensitive, whitespace-trimmed).
                          - Fix: CommandLog SP_STATUPDATE_START Command field showed '...'
                            truncation. Now shows @Databases, @Tables, @TimeLimit, @SortOrder,
                            and QS params (conditional).
            2.8.2026.0302 - v2.8 Comprehensive issue sweep (31 issues resolved):
                          - Feat: Query Store forced plan invalidation warning (#32, p1-critical).
                            After stats updates, automatically checks sys.query_store_plan for
                            forced plans on updated tables. Warns via @WarningsOut if found.
                          - Feat: @IncludeIndexedViews parameter (#49). Y = include statistics
                            on indexed views (views with clustered index). Default N.
                          - Feat: @LogSkippedToCommandLog parameter (#58). Writes CommandLog
                            entries for TOCTOU-skipped stats. For compliance audit trails.
                          - Feat: @ReturnDetailedResults parameter (#25). Returns second result
                            set with per-statistic detail for PowerShell/automation.
                          - Feat: @CompletionNotifyTable parameter (#64). Insert notification
                            row on all exit paths for ETL dependency chains. Auto-creates table.
                          - Feat: Transaction log space check (#61). Warns when log >90% full
                            during FULLSCAN operations. Prevents unwarned log growth.
                          - Feat: Stretch Database auto-skip (#55). Tables with remote data
                            archive are automatically excluded (deprecated feature, causes timeouts).
                          - Fix: Azure SQL MI vs DB distinction (#39). EngineEdition 5 (SQL DB)
                            vs 8 (MI) now detected separately with platform-specific warnings.
                          - Add: RLS detection (#60). Debug mode warns when Row-Level Security
                            policies exist on tables being updated (biased histogram risk).
                          - Add: Wide statistics detection (#59). Debug mode warns for stats
                            with >8 columns (tempdb/memory pressure risk during FULLSCAN).
                          - Add: Filtered index mismatch detection (#38). Debug mode warns when
                            stat filter_definition differs from index filter_definition.
                          - Add: Columnstore context detection (#28). Debug mode warns about
                            CCI modification_counter underreporting after bulk loads.
                          - Add: Computed column detection (#30). Debug mode warns about stats
                            on non-persisted computed columns (higher scan cost).
                          - Doc: @Help operational notes added for scheduling (#9), parallel
                            mode (#12), edition behavior (#36), PERSIST_SAMPLE_PERCENT (#11),
                            RCSI (#62), locking (#63), modification_counter semantics (#57),
                            quick start (#15, #16), consultant workflow (#46), Azure (#39).
            2.7.2026.0302 - v2.7 AG redo queue pause and tempdb pressure check:
                          - Feat: @MaxAGRedoQueueMB / @MaxAGWaitMinutes (#18). On AG primaries,
                            pauses stats when secondary redo queue exceeds threshold. Wait loop
                            with 30s recheck interval respects both @MaxAGWaitMinutes and @TimeLimit.
                            Non-AG instances skip check. Stop reason: AG_REDO_QUEUE.
                          - Feat: @MinTempdbFreeMB (#34). Per-stat tempdb free space check.
                            When breached: @FailFast=1 aborts with TEMPDB_PRESSURE, else warns
                            and continues. Important for FULLSCAN and Azure SQL.
                          - Debug banner now shows AG primary status, redo queue depth, and tempdb
                            free space. Warnings added for elevated redo queue (>100 MB) and low
                            tempdb (<100 MB) at startup.
            2.6.2026.0302 - v2.6 Multi-database direct mode:
                          - Fix: @Statistics and @StatisticsFromTable now respect @Databases
                            parameter (#44). Previously, DIRECT modes queried sys.stats in the
                            current database context only, silently ignoring @Databases. Now both
                            modes iterate all selected databases via dynamic SQL with USE, matching
                            the DISCOVERY mode pattern. Backwards compatible: when @Databases is
                            NULL, behavior is identical (loops once over current DB).
                          - Fix: DIRECT_TABLE column gap. Mode 1A was missing 5 columns that
                            DIRECT_STRING included: auto_created, histogram_steps, has_filter,
                            filter_definition, unfiltered_rows. Both modes now INSERT identical
                            column sets.
            2.5.2026.0302 - v2.5 Operational intelligence:
                          - Add: CommandLog index advisory (#31). Warns when dbo.CommandLog
                            lacks a nonclustered index on CommandType. Provides exact CREATE
                            INDEX DDL. Suppressed when a suitable index already exists.
                          - Add: Resource Governor detection (#35). Detects current session
                            workload group and MAX_DOP cap. Warns (always, not just debug)
                            when @MaxDOP > RG MAX_DOP — a silent production footgun.
                          - Doc: @LockTimeout semantics clarified (#51). @Help now documents
                            NULL vs -1 vs 0 vs positive values with recommendations.
                          - Fix: Version history dates corrected (v2.3 entries had wrong date).
                          - Closed: #53 (ALL_DATABASES already excludes system DBs), #41
                            (NORECOMPUTE already preserved), #14 (misfiled — diag tool param).
            2.4.2026.0302 - v2.4 Code quality and LLM navigability:
                          - Add: 19 region markers for LLM-friendly section navigation.
                            Enables surgical edits without full-file reprocessing.
                          - Fix: Collation-aware string comparisons (#48). All user-param-to-DMV-column
                            comparisons now include COLLATE DATABASE_DEFAULT. Affects @Databases LIKE,
                            @Tables IN, @ExcludeTables LIKE, @ExcludeStatistics LIKE, @Statistics joins,
                            @StatisticsFromTable joins. Prevents silent match failures on CS instances.
                          - Add: Per-phase timing in staged discovery (#40). Debug mode now reports
                            elapsed milliseconds for each of 6 discovery phases. Enables identification
                            of slow phases on databases with large catalogs (100K+ stats).
            2.3.2026.0227 - Bug fix batch (Issues #27, #33, #47, #50, #52, #66):
                          - Fix: sp_releaseapplock missing on queue CATCH RETURN path
                            (connection pool poison when queue init fails). (#27)
                          - Fix: @@TRANCOUNT check now returns immediately instead of
                            deferring to validation block. UPDATE STATISTICS acquires
                            Sch-M locks that escalate unpredictably inside caller
                            transactions. (#47)
                          - Fix: SET options enforcement added — proactively sets
                            ANSI_WARNINGS and ARITHABORT ON at startup (auto-reverts on
                            proc return). Prevents error 1934 from JDBC/linked server
                            connections. ANSI_NULLS captured at CREATE time. (#50)
                          - Fix: @Databases CTE MAXRECURSION raised from 500 to 0
                            (unlimited). Supports instances with 1000+ databases. (#66)
                          - Fix: ALL_DATABASES now filters with HAS_DBACCESS() to skip
                            SINGLE_USER databases held by other sessions. Per-database
                            TRY/CATCH prevents inaccessible databases from aborting the
                            entire run. (#52)
                          - Doc: @ExcludeStatistics/@ExcludeTables @Help text now documents
                            LIKE wildcard semantics (_ = single-char, [_] for literal). (#33)
            2.3.2026.0226 - v2.3 Code Review Implementation:
                            Trivial: MAXRECURSION 1000, sub-second durations, dm_exec_sessions,
                              ROWLOCK+READPAST, MAX_GRANT_PERCENT=25, TOCTOU message, hardware
                              context extension, JSON summary in ExtendedInfo END.
                            Low: @QueryStoreMetric AVG_CPU, @HoursStaleThreshold, @StopByTime,
                              @SkipTablesWithColumnstore, phase loss logging, CommandLog schema
                              check, @Help SAMPLING topic.
                            Medium: Stat-level LastStatCompletedAt, parameter fingerprint,
                              @CheckPermissionsOnly.
            2.2.2026.0220 - Adversarial Code Review (2 rounds):
                          Round 1 - Critical bug fixes:
                          - Fix: DIRECT_TABLE mode crash - INSERT column count mismatch for
                            is_published, is_tracked_by_cdc, temporal_type columns.
                          - Fix: DIRECT_STRING mode missing columns - added auto_created,
                            histogram_steps, has_filter, filter_definition, unfiltered_rows,
                            is_published, is_tracked_by_cdc, temporal_type to INSERT column list.
                          - Fix: @WarningsOut OUTPUT not populated when @Debug=0.
                          - Fix: Staged discovery fallback SELECTs missing 3 replication columns.
                          - Add: Re-entrancy guard via sp_getapplock (sp_HeapDoctor pattern).
                          - Add: TOCTOU check before UPDATE STATISTICS execution.
                          Round 2 - Additional fixes:
                          - Fix: Applock not released on 3 DIRECT_TABLE early-exit paths.
                          - Fix: @stats_processed counted TOCTOU-skipped stats (batch limit drift).
                          - Fix: Legacy discovery @DaysStaleThreshold missed never-updated stats
                            (NULL last_updated). Wrapped in ISNULL(..., 9999) like staged path.
                          - Fix: Incremental partition queries ran in wrong database context.
                            Added USE QUOTENAME(@current_database) to partition DMV queries.
                          - Fix: @WhatIfOutputTable SQL injection - added character blocklist.
                          - Fix: Orphan cleanup infinite loop when RunLabel XML is NULL.
                          - Fix: FORMAT() CLR dependency replaced with CONVERT-based formatting.
                          - Fix: All @Preset overrides broken - non-NULL parameter defaults caused
                            IS NULL checks to never fire. Changed to unconditional SET.
            2.1.2026.0219 - Phase 2 Extended Awareness:
                          - SYSDATETIME() consistency: All date/time functions now use SYSDATETIME()
                            instead of mixed GETDATE()/SYSDATETIME() for sub-second consistency.
                          - Azure SQL detection: Added @is_azure_sql flag and DTU/vCore consumption
                            warning for Azure SQL Database/MI/Edge environments.
                          - Hardware context: Debug mode shows CPU cores, memory, NUMA nodes, uptime.
                            Warns when uptime < 24h (QS/usage stats may be incomplete).
                          - RCSI awareness: Detects per-database Read Committed Snapshot Isolation
                            and snapshot isolation settings in debug output.
                          - Replication/CDC/Temporal awareness: Discovery now captures is_published,
                            is_tracked_by_cdc, and temporal_type. Progress output shows REPLICATED,
                            CDC, TEMPORAL flags for affected tables.
                          - Backup detection: Warns when backup operations are running (I/O competition).
                          - @MaxConsecutiveFailures parameter: Stops execution after N consecutive
                            failures to prevent cascading issues from shared resource problems.
                          - @WarningsOut OUTPUT parameter: Collects warnings (LOW_UPTIME, BACKUP_RUNNING,
                            AZURE_SQL) for programmatic access without parsing messages.
                          - @StopReasonOut OUTPUT parameter: Returns why execution stopped (COMPLETED,
                            TIME_LIMIT, BATCH_LIMIT, FAIL_FAST, CONSECUTIVE_FAILURES, etc.).
            2.0.2026.0212 - Phase 1 Environment Intelligence (v2.0 roadmap):
                          - CE Version/Compat Level: Shows per-database compatibility level and
                            effective CE version (70, 120, 130+) in debug output.
                          - Trace Flag Detection: Detects statistics-relevant trace flags (2371,
                            2389, 2390, 4139, 9481) and shows warnings for obsolete/misconfigured
                            flags. TF 2371 note for SQL 2016+ CL 130+, TF 9481 db-scoped config
                            recommendation, TF 2389/2390 modernization note.
                          - Database-Scoped Config: Detects LEGACY_CARDINALITY_ESTIMATION setting
                            and notes when CE is forced to legacy mode.
                          - SQL 2022 AUTO_DROP: Notes when AUTO_DROP feature is available.
                          - Fix: Phase validation now detects unexpected row loss between staged
                            discovery phases and falls back to legacy single-query mode. Prevents
                            processing incomplete data when DMV cross-applies fail silently.
                            (#2)
                          - Fix: Truncated partitions no longer force full RESAMPLE. Stale
                            partitions with data are updated via ON PARTITIONS(); empty/truncated
                            partitions are skipped. (#4/26)
                          - Fix: XE session script corrected - added sp_statement_starting and
                            sql_statement_starting events for during-execution visibility, fixed
                            invalid XE predicate syntax (IN() not supported, wait_type needs
                            numeric map_key values), replaced query_canceled with attention event,
                            added lock_escalation event, added start/complete correlation query.
                            (#8)
            1.9.2026.0206 - Feat: Added Status and StatusMessage columns to summary result set
                            for easy Agent job alerting (SUCCESS/WARNING/ERROR). Early-return
                            path (0 qualifying stats) now also returns the result set.
                            (Issue #2)
                          - Perf: Phase 6 Query Store enrichment now uses batched CTE + JOIN
                            instead of CROSS APPLY per row. Changes O(n) separate QS queries
                            to O(1) batched query with GROUP BY. Significant improvement on
                            databases with many statistics and large Query Store catalogs.
                            (Issue #4)
            1.9.2026.0129 - Fix: Changed @long_running_stats table variable PK from CLUSTERED to
                            NONCLUSTERED to eliminate "maximum key length 900 bytes" warning.
                            (4 sysname columns = 1024 bytes exceeds clustered limit but is fine
                            for nonclustered indexes which support up to 1700 bytes in SQL 2016+)
            1.9.2026.0128 - Additional Code Review Fixes:
                          - New @Preset parameter: NIGHTLY_MAINTENANCE, WEEKLY_FULL, OLTP_LIGHT,
                            WAREHOUSE_AGGRESSIVE for common configuration patterns
                          - @GroupByJoinPattern parameter (default Y): Updates commonly-joined tables together
                            to prevent "optimization cliff". Falls back silently if QS disabled/empty.
                          - @CleanupOrphanedRuns default changed from N to Y (with 24h threshold)
                          - LOCK_TIMEOUT now restores original session value instead of hardcoding -1
                          - XML entity decoding now includes &quot; and &apos; for complete coverage
                          - READPAST hint added to parallel mode queue for reduced lock contention
                          - @WhatIfOutputTable validates column DATA TYPES, not just names
                          - Query Store READ_ONLY warning when using @QueryStorePriority
                          - ##sp_StatUpdate_Progress global temp table for external monitoring
                            (opt-in via @ExposeProgressToAllSessions due to security - visible to all sessions)
                          - Debug mode now explains threshold interaction logic
            1.8.2026.0128 - Code Review Fixes (P1 & P2 issues from CODE_REVIEW_ANALYSIS.md):
                          - P1 #24: @LongRunningSamplePercent now caps at ~10M rows sampled.
                          - P1 #22: Added row-count validation between staged discovery phases.
                          - P1 #27: FOR XML PATH error aggregation decodes XML entities
                          - P1 #23: LOCK_TIMEOUT reset after UPDATE STATISTICS
                          - P1 #26: Incremental partition targeting cross-references sys.partitions.
                          - P2 #4: @DeadWorkerTimeoutMinutes default reduced from 30 to 15 minutes.
                          - P2 #10: @WhatIfOutputTable validates schema when table exists.
                          - P2 #20: Query Store Phase 6 operations skipped when QS disabled on DB.
            1.7.2026.0127 - BREAKING: @ModificationThreshold default 1000 → 5000 (less aggressive)
            1.6.2026.0127 - RunLabel in individual stat ExtendedInfo for run correlation
            1.6.2026.0128 - Staged Discovery (Performance):
                            New @StagedDiscovery parameter (default Y). 6-phase discovery
                            eliminates O(n²) DMV joins by: (1) collect basic candidates from
                            sys.stats, (2) batch enrich with sys.dm_db_stats_properties,
                            (3) pre-calculate tier thresholds (no inline SQRT), (4) apply
                            threshold filters, (5) add page counts for qualifying only,
                            (6) add Query Store data if enabled. Expected 6-12x improvement
                            on databases with 10K+ statistics. Use @StagedDiscovery=N for
                            legacy single-query behavior if needed.
                          - Adaptive Sampling for Long-Running Stats:
                            New @LongRunningThresholdMinutes and @LongRunningSamplePercent
                            parameters. Queries CommandLog for stats that historically took
                            longer than the threshold (or were killed) and automatically
                            applies a lower sample rate. Addresses the common problem of
                            large tables with 100% sample rates that never complete within
                            maintenance windows. Example: @LongRunningThresholdMinutes=240
                            forces 10% sample on stats that historically took >4 hours.
                          - New @ExcludeTables parameter: Exclude tables by pattern (supports %)
                            to skip problematic or low-priority tables entirely.
                          - New @CollectHeapForwarding parameter (default N): Controls whether
                            to query sys.dm_db_index_physical_stats for heap forwarding counts.
                            Default N for performance; set Y if you need forwarding diagnostics.
                          - New @WhatIfOutputTable parameter: When @Execute=N, writes generated
                            commands to specified table instead of just printing. Useful for
                            automation and command review. Table is auto-created if it doesn't
                            exist with columns: SequenceNum (IDENTITY), DatabaseName, SchemaName,
                            TableName, StatName, Command, ModificationCounter, DaysStale, PageCount.
                          - New @DeadWorkerTimeoutMinutes parameter (default 30): Enhanced dead
                            worker detection for parallel mode. In addition to checking
                            dm_exec_requests for session existence, considers worker dead if
                            no progress for N minutes (handles blocked/hung workers).
                          - Discovery now captures auto_created flag (sys.stats.auto_created)
                            and logs AutoCreated in ExtendedInfo XML. Enables deprioritization
                            of auto-created stats which SQL Server can recreate if needed.
                          - Discovery captures histogram step count (steps from dm_db_stats_properties)
                            and logs HistogramSteps in ExtendedInfo for diagnostic insight.
                          - New @CleanupOrphanedRuns parameter (default N): When Y, finds
                            SP_STATUPDATE_START entries without matching END (killed runs) and
                            inserts END markers with StopReason='KILLED' for clean audit trail.
                          - New @SortOrder = 'AUTO_CREATED': Processes user-created stats first
                            (auto_created=0), then auto-created stats. Useful when time-limited
                            to prioritize manually defined statistics over SQL Server auto-created.
                          - @WhatIfOutputTable auto-creates table if it doesn't exist (no longer
                            requires user to pre-create with specific schema).
                          - Created tools/sp_StatUpdate_XE_Session.sql: Extended Events session
                            for troubleshooting. Captures UPDATE STATISTICS commands, errors,
                            wait stats (LCK_M_SCH_*, CXPACKET), and long-running statements.
                          - Code quality: Replaced cursor-based error reporting with FOR XML
                            aggregation (SQL 2016 compatible). All validation errors now reported
                            in a single RAISERROR call instead of per-error cursor iteration.
            1.5.2026.0120 - CRITICAL: Fixed @ExcludeStatistics filter not working. The OR between
                            threshold logic blocks had incorrect operator precedence, causing
                            table/exclusion filters to only apply when @ThresholdLogic='AND'.
                            Wrapped both OR and AND threshold blocks in parentheses.
                          - Fix: @TargetNorecompute='N' now correctly filters to regular stats
                            only (no_recompute=0). Previously included all stats.
                          - Fix: Time/batch limit messages now use severity 10 (informational)
                            instead of severity 16 (error). Prevents SQL Agent jobs from
                            reporting failure when procedure stops gracefully at configured
                            limits. Return code remains 0 for successful execution; non-zero
                            only when actual stat update failures occur.
                          - Removed @StatisticsResample parameter (unnecessary/confusing).
                            RESAMPLE is now used automatically when appropriate: (1) when
                            PERSIST_SAMPLE_PERCENT is configured, (2) for incremental stats,
                            (3) for memory-optimized tables on SQL 2014. "Do no harm" approach.
            1.5.2026.0119 - Core logic fixes and new parameters based on code review analysis:
                            (1) Incremental stats partition targeting: Now queries
                                sys.dm_db_incremental_stats_properties to find which partitions
                                have modifications and only updates those (ON PARTITIONS clause).
                                Previously updated ALL partitions, defeating the purpose of
                                incremental statistics. SQL 2016 compatible (FOR XML PATH fallback).
                            (2) Query Store join reorder: Filter by object_id FIRST through
                                sys.query_store_query, then join to plans. Reduces intermediate
                                result set size on large Query Store catalogs.
                            (3) New @ExcludeStatistics parameter: Exclude stats by name pattern
                                (supports % wildcard), e.g., '_WA_Sys%' to skip auto-created stats.
                            (4) New @ProgressLogInterval parameter: Log SP_STATUPDATE_PROGRESS
                                to CommandLog every N stats for Agent job monitoring visibility.
            1.4.2026.0119d - Code review fixes:
                            (1) Tiered threshold cliff effect at 500/501 rows - added SQRT
                                alternative to first tier to smooth the transition.
                            (2) FilteredStatsStaleFactor now uses selectivity-adjusted threshold
                                instead of ratio check (ratio measures selectivity, not staleness).
                            (3) @parameters_string TRIM to prevent duplicate queues from whitespace.
                            (4) Query Store state check - only query if actual_state IN (1,2)
                                for READ_ONLY/READ_WRITE modes (avoids errors on disabled QS).
                            (5) Style: Changed 1/0 to 1 in EXISTS checks for clarity.
            1.4.2026.0119c - Bug fix: Arithmetic overflow (8115) in FILTERED_DRIFT sort order
                            and Query Store metric calculations. Changed int to bigint for
                            large value handling; added IIF() cap for ratio calculations.
            1.4.2026.0119b - Bug fix: @StatsInParallel=Y table claiming bug. @claimed_tables
                            table variable was not cleared between loop iterations, causing
                            SELECT TOP 1 to return stale data from previous claim attempts.
                            Workers would exit early with COMPLETED after processing 1 stat.
            1.4.2026.0119 - Query Store prioritization: @QueryStorePriority cross-references
                            sys.query_store_plan to prioritize statistics used by active queries.
                            @QueryStoreMinExecutions and @QueryStoreRecentHours control thresholds.
                            New QUERY_STORE sort order for query-driven maintenance.
                            Filtered statistics handling: @FilteredStatsMode (INCLUDE/EXCLUDE/
                            ONLY/PRIORITY) and @FilteredStatsStaleFactor detect filtered stats
                            with selectivity drift (unfiltered_rows/rows ratio) on partitioned data.
                            New FILTERED_DRIFT sort order. ExtendedInfo now logs HasFilter,
                            FilterDefinition, UnfilteredRows, FilteredDriftRatio, QSPlanCount,
                            QSTotalExecutions, QSLastExecution. QualifyReason now includes
                            QUERY_STORE_PRIORITY and FILTERED_DRIFT.
            1.3.2026.0119 - Multi-database support: Ola Hallengren-style keywords
                            (SYSTEM_DATABASES, USER_DATABASES, ALL_DATABASES,
                            AVAILABILITY_GROUP_DATABASES), wildcards (%), exclusions (-).
                            @IncludeSystemObjects parameter for system object statistics.
                            AG secondaries excluded automatically (warning, not error).
                            Bug fixes: RESAMPLE + PERSIST_SAMPLE_PERCENT conflict (1052),
                            RAISERROR bit parameter (2748), PERSIST invalid usage (153).
                            Code review hardening: STRING_SPLIT replaced with recursive CTE
                            for deterministic ordering, persisted_sample_percent respected,
                            OUTPUT parameters for automation, TRY/CATCH around CommandLog,
                            OPTION (RECOMPILE) on discovery queries, @commandlog_exists
                            caching, non-zero return code on failures for Agent jobs,
                            severity 16 on time/batch limits, MAXRECURSION 0 (unlimited).
            1.2.2026.0117 - Tiger Toolbox 5-tier adaptive thresholds (@TieredThresholds),
                            AND/OR threshold logic (@ThresholdLogic),
                            version-aware PERSIST_SAMPLE_PERCENT and MAXDOP.
                            Style refactor, @Help parameter,
                            incremental stats (@UpdateIncremental),
                            AG awareness, heap handling (index_id=0, PageCount),
                            memory-optimized tables, saner defaults.
            1.0.2026.0113 - Initial release with versioning, RUN_HEADER/FOOTER logging

Key Features:
    - RUN_HEADER/RUN_FOOTER logging to detect killed runs
    - Queue-based parallelism for large databases
    - Priority ordering (worst stats first)
    - Incremental statistics support (ON PARTITIONS)
    - RESAMPLE option for preserving sample rates
    - Availability Group awareness (prevents write attempts on secondaries)
    - Memory-optimized table handling
    - Heap forwarding pointer tracking

DROP-IN COMPATIBILITY with Ola Hallengren's SQL Server Maintenance Solution:
    https://ola.hallengren.com

    REQUIRED:
      - dbo.CommandLog table (https://ola.hallengren.com/scripts/CommandLog.sql)
        Used for all logging. Set @LogToTable = 'N' if you don't have it.

    OPTIONAL (for @StatsInParallel = 'Y'):
      - dbo.Queue table (https://ola.hallengren.com/scripts/Queue.sql)
      - dbo.QueueStatistic table (auto-created on first parallel run)

    NOT REQUIRED:
      - dbo.CommandExecute - sp_StatUpdate handles its own command execution

Note:       NORECOMPUTE flag is PRESERVED on update (not cleared).
            To clear NORECOMPUTE, manually DROP + CREATE the statistic.
*/

IF OBJECT_ID(N'dbo.sp_StatUpdate', N'P') IS NULL
BEGIN
    EXECUTE (N'CREATE PROCEDURE dbo.sp_StatUpdate AS RETURN 138;');
END;
GO

ALTER PROCEDURE
    dbo.sp_StatUpdate
(
    /*
    ============================================================================
    MODE 1: DIRECT - Pass specific statistics (skips DMV discovery)

    Three input methods (checked in order):
      1. @StatisticsFromTable - Name of temp/permanent table with stats list
      2. @Statistics            - Comma-separated 'Schema.Table.Stat' values
      3. NULL for both          - Use discovery mode
    ============================================================================
    */
    @Statistics sysname = NULL, /*'Schema.Table.Stat' or 'Table.Stat', comma-separated for multiple*/
    @StatisticsFromTable sysname = NULL, /*table name: '#MyStats', '##GlobalStats', 'dbo.StatsQueue'*/

    /*
    ============================================================================
    MODE 2: DISCOVERY - DMV-based candidate selection (when @Statistics is NULL)
    ============================================================================
    */
    /*
    PRESETS (v1.9): Common configurations in a single parameter.
    When @Preset is specified, it sets defaults for related parameters.
    You can still override individual parameters after the preset is applied.

    Available presets:
      NIGHTLY_MAINTENANCE - Balanced nightly job (1hr limit, tiered thresholds)
      WEEKLY_FULL - Weekly comprehensive update (4hr limit, lower thresholds)
      OLTP_LIGHT - Minimal impact for OLTP (30min, high thresholds, delay between stats)
      WAREHOUSE_AGGRESSIVE - Data warehouse (no time limit, low thresholds, FULLSCAN)
    */
    @Preset nvarchar(30) = NULL, /*NULL = use individual parameters. NIGHTLY_MAINTENANCE, WEEKLY_FULL, OLTP_LIGHT, WAREHOUSE_AGGRESSIVE*/
    @Databases nvarchar(max) = NULL, /*NULL = current database, SYSTEM_DATABASES, USER_DATABASES, ALL_DATABASES (excludes system), AVAILABILITY_GROUP_DATABASES, comma-separated, wildcards (%), exclusions (-)*/
    @Tables nvarchar(max) = NULL, /*NULL = all tables, or comma-separated 'Schema.Table'*/
    @ExcludeTables nvarchar(max) = NULL, /*comma-separated patterns to exclude (supports % wildcard), e.g., 'dbo.OrderHistory%' to skip archive tables*/
    @ExcludeStatistics nvarchar(max) = NULL, /*comma-separated patterns to exclude (supports % wildcard), e.g., '_WA_Sys%' to skip auto-created stats*/
    @TargetNorecompute nvarchar(10) = N'BOTH', /*Y = only NORECOMPUTE stats (primary use case - SQL auto-update ignores these), N = only regular stats, BOTH = all stats (default)*/
    @ModificationThreshold bigint = 5000, /*minimum modification_counter (note: when @TieredThresholds=1, tiered thresholds apply first; this value only affects large tables where tiered threshold is higher than this floor)*/
    @ModificationPercent float = NULL, /*alternative: min mod % of rows (SQRT-based)*/
    @TieredThresholds bit = 1, /*1 = use Tiger Toolbox 5-tier adaptive thresholds based on table size (0-500: 500 mods, 501-10K: 20%, 10K-100K: 15%, 100K-1M: 10%, 1M+: 5%). 0 = use fixed @ModificationThreshold*/
    @ThresholdLogic nvarchar(3) = N'OR', /*OR = any threshold qualifies (default), AND = all thresholds must be met*/
    @DaysStaleThreshold integer = NULL, /*minimum days since last update. Note: counts calendar day boundaries (midnight crossings), not 24-hour periods. Use @HoursStaleThreshold for precise time-based thresholds.*/
    @HoursStaleThreshold int = NULL, /*alternative to @DaysStaleThreshold using hours (DATEDIFF(HOUR,...)). Provides precise time-based threshold. Cannot be specified simultaneously with @DaysStaleThreshold.*/
    @MinPageCount bigint = 0, /*minimum table page count to process. 0 = no filter, 125 = ~1MB, 125000 = ~1GB. Use to skip tiny tables*/
    @IncludeSystemObjects nvarchar(1) = N'N', /*Y = include system object statistics (sys.* tables/views)*/
    @IncludeIndexedViews nvarchar(1) = N'N', /*Y = include statistics on indexed views (sys.stats on views with clustered index). N = user tables only (default). UPDATE STATISTICS on indexed views is valid SQL. (#49)*/
    @SkipTablesWithColumnstore nchar(1) = N'N', /*Y = skip tables that have a nonclustered columnstore index (type 5 or 6 in sys.indexes). Use when plan stability is paramount - updating rowstore stats on NCCI tables may change batch mode execution plans.*/
    @TemporalCoSchedule nvarchar(1) = N'Y', /*Y = when a system-versioned temporal table qualifies, also schedule history table stats. Prevents cross-table cardinality inconsistency for FOR SYSTEM_TIME queries. N = independent scheduling. (#201)*/
    @AscendingKeyBoost nvarchar(1) = N'Y', /*Y = identity/ascending key columns qualify with any modifications, bypassing normal threshold (#143). Detects via sys.identity_columns on leading stat column. N = normal threshold only.*/

    /*
    ============================================================================
    FILTERED STATISTICS (edge case handling for partitioned data)
    ============================================================================
    */
    @FilteredStatsMode nvarchar(10) = N'INCLUDE', /*INCLUDE = process all (default), EXCLUDE = skip filtered stats, ONLY = only process filtered stats, PRIORITY = boost filtered stats that show selectivity drift*/
    @FilteredStatsStaleFactor float = 2.0, /*for PRIORITY mode: trigger update when unfiltered_rows/rows exceeds this factor (detects filter predicate distribution changes)*/

    /*
    ============================================================================
    QUERY STORE PRIORITIZATION (query-driven stat maintenance)
    ============================================================================
    */
    @QueryStorePriority nvarchar(1) = NULL, /*Y = boost priority for stats on tables actively used by Query Store plans. N = ignore QS data. NULL = default (normalized to N'N' when no preset, or to N'Y' by OLTP_LIGHT preset). P2e fix v2.4: changed from N'N' to NULL to allow presets to override.*/
    @QueryStoreMetric nvarchar(20) = N'CPU', /*resource metric for priority: CPU (total CPU ms, default), DURATION (elapsed time), READS (logical I/O), EXECUTIONS (count), AVG_CPU (total_cpu_ms/execution_count - favors expensive single-execution queries over frequent cheap ones)*/
    @QueryStoreMinExecutions bigint = 100, /*minimum plan executions to boost priority*/
    @QueryStoreRecentHours integer = 168, /*plans executed in last N hours (default: 7 days). Intentionally short - recent query activity more relevant than 30-day history*/

    /*
    ============================================================================
    UPDATE BEHAVIOR (both modes)
    ============================================================================
    */
    @StatisticsSample integer = NULL, /*sample percent: NULL = let SQL Server decide (recommended), 1-100 = explicit %, 100 = FULLSCAN*/
    @PersistSamplePercent nvarchar(1) = N'Y', /*Y = add PERSIST_SAMPLE_PERCENT = ON (SQL 2016 SP1 CU4+) to remember sample rate*/
    @PersistSampleMinRows bigint = 1000000, /*Minimum sampled rows for RESAMPLE_PERSIST to fire. If computed sampled rows (row_count × persisted_pct%) fall below this, RESAMPLE is skipped to avoid low-quality histograms. NULL = no floor check.*/
    @MaxDOP integer = NULL, /*MAXDOP for UPDATE STATISTICS (SQL 2016 SP2+ / SQL 2017 CU3+). NULL = server default*/
    @MaxGrantPercent int = 10, /*Memory grant cap percent (1-100) for the candidate discovery SELECT ONLY. NOTE: Does NOT cap UPDATE STATISTICS memory (hint not valid on that statement). For stats memory control, use Resource Governor or reduce @StatisticsSample. Applied as OPTION(MAX_GRANT_PERCENT) on the internal ranking query. NULL = no hint. Default 10 limits memory monopolization during candidate enumeration.*/

    /*
    ============================================================================
    INCREMENTAL STATISTICS (partitioned tables only)
    ============================================================================
    */
    @UpdateIncremental bit = 1, /*1 = use ON PARTITIONS() for incremental stats*/

    /*
    ============================================================================
    EXECUTION CONTROL (both modes)
    ============================================================================
    */
    @TimeLimit integer = 3600, /*seconds (default: 1 hour, NULL = unlimited)*/
    @StopByTime nvarchar(8) = NULL, /*absolute wall-clock stop time (format: HH:MM or HH:MM:SS). Computes remaining seconds from now to specified time today. Overrides @TimeLimit when specified.*/
    @MaxSecondsPerStat int = NULL, /*P2c fix (v2.4): When @StopByTime/@TimeLimit is set, check CommandLog history. If estimated duration for a stat exceeds both this cap AND remaining seconds, skip with warning. NULL = no per-stat cap. Only skips if CommandLog history exists (conservative).*/
    @BatchLimit integer = NULL, /*max stats to update per run*/
    @SortOrder nvarchar(50) = N'MODIFICATION_COUNTER', /*priority: MODIFICATION_COUNTER, DAYS_STALE, RANDOM, PAGE_COUNT, QUERY_STORE, FILTERED_DRIFT, AUTO_CREATED*/
    @DelayBetweenStats integer = NULL, /*seconds to wait between stats updates. Use during OLTP hours to reduce contention; NULL = no delay*/
    @MaxConsecutiveFailures integer = NULL, /*stop after N consecutive failures (prevents cascading issues from shared resource problems). NULL = no limit*/
    @MaxAGRedoQueueMB integer = NULL, /*AG primary only: pause stats when any secondary redo queue exceeds this MB. NULL = disabled. Checks dm_hadr_database_replica_states before each stat update.*/
    @MaxAGWaitMinutes integer = 10, /*max minutes to wait for AG redo queue to drain before stopping (stop reason: AG_REDO_QUEUE). Only used when @MaxAGRedoQueueMB is set.*/

    /*
    ============================================================================
    JOIN PATTERN GROUPING (v1.9)
    Addresses the "optimization cliff" concern: partial updates
    can create INCONSISTENT stats between joined tables, causing wrong join orders.
    When enabled, stats on commonly-joined tables are updated together.
    ============================================================================
    */
    @GroupByJoinPattern nvarchar(1) = N'Y', /*Y (default) = group stats by Query Store join patterns (update joined tables together, prevents optimization cliffs). Falls back silently to priority ordering if QS disabled/empty. N = process by priority only*/
    @JoinPatternMinExecutions int = 100, /*minimum plan executions to consider when detecting join patterns*/

    /*
    ============================================================================
    ADAPTIVE SAMPLING FOR LONG-RUNNING STATS
    Addresses stats that historically take too long (e.g., >4 hours with 100% sample)
    by automatically applying a lower sample rate based on CommandLog history.
    ============================================================================
    */
    @LongRunningThresholdMinutes int = NULL, /*stats that took longer than this in CommandLog get forced sample rate. Requires existing CommandLog history - first run with this enabled will find nothing. (NULL = disabled)*/
    @LongRunningSamplePercent int = 10, /*sample percent to use for long-running stats (default: 10%)*/

    /*
    ============================================================================
    PERFORMANCE OPTIMIZATION
    ============================================================================
    */
    @StagedDiscovery nvarchar(1) = N'Y', /*Y = use 6-phase staged discovery (faster for large DBs), N = legacy single-query discovery*/
    @CollectHeapForwarding nvarchar(1) = N'N', /*Y = query dm_db_index_physical_stats for heap forwarding counts (slow), N = skip*/
    @MinTempdbFreeMB bigint = NULL, /*minimum tempdb free space (MB) before each stat update. NULL = disabled. When breached: @FailFast=1 aborts, else warns and continues. Especially important for FULLSCAN and Azure SQL.*/

    /*
    ============================================================================
    LOGGING & OUTPUT (both modes)
    ============================================================================
    */
    @LockTimeout integer = NULL, /*seconds to wait for schema locks. NULL = session default (typically infinite), -1 = infinite, 0 = fail immediately on any contention, positive = seconds. Recommended: 30-300 for parallel mode*/
    @LogToTable nvarchar(1) = N'Y', /*Y = log to dbo.CommandLog (requires table), N = no logging*/
    @LogSkippedToCommandLog nvarchar(1) = N'N', /*Y = write CommandLog entries for skipped statistics (TOCTOU/threshold-filtered) with Command='SKIPPED'. For compliance audit trails. (#58)*/
    @ProgressLogInterval int = NULL, /*log progress to CommandLog every N stats (for Agent job monitoring)*/
    @Execute nvarchar(1) = N'Y', /*Y = execute, N = print only (dry run)*/
    @ReturnDetailedResults bit = 0, /*1 = return second result set with per-statistic detail (database, schema, table, stat, command, duration_ms, result). For automation/PowerShell integration. (#25)*/
    @CompletionNotifyTable nvarchar(500) = NULL, /*table to receive notification row on all exit paths (RunLabel, StartTime, EndTime, StopReason, counts). Auto-created if not exists. For ETL dependency chains. (#64)*/
    @WhatIfOutputTable nvarchar(500) = NULL, /*table to receive commands when @Execute = N (for automation)*/
    @CheckPermissionsOnly nchar(1) = N'N', /*Y = check required permissions (VIEW ANY DATABASE, VIEW DATABASE STATE, ALTER on tables, INSERT on CommandLog) and report missing ones. Returns without executing any stats updates. Diagnostic mode only.*/
    @FailFast bit = 0, /*1 = abort on first error*/
    @Debug bit = 0, /*1 = verbose output*/
    @ExposeProgressToAllSessions nvarchar(1) = N'N', /*Y = create ##sp_StatUpdate_Progress global temp table (SECURITY NOTE: visible to ALL sessions on server). N = disabled (use @ProgressLogInterval for secure monitoring)*/
    @CleanupOrphanedRuns nvarchar(1) = N'Y', /*Y = mark orphaned SP_STATUPDATE_START entries (no END) as KILLED. v1.9: Default changed from N to Y*/
    @OrphanedRunThresholdHours int = 48, /*#148: Hours before a START entry with no END is considered orphaned. Default 48h to accommodate multi-day maintenance runs.*/
    @CommandLogRetentionDays int = 90, /*#251: Days of CommandLog history to scan for adaptive sampling, P2c skip estimation, and long-running stat detection. Default 90. Lower values reduce scan time on large CommandLog tables.*/

    /*
    ============================================================================
    PARALLEL EXECUTION (Ola Hallengren Queue pattern)

    When @StatsInParallel = 'Y':
      - First worker populates dbo.QueueStatistic with qualifying stats
      - All workers claim work via UPDATE ... WHERE TableStartTime IS NULL
      - Dead workers detected via sys.dm_exec_sessions (sleeping workers between stats appear in dm_exec_sessions but not dm_exec_requests)
      - Run same EXECUTE from multiple sessions/jobs for parallelism

    Prerequisites:
      - dbo.Queue table (https://ola.hallengren.com/scripts/Queue.sql)
      - dbo.QueueStatistic table (auto-created on first parallel run)
    ============================================================================
    */
    @StatsInParallel nvarchar(1) = N'N', /*Y = use queue-based parallel processing*/
    @MaxWorkers int = NULL, /*max concurrent parallel workers (#181). Before claiming work, count active sessions in QueueStatistic. If >= @MaxWorkers, exit cleanly with RAISERROR. NULL = unlimited.*/
    @DeadWorkerTimeoutMinutes int = 15, /*consider worker dead if no progress for N minutes (NULL = only check dm_exec_sessions). P2 #4: Reduced from 30 to 15 min.*/

    /*
    ============================================================================
    HELP & VERSION OUTPUT
    ============================================================================
    */
    @Help nvarchar(50) = N'0', /*1 = show help in SSMS result set. Named topics: 'SAMPLING' = sampling priority order documentation*/
    @Version varchar(20) = NULL OUTPUT, /*returns procedure version*/
    @VersionDate datetime = NULL OUTPUT, /*returns procedure version date*/

    /*
    ============================================================================
    SUMMARY OUTPUT (for automation - avoids parsing result sets)
    ============================================================================
    */
    @StatsFoundOut integer = NULL OUTPUT, /*total qualifying stats discovered*/
    @StatsProcessedOut integer = NULL OUTPUT, /*stats attempted (succeeded + failed)*/
    @StatsSucceededOut integer = NULL OUTPUT, /*stats updated successfully*/
    @StatsFailedOut integer = NULL OUTPUT, /*stats that failed to update*/
    @StatsRemainingOut integer = NULL OUTPUT, /*stats not processed (time/batch limit)*/
    @DurationSecondsOut integer = NULL OUTPUT, /*total run duration in seconds*/
    @WarningsOut nvarchar(max) = NULL OUTPUT, /*collected warnings for programmatic access*/
    @StopReasonOut nvarchar(50) = NULL OUTPUT /*why execution stopped: COMPLETED, TIME_LIMIT, BATCH_LIMIT, FAIL_FAST, CONSECUTIVE_FAILURES, etc.*/
)
WITH RECOMPILE
AS
BEGIN
    /*#region 02-INIT: SET options, version constants */
    SET NOCOUNT ON;
    SET XACT_ABORT ON;
    SET ARITHABORT ON;
    SET NUMERIC_ROUNDABORT OFF;

    /*
    ============================================================================
    VERSION AND CONSTANTS
    ============================================================================
    */
    DECLARE
        /* VERSION: Update BOTH @procedure_version AND @procedure_version_date together.
           Also update the header comment "Version:" line at the top of the file. */
        @procedure_version varchar(20) = '2.21.2026.03.10',
        @procedure_version_date datetime = '20260310',
        @procedure_name sysname = OBJECT_NAME(@@PROCID),
        @procedure_schema sysname = OBJECT_SCHEMA_NAME(@@PROCID);

    /*
    Set output parameters
    */
    SELECT
        @Version = @procedure_version,
        @VersionDate = @procedure_version_date;
    /*#endregion 02-INIT */

    /*#region 03-HELP: @Help parameter output */
    /*
    ============================================================================
    HELP SECTION
    ============================================================================
    */
    IF @Help IN (N'1', N'Y')
    BEGIN
        /*
        Introduction
        */
        SELECT
            introduction =
                N'Hi, I''m sp_StatUpdate!' UNION ALL
        SELECT
            N'I help you update statistics with priority ordering and time limits.' UNION ALL
        SELECT
            N'I can handle NORECOMPUTE stats, incremental stats, and memory-optimized tables.' UNION ALL
        SELECT
            N'for more info, visit: https://github.com/nanoDBA/sp_StatUpdate' UNION ALL
        SELECT
            N'' UNION ALL
        SELECT
            N'version: ' + @procedure_version + N' (' + CONVERT(nvarchar(10), @procedure_version_date, 120) + N')' UNION ALL
        SELECT
            N'v2.1 Phase 2: Extended Awareness (replication, CDC, temporal, consecutive failures)' UNION ALL
        SELECT
            N'v2.2: Adversarial review fixes (DIRECT mode crash, re-entrancy guard, TOCTOU check)' UNION ALL
        SELECT
            N'v2.3: Bug fixes (#27 applock leak, #47 open tran halt, #50 SET validation, #52 DB access, #66 MAXRECURSION)' UNION ALL
        SELECT
            N'v2.4: Region markers, collation-aware comparisons (#48), discovery phase timing (#40)' UNION ALL
        SELECT
            N'v2.5: CommandLog index advisory (#31), Resource Governor detection (#35), @LockTimeout docs (#51)' UNION ALL
        SELECT
            N'v2.6: Multi-database direct mode -- @Statistics and @StatisticsFromTable respect @Databases (#44)' UNION ALL
        SELECT
            N'v2.7: AG redo queue pause (#18), tempdb pressure check (#34)' UNION ALL
        SELECT
            N'v2.8: Comprehensive issue sweep — 31 issues resolved (QS forced plans, indexed views, log space, RLS/columnstore/filter detection)';

        /* P3f (v2.4): QUICK START section — printed before parameter list */
        RAISERROR(N'=============================================', 10, 1) WITH NOWAIT;
        RAISERROR(N'sp_StatUpdate — QUICK START', 10, 1) WITH NOWAIT;
        RAISERROR(N'=============================================', 10, 1) WITH NOWAIT;
        RAISERROR(N'The fastest path: use a @Preset for a pre-tuned configuration.', 10, 1) WITH NOWAIT;
        RAISERROR(N'', 10, 1) WITH NOWAIT;
        RAISERROR(N'  NIGHTLY_MAINTENANCE   Smart staleness + MAXDOP 4 + StopByTime-aware', 10, 1) WITH NOWAIT;
        RAISERROR(N'  WEEKLY_FULL           FULLSCAN on all user tables, no time limit', 10, 1) WITH NOWAIT;
        RAISERROR(N'  OLTP_LIGHT            Sample-only, MAXDOP 2, skips large tables', 10, 1) WITH NOWAIT;
        RAISERROR(N'  WAREHOUSE_AGGRESSIVE  FULLSCAN + parallel, dedicated maintenance windows', 10, 1) WITH NOWAIT;
        RAISERROR(N'', 10, 1) WITH NOWAIT;
        RAISERROR(N'Examples:', 10, 1) WITH NOWAIT;
        RAISERROR(N'  EXEC sp_StatUpdate @Preset = N''NIGHTLY_MAINTENANCE'', @Database = N''MyDB'';', 10, 1) WITH NOWAIT;
        RAISERROR(N'  EXEC sp_StatUpdate @Preset = N''WEEKLY_FULL'', @Execute = N''N''; -- dry run first', 10, 1) WITH NOWAIT;
        RAISERROR(N'', 10, 1) WITH NOWAIT;
        RAISERROR(N'Then use individual parameters below to fine-tune.', 10, 1) WITH NOWAIT;
        RAISERROR(N'=============================================', 10, 1) WITH NOWAIT;

        /*
        Parameter documentation
        */
        SELECT
            parameter_name =
                ap.name,
            data_type =
                t.name +
                CASE
                    WHEN t.name IN (N'varchar', N'nvarchar', N'char', N'nchar')
                    THEN N'(' +
                        CASE
                            WHEN ap.max_length = -1
                            THEN N'max'
                            WHEN t.name IN (N'nvarchar', N'nchar')
                            THEN CONVERT(nvarchar(10), ap.max_length / 2)
                            ELSE CONVERT(nvarchar(10), ap.max_length)
                        END + N')'
                    ELSE N''
                END,
            description =
                CASE ap.name
                    WHEN N'@Statistics'
                    THEN N'DIRECT MODE: comma-separated stat names (Schema.Table.Stat or Table.Stat)'
                    WHEN N'@StatisticsFromTable'
                    THEN N'DIRECT MODE: table name containing stats list (#temp, ##global, or dbo.Table)'
                    WHEN N'@Preset'
                    THEN N'NIGHTLY_MAINTENANCE, WEEKLY_FULL, OLTP_LIGHT, WAREHOUSE_AGGRESSIVE - sets common defaults'
                    WHEN N'@Databases'
                    THEN N'DISCOVERY: database(s) - NULL=current, SYSTEM_DATABASES, USER_DATABASES, ALL_DATABASES (excludes system), AVAILABILITY_GROUP_DATABASES, wildcards (%), exclusions (-)'
                    WHEN N'@Tables'
                    THEN N'DISCOVERY MODE: table filter (NULL = all, comma-separated Schema.Table)'
                    WHEN N'@ExcludeTables'
                    THEN N'DISCOVERY MODE: exclude tables by LIKE pattern (% = multi-char, _ = single-char wildcard, [_] for literal underscore)'
                    WHEN N'@ExcludeStatistics'
                    THEN N'DISCOVERY MODE: exclude stats by LIKE pattern (% = multi-char, _ = single-char wildcard, [_] for literal underscore)'
                    WHEN N'@IncludeSystemObjects'
                    THEN N'Y = include system object statistics (sys.* tables/views), N = user objects only'
                    WHEN N'@TargetNorecompute'
                    THEN N'Y = only NORECOMPUTE stats, N = only regular stats, BOTH = all stats'
                    WHEN N'@ModificationThreshold'
                    THEN N'minimum modification_counter to qualify for update'
                    WHEN N'@ModificationPercent'
                    THEN N'SQRT-based formula (mod_counter >= percent * SQRT(row_count))'
                    WHEN N'@TieredThresholds'
                    THEN N'1 = use Tiger Toolbox 5-tier adaptive thresholds (ignores @ModificationPercent)'
                    WHEN N'@ThresholdLogic'
                    THEN N'OR = any threshold qualifies, AND = all must be met'
                    WHEN N'@DaysStaleThreshold'
                    THEN N'minimum days since last update to qualify'
                    WHEN N'@MinPageCount'
                    THEN N'minimum used_page_count (125000 = ~1GB tables only)'
                    WHEN N'@StatisticsSample'
                    THEN N'sample percent: NULL = SQL Server decides, 100 = FULLSCAN'
                    WHEN N'@PersistSamplePercent'
                    THEN N'Y = add PERSIST_SAMPLE_PERCENT = ON to preserve sample rate'
                    WHEN N'@MaxDOP'
                    THEN N'MAXDOP for FULLSCAN operations (SQL Server 2016 SP2+)'
                    WHEN N'@MaxGrantPercent'
                    THEN N'Memory grant cap (1-100%) for candidate discovery query ONLY. Does NOT cap UPDATE STATISTICS memory (not valid syntax). To cap stats memory, use Resource Governor or reduce @StatisticsSample.'
                    WHEN N'@UpdateIncremental'
                    THEN N'1 = use ON PARTITIONS() for incremental stats on partitioned tables'
                    WHEN N'@TimeLimit'
                    THEN N'maximum seconds to run (NULL = unlimited, default: 18000 = 5 hours)'
                    WHEN N'@BatchLimit'
                    THEN N'maximum number of stats to update per run'
                    WHEN N'@SortOrder'
                    THEN N'priority ordering: MODIFICATION_COUNTER, DAYS_STALE, PAGE_COUNT, RANDOM, QUERY_STORE, FILTERED_DRIFT, AUTO_CREATED (user stats first)'
                    WHEN N'@GroupByJoinPattern'
                    THEN N'Y (default) = group stats by Query Store join patterns (prevents optimization cliffs, falls back if QS empty), N = priority only'
                    WHEN N'@JoinPatternMinExecutions'
                    THEN N'minimum plan executions to detect join patterns (default 100)'
                    WHEN N'@FilteredStatsMode'
                    THEN N'INCLUDE = all stats, EXCLUDE = skip filtered, ONLY = filtered only, PRIORITY = boost filtered with drift'
                    WHEN N'@FilteredStatsStaleFactor'
                    THEN N'PRIORITY mode threshold multiplier for selectivity-adjusted threshold (default 2.0)'
                    WHEN N'@QueryStorePriority'
                    THEN N'Y = prioritize stats used by Query Store plans, N = ignore'
                    WHEN N'@QueryStoreMetric'
                    THEN N'CPU = total CPU time (default), DURATION = elapsed time, READS = logical I/O, EXECUTIONS = count, AVG_CPU = avg CPU per execution (total_cpu_ms/execution_count, favors expensive single-run queries)'
                    WHEN N'@QueryStoreMinExecutions'
                    THEN N'minimum plan executions to boost priority (default 100)'
                    WHEN N'@QueryStoreRecentHours'
                    THEN N'only consider plans executed in last N hours (default 168 = 7 days)'
                    WHEN N'@DelayBetweenStats'
                    THEN N'seconds to wait between stats updates (pacing)'
                    WHEN N'@LongRunningThresholdMinutes'
                    THEN N'stats that took longer than this in CommandLog get forced sample rate (NULL = disabled)'
                    WHEN N'@LongRunningSamplePercent'
                    THEN N'sample percent for long-running stats (default 10%)'
                    WHEN N'@StagedDiscovery'
                    THEN N'Y = 6-phase staged discovery (faster for large DBs), N = legacy single query'
                    WHEN N'@CollectHeapForwarding'
                    THEN N'Y = collect heap forwarding pointer counts (slow), N = skip for performance'
                    WHEN N'@LockTimeout'
                    THEN N'seconds to wait for schema locks. NULL = session default, -1 = infinite wait, 0 = fail immediately on any contention, positive = seconds before timeout. Recommended: 30-300 for parallel mode.'
                    WHEN N'@LogToTable'
                    THEN N'Y = log to dbo.CommandLog table'
                    WHEN N'@ProgressLogInterval'
                    THEN N'log SP_STATUPDATE_PROGRESS to CommandLog every N stats (Agent job monitoring). Requires @LogToTable=Y. Progress entries include StatsProcessed, StatsSucceeded, StatsFailed, StatsTotal, ElapsedSeconds in ExtendedInfo XML.'
                    WHEN N'@Execute'
                    THEN N'Y = execute commands, N = print only (dry run)'
                    WHEN N'@WhatIfOutputTable'
                    THEN N'table to receive commands when @Execute = N (for automation scripts)'
                    WHEN N'@FailFast'
                    THEN N'1 = abort on first error, 0 = continue processing'
                    WHEN N'@Debug'
                    THEN N'1 = verbose diagnostic output'
                    WHEN N'@ExposeProgressToAllSessions'
                    THEN N'Y = create ##sp_StatUpdate_Progress (SECURITY: visible to ALL sessions). Use @ProgressLogInterval for secure monitoring.'
                    WHEN N'@CleanupOrphanedRuns'
                    THEN N'Y (default) = mark orphaned START entries >24h old (killed runs) with END marker'
                    WHEN N'@HoursStaleThreshold'
                    THEN N'alternative to @DaysStaleThreshold using precise hours (DATEDIFF HOUR). Note: @DaysStaleThreshold counts calendar midnight crossings, not 24-hour periods. Cannot be combined with @DaysStaleThreshold.'
                    WHEN N'@MaxSecondsPerStat'
                    THEN N'ADVISORY per-stat scheduling gate (NOT a hard timeout). Skips a stat when its estimated duration (from CommandLog history) exceeds BOTH this cap AND remaining window time. A stat with no CommandLog history always runs. Does not kill running UPDATE STATISTICS. NULL = disabled.'
                    WHEN N'@PersistSampleMinRows'
                    THEN N'minimum absolute sampled rows before RESAMPLE_PERSIST fires. If row_count * persisted_pct% < this value, RESAMPLE is skipped to avoid low-quality histograms. NULL = no floor check. Default 1000000.'
                    WHEN N'@StopByTime'
                    THEN N'wall-clock stop time (HH:MM or HH:MM:SS). Computes remaining seconds from now to specified time today and uses as @TimeLimit. Overrides @TimeLimit when specified.'
                    WHEN N'@SkipTablesWithColumnstore'
                    THEN N'Y = skip tables with nonclustered/clustered columnstore indexes (type 5/6 in sys.indexes). Use when plan stability is critical — updating rowstore stats alongside NCCIs may change batch mode execution plans.'
                    WHEN N'@TemporalCoSchedule'
                    THEN N'Y = when a system-versioned temporal table qualifies, also schedule its history table stats (#201). Prevents cardinality inconsistency for FOR SYSTEM_TIME queries that join current + history tables. N = independent scheduling.'
                    WHEN N'@AscendingKeyBoost'
                    THEN N'Y = identity/ascending key columns qualify with any modifications, bypassing normal threshold (#143). Detects via sys.identity_columns on the stat''s leading column. Prevents histogram staleness for insert-heavy tables. N = normal threshold only.'
                    WHEN N'@CheckPermissionsOnly'
                    THEN N'Y = check required permissions (VIEW ANY DATABASE, VIEW DATABASE STATE, INSERT on CommandLog) and report missing ones. No stats updates are executed. Diagnostic mode.'
                    WHEN N'@StatsInParallel'
                    THEN N'Y = use queue-based parallel processing (requires Queue tables)'
                    WHEN N'@MaxWorkers'
                    THEN N'max concurrent parallel workers (#181). Before joining queue, counts active sessions. If >= limit, exits cleanly (StopReason=MAX_WORKERS, return 0). NULL = unlimited. Use to prevent blocking storms on OLTP systems.'
                    WHEN N'@DeadWorkerTimeoutMinutes'
                    THEN N'parallel mode: consider worker dead if no progress for N minutes (default 15). Uses LastStatCompletedAt heartbeat column for accurate per-stat tracking. Units: minutes (same as @MaxAGWaitMinutes). Only applies when @StatsInParallel=Y.'
                    WHEN N'@CommandLogRetentionDays'
                    THEN N'days of CommandLog history to scan for adaptive sampling, P2c skip estimation, and long-running stat detection. Lower values reduce I/O on large CommandLog tables. (#251)'
                    WHEN N'@Help'
                    THEN N'1 = show this help information. Named topics: SAMPLING = sampling priority order, TRENDING = CommandLog trend queries.'
                    WHEN N'@Version'
                    THEN N'OUTPUT: returns procedure version string'
                    WHEN N'@VersionDate'
                    THEN N'OUTPUT: returns procedure version date'
                    WHEN N'@StatsFoundOut'
                    THEN N'OUTPUT: total qualifying stats discovered'
                    WHEN N'@StatsProcessedOut'
                    THEN N'OUTPUT: stats attempted (succeeded + failed)'
                    WHEN N'@StatsSucceededOut'
                    THEN N'OUTPUT: stats updated successfully'
                    WHEN N'@StatsFailedOut'
                    THEN N'OUTPUT: stats that failed to update'
                    WHEN N'@StatsRemainingOut'
                    THEN N'OUTPUT: stats not processed (time/batch limit)'
                    WHEN N'@DurationSecondsOut'
                    THEN N'OUTPUT: total run duration in seconds'
                    WHEN N'@WarningsOut'
                    THEN N'OUTPUT: collected warnings (LOW_UPTIME, BACKUP_RUNNING, AZURE_SQL, etc.)'
                    WHEN N'@StopReasonOut'
                    THEN N'OUTPUT: why execution stopped (COMPLETED, TIME_LIMIT, BATCH_LIMIT, FAIL_FAST, CONSECUTIVE_FAILURES, AG_REDO_QUEUE, TEMPDB_PRESSURE, LOG_SPACE_HIGH)'
                    WHEN N'@MaxConsecutiveFailures'
                    THEN N'stop after N consecutive failures (prevents cascading issues from shared resource problems)'
                    WHEN N'@MaxAGRedoQueueMB'
                    THEN N'AG primary only: pause stats when any secondary redo queue exceeds threshold MB. Checks dm_hadr_database_replica_states before each stat. Non-AG instances skip check. NULL = disabled.'
                    WHEN N'@MaxAGWaitMinutes'
                    THEN N'max minutes to wait for AG redo queue to drain before stopping with AG_REDO_QUEUE. Interacts with @TimeLimit (whichever is reached first wins). Default 10.'
                    WHEN N'@MinTempdbFreeMB'
                    THEN N'minimum tempdb free space (MB) before each stat update. When breached: @FailFast=1 aborts with TEMPDB_PRESSURE, else warns and continues. Important for FULLSCAN and Azure SQL. NULL = disabled.'
                    WHEN N'@IncludeIndexedViews'
                    THEN N'Y = include statistics on indexed views (views with clustered index). N (default) = user tables only. UPDATE STATISTICS on indexed views is valid SQL syntax.'
                    WHEN N'@LogSkippedToCommandLog'
                    THEN N'Y = write CommandLog entries for TOCTOU-skipped stats (Command=SKIPPED) and @MaxSecondsPerStat-skipped stats. For compliance audit trails. Requires @LogToTable=Y. Skipped stats also appear in @ReturnDetailedResults if enabled. N (default) = skip silently.'
                    WHEN N'@ReturnDetailedResults'
                    THEN N'1 = return second result set with per-statistic detail (database, schema, table, stat, mods, priority, processed). For PowerShell/automation.'
                    WHEN N'@CompletionNotifyTable'
                    THEN N'table to receive notification row on all exit paths (RunLabel, times, counts, StopReason). Auto-created if not exists. For ETL dependency chains. NULL = disabled.'
                    ELSE N'undocumented parameter'
                END,
            valid_inputs =
                CASE ap.name
                    /* String filters */
                    WHEN N'@Statistics' THEN N'NULL, schema.table.stat CSV (e.g., dbo.Orders.IX_Date)'
                    WHEN N'@StatisticsFromTable' THEN N'NULL, table name (e.g., #MyStats, dbo.StatsQueue)'
                    WHEN N'@Databases' THEN N'NULL, name/CSV/keyword (USER_DATABASES, ALL_DATABASES, SYSTEM_DATABASES, %wildcard%, -exclusion)'
                    WHEN N'@Tables' THEN N'NULL, ALL, schema.table CSV (supports % wildcards)'
                    WHEN N'@ExcludeTables' THEN N'NULL, schema.table CSV (supports % wildcards)'
                    WHEN N'@ExcludeStatistics' THEN N'NULL, stat name CSV (supports % wildcards, e.g., _WA_Sys%)'
                    /* Y/N toggles */
                    WHEN N'@IncludeSystemObjects' THEN N'Y, N'
                    WHEN N'@IncludeIndexedViews' THEN N'Y, N'
                    WHEN N'@TargetNorecompute' THEN N'Y, N, BOTH'
                    WHEN N'@SkipTablesWithColumnstore' THEN N'Y, N'
                    WHEN N'@TemporalCoSchedule' THEN N'Y, N'
                    WHEN N'@AscendingKeyBoost' THEN N'Y, N'
                    WHEN N'@QueryStorePriority' THEN N'Y, N'
                    WHEN N'@GroupByJoinPattern' THEN N'Y, N'
                    WHEN N'@StagedDiscovery' THEN N'Y, N'
                    WHEN N'@CollectHeapForwarding' THEN N'Y, N'
                    WHEN N'@LogToTable' THEN N'Y, N'
                    WHEN N'@LogSkippedToCommandLog' THEN N'Y, N'
                    WHEN N'@Execute' THEN N'Y, N'
                    WHEN N'@PersistSamplePercent' THEN N'Y, N'
                    WHEN N'@StatsInParallel' THEN N'Y, N'
                    WHEN N'@CleanupOrphanedRuns' THEN N'Y, N'
                    WHEN N'@ExposeProgressToAllSessions' THEN N'Y, N'
                    WHEN N'@CheckPermissionsOnly' THEN N'Y, N'
                    /* Enums */
                    WHEN N'@Preset' THEN N'NULL, NIGHTLY_MAINTENANCE, WEEKLY_FULL, OLTP_LIGHT, WAREHOUSE_AGGRESSIVE'
                    WHEN N'@SortOrder' THEN N'MODIFICATION_COUNTER, DAYS_STALE, PAGE_COUNT, RANDOM, QUERY_STORE, FILTERED_DRIFT, AUTO_CREATED'
                    WHEN N'@FilteredStatsMode' THEN N'INCLUDE, EXCLUDE, ONLY, PRIORITY'
                    WHEN N'@QueryStoreMetric' THEN N'CPU, DURATION, READS, EXECUTIONS, AVG_CPU'
                    WHEN N'@ThresholdLogic' THEN N'OR, AND'
                    /* Numeric */
                    WHEN N'@ModificationThreshold' THEN N'0-N (floor for modification_counter)'
                    WHEN N'@ModificationPercent' THEN N'NULL, 0.01-100 (percent of rows)'
                    WHEN N'@TieredThresholds' THEN N'0, 1'
                    WHEN N'@DaysStaleThreshold' THEN N'NULL, 1-N days'
                    WHEN N'@HoursStaleThreshold' THEN N'NULL, 1-N hours'
                    WHEN N'@MinPageCount' THEN N'0-N (125000 ≈ 1 GB)'
                    WHEN N'@FilteredStatsStaleFactor' THEN N'0.1-N (ratio of unfiltered/filtered rows)'
                    WHEN N'@QueryStoreMinExecutions' THEN N'1-N (plan execution count floor)'
                    WHEN N'@QueryStoreRecentHours' THEN N'1-N hours'
                    WHEN N'@JoinPatternMinExecutions' THEN N'1-N (default 100)'
                    WHEN N'@StatisticsSample' THEN N'NULL, 1-100 (100 = FULLSCAN)'
                    WHEN N'@MaxDOP' THEN N'NULL (server default), 0-N'
                    WHEN N'@MaxGrantPercent' THEN N'NULL (server default), 0.01-100'
                    WHEN N'@UpdateIncremental' THEN N'0, 1'
                    WHEN N'@TimeLimit' THEN N'NULL (unlimited), 1-N seconds'
                    WHEN N'@StopByTime' THEN N'NULL, HH:MM (e.g., 05:00, 23:59)'
                    WHEN N'@BatchLimit' THEN N'NULL (no limit), 1-N stats'
                    WHEN N'@DelayBetweenStats' THEN N'NULL, 1-N seconds'
                    WHEN N'@LongRunningThresholdMinutes' THEN N'NULL (disabled), 1-N minutes'
                    WHEN N'@LongRunningSamplePercent' THEN N'1-100'
                    WHEN N'@LockTimeout' THEN N'NULL (session default), -1 (infinite), 0-N seconds'
                    WHEN N'@ProgressLogInterval' THEN N'NULL, 1-N (e.g., 10, 50, 100)'
                    WHEN N'@MaxConsecutiveFailures' THEN N'NULL, 1-N (e.g., 3, 5, 10)'
                    WHEN N'@MaxAGRedoQueueMB' THEN N'NULL (disabled), 0-N MB'
                    WHEN N'@MaxAGWaitMinutes' THEN N'1-N minutes'
                    WHEN N'@MinTempdbFreeMB' THEN N'NULL (disabled), 0-N MB'
                    WHEN N'@MaxSecondsPerStat' THEN N'NULL (disabled), 1-N seconds'
                    WHEN N'@PersistSampleMinRows' THEN N'NULL (no floor), 1-N rows'
                    WHEN N'@OrphanedRunThresholdHours' THEN N'1-N hours'
                    WHEN N'@CommandLogRetentionDays' THEN N'1-N days'
                    WHEN N'@MaxWorkers' THEN N'NULL (unlimited), 1-N workers'
                    WHEN N'@DeadWorkerTimeoutMinutes' THEN N'NULL, 1-N minutes'
                    WHEN N'@ReturnDetailedResults' THEN N'0, 1'
                    WHEN N'@FailFast' THEN N'0, 1'
                    WHEN N'@Debug' THEN N'0, 1'
                    WHEN N'@Help' THEN N'0, 1'
                    /* Table/string references */
                    WHEN N'@WhatIfOutputTable' THEN N'NULL, table name (auto-created if not exists)'
                    WHEN N'@CompletionNotifyTable' THEN N'NULL, table name (auto-created if not exists)'
                    /* OUTPUT parameters */
                    WHEN N'@Version' THEN N'OUTPUT nvarchar(30)'
                    WHEN N'@VersionDate' THEN N'OUTPUT datetime'
                    WHEN N'@StatsFoundOut' THEN N'OUTPUT int'
                    WHEN N'@StatsProcessedOut' THEN N'OUTPUT int'
                    WHEN N'@StatsSucceededOut' THEN N'OUTPUT int'
                    WHEN N'@StatsFailedOut' THEN N'OUTPUT int'
                    WHEN N'@StatsRemainingOut' THEN N'OUTPUT int'
                    WHEN N'@DurationSecondsOut' THEN N'OUTPUT int'
                    WHEN N'@WarningsOut' THEN N'OUTPUT nvarchar(max)'
                    WHEN N'@StopReasonOut' THEN N'OUTPUT nvarchar(50)'
                    ELSE N''
                END,
            defaults =
                CASE ap.name
                    WHEN N'@Statistics'
                    THEN N'NULL (use discovery mode)'
                    WHEN N'@StatisticsFromTable'
                    THEN N'NULL'
                    WHEN N'@Databases'
                    THEN N'NULL (current database)'
                    WHEN N'@Tables'
                    THEN N'NULL (all tables)'
                    WHEN N'@ExcludeTables'
                    THEN N'NULL (no exclusions)'
                    WHEN N'@ExcludeStatistics'
                    THEN N'NULL (no exclusions)'
                    WHEN N'@IncludeSystemObjects'
                    THEN N'N'
                    WHEN N'@TargetNorecompute'
                    THEN N'BOTH'
                    WHEN N'@ModificationThreshold'
                    THEN N'5000'
                    WHEN N'@ModificationPercent'
                    THEN N'NULL'
                    WHEN N'@TieredThresholds'
                    THEN N'1'
                    WHEN N'@ThresholdLogic'
                    THEN N'OR'
                    WHEN N'@DaysStaleThreshold'
                    THEN N'NULL'
                    WHEN N'@HoursStaleThreshold'
                    THEN N'NULL'
                    WHEN N'@StopByTime'
                    THEN N'NULL'
                    WHEN N'@SkipTablesWithColumnstore'
                    THEN N'N'
                    WHEN N'@TemporalCoSchedule'
                    THEN N'Y'
                    WHEN N'@AscendingKeyBoost'
                    THEN N'Y'
                    WHEN N'@CheckPermissionsOnly'
                    THEN N'N'
                    WHEN N'@MinPageCount'
                    THEN N'0'
                    WHEN N'@StatisticsSample'
                    THEN N'NULL (SQL Server decides)'
                    WHEN N'@PersistSamplePercent'
                    THEN N'Y'
                    WHEN N'@MaxDOP'
                    THEN N'NULL'
                    WHEN N'@UpdateIncremental'
                    THEN N'1'
                    WHEN N'@TimeLimit'
                    THEN N'3600 (1 hour)'
                    WHEN N'@BatchLimit'
                    THEN N'NULL (no limit)'
                    WHEN N'@SortOrder'
                    THEN N'MODIFICATION_COUNTER'
                    WHEN N'@FilteredStatsMode'
                    THEN N'INCLUDE'
                    WHEN N'@FilteredStatsStaleFactor'
                    THEN N'2.0'
                    WHEN N'@QueryStorePriority'
                    THEN N'N'
                    WHEN N'@QueryStoreMetric'
                    THEN N'CPU'
                    WHEN N'@QueryStoreMinExecutions'
                    THEN N'100'
                    WHEN N'@QueryStoreRecentHours'
                    THEN N'168 (7 days)'
                    WHEN N'@DelayBetweenStats'
                    THEN N'NULL'
                    WHEN N'@LongRunningThresholdMinutes'
                    THEN N'NULL (disabled)'
                    WHEN N'@LongRunningSamplePercent'
                    THEN N'10'
                    WHEN N'@StagedDiscovery'
                    THEN N'Y'
                    WHEN N'@CollectHeapForwarding'
                    THEN N'N'
                    WHEN N'@LockTimeout'
                    THEN N'NULL (session default)'
                    WHEN N'@LogToTable'
                    THEN N'Y'
                    WHEN N'@ProgressLogInterval'
                    THEN N'NULL (disabled)'
                    WHEN N'@Execute'
                    THEN N'Y'
                    WHEN N'@WhatIfOutputTable'
                    THEN N'NULL'
                    WHEN N'@FailFast'
                    THEN N'0'
                    WHEN N'@Debug'
                    THEN N'0'
                    WHEN N'@ExposeProgressToAllSessions'
                    THEN N'N'
                    WHEN N'@CleanupOrphanedRuns'
                    THEN N'Y'
                    WHEN N'@StatsInParallel'
                    THEN N'N'
                    WHEN N'@MaxWorkers'
                    THEN N'NULL (unlimited)'
                    WHEN N'@DeadWorkerTimeoutMinutes'
                    THEN N'15'
                    WHEN N'@Help'
                    THEN N'0'
                    WHEN N'@MaxConsecutiveFailures'
                    THEN N'NULL (no limit)'
                    WHEN N'@WarningsOut'
                    THEN N'NULL (OUTPUT)'
                    WHEN N'@StopReasonOut'
                    THEN N'NULL (OUTPUT)'
                    WHEN N'@MaxAGRedoQueueMB'
                    THEN N'NULL (disabled)'
                    WHEN N'@MaxAGWaitMinutes'
                    THEN N'10'
                    WHEN N'@MinTempdbFreeMB'
                    THEN N'NULL (disabled)'
                    WHEN N'@MaxSecondsPerStat'
                    THEN N'NULL (disabled)'
                    WHEN N'@PersistSampleMinRows'
                    THEN N'1000000'
                    WHEN N'@Preset'
                    THEN N'NULL'
                    WHEN N'@IncludeIndexedViews'
                    THEN N'N'
                    WHEN N'@MaxGrantPercent'
                    THEN N'NULL'
                    WHEN N'@GroupByJoinPattern'
                    THEN N'Y'
                    WHEN N'@JoinPatternMinExecutions'
                    THEN N'100'
                    WHEN N'@LogSkippedToCommandLog'
                    THEN N'N'
                    WHEN N'@ReturnDetailedResults'
                    THEN N'0'
                    WHEN N'@CompletionNotifyTable'
                    THEN N'NULL'
                    WHEN N'@OrphanedRunThresholdHours'
                    THEN N'48'
                    WHEN N'@CommandLogRetentionDays'
                    THEN N'90'
                    WHEN N'@Version'
                    THEN N'OUTPUT'
                    WHEN N'@VersionDate'
                    THEN N'OUTPUT'
                    WHEN N'@StatsFoundOut'
                    THEN N'OUTPUT'
                    WHEN N'@StatsProcessedOut'
                    THEN N'OUTPUT'
                    WHEN N'@StatsSucceededOut'
                    THEN N'OUTPUT'
                    WHEN N'@StatsFailedOut'
                    THEN N'OUTPUT'
                    WHEN N'@StatsRemainingOut'
                    THEN N'OUTPUT'
                    WHEN N'@DurationSecondsOut'
                    THEN N'OUTPUT'
                    ELSE N''
                END
        FROM sys.parameters AS ap
        JOIN sys.types AS t
          ON t.user_type_id = ap.user_type_id
        WHERE ap.object_id = @@PROCID
        ORDER BY
            ap.parameter_id;

        /*
        Example usage
        */
        SELECT
            example_name =
                example_data.example_name,
            example_description =
                example_data.example_description,
            example_code =
                example_data.example_code
        FROM
        (
            VALUES
                (
                    N'Direct Mode - Single Stat',
                    N'Update a specific statistic by name',
                    N'EXECUTE dbo.sp_StatUpdate @Statistics = N''dbo.Customers._WA_Sys_00000001_ABC123'';'
                ),
                (
                    N'Direct Mode - From Table',
                    N'Update stats from a priority queue table',
                    N'EXECUTE dbo.sp_StatUpdate @StatisticsFromTable = N''dbo.StatsPriorityQueue'', @StatisticsSample = 100;'
                ),
                (
                    N'Discovery - NORECOMPUTE Only',
                    N'Find and update all NORECOMPUTE stats',
                    N'EXECUTE dbo.sp_StatUpdate @TargetNorecompute = N''Y'', @ModificationThreshold = 10000;'
                ),
                (
                    N'Discovery - All Stale Stats',
                    N'Update all stats stale > 30 days',
                    N'EXECUTE dbo.sp_StatUpdate @TargetNorecompute = N''BOTH'', @DaysStaleThreshold = 30;'
                ),
                (
                    N'Discovery - Large Tables Only',
                    N'Only tables with 1GB+ data',
                    N'EXECUTE dbo.sp_StatUpdate @MinPageCount = 125000, @TimeLimit = 7200;'
                ),
                (
                    N'Parallel Mode via SQL Agent',
                    N'Create 2-3 Agent jobs with identical command, schedule simultaneously. Work coordinated via dbo.QueueStatistic.',
                    N'EXECUTE dbo.sp_StatUpdate @Databases = N''Production'', @StatsInParallel = N''Y'', @TimeLimit = 3600, @LockTimeout = 60;'
                ),
                (
                    N'Dry Run',
                    N'Show what would be updated without executing',
                    N'EXECUTE dbo.sp_StatUpdate @Execute = N''N'', @Debug = 1;'
                ),
                /* #213: Advanced examples */
                (
                    N'Query Store Prioritization',
                    N'Update stats used by slowest queries first (by CPU, last 24h)',
                    N'EXECUTE dbo.sp_StatUpdate @Databases = N''Production'', @QueryStorePriority = N''Y'', @QueryStoreMetric = N''CPU'', @QueryStoreMinExecutions = 100, @QueryStoreRecentHours = 24, @TimeLimit = 3600;'
                ),
                (
                    N'NORECOMPUTE Stats Only',
                    N'Update only statistics with NORECOMPUTE flag (frozen stats needing manual refresh)',
                    N'EXECUTE dbo.sp_StatUpdate @Databases = N''Production'', @TargetNorecompute = N''Y'', @TimeLimit = 1800;'
                ),
                (
                    N'Filtered Stats Drift Detection',
                    N'Prioritize filtered statistics where selectivity has drifted significantly',
                    N'EXECUTE dbo.sp_StatUpdate @Databases = N''Production'', @FilteredStatsMode = N''PRIORITY'', @FilteredStatsStaleFactor = 1.5, @TimeLimit = 7200;'
                ),
                (
                    N'Adaptive Sampling for Large Tables',
                    N'Cap sample rate for stats that historically run >4 hours',
                    N'EXECUTE dbo.sp_StatUpdate @Databases = N''Production'', @LongRunningThresholdMinutes = 240, @LongRunningSamplePercent = 5, @TimeLimit = 7200;'
                ),
                (
                    N'Incremental Stats (Partitioned Tables)',
                    N'Update only modified partitions on partitioned tables with incremental stats',
                    N'EXECUTE dbo.sp_StatUpdate @Databases = N''Production'', @UpdateIncremental = 1, @SortOrder = N''MODIFICATION_COUNTER'', @TimeLimit = 3600;'
                )
        ) AS example_data
        (
            example_name,
            example_description,
            example_code
        );

        /*
        Modes explanation
        */
        SELECT
            mode_name =
                mode_data.mode_name,
            mode_description =
                mode_data.mode_description,
            mode_when_to_use =
                mode_data.mode_when_to_use
        FROM
        (
            VALUES
                (
                    N'DIRECT_TABLE',
                    N'Reads stats from @StatisticsFromTable parameter',
                    N'When you have a pre-populated queue (e.g., QueryStore priority queue)'
                ),
                (
                    N'DIRECT_STRING',
                    N'Parses stats from @Statistics comma-separated string',
                    N'When you know exactly which stats need updating'
                ),
                (
                    N'DISCOVERY',
                    N'Queries DMVs to find qualifying stats based on thresholds',
                    N'Nightly maintenance, catch-up runs, finding orphaned stats'
                )
        ) AS mode_data
        (
            mode_name,
            mode_description,
            mode_when_to_use
        );

        /*
        Operational notes (v2.8) — addresses documentation issues #9, #11, #12, #15, #16, #36, #46, #57, #62, #63
        */
        SELECT
            topic = note_data.topic,
            note = note_data.note
        FROM
        (
            VALUES
                /* #15: Essential parameters for new users */
                (N'Quick Start',
                 N'Essential parameters: @Databases, @Preset (or @TimeLimit + @ModificationThreshold), @LogToTable, @Execute. Start with: EXEC sp_StatUpdate @Preset=N''NIGHTLY_MAINTENANCE'', @Databases=N''USER_DATABASES'';'),
                /* #16: Zero-dependency quick start */
                (N'Zero Dependencies',
                 N'Run without Ola Hallengren tables: EXEC sp_StatUpdate @LogToTable=N''N'', @Execute=N''N''; (dry run, no CommandLog needed). Add @Execute=N''Y'' when ready.'),
                /* #46: Consultant workflow */
                (N'Consultant Workflow',
                 N'Step 1: EXEC sp_StatUpdate @Execute=N''N'', @Debug=1; (diagnose). Step 2: Review output. Step 3: EXEC sp_StatUpdate @Preset=N''NIGHTLY_MAINTENANCE'', @Databases=N''USER_DATABASES'';'),
                /* #57: modification_counter semantics */
                (N'@ModificationThreshold',
                 N'modification_counter reflects TOTAL table modifications (INSERT/UPDATE/DELETE), NOT per-column or per-filter changes. For filtered statistics, the counter may be high even when the filter predicate''s data distribution hasn''t changed.'),
                /* #62: RCSI and modification_counter */
                (N'RCSI Environments',
                 N'READ_COMMITTED_SNAPSHOT does not affect modification_counter (DML-driven only, not read-path). RCSI generates version store overhead in tempdb during stats updates — monitor tempdb if @MinTempdbFreeMB is not set.'),
                /* #63: Sch-S locking */
                (N'Locking Behavior',
                 N'UPDATE STATISTICS acquires Sch-M (schema modification) locks. sys.dm_db_stats_histogram uses Sch-S which can queue behind Sch-M. Avoid overlapping stats maintenance with schema changes. Use @LockTimeout to bound wait time.'),
                /* #9: Scheduling guidance */
                (N'Scheduling',
                 N'Avoid overlapping with index maintenance (both acquire Sch-M). On AG primaries, Sch-M locks replay to secondaries via redo thread — use @MaxAGRedoQueueMB to protect secondaries. Run during off-peak concurrency windows.'),
                /* #12, #212: Parallel mode — Agent job setup */
                (N'Parallel Mode',
                 N'Production setup: create 2-3 identical SQL Agent jobs, schedule to start simultaneously. All run the same sp_StatUpdate with @StatsInParallel=Y — work distribution is automatic via dbo.QueueStatistic. First worker populates queue; others join and claim work. Dead workers detected via @DeadWorkerTimeoutMinutes (default 15). Use @MaxWorkers to cap concurrent workers (prevents blocking storms). Start with 2-3 workers and @LockTimeout=30-60s. Monitor: SELECT COUNT(*) FROM dbo.QueueStatistic WHERE TableEndTime IS NOT NULL;'),
                /* #36: Edition-specific behavior, #197: SQL 2025 compatibility */
                (N'Edition Notes',
                 N'MAXDOP: works on all editions (SQL 2016 SP2+). PERSIST_SAMPLE_PERCENT: all editions (SQL 2016 SP1 CU4+). Incremental stats: requires partitioning (Enterprise or Standard SP1+). Parallel stats: all editions. SQL 2025 (v17): fully compatible — all features enabled via forward-compatible >= version checks.'),
                /* #11: PERSIST_SAMPLE_PERCENT CU history */
                (N'PERSIST_SAMPLE_PERCENT',
                 N'Available since SQL 2016 SP1 CU4 (build 4446+). Early CUs had bugs — ensure fleet CU consistency. RESAMPLE ignores persisted percent (uses previously computed rate). To audit: SELECT name, has_persisted_sample FROM sys.stats. To remove: UPDATE STATISTICS WITH SAMPLE (without PERSIST).'),
                /* Azure MI vs DB */
                (N'Azure SQL',
                 N'EngineEdition 5 = Azure SQL DB (no Resource Governor, no incremental stats, DTU model). EngineEdition 8 = Azure SQL MI (most on-prem features supported, vCore model). The procedure auto-detects and adjusts warnings.'),
                /* #158: Cross-database boundary */
                (N'Multi-Database Mode',
                 N'UPDATE STATISTICS runs in each database''s own context (USE [db]). It cannot cross database boundaries. Multi-database mode (@Databases) updates each database''s own statistics independently. Cross-database queries use statistics from each referenced database.'),
                /* #160: @Databases=NULL vs ALL_DATABASES */
                (N'@Databases=NULL',
                 N'@Databases=NULL targets the current database context only (equivalent to DB_NAME()). Use @Databases=N''ALL_DATABASES'' for all user+system databases, or @Databases=N''USER_DATABASES'' for user databases only. @Databases=N''ALL'' is not valid — use ALL_DATABASES.'),
                /* #172: @IncludeIndexedViews + @TargetNorecompute interaction */
                (N'Indexed View Stats',
                 N'@IncludeIndexedViews=Y with @TargetNorecompute=N skips indexed view statistics that have NORECOMPUTE set — often the most maintenance-critical ones (set NORECOMPUTE to prevent auto-update interference). Use @TargetNorecompute=BOTH to include all indexed view stats.'),
                /* #177: @MinPageCount clarification */
                (N'@MinPageCount Scope',
                 N'@MinPageCount uses used_page_count from sys.dm_db_partition_stats, which includes data pages, LOB pages, and row-overflow pages. Tables with large LOB/XML columns may have higher page counts than their row data alone suggests. 125000 pages ≈ 1 GB for standard 8KB pages.'),
                /* #180: Indexed views and NOEXPAND */
                (N'Indexed Views + NOEXPAND',
                 N'On Standard Edition, indexed view statistics are only used by the optimizer when the view is referenced with the NOEXPAND hint. UPDATE STATISTICS on the view is valid, but the optimizer may ignore the stats without NOEXPAND. Enterprise Edition uses indexed view stats automatically.'),
                /* #193: @ReturnDetailedResults vs CommandLog */
                (N'Output Channels',
                 N'@ReturnDetailedResults and CommandLog are independent output channels. Skipped stats (TOCTOU, @MaxSecondsPerStat) appear in @ReturnDetailedResults but not CommandLog unless @LogSkippedToCommandLog=Y. CommandLog requires @LogToTable=Y. Both channels report the same succeeded/failed stats.'),
                /* #162: modification_counter limitations */
                (N'modification_counter Limitations',
                 N'modification_counter can be reset by DBCC UPDATEUSAGE, certain restore operations, and detach/attach cycles. Columnstore bulk loads may undercount modifications. DBCC SHOW_STATISTICS shows histogram-level staleness but modification_counter is the only programmatic signal. If modification_counter is unreliable, use @SortOrder=N''DAYS_STALE'' or @DaysStaleThreshold to qualify stats by age instead.'),
                /* #143: Ascending key detection */
                (N'Ascending Key Stats',
                 N'Ascending key columns (identity, datetime inserts) accumulate rows beyond the histogram''s highest RANGE_HI_KEY, causing cardinality underestimates for recent values. Trace flags 2389/2390 (legacy CE) and 4139 (new CE quick stats) can help. Use @DaysStaleThreshold with a low value (e.g. 1-2 days) to catch ascending key stats that have few modifications but stale histograms. @SortOrder=N''DAYS_STALE'' prioritizes the oldest stats first.'),
                /* #156: Compressed tables and @MinPageCount */
                (N'Compressed Tables',
                 N'@MinPageCount uses used_page_count from sys.dm_db_partition_stats which reflects compressed (on-disk) page counts, not the uncompressed data size. ROW or PAGE compressed tables may appear smaller than their actual data volume. A table with 500K rows might show 100 pages compressed vs 5000 uncompressed. If using @MinPageCount to skip small tables, compressed tables may be incorrectly skipped.'),
                /* #206: Filter combination logic */
                (N'Filter Combination (AND Logic)',
                 N'Discovery filters (@Tables, @ExcludeTables, @ExcludeStatistics, @TargetNorecompute, @FilteredStatsMode) are combined with AND logic. Example: @Tables=N''dbo.Orders'', @ExcludeStatistics=N''_WA_Sys%%'' processes only non-auto-created stats on dbo.Orders. To process "all stats on table A PLUS specific stats on table B", run two separate invocations. Note: @Statistics triggers DIRECT mode (skips discovery entirely) and cannot be combined with @Tables.')
        ) AS note_data
        (
            topic,
            note
        );

        RETURN;
    END;

    /*
    ============================================================================
    @Help = 'SAMPLING' topic (v2.3)
    ============================================================================
    */
    IF @Help = N'SAMPLING'
    BEGIN
        SELECT
            priority =
                p.priority_num,
            name =
                p.priority_name,
            when_applied =
                p.when_applied,
            details =
                p.details
        FROM
        (
            VALUES
                (1, N'@StatisticsSample (explicit)', N'When @StatisticsSample is not NULL',
                 N'All statistics use this sample rate. Overrides all other sampling. Example: @StatisticsSample = 30 forces 30% on every stat.'),
                (2, N'Adaptive sampling (history-based)', N'When @LongRunningThresholdMinutes IS NOT NULL AND CommandLog history exists',
                 N'Stats that previously exceeded the threshold get a reduced sample rate. First run finds nothing — history is needed. Falls back to auto-sample if no history.'),
                (3, N'@Preset WAREHOUSE_AGGRESSIVE', N'When @Preset = ''WAREHOUSE_AGGRESSIVE''',
                 N'Forces FULLSCAN (100% sample) on all stats. Overrides adaptive sampling. Best for data warehouses where accuracy trumps speed.'),
                (4, N'SQL Server auto-sample (default)', N'When none of the above apply',
                 N'SQL Server selects the sample rate automatically based on table size. Small tables often get 100%; large tables may get 1-5%. This is standard UPDATE STATISTICS behavior.')
        ) AS p (priority_num, priority_name, when_applied, details)
        ORDER BY
            priority;

        SELECT
            note = N'@PersistSamplePercent = Y persists the explicit sample rate in the stats header (SQL 2016+ / TF 2371). Future auto-updates use the persisted rate instead of SQL Server auto-sample.'
        UNION ALL SELECT N'Available @Help topics: 1 (or Y) = full parameter help, SAMPLING = this topic, TRENDING = CommandLog trend queries.';

        RETURN;
    END;

    /*
    ============================================================================
    @Help = 'TRENDING' topic (#243)
    Canned CommandLog queries for cross-run stat trending
    ============================================================================
    */
    IF @Help = N'TRENDING'
    BEGIN
        SELECT
            query_name = q.query_name,
            description = q.description,
            sql_text = q.sql_text
        FROM
        (
            VALUES
                (N'Per-Stat Cross-Run Trend',
                 N'P95 duration and avg modifications at update time for each statistic across recent runs',
                 N'SELECT
    cl.DatabaseName,
    cl.SchemaName,
    cl.ObjectName AS TableName,
    cl.StatisticsName,
    COUNT(*) AS RunCount,
    CONVERT(decimal(10,1), AVG(DATEDIFF(MILLISECOND, cl.StartTime, cl.EndTime) / 1000.0)) AS AvgDurationSec,
    CONVERT(decimal(10,1),
        PERCENTILE_CONT(0.95) WITHIN GROUP (ORDER BY DATEDIFF(MILLISECOND, cl.StartTime, cl.EndTime) / 1000.0)
        OVER (PARTITION BY cl.DatabaseName, cl.SchemaName, cl.ObjectName, cl.StatisticsName)
    ) AS P95DurationSec,
    AVG(cl.ExtendedInfo.value(''(/ExtendedInfo/ModificationCounter)[1]'', ''bigint'')) AS AvgModsAtUpdate
FROM dbo.CommandLog AS cl
WHERE cl.CommandType = N''UPDATE_STATISTICS''
  AND cl.EndTime IS NOT NULL
  AND cl.ErrorNumber IS NULL
  AND cl.StartTime >= DATEADD(DAY, -30, SYSDATETIME())
GROUP BY cl.DatabaseName, cl.SchemaName, cl.ObjectName, cl.StatisticsName
ORDER BY AvgDurationSec DESC;'),

                (N'Per-Database Run Summary',
                 N'Aggregate run health per database: completion rate, avg stats/run, failure rate',
                 N'SELECT
    cl.DatabaseName,
    COUNT(DISTINCT cl.ExtendedInfo.value(''(/ExtendedInfo/RunLabel)[1]'', ''nvarchar(100)'')) AS DistinctRuns,
    COUNT(*) AS TotalStatUpdates,
    SUM(CASE WHEN cl.ErrorNumber IS NULL THEN 1 ELSE 0 END) AS Succeeded,
    SUM(CASE WHEN cl.ErrorNumber IS NOT NULL THEN 1 ELSE 0 END) AS Failed,
    CONVERT(decimal(5,1), SUM(CASE WHEN cl.ErrorNumber IS NULL THEN 1 ELSE 0 END) * 100.0 / NULLIF(COUNT(*), 0)) AS SuccessPct,
    CONVERT(decimal(10,1), AVG(DATEDIFF(MILLISECOND, cl.StartTime, cl.EndTime) / 1000.0)) AS AvgDurationSec
FROM dbo.CommandLog AS cl
WHERE cl.CommandType = N''UPDATE_STATISTICS''
  AND cl.EndTime IS NOT NULL
  AND cl.StartTime >= DATEADD(DAY, -30, SYSDATETIME())
GROUP BY cl.DatabaseName
ORDER BY TotalStatUpdates DESC;')
        ) AS q (query_name, description, sql_text);

        SELECT
            note = N'Copy and run these queries against the database containing your CommandLog table. Adjust the DATEADD(-30) window as needed.'
        UNION ALL SELECT N'Available @Help topics: 1 (or Y) = full parameter help, SAMPLING = sampling priority order, TRENDING = this topic.';

        RETURN;
    END;
    /*#endregion 03-HELP */

    /*#region 04-REENTRANCE: Re-entrancy guard (sp_getapplock) */
    /*
    ============================================================================
    RE-ENTRANCY GUARD (sp_HeapDoctor pattern)
    Prevents concurrent non-parallel runs from corrupting shared state
    (orphan cleanup, progress tables, CommandLog bracketing).
    Parallel mode workers skip this guard - they coordinate via queue tables.
    ============================================================================
    */
    IF @StatsInParallel = N'N'
    BEGIN
        DECLARE @lock_result int;
        EXEC @lock_result = sp_getapplock
            @Resource = N'sp_StatUpdate',
            @LockMode = N'Exclusive',
            @LockTimeout = 0,
            @LockOwner = N'Session';

        IF @lock_result < 0
        BEGIN
            RAISERROR(N'Another instance of sp_StatUpdate is already running (non-parallel mode). Use @StatsInParallel=''Y'' for concurrent execution.', 16, 1);
            RETURN;
        END;
    END;
    /*#endregion 04-REENTRANCE */

    /*#region 05-VARIABLES: Declarations, env detection, temp tables */
    /*
    ============================================================================
    VARIABLE DECLARATIONS
    ============================================================================
    */
    DECLARE
        @start_time datetime2(7) = SYSDATETIME(),
        @empty_line nvarchar(max) = N'',
        @error_number integer = 0,
        @return_code integer = 0,
        /*
        Capture original LOCK_TIMEOUT to restore after stat updates (P1 #23 v1.9)
        @@LOCK_TIMEOUT returns -1 for infinite wait, or timeout in milliseconds
        */
        @original_lock_timeout integer = @@LOCK_TIMEOUT;

    /*
    SQL Server version detection
    Major version: 13 = 2016, 14 = 2017, 15 = 2019, 16 = 2022, 17 = 2025
    Build number used for feature detection (e.g., PERSIST_SAMPLE_PERCENT, MAXDOP in UPDATE STATISTICS)
    Future versions (>= 17) inherit SQL 2022 feature set — all >= comparisons forward-compatible.
    */
    DECLARE
        @sql_version numeric(18, 10) =
            CONVERT
            (
                numeric(18, 10),
                LEFT
                (
                    CONVERT(nvarchar(128), SERVERPROPERTY(N'ProductVersion')),
                    CHARINDEX
                    (
                        N'.',
                        CONVERT(nvarchar(128), SERVERPROPERTY(N'ProductVersion'))
                    ) - 1
                ) +
                N'.' +
                REPLACE
                (
                    RIGHT
                    (
                        CONVERT(nvarchar(128), SERVERPROPERTY(N'ProductVersion')),
                        LEN(CONVERT(nvarchar(128), SERVERPROPERTY(N'ProductVersion'))) -
                        CHARINDEX
                        (
                            N'.',
                            CONVERT(nvarchar(128), SERVERPROPERTY(N'ProductVersion'))
                        )
                    ),
                    N'.',
                    N''
                )
            ),
        @sql_major_version integer =
            CONVERT
            (
                integer,
                LEFT
                (
                    CONVERT(nvarchar(128), SERVERPROPERTY(N'ProductVersion')),
                    CHARINDEX
                    (
                        N'.',
                        CONVERT(nvarchar(128), SERVERPROPERTY(N'ProductVersion'))
                    ) - 1
                )
            ),
        @sql_build_number integer =
            CONVERT
            (
                integer,
                PARSENAME(CONVERT(nvarchar(128), SERVERPROPERTY(N'ProductVersion')), 2)
            ),
        /*
        Feature availability flags based on SQL Server version/build:
        - PERSIST_SAMPLE_PERCENT: SQL 2016 SP1 CU4+ (build 4446+) or SQL 2017+
        - MAXDOP in UPDATE STATISTICS: SQL 2016 SP2+ (build 5026+) or SQL 2017 CU3+ (build 3015+)
        */
        @supports_persist_sample bit = 0,
        @supports_maxdop_stats bit = 0,
        /* SQL 2022+ feature detection (includes SQL 2025/v17+) */
        @supports_auto_drop bit = 0;

    /* Set AUTO_DROP support flag (SQL 2022+ / v16+) */
    IF @sql_major_version >= 16
        SET @supports_auto_drop = 1;

    /*
    Phase 1 Environment Detection (v2.0)
    Trace flags affecting statistics behavior - detected once at startup.
    */
    DECLARE
        @trace_flags table
        (
            TraceFlag int NOT NULL,
            Status bit NOT NULL,
            Global bit NOT NULL,
            Session bit NOT NULL
        );

    DECLARE
        @tf_2371_active bit = 0,    /* Dynamic thresholds (built-in for SQL 2016+ CL 130+) */
        @tf_2389_active bit = 0,    /* Ascending key detection (legacy) */
        @tf_2390_active bit = 0,    /* Descending key detection (legacy) */
        @tf_4139_active bit = 0,    /* Universal histogram amendment (modern) */
        @tf_9481_active bit = 0,    /* Force legacy CE */
        @tf_warnings nvarchar(max) = N'';

    /* Query active trace flags */
    INSERT INTO @trace_flags (TraceFlag, Status, Global, Session)
    EXEC (N'DBCC TRACESTATUS(-1) WITH NO_INFOMSGS');

    /* Check for statistics-relevant trace flags */
    SELECT
        @tf_2371_active = MAX(CASE WHEN TraceFlag = 2371 AND Status = 1 THEN 1 ELSE 0 END),
        @tf_2389_active = MAX(CASE WHEN TraceFlag = 2389 AND Status = 1 THEN 1 ELSE 0 END),
        @tf_2390_active = MAX(CASE WHEN TraceFlag = 2390 AND Status = 1 THEN 1 ELSE 0 END),
        @tf_4139_active = MAX(CASE WHEN TraceFlag = 4139 AND Status = 1 THEN 1 ELSE 0 END),
        @tf_9481_active = MAX(CASE WHEN TraceFlag = 9481 AND Status = 1 THEN 1 ELSE 0 END)
    FROM @trace_flags;

    /* Build trace flag warnings for debug output */
    IF @tf_2371_active = 1 AND @sql_major_version >= 13
        SET @tf_warnings = @tf_warnings + N'TF 2371 unnecessary (built-in for SQL 2016+ CL 130+); ';
    IF @tf_2389_active = 1 OR @tf_2390_active = 1
        SET @tf_warnings = @tf_warnings + N'TF 2389/2390 are legacy ascending key flags - consider TF 4139 instead; ';
    IF @tf_4139_active = 1
        SET @tf_warnings = @tf_warnings + N'TF 4139 active (histogram amendment for ascending keys); ';
    IF @tf_9481_active = 1
        SET @tf_warnings = @tf_warnings + N'TF 9481 forces legacy CE 70 globally - consider db-scoped config instead; ';

    /*
    Error collection table (show all errors at once)
    */
    DECLARE
        @errors table
        (
            id integer IDENTITY(1, 1) PRIMARY KEY,
            error_message nvarchar(max) NOT NULL,
            error_severity integer NOT NULL
        );

    /*
    Selected databases tables (Ola Hallengren pattern)
    Supports: SYSTEM_DATABASES, USER_DATABASES, ALL_DATABASES,
              AVAILABILITY_GROUP_DATABASES, wildcards (%), exclusions (-)
    */
    DECLARE
        @SelectedDatabases table
        (
            DatabaseItem nvarchar(max),
            DatabaseType char(1),        /* S=System, U=User, NULL=Any */
            AvailabilityGroup bit,       /* 1=AG databases only */
            StartPosition integer,
            Selected bit                 /* 1=Include, 0=Exclude */
        );

    DECLARE
        @tmpDatabases table
        (
            ID integer IDENTITY(1, 1) PRIMARY KEY,
            DatabaseName sysname NOT NULL,
            DatabaseType char(1),        /* S=System, U=User */
            AvailabilityGroup bit,
            Selected bit NOT NULL DEFAULT 0,
            Completed bit NOT NULL DEFAULT 0
        );

    DECLARE
        @CurrentDatabaseID integer = NULL,
        @CurrentDatabaseName sysname = NULL,
        @database_count integer = 0;

    /*
    Current item variables
    */
    DECLARE
        @current_database sysname = NULL,
        @current_schema_name sysname = NULL,
        @current_table_name sysname = NULL,
        @current_stat_name sysname = NULL,
        @current_object_id integer = NULL,
        @current_stats_id integer = NULL,
        @current_no_recompute bit = NULL,
        @current_is_incremental bit = NULL,
        @current_is_memory_optimized bit = NULL,
        @current_is_heap bit = NULL,
        @current_auto_created bit = NULL,
        @current_modification_counter bigint = NULL,
        @current_row_count bigint = NULL,
        @current_days_stale integer = NULL,
        @current_page_count bigint = NULL,
        @current_persisted_sample_percent float = NULL,
        @absolute_sampled_rows bigint = NULL, /*P1c: computed actual sampled rows from @current_row_count * @current_persisted_sample_percent*/
        @p246_pct int = NULL,
        @p246_msg nvarchar(500) = NULL,
        @current_histogram_steps int = NULL,
        @current_partition_number integer = NULL,
        @current_forwarded_records bigint = NULL,
        /* Replication and temporal table awareness */
        @current_is_published bit = NULL,
        @current_is_tracked_by_cdc bit = NULL,
        @current_temporal_type tinyint = NULL,
        /* Filtered statistics metadata */
        @current_has_filter bit = NULL,
        @current_filter_definition nvarchar(max) = NULL,
        @current_unfiltered_rows bigint = NULL,
        @current_filtered_drift_ratio float = NULL,
        /* Query Store priority metadata */
        @current_qs_plan_count integer = NULL,
        @current_qs_total_executions bigint = NULL,
        @current_qs_total_cpu_ms bigint = NULL,
        @current_qs_total_duration_ms bigint = NULL,
        @current_qs_total_logical_reads bigint = NULL,
        @current_qs_last_execution datetime2(3) = NULL,
        @current_qs_priority_boost bigint = NULL;

    /*
    TOCTOU check variables (verify stat still exists before execution)
    */
    DECLARE
        @toctou_sql nvarchar(500) = N'',
        @toctou_exists int = 0;

    /*
    Command building
    */
    DECLARE
        @current_command nvarchar(max) = N'',
        @current_command_type nvarchar(60) = N'UPDATE_STATISTICS',
        @current_start_time datetime2(7) = NULL,
        @current_end_time datetime2(7) = NULL,
        @current_error_number integer = NULL,
        @current_error_message nvarchar(max) = NULL,
        @current_extended_info xml = NULL,
        @current_commandlog_id integer = NULL;

    /*
    Output message helpers
    */
    DECLARE
        @norecompute_display nvarchar(20) = N'',
        @duration_ms integer = 0,
        @progress_msg nvarchar(500) = N'',
        @persisted_pct_msg integer = 0,
        @iteration_time datetime2(7) = NULL, /*Captured once per loop iteration for consistent timing*/
        @log_error_msg nvarchar(4000) = NULL; /*For TRY/CATCH - truncate at assignment to leave room for prefix*/

    /* P3e (v2.4): ETR (Estimated Time Remaining) tracking variables */
    DECLARE
        @etr_total_ms bigint = 0,          /* Running total ms across all completed stats */
        @etr_completed int = 0,            /* Count of stats completed (successful executions) */
        @etr_suffix nvarchar(50) = N'',    /* ETR display suffix appended to Complete message */
        @etr_avg_ms bigint = 0,            /* Average ms per stat for current run */
        @etr_remaining_count int = 0,      /* Stats remaining in queue */
        @etr_ms bigint = 0,               /* Estimated remaining ms */
        @etr_display nvarchar(20) = N'';   /* Human-readable ETR string (~Xh Ym, ~Xm, ~Xs) */

    /*
    Run identification for tracking completion
    */
    DECLARE
        @run_label nvarchar(100) = N'',
        @stop_reason nvarchar(50) = NULL,
        @commandlog_exists bit = CASE WHEN OBJECT_ID(N'dbo.CommandLog', N'U') IS NOT NULL THEN 1 ELSE 0 END;

    /*
    Counters
    */
    DECLARE
        @stats_processed integer = 0,
        @stats_succeeded integer = 0,
        @stats_failed integer = 0,
        @stats_toctou integer = 0,
        @stats_skipped integer = 0,
        @consecutive_failures integer = 0,
        @warnings nvarchar(max) = N''; /* Collected warnings for @WarningsOut OUTPUT */

    /*
    Queue-based parallel processing variables
    */
    DECLARE
        @queue_id integer = NULL,
        @queue_start_time datetime2(7) = NULL,
        @parameters_string nvarchar(max) = N'',
        @claimed_work bit = 0,
        /*
        Currently claimed table (parallel mode only).
        Worker claims one table at a time, processes all its stats, then claims next.
        */
        @claimed_table_database sysname = NULL,
        @claimed_table_schema sysname = NULL,
        @claimed_table_name sysname = NULL,
        @claimed_table_object_id integer = NULL,
        @claimed_table_stats_updated integer = 0,
        @claimed_table_stats_failed integer = 0,
        @claimed_table_stats_skipped integer = 0;

    /*
    Availability Group variables
    */
    DECLARE
        @is_ag_secondary bit = 0,
        @ag_role_desc nvarchar(60) = NULL;

    /*
    AG redo queue monitoring variables (v2.7, #18)
    */
    DECLARE
        @ag_redo_queue_mb bigint = NULL,
        @ag_wait_start datetime2(7) = NULL,
        @ag_is_primary bit = 0,
        @ag_redo_initial_mb bigint = NULL,
        @ag_wait_msg nvarchar(500) = N'',
        @ag_recovered_msg nvarchar(500) = N'';

    /*
    Tempdb pressure monitoring variables (v2.7, #34)
    */
    DECLARE
        @tempdb_free_mb bigint = NULL,
        @tempdb_msg nvarchar(500) = N'';

    /*
    Long-running stats table (for adaptive sampling)
    Stores stats that historically took longer than @LongRunningThresholdMinutes
    */
    DECLARE @long_running_stats TABLE
    (
        database_name sysname NOT NULL,
        schema_name sysname NOT NULL,
        table_name sysname NOT NULL,
        stat_name sysname NOT NULL,
        max_duration_minutes int NOT NULL,
        last_occurrence datetime2(7) NOT NULL,
        occurrence_count int NOT NULL DEFAULT 1,
        PRIMARY KEY NONCLUSTERED (database_name, schema_name, table_name, stat_name)
    );

    /*
    ============================================================================
    TEMP TABLE FOR STATS TO PROCESS
    ============================================================================
    */
    CREATE TABLE
        #stats_to_process
    (
        id integer IDENTITY(1, 1) PRIMARY KEY,
        database_name sysname NOT NULL,
        schema_name sysname NOT NULL,
        table_name sysname NOT NULL,
        stat_name sysname NOT NULL,
        object_id integer NOT NULL,
        stats_id integer NOT NULL,
        no_recompute bit NOT NULL DEFAULT 0,
        is_incremental bit NOT NULL DEFAULT 0,
        is_memory_optimized bit NOT NULL DEFAULT 0,
        is_heap bit NOT NULL DEFAULT 0,
        auto_created bit NOT NULL DEFAULT 0,
        /* Table metadata for replication/CDC/temporal awareness */
        is_published bit NOT NULL DEFAULT 0, /*transactional replication*/
        is_tracked_by_cdc bit NOT NULL DEFAULT 0, /*Change Data Capture*/
        temporal_type tinyint NOT NULL DEFAULT 0, /*0=none, 1=history, 2=system-versioned*/
        modification_counter bigint NOT NULL DEFAULT 0,
        row_count bigint NOT NULL DEFAULT 0,
        days_stale integer NOT NULL DEFAULT 0,
        page_count bigint NOT NULL DEFAULT 0,
        partition_number integer NULL,
        persisted_sample_percent float NULL, /*existing persisted sample (warn if overriding)*/
        histogram_steps int NULL, /*number of histogram steps for diagnostic insight*/
        /* Filtered statistics metadata */
        has_filter bit NOT NULL DEFAULT 0,
        filter_definition nvarchar(max) NULL,
        unfiltered_rows bigint NULL, /*total rows in table, vs rows matching filter*/
        filtered_drift_ratio AS /*computed: unfiltered_rows / NULLIF(row_count, 0) - measures selectivity drift*/
            CASE WHEN row_count > 0 AND unfiltered_rows IS NOT NULL
                 THEN CONVERT(float, unfiltered_rows) / row_count
                 ELSE NULL
            END,
        /* Query Store priority metadata */
        qs_plan_count integer NULL, /*distinct plans referencing this stat*/
        qs_total_executions bigint NULL, /*total executions of plans using stat*/
        qs_total_cpu_ms bigint NULL, /*total CPU time in ms (avg_cpu_time * count_executions / 1000)*/
        qs_total_duration_ms bigint NULL, /*total elapsed time in ms*/
        qs_total_logical_reads bigint NULL, /*total logical I/O reads*/
        qs_last_execution datetime2(3) NULL, /*most recent plan execution*/
        qs_priority_boost bigint NOT NULL DEFAULT 0, /*calculated boost for QS stats*/
        priority integer NOT NULL DEFAULT 0,
        /* Join pattern grouping (v1.9) - stats in same join group are updated together */
        join_group_id integer NULL, /*NULL = ungrouped, same ID = update together to avoid optimization cliffs*/
        processed bit NOT NULL DEFAULT 0
    );

    /*
    Index for efficient "get next unprocessed stat" query pattern:
    WHERE processed = 0 ORDER BY priority
    */
    CREATE NONCLUSTERED INDEX
        IX_stats_to_process_processed_priority
    ON #stats_to_process
        (processed, priority)
    INCLUDE
        (database_name, schema_name, table_name, stat_name);
    /*#endregion 05-VARIABLES */

    /*#region 06-GUARDS: Core checks, @@TRANCOUNT, SET enforcement */
    /*
    ============================================================================
    CORE REQUIREMENTS CHECKS
    ============================================================================
    */

    /*
    Check SQL Server version (STRING_SPLIT requires 2016+)
    */
    IF @sql_version < 13
    BEGIN
        INSERT INTO
            @errors
        (
            error_message,
            error_severity
        )
        SELECT
            error_message =
                N'sp_StatUpdate requires SQL Server 2016 or later (STRING_SPLIT dependency). Current version: ' +
                CONVERT(nvarchar(128), SERVERPROPERTY(N'ProductVersion')),
            error_severity = 16;
    END;

    /*
    Set feature availability flags based on SQL Server version/build
    Reference: Microsoft Tiger Toolbox usp_AdaptiveIndexDefrag version detection
    */
    SELECT
        @supports_persist_sample =
            CASE
                WHEN @sql_major_version >= 14 THEN 1                            /* SQL 2017+ */
                WHEN @sql_major_version = 13 AND @sql_build_number >= 4446 THEN 1 /* SQL 2016 SP1 CU4+ */
                ELSE 0
            END,
        @supports_maxdop_stats =
            CASE
                WHEN @sql_major_version >= 15 THEN 1                            /* SQL 2019+ */
                WHEN @sql_major_version = 14 AND @sql_build_number >= 3015 THEN 1 /* SQL 2017 CU3+ (14.0.3015.0, KB4041809) */
                WHEN @sql_major_version = 13 AND @sql_build_number >= 5026 THEN 1 /* SQL 2016 SP2 RTM+ (13.0.5026.0, KB4041809) — NOT SP1 */
                /* NOTE: SQL 2016 SP1 (13.0.4001) and below do NOT support MAXDOP in UPDATE STATISTICS.
                         The feature was first shipped in SQL 2016 SP2 RTM (build 13.0.5026.0).
                         KB4041809: https://support.microsoft.com/kb/4041809 */
                ELSE 0
            END;

    /*
    Check transaction count - RETURN immediately (UPDATE STATISTICS acquires Sch-M locks
    that escalate unpredictably inside caller's transaction; connection pool poison risk)
    */
    IF @@TRANCOUNT <> 0
    BEGIN
        RAISERROR(N'The transaction count is not 0. sp_StatUpdate must not be called within an open transaction.', 16, 1) WITH NOWAIT;
        SET @StopReasonOut = N'PARAMETER_ERROR';
        IF @StatsInParallel = N'N'
            EXEC sp_releaseapplock @Resource = N'sp_StatUpdate', @LockOwner = N'Session';
        RETURN 1;
    END;

    /*
    Enforce SET options required by UPDATE STATISTICS on indexed views / computed columns.
    Error 1934 fires when these are off (common via JDBC, linked servers, legacy ODBC).
    Proactively SET them here — values revert automatically when the proc returns.
    ANSI_NULLS is captured at proc CREATE time (preamble), so only ANSI_WARNINGS
    and ARITHABORT need runtime enforcement.
    */
    IF SESSIONPROPERTY(N'ANSI_WARNINGS') <> 1
    BEGIN
        SET ANSI_WARNINGS ON;
        RAISERROR(N'Note: SET ANSI_WARNINGS ON (was OFF, required for UPDATE STATISTICS)', 10, 1) WITH NOWAIT;
    END;

    IF SESSIONPROPERTY(N'ARITHABORT') <> 1
    BEGIN
        SET ARITHABORT ON;
        RAISERROR(N'Note: SET ARITHABORT ON (was OFF, required for UPDATE STATISTICS)', 10, 1) WITH NOWAIT;
    END;

    /*
    Check CommandLog exists if logging enabled
    */
    IF  @LogToTable = N'Y'
    AND NOT EXISTS
        (
            SELECT
                1
            FROM sys.objects AS o
            JOIN sys.schemas AS s
              ON s.schema_id = o.schema_id
            WHERE o.type = N'U'
            AND   s.name = N'dbo'
            AND   o.name = N'CommandLog'
        )
    BEGIN
        INSERT INTO
            @errors
        (
            error_message,
            error_severity
        )
        SELECT
            error_message =
                N'The table dbo.CommandLog does not exist. Set @LogToTable = N''N'' or create the table from https://ola.hallengren.com/scripts/CommandLog.sql',
            error_severity = 16;
    END;

    /*
    v2.3: Check CommandLog schema compatibility when logging is enabled.
    Non-blocking warning if expected columns are missing.
    Required columns: CommandType, DatabaseName, SchemaName, ObjectName, StatisticName, ExtendedInfo.
    */
    IF  @LogToTable = N'Y'
    AND @commandlog_exists = 1
    BEGIN
        DECLARE @commandlog_missing_cols nvarchar(max) = N'';
        IF NOT EXISTS (SELECT 1 FROM sys.columns WHERE object_id = OBJECT_ID(N'dbo.CommandLog') AND name = N'CommandType')
            SET @commandlog_missing_cols += N'CommandType, ';
        IF NOT EXISTS (SELECT 1 FROM sys.columns WHERE object_id = OBJECT_ID(N'dbo.CommandLog') AND name = N'DatabaseName')
            SET @commandlog_missing_cols += N'DatabaseName, ';
        IF NOT EXISTS (SELECT 1 FROM sys.columns WHERE object_id = OBJECT_ID(N'dbo.CommandLog') AND name = N'SchemaName')
            SET @commandlog_missing_cols += N'SchemaName, ';
        IF NOT EXISTS (SELECT 1 FROM sys.columns WHERE object_id = OBJECT_ID(N'dbo.CommandLog') AND name = N'ObjectName')
            SET @commandlog_missing_cols += N'ObjectName, ';
        IF NOT EXISTS (SELECT 1 FROM sys.columns WHERE object_id = OBJECT_ID(N'dbo.CommandLog') AND name = N'StatisticsName')
            SET @commandlog_missing_cols += N'StatisticsName, ';
        IF NOT EXISTS (SELECT 1 FROM sys.columns WHERE object_id = OBJECT_ID(N'dbo.CommandLog') AND name = N'ExtendedInfo')
            SET @commandlog_missing_cols += N'ExtendedInfo, ';

        IF LEN(@commandlog_missing_cols) > 0
        BEGIN
            SET @commandlog_missing_cols = LEFT(@commandlog_missing_cols, LEN(@commandlog_missing_cols) - 2); /* trim trailing ", " */
            DECLARE @commandlog_warn nvarchar(1000) =
                N'WARNING: dbo.CommandLog schema may be incompatible. Expected columns missing: '
                + @commandlog_missing_cols + N'. Logging may fail.';
            RAISERROR(@commandlog_warn, 10, 1) WITH NOWAIT;
        END;

        /*
        v2.5: CommandLog index advisory (#31).
        Large CommandLog tables (5M+ rows, common on busy instances running multiple maintenance
        jobs) cause full scans on @CleanupOrphanedRuns, @LongRunningThresholdMinutes, and progress
        queries. A nonclustered index leading on CommandType eliminates these scans.
        */
        IF NOT EXISTS
           (
               SELECT 1
               FROM sys.indexes AS i
               JOIN sys.index_columns AS ic ON ic.object_id = i.object_id AND ic.index_id = i.index_id
               JOIN sys.columns AS c ON c.object_id = ic.object_id AND c.column_id = ic.column_id
               WHERE i.object_id = OBJECT_ID(N'dbo.CommandLog')
               AND   i.type IN (1, 2) /* clustered or nonclustered */
               AND   c.name = N'CommandType'
               AND   ic.key_ordinal = 1
           )
        BEGIN
            /* #150: Build advisory DDL dynamically based on columns that actually exist in this schema */
            DECLARE
                @cmdlog_object_id int = OBJECT_ID(N'dbo.CommandLog'),
                @advisory_include nvarchar(500) = N'';

            SELECT @advisory_include = @advisory_include +
                CASE WHEN @advisory_include = N'' THEN N'' ELSE N', ' END + c.name
            FROM (VALUES
                (N'DatabaseName'), (N'SchemaName'), (N'ObjectName'),
                (N'StatisticsName'), (N'EndTime'), (N'ErrorNumber')
            ) AS cols(name)
            JOIN sys.columns AS c
              ON c.object_id = @cmdlog_object_id
             AND c.name = cols.name COLLATE DATABASE_DEFAULT;

            RAISERROR(N'ADVISORY: dbo.CommandLog has no index leading on CommandType. On large tables this causes full scans during orphan cleanup and adaptive sampling. Consider:', 10, 1) WITH NOWAIT;

            IF @advisory_include <> N''
                RAISERROR(N'  CREATE NONCLUSTERED INDEX IX_CommandLog_CommandType_StartTime ON dbo.CommandLog (CommandType, StartTime) INCLUDE (%s);', 10, 1, @advisory_include) WITH NOWAIT;
            ELSE
                RAISERROR(N'  CREATE NONCLUSTERED INDEX IX_CommandLog_CommandType_StartTime ON dbo.CommandLog (CommandType, StartTime);', 10, 1) WITH NOWAIT;
        END;
    END;

    /*
    Check Queue tables exist if parallel processing enabled
    */
    IF  @StatsInParallel = N'Y'
    AND NOT EXISTS
        (
            SELECT
                1
            FROM sys.objects AS o
            JOIN sys.schemas AS s
              ON s.schema_id = o.schema_id
            WHERE o.type = N'U'
            AND   s.name = N'dbo'
            AND   o.name = N'Queue'
        )
    BEGIN
        INSERT INTO
            @errors
        (
            error_message,
            error_severity
        )
        SELECT
            error_message =
                N'The table dbo.Queue does not exist. Download https://ola.hallengren.com/scripts/Queue.sql',
            error_severity = 16;
    END;

    /*
    Auto-create QueueStatistic table if it doesn't exist (requires dbo.Queue)
    */
    IF  @StatsInParallel = N'Y'
    AND NOT EXISTS
        (
            SELECT
                1
            FROM sys.objects AS o
            JOIN sys.schemas AS s
              ON s.schema_id = o.schema_id
            WHERE o.type = N'U'
            AND   s.name = N'dbo'
            AND   o.name = N'QueueStatistic'
        )
    AND EXISTS
        (
            SELECT
                1
            FROM sys.objects AS o
            JOIN sys.schemas AS s
              ON s.schema_id = o.schema_id
            WHERE o.type = N'U'
            AND   s.name = N'dbo'
            AND   o.name = N'Queue'
        )
    BEGIN
        RAISERROR(N'Creating dbo.QueueStatistic table for parallel processing...', 10, 1) WITH NOWAIT;

        CREATE TABLE dbo.QueueStatistic
        (
            QueueID integer NOT NULL,
            DatabaseName sysname NOT NULL,
            SchemaName sysname NOT NULL,
            ObjectName sysname NOT NULL,
            ObjectID integer NOT NULL,
            TablePriority integer NOT NULL DEFAULT 0,
            StatsCount integer NOT NULL DEFAULT 1,
            MaxModificationCounter bigint NOT NULL DEFAULT 0,
            TableStartTime datetime2(7) NULL,
            TableEndTime datetime2(7) NULL,
            SessionID smallint NULL,
            RequestID integer NULL,
            RequestStartTime datetime NULL,
            StatsUpdated integer NULL,
            StatsFailed integer NULL,
            StatsSkipped integer NULL,
            LastStatCompletedAt datetime2(3) NULL, /* v2.3: timestamp of last individual stat completion per worker */
            CONSTRAINT PK_QueueStatistic
                PRIMARY KEY CLUSTERED (QueueID, DatabaseName, SchemaName, ObjectName)
        );

        ALTER TABLE dbo.QueueStatistic
            ADD CONSTRAINT FK_QueueStatistic_Queue
            FOREIGN KEY (QueueID) REFERENCES dbo.Queue (QueueID);

        CREATE NONCLUSTERED INDEX IX_QueueStatistic_Unclaimed
            ON dbo.QueueStatistic (QueueID, TablePriority)
            INCLUDE (DatabaseName, SchemaName, ObjectName, ObjectID, TableStartTime, TableEndTime)
            WHERE TableStartTime IS NULL;

        /* #174: Disable lock escalation to prevent READPAST hint from losing effectiveness */
        ALTER TABLE dbo.QueueStatistic SET (LOCK_ESCALATION = DISABLE);

        RAISERROR(N'Created dbo.QueueStatistic table and indexes.', 10, 1) WITH NOWAIT;
    END;

    /*
    v2.3: Backward-compatible migration — add LastStatCompletedAt if it doesn't exist.
    Existing installations may not have this column from older versions.
    */
    IF  @StatsInParallel = N'Y'
    AND OBJECT_ID(N'dbo.QueueStatistic', N'U') IS NOT NULL
    AND NOT EXISTS (SELECT 1 FROM sys.columns WHERE object_id = OBJECT_ID(N'dbo.QueueStatistic') AND name = N'LastStatCompletedAt')
    BEGIN
        ALTER TABLE dbo.QueueStatistic ADD LastStatCompletedAt datetime2(3) NULL;
        IF @Debug = 1
            RAISERROR(N'Added LastStatCompletedAt column to dbo.QueueStatistic (v2.3 migration).', 10, 1) WITH NOWAIT;
    END;
    /*
    #142: Server-level AG readable secondary detection.
    If this server is an AG secondary for ALL databases, UPDATE STATISTICS will fail for everything.
    Check sys.dm_hadr_availability_replica_states early to prevent an error storm.
    */
    DECLARE @is_ag_secondary_server bit = 0;
    IF EXISTS (SELECT 1 FROM sys.all_objects WHERE name = N'dm_hadr_availability_replica_states' AND schema_id = SCHEMA_ID(N'sys'))
    BEGIN
        DECLARE @local_primary_count int = 0, @local_secondary_count int = 0;
        SELECT
            @local_primary_count = SUM(CASE WHEN ars.role_desc = N'PRIMARY' THEN 1 ELSE 0 END),
            @local_secondary_count = SUM(CASE WHEN ars.role_desc = N'SECONDARY' THEN 1 ELSE 0 END)
        FROM sys.dm_hadr_availability_replica_states AS ars
        WHERE ars.is_local = 1;

        IF @local_secondary_count > 0 AND @local_primary_count = 0
        BEGIN
            SET @is_ag_secondary_server = 1;
            RAISERROR(N'WARNING: This server is an AG readable secondary for all availability groups. UPDATE STATISTICS will fail for AG databases.', 10, 1) WITH NOWAIT;
            SET @WarningsOut = ISNULL(@WarningsOut, N'') + N'AG_SECONDARY_SERVER: All local AGs are secondary replicas; ';
        END;
    END;

    /* #144: Azure elastic pool DTU/vCore check.
       On Azure SQL DB (EngineEdition=5), check if running in an elastic pool
       where stats maintenance may consume shared pool resources. */
    IF CONVERT(int, SERVERPROPERTY(N'EngineEdition')) = 5
    BEGIN
        BEGIN TRY
            DECLARE @elastic_pool_name nvarchar(128);
            EXEC sys.sp_executesql
                N'SELECT @pool = elastic_pool_name FROM sys.database_service_objectives',
                N'@pool nvarchar(128) OUTPUT',
                @pool = @elastic_pool_name OUTPUT;
            IF @elastic_pool_name IS NOT NULL
            BEGIN
                RAISERROR(N'WARNING: Running in Azure elastic pool [%s]. Statistics maintenance consumes', 10, 1, @elastic_pool_name) WITH NOWAIT;
                RAISERROR(N'  shared pool DTU/vCore — other databases in the pool may be impacted.', 10, 1) WITH NOWAIT;
                SET @warnings += N'ELASTIC_POOL: ' + @elastic_pool_name + N'; ';
            END;
        END TRY
        BEGIN CATCH
            /* sys.database_service_objectives may not exist on all Azure tiers */
        END CATCH;
    END;

    /* #191: RCSI version store pressure warning.
       Databases using READ_COMMITTED_SNAPSHOT_ISOLATION keep row versions in tempdb.
       FULLSCAN statistics updates can increase version store usage significantly. */
    DECLARE @rcsi_db_count int = 0;
    SELECT @rcsi_db_count = COUNT(*)
    FROM sys.databases AS d
    WHERE d.is_read_committed_snapshot_on = 1
    AND   d.state = 0 /* ONLINE */
    AND   d.database_id > 4; /* user databases only */

    IF @rcsi_db_count > 0
    BEGIN
        DECLARE @version_store_mb bigint = 0;
        SELECT @version_store_mb = SUM(version_store_reserved_page_count) * 8 / 1024
        FROM tempdb.sys.dm_db_file_space_usage;

        IF @version_store_mb > 500 /* >500 MB version store already in use */
        BEGIN
            RAISERROR(N'WARNING: %d RCSI database(s) active, version store already %I64d MB.', 10, 1,
                @rcsi_db_count, @version_store_mb) WITH NOWAIT;
            RAISERROR(N'  FULLSCAN statistics updates may spike version store usage in tempdb.', 10, 1) WITH NOWAIT;
            SET @warnings += N'RCSI_VERSION_STORE: ' + CONVERT(nvarchar(20), @version_store_mb) + N' MB in use; ';
        END;
    END;
    /*#endregion 06-GUARDS */

    /*#region 07-PRESETS: Preset application, @StopByTime */
    /*
    ============================================================================
    PRESET APPLICATION (v1.9)
    ============================================================================
    Apply preset values to parameters. Presets only set NULL parameters,
    allowing explicit parameter values to override preset defaults.
    */
    IF @Preset IS NOT NULL
    BEGIN
        IF @Preset NOT IN (N'NIGHTLY_MAINTENANCE', N'WEEKLY_FULL', N'OLTP_LIGHT', N'WAREHOUSE_AGGRESSIVE')
        BEGIN
            INSERT INTO
                @errors
            (
                error_message,
                error_severity
            )
            SELECT
                error_message =
                    N'Invalid @Preset value. Use: NIGHTLY_MAINTENANCE, WEEKLY_FULL, OLTP_LIGHT, WAREHOUSE_AGGRESSIVE',
                error_severity = 16;
        END;

        IF @Debug = 1
        BEGIN
            RAISERROR(N'Applying preset: %s', 10, 1, @Preset) WITH NOWAIT;
        END;

        /*
        Presets unconditionally SET their defining parameters because SQL Server
        cannot distinguish "caller omitted this param" from "param got its default."
        If @Preset is specified, its values take priority.
        */

        /* NIGHTLY_MAINTENANCE: Balanced nightly job */
        IF @Preset = N'NIGHTLY_MAINTENANCE'
        BEGIN
            SET @TimeLimit = 3600; /* 1 hour */
            SET @TieredThresholds = 1;
            SET @ModificationThreshold = 5000;
            SET @TargetNorecompute = N'BOTH';
            SET @SortOrder = N'MODIFICATION_COUNTER';
        END;

        /* WEEKLY_FULL: Comprehensive weekly update */
        IF @Preset = N'WEEKLY_FULL'
        BEGIN
            SET @TimeLimit = 14400; /* 4 hours */
            SET @TieredThresholds = 1;
            SET @ModificationThreshold = 1000; /* Lower threshold */
            IF @DaysStaleThreshold IS NULL SET @DaysStaleThreshold = 7; /* Only if not specified (NULL default) */
            SET @TargetNorecompute = N'BOTH';
        END;

        /* OLTP_LIGHT: Minimal impact for OLTP systems */
        IF @Preset = N'OLTP_LIGHT'
        BEGIN
            SET @TimeLimit = 1800; /* 30 minutes */
            SET @ModificationThreshold = 50000; /* High threshold */
            SET @TieredThresholds = 1;
            IF @DelayBetweenStats IS NULL SET @DelayBetweenStats = 2; /* Only if not specified (NULL default) */
            IF @LockTimeout IS NULL SET @LockTimeout = 10; /* Only if not specified (NULL default) */
            IF @QueryStorePriority IS NULL SET @QueryStorePriority = N'Y'; /* Only if not specified (NULL default) */
        END;

        /* WAREHOUSE_AGGRESSIVE: Data warehouse full refresh */
        IF @Preset = N'WAREHOUSE_AGGRESSIVE'
        BEGIN
            SET @TimeLimit = NULL; /* No time limit */
            SET @ModificationThreshold = 500; /* Low threshold */
            SET @TieredThresholds = 0; /* Use fixed threshold */
            IF @StatisticsSample IS NULL SET @StatisticsSample = 100; /* FULLSCAN - only if not specified (NULL default) */
            SET @TargetNorecompute = N'BOTH';
        END;
    END;

    /*
    ============================================================================
    @StopByTime PROCESSING (v2.3)
    Convert absolute wall-clock stop time to a @TimeLimit (remaining seconds).
    Must occur before validation so @TimeLimit can be validated normally.
    ============================================================================
    */
    IF @StopByTime IS NOT NULL
    BEGIN
        BEGIN TRY
            DECLARE
                @stopby_time time(0) = CONVERT(time(0), @StopByTime),
                @now_time time(0) = CONVERT(time(0), SYSDATETIME()),
                @stopby_seconds_remaining int;

            SET @stopby_seconds_remaining =
                DATEDIFF(SECOND, @now_time, @stopby_time);

            /* If the stop time has already passed today, wrap to tomorrow */
            IF @stopby_seconds_remaining < 0
                SET @stopby_seconds_remaining = @stopby_seconds_remaining + 86400;

            /* Override @TimeLimit with computed seconds remaining */
            SET @TimeLimit = @stopby_seconds_remaining;
        END TRY
        BEGIN CATCH
            /* Validation will catch invalid formats via the pre-check above */
        END CATCH;
    END;
    /*#endregion 07-PRESETS */

    /*#region 08-VALIDATION: Parameter validation (pre-database) */
    /*
    ============================================================================
    PARAMETER VALIDATION
    ============================================================================
    */

    /* Normalize @Tables = 'ALL' to NULL (all tables). The display variable already
       shows 'ALL' for NULL, so users naturally expect 'ALL' to work as a keyword. */
    IF UPPER(LTRIM(RTRIM(@Tables))) = N'ALL'
        SET @Tables = NULL;

    /* P3 fix #159: Normalize @Databases='ALL' to 'ALL_DATABASES' with informational message.
       Users commonly try 'ALL' expecting it to work like other maintenance tools. */
    IF UPPER(LTRIM(RTRIM(@Databases))) = N'ALL'
    BEGIN
        SET @Databases = N'ALL_DATABASES';
        IF @Debug = 1
            RAISERROR(N'Note: @Databases=''ALL'' normalized to ''ALL_DATABASES'' (excludes system DBs).', 10, 1) WITH NOWAIT;
    END;

    /* P3 fix #198: Normalize empty string parameters to NULL with warning.
       Empty strings from parameterized jobs can cause unexpected behavior. */
    IF @Statistics IS NOT NULL AND LEN(LTRIM(RTRIM(@Statistics))) = 0
    BEGIN
        SET @Statistics = NULL;
        SET @WarningsOut = ISNULL(@WarningsOut, N'') + N'EMPTY_STRING_PARAM: @Statistics='''' treated as NULL (no filter); ';
        IF @Debug = 1
            RAISERROR(N'Note: @Statistics was empty string — treated as NULL (no filter).', 10, 1) WITH NOWAIT;
    END;

    IF @Tables IS NOT NULL AND LEN(LTRIM(RTRIM(@Tables))) = 0
    BEGIN
        SET @Tables = NULL;
        SET @WarningsOut = ISNULL(@WarningsOut, N'') + N'EMPTY_STRING_PARAM: @Tables='''' treated as NULL (all tables); ';
        IF @Debug = 1
            RAISERROR(N'Note: @Tables was empty string — treated as NULL (all tables).', 10, 1) WITH NOWAIT;
    END;

    IF @ExcludeStatistics IS NOT NULL AND LEN(LTRIM(RTRIM(@ExcludeStatistics))) = 0
    BEGIN
        SET @ExcludeStatistics = NULL;
        SET @WarningsOut = ISNULL(@WarningsOut, N'') + N'EMPTY_STRING_PARAM: @ExcludeStatistics='''' treated as NULL (no exclusions); ';
    END;

    IF @ExcludeTables IS NOT NULL AND LEN(LTRIM(RTRIM(@ExcludeTables))) = 0
    BEGIN
        SET @ExcludeTables = NULL;
        SET @WarningsOut = ISNULL(@WarningsOut, N'') + N'EMPTY_STRING_PARAM: @ExcludeTables='''' treated as NULL (no exclusions); ';
    END;

    IF @TargetNorecompute NOT IN (N'Y', N'N', N'BOTH')
    BEGIN
        INSERT INTO
            @errors
        (
            error_message,
            error_severity
        )
        SELECT
            error_message =
                N'The value for @TargetNorecompute is not supported. Use Y, N, or BOTH.',
            error_severity = 16;
    END;

    IF @Execute NOT IN (N'Y', N'N')
    BEGIN
        INSERT INTO
            @errors
        (
            error_message,
            error_severity
        )
        SELECT
            error_message =
                N'The value for @Execute is not supported. Use Y or N.',
            error_severity = 16;
    END;

    IF @CleanupOrphanedRuns NOT IN (N'Y', N'N')
    BEGIN
        INSERT INTO
            @errors
        (
            error_message,
            error_severity
        )
        SELECT
            error_message =
                N'The value for @CleanupOrphanedRuns is not supported. Use Y or N.',
            error_severity = 16;
    END;

    IF @GroupByJoinPattern NOT IN (N'Y', N'N')
    BEGIN
        INSERT INTO
            @errors
        (
            error_message,
            error_severity
        )
        SELECT
            error_message =
                N'The value for @GroupByJoinPattern is not supported. Use Y or N.',
            error_severity = 16;
    END;

    IF  @GroupByJoinPattern = N'Y'
    AND @StatsInParallel = N'Y'
    BEGIN
        INSERT INTO
            @errors
        (
            error_message,
            error_severity
        )
        SELECT
            error_message =
                N'@GroupByJoinPattern cannot be used with @StatsInParallel. Use one or the other.',
            error_severity = 16;
    END;

    IF  @WhatIfOutputTable IS NOT NULL
    AND @Execute = N'Y'
    BEGIN
        INSERT INTO
            @errors
        (
            error_message,
            error_severity
        )
        SELECT
            error_message =
                N'@WhatIfOutputTable requires @Execute = N (dry run mode).',
            error_severity = 16;
    END;

    /*
    Auto-create @WhatIfOutputTable if it doesn't exist, or validate schema if it does.
    P2 #10: Validate schema when table exists to give clear error message.
    P1b fix (v2.4): Validate via PARSENAME+QUOTENAME BEFORE any EXECUTE to prevent SQL injection.
    */
    IF  @WhatIfOutputTable IS NOT NULL
    AND @Execute = N'N'
    BEGIN
        /*
        P1b: Use PARSENAME+QUOTENAME to sanitize the table name BEFORE any dynamic SQL.
        PARSENAME returns NULL for names with injection characters (semicolons, quotes, etc.).
        QUOTENAME ensures safe bracket-quoting for the final FQN used in dynamic SQL.
        */
        DECLARE
            @safe_wio_schema sysname,
            @safe_wio_table  sysname,
            @safe_wio_fqn    nvarchar(512);

        SET @safe_wio_table  = PARSENAME(@WhatIfOutputTable, 1);
        SET @safe_wio_schema = ISNULL(PARSENAME(@WhatIfOutputTable, 2), N'dbo');

        IF @safe_wio_table IS NULL
        BEGIN
            INSERT INTO
                @errors
            (
                error_message,
                error_severity
            )
            SELECT
                error_message =
                    N'@WhatIfOutputTable is not a valid table name. Use schema.table or table format (e.g., ''dbo.WhatIfResults'').',
                error_severity = 16;
        END;
        ELSE
        BEGIN
            SET @safe_wio_fqn = QUOTENAME(@safe_wio_schema) + N'.' + QUOTENAME(@safe_wio_table);

        DECLARE @whatif_create_sql nvarchar(max) = N'
            IF OBJECT_ID(N''' + REPLACE(@safe_wio_fqn, N'''', N'''''') + N''', N''U'') IS NULL
            BEGIN
                CREATE TABLE ' + @safe_wio_fqn + N' (
                    SequenceNum int IDENTITY(1,1) PRIMARY KEY,
                    DatabaseName sysname NOT NULL,
                    SchemaName sysname NOT NULL,
                    TableName sysname NOT NULL,
                    StatName sysname NOT NULL,
                    Command nvarchar(max) NOT NULL,
                    ModificationCounter bigint NULL,
                    DaysStale int NULL,
                    PageCount bigint NULL
                );
            END;';

        BEGIN TRY
            /* Use EXECUTE() instead of sp_executesql so temp table persists to caller scope */
            EXECUTE (@whatif_create_sql);
        END TRY
        BEGIN CATCH
            INSERT INTO
                @errors
            (
                error_message,
                error_severity
            )
            SELECT
                error_message =
                    N'Failed to create @WhatIfOutputTable: ' + ERROR_MESSAGE(),
                error_severity = 16;
        END CATCH;

        /*
        Validate required columns exist with correct data types (v1.9 enhancement).
        Required: DatabaseName, SchemaName, TableName, StatName, Command
        Uses COL_LENGTH() for column existence.
        v1.9: Also validates data types to catch schema mismatches before insert fails.
        */
        DECLARE @whatif_validate_sql nvarchar(max) = N'
            DECLARE @missing_cols nvarchar(500) = N'''';
            DECLARE @wrong_types nvarchar(500) = N'''';
            DECLARE @tbl nvarchar(500) = N''' + REPLACE(@safe_wio_fqn, N'''', N'''''') + N''';
            DECLARE @obj_id int = OBJECT_ID(@tbl, N''U'');

            /* Check column existence */
            IF COL_LENGTH(@tbl, N''DatabaseName'') IS NULL SET @missing_cols += N''DatabaseName, '';
            IF COL_LENGTH(@tbl, N''SchemaName'') IS NULL SET @missing_cols += N''SchemaName, '';
            IF COL_LENGTH(@tbl, N''TableName'') IS NULL SET @missing_cols += N''TableName, '';
            IF COL_LENGTH(@tbl, N''StatName'') IS NULL SET @missing_cols += N''StatName, '';
            IF COL_LENGTH(@tbl, N''Command'') IS NULL SET @missing_cols += N''Command, '';

            IF LEN(@missing_cols) > 0
            BEGIN
                SET @missing_cols = LEFT(@missing_cols, LEN(@missing_cols) - 1);
                RAISERROR(N''@WhatIfOutputTable is missing required columns: %s. Expected schema: SequenceNum, DatabaseName, SchemaName, TableName, StatName, Command, ModificationCounter, DaysStale, PageCount'', 16, 1, @missing_cols);
            END

            /* Check data types if table exists (v1.9) */
            IF @obj_id IS NOT NULL AND LEN(@missing_cols) = 0
            BEGIN
                /* sysname columns must be nvarchar or sysname */
                IF NOT EXISTS (SELECT 1 FROM sys.columns c JOIN sys.types t ON c.user_type_id = t.user_type_id
                               WHERE c.object_id = @obj_id AND c.name = N''DatabaseName'' AND t.name IN (N''nvarchar'', N''sysname''))
                    SET @wrong_types += N''DatabaseName (expected sysname/nvarchar), '';
                IF NOT EXISTS (SELECT 1 FROM sys.columns c JOIN sys.types t ON c.user_type_id = t.user_type_id
                               WHERE c.object_id = @obj_id AND c.name = N''SchemaName'' AND t.name IN (N''nvarchar'', N''sysname''))
                    SET @wrong_types += N''SchemaName (expected sysname/nvarchar), '';
                IF NOT EXISTS (SELECT 1 FROM sys.columns c JOIN sys.types t ON c.user_type_id = t.user_type_id
                               WHERE c.object_id = @obj_id AND c.name = N''TableName'' AND t.name IN (N''nvarchar'', N''sysname''))
                    SET @wrong_types += N''TableName (expected sysname/nvarchar), '';
                IF NOT EXISTS (SELECT 1 FROM sys.columns c JOIN sys.types t ON c.user_type_id = t.user_type_id
                               WHERE c.object_id = @obj_id AND c.name = N''StatName'' AND t.name IN (N''nvarchar'', N''sysname''))
                    SET @wrong_types += N''StatName (expected sysname/nvarchar), '';
                IF NOT EXISTS (SELECT 1 FROM sys.columns c JOIN sys.types t ON c.user_type_id = t.user_type_id
                               WHERE c.object_id = @obj_id AND c.name = N''Command'' AND t.name IN (N''nvarchar'', N''varchar''))
                    SET @wrong_types += N''Command (expected nvarchar/varchar), '';

                IF LEN(@wrong_types) > 0
                BEGIN
                    SET @wrong_types = LEFT(@wrong_types, LEN(@wrong_types) - 1);
                    RAISERROR(N''@WhatIfOutputTable has columns with incompatible data types: %s'', 16, 1, @wrong_types);
                END
            END;';

        BEGIN TRY
            EXECUTE (@whatif_validate_sql);
        END TRY
        BEGIN CATCH
            INSERT INTO
                @errors
            (
                error_message,
                error_severity
            )
            SELECT
                error_message = ERROR_MESSAGE(),
                error_severity = 16;
        END CATCH;
        END; -- end ELSE (PARSENAME valid - safe to use @safe_wio_fqn)
    END;

    IF @LogToTable NOT IN (N'Y', N'N')
    BEGIN
        INSERT INTO
            @errors
        (
            error_message,
            error_severity
        )
        SELECT
            error_message =
                N'The value for @LogToTable is not supported. Use Y or N.',
            error_severity = 16;
    END;

    IF @PersistSamplePercent NOT IN (N'Y', N'N')
    BEGIN
        INSERT INTO
            @errors
        (
            error_message,
            error_severity
        )
        SELECT
            error_message =
                N'The value for @PersistSamplePercent is not supported. Use Y or N.',
            error_severity = 16;
    END;

    IF @StatsInParallel NOT IN (N'Y', N'N')
    BEGIN
        INSERT INTO
            @errors
        (
            error_message,
            error_severity
        )
        SELECT
            error_message =
                N'The value for @StatsInParallel is not supported. Use Y or N.',
            error_severity = 16;
    END;

    IF @IncludeSystemObjects NOT IN (N'Y', N'N')
    BEGIN
        INSERT INTO
            @errors
        (
            error_message,
            error_severity
        )
        SELECT
            error_message =
                N'The value for @IncludeSystemObjects is not supported. Use Y or N.',
            error_severity = 16;
    END;

    IF @ThresholdLogic NOT IN (N'OR', N'AND')
    BEGIN
        INSERT INTO
            @errors
        (
            error_message,
            error_severity
        )
        SELECT
            error_message =
                N'The value for @ThresholdLogic is not supported. Use OR or AND.',
            error_severity = 16;
    END;

    /*
    Validate @StatisticsFromTable doesn't contain SQL injection characters
    */
    IF  @StatisticsFromTable IS NOT NULL
    AND (
            @StatisticsFromTable LIKE N'%;%'
         OR @StatisticsFromTable LIKE N'%--%'
         OR @StatisticsFromTable LIKE N'%/*%'
         OR @StatisticsFromTable LIKE N'%*/%'
         OR @StatisticsFromTable LIKE N'%''%'
         OR @StatisticsFromTable LIKE N'%xp_%'
         OR @StatisticsFromTable LIKE N'%sp_execute%'
        )
    BEGIN
        INSERT INTO
            @errors
        (
            error_message,
            error_severity
        )
        SELECT
            error_message =
                N'The value for @StatisticsFromTable contains invalid characters.',
            error_severity = 16;
    END;

    /*
    P1b fix (v2.4): Old blocklist-based @WhatIfOutputTable injection check removed.
    Replaced by PARSENAME+QUOTENAME validation above, which fires BEFORE any EXECUTE
    and rejects ALL invalid identifiers — not just those matching a partial keyword list.
    */

    /*
    Validate @FilteredStatsMode
    */
    IF @FilteredStatsMode NOT IN (N'INCLUDE', N'EXCLUDE', N'ONLY', N'PRIORITY')
    BEGIN
        INSERT INTO
            @errors
        (
            error_message,
            error_severity
        )
        SELECT
            error_message =
                N'The value for @FilteredStatsMode is not supported. Use INCLUDE, EXCLUDE, ONLY, or PRIORITY.',
            error_severity = 16;
    END;

    /*
    Validate @QueryStorePriority
    */
    IF @QueryStorePriority NOT IN (N'Y', N'N')
    BEGIN
        INSERT INTO
            @errors
        (
            error_message,
            error_severity
        )
        SELECT
            error_message =
                N'The value for @QueryStorePriority is not supported. Use Y or N.',
            error_severity = 16;
    END;

    /*
    Validate @QueryStoreMetric
    */
    IF @QueryStoreMetric NOT IN (N'CPU', N'DURATION', N'READS', N'EXECUTIONS', N'AVG_CPU')
    BEGIN
        INSERT INTO
            @errors
        (
            error_message,
            error_severity
        )
        SELECT
            error_message =
                N'The value for @QueryStoreMetric is not supported. Use CPU, DURATION, READS, EXECUTIONS, or AVG_CPU.',
            error_severity = 16;
    END;

    /*
    Validate @SortOrder (add new options)
    */
    IF @SortOrder NOT IN (N'MODIFICATION_COUNTER', N'DAYS_STALE', N'PAGE_COUNT', N'RANDOM', N'QUERY_STORE', N'FILTERED_DRIFT', N'AUTO_CREATED')
    BEGIN
        INSERT INTO
            @errors
        (
            error_message,
            error_severity
        )
        SELECT
            error_message =
                N'The value for @SortOrder is not supported. Use MODIFICATION_COUNTER, DAYS_STALE, PAGE_COUNT, RANDOM, QUERY_STORE, FILTERED_DRIFT, or AUTO_CREATED.',
            error_severity = 16;
    END;

    /*
    Validate @HoursStaleThreshold / @DaysStaleThreshold mutual exclusion
    */
    IF @HoursStaleThreshold IS NOT NULL AND @DaysStaleThreshold IS NOT NULL
    BEGIN
        INSERT INTO
            @errors
        (
            error_message,
            error_severity
        )
        SELECT
            error_message =
                N'@HoursStaleThreshold and @DaysStaleThreshold cannot both be specified. Use one or the other. Note: @DaysStaleThreshold counts calendar day boundaries (midnight crossings); @HoursStaleThreshold uses precise elapsed hours.',
            error_severity = 16;
    END;

    /*
    Validate @StopByTime format (HH:MM or HH:MM:SS)
    */
    IF @StopByTime IS NOT NULL
    BEGIN
        BEGIN TRY
            DECLARE @stopby_parsed time(0) = CONVERT(time(0), @StopByTime);
        END TRY
        BEGIN CATCH
            INSERT INTO
                @errors
            (
                error_message,
                error_severity
            )
            SELECT
                error_message =
                    N'@StopByTime value ''' + @StopByTime + N''' is not a valid time format. Use HH:MM or HH:MM:SS (e.g., ''05:00'' or ''05:00:00'').',
                error_severity = 16;
        END CATCH;
    END;

    /*
    Validate @CheckPermissionsOnly
    */
    IF @CheckPermissionsOnly NOT IN (N'Y', N'N')
    BEGIN
        INSERT INTO
            @errors
        (
            error_message,
            error_severity
        )
        SELECT
            error_message =
                N'The value for @CheckPermissionsOnly is not supported. Use Y or N.',
            error_severity = 16;
    END;

    /*
    Validate @SkipTablesWithColumnstore
    */
    IF @SkipTablesWithColumnstore NOT IN (N'Y', N'N')
    BEGIN
        INSERT INTO
            @errors
        (
            error_message,
            error_severity
        )
        SELECT
            error_message =
                N'The value for @SkipTablesWithColumnstore is not supported. Use Y or N.',
            error_severity = 16;
    END;

    /*
    Validate @MaxAGRedoQueueMB (v2.7, #18)
    */
    IF @MaxAGRedoQueueMB IS NOT NULL AND @MaxAGRedoQueueMB < 0
    BEGIN
        INSERT INTO
            @errors
        (
            error_message,
            error_severity
        )
        SELECT
            error_message =
                N'@MaxAGRedoQueueMB must be >= 0 when specified. Supplied: ' + CONVERT(nvarchar(20), @MaxAGRedoQueueMB),
            error_severity = 16;
    END;

    /*
    Validate @MaxAGWaitMinutes (v2.7, #18)
    */
    IF @MaxAGWaitMinutes IS NOT NULL AND @MaxAGWaitMinutes < 1
    BEGIN
        INSERT INTO
            @errors
        (
            error_message,
            error_severity
        )
        SELECT
            error_message =
                N'@MaxAGWaitMinutes must be >= 1 when specified. Supplied: ' + CONVERT(nvarchar(20), @MaxAGWaitMinutes),
            error_severity = 16;
    END;

    /*
    Validate @MinTempdbFreeMB (v2.7, #34)
    */
    IF @MinTempdbFreeMB IS NOT NULL AND @MinTempdbFreeMB < 0
    BEGIN
        INSERT INTO
            @errors
        (
            error_message,
            error_severity
        )
        SELECT
            error_message =
                N'@MinTempdbFreeMB must be >= 0 when specified. Supplied: ' + CONVERT(nvarchar(20), @MinTempdbFreeMB),
            error_severity = 16;
    END;

    /*
    Validate @IncludeIndexedViews (#49)
    */
    IF @IncludeIndexedViews NOT IN (N'Y', N'N')
    BEGIN
        INSERT INTO @errors (error_message, error_severity)
        SELECT N'The value for @IncludeIndexedViews is not supported. Use Y or N.', 16;
    END;

    /*
    Validate @LogSkippedToCommandLog (#58)
    */
    IF @LogSkippedToCommandLog NOT IN (N'Y', N'N')
    BEGIN
        INSERT INTO @errors (error_message, error_severity)
        SELECT N'The value for @LogSkippedToCommandLog is not supported. Use Y or N.', 16;
    END;

    /*
    Validate @CompletionNotifyTable (#64)
    P1 fix (#155): Apply PARSENAME+QUOTENAME sanitization to prevent SQL injection via
    @CompletionNotifyTable. Identical pattern to @WhatIfOutputTable (P1b fix, v2.4).
    PARSENAME returns NULL for names containing injection characters (semicolons, quotes, etc.).
    QUOTENAME ensures safe bracket-quoting for the FQN used in dynamic SQL.
    */
    IF @CompletionNotifyTable IS NOT NULL AND @CompletionNotifyTable = N''
    BEGIN
        INSERT INTO @errors (error_message, error_severity)
        SELECT N'@CompletionNotifyTable cannot be empty string. Use NULL to disable or provide a table name.', 16;
    END;

    IF @CompletionNotifyTable IS NOT NULL AND @CompletionNotifyTable <> N''
    BEGIN
        DECLARE
            @safe_cnt_schema sysname,
            @safe_cnt_table  sysname,
            @safe_cnt_fqn    nvarchar(512);

        SET @safe_cnt_table  = PARSENAME(@CompletionNotifyTable, 1);
        SET @safe_cnt_schema = ISNULL(PARSENAME(@CompletionNotifyTable, 2), N'dbo');

        IF @safe_cnt_table IS NULL
        BEGIN
            INSERT INTO @errors (error_message, error_severity)
            SELECT
                N'@CompletionNotifyTable is not a valid table name. Use schema.table or table format (e.g., ''dbo.StatUpdateNotify''). Names with injection characters are rejected.',
                16;
        END;
        ELSE
        BEGIN
            SET @safe_cnt_fqn = QUOTENAME(@safe_cnt_schema) + N'.' + QUOTENAME(@safe_cnt_table);
        END;
    END;

    /* #182: Range validation for numeric parameters */
    IF @ModificationThreshold IS NOT NULL AND @ModificationThreshold < 0
    BEGIN
        INSERT INTO @errors (error_message, error_severity)
        SELECT N'@ModificationThreshold cannot be negative. Use 0 or positive integer.', 16;
    END;

    IF @StatisticsSample IS NOT NULL AND (@StatisticsSample < 1 OR @StatisticsSample > 100)
    BEGIN
        INSERT INTO @errors (error_message, error_severity)
        SELECT N'@StatisticsSample must be between 1 and 100 (100 = FULLSCAN). Use NULL for SQL Server auto-sample.', 16;
    END;

    IF @ModificationPercent IS NOT NULL AND (@ModificationPercent < 0 OR @ModificationPercent > 100)
    BEGIN
        INSERT INTO @errors (error_message, error_severity)
        SELECT N'@ModificationPercent must be between 0 and 100.', 16;
    END;

    IF @TimeLimit IS NOT NULL AND @TimeLimit < 0
    BEGIN
        INSERT INTO @errors (error_message, error_severity)
        SELECT N'@TimeLimit cannot be negative. Use NULL for unlimited or positive integer for seconds.', 16;
    END;

    IF @MaxDOP IS NOT NULL AND @MaxDOP < 0
    BEGIN
        INSERT INTO @errors (error_message, error_severity)
        SELECT N'@MaxDOP cannot be negative. Use NULL for default or 0 for unlimited.', 16;
    END;

    IF @MaxGrantPercent IS NOT NULL AND (@MaxGrantPercent < 1 OR @MaxGrantPercent > 100)
    BEGIN
        INSERT INTO @errors (error_message, error_severity)
        SELECT N'@MaxGrantPercent must be between 1 and 100.', 16;
    END;

    /* #195: Standard Edition + @IncludeIndexedViews warning.
       Indexed view statistics are updated but not used by the optimizer without
       NOEXPAND hint on Standard/Web/Express editions. Only Enterprise/Developer
       auto-match indexed views. */
    IF  @IncludeIndexedViews = N'Y'
    AND CONVERT(int, SERVERPROPERTY(N'EngineEdition')) NOT IN (3, 8) /* Not Enterprise (3) or MI (8) */
    AND CONVERT(nvarchar(128), SERVERPROPERTY(N'Edition')) NOT LIKE N'Developer%'
    BEGIN
        RAISERROR(N'WARNING: @IncludeIndexedViews=Y on non-Enterprise edition. Indexed view statistics', 10, 1) WITH NOWAIT;
        RAISERROR(N'  will be updated but the optimizer will not auto-match views without NOEXPAND hint.', 10, 1) WITH NOWAIT;
        RAISERROR(N'  Queries must explicitly reference views WITH (NOEXPAND) to use these statistics.', 10, 1) WITH NOWAIT;
        SET @warnings += N'INDEXED_VIEWS_NON_ENTERPRISE: Stats updated but NOEXPAND required; ';
    END;

    /* #170: @IncludeSystemObjects edition/role guard.
       Updating system table statistics is unsupported on read-only secondaries
       and can cause issues on replicas. Warn early. */
    IF @IncludeSystemObjects = N'Y'
    BEGIN
        RAISERROR(N'WARNING: @IncludeSystemObjects=Y — system table statistics will be included.', 10, 1) WITH NOWAIT;
        RAISERROR(N'  This is unsupported on AG readable secondary replicas and may cause errors.', 10, 1) WITH NOWAIT;
        SET @warnings += N'SYSTEM_OBJECTS_INCLUDED: system table stats may fail on replicas; ';
    END;
    /*#endregion 08-VALIDATION */

    /*#region 09-DB-PARSE: @Databases parsing, AG secondary check */
    /*
    ============================================================================
    PARSE @Databases - Ola Hallengren pattern
    Supports: SYSTEM_DATABASES, USER_DATABASES, ALL_DATABASES,
              AVAILABILITY_GROUP_DATABASES, wildcards (%), exclusions (-)
    ============================================================================
    */
    IF @Databases IS NOT NULL
    BEGIN
        /*
        Clean input: remove newlines and trim
        */
        SELECT @Databases = LTRIM(RTRIM(REPLACE(REPLACE(@Databases, CHAR(10), N''), CHAR(13), N'')));

        /*
        Parse comma-separated items into @SelectedDatabases
        Uses recursive CTE (Ola Hallengren pattern) to preserve order.
        STRING_SPLIT order is undefined in SQL 2016-2019; this approach is deterministic.
        */
        ;WITH DatabaseSplitter AS
        (
            /*
            Anchor: first item (before first comma or entire string if no comma)
            */
            SELECT
                DatabaseItem = LTRIM(RTRIM(
                    CASE
                        WHEN CHARINDEX(N',', @Databases) > 0
                        THEN SUBSTRING(@Databases, 1, CHARINDEX(N',', @Databases) - 1)
                        ELSE @Databases
                    END
                )),
                Remainder =
                    CASE
                        WHEN CHARINDEX(N',', @Databases) > 0
                        THEN SUBSTRING(@Databases, CHARINDEX(N',', @Databases) + 1, LEN(@Databases))
                        ELSE N''
                    END,
                StartPosition = 1

            UNION ALL

            /*
            Recursive: next item from remainder
            */
            SELECT
                DatabaseItem = LTRIM(RTRIM(
                    CASE
                        WHEN CHARINDEX(N',', Remainder) > 0
                        THEN SUBSTRING(Remainder, 1, CHARINDEX(N',', Remainder) - 1)
                        ELSE Remainder
                    END
                )),
                Remainder =
                    CASE
                        WHEN CHARINDEX(N',', Remainder) > 0
                        THEN SUBSTRING(Remainder, CHARINDEX(N',', Remainder) + 1, LEN(Remainder))
                        ELSE N''
                    END,
                StartPosition = StartPosition + 1
            FROM DatabaseSplitter
            WHERE LEN(Remainder) > 0
        ),
        Databases2 AS
        (
            SELECT
                DatabaseItem =
                    CASE
                        WHEN DatabaseItem LIKE N'-%'
                        THEN LTRIM(STUFF(DatabaseItem, 1, 1, N''))
                        ELSE DatabaseItem
                    END,
                StartPosition,
                Selected =
                    CASE
                        WHEN DatabaseItem LIKE N'-%'
                        THEN CONVERT(bit, 0)
                        ELSE CONVERT(bit, 1)
                    END
            FROM DatabaseSplitter
            WHERE DatabaseItem <> N''
        ),
        Databases3 AS
        (
            SELECT
                DatabaseItem =
                    CASE
                        WHEN DatabaseItem IN (N'ALL_DATABASES', N'SYSTEM_DATABASES',
                                              N'USER_DATABASES', N'AVAILABILITY_GROUP_DATABASES')
                        THEN N'%'
                        ELSE DatabaseItem
                    END,
                DatabaseType =
                    CASE
                        WHEN DatabaseItem = N'SYSTEM_DATABASES' THEN 'S'
                        WHEN DatabaseItem = N'USER_DATABASES' THEN 'U'
                        /*
                        ALL_DATABASES excludes system DBs by default.
                        Use SYSTEM_DATABASES explicitly if you need master/msdb/model.
                        */
                        WHEN DatabaseItem = N'ALL_DATABASES' THEN 'U'
                        ELSE NULL
                    END,
                AvailabilityGroup =
                    CASE
                        WHEN DatabaseItem = N'AVAILABILITY_GROUP_DATABASES'
                        THEN CONVERT(bit, 1)
                        ELSE NULL
                    END,
                StartPosition,
                Selected
            FROM Databases2
        )
        INSERT INTO @SelectedDatabases
            (DatabaseItem, DatabaseType, AvailabilityGroup, StartPosition, Selected)
        SELECT
            DatabaseItem,
            DatabaseType,
            AvailabilityGroup,
            StartPosition,
            Selected
        FROM Databases3
        OPTION (MAXRECURSION 0); /* Unlimited - supports instances with 1000+ databases */
    END;

    /*
    Populate @tmpDatabases with all accessible databases
    */
    INSERT INTO @tmpDatabases
        (DatabaseName, DatabaseType, AvailabilityGroup, Selected, Completed)
    SELECT
        DatabaseName = d.name,
        DatabaseType =
            CASE
                WHEN d.name IN (N'master', N'msdb', N'model')
                  OR d.is_distributor = 1
                THEN 'S'
                ELSE 'U'
            END,
        AvailabilityGroup =
            CASE
                WHEN EXISTS
                (
                    SELECT 1
                    FROM sys.dm_hadr_database_replica_states AS drs
                    WHERE drs.database_id = d.database_id
                    AND   drs.is_local = 1
                )
                THEN CONVERT(bit, 1)
                ELSE CONVERT(bit, 0)
            END,
        Selected = 0,
        Completed = 0
    FROM sys.databases AS d
    WHERE d.name <> N'tempdb'
    AND   d.source_database_id IS NULL  /* Exclude database snapshots */
    AND   d.state = 0                   /* ONLINE only */
    AND   HAS_DBACCESS(d.name) = 1;     /* Skip SINGLE_USER held by other sessions */

    /*
    Apply selections (inclusion pass first)
    */
    UPDATE td
    SET td.Selected = sd.Selected
    FROM @tmpDatabases AS td
    INNER JOIN @SelectedDatabases AS sd
        ON td.DatabaseName LIKE REPLACE(sd.DatabaseItem, N'_', N'[_]') COLLATE DATABASE_DEFAULT
        AND (td.DatabaseType = sd.DatabaseType OR sd.DatabaseType IS NULL)
        AND (td.AvailabilityGroup = sd.AvailabilityGroup OR sd.AvailabilityGroup IS NULL)
    WHERE sd.Selected = 1;

    /*
    Apply exclusions (must come after inclusions)
    */
    UPDATE td
    SET td.Selected = sd.Selected
    FROM @tmpDatabases AS td
    INNER JOIN @SelectedDatabases AS sd
        ON td.DatabaseName LIKE REPLACE(sd.DatabaseItem, N'_', N'[_]') COLLATE DATABASE_DEFAULT
        AND (td.DatabaseType = sd.DatabaseType OR sd.DatabaseType IS NULL)
        AND (td.AvailabilityGroup = sd.AvailabilityGroup OR sd.AvailabilityGroup IS NULL)
    WHERE sd.Selected = 0;

    /*
    Default to current database if @Databases is NULL
    */
    IF @Databases IS NULL
    BEGIN
        UPDATE @tmpDatabases
        SET Selected = 1
        WHERE DatabaseName = DB_NAME();
    END;

    /*
    Get count for display
    */
    SELECT @database_count = COUNT_BIG(*)
    FROM @tmpDatabases
    WHERE Selected = 1;

    /*
    Validate at least one database matched
    */
    IF @database_count = 0
    BEGIN
        INSERT INTO
            @errors
        (
            error_message,
            error_severity
        )
        SELECT
            error_message =
                N'No databases matched the @Databases pattern: ' + ISNULL(@Databases, N'(NULL)'),
            error_severity = 16;
    END;

    /*
    ============================================================================
    AVAILABILITY GROUP CHECK - Exclude secondary replicas (FAIL FAST)
    ============================================================================
    Check AG status immediately after database selection, before parameter
    validation. If all selected databases are on AG secondaries, fail fast
    instead of wasting cycles validating parameters we'll never use.
    */
    DECLARE
        @ag_secondary_count integer = 0,
        @ag_secondary_list nvarchar(max) = N'';

    DECLARE @ag_secondary_cache TABLE (DatabaseName sysname PRIMARY KEY);

    INSERT INTO @ag_secondary_cache (DatabaseName)
    SELECT DISTINCT
        d.name
    FROM sys.dm_hadr_availability_replica_states AS ars
    JOIN sys.dm_hadr_database_replica_states AS drs
        ON drs.replica_id = ars.replica_id
    JOIN sys.databases AS d
        ON d.database_id = drs.database_id
    WHERE ars.is_local = 1
    AND   ars.role_desc = N'SECONDARY';

    /*
    Build display list and exclude AG secondaries from selection
    */
    SELECT
        @ag_secondary_list = @ag_secondary_list + td.DatabaseName + N', '
    FROM @tmpDatabases AS td
    WHERE td.Selected = 1
    AND   EXISTS (SELECT 1 FROM @ag_secondary_cache AS c WHERE c.DatabaseName = td.DatabaseName);

    UPDATE td
    SET td.Selected = 0
    FROM @tmpDatabases AS td
    WHERE td.Selected = 1
    AND   EXISTS (SELECT 1 FROM @ag_secondary_cache AS c WHERE c.DatabaseName = td.DatabaseName);

    SELECT @ag_secondary_count = ROWCOUNT_BIG();

    /*
    Update database count after AG exclusion and validate
    */
    SELECT @database_count = COUNT_BIG(*)
    FROM @tmpDatabases
    WHERE Selected = 1;

    IF @database_count = 0
    AND @ag_secondary_count > 0
    BEGIN
        RAISERROR(N'All selected databases are on AG secondary replicas. Statistics cannot be updated on readable secondaries.', 16, 1) WITH NOWAIT;
        IF @StatsInParallel = N'N'
            EXEC sp_releaseapplock @Resource = N'sp_StatUpdate', @LockOwner = N'Session';
        RETURN 1;
    END;

    /* #161: Warn when @Databases matched zero databases (no AG secondaries — likely misspelling) */
    IF  @database_count = 0
    AND @ag_secondary_count = 0
    AND @Databases IS NOT NULL
    BEGIN
        RAISERROR(N'WARNING: @Databases=''%s'' matched 0 databases. Check spelling. Valid keywords: ALL_DATABASES, USER_DATABASES, SYSTEM_DATABASES, AVAILABILITY_GROUP_DATABASES. Wildcards: %%', 10, 1, @Databases) WITH NOWAIT;
        SET @WarningsOut = ISNULL(@WarningsOut, N'') +
            N'NO_MATCHING_DATABASES: @Databases matched 0 databases; ';
    END;
    /*#endregion 09-DB-PARSE */

    /*
    P2e fix (v2.4): @QueryStorePriority late normalization.
    Default was N'N' (non-NULL) which prevented OLTP_LIGHT preset from applying N'Y' override.
    Default changed to NULL. Now: if no preset selected and user didn't specify, apply 'N' here.
    This allows preset callers (like OLTP_LIGHT) to set 'Y' via their own block.
    */
    IF @QueryStorePriority IS NULL AND @Preset IS NULL
        SET @QueryStorePriority = N'N'; /* apply functional default when no preset overrides it */

    /*#region 10-VALIDATION-REPORT: Validation reporting, error aggregation */
    /*
    ============================================================================
    PARAMETER VALIDATION
    ============================================================================
    */
    IF  @StatisticsSample IS NOT NULL
    AND (
            @StatisticsSample < 1
         OR @StatisticsSample > 100
        )
    BEGIN
        INSERT INTO
            @errors
        (
            error_message,
            error_severity
        )
        SELECT
            error_message =
                N'The value for @StatisticsSample must be NULL or between 1 and 100.',
            error_severity = 16;
    END;

    IF  @MaxDOP IS NOT NULL
    AND (
            @MaxDOP < 0
         OR @MaxDOP > 64
        )
    BEGIN
        INSERT INTO
            @errors
        (
            error_message,
            error_severity
        )
        SELECT
            error_message =
                N'The value for @MaxDOP must be between 0 and 64.',
            error_severity = 16;
    END;

    IF  @MaxGrantPercent IS NOT NULL
    AND (
            @MaxGrantPercent < 1
         OR @MaxGrantPercent > 100
        )
    BEGIN
        INSERT INTO
            @errors
        (
            error_message,
            error_severity
        )
        SELECT
            error_message =
                N'The value for @MaxGrantPercent must be NULL or between 1 and 100.',
            error_severity = 16;
    END;

    /*
    Validate @LockTimeout
    -1 is valid (infinite wait), 0+ is valid (timeout in seconds)
    Negative values other than -1 are invalid
    */
    IF  @LockTimeout IS NOT NULL
    AND @LockTimeout < -1
    BEGIN
        INSERT INTO
            @errors
        (
            error_message,
            error_severity
        )
        SELECT
            error_message =
                N'The value for @LockTimeout must be -1 (infinite) or >= 0 seconds.',
            error_severity = 16;
    END;

    /*
    Validate @LongRunningThresholdMinutes and @LongRunningSamplePercent
    */
    IF  @LongRunningThresholdMinutes IS NOT NULL
    AND @LongRunningThresholdMinutes < 1
    BEGIN
        INSERT INTO
            @errors
        (
            error_message,
            error_severity
        )
        SELECT
            error_message =
                N'The value for @LongRunningThresholdMinutes must be >= 1.',
            error_severity = 16;
    END;

    /*
    Validate @MaxConsecutiveFailures
    */
    IF  @MaxConsecutiveFailures IS NOT NULL
    AND @MaxConsecutiveFailures < 1
    BEGIN
        INSERT INTO
            @errors
        (
            error_message,
            error_severity
        )
        SELECT
            error_message =
                N'The value for @MaxConsecutiveFailures must be >= 1.',
            error_severity = 16;
    END;

    IF  @LongRunningSamplePercent IS NOT NULL
    AND (
            @LongRunningSamplePercent < 1
         OR @LongRunningSamplePercent > 100
        )
    BEGIN
        INSERT INTO
            @errors
        (
            error_message,
            error_severity
        )
        SELECT
            error_message =
                N'The value for @LongRunningSamplePercent must be between 1 and 100.',
            error_severity = 16;
    END;

    IF  @LongRunningThresholdMinutes IS NOT NULL
    AND @LogToTable = N'N'
    BEGIN
        INSERT INTO
            @errors
        (
            error_message,
            error_severity
        )
        SELECT
            error_message =
                N'@LongRunningThresholdMinutes requires @LogToTable = ''Y'' (needs CommandLog history).',
            error_severity = 16;
    END;

    IF  @TimeLimit IS NOT NULL
    AND @TimeLimit < 0
    BEGIN
        INSERT INTO
            @errors
        (
            error_message,
            error_severity
        )
        SELECT
            error_message =
                N'The value for @TimeLimit must be >= 0.',
            error_severity = 16;
    END;

    IF  @BatchLimit IS NOT NULL
    AND @BatchLimit < 1
    BEGIN
        INSERT INTO
            @errors
        (
            error_message,
            error_severity
        )
        SELECT
            error_message =
                N'The value for @BatchLimit must be >= 1.',
            error_severity = 16;
    END;

    IF @StagedDiscovery NOT IN (N'Y', N'N')
    BEGIN
        INSERT INTO
            @errors
        (
            error_message,
            error_severity
        )
        SELECT
            error_message =
                N'The value for @StagedDiscovery must be Y or N.',
            error_severity = 16;
    END;

    IF @CollectHeapForwarding NOT IN (N'Y', N'N')
    BEGIN
        INSERT INTO
            @errors
        (
            error_message,
            error_severity
        )
        SELECT
            error_message =
                N'The value for @CollectHeapForwarding must be Y or N.',
            error_severity = 16;
    END;

    IF  @DelayBetweenStats IS NOT NULL
    AND @DelayBetweenStats < 0
    BEGIN
        INSERT INTO
            @errors
        (
            error_message,
            error_severity
        )
        SELECT
            error_message =
                N'The value for @DelayBetweenStats must be >= 0.',
            error_severity = 16;
    END;

    /*
    Raise all validation errors at once
    */
    IF EXISTS
       (
           SELECT
               1
           FROM @errors
       )
    BEGIN
        /*
        Aggregate all error messages using FOR XML (SQL 2016 compatible).
        STRING_AGG would be cleaner but requires SQL 2017+.
        */
        DECLARE @all_errors nvarchar(max);

        SELECT @all_errors = STUFF((
            SELECT CHAR(13) + CHAR(10) + e.error_message
            FROM @errors AS e
            ORDER BY e.id
            FOR XML PATH(''), TYPE
        ).value('.', 'nvarchar(max)'), 1, 2, '');

        /*
        DECODE XML ENTITIES (P1 #27, v1.9 enhancement)
        FOR XML PATH encodes special characters. Decode them for readable output.
        Order matters: decode &amp; last since it affects other entities.
        v1.9: Added &quot; and &apos; for complete XML entity coverage.
        */
        SELECT @all_errors = REPLACE(REPLACE(REPLACE(REPLACE(REPLACE(@all_errors,
            N'&lt;', N'<'),
            N'&gt;', N'>'),
            N'&quot;', N'"'),
            N'&apos;', N''''),
            N'&amp;', N'&');

        RAISERROR(@all_errors, 16, 1) WITH NOWAIT;
        RAISERROR(N'', 10, 1) WITH NOWAIT;
        RAISERROR(N'Documentation: https://ola.hallengren.com/sql-server-index-and-statistics-maintenance.html', 10, 1) WITH NOWAIT;

        /* #200: Set @StopReasonOut on parameter validation failure */
        SET @StopReasonOut = N'PARAMETER_ERROR';

        IF @StatsInParallel = N'N'
            EXEC sp_releaseapplock @Resource = N'sp_StatUpdate', @LockOwner = N'Session';
        RETURN 50000;
    END;
    /*#endregion 10-VALIDATION-REPORT */

    /*#region 11-PERMISSIONS: @CheckPermissionsOnly mode */
    /*
    ============================================================================
    @CheckPermissionsOnly mode (v2.3)
    Check required permissions and report missing ones. No stats updates.
    ============================================================================
    */
    IF @CheckPermissionsOnly = N'Y'
    BEGIN
        RAISERROR(N'sp_StatUpdate: @CheckPermissionsOnly mode - checking required permissions...', 10, 1) WITH NOWAIT;

        /* Build permission result table */
        DECLARE @perm_results TABLE
        (
            permission_name nvarchar(200),
            scope nvarchar(200),
            has_permission nvarchar(3),
            notes nvarchar(500)
        );

        /* Check VIEW ANY DATABASE */
        INSERT INTO @perm_results (permission_name, scope, has_permission, notes)
        SELECT
            N'VIEW ANY DATABASE',
            N'Server',
            CASE WHEN HAS_PERMS_BY_NAME(NULL, 'SERVER', 'VIEW ANY DATABASE') = 1 THEN N'YES' ELSE N'NO' END,
            N'Required to enumerate databases for discovery';

        /* Check VIEW DATABASE STATE (current database) */
        INSERT INTO @perm_results (permission_name, scope, has_permission, notes)
        SELECT
            N'VIEW DATABASE STATE',
            N'Database: ' + DB_NAME(),
            CASE WHEN HAS_PERMS_BY_NAME(DB_NAME(), 'DATABASE', 'VIEW DATABASE STATE') = 1 THEN N'YES' ELSE N'NO' END,
            N'Required for DMV access (dm_db_stats_properties, dm_exec_sessions)';

        /* Check ALTER on schema (required for UPDATE STATISTICS) */
        INSERT INTO @perm_results (permission_name, scope, has_permission, notes)
        SELECT
            N'ALTER',
            N'Database: ' + DB_NAME(),
            CASE WHEN HAS_PERMS_BY_NAME(DB_NAME(), 'DATABASE', 'ALTER ANY SCHEMA') = 1
                   OR IS_SRVROLEMEMBER(N'sysadmin') = 1
                   OR IS_MEMBER(N'db_owner') = 1
                   OR IS_MEMBER(N'db_ddladmin') = 1
                 THEN N'YES' ELSE N'NO'
            END,
            N'Required for UPDATE STATISTICS (via ALTER on tables, db_owner, db_ddladmin, or sysadmin)';

        /* Check INSERT on dbo.CommandLog (if table exists) */
        INSERT INTO @perm_results (permission_name, scope, has_permission, notes)
        SELECT
            N'INSERT',
            N'dbo.CommandLog',
            CASE
                WHEN @commandlog_exists = 0 THEN N'N/A'
                WHEN HAS_PERMS_BY_NAME(N'dbo.CommandLog', 'OBJECT', 'INSERT') = 1 THEN N'YES'
                ELSE N'NO'
            END,
            CASE WHEN @commandlog_exists = 0 THEN N'CommandLog table does not exist' ELSE N'Required for @LogToTable = Y' END;

        /* Return permission check results */
        SELECT
            permission_name,
            scope,
            has_permission,
            notes,
            status = CASE WHEN has_permission = N'NO' THEN N'MISSING' WHEN has_permission = N'N/A' THEN N'NOT APPLICABLE' ELSE N'OK' END
        FROM @perm_results
        ORDER BY
            CASE WHEN has_permission = N'NO' THEN 0 ELSE 1 END,
            permission_name;

        /* Emit missing permission warnings */
        IF EXISTS (SELECT 1 FROM @perm_results WHERE has_permission = N'NO')
        BEGIN
            RAISERROR(N'WARNING: Some required permissions are missing. See result set above.', 10, 1) WITH NOWAIT;
        END
        ELSE
        BEGIN
            RAISERROR(N'All checked permissions are present.', 10, 1) WITH NOWAIT;
        END;

        IF @StatsInParallel = N'N'
            EXEC sp_releaseapplock @Resource = N'sp_StatUpdate', @LockOwner = N'Session';
        RETURN 0;
    END;

    /*
    Build human-readable run label
    */
    SELECT
        @run_label =
            CONVERT(nvarchar(50), SERVERPROPERTY(N'ServerName')) +
            N'_' +
            REPLACE(REPLACE(REPLACE(CONVERT(nvarchar(19), @start_time, 120), N'-', N''), N':', N''), N' ', N'_');
    /*#endregion 11-PERMISSIONS */

    /*#region 12-HEADER: Header output (server info, params, debug) */
    /*
    ============================================================================
    HEADER OUTPUT
    ============================================================================
    */
    DECLARE
        @server_name nvarchar(128) = CONVERT(nvarchar(128), SERVERPROPERTY(N'ServerName')),
        @product_version nvarchar(128) = CONVERT(nvarchar(128), SERVERPROPERTY(N'ProductVersion')),
        @edition nvarchar(128) = CONVERT(nvarchar(128), SERVERPROPERTY(N'Edition')),
        @engine_edition int = CONVERT(int, SERVERPROPERTY(N'EngineEdition')),
        /* EngineEdition: 3=Enterprise, 5=Azure SQL DB, 8=Azure SQL MI, 9=Azure SQL Edge */
        @is_azure_sql bit = CASE WHEN CONVERT(int, SERVERPROPERTY(N'EngineEdition')) IN (5, 8, 9) THEN 1 ELSE 0 END,
        @Tables_display nvarchar(max) = ISNULL(@Tables, N'ALL'),
        @TimeLimit_display nvarchar(20) = ISNULL(CONVERT(nvarchar(20), @TimeLimit), N'None'),
        @BatchLimit_display nvarchar(20) = ISNULL(CONVERT(nvarchar(20), @BatchLimit), N'None'),
        @LockTimeout_display nvarchar(20) = ISNULL(CONVERT(nvarchar(20), @LockTimeout), N'None'),
        @MaxConsecutiveFailures_display nvarchar(20) = ISNULL(CONVERT(nvarchar(20), @MaxConsecutiveFailures), N'None'),
        @start_time_display nvarchar(30) = CONVERT(nvarchar(30), @start_time, 121);

    RAISERROR(N'', 10, 1) WITH NOWAIT;
    RAISERROR(N'===============================================================================', 10, 1) WITH NOWAIT;
    RAISERROR(N' sp_StatUpdate - Priority-Based Statistics Maintenance', 10, 1) WITH NOWAIT;
    RAISERROR(N'===============================================================================', 10, 1) WITH NOWAIT;
    RAISERROR(N'', 10, 1) WITH NOWAIT;
    RAISERROR(N'Server:      %s', 10, 1, @server_name) WITH NOWAIT;
    RAISERROR(N'Version:     %s', 10, 1, @product_version) WITH NOWAIT;
    RAISERROR(N'Edition:     %s', 10, 1, @edition) WITH NOWAIT;

    /*
    Azure SQL Platform Warning
    DTU/vCore consumption warning for Azure SQL environments.
    */
    IF @is_azure_sql = 1
    BEGIN
        /*
        Azure platform distinction (#39): EngineEdition 5 = Azure SQL DB, 8 = Azure SQL MI, 9 = Azure SQL Edge.
        MI supports incremental stats, Resource Governor, and most on-prem features. SQL DB does not.
        */
        DECLARE @azure_platform nvarchar(50) = CASE @engine_edition
            WHEN 5 THEN N'Azure SQL Database'
            WHEN 8 THEN N'Azure SQL Managed Instance'
            WHEN 9 THEN N'Azure SQL Edge'
            ELSE N'Azure SQL (unknown edition)'
        END;
        RAISERROR(N'Platform:    %s (EngineEdition=%d)', 10, 1, @azure_platform, @engine_edition) WITH NOWAIT;

        IF @engine_edition = 5
        BEGIN
            RAISERROR(N'  Note: Azure SQL DB — DTU/vCore impact, no Resource Governor, no incremental stats.', 10, 1) WITH NOWAIT;
            RAISERROR(N'  Consider running during off-peak hours or scaling up temporarily.', 10, 1) WITH NOWAIT;
            SET @warnings += N'AZURE_SQL_DB: DTU/vCore impact, limited feature set; ';
        END
        ELSE IF @engine_edition = 8
        BEGIN
            RAISERROR(N'  Note: Azure SQL MI — most on-prem features supported (incremental stats, RG, etc.).', 10, 1) WITH NOWAIT;
            RAISERROR(N'  vCore consumption still applies during maintenance windows.', 10, 1) WITH NOWAIT;
            SET @warnings += N'AZURE_SQL_MI: vCore impact during maintenance; ';
        END;
    END;

    /*
    Trace flag status (Phase 1.3 - v2.0)
    Show statistics-relevant trace flags if any are active.
    */
    IF @tf_2371_active = 1 OR @tf_2389_active = 1 OR @tf_2390_active = 1 OR @tf_4139_active = 1 OR @tf_9481_active = 1
    BEGIN
        DECLARE @tf_list nvarchar(100) = N'';
        IF @tf_2371_active = 1 SET @tf_list = @tf_list + N'2371,';
        IF @tf_2389_active = 1 SET @tf_list = @tf_list + N'2389,';
        IF @tf_2390_active = 1 SET @tf_list = @tf_list + N'2390,';
        IF @tf_4139_active = 1 SET @tf_list = @tf_list + N'4139,';
        IF @tf_9481_active = 1 SET @tf_list = @tf_list + N'9481,';
        SET @tf_list = LEFT(@tf_list, LEN(@tf_list) - 1); /* Remove trailing comma */
        RAISERROR(N'TraceFlags:  %s (stats-relevant)', 10, 1, @tf_list) WITH NOWAIT;
    END;

    /*
    SQL 2022 AUTO_DROP note (Phase 1.2 - v2.0)
    */
    IF @supports_auto_drop = 1
        RAISERROR(N'AUTO_DROP:   Available (SQL 2022+) - stats auto-drop on schema change by default', 10, 1) WITH NOWAIT;

    /* #173: Linux case-sensitive collation warning */
    DECLARE @server_collation nvarchar(128) = CONVERT(nvarchar(128), SERVERPROPERTY(N'Collation'));
    IF @server_collation LIKE N'%_CS_%'
    BEGIN
        RAISERROR(N'Collation:   %s (CASE-SENSITIVE)', 10, 1, @server_collation) WITH NOWAIT;
        RAISERROR(N'  Note: Case-sensitive collation — object name matching in @Tables, @ExcludeTables,', 10, 1) WITH NOWAIT;
        RAISERROR(N'  @Statistics, @ExcludeStatistics uses COLLATE DATABASE_DEFAULT. Ensure filter', 10, 1) WITH NOWAIT;
        RAISERROR(N'  values match the exact case of database object names.', 10, 1) WITH NOWAIT;
        SET @warnings += N'CASE_SENSITIVE_COLLATION: ' + @server_collation + N'; ';
    END;

    RAISERROR(N'Procedure:   %s', 10, 1, @procedure_version) WITH NOWAIT;
    RAISERROR(N'Start time:  %s', 10, 1, @start_time_display) WITH NOWAIT;

    /* P3d (v2.4): Show execute mode in banner — always visible including dry runs */
    DECLARE @execute_mode_display nvarchar(60) = CASE @Execute WHEN N'N' THEN N'DRY RUN — no updates will be executed' ELSE N'EXECUTE' END;
    RAISERROR(N'Mode:        %s', 10, 1, @execute_mode_display) WITH NOWAIT;

    /*
    Show database count and list if Debug mode
    */
    DECLARE @Databases_display nvarchar(max) = ISNULL(@Databases, N'(current: ' + DB_NAME() + N')');
    RAISERROR(N'Databases:   %d selected', 10, 1, @database_count) WITH NOWAIT;

    IF @ag_secondary_count > 0
    BEGIN
        RAISERROR(N'AG Warning:  %d database(s) excluded (secondary replicas)', 10, 1, @ag_secondary_count) WITH NOWAIT;
    END;

    RAISERROR(N'', 10, 1) WITH NOWAIT;
    RAISERROR(N'Parameters:', 10, 1) WITH NOWAIT;
    RAISERROR(N'  @Databases               = %s', 10, 1, @Databases_display) WITH NOWAIT;
    RAISERROR(N'  @Tables                  = %s', 10, 1, @Tables_display) WITH NOWAIT;
    RAISERROR(N'  @TargetNorecompute       = %s', 10, 1, @TargetNorecompute) WITH NOWAIT;
    RAISERROR(N'  @ModificationThreshold   = %I64d', 10, 1, @ModificationThreshold) WITH NOWAIT;
    IF @ModificationPercent IS NOT NULL
    BEGIN
        DECLARE @ModPctDisplay nvarchar(20) = CONVERT(nvarchar(20), @ModificationPercent);
        RAISERROR(N'  @ModificationPercent     = %s', 10, 1, @ModPctDisplay) WITH NOWAIT;
    END;

    /*
    Bit parameters must be cast to integer for RAISERROR display
    */
    DECLARE
        @TieredThresholds_int integer = @TieredThresholds,
        @UpdateIncremental_int integer = @UpdateIncremental,
        @FailFast_int integer = @FailFast,
        @Debug_int integer = @Debug;

    IF @Preset IS NOT NULL
        RAISERROR(N'  @Preset                  = %s', 10, 1, @Preset) WITH NOWAIT;
    RAISERROR(N'  @TieredThresholds        = %d', 10, 1, @TieredThresholds_int) WITH NOWAIT;
    RAISERROR(N'  @ThresholdLogic          = %s', 10, 1, @ThresholdLogic) WITH NOWAIT;
    IF @DaysStaleThreshold IS NOT NULL
    BEGIN
        RAISERROR(N'  @DaysStaleThreshold      = %d', 10, 1, @DaysStaleThreshold) WITH NOWAIT;
    END;
    RAISERROR(N'  @MinPageCount            = %I64d', 10, 1, @MinPageCount) WITH NOWAIT;
    RAISERROR(N'  @IncludeSystemObjects    = %s', 10, 1, @IncludeSystemObjects) WITH NOWAIT;
    IF @StatisticsSample IS NOT NULL
    BEGIN
        RAISERROR(N'  @StatisticsSample        = %d%%', 10, 1, @StatisticsSample) WITH NOWAIT;
    END;
    RAISERROR(N'  @UpdateIncremental       = %d', 10, 1, @UpdateIncremental_int) WITH NOWAIT;
    RAISERROR(N'  @TimeLimit               = %s seconds', 10, 1, @TimeLimit_display) WITH NOWAIT;
    RAISERROR(N'  @BatchLimit              = %s stats', 10, 1, @BatchLimit_display) WITH NOWAIT;
    RAISERROR(N'  @MaxConsecutiveFailures  = %s', 10, 1, @MaxConsecutiveFailures_display) WITH NOWAIT;
    IF @MaxAGRedoQueueMB IS NOT NULL
    BEGIN
        RAISERROR(N'  @MaxAGRedoQueueMB        = %d MB', 10, 1, @MaxAGRedoQueueMB) WITH NOWAIT;
        RAISERROR(N'  @MaxAGWaitMinutes        = %d', 10, 1, @MaxAGWaitMinutes) WITH NOWAIT;
    END;
    IF @MinTempdbFreeMB IS NOT NULL
    BEGIN
        DECLARE @MinTempdbFreeMB_display nvarchar(20) = CONVERT(nvarchar(20), @MinTempdbFreeMB);
        RAISERROR(N'  @MinTempdbFreeMB         = %s MB', 10, 1, @MinTempdbFreeMB_display) WITH NOWAIT;
    END;
    RAISERROR(N'  @LockTimeout             = %s seconds', 10, 1, @LockTimeout_display) WITH NOWAIT;
    RAISERROR(N'  @SortOrder               = %s', 10, 1, @SortOrder) WITH NOWAIT;
    RAISERROR(N'  @StatsInParallel         = %s', 10, 1, @StatsInParallel) WITH NOWAIT;
    RAISERROR(N'  @Execute                 = %s', 10, 1, @Execute) WITH NOWAIT;
    RAISERROR(N'  @FailFast                = %d', 10, 1, @FailFast_int) WITH NOWAIT;
    IF @ExcludeTables IS NOT NULL
        RAISERROR(N'  @ExcludeTables           = %s', 10, 1, @ExcludeTables) WITH NOWAIT;
    IF @ExcludeStatistics IS NOT NULL
        RAISERROR(N'  @ExcludeStatistics       = %s', 10, 1, @ExcludeStatistics) WITH NOWAIT;
    IF @LongRunningThresholdMinutes IS NOT NULL
    BEGIN
        RAISERROR(N'  @LongRunningThreshold    = %d minutes', 10, 1, @LongRunningThresholdMinutes) WITH NOWAIT;
        RAISERROR(N'  @LongRunningSamplePct    = %d%%', 10, 1, @LongRunningSamplePercent) WITH NOWAIT;
    END;

    /*
    Query Store parameters (when enabled)
    */
    IF @QueryStorePriority = N'Y'
    BEGIN
        RAISERROR(N'  @QueryStorePriority      = %s', 10, 1, @QueryStorePriority) WITH NOWAIT;
        RAISERROR(N'  @QueryStoreMetric        = %s', 10, 1, @QueryStoreMetric) WITH NOWAIT;
        RAISERROR(N'  @QueryStoreMinExecutions = %I64d', 10, 1, @QueryStoreMinExecutions) WITH NOWAIT;
        RAISERROR(N'  @QueryStoreRecentHours   = %d', 10, 1, @QueryStoreRecentHours) WITH NOWAIT;

        /* #189: Pre-run QS READ_ONLY warning — alert DBA before discovery, not after */
        DECLARE @qs_readonly_count int = 0;
        SELECT @qs_readonly_count = COUNT(*)
        FROM @tmpDatabases AS td
        WHERE td.Selected = 1
        AND EXISTS (
            SELECT 1
            FROM sys.databases AS d
            WHERE d.name = td.DatabaseName COLLATE DATABASE_DEFAULT
            AND   d.is_query_store_on = 1
        );
        /* Note: actual_state check requires per-database context (done in Phase 6).
           This is a lighter pre-check using sys.databases.is_query_store_on. */
        IF @qs_readonly_count > 0
            RAISERROR(N'  Note: QS state per-database checked during Phase 6. READ_ONLY databases may yield stale priority data.', 10, 1) WITH NOWAIT;
    END;

    /*
    Additional parameters (when non-default or relevant)
    */
    RAISERROR(N'  @GroupByJoinPattern      = %s', 10, 1, @GroupByJoinPattern) WITH NOWAIT;
    IF @FilteredStatsMode <> N'INCLUDE'
        RAISERROR(N'  @FilteredStatsMode       = %s', 10, 1, @FilteredStatsMode) WITH NOWAIT;
    IF @MaxDOP IS NOT NULL
        RAISERROR(N'  @MaxDOP                  = %d', 10, 1, @MaxDOP) WITH NOWAIT;
    IF @DelayBetweenStats IS NOT NULL
        RAISERROR(N'  @DelayBetweenStats       = %d seconds', 10, 1, @DelayBetweenStats) WITH NOWAIT;
    RAISERROR(N'  @LogToTable              = %s', 10, 1, @LogToTable) WITH NOWAIT;
    RAISERROR(N'  @CleanupOrphanedRuns     = %s', 10, 1, @CleanupOrphanedRuns) WITH NOWAIT;
    RAISERROR(N'  @Debug                   = %d', 10, 1, @Debug_int) WITH NOWAIT;
    IF @ExposeProgressToAllSessions = N'Y'
        RAISERROR(N'  @ExposeProgressToAllSess = %s', 10, 1, @ExposeProgressToAllSessions) WITH NOWAIT;
    IF @StatsInParallel = N'Y' AND @DeadWorkerTimeoutMinutes IS NOT NULL
        RAISERROR(N'  @DeadWorkerTimeout       = %d minutes', 10, 1, @DeadWorkerTimeoutMinutes) WITH NOWAIT;

    /*
    Threshold Interaction Explanation (v1.9, debug mode only)
    Helps users understand how the threshold parameters work together.
    Only shown in discovery mode (when neither @Statistics nor @StatisticsFromTable specified).
    */
    IF @Debug = 1 AND @Statistics IS NULL AND @StatisticsFromTable IS NULL
    BEGIN
        DECLARE @mod_pct_str nvarchar(20) = CONVERT(nvarchar(20), ISNULL(@ModificationPercent, 0));

        RAISERROR(N'', 10, 1) WITH NOWAIT;
        RAISERROR(N'Threshold logic explanation:', 10, 1) WITH NOWAIT;
        IF @TieredThresholds = 1
        BEGIN
            RAISERROR(N'  @TieredThresholds=1: Stats qualify if mod_count >= tier threshold OR sqrt threshold', 10, 1) WITH NOWAIT;
            RAISERROR(N'    Tier thresholds: 0-500 rows=500 mods, 501-10K=20%%, 10K-100K=15%%, 100K-1M=10%%, 1M+=5%%', 10, 1) WITH NOWAIT;
            RAISERROR(N'    @ModificationThreshold=%I64d acts as floor (only affects large tables)', 10, 1, @ModificationThreshold) WITH NOWAIT;
        END;
        ELSE IF @ModificationPercent IS NOT NULL
        BEGIN
            RAISERROR(N'  @TieredThresholds=0: Using SQRT formula: mod_count >= %s * SQRT(row_count)', 10, 1, @mod_pct_str) WITH NOWAIT;
        END;
        ELSE
        BEGIN
            RAISERROR(N'  @TieredThresholds=0: Using fixed threshold: mod_count >= %I64d', 10, 1, @ModificationThreshold) WITH NOWAIT;
        END;

        IF @DaysStaleThreshold IS NOT NULL
        BEGIN
            IF @ThresholdLogic = N'OR'
                RAISERROR(N'  OR days since update >= %d', 10, 1, @DaysStaleThreshold) WITH NOWAIT;
            ELSE
                RAISERROR(N'  AND days since update >= %d', 10, 1, @DaysStaleThreshold) WITH NOWAIT;
        END;
    END;

    /*
    Hardware context and warning collection (always runs for @WarningsOut)
    RAISERROR output gated behind @Debug; warning collection always executes.
    */
    DECLARE
        @hw_cpu_count int,
        @hw_memory_mb bigint,
        @hw_numa_nodes int,
        @hw_uptime_hours int,
        /* P1d fix (v2.4): process-level memory and visible schedulers for container awareness */
        @process_memory_kb bigint,     /* SQL Server process memory (container limit, not host RAM) */
        @visible_schedulers int,       /* Online schedulers visible to SQL (may differ from cpu_count in containers) */
        /* #208: container memory flag — set always, not just in debug mode */
        @is_container_memory bit = 0;  /* 1 = SQL process memory differs >20% from host physical_memory_kb */

    SELECT
        @hw_cpu_count = cpu_count,
        @hw_memory_mb = physical_memory_kb / 1024,
        @hw_numa_nodes = numa_node_count,
        @hw_uptime_hours = DATEDIFF(HOUR, sqlserver_start_time, SYSDATETIME()) /* P1d: SQL Server uptime, not OS uptime */
    FROM sys.dm_os_sys_info;

    /* P1d: Process memory from sys.dm_os_process_memory (reflects container memory limit) */
    SELECT @process_memory_kb = physical_memory_in_use_kb
    FROM sys.dm_os_process_memory;

    /* P1d: Visible online schedulers (may be less than cpu_count in container deployments) */
    SELECT @visible_schedulers = COUNT(*)
    FROM sys.dm_os_schedulers
    WHERE status = N'VISIBLE ONLINE';

    IF @hw_uptime_hours < 24
        SET @warnings += N'LOW_UPTIME: SQL Server restarted < 24h ago; ';

    DECLARE @active_backups int = 0;
    SELECT @active_backups = COUNT(*)
    FROM sys.dm_exec_requests AS r
    WHERE r.command LIKE N'BACKUP%';

    IF @active_backups > 0
        SET @warnings += N'BACKUP_RUNNING: ' + CONVERT(nvarchar(10), @active_backups) + N' backup(s) active; ';

    /* #184: Peak hours plan cache warning — UPDATE STATISTICS clears plan cache entries
       for affected tables, which can cause recompilations during peak load. */
    DECLARE @current_hour int = DATEPART(HOUR, SYSDATETIME());
    IF @current_hour >= 8 AND @current_hour < 18
    BEGIN
        RAISERROR(N'WARNING: Running during business hours (%d:00). UPDATE STATISTICS clears plan cache', 10, 1, @current_hour) WITH NOWAIT;
        RAISERROR(N'  entries for affected tables — expect query recompilations. Consider scheduling off-peak.', 10, 1) WITH NOWAIT;
        SET @warnings += N'PEAK_HOURS: running at ' + CONVERT(nvarchar(5), @current_hour) + N':00 (plan cache impact); ';
    END;

    /*
    #208: Container memory detection — always runs, not gated on @Debug.
    physical_memory_kb in sys.dm_os_sys_info reflects the *host* physical RAM.
    Inside a Linux container with a cgroup memory limit (e.g. 4 GB on a 256 GB host)
    this value is misleading for capacity planning and can trigger incorrect warnings.

    Detection: SQL process memory (dm_os_process_memory.physical_memory_in_use_kb)
    will diverge significantly from host physical_memory_kb when a container limit is active.
    A >20% divergence is used as the threshold (same heuristic as previous debug-only note).

    WARNING is always emitted (not just debug) and added to @WarningsOut so automation
    can detect it programmatically. The diagnostic note in the debug banner is also
    upgraded from "Note" to a labelled WARNING when the flag is set.
    */
    IF @process_memory_kb IS NOT NULL
    AND @hw_memory_mb > 0
    AND ABS(1.0 - CONVERT(float, @process_memory_kb) / CONVERT(float, @hw_memory_mb * 1024)) > 0.20
    BEGIN
        SET @is_container_memory = 1;
        DECLARE @host_ram_gb bigint = @hw_memory_mb / 1024;
        DECLARE @process_rss_mb bigint = @process_memory_kb / 1024;
        DECLARE @container_warn nvarchar(2000) =
            N'WARNING: Container detected — OOMKill risk. Host RAM: '
            + CONVERT(nvarchar(20), @host_ram_gb) + N' GB, SQL process RSS: '
            + CONVERT(nvarchar(20), @process_rss_mb) + N' MB. '
            + N'Configure max server memory based on container cgroup limit, not host RAM.'
            + CASE WHEN @visible_schedulers <> @hw_cpu_count
                   THEN N' CPU mismatch: ' + CONVERT(nvarchar(10), @visible_schedulers)
                        + N' visible schedulers vs ' + CONVERT(nvarchar(10), @hw_cpu_count)
                        + N' host cores — verify --cpus container flag.'
                   ELSE N''
              END
            + N' (#208, #247)';
        RAISERROR(@container_warn, 10, 1) WITH NOWAIT;
        SET @warnings += N'CONTAINER_MEMORY: OOMKill risk — host RAM '
            + CONVERT(nvarchar(20), @host_ram_gb) + N' GB, process RSS '
            + CONVERT(nvarchar(20), @process_rss_mb) + N' MB; configure max server memory from cgroup limit; ';
    END;

    /* #251: Advisory — suggest index on CommandLog.StartTime when retention window is large */
    IF  @commandlog_exists = 1
    AND @CommandLogRetentionDays > 30
    AND NOT EXISTS (
        SELECT 1
        FROM sys.indexes AS i
        INNER JOIN sys.index_columns AS ic ON ic.object_id = i.object_id AND ic.index_id = i.index_id
        INNER JOIN sys.columns AS c ON c.object_id = ic.object_id AND c.column_id = ic.column_id
        WHERE i.object_id = OBJECT_ID(N'dbo.CommandLog')
        AND   c.name = N'StartTime'
        AND   ic.key_ordinal = 1
    )
    BEGIN
        RAISERROR(N'INFO: @CommandLogRetentionDays=%d — consider adding an index on dbo.CommandLog(StartTime) for faster history lookups. (#251)', 10, 1, @CommandLogRetentionDays) WITH NOWAIT;
    END;

    /*
    Trace flag status and hardware context in debug mode (Phase 1.3 - v2.0)
    Show active statistics-relevant trace flags and recommendations.
    */
    IF @Debug = 1
    BEGIN
        RAISERROR(N'', 10, 1) WITH NOWAIT;
        IF LEN(@tf_warnings) > 0
        BEGIN
            RAISERROR(N'Statistics-Relevant Trace Flags: Active', 10, 1) WITH NOWAIT;
            RAISERROR(N'  %s', 10, 1, @tf_warnings) WITH NOWAIT;
        END
        ELSE
        BEGIN
            RAISERROR(N'Statistics-Relevant Trace Flags: None active', 10, 1) WITH NOWAIT;
        END;

        RAISERROR(N'', 10, 1) WITH NOWAIT;
        RAISERROR(N'Environment (hardware context):', 10, 1) WITH NOWAIT;
        DECLARE @hw_memory_gb bigint = @hw_memory_mb / 1024;
        RAISERROR(N'  CPU cores: %d (visible schedulers: %d), NUMA nodes: %d, Uptime: %d hours (SQL Server)', 10, 1,
            @hw_cpu_count, @visible_schedulers, @hw_numa_nodes, @hw_uptime_hours) WITH NOWAIT;
        DECLARE
            @proc_memory_mb bigint = @process_memory_kb / 1024,
            @proc_memory_gb bigint = @process_memory_kb / 1024 / 1024;
        RAISERROR(N'  Host memory: %I64d MB (%I64d GB) | Process (SQL) memory: %I64d MB', 10, 1,
            @hw_memory_mb, @hw_memory_gb, @proc_memory_mb) WITH NOWAIT;
        /* #208: Container memory — use flag set above (always-on detection) */
        IF @is_container_memory = 1
            RAISERROR(N'  WARNING: Container memory limit active — host RAM (%I64d GB) reported by physical_memory_kb. SQL process memory in use: %I64d MB. Capacity planning and memory warnings should use process memory, not host RAM. (#208)', 10, 1, @hw_memory_gb, @proc_memory_mb) WITH NOWAIT;

        IF @hw_uptime_hours < 24
            RAISERROR(N'  Note: SQL Server restarted < 24h ago. Query Store/usage stats may be incomplete.', 10, 1) WITH NOWAIT;

        IF @active_backups > 0
            RAISERROR(N'  Warning: %d backup operation(s) currently running. Statistics updates may compete for I/O.', 10, 1, @active_backups) WITH NOWAIT;
    END;

    /*
    v2.7: AG primary detection (#18).
    Query runs always (not just debug) so @MaxAGRedoQueueMB loop check works.
    Also captures initial redo queue for debug banner.
    */
    IF EXISTS
    (
        SELECT 1
        FROM sys.dm_hadr_availability_replica_states AS ars
        WHERE ars.is_local = 1
        AND   ars.role_desc = N'PRIMARY'
    )
    BEGIN
        SET @ag_is_primary = 1;

        SELECT @ag_redo_initial_mb = MAX(drs.redo_queue_size) / 1024.0
        FROM sys.dm_hadr_database_replica_states AS drs
        WHERE drs.is_local = 0
        AND   drs.is_primary_replica = 0;

        IF @ag_redo_initial_mb IS NOT NULL AND @ag_redo_initial_mb > 100
            SET @WarningsOut = ISNULL(@WarningsOut, N'') +
                N'AG_REDO_ELEVATED: Redo queue ' + CONVERT(nvarchar(20), @ag_redo_initial_mb) + N' MB at startup; ';
    END;

    /*
    v2.7: Tempdb free space detection (#34).
    Query runs always for warnings and debug banner.
    */
    SELECT @tempdb_free_mb =
        SUM(unallocated_extent_page_count) * 8 / 1024.0
    FROM tempdb.sys.dm_db_file_space_usage;

    IF @tempdb_free_mb IS NOT NULL AND @tempdb_free_mb < 100
        SET @WarningsOut = ISNULL(@WarningsOut, N'') +
            N'TEMPDB_LOW: Only ' + CONVERT(nvarchar(20), @tempdb_free_mb) + N' MB free at startup; ';

    /*
    v2.5: Resource Governor detection (#35).
    Query runs always (not just debug) so @MaxDOP conflict warning works.
    Display is debug-only; warning is always shown.
    */
    DECLARE
        @rg_workload_group sysname,
        @rg_max_dop int;

    SELECT
        @rg_workload_group = wg.name,
        @rg_max_dop = wg.max_dop
    FROM sys.dm_exec_sessions AS s
    JOIN sys.dm_resource_governor_workload_groups AS wg
      ON wg.group_id = s.group_id
    WHERE s.session_id = @@SPID;

    IF @Debug = 1 AND @rg_workload_group IS NOT NULL
    BEGIN
        IF @rg_max_dop > 0 /* 0 = no RG cap */
            RAISERROR(N'  Resource Governor: workload group [%s], MAX_DOP=%d', 10, 1,
                @rg_workload_group, @rg_max_dop) WITH NOWAIT;
        ELSE
            RAISERROR(N'  Resource Governor: workload group [%s] (no DOP cap)', 10, 1,
                @rg_workload_group) WITH NOWAIT;
    END;

    /* v2.7: AG redo queue and tempdb in debug banner */
    IF @Debug = 1
    BEGIN
        IF @ag_is_primary = 1
        BEGIN
            IF @ag_redo_initial_mb IS NOT NULL
                RAISERROR(N'  AG redo queue:   %I64d MB (max across secondaries at startup)', 10, 1, @ag_redo_initial_mb) WITH NOWAIT;
            ELSE
                RAISERROR(N'  AG primary:      Yes (secondaries offline or no redo data)', 10, 1) WITH NOWAIT;
        END;
        IF @tempdb_free_mb IS NOT NULL
            RAISERROR(N'  Tempdb free:     %I64d MB', 10, 1, @tempdb_free_mb) WITH NOWAIT;
    END;

    /*
    v2.5: Resource Governor @MaxDOP conflict warning (#35).
    Always shown (not just debug) when @MaxDOP > RG MAX_DOP — a real production footgun.
    */
    IF  @MaxDOP IS NOT NULL
    AND @rg_max_dop IS NOT NULL
    BEGIN
        /* #194: When workload group max_dop=0 (uncapped), fall back to server-level MAXDOP */
        DECLARE @effective_max_dop int = @rg_max_dop;
        IF @effective_max_dop = 0
            SELECT @effective_max_dop = CONVERT(int, value_in_use)
            FROM sys.configurations
            WHERE name = N'max degree of parallelism';

        IF  @effective_max_dop > 0
        AND @MaxDOP > @effective_max_dop
        BEGIN
            DECLARE @rg_warn nvarchar(500) =
                N'WARNING: @MaxDOP=' + CONVERT(nvarchar(10), @MaxDOP) +
                CASE WHEN @rg_max_dop = 0
                    THEN N' but server-level MAXDOP=' + CONVERT(nvarchar(10), @effective_max_dop)
                    ELSE N' but Resource Governor workload group [' + @rg_workload_group +
                         N'] caps MAX_DOP=' + CONVERT(nvarchar(10), @effective_max_dop)
                END +
                N'. @MaxDOP hint will be silently capped by SQL Server.';
            RAISERROR(@rg_warn, 10, 1) WITH NOWAIT;

            SET @WarningsOut = ISNULL(@WarningsOut, N'') +
                N'RG_MAXDOP_CAP: RG caps @MaxDOP from ' + CONVERT(nvarchar(10), @MaxDOP) +
                N' to ' + CONVERT(nvarchar(10), @effective_max_dop) + N'; ';
        END;
    END;

    /*
    One-time note when @PersistSamplePercent=Y but no sample rate specified
    (Moved from per-stat loop to reduce noise in debug output)
    */
    IF @Debug = 1 AND @PersistSamplePercent = N'Y' AND @StatisticsSample IS NULL
    BEGIN
        RAISERROR(N'Note: @PersistSamplePercent=Y ignored (no @StatisticsSample specified)', 10, 1) WITH NOWAIT;
    END;

    RAISERROR(N'', 10, 1) WITH NOWAIT;
    /*#endregion 12-HEADER */

    /*#region 13-RUN-INIT: CommandLog START, progress table, orphan cleanup */

    /* #164: Set session context so sp_StatUpdate sessions are identifiable in dm_exec_requests */
    BEGIN TRY
        EXEC sys.sp_set_session_context @key = N'sp_StatUpdate_RunLabel', @value = @run_label, @read_only = 0;
    END TRY
    BEGIN CATCH
        /* sp_set_session_context may not be available on all versions/editions — silently skip */
        IF @Debug = 1
            RAISERROR(N'  Note: sp_set_session_context not available — session context identifier not set.', 10, 1) WITH NOWAIT;
    END CATCH;

    /*
    ============================================================================
    LOG RUN_HEADER TO COMMANDLOG
    ============================================================================
    */
    IF  @LogToTable = N'Y'
    AND @Execute = N'Y'
    AND @commandlog_exists = 1
    BEGIN
        DECLARE
            @parameters_xml xml =
            (
                SELECT
                    /* Identity */
                    @procedure_version AS [Version],
                    @run_label AS RunLabel,
                    @@SPID AS SessionID,

                    /* Scope & targeting */
                    @Preset AS Preset,
                    @Databases AS [Databases],
                    @database_count AS DatabaseCount,
                    @Tables AS [Tables],
                    @ExcludeTables AS ExcludeTables,
                    @ExcludeStatistics AS ExcludeStatistics,
                    @Statistics AS [Statistics],
                    @StatisticsFromTable AS StatisticsFromTable,
                    @TargetNorecompute AS TargetNorecompute,
                    @IncludeSystemObjects AS IncludeSystemObjects,
                    @IncludeIndexedViews AS IncludeIndexedViews,
                    @SkipTablesWithColumnstore AS SkipTablesWithColumnstore,
                    @TemporalCoSchedule AS TemporalCoSchedule,
                    @AscendingKeyBoost AS AscendingKeyBoost,

                    /* Thresholds */
                    @ModificationThreshold AS ModificationThreshold,
                    @ModificationPercent AS ModificationPercent,
                    @TieredThresholds AS TieredThresholds,
                    @ThresholdLogic AS ThresholdLogic,
                    @DaysStaleThreshold AS DaysStaleThreshold,
                    @HoursStaleThreshold AS HoursStaleThreshold,
                    @MinPageCount AS MinPageCount,

                    /* Filtered stats */
                    @FilteredStatsMode AS FilteredStatsMode,
                    @FilteredStatsStaleFactor AS FilteredStatsStaleFactor,

                    /* Query Store */
                    @QueryStorePriority AS QueryStorePriority,
                    @QueryStoreMetric AS QueryStoreMetric,
                    @QueryStoreMinExecutions AS QueryStoreMinExecutions,
                    @QueryStoreRecentHours AS QueryStoreRecentHours,

                    /* Update behavior */
                    @StatisticsSample AS StatisticsSample,
                    @PersistSamplePercent AS PersistSamplePercent,
                    @PersistSampleMinRows AS PersistSampleMinRows,
                    @MaxDOP AS MaxDOP,
                    @MaxGrantPercent AS MaxGrantPercent,
                    @UpdateIncremental AS UpdateIncremental,

                    /* Execution control */
                    @TimeLimit AS TimeLimit,
                    @StopByTime AS StopByTime,
                    @MaxSecondsPerStat AS MaxSecondsPerStat,
                    @BatchLimit AS BatchLimit,
                    @SortOrder AS SortOrder,
                    @DelayBetweenStats AS DelayBetweenStats,
                    @MaxConsecutiveFailures AS MaxConsecutiveFailures,
                    @FailFast AS FailFast,

                    /* Join pattern */
                    @GroupByJoinPattern AS GroupByJoinPattern,
                    @JoinPatternMinExecutions AS JoinPatternMinExecutions,

                    /* Adaptive sampling */
                    @LongRunningThresholdMinutes AS LongRunningThresholdMinutes,
                    @LongRunningSamplePercent AS LongRunningSamplePercent,

                    /* Environmental safety */
                    @MaxAGRedoQueueMB AS MaxAGRedoQueueMB,
                    @MaxAGWaitMinutes AS MaxAGWaitMinutes,
                    @MinTempdbFreeMB AS MinTempdbFreeMB,

                    /* Discovery & performance */
                    @StagedDiscovery AS StagedDiscovery,
                    @CollectHeapForwarding AS CollectHeapForwarding,

                    /* Logging & output */
                    @LockTimeout AS LockTimeout,
                    @LogToTable AS LogToTable,
                    @LogSkippedToCommandLog AS LogSkippedToCommandLog,
                    @ProgressLogInterval AS ProgressLogInterval,
                    @ReturnDetailedResults AS ReturnDetailedResults,
                    @CompletionNotifyTable AS CompletionNotifyTable,

                    /* Parallel */
                    @StatsInParallel AS StatsInParallel,
                    @MaxWorkers AS MaxWorkers,
                    @DeadWorkerTimeoutMinutes AS DeadWorkerTimeoutMinutes,

                    /* Cleanup */
                    @CleanupOrphanedRuns AS CleanupOrphanedRuns,
                    @OrphanedRunThresholdHours AS OrphanedRunThresholdHours,
                    @CommandLogRetentionDays AS CommandLogRetentionDays,

                    /* Meta / diagnostic (#242) */
                    @Execute AS [Execute],
                    @Debug AS [Debug],
                    @CheckPermissionsOnly AS CheckPermissionsOnly,
                    @WhatIfOutputTable AS WhatIfOutputTable,
                    @ExposeProgressToAllSessions AS ExposeProgressToAllSessions
                FOR
                    XML RAW(N'Parameters'),
                    ELEMENTS XSINIL
            );

        /*
        START marker must succeed - abort if it fails
        This ensures SP_STATUPDATE_START is always the first entry for any run
        */
        INSERT INTO
            dbo.CommandLog
        (
            DatabaseName,
            SchemaName,
            ObjectName,
            ObjectType,
            Command,
            CommandType,
            StartTime,
            ExtendedInfo
        )
        VALUES
        (
            ISNULL(@Databases, DB_NAME()),
            N'dbo',
            N'sp_StatUpdate',
            N'P',
            N'EXECUTE dbo.sp_StatUpdate @Databases = N''' + ISNULL(@Databases, DB_NAME()) + N''''
                + CASE WHEN @Tables IS NOT NULL THEN N', @Tables = N''' + @Tables + N'''' ELSE N'' END
                + CASE WHEN @Statistics IS NOT NULL THEN N', @Statistics = N''' + @Statistics + N'''' ELSE N'' END
                + N', @TimeLimit = ' + CONVERT(nvarchar(10), @TimeLimit)
                + N', @SortOrder = N''' + @SortOrder + N''''
                + CASE WHEN @QueryStorePriority = N'Y' THEN N', @QueryStorePriority = N''Y'', @QueryStoreMetric = N''' + @QueryStoreMetric + N'''' ELSE N'' END
                + N';',
            N'SP_STATUPDATE_START',
            @start_time,
            @parameters_xml
        );

        RAISERROR(N'Run: %s (logged to CommandLog)', 10, 1, @run_label) WITH NOWAIT;
        RAISERROR(N'', 10, 1) WITH NOWAIT;
    END;

    /*
    ============================================================================
    GLOBAL TEMP TABLE FOR REAL-TIME PROGRESS MONITORING (v1.9)
    ============================================================================
    Create ##sp_StatUpdate_Progress table for external monitoring.
    Query from another session: SELECT * FROM ##sp_StatUpdate_Progress
    Table is auto-dropped when the session ends.

    SECURITY NOTE: Global temp tables are visible to ALL sessions on the server.
    This is opt-in via @ExposeProgressToAllSessions = 'Y' because it exposes
    database/table names to anyone who can query tempdb. For secure monitoring,
    use @ProgressLogInterval which writes to CommandLog (access-controlled).
    */
    IF @Execute = N'Y' AND @ExposeProgressToAllSessions = N'Y'
    BEGIN
        /* Create unique progress table name using run_label for multiple concurrent runs */
        DECLARE @progress_table_name nvarchar(128) = N'##sp_StatUpdate_Progress';

        /* #186: Clean stale rows from dead sessions before creating/re-creating */
        IF OBJECT_ID('tempdb..' + @progress_table_name, 'U') IS NOT NULL
        BEGIN
            /* Mark rows from dead sessions so monitoring tools see them as stale */
            DECLARE @cleanup_spid nvarchar(10) = CONVERT(nvarchar(10), @@SPID);
            EXECUTE (N'
                UPDATE ' + @progress_table_name + N'
                SET    Status = N''SESSION_DIED'',
                       CurrentStat = N''(session no longer active)''
                WHERE  SessionID NOT IN (SELECT session_id FROM sys.dm_exec_sessions)
                AND    Status <> N''SESSION_DIED'';

                DELETE FROM ' + @progress_table_name + N'
                WHERE  SessionID = ' + @cleanup_spid + N';
            ');
        END;

        /* Drop and recreate for this session (original row was deleted above) */
        IF OBJECT_ID('tempdb..' + @progress_table_name, 'U') IS NOT NULL
            EXECUTE (N'DROP TABLE ' + @progress_table_name);

        EXECUTE (N'
            CREATE TABLE ' + @progress_table_name + N' (
                RunLabel nvarchar(100) NOT NULL,
                StartTime datetime2(3) NOT NULL,
                CurrentTime datetime2(3) NOT NULL,
                SessionID int NOT NULL,
                StatsFound int NOT NULL DEFAULT 0,
                StatsProcessed int NOT NULL DEFAULT 0,
                StatsSucceeded int NOT NULL DEFAULT 0,
                StatsFailed int NOT NULL DEFAULT 0,
                CurrentDatabase sysname NULL,
                CurrentTable sysname NULL,
                CurrentStat sysname NULL,
                ElapsedSeconds int NOT NULL DEFAULT 0,
                Status nvarchar(20) NOT NULL DEFAULT N''RUNNING'',
                CONSTRAINT PK_sp_StatUpdate_Progress PRIMARY KEY (RunLabel)
            )
        ');

        /* Insert initial row using sp_executesql with parameters */
        DECLARE @progress_insert_sql nvarchar(500) = N'
            INSERT INTO ' + @progress_table_name + N' (RunLabel, StartTime, CurrentTime, SessionID)
            VALUES (@rl, @st, SYSDATETIME(), @sid)';

        EXEC sys.sp_executesql
            @progress_insert_sql,
            N'@rl nvarchar(100), @st datetime2(3), @sid int',
            @rl = @run_label,
            @st = @start_time,
            @sid = @@SPID;

        IF @Debug = 1
        BEGIN
            RAISERROR(N'Progress table created: %s (query from another session to monitor)', 10, 1, @progress_table_name) WITH NOWAIT;
        END;
    END;

    /*
    ============================================================================
    CLEANUP ORPHANED RUNS (runs that started but never ended - killed jobs)
    ============================================================================
    When @CleanupOrphanedRuns = 'Y', find SP_STATUPDATE_START entries without
    matching SP_STATUPDATE_END and insert END markers with StopReason='KILLED'.
    This helps with run analysis and prevents orphaned entries from accumulating.

    v1.9: Added 24-hour threshold to avoid interfering with concurrent runs.
    Only orphans >24h old are cleaned - this avoids marking concurrent runs
    (that are still actively running) as KILLED.
    */
    IF  @CleanupOrphanedRuns = N'Y'
    AND @LogToTable = N'Y'
    AND @commandlog_exists = 1
    BEGIN
        DECLARE @orphaned_count int = 0;

        /*
        Insert SP_STATUPDATE_END for each orphaned SP_STATUPDATE_START
        Match on RunLabel from ExtendedInfo XML to identify the specific run.
        Only clean up entries older than 24 hours to avoid interfering with
        concurrent runs that are still in progress.
        */
        INSERT INTO dbo.CommandLog
        (
            DatabaseName,
            SchemaName,
            ObjectName,
            ObjectType,
            Command,
            CommandType,
            StartTime,
            EndTime,
            ExtendedInfo
        )
        SELECT
            cl_start.DatabaseName,
            N'dbo',
            N'sp_StatUpdate',
            N'P',
            N'sp_StatUpdate killed (orphaned run cleanup)',
            N'SP_STATUPDATE_END',
            cl_start.StartTime,
            SYSDATETIME(),
            (
                SELECT
                    cl_start.ExtendedInfo.value('(/Parameters/Version)[1]', 'nvarchar(20)') AS [Version],
                    cl_start.ExtendedInfo.value('(/Parameters/RunLabel)[1]', 'nvarchar(100)') AS RunLabel,
                    0 AS StatsFound,
                    0 AS StatsProcessed,
                    0 AS StatsSucceeded,
                    0 AS StatsFailed,
                    0 AS StatsRemaining,
                    0 AS DurationSeconds,
                    N'KILLED' AS StopReason
                FOR XML RAW(N'Summary'), ELEMENTS
            )
        FROM dbo.CommandLog AS cl_start
        WHERE cl_start.CommandType = N'SP_STATUPDATE_START'
        /* #148: Only clean orphans older than @OrphanedRunThresholdHours (avoids concurrent run interference) */
        AND   cl_start.StartTime < DATEADD(HOUR, -@OrphanedRunThresholdHours, SYSDATETIME())
        /* Must have ExtendedInfo with RunLabel to avoid NULL=NULL matching */
        AND   cl_start.ExtendedInfo IS NOT NULL
        AND   cl_start.ExtendedInfo.exist('(/Parameters/RunLabel)[1]') = 1
        AND   NOT EXISTS
              (
                  SELECT 1
                  FROM dbo.CommandLog AS cl_end
                  WHERE cl_end.CommandType = N'SP_STATUPDATE_END'
                  AND   cl_end.ExtendedInfo.value('(/Summary/RunLabel)[1]', 'nvarchar(100)') =
                        cl_start.ExtendedInfo.value('(/Parameters/RunLabel)[1]', 'nvarchar(100)')
              );

        SELECT @orphaned_count = @@ROWCOUNT;

        IF @orphaned_count > 0
        BEGIN
            RAISERROR(N'Cleaned up %d orphaned run(s) from CommandLog', 10, 1, @orphaned_count) WITH NOWAIT;
            RAISERROR(N'', 10, 1) WITH NOWAIT;
        END;
    END;
    /*#endregion 13-RUN-INIT */

    /*#region 14-PRE-DISCOVERY: Adaptive sampling cache, mode selection */
    /*
    ============================================================================
    QUERY COMMANDLOG FOR LONG-RUNNING STATS (adaptive sampling)
    ============================================================================
    */
    IF  @LongRunningThresholdMinutes IS NOT NULL
    AND @commandlog_exists = 1
    BEGIN
        /*
        Find stats that historically took longer than @LongRunningThresholdMinutes.
        These will get a forced sample rate of @LongRunningSamplePercent.
        Also includes stats that were killed (EndTime IS NULL but ErrorNumber set).
        Uses CTE to extract stat name from XML before GROUP BY (XML methods not allowed in GROUP BY).

        LIMITATION: We don't know WHY stats were slow - could be table size, I/O
        contention, blocking, or high sample rate. Wall-clock time is the best
        available proxy. Consider XE session (tools/sp_StatUpdate_XE_Session.sql)
        for deeper analysis.
        */
        ;WITH long_running_candidates AS
        (
            SELECT
                database_name = cl.DatabaseName,
                schema_name = cl.SchemaName,
                table_name = cl.ObjectName,
                stat_name = COALESCE(
                    cl.ExtendedInfo.value('(/StatInfo/StatisticName)[1]', 'sysname'),
                    cl.StatisticsName,
                    cl.IndexName
                ),
                duration_minutes = DATEDIFF(MINUTE, cl.StartTime, ISNULL(cl.EndTime, SYSDATETIME())),
                start_time = cl.StartTime
            FROM dbo.CommandLog AS cl
            WHERE cl.CommandType = N'UPDATE_STATISTICS'
            AND   (
                      /*Stats that exceeded threshold*/
                      DATEDIFF(MINUTE, cl.StartTime, ISNULL(cl.EndTime, SYSDATETIME())) >= @LongRunningThresholdMinutes
                      /*Or stats that were killed/failed (EndTime NULL but error exists)*/
                      OR (cl.EndTime IS NULL AND cl.ErrorNumber IS NOT NULL)
                  )
        )
        INSERT INTO @long_running_stats
        (
            database_name,
            schema_name,
            table_name,
            stat_name,
            max_duration_minutes,
            last_occurrence,
            occurrence_count
        )
        SELECT
            database_name,
            schema_name,
            table_name,
            stat_name,
            max_duration_minutes = MAX(duration_minutes),
            last_occurrence = MAX(start_time),
            occurrence_count = COUNT(*)
        FROM long_running_candidates
        WHERE stat_name IS NOT NULL
        GROUP BY
            database_name,
            schema_name,
            table_name,
            stat_name;

        DECLARE @long_running_count int = (SELECT COUNT(*) FROM @long_running_stats);

        IF @long_running_count > 0
        BEGIN
            DECLARE @lr_msg nvarchar(500);
            SET @lr_msg = N'Adaptive Sampling: Found ' + CONVERT(nvarchar(10), @long_running_count) +
                          N' stats with historical duration >= ' + CONVERT(nvarchar(10), @LongRunningThresholdMinutes) +
                          N' min (will use ' + CONVERT(nvarchar(10), @LongRunningSamplePercent) + N'%% sample)';
            RAISERROR(@lr_msg, 10, 1) WITH NOWAIT;
            RAISERROR(N'', 10, 1) WITH NOWAIT;
        END;
    END;

    /*
    ============================================================================
    DETERMINE MODE: DIRECT (table), DIRECT (string), or DISCOVERY
    ============================================================================
    */
    DECLARE
        @mode nvarchar(20) =
            CASE
                WHEN @StatisticsFromTable IS NOT NULL
                THEN N'DIRECT_TABLE'
                WHEN @Statistics IS NOT NULL
                THEN N'DIRECT_STRING'
                ELSE N'DISCOVERY'
            END;

    RAISERROR(N'Mode: %s', 10, 1, @mode) WITH NOWAIT;
    RAISERROR(N'', 10, 1) WITH NOWAIT;

    /*
    P2b fix (v2.4): Lightweight QS forced plan inventory check.
    Runs unconditionally when Query Store is enabled (not gated on @QueryStorePriority).
    Most users never set @QueryStorePriority=Y — this ensures the INFO message is visible.
    This is informational only — not a stop condition.
    */
    IF EXISTS (SELECT 1 FROM sys.database_query_store_options WHERE actual_state IN (1, 2))
    BEGIN
        DECLARE @fp_count INT = 0;
        SELECT @fp_count = COUNT(*) FROM sys.query_store_plan WHERE is_forced_plan = 1 AND force_failure_count = 0;
        IF @fp_count > 0
            RAISERROR(N'[sp_StatUpdate] INFO: %d forced plan(s) in Query Store. Use @QueryStorePriority=''Y'' to prioritize affected stats.', 0, 1, @fp_count) WITH NOWAIT;
    END;

    /*#endregion 14-PRE-DISCOVERY */

    /*#region 15-DIRECT-MODE: Mode 1: DIRECT_TABLE and DIRECT_STRING */
    /*
    ============================================================================
    MODE 1A: DIRECT_TABLE - Read from temp/permanent table
    ============================================================================
    */
    IF @mode = N'DIRECT_TABLE'
    BEGIN
        RAISERROR(N'Reading statistics from table: %s', 10, 1, @StatisticsFromTable) WITH NOWAIT;

        DECLARE
            @table_sql nvarchar(max) = N'';

        /*
        Check if table exists
        */
        IF @StatisticsFromTable LIKE N'#%'
        BEGIN
            IF OBJECT_ID(N'tempdb..' + @StatisticsFromTable) IS NULL
            BEGIN
                RAISERROR(N'Temp table %s does not exist', 16, 1, @StatisticsFromTable);
                IF @StatsInParallel = N'N'
                    EXEC sp_releaseapplock @Resource = N'sp_StatUpdate', @LockOwner = N'Session';
                RETURN 1;
            END;
        END;
        ELSE
        BEGIN
            IF OBJECT_ID(@StatisticsFromTable) IS NULL
            BEGIN
                RAISERROR(N'Table %s does not exist', 16, 1, @StatisticsFromTable);
                IF @StatsInParallel = N'N'
                    EXEC sp_releaseapplock @Resource = N'sp_StatUpdate', @LockOwner = N'Session';
                RETURN 1;
            END;
        END;

        /*
        Create intermediate temp table
        */
        CREATE TABLE
            #input_stats
        (
            schema_name sysname NULL,
            table_name sysname NULL,
            stat_name sysname NOT NULL,
            priority integer NULL
        );

        /*
        Copy from source table - expects at minimum: StatName column
        */
        SELECT
            @table_sql = N'
        INSERT INTO
            #input_stats
        (
            stat_name
        )
        SELECT
            StatName
        FROM ' + @StatisticsFromTable + N';';

        BEGIN TRY
            EXECUTE sys.sp_executesql
                @table_sql;
        END TRY
        BEGIN CATCH
            RAISERROR(N'Table %s must have at least a StatName column', 16, 1, @StatisticsFromTable);
            IF @StatsInParallel = N'N'
                EXEC sp_releaseapplock @Resource = N'sp_StatUpdate', @LockOwner = N'Session';
            RETURN 1;
        END CATCH;

        /*
        Try to update optional columns if they exist
        */
        SELECT
            @table_sql = N'
        UPDATE
            ist
        SET
            ist.schema_name = src.SchemaName
        FROM #input_stats AS ist
        JOIN ' + @StatisticsFromTable + N' AS src
          ON src.StatName = ist.stat_name;';
        BEGIN TRY
            EXECUTE sys.sp_executesql
                @table_sql;
        END TRY
        BEGIN CATCH
        END CATCH;

        SELECT
            @table_sql = N'
        UPDATE
            ist
        SET
            ist.table_name = src.TableName
        FROM #input_stats AS ist
        JOIN ' + @StatisticsFromTable + N' AS src
          ON src.StatName = ist.stat_name;';
        BEGIN TRY
            EXECUTE sys.sp_executesql
                @table_sql;
        END TRY
        BEGIN CATCH
        END CATCH;

        SELECT
            @table_sql = N'
        UPDATE
            ist
        SET
            ist.priority = src.Priority
        FROM #input_stats AS ist
        JOIN ' + @StatisticsFromTable + N' AS src
          ON src.StatName = ist.stat_name;';
        BEGIN TRY
            EXECUTE sys.sp_executesql
                @table_sql;
        END TRY
        BEGIN CATCH
        END CATCH;

        /*
        Join with sys.stats to get full metadata — loop over selected databases.
        #input_stats is visible to dynamic SQL (temp tables in caller scope).
        */
        DECLARE
            @direct_table_sql nvarchar(max),
            @dt_skip_msg nvarchar(4000);

        WHILE EXISTS (SELECT 1 FROM @tmpDatabases WHERE Selected = 1 AND Completed = 0)
        BEGIN
            SELECT TOP (1)
                @CurrentDatabaseID = ID,
                @CurrentDatabaseName = DatabaseName
            FROM @tmpDatabases
            WHERE Selected = 1
            AND   Completed = 0
            ORDER BY ID;

            RAISERROR(N'  Scanning database: %s', 10, 1, @CurrentDatabaseName) WITH NOWAIT;

            BEGIN TRY
                SET @direct_table_sql = N'
USE ' + QUOTENAME(@CurrentDatabaseName) + N';

INSERT INTO
    #stats_to_process
(
    database_name,
    schema_name,
    table_name,
    stat_name,
    object_id,
    stats_id,
    no_recompute,
    is_incremental,
    is_memory_optimized,
    is_published,
    is_tracked_by_cdc,
    temporal_type,
    is_heap,
    auto_created,
    modification_counter,
    row_count,
    days_stale,
    page_count,
    persisted_sample_percent,
    histogram_steps,
    has_filter,
    filter_definition,
    unfiltered_rows,
    priority
)
SELECT
    database_name = DB_NAME(),
    schema_name = ISNULL(src.schema_name, OBJECT_SCHEMA_NAME(s.object_id)),
    table_name = ISNULL(src.table_name, OBJECT_NAME(s.object_id)),
    stat_name = s.name,
    object_id = s.object_id,
    stats_id = s.stats_id,
    no_recompute = s.no_recompute,
    is_incremental = s.is_incremental,
    is_memory_optimized = ISNULL(t.is_memory_optimized, 0),
    is_published = ISNULL(t.is_published, 0),
    is_tracked_by_cdc = ISNULL(t.is_tracked_by_cdc, 0),
    temporal_type = ISNULL(t.temporal_type, 0),
    is_heap =
        CASE
            WHEN EXISTS
                 (
                     SELECT
                         1
                     FROM sys.indexes AS i
                     WHERE i.object_id = s.object_id
                     AND   i.index_id = 0
                 )
            THEN 1
            ELSE 0
        END,
    auto_created = s.auto_created,
    modification_counter = ISNULL(sp.modification_counter, 0),
    row_count = ISNULL(sp.rows, 0),
    days_stale = ISNULL(DATEDIFF(DAY, sp.last_updated, SYSDATETIME()), 9999),
    page_count = ISNULL(pgs.total_pages, 0),
    persisted_sample_percent = sp.persisted_sample_percent,
    histogram_steps = sp.steps,
    has_filter = s.has_filter,
    filter_definition = s.filter_definition,
    unfiltered_rows = sp.unfiltered_rows,
    priority = ISNULL(src.priority, ROW_NUMBER() OVER (ORDER BY (SELECT NULL)))
FROM #input_stats AS src
JOIN sys.stats AS s
  ON s.name COLLATE DATABASE_DEFAULT = src.stat_name COLLATE DATABASE_DEFAULT
 AND (
         src.table_name IS NULL
      OR OBJECT_NAME(s.object_id) COLLATE DATABASE_DEFAULT = src.table_name COLLATE DATABASE_DEFAULT
     )
 AND (
         src.schema_name IS NULL
      OR OBJECT_SCHEMA_NAME(s.object_id) COLLATE DATABASE_DEFAULT = src.schema_name COLLATE DATABASE_DEFAULT
     )
LEFT JOIN sys.tables AS t
  ON t.object_id = s.object_id
CROSS APPLY sys.dm_db_stats_properties(s.object_id, s.stats_id) AS sp
OUTER APPLY
(
    SELECT
        total_pages = SUM(p.used_page_count)
    FROM sys.dm_db_partition_stats AS p
    WHERE p.object_id = s.object_id
    AND   p.index_id IN (0, 1)
) AS pgs
WHERE (OBJECTPROPERTY(s.object_id, N''IsUserTable'') = 1 OR @IncludeSystemObjects_param = N''Y'')
OPTION (RECOMPILE);';

                EXECUTE sys.sp_executesql
                    @direct_table_sql,
                    N'@IncludeSystemObjects_param nvarchar(1)',
                    @IncludeSystemObjects_param = @IncludeSystemObjects;

            END TRY
            BEGIN CATCH
                SET @dt_skip_msg =
                    N'  WARNING: Skipping database ' + QUOTENAME(@CurrentDatabaseName) +
                    N' - ' + ERROR_MESSAGE();
                RAISERROR(@dt_skip_msg, 10, 1) WITH NOWAIT;
                /* #204: Add per-database skip to @WarningsOut */
                SET @warnings += N'DB_SKIPPED: ' + @CurrentDatabaseName + N'; ';
            END CATCH;

            UPDATE @tmpDatabases
            SET Completed = 1
            WHERE ID = @CurrentDatabaseID;

        END; /* End of WHILE database loop for DIRECT_TABLE */

        DROP TABLE #input_stats;

        DECLARE
            @table_row_count integer =
            (
                SELECT
                    COUNT_BIG(*)
                FROM #stats_to_process
            );

        RAISERROR(N'Loaded %d statistics from table across %d database(s)', 10, 1, @table_row_count, @database_count) WITH NOWAIT;
    END;

    /*
    ============================================================================
    MODE 1B: DIRECT_STRING - Parse @Statistics parameter
    ============================================================================
    */
    IF @mode = N'DIRECT_STRING'
    BEGIN
        RAISERROR(N'Parsing explicit statistics list...', 10, 1) WITH NOWAIT;

        /*
        Materialize parsed stats into temp table so dynamic SQL can see it.
        PARSENAME positions: 3=schema, 2=table, 1=stat
        */
        CREATE TABLE
            #parsed_stats
        (
            parsed_schema sysname NULL,
            parsed_table sysname NULL,
            parsed_stat sysname NOT NULL
        );

        INSERT INTO
            #parsed_stats
        (
            parsed_schema,
            parsed_table,
            parsed_stat
        )
        SELECT
            parsed_schema = PARSENAME(LTRIM(RTRIM(ss.value)), 3),
            parsed_table = PARSENAME(LTRIM(RTRIM(ss.value)), 2),
            parsed_stat = PARSENAME(LTRIM(RTRIM(ss.value)), 1)
        FROM STRING_SPLIT(@Statistics, N',') AS ss
        WHERE LTRIM(RTRIM(ss.value)) <> N''
        AND   PARSENAME(LTRIM(RTRIM(ss.value)), 1) IS NOT NULL;

        DECLARE
            @requested_count integer =
            (
                SELECT
                    COUNT_BIG(*)
                FROM #parsed_stats
            );

        /*
        Loop over selected databases — #parsed_stats visible to dynamic SQL.
        */
        DECLARE
            @direct_string_sql nvarchar(max),
            @ds_skip_msg nvarchar(4000);

        WHILE EXISTS (SELECT 1 FROM @tmpDatabases WHERE Selected = 1 AND Completed = 0)
        BEGIN
            SELECT TOP (1)
                @CurrentDatabaseID = ID,
                @CurrentDatabaseName = DatabaseName
            FROM @tmpDatabases
            WHERE Selected = 1
            AND   Completed = 0
            ORDER BY ID;

            RAISERROR(N'  Scanning database: %s', 10, 1, @CurrentDatabaseName) WITH NOWAIT;

            BEGIN TRY
                SET @direct_string_sql = N'
USE ' + QUOTENAME(@CurrentDatabaseName) + N';

INSERT INTO
    #stats_to_process
(
    database_name,
    schema_name,
    table_name,
    stat_name,
    object_id,
    stats_id,
    no_recompute,
    is_incremental,
    is_memory_optimized,
    is_published,
    is_tracked_by_cdc,
    temporal_type,
    is_heap,
    auto_created,
    modification_counter,
    row_count,
    days_stale,
    page_count,
    persisted_sample_percent,
    histogram_steps,
    has_filter,
    filter_definition,
    unfiltered_rows,
    priority
)
SELECT
    database_name = DB_NAME(),
    schema_name = ISNULL(ps.parsed_schema, OBJECT_SCHEMA_NAME(s.object_id)),
    table_name = ISNULL(ps.parsed_table, OBJECT_NAME(s.object_id)),
    stat_name = s.name,
    object_id = s.object_id,
    stats_id = s.stats_id,
    no_recompute = s.no_recompute,
    is_incremental = s.is_incremental,
    is_memory_optimized = ISNULL(t.is_memory_optimized, 0),
    is_published = ISNULL(t.is_published, 0),
    is_tracked_by_cdc = ISNULL(t.is_tracked_by_cdc, 0),
    temporal_type = ISNULL(t.temporal_type, 0),
    is_heap =
        CASE
            WHEN EXISTS
                 (
                     SELECT
                         1
                     FROM sys.indexes AS i
                     WHERE i.object_id = s.object_id
                     AND   i.index_id = 0
                 )
            THEN 1
            ELSE 0
        END,
    auto_created = s.auto_created,
    modification_counter = ISNULL(sp.modification_counter, 0),
    row_count = ISNULL(sp.rows, 0),
    days_stale = ISNULL(DATEDIFF(DAY, sp.last_updated, SYSDATETIME()), 9999),
    page_count = ISNULL(pgs.total_pages, 0),
    persisted_sample_percent = sp.persisted_sample_percent,
    histogram_steps = sp.steps,
    has_filter = s.has_filter,
    filter_definition = s.filter_definition,
    unfiltered_rows = sp.unfiltered_rows,
    priority = ROW_NUMBER() OVER (ORDER BY (SELECT NULL))
FROM #parsed_stats AS ps
JOIN sys.stats AS s
  ON s.name COLLATE DATABASE_DEFAULT = ps.parsed_stat COLLATE DATABASE_DEFAULT
 AND (
         ps.parsed_table IS NULL
      OR OBJECT_NAME(s.object_id) COLLATE DATABASE_DEFAULT = ps.parsed_table COLLATE DATABASE_DEFAULT
     )
 AND (
         ps.parsed_schema IS NULL
      OR OBJECT_SCHEMA_NAME(s.object_id) COLLATE DATABASE_DEFAULT = ps.parsed_schema COLLATE DATABASE_DEFAULT
     )
LEFT JOIN sys.tables AS t
  ON t.object_id = s.object_id
CROSS APPLY sys.dm_db_stats_properties(s.object_id, s.stats_id) AS sp
OUTER APPLY
(
    SELECT
        total_pages = SUM(p.used_page_count)
    FROM sys.dm_db_partition_stats AS p
    WHERE p.object_id = s.object_id
    AND   p.index_id IN (0, 1)
) AS pgs
WHERE (OBJECTPROPERTY(s.object_id, N''IsUserTable'') = 1 OR @IncludeSystemObjects_param = N''Y'')
OPTION (RECOMPILE);';

                EXECUTE sys.sp_executesql
                    @direct_string_sql,
                    N'@IncludeSystemObjects_param nvarchar(1)',
                    @IncludeSystemObjects_param = @IncludeSystemObjects;

            END TRY
            BEGIN CATCH
                SET @ds_skip_msg =
                    N'  WARNING: Skipping database ' + QUOTENAME(@CurrentDatabaseName) +
                    N' - ' + ERROR_MESSAGE();
                RAISERROR(@ds_skip_msg, 10, 1) WITH NOWAIT;
                /* #204: Add per-database skip to @WarningsOut */
                SET @warnings += N'DB_SKIPPED: ' + @CurrentDatabaseName + N'; ';
            END CATCH;

            UPDATE @tmpDatabases
            SET Completed = 1
            WHERE ID = @CurrentDatabaseID;

        END; /* End of WHILE database loop for DIRECT_STRING */

        DROP TABLE #parsed_stats;

        /*
        Warn about any stats not found
        */
        DECLARE
            @found_count integer =
            (
                SELECT
                    COUNT_BIG(*)
                FROM #stats_to_process
            );

        IF @found_count < @requested_count
        BEGIN
            RAISERROR(N'Warning: Only %d of %d requested statistics found across %d database(s)', 10, 1, @found_count, @requested_count, @database_count) WITH NOWAIT;
        END;
    END;
    /*#endregion 15-DIRECT-MODE */

    /*#region 16-DISCOVERY: Mode 2: Staged and legacy discovery */
    /*
    ============================================================================
    MODE 2: DISCOVERY - DMV-based candidate selection
    ============================================================================
    */
    IF @mode = N'DISCOVERY'
    BEGIN
        RAISERROR(N'Discovering qualifying statistics via DMV...', 10, 1) WITH NOWAIT;

        DECLARE
            @discovery_sql nvarchar(max) = N'',
            @discovery_params nvarchar(max) = N'';

        /*
        ========================================================================
        LOOP OVER SELECTED DATABASES
        ========================================================================
        */
        /*
        Signal table for staged discovery failure detection.
        Created before the database loop so it persists across iterations.
        Dynamic SQL can write to it to signal unexpected row loss.
        */
        CREATE TABLE #staged_discovery_failed (reason nvarchar(500));

        WHILE EXISTS (SELECT 1 FROM @tmpDatabases WHERE Selected = 1 AND Completed = 0)
        BEGIN
            /*
            Get next database to process
            */
            SELECT TOP (1)
                @CurrentDatabaseID = ID,
                @CurrentDatabaseName = DatabaseName
            FROM @tmpDatabases
            WHERE Selected = 1
            AND   Completed = 0
            ORDER BY ID;

            RAISERROR(N'  Scanning database: %s', 10, 1, @CurrentDatabaseName) WITH NOWAIT;

            /*
            Per-database TRY/CATCH: Skip databases that become inaccessible during the run
            (SINGLE_USER acquired by another session, taken offline, etc.) instead of
            aborting the entire run or counting toward @MaxConsecutiveFailures.
            */
            BEGIN TRY

            /*
            ========================================================================
            PER-DATABASE ENVIRONMENT INFO (Phase 1.1/1.4 - v2.0, debug mode only)
            ========================================================================
            Show compatibility level, effective CE version, and relevant db-scoped configs.
            */
            IF @Debug = 1
            BEGIN
                DECLARE
                    @db_compat_level int,
                    @db_ce_version int,
                    @db_legacy_ce bit = 0,
                    @db_env_sql nvarchar(max);

                /* Get compatibility level */
                SELECT @db_compat_level = compatibility_level
                FROM sys.databases
                WHERE name = @CurrentDatabaseName;

                /* Calculate effective CE version */
                SET @db_ce_version = CASE
                    WHEN @db_compat_level <= 110 THEN 70
                    WHEN @db_compat_level = 120 THEN 120
                    ELSE @db_compat_level
                END;

                RAISERROR(N'    Compat Level: %d, CE Version: %d', 10, 1, @db_compat_level, @db_ce_version) WITH NOWAIT;

                /* Check database-scoped configurations (SQL 2016+) */
                IF @sql_major_version >= 13
                BEGIN
                    SET @db_env_sql = N'
                        SELECT @legacy_ce_out = CASE WHEN value = 1 THEN 1 ELSE 0 END
                        FROM ' + QUOTENAME(@CurrentDatabaseName) + N'.sys.database_scoped_configurations
                        WHERE name = N''LEGACY_CARDINALITY_ESTIMATION'';';

                    BEGIN TRY
                        EXEC sp_executesql @db_env_sql,
                            N'@legacy_ce_out bit OUTPUT',
                            @legacy_ce_out = @db_legacy_ce OUTPUT;
                    END TRY
                    BEGIN CATCH
                        SET @db_legacy_ce = 0; /* Ignore errors - db might not support this */
                    END CATCH;

                    IF @db_legacy_ce = 1
                        RAISERROR(N'    Note: LEGACY_CARDINALITY_ESTIMATION=ON (CE forced to 70)', 10, 1) WITH NOWAIT;
                END;

                /* Note if CE version differs from what compat level suggests due to trace flags */
                IF @tf_9481_active = 1 AND @db_compat_level >= 120
                    RAISERROR(N'    Note: TF 9481 forcing legacy CE despite compat level %d', 10, 1, @db_compat_level) WITH NOWAIT;

                /*
                RCSI / Snapshot Isolation detection (#53)
                Statistics updates under RCSI generate version store overhead in tempdb.
                */
                DECLARE
                    @db_rcsi bit = 0,
                    @db_snapshot bit = 0;

                SELECT
                    @db_rcsi = is_read_committed_snapshot_on,
                    @db_snapshot = snapshot_isolation_state
                FROM sys.databases
                WHERE name = @CurrentDatabaseName;

                IF @db_rcsi = 1
                    RAISERROR(N'    Note: RCSI enabled - stats updates generate version store overhead', 10, 1) WITH NOWAIT;
                IF @db_snapshot > 0
                    RAISERROR(N'    Note: Snapshot Isolation active - version store impact expected', 10, 1) WITH NOWAIT;
            END;

            /*
            ========================================================================
            STAGED DISCOVERY (6-phase approach for better performance)
            ========================================================================
            When @StagedDiscovery = 'Y', uses a phased approach:
              Phase 1: Collect basic candidate stats (fast - only sys.stats/objects)
              Phase 2: Batch-enrich with stats properties (one CROSS APPLY)
              Phase 3: Pre-calculate tier thresholds (no inline SQRT)
              Phase 4: Apply threshold filters (early elimination)
              Phase 5: Add page counts (only for qualifying stats)
              Phase 6: Add Query Store data (only if enabled, only for qualifying)
                       Uses batched CTE + JOIN instead of CROSS APPLY (O(1) vs O(n))

            This is significantly faster for large databases (10K+ stats) because:
              - Expensive DMV calls only run on candidates that might qualify
              - No inline SQRT calculations in WHERE clause
              - Query Store join (most expensive) runs last and only if needed
            */
            IF @StagedDiscovery = N'Y'
            BEGIN
                DECLARE @staged_sql nvarchar(max);

                SET @staged_sql = N'
                USE ' + QUOTENAME(@CurrentDatabaseName) + N';

                /*
                Phase row count tracking for validation (P1 #22)
                Prevents silent failures when phases don''t process expected rows.
                */
                DECLARE
                    @phase1_count int = 0,
                    @phase2_count int = 0,
                    @phase4_qualifying int = 0,
                    @phase5_remaining int = 0,
                    @phase_timer datetime2(7) = SYSDATETIME(),
                    @phase_ms int = 0;

                /*
                ================================================================
                PHASE 1: Collect basic candidate stats (FAST)
                Only touches sys.stats and sys.objects - no DMV cross-applies.
                ================================================================
                */
                CREATE TABLE #stat_candidates (
                    object_id int NOT NULL,
                    stats_id int NOT NULL,
                    stat_name sysname NOT NULL,
                    schema_name sysname NOT NULL,
                    table_name sysname NOT NULL,
                    no_recompute bit NOT NULL,
                    is_incremental bit NOT NULL,
                    has_filter bit NOT NULL,
                    filter_definition nvarchar(max) NULL,
                    is_memory_optimized bit NOT NULL DEFAULT 0,
                    auto_created bit NOT NULL DEFAULT 0,
                    /* Replication/CDC/Temporal */
                    is_published bit NOT NULL DEFAULT 0,
                    is_tracked_by_cdc bit NOT NULL DEFAULT 0,
                    temporal_type tinyint NOT NULL DEFAULT 0,
                    PRIMARY KEY CLUSTERED (object_id, stats_id)
                );

                INSERT INTO #stat_candidates
                    (object_id, stats_id, stat_name, schema_name, table_name,
                     no_recompute, is_incremental, has_filter, filter_definition, is_memory_optimized, auto_created,
                     is_published, is_tracked_by_cdc, temporal_type)
                SELECT
                    s.object_id,
                    s.stats_id,
                    s.name,
                    OBJECT_SCHEMA_NAME(s.object_id),
                    OBJECT_NAME(s.object_id),
                    s.no_recompute,
                    s.is_incremental,
                    s.has_filter,
                    s.filter_definition,
                    ISNULL(t.is_memory_optimized, 0),
                    s.auto_created,
                    ISNULL(t.is_published, 0),
                    ISNULL(t.is_tracked_by_cdc, 0),
                    ISNULL(t.temporal_type, 0)
                FROM sys.stats AS s
                JOIN sys.objects AS o ON o.object_id = s.object_id
                LEFT JOIN sys.tables AS t ON t.object_id = s.object_id
                WHERE (o.is_ms_shipped = 0 OR @IncludeSystemObjects_param = N''Y'')
                AND   (
                          OBJECTPROPERTY(s.object_id, N''IsUserTable'') = 1
                       OR @IncludeSystemObjects_param = N''Y''
                       OR (o.type = N''V'' AND @IncludeIndexedViews_param = N''Y''
                           AND EXISTS (SELECT 1 FROM sys.indexes AS vi WHERE vi.object_id = s.object_id AND vi.index_id = 1))
                      ) /* #49: Include indexed views when requested */
                AND   o.type NOT IN (N''ET'', N''S'') /* Exclude external tables (#54) and system tables */
                /* #55: Skip Stretch Database tables (deprecated, causes timeouts to Azure storage) */
                AND   ISNULL(OBJECTPROPERTY(s.object_id, N''TableHasRemoteDataArchive''), 0) = 0
                /* Skip tables on READ_ONLY filegroups (#65) */
                AND   NOT EXISTS
                      (
                          SELECT 1
                          FROM sys.indexes AS ri
                          JOIN sys.data_spaces AS rds ON rds.data_space_id = ri.data_space_id
                          JOIN sys.filegroups AS rfg ON rfg.data_space_id = rds.data_space_id
                          WHERE ri.object_id = s.object_id
                          AND   ri.index_id IN (0, 1) /* heap or clustered — the base storage */
                          AND   rfg.is_read_only = 1
                      )
                /* NORECOMPUTE filter */
                AND   (
                          (@TargetNorecompute_param = N''N'' AND s.no_recompute = 0)
                       OR (@TargetNorecompute_param = N''Y'' AND s.no_recompute = 1)
                       OR @TargetNorecompute_param = N''BOTH''
                      )
                /* Table filter */
                AND   (
                          @Tables_param IS NULL
                       OR OBJECT_SCHEMA_NAME(s.object_id) + N''.'' + OBJECT_NAME(s.object_id) COLLATE DATABASE_DEFAULT IN
                          (SELECT LTRIM(RTRIM(ss.value)) COLLATE DATABASE_DEFAULT FROM STRING_SPLIT(@Tables_param, N'','') AS ss)
                       OR OBJECT_NAME(s.object_id) COLLATE DATABASE_DEFAULT IN
                          (SELECT LTRIM(RTRIM(ss.value)) COLLATE DATABASE_DEFAULT FROM STRING_SPLIT(@Tables_param, N'','') AS ss)
                      )
                /* Table exclusion filter */
                AND   (
                          @ExcludeTables_param IS NULL
                       OR NOT EXISTS
                          (
                              SELECT 1
                              FROM STRING_SPLIT(@ExcludeTables_param, N'','') AS ex
                              WHERE OBJECT_SCHEMA_NAME(s.object_id) + N''.'' + OBJECT_NAME(s.object_id) COLLATE DATABASE_DEFAULT LIKE LTRIM(RTRIM(ex.value)) COLLATE DATABASE_DEFAULT
                          )
                      )
                /* Statistics exclusion filter */
                AND   (
                          @ExcludeStatistics_param IS NULL
                       OR NOT EXISTS
                          (
                              SELECT 1
                              FROM STRING_SPLIT(@ExcludeStatistics_param, N'','') AS ex
                              WHERE s.name COLLATE DATABASE_DEFAULT LIKE LTRIM(RTRIM(ex.value)) COLLATE DATABASE_DEFAULT
                                 OR s.name COLLATE DATABASE_DEFAULT = LTRIM(RTRIM(ex.value)) COLLATE DATABASE_DEFAULT
                          )
                      )
                /* Filtered stats mode filter */
                AND   (
                          @FilteredStatsMode_param = N''INCLUDE''
                       OR @FilteredStatsMode_param = N''PRIORITY''
                       OR (@FilteredStatsMode_param = N''EXCLUDE'' AND s.has_filter = 0)
                       OR (@FilteredStatsMode_param = N''ONLY'' AND s.has_filter = 1)
                      )
                /* v2.3: Skip tables with columnstore indexes when @SkipTablesWithColumnstore = Y */
                /* Columnstore indexes (type 5=nonclustered columnstore, 6=clustered columnstore) */
                /* may have plan stability concerns when rowstore stats are updated alongside NCCIs */
                AND   (
                          @SkipTablesWithColumnstore_param = N''N''
                       OR NOT EXISTS
                          (
                              SELECT 1
                              FROM sys.indexes AS ci
                              WHERE ci.object_id = s.object_id
                              AND   ci.type IN (5, 6) /* 5 = nonclustered columnstore, 6 = clustered columnstore */
                          )
                      );

                SELECT @phase1_count = @@ROWCOUNT,
                       @phase_ms = DATEDIFF(MILLISECOND, @phase_timer, SYSDATETIME());

                IF @Debug_param = 1
                    RAISERROR(N''    Phase 1 (candidates): %d stats (%d ms)'', 10, 1, @phase1_count, @phase_ms) WITH NOWAIT;

                SET @phase_timer = SYSDATETIME();

                /*
                ================================================================
                PHASE 2: Enrich with stats properties (batch CROSS APPLY)
                ================================================================
                */
                ALTER TABLE #stat_candidates ADD
                    modification_counter bigint NULL,
                    rows bigint NULL,
                    last_updated datetime2 NULL,
                    unfiltered_rows bigint NULL,
                    persisted_sample_percent float NULL,
                    histogram_steps int NULL;

                UPDATE sc
                SET
                    sc.modification_counter = ISNULL(sp.modification_counter, 0),
                    sc.rows = ISNULL(sp.rows, 0),
                    sc.last_updated = sp.last_updated,
                    sc.unfiltered_rows = sp.unfiltered_rows,
                    sc.persisted_sample_percent = sp.persisted_sample_percent,
                    sc.histogram_steps = sp.steps
                FROM #stat_candidates AS sc
                CROSS APPLY sys.dm_db_stats_properties(sc.object_id, sc.stats_id) AS sp;

                SELECT @phase2_count = @@ROWCOUNT,
                       @phase_ms = DATEDIFF(MILLISECOND, @phase_timer, SYSDATETIME());

                IF @Debug_param = 1
                    RAISERROR(N''    Phase 2 (enriched): %d stats (%d ms)'', 10, 1, @phase2_count, @phase_ms) WITH NOWAIT;

                /*
                VALIDATION: CROSS APPLY filters out stats with no properties.
                This is expected for never-updated stats. Log if significant.
                Unexpected total loss (0 enriched from 100+ candidates) triggers fallback.
                */
                IF @phase2_count = 0 AND @phase1_count > 100
                BEGIN
                    RAISERROR(N''    ERROR: Phase 2 enriched 0 of %d candidates - triggering legacy fallback'', 10, 1, @phase1_count) WITH NOWAIT;
                    INSERT INTO #staged_discovery_failed (reason) VALUES (N''Phase 2 returned 0 rows from '' + CONVERT(nvarchar(20), @phase1_count) + N'' candidates'');

                    /* Return empty result set to satisfy INSERT...EXEC schema */
                    SELECT
                        database_name = DB_NAME(),
                        schema_name = CONVERT(sysname, NULL),
                        table_name = CONVERT(sysname, NULL),
                        stat_name = CONVERT(sysname, NULL),
                        object_id = CONVERT(int, NULL),
                        stats_id = CONVERT(int, NULL),
                        no_recompute = CONVERT(bit, NULL),
                        is_incremental = CONVERT(bit, NULL),
                        is_memory_optimized = CONVERT(bit, NULL),
                        is_heap = CONVERT(bit, NULL),
                        auto_created = CONVERT(bit, NULL),
                        modification_counter = CONVERT(bigint, NULL),
                        row_count = CONVERT(bigint, NULL),
                        days_stale = CONVERT(int, NULL),
                        page_count = CONVERT(bigint, NULL),
                        persisted_sample_percent = CONVERT(float, NULL),
                        histogram_steps = CONVERT(int, NULL),
                        has_filter = CONVERT(bit, NULL),
                        filter_definition = CONVERT(nvarchar(max), NULL),
                        unfiltered_rows = CONVERT(bigint, NULL),
                        qs_plan_count = CONVERT(int, NULL),
                        qs_total_executions = CONVERT(bigint, NULL),
                        qs_total_cpu_ms = CONVERT(bigint, NULL),
                        qs_total_duration_ms = CONVERT(bigint, NULL),
                        qs_total_logical_reads = CONVERT(bigint, NULL),
                        qs_last_execution = CONVERT(datetime2, NULL),
                        qs_priority_boost = CONVERT(bigint, NULL),
                        is_published = CONVERT(bit, NULL),
                        is_tracked_by_cdc = CONVERT(bit, NULL),
                        temporal_type = CONVERT(tinyint, NULL),
                        priority = CONVERT(bigint, NULL)
                    WHERE 1 = 0;

                    DROP TABLE #stat_candidates;
                    RETURN;
                END;

                IF @phase2_count < @phase1_count AND @Debug_param = 1
                BEGIN
                    DECLARE @missing_count int = @phase1_count - @phase2_count;
                    RAISERROR(N''    Note: %d stats have no properties (never updated)'', 10, 1, @missing_count) WITH NOWAIT;
                    /* v2.3: Log specific Phase 1→2 losses (stats with no dm_db_stats_properties data) */
                    DECLARE @phase_loss_msg nvarchar(4000);
                    DECLARE phase_loss_cursor CURSOR LOCAL FAST_FORWARD FOR
                        SELECT N''  Phase 1→2 loss: '' + QUOTENAME(schema_name) + N''.'' + QUOTENAME(table_name) + N''.'' + QUOTENAME(stat_name)
                        FROM #stat_candidates
                        WHERE modification_counter IS NULL
                        ORDER BY schema_name, table_name, stat_name;
                    OPEN phase_loss_cursor;
                    FETCH NEXT FROM phase_loss_cursor INTO @phase_loss_msg;
                    WHILE @@FETCH_STATUS = 0
                    BEGIN
                        RAISERROR(@phase_loss_msg, 10, 1) WITH NOWAIT;
                        FETCH NEXT FROM phase_loss_cursor INTO @phase_loss_msg;
                    END;
                    CLOSE phase_loss_cursor;
                    DEALLOCATE phase_loss_cursor;
                END;

                /*
                ================================================================
                PHASE 3: Pre-calculate tier thresholds (avoids inline SQRT)
                ================================================================
                */
                ALTER TABLE #stat_candidates ADD
                    tier_threshold bigint NULL,
                    sqrt_threshold bigint NULL,
                    days_stale int NULL,
                    hours_stale int NULL; /* v2.3: for @HoursStaleThreshold */

                UPDATE #stat_candidates
                SET
                    tier_threshold =
                        CASE
                            WHEN rows <= 500 THEN 500
                            WHEN rows <= 10000 THEN (rows * 20) / 100 + 500
                            WHEN rows <= 100000 THEN (rows * 15) / 100 + 500
                            WHEN rows <= 1000000 THEN (rows * 10) / 100 + 500
                            ELSE CONVERT(bigint, CONVERT(float, rows) * 5 / 100) + 500
                        END,
                    sqrt_threshold = CONVERT(bigint, SQRT(CONVERT(float, CASE WHEN ISNULL(rows, 0) < 1 THEN 1 ELSE rows END) * 1000)),
                    days_stale = ISNULL(DATEDIFF(DAY, last_updated, SYSDATETIME()), 9999),
                    hours_stale = ISNULL(DATEDIFF(HOUR, last_updated, SYSDATETIME()), 999999); /* v2.3 */

                SET @phase_ms = DATEDIFF(MILLISECOND, @phase_timer, SYSDATETIME());
                IF @Debug_param = 1
                    RAISERROR(N''    Phase 3 (tier thresholds): calculated (%d ms)'', 10, 1, @phase_ms) WITH NOWAIT;
                SET @phase_timer = SYSDATETIME();

                /*
                ================================================================
                PHASE 4: Apply threshold filters (early elimination)
                ================================================================
                */
                ALTER TABLE #stat_candidates ADD qualifies bit NOT NULL DEFAULT 0;

                /* Apply threshold logic */
                IF @ThresholdLogic_param = N''OR''
                BEGIN
                    UPDATE #stat_candidates
                    SET qualifies = 1
                    WHERE (
                        /* Fixed modification threshold */
                        (@ModificationThreshold_param IS NOT NULL AND modification_counter >= @ModificationThreshold_param)
                        /* Modification percent (non-tiered) */
                        OR (@TieredThresholds_param = 0 AND @ModificationPercent_param IS NOT NULL
                            AND modification_counter >= (@ModificationPercent_param * SQRT(CONVERT(float, ISNULL(rows, 1)))))
                        /* Tiered thresholds */
                        OR (@TieredThresholds_param = 1 AND (modification_counter >= tier_threshold OR modification_counter >= sqrt_threshold))
                        /* Days stale */
                        OR (@DaysStaleThreshold_param IS NOT NULL AND days_stale >= @DaysStaleThreshold_param)
                        /* Hours stale (v2.3 - precise time-based threshold, alternative to @DaysStaleThreshold) */
                        OR (@HoursStaleThreshold_param IS NOT NULL AND hours_stale >= @HoursStaleThreshold_param)
                        /* No thresholds = include all */
                        OR (@ModificationThreshold_param IS NULL AND @ModificationPercent_param IS NULL
                            AND @TieredThresholds_param = 0 AND @DaysStaleThreshold_param IS NULL
                            AND @HoursStaleThreshold_param IS NULL)
                    );
                END
                ELSE /* AND logic */
                BEGIN
                    UPDATE #stat_candidates
                    SET qualifies = 1
                    WHERE (
                        @ModificationThreshold_param IS NULL OR modification_counter >= @ModificationThreshold_param
                    )
                    AND (
                        (@ModificationPercent_param IS NULL AND @TieredThresholds_param = 0)
                        OR (@TieredThresholds_param = 0 AND modification_counter >= (@ModificationPercent_param * SQRT(CONVERT(float, ISNULL(rows, 1)))))
                        OR (@TieredThresholds_param = 1 AND (modification_counter >= tier_threshold OR modification_counter >= sqrt_threshold))
                    )
                    AND (
                        @DaysStaleThreshold_param IS NULL OR days_stale >= @DaysStaleThreshold_param
                    )
                    AND (
                        /* v2.3: hours stale threshold */
                        @HoursStaleThreshold_param IS NULL OR hours_stale >= @HoursStaleThreshold_param
                    );
                END;

                /*
                #143: Ascending key boost — identity column stats with ANY modifications
                bypass normal thresholds. Leading column of stat checked against
                sys.identity_columns. This prevents histogram staleness for insert-heavy
                tables where modification_counter hasn''t hit threshold yet.
                */
                IF @AscendingKeyBoost_param = N''Y''
                BEGIN
                    DECLARE @ascending_rescued int = 0;

                    UPDATE sc
                    SET sc.qualifies = 1
                    FROM #stat_candidates AS sc
                    WHERE sc.qualifies = 0
                    AND   sc.modification_counter > 0
                    AND   EXISTS (
                        SELECT 1
                        FROM sys.stats_columns AS stc
                        JOIN sys.identity_columns AS ic
                          ON ic.object_id = stc.object_id AND ic.column_id = stc.column_id
                        WHERE stc.object_id = sc.object_id
                        AND   stc.stats_id = sc.stats_id
                        AND   stc.stats_column_id = 1
                    );

                    SET @ascending_rescued = @@ROWCOUNT;

                    IF @ascending_rescued > 0 AND @Debug_param = 1
                        RAISERROR(N''    Phase 4: Ascending key boost rescued %d stat(s)'', 10, 1, @ascending_rescued) WITH NOWAIT;
                END;

                /* Delete non-qualifying stats early */
                DELETE FROM #stat_candidates WHERE qualifies = 0;

                SELECT @phase4_qualifying = (SELECT COUNT(*) FROM #stat_candidates),
                       @phase_ms = DATEDIFF(MILLISECOND, @phase_timer, SYSDATETIME());

                IF @Debug_param = 1
                    RAISERROR(N''    Phase 4 (after thresholds): %d stats qualify (%d ms)'', 10, 1, @phase4_qualifying, @phase_ms) WITH NOWAIT;
                SET @phase_timer = SYSDATETIME();

                /*
                VALIDATION: If 0 stats qualify after threshold filtering, we can exit early.
                This is normal when no stats need updating.
                */
                IF @phase4_qualifying = 0
                BEGIN
                    IF @Debug_param = 1
                        RAISERROR(N''    No stats qualify - skipping remaining phases'', 10, 1) WITH NOWAIT;

                    /*
                    Return empty result set with correct schema.
                    Required: INSERT...EXEC consumes this result set, so we must
                    provide matching column schema even when returning 0 rows.
                    */
                    SELECT
                        database_name = DB_NAME(),
                        schema_name = CONVERT(sysname, NULL),
                        table_name = CONVERT(sysname, NULL),
                        stat_name = CONVERT(sysname, NULL),
                        object_id = CONVERT(int, NULL),
                        stats_id = CONVERT(int, NULL),
                        no_recompute = CONVERT(bit, NULL),
                        is_incremental = CONVERT(bit, NULL),
                        is_memory_optimized = CONVERT(bit, NULL),
                        is_heap = CONVERT(bit, NULL),
                        auto_created = CONVERT(bit, NULL),
                        modification_counter = CONVERT(bigint, NULL),
                        row_count = CONVERT(bigint, NULL),
                        days_stale = CONVERT(int, NULL),
                        page_count = CONVERT(bigint, NULL),
                        persisted_sample_percent = CONVERT(float, NULL),
                        histogram_steps = CONVERT(int, NULL),
                        has_filter = CONVERT(bit, NULL),
                        filter_definition = CONVERT(nvarchar(max), NULL),
                        unfiltered_rows = CONVERT(bigint, NULL),
                        qs_plan_count = CONVERT(int, NULL),
                        qs_total_executions = CONVERT(bigint, NULL),
                        qs_total_cpu_ms = CONVERT(bigint, NULL),
                        qs_total_duration_ms = CONVERT(bigint, NULL),
                        qs_total_logical_reads = CONVERT(bigint, NULL),
                        qs_last_execution = CONVERT(datetime2, NULL),
                        qs_priority_boost = CONVERT(bigint, NULL),
                        is_published = CONVERT(bit, NULL),
                        is_tracked_by_cdc = CONVERT(bit, NULL),
                        temporal_type = CONVERT(tinyint, NULL),
                        priority = CONVERT(bigint, NULL)
                    WHERE 1 = 0;

                    DROP TABLE #stat_candidates;
                    RETURN;
                END;

                /*
                ================================================================
                PHASE 5: Add page counts (only for qualifying stats)
                ================================================================
                */
                ALTER TABLE #stat_candidates ADD
                    page_count bigint NULL,
                    is_heap bit NULL;

                UPDATE sc
                SET
                    sc.page_count = ISNULL(pgs.total_pages, 0),
                    sc.is_heap = CASE WHEN ix.index_id IS NOT NULL THEN 1 ELSE 0 END
                FROM #stat_candidates AS sc
                OUTER APPLY (
                    SELECT SUM(p.used_page_count) AS total_pages
                    FROM sys.dm_db_partition_stats AS p
                    WHERE p.object_id = sc.object_id
                    AND   p.index_id IN (0, 1)
                ) AS pgs
                LEFT JOIN sys.indexes AS ix ON ix.object_id = sc.object_id AND ix.index_id = 0;

                /* Apply MinPageCount filter */
                DELETE FROM #stat_candidates WHERE ISNULL(page_count, 0) < @MinPageCount_param;

                SELECT @phase5_remaining = (SELECT COUNT(*) FROM #stat_candidates),
                       @phase_ms = DATEDIFF(MILLISECOND, @phase_timer, SYSDATETIME());

                IF @Debug_param = 1
                    RAISERROR(N''    Phase 5 (after MinPageCount): %d stats remain (%d ms)'', 10, 1, @phase5_remaining, @phase_ms) WITH NOWAIT;
                SET @phase_timer = SYSDATETIME();

                /*
                VALIDATION: Suspicious row loss in Phase 5.
                If MinPageCount is 0 (no filtering expected) and we lost >50% of rows,
                the page count UPDATE may have failed silently.
                */
                IF  @MinPageCount_param = 0
                AND @phase4_qualifying > 0
                AND @phase5_remaining < (@phase4_qualifying / 2)
                BEGIN
                    RAISERROR(N''    ERROR: Phase 5 kept %d of %d rows with MinPageCount=0 - triggering legacy fallback'', 10, 1,
                        @phase5_remaining, @phase4_qualifying) WITH NOWAIT;
                    INSERT INTO #staged_discovery_failed (reason)
                        VALUES (N''Phase 5 lost >50%% rows: '' + CONVERT(nvarchar(20), @phase5_remaining) + N'' of '' + CONVERT(nvarchar(20), @phase4_qualifying));

                    SELECT
                        database_name = DB_NAME(),
                        schema_name = CONVERT(sysname, NULL),
                        table_name = CONVERT(sysname, NULL),
                        stat_name = CONVERT(sysname, NULL),
                        object_id = CONVERT(int, NULL),
                        stats_id = CONVERT(int, NULL),
                        no_recompute = CONVERT(bit, NULL),
                        is_incremental = CONVERT(bit, NULL),
                        is_memory_optimized = CONVERT(bit, NULL),
                        is_heap = CONVERT(bit, NULL),
                        auto_created = CONVERT(bit, NULL),
                        modification_counter = CONVERT(bigint, NULL),
                        row_count = CONVERT(bigint, NULL),
                        days_stale = CONVERT(int, NULL),
                        page_count = CONVERT(bigint, NULL),
                        persisted_sample_percent = CONVERT(float, NULL),
                        histogram_steps = CONVERT(int, NULL),
                        has_filter = CONVERT(bit, NULL),
                        filter_definition = CONVERT(nvarchar(max), NULL),
                        unfiltered_rows = CONVERT(bigint, NULL),
                        qs_plan_count = CONVERT(int, NULL),
                        qs_total_executions = CONVERT(bigint, NULL),
                        qs_total_cpu_ms = CONVERT(bigint, NULL),
                        qs_total_duration_ms = CONVERT(bigint, NULL),
                        qs_total_logical_reads = CONVERT(bigint, NULL),
                        qs_last_execution = CONVERT(datetime2, NULL),
                        qs_priority_boost = CONVERT(bigint, NULL),
                        is_published = CONVERT(bit, NULL),
                        is_tracked_by_cdc = CONVERT(bit, NULL),
                        temporal_type = CONVERT(tinyint, NULL),
                        priority = CONVERT(bigint, NULL)
                    WHERE 1 = 0;

                    DROP TABLE #stat_candidates;
                    RETURN;
                END;

                /*
                ================================================================
                PHASE 6: Add Query Store data (only if enabled)
                P2 #20: Skip QS operations when QS is disabled.
                ================================================================
                */
                ALTER TABLE #stat_candidates ADD
                    qs_plan_count int NULL,
                    qs_total_executions bigint NULL,
                    qs_total_cpu_ms bigint NULL,
                    qs_total_duration_ms bigint NULL,
                    qs_total_logical_reads bigint NULL,
                    qs_last_execution datetime2 NULL,
                    qs_priority_boost bigint NULL;

                /*
                Only populate QS data if:
                1. User requested QS priority (@QueryStorePriority = Y)
                2. Query Store is enabled on this database (actual_state IN 1, 2)
                If neither, skip the UPDATE - NULL will be handled by ISNULL in ORDER BY.
                This avoids touching all rows when QS is disabled (10K+ stat databases).

                v1.9: Warn if Query Store is READ_ONLY (state 1) as data may be stale.
                */
                IF @QueryStorePriority_param = N''Y''
                AND EXISTS (SELECT 1 FROM sys.database_query_store_options WHERE actual_state IN (1, 2))
                BEGIN
                    /* v1.9: Warn if Query Store is READ_ONLY (might have stale data) */
                    IF EXISTS (SELECT 1 FROM sys.database_query_store_options WHERE actual_state = 1)
                    BEGIN
                        IF @Debug_param = 1
                            RAISERROR(N''    Warning: Query Store is READ_ONLY - priority data may be stale'', 10, 1) WITH NOWAIT;
                    END;

                    /* #190: Check if @QueryStoreRecentHours exceeds QS retention.
                       Uses stale_query_threshold_days from sys.database_query_store_options. */
                    DECLARE @qs_retention_days int;
                    SELECT @qs_retention_days = stale_query_threshold_days
                    FROM sys.database_query_store_options;

                    IF @qs_retention_days IS NOT NULL AND @QueryStoreRecentHours_param > (@qs_retention_days * 24)
                    BEGIN
                        DECLARE @qs_ret_warn nvarchar(500) = N''    Warning: @QueryStoreRecentHours=''
                            + CONVERT(nvarchar(10), @QueryStoreRecentHours_param) + N''h exceeds QS retention ''
                            + CONVERT(nvarchar(10), @qs_retention_days * 24) + N''h — enrichment may return no data'';
                        RAISERROR(@qs_ret_warn, 10, 1) WITH NOWAIT;
                    END;

                    /*
                    FIX #271: Plan XML table extraction for QS enrichment.
                    Previous approach joined on qsq.object_id (the MODULE id for stored
                    procs/functions) to #stat_candidates.object_id (the TABLE id from
                    sys.stats). These are different domains — the join produced zero
                    matches for all workload types (ad-hoc, ORM, stored proc).
                    Now we parse plan XML to find which tables each QS plan references.
                    */

                    /* Initialize qs_priority_boost to 0 for all rows first */
                    UPDATE #stat_candidates SET qs_priority_boost = 0;

                    /* Step 1: Extract table references from QS plans in the time window.
                       Step 2: Filter to only tables we have stat candidates for.
                       Step 3: Aggregate runtime stats per table object_id. */
                    ;WITH PlanTableRefs AS (
                        SELECT DISTINCT
                            qsp.plan_id,
                            PARSENAME(ref.value(''@Schema'',  ''sysname''), 1) AS ref_schema,
                            PARSENAME(ref.value(''@Table'',   ''sysname''), 1) AS ref_table
                        FROM sys.query_store_plan AS qsp
                        JOIN sys.query_store_runtime_stats AS qsrs
                            ON qsrs.plan_id = qsp.plan_id
                        JOIN sys.query_store_runtime_stats_interval AS qsrsi
                            ON qsrsi.runtime_stats_interval_id = qsrs.runtime_stats_interval_id
                        CROSS APPLY (SELECT TRY_CONVERT(xml, qsp.query_plan)) AS x(plan_xml)
                        CROSS APPLY x.plan_xml.nodes(''//*:Object'') AS t(ref)
                        WHERE qsrsi.end_time >= DATEADD(HOUR, -@QueryStoreRecentHours_param, SYSDATETIME())
                          AND x.plan_xml IS NOT NULL
                          AND ref.value(''@Table'', ''sysname'') IS NOT NULL
                    ),
                    FilteredRefs AS (
                        SELECT DISTINCT ptr.plan_id, sc.object_id
                        FROM PlanTableRefs AS ptr
                        JOIN (SELECT DISTINCT object_id, schema_name, table_name
                              FROM #stat_candidates) AS sc
                            ON sc.schema_name = ptr.ref_schema COLLATE DATABASE_DEFAULT
                            AND sc.table_name = ptr.ref_table COLLATE DATABASE_DEFAULT
                    ),
                    QSByTable AS (
                        SELECT
                            fr.object_id,
                            COUNT_BIG(DISTINCT fr.plan_id) AS plan_count,
                            SUM(qsrs2.count_executions) AS total_executions,
                            SUM(qsrs2.avg_cpu_time * qsrs2.count_executions) / 1000 AS total_cpu_ms,
                            SUM(qsrs2.avg_duration * qsrs2.count_executions) / 1000 AS total_duration_ms,
                            SUM(CONVERT(bigint, qsrs2.avg_logical_io_reads * qsrs2.count_executions)) AS total_logical_reads,
                            MAX(qsrs2.last_execution_time) AS last_execution
                        FROM FilteredRefs AS fr
                        JOIN sys.query_store_runtime_stats AS qsrs2
                            ON qsrs2.plan_id = fr.plan_id
                        JOIN sys.query_store_runtime_stats_interval AS qsrsi2
                            ON qsrsi2.runtime_stats_interval_id = qsrs2.runtime_stats_interval_id
                        WHERE qsrsi2.end_time >= DATEADD(HOUR, -@QueryStoreRecentHours_param, SYSDATETIME())
                        GROUP BY fr.object_id
                        HAVING SUM(qsrs2.count_executions) > 0
                    )
                    UPDATE sc
                    SET
                        sc.qs_plan_count = qs.plan_count,
                        sc.qs_total_executions = qs.total_executions,
                        sc.qs_total_cpu_ms = qs.total_cpu_ms,
                        sc.qs_total_duration_ms = qs.total_duration_ms,
                        sc.qs_total_logical_reads = qs.total_logical_reads,
                        sc.qs_last_execution = qs.last_execution,
                        sc.qs_priority_boost =
                            CASE
                                WHEN ISNULL(qs.total_executions, 0) >= @QueryStoreMinExecutions_param
                                THEN CASE @QueryStoreMetric_param
                                         WHEN N''CPU'' THEN ISNULL(qs.total_cpu_ms, 0)
                                         WHEN N''DURATION'' THEN ISNULL(qs.total_duration_ms, 0)
                                         WHEN N''READS'' THEN ISNULL(qs.total_logical_reads, 0) / 1000
                                         WHEN N''EXECUTIONS'' THEN ISNULL(qs.total_executions, 0)
                                         WHEN N''AVG_CPU'' THEN ISNULL(qs.total_cpu_ms, 0) / NULLIF(qs.total_executions, 0) /* avg CPU per execution */
                                         ELSE ISNULL(qs.total_cpu_ms, 0)
                                     END
                                ELSE 0
                            END
                    FROM #stat_candidates AS sc
                    INNER JOIN QSByTable AS qs ON qs.object_id = sc.object_id;
                END;

                SET @phase_ms = DATEDIFF(MILLISECOND, @phase_timer, SYSDATETIME());
                IF @Debug_param = 1
                    RAISERROR(N''    Phase 6 (Query Store): enriched (%d ms)'', 10, 1, @phase_ms) WITH NOWAIT;

                /*
                ================================================================
                FINAL: Return results with priority ordering
                ================================================================
                */
                SELECT
                    database_name = DB_NAME(),
                    schema_name,
                    table_name,
                    stat_name,
                    object_id,
                    stats_id,
                    no_recompute,
                    is_incremental,
                    is_memory_optimized,
                    ISNULL(is_heap, 0) AS is_heap,
                    ISNULL(auto_created, 0) AS auto_created,
                    ISNULL(modification_counter, 0) AS modification_counter,
                    row_count = ISNULL(rows, 0),
                    ISNULL(days_stale, 9999) AS days_stale,
                    ISNULL(page_count, 0) AS page_count,
                    persisted_sample_percent,
                    histogram_steps,
                    has_filter,
                    filter_definition,
                    unfiltered_rows,
                    qs_plan_count,
                    qs_total_executions,
                    qs_total_cpu_ms,
                    qs_total_duration_ms,
                    qs_total_logical_reads,
                    qs_last_execution,
                    ISNULL(qs_priority_boost, 0) AS qs_priority_boost,
                    is_published,
                    is_tracked_by_cdc,
                    temporal_type,
                    priority = ROW_NUMBER() OVER (
                        ORDER BY
                            /* #167: Filtered stats priority boost — when @FilteredStatsMode=PRIORITY, boost filtered stats showing drift */
                            CASE WHEN @FilteredStatsMode_param = N''PRIORITY''
                                      AND has_filter = 1
                                      AND ISNULL(rows, 0) > 0
                                      AND unfiltered_rows IS NOT NULL
                                      AND (CONVERT(float, unfiltered_rows) / rows) > @FilteredStatsStaleFactor_param
                                 THEN CONVERT(bigint, 500000000000)
                                 ELSE 0
                            END +
                            ISNULL(qs_priority_boost, 0) +
                            CASE @SortOrder_param
                                WHEN N''MODIFICATION_COUNTER'' THEN modification_counter
                                WHEN N''DAYS_STALE'' THEN days_stale
                                WHEN N''PAGE_COUNT'' THEN ISNULL(page_count, 0)
                                WHEN N''RANDOM'' THEN CHECKSUM(NEWID())
                                WHEN N''QUERY_STORE'' THEN ISNULL(qs_priority_boost, 0)
                                WHEN N''FILTERED_DRIFT'' THEN
                                    CASE WHEN has_filter = 1 AND ISNULL(rows, 0) > 0 AND unfiltered_rows IS NOT NULL
                                         THEN CONVERT(bigint, IIF((CONVERT(float, unfiltered_rows) / rows) > 9000000000000.0, 9000000000000.0, (CONVERT(float, unfiltered_rows) / rows)) * 1000000)
                                         ELSE 0
                                    END
                                WHEN N''AUTO_CREATED'' THEN
                                    /* User-created first (auto_created=0), then auto-created (1) */
                                    CASE WHEN ISNULL(auto_created, 0) = 0 THEN CONVERT(bigint, 1000000000000) ELSE 0 END + ISNULL(modification_counter, 0)
                                ELSE modification_counter
                            END DESC,
                            /* #185: Deterministic tie-breaker — stable order for same priority score */
                            object_id ASC,
                            stats_id ASC
                    )
                FROM #stat_candidates
                OPTION (MAX_GRANT_PERCENT = 25); /* Cap memory grant: prevents monopolizing server memory during maintenance — value replaced dynamically below */

                DROP TABLE #stat_candidates;
                ';

                /*
                P1a fix (v2.4): Parameterize MAX_GRANT_PERCENT in the candidate discovery SELECT.
                Replace hardcoded 25 with @MaxGrantPercent, or remove hint entirely when NULL.
                Gated on @supports_maxdop_stats (SQL 2016 SP2+) — older builds don't support the hint.
                */
                IF @MaxGrantPercent IS NOT NULL AND @supports_maxdop_stats = 1
                    SET @staged_sql = REPLACE(@staged_sql,
                        N'OPTION (MAX_GRANT_PERCENT = 25)',
                        N'OPTION (MAX_GRANT_PERCENT = ' + CAST(@MaxGrantPercent AS nvarchar(3)) + N')');
                ELSE
                    SET @staged_sql = REPLACE(@staged_sql,
                        N' OPTION (MAX_GRANT_PERCENT = 25);',
                        N';'); /* Remove hint when NULL or unsupported */

                /*
                Execute staged discovery and insert results
                */
                INSERT INTO #stats_to_process
                (
                    database_name, schema_name, table_name, stat_name, object_id, stats_id,
                    no_recompute, is_incremental, is_memory_optimized, is_heap, auto_created,
                    modification_counter, row_count, days_stale, page_count, persisted_sample_percent, histogram_steps,
                    has_filter, filter_definition, unfiltered_rows,
                    qs_plan_count, qs_total_executions, qs_total_cpu_ms, qs_total_duration_ms,
                    qs_total_logical_reads, qs_last_execution, qs_priority_boost,
                    is_published, is_tracked_by_cdc, temporal_type, priority
                )
                EXECUTE sys.sp_executesql
                    @staged_sql,
                    N'@SortOrder_param nvarchar(50),
                      @TargetNorecompute_param nvarchar(10),
                      @ModificationThreshold_param bigint,
                      @ModificationPercent_param float,
                      @TieredThresholds_param bit,
                      @ThresholdLogic_param nvarchar(3),
                      @DaysStaleThreshold_param integer,
                      @HoursStaleThreshold_param integer,
                      @MinPageCount_param bigint,
                      @IncludeSystemObjects_param nvarchar(1),
                      @Tables_param nvarchar(max),
                      @ExcludeTables_param nvarchar(max),
                      @ExcludeStatistics_param nvarchar(max),
                      @FilteredStatsMode_param nvarchar(10),
                      @FilteredStatsStaleFactor_param float,
                      @QueryStorePriority_param nvarchar(1),
                      @QueryStoreMetric_param nvarchar(20),
                      @QueryStoreMinExecutions_param bigint,
                      @QueryStoreRecentHours_param integer,
                      @SkipTablesWithColumnstore_param nchar(1),
                      @IncludeIndexedViews_param nvarchar(1),
                      @AscendingKeyBoost_param nvarchar(1),
                      @Debug_param bit',
                    @SortOrder_param = @SortOrder,
                    @TargetNorecompute_param = @TargetNorecompute,
                    @ModificationThreshold_param = @ModificationThreshold,
                    @ModificationPercent_param = @ModificationPercent,
                    @TieredThresholds_param = @TieredThresholds,
                    @ThresholdLogic_param = @ThresholdLogic,
                    @DaysStaleThreshold_param = @DaysStaleThreshold,
                    @HoursStaleThreshold_param = @HoursStaleThreshold,
                    @MinPageCount_param = @MinPageCount,
                    @IncludeSystemObjects_param = @IncludeSystemObjects,
                    @Tables_param = @Tables,
                    @ExcludeTables_param = @ExcludeTables,
                    @ExcludeStatistics_param = @ExcludeStatistics,
                    @FilteredStatsMode_param = @FilteredStatsMode,
                    @FilteredStatsStaleFactor_param = @FilteredStatsStaleFactor,
                    @QueryStorePriority_param = @QueryStorePriority,
                    @QueryStoreMetric_param = @QueryStoreMetric,
                    @QueryStoreMinExecutions_param = @QueryStoreMinExecutions,
                    @QueryStoreRecentHours_param = @QueryStoreRecentHours,
                    @SkipTablesWithColumnstore_param = @SkipTablesWithColumnstore,
                    @IncludeIndexedViews_param = @IncludeIndexedViews,
                    @AscendingKeyBoost_param = @AscendingKeyBoost,
                    @Debug_param = @Debug;
            END; /* End of staged discovery */

            /*
            FALLBACK: If staged discovery signaled failure, switch to legacy mode.
            The signal table #staged_discovery_failed is populated inside the dynamic SQL
            when unexpected row loss is detected between phases.
            Use @use_legacy_for_db as a per-database flag so @StagedDiscovery
            retains its original value for subsequent database iterations.
            */
            DECLARE @use_legacy_for_db bit = 0;

            IF  @StagedDiscovery = N'Y'
            AND EXISTS (SELECT 1 FROM #staged_discovery_failed)
            BEGIN
                DECLARE @fallback_reason nvarchar(500);
                SELECT TOP (1) @fallback_reason = reason FROM #staged_discovery_failed;

                RAISERROR(N'    Staged discovery failed: %s', 10, 1, @fallback_reason) WITH NOWAIT;
                RAISERROR(N'    Falling back to legacy single-query discovery...', 10, 1) WITH NOWAIT;

                /* Clear any partial results from staged attempt */
                DELETE FROM #stats_to_process WHERE database_name = @CurrentDatabaseName;

                SET @use_legacy_for_db = 1;
            END;

            /* Clean up signal table for next database iteration */
            DELETE FROM #staged_discovery_failed;

            IF @StagedDiscovery = N'N' OR @use_legacy_for_db = 1
            BEGIN
            /*
            ========================================================================
            LEGACY DISCOVERY (single-query approach)
            ========================================================================
            Build dynamic SQL to run in target database context

            HEAP HANDLING NOTES:
            ====================
            - Heaps have index_id = 0 in sys.indexes (clustered = 1, nonclustered > 1)
            - Correct identification: EXISTS (index_id = 0), NOT "NOT EXISTS (index_id = 1)"
            - PageCount: For all stats, get total table pages from heap (0) or clustered (1)
            - stats_id != index_id for column statistics (only index stats have stats_id = index_id)
            - Auto-created stats on heaps still use _WA_Sys_ prefix
            */
            SELECT
                @discovery_sql = N'
            USE ' + QUOTENAME(@CurrentDatabaseName) + N';

        /* FIX #271: Pre-compute QS plan-to-table mapping via plan XML extraction.
           Only populated when @QueryStorePriority = Y and QS is enabled. */
        IF OBJECT_ID(N''tempdb..#qs_table_stats'') IS NOT NULL
            DROP TABLE #qs_table_stats;

        CREATE TABLE #qs_table_stats (
            table_object_id int NOT NULL PRIMARY KEY,
            plan_count bigint NULL,
            total_executions bigint NULL,
            total_cpu_ms bigint NULL,
            total_duration_ms bigint NULL,
            total_logical_reads bigint NULL,
            last_execution datetime2(3) NULL
        );

        IF @QueryStorePriority_param = N''Y''
        AND EXISTS (SELECT 1 FROM sys.database_query_store_options WHERE actual_state IN (1, 2))
        BEGIN
            ;WITH PlanTableRefs AS (
                SELECT DISTINCT
                    qsp.plan_id,
                    PARSENAME(ref.value(''@Schema'', ''sysname''), 1) AS ref_schema,
                    PARSENAME(ref.value(''@Table'',  ''sysname''), 1) AS ref_table
                FROM sys.query_store_plan AS qsp
                JOIN sys.query_store_runtime_stats AS qsrs
                    ON qsrs.plan_id = qsp.plan_id
                JOIN sys.query_store_runtime_stats_interval AS qsrsi
                    ON qsrsi.runtime_stats_interval_id = qsrs.runtime_stats_interval_id
                CROSS APPLY (SELECT TRY_CONVERT(xml, qsp.query_plan)) AS x(plan_xml)
                CROSS APPLY x.plan_xml.nodes(''//*:Object'') AS t(ref)
                WHERE qsrsi.end_time >= DATEADD(HOUR, -@QueryStoreRecentHours_param, SYSDATETIME())
                  AND x.plan_xml IS NOT NULL
                  AND ref.value(''@Table'', ''sysname'') IS NOT NULL
            ),
            FilteredRefs AS (
                SELECT DISTINCT ptr.plan_id,
                    o2.object_id AS table_object_id
                FROM PlanTableRefs AS ptr
                JOIN sys.objects AS o2
                    ON o2.name = ptr.ref_table COLLATE DATABASE_DEFAULT
                JOIN sys.schemas AS s2
                    ON s2.schema_id = o2.schema_id
                    AND s2.name = ptr.ref_schema COLLATE DATABASE_DEFAULT
                WHERE OBJECTPROPERTY(o2.object_id, N''IsUserTable'') = 1
                   OR o2.type = N''V''
            )
            INSERT INTO #qs_table_stats
            SELECT
                fr.table_object_id,
                COUNT_BIG(DISTINCT fr.plan_id),
                SUM(qsrs2.count_executions),
                SUM(qsrs2.avg_cpu_time * qsrs2.count_executions) / 1000,
                SUM(qsrs2.avg_duration * qsrs2.count_executions) / 1000,
                SUM(CONVERT(bigint, qsrs2.avg_logical_io_reads * qsrs2.count_executions)),
                MAX(qsrs2.last_execution_time)
            FROM FilteredRefs AS fr
            JOIN sys.query_store_runtime_stats AS qsrs2
                ON qsrs2.plan_id = fr.plan_id
            JOIN sys.query_store_runtime_stats_interval AS qsrsi2
                ON qsrsi2.runtime_stats_interval_id = qsrs2.runtime_stats_interval_id
            WHERE qsrsi2.end_time >= DATEADD(HOUR, -@QueryStoreRecentHours_param, SYSDATETIME())
            GROUP BY fr.table_object_id
            HAVING SUM(qsrs2.count_executions) > 0;
        END;

        SELECT
            database_name = DB_NAME(),
            schema_name = OBJECT_SCHEMA_NAME(s.object_id),
            table_name = OBJECT_NAME(s.object_id),
            stat_name = s.name,
            object_id = s.object_id,
            stats_id = s.stats_id,
            no_recompute = s.no_recompute,
            is_incremental = s.is_incremental,
            is_memory_optimized = ISNULL(t.is_memory_optimized, 0),
            /*
            HEAP DETECTION: Check for index_id = 0 (heap) directly.
            Every table has either a heap (index_id=0) OR a clustered index (index_id=1), never both.
            */
            is_heap =
                CASE
                    WHEN EXISTS
                         (
                             SELECT
                                 1
                             FROM sys.indexes AS ix
                             WHERE ix.object_id = s.object_id
                             AND   ix.index_id = 0
                         )
                    THEN 1
                    ELSE 0
                END,
            auto_created = s.auto_created,
            modification_counter = ISNULL(sp.modification_counter, 0),
            row_count = ISNULL(sp.rows, 0),
            days_stale = ISNULL(DATEDIFF(DAY, sp.last_updated, SYSDATETIME()), 9999),
            page_count = ISNULL(pgs.total_pages, 0),
            persisted_sample_percent = sp.persisted_sample_percent,
            histogram_steps = sp.steps,
            /* Filtered statistics metadata */
            has_filter = s.has_filter,
            filter_definition = s.filter_definition,
            unfiltered_rows = sp.unfiltered_rows,
            /* Query Store priority (NULL if QS disabled or not requested) */
            qs_plan_count = qs_stats.plan_count,
            qs_total_executions = qs_stats.total_executions,
            qs_total_cpu_ms = qs_stats.total_cpu_ms,
            qs_total_duration_ms = qs_stats.total_duration_ms,
            qs_total_logical_reads = qs_stats.total_logical_reads,
            qs_last_execution = qs_stats.last_execution,
            /*
            Priority boost based on selected metric - uses resource consumption, not just execution count.
            Normalized to provide consistent ordering across metrics.
            */
            qs_priority_boost =
                CASE
                    WHEN @QueryStorePriority_param = N''Y''
                    AND  ISNULL(qs_stats.total_executions, 0) >= @QueryStoreMinExecutions_param
                    THEN CASE @QueryStoreMetric_param
                             WHEN N''CPU'' THEN ISNULL(qs_stats.total_cpu_ms, 0)
                             WHEN N''DURATION'' THEN ISNULL(qs_stats.total_duration_ms, 0)
                             WHEN N''READS'' THEN ISNULL(qs_stats.total_logical_reads, 0) / 1000 /* scale down */
                             WHEN N''EXECUTIONS'' THEN ISNULL(qs_stats.total_executions, 0)
                             WHEN N''AVG_CPU'' THEN ISNULL(qs_stats.total_cpu_ms, 0) / NULLIF(qs_stats.total_executions, 0) /* avg CPU per execution */
                             ELSE ISNULL(qs_stats.total_cpu_ms, 0) /* default to CPU */
                         END
                    ELSE 0
                END,
            /* Replication and temporal table awareness */
            is_published = ISNULL(t.is_published, 0),
            is_tracked_by_cdc = ISNULL(t.is_tracked_by_cdc, 0),
            temporal_type = ISNULL(t.temporal_type, 0),
            priority =
                ROW_NUMBER() OVER
                (
                    ORDER BY
                        /*
                        Query Store boost based on selected metric.
                        Uses actual resource consumption to prioritize expensive queries.
                        */
                        /* #167: Filtered stats priority boost — when @FilteredStatsMode=PRIORITY, boost filtered stats showing drift */
                        CASE WHEN @FilteredStatsMode_param = N''PRIORITY''
                                  AND s.has_filter = 1
                                  AND ISNULL(sp.rows, 0) > 0
                                  AND sp.unfiltered_rows IS NOT NULL
                                  AND (CONVERT(float, sp.unfiltered_rows) / sp.rows) > @FilteredStatsStaleFactor_param
                             THEN CONVERT(bigint, 500000000000)
                             ELSE 0
                        END +
                        CASE
                            WHEN @QueryStorePriority_param = N''Y''
                            AND  ISNULL(qs_stats.total_executions, 0) >= @QueryStoreMinExecutions_param
                            THEN CASE @QueryStoreMetric_param
                                     WHEN N''CPU'' THEN ISNULL(qs_stats.total_cpu_ms, 0)
                                     WHEN N''DURATION'' THEN ISNULL(qs_stats.total_duration_ms, 0)
                                     WHEN N''READS'' THEN ISNULL(qs_stats.total_logical_reads, 0) / 1000
                                     WHEN N''EXECUTIONS'' THEN ISNULL(qs_stats.total_executions, 0)
                                     WHEN N''AVG_CPU'' THEN ISNULL(qs_stats.total_cpu_ms, 0) / NULLIF(qs_stats.total_executions, 0)
                                     ELSE ISNULL(qs_stats.total_cpu_ms, 0)
                                 END
                            ELSE 0
                        END +
                        CASE @SortOrder_param
                            WHEN N''MODIFICATION_COUNTER''
                            THEN ISNULL(sp.modification_counter, 0)
                            WHEN N''DAYS_STALE''
                            THEN ISNULL(DATEDIFF(DAY, sp.last_updated, SYSDATETIME()), 9999)
                            WHEN N''PAGE_COUNT''
                            THEN ISNULL(pgs.total_pages, 0)
                            WHEN N''RANDOM''
                            THEN CHECKSUM(NEWID())
                            WHEN N''QUERY_STORE''
                            THEN CASE @QueryStoreMetric_param
                                     WHEN N''CPU'' THEN ISNULL(qs_stats.total_cpu_ms, 0)
                                     WHEN N''DURATION'' THEN ISNULL(qs_stats.total_duration_ms, 0)
                                     WHEN N''READS'' THEN ISNULL(qs_stats.total_logical_reads, 0) / 1000
                                     WHEN N''EXECUTIONS'' THEN ISNULL(qs_stats.total_executions, 0)
                                     WHEN N''AVG_CPU'' THEN ISNULL(qs_stats.total_cpu_ms, 0) / NULLIF(qs_stats.total_executions, 0)
                                     ELSE ISNULL(qs_stats.total_cpu_ms, 0)
                                 END
                            WHEN N''FILTERED_DRIFT''
                            THEN CASE
                                     WHEN s.has_filter = 1 AND ISNULL(sp.rows, 0) > 0 AND sp.unfiltered_rows IS NOT NULL
                                     THEN CONVERT(bigint, IIF((CONVERT(float, sp.unfiltered_rows) / sp.rows) > 9000000000000.0, 9000000000000.0, (CONVERT(float, sp.unfiltered_rows) / sp.rows)) * 1000000)
                                     ELSE 0
                                 END
                            WHEN N''AUTO_CREATED''
                            THEN /* User-created first (auto_created=0), then auto-created (1) */
                                 CASE WHEN ISNULL(s.auto_created, 0) = 0 THEN CONVERT(bigint, 1000000000000) ELSE 0 END + ISNULL(sp.modification_counter, 0)
                            ELSE ISNULL(sp.modification_counter, 0)
                        END DESC,
                        /* #185: Deterministic tie-breaker */
                        s.object_id ASC,
                        s.stats_id ASC
                )
        FROM sys.stats AS s
        JOIN sys.objects AS o
          ON o.object_id = s.object_id
        LEFT JOIN sys.tables AS t
          ON t.object_id = s.object_id
        CROSS APPLY sys.dm_db_stats_properties(s.object_id, s.stats_id) AS sp
        OUTER APPLY
        (
            /*
            PAGE COUNT: Get total table pages from the base table structure.
            - index_id = 0 for heaps
            - index_id = 1 for clustered indexes
            We always want the base table pages, regardless of which statistic we''re updating.
            Note: stats_id does NOT equal index_id for column statistics!
            */
            SELECT
                total_pages = SUM(p.used_page_count)
            FROM sys.dm_db_partition_stats AS p
            WHERE p.object_id = s.object_id
            AND   p.index_id IN (0, 1)
        ) AS pgs
        /*
        FIX #271: QS enrichment via plan XML table extraction (legacy path).
        Previous OUTER APPLY joined on qsq.object_id (MODULE id) to s.object_id
        (TABLE id) — different domains, zero matches for all workloads.
        Now uses pre-computed #qs_table_stats temp table populated from plan XML.
        */
        LEFT JOIN #qs_table_stats AS qs_stats
            ON qs_stats.table_object_id = s.object_id
        WHERE (o.is_ms_shipped = 0 OR @IncludeSystemObjects_param = N''Y'')
        AND   (
                  OBJECTPROPERTY(s.object_id, N''IsUserTable'') = 1
               OR @IncludeSystemObjects_param = N''Y''
               OR (o.type = N''V'' AND @IncludeIndexedViews_param = N''Y''
                   AND EXISTS (SELECT 1 FROM sys.indexes AS vi WHERE vi.object_id = s.object_id AND vi.index_id = 1))
              ) /* #49: Include indexed views when requested */
        AND   o.type NOT IN (N''ET'', N''S'') /* Exclude external tables (#54) and system tables */
        /* #55: Skip Stretch Database tables */
        AND   ISNULL(OBJECTPROPERTY(s.object_id, N''TableHasRemoteDataArchive''), 0) = 0
        /* Skip tables on READ_ONLY filegroups (#65) */
        AND   NOT EXISTS
              (
                  SELECT 1
                  FROM sys.indexes AS ri
                  JOIN sys.data_spaces AS rds ON rds.data_space_id = ri.data_space_id
                  JOIN sys.filegroups AS rfg ON rfg.data_space_id = rds.data_space_id
                  WHERE ri.object_id = s.object_id
                  AND   ri.index_id IN (0, 1) /* heap or clustered — the base storage */
                  AND   rfg.is_read_only = 1
              )
        /* NORECOMPUTE filter */
        AND   (
                  (@TargetNorecompute_param = N''N'' AND s.no_recompute = 0)
               OR (@TargetNorecompute_param = N''Y'' AND s.no_recompute = 1)
               OR @TargetNorecompute_param = N''BOTH''
              )
        /* Page count threshold (includes heaps via index_id IN (0, 1)) - always required */
        AND   ISNULL(pgs.total_pages, 0) >= @MinPageCount_param
        /*
        THRESHOLD LOGIC: OR vs AND mode
        ================================
        OR mode (default): stat qualifies if ANY threshold is met
        AND mode: stat qualifies only if ALL specified thresholds are met

        When @TieredThresholds_param = 1, uses Tiger Toolbox 5-tier formula:
          0-500 rows: 500 modifications OR SQRT(rows * 1000) - avoids cliff effect
          501-10K rows: 20% + 500 OR SQRT(rows * 1000)
          10K-100K rows: 15% + 500 OR SQRT(rows * 1000)
          100K-1M rows: 10% + 500 OR SQRT(rows * 1000)
          1M+ rows: 5% + 500 OR SQRT(rows * 1000)
        */
        AND   (
              (
                  /* OR Logic: Any threshold triggers update */
                  @ThresholdLogic_param = N''OR''
                  AND (
                      /* Modification threshold */
                      (
                          @ModificationThreshold_param IS NOT NULL
                          AND ISNULL(sp.modification_counter, 0) >= @ModificationThreshold_param
                      )
                      /* Modification percent (SQRT-based formula) - only if not using tiered */
                      OR (
                          @TieredThresholds_param = 0
                          AND @ModificationPercent_param IS NOT NULL
                          AND sp.modification_counter >= (@ModificationPercent_param * SQRT(ISNULL(sp.rows, 1)))
                      )
                      /* Tiered thresholds (Tiger Toolbox 5-tier adaptive formula) */
                      OR (
                          @TieredThresholds_param = 1
                          AND (
                              /* 0-500 rows: 500 modifications OR SQRT(rows * 1000) - avoids cliff effect at 500/501 boundary */
                              (ISNULL(sp.rows, 0) <= 500 AND (ISNULL(sp.modification_counter, 0) >= 500 OR ISNULL(sp.modification_counter, 0) >= SQRT(CONVERT(float, ISNULL(sp.rows, 1)) * 1000)))
                              /* 501-10K rows: 20% + 500 OR SQRT(rows * 1000) */
                              OR (ISNULL(sp.rows, 0) BETWEEN 501 AND 10000 AND (ISNULL(sp.modification_counter, 0) >= (ISNULL(sp.rows, 0) * 20) / 100 + 500 OR ISNULL(sp.modification_counter, 0) >= SQRT(CONVERT(float, ISNULL(sp.rows, 1)) * 1000)))
                              /* 10K-100K rows: 15% + 500 OR SQRT(rows * 1000) */
                              OR (ISNULL(sp.rows, 0) BETWEEN 10001 AND 100000 AND (ISNULL(sp.modification_counter, 0) >= (ISNULL(sp.rows, 0) * 15) / 100 + 500 OR ISNULL(sp.modification_counter, 0) >= SQRT(CONVERT(float, ISNULL(sp.rows, 1)) * 1000)))
                              /* 100K-1M rows: 10% + 500 OR SQRT(rows * 1000) */
                              OR (ISNULL(sp.rows, 0) BETWEEN 100001 AND 1000000 AND (ISNULL(sp.modification_counter, 0) >= (ISNULL(sp.rows, 0) * 10) / 100 + 500 OR ISNULL(sp.modification_counter, 0) >= SQRT(CONVERT(float, ISNULL(sp.rows, 1)) * 1000)))
                              /* 1M+ rows: 5% + 500 OR SQRT(rows * 1000) */
                              OR (ISNULL(sp.rows, 0) >= 1000001 AND (ISNULL(sp.modification_counter, 0) >= CONVERT(bigint, CONVERT(float, ISNULL(sp.rows, 0)) * 5 / 100) + 500 OR ISNULL(sp.modification_counter, 0) >= SQRT(CONVERT(float, ISNULL(sp.rows, 1)) * 1000)))
                          )
                      )
                      /* Days stale threshold */
                      OR (
                          @DaysStaleThreshold_param IS NOT NULL
                          AND ISNULL(DATEDIFF(DAY, sp.last_updated, SYSDATETIME()), 9999) >= @DaysStaleThreshold_param
                      )
                      /* Hours stale threshold (v2.3 - precise time-based, alternative to @DaysStaleThreshold) */
                      OR (
                          @HoursStaleThreshold_param IS NOT NULL
                          AND ISNULL(DATEDIFF(HOUR, sp.last_updated, SYSDATETIME()), 999999) >= @HoursStaleThreshold_param
                      )
                      /* If no thresholds specified, include all */
                      OR (
                          @ModificationThreshold_param IS NULL
                          AND @ModificationPercent_param IS NULL
                          AND @TieredThresholds_param = 0
                          AND @DaysStaleThreshold_param IS NULL
                          AND @HoursStaleThreshold_param IS NULL
                      )
                  )
              )
        OR    (
                  /* AND Logic: All specified thresholds must be met */
                  @ThresholdLogic_param = N''AND''
                  AND (
                      /* Modification threshold - must be met if specified */
                      @ModificationThreshold_param IS NULL
                      OR ISNULL(sp.modification_counter, 0) >= @ModificationThreshold_param
                  )
                  AND (
                      /* Modification percent OR Tiered - must be met if specified */
                      (@ModificationPercent_param IS NULL AND @TieredThresholds_param = 0)
                      OR (@TieredThresholds_param = 0 AND sp.modification_counter >= (@ModificationPercent_param * SQRT(ISNULL(sp.rows, 1))))
                      OR (@TieredThresholds_param = 1 AND (
                          (ISNULL(sp.rows, 0) <= 500 AND (ISNULL(sp.modification_counter, 0) >= 500 OR ISNULL(sp.modification_counter, 0) >= SQRT(CONVERT(float, ISNULL(sp.rows, 1)) * 1000)))
                          OR (ISNULL(sp.rows, 0) BETWEEN 501 AND 10000 AND (ISNULL(sp.modification_counter, 0) >= (ISNULL(sp.rows, 0) * 20) / 100 + 500 OR ISNULL(sp.modification_counter, 0) >= SQRT(CONVERT(float, ISNULL(sp.rows, 1)) * 1000)))
                          OR (ISNULL(sp.rows, 0) BETWEEN 10001 AND 100000 AND (ISNULL(sp.modification_counter, 0) >= (ISNULL(sp.rows, 0) * 15) / 100 + 500 OR ISNULL(sp.modification_counter, 0) >= SQRT(CONVERT(float, ISNULL(sp.rows, 1)) * 1000)))
                          OR (ISNULL(sp.rows, 0) BETWEEN 100001 AND 1000000 AND (ISNULL(sp.modification_counter, 0) >= (ISNULL(sp.rows, 0) * 10) / 100 + 500 OR ISNULL(sp.modification_counter, 0) >= SQRT(CONVERT(float, ISNULL(sp.rows, 1)) * 1000)))
                          OR (ISNULL(sp.rows, 0) >= 1000001 AND (ISNULL(sp.modification_counter, 0) >= CONVERT(bigint, CONVERT(float, ISNULL(sp.rows, 0)) * 5 / 100) + 500 OR ISNULL(sp.modification_counter, 0) >= SQRT(CONVERT(float, ISNULL(sp.rows, 1)) * 1000)))
                      ))
                  )
                  AND (
                      /* Days stale - must be met if specified */
                      @DaysStaleThreshold_param IS NULL
                      OR ISNULL(DATEDIFF(DAY, sp.last_updated, SYSDATETIME()), 9999) >= @DaysStaleThreshold_param
                  )
                  AND (
                      /* Hours stale (v2.3) - must be met if specified */
                      @HoursStaleThreshold_param IS NULL
                      OR ISNULL(DATEDIFF(HOUR, sp.last_updated, SYSDATETIME()), 999999) >= @HoursStaleThreshold_param
                  )
              )
              /* #143: Ascending key boost - identity column stats with any modifications bypass thresholds */
        OR    (
                  @AscendingKeyBoost_param = N''Y''
                  AND ISNULL(sp.modification_counter, 0) > 0
                  AND EXISTS (
                      SELECT 1
                      FROM sys.stats_columns AS stc
                      JOIN sys.identity_columns AS ic
                        ON ic.object_id = stc.object_id AND ic.column_id = stc.column_id
                      WHERE stc.object_id = s.object_id
                      AND   stc.stats_id = s.stats_id
                      AND   stc.stats_column_id = 1
                  )
              )
              ) /* End of threshold logic wrapper - ensures table/exclusion filters apply to both OR and AND modes */
        /* Table filter */
        AND   (
                  @Tables_param IS NULL
               OR OBJECT_SCHEMA_NAME(s.object_id) + N''.'' + OBJECT_NAME(s.object_id) COLLATE DATABASE_DEFAULT IN
                  (
                      SELECT
                          LTRIM(RTRIM(ss.value)) COLLATE DATABASE_DEFAULT
                      FROM STRING_SPLIT(@Tables_param, N'','') AS ss
                  )
               OR OBJECT_NAME(s.object_id) COLLATE DATABASE_DEFAULT IN
                  (
                      SELECT
                          LTRIM(RTRIM(ss.value)) COLLATE DATABASE_DEFAULT
                      FROM STRING_SPLIT(@Tables_param, N'','') AS ss
                  )
              )
        /* Table exclusion filter (pattern-based) */
        AND   (
                  @ExcludeTables_param IS NULL
               OR NOT EXISTS
                  (
                      SELECT 1
                      FROM STRING_SPLIT(@ExcludeTables_param, N'','') AS ex
                      WHERE OBJECT_SCHEMA_NAME(s.object_id) + N''.'' + OBJECT_NAME(s.object_id) COLLATE DATABASE_DEFAULT LIKE LTRIM(RTRIM(ex.value)) COLLATE DATABASE_DEFAULT
                  )
              )
        /* Statistics exclusion filter (pattern-based) */
        AND   (
                  @ExcludeStatistics_param IS NULL
               OR NOT EXISTS
                  (
                      SELECT 1
                      FROM STRING_SPLIT(@ExcludeStatistics_param, N'','') AS ex
                      WHERE s.name COLLATE DATABASE_DEFAULT LIKE LTRIM(RTRIM(ex.value)) COLLATE DATABASE_DEFAULT
                          OR s.name COLLATE DATABASE_DEFAULT = LTRIM(RTRIM(ex.value)) COLLATE DATABASE_DEFAULT
                  )
              )
        /*
        FILTERED STATISTICS FILTER
        ==========================
        INCLUDE (default) = normal behavior, include all stats
        EXCLUDE = skip filtered stats entirely
        ONLY = only process filtered stats
        PRIORITY = include all, but filtered stats with drift get priority boost
        */
        AND   (
                  @FilteredStatsMode_param = N''INCLUDE''
               OR @FilteredStatsMode_param = N''PRIORITY''
               OR (@FilteredStatsMode_param = N''EXCLUDE'' AND s.has_filter = 0)
               OR (@FilteredStatsMode_param = N''ONLY'' AND s.has_filter = 1)
              )
        /*
        FILTERED STATS STALENESS: In PRIORITY mode, filtered stats use a LOWER modification
        threshold proportional to their selectivity. A filter covering 10% of rows should
        update after 10% of the normal modifications (adjusted by @FilteredStatsStaleFactor).

        The formula: mod_counter >= @ModificationThreshold * selectivity * factor
        Where selectivity = rows / unfiltered_rows (0.1 for 10% filter)

        Note: unfiltered_rows/rows measures selectivity, not staleness. Filtered stats on
        small subsets need lower absolute thresholds since each modification has more impact.
        */
        AND   (
                  @FilteredStatsMode_param <> N''PRIORITY''
               OR s.has_filter = 0
               OR sp.unfiltered_rows IS NULL
               OR ISNULL(sp.rows, 0) = 0
               /* Filtered stat qualifies if mod_counter exceeds selectivity-adjusted threshold */
               OR ISNULL(sp.modification_counter, 0) >=
                  (@ModificationThreshold_param * @FilteredStatsStaleFactor_param *
                   (CONVERT(float, ISNULL(sp.rows, 1)) / CONVERT(float, ISNULL(sp.unfiltered_rows, 1))))
               /* Or if it meets the normal threshold anyway */
               OR ISNULL(sp.modification_counter, 0) >= @ModificationThreshold_param
              )
        /* v2.3: Skip tables with columnstore indexes when @SkipTablesWithColumnstore = Y */
        AND   (
                  @SkipTablesWithColumnstore_param = N''N''
               OR NOT EXISTS
                  (
                      SELECT 1
                      FROM sys.indexes AS ci
                      WHERE ci.object_id = s.object_id
                      AND   ci.type IN (5, 6) /* 5 = nonclustered columnstore, 6 = clustered columnstore */
                  )
              )
        ORDER BY
            priority
        OPTION (RECOMPILE);'; /*Prevents plan caching issues with varying parameters*/

            SELECT
                @discovery_params = N'
                @SortOrder_param nvarchar(50),
                @TargetNorecompute_param nvarchar(10),
                @ModificationThreshold_param bigint,
                @ModificationPercent_param float,
                @TieredThresholds_param bit,
                @ThresholdLogic_param nvarchar(3),
                @DaysStaleThreshold_param integer,
                @HoursStaleThreshold_param integer,
                @MinPageCount_param bigint,
                @IncludeSystemObjects_param nvarchar(1),
                @Tables_param nvarchar(max),
                @ExcludeTables_param nvarchar(max),
                @ExcludeStatistics_param nvarchar(max),
                @FilteredStatsMode_param nvarchar(10),
                @FilteredStatsStaleFactor_param float,
                @QueryStorePriority_param nvarchar(1),
                @QueryStoreMetric_param nvarchar(20),
                @QueryStoreMinExecutions_param bigint,
                @QueryStoreRecentHours_param integer,
                @SkipTablesWithColumnstore_param nchar(1),
                @IncludeIndexedViews_param nvarchar(1),
                @AscendingKeyBoost_param nvarchar(1)';

        /*
        Execute discovery in target database
        */
        INSERT INTO
            #stats_to_process
        (
            database_name,
            schema_name,
            table_name,
            stat_name,
            object_id,
            stats_id,
            no_recompute,
            is_incremental,
            is_memory_optimized,
            is_heap,
            auto_created,
            modification_counter,
            row_count,
            days_stale,
            page_count,
            persisted_sample_percent,
            histogram_steps,
            has_filter,
            filter_definition,
            unfiltered_rows,
            qs_plan_count,
            qs_total_executions,
            qs_total_cpu_ms,
            qs_total_duration_ms,
            qs_total_logical_reads,
            qs_last_execution,
            qs_priority_boost,
            is_published,
            is_tracked_by_cdc,
            temporal_type,
            priority
        )
            EXECUTE sys.sp_executesql
                @discovery_sql,
                @discovery_params,
                @SortOrder_param = @SortOrder,
                @TargetNorecompute_param = @TargetNorecompute,
                @ModificationThreshold_param = @ModificationThreshold,
                @ModificationPercent_param = @ModificationPercent,
                @TieredThresholds_param = @TieredThresholds,
                @ThresholdLogic_param = @ThresholdLogic,
                @DaysStaleThreshold_param = @DaysStaleThreshold,
                @HoursStaleThreshold_param = @HoursStaleThreshold,
                @MinPageCount_param = @MinPageCount,
                @IncludeSystemObjects_param = @IncludeSystemObjects,
                @Tables_param = @Tables,
                @ExcludeTables_param = @ExcludeTables,
                @ExcludeStatistics_param = @ExcludeStatistics,
                @FilteredStatsMode_param = @FilteredStatsMode,
                @FilteredStatsStaleFactor_param = @FilteredStatsStaleFactor,
                @QueryStorePriority_param = @QueryStorePriority,
                @QueryStoreMetric_param = @QueryStoreMetric,
                @QueryStoreMinExecutions_param = @QueryStoreMinExecutions,
                @QueryStoreRecentHours_param = @QueryStoreRecentHours,
                @SkipTablesWithColumnstore_param = @SkipTablesWithColumnstore,
                @IncludeIndexedViews_param = @IncludeIndexedViews,
                @AscendingKeyBoost_param = @AscendingKeyBoost;

            END; /* End of legacy discovery (explicit or fallback) */

            /*
            ================================================================
            POST-DISCOVERY PER-DATABASE DETECTION WARNINGS
            Lightweight checks on discovered stats for operational awareness.
            ================================================================
            */

            /* #60: RLS (Row-Level Security) detection — biased histogram risk */
            IF @Debug = 1
            BEGIN
                DECLARE @rls_check_sql nvarchar(max) = N'
                    SELECT @cnt = COUNT(DISTINCT sp.target_object_id)
                    FROM ' + QUOTENAME(@CurrentDatabaseName) + N'.sys.security_policies AS sp
                    INNER JOIN ' + QUOTENAME(@CurrentDatabaseName) + N'.sys.security_predicates AS spd
                        ON spd.object_id = sp.object_id
                    WHERE sp.is_enabled = 1
                    AND spd.target_object_id IN (
                        SELECT DISTINCT stp.object_id
                        FROM #stats_to_process AS stp
                        WHERE stp.database_name = @dbname COLLATE DATABASE_DEFAULT
                    )';
                DECLARE @rls_table_count int = 0;
                BEGIN TRY
                    EXEC sp_executesql @rls_check_sql,
                        N'@dbname sysname, @cnt int OUTPUT',
                        @dbname = @CurrentDatabaseName, @cnt = @rls_table_count OUTPUT;
                    IF @rls_table_count > 0
                    BEGIN
                        DECLARE @rls_msg nvarchar(500) = N'    RLS: ' + CONVERT(nvarchar(10), @rls_table_count)
                            + N' table(s) with Row-Level Security — histogram quality may vary by execution context';
                        RAISERROR(@rls_msg, 10, 1) WITH NOWAIT;
                        SET @warnings += N'RLS_DETECTED: ' + @CurrentDatabaseName + N'(' + CONVERT(nvarchar(10), @rls_table_count) + N' tables); ';
                    END;
                END TRY
                BEGIN CATCH /* RLS DMVs might not be accessible */ END CATCH;
            END;

            /* #59: Wide statistics detection (>8 columns) — tempdb/memory pressure risk */
            IF @Debug = 1
            BEGIN
                DECLARE @wide_check_sql nvarchar(max) = N'
                    SELECT @cnt = COUNT(*)
                    FROM (
                        SELECT sc2.object_id, sc2.stats_id, col_count = COUNT(*)
                        FROM ' + QUOTENAME(@CurrentDatabaseName) + N'.sys.stats_columns AS sc2
                        WHERE EXISTS (
                            SELECT 1 FROM #stats_to_process AS stp
                            WHERE stp.database_name = @dbname COLLATE DATABASE_DEFAULT
                            AND stp.object_id = sc2.object_id
                            AND stp.stats_id = sc2.stats_id
                        )
                        GROUP BY sc2.object_id, sc2.stats_id
                        HAVING COUNT(*) > 8
                    ) AS wide';
                DECLARE @wide_stat_count int = 0;
                BEGIN TRY
                    EXEC sp_executesql @wide_check_sql,
                        N'@dbname sysname, @cnt int OUTPUT',
                        @dbname = @CurrentDatabaseName, @cnt = @wide_stat_count OUTPUT;
                    IF @wide_stat_count > 0
                    BEGIN
                        DECLARE @wide_msg nvarchar(500) = N'    Wide Stats: ' + CONVERT(nvarchar(10), @wide_stat_count)
                            + N' statistic(s) with >8 columns — FULLSCAN may use significant tempdb/memory';
                        RAISERROR(@wide_msg, 10, 1) WITH NOWAIT;
                    END;
                END TRY
                BEGIN CATCH END CATCH;
            END;

            /* #38: Filtered index statistics — detect filter_definition mismatch */
            IF @Debug = 1
            BEGIN
                DECLARE @filter_check_sql nvarchar(max) = N'
                    SELECT @cnt = COUNT(*)
                    FROM ' + QUOTENAME(@CurrentDatabaseName) + N'.sys.stats AS st
                    INNER JOIN ' + QUOTENAME(@CurrentDatabaseName) + N'.sys.indexes AS ix
                        ON ix.object_id = st.object_id AND ix.name = st.name
                    WHERE st.has_filter = 1
                    AND ix.has_filter = 1
                    AND st.filter_definition <> ix.filter_definition
                    AND EXISTS (
                        SELECT 1 FROM #stats_to_process AS stp
                        WHERE stp.database_name = @dbname COLLATE DATABASE_DEFAULT
                        AND stp.object_id = st.object_id
                        AND stp.stats_id = st.stats_id
                    )';
                DECLARE @filter_mismatch_count int = 0;
                BEGIN TRY
                    EXEC sp_executesql @filter_check_sql,
                        N'@dbname sysname, @cnt int OUTPUT',
                        @dbname = @CurrentDatabaseName, @cnt = @filter_mismatch_count OUTPUT;
                    IF @filter_mismatch_count > 0
                    BEGIN
                        DECLARE @filter_msg nvarchar(500) = N'    Filter Mismatch: ' + CONVERT(nvarchar(10), @filter_mismatch_count)
                            + N' stat(s) with stale filter_definition (differs from index filter)';
                        RAISERROR(@filter_msg, 10, 1) WITH NOWAIT;
                        SET @warnings += N'FILTER_MISMATCH: ' + @CurrentDatabaseName + N'(' + CONVERT(nvarchar(10), @filter_mismatch_count) + N'); ';
                    END;
                END TRY
                BEGIN CATCH END CATCH;
            END;

            /* #28/#149: Columnstore context detection — always-on warning (promoted from debug-only) */
            BEGIN
                DECLARE @cs_check_sql nvarchar(max) = N'
                    SELECT @cnt = COUNT(DISTINCT stp.object_id)
                    FROM #stats_to_process AS stp
                    WHERE stp.database_name = @dbname COLLATE DATABASE_DEFAULT
                    AND EXISTS (
                        SELECT 1
                        FROM ' + QUOTENAME(@CurrentDatabaseName) + N'.sys.indexes AS csi
                        WHERE csi.object_id = stp.object_id
                        AND csi.type IN (5, 6) /* 5=NCCI, 6=CCI */
                    )';
                DECLARE @cs_table_count int = 0;
                BEGIN TRY
                    EXEC sp_executesql @cs_check_sql,
                        N'@dbname sysname, @cnt int OUTPUT',
                        @dbname = @CurrentDatabaseName, @cnt = @cs_table_count OUTPUT;
                    IF @cs_table_count > 0
                    BEGIN
                        DECLARE @cs_msg nvarchar(500) = N'    Columnstore: ' + CONVERT(nvarchar(10), @cs_table_count)
                            + N' table(s) with columnstore indexes — modification_counter may underreport after bulk loads';
                        RAISERROR(@cs_msg, 10, 1) WITH NOWAIT;
                        SET @warnings += N'COLUMNSTORE_TABLES: ' + CONVERT(nvarchar(10), @cs_table_count) + N' table(s) with columnstore indexes; ';
                    END;
                END TRY
                BEGIN CATCH END CATCH;
            END;

            /* #156: Compressed tables page_count inflation warning */
            IF @MinPageCount > 0
            BEGIN
                DECLARE @compressed_check_sql nvarchar(max) = N'
                    SELECT @cnt = COUNT(DISTINCT stp.object_id)
                    FROM #stats_to_process AS stp
                    INNER JOIN ' + QUOTENAME(@CurrentDatabaseName) + N'.sys.partitions AS p
                        ON p.object_id = stp.object_id AND p.index_id IN (0, 1)
                    WHERE stp.database_name = @dbname COLLATE DATABASE_DEFAULT
                    AND p.data_compression > 0';
                DECLARE @compressed_table_count int = 0;
                BEGIN TRY
                    EXEC sp_executesql @compressed_check_sql,
                        N'@dbname sysname, @cnt int OUTPUT',
                        @dbname = @CurrentDatabaseName, @cnt = @compressed_table_count OUTPUT;
                    IF @compressed_table_count > 0
                    BEGIN
                        DECLARE @comp_msg nvarchar(500) = N'    Compressed: ' + CONVERT(nvarchar(10), @compressed_table_count)
                            + N' table(s) — @MinPageCount uses compressed page counts (actual data may be larger)';
                        RAISERROR(@comp_msg, 10, 1) WITH NOWAIT;
                        SET @warnings += N'COMPRESSED_TABLES: ' + CONVERT(nvarchar(10), @compressed_table_count) + N' table(s) with compression — @MinPageCount uses compressed page counts; ';
                    END;
                END TRY
                BEGIN CATCH END CATCH;
            END;

            /* #30: Computed column statistics — non-persisted computed columns have higher update cost */
            IF @Debug = 1
            BEGIN
                DECLARE @cc_check_sql nvarchar(max) = N'
                    SELECT @cnt = COUNT(*)
                    FROM #stats_to_process AS stp
                    INNER JOIN ' + QUOTENAME(@CurrentDatabaseName) + N'.sys.stats_columns AS sc
                        ON sc.object_id = stp.object_id AND sc.stats_id = stp.stats_id AND sc.stats_column_id = 1
                    INNER JOIN ' + QUOTENAME(@CurrentDatabaseName) + N'.sys.computed_columns AS cc
                        ON cc.object_id = sc.object_id AND cc.column_id = sc.column_id
                    WHERE stp.database_name = @dbname COLLATE DATABASE_DEFAULT
                    AND cc.is_persisted = 0';
                DECLARE @cc_count int = 0;
                BEGIN TRY
                    EXEC sp_executesql @cc_check_sql,
                        N'@dbname sysname, @cnt int OUTPUT',
                        @dbname = @CurrentDatabaseName, @cnt = @cc_count OUTPUT;
                    IF @cc_count > 0
                    BEGIN
                        DECLARE @cc_msg nvarchar(500) = N'    Computed Cols: ' + CONVERT(nvarchar(10), @cc_count)
                            + N' stat(s) on non-persisted computed columns — higher scan cost';
                        RAISERROR(@cc_msg, 10, 1) WITH NOWAIT;
                    END;
                END TRY
                BEGIN CATCH END CATCH;
            END;

            END TRY
            BEGIN CATCH
                DECLARE @db_skip_msg nvarchar(4000) =
                    N'  WARNING: Skipping database ' + QUOTENAME(@CurrentDatabaseName) +
                    N' - ' + ERROR_MESSAGE();
                RAISERROR(@db_skip_msg, 10, 1) WITH NOWAIT;
                /* #204: Add per-database skip to @WarningsOut */
                SET @warnings += N'DB_SKIPPED: ' + @CurrentDatabaseName + N'; ';
            END CATCH;

            /*
            Mark this database as completed (runs for both staged and legacy)
            */
            UPDATE @tmpDatabases
            SET Completed = 1
            WHERE ID = @CurrentDatabaseID;

        END; /* End of WHILE database loop */

        /*
        #209: @Tables unqualified token multi-schema ambiguity warning.
        When a token in @Tables contains no dot (no schema prefix), it matches ALL schemas
        that have a table with that name. If the token matches tables in more than one schema
        within any database in this run, emit a WARNING so the caller can use 'schema.table'
        format to be precise.

        This check does NOT change matching behavior — all matched tables are still processed.
        It is purely diagnostic. A behavioral change (restrict to one schema) is a separate decision.

        The warning fires per (token, database) pair where multiple schemas are matched.
        Compatible with SQL 2016 (uses FOR XML PATH instead of STRING_AGG).
        */
        IF @Tables IS NOT NULL AND EXISTS (SELECT 1 FROM #stats_to_process)
        BEGIN
            DECLARE @ambig_warning nvarchar(max) = N'';

            SELECT @ambig_warning = @ambig_warning +
                N'TABLES_AMBIGUOUS: ''' + a.token + N''' matched '
                + CONVERT(nvarchar(10), a.schema_count) + N' schemas in [' + a.database_name + N'] ('
                + a.schema_list + N'). Use ''schema.table'' to target a specific table; '
            FROM (
                SELECT
                    token            = LTRIM(RTRIM(ss.value)),
                    database_name    = stp.database_name,
                    schema_count     = COUNT(DISTINCT stp.schema_name),
                    schema_list      = STUFF(
                                           (   SELECT N', ' + stp2.schema_name
                                               FROM #stats_to_process AS stp2
                                               WHERE stp2.table_name COLLATE DATABASE_DEFAULT
                                                     = LTRIM(RTRIM(ss.value)) COLLATE DATABASE_DEFAULT
                                               AND   stp2.database_name = stp.database_name
                                               GROUP BY stp2.schema_name
                                               ORDER BY stp2.schema_name
                                               FOR XML PATH(N''), TYPE
                                           ).value(N'.', N'nvarchar(max)')
                                           , 1, 2, N'')
                FROM STRING_SPLIT(@Tables, N',') AS ss
                INNER JOIN #stats_to_process AS stp
                    ON stp.table_name COLLATE DATABASE_DEFAULT
                       = LTRIM(RTRIM(ss.value)) COLLATE DATABASE_DEFAULT
                /* Unqualified token: no dot means no explicit schema prefix */
                WHERE CHARINDEX(N'.', LTRIM(RTRIM(ss.value))) = 0
                GROUP BY LTRIM(RTRIM(ss.value)), stp.database_name
                HAVING COUNT(DISTINCT stp.schema_name) > 1
            ) AS a;

            IF LEN(@ambig_warning) > 0
            BEGIN
                RAISERROR(N'WARNING: Unqualified @Tables token(s) matched multiple schemas — all matched tables are included. Specify ''schema.table'' format to target a specific table. %s', 10, 1, @ambig_warning) WITH NOWAIT;
                SET @warnings += @ambig_warning;
            END;
        END;

    END; /* End of IF @mode = N'DISCOVERY' */
    /*#endregion 16-DISCOVERY */

    /*#region 17-POST-DISCOVERY: Join patterns, stats report, early return */
    /*
    ============================================================================
    JOIN PATTERN GROUPING (v1.9 - optimization cliff prevention)
    ============================================================================
    When @GroupByJoinPattern = 'Y', analyze Query Store to find tables that are
    commonly joined together, and assign them the same join_group_id.

    Rationale: Partial statistics updates can create INCONSISTENT cardinality
    estimates between joined tables. Table A is updated (accurate), Table B is
    stale - the optimizer sees wrong ratios and picks wrong join orders.

    Solution: Update related tables together. Same join group = same run.
    */
    IF  @GroupByJoinPattern = N'Y'
    AND @mode = N'DISCOVERY'
    AND EXISTS (SELECT 1 FROM #stats_to_process)
    BEGIN
        RAISERROR(N'', 10, 1) WITH NOWAIT;
        RAISERROR(N'Join Pattern Analysis:', 10, 1) WITH NOWAIT;

        DECLARE @join_groups TABLE (
            database_name sysname,
            object_id int,
            join_group_id int,
            PRIMARY KEY (database_name, object_id)
        );

        /*
        For each database, query Query Store to find which tables commonly
        appear in the same queries (proxy for join relationships).
        */
        DECLARE
            @current_join_db sysname,
            @join_sql nvarchar(max);

        DECLARE join_cursor CURSOR LOCAL FAST_FORWARD FOR
            SELECT DISTINCT database_name
            FROM #stats_to_process;

        OPEN join_cursor;
        FETCH NEXT FROM join_cursor INTO @current_join_db;

        WHILE @@FETCH_STATUS = 0
        BEGIN
            /*
            SIMPLIFIED APPROACH:
            1. Get distinct object_ids from our discovered stats for this database
            2. Find which tables appear together in Query Store queries
            3. Assign group IDs based on co-occurrence

            We use the context_settings_id (within a module like stored proc)
            as a grouping key - tables referenced by the same module are
            likely to be joined together.
            */
            SET @join_sql = N'
            USE ' + QUOTENAME(@current_join_db) + N';

            /* Only proceed if Query Store is enabled and readable */
            IF EXISTS (SELECT 1 FROM sys.database_query_store_options WHERE actual_state IN (1, 2))
            BEGIN
                /*
                Group tables by the context (procedure/module) they appear in.
                Tables used by the same stored procedure are often joined together.
                */
                ;WITH ContextObjects AS (
                    SELECT DISTINCT
                        qsq.context_settings_id,
                        qsq.object_id
                    FROM sys.query_store_query AS qsq
                    JOIN sys.query_store_plan AS qsp ON qsp.query_id = qsq.query_id
                    JOIN sys.query_store_runtime_stats AS qsrs ON qsrs.plan_id = qsp.plan_id
                    WHERE qsq.object_id IS NOT NULL
                    AND   qsrs.count_executions >= ' + CONVERT(nvarchar(20), @JoinPatternMinExecutions) + N'
                ),
                /* Assign group based on minimum object_id per context */
                ObjectGroups AS (
                    SELECT
                        co.object_id,
                        MIN(co.object_id) OVER (PARTITION BY co.context_settings_id) AS group_anchor
                    FROM ContextObjects co
                )
                SELECT DISTINCT
                    database_name = DB_NAME(),
                    object_id,
                    join_group_id = DENSE_RANK() OVER (ORDER BY group_anchor)
                FROM ObjectGroups;
            END';

            BEGIN TRY
                INSERT INTO @join_groups (database_name, object_id, join_group_id)
                EXEC sys.sp_executesql @join_sql;
            END TRY
            BEGIN CATCH
                /* If Query Store query fails, continue without grouping for this database */
                IF @Debug = 1
                BEGIN
                    DECLARE @join_err nvarchar(500) = LEFT(ERROR_MESSAGE(), 500);
                    RAISERROR(N'  Warning: Join pattern analysis failed for %s: %s', 10, 1,
                        @current_join_db, @join_err) WITH NOWAIT;
                END;
            END CATCH;

            FETCH NEXT FROM join_cursor INTO @current_join_db;
        END;

        CLOSE join_cursor;
        DEALLOCATE join_cursor;

        /* Apply join groups to discovered stats (only for objects found in Query Store) */
        IF EXISTS (SELECT 1 FROM @join_groups)
        BEGIN
            UPDATE stp
            SET stp.join_group_id = jg.join_group_id
            FROM #stats_to_process AS stp
            JOIN @join_groups AS jg
                ON jg.database_name = stp.database_name
                AND jg.object_id = stp.object_id;

            DECLARE
                @grouped_count int = (SELECT COUNT(DISTINCT join_group_id) FROM #stats_to_process WHERE join_group_id IS NOT NULL),
                @tables_grouped int = (SELECT COUNT(DISTINCT CONCAT(database_name, '.', object_id))
                                       FROM #stats_to_process WHERE join_group_id IS NOT NULL);

            RAISERROR(N'  Found %d join groups covering %d tables', 10, 1, @grouped_count, @tables_grouped) WITH NOWAIT;

            /*
            Re-prioritize: stats in the same join group should be processed together.
            Update priority so group_id is the primary sort, then original priority within group.
            Ungrouped stats (join_group_id IS NULL) come last.
            */
            ;WITH RankedStats AS (
                SELECT
                    id,
                    ROW_NUMBER() OVER (
                        ORDER BY
                            CASE WHEN join_group_id IS NULL THEN 1 ELSE 0 END, /* Grouped first */
                            join_group_id, /* Then by group ID */
                            priority /* Original priority within each group */
                    ) AS new_priority
                FROM #stats_to_process
            )
            UPDATE stp
            SET stp.priority = rs.new_priority
            FROM #stats_to_process AS stp
            JOIN RankedStats AS rs ON rs.id = stp.id;

            IF @Debug = 1
            BEGIN
                RAISERROR(N'  Re-prioritized stats to process join groups together', 10, 1) WITH NOWAIT;
            END;
        END;
        ELSE
        BEGIN
            RAISERROR(N'  No join patterns detected (Query Store may be disabled or empty)', 10, 1) WITH NOWAIT;
        END;
    END;

    /*
    ============================================================================
    TEMPORAL HISTORY TABLE CO-SCHEDULING (#201)
    ============================================================================
    When a system-versioned temporal table (temporal_type=2) qualifies for update,
    also schedule its history table stats. Prevents cross-table cardinality
    inconsistency for FOR SYSTEM_TIME queries that join current + history tables.
    */
    IF  @TemporalCoSchedule = N'Y'
    AND @mode = N'DISCOVERY'
    AND EXISTS (SELECT 1 FROM #stats_to_process WHERE temporal_type = 2)
    BEGIN
        DECLARE
            @temporal_db sysname,
            @temporal_sql nvarchar(max),
            @temporal_coscheduled int = 0;

        DECLARE temporal_cursor CURSOR LOCAL FAST_FORWARD FOR
            SELECT DISTINCT database_name
            FROM #stats_to_process
            WHERE temporal_type = 2;

        OPEN temporal_cursor;
        FETCH NEXT FROM temporal_cursor INTO @temporal_db;

        WHILE @@FETCH_STATUS = 0
        BEGIN
            /*
            For each database with temporal tables in the result set,
            find history table stats that aren't already scheduled.
            Uses sys.tables.history_table_id to link current → history.
            */
            SET @temporal_sql = N'
                SELECT
                    database_name = @db_param,
                    schema_name = OBJECT_SCHEMA_NAME(hs.object_id),
                    table_name = OBJECT_NAME(hs.object_id),
                    stat_name = hs.name,
                    object_id = hs.object_id,
                    stats_id = hs.stats_id,
                    no_recompute = hs.no_recompute,
                    is_incremental = hs.is_incremental,
                    is_memory_optimized = 0,
                    is_heap = CASE WHEN NOT EXISTS (
                        SELECT 1 FROM sys.indexes AS ix
                        WHERE ix.object_id = hs.object_id AND ix.index_id = 1
                    ) THEN 1 ELSE 0 END,
                    auto_created = hs.auto_created,
                    is_published = ISNULL(ht.is_published, 0),
                    is_tracked_by_cdc = ISNULL(ht.is_tracked_by_cdc, 0),
                    temporal_type = ISNULL(ht.temporal_type, 1),
                    modification_counter = ISNULL(sp.modification_counter, 0),
                    row_count = ISNULL(sp.rows, 0),
                    days_stale = ISNULL(DATEDIFF(DAY, sp.last_updated, SYSDATETIME()), 999),
                    page_count = ISNULL(
                        (SELECT SUM(ps.used_page_count)
                         FROM sys.dm_db_partition_stats AS ps
                         WHERE ps.object_id = hs.object_id AND ps.index_id IN (0, 1)), 0)
                FROM sys.stats AS hs
                JOIN sys.tables AS ht ON ht.object_id = hs.object_id
                CROSS APPLY sys.dm_db_stats_properties(hs.object_id, hs.stats_id) AS sp
                WHERE ht.temporal_type = 1
                AND   ht.object_id IN (
                    SELECT ct.history_table_id
                    FROM sys.tables AS ct
                    WHERE ct.temporal_type = 2
                    AND   ct.object_id IN (
                        SELECT DISTINCT stp.object_id
                        FROM #stats_to_process AS stp
                        WHERE stp.database_name = @db_param
                        AND   stp.temporal_type = 2
                    )
                )
                AND   NOT EXISTS (
                    SELECT 1
                    FROM #stats_to_process AS existing
                    WHERE existing.database_name = @db_param
                    AND   existing.object_id = hs.object_id
                    AND   existing.stats_id = hs.stats_id
                );';

            BEGIN TRY
                DECLARE @temporal_full_sql nvarchar(max) =
                    N'USE ' + QUOTENAME(@temporal_db) + N'; ' + @temporal_sql;

                INSERT INTO #stats_to_process
                (
                    database_name, schema_name, table_name, stat_name,
                    object_id, stats_id, no_recompute, is_incremental,
                    is_memory_optimized, is_heap, auto_created,
                    is_published, is_tracked_by_cdc, temporal_type,
                    modification_counter, row_count, days_stale, page_count,
                    priority
                )
                EXEC sys.sp_executesql
                    @temporal_full_sql,
                    N'@db_param sysname',
                    @db_param = @temporal_db;

                SET @temporal_coscheduled += @@ROWCOUNT;
            END TRY
            BEGIN CATCH
                IF @Debug = 1
                BEGIN
                    DECLARE @temporal_err nvarchar(500) = ERROR_MESSAGE();
                    RAISERROR(N'  Temporal co-schedule warning (%s): %s', 10, 1, @temporal_db, @temporal_err) WITH NOWAIT;
                END;
            END CATCH;

            FETCH NEXT FROM temporal_cursor INTO @temporal_db;
        END;

        CLOSE temporal_cursor;
        DEALLOCATE temporal_cursor;

        IF @temporal_coscheduled > 0
        BEGIN
            DECLARE @temporal_msg nvarchar(200);
            SET @temporal_msg = N'Temporal co-schedule: Added ' +
                CONVERT(nvarchar(10), @temporal_coscheduled) +
                N' history table stat(s) for consistency';
            RAISERROR(@temporal_msg, 10, 1) WITH NOWAIT;

            /* Assign priority to co-scheduled stats — place them right after their parent tables */
            UPDATE stp
            SET stp.priority = parent.max_priority + 1
            FROM #stats_to_process AS stp
            CROSS APPLY (
                SELECT max_priority = MAX(p.priority)
                FROM #stats_to_process AS p
                WHERE p.database_name = stp.database_name
                AND   p.temporal_type = 2
            ) AS parent
            WHERE stp.priority = 0
            AND   stp.temporal_type = 1;
        END;
    END;

    /*
    ============================================================================
    REPORT DISCOVERED STATISTICS
    ============================================================================
    */
    DECLARE
        @total_stats integer =
        (
            SELECT
                COUNT_BIG(*)
            FROM #stats_to_process
        ),
        @norecompute_stats integer =
        (
            SELECT
                COUNT_BIG(*)
            FROM #stats_to_process AS stp
            WHERE stp.no_recompute = 1
        ),
        @incremental_stats integer =
        (
            SELECT
                COUNT_BIG(*)
            FROM #stats_to_process AS stp
            WHERE stp.is_incremental = 1
        ),
        @heap_stats integer =
        (
            SELECT
                COUNT_BIG(*)
            FROM #stats_to_process AS stp
            WHERE stp.is_heap = 1
        ),
        @memory_optimized_stats integer =
        (
            SELECT
                COUNT_BIG(*)
            FROM #stats_to_process AS stp
            WHERE stp.is_memory_optimized = 1
        ),
        @persisted_sample_stats integer =
        (
            SELECT
                COUNT_BIG(*)
            FROM #stats_to_process AS stp
            WHERE stp.persisted_sample_percent IS NOT NULL
        );

    RAISERROR(N'', 10, 1) WITH NOWAIT;
    RAISERROR(N'Found %d qualifying statistics:', 10, 1, @total_stats) WITH NOWAIT;
    RAISERROR(N'  - NORECOMPUTE:      %d', 10, 1, @norecompute_stats) WITH NOWAIT;
    RAISERROR(N'  - Incremental:      %d', 10, 1, @incremental_stats) WITH NOWAIT;
    RAISERROR(N'  - On heaps:         %d', 10, 1, @heap_stats) WITH NOWAIT;
    RAISERROR(N'  - Memory-optimized: %d', 10, 1, @memory_optimized_stats) WITH NOWAIT;
    RAISERROR(N'  - Persisted sample: %d', 10, 1, @persisted_sample_stats) WITH NOWAIT;

    /* #147: CDC-tracked tables warning — stats updates can delay CDC capture */
    DECLARE @cdc_stats int = (SELECT COUNT_BIG(*) FROM #stats_to_process WHERE is_tracked_by_cdc = 1);
    IF @cdc_stats > 0
    BEGIN
        RAISERROR(N'  - CDC-tracked:      %d (FULLSCAN may delay CDC capture job)', 10, 1, @cdc_stats) WITH NOWAIT;
        SET @warnings += N'CDC_TABLES: ' + CONVERT(nvarchar(10), @cdc_stats) + N' stats on CDC-tracked tables; ';
    END;

    /* #192: Warn when replicated tables are a majority of candidates */
    DECLARE @replicated_stats int = (SELECT COUNT_BIG(*) FROM #stats_to_process WHERE is_published = 1);
    IF @replicated_stats > 0 AND @total_stats > 0
    BEGIN
        DECLARE @repl_pct int = @replicated_stats * 100 / @total_stats;
        RAISERROR(N'  - Replicated:       %d (%d%%)', 10, 1, @replicated_stats, @repl_pct) WITH NOWAIT;
        IF @repl_pct > 50
        BEGIN
            RAISERROR(N'  WARNING: >50%% of candidates are on replicated tables. Statistics updates', 10, 1) WITH NOWAIT;
            RAISERROR(N'  generate log records that replicate to subscribers — monitor replication lag.', 10, 1) WITH NOWAIT;
            SET @warnings += N'REPLICATION_MAJORITY: ' + CONVERT(nvarchar(10), @repl_pct) + N'%% of stats on replicated tables; ';
        END;
    END;

    RAISERROR(N'', 10, 1) WITH NOWAIT;

    IF @total_stats = 0
    BEGIN
        RAISERROR(N'No statistics qualify for update. Exiting.', 10, 1) WITH NOWAIT;

        /*
        Set OUTPUT parameters before early return
        */
        SELECT
            @StatsFoundOut = 0,
            @StatsProcessedOut = 0,
            @StatsSucceededOut = 0,
            @StatsFailedOut = 0,
            @StatsRemainingOut = 0,
            @DurationSecondsOut = DATEDIFF(SECOND, @start_time, SYSDATETIME()),
            @WarningsOut = NULLIF(@warnings, N''),
            @StopReasonOut = N'NO_QUALIFYING_STATS';

        /*
        Return summary result set even on early exit (0 qualifying stats).
        Without this, INSERT #Summary EXEC sp_StatUpdate gets no rows.
        */
        SELECT
            Status = N'SUCCESS',
            StatusMessage = N'No statistics qualify for update',
            StatsFound = 0,
            StatsProcessed = 0,
            StatsSucceeded = 0,
            StatsFailed = 0,
            StatsToctou = 0,
            StatsSkipped = 0,
            StatsRemaining = 0,
            DatabasesProcessed = @database_count,
            DurationSeconds = DATEDIFF(SECOND, @start_time, SYSDATETIME()),
            StopReason = CONVERT(nvarchar(50), N'NO_QUALIFYING_STATS'),
            RunLabel = @run_label,
            Version = @procedure_version;

        IF @StatsInParallel = N'N'
            EXEC sp_releaseapplock @Resource = N'sp_StatUpdate', @LockOwner = N'Session';
        RETURN 0;
    END;
    /*#endregion 17-POST-DISCOVERY */

    /*#region 18-PARALLEL-QUEUE: Queue initialization, candidate display */
    /*
    ============================================================================
    PARALLEL MODE: QUEUE INITIALIZATION
    ============================================================================

    When @StatsInParallel = 'Y':
    - First worker creates/claims Queue row and populates QueueStatistic
    - QueueStatistic stores ONE ROW PER TABLE (not per stat)
    - This ensures no two workers update stats on the same table concurrently
    - Dead workers detected via sys.dm_exec_sessions (sleeping workers between stats appear in dm_exec_sessions but not dm_exec_requests)

    Queue claim uses UPDLOCK, HOLDLOCK pattern from Ola Hallengren.
    */
    IF @StatsInParallel = N'Y'
    BEGIN
        RAISERROR(N'', 10, 1) WITH NOWAIT;
        RAISERROR(N'Parallel mode: Initializing work queue...', 10, 1) WITH NOWAIT;

        /*
        v2.3: Backward-compatible migration — add ParameterFingerprint to dbo.Queue if missing.
        Allows detecting conflicting parameter sets when multiple workers join the same queue.
        */
        IF  OBJECT_ID(N'dbo.Queue', N'U') IS NOT NULL
        AND NOT EXISTS (SELECT 1 FROM sys.columns WHERE object_id = OBJECT_ID(N'dbo.Queue') AND name = N'ParameterFingerprint')
        BEGIN
            BEGIN TRY
                ALTER TABLE dbo.Queue ADD ParameterFingerprint int NULL;
                IF @Debug = 1
                    RAISERROR(N'  Added ParameterFingerprint column to dbo.Queue (v2.3 migration).', 10, 1) WITH NOWAIT;
            END TRY
            BEGIN CATCH
                /* Non-blocking: if ALTER fails (e.g., permissions), proceed without fingerprint */
                IF @Debug = 1
                BEGIN
                    DECLARE @fp_alter_err nvarchar(500) = ERROR_MESSAGE();
                    RAISERROR(N'  Warning: Could not add ParameterFingerprint to dbo.Queue: %s', 10, 1, @fp_alter_err) WITH NOWAIT;
                END;
            END CATCH;
        END;

        /*
        v2.3: Compute parameter fingerprint for conflict detection.
        CHECKSUM of key threshold parameters that define what qualifies for update.
        If two workers compute different fingerprints, they have incompatible criteria.
        */
        DECLARE @parameter_fingerprint int = CHECKSUM(
            ISNULL(CONVERT(nvarchar(10), @TieredThresholds), N'NULL'),
            ISNULL(CONVERT(nvarchar(20), @ModificationThreshold), N'NULL'),
            ISNULL(CONVERT(nvarchar(20), @ModificationPercent), N'NULL'),
            ISNULL(CONVERT(nvarchar(20), @DaysStaleThreshold), N'NULL'),
            ISNULL(CONVERT(nvarchar(20), @HoursStaleThreshold), N'NULL'),
            ISNULL(@QueryStoreMetric, N'NULL')
        );

        /*
        Build parameters string to identify this run.
        Workers with matching parameters share the same queue.
        */
        /*
        Normalize parameter values with TRIM to prevent duplicate queues from
        whitespace differences (e.g., 'MyDB' vs ' MyDB').
        */
        SELECT
            @parameters_string =
                N'@Databases=' + ISNULL(LTRIM(RTRIM(@Databases)), N'') +
                N',@Tables=' + ISNULL(LTRIM(RTRIM(@Tables)), N'') +
                N',@TargetNorecompute=' + ISNULL(LTRIM(RTRIM(@TargetNorecompute)), N'') +
                N',@ModificationThreshold=' + ISNULL(CONVERT(nvarchar(20), @ModificationThreshold), N'') +
                N',@MinPageCount=' + ISNULL(CONVERT(nvarchar(20), @MinPageCount), N'') +
                N',@IncludeSystemObjects=' + ISNULL(LTRIM(RTRIM(@IncludeSystemObjects)), N'') +
                N',@SortOrder=' + ISNULL(LTRIM(RTRIM(@SortOrder)), N'');

        BEGIN TRY
            /*
            Check if Queue row already exists for these parameters
            */
            SELECT
                @queue_id = q.QueueID
            FROM dbo.Queue AS q
            WHERE q.SchemaName = N'dbo'
            AND   q.ObjectName = N'sp_StatUpdate'
            AND   q.Parameters = @parameters_string;

            IF @queue_id IS NULL
            BEGIN
                /*
                No existing queue - this worker will create it.
                Use UPDLOCK, HOLDLOCK to prevent race condition.
                */
                BEGIN TRANSACTION;

                SELECT
                    @queue_id = q.QueueID
                FROM dbo.Queue AS q WITH (UPDLOCK, HOLDLOCK)
                WHERE q.SchemaName = N'dbo'
                AND   q.ObjectName = N'sp_StatUpdate'
                AND   q.Parameters = @parameters_string;

                IF @queue_id IS NULL
                BEGIN
                    INSERT INTO
                        dbo.Queue
                    (
                        SchemaName,
                        ObjectName,
                        Parameters
                    )
                    SELECT
                        SchemaName = N'dbo',
                        ObjectName = N'sp_StatUpdate',
                        Parameters = @parameters_string;

                    SET @queue_id = SCOPE_IDENTITY();

                    RAISERROR(N'  Created new queue (QueueID = %d)', 10, 1, @queue_id) WITH NOWAIT;

                    /* v2.3: Store parameter fingerprint for conflict detection */
                    /* Uses dynamic SQL to avoid compile-time column validation when column doesn't exist yet */
                    BEGIN TRY
                        IF EXISTS (SELECT 1 FROM sys.columns WHERE object_id = OBJECT_ID(N'dbo.Queue') AND name = N'ParameterFingerprint')
                        BEGIN
                            EXEC sp_executesql
                                N'UPDATE dbo.Queue SET ParameterFingerprint = @fp WHERE QueueID = @qid;',
                                N'@fp int, @qid int',
                                @fp = @parameter_fingerprint,
                                @qid = @queue_id;
                        END;
                    END TRY
                    BEGIN CATCH
                        /* Non-blocking: fingerprint is diagnostic, not critical */
                    END CATCH;
                END

                COMMIT TRANSACTION;

                /* v2.3: After transaction, check parameter fingerprint for conflict detection */
                /* (Done outside transaction to avoid leaving open txn on conflict RETURN) */
                /* Uses dynamic SQL to avoid compile-time column validation when column doesn't exist yet */
                BEGIN TRY
                    IF EXISTS (SELECT 1 FROM sys.columns WHERE object_id = OBJECT_ID(N'dbo.Queue') AND name = N'ParameterFingerprint')
                    BEGIN
                        DECLARE @stored_fingerprint int;
                        EXEC sp_executesql
                            N'SELECT @fp = ParameterFingerprint FROM dbo.Queue WHERE QueueID = @qid;',
                            N'@fp int OUTPUT, @qid int',
                            @fp = @stored_fingerprint OUTPUT,
                            @qid = @queue_id;

                        IF  @stored_fingerprint IS NOT NULL
                        AND @stored_fingerprint <> @parameter_fingerprint
                        BEGIN
                            RAISERROR(N'Conflicting sp_StatUpdate parameters detected. Worker cannot join existing queue initialized with different threshold parameters. (Stored fingerprint: %d, This worker: %d)', 16, 1,
                                @stored_fingerprint, @parameter_fingerprint);
                            IF @StatsInParallel = N'N'
                                EXEC sp_releaseapplock @Resource = N'sp_StatUpdate', @LockOwner = N'Session';
                            RETURN 50001;
                        END;
                    END;
                END TRY
                BEGIN CATCH
                    /* Non-blocking: if fingerprint check fails, proceed to join the queue */
                END CATCH;
            END;

            /*
            #181: Max worker count coordination.
            Before claiming, count active workers (sessions still alive in dm_exec_sessions).
            If >= @MaxWorkers, exit cleanly without joining the queue.
            */
            IF @MaxWorkers IS NOT NULL AND @queue_id IS NOT NULL
            BEGIN
                DECLARE @active_worker_count int = 0;

                SELECT
                    @active_worker_count = COUNT(DISTINCT qs.SessionID)
                FROM dbo.QueueStatistic AS qs
                JOIN sys.dm_exec_sessions AS ses
                  ON ses.session_id = qs.SessionID
                WHERE qs.QueueID = @queue_id
                AND   qs.TableEndTime IS NULL;

                IF @active_worker_count >= @MaxWorkers
                BEGIN
                    DECLARE @mw_msg nvarchar(500);
                    SET @mw_msg = N'Max parallel workers reached (' +
                        CONVERT(nvarchar(10), @active_worker_count) + N' active, limit ' +
                        CONVERT(nvarchar(10), @MaxWorkers) + N'). Exiting cleanly.';
                    RAISERROR(@mw_msg, 10, 1) WITH NOWAIT;

                    SET @StopReasonOut = N'MAX_WORKERS';
                    EXEC sp_releaseapplock @Resource = N'sp_StatUpdate', @LockOwner = N'Session';
                    RETURN 0;
                END;

                IF @Debug = 1
                BEGIN
                    DECLARE @mw_debug nvarchar(200);
                    SET @mw_debug = N'  Active workers: ' + CONVERT(nvarchar(10), @active_worker_count) +
                        N' / ' + CONVERT(nvarchar(10), @MaxWorkers) + N' max';
                    RAISERROR(@mw_debug, 10, 1) WITH NOWAIT;
                END;
            END;

            /*
            Attempt to claim the queue (become the first/lead worker).
            Only succeeds if no other worker is currently leading.
            */
            BEGIN TRANSACTION;

            UPDATE
                q
            SET
                q.QueueStartTime = SYSDATETIME(),
                q.SessionID = @@SPID,
                q.RequestID =
                (
                    SELECT
                        r.request_id
                    FROM sys.dm_exec_requests AS r
                    WHERE r.session_id = @@SPID
                ),
                q.RequestStartTime =
                (
                    SELECT
                        r.start_time
                    FROM sys.dm_exec_requests AS r
                    WHERE r.session_id = @@SPID
                )
            FROM dbo.Queue AS q
            WHERE q.QueueID = @queue_id
            /*
            Only claim if previous leader is dead (not in dm_exec_sessions).
            Using dm_exec_sessions: a sleeping leader appears in dm_exec_sessions but not dm_exec_requests.
            */
            AND   NOT EXISTS
                  (
                      SELECT
                          1
                      FROM sys.dm_exec_sessions AS s
                      WHERE s.session_id = q.SessionID
                  )
            /*
            And no active workers in QueueStatistic (sessions still alive in dm_exec_sessions)
            */
            AND   NOT EXISTS
                  (
                      SELECT
                          1
                      FROM dbo.QueueStatistic AS qs
                      JOIN sys.dm_exec_sessions AS s
                        ON s.session_id = qs.SessionID
                      WHERE qs.QueueID = @queue_id
                  );

            IF ROWCOUNT_BIG() = 1
            BEGIN
                /*
                Successfully claimed queue - populate QueueStatistic with tables.
                Aggregate stats by table, using max modification_counter for priority.
                */
                RAISERROR(N'  Claimed queue leadership - populating work items...', 10, 1) WITH NOWAIT;

                /*
                Clear any stale entries from previous (failed/killed) runs
                */
                DELETE FROM
                    dbo.QueueStatistic
                WHERE QueueID = @queue_id;

                /*
                Insert one row per table needing stats updates.
                Tables ordered by max modification_counter (most stale first).
                */
                INSERT INTO
                    dbo.QueueStatistic
                (
                    QueueID,
                    DatabaseName,
                    SchemaName,
                    ObjectName,
                    ObjectID,
                    TablePriority,
                    StatsCount,
                    MaxModificationCounter
                )
                SELECT
                    QueueID = @queue_id,
                    DatabaseName = stp.database_name,
                    SchemaName = stp.schema_name,
                    ObjectName = stp.table_name,
                    ObjectID = stp.object_id,
                    TablePriority = ROW_NUMBER() OVER (
                        ORDER BY
                            CASE WHEN @SortOrder = N'MODIFICATION_COUNTER' THEN MAX(stp.modification_counter) END DESC,
                            CASE WHEN @SortOrder = N'PAGE_COUNT' THEN MAX(stp.page_count) END DESC,
                            CASE WHEN @SortOrder = N'DAYS_STALE' THEN MAX(stp.days_stale) END DESC,
                            CASE WHEN @SortOrder = N'RANDOM' THEN CHECKSUM(NEWID()) END DESC
                    ),
                    StatsCount = COUNT_BIG(*),
                    MaxModificationCounter = MAX(stp.modification_counter)
                FROM #stats_to_process AS stp
                GROUP BY
                    stp.database_name,
                    stp.schema_name,
                    stp.table_name,
                    stp.object_id;

                DECLARE
                    @Tables_queued integer = ROWCOUNT_BIG();

                RAISERROR(N'  Queued %d tables for processing', 10, 1, @Tables_queued) WITH NOWAIT;
            END;
            ELSE
            BEGIN
                RAISERROR(N'  Joined existing queue (QueueID = %d)', 10, 1, @queue_id) WITH NOWAIT;
            END;

            COMMIT TRANSACTION;

            /*
            Get queue start time for this run
            */
            SELECT
                @queue_start_time = q.QueueStartTime
            FROM dbo.Queue AS q
            WHERE q.QueueID = @queue_id;

        END TRY
        BEGIN CATCH
            IF @@TRANCOUNT > 0
            BEGIN
                ROLLBACK TRANSACTION;
            END;

            DECLARE
                @queue_error_message nvarchar(4000) = ERROR_MESSAGE();

            RAISERROR(N'ERROR: Queue initialization failed: %s', 16, 1, @queue_error_message) WITH NOWAIT;
            IF @StatsInParallel = N'N'
                EXEC sp_releaseapplock @Resource = N'sp_StatUpdate', @LockOwner = N'Session';
            RETURN -1;
        END CATCH;

        RAISERROR(N'', 10, 1) WITH NOWAIT;
    END;

    /*
    ============================================================================
    SHOW TOP CANDIDATES (if not executing or debug mode)
    ============================================================================
    */
    IF @Execute = N'N'
    OR @Debug = 1
    BEGIN
        RAISERROR(N'Top 20 candidates by priority:', 10, 1) WITH NOWAIT;
        RAISERROR(N'', 10, 1) WITH NOWAIT;

        SELECT TOP (20)
            priority = stp.priority,
            table_path = stp.schema_name + N'.' + stp.table_name,
            stat_name = stp.stat_name,
            norecompute =
                CASE stp.no_recompute
                    WHEN 1
                    THEN N'YES'
                    ELSE N'no'
                END,
            incremental =
                CASE stp.is_incremental
                    WHEN 1
                    THEN N'YES'
                    ELSE N'no'
                END,
            is_heap =
                CASE stp.is_heap
                    WHEN 1
                    THEN N'HEAP'
                    ELSE N''
                END,
            modifications = FORMAT(stp.modification_counter, N'N0'),
            days_stale = stp.days_stale,
            pages = FORMAT(stp.page_count, N'N0')
        FROM #stats_to_process AS stp
        ORDER BY
            stp.priority;
    END;
    /*#endregion 18-PARALLEL-QUEUE */

    /*#region 19-PROCESS-LOOP: Main processing loop (WHILE 1=1) */
    /*
    ============================================================================
    PROCESS STATISTICS
    ============================================================================
    */
    RAISERROR(N'===============================================================================', 10, 1) WITH NOWAIT;
    RAISERROR(N' Processing Statistics', 10, 1) WITH NOWAIT;
    RAISERROR(N'===============================================================================', 10, 1) WITH NOWAIT;
    RAISERROR(N'', 10, 1) WITH NOWAIT;

    /*
    Processing loop
    */
    WHILE 1 = 1
    BEGIN
        /*
        Capture iteration time once for consistent elapsed calculations
        */
        SELECT @iteration_time = SYSDATETIME();

        /*
        Check time limit
        */
        IF  @TimeLimit IS NOT NULL
        AND DATEDIFF(SECOND, @start_time, SYSDATETIME()) >= @TimeLimit
        BEGIN
            RAISERROR(N'', 10, 1) WITH NOWAIT;
            RAISERROR(N'Time limit (%d seconds) reached. Stopping gracefully.', 10, 1, @TimeLimit) WITH NOWAIT;
            SELECT
                @stop_reason = N'TIME_LIMIT';
            BREAK;
        END;

        /*
        Check batch limit
        */
        IF  @BatchLimit IS NOT NULL
        AND @stats_processed >= @BatchLimit
        BEGIN
            RAISERROR(N'', 10, 1) WITH NOWAIT;
            RAISERROR(N'Batch limit (%d stats) reached. Stopping gracefully.', 10, 1, @BatchLimit) WITH NOWAIT;
            SELECT
                @stop_reason = N'BATCH_LIMIT';
            BREAK;
        END;

        /*
        ====================================================================
        AG REDO QUEUE CHECK (v2.7, #18)
        ====================================================================
        */

        /* #146: Periodic backup detection — check every 50 stats for new backup activity */
        IF @stats_processed > 0 AND @stats_processed % 50 = 0
        BEGIN
            DECLARE @mid_run_backups int = 0;
            SELECT @mid_run_backups = COUNT(*)
            FROM sys.dm_exec_requests AS r
            WHERE r.command LIKE N'BACKUP%';

            IF @mid_run_backups > 0 AND @active_backups = 0
            BEGIN
                /* Backup started after our run began */
                RAISERROR(N'  Note: %d backup(s) now running (started after sp_StatUpdate). I/O contention possible.', 10, 1, @mid_run_backups) WITH NOWAIT;
                SET @warnings += N'BACKUP_STARTED_MID_RUN: ' + CONVERT(nvarchar(10), @mid_run_backups) + N' backup(s); ';
            END;
        END;

        /*
        Before each stat update, check if AG secondary redo queue exceeds
        threshold. If over threshold, enter a wait loop. If wait exceeds
        @MaxAGWaitMinutes or @TimeLimit is reached during wait, stop the run.
        */
        IF  @MaxAGRedoQueueMB IS NOT NULL
        AND @ag_is_primary = 1
        AND @Execute = N'Y'
        BEGIN
            SELECT @ag_redo_queue_mb = MAX(drs.redo_queue_size) / 1024.0
            FROM sys.dm_hadr_database_replica_states AS drs
            WHERE drs.is_local = 0
            AND   drs.is_primary_replica = 0
            AND   drs.redo_queue_size IS NOT NULL;

            IF @ag_redo_queue_mb IS NOT NULL AND @ag_redo_queue_mb > @MaxAGRedoQueueMB
            BEGIN
                SET @ag_wait_start = SYSDATETIME();

                WHILE @ag_redo_queue_mb > @MaxAGRedoQueueMB
                BEGIN
                    /* Check AG wait timeout */
                    IF DATEDIFF(MINUTE, @ag_wait_start, SYSDATETIME()) >= @MaxAGWaitMinutes
                    BEGIN
                        SELECT @stop_reason = N'AG_REDO_QUEUE';
                        RAISERROR(N'', 10, 1) WITH NOWAIT;
                        RAISERROR(N'AG redo queue exceeded %d MB for %d minutes. Stopping to protect secondaries.', 10, 1,
                            @MaxAGRedoQueueMB, @MaxAGWaitMinutes) WITH NOWAIT;
                        SET @WarningsOut = ISNULL(@WarningsOut, N'') +
                            N'AG_REDO_QUEUE: Stopped after waiting ' +
                            CONVERT(nvarchar(10), @MaxAGWaitMinutes) + N' min; ';
                        BREAK;
                    END;

                    /* Check time limit during wait */
                    IF  @TimeLimit IS NOT NULL
                    AND DATEDIFF(SECOND, @start_time, SYSDATETIME()) >= @TimeLimit
                    BEGIN
                        SELECT @stop_reason = N'TIME_LIMIT';
                        RAISERROR(N'', 10, 1) WITH NOWAIT;
                        RAISERROR(N'Time limit reached while waiting for AG redo queue to drain.', 10, 1) WITH NOWAIT;
                        BREAK;
                    END;

                    SET @ag_wait_msg =
                        N'  AG redo queue: ' + CONVERT(nvarchar(20), @ag_redo_queue_mb) +
                        N' MB (threshold: ' + CONVERT(nvarchar(20), @MaxAGRedoQueueMB) +
                        N' MB) -- waiting 30s...';
                    RAISERROR(@ag_wait_msg, 10, 1) WITH NOWAIT;

                    WAITFOR DELAY '00:00:30';

                    /* #141: Re-check time limit after WAITFOR to prevent overshoot */
                    IF  @TimeLimit IS NOT NULL
                    AND DATEDIFF(SECOND, @start_time, SYSDATETIME()) >= @TimeLimit
                    BEGIN
                        SELECT @stop_reason = N'TIME_LIMIT';
                        RAISERROR(N'Time limit reached during AG redo queue wait.', 10, 1) WITH NOWAIT;
                        BREAK;
                    END;

                    /* Re-check redo queue */
                    SELECT @ag_redo_queue_mb = MAX(drs.redo_queue_size) / 1024.0
                    FROM sys.dm_hadr_database_replica_states AS drs
                    WHERE drs.is_local = 0
                    AND   drs.is_primary_replica = 0
                    AND   drs.redo_queue_size IS NOT NULL;

                    /* If secondaries went offline during wait, break out */
                    IF @ag_redo_queue_mb IS NULL
                    BEGIN
                        RAISERROR(N'  AG secondaries went offline during wait. Resuming.', 10, 1) WITH NOWAIT;
                        BREAK;
                    END;
                END;

                /* If stop_reason was set inside the wait loop, exit main loop */
                IF @stop_reason IS NOT NULL
                    BREAK;

                /* Redo queue drained -- log recovery */
                IF @ag_redo_queue_mb IS NOT NULL AND @ag_redo_queue_mb <= @MaxAGRedoQueueMB
                BEGIN
                    SET @ag_recovered_msg =
                        N'  AG redo queue drained to ' + CONVERT(nvarchar(20), @ag_redo_queue_mb) +
                        N' MB (threshold: ' + CONVERT(nvarchar(20), @MaxAGRedoQueueMB) +
                        N' MB). Resuming.';
                    RAISERROR(@ag_recovered_msg, 10, 1) WITH NOWAIT;
                END;
            END;
        END;

        /*
        ====================================================================
        TEMPDB PRESSURE CHECK (v2.7, #34)
        ====================================================================
        Before each stat update, check tempdb free space. Particularly
        important for FULLSCAN operations and Azure SQL.
        */
        IF  @MinTempdbFreeMB IS NOT NULL
        AND @Execute = N'Y'
        BEGIN
            SELECT @tempdb_free_mb =
                SUM(unallocated_extent_page_count) * 8 / 1024.0
            FROM tempdb.sys.dm_db_file_space_usage;

            IF @tempdb_free_mb < @MinTempdbFreeMB
            BEGIN
                SET @tempdb_msg =
                    N'  Tempdb free space: ' + CONVERT(nvarchar(20), @tempdb_free_mb) +
                    N' MB (threshold: ' + CONVERT(nvarchar(20), @MinTempdbFreeMB) +
                    N' MB)';

                IF @FailFast = 1
                BEGIN
                    RAISERROR(N'', 10, 1) WITH NOWAIT;
                    RAISERROR(@tempdb_msg, 10, 1) WITH NOWAIT;
                    RAISERROR(N'Tempdb pressure detected with @FailFast=1. Stopping.', 10, 1) WITH NOWAIT;
                    SELECT @stop_reason = N'TEMPDB_PRESSURE';
                    SET @WarningsOut = ISNULL(@WarningsOut, N'') +
                        N'TEMPDB_PRESSURE: Stopped, only ' +
                        CONVERT(nvarchar(20), @tempdb_free_mb) + N' MB free; ';
                    BREAK;
                END;
                ELSE
                BEGIN
                    RAISERROR(@tempdb_msg, 10, 1) WITH NOWAIT;
                    RAISERROR(N'  WARNING: Tempdb below threshold. Continuing (use @FailFast=1 to abort).', 10, 1) WITH NOWAIT;
                    SET @WarningsOut = ISNULL(@WarningsOut, N'') +
                        N'TEMPDB_LOW: ' + CONVERT(nvarchar(20), @tempdb_free_mb) +
                        N' MB free (threshold: ' + CONVERT(nvarchar(20), @MinTempdbFreeMB) + N' MB); ';
                END;
            END;
        END;

        /*
        ====================================================================
        TRANSACTION LOG SPACE CHECK (#61)
        ====================================================================
        For FULLSCAN operations on FULL recovery model databases, UPDATE
        STATISTICS can generate significant transaction log growth. Check
        per-database log usage before each stat update when using FULLSCAN.
        Only checks once per iteration; uses the current stat's database.
        */
        IF  @Execute = N'Y'
        AND @StatisticsSample = 100
        BEGIN
            DECLARE @log_check_db sysname;
            DECLARE @log_used_pct float = 0;

            /* Get the next stat's database */
            SELECT TOP (1) @log_check_db = stp.database_name
            FROM #stats_to_process AS stp
            WHERE stp.processed = 0
            ORDER BY stp.priority;

            IF @log_check_db IS NOT NULL
            BEGIN
                DECLARE @log_sql nvarchar(500) = N'
                    SELECT @pct = used_log_space_in_percent
                    FROM ' + QUOTENAME(@log_check_db) + N'.sys.dm_db_log_space_usage';
                BEGIN TRY
                    EXEC sp_executesql @log_sql,
                        N'@pct float OUTPUT', @pct = @log_used_pct OUTPUT;

                    IF @log_used_pct > 90.0
                    BEGIN
                        DECLARE @log_msg nvarchar(500) = N'  WARNING: Transaction log ' + @log_check_db
                            + N' is ' + CONVERT(nvarchar(10), CONVERT(int, @log_used_pct))
                            + N'% full. FULLSCAN may cause log growth.';
                        RAISERROR(@log_msg, 10, 1) WITH NOWAIT;
                        SET @warnings += N'LOG_SPACE_HIGH: ' + @log_check_db + N'('
                            + CONVERT(nvarchar(10), CONVERT(int, @log_used_pct)) + N'%); ';

                        /* @FailFast integration: abort when log pressure is critical */
                        IF @FailFast = 1
                        BEGIN
                            RAISERROR(N'Transaction log pressure detected with @FailFast=1. Stopping.', 10, 1) WITH NOWAIT;
                            SELECT @stop_reason = N'LOG_SPACE_HIGH';
                            SET @WarningsOut = ISNULL(@WarningsOut, N'') +
                                N'LOG_SPACE_HIGH: Stopped, log ' + @log_check_db +
                                N' at ' + CONVERT(nvarchar(10), CONVERT(int, @log_used_pct)) + N'%; ';
                            BREAK;
                        END;
                    END;
                END TRY
                BEGIN CATCH /* Ignore - db may not be accessible */ END CATCH;
            END;
        END;

        /*
        ====================================================================
        PARALLEL MODE: Claim table from QueueStatistic
        ====================================================================
        In parallel mode, we must claim a TABLE before processing its stats.
        This ensures no two workers update stats on the same table concurrently.
        */
        IF @StatsInParallel = N'Y'
        BEGIN
            /*
            Check if we need to claim a new table (no table claimed, or finished previous)
            */
            IF @claimed_table_database IS NULL
            BEGIN
                /*
                First, release any tables claimed by dead workers.
                A worker is dead if its session is no longer in dm_exec_sessions.
                Using dm_exec_sessions (not dm_exec_requests) because workers sleeping
                between stat claims are not in dm_exec_requests but ARE in dm_exec_sessions.
                */
                /* v2.3: LastStatCompletedAt column may not exist on pre-v2.3 installations.
                   Use dynamic SQL to avoid compile-time column validation failure. */
                DECLARE @dead_worker_sql nvarchar(max);
                DECLARE @has_heartbeat_col bit = CASE
                    WHEN EXISTS (SELECT 1 FROM sys.columns WHERE object_id = OBJECT_ID(N'dbo.QueueStatistic') AND name = N'LastStatCompletedAt')
                    THEN 1 ELSE 0 END;

                SET @dead_worker_sql = N'
                UPDATE qs
                SET    qs.TableStartTime = NULL,
                       qs.SessionID = NULL,
                       qs.RequestID = NULL,
                       qs.RequestStartTime = NULL'
                    + CASE WHEN @has_heartbeat_col = 1
                           THEN N',
                       qs.LastStatCompletedAt = NULL'
                           ELSE N'' END + N'
                FROM dbo.QueueStatistic AS qs
                WHERE qs.QueueID = @queue_id
                AND   qs.TableStartTime IS NOT NULL
                AND   qs.TableEndTime IS NULL
                AND   (
                          NOT EXISTS
                          (
                              SELECT 1
                              FROM sys.dm_exec_sessions AS s
                              WHERE s.session_id = qs.SessionID
                          )
                          OR
                          (
                              @DeadWorkerTimeoutMinutes IS NOT NULL
                              AND DATEDIFF(MINUTE, '
                    + CASE WHEN @has_heartbeat_col = 1
                           THEN N'COALESCE(qs.LastStatCompletedAt, qs.TableStartTime)'
                           ELSE N'qs.TableStartTime' END + N',
                                  SYSDATETIME()) > @DeadWorkerTimeoutMinutes
                          )
                      );';

                EXEC sp_executesql
                    @dead_worker_sql,
                    N'@queue_id int, @DeadWorkerTimeoutMinutes int',
                    @queue_id = @queue_id,
                    @DeadWorkerTimeoutMinutes = @DeadWorkerTimeoutMinutes;

                DECLARE
                    @released_count integer = ROWCOUNT_BIG();

                IF @released_count > 0
                AND @Debug = 1
                BEGIN
                    RAISERROR(N'  Released %d tables from dead workers', 10, 1, @released_count) WITH NOWAIT;
                END;

                /*
                Claim the next unclaimed table (highest priority first).
                Uses UPDATE with OUTPUT to atomically claim and return the table.
                */
                DECLARE
                    @claimed_tables TABLE
                    (
                        DatabaseName sysname,
                        SchemaName sysname,
                        ObjectName sysname,
                        ObjectID integer
                    );

                /*
                Clear table variable from previous iterations.
                DECLARE does not reset table variables inside loops - they persist
                and OUTPUT INTO appends rather than replaces. Without this DELETE,
                SELECT TOP 1 could return stale data from a prior claim attempt.
                */
                DELETE FROM @claimed_tables;

                /*
                ROWLOCK+READPAST hints (v1.9 #25 + v2.3): Skip locked rows instead of waiting.
                ROWLOCK ensures row-level lock granularity (prevents escalation to table locks
                on large queue tables). READPAST skips rows locked by other concurrent workers.
                When multiple workers claim tables concurrently, this prevents blocking.
                */
                UPDATE
                    qs
                SET
                    qs.TableStartTime = SYSDATETIME(),
                    qs.SessionID = @@SPID,
                    qs.RequestID =
                    (
                        SELECT
                            r.request_id
                        FROM sys.dm_exec_requests AS r
                        WHERE r.session_id = @@SPID
                    ),
                    qs.RequestStartTime =
                    (
                        SELECT
                            r.start_time
                        FROM sys.dm_exec_requests AS r
                        WHERE r.session_id = @@SPID
                    )
                OUTPUT
                    inserted.DatabaseName,
                    inserted.SchemaName,
                    inserted.ObjectName,
                    inserted.ObjectID
                INTO @claimed_tables
                FROM dbo.QueueStatistic AS qs WITH (ROWLOCK, READPAST)
                WHERE qs.QueueID = @queue_id
                AND   qs.TableStartTime IS NULL
                AND   qs.TablePriority =
                      (
                          SELECT
                              MIN(qs2.TablePriority)
                          FROM dbo.QueueStatistic AS qs2 WITH (ROWLOCK, READPAST) /* P2a fix: ROWLOCK prevents page/table lock escalation under parallel load */
                          WHERE qs2.QueueID = @queue_id
                          AND   qs2.TableStartTime IS NULL
                      );

                SELECT TOP (1)
                    @claimed_table_database = ct.DatabaseName,
                    @claimed_table_schema = ct.SchemaName,
                    @claimed_table_name = ct.ObjectName,
                    @claimed_table_object_id = ct.ObjectID
                FROM @claimed_tables AS ct;

                IF @claimed_table_database IS NOT NULL
                BEGIN
                    SELECT
                        @claimed_table_stats_updated = 0,
                        @claimed_table_stats_failed = 0,
                        @claimed_table_stats_skipped = 0;

                    IF @Debug = 1
                    BEGIN
                        RAISERROR(N'  Claimed table: %s.%s.%s', 10, 1,
                            @claimed_table_database,
                            @claimed_table_schema,
                            @claimed_table_name) WITH NOWAIT;
                    END;
                END;
                ELSE
                BEGIN
                    /*
                    No more tables to claim - all work done or claimed by others
                    */
                    SELECT
                        @stop_reason = N'PARALLEL_COMPLETE';
                    BREAK;
                END;
            END;
        END;

        /*
        Claim next work item
        */
        SELECT
            @claimed_work = 0,
            @current_database = NULL;

        SELECT TOP (1)
            @current_database = stp.database_name,
            @current_schema_name = stp.schema_name,
            @current_table_name = stp.table_name,
            @current_stat_name = stp.stat_name,
            @current_object_id = stp.object_id,
            @current_stats_id = stp.stats_id,
            @current_no_recompute = stp.no_recompute,
            @current_is_incremental = stp.is_incremental,
            @current_is_memory_optimized = stp.is_memory_optimized,
            @current_is_heap = stp.is_heap,
            @current_auto_created = stp.auto_created,
            @current_modification_counter = stp.modification_counter,
            @current_row_count = stp.row_count,
            @current_days_stale = stp.days_stale,
            @current_page_count = stp.page_count,
            @current_persisted_sample_percent = stp.persisted_sample_percent,
            @current_histogram_steps = stp.histogram_steps,
            @current_forwarded_records = NULL,
            /* Filtered statistics metadata */
            @current_has_filter = stp.has_filter,
            @current_filter_definition = stp.filter_definition,
            @current_unfiltered_rows = stp.unfiltered_rows,
            @current_filtered_drift_ratio = stp.filtered_drift_ratio,
            /* Query Store priority metadata */
            @current_qs_plan_count = stp.qs_plan_count,
            @current_qs_total_executions = stp.qs_total_executions,
            @current_qs_total_cpu_ms = stp.qs_total_cpu_ms,
            @current_qs_total_duration_ms = stp.qs_total_duration_ms,
            @current_qs_total_logical_reads = stp.qs_total_logical_reads,
            @current_qs_last_execution = stp.qs_last_execution,
            @current_qs_priority_boost = stp.qs_priority_boost,
            /* Replication and temporal table awareness */
            @current_is_published = stp.is_published,
            @current_is_tracked_by_cdc = stp.is_tracked_by_cdc,
            @current_temporal_type = stp.temporal_type
        FROM #stats_to_process AS stp
        WHERE stp.processed = 0
        /*
        In parallel mode, only process stats for the currently claimed table.
        This prevents concurrent updates to the same table from different workers.
        */
        AND   (
                  @StatsInParallel = N'N'
               OR (
                      stp.database_name = @claimed_table_database
                  AND stp.schema_name = @claimed_table_schema
                  AND stp.table_name = @claimed_table_name
                  )
              )
        ORDER BY
            stp.priority;

        IF @current_database IS NOT NULL
        BEGIN
            SELECT
                @claimed_work = 1;

            /*
            HEAP FORWARDING POINTERS: Query dm_db_index_physical_stats for heaps only.
            Forwarding pointers occur when rows grow and must be relocated.
            High counts indicate fragmentation that hurts scan performance.
            Note: Uses SAMPLED mode for performance (DETAILED is very slow).
            Controlled by @CollectHeapForwarding (default N for performance).
            */
            IF @current_is_heap = 1
            AND @CollectHeapForwarding = N'Y'
            BEGIN
                SELECT
                    @current_forwarded_records = ps.forwarded_record_count
                FROM sys.dm_db_index_physical_stats
                (
                    DB_ID(@current_database),
                    @current_object_id,
                    0,
                    NULL,
                    N'SAMPLED'
                ) AS ps
                WHERE ps.index_id = 0
                AND   ps.alloc_unit_type_desc = N'IN_ROW_DATA';
            END;

            /*
            Mark as in-progress
            */
            UPDATE
                stp
            SET
                stp.processed = 1
            FROM #stats_to_process AS stp
            WHERE stp.database_name = @current_database
            AND   stp.schema_name = @current_schema_name
            AND   stp.table_name = @current_table_name
            AND   stp.stat_name = @current_stat_name;
        END;

        /*
        Exit loop if no more work
        */
        IF @claimed_work = 0
        BEGIN
            SELECT
                @stop_reason = N'COMPLETED';
            BREAK;
        END;

        /*
        P2c fix (v2.4): @StopByTime window overshoot prevention.
        When @MaxSecondsPerStat and @TimeLimit are both set, check CommandLog history
        for estimated duration of this stat. If estimated > remaining_seconds, skip.
        Conservative: if no history in CommandLog, always run it.
        */
        IF  @MaxSecondsPerStat IS NOT NULL
        AND @TimeLimit IS NOT NULL
        AND @commandlog_exists = 1
        AND @Execute = N'Y'
        AND @current_database IS NOT NULL
        BEGIN
            DECLARE
                @p2c_estimated_seconds int = NULL,
                @p2c_remaining_seconds int,
                @p2c_skip_msg nvarchar(500);

            SELECT @p2c_remaining_seconds = @TimeLimit - DATEDIFF(SECOND, @start_time, SYSDATETIME());

            /* Estimate from CommandLog: avg of last 10 successful runs for this stat */
            SELECT TOP (1)
                @p2c_estimated_seconds = CONVERT(int, AVG(DATEDIFF(SECOND, cl.StartTime, cl.EndTime)))
            FROM dbo.CommandLog AS cl
            WHERE cl.CommandType = N'UPDATE_STATISTICS'
            AND   cl.DatabaseName = @current_database
            AND   cl.SchemaName = @current_schema_name
            AND   cl.ObjectName = @current_table_name
            AND   cl.StatisticsName = @current_stat_name
            AND   cl.EndTime IS NOT NULL
            AND   cl.ErrorNumber IS NULL
            AND   cl.StartTime >= DATEADD(DAY, -@CommandLogRetentionDays, SYSDATETIME()); /* #251: parameterized retention */

            /* Skip if history exists AND estimated exceeds both the per-stat cap AND remaining window */
            IF  @p2c_estimated_seconds IS NOT NULL
            AND @p2c_estimated_seconds > @MaxSecondsPerStat
            AND @p2c_estimated_seconds > @p2c_remaining_seconds
            BEGIN
                SELECT @p2c_skip_msg =
                    N'  [P2c SKIP] ' + QUOTENAME(@current_schema_name) + N'.' +
                    QUOTENAME(@current_table_name) + N'.' + QUOTENAME(@current_stat_name) +
                    N' — estimated ' + CONVERT(nvarchar(10), @p2c_estimated_seconds) +
                    N's, remaining ' + CONVERT(nvarchar(10), @p2c_remaining_seconds) + N's';
                RAISERROR(@p2c_skip_msg, 10, 1) WITH NOWAIT;
                SET @stats_skipped += 1;
                CONTINUE; /* Already marked processed=1 above; skip execution */
            END;
        END;

        SELECT
            @stats_processed += 1,
            @current_start_time = SYSDATETIME();

        /*
        ========================================================================
        BUILD UPDATE STATISTICS COMMAND
        ========================================================================
        */
        SELECT
            @current_command = N'';

        /*
        Lock timeout
        -1 = infinite wait (pass through as-is, don't multiply)
        0+ = timeout in seconds (convert to milliseconds)
        */
        IF @LockTimeout IS NOT NULL
        BEGIN
            SELECT
                @current_command =
                    N'SET LOCK_TIMEOUT ' +
                    CASE
                        WHEN @LockTimeout = -1 THEN N'-1'
                        ELSE CONVERT(nvarchar(20), CONVERT(bigint, @LockTimeout) * 1000)
                    END +
                    N'; ';
        END;

        /*
        Base command
        */
        SELECT
            @current_command +=
                N'UPDATE STATISTICS ' +
                QUOTENAME(@current_database) + N'.' +
                QUOTENAME(@current_schema_name) + N'.' +
                QUOTENAME(@current_table_name) +
                N' (' + QUOTENAME(@current_stat_name) + N')';

        /*
        WITH clause options
        Sample source tracking for ExtendedInfo (answers "why this sample rate?"):
          EXPLICIT = User passed @StatisticsSample
          ADAPTIVE = Long-running stat override (@LongRunningSamplePercent)
          ADAPTIVE_CAPPED = Adaptive but capped to ~10M rows
          AUTO = SQL Server decides (NULL)
          RESAMPLE = Using RESAMPLE (persisted or incremental)
          FULLSCAN_MEMOPT = Forced FULLSCAN for memory-optimized on SQL 2014
        */
        DECLARE
            @has_with_option bit = 0,
            @with_clause nvarchar(max) = N'',
            @is_long_running_stat bit = 0,
            @effective_sample_percent int = @StatisticsSample,
            @sample_source nvarchar(20) = CASE
                WHEN @StatisticsSample IS NOT NULL THEN N'EXPLICIT'
                ELSE N'AUTO'
            END;

        /*
        ADAPTIVE SAMPLING: Check if this stat is historically long-running
        If so, override the sample rate with @LongRunningSamplePercent
        */
        IF @LongRunningThresholdMinutes IS NOT NULL
        BEGIN
            IF EXISTS
            (
                SELECT 1
                FROM @long_running_stats AS lrs
                WHERE lrs.database_name = @current_database
                AND   lrs.schema_name = @current_schema_name
                AND   lrs.table_name = @current_table_name
                AND   lrs.stat_name = @current_stat_name
            )
            BEGIN
                SELECT
                    @is_long_running_stat = 1;

                /*
                CAP SAMPLE PERCENT TO AVOID EXCESSIVE ROW COUNTS
                10% of 1B rows = 100M rows, which is worse than auto-sample.
                Cap at ~10M rows sampled. For a 1B row table: 10M/1B*100 = 1%.
                Minimum 1% (SQL Server's floor for SAMPLE PERCENT).
                */
                SELECT @effective_sample_percent =
                    CASE
                        WHEN @current_row_count <= 0 THEN @LongRunningSamplePercent
                        WHEN @current_row_count <= 10000000 THEN @LongRunningSamplePercent
                        ELSE
                            CASE
                                WHEN CEILING(10000000.0 / @current_row_count * 100) < @LongRunningSamplePercent
                                THEN CONVERT(int, CEILING(10000000.0 / @current_row_count * 100))
                                ELSE @LongRunningSamplePercent
                            END
                    END;

                /* Ensure minimum 1% (SQL Server requirement for SAMPLE PERCENT) */
                IF @effective_sample_percent < 1
                    SELECT @effective_sample_percent = 1;

                /* Track sample source for ExtendedInfo logging */
                SELECT @sample_source =
                    CASE
                        WHEN @effective_sample_percent < @LongRunningSamplePercent
                        THEN N'ADAPTIVE_CAPPED'
                        ELSE N'ADAPTIVE'
                    END;

                DECLARE @lr_hist_msg nvarchar(500);
                SELECT @lr_hist_msg =
                    N'  Adaptive Sampling: ' + @current_stat_name +
                    N' (historically slow, forcing ' + CONVERT(nvarchar(10), @effective_sample_percent) + N'%% sample' +
                    CASE
                        WHEN @effective_sample_percent < @LongRunningSamplePercent
                        THEN N', capped from ' + CONVERT(nvarchar(10), @LongRunningSamplePercent) + N'%%'
                        ELSE N''
                    END + N')';
                RAISERROR(@lr_hist_msg, 10, 1) WITH NOWAIT;
            END;
        END;

        /*
        P1c fix (v2.4): Compute absolute sampled rows for RESAMPLE_PERSIST quality floor check.
        Reset each iteration so stale values from previous stats don't bleed through.
        This is referenced by the ELSE IF RESAMPLE_PERSIST block below.
        */
        SET @absolute_sampled_rows = NULL;
        IF  @current_row_count IS NOT NULL
        AND @current_persisted_sample_percent IS NOT NULL
        AND @current_persisted_sample_percent > 0
            SET @absolute_sampled_rows = CAST(@current_row_count * (@current_persisted_sample_percent / 100.0) AS BIGINT);

        /*
        #183 (P2): Warn when @StatisticsSample explicitly overrides a persisted sample percent.
        No behavior change — the update proceeds with @StatisticsSample as requested.
        Gives the DBA immediate visibility when their PERSIST_SAMPLE_PERCENT setting is being
        silently overridden. To preserve the persisted rate, leave @StatisticsSample NULL.
        */
        IF  @StatisticsSample IS NOT NULL
        AND @current_persisted_sample_percent IS NOT NULL
        AND CONVERT(int, ROUND(@current_persisted_sample_percent, 0)) <> @StatisticsSample
        BEGIN
            DECLARE @persist_ovr_msg nvarchar(1000);
            SET @persist_ovr_msg =
                N'WARNING: Stat [' + @current_schema_name + N'].[' + @current_table_name
                + N'].[' + @current_stat_name + N'] has persisted sample '
                + CONVERT(nvarchar(10), CONVERT(int, ROUND(@current_persisted_sample_percent, 0)))
                + N'% — @StatisticsSample=' + CONVERT(nvarchar(10), @StatisticsSample)
                + N' will override it. To preserve persisted sampling, leave @StatisticsSample NULL. (#183)';
            RAISERROR(N'%s', 10, 1, @persist_ovr_msg) WITH NOWAIT; /* Use %s to avoid % in message being treated as format spec */
            SET @warnings = @warnings
                + N'PERSIST_SAMPLE_OVERRIDE: [' + @current_schema_name + N'].[' + @current_table_name + N'].[' + @current_stat_name + N'] '
                + N'persisted=' + CONVERT(nvarchar(10), CONVERT(int, ROUND(@current_persisted_sample_percent, 0)))
                + N'% overridden by @StatisticsSample=' + CONVERT(nvarchar(10), @StatisticsSample) + N'%; ';
        END;

        /*
        Memory-optimized tables have special requirements
        - SQL Server 2014: Requires FULLSCAN or RESAMPLE, no sampling
        - SQL Server 2016+: Supports sampling
        Note: Memory-optimized takes precedence over adaptive sampling
        */
        IF  @current_is_memory_optimized = 1
        AND @sql_version < 13
        AND @effective_sample_percent IS NOT NULL
        AND @effective_sample_percent < 100
        BEGIN
            /*
            Force FULLSCAN for memory-optimized on SQL 2014
            */
            SELECT
                @with_clause = N'FULLSCAN',
                @has_with_option = 1,
                @sample_source = N'FULLSCAN_MEMOPT',
                @effective_sample_percent = 100;

            IF @Debug = 1
            BEGIN
                RAISERROR(N'  Note: Memory-optimized table on SQL 2014 requires FULLSCAN', 10, 1) WITH NOWAIT;
            END;
        END;
        ELSE IF @effective_sample_percent = 100
        BEGIN
            SELECT
                @with_clause = N'FULLSCAN',
                @has_with_option = 1;
        END;
        ELSE IF @effective_sample_percent IS NOT NULL
        BEGIN
            SELECT
                @with_clause =
                    N'SAMPLE ' +
                    CONVERT(nvarchar(10), @effective_sample_percent) +
                    N' PERCENT',
                @has_with_option = 1;
        END;
        /*
        RESPECT PERSISTED SAMPLE PERCENT
        When @StatisticsSample is NULL and the stat has a persisted sample,
        honor the existing setting by using RESAMPLE.
        This preserves the sample rate without overriding DBA-tuned values.
        Exception: Long-running stats use forced sample rate instead of RESAMPLE.
        P1c fix (v2.4): Quality floor — skip RESAMPLE when persisted sample rate would produce
        too few rows for meaningful histograms (controlled by @PersistSampleMinRows).
        */
        ELSE IF @effective_sample_percent IS NULL
        AND     @current_persisted_sample_percent IS NOT NULL
        AND     @is_long_running_stat = 0
        AND     (@PersistSampleMinRows IS NULL OR @absolute_sampled_rows IS NULL OR @absolute_sampled_rows >= @PersistSampleMinRows)
        BEGIN
            SELECT
                @with_clause = N'RESAMPLE',
                @has_with_option = 1,
                @sample_source = N'RESAMPLE_PERSIST';

            IF @Debug = 1
            BEGIN
                SELECT @persisted_pct_msg = CONVERT(integer, @current_persisted_sample_percent);
                RAISERROR(N'  Note: Respecting persisted sample %d%% via RESAMPLE', 10, 1, @persisted_pct_msg) WITH NOWAIT;
            END;
        END
        /* #246: Warn when persisted sample rate produces too few rows for quality histograms */
        ELSE IF @effective_sample_percent IS NULL
        AND     @current_persisted_sample_percent IS NOT NULL
        AND     @is_long_running_stat = 0
        AND     @PersistSampleMinRows IS NOT NULL
        AND     @absolute_sampled_rows IS NOT NULL
        AND     @absolute_sampled_rows < @PersistSampleMinRows
        BEGIN
            SET @p246_pct = CONVERT(integer, @current_persisted_sample_percent);
            SET @p246_msg =
                N'  WARNING: Persisted sample ' + CONVERT(nvarchar(10), @p246_pct)
                + N'% yields ~' + CONVERT(nvarchar(20), @absolute_sampled_rows)
                + N' rows (below @PersistSampleMinRows=' + CONVERT(nvarchar(20), @PersistSampleMinRows)
                + N'). RESAMPLE skipped — using SQL Server auto-sample instead. (#246)';
            RAISERROR(@p246_msg, 10, 1) WITH NOWAIT;
            SET @warnings += N'PERSIST_SAMPLE_INADEQUATE: [' + @current_schema_name + N'].[' + @current_table_name + N'].[' + @current_stat_name
                + N'] persisted ' + CONVERT(nvarchar(10), @p246_pct) + N'% yields ' + CONVERT(nvarchar(20), @absolute_sampled_rows) + N' rows; ';
        END;

        /*
        Incremental statistics: ON PARTITIONS()
        Only applies to incremental stats on partitioned tables.
        Query sys.dm_db_incremental_stats_properties to find stale partitions.
        */
        DECLARE
            @incremental_partitions nvarchar(max) = NULL,
            @incremental_partition_count int = 0,
            @incremental_total_partitions int = 0,
            @physical_partition_count int = 0,
            @on_partitions_clause nvarchar(max) = N'';

        IF  @UpdateIncremental = 1
        AND @current_is_incremental = 1
        BEGIN
            /*
            P1 #26: Cross-reference with sys.partitions
            dm_db_incremental_stats_properties may miss truncated/empty partitions.
            Get physical partition count from sys.partitions as authoritative source.
            */
            DECLARE @physical_sql nvarchar(max) = N'
                USE ' + QUOTENAME(@current_database) + N';
                SELECT @count_out = COUNT(DISTINCT partition_number)
                FROM sys.partitions
                WHERE object_id = @obj_id
                AND   index_id IN (0, 1)';

            EXEC sys.sp_executesql
                @physical_sql,
                N'@obj_id int, @count_out int OUTPUT',
                @obj_id = @current_object_id,
                @count_out = @physical_partition_count OUTPUT;

            /*
            Query dm_db_incremental_stats_properties to find partitions with modifications.
            Only update partitions that exceed the modification threshold.
            This is the correct behavior for incremental statistics - updating all
            partitions defeats the purpose of incremental stats.
            */
            DECLARE @partition_sql nvarchar(max) = N'
                USE ' + QUOTENAME(@current_database) + N';
                SELECT @partitions_out = STRING_AGG(CONVERT(nvarchar(10), isp.partition_number), N'', '')
                                         WITHIN GROUP (ORDER BY isp.partition_number),
                       @count_out = COUNT(*),
                       @total_out = (SELECT COUNT(*) FROM sys.dm_db_incremental_stats_properties(@obj_id, @stat_id))
                FROM sys.dm_db_incremental_stats_properties(@obj_id, @stat_id) AS isp
                WHERE isp.modification_counter > 0
                AND   ISNULL(isp.rows, 0) > 0'; /* #171: Skip empty partitions (post-SWITCH OUT) */

            /*
            Use STRING_AGG on SQL 2017+ (faster, cleaner)
            Fall back to FOR XML PATH on SQL 2016
            */
            IF @sql_major_version >= 14
            BEGIN
                /* SQL 2017+: Use STRING_AGG */
                EXEC sys.sp_executesql
                    @partition_sql,
                    N'@obj_id int, @stat_id int, @partitions_out nvarchar(max) OUTPUT, @count_out int OUTPUT, @total_out int OUTPUT',
                    @obj_id = @current_object_id,
                    @stat_id = @current_stats_id,
                    @partitions_out = @incremental_partitions OUTPUT,
                    @count_out = @incremental_partition_count OUTPUT,
                    @total_out = @incremental_total_partitions OUTPUT;
            END
            ELSE
            BEGIN
                /* SQL 2016: Use FOR XML PATH */
                SELECT @partition_sql = N'
                    USE ' + QUOTENAME(@current_database) + N';
                    SELECT @partitions_out = STUFF((
                               SELECT N'', '' + CONVERT(nvarchar(10), isp.partition_number)
                               FROM sys.dm_db_incremental_stats_properties(@obj_id, @stat_id) AS isp
                               WHERE isp.modification_counter > 0
                               AND   ISNULL(isp.rows, 0) > 0 /* #171: Skip empty partitions */
                               ORDER BY isp.partition_number
                               FOR XML PATH(''''), TYPE
                           ).value(''.'', ''nvarchar(max)''), 1, 2, N''''),
                           @count_out = (SELECT COUNT(*) FROM sys.dm_db_incremental_stats_properties(@obj_id, @stat_id)
                                         WHERE modification_counter > 0 AND ISNULL(rows, 0) > 0),
                           @total_out = (SELECT COUNT(*) FROM sys.dm_db_incremental_stats_properties(@obj_id, @stat_id))';

                EXEC sys.sp_executesql
                    @partition_sql,
                    N'@obj_id int, @stat_id int, @partitions_out nvarchar(max) OUTPUT, @count_out int OUTPUT, @total_out int OUTPUT',
                    @obj_id = @current_object_id,
                    @stat_id = @current_stats_id,
                    @partitions_out = @incremental_partitions OUTPUT,
                    @count_out = @incremental_partition_count OUTPUT,
                    @total_out = @incremental_total_partitions OUTPUT;
            END;

            /*
            Add ON PARTITIONS clause if we found specific stale partitions.
            If ALL physical partitions are stale, skip ON PARTITIONS (full RESAMPLE is more efficient).
            If NO partitions are stale, we shouldn't be here (discovery should have filtered).

            P1 #26 / v2.0 #4/26: Truncated partition handling.
            When DMV reports fewer partitions than sys.partitions, some are missing
            (truncated/empty). These have 0 rows so skip them — only update the
            stale partitions that actually have data. Previously this forced a full
            RESAMPLE which was wasteful (e.g., 24-partition table with 1 truncated
            would update all 24 instead of just the 5 stale ones).
            */
            DECLARE @partitions_missing int = 0;
            IF @physical_partition_count > @incremental_total_partitions
            BEGIN
                SELECT @partitions_missing = @physical_partition_count - @incremental_total_partitions;
                IF @Debug = 1
                BEGIN
                    RAISERROR(N'  Note: %d of %d partitions missing from DMV (truncated/empty, skipping)', 10, 1,
                        @partitions_missing, @physical_partition_count) WITH NOWAIT;
                END;
            END;

            IF  @incremental_partitions IS NOT NULL
            AND @incremental_partition_count > 0
            AND @incremental_partition_count < @physical_partition_count
            BEGIN
                /*
                Partial update: only stale partitions with data.
                Truncated partitions are naturally excluded (not in DMV).
                */
                SELECT
                    @on_partitions_clause = N' ON PARTITIONS(' + @incremental_partitions + N')';

                IF @Debug = 1
                BEGIN
                    IF @partitions_missing > 0
                        RAISERROR(N'  Note: Incremental statistics - updating %d of %d partitions (skipping %d truncated)', 10, 1,
                            @incremental_partition_count, @physical_partition_count, @partitions_missing) WITH NOWAIT;
                    ELSE
                        RAISERROR(N'  Note: Incremental statistics - updating %d of %d partitions', 10, 1,
                            @incremental_partition_count, @physical_partition_count) WITH NOWAIT;
                END;
            END
            ELSE IF @Debug = 1
            BEGIN
                IF @incremental_partition_count >= @physical_partition_count
                BEGIN
                    RAISERROR(N'  Note: Incremental statistics - all %d partitions stale, full RESAMPLE', 10, 1,
                        @physical_partition_count) WITH NOWAIT;
                END;
                ELSE
                BEGIN
                    RAISERROR(N'  Note: Incremental statistics - full update (partition info unavailable)', 10, 1) WITH NOWAIT;
                END;
            END;

            /*
            Incremental stats require RESAMPLE
            */
            IF @StatisticsSample IS NULL
            BEGIN
                IF @has_with_option = 0
                BEGIN
                    SELECT
                        @with_clause = N'RESAMPLE',
                        @has_with_option = 1,
                        @sample_source = N'RESAMPLE_INCR';
                END;
            END;
        END;

        /*
        MAXDOP (SQL 2016 SP2+, SQL 2017 CU3+)
        Only add if the server supports it - gracefully degrade on older builds
        */
        IF  @MaxDOP IS NOT NULL
        AND @supports_maxdop_stats = 1
        BEGIN
            IF @has_with_option = 0
            BEGIN
                SELECT
                    @with_clause = N'MAXDOP = ' + CONVERT(nvarchar(10), @MaxDOP),
                    @has_with_option = 1;
            END;
            ELSE
            BEGIN
                SELECT
                    @with_clause += N', MAXDOP = ' + CONVERT(nvarchar(10), @MaxDOP);
            END;
        END;
        ELSE IF @MaxDOP IS NOT NULL AND @supports_maxdop_stats = 0 AND @Debug = 1
        BEGIN
            RAISERROR(N'  Note: @MaxDOP ignored - requires SQL 2016 SP2+ or SQL 2017 CU3+', 10, 1) WITH NOWAIT;
        END;

        /*
        PERSIST_SAMPLE_PERCENT (SQL 2016 SP1 CU4+)
        Only add if:
          1. Server supports it (build check passed)
          2. A sample option was specified (FULLSCAN or SAMPLE n%)
          3. NOT using RESAMPLE (RESAMPLE and PERSIST_SAMPLE_PERCENT are mutually exclusive - Error 1052)
        PERSIST_SAMPLE_PERCENT cannot be used alone - it must accompany FULLSCAN or SAMPLE.
        */
        IF  @PersistSamplePercent = N'Y'
        AND @supports_persist_sample = 1
        AND @has_with_option = 1  /* Only add if FULLSCAN/SAMPLE already specified */
        AND @with_clause NOT LIKE N'%RESAMPLE%'  /* RESAMPLE and PERSIST_SAMPLE_PERCENT conflict (Error 1052) */
        BEGIN
            SELECT
                @with_clause += N', PERSIST_SAMPLE_PERCENT = ON';
        END;
        ELSE IF @PersistSamplePercent = N'Y' AND @supports_persist_sample = 0 AND @Debug = 1
        BEGIN
            RAISERROR(N'  Note: @PersistSamplePercent ignored - requires SQL 2016 SP1 CU4+', 10, 1) WITH NOWAIT;
        END;
        ELSE IF @PersistSamplePercent = N'Y' AND @with_clause LIKE N'%RESAMPLE%' AND @Debug = 1
        BEGIN
            RAISERROR(N'  Note: @PersistSamplePercent ignored - conflicts with RESAMPLE (Error 1052)', 10, 1) WITH NOWAIT;
        END;
        /* Note: @has_with_option=0 case now handled once at startup to reduce debug noise */

        /*
        ON PARTITIONS must come immediately after RESAMPLE in the WITH clause,
        before any other options like NORECOMPUTE.
        Valid:   WITH RESAMPLE ON PARTITIONS(2, 3), NORECOMPUTE
        Invalid: WITH RESAMPLE, NORECOMPUTE ON PARTITIONS(2, 3)
        (#215 F-1 fix)
        */
        IF @on_partitions_clause <> N''
        BEGIN
            SELECT
                @with_clause += @on_partitions_clause;
        END;

        /*
        NORECOMPUTE: Preserve the flag on stats that have it set
        Without this, UPDATE STATISTICS clears the no_recompute flag
        */
        IF @current_no_recompute = 1
        BEGIN
            IF @has_with_option = 0
            BEGIN
                SELECT
                    @with_clause = N'NORECOMPUTE',
                    @has_with_option = 1;
            END;
            ELSE
            BEGIN
                SELECT
                    @with_clause += N', NORECOMPUTE';
            END;
        END;

        /*
        Add WITH clause if we have options
        */
        IF @has_with_option = 1
        BEGIN
            SELECT
                @current_command += N' WITH ' + @with_clause;
        END;

        SELECT
            @current_command += N';';

        /*
        RESET LOCK_TIMEOUT (P1 #23, v1.9 enhancement)
        SET LOCK_TIMEOUT persists at session level after sp_executesql returns.
        v1.9: Restore to original session value instead of hardcoding -1.
        This respects caller's session state rather than assuming infinite wait.
        */
        IF @LockTimeout IS NOT NULL
        BEGIN
            SELECT
                @current_command += N' SET LOCK_TIMEOUT ' +
                    CONVERT(nvarchar(20), @original_lock_timeout) + N';';
        END;

        /*
        ========================================================================
        OUTPUT / EXECUTE
        ========================================================================
        */

        /*
        Progress message
        */
        SELECT
            @norecompute_display =
                CASE
                    WHEN @current_no_recompute = 1
                    THEN N'YES (preserved)'
                    ELSE N'no'
                END,
            @progress_msg =
                N'[' + CONVERT(nvarchar(10), @stats_processed) + N'/' + CONVERT(nvarchar(10), @total_stats) + N'] ' +
                @current_schema_name + N'.' + @current_table_name + N'.' + @current_stat_name +
                N' (mods: ' + CONVERT(nvarchar(20), @current_modification_counter) +
                N', stale: ' + CONVERT(nvarchar(10), @current_days_stale) + N' days' +
                CASE
                    WHEN @current_is_incremental = 1
                    THEN N', INCREMENTAL'
                    ELSE N''
                END +
                CASE
                    WHEN @current_is_heap = 1
                    AND  @current_forwarded_records > 0
                    THEN N', HEAP (fwd: ' + FORMAT(@current_forwarded_records, N'N0') + N')'
                    WHEN @current_is_heap = 1
                    THEN N', HEAP'
                    ELSE N''
                END +
                CASE
                    WHEN @current_is_memory_optimized = 1
                    THEN N', MEMORY'
                    ELSE N''
                END +
                CASE
                    WHEN @current_is_published = 1
                    THEN N', REPLICATED'
                    ELSE N''
                END +
                CASE
                    WHEN @current_is_tracked_by_cdc = 1
                    THEN N', CDC'
                    ELSE N''
                END +
                CASE
                    WHEN @current_temporal_type = 2
                    THEN N', TEMPORAL'
                    WHEN @current_temporal_type = 1
                    THEN N', TEMPORAL-HIST'
                    ELSE N''
                END +
                N', NORECOMPUTE: ' + @norecompute_display + N')';

        RAISERROR(@progress_msg, 10, 1) WITH NOWAIT;

        IF @Debug = 1
        BEGIN
            RAISERROR(N'  Command: %s', 10, 1, @current_command) WITH NOWAIT;
        END;

        IF @Execute = N'Y'
        BEGIN
            /*
            TOCTOU check (sp_HeapDoctor pattern): verify stat still exists.
            Between discovery and execution, the statistic may have been dropped
            (e.g., table dropped, stat auto-dropped on schema change, manual DROP).
            */
            SET @toctou_sql = N'SELECT @exists = COUNT(*) FROM '
                + QUOTENAME(@current_database) + N'.sys.stats AS s '
                + N'WHERE s.object_id = @obj_id AND s.stats_id = @stat_id';
            SET @toctou_exists = 0;

            BEGIN TRY
                EXEC sys.sp_executesql @toctou_sql,
                    N'@obj_id int, @stat_id int, @exists int OUTPUT',
                    @obj_id = @current_object_id,
                    @stat_id = @current_stats_id,
                    @exists = @toctou_exists OUTPUT;
            END TRY
            BEGIN CATCH
                SET @toctou_exists = 1; /* On error, proceed anyway (e.g., cross-DB permission issue) */
            END CATCH;

            IF @toctou_exists = 0
            BEGIN
                IF @Debug = 1
                BEGIN
                    DECLARE @toctou_msg nvarchar(2000) =
                        N'  Skipping ' + QUOTENAME(@current_schema_name) + N'.' + QUOTENAME(@current_table_name) + N'.' + QUOTENAME(@current_stat_name)
                        + N': object no longer exists (dropped or renamed between discovery and execution)';
                    RAISERROR(@toctou_msg, 10, 1) WITH NOWAIT;
                END
                ELSE
                BEGIN
                    RAISERROR(N'  SKIPPED: statistic no longer exists (dropped between discovery and execution)', 10, 1) WITH NOWAIT;
                END;
                SET @stats_skipped += 1;
                SET @stats_processed -= 1; /* Undo increment - TOCTOU skip is not a real attempt */

                /* #58: Log skipped stats to CommandLog for audit compliance */
                IF  @LogSkippedToCommandLog = N'Y'
                AND @LogToTable = N'Y'
                AND @commandlog_exists = 1
                AND @Execute = N'Y'
                BEGIN
                    BEGIN TRY
                        INSERT INTO dbo.CommandLog
                            (DatabaseName, SchemaName, ObjectName, ObjectType, Command, CommandType, StartTime, EndTime, ExtendedInfo)
                        VALUES
                        (
                            @current_database,
                            @current_schema_name,
                            @current_table_name,
                            N'U',
                            N'SKIPPED: ' + @current_stat_name + N' (object no longer exists)',
                            N'UPDATE_STATISTICS',
                            SYSDATETIME(),
                            SYSDATETIME(),
                            (SELECT N'TOCTOU_SKIP' AS SkipReason, @run_label AS RunLabel, @procedure_version AS [Version]
                             FOR XML RAW(N'ExtendedInfo'), ELEMENTS)
                        );
                    END TRY
                    BEGIN CATCH /* Non-critical - ignore */ END CATCH;
                END;

                UPDATE stp
                SET stp.processed = 1
                FROM #stats_to_process AS stp
                WHERE stp.database_name = @current_database
                AND   stp.schema_name = @current_schema_name
                AND   stp.table_name = @current_table_name
                AND   stp.stat_name = @current_stat_name;

                CONTINUE;
            END;

            /*
            Pre-execution INSERT to CommandLog (Ola Hallengren two-phase pattern):
            INSERT with NULL EndTime before execution, UPDATE EndTime after completion.
            This lets you monitor in-progress stats via: SELECT * FROM dbo.CommandLog WHERE EndTime IS NULL;
            */
            SET @current_commandlog_id = NULL;
            IF  @LogToTable = N'Y'
            AND @commandlog_exists = 1
            BEGIN
                BEGIN TRY
                    INSERT INTO
                        dbo.CommandLog
                    (
                        DatabaseName,
                        SchemaName,
                        ObjectName,
                        ObjectType,
                        StatisticsName,
                        Command,
                        CommandType,
                        StartTime
                    )
                    VALUES
                    (
                        @current_database,
                        @current_schema_name,
                        @current_table_name,
                        N'U',
                        @current_stat_name,
                        @current_command,
                        @current_command_type,
                        @current_start_time
                    );
                    SET @current_commandlog_id = SCOPE_IDENTITY();
                END TRY
                BEGIN CATCH
                    SET @log_error_msg = LEFT(ERROR_MESSAGE(), 3900);
                    RAISERROR(N'  WARNING: Failed to log start to CommandLog (%s). Continuing execution.', 10, 1, @log_error_msg) WITH NOWAIT;
                END CATCH;
            END;

            /* #163 (P2): Deadlock retry — up to 3 total attempts with exponential backoff on error 1205.
               ROWLOCK+READPAST skips locked rows but cannot prevent Sch-M conflicts when multiple
               workers update the same stat simultaneously. Retry loop handles that residual race. */
            DECLARE
                @exec_retry      int    = 0,
                @exec_retry_delay char(8),
                @exec_done       bit    = 0;

            BEGIN TRY
                WHILE @exec_done = 0
                BEGIN
                    BEGIN TRY
                        EXECUTE sys.sp_executesql
                            @current_command;
                        SET @exec_done = 1; /* Success — exit retry loop */
                    END TRY
                    BEGIN CATCH
                        IF ERROR_NUMBER() = 1205 AND @exec_retry < 2
                        BEGIN
                            /* Deadlock — back off and retry */
                            SET @exec_retry_delay =
                                CASE @exec_retry WHEN 0 THEN '00:00:01' WHEN 1 THEN '00:00:02' ELSE '00:00:04' END;
                            SET @exec_retry += 1;
                            RAISERROR(N'  ~ Deadlock on stat update (retry %d/2) — waiting %s before retry (#163)',
                                10, 1, @exec_retry, @exec_retry_delay) WITH NOWAIT;
                            WAITFOR DELAY @exec_retry_delay;
                        END
                        ELSE
                        BEGIN
                            /* Non-deadlock error, or all retries exhausted — re-raise to outer CATCH */
                            IF @exec_retry > 0
                                SET @warnings = @warnings
                                    + N'DEADLOCK_RETRY_FAIL: [' + @current_schema_name + N'].[' + @current_table_name + N'].[' + @current_stat_name + N'] '
                                    + N'deadlocked, failed after ' + CONVERT(nvarchar(5), @exec_retry + 1) + N' attempt(s); ';
                            SET @exec_done = 1; /* Force loop exit before re-raise */
                            ;THROW; /* Propagates to outer BEGIN CATCH */
                        END;
                    END CATCH;
                END; /* WHILE @exec_done = 0 */

                /* Emit note if stat update succeeded after one or more deadlock retries */
                IF @exec_retry > 0
                BEGIN
                    RAISERROR(N'  ~ Stat update succeeded after %d deadlock retry(s) (#163)', 10, 1, @exec_retry) WITH NOWAIT;
                    SET @warnings = @warnings
                        + N'DEADLOCK_RETRY_OK: [' + @current_schema_name + N'].[' + @current_table_name + N'].[' + @current_stat_name + N'] '
                        + N'succeeded after ' + CONVERT(nvarchar(5), @exec_retry) + N' retry(s); ';
                END;

                SELECT
                    @current_end_time = SYSDATETIME(),
                    @stats_succeeded += 1,
                    @consecutive_failures = 0, /* Reset on success */
                    @claimed_table_stats_updated += CASE WHEN @StatsInParallel = N'Y' THEN 1 ELSE 0 END,
                    @duration_ms = DATEDIFF(MILLISECOND, @current_start_time, @current_end_time);

                /* P3e (v2.4): Update ETR running totals */
                SET @etr_total_ms += @duration_ms;
                SET @etr_completed += 1;
                SET @etr_suffix = N'';

                /* P3e (v2.4): Compute ETR after at least 3 stats completed (avoids wild early estimates) */
                IF @etr_completed >= 3
                BEGIN
                    SET @etr_avg_ms = @etr_total_ms / @etr_completed;
                    SET @etr_remaining_count = @total_stats - @stats_processed;
                    IF @etr_remaining_count > 0
                    BEGIN
                        SET @etr_ms = CONVERT(bigint, @etr_remaining_count) * @etr_avg_ms;
                        IF @etr_ms >= 3600000
                            SET @etr_display = CONVERT(nvarchar(10), @etr_ms / 3600000) + N'h ' + CONVERT(nvarchar(10), (@etr_ms % 3600000) / 60000) + N'm';
                        ELSE IF @etr_ms >= 60000
                            SET @etr_display = CONVERT(nvarchar(10), @etr_ms / 60000) + N'm';
                        ELSE
                            SET @etr_display = CONVERT(nvarchar(10), @etr_ms / 1000) + N's';
                        SET @etr_suffix = N' | ETR: ~' + @etr_display;
                    END;
                END;

                SET @progress_msg =
                    N'  Complete (' +
                    CONVERT(nvarchar(10), @duration_ms / 1000) + N'.' +
                    CONVERT(nvarchar(10), (@duration_ms % 1000) / 100) + N's)' +
                    @etr_suffix;

                /* v2.3: Update LastStatCompletedAt to track per-stat heartbeat for dead worker detection */
                /* Uses dynamic SQL to avoid compile-time column validation when column doesn't exist yet */
                /* P2d fix (v2.4): Nested TRY/CATCH — heartbeat write failure is non-fatal.
                   Without this, a transient table lock or column error would fall into the outer CATCH,
                   mark a successfully-completed stat as FAILED, and potentially trip @MaxConsecutiveFailures. */
                IF  @StatsInParallel = N'Y'
                AND @claimed_table_database IS NOT NULL
                AND OBJECT_ID(N'dbo.QueueStatistic', N'U') IS NOT NULL
                AND @has_heartbeat_col = 1
                BEGIN
                    BEGIN TRY
                        EXEC sp_executesql
                            N'UPDATE dbo.QueueStatistic SET LastStatCompletedAt = SYSDATETIME() WHERE QueueID = @qid AND DatabaseName = @db AND SchemaName = @sch AND ObjectName = @obj;',
                            N'@qid int, @db sysname, @sch sysname, @obj sysname',
                            @qid = @queue_id,
                            @db = @claimed_table_database,
                            @sch = @claimed_table_schema,
                            @obj = @claimed_table_name;
                    END TRY
                    BEGIN CATCH
                        /* Heartbeat failure is non-fatal — the stat update succeeded. Log warning only. */
                        DECLARE @heartbeat_err nvarchar(500) = LEFT(ERROR_MESSAGE(), 500);
                        RAISERROR(N'[sp_StatUpdate] WARNING: Heartbeat write failed (%s). Stat update was successful.', 0, 1, @heartbeat_err) WITH NOWAIT;
                    END CATCH;
                END;

                RAISERROR(@progress_msg, 10, 1) WITH NOWAIT;

                /*
                Update CommandLog with success (two-phase pattern: pre-exec INSERT already done above).
                Rows with NULL EndTime are visible to other sessions during execution — query with:
                  SELECT * FROM dbo.CommandLog WHERE EndTime IS NULL AND CommandType = 'UPDATE_STATISTICS';
                */
                BEGIN TRY
                IF  @LogToTable = N'Y'
                AND @commandlog_exists = 1
                AND @current_commandlog_id IS NOT NULL
                BEGIN
                    /*
                    Build ExtendedInfo XML for CommandLog.
                    NOTE: RunLabel is intentionally denormalized into each stat's ExtendedInfo.
                    This enables simple correlation queries without complex joins:
                      SELECT * FROM CommandLog WHERE ExtendedInfo.value('...RunLabel...') = 'server_20260128_123456'
                    Trade-off: ~50 bytes per row vs. join complexity. Acceptable for maintenance logs.
                    */
                    SELECT
                        @current_extended_info =
                        (
                            SELECT
                                @current_object_id AS ObjectId,
                                @current_stats_id AS StatsId,
                                @current_modification_counter AS ModificationCounter,
                                CASE
                                    WHEN @current_row_count > 0
                                    THEN CONVERT(decimal(18, 2), (@current_modification_counter * 100.0 / @current_row_count))
                                    ELSE 0
                                END AS ModificationPct,
                                @current_days_stale AS DaysStale,
                                @current_page_count AS PageCount,
                                @current_page_count / 128 AS SizeMB,
                                @current_row_count AS [RowCount],
                                @current_no_recompute AS HasNorecompute,
                                @current_is_incremental AS IsIncremental,
                                @current_is_heap AS IsHeap,
                                ISNULL(@current_forwarded_records, 0) AS ForwardedRecords,
                                @current_is_memory_optimized AS IsMemoryOptimized,
                                @current_auto_created AS AutoCreated,
                                @current_histogram_steps AS HistogramSteps,
                                /* Persisted sample metadata (P1c, v2.4) */
                                @current_persisted_sample_percent AS PersistedSamplePercent,
                                @absolute_sampled_rows AS PersistedSampledRows,
                                /* Filtered statistics metadata */
                                @current_has_filter AS HasFilter,
                                LEFT(@current_filter_definition, 500) AS FilterDefinition, /*truncate for XML*/
                                @current_unfiltered_rows AS UnfilteredRows,
                                @current_filtered_drift_ratio AS FilteredDriftRatio,
                                /* Query Store priority metadata */
                                @current_qs_plan_count AS QSPlanCount,
                                @current_qs_total_executions AS QSTotalExecutions,
                                @current_qs_total_cpu_ms AS QSTotalCpuMs,
                                @current_qs_total_duration_ms AS QSTotalDurationMs,
                                @current_qs_total_logical_reads AS QSTotalLogicalReads,
                                @current_qs_last_execution AS QSLastExecution,
                                @current_qs_priority_boost AS QSPriorityBoost,
                                @QueryStoreMetric AS QSMetric,
                                CASE
                                    WHEN @mode IN (N'DIRECT_STRING', N'DIRECT_TABLE')
                                    THEN N'DIRECT_MODE'
                                    WHEN @current_qs_priority_boost > 0
                                    THEN N'QUERY_STORE_PRIORITY'
                                    WHEN @current_has_filter = 1
                                    AND  @FilteredStatsMode = N'PRIORITY'
                                    AND  @current_filtered_drift_ratio >= @FilteredStatsStaleFactor
                                    THEN N'FILTERED_DRIFT'
                                    WHEN @current_no_recompute = 1
                                    AND  @TargetNorecompute IN (N'Y', N'BOTH')
                                    THEN N'NORECOMPUTE_TARGET'
                                    WHEN @current_days_stale >= ISNULL(@DaysStaleThreshold, 999999)
                                    THEN N'DAYS_STALE'
                                    WHEN @TieredThresholds = 1
                                    THEN N'TIERED_THRESHOLD'
                                    WHEN @ModificationPercent IS NOT NULL
                                    AND  (@current_modification_counter * 100.0 / NULLIF(@current_row_count, 0)) >= @ModificationPercent
                                    THEN N'MOD_PERCENT'
                                    WHEN @current_modification_counter >= ISNULL(@ModificationThreshold, 0)
                                    THEN N'MOD_COUNTER'
                                    ELSE N'THRESHOLD_MATCH'
                                END AS QualifyReason,
                                /* Sample rate traceability - answers "why this sample rate?" */
                                @StatisticsSample AS RequestedSamplePct,
                                @effective_sample_percent AS EffectiveSamplePct,
                                @sample_source AS SampleSource,
                                @mode AS Mode,
                                @run_label AS RunLabel,
                                @stats_processed AS ProcessingPosition,
                                @procedure_version AS Version
                            FOR
                                XML RAW(N'ExtendedInfo'),
                                ELEMENTS
                        );

                    /* #153: Warn if command exceeds 4000 chars (older CommandLog schemas may have nvarchar(4000)) */
                    IF LEN(@current_command) > 4000
                        RAISERROR(N'  Note: UPDATE STATISTICS command is %d chars — may truncate on older CommandLog schemas with nvarchar(4000).', 10, 1, @current_command) WITH NOWAIT;

                    UPDATE dbo.CommandLog
                    SET EndTime = @current_end_time,
                        ErrorNumber = 0,
                        ExtendedInfo = @current_extended_info
                    WHERE ID = @current_commandlog_id;

                    /*
                    Progress logging at interval (for Agent job monitoring).
                    Logs SP_STATUPDATE_PROGRESS entry every N stats processed.
                    */
                    IF  @ProgressLogInterval IS NOT NULL
                    AND @stats_processed % @ProgressLogInterval = 0
                    BEGIN
                        INSERT INTO
                            dbo.CommandLog
                        (
                            DatabaseName,
                            SchemaName,
                            ObjectName,
                            ObjectType,
                            Command,
                            CommandType,
                            StartTime,
                            EndTime,
                            ExtendedInfo
                        )
                        VALUES
                        (
                            ISNULL(@Databases, DB_NAME()),
                            N'dbo',
                            N'sp_StatUpdate',
                            N'P',
                            N'Progress: ' + CONVERT(nvarchar(10), @stats_processed) + N'/' + CONVERT(nvarchar(10), @total_stats) + N' stats processed',
                            N'SP_STATUPDATE_PROGRESS',
                            @start_time,
                            SYSDATETIME(),
                            (
                                SELECT
                                    @stats_processed AS StatsProcessed,
                                    @stats_succeeded AS StatsSucceeded,
                                    @stats_failed AS StatsFailed,
                                    @total_stats AS StatsTotal,
                                    DATEDIFF(SECOND, @start_time, SYSDATETIME()) AS ElapsedSeconds
                                FOR XML RAW(N'Progress'), ELEMENTS
                            )
                        );
                    END;
                END;
                END TRY
                BEGIN CATCH
                    /* CommandLog UPDATE failure is non-fatal: stat update succeeded. Log warning only. */
                    SET @log_error_msg = LEFT(ERROR_MESSAGE(), 3900);
                    RAISERROR(N'  WARNING: Failed to update CommandLog (%s). Stat update succeeded.', 10, 1, @log_error_msg) WITH NOWAIT;
                END CATCH;

                /*
                #168 (P2): After stat update, warn if this table has ANY forced plans in Query Store.
                Statistics changes can shift cardinality estimates causing forced plans to become
                suboptimal. This gives the DBA immediate per-stat visibility — the end-of-run
                summary (#32) still provides the aggregate count for monitoring automation.
                Wrapped in TRY/CATCH: silently skipped when QS is disabled on the database.
                */
                BEGIN TRY
                    DECLARE @qs168_count int = 0, @qs168_sql nvarchar(max), @qs168_msg nvarchar(1000);
                    SET @qs168_sql =
                        N'SELECT @cnt = COUNT(DISTINCT qsp.plan_id)
                          FROM ' + QUOTENAME(@current_database) + N'.sys.query_store_plan AS qsp
                          INNER JOIN ' + QUOTENAME(@current_database) + N'.sys.query_store_query AS qsq
                              ON qsq.query_id = qsp.query_id
                          INNER JOIN ' + QUOTENAME(@current_database) + N'.sys.query_store_query_text AS qsqt
                              ON qsqt.query_text_id = qsq.query_text_id
                          WHERE qsp.is_forced_plan = 1
                          AND qsp.force_failure_count = 0
                          AND CHARINDEX(@tbl COLLATE DATABASE_DEFAULT,
                                        qsqt.query_sql_text COLLATE DATABASE_DEFAULT) > 0';
                    EXEC sp_executesql @qs168_sql,
                        N'@tbl sysname, @cnt int OUTPUT',
                        @tbl = @current_table_name,
                        @cnt = @qs168_count OUTPUT;
                    IF ISNULL(@qs168_count, 0) > 0
                    BEGIN
                        SET @qs168_msg =
                            N'WARNING: Stat update on [' + @current_schema_name + N'].[' + @current_table_name
                            + N'] — ' + CONVERT(nvarchar(10), @qs168_count)
                            + N' forced plan(s) exist in Query Store. Verify query plans remain optimal after statistics change. (#168)';
                        RAISERROR(N'%s', 10, 1, @qs168_msg) WITH NOWAIT;
                        SET @warnings = @warnings
                            + N'QS_FORCED_PLANS_STAT: [' + @current_schema_name + N'].[' + @current_table_name + N'].[' + @current_stat_name + N'] '
                            + CONVERT(nvarchar(10), @qs168_count) + N' forced plan(s); ';
                    END;
                END TRY
                BEGIN CATCH /* QS not enabled or not accessible on this database — skip */ END CATCH;

            END TRY
            BEGIN CATCH
                SELECT
                    @current_end_time = SYSDATETIME(),
                    @current_error_number = ERROR_NUMBER(),
                    @current_error_message = ERROR_MESSAGE();

                /*
                TOCTOU carve-out: errors 208 (invalid object name), 15009 (object not found),
                and 2767 (statistics not found) indicate the object/stat was dropped between
                queue-load and execution — a race condition, not a real infrastructure failure.
                Count separately from real failures to avoid misleading summary output (#222).
                */
                IF @current_error_number IN (208, 15009, 2767)
                BEGIN
                    SELECT @stats_toctou += 1;
                    RAISERROR(N'  ~ TOCTOU skip (error %d): object/statistic no longer exists — not counted as failure.', 10, 1, @current_error_number) WITH NOWAIT;
                END;
                ELSE
                BEGIN
                    SELECT
                        @stats_failed += 1,
                        @consecutive_failures += 1,
                        @claimed_table_stats_failed += CASE WHEN @StatsInParallel = N'Y' THEN 1 ELSE 0 END;
                    RAISERROR(N'  X Error %d: %s', 16, 1, @current_error_number, @current_error_message) WITH NOWAIT;
                END;

                /*
                Update CommandLog with error (two-phase pattern: pre-exec INSERT already done above)
                */
                IF  @LogToTable = N'Y'
                AND @commandlog_exists = 1
                AND @current_commandlog_id IS NOT NULL
                BEGIN
                    BEGIN TRY
                        UPDATE dbo.CommandLog
                        SET EndTime = @current_end_time,
                            ErrorNumber = @current_error_number,
                            ErrorMessage = @current_error_message
                        WHERE ID = @current_commandlog_id;
                    END TRY
                    BEGIN CATCH
                        SELECT @log_error_msg = LEFT(ERROR_MESSAGE(), 3900);
                        RAISERROR(N'  WARNING: Failed to log error to CommandLog (%s)', 10, 1, @log_error_msg) WITH NOWAIT;
                    END CATCH;
                END;

                SELECT
                    @return_code = @current_error_number;

                /*
                I/O corruption (823/824/825): Abort immediately and advise CHECKDB (#222).
                Continuing stats maintenance on a database with I/O corruption risks further damage.
                */
                IF @current_error_number IN (823, 824, 825)
                BEGIN
                    RAISERROR(N'', 10, 1) WITH NOWAIT;
                    RAISERROR(N'CRITICAL: I/O corruption detected (error %d). Aborting stats maintenance.', 16, 1, @current_error_number) WITH NOWAIT;
                    RAISERROR(N'  Run DBCC CHECKDB on database [%s] to assess corruption extent.', 10, 1, @current_database) WITH NOWAIT;
                    SELECT @stop_reason = N'IO_CORRUPTION';
                    SET @warnings = @warnings + N'IO_CORRUPTION: Error ' + CONVERT(nvarchar(10), @current_error_number) + N' on [' + @current_database + N']; ';
                    BREAK;
                END;

                /*
                FailFast: Abort on first error if enabled
                */
                IF @FailFast = 1
                BEGIN
                    RAISERROR(N'', 10, 1) WITH NOWAIT;
                    RAISERROR(N'FailFast enabled. Aborting due to error.', 16, 1) WITH NOWAIT;
                    SELECT @stop_reason = N'FAIL_FAST';
                    BREAK;
                END;

                /*
                MaxConsecutiveFailures: Abort after N consecutive failures
                Prevents cascading issues from shared resource problems (disk, memory, locks).
                */
                IF @MaxConsecutiveFailures IS NOT NULL AND @consecutive_failures >= @MaxConsecutiveFailures
                BEGIN
                    RAISERROR(N'', 10, 1) WITH NOWAIT;
                    RAISERROR(N'Aborting: %d consecutive failures reached. Last error %d: %s', 16, 1, @consecutive_failures, @current_error_number, @current_error_message) WITH NOWAIT;
                    SELECT @stop_reason = N'CONSECUTIVE_FAILURES';
                    BREAK;
                END;
            END CATCH;
        END;
        ELSE
        BEGIN
            /*
            Dry run - just show command
            */
            RAISERROR(N'  [DRY RUN] %s', 10, 1, @current_command) WITH NOWAIT;

            /*
            If @WhatIfOutputTable is specified, insert the command into that table
            */
            IF @WhatIfOutputTable IS NOT NULL
            BEGIN
                /* P1b fix: use @safe_wio_fqn (PARSENAME+QUOTENAME validated) instead of raw @WhatIfOutputTable */
                DECLARE @whatif_insert_sql nvarchar(max) = N'
                    INSERT INTO ' + @safe_wio_fqn + N'
                    (DatabaseName, SchemaName, TableName, StatName, Command, ModificationCounter, DaysStale, PageCount)
                    VALUES (@db, @schema, @table, @stat, @cmd, @mods, @days, @pages)';

                EXEC sys.sp_executesql
                    @whatif_insert_sql,
                    N'@db sysname, @schema sysname, @table sysname, @stat sysname, @cmd nvarchar(max), @mods bigint, @days int, @pages bigint',
                    @db = @current_database,
                    @schema = @current_schema_name,
                    @table = @current_table_name,
                    @stat = @current_stat_name,
                    @cmd = @current_command,
                    @mods = @current_modification_counter,
                    @days = @current_days_stale,
                    @pages = @current_page_count;
            END;

            SELECT
                @stats_skipped += 1,
                @claimed_table_stats_skipped += CASE WHEN @StatsInParallel = N'Y' THEN 1 ELSE 0 END;
        END;

        /*
        Delay between stats if specified.
        P2 fix (#210): Check @TimeLimit BEFORE sleeping. Previously the WAITFOR executed
        unconditionally, causing overshoot equal to the full delay duration even after
        the time budget was exhausted. Now we skip the sleep (and break) when time is up.
        */
        IF  @DelayBetweenStats IS NOT NULL
        AND @DelayBetweenStats > 0
        AND @Execute = N'Y'
        BEGIN
            /* Skip the sleep and exit the loop if we are already at or past the time limit */
            IF @TimeLimit IS NOT NULL AND DATEDIFF(SECOND, @start_time, SYSDATETIME()) >= @TimeLimit
            BEGIN
                RAISERROR(N'Time limit (%d seconds) reached (pre-delay check). Stopping gracefully.', 10, 1, @TimeLimit) WITH NOWAIT;
                SELECT @stop_reason = N'TIME_LIMIT';
                BREAK;
            END;

            DECLARE
                @delay_time datetime = DATEADD(MILLISECOND, CAST(@DelayBetweenStats * 1000 AS int), '00:00:00');

            WAITFOR DELAY @delay_time;
        END;

        /*
        Clear for next iteration
        */
        SELECT
            @current_command = NULL,
            @current_error_number = NULL,
            @current_error_message = NULL,
            @current_extended_info = NULL;

        /*
        Update global progress table (v1.9) for external monitoring.
        Only update every 10 stats or on completion to reduce overhead.
        */
        IF  @Execute = N'Y'
        AND @ExposeProgressToAllSessions = N'Y'
        AND (@stats_processed % 10 = 0 OR @stats_processed = @total_stats)
        AND OBJECT_ID('tempdb..##sp_StatUpdate_Progress', 'U') IS NOT NULL
        BEGIN
            BEGIN TRY
                UPDATE ##sp_StatUpdate_Progress
                SET
                    CurrentTime = SYSDATETIME(),
                    StatsFound = @total_stats,
                    StatsProcessed = @stats_processed,
                    StatsSucceeded = @stats_succeeded,
                    StatsFailed = @stats_failed,
                    CurrentDatabase = @current_database,
                    CurrentTable = @current_table_name,
                    CurrentStat = @current_stat_name,
                    ElapsedSeconds = DATEDIFF(SECOND, @start_time, SYSDATETIME())
                WHERE RunLabel = @run_label;
            END TRY
            BEGIN CATCH
                /* Ignore errors updating progress table - non-critical */
            END CATCH;
        END;

        /*
        ====================================================================
        PARALLEL MODE: Check if we're done with the current table
        ====================================================================
        If no more unprocessed stats for the claimed table, mark it complete
        and release the claim so we can claim the next table.
        */
        IF  @StatsInParallel = N'Y'
        AND @claimed_table_database IS NOT NULL
        BEGIN
            DECLARE
                @remaining_table_stats integer =
                (
                    SELECT
                        COUNT_BIG(*)
                    FROM #stats_to_process AS stp
                    WHERE stp.processed = 0
                    AND   stp.database_name = @claimed_table_database
                    AND   stp.schema_name = @claimed_table_schema
                    AND   stp.table_name = @claimed_table_name
                );

            IF @remaining_table_stats = 0
            BEGIN
                /*
                Mark table as complete in QueueStatistic
                */
                UPDATE
                    qs
                SET
                    qs.TableEndTime = SYSDATETIME(),
                    qs.StatsUpdated = @claimed_table_stats_updated,
                    qs.StatsFailed = @claimed_table_stats_failed,
                    qs.StatsSkipped = @claimed_table_stats_skipped
                FROM dbo.QueueStatistic AS qs
                WHERE qs.QueueID = @queue_id
                AND   qs.DatabaseName = @claimed_table_database
                AND   qs.SchemaName = @claimed_table_schema
                AND   qs.ObjectName = @claimed_table_name;

                IF @Debug = 1
                BEGIN
                    RAISERROR(N'  Completed table: %s.%s.%s (updated=%d, failed=%d, skipped=%d)', 10, 1,
                        @claimed_table_database,
                        @claimed_table_schema,
                        @claimed_table_name,
                        @claimed_table_stats_updated,
                        @claimed_table_stats_failed,
                        @claimed_table_stats_skipped) WITH NOWAIT;
                END;

                /*
                Release claim so next iteration will claim a new table
                */
                SELECT
                    @claimed_table_database = NULL,
                    @claimed_table_schema = NULL,
                    @claimed_table_name = NULL,
                    @claimed_table_object_id = NULL;
            END;
        END;
    END;
    /*#endregion 19-PROCESS-LOOP */

    /*#region 20-FINALIZE: Summary, CommandLog footer, output params, result set */
    /*
    ============================================================================
    SUMMARY
    ============================================================================
    */
    DECLARE
        @end_time datetime2(7) = SYSDATETIME(),
        @duration_seconds integer = DATEDIFF(SECOND, @start_time, SYSDATETIME()),
        @duration_ms_total bigint = DATEDIFF(MILLISECOND, @start_time, SYSDATETIME()),
        @remaining_stats integer =
        (
            SELECT
                COUNT_BIG(*)
            FROM #stats_to_process AS stp
            WHERE stp.processed = 0
        ),
        @end_time_display nvarchar(30) = CONVERT(nvarchar(30), SYSDATETIME(), 121);

    /*
    Determine stop reason if not already set
    */
    IF @stop_reason IS NULL
    BEGIN
        SELECT
            @stop_reason = N'NATURAL_END';
    END;

    /*
    Update global progress table with final status (v1.9)
    */
    IF  @Execute = N'Y'
    AND @ExposeProgressToAllSessions = N'Y'
    AND OBJECT_ID('tempdb..##sp_StatUpdate_Progress', 'U') IS NOT NULL
    BEGIN
        BEGIN TRY
            UPDATE ##sp_StatUpdate_Progress
            SET
                CurrentTime = @end_time,
                StatsFound = @total_stats,
                StatsProcessed = @stats_processed,
                StatsSucceeded = @stats_succeeded,
                StatsFailed = @stats_failed,
                ElapsedSeconds = @duration_seconds,
                Status = @stop_reason
            WHERE RunLabel = @run_label;
        END TRY
        BEGIN CATCH
            /* Ignore errors - non-critical */
        END CATCH;
    END;

    RAISERROR(N'', 10, 1) WITH NOWAIT;
    RAISERROR(N'===============================================================================', 10, 1) WITH NOWAIT;
    RAISERROR(N' Summary', 10, 1) WITH NOWAIT;
    RAISERROR(N'===============================================================================', 10, 1) WITH NOWAIT;
    RAISERROR(N'', 10, 1) WITH NOWAIT;
    RAISERROR(N'End time:        %s', 10, 1, @end_time_display) WITH NOWAIT;
    /* Sub-second duration display: show decimal seconds (e.g., 0.9s not 0s) */
    DECLARE @duration_display nvarchar(30) =
        CONVERT(nvarchar(20), @duration_ms_total / 1000) + N'.' +
        CONVERT(nvarchar(3), (@duration_ms_total % 1000) / 100) + N's';
    RAISERROR(N'Duration:        %s', 10, 1, @duration_display) WITH NOWAIT;
    RAISERROR(N'', 10, 1) WITH NOWAIT;
    RAISERROR(N'Stats processed: %d / %d', 10, 1, @stats_processed, @total_stats) WITH NOWAIT;
    RAISERROR(N'  Succeeded:     %d', 10, 1, @stats_succeeded) WITH NOWAIT;
    RAISERROR(N'  Failed:        %d', 10, 1, @stats_failed) WITH NOWAIT;
    IF @stats_toctou > 0
        RAISERROR(N'  TOCTOU skips:  %d (dropped objects)', 10, 1, @stats_toctou) WITH NOWAIT;
    RAISERROR(N'  Skipped:       %d (dry run)', 10, 1, @stats_skipped) WITH NOWAIT;
    RAISERROR(N'  Remaining:     %d', 10, 1, @remaining_stats) WITH NOWAIT;
    RAISERROR(N'', 10, 1) WITH NOWAIT;

    IF @remaining_stats > 0
    BEGIN
        RAISERROR(N'Note: %d stats remain. Re-run sp_StatUpdate to continue.', 10, 1, @remaining_stats) WITH NOWAIT;
    END;

    RAISERROR(N'===============================================================================', 10, 1) WITH NOWAIT;

    /*
    ============================================================================
    QUERY STORE FORCED PLAN CHECK (#32)
    After stats updates, warn if forced plans exist on updated tables.
    Statistics changes may invalidate forced plan choices.
    ============================================================================
    */
    IF  @Execute = N'Y'
    AND @stats_succeeded > 0
    BEGIN
        DECLARE
            @qs_check_db sysname = NULL,
            @qs_check_sql nvarchar(max),
            @qs_forced_count int = 0,
            @qs_forced_total int = 0,
            @qs_forced_details nvarchar(max) = N'',
            @qs_db_idx int = 0;

        DECLARE @qs_databases TABLE
        (
            idx int IDENTITY(1,1) PRIMARY KEY,
            database_name sysname NOT NULL
        );

        INSERT INTO @qs_databases (database_name)
        SELECT DISTINCT stp.database_name
        FROM #stats_to_process AS stp
        WHERE stp.processed = 1;

        SELECT @qs_db_idx = MIN(idx) FROM @qs_databases;

        WHILE @qs_db_idx IS NOT NULL
        BEGIN
            SELECT @qs_check_db = database_name
            FROM @qs_databases
            WHERE idx = @qs_db_idx;

            BEGIN TRY
                /*
                P1 fix (#187): The original join on qsq.object_id = stp.object_id was broken.
                sys.query_store_query.object_id is the compiled module ID (stored proc/function),
                NOT the table's object_id. For ad-hoc queries it is always 0, so the join
                never matched any ad-hoc query plans. Fixed by joining query_store_query_text
                and checking if the table name appears in the query SQL text via CHARINDEX.
                This correctly identifies forced plans referencing tables whose stats were updated.
                */
                SET @qs_check_sql = N'
                    SELECT @cnt = COUNT(DISTINCT qsp.plan_id)
                    FROM ' + QUOTENAME(@qs_check_db) + N'.sys.query_store_plan AS qsp
                    INNER JOIN ' + QUOTENAME(@qs_check_db) + N'.sys.query_store_query AS qsq
                        ON qsq.query_id = qsp.query_id
                    INNER JOIN ' + QUOTENAME(@qs_check_db) + N'.sys.query_store_query_text AS qsqt
                        ON qsqt.query_text_id = qsq.query_text_id
                    WHERE qsp.is_forced_plan = 1
                    AND EXISTS (
                        SELECT 1 FROM #stats_to_process AS stp
                        WHERE stp.database_name = @dbname COLLATE DATABASE_DEFAULT
                        AND stp.processed = 1
                        AND CHARINDEX(stp.table_name COLLATE DATABASE_DEFAULT,
                                      qsqt.query_sql_text COLLATE DATABASE_DEFAULT) > 0
                    )';

                EXEC sp_executesql @qs_check_sql,
                    N'@dbname sysname, @cnt int OUTPUT',
                    @dbname = @qs_check_db,
                    @cnt = @qs_forced_count OUTPUT;

                IF ISNULL(@qs_forced_count, 0) > 0
                BEGIN
                    SET @qs_forced_total = @qs_forced_total + @qs_forced_count;
                    SET @qs_forced_details = @qs_forced_details
                        + @qs_check_db + N'(' + CONVERT(nvarchar(10), @qs_forced_count) + N') ';
                END;
            END TRY
            BEGIN CATCH
                /* Query Store not enabled or not accessible on this database — skip */
            END CATCH;

            SELECT @qs_db_idx = MIN(idx) FROM @qs_databases WHERE idx > @qs_db_idx;
        END;

        IF @qs_forced_total > 0
        BEGIN
            SET @warnings = @warnings + N'QS_FORCED_PLANS: '
                + CONVERT(nvarchar(10), @qs_forced_total)
                + N' forced plan(s) on updated tables — verify plan quality: '
                + RTRIM(@qs_forced_details) + N'; ';
            RAISERROR(N'', 10, 1) WITH NOWAIT;
            RAISERROR(N'WARNING: %d Query Store forced plan(s) on tables with updated statistics: %s', 10, 1, @qs_forced_total, @qs_forced_details) WITH NOWAIT;
            RAISERROR(N'         Stats changes may affect forced plan quality. Review with sys.query_store_plan.', 10, 1) WITH NOWAIT;
        END;
    END;

    /*
    ============================================================================
    LOG RUN_FOOTER TO COMMANDLOG
    ============================================================================
    */
    IF  @LogToTable = N'Y'
    AND @Execute = N'Y'
    AND @commandlog_exists = 1
    BEGIN
        /* Build JSON summary for monitoring integration (v2.3) */
        DECLARE @json_status nvarchar(10) =
            CASE
                WHEN @stats_failed > 0 THEN N'ERROR'
                WHEN @remaining_stats > 0 THEN N'WARNING'
                ELSE N'OK'
            END;
        DECLARE @json_summary_str nvarchar(500) =
            N'{"succeeded":' + CONVERT(nvarchar(20), @stats_succeeded)
            + N',"failed":' + CONVERT(nvarchar(20), @stats_failed)
            + N',"duration_seconds":' + CONVERT(nvarchar(20), @duration_seconds)
            + N',"status":"' + @json_status + N'"}';

        DECLARE
            @summary_xml xml =
            (
                SELECT
                    @procedure_version AS [Version],
                    @run_label AS RunLabel,
                    @@SPID AS SessionID,
                    @total_stats AS StatsFound,
                    @stats_processed AS StatsProcessed,
                    @stats_succeeded AS StatsSucceeded,
                    @stats_failed AS StatsFailed,
                    @stats_toctou AS StatsToctou,
                    @remaining_stats AS StatsRemaining,
                    @duration_seconds AS DurationSeconds,
                    @stop_reason AS StopReason,
                    @json_summary_str AS JsonSummary
                FOR
                    XML RAW(N'Summary'),
                    ELEMENTS
            );

        BEGIN TRY
            INSERT INTO
                dbo.CommandLog
            (
                DatabaseName,
                SchemaName,
                ObjectName,
                ObjectType,
                Command,
                CommandType,
                StartTime,
                EndTime,
                ExtendedInfo
            )
            VALUES
            (
                ISNULL(@Databases, DB_NAME()),
                N'dbo',
                N'sp_StatUpdate',
                N'P',
                N'sp_StatUpdate completed: ' + @stop_reason,
                N'SP_STATUPDATE_END',
                @start_time,
                @end_time,
                @summary_xml
            );

            RAISERROR(N'', 10, 1) WITH NOWAIT;
            RAISERROR(N'Run logged: %s (StopReason: %s)', 10, 1, @run_label, @stop_reason) WITH NOWAIT;
        END TRY
        BEGIN CATCH
            SELECT @log_error_msg = LEFT(ERROR_MESSAGE(), 3900);
            RAISERROR(N'WARNING: Failed to log run end to CommandLog (%s)', 10, 1, @log_error_msg) WITH NOWAIT;
        END CATCH;
    END;

    /*
    ============================================================================
    POPULATE OUTPUT PARAMETERS (for automation)
    ============================================================================
    */
    IF @stats_toctou > 0
        SET @warnings = @warnings + N'TOCTOU_SKIPS: ' + CONVERT(nvarchar(10), @stats_toctou) + N' stat(s) skipped (objects dropped during run); ';

    SELECT
        @StatsFoundOut = @total_stats,
        @StatsProcessedOut = @stats_processed,
        @StatsSucceededOut = @stats_succeeded,
        @StatsFailedOut = @stats_failed,
        @StatsRemainingOut = @remaining_stats,
        @DurationSecondsOut = @duration_seconds,
        @WarningsOut = NULLIF(@warnings, N''),
        /* #179: If databases were skipped, append to stop reason so automation sees partial completion */
        @StopReasonOut = CASE
            WHEN @warnings LIKE N'%DB_SKIPPED:%' AND @stop_reason = N'COMPLETED'
            THEN N'COMPLETED_WITH_SKIPPED_DBS'
            ELSE @stop_reason
        END;

    /*
    ============================================================================
    COMPLETION NOTIFY TABLE (#64)
    Insert notification row for ETL pipeline dependency chains.
    Auto-creates the table if it doesn't exist.
    ============================================================================
    */
    IF @CompletionNotifyTable IS NOT NULL
    BEGIN
        BEGIN TRY
            DECLARE @notify_sql nvarchar(max);

            /* P1 fix (#155): Use @safe_cnt_fqn (PARSENAME+QUOTENAME validated) instead of raw @CompletionNotifyTable */
            /* Auto-create table if it doesn't exist */
            SET @notify_sql = N'
                IF OBJECT_ID(N''' + REPLACE(@safe_cnt_fqn, N'''', N'''''') + N''', N''U'') IS NULL
                BEGIN
                    CREATE TABLE ' + @safe_cnt_fqn + N' (
                        ID int IDENTITY(1,1) PRIMARY KEY,
                        RunLabel nvarchar(100) NOT NULL,
                        StartTime datetime2(7) NOT NULL,
                        EndTime datetime2(7) NOT NULL,
                        StopReason nvarchar(50) NULL,
                        StatsFound int NOT NULL,
                        StatsSucceeded int NOT NULL,
                        StatsFailed int NOT NULL,
                        StatsRemaining int NOT NULL,
                        DurationSeconds int NOT NULL,
                        Warnings nvarchar(max) NULL
                    );
                END;
                INSERT INTO ' + @safe_cnt_fqn + N'
                    (RunLabel, StartTime, EndTime, StopReason, StatsFound, StatsSucceeded, StatsFailed, StatsRemaining, DurationSeconds, Warnings)
                VALUES
                    (@rl, @st, @et, @sr, @sf, @ss, @sfl, @rem, @dur, @wrn);';

            EXEC sp_executesql @notify_sql,
                N'@rl nvarchar(100), @st datetime2(7), @et datetime2(7), @sr nvarchar(50),
                  @sf int, @ss int, @sfl int, @rem int, @dur int, @wrn nvarchar(max)',
                @rl = @run_label, @st = @start_time, @et = @end_time, @sr = @stop_reason,
                @sf = @total_stats, @ss = @stats_succeeded, @sfl = @stats_failed,
                @rem = @remaining_stats, @dur = @duration_seconds, @wrn = @warnings;
        END TRY
        BEGIN CATCH
            DECLARE @notify_err nvarchar(500) = N'WARNING: Failed to write to @CompletionNotifyTable: ' + LEFT(ERROR_MESSAGE(), 400);
            RAISERROR(@notify_err, 10, 1) WITH NOWAIT;
        END CATCH;
    END;

    /*
    ============================================================================
    RETURN SUMMARY RESULT SET
    ============================================================================
    Provides programmatic access to run statistics.
    Enables automation scripts to capture and react to results.
    */
    SELECT
        /*
        Status: Enables easy Agent job alerting
          ERROR   = At least one statistic failed to update
          WARNING = Stats skipped or remaining (time/batch limit)
          SUCCESS = All discovered stats updated without issues
        */
        Status = CASE
            WHEN @stats_failed > 0 THEN N'ERROR'
            WHEN @stats_skipped > 0 OR @remaining_stats > 0 THEN N'WARNING'
            ELSE N'SUCCESS'
        END,
        StatusMessage = CASE
            WHEN @stats_failed > 0 AND @remaining_stats > 0
                THEN N'Failed: ' + CONVERT(nvarchar(10), @stats_failed) + N' stat(s), '
                    + CONVERT(nvarchar(10), @remaining_stats) + N' remaining (' + ISNULL(@stop_reason, N'unknown') + N')'
            WHEN @stats_failed > 0
                THEN N'Failed: ' + CONVERT(nvarchar(10), @stats_failed) + N' stat(s)'
            WHEN @remaining_stats > 0
                THEN N'Incomplete: ' + CONVERT(nvarchar(10), @remaining_stats) + N' stat(s) remaining (' + ISNULL(@stop_reason, N'unknown') + N')'
            WHEN @stats_skipped > 0
                THEN N'Skipped: ' + CONVERT(nvarchar(10), @stats_skipped) + N' stat(s)'
            ELSE N'All ' + CONVERT(nvarchar(10), @stats_succeeded) + N' stat(s) updated successfully'
        END,
        StatsFound = @total_stats,
        StatsProcessed = @stats_processed,
        StatsSucceeded = @stats_succeeded,
        StatsFailed = @stats_failed,
        StatsToctou = @stats_toctou,
        StatsSkipped = @stats_skipped,
        StatsRemaining = @remaining_stats,
        DatabasesProcessed = @database_count,
        DurationSeconds = @duration_seconds,
        StopReason = @stop_reason,
        RunLabel = @run_label,
        Version = @procedure_version;

    /*
    ============================================================================
    DETAILED RESULTS (#25)
    Per-statistic result set for PowerShell/automation integration.
    ============================================================================
    */
    IF @ReturnDetailedResults = 1
    BEGIN
        SELECT
            DatabaseName = stp.database_name,
            SchemaName = stp.schema_name,
            TableName = stp.table_name,
            StatisticName = stp.stat_name,
            Modifications = stp.modification_counter,
            DaysStale = stp.days_stale,
            PageCount = stp.page_count,
            RowCount_ = stp.row_count,
            Priority = stp.priority,
            Processed = stp.processed,
            IsHeap = stp.is_heap,
            AutoCreated = stp.auto_created,
            NoRecompute = stp.no_recompute,
            IsIncremental = stp.is_incremental,
            HasFilter = stp.has_filter,
            QSPriorityBoost = stp.qs_priority_boost,
            /* #252: Per-signal breakdown — helps identify which threshold triggered each stat */
            ModPctOfThreshold = CASE
                WHEN ISNULL(@ModificationThreshold, 0) > 0
                THEN CONVERT(decimal(10, 1), stp.modification_counter * 100.0 / @ModificationThreshold)
                ELSE NULL
            END,
            DaysStalePctOfThreshold = CASE
                WHEN @DaysStaleThreshold IS NOT NULL AND @DaysStaleThreshold > 0
                THEN CONVERT(decimal(10, 1), stp.days_stale * 100.0 / @DaysStaleThreshold)
                ELSE NULL
            END,
            FilteredDriftRatio = stp.filtered_drift_ratio,
            PriorityRank = ROW_NUMBER() OVER (ORDER BY stp.priority),
            IsNearThreshold = CONVERT(bit, CASE
                WHEN ISNULL(@ModificationThreshold, 0) > 0
                AND  stp.modification_counter >= @ModificationThreshold * 0.8
                AND  stp.modification_counter < @ModificationThreshold
                THEN 1
                ELSE 0
            END)
        FROM #stats_to_process AS stp
        ORDER BY stp.priority;
    END;

    /*
    Ensure non-zero return code when failures occurred (Agent job detection)
    */
    IF @stats_failed > 0 AND @return_code = 0
    BEGIN
        SELECT @return_code = 1; /*Generic failure code for Agent jobs*/
    END;

    /*
    Release re-entrancy guard (sp_HeapDoctor pattern)
    */
    IF @StatsInParallel = N'N'
    BEGIN
        EXEC sp_releaseapplock
            @Resource = N'sp_StatUpdate',
            @LockOwner = N'Session';
    END;

    RETURN @return_code;
    /*#endregion 20-FINALIZE */
END;
GO

/*
===============================================================================
USAGE EXAMPLES
===============================================================================

-------------------------------------------------------------------------------
HELP - Because RTFM is a lifestyle
-------------------------------------------------------------------------------

-- Show help in SSMS result set (40+ parameters, you'll need this)
EXECUTE dbo.sp_StatUpdate @Help = 1;

-- Get version info (for when someone asks "what version are you running?")
DECLARE @v varchar(20), @d datetime;
EXECUTE dbo.sp_StatUpdate @Version = @v OUTPUT, @VersionDate = @d OUTPUT;
SELECT @v AS Version, @d AS VersionDate;

-------------------------------------------------------------------------------
PRESETS - For those who just want it to work
-------------------------------------------------------------------------------

-- "I don't care about the details, just fix my stats overnight"
EXECUTE dbo.sp_StatUpdate
    @Preset = N'NIGHTLY_MAINTENANCE',
    @Databases = N'USER_DATABASES';

-- "It's Sunday, we have 4 hours, go nuts"
EXECUTE dbo.sp_StatUpdate
    @Preset = N'WEEKLY_FULL',
    @Databases = N'USER_DATABASES';

-- "It's 2pm and the CEO's dashboard is slow. Be gentle."
EXECUTE dbo.sp_StatUpdate
    @Preset = N'OLTP_LIGHT',
    @Databases = N'SalesDB';

-- "It's a data warehouse. Nobody's watching. FULLSCAN everything."
EXECUTE dbo.sp_StatUpdate
    @Preset = N'WAREHOUSE_AGGRESSIVE',
    @Databases = N'DW_Production';

-------------------------------------------------------------------------------
THE CLASSIC PROBLEM: "Our maintenance job keeps getting killed at 5 AM"
-------------------------------------------------------------------------------

-- Your job runs alphabetically, spends 4 hours on AAA_Archive, then gets
-- killed when business hours start. Meanwhile, Orders and Customers are stale.
-- Solution: Worst-first ordering with a hard stop time.

EXECUTE dbo.sp_StatUpdate
    @Databases = N'USER_DATABASES',
    @SortOrder = N'MODIFICATION_COUNTER',  -- Most stale first
    @TimeLimit = 14400,                     -- 4 hours max, then stop gracefully
    @TargetNorecompute = N'BOTH';           -- Regular and NORECOMPUTE stats

-------------------------------------------------------------------------------
THE NORECOMPUTE PROBLEM: "Who turned off auto-update on these stats?"
-------------------------------------------------------------------------------

-- Someone (maybe you, maybe a vendor, maybe a consultant from 2019) set
-- NORECOMPUTE on critical statistics. SQL Server won't auto-update them.
-- They're now 6 months stale. This is fine.

EXECUTE dbo.sp_StatUpdate
    @Databases = N'VendorApp',
    @TargetNorecompute = N'Y',              -- Only NORECOMPUTE stats
    @ModificationThreshold = 1000,          -- Pretty much all of them
    @TimeLimit = 7200;

-------------------------------------------------------------------------------
THE PARANOID DBA: "Show me what you'd do, but don't touch anything"
-------------------------------------------------------------------------------

-- Dry run with debug output. Trust, but verify.
EXECUTE dbo.sp_StatUpdate
    @Databases = N'Production',
    @Execute = N'N',                        -- Don't actually do anything
    @Debug = 1;                             -- But tell me everything

-- Capture commands to a table for review/automation
EXECUTE dbo.sp_StatUpdate
    @Databases = N'Production',
    @Execute = N'N',
    @WhatIfOutputTable = N'tempdb.dbo.StatsToUpdate';

SELECT * FROM tempdb.dbo.StatsToUpdate ORDER BY SequenceNum;

-------------------------------------------------------------------------------
THE "QUERY STORE KNOWS BEST" APPROACH
-------------------------------------------------------------------------------

-- Let Query Store tell you which stats actually matter. Why update stats
-- on tables nobody queries? Focus on the hot paths.

EXECUTE dbo.sp_StatUpdate
    @Databases = N'Production',
    @QueryStorePriority = N'Y',             -- Boost stats used by QS plans
    @QueryStoreMetric = N'CPU',             -- Prioritize by CPU consumption
    @QueryStoreRecentHours = 48,            -- Only recent activity
    @SortOrder = N'QUERY_STORE',            -- QS priority ordering
    @TimeLimit = 3600;

-------------------------------------------------------------------------------
THE PARTITIONED TABLE NIGHTMARE
-------------------------------------------------------------------------------

-- You have a 2TB partitioned fact table. FULLSCAN takes 6 hours.
-- Incremental stats only update modified partitions. Much faster.

EXECUTE dbo.sp_StatUpdate
    @Databases = N'DataWarehouse',
    @Tables = N'dbo.FactSales',
    @UpdateIncremental = N'Y';              -- Only stale partitions

-------------------------------------------------------------------------------
THE "THIS ONE STAT TAKES 4 HOURS" PROBLEM
-------------------------------------------------------------------------------

-- Some genius set 100% sample on a billion-row table. It never finishes.
-- Query CommandLog for historically slow stats and force a lower sample.

EXECUTE dbo.sp_StatUpdate
    @Databases = N'BigData',
    @LongRunningThresholdMinutes = 60,      -- Stats that took >1hr before
    @LongRunningSamplePercent = 5,          -- Force 5% sample on those
    @TimeLimit = 14400;

-------------------------------------------------------------------------------
MULTI-DATABASE WITH EXCLUSIONS
-------------------------------------------------------------------------------

-- All user databases except the ones that always cause problems
EXECUTE dbo.sp_StatUpdate
    @Databases = N'USER_DATABASES, -DevDB, -TestDB, -ReportServerTempDB';

-- All databases matching a pattern
EXECUTE dbo.sp_StatUpdate
    @Databases = N'%_Production';

-- Skip archive and staging tables entirely
EXECUTE dbo.sp_StatUpdate
    @Databases = N'MyDatabase',
    @ExcludeTables = N'dbo.%Archive%, dbo.Staging_%';

-------------------------------------------------------------------------------
PARALLEL MODE - When one worker isn't enough
-------------------------------------------------------------------------------

-- Run this SAME command from 4 SQL Agent jobs simultaneously.
-- They coordinate via dbo.QueueStatistic. No duplicate work.

EXECUTE dbo.sp_StatUpdate
    @Databases = N'USER_DATABASES',
    @StatsInParallel = N'Y',                -- Enable queue-based coordination
    @LockTimeout = 30,                      -- Don't wait forever for locks
    @TimeLimit = 7200;

-- Monitor parallel progress from another session
SELECT * FROM dbo.QueueStatistic WHERE QueueID = 1 AND TableStartTime IS NOT NULL;

-------------------------------------------------------------------------------
DIRECT MODE - When you know exactly what needs updating
-------------------------------------------------------------------------------

-- "Just update these two stats and stop bothering me"
EXECUTE dbo.sp_StatUpdate
    @Statistics = N'dbo.Orders.IX_Orders_CustomerID, dbo.Customers.PK_Customers';

-- From a priority queue table (for custom prioritization logic)
EXECUTE dbo.sp_StatUpdate
    @StatisticsFromTable = N'Maintenance.dbo.StatsPriorityQueue',
    @TimeLimit = 3600;

-------------------------------------------------------------------------------
MONITORING YOUR RUN
-------------------------------------------------------------------------------

-- Secure: Write progress to CommandLog every 50 stats
EXECUTE dbo.sp_StatUpdate
    @Databases = N'Production',
    @ProgressLogInterval = 50;

-- Less secure but convenient: Global temp table (visible to all sessions!)
EXECUTE dbo.sp_StatUpdate
    @Databases = N'Production',
    @ExposeProgressToAllSessions = N'Y';

-- Then from another session:
SELECT * FROM ##sp_StatUpdate_Progress;

-------------------------------------------------------------------------------
AFTER THE RUN: Did it finish or get killed?
-------------------------------------------------------------------------------

SELECT
    CASE WHEN e.ID IS NOT NULL THEN 'Completed' ELSE 'KILLED' END AS Status,
    s.StartTime,
    e.ExtendedInfo.value('(/Summary/StopReason)[1]', 'nvarchar(50)') AS StopReason,
    e.ExtendedInfo.value('(/Summary/StatsProcessed)[1]', 'int') AS Processed,
    e.ExtendedInfo.value('(/Summary/StatsRemaining)[1]', 'int') AS Remaining
FROM dbo.CommandLog s
LEFT JOIN dbo.CommandLog e
    ON e.CommandType = 'SP_STATUPDATE_END'
    AND e.ExtendedInfo.value('(/Summary/RunLabel)[1]', 'nvarchar(100)') =
        s.ExtendedInfo.value('(/Parameters/RunLabel)[1]', 'nvarchar(100)')
WHERE s.CommandType = 'SP_STATUPDATE_START'
ORDER BY s.StartTime DESC;

===============================================================================
*/