<?php

declare(strict_types=1);

namespace SiteFort\Modules\Scanner\Queue;

use SiteFort\Modules\Scanner\Repository\ScanQueueRepository;
use SiteFort\Modules\Scanner\Repository\FileStateRepository;
use SiteFort\Modules\Scanner\Repository\TaskQueueRepository;
use SiteFort\Modules\Scanner\Service\ScanStatusService;

if ( ! defined( 'ABSPATH' ) ) {
    exit;
}

/**
 * Coordinates scan queue state and task setup.
 */
class ScanQueue {

    public const SYSTEM_CHECKS = [ 'reputation', 'users', 'content', 'sensitive_data', 'vulnerabilities' ];
    public const SYSTEM_CHECK_PRIORITY = 90;
    private const SYSTEM_CHECK_INITIAL_DELAY_SECONDS = 5;
    
    /** @var ScanQueueRepository */
    private static $repo;

    /** @var ScanStatusService */
    private static $statusService;

    /**
     * Escape a plugin-owned table identifier for direct interpolation.
     */
    private static function table_identifier( string $table ): string {
        if ( $table === '' || strlen( $table ) > 64 || ! preg_match( '/^[A-Za-z0-9_]+$/', $table ) ) {
            throw new \InvalidArgumentException( 'Invalid table identifier.' );
        }

        return '`' . str_replace( '`', '``', $table ) . '`';
    }

    /**
     * Resolve issue types that should be reconciled for completed components.
     *
     * File scan findings persist under the canonical `integrity` type; the
     * extra aliases ensure historical rows are reconciled during publish.
     *
     * @param array<int,string> $completed_components
     * @return array<int,string>
     */
    private static function resolve_issue_types_for_completed_components( array $completed_components ): array {
        $map_component_to_types = [
            // site_health is staged by the startup preflight, so it publishes with file_scan.
            'file_scan'       => [ 'malware', 'fake_image', 'integrity', 'modified', 'core', 'skipped', 'system_error', 'site_health' ],
            'reputation'      => [ 'blocklist' ],
            'users'           => [ 'user' ],
            'content'         => [ 'content' ],
            'sensitive_data'  => [ 'sensitive_data' ],
            'vulnerabilities' => [ 'vulnerability' ],
        ];

        $types_to_resolve = [];
        foreach ( $completed_components as $component ) {
            if ( isset( $map_component_to_types[ $component ] ) ) {
                $types_to_resolve = array_merge( $types_to_resolve, $map_component_to_types[ $component ] );
            }
        }

        return array_values( array_unique( $types_to_resolve ) );
    }

    private static function reconcile_published_vulnerability_findings(): void {
        $class = '\SiteFort\Modules\Vulnerability\Services\VulnerabilityRemediationService';
        if ( ! class_exists( $class ) ) {
            $path = dirname( dirname( __DIR__ ) ) . '/Vulnerability/Services/VulnerabilityRemediationService.php';
            if ( file_exists( $path ) ) {
                require_once $path;
            }
        }

        if ( ! class_exists( $class ) ) {
            sitefort_log( 'SiteFort: Vulnerability remediation service class missing during scan completion.' );
            return;
        }

        try {
            ( new $class() )->purge_resolved_active_findings();
        } catch ( \Throwable $e ) {
            sitefort_log( 'SiteFort: Vulnerability reconciliation failed during scan completion: ' . $e->getMessage() );
        }
    }

    /**
     * Build publish rules for scans that have explicitly skipped deep-analysis files.
     *
     * A file skipped because deep-analysis credits were exhausted reached a terminal
     * FSM state for scan progress, but it was not rechecked. Prior active file
     * findings for that exact path must therefore remain active until a future scan
     * actually analyzes the file.
     *
     * @param array<int,string> $types_to_resolve Issue types in this publish scope.
     * @param bool              $unscoped_publish Whether stale cleanup is intentionally unscoped.
     * @return array<string,mixed>
     */
    private static function build_publish_options( array $types_to_resolve, bool $unscoped_publish = false ): array {
        $file_issue_types = self::resolve_issue_types_for_completed_components( [ 'file_scan' ] );
        if ( ! $unscoped_publish && empty( array_intersect( $types_to_resolve, $file_issue_types ) ) ) {
            return [];
        }

        return [
            'preserve_skipped_file_findings' => [
                'skip_reasons' => [ FileStateRepository::SKIP_REASON_DEEP_ANALYSIS_CREDIT_EXHAUSTED ],
                'types'        => $file_issue_types,
            ],
        ];
    }

    // Singleton / Static Initialization
    private static function init() {
        if ( ! isset( self::$repo ) ) {
            self::$repo = new ScanQueueRepository();
            self::$statusService = new ScanStatusService();
        }

    }

    /**
     * Create a new scan job.
     * 
     * @param string $scan_type
     * @param string $source
     * @param string|null $force_id Optional pre-generated ID (e.g. from preflight)
     */
    public static function create( $scan_type, $source = 'local', $force_id = null ) {
        self::init();

        $job_id = $force_id ? $force_id : 'scan_' . wp_generate_uuid4();
        $now = time();

        $data = [
            'job_id'      => $job_id,
            'scan_type'   => $scan_type,
            'source'      => $source,
            'status'      => 'pending',
            'total_count' => 0,
            'processed_count' => 0,
            'cloud_stats' => wp_json_encode( [ 'files' => [ 'pending' => 0, 'complete' => 0, 'failed' => 0 ] ] ),
            'component_status' => wp_json_encode( [] ),
            'next_run_at' => $now,
            'last_dispatch_at' => 0,
            'cloud_error_count' => 0,
            'created_at'  => $now,
            'updated_at'  => $now,
            'last_ping'   => $now, // Initialize to prevent false "stuck" detection
        ];

        $insert_id = self::$repo->create_if_no_active( $data );
        if ( $insert_id ) {
            // Winner-only reset. These must only run after we own queue creation.
            delete_transient( 'sitefort_cloud_fail_count' );
            delete_transient( 'sitefort_last_scan_alert' );
            \SiteFort\Includes\SettingsStore::delete_field( \SiteFort\Includes\SettingsStore::COL_STATE, 'last_scan_failure_context' );

            if ( class_exists( 'SiteFort\\Modules\\Scanner\\Service\\ScanLogger' ) ) {
                \SiteFort\Modules\Scanner\Service\ScanLogger::clear();
            }
            self::reset_scan_runtime_tables();

            if ( class_exists( 'SiteFort\\Modules\\Scanner\\Service\\ScanLogger' ) ) {
                \SiteFort\Modules\Scanner\Service\ScanLogger::log( "QUEUE_CREATE: Success." );
            }
            $queue = self::get_job( $job_id );

            // Create the scan-run history row up front so terminal status updates always have a target.
            if ( $queue && ! class_exists( '\SiteFort\Modules\Scanner\Repository\IssueRepository' ) ) {
                require_once dirname( __DIR__ ) . '/Repository/IssueRepository.php';
            }
            if ( $queue ) {
                $config_snapshot = [
                    'type' => $scan_type,
                    'mode' => 'standard',
                    'items_count' => 0
                ];
                \SiteFort\Modules\Scanner\Repository\IssueRepository::createScanRun(
                    $queue['id'], 
                    $config_snapshot, 
                    $now 
                );

                do_action( 'sitefort_scan_started', [
                    'site_url'  => home_url(),
                    'scan_id'   => $queue['job_id'] ?? $queue['id'],
                    'scan_type' => $scan_type,
                    'status'    => $queue['status'] ?? 'pending',
                ] );
            }

            if ( ! $queue || ! self::seed_initial_tasks( (string) $queue['id'] ) ) {
                if ( $queue ) {
                    self::$repo->update( $queue['id'], [
                        'status'     => 'failed',
                        'updated_at' => $now,
                    ] );
                }
                return false;
            }

            // The resume ticker exists only while a scan is active.
            if ( ! class_exists( ScanCron::class ) ) {
                require_once __DIR__ . '/ScanCron.php';
            }
            ScanCron::ensure_active_scan_ticker();

            return $queue;
        }
        
        if ( class_exists( 'SiteFort\\Modules\\Scanner\\Service\\ScanLogger' ) ) {
            \SiteFort\Modules\Scanner\Service\ScanLogger::log( "QUEUE_CREATE: blocked (active scan exists or insert failed).", 3, 'error' );
        }
        return false;
    }

    /**
     * Reset runtime scan artifacts from previous runs.
     *
     * Runs only after atomic queue creation wins to avoid deleting artifacts
     * while another active scan exists.
     */
    private static function reset_scan_runtime_tables(): void {
        global $wpdb;

        $cloud_jobs_table  = $wpdb->prefix . 'sitefort_cloud_jobs';
        $cloud_jobs_identifier = self::table_identifier( $cloud_jobs_table );
        $file_states_table = $wpdb->prefix . 'sitefort_file_states';
        $file_states_identifier = self::table_identifier( $file_states_table );

        $deleted_jobs = 0;
        $deleted_files = 0;

        // phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery,WordPress.DB.DirectDatabaseQuery.NoCaching -- Checks existence of a plugin-owned cloud jobs table before clearing runtime artifacts.
        $cloud_jobs_exists = (string) $wpdb->get_var( $wpdb->prepare( 'SHOW TABLES LIKE %s', $cloud_jobs_table ) );
        if ( $cloud_jobs_exists === $cloud_jobs_table ) {
            // phpcs:disable WordPress.DB.DirectDatabaseQuery.DirectQuery,WordPress.DB.DirectDatabaseQuery.NoCaching,WordPress.DB.PreparedSQL.InterpolatedNotPrepared,PluginCheck.Security.DirectDB.UnescapedDBParameter
            $deleted_jobs = (int) $wpdb->query( "DELETE FROM {$cloud_jobs_identifier}" );
            // phpcs:enable WordPress.DB.DirectDatabaseQuery.DirectQuery,WordPress.DB.DirectDatabaseQuery.NoCaching,WordPress.DB.PreparedSQL.InterpolatedNotPrepared,PluginCheck.Security.DirectDB.UnescapedDBParameter
        }

        // phpcs:ignore WordPress.DB.DirectDatabaseQuery.DirectQuery,WordPress.DB.DirectDatabaseQuery.NoCaching -- Checks existence of a plugin-owned file-states table before clearing runtime artifacts.
        $file_states_exists = (string) $wpdb->get_var( $wpdb->prepare( 'SHOW TABLES LIKE %s', $file_states_table ) );
        if ( $file_states_exists === $file_states_table ) {
            // phpcs:disable WordPress.DB.DirectDatabaseQuery.DirectQuery,WordPress.DB.DirectDatabaseQuery.NoCaching,WordPress.DB.PreparedSQL.InterpolatedNotPrepared,PluginCheck.Security.DirectDB.UnescapedDBParameter
            $deleted_files = (int) $wpdb->query( "DELETE FROM {$file_states_identifier}" );
            // phpcs:enable WordPress.DB.DirectDatabaseQuery.DirectQuery,WordPress.DB.DirectDatabaseQuery.NoCaching,WordPress.DB.PreparedSQL.InterpolatedNotPrepared,PluginCheck.Security.DirectDB.UnescapedDBParameter
        }

        if ( class_exists( 'SiteFort\\Modules\\Scanner\\Service\\ScanLogger' ) ) {
            \SiteFort\Modules\Scanner\Service\ScanLogger::log(
                sprintf( 'Scan reset: cleared %d cloud jobs and %d file states', $deleted_jobs, $deleted_files )
            );
        }
    }

    /**
     * Seed the durable task queue for a new scan.
     *
     * @param string $scan_id
     * @return bool
     */
    private static function seed_initial_tasks( string $scan_id ): bool {
        if ( ! class_exists( TaskQueueRepository::class ) ) {
            require_once dirname( __DIR__ ) . '/Repository/TaskQueueRepository.php';
        }

        $repo = new TaskQueueRepository();
        // 50 beats system checks (90) so the bootstrap slice runs first even on
        // a slow queue; follow-up slices re-enqueue at 100.
        $worker_seeded = $repo->enqueue(
            $scan_id,
            'scan_worker',
            [],
            time(),
            50
        );

        if ( false === $worker_seeded || 0 === (int) $worker_seeded ) {
            return false;
        }

        $tasks = [];
        $system_check_available_at = time() + self::SYSTEM_CHECK_INITIAL_DELAY_SECONDS;

        foreach ( self::SYSTEM_CHECKS as $slug ) {
            $tasks[] = [
                'scan_id'      => $scan_id,
                'task_type'    => 'system_check',
                'payload'      => [ 'check_slug' => $slug ],
                'available_at' => $system_check_available_at,
                'priority'     => self::SYSTEM_CHECK_PRIORITY,
                'dedupe_key'   => 'syscheck:' . $slug,
            ];
        }

        $repo->enqueue_batch( $tasks );
        return true;
    }

    public static function get_job( $job_id ) {
        self::init();
        $row = self::$repo->find_by_job_id( $job_id );
        return $row ? self::map_row( $row ) : null;
    }

    public static function get() {
        self::init();
        $row = self::$repo->find_active();
        return $row ? self::map_row( $row ) : null;
    }

    public static function update( $data ) {
        self::init();

        // Prepare partial update for DB
        $db_update = [];

        // Map Queue Keys -> DB Columns
        if ( isset( $data['status'] ) ) $db_update['status'] = $data['status'];
        if ( isset( $data['processed'] ) ) $db_update['processed_count'] = (int) $data['processed'];
        if ( isset( $data['total_items'] ) ) $db_update['total_count'] = (int) $data['total_items'];
        if ( isset( $data['last_ping'] ) ) $db_update['last_ping'] = (int) $data['last_ping'];

        if ( isset( $data['cloud_stats'] ) ) {
            $db_update['cloud_stats'] = json_encode( $data['cloud_stats'] );
        }
        if ( isset( $data['next_run_at'] ) ) {
            $db_update['next_run_at'] = (int) $data['next_run_at'];
        }
        if ( isset( $data['last_dispatch_at'] ) ) {
            $db_update['last_dispatch_at'] = (int) $data['last_dispatch_at'];
        }
        if ( isset( $data['cloud_error_count'] ) ) {
            $db_update['cloud_error_count'] = (int) $data['cloud_error_count'];
        }
        if ( isset( $data['component_status'] ) ) {
            $db_update['component_status'] = is_string( $data['component_status'] )
                ? $data['component_status']
                : wp_json_encode( $data['component_status'] );
        }

        if ( empty( $db_update ) ) {
            return false;
        }

        // Single UPDATE scoped to the active row; no pre-SELECT needed.
        return self::$repo->update_active( $db_update );
    }

    /**
     * Record a cloud error and return the current count.
     *
     * @param string $error_message
     * @return int
     */
    public static function record_cloud_error( string $error_message ): int {
        self::init();
        $queue = self::get();
        if ( ! $queue ) return 0;

        $count = self::$repo->increment_cloud_error( (string) $queue['id'] );

        if ( class_exists( '\SiteFort\Modules\Scanner\Service\ScanLogger' ) ) {
            \SiteFort\Modules\Scanner\Service\ScanLogger::log( 'Cloud error: ' . $error_message, 3, 'error' );
        }

        return $count;
    }

    /**
     * Reset cloud error counter after a successful cloud operation.
     *
     * @return void
     */
    public static function reset_cloud_errors(): void {
        self::init();
        $queue = self::get();
        if ( ! $queue ) return;
        if ( (int) ( $queue['cloud_error_count'] ?? 0 ) === 0 ) return;
        self::update( [ 'cloud_error_count' => 0 ] );
    }

    /**
     * Start the scan (Transition Pending -> Running).
     */
    public static function start() {
        $updated = self::update( [ 'status' => 'running' ] );
        if ( $updated ) {
            $queue = self::get();
            if ( $queue ) {
                do_action( 'sitefort_scan_started', [
                    'site_url'  => home_url(),
                    'scan_id'   => $queue['job_id'] ?? $queue['id'],
                    'scan_type' => $queue['scan_type'] ?? ( $queue['type'] ?? 'standard' ),
                    'status'    => 'running',
                ] );
            }
        }
        return $updated;
    }

    /**
     * Mark the scan as complete.
     */
    public static function complete() {
        self::init();
        $queue = self::get();
        if ( ! $queue ) return [];

        $completed_at = time();
        self::$repo->update( $queue['id'], [
            'status'     => 'complete',
            'updated_at' => $completed_at,
        ] );
        \SiteFort\Includes\SettingsStore::set_field( \SiteFort\Includes\SettingsStore::COL_STATE, 'last_scan_status', 'complete' );
        \SiteFort\Includes\SettingsStore::set_field( \SiteFort\Includes\SettingsStore::COL_STATE, 'last_scan_time', $completed_at );
        \SiteFort\Includes\SettingsStore::delete_field( \SiteFort\Includes\SettingsStore::COL_STATE, 'last_scan_failure_context' );
        delete_transient( 'sitefort_last_scan_alert' );

        // Track total completed scans for setup widget.
        $completed_count = (int) \SiteFort\Includes\SettingsStore::get_field( \SiteFort\Includes\SettingsStore::COL_STATE, 'scans_completed', 0 );
        \SiteFort\Includes\SettingsStore::set_field( \SiteFort\Includes\SettingsStore::COL_STATE, 'scans_completed', (string) ( $completed_count + 1 ) );

        // Update local queue snapshot to terminal status.
        $queue['status'] = 'complete';

        $completed_components = [];
        $component_statuses = self::get_component_status( $queue, false );
        if ( empty( $component_statuses ) ) {
            $component_statuses = self::$statusService->get_all_complete_status();
        }

        foreach ( $component_statuses as $slug => $status ) {
            if ( $status === 'complete' ) {
                $completed_components[] = $slug;
            }
        }

        $types_to_resolve = self::resolve_issue_types_for_completed_components( $completed_components );

        $notify_new_vulnerabilities = in_array( 'vulnerabilities', $completed_components, true );
        $previous_vulnerability_issues = [];
        if ( $notify_new_vulnerabilities ) {
            if ( ! class_exists( '\SiteFort\Modules\Vulnerability\Services\VulnerabilityRefreshService' ) ) {
                $path = dirname( dirname( __DIR__ ) ) . '/Vulnerability/Services/VulnerabilityRefreshService.php';
                if ( file_exists( $path ) ) {
                    require_once $path;
                }
            }

            if ( class_exists( '\SiteFort\Modules\Vulnerability\Services\VulnerabilityRefreshService' ) ) {
                $previous_vulnerability_issues = \SiteFort\Modules\Vulnerability\Services\VulnerabilityRefreshService::getActiveVulnerabilityIssues();
            }
        }

        $published = \SiteFort\Modules\Scanner\Repository\IssueRepository::publish(
            $queue['job_id'],
            $types_to_resolve,
            self::build_publish_options( $types_to_resolve )
        );
        if ( ! $published ) {
            sitefort_log( sprintf(
                '[SiteFort] ScanQueue::complete() publish failed for scan_id=%s, scope=%s',
                $queue['job_id'],
                wp_json_encode( $types_to_resolve )
            ) );
        }

        if ( $published && in_array( 'vulnerability', $types_to_resolve, true ) ) {
            self::reconcile_published_vulnerability_findings();
        }

        if ( $published && $notify_new_vulnerabilities && class_exists( '\SiteFort\Modules\Vulnerability\Services\VulnerabilityRefreshService' ) ) {
            $current_vulnerability_issues = \SiteFort\Modules\Vulnerability\Services\VulnerabilityRefreshService::getActiveVulnerabilityIssues();
            \SiteFort\Modules\Vulnerability\Services\VulnerabilityRefreshService::dispatchNewVulnerabilityNotifications(
                $previous_vulnerability_issues,
                $current_vulnerability_issues
            );
        }
        // Persist the final per-component status so reloads do not flatten partial failures.
        \SiteFort\Modules\Scanner\Repository\IssueRepository::updateScanRunStatus( $queue['job_id'], $component_statuses, 'complete' );
        
        // Fire notification hook for scan completion
        $final_counts = class_exists( '\SiteFort\Modules\Scanner\Repository\IssueRepository' )
            ? \SiteFort\Modules\Scanner\Repository\IssueRepository::getCounts()
            : [ 'active' => 0 ];
        $issues_total = (int) ( $final_counts['active'] ?? 0 );
        \SiteFort\Includes\SettingsStore::set_field( \SiteFort\Includes\SettingsStore::COL_STATE, 'scan_issues_count', $issues_total );

        $max_severity = \SiteFort\Modules\Scanner\Repository\IssueRepository::getMaxSeverity();
        $by_type = $final_counts['by_type'] ?? [];

        if ( ! class_exists( '\SiteFort\Modules\Scanner\Service\ScanLogger' ) ) {
            require_once dirname( __DIR__ ) . '/Service/ScanLogger.php';
        }
        if ( class_exists( '\SiteFort\Modules\Scanner\Service\ScanLogger' ) ) {
            \SiteFort\Modules\Scanner\Service\ScanLogger::log_for_scan(
                (string) $queue['job_id'],
                sprintf(
                    'Scan completed. Active issues: %d%s',
                    $issues_total,
                    $max_severity ? ' • Highest severity: ' . strtoupper( (string) $max_severity ) : ''
                )
            );
            \SiteFort\Modules\Scanner\Service\ScanLogger::log_memory_usage( (string) $queue['job_id'] );
        }

        do_action( 'sitefort_scan_completed', [
            'site_url'     => home_url(),
            'issues_count' => $issues_total,
            'scan_id'      => $queue['job_id'] ?? $queue['id'],
            'severity'     => $max_severity,
            'by_type'      => $by_type,
        ] );

        if ( class_exists( '\SiteFort\Modules\Cloud\Services\StatePush' ) ) {
            \SiteFort\Modules\Cloud\Services\StatePush::ensure_terminal_scan_pushed();
        }

        self::cleanup_runtime_state( (string) $queue['id'] );

        return $queue;
    }

    /**
     * Mark scan as failed.
     */
    public static function fail( $error, array $context = [] ) {
        self::init();
        $queue = self::get();
        if ( ! $queue ) return false;

        $error = is_string( $error ) && $error !== '' ? $error : 'Scan failed due to an unexpected error.';
        $failure_context = self::normalize_failure_context( $queue, $error, $context );

        self::$repo->update( $queue['id'], [
            'status' => 'failed',
        ]);
        \SiteFort\Includes\SettingsStore::set_field( \SiteFort\Includes\SettingsStore::COL_STATE, 'last_scan_status', 'failed' );
        \SiteFort\Includes\SettingsStore::set_field( \SiteFort\Includes\SettingsStore::COL_STATE, 'last_scan_failure_context', $failure_context );

        // Stage a failure issue so it appears in the final scan report.
        if ( ! class_exists( '\SiteFort\Modules\Scanner\Repository\IssueRepository' ) ) {
            require_once dirname( __DIR__ ) . '/Repository/IssueRepository.php';
        }
        if ( class_exists( '\SiteFort\Modules\Scanner\Repository\IssueRepository' ) ) {
            \SiteFort\Modules\Scanner\Repository\IssueRepository::stage( [
                'scan_id'   => $queue['job_id'],
                'hash'      => \SiteFort\Modules\Scanner\Repository\IssueRepository::generateHash( 'system_error', 'scan:' . $queue['job_id'] ),
                'type'      => 'system_error',
                'status'    => 'failed',
                'severity'  => 'low',
                'message'   => $error,
                'file'      => '(scan)',
                'data'      => [
                    'source'            => 'scan_queue_fail',
                    'error_code'        => $failure_context['error_code'] ?? '',
                    'status_code'       => $failure_context['status_code'] ?? 0,
                    'stage'             => $failure_context['stage'] ?? '',
                    'incident_ref'      => $failure_context['incident_ref'] ?? '',
                    'request_id'        => $failure_context['request_id'] ?? '',
                    'occurred_at'       => $failure_context['occurred_at'] ?? time(),
                    'retryable'         => $failure_context['retryable'] ?? true,
                    'technical_message' => $failure_context['technical_message'] ?? '',
                    'failure_origin'    => $failure_context['failure_origin'] ?? '',
                    'failure_type'      => $failure_context['failure_type'] ?? '',
                ],
            ] );
        }

        if ( ! class_exists( '\SiteFort\Modules\Scanner\Service\ScanLogger' ) ) {
            require_once dirname( __DIR__ ) . '/Service/ScanLogger.php';
        }
        if ( class_exists( '\SiteFort\Modules\Scanner\Service\ScanLogger' ) ) {
            \SiteFort\Modules\Scanner\Service\ScanLogger::log_for_scan( (string) $queue['job_id'], 'Scan failed: ' . $error, 3, 'error' );
            \SiteFort\Modules\Scanner\Service\ScanLogger::log_memory_usage( (string) $queue['job_id'] );
        }

        // If we have ANY staged findings, replace the last published report
        // with this scan's partial results. If there are no findings, keep the previous report and
        // clean up staging artifacts.
        if ( ! class_exists( '\SiteFort\Modules\Scanner\Repository\IssueRepository' ) ) {
            require_once dirname( __DIR__ ) . '/Repository/IssueRepository.php';
        }

        $scan_id = $queue['job_id'];
        $staged_count = \SiteFort\Modules\Scanner\Repository\IssueRepository::countStaged( $scan_id );

        // Freeze component status before the queue row is discarded so stopped scans reload accurately.
        $frozen_status = self::get_component_status( $queue, false );
        // Mark any 'active' components as 'stopped' since the scan was interrupted
        foreach ( $frozen_status as $slug => $status ) {
            if ( $status === 'active' ) {
                $frozen_status[$slug] = 'stopped';
            }
        }

        if ( $staged_count > 0 ) {
            $published = \SiteFort\Modules\Scanner\Repository\IssueRepository::publish(
                $scan_id,
                [],
                self::build_publish_options( [], true )
            );
            if ( ! $published ) {
                sitefort_log( sprintf(
                    '[SiteFort] ScanQueue::fail() publish failed for scan_id=%s',
                    $scan_id
                ) );
            }
            // Persist the frozen status for reload
            \SiteFort\Modules\Scanner\Repository\IssueRepository::updateScanRunStatus( $scan_id, $frozen_status, 'stopped' );
        } else {
            \SiteFort\Modules\Scanner\Repository\IssueRepository::discardStaged( $scan_id );
            \SiteFort\Modules\Scanner\Repository\IssueRepository::discardScanRun( $scan_id );
        }
        
        // Do not emit failure alerts for controlled stop conditions.
        if ( class_exists( '\SiteFort\Modules\Scanner\Service\ScanAlertService' ) ) {
            $scan_error_code = sanitize_key( (string) ( $failure_context['error_code'] ?? 'scan_failed' ) );
            $suppressed_alert_codes = [ 'user_stopped', 'console_stopped', 'plugin_deactivated', 'credits_exhausted' ];
            $is_controlled_stop = in_array( $scan_error_code, $suppressed_alert_codes, true )
                || stripos( $error, 'stopped by user' ) !== false;

            if ( ! $is_controlled_stop ) {
                \SiteFort\Modules\Scanner\Service\ScanAlertService::send_alert( 'scan_failed', $error, $failure_context );
            }
        }

        $scan_error_code = sanitize_key( (string) ( $failure_context['error_code'] ?? 'scan_failed' ) );
        $is_stopped = in_array( $scan_error_code, [ 'user_stopped', 'console_stopped', 'plugin_deactivated', 'credits_exhausted' ], true )
            || stripos( $error, 'stopped' ) !== false;
        $scan_event = [
            'site_url'   => home_url(),
            'scan_id'    => $queue['job_id'] ?? $queue['id'],
            'error'      => $error,
            'error_code' => $scan_error_code,
            'context'    => $failure_context,
        ];
        // phpcs:ignore WordPress.NamingConventions.PrefixAllGlobals.DynamicHooknameFound -- Both branches are plugin-prefixed hooks; the dynamic ternary only selects between them.
        do_action( $is_stopped ? 'sitefort_scan_stopped' : 'sitefort_scan_failed', $scan_event );

        if ( class_exists( '\SiteFort\Modules\Cloud\Services\StatePush' ) ) {
            \SiteFort\Modules\Cloud\Services\StatePush::ensure_terminal_scan_pushed();
        }

        self::cleanup_runtime_state( (string) $queue['id'] );

        return true;
    }

    /**
     * Normalize and sanitize failure context for persistence and UI reporting.
     *
     * @param array  $queue
     * @param string $message
     * @param array  $context
     * @return array<string,mixed>
     */
    private static function normalize_failure_context( array $queue, string $message, array $context ): array {
        $occurred_at = isset( $context['occurred_at'] ) ? (int) $context['occurred_at'] : time();
        $scan_id = sanitize_text_field( (string) ( $queue['job_id'] ?? '' ) );
        $error_code = isset( $context['error_code'] ) ? sanitize_key( (string) $context['error_code'] ) : 'scan_failed';
        $stage = isset( $context['stage'] ) ? sanitize_key( (string) $context['stage'] ) : 'scanner';
        $status_code = isset( $context['status_code'] ) ? (int) $context['status_code'] : 0;
        $request_id = isset( $context['request_id'] ) ? sanitize_text_field( (string) $context['request_id'] ) : '';
        $host_id = isset( $context['host_id'] ) ? sanitize_text_field( (string) $context['host_id'] ) : '';
        $technical_message = isset( $context['technical_message'] ) ? sanitize_text_field( (string) $context['technical_message'] ) : '';
        $failure_origin = isset( $context['failure_origin'] ) ? sanitize_key( (string) $context['failure_origin'] ) : '';
        $failure_type = isset( $context['failure_type'] ) ? sanitize_key( (string) $context['failure_type'] ) : '';

        $non_retryable_codes = [ 'user_stopped', 'console_stopped', 'plugin_deactivated' ];
        $retryable = array_key_exists( 'retryable', $context )
            ? (bool) $context['retryable']
            : ! in_array( $error_code, $non_retryable_codes, true );

        $seed = $scan_id . '|' . $occurred_at . '|' . $error_code . '|' . $message;
        $incident_ref = isset( $context['incident_ref'] )
            ? sanitize_text_field( (string) $context['incident_ref'] )
            : strtoupper( substr( hash( 'sha256', $seed ), 0, 12 ) );

        return [
            'scan_id'            => $scan_id,
            'message'            => sanitize_text_field( $message ),
            'error_code'         => $error_code,
            'stage'              => $stage,
            'status_code'        => $status_code,
            'request_id'         => $request_id,
            'host_id'            => $host_id,
            'retryable'          => $retryable,
            'occurred_at'        => $occurred_at,
            'incident_ref'       => $incident_ref,
            'cloud_error_count'  => isset( $context['cloud_error_count'] ) ? (int) $context['cloud_error_count'] : (int) ( $queue['cloud_error_count'] ?? 0 ),
            'technical_message'  => $technical_message,
            'failure_origin'     => $failure_origin,
            'failure_type'       => $failure_type,
        ];
    }

    // --- Delegated Methods ---

    /**
     * Heartbeat: refresh the durable queue heartbeat.
     * Best-effort and safe to call frequently.
     */
    public static function heartbeat() {
        self::init();
        self::update( [ 'last_ping' => time() ] );
    }

    /**
     * Delete durable task rows for a scan.
     *
     * Use this only from out-of-band terminal paths. The task-runner path
     * performs its own post-commit cleanup so it does not delete the currently
     * leased task row before TaskRunner finishes bookkeeping.
     *
     * @param string $scan_id
     * @return void
     */
    public static function cleanup_task_queue( string $scan_id = '' ): void {
        self::init();

        if ( '' === $scan_id ) {
            $queue = self::get();
            $scan_id = is_array( $queue ) ? (string) ( $queue['id'] ?? '' ) : '';
        }

        if ( '' === $scan_id ) {
            return;
        }

        if ( ! class_exists( TaskQueueRepository::class ) ) {
            require_once dirname( __DIR__ ) . '/Repository/TaskQueueRepository.php';
        }

        ( new TaskQueueRepository() )->delete_by_scan_id( $scan_id );
    }

    public static function cleanup_runtime_state( string $scan_id ): void {
        $scan_id = sanitize_text_field( $scan_id );
        if ( '' === $scan_id ) {
            return;
        }

        if ( ! class_exists( TaskScheduler::class ) ) {
            require_once __DIR__ . '/TaskScheduler.php';
        }
        if ( class_exists( TaskScheduler::class ) ) {
            TaskScheduler::clear_wakeups( $scan_id );
        }
        if ( ! class_exists( WorkerRuntime::class ) ) {
            require_once __DIR__ . '/WorkerRuntime.php';
        }
        if ( class_exists( WorkerRuntime::class ) ) {
            WorkerRuntime::clear_scan_state( $scan_id );
        }
        if ( ! class_exists( WorkerLiveness::class ) ) {
            require_once __DIR__ . '/WorkerLiveness.php';
        }
        if ( class_exists( WorkerLiveness::class ) ) {
            WorkerLiveness::clear_scan_state( $scan_id );
        }

        foreach ( [
            'sitefort_scan_preflight_',
            'sitefort_rr_phase_',
            'sitefort_last_poll_check_',
            'sitefort_scan_start_',
            'sitefort_cloud_job_',
            'sitefort_last_completed_reconcile_',
            'sitefort_file_index_complete_',
            'sitefort_discovery_complete_',
            'sitefort_discovery_stack_',
            'sitefort_scan_sig_version_',
            'sitefort_unindexed_wpv_',
            'sitefort_credit_exhausted_',
            'sitefort_deep_analysis_credit_exhausted_',
            'sitefort_deep_analysis_credit_summary_logged_',
        ] as $prefix ) {
            delete_transient( $prefix . $scan_id );
        }

        // Per-scan resume cursors.
        delete_option( 'sitefort_user_scan_cursor_' . sanitize_key( $scan_id ) );
        delete_transient( 'sitefort_sensitive_scan_cursor_' . sanitize_key( $scan_id ) );

        // Scan is terminal; the minute resume ticker has nothing left to do.
        if ( ! class_exists( ScanCron::class ) ) {
            require_once __DIR__ . '/ScanCron.php';
        }
        if ( class_exists( ScanCron::class ) ) {
            ScanCron::unschedule();
        }

        if ( ! class_exists( '\SiteFort\Modules\Scanner\Service\ResourcePressure' ) ) {
            require_once dirname( __DIR__ ) . '/Service/ResourcePressure.php';
        }
        if ( class_exists( '\SiteFort\Modules\Scanner\Service\ResourcePressure' ) ) {
            \SiteFort\Modules\Scanner\Service\ResourcePressure::clear_state( $scan_id );
        }

        if ( ! class_exists( '\SiteFort\Modules\Scanner\Service\AIMDController' ) ) {
            require_once dirname( __DIR__ ) . '/Service/AIMDController.php';
        }
        if ( class_exists( '\SiteFort\Modules\Scanner\Service\AIMDController' ) ) {
            \SiteFort\Modules\Scanner\Service\AIMDController::clear_state( $scan_id );
        }

        if ( ! class_exists( '\SiteFort\Modules\Scanner\Service\ScanLogger' ) ) {
            require_once dirname( __DIR__ ) . '/Service/ScanLogger.php';
        }
        if ( class_exists( '\SiteFort\Modules\Scanner\Service\ScanLogger' ) ) {
            \SiteFort\Modules\Scanner\Service\ScanLogger::clear_throttles_for_scan( $scan_id );
        }
    }

    /**
     * Persist component status transitions for UI consistency.
     *
     * @param string $slug Component slug
     * @param string $status pending|active|complete|failed|stopped
     * @param int $active_for Seconds to keep "active" visible after transition
     * @return bool|int
     */
    public static function set_component_status( $slug, $status, $active_for = 0 ) {
        self::init();
        if ( empty( $slug ) ) return false;

        $queue = self::get();
        if ( ! $queue ) return false;

        $current = $queue['component_status'] ?? [];
        $normalized = self::normalize_component_status_map( $current );
        $now = time();

        $active_until = 0;
        if ( isset( $normalized[ $slug ]['active_until'] ) ) {
            $active_until = (int) $normalized[ $slug ]['active_until'];
        }

        if ( $status === 'active' && $active_for > 0 ) {
            $active_until = $now + (int) $active_for;
        }

        // Clear the active grace window when transitioning to a terminal state.
        // Preserving it would cause the frontend to show stale "scanning" states
        // when multiple checks complete back-to-back within the grace period.
        if ( in_array( $status, [ 'complete', 'failed', 'stopped' ], true ) ) {
            $active_until = 0;
        }

        $normalized[ $slug ] = [
            'status'     => $status,
            'updated_at' => $now,
        ];
        if ( $active_until > 0 ) {
            $normalized[ $slug ]['active_until'] = $active_until;
        }

        return self::update( [ 'component_status' => $normalized ] );
    }

    public static function get_component_status( $queue, $allow_active_grace = true ) {
        self::init();
        $base = self::$statusService->get_component_status( $queue );
        $stored = $queue['component_status'] ?? [];
        $normalized = self::normalize_component_status_map( $stored );

        if ( empty( $normalized ) ) {
            return $base;
        }

        $now = time();
        foreach ( $normalized as $slug => $entry ) {
            $status = $entry['status'] ?? null;
            if ( ! $status ) continue;

            // Computed statuses are authoritative; do not overwrite them with stale DB values.
            if ( in_array( $slug, ['file_scan', 'file_changes', 'cloud_ai'], true ) ) {
                continue;
            }

            $active_until = (int) ( $entry['active_until'] ?? 0 );
            if ( $allow_active_grace && $active_until > 0 && $now <= $active_until && ! in_array( $status, [ 'failed', 'stopped' ], true ) ) {
                $status = 'active';
            }

            $base[ $slug ] = $status;
        }

        return $base;
    }

    /**
     * @param array<string,mixed>|null $queue Already-fetched active queue to avoid a redundant lookup.
     */
    public static function get_progress( $queue = null ) {
        self::init();
        if ( null === $queue ) {
            $queue = self::get();
        }
        return self::$statusService->get_progress( $queue );
    }

    public static function is_stuck( $threshold = 45 ) {
        self::init();
        $queue = self::get();
        return self::$statusService->is_stuck( $queue, $threshold );
    }
    
    public static function is_active() {
        $queue = self::get();
        return $queue && in_array( $queue['status'], [ 'pending', 'running' ], true );
    }
    
    /**
     * Get the pinned malware signature version for a scan.
     *
     * The scan_queue record is the source of truth; a transient is used as cache.
     *
     * @param string $scan_id Scan UUID.
     * @return string|null Signature version or null if not yet pinned.
     */
    public static function get_pinned_signature_version( string $scan_id ): ?string {
        // Pinned version never changes mid-request.
        static $memo = [];
        if ( array_key_exists( $scan_id, $memo ) ) {
            return $memo[ $scan_id ];
        }

        global $wpdb;
        $table = self::table_identifier( $wpdb->prefix . 'sitefort_scan_queue' );

        // phpcs:disable WordPress.DB.DirectDatabaseQuery.DirectQuery,WordPress.DB.DirectDatabaseQuery.NoCaching,PluginCheck.Security.DirectDB.UnescapedDBParameter,WordPress.DB.PreparedSQL.InterpolatedNotPrepared
        $val = (string) $wpdb->get_var(
            $wpdb->prepare(
                "SELECT malware_signature_version FROM {$table} WHERE job_id = %s",
                $scan_id
            )
        );
        // phpcs:enable WordPress.DB.DirectDatabaseQuery.DirectQuery,WordPress.DB.DirectDatabaseQuery.NoCaching,PluginCheck.Security.DirectDB.UnescapedDBParameter,WordPress.DB.PreparedSQL.InterpolatedNotPrepared

        $val = trim( $val );
        if ( $val !== '' ) {
            set_transient( 'sitefort_scan_sig_version_' . $scan_id, $val, DAY_IN_SECONDS );
            $memo[ $scan_id ] = $val;
            return $val;
        }

        $cached = get_transient( 'sitefort_scan_sig_version_' . $scan_id );
        if ( is_string( $cached ) && $cached !== '' ) {
            $memo[ $scan_id ] = $cached;
            return $cached;
        }

        // Not pinned yet; don't memoize so a later pin is picked up.
        return null;
    }

    // --- Mappers ---

    private static function map_row( $row ) {
        $component_status = [];
        if ( isset( $row['component_status'] ) ) {
            if ( is_array( $row['component_status'] ) ) {
                $component_status = $row['component_status'];
            } elseif ( is_string( $row['component_status'] ) && $row['component_status'] !== '' ) {
                $decoded = json_decode( $row['component_status'], true );
                if ( is_array( $decoded ) ) {
                    $component_status = $decoded;
                }
            }
        }

        return [
            'id'          => $row['job_id'],
            'job_id'      => $row['job_id'],
            'db_id'       => $row['id'],
            'status'      => $row['status'],
            'source'      => $row['source'],
            'type'        => $row['scan_type'],
            'scan_type'   => $row['scan_type'],
            'total_items' => (int)$row['total_count'],
            'processed'   => (int)$row['processed_count'],
            'cloud_stats' => !empty($row['cloud_stats']) ? json_decode( $row['cloud_stats'], true ) : [ 'files' => [ 'pending' => 0, 'complete' => 0, 'failed' => 0 ] ],
            'created_at'  => (int)$row['created_at'],
            'last_ping'   => (int)($row['last_ping'] ?? $row['updated_at']), // Use dedicated column, fallback to updated_at
            'next_run_at' => (int)($row['next_run_at'] ?? 0),
            'last_dispatch_at' => (int)($row['last_dispatch_at'] ?? 0),
            'cloud_error_count' => (int)($row['cloud_error_count'] ?? 0),
            'issues'      => [],
            'component_status' => $component_status,
        ];
    }

    private static function normalize_component_status_map( $raw ) {
        if ( is_string( $raw ) ) {
            $raw = json_decode( $raw, true );
        }
        if ( ! is_array( $raw ) ) {
            return [];
        }

        $normalized = [];
        foreach ( $raw as $slug => $entry ) {
            if ( is_array( $entry ) ) {
                $normalized[ $slug ] = [
                    'status'       => $entry['status'] ?? null,
                    'active_until' => isset( $entry['active_until'] ) ? (int) $entry['active_until'] : 0,
                    'updated_at'   => isset( $entry['updated_at'] ) ? (int) $entry['updated_at'] : 0,
                ];
            } elseif ( is_string( $entry ) ) {
                $normalized[ $slug ] = [ 'status' => $entry ];
            }
        }

        return $normalized;
    }
}
